--- emacs23-23.1+1.orig/debian/copyright +++ emacs23-23.1+1/debian/copyright @@ -0,0 +1,102 @@ +-*-text-*- + +This package was debianized by Rob Browning on +Tue, 16 Dec 1997 00:05:45 -0600. + +The original source archive is emacs-23.1.tar.gz, and it +can be found here for stable releases: + + ftp://ftp.gnu.org:/gnu/emacs/ + +and here for alpha pre-releases: + + ftp://alpha.gnu.org:/gnu/emacs/pretest/ + +Please see /usr/share/doc/emacs23-common/README.Debian.gz for a +description of the Debian specific differences from the upstream +version. + +Copyright: + + Emacs itself is licensed under the terms of the GNU General Public + License (GPL), Version 3. See the file + /usr/share/common-licenses/GPL-3 for more information. + + doc/man/b2m.1, doc/man/ebrowse.1, doc/man/grep-changelog.1, and + doc/man/rcs-checkin.1 are licensed as follows: + + Copyright (C) 2008, 2009 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this + document provided the copyright notice and this permission notice are + preserved on all copies. + + Permission is granted to copy and distribute modified versions of + this document under the conditions for verbatim copying, provided that + the entire resulting derived work is distributed under the terms of + a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this + document into another language, under the above conditions for + modified versions, except that this permission notice may be stated + in a translation approved by the Free Software Foundation. + + doc/man/emacs.1 is licensed as follows: + + Copyright (C) 1995, 1999, 2000, 2001, 2002, 2003, 2004, 2005, + 2006, 2007, 2008, 2009 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of + this document provided the copyright notice and this permission + notice are preserved on all copies. + + Permission is granted to copy and distribute modified versions of + this document under the conditions for verbatim copying, provided + that the entire resulting derived work is distributed under the + terms of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this + document into another language, under the above conditions for + modified versions, except that this permission notice may be + stated in a translation approved by the Free Software Foundation. + + doc/man/etags.1 is licensed as follows: + + Copyright (C) 1992, 1999, 2001, 2002, 2003, 2004, 2005, 2006, + 2007, 2008, 2009 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this + document provided the copyright notice and this permission notice are + preserved on all copies. + + Permission is granted to copy and distribute modified versions of + this document under the conditions for verbatim copying, provided that + the entire resulting derived work is distributed under the terms of + a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this + document into another language, under the above conditions for + modified versions, except that this permission notice may be stated + in a translation approved by the Free Software Foundation. + + man/faq.texi is licensed as follows: + + Copyright (C) 1994,1995,1996,1997,1998,1999,2000 Reuven M. Lerner + Copyright (C) 1992,1993 Steven Byrnes + Copyright (C) 1990,1991,1992 Joseph Brian Wells + + This list of frequently asked questions about GNU Emacs with + answers ("FAQ") may be translated into other languages, + transformed into other formats (e.g. Texinfo, Info, WWW, WAIS), + and updated with new information. + + The same conditions apply to any derivative of the FAQ as apply to + the FAQ itself. Every copy of the FAQ must include this notice or + an approved translation, information on who is currently + maintaining the FAQ and how to contact them (including their + e-mail address), and information on where the latest version of + the FAQ is archived (including FTP information). + + The FAQ may be copied and redistributed under these conditions, + except that the FAQ may not be embedded in a larger literary work + unless that work itself allows free copying and redistribution. --- emacs23-23.1+1.orig/debian/rules +++ emacs23-23.1+1/debian/rules @@ -0,0 +1,913 @@ +#!/usr/bin/make -f +# -*- makefile -*- + +# This file is licensed under the terms of the Gnu Public License. +# With the one additional provision that Ian Jackson's name may not be +# removed from the file. + +# Copyright 1994,1995 Ian Jackson +# Copyright 2004-2005 Jérôme Marant +# Copyright 1998-2009 Rob Browning + +# Originally copied from the GNU Hello Debian rules file (1.3). +# Modified for emacs by Mark Eichin . +# Debhelper support added via one of Joey Hess' example files. +# See the debian/changelog for further historical information. + +# TODO: +# +# Figure out what happened to fns-*.elc +# Should we set defaults for things like xsupport at the top here? +# Deal with build_binary_pkg and continue integration. + +# Uncomment this to turn on verbose mode. +#export DH_VERBOSE=1 + +SHELL := /bin/bash + +quilt := QUILT_PATCHES=debian/patches quilt + +deb_trash := + +pf := set -o pipefail + +# For now we assume that emacs' versioning scheme is always +# MAJOR.MINORtinyrev where MAJOR and MINOR are integers and tinyrev is +# an optional lowercase letter (or letters). We also assume that +# upstream uses a numbering scheme that sorts in a "Debian friendly" +# way. So far that's always been true. If it becomes false, some of +# the values below will have to be set manually. + +# At the moment, we try to make it so that a "debian/rules clean" will +# get you back to the same state you were in before "debian/rules +# build". With the original upstream source that's somewhat tricky +# because they ship the .elc files, but we need to re-build them when +# we patch the corresponding .el files. This is further complicated +# by the fact that any of these .el files may have macros, and if +# those are changed, then any other .el files that use those macros +# must also be recompiled. Over the years, we've tried various ways +# to handle this problem, originally by trying to keep track of which +# files need to be recompiled and only recompiling those, then later +# by just re-building all the .elc files with "make bootstrap". In +# either case, if you don't want to have diff bloat, you have to do +# something to keep track of the original .elc files so you can +# restore them during make clean. + +# All of this was a lot of work, and was using quite a bit of +# unnecessary storage both in the .orig.tar.gz and during the package +# build. So in order to avoid this, and to dramatically simplify +# things, we now just remove the .elc files from the upstream +# distribution whenever we create the debian .orig.tar.gz file for a +# given upstream release. Since were always clobbering all of the +# .elc files during the package build anyway, this shouldn't be any +# great loss, and it also means that "debian/rules clean" now needs to +# be little more than a "make distclean" followed by a purge of all +# the remaining .elc files. + +# NOTE -- emacs doesn't respect .elc files in VPATH build. They're +# modified in srcdir, not builddir. We don't worry about this because +# it shouldn't affect our builds ATM, but if we ever have more than +# one emacs configuration which could produce differing .elc files, +# we'll need to be careful. We'll probably have to build completely +# separate packages from completely separate source trees. + +# In order to keep the autofiles up to date, but avoid any alterations +# outside of ./debian, we keep the changes made by running a new +# autoconf, etc. in patches/autofiles.diff. This patch can be +# automatically regenerated by running "debian/rules autofiles-sync", +# and this patch should always be maintained as the last one in the +# patch series. + +# Note that we use quilt to handle the debian patches. One of the +# biggest differences between quilt and say dpatch is that you have to +# explicitly "quilt add" a file to a patch before you edit it. See +# "man quilt" for details.. + +# If the source tree ever ends up in an untenable "can't go forward, +# can't go back" state with respect to patching, you can always start +# over by just moving the current debian directory to a newly unpacked +# orig.tar.gz tree. Note that f you were in the process of editing a +# patch, you will lose those edits, but shouldn't lose anything else. +# This process just reverts all of the upstream files and abandons the +# volatile "what's been done to the current tree" state that quilt +# maintains in ./.pc. All of the actual patches are stored in +# debian/patches and should be unharmed. + +###################################################################### +# Important top-level targets: +# +# check-vars - displays how the version number has been parsed. +# buildpackage - build binary packages via dpkg-buildpackage w/suitable args +# prepare-release - prepare and check debs for upload. +# autofiles-sync - force a new autofiles.diff to be generated. +# +###################################################################### + +# The name of the Debian source package +src_name := $(shell $(pf); dpkg-parsechangelog | egrep '^Source:') +src_name := $(shell $(pf); echo $(src_name) | perl -pe 's/Source:\s+//o') + +# The version from the changelog (i.e. 20.5-1) +debian_ver := $(shell $(pf); dpkg-parsechangelog | egrep '^Version:') +debian_ver := $(shell $(pf); echo $(debian_ver) | perl -pe 's/Version:\s+//o') +# The Debian revision (i.e. the 1 from 20.5-1) +# Always everything after the last '-' +debian_rev := $(shell $(pf); echo $(debian_ver) | perl -pe 's/.*-//o') + +# The official upstream version defined by emacs-version in lisp/version.el. +# The extraction method matches the code in the upstream configure.in. +nominal_ver := \ + $(shell $(pf); grep 'defconst[ ]*emacs-version' lisp/version.el \ + | sed -e 's/^[^"]*"\([^"]*\)".*$$/\1/') + +# This must be the version that's actually used at runtime for things +# like load-path. It may not be the same as the upstream version +# (i.e. when you have upstream 20.5a, the functional version may still +# be 20.5), so sometimes we may have to do this by hand. +runtime_ver := $(shell $(pf); echo $(nominal_ver) | perl -pe 's/[a-z]+$$//o') + +major_ver := $(shell $(pf); echo $(runtime_ver) | perl -pe 's/\..*$$//o') +minor_ver := $(shell $(pf); echo $(runtime_ver) | perl -pe 's/^[^.]*\.//o') + +# version for the debian source, i.e. if the upstream is 21.3, this +# might be 21.3, or it might be 21.3+1 if we've had to have more than +# one re-release of the upstream source. Rare, but it happens... +# Always everything before the last '-' +debsrc_ver := $(shell $(pf); echo $(debian_ver) | perl -pe 's/-[^-]+$$//o') + +# upstream version - the actual upstream version, i.e. 21.4a, minus any +foo +upstream_ver := $(shell $(pf); echo $(debsrc_ver) | perl -pe 's/\+[^+]+$$//o') + +deb_orig_tgz := $(src_name)_$(debsrc_ver).orig.tar.gz +# name of the orig_tgz unpack directory +deb_orig_tgz_dir := emacs-$(runtime_ver) + +###################################################################### +# Customizable variables + +# The flavor (i.e. emacs21) currently matches the source package name. +flavor := $(src_name) + +bin_priority := 26 + +# This might also be something like 2006-09-09 for snapshots. +menu_ver := $(major_ver) + +info_subdir := emacs-$(major_ver) + +###################################################################### + +# Should these be exported like this (as autotools-dev recommends for +# the two vars below) or not? +export DEB_HOST_ARCH ?= $(shell dpkg-architecture -qDEB_HOST_ARCH) +export DEB_HOST_GNU_CPU ?= $(shell dpkg-architecture -qDEB_HOST_GNU_CPU) + +# As recommended by /usr/share/doc/autotools-dev/README.Debian.gz. +# Handle cross-compiling and don't make ./configure guess. +export DEB_HOST_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_HOST_GNU_TYPE) +export DEB_BUILD_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_BUILD_GNU_TYPE) +confflags += --build=$(DEB_BUILD_GNU_TYPE) --host=$(DEB_HOST_GNU_TYPE) + +LDFLAGS := -g +CFLAGS := -DDEBIAN -g + +ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS))) + CFLAGS += -O0 +else # not noopt + ifeq (m68k,$(DEB_HOST_ARCH)) + # fix problem with newer versions of gcc on m68k + # -O2 causes a build failure (broken byte compiler) + CFLAGS += -O1 + else # neq (m68k,$(DEB_HOST_ARCH)) + CFLAGS += -O2 + endif # neq (m68k,$(DEB_HOST_ARCH)) +endif # not noopt + +target := $(DEB_HOST_GNU_TYPE) +movemail_bin := usr/lib/emacs/$(runtime_ver)/$(target)/movemail + +# These files may be modified in the *source* tree during the build. +# Wonder if we could patch emacs to copy/use these files to/from the +# build tree... (See Makefile.in's AUTOGENEL definition.) +protected_files := \ + config.guess \ + config.sub \ + lisp/cus-load.el \ + lisp/finder-inf.el \ + lisp/loaddefs.el \ + lisp/subdirs.el + +# Info files that are going to show up in the main dir. +main_dir_info_files := $(shell grep '^$$(infodir)/' doc/misc/Makefile.in | \ + sed -e "s%\$$(infodir)/\([^:]*\).*$$%\1%" | sort) emacs eintr elisp + +# Files that the build stage depends on (may also be listed in other vars). +persistent_autogen_build_files := debian/control debian/copyright +nonpersistent_autogen_build_files := + +# These files must always exist, i.e. can't ever be cleaned. +persistent_autogen_install_files := + +nonpersistent_autogen_install_files := \ + debian/$(flavor)-bin-common.lintian-overrides \ + debian/$(flavor)-bin-common.postinst \ + debian/$(flavor)-bin-common.prerm \ + debian/$(flavor)-common.README.Debian \ + debian/$(flavor)-common.docs \ + debian/$(flavor)-common.lintian-overrides \ + debian/$(flavor)-common.postinst \ + debian/$(flavor)-common.prerm \ + debian/$(flavor)-nox.README.Debian \ + debian/$(flavor)-nox.lintian-overrides \ + debian/$(flavor)-nox.menu \ + debian/$(flavor)-nox.postinst \ + debian/$(flavor)-nox.prerm \ + debian/$(flavor)-lucid.README.Debian \ + debian/$(flavor)-lucid.desktop \ + debian/$(flavor)-lucid.lintian-overrides \ + debian/$(flavor)-lucid.menu \ + debian/$(flavor)-lucid.postinst \ + debian/$(flavor)-lucid.prerm \ + debian/$(flavor).README.Debian \ + debian/$(flavor).desktop \ + debian/$(flavor).menu \ + debian/$(flavor).lintian-overrides \ + debian/$(flavor).postinst \ + debian/$(flavor).prerm + +autogen_build_files := \ + $(nonpersistent_autogen_build_files) $(persistent_autogen_build_files) + +autogen_install_files := \ + $(nonpersistent_autogen_install_files) $(persistent_autogen_install_files) + +persistent_autogen_files := \ + $(persistent_autogen_build_files) $(persistent_autogen_install_files) + +nonpersistent_autogen_files := \ + $(nonpersistent_autogen_build_files) $(nonpersistent_autogen_install_files) + + +# Build directories +pkgdir_common := $(CURDIR)/debian/$(flavor)-common +pkgdir_bin_common := $(CURDIR)/debian/$(flavor)-bin-common +pkgdir_x := $(CURDIR)/debian/$(flavor) +pkgdir_nox := $(CURDIR)/debian/$(flavor)-nox +pkgdir_lucid := $(CURDIR)/debian/$(flavor)-lucid +pkgdir_el := $(CURDIR)/debian/$(flavor)-el + +install_dir_x := $(CURDIR)/debian/install-x +install_dir_nox := $(CURDIR)/debian/install-nox +install_dir_lucid := $(CURDIR)/debian/install-lucid + +local_lpath := /etc/$(flavor):/etc/emacs +local_lpath := $(local_lpath):/usr/local/share/emacs/$(runtime_ver)/site-lisp +local_lpath := $(local_lpath):/usr/local/share/emacs/site-lisp +local_lpath := $(local_lpath):/usr/share/emacs/$(runtime_ver)/site-lisp +local_lpath := $(local_lpath):/usr/share/emacs/site-lisp + +# This shouldn't be needed as of 20.3 +local_lpath := $(local_lpath):/usr/share/emacs/$(runtime_ver)/leim + +# Installation local_lpath +local_lpath_install := $(pkgdir_common)/$(subst :,:$(pkgdir_common)/,$(local_lpath)) + +define checkroot + test root = "`whoami`" +endef + +define checkdir + @if ! test -s debian/patches/autofiles.diff; \ + then \ + echo; \ + echo "The Debian autofiles patch is not available."; \ + echo "Please run this command:"; \ + echo " debian/rules autofiles-sync"; \ + echo; \ + false; \ + fi + dpkg-parsechangelog > /dev/null + dh_testdir debian/emacsVER.postinst + @if ! test -f src/emacs.c; \ + then \ + echo; \ + echo -n "The upstream source does not appear to be available."; \ + echo " Please put the contents"; \ + echo -n "of $(deb_orig_tgz) into the"; \ + echo " current directory."; \ + echo; \ + false; \ + fi +endef + +define build_cmd + $(MAKE) -C $(1) CFLAGS="$(CFLAGS)" LDFLAGS="$(LDFLAGS)" + # If we don't use bootstrap, we need to explicitly build info. + $(MAKE) -C $(1) CFLAGS="$(CFLAGS)" LDFLAGS="$(LDFLAGS)" info +endef + +# If we ever need to do the stripping outside of dh_strip, just add an +# INSTALL_STRIP="-s" to the make vars below. + +define emacs_inst + $(MAKE) -C debian/$(1) install DESTDIR=$(2) \ + infodir=/usr/share/info/emacs-$(major_ver) \ + localstatedir=/var +endef + + + +define patch + $(quilt) push -a +endef + +define unpatch + test -z "$$($(quilt) applied)" || $(quilt) pop -a + rm -f debian/stamp/patch + rm -rf .pc +endef + +define cleanup_all + # distclean goes first so we clean using patched code + rm -f debian/stamp/setup + rm -f debian/stamp/configure + rm -f debian/stamp/build + -$(MAKE) distclean + cd info && rm -f $$(ls | grep -v COPYING | grep -v '^dir$$') + dh_clean + $(unpatch) + # now clean up bits in the source tree that the above didn't handle + find -name "*.elc" | xargs --no-run-if-empty rm + if [ -e debian/protected-files.tgz ]; then \ + tar xzpf debian/protected-files.tgz; \ + fi + rm -f debian/protected-files.tgz + # now clean up everything else (mostly ./debian related stuff) + find -name '*~' | xargs --no-run-if-empty rm -f + rm -f debian/substvars + rm -f $(nonpersistent_autogen_files) + rm -rf \ + debian/build-x \ + debian/install-x \ + debian/build-nox \ + debian/install-nox \ + debian/build-lucid \ + debian/install-lucid \ + debian/files* + rm -rf debian/*.tmp + rm -rf $(deb_trash) + rm -rf .pc + chmod 644 debian/mangle-info + test ! -e debian/stamp || rmdir debian/stamp +endef + +define update_debian_autofiles_quilt + $(cleanup_all) + # Make sure autofiles.diff exists, otherwise patching will fail. + if ! test -e debian/patches/autofiles.diff; \ + then \ + touch debian/patches/autofiles.diff; \ + fi; + $(quilt) push $$($(quilt) series | tail -n 2 | head -n 1) + test "$$($(quilt) next)" = autofiles.diff + $(quilt) pop + mkdir -p debian/tmp-autofiles/old + $(pf); tar cpSf - --exclude ./debian --exclude ./.pc . \ + | tar -C debian/tmp-autofiles/old -xpSf - + cp -a debian/tmp-autofiles/old debian/tmp-autofiles/new + cd debian/tmp-autofiles/new && aclocal + cd debian/tmp-autofiles/new && autoconf + cd debian/tmp-autofiles/new && autoheader + cd debian/tmp-autofiles/new && rm -rf autom4te.cache + cd debian/tmp-autofiles && diff -ruN old new > new.diff; \ + test $$? -eq 1 + $(quilt) import -f -P autofiles.diff debian/tmp-autofiles/new.diff + $(quilt) header -r autofiles.diff < debian/autofiles-diff-header + $(patch) + $(quilt) refresh --no-timestamps autofiles.diff + $(cleanup_all) +endef +deb_trash += debian/tmp-autofiles + +# If we ever need it, we can create a copy that doesn't assume ./debian/ +define deb_sub + perl -p \ + -e "s|\@PKG_NAME\@|$(pkg_name)|go;" \ + -e "s|\@MAJOR_VERSION\@|$(major_ver)|go;" \ + -e "s|\@MINOR_VERSION\@|$(minor_ver)|go;" \ + -e "s|\@FULL_VERSION\@|$(runtime_ver)|go;" \ + -e "s|\@PACKAGE_VERSION\@|$(debian_ver)|go;" \ + -e "s|\@DEBIAN_REV\@|$(deb_rev)|go;" \ + -e "s|\@NOMINAL_VERSION\@|$(nominal_ver)|go;" \ + -e "s|\@UPSTREAM_VERSION\@|$(upstream_ver)|go;" \ + -e "s|\@DEBSRC_VERSION\@|$(debsrc_ver)|go;" \ + -e "s|\@DEB_FLAVOR\@|$(flavor)|go;" \ + -e "s|\@MENU_VERSION\@|$(menu_ver)|go;" \ + -e "s|\@INFO_FILES\@|$(main_dir_info_files)|go;" \ + -e "s|\@INFO_SUBDIR\@|$(info_subdir)|go;" \ + -e "s|\@X_SUPPORT\@|$(xsupport)|go;" \ + -e "s|\@BIN_PRIORITY\@|$(bin_priority)|go;" \ + -e "s|\@MOVEMAIL_BIN\@|$(movemail_bin)|go;" \ + < $(1) > $(2) +endef + +check-vars: + @echo "upstream_ver: $(upstream_ver)" + @echo "debian_ver: $(debian_ver)" + @echo "debsrc_ver: $(debsrc_ver)" + @echo "debian_rev: $(debian_rev)" + @echo "nominal_ver: $(nominal_ver)" + @echo "runtime_ver: $(runtime_ver)" + @echo "major_ver: $(major_ver)" + @echo "minor_ver: $(minor_ver)" + @echo "movemail_bin: $(movemail_bin)" +.PHONY: check-vars + +.PHONY: check-diff +check-diff: clean + $(checkdir) + test -r ../$(deb_orig_tgz) + rm -rf debian/tmp-diff && mkdir debian/tmp-diff + cd debian/tmp-diff && tar xzpSf ../../../$(deb_orig_tgz) + cd debian/tmp-diff && mv $(deb_orig_tgz_dir) orig + + mkdir debian/tmp-diff/new + $(pf); tar cpf - --exclude './debian' --exclude './.pc' . \ + | (cd debian/tmp-diff/new && tar xpf -) + + @echo + @echo "########################################" + @echo "### Diffs outside ./debian" + @cd debian/tmp-diff && diff -ruN orig new + @echo "########################################" + @echo "### Empty file list differences" + @diff -u \ + <(cd debian/tmp-diff/orig && find -size 0) \ + <(cd debian/tmp-diff/new && find -size 0) \ + > debian/tmp-diff/empty-files.diff || test $$? -eq 1 + @cat debian/tmp-diff/empty-files.diff + @test ! -s debian/tmp-diff/empty-files.diff || false + @echo "########################################" + @rm -rf debian/tmp-diff + +deb_trash += debian/tmp-diff + + +buildpackage: + $(checkdir) + dpkg-buildpackage -D -us -uc -rfakeroot -i'\.git|\.pc' +.PHONY: buildpackage + +prepare-release: + $(checkdir) + # don't want to be root -- using fakeroot below. + # also, stacking fakeroots seems to cause trouble generating diff. + @test "`whoami`" != root || \ + (echo "please run prepare-release as a normal user (not root)"; \ + false) + # check for any uncommitted changes + @if test $$(cd debian && git-diff-files | wc -c) -ne 0; \ + then \ + read -p "Uncommitted changes. Continue? [y/n] "; \ + if test "$${REPLY}" != y; \ + then \ + false; \ + fi; \ + fi + # TODO: make sure we actually installed the binary. + # TODO: run tests (use a check target?) + @read -p "Regenerate autofiles.diff? [y/n] "; \ + if test "$${REPLY}" == y; \ + then \ + $(MAKE) -f debian/rules autofiles-sync; \ + else \ + true; \ + fi + $(MAKE) -f debian/rules clean + $(MAKE) -f debian/rules buildpackage + test -f ../$(src_name)_$(debian_ver).diff.gz + @if [ $$(zgrep '^---' \ + ../$(src_name)_$(debian_ver).diff.gz \ + | grep -v /debian/ | wc -c) -ne 0 ]; \ + then \ + echo "Diffs outside debian/ found, please fix and retry."; \ + echo "This probably means either something wasn't cleaned"; \ + echo "properly, or you need to do some work in debian/patches."; \ + false; \ + else \ + echo "Everything looks OK. Ready for release."; \ + echo "Don't forget to run debsign if needed."; \ + fi +.PHONY: prepare-release + + +# we don't sync this automatically on clean because it's expensive and +# should only be done by a maintainer with time to deal with any mess +# it might create. +autofiles-sync: + $(update_debian_autofiles_quilt) +.PHONY: autofiles-sync + +debian-sync: $(persistent_autogen_files) + +.PHONY: force-debian-sync debian-sync + +debian/$(flavor).%: xsupport := "x" +debian/$(flavor).%: pkg_name := $(flavor) + +debian/$(flavor)-nox.%: xsupport := "nox" +debian/$(flavor)-nox.%: pkg_name := $(flavor)-nox + +debian/$(flavor)-lucid.%: xsupport := "lucid" +debian/$(flavor)-lucid.%: pkg_name := $(flavor)-lucid + +debian/$(flavor)-common.%: pkg_name := $(flavor)-common +debian/$(flavor)-bin-common.%: pkg_name := $(flavor)-bin-common + +debian/%: debian/%.in debian/changelog + $(call deb_sub,$<,$@) + +debian/$(flavor)-bin-common.%: debian/emacsVER-bin-common.% debian/changelog + $(call deb_sub,$<,$@) + +debian/$(flavor)-common.%: debian/emacsVER-common.% debian/changelog + $(call deb_sub,$<,$@) + +debian/$(flavor)-el.%: debian/emacsVER-el.% debian/changelog + $(call deb_sub,$<,$@) + +debian/$(flavor).%: debian/emacsVER.% debian/changelog + $(call deb_sub,$<,$@) + +debian/$(flavor)-nox.%: debian/emacsVER.% debian/changelog + $(call deb_sub,$<,$@) + +debian/$(flavor)-lucid.%: debian/emacsVER.% debian/changelog + $(call deb_sub,$<,$@) + +debian/$(flavor)-common.README.Debian: \ + debian/emacsVER-common.README debian/patches/*.diff debian/patches/series + cd debian && \ + csplit -s -f emacsVER-common.README. \ + emacsVER-common.README '/@@PATCH_LIST_HERE@@/' + cp debian/emacsVER-common.README.00 debian/emacsVER-common.README.tmp + for p in $$($(quilt) series); do $(quilt) header $$p; done \ + >> debian/emacsVER-common.README.tmp + tail -n +2 \ + < debian/emacsVER-common.README.01 \ + >> debian/emacsVER-common.README.tmp + mv debian/emacsVER-common.README.tmp $@ + +deb_trash += debian/emacsVER-common.README.tmp +deb_trash += debian/emacsVER-common.README.00 +deb_trash += debian/emacsVER-common.README.01 + +debian/protected-files.tgz: + tar czpSf debian/protected-files.tgz.tmp $(protected_files) + mv debian/protected-files.tgz.tmp $@ + +debian/stamp/patch: debian/protected-files.tgz + $(checkdir) + $(patch) + mkdir -p $(dir $@) && touch $@ + +debian/stamp/setup: debian/stamp/patch + $(checkdir) + cp /usr/share/misc/config.sub . + cp /usr/share/misc/config.guess . + mkdir -p $(dir $@) && touch $@ + +# common configure flags +confflags += --prefix=/usr +confflags += --sharedstatedir=/var/lib +confflags += --libexecdir=/usr/lib +confflags += --localstatedir=/var/lib +confflags += --infodir=/usr/share/info +confflags += --mandir=/usr/share/man +confflags += --with-pop=yes +confflags += --enable-locallisppath=$(local_lpath) + +# x configure flags +confflags_x := $(confflags) +confflags_x += --with-x=yes +confflags_x += --with-x-toolkit=gtk +confflags_x += --with-toolkit-scroll-bars + +# nox configure flags +confflags_nox := $(confflags) +confflags_nox += --with-x=no + +# lucid configure flags +confflags_lucid := $(confflags) +confflags_lucid += --with-x=yes +confflags_lucid += --with-x-toolkit=lucid +confflags_lucid += --with-toolkit-scroll-bars + +configure: debian/stamp/configure +.PHONY: configure + +define cfg_tree + rm -rf $(1) + mkdir $(1) + cp -a $$(ls -A | grep -v '^debian$$' | grep -v '^.pc$$') "$(1)" + cd $(1) && CFLAGS="$(CFLAGS)" ../../configure $(confflags) $(2) +endef + +# For those who prefer the old-style non-toolkit scrollbars, just add +# --without-toolkit-scroll-bars to the build-x cfg_tree line below. +# The resulting emacsXY package will have the old scrollbars. + +debian/stamp/configure: debian/stamp/setup + $(checkdir) + $(call cfg_tree,debian/build-x,$(confflags_x)) + $(call cfg_tree,debian/build-nox,$(confflags_nox)) + $(call cfg_tree,debian/build-lucid,$(confflags_lucid)) + mkdir -p debian/stamp && touch $@ + +build: debian/stamp/build +.PHONY: build + +debian/stamp/build: debian/stamp/configure $(autogen_build_files) + $(checkdir) + # See if we can do without the bootstrap now... + #cd debian/build-x && $(build_cmd) bootstrap + #cd debian/build-x && $(build_cmd) clean + $(call build_cmd,debian/build-x) + $(call build_cmd,debian/build-nox) + $(call build_cmd,debian/build-lucid) + mkdir -p debian/stamp && touch $@ + + +define install_common_binpkg_bits + # args: (1) srcdir (2) pkgdir (3) pkgname (4) bin-suffix + + install -d $(2)/usr/bin/ + test -f $(1)/usr/bin/emacs-* + cp -a $(1)/usr/bin/emacs-* $(2)/usr/bin/$(flavor)-$(4) + dh_link -p$(3) usr/bin/$(flavor)-$(4) usr/bin/$(flavor) + + install -d $(2)/usr/share/emacs/$(runtime_ver)/etc + cp -a $(1)/usr/share/emacs/$(runtime_ver)/etc/DOC-$(runtime_ver).1 \ + $(2)/usr/share/emacs/$(runtime_ver)/etc/ + + install -d $(2)/usr/share/man/man1 + dh_link -p$(3) \ + usr/share/man/man1/emacs.$(flavor).1.gz \ + usr/share/man/man1/$(flavor).1.gz + dh_link -p$(3) \ + usr/share/man/man1/emacs.$(flavor).1.gz \ + usr/share/man/man1/$(flavor)-$(4).1.gz + +endef + + +install: debian/stamp/build $(autogen_install_files) + $(checkdir) + dh_testdir + dh_testroot + dh_clean -k + dh_installdirs + + rm -rf $(install_dir_x) $(install_dir_nox) $(install_dir_lucid) + + # Deal with accidental multiple version problem. + rm -f debian/build-x/etc/DOC-$(runtime_ver).* + rm -f debian/build-x/src/emacs-$(runtime_ver).* + rm -f debian/build-x/src/emacs + $(call emacs_inst,build-x,$(install_dir_x)) + + # Deal with accidental multiple version problem. + rm -f debian/build-nox/etc/DOC-$(runtime_ver).* + rm -f debian/build-nox/src/emacs-$(runtime_ver).* + rm -f debian/build-nox/src/emacs + $(call emacs_inst,build-nox,$(install_dir_nox)) + + $(call emacs_inst,build-lucid,$(install_dir_lucid)) + +# # Use X install dir for the common packages too. +# $(call emacs_inst,build-x,$(install_dir_x)) + + ################################################## + # emacsXY-common + + cp -a $(install_dir_x)/* $(pkgdir_common) + + rm -r $(pkgdir_common)/usr/bin + rm -r $(pkgdir_common)/usr/lib + + cd $(pkgdir_common)/usr/share/emacs/$(runtime_ver)/etc \ + && test -f DOC-$(runtime_ver).* + cd $(pkgdir_common)/usr/share/emacs/$(runtime_ver)/etc \ + && rm DOC-$(runtime_ver).* + + # lisp path directories + install -d $(pkgdir_common)/etc/$(flavor)/site-start.d + install -d $(pkgdir_common)/usr/share/$(flavor) + + # The version-specific site-lisp dir, say emacs/21.1/site-lisp, needs + # to be in share/FLAVOR so that as we upgrade from 21.1 to 21.2, + # etc., add-on package bits don't get left behind. + mv $(pkgdir_common)/usr/share/emacs/$(runtime_ver)/site-lisp \ + $(pkgdir_common)/usr/share/$(flavor) + dh_link -p$(flavor)-common usr/share/$(flavor)/site-lisp \ + usr/share/emacs/$(runtime_ver)/site-lisp + + # This is a duplicate of the file in FLAVOR/site-lisp + rm $(pkgdir_common)/usr/share/emacs/site-lisp/subdirs.el + + cd $(pkgdir_common)/usr/share/emacs/$(runtime_ver)/etc/images/icons \ + && convert hicolor/16x16/apps/emacs.{png,xpm} + cd $(pkgdir_common)/usr/share/emacs/$(runtime_ver)/etc/images/icons \ + && convert hicolor/32x32/apps/emacs.{png,xpm} + + # Fixup image files in unversioned directories (remove old + # images, version unversioned images) and prepare for + # update-alternatives. + rm $(pkgdir_common)/usr/share/icons/hicolor/16x16/apps/emacs22.png + rm $(pkgdir_common)/usr/share/icons/hicolor/24x24/apps/emacs22.png + rm $(pkgdir_common)/usr/share/icons/hicolor/48x48/apps/emacs22.png + + cd $(pkgdir_common)/usr/share/icons/hicolor \ + && mv scalable/apps/emacs.svg scalable/apps/${flavor}.svg \ + && mv 16x16/apps/emacs.png 16x16/apps/${flavor}.png \ + && mv 24x24/apps/emacs.png 24x24/apps/${flavor}.png \ + && mv 32x32/apps/emacs.png 32x32/apps/${flavor}.png \ + && mv 48x48/apps/emacs.png 48x48/apps/${flavor}.png \ + && mv 128x128/apps/emacs.png 128x128/apps/${flavor}.png + + cd $(pkgdir_common)/usr/share/icons/hicolor/scalable/mimetypes \ + && mv emacs-document.svg ${flavor}-document.svg + + # Remove redundant emacs.desktop file. + rm $(pkgdir_common)/usr/share/emacs/$(runtime_ver)/etc/emacs.desktop + rm $(pkgdir_common)/usr/share/applications/emacs.desktop + + # Mangle info files. + chmod 755 debian/mangle-info + for f in $(main_dir_info_files); \ + do \ + DEBIAN_INFO_PREFIX=$(info_subdir) \ + debian/mangle-info \ + $(pkgdir_common)/usr/share/info/$(info_subdir)/$$f; \ + done + + perl -pi -e "s|man1/etags\\.1|man1/etags\\.$(flavor)\\.1|" \ + $(pkgdir_common)/usr/share/man/man1/ctags.$(flavor).1 + + cd $(pkgdir_common)/usr/share/man/man1/ && \ + for f in *.1; do mv $$f $$(basename $${f} .1).$(flavor).1; done + + # At least etc/COPYING is needed by M-x describe-copying. + rm $(pkgdir_common)/usr/share/emacs/$(runtime_ver)/etc/COPYING + rm $(pkgdir_common)/usr/share/emacs/$(runtime_ver)/lisp/COPYING + dh_link -p$(flavor)-common /usr/share/common-licenses/GPL-3 \ + usr/share/emacs/$(runtime_ver)/etc/COPYING + dh_link -p$(flavor)-common /usr/share/common-licenses/GPL-3 \ + usr/share/emacs/$(runtime_ver)/lisp/COPYING + + $(pf); cd $(pkgdir_common) && \ + find -name "*.elc" | perl -pe 's/\.elc$$/\.el/o' | xargs rm -f + + $(pf); cd $(pkgdir_common) && \ + find -name "*.elc" | perl -pe 's/\.elc$$/\.el\.gz/o' | xargs rm -f + + # Remove extraneous info dir files. These may not exist if dpkg + # is 1.5.4 or newer. + rm -f $(pkgdir_common)/usr/share/info/emacs-$(major_ver)/dir + rm -f $(pkgdir_common)/usr/share/info/emacs-$(major_ver)/dir.old + + # Remove the shared game score directory to as a simple way to avoid + # a conflict with other flavors of Emacs. Since Debian's + # update-game-score binary isn't setuid, that directory is never used. + rm $(pkgdir_common)/var/games/emacs/tetris-scores + rm $(pkgdir_common)/var/games/emacs/snake-scores + rmdir $(pkgdir_common)/var/games/emacs/ + rmdir $(pkgdir_common)/var/games/ + rmdir $(pkgdir_common)/var/ + + # Make sure /usr/local dir doesn't exist. + rm -r $(pkgdir_common)/usr/local + + ################################################## + # emacsXY-bin-common + + # Move common binaries to emacs-bin-common. + install -d $(pkgdir_bin_common)/usr + cp -a $(install_dir_x)/usr/bin $(pkgdir_bin_common)/usr + cp -a $(install_dir_x)/usr/lib $(pkgdir_bin_common)/usr + + # Make sure there's just one. + test -f $(pkgdir_bin_common)/usr/bin/emacs-* + rm $(pkgdir_bin_common)/usr/bin/{emacs,emacs-*} + + # Set up movemail. + chown root.mail $(pkgdir_bin_common)/$(movemail_bin) + chmod g+s $(pkgdir_bin_common)/$(movemail_bin) + + # Set up alternatives. + alternatives=`ls $(pkgdir_bin_common)/usr/bin | xargs` && \ + set -x && \ + for f in debian/$(flavor)-bin-common.*; \ + do \ + perl -pwi -e "s|\@ALTERNATIVES\@|$${alternatives}|go" $$f ; \ + done + + for f in `ls $(pkgdir_bin_common)/usr/bin`; \ + do \ + mv $(pkgdir_bin_common)/usr/bin/$$f \ + $(pkgdir_bin_common)/usr/bin/$$f.$(flavor) ; \ + done + + ################################################## + # emacsXY + $(call install_common_binpkg_bits,\ + $(install_dir_x),$(pkgdir_x),$(flavor),x) + + # install desktop entry + install -d $(pkgdir_x)/usr/share/applications + install -m 0644 \ + debian/$(flavor).desktop $(pkgdir_x)/usr/share/applications/ + + ################################################## + # emacsXY-nox + $(call emacs_inst,build-nox,$(install_dir_nox)) + $(call install_common_binpkg_bits,\ + $(install_dir_nox),$(pkgdir_nox),$(flavor)-nox,nox) + rm -rf $(install_dir_nox) + + ################################################## + # emacsXY-lucid + $(call emacs_inst,build-lucid,$(install_dir_lucid)) + $(call install_common_binpkg_bits,\ + $(install_dir_lucid),$(pkgdir_lucid),$(flavor)-lucid,lucid) + + # install desktop entry + install -d $(pkgdir_lucid)/usr/share/applications + install -m 0644 \ + debian/$(flavor)-lucid.desktop $(pkgdir_lucid)/usr/share/applications/ + rm -rf $(install_dir_lucid) + + ################################################## + # emacsXY-el + + $(pf); \ + (cd $(install_dir_x) && find -name "*.el" -o -name "*.el.gz" -print0 \ + | tar cpf - --null --files-from -) \ + | (cd $(pkgdir_el) && tar xpf -) + + ################################################## + # final cleanup + rm -rf $(install_dir_x) + rm -rf $(install_dir_nox) + rm -rf $(install_dir_lucid) + + +binary-indep: build install + $(checkdir) + dh_testdir -i + dh_testroot -i + dh_installchangelogs -i + dh_lintian -i + dh_installdocs -i + dh_link -i + dh_strip -i + dh_compress -i + dh_fixperms -i + dh_installdeb -i + dh_shlibdeps -i + dh_gencontrol -i + dh_md5sums -i + dh_builddeb -i + +binary-arch: build install + $(checkdir) + dh_testdir -a + dh_testroot -a + dh_installinfo -a + dh_lintian -a + dh_installman -a + dh_installchangelogs -a + dh_installdocs -a + dh_installexamples -a +# dh_install -a + dh_installmenu -a + dh_link -a + dh_strip -a + dh_compress -a + dh_fixperms -a -X$(movemail_bin) + dh_installdeb -a + dh_shlibdeps -a + dh_gencontrol -a + dh_md5sums -a + dh_builddeb -a + +binary: binary-indep binary-arch + +clean: debian-sync + $(checkdir) + $(cleanup_all) + +source diff: + @echo >&2 'source and diff are obsolete - use dpkg-source -b'; false + +.PHONY: binary binary-arch binary-indep clean --- emacs23-23.1+1.orig/debian/README.add-on-package-maintainers +++ emacs23-23.1+1/debian/README.add-on-package-maintainers @@ -0,0 +1,2 @@ +Please see /usr/share/doc/emacsen-common/debian-emacs-policy.gz for +information on how to properly structure your emacs add-on packages. --- emacs23-23.1+1.orig/debian/control +++ emacs23-23.1+1/debian/control @@ -0,0 +1,91 @@ +Source: emacs23 +Section: editors +Priority: optional +Maintainer: Ubuntu Core Developers +XSBC-Original-Maintainer: Rob Browning +Uploaders: Jerome Marant +Build-Depends: mailx, libncurses5-dev, texinfo, liblockfile-dev, librsvg2-dev, libgif-dev | libungif4-dev, libtiff4-dev | libtiff-dev, xaw3dg-dev, libpng12-dev, libjpeg62-dev, libm17n-dev, libotf-dev, libgpm-dev [!hurd-i386 !kfreebsd-i386 !kfreebsd-amd64], libdbus-1-dev, autotools-dev, dpkg-dev (>> 1.10.0), quilt (>= 0.42-1), debhelper (>= 4), libxaw7-dev, sharutils, imagemagick, libgtk2.0-dev, libasound2-dev [!hurd-i386 !kfreebsd-i386 !kfreebsd-amd64] +Standards-Version: 3.7.2 + +Package: emacs +Section: editors +Priority: optional +Architecture: all +Depends: emacs23 | emacs23-lucid | emacs23-nox +Provides: emacsen, editor, mail-reader, news-reader +Description: The GNU Emacs editor (metapackage) + GNU Emacs is the extensible self-documenting text editor. + This is a metapackage which will always depend on the latest Emacs + release. + +Package: emacs23-lucid +Section: editors +Priority: optional +Architecture: any +Depends: emacs23-bin-common (= ${binary:Version}), install-info, ${shlibs:Depends} +Provides: emacs23, emacsen, editor, info-browser, mail-reader, news-reader +Suggests: emacs23-common-non-dfsg +Conflicts: emacs23, emacs23-nox, emacs23-gtk +Replaces: emacs23, emacs23-nox, emacs23-gtk +Description: The GNU Emacs editor + GNU Emacs is the extensible self-documenting text editor. + This package contains a version of Emacs with a Lucid user interface. + +Package: emacs23-nox +Section: editors +Priority: optional +Architecture: any +Depends: emacs23-bin-common (= ${binary:Version}), install-info, ${shlibs:Depends} +Provides: emacs23, editor, emacsen, info-browser, mail-reader, news-reader +Suggests: emacs23-common-non-dfsg +Conflicts: emacs23, emacs23-lucid, emacs23-gtk +Replaces: emacs23, emacs23-lucid, emacs23-gtk +Description: The GNU Emacs editor (without X support) + GNU Emacs is the extensible self-documenting text editor. + This package contains a version of Emacs compiled without support for X. + +Package: emacs23 +Section: editors +Priority: optional +Architecture: any +Depends: emacs23-bin-common (= ${binary:Version}), install-info, ${shlibs:Depends} +Provides: editor, emacsen, info-browser, mail-reader, news-reader, emacs23-gtk +Suggests: emacs23-common-non-dfsg +Conflicts: emacs23-lucid, emacs23-nox, emacs23-gtk +Replaces: emacs23-lucid, emacs23-nox, emacs23-gtk +Description: The GNU Emacs editor (with GTK+ user interface) + GNU Emacs is the extensible self-documenting text editor. + This package contains a version of Emacs with a GTK+ user interface. + +Package: emacs23-bin-common +Section: editors +Priority: optional +Architecture: any +Depends: emacs23-common (= ${source:Version}), ${shlibs:Depends} +Description: The GNU Emacs editor's shared, architecture dependent files + GNU Emacs is the extensible self-documenting text editor. + This package contains the architecture dependent infrastructure + that's shared by emacs23, emacs23-lucid, and emacs23-nox. + +Package: emacs23-common +Section: editors +Priority: optional +Architecture: all +Depends: emacsen-common (>= 1.4.10), dpkg (>= 1.9.0), ${shlibs:Depends} +Suggests: emacs23-el +Conflicts: emacs23-el (<< ${source:Version}), emacs23-common-non-dfsg +Replaces: emacs23-common-non-dfsg +Description: The GNU Emacs editor's shared, architecture independent infrastructure + GNU Emacs is the extensible self-documenting text editor. + This package contains the architecture independent infrastructure + that's shared by emacs23, emacs23-lucid, and emacs23-nox. + +Package: emacs23-el +Section: editors +Priority: optional +Architecture: all +Depends: emacs23-common (= ${source:Version}) +Description: GNU Emacs LISP (.el) files + GNU Emacs is the extensible self-documenting text editor. + This package contains the elisp sources for the convenience of users, + saving space in the main package for small systems. --- emacs23-23.1+1.orig/debian/emacsVER.prerm +++ emacs23-23.1+1/debian/emacsVER.prerm @@ -0,0 +1,18 @@ +#!/bin/sh + +set -e + +MAJOR=@MAJOR_VERSION@ +FLAVOR=@DEB_FLAVOR@ + +# update-alternatives on things that collide with xemacs, other editors +if [ "$1" != "upgrade" ] +then + update-alternatives --remove emacs /usr/bin/${FLAVOR}-@X_SUPPORT@ + update-alternatives --remove editor /usr/bin/${FLAVOR} +fi + +# emacsen-common registration. +/usr/lib/emacsen-common/emacs-remove ${FLAVOR} + +#DEBHELPER# --- emacs23-23.1+1.orig/debian/emacsVER-common.README +++ emacs23-23.1+1/debian/emacsVER-common.README @@ -0,0 +1,42 @@ +This file details the Debian specific changes to Emacs. + +The following tags may be used in the sections below: Patch, Status, +Author, Added-by, Provided-by, and Date. When known, Author is used +to indicate the person believed to have written the relevant code. +Provided-by may be used to indicate the person who submitted the code +to Debian, and Added-by indicates the person who actually added the +code to the Debian package. + +* The Debian copy of the upstream source contains no .elc files. + + The .elc files have been removed because we always regenerate them + and because Emacs modifies them in the source tree during the build + process, even when using a VPATH build. This means that a "make + clean" can't easily return the tree to the upstream state, resulting + in a giant Debian binary diff. There are other solutions if this + turns out to be a problem. If nothing else, we can keep the current + infrastructure and just add the .elc files to protected_files in + debian/rules. Removing the .elc files doesn't affect whether or not + our source archive would match the upstream md5sum because we have + to repackage it anyway to add leim support. + +* The etc/yow.lines file has been updated from the upstream development tree. + +The etc/yow.lines file in the Debian package is newer than the one in +the original distribution. It has been copied from the upstream Emacs +development tree. + +* The -i icon is the Emacs GNU. + +* Those who prefer the old-style scrollbars can edit debian/rules + + If you prefer the old-style, non-toolkit scrollbars, just edit + debian/rules to add --without-toolkit-scrollbars where indicated and + rebuild. + +@@PATCH_LIST_HERE@@ + +Local Variables: +mode: outline +outline-regexp: " *\\*+" +End: --- emacs23-23.1+1.orig/debian/emacsVER.lintian-overrides +++ emacs23-23.1+1/debian/emacsVER.lintian-overrides @@ -0,0 +1,2 @@ +@PKG_NAME@ binary: menu-icon-missing /usr/share/emacs/@FULL_VERSION@/etc/images/icons/hicolor/16x16/apps/emacs.xpm +@PKG_NAME@ binary: menu-icon-missing /usr/share/emacs/@FULL_VERSION@/etc/images/icons/hicolor/32x32/apps/emacs.xpm --- emacs23-23.1+1.orig/debian/emacsVER-common.prerm +++ emacs23-23.1+1/debian/emacsVER-common.prerm @@ -0,0 +1,22 @@ +#!/bin/sh + +set -e + +MAJOR=@MAJOR_VERSION@ +MINOR=@MINOR_VERSION@ +FULL=@FULL_VERSION@ +INFO_FILES="@INFO_FILES@" +INFO_SUBDIR=@INFO_SUBDIR@ + +set +e +# Only remove these directories if they're empty. +rmdir /usr/local/share/emacs/${FULL}/site-lisp 2>/dev/null +rmdir /usr/local/share/emacs/${FULL} 2>/dev/null +set -e + +for file in ${INFO_FILES} +do + install-info --quiet --remove-exactly ${INFO_SUBDIR}/${file} || true +done + +#DEBHELPER# --- emacs23-23.1+1.orig/debian/emacsVER-bin-common.postinst +++ emacs23-23.1+1/debian/emacsVER-bin-common.postinst @@ -0,0 +1,19 @@ +#!/bin/sh -e + +FLAVOR=@DEB_FLAVOR@ +MAJOR=@MAJOR_VERSION@ +MINOR=@MINOR_VERSION@ +FULL=@FULL_VERSION@ +ALTERNATIVES="@ALTERNATIVES@" +BIN_PRIORITY=@BIN_PRIORITY@ + +# update-alternatives on things that collide with xemacs, other editors +for i in ${ALTERNATIVES} +do + update-alternatives \ + --install /usr/bin/$i $i /usr/bin/$i.${FLAVOR} ${BIN_PRIORITY} \ + --slave /usr/share/man/man1/$i.1.gz $i.1.gz \ + /usr/share/man/man1/$i.${FLAVOR}.1.gz +done + +#DEBHELPER# --- emacs23-23.1+1.orig/debian/emacsVER.README +++ emacs23-23.1+1/debian/emacsVER.README @@ -0,0 +1,3 @@ + +Please see /usr/share/doc/@PKG_NAME@-common/ as the primary +documentation directory. --- emacs23-23.1+1.orig/debian/mangle-info +++ emacs23-23.1+1/debian/mangle-info @@ -0,0 +1,17 @@ +#!/usr/bin/perl -w -i + +use English; +use strict; + +$RS = undef; + +my $prefix = $ENV{"DEBIAN_INFO_PREFIX"}; + +my $x = <>; +if(!($x =~ m/^(\s*START-INFO-DIR-ENTRY\s+\*\s*[^:]+:\s*)\(([^\)]+)\)/mo)) { + die "Couldn't find START-INFO-DIR-ENTRY."; +} + +print ${PREMATCH}; +print "$1($prefix/$2)"; +print ${POSTMATCH}; --- emacs23-23.1+1.orig/debian/autofiles-diff-header +++ emacs23-23.1+1/debian/autofiles-diff-header @@ -0,0 +1,3 @@ +* The autoconf related files have been updated. + Patch: autofiles.dpatch + Author: N/A (automatically generated) --- emacs23-23.1+1.orig/debian/emacsVER.README.Debian +++ emacs23-23.1+1/debian/emacsVER.README.Debian @@ -0,0 +1,3 @@ + +Please see /usr/share/doc/emacs@MAJOR_VERSION@-common/ as the primary +documentation directory. --- emacs23-23.1+1.orig/debian/compat +++ emacs23-23.1+1/debian/compat @@ -0,0 +1 @@ +4 --- emacs23-23.1+1.orig/debian/emacsVER-common.postinst +++ emacs23-23.1+1/debian/emacsVER-common.postinst @@ -0,0 +1,63 @@ +#!/bin/sh -e + +MAJOR=@MAJOR_VERSION@ +MINOR=@MINOR_VERSION@ +FULL=@FULL_VERSION@ +INFO_FILES="@INFO_FILES@" +INFO_SUBDIR=@INFO_SUBDIR@ + +CRUFT_INFOFILES="ccmode emacs widget" + +# We have to clean these up because the old package didn't. The info +# files were being removed in the postinst, not the prerm, and so +# install-info wasn't doing anything because the files weren't there.. +for file in ${CRUFT_INFOFILES} +do + install-info --quiet --remove-exactly ${file} || true +done + +for file in ${INFO_FILES} +do + install-info --quiet --section Emacs Emacs \ + /usr/share/info/${INFO_SUBDIR}/${file}.gz || true +done + +# Create the site-lisp dir for this flavor if we're allowed + +parentdir=/usr/local/share/emacs +newdir=site-lisp + +if [ -d ${parentdir} ] +then + if mkdir ${parentdir}/${newdir} 2>/dev/null + then + chown root:staff ${parentdir}/${newdir} + chmod 2775 ${parentdir}/${newdir} + fi +fi + +parentdir=/usr/local/share/emacs +newdir=${FULL} + +if [ -d ${parentdir} ] +then + if mkdir ${parentdir}/${newdir} 2>/dev/null + then + chown root:staff ${parentdir}/${newdir} + chmod 2775 ${parentdir}/${newdir} + fi +fi + +parentdir=/usr/local/share/emacs/${FULL} +newdir=site-lisp + +if [ -d ${parentdir} ] +then + if mkdir ${parentdir}/${newdir} 2>/dev/null + then + chown root:staff ${parentdir}/${newdir} + chmod 2775 ${parentdir}/${newdir} + fi +fi + +#DEBHELPER# --- emacs23-23.1+1.orig/debian/dfsg-splitter +++ emacs23-23.1+1/debian/dfsg-splitter @@ -0,0 +1,135 @@ +#!/bin/bash + +set -e +set -x + +# Usage: put the relevant emacs archive into the current directory and +# run the script. The resulting two orig.tar.gz files will be placed +# into a new ./split-tmp directory. + +emacs_archive_name="emacs-23.1.tar.gz" +emacs_dir="emacs-23.1" +emacs_version="23.1" +emacs_major="23" +deb_src_rev="1" + +main_dir="$(pwd)/split-tmp/${emacs_dir}" +non_main_dir="$(pwd)/split-tmp/${emacs_dir}-non-dfsg" + +if ! test root = "`whoami`" +then + echo Use fakeroot. + exit 1 +fi + +if test -e split-tmp +then + echo "./split-tmp already exists - aborting" + exit 1 +fi + +mkdir ./split-tmp +pushd split-tmp + +umask 002 + +tar xzf "../${emacs_archive_name}" + +find "${emacs_dir}" -name "*.elc" -exec rm {} + +find "${emacs_dir}"/info -type f \ + -not -name "COPYING" -not -name dir -exec rm {} + + +mkdir "${non_main_dir}" + +function move_to_non_main_dir() +{ + pushd "${emacs_dir}" + test "$1" + test ! -e "${non_main_dir}/$1" + cp -a --parents "$1" "${non_main_dir}/" + rm -r "$1" + popd +} + +function copy_to_non_main_dir() +{ + pushd "${emacs_dir}" + cp -a --parents "$1" "${non_main_dir}/" + popd +} + +function remove_from_main_dir() +{ + pushd "${emacs_dir}" + rm "$1" + popd +} + +# assumes someone has already copied file to non-main dir +function move_to_main_dir() +{ + pushd "${non_main_dir}" + cp -a --parents "$1" "${main_dir}/" + rm "$1" + popd +} + +# assumes someone has already copied file to non-main dir +function copy_to_main_dir() +{ + pushd "${non_main_dir}" + cp -a --parents "$1" "${main_dir}/" + popd +} + +# So both sides will have a copy (at the very least, version.el refers to it). +copy_to_non_main_dir "etc/COPYING" + +# verbatim dist only +move_to_non_main_dir "etc/CENSORSHIP" +move_to_non_main_dir "etc/copying.paper" +move_to_non_main_dir "etc/LINUX-GNU" +move_to_non_main_dir "etc/THE-GNU-PROJECT" +move_to_non_main_dir "etc/WHY-FREE" +move_to_non_main_dir "etc/GNU" +move_to_non_main_dir "etc/MOTIVATION" + +# reprinted with permissions or copyright mentioned +# no modification mention +move_to_non_main_dir "etc/INTERVIEW" + +# Assuming modification not allowed by default (emails, etc.) +move_to_non_main_dir "etc/COOKIES" +move_to_non_main_dir "etc/DEVEL.HUMOR" +move_to_non_main_dir "etc/JOKES" + +# This is used via debian/rules to track the nominal_ver. +copy_to_non_main_dir "lisp/version.el" + +# GFDL documentation in doc/ +move_to_non_main_dir "doc/lispintro" +move_to_non_main_dir "doc/lispref" +move_to_non_main_dir "doc/emacs" + +# doc/misc + +# Most doc/misc files don't appear to be compatible with the DFSG. +move_to_non_main_dir "doc/misc" + +# doc/misc files that do appear to be compatible with the DFSG +move_to_main_dir "doc/misc/faq.texi" + +# Copy back files we want in both archives. +copy_to_main_dir "doc/misc/ChangeLog" +copy_to_main_dir "doc/misc/Makefile.in" + + +GZIP=-9v tar czpSf \ + "emacs${emacs_major}_${emacs_version}+${deb_src_rev}.orig.tar.gz" \ + "${emacs_dir}" + +GZIP=-9v tar czpSf \ + "emacs${emacs_major}-non-dfsg_${emacs_version}+${deb_src_rev}.orig.tar.gz" \ + "${emacs_dir}"-non-dfsg + +exit 0 --- emacs23-23.1+1.orig/debian/emacsVER-common.lintian-overrides +++ emacs23-23.1+1/debian/emacsVER-common.lintian-overrides @@ -0,0 +1 @@ +@PKG_NAME@ binary: desktop-command-not-in-package /usr/share/applications/emacs.desktop emacs --- emacs23-23.1+1.orig/debian/emacsVER-common.docs +++ emacs23-23.1+1/debian/emacsVER-common.docs @@ -0,0 +1,3 @@ +BUGS +README +debian/README.add-on-package-maintainers --- emacs23-23.1+1.orig/debian/emacsVER.postinst +++ emacs23-23.1+1/debian/emacsVER.postinst @@ -0,0 +1,37 @@ +#!/bin/sh + +set -e + +FLAVOR=@DEB_FLAVOR@ + +update-alternatives \ + --install /usr/bin/emacs emacs \ + /usr/bin/${FLAVOR}-@X_SUPPORT@ @BIN_PRIORITY@ \ + --slave /usr/share/man/man1/emacs.1.gz emacs.1.gz \ + /usr/share/man/man1/emacs.${FLAVOR}.1.gz \ + --slave /usr/share/icons/hicolor/scalable/apps/emacs.svg emacs.svg \ + /usr/share/icons/hicolor/scalable/apps/${FLAVOR}.svg \ + --slave /usr/share/icons/hicolor/scalable/mimetypes/emacs-document.svg \ + emacs-document.svg \ + /usr/share/icons/hicolor/scalable/mimetypes/${FLAVOR}-document.svg \ + --slave /usr/share/icons/hicolor/16x16/apps/emacs.png emacs-16x16.png \ + /usr/share/icons/hicolor/16x16/apps/${FLAVOR}.png \ + --slave /usr/share/icons/hicolor/24x24/apps/emacs.png emacs-24x24.png \ + /usr/share/icons/hicolor/24x24/apps/${FLAVOR}.png \ + --slave /usr/share/icons/hicolor/32x32/apps/emacs.png emacs-32x32.png \ + /usr/share/icons/hicolor/32x32/apps/${FLAVOR}.png \ + --slave /usr/share/icons/hicolor/48x48/apps/emacs.png emacs-48x48.png \ + /usr/share/icons/hicolor/48x48/apps/${FLAVOR}.png \ + --slave /usr/share/icons/hicolor/128x128/apps/emacs.png emacs-128x128.png \ + /usr/share/icons/hicolor/128x128/apps/${FLAVOR}.png + +update-alternatives \ + --install /usr/bin/editor editor \ + /usr/bin/${FLAVOR} 0 \ + --slave /usr/share/man/man1/editor.1.gz editor.1.gz \ + /usr/share/man/man1/emacs.1${FLAVOR}.1.gz + +# emacsen-common registration. +/usr/lib/emacsen-common/emacs-install ${FLAVOR} + +#DEBHELPER# --- emacs23-23.1+1.orig/debian/control.in +++ emacs23-23.1+1/debian/control.in @@ -0,0 +1,91 @@ +Source: @DEB_FLAVOR@ +Section: editors +Priority: optional +Maintainer: Ubuntu Core Developers +XSBC-Original-Maintainer: Rob Browning +Uploaders: Jerome Marant +Build-Depends: mailx, libncurses5-dev, texinfo, liblockfile-dev, librsvg2-dev, libgif-dev | libungif4-dev, libtiff4-dev | libtiff-dev, xaw3dg-dev, libpng12-dev, libjpeg62-dev, libm17n-dev, libotf-dev, libgpm-dev [!hurd-i386 !kfreebsd-i386 !kfreebsd-amd64], libdbus-1-dev, autotools-dev, dpkg-dev (>> 1.10.0), quilt (>= 0.42-1), debhelper (>= 4), libxaw7-dev, sharutils, imagemagick, libgtk2.0-dev, libasound2-dev [!hurd-i386 !kfreebsd-i386 !kfreebsd-amd64] +Standards-Version: 3.7.2 + +Package: emacs +Section: editors +Priority: optional +Architecture: all +Depends: @DEB_FLAVOR@ | @DEB_FLAVOR@-lucid | @DEB_FLAVOR@-nox +Provides: emacsen, editor, mail-reader, news-reader +Description: The GNU Emacs editor (metapackage) + GNU Emacs is the extensible self-documenting text editor. + This is a metapackage which will always depend on the latest Emacs + release. + +Package: @DEB_FLAVOR@-lucid +Section: editors +Priority: optional +Architecture: any +Depends: @DEB_FLAVOR@-bin-common (= ${binary:Version}), install-info, ${shlibs:Depends} +Provides: @DEB_FLAVOR@, emacsen, editor, info-browser, mail-reader, news-reader +Suggests: @DEB_FLAVOR@-common-non-dfsg +Conflicts: @DEB_FLAVOR@, @DEB_FLAVOR@-nox, emacs23-gtk +Replaces: @DEB_FLAVOR@, @DEB_FLAVOR@-nox, emacs23-gtk +Description: The GNU Emacs editor + GNU Emacs is the extensible self-documenting text editor. + This package contains a version of Emacs with a Lucid user interface. + +Package: @DEB_FLAVOR@-nox +Section: editors +Priority: optional +Architecture: any +Depends: @DEB_FLAVOR@-bin-common (= ${binary:Version}), install-info, ${shlibs:Depends} +Provides: @DEB_FLAVOR@, editor, emacsen, info-browser, mail-reader, news-reader +Suggests: @DEB_FLAVOR@-common-non-dfsg +Conflicts: @DEB_FLAVOR@, @DEB_FLAVOR@-lucid, emacs23-gtk +Replaces: @DEB_FLAVOR@, @DEB_FLAVOR@-lucid, emacs23-gtk +Description: The GNU Emacs editor (without X support) + GNU Emacs is the extensible self-documenting text editor. + This package contains a version of Emacs compiled without support for X. + +Package: @DEB_FLAVOR@ +Section: editors +Priority: optional +Architecture: any +Depends: @DEB_FLAVOR@-bin-common (= ${binary:Version}), install-info, ${shlibs:Depends} +Provides: editor, emacsen, info-browser, mail-reader, news-reader, emacs23-gtk +Suggests: @DEB_FLAVOR@-common-non-dfsg +Conflicts: @DEB_FLAVOR@-lucid, @DEB_FLAVOR@-nox, emacs23-gtk +Replaces: @DEB_FLAVOR@-lucid, @DEB_FLAVOR@-nox, emacs23-gtk +Description: The GNU Emacs editor (with GTK+ user interface) + GNU Emacs is the extensible self-documenting text editor. + This package contains a version of Emacs with a GTK+ user interface. + +Package: @DEB_FLAVOR@-bin-common +Section: editors +Priority: optional +Architecture: any +Depends: @DEB_FLAVOR@-common (= ${source:Version}), ${shlibs:Depends} +Description: The GNU Emacs editor's shared, architecture dependent files + GNU Emacs is the extensible self-documenting text editor. + This package contains the architecture dependent infrastructure + that's shared by @DEB_FLAVOR@, @DEB_FLAVOR@-lucid, and @DEB_FLAVOR@-nox. + +Package: @DEB_FLAVOR@-common +Section: editors +Priority: optional +Architecture: all +Depends: emacsen-common (>= 1.4.10), dpkg (>= 1.9.0), ${shlibs:Depends} +Suggests: @DEB_FLAVOR@-el +Conflicts: @DEB_FLAVOR@-el (<< ${source:Version}), @DEB_FLAVOR@-common-non-dfsg +Replaces: @DEB_FLAVOR@-common-non-dfsg +Description: The GNU Emacs editor's shared, architecture independent infrastructure + GNU Emacs is the extensible self-documenting text editor. + This package contains the architecture independent infrastructure + that's shared by @DEB_FLAVOR@, @DEB_FLAVOR@-lucid, and @DEB_FLAVOR@-nox. + +Package: @DEB_FLAVOR@-el +Section: editors +Priority: optional +Architecture: all +Depends: @DEB_FLAVOR@-common (= ${source:Version}) +Description: GNU Emacs LISP (.el) files + GNU Emacs is the extensible self-documenting text editor. + This package contains the elisp sources for the convenience of users, + saving space in the main package for small systems. --- emacs23-23.1+1.orig/debian/emacsVER.menu +++ emacs23-23.1+1/debian/emacsVER.menu @@ -0,0 +1,17 @@ +?package(@PKG_NAME@):\ + needs="X11"\ + section="Applications/Editors"\ + title="Emacs @MENU_VERSION@ (X11)"\ + command="/usr/bin/@DEB_FLAVOR@"\ + icon16x16="/usr/share/emacs/@FULL_VERSION@/etc/images/icons/hicolor/16x16/apps/emacs.xpm"\ + icon32x32="/usr/share/emacs/@FULL_VERSION@/etc/images/icons/hicolor/32x32/apps/emacs.xpm"\ + hints="Text" + +?package(@PKG_NAME@):\ + needs="text"\ + section="Applications/Editors"\ + title="Emacs @MENU_VERSION@ (text)"\ + command="/usr/bin/@DEB_FLAVOR@ -nw"\ + icon16x16="/usr/share/emacs/@FULL_VERSION@/etc/images/icons/hicolor/16x16/apps/emacs.xpm"\ + icon32x32="/usr/share/emacs/@FULL_VERSION@/etc/images/icons/hicolor/32x32/apps/emacs.xpm"\ + hints="Text" --- emacs23-23.1+1.orig/debian/missing-file.dfsg +++ emacs23-23.1+1/debian/missing-file.dfsg @@ -0,0 +1,10 @@ + +The file that would normally be displayed here (@FILE@) has been moved +to the emacs@MAJOR_VERSION@-common-non-dfsg package because its +license does not appear to be compatible with the Debian Free Software +Guidelines (DFSG). Please see +/usr/share/doc/emacs@MAJOR_VERSION@-common/copyright for more +information. + +Please install @FILE@ from Debian's non-free distribution if you would +like for Emacs to display the original file. --- emacs23-23.1+1.orig/debian/emacsVER-bin-common.prerm +++ emacs23-23.1+1/debian/emacsVER-bin-common.prerm @@ -0,0 +1,21 @@ +#!/bin/sh + +set -e + +FLAVOR=@DEB_FLAVOR@ +MAJOR=@MAJOR_VERSION@ +MINOR=@MINOR_VERSION@ +FULL=@FULL_VERSION@ +ALTERNATIVES="@ALTERNATIVES@" + +# update-alternatives on things that collide with xemacs, other editors +if [ "$1" != "upgrade" ] +then + for i in ${ALTERNATIVES} + do + update-alternatives --remove $i /usr/bin/$i.${FLAVOR} + done +fi + +#DEBHELPER# + --- emacs23-23.1+1.orig/debian/emacsVER-bin-common.lintian-overrides +++ emacs23-23.1+1/debian/emacsVER-bin-common.lintian-overrides @@ -0,0 +1,8 @@ +@PKG_NAME@ binary: setgid-binary @MOVEMAIL_BIN@ 2755 root/mail +@PKG_NAME@ binary: binary-without-manpage usr/bin/b2m.@DEB_FLAVOR@ +@PKG_NAME@ binary: binary-without-manpage usr/bin/ctags.@DEB_FLAVOR@ +@PKG_NAME@ binary: binary-without-manpage usr/bin/ebrowse.@DEB_FLAVOR@ +@PKG_NAME@ binary: binary-without-manpage usr/bin/emacsclient.@DEB_FLAVOR@ +@PKG_NAME@ binary: binary-without-manpage usr/bin/etags.@DEB_FLAVOR@ +@PKG_NAME@ binary: binary-without-manpage usr/bin/grep-changelog.@DEB_FLAVOR@ +@PKG_NAME@ binary: binary-without-manpage usr/bin/rcs-checkin.@DEB_FLAVOR@ --- emacs23-23.1+1.orig/debian/emacsVER.desktop +++ emacs23-23.1+1/debian/emacsVER.desktop @@ -0,0 +1,13 @@ +[Desktop Entry] +Version=1.0 +Encoding=UTF-8 +Name=GNU Emacs @MENU_VERSION@ +GenericName=Text Editor +Comment=View and edit files +MimeType=text/english;text/plain;text/x-makefile;text/x-c++hdr;text/x-c++src;text/x-chdr;text/x-csrc;text/x-java;text/x-moc;text/x-pascal;text/x-tcl;text/x-tex;application/x-shellscript;text/x-c;text/x-c++; +Exec=/usr/bin/@DEB_FLAVOR@ %F +TryExec=@DEB_FLAVOR@ +Icon=/usr/share/icons/hicolor/scalable/apps/@DEB_FLAVOR@.svg +Type=Application +Terminal=false +Categories=Utility;Development;TextEditor; --- emacs23-23.1+1.orig/debian/changelog +++ emacs23-23.1+1/debian/changelog @@ -0,0 +1,1554 @@ +emacs23 (23.1+1-4ubuntu5) lucid; urgency=low + + [ Rob Browning ] + * Apply upstream patch to fix problem with GTK and dynamically + generated menus (which could be unexpectedly empty). Thanks to + Baylis Shanks for the report. + (closes: 550541) + + [ Reinhard Tartler ] + * snatched patch from debian upload 23.1+1-5. LP: #415101 + + -- Reinhard Tartler Fri, 06 Nov 2009 09:21:16 +0100 + +emacs23 (23.1+1-4ubuntu4) lucid; urgency=low + + * reintroduce the "emacs" binary package. emacs22 will be changed to + no longer build it. + + -- Reinhard Tartler Wed, 04 Nov 2009 15:21:35 +0100 + +emacs23 (23.1+1-4ubuntu3) karmic; urgency=low + + * Also comment out emacs binary in debian/control.in (LP: #433397) really + this time + + -- Scott Kitterman Wed, 14 Oct 2009 11:46:59 -0400 + +emacs23 (23.1+1-4ubuntu2) karmic; urgency=low + + * Stop shipping emacs binary so emacs22 in main doesn't get hijacked + (LP: #433397) + - Comment out the binary in debian/control + + -- Scott Kitterman Sun, 11 Oct 2009 23:22:39 -0400 + +emacs23 (23.1+1-4ubuntu1) karmic; urgency=low + + * FFe granted in LP: #433397, #408085 + * debian/control.in: + - Change Maintainer to Ubuntu Core Developers, per Ubuntu policy. + - Conflict and Replace emacs23-common-non-dfsg, since we provide + all of its features. + - Do not suggest emacs23-common-non-dfsg. + - Replace use of Source-Version with source:Version. + * debian/control: Regenerate. + * debian/copyright.in: + - Remove text about removed files. + * debian/copyright: + - Regenerate. + * debian/emacsVER-common.postinst: + - Install info files. Rules copied from nondfsg package, with + the change that we use INFO_SUBDIR and INFO_FILES. + * debian/emacsVER-common.prerm: + - Remove info files. Rules copied from nondfsg package, with + the change that we use INFO_SUBDIR and INFO_FILES. + * debian/patches: + - handle-dfsg-split.diff: Remove. + - ubuntu-restore-nondfsg-files.diff: New patch that reintroduces + the non-DFSG files, with the exception of .elc files and info + files, which use special characters and thus can't be easily + represented in patch form. Both will be regenerated at build + time. + * debian/rules: + - Do not install replacements for non-DFSG files. + - Install all info files, not just efaq. + - During cleanup, chmod mangle-info back to 644, so it does not + show up as modified. + + -- Michael W. Olson (GNU address) Wed, 16 Sep 2009 19:35:02 -0700 + +emacs23 (23.1+1-4) unstable; urgency=low + + * Remove redundant upstream emacs.desktop files from emacs23-common, + and merge some of the upstream emacs.desktop file info into the + Debian files. Thanks to Michael Biebl for the + report. (closes: #541173) + + * Handle the fact that the share/info/emacs-VER/dir{,.old} files may + not be created during the install (and so may not need to be + removed). This may be the case with dpkg 1.5.4 or newer. Thanks + to Sven Joachim for the report and the + fix. (closes: 545379) + + * Add a bit to the emacsVER-lucid description. Thanks to Drew + Parsons for the suggestion. + (closes: #545263) + + * Add provides emacs23-gtk to emacs23 as a transition measure (to be + deleted in emacs24) to allow more seamless upgrades from the + earlier unstable/testing packages. Thanks to Josh Triplett + for the suggestion. (closes: #545405) + + -- Rob Browning Sun, 13 Sep 2009 18:10:28 -0700 + +emacs23 (23.1+1-3) unstable; urgency=low + + * Fix overlooked manpage rename in emacsVER.postinst. Thanks to + Sven Joachim . (closes: #539926) + + * Change emacsVER to be the GTK+ version to match the upstream + default, and add an emacsVER-lucid package for those who still + want the non-GTK+ version. Thanks to Romain Francoise + and others for the report. + (closes: #539800) + + * Don't build-depend on libgmp-dev on hurd or kfreebsd. Thanks to + Cyril Brulebois . (closes: #541353) + + * Fix emacsVER.desktop to refer to SVG file instead of incorrect + PNG, remove emacs22.png files from unversioned /usr/share/icons + directory, and change emacs*.png and emacs*.svg files to + emacsVER*.png and emacsVER*.svg. Also use update-alternatives to + manage the unversioned names for these files. Thanks to Atsuhito + KOHDA for the initial + report. (closes: #539851) + + * Fix Rmail to handle capitalized month names in Date lines, + i.e. "Date: Thu, 06 Aug 2009 18:33:32 +0100". Thanks to Jeroen + Nijhof for the report and Sven Joachim + for the fix. (closes: #540234) + + -- Rob Browning Thu, 03 Sep 2009 21:55:25 -0700 + +emacs23 (23.1+1-2) unstable; urgency=low + + * Add dependencies on install-info to primary binary packages and + remove install-info from meta package provides. Thanks to Norbert + Preining . (See emacs21 bugs #532600, #532599, + #532597, and #532602.) + + * Add libpm-dev and libdbus-1-dev build dependencies. Thanks to + Sven Joachim for reporting this and most of the + following additional issues. + + * Fix a spelling error, fix a menu section error, add a version to + the GPL file referred to by debian/copyright, and add a number of + debian/emacsVER*.lintian-overrides to quiet long-standing + warnings. + + * Fix update-alternatives to reflect the fact that all the binaries + have manpages now. Rename manpages from NAME.1FLAVOR to + NAME.FLAVOR.1. + + * Remove obsolete dependencies and conflicts (w3-el, emacs22 + packages, etc.). + + * Remove explicit install-info calls. Rely on triggers now. + + * Set debian-emacs-flavor to 'emacs23. Somehow that change didn't + make it in to the initial package and it was still set to emacs22. + + * Search /usr/share/info/emacs-23 rather than + /usr/share/info/emacs-22. + + -- Rob Browning Sun, 02 Aug 2009 19:55:15 -0700 + +emacs23 (23.1+1-1) unstable; urgency=low + + * New emacs23 packages. + + * The debian/dfsg-splitter has been updated. + + * Patches have been removed or adjusted. + + -- Rob Browning Sat, 18 Jul 2009 18:41:25 -0700 + +emacs22 (22.3+1-1) unstable; urgency=low + + * New upstream release. (closes: #512134) + + -- Rob Browning Sat, 28 Mar 2009 19:18:43 -0700 + +emacs22 (22.2+2-5) unstable; urgency=low + + * Add a build dependency on libasound2-dev which emacs22 is already + linked against on i386. This change just makes things consistent + across all the relevant platforms. Thanks to Sven Joachim + for the fix. (closes: #503054) + + * Set mail-interactive to t if /usr/bin/mail is not an executable and + fakemail is chosen. This should still help avoid silent mail loss, + but won't signal an error if the mailer is never invoked. Thanks to + Ralf Resack for proposing the + fix. (closes: #429059) + + -- Rob Browning Sun, 09 Nov 2008 12:05:33 -0800 + +emacs22 (22.2+2-4) unstable; urgency=medium + + * Fix a security problem related to the invocation of python + (CVE-2008-3949). Avoid including the current directory in the module + lookup path when invoking python from python.el. Thanks to Sven + Joachim and Michael Berg . + (closes: #499568) + + * Invoke xmlstarlet from flymake as xmlstarlet rather than xml. Thanks + to Jussi Judin . (closes: #447378) + + * Fix vc-mode's handling of internal temporary buffers. This should + avoid failures when trying to open files under monotone version + control. Thanks to Sven Joachim and Michael Berg + . (closes: #476108) + + -- Rob Browning Tue, 14 Oct 2008 21:28:47 -0700 + +emacs22 (22.2+2-3) unstable; urgency=medium + + * Fix an insecurity related to fast-lock-cache-directories + (CVE-2008-2142). Thanks to Sven Joachim and Morten + Welinder . (closes: #480885) + + * Don't remove /usr/local/share/emacs/site-lisp in emacs22-common. + Leave that up to emacsen-common. Thanks to Sven Joachim + . (closes: #490524) + + * Don't prematurely raise an error when trying to save a non-ASCII + buffer when select-safe-coding-system-accept-default-p is set to a + function. Thanks to Jun Inoue . + (closes: #488427) + + * Don't look for GNU to find etc/. Look for NEWS instead. Thanks to + "Bernhard Michler" for the report and Sven Joachim + for the fix. (closes: #478240) + + * Fix a problem in WoMan which caused it to raise an error for a number + of manpages. Thanks to Sven Joachim . (closes: #476223) + + -- Rob Browning Wed, 23 Jul 2008 20:56:33 -0700 + +emacs22 (22.2+2-2) unstable; urgency=medium + + * Fix debian-expand-file-name-dfsg and describe-gnu-project (C-h C-p). + Thanks to Valery V. Vorotyntsev . + (closes: #448391, #477215) + + * Fix an insecurity in vcdiff's temporary file handling + (CVE-2008-1694). Thanks to Moritz Muehlenhoff and + Steve Grubb. (closes: #476611) + + -- Rob Browning Sat, 26 Apr 2008 22:02:40 -0700 + +emacs22 (22.2+2-1) unstable; urgency=low + + * Move mh-e.texi here from the non-DFSG package because the license does + appear to be DFSG compatible. Thanks to Peter S Galbraith + . (closes: #433953) + + * Add Conflicts and Replaces emacs22-common-non-dfsg (<< 22.2+1-2) to + debian/control.in to handle move of mh-e. + + -- Rob Browning Sun, 20 Apr 2008 13:25:33 -0700 + +emacs22 (22.2+1-1) unstable; urgency=low + + * New upstream release. (closes: #473021, #474271) + + * Move dired-x.texi to the non-DFSG package because the license has + changed. + + * Update debian/copyright to reflect recent changes. + + * Update debian/dfsg-splitter for new upstream release. + + * Add libgif-dev to debian/control. Thanks to Sven Joachim + . (closes: #472419) + + -- Rob Browning Thu, 10 Apr 2008 18:41:02 -0700 + +emacs22 (22.1+1-3) unstable; urgency=low + + * Incorporate a patch to fix a vulnerability in the handling of file + local variables (CVE-2007-5795) (closes: #449008). Thanks to Drake + Wilson , and also thanks to Romain Francoise for + the 22.1+1-2.1 NMU. [rlb] + + * Support has been added for GNU/kFreeBSD. Thanks to Petr Salinger + (closes: #451178) + + * Incorporate a patch to fix a a stack-based buffer overflow in the + format function which can occur when dealing with high precision + values. The overflow could lead to arbitrary code execution + (CVE-2007-6109). Thanks to Nico Golde for the + 22.1+1-2.2 and 22.1+1-2.3 NMUs. The patch fixes both the CVE + (#455432) and a bug introduced by an incomplete initial patch + (#456235). + + * Don't override install-info anymore. (closes: #438695) + + * Fix a problem with auto save file names. Thanks to Sven Joachim + . (closes: #469017) + + * Fix the switch-to-buffer-other-frame function so that it returns the + new buffer. This also means that find-file-read-only-other-frame will + now correctly mark the new buffer as read only. Thanks to Sven + Joachim . (closes: #457539) + + -- Rob Browning Sun, 02 Mar 2008 14:22:35 -0800 + +emacs22 (22.1+1-2) unstable; urgency=low + + * Fix mail locking patch for Debian's non-Linux architectures. Thanks + to Michael Banck . (closes: #433816) [rlb] + + * Fix control file for binary NMUs. Thanks to Lior Kaplan + . (closes: #432957) [rlb] + + * Fix problem with --no-bitmap-icon with upstream patch. Thanks to Sven + Joachim . (closes: #433969) [rlb] + + * Add build dependency versions of quilt that include support for + "header". Thanks to Max Dmitrichenko + . (closes: #432695) [rlb] + + * Incorporate upstream fixes to Emacs manpage. Thanks to Sven Joachim + . (closes: #432732) [rlb] + + * Symlink etc/COPYING and lisp/COPYING to + /usr/share/common-licenses/GPL-2. Thanks to Milan Zamazal + for the report. (closes: #436810) [rlb] + + -- Rob Browning Tue, 21 Aug 2007 22:29:09 -0700 + +emacs22 (22.1+1-1) unstable; urgency=low + + * New upstream release. (closes: #427279) [rlb] + + * Change build dependency from libpng3-dev to libpng12-dev. + (closes: #424622) [rlb] + + * If allowed, create and remove non-flavor-specific + /usr/local/share/emacs/site-lisp. + + * Fix cc-mode local variable problem. Thanks to Sven Joachim + for forwarding the upstream patch. + (closes: #428898) [rlb] + + * Add desktop file for emacs22-gtk. (closes: #424069) [rlb] + + * Remove /var/games/emacs/ since Emacs doesn't use it unless + update-game-score is setuid and Debian's isn't. + (closes: #423948, #430533) [rlb] + + * New release restores python mode. (closes: #430553) [rlb] + + * Add /usr/share/info/emacs-22 to Info-default-directory-list before + /usr/share/info. (closes: #425924, #429526) [rlb] + + * Change the desktop file to only use the major version in the name, + rather than the full upstream version, so that the string won't change + from say 22.0.99 to 22.1. + + -- Rob Browning Fri, 06 Jul 2007 20:20:15 -0700 + +emacs22 (22.0.99+1-1) experimental; urgency=low + + * Update to 22.0.99. + + -- Rob Browning Sat, 12 May 2007 11:01:29 -0700 + +emacs22 (22.0.95+1-1) experimental; urgency=low + + * New emacs22 packages. + + * The debian/dfsg-splitter has been updated. [rlb] + + * Obsolete patches have been removed. [rlb] + + -- Rob Browning Sun, 11 Mar 2007 10:14:16 -0700 + +emacs21 (21.4a+1-5) unstable; urgency=low + + * Move man pages back to emacs21-common. (closes: #414321) [rlb] + - debian/rules + + -- Rob Browning Sat, 10 Mar 2007 16:16:15 -0800 + +emacs21 (21.4a+1-4) unstable; urgency=low + + * Merge useful bits from Jerome and my orphaned emacs22 tree (which + itself was based on Jérôme's snapshot tree) in preparation for + upcoming emacs22 branch. Many thanks to Jérôme. A partial summary of + these changes follows: + + Add debian/rules info_subdir variable. + + Modify desktop and menu files version. This approach should work for + normal versions, "Emacs 21.4a (X11)", and for snapshots, "Emacs + 2006-09-09 (X11)". See the menu_ver variable in debian/rules. + + Overhaul debian/rules to build all of the install trees at once and + then call the dh_* programs generically rather than calling them once + per package. [rlb] + + - emacsVER-bin-common.postinst + - emacsVER-bin-common.prerm + - emacsVER-common.postinst + - emacsVER-common.prerm + - emacsVER.desktop + - emacsVER.menu + - rules + + -- Rob Browning Sat, 3 Mar 2007 16:13:23 -0800 + +emacs21 (21.4a+1-3) unstable; urgency=high + + * Fix build failure on mipsel. + Thanks to Aurelien Jarno . + (closes: #401665) [Jérôme Marant] + - debian/patches/arch-mipsel.diff: set OUTPUT_ARCH to `mips' + instead of `mipsel'. + + * Changed FSF address in copyright file. [Jérôme Marant] + - debian/copyright.in + - debian/copyright + + -- Jerome Marant Thu, 04 Jan 2007 08:31:28 +0100 + +emacs21 (21.4a+1-2) unstable; urgency=low + + * Make both emacs21 and emacs21-nox packages suggest non-DFSG + packages and fix erroneous emacs21-common dependency on it + [Jérôme Marant] + - debian/control.in + - debian/control + + * Grab yow mode from the CVS trunk so it is now compatible with yow.lines + replacement which also comes from the CVS trunk. + (closes: #395501) [Jérôme Marant] + - debian/patches/yow-mode-from-cvs.diff: new patch. + - debian/patches/series: updated. + + * Properly handle ldapsearch output from OpenLDAP version 2 and above. + Thanks to both Joshua Judson Rosen and + Henrik Holmboe . + (closes: #381484) [Jérôme Marant] + - debian/patches/ldapsearch-output.diff: new patch. + - debian/patches/series: updated. + + * Mention license of both emacs.1 and etags.1 manpages and add a copy of + the GFDL to the copyright file (closes: #396875) [Jérôme Marant] + - debian/copyright.in + - debian/copyright: re-generated. + + * Fix generation of emacs21-common README.Debian. [rlb] + + -- Rob Browning Sat, 2 Dec 2006 11:45:44 -0800 + +emacs21 (21.4a+1-1) unstable; urgency=low + + * In accordance with the recent General Resolution + (http://www.debian.org/vote/2006/vote_001), move all non-DFSG files to + new packages that will be included in Debian's non-free section. The + debian/dfsg-splitter script has been used to split the upstream + archive. (closes: #207932) [rlb] + - debian/control.in + - debian/copyright.in + - debian/dfsg-splitter + - debian/emacs-common.README + - debian/patches/handle-dfsg-split.diff + - debian/patches/series + - debian/replacement/yow.lines.uu + - debian/rules + - debian/missing-file.dfsg: new template file used to generate + replacements for non-free files normally accessible through C-h + key bindings. Those files will be displayed if the original + ones are not available. + + * Acknowledge NMU. Thanks Marc Brockschmidt + (Closes: #381452) [Jérôme Marant] + + * Separate mipsel from mips autodetection in configure.in [Jérôme Marant] + - debian/patches/arch-mipsel.diff: update. + + * Split mips and mipsel ports into two separate patches [Jérôme Marant] + - debian/patches/arch-mips.diff: new file. Add mips-specific code + from arch-mipsel+mips.diff patch + - debian/patches/arch-mipsel.diff: add mipsel-specific code from + arch-mipsel+mips.diff patch + - debian/patches/arch-mipsel+mips.diff: remove. + + * Bump Standards-Version to 3.7.2 [Jérôme Marant] + - debian/control.in + + * Add a new dummy `emacs' package which depends on the latest + Emacs release (closes: #82687) + - debian/control.in: added new entry for `emacs' package. + - debian/control: re-generated. + - debian/emacs.*: renamed to debian/emacsVER.* + - debian/emacs-*.*: renamed to debian/emacsVER-*.* + - debian/rules: changed accordingly. + + * Remove erroneous semicolon character when reading XBM files. + Thanks to Jochen Voss . + (closes: #392651) [Jérôme Marant] + - debian/patches/xbm-read-erroneous-semicolon.diff: new file. + - debian/patches/series: updated. + + * Properly point to README.Debian.gz from Emacs NEWS file. + Thanks to Per Bojsen . + (closes: #389063) [Jérôme Marant] + - debian/patches/misc-unseparated.diff: updated. + + -- Rob Browning Wed, 25 Oct 2006 00:40:34 -0700 + +emacs21 (21.4a-6.2) unstable; urgency=low + + * Non-maintainer brown paper bag release. + * Apply patch from 21.4a-6.1 properly, somehow quilt hates me. + + -- Marc 'HE' Brockschmidt Wed, 27 Sep 2006 08:30:33 +0200 + +emacs21 (21.4a-6.1) unstable; urgency=low + + * Non-maintainer upload. + * debian/patches/arch-mipsel+mips.diff: + Add patch from Max Kellermann (updated by + Thiemo Seufer ) to fix segfaults on mips + and mipsel. Thanks for the hard work! (Closes: #381452) + + -- Marc 'HE' Brockschmidt Wed, 27 Sep 2006 00:13:30 +0200 + +emacs21 (21.4a-6) unstable; urgency=low + + * When we create an empty aclocal.m4 after patching (to get around + quilt's use of patch -E), make the timestamp match the timestamp of + configure.in, so that we won't accidentally re-run autoconf given the + dependency in Makefile.in. [rlb]. + - debian/rules + + -- Rob Browning Sun, 14 May 2006 15:24:35 -0700 + +emacs21 (21.4a-5) unstable; urgency=low + + * Don't include dpatch.make in debian/rules since the package no longer + depends on dpatch. Thanks to Romain Francoise + . (closes: #367177) [rlb] + - debian/rules + + -- Rob Browning Sun, 14 May 2006 10:18:04 -0700 + +emacs21 (21.4a-4) unstable; urgency=low + + * Migrate from dpatch to quilt and update generation of README. [rlb] + - debian/README.in + - debian/rules + - debian/control.in + - debian/patches/* + + * Change occurrence of "find ... -perm +u+x" to "find ... -perm /u+x". + The former is no longer handled the way it used to be, and *doesn't* + find all files with execute permission. Thanks to François Fleuret + for pointing out the initial problem. [rlb] + - debian/rules + + * Replace $(pwd) with $(CURDIR) in debian/rules. + - debian/rules + + * Remove PACKAGE variable. + - debian/rules + + * Arrange DEB_ vars as recommended by + /usr/share/doc/autotools-dev/README.Debian.gz and do the same with + DEB_HOST_ARCH and DEB_HOST_GNU_CPU. [rlb] + - debian/rules + + * Use DEB_HOST_GNU_TYPE for the value of target rather than + DEB_BUILD_GNU_TYPE. [rlb] + - debian/rules + + * Add $(src_name) and $(flavor) and use them. [rlb] + - debian/rules + + * Remove show-upstream-diffs target (use check-diff instead). [rlb] + - debian/rules + + * Rename orig_tgz and orig_tgz_dir variables to deb_orig_tgz and + deb_orig_tgz_dir. [rlb] + - debian/rules + + * Lowercase local makefile variable names. [rlb] + - debian/rules + + * Migrate to debhelper (while consulting Jérôme Marant's work on + emacs-snapshot). There may still be a bit to do. [rlb] + - debian/rules + - debian/changelog + - debian/compat + - debian/control + - debian/control.in + - debian/emacs-bin-common.postinst + - debian/emacs-bin-common.postrm + - debian/emacs-bin-common.prerm + - debian/emacs-common.README + - debian/emacs-common.docs + - debian/emacs-common.postinst + - debian/emacs-common.prerm + - debian/emacs-el.prerm + - debian/emacs.README + - debian/emacs.menu + - debian/emacs.postinst + - debian/emacs.postrm + - debian/emacs.preinst + - debian/emacs.prerm + - debian/rules + - debian/README.binpkg.in (moved to debian/emacs.README) + - debian/README.in (moved to debian/emacs-common.README) + - debian/build-binary-pkg (removed - now handled in debian/rules) + - debian/menu.in (moved to debian/emacs.menu) + + * Change nominal_ver computation to match code in configure.in. [rlb] + - debian/rules + + * Add libxaw7-dev dependency to make sure we get that instead of + libxaw8-dev. Thanks to Tollef Fog Heen . + (closes: #365597) [rlb] + - debian/control.in + + * Apply an upstream patch to fix an mmap related Hurd build problem. + Thanks to Michael Banck . (closes: #347554) [rlb] + - debian/patches/series + - debian/patches/hurd-mmap.diff + + -- Rob Browning Sat, 13 May 2006 16:24:05 -0700 + +emacs21 (21.4a-3) unstable; urgency=low + + * Disable support for the ppc64 architecture: the patch breaks the + powerpc support and does not work on ppc64 any more anyway. + (closes: #329459) [Jérôme Marant] + - debian/patches/00list: disable arch-ppc64 patch. + - debian/patches/autofiles.dpatch: regenerated. + + -- Rob Browning Sun, 2 Oct 2005 19:00:13 -0700 + +emacs21 (21.4a-2) unstable; urgency=low + + * Apply patch applying modifiers to multibyte-char keys. Thanks to + Martin Stjernholm (closes: #309963) [Jérôme Marant] + - debian/patches/multibyte-char-key-modifiers.dpatch: new file. + - debian/00list: updated. + + * Apply patch supporting the ppc64 architecture. This is a slightly + modified patch derived from the Emacs CVS mainline. + (closes: #300368) [Jérôme Marant] + - debian/patches/arch-ppc64.patch: new file. + - debian/00list: updated. + + * Add real dependency as an alternative to the libtiff-dev build + dependency in order for the build to be deterministic. + (closes: #311074) [Jérôme Marant] + - debian/control.in: add libtiff4-dev as alternative libtiff-dev + build dependency. + - debian/control: regenerated. + + * Bump Standards-Version to 3.6.2. [Jérôme Marant] + - debian/control.in + - debian/control: regenerated. + + * Use the "kitchen sink" bitmap icon when iconifying the Emacs window. + (closes: #309930) [Jérôme Marant] + - debian/menu.in: pass the `-i' option to the command launching Emacs + under X11. + - debian/emacs.desktop: likewise. + + * Work around bug in Xorg which makes AltGr incorrectly recognized. + This patch has been backported from Emacs CVS trunk. [Jérôme Marant] + - debian/patches/xorg-altgr-fix.dpatch: new file. + - debian/00list: updated. + + * Apply patch preventing an infinite loop in whitespace.el if kill-read-only + is set to t. Thanks to Romain Francoise + (closes: #273123) [Jérôme Marant] + - debian/patches/whitespace-readonly-infloop.dpatch: new file. + - debian/00list: updated. + + -- Rob Browning Sat, 17 Sep 2005 23:39:52 -0700 + +emacs21 (21.4a-1) unstable; urgency=medium + + * New upstream release. (closes: #294313) [Jérôme Marant] + - debian/patches/movemail-pop-fmt-vulnerability.dpatch: removed since + it has been applied upstream. + + * Apply patch from Romain Francoise making PCL-CVS + compliant with recent versions of CVS. (closes: #291221) [Jérôme Marant] + - debian/patches/pcl-cvs-format.dpatch: new file. + - debian/00list: updated. + - debian/control: tightened dependency on dpatch (>= 2.0.9). + + * Add MIME type to desktop file. (closes: #296618) [Jérôme Marant] + - debian/emacs.desktop: added MimeType entry. + + * Apply patch supporting the AMD64 architecture. This is a slightly + modified patch derived from the Emacs CVS mainline. Thanks to + Goswin von Brederlow and + amd64 porters. (closes: #248796) [Jérôme Marant] + - debian/patches/arch-amd64.patch: new file. + - debian/00list: updated. + + * Hard code leim version in copyright.in for now. with 21.4a the emacs + tar.gz name changed, but the leim archive name didn't. [rlb] + - debian/copyright.in + - debian/copyright + + * Remove prebuild target from debian/rules. Instead, just issue + instructions to the user. [rlb] + - debian/rules + + * Fix invocation of wc -l when counting fns-*.el files. [rlb] + - debian/rules + + * Use dpatch for the autotool related diff rather than generating and + applying a diff manually. What was the debian/autofiles.diff is now + handled via debian/patches/autofiles.dpatch. Also, we no longer try + to automatically generate the diff when needed. Instead, the diff + must be generated manually via "debian/rules autofiles-sync". + + The earlier approach was broken because dpatch files that + autofiles.diff depended on could end up later in the Debian diff (and + hence have newer timestamps). This would cause an unexpected run of + aclocal, etc. and break the buildds. If we ever want to re-automate + generation of the autofiles diff, we'll need to use dpatch md5 sigs + (or similar) rather than timestamps. (closes: #297796) [rlb] + - debian/autofiles.diff: removed + - debian/patches/00list: added autofiles + - debian/patches/autofiles.dpatch: new + - debian/rules: updated + + -- Rob Browning Tue, 15 Mar 2005 11:00:04 -0600 + +emacs21 (21.3+1-9) unstable; urgency=high + + * Modify debian/rules to support using an arch source repository and an + archive arrangement somewhat similar to, but not compatible with + arch-buildpackage's. [rlb] + - debian/rules + + * Applied patch to fix mailspool pop format string vulnerability + (CAN-2005-0100). [rlb] + Thanks to Max Vozeler . + - debian/patches/movemail-pop-fmt-vulnerability.dpatch + + -- Rob Browning Thu, 3 Feb 2005 21:02:03 -0600 + +emacs21 (21.3+1-8) unstable; urgency=medium + + * Apply patch allowing Emacs to properly interpret logo keys as Meta + rather than Meta+Super+Hyper. This problem has been showing up since + latest XFree86 and Xorg introducted `fake keys'. + Thanks to Denis Barbier + (closes: #255286, #274103) [Jérôme Marant] + - debian/patches/xfree86-4.3-modifiers.dpatch: new file + - debian/patches/00list: updated. + + * Apply patch fixing long-standing memory leak in decode-coding-region + and similar routines. Thanks to Florian Weimer . + (closes: #273919) [Jérôme Marant] + - debian/patches/coding-region-leak.dpatch: new file. + - debian/patches/00list: updated. + + * Apply patch tightening permissions of local backup copies of remote + files. Thanks to Michael Albinus . + (closes: #274427) [Jérôme Marant] + - debian/patches/remote-files-permissions.dpatch: new file. + - debian/patches/00list: updated. + + -- Rob Browning Sat, 16 Oct 2004 11:10:32 -0500 + +emacs21 (21.3+1-7) unstable; urgency=medium + + * set recompile against libtiff4-dev and upload with + urgency=medium. (closes: #262828) [rlb] + - debian/changelog + + -- Rob Browning Tue, 3 Aug 2004 11:34:43 -0500 + +emacs21 (21.3+1-6) unstable; urgency=low + + * fix debian/README rendering problem. [rlb] + + * Stop provinding www-browser since the w3-el-e21 package provides it + now. [Jérôme Marant] + - debian/control.in: remove www-browser provides for emacs and + emacs-nox. + - debian/control: synced. + + * Fixed installation of .desktop entry. [Jérôme Marant] + - debian/build-binary-pkg: fixed typo. + + * Set value of the auto-save-file-name-transforms variable at run-time + in order to override its build-time value. + (closes: #160615, #167295, #175346, #241826, #250676, #178792) + [Jérôme Marant] + - debian/patches/startup-auto-save-file-name-transforms.dpatch: new file. + - debian/patches/00list: updated. + + * Add Python byte-compiled file extensions to completion-ignore-extensions + variable. (closes: #177276) [Jérôme Marant] + - debian/patches/python-completion-ignored-extensions.dpatch: new file. + - debian/patches/00list: updated. + + * Fixed removal of alternatives + (closes: #251822, #206901, #241820, #163034) [Jérôme Marant] + - debian/emacs-bin-common.prerm + + * Add a slave alternative for "editor" manpage. + Thanks to Daniel Kraft . (closes: #255639) [Jérôme Marant] + - debian/emacs.postinst + + * Apply a 2003-06-21 patch from upstream CVS to fix a non-interactive + signal handling problem that could cause Emacs to die prematurely as + the result of a SIGIO or SIGHUP. (closes: #253887) [rlb] + - debian/patches/fix-batch-mode-signal-handling.dpatch + - debian/patches/00list + + * Add warning message to prepare-release explaining that you have to run + it as a normal user (not root). [rlb] + - debian/rules + + -- Rob Browning Mon, 26 Jul 2004 10:27:10 -0500 + +emacs21 (21.3+1-5) unstable; urgency=low + + * Apply patch allowing emacsclient to handle ALTERNATE_EDITOR properly + when the command is run without any parameter [Jérôme Marant] + (closes: #219658) + - debian/patches/emacsclient-alternate-editor.dpatch: new file. + + * Provide the `editor' virtual package. [Jérôme Marant] + (closes: #66243, #90154, #158807) + - debian/control.in: emacs and emacs-nox now provide the `editor' + virtual package. + - debian/control: synchronized with debian/control.in. + - debian/emacs.postinst: adding an `editor' alternative with a priority + of 0 as discussed in + http://lists.debian.org/debian-policy/2000/debian-policy-200006/msg00122.html + - debian/emacs.prerm: removing the `editor' alternative on package + removal. + + * Added automatic switching to UTF-8 encoding when editing the debian + changelog file. [Jérôme Marant] + - debian/changelog: added Emacs local variables forcing coding + to UTF-8. + + * Fix handling of menu entry for text version of Emacs [Jérôme Marant] + (closes: #221171) + - debian/menu.in: call the text version of emacs with the `-nw' + parameter. + + * Install the emacsclient manpage [Jérôme Marant] (closes: #222767) + - debian/build-common-pkg: install missing emacsclient manpage. + - debian/emacs-common.postinst: install alternative for emacsclient + manpage. + + * Install .desktop entry in order to make Emacs easy to start in + both GNOME and KDE. Thanks to Adam C Powell IV + [Jérôme Marant] (closes: #233711) + - emacs.desktop: new template file for desktop entries + - debian/rules: generate desktop file from emacs.desktop template + and install it for emacs21. + + * test -n "${major_ver}" in a few places so that we don't accidentally + generate bad output files from our .in files. [rlb] + - debian/rules + + * truncate aclocal.m4 during autofiles-sync so that old bits won't kill new + autoconf run. Also ignore autom4te.cache when generating + autofiles.diff. [rlb] + - debian/rules + + * fix bug in prepare-release autodiff prompt handling. [rlb] + - debian/rules + + * update configure.in for newer autoconf versions. [rlb] + - autoconf-updates.dpatch + + * add an emacsXY-bin-common package containing all the architecture + specific bits, so that emacsXY-common can be architecture independent. + This should save many megabytes * architectures in the debian pool. + [rlb] (closes: #232888, #233345) + - debian/rules: move some build-* code from debian/ scripts to rules + and adjust to build emacsXY-bin-common. + - debian/emacs-common.postinst debian/emacs-common.prerm: some code + moved to new emacs-bin-common scripts. + - debian/emacs-common.postrm: deleted. + - debian/emacs-bin-common.postinst: new file. + - debian/emacs-bin-common.prerm: new file. + - debian/emacs-bin-common.postrm: new file. + - debian/build-common-pkg: deleted - code now in debian/rules. + - debian/build--pkg: deleted - code now in debian/rules. + - debian/emacs-el.postinst: deleted - was empty. + - debian/control.in: add emacsXY-bin-common and adjust other entries. + - debian/fix-debian-scripts: deleted - no longer used. + - debian/build-binary-pkg: adjusted to handle more of the common code. + + * Add support for linux 2.6 to ACPI in lisp/battery.el. Thanks to + Mario Lang [Jérôme Marant] (closes: #228658) + - debian/patches/battery-acpi-support.dpatch: updated. + + * Generate md5sums file for every package [Jérôme Marant] (closes: #22590) + - debian/rules: generate md5sums file just before building packages. + - debian/build-binary-pkg: likewise. + + * no point in byte-compiling fns-*.el according to upstream authors + (closes: #189277) + + * fix configure args (--build alone doesn't seem to work anymore). [rlb] + - debian/rules + + * re-enable gif support via libungif. [rlb] + - debian/rules + + * re-enable toolkit scrollbars, but make it really easy for people to + disable them in debian/rules. Search for + --without-toolkit-scrollbars. [rlb] + - debian/rules + - debian/README.in + + * fix problem with upgrades by adding emacs21-common (<< 21.3+1-4) to + Replaces for the common packages. [rlb] + - debian/control.in + - debian/control + + -- Rob Browning Tue, 6 Apr 2004 18:07:38 -0500 + +emacs21 (21.3+1-4) unstable; urgency=medium + + * debian/changelog: converted to UTF-8 as per Policy. [Jérôme Marant] + * debian/control.in: + - Bumped Standards-Version to 3.6.1. [Jérôme Marant] + - Added versioned build-dependency on dpatch >= 1.23 since this version + no longer requires numerial prefixes to dpatches. [Jérôme Marant] + * debian/patches/*.dpatch: removed numerical prefix since the patch order + is specified in debian/patches/00list. [Jérôme Marant] + * debian/patches/hurd-libio-glibc.dpatch: new patch allowing Emacs + to be built on Hurd systems using a libio-based glibc. + Thanks to Markus Brinkmann . + (closes: #143220) [Jérôme Marant] + * debian/patches/battery-acpi-support.dpatch: new patch adding ACPI + support to lisp/battery.el. Thanks to Mario Lang . + (closes: #208812) [Jérôme Marant] + * debian/patches/scroll-margin.dpatch: new patch preventing emacs + to hang with a non-0 scroll-margin set. + (closes: #175658) [Jérôme Marant] + * debian/patches/save-buffer.dpatch: new patch fixing a bug which + makes a file being removed when the coding system of its buffer + has changed and saving the changes was canceled. + (closes: #194171) [Jérôme Marant] + * debian/patches/00list: updated with respect to new patches. + [Jérôme Marant] + * debian/menu.in: + - Added hints to menu entries. (closes: #144282) [Jérôme Marant] + - Changed titles for both text and X11 entries in order to + differenciate them. (closes: #197527, #188598) [Jérôme Marant] + * debian/patches/browse-url.dpatch: + - Updated patch fixing a wrong call to galeon. Thanks to + Mikael Hedin . (closes: #208206) [Jérôme Marant] + - Updated patch fixing browse-url's invocation of Mozilla. + Thanks to Jeff Sheinberg , + Martin Pool and KATO Kazuyoshi . + (closes: #148408, #216067) [Jérôme Marant] + * Use -O1 rather than -O2 on m68k. Fixes a build failure (looks like a + broken byte compiler) with newer versions of gcc. (closes: #207580) + + -- Rob Browning Fri, 31 Oct 2003 00:00:10 -0600 + +emacs21 (21.3+1-3) unstable; urgency=low + + * create debian/stmap it doesn't exist. (closes: #210802) + + -- Rob Browning Sat, 13 Sep 2003 14:49:18 -0500 + +emacs21 (21.3+1-2) unstable; urgency=low + + * add back accidentally removed dpatch Build-Depends. (closes: #210627) + + -- Rob Browning Fri, 12 Sep 2003 10:30:21 -0500 + +emacs21 (21.3+1-1) unstable; urgency=low + + * repackage without .elc files since we regenerate all of them anyway. + This will save space, and will also allow us to use dpatch in a + straightforward way. + * modify debian/rules computation of version numbers to handle + (i.e. ignore) the +1 in 21.3+1. + * rework to use dpatch and to patch/unpatch the debian source in-place + rather than using a debian/build-src copy of the whole source tree. + * incorporated patch (500-detect-coding-iso2022.dpatch) to fix raw-text + coding problem. Thanks to Kenichi Handa . + (closes: #198736) + + -- Rob Browning Thu, 11 Sep 2003 23:15:44 -0500 + +emacs21 (21.3-2) unstable; urgency=low + + * Compile --without-toolkit-scroll-bars for now (my pref, and to avoid + xaw3d issues for the moment). + * Update copyright to reflect documentation licenses. (closes: #161500) + + -- Rob Browning Wed, 13 Aug 2003 08:53:35 -0500 + +emacs21 (21.3-1) unstable; urgency=low + + * new upstream version. + + -- Rob Browning Wed, 23 Apr 2003 13:16:06 -0500 + +emacs21 (21.2-6) unstable; urgency=low + + * changed sort behavior for x-vs-no-x fix in cus-dep.el based on + suggestion from Matt Kraai . (closes: #166139) + * finish breaking up most of the debian/patch/* files. + * set up automatic generation for autofiles.diff which contains all the + diffs to automatically generated files and is applied after all of the + debian/patch/*.diff files. + * add an apply-patches-upto command so it's easier to create partially + patched trees for editing. + + -- Rob Browning Thu, 6 Feb 2003 18:12:41 -0600 + +emacs21 (21.2-5) unstable; urgency=low + + * fix bug in rules and binary-pkg generation. (closes: #164770) + * fix problem with config.sub and config.guess updates. (closes: #164763) + * time to stop creating the /usr/doc symlinks... + + -- Rob Browning Tue, 15 Oct 2002 16:34:52 -0500 + +emacs21 (21.2-4) unstable; urgency=low + + * create debian/patches/ and start migrating to represent + changes as patches against the upstream source. Don't edit the main + tree anymore. + * rework tree and packaging to have emacs21-common, emacs21, and + emacs21-nox packages with emacs21-common containing nearly all the + data. + + -- Rob Browning Sat, 12 Oct 2002 15:09:37 -0500 + +emacs21 (21.2-3) unstable; urgency=low + + * Update emacs21-nox package description. + + -- Rob Browning Wed, 29 May 2002 14:04:57 -0500 + +emacs21 (21.2-2) unstable; urgency=low + + * fix control file priorities to match overrides. + * fix rules to handle autotools more correctly. See + /usr/share/doc/autotools-dev/README.Debian.gz for details. + (closes: #139998) + * firewall, headless box, and anti-X users everywhere rejoice! + Introducing emacs21-nox package :> + + -- Rob Browning Tue, 28 May 2002 12:09:48 -0500 + +emacs21 (21.2-1) unstable; urgency=low + + * new upstream release. + * move outline of Debian specific Emacs changes to + /usr/share/doc/*/README.Debian.gz.x + + -- Rob Browning Fri, 22 Mar 2002 11:41:17 -0600 + +emacs21 (21.1-9) unstable; urgency=low + + * fix control.in to use ${Source-Version}. (closes: #138994) + + -- Rob Browning Mon, 18 Mar 2002 21:54:47 -0600 + +emacs21 (21.1-8) unstable; urgency=low + + * Fix .texi problems with upstream patch. (closes: #138236) + + -- Rob Browning Sun, 17 Mar 2002 11:58:59 -0600 + +emacs21 (21.1-7) unstable; urgency=high + + * fix vc-path to be correct for a Debian system. (closes: #120079) + * re-add lost hppa and s390 patches. (closes: #107251) + + -- Rob Browning Thu, 6 Dec 2001 14:10:45 -0600 + +emacs21 (21.1-6) unstable; urgency=medium + + * modify order in browse-url.el. + * added upstream iso-acc.el patch to fix accent bug. (closes: #119852) + * fix ppc nocombreloc bug with upstream patch. (closes: #117557) + + -- Rob Browning Tue, 4 Dec 2001 08:43:38 -0600 + +emacs21 (21.1-5) unstable; urgency=low + + * Run autoconf to remove stale ppc code. (closes: #119189) + * Write new browse-url.el code with support for galeon and to default to + searching for a suitable browser, free browsers first. (closes: #116822) + + -- Rob Browning Tue, 13 Nov 2001 09:51:31 -0600 + +emacs21 (21.1-4) unstable; urgency=low + + * Really fix alternatives problem this time. + + -- Rob Browning Fri, 9 Nov 2001 10:24:49 -0600 + +emacs21 (21.1-3) unstable; urgency=low + + * Fix but in grep in postinst. (closes: #117251, #117256, #117415, #118792) + * Remove vestigal ppc bits and add upstream patch for ppc nocombreloc + problem. (closes: #117557) + * fix bug in upstream-files.tar handling. + * don't configure gif support until our libungif is new enough. See bug + #117729. + * Fix manpage to list correct default window size. (closes: #118641) + + -- Rob Browning Thu, 8 Nov 2001 21:15:20 -0600 + +emacs21 (21.1-2) unstable; urgency=low + + * change to priority optional. + * use xaw3d scrollbars after checking upstream preferences. + (closes: #116831, #116911, #116638) + * added some build-depends. (closes: #116981) + * fixed typo in NEWS. (closes: #116814) + * fixed alternatives bug in postinst/prerm for emacsclient (closes: #116915) + + -- Rob Browning Thu, 25 Oct 2001 16:02:45 -0500 + +emacs21 (21.1-1) unstable; urgency=low + + * New emacs21 packages. Many changes -- reviewed all Debian files. + + -- Rob Browning Thu, 18 Oct 2001 17:28:03 -0500 + +emacs20 (20.7-10) unstable; urgency=medium + + * Add arch header for mipsel and fix configure.in and + configure. (closes: #103959) + + -- Rob Browning Mon, 23 Jul 2001 09:23:06 -0500 + +emacs20 (20.7-9) unstable; urgency=low + + * Added more Build-Depends. (closes: #101832) + * Disable ralloc on Hurd. Thanks to Robert Bihlmeyer + . (closes: #101926) + + -- Rob Browning Tue, 10 Jul 2001 12:48:22 -0500 + +emacs20 (20.7-8) unstable; urgency=low + + * Added ia64 patches from Bdale Garbee for ia64.h. + (closes: #90518) + * Added Build-Depends on mailx for now (though this is *wrong* for the + long run -- I need to fix my fakemail handling). + (closes: #95903, #96761) + * Fix fakeroot sgid problem (move movemail chmod +s in debian/rules). + * Remove emacs' overzealous dir.gz file. + * Shrink gnu.xpm to 32x32 and make it the menu icon. (closes: #20253, #21310) + * Update manpage to not refer to kitchen sink anymore -- though with + emacs21, we're going to move back to using whatever they choose. + (closes: #81682) + + -- Rob Browning Wed, 13 Jun 2001 23:56:16 -0500 + +emacs20 (20.7-7) unstable; urgency=low + + * Fixed reftex-info problem. (closes: #44837). + * Fix install-strip target in Makefile.in. Thanks to + Kalle Olavi Niemitalo . (closes: #51348) + + -- Rob Browning Sat, 5 May 2001 23:50:50 -0500 + +emacs20 (20.7-6) unstable; urgency=low + + * Fix improper usage of dpkg-statoverride and make sure movemail is set + up right. (closes: #95953) + * Fix bad manpage location in postinst update-alternatives call. + * Fix bad .so in ctags manpage (closes: #88231, #45317, #65017, #74570) + + -- Rob Browning Sat, 5 May 2001 09:47:40 -0500 + +emacs20 (20.7-5) unstable; urgency=low + + * configure.in: add detection of CONF_MAIL_PROGRAM_NAME. + * lib-src/fakemail.c: use CONF_MAIL_PROGRAM_NAME when appropriate + (closes: #72103) -- need to forward upstream. + * Add "modified by Debian" clause to (emacs-version) at RMS's request. + * Start Debian modifications section in copyright file as per policy. + * Add build fixes for hurd (closes: #78461). Changes suggested by + Marcus.Brinkmann@ruhr-uni-bochum.de. Thanks. + * Switch from Debian sendmail.el hack to Francesco's suggestion of + setting mail-from-style to 'system-default by default at startup + (closes: #35128). This allows the user to override when desired in + the normal way. This should be discussed with the upstream + maintainers. They may be amenable to making this the default on + Debian systems. + * add dependency on dpkg (>= 1.9.0) for new install-info. + * info pages should finally work right (or at least closer to right). + They're now installed in /usr/share/info/emacs-20/ under their normal + names, and install-info can add the appropriate (emacs-20/emacs), + etc. entries to /usr/share/info/dir. This hopefully closes a bunch of + old bugs. + (closes: #64994, #64512, #64025, #62155, #59332, #51163, #40443) + * No more files in /usr/doc. (closes: #91454, #63768) + * /usr/man moved to /usr/share/man. (closes: #91149) + * This should be fixed, in addition we've switched to dpkg-statoverride + (closes: #73007) + * /usr/share/info/dir.gz should be gone. + (closes: #75594, #68551, #65012) + + -- Rob Browning Sun, 29 Apr 2001 22:03:33 -0500 + +emacs20 (20.7-4) unstable frozen; urgency=low + + * Upload to unstable *and* frozen since this fixes outstanding grave + bugs. + + -- Rob Browning Thu, 27 Jul 2000 16:21:15 -0500 + +emacs20 (20.7-3) unstable; urgency=low + + * Change code to rebuild *all* the install tree .elc files at build + time. This should fix the grave problems with gnus trashing mail at + the expense of more CPU at build time. + + -- Rob Browning Wed, 19 Jul 2000 20:27:27 -0500 + +emacs20 (20.7-2) frozen unstable; urgency=low + + * Revert to setting debian-emacs-flavor in startup.el as per recent + flip-flop in debian-emacs-policy :< This was a *tiny* source change, + and definitely has to go into frozen - too much breaks otherwise. + + -- Rob Browning Tue, 20 Jun 2000 11:31:29 -0500 + +emacs20 (20.7-1) frozen unstable; urgency=low + + * New upstream bug-fix version. Fixes security bugs, among others. + * Removed some now redundant Debian patches. + + -- Rob Browning Sat, 17 Jun 2000 12:59:48 -0500 + +emacs20 (20.6-3) unstable frozen; urgency=medium + + * Temp fix for alpha corruption problem in cm/src.h + src/termcap.c, src/terminfo.c, and src/sysdep.c (forwarded bug 63993). + + -- Rob Browning Mon, 12 Jun 2000 18:55:22 -0500 + +emacs20 (20.6-2) frozen unstable; urgency=low + + * Make sure info files get registered after /usr/share migration. + + -- Rob Browning Fri, 12 May 2000 15:30:02 -0500 + +emacs20 (20.6-1) frozen unstable; urgency=low + + * Let emacsen-common handle setting debian-emacs-flavor and modify + "Depends:" accordingly. + * Maintainer release of 20.6 - fixes same issues as 20.6-0.1, so it + should go into frozen. + * Move info files to /usr/share/info. + * Make sure .elc files for .el files we've modified are *always* rebuilt. + * Add new unexelf.c from Gerd Moellmann . Without this, + emacs20 will *not* build on either frozen or unstable x86 machines. + + -- Rob Browning Fri, 12 May 2000 11:00:33 -0500 + +emacs20 (20.6-0.1) frozen unstable; urgency=low + + * Non-maintainer release. + * New upstream bug fix release (closes:#60931). + * ARM support merged upstream. + * Add security patches from RUS-CERT posting on BugTraq. + * postinst: Use 2775 as directory permissions in /usr/local (closes:#59919) + + -- Joel Klecker Wed, 26 Apr 2000 11:26:28 -0700 + +emacs20 (20.5a-2) unstable; urgency=low + + * Check in a bogus modification to all the .el files that we modified + before 20.5a so that new .elc files with our changes will be generated + when we build. This must be done every time an upstream change is + merged in. + + -- Rob Browning Tue, 28 Dec 1999 19:51:14 -0600 + +emacs20 (20.5a-1) unstable; urgency=high + + * Upstream version number is just fine (20.5a *is* newer than 20.5). + Switch to use it. + + -- Rob Browning Wed, 22 Dec 1999 11:12:44 -0600 + +emacs20 (20.4.pre20.5a-1) unstable; urgency=high + + * New upstream version, including some Y2K fixes. + * Use weird version to avoid epochs. This is upstream 20.5a. + + -- Rob Browning Wed, 22 Dec 1999 00:16:52 -0600 + +emacs20 (20.4-3) unstable; urgency=low + + * Fix mistake in this file. Fix bug number in architecture + dependency "closes" in last revision. + * Powerpc configure.in patch from Susumu OSAWA . + (Should close bug 48997, but marked forwarded instead until patch is + resolved upstream.) + * Jargon problems apparently fixed. (closes: #31103 #37030) + * Gnus printing problems apparently fixed (closes: #20760) + * Fix manpage to refer to more accurate Debian file locations. + (closes: #35267) + * cperl-mode problem apparently fixed. (closes: #46739) + * Fix build stripping problem (use INSTALL_STRIP=-s rather than + INSTALL_PROGRAM="install -s"). + + -- Rob Browning Sat, 4 Dec 1999 19:24:07 -0600 + +emacs20 (20.4-2) unstable; urgency=low + + * Modify mail-spool-directory/movemail patch in preparation for upstream + inclusion. + * Fix architecture dependency. (closes: #48997) + + -- Rob Browning Fri, 12 Nov 1999 17:59:01 -0600 + +emacs20 (20.4-1) unstable; urgency=low + + * New upstream version. + * I decided to go ahead and get this out without the major overhaul + that's coming, but I'm going to be working more tightly the core + upstream developers from now on, so there will be some more + substantial changes soon, including getting rid of more Debianisms and + double checking all our current patches. + * Fix movemail liblockfile detection to be non-Debian specific + (currently working out the appropriate upstream patch (see etc/NEWS)). + * Fix emacs to support a --with-mail-spool-directory configure option and to + automagically detect the right answer most of the time without it + (currently working out the appropriate upstream patch (see etc/NEWS)). + * Add the lisp-level variable mail-spool-directory which always contains + the location of the mail spool, and hack movemail, nnmail, rmail, and + friends to use it (currently working out the appropriate upstream + patch (see etc/NEWS)) . + * hexl-mode bug fixed upstream. (closes: #21762) + + -- Rob Browning Sat, 30 Oct 1999 13:24:39 -0500 + +emacs20 (20.3-11) unstable; urgency=low + + * Fix liblockfile version skew. (closes: #43803 #45123) + + -- Rob Browning Thu, 23 Sep 1999 13:27:00 -0500 + +emacs20 (20.3-10) unstable; urgency=low + + * Restructure debian/rules to build -el in binary-indep + (closes: #26761) + * Add emacsclient.1 manpage submitted ages ago. (closes: #22463) + * Handle duplicate DOC files (closes: #27668) + * Switch to gnu icon from old B&W drippy sink (closes: #33260) + + -- Rob Browning Tue, 6 Jul 1999 23:21:44 -0500 + +emacs20 (20.3-9) unstable; urgency=low + + * Added HURD patch from Marcus Brinkmann . + (closes: #38571). + * Backed out (global-set-key [delete] 'delete-char) modification + (Ref: #26366). This is too controversial (think cross-platform) + and needs to be resolved by the Debian Keyboard Czar in concert with + others. For now we revert to the upstream behavior... + * Add /usr/share/info to info search path (closes: #38285). + + -- Rob Browning Fri, 11 Jun 1999 00:43:51 -0500 + +emacs20 (20.3-8) unstable; urgency=low + + * Added patch to emacs.c from Wolfram Gloger + to fix exit segfaults. + (closes: #37745) + * Fixed suidregister inconsistency between postinst and postrm + (closes #36845) + + -- Rob Browning Sun, 30 May 1999 14:38:51 -0500 + +emacs20 (20.3-7) unstable frozen; urgency=low + + * Needed to go to frozen too: --print-architecture was an important + bug. Should be OK since other fixes since -5 are minor and + important. + * Add conflict with w3-el (as per Ben Pfaff's + request). (closes: #30413). + * Undo broken (and unneeded) "fix" for suidregister call in postrm. + + -- Rob Browning Thu, 28 Jan 1999 14:49:27 -0600 + +emacs20 (20.3-6) unstable; urgency=low + + * Use --print-installation-architecture rather than --print-architecture + (closes: #28177). + * Remove "#undef SIGIO" from m/arm.h as indicated by David Welton + (closes: #31279). + * Fix call to suidunregister (I didn't realize that it can't take + multiple file arguments) (closes: #21243 #26886). + + -- Rob Browning Wed, 27 Jan 1999 11:50:14 -0600 + +emacs20 (20.3-5) frozen unstable; urgency=low + + * Added NetWinder patches (closes: #28277). (Thanks to David Welton) + * Rebuilt emacs20-el so the versions coincide. In the future, people + need to be sure to build *both* binary packages when doing a + non-maintainer binary release. (This fix justifies inclusion into + frozen). + + -- Rob Browning Sun, 1 Nov 1998 20:14:36 -0600 + +emacs20 (20.3-4) unstable; urgency=low + + * Fix gnus to default to /var/spool/mail rather than /usr/spool/mail for + mailbox locations (closes: #21364). + + -- Rob Browning Sat, 17 Oct 1998 14:28:45 -0500 + +emacs20 (20.3-3) unstable; urgency=low + + * Fixed leim. All the input methods should work now (closes: #27398). + * Made (global-set-key [delete] 'delete-char) the default (closes: #26366). + * Fix ownership on emacs20-el files (closes: #27398). + + -- Rob Browning Tue, 13 Oct 1998 16:57:51 -0500 + +emacs20 (20.3-2) unstable; urgency=low + + * Added 20.2 patches for powerpc. I omitted the patches to the + following files because it looks like equivalent fixes have already + made it into 20.3. If anyone who understands that code better knows + differently, please let me know. The rest of the patches applied + cleanly. + src/callproc.c.rej + src/dired.c.rej + src/fileio.c.rej + src/process.c.rej + src/regex.c.rej + I also modified src/m/powerpc.h to fix problems calling the ldscript. + + -- Rob Browning Mon, 7 Sep 1998 18:20:41 -0500 + +emacs20 (20.3-1) unstable; urgency=low + + * New upstream version. + * Modify all the debian/* stuff to automatically track version changes. + * Major changes to info page handling. Emacs20 info is now integrated into + the main info page. This was the best way I could think of to handle + cross references, etc. without major source changes. + * Locked emacs20-el and emacs20 package versions together with dependencies. + * Add info direntries for widget, info, and customize. + * Fix handling of /usr/local/share (which was badly broken). + * Turn stripping back on. It appears to work. + + -- Rob Browning Tue, 1 Sep 1998 11:44:04 -0500 + +emacs20 (20.2-9) unstable; urgency=low + + * Fixes for leim problems (closes: #25536). Thanks to + Junio Hamano + * update-elc now made executable (closes: #25899). Thanks to + Junio Hamano + * Fix problem with package including dirs in /usr/local/share + (closes: #23431). + + -- Rob Browning Sat, 22 Aug 1998 11:45:16 -0500 + +emacs20 (20.2-8) unstable; urgency=low + + * Regenerate .elc files for .el files we've modified. I didn't realize + that some of the .elc files were in the upstream tar file. Hope this + doesn't break anything. We haven't been using our sendmail and + message modifications until now. (closes: #21079). + * Fix i386ism in debian scripts use "dpkg --print-architecture" + instead. (closes: #20548). + * Fixed reference in README.add-on-package-maintainers + (closes: #23445) + * Fix some alpha problems (closes: #21834). + * Had to add Replaces: emacs20 to emacs20-el to fix problem with + copyright files being in the wrong package (closes: #21531). + + -- Rob Browning Fri, 7 Aug 1998 20:39:59 -0500 + +emacs20 (20.2-7) frozen unstable; urgency=low + + * Changed emacs20-el from standard to optional. + * Fixed broken postrm (release critical) (closes: #24236) + * Don't strip emacs binary (strip is broken see binutils #23153). + * Since we can't strip, don't compile or link with "-g". + + -- Rob Browning Thu, 16 Jul 1998 16:58:04 -0500 + +emacs20 (20.2-6) frozen unstable; urgency=low + + * Gack. Fix reject due to changed .tar.gz file (./leim added to tar). + + -- Rob Browning Wed, 8 Apr 1998 14:04:54 -0500 + +emacs20 (20.2-5) frozen unstable; urgency=low + + * Make sure to preserve timestamps on .el files in emacs20-el + (closes: #20274) + * Add leim support for alternate input methods. May close several + bugs. + + -- Rob Browning Sun, 5 Apr 1998 10:38:20 -0500 + +emacs20 (20.2-4) frozen unstable; urgency=low + + * Added copright file to emacs20-el package (closes: #19300) + * suidmanager doesn't understand symbolic perms + (closes: #18448, #19213) + + -- Rob Browning Fri, 13 Mar 1998 13:01:07 -0600 + +emacs20 (20.2-3) unstable; urgency=low + + * Fixed problem with permissions on /usr/share/emacs/20.2/site-lisp/ + (closes: #18717) + + -- Rob Browning Mon, 2 Mar 1998 12:02:33 -0600 + +emacs20 (20.2-2) unstable; urgency=low + + * fixed bad menu line (closes: #18362). + + -- Rob Browning Thu, 19 Feb 1998 10:52:58 -0600 + +emacs20 (20.2-2) unstable; urgency=low + + * Explicit dependency on liblockfile0 until bug is fixed + (closes #18186) + * added lisp/site-lisp.el to fix info path problem (closes #18190) + + -- Rob Browning Sat, 14 Feb 1998 19:19:09 -0600 + +emacs20 (20.2-1) unstable; urgency=low + + * movemail no longer suid -- not needed. + * start from scratch with emacs-20.2 source and old emacs-19.34 and + xemacs patches. + + -- Rob Browning Tue, 16 Dec 1997 01:20:27 -0600 + +Local Variables: +coding: utf-8 +End: --- emacs23-23.1+1.orig/debian/copyright.in +++ emacs23-23.1+1/debian/copyright.in @@ -0,0 +1,102 @@ +-*-text-*- + +This package was debianized by Rob Browning on +Tue, 16 Dec 1997 00:05:45 -0600. + +The original source archive is emacs-@UPSTREAM_VERSION@.tar.gz, and it +can be found here for stable releases: + + ftp://ftp.gnu.org:/gnu/emacs/ + +and here for alpha pre-releases: + + ftp://alpha.gnu.org:/gnu/emacs/pretest/ + +Please see /usr/share/doc/@DEB_FLAVOR@-common/README.Debian.gz for a +description of the Debian specific differences from the upstream +version. + +Copyright: + + Emacs itself is licensed under the terms of the GNU General Public + License (GPL), Version 3. See the file + /usr/share/common-licenses/GPL-3 for more information. + + doc/man/b2m.1, doc/man/ebrowse.1, doc/man/grep-changelog.1, and + doc/man/rcs-checkin.1 are licensed as follows: + + Copyright (C) 2008, 2009 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this + document provided the copyright notice and this permission notice are + preserved on all copies. + + Permission is granted to copy and distribute modified versions of + this document under the conditions for verbatim copying, provided that + the entire resulting derived work is distributed under the terms of + a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this + document into another language, under the above conditions for + modified versions, except that this permission notice may be stated + in a translation approved by the Free Software Foundation. + + doc/man/emacs.1 is licensed as follows: + + Copyright (C) 1995, 1999, 2000, 2001, 2002, 2003, 2004, 2005, + 2006, 2007, 2008, 2009 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of + this document provided the copyright notice and this permission + notice are preserved on all copies. + + Permission is granted to copy and distribute modified versions of + this document under the conditions for verbatim copying, provided + that the entire resulting derived work is distributed under the + terms of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this + document into another language, under the above conditions for + modified versions, except that this permission notice may be + stated in a translation approved by the Free Software Foundation. + + doc/man/etags.1 is licensed as follows: + + Copyright (C) 1992, 1999, 2001, 2002, 2003, 2004, 2005, 2006, + 2007, 2008, 2009 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this + document provided the copyright notice and this permission notice are + preserved on all copies. + + Permission is granted to copy and distribute modified versions of + this document under the conditions for verbatim copying, provided that + the entire resulting derived work is distributed under the terms of + a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this + document into another language, under the above conditions for + modified versions, except that this permission notice may be stated + in a translation approved by the Free Software Foundation. + + man/faq.texi is licensed as follows: + + Copyright (C) 1994,1995,1996,1997,1998,1999,2000 Reuven M. Lerner + Copyright (C) 1992,1993 Steven Byrnes + Copyright (C) 1990,1991,1992 Joseph Brian Wells + + This list of frequently asked questions about GNU Emacs with + answers ("FAQ") may be translated into other languages, + transformed into other formats (e.g. Texinfo, Info, WWW, WAIS), + and updated with new information. + + The same conditions apply to any derivative of the FAQ as apply to + the FAQ itself. Every copy of the FAQ must include this notice or + an approved translation, information on who is currently + maintaining the FAQ and how to contact them (including their + e-mail address), and information on where the latest version of + the FAQ is archived (including FTP information). + + The FAQ may be copied and redistributed under these conditions, + except that the FAQ may not be embedded in a larger literary work + unless that work itself allows free copying and redistribution. --- emacs23-23.1+1.orig/debian/patches/debian-adjust-mail-from-addresses.diff +++ emacs23-23.1+1/debian/patches/debian-adjust-mail-from-addresses.diff @@ -0,0 +1,46 @@ +* The default handling of mail from addresses has been changed. + Patch: debian-adjust-mail-from-addresses.diff + Bug: 7051 35128 + + * The default for message-sendmail-f-is-evil has been changed to t. + + This is correct for Debian systems where we know the MTA should be + trusted. + + * The default mail-from-style is 'system-default rather than 'angles. + +Index: b/lisp/gnus/message.el +=================================================================== +--- a/lisp/gnus/message.el ++++ b/lisp/gnus/message.el +@@ -808,9 +808,14 @@ + (const never) + (const ask))) + +-(defcustom message-sendmail-f-is-evil nil +- "*Non-nil means don't add \"-f username\" to the sendmail command line. +-Doing so would be even more evil than leaving it out." ++;; message-sendmail-f-is-evil is nil here in the upstream source, but ++;; sendmail works right under Debian Linux, so we want t. [was ++;; orignally reported for emacs 19 as debian#7051] ++(defcustom message-sendmail-f-is-evil t ++ "*Non-nil means don't add \"-f username\" to the sendmail command ++line, because adding it would be more evil than leaving it out. Under ++Debian/GNU/Linux, sendmail works right, so it should be safe for this ++to be set to true." + :group 'message-sending + :link '(custom-manual "(message)Mail Variables") + :type 'boolean) +Index: b/lisp/mail/sendmail.el +=================================================================== +--- a/lisp/mail/sendmail.el ++++ b/lisp/mail/sendmail.el +@@ -58,7 +58,7 @@ + :type 'file) + + ;;;###autoload +-(defcustom mail-from-style 'angles ++(defcustom mail-from-style 'system-default + "Specifies how \"From:\" fields look. + + If `nil', they contain just the return address like: --- emacs23-23.1+1.orig/debian/patches/debian-startup.diff +++ emacs23-23.1+1/debian/patches/debian-startup.diff @@ -0,0 +1,48 @@ +* Emacs runs debian-startup and sets debian-emacs-flavor. + Patch: debian-startup.diff + + * Emacs runs debian-startup during the startup process unless + site-run-file is false. + + * The global variable debian-emacs-flavor is bound to 'emacs23. + Author: Rob Browning + +Index: b/lisp/startup.el +=================================================================== +--- a/lisp/startup.el ++++ b/lisp/startup.el +@@ -394,6 +394,10 @@ + (setq tutorial-directory (file-name-as-directory + (expand-file-name "tutorials" data-directory)))) + ++(defconst debian-emacs-flavor 'emacs23 ++ "A symbol representing the particular debian flavor of emacs running. ++Something like 'emacs20, 'xemacs20, etc.") ++ + (defun normal-top-level-add-subdirs-to-load-path () + "Add all subdirectories of current directory to `load-path'. + More precisely, this uses only the subdirectories whose names +@@ -977,8 +981,21 @@ + ;; be loaded from site-run-file and wants to test if -q was given + ;; should check init-file-user instead, since that is already set. + ;; See cus-edit.el for an example. +- (if site-run-file +- (load site-run-file t t)) ++ ++ ;; Original upstream startup ++ ;; (if site-run-file ++ ;; (load site-run-file t t)) ++ ;; ++ ++ ;; Debian startup ++ (if site-run-file ++ (progn ++ ;; Load all the debian package snippets. ++ ;; It's in here because we want -q to kill it too. ++ (if (load "debian-startup" t t nil) ++ (debian-startup debian-emacs-flavor)) ++ ;; Now the normal site file... ++ (load site-run-file t t nil))) + + ;; Sites should not disable this. Only individuals should disable + ;; the startup screen. --- emacs23-23.1+1.orig/debian/patches/require-movemail-use-liblockfile.diff +++ emacs23-23.1+1/debian/patches/require-movemail-use-liblockfile.diff @@ -0,0 +1,40 @@ +* The build will fail if liblockfile isn't selected for movemail. + Patch: require-movemail-use-liblockfile.diff + Author: Rob Browning + Added-by: Rob Browning + + This makes sure the Debian Emacs won't accidentally be built with + the wrong locking strategy. To disable this check, comment out + require-movemail-use-liblockfile.diff in debian/patches/series. + +Index: b/lib-src/movemail.c +=================================================================== +--- a/lib-src/movemail.c ++++ b/lib-src/movemail.c +@@ -166,6 +166,10 @@ + /* Nonzero means this is name of a lock file to delete on fatal error. */ + char *delete_lockname; + ++#ifndef MAIL_USE_MAILLOCK ++#error "Debian requires that mail locking be handled by liblockfile." ++#endif /* ndef MAIL_USE_MAILLOCK */ ++ + int + main (argc, argv) + int argc; +Index: b/src/s/bsd-common.h +=================================================================== +--- a/src/s/bsd-common.h ++++ b/src/s/bsd-common.h +@@ -66,7 +66,11 @@ + The alternative is that a lock file named + /usr/spool/mail/$USER.lock. */ + ++/* conditional copied from gnu-linux.h */ ++#if !((defined (HAVE_LIBMAIL) || defined (HAVE_LIBLOCKFILE)) && \ ++ defined (HAVE_MAILLOCK_H)) + #define MAIL_USE_FLOCK ++#endif + + /* Define CLASH_DETECTION if you want lock files to be written + so that Emacs can tell instantly when you try to modify --- emacs23-23.1+1.orig/debian/patches/autofiles.diff +++ emacs23-23.1+1/debian/patches/autofiles.diff @@ -0,0 +1,22074 @@ +* The autoconf related files have been updated. + Patch: autofiles.dpatch + Author: N/A (automatically generated) +Index: emacs23/configure +=================================================================== +--- emacs23.orig/configure ++++ emacs23/configure +@@ -1,9 +1,9 @@ + #! /bin/sh + # Guess values for system-dependent variables and create Makefiles. +-# Generated by GNU Autoconf 2.61 for emacs 23.1. ++# Generated by GNU Autoconf 2.63 for emacs 23.1. + # + # Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, +-# 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. ++# 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. + # This configure script is free software; the Free Software Foundation + # gives unlimited permission to copy, distribute and modify it. + ## --------------------- ## +@@ -15,7 +15,7 @@ + if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then + emulate sh + NULLCMD=: +- # Zsh 3.x and 4.x performs word splitting on ${1+"$@"}, which ++ # Pre-4.2 versions of Zsh do word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +@@ -37,17 +37,45 @@ + as_cr_digits='0123456789' + as_cr_alnum=$as_cr_Letters$as_cr_digits + +-# The user is always right. +-if test "${PATH_SEPARATOR+set}" != set; then +- echo "#! /bin/sh" >conf$$.sh +- echo "exit 0" >>conf$$.sh +- chmod +x conf$$.sh +- if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then +- PATH_SEPARATOR=';' ++as_nl=' ++' ++export as_nl ++# Printing a long string crashes Solaris 7 /usr/bin/printf. ++as_echo='\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\' ++as_echo=$as_echo$as_echo$as_echo$as_echo$as_echo ++as_echo=$as_echo$as_echo$as_echo$as_echo$as_echo$as_echo ++if (test "X`printf %s $as_echo`" = "X$as_echo") 2>/dev/null; then ++ as_echo='printf %s\n' ++ as_echo_n='printf %s' ++else ++ if test "X`(/usr/ucb/echo -n -n $as_echo) 2>/dev/null`" = "X-n $as_echo"; then ++ as_echo_body='eval /usr/ucb/echo -n "$1$as_nl"' ++ as_echo_n='/usr/ucb/echo -n' + else +- PATH_SEPARATOR=: ++ as_echo_body='eval expr "X$1" : "X\\(.*\\)"' ++ as_echo_n_body='eval ++ arg=$1; ++ case $arg in ++ *"$as_nl"*) ++ expr "X$arg" : "X\\(.*\\)$as_nl"; ++ arg=`expr "X$arg" : ".*$as_nl\\(.*\\)"`;; ++ esac; ++ expr "X$arg" : "X\\(.*\\)" | tr -d "$as_nl" ++ ' ++ export as_echo_n_body ++ as_echo_n='sh -c $as_echo_n_body as_echo' + fi +- rm -f conf$$.sh ++ export as_echo_body ++ as_echo='sh -c $as_echo_body as_echo' ++fi ++ ++# The user is always right. ++if test "${PATH_SEPARATOR+set}" != set; then ++ PATH_SEPARATOR=: ++ (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 && { ++ (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 || ++ PATH_SEPARATOR=';' ++ } + fi + + # Support unset when possible. +@@ -63,8 +91,6 @@ + # there to prevent editors from complaining about space-tab. + # (If _AS_PATH_WALK were called with IFS unset, it would disable word + # splitting by setting IFS to empty value.) +-as_nl=' +-' + IFS=" "" $as_nl" + + # Find who we are. Look in the path if we contain no directory separator. +@@ -87,7 +113,7 @@ + as_myself=$0 + fi + if test ! -f "$as_myself"; then +- echo "$as_myself: error: cannot find myself; rerun with an absolute file name" >&2 ++ $as_echo "$as_myself: error: cannot find myself; rerun with an absolute file name" >&2 + { (exit 1); exit 1; } + fi + +@@ -100,17 +126,10 @@ + PS4='+ ' + + # NLS nuisances. +-for as_var in \ +- LANG LANGUAGE LC_ADDRESS LC_ALL LC_COLLATE LC_CTYPE LC_IDENTIFICATION \ +- LC_MEASUREMENT LC_MESSAGES LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER \ +- LC_TELEPHONE LC_TIME +-do +- if (set +x; test -z "`(eval $as_var=C; export $as_var) 2>&1`"); then +- eval $as_var=C; export $as_var +- else +- ($as_unset $as_var) >/dev/null 2>&1 && $as_unset $as_var +- fi +-done ++LC_ALL=C ++export LC_ALL ++LANGUAGE=C ++export LANGUAGE + + # Required to use basename. + if expr a : '\(a\)' >/dev/null 2>&1 && +@@ -132,7 +151,7 @@ + $as_expr X/"$0" : '.*/\([^/][^/]*\)/*$' \| \ + X"$0" : 'X\(//\)$' \| \ + X"$0" : 'X\(/\)' \| . 2>/dev/null || +-echo X/"$0" | ++$as_echo X/"$0" | + sed '/^.*\/\([^/][^/]*\)\/*$/{ + s//\1/ + q +@@ -158,7 +177,7 @@ + as_have_required=no + fi + +- if test $as_have_required = yes && (eval ": ++ if test $as_have_required = yes && (eval ": + (as_func_return () { + (exit \$1) + } +@@ -240,7 +259,7 @@ + if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then + emulate sh + NULLCMD=: +- # Zsh 3.x and 4.x performs word splitting on ${1+"$@"}, which ++ # Pre-4.2 versions of Zsh do word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +@@ -261,7 +280,7 @@ + if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then + emulate sh + NULLCMD=: +- # Zsh 3.x and 4.x performs word splitting on ${1+"$@"}, which ++ # Pre-4.2 versions of Zsh do word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +@@ -341,10 +360,10 @@ + + if test "x$CONFIG_SHELL" != x; then + for as_var in BASH_ENV ENV +- do ($as_unset $as_var) >/dev/null 2>&1 && $as_unset $as_var +- done +- export CONFIG_SHELL +- exec "$CONFIG_SHELL" "$as_myself" ${1+"$@"} ++ do ($as_unset $as_var) >/dev/null 2>&1 && $as_unset $as_var ++ done ++ export CONFIG_SHELL ++ exec "$CONFIG_SHELL" "$as_myself" ${1+"$@"} + fi + + +@@ -413,9 +432,10 @@ + + test \$exitcode = 0") || { + echo No shell found that supports shell functions. +- echo Please tell autoconf@gnu.org about your system, +- echo including any error possibly output before this +- echo message ++ echo Please tell bug-autoconf@gnu.org about your system, ++ echo including any error possibly output before this message. ++ echo This can help us improve future autoconf versions. ++ echo Configuration will now proceed without shell functions. + } + + +@@ -451,7 +471,7 @@ + s/-\n.*// + ' >$as_me.lineno && + chmod +x "$as_me.lineno" || +- { echo "$as_me: error: cannot create $as_me.lineno; rerun with a POSIX shell" >&2 ++ { $as_echo "$as_me: error: cannot create $as_me.lineno; rerun with a POSIX shell" >&2 + { (exit 1); exit 1; }; } + + # Don't try to exec as it changes $[0], causing all sort of problems +@@ -479,7 +499,6 @@ + *) + ECHO_N='-n';; + esac +- + if expr a : '\(a\)' >/dev/null 2>&1 && + test "X`expr 00001 : '.*\(...\)'`" = X001; then + as_expr=expr +@@ -492,19 +511,22 @@ + rm -f conf$$.dir/conf$$.file + else + rm -f conf$$.dir +- mkdir conf$$.dir ++ mkdir conf$$.dir 2>/dev/null + fi +-echo >conf$$.file +-if ln -s conf$$.file conf$$ 2>/dev/null; then +- as_ln_s='ln -s' +- # ... but there are two gotchas: +- # 1) On MSYS, both `ln -s file dir' and `ln file dir' fail. +- # 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable. +- # In both cases, we have to default to `cp -p'. +- ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe || ++if (echo >conf$$.file) 2>/dev/null; then ++ if ln -s conf$$.file conf$$ 2>/dev/null; then ++ as_ln_s='ln -s' ++ # ... but there are two gotchas: ++ # 1) On MSYS, both `ln -s file dir' and `ln file dir' fail. ++ # 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable. ++ # In both cases, we have to default to `cp -p'. ++ ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe || ++ as_ln_s='cp -p' ++ elif ln conf$$.file conf$$ 2>/dev/null; then ++ as_ln_s=ln ++ else + as_ln_s='cp -p' +-elif ln conf$$.file conf$$ 2>/dev/null; then +- as_ln_s=ln ++ fi + else + as_ln_s='cp -p' + fi +@@ -529,10 +551,10 @@ + as_test_x=' + eval sh -c '\'' + if test -d "$1"; then +- test -d "$1/."; ++ test -d "$1/."; + else + case $1 in +- -*)set "./$1";; ++ -*)set "./$1";; + esac; + case `ls -ld'$as_ls_L_option' "$1" 2>/dev/null` in + ???[sx]*):;;*)false;;esac;fi +@@ -616,134 +638,170 @@ + ac_config_libobj_dir=src + ac_header_list= + ac_func_list= +-ac_subst_vars='SHELL +-PATH_SEPARATOR +-PACKAGE_NAME +-PACKAGE_TARNAME +-PACKAGE_VERSION +-PACKAGE_STRING +-PACKAGE_BUGREPORT +-exec_prefix +-prefix +-program_transform_name +-bindir +-sbindir +-libexecdir +-datarootdir +-datadir +-sysconfdir +-sharedstatedir +-localstatedir +-includedir +-oldincludedir +-docdir +-infodir +-htmldir +-dvidir +-pdfdir +-psdir +-libdir +-localedir +-mandir +-DEFS +-ECHO_C +-ECHO_N +-ECHO_T +-LIBS +-build_alias +-host_alias +-target_alias +-MAINT +-build +-build_cpu +-build_vendor +-build_os +-host +-host_cpu +-host_vendor +-host_os +-CC +-CFLAGS +-LDFLAGS +-CPPFLAGS +-ac_ct_CC +-EXEEXT +-OBJEXT +-CPP +-GREP +-EGREP +-LN_S +-INSTALL_PROGRAM +-INSTALL_SCRIPT +-INSTALL_DATA +-RANLIB +-INSTALL_INFO +-GZIP_PROG +-MAKEINFO +-LIBSOUND +-PKG_CONFIG +-ALSA_CFLAGS +-ALSA_LIBS +-CFLAGS_SOUND +-SET_MAKE +-XMKMF +-HAVE_XSERVER +-RSVG_CFLAGS +-RSVG_LIBS +-GTK_CFLAGS +-GTK_LIBS +-DBUS_CFLAGS +-DBUS_LIBS +-FONTCONFIG_CFLAGS +-FONTCONFIG_LIBS +-XFT_CFLAGS +-XFT_LIBS +-LIBOTF_CFLAGS +-LIBOTF_LIBS +-M17N_FLT_CFLAGS +-M17N_FLT_LIBS +-FREETYPE_CFLAGS +-FREETYPE_LIBS +-ALLOCA +-liblockfile +-LIBOBJS +-NEED_SETGID +-KMEM_GROUP +-GETLOADAVG_LIBS +-GETOPT_H +-GETOPTOBJS +-version +-configuration +-canonical +-srcdir +-lispdir +-locallisppath +-lisppath +-x_default_search_path +-etcdir +-archlibdir +-bitmapdir +-gamedir +-gameuser +-c_switch_system +-c_switch_machine +-LD_SWITCH_X_SITE +-LD_SWITCH_X_SITE_AUX +-C_SWITCH_X_SITE +-X_TOOLKIT_TYPE +-machfile +-opsysfile +-ns_appdir +-ns_appbindir +-ns_appresdir +-ns_appsrc +-GNUSTEP_MAKEFILES +-GNUSTEP_SYSTEM_HEADERS +-GNUSTEP_SYSTEM_LIBRARIES +-GNU_OBJC_CFLAGS ++ac_subst_vars='LTLIBOBJS + LIB_SRC_EXTRA_INSTALLABLES +-LTLIBOBJS' ++GNU_OBJC_CFLAGS ++GNUSTEP_SYSTEM_LIBRARIES ++GNUSTEP_SYSTEM_HEADERS ++GNUSTEP_MAKEFILES ++ns_appsrc ++ns_appresdir ++ns_appbindir ++ns_appdir ++opsysfile ++machfile ++X_TOOLKIT_TYPE ++C_SWITCH_X_SITE ++LD_SWITCH_X_SITE_AUX ++LD_SWITCH_X_SITE ++c_switch_machine ++c_switch_system ++gameuser ++gamedir ++bitmapdir ++archlibdir ++etcdir ++x_default_search_path ++lisppath ++locallisppath ++lispdir ++srcdir ++canonical ++configuration ++version ++GETOPTOBJS ++GETOPT_H ++GETLOADAVG_LIBS ++KMEM_GROUP ++NEED_SETGID ++LIBOBJS ++liblockfile ++ALLOCA ++FREETYPE_LIBS ++FREETYPE_CFLAGS ++M17N_FLT_LIBS ++M17N_FLT_CFLAGS ++LIBOTF_LIBS ++LIBOTF_CFLAGS ++XFT_LIBS ++XFT_CFLAGS ++FONTCONFIG_LIBS ++FONTCONFIG_CFLAGS ++DBUS_LIBS ++DBUS_CFLAGS ++GTK_LIBS ++GTK_CFLAGS ++RSVG_LIBS ++RSVG_CFLAGS ++HAVE_XSERVER ++XMKMF ++SET_MAKE ++CFLAGS_SOUND ++ALSA_LIBS ++ALSA_CFLAGS ++PKG_CONFIG ++LIBSOUND ++MAKEINFO ++GZIP_PROG ++INSTALL_INFO ++RANLIB ++INSTALL_DATA ++INSTALL_SCRIPT ++INSTALL_PROGRAM ++LN_S ++EGREP ++GREP ++CPP ++OBJEXT ++EXEEXT ++ac_ct_CC ++CPPFLAGS ++LDFLAGS ++CFLAGS ++CC ++host_os ++host_vendor ++host_cpu ++host ++build_os ++build_vendor ++build_cpu ++build ++MAINT ++target_alias ++host_alias ++build_alias ++LIBS ++ECHO_T ++ECHO_N ++ECHO_C ++DEFS ++mandir ++localedir ++libdir ++psdir ++pdfdir ++dvidir ++htmldir ++infodir ++docdir ++oldincludedir ++includedir ++localstatedir ++sharedstatedir ++sysconfdir ++datadir ++datarootdir ++libexecdir ++sbindir ++bindir ++program_transform_name ++prefix ++exec_prefix ++PACKAGE_BUGREPORT ++PACKAGE_STRING ++PACKAGE_VERSION ++PACKAGE_TARNAME ++PACKAGE_NAME ++PATH_SEPARATOR ++SHELL' + ac_subst_files='' ++ac_user_opts=' ++enable_option_checking ++with_pop ++with_kerberos ++with_kerberos5 ++with_hesiod ++with_sound ++with_sync_input ++with_x_toolkit ++with_xpm ++with_jpeg ++with_tiff ++with_gif ++with_png ++with_rsvg ++with_xft ++with_libotf ++with_m17n_flt ++with_toolkit_scroll_bars ++with_xaw3d ++with_xim ++with_ns ++with_gpm ++with_dbus ++with_makeinfo ++with_gtk ++with_gcc ++with_pkg_config_prog ++with_gnustep_conf ++enable_ns_self_contained ++enable_asserts ++enable_maintainer_mode ++enable_locallisppath ++enable_largefile ++with_x ++' + ac_precious_vars='build_alias + host_alias + target_alias +@@ -759,6 +817,8 @@ + # Initialize some variables set by options. + ac_init_help= + ac_init_version=false ++ac_unrecognized_opts= ++ac_unrecognized_sep= + # The variables have the same names as the options, with + # dashes changed to underlines. + cache_file=/dev/null +@@ -857,13 +917,21 @@ + datarootdir=$ac_optarg ;; + + -disable-* | --disable-*) +- ac_feature=`expr "x$ac_option" : 'x-*disable-\(.*\)'` ++ ac_useropt=`expr "x$ac_option" : 'x-*disable-\(.*\)'` + # Reject names that are not valid shell variable names. +- expr "x$ac_feature" : ".*[^-._$as_cr_alnum]" >/dev/null && +- { echo "$as_me: error: invalid feature name: $ac_feature" >&2 ++ expr "x$ac_useropt" : ".*[^-+._$as_cr_alnum]" >/dev/null && ++ { $as_echo "$as_me: error: invalid feature name: $ac_useropt" >&2 + { (exit 1); exit 1; }; } +- ac_feature=`echo $ac_feature | sed 's/[-.]/_/g'` +- eval enable_$ac_feature=no ;; ++ ac_useropt_orig=$ac_useropt ++ ac_useropt=`$as_echo "$ac_useropt" | sed 's/[-+.]/_/g'` ++ case $ac_user_opts in ++ *" ++"enable_$ac_useropt" ++"*) ;; ++ *) ac_unrecognized_opts="$ac_unrecognized_opts$ac_unrecognized_sep--disable-$ac_useropt_orig" ++ ac_unrecognized_sep=', ';; ++ esac ++ eval enable_$ac_useropt=no ;; + + -docdir | --docdir | --docdi | --doc | --do) + ac_prev=docdir ;; +@@ -876,13 +944,21 @@ + dvidir=$ac_optarg ;; + + -enable-* | --enable-*) +- ac_feature=`expr "x$ac_option" : 'x-*enable-\([^=]*\)'` ++ ac_useropt=`expr "x$ac_option" : 'x-*enable-\([^=]*\)'` + # Reject names that are not valid shell variable names. +- expr "x$ac_feature" : ".*[^-._$as_cr_alnum]" >/dev/null && +- { echo "$as_me: error: invalid feature name: $ac_feature" >&2 ++ expr "x$ac_useropt" : ".*[^-+._$as_cr_alnum]" >/dev/null && ++ { $as_echo "$as_me: error: invalid feature name: $ac_useropt" >&2 + { (exit 1); exit 1; }; } +- ac_feature=`echo $ac_feature | sed 's/[-.]/_/g'` +- eval enable_$ac_feature=\$ac_optarg ;; ++ ac_useropt_orig=$ac_useropt ++ ac_useropt=`$as_echo "$ac_useropt" | sed 's/[-+.]/_/g'` ++ case $ac_user_opts in ++ *" ++"enable_$ac_useropt" ++"*) ;; ++ *) ac_unrecognized_opts="$ac_unrecognized_opts$ac_unrecognized_sep--enable-$ac_useropt_orig" ++ ac_unrecognized_sep=', ';; ++ esac ++ eval enable_$ac_useropt=\$ac_optarg ;; + + -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ + | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ +@@ -1073,22 +1149,38 @@ + ac_init_version=: ;; + + -with-* | --with-*) +- ac_package=`expr "x$ac_option" : 'x-*with-\([^=]*\)'` ++ ac_useropt=`expr "x$ac_option" : 'x-*with-\([^=]*\)'` + # Reject names that are not valid shell variable names. +- expr "x$ac_package" : ".*[^-._$as_cr_alnum]" >/dev/null && +- { echo "$as_me: error: invalid package name: $ac_package" >&2 ++ expr "x$ac_useropt" : ".*[^-+._$as_cr_alnum]" >/dev/null && ++ { $as_echo "$as_me: error: invalid package name: $ac_useropt" >&2 + { (exit 1); exit 1; }; } +- ac_package=`echo $ac_package | sed 's/[-.]/_/g'` +- eval with_$ac_package=\$ac_optarg ;; ++ ac_useropt_orig=$ac_useropt ++ ac_useropt=`$as_echo "$ac_useropt" | sed 's/[-+.]/_/g'` ++ case $ac_user_opts in ++ *" ++"with_$ac_useropt" ++"*) ;; ++ *) ac_unrecognized_opts="$ac_unrecognized_opts$ac_unrecognized_sep--with-$ac_useropt_orig" ++ ac_unrecognized_sep=', ';; ++ esac ++ eval with_$ac_useropt=\$ac_optarg ;; + + -without-* | --without-*) +- ac_package=`expr "x$ac_option" : 'x-*without-\(.*\)'` ++ ac_useropt=`expr "x$ac_option" : 'x-*without-\(.*\)'` + # Reject names that are not valid shell variable names. +- expr "x$ac_package" : ".*[^-._$as_cr_alnum]" >/dev/null && +- { echo "$as_me: error: invalid package name: $ac_package" >&2 ++ expr "x$ac_useropt" : ".*[^-+._$as_cr_alnum]" >/dev/null && ++ { $as_echo "$as_me: error: invalid package name: $ac_useropt" >&2 + { (exit 1); exit 1; }; } +- ac_package=`echo $ac_package | sed 's/[-.]/_/g'` +- eval with_$ac_package=no ;; ++ ac_useropt_orig=$ac_useropt ++ ac_useropt=`$as_echo "$ac_useropt" | sed 's/[-+.]/_/g'` ++ case $ac_user_opts in ++ *" ++"with_$ac_useropt" ++"*) ;; ++ *) ac_unrecognized_opts="$ac_unrecognized_opts$ac_unrecognized_sep--without-$ac_useropt_orig" ++ ac_unrecognized_sep=', ';; ++ esac ++ eval with_$ac_useropt=no ;; + + --x) + # Obsolete; use --with-x. +@@ -1108,7 +1200,7 @@ + | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) + x_libraries=$ac_optarg ;; + +- -*) { echo "$as_me: error: unrecognized option: $ac_option ++ -*) { $as_echo "$as_me: error: unrecognized option: $ac_option + Try \`$0 --help' for more information." >&2 + { (exit 1); exit 1; }; } + ;; +@@ -1117,16 +1209,16 @@ + ac_envvar=`expr "x$ac_option" : 'x\([^=]*\)='` + # Reject names that are not valid shell variable names. + expr "x$ac_envvar" : ".*[^_$as_cr_alnum]" >/dev/null && +- { echo "$as_me: error: invalid variable name: $ac_envvar" >&2 ++ { $as_echo "$as_me: error: invalid variable name: $ac_envvar" >&2 + { (exit 1); exit 1; }; } + eval $ac_envvar=\$ac_optarg + export $ac_envvar ;; + + *) + # FIXME: should be removed in autoconf 3.0. +- echo "$as_me: WARNING: you should use --build, --host, --target" >&2 ++ $as_echo "$as_me: WARNING: you should use --build, --host, --target" >&2 + expr "x$ac_option" : ".*[^-._$as_cr_alnum]" >/dev/null && +- echo "$as_me: WARNING: invalid host type: $ac_option" >&2 ++ $as_echo "$as_me: WARNING: invalid host type: $ac_option" >&2 + : ${build_alias=$ac_option} ${host_alias=$ac_option} ${target_alias=$ac_option} + ;; + +@@ -1135,22 +1227,38 @@ + + if test -n "$ac_prev"; then + ac_option=--`echo $ac_prev | sed 's/_/-/g'` +- { echo "$as_me: error: missing argument to $ac_option" >&2 ++ { $as_echo "$as_me: error: missing argument to $ac_option" >&2 + { (exit 1); exit 1; }; } + fi + +-# Be sure to have absolute directory names. ++if test -n "$ac_unrecognized_opts"; then ++ case $enable_option_checking in ++ no) ;; ++ fatal) { $as_echo "$as_me: error: unrecognized options: $ac_unrecognized_opts" >&2 ++ { (exit 1); exit 1; }; } ;; ++ *) $as_echo "$as_me: WARNING: unrecognized options: $ac_unrecognized_opts" >&2 ;; ++ esac ++fi ++ ++# Check all directory arguments for consistency. + for ac_var in exec_prefix prefix bindir sbindir libexecdir datarootdir \ + datadir sysconfdir sharedstatedir localstatedir includedir \ + oldincludedir docdir infodir htmldir dvidir pdfdir psdir \ + libdir localedir mandir + do + eval ac_val=\$$ac_var ++ # Remove trailing slashes. ++ case $ac_val in ++ */ ) ++ ac_val=`expr "X$ac_val" : 'X\(.*[^/]\)' \| "X$ac_val" : 'X\(.*\)'` ++ eval $ac_var=\$ac_val;; ++ esac ++ # Be sure to have absolute directory names. + case $ac_val in + [\\/$]* | ?:[\\/]* ) continue;; + NONE | '' ) case $ac_var in *prefix ) continue;; esac;; + esac +- { echo "$as_me: error: expected an absolute directory name for --$ac_var: $ac_val" >&2 ++ { $as_echo "$as_me: error: expected an absolute directory name for --$ac_var: $ac_val" >&2 + { (exit 1); exit 1; }; } + done + +@@ -1165,7 +1273,7 @@ + if test "x$host_alias" != x; then + if test "x$build_alias" = x; then + cross_compiling=maybe +- echo "$as_me: WARNING: If you wanted to set the --build type, don't use --host. ++ $as_echo "$as_me: WARNING: If you wanted to set the --build type, don't use --host. + If a cross compiler is detected then cross compile mode will be used." >&2 + elif test "x$build_alias" != "x$host_alias"; then + cross_compiling=yes +@@ -1181,10 +1289,10 @@ + ac_pwd=`pwd` && test -n "$ac_pwd" && + ac_ls_di=`ls -di .` && + ac_pwd_ls_di=`cd "$ac_pwd" && ls -di .` || +- { echo "$as_me: error: Working directory cannot be determined" >&2 ++ { $as_echo "$as_me: error: working directory cannot be determined" >&2 + { (exit 1); exit 1; }; } + test "X$ac_ls_di" = "X$ac_pwd_ls_di" || +- { echo "$as_me: error: pwd does not report name of working directory" >&2 ++ { $as_echo "$as_me: error: pwd does not report name of working directory" >&2 + { (exit 1); exit 1; }; } + + +@@ -1192,12 +1300,12 @@ + if test -z "$srcdir"; then + ac_srcdir_defaulted=yes + # Try the directory containing this script, then the parent directory. +- ac_confdir=`$as_dirname -- "$0" || +-$as_expr X"$0" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ +- X"$0" : 'X\(//\)[^/]' \| \ +- X"$0" : 'X\(//\)$' \| \ +- X"$0" : 'X\(/\)' \| . 2>/dev/null || +-echo X"$0" | ++ ac_confdir=`$as_dirname -- "$as_myself" || ++$as_expr X"$as_myself" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ ++ X"$as_myself" : 'X\(//\)[^/]' \| \ ++ X"$as_myself" : 'X\(//\)$' \| \ ++ X"$as_myself" : 'X\(/\)' \| . 2>/dev/null || ++$as_echo X"$as_myself" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q +@@ -1224,12 +1332,12 @@ + fi + if test ! -r "$srcdir/$ac_unique_file"; then + test "$ac_srcdir_defaulted" = yes && srcdir="$ac_confdir or .." +- { echo "$as_me: error: cannot find sources ($ac_unique_file) in $srcdir" >&2 ++ { $as_echo "$as_me: error: cannot find sources ($ac_unique_file) in $srcdir" >&2 + { (exit 1); exit 1; }; } + fi + ac_msg="sources are in $srcdir, but \`cd $srcdir' does not work" + ac_abs_confdir=`( +- cd "$srcdir" && test -r "./$ac_unique_file" || { echo "$as_me: error: $ac_msg" >&2 ++ cd "$srcdir" && test -r "./$ac_unique_file" || { $as_echo "$as_me: error: $ac_msg" >&2 + { (exit 1); exit 1; }; } + pwd)` + # When building in place, set srcdir=. +@@ -1278,9 +1386,9 @@ + + Installation directories: + --prefix=PREFIX install architecture-independent files in PREFIX +- [$ac_default_prefix] ++ [$ac_default_prefix] + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX +- [PREFIX] ++ [PREFIX] + + By default, \`make install' will install all the files in + \`$ac_default_prefix/bin', \`$ac_default_prefix/lib' etc. You can specify +@@ -1290,25 +1398,25 @@ + For better control, use the options below. + + Fine tuning of the installation directories: +- --bindir=DIR user executables [EPREFIX/bin] +- --sbindir=DIR system admin executables [EPREFIX/sbin] +- --libexecdir=DIR program executables [EPREFIX/libexec] +- --sysconfdir=DIR read-only single-machine data [PREFIX/etc] +- --sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com] +- --localstatedir=DIR modifiable single-machine data [PREFIX/var] +- --libdir=DIR object code libraries [EPREFIX/lib] +- --includedir=DIR C header files [PREFIX/include] +- --oldincludedir=DIR C header files for non-gcc [/usr/include] +- --datarootdir=DIR read-only arch.-independent data root [PREFIX/share] +- --datadir=DIR read-only architecture-independent data [DATAROOTDIR] +- --infodir=DIR info documentation [DATAROOTDIR/info] +- --localedir=DIR locale-dependent data [DATAROOTDIR/locale] +- --mandir=DIR man documentation [DATAROOTDIR/man] +- --docdir=DIR documentation root [DATAROOTDIR/doc/emacs] +- --htmldir=DIR html documentation [DOCDIR] +- --dvidir=DIR dvi documentation [DOCDIR] +- --pdfdir=DIR pdf documentation [DOCDIR] +- --psdir=DIR ps documentation [DOCDIR] ++ --bindir=DIR user executables [EPREFIX/bin] ++ --sbindir=DIR system admin executables [EPREFIX/sbin] ++ --libexecdir=DIR program executables [EPREFIX/libexec] ++ --sysconfdir=DIR read-only single-machine data [PREFIX/etc] ++ --sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com] ++ --localstatedir=DIR modifiable single-machine data [PREFIX/var] ++ --libdir=DIR object code libraries [EPREFIX/lib] ++ --includedir=DIR C header files [PREFIX/include] ++ --oldincludedir=DIR C header files for non-gcc [/usr/include] ++ --datarootdir=DIR read-only arch.-independent data root [PREFIX/share] ++ --datadir=DIR read-only architecture-independent data [DATAROOTDIR] ++ --infodir=DIR info documentation [DATAROOTDIR/info] ++ --localedir=DIR locale-dependent data [DATAROOTDIR/locale] ++ --mandir=DIR man documentation [DATAROOTDIR/man] ++ --docdir=DIR documentation root [DATAROOTDIR/doc/emacs] ++ --htmldir=DIR html documentation [DOCDIR] ++ --dvidir=DIR dvi documentation [DOCDIR] ++ --pdfdir=DIR pdf documentation [DOCDIR] ++ --psdir=DIR ps documentation [DOCDIR] + _ACEOF + + cat <<\_ACEOF +@@ -1335,6 +1443,7 @@ + cat <<\_ACEOF + + Optional Features: ++ --disable-option-checking ignore unrecognized --enable/--with options + --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) + --enable-FEATURE[=ARG] include FEATURE [ARG=yes] + --disable-ns-self-contained +@@ -1406,15 +1515,17 @@ + if test "$ac_init_help" = "recursive"; then + # If there are subdirs, report their specific --help. + for ac_dir in : $ac_subdirs_all; do test "x$ac_dir" = x: && continue +- test -d "$ac_dir" || continue ++ test -d "$ac_dir" || ++ { cd "$srcdir" && ac_pwd=`pwd` && srcdir=. && test -d "$ac_dir"; } || ++ continue + ac_builddir=. + + case "$ac_dir" in + .) ac_dir_suffix= ac_top_builddir_sub=. ac_top_build_prefix= ;; + *) +- ac_dir_suffix=/`echo "$ac_dir" | sed 's,^\.[\\/],,'` ++ ac_dir_suffix=/`$as_echo "$ac_dir" | sed 's|^\.[\\/]||'` + # A ".." for each directory in $ac_dir_suffix. +- ac_top_builddir_sub=`echo "$ac_dir_suffix" | sed 's,/[^\\/]*,/..,g;s,/,,'` ++ ac_top_builddir_sub=`$as_echo "$ac_dir_suffix" | sed 's|/[^\\/]*|/..|g;s|/||'` + case $ac_top_builddir_sub in + "") ac_top_builddir_sub=. ac_top_build_prefix= ;; + *) ac_top_build_prefix=$ac_top_builddir_sub/ ;; +@@ -1450,7 +1561,7 @@ + echo && + $SHELL "$ac_srcdir/configure" --help=recursive + else +- echo "$as_me: WARNING: no configuration information is in $ac_dir" >&2 ++ $as_echo "$as_me: WARNING: no configuration information is in $ac_dir" >&2 + fi || ac_status=$? + cd "$ac_pwd" || { ac_status=$?; break; } + done +@@ -1460,10 +1571,10 @@ + if $ac_init_version; then + cat <<\_ACEOF + emacs configure 23.1 +-generated by GNU Autoconf 2.61 ++generated by GNU Autoconf 2.63 + + Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, +-2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. ++2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. + This configure script is free software; the Free Software Foundation + gives unlimited permission to copy, distribute and modify it. + _ACEOF +@@ -1474,7 +1585,7 @@ + running configure, to aid debugging if configure makes a mistake. + + It was created by emacs $as_me 23.1, which was +-generated by GNU Autoconf 2.61. Invocation command line was ++generated by GNU Autoconf 2.63. Invocation command line was + + $ $0 $@ + +@@ -1510,7 +1621,7 @@ + do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. +- echo "PATH: $as_dir" ++ $as_echo "PATH: $as_dir" + done + IFS=$as_save_IFS + +@@ -1545,7 +1656,7 @@ + | -silent | --silent | --silen | --sile | --sil) + continue ;; + *\'*) +- ac_arg=`echo "$ac_arg" | sed "s/'/'\\\\\\\\''/g"` ;; ++ ac_arg=`$as_echo "$ac_arg" | sed "s/'/'\\\\\\\\''/g"` ;; + esac + case $ac_pass in + 1) ac_configure_args0="$ac_configure_args0 '$ac_arg'" ;; +@@ -1597,11 +1708,12 @@ + case $ac_val in #( + *${as_nl}*) + case $ac_var in #( +- *_cv_*) { echo "$as_me:$LINENO: WARNING: Cache variable $ac_var contains a newline." >&5 +-echo "$as_me: WARNING: Cache variable $ac_var contains a newline." >&2;} ;; ++ *_cv_*) { $as_echo "$as_me:$LINENO: WARNING: cache variable $ac_var contains a newline" >&5 ++$as_echo "$as_me: WARNING: cache variable $ac_var contains a newline" >&2;} ;; + esac + case $ac_var in #( + _ | IFS | as_nl) ;; #( ++ BASH_ARGV | BASH_SOURCE) eval $ac_var= ;; #( + *) $as_unset $ac_var ;; + esac ;; + esac +@@ -1631,9 +1743,9 @@ + do + eval ac_val=\$$ac_var + case $ac_val in +- *\'\''*) ac_val=`echo "$ac_val" | sed "s/'\''/'\''\\\\\\\\'\'''\''/g"`;; ++ *\'\''*) ac_val=`$as_echo "$ac_val" | sed "s/'\''/'\''\\\\\\\\'\'''\''/g"`;; + esac +- echo "$ac_var='\''$ac_val'\''" ++ $as_echo "$ac_var='\''$ac_val'\''" + done | sort + echo + +@@ -1648,9 +1760,9 @@ + do + eval ac_val=\$$ac_var + case $ac_val in +- *\'\''*) ac_val=`echo "$ac_val" | sed "s/'\''/'\''\\\\\\\\'\'''\''/g"`;; ++ *\'\''*) ac_val=`$as_echo "$ac_val" | sed "s/'\''/'\''\\\\\\\\'\'''\''/g"`;; + esac +- echo "$ac_var='\''$ac_val'\''" ++ $as_echo "$ac_var='\''$ac_val'\''" + done | sort + echo + fi +@@ -1666,8 +1778,8 @@ + echo + fi + test "$ac_signal" != 0 && +- echo "$as_me: caught signal $ac_signal" +- echo "$as_me: exit $exit_status" ++ $as_echo "$as_me: caught signal $ac_signal" ++ $as_echo "$as_me: exit $exit_status" + } >&5 + rm -f core *.core core.conftest.* && + rm -f -r conftest* confdefs* conf$$* $ac_clean_files && +@@ -1709,21 +1821,24 @@ + + + # Let the site file select an alternate cache file if it wants to. +-# Prefer explicitly selected file to automatically selected ones. ++# Prefer an explicitly selected file to automatically selected ones. ++ac_site_file1=NONE ++ac_site_file2=NONE + if test -n "$CONFIG_SITE"; then +- set x "$CONFIG_SITE" ++ ac_site_file1=$CONFIG_SITE + elif test "x$prefix" != xNONE; then +- set x "$prefix/share/config.site" "$prefix/etc/config.site" ++ ac_site_file1=$prefix/share/config.site ++ ac_site_file2=$prefix/etc/config.site + else +- set x "$ac_default_prefix/share/config.site" \ +- "$ac_default_prefix/etc/config.site" ++ ac_site_file1=$ac_default_prefix/share/config.site ++ ac_site_file2=$ac_default_prefix/etc/config.site + fi +-shift +-for ac_site_file ++for ac_site_file in "$ac_site_file1" "$ac_site_file2" + do ++ test "x$ac_site_file" = xNONE && continue + if test -r "$ac_site_file"; then +- { echo "$as_me:$LINENO: loading site script $ac_site_file" >&5 +-echo "$as_me: loading site script $ac_site_file" >&6;} ++ { $as_echo "$as_me:$LINENO: loading site script $ac_site_file" >&5 ++$as_echo "$as_me: loading site script $ac_site_file" >&6;} + sed 's/^/| /' "$ac_site_file" >&5 + . "$ac_site_file" + fi +@@ -1733,16 +1848,16 @@ + # Some versions of bash will fail to source /dev/null (special + # files actually), so we avoid doing that. + if test -f "$cache_file"; then +- { echo "$as_me:$LINENO: loading cache $cache_file" >&5 +-echo "$as_me: loading cache $cache_file" >&6;} ++ { $as_echo "$as_me:$LINENO: loading cache $cache_file" >&5 ++$as_echo "$as_me: loading cache $cache_file" >&6;} + case $cache_file in + [\\/]* | ?:[\\/]* ) . "$cache_file";; + *) . "./$cache_file";; + esac + fi + else +- { echo "$as_me:$LINENO: creating cache $cache_file" >&5 +-echo "$as_me: creating cache $cache_file" >&6;} ++ { $as_echo "$as_me:$LINENO: creating cache $cache_file" >&5 ++$as_echo "$as_me: creating cache $cache_file" >&6;} + >$cache_file + fi + +@@ -1759,29 +1874,38 @@ + eval ac_new_val=\$ac_env_${ac_var}_value + case $ac_old_set,$ac_new_set in + set,) +- { echo "$as_me:$LINENO: error: \`$ac_var' was set to \`$ac_old_val' in the previous run" >&5 +-echo "$as_me: error: \`$ac_var' was set to \`$ac_old_val' in the previous run" >&2;} ++ { $as_echo "$as_me:$LINENO: error: \`$ac_var' was set to \`$ac_old_val' in the previous run" >&5 ++$as_echo "$as_me: error: \`$ac_var' was set to \`$ac_old_val' in the previous run" >&2;} + ac_cache_corrupted=: ;; + ,set) +- { echo "$as_me:$LINENO: error: \`$ac_var' was not set in the previous run" >&5 +-echo "$as_me: error: \`$ac_var' was not set in the previous run" >&2;} ++ { $as_echo "$as_me:$LINENO: error: \`$ac_var' was not set in the previous run" >&5 ++$as_echo "$as_me: error: \`$ac_var' was not set in the previous run" >&2;} + ac_cache_corrupted=: ;; + ,);; + *) + if test "x$ac_old_val" != "x$ac_new_val"; then +- { echo "$as_me:$LINENO: error: \`$ac_var' has changed since the previous run:" >&5 +-echo "$as_me: error: \`$ac_var' has changed since the previous run:" >&2;} +- { echo "$as_me:$LINENO: former value: $ac_old_val" >&5 +-echo "$as_me: former value: $ac_old_val" >&2;} +- { echo "$as_me:$LINENO: current value: $ac_new_val" >&5 +-echo "$as_me: current value: $ac_new_val" >&2;} +- ac_cache_corrupted=: ++ # differences in whitespace do not lead to failure. ++ ac_old_val_w=`echo x $ac_old_val` ++ ac_new_val_w=`echo x $ac_new_val` ++ if test "$ac_old_val_w" != "$ac_new_val_w"; then ++ { $as_echo "$as_me:$LINENO: error: \`$ac_var' has changed since the previous run:" >&5 ++$as_echo "$as_me: error: \`$ac_var' has changed since the previous run:" >&2;} ++ ac_cache_corrupted=: ++ else ++ { $as_echo "$as_me:$LINENO: warning: ignoring whitespace changes in \`$ac_var' since the previous run:" >&5 ++$as_echo "$as_me: warning: ignoring whitespace changes in \`$ac_var' since the previous run:" >&2;} ++ eval $ac_var=\$ac_old_val ++ fi ++ { $as_echo "$as_me:$LINENO: former value: \`$ac_old_val'" >&5 ++$as_echo "$as_me: former value: \`$ac_old_val'" >&2;} ++ { $as_echo "$as_me:$LINENO: current value: \`$ac_new_val'" >&5 ++$as_echo "$as_me: current value: \`$ac_new_val'" >&2;} + fi;; + esac + # Pass precious variables to config.status. + if test "$ac_new_set" = set; then + case $ac_new_val in +- *\'*) ac_arg=$ac_var=`echo "$ac_new_val" | sed "s/'/'\\\\\\\\''/g"` ;; ++ *\'*) ac_arg=$ac_var=`$as_echo "$ac_new_val" | sed "s/'/'\\\\\\\\''/g"` ;; + *) ac_arg=$ac_var=$ac_new_val ;; + esac + case " $ac_configure_args " in +@@ -1791,10 +1915,12 @@ + fi + done + if $ac_cache_corrupted; then +- { echo "$as_me:$LINENO: error: changes in the environment can compromise the build" >&5 +-echo "$as_me: error: changes in the environment can compromise the build" >&2;} +- { { echo "$as_me:$LINENO: error: run \`make distclean' and/or \`rm $cache_file' and start over" >&5 +-echo "$as_me: error: run \`make distclean' and/or \`rm $cache_file' and start over" >&2;} ++ { $as_echo "$as_me:$LINENO: error: in \`$ac_pwd':" >&5 ++$as_echo "$as_me: error: in \`$ac_pwd':" >&2;} ++ { $as_echo "$as_me:$LINENO: error: changes in the environment can compromise the build" >&5 ++$as_echo "$as_me: error: changes in the environment can compromise the build" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: run \`make distclean' and/or \`rm $cache_file' and start over" >&5 ++$as_echo "$as_me: error: run \`make distclean' and/or \`rm $cache_file' and start over" >&2;} + { (exit 1); exit 1; }; } + fi + +@@ -1838,13 +1964,10 @@ + # Use a double $ so make ignores it. + test "$program_suffix" != NONE && + program_transform_name="s&\$&$program_suffix&;$program_transform_name" +-# Double any \ or $. echo might interpret backslashes. ++# Double any \ or $. + # By default was `s,x,x', remove it if useless. +-cat <<\_ACEOF >conftest.sed +-s/[\\$]/&&/g;s/;s,x,x,$// +-_ACEOF +-program_transform_name=`echo $program_transform_name | sed -f conftest.sed` +-rm -f conftest.sed ++ac_script='s/[\\$]/&&/g;s/;s,x,x,$//' ++program_transform_name=`$as_echo "$program_transform_name" | sed "$ac_script"` + + + lispdir='${datadir}/emacs/${version}/lisp' +@@ -1967,10 +2090,10 @@ + m | mo | mot | moti | motif ) val=motif ;; + g | gt | gtk ) val=gtk ;; + * ) +-{ { echo "$as_me:$LINENO: error: \`--with-x-toolkit=$withval' is invalid; ++{ { $as_echo "$as_me:$LINENO: error: \`--with-x-toolkit=$withval' is invalid; + this option's value should be \`yes', \`no', \`lucid', \`athena', \`motif' or \`gtk'. + \`yes' and \`gtk' are synonyms. \`athena' and \`lucid' are synonyms." >&5 +-echo "$as_me: error: \`--with-x-toolkit=$withval' is invalid; ++$as_echo "$as_me: error: \`--with-x-toolkit=$withval' is invalid; + this option's value should be \`yes', \`no', \`lucid', \`athena', \`motif' or \`gtk'. + \`yes' and \`gtk' are synonyms. \`athena' and \`lucid' are synonyms." >&2;} + { (exit 1); exit 1; }; } +@@ -2119,9 +2242,9 @@ + + # Check whether --with-gtk was given. + if test "${with_gtk+set}" = set; then +- withval=$with_gtk; { { echo "$as_me:$LINENO: error: --with-gtk has been removed. Use --with-x-toolkit to ++ withval=$with_gtk; { { $as_echo "$as_me:$LINENO: error: --with-gtk has been removed. Use --with-x-toolkit to + specify a toolkit." >&5 +-echo "$as_me: error: --with-gtk has been removed. Use --with-x-toolkit to ++$as_echo "$as_me: error: --with-gtk has been removed. Use --with-x-toolkit to + specify a toolkit." >&2;} + { (exit 1); exit 1; }; } + fi +@@ -2130,9 +2253,9 @@ + + # Check whether --with-gcc was given. + if test "${with_gcc+set}" = set; then +- withval=$with_gcc; { { echo "$as_me:$LINENO: error: --with-gcc has been removed. Set the \`CC' environment ++ withval=$with_gcc; { { $as_echo "$as_me:$LINENO: error: --with-gcc has been removed. Set the \`CC' environment + variable to specify a compiler." >&5 +-echo "$as_me: error: --with-gcc has been removed. Set the \`CC' environment ++$as_echo "$as_me: error: --with-gcc has been removed. Set the \`CC' environment + variable to specify a compiler." >&2;} + { (exit 1); exit 1; }; } + fi +@@ -2228,13 +2351,13 @@ + #### Check if the source directory already has a configured system in it. + if test `pwd` != `(cd ${srcdir} && pwd)` \ + && test -f "${srcdir}/src/config.h" ; then +- { echo "$as_me:$LINENO: WARNING: The directory tree \`${srcdir}' is being used ++ { $as_echo "$as_me:$LINENO: WARNING: The directory tree \`${srcdir}' is being used + as a build directory right now; it has been configured in its own + right. To configure in another directory as well, you MUST + use GNU make. If you do not have GNU make, then you must + now do \`make distclean' in ${srcdir}, + and then run $0 again." >&5 +-echo "$as_me: WARNING: The directory tree \`${srcdir}' is being used ++$as_echo "$as_me: WARNING: The directory tree \`${srcdir}' is being used + as a build directory right now; it has been configured in its own + right. To configure in another directory as well, you MUST + use GNU make. If you do not have GNU make, then you must +@@ -2264,8 +2387,8 @@ + fi + done + if test -z "$ac_aux_dir"; then +- { { echo "$as_me:$LINENO: error: cannot find install-sh or install.sh in \"$srcdir\" \"$srcdir/..\" \"$srcdir/../..\"" >&5 +-echo "$as_me: error: cannot find install-sh or install.sh in \"$srcdir\" \"$srcdir/..\" \"$srcdir/../..\"" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: cannot find install-sh or install.sh in \"$srcdir\" \"$srcdir/..\" \"$srcdir/../..\"" >&5 ++$as_echo "$as_me: error: cannot find install-sh or install.sh in \"$srcdir\" \"$srcdir/..\" \"$srcdir/../..\"" >&2;} + { (exit 1); exit 1; }; } + fi + +@@ -2280,34 +2403,34 @@ + + # Make sure we can run config.sub. + $SHELL "$ac_aux_dir/config.sub" sun4 >/dev/null 2>&1 || +- { { echo "$as_me:$LINENO: error: cannot run $SHELL $ac_aux_dir/config.sub" >&5 +-echo "$as_me: error: cannot run $SHELL $ac_aux_dir/config.sub" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: cannot run $SHELL $ac_aux_dir/config.sub" >&5 ++$as_echo "$as_me: error: cannot run $SHELL $ac_aux_dir/config.sub" >&2;} + { (exit 1); exit 1; }; } + +-{ echo "$as_me:$LINENO: checking build system type" >&5 +-echo $ECHO_N "checking build system type... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking build system type" >&5 ++$as_echo_n "checking build system type... " >&6; } + if test "${ac_cv_build+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_build_alias=$build_alias + test "x$ac_build_alias" = x && + ac_build_alias=`$SHELL "$ac_aux_dir/config.guess"` + test "x$ac_build_alias" = x && +- { { echo "$as_me:$LINENO: error: cannot guess build type; you must specify one" >&5 +-echo "$as_me: error: cannot guess build type; you must specify one" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: cannot guess build type; you must specify one" >&5 ++$as_echo "$as_me: error: cannot guess build type; you must specify one" >&2;} + { (exit 1); exit 1; }; } + ac_cv_build=`$SHELL "$ac_aux_dir/config.sub" $ac_build_alias` || +- { { echo "$as_me:$LINENO: error: $SHELL $ac_aux_dir/config.sub $ac_build_alias failed" >&5 +-echo "$as_me: error: $SHELL $ac_aux_dir/config.sub $ac_build_alias failed" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: $SHELL $ac_aux_dir/config.sub $ac_build_alias failed" >&5 ++$as_echo "$as_me: error: $SHELL $ac_aux_dir/config.sub $ac_build_alias failed" >&2;} + { (exit 1); exit 1; }; } + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_build" >&5 +-echo "${ECHO_T}$ac_cv_build" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_build" >&5 ++$as_echo "$ac_cv_build" >&6; } + case $ac_cv_build in + *-*-*) ;; +-*) { { echo "$as_me:$LINENO: error: invalid value of canonical build" >&5 +-echo "$as_me: error: invalid value of canonical build" >&2;} ++*) { { $as_echo "$as_me:$LINENO: error: invalid value of canonical build" >&5 ++$as_echo "$as_me: error: invalid value of canonical build" >&2;} + { (exit 1); exit 1; }; };; + esac + build=$ac_cv_build +@@ -2324,27 +2447,27 @@ + case $build_os in *\ *) build_os=`echo "$build_os" | sed 's/ /-/g'`;; esac + + +-{ echo "$as_me:$LINENO: checking host system type" >&5 +-echo $ECHO_N "checking host system type... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking host system type" >&5 ++$as_echo_n "checking host system type... " >&6; } + if test "${ac_cv_host+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test "x$host_alias" = x; then + ac_cv_host=$ac_cv_build + else + ac_cv_host=`$SHELL "$ac_aux_dir/config.sub" $host_alias` || +- { { echo "$as_me:$LINENO: error: $SHELL $ac_aux_dir/config.sub $host_alias failed" >&5 +-echo "$as_me: error: $SHELL $ac_aux_dir/config.sub $host_alias failed" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: $SHELL $ac_aux_dir/config.sub $host_alias failed" >&5 ++$as_echo "$as_me: error: $SHELL $ac_aux_dir/config.sub $host_alias failed" >&2;} + { (exit 1); exit 1; }; } + fi + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_host" >&5 +-echo "${ECHO_T}$ac_cv_host" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_host" >&5 ++$as_echo "$ac_cv_host" >&6; } + case $ac_cv_host in + *-*-*) ;; +-*) { { echo "$as_me:$LINENO: error: invalid value of canonical host" >&5 +-echo "$as_me: error: invalid value of canonical host" >&2;} ++*) { { $as_echo "$as_me:$LINENO: error: invalid value of canonical host" >&5 ++$as_echo "$as_me: error: invalid value of canonical host" >&2;} + { (exit 1); exit 1; }; };; + esac + host=$ac_cv_host +@@ -2426,7 +2549,7 @@ + if test -f /usr/lib/crti.o; then + + cat >>confdefs.h <<\_ACEOF +-#define HAVE_CRTIN ++#define HAVE_CRTIN /**/ + _ACEOF + + fi +@@ -2701,9 +2824,9 @@ + + + if test $unported = yes; then +- { { echo "$as_me:$LINENO: error: Emacs hasn't been ported to \`${canonical}' systems. ++ { { $as_echo "$as_me:$LINENO: error: Emacs hasn't been ported to \`${canonical}' systems. + Check \`etc/MACHINES' for recognized configuration names." >&5 +-echo "$as_me: error: Emacs hasn't been ported to \`${canonical}' systems. ++$as_echo "$as_me: error: Emacs hasn't been ported to \`${canonical}' systems. + Check \`etc/MACHINES' for recognized configuration names." >&2;} + { (exit 1); exit 1; }; } + fi +@@ -2726,10 +2849,10 @@ + if test -n "$ac_tool_prefix"; then + # Extract the first word of "${ac_tool_prefix}gcc", so it can be a program name with args. + set dummy ${ac_tool_prefix}gcc; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_CC+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +@@ -2742,7 +2865,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_CC="${ac_tool_prefix}gcc" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -2753,11 +2876,11 @@ + fi + CC=$ac_cv_prog_CC + if test -n "$CC"; then +- { echo "$as_me:$LINENO: result: $CC" >&5 +-echo "${ECHO_T}$CC" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $CC" >&5 ++$as_echo "$CC" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -2766,10 +2889,10 @@ + ac_ct_CC=$CC + # Extract the first word of "gcc", so it can be a program name with args. + set dummy gcc; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_ac_ct_CC+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$ac_ct_CC"; then + ac_cv_prog_ac_ct_CC="$ac_ct_CC" # Let the user override the test. +@@ -2782,7 +2905,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_ac_ct_CC="gcc" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -2793,11 +2916,11 @@ + fi + ac_ct_CC=$ac_cv_prog_ac_ct_CC + if test -n "$ac_ct_CC"; then +- { echo "$as_me:$LINENO: result: $ac_ct_CC" >&5 +-echo "${ECHO_T}$ac_ct_CC" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $ac_ct_CC" >&5 ++$as_echo "$ac_ct_CC" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + if test "x$ac_ct_CC" = x; then +@@ -2805,12 +2928,8 @@ + else + case $cross_compiling:$ac_tool_warned in + yes:) +-{ echo "$as_me:$LINENO: WARNING: In the future, Autoconf will not detect cross-tools +-whose name does not start with the host triplet. If you think this +-configuration is useful to you, please write to autoconf@gnu.org." >&5 +-echo "$as_me: WARNING: In the future, Autoconf will not detect cross-tools +-whose name does not start with the host triplet. If you think this +-configuration is useful to you, please write to autoconf@gnu.org." >&2;} ++{ $as_echo "$as_me:$LINENO: WARNING: using cross tools not prefixed with host triplet" >&5 ++$as_echo "$as_me: WARNING: using cross tools not prefixed with host triplet" >&2;} + ac_tool_warned=yes ;; + esac + CC=$ac_ct_CC +@@ -2823,10 +2942,10 @@ + if test -n "$ac_tool_prefix"; then + # Extract the first word of "${ac_tool_prefix}cc", so it can be a program name with args. + set dummy ${ac_tool_prefix}cc; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_CC+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +@@ -2839,7 +2958,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_CC="${ac_tool_prefix}cc" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -2850,11 +2969,11 @@ + fi + CC=$ac_cv_prog_CC + if test -n "$CC"; then +- { echo "$as_me:$LINENO: result: $CC" >&5 +-echo "${ECHO_T}$CC" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $CC" >&5 ++$as_echo "$CC" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -2863,10 +2982,10 @@ + if test -z "$CC"; then + # Extract the first word of "cc", so it can be a program name with args. + set dummy cc; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_CC+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +@@ -2884,7 +3003,7 @@ + continue + fi + ac_cv_prog_CC="cc" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -2907,11 +3026,11 @@ + fi + CC=$ac_cv_prog_CC + if test -n "$CC"; then +- { echo "$as_me:$LINENO: result: $CC" >&5 +-echo "${ECHO_T}$CC" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $CC" >&5 ++$as_echo "$CC" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -2922,10 +3041,10 @@ + do + # Extract the first word of "$ac_tool_prefix$ac_prog", so it can be a program name with args. + set dummy $ac_tool_prefix$ac_prog; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_CC+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +@@ -2938,7 +3057,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_CC="$ac_tool_prefix$ac_prog" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -2949,11 +3068,11 @@ + fi + CC=$ac_cv_prog_CC + if test -n "$CC"; then +- { echo "$as_me:$LINENO: result: $CC" >&5 +-echo "${ECHO_T}$CC" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $CC" >&5 ++$as_echo "$CC" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -2966,10 +3085,10 @@ + do + # Extract the first word of "$ac_prog", so it can be a program name with args. + set dummy $ac_prog; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_ac_ct_CC+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$ac_ct_CC"; then + ac_cv_prog_ac_ct_CC="$ac_ct_CC" # Let the user override the test. +@@ -2982,7 +3101,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_ac_ct_CC="$ac_prog" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -2993,11 +3112,11 @@ + fi + ac_ct_CC=$ac_cv_prog_ac_ct_CC + if test -n "$ac_ct_CC"; then +- { echo "$as_me:$LINENO: result: $ac_ct_CC" >&5 +-echo "${ECHO_T}$ac_ct_CC" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $ac_ct_CC" >&5 ++$as_echo "$ac_ct_CC" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -3009,12 +3128,8 @@ + else + case $cross_compiling:$ac_tool_warned in + yes:) +-{ echo "$as_me:$LINENO: WARNING: In the future, Autoconf will not detect cross-tools +-whose name does not start with the host triplet. If you think this +-configuration is useful to you, please write to autoconf@gnu.org." >&5 +-echo "$as_me: WARNING: In the future, Autoconf will not detect cross-tools +-whose name does not start with the host triplet. If you think this +-configuration is useful to you, please write to autoconf@gnu.org." >&2;} ++{ $as_echo "$as_me:$LINENO: WARNING: using cross tools not prefixed with host triplet" >&5 ++$as_echo "$as_me: WARNING: using cross tools not prefixed with host triplet" >&2;} + ac_tool_warned=yes ;; + esac + CC=$ac_ct_CC +@@ -3024,44 +3139,50 @@ + fi + + +-test -z "$CC" && { { echo "$as_me:$LINENO: error: no acceptable C compiler found in \$PATH ++test -z "$CC" && { { $as_echo "$as_me:$LINENO: error: in \`$ac_pwd':" >&5 ++$as_echo "$as_me: error: in \`$ac_pwd':" >&2;} ++{ { $as_echo "$as_me:$LINENO: error: no acceptable C compiler found in \$PATH + See \`config.log' for more details." >&5 +-echo "$as_me: error: no acceptable C compiler found in \$PATH ++$as_echo "$as_me: error: no acceptable C compiler found in \$PATH + See \`config.log' for more details." >&2;} +- { (exit 1); exit 1; }; } ++ { (exit 1); exit 1; }; }; } + + # Provide some information about the compiler. +-echo "$as_me:$LINENO: checking for C compiler version" >&5 +-ac_compiler=`set X $ac_compile; echo $2` ++$as_echo "$as_me:$LINENO: checking for C compiler version" >&5 ++set X $ac_compile ++ac_compiler=$2 + { (ac_try="$ac_compiler --version >&5" + case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compiler --version >&5") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } + { (ac_try="$ac_compiler -v >&5" + case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compiler -v >&5") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } + { (ac_try="$ac_compiler -V >&5" + case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compiler -V >&5") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } + + cat >conftest.$ac_ext <<_ACEOF +@@ -3080,27 +3201,22 @@ + } + _ACEOF + ac_clean_files_save=$ac_clean_files +-ac_clean_files="$ac_clean_files a.out a.exe b.out" ++ac_clean_files="$ac_clean_files a.out a.out.dSYM a.exe b.out" + # Try to create an executable without -o first, disregard a.out. + # It will help us diagnose broken compilers, and finding out an intuition + # of exeext. +-{ echo "$as_me:$LINENO: checking for C compiler default output file name" >&5 +-echo $ECHO_N "checking for C compiler default output file name... $ECHO_C" >&6; } +-ac_link_default=`echo "$ac_link" | sed 's/ -o *conftest[^ ]*//'` +-# +-# List of possible output files, starting from the most likely. +-# The algorithm is not robust to junk in `.', hence go to wildcards (a.*) +-# only as a last resort. b.out is created by i960 compilers. +-ac_files='a_out.exe a.exe conftest.exe a.out conftest a.* conftest.* b.out' +-# +-# The IRIX 6 linker writes into existing files which may not be +-# executable, retaining their permissions. Remove them first so a +-# subsequent execution test works. ++{ $as_echo "$as_me:$LINENO: checking for C compiler default output file name" >&5 ++$as_echo_n "checking for C compiler default output file name... " >&6; } ++ac_link_default=`$as_echo "$ac_link" | sed 's/ -o *conftest[^ ]*//'` ++ ++# The possible output files: ++ac_files="a.out conftest.exe conftest a.exe a_out.exe b.out conftest.*" ++ + ac_rmfiles= + for ac_file in $ac_files + do + case $ac_file in +- *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.o | *.obj ) ;; ++ *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.dSYM | *.o | *.obj ) ;; + * ) ac_rmfiles="$ac_rmfiles $ac_file";; + esac + done +@@ -3111,10 +3227,11 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link_default") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; then + # Autoconf-2.13 could set the ac_cv_exeext variable to `no'. + # So ignore a value of `no', otherwise this would lead to `EXEEXT = no' +@@ -3125,7 +3242,7 @@ + do + test -f "$ac_file" || continue + case $ac_file in +- *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.o | *.obj ) ++ *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.dSYM | *.o | *.obj ) + ;; + [ab].out ) + # We found the default executable, but exeext='' is most +@@ -3152,25 +3269,27 @@ + ac_file='' + fi + +-{ echo "$as_me:$LINENO: result: $ac_file" >&5 +-echo "${ECHO_T}$ac_file" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_file" >&5 ++$as_echo "$ac_file" >&6; } + if test -z "$ac_file"; then +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + +-{ { echo "$as_me:$LINENO: error: C compiler cannot create executables ++{ { $as_echo "$as_me:$LINENO: error: in \`$ac_pwd':" >&5 ++$as_echo "$as_me: error: in \`$ac_pwd':" >&2;} ++{ { $as_echo "$as_me:$LINENO: error: C compiler cannot create executables + See \`config.log' for more details." >&5 +-echo "$as_me: error: C compiler cannot create executables ++$as_echo "$as_me: error: C compiler cannot create executables + See \`config.log' for more details." >&2;} +- { (exit 77); exit 77; }; } ++ { (exit 77); exit 77; }; }; } + fi + + ac_exeext=$ac_cv_exeext + + # Check that the compiler produces executables we can run. If not, either + # the compiler is broken, or we cross compile. +-{ echo "$as_me:$LINENO: checking whether the C compiler works" >&5 +-echo $ECHO_N "checking whether the C compiler works... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether the C compiler works" >&5 ++$as_echo_n "checking whether the C compiler works... " >&6; } + # FIXME: These cross compiler hacks should be removed for Autoconf 3.0 + # If not cross compiling, check that we can run a simple program. + if test "$cross_compiling" != yes; then +@@ -3179,49 +3298,53 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + cross_compiling=no + else + if test "$cross_compiling" = maybe; then + cross_compiling=yes + else +- { { echo "$as_me:$LINENO: error: cannot run C compiled programs. ++ { { $as_echo "$as_me:$LINENO: error: in \`$ac_pwd':" >&5 ++$as_echo "$as_me: error: in \`$ac_pwd':" >&2;} ++{ { $as_echo "$as_me:$LINENO: error: cannot run C compiled programs. + If you meant to cross compile, use \`--host'. + See \`config.log' for more details." >&5 +-echo "$as_me: error: cannot run C compiled programs. ++$as_echo "$as_me: error: cannot run C compiled programs. + If you meant to cross compile, use \`--host'. + See \`config.log' for more details." >&2;} +- { (exit 1); exit 1; }; } ++ { (exit 1); exit 1; }; }; } + fi + fi + fi +-{ echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++{ $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + +-rm -f a.out a.exe conftest$ac_cv_exeext b.out ++rm -f -r a.out a.out.dSYM a.exe conftest$ac_cv_exeext b.out + ac_clean_files=$ac_clean_files_save + # Check that the compiler produces executables we can run. If not, either + # the compiler is broken, or we cross compile. +-{ echo "$as_me:$LINENO: checking whether we are cross compiling" >&5 +-echo $ECHO_N "checking whether we are cross compiling... $ECHO_C" >&6; } +-{ echo "$as_me:$LINENO: result: $cross_compiling" >&5 +-echo "${ECHO_T}$cross_compiling" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether we are cross compiling" >&5 ++$as_echo_n "checking whether we are cross compiling... " >&6; } ++{ $as_echo "$as_me:$LINENO: result: $cross_compiling" >&5 ++$as_echo "$cross_compiling" >&6; } + +-{ echo "$as_me:$LINENO: checking for suffix of executables" >&5 +-echo $ECHO_N "checking for suffix of executables... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for suffix of executables" >&5 ++$as_echo_n "checking for suffix of executables... " >&6; } + if { (ac_try="$ac_link" + case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; then + # If both `conftest.exe' and `conftest' are `present' (well, observable) + # catch `conftest.exe'. For instance with Cygwin, `ls conftest' will +@@ -3230,31 +3353,33 @@ + for ac_file in conftest.exe conftest conftest.*; do + test -f "$ac_file" || continue + case $ac_file in +- *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.o | *.obj ) ;; ++ *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.dSYM | *.o | *.obj ) ;; + *.* ) ac_cv_exeext=`expr "$ac_file" : '[^.]*\(\..*\)'` + break;; + * ) break;; + esac + done + else +- { { echo "$as_me:$LINENO: error: cannot compute suffix of executables: cannot compile and link ++ { { $as_echo "$as_me:$LINENO: error: in \`$ac_pwd':" >&5 ++$as_echo "$as_me: error: in \`$ac_pwd':" >&2;} ++{ { $as_echo "$as_me:$LINENO: error: cannot compute suffix of executables: cannot compile and link + See \`config.log' for more details." >&5 +-echo "$as_me: error: cannot compute suffix of executables: cannot compile and link ++$as_echo "$as_me: error: cannot compute suffix of executables: cannot compile and link + See \`config.log' for more details." >&2;} +- { (exit 1); exit 1; }; } ++ { (exit 1); exit 1; }; }; } + fi + + rm -f conftest$ac_cv_exeext +-{ echo "$as_me:$LINENO: result: $ac_cv_exeext" >&5 +-echo "${ECHO_T}$ac_cv_exeext" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_exeext" >&5 ++$as_echo "$ac_cv_exeext" >&6; } + + rm -f conftest.$ac_ext + EXEEXT=$ac_cv_exeext + ac_exeext=$EXEEXT +-{ echo "$as_me:$LINENO: checking for suffix of object files" >&5 +-echo $ECHO_N "checking for suffix of object files... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for suffix of object files" >&5 ++$as_echo_n "checking for suffix of object files... " >&6; } + if test "${ac_cv_objext+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -3277,40 +3402,43 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; then + for ac_file in conftest.o conftest.obj conftest.*; do + test -f "$ac_file" || continue; + case $ac_file in +- *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf ) ;; ++ *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.dSYM ) ;; + *) ac_cv_objext=`expr "$ac_file" : '.*\.\(.*\)'` + break;; + esac + done + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + +-{ { echo "$as_me:$LINENO: error: cannot compute suffix of object files: cannot compile ++{ { $as_echo "$as_me:$LINENO: error: in \`$ac_pwd':" >&5 ++$as_echo "$as_me: error: in \`$ac_pwd':" >&2;} ++{ { $as_echo "$as_me:$LINENO: error: cannot compute suffix of object files: cannot compile + See \`config.log' for more details." >&5 +-echo "$as_me: error: cannot compute suffix of object files: cannot compile ++$as_echo "$as_me: error: cannot compute suffix of object files: cannot compile + See \`config.log' for more details." >&2;} +- { (exit 1); exit 1; }; } ++ { (exit 1); exit 1; }; }; } + fi + + rm -f conftest.$ac_cv_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_objext" >&5 +-echo "${ECHO_T}$ac_cv_objext" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_objext" >&5 ++$as_echo "$ac_cv_objext" >&6; } + OBJEXT=$ac_cv_objext + ac_objext=$OBJEXT +-{ echo "$as_me:$LINENO: checking whether we are using the GNU C compiler" >&5 +-echo $ECHO_N "checking whether we are using the GNU C compiler... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether we are using the GNU C compiler" >&5 ++$as_echo_n "checking whether we are using the GNU C compiler... " >&6; } + if test "${ac_cv_c_compiler_gnu+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -3336,20 +3464,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_compiler_gnu=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_compiler_gnu=no +@@ -3359,15 +3488,19 @@ + ac_cv_c_compiler_gnu=$ac_compiler_gnu + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_c_compiler_gnu" >&5 +-echo "${ECHO_T}$ac_cv_c_compiler_gnu" >&6; } +-GCC=`test $ac_compiler_gnu = yes && echo yes` ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_c_compiler_gnu" >&5 ++$as_echo "$ac_cv_c_compiler_gnu" >&6; } ++if test $ac_compiler_gnu = yes; then ++ GCC=yes ++else ++ GCC= ++fi + ac_test_CFLAGS=${CFLAGS+set} + ac_save_CFLAGS=$CFLAGS +-{ echo "$as_me:$LINENO: checking whether $CC accepts -g" >&5 +-echo $ECHO_N "checking whether $CC accepts -g... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether $CC accepts -g" >&5 ++$as_echo_n "checking whether $CC accepts -g... " >&6; } + if test "${ac_cv_prog_cc_g+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_save_c_werror_flag=$ac_c_werror_flag + ac_c_werror_flag=yes +@@ -3394,20 +3527,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_prog_cc_g=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + CFLAGS="" +@@ -3432,20 +3566,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + : + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_c_werror_flag=$ac_save_c_werror_flag +@@ -3471,20 +3606,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_prog_cc_g=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + +@@ -3499,8 +3635,8 @@ + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + ac_c_werror_flag=$ac_save_c_werror_flag + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_prog_cc_g" >&5 +-echo "${ECHO_T}$ac_cv_prog_cc_g" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_prog_cc_g" >&5 ++$as_echo "$ac_cv_prog_cc_g" >&6; } + if test "$ac_test_CFLAGS" = set; then + CFLAGS=$ac_save_CFLAGS + elif test $ac_cv_prog_cc_g = yes; then +@@ -3516,10 +3652,10 @@ + CFLAGS= + fi + fi +-{ echo "$as_me:$LINENO: checking for $CC option to accept ISO C89" >&5 +-echo $ECHO_N "checking for $CC option to accept ISO C89... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $CC option to accept ISO C89" >&5 ++$as_echo_n "checking for $CC option to accept ISO C89... " >&6; } + if test "${ac_cv_prog_cc_c89+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_prog_cc_c89=no + ac_save_CC=$CC +@@ -3590,20 +3726,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_prog_cc_c89=$ac_arg + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + +@@ -3619,15 +3756,15 @@ + # AC_CACHE_VAL + case "x$ac_cv_prog_cc_c89" in + x) +- { echo "$as_me:$LINENO: result: none needed" >&5 +-echo "${ECHO_T}none needed" >&6; } ;; ++ { $as_echo "$as_me:$LINENO: result: none needed" >&5 ++$as_echo "none needed" >&6; } ;; + xno) +- { echo "$as_me:$LINENO: result: unsupported" >&5 +-echo "${ECHO_T}unsupported" >&6; } ;; ++ { $as_echo "$as_me:$LINENO: result: unsupported" >&5 ++$as_echo "unsupported" >&6; } ;; + *) + CC="$CC $ac_cv_prog_cc_c89" +- { echo "$as_me:$LINENO: result: $ac_cv_prog_cc_c89" >&5 +-echo "${ECHO_T}$ac_cv_prog_cc_c89" >&6; } ;; ++ { $as_echo "$as_me:$LINENO: result: $ac_cv_prog_cc_c89" >&5 ++$as_echo "$ac_cv_prog_cc_c89" >&6; } ;; + esac + + +@@ -3647,11 +3784,11 @@ + ## using a Sun compiler, which needs -Xs to prevent whitespace. + if test x"$GCC" != xyes && test x"$emacs_check_sunpro_c" = xyes && \ + test x"$CPP" = x; then +- { echo "$as_me:$LINENO: checking whether we are using a Sun C compiler" >&5 +-echo $ECHO_N "checking whether we are using a Sun C compiler... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether we are using a Sun C compiler" >&5 ++$as_echo_n "checking whether we are using a Sun C compiler... " >&6; } + + if test "${emacs_cv_sunpro_c+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -3677,32 +3814,36 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + emacs_cv_sunpro_c=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_sunpro_c=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi + +- { echo "$as_me:$LINENO: result: $emacs_cv_sunpro_c" >&5 +-echo "${ECHO_T}$emacs_cv_sunpro_c" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $emacs_cv_sunpro_c" >&5 ++$as_echo "$emacs_cv_sunpro_c" >&6; } + + if test x"$emacs_cv_sunpro_c" = xyes; then + NON_GNU_CPP="$CC -E -Xs" +@@ -3736,26 +3877,20 @@ + CC="$CC $NON_GCC_TEST_OPTIONS" + fi + +- +-cat >>confdefs.h <<\_ACEOF +-#define _GNU_SOURCE 1 +-_ACEOF +- +- + ac_ext=c + ac_cpp='$CPP $CPPFLAGS' + ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' + ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' + ac_compiler_gnu=$ac_cv_c_compiler_gnu +-{ echo "$as_me:$LINENO: checking how to run the C preprocessor" >&5 +-echo $ECHO_N "checking how to run the C preprocessor... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking how to run the C preprocessor" >&5 ++$as_echo_n "checking how to run the C preprocessor... " >&6; } + # On Suns, sometimes $CPP names a directory. + if test -n "$CPP" && test -d "$CPP"; then + CPP= + fi + if test -z "$CPP"; then + if test "${ac_cv_prog_CPP+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + # Double quotes because CPP needs to be expanded + for CPP in "$CC -E" "$CC -E -traditional-cpp" "/lib/cpp" +@@ -3787,20 +3922,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + : + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + # Broken: fails on valid input. +@@ -3824,13 +3960,14 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err +@@ -3838,7 +3975,7 @@ + # Broken: success on invalid input. + continue + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + # Passes both tests. +@@ -3863,8 +4000,8 @@ + else + ac_cv_prog_CPP=$CPP + fi +-{ echo "$as_me:$LINENO: result: $CPP" >&5 +-echo "${ECHO_T}$CPP" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $CPP" >&5 ++$as_echo "$CPP" >&6; } + ac_preproc_ok=false + for ac_c_preproc_warn_flag in '' yes + do +@@ -3892,20 +4029,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + : + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + # Broken: fails on valid input. +@@ -3929,13 +4067,14 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err +@@ -3943,7 +4082,7 @@ + # Broken: success on invalid input. + continue + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + # Passes both tests. +@@ -3959,11 +4098,13 @@ + if $ac_preproc_ok; then + : + else +- { { echo "$as_me:$LINENO: error: C preprocessor \"$CPP\" fails sanity check ++ { { $as_echo "$as_me:$LINENO: error: in \`$ac_pwd':" >&5 ++$as_echo "$as_me: error: in \`$ac_pwd':" >&2;} ++{ { $as_echo "$as_me:$LINENO: error: C preprocessor \"$CPP\" fails sanity check + See \`config.log' for more details." >&5 +-echo "$as_me: error: C preprocessor \"$CPP\" fails sanity check ++$as_echo "$as_me: error: C preprocessor \"$CPP\" fails sanity check + See \`config.log' for more details." >&2;} +- { (exit 1); exit 1; }; } ++ { (exit 1); exit 1; }; }; } + fi + + ac_ext=c +@@ -3973,42 +4114,37 @@ + ac_compiler_gnu=$ac_cv_c_compiler_gnu + + +-{ echo "$as_me:$LINENO: checking for grep that handles long lines and -e" >&5 +-echo $ECHO_N "checking for grep that handles long lines and -e... $ECHO_C" >&6; } +-if test "${ac_cv_path_GREP+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 +-else +- # Extract the first word of "grep ggrep" to use in msg output +-if test -z "$GREP"; then +-set dummy grep ggrep; ac_prog_name=$2 ++{ $as_echo "$as_me:$LINENO: checking for grep that handles long lines and -e" >&5 ++$as_echo_n "checking for grep that handles long lines and -e... " >&6; } + if test "${ac_cv_path_GREP+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else ++ if test -z "$GREP"; then + ac_path_GREP_found=false +-# Loop through the user's path and test for each of PROGNAME-LIST +-as_save_IFS=$IFS; IFS=$PATH_SEPARATOR ++ # Loop through the user's path and test for each of PROGNAME-LIST ++ as_save_IFS=$IFS; IFS=$PATH_SEPARATOR + for as_dir in $PATH$PATH_SEPARATOR/usr/xpg4/bin + do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_prog in grep ggrep; do +- for ac_exec_ext in '' $ac_executable_extensions; do +- ac_path_GREP="$as_dir/$ac_prog$ac_exec_ext" +- { test -f "$ac_path_GREP" && $as_test_x "$ac_path_GREP"; } || continue +- # Check for GNU ac_path_GREP and select it if it is found. ++ for ac_exec_ext in '' $ac_executable_extensions; do ++ ac_path_GREP="$as_dir/$ac_prog$ac_exec_ext" ++ { test -f "$ac_path_GREP" && $as_test_x "$ac_path_GREP"; } || continue ++# Check for GNU ac_path_GREP and select it if it is found. + # Check for GNU $ac_path_GREP + case `"$ac_path_GREP" --version 2>&1` in + *GNU*) + ac_cv_path_GREP="$ac_path_GREP" ac_path_GREP_found=:;; + *) + ac_count=0 +- echo $ECHO_N "0123456789$ECHO_C" >"conftest.in" ++ $as_echo_n 0123456789 >"conftest.in" + while : + do + cat "conftest.in" "conftest.in" >"conftest.tmp" + mv "conftest.tmp" "conftest.in" + cp "conftest.in" "conftest.nl" +- echo 'GREP' >> "conftest.nl" ++ $as_echo 'GREP' >> "conftest.nl" + "$ac_path_GREP" -e 'GREP$' -e '-(cannot match)-' < "conftest.nl" >"conftest.out" 2>/dev/null || break + diff "conftest.out" "conftest.nl" >/dev/null 2>&1 || break + ac_count=`expr $ac_count + 1` +@@ -4023,74 +4159,60 @@ + rm -f conftest.in conftest.tmp conftest.nl conftest.out;; + esac + +- +- $ac_path_GREP_found && break 3 ++ $ac_path_GREP_found && break 3 ++ done + done + done +- +-done + IFS=$as_save_IFS +- +- +-fi +- +-GREP="$ac_cv_path_GREP" +-if test -z "$GREP"; then +- { { echo "$as_me:$LINENO: error: no acceptable $ac_prog_name could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&5 +-echo "$as_me: error: no acceptable $ac_prog_name could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&2;} ++ if test -z "$ac_cv_path_GREP"; then ++ { { $as_echo "$as_me:$LINENO: error: no acceptable grep could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&5 ++$as_echo "$as_me: error: no acceptable grep could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&2;} + { (exit 1); exit 1; }; } +-fi +- ++ fi + else + ac_cv_path_GREP=$GREP + fi + +- + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_path_GREP" >&5 +-echo "${ECHO_T}$ac_cv_path_GREP" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_path_GREP" >&5 ++$as_echo "$ac_cv_path_GREP" >&6; } + GREP="$ac_cv_path_GREP" + + +-{ echo "$as_me:$LINENO: checking for egrep" >&5 +-echo $ECHO_N "checking for egrep... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for egrep" >&5 ++$as_echo_n "checking for egrep... " >&6; } + if test "${ac_cv_path_EGREP+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if echo a | $GREP -E '(a|b)' >/dev/null 2>&1 + then ac_cv_path_EGREP="$GREP -E" + else +- # Extract the first word of "egrep" to use in msg output +-if test -z "$EGREP"; then +-set dummy egrep; ac_prog_name=$2 +-if test "${ac_cv_path_EGREP+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 +-else ++ if test -z "$EGREP"; then + ac_path_EGREP_found=false +-# Loop through the user's path and test for each of PROGNAME-LIST +-as_save_IFS=$IFS; IFS=$PATH_SEPARATOR ++ # Loop through the user's path and test for each of PROGNAME-LIST ++ as_save_IFS=$IFS; IFS=$PATH_SEPARATOR + for as_dir in $PATH$PATH_SEPARATOR/usr/xpg4/bin + do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_prog in egrep; do +- for ac_exec_ext in '' $ac_executable_extensions; do +- ac_path_EGREP="$as_dir/$ac_prog$ac_exec_ext" +- { test -f "$ac_path_EGREP" && $as_test_x "$ac_path_EGREP"; } || continue +- # Check for GNU ac_path_EGREP and select it if it is found. ++ for ac_exec_ext in '' $ac_executable_extensions; do ++ ac_path_EGREP="$as_dir/$ac_prog$ac_exec_ext" ++ { test -f "$ac_path_EGREP" && $as_test_x "$ac_path_EGREP"; } || continue ++# Check for GNU ac_path_EGREP and select it if it is found. + # Check for GNU $ac_path_EGREP + case `"$ac_path_EGREP" --version 2>&1` in + *GNU*) + ac_cv_path_EGREP="$ac_path_EGREP" ac_path_EGREP_found=:;; + *) + ac_count=0 +- echo $ECHO_N "0123456789$ECHO_C" >"conftest.in" ++ $as_echo_n 0123456789 >"conftest.in" + while : + do + cat "conftest.in" "conftest.in" >"conftest.tmp" + mv "conftest.tmp" "conftest.in" + cp "conftest.in" "conftest.nl" +- echo 'EGREP' >> "conftest.nl" ++ $as_echo 'EGREP' >> "conftest.nl" + "$ac_path_EGREP" 'EGREP$' < "conftest.nl" >"conftest.out" 2>/dev/null || break + diff "conftest.out" "conftest.nl" >/dev/null 2>&1 || break + ac_count=`expr $ac_count + 1` +@@ -4105,69 +4227,31 @@ + rm -f conftest.in conftest.tmp conftest.nl conftest.out;; + esac + +- +- $ac_path_EGREP_found && break 3 ++ $ac_path_EGREP_found && break 3 ++ done + done + done +- +-done + IFS=$as_save_IFS +- +- +-fi +- +-EGREP="$ac_cv_path_EGREP" +-if test -z "$EGREP"; then +- { { echo "$as_me:$LINENO: error: no acceptable $ac_prog_name could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&5 +-echo "$as_me: error: no acceptable $ac_prog_name could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&2;} ++ if test -z "$ac_cv_path_EGREP"; then ++ { { $as_echo "$as_me:$LINENO: error: no acceptable egrep could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&5 ++$as_echo "$as_me: error: no acceptable egrep could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" >&2;} + { (exit 1); exit 1; }; } +-fi +- ++ fi + else + ac_cv_path_EGREP=$EGREP + fi + +- + fi + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_path_EGREP" >&5 +-echo "${ECHO_T}$ac_cv_path_EGREP" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_path_EGREP" >&5 ++$as_echo "$ac_cv_path_EGREP" >&6; } + EGREP="$ac_cv_path_EGREP" + + +- +-{ echo "$as_me:$LINENO: checking for AIX" >&5 +-echo $ECHO_N "checking for AIX... $ECHO_C" >&6; } +-cat >conftest.$ac_ext <<_ACEOF +-/* confdefs.h. */ +-_ACEOF +-cat confdefs.h >>conftest.$ac_ext +-cat >>conftest.$ac_ext <<_ACEOF +-/* end confdefs.h. */ +-#ifdef _AIX +- yes +-#endif +- +-_ACEOF +-if (eval "$ac_cpp conftest.$ac_ext") 2>&5 | +- $EGREP "yes" >/dev/null 2>&1; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } +-cat >>confdefs.h <<\_ACEOF +-#define _ALL_SOURCE 1 +-_ACEOF +- +-else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } +-fi +-rm -f conftest* +- +- +-{ echo "$as_me:$LINENO: checking for ANSI C header files" >&5 +-echo $ECHO_N "checking for ANSI C header files... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for ANSI C header files" >&5 ++$as_echo_n "checking for ANSI C header files... " >&6; } + if test "${ac_cv_header_stdc+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -4194,20 +4278,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_header_stdc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_header_stdc=no +@@ -4299,37 +4384,40 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + : + else +- echo "$as_me: program exited with status $ac_status" >&5 +-echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: program exited with status $ac_status" >&5 ++$as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ( exit $ac_status ) + ac_cv_header_stdc=no + fi ++rm -rf conftest.dSYM + rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext + fi + + + fi + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_stdc" >&5 +-echo "${ECHO_T}$ac_cv_header_stdc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_stdc" >&5 ++$as_echo "$ac_cv_header_stdc" >&6; } + if test $ac_cv_header_stdc = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -4351,11 +4439,11 @@ + for ac_header in sys/types.h sys/stat.h stdlib.h string.h memory.h strings.h \ + inttypes.h stdint.h unistd.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -4373,20 +4461,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + eval "$as_ac_Header=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_Header=no" +@@ -4394,12 +4483,15 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -4407,18 +4499,19 @@ + done + + ++ ++ if test "${ac_cv_header_minix_config_h+set}" = set; then ++ { $as_echo "$as_me:$LINENO: checking for minix/config.h" >&5 ++$as_echo_n "checking for minix/config.h... " >&6; } + if test "${ac_cv_header_minix_config_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for minix/config.h" >&5 +-echo $ECHO_N "checking for minix/config.h... $ECHO_C" >&6; } +-if test "${ac_cv_header_minix_config_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_minix_config_h" >&5 +-echo "${ECHO_T}$ac_cv_header_minix_config_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_minix_config_h" >&5 ++$as_echo "$ac_cv_header_minix_config_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking minix/config.h usability" >&5 +-echo $ECHO_N "checking minix/config.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking minix/config.h usability" >&5 ++$as_echo_n "checking minix/config.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -4434,32 +4527,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking minix/config.h presence" >&5 +-echo $ECHO_N "checking minix/config.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking minix/config.h presence" >&5 ++$as_echo_n "checking minix/config.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -4473,73 +4567,74 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: minix/config.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: minix/config.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: minix/config.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: minix/config.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: minix/config.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: minix/config.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: minix/config.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: minix/config.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: minix/config.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: minix/config.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: minix/config.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: minix/config.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: minix/config.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: minix/config.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: minix/config.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: minix/config.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: minix/config.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: minix/config.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: minix/config.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: minix/config.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: minix/config.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: minix/config.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: minix/config.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: minix/config.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: minix/config.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: minix/config.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: minix/config.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: minix/config.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: minix/config.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: minix/config.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: minix/config.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: minix/config.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for minix/config.h" >&5 +-echo $ECHO_N "checking for minix/config.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for minix/config.h" >&5 ++$as_echo_n "checking for minix/config.h... " >&6; } + if test "${ac_cv_header_minix_config_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_minix_config_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_minix_config_h" >&5 +-echo "${ECHO_T}$ac_cv_header_minix_config_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_minix_config_h" >&5 ++$as_echo "$ac_cv_header_minix_config_h" >&6; } + + fi +-if test $ac_cv_header_minix_config_h = yes; then ++if test "x$ac_cv_header_minix_config_h" = x""yes; then + MINIX=yes + else + MINIX= + fi + + +-if test "$MINIX" = yes; then ++ if test "$MINIX" = yes; then + + cat >>confdefs.h <<\_ACEOF + #define _POSIX_SOURCE 1 +@@ -4555,22 +4650,14 @@ + #define _MINIX 1 + _ACEOF + +-fi +- +- +- +- +- +- +- +- ++ fi + + + +- { echo "$as_me:$LINENO: checking whether it is safe to define __EXTENSIONS__" >&5 +-echo $ECHO_N "checking whether it is safe to define __EXTENSIONS__... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether it is safe to define __EXTENSIONS__" >&5 ++$as_echo_n "checking whether it is safe to define __EXTENSIONS__... " >&6; } + if test "${ac_cv_safe_to_define___extensions__+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -4595,20 +4682,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_safe_to_define___extensions__=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_safe_to_define___extensions__=no +@@ -4616,14 +4704,22 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_safe_to_define___extensions__" >&5 +-echo "${ECHO_T}$ac_cv_safe_to_define___extensions__" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_safe_to_define___extensions__" >&5 ++$as_echo "$ac_cv_safe_to_define___extensions__" >&6; } + test $ac_cv_safe_to_define___extensions__ = yes && + cat >>confdefs.h <<\_ACEOF + #define __EXTENSIONS__ 1 + _ACEOF + + cat >>confdefs.h <<\_ACEOF ++#define _ALL_SOURCE 1 ++_ACEOF ++ ++ cat >>confdefs.h <<\_ACEOF ++#define _GNU_SOURCE 1 ++_ACEOF ++ ++ cat >>confdefs.h <<\_ACEOF + #define _POSIX_PTHREAD_SEMANTICS 1 + _ACEOF + +@@ -4634,8 +4730,8 @@ + + + ### Use -Wno-pointer-sign if the compiler supports it +-{ echo "$as_me:$LINENO: checking whether gcc understands -Wno-pointer-sign" >&5 +-echo $ECHO_N "checking whether gcc understands -Wno-pointer-sign... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether gcc understands -Wno-pointer-sign" >&5 ++$as_echo_n "checking whether gcc understands -Wno-pointer-sign... " >&6; } + SAVE_CFLAGS="$CFLAGS" + CFLAGS="$CFLAGS -Wno-pointer-sign" + cat >conftest.$ac_ext <<_ACEOF +@@ -4659,20 +4755,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + has_option=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + has_option=no +@@ -4682,23 +4779,23 @@ + if test $has_option = yes; then + C_WARNINGS_SWITCH="-Wno-pointer-sign $C_WARNINGS_SWITCH" + fi +-{ echo "$as_me:$LINENO: result: $has_option" >&5 +-echo "${ECHO_T}$has_option" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $has_option" >&5 ++$as_echo "$has_option" >&6; } + CFLAGS="$SAVE_CFLAGS" + unset has_option + unset SAVE_CFLAGS + + #### Some other nice autoconf tests. + +-{ echo "$as_me:$LINENO: checking whether ln -s works" >&5 +-echo $ECHO_N "checking whether ln -s works... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether ln -s works" >&5 ++$as_echo_n "checking whether ln -s works... " >&6; } + LN_S=$as_ln_s + if test "$LN_S" = "ln -s"; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + else +- { echo "$as_me:$LINENO: result: no, using $LN_S" >&5 +-echo "${ECHO_T}no, using $LN_S" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no, using $LN_S" >&5 ++$as_echo "no, using $LN_S" >&6; } + fi + + ac_ext=c +@@ -4706,15 +4803,15 @@ + ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' + ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' + ac_compiler_gnu=$ac_cv_c_compiler_gnu +-{ echo "$as_me:$LINENO: checking how to run the C preprocessor" >&5 +-echo $ECHO_N "checking how to run the C preprocessor... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking how to run the C preprocessor" >&5 ++$as_echo_n "checking how to run the C preprocessor... " >&6; } + # On Suns, sometimes $CPP names a directory. + if test -n "$CPP" && test -d "$CPP"; then + CPP= + fi + if test -z "$CPP"; then + if test "${ac_cv_prog_CPP+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + # Double quotes because CPP needs to be expanded + for CPP in "$CC -E" "$CC -E -traditional-cpp" "/lib/cpp" +@@ -4746,20 +4843,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + : + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + # Broken: fails on valid input. +@@ -4783,13 +4881,14 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err +@@ -4797,7 +4896,7 @@ + # Broken: success on invalid input. + continue + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + # Passes both tests. +@@ -4822,8 +4921,8 @@ + else + ac_cv_prog_CPP=$CPP + fi +-{ echo "$as_me:$LINENO: result: $CPP" >&5 +-echo "${ECHO_T}$CPP" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $CPP" >&5 ++$as_echo "$CPP" >&6; } + ac_preproc_ok=false + for ac_c_preproc_warn_flag in '' yes + do +@@ -4851,20 +4950,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + : + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + # Broken: fails on valid input. +@@ -4888,13 +4988,14 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err +@@ -4902,7 +5003,7 @@ + # Broken: success on invalid input. + continue + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + # Passes both tests. +@@ -4918,11 +5019,13 @@ + if $ac_preproc_ok; then + : + else +- { { echo "$as_me:$LINENO: error: C preprocessor \"$CPP\" fails sanity check ++ { { $as_echo "$as_me:$LINENO: error: in \`$ac_pwd':" >&5 ++$as_echo "$as_me: error: in \`$ac_pwd':" >&2;} ++{ { $as_echo "$as_me:$LINENO: error: C preprocessor \"$CPP\" fails sanity check + See \`config.log' for more details." >&5 +-echo "$as_me: error: C preprocessor \"$CPP\" fails sanity check ++$as_echo "$as_me: error: C preprocessor \"$CPP\" fails sanity check + See \`config.log' for more details." >&2;} +- { (exit 1); exit 1; }; } ++ { (exit 1); exit 1; }; }; } + fi + + ac_ext=c +@@ -4944,11 +5047,12 @@ + # SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff" + # OS/2's system install, which has a completely different semantic + # ./install, which can be erroneously created by make from ./install.sh. +-{ echo "$as_me:$LINENO: checking for a BSD-compatible install" >&5 +-echo $ECHO_N "checking for a BSD-compatible install... $ECHO_C" >&6; } ++# Reject install programs that cannot install multiple files. ++{ $as_echo "$as_me:$LINENO: checking for a BSD-compatible install" >&5 ++$as_echo_n "checking for a BSD-compatible install... " >&6; } + if test -z "$INSTALL"; then + if test "${ac_cv_path_install+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR + for as_dir in $PATH +@@ -4977,17 +5081,29 @@ + # program-specific install script used by HP pwplus--don't use. + : + else +- ac_cv_path_install="$as_dir/$ac_prog$ac_exec_ext -c" +- break 3 ++ rm -rf conftest.one conftest.two conftest.dir ++ echo one > conftest.one ++ echo two > conftest.two ++ mkdir conftest.dir ++ if "$as_dir/$ac_prog$ac_exec_ext" -c conftest.one conftest.two "`pwd`/conftest.dir" && ++ test -s conftest.one && test -s conftest.two && ++ test -s conftest.dir/conftest.one && ++ test -s conftest.dir/conftest.two ++ then ++ ac_cv_path_install="$as_dir/$ac_prog$ac_exec_ext -c" ++ break 3 ++ fi + fi + fi + done + done + ;; + esac ++ + done + IFS=$as_save_IFS + ++rm -rf conftest.one conftest.two conftest.dir + + fi + if test "${ac_cv_path_install+set}" = set; then +@@ -5000,8 +5116,8 @@ + INSTALL=$ac_install_sh + fi + fi +-{ echo "$as_me:$LINENO: result: $INSTALL" >&5 +-echo "${ECHO_T}$INSTALL" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $INSTALL" >&5 ++$as_echo "$INSTALL" >&6; } + + # Use test -z because SunOS4 sh mishandles braces in ${var-val}. + # It thinks the first close brace ends the variable substitution. +@@ -5015,10 +5131,10 @@ + if test -n "$ac_tool_prefix"; then + # Extract the first word of "${ac_tool_prefix}ranlib", so it can be a program name with args. + set dummy ${ac_tool_prefix}ranlib; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_RANLIB+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$RANLIB"; then + ac_cv_prog_RANLIB="$RANLIB" # Let the user override the test. +@@ -5031,7 +5147,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_RANLIB="${ac_tool_prefix}ranlib" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -5042,11 +5158,11 @@ + fi + RANLIB=$ac_cv_prog_RANLIB + if test -n "$RANLIB"; then +- { echo "$as_me:$LINENO: result: $RANLIB" >&5 +-echo "${ECHO_T}$RANLIB" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $RANLIB" >&5 ++$as_echo "$RANLIB" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -5055,10 +5171,10 @@ + ac_ct_RANLIB=$RANLIB + # Extract the first word of "ranlib", so it can be a program name with args. + set dummy ranlib; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_ac_ct_RANLIB+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$ac_ct_RANLIB"; then + ac_cv_prog_ac_ct_RANLIB="$ac_ct_RANLIB" # Let the user override the test. +@@ -5071,7 +5187,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_ac_ct_RANLIB="ranlib" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -5082,11 +5198,11 @@ + fi + ac_ct_RANLIB=$ac_cv_prog_ac_ct_RANLIB + if test -n "$ac_ct_RANLIB"; then +- { echo "$as_me:$LINENO: result: $ac_ct_RANLIB" >&5 +-echo "${ECHO_T}$ac_ct_RANLIB" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $ac_ct_RANLIB" >&5 ++$as_echo "$ac_ct_RANLIB" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + if test "x$ac_ct_RANLIB" = x; then +@@ -5094,12 +5210,8 @@ + else + case $cross_compiling:$ac_tool_warned in + yes:) +-{ echo "$as_me:$LINENO: WARNING: In the future, Autoconf will not detect cross-tools +-whose name does not start with the host triplet. If you think this +-configuration is useful to you, please write to autoconf@gnu.org." >&5 +-echo "$as_me: WARNING: In the future, Autoconf will not detect cross-tools +-whose name does not start with the host triplet. If you think this +-configuration is useful to you, please write to autoconf@gnu.org." >&2;} ++{ $as_echo "$as_me:$LINENO: WARNING: using cross tools not prefixed with host triplet" >&5 ++$as_echo "$as_me: WARNING: using cross tools not prefixed with host triplet" >&2;} + ac_tool_warned=yes ;; + esac + RANLIB=$ac_ct_RANLIB +@@ -5111,10 +5223,10 @@ + fi + # Extract the first word of "install-info", so it can be a program name with args. + set dummy install-info; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_INSTALL_INFO+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $INSTALL_INFO in + [\\/]* | ?:[\\/]*) +@@ -5129,7 +5241,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_INSTALL_INFO="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -5141,20 +5253,20 @@ + fi + INSTALL_INFO=$ac_cv_path_INSTALL_INFO + if test -n "$INSTALL_INFO"; then +- { echo "$as_me:$LINENO: result: $INSTALL_INFO" >&5 +-echo "${ECHO_T}$INSTALL_INFO" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $INSTALL_INFO" >&5 ++$as_echo "$INSTALL_INFO" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + + # Extract the first word of "install-info", so it can be a program name with args. + set dummy install-info; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_INSTALL_INFO+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $INSTALL_INFO in + [\\/]* | ?:[\\/]*) +@@ -5169,7 +5281,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_INSTALL_INFO="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -5181,20 +5293,20 @@ + fi + INSTALL_INFO=$ac_cv_path_INSTALL_INFO + if test -n "$INSTALL_INFO"; then +- { echo "$as_me:$LINENO: result: $INSTALL_INFO" >&5 +-echo "${ECHO_T}$INSTALL_INFO" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $INSTALL_INFO" >&5 ++$as_echo "$INSTALL_INFO" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + + # Extract the first word of "install-info", so it can be a program name with args. + set dummy install-info; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_INSTALL_INFO+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $INSTALL_INFO in + [\\/]* | ?:[\\/]*) +@@ -5209,7 +5321,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_INSTALL_INFO="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -5222,20 +5334,20 @@ + fi + INSTALL_INFO=$ac_cv_path_INSTALL_INFO + if test -n "$INSTALL_INFO"; then +- { echo "$as_me:$LINENO: result: $INSTALL_INFO" >&5 +-echo "${ECHO_T}$INSTALL_INFO" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $INSTALL_INFO" >&5 ++$as_echo "$INSTALL_INFO" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + + # Extract the first word of "gzip", so it can be a program name with args. + set dummy gzip; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_GZIP_PROG+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $GZIP_PROG in + [\\/]* | ?:[\\/]*) +@@ -5250,7 +5362,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_GZIP_PROG="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -5262,11 +5374,11 @@ + fi + GZIP_PROG=$ac_cv_path_GZIP_PROG + if test -n "$GZIP_PROG"; then +- { echo "$as_me:$LINENO: result: $GZIP_PROG" >&5 +-echo "${ECHO_T}$GZIP_PROG" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $GZIP_PROG" >&5 ++$as_echo "$GZIP_PROG" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -5275,10 +5387,10 @@ + ## Need makeinfo >= 4.6 (?) to build the manuals. + # Extract the first word of "makeinfo", so it can be a program name with args. + set dummy makeinfo; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_MAKEINFO+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $MAKEINFO in + [\\/]* | ?:[\\/]*) +@@ -5293,7 +5405,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_MAKEINFO="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -5306,11 +5418,11 @@ + fi + MAKEINFO=$ac_cv_path_MAKEINFO + if test -n "$MAKEINFO"; then +- { echo "$as_me:$LINENO: result: $MAKEINFO" >&5 +-echo "${ECHO_T}$MAKEINFO" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $MAKEINFO" >&5 ++$as_echo "$MAKEINFO" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -5332,11 +5444,11 @@ + if test "x${with_makeinfo}" = "xno"; then + MAKEINFO=off + elif ! test -e $srcdir/info/emacs; then +- { { echo "$as_me:$LINENO: error: You do not seem to have makeinfo >= 4.6, and your ++ { { $as_echo "$as_me:$LINENO: error: You do not seem to have makeinfo >= 4.6, and your + source tree does not seem to have pre-built manuals in the \`info' directory. + Either install a suitable version of makeinfo, or re-run configure + with the \`--without-makeinfo' option to build without the manuals. " >&5 +-echo "$as_me: error: You do not seem to have makeinfo >= 4.6, and your ++$as_echo "$as_me: error: You do not seem to have makeinfo >= 4.6, and your + source tree does not seem to have pre-built manuals in the \`info' directory. + Either install a suitable version of makeinfo, or re-run configure + with the \`--without-makeinfo' option to build without the manuals. " >&2;} +@@ -5363,8 +5475,8 @@ + LDFLAGS="$LDFLAGS -znocombreloc" + fi + +-{ echo "$as_me:$LINENO: checking for -znocombreloc" >&5 +-echo $ECHO_N "checking for -znocombreloc... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for -znocombreloc" >&5 ++$as_echo_n "checking for -znocombreloc... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + main(){return 0;} + _ACEOF +@@ -5374,38 +5486,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + LDFLAGS=$late_LDFLAGS +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + + #### Extract some information from the operating system and machine files. + +-{ echo "$as_me:$LINENO: checking the machine- and system-dependent files to find out ++{ $as_echo "$as_me:$LINENO: checking the machine- and system-dependent files to find out + - which libraries the lib-src programs will want, and + - whether the GNU malloc routines are usable..." >&5 +-echo "$as_me: checking the machine- and system-dependent files to find out ++$as_echo "$as_me: checking the machine- and system-dependent files to find out + - which libraries the lib-src programs will want, and + - whether the GNU malloc routines are usable..." >&6;} + +@@ -5554,10 +5670,10 @@ + + if test "$enable_largefile" != no; then + +- { echo "$as_me:$LINENO: checking for special C compiler options needed for large files" >&5 +-echo $ECHO_N "checking for special C compiler options needed for large files... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for special C compiler options needed for large files" >&5 ++$as_echo_n "checking for special C compiler options needed for large files... " >&6; } + if test "${ac_cv_sys_largefile_CC+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_sys_largefile_CC=no + if test "$GCC" != yes; then +@@ -5594,20 +5710,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + break + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + +@@ -5621,20 +5738,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_sys_largefile_CC=' -n32'; break + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + +@@ -5647,16 +5765,16 @@ + rm -f conftest.$ac_ext + fi + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_sys_largefile_CC" >&5 +-echo "${ECHO_T}$ac_cv_sys_largefile_CC" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_sys_largefile_CC" >&5 ++$as_echo "$ac_cv_sys_largefile_CC" >&6; } + if test "$ac_cv_sys_largefile_CC" != no; then + CC=$CC$ac_cv_sys_largefile_CC + fi + +- { echo "$as_me:$LINENO: checking for _FILE_OFFSET_BITS value needed for large files" >&5 +-echo $ECHO_N "checking for _FILE_OFFSET_BITS value needed for large files... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for _FILE_OFFSET_BITS value needed for large files" >&5 ++$as_echo_n "checking for _FILE_OFFSET_BITS value needed for large files... " >&6; } + if test "${ac_cv_sys_file_offset_bits+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + while :; do + cat >conftest.$ac_ext <<_ACEOF +@@ -5688,20 +5806,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_sys_file_offset_bits=no; break + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + +@@ -5738,20 +5857,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_sys_file_offset_bits=64; break + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + +@@ -5762,8 +5882,8 @@ + break + done + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_sys_file_offset_bits" >&5 +-echo "${ECHO_T}$ac_cv_sys_file_offset_bits" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_sys_file_offset_bits" >&5 ++$as_echo "$ac_cv_sys_file_offset_bits" >&6; } + case $ac_cv_sys_file_offset_bits in #( + no | unknown) ;; + *) +@@ -5772,12 +5892,12 @@ + _ACEOF + ;; + esac +-rm -f conftest* ++rm -rf conftest* + if test $ac_cv_sys_file_offset_bits = unknown; then +- { echo "$as_me:$LINENO: checking for _LARGE_FILES value needed for large files" >&5 +-echo $ECHO_N "checking for _LARGE_FILES value needed for large files... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for _LARGE_FILES value needed for large files" >&5 ++$as_echo_n "checking for _LARGE_FILES value needed for large files... " >&6; } + if test "${ac_cv_sys_large_files+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + while :; do + cat >conftest.$ac_ext <<_ACEOF +@@ -5809,20 +5929,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_sys_large_files=no; break + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + +@@ -5859,20 +5980,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_sys_large_files=1; break + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + +@@ -5883,8 +6005,8 @@ + break + done + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_sys_large_files" >&5 +-echo "${ECHO_T}$ac_cv_sys_large_files" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_sys_large_files" >&5 ++$as_echo "$ac_cv_sys_large_files" >&6; } + case $ac_cv_sys_large_files in #( + no | unknown) ;; + *) +@@ -5893,7 +6015,7 @@ + _ACEOF + ;; + esac +-rm -f conftest* ++rm -rf conftest* + fi + fi + +@@ -5924,20 +6046,21 @@ + + for ac_header in machine/soundcard.h sys/soundcard.h soundcard.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -5953,32 +6076,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -5992,69 +6116,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -6062,10 +6190,10 @@ + done + + # Emulation library used on NetBSD. +- { echo "$as_me:$LINENO: checking for _oss_ioctl in -lossaudio" >&5 +-echo $ECHO_N "checking for _oss_ioctl in -lossaudio... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for _oss_ioctl in -lossaudio" >&5 ++$as_echo_n "checking for _oss_ioctl in -lossaudio... " >&6; } + if test "${ac_cv_lib_ossaudio__oss_ioctl+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lossaudio $LIBS" +@@ -6097,33 +6225,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_ossaudio__oss_ioctl=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_ossaudio__oss_ioctl=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_ossaudio__oss_ioctl" >&5 +-echo "${ECHO_T}$ac_cv_lib_ossaudio__oss_ioctl" >&6; } +-if test $ac_cv_lib_ossaudio__oss_ioctl = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_ossaudio__oss_ioctl" >&5 ++$as_echo "$ac_cv_lib_ossaudio__oss_ioctl" >&6; } ++if test "x$ac_cv_lib_ossaudio__oss_ioctl" = x""yes; then + LIBSOUND=-lossaudio + else + LIBSOUND= +@@ -6138,10 +6270,10 @@ + + # Extract the first word of "pkg-config", so it can be a program name with args. + set dummy pkg-config; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_PKG_CONFIG+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $PKG_CONFIG in + [\\/]* | ?:[\\/]*) +@@ -6156,7 +6288,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_PKG_CONFIG="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -6169,11 +6301,11 @@ + fi + PKG_CONFIG=$ac_cv_path_PKG_CONFIG + if test -n "$PKG_CONFIG"; then +- { echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 +-echo "${ECHO_T}$PKG_CONFIG" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 ++$as_echo "$PKG_CONFIG" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -6183,28 +6315,28 @@ + else + PKG_CONFIG_MIN_VERSION=0.9.0 + if $PKG_CONFIG --atleast-pkgconfig-version $PKG_CONFIG_MIN_VERSION; then +- { echo "$as_me:$LINENO: checking for $ALSA_MODULES" >&5 +-echo $ECHO_N "checking for $ALSA_MODULES... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ALSA_MODULES" >&5 ++$as_echo_n "checking for $ALSA_MODULES... " >&6; } + + if $PKG_CONFIG --exists "$ALSA_MODULES" 2>&5; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + succeeded=yes + +- { echo "$as_me:$LINENO: checking ALSA_CFLAGS" >&5 +-echo $ECHO_N "checking ALSA_CFLAGS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking ALSA_CFLAGS" >&5 ++$as_echo_n "checking ALSA_CFLAGS... " >&6; } + ALSA_CFLAGS=`$PKG_CONFIG --cflags "$ALSA_MODULES"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $ALSA_CFLAGS" >&5 +-echo "${ECHO_T}$ALSA_CFLAGS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $ALSA_CFLAGS" >&5 ++$as_echo "$ALSA_CFLAGS" >&6; } + +- { echo "$as_me:$LINENO: checking ALSA_LIBS" >&5 +-echo $ECHO_N "checking ALSA_LIBS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking ALSA_LIBS" >&5 ++$as_echo_n "checking ALSA_LIBS... " >&6; } + ALSA_LIBS=`$PKG_CONFIG --libs "$ALSA_MODULES"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $ALSA_LIBS" >&5 +-echo "${ECHO_T}$ALSA_LIBS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $ALSA_LIBS" >&5 ++$as_echo "$ALSA_LIBS" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + ALSA_CFLAGS="" + ALSA_LIBS="" + ## If we have a custom action on failure, don't print errors, but +@@ -6253,20 +6385,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_alsa_normal=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_alsa_normal=no +@@ -6295,20 +6428,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_alsa_subdir=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_alsa_subdir=no +@@ -6316,8 +6450,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + if test "$emacs_alsa_subdir" != yes; then +- { { echo "$as_me:$LINENO: error: pkg-config found alsa, but it does not compile. See config.log for error messages." >&5 +-echo "$as_me: error: pkg-config found alsa, but it does not compile. See config.log for error messages." >&2;} ++ { { $as_echo "$as_me:$LINENO: error: pkg-config found alsa, but it does not compile. See config.log for error messages." >&5 ++$as_echo "$as_me: error: pkg-config found alsa, but it does not compile. See config.log for error messages." >&2;} + { (exit 1); exit 1; }; } + fi + ALSA_CFLAGS="$ALSA_CFLAGS -DALSA_SUBDIR_INCLUDE" +@@ -6367,20 +6501,21 @@ + sys/param.h sys/vlimit.h sys/resource.h locale.h sys/_mbstate_t.h \ + sys/utsname.h pwd.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -6396,32 +6531,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -6435,69 +6571,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -6505,8 +6645,8 @@ + done + + +-{ echo "$as_me:$LINENO: checking if personality LINUX32 can be set" >&5 +-echo $ECHO_N "checking if personality LINUX32 can be set... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking if personality LINUX32 can be set" >&5 ++$as_echo_n "checking if personality LINUX32 can be set... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -6528,28 +6668,29 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_personality_linux32=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_personality_linux32=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $emacs_cv_personality_linux32" >&5 +-echo "${ECHO_T}$emacs_cv_personality_linux32" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_personality_linux32" >&5 ++$as_echo "$emacs_cv_personality_linux32" >&6; } + + if test $emacs_cv_personality_linux32 = yes; then + +@@ -6562,11 +6703,11 @@ + + for ac_header in term.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -6581,20 +6722,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + eval "$as_ac_Header=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_Header=no" +@@ -6602,22 +6744,25 @@ + + rm -f conftest.err conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi + + done + +-{ echo "$as_me:$LINENO: checking for ANSI C header files" >&5 +-echo $ECHO_N "checking for ANSI C header files... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for ANSI C header files" >&5 ++$as_echo_n "checking for ANSI C header files... " >&6; } + if test "${ac_cv_header_stdc+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -6644,20 +6789,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_header_stdc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_header_stdc=no +@@ -6749,37 +6895,40 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + : + else +- echo "$as_me: program exited with status $ac_status" >&5 +-echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: program exited with status $ac_status" >&5 ++$as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ( exit $ac_status ) + ac_cv_header_stdc=no + fi ++rm -rf conftest.dSYM + rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext + fi + + + fi + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_stdc" >&5 +-echo "${ECHO_T}$ac_cv_header_stdc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_stdc" >&5 ++$as_echo "$ac_cv_header_stdc" >&6; } + if test $ac_cv_header_stdc = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -6788,10 +6937,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking whether time.h and sys/time.h may both be included" >&5 +-echo $ECHO_N "checking whether time.h and sys/time.h may both be included... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether time.h and sys/time.h may both be included" >&5 ++$as_echo_n "checking whether time.h and sys/time.h may both be included... " >&6; } + if test "${ac_cv_header_time+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -6818,20 +6967,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_header_time=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_header_time=no +@@ -6839,8 +6989,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_time" >&5 +-echo "${ECHO_T}$ac_cv_header_time" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_time" >&5 ++$as_echo "$ac_cv_header_time" >&6; } + if test $ac_cv_header_time = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -6849,10 +6999,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking whether sys_siglist is declared" >&5 +-echo $ECHO_N "checking whether sys_siglist is declared... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether sys_siglist is declared" >&5 ++$as_echo_n "checking whether sys_siglist is declared... " >&6; } + if test "${ac_cv_have_decl_sys_siglist+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -6878,20 +7028,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_have_decl_sys_siglist=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_have_decl_sys_siglist=no +@@ -6899,9 +7050,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_have_decl_sys_siglist" >&5 +-echo "${ECHO_T}$ac_cv_have_decl_sys_siglist" >&6; } +-if test $ac_cv_have_decl_sys_siglist = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_have_decl_sys_siglist" >&5 ++$as_echo "$ac_cv_have_decl_sys_siglist" >&6; } ++if test "x$ac_cv_have_decl_sys_siglist" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_DECL_SYS_SIGLIST 1 +@@ -6919,10 +7070,10 @@ + + if test $ac_cv_have_decl_sys_siglist != yes; then + # For Tru64, at least: +- { echo "$as_me:$LINENO: checking whether __sys_siglist is declared" >&5 +-echo $ECHO_N "checking whether __sys_siglist is declared... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether __sys_siglist is declared" >&5 ++$as_echo_n "checking whether __sys_siglist is declared... " >&6; } + if test "${ac_cv_have_decl___sys_siglist+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -6948,20 +7099,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_have_decl___sys_siglist=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_have_decl___sys_siglist=no +@@ -6969,9 +7121,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_have_decl___sys_siglist" >&5 +-echo "${ECHO_T}$ac_cv_have_decl___sys_siglist" >&6; } +-if test $ac_cv_have_decl___sys_siglist = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_have_decl___sys_siglist" >&5 ++$as_echo "$ac_cv_have_decl___sys_siglist" >&6; } ++if test "x$ac_cv_have_decl___sys_siglist" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_DECL___SYS_SIGLIST 1 +@@ -6995,10 +7147,10 @@ + + fi + fi +-{ echo "$as_me:$LINENO: checking for sys/wait.h that is POSIX.1 compatible" >&5 +-echo $ECHO_N "checking for sys/wait.h that is POSIX.1 compatible... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for sys/wait.h that is POSIX.1 compatible" >&5 ++$as_echo_n "checking for sys/wait.h that is POSIX.1 compatible... " >&6; } + if test "${ac_cv_header_sys_wait_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7031,20 +7183,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_header_sys_wait_h=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_header_sys_wait_h=no +@@ -7052,8 +7205,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_sys_wait_h" >&5 +-echo "${ECHO_T}$ac_cv_header_sys_wait_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_sys_wait_h" >&5 ++$as_echo "$ac_cv_header_sys_wait_h" >&6; } + if test $ac_cv_header_sys_wait_h = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -7063,10 +7216,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking for struct utimbuf" >&5 +-echo $ECHO_N "checking for struct utimbuf... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct utimbuf" >&5 ++$as_echo_n "checking for struct utimbuf... " >&6; } + if test "${emacs_cv_struct_utimbuf+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7101,20 +7254,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_struct_utimbuf=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_struct_utimbuf=no +@@ -7122,8 +7276,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_struct_utimbuf" >&5 +-echo "${ECHO_T}$emacs_cv_struct_utimbuf" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_struct_utimbuf" >&5 ++$as_echo "$emacs_cv_struct_utimbuf" >&6; } + if test $emacs_cv_struct_utimbuf = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -7132,10 +7286,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking return type of signal handlers" >&5 +-echo $ECHO_N "checking return type of signal handlers... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking return type of signal handlers" >&5 ++$as_echo_n "checking return type of signal handlers... " >&6; } + if test "${ac_cv_type_signal+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7160,20 +7314,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_type_signal=int + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_type_signal=void +@@ -7181,8 +7336,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_type_signal" >&5 +-echo "${ECHO_T}$ac_cv_type_signal" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_type_signal" >&5 ++$as_echo "$ac_cv_type_signal" >&6; } + + cat >>confdefs.h <<_ACEOF + #define RETSIGTYPE $ac_cv_type_signal +@@ -7190,10 +7345,10 @@ + + + +-{ echo "$as_me:$LINENO: checking for speed_t" >&5 +-echo $ECHO_N "checking for speed_t... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for speed_t" >&5 ++$as_echo_n "checking for speed_t... " >&6; } + if test "${emacs_cv_speed_t+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7216,20 +7371,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_speed_t=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_speed_t=no +@@ -7237,8 +7393,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_speed_t" >&5 +-echo "${ECHO_T}$emacs_cv_speed_t" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_speed_t" >&5 ++$as_echo "$emacs_cv_speed_t" >&6; } + if test $emacs_cv_speed_t = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -7247,10 +7403,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking for struct timeval" >&5 +-echo $ECHO_N "checking for struct timeval... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct timeval" >&5 ++$as_echo_n "checking for struct timeval... " >&6; } + if test "${emacs_cv_struct_timeval+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7282,20 +7438,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_struct_timeval=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_struct_timeval=no +@@ -7303,8 +7460,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_struct_timeval" >&5 +-echo "${ECHO_T}$emacs_cv_struct_timeval" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_struct_timeval" >&5 ++$as_echo "$emacs_cv_struct_timeval" >&6; } + HAVE_TIMEVAL=$emacs_cv_struct_timeval + if test $emacs_cv_struct_timeval = yes; then + +@@ -7314,10 +7471,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking for struct exception" >&5 +-echo $ECHO_N "checking for struct exception... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct exception" >&5 ++$as_echo_n "checking for struct exception... " >&6; } + if test "${emacs_cv_struct_exception+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7340,20 +7497,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_struct_exception=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_struct_exception=no +@@ -7361,8 +7519,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_struct_exception" >&5 +-echo "${ECHO_T}$emacs_cv_struct_exception" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_struct_exception" >&5 ++$as_echo "$emacs_cv_struct_exception" >&6; } + HAVE_EXCEPTION=$emacs_cv_struct_exception + if test $emacs_cv_struct_exception != yes; then + +@@ -7375,20 +7533,21 @@ + + for ac_header in sys/socket.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -7404,32 +7563,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -7443,69 +7603,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -7515,11 +7679,11 @@ + + for ac_header in net/if.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7540,20 +7704,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + eval "$as_ac_Header=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_Header=no" +@@ -7561,12 +7726,15 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -7574,10 +7742,10 @@ + done + + +-{ echo "$as_me:$LINENO: checking whether struct tm is in sys/time.h or time.h" >&5 +-echo $ECHO_N "checking whether struct tm is in sys/time.h or time.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether struct tm is in sys/time.h or time.h" >&5 ++$as_echo_n "checking whether struct tm is in sys/time.h or time.h... " >&6; } + if test "${ac_cv_struct_tm+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7593,7 +7761,7 @@ + { + struct tm tm; + int *p = &tm.tm_sec; +- return !p; ++ return !p; + ; + return 0; + } +@@ -7604,20 +7772,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_struct_tm=time.h + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_struct_tm=sys/time.h +@@ -7625,8 +7794,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_struct_tm" >&5 +-echo "${ECHO_T}$ac_cv_struct_tm" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_struct_tm" >&5 ++$as_echo "$ac_cv_struct_tm" >&6; } + if test $ac_cv_struct_tm = sys/time.h; then + + cat >>confdefs.h <<\_ACEOF +@@ -7635,10 +7804,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking for struct tm.tm_zone" >&5 +-echo $ECHO_N "checking for struct tm.tm_zone... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct tm.tm_zone" >&5 ++$as_echo_n "checking for struct tm.tm_zone... " >&6; } + if test "${ac_cv_member_struct_tm_tm_zone+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7666,20 +7835,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_tm_tm_zone=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -7708,20 +7878,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_tm_tm_zone=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_struct_tm_tm_zone=no +@@ -7732,9 +7903,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_struct_tm_tm_zone" >&5 +-echo "${ECHO_T}$ac_cv_member_struct_tm_tm_zone" >&6; } +-if test $ac_cv_member_struct_tm_tm_zone = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_struct_tm_tm_zone" >&5 ++$as_echo "$ac_cv_member_struct_tm_tm_zone" >&6; } ++if test "x$ac_cv_member_struct_tm_tm_zone" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_STRUCT_TM_TM_ZONE 1 +@@ -7750,10 +7921,10 @@ + _ACEOF + + else +- { echo "$as_me:$LINENO: checking whether tzname is declared" >&5 +-echo $ECHO_N "checking whether tzname is declared... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether tzname is declared" >&5 ++$as_echo_n "checking whether tzname is declared... " >&6; } + if test "${ac_cv_have_decl_tzname+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7780,20 +7951,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_have_decl_tzname=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_have_decl_tzname=no +@@ -7801,9 +7973,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_have_decl_tzname" >&5 +-echo "${ECHO_T}$ac_cv_have_decl_tzname" >&6; } +-if test $ac_cv_have_decl_tzname = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_have_decl_tzname" >&5 ++$as_echo "$ac_cv_have_decl_tzname" >&6; } ++if test "x$ac_cv_have_decl_tzname" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_DECL_TZNAME 1 +@@ -7819,10 +7991,10 @@ + fi + + +- { echo "$as_me:$LINENO: checking for tzname" >&5 +-echo $ECHO_N "checking for tzname... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for tzname" >&5 ++$as_echo_n "checking for tzname... " >&6; } + if test "${ac_cv_var_tzname+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7849,31 +8021,35 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_var_tzname=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_var_tzname=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_var_tzname" >&5 +-echo "${ECHO_T}$ac_cv_var_tzname" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_var_tzname" >&5 ++$as_echo "$ac_cv_var_tzname" >&6; } + if test $ac_cv_var_tzname = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -7883,10 +8059,10 @@ + fi + fi + +-{ echo "$as_me:$LINENO: checking for struct tm.tm_gmtoff" >&5 +-echo $ECHO_N "checking for struct tm.tm_gmtoff... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct tm.tm_gmtoff" >&5 ++$as_echo_n "checking for struct tm.tm_gmtoff... " >&6; } + if test "${ac_cv_member_struct_tm_tm_gmtoff+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -7912,20 +8088,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_tm_tm_gmtoff=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -7952,20 +8129,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_tm_tm_gmtoff=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_struct_tm_tm_gmtoff=no +@@ -7976,9 +8154,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_struct_tm_tm_gmtoff" >&5 +-echo "${ECHO_T}$ac_cv_member_struct_tm_tm_gmtoff" >&6; } +-if test $ac_cv_member_struct_tm_tm_gmtoff = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_struct_tm_tm_gmtoff" >&5 ++$as_echo "$ac_cv_member_struct_tm_tm_gmtoff" >&6; } ++if test "x$ac_cv_member_struct_tm_tm_gmtoff" = x""yes; then + + cat >>confdefs.h <<\_ACEOF + #define HAVE_TM_GMTOFF 1 +@@ -7986,10 +8164,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking for struct ifreq.ifr_flags" >&5 +-echo $ECHO_N "checking for struct ifreq.ifr_flags... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct ifreq.ifr_flags" >&5 ++$as_echo_n "checking for struct ifreq.ifr_flags... " >&6; } + if test "${ac_cv_member_struct_ifreq_ifr_flags+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -8021,20 +8199,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_flags=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -8067,20 +8246,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_flags=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_struct_ifreq_ifr_flags=no +@@ -8091,9 +8271,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_flags" >&5 +-echo "${ECHO_T}$ac_cv_member_struct_ifreq_ifr_flags" >&6; } +-if test $ac_cv_member_struct_ifreq_ifr_flags = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_flags" >&5 ++$as_echo "$ac_cv_member_struct_ifreq_ifr_flags" >&6; } ++if test "x$ac_cv_member_struct_ifreq_ifr_flags" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_STRUCT_IFREQ_IFR_FLAGS 1 +@@ -8101,10 +8281,10 @@ + + + fi +-{ echo "$as_me:$LINENO: checking for struct ifreq.ifr_hwaddr" >&5 +-echo $ECHO_N "checking for struct ifreq.ifr_hwaddr... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct ifreq.ifr_hwaddr" >&5 ++$as_echo_n "checking for struct ifreq.ifr_hwaddr... " >&6; } + if test "${ac_cv_member_struct_ifreq_ifr_hwaddr+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -8136,20 +8316,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_hwaddr=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -8182,20 +8363,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_hwaddr=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_struct_ifreq_ifr_hwaddr=no +@@ -8206,9 +8388,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_hwaddr" >&5 +-echo "${ECHO_T}$ac_cv_member_struct_ifreq_ifr_hwaddr" >&6; } +-if test $ac_cv_member_struct_ifreq_ifr_hwaddr = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_hwaddr" >&5 ++$as_echo "$ac_cv_member_struct_ifreq_ifr_hwaddr" >&6; } ++if test "x$ac_cv_member_struct_ifreq_ifr_hwaddr" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_STRUCT_IFREQ_IFR_HWADDR 1 +@@ -8216,10 +8398,10 @@ + + + fi +-{ echo "$as_me:$LINENO: checking for struct ifreq.ifr_netmask" >&5 +-echo $ECHO_N "checking for struct ifreq.ifr_netmask... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct ifreq.ifr_netmask" >&5 ++$as_echo_n "checking for struct ifreq.ifr_netmask... " >&6; } + if test "${ac_cv_member_struct_ifreq_ifr_netmask+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -8251,20 +8433,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_netmask=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -8297,20 +8480,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_netmask=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_struct_ifreq_ifr_netmask=no +@@ -8321,9 +8505,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_netmask" >&5 +-echo "${ECHO_T}$ac_cv_member_struct_ifreq_ifr_netmask" >&6; } +-if test $ac_cv_member_struct_ifreq_ifr_netmask = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_netmask" >&5 ++$as_echo "$ac_cv_member_struct_ifreq_ifr_netmask" >&6; } ++if test "x$ac_cv_member_struct_ifreq_ifr_netmask" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_STRUCT_IFREQ_IFR_NETMASK 1 +@@ -8331,10 +8515,10 @@ + + + fi +-{ echo "$as_me:$LINENO: checking for struct ifreq.ifr_broadaddr" >&5 +-echo $ECHO_N "checking for struct ifreq.ifr_broadaddr... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct ifreq.ifr_broadaddr" >&5 ++$as_echo_n "checking for struct ifreq.ifr_broadaddr... " >&6; } + if test "${ac_cv_member_struct_ifreq_ifr_broadaddr+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -8366,20 +8550,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_broadaddr=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -8412,20 +8597,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_broadaddr=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_struct_ifreq_ifr_broadaddr=no +@@ -8436,9 +8622,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_broadaddr" >&5 +-echo "${ECHO_T}$ac_cv_member_struct_ifreq_ifr_broadaddr" >&6; } +-if test $ac_cv_member_struct_ifreq_ifr_broadaddr = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_broadaddr" >&5 ++$as_echo "$ac_cv_member_struct_ifreq_ifr_broadaddr" >&6; } ++if test "x$ac_cv_member_struct_ifreq_ifr_broadaddr" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_STRUCT_IFREQ_IFR_BROADADDR 1 +@@ -8446,10 +8632,10 @@ + + + fi +-{ echo "$as_me:$LINENO: checking for struct ifreq.ifr_addr" >&5 +-echo $ECHO_N "checking for struct ifreq.ifr_addr... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for struct ifreq.ifr_addr" >&5 ++$as_echo_n "checking for struct ifreq.ifr_addr... " >&6; } + if test "${ac_cv_member_struct_ifreq_ifr_addr+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -8481,20 +8667,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_addr=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -8527,20 +8714,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_ifreq_ifr_addr=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_struct_ifreq_ifr_addr=no +@@ -8551,9 +8739,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_addr" >&5 +-echo "${ECHO_T}$ac_cv_member_struct_ifreq_ifr_addr" >&6; } +-if test $ac_cv_member_struct_ifreq_ifr_addr = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_struct_ifreq_ifr_addr" >&5 ++$as_echo "$ac_cv_member_struct_ifreq_ifr_addr" >&6; } ++if test "x$ac_cv_member_struct_ifreq_ifr_addr" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_STRUCT_IFREQ_IFR_ADDR 1 +@@ -8564,11 +8752,11 @@ + + + +-{ echo "$as_me:$LINENO: checking for function prototypes" >&5 +-echo $ECHO_N "checking for function prototypes... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for function prototypes" >&5 ++$as_echo_n "checking for function prototypes... " >&6; } + if test "$ac_cv_prog_cc_c89" != no; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + + cat >>confdefs.h <<\_ACEOF + #define PROTOTYPES 1 +@@ -8580,14 +8768,14 @@ + _ACEOF + + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + +-{ echo "$as_me:$LINENO: checking for working volatile" >&5 +-echo $ECHO_N "checking for working volatile... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for working volatile" >&5 ++$as_echo_n "checking for working volatile... " >&6; } + if test "${ac_cv_c_volatile+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -8613,20 +8801,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_c_volatile=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_c_volatile=no +@@ -8634,20 +8823,20 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_c_volatile" >&5 +-echo "${ECHO_T}$ac_cv_c_volatile" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_c_volatile" >&5 ++$as_echo "$ac_cv_c_volatile" >&6; } + if test $ac_cv_c_volatile = no; then + + cat >>confdefs.h <<\_ACEOF +-#define volatile ++#define volatile /**/ + _ACEOF + + fi + +-{ echo "$as_me:$LINENO: checking for an ANSI C-conforming const" >&5 +-echo $ECHO_N "checking for an ANSI C-conforming const... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for an ANSI C-conforming const" >&5 ++$as_echo_n "checking for an ANSI C-conforming const... " >&6; } + if test "${ac_cv_c_const+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -8719,20 +8908,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_c_const=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_c_const=no +@@ -8740,20 +8930,20 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_c_const" >&5 +-echo "${ECHO_T}$ac_cv_c_const" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_c_const" >&5 ++$as_echo "$ac_cv_c_const" >&6; } + if test $ac_cv_c_const = no; then + + cat >>confdefs.h <<\_ACEOF +-#define const ++#define const /**/ + _ACEOF + + fi + +-{ echo "$as_me:$LINENO: checking for void * support" >&5 +-echo $ECHO_N "checking for void * support... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for void * support" >&5 ++$as_echo_n "checking for void * support... " >&6; } + if test "${emacs_cv_void_star+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -8776,20 +8966,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_void_star=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_void_star=no +@@ -8797,8 +8988,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_void_star" >&5 +-echo "${ECHO_T}$emacs_cv_void_star" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_void_star" >&5 ++$as_echo "$emacs_cv_void_star" >&6; } + if test $emacs_cv_void_star = yes; then + cat >>confdefs.h <<\_ACEOF + #define POINTER_TYPE void +@@ -8815,11 +9006,12 @@ + + + +-{ echo "$as_me:$LINENO: checking whether ${MAKE-make} sets \$(MAKE)" >&5 +-echo $ECHO_N "checking whether ${MAKE-make} sets \$(MAKE)... $ECHO_C" >&6; } +-set x ${MAKE-make}; ac_make=`echo "$2" | sed 's/+/p/g; s/[^a-zA-Z0-9_]/_/g'` ++{ $as_echo "$as_me:$LINENO: checking whether ${MAKE-make} sets \$(MAKE)" >&5 ++$as_echo_n "checking whether ${MAKE-make} sets \$(MAKE)... " >&6; } ++set x ${MAKE-make} ++ac_make=`$as_echo "$2" | sed 's/+/p/g; s/[^a-zA-Z0-9_]/_/g'` + if { as_var=ac_cv_prog_make_${ac_make}_set; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.make <<\_ACEOF + SHELL = /bin/sh +@@ -8836,20 +9028,20 @@ + rm -f conftest.make + fi + if eval test \$ac_cv_prog_make_${ac_make}_set = yes; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + SET_MAKE= + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + SET_MAKE="MAKE=${MAKE-make}" + fi + + +-{ echo "$as_me:$LINENO: checking for long file names" >&5 +-echo $ECHO_N "checking for long file names... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for long file names" >&5 ++$as_echo_n "checking for long file names... " >&6; } + if test "${ac_cv_sys_long_file_names+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_sys_long_file_names=yes + # Test for long file names in all the places we know might matter: +@@ -8878,8 +9070,8 @@ + test $ac_cv_sys_long_file_names = no && break + done + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_sys_long_file_names" >&5 +-echo "${ECHO_T}$ac_cv_sys_long_file_names" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_sys_long_file_names" >&5 ++$as_echo "$ac_cv_sys_long_file_names" >&6; } + if test $ac_cv_sys_long_file_names = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -8891,8 +9083,8 @@ + + #### Choose a window system. + +-{ echo "$as_me:$LINENO: checking for X" >&5 +-echo $ECHO_N "checking for X... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for X" >&5 ++$as_echo_n "checking for X... " >&6; } + + + # Check whether --with-x was given. +@@ -8906,11 +9098,11 @@ + have_x=disabled + else + case $x_includes,$x_libraries in #( +- *\'*) { { echo "$as_me:$LINENO: error: Cannot use X directory names containing '" >&5 +-echo "$as_me: error: Cannot use X directory names containing '" >&2;} ++ *\'*) { { $as_echo "$as_me:$LINENO: error: cannot use X directory names containing '" >&5 ++$as_echo "$as_me: error: cannot use X directory names containing '" >&2;} + { (exit 1); exit 1; }; };; #( + *,NONE | NONE,*) if test "${ac_cv_have_x+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + # One or both of the vars are not set, and there is no cached value. + ac_x_includes=no ac_x_libraries=no +@@ -8931,7 +9123,7 @@ + eval "ac_im_$ac_var=\`\${MAKE-make} $ac_var 2>/dev/null | sed -n 's/^$ac_var=//p'\`" + done + # Open Windows xmkmf reportedly sets LIBDIR instead of USRLIBDIR. +- for ac_extension in a so sl; do ++ for ac_extension in a so sl dylib la dll; do + if test ! -f "$ac_im_usrlibdir/libX11.$ac_extension" && + test -f "$ac_im_libdir/libX11.$ac_extension"; then + ac_im_usrlibdir=$ac_im_libdir; break +@@ -8945,7 +9137,7 @@ + *) test -f "$ac_im_incroot/X11/Xos.h" && ac_x_includes=$ac_im_incroot;; + esac + case $ac_im_usrlibdir in +- /usr/lib | /lib) ;; ++ /usr/lib | /usr/lib64 | /lib | /lib64) ;; + *) test -d "$ac_im_usrlibdir" && ac_x_libraries=$ac_im_usrlibdir ;; + esac + fi +@@ -9006,13 +9198,14 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err +@@ -9020,7 +9213,7 @@ + # We can compile using X headers with no special include directory. + ac_x_includes= + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + for ac_dir in $ac_x_header_dirs; do +@@ -9061,30 +9254,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + LIBS=$ac_save_LIBS + # We can link X programs with no special library path. + ac_x_libraries= + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + LIBS=$ac_save_LIBS +-for ac_dir in `echo "$ac_x_includes $ac_x_header_dirs" | sed s/include/lib/g` ++for ac_dir in `$as_echo "$ac_x_includes $ac_x_header_dirs" | sed s/include/lib/g` + do + # Don't even attempt the hair of trying to link an X program! +- for ac_extension in a so sl; do ++ for ac_extension in a so sl dylib la dll; do + if test -r "$ac_dir/libX11.$ac_extension"; then + ac_x_libraries=$ac_dir + break 2 +@@ -9093,6 +9289,7 @@ + done + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi # $ac_x_libraries = no +@@ -9115,8 +9312,8 @@ + fi # $with_x != no + + if test "$have_x" != yes; then +- { echo "$as_me:$LINENO: result: $have_x" >&5 +-echo "${ECHO_T}$have_x" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $have_x" >&5 ++$as_echo "$have_x" >&6; } + no_x=yes + else + # If each of the values was on the command line, it overrides each guess. +@@ -9126,8 +9323,8 @@ + ac_cv_have_x="have_x=yes\ + ac_x_includes='$x_includes'\ + ac_x_libraries='$x_libraries'" +- { echo "$as_me:$LINENO: result: libraries $x_libraries, headers $x_includes" >&5 +-echo "${ECHO_T}libraries $x_libraries, headers $x_includes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: libraries $x_libraries, headers $x_includes" >&5 ++$as_echo "libraries $x_libraries, headers $x_includes" >&6; } + fi + + if test "$no_x" = yes; then +@@ -9223,17 +9420,17 @@ + LDFLAGS="$LDFLAGS -L${GNUSTEP_SYSTEM_LIBRARIES}" + fi + if test "${ac_cv_header_AppKit_AppKit_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for AppKit/AppKit.h" >&5 +-echo $ECHO_N "checking for AppKit/AppKit.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for AppKit/AppKit.h" >&5 ++$as_echo_n "checking for AppKit/AppKit.h... " >&6; } + if test "${ac_cv_header_AppKit_AppKit_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_AppKit_AppKit_h" >&5 +-echo "${ECHO_T}$ac_cv_header_AppKit_AppKit_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_AppKit_AppKit_h" >&5 ++$as_echo "$ac_cv_header_AppKit_AppKit_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking AppKit/AppKit.h usability" >&5 +-echo $ECHO_N "checking AppKit/AppKit.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking AppKit/AppKit.h usability" >&5 ++$as_echo_n "checking AppKit/AppKit.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -9249,32 +9446,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking AppKit/AppKit.h presence" >&5 +-echo $ECHO_N "checking AppKit/AppKit.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking AppKit/AppKit.h presence" >&5 ++$as_echo_n "checking AppKit/AppKit.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -9288,71 +9486,72 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: AppKit/AppKit.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: AppKit/AppKit.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: AppKit/AppKit.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: AppKit/AppKit.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: AppKit/AppKit.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: AppKit/AppKit.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: AppKit/AppKit.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: AppKit/AppKit.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: AppKit/AppKit.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: AppKit/AppKit.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: AppKit/AppKit.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: AppKit/AppKit.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: AppKit/AppKit.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: AppKit/AppKit.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: AppKit/AppKit.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: AppKit/AppKit.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: AppKit/AppKit.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for AppKit/AppKit.h" >&5 +-echo $ECHO_N "checking for AppKit/AppKit.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for AppKit/AppKit.h" >&5 ++$as_echo_n "checking for AppKit/AppKit.h... " >&6; } + if test "${ac_cv_header_AppKit_AppKit_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_AppKit_AppKit_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_AppKit_AppKit_h" >&5 +-echo "${ECHO_T}$ac_cv_header_AppKit_AppKit_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_AppKit_AppKit_h" >&5 ++$as_echo "$ac_cv_header_AppKit_AppKit_h" >&6; } + + fi +-if test $ac_cv_header_AppKit_AppKit_h = yes; then ++if test "x$ac_cv_header_AppKit_AppKit_h" = x""yes; then + HAVE_NS=yes + else +- { { echo "$as_me:$LINENO: error: \`--with-ns' was specified, but the include ++ { { $as_echo "$as_me:$LINENO: error: \`--with-ns' was specified, but the include + files are missing or cannot be compiled." >&5 +-echo "$as_me: error: \`--with-ns' was specified, but the include ++$as_echo "$as_me: error: \`--with-ns' was specified, but the include + files are missing or cannot be compiled." >&2;} + { (exit 1); exit 1; }; } + fi +@@ -9380,20 +9579,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ns_have_nsinteger=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ns_have_nsinteger=no +@@ -9440,10 +9640,10 @@ + if test "$window_system" = none && test "X$with_x" != "Xno"; then + # Extract the first word of "X", so it can be a program name with args. + set dummy X; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_HAVE_XSERVER+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$HAVE_XSERVER"; then + ac_cv_prog_HAVE_XSERVER="$HAVE_XSERVER" # Let the user override the test. +@@ -9456,7 +9656,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_HAVE_XSERVER="true" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -9468,18 +9668,18 @@ + fi + HAVE_XSERVER=$ac_cv_prog_HAVE_XSERVER + if test -n "$HAVE_XSERVER"; then +- { echo "$as_me:$LINENO: result: $HAVE_XSERVER" >&5 +-echo "${ECHO_T}$HAVE_XSERVER" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $HAVE_XSERVER" >&5 ++$as_echo "$HAVE_XSERVER" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + + if test "$HAVE_XSERVER" = true || + test -n "$DISPLAY" || + test "`echo /usr/lib/libX11.*`" != "/usr/lib/libX11.*"; then +- { { echo "$as_me:$LINENO: error: You seem to be running X, but no X development libraries ++ { { $as_echo "$as_me:$LINENO: error: You seem to be running X, but no X development libraries + were found. You should install the relevant development files for X + and for the toolkit you want, such as Gtk+, Lesstif or Motif. Also make + sure you have development files for image handling, i.e. +@@ -9487,7 +9687,7 @@ + If you are sure you want Emacs compiled without X window support, pass + --without-x + to configure." >&5 +-echo "$as_me: error: You seem to be running X, but no X development libraries ++$as_echo "$as_me: error: You seem to be running X, but no X development libraries + were found. You should install the relevant development files for X + and for the toolkit you want, such as Gtk+, Lesstif or Motif. Also make + sure you have development files for image handling, i.e. +@@ -9509,10 +9709,10 @@ + # Assume not, until told otherwise. + GNU_MALLOC=yes + doug_lea_malloc=yes +-{ echo "$as_me:$LINENO: checking for malloc_get_state" >&5 +-echo $ECHO_N "checking for malloc_get_state... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for malloc_get_state" >&5 ++$as_echo_n "checking for malloc_get_state... " >&6; } + if test "${ac_cv_func_malloc_get_state+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -9565,41 +9765,45 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_func_malloc_get_state=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_func_malloc_get_state=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_malloc_get_state" >&5 +-echo "${ECHO_T}$ac_cv_func_malloc_get_state" >&6; } +-if test $ac_cv_func_malloc_get_state = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_malloc_get_state" >&5 ++$as_echo "$ac_cv_func_malloc_get_state" >&6; } ++if test "x$ac_cv_func_malloc_get_state" = x""yes; then + : + else + doug_lea_malloc=no + fi + +-{ echo "$as_me:$LINENO: checking for malloc_set_state" >&5 +-echo $ECHO_N "checking for malloc_set_state... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for malloc_set_state" >&5 ++$as_echo_n "checking for malloc_set_state... " >&6; } + if test "${ac_cv_func_malloc_set_state+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -9652,41 +9856,45 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_func_malloc_set_state=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_func_malloc_set_state=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_malloc_set_state" >&5 +-echo "${ECHO_T}$ac_cv_func_malloc_set_state" >&6; } +-if test $ac_cv_func_malloc_set_state = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_malloc_set_state" >&5 ++$as_echo "$ac_cv_func_malloc_set_state" >&6; } ++if test "x$ac_cv_func_malloc_set_state" = x""yes; then + : + else + doug_lea_malloc=no + fi + +-{ echo "$as_me:$LINENO: checking whether __after_morecore_hook exists" >&5 +-echo $ECHO_N "checking whether __after_morecore_hook exists... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether __after_morecore_hook exists" >&5 ++$as_echo_n "checking whether __after_morecore_hook exists... " >&6; } + if test "${emacs_cv_var___after_morecore_hook+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -9709,31 +9917,35 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + emacs_cv_var___after_morecore_hook=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_var___after_morecore_hook=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_var___after_morecore_hook" >&5 +-echo "${ECHO_T}$emacs_cv_var___after_morecore_hook" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_var___after_morecore_hook" >&5 ++$as_echo "$emacs_cv_var___after_morecore_hook" >&6; } + if test $emacs_cv_var___after_morecore_hook = no; then + doug_lea_malloc=no + fi +@@ -9763,20 +9975,21 @@ + + for ac_header in stdlib.h unistd.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -9792,32 +10005,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -9831,69 +10045,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -9903,11 +10121,11 @@ + + for ac_func in getpagesize + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -9960,44 +10178,51 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi + done + +-{ echo "$as_me:$LINENO: checking for working mmap" >&5 +-echo $ECHO_N "checking for working mmap... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for working mmap" >&5 ++$as_echo_n "checking for working mmap... " >&6; } + if test "${ac_cv_func_mmap_fixed_mapped+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test "$cross_compiling" = yes; then + ac_cv_func_mmap_fixed_mapped=no +@@ -10141,36 +10366,39 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + ac_cv_func_mmap_fixed_mapped=yes + else +- echo "$as_me: program exited with status $ac_status" >&5 +-echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: program exited with status $ac_status" >&5 ++$as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ( exit $ac_status ) + ac_cv_func_mmap_fixed_mapped=no + fi ++rm -rf conftest.dSYM + rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext + fi + + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_mmap_fixed_mapped" >&5 +-echo "${ECHO_T}$ac_cv_func_mmap_fixed_mapped" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_mmap_fixed_mapped" >&5 ++$as_echo "$ac_cv_func_mmap_fixed_mapped" >&6; } + if test $ac_cv_func_mmap_fixed_mapped = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -10187,10 +10415,10 @@ + LIBS="$libsrc_libs $LIBS" + + +-{ echo "$as_me:$LINENO: checking for dnet_ntoa in -ldnet" >&5 +-echo $ECHO_N "checking for dnet_ntoa in -ldnet... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for dnet_ntoa in -ldnet" >&5 ++$as_echo_n "checking for dnet_ntoa in -ldnet... " >&6; } + if test "${ac_cv_lib_dnet_dnet_ntoa+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-ldnet $LIBS" +@@ -10222,33 +10450,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_dnet_dnet_ntoa=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_dnet_dnet_ntoa=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_dnet_dnet_ntoa" >&5 +-echo "${ECHO_T}$ac_cv_lib_dnet_dnet_ntoa" >&6; } +-if test $ac_cv_lib_dnet_dnet_ntoa = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_dnet_dnet_ntoa" >&5 ++$as_echo "$ac_cv_lib_dnet_dnet_ntoa" >&6; } ++if test "x$ac_cv_lib_dnet_dnet_ntoa" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBDNET 1 + _ACEOF +@@ -10258,10 +10490,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking for main in -lXbsd" >&5 +-echo $ECHO_N "checking for main in -lXbsd... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for main in -lXbsd" >&5 ++$as_echo_n "checking for main in -lXbsd... " >&6; } + if test "${ac_cv_lib_Xbsd_main+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lXbsd $LIBS" +@@ -10287,42 +10519,46 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_Xbsd_main=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_Xbsd_main=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_Xbsd_main" >&5 +-echo "${ECHO_T}$ac_cv_lib_Xbsd_main" >&6; } +-if test $ac_cv_lib_Xbsd_main = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_Xbsd_main" >&5 ++$as_echo "$ac_cv_lib_Xbsd_main" >&6; } ++if test "x$ac_cv_lib_Xbsd_main" = x""yes; then + LD_SWITCH_X_SITE="$LD_SWITCH_X_SITE -lXbsd" + fi + + + +-{ echo "$as_me:$LINENO: checking for cma_open in -lpthreads" >&5 +-echo $ECHO_N "checking for cma_open in -lpthreads... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for cma_open in -lpthreads" >&5 ++$as_echo_n "checking for cma_open in -lpthreads... " >&6; } + if test "${ac_cv_lib_pthreads_cma_open+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lpthreads $LIBS" +@@ -10354,33 +10590,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_pthreads_cma_open=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_pthreads_cma_open=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_pthreads_cma_open" >&5 +-echo "${ECHO_T}$ac_cv_lib_pthreads_cma_open" >&6; } +-if test $ac_cv_lib_pthreads_cma_open = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_pthreads_cma_open" >&5 ++$as_echo "$ac_cv_lib_pthreads_cma_open" >&6; } ++if test "x$ac_cv_lib_pthreads_cma_open" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBPTHREADS 1 + _ACEOF +@@ -10393,10 +10633,10 @@ + + case ${host_os} in + aix*) +- { echo "$as_me:$LINENO: checking for -bbigtoc option" >&5 +-echo $ECHO_N "checking for -bbigtoc option... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for -bbigtoc option" >&5 ++$as_echo_n "checking for -bbigtoc option... " >&6; } + if test "${gdb_cv_bigtoc+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + + case $GCC in +@@ -10426,32 +10666,36 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + : + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + gdb_cv_bigtoc= + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + + fi +-{ echo "$as_me:$LINENO: result: $gdb_cv_bigtoc" >&5 +-echo "${ECHO_T}$gdb_cv_bigtoc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $gdb_cv_bigtoc" >&5 ++$as_echo "$gdb_cv_bigtoc" >&6; } + ;; + esac + +@@ -10478,8 +10722,8 @@ + fi + + if test "${opsys}" = "gnu-linux"; then +- { echo "$as_me:$LINENO: checking whether X on GNU/Linux needs -b to link" >&5 +-echo $ECHO_N "checking whether X on GNU/Linux needs -b to link... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether X on GNU/Linux needs -b to link" >&5 ++$as_echo_n "checking whether X on GNU/Linux needs -b to link... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -10501,26 +10745,30 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + xlinux_first_failure=no + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + xlinux_first_failure=yes + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + if test "${xlinux_first_failure}" = "yes"; then +@@ -10553,26 +10801,30 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + xlinux_second_failure=no + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + xlinux_second_failure=yes + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + if test "${xlinux_second_failure}" = "yes"; then +@@ -10582,22 +10834,22 @@ + C_SWITCH_X_SITE="$OLD_C_SWITCH_X_SITE" + CPPFLAGS="$OLD_CPPFLAGS" + LIBS="$OLD_LIBS" +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + else +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + fi + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + fi + + # Reportedly, some broken Solaris systems have XKBlib.h but are missing + # header files included from there. +- { echo "$as_me:$LINENO: checking for Xkb" >&5 +-echo $ECHO_N "checking for Xkb... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for Xkb" >&5 ++$as_echo_n "checking for Xkb... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -10620,30 +10872,34 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + emacs_xkb=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_xkb=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext +- { echo "$as_me:$LINENO: result: $emacs_xkb" >&5 +-echo "${ECHO_T}$emacs_xkb" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $emacs_xkb" >&5 ++$as_echo "$emacs_xkb" >&6; } + if test $emacs_xkb = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -10659,11 +10915,11 @@ + for ac_func in XrmSetDatabase XScreenResourceString \ + XScreenNumberOfScreen XSetWMProtocols + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -10716,35 +10972,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -10753,10 +11016,10 @@ + fi + + if test "${window_system}" = "x11"; then +- { echo "$as_me:$LINENO: checking X11 version 6" >&5 +-echo $ECHO_N "checking X11 version 6... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking X11 version 6" >&5 ++$as_echo_n "checking X11 version 6... " >&6; } + if test "${emacs_cv_x11_version_6+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -10782,41 +11045,45 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + emacs_cv_x11_version_6=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_x11_version_6=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi + + if test $emacs_cv_x11_version_6 = yes; then +- { echo "$as_me:$LINENO: result: 6 or newer" >&5 +-echo "${ECHO_T}6 or newer" >&6; } ++ { $as_echo "$as_me:$LINENO: result: 6 or newer" >&5 ++$as_echo "6 or newer" >&6; } + + cat >>confdefs.h <<\_ACEOF + #define HAVE_X11R6 1 + _ACEOF + + else +- { echo "$as_me:$LINENO: result: before 6" >&5 +-echo "${ECHO_T}before 6" >&6; } ++ { $as_echo "$as_me:$LINENO: result: before 6" >&5 ++$as_echo "before 6" >&6; } + fi + fi + +@@ -10833,10 +11100,10 @@ + + # Extract the first word of "pkg-config", so it can be a program name with args. + set dummy pkg-config; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_PKG_CONFIG+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $PKG_CONFIG in + [\\/]* | ?:[\\/]*) +@@ -10851,7 +11118,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_PKG_CONFIG="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -10864,11 +11131,11 @@ + fi + PKG_CONFIG=$ac_cv_path_PKG_CONFIG + if test -n "$PKG_CONFIG"; then +- { echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 +-echo "${ECHO_T}$PKG_CONFIG" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 ++$as_echo "$PKG_CONFIG" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -10878,28 +11145,28 @@ + else + PKG_CONFIG_MIN_VERSION=0.9.0 + if $PKG_CONFIG --atleast-pkgconfig-version $PKG_CONFIG_MIN_VERSION; then +- { echo "$as_me:$LINENO: checking for $RSVG_MODULE" >&5 +-echo $ECHO_N "checking for $RSVG_MODULE... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $RSVG_MODULE" >&5 ++$as_echo_n "checking for $RSVG_MODULE... " >&6; } + + if $PKG_CONFIG --exists "$RSVG_MODULE" 2>&5; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + succeeded=yes + +- { echo "$as_me:$LINENO: checking RSVG_CFLAGS" >&5 +-echo $ECHO_N "checking RSVG_CFLAGS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking RSVG_CFLAGS" >&5 ++$as_echo_n "checking RSVG_CFLAGS... " >&6; } + RSVG_CFLAGS=`$PKG_CONFIG --cflags "$RSVG_MODULE"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $RSVG_CFLAGS" >&5 +-echo "${ECHO_T}$RSVG_CFLAGS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $RSVG_CFLAGS" >&5 ++$as_echo "$RSVG_CFLAGS" >&6; } + +- { echo "$as_me:$LINENO: checking RSVG_LIBS" >&5 +-echo $ECHO_N "checking RSVG_LIBS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking RSVG_LIBS" >&5 ++$as_echo_n "checking RSVG_LIBS... " >&6; } + RSVG_LIBS=`$PKG_CONFIG --libs "$RSVG_MODULE"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $RSVG_LIBS" >&5 +-echo "${ECHO_T}$RSVG_LIBS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $RSVG_LIBS" >&5 ++$as_echo "$RSVG_LIBS" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + RSVG_CFLAGS="" + RSVG_LIBS="" + ## If we have a custom action on failure, don't print errors, but +@@ -10950,10 +11217,10 @@ + + # Extract the first word of "pkg-config", so it can be a program name with args. + set dummy pkg-config; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_PKG_CONFIG+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $PKG_CONFIG in + [\\/]* | ?:[\\/]*) +@@ -10968,7 +11235,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_PKG_CONFIG="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -10981,11 +11248,11 @@ + fi + PKG_CONFIG=$ac_cv_path_PKG_CONFIG + if test -n "$PKG_CONFIG"; then +- { echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 +-echo "${ECHO_T}$PKG_CONFIG" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 ++$as_echo "$PKG_CONFIG" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -10995,28 +11262,28 @@ + else + PKG_CONFIG_MIN_VERSION=0.9.0 + if $PKG_CONFIG --atleast-pkgconfig-version $PKG_CONFIG_MIN_VERSION; then +- { echo "$as_me:$LINENO: checking for $GTK_MODULES" >&5 +-echo $ECHO_N "checking for $GTK_MODULES... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $GTK_MODULES" >&5 ++$as_echo_n "checking for $GTK_MODULES... " >&6; } + + if $PKG_CONFIG --exists "$GTK_MODULES" 2>&5; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + succeeded=yes + +- { echo "$as_me:$LINENO: checking GTK_CFLAGS" >&5 +-echo $ECHO_N "checking GTK_CFLAGS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking GTK_CFLAGS" >&5 ++$as_echo_n "checking GTK_CFLAGS... " >&6; } + GTK_CFLAGS=`$PKG_CONFIG --cflags "$GTK_MODULES"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $GTK_CFLAGS" >&5 +-echo "${ECHO_T}$GTK_CFLAGS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $GTK_CFLAGS" >&5 ++$as_echo "$GTK_CFLAGS" >&6; } + +- { echo "$as_me:$LINENO: checking GTK_LIBS" >&5 +-echo $ECHO_N "checking GTK_LIBS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking GTK_LIBS" >&5 ++$as_echo_n "checking GTK_LIBS... " >&6; } + GTK_LIBS=`$PKG_CONFIG --libs "$GTK_MODULES"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $GTK_LIBS" >&5 +-echo "${ECHO_T}$GTK_LIBS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $GTK_LIBS" >&5 ++$as_echo "$GTK_LIBS" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + GTK_CFLAGS="" + GTK_LIBS="" + ## If we have a custom action on failure, don't print errors, but +@@ -11040,8 +11307,8 @@ + fi + + if test "$pkg_check_gtk" = "no" && test "$USE_X_TOOLKIT" != "maybe"; then +- { { echo "$as_me:$LINENO: error: $GTK_PKG_ERRORS" >&5 +-echo "$as_me: error: $GTK_PKG_ERRORS" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: $GTK_PKG_ERRORS" >&5 ++$as_echo "$as_me: error: $GTK_PKG_ERRORS" >&2;} + { (exit 1); exit 1; }; } + fi + fi +@@ -11058,11 +11325,11 @@ + + for ac_func in gtk_main + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -11115,35 +11382,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + GTK_COMPILES=yes + fi +@@ -11151,8 +11425,8 @@ + + if test "${GTK_COMPILES}" != "yes"; then + if test "$USE_X_TOOLKIT" != "maybe"; then +- { { echo "$as_me:$LINENO: error: Gtk+ wanted, but it does not compile, see config.log. Maybe some x11-devel files missing?" >&5 +-echo "$as_me: error: Gtk+ wanted, but it does not compile, see config.log. Maybe some x11-devel files missing?" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: Gtk+ wanted, but it does not compile, see config.log. Maybe some x11-devel files missing?" >&5 ++$as_echo "$as_me: error: Gtk+ wanted, but it does not compile, see config.log. Maybe some x11-devel files missing?" >&2;} + { (exit 1); exit 1; }; }; + fi + else +@@ -11166,11 +11440,11 @@ + if $PKG_CONFIG --atleast-version=2.10 gtk+-2.0; then + : + else +- { echo "$as_me:$LINENO: WARNING: Your version of Gtk+ will have problems with ++ { $as_echo "$as_me:$LINENO: WARNING: Your version of Gtk+ will have problems with + closing open displays. This is no problem if you just use + one display, but if you use more than one and close one of them + Emacs may crash." >&5 +-echo "$as_me: WARNING: Your version of Gtk+ will have problems with ++$as_echo "$as_me: WARNING: Your version of Gtk+ will have problems with + closing open displays. This is no problem if you just use + one display, but if you use more than one and close one of them + Emacs may crash." >&2;} +@@ -11191,11 +11465,11 @@ + + for ac_func in gdk_display_open + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -11248,35 +11522,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + HAVE_GTK_MULTIDISPLAY=yes + fi +@@ -11291,10 +11572,10 @@ + fi + + HAVE_GTK_FILE_SELECTION=no +- { echo "$as_me:$LINENO: checking whether GTK_TYPE_FILE_SELECTION is declared" >&5 +-echo $ECHO_N "checking whether GTK_TYPE_FILE_SELECTION is declared... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether GTK_TYPE_FILE_SELECTION is declared" >&5 ++$as_echo_n "checking whether GTK_TYPE_FILE_SELECTION is declared... " >&6; } + if test "${ac_cv_have_decl_GTK_TYPE_FILE_SELECTION+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -11322,20 +11603,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_have_decl_GTK_TYPE_FILE_SELECTION=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_have_decl_GTK_TYPE_FILE_SELECTION=no +@@ -11343,9 +11625,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_have_decl_GTK_TYPE_FILE_SELECTION" >&5 +-echo "${ECHO_T}$ac_cv_have_decl_GTK_TYPE_FILE_SELECTION" >&6; } +-if test $ac_cv_have_decl_GTK_TYPE_FILE_SELECTION = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_have_decl_GTK_TYPE_FILE_SELECTION" >&5 ++$as_echo "$ac_cv_have_decl_GTK_TYPE_FILE_SELECTION" >&6; } ++if test "x$ac_cv_have_decl_GTK_TYPE_FILE_SELECTION" = x""yes; then + HAVE_GTK_FILE_SELECTION=yes + else + HAVE_GTK_FILE_SELECTION=no +@@ -11355,11 +11637,11 @@ + + for ac_func in gtk_file_selection_new + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -11412,35 +11694,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + HAVE_GTK_FILE_SELECTION=yes + else +@@ -11451,10 +11740,10 @@ + fi + + HAVE_GTK_FILE_CHOOSER=no +- { echo "$as_me:$LINENO: checking whether GTK_TYPE_FILE_CHOOSER is declared" >&5 +-echo $ECHO_N "checking whether GTK_TYPE_FILE_CHOOSER is declared... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether GTK_TYPE_FILE_CHOOSER is declared" >&5 ++$as_echo_n "checking whether GTK_TYPE_FILE_CHOOSER is declared... " >&6; } + if test "${ac_cv_have_decl_GTK_TYPE_FILE_CHOOSER+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -11482,20 +11771,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_have_decl_GTK_TYPE_FILE_CHOOSER=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_have_decl_GTK_TYPE_FILE_CHOOSER=no +@@ -11503,9 +11793,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_have_decl_GTK_TYPE_FILE_CHOOSER" >&5 +-echo "${ECHO_T}$ac_cv_have_decl_GTK_TYPE_FILE_CHOOSER" >&6; } +-if test $ac_cv_have_decl_GTK_TYPE_FILE_CHOOSER = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_have_decl_GTK_TYPE_FILE_CHOOSER" >&5 ++$as_echo "$ac_cv_have_decl_GTK_TYPE_FILE_CHOOSER" >&6; } ++if test "x$ac_cv_have_decl_GTK_TYPE_FILE_CHOOSER" = x""yes; then + HAVE_GTK_FILE_CHOOSER=yes + else + HAVE_GTK_FILE_CHOOSER=no +@@ -11515,11 +11805,11 @@ + + for ac_func in gtk_file_chooser_dialog_new + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -11572,35 +11862,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + HAVE_GTK_FILE_CHOOSER=yes + else +@@ -11624,20 +11921,21 @@ + + for ac_header in pthread.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -11653,32 +11951,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -11692,69 +11991,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -11762,10 +12065,10 @@ + done + + if test "$ac_cv_header_pthread_h"; then +- { echo "$as_me:$LINENO: checking for pthread_self in -lpthread" >&5 +-echo $ECHO_N "checking for pthread_self in -lpthread... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for pthread_self in -lpthread" >&5 ++$as_echo_n "checking for pthread_self in -lpthread... " >&6; } + if test "${ac_cv_lib_pthread_pthread_self+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lpthread $LIBS" +@@ -11797,33 +12100,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_pthread_pthread_self=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_pthread_pthread_self=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_pthread_pthread_self" >&5 +-echo "${ECHO_T}$ac_cv_lib_pthread_pthread_self" >&6; } +-if test $ac_cv_lib_pthread_pthread_self = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_pthread_pthread_self" >&5 ++$as_echo "$ac_cv_lib_pthread_pthread_self" >&6; } ++if test "x$ac_cv_lib_pthread_pthread_self" = x""yes; then + HAVE_GTK_AND_PTHREAD=yes + fi + +@@ -11849,10 +12156,10 @@ + + # Extract the first word of "pkg-config", so it can be a program name with args. + set dummy pkg-config; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_PKG_CONFIG+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $PKG_CONFIG in + [\\/]* | ?:[\\/]*) +@@ -11867,7 +12174,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_PKG_CONFIG="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -11880,11 +12187,11 @@ + fi + PKG_CONFIG=$ac_cv_path_PKG_CONFIG + if test -n "$PKG_CONFIG"; then +- { echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 +-echo "${ECHO_T}$PKG_CONFIG" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 ++$as_echo "$PKG_CONFIG" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -11894,28 +12201,28 @@ + else + PKG_CONFIG_MIN_VERSION=0.9.0 + if $PKG_CONFIG --atleast-pkgconfig-version $PKG_CONFIG_MIN_VERSION; then +- { echo "$as_me:$LINENO: checking for dbus-1 >= 1.0" >&5 +-echo $ECHO_N "checking for dbus-1 >= 1.0... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for dbus-1 >= 1.0" >&5 ++$as_echo_n "checking for dbus-1 >= 1.0... " >&6; } + + if $PKG_CONFIG --exists "dbus-1 >= 1.0" 2>&5; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + succeeded=yes + +- { echo "$as_me:$LINENO: checking DBUS_CFLAGS" >&5 +-echo $ECHO_N "checking DBUS_CFLAGS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking DBUS_CFLAGS" >&5 ++$as_echo_n "checking DBUS_CFLAGS... " >&6; } + DBUS_CFLAGS=`$PKG_CONFIG --cflags "dbus-1 >= 1.0"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $DBUS_CFLAGS" >&5 +-echo "${ECHO_T}$DBUS_CFLAGS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $DBUS_CFLAGS" >&5 ++$as_echo "$DBUS_CFLAGS" >&6; } + +- { echo "$as_me:$LINENO: checking DBUS_LIBS" >&5 +-echo $ECHO_N "checking DBUS_LIBS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking DBUS_LIBS" >&5 ++$as_echo_n "checking DBUS_LIBS... " >&6; } + DBUS_LIBS=`$PKG_CONFIG --libs "dbus-1 >= 1.0"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $DBUS_LIBS" >&5 +-echo "${ECHO_T}$DBUS_LIBS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $DBUS_LIBS" >&5 ++$as_echo "$DBUS_LIBS" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + DBUS_CFLAGS="" + DBUS_LIBS="" + ## If we have a custom action on failure, don't print errors, but +@@ -11950,10 +12257,10 @@ + HAVE_XAW3D=no + if test x"${USE_X_TOOLKIT}" = xmaybe || test x"${USE_X_TOOLKIT}" = xLUCID; then + if test "$with_xaw3d" != no; then +- { echo "$as_me:$LINENO: checking for xaw3d" >&5 +-echo $ECHO_N "checking for xaw3d... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for xaw3d" >&5 ++$as_echo_n "checking for xaw3d... " >&6; } + if test "${emacs_cv_xaw3d+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -11978,26 +12285,30 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + emacs_cv_xaw3d=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_xaw3d=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +@@ -12006,8 +12317,8 @@ + emacs_cv_xaw3d=no + fi + if test $emacs_cv_xaw3d = yes; then +- { echo "$as_me:$LINENO: result: yes; using Lucid toolkit" >&5 +-echo "${ECHO_T}yes; using Lucid toolkit" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes; using Lucid toolkit" >&5 ++$as_echo "yes; using Lucid toolkit" >&6; } + USE_X_TOOLKIT=LUCID + HAVE_XAW3D=yes + +@@ -12016,12 +12327,12 @@ + _ACEOF + + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } +- { echo "$as_me:$LINENO: checking for libXaw" >&5 +-echo $ECHO_N "checking for libXaw... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for libXaw" >&5 ++$as_echo_n "checking for libXaw... " >&6; } + if test "${emacs_cv_xaw+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -12046,41 +12357,45 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + emacs_cv_xaw=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_xaw=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi + + if test $emacs_cv_xaw = yes; then +- { echo "$as_me:$LINENO: result: yes; using Lucid toolkit" >&5 +-echo "${ECHO_T}yes; using Lucid toolkit" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes; using Lucid toolkit" >&5 ++$as_echo "yes; using Lucid toolkit" >&6; } + USE_X_TOOLKIT=LUCID + elif test x"${USE_X_TOOLKIT}" = xLUCID; then +- { { echo "$as_me:$LINENO: error: Lucid toolkit requires X11/Xaw include files" >&5 +-echo "$as_me: error: Lucid toolkit requires X11/Xaw include files" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: Lucid toolkit requires X11/Xaw include files" >&5 ++$as_echo "$as_me: error: Lucid toolkit requires X11/Xaw include files" >&2;} + { (exit 1); exit 1; }; } + else +- { echo "$as_me:$LINENO: result: no; do not use toolkit by default" >&5 +-echo "${ECHO_T}no; do not use toolkit by default" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no; do not use toolkit by default" >&5 ++$as_echo "no; do not use toolkit by default" >&6; } + USE_X_TOOLKIT=none + fi + fi +@@ -12089,10 +12404,10 @@ + X_TOOLKIT_TYPE=$USE_X_TOOLKIT + + if test "${USE_X_TOOLKIT}" != "none"; then +- { echo "$as_me:$LINENO: checking X11 toolkit version" >&5 +-echo $ECHO_N "checking X11 toolkit version... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking X11 toolkit version" >&5 ++$as_echo_n "checking X11 toolkit version... " >&6; } + if test "${emacs_cv_x11_toolkit_version_6+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -12118,42 +12433,46 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + emacs_cv_x11_toolkit_version_6=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_x11_toolkit_version_6=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi + + HAVE_X11XTR6=$emacs_cv_x11_toolkit_version_6 + if test $emacs_cv_x11_toolkit_version_6 = yes; then +- { echo "$as_me:$LINENO: result: 6 or newer" >&5 +-echo "${ECHO_T}6 or newer" >&6; } ++ { $as_echo "$as_me:$LINENO: result: 6 or newer" >&5 ++$as_echo "6 or newer" >&6; } + + cat >>confdefs.h <<\_ACEOF + #define HAVE_X11XTR6 1 + _ACEOF + + else +- { echo "$as_me:$LINENO: result: before 6" >&5 +-echo "${ECHO_T}before 6" >&6; } ++ { $as_echo "$as_me:$LINENO: result: before 6" >&5 ++$as_echo "before 6" >&6; } + fi + + OLDLIBS="$LIBS" +@@ -12163,10 +12482,10 @@ + LIBS="-lXt $LIBS" + fi + +-{ echo "$as_me:$LINENO: checking for XmuConvertStandardSelection in -lXmu" >&5 +-echo $ECHO_N "checking for XmuConvertStandardSelection in -lXmu... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for XmuConvertStandardSelection in -lXmu" >&5 ++$as_echo_n "checking for XmuConvertStandardSelection in -lXmu... " >&6; } + if test "${ac_cv_lib_Xmu_XmuConvertStandardSelection+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lXmu $LIBS" +@@ -12198,33 +12517,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_Xmu_XmuConvertStandardSelection=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_Xmu_XmuConvertStandardSelection=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_Xmu_XmuConvertStandardSelection" >&5 +-echo "${ECHO_T}$ac_cv_lib_Xmu_XmuConvertStandardSelection" >&6; } +-if test $ac_cv_lib_Xmu_XmuConvertStandardSelection = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_Xmu_XmuConvertStandardSelection" >&5 ++$as_echo "$ac_cv_lib_Xmu_XmuConvertStandardSelection" >&6; } ++if test "x$ac_cv_lib_Xmu_XmuConvertStandardSelection" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBXMU 1 + _ACEOF +@@ -12240,10 +12563,10 @@ + if test "${HAVE_X11}" = "yes"; then + if test "${USE_X_TOOLKIT}" != "none"; then + +-{ echo "$as_me:$LINENO: checking for XShapeQueryExtension in -lXext" >&5 +-echo $ECHO_N "checking for XShapeQueryExtension in -lXext... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for XShapeQueryExtension in -lXext" >&5 ++$as_echo_n "checking for XShapeQueryExtension in -lXext... " >&6; } + if test "${ac_cv_lib_Xext_XShapeQueryExtension+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lXext $LIBS" +@@ -12275,33 +12598,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_Xext_XShapeQueryExtension=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_Xext_XShapeQueryExtension=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_Xext_XShapeQueryExtension" >&5 +-echo "${ECHO_T}$ac_cv_lib_Xext_XShapeQueryExtension" >&6; } +-if test $ac_cv_lib_Xext_XShapeQueryExtension = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_Xext_XShapeQueryExtension" >&5 ++$as_echo "$ac_cv_lib_Xext_XShapeQueryExtension" >&6; } ++if test "x$ac_cv_lib_Xext_XShapeQueryExtension" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBXEXT 1 + _ACEOF +@@ -12314,10 +12641,10 @@ + fi + + if test "${USE_X_TOOLKIT}" = "MOTIF"; then +- { echo "$as_me:$LINENO: checking for Motif version 2.1" >&5 +-echo $ECHO_N "checking for Motif version 2.1... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for Motif version 2.1" >&5 ++$as_echo_n "checking for Motif version 2.1... " >&6; } + if test "${emacs_cv_motif_version_2_1+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -12344,20 +12671,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_motif_version_2_1=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_motif_version_2_1=no +@@ -12365,8 +12693,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_motif_version_2_1" >&5 +-echo "${ECHO_T}$emacs_cv_motif_version_2_1" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_motif_version_2_1" >&5 ++$as_echo "$emacs_cv_motif_version_2_1" >&6; } + HAVE_MOTIF_2_1=$emacs_cv_motif_version_2_1 + if test $emacs_cv_motif_version_2_1 = yes; then + HAVE_LIBXP=no +@@ -12375,10 +12703,10 @@ + #define HAVE_MOTIF_2_1 1 + _ACEOF + +- { echo "$as_me:$LINENO: checking for XpCreateContext in -lXp" >&5 +-echo $ECHO_N "checking for XpCreateContext in -lXp... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for XpCreateContext in -lXp" >&5 ++$as_echo_n "checking for XpCreateContext in -lXp... " >&6; } + if test "${ac_cv_lib_Xp_XpCreateContext+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lXp $LIBS" +@@ -12410,33 +12738,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_Xp_XpCreateContext=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_Xp_XpCreateContext=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_Xp_XpCreateContext" >&5 +-echo "${ECHO_T}$ac_cv_lib_Xp_XpCreateContext" >&6; } +-if test $ac_cv_lib_Xp_XpCreateContext = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_Xp_XpCreateContext" >&5 ++$as_echo "$ac_cv_lib_Xp_XpCreateContext" >&6; } ++if test "x$ac_cv_lib_Xp_XpCreateContext" = x""yes; then + HAVE_LIBXP=yes + fi + +@@ -12448,10 +12780,10 @@ + + fi + else +- { echo "$as_me:$LINENO: checking for LessTif where some systems put it" >&5 +-echo $ECHO_N "checking for LessTif where some systems put it... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for LessTif where some systems put it" >&5 ++$as_echo_n "checking for LessTif where some systems put it... " >&6; } + if test "${emacs_cv_lesstif+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + # We put this in CFLAGS temporarily to precede other -I options + # that might be in CFLAGS temporarily. +@@ -12481,20 +12813,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_lesstif=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_lesstif=no +@@ -12502,8 +12835,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_lesstif" >&5 +-echo "${ECHO_T}$emacs_cv_lesstif" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_lesstif" >&5 ++$as_echo "$emacs_cv_lesstif" >&6; } + if test $emacs_cv_lesstif = yes; then + # Make sure this -I option remains in CPPFLAGS after it is set + # back to REAL_CPPFLAGS. +@@ -12576,13 +12909,14 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +@@ -12594,7 +12928,7 @@ + _ACEOF + + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + HAVE_XIM=no +@@ -12653,20 +12987,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_arg6_star=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + +@@ -12699,10 +13034,10 @@ + + # Extract the first word of "pkg-config", so it can be a program name with args. + set dummy pkg-config; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_PKG_CONFIG+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $PKG_CONFIG in + [\\/]* | ?:[\\/]*) +@@ -12717,7 +13052,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_PKG_CONFIG="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -12730,11 +13065,11 @@ + fi + PKG_CONFIG=$ac_cv_path_PKG_CONFIG + if test -n "$PKG_CONFIG"; then +- { echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 +-echo "${ECHO_T}$PKG_CONFIG" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 ++$as_echo "$PKG_CONFIG" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -12744,28 +13079,28 @@ + else + PKG_CONFIG_MIN_VERSION=0.9.0 + if $PKG_CONFIG --atleast-pkgconfig-version $PKG_CONFIG_MIN_VERSION; then +- { echo "$as_me:$LINENO: checking for fontconfig >= 2.2.0" >&5 +-echo $ECHO_N "checking for fontconfig >= 2.2.0... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for fontconfig >= 2.2.0" >&5 ++$as_echo_n "checking for fontconfig >= 2.2.0... " >&6; } + + if $PKG_CONFIG --exists "fontconfig >= 2.2.0" 2>&5; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + succeeded=yes + +- { echo "$as_me:$LINENO: checking FONTCONFIG_CFLAGS" >&5 +-echo $ECHO_N "checking FONTCONFIG_CFLAGS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking FONTCONFIG_CFLAGS" >&5 ++$as_echo_n "checking FONTCONFIG_CFLAGS... " >&6; } + FONTCONFIG_CFLAGS=`$PKG_CONFIG --cflags "fontconfig >= 2.2.0"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $FONTCONFIG_CFLAGS" >&5 +-echo "${ECHO_T}$FONTCONFIG_CFLAGS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $FONTCONFIG_CFLAGS" >&5 ++$as_echo "$FONTCONFIG_CFLAGS" >&6; } + +- { echo "$as_me:$LINENO: checking FONTCONFIG_LIBS" >&5 +-echo $ECHO_N "checking FONTCONFIG_LIBS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking FONTCONFIG_LIBS" >&5 ++$as_echo_n "checking FONTCONFIG_LIBS... " >&6; } + FONTCONFIG_LIBS=`$PKG_CONFIG --libs "fontconfig >= 2.2.0"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $FONTCONFIG_LIBS" >&5 +-echo "${ECHO_T}$FONTCONFIG_LIBS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $FONTCONFIG_LIBS" >&5 ++$as_echo "$FONTCONFIG_LIBS" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + FONTCONFIG_CFLAGS="" + FONTCONFIG_LIBS="" + ## If we have a custom action on failure, don't print errors, but +@@ -12801,10 +13136,10 @@ + + # Extract the first word of "pkg-config", so it can be a program name with args. + set dummy pkg-config; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_PKG_CONFIG+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $PKG_CONFIG in + [\\/]* | ?:[\\/]*) +@@ -12819,7 +13154,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_PKG_CONFIG="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -12832,11 +13167,11 @@ + fi + PKG_CONFIG=$ac_cv_path_PKG_CONFIG + if test -n "$PKG_CONFIG"; then +- { echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 +-echo "${ECHO_T}$PKG_CONFIG" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 ++$as_echo "$PKG_CONFIG" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -12846,28 +13181,28 @@ + else + PKG_CONFIG_MIN_VERSION=0.9.0 + if $PKG_CONFIG --atleast-pkgconfig-version $PKG_CONFIG_MIN_VERSION; then +- { echo "$as_me:$LINENO: checking for xft >= 0.13.0" >&5 +-echo $ECHO_N "checking for xft >= 0.13.0... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for xft >= 0.13.0" >&5 ++$as_echo_n "checking for xft >= 0.13.0... " >&6; } + + if $PKG_CONFIG --exists "xft >= 0.13.0" 2>&5; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + succeeded=yes + +- { echo "$as_me:$LINENO: checking XFT_CFLAGS" >&5 +-echo $ECHO_N "checking XFT_CFLAGS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking XFT_CFLAGS" >&5 ++$as_echo_n "checking XFT_CFLAGS... " >&6; } + XFT_CFLAGS=`$PKG_CONFIG --cflags "xft >= 0.13.0"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $XFT_CFLAGS" >&5 +-echo "${ECHO_T}$XFT_CFLAGS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $XFT_CFLAGS" >&5 ++$as_echo "$XFT_CFLAGS" >&6; } + +- { echo "$as_me:$LINENO: checking XFT_LIBS" >&5 +-echo $ECHO_N "checking XFT_LIBS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking XFT_LIBS" >&5 ++$as_echo_n "checking XFT_LIBS... " >&6; } + XFT_LIBS=`$PKG_CONFIG --libs "xft >= 0.13.0"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $XFT_LIBS" >&5 +-echo "${ECHO_T}$XFT_LIBS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $XFT_LIBS" >&5 ++$as_echo "$XFT_LIBS" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + XFT_CFLAGS="" + XFT_LIBS="" + ## If we have a custom action on failure, don't print errors, but +@@ -12898,17 +13233,17 @@ + CFLAGS="$CFLAGS $XFT_CFLAGS" + LIBS="$XFT_LIBS $LIBS" + if test "${ac_cv_header_X11_Xft_Xft_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for X11/Xft/Xft.h" >&5 +-echo $ECHO_N "checking for X11/Xft/Xft.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for X11/Xft/Xft.h" >&5 ++$as_echo_n "checking for X11/Xft/Xft.h... " >&6; } + if test "${ac_cv_header_X11_Xft_Xft_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_X11_Xft_Xft_h" >&5 +-echo "${ECHO_T}$ac_cv_header_X11_Xft_Xft_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_X11_Xft_Xft_h" >&5 ++$as_echo "$ac_cv_header_X11_Xft_Xft_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking X11/Xft/Xft.h usability" >&5 +-echo $ECHO_N "checking X11/Xft/Xft.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking X11/Xft/Xft.h usability" >&5 ++$as_echo_n "checking X11/Xft/Xft.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -12924,32 +13259,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking X11/Xft/Xft.h presence" >&5 +-echo $ECHO_N "checking X11/Xft/Xft.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking X11/Xft/Xft.h presence" >&5 ++$as_echo_n "checking X11/Xft/Xft.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -12963,70 +13299,71 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: X11/Xft/Xft.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: X11/Xft/Xft.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: X11/Xft/Xft.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: X11/Xft/Xft.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: X11/Xft/Xft.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: X11/Xft/Xft.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: X11/Xft/Xft.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: X11/Xft/Xft.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: X11/Xft/Xft.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: X11/Xft/Xft.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: X11/Xft/Xft.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: X11/Xft/Xft.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: X11/Xft/Xft.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: X11/Xft/Xft.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: X11/Xft/Xft.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/Xft/Xft.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: X11/Xft/Xft.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for X11/Xft/Xft.h" >&5 +-echo $ECHO_N "checking for X11/Xft/Xft.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for X11/Xft/Xft.h" >&5 ++$as_echo_n "checking for X11/Xft/Xft.h... " >&6; } + if test "${ac_cv_header_X11_Xft_Xft_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_X11_Xft_Xft_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_X11_Xft_Xft_h" >&5 +-echo "${ECHO_T}$ac_cv_header_X11_Xft_Xft_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_X11_Xft_Xft_h" >&5 ++$as_echo "$ac_cv_header_X11_Xft_Xft_h" >&6; } + + fi +-if test $ac_cv_header_X11_Xft_Xft_h = yes; then +- { echo "$as_me:$LINENO: checking for XftFontOpen in -lXft" >&5 +-echo $ECHO_N "checking for XftFontOpen in -lXft... $ECHO_C" >&6; } ++if test "x$ac_cv_header_X11_Xft_Xft_h" = x""yes; then ++ { $as_echo "$as_me:$LINENO: checking for XftFontOpen in -lXft" >&5 ++$as_echo_n "checking for XftFontOpen in -lXft... " >&6; } + if test "${ac_cv_lib_Xft_XftFontOpen+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lXft $XFT_LIBS $LIBS" +@@ -13058,33 +13395,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_Xft_XftFontOpen=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_Xft_XftFontOpen=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_Xft_XftFontOpen" >&5 +-echo "${ECHO_T}$ac_cv_lib_Xft_XftFontOpen" >&6; } +-if test $ac_cv_lib_Xft_XftFontOpen = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_Xft_XftFontOpen" >&5 ++$as_echo "$ac_cv_lib_Xft_XftFontOpen" >&6; } ++if test "x$ac_cv_lib_Xft_XftFontOpen" = x""yes; then + HAVE_XFT=yes + fi + +@@ -13135,10 +13476,10 @@ + + # Extract the first word of "pkg-config", so it can be a program name with args. + set dummy pkg-config; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_PKG_CONFIG+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $PKG_CONFIG in + [\\/]* | ?:[\\/]*) +@@ -13153,7 +13494,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_PKG_CONFIG="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -13166,11 +13507,11 @@ + fi + PKG_CONFIG=$ac_cv_path_PKG_CONFIG + if test -n "$PKG_CONFIG"; then +- { echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 +-echo "${ECHO_T}$PKG_CONFIG" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 ++$as_echo "$PKG_CONFIG" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -13180,28 +13521,28 @@ + else + PKG_CONFIG_MIN_VERSION=0.9.0 + if $PKG_CONFIG --atleast-pkgconfig-version $PKG_CONFIG_MIN_VERSION; then +- { echo "$as_me:$LINENO: checking for libotf" >&5 +-echo $ECHO_N "checking for libotf... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for libotf" >&5 ++$as_echo_n "checking for libotf... " >&6; } + + if $PKG_CONFIG --exists "libotf" 2>&5; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + succeeded=yes + +- { echo "$as_me:$LINENO: checking LIBOTF_CFLAGS" >&5 +-echo $ECHO_N "checking LIBOTF_CFLAGS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking LIBOTF_CFLAGS" >&5 ++$as_echo_n "checking LIBOTF_CFLAGS... " >&6; } + LIBOTF_CFLAGS=`$PKG_CONFIG --cflags "libotf"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $LIBOTF_CFLAGS" >&5 +-echo "${ECHO_T}$LIBOTF_CFLAGS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $LIBOTF_CFLAGS" >&5 ++$as_echo "$LIBOTF_CFLAGS" >&6; } + +- { echo "$as_me:$LINENO: checking LIBOTF_LIBS" >&5 +-echo $ECHO_N "checking LIBOTF_LIBS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking LIBOTF_LIBS" >&5 ++$as_echo_n "checking LIBOTF_LIBS... " >&6; } + LIBOTF_LIBS=`$PKG_CONFIG --libs "libotf"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $LIBOTF_LIBS" >&5 +-echo "${ECHO_T}$LIBOTF_LIBS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $LIBOTF_LIBS" >&5 ++$as_echo "$LIBOTF_LIBS" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + LIBOTF_CFLAGS="" + LIBOTF_LIBS="" + ## If we have a custom action on failure, don't print errors, but +@@ -13230,10 +13571,10 @@ + #define HAVE_LIBOTF 1 + _ACEOF + +- { echo "$as_me:$LINENO: checking for OTF_get_variation_glyphs in -lotf" >&5 +-echo $ECHO_N "checking for OTF_get_variation_glyphs in -lotf... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for OTF_get_variation_glyphs in -lotf" >&5 ++$as_echo_n "checking for OTF_get_variation_glyphs in -lotf... " >&6; } + if test "${ac_cv_lib_otf_OTF_get_variation_glyphs+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lotf $LIBS" +@@ -13265,33 +13606,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_otf_OTF_get_variation_glyphs=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_otf_OTF_get_variation_glyphs=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_otf_OTF_get_variation_glyphs" >&5 +-echo "${ECHO_T}$ac_cv_lib_otf_OTF_get_variation_glyphs" >&6; } +-if test $ac_cv_lib_otf_OTF_get_variation_glyphs = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_otf_OTF_get_variation_glyphs" >&5 ++$as_echo "$ac_cv_lib_otf_OTF_get_variation_glyphs" >&6; } ++if test "x$ac_cv_lib_otf_OTF_get_variation_glyphs" = x""yes; then + HAVE_OTF_GET_VARIATION_GLYPHS=yes + else + HAVE_OTF_GET_VARIATION_GLYPHS=no +@@ -13316,10 +13661,10 @@ + + # Extract the first word of "pkg-config", so it can be a program name with args. + set dummy pkg-config; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_path_PKG_CONFIG+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + case $PKG_CONFIG in + [\\/]* | ?:[\\/]*) +@@ -13334,7 +13679,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_PKG_CONFIG="$as_dir/$ac_word$ac_exec_ext" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -13347,11 +13692,11 @@ + fi + PKG_CONFIG=$ac_cv_path_PKG_CONFIG + if test -n "$PKG_CONFIG"; then +- { echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 +-echo "${ECHO_T}$PKG_CONFIG" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 ++$as_echo "$PKG_CONFIG" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + +@@ -13361,28 +13706,28 @@ + else + PKG_CONFIG_MIN_VERSION=0.9.0 + if $PKG_CONFIG --atleast-pkgconfig-version $PKG_CONFIG_MIN_VERSION; then +- { echo "$as_me:$LINENO: checking for m17n-flt" >&5 +-echo $ECHO_N "checking for m17n-flt... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for m17n-flt" >&5 ++$as_echo_n "checking for m17n-flt... " >&6; } + + if $PKG_CONFIG --exists "m17n-flt" 2>&5; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + succeeded=yes + +- { echo "$as_me:$LINENO: checking M17N_FLT_CFLAGS" >&5 +-echo $ECHO_N "checking M17N_FLT_CFLAGS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking M17N_FLT_CFLAGS" >&5 ++$as_echo_n "checking M17N_FLT_CFLAGS... " >&6; } + M17N_FLT_CFLAGS=`$PKG_CONFIG --cflags "m17n-flt"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $M17N_FLT_CFLAGS" >&5 +-echo "${ECHO_T}$M17N_FLT_CFLAGS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $M17N_FLT_CFLAGS" >&5 ++$as_echo "$M17N_FLT_CFLAGS" >&6; } + +- { echo "$as_me:$LINENO: checking M17N_FLT_LIBS" >&5 +-echo $ECHO_N "checking M17N_FLT_LIBS... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking M17N_FLT_LIBS" >&5 ++$as_echo_n "checking M17N_FLT_LIBS... " >&6; } + M17N_FLT_LIBS=`$PKG_CONFIG --libs "m17n-flt"|sed -e 's,///*,/,g'` +- { echo "$as_me:$LINENO: result: $M17N_FLT_LIBS" >&5 +-echo "${ECHO_T}$M17N_FLT_LIBS" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $M17N_FLT_LIBS" >&5 ++$as_echo "$M17N_FLT_LIBS" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + M17N_FLT_CFLAGS="" + M17N_FLT_LIBS="" + ## If we have a custom action on failure, don't print errors, but +@@ -13436,17 +13781,17 @@ + if test "${HAVE_X11}" = "yes"; then + if test "${with_xpm}" != "no"; then + if test "${ac_cv_header_X11_xpm_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for X11/xpm.h" >&5 +-echo $ECHO_N "checking for X11/xpm.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for X11/xpm.h" >&5 ++$as_echo_n "checking for X11/xpm.h... " >&6; } + if test "${ac_cv_header_X11_xpm_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_X11_xpm_h" >&5 +-echo "${ECHO_T}$ac_cv_header_X11_xpm_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_X11_xpm_h" >&5 ++$as_echo "$ac_cv_header_X11_xpm_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking X11/xpm.h usability" >&5 +-echo $ECHO_N "checking X11/xpm.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking X11/xpm.h usability" >&5 ++$as_echo_n "checking X11/xpm.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -13462,32 +13807,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking X11/xpm.h presence" >&5 +-echo $ECHO_N "checking X11/xpm.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking X11/xpm.h presence" >&5 ++$as_echo_n "checking X11/xpm.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -13501,70 +13847,71 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: X11/xpm.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: X11/xpm.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/xpm.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: X11/xpm.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/xpm.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: X11/xpm.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/xpm.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: X11/xpm.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: X11/xpm.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: X11/xpm.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/xpm.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: X11/xpm.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/xpm.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: X11/xpm.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/xpm.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: X11/xpm.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/xpm.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: X11/xpm.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/xpm.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: X11/xpm.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/xpm.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: X11/xpm.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/xpm.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: X11/xpm.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/xpm.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: X11/xpm.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/xpm.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: X11/xpm.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/xpm.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: X11/xpm.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/xpm.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: X11/xpm.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for X11/xpm.h" >&5 +-echo $ECHO_N "checking for X11/xpm.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for X11/xpm.h" >&5 ++$as_echo_n "checking for X11/xpm.h... " >&6; } + if test "${ac_cv_header_X11_xpm_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_X11_xpm_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_X11_xpm_h" >&5 +-echo "${ECHO_T}$ac_cv_header_X11_xpm_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_X11_xpm_h" >&5 ++$as_echo "$ac_cv_header_X11_xpm_h" >&6; } + + fi +-if test $ac_cv_header_X11_xpm_h = yes; then +- { echo "$as_me:$LINENO: checking for XpmReadFileToPixmap in -lXpm" >&5 +-echo $ECHO_N "checking for XpmReadFileToPixmap in -lXpm... $ECHO_C" >&6; } ++if test "x$ac_cv_header_X11_xpm_h" = x""yes; then ++ { $as_echo "$as_me:$LINENO: checking for XpmReadFileToPixmap in -lXpm" >&5 ++$as_echo_n "checking for XpmReadFileToPixmap in -lXpm... " >&6; } + if test "${ac_cv_lib_Xpm_XpmReadFileToPixmap+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lXpm -lX11 $LIBS" +@@ -13596,33 +13943,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_Xpm_XpmReadFileToPixmap=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_Xpm_XpmReadFileToPixmap=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_Xpm_XpmReadFileToPixmap" >&5 +-echo "${ECHO_T}$ac_cv_lib_Xpm_XpmReadFileToPixmap" >&6; } +-if test $ac_cv_lib_Xpm_XpmReadFileToPixmap = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_Xpm_XpmReadFileToPixmap" >&5 ++$as_echo "$ac_cv_lib_Xpm_XpmReadFileToPixmap" >&6; } ++if test "x$ac_cv_lib_Xpm_XpmReadFileToPixmap" = x""yes; then + HAVE_XPM=yes + fi + +@@ -13630,8 +13981,8 @@ + + + if test "${HAVE_XPM}" = "yes"; then +- { echo "$as_me:$LINENO: checking for XpmReturnAllocPixels preprocessor define" >&5 +-echo $ECHO_N "checking for XpmReturnAllocPixels preprocessor define... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for XpmReturnAllocPixels preprocessor define" >&5 ++$as_echo_n "checking for XpmReturnAllocPixels preprocessor define... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -13654,11 +14005,11 @@ + + + if test "${HAVE_XPM}" = "yes"; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + fi + fi +@@ -13677,17 +14028,17 @@ + if test "${HAVE_X11}" = "yes"; then + if test "${with_jpeg}" != "no"; then + if test "${ac_cv_header_jerror_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for jerror.h" >&5 +-echo $ECHO_N "checking for jerror.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for jerror.h" >&5 ++$as_echo_n "checking for jerror.h... " >&6; } + if test "${ac_cv_header_jerror_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_jerror_h" >&5 +-echo "${ECHO_T}$ac_cv_header_jerror_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_jerror_h" >&5 ++$as_echo "$ac_cv_header_jerror_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking jerror.h usability" >&5 +-echo $ECHO_N "checking jerror.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking jerror.h usability" >&5 ++$as_echo_n "checking jerror.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -13703,32 +14054,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking jerror.h presence" >&5 +-echo $ECHO_N "checking jerror.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking jerror.h presence" >&5 ++$as_echo_n "checking jerror.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -13742,70 +14094,71 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: jerror.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: jerror.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: jerror.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: jerror.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: jerror.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: jerror.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: jerror.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: jerror.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: jerror.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: jerror.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: jerror.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: jerror.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: jerror.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: jerror.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: jerror.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: jerror.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: jerror.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: jerror.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: jerror.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: jerror.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: jerror.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: jerror.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: jerror.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: jerror.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: jerror.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: jerror.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: jerror.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: jerror.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: jerror.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: jerror.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: jerror.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: jerror.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for jerror.h" >&5 +-echo $ECHO_N "checking for jerror.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for jerror.h" >&5 ++$as_echo_n "checking for jerror.h... " >&6; } + if test "${ac_cv_header_jerror_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_jerror_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_jerror_h" >&5 +-echo "${ECHO_T}$ac_cv_header_jerror_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_jerror_h" >&5 ++$as_echo "$ac_cv_header_jerror_h" >&6; } + + fi +-if test $ac_cv_header_jerror_h = yes; then +- { echo "$as_me:$LINENO: checking for jpeg_destroy_compress in -ljpeg" >&5 +-echo $ECHO_N "checking for jpeg_destroy_compress in -ljpeg... $ECHO_C" >&6; } ++if test "x$ac_cv_header_jerror_h" = x""yes; then ++ { $as_echo "$as_me:$LINENO: checking for jpeg_destroy_compress in -ljpeg" >&5 ++$as_echo_n "checking for jpeg_destroy_compress in -ljpeg... " >&6; } + if test "${ac_cv_lib_jpeg_jpeg_destroy_compress+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-ljpeg $LIBS" +@@ -13837,33 +14190,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_jpeg_jpeg_destroy_compress=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_jpeg_jpeg_destroy_compress=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_jpeg_jpeg_destroy_compress" >&5 +-echo "${ECHO_T}$ac_cv_lib_jpeg_jpeg_destroy_compress" >&6; } +-if test $ac_cv_lib_jpeg_jpeg_destroy_compress = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_jpeg_jpeg_destroy_compress" >&5 ++$as_echo "$ac_cv_lib_jpeg_jpeg_destroy_compress" >&6; } ++if test "x$ac_cv_lib_jpeg_jpeg_destroy_compress" = x""yes; then + HAVE_JPEG=yes + fi + +@@ -13895,8 +14252,8 @@ + _ACEOF + + else +- { echo "$as_me:$LINENO: WARNING: libjpeg found, but not version 6b or later" >&5 +-echo "$as_me: WARNING: libjpeg found, but not version 6b or later" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: libjpeg found, but not version 6b or later" >&5 ++$as_echo "$as_me: WARNING: libjpeg found, but not version 6b or later" >&2;} + HAVE_JPEG=no + fi + rm -f conftest* +@@ -13914,20 +14271,21 @@ + + for ac_header in png.h libpng/png.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -13943,32 +14301,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -13982,69 +14341,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -14052,10 +14415,10 @@ + done + + if test "$ac_cv_header_png_h" = yes || test "$ac_cv_header_libpng_png_h" = yes ; then +- { echo "$as_me:$LINENO: checking for png_get_channels in -lpng" >&5 +-echo $ECHO_N "checking for png_get_channels in -lpng... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for png_get_channels in -lpng" >&5 ++$as_echo_n "checking for png_get_channels in -lpng... " >&6; } + if test "${ac_cv_lib_png_png_get_channels+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lpng -lz -lm $LIBS" +@@ -14087,33 +14450,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_png_png_get_channels=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_png_png_get_channels=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_png_png_get_channels" >&5 +-echo "${ECHO_T}$ac_cv_lib_png_png_get_channels" >&6; } +-if test $ac_cv_lib_png_png_get_channels = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_png_png_get_channels" >&5 ++$as_echo "$ac_cv_lib_png_png_get_channels" >&6; } ++if test "x$ac_cv_lib_png_png_get_channels" = x""yes; then + HAVE_PNG=yes + fi + +@@ -14134,17 +14501,17 @@ + if test "${HAVE_X11}" = "yes"; then + if test "${with_tiff}" != "no"; then + if test "${ac_cv_header_tiffio_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for tiffio.h" >&5 +-echo $ECHO_N "checking for tiffio.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for tiffio.h" >&5 ++$as_echo_n "checking for tiffio.h... " >&6; } + if test "${ac_cv_header_tiffio_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_tiffio_h" >&5 +-echo "${ECHO_T}$ac_cv_header_tiffio_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_tiffio_h" >&5 ++$as_echo "$ac_cv_header_tiffio_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking tiffio.h usability" >&5 +-echo $ECHO_N "checking tiffio.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking tiffio.h usability" >&5 ++$as_echo_n "checking tiffio.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -14160,32 +14527,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking tiffio.h presence" >&5 +-echo $ECHO_N "checking tiffio.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking tiffio.h presence" >&5 ++$as_echo_n "checking tiffio.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -14199,73 +14567,74 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: tiffio.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: tiffio.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: tiffio.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: tiffio.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: tiffio.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: tiffio.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: tiffio.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: tiffio.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: tiffio.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: tiffio.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: tiffio.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: tiffio.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: tiffio.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: tiffio.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: tiffio.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: tiffio.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: tiffio.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: tiffio.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: tiffio.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: tiffio.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: tiffio.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: tiffio.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: tiffio.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: tiffio.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: tiffio.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: tiffio.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: tiffio.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: tiffio.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: tiffio.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: tiffio.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: tiffio.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: tiffio.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for tiffio.h" >&5 +-echo $ECHO_N "checking for tiffio.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for tiffio.h" >&5 ++$as_echo_n "checking for tiffio.h... " >&6; } + if test "${ac_cv_header_tiffio_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_tiffio_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_tiffio_h" >&5 +-echo "${ECHO_T}$ac_cv_header_tiffio_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_tiffio_h" >&5 ++$as_echo "$ac_cv_header_tiffio_h" >&6; } + + fi +-if test $ac_cv_header_tiffio_h = yes; then ++if test "x$ac_cv_header_tiffio_h" = x""yes; then + tifflibs="-lz -lm" + # At least one tiff package requires the jpeg library. + if test "${HAVE_JPEG}" = yes; then tifflibs="-ljpeg $tifflibs"; fi +- { echo "$as_me:$LINENO: checking for TIFFGetVersion in -ltiff" >&5 +-echo $ECHO_N "checking for TIFFGetVersion in -ltiff... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for TIFFGetVersion in -ltiff" >&5 ++$as_echo_n "checking for TIFFGetVersion in -ltiff... " >&6; } + if test "${ac_cv_lib_tiff_TIFFGetVersion+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-ltiff $tifflibs $LIBS" +@@ -14297,33 +14666,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_tiff_TIFFGetVersion=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_tiff_TIFFGetVersion=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_tiff_TIFFGetVersion" >&5 +-echo "${ECHO_T}$ac_cv_lib_tiff_TIFFGetVersion" >&6; } +-if test $ac_cv_lib_tiff_TIFFGetVersion = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_tiff_TIFFGetVersion" >&5 ++$as_echo "$ac_cv_lib_tiff_TIFFGetVersion" >&6; } ++if test "x$ac_cv_lib_tiff_TIFFGetVersion" = x""yes; then + HAVE_TIFF=yes + fi + +@@ -14345,17 +14718,17 @@ + HAVE_GIF=no + if test "${HAVE_X11}" = "yes" && test "${with_gif}" != "no"; then + if test "${ac_cv_header_gif_lib_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for gif_lib.h" >&5 +-echo $ECHO_N "checking for gif_lib.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for gif_lib.h" >&5 ++$as_echo_n "checking for gif_lib.h... " >&6; } + if test "${ac_cv_header_gif_lib_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_gif_lib_h" >&5 +-echo "${ECHO_T}$ac_cv_header_gif_lib_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_gif_lib_h" >&5 ++$as_echo "$ac_cv_header_gif_lib_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking gif_lib.h usability" >&5 +-echo $ECHO_N "checking gif_lib.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking gif_lib.h usability" >&5 ++$as_echo_n "checking gif_lib.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -14371,32 +14744,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking gif_lib.h presence" >&5 +-echo $ECHO_N "checking gif_lib.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking gif_lib.h presence" >&5 ++$as_echo_n "checking gif_lib.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -14410,72 +14784,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: gif_lib.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: gif_lib.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: gif_lib.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: gif_lib.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gif_lib.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: gif_lib.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gif_lib.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: gif_lib.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: gif_lib.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: gif_lib.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: gif_lib.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: gif_lib.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: gif_lib.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: gif_lib.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: gif_lib.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: gif_lib.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: gif_lib.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: gif_lib.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: gif_lib.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: gif_lib.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gif_lib.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: gif_lib.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gif_lib.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: gif_lib.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gif_lib.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: gif_lib.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gif_lib.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: gif_lib.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gif_lib.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: gif_lib.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gif_lib.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: gif_lib.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for gif_lib.h" >&5 +-echo $ECHO_N "checking for gif_lib.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for gif_lib.h" >&5 ++$as_echo_n "checking for gif_lib.h... " >&6; } + if test "${ac_cv_header_gif_lib_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_gif_lib_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_gif_lib_h" >&5 +-echo "${ECHO_T}$ac_cv_header_gif_lib_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_gif_lib_h" >&5 ++$as_echo "$ac_cv_header_gif_lib_h" >&6; } + + fi +-if test $ac_cv_header_gif_lib_h = yes; then ++if test "x$ac_cv_header_gif_lib_h" = x""yes; then + # EGifPutExtensionLast only exists from version libungif-4.1.0b1. + # Earlier versions can crash Emacs. +- { echo "$as_me:$LINENO: checking for EGifPutExtensionLast in -lgif" >&5 +-echo $ECHO_N "checking for EGifPutExtensionLast in -lgif... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for EGifPutExtensionLast in -lgif" >&5 ++$as_echo_n "checking for EGifPutExtensionLast in -lgif... " >&6; } + if test "${ac_cv_lib_gif_EGifPutExtensionLast+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lgif $LIBS" +@@ -14507,33 +14882,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_gif_EGifPutExtensionLast=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_gif_EGifPutExtensionLast=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_gif_EGifPutExtensionLast" >&5 +-echo "${ECHO_T}$ac_cv_lib_gif_EGifPutExtensionLast" >&6; } +-if test $ac_cv_lib_gif_EGifPutExtensionLast = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_gif_EGifPutExtensionLast" >&5 ++$as_echo "$ac_cv_lib_gif_EGifPutExtensionLast" >&6; } ++if test "x$ac_cv_lib_gif_EGifPutExtensionLast" = x""yes; then + HAVE_GIF=yes + else + try_libungif=yes +@@ -14549,10 +14928,10 @@ + + # If gif_lib.h but no libgif, try libungif. + if test x"$try_libungif" = xyes; then +- { echo "$as_me:$LINENO: checking for EGifPutExtensionLast in -lungif" >&5 +-echo $ECHO_N "checking for EGifPutExtensionLast in -lungif... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for EGifPutExtensionLast in -lungif" >&5 ++$as_echo_n "checking for EGifPutExtensionLast in -lungif... " >&6; } + if test "${ac_cv_lib_ungif_EGifPutExtensionLast+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lungif $LIBS" +@@ -14584,33 +14963,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_ungif_EGifPutExtensionLast=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_ungif_EGifPutExtensionLast=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_ungif_EGifPutExtensionLast" >&5 +-echo "${ECHO_T}$ac_cv_lib_ungif_EGifPutExtensionLast" >&6; } +-if test $ac_cv_lib_ungif_EGifPutExtensionLast = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_ungif_EGifPutExtensionLast" >&5 ++$as_echo "$ac_cv_lib_ungif_EGifPutExtensionLast" >&6; } ++if test "x$ac_cv_lib_ungif_EGifPutExtensionLast" = x""yes; then + HAVE_GIF=yes + fi + +@@ -14649,13 +15032,13 @@ + MISSING="$MISSING libtiff" && WITH_NO="$WITH_NO --with-tiff=no" + + if test "X${MISSING}" != X; then +- { { echo "$as_me:$LINENO: error: The following required libraries were not found: ++ { { $as_echo "$as_me:$LINENO: error: The following required libraries were not found: + $MISSING + Maybe some development libraries/packages are missing? + If you don't want to link with them give + $WITH_NO + as options to configure" >&5 +-echo "$as_me: error: The following required libraries were not found: ++$as_echo "$as_me: error: The following required libraries were not found: + $MISSING + Maybe some development libraries/packages are missing? + If you don't want to link with them give +@@ -14669,17 +15052,17 @@ + HAVE_GPM=no + if test "${with_gpm}" != "no"; then + if test "${ac_cv_header_gpm_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for gpm.h" >&5 +-echo $ECHO_N "checking for gpm.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for gpm.h" >&5 ++$as_echo_n "checking for gpm.h... " >&6; } + if test "${ac_cv_header_gpm_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_gpm_h" >&5 +-echo "${ECHO_T}$ac_cv_header_gpm_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_gpm_h" >&5 ++$as_echo "$ac_cv_header_gpm_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking gpm.h usability" >&5 +-echo $ECHO_N "checking gpm.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking gpm.h usability" >&5 ++$as_echo_n "checking gpm.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -14695,32 +15078,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking gpm.h presence" >&5 +-echo $ECHO_N "checking gpm.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking gpm.h presence" >&5 ++$as_echo_n "checking gpm.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -14734,70 +15118,71 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: gpm.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: gpm.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: gpm.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: gpm.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gpm.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: gpm.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gpm.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: gpm.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: gpm.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: gpm.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: gpm.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: gpm.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: gpm.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: gpm.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: gpm.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: gpm.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: gpm.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: gpm.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: gpm.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: gpm.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gpm.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: gpm.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gpm.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: gpm.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gpm.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: gpm.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gpm.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: gpm.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gpm.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: gpm.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: gpm.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: gpm.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for gpm.h" >&5 +-echo $ECHO_N "checking for gpm.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for gpm.h" >&5 ++$as_echo_n "checking for gpm.h... " >&6; } + if test "${ac_cv_header_gpm_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_gpm_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_gpm_h" >&5 +-echo "${ECHO_T}$ac_cv_header_gpm_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_gpm_h" >&5 ++$as_echo "$ac_cv_header_gpm_h" >&6; } + + fi +-if test $ac_cv_header_gpm_h = yes; then +- { echo "$as_me:$LINENO: checking for Gpm_Open in -lgpm" >&5 +-echo $ECHO_N "checking for Gpm_Open in -lgpm... $ECHO_C" >&6; } ++if test "x$ac_cv_header_gpm_h" = x""yes; then ++ { $as_echo "$as_me:$LINENO: checking for Gpm_Open in -lgpm" >&5 ++$as_echo_n "checking for Gpm_Open in -lgpm... " >&6; } + if test "${ac_cv_lib_gpm_Gpm_Open+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lgpm $LIBS" +@@ -14829,33 +15214,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_gpm_Gpm_Open=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_gpm_Gpm_Open=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_gpm_Gpm_Open" >&5 +-echo "${ECHO_T}$ac_cv_lib_gpm_Gpm_Open" >&6; } +-if test $ac_cv_lib_gpm_Gpm_Open = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_gpm_Gpm_Open" >&5 ++$as_echo "$ac_cv_lib_gpm_Gpm_Open" >&6; } ++if test "x$ac_cv_lib_gpm_Gpm_Open" = x""yes; then + HAVE_GPM=yes + fi + +@@ -14873,17 +15262,17 @@ + fi + + if test "${ac_cv_header_malloc_malloc_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for malloc/malloc.h" >&5 +-echo $ECHO_N "checking for malloc/malloc.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for malloc/malloc.h" >&5 ++$as_echo_n "checking for malloc/malloc.h... " >&6; } + if test "${ac_cv_header_malloc_malloc_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_malloc_malloc_h" >&5 +-echo "${ECHO_T}$ac_cv_header_malloc_malloc_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_malloc_malloc_h" >&5 ++$as_echo "$ac_cv_header_malloc_malloc_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking malloc/malloc.h usability" >&5 +-echo $ECHO_N "checking malloc/malloc.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking malloc/malloc.h usability" >&5 ++$as_echo_n "checking malloc/malloc.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -14899,32 +15288,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking malloc/malloc.h presence" >&5 +-echo $ECHO_N "checking malloc/malloc.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking malloc/malloc.h presence" >&5 ++$as_echo_n "checking malloc/malloc.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -14938,66 +15328,67 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: malloc/malloc.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: malloc/malloc.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: malloc/malloc.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: malloc/malloc.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: malloc/malloc.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: malloc/malloc.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: malloc/malloc.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: malloc/malloc.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: malloc/malloc.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: malloc/malloc.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: malloc/malloc.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: malloc/malloc.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: malloc/malloc.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: malloc/malloc.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: malloc/malloc.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: malloc/malloc.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: malloc/malloc.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: malloc/malloc.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: malloc/malloc.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: malloc/malloc.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: malloc/malloc.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: malloc/malloc.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: malloc/malloc.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: malloc/malloc.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: malloc/malloc.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: malloc/malloc.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: malloc/malloc.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: malloc/malloc.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: malloc/malloc.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: malloc/malloc.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: malloc/malloc.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: malloc/malloc.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for malloc/malloc.h" >&5 +-echo $ECHO_N "checking for malloc/malloc.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for malloc/malloc.h" >&5 ++$as_echo_n "checking for malloc/malloc.h... " >&6; } + if test "${ac_cv_header_malloc_malloc_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_malloc_malloc_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_malloc_malloc_h" >&5 +-echo "${ECHO_T}$ac_cv_header_malloc_malloc_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_malloc_malloc_h" >&5 ++$as_echo "$ac_cv_header_malloc_malloc_h" >&6; } + + fi +-if test $ac_cv_header_malloc_malloc_h = yes; then ++if test "x$ac_cv_header_malloc_malloc_h" = x""yes; then + + cat >>confdefs.h <<\_ACEOF + #define HAVE_MALLOC_MALLOC_H 1 +@@ -15046,17 +15437,17 @@ + HAVE_X_SM=no + if test "${HAVE_X11}" = "yes"; then + if test "${ac_cv_header_X11_SM_SMlib_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for X11/SM/SMlib.h" >&5 +-echo $ECHO_N "checking for X11/SM/SMlib.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for X11/SM/SMlib.h" >&5 ++$as_echo_n "checking for X11/SM/SMlib.h... " >&6; } + if test "${ac_cv_header_X11_SM_SMlib_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_X11_SM_SMlib_h" >&5 +-echo "${ECHO_T}$ac_cv_header_X11_SM_SMlib_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_X11_SM_SMlib_h" >&5 ++$as_echo "$ac_cv_header_X11_SM_SMlib_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking X11/SM/SMlib.h usability" >&5 +-echo $ECHO_N "checking X11/SM/SMlib.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking X11/SM/SMlib.h usability" >&5 ++$as_echo_n "checking X11/SM/SMlib.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -15072,32 +15463,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking X11/SM/SMlib.h presence" >&5 +-echo $ECHO_N "checking X11/SM/SMlib.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking X11/SM/SMlib.h presence" >&5 ++$as_echo_n "checking X11/SM/SMlib.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -15111,70 +15503,71 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: X11/SM/SMlib.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: X11/SM/SMlib.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: X11/SM/SMlib.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: X11/SM/SMlib.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: X11/SM/SMlib.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: X11/SM/SMlib.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: X11/SM/SMlib.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: X11/SM/SMlib.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: X11/SM/SMlib.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: X11/SM/SMlib.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: X11/SM/SMlib.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: X11/SM/SMlib.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: X11/SM/SMlib.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: X11/SM/SMlib.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: X11/SM/SMlib.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: X11/SM/SMlib.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: X11/SM/SMlib.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for X11/SM/SMlib.h" >&5 +-echo $ECHO_N "checking for X11/SM/SMlib.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for X11/SM/SMlib.h" >&5 ++$as_echo_n "checking for X11/SM/SMlib.h... " >&6; } + if test "${ac_cv_header_X11_SM_SMlib_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_X11_SM_SMlib_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_X11_SM_SMlib_h" >&5 +-echo "${ECHO_T}$ac_cv_header_X11_SM_SMlib_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_X11_SM_SMlib_h" >&5 ++$as_echo "$ac_cv_header_X11_SM_SMlib_h" >&6; } + + fi +-if test $ac_cv_header_X11_SM_SMlib_h = yes; then +- { echo "$as_me:$LINENO: checking for SmcOpenConnection in -lSM" >&5 +-echo $ECHO_N "checking for SmcOpenConnection in -lSM... $ECHO_C" >&6; } ++if test "x$ac_cv_header_X11_SM_SMlib_h" = x""yes; then ++ { $as_echo "$as_me:$LINENO: checking for SmcOpenConnection in -lSM" >&5 ++$as_echo_n "checking for SmcOpenConnection in -lSM... " >&6; } + if test "${ac_cv_lib_SM_SmcOpenConnection+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lSM -lICE $LIBS" +@@ -15206,33 +15599,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_SM_SmcOpenConnection=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_SM_SmcOpenConnection=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_SM_SmcOpenConnection" >&5 +-echo "${ECHO_T}$ac_cv_lib_SM_SmcOpenConnection" >&6; } +-if test $ac_cv_lib_SM_SmcOpenConnection = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_SM_SmcOpenConnection" >&5 ++$as_echo "$ac_cv_lib_SM_SmcOpenConnection" >&6; } ++if test "x$ac_cv_lib_SM_SmcOpenConnection" = x""yes; then + HAVE_X_SM=yes + fi + +@@ -15254,10 +15651,10 @@ + fi + + # If netdb.h doesn't declare h_errno, we must declare it by hand. +-{ echo "$as_me:$LINENO: checking whether netdb declares h_errno" >&5 +-echo $ECHO_N "checking whether netdb declares h_errno... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether netdb declares h_errno" >&5 ++$as_echo_n "checking whether netdb declares h_errno... " >&6; } + if test "${emacs_cv_netdb_declares_h_errno+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -15280,31 +15677,35 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + emacs_cv_netdb_declares_h_errno=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_netdb_declares_h_errno=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_netdb_declares_h_errno" >&5 +-echo "${ECHO_T}$emacs_cv_netdb_declares_h_errno" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_netdb_declares_h_errno" >&5 ++$as_echo "$emacs_cv_netdb_declares_h_errno" >&6; } + if test $emacs_cv_netdb_declares_h_errno = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -15315,10 +15716,10 @@ + + # The Ultrix 4.2 mips builtin alloca declared by alloca.h only works + # for constant arguments. Useless! +-{ echo "$as_me:$LINENO: checking for working alloca.h" >&5 +-echo $ECHO_N "checking for working alloca.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for working alloca.h" >&5 ++$as_echo_n "checking for working alloca.h... " >&6; } + if test "${ac_cv_working_alloca_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -15342,31 +15743,35 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_working_alloca_h=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_working_alloca_h=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_working_alloca_h" >&5 +-echo "${ECHO_T}$ac_cv_working_alloca_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_working_alloca_h" >&5 ++$as_echo "$ac_cv_working_alloca_h" >&6; } + if test $ac_cv_working_alloca_h = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -15375,10 +15780,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking for alloca" >&5 +-echo $ECHO_N "checking for alloca... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for alloca" >&5 ++$as_echo_n "checking for alloca... " >&6; } + if test "${ac_cv_func_alloca_works+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -15422,31 +15827,35 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_func_alloca_works=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_func_alloca_works=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_alloca_works" >&5 +-echo "${ECHO_T}$ac_cv_func_alloca_works" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_alloca_works" >&5 ++$as_echo "$ac_cv_func_alloca_works" >&6; } + + if test $ac_cv_func_alloca_works = yes; then + +@@ -15467,10 +15876,10 @@ + _ACEOF + + +-{ echo "$as_me:$LINENO: checking whether \`alloca.c' needs Cray hooks" >&5 +-echo $ECHO_N "checking whether \`alloca.c' needs Cray hooks... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether \`alloca.c' needs Cray hooks" >&5 ++$as_echo_n "checking whether \`alloca.c' needs Cray hooks... " >&6; } + if test "${ac_cv_os_cray+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -15494,15 +15903,15 @@ + rm -f conftest* + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_os_cray" >&5 +-echo "${ECHO_T}$ac_cv_os_cray" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_os_cray" >&5 ++$as_echo "$ac_cv_os_cray" >&6; } + if test $ac_cv_os_cray = yes; then + for ac_func in _getb67 GETB67 getb67; do +- as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++ as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -15555,33 +15964,40 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define CRAY_STACKSEG_END $ac_func +@@ -15593,10 +16009,10 @@ + done + fi + +-{ echo "$as_me:$LINENO: checking stack direction for C alloca" >&5 +-echo $ECHO_N "checking stack direction for C alloca... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking stack direction for C alloca" >&5 ++$as_echo_n "checking stack direction for C alloca... " >&6; } + if test "${ac_cv_c_stack_direction+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test "$cross_compiling" = yes; then + ac_cv_c_stack_direction=0 +@@ -15634,36 +16050,39 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + ac_cv_c_stack_direction=1 + else +- echo "$as_me: program exited with status $ac_status" >&5 +-echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: program exited with status $ac_status" >&5 ++$as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ( exit $ac_status ) + ac_cv_c_stack_direction=-1 + fi ++rm -rf conftest.dSYM + rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext + fi + + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_c_stack_direction" >&5 +-echo "${ECHO_T}$ac_cv_c_stack_direction" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_c_stack_direction" >&5 ++$as_echo "$ac_cv_c_stack_direction" >&6; } + + cat >>confdefs.h <<_ACEOF + #define STACK_DIRECTION $ac_cv_c_stack_direction +@@ -15674,18 +16093,18 @@ + + + if test x"$ac_cv_func_alloca_works" != xyes; then +- { { echo "$as_me:$LINENO: error: a system implementation of alloca is required " >&5 +-echo "$as_me: error: a system implementation of alloca is required " >&2;} ++ { { $as_echo "$as_me:$LINENO: error: a system implementation of alloca is required " >&5 ++$as_echo "$as_me: error: a system implementation of alloca is required " >&2;} + { (exit 1); exit 1; }; } + fi + + # fmod, logb, and frexp are found in -lm on most systems. + # On HPUX 9.01, -lm does not contain logb, so check for sqrt. + +-{ echo "$as_me:$LINENO: checking for sqrt in -lm" >&5 +-echo $ECHO_N "checking for sqrt in -lm... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for sqrt in -lm" >&5 ++$as_echo_n "checking for sqrt in -lm... " >&6; } + if test "${ac_cv_lib_m_sqrt+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lm $LIBS" +@@ -15717,33 +16136,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_m_sqrt=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_m_sqrt=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_m_sqrt" >&5 +-echo "${ECHO_T}$ac_cv_lib_m_sqrt" >&6; } +-if test $ac_cv_lib_m_sqrt = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_m_sqrt" >&5 ++$as_echo "$ac_cv_lib_m_sqrt" >&6; } ++if test "x$ac_cv_lib_m_sqrt" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBM 1 + _ACEOF +@@ -15756,10 +16179,10 @@ + # Check for mail-locking functions in a "mail" library. Probably this should + # have the same check as for liblockfile below. + +-{ echo "$as_me:$LINENO: checking for maillock in -lmail" >&5 +-echo $ECHO_N "checking for maillock in -lmail... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for maillock in -lmail" >&5 ++$as_echo_n "checking for maillock in -lmail... " >&6; } + if test "${ac_cv_lib_mail_maillock+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lmail $LIBS" +@@ -15791,33 +16214,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_mail_maillock=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_mail_maillock=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_mail_maillock" >&5 +-echo "${ECHO_T}$ac_cv_lib_mail_maillock" >&6; } +-if test $ac_cv_lib_mail_maillock = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_mail_maillock" >&5 ++$as_echo "$ac_cv_lib_mail_maillock" >&6; } ++if test "x$ac_cv_lib_mail_maillock" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBMAIL 1 + _ACEOF +@@ -15827,10 +16254,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking for maillock in -llockfile" >&5 +-echo $ECHO_N "checking for maillock in -llockfile... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for maillock in -llockfile" >&5 ++$as_echo_n "checking for maillock in -llockfile... " >&6; } + if test "${ac_cv_lib_lockfile_maillock+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-llockfile $LIBS" +@@ -15862,33 +16289,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_lockfile_maillock=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_lockfile_maillock=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_lockfile_maillock" >&5 +-echo "${ECHO_T}$ac_cv_lib_lockfile_maillock" >&6; } +-if test $ac_cv_lib_lockfile_maillock = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_lockfile_maillock" >&5 ++$as_echo "$ac_cv_lib_lockfile_maillock" >&6; } ++if test "x$ac_cv_lib_lockfile_maillock" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBLOCKFILE 1 + _ACEOF +@@ -15903,10 +16334,10 @@ + if test "$ac_cv_lib_lockfile_maillock" = no; then + # Extract the first word of "liblockfile.so", so it can be a program name with args. + set dummy liblockfile.so; ac_word=$2 +-{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 ++$as_echo_n "checking for $ac_word... " >&6; } + if test "${ac_cv_prog_liblockfile+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test -n "$liblockfile"; then + ac_cv_prog_liblockfile="$liblockfile" # Let the user override the test. +@@ -15920,7 +16351,7 @@ + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_liblockfile="yes" +- echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 ++ $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi + done +@@ -15932,19 +16363,19 @@ + fi + liblockfile=$ac_cv_prog_liblockfile + if test -n "$liblockfile"; then +- { echo "$as_me:$LINENO: result: $liblockfile" >&5 +-echo "${ECHO_T}$liblockfile" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $liblockfile" >&5 ++$as_echo "$liblockfile" >&6; } + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + + + if test $ac_cv_prog_liblockfile = yes; then +- { { echo "$as_me:$LINENO: error: Shared liblockfile found but can't link against it. ++ { { $as_echo "$as_me:$LINENO: error: Shared liblockfile found but can't link against it. + This probably means that movemail could lose mail. + There may be a \`development' package to install containing liblockfile." >&5 +-echo "$as_me: error: Shared liblockfile found but can't link against it. ++$as_echo "$as_me: error: Shared liblockfile found but can't link against it. + This probably means that movemail could lose mail. + There may be a \`development' package to install containing liblockfile." >&2;} + { (exit 1); exit 1; }; } +@@ -15954,11 +16385,11 @@ + + for ac_func in touchlock + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -16011,35 +16442,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -16048,20 +16486,21 @@ + + for ac_header in maillock.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -16077,32 +16516,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -16116,69 +16556,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -16268,11 +16712,11 @@ + memset memcmp difftime memcpy mempcpy mblen mbrlen posix_memalign \ + cfmakeraw cfsetspeed + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -16325,35 +16769,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -16363,20 +16814,21 @@ + + for ac_header in sys/un.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -16392,32 +16844,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -16431,69 +16884,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -16507,20 +16964,21 @@ + + for ac_header in $ac_header_list + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -16536,32 +16994,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -16575,69 +17034,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -16654,11 +17117,11 @@ + + for ac_func in $ac_func_list + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -16711,35 +17174,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -16761,10 +17231,10 @@ + + + +-{ echo "$as_me:$LINENO: checking for working mktime" >&5 +-echo $ECHO_N "checking for working mktime... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for working mktime" >&5 ++$as_echo_n "checking for working mktime... " >&6; } + if test "${ac_cv_func_working_mktime+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test "$cross_compiling" = yes; then + ac_cv_func_working_mktime=no +@@ -16976,36 +17446,39 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + ac_cv_func_working_mktime=yes + else +- echo "$as_me: program exited with status $ac_status" >&5 +-echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: program exited with status $ac_status" >&5 ++$as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ( exit $ac_status ) + ac_cv_func_working_mktime=no + fi ++rm -rf conftest.dSYM + rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext + fi + + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_working_mktime" >&5 +-echo "${ECHO_T}$ac_cv_func_working_mktime" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_working_mktime" >&5 ++$as_echo "$ac_cv_func_working_mktime" >&6; } + if test $ac_cv_func_working_mktime = no; then + case " $LIBOBJS " in + *" mktime.$ac_objext "* ) ;; +@@ -17027,17 +17500,17 @@ + + # Make sure getloadavg.c is where it belongs, at configure-time. + test -f "$srcdir/$ac_config_libobj_dir/getloadavg.c" || +- { { echo "$as_me:$LINENO: error: $srcdir/$ac_config_libobj_dir/getloadavg.c is missing" >&5 +-echo "$as_me: error: $srcdir/$ac_config_libobj_dir/getloadavg.c is missing" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: $srcdir/$ac_config_libobj_dir/getloadavg.c is missing" >&5 ++$as_echo "$as_me: error: $srcdir/$ac_config_libobj_dir/getloadavg.c is missing" >&2;} + { (exit 1); exit 1; }; } + + ac_save_LIBS=$LIBS + + # Check for getloadavg, but be sure not to touch the cache variable. +-({ echo "$as_me:$LINENO: checking for getloadavg" >&5 +-echo $ECHO_N "checking for getloadavg... $ECHO_C" >&6; } ++({ $as_echo "$as_me:$LINENO: checking for getloadavg" >&5 ++$as_echo_n "checking for getloadavg... " >&6; } + if test "${ac_cv_func_getloadavg+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -17090,32 +17563,36 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_func_getloadavg=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_func_getloadavg=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_getloadavg" >&5 +-echo "${ECHO_T}$ac_cv_func_getloadavg" >&6; } +-if test $ac_cv_func_getloadavg = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_getloadavg" >&5 ++$as_echo "$ac_cv_func_getloadavg" >&6; } ++if test "x$ac_cv_func_getloadavg" = x""yes; then + exit 0 + else + exit 1 +@@ -17126,11 +17603,11 @@ + + for ac_func in pstat_getdynamic + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -17183,35 +17660,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -17220,10 +17704,10 @@ + + # Solaris has libkstat which does not require root. + +-{ echo "$as_me:$LINENO: checking for kstat_open in -lkstat" >&5 +-echo $ECHO_N "checking for kstat_open in -lkstat... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for kstat_open in -lkstat" >&5 ++$as_echo_n "checking for kstat_open in -lkstat... " >&6; } + if test "${ac_cv_lib_kstat_kstat_open+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lkstat $LIBS" +@@ -17255,33 +17739,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_kstat_kstat_open=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_kstat_kstat_open=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_kstat_kstat_open" >&5 +-echo "${ECHO_T}$ac_cv_lib_kstat_kstat_open" >&6; } +-if test $ac_cv_lib_kstat_kstat_open = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_kstat_kstat_open" >&5 ++$as_echo "$ac_cv_lib_kstat_kstat_open" >&6; } ++if test "x$ac_cv_lib_kstat_kstat_open" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBKSTAT 1 + _ACEOF +@@ -17297,10 +17785,10 @@ + # to get the right answer into the cache. + # For kstat on solaris, we need libelf to force the definition of SVR4 below. + if test $ac_have_func = no; then +- { echo "$as_me:$LINENO: checking for elf_begin in -lelf" >&5 +-echo $ECHO_N "checking for elf_begin in -lelf... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for elf_begin in -lelf" >&5 ++$as_echo_n "checking for elf_begin in -lelf... " >&6; } + if test "${ac_cv_lib_elf_elf_begin+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lelf $LIBS" +@@ -17332,42 +17820,46 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_elf_elf_begin=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_elf_elf_begin=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_elf_elf_begin" >&5 +-echo "${ECHO_T}$ac_cv_lib_elf_elf_begin" >&6; } +-if test $ac_cv_lib_elf_elf_begin = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_elf_elf_begin" >&5 ++$as_echo "$ac_cv_lib_elf_elf_begin" >&6; } ++if test "x$ac_cv_lib_elf_elf_begin" = x""yes; then + LIBS="-lelf $LIBS" + fi + + fi + if test $ac_have_func = no; then +- { echo "$as_me:$LINENO: checking for kvm_open in -lkvm" >&5 +-echo $ECHO_N "checking for kvm_open in -lkvm... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for kvm_open in -lkvm" >&5 ++$as_echo_n "checking for kvm_open in -lkvm... " >&6; } + if test "${ac_cv_lib_kvm_kvm_open+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lkvm $LIBS" +@@ -17399,41 +17891,45 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_kvm_kvm_open=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_kvm_kvm_open=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_kvm_kvm_open" >&5 +-echo "${ECHO_T}$ac_cv_lib_kvm_kvm_open" >&6; } +-if test $ac_cv_lib_kvm_kvm_open = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_kvm_kvm_open" >&5 ++$as_echo "$ac_cv_lib_kvm_kvm_open" >&6; } ++if test "x$ac_cv_lib_kvm_kvm_open" = x""yes; then + LIBS="-lkvm $LIBS" + fi + + # Check for the 4.4BSD definition of getloadavg. +- { echo "$as_me:$LINENO: checking for getloadavg in -lutil" >&5 +-echo $ECHO_N "checking for getloadavg in -lutil... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for getloadavg in -lutil" >&5 ++$as_echo_n "checking for getloadavg in -lutil... " >&6; } + if test "${ac_cv_lib_util_getloadavg+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lutil $LIBS" +@@ -17465,33 +17961,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_util_getloadavg=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_util_getloadavg=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_util_getloadavg" >&5 +-echo "${ECHO_T}$ac_cv_lib_util_getloadavg" >&6; } +-if test $ac_cv_lib_util_getloadavg = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_util_getloadavg" >&5 ++$as_echo "$ac_cv_lib_util_getloadavg" >&6; } ++if test "x$ac_cv_lib_util_getloadavg" = x""yes; then + LIBS="-lutil $LIBS" ac_have_func=yes ac_cv_func_getloadavg_setgid=yes + fi + +@@ -17502,10 +18002,10 @@ + # Since it is not a standard part of AIX, it might be installed locally. + ac_getloadavg_LIBS=$LIBS + LIBS="-L/usr/local/lib $LIBS" +- { echo "$as_me:$LINENO: checking for getloadavg in -lgetloadavg" >&5 +-echo $ECHO_N "checking for getloadavg in -lgetloadavg... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for getloadavg in -lgetloadavg" >&5 ++$as_echo_n "checking for getloadavg in -lgetloadavg... " >&6; } + if test "${ac_cv_lib_getloadavg_getloadavg+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lgetloadavg $LIBS" +@@ -17537,33 +18037,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_getloadavg_getloadavg=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_getloadavg_getloadavg=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_getloadavg_getloadavg" >&5 +-echo "${ECHO_T}$ac_cv_lib_getloadavg_getloadavg" >&6; } +-if test $ac_cv_lib_getloadavg_getloadavg = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_getloadavg_getloadavg" >&5 ++$as_echo "$ac_cv_lib_getloadavg_getloadavg" >&6; } ++if test "x$ac_cv_lib_getloadavg_getloadavg" = x""yes; then + LIBS="-lgetloadavg $LIBS" + else + LIBS=$ac_getloadavg_LIBS +@@ -17576,11 +18080,11 @@ + + for ac_func in getloadavg + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -17633,35 +18137,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + else +@@ -17679,17 +18190,17 @@ + # Figure out what our getloadavg.c needs. + ac_have_func=no + if test "${ac_cv_header_sys_dg_sys_info_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for sys/dg_sys_info.h" >&5 +-echo $ECHO_N "checking for sys/dg_sys_info.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for sys/dg_sys_info.h" >&5 ++$as_echo_n "checking for sys/dg_sys_info.h... " >&6; } + if test "${ac_cv_header_sys_dg_sys_info_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_sys_dg_sys_info_h" >&5 +-echo "${ECHO_T}$ac_cv_header_sys_dg_sys_info_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_sys_dg_sys_info_h" >&5 ++$as_echo "$ac_cv_header_sys_dg_sys_info_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking sys/dg_sys_info.h usability" >&5 +-echo $ECHO_N "checking sys/dg_sys_info.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking sys/dg_sys_info.h usability" >&5 ++$as_echo_n "checking sys/dg_sys_info.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -17705,32 +18216,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking sys/dg_sys_info.h presence" >&5 +-echo $ECHO_N "checking sys/dg_sys_info.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking sys/dg_sys_info.h presence" >&5 ++$as_echo_n "checking sys/dg_sys_info.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -17744,66 +18256,67 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: sys/dg_sys_info.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: sys/dg_sys_info.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: sys/dg_sys_info.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: sys/dg_sys_info.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: sys/dg_sys_info.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: sys/dg_sys_info.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: sys/dg_sys_info.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: sys/dg_sys_info.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: sys/dg_sys_info.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: sys/dg_sys_info.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: sys/dg_sys_info.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: sys/dg_sys_info.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: sys/dg_sys_info.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: sys/dg_sys_info.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: sys/dg_sys_info.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/dg_sys_info.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: sys/dg_sys_info.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for sys/dg_sys_info.h" >&5 +-echo $ECHO_N "checking for sys/dg_sys_info.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for sys/dg_sys_info.h" >&5 ++$as_echo_n "checking for sys/dg_sys_info.h... " >&6; } + if test "${ac_cv_header_sys_dg_sys_info_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_sys_dg_sys_info_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_sys_dg_sys_info_h" >&5 +-echo "${ECHO_T}$ac_cv_header_sys_dg_sys_info_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_sys_dg_sys_info_h" >&5 ++$as_echo "$ac_cv_header_sys_dg_sys_info_h" >&6; } + + fi +-if test $ac_cv_header_sys_dg_sys_info_h = yes; then ++if test "x$ac_cv_header_sys_dg_sys_info_h" = x""yes; then + ac_have_func=yes + + cat >>confdefs.h <<\_ACEOF +@@ -17811,10 +18324,10 @@ + _ACEOF + + +-{ echo "$as_me:$LINENO: checking for dg_sys_info in -ldgc" >&5 +-echo $ECHO_N "checking for dg_sys_info in -ldgc... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for dg_sys_info in -ldgc" >&5 ++$as_echo_n "checking for dg_sys_info in -ldgc... " >&6; } + if test "${ac_cv_lib_dgc_dg_sys_info+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-ldgc $LIBS" +@@ -17846,33 +18359,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_dgc_dg_sys_info=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_dgc_dg_sys_info=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_dgc_dg_sys_info" >&5 +-echo "${ECHO_T}$ac_cv_lib_dgc_dg_sys_info" >&6; } +-if test $ac_cv_lib_dgc_dg_sys_info = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_dgc_dg_sys_info" >&5 ++$as_echo "$ac_cv_lib_dgc_dg_sys_info" >&6; } ++if test "x$ac_cv_lib_dgc_dg_sys_info" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBDGC 1 + _ACEOF +@@ -17886,17 +18403,17 @@ + + + if test "${ac_cv_header_locale_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for locale.h" >&5 +-echo $ECHO_N "checking for locale.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for locale.h" >&5 ++$as_echo_n "checking for locale.h... " >&6; } + if test "${ac_cv_header_locale_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_locale_h" >&5 +-echo "${ECHO_T}$ac_cv_header_locale_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_locale_h" >&5 ++$as_echo "$ac_cv_header_locale_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking locale.h usability" >&5 +-echo $ECHO_N "checking locale.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking locale.h usability" >&5 ++$as_echo_n "checking locale.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -17912,32 +18429,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking locale.h presence" >&5 +-echo $ECHO_N "checking locale.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking locale.h presence" >&5 ++$as_echo_n "checking locale.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -17951,63 +18469,64 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: locale.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: locale.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: locale.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: locale.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: locale.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: locale.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: locale.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: locale.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: locale.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: locale.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: locale.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: locale.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: locale.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: locale.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: locale.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: locale.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: locale.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: locale.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: locale.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: locale.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: locale.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: locale.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: locale.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: locale.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: locale.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: locale.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: locale.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: locale.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: locale.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: locale.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: locale.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: locale.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for locale.h" >&5 +-echo $ECHO_N "checking for locale.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for locale.h" >&5 ++$as_echo_n "checking for locale.h... " >&6; } + if test "${ac_cv_header_locale_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_locale_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_locale_h" >&5 +-echo "${ECHO_T}$ac_cv_header_locale_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_locale_h" >&5 ++$as_echo "$ac_cv_header_locale_h" >&6; } + + fi + +@@ -18015,11 +18534,11 @@ + + for ac_func in setlocale + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -18072,35 +18591,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -18121,17 +18647,17 @@ + + if test $ac_have_func = no; then + if test "${ac_cv_header_inq_stats_cpustats_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for inq_stats/cpustats.h" >&5 +-echo $ECHO_N "checking for inq_stats/cpustats.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for inq_stats/cpustats.h" >&5 ++$as_echo_n "checking for inq_stats/cpustats.h... " >&6; } + if test "${ac_cv_header_inq_stats_cpustats_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_inq_stats_cpustats_h" >&5 +-echo "${ECHO_T}$ac_cv_header_inq_stats_cpustats_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_inq_stats_cpustats_h" >&5 ++$as_echo "$ac_cv_header_inq_stats_cpustats_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking inq_stats/cpustats.h usability" >&5 +-echo $ECHO_N "checking inq_stats/cpustats.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking inq_stats/cpustats.h usability" >&5 ++$as_echo_n "checking inq_stats/cpustats.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -18147,32 +18673,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking inq_stats/cpustats.h presence" >&5 +-echo $ECHO_N "checking inq_stats/cpustats.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking inq_stats/cpustats.h presence" >&5 ++$as_echo_n "checking inq_stats/cpustats.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -18186,66 +18713,67 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: inq_stats/cpustats.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: inq_stats/cpustats.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: inq_stats/cpustats.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: inq_stats/cpustats.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: inq_stats/cpustats.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: inq_stats/cpustats.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: inq_stats/cpustats.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: inq_stats/cpustats.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: inq_stats/cpustats.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: inq_stats/cpustats.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: inq_stats/cpustats.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: inq_stats/cpustats.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: inq_stats/cpustats.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: inq_stats/cpustats.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: inq_stats/cpustats.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: inq_stats/cpustats.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: inq_stats/cpustats.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for inq_stats/cpustats.h" >&5 +-echo $ECHO_N "checking for inq_stats/cpustats.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for inq_stats/cpustats.h" >&5 ++$as_echo_n "checking for inq_stats/cpustats.h... " >&6; } + if test "${ac_cv_header_inq_stats_cpustats_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_inq_stats_cpustats_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_inq_stats_cpustats_h" >&5 +-echo "${ECHO_T}$ac_cv_header_inq_stats_cpustats_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_inq_stats_cpustats_h" >&5 ++$as_echo "$ac_cv_header_inq_stats_cpustats_h" >&6; } + + fi +-if test $ac_cv_header_inq_stats_cpustats_h = yes; then ++if test "x$ac_cv_header_inq_stats_cpustats_h" = x""yes; then + ac_have_func=yes + + cat >>confdefs.h <<\_ACEOF +@@ -18264,17 +18792,17 @@ + + if test $ac_have_func = no; then + if test "${ac_cv_header_sys_cpustats_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for sys/cpustats.h" >&5 +-echo $ECHO_N "checking for sys/cpustats.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for sys/cpustats.h" >&5 ++$as_echo_n "checking for sys/cpustats.h... " >&6; } + if test "${ac_cv_header_sys_cpustats_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_sys_cpustats_h" >&5 +-echo "${ECHO_T}$ac_cv_header_sys_cpustats_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_sys_cpustats_h" >&5 ++$as_echo "$ac_cv_header_sys_cpustats_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking sys/cpustats.h usability" >&5 +-echo $ECHO_N "checking sys/cpustats.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking sys/cpustats.h usability" >&5 ++$as_echo_n "checking sys/cpustats.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -18290,32 +18818,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking sys/cpustats.h presence" >&5 +-echo $ECHO_N "checking sys/cpustats.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking sys/cpustats.h presence" >&5 ++$as_echo_n "checking sys/cpustats.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -18329,66 +18858,67 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: sys/cpustats.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: sys/cpustats.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/cpustats.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: sys/cpustats.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/cpustats.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: sys/cpustats.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/cpustats.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: sys/cpustats.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: sys/cpustats.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: sys/cpustats.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/cpustats.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: sys/cpustats.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/cpustats.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: sys/cpustats.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/cpustats.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: sys/cpustats.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/cpustats.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: sys/cpustats.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: sys/cpustats.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: sys/cpustats.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/cpustats.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: sys/cpustats.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/cpustats.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: sys/cpustats.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/cpustats.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: sys/cpustats.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/cpustats.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: sys/cpustats.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/cpustats.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: sys/cpustats.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: sys/cpustats.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: sys/cpustats.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for sys/cpustats.h" >&5 +-echo $ECHO_N "checking for sys/cpustats.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for sys/cpustats.h" >&5 ++$as_echo_n "checking for sys/cpustats.h... " >&6; } + if test "${ac_cv_header_sys_cpustats_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_sys_cpustats_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_sys_cpustats_h" >&5 +-echo "${ECHO_T}$ac_cv_header_sys_cpustats_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_sys_cpustats_h" >&5 ++$as_echo "$ac_cv_header_sys_cpustats_h" >&6; } + + fi +-if test $ac_cv_header_sys_cpustats_h = yes; then ++if test "x$ac_cv_header_sys_cpustats_h" = x""yes; then + ac_have_func=yes; cat >>confdefs.h <<\_ACEOF + #define UMAX 1 + _ACEOF +@@ -18402,20 +18932,21 @@ + + for ac_header in mach/mach.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -18431,32 +18962,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -18470,69 +19002,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -18544,20 +19080,21 @@ + + for ac_header in nlist.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -18573,32 +19110,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -18612,74 +19150,78 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF +- { echo "$as_me:$LINENO: checking for struct nlist.n_un.n_name" >&5 +-echo $ECHO_N "checking for struct nlist.n_un.n_name... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for struct nlist.n_un.n_name" >&5 ++$as_echo_n "checking for struct nlist.n_un.n_name... " >&6; } + if test "${ac_cv_member_struct_nlist_n_un_n_name+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -18705,20 +19247,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_nlist_n_un_n_name=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -18745,20 +19288,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_struct_nlist_n_un_n_name=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_struct_nlist_n_un_n_name=no +@@ -18769,9 +19313,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_struct_nlist_n_un_n_name" >&5 +-echo "${ECHO_T}$ac_cv_member_struct_nlist_n_un_n_name" >&6; } +-if test $ac_cv_member_struct_nlist_n_un_n_name = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_struct_nlist_n_un_n_name" >&5 ++$as_echo "$ac_cv_member_struct_nlist_n_un_n_name" >&6; } ++if test "x$ac_cv_member_struct_nlist_n_un_n_name" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_STRUCT_NLIST_N_UN_N_NAME 1 +@@ -18794,10 +19338,10 @@ + + + # Some definitions of getloadavg require that the program be installed setgid. +-{ echo "$as_me:$LINENO: checking whether getloadavg requires setgid" >&5 +-echo $ECHO_N "checking whether getloadavg requires setgid... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether getloadavg requires setgid" >&5 ++$as_echo_n "checking whether getloadavg requires setgid... " >&6; } + if test "${ac_cv_func_getloadavg_setgid+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -18819,8 +19363,8 @@ + rm -f conftest* + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_getloadavg_setgid" >&5 +-echo "${ECHO_T}$ac_cv_func_getloadavg_setgid" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_getloadavg_setgid" >&5 ++$as_echo "$ac_cv_func_getloadavg_setgid" >&6; } + if test $ac_cv_func_getloadavg_setgid = yes; then + NEED_SETGID=true + +@@ -18833,38 +19377,38 @@ + fi + + if test $ac_cv_func_getloadavg_setgid = yes; then +- { echo "$as_me:$LINENO: checking group of /dev/kmem" >&5 +-echo $ECHO_N "checking group of /dev/kmem... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking group of /dev/kmem" >&5 ++$as_echo_n "checking group of /dev/kmem... " >&6; } + if test "${ac_cv_group_kmem+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + # On Solaris, /dev/kmem is a symlink. Get info on the real file. + ac_ls_output=`ls -lgL /dev/kmem 2>/dev/null` + # If we got an error (system does not support symlinks), try without -L. + test -z "$ac_ls_output" && ac_ls_output=`ls -lg /dev/kmem` +- ac_cv_group_kmem=`echo $ac_ls_output \ ++ ac_cv_group_kmem=`$as_echo "$ac_ls_output" \ + | sed -ne 's/[ ][ ]*/ /g; + s/^.[sSrwx-]* *[0-9]* *\([^0-9]*\) *.*/\1/; + / /s/.* //;p;'` + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_group_kmem" >&5 +-echo "${ECHO_T}$ac_cv_group_kmem" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_group_kmem" >&5 ++$as_echo "$ac_cv_group_kmem" >&6; } + KMEM_GROUP=$ac_cv_group_kmem + fi + if test "x$ac_save_LIBS" = x; then + GETLOADAVG_LIBS=$LIBS + else +- GETLOADAVG_LIBS=`echo "$LIBS" | sed "s!$ac_save_LIBS!!"` ++ GETLOADAVG_LIBS=`$as_echo "$LIBS" | sed "s|$ac_save_LIBS||"` + fi + LIBS=$ac_save_LIBS + + + +-{ echo "$as_me:$LINENO: checking for _LARGEFILE_SOURCE value needed for large files" >&5 +-echo $ECHO_N "checking for _LARGEFILE_SOURCE value needed for large files... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for _LARGEFILE_SOURCE value needed for large files" >&5 ++$as_echo_n "checking for _LARGEFILE_SOURCE value needed for large files... " >&6; } + if test "${ac_cv_sys_largefile_source+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + while :; do + cat >conftest.$ac_ext <<_ACEOF +@@ -18873,11 +19417,13 @@ + cat confdefs.h >>conftest.$ac_ext + cat >>conftest.$ac_ext <<_ACEOF + /* end confdefs.h. */ +-#include ++#include /* for off_t */ ++ #include + int + main () + { +-return fseeko (stdin, 0, 0) && (fseeko) (stdin, 0, 0); ++int (*fp) (FILE *, off_t, int) = fseeko; ++ return fseeko (stdin, 0, 0) && fp (stdin, 0, 0); + ; + return 0; + } +@@ -18888,26 +19434,30 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_sys_largefile_source=no; break + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + cat >conftest.$ac_ext <<_ACEOF +@@ -18917,11 +19467,13 @@ + cat >>conftest.$ac_ext <<_ACEOF + /* end confdefs.h. */ + #define _LARGEFILE_SOURCE 1 +-#include ++#include /* for off_t */ ++ #include + int + main () + { +-return fseeko (stdin, 0, 0) && (fseeko) (stdin, 0, 0); ++int (*fp) (FILE *, off_t, int) = fseeko; ++ return fseeko (stdin, 0, 0) && fp (stdin, 0, 0); + ; + return 0; + } +@@ -18932,34 +19484,38 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_sys_largefile_source=1; break + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + ac_cv_sys_largefile_source=unknown + break + done + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_sys_largefile_source" >&5 +-echo "${ECHO_T}$ac_cv_sys_largefile_source" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_sys_largefile_source" >&5 ++$as_echo "$ac_cv_sys_largefile_source" >&6; } + case $ac_cv_sys_largefile_source in #( + no | unknown) ;; + *) +@@ -18968,7 +19524,7 @@ + _ACEOF + ;; + esac +-rm -f conftest* ++rm -rf conftest* + + # We used to try defining _XOPEN_SOURCE=500 too, to work around a bug + # in glibc 2.1.3, but that breaks too many other things. +@@ -19008,20 +19564,21 @@ + + for ac_header in getopt.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -19037,32 +19594,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -19076,69 +19634,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + else +@@ -19151,11 +19713,11 @@ + + for ac_func in getopt_long_only + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -19208,35 +19770,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + else +@@ -19247,10 +19816,10 @@ + fi + + if test -z "$GETOPT_H"; then +- { echo "$as_me:$LINENO: checking whether optreset is declared" >&5 +-echo $ECHO_N "checking whether optreset is declared... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether optreset is declared" >&5 ++$as_echo_n "checking whether optreset is declared... " >&6; } + if test "${ac_cv_have_decl_optreset+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -19277,20 +19846,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_have_decl_optreset=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_have_decl_optreset=no +@@ -19298,25 +19868,25 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_have_decl_optreset" >&5 +-echo "${ECHO_T}$ac_cv_have_decl_optreset" >&6; } +-if test $ac_cv_have_decl_optreset = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_have_decl_optreset" >&5 ++$as_echo "$ac_cv_have_decl_optreset" >&6; } ++if test "x$ac_cv_have_decl_optreset" = x""yes; then + GETOPT_H=getopt.h + fi + + fi + + if test -z "$GETOPT_H"; then +- { echo "$as_me:$LINENO: checking for working GNU getopt function" >&5 +-echo $ECHO_N "checking for working GNU getopt function... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for working GNU getopt function" >&5 ++$as_echo_n "checking for working GNU getopt function... " >&6; } + if test "${gl_cv_func_gnu_getopt+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test "$cross_compiling" = yes; then +- { echo "$as_me:$LINENO: checking whether getopt_clip is declared" >&5 +-echo $ECHO_N "checking whether getopt_clip is declared... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether getopt_clip is declared" >&5 ++$as_echo_n "checking whether getopt_clip is declared... " >&6; } + if test "${ac_cv_have_decl_getopt_clip+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -19343,20 +19913,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_have_decl_getopt_clip=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_have_decl_getopt_clip=no +@@ -19364,9 +19935,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_have_decl_getopt_clip" >&5 +-echo "${ECHO_T}$ac_cv_have_decl_getopt_clip" >&6; } +-if test $ac_cv_have_decl_getopt_clip = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_have_decl_getopt_clip" >&5 ++$as_echo "$ac_cv_have_decl_getopt_clip" >&6; } ++if test "x$ac_cv_have_decl_getopt_clip" = x""yes; then + gl_cv_func_gnu_getopt=no + else + gl_cv_func_gnu_getopt=yes +@@ -19400,36 +19971,39 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + gl_cv_func_gnu_getopt=yes + else +- echo "$as_me: program exited with status $ac_status" >&5 +-echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: program exited with status $ac_status" >&5 ++$as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ( exit $ac_status ) + gl_cv_func_gnu_getopt=no + fi ++rm -rf conftest.dSYM + rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext + fi + + + fi +-{ echo "$as_me:$LINENO: result: $gl_cv_func_gnu_getopt" >&5 +-echo "${ECHO_T}$gl_cv_func_gnu_getopt" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $gl_cv_func_gnu_getopt" >&5 ++$as_echo "$gl_cv_func_gnu_getopt" >&6; } + if test "$gl_cv_func_gnu_getopt" = "no"; then + GETOPT_H=getopt.h + fi +@@ -19456,10 +20030,10 @@ + + + +-{ echo "$as_me:$LINENO: checking whether getpgrp requires zero arguments" >&5 +-echo $ECHO_N "checking whether getpgrp requires zero arguments... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether getpgrp requires zero arguments" >&5 ++$as_echo_n "checking whether getpgrp requires zero arguments... " >&6; } + if test "${ac_cv_func_getpgrp_void+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + # Use it with a single arg. + cat >conftest.$ac_ext <<_ACEOF +@@ -19483,20 +20057,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_func_getpgrp_void=no + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_func_getpgrp_void=yes +@@ -19505,8 +20080,8 @@ + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_getpgrp_void" >&5 +-echo "${ECHO_T}$ac_cv_func_getpgrp_void" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_getpgrp_void" >&5 ++$as_echo "$ac_cv_func_getpgrp_void" >&6; } + if test $ac_cv_func_getpgrp_void = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -19519,11 +20094,11 @@ + + for ac_func in strftime + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -19576,43 +20151,50 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + else + # strftime is in -lintl on SCO UNIX. +-{ echo "$as_me:$LINENO: checking for strftime in -lintl" >&5 +-echo $ECHO_N "checking for strftime in -lintl... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for strftime in -lintl" >&5 ++$as_echo_n "checking for strftime in -lintl... " >&6; } + if test "${ac_cv_lib_intl_strftime+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lintl $LIBS" +@@ -19644,33 +20226,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_intl_strftime=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_intl_strftime=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_intl_strftime" >&5 +-echo "${ECHO_T}$ac_cv_lib_intl_strftime" >&6; } +-if test $ac_cv_lib_intl_strftime = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_intl_strftime" >&5 ++$as_echo "$ac_cv_lib_intl_strftime" >&6; } ++if test "x$ac_cv_lib_intl_strftime" = x""yes; then + cat >>confdefs.h <<\_ACEOF + #define HAVE_STRFTIME 1 + _ACEOF +@@ -19686,11 +20272,11 @@ + + for ac_func in grantpt + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -19743,35 +20329,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -19782,11 +20375,11 @@ + + for ac_func in getpt + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -19839,35 +20432,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -19879,10 +20479,10 @@ + # It's better to believe a function is not available + # than to expect to find it in ncurses. + +-{ echo "$as_me:$LINENO: checking for tparm in -lncurses" >&5 +-echo $ECHO_N "checking for tparm in -lncurses... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for tparm in -lncurses" >&5 ++$as_echo_n "checking for tparm in -lncurses... " >&6; } + if test "${ac_cv_lib_ncurses_tparm+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lncurses $LIBS" +@@ -19914,33 +20514,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_ncurses_tparm=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_ncurses_tparm=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_ncurses_tparm" >&5 +-echo "${ECHO_T}$ac_cv_lib_ncurses_tparm" >&6; } +-if test $ac_cv_lib_ncurses_tparm = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_ncurses_tparm" >&5 ++$as_echo "$ac_cv_lib_ncurses_tparm" >&6; } ++if test "x$ac_cv_lib_ncurses_tparm" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBNCURSES 1 + _ACEOF +@@ -19976,33 +20580,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + have_res_init=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + have_res_init=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + if test "$have_res_init" = no; then + OLIBS="$LIBS" + LIBS="$LIBS -lresolv" +- { echo "$as_me:$LINENO: checking for res_init with -lresolv" >&5 +-echo $ECHO_N "checking for res_init with -lresolv... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for res_init with -lresolv" >&5 ++$as_echo_n "checking for res_init with -lresolv... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -20026,30 +20634,34 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + have_res_init=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + have_res_init=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext +- { echo "$as_me:$LINENO: result: $have_res_init" >&5 +-echo "${ECHO_T}$have_res_init" >&6; } ++ { $as_echo "$as_me:$LINENO: result: $have_res_init" >&5 ++$as_echo "$have_res_init" >&6; } + if test "$have_res_init" = yes ; then + resolv=yes + fi +@@ -20067,10 +20679,10 @@ + # Do we need the Hesiod library to provide the support routines? + if test "$with_hesiod" != no ; then + # Don't set $LIBS here -- see comments above. +- { echo "$as_me:$LINENO: checking for res_send" >&5 +-echo $ECHO_N "checking for res_send... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for res_send" >&5 ++$as_echo_n "checking for res_send... " >&6; } + if test "${ac_cv_func_res_send+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -20123,38 +20735,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_func_res_send=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_func_res_send=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_res_send" >&5 +-echo "${ECHO_T}$ac_cv_func_res_send" >&6; } +-if test $ac_cv_func_res_send = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_res_send" >&5 ++$as_echo "$ac_cv_func_res_send" >&6; } ++if test "x$ac_cv_func_res_send" = x""yes; then + : + else +- { echo "$as_me:$LINENO: checking for __res_send" >&5 +-echo $ECHO_N "checking for __res_send... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for __res_send" >&5 ++$as_echo_n "checking for __res_send... " >&6; } + if test "${ac_cv_func___res_send+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -20207,38 +20823,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_func___res_send=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_func___res_send=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func___res_send" >&5 +-echo "${ECHO_T}$ac_cv_func___res_send" >&6; } +-if test $ac_cv_func___res_send = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func___res_send" >&5 ++$as_echo "$ac_cv_func___res_send" >&6; } ++if test "x$ac_cv_func___res_send" = x""yes; then + : + else +- { echo "$as_me:$LINENO: checking for res_send in -lresolv" >&5 +-echo $ECHO_N "checking for res_send in -lresolv... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for res_send in -lresolv" >&5 ++$as_echo_n "checking for res_send in -lresolv... " >&6; } + if test "${ac_cv_lib_resolv_res_send+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lresolv $LIBS" +@@ -20270,39 +20890,43 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_resolv_res_send=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_resolv_res_send=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_resolv_res_send" >&5 +-echo "${ECHO_T}$ac_cv_lib_resolv_res_send" >&6; } +-if test $ac_cv_lib_resolv_res_send = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_resolv_res_send" >&5 ++$as_echo "$ac_cv_lib_resolv_res_send" >&6; } ++if test "x$ac_cv_lib_resolv_res_send" = x""yes; then + resolv=yes + else +- { echo "$as_me:$LINENO: checking for __res_send in -lresolv" >&5 +-echo $ECHO_N "checking for __res_send in -lresolv... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for __res_send in -lresolv" >&5 ++$as_echo_n "checking for __res_send in -lresolv... " >&6; } + if test "${ac_cv_lib_resolv___res_send+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lresolv $LIBS" +@@ -20334,33 +20958,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_resolv___res_send=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_resolv___res_send=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_resolv___res_send" >&5 +-echo "${ECHO_T}$ac_cv_lib_resolv___res_send" >&6; } +-if test $ac_cv_lib_resolv___res_send = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_resolv___res_send" >&5 ++$as_echo "$ac_cv_lib_resolv___res_send" >&6; } ++if test "x$ac_cv_lib_resolv___res_send" = x""yes; then + resolv=yes + fi + +@@ -20375,10 +21003,10 @@ + else + RESOLVLIB= + fi +- { echo "$as_me:$LINENO: checking for hes_getmailhost" >&5 +-echo $ECHO_N "checking for hes_getmailhost... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for hes_getmailhost" >&5 ++$as_echo_n "checking for hes_getmailhost... " >&6; } + if test "${ac_cv_func_hes_getmailhost+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -20431,38 +21059,42 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_func_hes_getmailhost=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_func_hes_getmailhost=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_hes_getmailhost" >&5 +-echo "${ECHO_T}$ac_cv_func_hes_getmailhost" >&6; } +-if test $ac_cv_func_hes_getmailhost = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_hes_getmailhost" >&5 ++$as_echo "$ac_cv_func_hes_getmailhost" >&6; } ++if test "x$ac_cv_func_hes_getmailhost" = x""yes; then + : + else +- { echo "$as_me:$LINENO: checking for hes_getmailhost in -lhesiod" >&5 +-echo $ECHO_N "checking for hes_getmailhost in -lhesiod... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for hes_getmailhost in -lhesiod" >&5 ++$as_echo_n "checking for hes_getmailhost in -lhesiod... " >&6; } + if test "${ac_cv_lib_hesiod_hes_getmailhost+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lhesiod $RESOLVLIB $LIBS" +@@ -20494,33 +21126,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_hesiod_hes_getmailhost=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_hesiod_hes_getmailhost=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_hesiod_hes_getmailhost" >&5 +-echo "${ECHO_T}$ac_cv_lib_hesiod_hes_getmailhost" >&6; } +-if test $ac_cv_lib_hesiod_hes_getmailhost = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_hesiod_hes_getmailhost" >&5 ++$as_echo "$ac_cv_lib_hesiod_hes_getmailhost" >&6; } ++if test "x$ac_cv_lib_hesiod_hes_getmailhost" = x""yes; then + + cat >>confdefs.h <<\_ACEOF + #define HAVE_LIBHESIOD 1 +@@ -20546,10 +21182,10 @@ + # These tell us which Kerberos-related libraries to use. + if test "${with_kerberos}" != no; then + +-{ echo "$as_me:$LINENO: checking for com_err in -lcom_err" >&5 +-echo $ECHO_N "checking for com_err in -lcom_err... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for com_err in -lcom_err" >&5 ++$as_echo_n "checking for com_err in -lcom_err... " >&6; } + if test "${ac_cv_lib_com_err_com_err+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lcom_err $LIBS" +@@ -20581,33 +21217,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_com_err_com_err=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_com_err_com_err=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_com_err_com_err" >&5 +-echo "${ECHO_T}$ac_cv_lib_com_err_com_err" >&6; } +-if test $ac_cv_lib_com_err_com_err = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_com_err_com_err" >&5 ++$as_echo "$ac_cv_lib_com_err_com_err" >&6; } ++if test "x$ac_cv_lib_com_err_com_err" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBCOM_ERR 1 + _ACEOF +@@ -20617,10 +21257,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking for mit_des_cbc_encrypt in -lk5crypto" >&5 +-echo $ECHO_N "checking for mit_des_cbc_encrypt in -lk5crypto... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for mit_des_cbc_encrypt in -lk5crypto" >&5 ++$as_echo_n "checking for mit_des_cbc_encrypt in -lk5crypto... " >&6; } + if test "${ac_cv_lib_k5crypto_mit_des_cbc_encrypt+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lk5crypto $LIBS" +@@ -20652,33 +21292,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_k5crypto_mit_des_cbc_encrypt=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_k5crypto_mit_des_cbc_encrypt=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_k5crypto_mit_des_cbc_encrypt" >&5 +-echo "${ECHO_T}$ac_cv_lib_k5crypto_mit_des_cbc_encrypt" >&6; } +-if test $ac_cv_lib_k5crypto_mit_des_cbc_encrypt = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_k5crypto_mit_des_cbc_encrypt" >&5 ++$as_echo "$ac_cv_lib_k5crypto_mit_des_cbc_encrypt" >&6; } ++if test "x$ac_cv_lib_k5crypto_mit_des_cbc_encrypt" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBK5CRYPTO 1 + _ACEOF +@@ -20688,10 +21332,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking for mit_des_cbc_encrypt in -lcrypto" >&5 +-echo $ECHO_N "checking for mit_des_cbc_encrypt in -lcrypto... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for mit_des_cbc_encrypt in -lcrypto" >&5 ++$as_echo_n "checking for mit_des_cbc_encrypt in -lcrypto... " >&6; } + if test "${ac_cv_lib_crypto_mit_des_cbc_encrypt+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lcrypto $LIBS" +@@ -20723,33 +21367,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_crypto_mit_des_cbc_encrypt=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_crypto_mit_des_cbc_encrypt=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_crypto_mit_des_cbc_encrypt" >&5 +-echo "${ECHO_T}$ac_cv_lib_crypto_mit_des_cbc_encrypt" >&6; } +-if test $ac_cv_lib_crypto_mit_des_cbc_encrypt = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_crypto_mit_des_cbc_encrypt" >&5 ++$as_echo "$ac_cv_lib_crypto_mit_des_cbc_encrypt" >&6; } ++if test "x$ac_cv_lib_crypto_mit_des_cbc_encrypt" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBCRYPTO 1 + _ACEOF +@@ -20759,10 +21407,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking for krb5_init_context in -lkrb5" >&5 +-echo $ECHO_N "checking for krb5_init_context in -lkrb5... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for krb5_init_context in -lkrb5" >&5 ++$as_echo_n "checking for krb5_init_context in -lkrb5... " >&6; } + if test "${ac_cv_lib_krb5_krb5_init_context+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lkrb5 $LIBS" +@@ -20794,33 +21442,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_krb5_krb5_init_context=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_krb5_krb5_init_context=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_krb5_krb5_init_context" >&5 +-echo "${ECHO_T}$ac_cv_lib_krb5_krb5_init_context" >&6; } +-if test $ac_cv_lib_krb5_krb5_init_context = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_krb5_krb5_init_context" >&5 ++$as_echo "$ac_cv_lib_krb5_krb5_init_context" >&6; } ++if test "x$ac_cv_lib_krb5_krb5_init_context" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBKRB5 1 + _ACEOF +@@ -20831,10 +21483,10 @@ + + if test "${with_kerberos5}" = no; then + +-{ echo "$as_me:$LINENO: checking for des_cbc_encrypt in -ldes425" >&5 +-echo $ECHO_N "checking for des_cbc_encrypt in -ldes425... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for des_cbc_encrypt in -ldes425" >&5 ++$as_echo_n "checking for des_cbc_encrypt in -ldes425... " >&6; } + if test "${ac_cv_lib_des425_des_cbc_encrypt+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-ldes425 $LIBS" +@@ -20866,33 +21518,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_des425_des_cbc_encrypt=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_des425_des_cbc_encrypt=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_des425_des_cbc_encrypt" >&5 +-echo "${ECHO_T}$ac_cv_lib_des425_des_cbc_encrypt" >&6; } +-if test $ac_cv_lib_des425_des_cbc_encrypt = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_des425_des_cbc_encrypt" >&5 ++$as_echo "$ac_cv_lib_des425_des_cbc_encrypt" >&6; } ++if test "x$ac_cv_lib_des425_des_cbc_encrypt" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBDES425 1 + _ACEOF +@@ -20901,10 +21557,10 @@ + + else + +-{ echo "$as_me:$LINENO: checking for des_cbc_encrypt in -ldes" >&5 +-echo $ECHO_N "checking for des_cbc_encrypt in -ldes... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for des_cbc_encrypt in -ldes" >&5 ++$as_echo_n "checking for des_cbc_encrypt in -ldes... " >&6; } + if test "${ac_cv_lib_des_des_cbc_encrypt+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-ldes $LIBS" +@@ -20936,33 +21592,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_des_des_cbc_encrypt=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_des_des_cbc_encrypt=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_des_des_cbc_encrypt" >&5 +-echo "${ECHO_T}$ac_cv_lib_des_des_cbc_encrypt" >&6; } +-if test $ac_cv_lib_des_des_cbc_encrypt = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_des_des_cbc_encrypt" >&5 ++$as_echo "$ac_cv_lib_des_des_cbc_encrypt" >&6; } ++if test "x$ac_cv_lib_des_des_cbc_encrypt" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBDES 1 + _ACEOF +@@ -20974,10 +21634,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking for krb_get_cred in -lkrb4" >&5 +-echo $ECHO_N "checking for krb_get_cred in -lkrb4... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for krb_get_cred in -lkrb4" >&5 ++$as_echo_n "checking for krb_get_cred in -lkrb4... " >&6; } + if test "${ac_cv_lib_krb4_krb_get_cred+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lkrb4 $LIBS" +@@ -21009,33 +21669,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_krb4_krb_get_cred=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_krb4_krb_get_cred=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_krb4_krb_get_cred" >&5 +-echo "${ECHO_T}$ac_cv_lib_krb4_krb_get_cred" >&6; } +-if test $ac_cv_lib_krb4_krb_get_cred = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_krb4_krb_get_cred" >&5 ++$as_echo "$ac_cv_lib_krb4_krb_get_cred" >&6; } ++if test "x$ac_cv_lib_krb4_krb_get_cred" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBKRB4 1 + _ACEOF +@@ -21044,10 +21708,10 @@ + + else + +-{ echo "$as_me:$LINENO: checking for krb_get_cred in -lkrb" >&5 +-echo $ECHO_N "checking for krb_get_cred in -lkrb... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for krb_get_cred in -lkrb" >&5 ++$as_echo_n "checking for krb_get_cred in -lkrb... " >&6; } + if test "${ac_cv_lib_krb_krb_get_cred+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lkrb $LIBS" +@@ -21079,33 +21743,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_krb_krb_get_cred=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_krb_krb_get_cred=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_krb_krb_get_cred" >&5 +-echo "${ECHO_T}$ac_cv_lib_krb_krb_get_cred" >&6; } +-if test $ac_cv_lib_krb_krb_get_cred = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_krb_krb_get_cred" >&5 ++$as_echo "$ac_cv_lib_krb_krb_get_cred" >&6; } ++if test "x$ac_cv_lib_krb_krb_get_cred" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBKRB 1 + _ACEOF +@@ -21122,20 +21790,21 @@ + + for ac_header in krb5.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21151,32 +21820,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21190,74 +21860,78 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF +- { echo "$as_me:$LINENO: checking for krb5_error.text" >&5 +-echo $ECHO_N "checking for krb5_error.text... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for krb5_error.text" >&5 ++$as_echo_n "checking for krb5_error.text... " >&6; } + if test "${ac_cv_member_krb5_error_text+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -21283,20 +21957,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_krb5_error_text=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -21323,20 +21998,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_krb5_error_text=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_krb5_error_text=no +@@ -21347,9 +22023,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_krb5_error_text" >&5 +-echo "${ECHO_T}$ac_cv_member_krb5_error_text" >&6; } +-if test $ac_cv_member_krb5_error_text = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_krb5_error_text" >&5 ++$as_echo "$ac_cv_member_krb5_error_text" >&6; } ++if test "x$ac_cv_member_krb5_error_text" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_KRB5_ERROR_TEXT 1 +@@ -21357,10 +22033,10 @@ + + + fi +-{ echo "$as_me:$LINENO: checking for krb5_error.e_text" >&5 +-echo $ECHO_N "checking for krb5_error.e_text... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for krb5_error.e_text" >&5 ++$as_echo_n "checking for krb5_error.e_text... " >&6; } + if test "${ac_cv_member_krb5_error_e_text+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -21386,20 +22062,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_krb5_error_e_text=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -21426,20 +22103,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_member_krb5_error_e_text=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_member_krb5_error_e_text=no +@@ -21450,9 +22128,9 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_member_krb5_error_e_text" >&5 +-echo "${ECHO_T}$ac_cv_member_krb5_error_e_text" >&6; } +-if test $ac_cv_member_krb5_error_e_text = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_member_krb5_error_e_text" >&5 ++$as_echo "$ac_cv_member_krb5_error_e_text" >&6; } ++if test "x$ac_cv_member_krb5_error_e_text" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_KRB5_ERROR_E_TEXT 1 +@@ -21469,20 +22147,21 @@ + + for ac_header in des.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21498,32 +22177,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21537,89 +22217,94 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + else + + for ac_header in kerberosIV/des.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21635,32 +22320,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21674,89 +22360,94 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + else + + for ac_header in kerberos/des.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21772,32 +22463,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21811,69 +22503,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -21891,20 +22587,21 @@ + + for ac_header in krb.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21920,32 +22617,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -21959,89 +22657,94 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + else + + for ac_header in kerberosIV/krb.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -22057,32 +22760,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -22096,89 +22800,94 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + else + + for ac_header in kerberos/krb.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -22194,32 +22903,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -22233,69 +22943,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -22314,20 +23028,21 @@ + + for ac_header in com_err.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -22343,32 +23058,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -22382,69 +23098,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -22456,10 +23176,10 @@ + # Solaris requires -lintl if you want strerror (which calls dgettext) + # to return localized messages. + +-{ echo "$as_me:$LINENO: checking for dgettext in -lintl" >&5 +-echo $ECHO_N "checking for dgettext in -lintl... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for dgettext in -lintl" >&5 ++$as_echo_n "checking for dgettext in -lintl... " >&6; } + if test "${ac_cv_lib_intl_dgettext+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_check_lib_save_LIBS=$LIBS + LIBS="-lintl $LIBS" +@@ -22491,33 +23211,37 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_lib_intl_dgettext=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_lib_intl_dgettext=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + LIBS=$ac_check_lib_save_LIBS + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_lib_intl_dgettext" >&5 +-echo "${ECHO_T}$ac_cv_lib_intl_dgettext" >&6; } +-if test $ac_cv_lib_intl_dgettext = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_lib_intl_dgettext" >&5 ++$as_echo "$ac_cv_lib_intl_dgettext" >&6; } ++if test "x$ac_cv_lib_intl_dgettext" = x""yes; then + cat >>confdefs.h <<_ACEOF + #define HAVE_LIBINTL 1 + _ACEOF +@@ -22527,10 +23251,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking whether localtime caches TZ" >&5 +-echo $ECHO_N "checking whether localtime caches TZ... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether localtime caches TZ" >&5 ++$as_echo_n "checking whether localtime caches TZ... " >&6; } + if test "${emacs_cv_localtime_cache+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test x$ac_cv_func_tzset = xyes; then + if test "$cross_compiling" = yes; then +@@ -22579,29 +23303,32 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + emacs_cv_localtime_cache=no + else +- echo "$as_me: program exited with status $ac_status" >&5 +-echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: program exited with status $ac_status" >&5 ++$as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ( exit $ac_status ) + emacs_cv_localtime_cache=yes + fi ++rm -rf conftest.dSYM + rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext + fi + +@@ -22612,8 +23339,8 @@ + emacs_cv_localtime_cache=no + fi + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_localtime_cache" >&5 +-echo "${ECHO_T}$emacs_cv_localtime_cache" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_localtime_cache" >&5 ++$as_echo "$emacs_cv_localtime_cache" >&6; } + if test $emacs_cv_localtime_cache = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -22626,11 +23353,11 @@ + + for ac_func in gettimeofday + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -22683,45 +23410,52 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi + done + + if test $ac_cv_func_gettimeofday = yes; then +- { echo "$as_me:$LINENO: checking whether gettimeofday can accept two arguments" >&5 +-echo $ECHO_N "checking whether gettimeofday can accept two arguments... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking whether gettimeofday can accept two arguments" >&5 ++$as_echo_n "checking whether gettimeofday can accept two arguments... " >&6; } + if test "${emacs_cv_gettimeofday_two_arguments+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -22755,20 +23489,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_gettimeofday_two_arguments=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_gettimeofday_two_arguments=no +@@ -22776,8 +23511,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_gettimeofday_two_arguments" >&5 +-echo "${ECHO_T}$emacs_cv_gettimeofday_two_arguments" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_gettimeofday_two_arguments" >&5 ++$as_echo "$emacs_cv_gettimeofday_two_arguments" >&6; } + if test $emacs_cv_gettimeofday_two_arguments = no; then + + cat >>confdefs.h <<\_ACEOF +@@ -22789,10 +23524,10 @@ + fi + + ok_so_far=yes +-{ echo "$as_me:$LINENO: checking for socket" >&5 +-echo $ECHO_N "checking for socket... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for socket" >&5 ++$as_echo_n "checking for socket... " >&6; } + if test "${ac_cv_func_socket+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -22845,32 +23580,36 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + ac_cv_func_socket=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_func_socket=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_socket" >&5 +-echo "${ECHO_T}$ac_cv_func_socket" >&6; } +-if test $ac_cv_func_socket = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_socket" >&5 ++$as_echo "$ac_cv_func_socket" >&6; } ++if test "x$ac_cv_func_socket" = x""yes; then + : + else + ok_so_far=no +@@ -22878,17 +23617,17 @@ + + if test $ok_so_far = yes; then + if test "${ac_cv_header_netinet_in_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for netinet/in.h" >&5 +-echo $ECHO_N "checking for netinet/in.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for netinet/in.h" >&5 ++$as_echo_n "checking for netinet/in.h... " >&6; } + if test "${ac_cv_header_netinet_in_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_netinet_in_h" >&5 +-echo "${ECHO_T}$ac_cv_header_netinet_in_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_netinet_in_h" >&5 ++$as_echo "$ac_cv_header_netinet_in_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking netinet/in.h usability" >&5 +-echo $ECHO_N "checking netinet/in.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking netinet/in.h usability" >&5 ++$as_echo_n "checking netinet/in.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -22904,32 +23643,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking netinet/in.h presence" >&5 +-echo $ECHO_N "checking netinet/in.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking netinet/in.h presence" >&5 ++$as_echo_n "checking netinet/in.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -22943,66 +23683,67 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: netinet/in.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: netinet/in.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: netinet/in.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: netinet/in.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: netinet/in.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: netinet/in.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: netinet/in.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: netinet/in.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: netinet/in.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: netinet/in.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: netinet/in.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: netinet/in.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: netinet/in.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: netinet/in.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: netinet/in.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: netinet/in.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: netinet/in.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: netinet/in.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: netinet/in.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: netinet/in.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: netinet/in.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: netinet/in.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: netinet/in.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: netinet/in.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: netinet/in.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: netinet/in.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: netinet/in.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: netinet/in.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: netinet/in.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: netinet/in.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: netinet/in.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: netinet/in.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for netinet/in.h" >&5 +-echo $ECHO_N "checking for netinet/in.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for netinet/in.h" >&5 ++$as_echo_n "checking for netinet/in.h... " >&6; } + if test "${ac_cv_header_netinet_in_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_netinet_in_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_netinet_in_h" >&5 +-echo "${ECHO_T}$ac_cv_header_netinet_in_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_netinet_in_h" >&5 ++$as_echo "$ac_cv_header_netinet_in_h" >&6; } + + fi +-if test $ac_cv_header_netinet_in_h = yes; then ++if test "x$ac_cv_header_netinet_in_h" = x""yes; then + : + else + ok_so_far=no +@@ -23012,17 +23753,17 @@ + fi + if test $ok_so_far = yes; then + if test "${ac_cv_header_arpa_inet_h+set}" = set; then +- { echo "$as_me:$LINENO: checking for arpa/inet.h" >&5 +-echo $ECHO_N "checking for arpa/inet.h... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for arpa/inet.h" >&5 ++$as_echo_n "checking for arpa/inet.h... " >&6; } + if test "${ac_cv_header_arpa_inet_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_arpa_inet_h" >&5 +-echo "${ECHO_T}$ac_cv_header_arpa_inet_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_arpa_inet_h" >&5 ++$as_echo "$ac_cv_header_arpa_inet_h" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking arpa/inet.h usability" >&5 +-echo $ECHO_N "checking arpa/inet.h usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking arpa/inet.h usability" >&5 ++$as_echo_n "checking arpa/inet.h usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -23038,32 +23779,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking arpa/inet.h presence" >&5 +-echo $ECHO_N "checking arpa/inet.h presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking arpa/inet.h presence" >&5 ++$as_echo_n "checking arpa/inet.h presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -23077,66 +23819,67 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: arpa/inet.h: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: arpa/inet.h: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: arpa/inet.h: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: arpa/inet.h: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: arpa/inet.h: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: arpa/inet.h: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: arpa/inet.h: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: arpa/inet.h: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: arpa/inet.h: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: arpa/inet.h: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: arpa/inet.h: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: arpa/inet.h: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: arpa/inet.h: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: arpa/inet.h: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: arpa/inet.h: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: arpa/inet.h: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: arpa/inet.h: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: arpa/inet.h: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: arpa/inet.h: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: arpa/inet.h: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: arpa/inet.h: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: arpa/inet.h: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: arpa/inet.h: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: arpa/inet.h: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: arpa/inet.h: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: arpa/inet.h: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: arpa/inet.h: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: arpa/inet.h: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: arpa/inet.h: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: arpa/inet.h: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: arpa/inet.h: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: arpa/inet.h: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for arpa/inet.h" >&5 +-echo $ECHO_N "checking for arpa/inet.h... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for arpa/inet.h" >&5 ++$as_echo_n "checking for arpa/inet.h... " >&6; } + if test "${ac_cv_header_arpa_inet_h+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + ac_cv_header_arpa_inet_h=$ac_header_preproc + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_header_arpa_inet_h" >&5 +-echo "${ECHO_T}$ac_cv_header_arpa_inet_h" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_header_arpa_inet_h" >&5 ++$as_echo "$ac_cv_header_arpa_inet_h" >&6; } + + fi +-if test $ac_cv_header_arpa_inet_h = yes; then ++if test "x$ac_cv_header_arpa_inet_h" = x""yes; then + : + else + ok_so_far=no +@@ -23155,20 +23898,21 @@ + + for ac_header in sys/ioctl.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -23184,32 +23928,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -23223,69 +23968,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -23301,41 +24050,73 @@ + + fi + +-{ echo "$as_me:$LINENO: checking whether system supports dynamic ptys" >&5 +-echo $ECHO_N "checking whether system supports dynamic ptys... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking whether system supports dynamic ptys" >&5 ++$as_echo_n "checking whether system supports dynamic ptys... " >&6; } + if test -d /dev/pts && ls -d /dev/ptmx > /dev/null 2>&1 ; then +- { echo "$as_me:$LINENO: result: yes" >&5 +-echo "${ECHO_T}yes" >&6; } ++ { $as_echo "$as_me:$LINENO: result: yes" >&5 ++$as_echo "yes" >&6; } + + cat >>confdefs.h <<\_ACEOF + #define HAVE_DEV_PTMX 1 + _ACEOF + + else +- { echo "$as_me:$LINENO: result: no" >&5 +-echo "${ECHO_T}no" >&6; } ++ { $as_echo "$as_me:$LINENO: result: no" >&5 ++$as_echo "no" >&6; } + fi + +-{ echo "$as_me:$LINENO: checking for pid_t" >&5 +-echo $ECHO_N "checking for pid_t... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for pid_t" >&5 ++$as_echo_n "checking for pid_t... " >&6; } + if test "${ac_cv_type_pid_t+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else +- cat >conftest.$ac_ext <<_ACEOF ++ ac_cv_type_pid_t=no ++cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF + cat confdefs.h >>conftest.$ac_ext + cat >>conftest.$ac_ext <<_ACEOF + /* end confdefs.h. */ + $ac_includes_default +-typedef pid_t ac__type_new_; + int + main () + { +-if ((ac__type_new_ *) 0) +- return 0; +-if (sizeof (ac__type_new_)) ++if (sizeof (pid_t)) ++ return 0; ++ ; + return 0; ++} ++_ACEOF ++rm -f conftest.$ac_objext ++if { (ac_try="$ac_compile" ++case "(($ac_try" in ++ *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; ++ *) ac_try_echo=$ac_try;; ++esac ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 ++ (eval "$ac_compile") 2>conftest.er1 ++ ac_status=$? ++ grep -v '^ *+' conftest.er1 >conftest.err ++ rm -f conftest.er1 ++ cat conftest.err >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ (exit $ac_status); } && { ++ test -z "$ac_c_werror_flag" || ++ test ! -s conftest.err ++ } && test -s conftest.$ac_objext; then ++ cat >conftest.$ac_ext <<_ACEOF ++/* confdefs.h. */ ++_ACEOF ++cat confdefs.h >>conftest.$ac_ext ++cat >>conftest.$ac_ext <<_ACEOF ++/* end confdefs.h. */ ++$ac_includes_default ++int ++main () ++{ ++if (sizeof ((pid_t))) ++ return 0; + ; + return 0; + } +@@ -23346,30 +24127,39 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then +- ac_cv_type_pid_t=yes ++ : ++else ++ $as_echo "$as_me: failed program was:" >&5 ++sed 's/^/| /' conftest.$ac_ext >&5 ++ ++ ac_cv_type_pid_t=yes ++fi ++ ++rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + +- ac_cv_type_pid_t=no ++ + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_type_pid_t" >&5 +-echo "${ECHO_T}$ac_cv_type_pid_t" >&6; } +-if test $ac_cv_type_pid_t = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_type_pid_t" >&5 ++$as_echo "$ac_cv_type_pid_t" >&6; } ++if test "x$ac_cv_type_pid_t" = x""yes; then + : + else + +@@ -23382,20 +24172,21 @@ + + for ac_header in vfork.h + do +-as_ac_Header=`echo "ac_cv_header_$ac_header" | $as_tr_sh` ++as_ac_Header=`$as_echo "ac_cv_header_$ac_header" | $as_tr_sh` + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- { echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + else + # Is the header compilable? +-{ echo "$as_me:$LINENO: checking $ac_header usability" >&5 +-echo $ECHO_N "checking $ac_header usability... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header usability" >&5 ++$as_echo_n "checking $ac_header usability... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -23411,32 +24202,33 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_header_compiler=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_compiler=no + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 +-echo "${ECHO_T}$ac_header_compiler" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_compiler" >&5 ++$as_echo "$ac_header_compiler" >&6; } + + # Is the header present? +-{ echo "$as_me:$LINENO: checking $ac_header presence" >&5 +-echo $ECHO_N "checking $ac_header presence... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking $ac_header presence" >&5 ++$as_echo_n "checking $ac_header presence... " >&6; } + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF +@@ -23450,69 +24242,73 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } >/dev/null && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + }; then + ac_header_preproc=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_header_preproc=no + fi + + rm -f conftest.err conftest.$ac_ext +-{ echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 +-echo "${ECHO_T}$ac_header_preproc" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_header_preproc" >&5 ++$as_echo "$ac_header_preproc" >&6; } + + # So? What about this header? + case $ac_header_compiler:$ac_header_preproc:$ac_c_preproc_warn_flag in + yes:no: ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 +-echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&5 ++$as_echo "$as_me: WARNING: $ac_header: accepted by the compiler, rejected by the preprocessor!" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the compiler's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the compiler's result" >&2;} + ac_header_preproc=yes + ;; + no:yes:* ) +- { echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 +-echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 +-echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 +-echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 +-echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 +-echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} +- { echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 +-echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: present but cannot be compiled" >&5 ++$as_echo "$as_me: WARNING: $ac_header: present but cannot be compiled" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: check for missing prerequisite headers?" >&5 ++$as_echo "$as_me: WARNING: $ac_header: check for missing prerequisite headers?" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: see the Autoconf documentation" >&5 ++$as_echo "$as_me: WARNING: $ac_header: see the Autoconf documentation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&5 ++$as_echo "$as_me: WARNING: $ac_header: section \"Present But Cannot Be Compiled\"" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: proceeding with the preprocessor's result" >&5 ++$as_echo "$as_me: WARNING: $ac_header: proceeding with the preprocessor's result" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_header: in the future, the compiler will take precedence" >&5 ++$as_echo "$as_me: WARNING: $ac_header: in the future, the compiler will take precedence" >&2;} + + ;; + esac +-{ echo "$as_me:$LINENO: checking for $ac_header" >&5 +-echo $ECHO_N "checking for $ac_header... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for $ac_header" >&5 ++$as_echo_n "checking for $ac_header... " >&6; } + if { as_var=$as_ac_Header; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + eval "$as_ac_Header=\$ac_header_preproc" + fi +-ac_res=`eval echo '${'$as_ac_Header'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } ++ac_res=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } + + fi +-if test `eval echo '${'$as_ac_Header'}'` = yes; then ++as_val=`eval 'as_val=${'$as_ac_Header'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_header" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_header" | $as_tr_cpp` 1 + _ACEOF + + fi +@@ -23523,11 +24319,11 @@ + + for ac_func in fork vfork + do +-as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh` +-{ echo "$as_me:$LINENO: checking for $ac_func" >&5 +-echo $ECHO_N "checking for $ac_func... $ECHO_C" >&6; } ++as_ac_var=`$as_echo "ac_cv_func_$ac_func" | $as_tr_sh` ++{ $as_echo "$as_me:$LINENO: checking for $ac_func" >&5 ++$as_echo_n "checking for $ac_func... " >&6; } + if { as_var=$as_ac_var; eval "test \"\${$as_var+set}\" = set"; }; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -23580,45 +24376,52 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + eval "$as_ac_var=yes" + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + eval "$as_ac_var=no" + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + fi +-ac_res=`eval echo '${'$as_ac_var'}'` +- { echo "$as_me:$LINENO: result: $ac_res" >&5 +-echo "${ECHO_T}$ac_res" >&6; } +-if test `eval echo '${'$as_ac_var'}'` = yes; then ++ac_res=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ { $as_echo "$as_me:$LINENO: result: $ac_res" >&5 ++$as_echo "$ac_res" >&6; } ++as_val=`eval 'as_val=${'$as_ac_var'} ++ $as_echo "$as_val"'` ++ if test "x$as_val" = x""yes; then + cat >>confdefs.h <<_ACEOF +-#define `echo "HAVE_$ac_func" | $as_tr_cpp` 1 ++#define `$as_echo "HAVE_$ac_func" | $as_tr_cpp` 1 + _ACEOF + + fi + done + + if test "x$ac_cv_func_fork" = xyes; then +- { echo "$as_me:$LINENO: checking for working fork" >&5 +-echo $ECHO_N "checking for working fork... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for working fork" >&5 ++$as_echo_n "checking for working fork... " >&6; } + if test "${ac_cv_func_fork_works+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test "$cross_compiling" = yes; then + ac_cv_func_fork_works=cross +@@ -23647,36 +24450,39 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + ac_cv_func_fork_works=yes + else +- echo "$as_me: program exited with status $ac_status" >&5 +-echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: program exited with status $ac_status" >&5 ++$as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ( exit $ac_status ) + ac_cv_func_fork_works=no + fi ++rm -rf conftest.dSYM + rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext + fi + + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_fork_works" >&5 +-echo "${ECHO_T}$ac_cv_func_fork_works" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_fork_works" >&5 ++$as_echo "$ac_cv_func_fork_works" >&6; } + + else + ac_cv_func_fork_works=$ac_cv_func_fork +@@ -23691,15 +24497,15 @@ + ac_cv_func_fork_works=yes + ;; + esac +- { echo "$as_me:$LINENO: WARNING: result $ac_cv_func_fork_works guessed because of cross compilation" >&5 +-echo "$as_me: WARNING: result $ac_cv_func_fork_works guessed because of cross compilation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: result $ac_cv_func_fork_works guessed because of cross compilation" >&5 ++$as_echo "$as_me: WARNING: result $ac_cv_func_fork_works guessed because of cross compilation" >&2;} + fi + ac_cv_func_vfork_works=$ac_cv_func_vfork + if test "x$ac_cv_func_vfork" = xyes; then +- { echo "$as_me:$LINENO: checking for working vfork" >&5 +-echo $ECHO_N "checking for working vfork... $ECHO_C" >&6; } ++ { $as_echo "$as_me:$LINENO: checking for working vfork" >&5 ++$as_echo_n "checking for working vfork... " >&6; } + if test "${ac_cv_func_vfork_works+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + if test "$cross_compiling" = yes; then + ac_cv_func_vfork_works=cross +@@ -23806,42 +24612,45 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { ac_try='./conftest$ac_exeext' + { (case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_try") 2>&5 + ac_status=$? +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); }; }; then + ac_cv_func_vfork_works=yes + else +- echo "$as_me: program exited with status $ac_status" >&5 +-echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: program exited with status $ac_status" >&5 ++$as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ( exit $ac_status ) + ac_cv_func_vfork_works=no + fi ++rm -rf conftest.dSYM + rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext + fi + + + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_func_vfork_works" >&5 +-echo "${ECHO_T}$ac_cv_func_vfork_works" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_func_vfork_works" >&5 ++$as_echo "$ac_cv_func_vfork_works" >&6; } + + fi; + if test "x$ac_cv_func_fork_works" = xcross; then + ac_cv_func_vfork_works=$ac_cv_func_vfork +- { echo "$as_me:$LINENO: WARNING: result $ac_cv_func_vfork_works guessed because of cross compilation" >&5 +-echo "$as_me: WARNING: result $ac_cv_func_vfork_works guessed because of cross compilation" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: result $ac_cv_func_vfork_works guessed because of cross compilation" >&5 ++$as_echo "$as_me: WARNING: result $ac_cv_func_vfork_works guessed because of cross compilation" >&2;} + fi + + if test "x$ac_cv_func_vfork_works" = xyes; then +@@ -23866,10 +24675,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking for nl_langinfo and CODESET" >&5 +-echo $ECHO_N "checking for nl_langinfo and CODESET... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for nl_langinfo and CODESET" >&5 ++$as_echo_n "checking for nl_langinfo and CODESET... " >&6; } + if test "${emacs_cv_langinfo_codeset+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -23892,32 +24701,36 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err +- } && test -s conftest$ac_exeext && +- $as_test_x conftest$ac_exeext; then ++ } && test -s conftest$ac_exeext && { ++ test "$cross_compiling" = yes || ++ $as_test_x conftest$ac_exeext ++ }; then + emacs_cv_langinfo_codeset=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_langinfo_codeset=no + fi + ++rm -rf conftest.dSYM + rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext + + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_langinfo_codeset" >&5 +-echo "${ECHO_T}$emacs_cv_langinfo_codeset" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_langinfo_codeset" >&5 ++$as_echo "$emacs_cv_langinfo_codeset" >&6; } + if test $emacs_cv_langinfo_codeset = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -23926,26 +24739,58 @@ + + fi + +-{ echo "$as_me:$LINENO: checking for size_t" >&5 +-echo $ECHO_N "checking for size_t... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for size_t" >&5 ++$as_echo_n "checking for size_t... " >&6; } + if test "${ac_cv_type_size_t+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else +- cat >conftest.$ac_ext <<_ACEOF ++ ac_cv_type_size_t=no ++cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ + _ACEOF + cat confdefs.h >>conftest.$ac_ext + cat >>conftest.$ac_ext <<_ACEOF + /* end confdefs.h. */ + $ac_includes_default +-typedef size_t ac__type_new_; + int + main () + { +-if ((ac__type_new_ *) 0) +- return 0; +-if (sizeof (ac__type_new_)) ++if (sizeof (size_t)) ++ return 0; ++ ; + return 0; ++} ++_ACEOF ++rm -f conftest.$ac_objext ++if { (ac_try="$ac_compile" ++case "(($ac_try" in ++ *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; ++ *) ac_try_echo=$ac_try;; ++esac ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 ++ (eval "$ac_compile") 2>conftest.er1 ++ ac_status=$? ++ grep -v '^ *+' conftest.er1 >conftest.err ++ rm -f conftest.er1 ++ cat conftest.err >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ (exit $ac_status); } && { ++ test -z "$ac_c_werror_flag" || ++ test ! -s conftest.err ++ } && test -s conftest.$ac_objext; then ++ cat >conftest.$ac_ext <<_ACEOF ++/* confdefs.h. */ ++_ACEOF ++cat confdefs.h >>conftest.$ac_ext ++cat >>conftest.$ac_ext <<_ACEOF ++/* end confdefs.h. */ ++$ac_includes_default ++int ++main () ++{ ++if (sizeof ((size_t))) ++ return 0; + ; + return 0; + } +@@ -23956,30 +24801,39 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then +- ac_cv_type_size_t=yes ++ : ++else ++ $as_echo "$as_me: failed program was:" >&5 ++sed 's/^/| /' conftest.$ac_ext >&5 ++ ++ ac_cv_type_size_t=yes ++fi ++ ++rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + +- ac_cv_type_size_t=no ++ + fi + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_type_size_t" >&5 +-echo "${ECHO_T}$ac_cv_type_size_t" >&6; } +-if test $ac_cv_type_size_t = yes; then ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_type_size_t" >&5 ++$as_echo "$ac_cv_type_size_t" >&6; } ++if test "x$ac_cv_type_size_t" = x""yes; then + + cat >>confdefs.h <<_ACEOF + #define HAVE_SIZE_T 1 +@@ -23989,10 +24843,10 @@ + fi + + +-{ echo "$as_me:$LINENO: checking for mbstate_t" >&5 +-echo $ECHO_N "checking for mbstate_t... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for mbstate_t" >&5 ++$as_echo_n "checking for mbstate_t... " >&6; } + if test "${ac_cv_type_mbstate_t+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -24016,20 +24870,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + ac_cv_type_mbstate_t=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + ac_cv_type_mbstate_t=no +@@ -24037,8 +24892,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $ac_cv_type_mbstate_t" >&5 +-echo "${ECHO_T}$ac_cv_type_mbstate_t" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $ac_cv_type_mbstate_t" >&5 ++$as_echo "$ac_cv_type_mbstate_t" >&6; } + if test $ac_cv_type_mbstate_t = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -24053,10 +24908,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking for C restrict keyword" >&5 +-echo $ECHO_N "checking for C restrict keyword... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for C restrict keyword" >&5 ++$as_echo_n "checking for C restrict keyword... " >&6; } + if test "${emacs_cv_c_restrict+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -24079,20 +24934,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_c_restrict=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + cat >conftest.$ac_ext <<_ACEOF +@@ -24116,20 +24972,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_c_restrict=__restrict + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_c_restrict=no +@@ -24140,8 +24997,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_c_restrict" >&5 +-echo "${ECHO_T}$emacs_cv_c_restrict" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_c_restrict" >&5 ++$as_echo "$emacs_cv_c_restrict" >&6; } + case "$emacs_cv_c_restrict" in + yes) emacs_restrict=restrict;; + no) emacs_restrict="";; +@@ -24155,10 +25012,10 @@ + + fi + +-{ echo "$as_me:$LINENO: checking for C restricted array declarations" >&5 +-echo $ECHO_N "checking for C restricted array declarations... $ECHO_C" >&6; } ++{ $as_echo "$as_me:$LINENO: checking for C restricted array declarations" >&5 ++$as_echo_n "checking for C restricted array declarations... " >&6; } + if test "${emacs_cv_c_restrict_arr+set}" = set; then +- echo $ECHO_N "(cached) $ECHO_C" >&6 ++ $as_echo_n "(cached) " >&6 + else + cat >conftest.$ac_ext <<_ACEOF + /* confdefs.h. */ +@@ -24181,20 +25038,21 @@ + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; + esac +-eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 ++eval ac_try_echo="\"\$as_me:$LINENO: $ac_try_echo\"" ++$as_echo "$ac_try_echo") >&5 + (eval "$ac_compile") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 +- echo "$as_me:$LINENO: \$? = $ac_status" >&5 ++ $as_echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext; then + emacs_cv_c_restrict_arr=yes + else +- echo "$as_me: failed program was:" >&5 ++ $as_echo "$as_me: failed program was:" >&5 + sed 's/^/| /' conftest.$ac_ext >&5 + + emacs_cv_c_restrict_arr=no +@@ -24202,8 +25060,8 @@ + + rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext + fi +-{ echo "$as_me:$LINENO: result: $emacs_cv_c_restrict_arr" >&5 +-echo "${ECHO_T}$emacs_cv_c_restrict_arr" >&6; } ++{ $as_echo "$as_me:$LINENO: result: $emacs_cv_c_restrict_arr" >&5 ++$as_echo "$emacs_cv_c_restrict_arr" >&6; } + if test "$emacs_cv_c_restrict_arr" = yes; then + + cat >>confdefs.h <<\_ACEOF +@@ -24222,8 +25080,8 @@ + version=`grep 'defconst[ ]*emacs-version' ${srcdir}/lisp/version.el \ + | sed -e 's/^[^"]*"\([^"]*\)".*$/\1/'` + if test x"${version}" = x; then +- { { echo "$as_me:$LINENO: error: can't find current emacs version in \`${srcdir}/lisp/version.el'." >&5 +-echo "$as_me: error: can't find current emacs version in \`${srcdir}/lisp/version.el'." >&2;} ++ { { $as_echo "$as_me:$LINENO: error: can't find current emacs version in \`${srcdir}/lisp/version.el'." >&5 ++$as_echo "$as_me: error: can't find current emacs version in \`${srcdir}/lisp/version.el'." >&2;} + { (exit 1); exit 1; }; } + fi + +@@ -24530,11 +25388,12 @@ + case $ac_val in #( + *${as_nl}*) + case $ac_var in #( +- *_cv_*) { echo "$as_me:$LINENO: WARNING: Cache variable $ac_var contains a newline." >&5 +-echo "$as_me: WARNING: Cache variable $ac_var contains a newline." >&2;} ;; ++ *_cv_*) { $as_echo "$as_me:$LINENO: WARNING: cache variable $ac_var contains a newline" >&5 ++$as_echo "$as_me: WARNING: cache variable $ac_var contains a newline" >&2;} ;; + esac + case $ac_var in #( + _ | IFS | as_nl) ;; #( ++ BASH_ARGV | BASH_SOURCE) eval $ac_var= ;; #( + *) $as_unset $ac_var ;; + esac ;; + esac +@@ -24567,12 +25426,12 @@ + if diff "$cache_file" confcache >/dev/null 2>&1; then :; else + if test -w "$cache_file"; then + test "x$cache_file" != "x/dev/null" && +- { echo "$as_me:$LINENO: updating cache $cache_file" >&5 +-echo "$as_me: updating cache $cache_file" >&6;} ++ { $as_echo "$as_me:$LINENO: updating cache $cache_file" >&5 ++$as_echo "$as_me: updating cache $cache_file" >&6;} + cat confcache >$cache_file + else +- { echo "$as_me:$LINENO: not updating unwritable cache $cache_file" >&5 +-echo "$as_me: not updating unwritable cache $cache_file" >&6;} ++ { $as_echo "$as_me:$LINENO: not updating unwritable cache $cache_file" >&5 ++$as_echo "$as_me: not updating unwritable cache $cache_file" >&6;} + fi + fi + rm -f confcache +@@ -24588,7 +25447,7 @@ + for ac_i in : $LIBOBJS; do test "x$ac_i" = x: && continue + # 1. Remove the extension, and $U if already installed. + ac_script='s/\$U\././;s/\.o$//;s/\.obj$//' +- ac_i=`echo "$ac_i" | sed "$ac_script"` ++ ac_i=`$as_echo "$ac_i" | sed "$ac_script"` + # 2. Prepend LIBOBJDIR. When used with automake>=1.10 LIBOBJDIR + # will be set to the directory where LIBOBJS objects are built. + ac_libobjs="$ac_libobjs \${LIBOBJDIR}$ac_i\$U.$ac_objext" +@@ -24601,11 +25460,12 @@ + + + : ${CONFIG_STATUS=./config.status} ++ac_write_fail=0 + ac_clean_files_save=$ac_clean_files + ac_clean_files="$ac_clean_files $CONFIG_STATUS" +-{ echo "$as_me:$LINENO: creating $CONFIG_STATUS" >&5 +-echo "$as_me: creating $CONFIG_STATUS" >&6;} +-cat >$CONFIG_STATUS <<_ACEOF ++{ $as_echo "$as_me:$LINENO: creating $CONFIG_STATUS" >&5 ++$as_echo "$as_me: creating $CONFIG_STATUS" >&6;} ++cat >$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 + #! $SHELL + # Generated by $as_me. + # Run this file to recreate the current configuration. +@@ -24618,7 +25478,7 @@ + SHELL=\${CONFIG_SHELL-$SHELL} + _ACEOF + +-cat >>$CONFIG_STATUS <<\_ACEOF ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 + ## --------------------- ## + ## M4sh Initialization. ## + ## --------------------- ## +@@ -24628,7 +25488,7 @@ + if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then + emulate sh + NULLCMD=: +- # Zsh 3.x and 4.x performs word splitting on ${1+"$@"}, which ++ # Pre-4.2 versions of Zsh do word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +@@ -24650,17 +25510,45 @@ + as_cr_digits='0123456789' + as_cr_alnum=$as_cr_Letters$as_cr_digits + +-# The user is always right. +-if test "${PATH_SEPARATOR+set}" != set; then +- echo "#! /bin/sh" >conf$$.sh +- echo "exit 0" >>conf$$.sh +- chmod +x conf$$.sh +- if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then +- PATH_SEPARATOR=';' ++as_nl=' ++' ++export as_nl ++# Printing a long string crashes Solaris 7 /usr/bin/printf. ++as_echo='\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\' ++as_echo=$as_echo$as_echo$as_echo$as_echo$as_echo ++as_echo=$as_echo$as_echo$as_echo$as_echo$as_echo$as_echo ++if (test "X`printf %s $as_echo`" = "X$as_echo") 2>/dev/null; then ++ as_echo='printf %s\n' ++ as_echo_n='printf %s' ++else ++ if test "X`(/usr/ucb/echo -n -n $as_echo) 2>/dev/null`" = "X-n $as_echo"; then ++ as_echo_body='eval /usr/ucb/echo -n "$1$as_nl"' ++ as_echo_n='/usr/ucb/echo -n' + else +- PATH_SEPARATOR=: ++ as_echo_body='eval expr "X$1" : "X\\(.*\\)"' ++ as_echo_n_body='eval ++ arg=$1; ++ case $arg in ++ *"$as_nl"*) ++ expr "X$arg" : "X\\(.*\\)$as_nl"; ++ arg=`expr "X$arg" : ".*$as_nl\\(.*\\)"`;; ++ esac; ++ expr "X$arg" : "X\\(.*\\)" | tr -d "$as_nl" ++ ' ++ export as_echo_n_body ++ as_echo_n='sh -c $as_echo_n_body as_echo' + fi +- rm -f conf$$.sh ++ export as_echo_body ++ as_echo='sh -c $as_echo_body as_echo' ++fi ++ ++# The user is always right. ++if test "${PATH_SEPARATOR+set}" != set; then ++ PATH_SEPARATOR=: ++ (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 && { ++ (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 || ++ PATH_SEPARATOR=';' ++ } + fi + + # Support unset when possible. +@@ -24676,8 +25564,6 @@ + # there to prevent editors from complaining about space-tab. + # (If _AS_PATH_WALK were called with IFS unset, it would disable word + # splitting by setting IFS to empty value.) +-as_nl=' +-' + IFS=" "" $as_nl" + + # Find who we are. Look in the path if we contain no directory separator. +@@ -24700,7 +25586,7 @@ + as_myself=$0 + fi + if test ! -f "$as_myself"; then +- echo "$as_myself: error: cannot find myself; rerun with an absolute file name" >&2 ++ $as_echo "$as_myself: error: cannot find myself; rerun with an absolute file name" >&2 + { (exit 1); exit 1; } + fi + +@@ -24713,17 +25599,10 @@ + PS4='+ ' + + # NLS nuisances. +-for as_var in \ +- LANG LANGUAGE LC_ADDRESS LC_ALL LC_COLLATE LC_CTYPE LC_IDENTIFICATION \ +- LC_MEASUREMENT LC_MESSAGES LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER \ +- LC_TELEPHONE LC_TIME +-do +- if (set +x; test -z "`(eval $as_var=C; export $as_var) 2>&1`"); then +- eval $as_var=C; export $as_var +- else +- ($as_unset $as_var) >/dev/null 2>&1 && $as_unset $as_var +- fi +-done ++LC_ALL=C ++export LC_ALL ++LANGUAGE=C ++export LANGUAGE + + # Required to use basename. + if expr a : '\(a\)' >/dev/null 2>&1 && +@@ -24745,7 +25624,7 @@ + $as_expr X/"$0" : '.*/\([^/][^/]*\)/*$' \| \ + X"$0" : 'X\(//\)$' \| \ + X"$0" : 'X\(/\)' \| . 2>/dev/null || +-echo X/"$0" | ++$as_echo X/"$0" | + sed '/^.*\/\([^/][^/]*\)\/*$/{ + s//\1/ + q +@@ -24796,7 +25675,7 @@ + s/-\n.*// + ' >$as_me.lineno && + chmod +x "$as_me.lineno" || +- { echo "$as_me: error: cannot create $as_me.lineno; rerun with a POSIX shell" >&2 ++ { $as_echo "$as_me: error: cannot create $as_me.lineno; rerun with a POSIX shell" >&2 + { (exit 1); exit 1; }; } + + # Don't try to exec as it changes $[0], causing all sort of problems +@@ -24824,7 +25703,6 @@ + *) + ECHO_N='-n';; + esac +- + if expr a : '\(a\)' >/dev/null 2>&1 && + test "X`expr 00001 : '.*\(...\)'`" = X001; then + as_expr=expr +@@ -24837,19 +25715,22 @@ + rm -f conf$$.dir/conf$$.file + else + rm -f conf$$.dir +- mkdir conf$$.dir ++ mkdir conf$$.dir 2>/dev/null + fi +-echo >conf$$.file +-if ln -s conf$$.file conf$$ 2>/dev/null; then +- as_ln_s='ln -s' +- # ... but there are two gotchas: +- # 1) On MSYS, both `ln -s file dir' and `ln file dir' fail. +- # 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable. +- # In both cases, we have to default to `cp -p'. +- ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe || ++if (echo >conf$$.file) 2>/dev/null; then ++ if ln -s conf$$.file conf$$ 2>/dev/null; then ++ as_ln_s='ln -s' ++ # ... but there are two gotchas: ++ # 1) On MSYS, both `ln -s file dir' and `ln file dir' fail. ++ # 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable. ++ # In both cases, we have to default to `cp -p'. ++ ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe || ++ as_ln_s='cp -p' ++ elif ln conf$$.file conf$$ 2>/dev/null; then ++ as_ln_s=ln ++ else + as_ln_s='cp -p' +-elif ln conf$$.file conf$$ 2>/dev/null; then +- as_ln_s=ln ++ fi + else + as_ln_s='cp -p' + fi +@@ -24874,10 +25755,10 @@ + as_test_x=' + eval sh -c '\'' + if test -d "$1"; then +- test -d "$1/."; ++ test -d "$1/."; + else + case $1 in +- -*)set "./$1";; ++ -*)set "./$1";; + esac; + case `ls -ld'$as_ls_L_option' "$1" 2>/dev/null` in + ???[sx]*):;;*)false;;esac;fi +@@ -24900,7 +25781,7 @@ + # values after options handling. + ac_log=" + This file was extended by emacs $as_me 23.1, which was +-generated by GNU Autoconf 2.61. Invocation command line was ++generated by GNU Autoconf 2.63. Invocation command line was + + CONFIG_FILES = $CONFIG_FILES + CONFIG_HEADERS = $CONFIG_HEADERS +@@ -24913,7 +25794,16 @@ + + _ACEOF + +-cat >>$CONFIG_STATUS <<_ACEOF ++case $ac_config_files in *" ++"*) set x $ac_config_files; shift; ac_config_files=$*;; ++esac ++ ++case $ac_config_headers in *" ++"*) set x $ac_config_headers; shift; ac_config_headers=$*;; ++esac ++ ++ ++cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 + # Files that config.status was made for. + config_files="$ac_config_files" + config_headers="$ac_config_headers" +@@ -24921,22 +25811,23 @@ + + _ACEOF + +-cat >>$CONFIG_STATUS <<\_ACEOF ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 + ac_cs_usage="\ + \`$as_me' instantiates files from templates according to the + current configuration. + +-Usage: $0 [OPTIONS] [FILE]... ++Usage: $0 [OPTION]... [FILE]... + + -h, --help print this help, then exit + -V, --version print version number and configuration settings, then exit +- -q, --quiet do not print progress messages ++ -q, --quiet, --silent ++ do not print progress messages + -d, --debug don't remove temporary files + --recheck update $as_me by reconfiguring in the same conditions +- --file=FILE[:TEMPLATE] +- instantiate the configuration file FILE +- --header=FILE[:TEMPLATE] +- instantiate the configuration header FILE ++ --file=FILE[:TEMPLATE] ++ instantiate the configuration file FILE ++ --header=FILE[:TEMPLATE] ++ instantiate the configuration header FILE + + Configuration files: + $config_files +@@ -24950,24 +25841,24 @@ + Report bugs to ." + + _ACEOF +-cat >>$CONFIG_STATUS <<_ACEOF ++cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 + ac_cs_version="\\ + emacs config.status 23.1 +-configured by $0, generated by GNU Autoconf 2.61, +- with options \\"`echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`\\" ++configured by $0, generated by GNU Autoconf 2.63, ++ with options \\"`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`\\" + +-Copyright (C) 2006 Free Software Foundation, Inc. ++Copyright (C) 2008 Free Software Foundation, Inc. + This config.status script is free software; the Free Software Foundation + gives unlimited permission to copy, distribute and modify it." + + ac_pwd='$ac_pwd' + srcdir='$srcdir' + INSTALL='$INSTALL' ++test -n "\$AWK" || AWK=awk + _ACEOF + +-cat >>$CONFIG_STATUS <<\_ACEOF +-# If no file are specified by the user, then we need to provide default +-# value. By we need to know if files were specified by the user. ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 ++# The default lists apply if the user does not specify any file. + ac_need_defaults=: + while test $# != 0 + do +@@ -24989,30 +25880,36 @@ + -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) + ac_cs_recheck=: ;; + --version | --versio | --versi | --vers | --ver | --ve | --v | -V ) +- echo "$ac_cs_version"; exit ;; ++ $as_echo "$ac_cs_version"; exit ;; + --debug | --debu | --deb | --de | --d | -d ) + debug=: ;; + --file | --fil | --fi | --f ) + $ac_shift +- CONFIG_FILES="$CONFIG_FILES $ac_optarg" ++ case $ac_optarg in ++ *\'*) ac_optarg=`$as_echo "$ac_optarg" | sed "s/'/'\\\\\\\\''/g"` ;; ++ esac ++ CONFIG_FILES="$CONFIG_FILES '$ac_optarg'" + ac_need_defaults=false;; + --header | --heade | --head | --hea ) + $ac_shift +- CONFIG_HEADERS="$CONFIG_HEADERS $ac_optarg" ++ case $ac_optarg in ++ *\'*) ac_optarg=`$as_echo "$ac_optarg" | sed "s/'/'\\\\\\\\''/g"` ;; ++ esac ++ CONFIG_HEADERS="$CONFIG_HEADERS '$ac_optarg'" + ac_need_defaults=false;; + --he | --h) + # Conflict between --help and --header +- { echo "$as_me: error: ambiguous option: $1 ++ { $as_echo "$as_me: error: ambiguous option: $1 + Try \`$0 --help' for more information." >&2 + { (exit 1); exit 1; }; };; + --help | --hel | -h ) +- echo "$ac_cs_usage"; exit ;; ++ $as_echo "$ac_cs_usage"; exit ;; + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil | --si | --s) + ac_cs_silent=: ;; + + # This is an error. +- -*) { echo "$as_me: error: unrecognized option: $1 ++ -*) { $as_echo "$as_me: error: unrecognized option: $1 + Try \`$0 --help' for more information." >&2 + { (exit 1); exit 1; }; } ;; + +@@ -25031,27 +25928,29 @@ + fi + + _ACEOF +-cat >>$CONFIG_STATUS <<_ACEOF ++cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 + if \$ac_cs_recheck; then +- echo "running CONFIG_SHELL=$SHELL $SHELL $0 "$ac_configure_args \$ac_configure_extra_args " --no-create --no-recursion" >&6 +- CONFIG_SHELL=$SHELL ++ set X '$SHELL' '$0' $ac_configure_args \$ac_configure_extra_args --no-create --no-recursion ++ shift ++ \$as_echo "running CONFIG_SHELL=$SHELL \$*" >&6 ++ CONFIG_SHELL='$SHELL' + export CONFIG_SHELL +- exec $SHELL "$0"$ac_configure_args \$ac_configure_extra_args --no-create --no-recursion ++ exec "\$@" + fi + + _ACEOF +-cat >>$CONFIG_STATUS <<\_ACEOF ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 + exec 5>>config.log + { + echo + sed 'h;s/./-/g;s/^.../## /;s/...$/ ##/;p;x;p;x' <<_ASBOX + ## Running $as_me. ## + _ASBOX +- echo "$ac_log" ++ $as_echo "$ac_log" + } >&5 + + _ACEOF +-cat >>$CONFIG_STATUS <<_ACEOF ++cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 + # + # INIT-COMMANDS + # +@@ -25059,7 +25958,7 @@ + + _ACEOF + +-cat >>$CONFIG_STATUS <<\_ACEOF ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 + + # Handling of arguments. + for ac_config_target in $ac_config_targets +@@ -25079,8 +25978,8 @@ + "leim/Makefile") CONFIG_FILES="$CONFIG_FILES leim/Makefile" ;; + "default") CONFIG_COMMANDS="$CONFIG_COMMANDS default" ;; + +- *) { { echo "$as_me:$LINENO: error: invalid argument: $ac_config_target" >&5 +-echo "$as_me: error: invalid argument: $ac_config_target" >&2;} ++ *) { { $as_echo "$as_me:$LINENO: error: invalid argument: $ac_config_target" >&5 ++$as_echo "$as_me: error: invalid argument: $ac_config_target" >&2;} + { (exit 1); exit 1; }; };; + esac + done +@@ -25121,233 +26020,144 @@ + (umask 077 && mkdir "$tmp") + } || + { +- echo "$me: cannot create a temporary directory in ." >&2 ++ $as_echo "$as_me: cannot create a temporary directory in ." >&2 + { (exit 1); exit 1; } + } + +-# +-# Set up the sed scripts for CONFIG_FILES section. +-# +- +-# No need to generate the scripts if there are no CONFIG_FILES. +-# This happens for instance when ./config.status config.h ++# Set up the scripts for CONFIG_FILES section. ++# No need to generate them if there are no CONFIG_FILES. ++# This happens for instance with `./config.status config.h'. + if test -n "$CONFIG_FILES"; then + +-_ACEOF + ++ac_cr=' ' ++ac_cs_awk_cr=`$AWK 'BEGIN { print "a\rb" }' /dev/null` ++if test "$ac_cs_awk_cr" = "a${ac_cr}b"; then ++ ac_cs_awk_cr='\\r' ++else ++ ac_cs_awk_cr=$ac_cr ++fi ++ ++echo 'BEGIN {' >"$tmp/subs1.awk" && ++_ACEOF + + ++{ ++ echo "cat >conf$$subs.awk <<_ACEOF" && ++ echo "$ac_subst_vars" | sed 's/.*/&!$&$ac_delim/' && ++ echo "_ACEOF" ++} >conf$$subs.sh || ++ { { $as_echo "$as_me:$LINENO: error: could not make $CONFIG_STATUS" >&5 ++$as_echo "$as_me: error: could not make $CONFIG_STATUS" >&2;} ++ { (exit 1); exit 1; }; } ++ac_delim_num=`echo "$ac_subst_vars" | grep -c '$'` + ac_delim='%!_!# ' + for ac_last_try in false false false false false :; do +- cat >conf$$subs.sed <<_ACEOF +-SHELL!$SHELL$ac_delim +-PATH_SEPARATOR!$PATH_SEPARATOR$ac_delim +-PACKAGE_NAME!$PACKAGE_NAME$ac_delim +-PACKAGE_TARNAME!$PACKAGE_TARNAME$ac_delim +-PACKAGE_VERSION!$PACKAGE_VERSION$ac_delim +-PACKAGE_STRING!$PACKAGE_STRING$ac_delim +-PACKAGE_BUGREPORT!$PACKAGE_BUGREPORT$ac_delim +-exec_prefix!$exec_prefix$ac_delim +-prefix!$prefix$ac_delim +-program_transform_name!$program_transform_name$ac_delim +-bindir!$bindir$ac_delim +-sbindir!$sbindir$ac_delim +-libexecdir!$libexecdir$ac_delim +-datarootdir!$datarootdir$ac_delim +-datadir!$datadir$ac_delim +-sysconfdir!$sysconfdir$ac_delim +-sharedstatedir!$sharedstatedir$ac_delim +-localstatedir!$localstatedir$ac_delim +-includedir!$includedir$ac_delim +-oldincludedir!$oldincludedir$ac_delim +-docdir!$docdir$ac_delim +-infodir!$infodir$ac_delim +-htmldir!$htmldir$ac_delim +-dvidir!$dvidir$ac_delim +-pdfdir!$pdfdir$ac_delim +-psdir!$psdir$ac_delim +-libdir!$libdir$ac_delim +-localedir!$localedir$ac_delim +-mandir!$mandir$ac_delim +-DEFS!$DEFS$ac_delim +-ECHO_C!$ECHO_C$ac_delim +-ECHO_N!$ECHO_N$ac_delim +-ECHO_T!$ECHO_T$ac_delim +-LIBS!$LIBS$ac_delim +-build_alias!$build_alias$ac_delim +-host_alias!$host_alias$ac_delim +-target_alias!$target_alias$ac_delim +-MAINT!$MAINT$ac_delim +-build!$build$ac_delim +-build_cpu!$build_cpu$ac_delim +-build_vendor!$build_vendor$ac_delim +-build_os!$build_os$ac_delim +-host!$host$ac_delim +-host_cpu!$host_cpu$ac_delim +-host_vendor!$host_vendor$ac_delim +-host_os!$host_os$ac_delim +-CC!$CC$ac_delim +-CFLAGS!$CFLAGS$ac_delim +-LDFLAGS!$LDFLAGS$ac_delim +-CPPFLAGS!$CPPFLAGS$ac_delim +-ac_ct_CC!$ac_ct_CC$ac_delim +-EXEEXT!$EXEEXT$ac_delim +-OBJEXT!$OBJEXT$ac_delim +-CPP!$CPP$ac_delim +-GREP!$GREP$ac_delim +-EGREP!$EGREP$ac_delim +-LN_S!$LN_S$ac_delim +-INSTALL_PROGRAM!$INSTALL_PROGRAM$ac_delim +-INSTALL_SCRIPT!$INSTALL_SCRIPT$ac_delim +-INSTALL_DATA!$INSTALL_DATA$ac_delim +-RANLIB!$RANLIB$ac_delim +-INSTALL_INFO!$INSTALL_INFO$ac_delim +-GZIP_PROG!$GZIP_PROG$ac_delim +-MAKEINFO!$MAKEINFO$ac_delim +-LIBSOUND!$LIBSOUND$ac_delim +-PKG_CONFIG!$PKG_CONFIG$ac_delim +-ALSA_CFLAGS!$ALSA_CFLAGS$ac_delim +-ALSA_LIBS!$ALSA_LIBS$ac_delim +-CFLAGS_SOUND!$CFLAGS_SOUND$ac_delim +-SET_MAKE!$SET_MAKE$ac_delim +-XMKMF!$XMKMF$ac_delim +-HAVE_XSERVER!$HAVE_XSERVER$ac_delim +-RSVG_CFLAGS!$RSVG_CFLAGS$ac_delim +-RSVG_LIBS!$RSVG_LIBS$ac_delim +-GTK_CFLAGS!$GTK_CFLAGS$ac_delim +-GTK_LIBS!$GTK_LIBS$ac_delim +-DBUS_CFLAGS!$DBUS_CFLAGS$ac_delim +-DBUS_LIBS!$DBUS_LIBS$ac_delim +-FONTCONFIG_CFLAGS!$FONTCONFIG_CFLAGS$ac_delim +-FONTCONFIG_LIBS!$FONTCONFIG_LIBS$ac_delim +-XFT_CFLAGS!$XFT_CFLAGS$ac_delim +-XFT_LIBS!$XFT_LIBS$ac_delim +-LIBOTF_CFLAGS!$LIBOTF_CFLAGS$ac_delim +-LIBOTF_LIBS!$LIBOTF_LIBS$ac_delim +-M17N_FLT_CFLAGS!$M17N_FLT_CFLAGS$ac_delim +-M17N_FLT_LIBS!$M17N_FLT_LIBS$ac_delim +-FREETYPE_CFLAGS!$FREETYPE_CFLAGS$ac_delim +-FREETYPE_LIBS!$FREETYPE_LIBS$ac_delim +-ALLOCA!$ALLOCA$ac_delim +-liblockfile!$liblockfile$ac_delim +-LIBOBJS!$LIBOBJS$ac_delim +-NEED_SETGID!$NEED_SETGID$ac_delim +-KMEM_GROUP!$KMEM_GROUP$ac_delim +-GETLOADAVG_LIBS!$GETLOADAVG_LIBS$ac_delim +-GETOPT_H!$GETOPT_H$ac_delim +-GETOPTOBJS!$GETOPTOBJS$ac_delim +-version!$version$ac_delim +-_ACEOF ++ . ./conf$$subs.sh || ++ { { $as_echo "$as_me:$LINENO: error: could not make $CONFIG_STATUS" >&5 ++$as_echo "$as_me: error: could not make $CONFIG_STATUS" >&2;} ++ { (exit 1); exit 1; }; } + +- if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 97; then ++ ac_delim_n=`sed -n "s/.*$ac_delim\$/X/p" conf$$subs.awk | grep -c X` ++ if test $ac_delim_n = $ac_delim_num; then + break + elif $ac_last_try; then +- { { echo "$as_me:$LINENO: error: could not make $CONFIG_STATUS" >&5 +-echo "$as_me: error: could not make $CONFIG_STATUS" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: could not make $CONFIG_STATUS" >&5 ++$as_echo "$as_me: error: could not make $CONFIG_STATUS" >&2;} + { (exit 1); exit 1; }; } + else + ac_delim="$ac_delim!$ac_delim _$ac_delim!! " + fi + done ++rm -f conf$$subs.sh + +-ac_eof=`sed -n '/^CEOF[0-9]*$/s/CEOF/0/p' conf$$subs.sed` +-if test -n "$ac_eof"; then +- ac_eof=`echo "$ac_eof" | sort -nru | sed 1q` +- ac_eof=`expr $ac_eof + 1` +-fi +- +-cat >>$CONFIG_STATUS <<_ACEOF +-cat >"\$tmp/subs-1.sed" <<\CEOF$ac_eof +-/@[a-zA-Z_][a-zA-Z_0-9]*@/!b +-_ACEOF +-sed ' +-s/[,\\&]/\\&/g; s/@/@|#_!!_#|/g +-s/^/s,@/; s/!/@,|#_!!_#|/ +-:n +-t n +-s/'"$ac_delim"'$/,g/; t +-s/$/\\/; p +-N; s/^.*\n//; s/[,\\&]/\\&/g; s/@/@|#_!!_#|/g; b n +-' >>$CONFIG_STATUS >$CONFIG_STATUS <<_ACEOF +-CEOF$ac_eof ++cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 ++cat >>"\$tmp/subs1.awk" <<\\_ACAWK && + _ACEOF ++sed -n ' ++h ++s/^/S["/; s/!.*/"]=/ ++p ++g ++s/^[^!]*!// ++:repl ++t repl ++s/'"$ac_delim"'$// ++t delim ++:nl ++h ++s/\(.\{148\}\).*/\1/ ++t more1 ++s/["\\]/\\&/g; s/^/"/; s/$/\\n"\\/ ++p ++n ++b repl ++:more1 ++s/["\\]/\\&/g; s/^/"/; s/$/"\\/ ++p ++g ++s/.\{148\}// ++t nl ++:delim ++h ++s/\(.\{148\}\).*/\1/ ++t more2 ++s/["\\]/\\&/g; s/^/"/; s/$/"/ ++p ++b ++:more2 ++s/["\\]/\\&/g; s/^/"/; s/$/"\\/ ++p ++g ++s/.\{148\}// ++t delim ++' >$CONFIG_STATUS || ac_write_fail=1 ++rm -f conf$$subs.awk ++cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 ++_ACAWK ++cat >>"\$tmp/subs1.awk" <<_ACAWK && ++ for (key in S) S_is_set[key] = 1 ++ FS = "" ++ ++} ++{ ++ line = $ 0 ++ nfields = split(line, field, "@") ++ substed = 0 ++ len = length(field[1]) ++ for (i = 2; i < nfields; i++) { ++ key = field[i] ++ keylen = length(key) ++ if (S_is_set[key]) { ++ value = S[key] ++ line = substr(line, 1, len) "" value "" substr(line, len + keylen + 3) ++ len += length(value) + length(field[++i]) ++ substed = 1 ++ } else ++ len += 1 + keylen ++ } + ++ print line ++} + +-ac_delim='%!_!# ' +-for ac_last_try in false false false false false :; do +- cat >conf$$subs.sed <<_ACEOF +-configuration!$configuration$ac_delim +-canonical!$canonical$ac_delim +-srcdir!$srcdir$ac_delim +-lispdir!$lispdir$ac_delim +-locallisppath!$locallisppath$ac_delim +-lisppath!$lisppath$ac_delim +-x_default_search_path!$x_default_search_path$ac_delim +-etcdir!$etcdir$ac_delim +-archlibdir!$archlibdir$ac_delim +-bitmapdir!$bitmapdir$ac_delim +-gamedir!$gamedir$ac_delim +-gameuser!$gameuser$ac_delim +-c_switch_system!$c_switch_system$ac_delim +-c_switch_machine!$c_switch_machine$ac_delim +-LD_SWITCH_X_SITE!$LD_SWITCH_X_SITE$ac_delim +-LD_SWITCH_X_SITE_AUX!$LD_SWITCH_X_SITE_AUX$ac_delim +-C_SWITCH_X_SITE!$C_SWITCH_X_SITE$ac_delim +-X_TOOLKIT_TYPE!$X_TOOLKIT_TYPE$ac_delim +-machfile!$machfile$ac_delim +-opsysfile!$opsysfile$ac_delim +-ns_appdir!$ns_appdir$ac_delim +-ns_appbindir!$ns_appbindir$ac_delim +-ns_appresdir!$ns_appresdir$ac_delim +-ns_appsrc!$ns_appsrc$ac_delim +-GNUSTEP_MAKEFILES!$GNUSTEP_MAKEFILES$ac_delim +-GNUSTEP_SYSTEM_HEADERS!$GNUSTEP_SYSTEM_HEADERS$ac_delim +-GNUSTEP_SYSTEM_LIBRARIES!$GNUSTEP_SYSTEM_LIBRARIES$ac_delim +-GNU_OBJC_CFLAGS!$GNU_OBJC_CFLAGS$ac_delim +-LIB_SRC_EXTRA_INSTALLABLES!$LIB_SRC_EXTRA_INSTALLABLES$ac_delim +-LTLIBOBJS!$LTLIBOBJS$ac_delim ++_ACAWK + _ACEOF +- +- if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 30; then +- break +- elif $ac_last_try; then +- { { echo "$as_me:$LINENO: error: could not make $CONFIG_STATUS" >&5 +-echo "$as_me: error: could not make $CONFIG_STATUS" >&2;} ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 ++if sed "s/$ac_cr//" < /dev/null > /dev/null 2>&1; then ++ sed "s/$ac_cr\$//; s/$ac_cr/$ac_cs_awk_cr/g" ++else ++ cat ++fi < "$tmp/subs1.awk" > "$tmp/subs.awk" \ ++ || { { $as_echo "$as_me:$LINENO: error: could not setup config files machinery" >&5 ++$as_echo "$as_me: error: could not setup config files machinery" >&2;} + { (exit 1); exit 1; }; } +- else +- ac_delim="$ac_delim!$ac_delim _$ac_delim!! " +- fi +-done +- +-ac_eof=`sed -n '/^CEOF[0-9]*$/s/CEOF/0/p' conf$$subs.sed` +-if test -n "$ac_eof"; then +- ac_eof=`echo "$ac_eof" | sort -nru | sed 1q` +- ac_eof=`expr $ac_eof + 1` +-fi +- +-cat >>$CONFIG_STATUS <<_ACEOF +-cat >"\$tmp/subs-2.sed" <<\CEOF$ac_eof +-/@[a-zA-Z_][a-zA-Z_0-9]*@/!b end +-_ACEOF +-sed ' +-s/[,\\&]/\\&/g; s/@/@|#_!!_#|/g +-s/^/s,@/; s/!/@,|#_!!_#|/ +-:n +-t n +-s/'"$ac_delim"'$/,g/; t +-s/$/\\/; p +-N; s/^.*\n//; s/[,\\&]/\\&/g; s/@/@|#_!!_#|/g; b n +-' >>$CONFIG_STATUS >$CONFIG_STATUS <<_ACEOF +-:end +-s/|#_!!_#|//g +-CEOF$ac_eof + _ACEOF + +- + # VPATH may cause trouble with some makes, so we remove $(srcdir), + # ${srcdir} and @srcdir@ from VPATH if srcdir is ".", strip leading and + # trailing colons and then remove the whole line if VPATH becomes empty +@@ -25363,19 +26173,133 @@ + }' + fi + +-cat >>$CONFIG_STATUS <<\_ACEOF ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 + fi # test -n "$CONFIG_FILES" + ++# Set up the scripts for CONFIG_HEADERS section. ++# No need to generate them if there are no CONFIG_HEADERS. ++# This happens for instance with `./config.status Makefile'. ++if test -n "$CONFIG_HEADERS"; then ++cat >"$tmp/defines.awk" <<\_ACAWK || ++BEGIN { ++_ACEOF ++ ++# Transform confdefs.h into an awk script `defines.awk', embedded as ++# here-document in config.status, that substitutes the proper values into ++# config.h.in to produce config.h. ++ ++# Create a delimiter string that does not exist in confdefs.h, to ease ++# handling of long lines. ++ac_delim='%!_!# ' ++for ac_last_try in false false :; do ++ ac_t=`sed -n "/$ac_delim/p" confdefs.h` ++ if test -z "$ac_t"; then ++ break ++ elif $ac_last_try; then ++ { { $as_echo "$as_me:$LINENO: error: could not make $CONFIG_HEADERS" >&5 ++$as_echo "$as_me: error: could not make $CONFIG_HEADERS" >&2;} ++ { (exit 1); exit 1; }; } ++ else ++ ac_delim="$ac_delim!$ac_delim _$ac_delim!! " ++ fi ++done ++ ++# For the awk script, D is an array of macro values keyed by name, ++# likewise P contains macro parameters if any. Preserve backslash ++# newline sequences. ++ ++ac_word_re=[_$as_cr_Letters][_$as_cr_alnum]* ++sed -n ' ++s/.\{148\}/&'"$ac_delim"'/g ++t rset ++:rset ++s/^[ ]*#[ ]*define[ ][ ]*/ / ++t def ++d ++:def ++s/\\$// ++t bsnl ++s/["\\]/\\&/g ++s/^ \('"$ac_word_re"'\)\(([^()]*)\)[ ]*\(.*\)/P["\1"]="\2"\ ++D["\1"]=" \3"/p ++s/^ \('"$ac_word_re"'\)[ ]*\(.*\)/D["\1"]=" \2"/p ++d ++:bsnl ++s/["\\]/\\&/g ++s/^ \('"$ac_word_re"'\)\(([^()]*)\)[ ]*\(.*\)/P["\1"]="\2"\ ++D["\1"]=" \3\\\\\\n"\\/p ++t cont ++s/^ \('"$ac_word_re"'\)[ ]*\(.*\)/D["\1"]=" \2\\\\\\n"\\/p ++t cont ++d ++:cont ++n ++s/.\{148\}/&'"$ac_delim"'/g ++t clear ++:clear ++s/\\$// ++t bsnlc ++s/["\\]/\\&/g; s/^/"/; s/$/"/p ++d ++:bsnlc ++s/["\\]/\\&/g; s/^/"/; s/$/\\\\\\n"\\/p ++b cont ++' >$CONFIG_STATUS || ac_write_fail=1 ++ ++cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 ++ for (key in D) D_is_set[key] = 1 ++ FS = "" ++} ++/^[\t ]*#[\t ]*(define|undef)[\t ]+$ac_word_re([\t (]|\$)/ { ++ line = \$ 0 ++ split(line, arg, " ") ++ if (arg[1] == "#") { ++ defundef = arg[2] ++ mac1 = arg[3] ++ } else { ++ defundef = substr(arg[1], 2) ++ mac1 = arg[2] ++ } ++ split(mac1, mac2, "(") #) ++ macro = mac2[1] ++ prefix = substr(line, 1, index(line, defundef) - 1) ++ if (D_is_set[macro]) { ++ # Preserve the white space surrounding the "#". ++ print prefix "define", macro P[macro] D[macro] ++ next ++ } else { ++ # Replace #undef with comments. This is necessary, for example, ++ # in the case of _POSIX_SOURCE, which is predefined and required ++ # on some systems where configure will not decide to define it. ++ if (defundef == "undef") { ++ print "/*", prefix defundef, macro, "*/" ++ next ++ } ++ } ++} ++{ print } ++_ACAWK ++_ACEOF ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 ++ { { $as_echo "$as_me:$LINENO: error: could not setup config headers machinery" >&5 ++$as_echo "$as_me: error: could not setup config headers machinery" >&2;} ++ { (exit 1); exit 1; }; } ++fi # test -n "$CONFIG_HEADERS" ++ + +-for ac_tag in :F $CONFIG_FILES :H $CONFIG_HEADERS :C $CONFIG_COMMANDS ++eval set X " :F $CONFIG_FILES :H $CONFIG_HEADERS :C $CONFIG_COMMANDS" ++shift ++for ac_tag + do + case $ac_tag in + :[FHLC]) ac_mode=$ac_tag; continue;; + esac + case $ac_mode$ac_tag in + :[FHL]*:*);; +- :L* | :C*:*) { { echo "$as_me:$LINENO: error: Invalid tag $ac_tag." >&5 +-echo "$as_me: error: Invalid tag $ac_tag." >&2;} ++ :L* | :C*:*) { { $as_echo "$as_me:$LINENO: error: invalid tag $ac_tag" >&5 ++$as_echo "$as_me: error: invalid tag $ac_tag" >&2;} + { (exit 1); exit 1; }; };; + :[FH]-) ac_tag=-:-;; + :[FH]*) ac_tag=$ac_tag:$ac_tag.in;; +@@ -25404,26 +26328,38 @@ + [\\/$]*) false;; + *) test -f "$srcdir/$ac_f" && ac_f="$srcdir/$ac_f";; + esac || +- { { echo "$as_me:$LINENO: error: cannot find input file: $ac_f" >&5 +-echo "$as_me: error: cannot find input file: $ac_f" >&2;} ++ { { $as_echo "$as_me:$LINENO: error: cannot find input file: $ac_f" >&5 ++$as_echo "$as_me: error: cannot find input file: $ac_f" >&2;} + { (exit 1); exit 1; }; };; + esac +- ac_file_inputs="$ac_file_inputs $ac_f" ++ case $ac_f in *\'*) ac_f=`$as_echo "$ac_f" | sed "s/'/'\\\\\\\\''/g"`;; esac ++ ac_file_inputs="$ac_file_inputs '$ac_f'" + done + + # Let's still pretend it is `configure' which instantiates (i.e., don't + # use $as_me), people would be surprised to read: + # /* config.h. Generated by config.status. */ +- configure_input="Generated from "`IFS=: +- echo $* | sed 's|^[^:]*/||;s|:[^:]*/|, |g'`" by configure." ++ configure_input='Generated from '` ++ $as_echo "$*" | sed 's|^[^:]*/||;s|:[^:]*/|, |g' ++ `' by configure.' + if test x"$ac_file" != x-; then + configure_input="$ac_file. $configure_input" +- { echo "$as_me:$LINENO: creating $ac_file" >&5 +-echo "$as_me: creating $ac_file" >&6;} ++ { $as_echo "$as_me:$LINENO: creating $ac_file" >&5 ++$as_echo "$as_me: creating $ac_file" >&6;} + fi ++ # Neutralize special characters interpreted by sed in replacement strings. ++ case $configure_input in #( ++ *\&* | *\|* | *\\* ) ++ ac_sed_conf_input=`$as_echo "$configure_input" | ++ sed 's/[\\\\&|]/\\\\&/g'`;; #( ++ *) ac_sed_conf_input=$configure_input;; ++ esac + + case $ac_tag in +- *:-:* | *:-) cat >"$tmp/stdin";; ++ *:-:* | *:-) cat >"$tmp/stdin" \ ++ || { { $as_echo "$as_me:$LINENO: error: could not create $ac_file" >&5 ++$as_echo "$as_me: error: could not create $ac_file" >&2;} ++ { (exit 1); exit 1; }; } ;; + esac + ;; + esac +@@ -25433,7 +26369,7 @@ + X"$ac_file" : 'X\(//\)[^/]' \| \ + X"$ac_file" : 'X\(//\)$' \| \ + X"$ac_file" : 'X\(/\)' \| . 2>/dev/null || +-echo X"$ac_file" | ++$as_echo X"$ac_file" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q +@@ -25459,7 +26395,7 @@ + as_dirs= + while :; do + case $as_dir in #( +- *\'*) as_qdir=`echo "$as_dir" | sed "s/'/'\\\\\\\\''/g"`;; #( ++ *\'*) as_qdir=`$as_echo "$as_dir" | sed "s/'/'\\\\\\\\''/g"`;; #'( + *) as_qdir=$as_dir;; + esac + as_dirs="'$as_qdir' $as_dirs" +@@ -25468,7 +26404,7 @@ + X"$as_dir" : 'X\(//\)[^/]' \| \ + X"$as_dir" : 'X\(//\)$' \| \ + X"$as_dir" : 'X\(/\)' \| . 2>/dev/null || +-echo X"$as_dir" | ++$as_echo X"$as_dir" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q +@@ -25489,17 +26425,17 @@ + test -d "$as_dir" && break + done + test -z "$as_dirs" || eval "mkdir $as_dirs" +- } || test -d "$as_dir" || { { echo "$as_me:$LINENO: error: cannot create directory $as_dir" >&5 +-echo "$as_me: error: cannot create directory $as_dir" >&2;} ++ } || test -d "$as_dir" || { { $as_echo "$as_me:$LINENO: error: cannot create directory $as_dir" >&5 ++$as_echo "$as_me: error: cannot create directory $as_dir" >&2;} + { (exit 1); exit 1; }; }; } + ac_builddir=. + + case "$ac_dir" in + .) ac_dir_suffix= ac_top_builddir_sub=. ac_top_build_prefix= ;; + *) +- ac_dir_suffix=/`echo "$ac_dir" | sed 's,^\.[\\/],,'` ++ ac_dir_suffix=/`$as_echo "$ac_dir" | sed 's|^\.[\\/]||'` + # A ".." for each directory in $ac_dir_suffix. +- ac_top_builddir_sub=`echo "$ac_dir_suffix" | sed 's,/[^\\/]*,/..,g;s,/,,'` ++ ac_top_builddir_sub=`$as_echo "$ac_dir_suffix" | sed 's|/[^\\/]*|/..|g;s|/||'` + case $ac_top_builddir_sub in + "") ac_top_builddir_sub=. ac_top_build_prefix= ;; + *) ac_top_build_prefix=$ac_top_builddir_sub/ ;; +@@ -25539,12 +26475,13 @@ + esac + _ACEOF + +-cat >>$CONFIG_STATUS <<\_ACEOF ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 + # If the template does not know about datarootdir, expand it. + # FIXME: This hack should be removed a few years after 2.60. + ac_datarootdir_hack=; ac_datarootdir_seen= + +-case `sed -n '/datarootdir/ { ++ac_sed_dataroot=' ++/datarootdir/ { + p + q + } +@@ -25553,13 +26490,14 @@ + /@infodir@/p + /@localedir@/p + /@mandir@/p +-' $ac_file_inputs` in ++' ++case `eval "sed -n \"\$ac_sed_dataroot\" $ac_file_inputs"` in + *datarootdir*) ac_datarootdir_seen=yes;; + *@datadir@*|*@docdir@*|*@infodir@*|*@localedir@*|*@mandir@*) +- { echo "$as_me:$LINENO: WARNING: $ac_file_inputs seems to ignore the --datarootdir setting" >&5 +-echo "$as_me: WARNING: $ac_file_inputs seems to ignore the --datarootdir setting" >&2;} ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_file_inputs seems to ignore the --datarootdir setting" >&5 ++$as_echo "$as_me: WARNING: $ac_file_inputs seems to ignore the --datarootdir setting" >&2;} + _ACEOF +-cat >>$CONFIG_STATUS <<_ACEOF ++cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 + ac_datarootdir_hack=' + s&@datadir@&$datadir&g + s&@docdir@&$docdir&g +@@ -25573,15 +26511,16 @@ + # Neutralize VPATH when `$srcdir' = `.'. + # Shell code in configure.ac might set extrasub. + # FIXME: do we really want to maintain this feature? +-cat >>$CONFIG_STATUS <<_ACEOF +- sed "$ac_vpsub ++cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 ++ac_sed_extra="$ac_vpsub + $extrasub + _ACEOF +-cat >>$CONFIG_STATUS <<\_ACEOF ++cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 + :t + /@[a-zA-Z_][a-zA-Z_0-9]*@/!b +-s&@configure_input@&$configure_input&;t t ++s|@configure_input@|$ac_sed_conf_input|;t t + s&@top_builddir@&$ac_top_builddir_sub&;t t ++s&@top_build_prefix@&$ac_top_build_prefix&;t t + s&@srcdir@&$ac_srcdir&;t t + s&@abs_srcdir@&$ac_abs_srcdir&;t t + s&@top_srcdir@&$ac_top_srcdir&;t t +@@ -25591,123 +26530,62 @@ + s&@abs_top_builddir@&$ac_abs_top_builddir&;t t + s&@INSTALL@&$ac_INSTALL&;t t + $ac_datarootdir_hack +-" $ac_file_inputs | sed -f "$tmp/subs-1.sed" | sed -f "$tmp/subs-2.sed" >$tmp/out ++" ++eval sed \"\$ac_sed_extra\" "$ac_file_inputs" | $AWK -f "$tmp/subs.awk" >$tmp/out \ ++ || { { $as_echo "$as_me:$LINENO: error: could not create $ac_file" >&5 ++$as_echo "$as_me: error: could not create $ac_file" >&2;} ++ { (exit 1); exit 1; }; } + + test -z "$ac_datarootdir_hack$ac_datarootdir_seen" && + { ac_out=`sed -n '/\${datarootdir}/p' "$tmp/out"`; test -n "$ac_out"; } && + { ac_out=`sed -n '/^[ ]*datarootdir[ ]*:*=/p' "$tmp/out"`; test -z "$ac_out"; } && +- { echo "$as_me:$LINENO: WARNING: $ac_file contains a reference to the variable \`datarootdir' ++ { $as_echo "$as_me:$LINENO: WARNING: $ac_file contains a reference to the variable \`datarootdir' + which seems to be undefined. Please make sure it is defined." >&5 +-echo "$as_me: WARNING: $ac_file contains a reference to the variable \`datarootdir' ++$as_echo "$as_me: WARNING: $ac_file contains a reference to the variable \`datarootdir' + which seems to be undefined. Please make sure it is defined." >&2;} + + rm -f "$tmp/stdin" + case $ac_file in +- -) cat "$tmp/out"; rm -f "$tmp/out";; +- *) rm -f "$ac_file"; mv "$tmp/out" $ac_file;; +- esac ++ -) cat "$tmp/out" && rm -f "$tmp/out";; ++ *) rm -f "$ac_file" && mv "$tmp/out" "$ac_file";; ++ esac \ ++ || { { $as_echo "$as_me:$LINENO: error: could not create $ac_file" >&5 ++$as_echo "$as_me: error: could not create $ac_file" >&2;} ++ { (exit 1); exit 1; }; } + ;; + :H) + # + # CONFIG_HEADER + # +-_ACEOF +- +-# Transform confdefs.h into a sed script `conftest.defines', that +-# substitutes the proper values into config.h.in to produce config.h. +-rm -f conftest.defines conftest.tail +-# First, append a space to every undef/define line, to ease matching. +-echo 's/$/ /' >conftest.defines +-# Then, protect against being on the right side of a sed subst, or in +-# an unquoted here document, in config.status. If some macros were +-# called several times there might be several #defines for the same +-# symbol, which is useless. But do not sort them, since the last +-# AC_DEFINE must be honored. +-ac_word_re=[_$as_cr_Letters][_$as_cr_alnum]* +-# These sed commands are passed to sed as "A NAME B PARAMS C VALUE D", where +-# NAME is the cpp macro being defined, VALUE is the value it is being given. +-# PARAMS is the parameter list in the macro definition--in most cases, it's +-# just an empty string. +-ac_dA='s,^\\([ #]*\\)[^ ]*\\([ ]*' +-ac_dB='\\)[ (].*,\\1define\\2' +-ac_dC=' ' +-ac_dD=' ,' +- +-uniq confdefs.h | +- sed -n ' +- t rset +- :rset +- s/^[ ]*#[ ]*define[ ][ ]*// +- t ok +- d +- :ok +- s/[\\&,]/\\&/g +- s/^\('"$ac_word_re"'\)\(([^()]*)\)[ ]*\(.*\)/ '"$ac_dA"'\1'"$ac_dB"'\2'"${ac_dC}"'\3'"$ac_dD"'/p +- s/^\('"$ac_word_re"'\)[ ]*\(.*\)/'"$ac_dA"'\1'"$ac_dB$ac_dC"'\2'"$ac_dD"'/p +- ' >>conftest.defines +- +-# Remove the space that was appended to ease matching. +-# Then replace #undef with comments. This is necessary, for +-# example, in the case of _POSIX_SOURCE, which is predefined and required +-# on some systems where configure will not decide to define it. +-# (The regexp can be short, since the line contains either #define or #undef.) +-echo 's/ $// +-s,^[ #]*u.*,/* & */,' >>conftest.defines +- +-# Break up conftest.defines: +-ac_max_sed_lines=50 +- +-# First sed command is: sed -f defines.sed $ac_file_inputs >"$tmp/out1" +-# Second one is: sed -f defines.sed "$tmp/out1" >"$tmp/out2" +-# Third one will be: sed -f defines.sed "$tmp/out2" >"$tmp/out1" +-# et cetera. +-ac_in='$ac_file_inputs' +-ac_out='"$tmp/out1"' +-ac_nxt='"$tmp/out2"' +- +-while : +-do +- # Write a here document: +- cat >>$CONFIG_STATUS <<_ACEOF +- # First, check the format of the line: +- cat >"\$tmp/defines.sed" <<\\CEOF +-/^[ ]*#[ ]*undef[ ][ ]*$ac_word_re[ ]*\$/b def +-/^[ ]*#[ ]*define[ ][ ]*$ac_word_re[( ]/b def +-b +-:def +-_ACEOF +- sed ${ac_max_sed_lines}q conftest.defines >>$CONFIG_STATUS +- echo 'CEOF +- sed -f "$tmp/defines.sed"' "$ac_in >$ac_out" >>$CONFIG_STATUS +- ac_in=$ac_out; ac_out=$ac_nxt; ac_nxt=$ac_in +- sed 1,${ac_max_sed_lines}d conftest.defines >conftest.tail +- grep . conftest.tail >/dev/null || break +- rm -f conftest.defines +- mv conftest.tail conftest.defines +-done +-rm -f conftest.defines conftest.tail +- +-echo "ac_result=$ac_in" >>$CONFIG_STATUS +-cat >>$CONFIG_STATUS <<\_ACEOF + if test x"$ac_file" != x-; then +- echo "/* $configure_input */" >"$tmp/config.h" +- cat "$ac_result" >>"$tmp/config.h" +- if diff $ac_file "$tmp/config.h" >/dev/null 2>&1; then +- { echo "$as_me:$LINENO: $ac_file is unchanged" >&5 +-echo "$as_me: $ac_file is unchanged" >&6;} ++ { ++ $as_echo "/* $configure_input */" \ ++ && eval '$AWK -f "$tmp/defines.awk"' "$ac_file_inputs" ++ } >"$tmp/config.h" \ ++ || { { $as_echo "$as_me:$LINENO: error: could not create $ac_file" >&5 ++$as_echo "$as_me: error: could not create $ac_file" >&2;} ++ { (exit 1); exit 1; }; } ++ if diff "$ac_file" "$tmp/config.h" >/dev/null 2>&1; then ++ { $as_echo "$as_me:$LINENO: $ac_file is unchanged" >&5 ++$as_echo "$as_me: $ac_file is unchanged" >&6;} + else +- rm -f $ac_file +- mv "$tmp/config.h" $ac_file ++ rm -f "$ac_file" ++ mv "$tmp/config.h" "$ac_file" \ ++ || { { $as_echo "$as_me:$LINENO: error: could not create $ac_file" >&5 ++$as_echo "$as_me: error: could not create $ac_file" >&2;} ++ { (exit 1); exit 1; }; } + fi + else +- echo "/* $configure_input */" +- cat "$ac_result" ++ $as_echo "/* $configure_input */" \ ++ && eval '$AWK -f "$tmp/defines.awk"' "$ac_file_inputs" \ ++ || { { $as_echo "$as_me:$LINENO: error: could not create -" >&5 ++$as_echo "$as_me: error: could not create -" >&2;} ++ { (exit 1); exit 1; }; } + fi +- rm -f "$tmp/out12" + ;; + +- :C) { echo "$as_me:$LINENO: executing $ac_file commands" >&5 +-echo "$as_me: executing $ac_file commands" >&6;} ++ :C) { $as_echo "$as_me:$LINENO: executing $ac_file commands" >&5 ++$as_echo "$as_me: executing $ac_file commands" >&6;} + ;; + esac + +@@ -25782,6 +26660,11 @@ + chmod +x $CONFIG_STATUS + ac_clean_files=$ac_clean_files_save + ++test $ac_write_fail = 0 || ++ { { $as_echo "$as_me:$LINENO: error: write failure creating $CONFIG_STATUS" >&5 ++$as_echo "$as_me: error: write failure creating $CONFIG_STATUS" >&2;} ++ { (exit 1); exit 1; }; } ++ + + # configure is writing to config.log, and then calls config.status. + # config.status does its own redirection, appending to config.log. +@@ -25803,5 +26686,9 @@ + # would make configure fail if this is the last instruction. + $ac_cs_success || { (exit 1); exit 1; } + fi ++if test -n "$ac_unrecognized_opts" && test "$enable_option_checking" != no; then ++ { $as_echo "$as_me:$LINENO: WARNING: unrecognized options: $ac_unrecognized_opts" >&5 ++$as_echo "$as_me: WARNING: unrecognized options: $ac_unrecognized_opts" >&2;} ++fi + + +Index: emacs23/src/config.in +=================================================================== +--- emacs23.orig/src/config.in ++++ emacs23/src/config.in +@@ -888,6 +888,28 @@ + /* Define to 1 if using the Motif X toolkit. */ + #undef USE_MOTIF + ++/* Enable extensions on AIX 3, Interix. */ ++#ifndef _ALL_SOURCE ++# undef _ALL_SOURCE ++#endif ++/* Enable GNU extensions on systems that have them. */ ++#ifndef _GNU_SOURCE ++# undef _GNU_SOURCE ++#endif ++/* Enable threading extensions on Solaris. */ ++#ifndef _POSIX_PTHREAD_SEMANTICS ++# undef _POSIX_PTHREAD_SEMANTICS ++#endif ++/* Enable extensions on HP NonStop. */ ++#ifndef _TANDEM_SOURCE ++# undef _TANDEM_SOURCE ++#endif ++/* Enable general extensions on Solaris. */ ++#ifndef __EXTENSIONS__ ++# undef __EXTENSIONS__ ++#endif ++ ++ + /* Define to 1 if we should use toolkit scroll bars. */ + #undef USE_TOOLKIT_SCROLL_BARS + +@@ -901,21 +923,9 @@ + XPointer or XPointer*. */ + #undef XRegisterIMInstantiateCallback_arg6 + +-/* Define to 1 if on AIX 3. +- System headers sometimes define this. +- We just want to avoid a redefinition error message. */ +-#ifndef _ALL_SOURCE +-# undef _ALL_SOURCE +-#endif +- + /* Number of bits in a file offset, on hosts where this is settable. */ + #undef _FILE_OFFSET_BITS + +-/* Enable GNU extensions on systems that have them. */ +-#ifndef _GNU_SOURCE +-# undef _GNU_SOURCE +-#endif +- + /* Define to 1 to make fseeko visible on some hosts (e.g. glibc 2.2). */ + #undef _LARGEFILE_SOURCE + +@@ -932,17 +942,6 @@ + /* Define to 1 if you need to in order for `stat' and other things to work. */ + #undef _POSIX_SOURCE + +-/* Enable extensions on Solaris. */ +-#ifndef __EXTENSIONS__ +-# undef __EXTENSIONS__ +-#endif +-#ifndef _POSIX_PTHREAD_SEMANTICS +-# undef _POSIX_PTHREAD_SEMANTICS +-#endif +-#ifndef _TANDEM_SOURCE +-# undef _TANDEM_SOURCE +-#endif +- + /* Define to rpl_ if the getopt replacement functions and variables should be + used. */ + #undef __GETOPT_PREFIX +Index: emacs23/src/config.in~ +=================================================================== +--- /dev/null ++++ emacs23/src/config.in~ +@@ -0,0 +1,1219 @@ ++/* src/config.in. Generated from configure.in by autoheader. */ ++ ++/* GNU Emacs site configuration template file. ++ Copyright (C) 1988, 1993, 1994, 1999, 2000, 2001, 2002, 2004, 2005, ++ 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++ ++This file is part of GNU Emacs. ++ ++GNU Emacs 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. ++ ++GNU Emacs 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 GNU Emacs. If not, see . */ ++ ++ ++/* No code in Emacs #includes config.h twice, but some bits of code ++ intended to work with other packages as well (like gmalloc.c) ++ think they can include it as many times as they like. */ ++#ifndef EMACS_CONFIG_H ++#define EMACS_CONFIG_H ++ ++ ++/* Define to 1 if the mktime function is broken. */ ++#undef BROKEN_MKTIME ++ ++/* Define to one of `_getb67', `GETB67', `getb67' for Cray-2 and Cray-YMP ++ systems. This function is required for `alloca.c' support on those systems. ++ */ ++#undef CRAY_STACKSEG_END ++ ++/* Define to 1 if using `alloca.c'. */ ++#undef C_ALLOCA ++ ++/* Define to 1 if using `getloadavg.c'. */ ++#undef C_GETLOADAVG ++ ++/* Define C_SWITCH_X_SITE to contain any special flags your compiler may need ++ to deal with X Windows. For instance, if you've defined HAVE_X_WINDOWS ++ above and your X include files aren't in a place that your compiler can ++ find on its own, you might want to add "-I/..." or something similar. */ ++#undef C_SWITCH_X_SITE ++ ++/* Define to 1 for DGUX with . */ ++#undef DGUX ++ ++/* Define to 1 if you are using the GNU C Library. */ ++#undef DOUG_LEA_MALLOC ++ ++/* Define to the canonical Emacs configuration name. */ ++#undef EMACS_CONFIGURATION ++ ++/* Define to the options passed to configure. */ ++#undef EMACS_CONFIG_OPTIONS ++ ++/* Define to 1 if the `getloadavg' function needs to be run setuid or setgid. ++ */ ++#undef GETLOADAVG_PRIVILEGED ++ ++/* Define to 1 if the `getpgrp' function requires zero arguments. */ ++#undef GETPGRP_VOID ++ ++/* Define to 1 if gettimeofday accepts only one argument. */ ++#undef GETTIMEOFDAY_ONE_ARGUMENT ++ ++/* Define to 1 if you want to use the GNU memory allocator. */ ++#undef GNU_MALLOC ++ ++/* Define to 1 if the file /usr/lpp/X11/bin/smt.exp exists. */ ++#undef HAVE_AIX_SMT_EXP ++ ++/* Define to 1 if you have the `alarm' function. */ ++#undef HAVE_ALARM ++ ++/* Define to 1 if you have `alloca', as a function or macro. */ ++#undef HAVE_ALLOCA ++ ++/* Define to 1 if you have and it should be used (not on Ultrix). ++ */ ++#undef HAVE_ALLOCA_H ++ ++/* Define to 1 if ALSA is available. */ ++#undef HAVE_ALSA ++ ++/* Define to 1 if you have the `bcmp' function. */ ++#undef HAVE_BCMP ++ ++/* Define to 1 if you have the `bcopy' function. */ ++#undef HAVE_BCOPY ++ ++/* Define to 1 if you have the `bzero' function. */ ++#undef HAVE_BZERO ++ ++/* Define to 1 if you have the `cbrt' function. */ ++#undef HAVE_CBRT ++ ++/* Define to 1 if you have the `cfmakeraw' function. */ ++#undef HAVE_CFMAKERAW ++ ++/* Define to 1 if you have the `cfsetspeed' function. */ ++#undef HAVE_CFSETSPEED ++ ++/* Define to 1 if you have the `closedir' function. */ ++#undef HAVE_CLOSEDIR ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_COFF_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_COM_ERR_H ++ ++/* Define to 1 if you have /usr/lib/crti.o. */ ++#undef HAVE_CRTIN ++ ++/* Define to 1 if using D-Bus. */ ++#undef HAVE_DBUS ++ ++/* Define to 1 if you have the declaration of `sys_siglist', and to 0 if you ++ don't. */ ++#undef HAVE_DECL_SYS_SIGLIST ++ ++/* Define to 1 if you have the declaration of `tzname', and to 0 if you don't. ++ */ ++#undef HAVE_DECL_TZNAME ++ ++/* Define to 1 if you have the declaration of `__sys_siglist', and to 0 if you ++ don't. */ ++#undef HAVE_DECL___SYS_SIGLIST ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_DES_H ++ ++/* Define to 1 if dynamic ptys are supported. */ ++#undef HAVE_DEV_PTMX ++ ++/* Define to 1 if you have the `difftime' function. */ ++#undef HAVE_DIFFTIME ++ ++/* Define to 1 if you have the `dup2' function. */ ++#undef HAVE_DUP2 ++ ++/* Define to 1 if you have the `euidaccess' function. */ ++#undef HAVE_EUIDACCESS ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_FCNTL_H ++ ++/* Define to 1 if you have the `fmod' function. */ ++#undef HAVE_FMOD ++ ++/* Define to 1 if you have the `fork' function. */ ++#undef HAVE_FORK ++ ++/* Define to 1 if you have the `fpathconf' function. */ ++#undef HAVE_FPATHCONF ++ ++/* Define to 1 if using the freetype and fontconfig libraries. */ ++#undef HAVE_FREETYPE ++ ++/* Define to 1 if you have the `frexp' function. */ ++#undef HAVE_FREXP ++ ++/* Define to 1 if fseeko (and presumably ftello) exists and is declared. */ ++#undef HAVE_FSEEKO ++ ++/* Define to 1 if you have the `fsync' function. */ ++#undef HAVE_FSYNC ++ ++/* Define to 1 if you have the `ftime' function. */ ++#undef HAVE_FTIME ++ ++/* Define to 1 if you have the `gai_strerror' function. */ ++#undef HAVE_GAI_STRERROR ++ ++/* Define to 1 if you have the `gdk_display_open' function. */ ++#undef HAVE_GDK_DISPLAY_OPEN ++ ++/* Define to 1 if you have the `getaddrinfo' function. */ ++#undef HAVE_GETADDRINFO ++ ++/* Define to 1 if you have the `getcwd' function. */ ++#undef HAVE_GETCWD ++ ++/* Define to 1 if you have the `getdelim' function. */ ++#undef HAVE_GETDELIM ++ ++/* Define to 1 if you have the `getdomainname' function. */ ++#undef HAVE_GETDOMAINNAME ++ ++/* Define to 1 if you have the `gethostname' function. */ ++#undef HAVE_GETHOSTNAME ++ ++/* Define to 1 if you have the `getline' function. */ ++#undef HAVE_GETLINE ++ ++/* Define to 1 if you have the `getloadavg' function. */ ++#undef HAVE_GETLOADAVG ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_GETOPT_H ++ ++/* Define to 1 if you have the `getopt_long_only' function. */ ++#undef HAVE_GETOPT_LONG_ONLY ++ ++/* Define to 1 if you have the `getpagesize' function. */ ++#undef HAVE_GETPAGESIZE ++ ++/* Define to 1 if you have the `getpeername' function. */ ++#undef HAVE_GETPEERNAME ++ ++/* Define to 1 if you have the `getpt' function. */ ++#undef HAVE_GETPT ++ ++/* Define to 1 if you have the `getrlimit' function. */ ++#undef HAVE_GETRLIMIT ++ ++/* Define to 1 if you have the `getrusage' function. */ ++#undef HAVE_GETRUSAGE ++ ++/* Define to 1 if you have the `getsockname' function. */ ++#undef HAVE_GETSOCKNAME ++ ++/* Define to 1 if you have the `getsockopt' function. */ ++#undef HAVE_GETSOCKOPT ++ ++/* Define to 1 if you have the `gettimeofday' function. */ ++#undef HAVE_GETTIMEOFDAY ++ ++/* Define to 1 if you have the `getwd' function. */ ++#undef HAVE_GETWD ++ ++/* Define to 1 if you have the `get_current_dir_name' function. */ ++#undef HAVE_GET_CURRENT_DIR_NAME ++ ++/* Define to 1 if you have a gif library (default -lgif; otherwise specify ++ with LIBGIF). */ ++#undef HAVE_GIF ++ ++/* Define to 1 if you have the gpm library (-lgpm). */ ++#undef HAVE_GPM ++ ++/* Define to 1 if you have the `grantpt' function. */ ++#undef HAVE_GRANTPT ++ ++/* Define to 1 if you have GTK and pthread (-lpthread). */ ++#undef HAVE_GTK_AND_PTHREAD ++ ++/* Define to 1 if GTK has both file selection and chooser dialog. */ ++#undef HAVE_GTK_FILE_BOTH ++ ++/* Define to 1 if you have the `gtk_file_chooser_dialog_new' function. */ ++#undef HAVE_GTK_FILE_CHOOSER_DIALOG_NEW ++ ++/* Define to 1 if you have the `gtk_file_selection_new' function. */ ++#undef HAVE_GTK_FILE_SELECTION_NEW ++ ++/* Define to 1 if you have the `gtk_main' function. */ ++#undef HAVE_GTK_MAIN ++ ++/* Define to 1 if GTK can handle more than one display. */ ++#undef HAVE_GTK_MULTIDISPLAY ++ ++/* Define to 1 if netdb.h declares h_errno. */ ++#undef HAVE_H_ERRNO ++ ++/* Define to 1 if you have the `index' function. */ ++#undef HAVE_INDEX ++ ++/* Define to 1 if you have inet sockets. */ ++#undef HAVE_INET_SOCKETS ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_INTTYPES_H ++ ++/* Define to 1 if you have the jpeg library (-ljpeg). */ ++#undef HAVE_JPEG ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_KERBEROSIV_DES_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_KERBEROSIV_KRB_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_KERBEROS_DES_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_KERBEROS_KRB_H ++ ++/* Define to 1 if `e_text' is member of `krb5_error'. */ ++#undef HAVE_KRB5_ERROR_E_TEXT ++ ++/* Define to 1 if `text' is member of `krb5_error'. */ ++#undef HAVE_KRB5_ERROR_TEXT ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_KRB5_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_KRB_H ++ ++/* Define if you have and nl_langinfo(CODESET). */ ++#undef HAVE_LANGINFO_CODESET ++ ++/* Define to 1 if the directory /usr/lib64 exists. */ ++#undef HAVE_LIB64_DIR ++ ++/* Define to 1 if you have the `com_err' library (-lcom_err). */ ++#undef HAVE_LIBCOM_ERR ++ ++/* Define to 1 if you have the `crypto' library (-lcrypto). */ ++#undef HAVE_LIBCRYPTO ++ ++/* Define to 1 if you have the `des' library (-ldes). */ ++#undef HAVE_LIBDES ++ ++/* Define to 1 if you have the `des425' library (-ldes425). */ ++#undef HAVE_LIBDES425 ++ ++/* Define to 1 if you have the `dgc' library (-ldgc). */ ++#undef HAVE_LIBDGC ++ ++/* Define to 1 if you have the `dnet' library (-ldnet). */ ++#undef HAVE_LIBDNET ++ ++/* Define to 1 if you have the hesiod library (-lhesiod). */ ++#undef HAVE_LIBHESIOD ++ ++/* Define to 1 if you have the `intl' library (-lintl). */ ++#undef HAVE_LIBINTL ++ ++/* Define to 1 if you have the `k5crypto' library (-lk5crypto). */ ++#undef HAVE_LIBK5CRYPTO ++ ++/* Define to 1 if you have the `krb' library (-lkrb). */ ++#undef HAVE_LIBKRB ++ ++/* Define to 1 if you have the `krb4' library (-lkrb4). */ ++#undef HAVE_LIBKRB4 ++ ++/* Define to 1 if you have the `krb5' library (-lkrb5). */ ++#undef HAVE_LIBKRB5 ++ ++/* Define to 1 if you have the `kstat' library (-lkstat). */ ++#undef HAVE_LIBKSTAT ++ ++/* Define to 1 if you have the `lockfile' library (-llockfile). */ ++#undef HAVE_LIBLOCKFILE ++ ++/* Define to 1 if you have the `m' library (-lm). */ ++#undef HAVE_LIBM ++ ++/* Define to 1 if you have the `mail' library (-lmail). */ ++#undef HAVE_LIBMAIL ++ ++/* Define to 1 if you have the `ncurses' library (-lncurses). */ ++#undef HAVE_LIBNCURSES ++ ++/* Define to 1 if using libotf. */ ++#undef HAVE_LIBOTF ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_LIBPNG_PNG_H ++ ++/* Define to 1 if you have the `pthreads' library (-lpthreads). */ ++#undef HAVE_LIBPTHREADS ++ ++/* Define to 1 if you have the resolv library (-lresolv). */ ++#undef HAVE_LIBRESOLV ++ ++/* Define to 1 if you have the `Xext' library (-lXext). */ ++#undef HAVE_LIBXEXT ++ ++/* Define to 1 if you have the `Xmu' library (-lXmu). */ ++#undef HAVE_LIBXMU ++ ++/* Define to 1 if you have the Xp library (-lXp). */ ++#undef HAVE_LIBXP ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_LIMITS_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_LINUX_VERSION_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_LOCALE_H ++ ++/* Define to 1 if you have the `logb' function. */ ++#undef HAVE_LOGB ++ ++/* Define to 1 if you support file names longer than 14 characters. */ ++#undef HAVE_LONG_FILE_NAMES ++ ++/* Define to 1 if you have the `lrand48' function. */ ++#undef HAVE_LRAND48 ++ ++/* Define to 1 if using libm17n-flt. */ ++#undef HAVE_M17N_FLT ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_MACHINE_SOUNDCARD_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_MACH_MACH_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_MAILLOCK_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_MALLOC_MALLOC_H ++ ++/* Define to 1 if you have the `mblen' function. */ ++#undef HAVE_MBLEN ++ ++/* Define to 1 if you have the `mbrlen' function. */ ++#undef HAVE_MBRLEN ++ ++/* Define to 1 if you have the `mbsinit' function. */ ++#undef HAVE_MBSINIT ++ ++/* Define to 1 if declares mbstate_t. */ ++#undef HAVE_MBSTATE_T ++ ++/* Define to 1 if you have the `memcmp' function. */ ++#undef HAVE_MEMCMP ++ ++/* Define to 1 if you have the `memcpy' function. */ ++#undef HAVE_MEMCPY ++ ++/* Define to 1 if you have the `memmove' function. */ ++#undef HAVE_MEMMOVE ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_MEMORY_H ++ ++/* Define to 1 if you have the `mempcpy' function. */ ++#undef HAVE_MEMPCPY ++ ++/* Define to 1 if you have the `memset' function. */ ++#undef HAVE_MEMSET ++ ++/* Define to 1 if you have mouse menus. (This is automatic if you use X, but ++ the option to specify it remains.) It is also defined with other window ++ systems that support xmenu.c. */ ++#undef HAVE_MENUS ++ ++/* Define to 1 if you have the `mkdir' function. */ ++#undef HAVE_MKDIR ++ ++/* Define to 1 if you have the `mkstemp' function. */ ++#undef HAVE_MKSTEMP ++ ++/* Define to 1 if you have the `mktime' function. */ ++#undef HAVE_MKTIME ++ ++/* Define to 1 if you have a working `mmap' system call. */ ++#undef HAVE_MMAP ++ ++/* Define to 1 if you have Motif 2.1 or newer. */ ++#undef HAVE_MOTIF_2_1 ++ ++/* Define to 1 if you have the `mremap' function. */ ++#undef HAVE_MREMAP ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_NET_IF_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_NLIST_H ++ ++/* Define to 1 if you are using the NeXTstep API, either GNUstep or Cocoa on ++ Mac OS X. */ ++#undef HAVE_NS ++ ++/* Define to 1 if libotf has OTF_get_variation_glyphs. */ ++#undef HAVE_OTF_GET_VARIATION_GLYPHS ++ ++/* Define to 1 if personality LINUX32 can be set. */ ++#undef HAVE_PERSONALITY_LINUX32 ++ ++/* Define to 1 if you have the png library (-lpng). */ ++#undef HAVE_PNG ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_PNG_H ++ ++/* Define to 1 if you have the `posix_memalign' function. */ ++#undef HAVE_POSIX_MEMALIGN ++ ++/* Define to 1 if you have the `pstat_getdynamic' function. */ ++#undef HAVE_PSTAT_GETDYNAMIC ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_PTHREAD_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_PTY_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_PWD_H ++ ++/* Define to 1 if you have the `random' function. */ ++#undef HAVE_RANDOM ++ ++/* Define to 1 if you have the `recvfrom' function. */ ++#undef HAVE_RECVFROM ++ ++/* Define to 1 if you have the `rename' function. */ ++#undef HAVE_RENAME ++ ++/* Define to 1 if res_init is available. */ ++#undef HAVE_RES_INIT ++ ++/* Define to 1 if you have the `rindex' function. */ ++#undef HAVE_RINDEX ++ ++/* Define to 1 if you have the `rint' function. */ ++#undef HAVE_RINT ++ ++/* Define to 1 if you have the `rmdir' function. */ ++#undef HAVE_RMDIR ++ ++/* Define to 1 if using librsvg. */ ++#undef HAVE_RSVG ++ ++/* Define to 1 if you have the `select' function. */ ++#undef HAVE_SELECT ++ ++/* Define to 1 if you have the `sendto' function. */ ++#undef HAVE_SENDTO ++ ++/* Define to 1 if you have the `setitimer' function. */ ++#undef HAVE_SETITIMER ++ ++/* Define to 1 if you have the `setlocale' function. */ ++#undef HAVE_SETLOCALE ++ ++/* Define to 1 if you have the `setpgid' function. */ ++#undef HAVE_SETPGID ++ ++/* Define to 1 if you have the `setrlimit' function. */ ++#undef HAVE_SETRLIMIT ++ ++/* Define to 1 if you have the `setsid' function. */ ++#undef HAVE_SETSID ++ ++/* Define to 1 if you have the `setsockopt' function. */ ++#undef HAVE_SETSOCKOPT ++ ++/* Define to 1 if you have the `shutdown' function. */ ++#undef HAVE_SHUTDOWN ++ ++/* Define to 1 if the system has the type `size_t'. */ ++#undef HAVE_SIZE_T ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SOUNDCARD_H ++ ++/* Define to 1 if `speed_t' is declared by . */ ++#undef HAVE_SPEED_T ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_STDINT_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_STDIO_EXT_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_STDLIB_H ++ ++/* Define to 1 if you have the `strerror' function. */ ++#undef HAVE_STRERROR ++ ++/* Define to 1 if you have the `strftime' function. */ ++#undef HAVE_STRFTIME ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_STRINGS_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_STRING_H ++ ++/* Define to 1 if you have the `strsignal' function. */ ++#undef HAVE_STRSIGNAL ++ ++/* Define to 1 if `ifr_addr' is member of `struct ifreq'. */ ++#undef HAVE_STRUCT_IFREQ_IFR_ADDR ++ ++/* Define to 1 if `ifr_broadaddr' is member of `struct ifreq'. */ ++#undef HAVE_STRUCT_IFREQ_IFR_BROADADDR ++ ++/* Define to 1 if `ifr_flags' is member of `struct ifreq'. */ ++#undef HAVE_STRUCT_IFREQ_IFR_FLAGS ++ ++/* Define to 1 if `ifr_hwaddr' is member of `struct ifreq'. */ ++#undef HAVE_STRUCT_IFREQ_IFR_HWADDR ++ ++/* Define to 1 if `ifr_netmask' is member of `struct ifreq'. */ ++#undef HAVE_STRUCT_IFREQ_IFR_NETMASK ++ ++/* Define to 1 if `n_un.n_name' is member of `struct nlist'. */ ++#undef HAVE_STRUCT_NLIST_N_UN_N_NAME ++ ++/* Define to 1 if `tm_zone' is member of `struct tm'. */ ++#undef HAVE_STRUCT_TM_TM_ZONE ++ ++/* Define to 1 if `struct utimbuf' is declared by . */ ++#undef HAVE_STRUCT_UTIMBUF ++ ++/* Define to 1 if you have the `sync' function. */ ++#undef HAVE_SYNC ++ ++/* Define to 1 if you have the `sysinfo' function. */ ++#undef HAVE_SYSINFO ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_IOCTL_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_MMAN_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_PARAM_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_RESOURCE_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_SELECT_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_SOCKET_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_SOUNDCARD_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_STAT_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_SYSTEMINFO_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_TIMEB_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_TIME_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_TYPES_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_UN_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_UTSNAME_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS_VLIMIT_H ++ ++/* Define to 1 if you have that is POSIX.1 compatible. */ ++#undef HAVE_SYS_WAIT_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_SYS__MBSTATE_T_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_TERMCAP_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_TERMIOS_H ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_TERM_H ++ ++/* Define to 1 if you have the tiff library (-ltiff). */ ++#undef HAVE_TIFF ++ ++/* Define to 1 if `struct timeval' is declared by . */ ++#undef HAVE_TIMEVAL ++ ++/* Define to 1 if `tm_gmtoff' is member of `struct tm'. */ ++#undef HAVE_TM_GMTOFF ++ ++/* Define to 1 if your `struct tm' has `tm_zone'. Deprecated, use ++ `HAVE_STRUCT_TM_TM_ZONE' instead. */ ++#undef HAVE_TM_ZONE ++ ++/* Define to 1 if you have the `touchlock' function. */ ++#undef HAVE_TOUCHLOCK ++ ++/* Define to 1 if you don't have `tm_zone' but do have the external array ++ `tzname'. */ ++#undef HAVE_TZNAME ++ ++/* Define to 1 if you have the `tzset' function. */ ++#undef HAVE_TZSET ++ ++/* Define to 1 if you have the `ualarm' function. */ ++#undef HAVE_UALARM ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_UNISTD_H ++ ++/* Define to 1 if you have the `utimes' function. */ ++#undef HAVE_UTIMES ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_UTIME_H ++ ++/* Define to 1 if you have the `vfork' function. */ ++#undef HAVE_VFORK ++ ++/* Define to 1 if you have the header file. */ ++#undef HAVE_VFORK_H ++ ++/* Define to 1 if `fork' works. */ ++#undef HAVE_WORKING_FORK ++ ++/* Define to 1 if `vfork' works. */ ++#undef HAVE_WORKING_VFORK ++ ++/* Define to 1 if you want to use version 11 of X windows. Otherwise, Emacs ++ expects to use version 10. */ ++#undef HAVE_X11 ++ ++/* Define to 1 if you have the X11R6 or newer version of Xlib. */ ++#undef HAVE_X11R6 ++ ++/* Define to 1 if you have the X11R6 or newer version of Xt. */ ++#undef HAVE_X11XTR6 ++ ++/* Define to 1 if you have the Xaw3d library (-lXaw3d). */ ++#undef HAVE_XAW3D ++ ++/* Define to 1 if you have the Xft library. */ ++#undef HAVE_XFT ++ ++/* Define to 1 if XIM is available */ ++#undef HAVE_XIM ++ ++/* Define to 1 if you have the XkbGetKeyboard function. */ ++#undef HAVE_XKBGETKEYBOARD ++ ++/* Define to 1 if you have the Xpm libary (-lXpm). */ ++#undef HAVE_XPM ++ ++/* Define to 1 if you have the `XrmSetDatabase' function. */ ++#undef HAVE_XRMSETDATABASE ++ ++/* Define to 1 if you have the `XScreenNumberOfScreen' function. */ ++#undef HAVE_XSCREENNUMBEROFSCREEN ++ ++/* Define to 1 if you have the `XScreenResourceString' function. */ ++#undef HAVE_XSCREENRESOURCESTRING ++ ++/* Define to 1 if you have the `XSetWMProtocols' function. */ ++#undef HAVE_XSETWMPROTOCOLS ++ ++/* Define to 1 if you have the SM library (-lSM). */ ++#undef HAVE_X_SM ++ ++/* Define to 1 if you want to use the X window system. */ ++#undef HAVE_X_WINDOWS ++ ++/* Define to 1 if you have the `__fpending' function. */ ++#undef HAVE___FPENDING ++ ++/* Define to support using a Hesiod database to find the POP server. */ ++#undef HESIOD ++ ++/* Define to support Kerberos-authenticated POP mail retrieval. */ ++#undef KERBEROS ++ ++/* Define to use Kerberos 5 instead of Kerberos 4. */ ++#undef KERBEROS5 ++ ++/* Define LD_SWITCH_X_SITE to contain any special flags your loader may need ++ to deal with X Windows. For instance, if you've defined HAVE_X_WINDOWS ++ above and your X libraries aren't in a place that your loader can find on ++ its own, you might want to add "-L/..." or something similar. */ ++#undef LD_SWITCH_X_SITE ++ ++/* Define LD_SWITCH_X_SITE_AUX with an -R option in case it's needed (for ++ Solaris, for example). */ ++#undef LD_SWITCH_X_SITE_AUX ++ ++/* Compiler option to link with the gif library (if not -lgif). */ ++#undef LIBGIF ++ ++/* Define to 1 if localtime caches TZ. */ ++#undef LOCALTIME_CACHE ++ ++/* Define to support POP mail retrieval. */ ++#undef MAIL_USE_POP ++ ++/* Define to 1 if your `struct nlist' has an `n_un' member. Obsolete, depend ++ on `HAVE_STRUCT_NLIST_N_UN_N_NAME */ ++#undef NLIST_NAME_UNION ++ ++/* Define to 1 if you don't have struct exception in math.h. */ ++#undef NO_MATHERR ++ ++/* Define to 1 if `NSInteger' is defined. */ ++#undef NS_HAVE_NSINTEGER ++ ++/* Define to 1 if you are using NS windowing under MacOS X. */ ++#undef NS_IMPL_COCOA ++ ++/* Define to 1 if you are using NS windowing under GNUstep. */ ++#undef NS_IMPL_GNUSTEP ++ ++/* Define to the address where bug reports for this package should be sent. */ ++#undef PACKAGE_BUGREPORT ++ ++/* Define to the full name of this package. */ ++#undef PACKAGE_NAME ++ ++/* Define to the full name and version of this package. */ ++#undef PACKAGE_STRING ++ ++/* Define to the one symbol short name of this package. */ ++#undef PACKAGE_TARNAME ++ ++/* Define to the version of this package. */ ++#undef PACKAGE_VERSION ++ ++/* Define as `void' if your compiler accepts `void *'; otherwise define as ++ `char'. */ ++#undef POINTER_TYPE ++ ++/* Define to 1 if the C compiler supports function prototypes. */ ++#undef PROTOTYPES ++ ++/* Define REL_ALLOC if you want to use the relocating allocator for buffer ++ space. */ ++#undef REL_ALLOC ++ ++/* Define as the return type of signal handlers (`int' or `void'). */ ++#undef RETSIGTYPE ++ ++/* If using the C implementation of alloca, define if you know the ++ direction of stack growth for your system; otherwise it will be ++ automatically deduced at runtime. ++ STACK_DIRECTION > 0 => grows toward higher addresses ++ STACK_DIRECTION < 0 => grows toward lower addresses ++ STACK_DIRECTION = 0 => direction of growth unknown */ ++#undef STACK_DIRECTION ++ ++/* Define to 1 if you have the ANSI C header files. */ ++#undef STDC_HEADERS ++ ++/* Define to 1 on System V Release 4. */ ++#undef SVR4 ++ ++/* Process async input synchronously. */ ++#undef SYNC_INPUT ++ ++/* Define to 1 if you can safely include both and . */ ++#undef TIME_WITH_SYS_TIME ++ ++/* Define to 1 if your declares `struct tm'. */ ++#undef TM_IN_SYS_TIME ++ ++/* Define to 1 for Encore UMAX. */ ++#undef UMAX ++ ++/* Define to 1 for Encore UMAX 4.3 that has instead of ++ . */ ++#undef UMAX4_3 ++ ++/* Define to the unexec source file name. */ ++#undef UNEXEC_SRC ++ ++/* Define to 1 if using GTK. */ ++#undef USE_GTK ++ ++/* Define to 1 if using the Lucid X toolkit. */ ++#undef USE_LUCID ++ ++/* Define to 1 if using the Motif X toolkit. */ ++#undef USE_MOTIF ++ ++/* Define to 1 if we should use toolkit scroll bars. */ ++#undef USE_TOOLKIT_SCROLL_BARS ++ ++/* Define to 1 if we should use XIM, if it is available. */ ++#undef USE_XIM ++ ++/* Define to 1 if using an X toolkit. */ ++#undef USE_X_TOOLKIT ++ ++/* Define to the type of the 6th arg of XRegisterIMInstantiateCallback, either ++ XPointer or XPointer*. */ ++#undef XRegisterIMInstantiateCallback_arg6 ++ ++/* Define to 1 if on AIX 3. ++ System headers sometimes define this. ++ We just want to avoid a redefinition error message. */ ++#ifndef _ALL_SOURCE ++# undef _ALL_SOURCE ++#endif ++ ++/* Number of bits in a file offset, on hosts where this is settable. */ ++#undef _FILE_OFFSET_BITS ++ ++/* Enable GNU extensions on systems that have them. */ ++#ifndef _GNU_SOURCE ++# undef _GNU_SOURCE ++#endif ++ ++/* Define to 1 to make fseeko visible on some hosts (e.g. glibc 2.2). */ ++#undef _LARGEFILE_SOURCE ++ ++/* Define for large files, on AIX-style hosts. */ ++#undef _LARGE_FILES ++ ++/* Define to 1 if on MINIX. */ ++#undef _MINIX ++ ++/* Define to 2 if the system does not provide POSIX.1 features except with ++ this defined. */ ++#undef _POSIX_1_SOURCE ++ ++/* Define to 1 if you need to in order for `stat' and other things to work. */ ++#undef _POSIX_SOURCE ++ ++/* Enable extensions on Solaris. */ ++#ifndef __EXTENSIONS__ ++# undef __EXTENSIONS__ ++#endif ++#ifndef _POSIX_PTHREAD_SEMANTICS ++# undef _POSIX_PTHREAD_SEMANTICS ++#endif ++#ifndef _TANDEM_SOURCE ++# undef _TANDEM_SOURCE ++#endif ++ ++/* Define to rpl_ if the getopt replacement functions and variables should be ++ used. */ ++#undef __GETOPT_PREFIX ++ ++/* Define like PROTOTYPES; this can be used by system headers. */ ++#undef __PROTOTYPES ++ ++/* Define to compiler's equivalent of C99 restrict keyword. Don't define if ++ equivalent is `__restrict'. */ ++#undef __restrict ++ ++/* Define to compiler's equivalent of C99 restrict keyword in array ++ declarations. Define as empty for no equivalent. */ ++#undef __restrict_arr ++ ++/* Define to the used machine dependent file. */ ++#undef config_machfile ++ ++/* Define to the used os dependent file. */ ++#undef config_opsysfile ++ ++/* Define to empty if `const' does not conform to ANSI C. */ ++#undef const ++ ++/* Define to a type if does not define. */ ++#undef mbstate_t ++ ++/* Define to `int' if does not define. */ ++#undef pid_t ++ ++/* Define to any substitute for sys_siglist. */ ++#undef sys_siglist ++ ++/* Define as `fork' if `vfork' does not work. */ ++#undef vfork ++ ++/* Define to empty if the keyword `volatile' does not work. Warning: valid ++ code using `volatile' can become incorrect without. Disable with care. */ ++#undef volatile ++ ++ ++/* If we're using X11/Carbon/GNUstep, define some consequences. */ ++#if defined(HAVE_X_WINDOWS) || defined(HAVE_NS) ++#define HAVE_WINDOW_SYSTEM ++#define HAVE_MOUSE ++#endif ++ ++/* Define AMPERSAND_FULL_NAME if you use the convention ++ that & in the full name stands for the login id. */ ++/* Turned on June 1996 supposing nobody will mind it. */ ++#define AMPERSAND_FULL_NAME ++ ++/* Define HAVE_SOUND if we have sound support. We know it works ++ and compiles only on the specified platforms. For others, ++ it probably doesn't make sense to try. */ ++ ++#if defined __FreeBSD__ || defined __NetBSD__ || defined __linux__ ++#ifdef HAVE_MACHINE_SOUNDCARD_H ++#define HAVE_SOUND 1 ++#endif ++#ifdef HAVE_SYS_SOUNDCARD_H ++#define HAVE_SOUND 1 ++#endif ++#ifdef HAVE_SOUNDCARD_H ++#define HAVE_SOUND 1 ++#endif ++#ifdef HAVE_ALSA ++#define HAVE_SOUND 1 ++#endif ++#endif /* __FreeBSD__ || __NetBSD__ || __linux__ */ ++ ++/* If using GNU, then support inline function declarations. */ ++/* Don't try to switch on inline handling as detected by AC_C_INLINE ++ generally, because even if non-gcc compilers accept `inline', they ++ may reject `extern inline'. */ ++#if defined (__GNUC__) && defined (OPTIMIZE) ++#define INLINE __inline__ ++#else ++#define INLINE ++#endif ++ ++/* `subprocesses' should be defined if you want to ++ have code for asynchronous subprocesses ++ (as used in M-x compile and M-x shell). ++ Only MSDOS does not support this (it overrides ++ this in its config_opsysfile below). */ ++ ++#define subprocesses ++ ++/* Include the os and machine dependent files. */ ++#include config_opsysfile ++#include config_machfile ++ ++/* Set up some defines, C and LD flags for NeXTstep interface on GNUstep. ++ (There is probably a better place to do this, but right now the Cocoa ++ side does this in s/darwin.h and we cannot ++ parallel this exactly since GNUstep is multi-OS. */ ++#ifdef HAVE_NS ++#define OTHER_FILES ns-app ++# ifdef NS_IMPL_GNUSTEP ++/* See also .m.o rule in Makefile.in */ ++/* FIXME: are all these flags really needed? Document here why. */ ++# define C_SWITCH_X_SYSTEM -D_REENTRANT -fPIC -fno-strict-aliasing ++/* GNUstep needs a bit more pure memory. Of the existing knobs, ++SYSTEM_PURESIZE_EXTRA seems like the least likely to cause problems. */ ++# define SYSTEM_PURESIZE_EXTRA 30000 ++# endif /* NS_IMPL_GNUSTEP */ ++#endif /* HAVE_NS */ ++ ++/* SIGTYPE is the macro we actually use. */ ++#ifndef SIGTYPE ++#define SIGTYPE RETSIGTYPE ++#endif ++ ++#ifdef emacs /* Don't do this for lib-src. */ ++/* Tell regex.c to use a type compatible with Emacs. */ ++#define RE_TRANSLATE_TYPE Lisp_Object ++#define RE_TRANSLATE(TBL, C) CHAR_TABLE_TRANSLATE (TBL, C) ++#ifdef make_number ++/* If make_number is a macro, use it. */ ++#define RE_TRANSLATE_P(TBL) (!EQ (TBL, make_number (0))) ++#else ++/* If make_number is a function, avoid it. */ ++#define RE_TRANSLATE_P(TBL) (!(INTEGERP (TBL) && XINT (TBL) == 0)) ++#endif ++#endif ++ ++/* Avoid link-time collision with system mktime if we will use our own. */ ++#if ! HAVE_MKTIME || BROKEN_MKTIME ++#define mktime emacs_mktime ++#endif ++ ++#define my_strftime nstrftime /* for strftime.c */ ++ ++/* The rest of the code currently tests the CPP symbol BSTRING. ++ Override any claims made by the system-description files. ++ Note that on some SCO version it is possible to have bcopy and not bcmp. */ ++#undef BSTRING ++#if defined (HAVE_BCOPY) && defined (HAVE_BCMP) ++#define BSTRING ++#endif ++ ++/* Some of the files of Emacs which are intended for use with other ++ programs assume that if you have a config.h file, you must declare ++ the type of getenv. ++ ++ This declaration shouldn't appear when alloca.s or Makefile.in ++ includes config.h. */ ++#ifndef NOT_C_CODE ++extern char *getenv (); ++#endif ++ ++/* These default definitions are good for almost all machines. ++ The exceptions override them in m/MACHINE.h. */ ++ ++#ifndef BITS_PER_CHAR ++#define BITS_PER_CHAR 8 ++#endif ++ ++#ifndef BITS_PER_SHORT ++#define BITS_PER_SHORT 16 ++#endif ++ ++/* Note that lisp.h uses this in a preprocessor conditional, so it ++ would not work to use sizeof. That being so, we do all of them ++ without sizeof, for uniformity's sake. */ ++#ifndef BITS_PER_INT ++#define BITS_PER_INT 32 ++#endif ++ ++#ifndef BITS_PER_LONG ++#ifdef _LP64 ++#define BITS_PER_LONG 64 ++#else ++#define BITS_PER_LONG 32 ++#endif ++#endif ++ ++/* Define if the compiler supports function prototypes. It may do so ++ but not define __STDC__ (e.g. DEC C by default) or may define it as ++ zero. */ ++#undef PROTOTYPES ++/* For mktime.c: */ ++#ifndef __P ++# if defined PROTOTYPES ++# define __P(args) args ++# else ++# define __P(args) () ++# endif /* GCC. */ ++#endif /* __P */ ++ ++/* Don't include "string.h" or in non-C code. */ ++#ifndef NOT_C_CODE ++#ifdef HAVE_STRING_H ++#include "string.h" ++#endif ++#ifdef HAVE_STRINGS_H ++#include "strings.h" /* May be needed for bcopy & al. */ ++#endif ++#ifdef HAVE_STDLIB_H ++#include ++#endif ++#ifndef __GNUC__ ++# ifdef HAVE_ALLOCA_H ++# include ++# else /* AIX files deal with #pragma. */ ++# ifndef alloca /* predefined by HP cc +Olibcalls */ ++char *alloca (); ++# endif ++# endif /* HAVE_ALLOCA_H */ ++#endif /* __GNUC__ */ ++#ifndef HAVE_SIZE_T ++typedef unsigned size_t; ++#endif ++#endif /* NOT_C_CODE */ ++ ++/* Define HAVE_X_I18N if we have usable i18n support. */ ++ ++#ifdef HAVE_X11R6 ++#define HAVE_X_I18N ++#elif !defined X11R5_INHIBIT_I18N ++#define HAVE_X_I18N ++#endif ++ ++/* Define HAVE_X11R6_XIM if we have usable X11R6-style XIM support. */ ++ ++#if defined HAVE_X11R6 && !defined INHIBIT_X11R6_XIM ++#define HAVE_X11R6_XIM ++#endif ++ ++/* Should we enable expensive run-time checking of data types? */ ++#undef ENABLE_CHECKING ++ ++#if defined __GNUC__ && (__GNUC__ > 2 \ ++ || (__GNUC__ == 2 && __GNUC_MINOR__ >= 5)) ++#define NO_RETURN __attribute__ ((__noreturn__)) ++#else ++#define NO_RETURN /* nothing */ ++#endif ++ ++/* These won't be used automatically yet. We also need to know, at least, ++ that the stack is continuous. */ ++#ifdef __GNUC__ ++# ifndef GC_SETJMP_WORKS ++ /* GC_SETJMP_WORKS is nearly always appropriate for GCC -- ++ see NON_SAVING_SETJMP in the target descriptions. */ ++ /* Exceptions (see NON_SAVING_SETJMP in target description) are ++ SCO5 non-ELF (but Emacs specifies ELF) and SVR3 on x86. ++ Fixme: Deal with SVR3. */ ++# define GC_SETJMP_WORKS 1 ++# endif ++# ifndef GC_LISP_OBJECT_ALIGNMENT ++# define GC_LISP_OBJECT_ALIGNMENT (__alignof__ (Lisp_Object)) ++# endif ++#endif ++ ++#ifndef HAVE_BCOPY ++#define bcopy(a,b,s) memcpy (b,a,s) ++#endif ++#ifndef HAVE_BZERO ++#define bzero(a,s) memset (a,0,s) ++#endif ++#ifndef HAVE_BCMP ++#define BCMP memcmp ++#endif ++ ++#endif /* EMACS_CONFIG_H */ ++ ++/* ++Local Variables: ++mode: c ++End: ++*/ ++ --- emacs23-23.1+1.orig/debian/patches/avoid-fakemail-mail-loss.diff +++ emacs23-23.1+1/debian/patches/avoid-fakemail-mail-loss.diff @@ -0,0 +1,99 @@ +* An attempt is made to avoid silently losing mail via fakemail. + Patch: avoid-fakemail-mail-loss.diff + Author: Rob Browning + Added-by: Rob Browning + + This fix attempts to avoid a situation where Emacs can silently lose + mail. This can occur if sendmail.el (at least) falls back to + fakemail, and the underlying binary (MAIL_PROGRAM_NAME) that + fakemail is configured to use doesn't exist. Unless + mail-interactive is true, Emacs won't wait for the mailer and so + won't know that fakemail failed. + + For now, Debian sets fakemail's MAIL_PROGRAM_NAME to /usr/bin/mail + (which is the correct value for Debian systems) rather than + /bin/mail. Debian also adjusts Emacs to test whether or not + /usr/bin/mail exists and is executable. If either of these tests + fail, then mail-interactive is set to t. That should ensure that a + user will actually see an error if they attempt to use the broken + fakemail. + + Note that Debian actually forces the MAIL_PROGRAM_NAME value to + /usr/bin/mail. The build will fail if any other value is specified. + This is done to ensure that MAIL_PROGRAM_NAME isn't accidentally set + to some other value during the build process. If this is + undesirable for some reason, just comment out + avoid-fakemail-loss.diff in debian/patches/series. + +Index: b/lib-src/fakemail.c +=================================================================== +--- a/lib-src/fakemail.c ++++ b/lib-src/fakemail.c +@@ -136,8 +136,10 @@ + #define NIL ((line_list) NULL) + #define INITIAL_LINE_SIZE 200 + +-#ifndef MAIL_PROGRAM_NAME +-#define MAIL_PROGRAM_NAME "/bin/mail" ++#ifdef MAIL_PROGRAM_NAME ++#error "Debian assumption violated -- see avoid-fakemail-mail-loss.diff" ++#else ++#define MAIL_PROGRAM_NAME "/usr/bin/mail" + #endif + + static char *my_name; +Index: b/lisp/mail/feedmail.el +=================================================================== +--- a/lisp/mail/feedmail.el ++++ b/lisp/mail/feedmail.el +@@ -1323,7 +1323,12 @@ + "/usr/lib/sendmail") + ((file-exists-p "/usr/ucblib/sendmail") + "/usr/ucblib/sendmail") +- (t "fakemail")) ++ (t ++ (if (not (file-executable-p "/usr/bin/mail")) ++ (progn ++ (message "/usr/bin/mail is not an executable. Setting mail-interactive to t.") ++ (setq mail-interactive t))) ++ "fakemail")) + nil errors-to nil "-oi" "-t") + ;; provide envelope "from" to sendmail; results will vary + (list "-f" user-mail-address) +Index: b/lisp/mail/sendmail.el +=================================================================== +--- a/lisp/mail/sendmail.el ++++ b/lisp/mail/sendmail.el +@@ -52,7 +52,12 @@ + ((file-exists-p "/usr/sbin/sendmail") "/usr/sbin/sendmail") + ((file-exists-p "/usr/lib/sendmail") "/usr/lib/sendmail") + ((file-exists-p "/usr/ucblib/sendmail") "/usr/ucblib/sendmail") +- (t "fakemail")) ;In ../etc, to interface to /bin/mail. ++ (t ++ (if (not (file-executable-p "/usr/bin/mail")) ++ (progn ++ (message "/usr/bin/mail is not an executable. Setting mail-interactive to t.") ++ (setq mail-interactive t))) ++ "fakemail")) ;In ../etc, to interface to /bin/mail. + "Program used to send messages." + :group 'mail + :type 'file) +Index: b/lisp/gnus/message.el +=================================================================== +--- a/lisp/gnus/message.el ++++ b/lisp/gnus/message.el +@@ -4520,7 +4520,13 @@ + "/usr/lib/sendmail") + ((file-exists-p "/usr/ucblib/sendmail") + "/usr/ucblib/sendmail") +- (t "fakemail")) ++ (t ++ (if (not (file-executable-p ++ "/usr/bin/mail")) ++ (progn ++ (message "/usr/bin/mail is not an executable. Setting mail-interactive to t.") ++ (setq mail-interactive t))) ++ "fakemail")) + nil errbuf nil "-oi") + message-sendmail-extra-arguments + ;; Always specify who from, --- emacs23-23.1+1.orig/debian/patches/fix-rmail-capitalized-month-names.diff +++ emacs23-23.1+1/debian/patches/fix-rmail-capitalized-month-names.diff @@ -0,0 +1,40 @@ +* Rmail can now handle capitilized month names. + Patch: fix-rmail-capitalized-month-names.diff + Provided-by: Sven Joachim + Originally-reported-by: Jeroen Nijhof + Date: Thu, 06 Aug 2009 22:51:47 +0200 + Added-by: Rob Browning + Status: incorporated upstream + Bug: 540234 + + Rmail can not handle Date lines that have a capitalized month name + like "Date: Thu, 06 Aug 2009 18:33:32 +0100". + +Index: b/lisp/mail/rmailsum.el +=================================================================== +--- a/lisp/mail/rmailsum.el ++++ b/lisp/mail/rmailsum.el +@@ -518,16 +518,19 @@ + (concat (save-excursion + (if (not (re-search-forward "^Date:" nil t)) + " " +- (cond ((re-search-forward "\\([^0-9:]\\)\\([0-3]?[0-9]\\)\\([- \t_]+\\)\\([adfjmnos][aceopu][bcglnprtvy]\\)" +- (line-end-position) t) ++ ;; Match month names case-insensitively ++ (cond ((let ((case-fold-search t)) ++ (re-search-forward "\\([^0-9:]\\)\\([0-3]?[0-9]\\)\\([- \t_]+\\)\\([adfjmnos][aceopu][bcglnprtvy]\\)" ++ (line-end-position) t)) + (format "%2d-%3s" + (string-to-number (buffer-substring + (match-beginning 2) + (match-end 2))) + (buffer-substring + (match-beginning 4) (match-end 4)))) +- ((re-search-forward "\\([^a-z]\\)\\([adfjmnos][acepou][bcglnprtvy]\\)\\([-a-z \t_]*\\)\\([0-9][0-9]?\\)" +- (line-end-position) t) ++ ((let ((case-fold-search t)) ++ (re-search-forward "\\([^a-z]\\)\\([adfjmnos][acepou][bcglnprtvy]\\)\\([-a-z \t_]*\\)\\([0-9][0-9]?\\)" ++ (line-end-position) t)) + (format "%2d-%3s" + (string-to-number (buffer-substring + (match-beginning 4) --- emacs23-23.1+1.orig/debian/patches/version-mention-debian.diff +++ emacs23-23.1+1/debian/patches/version-mention-debian.diff @@ -0,0 +1,20 @@ +* The output of (version) has been modified to indicate Debian modifications. + Patch: version-mention-debian.diff + Author: Rob Browning + Added-by: Rob Browning + +Index: b/lisp/version.el +=================================================================== +--- a/lisp/version.el ++++ b/lisp/version.el +@@ -57,8 +57,8 @@ + (interactive "P") + (let ((version-string + (format (if (not (interactive-p)) +- "GNU Emacs %s (%s%s%s)\n of %s on %s" +- "GNU Emacs %s (%s%s%s) of %s on %s") ++ "GNU Emacs %s (%s%s%s)\n of %s on %s, modified by Debian" ++ "GNU Emacs %s (%s%s%s) of %s on %s, modified by Debian") + emacs-version + system-configuration + (cond ((featurep 'motif) --- emacs23-23.1+1.orig/debian/patches/series +++ emacs23-23.1+1/debian/patches/series @@ -0,0 +1,13 @@ +ubuntu-restore-nondfsg-files.diff +debian-site-init-el.diff +debian-startup.diff +debian-adjust-mail-from-addresses.diff +misc-unseparated.diff +require-movemail-use-liblockfile.diff +avoid-fakemail-mail-loss.diff +version-mention-debian.diff +look-for-news-to-find-etc.diff +fix-flymake-xmlstarlet-invocation.diff +fix-rmail-capitalized-month-names.diff +fix-dynamic-menus.diff +autofiles.diff --- emacs23-23.1+1.orig/debian/patches/fix-flymake-xmlstarlet-invocation.diff +++ emacs23-23.1+1/debian/patches/fix-flymake-xmlstarlet-invocation.diff @@ -0,0 +1,24 @@ +* Emacs now invokes the correct xmlstarlet executable on Debian systems. + Patch: fix-flymake-xmlstarlet-invocation.diff + Provided-by: Jussi Judin + Date: Sat, 20 Oct 2007 14:42:02 UTC + Added-by: Rob Browning + Status: Debian specific + Bug: 447378 + + Emacs invokes xmlstarlet rather than xml, which is the correct + executable name on Debian systems. + +Index: b/lisp/progmodes/flymake.el +=================================================================== +--- a/lisp/progmodes/flymake.el ++++ b/lisp/progmodes/flymake.el +@@ -1754,7 +1754,7 @@ + + ;;;; xml-specific init-cleanup routines + (defun flymake-xml-init () +- (list "xml" (list "val" (flymake-init-create-temp-buffer-copy 'flymake-create-temp-inplace)))) ++ (list "xmlstarlet" (list "val" (flymake-init-create-temp-buffer-copy 'flymake-create-temp-inplace)))) + + (provide 'flymake) + --- emacs23-23.1+1.orig/debian/patches/debian-site-init-el.diff +++ emacs23-23.1+1/debian/patches/debian-site-init-el.diff @@ -0,0 +1,23 @@ +* Emacs will prefer /usr/share/info/emacs-23 over /usr/share/info. + Patch: debian-site-init-el.diff + + The value of Info-default-directory-list has been augmented via + site-init.el to include /usr/share/info/emacs-23 before + /usr/share/info. + +Index: b/lisp/site-init.el +=================================================================== +--- /dev/null ++++ b/lisp/site-init.el +@@ -0,0 +1,11 @@ ++ ++;; Add the flavor specific directory for Debian. ++(setq Info-default-directory-list ++ (let ((result nil) ++ (found-match nil)) ++ (dolist (elt Info-default-directory-list (nreverse result)) ++ (if (and (not found-match) (equal elt "/usr/share/info/")) ++ (progn ++ (push "/usr/share/info/emacs-23" result) ++ (setq found-match t))) ++ (push elt result)))) --- emacs23-23.1+1.orig/debian/patches/look-for-news-to-find-etc.diff +++ emacs23-23.1+1/debian/patches/look-for-news-to-find-etc.diff @@ -0,0 +1,33 @@ +* Emacs will now look for NEWS in order to find etc/ rather than GNU. + Patch: look-for-news-to-find-etc.diff + Provided-by: Sven Joachim + Originally-reported-by: Bernhard Michler + Date: Mon, 28 Apr 2008 11:20:23 +0200 + Added-by: Rob Browning + Status: Debian specific + + Since Debian doesn't include GNU in the Debian packages (the common + licenses are in /usr/share/common-licenses), Emacs will now look for + NEWS to find the etc directory instead of GNU. + +Index: b/src/callproc.c +=================================================================== +--- a/src/callproc.c ++++ b/src/callproc.c +@@ -1521,14 +1521,14 @@ + + srcdir = Fexpand_file_name (build_string ("../src/"), + build_string (PATH_DUMPLOADSEARCH)); +- tem = Fexpand_file_name (build_string ("GNU"), Vdata_directory); ++ tem = Fexpand_file_name (build_string ("NEWS"), Vdata_directory); + tem1 = Ffile_exists_p (tem); + if (!NILP (Fequal (srcdir, Vinvocation_directory)) || NILP (tem1)) + { + Lisp_Object newdir; + newdir = Fexpand_file_name (build_string ("../etc/"), + build_string (PATH_DUMPLOADSEARCH)); +- tem = Fexpand_file_name (build_string ("GNU"), newdir); ++ tem = Fexpand_file_name (build_string ("NEWS"), newdir); + tem1 = Ffile_exists_p (tem); + if (!NILP (tem1)) + Vdata_directory = newdir; --- emacs23-23.1+1.orig/debian/patches/ubuntu-restore-nondfsg-files.diff +++ emacs23-23.1+1/debian/patches/ubuntu-restore-nondfsg-files.diff @@ -0,0 +1,345729 @@ +* Restore non-DFSG files and documentation. + +diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog +new file mode 100644 +index 0000000..cc6715b +--- /dev/null ++++ b/doc/emacs/ChangeLog +@@ -0,0 +1,6809 @@ ++2009-07-29 Chong Yidong ++ ++ * Version 23.1 released. ++ ++2009-07-28 Chong Yidong ++ ++ * building.texi (Lisp Libraries): Clarify meaning of autoloading. ++ ++2009-07-22 Richard Stallman ++ ++ * glossary.texi (GNU, Daemon): Update information. ++ ++2009-07-21 Chong Yidong ++ ++ * frames.texi (Cut/Paste Other App): Remove discussion of ++ select-active-regions for 23.1, as it is not fully functional. ++ ++2009-07-15 Chong Yidong ++ ++ * macos.texi (Mac OS / GNUstep): Add note about stability. ++ ++2009-07-15 Glenn Morris ++ ++ * misc.texi (Gnus): Remove widow. ++ ++2009-07-11 Glenn Morris ++ ++ * arevert-xtra.texi (Autorevert): Add menu descriptions. ++ ++ * display.texi (Horizontal Scrolling): Re-word to remove widow. ++ ++ * emacs.texi (Top): Info can be read from other places than Emacs. ++ Don't print the copying notice twice in the printed version. ++ Update the menu and detailmenu. ++ (Preface): The meaning of "on-line" has changed. ++ Correct name for "Common Problems" chapter. ++ (Distrib): Update FSF shop URL. ++ (Intro): Showing two files at once is not so exciting. ++ ++ * macos.texi (Mac OS / GNUstep): Fix spelling and cross-reference. ++ (Mac / GNUstep Basics): Minor grammar changes. ++ (Mac / GNUstep Events): Fix typo. ++ (GNUstep Support): CANNOT_DUMP no longer applies. ++ ++ * misc.texi (Document View): Fix typos. ++ ++ * dired.texi (Dired): ++ * help.texi (Help): ++ * macos.texi (Mac OS / GNUstep): ++ * maintaining.texi (Version Control, Introduction to VC): ++ End menu descriptions with a period. ++ ++2009-07-10 Eli Zaretskii ++ ++ * msdog.texi (Windows Files) : Don't be ++ so categorical in saying that the option is only useful on NTFS. ++ ++2009-07-09 Glenn Morris ++ ++ * Makefile.in (texinfodir): New variable, with location of texinfo.tex. ++ (ENVADD): Add texinfodir to TEXINPUTS. ++ ++ * emacs.texi (Top): Fix cross-reference. ++ ++ * maintaining.texi (VC Directory Buffer): Fix cross-reference. ++ ++ * vc1-xtra.texi (Revision Tags): Fix typo. ++ ++2009-07-03 Glenn Morris ++ ++ * emerge-xtra.texi (Emerge): Tweak Misc menu description. ++ (Submodes of Emerge): Skip Prefers is only relevant with an ancestor. ++ (Merge Commands): `.' does not seem to work in A or B buffer. ++ `l' can recreate the 3-window display. ++ ++ * glossary.texi (Glossary): Minor phrasing changes throughout. ++ Add more internal cross-references. ++ : You can't really autoload a variable. ++ : Move details here from `M-C-' item. ++ : Refer to `Truncation.' ++ : ++ : New entries. ++ : Mention recycle bins. ++ : Mention ``folders.'' ++ : Don't mention ``type-ahead.'' ++ : Refer to the manual node. ++ : Can be global or local. ++ : There are other checkers besides Ispell. ++ ++2009-07-02 Glenn Morris ++ ++ * anti.texi (Antinews): Minor changes in phrasing. ++ ++ * cal-xtra.texi, fortran-xtra.texi: Re-order a few things to reduce ++ some underfull lines in dvi output. ++ ++ * emacs-xtra.texi (Introduction): Mention included in info Emacs manual. ++ ++ * sending.texi (Mail Sending): Add a tiny bit on mailclient. ++ ++ * vc-xtra.texi (Advanced VC Usage): End all menu items with a period. ++ ++2009-07-01 Chong Yidong ++ ++ * anti.texi (Antinews): Correct the list of removed platforms. ++ ++2009-06-28 Glenn Morris ++ ++ * arevert-xtra.texi: Minor language tweaks. ++ ++ * dired-xtra.texi: Minor revisions. ++ ++2009-06-17 Kenichi Handa ++ ++ * mule.texi (Charsets): Update the description for the new charset. ++ (list-character-sets): New findex. ++ (Language Environments): Add @anchor{Describe Language Environment}. ++ ++2009-06-10 Chong Yidong ++ ++ * basic.texi (Moving Point): Fix tag. ++ ++ * picture-xtra.texi (Insert in Picture): Use and . ++ ++ * mini.texi (Completion Commands): Decapitalize and , and ++ use camel-case for PageUp and PageDown. ++ ++ * display.texi (Scrolling): Decapitalize and , and use ++ camel-case for PageUp and PageDown. ++ ++ * calendar.texi (Scroll Calendar): Decapitalize and . ++ ++ * search.texi (Isearch Scroll): Add isearch-allow-scroll to index. ++ (Isearch Scroll): Decapitalize and . ++ ++2009-06-09 Agustín Martín ++ ++ * fixit.texi (Spelling): Set default dictionary. Improve ++ descriptions (Bug#2554) ++ ++2009-06-08 David Reitter ++ ++ * macos.texi (Color panel, Font panel): Remove mention of Save Options, ++ since saving colors and faces set this way is not implemented. ++ (Environment variables): Remove mention of mac-fix-env, which is ++ scheduled to be removed. ++ ++2009-06-04 Chong Yidong ++ ++ * custom.texi (Init Examples): Add example of changing load-path. ++ ++ * building.texi (Lisp Libraries): Add example of changing ++ load-path (Bug#3446). ++ ++2009-05-28 Chong Yidong ++ ++ * mark.texi (Mark): Further clarifications. ++ (Setting Mark): Emphasize that C-SPC activates the mark. ++ ++2009-05-28 Chong Yidong ++ ++ * mark.texi (Mark): Clarify introduction. Mention disabling Transient ++ Mark mode. ++ (Using Region, Persistent Mark): Use "active mark" instead of "active ++ region". ++ ++2009-05-16 Ari Roponen (tiny change) ++ ++ * mule.texi (Select Input Method): Fix typo. ++ ++2009-05-13 Chong Yidong ++ ++ * anti.texi (Antinews): Document completion changes. Some additional ++ copyedits and rearrangement of entries. ++ ++2009-05-12 Chong Yidong ++ ++ * misc.texi (Interactive Shell, Saving Emacs Sessions) ++ (Shell History Copying, Terminal emulator): Copyedits. ++ ++ * xresources.texi (Resources): Simplify descriptions. Shorten ++ description of editres, which is not very useful these days. ++ (Table of Resources): Document fontBackend resource. ++ ++ * trouble.texi (Quitting): Add other undo bindings to table. ++ (DEL Does Not Delete): Note that the erasure key is usually labelled ++ "Backspace". Remove discussion of obscure Xmodmap issue. ++ ++2009-05-07 Chong Yidong ++ ++ * files.texi (Visiting): Copyedits. ++ ++2009-05-06 Chong Yidong ++ ++ * basic.texi (Inserting Text): Document ucs-insert. ++ ++ * mule.texi (International Chars): Define "multibyte". Note that ++ internal representation is unicode-based. Simplify definition of raw ++ bytes. Mention ucs-insert. ++ (Enabling Multibyte): Remove obsolete discussion. Copyedits. ++ (Language Environments): Add language environments new to Emacs 23. ++ (Multibyte Conversion): Node deleted. ++ (Coding Systems): Remove obsolete unify-8859-on-decoding-mode. Don't ++ mention obsolete emacs-mule coding system. ++ (Output Coding): Copyedits. ++ ++ * emacs.texi (Top): Update node listing. ++ ++2009-05-05 Per Starbäck (tiny change) ++ ++ * trouble.texi (Lossage): Use new binding of view-emacs-problems. ++ ++2009-04-28 Stefan Monnier ++ ++ * building.texi (Lisp Libraries): `load-library' does offer completion. ++ ++2009-04-28 Chong Yidong ++ ++ * frames.texi (Text-Only Mouse): Mention gpm-mouse-mode instead of ++ t-mouse-mode. Suggested by Per Starbäck (Bug#3126). ++ ++2009-04-25 Eli Zaretskii ++ ++ * maintaining.texi (Tags): Clarify text. (Bug#3101) ++ ++2009-04-22 Chong Yidong ++ ++ * entering.texi (Entering Emacs): Document initial-buffer-choice. ++ ++ * building.texi (Lisp Interaction): Document initial-scratch-message. ++ ++2009-04-18 Juanma Barranquero ++ ++ * msdog.texi (Windows Fonts): Fix typos. ++ ++ * files.texi (Save Commands): Fix pxref. ++ ++2009-04-18 Chong Yidong ++ ++ * files.texi (Save Commands): Mention diff-buffer-with-file. ++ (Comparing Files): Document diff-buffer-with-file. Suggested by Magnus ++ Henoch (Bug#3036). ++ ++2009-03-15 Glenn Morris ++ ++ * sending.texi (Mail Format): Replace "Sender" with "Message-Id", since ++ the former is not always used. ++ (Mail Headers): Use active voice. Add "Mail-reply-to". ++ Change case of "Id". Avoid repeated "appropriate". ++ (Mail Aliases): Fix previous change - use an example with a ".", so it ++ does actually get quoted when expanded. ++ (Mail Sending): Mailclient is the default on some systems. ++ (Citing Mail): Mention mail-indentation-spaces. ++ (Mail Mode Misc): Add an @dfn for "mail signature". ++ ++2009-03-15 Chong Yidong ++ ++ * mini.texi (Completion Commands): Describe Emacs 23 completion rules. ++ (Completion Options): Document read-file-name-completion-ignore-case, ++ read-buffer-completion-ignore-case, and completion-styles. Remove ++ description of partial-completion-mode. ++ ++2009-03-14 Glenn Morris ++ ++ * sending.texi (Mail Format): Fix typo. Add index entry for ++ mail-header-separator. ++ (Mail Headers): Put info about initialization and changing in one place ++ at the start. Update FCC section for mbox Rmail. Clarify From ++ section, mention mail-setup-with-from. Clarify Reply-to section. ++ Add Mail-followup-to and mail-mailing-lists. Clarify References ++ section. ++ (Mail Aliases): Update example, make less contentious. ++ Update for name change of mail-interactive-insert-alias. ++ (Mail Mode): Remove mention of `%' as a word separator. ++ (Mail Sending): Mention mail-send-hook. Mention Mailclient. ++ (Header Editing): Add reply-to, mail-reply-to, and mail-followup-to ++ commands. Clarify FCC handling. In mail-complete, add reference to ++ Mail Aliases section, and mention mail-complete-function. ++ (Citing Mail): Mention mail-yank-ignored-headers and mail-citation-hook. ++ (Mail Mode Misc): Clarify the mail-signature function. Add basic ++ signature netiquette. Explain how the mail hooks work when continuing ++ a composition. ++ (Mail Amusements): Internationalize the spook section a bit. ++ Remove the spook mail-setup-hook example, since it doesn't work well. ++ Mention fortune-file. ++ (Mail Methods): Mention read-mail-command. ++ ++2009-03-14 David Reitter ++ ++ * macos.texi (Mac / GNUstep Basics): Remove references to Prefs panel ++ and NS resources following recent changes. ++ ++2009-03-10 Jason Rumney ++ ++ * msdog.texi (Windows Misc): Remove doc for obsolete variable. Modify ++ w32-use-visible-system-caret doc to indicate that it should get set ++ automatically. ++ (Windows Fonts): Add doc for the uniscribe backend. ++ ++2009-03-08 Dan Nicolaescu ++ ++ * maintaining.texi (VC Directory Commands): Fix doc for the x key in ++ vc-dir. (Bug#2598) ++ ++2009-03-05 Reiner Steib ++ ++ * fixit.texi (Spelling): Add turn-on-flyspell. (Bug#2517) ++ ++2009-03-05 Glenn Morris ++ ++ * rmail.texi (Rmail Basics): Add reference to sorting. ++ (Rmail Scrolling, Rmail Motion, Rmail Reply, Rmail Display): ++ Minor re-wordings. ++ (Rmail Motion): Mention rmail-next-same-subject. ++ (Rmail Deletion): Expunging is not the only way to change the numbers. ++ (Rmail Labels): Labels can also be used in sorting. ++ (Rmail Summary Edit): Mention rmail-summary-next-same-subject. ++ (Rmail Display): Mention rmail-mime. ++ ++2009-03-04 Glenn Morris ++ ++ * rmail.texi (Rmail Sorting): Add the keybindings associated with each ++ sort command. Fix `rmail-sort-by-labels' name. Mention sorting from ++ summary. Mention sorts cannot be undone. ++ (Rmail Display): Give an example of how to use goto-address-mode. ++ (Rmail Editing): It's keybindings that are redefined, not commands. ++ Fix some typos. ++ (Movemail): Some minor rewording. ++ (Remote Mailboxes): Emacs movemail supports pop by default. ++ Fix some minor grammatical issues. The "two alternative ways" to ++ specify a POP mailbox are really just one. Remove all reference to the ++ variables rmail-pop-password and rmail-pop-password-required, obsolete ++ since Emacs 22.1. Clarify the four password steps. Emacs movemail ++ can support Kerberos. ++ ++2009-03-03 Glenn Morris ++ ++ * rmail.texi (Rmail Deletion): Revert previous change, which was ++ describing the Rmail summary versions. ++ (Rmail Reply): Give more details of rmail-dont-reply-to-names. ++ Minor re-wording for rmail-resend. ++ (Rmail Make Summary): Summaries apply to buffers rather than files. ++ : Headers includes the subject. ++ : Give more ++ details, including prefix arguments. ++ Mention rmail-summary-by-senders on C-M-f. ++ Not counting lines might be faster. ++ (Rmail Summary Edit): More details on the delete commands. ++ Mention rmail-summary-undelete-many, rmail-summary-bury, and C-M-n/p. ++ Name the commands bound to the various keys. Mention prefix argument ++ for searching. ++ (Rmail Display): Mention rmail-displayed-headers. Fix typo. ++ Simplify rmail-highlighted-headers description. Update face name. ++ ++2009-03-02 Juanma Barranquero ++ ++ * mark.texi (Marking Objects): Fix typo. ++ ++2009-03-01 Chong Yidong ++ ++ * abbrevs.texi (Expanding Abbrevs): Mention abbrev-expand-functions ++ instead of obsolete pre-abbrev-expand-hook. Link to elisp manual. ++ ++2009-03-01 Glenn Morris ++ ++ * rmail.texi (Rmail): Fix some typos. Use consistent case in menu. ++ (Rmail Motion): - M-s searches from the end of messages. ++ (Rmail Deletion): Minor clarification. Fix numeric argument ++ description. ++ (Rmail Inbox): Fix default inbox description. Mention `mbox' by name. ++ newmail and RMAILOSE files need not be in home-directory. ++ (Rmail Files): Mention I/O menus are unselectable if no files match. ++ Mention `MAIL' env-var. ++ ++2009-02-24 Jason Rumney ++ ++ * mule.texi (Fontsets): Mention fontset-default, font specs and ++ fallback fontsets. ++ (Defining Fontsets): Mention ns and w32 variants of ++ standard-fontset-spec. Update description of startup fontset to match ++ Emacs 23 behavior. ++ (Modifying Fontsets): New section. (Bug#656) ++ (International): Link to Modifying Fontsets. ++ ++2009-02-23 Adrian Robert ++ ++ * macos.texi (Mac / GNUstep Basics, Mac / GNUstep Customization): ++ Mention ns-extended-platform-support-mode. ++ ++2009-02-22 Karl Berry ++ ++ * macos.texi (Mac / GNUstep Customization): One more duplicate "the". ++ ++2009-02-19 Juanma Barranquero ++ ++ * basic.texi (Moving Point, Position Info): ++ * files.texi (Visiting): ++ * mini.texi (Completion Options): ++ * text.texi (HTML Mode): Remove duplicate words. ++ ++2009-02-20 Glenn Morris ++ ++ * rmail.texi: Minor updates for mbox rather than Babyl. ++ ++2009-02-17 Karl Berry ++ ++ * emacs.texi (Top): Add @insertcopying before master menu. (Bug#1988) ++ ++2009-02-17 Richard M Stallman ++ ++ * anti.texi (Antinews): Mention Babyl format. ++ ++ * emacs.texi (Top): Delete `Out of Rmail' from subnode menu. ++ ++ * rmail.texi: Update for mbox format. ++ Various small fixes, as well as the following. ++ (Out of Rmail): Node deleted. ++ (Rmail): Update menu. ++ (Rmail Files): Comment out set-rmail-inbox-list. ++ Document rmail-inbox-list instead. ++ (Rmail Output): Substantial changes since C-o is now ++ rmail-output-as-seen and o is rmail-output. ++ (Rmail Attributes): Delete `stored', add `retried'. ++ (Rmail Display): Editing headers works in all cases. ++ ++2009-02-17 Glenn Morris ++ ++ * basic.texi (Position Info): M-x count-lines-region is not always on ++ M-=. (Bug#2269) ++ ++2009-02-09 Glenn Morris ++ ++ * calendar.texi (Holidays, Displaying the Diary): Update for new marker ++ defaults. ++ ++2009-02-07 Eli Zaretskii ++ ++ * rmail.texi (Rmail Coding) : Remove stale ++ documentation of possible problems with redecoding. ++ ++2009-02-03 Glenn Morris ++ ++ * rmail.texi (Out of Rmail): Mention b2m.pl. ++ ++2009-01-31 Glenn Morris ++ ++ * rmail.texi (Out of Rmail): Correct b2m location. ++ ++2009-01-27 Chong Yidong ++ ++ * fixit.texi (Undo): Update undo limit values. ++ ++2009-01-27 Glenn Morris ++ ++ * emacs.texi (Top): Fix Antinews menu entry. ++ ++2009-01-25 Karl Berry ++ ++ * text.texi (Foldout): Use @itemize @w{} to make an itemize ++ item with no marker, instead of the syntactically incorrect ++ @itemize @asis. ++ ++2009-01-25 Juri Linkov ++ ++ * building.texi (Grep Searching): Fix index entry for lgrep. ++ ++2009-01-24 Eli Zaretskii ++ ++ * msdog.texi (Windows Printing): Add an index entry for Ghostscript. ++ ++2009-01-21 Adrian Robert ++ ++ * macos.texi (Preferences Panel): Update description of font setting to ++ reflect that prior frame selection is no longer needed. ++ ++2009-01-20 Nick Roberts ++ ++ * building.texi (Debuggers): Revert some of 2008-10-31 change to ++ raise GUD subsections. ++ ++2009-01-15 Glenn Morris ++ ++ * ack.texi (Acknowledgments): Another update based mainly on AUTHORS. ++ ++2009-01-10 Glenn Morris ++ ++ * ack.texi (Acknowledgments): Some more updates based on AUTHORS. ++ ++2009-01-04 Chong Yidong ++ ++ * display.texi (Visual Line Mode): M-] and M-[ no longer move by ++ logical lines. ++ ++2008-12-29 Juri Linkov ++ ++ * mini.texi (Minibuffer History): Add a link to `Isearch Minibuffer'. ++ ++ * text.texi (Fill Commands): Replace `M-s' with `M-o M-s'. ++ ++2008-12-28 Chong Yidong ++ ++ * misc.texi (Goto Address mode): Rename from Goto-address. Refer to ++ goto-address-mode instead of goto-address. ++ ++ * rmail.texi (Rmail Display): Goto-address renamed to Goto Address ++ mode. ++ ++ * emacs.texi (Top): Update node listing. ++ ++2008-12-26 Eli Zaretskii ++ ++ * custom.texi (Directory Variables): Explain what is a "project". ++ Add indexing. Improve wording. Add a footnote about using ++ _dir-locals.el on MS-DOS. ++ ++2008-12-24 Dan Nicolaescu ++ ++ * files.texi (Misc File Ops): Mention chmod as an alias for ++ set-file-modes. ++ ++2008-12-24 Martin Rudalics ++ ++ * help.texi (Help): Fix typos and reword. ++ (Help Summary): Add entries for C-h n and C-h r, reorder ++ entries, and do some minor fixes. ++ (Name Help): Say that C-h F works for commands only. ++ (Misc Help): Say that view-lossage displays 300 keystrokes. ++ ++2008-12-20 Glenn Morris ++ ++ * ack.texi (Acknowledgments): General update based on AUTHORS, ++ including removal of some stuff no longer distributed. ++ ++2008-12-19 Agustin Martin ++ ++ * fixit.texi: Mention hunspell ++ ++2008-12-19 Glenn Morris ++ ++ * ack.texi (Acknowledgments): Small grammar fix. ++ Consolidate explanatory text at start. ++ ++ * display.texi (Text Display): ++ * indent.texi (Indentation): Use @acronym with ASCII. ++ ++2008-12-18 Glenn Morris ++ ++ * ack.texi: Various small updates and fixes. ++ ++2008-12-18 Juri Linkov ++ ++ * search.texi (Word Search): Replace `C-s RET C-w' with `M-s w RET' ++ as a key binding to start a forward nonincremental word search. ++ Replace `C-r RET C-w' with `M-s w C-r RET' as a key binding to start ++ a backward nonincremental word search. Add index for `M-s w' ++ `isearch-forward-word'. ++ (Regexp Search): Add a short summary of regexp key commands like ++ in the node "Basic Isearch". ++ (Other Repeating Search): Fix typo. ++ ++2008-12-14 Vinicius Jose Latorre ++ ++ * misc.texi (PostScript Variables): Fix doc. ++ ++2008-12-10 Chong Yidong ++ ++ * programs.texi (Program Modes): Mention Ruby mode. ++ ++2008-12-10 Dan Nicolaescu ++ ++ * misc.texi (emacsclient Options): Describe what an empty string ++ argument does for --alternate-editor. ++ ++2008-12-09 Frank Schmitt ++ ++ * cmdargs.texi (Font X): Distinguish between client-side and ++ server-side fonts. List valid Fontconfig properties. Add reference to ++ Fontconfig manual. List valid GTK font properties. Explain use of ++ fc-list. ++ ++2008-12-09 Chong Yidong ++ ++ * cmdargs.texi (Font X): Move discussion of quoting to top. ++ ++2008-12-06 Glenn Morris ++ ++ * maintaining.texi (Old Revisions): Improve previous change. ++ ++2008-12-05 Richard M Stallman ++ ++ * anti.texi (Antinews): Minor fixes. ++ ++2008-12-03 Glenn Morris ++ ++ * maintaining.texi (Old Revisions): Fix diff-switches description. ++ ++2008-12-01 Martin Rudalics ++ ++ * emacs.texi (Top): Fix typo. ++ ++2008-11-30 Chong Yidong ++ ++ * misc.texi (Document View): Explain dependence on gs at the top. ++ Copyedits. ++ ++ * emacs.texi (Top): Add DocView nodes to detailed node listing. ++ ++ * programs.texi (Other C Commands): Document hide-ifdef-shadow. ++ (Comment Commands): Discuss region-active behavior of M-; first. ++ ++2008-11-29 Martin Rudalics ++ ++ * display.texi (Line Truncation): Add reference to Continuation ++ Lines. ++ ++ * windows.texi (Pop Up Window): Mention split-height-threshold ++ and split-width-threshold. ++ (Split Window): Add reference to Continuation Lines. ++ ++2008-11-28 Adrian Robert ++ ++ * macos.texi: Change references to "Mac" to "Mac / GNUstep". ++ (GNUstep Support): New node. ++ * anti.texi: ++ * emacs.texi: ++ * msdog.texi: Change reference to Mac OS node to Mac OS / GNUstep. ++ ++ ++2008-11-28 Richard M Stallman ++ ++ * misc.texi (Dissociated Press): Minor cleanups. ++ ++ * dired.texi (Image-Dired): Avoid passive. ++ ++2008-11-28 Eli Zaretskii ++ ++ * anti.texi (Antinews): Add stuff about Unicode vs emacs-mule ++ representation. ++ ++2008-11-26 Richard M. Stallman ++ ++ * files.texi (Visiting): Rewrite paragraph for clarity. ++ ++ * buffers.texi (Select Buffer): Rewrite paragraphs using active voice. ++ ++2008-11-25 Alan Mackenzie ++ ++ * programs.texi (Moving by Parens): Clarify that parens inside strings ++ and comments are ignored, and that the commands assume the starting ++ point isn't in a string or comment. ++ ++2008-11-26 Adrian Robert ++ ++ * macos.texi: Add Prev/Next/Top pointers to all nodes. ++ (Mac Basics): Merge in Grabbing Environment Variables from earlier ++ version. ++ (Mac Customization): Rewrite Preferences Panel section and merge in to ++ this node, add Open files by dragging to an Emacs window. ++ ++ * emacs.texi: Remove TOC reference to Mac Preferences Panel section. ++ ++2008-11-26 Chong Yidong ++ ++ * files.texi (Misc File Ops): Document set-file-modes. ++ ++ * windows.texi (Split Window): Document integer values of ++ truncate-partial-width-windows. ++ ++ * text.texi (Text): Simplify description of markup languages. ++ (TeX Mode): Simplify introduction. Mention BibTeX mode. ++ (TeX Editing): Note that `""' inserts one `"' character. ++ (HTML Mode): Note in the introduction that XML mode is an alias for ++ SGML mode. Mention nXML mode. ++ ++2008-11-25 Chong Yidong ++ ++ * building.texi (Watch Expressions): Fix typo. ++ ++2008-11-24 Chong Yidong ++ ++ * files.texi (Visiting): Document new behavior of ++ confirm-nonexistent-file-or-buffer. ++ ++ * buffers.texi (Select Buffer): Document ++ confirm-nonexistent-file-or-buffer. ++ ++ * picture-xtra.texi (Picture Mode): Use picture-mode instead of ++ edit-picture. ++ ++ * text.texi (Text): Simplify introduction. Discard mention of `M-x ++ edit-picture', since that is just an alias for picture-mode. ++ (Sentences): Note that repeated M-@ extends the region. ++ (Pages): Make terminology more consistent. Link to Regexps node. ++ (Longlines): Discuss relationship with Visual Line mode. ++ (Text Mode): Remove extraneous discussion of other modes, since they ++ were already introduced in the parent node. ++ ++2008-11-23 Chong Yidong ++ ++ * anti.texi (Antinews): Rewrite. ++ ++ * entering.texi (Exiting): Mention "minimize" terminology. ++ ++ * frames.texi (Frame Commands): Mention "minimize" terminology. ++ ++ * cmdargs.texi (Font X): Document Fontconfig and GTK font specification ++ formats. ++ (Icons X): Mention "minimize" terminology and use of icons in taskbar. ++ (Misc X): Don't document useless -hb option. ++ ++2008-11-22 Juri Linkov ++ ++ * dired.texi (Dired Navigation): Change normal file name search option ++ from `non-nil' to `t'. Add `dwim' option. ++ ++2008-11-22 Juri Linkov ++ ++ * custom.texi (Directory Variables): Rename ".dir-settings.el" to ++ ".dir-locals.el". Rename `define-project-bindings' to ++ `dir-locals-set-class-variables'. Rename `set-directory-project' to ++ `dir-locals-set-directory-class'. ++ ++2008-11-22 Lute Kamstra ++ ++ * buffers.texi (Select Buffer): Index goto-line. ++ * basic.texi (Moving Point): Mention the use of a numeric prefix ++ argument with goto-line and refer to Select Buffer for the use of a ++ plain prefix argument. ++ ++2008-11-19 Glenn Morris ++ ++ * doclicense.texi: Update to FDL 1.3. ++ * emacs.texi, emacs-xtra.texi: Relicense under FDL 1.3 or later. ++ ++2008-11-17 Chong Yidong ++ ++ * custom.texi (Minor Modes): Define mode commands and mode variables ++ more precisely. Recommend using mode commands instead of setting ++ variables directly. Put minor modes in a list, and add more modes. ++ (Easy Customization): Use "init file" instead of .emacs. ++ (Customization Groups): Update to new Custom buffer appearance. ++ (Saving Customizations): Copyedits. Update example. ++ (Variables): Give example of variable type-sensitivity. ++ (Examining): Update example. ++ (Hooks): Copyedits. ++ (Specifying File Variables): Use C comments instead of an artificial ++ Lisp for the example. ++ (Keymaps): Move internals discussion to Prefix Keymaps. ++ (Rebinding): Remove redundant paragraph (stated in Key Binding). ++ (Init Rebinding): Document kbd macro. ++ (Init File): Link to Find Init. ++ ++ * mark.texi (Using Region): Document Delete Selection Mode more ++ thoroughly. ++ ++ * frames.texi (Mouse Commands): Move most of the description of Delete ++ Selection Mode to Using Region, and link to it. ++ (Clipboard): Note that paste is bound to clipboard-yank. ++ ++ * building.texi (Compilation): Document first-error value of ++ compilation-scroll-output. ++ (Compilation Mode): Note that compilation-auto-jump-to-first-error ++ works as soon as an error is available. Suggested by Juri Linkov. ++ ++ * mini.texi (Passwords): New node. ++ ++ * files.texi (Remote Files): Link to Passwords node. ++ ++ * emacs.texi (Top): Update node listings. ++ ++2008-11-16 Chong Yidong ++ ++ * ack.texi (Acknowledgments): Some updating of credits. ++ ++ * emacs.texi (Acknowledgments): Add a couple more names. ++ ++ * dired.texi (Dired Deletion): Document delete-by-moving-to-trash. ++ ++ * files.texi (Directories): Describe delete-directory in text. ++ (Misc File Ops): Document use of trash. ++ ++2008-11-16 Juanma Barranquero ++ ++ * macos.texi (Mac Customization): Fix typos. ++ ++2008-11-14 Chong Yidong ++ ++ * macos.texi (Mac OS): Move Cocoa manual from ns-emacs.texi to here, ++ replacing previous contents. Numerous copyedits to adapt ns-emacs to ++ the conventions of the main Emacs manual. ++ ++ * emacs.texi (Top): Update node listings. ++ ++2008-11-12 Chong Yidong ++ ++ * cmdargs.texi (Emacs Invocation): Link to Emacs Server. Note that ++ command-line-args is processed during startup. ++ (Action Arguments): Correctly describe how file arguments interact with ++ the startup screen. Link to Lisp Interaction for scratch buffer. ++ (Initial Options): Link to Command Example for -batch option. ++ (Environment): Document initial-environment. ++ ++ * entering.texi (Entering Emacs): Note that inhibit-startup-screen ++ can't be changed in the site-start file. ++ ++2008-11-07 Chong Yidong ++ ++ * dired.texi (Dired): Mention C-x C-d too. ++ (Dired Enter): Document M-n in the Dired minibuffer. ++ (Dired Navigation): Explain dired-goto-file more clearly. Document ++ dired-isearch-filenames. ++ (Dired Deletion): Remove unnecessary "expunged" terminology. ++ (Flagging Many Files): & is now rebound to `% &'. ++ (Shell Commands in Dired): Document dired-do-async-shell-command. ++ Clarify how multi-file arguments are passed. ++ (Misc Dired Features): Document dired-do-isearch. ++ ++2008-11-06 Chong Yidong ++ ++ * entering.texi (Entering Emacs): Document inhibit-startup-screen. ++ ++2008-11-03 Chong Yidong ++ ++ * search.texi (Other Repeating Search): Remove obsolete findex entries. ++ ++2008-11-01 Chong Yidong ++ ++ * programs.texi (Program Modes): Link to Program Indent node. ++ (Left Margin Paren): Explain consequences of changing ++ open-paren-in-column-0-is-defun-start more concisely. ++ (Which Function, Program Indent, Info Lookup): Minor edits. ++ (Basic Indent): If region is active, TAB indents the region. ++ (Multi-line Indent): If region is active, TAB indents the region. Note ++ that indent-region is useful when Transient Mark mode is off. ++ (Matching): The delimiter at the cursor is highlighted---the character ++ changes color. ++ (Symbol Completion): Link to Completion node. ++ ++ * misc.texi (Invoking emacsclient): Describe how to use Emacs server in ++ a strictly text-only system. ++ ++ * abbrevs.texi (Saving Abbrevs): Note that abbrev file is not loaded in ++ batch mode. ++ ++2008-11-01 Richard M. Stallman ++ ++ * misc.texi (Document View): Major rewrite. ++ ++ * maintaining.texi (Types of Log File): Change logs are older than ++ version control. ++ (VCS Concepts): Simplify and rearrange. ++ (Version Control Systems): Make it clear that Linux is only the kernel. ++ (VC Mode Line): Shorten reference to menu item. ++ (Basic VC Editing): Clarify VC fileset. Shorten and simplify. ++ (VC Directory Mode): Minor cleanup. ++ Unchanged files are hidden, not omitted. ++ (VC Directory Commands): Shorten and simplify. ++ (Change Log Commands): New node, split from Change Logs. ++ (VC Directory Buffer): New node, split from VC Directory Mode. ++ ++2008-10-31 Chong Yidong ++ ++ * misc.texi (Document View): Renamed from Document Files, moved here ++ from files.texi. ++ ++ * files.texi (Version Control): Moved to maintaining.texi. Subnodes ++ moved as well. ++ (Document Files): Moved to misc.texi. ++ ++ * maintaining.texi (Change Log): Document log-edit-insert-changelog and ++ vc-update-change-log. ++ (Version Control): Move here from files.texi. ++ (Format of ChangeLog): Make it a subnode of Change Log. ++ ++ * emacs.texi (Top): Update node listing. ++ ++2008-10-31 Tassilo Horn ++ ++ * files.texi (Files): Add a section about document ++ files (doc-view-mode). ++ ++2008-10-31 Chong Yidong ++ ++ * building.texi (Compilation Mode): Document ++ compilation-auto-jump-to-first-error. ++ (Debuggers): Lower GUD subsections to subsubsections. ++ (Starting GUD): Add cindex. ++ (Lisp Interaction): Note that scratch is no longer the initial buffer. ++ ++2008-10-30 Chong Yidong ++ ++ * indent.texi (Indentation): Link to Program Indent. ++ ++ * misc.texi (Invoking emacsclient): If Emacs has no available frame, it ++ now uses emacsclient's terminal. ++ ++2008-10-29 Chong Yidong ++ ++ * mark.texi (Using Region): Document use-empty-active-region. ++ ++ * emacs.texi (Top): Update node listings. ++ ++ * misc.texi (Emacs Server): Rewrite. Document daemon-mode. Don't ++ mention obsolete emacs.bash script. ++ (Invoking emacsclient): Rewrite, moving optional arguments to ++ emacsclient Options. ++ (emacsclient Options): New node. Document server-use-tcp and ++ server-host. ++ ++2008-10-28 Chong Yidong ++ ++ * indent.texi (Indentation): Replace list with paragraphed text, ++ putting description of syntax-driven indentation first. Document new ++ effect of active regions on tab. ++ (Tab Stops): Note that editable tab stops affect indentation commands. ++ ++2008-10-27 Dan Nicolaescu ++ ++ * cmdargs.texi (Initial Options): Document -daemon=SERVER_NAME. ++ ++2008-10-23 Chong Yidong ++ ++ * custom.texi (Function Keys): Note that modified keypad keys are not ++ translated. ++ ++ * basic.texi (Arguments): Explain how to insert multiple digits. ++ ++2008-10-22 Michael Albinus ++ ++ * files.texi (Remote Files): Precise selection of default method. ++ Rewrite paragraph about disabling remote file names. ++ ++2008-10-22 Chong Yidong ++ ++ * search.texi (Special Isearch): Document M-TAB is isearch. ++ ++ * files.texi (VC Mode Line): Use @kbd instead of @key for mouse ++ command. ++ ++ * frames.texi: Use @kbd instead of @key for mouse commands throughout. ++ ++2008-10-22 Tassilo Horn ++ ++ * emacs.texi (Acknowledgments): Added myself to Acknowledgments ++ section. ++ ++2008-10-21 Chong Yidong ++ ++ * vc1-xtra.texi: Move nodes VC Directory Mode and VC Directory Commands ++ to files.texi. Move contents of vc2-xtra.texi here. ++ ++ * vc2-xtra.texi: File removed. ++ ++ * vc-xtra.texi (Advanced VC Usage): Remove VC Directory Mode and VC ++ Directory Commands from the submenu. Don't include deleted file ++ vc2-xtra.texi. ++ ++ * files.texi (Visiting): Document find-file-confirm-nonexistent-file. ++ (Version Control): Add VC Directory Mode and VC Directory Commands to ++ the submenu. ++ (Why Version Control?): Use table format. ++ (Version Control Systems): Note that Meta-CVS support is gone. ++ (VCS Concepts): Note precisely when VC started supporting filesets. ++ Remove bogus xref to CVS Options node. ++ (Types of Log File): Copyedits. ++ (VC Mode Line): Document tooltips and mouse-1 on VC indicator. ++ (Basic VC Editing): Content moved from Selecting A Fileset and Doing ++ The Right Thing. ++ (Selecting A Fileset, Doing The Right Thing): Nodes deleted. ++ (Log Buffer): Reorganize node, putting C-c C-c description first. ++ (Old Revisions): Use CVS for example, not RCS. ++ (Secondary VC Commands): Remove VC Directory Mode and VC Directory ++ Commands from the submenu, putting them under Version Control. ++ (VC Directory Mode): Move node contents here from vc1-xtra.texi; we ++ need to include it in the manual unconditionally, since it is now ++ crucial to using distributed version control systems. ++ (Comparing Files): Note that diff uses the minibuffer, and that the ++ output is shown using Diff mode. ++ (Diff Mode): Explain what "patch" and "hunk" mean. Document ++ diff-update-on-the-fly, diff-refine-hunk, and ++ diff-show-trailing-whitespaces. ++ (File Archives): Add rar support. ++ ++ * major.texi (Choosing Modes): Make mode selection sequence more ++ obvious by describing the steps in order of priority. Note that ++ magic-mode-alist is nil by default. Document ++ magic-fallback-mode-alist. ++ ++2008-10-20 Chong Yidong ++ ++ * frames.texi (Mouse References): Copyedits. ++ ++2008-10-20 Tassilo Horn ++ ++ * ack.texi (Acknowledgments): Add myself as doc-view author. ++ ++2008-10-20 Eli Zaretskii ++ ++ * frames.texi (Dialog Boxes): Add @cindex entries. ++ ++2008-10-20 Chong Yidong ++ ++ * frames.texi (Dialog Boxes): Clarify description of GTK+ file chooser. ++ (Text-Only Mouse): Copyedit. ++ ++2008-10-19 Chong Yidong ++ ++ * frames.texi: Use @key throughout for mouse clicks. ++ (Cut/Paste Other App): Document yank-pop-change-selection. ++ (Secondary Selection): Fix modified mouse click syntax. ++ (Clipboard): Describe Cut, Copy and Paste commands. ++ (Mouse References): Not all references are in read-only buffers. ++ Copyedits. ++ (Creating Frames): Add xref to Init File. ++ (Frame Commands): Add xref to Exiting. ++ (Scroll Bars): Document GTK vs toolkit behavior. ++ ++2008-10-15 Chong Yidong ++ ++ * files.texi (Version Control): Copyedits. Add Bazaar. ++ (Version Control Systems): List different VCS's using an itemized list. ++ Add Bazaar. ++ (VCS Concepts): Copyedits. Tweak description of file merging. ++ ++ * frames.texi (Mouse Commands, Cut/Paste Other App): Rewrite. ++ (Cut/Paste Other App): Document select-active-regions and ++ x-select-enable-primary. ++ ++2008-10-13 Chong Yidong ++ ++ * mark.texi (Shift Selection): Correct case in node name. ++ ++ * emacs.texi (Top): Update node order in Mark chapter. ++ ++2008-10-12 Eli Zaretskii ++ ++ * msdog-xtra.texi (MS-DOS): Fix bad pxref. ++ ++ * mini.texi (Minibuffer File): Fix markup in last change. Refer to ++ elsewhere in the manual instead of describing yet again the intricacies ++ of $HOME on MS-Windows and MS-DOS. ++ ++2008-10-12 Chong Yidong ++ ++ * mini.texi (Minibuffer File): Add xref to File Names. ++ (Minibuffer File): Add discussion of `~' in file names. Add ++ insert-default-directory index reference. ++ ++ * files.texi (File Names): Reorganize description. ++ (Visiting): Add xref to Mode Line. Copyedits. ++ (Save Commands): Mention prefix behavior of C-x C-s. ++ (Numbered Backups): Node deleted. ++ (Backup Names): Contents of Numbered Backups moved here. State default ++ of version-control variable. ++ (Reverting): Copyedits. ++ (Version Control): Add additional version control systems. ++ ++ * emacs.texi (Top): Delete Numbered Backups node. ++ ++ * cmdargs.texi (General Variables): Change Numbered Backups xref to ++ Backup Names. ++ (Initial Options): Document renamed variable inhibit-startup-screen. ++ ++2008-10-11 Romain Francoise ++ ++ * kmacro.texi (Edit Keyboard Macro): Lossage is now 300 keys. ++ ++2008-10-11 Chong Yidong ++ ++ * buffers.texi (Buffers): Add xrefs to Mode Line and Lisp Interaction. ++ (Select Buffer): Mention use of minibuffer history. Describe default ++ value of default-major-mode. Mention that C-x 4 b selects the other ++ window. ++ (List Buffers): Document CRM indicators in the order they appear. ++ (Kill Buffer): Document new command kill-matching buffers. ++ (Several Buffers): Move explanation of the relationship between buffer ++ list and buffer menu to the top. ++ (Indirect Buffers): Document new variable clone-indirect-buffer-hook. ++ ++2008-10-10 Chong Yidong ++ ++ * entering.texi (Exiting): Document change of C-x C-c to ++ save-buffers-kill-terminal. Document kill-emacs. ++ ++2008-09-30 Eli Zaretskii ++ ++ * mule.texi (Coding Systems): Don't mention codepage-setup. ++ ++ * msdog-xtra.texi (MS-DOS Printing, MS-DOS and MULE): No need to create ++ cpNNN coding systems anymore. ++ (MS-DOS and MULE): Don't mention code-pages.el. Don't mention support ++ for unibyte mode. Don't mention line-drawing characters. Don't ++ mention dos-unsupported-char-glyph. ++ ++2008-09-25 Chong Yidong ++ ++ * search.texi (Search): Shorten introduction. ++ (Basic Isearch): Add command table. Discuss reverse isearch and ++ isearch highlighting. ++ (Repeat Isearch): Move lazy highlighting discussion here. Add search ++ ring to cindex. ++ (Special Isearch): Move input methods discussion here. ++ (Non-ASCII Isearch): Node deleted, merged with Special Isearch. ++ (Isearch Yank): Node deleted, and contents moved into Basic Isearch and ++ Repeat Isearch. ++ (Isearch Minibuffer): New node. ++ (Word Search): Document new word search commands. ++ (Regexp Example): Simplify example using sentence-end-base variable. ++ (Replace): Reword introduction. ++ (Unconditional Replace): Remove unnecessary example. ++ (Other Repeating Search): Document new `M-s o' binding. ++ ++ * emacs.texi (Top): Update node listings. ++ ++2008-09-22 Juanma Barranquero ++ ++ * emacs.texi (Top): Remove Kill Errors from menu. ++ ++2008-09-22 Chong Yidong ++ ++ * kmacro.texi (Basic Keyboard Macro): Make F3 and F4 the preferred ++ interface for defining macros. Simplify examples. Note that C-g quits ++ macro definitions. ++ (Keyboard Macro Counter): Document using F3 to insert counter. Give ++ usage example. ++ (Keyboard Macro Query): Organize query responses in a table. ++ ++ * fixit.texi (Fixit): Favor C-/ keybinding for undo throughout. Link ++ to Erasing node. ++ (Undo): Reorganize paragraphs for logical flow. Move keybinding ++ rationale to a footnote. ++ (Kill Errors): Remove node, due to redundancy with Erasing. ++ (Spelling): Move discussion of flyspell to end. Note new behavior of ++ M-$ in active region. Remove non-ispell-specific keybindings from ++ table. ++ ++2008-09-21 Dan Nicolaescu ++ ++ * cmdargs.texi (Initial Options): Document --daemon. ++ ++2008-09-20 Glenn Morris ++ ++ * files.texi (Numbered Backups): Mention that some modes set ++ version-control. ++ ++2008-09-20 Jim Blandy ++ ++ * files.texi (Numbered Backups): Reference File Variables, as well. ++ Remove discussion of Rmail's implementation. ++ ++2008-09-06 Chong Yidong ++ ++ * misc.texi (Recursive Edit): Note that top-level exits active ++ minibuffers. ++ ++ * trouble.texi (Quitting): Likewise. ++ ++2008-08-31 Chong Yidong ++ ++ * emacs.texi (Top): Add Temporary Face Changes xref. ++ ++ * display.texi (Display): Move Temporary Face Changes node to just ++ after Standard Faces. ++ (Scrolling): Document recenter-top-bottom instead of recenter. ++ (Horizontal Scrolling): Move auto hscroll discussion to the top. ++ (Faces, Standard Faces, Temporary Face Changes, Useless Whitespace) ++ (Display Custom): Copyedits. ++ (Optional Mode Line): Document display-battery-mode. ++ ++2008-08-27 Romain Francoise ++ ++ * custom.texi (Directory Variables): Minor fix. ++ ++2008-08-27 Glenn Morris ++ ++ * cal-xtra.texi (Advanced Calendar/Diary Usage): Tweak some menu ++ descriptions. ++ (Calendar Customizing): Tweak layout description. ++ Move calendar-today-marker and calendar-today face to the other ++ markers. Condense calendar-star-date and calendar-mark-today ++ description. ++ (Holiday Customizing): Add oriental and solar holidays. ++ Add index entries for Baha'i, Christian, Hebrew and Islamic holidays. ++ Fix holiday-float description. Use zerop in examples. Be less verbose. ++ (Date Display Format): Change ISO format. Be less verbose. ++ (Diary Customizing): Mention day and month abbrev arrays. ++ Mention the date-form variables by name. Update European example. ++ (Non-Gregorian Diary): Change node name. Mention Baha'i functions. ++ Condense examples. Mention diary-entry-symbols by name. ++ Condense table for insertion commands. ++ (Fancy Diary Display): Mention diary-include-string and ++ diary-sexp-entry-symbol. Condense example. Add Chinese, Coptic, ++ Ethiopic, Persian date functions. Condense descriptions. ++ ++ * calendar.texi (Format of Diary File): Mention diary-nonmarking-symbol. ++ (Adding to Diary): Adapt for changed node name. ++ ++2008-08-26 Glenn Morris ++ ++ * cal-xtra.texi (Non-Gregorian Diary Entries): New name for ++ node "Hebrew/Islamic Entries". ++ ++ * calendar.texi (Specified Dates): Fix names of iso functions. ++ (General Calendar): There may not be another window. ++ (Writing Calendar Files, Holidays): Tweak intro. ++ (Holidays): Mention Baha'i and Chinese holidays. ++ (Sunrise/Sunset): Add M-x calendar-sunrise-sunset-month. ++ (Lunar Phases): Remove incorrect reference to calendar-time-zone. ++ (To Other Calendar): Add calendar-print-other-dates. ++ Refer to "graphic display" rather than "X. ++ (From Other Calendar): Add calendar-bahai-goto-date. Fix reference. ++ (Displaying the Diary): Fix whitespace after reference. ++ Fix `diary-number-of-entries' reference. ++ (Date Formats): Explicitly mention that day names can be abbreviated. ++ (Adding to Diary): Add some references to other sections. ++ (Special Diary Entries): Fix reference. ++ (Appointments): Simplify appt-message-warning-time entry. ++ Clarify where times must be. ++ (Importing Diary): Comment out icalendar paragraph that does not apply. ++ (Time Intervals): Simplify entry for timeclock-ask-before-exiting. ++ ++2008-08-23 Glenn Morris ++ ++ * fortran-xtra.texi (Fortran): Change description of free form and ++ fixed form a bit. Mention hideshow and imenu. ++ (Fortran Motion): Mention fortran-end-of-subprogram, ++ fortran-beginning-of-subprogram, fortran-mark-do, fortran-mark-if. ++ (Fortran Indent): Minor re-word. ++ (ForIndent Commands): Mention fortran-fill-paragraph and ++ fortran-fill-statement. ++ (ForIndent Cont): Mention fortran-tab-mode-string. ++ (Fortran Comments): Mention fortran-comment-line-start-skip. ++ (Fortran Columns): Mention font-locking. ++ (Fortran Abbrev): Word syntax not relevant with new-style abbrev. ++ ++2008-08-23 Johan Bockgard ++ ++ * basic.texi (Moving Point): Fix / confusion. ++ ++2008-08-22 Chong Yidong ++ ++ * mini.texi (Minibuffer): Simplify introduction. ++ (Minibuffer File): Document tilde in minibuffer filenames. ++ (Minibuffer Edit): Mention that the prompt is read-only. Describe how ++ to enter tabs, spaces, and question marks. Describe behavior of C-a. ++ (Completion Example): Update example to current command list. ++ (Completion Options): Document `lazy' value of completion-auto-help. ++ Update contents of completion-ignored-extensions. ++ (Minibuffer History): Describe "future history" list. State default ++ value of history-delete-duplicates. ++ ++2008-08-21 Glenn Morris ++ ++ * fortran-xtra.texi (Fortran Columns): Document `fortran-line-length'. ++ (Fortran Comments): Replace fortran-indent-comment with comment-dwim. ++ ++2008-08-17 Chong Yidong ++ ++ * regs.texi (Registers): Clarify valid register names. ++ (RegPos): Note that buffer is saved and restored too. ++ (RegText): Note that mark is reactivated/deactivated. ++ (RegConfig): Xref to Windows node. ++ ++2008-08-16 Chong Yidong ++ ++ * basic.texi (Inserting Text): Provide command name for C-q. ++ ++ * killing.texi (Killing): Copyedit. Define read-only text. ++ (Deletion): DEL and C-d were already explained in Erasing; xref there. ++ (Killing by Lines): Copyedit. ++ (Other Kill Commands): Move M-w description here. ++ (Yanking): Move M-w to Other Kill Commands. ++ (Kill Ring): Also mention saving text in registers. Link to Text ++ Properties in elisp manual. ++ (Accumulating Text): Copyedit. ++ (CUA Bindings): Shift selection is now the default. ++ ++2008-08-12 Teodor Zlatanov ++ ++ * maintaining.texi (Change Log): Mention next-error is available. ++ ++2008-08-10 Glenn Morris ++ ++ * cal-xtra.texi (Calendar Customizing): Mention whitespace variables ++ and intermonth text. ++ (Holiday Customizing): Add holiday-chinese. ++ ++2008-08-08 Eli Zaretskii ++ ++ * files.texi (Log Buffer, Diff Mode): Fix last changes. Add indexing. ++ ++2008-08-07 Dan Nicolaescu ++ ++ * files.texi (Log Buffer): Describe C-c C-d. ++ (Diff Mode): Describe C-x 4 A. ++ ++2008-08-06 Eli Zaretskii ++ ++ * vc1-xtra.texi (VC Directory Mode): Fix last change. ++ ++2008-08-06 Dan Nicolaescu ++ ++ * files.texi (Old Revisions): Update the keys used by vc-annotate and ++ describe the new bindings to show the changeset diff, toggle annotation ++ visibility, show revisions. ++ (VC Status): Describe key bindings for modifying the change comments, ++ displaying changeset diffs and annotations. ++ ++ * vc1-xtra.texi (VC Directory Mode): Talk about multiple VC systems. ++ ++2008-08-05 Nick Roberts ++ ++ * vc1-xtra.texi (VC Directory Mode): Fix typo. ++ ++2008-08-02 Eli Zaretskii ++ ++ * vc1-xtra.texi (VC Directory Mode, VC Directory Commands): Fix English ++ and wording. ++ ++2008-08-02 Dan Nicolaescu ++ ++ * vc1-xtra.texi (VC Directory Mode): Fix and improve the info about ++ marking/unmarking. Add descriptions for the multiple file search ++ commands. Improve some old info. ++ ++2008-07-31 Chong Yidong ++ ++ * display.texi (Visual Line Mode): New node. ++ ++ * basic.texi (Inserting Text): Move DEL to deletion node. ++ (Moving Point): Add additional alternative key bindings. Describe ++ line-move-visual. ++ (Erasing): Describe DEL. ++ (Basic Undo, Blank Lines, Arguments): Copyedit. ++ (Continuation Lines): Mention Visual Line mode. ++ (Position Info): Move extended discussion to mule.texi. ++ ++ * mule.texi (International Chars): Describe C-x =. ++ ++ * emacs.texi (Top): Add Visual Line Mode node. ++ ++2008-07-31 Dan Nicolaescu ++ ++ * emacs.texi: Remove VMS support. ++ ++2008-07-30 Dan Nicolaescu ++ ++ * vc1-xtra.texi (VC Directory Mode): Update the display format and fix ++ the vc-dir command name. ++ ++2008-07-27 Dan Nicolaescu ++ ++ * xresources.texi: Remove mentions of Mac Carbon. ++ ++2008-07-19 Andreas Schwab ++ ++ * ns-emacs.texi: Move to ../misc. ++ ++2008-07-15 Chong Yidong ++ ++ * entering.texi (Exiting): Don't describe text-only terminals as the ++ default. Describe the new startup screen. ++ (Exiting): Describe how to kill Emacs first. Change description of ++ iconification to handle modern window systems. ++ ++2008-07-15 Adrian Robert ++ ++ * ns-emacs.texi: New file, documents features of Emacs port under ++ NeXTstep windowing. ++ ++2008-07-15 Chong Yidong ++ ++ * entering.texi (Entering Emacs): Update prev node. ++ ++ * glossary.texi (Glossary): Remove xref to Text Characters. ++ ++ * commands.texi (User Input): Rewrite. Describe Emacs' behavior ++ directly, rather than in the context of ASCII. Move description of ++ special properties of modifier key to new Modifier Keys node. ++ (Keys): Copyedit. ++ (Text Characters): Delete node. Multibyte is the default nowadays, and ++ the node contents are obsolete. ++ ++ * custom.texi (Modifier Keys): New node. ++ ++ * emacs.texi (Top): Update node list. ++ ++2008-07-13 Chong Yidong ++ ++ * emacs.texi (Intro): Increase conciseness slightly. Remove paragraph ++ saying that Emacs provides menus and mouse support (which is par for ++ the course). ++ ++ * screen.texi (Screen): Copyedit. Define "buffer" and "current buffer" ++ early on. ++ (Point): Copyedit. Relegate historical trivia to a footnote. ++ (Mode Line): Explain mode-line format more consistently. ++ (Menu Bar): Copyedit. ++ ++2008-06-27 Glenn Morris ++ ++ * cal-xtra.texi (Sexp Diary Entries): ++ * calendar.texi (Lunar Phases): Update for lunar.el name changes. ++ ++2008-06-26 Chong Yidong ++ ++ * mark.texi (Shift selection): New node. ++ (Mark): Copyedits. ++ (Persistent Mark): Move to the end of the chapter. ++ ++2008-06-20 Eli Zaretskii ++ ++ * makefile.w32-in (distclean): Remove makefile. ++ ++2008-06-17 Nick Roberts ++ ++ * building.texi (Starting GUD): Add an entry for gud-gdb. ++ (GDB Graphical Interface): Explain that gud-gdb is now needed for text ++ command mode. ++ ++2008-06-17 Glenn Morris ++ ++ * calendar.texi: Fix references to mouse-2 and mouse-3 in calendar. ++ ++2008-06-17 Nick Roberts ++ ++ * building.texi (Starting GUD): Expand on remote debugging. ++ (Other GDB-UI Buffers): Mention new keyboard bindings. ++ ++2008-06-15 Glenn Morris ++ ++ * gnu.texi: Use a verbatim license for this invariant section, ++ as per etc/GNU. ++ ++2008-06-13 Daniel Engeler ++ ++ * emacs.texi, misc.texi: Add documentation about serial port access. ++ ++2008-06-13 Glenn Morris ++ ++ * emacs-xtra.texi, emacs.texi: Update Back-Cover text per ++ maintain.info. ++ ++2008-06-05 Miles Bader ++ ++ * display.texi (Temporary Face Changes): Update to reflect function ++ renamings in face-remap.el. ++ ++2008-06-04 Miles Bader ++ ++ * display.texi (Temporary Face Changes): Add ++ `adjust-buffer-face-height'. Rewrite description of ++ `increase-buffer-face-height' and `decrease-default-face-height' now ++ that they aren't bound by default. ++ ++2008-06-03 Miles Bader ++ ++ * display.texi (Temporary Face Changes): New node. ++ ++2008-05-31 Eli Zaretskii ++ ++ * msdog.texi (Windows Keyboard): Fix text added on 2008-05-29. ++ ++2008-05-31 Glenn Morris ++ ++ * cal-xtra.texi (Fancy Diary Display): Simplify. ++ ++2008-05-30 Glenn Morris ++ ++ * cal-xtra.texi (Fancy Diary Display): Update for ++ diary-display-function replacing diary-display-hook. ++ ++2008-05-29 Drew Adams ++ ++ * msdog.texi (Windows Keyboard): Add descriptions of ++ w32-register-hot-key and w32-unregister-hot-key. ++ ++2008-05-21 Tom Tromey ++ ++ * custom.texi (Directory Variables): Grammar fix. Link to Safe File ++ Variables node. ++ ++2008-05-19 Tom Tromey ++ ++ * custom.texi (Variables): Add Directory Variables to menu. ++ (Directory Variables): New node. ++ ++2008-05-16 Eric S. Raymond ++ ++ * vc2-xtra.texi: Modify an example so it reflects what vc.el now does. ++ ++2008-05-15 Eric S. Raymond ++ ++ * vc2-xtra.texi, emacs.texi, files.texi: Snapshots node renamed to ++ Revision Tags and rewritten. Section now uses modern terminology, ++ (tags rather than snapshots) and describes post-SCCS systems more ++ accurately. ++ ++2008-05-10 Eli Zaretskii ++ ++ * msdog.texi (Windows Files): Update documentation of ++ w32-get-true-file-attributes. ++ ++2008-05-09 Eric S. Raymond ++ ++ * files.texi, vc-xtra.texi, vc1-xtra.texi: Document the new VC ++ directory mode. ++ ++2008-05-08 Chong Yidong ++ ++ * killing.texi (Appending Kills): Remove a strangely off-topic index ++ entry "television". ++ ++2008-05-07 Eric S. Raymond ++ ++ * ack.texi, files.texi, vc2-xtra.texi: Meta-CVS is no longer supported. ++ ++2008-05-02 Eric S. Raymond ++ ++ * emacs/buffers.texi, emacs/files.texi (Version-control): ++ vc-toggle-read-only is no longer a good idea... ++ ++2008-04-29 Glenn Morris ++ ++ * cal-xtra.texi (Sexp Diary Entries): Clarify diary-float. ++ ++2008-04-22 Juri Linkov ++ ++ * dired.texi (Subdirectories in Dired): Describe using `^' ++ to return to the parent directory. ++ ++2008-04-22 Nick Roberts ++ ++ * building.texi (GDB-UI Layout, Other GDB-UI Buffers): Update for ++ recent changes. ++ ++2008-04-19 Nick Roberts ++ ++ * building.texi (GDB-UI Layout, Breakpoints Buffer) ++ (Other GDB-UI Buffers): Update for recent thread related changes. ++ ++2008-04-11 Mirko Vukovic (tiny change) ++ ++ * maintaining.texi (Maintaining): ++ * emacs.texi (Top): Typo. ++ ++2008-04-08 Stefan Monnier ++ ++ * display.texi (Font Lock): Prefer add-hook to using a non-nil `mode' ++ arg in `font-lock-add-keywords'. ++ ++2008-04-08 Glenn Morris ++ ++ * cal-xtra.texi, calendar.texi: Update for calendar name changes. ++ Also add Baha'i calendar references where appropriate. ++ ++2008-04-05 Glenn Morris ++ ++ * custom.texi (Init File): Byte-compiling .emacs is bad. ++ ++2008-04-04 Stefan Monnier ++ ++ * mini.texi (Minibuffer Edit) : Adjust default. ++ ++2008-03-29 Glenn Morris ++ ++ * calendar.texi: Update for `calendar-date-style' replacing ++ `european-calendar'. ++ ++2008-03-28 Jason Rumney ++ ++ * display.texi (Display Custom): Mention overlay-margin in text. ++ ++2008-03-12 Reiner Steib ++ ++ * custom.texi, dired.texi, mini.texi, mule.texi: Add `referenced in the ++ tutorial' comments. ++ ++2008-03-28 Chong Yidong ++ ++ * mark.texi (Mark): Rearrange nodes. ++ (Persistent Mark): Rename from Transient Mark. ++ (Mark, Setting Mark, Marking Objects, Persistent Mark, Mark Ring): ++ Describe Transient Mark mode as the default. ++ ++ * basic.texi (Basic Undo): Don't mention setting the mark, which isn't ++ the default behavior with Transient Mark mode off. ++ (Position Info): Fix typo. ++ ++ * display.texi (Standard Faces): Reference the Mark node. ++ Remove discussion of the region face, which is discussed there. ++ ++ * emacs.texi (Top): Update node listings. ++ ++ * files.texi (Diff Mode, Misc File Ops): Describe Transient Mark mode ++ as the default. ++ ++ * fixit.texi (Undo): Standardize choice of undo key sequence. ++ (Undo, Spelling): Describe Transient Mark mode as the default. ++ ++ * frames.texi (Mouse Commands): Treat Transient Mark mode as the ++ default. ++ ++ * glossary.texi (Glossary): Treat Transient Mark mode as the default. ++ ++ * killing.texi (Kill Ring, Accumulating Text): Assume Transient Mark ++ mode is the default, and note that the mark is not activated when set. ++ ++ * programs.texi (Moving by Defuns, Expressions, Comment Commands): ++ Describe Transient Mark mode as the default. ++ ++ * search.texi (Basic Isearch): Reference the Mark Ring node. ++ (Replace, Unconditional Replace, Other Repeating Search): ++ Describe Transient Mark mode as the default. ++ ++ * text.texi (Words, Pages, Fill Commands, HTML Mode): Describe ++ Transient Mark mode as the default. ++ (Paragraphs): Describe how M-h behaves when region is active. ++ ++ * trouble.texi (Quitting): Clarify effects of C-g. ++ ++2008-03-13 Glenn Morris ++ ++ * emacs.texi (EMACSVER): Set to 23.0.60. ++ ++2008-03-05 Glenn Morris ++ ++ * dired.texi (Hiding Subdirectories): Fix previous change. ++ ++2008-03-05 Drew Adams ++ ++ * dired.texi (Hiding Subdirectories): Document `dired-hide-subdir'. ++ ++2008-02-28 Kim F. Storm ++ ++ * help.texi (Help Files): Move describe-gnu-project to C-h g. ++ Move describe-distribution to C-h C-o. ++ Move view-emacs-problems to C-h C-p. ++ Add view-emacs-debugging on C-h C-d. ++ Add view-external-packages on C-h C-e. ++ Add view-order-manuals on C-h C-m. ++ ++2008-02-17 Ulrich Mueller ++ ++ * msdog-xtra.texi (MS-DOS): Docstring fix. ++ ++2008-02-09 Eli Zaretskii ++ ++ * msdog.texi (Windows Fonts): Use a @table for describing font ++ properties. ++ ++2008-02-07 Jason Rumney ++ ++ * msdog.texi (Windows Files): w32-get-true-file-attributes default ++ value has changed. ++ (Windows HOME): Clarify what is meant by "if that fails as well". ++ (Windows Fonts): New section. ++ ++2008-02-07 D. E. Evans (tiny change) ++ ++ * basic.texi (Basic Undo): Remove duplicate "you can". ++ ++2008-02-02 Eli Zaretskii ++ ++ * maintaining.texi (Tags): Fix last change. ++ ++2008-02-02 Michael Albinus ++ ++ * tramp.texi: Use new FSF's Back-Cover Text. ++ ++2008-01-31 Nick Roberts ++ ++ * trouble.texi (Checklist): Direct users to emacs-devel@gnu.org. ++ ++2008-01-26 Richard Stallman ++ ++ * maintaining.texi (Tags): Delete redundant index entry. ++ ++2008-01-26 Eli Zaretskii ++ ++ * programs.texi (Imenu): Move "@cindex tags" from here... ++ * maintaining.texi (Tags): ...to here. ++ ++2008-01-23 Kevin Ryde ++ ++ * custom.texi (Mouse Buttons): Update elisp xref to "Click Events" on ++ click count. ++ ++2008-01-21 Juanma Barranquero ++ ++ * entering.texi (Exiting): Fix typo. ++ Reported by D. E. Evans . ++ ++2007-12-31 Martin Rudalics ++ ++ * glossary.texi (Glossary): Fix typo. ++ ++2007-12-27 Richard Stallman ++ ++ * text.texi (Formatted Text): Improve menu tag. ++ (Editing Format Info): In Info, add duplicate menu of nodes ++ about the submenus. ++ (Format Faces): Say where Faces menu is found. Mention Other. ++ (Format Colors): Say where these submenus are found. ++ (Format Indentation, Format Justification): Likewise. ++ (Format Properties): Likewise. ++ ++2007-12-22 Richard Stallman ++ ++ * search.texi (Query Replace): Make exp of query-replace more ++ self-contained, and clarify. ++ ++ * cc-mode.texi (Getting Started): Change @ref to @pxref. ++ ++2007-12-15 Richard Stallman ++ ++ * files.texi (Auto Save): Clarify definition of auto-saving. ++ ++2007-11-26 Richard Stallman ++ ++ * help.texi (Help Echo): Cleanups. ++ ++2007-11-23 Thien-Thi Nguyen ++ ++ * files.texi (Why Version Control?): Fix typo. ++ (VCS Concepts): Fix typos; small tense fix. ++ (Selecting a Fileset): Fix typos; small rewording. ++ (Log Buffer): Likewise. ++ (Old Revisions): Likewise. ++ ++2007-11-17 Eli Zaretskii ++ ++ * mule.texi (Communication Coding): Fix wording of last change. ++ ++2007-11-16 Werner Lemberg ++ ++ * custom.texi (Specifying File Variables): ++ * major.texi (Choosing Modes): Mention '\" in man pages. ++ ++2007-11-16 Kenichi Handa ++ ++ * mule.texi (Communication Coding): Document x-select-request-type. ++ ++ * frames.texi (Cut/Paste Other App): Mention x-select-request-type. ++ ++2007-11-15 Francesco Potortì ++ ++ * maintaining.texi (TEXTAGS): Note that you can use "-" for stdout with ++ --output=file. ++ ++2007-11-13 Martin Rudalics ++ ++ * help.texi (Help Summary, Apropos, Misc Help): Fix typos. ++ (Help Echo): Avoid mentioning the term "region" here and ++ consistently use the term "active text". ++ ++2007-11-11 Glenn Morris ++ ++ * calendar.texi (Special Diary Entries): Fix Thanksgiving example. ++ ++2007-11-10 Paul Pogonyshev ++ ++ * search.texi (Query Replace): Mention ++ `query-replace-show-replacement'. ++ ++2007-11-09 Nick Roberts ++ ++ * building.texi (Watch Expressions): Remove obscure sentence. ++ ++2007-11-06 Kenichi Handa ++ ++ * mule.texi (Select Input Method): Describe how to activate an input ++ method in the text mode. ++ ++2007-11-01 Dan Nicolaescu ++ ++ * cmdargs.texi (Misc Variables): Remove Sun windows info. ++ ++2007-10-30 Nick Roberts ++ ++ * building.texi (Watch Expressions): Describe gdb-delete-out-of-scope. ++ ++2007-10-30 Glenn Morris ++ ++ * misc.texi (Directory Tracking): Explain a bit more about ++ dirtrack-mode. ++ ++2007-10-25 Glenn Morris ++ ++ * fortran-xtra.texi (Fortran): F90 mode handles F2003. ++ ++2007-10-24 Richard Stallman ++ ++ * misc.texi (Interactive Shell): Cleanup last change. ++ ++2007-10-22 Juri Linkov ++ ++ * mini.texi (Minibuffer History): Add text about a list of minibuffer ++ default values. ++ ++2007-10-20 Eric S. Raymond ++ ++ * files.texi: Disambiguate two slightly different uses of the term ++ 'filesets'. ++ ++2007-10-18 Martin Rudalics ++ ++ * trouble.texi (Quitting): Fix typo. ++ ++2007-10-18 Glenn Morris ++ ++ * frames.texi (Mode Line Mouse): Mention minor mode names. ++ ++2007-10-17 Juri Linkov ++ ++ * text.texi (Fill Commands): Undocument fill-paragraph-or-region. ++ fill-paragraph operates on the active region in Transient Mark mode. ++ (Fill Prefix, Format Indentation): Replace fill-paragraph-or-region ++ with fill-paragraph. ++ ++ * basic.texi (Arguments): Replace fill-paragraph-or-region with ++ fill-paragraph. ++ ++ * fixit.texi (Spelling): ispell-word operates on the active region ++ in Transient Mark mode. ++ ++2007-10-17 Aaron S. Hawley ++ ++ * building.texi (Source Buffers): ++ * custom.texi (Init Non-ASCII): ++ * glossary.texi (Glossary): Use "key binding" consistently. ++ ++2007-10-17 Juanma Barranquero ++ ++ * calendar.texi (Diary): Fix directive. ++ ++2007-10-16 Richard Stallman ++ ++ * calendar.texi (Diary): Clarify text about diary file example. ++ ++2007-10-13 Eric S. Raymond ++ ++ * files.texi: Capitalize node names according to convention. ++ ++2007-10-13 Glenn Morris ++ ++ * misc.texi (Interactive Shell): Correct INSIDE_EMACS reference. ++ ++2007-10-11 Eric S. Raymond ++ ++ * emacs.texi: ++ * files.texi (Version Systems): Minor fixes to version-control material ++ suggested by RMS and Robert J. Chassell. ++ ++2007-10-10 Eric S. Raymond ++ ++ * files.texi (Version Systems): ++ * vc-xtra.texi: ++ * vc1-xtra.texi: ++ * vc2-xtra.texi: Merge in changes for new VC with fileset-oriented ++ operations. Change of terminology from `version' to `revision'. ++ Revise text for adequate description of VCSes with monotonic IDs. ++ * emacs.texi: Change of terminology from `version' to `revision'. ++ ++2007-10-09 Eric S. Raymond ++ ++ * files.texi (Version Systems): Describe newer VCses. ++ Reorder the descriptions to be chronological. ++ ++2007-10-09 Richard Stallman ++ ++ * display.texi (Cursor Display): Correct how cursor appears ++ in nonselected windows. ++ ++2007-10-04 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Remove references to gdba ++ and mention gud-gdb. ++ ++2007-08-31 Eli Zaretskii ++ ++ * rmail.texi (Rmail Sorting): Improve indexing. ++ ++2007-10-06 Juri Linkov ++ ++ * text.texi (Fill Commands): Document fill-paragraph-or-region. ++ (Fill Prefix, Format Indentation): Replace fill-paragraph with ++ fill-paragraph-or-region. ++ ++ * basic.texi (Arguments): Replace fill-paragraph with ++ fill-paragraph-or-region. ++ ++2007-10-06 Eric S. Raymond ++ ++ * files.texi: Update the section on version control for 2007 ++ conditions. None of these changes are new-VC-specific; that ++ will come later. ++ ++2007-09-15 Glenn Morris ++ ++ * calendar.texi (Holidays): Change all instances of `holiday-list' back ++ to `list-holidays'. ++ ++2007-09-14 Glenn Morris ++ ++ * calendar.texi: Update all instances of mark-calendar-holidays, ++ list-calendar-holidays, list-holidays with the new names. ++ ++2007-09-06 Glenn Morris ++ ++ Move manual sources from man/ to subdirectories of doc/. ++ Split into the Emacs manual in emacs/, and other manuals in misc/. ++ * Makefile.in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs ++ manual. ++ (infodir): New variable. ++ (info): Use $infodir. ++ (emacsman): Delete target, not needed any more. ++ Move all targets that are not the Emacs manual to misc/Makefile.in. ++ (mostlyclean): Remove `gnustmp'. ++ * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs ++ manual. ++ (MULTI_INSTALL_INFO, ENVADD, infodir): Go up one more level. ++ (emacsman): Delete target, not needed any more. ++ (clean): Remove all info files but Emacs manual. ++ Move all targets that are not the Emacs manual to misc/Makefile.in. ++ * emacs-xtra.texi, emacs.texi (setfilename): Go up one more level. ++ ++ * Makefile.in (INFOSOURCES): Delete. ++ (.SUFFIXES): Use $(TEXI2DVI) rather than texi2dvi. ++ (mostlyclean): Add *.op, *.ops. Move *.aux *.cps *.fns *.kys *.pgs ++ *.vrs *.toc here... ++ (maintainer-clean): ...from here. ++ ++2007-09-05 Glenn Morris ++ ++ * custom.texi (Safe File Variables): Clarify `!' and risky variables. ++ ++2007-08-29 Glenn Morris ++ ++ * emacs.texi (EMACSVER): Increase to 23.0.50. ++ ++2007-08-27 Richard Stallman ++ ++ * emacs.texi (Top): Clarify menu item for Glossary. ++ ++ * display.texi (Faces): Change secn title. ++ Clarify not all fonts come from Font Lock. ++ ++2007-08-17 Eli Zaretskii ++ ++ * basic.texi (Position Info): Add index entry for face at point. ++ Mention that character faces are also displayed by "C-u C-x =". ++ ++2007-08-08 Glenn Morris ++ ++ * glossary.texi (Glossary): Deprecate `iff'. ++ ++2007-08-07 Chong Yidong ++ ++ * files.texi (File Conveniences): Document point motion keys in Image ++ mode. ++ ++2007-07-27 Glenn Morris ++ ++ * emacs.texi (Copying): Include license text from gpl.texi, rather than ++ in-line. ++ ++ * gpl.texi: New file with text of GPL. ++ * Makefile.in (EMACSSOURCES): Add gpl.texi. ++ ++2007-07-26 Dan Nicolaescu ++ ++ * vc2-xtra.texi (Customizing VC): Add GIT and HG. ++ ++ * dired.texi (Wdired): Mention C-x C-q key binding. ++ ++2007-07-28 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Qualify use of "M-x gdba". ++ ++2007-07-25 Glenn Morris ++ ++ * emacs.texi (Copying): Replace license with GPLv3. ++ ++ * Relicense all FSF files to GPLv3 or later. ++ ++2007-07-24 Glenn Morris ++ ++ * calendar.texi (Writing Calendar Files): cal-tex-diary etc only work ++ for some calendars. ++ ++2007-07-23 Nick Roberts ++ ++ * screen.texi (Mode Line): Describe new mode-line flag that shows if ++ default-directory for the current buffer is on a remote machine. ++ ++2007-07-21 Eli Zaretskii ++ ++ * vc2-xtra.texi (Customizing VC) : Update the ++ default value. ++ ++2007-07-21 Richard Stallman ++ ++ * files.texi (Why Version Control?): Improve previous change. ++ ++2007-07-18 Eric S. Raymond ++ ++ * files.texi (Why Version Control?): New node. ++ ++2007-07-12 Nick Roberts ++ ++ * building.texi (Starting GUD): Add xref to this anchor. ++ ++2007-06-24 Karl Berry ++ ++ * emacs.texi: New Back-Cover Text. ++ ++2007-06-07 Alan Mackenzie ++ ++ * display.texi (Optional Mode Line): Document the new form of ++ line+column numbers, "(561,2)". ++ ++2007-06-06 Juanma Barranquero ++ ++ * maintaining.texi (Create Tags Table): Fix typos. ++ ++2007-06-02 Chong Yidong ++ ++ * Version 22.1 released. ++ ++2007-05-07 Karl Berry ++ ++ * emacs.texi (EMACSVER): Back to 22. ++ ++2007-05-06 Richard Stallman ++ ++ * maintaining.texi (Create Tags Table): Clean up previous change. ++ ++2007-05-05 Francesco Potortì ++ ++ * maintaining.texi (Create Tags Table): Add text about the dangers of ++ making symbolic links to tags files. ++ ++2007-05-04 Karl Berry ++ ++ * emacs.texi (EMACSVER) [smallbook]: 22.1 for printed version, not 22. ++ ++2007-05-03 Karl Berry ++ ++ * emacs.texi (EMACSVER) [smallbook]: 22 for printed version. ++ ++ * .cvsignore (*.pdf): New entry. ++ ++ * emacs.texi (\urlcolor, \linkcolor) [smallbook]: \let to \Black ++ for printing. ++ ++2007-05-01 Richard Stallman ++ ++ * cmdargs.texi (Initial Options): Under --batch, mention --eval. ++ ++2007-04-28 Glenn Morris ++ ++ * ack.texi (Acknowledgments): ++ * anti.texi (Antinews): ++ * programs.texi (Program Modes): Restore mention of python.el pending ++ consideration of legal status. ++ ++2007-04-28 Richard Stallman ++ ++ * files.texi (File Names): Fixes to ~ description on MS systems. ++ ++2007-04-26 Glenn Morris ++ ++ * emacs.texi (EMACSVER): Increase to 22.1.50. ++ ++2007-04-25 Karl Berry ++ ++ * emacs.texi: Improve line breaks on copyright page, ++ similar layout to lispref, 8.5x11 by default. ++ ++ * dired.texi (Image-Dired): Improve line break, fix typo. ++ ++2007-04-24 Chong Yidong ++ ++ * programs.texi (Program Modes): ++ * anti.texi (Antinews): ++ * ack.texi (Acknowledgments): python.el removed. ++ ++2007-04-23 Chong Yidong ++ ++ * display.texi (Highlight Interactively): Correct description of ++ hi-lock-file-patterns-policy. ++ ++ * files.texi (File Archives): Mention self-extracting executables. ++ ++2007-04-23 Eli Zaretskii ++ ++ * search.texi (Unconditional Replace, Query Replace): Add xref to ++ "Replacement and Case". ++ ++2007-04-22 Chong Yidong ++ ++ * dired.texi (Image-Dired): Move from Thumbnails node. ++ * misc.texi (Thumbnails): Node deleted. ++ * emacs.texi (Top): Update node listing. ++ ++ * files.texi (File Conveniences): ++ * ack.texi (Acknowledgments): Rename "tumme" to "image-dired". ++ ++2007-04-21 Richard Stallman ++ ++ * display.texi (Highlight Interactively): Correct previous change. ++ Clarify doc of hi-lock-find-patterns, and move new features into it. ++ ++2007-04-20 David Koppelman ++ ++ * display.texi (Highlight Interactively): Document ++ hi-lock-file-patterns-policy. ++ ++2007-04-20 Martin Rudalics ++ ++ * display.texi (Scrolling): Fix typo. ++ ++2007-04-15 Chong Yidong ++ ++ * doclicense.texi: Remove node heading, so that it can be included by ++ other files. ++ ++ * emacs.texi: Insert node heading for GFDL. ++ ++2007-04-14 Eli Zaretskii ++ ++ * cmdargs.texi (Colors): Qualify "color of window" index entry by ++ "command line". ++ ++ * display.texi (Faces): Refer to "Creating Frames" for face ++ and other frame customizations in .emacs. ++ ++ * frames.texi (Creating Frames): Mention that face customizations can ++ be put in .emacs. Add index entries. ++ ++2007-04-12 Richard Stallman ++ ++ * glossary.texi (Glossary): Explain `iff'. ++ ++2007-04-11 Karl Berry ++ ++ * gnu.texi (Top), ++ * macos.texi (Mac Font Specs), ++ * anti.texi (Antinews), ++ * xresources.texi (Resources), ++ * misc.texi (Emulation), ++ * calendar.texi (Daylight Saving), ++ * dired.texi (Dired and Find), ++ * rmail.texi (Remote Mailboxes), ++ * sending.texi (Mail Headers), ++ * programs.texi (Which Function), ++ * files.texi (Recover), ++ * buffers.texi (Uniquify), ++ * frames.texi (Wheeled Mice), ++ * killing.texi (Rectangles): Wording to improve breaks in ++ 8.5x11 format. ++ * mule.texi (Language Environments): \hbadness=10000 since there's ++ no way to reword. ++ * emacs.texi (smallbook): New @set to more easily switch between ++ smallbook and 8.5x11. ++ ++2007-04-11 Richard Stallman ++ ++ * files.texi (File Conveniences): Add xref to Tumme. ++ Delete text about Thumbnail mode. ++ ++2007-04-09 Alan Mackenzie ++ ++ * cmdargs.texi (Initial Options): Call "inhibit-splash-screen" by its ++ new name. Insert concept index entries. ++ ++2007-04-08 Chong Yidong ++ ++ * display.texi (Standard Faces): Document prefix arg for ++ list-faces-display. ++ ++ * rmail.texi (Rmail Scrolling): Document rmail-end-of-message. ++ ++2007-04-07 Chong Yidong ++ ++ * killing.texi (Deletion): Rewrite description of M-\ prefix argument. ++ ++ * files.texi (Misc File Ops): Rewrite description of ++ insert-file-literally. ++ ++2007-03-31 Eli Zaretskii ++ ++ * misc.texi (Printing): Postscript -> PostScript. ++ ++ * ack.texi (Acknowledgments): Postscript -> PostScript. ++ ++ * custom.texi (Init File, Init Non-ASCII): Fix last change. ++ ++ * emacs.texi (Top): Fix the menu due to the change in custom.texi ++ below. ++ ++2007-03-30 Chong Yidong ++ ++ * custom.texi (Non-ASCII Rebinding): Node deleted. Material moved to ++ Init Non-ASCII. ++ (Init Rebinding, Init Syntax): Link to Init Non-ASCII instead. ++ (Init Non-ASCII): New node. ++ ++2007-03-28 YAMAMOTO Mitsuharu ++ ++ * macos.texi (Mac Font Specs): Mention AppleAntiAliasingThreshold. ++ ++2007-03-12 Glenn Morris ++ ++ * calendar.texi, emacs.texi (Daylight Saving): Rename node from ++ "Daylight Savings". ++ ++ * calendar.texi: Replace "daylight savings" with "daylight ++ saving" in text throughout. ++ ++2007-03-04 Richard Stallman ++ ++ * custom.texi (Safe File Variables): Minor correction. ++ ++2007-02-28 Thien-Thi Nguyen ++ ++ * rmail.texi (Movemail): Add internal ref. ++ Don't indent the intro for the PROTO table. ++ Format PROTO table items with @code. ++ ++2007-02-26 Nick Roberts ++ ++ * building.texi: Remove references to bashdb. ++ ++2007-02-19 Juanma Barranquero ++ ++ * mule.texi (Language Environments): Update list of supported language ++ environments. ++ ++2007-02-14 Kim F. Storm ++ ++ * building.texi (Grep Searching): Fix lgrep doc. ++ ++2007-02-12 Chong Yidong ++ ++ * back.texi: Remove unused file. ++ ++2007-02-05 Francesco Potortì ++ ++ * maintaining.texi (Tag Syntax): Now --members is the default for ++ etags, not for ctags yet. ++ ++2007-02-03 Eli Zaretskii ++ ++ * emacs.texi (Top): Update the top-level menus. Make the detailed menu ++ headers compliant with Texinfo guidelines and with what texnfo-upd.el ++ expects. Add comments to prevent people from inadvertently modifying ++ the key parts needed by `texinfo-multiple-files-update'. ++ ++2007-01-29 Chong Yidong ++ ++ * frames.texi (Secondary Selection): Window clicked does not matter ++ when mouse-yank-at-point is non-nil. ++ ++2007-01-16 Glenn Morris ++ ++ * abbrevs.texi (Editing Abbrevs): Describe how to disable a ++ system abbrev. ++ ++2007-01-11 Richard Stallman ++ ++ * msdog.texi (Windows Keyboard): Another small cleanup. ++ ++2007-01-10 Richard Stallman ++ ++ * msdog.texi (Windows Keyboard): Yet another try to make ++ everyone happy with that passage. ++ ++2007-01-05 Richard Stallman ++ ++ * anti.texi (Antinews): Mention M-x shell scrolling. ++ ++2007-01-05 Nick Roberts ++ ++ * building.texi (Watch Expressions): Describe gdb-max-children. ++ ++2007-01-04 Richard Stallman ++ ++ * msdog.texi (Windows Keyboard): Clarify previous change. ++ ++2007-01-02 Richard Stallman ++ ++ * custom.texi (Changing a Variable): Minor clarification. ++ (Specific Customization): customize-customized => customize-unsaved. ++ ++ * entering.texi (Entering Emacs): Clean up text about restarting ++ Emacs for each file. ++ ++ * misc.texi (Shell Options): Minor cleanup. ++ ++ * msdog.texi (Windows Keyboard): Explain that Windows was incompatible ++ with Emacs, not vice versa. ++ ++ * programs.texi (Symbol Completion): Recommend customizing ++ window manager. ++ ++ * xresources.texi (Resources): Minor fix. ++ ++2007-01-01 Jan Djärv ++ ++ * xresources.texi (Table of Resources): Add scrollBarWidth resource. ++ ++2007-01-01 Richard Stallman ++ ++ * commands.texi (User Input): Document keys stolen by window mangers. ++ ++2006-12-31 Richard Stallman ++ ++ * custom.texi (Specific Customization): Document customize-option ++ instead of customize-variable. ++ ++2006-12-31 Kim F. Storm ++ ++ * major.texi (Choosing Modes): Document auto-mode-case-fold. ++ ++2006-12-30 Kim F. Storm ++ ++ * killing.texi (CUA Bindings): Fix typo. ++ ++ * xresources.texi (Table of Resources): Mention grow-only value for ++ auto-resize-tool-bars. ++ ++2006-12-27 Eli Zaretskii ++ ++ * msdog.texi (Windows Keyboard): Mention widespread Windows bindings, ++ and how to get them back. ++ ++2006-12-26 Richard Stallman ++ ++ * calendar.texi (Holidays): Holiday listing is based on current ++ practice, but DST is not. ++ ++2006-12-25 Richard Stallman ++ ++ * emacs.texi (Top): Update subnode menus. ++ ++ * mark.texi (Transient Mark): Fix xref. ++ ++ * killing.texi (Graphical Kill): Node deleted. ++ (Killing): Add xref to Cut and Paste. ++ (CUA Bindings): Update xref. ++ ++ * frames.texi (Cut and Paste): New section to hold other nodes. ++ (Mouse Commands): Node demoted. ++ (Cut/Paste Other App): Split out from Mouse Commands. ++ (Word and Line Mouse): Likewise. ++ (Secondary Selection, Clipboard): Nodes demoted. ++ ++2006-12-24 Kevin Ryde ++ ++ * calendar.texi (Holidays): US daylight saving begins second Sunday ++ in March for 2007 onwards. ++ (Daylight Savings): Show new US default daylight saving rules, 2nd ++ Sun in Mar to 1st Sun in Nov, now in cal-dst.el. ++ ++2006-12-23 Chong Yidong ++ ++ * calendar.texi (Scroll Calendar): < and > are switched. ++ ++2006-12-23 Kevin Rodgers ++ ++ * killing.texi (Deletion): Describe M-\ prefix argument. ++ ++2006-12-23 Richard Stallman ++ ++ * search.texi (Regexp Search): Explain why forward and reverse regexp ++ search are not mirror images. ++ ++2006-12-19 Kim F. Storm ++ ++ * major.texi (Choosing Modes): Describe match-function elements for ++ magic-mode-alist. ++ ++2006-12-18 Eli Zaretskii ++ ++ * msdog.texi (Windows Keyboard): Add a footnote about "Windows" keys ++ peculiarities. ++ ++2006-12-18 Richard Stallman ++ ++ * abbrevs.texi (Editing Abbrevs): Fix previous change. ++ ++2006-12-17 Alan Mackenzie ++ ++ * programs.texi (Left Margin Paren): Remove the bit which says ++ that CC Mode sets open-paren-in-column-0-is-defun-start to nil. ++ Discuss some of the issues of setting this option to nil. ++ ++2006-12-17 Glenn Morris ++ ++ * abbrevs.texi (Editing Abbrevs): Mention system abbrevs. ++ ++2006-12-16 Eli Zaretskii ++ ++ * msdog.texi (Windows Keyboard): Clarify `w32-recognize-altgr' effect. ++ (Windows Files): `w32-get-true-file-attributes' is only relevant for ++ NTFS volumes. ++ (ls in Lisp): `links' in `ls-lisp-verbosity' is only relevant to NTFS ++ volumes. ++ ++2006-12-15 Eli Zaretskii ++ ++ * text.texi (HTML Mode): Fix "C-c TAB". ++ ++2006-12-09 Richard Stallman ++ ++ * misc.texi (Invoking emacsclient): Simplify TCP file text. ++ ++2006-12-08 Kevin Rodgers ++ ++ * files.texi (Misc File Ops): Document insert-file-literally. ++ ++2006-12-08 Eli Zaretskii ++ ++ * cmdargs.texi (Colors): Note that --color is intended for overriding ++ the terminal defaults, not for normal invocation. ++ ++ * misc.texi (Emacs Server): Improve wording. Don't mention the ++ ``server program''. Add a cross-reference to "Init File" node. ++ (Invoking emacsclient): Add index entries. Document both short and ++ long versions of command-line options. Document the -f option. ++ ++2006-12-06 Richard Stallman ++ ++ * text.texi (Outline Format): Say to set outline-regexp ++ and outline-level with major modes and file local variables. ++ ++2006-12-05 Michaël Cadilhac ++ ++ * anti.texi (Antinews): Mention the alternative to ++ `~/.emacs_SHELLNAME', which is `~/.emacs.d/init_SHELLNAME.sh'. ++ ++ * misc.texi (Interactive Shell): Ditto. ++ ++2006-12-04 Eli Zaretskii ++ ++ * emacs.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. ++ ++ * ack.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. ++ ++2006-12-01 Eli Zaretskii ++ ++ * mule.texi (Enabling Multibyte): Rephrase the confusing reference to a ++ colon in the mode line. ++ ++ * msdog.texi (Windows Processes) [@ifnottex]: Mention w32-shell-execute. ++ ++2006-11-26 Nick Roberts ++ ++ * building.texi (Watch Expressions): Mention SPC for expanding/ ++ contracting watch expressions. ++ ++2006-11-26 Kim F. Storm ++ ++ * kmacro.texi (Basic Keyboard Macro): Mention F3/F4 more. ++ ++2006-11-26 Nick Roberts ++ ++ * building.texi (Debugger Operation): Define text command mode. ++ Clarify how tooltips work. ++ (GDB Graphical Interface): Explain how to run in text command mode ++ more clearly. ++ ++2006-11-25 Juanma Barranquero ++ ++ * mule.texi (Defining Fontsets): Fix use of `charset' and `font'. ++ ++2006-11-22 Juanma Barranquero ++ ++ * anti.texi (Antinews): Mention --server-file and TCP sockets. ++ ++2006-11-18 Chong Yidong ++ ++ * misc.texi (Interactive Shell): INSIDE_EMACS is set to t, ++ and EMACS is deprecated. ++ ++2006-11-18 Juanma Barranquero ++ ++ * makefile.w32-in (emacs.dvi): Remove xresmini.texi. ++ ++2006-11-18 Jan Djärv ++ ++ * Makefile.in (emacs.dvi): Remove xresmini.texi. ++ ++ * emacs.texi: Include xresources.texi both for info and dvi. ++ ++ * xresources.texi: Merge text from xresmini.texi. ++ ++2006-11-12 Roberto Rodríguez (tiny change) ++ ++ * glossary.texi: Fix typos. ++ ++2006-11-06 Richard Stallman ++ ++ * emacs.texi (Acknowledgments): Fix name spelling, add Anna Bigatti. ++ ++ * ack.texi (Acknowledgments): Fix name spelling. ++ ++2006-11-01 Juri Linkov ++ ++ * search.texi (Word Search): Document incremental word search. ++ ++2006-10-28 Glenn Morris ++ ++ * ack.texi (Acknowledgments): Add cal-html author. ++ ++ * calendar.texi (Writing Calendar Files): Rename section (was "LaTeX ++ Calendar"). Describe new package cal-html. ++ * emacs.texi (Top): Rename old node "LaTeX Calendar" to "Writing ++ Calendar Files." ++ ++2006-10-23 Richard Stallman ++ ++ * abbrevs.texi (Expanding Abbrevs): Expansion happens only when ++ Abbrev mode is enabled. ++ ++2006-10-16 Richard Stallman ++ ++ * emacs.texi: Update ISBN. ++ ++2006-10-11 Kim F. Storm ++ ++ * emacs.texi (Acknowledgments): Use @dotless{i}. ++ ++2006-10-08 Nick Roberts ++ ++ * building.texi (Breakpoints Buffer): Mention catchpoints. ++ ++2006-10-08 Kim F. Storm ++ ++ * ack.texi (Acknowledgments): Update. ++ ++ * emacs.texi (Acknowledgments): Fix bad @/ form. ++ ++2006-10-05 Kim F. Storm ++ ++ * emacs.texi (Acknowledgments): Add more contributors. ++ ++2006-10-03 Richard Stallman ++ ++ * emacs.texi (Acknowledgments): Update version and edition. ++ ++2006-10-01 Karl Berry ++ ++ * custom.texi (Customization Groups): Page break to keep example buffer ++ on one page. ++ ++2006-09-30 Karl Berry ++ ++ * programs.texi (Basic Indent): @need to improve page break. ++ * text.texi: Rewording to improve page breaks, and use @LaTeX{}. ++ ++2006-09-29 Glenn Morris ++ ++ * calendar.texi (Date Formats): Doc fix for european-calendar-style. ++ ++2006-09-29 Karl Berry ++ ++ * windows.texi (Basic Window): Remove forced @break, no longer ++ desirable. ++ * frames.texi (Frame Commands), ++ * mark.texi (Marking Objects): Reword to avoid bad page break. ++ * display.texi (Auto Scrolling): Use @tie{} to avoid bad line break. ++ ++2006-09-19 Richard Stallman ++ ++ * frames.texi (Dialog Boxes): Clean up wording: avoid passive, ++ stick to present tense. ++ ++2006-09-18 Jan Djärv ++ ++ * frames.texi (Dialog Boxes): Rename x-use-old-gtk-file-dialog ++ to x-gtk-use-old-file-dialog. ++ (Dialog Boxes): Document x-gtk-file-dialog-help-text. ++ ++2006-09-15 Jay Belanger ++ ++ * emacs.texi (GNU GENERAL PUBLIC LICENSE): ++ Change "Library Public License" to "Lesser Public License" ++ throughout. Use "yyyy" to represent year. ++ ++2006-09-12 Reiner Steib ++ ++ * files.texi (Visiting): Add index entry "open file". ++ ++2006-09-11 Richard Stallman ++ ++ * building.texi (Compilation Mode): Clarification. ++ (Grep Searching): Add xref to Compilation Mode. ++ ++2006-09-08 Richard Stallman ++ ++ * search.texi (Search): Ref multi-file search commands here. ++ (Other Repeating Search): Not here. ++ ++2006-08-28 Richard Stallman ++ ++ * windows.texi (Split Window): Update xref. ++ ++ * basic.texi (Continuation Lines): Update xref. ++ ++ * indent.texi (Tab Stops): Update xref. ++ ++ * emacs.texi (Top): Update subnode menu. ++ ++ * display.texi (Line Truncation, Displaying Boundaries): New nodes, ++ split out of Display Custom. ++ ++2006-08-25 Kim F. Storm ++ ++ * display.texi (Display Custom): Add variables overline-margin ++ and x-underline-at-descent-line. ++ ++2006-08-25 Richard Stallman ++ ++ * entering.texi (Exiting): Rewrite to give graphical displays ++ priority over text terminals. ++ ++ * search.texi (Incremental Search): Move index entries. ++ ++2006-08-23 Chong Yidong ++ ++ * custom.texi (Init File): Reference Find Init to avoid "home ++ directory" confusion. ++ ++2006-08-22 Nick Roberts ++ ++ * building.texi (Other GDB-UI Buffers): Describe how to edit ++ a value in the locals buffer. ++ ++2006-08-21 Richard Stallman ++ ++ * search.texi (Basic Isearch): Add `isearch' index entry. ++ ++2006-08-16 Richard Stallman ++ ++ * misc.texi (Saving Emacs Sessions): Clean up wording. ++ ++ * mark.texi (Marking Objects): Mention term "select all". ++ ++ * emacs.texi (Top): Update subnode menu. ++ ++ * help.texi (Help Mode): Move node up in file. ++ ++2006-08-15 Nick Roberts ++ ++ * building.texi (Stack Buffer): Explain fringe arrow. ++ ++2006-08-12 Eli Zaretskii ++ ++ * misc.texi (Saving Emacs Sessions): Clarify when desktop is restored ++ on startup. ++ ++2006-08-11 Romain Francoise ++ ++ * ack.texi (Acknowledgments): Delete mention to zone-mode.el. ++ ++2006-08-10 Sven Joachim (tiny change) ++ ++ * mule.texi (Recognize Coding, Text Coding): Fix typos. ++ ++2006-08-10 Richard Stallman ++ ++ * text.texi (Format Faces): Substantial rewrites to deal ++ with face merging. Empty regions don't count. Clarify ++ face property inheritance. ++ ++2006-08-08 Romain Francoise ++ ++ * dired.texi (Marks vs Flags): Fix typo reported by Ari Roponen ++ . ++ ++2006-08-04 Eli Zaretskii ++ ++ * cmdargs.texi (Window Size X) <--geometry>: Only width and height ++ apply to all frames. ++ ++2006-08-01 Richard Stallman ++ ++ * help.texi (Name Help): Add index entries for describe-variable. ++ ++2006-08-01 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Shorten node names. ++ (GDB-UI Layout): Use GDB-related. ++ (Other GDB-UI Buffers): Simplify English. ++ ++2006-07-31 Richard Stallman ++ ++ * search.texi (Query Replace): Add xref for Dired's Q command. ++ ++2006-07-31 Nick Roberts ++ ++ * building.texi (GDB commands in Fringe): Rename to... ++ (Source Buffers): ..this and move forward. Describe hollow arrow and ++ new option gdb-find-source-frame. ++ ++2006-07-29 Richard Stallman ++ ++ * dired.texi (Operating on Files): Simplify previous change ++ and fix Texinfo usage. ++ ++2006-07-29 Eli Zaretskii ++ ++ * dired.texi (Operating on Files): Add cross-references. State the ++ Unix commands that do similar things. ++ ++2006-07-28 Richard Stallman ++ ++ * mark.texi (Transient Mark): Clarify that region never disappears ++ when Transient Mark mode is off, and not when it is on. ++ ++2006-07-27 Richard Stallman ++ ++ * search.texi (Non-ASCII Isearch): Clarify. Mention C-q. ++ ++2006-07-24 Richard Stallman ++ ++ * xresources.texi (GTK styles): Fix texinfo usage. ++ ++ * commands.texi (User Input): Explain why we teach keyboard cmds. ++ ++ * xresources.texi, xresmini.texi, search.texi, programs.texi: ++ * misc.texi, kmacro.texi, killing.texi, glossary.texi: ++ * fortran-xtra.texi, files.texi, emacs.texi, emacs-xtra.texi: ++ * doclicense.texi, display.texi, dired.texi, basic.texi: ++ * anti.texi, ack.texi: Move periods and commas inside quotes. ++ ++2006-07-22 Eli Zaretskii ++ ++ * cmdargs.texi (General Variables): Document EMAIL. ++ ++2006-07-21 Eli Zaretskii ++ ++ * frames.texi (Frame Commands): Mention that focus-follows-mouse ++ doesn't have effect on MS-Windows. ++ ++2006-07-17 Richard Stallman ++ ++ * building.texi (Grep Searching): Explain about chaining grep commands. ++ ++2006-07-10 Nick Roberts ++ ++ * killing.texi, mini.texi: Fix typos. ++ ++2006-07-09 Chong Yidong ++ ++ * misc.texi (Invoking emacsclient): Document behavior when emacsclient ++ is invoked for multiple files. ++ ++2006-07-08 Eli Zaretskii ++ ++ * msdog.texi (Windows Keyboard) [@iftex]: Add an @inforef to the ++ on-line manual for the rest of this node. ++ (Windows Mouse) : Include ++ unconditionally. ++ (Windows Processes) : Include unconditionally. ++ Improve wording. ++ (Windows Printing): Improve wording. ++ (Windows Misc) [@iftex]: Add an @inforef to the on-line manual for the ++ rest of this node. ++ ++2006-07-05 Thien-Thi Nguyen ++ ++ * building.texi (Lisp Eval): Throughout, replace eval-current-buffer ++ with eval-buffer. ++ ++2006-07-05 Nick Roberts ++ ++ * mule.texi (Coding Systems, Specify Coding): Link descriptions ++ of character translation. ++ ++2006-07-04 Nick Roberts ++ ++ * rmail.texi (Remote Mailboxes): Add missing @code keyword. ++ ++2006-07-03 Karl Berry ++ ++ * emacs.texi (\hbadness): Set to 6000 so we aren't bothered by ++ not-too-underfull hboxes in the TeX output. ++ * abbrevs.texi, buffers.texi, building.texi, calendar.texi, ++ * cmdargs.texi, custom.texi, dired.texi, macos.texi, ++ * maintaining.texi, misc.texi, mule.texi, programs.texi, rmail.texi, ++ * sending.texi, text.texi: Fix overfull/underfull boxes. ++ ++2006-07-03 Romain Francoise ++ ++ * m-x.texi (M-x): Fix. ++ ++2006-07-03 Richard Stallman ++ ++ * search.texi (Other Repeating Search): filename -> file name. ++ ++ * misc.texi (Narrowing): Minor cleanups. ++ ++ * files.texi (Visiting): filename -> file name. ++ ++ * emacs.texi (Top): Update subnode menus. ++ ++ * mule.texi (Coding Systems): Move char translation stuff here. ++ (Specify Coding, Output Coding): New nodes, out of Recognize Coding. ++ (Recognize Coding): Substantial local rewrites. ++ (International): Update menu. ++ ++ * display.texi (Auto Scrolling): New node, broken out of Scrolling. ++ (Scrolling): Substantial local rewrites. ++ (Display): Update menu and intro. ++ ++ * dired.texi: filename -> file name. ++ ++ * custom.texi (Safe File Variables): Texinfo usage fix. ++ ++2006-07-03 Teodor Zlatanov ++ ++ * help.texi, m-x.texi: Lots of cleanups. ++ ++2006-06-30 Eli Zaretskii ++ ++ * msdog.texi (ls in Lisp, Windows Keyboard, Windows Mouse) ++ (Windows Processes, Windows Misc): Shorten the printed version by ++ selectively conditioning less important portions by @ifnottex. ++ ++2006-06-27 Richard Stallman ++ ++ * mini.texi (Minibuffer File): Minor cleanup. ++ ++2006-06-25 Nick Roberts ++ ++ * frames.texi (XTerm Mouse): Rename to... ++ (Text-Only Mouse): ...this. Mention t-mouse-mode. ++ ++ * emacs.texi (Top): Use new node name. ++ ++2006-06-24 Eli Zaretskii ++ ++ * emacs.texi (Top): Update the detailed menu according to changes in ++ msdog.texi. ++ ++ * msdog.texi (Windows Keyboard): New section. ++ (Windows Mouse): New section. ++ (Windows System Menu): Remove section (text merged with "Windows ++ Keyboard"). ++ (Windows Misc): New section. ++ ++ * dired.texi (Dired Enter): Refer to msdog.texi for ls-lisp emulation. ++ ++ * msdog.texi (ls in Lisp): New section. ++ ++ * files.texi (Visiting): Document case-insensitive wildcard matching ++ under find-file-wildcards. ++ ++2006-06-16 YAMAMOTO Mitsuharu ++ ++ * macos.texi (Mac Input): Add description of mac-function-modifier. ++ Now Unicode keyboard layouts work. ++ ++2006-06-10 Richard Stallman ++ ++ * mule.texi (Recognize Coding): Clarify previous change. ++ ++2006-06-09 Kenichi Handa ++ ++ * mule.texi (Recognize Coding): Describe the convention of "CODING!" ++ notation. ++ ++2006-06-07 Kevin Ryde ++ ++ * mule.texi (Coding Systems): Footnote xref "MS-DOS and MULE" in main ++ manual for @ifnottex, but in emacs-extra for @iftex. ++ ++ * cmdargs.texi (General Variables): Fix smtpmail xref. ++ ++2006-05-29 Stefan Monnier ++ ++ * programs.texi (Comment Commands): ++ * custom.texi (Specifying File Variables): ++ Use ;; instead of ;;; to better follow coding conventions. ++ ++2006-06-07 Nick Roberts ++ ++ * building.texi (Watch Expressions): Move node to end. ++ (GDB Graphical Interface): Move description of clicks in fringe... ++ (GDB commands in the Fringe): ...to here. New node. ++ ++2006-06-05 Romain Francoise ++ ++ * xresmini.texi (GTK resources): Fix various typos. ++ ++2006-06-05 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Update bindings. ++ (Commands of GUD): Add gud-print. Remove gud-run. ++ Restate availability more generally. ++ ++2006-06-03 Teodor Zlatanov ++ ++ * mini.texi: Lots of cleanups. ++ ++2006-06-01 Luc Teirlinck ++ ++ * misc.texi (Shell History Copying): Update descriptions of `C-c RET' ++ and Mouse-2. ++ ++2006-06-01 Jan Djärv ++ ++ * screen.texi (Menu Bar): Change menu-bar-start to menu-bar-open. ++ ++2006-05-31 Richard Stallman ++ ++ * basic.texi (Moving Point): Fix previous change. ++ ++2006-05-29 Jan Djärv ++ ++ * screen.texi (Menu Bar): F10 for Gtk+/Lesstif/Lucid menus. ++ ++2006-05-28 Teodor Zlatanov ++ ++ * basic.texi: Many simplifications and improvements in wording. ++ ++2006-05-26 Nick Roberts ++ ++ * anti.texi (Antinews): Create a node for gdb-ui. ++ ++2006-05-22 Reiner Steib ++ ++ * frames.texi (Menu Bars, Tool Bars): Add index entries. ++ ++2006-05-20 Richard Stallman ++ ++ * dired.texi (Dired Navigation): dired-goto-file is now j. ++ ++2006-05-20 Eli Zaretskii ++ ++ * mule.texi (Coding Systems): Mention the undecided-* coding systems ++ and their aliases. ++ ++ * msdog.texi (Windows Printing): Mention non-support of plain text ++ printing with some el-cheapo printers, and suggest a workaround. ++ ++2006-05-20 Kevin Ryde ++ ++ * text.texi (TeX Print): tex-dvi-view-command has a default value, ++ remove the bit saying you must set it. ++ ++2006-05-19 Luc Teirlinck ++ ++ * trouble.texi (Checklist): ++ * text.texi (Text, Auto Fill, Text Mode): ++ * search.texi (Nonincremental Search): ++ * rmail.texi (Rmail Labels): ++ * mule.texi (Input Methods, Multibyte Conversion): ++ * misc.texi (Gnus, Where to Look, PostScript): ++ * maintaining.texi (Create Tags Table): ++ * indent.texi (Indentation Commands): ++ * fixit.texi (Spelling): ++ * emacs.texi (Copying): ++ * custom.texi (Init File): ifinfo -> ifnottex. ++ ++2006-05-17 Richard Stallman ++ ++ * files.texi (Diff Mode): Mention C-x `. ++ ++2006-05-08 Richard Stallman ++ ++ * custom.texi (Disabling): Textual cleanups. ++ ++2006-05-12 Glenn Morris ++ ++ * calendar.texi (Displaying the Diary, Format of Diary File): ++ Refer to diary-view-entries, diary-list-entries, ++ diary-show-all-entries rather than obsolete aliases. ++ ++2006-05-12 Eli Zaretskii ++ ++ * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) ++ (Displaying the Diary, Special Diary Entries, Importing Diary): ++ * building.texi (Compilation Shell): ++ * buffers.texi (Several Buffers) [iftex]: Replace @xref's to ++ emacs-xtra with @inforef's. ++ ++ * files.texi (Visiting): Fix wording. ++ ++ * mule.texi (Coding Systems, Text Coding): More indexing. ++ Mention that C-x RET f can set eol conversion. ++ ++2006-05-07 Jan Djärv ++ ++ * xresmini.texi (GTK resources): Insert GTK description. ++ ++ * xresources.texi (GTK resources): metafont should be menufont. ++ ++2006-05-06 Michael Albinus ++ ++ * mini.texi (Completion Options): Completion of remote files' ++ method, user name and host name is active only in partial ++ completion mode. ++ ++2006-05-06 Eli Zaretskii ++ ++ * makefile.w32-in (emacs.dvi): ++ * Makefile.in (emacs.dvi): Add xresmini.texi. ++ ++ * xresmini.texi (Table of Resources): Remove xref to non-existent ++ node "LessTif Resources". ++ ++ * msdog.texi (Microsoft Windows): ++ * calendar.texi (Calendar/Diary, Displaying the Diary) ++ (Special Diary Entries, Importing Diary, Holidays): ++ * programs.texi (Program Modes): ++ * text.texi (Text): ++ * buffers.texi (Several Buffers): ++ * files.texi (Comparing Files): Fix cross-references to emacs-xtra. ++ ++2006-05-06 Eli Zaretskii ++ ++ The following changes merge the emacs-xtra manual into the main ++ manual, but only for on-line version of the manual. ++ ++ * vc2-xtra.texi (Version Backups, Local Version Control) ++ (Making Snapshots, Change Logs and VC, Version Headers) ++ (Customizing VC, CVS Options) [ifnottex]: Conditional xref's for ++ on-line manual. ++ ++ * vc1-xtra.texi (VC Dired Mode) [ifnottex]: Conditional xref's ++ for on-line manual. ++ ++ * msdog-xtra.texi (MS-DOS, MS-DOS Keyboard, MS-DOS Mouse) ++ (MS-DOS Display, MS-DOS File Names, MS-DOS Printing) ++ (MS-DOS and MULE, MS-DOS Processes) [ifnottex]: Conditional xref's ++ for on-line manual. ++ ++ * fortran-xtra.texi (Fortran, Fortran Autofill) ++ (Fortran Autofill, Fortran Abbrev) [ifnottex]: Conditional xref's ++ for on-line manual. ++ ++ * picture-xtra.texi (Basic Picture, Rectangles in Picture) [ifnottex]: ++ Conditional xref's for on-line manual. ++ ++ * emerge-xtra.texi (Emerge, Overview of Emerge) ++ (Fine Points of Emerge) [ifnottex]: Conditional xref's for on-line ++ manual. ++ ++ * Makefile.in (INFO_TARGETS): Remove ../info/emacs-xtra. ++ (EMACS_XTRA): New variable, lists the new *-xtra.texi files. ++ (EMACSSOURCES): Use EMACS_XTRA. ++ (../info/emacs-xtra): Remove. ++ (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. ++ ++ * makefile.w32-in (INFO_TARGETS): Remove $(infodir)/emacs-xtra. ++ (EMACS_XTRA): New variable, lists the new *-xtra.texi files. ++ (EMACSSOURCES): Use EMACS_XTRA. ++ ($(infodir)/emacs-xtra): Remove. ++ (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. ++ ++ * trouble.texi (Quitting): ++ * text.texi (Text): ++ * programs.texi (Program Modes): ++ * msdog.texi (Microsoft Windows): ++ * frames.texi (Frames): ++ * files.texi (Backup, Version Control, VC Concepts) ++ (Types of Log File, Advanced C-x v v, Log Buffer, Old Versions) ++ (Registering, VC Status, VC Undo, Multi-User Branching) ++ (Comparing Files): ++ * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) ++ (Displaying the Diary, Special Diary Entries, Importing Diary): ++ * buffers.texi (Several Buffers): Replace inforef to emacs-xtra by ++ conditional xref's, depending on @iftex/@ifnottex. ++ ++ * msdog.texi (Microsoft Windows) [ifnottex]: Add menu entry for ++ "MS-DOS". @include msdog-xtra.texi. ++ ++ * programs.texi (Programs) [ifnottex]: Add menu entry for "Fortran". ++ [ifnottex]: @include fortran-xtra.texi. ++ ++ * files.texi (Secondary VC Commands) [ifnottex]: Add menu entries ++ for vc-xtra.texi subsections. ++ (VC Undo) [ifnottex]: @include vc1-xtra.texi and @lowersections it. ++ (Multi-User Branching) [ifnottex]: @include vc2-xtra.texi. ++ ++ * sending.texi (Sending Mail): A @node line without explicit Prev, ++ Next, and Up links. ++ ++ * abbrevs.texi (Abbrevs): A @node line without explicit Prev, ++ Next, and Up links. ++ ++ * emacs.texi (Top) [ifnottex]: Add menu entries for "Picture Mode" ++ and its sections. @include picture-xtra.texi. ++ ++ * maintaining.texi (Maintaining) [ifnottex]: Add menu entry for ++ "Emerge". ++ (List Tags) [ifnottex]: @include emerge-xtra.texi. ++ ++ * cal-xtra.texi (Daylight Savings): Remove this node: it is an ++ exact duplicate of its name-sake in calendar.texi. ++ ++ * calendar.texi (Calendar/Diary) [ifnottex]: Add menu item for ++ "Advanced Calendar/Diary Usage". ++ (Time Intervals) [ifnottex]: @include cal-xtra.texi. ++ ++ * dired.texi (Subdirectories in Dired) [ifnottex]: @include ++ dired-xtra.texi. ++ (Dired) [ifnottex]: Add menu entry for "Subdir Switches". ++ ++ * files.texi (Reverting) [ifnottex]: @include arevert-xtra.texi. ++ (Files) [ifnottex]: Add menu entry for Autorevert. ++ ++ * emacs-xtra.texi (Introduction): Reword to make consistent with ++ printed version only. ++ : Remove the body of all chapters and move them to the ++ new *-xtra.texi files. Use @raisesections and @lowersections to ++ convert sections to chapters etc. ++ ++ * msdog-xtra.texi: ++ * fortran-xtra.texi: ++ * vc-xtra.texi: ++ * vc1-xtra.texi: ++ * vc2-xtra.texi: ++ * emerge-xtra.texi: ++ * cal-xtra.texi: ++ * dired-xtra.texi: ++ * arevert-xtra.texi: New files, with text from respective chapters ++ of emacs-xtra.texi. Convert each @chapter into @section, @section ++ into @subsection, etc. ++ ++ * emacs-xtra.texi (MS-DOS): Renamed from "MS-DOG". All references ++ updated. ++ ++ * msdog.texi (Microsoft Windows): Rename from "Emacs and Microsoft ++ Windows". All references updated. ++ ++2006-05-06 YAMAMOTO Mitsuharu ++ ++ * macos.texi (Mac Input): Mention input from Character Palette. ++ (Mac Font Specs): Fix typo. ++ ++2006-05-05 Richard Stallman ++ ++ * files.texi (Diff Mode): Minor cleanup. ++ ++2006-05-05 Karl Berry ++ ++ * emacs.texi: Call @fonttextsize 10, inside @tex to avoid ++ errors from the current release of makeinfo (4.8). ++ * help.texi (Library Keywords): Change widest word in multitable ++ template from `emulations' to `convenience'. (Not sure if this is ++ related to the font change.) ++ ++2006-05-05 Eli Zaretskii ++ ++ * files.texi (File Names): Add a footnote about limited support of ++ ~USER on MS-Windows. ++ ++ * cmdargs.texi (Initial Options): Add a footnote about limited ++ support of ~USER on MS-Windows. ++ ++2006-05-03 Richard Stallman ++ ++ * files.texi (Diff Mode): Node moved here. ++ (Comparing Files): Delete what duplicates new node. ++ (Files): Put Diff Mode in menu. ++ ++ * misc.texi (Diff Mode): Moved to files.texi. ++ ++ * emacs.texi (Top): Update menu for Diff Mode. ++ ++ * trouble.texi (Emergency Escape): Simplify. ++ ++ * emacs.texi (Top): Minor clarification. ++ ++2006-05-03 Teodor Zlatanov ++ ++ * commands.texi, entering.texi, screen.texi: Many simplifications. ++ ++2006-05-03 Richard Stallman ++ ++ * commands.texi (Text Characters): Delete paragraph about unibyte ++ non-ASCII printing chars. ++ ++ * killing.texi (Killing): Say "graphical displays". ++ * display.texi: Say "graphical displays". ++ ++ * cmdargs.texi (Misc X): Say "graphical displays". ++ ++2006-05-01 Richard Stallman ++ ++ * emacs.texi (Top): Add Diff Mode to menu. ++ ++2006-05-01 Aaron S. Hawley ++ ++ * misc.texi (Diff Mode): New node. ++ ++2006-05-01 YAMAMOTO Mitsuharu ++ ++ * macos.texi (Mac International): Now Carbon Emacs has ATSUI support. ++ (Mac Environment Variables): Shorten example line. ++ (Mac Font Specs): Shorten lisp lines. Add descriptions for ATSUI. ++ ++2006-05-01 Nick Roberts ++ ++ * building.texi (GUD Customization): Describe cases %d and %c. ++ Update description for %e. ++ ++2006-04-30 Glenn Morris ++ ++ * calendar.texi (LaTeX Calendar): Mention cal-tex-preamble-extra. ++ ++2006-04-29 Dan Nicolaescu ++ ++ * custom.texi (Examining): Update C-h v output example. ++ ++2006-04-29 Kim F. Storm ++ ++ * building.texi (Grep Searching): Add lgrep and rgrep. ++ ++2006-04-23 Richard Stallman ++ ++ * emacs.texi [TeX]: Use xresmini.texi instead of xresources.texi. ++ ++ * xresmini.texi: New file. ++ ++ * xresources.texi (Face Resources): Split table into font resources ++ and the rest. Combine similar attributes for brevity. ++ ++2006-04-21 Eli Zaretskii ++ ++ * emacs-xtra.texi (MS-DOS File Names): Remove section about ++ backslashes and case-insensitivity in file names (moved to the ++ main manual). ++ (MS-DOS Printing): Move most of the text to the main manual. ++ ++ * msdog.texi (Windows Files, Windows HOME, MS-Windows Printing): ++ New nodes. ++ (Windows Processes, Windows System Menu): Add index entries and ++ fix wording. ++ ++2006-04-18 J.D. Smith ++ ++ * misc.texi (Shell Ring): Add notes on saved input when ++ navigating off the end of the history list. ++ ++2006-04-18 Chong Yidong ++ ++ * misc.texi (Shell Options): Correct default value of ++ comint-scroll-show-maximum-output. ++ ++2006-04-18 Nick Roberts ++ ++ * building.texi (Watch Expressions): Update. ++ ++2006-04-12 Richard Stallman ++ ++ * search.texi: Clean up previous change. ++ ++2006-04-12 Eli Zaretskii ++ ++ * search.texi (Regexp Backslash, Regexp Replace): Add index ++ entries for ``back reference'' and mention the term itself in the ++ text. ++ ++2006-04-11 Richard Stallman ++ ++ * custom.texi (Safe File Variables): ++ Document enable-local-variables = :safe. ++ ++2006-04-11 Karl Berry ++ ++ * emacs-xtra.texi, emacs.texi (Dired under VC, VC Dired Commands) ++ (Remote Repositories, Version Backups, Local Version Control) ++ (Snapshots, Making and Using Snapshots, Snapshot Caveats) ++ (Miscellaneous Commands and Features of VC, Change Logs and VC) ++ (Renaming VC Work Files and Master Files) ++ (Inserting Version Control Headers, Customizing VC, General Options) ++ (Options for RCS and SCCS, Options specific for CVS): Move all ++ these nodes to emacs-xtra.texi, for brevity. ++ * cmdargs.texi, files.texi: Change cross-references. ++ ++2006-04-11 J.D. Smith ++ ++ * files.texi (Old Versions): Update description of vc-annotate's ++ use of color to indicate date ranges. ++ ++2006-04-09 Kevin Ryde ++ ++ * sending.texi (Mail Sending): In send-mail-function @pxref smtpmail, ++ put info and printed manual names the right way around. ++ ++2006-04-09 Karl Berry ++ ++ * msdog.texi, emacs-xtra.texi: Move all the MS-DOS material to ++ emacs-xtra.texi, leaving only MS Windows information. ++ * building.texi, emacs.texi, frames.texi, gnu.texi, macos.texi, ++ * msdog.texi, mule.texi, trouble.texi: Change cross-references and ++ node names. ++ ++ * emacs.texi: Move @summarycontents and @contents to the beginning ++ of the file. ++ ++2006-04-08 Kevin Ryde ++ ++ * text.texi (Fill Commands): fill-nobreak-predicate is now a hook. ++ ++2006-04-07 Richard Stallman ++ ++ * programs.texi (Comments, Comment Commands, Options for Comments) ++ (Multi-Line Comments): "Align", not "indent". ++ (Basic Indent): C-j deletes trailing whitespace before the newline. ++ ++2006-04-06 Richard Stallman ++ ++ * programs.texi (Basic Indent): Clarify relationship of C-j to TAB. ++ ++2006-04-06 Eli Zaretskii ++ ++ * killing.texi (Rectangles): Add index entry for marking a rectangle. ++ ++2006-04-05 Richard Stallman ++ ++ * emacs.texi (Top): Update subnode menu. ++ ++ * trouble.texi (Unasked-for Search): Node deleted. ++ (Lossage): Delete from menu. ++ ++2006-04-04 Richard Stallman ++ ++ * trouble.texi: Various cleanups. ++ (Checklist): Don't bother saying how to snail a bug report. ++ (Emergency Escape): Much rewriting. ++ (After a Crash): Rename the core dump immediately. ++ (Total Frustration): Call it a psychotherapist. ++ (Bug Criteria): Avoid "illegal instruction". ++ (Sending Patches): We always put the contributor's name in. ++ ++ * misc.texi (Thumbnails): Minor correction. ++ ++2006-04-03 Richard Stallman ++ ++ * misc.texi (Thumbnails): Minor cleanup. ++ ++2006-04-02 Karl Berry ++ ++ * sending.texi (Mail Sending): pxref to Top needs five args. ++ ++ * texinfo.tex: Update to current version (2006-03-21.13). ++ ++2006-03-31 Richard Stallman ++ ++ * emacs.texi (Top): Update subnode menu. ++ ++ * help.texi (Help Mode): Cleanup. ++ ++ * dired.texi: Many cleanups. ++ (Dired Deletion): Describe dired-recursive-deletes. ++ (Operating on Files): dired-create-directory moved. ++ (Misc Dired Features): Move to here. ++ (Tumme): Node moved to misc.texi. ++ ++ * custom.texi: Many cleanups. ++ (Minor Modes): Don't mention ISO Accents Mode. ++ (Examining): Update C-h v output example. ++ (Hooks): Add index and xref for add-hook. ++ (Locals): Delete list of vars that are always per-buffer. Rearrange. ++ (Local Keymaps): Don't mention lisp-mode-map, c-mode-map. ++ ++ * misc.texi: Many cleanups. ++ (beginning): Add to summary of topics. ++ (Shell): Put eshell xref at the end. Remove eshell from table. ++ (Thumbnails): New node. ++ ++2006-03-28 Eli Zaretskii ++ ++ * files.texi (File Name Cache): Make it clear that the cache is ++ not persistent. ++ ++2006-03-25 Karl Berry ++ ++ * emacs-xtra.texi, emacs.texi, gnu.texi: ++ (1) use @copyright{} instead of (C) in typeset text; ++ (2) do not indent copyright year list (or anything else). ++ ++2006-03-21 Juanma Barranquero ++ ++ * files.texi (VC Dired Mode): Remove misplaced brackets. ++ ++2006-03-21 Andre Spiegel ++ ++ * files.texi: Various updates and clarifications in the VC chapter. ++ ++2006-03-19 Luc Teirlinck ++ ++ * help.texi (Help Mode): Document "C-c C-c". ++ ++2006-03-16 Luc Teirlinck ++ ++ * emacs-xtra.texi (Top): Avoid ugly continuation line in ++ menu in the standalone Info reader. ++ ++2006-03-15 Chong Yidong ++ ++ * emacs-xtra.texi (Emerge, Picture Mode, Fortran): New chapters, ++ moved here from Emacs manual. ++ ++ * programs.texi (Fortran): Section moved to emacs-xtra. ++ (Program Modes): Xref to Fortran in emacs-xtra. ++ ++ * maintaining.texi (Emerge): Move to emacs-xtra. ++ * files.texi (Comparing Files): Xref to Emerge in emacs-xtra. ++ ++ * picture.texi: File deleted. ++ * Makefile.in: ++ * makefile.w32-in: Remove picture.texi. ++ ++ * text.texi (Text): Xref to Picture Mode in emacs-xtra. ++ * abbrevs.texi (Abbrevs): ++ * sending.texi (Sending Mail): Picture node removed. ++ ++ * emacs.texi (Top): Update node listings. ++ ++2006-03-12 Richard Stallman ++ ++ * calendar.texi: Various cleanups. ++ ++2006-03-11 Luc Teirlinck ++ ++ * search.texi (Regexps): Use @samp for regexp that is not in Lisp ++ syntax. ++ ++2006-03-08 Luc Teirlinck ++ ++ * search.texi (Regexps): More accurately describe which characters ++ are special in which situations. Recommend _not_ to quote `]' or ++ `-' when they are not special. ++ ++2006-02-28 Andre Spiegel ++ ++ * files.texi (Old Versions): Clarify operation of C-x v =. ++ ++2006-02-21 Nick Roberts ++ ++ * building.texi (Watch Expressions): Update and describe ++ gdb-speedbar-auto-raise. ++ ++2006-02-19 Richard M. Stallman ++ ++ * emacs.texi: Use @smallbook. ++ (Top): Update ref to Emacs paper, delete ref to Cookbook. ++ Update subnode menu. ++ ++ * building.texi (Lisp Interaction): Minor addition. ++ ++2006-02-18 Nick Roberts ++ ++ * building.texi (Watch Expressions): Update and be more precise. ++ ++2006-02-15 Francesco Potortì ++ ++ * maintaining.texi (Create Tags Table): Explain why the ++ exception when etags writes to files under the /dev tree. ++ ++2006-02-14 Richard M. Stallman ++ ++ * custom.texi (Safe File Variables): Lots of clarification. ++ Renamed from Unsafe File Variables. ++ ++2006-02-14 Chong Yidong ++ ++ * custom.texi (Unsafe File Variables): File variable confirmation ++ assumed denied in batch mode. ++ ++2006-02-14 Richard M. Stallman ++ ++ * building.texi (GDB User Interface Layout): Don't say `inferior' ++ for program being debugged. ++ ++2006-02-15 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): ++ Replace gdb-use-inferior-io-buffer with gdb-use-separate-io-buffer. ++ ++2006-02-13 Chong Yidong ++ ++ * custom.texi (Specifying File Variables, Unsafe File Variables): ++ New nodes, split from File Variables. Document new file local ++ variable behavior. ++ ++2006-02-13 YAMAMOTO Mitsuharu ++ ++ * display.texi (Standard Faces): ++ * files.texi (Visiting): ++ * frames.texi (Clipboard): ++ * glossary.texi (Glossary) : ++ * xresources.texi (X Resources): Mention Mac OS port. ++ ++2006-02-12 Richard M. Stallman ++ ++ * building.texi (Building): Clarify topic in intro. ++ ++ * maintaining.texi (Maintaining): Change title; clarify topic. ++ Delete duplicate index entries. ++ ++ * building.texi (Other GDB User Interface Buffers): Clarifications. ++ ++ * text.texi (Cell Commands): Clarifications. ++ ++ * programs.texi (Defuns): Delete duplicate explanation of ++ left-margin paren convention. ++ (Hungry Delete): Minor cleanup. ++ ++2006-02-11 Mathias Dahl ++ ++ * dired.texi (Tumme): More tumme documentation. ++ ++2006-02-11 Alan Mackenzie ++ ++ * programs.texi ("Hungry Delete"): Correct the appellation of the ++ backspace and delete keys to @kbd{DEL} and @kbd{DELETE}. ++ ++2006-02-11 Mathias Dahl ++ ++ * dired.texi (Tumme): Fix small bug. ++ ++2006-02-10 YAMAMOTO Mitsuharu ++ ++ * macos.texi (Mac International): Rename "fontset-mac" to ++ "fontset-standard". ++ ++2006-02-09 Mathias Dahl ++ ++ * dired.texi (Tumme): Basic documentation for Tumme added. ++ ++2006-02-07 Luc Teirlinck ++ ++ * mule.texi (International): ++ * programs.texi (Basic Indent): Fix typos. ++ ++ * custom.texi (Minor Modes): ++ * display.texi (Text Display): ++ * commands.texi (Text Characters): Update xrefs. ++ ++2006-02-07 Richard M. Stallman ++ ++ * emacs.texi (Top): Update subnode menu. ++ Update info on old Emacs papers. ++ (Intro): "Graphical display", not window system. ++ ++ * xresources.texi (GTK styles): Minor clarifications. ++ ++ * trouble.texi: "Graphical display", not window system. ++ (Stuck Recursive): Minor clarification. ++ ++ * text.texi: Minor clarifications. ++ (Sentences): Explain why two-space convention is better. ++ Explain sentence-end-without-period here. ++ (Fill Commands): Not here. ++ (Refill): Node moved down. ++ (Filling): Update menu. ++ (Table Creation, Cell Justification, Column Commands): Clarify. ++ ++ * sending.texi: Minor clarifications. ++ ++ * search.texi (Regexp Backslash): Clarification. ++ ++ * rmail.texi: Minor cleanups. ++ (Rmail): Delete digression about `rmail-mode'. ++ (Rmail Inbox): Delete false advice wrt rmail-primary-inbox-list. ++ (Rmail Files): Mention C-u M-x rmail. ++ (Rmail Reply): Mention References. ++ (Rmail Display): Mention rmail-nonignored-headers. ++ ++ * programs.texi: Minor cleanups. ++ (Comment Commands): Mention momentary Transient Mark mode. ++ (Matching): Be more specific about customizing show-paren-mode. ++ (Info Lookup): Don't list the modes that support C-h S. ++ Just say what it does in an unsupported mode. ++ (Man Page): Delete excessive info on customizing woman. ++ (Motion in C): Don't mention c-for/backward-into-nomenclature. ++ ++ * abbrevs.texi: Minor clarifications. ++ (Dabbrev Customization): Talk about "dynamic abbrev expansion", ++ not "dynamic abbrevs" as if they were a kind of abbrev. ++ ++ * picture.texi (Picture): Minor cleanup. ++ ++ * mule.texi (Communication Coding): Say "other applications". ++ (Fontsets): Not specific to X. Add xref to X Resources. ++ (Unibyte Mode): Rename from Single-Byte Character Support. ++ "Graphical display", not window system. ++ (International): Update menu. ++ ++ * maintaining.texi (Format of ChangeLog): ++ New node, split out from ChangeLog. ++ (ChangeLog): Clarifications in the remaining text. ++ (Create Tags Table, Etags Regexps, Select Tags Table): Cleanups. ++ (Find Tag): Add @w. ++ (Tags Search): Explain tag table order here. Simplify grep ref. ++ (List Tags): tags-tag-face is a variable, not a face. ++ (Emerge): Cleanups. ++ ++ * kmacro.texi (Keyboard Macro Counter): Rewrite for clarity. ++ (Keyboard Macros): Avoid "the user". ++ ++ * killing.texi: "Graphical display", not window system. ++ ++ * help.texi (Help Echo): "Graphical display", not window system. ++ ++ * glossary.texi: Say "you", not "the user". Say "graphical display". ++ ++ * frames.texi: Minor cleanups. "Graphical display", not window system. ++ ++ * files.texi (Visiting): Make drag-and-drop not X-specific. ++ ++ * custom.texi: Minor cleanups. "Graphical display", not window system. ++ ++ * cmdargs.texi: Minor cleanups. ++ ++ * building.texi (Compilation): Move and split kill-compilation para. ++ Add para about multiple compilers. ++ (Compilation Mode): Commands also available in grep mode and others. ++ Mention C-u C-x ` more tutorially. Clarify C-x `. ++ (Compilation Shell): Clarify. Put Bash example first. ++ (Grep Searching): Minor cleanups; add @w. ++ (Debuggers): Minor cleanups. ++ (Starting GUD): Make GDB xgraphical mode issue clearer. ++ (Debugger Operation): Lots of clarifications including ++ GDB tooltip side-effect issue. ++ (Commands of GUD): Clarify. ++ (GUD Customization): Add bashdb-mode-hook. ++ (GDB Graphical Interface): Rewrite for clarity. ++ (GDB User Interface Layout): Rewrite for clarity. ++ (Stack Buffer, Watch Expressions): Likewise. ++ (Other GDB User Interface Buffers): Cleanups. ++ (Lisp Libraries, External Lisp): Cleanup. ++ ++ * basic.texi (Position Info): "Graphical displays", rather than ++ window systems. ++ ++ * anti.texi: Minor cleanup. ++ ++2006-02-03 Eli Zaretskii ++ ++ * custom.texi (Init File, Find Init): Add cross-references to ++ where $HOME is described. ++ ++2006-02-01 Luc Teirlinck ++ ++ * frames.texi (Frame Parameters): Remove @item for S-Mouse-1; it ++ is not inside the @table. ++ ++ * emacs.texi (Top): Correct node name. ++ ++ * files.texi (File Names): Fix @xref. ++ (Reverting): Fix typo. ++ ++ * mule.texi (International): Correct node name. ++ ++ * kmacro.texi (Save Keyboard Macro): Add missing @kbd to @table. ++ ++2006-02-01 Richard M. Stallman ++ ++ * emacs.texi (Top): Update subnode menu. ++ ++ * mule.texi: Minor clarifications. ++ Reduce the specific references to X Windows. ++ Refer to "graphical" terminals, rather than window systems. ++ (Text Coding): Rename from Specify Coding. ++ (Communication Coding, File Name Coding, Terminal Coding): ++ New nodes split out from Text Coding. ++ ++ * kmacro.texi: Minor clarifications. ++ (Keyboard Macro Ring): Comment out some excessive commands. ++ (Basic Keyboard Macro): Split up the table, putting part in each node. ++ ++ * major.texi: Minor clarifications. ++ ++ * misc.texi (Single Shell, Interactive Shell): Fix xrefs. ++ ++ * windows.texi: Minor clarifications. ++ (Change Window): Don't describe mode-line mouse cmds here. ++ Add xref to Mode Line Mouse. ++ ++ * msdog.texi (Text and Binary, MS-DOS and MULE): Fix xrefs. ++ ++ * macos.texi (Mac International): Fix xref. ++ ++ * indent.texi: Minor clarifications. ++ ++ * frames.texi: Minor clarifications. ++ Reduce the specific references to X Windows. ++ Refer to "graphical" terminals, rather than window systems. ++ (Frame Parameters): Don't mention commands like ++ set-foreground-color. Just say to customize a face. ++ (Drag and Drop): Lisp-level stuff moved to Emacs Lisp manual. ++ ++ * files.texi: Minor clarifications. ++ (Numbered Backups): New node, split out from Backup Names. ++ ++ * display.texi (Font Lock): C mode no longer depends on (-in-col-0. ++ ++ * cmdargs.texi (General Variables): Fix xref. ++ ++ * buffers.texi: Minor clarifications. ++ ++2006-01-31 Richard M. Stallman ++ ++ * display.texi (Scrolling, Horizontal Scrolling, Follow Mode): ++ Nodes moved to top. ++ ++ * display.texi: Minor clarifications. ++ (Display): Rearrange menu. ++ (Standard Faces): Mention query-replace face. ++ (Faces): Simplify. ++ (Font Lock): Simplify face customization info. ++ (Highlight Changes): Node merged into Highlight Interactively. ++ (Highlight Interactively): Much rewriting and cleanup. ++ (Optional Mode Line): Narrowed line number not good for goto-line. ++ Simplify face customization advice. ++ (Text Display): Mention use of escape-glyph face. ++ Move ctl-arrow and tab-width here. ++ (Display Custom): Move no-redraw-on-reenter to end of node. ++ ++ * search.texi: Minor clarifications. ++ (Isearch Scroll): Simplify. ++ (Other Repeating Search): Document multi-occur-in-matching-buffers. ++ ++ * regs.texi (Registers): Mention bookmarks here. ++ ++ * mark.texi: Minor clarifications. ++ (Selective Undo): Node deleted. ++ ++ * m-x.texi: Minor clarifications. ++ ++ * killing.texi: Minor clarifications. ++ Refer to "graphical" terminals, rather than window systems. ++ ++ * help.texi: Clarifications. ++ (Help): Don't describe C-h F and C-h K here. ++ (Key Help): Describe C-h K here. ++ (Name Help): Mention Emacs Lisp Intro. ++ Describe C-h F here. ++ (Misc Help): Mention C-h F and C-h K only briefly. ++ ++ * fixit.texi (Undo): New node, mostly copied from basic.texi. ++ Selective undo text merged in. ++ (Spelling): Mention Aspell along with Ispell. ++ ++ * emacs.texi (Top): Update subnode menus. ++ ++ * basic.texi (Basic Undo): Rename from Undo. Most of text ++ moved to new Undo node. ++ ++2006-01-29 Chong Yidong ++ ++ * basic.texi (Continuation Lines, Inserting Text): ++ Mention longlines mode. ++ ++2006-01-29 Richard M. Stallman ++ ++ * screen.texi: Minor cleanups. ++ (Screen): Clean up the intro paragraphs. ++ (Mode Line): Lots of rewriting. Handle frame-name better. ++ eol-mnemonic-... vars moved out. ++ ++ * emacs.texi (Top): Change menu item for MS-DOS node. ++ Update subnode menu. ++ ++ * msdog.texi (MS-DOS): Rewrite intro to explain how this ++ chapter relates to Windows. Title changed. ++ ++ * mini.texi: Minor cleanups. ++ ++ * mark.texi (Selective Undo): New node, text moved from basic.texi. ++ (Mark): Put it in the menu. ++ ++ * entering.texi: Minor cleanups. ++ ++ * emacs.texi (Top): Add xref to Mac chapter; explain Windows better. ++ (Intro): Refer to "graphical" terminals, rather than X. ++ ++ * display.texi (Display Custom): Add xref to Variables. ++ (Optional Mode Line): eol-mnemonic-... vars moved here. ++ ++ * commands.texi: Minor cleanups. Refer to "graphical" terminals, ++ rather than X. ++ ++ * basic.texi: Minor cleanups. ++ (Undo): selective-undo moved. ++ ++2006-01-25 Luc Teirlinck ++ ++ * anti.texi (Antinews): Various corrections and additions. ++ ++2006-01-23 Juri Linkov ++ ++ * custom.texi (Easy Customization, Customization Groups) ++ (Browsing Custom): Mention links along with buttons. ++ ++2006-01-21 Eli Zaretskii ++ ++ * text.texi (TeX Print): Use @key for TAB. ++ ++ * kmacro.texi (Keyboard Macro Step-Edit): Use @key for TAB. ++ ++2006-01-15 Sven Joachim (tiny change) ++ ++ * files.texi (File Aliases): Don't claim that usually separate ++ buffers are created for two file names that name the same data. ++ Mention additional situations where different names mean the same ++ file on disk. ++ ++2006-01-19 Richard M. Stallman ++ ++ * killing.texi (Deletion): Upcase @key argument. ++ ++ * custom.texi (Custom Themes): Minor cleanup. ++ ++ * programs.texi (Hungry Delete): Upcase @key argument. ++ ++2006-01-16 Juri Linkov ++ ++ * display.texi (Standard Faces): Add `mode-line-buffer-id'. ++ Move `mode-line-highlight' before `mode-line-buffer-id'. ++ ++2006-01-14 Richard M. Stallman ++ ++ * basic.texi (Inserting Text): Minor cleanup. ++ ++2006-01-11 Luc Teirlinck ++ ++ * custom.texi (Changing a Variable, Face Customization): ++ Update for changes in Custom menus. ++ ++2006-01-05 YAMAMOTO Mitsuharu ++ ++ * macos.texi (Mac International): Undo last change. ++ ++2006-01-02 Chong Yidong ++ ++ * custom.texi (Custom Themes): Describe the new ++ customize-create-theme interface. ++ ++2005-12-30 Juri Linkov ++ ++ * basic.texi (Position Info): Update example. ++ ++2005-12-27 Jan Djärv ++ ++ * frames.texi (Dialog Boxes): Add x-gtk-show-hidden-files. ++ ++2005-12-24 Chong Yidong ++ ++ * custom.texi (Custom Themes): `load-theme' always loads. ++ ++2005-12-23 Juri Linkov ++ ++ * display.texi (Highlight Interactively): Use double space to ++ separate sentences. Replace C-p with M-p, and C-n with M-n. ++ ++2005-12-22 Richard M. Stallman ++ ++ * custom.texi (Easy Customization and subnodes): ++ Replace "active field" with "button". ++ Use "user option" only for variables. ++ Use "setting" for variable-or-face. ++ ++2005-12-22 Luc Teirlinck ++ ++ * buffers.texi (Select Buffer): Change order in table to make ++ "Similar" refer to the correct item. ++ (Indirect Buffers): Minor rewording. ++ ++2005-12-20 Juri Linkov ++ ++ * files.texi (VC Status): Put P and N near p and n. ++ ++2005-12-19 Richard M. Stallman ++ ++ * programs.texi (Electric C): Delete the info about newline control. ++ (Other C Commands): Minor cleanup. ++ (Left Margin Paren): Minor cleanup. ++ ++2005-12-19 Luc Teirlinck ++ ++ * custom.texi (Easy Customization): Add "Browsing Custom" to menu. ++ (Customization Groups): Delete text moved to "Browsing Custom". ++ (Browsing Custom): New node. ++ (Specific Customization): Clarify which commands only work for ++ loaded options. ++ ++2005-12-18 Bill Wohler ++ ++ * frames.texi (Tool Bars): Shorten text of previous change. ++ ++2005-12-18 Aaron S. Hawley ++ ++ * files.texi (VC Status): Document log-view mode. ++ ++2005-12-18 Bill Wohler ++ ++ * frames.texi (Tool Bars): Mention that you can turn off tool bars ++ permanently via the customize interface. ++ ++2005-12-16 Ralf Angeli ++ ++ * killing.texi (Killing by Lines): Document `kill-whole-line' ++ function. ++ ++2005-12-16 Lőrentey Károly ++ ++ * buffers.texi (Select Buffer): Change `prev-buffer' to ++ `previous-buffer'. Indicate that these functions use a frame ++ local buffer list. ++ ++2005-12-12 Richard M. Stallman ++ ++ * custom.texi (Easy Customization): Change menu comment. ++ (Prefix Keymaps): Fix spelling of Control-X-prefix. ++ ++ * help.texi (Apropos): Rewrite. Talk about "apropos patterns". ++ (Help): Among the Apropos commands, describe only C-h a here. ++ ++2005-12-11 Richard M. Stallman ++ ++ * programs.texi (Options for Comments): Comment-end starts with space. ++ ++ * glossary.texi (Glossary): Minor cleanup. ++ ++ * files.texi (Old Versions): Use @table. ++ ++2005-12-10 David Koppelman ++ ++ * display.texi (Highlight Interactively): Include ++ global-hi-lock-mode. Add miscellaneous details and elaborations. ++ ++2005-12-09 Richard M. Stallman ++ ++ * display.texi (Font Lock): Delete the Global FL menu item. ++ ++2005-12-09 Luc Teirlinck ++ ++ * custom.texi (Minibuffer Maps): Mention the maps for file name ++ completion. ++ ++2005-12-09 Kim F. Storm ++ ++ * killing.texi (CUA Bindings): Describe how to use C-x and C-c as ++ prefix keys even when mark is active. Describe that RET moves ++ cursor to next corner in rectangle; clarify insert around rectangle. ++ ++2005-12-08 Luc Teirlinck ++ ++ * custom.texi (Customization): Use xref to elisp manual for ++ non-TeX output. ++ (Minor Modes): Update. ++ (Customization Groups, Changing a Variable, Face Customization): ++ Update for new appearance of Custom buffers. ++ (Changing a Variable): `custom-buffer-done-function' has been ++ replaced by `custom-buffer-done-kill'. ++ (Specific Customization): In the `customize-group' buffer, a ++ subgroup's contents are not "hidden". They are not included at ++ all. They have no [Show] button. ++ (Mouse Buttons): Add pxref to description of mouse event lists in ++ Elisp manual. Add `menu-bar' and `header-line' dummy prefix keys. ++ (Find Init): Emacs now looks for ~/.emacs.d/init.el instead of ++ ~/.emacs.d/.emacs, if it can not find ~/.emacs(.el). ++ ++2005-12-08 Richard M. Stallman ++ ++ * mini.texi (Completion Commands, Completion): ++ In file name input, SPC does not do completion. ++ ++2005-12-08 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Explain screen size ++ setting. ++ (Other GDB User Interface Buffers): Describe features specific to ++ GDB 6.4. ++ ++2005-12-01 Nick Roberts ++ ++ * building.texi (GDB User Interface Layout): Describe how to ++ kill associated buffers. ++ (Breakpoints Buffer): Use D instead of d for gdb-delete-breakpoint. ++ (Watch Expressions): Be more precise. ++ (Other GDB User Interface Buffers): Describe how to change a ++ register value. ++ ++2005-11-24 YAMAMOTO Mitsuharu ++ ++ * macos.texi (Mac Input): Remove description of ++ mac-command-key-is-meta. Add descriptions of ++ mac-control-modifier, mac-command-modifier, and ++ mac-option-modifier. ++ (Mac International): Fix description of conversion of clipboard data. ++ (Mac Font Specs): Add example of font customization by face attributes. ++ ++2005-11-22 Nick Roberts ++ ++ * building.texi (Watch Expressions): Expand description. ++ (Other GDB User Interface Buffers): Describe local map for ++ gud-watch. ++ ++2005-11-21 Chong Yidong ++ ++ * display.texi (Font Lock): Font lock is enabled by default now. ++ ++2005-11-20 Juri Linkov ++ ++ * basic.texi (Position Info): Update examples of the output. ++ Remove the fact that examples are produced in the TeXinfo buffer, ++ because in the Info reader users will get a different output from ++ `C-x ='. ++ ++ * building.texi (Compilation Mode): Remove paragraph duplicated ++ from the node `Compilation'. Add `compilation-skip-threshold'. ++ ++ * display.texi (Font Lock): Suggest more user-friendly method of ++ finding all Font Lock faces (M-x customize-group RET font-lock-faces). ++ ++2005-11-18 Richard M. Stallman ++ ++ * files.texi (Registering): Mention @@ in mode line. ++ ++ * mini.texi (Minibuffer File): Clarify previous change. Add @findex. ++ ++2005-11-08 Aaron S. Hawley ++ ++ * files.texi (Renaming and VC): Some back-ends don't ++ handle renaming. ++ ++2005-11-17 Juri Linkov ++ ++ * emacs.texi (Top): ++ * display.texi (Highlight Interactively): Put this font-lock based ++ mode near Font Lock node. ++ ++2005-11-16 Chong Yidong ++ ++ * ack.texi (Acknowledgments): Acknowledge Andrew Zhilin for Emacs ++ icons. ++ ++2005-11-12 Kim F. Storm ++ ++ * help.texi (Help): Fix C-h a entry. Add C-h d entry. ++ (Help Summary): Add C-h d and C-h e. ++ (Apropos): Clarify that all apropos commands may search for either ++ list of words or a regexp. Add C-h d for apropos-documentation. ++ Describe apropos-documentation-sort-by-scores user option. ++ ++2005-11-09 Luc Teirlinck ++ ++ * killing.texi (CUA Bindings): Add @section. ++ ++2005-11-10 Kim F. Storm ++ ++ * emacs.texi (Top): Add CUA Bindings entry to menu. ++ ++ * killing.texi (CUA Bindings): New node. Moved here from ++ misc.texi and extended with info on rectangle commands and ++ rectangle highlighting, interface to registers, and the global ++ mark feature. ++ ++ * misc.texi (Emulation): Move CUA bindings item to killing.texi. ++ ++ * regs.texi: Prev link points to CUA Bindings node. ++ ++2005-11-07 Luc Teirlinck ++ ++ * help.texi (Help Echo): By default, help echos are only shown on ++ mouse-over, not on point-over. ++ ++2005-11-04 Jérôme Marant ++ ++ * misc.texi (Shell Mode): Describe how to activate password echoing. ++ ++2005-11-04 Romain Francoise ++ ++ * mark.texi (Mark Ring): Fix typo. ++ ++2005-11-03 Richard M. Stallman ++ ++ * mark.texi (Mark Ring): Mention set-mark-command-repeat-pop. ++ ++2005-11-01 Bill Wohler ++ ++ * help.texi (Help Mode): Fix typo. ++ ++2005-11-01 Nick Roberts ++ ++ * building.texi (Other GDB User Interface Buffers): Describe ++ the command gdb-use-inferior-io-buffer. ++ ++2005-10-31 Romain Francoise ++ ++ * files.texi (Compressed Files): Fix typo. ++ ++ * buffers.texi (Misc Buffer): Downcase `*shell*'. ++ ++ * windows.texi (Force Same Window): Likewise. ++ ++2005-10-30 Bill Wohler ++ ++ * help.texi (Help Mode): URLs viewed with browse-url. ++ ++2005-10-31 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Don't reference ++ gdb-mouse-set-clear-breakpoint. Explain gdb-mouse-until ++ must stay in same frame. ++ ++2005-10-29 Chong Yidong ++ ++ * custom.texi (Init File): Document ~/.emacs.d/init.el. ++ ++ * anti.texi (Antinews): Likewise. ++ ++2005-10-28 Bill Wohler ++ ++ * help.texi (Help): Help mode now creates hyperlinks for URLs. ++ ++2005-10-28 Richard M. Stallman ++ ++ * files.texi (Visiting): Explain how to enter ? in a file name. ++ ++ * trouble.texi (Memory Full): Mention !MEM FULL! in mode line. ++ ++2005-10-25 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Describe ++ gdb-mouse-until. ++ ++2005-10-23 Richard M. Stallman ++ ++ * custom.texi (Init File): Recommend when to use site-start.el. ++ ++2005-10-21 Juri Linkov ++ ++ * custom.texi (Examining): Mention accessing the old variable ++ value via M-n in set-variable. ++ ++2005-10-18 Romain Francoise ++ ++ * files.texi (Version Systems): Capitalize GNU. ++ ++2005-10-18 Nick Roberts ++ ++ * building.texi (Compilation Mode): Remove redundant paragraph. ++ (Watch Expressions): Remove paragraph to reflect code change. ++ ++2005-10-16 Richard M. Stallman ++ ++ * building.texi (Compilation Mode, Compilation): Clarified. ++ ++2005-10-15 Richard M. Stallman ++ ++ * misc.texi (Saving Emacs Sessions): Mention savehist library. ++ ++2005-10-13 Kenichi Handa ++ ++ * basic.texi (Position Info): Fix previous change. ++ ++2005-10-12 Jan Djärv ++ ++ * cmdargs.texi (Icons X): Fix typo. ++ ++2005-10-12 Kenichi Handa ++ ++ * basic.texi (Position Info): Describe the case that Emacs shows ++ "part of display ...". ++ ++2005-10-10 Jan Djärv ++ ++ * cmdargs.texi (Icons X): -nb => -nbi. ++ ++2005-10-10 Chong Yidong ++ ++ * frames.texi (Speedbar): A couple more clarifications. ++ ++2005-10-11 Nick Roberts ++ ++ * building.texi (GDB User Interface Layout): Improve diagram. ++ (Watch Expressions): Explain how to make speedbar global. ++ (Other GDB User Interface Buffers): Make references more precise. ++ ++2005-10-09 Richard M. Stallman ++ ++ * frames.texi (Speedbar): Clarify the text. ++ ++2005-10-09 Chong Yidong ++ ++ * frames.texi (Speedbar): Add information on keybindings, ++ dismissing the speedbar, and buffer display mode. Link to ++ speedbar manual. ++ ++2005-10-09 Jan Djärv ++ ++ * cmdargs.texi (Icons X): Removed options -i, -itype, --icon-type, ++ added -nb, --no-bitmap-icon. ++ ++2005-10-07 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Add variables and ++ functions to indices. Be more precise. ++ ++2005-10-03 Jan Djärv ++ ++ * frames.texi (Drag and Drop): Remove the x- from ++ x-dnd-open-file-other-window and xdnd-protocol-alist. ++ ++2005-09-30 Romain Francoise ++ ++ * mini.texi (Minibuffer): The default value now appears before the ++ colon in minibuffer prompts. ++ ++2005-09-25 Richard M. Stallman ++ ++ * search.texi (Regexp Search): Doc search-whitespace-regexp. ++ ++2005-09-20 Emanuele Giaquinta (tiny change) ++ ++ * text.texi (Paragraphs): Correction about Paragraph-Indent Text mode. ++ ++2005-09-21 YAMAMOTO Mitsuharu ++ ++ * emacs.texi (Top): Update submenus from macos.texi. ++ ++ * macos.texi: Change `Mac OS 8 or 9' to `Mac OS Classic'. ++ (Mac OS): Update feature support status. ++ (Mac Input): List supported input scripts. Remove description ++ about `mac-keyboard-text-encoding'. Mention mouse button ++ emulation and related variables. ++ (Mac International): Mention Central European and Cyrillic ++ support. Now `keyboard-coding-system' is dynamically changed. ++ Add description about coding system for selection. Add ++ description about language environment. ++ (Mac Environment Variables): Mention ++ `~/.MacOSX/environment.plist'. Give example of command line ++ arguments. Add Preferences support. ++ (Mac Directories): Explicitly state that this node is for Mac OS ++ Classic only. ++ (Mac Font Specs): Mention specification for scalable fonts. List ++ supported charsets. Add preferred way of creating fontsets. Add ++ description about `mac-allow-anti-aliasing'. ++ (Mac Functions): Add descriptions about `mac-set-file-creator', ++ `mac-get-file-creator', `mac-set-file-type', `mac-get-file-type', ++ and `mac-get-preference'. ++ ++2005-09-16 Romain Francoise ++ ++ Update all files to specify GFDL version 1.2. ++ ++ * doclicense.texi (GNU Free Documentation License): Update to ++ version 1.2. ++ ++2005-09-15 Richard M. Stallman ++ ++ * buffers.texi (List Buffers): Fix xref. ++ ++ * rmail.texi (Rmail Basics): Fix xref. ++ ++ * emacs.texi (Top): Update subnode menus. ++ ++ * files.texi (Saving Commands): New node, broken out of Saving. ++ (Customize Save): New node, broken out of Saving. ++ Clarify effect of write-region-inhibit-fsync. ++ (Misc File Ops): Say write-region-inhibit-fsync affects write-region. ++ ++2005-09-14 Romain Francoise ++ ++ * files.texi (Saving): Mention write-region-inhibit-fsync. ++ ++2005-09-05 Chong Yidong ++ ++ * custom.texi (Custom Themes): New node. ++ ++2005-09-03 Richard M. Stallman ++ ++ * search.texi (Search Case): Mention vars that control ++ case-fold-search for various operations. ++ ++2005-08-22 Juri Linkov ++ ++ * display.texi (Standard Faces): Merge the text from ++ `(elisp)Standard Faces' into this node. ++ ++2005-08-18 Luc Teirlinck ++ ++ * emacs.texi (Top): Delete menu item for deleted node ++ Keyboard Translations. ++ ++2005-08-18 Richard M. Stallman ++ ++ * trouble.texi (Unasked-for Search): ++ Delete xref to Keyboard Translations. ++ ++ * glossary.texi (Glossary): Delete xref. ++ ++ * custom.texi (Minor Modes): Say that the list here is not complete. ++ (Keyboard Translations): Node deleted. ++ (Disabling): Delete xref to it. ++ (Customization Groups): Fix Custom buffer example. ++ (Hooks): Mention remove-hooks. ++ ++2005-08-17 Luc Teirlinck ++ ++ * building.texi (GDB Graphical Interface): Improve filling of menu ++ item. ++ ++2005-08-18 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Use better node names. ++ ++2005-08-14 Richard M. Stallman ++ ++ * text.texi (Sentences): Fix xref. ++ ++2005-08-14 Juri Linkov ++ ++ * building.texi (Compilation, Grep Searching): Move grep command ++ headings from `Compilation' to `Grep Searching'. ++ ++ * dired.texi (Dired and Find): ++ * maintaining.texi (Tags Search): Replace grep xref to ++ `Compilation' node with `Grep Searching'. ++ ++ * files.texi (Comparing Files): Replace xref to `Compilation' with ++ `Compilation Mode'. ++ ++2005-08-13 Alan Mackenzie ++ ++ * search.texi (Non-ASCII Isearch): Correct a typo. ++ (Replacement Commands): Mention query-replace key binding. ++ ++2005-08-11 Richard M. Stallman ++ ++ * programs.texi (Options for Comments): Fix xref. ++ ++ * search.texi (Regexp Backslash, Regexp Example): New nodes split ++ out of Regexps. ++ ++2005-08-09 Juri Linkov ++ ++ * building.texi (Compilation): Use `itemx' instead of `item'. ++ (Grep Searching): Simplify phrase. ++ ++ * display.texi (Standard Faces): Describe vertical-border on ++ window systems. ++ ++ * windows.texi (Split Window): Simplify phrase and mention ++ vertical-border face. ++ ++2005-08-09 Richard M. Stallman ++ ++ * files.texi (Comparing Files): Clarify compare-windows. ++ ++ * calendar.texi (Scroll Calendar): Document < and > in calendar. ++ ++2005-08-06 Eli Zaretskii ++ ++ * mule.texi (Coding Systems): Rephrase the paragraph about ++ codepages: no need for "M-x codepage-setup" anymore, except on ++ MS-DOS. ++ ++ * msdog.texi (MS-DOS and MULE): Clarify that this section is for ++ the MS-DOS port only. ++ ++2005-07-30 Eli Zaretskii ++ ++ * makefile.w32-in (info): Don't run multi-install-info.bat. ++ ($(infodir)/dir): New target, produced by running ++ multi-install-info.bat. ++ ++2005-07-22 Eli Zaretskii ++ ++ * files.texi (Quoted File Names): Add index entry. ++ ++2005-07-19 Juri Linkov ++ ++ * files.texi (Comparing Files): Mention resync for `compare-windows'. ++ ++2005-07-18 Juri Linkov ++ ++ * custom.texi (Easy Customization): ++ * files.texi (Old Versions): ++ * frames.texi (Wheeled Mice): ++ * mule.texi (Specify Coding): ++ * text.texi (Cell Justification): ++ * trouble.texi (After a Crash): ++ * xresources.texi (GTK styles): ++ Delete duplicate duplicate words. ++ ++2005-07-17 Richard M. Stallman ++ ++ * frames.texi (Creating Frames): Fix foreground color example. ++ ++ * custom.texi (Init Examples): Clean up text about conditionals. ++ ++2005-07-16 Richard M. Stallman ++ ++ * mini.texi (Completion Commands): Fix command name for ?. ++ ++2005-07-16 Eli Zaretskii ++ ++ * display.texi (Standard Faces): Explain that customization of ++ `menu' face has no effect on w32 and with GTK. Add ++ cross-references. ++ ++ * cmdargs.texi (General Variables): Clarify the default location ++ of $HOME on w32 systems. ++ ++2005-07-15 Jason Rumney ++ ++ * cmdargs.texi (General Variables): Default HOME on MS Windows has ++ changed. ++ ++2005-07-08 Kenichi Handa ++ ++ * mule.texi (Recognize Coding): Recommend ++ revert-buffer-with-coding-system instead of revert-buffer. ++ ++2005-07-07 Richard M. Stallman ++ ++ * anti.texi (Antinews): Mention mode-line-inverse-video. ++ ++ * files.texi (Saving): Minor correction about C-x C-w. ++ ++ * display.texi (Display Custom): Don't mention mode-line-inverse-video. ++ ++2005-07-07 Luc Teirlinck ++ ++ * search.texi (Isearch Scroll): Add example of using the ++ `isearch-scroll' property. ++ (Slow Isearch): Reference anchor for `baud-rate' instead of entire ++ `Display Custom' node. ++ (Regexp Replace): Put text that requires Emacs Lisp knowledge last ++ and de-emphasize it. ++ (Other Repeating Search): `occur' currently can not correctly ++ handle multiline matches. Correct, clarify and update description ++ of `flush-lines' and `keep-lines'. ++ ++ * display.texi (Display Custom): Add anchor for `baud-rate'. ++ ++2005-07-07 Richard M. Stallman ++ ++ * gnu.texi: Update where to get GNU status; add refs for how to help. ++ Add footnotes 6 and 7. ++ ++2005-07-04 Lute Kamstra ++ ++ Update FSF's address in GPL notices. ++ ++ * doclicense.texi (GNU Free Documentation License): ++ * trouble.texi (Checklist): Update FSF's address. ++ ++2005-06-24 Richard M. Stallman ++ ++ * display.texi (Text Display): Change index entries. ++ ++2005-06-24 Eli Zaretskii ++ ++ * makefile.w32-in (MAKEINFO): Use --force. ++ (INFO_TARGETS, DVI_TARGETS): Make identical to the lists in ++ Makefile.in. ++ ++2005-06-23 Richard M. Stallman ++ ++ * anti.texi (Antinews): Renamed show-nonbreak-escape to ++ nobreak-char-display. ++ ++ * emacs.texi (Top): Update detailed node listing. ++ ++ * display.texi (Text Display): Renamed show-nonbreak-escape ++ to nobreak-char-display and no-break-space to nobreak-space. ++ (Standard Faces): Split up the list of standard faces ++ and put it in a separate node. Add nobreak-space and ++ escape-glyph. ++ ++2005-06-23 Lute Kamstra ++ ++ * mule.texi (Select Input Method): Fix typo. ++ ++2005-06-23 Kenichi Handa ++ ++ * mule.texi (International): List all supported scripts. Adjust ++ text for that leim is now included in the normal Emacs ++ distribution. ++ (Language Environments): List all language environments. ++ Intlfonts contains fonts for most supported scripts, not all.. ++ (Select Input Method): Refer to C-u C-x = to see how to type to ++ input a specific character. ++ (Recognize Coding): Fix typo, china-iso-8bit -> chinese-iso-8bit. ++ ++2005-06-23 Juanma Barranquero ++ ++ * building.texi (Grep Searching): Texinfo usage fix. ++ ++2005-06-22 Miles Bader ++ ++ * display.texi (Faces): Change `vertical-divider' to `vertical-border'. ++ ++2005-06-20 Miles Bader ++ ++ * display.texi (Faces): Add `vertical-divider'. ++ ++2005-06-17 Richard M. Stallman ++ ++ * text.texi (Adaptive Fill): Minor clarification. ++ ++2005-06-10 Lute Kamstra ++ ++ * emacs.texi (Top): Correct version number. ++ * anti.texi (Antinews): Correct version number. Use EMACSVER to ++ refer to the current version of Emacs. ++ ++2005-06-08 Luc Teirlinck ++ ++ * files.texi (Log Buffer): Document when there can be more than ++ one file to be committed. ++ ++2005-06-08 Juri Linkov ++ ++ * display.texi (Faces): Add `shadow' face. ++ ++2005-06-07 Masatake YAMATO ++ ++ * display.texi (Faces): Write about mode-line-highlight. ++ ++2005-06-06 Richard M. Stallman ++ ++ * misc.texi (Printing Package): Explain how to initialize ++ printing package. ++ ++ * cmdargs.texi (Action Arguments): Clarify directory default for -l. ++ ++2005-06-05 Chong Yidong ++ ++ * emacs.texi: Rename Hardcopy to Printing. ++ Make PostScript and PostScript Variables subnodes of it. ++ ++ * misc.texi (Printing): Rename node from Hardcopy. ++ Mention menu bar options. ++ Move PostScript and PostScript Variables to submenu. ++ (Printing package): New node. ++ ++ * mark.texi (Using Region): Change Hardcopy xref to Printing. ++ ++ * dired.texi (Operating on Files): Likewise. ++ ++ * calendar.texi (Displaying the Diary): Likewise. ++ ++ * msdog.texi (MS-DOS Printing, MS-DOS Processes): Likewise. ++ ++ * glossary.texi (Glossary): Likewise. ++ ++ * frames.texi (Mode Line Mouse): Mention mode-line-highlight ++ effect. ++ ++2005-06-04 Richard M. Stallman ++ ++ * trouble.texi (After a Crash): Polish previous change. ++ ++2005-05-30 Noah Friedman ++ ++ * trouble.texi (After a Crash): Mention emacs-buffer.gdb as a ++ recovery mechanism. ++ ++2005-05-28 Nick Roberts ++ ++ * building.texi (Other Buffers): SPC toggles display of ++ floating point registers. ++ ++2005-05-27 Nick Roberts ++ ++ * files.texi (Log Buffer): Merge in description of Log Edit ++ mode from pcl-cvs.texi. ++ ++2005-05-26 Richard M. Stallman ++ ++ * building.texi (Lisp Eval): C-M-x with arg runs Edebug. ++ ++2005-05-24 Luc Teirlinck ++ ++ * fixit.texi (Spelling): Delete confusing sentence; flyspell is ++ not enabled by default. ++ When not on a word, `ispell-word' by default checks the word ++ before point. ++ ++2005-05-24 Nick Roberts ++ ++ * building.texi (Debugger Operation): Simplify last sentence. ++ ++2005-05-23 Lute Kamstra ++ ++ * emacs.texi: Update FSF's address throughout. ++ (Preface): Use @cite. ++ (Distrib): Add cross reference to the node "Copying". Mention the ++ FDL. Don't refer to etc/{FTP,ORDERS}. Mention the sale of ++ printed manuals. ++ (Intro): Use @xref for the Emacs Lisp Intro. ++ ++2005-05-18 Luc Teirlinck ++ ++ * buffers.texi (Select Buffer): Document `C-u M-g M-g'. ++ ++ * basic.texi (Moving Point): Mention default for `goto-line'. ++ ++ * programs.texi (Lisp Doc): Eldoc mode shows only the first line ++ of a variable's docstring. ++ ++2005-05-18 Lute Kamstra ++ ++ * maintaining.texi (Overview of Emerge): Add cross reference. ++ Remove duplication. ++ ++ * emacs.texi (Top): Update to the current structure of the manual. ++ * misc.texi (Emacs Server): Add menu description. ++ * files.texi (Saving): Fix menu. ++ * custom.texi (Customization): Fix menu. ++ * mule.texi (International): Fix menu. ++ * kmacro.texi (Keyboard Macros): Fix menu. ++ ++2005-05-16 Luc Teirlinck ++ ++ * display.texi: Various minor changes. ++ (Faces): Delete text that is repeated in the next section. ++ ++2005-05-16 Nick Roberts ++ ++ * building.texi (Debugger Operation): Mention GUD tooltips are ++ disabled with GDB in text command mode. ++ ++2005-05-16 Nick Roberts ++ ++ * building.texi: Replace toolbar with "tool bar" for consistency. ++ (Compilation Mode): Describe compilation-context-lines ++ and use of arrow in compilation buffer. ++ (Debugger Operation): Replace help text with variable's value. ++ ++ * frames.texi (Tooltips): Replace toolbar with "tool bar" for ++ consistency. ++ ++2005-05-15 Luc Teirlinck ++ ++ * major.texi (Choosing Modes): normal-mode processes the -*- line. ++ Add xref. ++ ++2005-05-14 Luc Teirlinck ++ ++ * basic.texi (Moving Point): Mention `M-g g' binding for `goto-line'. ++ (Position Info): Delete discussion of `goto-line'. It is already ++ described in `Moving point'. ++ ++ * mini.texi (Completion Commands): Correct reference. ++ (Completion Options): Fix typo. ++ ++ * killing.texi (Deletion): Complete description of `C-x C-o'. ++ ++2005-05-10 Richard M. Stallman ++ ++ * building.texi (Compilation): Clarify recompile's directory choice. ++ ++ * frames.texi (Tooltips): Cleanups. ++ ++ * basic.texi (Arguments): Fix punctuation. ++ ++2005-05-09 Luc Teirlinck ++ ++ * screen.texi (Menu Bar): The up and down (not left and right) ++ arrow keys move through a keyboard menu. ++ ++2005-05-08 Luc Teirlinck ++ ++ * basic.texi: Various typo and grammar fixes. ++ (Moving Point): C-a now runs move-beginning-of-line. ++ ++2005-05-08 Nick Roberts ++ ++ * building.texi (Debugger Operation): Describe gud-tooltip-echo-area. ++ ++ * frames.texi (Tooltips): Describe help tooltips and GUD tooltips ++ as different animals. ++ ++2005-05-07 Luc Teirlinck ++ ++ * frames.texi (Mouse References): Clarify `mouse-1-click-follows-link'. ++ Correct index entry. ++ ++2005-05-07 Nick Roberts ++ ++ * building.texi (Debugger Operation): Update to reflect changes ++ in GUD tooltips. ++ ++2005-04-30 Richard M. Stallman ++ ++ * files.texi (Compressed Files): Auto Compression normally enabled. ++ ++ * building.texi (Debugger Operation): Clarify previous change. ++ ++2005-04-28 Nick Roberts ++ ++ * building.texi (Debugger Operation): Add description for ++ GUD tooltips when program is not running. ++ ++2005-04-26 Luc Teirlinck ++ ++ * misc.texi (Shell): Add `Shell Prompts' to menu. ++ (Shell Mode): Add xref to `Shell Prompts'. Clarify `C-c C-u' ++ description. Delete remarks moved to new node. ++ (Shell Prompts): New node. ++ (History References): Replace remarks moved to `Shell Prompts' ++ with xref to that node. ++ (Remote Host): Clarify how to specify the terminal type when ++ logging in to a different machine. ++ ++2005-04-26 Richard M. Stallman ++ ++ * emacs.texi (Top): Update submenus from files.texi. ++ ++ * files.texi (Filesets): Clarify previous change. ++ ++ * dired.texi (Misc Dired Features): Clarify previous change. ++ ++2005-04-25 Chong Yidong ++ ++ * ack.texi (Acknowledgments): Delete info about iso-acc.el. ++ ++ * dired.texi (Misc Dired Features): Document ++ dired-compare-directories. ++ ++ * files.texi (Filesets): New node. ++ (File Conveniences): Document Image mode. ++ ++ * text.texi (TeX Print): Document tex-compile. ++ ++2005-04-25 Luc Teirlinck ++ ++ * frames.texi (Tooltips): Tooltip mode is enabled by default. ++ Delete redundant reference to tooltip Custom group. It is ++ referred too again in the next paragraph. ++ ++2005-04-24 Richard M. Stallman ++ ++ * ack.texi: Delete info about lazy-lock.el and fast-lock.el. ++ ++2005-04-19 Kim F. Storm ++ ++ * building.texi (Compilation Mode): Add M-g M-n and M-g M-p bindings. ++ ++2005-04-18 Lars Hansen ++ ++ * misc.texi (Saving Emacs Sessions): Add that "--no-desktop" now ++ turns off desktop-save-mode. ++ ++2005-04-17 Luc Teirlinck ++ ++ * frames.texi (XTerm Mouse): Xterm Mouse mode is no longer enabled ++ by default in terminals compatible with xterm. Mention that ++ xterm-mouse-mode is a minor mode and put in pxref to Minor Modes ++ node. ++ ++2005-04-12 Luc Teirlinck ++ ++ * frames.texi (XTerm Mouse): Xterm Mouse mode is now enabled by default. ++ ++2005-04-12 Jan Djärv ++ ++ * xresources.texi (Table of Resources): Add cursorBlink. ++ ++2005-04-11 Luc Teirlinck ++ ++ * rmail.texi (Rmail Summary Edit): Explain numeric arguments to ++ `d', `C-d' and `u'. ++ ++2005-04-11 Richard M. Stallman ++ ++ * cmdargs.texi (Initial Options): -Q is now --quick, and does less. ++ (Misc X): Add -D, --basic-display. ++ ++ * maintaining.texi (Change Log): Correct the description of ++ the example. ++ ++ * major.texi (Choosing Modes): Document magic-mode-alist. ++ ++2005-04-10 Luc Teirlinck ++ ++ * rmail.texi (Rmail Basics): Clarify description of `q' and `b'. ++ (Rmail Deletion): `C-d' in RMAIL buffer does not accept a numeric arg. ++ (Rmail Inbox): Give full name of `rmail-primary-inbox-list'. ++ (Rmail Output): Clarify which statements apply to `o', `C-o' and ++ `w', respectively. ++ (Rmail Labels): Mention `l'. ++ (Rmail Attributes): Correct pxref. Mention `stored' attribute. ++ (Rmail Summary Edit): Describe `j' and RET. ++ ++2005-04-10 Jan Djärv ++ ++ * xresources.texi (Lucid Resources): Add fontSet resource. ++ ++2005-04-09 Luc Teirlinck ++ ++ * display.texi (Useless Whitespace): `indicate-unused-lines' is ++ now called `indicate-empty-lines'. ++ ++2005-04-06 Kim F. Storm ++ ++ * cmdargs.texi (Initial Options): Add --bare-bones alias for -Q. ++ ++2005-04-04 Luc Teirlinck ++ ++ * dired.texi (Dired Visiting): `dired-view-command-alist' has been ++ deleted. ++ (Marks vs Flags): Add some convenient key bindings. ++ (Hiding Subdirectories): Delete redundant and inaccurate sentence. ++ (Misc Dired Features): Correct and expand description of `w' command. ++ ++ * frames.texi (XTerm Mouse): Delete apparently false info. ++ The GNU/Linux console currently does not appear to support ++ `xterm-mouse-mode'. ++ ++2005-04-03 Glenn Morris ++ ++ * calendar.texi (Diary): Mention shell utility `calendar'. ++ ++2005-04-01 Richard M. Stallman ++ ++ * cmdargs.texi (Misc X): Explain horizontal scroll bars don't exist. ++ ++2005-04-01 Lute Kamstra ++ ++ * maintaining.texi (Change Log): add-change-log-entry uses ++ add-log-mailing-address. ++ ++2005-03-31 Luc Teirlinck ++ ++ * files.texi (Reverting): Move `auto-revert-check-vc-info' to ++ `VC Mode Line' and put in an xref to that node. ++ (VC Mode Line): Move `auto-revert-check-vc-info' here and clarify ++ its description. ++ ++2005-03-31 Paul Eggert ++ ++ * calendar.texi (Calendar Systems): Say that the Persian calendar ++ implemented here is the arithmetical one championed by Birashk. ++ ++2005-03-30 Glenn Morris ++ ++ * programs.texi (Fortran Motion): Fix previous change. ++ ++2005-03-29 Richard M. Stallman ++ ++ * mule.texi (Single-Byte Character Support): Reinstall the C-x 8 info. ++ ++2005-03-29 Chong Yidong ++ ++ * text.texi (Refill): Refer to Long Lines Mode. ++ (Longlines): New node. ++ (Auto Fill): Don't index "word wrap" here. ++ (Filling): Add Longlines to menu. ++ ++2005-03-29 Richard M. Stallman ++ ++ * xresources.texi: Minor fixes. ++ ++ * misc.texi (Emacs Server): Fix Texinfo usage. ++ ++ * emacs.texi (Top): Don't use a real section heading for ++ "Detailed Node Listing". Fake it instead. ++ ++ * basic.texi (Position Info): Minor cleanup. ++ ++ * mule.texi (Input Methods): Minor cleanup. ++ ++2005-03-29 Glenn Morris ++ ++ * programs.texi (ForIndent Vars): `fortran-if-indent' does other ++ constructs as well. ++ (Fortran Motion): Add fortran-end-of-block, fortran-beginning-of-block. ++ ++2005-03-29 Kenichi Handa ++ ++ * mule.texi (Input Methods): Refer to the command C-u C-x =. ++ ++ * basic.texi (Position Info): Update the description about the ++ command C-u C-x =. ++ ++2005-03-28 Richard M. Stallman ++ ++ * emacs.texi (Top): Use @section for the detailed node listing. ++ ++ * calendar.texi: Minor fixes to previous change. ++ ++ * programs.texi (Fortran): Small fixes to previous changes. ++ ++ * emacs.texi (Top): Update list of subnodes of Dired. ++ Likewise for building.texi. ++ ++ * files.texi (File Conveniences): Delete Auto Image File mode. ++ ++2005-03-28 Chong Yidong ++ ++ * building.texi (Flymake): New node. ++ ++ * custom.texi (Function Keys): Document kp- event types and ++ keypad-setup package. ++ ++ * dired.texi (Wdired): New node. ++ ++ * files.texi (File Conveniences): Reorder entries. ++ Explain how to turn on Auto-image-file mode. ++ Document Thumbs mode. ++ ++ * mule.texi (Specify Coding): Document recode-region and ++ recode-file-name. ++ ++ * programs.texi (Program Modes): Add Conf mode and DNS mode. ++ ++2005-03-27 Luc Teirlinck ++ ++ * commands.texi (Keys): M-o is now a prefix key. ++ ++2005-03-27 Glenn Morris ++ ++ * programs.texi: Reformat and update copyright years. ++ (Fortran): Update section. ++ ++2005-03-26 Luc Teirlinck ++ ++ * files.texi: Several small changes in addition to: ++ (Visiting): Change xref for Dialog Boxes to ref. ++ (Version Headers): Replace references to obsolete var ++ `vc-header-alist' with `vc-BACKEND-header'. ++ (Customizing VC): Update value of `vc-handled-backends'. ++ ++2005-03-26 Glenn Morris ++ ++ * emacs-xtra.texi (Advanced Calendar/Diary Usage): New section; ++ move here from Emacs Lisp Reference Manual. ++ * calendar.texi (Calendar/Diary, Diary Commands) ++ (Special Diary Entries, Importing Diary): Change some xrefs to ++ point to emacs-xtra rather than elisp. ++ ++ * emacs-xtra.texi (Calendar Customizing): ++ Move view-diary-entries-initially, view-calendar-holidays-initially, ++ mark-diary-entries-in-calendar, mark-holidays-in-calendar to main ++ Emacs Manual. ++ (Appt Customizing): Merge entire section into main Emacs Manual. ++ * calendar.texi (Holidays): Move view-calendar-holidays-initially, ++ mark-holidays-in-calendar here from emacs-xtra. ++ (Displaying the Diary): Move view-diary-entries-initially, ++ mark-diary-entries-in-calendar here from emacs-xtra. ++ (Appointments): Move appt-display-mode-line, ++ appt-display-duration, appt-disp-window-function, ++ appt-delete-window-function here from emacs-xtra. ++ ++ * calendar.texi: Update and reformat copyright. ++ Change all @xrefs to the non-printing emacs-xtra to @inforefs. ++ (Calendar/Diary): Menu now only on Mouse-3, not C-Mouse-3. ++ (Diary): Refer to `diary-file' rather than ~/diary. ++ (Diary Commands): Rename node to "Displaying the Diary". ++ * emacs.texi (Top): Rename "Diary Commands" section. ++ * misc.texi (Hardcopy): Rename "Diary Commands" xref. ++ ++2005-03-26 Eli Zaretskii ++ ++ * misc.texi (Emacs Server): Fix the command for setting ++ server-name. Add an xref to Invoking emacsclient. ++ ++ * help.texi (Help Summary): Clarify when "C-h ." will do something ++ nontrivial. ++ (Apropos): Add cindex entry for apropos-sort-by-scores. ++ ++ * display.texi (Text Display): Add index entries for how no-break ++ characters are displayed. ++ ++2005-03-26 Eli Zaretskii ++ ++ * files.texi (Visiting): Fix cross-references introduced with the ++ last change. ++ ++ * xresources.texi (GTK resources): Fix last change. ++ ++2005-03-25 Chong Yidong ++ ++ * xresources.texi (X Resources): GTK options documented too. ++ (Resources): Clarify meaning of program name. ++ (Table of Resources): Add visualClass. ++ (GTK resources): Rewrite. ++ (GTK widget names, GTK Names in Emacs, GTK styles): Cleanups. ++ ++ * display.texi (Text Display): Mention non-breaking spaces. ++ ++ * files.texi (Reverting): Document auto-revert-check-vc-info. ++ ++ * frames.texi (Mouse Commands): Document ++ x-mouse-click-focus-ignore-position and mouse-drag-copy-region. ++ ++ * help.texi (Help Summary): Add `C-h .'. ++ (Apropos): Apropos accepts a list of search terms. ++ Document apropos-sort-by-scores. ++ (Help Echo): Document display-local-help. ++ ++ * misc.texi (Emacs Server): Document server-name. ++ (Invoking emacsclient): Document -s option for server names. ++ ++ * text.texi (Outline Visibility): Introduce "current heading ++ line" (commands can be called with point on a body line). ++ Re-order table to follow the sequence of discussion. ++ hide-body won't hide lines before first header line. ++ (TeX Mode): Add DocTeX mode. ++ ++2005-03-24 Richard M. Stallman ++ ++ * mule.texi (Single-Byte Character Support): Delete mention ++ of iso-acc.el and iso-transl.el. ++ ++2005-03-23 Lute Kamstra ++ ++ * search.texi (Non-ASCII Isearch): Rename from Non-Ascii Isearch. ++ ++2005-03-23 Richard M. Stallman ++ ++ * search.texi: Delete explicit node pointers. ++ (Incremental Search): New menu. ++ (Basic Isearch, Repeat Isearch, Error in Isearch) ++ (Non-Ascii Isearch, Isearch Yank, Highlight Isearch, Isearch Scroll) ++ (Slow Isearch): New subnodes. ++ (Configuring Scrolling): Node deleted. ++ (Search Case): Doc default-case-fold-search. ++ (Regexp Replace): Move replace-regexp doc here. ++ ++ * rmail.texi (Movemail): Put commas inside closequotes. ++ ++ * picture.texi (Insert in Picture): Document C-c arrow combos. ++ (Basic Picture): Clarify erasure. ++ ++ * display.texi (Font Lock): Put commas inside closequotes. ++ ++ * cmdargs.texi (General Variables): Put commas inside closequotes. ++ ++2005-03-23 Nick Roberts ++ ++ * building.texi (Stack Buffer): Mention reverse contrast for ++ *selected* frame (might not be current frame). ++ ++2005-03-21 Richard M. Stallman ++ ++ * building.texi (Starting GUD): Add bashdb. ++ ++2005-03-20 Chong Yidong ++ ++ * basic.texi (Moving Point): Add M-g M-g binding. ++ (Undo): Document undo-only. ++ (Position Info): Document M-g M-g and C-u M-g M-g. ++ ++ * building.texi (Building): Put Grep Searching after Compilation ++ Shell. ++ (Compilation Mode): Document M-n, M-p, M-}, M-{, and C-c C-f bindings. ++ Document next-error-highlight. ++ (Grep Searching): Document grep-highlight-matches. ++ (Lisp Eval): Typing C-x C-e twice prints integers specially. ++ ++ * calendar.texi (Importing Diary): Rename node from iCalendar. ++ Document diary-from-outlook. ++ ++ * dired.texi (Misc Dired Features): Rename node from Misc Dired ++ Commands. ++ Mention effect of X drag and drop on Dired buffers. ++ ++ * files.texi (Visiting): Document large-file-warning-threshold. ++ Move paragraph on file-selection dialog. ++ Mention visiting files using X drag and drop. ++ (Reverting): Mention using Auto-Revert mode to tail files. ++ Document auto-revert-tail-mode. ++ (Version Systems): Minor correction. ++ (Comparing Files): Diff-mode is no longer based on Compilation ++ mode. ++ Document compare-ignore-whitespace. ++ (Misc File Ops): Explain passing a directory to rename-file. ++ Likewise for copy-file and make-symbolic-link. ++ ++ * frames.texi (Wheeled Mice): Mouse wheel support on by default. ++ Document mouse-wheel-progressive speed. ++ ++ * help.texi (Misc Help): Document numeric argument for C-h i. ++ Correctly explain the effect of just C-u as argument. ++ ++ * killing.texi (Deletion): Document numeric argument for ++ just-one-space. ++ ++ * mini.texi (Completion): Completion acts on text before point. ++ ++ * misc.texi (Saving Emacs Sessions): Document desktop-restore-eager. ++ (Emulation): CUA mode replaces pc-bindings-mode, ++ pc-selection-mode, and s-region. ++ ++ * mule.texi (Input Methods): Leim is now built-in. ++ (Select Input Method): Document quail-show-key. ++ (Specify Coding): Document revert-buffer-with-coding-system. ++ ++ * programs.texi (Fortran Motion): Document f90-next-statement, ++ f90-previous-statement, f90-next-block, f90-previous-block, ++ f90-end-of-block, and f90-beginning-of-block. ++ ++ * text.texi (Format Faces): Replace old M-g key prefix with M-o. ++ ++ * emacs.texi (Acknowledgments): Updated. ++ ++ * anti.texi: Total rewrite. ++ ++2005-03-19 Chong Yidong ++ ++ * ack.texi (Acknowledgments): Update. ++ ++2005-03-19 Eli Zaretskii ++ ++ * anti.texi (Antinews): Refer to Emacs 21.4, not 21.3. Update ++ copyright years. ++ ++2005-03-14 Nick Roberts ++ ++ * building.texi (Commands of GUD): Move paragraph on setting ++ breakpoints with mouse to the GDB Graphical Interface node. ++ ++2005-03-07 Richard M. Stallman ++ ++ * misc.texi (Single Shell, Shell Options): Fix previous change. ++ ++ * building.texi (Debugger Operation): Update GUD tooltip enable info. ++ ++2005-03-06 Richard M. Stallman ++ ++ * building.texi (Starting GUD): Don't explain text vs graphical ++ GDB here. Just mention it and xref. ++ Delete "just one debugger process". ++ (Debugger Operation): Move GUD tooltip info here. ++ (GUD Tooltips): Node deleted. ++ (GDB Graphical Interface): Explain the two GDB modes here. ++ ++ * sending.texi (Sending Mail): Minor cleanup. ++ (Mail Aliases): Explain quoting conventions. ++ Update key rebinding example. ++ (Header Editing): C-M-i is like M-TAB. ++ (Mail Mode Misc): mail-attach-file does not do MIME. ++ ++ * rmail.texi (Rmail Inbox): Move text from Remote Mailboxes ++ that really belongs here. ++ (Remote Mailboxes): Text moved to Rmail Inbox. ++ (Rmail Display): Mention Mouse-1. ++ (Movemail): Clarify two movemail versions. ++ Clarify rmail-movemail-program. ++ ++ * misc.texi (Single Shell): Replace uudecode example with gpg example. ++ Document async shell commands. ++ (Shell History): Clarify. ++ (Shell Ring): Mention C-UP an C-DOWN. ++ (Shell Options): Add comint-prompt-read-only. ++ (Invoking emacsclient): Set EDITOR to run Emacs. ++ (Sorting): No need to explain what region is. ++ (Saving Emacs Sessions): Fix typo. ++ (Recursive Edit): Fix punctuation. ++ (Emulation): Don't mention "PC bindings" which are standard. ++ (Hyperlinking): Explain Mouse-1 convention here. ++ (Find Func): Node deleted. ++ ++ * help.texi (Name Help): Xref to Hyperlinking. ++ ++ * glossary.texi (Glossary): ++ Rename "Balance Parentheses" to "Balancing...". ++ Add "Byte Compilation". Correct "Copyleft". ++ New xref in "Customization". ++ Clarify "Current Line", "Echoing", "Fringe", "Frame", "Speedbar". ++ Add "Graphical Terminal" "Keybinding", "Margin", "Window System". ++ Rename "Registers" to "Register". ++ Replace "Selecting" with "Selected Frame", ++ "Selected Window", and "Selecting a Buffer". ++ ++ * files.texi (Types of Log File): Explain how projects' ++ methods can vary. ++ ++ * display.texi (Faces): Delete "Emacs 21". ++ ++ * custom.texi (Changing a Variable): C-M-i like M-TAB. ++ * fixit.texi (Spelling): C-M-i like M-TAB. ++ * mini.texi (Completion Options): C-M-i like M-TAB. ++ * programs.texi (Symbol Completion): C-M-i like M-TAB. ++ * text.texi (Text Mode): C-M-i like M-TAB. ++ ++ * commands.texi (Keys): Mention F1 and F2 in list of prefixes. ++ ++ * calendar.texi (Specified Dates): Mention `g w'. ++ (Appointments): appt-activate toggles with no arg. ++ ++2005-03-05 Juri Linkov ++ ++ * cmdargs.texi (Emacs Invocation): Add cindex ++ "invocation (command line arguments)" ++ (Misc X): Add -nbc, --no-blinking-cursor. ++ ++2005-03-04 Ulf Jasper ++ ++ * calendar.texi (iCalendar): No need to require it now. ++ ++2005-03-03 Nick Roberts ++ ++ * trouble.texi (Contributing): Mention Savannah. Direct users to ++ emacs-devel. ++ ++2005-03-01 Glenn Morris ++ ++ * calendar.texi (Adding to Diary): Mention redrawing of calendar ++ window. ++ ++2005-02-27 Richard M. Stallman ++ ++ * building.texi (Compilation): Update mode line status info. ++ ++2005-02-27 Matt Hodges ++ ++ * calendar.texi (General Calendar): Document binding of ++ scroll-other-window-down. ++ (Mayan Calendar): Fix earliest date. ++ (Time Intervals): Document timeclock-change. ++ Fix timeclock-ask-before-exiting documentation. ++ ++2005-02-26 Kim F. Storm ++ ++ * frames.texi (Mouse References): ++ Add mouse-1-click-in-non-selected-windows. ++ ++2005-02-25 Richard M. Stallman ++ ++ * screen.texi (Screen): Explain better about cursors and mode lines; ++ don't presuppose text terminals. ++ (Point): Don't assume just one cursor. ++ Clarify explanation of cursors. ++ (Echo Area, Menu Bar): Cleanups. ++ ++ * mini.texi (Minibuffer): Prompts are highlighted. ++ (Minibuffer Edit): Newline = C-j only on text terminals. ++ Clarify resize-mini-windows values. ++ Mention M-PAGEUP and M-PAGEDOWN. ++ (Completion Commands): Mouse-1 like Mouse-2. ++ (Minibuffer History): Explain history commands better. ++ (Repetition): Add xref to Incremental Search. ++ ++ * mark.texi (Setting Mark): Clarify info about displaying mark. ++ Clarify explanation of C-@ and C-SPC. ++ (Transient Mark): Mention Delete Selection mode. ++ (Marking Objects): Clean up text about extending the region. ++ ++ * m-x.texi (M-x): One C-g doesn't always go to top level. ++ No delay before suggest-key-bindings output. ++ ++ * fixit.texi (Fixit): Mention C-/ for undo. ++ (Spelling): Mention ESC TAB like M-TAB. ++ Replacement words with r and R are rechecked. ++ Say where C-g leaves point. Mention ? as input. ++ ++2005-02-23 Lute Kamstra ++ ++ * cmdargs.texi (Initial Options): Add cross reference. ++ ++2005-02-16 Luc Teirlinck ++ ++ * emacs.texi (Top): Update menu for splitting of node in ++ msdog.texi. ++ * frames.texi (Frames): Update xref for splitting of node in ++ msdog.texi. ++ * trouble.texi (Quitting): Ditto. ++ ++2005-02-16 Richard M. Stallman ++ ++ * windows.texi (Split Window): Simplify line truncation info ++ and xref to Display Custom. ++ ++ * trouble.texi (Quitting): Emergency escape only for text terminal. ++ (Screen Garbled): C-l for ungarbling is only for text terminal. ++ ++ * text.texi (Text Mode): ESC TAB alternative for M-TAB. ++ ++ * sending.texi (Header Editing): ESC TAB alternative for M-TAB. ++ ++ * programs.texi (Program Modes): Mention Python mode. ++ (Moving by Defuns): Repeating C-M-h extends region. ++ (Basic Indent): Clarify. ++ (Custom C Indent): Clarify. ++ (Expressions): Repeating C-M-@ extends region. ++ (Info Lookup): Clarify for C-h S. ++ (Symbol Completion): ESC TAB alternative for M-TAB. ++ (Electric C): Clarify. ++ ++ * emacs.texi (Top): Update display.texi and frames.texi submenu data. ++ ++ * msdog.texi (MS-DOS Keyboard, MS-DOS Mouse): Split from ++ MS-DOS Input node. ++ (MS-DOS Keyboard): Start with explaining DEL and BREAK. ++ (MS-DOS and MULE): Clarify. ++ (MS-DOS Processes, Windows Processes): Fix typos. ++ ++ * major.texi (Choosing Modes): Clarify. ++ ++ * kmacro.texi (Basic Keyboard Macro): Doc F3, F4. ++ (Keyboard Macro Step-Edit): Clarify. ++ ++ * indent.texi (Indentation): Clarifications. ++ ++ * help.texi (Help): Correct error about C-h in query-replace. ++ Clarify apropos vs C-h a. Fix how to search in FAQ. ++ (Key Help): Describe C-h w here. ++ (Name Help): Minor cleanup. C-h w moved to Key Help. ++ Clarify the "object" joke. ++ (Apropos): Clarify. Mouse-1 like Mouse-2. ++ (Help Mode): Mouse-1 like Mouse-2. ++ ++ * fixit.texi (Spelling): Mention ESC TAB as alt. for M-TAB. ++ ++ * display.texi (Display): Reorder menu. ++ (Faces): Cleanup. ++ (Font Lock): Cleanup. Mention Options menu. ++ Delete obsolete text. ++ (Scrolling): For C-l, don't presume text terminal. ++ (Horizontal Scrolling): Simplify intro. ++ (Follow Mode): Clarify. ++ (Cursor Display): Moved before Display Custom. ++ (Display Custom): Explain no-redraw-on-reenter is for text terminals. ++ Doc default-tab-width. Doc line truncation more thoroughly. ++ ++ * dired.texi (Dired Enter): C-x C-f can run Dired. ++ (Dired Visiting): Comment out `a' command. ++ Mouse-1 is like Mouse-2. ++ (Shell Commands in Dired): ? can be used more than once. ++ ++ * basic.texi (Continuation Lines): Simplify description of truncation, ++ and refer to Display Custom for the rest of it. ++ ++2005-02-06 Lute Kamstra ++ ++ * basic.texi (Undo): Fix typo. ++ ++ * cmdargs.texi (Emacs Invocation): Fix typo. ++ ++ * custom.texi (Init Examples): Fix typo. ++ ++ * abbrevs.texi (Expanding Abbrevs): Fix typo. ++ ++2005-02-06 Richard M. Stallman ++ ++ * regs.texi (Registers): Registers can hold numbers, too. ++ ++ * killing.texi (Other Kill Commands): Cleanup. ++ Delete redundant explanation of kill in read-only buffer. ++ (Yanking): Mention term "copying". ++ (Accumulating Text): Fix typo. ++ ++ * entering.texi (Entering Emacs): Update rationale at start. ++ (Exiting): Treat iconifying on a par with suspension. ++ ++ * custom.texi (Minor Modes): Fix typo. ++ (Easy Customization): Fix menu style. ++ (Variables): Add xref. ++ (Examining): Setting for future sessions works through .emacs. ++ (Keymaps): "Text terminals", not "Many". ++ (Init Rebinding): Explain \C-. Show example of \M-. ++ Fix minor wording errors. ++ (Function Keys): Explain vector syntax just once. ++ (Named ASCII Chars): Clarify history of TAB/C-i connection. ++ (Init File): Mention .emacs.d directory. ++ (Init Examples): Add xref. ++ (Find Init): Mention .emacs.d directory. ++ ++ * cmdargs.texi (Emacs Invocation): +LINENUM is also an option. ++ (Action Arguments): Explain which kinds of -l args are found how. ++ (Initial Options): --batch does not inhibit site-start. ++ Add xrefs. ++ (Command Example): Use --batch, not -batch. ++ ++ * basic.texi (Inserting Text): Cleanup wording. ++ (Moving Point): Doc PRIOR, PAGEUP, NEXT, PAGEDOWN more systematically. ++ C-n is not error at end of buffer. ++ (Undo): Doc C-/ like C-_. Add xrefs. ++ (Arguments): META key may be labeled ALT. ++ Peculiar arg meanings are explained in doc strings. ++ ++ * abbrevs.texi (Expanding Abbrevs): Clarify. ++ ++2005-02-05 Eli Zaretskii ++ ++ * frames.texi (Frame Parameters): Add an xref to the description ++ of list-colors-display. Add a pointer to the X docs about colors. ++ ++ * cmdargs.texi (Colors): Mention 16-, 88- and 256-color modes. ++ Improve docs of list-colors-display. ++ ++2005-02-03 Lute Kamstra ++ ++ * frames.texi (Frames, Drag and Drop): Fix typos. ++ ++2005-02-03 Richard M. Stallman ++ ++ * windows.texi (Basic Window): Mention color-change in mode line. ++ (Change Window): Explain dragging vertical boundaries. ++ ++ * text.texi (Sentences): Clarify. ++ (Paragraphs): Explain M-a and blank lines. ++ (Outline Mode): Clarify text and menu. ++ (Hard and Soft Newlines): Mention use-hard-newlines. ++ ++ * frames.texi (Frames): Delete unnecessary mention of Windows. ++ (Mouse Commands): Likewise. Mention xterm mouse support. ++ (Clipboard): Clarify. ++ (Mouse References): Mention use of Mouse-1 for following links. ++ (Menu Mouse Clicks): Clarify. ++ (Mode Line Mouse): Clarify. ++ (Drag and Drop): Rewrite. ++ ++ * fixit.texi (Spelling): Fix typo. ++ ++ * files.texi (File Names): Clarify. ++ (Visiting): Update conditions for use of file dialog. Clarify. ++ (Saving): Doc d as answer in save-some-buffers. ++ (Remote Files): Clean up the text. ++ ++ * dired.texi (Misc Dired Commands): Delete dired-marked-files. ++ ++ * buffers.texi (Select Buffer): Doc next-buffer and prev-buffer. ++ (List Buffers): Clarify. ++ (Several Buffers): Doc T command. ++ (Buffer Convenience): Clarify menu. ++ ++ * basic.texi (Undo): Clarify last change. ++ ++2005-02-02 Matt Hodges ++ ++ * fixit.texi (Spelling): Fix typo. ++ ++2005-02-01 Luc Teirlinck ++ ++ * basic.texi (Undo): Update description of `undo-outer-limit'. ++ ++2005-02-01 Nick Roberts ++ ++ * building.texi: Update documentation relating to GDB Graphical ++ Interface. ++ ++2005-01-30 Luc Teirlinck ++ ++ * custom.texi (Easy Customization): Adapt menu to node name change. ++ ++2005-01-30 Richard M. Stallman ++ ++ * custom.texi (Easy Customization): Defn of "User Option" now ++ includes faces. Don't say just "option" when talking about variables. ++ Do say just "options" to mean "anything customizable". ++ (Specific Customization): Describe `customize-variable', ++ not `customize-option'. ++ ++ * glossary.texi (Glossary) : Add xref. ++ : Change definition--include faces. Change xref. ++ ++ * picture.texi (Picture): Mention artist.el. ++ ++ * sending.texi, screen.texi, programs.texi, misc.texi: ++ * mini.texi, major.texi, maintaining.texi, macos.texi: ++ * help.texi, frames.texi, files.texi: ++ Don't say just "option" when talking about variables. ++ ++ * display.texi, mule.texi: Don't say just "option" when talking ++ about variables. Other minor cleanups. ++ ++2005-01-26 Lute Kamstra ++ ++ * cmdargs.texi (Initial Options): Add a cross reference to `Init ++ File'. Mention the `-Q' option at the `--no-site-file' option. ++ ++2005-01-22 David Kastrup ++ ++ * building.texi (Grep Searching): Mention alias `find-grep' for ++ `grep-find'. ++ ++2005-01-20 Richard M. Stallman ++ ++ * calendar.texi (Time Intervals): Delete special stuff for MS-DOS. ++ ++2005-01-15 Sergey Poznyakoff ++ ++ * rmail.texi (Movemail): Explain differences ++ between standard and mailutils versions of movemail. ++ Describe command line and configuration options introduced ++ with the latter. ++ Explain the notion of mailbox URL, provide examples and ++ cross-references to mailutils documentation. ++ Describe various methods of specifying mailbox names, ++ user names and user passwords for rmail. ++ (Remote Mailboxes): New section. Describe ++ how movemail handles remote mailboxes. Describe configuration ++ options used to control its behavior. ++ (Other Mailbox Formats): Explain handling of various mailbox ++ formats. ++ ++2005-01-13 Richard M. Stallman ++ ++ * commands.texi (Commands): Clarification. ++ ++2005-01-11 Richard M. Stallman ++ ++ * programs.texi (Multi-line Indent): Fix previous change. ++ (Fortran Autofill): Simplify description of fortran-auto-fill-mode. ++ ++2005-01-08 Richard M. Stallman ++ ++ * display.texi (Faces): isearch-lazy-highlight-face renamed to ++ lazy-highlight. ++ ++ * search.texi (Query Replace): Mention faces query-replace ++ and lazy-highlight. ++ (Incremental Search): Update isearch highlighting info. ++ ++2005-01-04 Richard M. Stallman ++ ++ * custom.texi (Saving Customizations): Minor improvement. ++ ++2005-01-03 Luc Teirlinck ++ ++ * custom.texi (Saving Customizations): Emacs no longer loads ++ `custom-file' after .emacs. No longer mention customizing through ++ Custom. ++ ++2005-01-01 Andreas Schwab ++ ++ * killing.texi (Graphical Kill): Move up under node Killing, ++ change @section to @subsection. ++ ++2005-01-01 Richard M. Stallman ++ ++ * custom.texi (Face Customization): Mention hex color specs. ++ ++ * emacs.texi (Top): Update Killing submenu. ++ ++ * killing.texi (Killing): Reorganize section. ++ No more TeX-only text; put the node command at start of chapter. ++ But the first section heading is used only in TeX. ++ Rewrite the text to read better in this mode. ++ (Graphical Kill): New subnode gets some of the text that ++ used to be in the first section. ++ ++2004-12-31 Richard M. Stallman ++ ++ * dired.texi (Shell Commands in Dired): Delete the ? example. ++ ++ * display.texi (Scrolling): Correct scroll-preserve-screen-position. ++ ++ * files.texi (Saving): Describe new require-final-newline features ++ and mode-require-final-newline. ++ ++2004-12-29 Richard M. Stallman ++ ++ * custom.texi (File Variables): Clarify previous change. ++ ++2004-12-27 Jan Djärv ++ ++ * frames.texi (Dialog Boxes): Mention Gtk+ 2.6 also, as that version is ++ out now. ++ ++2004-12-27 Richard M. Stallman ++ ++ * Makefile.in (MAKEINFO): Specify --force. ++ ++ * basic.texi (Moving Point): C-e now runs move-end-of-line. ++ (Undo): Doc undo-outer-limit. ++ ++2004-12-15 Juri Linkov ++ ++ * mark.texi (Transient Mark, Mark Ring): M-< and other ++ movement commands don't set mark in Transient Mark mode ++ if mark is active. ++ ++2004-12-12 Juri Linkov ++ ++ * misc.texi (FFAP): Add C-x C-r, C-x C-v, C-x C-d, ++ C-x 4 r, C-x 4 d, C-x 5 r, C-x 5 d. ++ ++ * dired.texi (Dired Navigation): Add @r{(Dired)} to M-g. ++ (Misc Dired Commands): Add @r{(Dired)} to w. ++ ++2004-12-12 Juri Linkov ++ ++ * mark.texi (Marking Objects): Marking commands also extend the ++ region when mark is active in Transient Mark mode. ++ ++2004-12-08 Luc Teirlinck ++ ++ * custom.texi (Saving Customizations): Emacs only loads the custom ++ file automatically after the init file in version 22.1 or later. ++ Adapt text and examples to this fact. ++ ++2004-12-07 Luc Teirlinck ++ ++ * frames.texi (Scroll Bars): The option `scroll-bar-mode' has to ++ be set through Custom. Otherwise, it has no effect. ++ ++2004-12-05 Richard M. Stallman ++ ++ * cmdargs.texi, doclicense.texi, xresources.texi, emacs.texi: ++ * entering.texi: Rename Command Line to Emacs Invocation. ++ ++ * misc.texi (Term Mode): Correctly describe C-c. ++ ++ * custom.texi (Easy Customization): Move up to section level, ++ before Variables. Avoid using the term "variable"; say "option". ++ New initial explanation. ++ (Variables): In initial explanation, connect "variable" to the ++ already-explained "user option". ++ ++ * emacs.texi (Top): Fix ref to Command Line. ++ Move reference to Easy Customization. ++ ++ * xresources.texi (X Resources): Fix From link. ++ ++ * doclicense.texi (GNU Free Documentation License): Fix To link. ++ ++ * entering.texi (Entering Emacs): Fix xref, now to Command Line. ++ ++ * cmdargs.texi (Command Line): Node renamed from Command Arguments. ++ ++2004-12-03 Richard M. Stallman ++ ++ * cmdargs.texi (Initial Options): Clarify batch mode i/o. ++ ++2004-12-01 Luc Teirlinck ++ ++ * kmacro.texi: Several small changes in addition to the following. ++ (Keyboard Macro Ring): Describe behavior of `C-x C-k C-k' when ++ defining a keyboard macro. ++ Mention `kmacro-ring-max'. ++ (Keyboard Macro Counter): Clarify description of ++ `kmacro-insert-counter', `kmacro-set-counter', ++ `kmacro-add-counter' and `kmacro-set-format'. ++ ++2004-11-29 Reiner Steib ++ ++ * custom.texi (File Variables): Add `unibyte' and make it more ++ clear that `unibyte' and `coding' are special. Suggested by Simon ++ Krahnke . ++ ++ * mule.texi (Enabling Multibyte): Refer to File Variables. ++ Suggested by Simon Krahnke . ++ ++2004-11-26 Jan Djärv ++ ++ * frames.texi (Dialog Boxes): Rename use-old-gtk-file-dialog to ++ x-use-old-gtk-file-dialog. ++ ++2004-11-20 Richard M. Stallman ++ ++ * text.texi (Fill Prefix): M-q doesn't apply fill prefix to first line. ++ ++2004-11-09 Lars Brinkhoff ++ ++ * building.texi (Lisp Eval): Delete hyphen in section name. ++ ++2004-11-19 Thien-Thi Nguyen ++ ++ * files.texi (Old Versions): ++ No longer document annotation as "CVS only". ++ ++2004-11-10 Andre Spiegel ++ ++ * files.texi (Version Control): Rewrite the introduction about ++ version systems, mentioning the new ones that we support. Thanks ++ to Alex Ott, Karl Fogel, Stefan Monnier, and David Kastrup for ++ suggestions. ++ ++2004-11-03 Jan Djärv ++ ++ * frames.texi (Dialog Boxes): Replace non-nil with non-@code{nil}. ++ ++2004-11-02 Jan Djärv ++ ++ * frames.texi (Dialog Boxes): Document use-old-gtk-file-dialog. ++ ++2004-10-23 Eli Zaretskii ++ ++ * text.texi (Text Based Tables, Table Definition) ++ (Table Creation, Table Recognition, Cell Commands) ++ (Cell Justification, Row Commands, Column Commands) ++ (Fixed Width Mode, Table Conversion, Measuring Tables) ++ (Table Misc): New nodes, documenting the Table Mode. ++ ++2004-10-19 Jason Rumney ++ ++ * makefile.w32-in (info): Change order of arguments to makeinfo. ++ ++2004-10-19 Ulf Jasper ++ ++ * calendar.texi (iCalendar): Update for package changes. ++ ++2004-10-09 Luc Teirlinck ++ ++ * files.texi (Misc File Ops): View mode is a minor mode. ++ ++2004-10-08 Glenn Morris ++ ++ * calendar.texi (iCalendar): Style changes. ++ ++2004-10-07 Luc Teirlinck ++ ++ * search.texi (Regexps): The regexp described in the example is no ++ longer stored in the variable `sentence-end'. ++ ++2004-10-06 Nick Roberts ++ ++ * building.texi (Starting GUD): Note that multiple debugging ++ sessions requires `gdb --fullname'. ++ ++2004-10-05 Ulf Jasper ++ ++ * calendar.texi (iCalendar): New section for a new package. ++ ++2004-10-05 Luc Teirlinck ++ ++ * text.texi: Various small changes in addition to the following. ++ (Text): Replace xref for autotype with inforef. ++ (Sentences): Explain nil value for `sentence-end'. ++ (Paragraphs): Update default values for `paragraph-start' and ++ `paragraph-separate'. ++ (Text Mode): Correct description of Text mode's effect on the ++ syntax table. ++ (Outline Visibility): `hide-other' does not hide top level headings. ++ `selective-display-ellipses' no longer has an effect on Outline mode. ++ (TeX Misc): Add missing @cindex. ++ Replace xref for RefTeX with inforef. ++ (Requesting Formatted Text): The variable ++ `enriched-fill-after-visiting' no longer exists. ++ (Editing Format Info): Update names of menu items and commands. ++ (Format Faces): Mention special effect of specifying the default face. ++ Describe inheritance of text properties. ++ Correct description of `fixed' face. ++ (Format Indentation): Correct description of effect of setting ++ margins. Mention `set-left-margin' and `set-right-margin'. ++ (Format Justification): Update names of menu items. ++ `set-justification-full' is now bound to `M-j b'. ++ Mention that `default-justification' is a per buffer variable. ++ (Format Properties): Update name of menu item. ++ (Forcing Enriched Mode): `format-decode-buffer' automatically ++ turns on Enriched mode if the buffer is in text/enriched format. ++ ++2004-10-05 Emilio C. Lopes ++ ++ * calendar.texi (From Other Calendar): Add calendar-goto-iso-week. ++ ++2004-09-28 Kim F. Storm ++ ++ * display.texi (Display Custom) : ++ Align with new functionality. ++ ++2004-09-22 Luc Teirlinck ++ ++ * display.texi (Display Custom): Remove stray `@end defvar'. ++ ++2004-09-23 Kim F. Storm ++ ++ * display.texi (Display Custom): Add `overflow-newline-into-fringe', ++ `indicate-buffer-boundaries' and `default-indicate-buffer-boundaries'. ++ ++2004-09-20 Richard M. Stallman ++ ++ * custom.texi (Hooks): Explain using setq to clear out a hook. ++ (File Variables): Explain multiline string constants. ++ (Non-ASCII Rebinding): Explain when you need to update ++ non-ASCII char codes in .emacs. ++ ++ * building.texi (Compilation): Explain how to make a silent ++ subprocess that won't be terminated. Explain compilation-environment. ++ ++2004-09-13 Kim F. Storm ++ ++ * mini.texi (Repetition): Rename isearch-resume-enabled to ++ isearch-resume-in-command-history and change default to disabled. ++ ++2004-09-09 Kim F. Storm ++ ++ * kmacro.texi (Save Keyboard Macro): Replace `name-last-kbd-macro' ++ with new `kmacro-name-last-macro'. ++ ++2004-09-08 Juri Linkov ++ ++ * mini.texi (Minibuffer History): Add `history-delete-duplicates'. ++ ++2004-09-03 Juri Linkov ++ ++ * search.texi (Incremental Search): Update wording for M-%. ++ ++2004-09-02 Luc Teirlinck ++ ++ * killing.texi (Killing): Correct description of kill commands in ++ read-only buffer. ++ ++2004-09-02 Teodor Zlatanov ++ ++ * building.texi (Compilation Mode): Add a paragraph about rules ++ for finding the compilation buffer for `next-error'. ++ ++ * search.texi (Other Repeating Search): Mention that Occur mode ++ supports the next-error functionality. ++ ++2004-09-02 Juri Linkov ++ ++ * search.texi (Regexp Replace): Add missing backslash to \footnote. ++ ++2004-08-31 Luc Teirlinck ++ ++ * kmacro.texi (Basic Keyboard Macro): ++ `apply-macro-to-region-lines' now operates on all lines that begin ++ in the region, rather than on all complete lines in the region. ++ ++2004-08-31 Jan Djärv ++ ++ * frames.texi (Drag and drop): Add documentation about ++ x-dnd-test-function and x-dnd-known-types. ++ ++2004-08-30 Luc Teirlinck ++ ++ * indent.texi: Various minor changes in addition to: ++ (Indentation Commands): Correct description of `indent-relative'. ++ (Tab Stops): is no longer bound to `tab-to-tab-stop' in Text ++ mode. The *Tab Stops* buffer uses Overwrite Mode. ++ (Just Spaces): `tabify' converts sequences of at least two spaces ++ to tabs. ++ ++2004-08-27 Luc Teirlinck ++ ++ * frames.texi (Secondary Selection): Setting the secondary ++ selection with M-Drag-Mouse-1 does not alter the kill ring, ++ setting it with M-Mouse-1 and M-Mouse-3 does. ++ (Mode Line Mouse): C-Mouse-2 on scroll bar now also works for ++ toolkit scroll bars. ++ (Scroll Bars): Ditto. ++ ++ * windows.texi (Basic Window): When using a window system, the value ++ of point in a non-selected window is indicated by a hollow box. ++ (Split Window): Side by side windows are separated by a scroll bar, ++ if scroll bars are used. ++ C-Mouse-2 on scroll bar now also works for toolkit scroll bars. ++ (Change Window): Correct Mouse-2 vs Mouse-3 mess-up. ++ (Window Convenience): Update bindings for `winner-undo' and ++ `winner-redo'. ++ ++ * ack.texi (Acknowledgments): Use `@unnumbered'. ++ * misc.texi: Adapt sectioning in Info to the node structure. ++ (Invoking emacsclient): Make "Invoking emacsclient" a subsection ++ of "Using Emacs as a Server". ++ * building.texi (Building): Interchange nodes (for correct numbering). ++ * programs.texi (Programs): Interchange nodes (for correct numbering). ++ * killing.texi, entering.texi, commands.texi: Adapt sectioning in ++ Info to the node structure. ++ * emacs.texi: Make "GNU GENERAL PUBLIC LICENSE" an appendix. ++ Rearrange order of nodes and sections such that both "GNU GENERAL ++ PUBLIC LICENSE" and "GNU Free Documentation License" appear at the ++ end, as appropriate for appendices. ++ (Acknowledgments): Put inside @iftex instead of @ifnotinfo. ++ Use `@unnumberedsec'. ++ * trouble.texi: Adapt sectioning in Info to the node structure. ++ Adapt node pointers to change in emacs.texi. ++ * cmdargs.texi, doclicense.texi: Adapt node pointers. ++ ++2004-08-25 Kenichi Handa ++ ++ * custom.texi (Non-ASCII Rebinding): Fix and simplify the ++ description for unibyte mode. ++ ++2004-08-23 Luc Teirlinck ++ ++ * display.texi (Font Lock): Correct invalid (for hardcopy) @xref. ++ ++ * search.texi (Regexps): Correct cryptic (in hardcopy) @ref. ++ (Configuring Scrolling): Correct invalid (for hardcopy) @xref. ++ (Regexp Replace): Standardize reference to hardcopy Elisp Manual ++ in @pxref. ++ ++2004-08-22 Luc Teirlinck ++ ++ * kmacro.texi (Keyboard Macro Counter, Keyboard Macro Step-Edit): ++ Change section names. ++ ++2004-08-21 Luc Teirlinck ++ ++ * kmacro.texi (Keyboard Macro Ring): Rename section. ++ Emacs treats the head of the macro ring as the `last keyboard macro'. ++ (Keyboard Macro Counter): Minor change. ++ (Save Keyboard Macro): Some clarifications. ++ (Edit Keyboard Macro): Rename section. ++ ++ * buffers.texi (Buffers): Maximum buffer size is now 256M on ++ 32-bit machines. ++ (Several Buffers): Clarify which buffer is selected if `2' is ++ pressed in the Buffer Menu. ++ Auto Revert mode can be used to update the Buffer Menu ++ automatically. ++ ++2004-08-21 Eli Zaretskii ++ ++ * help.texi (Misc Help): Add an index entry for finding an Info ++ manual by its file name. ++ ++2004-08-20 Luc Teirlinck ++ ++ * files.texi (Backup Deletion): Correct description of ++ `delete-old-versions'. ++ (Time Stamps): `time-stamp' needs to be added to `before-save-hook'. ++ (Auto Save Files): Recommend `auto-save-mode' to reenable ++ auto-saving, rather than the abbreviation `auto-save'. ++ ++2004-08-17 Luc Teirlinck ++ ++ * emacs.texi (Top): Mention "cutting" and "pasting" as synonyms ++ for "killing" and "yanking" in main menu. ++ ++2004-08-16 Richard M. Stallman ++ ++ * killing.texi (Yanking, Killing): Minor cleanups. ++ ++ * mark.texi (Momentary Mark): Minor cleanups. ++ ++2004-08-15 Kenichi Handa ++ ++ * custom.texi (Non-ASCII Rebinding): ++ C-q always inserts the right code to pass to global-set-key. ++ ++2004-08-13 Luc Teirlinck ++ ++ * regs.texi (RegNumbers): Mention `C-x r i' binding for ++ `insert-register', instead of `C-x r g' binding, for consistency. ++ ++2004-08-12 Luc Teirlinck ++ ++ * fixit.texi (Spelling): Fix typo. ++ ++2004-08-11 Luc Teirlinck ++ ++ * help.texi (Help): Fix Texinfo usage. ++ ++2004-07-24 Richard M. Stallman ++ ++ * text.texi (Paragraphs): Update how paragraphs are separated ++ and the default for paragraph-separate. ++ ++ * search.texi (Regexp Replace): Further update text for new ++ replacement operators. ++ ++2004-07-18 Luc Teirlinck ++ ++ * emacs-xtra.texi (Subdir switches): Dired does not remember the ++ `R' switch. ++ ++ * dired.texi (Dired Updating): `k' only deletes inserted ++ subdirectories from the Dired buffer if a prefix argument was given. ++ ++ * search.texi (Regexps): Delete redundant definition of `symbol' in ++ description of `\_>'. It already occurs in the description of `\_<'. ++ ++2004-07-01 Juri Linkov ++ ++ * search.texi (Incremental Search): Add C-M-w, C-M-y, M-%, C-M-%, M-e. ++ (Regexp Search): Add M-r. ++ ++2004-06-30 Luc Teirlinck ++ ++ * makefile.w32-in (EMACSSOURCES): Remove emacs-xtra. ++ ++2004-06-29 Jesper Harder ++ ++ * search.texi, calendar.texi: Markup fixes. ++ ++2004-06-25 Richard M. Stallman ++ ++ * search.texi (Regexp Replace): Rewrite description of \# \, and \?. ++ ++2004-06-25 David Kastrup ++ ++ * search.texi (Regexp Replace): Some typo corrections and ++ rearrangement. ++ ++2004-06-24 David Kastrup ++ ++ * search.texi (Unconditional Replace): Use replace-string instead ++ of query-replace in example. ++ (Regexp Replace): Add explanations for `\,', `\#' and `\?' ++ sequences. ++ (Query Replace): Correct explanation of `^' which does not use ++ the mark stack. ++ ++2004-06-21 Nick Roberts ++ ++ * misc.texi (Shell History Copying): Document comint-insert-input. ++ (Shell Ring): Describe comint-dynamic-list-input-ring here. ++ ++2004-06-20 Jesper Harder ++ ++ * msdog.texi (Text and Binary, MS-DOS Printing): Use m-dash. ++ * custom.texi (Customization): Do. ++ * anti.texi (Antinews): Do. ++ * abbrevs.texi (Defining Abbrevs): Do. ++ ++ * programs.texi (Info Lookup): Fix keybinding for ++ info-lookup-symbol. ++ ++2004-06-16 Juanma Barranquero ++ ++ * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, EMACSSOURCES): ++ Add emacs-xtra. ++ ($(infodir)/emacs-xtra, emacs-xtra.dvi): New dependencies. ++ (clean): Add emacs-xtra and flymake. Remove redundancies. ++ ++2004-06-15 Luc Teirlinck ++ ++ * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/emacs-xtra): ++ Add emacs-xtra. ++ * emacs-xtra.texi: New file. ++ ++2004-06-14 Luc Teirlinck ++ ++ * dired.texi (Dired Enter): Mention conditions on `ls' switches. ++ (Dired and Find): Mention differences with ordinary Dired buffers. ++ ++2004-06-13 Richard M. Stallman ++ ++ * custom.texi (Init Syntax): Explain about vars that do special ++ things when set with setq or with Custom. ++ (Init Examples): Add line-number-mode example. ++ ++2004-06-12 Juri Linkov ++ ++ * dired.texi (Operating on Files): Add dired-do-touch. ++ ++2004-06-10 Juri Linkov ++ ++ * building.texi (Lisp Eval): Add C-M-x on defface. ++ ++2004-06-08 Luc Teirlinck ++ ++ * files.texi (Reverting): Auto-Revert mode and ++ Global Auto-Revert mode no longer revert remote files. ++ ++2004-05-29 Richard M. Stallman ++ ++ * custom.texi (Init File): Two dashes start --no-site-file. ++ ++2004-05-29 Alan Mackenzie ++ ++ * programs.texi: Update for CC Mode 5.30 and incidental amendments. ++ ("AWK"): Is consistently thus spelled throughout. ++ (AWK, Pike): Document as "C-like modes". ++ (@kbd{M-j}): Document as alternative to @kbd{C-M-j}. ++ (M-x man): Supersedes M-x manual-entry. ++ Add numerous index entries. Correct "ESC a/e" to "M-a/e". ++ ++ ("Comments in C"): Delete node; the info is in CC Mode manual. ++ (c-comment-only-line-offset): Remove description. ++ ++ (C-c ., C-c C-c): Describe new C Mode bindings. ++ ++ (C-u TAB, indent-code-rigidly, c-indent-exp, c-tab-always-indent) ++ (@dfn{Style}, c-default-style, comment-column, comment-padding) ++ (c-up-conditional, c-beginning-of-statement, c-end-of-statement): ++ Amend definitions. ++ ++ (c-beginning-of-defun, c-end-of-defun, c-context-line-break): ++ Describe functions. ++ ++ (c-comment-start-regexp, c-hanging-comment-ender-p) ++ (c-hanging-comment-starter-p): Remove obsolete definitions. ++ ++ * emacs.texi: Remove the menu entry "Comments in C". ++ ++2004-05-27 Luc Teirlinck ++ ++ * dired.texi (Dired and Find): `find-ls-option' does not apply to ++ `M-x locate'. ++ ++2004-05-16 Karl Berry ++ ++ * emacs.texi (ack.texi) [@ifnottex]: Change condition; with @ifinfo, ++ makeinfo --html fails. ++ * help.texi (Help Summary) [@ifnottex]: Likewise. ++ ++2004-05-13 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): Update and describe ++ layout first. ++ ++2004-05-04 Jason Rumney ++ ++ * makefile.w32-in: Revert last change. ++ ++2004-05-03 Jason Rumney ++ ++ * makefile.w32-in (MULTI_INSTALL_INFO, ENVADD): Use forward slashes. ++ ++2004-04-23 Juanma Barranquero ++ ++ * makefile.w32-in: Add "-*- makefile -*-" mode tag. ++ ++2004-04-18 Juri Linkov ++ ++ * fixit.texi (Spelling): Remove file extension from ispell xref. ++ ++2004-04-15 Kim F. Storm ++ ++ * cmdargs.texi (Initial Options): Add -Q. ++ ++2004-04-05 Kim F. Storm ++ ++ * custom.texi (File Variables): Add safe-local-eval-forms. ++ ++2004-04-02 Luc Teirlinck ++ ++ * files.texi (Reverting): Correct description of revert-buffer's ++ handling of point. ++ ++2004-03-22 Juri Linkov ++ ++ * emacs.texi (Top): Add `Misc X'. ++ ++ * trouble.texi: Fix help key bindings. ++ ++ * glossary.texi: Improve references. ++ ++ * help.texi: Sync keywords with finder.el. ++ ++ * mini.texi (Completion): Add description for menu items. ++ ++ * misc.texi (Browse-URL, FFAP): Add information about keywords. ++ ++ * sending.texi (Mail Methods): Fix xref to Message manual. ++ ++2004-03-12 Richard M. Stallman ++ ++ * buffers.texi (Misc Buffer): Add index entry for rename-uniquely. ++ ++2004-03-04 Richard M. Stallman ++ ++ * search.texi (Regexps): Explain that ^ and $ have their ++ special meanings only in certain contexts. ++ ++ * programs.texi (Expressions): Doc C-M-SPC as alias for C-M-@. ++ ++ * mule.texi (Specify Coding): Doc C-x RET F. ++ ++ * buffers.texi (Misc Buffer): Explain use of M-x rename-uniquely ++ for multiple compile and grep buffers. ++ (Indirect Buffers): Don't recommand clone-indirect-buffer ++ for multiple compile and grep buffers. ++ ++2004-02-29 Juanma Barranquero ++ ++ * makefile.w32-in (mostlyclean, clean, maintainer-clean): ++ Use $(DEL) instead of rm, and ignore exit code. ++ ++2004-02-23 Nick Roberts ++ ++ * building.texi (Watch Expressions): Update. ++ ++2004-02-21 Juri Linkov ++ ++ * cmdargs.texi (Action Arguments): Add alias --find-file. Add ++ --directory, --help, --version. Move text about command-line-args ++ to Command Arguments. ++ (Initial Options): Add @cindex for --script. Fix @cindex for -q. ++ Add --no-desktop. Add alias --no-multibyte, --no-unibyte. ++ (Window Size X): Join -g and --geometry. Add @cindex. ++ (Borders X): Fix @cindex for -ib. Add @cindex for -bw. ++ (Title X): Remove alias -title. ++ (Misc X): New node. ++ ++2004-02-15 Jan Djärv ++ ++ * frames.texi (Drag and drop): Add Motif to list of supported ++ protocols. ++ ++2004-02-03 Jan Djärv ++ ++ * frames.texi (Drag and drop): New section. ++ ++2004-01-24 Richard M. Stallman ++ ++ * emacs.texi (Acknowledgments): Renamed from Acknowledgements. ++ Include it only @ifnotinfo. Patch the preceding and following ++ node headers to point to each other. ++ ++2004-01-11 Glenn Morris ++ ++ * calendar.texi (Appointments): Update section. ++ ++2003-12-29 Kevin Ryde ++ ++ * programs.texi (C Modes): Fix the xref. ++ ++2003-12-23 Nick Roberts ++ ++ * building.texi (Watch Expressions): Update. ++ (Commands of GUD): Include use of toolbar + breakpoints set from ++ fringe/margin. ++ ++2003-12-03 Andre Spiegel ++ ++ * files.texi: Say how to disable VC. Suggested by Alan Mackenzie ++ . ++ ++2003-11-29 Jan Djärv ++ ++ * frames.texi (Dialog Boxes): Add use-file-dialog. ++ ++2003-11-22 Martin Stjernholm ++ ++ * ack.texi: Note that Alan Mackenzie contributed the AWK support ++ in CC Mode. ++ ++2003-11-02 Jesper Harder (tiny change) ++ ++ * man/ack.texi, man/basic.texi, man/cmdargs.texi: ++ * man/commands.texi, man/custom.texi, man/display.texi: ++ * man/emacs.texi, man/files.texi: ++ * man/frames.texi, man/glossary.texi, man/killing.texi: ++ * man/macos.texi, man/mark.texi, man/misc.texi, man/msdog.texi: ++ * man/mule.texi, man/rmail.texi, man/search.texi: ++ * man/sending.texi, man/text.texi, man/trouble.texi: ++ Replace @sc{ascii} and ASCII with @acronym{ASCII}. ++ ++2003-11-01 Alan Mackenzie ++ ++ * search.texi (Scrolling During Incremental Search): Document a ++ new scrolling facility in isearch mode. ++ ++2003-10-22 Miles Bader ++ ++ * Makefile.in (info): Move before $(top_srcdir)/info. ++ ++2003-10-22 Nick Roberts ++ ++ * building.texi (Watch Expressions): Update section on data display ++ to reflect code changes (GDB Graphical Interface). ++ ++2003-10-13 Richard M. Stallman ++ ++ * xresources.texi (GTK resources): Clean up previous change. ++ ++2003-10-12 Jan Djärv ++ ++ * xresources.texi (GTK resources): Add a note that some themes ++ disallow customizations. Add scroll theme example. ++ ++2003-09-30 Richard M. Stallman ++ ++ * cmdargs.texi (General Variables): Remove MAILRC envvar. ++ ++ * misc.texi (Saving Emacs Sessions): Shorten the section, ++ collapsing back into one node. ++ ++2003-09-30 Lars Hansen ++ ++ * misc.texi: Section "Saving Emacs Sessions" rewritten. ++ ++2003-09-29 Jan Djärv ++ ++ * xresources.texi (GTK names in Emacs): Correct typo. ++ ++2003-09-24 Luc Teirlinck ++ ++ * cmdargs.texi (Font X): Mention new default font. More ++ fully describe long font names, wildcard patterns and the ++ problems involved. (Result of discussion on emacs-devel.) ++ ++2003-09-22 Luc Teirlinck ++ ++ * emacs.texi (Acknowledgements): Correct typo. ++ ++2003-09-22 Richard M. Stallman ++ ++ * dired.texi (Misc Dired Commands): New node. ++ (Dired Navigation): Add dired-goto-file. ++ ++ * files.texi (File Aliases, Misc File Ops): Add @cindex entries. ++ ++ * emacs.texi (Acknowledgements): New node, split from Distribution. ++ ++ * cmdargs.texi (Action Arguments): -f reads interactive args. ++ ++2003-09-08 Lute Kamstra ++ ++ * screen.texi (Mode Line): Say that POS comes before LINE. ++ Mention `size-indication-mode'. ++ * display.texi (Optional Mode Line): Document ++ `size-indication-mode'. ++ * basic.texi (Position Info): Mention `size-indication-mode'. ++ ++2003-09-07 Luc Teirlinck ++ ++ * xresources.texi (Resources): Refer to `editres' man page. ++ (Lucid Resources): Update defaults. Expand description of ++ `shadowThickness'. ++ ++2003-09-04 Miles Bader ++ ++ * Makefile.in (top_srcdir): New variable. ++ ($(top_srcdir)/info): New rule. ++ (info): Depend on it. ++ ++2003-09-03 Peter Runestig ++ ++ * makefile.w32-in: New file. ++ ++2003-08-29 Richard M. Stallman ++ ++ * misc.texi (Saving Emacs Sessions): Correct previous change. ++ ++2003-08-19 Luc Teirlinck ++ ++ * emacs.texi (Top): Update menu to reflect new Keyboard Macros chapter. ++ (Intro): Include kmacro.texi after fixit.texi instead of after ++ custom.texi. (As suggested by Kim Storm.) ++ ++2003-08-18 Luc Teirlinck ++ ++ * fixit.texi (Fixit): Update `Next' pointer. ++ * files.texi (Files): Update `Previous' pointer. ++ * kmacro.texi (Keyboard Macros): Remove redundant node and section. ++ * emacs.texi (Intro): Include kmacro.texi after custom.texi. ++ (Suggested by Kim Storm.) ++ * Makefile (EMACSSOURCES): Add kmacro.texi. (Suggested by Kim Storm.) ++ ++2003-08-18 Kim F. Storm ++ ++ * kmacro.texi: New file describing enhanced keyboard macro ++ functionality. Replaces old description in custom.texi. ++ ++ * custom.texi (Customization): Add xref to Keyboard Macros chapter. ++ (Keyboard Macros): Move to new kmacro.texi file. ++ ++ * emacs.texi (Keyboard Macros): Reference new keyboard macro topics. ++ ++2003-08-17 Edward M. Reingold ++ ++ * calendar.texi (Specified Dates): Add `calendar-goto-day-of-year'. ++ ++2003-08-17 Alex Schroeder ++ ++ * misc.texi (Saving Emacs Sessions): Manual M-x desktop-save not ++ required. ++ ++2003-08-05 Richard M. Stallman ++ ++ * programs.texi (Lisp Indent): Don't describe ++ lisp-indent-function property here. Use xref to Lisp Manual. ++ ++2003-08-03 Glenn Morris ++ ++ * calendar.texi (Date Formats): Document changed behavior of ++ abbreviations. ++ ++2003-07-24 Markus Rost ++ ++ * buffers.texi (List Buffers): Fix previous change. ++ ++2003-07-13 Markus Rost ++ ++ * buffers.texi (List Buffers): Adjust to new format of *Buffer ++ List*. ++ ++2003-07-07 Luc Teirlinck ++ ++ * display.texi (Font Lock): Fix typo. ++ ++2003-07-07 Richard M. Stallman ++ ++ * display.texi (Font Lock): Add xref for format info on ++ font-lock-remove-keywords. ++ ++ * building.texi (Compilation): Document what happens with asynch ++ children of compiler process. ++ ++ * help.texi (Library Keywords): Use @multitable. ++ ++2003-06-04 Richard M. Stallman ++ ++ * programs.texi (Expressions): Delete C-M-DEL. ++ ++ * misc.texi (Shell Options): Clarify comint-scroll-show-maximum-output. ++ comint-move-point-for-output renamed from ++ comint-scroll-to-bottom-on-output. ++ ++ * custom.texi (Init Rebinding): Replace previous change with xref. ++ (Non-ASCII Rebinding): Explain that issue more briefly here. ++ ++2003-05-28 Richard M. Stallman ++ ++ * indent.texi (Indentation): Condense, simplify, clarify prev change. ++ ++2003-05-28 Nick Roberts ++ ++ * building.texi (GDB Graphical Interface): New node. ++ (Rewritten somewhat by RMS.) ++ ++2003-05-28 Kai Großjohann ++ ++ * custom.texi (Init Rebinding): Xref Non-ASCII Rebinding, for ++ non-English letters. Explain how to set coding systems correctly ++ and how to include the right coding cookie in the file. ++ ++2003-05-22 Kai Großjohann ++ ++ * indent.texi (Indentation): Explain the concepts. ++ (Just Spaces): Explain why preventing tabs for indentation might ++ be useful. ++ ++2003-04-16 Richard M. Stallman ++ ++ * search.texi (Regexps): Ref to Lisp manual for more regexp features. ++ ++2003-02-22 Alex Schroeder ++ ++ * cmdargs.texi (General Variables): Document SMTPSERVER. ++ ++ * sending.texi: Remove SMTP node. ++ (Mail Sending): Describe `send-mail-function'. Link to SMTP ++ library. ++ ++2003-02-22 Alex Schroeder ++ ++ * sending.texi (Sending via SMTP): Explain MTA/MUA. ++ ++2003-02-22 Simon Josefsson ++ ++ * sending.texi (Mail Methods): Add node about SMTP. ++ ++2003-02-17 Jan Djärv ++ ++ * xresources.texi (GTK names in Emacs): Add emacs-toolbar - GtkToolbar. ++ ++2003-02-01 Kevin Ryde ++ ++ * glossary.texi (Glossary): Correction to cl cross reference. ++ ++2003-01-20 Richard M. Stallman ++ ++ * killing.texi (Rectangles): Document C-x c r. ++ ++2003-01-19 Jan Djärv ++ ++ * xresources.texi (GTK resources): New node. ++ (GTK widget names): New node. ++ (GTK names in Emacs): New node. ++ (GTK styles): New node. ++ ++2003-01-09 Francesco Potortì ++ ++ * maintaining.texi (Create Tags Table): Add reference to the new ++ `etags --help --lang=LANG' option. ++ ++2002-10-02 Karl Berry ++ ++ * emacs.texi: Per rms, update all manuals to use @copying instead of ++ @ifinfo. Also use @ifnottex instead of @ifinfo around the top node, ++ where needed for the sake of the HTML output. ++ ++2001-12-20 Eli Zaretskii ++ ++ * Makefile.in (EMACSSOURCES): Update the list of Emacs manual ++ source files. ++ ++2001-11-16 Eli Zaretskii ++ ++ * Makefile.in (emacsman): New target. ++ ++2001-10-20 Gerd Moellmann ++ ++ * (Version 21.1 released.) ++ ++2001-10-05 Gerd Moellmann ++ ++ * Branch for 21.1. ++ ++2001-03-05 Gerd Moellmann ++ ++ * Makefile.in (mostlyclean, maintainer-clean): Delete more files. ++ ++2000-05-31 Stefan Monnier ++ ++ * .cvsignore (*.tmp): New entry. Seems to be used for @macro. ++ ++1999-07-12 Richard Stallman ++ ++ * Version 20.4 released. ++ ++1998-12-04 Markus Rost ++ ++ * Makefile.in (INFO_TARGETS): Delete customize.info. ++ (DVI_TARGETS): Delete customize.dvi. ++ (../info/customize, customize.dvi): Targets deleted. ++ ++1998-08-19 Richard Stallman ++ ++ * Version 20.3 released. ++ ++1998-05-06 Richard Stallman ++ ++ * Makefile.in (EMACSSOURCES): Add mule.texi. ++ Add msdog.texi, ack.texi. Remove gnu1.texi. ++ ++1998-04-06 Andreas Schwab ++ ++ * Makefile.in (ENVADD): Enviroment vars to pass to texi2dvi. Use ++ it in dvi targets. ++ ++1997-09-23 Paul Eggert ++ ++ * Makefile.in: Merge changes mistakenly made to `Makefile'. ++ (INFO_TARGETS): Change ../info/custom to ../info/customize. ++ (../info/customize): Rename from ../info/custom. ++ ++1997-09-19 Richard Stallman ++ ++ * Version 20.2 released. ++ ++1997-09-15 Richard Stallman ++ ++ * Version 20.1 released. ++ ++1997-08-24 Richard Stallman ++ ++ * Makefile (../info/customize, customize.dvi): New targets. ++ (INFO_TARGETS): Add ../info/customize. ++ (DVI_TARGETS): Add customize.dvi. ++ ++1996-08-11 Richard Stallman ++ ++ * Version 19.33 released. ++ ++1996-07-31 Richard Stallman ++ ++ * Version 19.32 released. ++ ++1996-06-20 Richard Stallman ++ ++ * Makefile.in (All info targets): cd $(srcdir) to do the work. ++ ++1996-06-19 Richard Stallman ++ ++ * Makefile.in (All info targets): Specify $(srcdir) in input files. ++ Specify -I option. ++ (All dvi targets): Set the TEXINPUTS variable. ++ ++1996-05-25 Karl Heuer ++ ++ * Version 19.31 released. ++ ++1995-11-24 Richard Stallman ++ ++ * Version 19.30 released. ++ ++1995-02-07 Richard Stallman ++ ++ * Makefile.in (maintainer-clean): Rename from realclean. ++ ++1994-11-23 Richard Stallman ++ ++ * Makefile.in: New file. ++ * Makefile: File deleted. ++ ++1994-11-19 Richard Stallman ++ ++ * Makefile (TEXINDEX_OBJS): Variable deleted. ++ (texindex, texindex.o, getopt.o): Rules deleted. ++ All deps on texindex deleted. ++ (distclean): Don't delete texindex. ++ (mostlyclean): Don't delete *.o. ++ * texindex.c, getopt.c: Files deleted. ++ ++1994-09-07 Richard Stallman ++ ++ * Version 19.26 released. ++ ++1994-07-02 Richard Stallman (rms@gnu.ai.mit.edu) ++ ++ * Makefile (EMACSSOURCES): Exclude undo.texi. ++ ++1994-05-30 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Version 19.25 released. ++ ++1994-05-23 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Version 19.24 released. ++ ++1994-05-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Version 19.23 released. ++ ++1994-04-17 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Makefile: Delete spurious tab. ++ ++1994-02-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Makefile (.SUFFIXES): New rule. ++ ++1993-12-04 Richard Stallman (rms@srarc2) ++ ++ * getopt.c: New file. ++ * Makefile (TEXINDEX_OBJS): Use getopt.o in this dir, not ../lib-src. ++ (getopt.o): New rule. ++ (dvi): Don't depend on texindex. ++ (emacs.dvi): Depend on texindex. ++ ++1993-12-03 Richard Stallman (rms@srarc2) ++ ++ * Makefile (TEXI2DVI): New variable. ++ (emacs.dvi): Add explicit command. ++ (TEXINDEX_OBJS): Delete duplicate getopt.o. ++ ++1993-11-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Version 19.22 released. ++ ++1993-11-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Makefile (TEXINDEX_OBJS): Delete spurious period. ++ ++1993-11-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Version 19.21 released. ++ ++1993-11-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Makefile (realclean): Don't delete the Info files. ++ ++1993-10-25 Brian J. Fox (bfox@albert.gnu.ai.mit.edu) ++ ++ * frames.texi (Creating Frames): Mention `C-x 5' instead of `C-x ++ 4' where appropriate. ++ ++1993-10-20 Brian J. Fox (bfox@ai.mit.edu) ++ ++ * Makefile: Fix targets for texindex. ++ ++ * texindex.c: Include "../src/config.h" if building in emacs. ++ ++ * Makefile: Change all files to FILENAME.texi, force all targets ++ to be FILENAME, not FILENAME.info. ++ Add target to build texindex.c, defining `emacs'. ++ ++1993-08-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Version 19.19 released. ++ ++1993-08-08 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Version 19.18 released. ++ ++1993-07-20 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Makefile: Fix source file names of the separate manuals. ++ ++1993-07-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Version 19.17 released. ++ ++1993-07-10 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * split-man: Fix typos in last change. ++ ++1993-07-06 Jim Blandy (jimb@geech.gnu.ai.mit.edu) ++ ++ * Version 19.16 released. ++ ++1993-06-19 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * version 19.15 released. ++ ++1993-06-18 Jim Blandy (jimb@geech.gnu.ai.mit.edu) ++ ++ * Makefile (distclean): It's rm, not rf. ++ ++1993-06-17 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * Version 19.14 released. ++ ++1993-06-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * Makefile: New file. ++ ++1993-06-08 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * Version 19.13 released. ++ ++1993-05-27 Jim Blandy (jimb@geech.gnu.ai.mit.edu) ++ ++ * Version 19.9 released. ++ ++1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * Version 19.8 released. ++ ++1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * cmdargs.texi: Document the -i, -itype, and -iconic options. ++ ++ * trouble.texi: It's `enable-flow-control-on', not ++ `evade-flow-control-on'. ++ ++1993-05-24 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * display.texi: Document standard-display-european. ++ ++1993-05-22 Jim Blandy (jimb@geech.gnu.ai.mit.edu) ++ ++ * Version 19.7 released. ++ ++ * emacs.texi: Add a sentence to the top menu mentioning the ++ specific version of Emacs this manual applies to. ++ ++1993-04-25 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) ++ ++ * basic.texi: Document next-line-add-lines variable used to ++ implement down-arrow. ++ ++ * killing.texi: Document kill-whole-line. ++ ++1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) ++ ++ * text.texi: Update unix TeX ordering information. ++ ++1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) ++ ++ * news.texi: Mention fill-rectangle in keybinding list. ++ ++ * killing.texi: Document fill-rectangle. ++ ++1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) ++ ++ * vc.texi: Bring the docs up to date with VC 5.2. ++ ++1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) ++ ++ * emacs.tex: Mention blackbox and gomoku under Amusements. ++ Assembler mode is now mentioned and appropriately indexed ++ under Programming Modes. ++ ++1991-02-15 Robert J. Chassell (bob@wookumz.ai.mit.edu) ++ ++ * emacs.tex: Update TeX ordering information. ++ ++1990-06-26 David Lawrence (tale@geech) ++ ++ * emacs.tex: Note that completion-ignored-extensions is not used ++ to filter out names when all completions are displayed in ++ *Completions*. ++ ++1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu) ++ ++ * texindex.tex: If USG, include sys/types.h and sys/fcntl.h. ++ ++1990-03-21 Jim Kingdon (kingdon@pogo.ai.mit.edu) ++ ++ * emacs.tex: Add @findex grep. ++ ++1988-08-16 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) ++ ++ * emacs.tex: Correct two typos. No other changes before ++ Version 19 will be made. ++ ++1988-05-23 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) ++ ++ * emacs.tex: Update information for obtaining TeX distribution from the ++ University of Washington. ++ ++;; Local Variables: ++;; coding: utf-8 ++;; fill-column: 79 ++;; add-log-time-zone-rule: t ++;; End: ++ ++ Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, ++ 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++ ++ This file is part of GNU Emacs. ++ ++ GNU Emacs 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. ++ ++ GNU Emacs 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 GNU Emacs. If not, see . ++ ++;;; arch-tag: f1d62776-3ed5-4811-9d96-267252577dbd +diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in +new file mode 100644 +index 0000000..edb845b +--- /dev/null ++++ b/doc/emacs/Makefile.in +@@ -0,0 +1,159 @@ ++#### Makefile for the Emacs Manual ++ ++# Copyright (C) 1994, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, ++# 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++ ++# This file is part of GNU Emacs. ++ ++# GNU Emacs 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. ++ ++# GNU Emacs 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 GNU Emacs. If not, see . ++ ++ ++# Where to find the source code. $(srcdir) will be the man ++# subdirectory of the source tree. This is ++# set by the configure script's `--srcdir' option. ++srcdir=@srcdir@ ++top_srcdir=@top_srcdir@ ++ ++# Tell make where to find source files; this is needed for the makefiles. ++VPATH=@srcdir@ ++ ++## Where the output files go. ++## Note that the setfilename command in the .texi files assumes this. ++infodir=../../info ++# Directory with the (customized) texinfo.tex file. ++texinfodir = $(srcdir)/../misc ++ ++# The makeinfo program is part of the Texinfo distribution. ++# Use --force so that it generates output even if there are errors. ++MAKEINFO = makeinfo --force ++ ++INFO_TARGETS = $(infodir)/emacs ++DVI_TARGETS = emacs.dvi ++ ++ ++TEXI2DVI = texi2dvi ++ ++# The following rule does not work with all versions of `make'. ++.SUFFIXES: .texi .dvi ++.texi.dvi: ++ $(TEXI2DVI) $< ++ ++ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" MAKEINFO="$(MAKEINFO) -I$(srcdir)" ++ ++ ++EMACS_XTRA=\ ++ $(srcdir)/arevert-xtra.texi \ ++ $(srcdir)/cal-xtra.texi \ ++ $(srcdir)/dired-xtra.texi \ ++ $(srcdir)/picture-xtra.texi \ ++ $(srcdir)/emerge-xtra.texi \ ++ $(srcdir)/vc-xtra.texi \ ++ $(srcdir)/vc1-xtra.texi \ ++ $(srcdir)/fortran-xtra.texi \ ++ $(srcdir)/msdog-xtra.texi ++ ++EMACSSOURCES= \ ++ ${srcdir}/emacs.texi \ ++ ${srcdir}/doclicense.texi \ ++ ${srcdir}/gpl.texi \ ++ ${srcdir}/screen.texi \ ++ ${srcdir}/commands.texi \ ++ ${srcdir}/entering.texi \ ++ ${srcdir}/basic.texi \ ++ ${srcdir}/mini.texi \ ++ ${srcdir}/m-x.texi \ ++ ${srcdir}/help.texi \ ++ ${srcdir}/mark.texi \ ++ ${srcdir}/killing.texi \ ++ ${srcdir}/regs.texi \ ++ ${srcdir}/display.texi \ ++ ${srcdir}/search.texi \ ++ ${srcdir}/fixit.texi \ ++ ${srcdir}/files.texi \ ++ ${srcdir}/buffers.texi \ ++ ${srcdir}/windows.texi \ ++ ${srcdir}/frames.texi \ ++ ${srcdir}/mule.texi \ ++ ${srcdir}/major.texi \ ++ ${srcdir}/indent.texi \ ++ ${srcdir}/text.texi \ ++ ${srcdir}/programs.texi \ ++ ${srcdir}/building.texi \ ++ ${srcdir}/maintaining.texi \ ++ ${srcdir}/abbrevs.texi \ ++ ${srcdir}/sending.texi \ ++ ${srcdir}/rmail.texi \ ++ ${srcdir}/dired.texi \ ++ ${srcdir}/calendar.texi \ ++ ${srcdir}/misc.texi \ ++ ${srcdir}/custom.texi \ ++ ${srcdir}/trouble.texi \ ++ ${srcdir}/cmdargs.texi \ ++ ${srcdir}/xresources.texi \ ++ ${srcdir}/anti.texi \ ++ ${srcdir}/macos.texi \ ++ ${srcdir}/msdog.texi \ ++ ${srcdir}/gnu.texi \ ++ ${srcdir}/glossary.texi \ ++ ${srcdir}/ack.texi \ ++ ${srcdir}/kmacro.texi \ ++ $(EMACS_XTRA) ++ ++info: $(infodir) $(INFO_TARGETS) ++ ++$(infodir): ++ mkdir $@ ++ ++dvi: $(DVI_TARGETS) ++ ++# Note that all the Info targets build the Info files ++# in srcdir. There is no provision for Info files ++# to exist in the build directory. ++# In a distribution of Emacs, the Info files should be up to date. ++ ++emacs : $(infodir)/emacs ++ ++$(infodir)/emacs: ${EMACSSOURCES} ++ cd $(srcdir); $(MAKEINFO) emacs.texi ++ ++emacs.dvi: ${EMACSSOURCES} ++ $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi ++ ++ ++emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) ++ $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi ++ ++ ++mostlyclean: ++ rm -f *.log *.cp *.fn *.ky *.op *.ops *.pg *.vr core *.tp *.core ++ rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc ++ ++clean: mostlyclean ++ rm -f *.dvi ++ ++distclean: clean ++# rm -f Makefile ++ ++maintainer-clean: distclean ++ for file in $(INFO_TARGETS); do rm -f $${file}*; done ++ ++ ++# Formerly this directory had texindex.c and getopt.c in it ++# and this makefile built them to make texindex. ++# That caused trouble because this is run entirely in the source directory. ++# Since we expect to get texi2dvi from elsewhere, ++# it is ok to expect texindex from elsewhere also. ++ ++ ++### Makefile ends here +diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi +new file mode 100644 +index 0000000..0740e06 +--- /dev/null ++++ b/doc/emacs/abbrevs.texi +@@ -0,0 +1,461 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, ++@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Abbrevs ++@chapter Abbrevs ++@cindex abbrevs ++@cindex expansion (of abbrevs) ++ ++ A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert ++it, into some different text. Abbrevs are defined by the user to expand ++in specific ways. For example, you might define @samp{foo} as an abbrev ++expanding to @samp{find outer otter}. Then you could insert ++@samp{find outer otter } into the buffer by typing @kbd{f o o ++@key{SPC}}. ++ ++ A second kind of abbreviation facility is called @dfn{dynamic abbrev ++expansion}. You use dynamic abbrev expansion with an explicit command ++to expand the letters in the buffer before point by looking for other ++words in the buffer that start with those letters. @xref{Dynamic ++Abbrevs}. ++ ++ ``Hippie'' expansion generalizes abbreviation expansion. ++@xref{Hippie Expand, , Hippie Expansion, autotype, Features for ++Automatic Typing}. ++ ++@menu ++* Abbrev Concepts:: Fundamentals of defined abbrevs. ++* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. ++* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. ++* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. ++* Saving Abbrevs:: Saving the entire list of abbrevs for another session. ++* Dynamic Abbrevs:: Abbreviations for words already in the buffer. ++* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. ++@end menu ++ ++@node Abbrev Concepts ++@section Abbrev Concepts ++ ++ An @dfn{abbrev} is a word which has been defined to @dfn{expand} into ++a specified @dfn{expansion}. When you insert a word-separator character ++following the abbrev, that expands the abbrev---replacing the abbrev ++with its expansion. For example, if @samp{foo} is defined as an abbrev ++expanding to @samp{find outer otter}, then you can insert @samp{find ++outer otter.} into the buffer by typing @kbd{f o o .}. ++ ++@findex abbrev-mode ++@vindex abbrev-mode ++@cindex Abbrev mode ++@cindex mode, Abbrev ++ Abbrevs expand only when Abbrev mode (a minor mode) is enabled. ++Disabling Abbrev mode does not cause abbrev definitions to be forgotten, ++but they do not expand until Abbrev mode is enabled again. The command ++@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it ++turns Abbrev mode on if the argument is positive, off otherwise. ++@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is ++on when the variable is non-@code{nil}. The variable @code{abbrev-mode} ++automatically becomes local to the current buffer when it is set. ++ ++ Abbrevs can have @dfn{mode-specific} definitions, active only in one major ++mode. Abbrevs can also have @dfn{global} definitions that are active in ++all major modes. The same abbrev can have a global definition and various ++mode-specific definitions for different major modes. A mode-specific ++definition for the current major mode overrides a global definition. ++ ++ You can define abbrevs interactively during the editing session. You ++can also save lists of abbrev definitions in files for use in later ++sessions. Some users keep extensive lists of abbrevs that they load ++in every session. ++ ++@node Defining Abbrevs ++@section Defining Abbrevs ++ ++@table @kbd ++@item C-x a g ++Define an abbrev, using one or more words before point as its expansion ++(@code{add-global-abbrev}). ++@item C-x a l ++Similar, but define an abbrev specific to the current major mode ++(@code{add-mode-abbrev}). ++@item C-x a i g ++Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}). ++@item C-x a i l ++Define a word in the buffer as a mode-specific abbrev ++(@code{inverse-add-mode-abbrev}). ++@item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} ++Define @var{abbrev} as an abbrev expanding into @var{exp}. ++@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} ++Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}. ++@item M-x kill-all-abbrevs ++Discard all abbrev definitions, leaving a blank slate. ++@end table ++ ++@kindex C-x a g ++@findex add-global-abbrev ++ The usual way to define an abbrev is to enter the text you want the ++abbrev to expand to, position point after it, and type @kbd{C-x a g} ++(@code{add-global-abbrev}). This reads the abbrev itself using the ++minibuffer, and then defines it as an abbrev for one or more words before ++point. Use a numeric argument to say how many words before point should be ++taken as the expansion. For example, to define the abbrev @samp{foo} as ++mentioned above, insert the text @samp{find outer otter} and then type ++@kbd{C-u 3 C-x a g f o o @key{RET}}. ++ ++ An argument of zero to @kbd{C-x a g} means to use the contents of the ++region as the expansion of the abbrev being defined. ++ ++@kindex C-x a l ++@findex add-mode-abbrev ++ The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but ++defines a mode-specific abbrev. Mode-specific abbrevs are active only in a ++particular major mode. @kbd{C-x a l} defines an abbrev for the major mode ++in effect at the time @kbd{C-x a l} is typed. The arguments work the same ++as for @kbd{C-x a g}. ++ ++@kindex C-x a i g ++@findex inverse-add-global-abbrev ++@kindex C-x a i l ++@findex inverse-add-mode-abbrev ++ If the abbrev text itself is already in the buffer, you can use the ++commands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and ++@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as an ++abbrev by specify the expansion in the minibuffer. These commands are ++called ``inverse'' because they invert the meaning of the two text ++strings they use (one from the buffer and one read with the ++minibuffer). ++ ++@findex define-mode-abbrev ++@findex define-global-abbrev ++ You can define an abbrev without inserting either the abbrev or its ++expansion in the buffer using the command @code{define-global-abbrev}. ++It reads two arguments---the abbrev, and its expansion. The command ++@code{define-mode-abbrev} does likewise for a mode-specific abbrev. ++ ++ To change the definition of an abbrev, just define a new definition. ++When the abbrev has a prior definition, the abbrev definition commands ++ask for confirmation before replacing it. ++ ++@findex kill-all-abbrevs ++ To remove an abbrev definition, give a negative argument to the ++abbrev definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. ++The former removes a global definition, while the latter removes a ++mode-specific definition. @kbd{M-x kill-all-abbrevs} removes all ++abbrev definitions, both global and local. ++ ++@node Expanding Abbrevs ++@section Controlling Abbrev Expansion ++ ++ When Abbrev mode is enabled, an abbrev expands whenever it is ++present in the buffer just before point and you type a self-inserting ++whitespace or punctuation character (@key{SPC}, comma, etc.@:). More ++precisely, any character that is not a word constituent expands an ++abbrev, and any word-constituent character can be part of an abbrev. ++The most common way to use an abbrev is to insert it and then insert a ++punctuation or whitespace character to expand it. ++ ++@vindex abbrev-all-caps ++ Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find ++outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into ++@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the ++variable @code{abbrev-all-caps} (setting it non-@code{nil} specifies ++@samp{FIND OUTER OTTER}). ++ ++ These commands are used to control abbrev expansion: ++ ++@table @kbd ++@item M-' ++Separate a prefix from a following abbrev to be expanded ++(@code{abbrev-prefix-mark}). ++@item C-x a e ++@findex expand-abbrev ++Expand the abbrev before point (@code{expand-abbrev}). ++This is effective even when Abbrev mode is not enabled. ++@item M-x expand-region-abbrevs ++Expand some or all abbrevs found in the region. ++@end table ++ ++@kindex M-' ++@findex abbrev-prefix-mark ++ You may wish to expand an abbrev and attach a prefix to the expansion; ++for example, if @samp{cnst} expands into @samp{construction}, you might want ++to use it to enter @samp{reconstruction}. It does not work to type ++@kbd{recnst}, because that is not necessarily a defined abbrev. What ++you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in ++between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert ++@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to ++indicate that it has done its work. Then insert the abbrev @samp{cnst}; ++the buffer now contains @samp{re-cnst}. Now insert a non-word character ++to expand the abbrev @samp{cnst} into @samp{construction}. This ++expansion step also deletes the hyphen that indicated @kbd{M-'} had been ++used. The result is the desired @samp{reconstruction}. ++ ++ If you actually want the text of the abbrev in the buffer, rather than ++its expansion, you can accomplish this by inserting the following ++punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in ++the buffer, not expanding it. ++ ++@findex unexpand-abbrev ++ If you expand an abbrev by mistake, you can undo the expansion and ++bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}). ++This also undoes the insertion of the non-word character that expanded ++the abbrev. If the result you want is the terminating non-word ++character plus the unexpanded abbrev, you must reinsert the terminating ++character, quoting it with @kbd{C-q}. You can also use the command ++@kbd{M-x unexpand-abbrev} to cancel the last expansion without ++deleting the terminating character. ++ ++@findex expand-region-abbrevs ++ @kbd{M-x expand-region-abbrevs} searches through the region for defined ++abbrevs, and for each one found offers to replace it with its expansion. ++This command is useful if you have typed in text using abbrevs but forgot ++to turn on Abbrev mode first. It may also be useful together with a ++special set of abbrev definitions for making several global replacements at ++once. This command is effective even if Abbrev mode is not enabled. ++ ++ Expanding any abbrev runs @code{abbrev-expand-functions}, a special ++hook. Functions in this special hook can make arbitrary changes to ++the abbrev expansion. @xref{Abbrev Expansion,,, elisp, The Emacs Lisp ++Reference Manual}. ++ ++@node Editing Abbrevs ++@section Examining and Editing Abbrevs ++ ++@table @kbd ++@item M-x list-abbrevs ++Display a list of all abbrev definitions. With a numeric argument, list ++only local abbrevs. ++@item M-x edit-abbrevs ++Edit a list of abbrevs; you can add, alter or remove definitions. ++@end table ++ ++@findex list-abbrevs ++ The output from @kbd{M-x list-abbrevs} looks like this: ++ ++@example ++@var{various other tables@dots{}} ++(lisp-mode-abbrev-table) ++"dk" 0 "define-key" ++(global-abbrev-table) ++"dfn" 0 "definition" ++@end example ++ ++@noindent ++(Some blank lines of no semantic significance, and some other abbrev ++tables, have been omitted.) ++ ++ A line containing a name in parentheses is the header for abbrevs in a ++particular abbrev table; @code{global-abbrev-table} contains all the global ++abbrevs, and the other abbrev tables that are named after major modes ++contain the mode-specific abbrevs. ++ ++ Within each abbrev table, each nonblank line defines one abbrev. The ++word at the beginning of the line is the abbrev. The number that ++follows is the number of times the abbrev has been expanded. Emacs ++keeps track of this to help you see which abbrevs you actually use, so ++that you can eliminate those that you don't use often. The string at ++the end of the line is the expansion. ++ ++ Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs ++(@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) are ++pre-defined by various modes, and are not saved to your abbrev file. ++To disable a ``system'' abbrev, define an abbrev of the same name that ++expands to itself, and save it to your abbrev file. ++ ++@findex edit-abbrevs ++@kindex C-c C-c @r{(Edit Abbrevs)} ++ @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev ++definitions by editing a list of them in an Emacs buffer. The list has ++the same format described above. The buffer of abbrevs is called ++@samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in ++this buffer to install the abbrev definitions as specified in the ++buffer---and delete any abbrev definitions not listed. ++ ++ The command @code{edit-abbrevs} is actually the same as ++@code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*} ++whereas @code{list-abbrevs} merely displays it in another window. ++ ++@node Saving Abbrevs ++@section Saving Abbrevs ++ ++ These commands allow you to keep abbrev definitions between editing ++sessions. ++ ++@table @kbd ++@item M-x write-abbrev-file @key{RET} @var{file} @key{RET} ++Write a file @var{file} describing all defined abbrevs. ++@item M-x read-abbrev-file @key{RET} @var{file} @key{RET} ++Read the file @var{file} and define abbrevs as specified therein. ++@item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET} ++Similar but do not display a message about what is going on. ++@item M-x define-abbrevs ++Define abbrevs from definitions in current buffer. ++@item M-x insert-abbrevs ++Insert all abbrevs and their expansions into current buffer. ++@end table ++ ++@findex write-abbrev-file ++ @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and ++then writes a description of all current abbrev definitions into that ++file. This is used to save abbrev definitions for use in a later ++session. The text stored in the file is a series of Lisp expressions ++that, when executed, define the same abbrevs that you currently have. ++ ++@findex read-abbrev-file ++@findex quietly-read-abbrev-file ++@vindex abbrev-file-name ++@cindex abbrev file ++ @kbd{M-x read-abbrev-file} reads a file name using the minibuffer ++and then reads the file, defining abbrevs according to the contents of ++the file. The function @code{quietly-read-abbrev-file} is similar ++except that it does not display a message in the echo area; you cannot ++invoke it interactively, and it is used primarily in the @file{.emacs} ++file. If either of these functions is called with @code{nil} as the ++argument, it uses the file name specified in the variable ++@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}. ++That file is your standard abbrev definition file, and Emacs loads ++abbrevs from it automatically when it starts up. (As an exception, ++Emacs does not load the abbrev file when it is started in batch mode. ++@xref{Initial Options}, for a description of batch mode.) ++ ++@vindex save-abbrevs ++ Emacs will offer to save abbrevs automatically if you have changed ++any of them, whenever it offers to save all files (for @kbd{C-x s} or ++@kbd{C-x C-c}). It saves them in the file specified by ++@code{abbrev-file-name}. This feature can be inhibited by setting the ++variable @code{save-abbrevs} to @code{nil}. ++ ++@findex insert-abbrevs ++@findex define-abbrevs ++ The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are ++similar to the previous commands but work on text in an Emacs buffer. ++@kbd{M-x insert-abbrevs} inserts text into the current buffer after point, ++describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses ++the entire current buffer and defines abbrevs accordingly. ++ ++@node Dynamic Abbrevs ++@section Dynamic Abbrev Expansion ++ ++ The abbrev facility described above operates automatically as you ++insert text, but all abbrevs must be defined explicitly. By contrast, ++@dfn{dynamic abbrevs} allow the meanings of abbreviations to be ++determined automatically from the contents of the buffer, but dynamic ++abbrev expansion happens only when you request it explicitly. ++ ++@kindex M-/ ++@kindex C-M-/ ++@findex dabbrev-expand ++@findex dabbrev-completion ++@table @kbd ++@item M-/ ++Expand the word in the buffer before point as a @dfn{dynamic abbrev}, ++by searching in the buffer for words starting with that abbreviation ++(@code{dabbrev-expand}). ++ ++@item C-M-/ ++Complete the word before point as a dynamic abbrev ++(@code{dabbrev-completion}). ++@end table ++ ++@vindex dabbrev-limit ++ For example, if the buffer contains @samp{does this follow } and you ++type @kbd{f o M-/}, the effect is to insert @samp{follow} because that ++is the last word in the buffer that starts with @samp{fo}. A numeric ++argument to @kbd{M-/} says to take the second, third, etc.@: distinct ++expansion found looking backward from point. Repeating @kbd{M-/} ++searches for an alternative expansion by looking farther back. After ++scanning all the text before point, it searches the text after point. ++The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far ++away in the buffer to search for an expansion. ++ ++@vindex dabbrev-check-all-buffers ++ After scanning the current buffer, @kbd{M-/} normally searches other ++buffers, unless you have set @code{dabbrev-check-all-buffers} to ++@code{nil}. ++ ++@vindex dabbrev-ignored-buffer-regexps ++ For finer control over which buffers to scan, customize the variable ++@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regular ++expressions. If a buffer's name matches any of these regular ++expressions, dynamic abbrev expansion skips that buffer. ++ ++ A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to ++search first for expansions after point, then other buffers, and ++consider expansions before point only as a last resort. If you repeat ++the @kbd{M-/} to look for another expansion, do not specify an ++argument. Repeating @kbd{M-/} cycles through all the expansions after ++point and then the expansions before point. ++ ++ After you have expanded a dynamic abbrev, you can copy additional ++words that follow the expansion in its original context. Simply type ++@kbd{@key{SPC} M-/} for each additional word you want to copy. The ++spacing and punctuation between words is copied along with the words. ++ ++ The command @kbd{C-M-/} (@code{dabbrev-completion}) performs ++completion of a dynamic abbrev. Instead of trying the possible ++expansions one by one, it finds all of them, then inserts the text ++that they have in common. If they have nothing in common, @kbd{C-M-/} ++displays a list of completions, from which you can select a choice in ++the usual manner. @xref{Completion}. ++ ++ Dynamic abbrev expansion is completely independent of Abbrev mode; the ++expansion of a word with @kbd{M-/} is completely independent of whether ++it has a definition as an ordinary abbrev. ++ ++@node Dabbrev Customization ++@section Customizing Dynamic Abbreviation ++ ++ Normally, dynamic abbrev expansion ignores case when searching for ++expansions. That is, the expansion need not agree in case with the word ++you are expanding. ++ ++@vindex dabbrev-case-fold-search ++ This feature is controlled by the variable ++@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in ++this search; if it is @code{nil}, the word and the expansion must match ++in case. If the value of @code{dabbrev-case-fold-search} is ++@code{case-fold-search}, which is true by default, then the variable ++@code{case-fold-search} controls whether to ignore case while searching ++for expansions. ++ ++@vindex dabbrev-case-replace ++ Normally, dynamic abbrev expansion preserves the case pattern ++@emph{of the dynamic abbrev you are expanding}, by converting the ++expansion to that case pattern. ++ ++@vindex dabbrev-case-fold-search ++ The variable @code{dabbrev-case-replace} controls whether to ++preserve the case pattern of the dynamic abbrev. If it is @code{t}, ++the dynamic abbrev's case pattern is preserved in most cases; if it is ++@code{nil}, the expansion is always copied verbatim. If the value of ++@code{dabbrev-case-replace} is @code{case-replace}, which is true by ++default, then the variable @code{case-replace} controls whether to ++copy the expansion verbatim. ++ ++ However, if the expansion contains a complex mixed case pattern, and ++the dynamic abbrev matches this pattern as far as it goes, then the ++expansion is always copied verbatim, regardless of those variables. ++Thus, for example, if the buffer contains ++@code{variableWithSillyCasePattern}, and you type @kbd{v a M-/}, it ++copies the expansion verbatim including its case pattern. ++ ++@vindex dabbrev-abbrev-char-regexp ++ The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil}, ++controls which characters are considered part of a word, for dynamic expansion ++purposes. The regular expression must match just one character, never ++two or more. The same regular expression also determines which ++characters are part of an expansion. The value @code{nil} has a special ++meaning: dynamic abbrevs are made of word characters, but expansions are ++made of word and symbol characters. ++ ++@vindex dabbrev-abbrev-skip-leading-regexp ++ In shell scripts and makefiles, a variable name is sometimes prefixed ++with @samp{$} and sometimes not. Major modes for this kind of text can ++customize dynamic abbrev expansion to handle optional prefixes by setting ++the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value ++should be a regular expression that matches the optional prefix that ++dynamic abbrev expression should ignore. ++ ++@ignore ++ arch-tag: 638e0079-9540-48ec-9166-414083e16445 ++@end ignore +diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi +new file mode 100644 +index 0000000..6981774 +--- /dev/null ++++ b/doc/emacs/ack.texi +@@ -0,0 +1,1402 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2002, 2003, ++@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@node Acknowledgments, Screen, Concept Index, Top ++@unnumbered Acknowledgments ++ ++Many people have contributed code included in the Free Software ++Foundation's distribution of GNU Emacs. To show our appreciation for ++their public spirit, we list here in alphabetical order those who have ++written substantial portions. Others too numerous to mention have ++reported and fixed bugs, and added features to many parts of Emacs. ++We thank them for their generosity as well. ++ ++This list is intended to mention every contributor of a major package or ++feature we currently distribute; if you know of someone we have omitted, ++please report that as a manual bug. More comprehensive information is ++available in the @file{ChangeLog} files, summarized in the file ++@file{etc/AUTHORS} in the distribution. ++ ++@c We should list here anyone who has contributed a new package, ++@c and anyone who has made major enhancements in Emacs ++@c that many users would notice and consider important. ++@c Remove things that are no longer distributed. ++@c Note this file is only used ifnottex; otherwise a shorter version in ++@c emacs.texi is used. ++ ++@itemize @bullet ++@item ++Per Abrahamsen wrote the customization facilities, as well as ++@file{double.el}, for typing accented characters not normally available ++from the keyboard; @file{xt-mouse.el}, which allows mouse commands ++through Xterm; @file{gnus-cus.el}, which implements customization ++commands for Gnus; @file{gnus-cite.el}, a citation-parsing facility for ++news articles); @file{gnus-score.el}, scoring for Gnus; @file{cpp.el}, ++which hides or highlights parts of C programs according to preprocessor ++conditionals; and the widget library files @file{wid-browse.el}, ++@file{wid-edit.el}, @file{widget.el}. He also co-wrote ++@file{gnus-soup.el}. ++ ++@item ++Tomas Abrahamsson wrote @file{artist.el}, a package for producing ++@acronym{ASCII} art with a mouse or with keyboard keys. ++ ++@item ++Jay K.@: Adams wrote @file{jka-compr.el} and @file{jka-cmpr-hook.el}, ++providing automatic decompression and recompression for compressed ++files. ++ ++@item ++Michael Albinus wrote @file{dbus.el}, a package that implements the ++D-Bus message bus protocol; @file{zeroconf.el}, a mode for browsing ++Avahi services; and @file{xesam.el}, a Xesam-based search engine ++interface. He and Kai Gro@ss{}johann wrote the Tramp package, which ++provides transparent remote file editing using rcp, ssh, ftp, and ++other network protocols. He and Daniel Pittman wrote ++@file{tramp-cache.el}. ++ ++@item ++Ralf Angeli wrote @file{scroll-lock.el}, a minor mode which keeps the ++point vertically fixed by scrolling the window when moving up and down ++in the buffer. ++ ++@item ++Joe Arceneaux wrote the original text property implementation, and ++implemented support for X11. ++ ++@item ++Miles Bader wrote @file{image-file.el}, support code for visiting image ++files; @file{minibuf-eldef.el}, a minor mode that hides the minibuffer ++default value when appropriate; @file{rfn-eshadow.el}, shadowing of ++@code{read-file-name} input; @file{mb-depth.el}, display of minibuffer ++depth; @file{button.el}, the library that implements clickable buttons; ++@file{face-remap.el}, a package for changing the default face in ++individual buffers; and @file{macroexp.el} for macro-expansion. ++ ++@item ++David Bakhash wrote @file{strokes.el}, a mode for controlling Emacs by ++moving the mouse in particular patterns. ++ ++@item ++Eli Barzilay wrote @file{calculator.el}, a desktop calculator for ++Emacs. ++ ++@item ++Steven L.@: Baur wrote @file{footnote.el} which lets you include ++footnotes in email messages; and @file{gnus-audio.el} and ++@file{earcon.el}, which provide sound effects for Gnus. He also wrote ++@file{gnus-setup.el}. ++ ++@item ++Alexander L.@: Belikoff, Sergey Berezin, Sacha Chua, David Edmondson, ++Noah Friedman, Andreas Fuchs, Mario Lang, Ben Mesander, Lawrence ++Mitchell, Gergely Nagy, Michael Olson, Per Persson, Jorgen Schaefer, ++Alex Schroeder, and Tom Tromey wrote ERC, an advanced Internet Relay ++Chat client (for more information, see the file @file{CREDITS} in the ++ERC distribution). ++ ++@item ++Scott Bender, Michael Brouwer, Christophe de Dinechin, Carl Edman, ++Christian Limpach and Adrian Robert developed and maintained the ++NeXTstep port of Emacs. ++ ++@item ++Anna M.@: Bigatti wrote @file{cal-html.el}, which produces HTML calendars. ++ ++@item ++Ray Blaak and Simon South wrote @file{delphi.el}, a mode for editing ++Delphi (Object Pascal) source code. ++ ++@item ++Martin Blais, Stefan Merten, and David Goodger wrote @file{rst.el}, a ++mode for editing reStructuredText documents. ++ ++@item ++Jim Blandy wrote Emacs 19's input system, brought its configuration and ++build process up to the GNU coding standards, and contributed to the ++frame support and multi-face support. Jim also wrote @file{tvi970.el}, ++terminal support for the TeleVideo 970 terminals; and co-wrote ++@file{wyse50.el} (q.v.@:). ++ ++@item ++Per Bothner wrote @file{term.el}, a terminal emulator in an Emacs ++buffer. ++ ++@item ++Terrence M.@: Brannon wrote @file{landmark.el}, a neural-network robot ++that learns landmarks. ++ ++@item ++Frank Bresz wrote @file{diff.el}, a program to display @code{diff} ++output. ++ ++@item ++Peter Breton implemented @file{dirtrack.el}, a library for tracking ++directory changes in shell buffers; @file{filecache.el}, which records ++which directories your files are in; @file{locate.el}, which ++interfaces to the @code{locate} command; @file{find-lisp.el}, an Emacs ++Lisp emulation of the @command{find} program; @file{net-utils.el}; and ++the ``generic mode'' feature. ++ ++@item ++Emmanuel Briot wrote @file{xml.el}, an XML parser for Emacs; and ++@file{ada-prj.el}, editing of Ada mode project files, as well as ++co-authoring @file{ada-mode.el} and @file{ada-xref.el}. ++ ++@item ++Kevin Broadey wrote @file{foldout.el}, providing folding extensions to ++Emacs's outline modes. ++ ++@item ++David M.@: Brown wrote @file{array.el}, for editing arrays and other ++tabular data. ++ ++@item ++W@l{}odek Bzyl and Ryszard Kubiak wrote @file{ogonek.el}, a package for ++changing the encoding of Polish characters. ++ ++@item ++Bill Carpenter provided @file{feedmail.el}, a package for massaging ++outgoing mail messages and sending them through various popular mailers. ++ ++@item ++Per Cederqvist and Inge Wallin wrote @file{ewoc.el}, an Emacs widget for ++manipulating object collections. Per Cederqvist, Inge Wallin, and ++Thomas Bellman wrote @file{avl-tree.el}, for balanced binary trees. ++ ++@item ++Hans Chalupsky wrote @file{advice.el}, an overloading mechanism for ++Emacs Lisp functions; and @file{trace.el}, a tracing facility for Emacs ++Lisp. ++ ++@item ++Chris Chase, Carsten Dominik, and J.@: D.@: Smith wrote IDLWAVE mode, ++for editing IDL and WAVE CL. ++ ++@item ++Bob Chassell wrote @file{texnfo-upd.el}, @file{texinfo.el}, and ++@file{makeinfo.el}, modes and utilities for working with Texinfo files; ++and @file{page-ext.el}, commands for extended page handling. ++ ++@item ++Jihyun Cho wrote @file{hanja-util.el} and @file{hangul.el}, utilities ++for Korean Hanja. ++ ++@item ++Andrew Choi and Yamamoto Mitsuharu wrote the Carbon support, used ++prior to Emacs 23 for Mac OS. ++ ++@item ++Chong Yidong was the Emacs co-maintainer for Emacs 23. He made many ++improvements to the Emacs display engine; and, together with Kai ++Gro@ss{}johann and Alex Schroeder, wrote @file{longlines.el}, a minor ++mode for wrapping long lines. ++ ++@item ++James Clark wrote SGML mode, a mode for editing SGML documents; and ++nXML mode, a mode for editing XML documents. He also contributed to ++Emacs's dumping procedures. ++ ++@item ++Mike Clarkson wrote @file{edt.el}, an emulation of DEC's EDT editor. ++ ++@item ++Glynn Clements provided @file{gamegrid.el} and a couple of games that ++use it, Snake and Tetris. ++ ++@item ++Andrew Cohen wrote @file{spam-wash.el}, to decode and clean email before ++it is analysed for spam. ++ ++@item ++Georges Brun-Cottan and Stefan Monnier wrote @file{easy-mmode.el}, a ++package for easy definition of major and minor modes. ++ ++@item ++Andrew Csillag wrote M4 mode (@file{m4-mode.el}). ++ ++@item ++Doug Cutting and Jamie Zawinski wrote @file{disass.el}, a disassembler ++for compiled Emacs Lisp code. ++ ++@item ++Mathias Dahl wrote @file{image-dired.el}, a package for viewing image ++files as ``thumbnails.'' ++ ++@item ++Michael DeCorte wrote @file{emacs.csh}, a C-shell script that starts a ++new Emacs job, or restarts a paused Emacs if one exists. ++ ++@item ++Gary Delp wrote @file{mailpost.el}, an interface between RMAIL and the ++@file{/usr/uci/post} mailer. ++ ++@item ++Matthieu Devin wrote @file{delsel.el}, a package to make newly-typed ++text replace the current selection. ++ ++@item ++Eric Ding wrote @file{goto-addr.el}, ++ ++@item ++Jan Dj@"{a}rv added support for the GTK+ toolkit and X drag-and-drop. ++ ++@item ++Carsten Dominik wrote Ref@TeX{}, a package for setting up labels and ++cross-references in La@TeX{} documents; and co-wrote IDLWAVE mode ++(q.v.@:). He was the main author of Org mode, for maintaining notes, ++todo lists, and project planning. Thomas Baumann, Bastien Guerry, ++Tassilo Horn, Philip Jackson, Tokuya Kameshima, Eric Schulte, Andy ++Stewart, David O'Toole, John Wiegley, and Piotr Zielinski also wrote ++various Org mode components. ++ ++@item ++Scott Draves wrote @file{tq.el}, help functions for maintaining ++transaction queues between Emacs and its subprocesses. ++ ++@item ++Benjamin Drieu wrote @file{pong.el}, an implementation of the classical ++pong game. ++ ++@item ++Viktor Dukhovni wrote support for dumping under SunOS version 4. ++ ++@item ++John Eaton and Kurt Hornik wrote Octave mode. ++ ++@item ++Rolf Ebert co-wrote Ada mode. ++ ++@item ++Stephen Eglen wrote @file{mspools.el}, which tells you which Procmail ++folders have mail waiting in them; and @file{iswitchb.el}, a feature ++for incremental reading and completion of buffer names. ++ ++@item ++Torbj@"orn Einarsson wrote @file{f90.el}, a mode for Fortran 90 files. ++ ++@item ++Tsugutomo Enami co-wrote the support for international character sets. ++ ++@item ++David Engster wrote @file{mairix.el} and @file{nnmairix.el}, an ++interface to the Mairix indexing tool. ++ ++@item ++Hans Henrik Eriksen wrote @file{simula.el}, a mode for editing SIMULA 87 ++code. ++ ++@item ++Michael Ernst wrote @file{reposition.el}, a command for recentering a ++function's source code and preceding comment on the screen. ++ ++@item ++Ata Etemadi wrote @file{cdl.el}, functions for working with Common Data ++Language source code. ++ ++@item ++Frederick Farnbach implemented @file{morse.el}, which converts text to ++Morse code. ++ ++@item ++Oscar Figueiredo wrote EUDC, the Emacs Unified Directory Client, which ++is an interface to directory servers via LDAP, CCSO PH/QI, or BBDB; and ++@file{ldap.el}, the LDAP client interface. ++ ++@item ++Fred Fish wrote the support for dumping COFF executable files. ++ ++@item ++Karl Fogel wrote @file{bookmark.el}, which implements named ++placeholders; @file{mail-hist.el}, a history mechanism for outgoing ++mail messages; and @file{saveplace.el}, for preserving point's ++location in files between editing sessions. ++ ++@item ++Gary Foster wrote @file{crisp.el}, the emulation for CRiSP and Brief ++editors; and @file{scroll-all.el}, a mode for scrolling several buffers ++together. ++ ++@item ++Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin, ++@file{type-break.el}, which reminds you to take periodic breaks from ++typing, and @code{eldoc-mode}, a mode to show the defined parameters or ++the doc string for the Lisp function near point. ++ ++@item ++Shigeru Fukaya wrote a testsuite for the byte-compiler. ++ ++@item ++Keith Gabryelski wrote @file{hexl.el}, a mode for editing binary files. ++ ++@item ++Kevin Gallagher rewrote and enhanced the EDT emulation, and wrote ++@file{flow-ctrl.el}, a package for coping with unsuppressible XON/XOFF ++flow control. ++ ++@item ++Kevin Gallo added multiple-frame support for Windows NT and wrote ++@file{w32-win.el}, support functions for the MS-Windows window system. ++ ++@item ++Juan Le@'{o}n Lahoz Garc@'{i}a wrote @file{wdired.el}, a package for ++performing file operations by directly editing Dired buffers. ++ ++@item ++Howard Gayle wrote much of the C and Lisp code for display tables and ++case tables. He also wrote @file{rot13.el}, a command to display the ++plain-text form of a buffer encoded with the Caesar cipher; ++@file{vt100-led.el}, a package for controlling the LEDs on ++VT100-compatible terminals; and much of the support for ISO-8859 ++European character sets (which includes @file{iso-ascii.el}, ++@file{iso-insert.el}, @file{iso-swed.el}, ++@file{iso-syntax.el}, @file{iso-transl.el}, and @file{swedish.el}). ++ ++@item ++Stephen Gildea made the Emacs quick reference card, and made many ++contributions for @file{time-stamp.el}, a package for maintaining ++last-change time stamps in files. ++ ++@item ++Julien Gilles wrote @file{gnus-ml.el}, a mailing list minor mode for ++Gnus. ++ ++@item ++David Gillespie wrote the Common Lisp compatibility packages; ++@code{Calc}, an advanced calculator and mathematical tool, since ++maintained and developed by Jay Belanger; @file{complete.el}, a partial ++completion mechanism; and @file{edmacro.el}, a package for editing ++keyboard macros. ++ ++@item ++Bob Glickstein wrote @file{sregex.el}, a facility for writing regexps ++using a Lisp-like syntax. ++ ++@item ++Boris Goldowsky wrote @file{avoid.el}, a package to keep the mouse ++cursor out of the way of the text cursor; @file{shadowfile.el}, a ++package for keeping identical copies of files in more than one place; ++@file{format.el}, a package for reading and writing files in various ++formats; @file{enriched.el}, a package for saving text properties in ++files; @file{facemenu.el}, a package for specifying faces; and ++@file{descr-text.el}, describing text and character properties. ++ ++@item ++Michelangelo Grigni wrote @file{ffap.el} which visits a file, ++taking the file name from the buffer. ++ ++@item ++Odd Gripenstam wrote @file{dcl-mode.el} for editing DCL command files. ++ ++@item ++Michael Gschwind wrote @file{iso-cvt.el}, a package to convert between ++the ISO 8859-1 character set and the notations for non-@acronym{ASCII} ++characters used by @TeX{} and net tradition. ++ ++@item ++Bastien Guerry wrote @file{gnus-bookmark.el}, bookmark support for Gnus; ++as well as contributing to Org mode (q.v.@:). ++ ++@item ++Henry Guillaume wrote @file{find-file.el}, a package to visit files ++related to the currently visited file. ++ ++@item ++Doug Gwyn wrote the portable @code{alloca} implementation. ++ ++@item ++Ken'ichi Handa implemented most of the support for international ++character sets, and wrote most of the Emacs 23 font handling code. He ++also wrote @file{composite.el}, which provides a minor mode that ++composes characters automatically when they are displayed; ++@file{isearch-x.el}, a facility for searching non-@acronym{ASCII} ++text; and @file{ps-bdf.el}, a BDF font support for printing ++non-@acronym{ASCII} text on a PostScript printer. Together with Naoto ++Takahashi, he wrote @file{quail.el}, an input facility for typing ++non-@acronym{ASCII} text from an @acronym{ASCII} keyboard. ++ ++@item ++Jesper Harder wrote @file{yenc.el}, for decoding yenc encoded messages. ++ ++@item ++K. Shane Hartman wrote @file{chistory.el} and @file{echistory.el}, ++packages for browsing command history lists; @file{electric.el} and ++@file{helper.el}, which provide an alternative command loop and ++appropriate help facilities; @file{emacsbug.el}, a package for ++reporting Emacs bugs; @file{picture.el}, a mode for editing ++@acronym{ASCII} pictures; and @file{view.el}, a package for perusing ++files and buffers without editing them. ++ ++@item ++John Heidemann wrote @file{mouse-copy.el} and @file{mouse-drag.el}, ++which provide alternative mouse-based editing and scrolling features. ++ ++@item ++Jon K Hellan wrote @file{utf7.el}, support for mail-safe transformation ++format of Unicode. ++ ++@item ++Markus Heritsch co-wrote Ada mode. ++ ++@item ++Karl Heuer wrote the original blessmail script, implemented the ++@code{intangible} text property, and rearranged the structure of the ++@code{Lisp_Object} type to allow for more data bits. ++ ++@item ++Manabu Higashida ported Emacs to MS-DOS. ++ ++@item ++Anders Holst wrote @file{hippie-exp.el}, a versatile completion and ++expansion package. ++ ++@item ++Tassilo Horn wrote DocView mode, allowing viewing of PDF, PostScript and ++DVI documents. ++ ++@item ++Tom Houlder wrote @file{mantemp.el}, which generates manual C@t{++} ++template instantiations. ++ ++@item ++Joakim Hove wrote @file{html2text.el}, a html to plain text converter. ++ ++@item ++Denis Howe wrote @file{browse-url.el}, a package for invoking a WWW ++browser to display a URL. ++ ++@item ++Lars Magne Ingebrigtsen did a major redesign of the Gnus news-reader and ++wrote many of its parts. Several of these are now general components of ++Emacs: @file{dns.el} for Domain Name Service lookups; ++@file{format-spec.el} for formatting arbitrary format strings; ++@file{netrc.el} for parsing of @file{.netrc} files; and ++@file{time-date.el} for general date and time handling. Components of ++Gnus have also been written by: Nagy Andras, David Blacka, Scott Byer, ++Kevin Greiner, Kai Gro@ss{}johann, Joe Hildebrand, Paul Jarc, Sascha ++L@"{u}decke, David Moore, Jim Radford, Benjamin Rutt, Raymond Scholz, ++Thomas Steffen, Reiner Steib, Didier Verna, Ilja Weis, Katsumi Yamaoka, ++Teodor Zlatanov, and others (@pxref{Contributors,,,gnus, the Gnus Manual}). ++ ++@item ++Andrew Innes contributed extensively to the MS-Windows support. ++ ++@item ++Seiichiro Inoue improved Emacs's XIM support. ++ ++@item ++Philip Jackson wrote @file{find-cmd.el}, to build a @code{find} ++command-line. ++ ++@item ++Ulf Jasper wrote @file{icalendar.el}, a package for converting Emacs ++diary entries to and from the iCalendar format; ++@file{newsticker.el}, an RSS and Atom based Newsticker; and ++@file{bubbles.el}, a puzzle game. ++ ++@item ++Kyle Jones wrote @file{life.el}, a package to play Conway's ``life'' game. ++ ++@item ++Terry Jones wrote @file{shadow.el}, a package for finding potential ++load-path problems when some Lisp file ``shadows'' another. ++ ++@item ++Simon Josefsson wrote @file{dns-mode.el}, an editing mode for Domain ++Name System master files; @file{dig.el}, a Domain Name System interface; ++@file{flow-fill.el}, a package for interpreting RFC2646 formatted text ++in messages; @file{fringe.el}, a package for customizing the fringe; ++@file{imap.el}, an Emacs Lisp library for talking to IMAP servers; ++@file{password-cache.el}, a password reader; @file{nnimap.el}, the IMAP ++back-end for Gnus; @file{url-imap.el} for the URL library; ++@file{rfc2104.el}, a hashed message authentication facility; the Gnus ++S/MIME and Sieve components; and @file{tls.el} and @file{starttls.el} ++for the Transport Layer Security protocol. ++ ++@item ++Arne J@o{}rgensen wrote @file{latexenc.el}, a package to ++automatically guess the correct coding system in LaTeX files. ++ ++@item ++Alexandre Julliard wrote @file{vc-git.el}, support for the Git version ++control system. ++ ++@item ++Tomoji Kagatani implemented @file{smtpmail.el}, used for sending out ++mail with SMTP. ++ ++@item ++Ivan Kanis wrote @file{vc-hg.el}, support for the Mercurial version ++control system. ++ ++@item ++Henry Kautz wrote @file{bib-mode.el}, a mode for maintaining ++bibliography databases compatible with @code{refer} (the @code{troff} ++version) and @code{lookbib}, and @file{refbib.el}, a package to convert ++those databases to the format used by the LaTeX text formatting package. ++ ++@item ++Taichi Kawabata added support for Devanagari script and the Indian ++languages. ++ ++@item ++Taro Kawagishi implented the MD4 Message Digest Algorithm in Lisp; and ++wrote @file{ntlm.el} and @file{sasl-ntlm.el} for NT LanManager ++authentication support. ++ ++@item ++Howard Kaye wrote @file{sort.el}, commands to sort text in Emacs ++buffers. ++ ++@item ++Michael Kifer wrote @code{ediff}, an interactive interface to the ++@command{diff}, @command{patch}, and @command{merge} programs; and ++Viper, the newest emulation for VI. ++ ++@item ++Richard King wrote the first version of @file{userlock.el} and ++@file{filelock.c}, which provide simple support for multiple users ++editing the same file. He also wrote the initial version of ++@file{uniquify.el}, a facility to make buffer names unique by adding ++parts of the file's name to the buffer name. ++ ++@item ++Peter Kleiweg wrote @file{ps-mode.el}, a mode for editing PostScript ++files and running a PostScript interpreter interactively from within ++Emacs. ++ ++@item ++Shuhei Kobayashi wrote @file{hex-util.el}, for operating on hexadecimal ++strings; support for HMAC (Keyed-Hashing for Message Authentication); ++and a Lisp implementation of the SHA1 Secure Hash Algorithm. ++ ++@item ++Pavel Kobyakov wrote @file{flymake.el}, a minor mode for performing ++on-the-fly syntax checking. ++ ++@item ++Larry K.@: Kolodney wrote @file{cvtmail.c}, a program to convert the mail ++directories used by Gosling Emacs into RMAIL format. ++ ++@item ++David M.@: Koppelman wrote @file{hi-lock.el}, a minor mode for ++interactive automatic highlighting of parts of the buffer text. ++ ++@item ++Koseki Yoshinori wrote @file{iimage.el}, a minor mode for displaying ++inline images. ++ ++@item ++Robert Krawitz wrote the original @file{xmenu.c}, part of Emacs's pop-up ++menu support. ++ ++@item ++Sebastian Kremer wrote @code{dired-mode}, with contributions by Lawrence ++R.@: Dodd. He also wrote @file{ls-lisp.el}, a Lisp emulation of the ++@code{ls} command for platforms which don't have @code{ls} as a standard ++program. ++ ++@item ++Geoff Kuenning and Ken Stevens wrote @file{ispell.el}, a spell-checker ++interface. ++ ++@item ++David K@ringaccent{a}gedal wrote @file{tempo.el}, providing support for ++easy insertion of boilerplate text and other common constructions. ++ ++@item ++Daniel LaLiberte wrote @file{edebug.el}, a source-level debugger for ++Emacs Lisp; @file{cl-specs.el}, specifications to help @code{edebug} ++debug code written using David Gillespie's Common Lisp support; ++@file{cust-print.el}, a customizable package for printing lisp ++objects; and @file{isearch.el}, Emacs's incremental search minor mode. ++He also co-wrote @file{hideif.el} (q.v.@:). ++ ++@item ++Vinicius Jose Latorre wrote the Emacs printing facilities, as well as ++@code{ps-print} (with Jim Thompson, Jacques Duthen, and Kenichi Handa), ++a package for pretty-printing Emacs buffers to PostScript printers; ++@file{delim-col.el}, a package to arrange text into columns; ++@file{ebnf2ps.el}, a package that translates EBNF grammar to a syntactic ++chart that can be printed to a PostScript printer; and ++@file{whitespace.el}, a package that detects and cleans up excess ++whitespace in a file. The previous version of @file{whitespace.el}, ++used prior to Emacs 23, was written by Rajesh Vaidheeswarran. ++ ++@item ++Frederic Lepied wrote @file{expand.el}, which uses the abbrev ++mechanism for inserting programming constructs. ++ ++@item ++Peter Liljenberg wrote @file{elint.el}, a Lint-style code checker for ++Emacs Lisp programs. ++ ++@item ++Lars Lindberg wrote @file{msb.el}, which provides more flexible menus ++for buffer selection; co-wrote @file{imenu.el} (q.v.@:); and rewrote ++@file{dabbrev.el}, originally written by Don Morrison. ++ ++@item ++Anders Lindgren wrote @file{autorevert.el}, a package for automatically ++reverting files visited by Emacs that were changed on disk; ++@file{cwarn.el}, a package to highlight suspicious C and C@t{++} ++constructs; and @file{follow.el}, a minor mode to synchronize windows ++that show the same buffer. ++ ++@item ++Thomas Link wrote @file{filesets.el}, a package for handling sets of ++files. ++ ++@item ++Juri Linkov wrote @file{misearch.el}, extending isearch to multi-buffer ++searches. ++ ++@item ++K@'{a}roly L@"{o}rentey wrote the ``multi-terminal'' code, which ++allows Emacs to run on graphical and text-only terminals ++simultaneously. ++ ++@item ++Martin Lorentzon wrote @file{vc-annotate.el}, support for version ++control annotation. ++ ++@item ++Dave Love wrote much of the code dealing with Unicode support and ++Latin-N unification. He added support for many coding systems, ++including the various UTF-7 and UTF-16 coding systems. He also wrote ++@code{autoarg-mode}, a global minor mode whereby digit keys supply ++prefix arguments; @code{autoarg-kp-mode}, which redefines the keypad ++numeric keys to digit arguments; @file{autoconf.el}, a mode for editing ++Autoconf files; @file{cfengine.el}, a mode for editing Cfengine files; ++@file{elide-head.el}, a package for eliding boilerplate text from file ++headers; @file{hl-line.el}, a minor mode for highlighting the line in ++the current window on which point is; @file{cap-words.el}, a minor mode ++for motion in ``CapitalizedWordIdentifiers''; @file{latin1-disp.el}, a ++package that lets you display ISO 8859 characters on Latin-1 terminals ++by setting up appropriate display tables; @file{python.el}, a major mode ++for the Python programming language; @file{refill.el}, a mode for ++automatic paragraph refilling, akin to typical word processors; ++@file{smiley.el}, a facility for displaying smiley faces; ++@file{sym-comp.el}, a library for performing mode-dependent symbol ++completion; @file{benchmark.el} for timing code execution; and ++@file{tool-bar.el}, a mode to control the display of the Emacs tool bar. ++With Riccardo Murri he wrote @file{vc-bzr.el}, support for the Bazaar ++version control system. ++ ++@item ++Eric Ludlam wrote the Speedbar package. He also wrote ++@file{checkdoc.el}, for checking doc strings in Emacs Lisp programs; ++@file{dframe.el}, providing dedicatd frame support modes; and ++@file{ezimage.el}, a generalized way to place images over text. ++ ++@item ++Alan Mackenzie wrote the integrated AWK support in CC Mode, and ++maintained CC Mode from Emacs 22 onwards. ++ ++@item ++Christopher J.@: Madsen wrote @file{decipher.el}, a package for cracking ++simple substitution ciphers. ++ ++@item ++Neil M.@: Mager wrote @file{appt.el}, functions to notify users of their ++appointments. It finds appointments recorded in the diary files ++used by the @code{calendar} package. ++ ++@item ++Ken Manheimer wrote @file{allout.el}, a mode for manipulating and ++formatting outlines, and @file{icomplete.el}, which provides incremental ++completion feedback in the minibuffer. ++ ++@item ++Bill Mann wrote @file{perl-mode.el}, a mode for editing Perl code. ++ ++@item ++Brian Marick and Daniel LaLiberte wrote @file{hideif.el}, support for ++hiding selected code within C @code{#ifdef} clauses. ++ ++@item ++Simon Marshall wrote @file{regexp-opt.el}, which generates a regular ++expression from a list of strings; and the fast-lock and lazy-lock ++font-lock support modes. He also extended @file{comint.el} and ++@file{shell.el}, originally written by Olin Shivers. ++ ++@item ++Bengt Martensson, Dirk Herrmann, Marc Shapiro, Mike Newton, Aaron Larson, ++and Stefan Schoef, wrote @file{bibtex.el}, a mode for editing Bib@TeX{} ++bibliography files. ++ ++@item ++Charlie Martin wrote @file{autoinsert.el}, which provides automatic ++mode-sensitive insertion of text into new files. ++ ++@item ++Yukihiro Matsumoto and Nobuyoshi Nakada wrote Ruby-mode. ++ ++@item ++Thomas May wrote @file{blackbox.el}, a version of the traditional ++blackbox game. ++ ++@item ++Roland McGrath wrote @file{compile.el} (since updated by Daniel ++Pfeiffer), a package for running compilations in a buffer, and then ++visiting the locations reported in error messages; @file{etags.el}, a ++package for jumping to function definitions and searching or replacing ++in all the files mentioned in a @file{TAGS} file; @file{find-dired.el}, ++for using @code{dired} commands on output from the @code{find} program, ++with Sebastian Kremer; @file{grep.el} for running the @code{grep} ++command; @file{map-ynp.el}, a general purpose boolean question-asker; ++@file{autoload.el}, providing semi-automatic maintenance of autoload ++files. ++ ++@item ++Michael McNamara and Wilson Snyder wrote Verilog mode. ++ ++@item ++David Megginson wrote @file{derived.el}, which allows one to define new ++major modes by inheriting key bindings and commands from existing major ++modes. ++ ++@item ++Will Mengarini wrote @file{repeat.el}, a command to repeat the preceding ++command with its arguments. ++ ++@item ++Richard Mlynarik wrote @file{cl-indent.el}, a package for indenting ++Common Lisp code; @file{ebuff-menu.el}, an ``electric'' browser for ++buffer listings; @file{ehelp.el}, bindings for browsing help screens; ++@file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format, ++used in mail messages and news articles; @file{terminal.el}, a ++terminal emulator for Emacs subprocesses; and @file{yow.el}, an ++essential utility. ++ ++@item ++Gerd Moellmann was the Emacs maintainer from the beginning of Emacs 21 ++development until the release of 21.1. He wrote the new display ++engine used from Emacs 21 onwards, and the asynchronous timers ++facility. He also wrote @code{ebrowse}, the C@t{++} browser; ++@file{jit-lock.el}, the Just-In-Time font-lock support mode; ++@file{tooltip.el}, a package for displaying tooltips; ++@file{authors.el}, a package for maintaining the @file{AUTHORS} file; ++and @file{rx.el}, a regular expression constructor. ++ ++@item ++Stefan Monnier was the Emacs co-maintainer for Emacs 23. He added ++support for Arch and Subversion to VC, re-wrote much of the Emacs server ++to use the built-in networking primitives, and re-wrote the abbrev and ++minibuffer completion code for Emacs 23. He also wrote @code{PCL-CVS}, ++a directory-level front end to the CVS version control system; ++@file{reveal.el}, a minor mode for automatically revealing invisible ++text; @file{smerge-mode.el}, a minor mode for resolving @code{diff3} ++conflicts; @file{diff-mode.el}, a mode for viewing and editing context ++diffs; @file{css-mode.el} for Cascading Style Sheets; and ++@file{bibtex-style.el} for BibTeX Style files. ++ ++@item ++Morioka Tomohiko wrote several packages for MIME support in Gnus and ++elsewhere. ++ ++@item ++Takahashi Naoto co-wrote @file{quail.el} (q.v.@:), and wrote ++@file{robin.el}, another input method. ++ ++@item ++Sen Nagata wrote @file{crm.el}, a package for reading multiple strings ++with completion, and @file{rfc2368.el}, support for @code{mailto:} ++URLs. ++ ++@item ++Erik Naggum wrote the time-conversion functions. He also wrote ++@file{disp-table.el}, a package for dealing with display tables; ++@file{mailheader.el}, a package for parsing email headers; and ++@file{parse-time.el}, a package for parsing time strings. ++ ++@item ++Thomas Neumann and Eric Raymond wrote @file{make-mode.el}, ++a mode for editing makefiles. ++ ++@item ++Thien-Thi Nguyen and Dan Nicolaescu wrote @file{hideshow.el}, a minor ++mode for selectively displaying blocks of text. ++ ++@item ++Dan Nicolaescu added support for running Emacs as a daemon. He also ++wrote @file{romanian.el}, support for editing Romanian text; ++@file{iris-ansi.el}, support for running Emacs on SGI's @code{xwsh} ++and @code{winterm} terminal emulators; and @file{vc-dir.el}, displaying ++the status of version-controlled directories. ++ ++@item ++Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation. ++ ++@item ++Hrvoje Niksic wrote @file{savehist.el}, for saving the minibuffer ++history between Emacs sessions. ++ ++@item ++Jeff Norden wrote @file{kermit.el}, a package to help the Kermit ++dialup communications program run comfortably in an Emacs shell buffer. ++ ++@item ++Andrew Norman wrote @file{ange-ftp.el}, providing transparent FTP ++support. ++ ++@item ++Edward O'Connor wrote @file{json.el}, a file for parsing and ++generating JSON files. ++ ++@item ++Kentaro Ohkouchi created the Emacs icons used beginning with Emacs 23. ++ ++@item ++Alexandre Oliva wrote @file{gnus-mlspl.el}, a group params-based mail ++splitting mechanism. ++ ++@item ++Takaaki Ota wrote @file{table.el}, a package for creating and editing ++embedded text-based tables. ++ ++@item ++Pieter E.@: J.@: Pareit wrote @file{mixal-mode.el}, an editing mode for ++the MIX assembly language. ++ ++@item ++David Pearson wrote @file{quickurl.el}, a simple method of inserting a ++URL into the current buffer based on text at point; @file{5x5.el}, a ++game to fill all squares on the field. ++ ++@item ++Jeff Peck wrote @file{sun.el}, key bindings for sunterm keys. ++ ++@item ++Damon Anton Permezel wrote @file{hanoi.el}, an animated demonstration of ++the ``Towers of Hanoi'' puzzle. ++ ++@item ++William M.@: Perry wrote @file{mailcap.el} (with Lars Magne ++Ingebrigtsen), a MIME media types configuration facility; ++@file{mwheel.el}, a package for supporting mouse wheels; co-wrote (with ++Dave Love) @file{socks.el}, a Socks v5 client; and developed the URL ++package. ++ ++@item ++Per Persson wrote @file{gnus-vm.el}, the VM interface for Gnus. ++ ++@item ++Jens Petersen wrote @file{find-func.el}, which makes it easy to find ++the source code for an Emacs Lisp function or variable. ++ ++@item ++Daniel Pfeiffer wrote @file{conf-mode.el}, a mode for editing ++configuration files; @file{copyright.el}, a package for updating ++copyright notices in files; @file{executable.el}, a package for ++executing interpreter scripts; @file{sh-script.el}, a mode for editing ++shell scripts; @file{skeleton.el}, implementing a concise language for ++writing statement skeletons; and @file{two-column.el}, a minor mode ++for simultaneous two-column editing. ++ ++Daniel also rewrote @file{apropos.el} (originally written by Joe Wells), ++for finding commands, functions, and variables matching a regular ++expression; and, together with Jim Blandy, co-authored @file{wyse50.el}, ++support for Wyse 50 terminals. He also co-wrote @file{compile.el} ++(q.v.@:) and @file{ada-stmt.el}. ++ ++@item ++Richard L.@: Pieri wrote @file{pop3.el}, a Post Office Protocol (RFC ++1460) interface for Emacs. ++ ++@item ++Fred Pierresteguy and Paul Reilly made Emacs work with X Toolkit ++widgets. ++ ++@item ++Fran@,{c}ois Pinard, Greg McGary, and Bruno Haible wrote @file{po.el}, ++support for PO translation files. ++ ++@item ++Christian Plaunt wrote @file{soundex.el}, an implementation of the ++Soundex algorithm for comparing English words by their pronunciation. ++ ++@item ++David Ponce wrote @file{recentf.el}, a package that puts a menu of ++recently visited files in the Emacs menu bar; @file{ruler-mode.el}, a ++minor mode for displaying a ruler in the header line; and ++@file{tree-widget.el}, a package to display hierarchical data ++structures. ++ ++@item ++Francesco A.@: Potorti wrote @file{cmacexp.el}, providing a command which ++runs the C preprocessor on a region of a file and displays the results. ++He also expanded and redesigned the @code{etags} program. ++ ++@item ++Michael D.@: Prange and Steven A.@: Wood wrote @file{fortran.el}, a mode ++for editing Fortran code. ++ ++@item ++Ashwin Ram wrote @file{refer.el}, commands to look up references in ++bibliography files by keyword. ++ ++@item ++Eric S.@: Raymond wrote @file{vc.el}, an interface to the RCS and SCCS ++source code version control systems, with Paul Eggert; @file{gud.el}, ++a package for running source-level debuggers like GDB and SDB in ++Emacs; @file{asm-mode.el}, a mode for editing assembly language code; ++@file{AT386.el}, terminal support package for IBM's AT keyboards; ++@file{cookie1.el}, support for ``fortune-cookie'' programs like ++@file{yow.el} and @file{spook.el}; @file{finder.el}, a package for ++finding Emacs Lisp packages by keyword and topic; @file{keyswap.el}, ++code to swap the @key{BS} and @key{DEL} keys; @file{loadhist.el}, ++functions for loading and unloading Emacs features; ++@file{lisp-mnt.el}, functions for working with the special headers ++used in Emacs Lisp library files; and code to set and make use of the ++@code{load-history} lisp variable, which records the source file from ++which each lisp function loaded into Emacs came. ++ ++@item ++Edward M.@: Reingold wrote the extensive calendar and diary support, ++with contributions from Stewart Clamen (@file{cal-mayan.el}), Nachum ++Dershowitz (@file{cal-hebrew.el}), Paul Eggert (@file{cal-dst.el}), ++Steve Fisk (@file{cal-tex.el}), Michael Kifer (@file{cal-x.el}), Lara ++Rios (@file{cal-menu.el}), and Denis B.@: Roegel (@file{solar.el}). ++Andy Oram contributed to its documentation. Reingold also contributed ++to @file{tex-mode.el}, a mode for editing @TeX{} files, as did William ++F.@: Schelter, Dick King, Stephen Gildea, Michael Prange, and Jacob ++Gore. ++ ++@item ++David Reitter wrote @file{mailclient.el} which can send mail via the ++system's designated mail client. ++ ++@item ++Alex Rezinsky wrote @file{which-func.el}, a mode that shows the name ++of the current function in the mode line. ++ ++@item ++Rob Riepel wrote @file{tpu-edt.el} and its associated files, providing ++an emulation of the VMS TPU text editor emulating the VMS EDT editor, ++and @file{vt-control.el}, providing some control functions for the DEC ++VT line of terminals. ++ ++@item ++Nick Roberts wrote @file{gdb-ui.el}, the graphical user interface to ++GDB; and @file{t-mouse.el}, mouse support in text terminals. ++ ++@item ++Danny Roozendaal implemented @file{handwrite.el}, which converts text ++into ``handwriting.'' ++ ++@item ++Markus Rost wrote @file{cus-test.el}, a testing framework for customize. ++ ++@item ++Guillermo J.@: Rozas wrote @file{scheme.el}, a mode for editing Scheme and ++DSSSL code, and @file{fakemail.c}, an interface to the System V mailer. ++ ++@item ++Ivar Rummelhoff wrote @file{winner.el}, which records recent window ++configurations so you can move back to them. ++ ++@item ++Jason Rumney ported the Emacs 21 display engine to MS-Windows, and has ++contributed extensively to the MS-Windows port of Emacs. ++ ++@item ++Wolfgang Rupprecht wrote Emacs 19's floating-point support (including ++@file{float-sup.el} and @file{floatfns.c}), and @file{sup-mouse.el}, ++support for the Supdup mouse on lisp machines. ++ ++@item ++Kevin Ryde wrote @file{info-xref.el}, a library for checking ++references in Info files. ++ ++@item ++James B.@: Salem and Brewster Kahle wrote @file{completion.el}, providing ++dynamic word completion. ++ ++@item ++Masahiko Sato wrote @file{vip.el}, an emulation of the VI editor. ++ ++@item ++Holger Schauer wrote @file{fortune.el}, a package for using fortune in ++message signatures. ++ ++@item ++William Schelter wrote @file{telnet.el}, support for @code{telnet} ++sessions within Emacs. ++ ++@item ++Ralph Schleicher wrote @file{battery.el}, a package for displaying ++laptop computer battery status, and @file{info-look.el}, a package for ++looking up Info documentation for symbols in the buffer. ++ ++@item ++Michael Schmidt and Tom Perrine wrote @file{modula2.el}, a mode for ++editing Modula-2 code, based on work by Mick Jordan and Peter Robinson. ++ ++@item ++Ronald S.@: Schnell wrote @file{dunnet.el}, a text adventure game. ++ ++@item ++Philippe Schnoebelen wrote @file{gomoku.el}, a Go Moku game played ++against Emacs; and @file{mpuz.el}, a multiplication puzzle. ++ ++@item ++Rainer Schoepf contributed to Alpha and OSF1 support. ++ ++@item ++Jan Schormann wrote @file{solitaire.el}, an implementation of the ++Solitaire game. ++ ++@item ++Alex Schroeder wrote @file{ansi-color.el}, a package for translating ++ANSI color escape sequences to Emacs faces; @file{sql.el}, a package ++for interactively running an SQL interpreter in an Emacs buffer; ++@file{cus-theme.el}, an interface for custom themes; @file{master.el}, a ++package for making a buffer @samp{master} over another; and ++@file{spam-stat.el}, for statistical detection of junk email. He also ++wrote parts of the IRC client ERC (q.v.@:). ++ ++@item ++Randal Schwartz wrote @file{pp.el}, a pretty-printer for lisp objects. ++ ++@item ++Oliver Seidel wrote @file{todo-mode.el}, a package for maintaining ++@file{TODO} list files. ++ ++@item ++Manuel Serrano wrote the Flyspell package, which does spell checking ++as you type. ++ ++@item ++Hovav Shacham wrote @file{windmove.el}, a set of commands for selecting ++windows based on their geometrical position on the frame. ++ ++@item ++Stanislav Shalunov wrote @file{uce.el}, for responding to unsolicited ++commercial email. ++ ++@item ++Richard Sharman wrote @file{hilit-chg.el}, which uses colors to show ++recent editing changes. ++ ++@item ++Olin Shivers wrote @file{comint.el}, a library for modes running ++interactive command-line-oriented subprocesses, and @file{shell.el}, for ++running inferior shells (both since extended by Simon Marshall); ++@file{cmuscheme.el}, for running inferior Scheme processes; ++@file{inf-lisp.el}, for running inferior Lisp process. ++ ++@item ++Espen Skoglund wrote @file{pascal.el}, a mode for editing Pascal code. ++ ++@item ++Rick Sladkey wrote @file{backquote.el}, a lisp macro for creating ++mostly-constant data. ++ ++@item ++Lynn Slater wrote @file{help-macro.el}, a macro for writing interactive ++help for key bindings. ++ ++@item ++Chris Smith wrote @file{icon.el}, a mode for editing Icon code. ++ ++@item ++David Smith wrote @file{ielm.el}, a mode for interacting with the Emacs ++Lisp interpreter as a subprocess. ++ ++@item ++Paul D.@: Smith wrote @file{snmp-mode.el}. ++ ++@item ++William Sommerfeld wrote @file{scribe.el}, a mode for editing Scribe ++files, and @file{server.el}, a package allowing programs to send files ++to an extant Emacs job to be edited. ++ ++@item ++Andre Spiegel made many contributions to the Emacs Version Control ++package, and in particular made it support multiple back ends. ++ ++@item ++Michael Staats wrote @file{pc-select.el}, which rebinds keys for ++selecting regions to follow many other systems. ++ ++@item ++Richard Stallman invented Emacs. He is the original author of GNU ++Emacs, and has been Emacs maintainer over several non-contiguous ++periods. In addition to much of the ``core'' Emacs code, he has ++written @file{easymenu.el}, a facility for defining Emacs menus; ++@file{image-mode.el}, support for visiting image files; ++@file{menu-bar.el}, the Emacs menu bar support code; ++@file{paren.el}, a package to make matching parentheses stand out in ++color; and also co-authored portions of CC mode. ++ ++@item ++Sam Steingold wrote @file{gulp.el}, a facility for asking package ++maintainers for updated versions of their packages via e-mail, and ++@file{midnight.el}, a package for running a command every midnight. ++ ++@item ++Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for ++browsing indices made from buffer contents. ++ ++@item ++Peter Stephenson wrote @file{vcursor.el}, which implements a ``virtual ++cursor'' that you can move with the keyboard and use for copying text. ++ ++@item ++Ken Stevens wrote the initial version of @file{ispell.el} and maintains ++that package since Ispell 3.1 release. ++ ++@item ++Kim F.@: Storm made many improvements to the Emacs display engine, ++process support, and networking support. He also wrote ++@file{bindat.el}, a package for encoding and decoding binary data; ++CUA mode, which allows Emacs to emulate the standard CUA key ++bindings; @file{ido.el}, a package for selecting buffers and files ++quickly; @file{keypad.el} for simplified keypad bindings; and ++@file{kmacro.el}, the keyboard macro facility. ++ ++@item ++Martin Stjernholm co-authored CC Mode, a major editing mode for C, ++C@t{++}, Objective-C, Java, Pike, CORBA IDL, and AWK code. ++ ++@item ++Steve Strassman did not write @file{spook.el}, and even if he did, he ++really didn't mean for you to use it in an anarchistic way. ++ ++@item ++Olaf Sylvester wrote @file{bs.el}, a package for manipulating Emacs ++buffers. ++ ++@item ++Tibor @v{S}imko and Milan Zamazal wrote @file{slovak.el}, support for ++editing text in Slovak language. ++ ++@item ++Luc Teirlinck wrote @file{help-at-pt.el}, providing local help through ++the keyboard. ++ ++@item ++Jean-Philippe Theberge wrote @file{thumbs.el}, a package for viewing ++image files as ``thumbnails.'' ++ ++@item ++Spencer Thomas wrote the original @file{dabbrev.el}, providing a command ++which completes the partial word before point, based on other nearby ++words for which it is a prefix. He also wrote the original dumping ++support. ++ ++@item ++Toru Tomabechi contributed to Tibetan support. ++ ++@item ++Markus Triska wrote @file{linum.el}, a minor mode that displays line ++numbers in the left margin. ++ ++@item ++Tom Tromey and Chris Lindblad wrote @file{tcl.el}, a mode for editing ++Tcl/Tk source files and running a Tcl interpreter as an Emacs ++subprocess. ++ ++@item ++Tom Tromey wrote @file{bug-reference.el}, providing clickable links to ++bug reports. ++ ++@item ++Eli Tziperman wrote @file{rmail-spam-filter.el}, a spam filter for RMAIL. ++ ++@item ++Daiki Ueno wrote @file{starttls.el}, support for Transport Layer ++Security protocol; @file{sasl-cram.el} and @file{sasl-digest.el} (with ++Kenichi Okada), and @file{sasl.el}, support for Simple Authentication ++and Security Layer (SASL); and the EasyPG (and its predecessor PGG) ++package, for GnuPG and PGP support. ++ ++@item ++Masanobu Umeda wrote GNUS, a feature-rich reader for Usenet news that ++was the ancestor of the current Gnus package. He also wrote ++@file{prolog.el}, a mode for editing Prolog code; @file{rmailsort.el}, a ++package for sorting messages in RMAIL folders; @file{metamail.el}, an ++interface to the Metamail program; @file{gnus-kill.el}, the Kill File ++mode for Gnus; @file{gnus-mh.el}, an mh-e interface for Gnus; ++@file{gnus-msg.el}, a mail and post interface for Gnus; and ++@file{timezone.el}, providing functions for dealing with time zones. ++ ++@item ++Neil W.@: Van Dyke wrote @file{webjump.el}, a ``hot links'' package. ++ ++@item ++Didier Verna wrote @file{rect.el}, a package of functions for ++operations on rectangle regions of text. He also contributed to Gnus ++(q.v.@:). ++ ++@item ++Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code. ++ ++@item ++Geoffrey Voelker wrote the Windows NT support. He also wrote ++@file{dos-w32.el}, functions shared by the MS-DOS and MS-Windows ports ++of Emacs, and @file{w32-fns.el}, MS-Windows specific support functions. ++ ++@item ++Johan Vromans wrote @file{forms.el} and its associated files, a mode for ++filling in forms. He also wrote @file{iso-acc.el}, a minor mode ++providing electric accent keys. ++ ++@item ++Colin Walters wrote Ibuffer, an enhanced buffer menu. ++ ++@item ++Barry Warsaw wrote @file{assoc.el}, a set of utility functions for ++working with association lists; @file{cc-mode.el}, a mode for editing ++C, C@t{++}, and Java code, based on earlier work by Dave Detlefs, ++Stewart Clamen, and Richard Stallman; @file{elp.el}, a profiler ++for Emacs Lisp programs; @file{man.el}, a mode for reading UNIX manual ++pages; @file{regi.el}, providing an AWK-like functionality for use in ++lisp programs; @file{reporter.el}, providing customizable bug ++reporting for lisp packages; and @file{supercite.el}, a minor mode for ++quoting sections of mail messages and news articles. ++ ++@item ++Christoph Wedler wrote @file{antlr-mode.el}, a major mode for ANTLR ++grammar files. ++ ++@item ++Morten Welinder helped port Emacs to MS-DOS, and introduced face ++support into the MS-DOS port of Emacs. He also wrote ++@file{desktop.el}, facilities for saving some of Emacs's state between ++sessions; @file{timer.el}, the Emacs facility to run commands at a ++given time or frequency, or when Emacs is idle, and its C-level ++support code; @file{pc-win.el}, the MS-DOS ``window-system'' support; ++@file{internal.el}, an ``internal terminal'' emulator for the MS-DOS ++port of Emacs; @file{arc-mode.el}, the mode for editing compressed ++archives; @file{s-region.el}, commands for setting the region using ++the shift key and motion commands; and @file{dos-fns.el}, functions ++for use under MS-DOS. ++ ++@item ++Joe Wells wrote the original version of @file{apropos.el} (q.v.@:); ++@file{resume.el}, support for processing command-line arguments after ++resuming a suspended Emacs job; and @file{mail-extr.el}, a package for ++extracting names and addresses from mail headers, with contributions ++from Jamie Zawinski. ++ ++@item ++Rodney Whitby and Reto Zimmermann wrote @file{vhdl-mode.el}, a major ++mode for editing VHDL source code. ++ ++@item ++John Wiegley wrote @file{align.el}, a set of commands for aligning text ++according to regular-expression based rules; @file{isearchb.el} for fast ++buffer switching; @file{timeclock.el}, a package for keeping track of ++time spent on projects; the Baha'i calendar support; ++@file{pcomplete.el}, a programmable completion facility; ++@file{remember.el}, a mode for jotting down things to remember; ++@file{eudcb-mab.el}, an address book backend for the Emacs Unified ++Directory Client; and @code{eshell}, a command shell implemented ++entirely in Emacs Lisp. He also contributed to Org mode (q.v.@:). ++ ++@item ++Ed Wilkinson wrote @file{b2m.c}, a program to convert mail files from ++RMAIL format to Unix @code{mbox} format. ++ ++@item ++Mike Williams wrote @file{mouse-sel.el}, providing enhanced mouse ++selection; and @file{thingatpt.el}, a library of functions for finding ++the ``thing'' (word, line, s-expression) containing point. ++ ++@item ++Roland Winkler wrote @file{proced.el}, a system process editor. ++ ++@item ++Bill Wohler wrote MH-E, the Emacs interface to the MH mail system; ++making use of earlier work by James R.@: Larus. Satyaki Das, Peter S.@: ++Galbraith, Stephen Gildea, and Jeffrey C.@: Honig also wrote various ++MH-E components. ++ ++@item ++Dale R.@: Worley wrote @file{emerge.el}, a package for interactively ++merging two versions of a file. ++ ++@item ++Francis J.@: Wright wrote @file{woman.el}, a package for browsing ++manual pages without the @code{man} command. ++ ++@item ++Tom Wurgler wrote @file{emacs-lock.el}, which makes it harder ++to exit with valuable buffers unsaved. ++ ++@item ++Masatake Yamato wrote @file{ld-script.el}, an editing mode for GNU ++linker scripts, and contributed subword handling in CC mode. ++ ++@item ++Jonathan Yavner wrote @file{testcover.el}, a package for keeping track ++of the testing status of Emacs Lisp code; @file{unsafep.el} to determine ++if a Lisp form is safe; and the SES spreadsheet package. ++ ++@item ++Ryan Yeske wrote @file{rcirc.el} a simple Internet Relay Chat client. ++ ++@item ++Ilya Zakharevich and Bob Olson wrote @file{cperl-mode.el}, a major ++mode for editing Perl code. Ilya Zakharevich also wrote ++@file{tmm.el}, a mode for accessing the Emacs menu bar on a text-mode ++terminal. ++ ++@item ++Milan Zamazal wrote @file{czech.el}, support for editing Czech text; ++@file{glasses.el}, a package for easier reading of source code that ++uses illegible identifier names; and @file{tildify.el}, commands for ++adding hard spaces to text, @TeX{}, and SGML/HTML files. ++ ++@item ++Victor Zandy wrote @file{zone.el}, a package for people who like to ++zone out in front of Emacs. ++ ++@item ++Eli Zaretskii made many standard Emacs features work on MS-DOS and ++Microsoft Windows. He also wrote @file{tty-colors.el}, which ++implements transparent mapping of X colors to tty colors; and ++@file{rxvt.el}. ++ ++@item ++Jamie Zawinski wrote much of the support for faces and X selections. ++With Hallvard Furuseth, he wrote the optimizing byte compiler used ++from Emacs 19 onwards. He also wrote @file{mailabbrev.el}, a package ++that provides automatic expansion of mail aliases, and ++@file{tar-mode.el}, which provides simple viewing and editing commands ++for tar files. ++ ++@item ++Andrew Zhilin created the Emacs 22 icons. ++ ++@item ++Shenghuo Zhu wrote @file{binhex.el}, a package for reading and writing ++binhex files; @file{mm-partial.el}, message/partial support for MIME ++messages; @file{rfc1843.el}, an HZ decoding package; ++@file{uudecode.el}, an Emacs Lisp decoder for uuencoded data; and ++@file{webmail.el}, an interface to Web mail. He also wrote several ++other Gnus components. ++ ++@item ++Ian T.@: Zimmerman wrote @file{gametree.el}. ++ ++@item ++Reto Zimmermann wrote @file{vera-mode.el}. ++ ++@item ++Neal Ziring and Felix S.@: T.@: Wu wrote @file{vi.el}, an emulation of the ++VI text editor. ++ ++@item ++Detlev Zundel wrote @file{re-builder.el}, a package for building regexps ++with visual feedback. ++ ++@end itemize ++ ++@ignore ++ arch-tag: bb1d0fa4-0240-4992-b5d4-8602d1e3d4ba ++@end ignore +diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi +new file mode 100644 +index 0000000..ae9e723 +--- /dev/null ++++ b/doc/emacs/anti.texi +@@ -0,0 +1,141 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++ ++@node Antinews, Mac OS / GNUstep, X Resources, Top ++@appendix Emacs 22 Antinews ++@c Update the emacs.texi Antinews menu entry with the above version number. ++ ++ For those users who live backwards in time, here is information ++about downgrading to Emacs version 22.3. We hope you will enjoy the ++greater simplicity that results from the absence of many Emacs ++@value{EMACSVER} features. ++ ++@itemize @bullet ++ ++@item ++We have switched to a character representation specially designed for ++Emacs. Rather than forcing all the widely used scripts into artificial ++alignment, as Unicode does, Emacs treats them all equally, giving ++each one a place in the space of character codes. We have eliminated ++the confusing practice, in Emacs 23, whereby one character can belong ++to multiple character sets. Now each script has its own variant, and ++they all are different as far as Emacs is concerned. For example, ++there's a Latin-1 c-cedilla character, and there's a Latin-2 ++c-cedilla; searching a buffer for the Latin-1 variant only finds that ++variant, but not the others. ++ ++@item ++Emacs now uses its own special internal encoding for non-@acronym{ASCII} ++characters, known as @samp{emacs-mule}. This was imperative to ++support several different variants of the same character, each one ++belonging to its own script: @samp{emacs-mule} marks each character ++with its script, to better discern them from one another. ++ ++@item ++For simplicity, the functions @code{encode-coding-region} and ++@code{decode-coding-region} no longer accept an argument saying where ++to store the result of their conversions. The result always replaces ++the original, so there's no need to look for it elsewhere. ++ ++@item ++Emacs no longer performs font anti-aliasing. If your fonts look ugly, ++try choosing a larger font and increasing the screen resolution. ++Admittedly, this becomes difficult as you go further back in time, ++since available screen resolutions will decrease. ++ ++@item ++The Fontconfig font library is no longer supported. To specify a ++font, you must use an XLFD (X Logical Font Descriptor). The other ++ways of specifying fonts---so-called ``Fontconfig'' and ``GTK'' font ++names---are redundant, so they have been removed. ++ ++@item ++Transient Mark mode is now disabled by default. Furthermore, some ++commands that operate specifically on the region when it is active and ++Transient Mark mode is enabled (such as @code{fill-paragraph} ++@code{ispell-word}, and @code{indent-for-tab-command}), no longer do ++so. ++ ++@item ++Holding @key{shift} while typing a motion command no longer creates a ++temporarily active region, since that's inconsistent with how Emacs ++normally handles keybindings. The variable @code{shift-select-mode} ++has been deleted. You can, however, still create temporarily active ++regions by dragging the mouse. ++ ++@item ++The line motion commands, @kbd{C-n} and @kbd{C-p}, now move by logical ++text lines, not screen lines. Even if a long text line is continued ++over multiple screen lines, @kbd{C-n} and @kbd{C-p} treat it as a ++single line, because that's ultimately what it is. ++ ++@item ++Visual Line mode, which provides ``word wrap'' functionality, has been ++removed. You can still use Long Lines mode to gain an approximation ++of word wrapping, though this has some drawbacks---for instance, ++syntax highlighting often doesn't work well on wrapped lines. ++ ++@item ++@kbd{C-l} now runs @code{recenter} instead of ++@code{recenter-top-bottom}. This always sets the current line at the ++center of the window, instead of cycling through the center, top, and ++bottom of the window on successive invocations. This lets you type ++@kbd{C-l C-l C-l C-l} to be @emph{absolutely sure} that you have ++recentered the line. ++ ++@item ++The way Emacs generates possible minibuffer completions is now much ++simpler to understand. It matches alternatives to the text before ++point, ignoring the text after point; it also does not attempt to ++perform partial completion if the first completion attempt fails. ++ ++@item ++Typing @kbd{M-n} at the start of the minibuffer history list no longer ++attempts to generate guesses of possible minibuffer input. It instead ++does the straightforward thing, by issuing the message @samp{End of ++history; no default available}. ++ ++@item ++Individual buffers can no longer display faces specially. The text ++scaling commands @kbd{C-x C-+}, @kbd{C-x C--}, and @kbd{C-x C-0} have ++been removed, and so has the buffer face menu bound to ++@kbd{S-down-mouse-1}. ++ ++@item ++VC no longer supports fileset-based operations on distributed version ++control systems (DVCSs) such as Arch, Bazaar, Subversion, Mercurial, ++and Git. For instance, multi-file commits will be performed by ++committing one file at a time. As you go further back in time, we ++will remove DVCS support entirely, so you should migrate your projects ++to CVS. ++ ++@item ++Rmail now uses a special file format, Babyl format, specifically designed ++for storing and editing mail. When you visit a file in Rmail, or get new ++mail, Rmail converts it automatically to Babyl format. ++ ++@item ++Emacs can no longer display frames on X windows and text terminals ++(ttys) simultaneously. If you start Emacs as an X application, it ++can only create X frames; if you start Emacs on a tty, it can only use ++that tty. No more confusion about which type of frame ++@command{emacsclient} will use in any given Emacs session! ++ ++@item ++Emacs can no longer be started as a daemon. You can be sure that if ++you don't see Emacs, then it's not running. ++ ++@item ++Emacs has added support for many soon-to-be-non-obsolete platforms, ++including VMS, DECstation, SCO Unix, and systems lacking alloca. ++Support for Sun windows has been added. ++ ++@item ++To keep up with decreasing computer memory capacity and disk space, many ++other functions and files have been eliminated in Emacs 22.3. ++@end itemize ++ ++@ignore ++ arch-tag: 32932bd9-46f5-41b2-8a0e-fb0cc4caeb29 ++@end ignore +diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi +new file mode 100644 +index 0000000..94d7dfc +--- /dev/null ++++ b/doc/emacs/arevert-xtra.texi +@@ -0,0 +1,192 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@c This file is included either in emacs-xtra.texi (when producing the ++@c printed version) or in the main Emacs manual (for the on-line version). ++@node Autorevert ++@section Auto Reverting Non-File Buffers ++ ++Global Auto Revert Mode normally only reverts file buffers. There are ++two ways to auto-revert certain non-file buffers: enabling Auto Revert ++Mode in those buffers (using @kbd{M-x auto-revert-mode}); and setting ++@code{global-auto-revert-non-file-buffers} non-@code{nil}. The latter ++enables Auto Reverting for all types of buffers for which it is ++implemented (listed in the menu below). ++ ++Like file buffers, non-file buffers should normally not revert while ++you are working on them, or while they contain information that might ++get lost after reverting. Therefore, they do not revert if they are ++``modified''. This can get tricky, because deciding when a non-file ++buffer should be marked modified is usually more difficult than for ++file buffers. ++ ++Another tricky detail is that, for efficiency reasons, Auto Revert ++often does not try to detect all possible changes in the buffer, only ++changes that are ``major'' or easy to detect. Hence, enabling ++auto-reverting for a non-file buffer does not always guarantee that ++all information in the buffer is up-to-date, and does not necessarily ++make manual reverts useless. ++ ++At the other extreme, certain buffers automatically revert every ++@code{auto-revert-interval} seconds. (This currently only applies to ++the Buffer Menu.) In this case, Auto Revert does not print any ++messages while reverting, even when @code{auto-revert-verbose} is ++non-@code{nil}. ++ ++The details depend on the particular types of buffers and are ++explained in the corresponding sections. ++ ++@menu ++* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. ++* Auto Reverting Dired:: Auto Revert of Dired buffers. ++* Supporting additional buffers:: How to add more Auto Revert support. ++@end menu ++ ++@node Auto Reverting the Buffer Menu ++@subsection Auto Reverting the Buffer Menu ++ ++If auto-reverting of non-file buffers is enabled, the Buffer Menu ++automatically reverts every @code{auto-revert-interval} seconds, ++whether there is a need for it or not. (It would probably take longer ++to check whether there is a need than to actually revert.) ++ ++If the Buffer Menu inappropriately gets marked modified, just revert ++it manually using @kbd{g} and auto-reverting will resume. However, if ++you marked certain buffers to get deleted or to be displayed, you have ++to be careful, because reverting erases all marks. The fact that ++adding marks sets the buffer's modified flag prevents Auto Revert from ++automatically erasing the marks. ++ ++@node Auto Reverting Dired ++@subsection Auto Reverting Dired buffers ++ ++Auto-reverting Dired buffers currently works on GNU or Unix style ++operating systems. It may not work satisfactorily on some other ++systems. ++ ++Dired buffers only auto-revert when the file list of the buffer's main ++directory changes (e.g. when a new file is added). They do not ++auto-revert when information about a particular file changes ++(e.g. when the size changes) or when inserted subdirectories change. ++To be sure that @emph{all} listed information is up to date, you have ++to manually revert using @kbd{g}, @emph{even} if auto-reverting is ++enabled in the Dired buffer. Sometimes, you might get the impression ++that modifying or saving files listed in the main directory actually ++does cause auto-reverting. This is because making changes to a file, ++or saving it, very often causes changes in the directory itself; for ++instance, through backup files or auto-save files. However, this is ++not guaranteed. ++ ++If the Dired buffer is marked modified and there are no changes you ++want to protect, then most of the time you can make auto-reverting ++resume by manually reverting the buffer using @kbd{g}. There is one ++exception. If you flag or mark files, you can safely revert the ++buffer. This will not erase the flags or marks (unless the marked ++file has been deleted, of course). However, the buffer will stay ++modified, even after reverting, and auto-reverting will not resume. ++This is because, if you flag or mark files, you may be working on the ++buffer and you might not want the buffer to change without warning. ++If you want auto-reverting to resume in the presence of marks and ++flags, mark the buffer non-modified using @kbd{M-~}. However, adding, ++deleting or changing marks or flags will mark it modified again. ++ ++Remote Dired buffers are not auto-reverted (because it may be slow). ++Neither are Dired buffers for which you used shell wildcards or file ++arguments to list only some of the files. @samp{*Find*} and ++@samp{*Locate*} buffers do not auto-revert either. ++ ++@node Supporting additional buffers ++@subsection Adding Support for Auto-Reverting additional Buffers. ++ ++This section is intended for Elisp programmers who would like to add ++support for auto-reverting new types of buffers. ++ ++To support auto-reverting the buffer must first of all have a ++@code{revert-buffer-function}. @xref{Definition of ++revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. ++ ++In addition, it @emph{must} have a @code{buffer-stale-function}. ++ ++@defvar buffer-stale-function ++The value of this variable is a function to check whether a non-file ++buffer needs reverting. This should be a function with one optional ++argument @var{noconfirm}. The function should return non-@code{nil} ++if the buffer should be reverted. The buffer is current when this ++function is called. ++ ++While this function is mainly intended for use in auto-reverting, it ++could be used for other purposes as well. For instance, if ++auto-reverting is not enabled, it could be used to warn the user that ++the buffer needs reverting. The idea behind the @var{noconfirm} ++argument is that it should be @code{t} if the buffer is going to be ++reverted without asking the user and @code{nil} if the function is ++just going to be used to warn the user that the buffer is out of date. ++In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. ++If the function is only going to be used for auto-reverting, you can ++ignore the @var{noconfirm} argument. ++ ++If you just want to automatically auto-revert every ++@code{auto-revert-interval} seconds (like the Buffer Menu), use: ++ ++@example ++(set (make-local-variable 'buffer-stale-function) ++ #'(lambda (&optional noconfirm) 'fast)) ++@end example ++ ++@noindent ++in the buffer's mode function. ++ ++The special return value @samp{fast} tells the caller that the need ++for reverting was not checked, but that reverting the buffer is fast. ++It also tells Auto Revert not to print any revert messages, even if ++@code{auto-revert-verbose} is non-@code{nil}. This is important, as ++getting revert messages every @code{auto-revert-interval} seconds can ++be very annoying. The information provided by this return value could ++also be useful if the function is consulted for purposes other than ++auto-reverting. ++@end defvar ++ ++Once the buffer has a @code{revert-buffer-function} and a ++@code{buffer-stale-function}, several problems usually remain. ++ ++The buffer will only auto-revert if it is marked unmodified. Hence, ++you will have to make sure that various functions mark the buffer ++modified if and only if either the buffer contains information that ++might be lost by reverting, or there is reason to believe that the user ++might be inconvenienced by auto-reverting, because he is actively ++working on the buffer. The user can always override this by manually ++adjusting the modified status of the buffer. To support this, calling ++the @code{revert-buffer-function} on a buffer that is marked ++unmodified should always keep the buffer marked unmodified. ++ ++It is important to assure that point does not continuously jump around ++as a consequence of auto-reverting. Of course, moving point might be ++inevitable if the buffer radically changes. ++ ++You should make sure that the @code{revert-buffer-function} does not ++print messages that unnecessarily duplicate Auto Revert's own messages, ++displayed if @code{auto-revert-verbose} is @code{t}, and effectively ++override a @code{nil} value for @code{auto-revert-verbose}. Hence, ++adapting a mode for auto-reverting often involves getting rid of such ++messages. This is especially important for buffers that automatically ++revert every @code{auto-revert-interval} seconds. ++ ++If the new auto-reverting is part of Emacs, you should mention it ++in the documentation string of @code{global-auto-revert-non-file-buffers}. ++ ++@ifinfo ++Similarly, you should add a node to this chapter's menu. This node ++@end ifinfo ++@ifnotinfo ++Similarly, you should add a section to this chapter. This section ++@end ifnotinfo ++should at the very least make clear whether enabling auto-reverting ++for the buffer reliably assures that all information in the buffer is ++completely up to date (or will be after @code{auto-revert-interval} ++seconds). ++ ++@ignore ++ arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e ++@end ignore +diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi +new file mode 100644 +index 0000000..4973b4a +--- /dev/null ++++ b/doc/emacs/basic.texi +@@ -0,0 +1,724 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Basic, Minibuffer, Exiting, Top ++@chapter Basic Editing Commands ++ ++@kindex C-h t ++@findex help-with-tutorial ++ Here we explain the basics of how to enter text, make corrections, ++and save the text in a file. If this material is new to you, we ++suggest you first run the Emacs learn-by-doing tutorial, by typing ++@kbd{Control-h t} inside Emacs. (@code{help-with-tutorial}). ++ ++@menu ++ ++* Inserting Text:: Inserting text by simply typing it. ++* Moving Point:: Moving the cursor to the place where you want to ++ change something. ++* Erasing:: Deleting and killing text. ++* Basic Undo:: Undoing recent changes in the text. ++* Files: Basic Files. Visiting, creating, and saving files. ++* Help: Basic Help. Asking what a character does. ++* Blank Lines:: Making and deleting blank lines. ++* Continuation Lines:: How Emacs displays lines too wide for the screen. ++* Position Info:: What page, line, row, or column is point on? ++* Arguments:: Numeric arguments for repeating a command N times. ++* Repeating:: Repeating the previous command quickly. ++@end menu ++ ++@node Inserting Text ++@section Inserting Text ++ ++@cindex insertion ++@cindex graphic characters ++ You can insert an ordinary @dfn{graphic character} (e.g., @samp{a}, ++@samp{B}, @samp{3}, and @samp{=}) by typing the associated key. This ++adds the character to the buffer at point. Insertion moves point ++forward, so that point remains just after the inserted text. ++@xref{Point}. ++ ++@kindex RET ++@cindex newline ++ To end a line and start a new one, type @key{RET}. This key may be ++labeled @key{Return} or @key{Enter} on your keyboard, but we refer to ++it as @key{RET} in this manual. Pressing it inserts a newline ++character in the buffer. If point is at the end of the line, this ++creates a new blank line after it; if point is in the middle of a ++line, the line is split at that position. ++ ++ As we explain later in this manual, you can change the way Emacs ++handles text insertion by turning on @dfn{minor modes}. For instance, ++if you turn on a minor mode called @dfn{Auto Fill} mode, Emacs can ++split lines automatically when they become too long (@pxref{Filling}). ++If you turn on a minor mode called @dfn{Overwrite} mode, inserted ++characters replace (overwrite) existing text, instead of shoving it to ++the right. @xref{Minor Modes}. ++ ++@cindex quoting ++@kindex C-q ++@findex quoted-insert ++ Only graphic characters can be inserted by typing the associated ++key; other keys act as editing commands and do not insert themselves. ++For instance, @kbd{DEL} runs the command @code{delete-backward-char} ++by default (some modes bind it to a different command); it does not ++insert a literal @samp{DEL} character (@acronym{ASCII} character code ++127). ++ ++ To insert a non-graphic character, or a character that your keyboard ++does not support, first @dfn{quote} it by typing @kbd{C-q} ++(@code{quoted-insert}). There are two ways to use @kbd{C-q}: ++ ++@itemize @bullet ++@item ++@kbd{C-q} followed by any non-graphic character (even @kbd{C-g}) ++inserts that character. For instance, @kbd{C-q @key{DEL}} inserts a ++literal @samp{DEL} character. ++ ++@item ++@kbd{C-q} followed by a sequence of octal digits inserts the character ++with the specified octal character code. You can use any number of ++octal digits; any non-digit terminates the sequence. If the ++terminating character is @key{RET}, it serves only to terminate the ++sequence. Any other non-digit terminates the sequence and then acts ++as normal input---thus, @kbd{C-q 1 0 1 B} inserts @samp{AB}. ++ ++The use of octal sequences is disabled in ordinary non-binary ++Overwrite mode, to give you a convenient way to insert a digit instead ++of overwriting with it. ++@end itemize ++ ++@vindex read-quoted-char-radix ++@noindent ++To use decimal or hexadecimal instead of octal, set the variable ++@code{read-quoted-char-radix} to 10 or 16. If the radix is greater ++than 10, some letters starting with @kbd{a} serve as part of a ++character code, just like digits. ++ ++ A numeric argument tells @kbd{C-q} how many copies of the quoted ++character to insert (@pxref{Arguments}). ++ ++@findex ucs-insert ++@cindex Unicode ++ Instead of @kbd{C-q}, you can use @kbd{C-x 8 @key{RET}} ++(@code{ucs-insert}) to insert a character based on its Unicode name or ++code-point. This commands prompts for a character to insert, using ++the minibuffer; you can specify the character using either (i) the ++character's name in the Unicode standard, or (ii) the character's ++code-point in the Unicode standard. ++ ++@node Moving Point ++@section Changing the Location of Point ++ ++@cindex arrow keys ++@cindex moving point ++@cindex movement ++@cindex cursor motion ++@cindex moving the cursor ++ To do more than insert characters, you have to know how to move ++point (@pxref{Point}). The keyboard commands @kbd{C-f}, @kbd{C-b}, ++@kbd{C-n}, and @kbd{C-p} move point to the right, left, up and down ++respectively. These are equivalent to the commands @kbd{@key{right}}, ++@kbd{@key{left}}, @kbd{@key{down}}, and @kbd{@key{up}}, entered using ++the @dfn{arrow keys} present on many keyboards. Many Emacs users find ++that it is slower to use the arrow keys than the equivalent control ++keys. You can also click the left mouse button to move point to the ++position clicked. Emacs also provides a variety of additional ++keyboard commands that move point in more sophisticated ways. ++ ++@kindex C-a ++@kindex C-e ++@kindex C-f ++@kindex C-b ++@kindex C-n ++@kindex C-p ++@kindex M-> ++@kindex M-< ++@kindex M-r ++@kindex LEFT ++@kindex RIGHT ++@kindex UP ++@kindex DOWN ++@findex move-beginning-of-line ++@findex move-end-of-line ++@findex forward-char ++@findex backward-char ++@findex next-line ++@findex previous-line ++@findex beginning-of-buffer ++@findex end-of-buffer ++@findex goto-char ++@findex goto-line ++@findex move-to-window-line ++@table @kbd ++@item C-a ++@itemx @key{Home} ++Move to the beginning of the line (@code{move-beginning-of-line}). ++@item C-e ++@itemx @key{End} ++Move to the end of the line (@code{move-end-of-line}). ++@item C-f ++@itemx @key{right} ++Move forward one character (@code{forward-char}). ++@item C-b ++@itemx @key{left} ++Move backward one character (@code{backward-char}). ++@item M-f ++@itemx M-@key{right} ++@itemx C-@key{right} ++Move forward one word (@code{forward-word}). ++@item M-b ++@itemx M-@key{left} ++@itemx C-@key{left} ++Move backward one word (@code{backward-word}). ++@item C-n ++@itemx @key{down} ++Move down one screen line (@code{next-line}). This command attempts ++to keep the horizontal position unchanged, so if you start in the ++middle of one line, you move to the middle of the next. ++@item C-p ++@itemx @key{up} ++Move up one screen line (@code{previous-line}). This command ++preserves position within the line, like @kbd{C-n}. ++@item M-r ++Move point to left margin, vertically centered in the window ++(@code{move-to-window-line}). Text does not move on the screen. ++A numeric argument says which screen line to place point on, counting ++downward from the top of the window (zero means the top line). A ++negative argument counts lines up from the bottom (@minus{}1 means the ++bottom line). ++@item M-< ++Move to the top of the buffer (@code{beginning-of-buffer}). With ++numeric argument @var{n}, move to @var{n}/10 of the way from the top. ++@xref{Arguments}, for more information on numeric arguments.@refill ++@item M-> ++Move to the end of the buffer (@code{end-of-buffer}). ++@item C-v ++@itemx @key{PageDown} ++@itemx @key{next} ++Scroll the display one screen forward, and move point if necessary to ++put it on the screen (@code{scroll-up}). If your keyboard has a ++@key{PageDown} key (sometimes labelled @key{next}), it does the same ++thing as @key{C-v}. Scrolling commands are described further in ++@ref{Scrolling}. ++@item M-v ++@itemx @key{PageUp} ++@itemx @key{prior} ++Scroll one screen backward, and move point if necessary to put it on ++the screen (@code{scroll-down}). If your keyboard has a @key{PageUp} ++key (sometimes labelled @key{prior}), it does the same thing as ++@kbd{M-v}. ++@item M-x goto-char ++Read a number @var{n} and move point to buffer position @var{n}. ++Position 1 is the beginning of the buffer. ++@item M-g M-g ++@itemx M-g g ++Read a number @var{n} and move point to the beginning of line number ++@var{n} (@code{goto-line}). Line 1 is the beginning of the buffer. If ++point is on or just after a number in the buffer, that is the default ++for @var{n}. Just type @key{RET} in the minibuffer to use it. You can ++also specify @var{n} by giving @kbd{M-g M-g} a numeric prefix argument. ++@xref{Select Buffer}, for the behavior of @kbd{M-g M-g} when you give it ++a plain prefix argument. ++@item C-x C-n ++@findex set-goal-column ++@kindex C-x C-n ++Use the current column of point as the @dfn{semipermanent goal column} ++for @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). When a ++semipermanent goal column is in effect, those commands always try to ++move to this column, or as close as possible to it, after moving ++vertically. The goal column remains in effect until canceled. ++@item C-u C-x C-n ++Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} try to ++preserve the horizontal position, as usual. ++@end table ++ ++@vindex line-move-visual ++ When a line of text in the buffer is longer than the width of the ++window, Emacs usually displays it on two or more @dfn{screen lines}. ++For convenience, @kbd{C-n} and @kbd{C-p} move point by screen lines, ++as do the equivalent keys @kbd{@key{down}} and @kbd{@key{up}}. You ++can force these commands to move according to @dfn{logical lines} ++(i.e., according to the text lines in the buffer) by setting the ++variable @code{line-move-visual} to @code{nil}; if a logical line ++occupies multiple screen lines, the cursor then skips over the ++additional screen lines. Moving by logical lines was the default ++behavior prior to Emacs 23.1. For details, see @ref{Continuation ++Lines}. @xref{Variables}, for how to set variables such as ++@code{line-move-visual}. ++ ++ Unlike @kbd{C-n} and @kbd{C-p}, most of the Emacs commands that work ++on lines work on @emph{logical} lines. For instance, @kbd{C-a} ++(@code{move-beginning-of-line}) and @kbd{C-e} ++(@code{move-end-of-line}) respectively move to the beginning and end ++of the logical line. Whenever we encounter commands that work on ++screen lines, such as @kbd{C-n} and @kbd{C-p}, we will point these ++out. ++ ++@vindex track-eol ++ When @code{line-move-visual} is @code{nil}, you can also set the ++variable @code{track-eol} to a non-@code{nil} value. Then @kbd{C-n} ++and @kbd{C-p}, when starting at the end of the logical line, move to ++the end of the next logical line. Normally, @code{track-eol} is ++@code{nil}. ++ ++@vindex next-line-add-newlines ++ @kbd{C-n} normally stops at the end of the buffer when you use it on ++the last line of the buffer. However, if you set the variable ++@code{next-line-add-newlines} to a non-@code{nil} value, @kbd{C-n} on ++the last line of a buffer creates an additional line at the end and ++moves down into it. ++ ++@node Erasing ++@section Erasing Text ++ ++@table @kbd ++@item @key{DEL} ++@itemx @key{Backspace} ++Delete the character before point (@code{delete-backward-char}). ++@item C-d ++@itemx @key{Delete} ++Delete the character after point (@code{delete-char}). ++@item C-k ++Kill to the end of the line (@code{kill-line}). ++@item M-d ++Kill forward to the end of the next word (@code{kill-word}). ++@item M-@key{DEL} ++Kill back to the beginning of the previous word ++(@code{backward-kill-word}). ++@end table ++ ++ The key @kbd{@key{DEL}} (@code{delete-backward-char}) removes the ++character before point, moving the cursor and all the characters after ++it backwards. On most keyboards, @key{DEL} is labelled ++@key{Backspace}, but we refer to it as @key{DEL} in this manual. Do ++not confuse @key{DEL} with another key, labelled @key{Delete}, that ++exists on many keyboards; we will discuss @key{Delete} momentarily. ++ ++ Typing @key{DEL} when the cursor is at the beginning of a line ++deletes the preceding newline character, joining the line with the one ++before it. ++ ++ On some text-only terminals, Emacs may not recognize the @key{DEL} ++key properly. If @key{DEL} does not do the right thing (e.g., if it ++deletes characters forwards), see @ref{DEL Does Not Delete}. ++ ++@cindex killing characters and lines ++@cindex deleting characters and lines ++@cindex erasing characters and lines ++ The key @kbd{C-d} (@code{delete-char}) deletes the character after ++point, i.e., the character under the cursor. This shifts the rest of ++the text on the line to the left. If you type @kbd{C-d} at the end of ++a line, it joins that line with the following line. This command is ++also bound to the key labelled @key{Delete} on many keyboards. ++ ++ To erase a larger amount of text, use the @kbd{C-k} key, which ++erases (kills) a line at a time. If you type @kbd{C-k} at the ++beginning or middle of a line, it kills all the text up to the end of ++the line. If you type @kbd{C-k} at the end of a line, it joins that ++line with the following line. ++ ++ To learn more about killing text, see @ref{Killing}. ++ ++@node Basic Undo ++@section Undoing Changes ++ ++@table @kbd ++@item C-/ ++Undo one entry of the undo records---usually, one command worth ++(@code{undo}). ++@itemx C-x u ++@item C-_ ++The same. ++@end table ++ ++ Emacs records a list of changes made in the buffer text, so you can ++undo recent changes. This is done using the @code{undo} command, ++which is bound to @kbd{C-/} (as well as @kbd{C-x u} and @kbd{C-_}). ++Normally, this command undoes the last change, moving point back to ++where it was before the change. The undo command applies only to ++changes in the buffer; you can't use it to undo cursor motion. ++ ++ Although each editing command usually makes a separate entry in the ++undo records, very simple commands may be grouped together. ++Sometimes, an entry may cover just part of a complex command. ++ ++ If you repeat @kbd{C-/} (or its aliases), each repetition undoes ++another, earlier change, back to the limit of the undo information ++available. If all recorded changes have already been undone, the undo ++command displays an error message and does nothing. ++ ++ To learn more about the @code{undo} command, see @ref{Undo}. ++ ++@node Basic Files ++@section Files ++ ++ Text that you insert in an Emacs buffer lasts only as long as the ++Emacs session. To keep any text permanently, you must put it in a ++@dfn{file}. Files are named units of text which are stored by the ++operating system for you to retrieve later by name. To use the ++contents of a file in any way, including editing it with Emacs, you ++must specify the file name. ++ ++ Suppose there is a file named @file{test.emacs} in your home ++directory. To begin editing this file in Emacs, type ++ ++@example ++C-x C-f test.emacs @key{RET} ++@end example ++ ++@noindent ++Here the file name is given as an @dfn{argument} to the command @kbd{C-x ++C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to ++read the argument, and you type @key{RET} to terminate the argument ++(@pxref{Minibuffer}). ++ ++ Emacs obeys this command by @dfn{visiting} the file: it creates a ++buffer, copies the contents of the file into the buffer, and then ++displays the buffer for editing. If you alter the text, you can ++@dfn{save} the new text in the file by typing @kbd{C-x C-s} ++(@code{save-buffer}). This copies the altered buffer contents back ++into the file @file{test.emacs}, making them permanent. Until you ++save, the changed text exists only inside Emacs, and the file ++@file{test.emacs} is unaltered. ++ ++ To create a file, just visit it with @kbd{C-x C-f} as if it already ++existed. This creates an empty buffer, in which you can insert the ++text you want to put in the file. Emacs actually creates the file the ++first time you save this buffer with @kbd{C-x C-s}. ++ ++ To learn more about using files in Emacs, see @ref{Files}. ++ ++@node Basic Help ++@section Help ++ ++@cindex getting help with keys ++ If you forget what a key does, you can find out with the Help ++character, which is @kbd{C-h} (or @key{F1}, which is an alias for ++@kbd{C-h}). Type @kbd{C-h k}, followed by the key of interest; for ++example, @kbd{C-h k C-n} tells you what @kbd{C-n} does. @kbd{C-h} is ++a prefix key; @kbd{C-h k} is just one of its subcommands (the command ++@code{describe-key}). The other subcommands of @kbd{C-h} provide ++different kinds of help. Type @kbd{C-h} twice to get a description of ++all the help facilities. @xref{Help}. ++ ++@node Blank Lines ++@section Blank Lines ++ ++@cindex inserting blank lines ++@cindex deleting blank lines ++ Here are special commands and techniques for inserting and deleting ++blank lines. ++ ++@table @kbd ++@item C-o ++Insert a blank line after the cursor (@code{open-line}). ++@item C-x C-o ++Delete all but one of many consecutive blank lines ++(@code{delete-blank-lines}). ++@end table ++ ++@kindex C-o ++@kindex C-x C-o ++@cindex blank lines ++@findex open-line ++@findex delete-blank-lines ++ We have seen how @kbd{@key{RET}} (@code{newline}) starts a new line ++of text. However, it may be easier to see what you are doing if you ++first make a blank line and then insert the desired text into it. ++This is easy to do using the key @kbd{C-o} (@code{open-line}), which ++inserts a newline after point but leaves point in front of the ++newline. After @kbd{C-o}, type the text for the new line. ++ ++ You can make several blank lines by typing @kbd{C-o} several times, or ++by giving it a numeric argument specifying how many blank lines to make. ++@xref{Arguments}, for how. If you have a fill prefix, the @kbd{C-o} ++command inserts the fill prefix on the new line, if typed at the ++beginning of a line. @xref{Fill Prefix}. ++ ++ The easy way to get rid of extra blank lines is with the command ++@kbd{C-x C-o} (@code{delete-blank-lines}). If point lies within a run ++of several blank lines, @kbd{C-x C-o} deletes all but one of them. If ++point is on a single blank line, @kbd{C-x C-o} deletes it. If point ++is on a nonblank line, @kbd{C-x C-o} deletes all following blank ++lines, if any exists. ++ ++@node Continuation Lines ++@section Continuation Lines ++ ++@cindex continuation line ++@cindex wrapping ++@cindex line wrapping ++@cindex fringes, and continuation lines ++ Sometimes, a line of text in the buffer---a @dfn{logical line}---is ++too long to fit in the window, and Emacs displays it as two or more ++@dfn{screen lines}. This is called @dfn{line wrapping} or ++@dfn{continuation}, and the long logical line is called a ++@dfn{continued line}. On a graphical display, Emacs indicates line ++wrapping with small bent arrows in the left and right window fringes. ++On a text-only terminal, Emacs indicates line wrapping by displaying a ++@samp{\} character at the right margin. ++ ++ Most commands that act on lines act on logical lines, not screen ++lines. For instance, @kbd{C-k} kills a logical line. As described ++earlier, @kbd{C-n} (@code{next-line}) and @kbd{C-p} ++(@code{previous-line}) are special exceptions: they move point down ++and up, respectively, by one screen line (@pxref{Moving Point}). ++ ++@cindex truncation ++@cindex line truncation, and fringes ++ Emacs can optionally @dfn{truncate} long logical lines instead of ++continuing them. This means that every logical line occupies a single ++screen line; if it is longer than the width of the window, the rest of ++the line is not displayed. On a graphical display, a truncated line ++is indicated by a small straight arrow in the right fringe; on a ++text-only terminal, it is indicated by a @samp{$} character in the ++right margin. @xref{Line Truncation}. ++ ++ By default, continued lines are wrapped at the right window edge. ++Since the wrapping may occur in the middle of a word, continued lines ++can be difficult to read. The usual solution is to break your lines ++before they get too long, by inserting newlines. If you prefer, you ++can make Emacs insert a newline automatically when a line gets too ++long, by using Auto Fill mode. @xref{Filling}. ++ ++@cindex word wrap ++ Sometimes, you may need to edit files containing many long logical ++lines, and it may not be practical to break them all up by adding ++newlines. In that case, you can use Visual Line mode, which enables ++@dfn{word wrapping}: instead of wrapping long lines exactly at the ++right window edge, Emacs wraps them at the word boundaries (i.e., ++space or tab characters) nearest to the right window edge. Visual ++Line mode also redefines editing commands such as @code{C-a}, ++@code{C-n}, and @code{C-k} to operate on screen lines rather than ++logical lines. @xref{Visual Line Mode}. ++ ++@node Position Info ++@section Cursor Position Information ++ ++ Here are commands to get information about the size and position of ++parts of the buffer, and to count lines. ++ ++@table @kbd ++@item M-x what-page ++Display the page number of point, and the line number within that page. ++@item M-x what-line ++Display the line number of point in the whole buffer. ++@item M-x line-number-mode ++@itemx M-x column-number-mode ++Toggle automatic display of the current line number or column number. ++@xref{Optional Mode Line}. ++@item M-x count-lines-region ++Display the number of lines in the current region. Normally bound to ++@kbd{M-=}, except in a few specialist modes. @xref{Mark}, for ++information about the region. ++@item C-x = ++Display the character code of character after point, character position of ++point, and column of point (@code{what-cursor-position}). ++@item M-x hl-line-mode ++Enable or disable highlighting of the current line. @xref{Cursor ++Display}. ++@item M-x size-indication-mode ++Toggle automatic display of the size of the buffer. ++@xref{Optional Mode Line}. ++@end table ++ ++@findex what-page ++@findex what-line ++@cindex line number commands ++@cindex location of point ++@cindex cursor location ++@cindex point location ++ @kbd{M-x what-line} displays the current line number in the echo ++area. This command is usually redundant, because the current line ++number is shown in the mode line (@pxref{Mode Line}). However, if you ++narrow the buffer, the mode line shows the line number relative to ++the accessible portion (@pxref{Narrowing}). By contrast, ++@code{what-line} displays both the line number relative to the ++narrowed region and the line number relative to the whole buffer. ++ ++ @kbd{M-x what-page} counts pages from the beginning of the file, and ++counts lines within the page, showing both numbers in the echo area. ++@xref{Pages}. ++ ++@kindex M-= ++@findex count-lines-region ++ Use @kbd{M-x count-lines-region} (normally bound to @kbd{M-=}) to ++display the number of lines in the region (@pxref{Mark}). @xref{Pages}, ++for the command @kbd{C-x l} which counts the lines in the current page. ++ ++@kindex C-x = ++@findex what-cursor-position ++ The command @kbd{C-x =} (@code{what-cursor-position}) shows ++information about the current cursor position and the buffer contents ++at that position. It displays a line in the echo area that looks like ++this: ++ ++@smallexample ++Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 ++@end smallexample ++ ++ After @samp{Char:}, this shows the character in the buffer at point. ++The text inside the parenthesis shows the corresponding decimal, octal ++and hex character codes; for more information about how @kbd{C-x =} ++displays character information, see @ref{International Chars}. After ++@samp{point=} is the position of point as a character count (the first ++character in the buffer is position 1, the second character is ++position 2, and so on). The number after that is the total number of ++characters in the buffer, and the number in parenthesis expresses the ++position as a percentage of the total. After @samp{column=} is the ++horizontal position of point, in columns counting from the left edge ++of the window. ++ ++ If the buffer has been narrowed, making some of the text at the ++beginning and the end temporarily inaccessible, @kbd{C-x =} displays ++additional text describing the currently accessible range. For ++example, it might display this: ++ ++@smallexample ++Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0 ++@end smallexample ++ ++@noindent ++where the two extra numbers give the smallest and largest character ++position that point is allowed to assume. The characters between ++those two positions are the accessible ones. @xref{Narrowing}. ++ ++@node Arguments ++@section Numeric Arguments ++@cindex numeric arguments ++@cindex prefix arguments ++@cindex arguments to commands ++ ++ In the terminology of mathematics and computing, @dfn{argument} ++means ``data provided to a function or operation.'' You can give any ++Emacs command a @dfn{numeric argument} (also called a @dfn{prefix ++argument}). Some commands interpret the argument as a repetition ++count. For example, giving @kbd{C-f} an argument of ten causes it to ++move point forward by ten characters instead of one. With these ++commands, no argument is equivalent to an argument of one, and ++negative arguments cause them to move or act in the opposite ++direction. ++ ++@kindex M-1 ++@kindex M-@t{-} ++@findex digit-argument ++@findex negative-argument ++ The easiest way to specify a numeric argument is to type a digit ++and/or a minus sign while holding down the @key{META} key. For ++example, ++ ++@example ++M-5 C-n ++@end example ++ ++@noindent ++moves down five lines. The keys @kbd{M-1}, @kbd{M-2}, and so on, as ++well as @kbd{M--}, are bound to commands (@code{digit-argument} and ++@code{negative-argument}) that set up an argument for the next ++command. @kbd{Meta--} without digits normally means @minus{}1. ++ ++If you enter more than one digit, you need not hold down the ++@key{META} key for the second and subsequent digits. Thus, to move ++down fifty lines, type ++ ++@example ++M-5 0 C-n ++@end example ++ ++@noindent ++Note that this @emph{does not} insert five copies of @samp{0} and move ++down one line, as you might expect---the @samp{0} is treated as part ++of the prefix argument. ++ ++(What if you do want to insert five copies of @samp{0}? Type @kbd{M-5 ++C-u 0}. Here, @kbd{C-u} ``terminates'' the prefix argument, so that ++the next keystroke begins the command that you want to execute. Note ++that this meaning of @kbd{C-u} applies only to this case. For the ++usual role of @kbd{C-u}, see below.) ++ ++@kindex C-u ++@findex universal-argument ++ Instead of typing @kbd{M-1}, @kbd{M-2}, and so on, another way to ++specify a numeric argument is to type @kbd{C-u} ++(@code{universal-argument}) followed by some digits, or (for a ++negative argument) a minus sign followed by digits. A minus sign ++without digits normally means @minus{}1. ++ ++ @kbd{C-u} alone has the special meaning of ``four times'': it ++multiplies the argument for the next command by four. @kbd{C-u C-u} ++multiplies it by sixteen. Thus, @kbd{C-u C-u C-f} moves forward ++sixteen characters. Other useful combinations are @kbd{C-u C-n}, ++@kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u ++C-u C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four ++lines). ++ ++ You can use a numeric argument before a self-inserting character to ++insert multiple copies of it. This is straightforward when the ++character is not a digit; for example, @kbd{C-u 6 4 a} inserts 64 ++copies of the character @samp{a}. But this does not work for ++inserting digits; @kbd{C-u 6 4 1} specifies an argument of 641. You ++can separate the argument from the digit to insert with another ++@kbd{C-u}; for example, @kbd{C-u 6 4 C-u 1} does insert 64 copies of ++the character @samp{1}. ++ ++ Some commands care whether there is an argument, but ignore its ++value. For example, the command @kbd{M-q} (@code{fill-paragraph}) ++fills text; with an argument, it justifies the text as well. ++(@xref{Filling}, for more information on @kbd{M-q}.) For these ++commands, it is enough to the argument with a single @kbd{C-u}. ++ ++ Some commands use the value of the argument as a repeat count, but ++do something special when there is no argument. For example, the ++command @kbd{C-k} (@code{kill-line}) with argument @var{n} kills ++@var{n} lines, including their terminating newlines. But @kbd{C-k} ++with no argument is special: it kills the text up to the next newline, ++or, if point is right at the end of the line, it kills the newline ++itself. Thus, two @kbd{C-k} commands with no arguments can kill a ++nonblank line, just like @kbd{C-k} with an argument of one. ++(@xref{Killing}, for more information on @kbd{C-k}.) ++ ++ A few commands treat a plain @kbd{C-u} differently from an ordinary ++argument. A few others may treat an argument of just a minus sign ++differently from an argument of @minus{}1. These unusual cases are ++described when they come up; they exist to make an individual command ++more convenient, and they are documented in that command's ++documentation string. ++ ++ We use the term ``prefix argument'' as well as ``numeric argument,'' ++to emphasize that you type these argument before the command, and to ++distinguish them from minibuffer arguments that come after the ++command. ++ ++@node Repeating ++@section Repeating a Command ++@cindex repeating a command ++ ++ Many simple commands, such as those invoked with a single key or ++with @kbd{M-x @var{command-name} @key{RET}}, can be repeated by ++invoking them with a numeric argument that serves as a repeat count ++(@pxref{Arguments}). However, if the command you want to repeat ++prompts for input, or uses a numeric argument in another way, that ++method won't work. ++ ++@kindex C-x z ++@findex repeat ++ The command @kbd{C-x z} (@code{repeat}) provides another way to repeat ++an Emacs command many times. This command repeats the previous Emacs ++command, whatever that was. Repeating a command uses the same arguments ++that were used before; it does not read new arguments each time. ++ ++ To repeat the command more than once, type additional @kbd{z}'s: each ++@kbd{z} repeats the command one more time. Repetition ends when you ++type a character other than @kbd{z}, or press a mouse button. ++ ++ For example, suppose you type @kbd{C-u 2 0 C-d} to delete 20 ++characters. You can repeat that command (including its argument) three ++additional times, to delete a total of 80 characters, by typing @kbd{C-x ++z z z}. The first @kbd{C-x z} repeats the command once, and each ++subsequent @kbd{z} repeats it once again. ++ ++@ignore ++ arch-tag: cda8952a-c439-41c1-aecf-4bc0d6482956 ++@end ignore +diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi +new file mode 100644 +index 0000000..848d133 +--- /dev/null ++++ b/doc/emacs/buffers.texi +@@ -0,0 +1,678 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Buffers, Windows, Files, Top ++@chapter Using Multiple Buffers ++ ++@cindex buffers ++ The text you are editing in Emacs resides in an object called a ++@dfn{buffer}. Each time you visit a file, a buffer is created to hold the ++file's text. Each time you invoke Dired, a buffer is created to hold the ++directory listing. If you send a message with @kbd{C-x m}, a buffer named ++@samp{*mail*} is used to hold the text of the message. When you ask for a ++command's documentation, that appears in a buffer called @samp{*Help*}. ++ ++ Each buffer has a unique name, which can be of any length. When a ++buffer is displayed in a window, its name is shown in the mode line ++(@pxref{Mode Line}). The distinction between upper and lower case ++matters in buffer names. Most buffers are made by visiting files, and ++their names are derived from the files' names; however, you can also ++create an empty buffer with any name you want. A newly started Emacs ++has a buffer named @samp{*scratch*}, which is not associated with any ++file and can be used for evaluating Lisp expressions in Emacs ++(@pxref{Lisp Interaction}). ++ ++@cindex selected buffer ++@cindex current buffer ++ At any time, one and only one buffer is @dfn{current}. This is also ++called the @dfn{selected buffer}. We often say that a command ++operates on ``the buffer''; this really means that the command ++operates on the current buffer (most commands do). When there is only ++one Emacs window, the buffer displayed in that window is current. ++When there are multiple windows present, the buffer displayed in the ++@dfn{selected window} is current. @xref{Windows}. ++ ++ Each buffer records individually what file it is visiting (if any), ++whether it is modified, and what major mode and minor modes are in ++effect (@pxref{Major Modes}). Any Emacs variable can be made ++@dfn{local to} a particular buffer, meaning its value in that buffer ++can be different from the value in other buffers. @xref{Locals}. ++ ++@cindex buffer size, maximum ++ A buffer's size cannot be larger than some maximum, which is defined ++by the largest buffer position representable by the @dfn{Emacs integer} ++data type. This is because Emacs tracks buffer positions using that ++data type. For 32-bit machines, the largest buffer size is 256 ++megabytes. ++ ++@menu ++* Select Buffer:: Creating a new buffer or reselecting an old one. ++* List Buffers:: Getting a list of buffers that exist. ++* Misc Buffer:: Renaming; changing read-onlyness; copying text. ++* Kill Buffer:: Killing buffers you no longer need. ++* Several Buffers:: How to go through the list of all buffers ++ and operate variously on several of them. ++* Indirect Buffers:: An indirect buffer shares the text of another buffer. ++* Buffer Convenience:: Convenience and customization features for ++ buffer handling. ++@end menu ++ ++@node Select Buffer ++@section Creating and Selecting Buffers ++@cindex change buffers ++@cindex switch buffers ++ ++@table @kbd ++@item C-x b @var{buffer} @key{RET} ++Select or create a buffer named @var{buffer} (@code{switch-to-buffer}). ++@item C-x 4 b @var{buffer} @key{RET} ++Similar, but select @var{buffer} in another window ++(@code{switch-to-buffer-other-window}). ++@item C-x 5 b @var{buffer} @key{RET} ++Similar, but select @var{buffer} in a separate frame ++(@code{switch-to-buffer-other-frame}). ++@item C-x @key{LEFT} ++Select the previous buffer in the list of existing buffers. ++@item C-x @key{RIGHT} ++Select the next buffer in the list of existing buffers. ++@item C-u M-g M-g ++@itemx C-u M-g g ++Read a number @var{n} and move to line @var{n} in the most recently ++selected buffer other than the current buffer. ++@end table ++ ++@kindex C-x b ++@findex switch-to-buffer ++ To select the buffer named @var{bufname}, type @kbd{C-x b ++@var{bufname} @key{RET}}. This runs the command ++@code{switch-to-buffer} with argument @var{bufname}. While entering ++the buffer name, you can use the usual minibuffer completion and ++history commands (@pxref{Minibuffer}). An empty argument to @kbd{C-x ++b} specifies the buffer that was current most recently among those not ++now displayed in any window. ++ ++@cindex minibuffer confirmation ++@cindex confirming in the minibuffer ++ If you specify a buffer that does not exist, @kbd{C-x b} creates a ++new, empty buffer that is not visiting any file, and selects it for ++editing. First, however, Emacs might prompt you for confirmation, in ++case you entered the wrong buffer name. Emacs asks for confirmation ++only if the last key you typed, before submitting the minibuffer input ++with @key{RET}, was @key{TAB} (@code{minibuffer-complete}). This ++catches a common mistake, in which one types @key{RET} before ++realizing that @key{TAB} did not complete far enough to yield the ++desired buffer name (@pxref{Completion}). Emacs asks for confirmation ++by putting the message @samp{[Confirm]} in the minibuffer; type ++@key{RET} again to confirm and visit the buffer. ++ ++@vindex confirm-nonexistent-file-or-buffer ++ The variable @code{confirm-nonexistent-file-or-buffer} controls ++whether Emacs asks for confirmation before visiting a buffer that did ++not previously exist. The default value, @code{after-completion}, ++gives the behavior we have just described. If the value is ++@code{nil}, Emacs never asks for confirmation; for any other ++non-@code{nil} value, Emacs always asks for confirmation. This ++variable also affects the @code{find-file} command (@pxref{Visiting}). ++ ++ One reason to create a new buffer is to use it for making temporary ++notes. If you try to save it, Emacs asks for the file name to use. ++The variable @code{default-major-mode} determines the new buffer's ++major mode; the default value is Fundamental mode. @xref{Major ++Modes}. ++ ++@kindex C-x @key{LEFT} ++@kindex C-x @key{RIGHT} ++@findex next-buffer ++@findex previous-buffer ++ For conveniently switching between a few buffers, use the commands ++@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}. @kbd{C-x @key{RIGHT}} ++(@code{previous-buffer}) selects the previous buffer (following the order ++of most recent selection in the current frame), while @kbd{C-x @key{LEFT}} ++(@code{next-buffer}) moves through buffers in the reverse direction. ++ ++@kindex C-x 4 b ++@findex switch-to-buffer-other-window ++@vindex even-window-heights ++ To select a buffer in a window other than the current one, type ++@kbd{C-x 4 b} (@code{switch-to-buffer-other-window}). This prompts ++for a buffer name using the minibuffer, displays that buffer in ++another window, and selects that window. By default, if displaying ++the buffer causes two vertically adjacent windows to be displayed, the ++heights of those windows are evened out; to countermand that and ++preserve the window configuration, set the variable ++@code{even-window-heights} to @code{nil}. ++ ++@kindex C-x 5 b ++@findex switch-to-buffer-other-frame ++ Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame}) ++prompts for a buffer name, displays that buffer in another frame, and ++selects that frame. ++ ++ In addition, @kbd{C-x C-f}, and any other command for visiting a ++file, can also be used to switch to an existing file-visiting buffer. ++@xref{Visiting}. ++ ++@vindex display-buffer-reuse-frames ++ You can control how certain buffers are handled by these commands by ++customizing the variables @code{special-display-buffer-names}, ++@code{special-display-regexps}, @code{same-window-buffer-names}, and ++@code{same-window-regexps}. See @ref{Force Same Window}, and ++@ref{Special Buffer Frames}, for more about these variables. In ++addition, if the value of @code{display-buffer-reuse-frames} is ++non-@code{nil}, and the buffer you want to switch to is already ++displayed in some frame, Emacs will just raise that frame. ++ ++@findex goto-line ++ @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix ++argument, reads a number @var{n} using the minibuffer, selects the ++most recently selected buffer other than the current buffer in another ++window, and then moves point to the beginning of line number @var{n} ++in that buffer. This is mainly useful in a buffer that refers to line ++numbers in another buffer: if point is on or just after a number, ++@code{goto-line} uses that number as the default for @var{n}. Note ++that prefix arguments other than just @kbd{C-u} behave differently. ++@kbd{C-u 4 M-g M-g} goes to line 4 in the @emph{current} buffer, ++without reading a number from the minibuffer. (Remember that @kbd{M-g ++M-g} without prefix argument reads a number @var{n} and then moves to ++line number @var{n} in the current buffer. @xref{Moving Point}.) ++ ++ Emacs uses buffer names that start with a space for internal purposes. ++It treats these buffers specially in minor ways---for example, by ++default they do not record undo information. It is best to avoid using ++such buffer names yourself. ++ ++@node List Buffers ++@section Listing Existing Buffers ++ ++@table @kbd ++@item C-x C-b ++List the existing buffers (@code{list-buffers}). ++@end table ++ ++@cindex listing current buffers ++@kindex C-x C-b ++@findex list-buffers ++ To display a list of existing buffers, type @kbd{C-x C-b}. Each ++line in the list shows one buffer's name, major mode and visited file. ++The buffers are listed in the order that they were current; the ++buffers that were current most recently come first. ++ ++ @samp{.} in the first field of a line indicates that the buffer is ++current. @samp{%} indicates a read-only buffer. @samp{*} indicates ++that the buffer is ``modified.'' If several buffers are modified, it ++may be time to save some with @kbd{C-x s} (@pxref{Save Commands}). ++Here is an example of a buffer list: ++ ++@smallexample ++CRM Buffer Size Mode File ++. * .emacs 3294 Emacs-Lisp ~/.emacs ++ % *Help* 101 Help ++ search.c 86055 C ~/cvs/emacs/src/search.c ++ % src 20959 Dired by name ~/cvs/emacs/src/ ++ * *mail* 42 Mail ++ % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO ++ % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS ++ *scratch* 191 Lisp Interaction ++ * *Messages* 1554 Fundamental ++@end smallexample ++ ++@noindent ++The buffer @samp{*Help*} was made by a help request (@pxref{Help}); it ++is not visiting any file. The buffer @code{src} was made by Dired on ++the directory @file{~/cvs/emacs/src/}. You can list only buffers that ++are visiting files by giving the command a prefix argument, as in ++@kbd{C-u C-x C-b}. ++ ++ @code{list-buffers} omits buffers whose names begin with a space, ++unless they visit files: such buffers are used internally by Emacs. ++ ++@node Misc Buffer ++@section Miscellaneous Buffer Operations ++ ++@table @kbd ++@item C-x C-q ++Toggle read-only status of buffer (@code{toggle-read-only}). ++@item M-x rename-buffer @key{RET} @var{name} @key{RET} ++Change the name of the current buffer. ++@item M-x rename-uniquely ++Rename the current buffer by adding @samp{<@var{number}>} to the end. ++@item M-x view-buffer @key{RET} @var{buffer} @key{RET} ++Scroll through buffer @var{buffer}. ++@end table ++ ++@kindex C-x C-q ++@vindex buffer-read-only ++@cindex read-only buffer ++ A buffer can be @dfn{read-only}, which means that commands to change ++its contents are not allowed. The mode line indicates read-only ++buffers with @samp{%%} or @samp{%*} near the left margin. Read-only ++buffers are usually made by subsystems such as Dired and Rmail that ++have special commands to operate on the text; also by visiting a file ++whose access control says you cannot write it. ++ ++@findex toggle-read-only ++ If you wish to make changes in a read-only buffer, use the command ++@kbd{C-x C-q} (@code{toggle-read-only}). It makes a read-only buffer ++writable, and makes a writable buffer read-only. This ++works by setting the variable @code{buffer-read-only}, which has a local ++value in each buffer and makes the buffer read-only if its value is ++non-@code{nil}. If you have files under version control, you may find ++it convenient to bind @kbd{C-x C-q} to @code{vc-toggle-read-only} ++instead. This will guard you against an operation that will confuse ++most modern version-conmtrol systems. @xref{Version Control}. ++ ++@findex rename-buffer ++ @kbd{M-x rename-buffer} changes the name of the current buffer. You ++specify the new name as a minibuffer argument; there is no default. ++If you specify a name that is in use for some other buffer, an error ++happens and no renaming is done. ++ ++@findex rename-uniquely ++ @kbd{M-x rename-uniquely} renames the current buffer to a similar ++name with a numeric suffix added to make it both different and unique. ++This command does not need an argument. It is useful for creating ++multiple shell buffers: if you rename the @samp{*shell*} buffer, then ++do @kbd{M-x shell} again, it makes a new shell buffer named ++@samp{*shell*}; meanwhile, the old shell buffer continues to exist ++under its new name. This method is also good for mail buffers, ++compilation buffers, and most Emacs features that create special ++buffers with particular names. (With some of these features, such as ++@kbd{M-x compile}, @kbd{M-x grep} an @kbd{M-x info}, you need to ++switch to some other buffer before using the command, in order for it ++to make a different buffer.) ++ ++@findex view-buffer ++ @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc ++File Ops}) except that it examines an already existing Emacs buffer. ++View mode provides commands for scrolling through the buffer ++conveniently but not for changing it. When you exit View mode with ++@kbd{q}, that switches back to the buffer (and the position) which was ++previously displayed in the window. Alternatively, if you exit View ++mode with @kbd{e}, the buffer and the value of point that resulted from ++your perusal remain in effect. ++ ++ The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer} ++can be used to copy text from one buffer to another. @xref{Accumulating ++Text}. ++ ++@node Kill Buffer ++@section Killing Buffers ++ ++@cindex killing buffers ++ If you continue an Emacs session for a while, you may accumulate a ++large number of buffers. You may then find it convenient to @dfn{kill} ++the buffers you no longer need. On most operating systems, killing a ++buffer releases its space back to the operating system so that other ++programs can use it. Here are some commands for killing buffers: ++ ++@table @kbd ++@item C-x k @var{bufname} @key{RET} ++Kill buffer @var{bufname} (@code{kill-buffer}). ++@item M-x kill-some-buffers ++Offer to kill each buffer, one by one. ++@item M-x kill-matching-buffers ++Offer to kill all buffers matching a regular expression. ++@end table ++ ++@findex kill-buffer ++@kindex C-x k ++ @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you ++specify in the minibuffer. The default, used if you type just ++@key{RET} in the minibuffer, is to kill the current buffer. If you ++kill the current buffer, another buffer becomes current: one that was ++current in the recent past but is not displayed in any window now. If ++you ask to kill a file-visiting buffer that is modified, then you must ++confirm with @kbd{yes} before the buffer is killed. ++ ++@findex kill-some-buffers ++ The command @kbd{M-x kill-some-buffers} asks about each buffer, one ++by one. An answer of @kbd{y} means to kill the buffer, just like ++@code{kill-buffer}. This command ignores buffers whose names begin ++with a space, which are used internally by Emacs. ++ ++@findex kill-matching-buffers ++ The command @kbd{M-x kill-matching-buffers} prompts for a regular ++expression and kills all buffers whose names match that expression. ++@xref{Regexps}. Like @code{kill-some-buffers}, it asks for ++confirmation before each kill. This command normally ignores buffers ++whose names begin with a space, which are used internally by Emacs. ++To kill internal buffers as well, call @code{kill-matching-buffers} ++with a prefix argument. ++ ++ The buffer menu feature is also convenient for killing various ++buffers. @xref{Several Buffers}. ++ ++@vindex kill-buffer-hook ++ If you want to do something special every time a buffer is killed, you ++can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}). ++ ++@findex clean-buffer-list ++ If you run one Emacs session for a period of days, as many people do, ++it can fill up with buffers that you used several days ago. The command ++@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills ++all the unmodified buffers that you have not used for a long time. An ++ordinary buffer is killed if it has not been displayed for three days; ++however, you can specify certain buffers that should never be killed ++automatically, and others that should be killed if they have been unused ++for a mere hour. ++ ++@cindex Midnight mode ++@vindex midnight-mode ++@vindex midnight-hook ++ You can also have this buffer purging done for you, every day at ++midnight, by enabling Midnight mode. Midnight mode operates each day ++at midnight; at that time, it runs @code{clean-buffer-list}, or ++whichever functions you have placed in the normal hook ++@code{midnight-hook} (@pxref{Hooks}). To enable Midnight mode, use ++the Customization buffer to set the variable @code{midnight-mode} to ++@code{t}. @xref{Easy Customization}. ++ ++@node Several Buffers ++@section Operating on Several Buffers ++@cindex buffer menu ++ ++@table @kbd ++@item M-x buffer-menu ++Begin editing a buffer listing all Emacs buffers. ++@item M-x buffer-menu-other-window. ++Similar, but do it in another window. ++@end table ++ ++ The @dfn{buffer menu} opened by @kbd{C-x C-b} (@pxref{List Buffers}) ++does not merely list buffers. It also allows you to perform various ++operations on buffers, through an interface similar to Dired ++(@pxref{Dired}). You can save buffers, kill them (here called ++@dfn{deleting} them, for consistency with Dired), or display them. ++ ++@findex buffer-menu ++@findex buffer-menu-other-window ++ To use the buffer menu, type @kbd{C-x C-b} and switch to the window ++displaying the @samp{*Buffer List*} buffer. You can also type ++@kbd{M-x buffer-menu} to open the buffer menu in the selected window. ++Alternatively, the command @kbd{M-x buffer-menu-other-window} opens ++the buffer menu in another window, and selects that window. ++ ++ The buffer menu is a read-only buffer, and can be changed only ++through the special commands described in this section. The usual ++Emacs cursor motion commands can be used in this buffer. The ++following commands apply to the buffer described on the current line: ++ ++@table @kbd ++@item d ++Request to delete (kill) the buffer, then move down. The request ++shows as a @samp{D} on the line, before the buffer name. Requested ++deletions take place when you type the @kbd{x} command. ++@item C-d ++Like @kbd{d} but move up afterwards instead of down. ++@item s ++Request to save the buffer. The request shows as an @samp{S} on the ++line. Requested saves take place when you type the @kbd{x} command. ++You may request both saving and deletion for the same buffer. ++@item x ++Perform previously requested deletions and saves. ++@item u ++Remove any request made for the current line, and move down. ++@item @key{DEL} ++Move to previous line and remove any request made for that line. ++@end table ++ ++ The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove ++flags also move down (or up) one line. They accept a numeric argument ++as a repeat count. ++ ++ These commands operate immediately on the buffer listed on the current ++line: ++ ++@table @kbd ++@item ~ ++Mark the buffer ``unmodified.'' The command @kbd{~} does this ++immediately when you type it. ++@item % ++Toggle the buffer's read-only flag. The command @kbd{%} does ++this immediately when you type it. ++@item t ++Visit the buffer as a tags table. @xref{Select Tags Table}. ++@end table ++ ++ There are also commands to select another buffer or buffers: ++ ++@table @kbd ++@item q ++Quit the buffer menu---immediately display the most recent formerly ++visible buffer in its place. ++@item @key{RET} ++@itemx f ++Immediately select this line's buffer in place of the @samp{*Buffer ++List*} buffer. ++@item o ++Immediately select this line's buffer in another window as if by ++@kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible. ++@item C-o ++Immediately display this line's buffer in another window, but don't ++select the window. ++@item 1 ++Immediately select this line's buffer in a full-screen window. ++@item 2 ++Immediately set up two windows, with this line's buffer selected in ++one, and the previously current buffer (aside from the buffer ++@samp{*Buffer List*}) displayed in the other. ++@item b ++Bury the buffer listed on this line. ++@item m ++Mark this line's buffer to be displayed in another window if you exit ++with the @kbd{v} command. The request shows as a @samp{>} at the ++beginning of the line. (A single buffer may not have both a delete ++request and a display request.) ++@item v ++Immediately select this line's buffer, and also display in other windows ++any buffers previously marked with the @kbd{m} command. If you have not ++marked any buffers, this command is equivalent to @kbd{1}. ++@end table ++ ++ There is also a command that affects the entire buffer list: ++ ++@table @kbd ++@item T ++Delete, or reinsert, lines for non-file buffers. This command toggles ++the inclusion of such buffers in the buffer list. ++@end table ++ ++ What @code{buffer-menu} actually does is create and switch to a ++suitable buffer, and turn on Buffer Menu mode in it. Everything else ++described above is implemented by the special commands provided in ++Buffer Menu mode. One consequence of this is that you can switch from ++the @samp{*Buffer List*} buffer to another Emacs buffer, and edit ++there. You can reselect the @samp{*Buffer List*} buffer later, to ++perform the operations already requested, or you can kill it, or pay ++no further attention to it. ++ ++ Normally, the buffer @samp{*Buffer List*} is not updated ++automatically when buffers are created and killed; its contents are ++just text. If you have created, deleted or renamed buffers, the way ++to update @samp{*Buffer List*} to show what you have done is to type ++@kbd{g} (@code{revert-buffer}). You can make this happen regularly ++every @code{auto-revert-interval} seconds if you enable Auto Revert ++mode in this buffer, as long as it is not marked modified. Global ++Auto Revert mode applies to the @samp{*Buffer List*} buffer only if ++@code{global-auto-revert-non-file-buffers} is non-@code{nil}. ++@iftex ++@inforef{Autorevert,, emacs-xtra}, for details. ++@end iftex ++@ifnottex ++@xref{Autorevert, global-auto-revert-non-file-buffers}, for details. ++@end ifnottex ++ ++@node Indirect Buffers ++@section Indirect Buffers ++@cindex indirect buffer ++@cindex base buffer ++ ++ An @dfn{indirect buffer} shares the text of some other buffer, which ++is called the @dfn{base buffer} of the indirect buffer. In some ways it ++is the analogue, for buffers, of a symbolic link between files. ++ ++@table @kbd ++@findex make-indirect-buffer ++@item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET} ++Create an indirect buffer named @var{indirect-name} whose base buffer ++is @var{base-buffer}. ++@findex clone-indirect-buffer ++@item M-x clone-indirect-buffer @key{RET} ++Create an indirect buffer that is a twin copy of the current buffer. ++@item C-x 4 c ++@kindex C-x 4 c ++@findex clone-indirect-buffer-other-window ++Create an indirect buffer that is a twin copy of the current buffer, and ++select it in another window (@code{clone-indirect-buffer-other-window}). ++@end table ++ ++ The text of the indirect buffer is always identical to the text of its ++base buffer; changes made by editing either one are visible immediately ++in the other. But in all other respects, the indirect buffer and its ++base buffer are completely separate. They can have different names, ++different values of point, different narrowing, different markers, ++different major modes, and different local variables. ++ ++ An indirect buffer cannot visit a file, but its base buffer can. If ++you try to save the indirect buffer, that actually works by saving the ++base buffer. Killing the base buffer effectively kills the indirect ++buffer, but killing an indirect buffer has no effect on its base buffer. ++ ++ One way to use indirect buffers is to display multiple views of an ++outline. @xref{Outline Views}. ++ ++@vindex clone-indirect-buffer-hook ++ A quick and handy way to make an indirect buffer is with the command ++@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect ++buffer whose base buffer is the current buffer. With a numeric ++argument, it prompts for the name of the indirect buffer; otherwise it ++uses the name of the current buffer, with a @samp{<@var{n}>} suffix ++added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window}) ++works like @kbd{M-x clone-indirect-buffer}, but it selects the new ++buffer in another window. These functions run the hook ++@code{clone-indirect-buffer-hook} after creating the indirect buffer. ++ ++ The more general way to make an indirect buffer is with the command ++@kbd{M-x make-indirect-buffer}. It creates an indirect buffer from ++buffer @var{base-buffer}, under the name @var{indirect-name}. It ++prompts for both @var{base-buffer} and @var{indirect-name} using the ++minibuffer. ++ ++@node Buffer Convenience ++@section Convenience Features and Customization of Buffer Handling ++ ++ This section describes several modes and features that make it more ++convenient to switch between buffers. ++ ++@menu ++* Uniquify:: Making buffer names unique with directory parts. ++* Iswitchb:: Switching between buffers with substrings. ++* Buffer Menus:: Configurable buffer menu. ++@end menu ++ ++@node Uniquify ++@subsection Making Buffer Names Unique ++ ++@cindex unique buffer names ++@cindex directories in buffer names ++ When several buffers visit identically-named files, Emacs must give ++the buffers distinct names. The usual method for making buffer names ++unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer ++names (all but one of them). ++ ++@vindex uniquify-buffer-name-style ++ Other methods work by adding parts of each file's directory to the ++buffer name. To select one, customize the variable ++@code{uniquify-buffer-name-style} (@pxref{Easy Customization}). ++ ++ To begin with, the @code{forward} naming method includes part of the ++file's directory name at the beginning of the buffer name; using this ++method, buffers visiting the files @file{/u/rms/tmp/Makefile} and ++@file{/usr/projects/zaphod/Makefile} would be named ++@samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead ++of @samp{Makefile} and @samp{Makefile<2>}). ++ ++ In contrast, the @code{post-forward} naming method would call the ++buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the ++@code{reverse} naming method would call them @samp{Makefile\tmp} and ++@samp{Makefile\zaphod}. The nontrivial difference between ++@code{post-forward} and @code{reverse} occurs when just one directory ++name is not enough to distinguish two files; then @code{reverse} puts ++the directory names in reverse order, so that @file{/top/middle/file} ++becomes @samp{file\middle\top}, while @code{post-forward} puts them in ++forward order after the file name, as in @samp{file|top/middle}. ++ ++ Which rule to follow for putting the directory names in the buffer ++name is not very important if you are going to @emph{look} at the ++buffer names before you type one. But as an experienced user, if you ++know the rule, you won't have to look. And then you may find that one ++rule or another is easier for you to remember and apply quickly. ++ ++@node Iswitchb ++@subsection Switching Between Buffers using Substrings ++ ++@findex iswitchb-mode ++@cindex Iswitchb mode ++@cindex mode, Iswitchb ++@kindex C-x b @r{(Iswitchb mode)} ++@kindex C-x 4 b @r{(Iswitchb mode)} ++@kindex C-x 5 b @r{(Iswitchb mode)} ++@kindex C-x 4 C-o @r{(Iswitchb mode)} ++ ++ Iswitchb global minor mode provides convenient switching between ++buffers using substrings of their names. It replaces the normal ++definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x ++4 C-o} with alternative commands that are somewhat ``smarter.'' ++ ++ When one of these commands prompts you for a buffer name, you can ++type in just a substring of the name you want to choose. As you enter ++the substring, Iswitchb mode continuously displays a list of buffers ++that match the substring you have typed. ++ ++ At any time, you can type @key{RET} to select the first buffer in ++the list. So the way to select a particular buffer is to make it the ++first in the list. There are two ways to do this. You can type more ++of the buffer name and thus narrow down the list, excluding unwanted ++buffers above the desired one. Alternatively, you can use @kbd{C-s} ++and @kbd{C-r} to rotate the list until the desired buffer is first. ++ ++ @key{TAB} while entering the buffer name performs completion on the ++string you have entered, based on the displayed list of buffers. ++ ++ To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize ++the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy ++Customization}). ++ ++@node Buffer Menus ++@subsection Customizing Buffer Menus ++ ++@findex bs-show ++@cindex buffer list, customizable ++@table @kbd ++@item M-x bs-show ++Make a list of buffers similarly to @kbd{M-x list-buffers} but ++customizable. ++@end table ++ ++ @kbd{M-x bs-show} pops up a buffer list similar to the one normally ++displayed by @kbd{C-x C-b} but which you can customize. If you prefer ++this to the usual buffer list, you can bind this command to @kbd{C-x ++C-b}. To customize this buffer list, use the @code{bs} Custom group ++(@pxref{Easy Customization}). ++ ++@findex msb-mode ++@cindex mode, MSB ++@cindex MSB mode ++@cindex buffer menu ++@findex mouse-buffer-menu ++@kindex C-Down-Mouse-1 ++ MSB global minor mode (``MSB'' stands for ``mouse select buffer'') ++provides a different and customizable mouse buffer menu which you may ++prefer. It replaces the bindings of @code{mouse-buffer-menu}, ++normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You ++can customize the menu in the @code{msb} Custom group. ++ ++@ignore ++ arch-tag: 08c43460-f4f4-4b43-9cb5-1ea9ad991695 ++@end ignore +diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi +new file mode 100644 +index 0000000..2eb714b +--- /dev/null ++++ b/doc/emacs/building.texi +@@ -0,0 +1,1484 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Building, Maintaining, Programs, Top ++@chapter Compiling and Testing Programs ++@cindex building programs ++@cindex program building ++@cindex running Lisp functions ++ ++ The previous chapter discusses the Emacs commands that are useful for ++making changes in programs. This chapter deals with commands that assist ++in the larger process of compiling and testing programs. ++ ++@menu ++* Compilation:: Compiling programs in languages other ++ than Lisp (C, Pascal, etc.). ++* Compilation Mode:: The mode for visiting compiler errors. ++* Compilation Shell:: Customizing your shell properly ++ for use in the compilation buffer. ++* Grep Searching:: Searching with grep. ++* Flymake:: Finding syntax errors on the fly. ++* Debuggers:: Running symbolic debuggers for non-Lisp programs. ++* Executing Lisp:: Various modes for editing Lisp programs, ++ with different facilities for running ++ the Lisp programs. ++* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs. ++* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. ++* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. ++* External Lisp:: Communicating through Emacs with a separate Lisp. ++@end menu ++ ++@node Compilation ++@section Running Compilations under Emacs ++@cindex inferior process ++@cindex make ++@cindex compilation errors ++@cindex error log ++ ++ Emacs can run compilers for noninteractive languages such as C and ++Fortran as inferior processes, feeding the error log into an Emacs buffer. ++It can also parse the error messages and show you the source lines where ++compilation errors occurred. ++ ++@table @kbd ++@item M-x compile ++Run a compiler asynchronously under Emacs, with error messages going to ++the @samp{*compilation*} buffer. ++@item M-x recompile ++Invoke a compiler with the same command as in the last invocation of ++@kbd{M-x compile}. ++@item M-x kill-compilation ++Kill the running compilation subprocess. ++@end table ++ ++@findex compile ++ To run @code{make} or another compilation command, do @kbd{M-x ++compile}. This command reads a shell command line using the minibuffer, ++and then executes the command in an inferior shell, putting output in ++the buffer named @samp{*compilation*}. The current buffer's default ++directory is used as the working directory for the execution of the ++command; normally, therefore, the compilation happens in this ++directory. ++ ++@vindex compile-command ++ The default for the compilation command is normally @samp{make -k}, ++which is correct most of the time for nontrivial programs. ++@xref{Top,, Make, make, GNU Make Manual}. If you have done @kbd{M-x ++compile} before, the default each time is the command you used the ++previous time. @code{compile} stores this command in the variable ++@code{compile-command}, so setting that variable specifies the default ++for the next use of @kbd{M-x compile}. If a file specifies a file ++local value for @code{compile-command}, that provides the default when ++you type @kbd{M-x compile} in that file's buffer. @xref{File ++Variables}. ++ ++ Starting a compilation displays the buffer @samp{*compilation*} in ++another window but does not select it. The buffer's mode line tells ++you whether compilation is finished, with the word @samp{run}, ++@samp{signal} or @samp{exit} inside the parentheses. You do not have ++to keep this buffer visible; compilation continues in any case. While ++a compilation is going on, the string @samp{Compiling} appears in the ++mode lines of all windows. When this string disappears, the ++compilation is finished. ++ ++ If you want to watch the compilation transcript as it appears, switch ++to the @samp{*compilation*} buffer and move point to the end of the ++buffer. When point is at the end, new compilation output is inserted ++above point, which remains at the end. If point is not at the end of ++the buffer, it remains fixed while more compilation output is added at ++the end of the buffer. ++ ++@cindex compilation buffer, keeping point at end ++@vindex compilation-scroll-output ++ If you change the variable @code{compilation-scroll-output} to a ++non-@code{nil} value, the compilation buffer will scroll automatically ++to follow the output as it comes in. If the value is ++@code{first-error}, the scrolling stops at the first error that ++appears, leaving point at that error. For any other non-@code{nil} ++value, the buffer continues scrolling until there is no more output. ++ ++@findex recompile ++ To rerun the last compilation with the same command, type @kbd{M-x ++recompile}. This automatically reuses the compilation command from ++the last invocation of @kbd{M-x compile}. It also reuses the ++@samp{*compilation*} buffer and starts the compilation in its default ++directory, which is the directory in which the previous compilation ++was started. ++ ++ When the compiler process terminates, for whatever reason, the mode ++line of the @samp{*compilation*} buffer changes to say @samp{exit} ++(followed by the exit code, @samp{[0]} for a normal exit), or ++@samp{signal} (if a signal terminated the process), instead of ++@samp{run}. ++ ++@findex kill-compilation ++ Starting a new compilation also kills any compilation already ++running in @samp{*compilation*}, as the buffer can only handle one ++compilation at any time. However, @kbd{M-x compile} asks for ++confirmation before actually killing a compilation that is running. ++You can also kill the compilation process with @kbd{M-x ++kill-compilation}. ++ ++ If you want to run two compilations at once, you should start the ++first one, then rename the @samp{*compilation*} buffer (perhaps using ++@code{rename-uniquely}; @pxref{Misc Buffer}), and start the other ++compilation. That will create a new @samp{*compilation*} buffer. ++ ++ Emacs does not expect a compiler process to launch asynchronous ++subprocesses; if it does, and they keep running after the main ++compiler process has terminated, Emacs may kill them or their output ++may not arrive in Emacs. To avoid this problem, make the main process ++wait for its subprocesses to finish. In a shell script, you can do this ++using @samp{$!} and @samp{wait}, like this: ++ ++@example ++(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess} ++echo first message ++wait $pid # @r{Wait for subprocess} ++@end example ++ ++ If the background process does not output to the compilation buffer, ++so you only need to prevent it from being killed when the main ++compilation process terminates, this is sufficient: ++ ++@example ++nohup @var{command}; sleep 1 ++@end example ++ ++@vindex compilation-environment ++ You can control the environment passed to the compilation command ++with the variable @code{compilation-environment}. Its value is a list ++of environment variable settings; each element should be a string of ++the form @code{"@var{envvarname}=@var{value}"}. These environment ++variable settings override the usual ones. ++ ++@node Compilation Mode ++@section Compilation Mode ++ ++@cindex Compilation mode ++@cindex mode, Compilation ++ The @samp{*compilation*} buffer uses a special major mode, ++Compilation mode, whose main feature is to provide a convenient way to ++visit the source line corresponding to an error message. These ++commands are also available in other special buffers that list ++locations in files, including those made by @kbd{M-x grep} and ++@kbd{M-x occur}. ++ ++@table @kbd ++@item M-g M-n ++@itemx M-g n ++@itemx C-x ` ++Visit the locus of the next error message or match. ++@item M-g M-p ++@itemx M-g p ++Visit the locus of the previous error message or match. ++@item @key{RET} ++Visit the locus of the error message that point is on. ++This command is used in the compilation buffer. ++@item Mouse-2 ++Visit the locus of the error message that you click on. ++@item M-n ++Find and highlight the locus of the next error message, without ++selecting the source buffer. ++@item M-p ++Find and highlight the locus of the previous error message, without ++selecting the source buffer. ++@item M-@} ++Move point to the next error for a different file than the current ++one. ++@item M-@{ ++Move point to the previous error for a different file than the current ++one. ++@item C-c C-f ++Toggle Next Error Follow minor mode, which makes cursor motion in the ++compilation buffer produce automatic source display. ++@end table ++ ++@findex compile-goto-error ++@vindex compilation-auto-jump-to-first-error ++ You can visit the source for any particular error message by moving ++point in the @samp{*compilation*} buffer to that error message and ++typing @key{RET} (@code{compile-goto-error}). Alternatively, you can ++click @kbd{Mouse-2} on the error message; you need not switch to the ++@samp{*compilation*} buffer first. If you set the variable ++@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value, ++Emacs automatically jumps to the first error, if any, as soon as it ++appears in the @samp{*compilation*} buffer. ++ ++@kindex M-g M-n ++@kindex M-g n ++@kindex C-x ` ++@findex next-error ++@vindex next-error-highlight ++ To parse the compiler error messages sequentially, type @kbd{C-x `} ++(@code{next-error}). The character following the @kbd{C-x} is the ++backquote or ``grave accent,'' not the single-quote. This command is ++available in all buffers, not just in @samp{*compilation*}; it ++displays the next error message at the top of one window and source ++location of the error in another window. It also temporarily ++highlights the relevant source line, for a period controlled by the ++variable @code{next-error-highlight}. ++ ++ The first time @w{@kbd{C-x `}} is used after the start of a compilation, ++it moves to the first error's location. Subsequent uses of @kbd{C-x ++`} advance down to subsequent errors. If you visit a specific error ++message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}} ++commands advance from there. When @w{@kbd{C-x `}} gets to the end of the ++buffer and finds no more error messages to visit, it fails and signals ++an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of ++the compilation buffer, and goes to the first error's location. ++ ++@vindex compilation-skip-threshold ++ By default, @w{@kbd{C-x `}} skips less important messages. The variable ++@code{compilation-skip-threshold} controls this. If its value is 2, ++@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less ++than warning, and 0 doesn't skip any messages. The default is 1. ++ ++ When the window has a left fringe, an arrow in the fringe points to ++the current message in the compilation buffer. The variable ++@code{compilation-context-lines} controls the number of lines of ++leading context to display before the current message. Going to an ++error message location scrolls the @samp{*compilation*} buffer to put ++the message that far down from the top. The value @code{nil} is ++special: if there's a left fringe, the window doesn't scroll at all ++if the message is already visible. If there is no left fringe, ++@code{nil} means display the message at the top of the window. ++ ++ If you're not in the compilation buffer when you run ++@code{next-error}, Emacs will look for a buffer that contains error ++messages. First, it looks for one displayed in the selected frame, ++then for one that previously had @code{next-error} called on it, and ++then at the current buffer. Finally, Emacs looks at all the remaining ++buffers. @code{next-error} signals an error if it can't find any such ++buffer. ++ ++@vindex compilation-error-regexp-alist ++@vindex grep-regexp-alist ++ To parse messages from the compiler, Compilation mode uses the ++variable @code{compilation-error-regexp-alist} which lists various ++formats of error messages and tells Emacs how to extract the source file ++and the line number from the text of a message. If your compiler isn't ++supported, you can tailor Compilation mode to it by adding elements to ++that list. A similar variable @code{grep-regexp-alist} tells Emacs how ++to parse output of a @code{grep} command. ++ ++@findex compilation-next-error ++@findex compilation-previous-error ++@findex compilation-next-file ++@findex compilation-previous-file ++ Compilation mode also redefines the keys @key{SPC} and @key{DEL} to ++scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error}) ++and @kbd{M-p} (@code{compilation-previous-error}) to move to the next ++or previous error message. You can also use @kbd{M-@{} ++(@code{compilation-next-file} and @kbd{M-@}} ++(@code{compilation-previous-file}) to move up or down to an error ++message for a different source file. ++ ++@cindex Next Error Follow mode ++@findex next-error-follow-minor-mode ++ You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In ++this minor mode, ordinary cursor motion in the compilation buffer ++automatically updates the source buffer. For instance, moving the ++cursor to the next error message causes the location of that error to ++be displayed immediately. ++ ++ The features of Compilation mode are also available in a minor mode ++called Compilation Minor mode. This lets you parse error messages in ++any buffer, not just a normal compilation output buffer. Type @kbd{M-x ++compilation-minor-mode} to enable the minor mode. This defines the keys ++@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode. ++ ++ Compilation minor mode works in any buffer, as long as the contents ++are in a format that it understands. In an Rlogin buffer (@pxref{Remote ++Host}), Compilation minor mode automatically accesses remote source ++files by FTP (@pxref{File Names}). ++ ++@node Compilation Shell ++@section Subshells for Compilation ++ ++ Emacs uses a shell to run the compilation command, but specifies the ++option for a noninteractive shell. This means, in particular, that ++the shell should start with no prompt. If you find your usual shell ++prompt making an unsightly appearance in the @samp{*compilation*} ++buffer, it means you have made a mistake in your shell's init file by ++setting the prompt unconditionally. (This init file's name may be ++@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or ++various other things, depending on the shell you use.) The shell init ++file should set the prompt only if there already is a prompt. Here's ++how to do it in bash: ++ ++@example ++if [ "$@{PS1+set@}" = set ] ++then PS1=@dots{} ++fi ++@end example ++ ++@noindent ++And here's how to do it in csh: ++ ++@example ++if ($?prompt) set prompt = @dots{} ++@end example ++ ++ There may well be other things that your shell's init file ++ought to do only for an interactive shell. You can use the same ++method to conditionalize them. ++ ++ The MS-DOS ``operating system'' does not support asynchronous ++subprocesses; to work around this lack, @kbd{M-x compile} runs the ++compilation command synchronously on MS-DOS. As a consequence, you must ++wait until the command finishes before you can do anything else in ++Emacs. ++@iftex ++@inforef{MS-DOS,,emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{MS-DOS}. ++@end ifnottex ++ ++@node Grep Searching ++@section Searching with Grep under Emacs ++ ++ Just as you can run a compiler from Emacs and then visit the lines ++with compilation errors, you can also run @code{grep} and then visit ++the lines on which matches were found. This works by treating the ++matches reported by @code{grep} as if they were ``errors.'' The ++buffer of matches uses Grep mode, which is a variant of Compilation ++mode (@pxref{Compilation Mode}). ++ ++@table @kbd ++@item M-x grep ++@itemx M-x lgrep ++Run @code{grep} asynchronously under Emacs, with matching lines ++listed in the buffer named @samp{*grep*}. ++@item M-x grep-find ++@itemx M-x find-grep ++@itemx M-x rgrep ++Run @code{grep} via @code{find}, with user-specified arguments, and ++collect output in the buffer named @samp{*grep*}. ++@item M-x kill-grep ++Kill the running @code{grep} subprocess. ++@end table ++ ++@findex grep ++ To run @code{grep}, type @kbd{M-x grep}, then enter a command line ++that specifies how to run @code{grep}. Use the same arguments you ++would give @code{grep} when running it normally: a @code{grep}-style ++regexp (usually in single-quotes to quote the shell's special ++characters) followed by file names, which may use wildcards. If you ++specify a prefix argument for @kbd{M-x grep}, it finds the tag ++(@pxref{Tags}) in the buffer around point, and puts that into the ++default @code{grep} command. ++ ++ Your command need not simply run @code{grep}; you can use any shell ++command that produces output in the same format. For instance, you ++can chain @code{grep} commands, like this: ++ ++@example ++grep -nH -e foo *.el | grep bar | grep toto ++@end example ++ ++ The output from @code{grep} goes in the @samp{*grep*} buffer. You ++can find the corresponding lines in the original files using @w{@kbd{C-x ++`}}, @key{RET}, and so forth, just like compilation errors. ++ ++ Some grep programs accept a @samp{--color} option to output special ++markers around matches for the purpose of highlighting. You can make ++use of this feature by setting @code{grep-highlight-matches} to ++@code{t}. When displaying a match in the source buffer, the exact ++match will be highlighted, instead of the entire source line. ++ ++@findex grep-find ++@findex find-grep ++ The command @kbd{M-x grep-find} (also available as @kbd{M-x ++find-grep}) is similar to @kbd{M-x grep}, but it supplies a different ++initial default for the command---one that runs both @code{find} and ++@code{grep}, so as to search every file in a directory tree. See also ++the @code{find-grep-dired} command, in @ref{Dired and Find}. ++ ++@findex lgrep ++@findex rgrep ++ The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep} ++(recursive grep) are more user-friendly versions of @code{grep} and ++@code{grep-find}, which prompt separately for the regular expression ++to match, the files to search, and the base directory for the search. ++Case sensitivity of the search is controlled by the ++current value of @code{case-fold-search}. ++ ++These commands build the shell commands based on the variables ++@code{grep-template} (for @code{lgrep}) and @code{grep-find-template} ++(for @code{rgrep}). ++ ++The files to search can use aliases defined in the variable ++@code{grep-files-aliases}. ++ ++Subdirectories listed in the variable ++@code{grep-find-ignored-directories} such as those typically used by ++various version control systems, like CVS and arch, are automatically ++skipped by @code{rgrep}. ++ ++@node Flymake ++@section Finding Syntax Errors On The Fly ++@cindex checking syntax ++ ++ Flymake mode is a minor mode that performs on-the-fly syntax ++checking for many programming and markup languages, including C, C++, ++Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell ++mode, which performs spell checking for ordinary human languages in a ++similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode ++runs an appropriate syntax checking tool in the background, using a ++temporary copy of the buffer. It then parses the error and warning ++messages, and highlights the erroneous lines in the buffer. The ++syntax checking tool used depends on the language; for example, for ++C/C++ files this is usually the C compiler. Flymake can also use ++build tools such as @code{make} for checking complicated projects. ++ ++ To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move ++to the errors spotted by Flymake mode with @kbd{M-x ++flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To ++display any error messages associated with the current line, use ++@kbd{M-x flymake-display-err-menu-for-current-line}. ++ ++ For more details about using Flymake, see @ref{Top, Flymake, ++Flymake, flymake, The Flymake Manual}. ++ ++@node Debuggers ++@section Running Debuggers Under Emacs ++@cindex debuggers ++@cindex GUD library ++@cindex GDB ++@cindex DBX ++@cindex SDB ++@cindex XDB ++@cindex Perldb ++@cindex JDB ++@cindex PDB ++ ++@c Do you believe in GUD? ++The GUD (Grand Unified Debugger) library provides an Emacs interface ++to a wide variety of symbolic debuggers. Unlike the GDB graphical ++interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD ++can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger ++PDB, or the Java Debugger JDB. ++ ++ In addition, Emacs contains a built-in system for debugging Emacs ++Lisp programs. @xref{Debugging,, The Lisp Debugger, elisp, the Emacs ++Lisp Reference Manual}, for information on the Emacs Lisp debugger. ++ ++@menu ++* Starting GUD:: How to start a debugger subprocess. ++* Debugger Operation:: Connection between the debugger and source buffers. ++* Commands of GUD:: Key bindings for common commands. ++* GUD Customization:: Defining your own commands for GUD. ++* GDB Graphical Interface:: An enhanced mode that uses GDB features to ++ implement a graphical debugging environment through ++ Emacs. ++@end menu ++ ++@node Starting GUD ++@subsection Starting GUD ++ ++ There are several commands for starting a debugger under GUD, each ++corresponding to a particular debugger program. ++ ++@table @kbd ++@item M-x gdb @key{RET} @var{file} @key{RET} ++@findex gdb ++Run GDB as a subprocess of Emacs. This uses an IDE-like graphical ++interface; see @ref{GDB Graphical Interface}. Only GDB works with the ++graphical interface. ++ ++@item M-x gud-gdb @key{RET} @var{file} @key{RET} ++@findex gud-gdb ++Run GDB as a subprocess of Emacs. This command creates a buffer for ++input and output to GDB, and switches to it. If a GDB buffer already ++exists, it just switches to that buffer. ++ ++@item M-x dbx @key{RET} @var{file} @key{RET} ++@findex dbx ++Run DBX as a subprocess of Emacs. Since Emacs does not implement a ++graphical interface for DBX, communication with DBX works by typing ++commands in the GUD interaction buffer. The same is true for all ++the other supported debuggers. ++ ++@item M-x xdb @key{RET} @var{file} @key{RET} ++@findex xdb ++@vindex gud-xdb-directories ++Run XDB as a subprocess of Emacs. Use the variable ++@code{gud-xdb-directories} to specify directories to search for source ++files. ++ ++@item M-x sdb @key{RET} @var{file} @key{RET} ++@findex sdb ++Run SDB as a subprocess of Emacs. ++ ++Some versions of SDB do not mention source file names in their ++messages. When you use them, you need to have a valid tags table ++(@pxref{Tags}) in order for GUD to find functions in the source code. ++If you have not visited a tags table or the tags table doesn't list ++one of the functions, you get a message saying @samp{The sdb support ++requires a valid tags table to work}. If this happens, generate a ++valid tags table in the working directory and try again. ++ ++@item M-x perldb @key{RET} @var{file} @key{RET} ++@findex perldb ++Run the Perl interpreter in debug mode to debug @var{file}, a Perl program. ++ ++@item M-x jdb @key{RET} @var{file} @key{RET} ++@findex jdb ++Run the Java debugger to debug @var{file}. ++ ++@item M-x pdb @key{RET} @var{file} @key{RET} ++@findex pdb ++Run the Python debugger to debug @var{file}. ++@end table ++ ++ Each of these commands takes one argument: a command line to invoke ++the debugger. In the simplest case, specify just the name of the ++executable file you want to debug. You may also use options that the ++debugger supports. However, shell wildcards and variables are not ++allowed. GUD assumes that the first argument not starting with a ++@samp{-} is the executable file name. ++ ++@cindex remote host, debugging on ++Tramp provides a facility to debug programs on remote hosts ++(@pxref{Running a debugger on a remote host, Running a debugger on a ++remote host,, tramp, The Tramp Manual}), whereby both the debugger and ++the program being debugged are on the same remote host. This should ++not be confused with debugging programs remotely, where the program ++and the debugger run on different machines, as can be done using the ++GDB remote debugging feature, for example (@pxref{Remote Debugging,, ++Debugging Remote Programs, gdb, The GNU debugger}). ++ ++@node Debugger Operation ++@subsection Debugger Operation ++ ++@cindex fringes, and current execution line in GUD ++ Generally when you run a debugger with GUD, the debugger uses an Emacs ++buffer for its ordinary input and output. This is called the GUD ++buffer. Input and output from the program you are debugging also use ++this buffer. We call this @dfn{text command mode}. The GDB Graphical ++Interface can use further buffers (@pxref{GDB Graphical Interface}). ++ ++ The debugger displays the source files of the program by visiting ++them in Emacs buffers. An arrow in the left fringe indicates the ++current execution line.@footnote{On a text-only terminal, the arrow ++appears as @samp{=>} and overlays the first two text columns.} Moving ++point in this buffer does not move the arrow. The arrow is not part ++of the file's text; it appears only on the screen. ++ ++ You can start editing these source files at any time in the buffers ++that display them. If you do modify a source file, keep in mind that ++inserting or deleting lines will throw off the arrow's positioning; ++GUD has no way of figuring out which line corresponded before your ++changes to the line number in a debugger message. Also, you'll ++typically have to recompile and restart the program for your changes ++to be reflected in the debugger's tables. ++ ++@cindex tooltips with GUD ++@vindex tooltip-gud-modes ++@vindex gud-tooltip-mode ++@vindex gud-tooltip-echo-area ++ The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. ++You activate this feature by turning on the minor mode ++@code{gud-tooltip-mode}. Then you can display a variable's value in a ++tooltip simply by pointing at it with the mouse. This operates in the ++GUD buffer and in source buffers with major modes in the list ++@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area} ++is non-@code{nil} then the variable's value is displayed in the echo ++area. When debugging a C program using the GDB Graphical Interface, you ++can also display macro definitions associated with an identifier when ++the program is not executing. ++ ++ GUD tooltips are disabled when you use GDB in text command mode ++(@pxref{GDB Graphical Interface}), because displaying an expression's ++value in GDB can sometimes expand a macro and result in a side effect ++that interferes with the program's operation. The GDB graphical ++interface supports GUD tooltips and assures they will not cause side ++effects. ++ ++@node Commands of GUD ++@subsection Commands of GUD ++ ++ The GUD interaction buffer uses a variant of Shell mode, so the ++Emacs commands of Shell mode are available (@pxref{Shell Mode}). All ++the usual commands for your debugger are available, and you can use ++the Shell mode history commands to repeat them. If you wish, you can ++control your debugger process entirely through this buffer. ++ ++ GUD mode also provides commands for setting and clearing ++breakpoints, for selecting stack frames, and for stepping through the ++program. These commands are available both in the GUD buffer and ++globally, but with different key bindings. It also has its own tool ++bar from which you can invoke the more common commands by clicking on ++the appropriate icon. This is particularly useful for repetitive ++commands like @code{gud-next} and @code{gud-step}, and allows you to ++keep the GUD buffer hidden. ++ ++ The breakpoint commands are normally used in source file buffers, ++because that is the easiest way to specify where to set or clear the ++breakpoint. Here's the global command to set a breakpoint: ++ ++@table @kbd ++@item C-x @key{SPC} ++@kindex C-x SPC ++Set a breakpoint on the source line that point is on. ++@end table ++ ++@kindex C-x C-a @r{(GUD)} ++ Here are the other special commands provided by GUD@. The keys ++starting with @kbd{C-c} are available only in the GUD interaction ++buffer. The key bindings that start with @kbd{C-x C-a} are available ++in the GUD interaction buffer and also in source files. Some of these ++commands are not available to all the supported debuggers. ++ ++@table @kbd ++@item C-c C-l ++@kindex C-c C-l @r{(GUD)} ++@itemx C-x C-a C-l ++@findex gud-refresh ++Display in another window the last line referred to in the GUD ++buffer (that is, the line indicated in the last location message). ++This runs the command @code{gud-refresh}. ++ ++@item C-c C-s ++@kindex C-c C-s @r{(GUD)} ++@itemx C-x C-a C-s ++@findex gud-step ++Execute a single line of code (@code{gud-step}). If the line contains ++a function call, execution stops after entering the called function. ++ ++@item C-c C-n ++@kindex C-c C-n @r{(GUD)} ++@itemx C-x C-a C-n ++@findex gud-next ++Execute a single line of code, stepping across entire function calls ++at full speed (@code{gud-next}). ++ ++@item C-c C-i ++@kindex C-c C-i @r{(GUD)} ++@itemx C-x C-a C-i ++@findex gud-stepi ++Execute a single machine instruction (@code{gud-stepi}). ++ ++@item C-c C-p ++@kindex C-c C-p @r{(GUD)} ++@itemx C-x C-a C-p ++@findex gud-print ++Evaluate the expression at point (@code{gud-print}). If Emacs ++does not print the exact expression that you want, mark it as a region ++first. ++ ++@need 3000 ++@item C-c C-r ++@kindex C-c C-r @r{(GUD)} ++@itemx C-x C-a C-r ++@findex gud-cont ++Continue execution without specifying any stopping point. The program ++will run until it hits a breakpoint, terminates, or gets a signal that ++the debugger is checking for (@code{gud-cont}). ++ ++@need 1000 ++@item C-c C-d ++@kindex C-c C-d @r{(GUD)} ++@itemx C-x C-a C-d ++@findex gud-remove ++Delete the breakpoint(s) on the current source line, if any ++(@code{gud-remove}). If you use this command in the GUD interaction ++buffer, it applies to the line where the program last stopped. ++ ++@item C-c C-t ++@kindex C-c C-t @r{(GUD)} ++@itemx C-x C-a C-t ++@findex gud-tbreak ++Set a temporary breakpoint on the current source line, if any ++(@code{gud-tbreak}). If you use this command in the GUD interaction ++buffer, it applies to the line where the program last stopped. ++ ++@item C-c < ++@kindex C-c < @r{(GUD)} ++@itemx C-x C-a < ++@findex gud-up ++Select the next enclosing stack frame (@code{gud-up}). This is ++equivalent to the GDB command @samp{up}. ++ ++@item C-c > ++@kindex C-c > @r{(GUD)} ++@itemx C-x C-a > ++@findex gud-down ++Select the next inner stack frame (@code{gud-down}). This is ++equivalent to the GDB command @samp{down}. ++ ++@item C-c C-u ++@kindex C-c C-u @r{(GUD)} ++@itemx C-x C-a C-u ++@findex gud-until ++Continue execution to the current line (@code{gud-until}). The ++program will run until it hits a breakpoint, terminates, gets a signal ++that the debugger is checking for, or reaches the line on which the ++cursor currently sits. ++ ++@item C-c C-f ++@kindex C-c C-f @r{(GUD)} ++@itemx C-x C-a C-f ++@findex gud-finish ++Run the program until the selected stack frame returns or ++stops for some other reason (@code{gud-finish}). ++@end table ++ ++ If you are using GDB, these additional key bindings are available: ++ ++@table @kbd ++@item C-x C-a C-j ++@kindex C-x C-a C-j @r{(GUD)} ++@findex gud-jump ++Only useful in a source buffer, @code{gud-jump} transfers the ++program's execution point to the current line. In other words, the ++next line that the program executes will be the one where you gave the ++command. If the new execution line is in a different function from ++the previously one, GDB prompts for confirmation since the results may ++be bizarre. See the GDB manual entry regarding @code{jump} for ++details. ++ ++@item @key{TAB} ++@kindex TAB @r{(GUD)} ++@findex gud-gdb-complete-command ++With GDB, complete a symbol name (@code{gud-gdb-complete-command}). ++This key is available only in the GUD interaction buffer. ++@end table ++ ++ These commands interpret a numeric argument as a repeat count, when ++that makes sense. ++ ++ Because @key{TAB} serves as a completion command, you can't use it to ++enter a tab as input to the program you are debugging with GDB. ++Instead, type @kbd{C-q @key{TAB}} to enter a tab. ++ ++@node GUD Customization ++@subsection GUD Customization ++ ++@vindex gdb-mode-hook ++@vindex dbx-mode-hook ++@vindex sdb-mode-hook ++@vindex xdb-mode-hook ++@vindex perldb-mode-hook ++@vindex pdb-mode-hook ++@vindex jdb-mode-hook ++ On startup, GUD runs one of the following hooks: @code{gdb-mode-hook}, ++if you are using GDB; @code{dbx-mode-hook}, if you are using DBX; ++@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you ++are using XDB; @code{perldb-mode-hook}, for Perl debugging mode; ++@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can ++use these hooks to define custom key bindings for the debugger ++interaction buffer. @xref{Hooks}. ++ ++ Here is a convenient way to define a command that sends a particular ++command string to the debugger, and set up a key binding for it in the ++debugger interaction buffer: ++ ++@findex gud-def ++@example ++(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring}) ++@end example ++ ++ This defines a command named @var{function} which sends ++@var{cmdstring} to the debugger process, and gives it the documentation ++string @var{docstring}. You can then use the command @var{function} in any ++buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds ++the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to ++@kbd{C-x C-a @var{binding}} generally. ++ ++ The command string @var{cmdstring} may contain certain ++@samp{%}-sequences that stand for data to be filled in at the time ++@var{function} is called: ++ ++@table @samp ++@item %f ++The name of the current source file. If the current buffer is the GUD ++buffer, then the ``current source file'' is the file that the program ++stopped in. ++ ++@item %l ++The number of the current source line. If the current buffer is the GUD ++buffer, then the ``current source line'' is the line that the program ++stopped in. ++ ++@item %e ++In transient-mark-mode the text in the region, if it is active. ++Otherwise the text of the C lvalue or function-call expression at or ++adjacent to point. ++ ++@item %a ++The text of the hexadecimal address at or adjacent to point. ++ ++@item %p ++The numeric argument of the called function, as a decimal number. If ++the command is used without a numeric argument, @samp{%p} stands for the ++empty string. ++ ++If you don't use @samp{%p} in the command string, the command you define ++ignores any numeric argument. ++ ++@item %d ++The name of the directory of the current source file. ++ ++@item %c ++Fully qualified class name derived from the expression surrounding point ++(jdb only). ++@end table ++ ++@node GDB Graphical Interface ++@subsection GDB Graphical Interface ++ ++ The command @code{gdb} starts GDB in a graphical interface, using ++Emacs windows for display program state information. In effect, this ++makes Emacs into an IDE (interactive development environment). With ++it, you do not need to use textual GDB commands; you can control the ++debugging session with the mouse. For example, you can click in the ++fringe of a source buffer to set a breakpoint there, or on a stack ++frame in the stack buffer to select that frame. ++ ++ This mode requires telling GDB that its ``screen size'' is ++unlimited, so it sets the height and width accordingly. For correct ++operation you must not change these values during the GDB session. ++ ++@vindex gud-gdb-command-name ++ To run GDB in text command mode, like the other debuggers in Emacs, ++use @kbd{M-x gud-gdb}. You need to use text command mode to debug ++multiple programs within one Emacs session. ++ ++@menu ++* GDB-UI Layout:: Control the number of displayed buffers. ++* Source Buffers:: Use the mouse in the fringe/margin to ++ control your program. ++* Breakpoints Buffer:: A breakpoint control panel. ++* Stack Buffer:: Select a frame from the call stack. ++* Other GDB-UI Buffers:: Input/output, locals, registers, ++ assembler, threads and memory buffers. ++* Watch Expressions:: Monitor variable values in the speedbar. ++@end menu ++ ++@node GDB-UI Layout ++@subsubsection GDB User Interface Layout ++@cindex GDB User Interface layout ++ ++@vindex gdb-many-windows ++ If the variable @code{gdb-many-windows} is @code{nil} (the default ++value) then @kbd{M-x gdb} normally displays only the GUD buffer. ++However, if the variable @code{gdb-show-main} is also non-@code{nil}, ++it starts with two windows: one displaying the GUD buffer, and the ++other showing the source for the @code{main} function of the program ++you are debugging. ++ ++ If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} ++displays the following frame layout: ++ ++@smallexample ++@group +++--------------------------------+--------------------------------+ ++| GUD buffer (I/O of GDB) | Locals/Registers buffer | ++|--------------------------------+--------------------------------+ ++| Primary Source buffer | I/O buffer for debugged pgm | ++|--------------------------------+--------------------------------+ ++| Stack buffer | Breakpoints/thread buffer | +++--------------------------------+--------------------------------+ ++@end group ++@end smallexample ++ ++ However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O ++buffer does not appear and the primary source buffer occupies the full ++width of the frame. ++ ++@findex gdb-restore-windows ++ If you change the window layout, for example, while editing and ++re-compiling your program, then you can restore this standard window ++layout with the command @code{gdb-restore-windows}. ++ ++@findex gdb-many-windows ++ To switch between this standard layout and a simple layout ++containing just the GUD buffer and a source file, type @kbd{M-x ++gdb-many-windows}. ++ ++ You may also specify additional GDB-related buffers to display, ++either in the same frame or a different one. Select the buffers you ++want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames} ++sub-menus. If the menu-bar is unavailable, type @code{M-x ++gdb-display-@var{buffertype}-buffer} or @code{M-x ++gdb-frame-@var{buffertype}-buffer} respectively, where ++@var{buffertype} is the relevant buffer type, such as ++@samp{breakpoints}. Most of these buffers are read-only, and typing ++@kbd{q} in them kills them. ++ ++ When you finish debugging, kill the GUD buffer with @kbd{C-x k}, ++which will also kill all the buffers associated with the session. ++However you need not do this if, after editing and re-compiling your ++source code within Emacs, you wish continue debugging. When you ++restart execution, GDB will automatically find your new executable. ++Keeping the GUD buffer has the advantage of keeping the shell history ++as well as GDB's breakpoints. You do need to check that the ++breakpoints in recently edited source files are still in the right ++places. ++ ++@node Source Buffers ++@subsubsection Source Buffers ++@cindex GDB commands in Fringe ++ ++@c @findex gdb-mouse-set-clear-breakpoint ++@c @findex gdb-mouse-toggle-breakpoint ++Many GDB commands can be entered using key bindings or the tool bar but ++sometimes it is quicker to use the fringe. These commands either ++manipulate breakpoints or control program execution. When there is no ++fringe, you can use the margin but this is only present when the ++source file already has a breakpoint. ++ ++You can click @kbd{Mouse-1} in the fringe or display margin of a ++source buffer to set a breakpoint there and, on a graphical display, a ++red bullet will appear on that line. If a breakpoint already exists ++on that line, the same click will remove it. You can also enable or ++disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet. ++ ++A solid arrow in the left fringe of a source buffer indicates the line ++of the innermost frame where the debugged program has stopped. A ++hollow arrow indicates the current execution line of higher level ++frames. ++ ++If you drag the arrow in the fringe with @kbd{Mouse-1} ++(@code{gdb-mouse-until}), execution will continue to the line where ++you release the button, provided it is still in the same frame. ++Alternatively, you can click @kbd{Mouse-3} at some point in the fringe ++of this buffer and execution will advance to there. A similar command ++(@code{gdb-mouse-jump}) allows you to jump to a source line without ++executing the intermediate lines by clicking @kbd{C-Mouse-3}. This ++command allows you to go backwards which can be useful for running ++through code that has already executed, in order to examine its ++execution in more detail. ++ ++@table @kbd ++@item Mouse-1 ++Set or clear a breakpoint. ++ ++@item C-Mouse-1 ++Enable or disable a breakpoint. ++ ++@item Mouse-3 ++Continue execution to here. ++ ++@item C-Mouse-3 ++Jump to here. ++@end table ++ ++If the variable @code{gdb-find-source-frame} is non-@code{nil} and ++execution stops in a frame for which there is no source code e.g after ++an interrupt, then Emacs finds and displays the first frame further up ++stack for which there is source. If it is @code{nil} then the source ++buffer continues to display the last frame which maybe more useful, ++for example, when re-setting a breakpoint. ++ ++@node Breakpoints Buffer ++@subsubsection Breakpoints Buffer ++ ++ The breakpoints buffer shows the existing breakpoints, watchpoints and ++catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has ++these special commands, which mostly apply to the @dfn{current ++breakpoint}, the breakpoint which point is on. ++ ++@table @kbd ++@item @key{SPC} ++@kindex SPC @r{(GDB breakpoints buffer)} ++@findex gdb-toggle-breakpoint ++Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}). ++On a graphical display, this changes the color of a bullet in the ++margin of a source buffer at the relevant line. This is red when ++the breakpoint is enabled and grey when it is disabled. Text-only ++terminals correspondingly display a @samp{B} or @samp{b}. ++ ++@item D ++@kindex D @r{(GDB breakpoints buffer)} ++@findex gdb-delete-breakpoint ++Delete the current breakpoint (@code{gdb-delete-breakpoint}). ++ ++@item @key{RET} ++@kindex RET @r{(GDB breakpoints buffer)} ++@findex gdb-goto-breakpoint ++Visit the source line for the current breakpoint ++(@code{gdb-goto-breakpoint}). ++ ++@item Mouse-2 ++@kindex Mouse-2 @r{(GDB breakpoints buffer)} ++Visit the source line for the breakpoint you click on. ++@end table ++ ++When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer ++shares its window with the threads buffer. To switch from one to the ++other click with @kbd{mouse-1} on the relevant button in the header ++line. ++ ++@node Stack Buffer ++@subsubsection Stack Buffer ++ ++ The stack buffer displays a @dfn{call stack}, with one line for each ++of the nested subroutine calls (@dfn{stack frames}) now active in the ++program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}. ++ ++@findex gdb-frames-select ++An arrow in the fringe points to the selected frame or, if the fringe is ++not present, the number of the selected frame is displayed in reverse ++contrast. To select a frame in GDB, move point in the stack buffer to ++that stack frame and type @key{RET} (@code{gdb-frames-select}), or click ++@kbd{Mouse-2} on a stack frame. If the locals buffer is visible, ++selecting a stack frame updates it to display the local variables of the ++new frame. ++ ++@node Other GDB-UI Buffers ++@subsubsection Other Buffers ++ ++@table @asis ++@item Input/Output Buffer ++@vindex gdb-use-separate-io-buffer ++If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil}, ++the program being debugged takes its input and displays its output ++here. Otherwise it uses the GUD buffer for that. To toggle whether ++GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}. ++This takes effect when you next restart the program you are debugging. ++ ++The history and replay commands from Shell mode are available here, ++as are the commands to send signals to the debugged program. ++@xref{Shell Mode}. ++ ++@item Locals Buffer ++The locals buffer displays the values of local variables of the ++current frame for simple data types (@pxref{Frame Info, Frame Info, ++Information on a frame, gdb, The GNU debugger}). Press @key{RET} or ++click @kbd{Mouse-2} on the value if you want to edit it. ++ ++Arrays and structures display their type only. With GDB 6.4 or later, ++move point to their name and press @key{RET}, or alternatively click ++@kbd{Mouse-2} there, to examine their values. With earlier versions ++of GDB, use @kbd{Mouse-2} or @key{RET} on the type description ++(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}. ++ ++@item Registers Buffer ++@findex toggle-gdb-all-registers ++The registers buffer displays the values held by the registers ++(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or ++click @kbd{Mouse-2} on a register if you want to edit its value. ++With GDB 6.4 or later, recently changed register values display with ++@code{font-lock-warning-face}. With earlier versions of GDB, you can ++press @key{SPC} to toggle the display of floating point registers ++(@code{toggle-gdb-all-registers}). ++ ++@item Assembler Buffer ++The assembler buffer displays the current frame as machine code. An ++arrow points to the current instruction, and you can set and remove ++breakpoints as in a source buffer. Breakpoint icons also appear in ++the fringe or margin. ++ ++@item Threads Buffer ++@findex gdb-threads-select ++The threads buffer displays a summary of all threads currently in your ++program (@pxref{Threads, Threads, Debugging programs with multiple ++threads, gdb, The GNU debugger}). Move point to any thread in the ++list and press @key{RET} to select it (@code{gdb-threads-select}) and ++display the associated source in the primary source buffer. ++Alternatively, click @kbd{Mouse-2} on a thread to select it. If the ++locals buffer is visible, its contents update to display the variables ++that are local in the new thread. ++ ++When there is more than one main thread and the threads buffer is ++present, Emacs displays the selected thread number in the mode line of ++many of the GDB-UI Buffers. ++ ++@item Memory Buffer ++The memory buffer lets you examine sections of program memory ++(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). ++Click @kbd{Mouse-1} on the appropriate part of the header line to ++change the starting address or number of data items that the buffer ++displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click ++@kbd{Mouse-3} on the header line to select the display format or unit ++size for these data items. ++@end table ++ ++When @code{gdb-many-windows} is non-@code{nil}, the threads buffer ++shares its window with the breakpoints buffer, and the locals buffer ++with the registers buffer. To switch from one to the other click with ++@kbd{mouse-1} on the relevant button in the header line. ++ ++@node Watch Expressions ++@subsubsection Watch Expressions ++@cindex Watching expressions in GDB ++ ++@findex gud-watch ++@kindex C-x C-a C-w @r{(GUD)} ++ If you want to see how a variable changes each time your program ++stops, move point into the variable name and click on the watch icon ++in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you ++specify a prefix argument, you can enter the variable name in the ++minibuffer. ++ ++ Each watch expression is displayed in the speedbar. Complex data ++types, such as arrays, structures and unions are represented in a tree ++format. Leaves and simple data types show the name of the expression ++and its value and, when the speedbar frame is selected, display the ++type as a tooltip. Higher levels show the name, type and address ++value for pointers and just the name and type otherwise. Root expressions ++also display the frame address as a tooltip to help identify the frame ++in which they were defined. ++ ++ To expand or contract a complex data type, click @kbd{Mouse-2} or ++press @key{SPC} on the tag to the left of the expression. Emacs asks ++for confirmation before expanding the expression if its number of ++immediate children exceeds the value of the variable ++@code{gdb-max-children}. ++ ++@kindex D @r{(GDB speedbar)} ++@findex gdb-var-delete ++ To delete a complex watch expression, move point to the root ++expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}). ++ ++@kindex RET @r{(GDB speedbar)} ++@findex gdb-edit-value ++ To edit a variable with a simple data type, or a simple element of a ++complex data type, move point there in the speedbar and type @key{RET} ++(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to ++edit it. Either way, this reads the new value using the minibuffer. ++ ++@vindex gdb-show-changed-values ++ If you set the variable @code{gdb-show-changed-values} to ++non-@code{nil} (the default value), Emacs uses ++@code{font-lock-warning-face} to highlight values that have recently ++changed and @code{shadow} face to make variables which have gone out of ++scope less noticeable. When a variable goes out of scope you can't ++edit its value. ++ ++@vindex gdb-delete-out-of-scope ++ If the variable @code{gdb-delete-out-of-scope} is non-@code{nil} ++(the default value), Emacs automatically deletes watch expressions ++which go out of scope. Sometimes, when re-entering the same function, ++it may be useful to set this value to @code{nil} so that you don't ++need to recreate the watch expression. ++ ++@vindex gdb-use-colon-colon-notation ++ If the variable @code{gdb-use-colon-colon-notation} is ++non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}} ++format. This allows the user to display watch expressions which share ++the same variable name. The default value is @code{nil}. ++ ++@vindex gdb-speedbar-auto-raise ++To automatically raise the speedbar every time the display of watch ++expressions updates, set @code{gdb-speedbar-auto-raise} to ++non-@code{nil}. This can be useful if you are debugging with a full ++screen Emacs frame. ++ ++@node Executing Lisp ++@section Executing Lisp Expressions ++ ++ Emacs has several different major modes for Lisp and Scheme. They are ++the same in terms of editing commands, but differ in the commands for ++executing Lisp expressions. Each mode has its own purpose. ++ ++@table @asis ++@item Emacs-Lisp mode ++The mode for editing source files of programs to run in Emacs Lisp. ++This mode defines @kbd{C-M-x} to evaluate the current defun. ++@xref{Lisp Libraries}. ++@item Lisp Interaction mode ++The mode for an interactive session with Emacs Lisp. It defines ++@kbd{C-j} to evaluate the sexp before point and insert its value in the ++buffer. @xref{Lisp Interaction}. ++@item Lisp mode ++The mode for editing source files of programs that run in Lisps other ++than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun ++to an inferior Lisp process. @xref{External Lisp}. ++@item Inferior Lisp mode ++The mode for an interactive session with an inferior Lisp process. ++This mode combines the special features of Lisp mode and Shell mode ++(@pxref{Shell Mode}). ++@item Scheme mode ++Like Lisp mode but for Scheme programs. ++@item Inferior Scheme mode ++The mode for an interactive session with an inferior Scheme process. ++@end table ++ ++ Most editing commands for working with Lisp programs are in fact ++available globally. @xref{Programs}. ++ ++@node Lisp Libraries ++@section Libraries of Lisp Code for Emacs ++@cindex libraries ++@cindex loading Lisp code ++ ++ Lisp code for Emacs editing commands is stored in files whose names ++conventionally end in @file{.el}. This ending tells Emacs to edit them in ++Emacs-Lisp mode (@pxref{Executing Lisp}). ++ ++@cindex byte code ++ Emacs Lisp code can be compiled into byte-code, which loads faster, ++takes up less space, and executes faster. @xref{Byte Compilation,, ++Byte Compilation, elisp, the Emacs Lisp Reference Manual}. By ++convention, the compiled code for a library goes in a separate file ++whose name ends in @samp{.elc}. Thus, the compiled code for ++@file{foo.el} goes in @file{foo.elc}. ++ ++@findex load-file ++ To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This ++command reads a file name using the minibuffer and then executes the ++contents of that file as Lisp code. It is not necessary to visit the ++file first; in any case, this command reads the file as found on disk, ++not text in an Emacs buffer. ++ ++@findex load ++@findex load-library ++ Once a file of Lisp code is installed in the Emacs Lisp library ++directories, users can load it using @kbd{M-x load-library}. Programs ++can load it by calling @code{load}, a more primitive function that is ++similar but accepts some additional arguments. ++ ++ @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it ++searches a sequence of directories and tries three file names in each ++directory. Suppose your argument is @var{lib}; the three names are ++@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just ++@file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention ++the result of compiling @file{@var{lib}.el}; it is better to load the ++compiled file, since it will load and run faster. ++ ++ If @code{load-library} finds that @file{@var{lib}.el} is newer than ++@file{@var{lib}.elc} file, it issues a warning, because it's likely ++that somebody made changes to the @file{.el} file and forgot to ++recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is ++because people often leave unfinished edits the source file, and don't ++recompile it until they think it is ready to use. ++ ++@vindex load-path ++ The variable @code{load-path} specifies the sequence of directories ++searched by @kbd{M-x load-library}. Its value should be a list of ++strings that are directory names; in addition, @code{nil} in this list ++stands for the current default directory. (Generally, it is not a ++good idea to put @code{nil} in the list; if you find yourself wishing ++that @code{nil} were in the list, most likely what you really want is ++to do @kbd{M-x load-file} this once.) ++ ++ The default value of @code{load-path} is a list of directories where ++the Lisp code for Emacs itself is stored. If you have libraries of ++your own, put them in a single directory and add that directory to ++@code{load-path}, by adding a line like this to your init file ++(@pxref{Init File}): ++ ++@example ++(add-to-list 'load-path "/path/to/lisp/libraries") ++@end example ++ ++@cindex autoload ++ Some commands are @dfn{autoloaded}: when you run them, Emacs will ++automatically load the associated library first. For instance, the ++@code{compile} and @code{compilation-mode} commands ++(@pxref{Compilation}) are autoloaded; if you call either command, ++Emacs automatically loads the @code{compile} library. In contrast, ++the command @code{recompile} is not autoloaded, so it is unavailable ++until you load the @code{compile} library. ++ ++@vindex load-dangerous-libraries ++@cindex Lisp files byte-compiled by XEmacs ++ By default, Emacs refuses to load compiled Lisp files which were ++compiled with XEmacs, a modified versions of Emacs---they can cause ++Emacs to crash. Set the variable @code{load-dangerous-libraries} to ++@code{t} if you want to try loading them. ++ ++@node Lisp Eval ++@section Evaluating Emacs Lisp Expressions ++@cindex Emacs-Lisp mode ++@cindex mode, Emacs-Lisp ++ ++@findex emacs-lisp-mode ++ Lisp programs intended to be run in Emacs should be edited in ++Emacs-Lisp mode; this happens automatically for file names ending in ++@file{.el}. By contrast, Lisp mode itself is used for editing Lisp ++programs intended for other Lisp systems. To switch to Emacs-Lisp mode ++explicitly, use the command @kbd{M-x emacs-lisp-mode}. ++ ++ For testing of Lisp programs to run in Emacs, it is often useful to ++evaluate part of the program as it is found in the Emacs buffer. For ++example, after changing the text of a Lisp function definition, ++evaluating the definition installs the change for future calls to the ++function. Evaluation of Lisp expressions is also useful in any kind of ++editing, for invoking noninteractive functions (functions that are ++not commands). ++ ++@table @kbd ++@item M-: ++Read a single Lisp expression in the minibuffer, evaluate it, and print ++the value in the echo area (@code{eval-expression}). ++@item C-x C-e ++Evaluate the Lisp expression before point, and print the value in the ++echo area (@code{eval-last-sexp}). ++@item C-M-x ++Evaluate the defun containing or after point, and print the value in ++the echo area (@code{eval-defun}). ++@item M-x eval-region ++Evaluate all the Lisp expressions in the region. ++@item M-x eval-buffer ++Evaluate all the Lisp expressions in the buffer. ++@end table ++ ++@ifinfo ++@c This uses ``colon'' instead of a literal `:' because Info cannot ++@c cope with a `:' in a menu ++@kindex M-@key{colon} ++@end ifinfo ++@ifnotinfo ++@kindex M-: ++@end ifnotinfo ++@findex eval-expression ++ @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating ++a Lisp expression interactively. It reads the expression using the ++minibuffer, so you can execute any expression on a buffer regardless of ++what the buffer contains. When the expression is evaluated, the current ++buffer is once again the buffer that was current when @kbd{M-:} was ++typed. ++ ++@kindex C-M-x @r{(Emacs-Lisp mode)} ++@findex eval-defun ++ In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command ++@code{eval-defun}, which parses the defun containing or following point ++as a Lisp expression and evaluates it. The value is printed in the echo ++area. This command is convenient for installing in the Lisp environment ++changes that you have just made in the text of a function definition. ++ ++ @kbd{C-M-x} treats @code{defvar} expressions specially. Normally, ++evaluating a @code{defvar} expression does nothing if the variable it ++defines already has a value. But @kbd{C-M-x} unconditionally resets the ++variable to the initial value specified in the @code{defvar} expression. ++@code{defcustom} expressions are treated similarly. ++This special feature is convenient for debugging Lisp programs. ++Typing @kbd{C-M-x} on a @code{defface} expression reinitializes ++the face according to the @code{defface} specification. ++ ++@kindex C-x C-e ++@findex eval-last-sexp ++ The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp ++expression preceding point in the buffer, and displays the value in the ++echo area. It is available in all major modes, not just Emacs-Lisp ++mode. It does not treat @code{defvar} specially. ++ ++ When the result of an evaluation is an integer, you can type ++@kbd{C-x C-e} a second time to display the value of the integer result ++in additional formats (octal, hexadecimal, and character). ++ ++ If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it ++inserts the value into the current buffer at point, rather than ++displaying it in the echo area. The argument's value does not matter. ++@kbd{C-M-x} with a numeric argument instruments the function ++definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}). ++ ++@findex eval-region ++@findex eval-buffer ++ The most general command for evaluating Lisp expressions from a buffer ++is @code{eval-region}. @kbd{M-x eval-region} parses the text of the ++region as one or more Lisp expressions, evaluating them one by one. ++@kbd{M-x eval-buffer} is similar but evaluates the entire ++buffer. This is a reasonable way to install the contents of a file of ++Lisp code that you are ready to test. Later, as you find bugs and ++change individual functions, use @kbd{C-M-x} on each function that you ++change. This keeps the Lisp world in step with the source file. ++ ++@vindex eval-expression-print-level ++@vindex eval-expression-print-length ++@vindex eval-expression-debug-on-error ++ The two customizable variables @code{eval-expression-print-level} and ++@code{eval-expression-print-length} control the maximum depth and length ++of lists to print in the result of the evaluation commands before ++abbreviating them. @code{eval-expression-debug-on-error} controls ++whether evaluation errors invoke the debugger when these commands are ++used; its default is @code{t}. ++ ++@node Lisp Interaction ++@section Lisp Interaction Buffers ++ ++ When Emacs starts up, it contains a buffer named @samp{*scratch*}, ++which is provided for evaluating Lisp expressions interactively inside ++Emacs. Its major mode is Lisp Interaction mode. ++ ++@findex eval-print-last-sexp ++@kindex C-j @r{(Lisp Interaction mode)} ++ The simplest way to use the @samp{*scratch*} buffer is to insert ++Lisp expressions and type @kbd{C-j} (@code{eval-print-last-sexp}) ++after each expression. This command reads the Lisp expression before ++point, evaluates it, and inserts the value in printed representation ++before point. The result is a complete typescript of the expressions ++you have evaluated and their values. ++ ++@vindex initial-scratch-message ++ At startup, the @samp{*scratch*} buffer contains a short message, in ++the form of a Lisp comment, that explains what it is for. This ++message is controlled by the variable @code{initial-scratch-message}, ++which should be either a string or @code{nil}. If you set it to the ++empty string, or @code{nil}, the initial message is suppressed. ++ ++@findex lisp-interaction-mode ++ All other commands in Lisp Interaction mode are the same as in Emacs ++Lisp mode. You can enable Lisp Interaction mode by typing @kbd{M-x ++lisp-interaction-mode}. ++ ++@findex ielm ++ An alternative way of evaluating Emacs Lisp expressions interactively ++is to use Inferior Emacs-Lisp mode, which provides an interface rather ++like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp ++expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer ++which uses this mode. For more information see that command's ++documentation. ++ ++@node External Lisp ++@section Running an External Lisp ++ ++ Emacs has facilities for running programs in other Lisp systems. You can ++run a Lisp process as an inferior of Emacs, and pass expressions to it to ++be evaluated. You can also pass changed function definitions directly from ++the Emacs buffers in which you edit the Lisp programs to the inferior Lisp ++process. ++ ++@findex run-lisp ++@vindex inferior-lisp-program ++@kindex C-x C-z ++ To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs ++the program named @code{lisp}, the same program you would run by typing ++@code{lisp} as a shell command, with both input and output going through ++an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal ++output'' from Lisp will go into the buffer, advancing point, and any ++``terminal input'' for Lisp comes from text in the buffer. (You can ++change the name of the Lisp executable file by setting the variable ++@code{inferior-lisp-program}.) ++ ++ To give input to Lisp, go to the end of the buffer and type the input, ++terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp ++mode, which combines the special characteristics of Lisp mode with most ++of the features of Shell mode (@pxref{Shell Mode}). The definition of ++@key{RET} to send a line to a subprocess is one of the features of Shell ++mode. ++ ++@findex lisp-mode ++ For the source files of programs to run in external Lisps, use Lisp ++mode. You can switch to this mode with @kbd{M-x lisp-mode}, and it is ++used automatically for files whose names end in @file{.l}, ++@file{.lsp}, or @file{.lisp}. ++ ++@kindex C-M-x @r{(Lisp mode)} ++@findex lisp-eval-defun ++ When you edit a function in a Lisp program you are running, the easiest ++way to send the changed definition to the inferior Lisp process is the key ++@kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun}, ++which finds the defun around or following point and sends it as input to ++the Lisp process. (Emacs can send input to any inferior process regardless ++of what buffer is current.) ++ ++ Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing ++programs to be run in another Lisp system) and Emacs-Lisp mode (for ++editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in ++both modes it has the effect of installing the function definition ++that point is in, but the way of doing so is different according to ++where the relevant Lisp environment is found. ++ ++ ++@ignore ++ arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed ++@end ignore +diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi +new file mode 100644 +index 0000000..38809ef +--- /dev/null ++++ b/doc/emacs/cal-xtra.texi +@@ -0,0 +1,864 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@c This file is included either in emacs-xtra.texi (when producing the ++@c printed version) or in the main Emacs manual (for the on-line version). ++ ++@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. ++@node Advanced Calendar/Diary Usage ++@section Customizing the Calendar and Diary ++ ++ There are many customizations that you can use to make the calendar and ++diary suit your personal tastes. ++ ++@menu ++* Calendar Customizing:: Calendar layout and hooks. ++* Holiday Customizing:: Defining your own holidays. ++* Date Display Format:: Changing the format. ++* Time Display Format:: Changing the format. ++* Diary Customizing:: Defaults you can set. ++* Non-Gregorian Diary:: Diary entries based on other calendars. ++* Fancy Diary Display:: Enhancing the diary display, sorting entries, ++ using included diary files. ++* Sexp Diary Entries:: Fancy things you can do. ++@end menu ++ ++@node Calendar Customizing ++@subsection Customizing the Calendar ++ ++@vindex calendar-intermonth-text ++@cindex calendar layout ++@cindex calendar week numbers ++ The calendar display unfortunately cannot be changed from three ++months, but you can customize the whitespace used by setting the ++variables: @code{calendar-left-margin}, ++@code{calendar-day-header-width}, @code{calendar-day-digit-width}, ++@code{calendar-column-width}, and @code{calendar-intermonth-spacing}. ++To display text @emph{between} the months, for example week numbers, ++customize the variables @code{calendar-intermonth-header} and ++@code{calendar-intermonth-text} as described in their documentation. ++ ++@vindex calendar-holiday-marker ++@vindex diary-entry-marker ++@vindex calenday-today-marker ++ The variable @code{calendar-holiday-marker} specifies how to mark a ++date as being a holiday. Its value may be a single-character string to ++insert next to the date, or a face name to use for displaying the date. ++Likewise, the variable @code{diary-entry-marker} specifies how to mark a ++date that has diary entries, and @code{calenday-today-marker} is used by ++the function @code{calendar-mark-today} to mark today's date. By ++default, the calendar uses faces named @code{holiday}, @code{diary}, and ++@code{calendar-today} for these purposes. ++ ++@vindex calendar-load-hook ++ The variable @code{calendar-load-hook} is a normal hook run when the ++calendar package is first loaded (before actually starting to display ++the calendar). ++ ++@vindex calendar-initial-window-hook ++ Starting the calendar runs the normal hook ++@code{calendar-initial-window-hook}. Recomputation of the calendar ++display does not run this hook. But if you leave the calendar with the ++@kbd{q} command and reenter it, the hook runs again.@refill ++ ++@vindex calendar-today-visible-hook ++@findex calendar-star-date ++ The variable @code{calendar-today-visible-hook} is a normal hook run ++after the calendar buffer has been prepared with the calendar when the ++current date is visible in the window. One use of this hook is to ++mark today's date; to do that use either of the functions ++@code{calendar-mark-today} or @code{calendar-star-date}: ++ ++@findex calendar-mark-today ++@smallexample ++(add-hook 'calendar-today-visible-hook 'calendar-mark-today) ++@end smallexample ++ ++@vindex calendar-today-invisible-hook ++@noindent ++ A similar normal hook, @code{calendar-today-invisible-hook} is run if ++the current date is @emph{not} visible in the window. ++ ++@vindex calendar-move-hook ++ Each of the calendar cursor motion commands runs the hook ++@code{calendar-move-hook} after it moves the cursor. ++ ++@node Holiday Customizing ++@subsection Customizing the Holidays ++ ++@vindex calendar-holidays ++@vindex holiday-oriental-holidays ++@vindex holiday-solar-holidays ++ Emacs knows about holidays defined by entries on one of several lists. ++The lists of holidays that Emacs uses are for ++general holidays (@code{holiday-general-holidays}), ++local holidays (@code{holiday-local-holidays}), ++sun- and moon-related holidays (@code{holiday-solar-holidays}), ++Baha'i holidays (@code{holiday-bahai-holidays}), ++Christian holidays (@code{holiday-christian-holidays}), ++Hebrew (Jewish) holidays (@code{holiday-hebrew-holidays}), ++Islamic (Muslim) holidays (@code{holiday-islamic-holidays}), ++Oriental holidays (@code{holiday-oriental-holidays}), ++and other holidays (@code{holiday-other-holidays}). ++ ++You can customize these lists of holidays to your own needs, deleting or ++adding holidays as described below. Set any of them to @code{nil} to ++eliminate the associated holidays. ++ ++@vindex holiday-general-holidays ++ The general holidays are, by default, holidays common throughout the ++United States. ++ ++@vindex holiday-local-holidays ++ There are no default local holidays, but your site may supply some. ++ ++@vindex holiday-bahai-holidays ++@vindex holiday-christian-holidays ++@vindex holiday-hebrew-holidays ++@vindex holiday-islamic-holidays ++@vindex calendar-bahai-all-holidays-flag ++@vindex calendar-christian-all-holidays-flag ++@vindex calendar-hebrew-all-holidays-flag ++@vindex calendar-islamic-all-holidays-flag ++ By default, Emacs does not include all the holidays of the religions ++that it knows, only those commonly found in secular calendars. For a ++more extensive collection of religious holidays, you can set any (or ++all) of the variables @code{calendar-bahai-all-holidays-flag}, ++@code{calendar-christian-all-holidays-flag}, ++@code{calendar-hebrew-all-holidays-flag}, or ++@code{calendar-islamic-all-holidays-flag} to @code{t}. ++ ++@vindex holiday-other-holidays ++ You can set the variable @code{holiday-other-holidays} to any list of ++holidays. This list, normally empty, is intended for individual use. ++ ++@cindex holiday forms ++ Each of the holiday variables is a list of @dfn{holiday forms}, each ++form describing a holiday (or sometimes a list of holidays). ++ ++ Here is a table of the possible kinds of holiday form. Day numbers ++and month numbers count starting from 1, but ``dayname'' numbers ++count Sunday as 0. The element @var{string} is always the ++description of the holiday, as a string. ++ ++@table @code ++@item (holiday-fixed @var{month} @var{day} @var{string}) ++A fixed date on the Gregorian calendar. ++ ++@item (holiday-float @var{month} @var{dayname} @var{k} @var{string} ++ &optional @var{day}) ++The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on) ++after or before Gregorian date @var{month}, @var{day}. Negative @var{k} ++means count back from the end of the month. Optional @var{day} defaults ++to 1 if @var{k} is positive, and the last day of @var{month} otherwise. ++ ++@item (holiday-chinese @var{month} @var{day} @var{string}) ++A fixed date on the Chinese calendar. ++ ++@item (holiday-hebrew @var{month} @var{day} @var{string}) ++A fixed date on the Hebrew calendar. ++ ++@item (holiday-islamic @var{month} @var{day} @var{string}) ++A fixed date on the Islamic calendar. ++ ++@item (holiday-julian @var{month} @var{day} @var{string}) ++A fixed date on the Julian calendar. ++ ++@item (holiday-sexp @var{sexp} @var{string}) ++A date calculated by the Lisp expression @var{sexp}. The expression ++should use the variable @code{year} to compute and return the date of a ++holiday in the form of a list @code{(@var{month} @var{day} @var{year})}, ++or @code{nil} if the holiday doesn't happen this year. ++ ++@item (if @var{condition} @var{holiday-form}) ++A holiday that happens only if @var{condition} is true. ++ ++@item (@var{function} @r{[}@var{args}@r{]}) ++A list of dates calculated by the function @var{function}, called with ++arguments @var{args}. ++@end table ++ ++ For example, suppose you want to add Bastille Day, celebrated in ++France on July 14 (i.e., the fourteenth day of the seventh month). You ++can do this as follows: ++ ++@smallexample ++(setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) ++@end smallexample ++ ++ Many holidays occur on a specific day of the week, at a specific time ++of month. Here is a holiday form describing Hurricane Supplication Day, ++celebrated in the Virgin Islands on the fourth Monday in August: ++ ++@smallexample ++(holiday-float 8 1 4 "Hurricane Supplication Day") ++@end smallexample ++ ++@noindent ++Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, ++Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in ++the month (1 specifies the first occurrence, 2 the second occurrence, ++@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and ++so on). ++ ++ You can specify holidays that occur on fixed days of the Baha'i, ++Chinese, Hebrew, Islamic, and Julian calendars too. For example, ++ ++@smallexample ++(setq other-holidays ++ '((holiday-hebrew 10 2 "Last day of Hanukkah") ++ (holiday-islamic 3 12 "Mohammed's Birthday") ++ (holiday-julian 4 2 "Jefferson's Birthday"))) ++@end smallexample ++ ++@noindent ++adds the last day of Hanukkah (since the Hebrew months are numbered with ++1 starting from Nisan), the Islamic feast celebrating Mohammed's ++birthday (since the Islamic months are numbered from 1 starting with ++Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the ++Julian calendar. ++ ++ To include a holiday conditionally, use either Emacs Lisp's @code{if} ++or the @code{holiday-sexp} form. For example, American presidential ++elections occur on the first Tuesday after the first Monday in November ++of years divisible by 4: ++ ++@smallexample ++(holiday-sexp '(if (zerop (% year 4)) ++ (calendar-gregorian-from-absolute ++ (1+ (calendar-dayname-on-or-before ++ 1 (+ 6 (calendar-absolute-from-gregorian ++ (list 11 1 year))))))) ++ "US Presidential Election") ++@end smallexample ++ ++@noindent ++or ++ ++@smallexample ++(if (zerop (% displayed-year 4)) ++ (holiday-fixed 11 ++ (calendar-extract-day ++ (calendar-gregorian-from-absolute ++ (1+ (calendar-dayname-on-or-before ++ 1 (+ 6 (calendar-absolute-from-gregorian ++ (list 11 1 displayed-year))))))) ++ "US Presidential Election")) ++@end smallexample ++ ++ Some holidays just don't fit into any of these forms because special ++calculations are involved in their determination. In such cases you ++must write a Lisp function to do the calculation. To include eclipses, ++for example, add @code{(eclipses)} to @code{holiday-other-holidays} ++and write an Emacs Lisp function @code{eclipses} that returns a ++(possibly empty) list of the relevant Gregorian dates among the range ++visible in the calendar window, with descriptive strings, like this: ++ ++@smallexample ++(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) ++@end smallexample ++ ++@node Date Display Format ++@subsection Date Display Format ++@vindex calendar-date-display-form ++ ++ You can customize the manner of displaying dates in the diary, in mode ++lines, and in messages by setting @code{calendar-date-display-form}. ++This variable holds a list of expressions that can involve the variables ++@code{month}, @code{day}, and @code{year}, which are all numbers in ++string form, and @code{monthname} and @code{dayname}, which are both ++alphabetic strings. In the American style, the default value of this ++list is as follows: ++ ++@smallexample ++((if dayname (concat dayname ", ")) monthname " " day ", " year) ++@end smallexample ++ ++@noindent ++while in the European style this value is the default: ++ ++@smallexample ++((if dayname (concat dayname ", ")) day " " monthname " " year) ++@end smallexample ++ ++@noindent ++The default ISO date representation is: ++ ++@smallexample ++((format "%s-%.2d-%.2d" year (string-to-number month) ++ (string-to-number day))) ++@end smallexample ++ ++@noindent ++This specifies a typical American format: ++ ++@smallexample ++(month "/" day "/" (substring year -2)) ++@end smallexample ++ ++@node Time Display Format ++@subsection Time Display Format ++@vindex calendar-time-display-form ++ ++ The calendar and diary by default display times of day in the ++conventional American style with the hours from 1 through 12, minutes, ++and either @samp{am} or @samp{pm}. If you prefer the European style, ++also known in the US as military, in which the hours go from 00 to 23, ++you can alter the variable @code{calendar-time-display-form}. This ++variable is a list of expressions that can involve the variables ++@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all ++numbers in string form, and @code{am-pm} and @code{time-zone}, which are ++both alphabetic strings. The default value is: ++ ++@smallexample ++(12-hours ":" minutes am-pm ++ (if time-zone " (") time-zone (if time-zone ")")) ++@end smallexample ++ ++@noindent ++Here is a value that provides European style times: ++ ++@smallexample ++(24-hours ":" minutes ++ (if time-zone " (") time-zone (if time-zone ")")) ++@end smallexample ++ ++Note that few calendar functions return a time of day (at present, only ++solar functions). ++ ++@node Diary Customizing ++@subsection Customizing the Diary ++ ++@vindex diary-show-holidays-flag ++ Ordinarily, the mode line of the diary window indicates any holidays ++that fall on the date of the diary entries. The process of checking for ++holidays can be slow, depending on the defined holidays. In that case, ++setting @code{diary-show-holidays-flag} to @code{nil} will speed up the ++diary display. ++ ++@vindex diary-number-of-entries ++ The variable @code{diary-number-of-entries} controls the number of ++days of diary entries to be displayed at one time. It affects the ++initial display when @code{calendar-view-diary-initially-flag} is ++@code{t}, as well as the command @kbd{M-x diary}. For example, a value ++of 1 (the default) displays only the current day's diary entries, ++whereas a value of 2 will also show the next day's entries. The value ++can also be a vector of seven integers: for example, if the value is ++@code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday, the ++current date's and the next day's diary entries appear Monday through ++Thursday, Friday through Monday's entries appear on Friday, while on ++Saturday only that day's entries appear. ++ ++@vindex diary-print-entries-hook ++@findex diary-print-entries ++ The variable @code{diary-print-entries-hook} is a normal hook run ++after preparation of a temporary buffer containing just the diary ++entries currently visible in the diary buffer. (The other, irrelevant ++diary entries are really absent from the temporary buffer; in the diary ++buffer, they are merely hidden.) The default value of this hook does ++the printing with the command @code{lpr-buffer}. If you want to use a ++different command to do the printing, just change the value of this ++hook. Other uses might include, for example, rearranging the lines into ++order by day and time. ++ ++@vindex diary-date-forms ++ You can customize the form of dates in your diary file by setting the ++variable @code{diary-date-forms}. This variable is a list of patterns ++for recognizing a date. Each date pattern is a list whose elements may ++be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs ++Lisp Reference Manual}) or the symbols @code{month}, @code{day}, ++@code{year}, @code{monthname}, and @code{dayname}. All these elements ++serve as patterns that match certain kinds of text in the diary file. ++In order for the date pattern, as a whole, to match, all of its elements ++must match consecutively. ++ ++ A regular expression in a date pattern matches in its usual fashion, ++using the standard syntax table altered so that @samp{*} is a word ++constituent. ++ ++ The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, ++and @code{dayname} match the month number, day number, year number, ++month name, and day name of the date being considered. The symbols that ++match numbers allow leading zeros; those that match names allow ++capitalization and abbreviation (as specified by ++@code{calendar-month-abbrev-array} and ++@code{calendar-day-abbrev-array}). All the symbols can match @samp{*}; ++since @samp{*} in a diary entry means ``any day'', ``any month'', and so ++on, it should match regardless of the date being considered. ++ ++ The default value of @code{diary-date-forms} in the American style is ++provided by @code{diary-american-date-forms}: ++ ++@example ++((month "/" day "[^/0-9]") ++ (month "/" day "/" year "[^0-9]") ++ (monthname " *" day "[^,0-9]") ++ (monthname " *" day ", *" year "[^0-9]") ++ (dayname "\\W")) ++@end example ++ ++@noindent ++Other default styles are provided by @code{diary-european-date-forms} ++and @code{diary-iso-date-forms}. ++ ++ The date patterns in the list must be @emph{mutually exclusive} and ++must not match any portion of the diary entry itself, just the date and ++one character of whitespace. If, to be mutually exclusive, the pattern ++must match a portion of the diary entry text---beyond the whitespace ++that ends the date---then the first element of the date pattern ++@emph{must} be @code{backup}. This causes the date recognizer to back ++up to the beginning of the current word of the diary entry, after ++finishing the match. Even if you use @code{backup}, the date pattern ++must absolutely not match more than a portion of the first word of the ++diary entry. For example, the default value of ++@code{diary-european-date-forms} is: ++ ++@example ++((day "/" month "[^/0-9]") ++ (day "/" month "/" year "[^0-9]") ++ (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)") ++ (day " *" monthname " *" year "[^0-9]") ++ (dayname "\\W")) ++@end example ++ ++@noindent ++Notice the use of @code{backup} in the third pattern, because it needs ++to match part of a word beyond the date itself to distinguish it from ++the fourth pattern. ++ ++@node Non-Gregorian Diary ++@subsection Diary Entries Using non-Gregorian Calendars ++ ++ As well as entries based on the standard Gregorian calendar, your ++diary can have entries based on Baha'i, Hebrew, or Islamic dates. ++Recognition of such entries can be time-consuming, however, and since ++most people don't use them, you must explicitly enable their use. If ++you want the diary to recognize Hebrew-date diary entries, for example, ++you must do this: ++ ++@vindex diary-nongregorian-listing-hook ++@vindex diary-nongregorian-marking-hook ++@findex diary-hebrew-list-entries ++@findex diary-hebrew-mark-entries ++@findex diary-islamic-list-entries ++@findex diary-islamic-mark-entries ++@findex diary-bahai-list-entries ++@findex diary-bahai-mark-entries ++@smallexample ++(add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries) ++(add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries) ++@end smallexample ++ ++@noindent ++Similarly, for Islamic and Baha'i entries, add ++@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or ++@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}. ++ ++@vindex diary-bahai-entry-symbol ++@vindex diary-hebrew-entry-symbol ++@vindex diary-islamic-entry-symbol ++ These diary entries have the same formats as Gregorian-date diary ++entries; except that @code{diary-bahai-entry-symbol} (default @samp{B}) ++must precede a Baha'i date, @code{diary-hebrew-entry-symbol} (default ++@samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default ++@samp{I}) an Islamic date. Moreover, non-Gregorian month names may not ++be abbreviated (because the first three letters are often not unique). ++For example, a diary entry for the Hebrew date Heshvan 25 could look ++like this: ++ ++@smallexample ++HHeshvan 25 Happy Hebrew birthday! ++@end smallexample ++ ++@noindent ++and would appear in the diary for any date that corresponds to Heshvan 25 ++on the Hebrew calendar. And here is an Islamic-date diary entry that matches ++Dhu al-Qada 25: ++ ++@smallexample ++IDhu al-Qada 25 Happy Islamic birthday! ++@end smallexample ++ ++ As with Gregorian-date diary entries, non-Gregorian entries are ++nonmarking if preceded by @code{diary-nonmarking-symbol} (default ++@samp{&}). ++ ++ Here is a table of commands used in the calendar to create diary ++entries that match the selected date and other dates that are similar in ++the Baha'i, Hebrew, or Islamic calendars: ++ ++@table @kbd ++@item i h d ++@code{diary-hebrew-insert-entry} ++@item i h m ++@code{diary-hebrew-insert-monthly-entry} ++@item i h y ++@code{diary-hebrew-insert-yearly-entry} ++@item i i d ++@code{diary-islamic-insert-entry} ++@item i i m ++@code{diary-islamic-insert-monthly-entry} ++@item i i y ++@code{diary-islamic-insert-yearly-entry} ++@item i B d ++@code{diary-bahai-insert-entry} ++@item i B m ++@code{diary-bahai-insert-monthly-entry} ++@item i B y ++@code{diary-bahai-insert-yearly-entry} ++@end table ++ ++@findex diary-hebrew-insert-entry ++@findex diary-hebrew-insert-monthly-entry ++@findex diary-hebrew-insert-yearly-entry ++@findex diary-islamic-insert-entry ++@findex diary-islamic-insert-monthly-entry ++@findex diary-islamic-insert-yearly-entry ++@findex diary-bahai-insert-entry ++@findex diary-bahai-insert-monthly-entry ++@findex diary-bahai-insert-yearly-entry ++ These commands work much like the corresponding commands for ordinary ++diary entries: they apply to the date that point is on in the calendar ++window, and what they do is insert just the date portion of a diary ++entry at the end of your diary file. You must then insert the rest of ++the diary entry. The basic commands add an entry for the specific ++non-Gregorian date, the @samp{monthly} commands for the given ++non-Gregorian day-within-month in every month, and the @samp{yearly} ++commands for the given non-Gregorian day and month in every year. ++ ++@node Fancy Diary Display ++@subsection Fancy Diary Display ++@vindex diary-display-function ++@findex diary-simple-display ++@findex diary-fancy-display ++@cindex diary buffer ++ ++ Diary display works by preparing the diary buffer and then running the ++function specified by the variable @code{diary-display-function}. The ++default value (@code{diary-simple-display}) hides the irrelevant diary ++entries and then displays the buffer. The alternative ++@code{diary-fancy-display} displays diary entries and holidays by ++copying them into a special buffer that exists only for the sake of ++display. Copying to a separate buffer provides an opportunity to change ++the displayed text to make it prettier---for example, to sort the ++entries by the dates they apply to. ++ ++ As with simple diary display, you can print a hard copy of the buffer ++with @code{diary-print-entries}. To print a hard copy of a day-by-day ++diary for a week, position point on Sunday of that week, type ++@kbd{7 d}, and then do @kbd{M-x diary-print-entries}. As usual, the ++inclusion of the holidays slows down the display slightly; you can speed ++things up by setting the variable @code{diary-show-holidays-flag} to ++@code{nil}. ++ ++@vindex diary-list-include-blanks ++ Ordinarily, the fancy diary buffer does not show days for which there are ++no diary entries, even if that day is a holiday. If you want such days to be ++shown in the fancy diary buffer, set the variable ++@code{diary-list-include-blanks} to @code{t}.@refill ++ ++@cindex sorting diary entries ++ If you use the fancy diary display, you can use the normal hook ++@code{diary-list-entries-hook} to sort each day's diary entries by their ++time of day. Here's how: ++ ++@findex diary-sort-entries ++@example ++(add-hook 'diary-list-entries-hook 'diary-sort-entries t) ++@end example ++ ++@noindent ++For each day, this sorts diary entries that begin with a recognizable ++time of day according to their times. Diary entries without times come ++first within each day. ++ ++@vindex diary-include-string ++ Fancy diary display also has the ability to process included diary ++files. This permits a group of people to share a diary file for events ++that apply to all of them. Lines in the diary file starting with ++@code{diary-include-string}: ++ ++@smallexample ++#include "@var{filename}" ++@end smallexample ++ ++@noindent ++include the diary entries from the file @var{filename} in the fancy ++diary buffer. The include mechanism is recursive, so that included ++files can include other files, and so on (you must be careful not to ++have a cycle of inclusions, of course). Here is how to enable the ++include facility: ++ ++@vindex diary-list-entries-hook ++@vindex diary-mark-entries-hook ++@findex diary-include-other-diary-files ++@findex diary-mark-included-diary-files ++@smallexample ++(add-hook 'diary-list-entries-hook 'diary-include-other-diary-files) ++(add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files) ++@end smallexample ++ ++The include mechanism works only with the fancy diary display, because ++ordinary diary display shows the entries directly from your diary file. ++ ++@node Sexp Diary Entries ++@subsection Sexp Entries and the Fancy Diary Display ++@cindex sexp diary entries ++ ++@vindex diary-sexp-entry-symbol ++ Sexp diary entries allow you to do more than just have complicated ++conditions under which a diary entry applies. Sexp entries should be ++preceded by @code{diary-sexp-entry-symbol} (default @samp{%%}) in the ++diary file. If you use the fancy diary display, sexp entries can ++generate the text of the entry depending on the date itself. ++ ++For example, an anniversary diary entry can insert ++the number of years since the anniversary date into the text of the ++diary entry. Thus the @samp{%d} in this diary entry: ++ ++@findex diary-anniversary ++@smallexample ++%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) ++@end smallexample ++ ++@noindent ++gets replaced by the age, so on October 31, 1990 the entry appears in ++the fancy diary buffer like this: ++ ++@smallexample ++Arthur's birthday (42 years old) ++@end smallexample ++ ++@noindent ++If the diary file instead contains this entry: ++ ++@smallexample ++%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday ++@end smallexample ++ ++@noindent ++the entry in the fancy diary buffer for October 31, 1990 appears like this: ++ ++@smallexample ++Arthur's 42nd birthday ++@end smallexample ++ ++ Similarly, cyclic diary entries can interpolate the number of repetitions ++that have occurred: ++ ++@findex diary-cyclic ++@smallexample ++%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) ++@end smallexample ++ ++@noindent ++looks like this: ++ ++@smallexample ++Renew medication (5th time) ++@end smallexample ++ ++@noindent ++in the fancy diary display on September 8, 1990. ++ ++ There is an early reminder diary sexp that includes its entry in the ++diary not only on the date of occurrence, but also on earlier dates. ++For example, if you want a reminder a week before your anniversary, you ++can use ++ ++@findex diary-remind ++@smallexample ++%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary ++@end smallexample ++ ++@noindent ++and the fancy diary will show @samp{Ed's anniversary} both on December ++15 and on December 22. ++ ++@findex diary-date ++ The function @code{diary-date} applies to dates described by a month, ++day, year combination, each of which can be an integer, a list of ++integers, or @code{t} (meaning all values). For example, ++ ++@smallexample ++%%(diary-date '(10 11 12) 22 t) Rake leaves ++@end smallexample ++ ++@noindent ++causes the fancy diary to show ++ ++@smallexample ++Rake leaves ++@end smallexample ++ ++@noindent ++on October 22, November 22, and December 22 of every year. ++ ++@findex diary-float ++ The function @code{diary-float} allows you to describe diary entries ++that apply to dates like the third Friday of November, or the last ++Tuesday in April. The parameters are the @var{month}, @var{dayname}, ++and an index @var{n}. The entry appears on the @var{n}th @var{dayname} ++after the first day of @var{month}, where @var{dayname}=0 means Sunday, ++1 means Monday, and so on. If @var{n} is negative it counts backward ++from the end of @var{month}. The value of @var{month} can be a list of ++months, a single month, or @code{t} to specify all months. You can also ++use an optional parameter @var{day} to specify the @var{n}th ++@var{dayname} on or after/before @var{day} of @var{month}; the value of ++@var{day} defaults to 1 if @var{n} is positive and to the last day of ++@var{month} if @var{n} is negative. For example, ++ ++@smallexample ++%%(diary-float t 1 -1) Pay rent ++@end smallexample ++ ++@noindent ++causes the fancy diary to show ++ ++@smallexample ++Pay rent ++@end smallexample ++ ++@noindent ++on the last Monday of every month. ++ ++ The generality of sexp diary entries lets you specify any diary ++entry that you can describe algorithmically. A sexp diary entry ++contains an expression that computes whether the entry applies to any ++given date. If its value is non-@code{nil}, the entry applies to that ++date; otherwise, it does not. The expression can use the variable ++@code{date} to find the date being considered; its value is a list ++(@var{month} @var{day} @var{year}) that refers to the Gregorian ++calendar. ++ ++ The sexp diary entry applies to a date when the expression's value ++is non-@code{nil}, but some values have more specific meanings. If ++the value is a string, that string is a description of the event which ++occurs on that date. The value can also have the form ++@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to ++mark the date in the calendar, and @var{string} is the description of ++the event. If @var{mark} is a single-character string, that character ++appears next to the date in the calendar. If @var{mark} is a face ++name, the date is displayed in that face. If @var{mark} is ++@code{nil}, that specifies no particular highlighting for the date. ++ ++ Suppose you get paid on the 21st of the month if it is a weekday, and ++on the Friday before if the 21st is on a weekend. Here is how to write ++a sexp diary entry that matches those dates: ++ ++@smallexample ++&%%(let ((dayname (calendar-day-of-week date)) ++ (day (cadr date))) ++ (or (and (= day 21) (memq dayname '(1 2 3 4 5))) ++ (and (memq day '(19 20)) (= dayname 5))) ++ ) Pay check deposited ++@end smallexample ++ ++ The following sexp diary entries take advantage of the ability (in the fancy ++diary display) to concoct diary entries whose text varies based on the date: ++ ++@findex diary-sunrise-sunset ++@findex diary-lunar-phases ++@findex diary-day-of-year ++@findex diary-iso-date ++@findex diary-julian-date ++@findex diary-astro-day-number ++@findex diary-bahai-date ++@findex diary-chinese-date ++@findex diary-coptic-date ++@findex diary-ethiopic-date ++@findex diary-hebrew-date ++@findex diary-islamic-date ++@findex diary-french-date ++@findex diary-mayan-date ++@findex diary-persian-date ++@table @code ++@item %%(diary-sunrise-sunset) ++Make a diary entry for today's local times of sunrise and sunset. ++@item %%(diary-lunar-phases) ++Make a diary entry for the phases (quarters) of the moon. ++@item %%(diary-day-of-year) ++Make a diary entry with today's day number in the current year and the number ++of days remaining in the current year. ++@item %%(diary-iso-date) ++Make a diary entry with today's equivalent ISO commercial date. ++@item %%(diary-julian-date) ++Make a diary entry with today's equivalent Julian calendar date. ++@item %%(diary-astro-day-number) ++Make a diary entry with today's equivalent astronomical (Julian) day number. ++@item %%(diary-bahai-date) ++Make a diary entry with today's equivalent Baha'i calendar date. ++@item %%(diary-chinese-date) ++Make a diary entry with today's equivalent Chinese calendar date. ++@item %%(diary-coptic-date) ++Make a diary entry with today's equivalent Coptic calendar date. ++@item %%(diary-ethiopic-date) ++Make a diary entry with today's equivalent Ethiopic calendar date. ++@item %%(diary-french-date) ++Make a diary entry with today's equivalent date on the French Revolutionary ++calendar. ++@item %%(diary-hebrew-date) ++Make a diary entry with today's equivalent Hebrew calendar date. ++@item %%(diary-islamic-date) ++Make a diary entry with today's equivalent Islamic calendar date. ++@item %%(diary-mayan-date) ++Make a diary entry with today's equivalent Mayan calendar date. ++@item %%(diary-persian-date) ++Make a diary entry with today's equivalent Persian calendar date. ++@end table ++ ++@noindent ++For example, including the diary entry ++ ++@smallexample ++&%%(diary-hebrew-date) ++@end smallexample ++ ++@noindent ++causes every day's diary display to contain the equivalent date on the ++Hebrew calendar, if you are using the fancy diary display. (With simple ++diary display, the literal line @samp{&%%(diary-hebrew-date)} appears in ++the diary for any date.) ++ ++ This function has been used to construct certain standard Hebrew sexp ++diary entries: ++ ++@cindex rosh hodesh ++@findex diary-hebrew-rosh-hodesh ++@cindex parasha, weekly ++@findex diary-hebrew-parasha ++@cindex candle lighting times ++@findex diary-hebrew-sabbath-candles ++@cindex omer count ++@findex diary-hebrew-omer ++@cindex yahrzeits ++@findex diary-hebrew-yahrzeit ++@table @code ++@item %%(diary-hebrew-rosh-hodesh) ++Make a diary entry that tells the occurrence and ritual announcement of each ++new Hebrew month. ++@item %%(diary-hebrew-parasha) ++Make a Saturday diary entry that tells the weekly synagogue scripture reading. ++@item %%(diary-hebrew-sabbath-candles) ++Make a Friday diary entry that tells the @emph{local time} of Sabbath ++candle lighting. ++@item %%(diary-hebrew-omer) ++Make a diary entry that gives the omer count, when appropriate. ++@item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name} ++Make a diary entry marking the anniversary of a date of death. The date ++is the @emph{Gregorian} (civil) date of death. The diary entry appears ++on the proper Hebrew calendar anniversary and on the day before. (The ++order of the parameters changes according to the calendar date style; ++for example in the European style to @var{day}, @var{month}, @var{year}.) ++@end table ++ ++ All the functions documented above take an optional argument ++@var{mark} which specifies how to mark the date in the calendar display. ++If one of these functions decides that it applies to a certain date, ++it returns a value that contains @var{mark}, as described above. ++ ++@ignore ++ arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431 ++@end ignore +diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi +new file mode 100644 +index 0000000..8b56b65 +--- /dev/null ++++ b/doc/emacs/calendar.texi +@@ -0,0 +1,1715 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Calendar/Diary, Document View, Dired, Top ++@chapter The Calendar and the Diary ++@cindex calendar ++@findex calendar ++ ++ Emacs provides the functions of a desk calendar, with a diary of ++planned or past events. It also has facilities for managing your ++appointments, and keeping track of how much time you spend working on ++certain projects. ++ ++ To enter the calendar, type @kbd{M-x calendar}; this displays a ++three-month calendar centered on the current month, with point on the ++current date. With a numeric argument, as in @kbd{C-u M-x calendar}, it ++prompts you for the month and year to be the center of the three-month ++calendar. The calendar uses its own buffer, whose major mode is ++Calendar mode. ++ ++ @kbd{Mouse-3} in the calendar brings up a menu of operations on a ++particular date; @kbd{Mouse-2} brings up a menu of commonly used ++calendar features that are independent of any particular date. To exit ++the calendar, type @kbd{q}. ++ ++@iftex ++ This chapter describes the basic calendar features. ++@inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information ++about more specialized features. ++@end iftex ++ ++@menu ++* Calendar Motion:: Moving through the calendar; selecting a date. ++* Scroll Calendar:: Bringing earlier or later months onto the screen. ++* Counting Days:: How many days are there between two dates? ++* General Calendar:: Exiting or recomputing the calendar. ++* Writing Calendar Files:: Writing calendars to files of various formats. ++* Holidays:: Displaying dates of holidays. ++* Sunrise/Sunset:: Displaying local times of sunrise and sunset. ++* Lunar Phases:: Displaying phases of the moon. ++* Other Calendars:: Converting dates to other calendar systems. ++* Diary:: Displaying events from your diary. ++* Appointments:: Reminders when it's time to do something. ++* Importing Diary:: Converting diary events to/from other formats. ++* Daylight Saving:: How to specify when daylight saving time is active. ++* Time Intervals:: Keeping track of time intervals. ++@ifnottex ++* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. ++@end ifnottex ++@end menu ++ ++@node Calendar Motion ++@section Movement in the Calendar ++ ++@cindex moving inside the calendar ++ Calendar mode provides commands to move through the calendar in ++logical units of time such as days, weeks, months, and years. If you ++move outside the three months originally displayed, the calendar ++display ``scrolls'' automatically through time to make the selected ++date visible. Moving to a date lets you view its holidays or diary ++entries, or convert it to other calendars; moving by long time periods ++is also useful simply to scroll the calendar. ++ ++@menu ++* Calendar Unit Motion:: Moving by days, weeks, months, and years. ++* Move to Beginning or End:: Moving to start/end of weeks, months, and years. ++* Specified Dates:: Moving to the current date or another ++ specific date. ++@end menu ++ ++@node Calendar Unit Motion ++@subsection Motion by Standard Lengths of Time ++ ++ The commands for movement in the calendar buffer parallel the ++commands for movement in text. You can move forward and backward by ++days, weeks, months, and years. ++ ++@table @kbd ++@item C-f ++Move point one day forward (@code{calendar-forward-day}). ++@item C-b ++Move point one day backward (@code{calendar-backward-day}). ++@item C-n ++Move point one week forward (@code{calendar-forward-week}). ++@item C-p ++Move point one week backward (@code{calendar-backward-week}). ++@item M-@} ++Move point one month forward (@code{calendar-forward-month}). ++@item M-@{ ++Move point one month backward (@code{calendar-backward-month}). ++@item C-x ] ++Move point one year forward (@code{calendar-forward-year}). ++@item C-x [ ++Move point one year backward (@code{calendar-backward-year}). ++@end table ++ ++@kindex C-f @r{(Calendar mode)} ++@findex calendar-forward-day ++@kindex C-b @r{(Calendar mode)} ++@findex calendar-backward-day ++@kindex C-n @r{(Calendar mode)} ++@findex calendar-forward-week ++@kindex C-p @r{(Calendar mode)} ++@findex calendar-backward-week ++ The day and week commands are natural analogues of the usual Emacs ++commands for moving by characters and by lines. Just as @kbd{C-n} ++usually moves to the same column in the following line, in Calendar ++mode it moves to the same day in the following week. And @kbd{C-p} ++moves to the same day in the previous week. ++ ++ The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and ++@kbd{C-p}, just as they normally are in other modes. ++ ++@kindex M-@} @r{(Calendar mode)} ++@findex calendar-forward-month ++@kindex M-@{ @r{(Calendar mode)} ++@findex calendar-backward-month ++@kindex C-x ] @r{(Calendar mode)} ++@findex calendar-forward-year ++@kindex C-x [ @r{(Calendar mode)} ++@findex calendar-forward-year ++ The commands for motion by months and years work like those for ++weeks, but move a larger distance. The month commands @kbd{M-@}} and ++@kbd{M-@{} move forward or backward by an entire month. The year ++commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a ++whole year. ++ ++ The easiest way to remember these commands is to consider months and ++years analogous to paragraphs and pages of text, respectively. But ++the commands themselves are not quite analogous. The ordinary Emacs ++paragraph commands move to the beginning or end of a paragraph, ++whereas these month and year commands move by an entire month or an ++entire year, keeping the same date within the month or year. ++ ++ All these commands accept a numeric argument as a repeat count. ++For convenience, the digit keys and the minus sign specify numeric ++arguments in Calendar mode even without the Meta modifier. For example, ++@kbd{100 C-f} moves point 100 days forward from its present location. ++ ++@node Move to Beginning or End ++@subsection Beginning or End of Week, Month or Year ++ ++ A week (or month, or year) is not just a quantity of days; we think of ++weeks (months, years) as starting on particular dates. So Calendar mode ++provides commands to move to the beginning or end of a week, month or ++year: ++ ++@table @kbd ++@kindex C-a @r{(Calendar mode)} ++@findex calendar-beginning-of-week ++@item C-a ++Move point to start of week (@code{calendar-beginning-of-week}). ++@kindex C-e @r{(Calendar mode)} ++@findex calendar-end-of-week ++@item C-e ++Move point to end of week (@code{calendar-end-of-week}). ++@kindex M-a @r{(Calendar mode)} ++@findex calendar-beginning-of-month ++@item M-a ++Move point to start of month (@code{calendar-beginning-of-month}). ++@kindex M-e @r{(Calendar mode)} ++@findex calendar-end-of-month ++@item M-e ++Move point to end of month (@code{calendar-end-of-month}). ++@kindex M-< @r{(Calendar mode)} ++@findex calendar-beginning-of-year ++@item M-< ++Move point to start of year (@code{calendar-beginning-of-year}). ++@kindex M-> @r{(Calendar mode)} ++@findex calendar-end-of-year ++@item M-> ++Move point to end of year (@code{calendar-end-of-year}). ++@end table ++ ++ These commands also take numeric arguments as repeat counts, with the ++repeat count indicating how many weeks, months, or years to move ++backward or forward. ++ ++@vindex calendar-week-start-day ++@cindex weeks, which day they start on ++@cindex calendar, first day of week ++ By default, weeks begin on Sunday. To make them begin on Monday ++instead, set the variable @code{calendar-week-start-day} to 1. ++ ++@node Specified Dates ++@subsection Specified Dates ++ ++ Calendar mode provides commands for moving to a particular date ++specified in various ways. ++ ++@table @kbd ++@item g d ++Move point to specified date (@code{calendar-goto-date}). ++@item g D ++Move point to specified day of year (@code{calendar-goto-day-of-year}). ++@item g w ++Move point to specified week of year (@code{calendar-iso-goto-week}). ++@item o ++Center calendar around specified month (@code{calendar-other-month}). ++@item . ++Move point to today's date (@code{calendar-goto-today}). ++@end table ++ ++@kindex g d @r{(Calendar mode)} ++@findex calendar-goto-date ++ @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day ++of the month, and then moves to that date. Because the calendar includes all ++dates from the beginning of the current era, you must type the year in its ++entirety; that is, type @samp{1990}, not @samp{90}. ++ ++@kindex g D @r{(Calendar mode)} ++@findex calendar-goto-day-of-year ++@kindex g w @r{(Calendar mode)} ++@findex calendar-iso-goto-week ++ @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and ++day number, and moves to that date. Negative day numbers count ++backward from the end of the year. @kbd{g w} ++(@code{calendar-iso-goto-week}) prompts for a year and week number, ++and moves to that week. ++ ++@kindex o @r{(Calendar mode)} ++@findex calendar-other-month ++ @kbd{o} (@code{calendar-other-month}) prompts for a month and year, ++then centers the three-month calendar around that month. ++ ++@kindex . @r{(Calendar mode)} ++@findex calendar-goto-today ++ You can return to today's date with @kbd{.}@: ++(@code{calendar-goto-today}). ++ ++@node Scroll Calendar ++@section Scrolling in the Calendar ++ ++@cindex scrolling in the calendar ++ The calendar display scrolls automatically through time when you ++move out of the visible portion. You can also scroll it manually. ++Imagine that the calendar window contains a long strip of paper with ++the months on it. Scrolling the calendar means moving the strip ++horizontally, so that new months become visible in the window. ++ ++@table @kbd ++@item > ++Scroll calendar one month forward (@code{calendar-scroll-left}). ++@item < ++Scroll calendar one month backward (@code{calendar-scroll-right}). ++@item C-v ++@itemx @key{next} ++Scroll calendar three months forward ++(@code{calendar-scroll-left-three-months}). ++@item M-v ++@itemx @key{prior} ++Scroll calendar three months backward ++(@code{calendar-scroll-right-three-months}). ++@end table ++ ++@kindex > @r{(Calendar mode)} ++@findex calendar-scroll-left ++@kindex < @r{(Calendar mode)} ++@findex calendar-scroll-right ++ The most basic calendar scroll commands scroll by one month at a ++time. This means that there are two months of overlap between the ++display before the command and the display after. @kbd{>} scrolls the ++calendar contents one month forward in time. @kbd{<} scrolls the ++contents one month backwards in time. ++ ++@kindex C-v @r{(Calendar mode)} ++@findex calendar-scroll-left-three-months ++@kindex M-v @r{(Calendar mode)} ++@findex calendar-scroll-right-three-months ++ The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire ++``screenful''---three months---in analogy with the usual meaning of ++these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes ++earlier dates visible. These commands take a numeric argument as a ++repeat count; in particular, since @kbd{C-u} multiplies the next command ++by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and ++typing @kbd{C-u M-v} scrolls the calendar backward by a year. ++ ++ The function keys @key{next} and @key{prior} are equivalent to ++@kbd{C-v} and @kbd{M-v}, just as they are in other modes. ++ ++@node Counting Days ++@section Counting Days ++ ++@table @kbd ++@item M-= ++Display the number of days in the current region ++(@code{calendar-count-days-region}). ++@end table ++ ++@kindex M-= @r{(Calendar mode)} ++@findex calendar-count-days-region ++ To determine the number of days in the region, type @kbd{M-=} ++(@code{calendar-count-days-region}). The numbers of days shown is ++@emph{inclusive}; that is, it includes the days specified by mark and ++point. ++ ++@node General Calendar ++@section Miscellaneous Calendar Commands ++ ++@table @kbd ++@item p d ++Display day-in-year (@code{calendar-print-day-of-year}). ++@item C-c C-l ++Regenerate the calendar window (@code{calendar-redraw}). ++@item SPC ++Scroll the next window up (@code{scroll-other-window}). ++@item DEL ++Scroll the next window down (@code{scroll-other-window-down}). ++@item q ++Exit from calendar (@code{calendar-exit}). ++@end table ++ ++@kindex p d @r{(Calendar mode)} ++@cindex day of year ++@findex calendar-print-day-of-year ++ To display the number of days elapsed since the start of the year, or ++the number of days remaining in the year, type the @kbd{p d} command ++(@code{calendar-print-day-of-year}). This displays both of those ++numbers in the echo area. The count of days elapsed includes the ++selected date. The count of days remaining does not include that ++date. ++ ++@kindex C-c C-l @r{(Calendar mode)} ++@findex calendar-redraw ++ If the calendar window text gets corrupted, type @kbd{C-c C-l} ++(@code{calendar-redraw}) to redraw it. (This can only happen if you use ++non-Calendar-mode editing commands.) ++ ++@kindex SPC @r{(Calendar mode)} ++ In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window}) ++and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other ++window (if there is one) up or down, respectively. This is handy when ++you display a list of holidays or diary entries in another window. ++ ++@kindex q @r{(Calendar mode)} ++@findex exit-calendar ++@vindex calendar-remove-frame-by-deleting ++ To exit from the calendar, type @kbd{q} (@code{calendar-exit}). This ++buries all buffers related to the calendar, selecting other buffers. ++(If a frame contains a dedicated calendar window, exiting from the ++calendar deletes or iconifies that frame depending on the value of ++@code{calendar-remove-frame-by-deleting}.) ++ ++@node Writing Calendar Files ++@section Writing Calendar Files ++ ++ You can write calendars and diary entries to HTML and La@TeX{} files. ++ ++@cindex calendar and HTML ++ The Calendar HTML commands produce files of HTML code that contain ++calendar and diary entries. Each file applies to one month, and has a ++name of the format @file{@var{yyyy}-@var{mm}.html}, where @var{yyyy} and ++@var{mm} are the four-digit year and two-digit month, respectively. The ++variable @code{cal-html-directory} specifies the default output ++directory for the HTML files. ++ ++@vindex cal-html-css-default ++ Diary entries enclosed by @code{<} and @code{>} are interpreted as ++HTML tags (for example: this is a diary entry with some red text). You can change the overall ++appearance of the displayed HTML pages (for example, the color of ++various page elements, header styles) via a stylesheet @file{cal.css} in ++the directory containing the HTML files (see the value of the variable ++@code{cal-html-css-default} for relevant style settings). ++ ++@kindex t @r{(Calendar mode)} ++@table @kbd ++@item H m ++Generate a one-month calendar (@code{cal-html-cursor-month}). ++@item H y ++Generate a calendar file for each month of a year, as well as an index ++page (@code{cal-html-cursor-year}). By default, this command writes ++files to a @var{yyyy} subdirectory - if this is altered some hyperlinks ++between years will not work. ++@end table ++ ++ If the variable @code{cal-html-print-day-number-flag} is ++non-@code{nil}, then the monthly calendars show the day-of-the-year ++number. The variable @code{cal-html-year-index-cols} specifies the ++number of columns in the yearly index page. ++ ++@cindex calendar and La@TeX{} ++ The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that ++prints as a calendar. Depending on the command you use, the printed ++calendar covers the day, week, month or year that point is in. ++ ++@kindex t @r{(Calendar mode)} ++@table @kbd ++@item t m ++Generate a one-month calendar (@code{cal-tex-cursor-month}). ++@item t M ++Generate a sideways-printing one-month calendar ++(@code{cal-tex-cursor-month-landscape}). ++@item t d ++Generate a one-day calendar ++(@code{cal-tex-cursor-day}). ++@item t w 1 ++Generate a one-page calendar for one week ++(@code{cal-tex-cursor-week}). ++@item t w 2 ++Generate a two-page calendar for one week ++(@code{cal-tex-cursor-week2}). ++@item t w 3 ++Generate an ISO-style calendar for one week ++(@code{cal-tex-cursor-week-iso}). ++@item t w 4 ++Generate a calendar for one Monday-starting week ++(@code{cal-tex-cursor-week-monday}). ++@item t f w ++Generate a Filofax-style two-weeks-at-a-glance calendar ++(@code{cal-tex-cursor-filofax-2week}). ++@item t f W ++Generate a Filofax-style one-week-at-a-glance calendar ++(@code{cal-tex-cursor-filofax-week}). ++@item t y ++Generate a calendar for one year ++(@code{cal-tex-cursor-year}). ++@item t Y ++Generate a sideways-printing calendar for one year ++(@code{cal-tex-cursor-year-landscape}). ++@item t f y ++Generate a Filofax-style calendar for one year ++(@code{cal-tex-cursor-filofax-year}). ++@end table ++ ++ Some of these commands print the calendar sideways (in ``landscape ++mode''), so it can be wider than it is long. Some of them use Filofax ++paper size (3.75in x 6.75in). All of these commands accept a prefix ++argument which specifies how many days, weeks, months or years to print ++(starting always with the selected one). ++ ++ If the variable @code{cal-tex-holidays} is non-@code{nil} (the default), ++then the printed calendars show the holidays in @code{calendar-holidays}. ++If the variable @code{cal-tex-diary} is non-@code{nil} (the default is ++@code{nil}), diary entries are included also (in monthly, filofax, and ++iso-week calendars only). If the variable @code{cal-tex-rules} is ++non-@code{nil} (the default is @code{nil}), the calendar displays ruled ++pages in styles that have sufficient room. Consult the documentation of ++the individual cal-tex functions to see which calendars support which ++features. ++ ++ You can use the variable @code{cal-tex-preamble-extra} to insert extra ++La@TeX{} commands in the preamble of the generated document if you need ++to. ++ ++@node Holidays ++@section Holidays ++@cindex holidays ++ ++ The Emacs calendar knows about many major and minor holidays, ++and can display them. You can add your own holidays to the default list. ++ ++@table @kbd ++@item h ++Display holidays for the selected date ++(@code{calendar-cursor-holidays}). ++@item Mouse-3 Holidays ++Display any holidays for the date you click on. ++@item x ++Mark holidays in the calendar window (@code{calendar-mark-holidays}). ++@item u ++Unmark calendar window (@code{calendar-unmark}). ++@item a ++List all holidays for the displayed three months in another window ++(@code{calendar-list-holidays}). ++@item M-x holidays ++List all holidays for three months around today's date in another ++window. ++@item M-x list-holidays ++List holidays in another window for a specified range of years. ++@end table ++ ++@kindex h @r{(Calendar mode)} ++@findex calendar-cursor-holidays ++@vindex calendar-view-holidays-initially-flag ++ To see if any holidays fall on a given date, position point on that ++date in the calendar window and use the @kbd{h} command. Alternatively, ++click on that date with @kbd{Mouse-3} and then choose @kbd{Holidays} ++from the menu that appears. Either way, this displays the holidays for ++that date, in the echo area if they fit there, otherwise in a separate ++window. ++ ++@kindex x @r{(Calendar mode)} ++@findex calendar-mark-holidays ++@kindex u @r{(Calendar mode)} ++@findex calendar-unmark ++@vindex calendar-mark-holidays-flag ++ To view the distribution of holidays for all the dates shown in the ++calendar, use the @kbd{x} command. This displays the dates that are ++holidays in a different face. ++@iftex ++@inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Calendar Customizing, calendar-holiday-marker}. ++@end ifnottex ++ The command applies both to the currently visible months and to ++other months that subsequently become visible by scrolling. To turn ++marking off and erase the current marks, type @kbd{u}, which also ++erases any diary marks (@pxref{Diary}). If the variable ++@code{calendar-mark-holidays-flag} is non-@code{nil}, creating or ++updating the calendar marks holidays automatically. ++ ++@kindex a @r{(Calendar mode)} ++@findex calendar-list-holidays ++ To get even more detailed information, use the @kbd{a} command, which ++displays a separate buffer containing a list of all holidays in the ++current three-month range. You can use @key{SPC} and @key{DEL} in the ++calendar window to scroll that list up and down, respectively. ++ ++@findex holidays ++ The command @kbd{M-x holidays} displays the list of holidays for the ++current month and the preceding and succeeding months; this works even ++if you don't have a calendar window. If the variable ++@code{calendar-view-holidays-initially-flag} is non-@code{nil}, creating ++the calendar displays holidays in this way. If you want the list of ++holidays centered around a different month, use @kbd{C-u M-x ++holidays}, which prompts for the month and year. ++ ++ The holidays known to Emacs include United States holidays and the ++major Baha'i, Chinese, Christian, Islamic, and Jewish holidays; also the ++solstices and equinoxes. ++ ++@findex list-holidays ++ The command @kbd{M-x holiday-list} displays the list of holidays for ++a range of years. This function asks you for the starting and stopping ++years, and allows you to choose all the holidays or one of several ++categories of holidays. You can use this command even if you don't have ++a calendar window. ++ ++ The dates used by Emacs for holidays are based on @emph{current ++practice}, not historical fact. For example Veteran's Day began in ++1919, but is shown in earlier years. ++ ++@node Sunrise/Sunset ++@section Times of Sunrise and Sunset ++@cindex sunrise and sunset ++ ++ Special calendar commands can tell you, to within a minute or two, the ++times of sunrise and sunset for any date. ++ ++@table @kbd ++@item S ++Display times of sunrise and sunset for the selected date ++(@code{calendar-sunrise-sunset}). ++@item Mouse-3 Sunrise/sunset ++Display times of sunrise and sunset for the date you click on. ++@item M-x sunrise-sunset ++Display times of sunrise and sunset for today's date. ++@item C-u M-x sunrise-sunset ++Display times of sunrise and sunset for a specified date. ++@item M-x calendar-sunrise-sunset-month ++Display times of sunrise and sunset for the selected month. ++@end table ++ ++@kindex S @r{(Calendar mode)} ++@findex calendar-sunrise-sunset ++@findex sunrise-sunset ++ Within the calendar, to display the @emph{local times} of sunrise and ++sunset in the echo area, move point to the date you want, and type ++@kbd{S}. Alternatively, click @kbd{Mouse-3} on the date, then choose ++@samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x ++sunrise-sunset} is available outside the calendar to display this ++information for today's date or a specified date. To specify a date ++other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for ++the year, month, and day. ++ ++ You can display the times of sunrise and sunset for any location and ++any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a ++longitude, latitude, number of minutes difference from Coordinated ++Universal Time, and date, and then tells you the times of sunrise and ++sunset for that location on that date. ++ ++ Because the times of sunrise and sunset depend on the location on ++earth, you need to tell Emacs your latitude, longitude, and location ++name before using these commands. Here is an example of what to set: ++ ++@vindex calendar-location-name ++@vindex calendar-longitude ++@vindex calendar-latitude ++@example ++(setq calendar-latitude 40.1) ++(setq calendar-longitude -88.2) ++(setq calendar-location-name "Urbana, IL") ++@end example ++ ++@noindent ++Use one decimal place in the values of @code{calendar-latitude} and ++@code{calendar-longitude}. ++ ++ Your time zone also affects the local time of sunrise and sunset. ++Emacs usually gets time zone information from the operating system, but ++if these values are not what you want (or if the operating system does ++not supply them), you must set them yourself. Here is an example: ++ ++@vindex calendar-time-zone ++@vindex calendar-standard-time-zone-name ++@vindex calendar-daylight-time-zone-name ++@example ++(setq calendar-time-zone -360) ++(setq calendar-standard-time-zone-name "CST") ++(setq calendar-daylight-time-zone-name "CDT") ++@end example ++ ++@noindent ++The value of @code{calendar-time-zone} is the number of minutes ++difference between your local standard time and Coordinated Universal ++Time (Greenwich time). The values of ++@code{calendar-standard-time-zone-name} and ++@code{calendar-daylight-time-zone-name} are the abbreviations used in ++your time zone. Emacs displays the times of sunrise and sunset ++@emph{corrected for daylight saving time}. @xref{Daylight Saving}, ++for how daylight saving time is determined. ++ ++ As a user, you might find it convenient to set the calendar location ++variables for your usual physical location in your @file{.emacs} file. ++And when you install Emacs on a machine, you can create a ++@file{default.el} file which sets them properly for the typical location ++of most users of that machine. @xref{Init File}. ++ ++@node Lunar Phases ++@section Phases of the Moon ++@cindex phases of the moon ++@cindex moon, phases of ++ ++ These calendar commands display the dates and times of the phases of ++the moon (new moon, first quarter, full moon, last quarter). This ++feature is useful for debugging problems that ``depend on the phase of ++the moon.'' ++ ++@table @kbd ++@item M ++Display the dates and times for all the quarters of the moon for the ++three-month period shown (@code{calendar-lunar-phases}). ++@item M-x lunar-phases ++Display dates and times of the quarters of the moon for three months around ++today's date. ++@end table ++ ++@kindex M @r{(Calendar mode)} ++@findex calendar-lunar-phases ++ Within the calendar, use the @kbd{M} command to display a separate ++buffer of the phases of the moon for the current three-month range. The ++dates and times listed are accurate to within a few minutes. ++ ++@findex lunar-phases ++ Outside the calendar, use the command @kbd{M-x lunar-phases} to ++display the list of the phases of the moon for the current month and the ++preceding and succeeding months. For information about a different ++month, use @kbd{C-u M-x lunar-phases}, which prompts for the month and ++year. ++ ++ The dates and times given for the phases of the moon are given in ++local time (corrected for daylight saving, when appropriate). ++See the discussion in the previous section. @xref{Sunrise/Sunset}. ++ ++@node Other Calendars ++@section Conversion To and From Other Calendars ++ ++@cindex Gregorian calendar ++ The Emacs calendar displayed is @emph{always} the Gregorian calendar, ++sometimes called the ``new style'' calendar, which is used in most of ++the world today. However, this calendar did not exist before the ++sixteenth century and was not widely used before the eighteenth century; ++it did not fully displace the Julian calendar and gain universal ++acceptance until the early twentieth century. The Emacs calendar can ++display any month since January, year 1 of the current era, but the ++calendar displayed is the Gregorian, even for a date at which the ++Gregorian calendar did not exist. ++ ++ While Emacs cannot display other calendars, it can convert dates to ++and from several other calendars. ++ ++@menu ++* Calendar Systems:: The calendars Emacs understands ++ (aside from Gregorian). ++* To Other Calendar:: Converting the selected date to various calendars. ++* From Other Calendar:: Moving to a date specified in another calendar. ++* Mayan Calendar:: Moving to a date specified in a Mayan calendar. ++@end menu ++ ++@node Calendar Systems ++@subsection Supported Calendar Systems ++ ++@cindex ISO commercial calendar ++ The ISO commercial calendar is used largely in Europe. ++ ++@cindex Julian calendar ++ The Julian calendar, named after Julius Caesar, was the one used in Europe ++throughout medieval times, and in many countries up until the nineteenth ++century. ++ ++@cindex Julian day numbers ++@cindex astronomical day numbers ++ Astronomers use a simple counting of days elapsed since noon, Monday, ++January 1, 4713 B.C. on the Julian calendar. The number of days elapsed ++is called the @dfn{Julian day number} or the @dfn{Astronomical day number}. ++ ++@cindex Hebrew calendar ++ The Hebrew calendar is used by tradition in the Jewish religion. The ++Emacs calendar program uses the Hebrew calendar to determine the dates ++of Jewish holidays. Hebrew calendar dates begin and end at sunset. ++ ++@cindex Islamic calendar ++ The Islamic calendar is used in many predominantly Islamic countries. ++Emacs uses it to determine the dates of Islamic holidays. There is no ++universal agreement in the Islamic world about the calendar; Emacs uses ++a widely accepted version, but the precise dates of Islamic holidays ++often depend on proclamation by religious authorities, not on ++calculations. As a consequence, the actual dates of observance can vary ++slightly from the dates computed by Emacs. Islamic calendar dates begin ++and end at sunset. ++ ++@cindex French Revolutionary calendar ++ The French Revolutionary calendar was created by the Jacobins after the 1789 ++revolution, to represent a more secular and nature-based view of the annual ++cycle, and to install a 10-day week in a rationalization measure similar to ++the metric system. The French government officially abandoned this ++calendar at the end of 1805. ++ ++@cindex Mayan calendar ++ The Maya of Central America used three separate, overlapping calendar ++systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}. ++Emacs knows about all three of these calendars. Experts dispute the ++exact correlation between the Mayan calendar and our calendar; Emacs uses the ++Goodman-Martinez-Thompson correlation in its calculations. ++ ++@cindex Coptic calendar ++@cindex Ethiopic calendar ++ The Copts use a calendar based on the ancient Egyptian solar calendar. ++Their calendar consists of twelve 30-day months followed by an extra ++five-day period. Once every fourth year they add a leap day to this ++extra period to make it six days. The Ethiopic calendar is identical in ++structure, but has different year numbers and month names. ++ ++@cindex Persian calendar ++ The Persians use a solar calendar based on a design of Omar Khayyam. ++Their calendar consists of twelve months of which the first six have 31 ++days, the next five have 30 days, and the last has 29 in ordinary years ++and 30 in leap years. Leap years occur in a complicated pattern every ++four or five years. ++The calendar implemented here is the arithmetical Persian calendar ++championed by Birashk, based on a 2,820-year cycle. It differs from ++the astronomical Persian calendar, which is based on astronomical ++events. As of this writing the first future discrepancy is projected ++to occur on March 20, 2025. It is currently not clear what the ++official calendar of Iran will be that far into the future. ++ ++@cindex Chinese calendar ++ The Chinese calendar is a complicated system of lunar months arranged ++into solar years. The years go in cycles of sixty, each year containing ++either twelve months in an ordinary year or thirteen months in a leap ++year; each month has either 29 or 30 days. Years, ordinary months, and ++days are named by combining one of ten ``celestial stems'' with one of ++twelve ``terrestrial branches'' for a total of sixty names that are ++repeated in a cycle of sixty. ++ ++@cindex Baha'i calendar ++ The Baha'i calendar system is based on a solar cycle of 19 months with ++19 days each. The four remaining ``intercalary'' days are placed ++between the 18th and 19th months. ++ ++@node To Other Calendar ++@subsection Converting To Other Calendars ++ ++ The following commands describe the selected date (the date at point) ++in various other calendar systems: ++ ++@table @kbd ++@item Mouse-3 Other calendars ++Display the date that you click on, expressed in various other calendars. ++@kindex p @r{(Calendar mode)} ++@findex calendar-print-other-dates ++@item p o ++Display the selected date in various other calendars. ++(@code{calendar-print-other-dates}). ++@findex calendar-iso-print-date ++@item p c ++Display ISO commercial calendar equivalent for selected day ++(@code{calendar-iso-print-date}). ++@findex calendar-julian-print-date ++@item p j ++Display Julian date for selected day (@code{calendar-julian-print-date}). ++@findex calendar-astro-print-day-number ++@item p a ++Display astronomical (Julian) day number for selected day ++(@code{calendar-astro-print-day-number}). ++@findex calendar-hebrew-print-date ++@item p h ++Display Hebrew date for selected day (@code{calendar-hebrew-print-date}). ++@findex calendar-islamic-print-date ++@item p i ++Display Islamic date for selected day (@code{calendar-islamic-print-date}). ++@findex calendar-french-print-date ++@item p f ++Display French Revolutionary date for selected day ++(@code{calendar-french-print-date}). ++@findex calendar-bahai-print-date ++@item p b ++Display Baha'i date for selected day ++(@code{calendar-bahai-print-date}). ++@findex calendar-chinese-print-date ++@item p C ++Display Chinese date for selected day ++(@code{calendar-chinese-print-date}). ++@findex calendar-coptic-print-date ++@item p k ++Display Coptic date for selected day ++(@code{calendar-coptic-print-date}). ++@findex calendar-ethiopic-print-date ++@item p e ++Display Ethiopic date for selected day ++(@code{calendar-ethiopic-print-date}). ++@findex calendar-persian-print-date ++@item p p ++Display Persian date for selected day ++(@code{calendar-persian-print-date}). ++@findex calendar-mayan-print-date ++@item p m ++Display Mayan date for selected day (@code{calendar-mayan-print-date}). ++@end table ++ ++ If you are using a graphic display, the easiest way to translate a ++date into other calendars is to click on it with @kbd{Mouse-3}, then ++choose @kbd{Other calendars} from the menu that appears. This displays ++the equivalent forms of the date in all the calendars Emacs understands, ++in the form of a menu. (Choosing an alternative from this menu doesn't ++actually do anything---the menu is used only for display.) ++ ++ Otherwise, move point to the date you want to convert, then type the ++appropriate command starting with @kbd{p} from the table above. The ++prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the ++equivalent date in the echo area. @kbd{p o} displays the ++date in all forms known to Emacs. ++ ++@node From Other Calendar ++@subsection Converting From Other Calendars ++ ++ You can use the other supported calendars to specify a date to move ++to. This section describes the commands for doing this using calendars ++other than Mayan; for the Mayan calendar, see the following section. ++ ++@kindex g @var{char} @r{(Calendar mode)} ++@findex calendar-iso-goto-date ++@findex calendar-iso-goto-week ++@findex calendar-julian-goto-date ++@findex calendar-astro-goto-day-number ++@findex calendar-bahai-goto-date ++@findex calendar-hebrew-goto-date ++@findex calendar-islamic-goto-date ++@findex calendar-french-goto-date ++@findex calendar-chinese-goto-date ++@findex calendar-persian-goto-date ++@findex calendar-coptic-goto-date ++@findex calendar-ethiopic-goto-date ++@table @kbd ++@item g c ++Move to a date specified in the ISO commercial calendar ++(@code{calendar-iso-goto-date}). ++@item g w ++Move to a week specified in the ISO commercial calendar ++(@code{calendar-iso-goto-week}). ++@item g j ++Move to a date specified in the Julian calendar ++(@code{calendar-julian-goto-date}). ++@item g a ++Move to a date specified with an astronomical (Julian) day number ++(@code{calendar-astro-goto-day-number}). ++@item g b ++Move to a date specified in the Baha'i calendar ++(@code{calendar-bahai-goto-date}). ++@item g h ++Move to a date specified in the Hebrew calendar ++(@code{calendar-hebrew-goto-date}). ++@item g i ++Move to a date specified in the Islamic calendar ++(@code{calendar-islamic-goto-date}). ++@item g f ++Move to a date specified in the French Revolutionary calendar ++(@code{calendar-french-goto-date}). ++@item g C ++Move to a date specified in the Chinese calendar ++(@code{calendar-chinese-goto-date}). ++@item g p ++Move to a date specified in the Persian calendar ++(@code{calendar-persian-goto-date}). ++@item g k ++Move to a date specified in the Coptic calendar ++(@code{calendar-coptic-goto-date}). ++@item g e ++Move to a date specified in the Ethiopic calendar ++(@code{calendar-ethiopic-goto-date}). ++@end table ++ ++ These commands ask you for a date on the other calendar, move point to ++the Gregorian calendar date equivalent to that date, and display the ++other calendar's date in the echo area. Emacs uses strict completion ++(@pxref{Strict Completion}) whenever it asks you to type a month name, so you ++don't have to worry about the spelling of Hebrew, Islamic, or French names. ++ ++@c FIXME move? ++@findex calendar-hebrew-list-yahrzeits ++@cindex yahrzeits ++ One common question concerning the Hebrew calendar is the computation ++of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs ++calendar includes a facility for such calculations. If you are in the ++calendar, the command @kbd{M-x calendar-hebrew-list-yahrzeits} asks you for ++a range of years and then displays a list of the yahrzeit dates for those ++years for the date given by point. If you are not in the calendar, ++this command first asks you for the date of death and the range of ++years, and then displays the list of yahrzeit dates. ++ ++@node Mayan Calendar ++@subsection Converting from the Mayan Calendar ++ ++ Here are the commands to select dates based on the Mayan calendar: ++ ++@table @kbd ++@item g m l ++Move to a date specified by the long count calendar ++(@code{calendar-mayan-goto-long-count-date}). ++@item g m n t ++Move to the next occurrence of a place in the ++tzolkin calendar (@code{calendar-mayan-next-tzolkin-date}). ++@item g m p t ++Move to the previous occurrence of a place in the ++tzolkin calendar (@code{calendar-mayan-previous-tzolkin-date}). ++@item g m n h ++Move to the next occurrence of a place in the ++haab calendar (@code{calendar-mayan-next-haab-date}). ++@item g m p h ++Move to the previous occurrence of a place in the ++haab calendar (@code{calendar-mayan-previous-haab-date}). ++@item g m n c ++Move to the next occurrence of a place in the ++calendar round (@code{calendar-mayan-next-calendar-round-date}). ++@item g m p c ++Move to the previous occurrence of a place in the ++calendar round (@code{calendar-mayan-previous-calendar-round-date}). ++@end table ++ ++@cindex Mayan long count ++ To understand these commands, you need to understand the Mayan calendars. ++The @dfn{long count} is a counting of days with these units: ++ ++@display ++1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal ++1 katun = 20 tun@ @ @ 1 baktun = 20 katun ++@end display ++ ++@kindex g m @r{(Calendar mode)} ++@findex calendar-mayan-goto-long-count-date ++@noindent ++Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 ++tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long ++count dates as early as 7.17.18.13.3, but no earlier. When you use the ++@kbd{g m l} command, type the Mayan long count date with the baktun, ++katun, tun, uinal, and kin separated by periods. ++ ++@findex calendar-mayan-previous-tzolkin-date ++@findex calendar-mayan-next-tzolkin-date ++@cindex Mayan tzolkin calendar ++ The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of ++independent cycles of 13 and 20 days. Since this cycle repeats ++endlessly, Emacs provides commands to move backward and forward to the ++previous or next point in the cycle. Type @kbd{g m p t} to go to the ++previous tzolkin date; Emacs asks you for a tzolkin date and moves point ++to the previous occurrence of that date. Similarly, type @kbd{g m n t} ++to go to the next occurrence of a tzolkin date. ++ ++@findex calendar-mayan-previous-haab-date ++@findex calendar-mayan-next-haab-date ++@cindex Mayan haab calendar ++ The Mayan haab calendar is a cycle of 365 days arranged as 18 months ++of 20 days each, followed a 5-day monthless period. Like the tzolkin ++cycle, this cycle repeats endlessly, and there are commands to move ++backward and forward to the previous or next point in the cycle. Type ++@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab ++date and moves point to the previous occurrence of that date. ++Similarly, type @kbd{g m n h} to go to the next occurrence of a haab ++date. ++ ++@c This is omitted because it is too long for smallbook format. ++@c @findex calendar-mayan-previous-calendar-round-date ++@findex calendar-mayan-next-calendar-round-date ++@cindex Mayan calendar round ++ The Maya also used the combination of the tzolkin date and the haab ++date. This combination is a cycle of about 52 years called a ++@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for ++both a haab and a tzolkin date and then moves point to the previous ++occurrence of that combination. Use @kbd{g m n c} to move point to the ++next occurrence of a combination. These commands signal an error if the ++haab/tzolkin date combination you have typed is impossible. ++ ++ Emacs uses strict completion (@pxref{Strict Completion}) whenever it ++asks you to type a Mayan name, so you don't have to worry about ++spelling. ++ ++@node Diary ++@section The Diary ++@cindex diary ++ ++ The Emacs diary keeps track of appointments or other events on a daily ++basis, in conjunction with the calendar. To use the diary feature, you ++must first create a @dfn{diary file} containing a list of events and ++their dates. Then Emacs can automatically pick out and display the ++events for today, for the immediate future, or for any specified ++date. ++ ++ The name of the diary file is specified by the variable ++@code{diary-file}; @file{~/diary} is the default. Here's an example ++showing what that file looks like: ++ ++@example ++12/22/1988 Twentieth wedding anniversary!! ++&1/1. Happy New Year! ++10/22 Ruth's birthday. ++* 21, *: Payday ++Tuesday--weekly meeting with grad students at 10am ++ Supowit, Shen, Bitner, and Kapoor to attend. ++1/13/89 Friday the thirteenth!! ++&thu 4pm squash game with Lloyd. ++mar 16 Dad's birthday ++April 15, 1989 Income tax due. ++&* 15 time cards due. ++@end example ++ ++@noindent ++This format is essentially the same as the one used by the system's ++@command{calendar} utility. This example uses extra spaces to align ++the event descriptions of most of the entries. Such formatting is ++purely a matter of taste. ++ ++ Although you probably will start by creating a diary manually, Emacs ++provides a number of commands to let you view, add, and change diary ++entries. ++ ++@menu ++* Displaying the Diary:: Viewing diary entries and associated calendar dates. ++* Format of Diary File:: Entering events in your diary. ++* Date Formats:: Various ways you can specify dates. ++* Adding to Diary:: Commands to create diary entries. ++* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. ++@end menu ++ ++@node Displaying the Diary ++@subsection Displaying the Diary ++ ++ Once you have created a diary file, you can use the calendar to view ++it. You can also view today's events outside of Calendar mode. ++ ++@table @kbd ++@item d ++Display all diary entries for the selected date ++(@code{diary-view-entries}). ++@item Mouse-3 Diary ++Display all diary entries for the date you click on. ++@item s ++Display the entire diary file (@code{diary-show-all-entries}). ++@item m ++Mark all visible dates that have diary entries ++(@code{diary-mark-entries}). ++@item u ++Unmark the calendar window (@code{calendar-unmark}). ++@item M-x diary-print-entries ++Print hard copy of the diary display as it appears. ++@item M-x diary ++Display all diary entries for today's date. ++@item M-x diary-mail-entries ++Mail yourself email reminders about upcoming diary entries. ++@end table ++ ++@kindex d @r{(Calendar mode)} ++@findex diary-view-entries ++@vindex calendar-view-diary-initially-flag ++ Displaying the diary entries with @kbd{d} shows in a separate window ++the diary entries for the selected date in the calendar. The mode line ++of the new window shows the date of the diary entries and any holidays ++that fall on that date. If you specify a numeric argument with @kbd{d}, ++it shows all the diary entries for that many successive days. Thus, ++@kbd{2 d} displays all the entries for the selected date and for the ++following day. ++ ++ Another way to display the diary entries for a date is to click ++@kbd{Mouse-3} on the date, and then choose @kbd{Diary entries} from ++the menu that appears. If the variable ++@code{calendar-view-diary-initially-flag} is non-@code{nil}, creating the ++calendar lists the diary entries for the current date (provided the ++current date is visible). ++ ++@kindex m @r{(Calendar mode)} ++@findex diary-mark-entries ++@vindex calendar-mark-diary-entries-flag ++ To get a broader view of which days are mentioned in the diary, use ++the @kbd{m} command. This displays the dates that have diary entries in ++a different face. ++@iftex ++@inforef{Calendar Customizing, diary-entry-marker, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Calendar Customizing, diary-entry-marker}. ++@end ifnottex ++ ++ The command applies both to the currently visible months and to ++other months that subsequently become visible by scrolling. To turn ++marking off and erase the current marks, type @kbd{u}, which also ++turns off holiday marks (@pxref{Holidays}). If the variable ++@code{calendar-mark-diary-entries-flag} is non-@code{nil}, creating or ++updating the calendar marks diary dates automatically. ++ ++@kindex s @r{(Calendar mode)} ++@findex diary-show-all-entries ++ To see the full diary file, rather than just some of the entries, use ++the @kbd{s} command. ++ ++ Display of selected diary entries uses invisible text to hide entries ++that don't apply. The diary buffer as you see it is an illusion, so ++simply printing the buffer does not print what you see on your screen. ++There is a special command to print hard copy of the diary buffer ++@emph{as it appears}; this command is @kbd{M-x diary-print-entries}. ++It sends the data directly to the printer. You can customize it ++like @code{lpr-region} (@pxref{Printing}). ++ ++@findex diary ++ The command @kbd{M-x diary} displays the diary entries for the current ++date, independently of the calendar display, and optionally for the next ++few days as well; the variable @code{diary-number-of-entries} specifies ++how many days to include. ++@iftex ++@inforef{Diary Customizing,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Diary Customizing, diary-number-of-entries}. ++@end ifnottex ++ ++ If you put @code{(diary)} in your @file{.emacs} file, this ++automatically displays a window with the day's diary entries, when you ++enter Emacs. The mode line of the displayed window shows the date and ++any holidays that fall on that date. ++ ++@findex diary-mail-entries ++@vindex diary-mail-days ++ Many users like to receive notice of events in their diary as email. ++To send such mail to yourself, use the command @kbd{M-x ++diary-mail-entries}. A prefix argument specifies how many days ++(starting with today) to check; otherwise, the variable ++@code{diary-mail-days} says how many days. ++ ++@node Format of Diary File ++@subsection The Diary File ++@cindex diary file ++ ++@vindex diary-file ++ Your @dfn{diary file} is a file that records events associated with ++particular dates. The name of the diary file is specified by the ++variable @code{diary-file}; @file{~/diary} is the default. The ++@code{calendar} utility program supports a subset of the format allowed ++by the Emacs diary facilities, so you can use that utility to view the ++diary file, with reasonable results aside from the entries it cannot ++understand. ++ ++ Each entry in the diary file describes one event and consists of one ++or more lines. An entry always begins with a date specification at the ++left margin. The rest of the entry is simply text to describe the ++event. If the entry has more than one line, then the lines after the ++first must begin with whitespace to indicate they continue a previous ++entry. Lines that do not begin with valid dates and do not continue a ++preceding entry are ignored. ++ ++@vindex diary-nonmarking-symbol ++ You can inhibit the marking of certain diary entries in the calendar ++window; to do this, insert an ampersand @code{diary-nonmarking-symbol} ++(default @samp{&}) at the beginning of the entry, before the date. This ++has no effect on display of the entry in the diary window; it affects ++only marks on dates in the calendar window. Nonmarking entries are ++especially useful for generic entries that would otherwise mark many ++different dates. ++ ++ If the first line of a diary entry consists only of the date or day ++name with no following blanks or punctuation, then the diary window ++display doesn't include that line; only the continuation lines appear. ++For example, this entry: ++ ++@example ++02/11/1989 ++ Bill B. visits Princeton today ++ 2pm Cognitive Studies Committee meeting ++ 2:30-5:30 Liz at Lawrenceville ++ 4:00pm Dentist appt ++ 7:30pm Dinner at George's ++ 8:00-10:00pm concert ++@end example ++ ++@noindent ++appears in the diary window without the date line at the beginning. ++This style of entry looks neater when you display just a single day's ++entries, but can cause confusion if you ask for more than one day's ++entries. ++ ++ You can edit the diary entries as they appear in the window, but it is ++important to remember that the buffer displayed contains the @emph{entire} ++diary file, with portions of it concealed from view. This means, for ++instance, that the @kbd{C-f} (@code{forward-char}) command can put point ++at what appears to be the end of the line, but what is in reality the ++middle of some concealed line. ++ ++ @emph{Be careful when editing the diary entries!} Inserting ++additional lines or adding/deleting characters in the middle of a ++visible line cannot cause problems, but editing at the end of a line may ++not do what you expect. Deleting a line may delete other invisible ++entries that follow it. Before editing the diary, it is best to display ++the entire file with @kbd{s} (@code{diary-show-all-entries}). ++ ++@node Date Formats ++@subsection Date Formats ++ ++ Here are some sample diary entries, illustrating different ways of ++formatting a date. The examples all show dates in American order ++(month, day, year), but Calendar mode supports European order (day, ++month, year) and ISO order (year, month, day) as options. ++ ++@example ++4/20/93 Switch-over to new tabulation system ++apr. 25 Start tabulating annual results ++4/30 Results for April are due ++*/25 Monthly cycle finishes ++Friday Don't leave without backing up files ++@end example ++ ++ The first entry appears only once, on April 20, 1993. The second and ++third appear every year on the specified dates, and the fourth uses a ++wildcard (asterisk) for the month, so it appears on the 25th of every ++month. The final entry appears every week on Friday. ++ ++ You can use just numbers to express a date, as in ++@samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}. ++This must be followed by a nondigit. In the date itself, @var{month} ++and @var{day} are numbers of one or two digits. The optional @var{year} ++is also a number, and may be abbreviated to the last two digits; that ++is, you can use @samp{11/12/1989} or @samp{11/12/89}. ++ ++ Dates can also have the form @samp{@var{monthname} @var{day}} or ++@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can ++be spelled in full or abbreviated (with or without a period). The ++preferred abbreviations for month and day names can be set using ++the variables @code{calendar-abbrev-length}, ++@code{calendar-month-abbrev-array}, and ++@code{calendar-day-abbrev-array}. The default is to use the first three ++letters of a name as its abbreviation. Case is not significant. ++ ++ A date may be @dfn{generic}; that is, partially unspecified. Then the ++entry applies to all dates that match the specification. If the date ++does not contain a year, it is generic and applies to any year. ++Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*}; ++this matches any month, day, or year, respectively. Thus, a diary entry ++@samp{3/*/*} matches any day in March of any year; so does @samp{march ++*}. ++ ++@vindex calendar-date-style ++@findex calendar-set-date-style ++ If you prefer the European style of writing dates (in which the day ++comes before the month), or the ISO style (in which the order is year, ++month, day), type @kbd{M-x calendar-set-date-style} while in the ++calendar, or customize the variable @code{calendar-date-style}. This ++affects how diary dates are interpreted, date display, and the order in ++which some commands expect their arguments to be given. ++ ++ You can use the name of a day of the week as a generic date which ++applies to any date falling on that day of the week. You can abbreviate ++the day of the week as described above, or spell it in full; case is not ++significant. ++ ++@node Adding to Diary ++@subsection Commands to Add to the Diary ++ ++ While in the calendar, there are several commands to create diary ++entries. The basic commands are listed here; more sophisticated ++commands are in the next section (@pxref{Special Diary Entries}). ++Entries can also be based on non-Gregorian calendars. ++@iftex ++@inforef{Non-Gregorian Diary,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Non-Gregorian Diary}. ++@end ifnottex ++ ++@table @kbd ++@item i d ++Add a diary entry for the selected date (@code{diary-insert-entry}). ++@item i w ++Add a diary entry for the selected day of the week (@code{diary-insert-weekly-entry}). ++@item i m ++Add a diary entry for the selected day of the month (@code{diary-insert-monthly-entry}). ++@item i y ++Add a diary entry for the selected day of the year (@code{diary-insert-yearly-entry}). ++@end table ++ ++@kindex i d @r{(Calendar mode)} ++@findex diary-insert-entry ++ You can make a diary entry for a specific date by selecting that date ++in the calendar window and typing the @kbd{i d} command. This command ++displays the end of your diary file in another window and inserts the ++date; you can then type the rest of the diary entry. ++ ++@kindex i w @r{(Calendar mode)} ++@findex diary-insert-weekly-entry ++@kindex i m @r{(Calendar mode)} ++@findex diary-insert-monthly-entry ++@kindex i y @r{(Calendar mode)} ++@findex diary-insert-yearly-entry ++ If you want to make a diary entry that applies to a specific day of ++the week, select that day of the week (any occurrence will do) and type ++@kbd{i w}. This inserts the day-of-week as a generic date; you can then ++type the rest of the diary entry. You can make a monthly diary entry in ++the same fashion: select the day of the month, use the @kbd{i m} ++command, and type the rest of the entry. Similarly, you can insert a ++yearly diary entry with the @kbd{i y} command. ++ ++ All of the above commands make marking diary entries by default. To ++make a nonmarking diary entry, give a numeric argument to the command. ++For example, @kbd{C-u i w} makes a nonmarking weekly diary entry. ++ ++ When you modify the diary file, be sure to save the file before ++exiting Emacs. Saving the diary file after using any of the above ++insertion commands will automatically update the diary marks in the ++calendar window, if appropriate. You can use the command ++@code{calendar-redraw} to force an update at any time. ++ ++@node Special Diary Entries ++@subsection Special Diary Entries ++ ++ In addition to entries based on calendar dates, the diary file can ++contain @dfn{sexp entries} for regular events such as anniversaries. ++These entries are based on Lisp expressions (sexps) that Emacs evaluates ++as it scans the diary file. Instead of a date, a sexp entry contains ++@samp{%%} followed by a Lisp expression which must begin and end with ++parentheses. The Lisp expression determines which dates the entry ++applies to. ++ ++ Calendar mode provides commands to insert certain commonly used ++sexp entries: ++ ++@table @kbd ++@item i a ++Add an anniversary diary entry for the selected date ++(@code{diary-insert-anniversary-entry}). ++@item i b ++Add a block diary entry for the current region ++(@code{diary-insert-block-entry}). ++@item i c ++Add a cyclic diary entry starting at the date ++(@code{diary-insert-cyclic-entry}). ++@end table ++ ++@kindex i a @r{(Calendar mode)} ++@findex diary-insert-anniversary-entry ++ If you want to make a diary entry that applies to the anniversary of a ++specific date, move point to that date and use the @kbd{i a} command. ++This displays the end of your diary file in another window and inserts ++the anniversary description; you can then type the rest of the diary ++entry. The entry looks like this: ++ ++@findex diary-anniversary ++@example ++%%(diary-anniversary 10 31 1948) Arthur's birthday ++@end example ++ ++@noindent ++This entry applies to October 31 in any year after 1948; @samp{10 31 ++1948} specifies the date. (If you are using the European or ISO ++calendar style, the input order of month, day and year is different.) ++The reason this expression requires a beginning year is that advanced ++diary functions can use it to calculate the number of elapsed years. ++ ++ A @dfn{block} diary entry applies to a specified range of consecutive ++dates. Here is a block diary entry that applies to all dates from June ++24, 1990 through July 10, 1990: ++ ++@findex diary-block ++@example ++%%(diary-block 6 24 1990 7 10 1990) Vacation ++@end example ++ ++@noindent ++The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990} ++indicates the stopping date. (Again, if you are using the European or ISO ++calendar style, the input order of month, day and year is different.) ++ ++@kindex i b @r{(Calendar mode)} ++@findex diary-insert-block-entry ++ To insert a block entry, place point and the mark on the two ++dates that begin and end the range, and type @kbd{i b}. This command ++displays the end of your diary file in another window and inserts the ++block description; you can then type the diary entry. ++ ++@kindex i c @r{(Calendar mode)} ++@findex diary-insert-cyclic-entry ++ @dfn{Cyclic} diary entries repeat after a fixed interval of days. To ++create one, select the starting date and use the @kbd{i c} command. The ++command prompts for the length of interval, then inserts the entry, ++which looks like this: ++ ++@findex diary-cyclic ++@example ++%%(diary-cyclic 50 3 1 1990) Renew medication ++@end example ++ ++@noindent ++This entry applies to March 1, 1990 and every 50th day following; ++@samp{3 1 1990} specifies the starting date. (If you are using the ++European or ISO calendar style, the input order of month, day and year ++is different.) ++ ++ All three of these commands make marking diary entries. To insert a ++nonmarking entry, give a numeric argument to the command. For example, ++@kbd{C-u i a} makes a nonmarking anniversary diary entry. ++ ++ Marking sexp diary entries in the calendar is @emph{extremely} ++time-consuming, since every date visible in the calendar window must be ++individually checked. So it's a good idea to make sexp diary entries ++nonmarking (with @samp{&}) when possible. ++ ++ Another sophisticated kind of sexp entry, a @dfn{floating} diary entry, ++specifies a regularly occurring event by offsets specified in days, ++weeks, and months. It is comparable to a crontab entry interpreted by ++the @code{cron} utility. Here is a nonmarking, floating diary entry ++that applies to the fourth Thursday in November: ++ ++@findex diary-float ++@example ++&%%(diary-float 11 4 4) American Thanksgiving ++@end example ++ ++@noindent ++The 11 specifies November (the eleventh month), the 4 specifies Thursday ++(the fourth day of the week, where Sunday is numbered zero), and the ++second 4 specifies the fourth Thursday (1 would mean ``first,'' 2 would ++mean ``second,'' @minus{}2 would mean ``second-to-last,'' and so on). ++The month can be a single month or a list of months. Thus you could change ++the 11 above to @samp{'(1 2 3)} and have the entry apply to the last ++Thursday of January, February, and March. If the month is @code{t}, the ++entry applies to all months of the year.@refill ++ ++ Each of the standard sexp diary entries takes an optional parameter ++specifying the name of a face or a single-character string to use when ++marking the entry in the calendar. Most generally, sexp diary entries ++can perform arbitrary computations to determine when they apply. ++@iftex ++@inforef{Sexp Diary Entries,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Sexp Diary Entries}. ++@end ifnottex ++ ++@node Appointments ++@section Appointments ++@cindex appointment notification ++ ++@vindex appt-display-format ++@vindex appt-audible ++@vindex appt-display-mode-line ++ If you have a diary entry for an appointment, and that diary entry ++begins with a recognizable time of day, Emacs can warn you several ++minutes beforehand that that appointment is pending. Emacs alerts you ++to the appointment by displaying a message in your chosen format, as ++specified by the variable @code{appt-display-format}. If the value of ++@code{appt-audible} is non-@code{nil}, the warning includes an audible ++reminder. In addition, if @code{appt-display-mode-line} is ++non-@code{nil}, Emacs displays the number of minutes to the ++appointment on the mode line. ++ ++@vindex appt-display-duration ++@vindex appt-disp-window-function ++@vindex appt-delete-window-function ++ If @code{appt-display-format} has the value @code{window}, then the ++variable @code{appt-display-duration} controls how long the reminder ++window is visible for; and the variables ++@code{appt-disp-window-function} and @code{appt-delete-window-function} ++give the names of functions used to create and destroy the window, ++respectively. ++ ++@findex appt-activate ++ To enable appointment notification, use the command @kbd{M-x ++appt-activate}. With a positive argument, it enables notification; ++with a negative argument, it disables notification; with no argument, ++it toggles. Enabling notification also sets up an appointment list ++for today from the diary file, giving all diary entries found with ++recognizable times of day, and reminds you just before each of them. ++ ++ For example, suppose the diary file contains these lines: ++ ++@example ++Monday ++ 9:30am Coffee break ++ 12:00pm Lunch ++@end example ++ ++@vindex appt-message-warning-time ++@noindent ++Then on Mondays, you will be reminded at around 9:20am about your ++coffee break and at around 11:50am about lunch. The variable ++@code{appt-message-warning-time} specifies how many minutes (default 12) ++in advance to warn you. ++ ++ You can write times in am/pm style (with @samp{12:00am} standing ++for midnight and @samp{12:00pm} standing for noon), or 24-hour ++European/military style. You need not be consistent; your diary file ++can have a mixture of the two styles. Times must be at the beginning of ++diary entries if they are to be recognized. ++ ++@vindex appt-display-diary ++ Emacs updates the appointments list from the diary file ++automatically just after midnight. You can force an update at any ++time by re-enabling appointment notification. Both these actions also ++display the day's diary buffer, unless you set ++@code{appt-display-diary} to @code{nil}. The appointments list is ++also updated whenever the diary file is saved. ++ ++@findex appt-add ++@findex appt-delete ++@cindex alarm clock ++ You can also use the appointment notification facility like an alarm ++clock. The command @kbd{M-x appt-add} adds entries to the appointment ++list without affecting your diary file. You delete entries from the ++appointment list with @kbd{M-x appt-delete}. ++ ++@node Importing Diary ++@section Importing and Exporting Diary Entries ++ ++ You can transfer diary entries between Emacs diary files and a ++variety of other formats. ++ ++@vindex diary-outlook-formats ++ You can import diary entries from Outlook-generated appointment ++messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x ++diary-from-outlook} to import the entry. You can make this command ++recognize additional appointment message formats by customizing the ++variable @code{diary-outlook-formats}. ++ ++@cindex iCalendar support ++ The icalendar package allows you to transfer data between your Emacs ++diary file and iCalendar files, which are defined in ``RFC ++2445---Internet Calendaring and Scheduling Core Object Specification ++(iCalendar)'' (as well as the earlier vCalendar format). ++ ++@c Importing works for ``ordinary'' (i.e. non-recurring) events, but ++@c (at present) may not work correctly (if at all) for recurring events. ++@c Exporting of diary files into iCalendar files should work correctly ++@c for most diary entries. This feature is a work in progress, so the ++@c commands may evolve in future. ++ ++@findex icalendar-import-buffer ++ The command @code{icalendar-import-buffer} extracts ++iCalendar data from the current buffer and adds it to your (default) ++diary file. This function is also suitable for automatic extraction of ++iCalendar data; for example with the Rmail mail client one could use: ++ ++@example ++(add-hook 'rmail-show-message-hook 'icalendar-import-buffer) ++@end example ++ ++@findex icalendar-import-file ++ The command @code{icalendar-import-file} imports an iCalendar file ++and adds the results to an Emacs diary file. For example: ++ ++@example ++(icalendar-import-file "/here/is/calendar.ics" ++ "/there/goes/ical-diary") ++@end example ++ ++@noindent ++You can use an @code{#include} directive to add the import file contents ++to the main diary file, if these are different files. ++@iftex ++@inforef{Fancy Diary Display,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Fancy Diary Display}. ++@end ifnottex ++ ++ ++@findex icalendar-export-file, icalendar-export-region ++ Use @code{icalendar-export-file} to interactively export an entire ++Emacs diary file to iCalendar format. To export only a part of a diary ++file, mark the relevant area, and call @code{icalendar-export-region}. ++In both cases the result is appended to the target file. ++ ++@node Daylight Saving ++@section Daylight Saving Time ++@cindex daylight saving time ++ ++ Emacs understands the difference between standard time and daylight ++saving time---the times given for sunrise, sunset, solstices, ++equinoxes, and the phases of the moon take that into account. The rules ++for daylight saving time vary from place to place and have also varied ++historically from year to year. To do the job properly, Emacs needs to ++know which rules to use. ++ ++@vindex calendar-daylight-savings-starts ++@vindex calendar-daylight-savings-ends ++ Some operating systems keep track of the rules that apply to the place ++where you are; on these systems, Emacs gets the information it needs ++from the system automatically. If some or all of this information is ++missing, Emacs fills in the gaps with the rules currently used in ++Cambridge, Massachusetts. If the resulting rules are not what you want, ++you can tell Emacs the rules to use by setting certain variables: ++@code{calendar-daylight-savings-starts} and ++@code{calendar-daylight-savings-ends}. ++ ++ These values should be Lisp expressions that refer to the variable ++@code{year}, and evaluate to the Gregorian date on which daylight ++saving time starts or (respectively) ends, in the form of a list ++@code{(@var{month} @var{day} @var{year})}. The values should be ++@code{nil} if your area does not use daylight saving time. ++ ++ Emacs uses these expressions to determine the starting date of ++daylight saving time for the holiday list and for correcting times of ++day in the solar and lunar calculations. ++ ++ The values for Cambridge, Massachusetts are as follows: ++ ++@example ++(calendar-nth-named-day 2 0 3 year) ++(calendar-nth-named-day 1 0 11 year) ++@end example ++ ++@noindent ++That is, the second 0th day (Sunday) of the third month (March) in ++the year specified by @code{year}, and the first Sunday of the eleventh month ++(November) of that year. If daylight saving time were ++changed to start on October 1, you would set ++@code{calendar-daylight-savings-starts} to this: ++ ++@example ++(list 10 1 year) ++@end example ++ ++ If there is no daylight saving time at your location, or if you want ++all times in standard time, set @code{calendar-daylight-savings-starts} ++and @code{calendar-daylight-savings-ends} to @code{nil}. ++ ++@vindex calendar-daylight-time-offset ++ The variable @code{calendar-daylight-time-offset} specifies the ++difference between daylight saving time and standard time, measured in ++minutes. The value for Cambridge, Massachusetts is 60. ++ ++@c @vindex calendar-daylight-savings-starts-time too long! ++@vindex calendar-daylight-savings-ends-time ++ Finally, the two variables ++@code{calendar-daylight-savings-starts-time} and ++@code{calendar-daylight-savings-ends-time} specify the number of ++minutes after midnight local time when the transition to and from ++daylight saving time should occur. For Cambridge, Massachusetts both ++variables' values are 120. ++ ++@node Time Intervals ++@section Summing Time Intervals ++@cindex time intervals, summing ++@cindex summing time intervals ++@cindex timeclock ++ ++ The timeclock package adds up time intervals, so you can (for ++instance) keep track of how much time you spend working on particular ++projects. ++ ++@findex timeclock-in ++@findex timeclock-out ++@findex timeclock-change ++@findex timeclock-workday-remaining ++@findex timeclock-when-to-leave ++ Use the @kbd{M-x timeclock-in} command when you start working on a ++project, and @kbd{M-x timeclock-out} command when you're done. Each ++time you do this, it adds one time interval to the record of the ++project. You can change to working on a different project with @kbd{M-x ++timeclock-change}. ++ ++ Once you've collected data from a number of time intervals, you can use ++@kbd{M-x timeclock-workday-remaining} to see how much time is left to ++work today (assuming a typical average of 8 hours a day), and @kbd{M-x ++timeclock-when-to-leave} which will calculate when you're ``done.'' ++ ++@vindex timeclock-modeline-display ++@findex timeclock-modeline-display ++ If you want Emacs to display the amount of time ``left'' of your ++workday in the mode line, either customize the ++@code{timeclock-modeline-display} variable and set its value to ++@code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command. ++ ++@vindex timeclock-ask-before-exiting ++ Terminating the current Emacs session might or might not mean that ++you have stopped working on the project and, by default, Emacs asks ++you. You can, however, set customize the value of the variable ++@code{timeclock-ask-before-exiting} to @code{nil} to avoid the question; ++then, only an explicit @kbd{M-x timeclock-out} or @kbd{M-x ++timeclock-change} will tell Emacs that the current interval is over. ++ ++@cindex @file{.timelog} file ++@vindex timeclock-file ++@findex timeclock-reread-log ++ The timeclock functions work by accumulating the data in a file ++called @file{.timelog} in your home directory. You can specify a ++different name for this file by customizing the variable ++@code{timeclock-file}. If you edit the timeclock file manually, or if ++you change the value of any of timeclock's customizable variables, you ++should run the command @kbd{M-x timeclock-reread-log} to update the ++data in Emacs from the file. ++ ++@ifnottex ++@include cal-xtra.texi ++@end ifnottex ++ ++@ignore ++ arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92 ++@end ignore +diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi +new file mode 100644 +index 0000000..2d4d8b3 +--- /dev/null ++++ b/doc/emacs/cmdargs.texi +@@ -0,0 +1,1414 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Emacs Invocation, X Resources, GNU Free Documentation License, Top ++@appendix Command Line Arguments for Emacs Invocation ++@cindex command line arguments ++@cindex arguments (command line) ++@cindex options (command line) ++@cindex switches (command line) ++@cindex startup (command line arguments) ++@cindex invocation (command line arguments) ++ ++ Emacs supports command line arguments to request various actions ++when invoking Emacs. These are for compatibility with other editors ++and for sophisticated activities. We don't recommend using them for ++ordinary editing (@xref{Emacs Server}, for a way to access an existing ++Emacs job from the command line). ++ ++ Arguments starting with @samp{-} are @dfn{options}, and so is ++@samp{+@var{linenum}}. All other arguments specify files to visit. ++Emacs visits the specified files while it starts up. The last file ++specified on the command line becomes the current buffer; the other ++files are also visited in other buffers. As with most programs, the ++special argument @samp{--} says that all subsequent arguments are file ++names, not options, even if they start with @samp{-}. ++ ++ Emacs command options can specify many things, such as the size and ++position of the X window Emacs uses, its colors, and so on. A few ++options support advanced usage, such as running Lisp functions on files ++in batch mode. The sections of this chapter describe the available ++options, arranged according to their purpose. ++ ++ There are two ways of writing options: the short forms that start with ++a single @samp{-}, and the long forms that start with @samp{--}. For ++example, @samp{-d} is a short form and @samp{--display} is the ++corresponding long form. ++ ++ The long forms with @samp{--} are easier to remember, but longer to ++type. However, you don't have to spell out the whole option name; any ++unambiguous abbreviation is enough. When a long option takes an ++argument, you can use either a space or an equal sign to separate the ++option name and the argument. Thus, you can write either ++@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}. ++We recommend an equal sign because it makes the relationship clearer, ++and the tables below always show an equal sign. ++ ++@cindex initial options (command line) ++@cindex action options (command line) ++@vindex command-line-args ++ Most options specify how to initialize Emacs, or set parameters for ++the Emacs session. We call them @dfn{initial options}. A few options ++specify things to do, such as loading libraries or calling Lisp ++functions. These are called @dfn{action options}. These and file ++names together are called @dfn{action arguments}. The action ++arguments are stored as a list of strings in the variable ++@code{command-line-args}. (Actually, when Emacs starts up, ++@code{command-line-args} contains all the arguments passed from the ++command line; during initialization, the initial arguments are removed ++from this list when they are processed, leaving only the action ++arguments.) ++ ++@menu ++* Action Arguments:: Arguments to visit files, load libraries, ++ and call functions. ++* Initial Options:: Arguments that take effect while starting Emacs. ++* Command Example:: Examples of using command line arguments. ++* Resume Arguments:: Specifying arguments when you resume a running Emacs. ++* Environment:: Environment variables that Emacs uses. ++* Display X:: Changing the default display and using remote login. ++* Font X:: Choosing a font for text, under X. ++* Colors:: Choosing display colors. ++* Window Size X:: Start-up window size, under X. ++* Borders X:: Internal and external borders, under X. ++* Title X:: Specifying the initial frame's title. ++* Icons X:: Choosing what sort of icon to use, under X. ++* Misc X:: Other display options. ++@end menu ++ ++@node Action Arguments ++@appendixsec Action Arguments ++ ++ Here is a table of action arguments: ++ ++@table @samp ++@item @var{file} ++@opindex --file ++@itemx --file=@var{file} ++@opindex --find-file ++@itemx --find-file=@var{file} ++@opindex --visit ++@itemx --visit=@var{file} ++@cindex visiting files, command-line argument ++@vindex inhibit-startup-buffer-menu ++Visit @var{file} using @code{find-file}. @xref{Visiting}. ++ ++When Emacs starts up, it displays the startup buffer in one window, ++and the buffer visiting @var{file} in another window ++(@pxref{Windows}). If you supply more than one file argument, the ++displayed file is the last one specified on the command line; the ++other files are visited but their buffers are not shown. ++ ++If the startup buffer is disabled (@pxref{Entering Emacs}), then ++@var{file} is visited in a single window if one file argument was ++supplied; with two file arguments, Emacs displays the files in two ++different windows; with more than two file argument, Emacs displays ++the last file specified in one window, plus a Buffer Menu in a ++different window (@pxref{Several Buffers}). To inhibit using the ++Buffer Menu for this, change the variable ++@code{inhibit-startup-buffer-menu} to @code{t}. ++ ++@item +@var{linenum} @var{file} ++@opindex +@var{linenum} ++Visit @var{file} using @code{find-file}, then go to line number ++@var{linenum} in it. ++ ++@item +@var{linenum}:@var{columnnum} @var{file} ++Visit @var{file} using @code{find-file}, then go to line number ++@var{linenum} and put point at column number @var{columnnum}. ++ ++@item -l @var{file} ++@opindex -l ++@itemx --load=@var{file} ++@opindex --load ++@cindex loading Lisp libraries, command-line argument ++Load a Lisp library named @var{file} with the function @code{load}. ++@xref{Lisp Libraries}. If @var{file} is not an absolute file name, ++the library can be found either in the current directory, or in the ++Emacs library search path as specified with @env{EMACSLOADPATH} ++(@pxref{General Variables}). ++ ++@strong{Warning:} If previous command-line arguments have visited ++files, the current directory is the directory of the last file ++visited. ++ ++@item -L @var{dir} ++@opindex -L ++@itemx --directory=@var{dir} ++@opindex --directory ++Add directory @var{dir} to the variable @code{load-path}. ++ ++@item -f @var{function} ++@opindex -f ++@itemx --funcall=@var{function} ++@opindex --funcall ++@cindex call Lisp functions, command-line argument ++Call Lisp function @var{function}. If it is an interactive function ++(a command), it reads the arguments interactively just as if you had ++called the same function with a key sequence. Otherwise, it calls the ++function with no arguments. ++ ++@item --eval=@var{expression} ++@opindex --eval ++@itemx --execute=@var{expression} ++@opindex --execute ++@cindex evaluate expression, command-line argument ++Evaluate Lisp expression @var{expression}. ++ ++@item --insert=@var{file} ++@opindex --insert ++@cindex insert file contents, command-line argument ++Insert the contents of @var{file} into the @samp{*scratch*} buffer ++(@pxref{Lisp Interaction}). This is like what @kbd{M-x insert-file} ++does (@pxref{Misc File Ops}). ++ ++@item --kill ++@opindex --kill ++Exit from Emacs without asking for confirmation. ++ ++@item --help ++@opindex --help ++Print a usage message listing all available options, then exit ++successfully. ++ ++@item --version ++@opindex --version ++Print Emacs version, then exit successfully. ++@end table ++ ++@node Initial Options ++@appendixsec Initial Options ++ ++ The initial options specify parameters for the Emacs session. This ++section describes the more general initial options; some other options ++specifically related to the X Window System appear in the following ++sections. ++ ++ Some initial options affect the loading of the initialization file. ++The normal actions of Emacs are to first load @file{site-start.el} if ++it exists, then your own initialization file @file{~/.emacs} if it ++exists, and finally @file{default.el} if it exists. @xref{Init File}. ++Certain options prevent loading of some of these files or substitute ++other files for them. ++ ++@table @samp ++@item -t @var{device} ++@opindex -t ++@itemx --terminal=@var{device} ++@opindex --terminal ++@cindex device for Emacs terminal I/O ++Use @var{device} as the device for terminal input and output. ++@samp{--terminal} implies @samp{--no-window-system}. ++ ++@item -d @var{display} ++@opindex -d ++@itemx --display=@var{display} ++@opindex --display ++@cindex display for Emacs frame ++Use the X Window System and use the display named @var{display} to open ++the initial Emacs frame. @xref{Display X}, for more details. ++ ++@item -nw ++@opindex -nw ++@itemx --no-window-system ++@opindex --no-window-system ++@cindex disable window system ++Don't communicate directly with the window system, disregarding the ++@env{DISPLAY} environment variable even if it is set. This means that ++Emacs uses the terminal from which it was launched for all its display ++and input. ++ ++@cindex batch mode ++@item -batch ++@opindex --batch ++@itemx --batch ++Run Emacs in @dfn{batch mode}. Batch mode is used for running ++programs written in Emacs Lisp from shell scripts, makefiles, and so ++on. To invoke a Lisp program, use the @samp{-batch} option in ++conjunction with one or more of @samp{-l}, @samp{-f} or @samp{--eval} ++(@pxref{Action Arguments}). @xref{Command Example}, for an example. ++ ++In batch mode, Emacs does not display the text being edited, and the ++standard terminal interrupt characters such as @kbd{C-z} and @kbd{C-c} ++have their usual effect. Emacs functions that normally print a ++message in the echo area will print to either the standard output ++stream (@code{stdout}) or the standard error stream (@code{stderr}) ++instead. (To be precise, functions like @code{prin1}, @code{princ} ++and @code{print} print to @code{stdout}, while @code{message} and ++@code{error} print to @code{stderr}.) Functions that normally read ++keyboard input from the minibuffer take their input from the ++terminal's standard input stream (@code{stdin}) instead. ++ ++@samp{--batch} implies @samp{-q} (do not load an initialization file), ++but @file{site-start.el} is loaded nonetheless. It also causes Emacs ++to exit after processing all the command options. In addition, it ++disables auto-saving except in buffers for which it has been ++explicitly requested. ++ ++@item --script @var{file} ++@opindex --script ++@cindex script mode ++Run Emacs in batch mode, like @samp{--batch}, and then read and ++execute the Lisp code in @var{file}. ++ ++The normal use of this option is in executable script files that run ++Emacs. They can start with this text on the first line ++ ++@example ++#!/usr/bin/emacs --script ++@end example ++ ++@noindent ++which will invoke Emacs with @samp{--script} and supply the name of ++the script file as @var{file}. Emacs Lisp then treats @samp{#!} as a ++comment delimiter. ++ ++@item -q ++@opindex -q ++@itemx --no-init-file ++@opindex --no-init-file ++@cindex bypassing init and @file{default.el} file ++@cindex init file, not loading ++@cindex @file{default.el} file, not loading ++Do not load your Emacs initialization file, and do not load the file ++@file{default.el} either (@pxref{Init File}). Regardless of this ++switch, @file{site-start.el} is still loaded. When Emacs is invoked ++like this, the Customize facility does not allow options to be saved ++(@pxref{Easy Customization}). ++ ++@item --no-site-file ++@opindex --no-site-file ++@cindex @file{site-start.el} file, not loading ++Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u} ++and @samp{--batch} have no effect on the loading of this file---this ++option and @samp{-Q} are the only options that block it. ++ ++@item --no-splash ++@opindex --no-splash ++@vindex inhibit-startup-screen ++@cindex splash screen ++@cindex startup message ++Do not display a startup screen. You can also achieve this effect by ++setting the variable @code{inhibit-startup-screen} to non-@code{nil} ++in your initialization file (@pxref{Entering Emacs}). ++ ++@item -Q ++@opindex -Q ++@itemx --quick ++@opindex --quick ++Start emacs with minimum customizations. This is like using ++@samp{-q}, @samp{--no-site-file}, and @samp{--no-splash} together. ++ ++@item -daemon ++@opindex -daemon ++@itemx --daemon ++@opindex --daemon ++Start Emacs as a daemon---after Emacs starts up, it starts the Emacs ++server and disconnects from the terminal without opening any frames. ++You can then use the @command{emacsclient} command to connect to Emacs ++for editing. @xref{Emacs Server}, for information about using Emacs ++as a daemon. ++ ++@item -daemon=@var{SERVER-NAME} ++Start emacs in background as a daemon, and use @var{SERVER-NAME} as ++the server name. ++ ++@item --no-desktop ++@opindex --no-desktop ++Do not reload any saved desktop. @xref{Saving Emacs Sessions}. ++ ++@item -u @var{user} ++@opindex -u ++@itemx --user=@var{user} ++@opindex --user ++@cindex load init file of another user ++Load @var{user}'s initialization file instead of your ++own@footnote{This option has no effect on MS-Windows.}. ++ ++@item --debug-init ++@opindex --debug-init ++@cindex errors in init file ++Enable the Emacs Lisp debugger for errors in the init file. ++@xref{Error Debugging,, Entering the Debugger on an Error, elisp, The ++GNU Emacs Lisp Reference Manual}. ++ ++@item --unibyte ++@opindex --unibyte ++@itemx --no-multibyte ++@opindex --no-multibyte ++@cindex unibyte operation, command-line argument ++Do almost everything with single-byte buffers and strings. ++All buffers and strings are unibyte unless you (or a Lisp program) ++explicitly ask for a multibyte buffer or string. (Note that Emacs ++always loads Lisp files in multibyte mode, even if @samp{--unibyte} is ++specified; see @ref{Enabling Multibyte}.) Setting the environment ++variable @env{EMACS_UNIBYTE} has the same effect ++(@pxref{General Variables}). ++ ++@item --multibyte ++@opindex --multibyte ++@itemx --no-unibyte ++@opindex --no-unibyte ++Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs ++uses multibyte characters by default, as usual. ++@end table ++ ++@node Command Example ++@appendixsec Command Argument Example ++ ++ Here is an example of using Emacs with arguments and options. It ++assumes you have a Lisp program file called @file{hack-c.el} which, when ++loaded, performs some useful operation on the current buffer, expected ++to be a C program. ++ ++@example ++emacs --batch foo.c -l hack-c -f save-buffer >& log ++@end example ++ ++@noindent ++This says to visit @file{foo.c}, load @file{hack-c.el} (which makes ++changes in the visited file), save @file{foo.c} (note that ++@code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and ++then exit back to the shell (because of @samp{--batch}). @samp{--batch} ++also guarantees there will be no problem redirecting output to ++@file{log}, because Emacs will not assume that it has a display terminal ++to work with. ++ ++@node Resume Arguments ++@appendixsec Resuming Emacs with Arguments ++ ++ You can specify action arguments for Emacs when you resume it after ++a suspension. To prepare for this, put the following code in your ++@file{.emacs} file (@pxref{Hooks}): ++ ++@c `resume-suspend-hook' is correct. It is the name of a function. ++@example ++(add-hook 'suspend-hook 'resume-suspend-hook) ++(add-hook 'suspend-resume-hook 'resume-process-args) ++@end example ++ ++ As further preparation, you must execute the shell script ++@file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} ++(if you use bash as your shell). These scripts define an alias named ++@code{edit}, which will resume Emacs giving it new command line ++arguments such as files to visit. The scripts are found in the ++@file{etc} subdirectory of the Emacs distribution. ++ ++ Only action arguments work properly when you resume Emacs. Initial ++arguments are not recognized---it's too late to execute them anyway. ++ ++ Note that resuming Emacs (with or without arguments) must be done from ++within the shell that is the parent of the Emacs job. This is why ++@code{edit} is an alias rather than a program or a shell script. It is ++not possible to implement a resumption command that could be run from ++other subjobs of the shell; there is no way to define a command that could ++be made the value of @env{EDITOR}, for example. Therefore, this feature ++does not take the place of the Emacs Server feature (@pxref{Emacs ++Server}). ++ ++ The aliases use the Emacs Server feature if you appear to have a ++server Emacs running. However, they cannot determine this with complete ++accuracy. They may think that a server is still running when in ++actuality you have killed that Emacs, because the file ++@file{/tmp/esrv@dots{}} still exists. If this happens, find that ++file and delete it. ++ ++@node Environment ++@appendixsec Environment Variables ++@cindex environment variables ++ ++ The @dfn{environment} is a feature of the operating system; it ++consists of a collection of variables with names and values. Each ++variable is called an @dfn{environment variable}; environment variable ++names are case-sensitive, and it is conventional to use upper case ++letters only. The values are all text strings. ++ ++ What makes the environment useful is that subprocesses inherit the ++environment automatically from their parent process. This means you ++can set up an environment variable in your login shell, and all the ++programs you run (including Emacs) will automatically see it. ++Subprocesses of Emacs (such as shells, compilers, and version-control ++software) inherit the environment from Emacs, too. ++ ++@findex setenv ++@findex getenv ++@vindex initial-environment ++ Inside Emacs, the command @kbd{M-x getenv} gets the value of an ++environment variable. @kbd{M-x setenv} sets a variable in the Emacs ++environment. (Environment variable substitutions with @samp{$} work ++in the value just as in file names; see @ref{File Names with $}.) The ++variable @code{initial-environment} stores the initial environment ++inherited by Emacs. ++ ++ The way to set environment variables outside of Emacs depends on the ++operating system, and especially the shell that you are using. For ++example, here's how to set the environment variable @env{ORGANIZATION} ++to @samp{not very much} using Bash: ++ ++@example ++export ORGANIZATION="not very much" ++@end example ++ ++@noindent ++and here's how to do it in csh or tcsh: ++ ++@example ++setenv ORGANIZATION "not very much" ++@end example ++ ++ When Emacs is using the X Window System, various environment ++variables that control X work for Emacs as well. See the X ++documentation for more information. ++ ++@menu ++* General Variables:: Environment variables that all versions of Emacs use. ++* Misc Variables:: Certain system-specific variables. ++* MS-Windows Registry:: An alternative to the environment on MS-Windows. ++@end menu ++ ++@node General Variables ++@appendixsubsec General Variables ++ ++ Here is an alphabetical list of environment variables that have ++special meanings in Emacs. Most of these variables are also used by ++some other programs. Emacs does not require any of these environment ++variables to be set, but it uses their values if they are set. ++ ++@table @env ++@item CDPATH ++Used by the @code{cd} command to search for the directory you specify, ++when you specify a relative directory name. ++@item EMACS_UNIBYTE ++@cindex unibyte operation, environment variable ++Defining this environment variable with a nonempty value directs Emacs ++to do almost everything with single-byte buffers and strings. It is ++equivalent to using the @samp{--unibyte} command-line option on each ++invocation. @xref{Initial Options}. ++@item EMACSDATA ++Directory for the architecture-independent files that come with Emacs. ++This is used to initialize the Lisp variable @code{data-directory}. ++@item EMACSDOC ++Directory for the documentation string file, ++@file{DOC-@var{emacsversion}}. This is used to initialize the Lisp ++variable @code{doc-directory}. ++@item EMACSLOADPATH ++A colon-separated list of directories@footnote{ ++Here and below, whenever we say ``colon-separated list of directories,'' ++it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, ++the directories are separated by semi-colons instead, since DOS/Windows ++file names might include a colon after a drive letter.} ++to search for Emacs Lisp files---used to initialize @code{load-path}. ++@item EMACSPATH ++A colon-separated list of directories to search for executable ++files---used to initialize @code{exec-path}. ++@item EMAIL ++@vindex user-mail-address@r{, initialization} ++Your email address; used to initialize the Lisp variable ++@code{user-mail-address}, which the Emacs mail interface puts into ++the @samp{From} header of outgoing messages (@pxref{Mail Headers}). ++@item ESHELL ++Used for shell-mode to override the @env{SHELL} environment variable. ++@item HISTFILE ++The name of the file that shell commands are saved in between logins. ++This variable defaults to @file{~/.bash_history} if you use Bash, to ++@file{~/.sh_history} if you use ksh, and to @file{~/.history} ++otherwise. ++@item HOME ++The location of your files in the directory tree; used for ++expansion of file names starting with a tilde (@file{~}). On MS-DOS, ++it defaults to the directory from which Emacs was started, with ++@samp{/bin} removed from the end if it was present. On Windows, the ++default value of @env{HOME} is the @file{Application Data} ++subdirectory of the user profile directory (normally, this is ++@file{C:/Documents and Settings/@var{username}/Application Data}, ++where @var{username} is your user name), though for backwards ++compatibility @file{C:/} will be used instead if a @file{.emacs} file ++is found there. ++@item HOSTNAME ++The name of the machine that Emacs is running on. ++@item INCPATH ++A colon-separated list of directories. Used by the @code{complete} package ++to search for files. ++@item INFOPATH ++A colon-separated list of directories in which to search for Info files. ++@item LC_ALL ++@itemx LC_COLLATE ++@itemx LC_CTYPE ++@itemx LC_MESSAGES ++@itemx LC_MONETARY ++@itemx LC_NUMERIC ++@itemx LC_TIME ++@itemx LANG ++The user's preferred locale. The locale has six categories, specified ++by the environment variables @env{LC_COLLATE} for sorting, ++@env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system ++messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for ++numbers, and @env{LC_TIME} for dates and times. If one of these ++variables is not set, the category defaults to the value of the ++@env{LANG} environment variable, or to the default @samp{C} locale if ++@env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides ++the settings of all the other locale environment variables. ++ ++On MS-Windows, if @env{LANG} is not already set in the environment ++when Emacs starts, Emacs sets it based on the system-wide default ++language, which you can set in the @samp{Regional Settings} Control Panel ++on some versions of MS-Windows. ++ ++The value of the @env{LC_CTYPE} category is ++matched against entries in @code{locale-language-names}, ++@code{locale-charset-language-names}, and ++@code{locale-preferred-coding-systems}, to select a default language ++environment and coding system. @xref{Language Environments}. ++@item LOGNAME ++The user's login name. See also @env{USER}. ++@item MAIL ++The name of your system mail inbox. ++@item MH ++Name of setup file for the mh system. (The default is @file{~/.mh_profile}.) ++@item NAME ++Your real-world name. ++@item NNTPSERVER ++The name of the news server. Used by the mh and Gnus packages. ++@item ORGANIZATION ++The name of the organization to which you belong. Used for setting the ++`Organization:' header in your posts from the Gnus package. ++@item PATH ++A colon-separated list of directories in which executables reside. This ++is used to initialize the Emacs Lisp variable @code{exec-path}. ++@item PWD ++If set, this should be the default directory when Emacs was started. ++@item REPLYTO ++If set, this specifies an initial value for the variable ++@code{mail-default-reply-to}. @xref{Mail Headers}. ++@item SAVEDIR ++The name of a directory in which news articles are saved by default. ++Used by the Gnus package. ++@item SHELL ++The name of an interpreter used to parse and execute programs run from ++inside Emacs. ++@item SMTPSERVER ++The name of the outgoing mail server. Used by the SMTP library ++(@pxref{Top,,,smtpmail,Sending mail via SMTP}). ++@cindex background mode, on @command{xterm} ++@item TERM ++The type of the terminal that Emacs is using. This variable must be ++set unless Emacs is run in batch mode. On MS-DOS, it defaults to ++@samp{internal}, which specifies a built-in terminal emulation that ++handles the machine's own display. If the value of @env{TERM} indicates ++that Emacs runs in non-windowed mode from @command{xterm} or a similar ++terminal emulator, the background mode defaults to @samp{light}, and ++Emacs will choose colors that are appropriate for a light background. ++@item TERMCAP ++The name of the termcap library file describing how to program the ++terminal specified by the @env{TERM} variable. This defaults to ++@file{/etc/termcap}. ++@item TMPDIR ++Used by the Emerge package as a prefix for temporary files. ++@item TZ ++This specifies the current time zone and possibly also daylight ++saving time information. On MS-DOS, if @env{TZ} is not set in the ++environment when Emacs starts, Emacs defines a default value as ++appropriate for the country code returned by DOS. On MS-Windows, Emacs ++does not use @env{TZ} at all. ++@item USER ++The user's login name. See also @env{LOGNAME}. On MS-DOS, this ++defaults to @samp{root}. ++@item VERSION_CONTROL ++Used to initialize the @code{version-control} variable (@pxref{Backup Names}). ++@end table ++ ++@node Misc Variables ++@appendixsubsec Miscellaneous Variables ++ ++These variables are used only on particular configurations: ++ ++@table @env ++@item COMSPEC ++On MS-DOS and MS-Windows, the name of the command interpreter to use ++when invoking batch files and commands internal to the shell. On MS-DOS ++this is also used to make a default value for the @env{SHELL} environment ++variable. ++ ++@item NAME ++On MS-DOS, this variable defaults to the value of the @env{USER} ++variable. ++ ++@item TEMP ++@itemx TMP ++On MS-DOS and MS-Windows, these specify the name of the directory for ++storing temporary files in. ++ ++@item EMACSTEST ++On MS-DOS, this specifies a file to use to log the operation of the ++internal terminal emulator. This feature is useful for submitting bug ++reports. ++ ++@item EMACSCOLORS ++On MS-DOS, this specifies the screen colors. It is useful to set them ++this way, since otherwise Emacs would display the default colors ++momentarily when it starts up. ++ ++The value of this variable should be the two-character encoding of the ++foreground (the first character) and the background (the second ++character) colors of the default face. Each character should be the ++hexadecimal code for the desired color on a standard PC text-mode ++display. For example, to get blue text on a light gray background, ++specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and ++7 is the code of the light gray color. ++ ++The PC display usually supports only eight background colors. However, ++Emacs switches the DOS display to a mode where all 16 colors can be used ++for the background, so all four bits of the background color are ++actually used. ++ ++@item PRELOAD_WINSOCK ++On MS-Windows, if you set this variable, Emacs will load and initialize ++the network library at startup, instead of waiting until the first ++time it is required. ++ ++@item emacs_dir ++On MS-Windows, @env{emacs_dir} is a special environment variable, which ++indicates the full path of the directory in which Emacs is installed. ++If Emacs is installed in the standard directory structure, it ++calculates this value automatically. It is not much use setting this ++variable yourself unless your installation is non-standard, since ++unlike other environment variables, it will be overridden by Emacs at ++startup. When setting other environment variables, such as ++@env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir} ++rather than hard-coding an absolute path. This allows multiple ++versions of Emacs to share the same environment variable settings, and ++it allows you to move the Emacs installation directory, without ++changing any environment or registry settings. ++@end table ++ ++@node MS-Windows Registry ++@appendixsubsec The MS-Windows System Registry ++@pindex addpm, MS-Windows installation program ++@cindex registry, setting environment variables and resources on MS-Windows ++ ++Under MS-Windows, the installation program @command{addpm.exe} adds ++values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA}, ++@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the ++@file{HKEY_LOCAL_MACHINE} section of the system registry, under ++@file{/Software/GNU/Emacs}. It does this because there is no standard ++place to set environment variables across different versions of ++Windows. Running @command{addpm.exe} is no longer strictly necessary ++in recent versions of Emacs, but if you are upgrading from an older ++version, running @command{addpm.exe} ensures that you do not have ++older registry entries from a previous installation, which may not be ++compatible with the latest version of Emacs. ++ ++When Emacs starts, as well as checking the environment, it also checks ++the System Registry for those variables and for @env{HOME}, @env{LANG} ++and @env{PRELOAD_WINSOCK}. ++ ++To determine the value of those variables, Emacs goes through the ++following procedure. First, the environment is checked. If the ++variable is not found there, Emacs looks for registry keys by that ++name under @file{/Software/GNU/Emacs}; first in the ++@file{HKEY_CURRENT_USER} section of the registry, and if not found ++there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs ++still cannot determine the values, compiled-in defaults are used. ++ ++In addition to the environment variables above, you can also add many ++of the settings which on X belong in the @file{.Xdefaults} file ++(@pxref{X Resources}) to the @file{/Software/GNU/Emacs} registry key. ++Settings you add to the @file{HKEY_LOCAL_MACHINE} section will affect ++all users of the machine. Settings you add to the ++@file{HKEY_CURRENT_USER} section will only affect you, and will ++override machine wide settings. ++ ++@node Display X ++@appendixsec Specifying the Display Name ++@cindex display name (X Window System) ++@cindex @env{DISPLAY} environment variable ++ ++ The environment variable @env{DISPLAY} tells all X clients, including ++Emacs, where to display their windows. Its value is set by default ++in ordinary circumstances, when you start an X server and run jobs ++locally. Occasionally you may need to specify the display yourself; for ++example, if you do a remote login and want to run a client program ++remotely, displaying on your local screen. ++ ++ With Emacs, the main reason people change the default display is to ++let them log into another system, run Emacs on that system, but have the ++window displayed at their local terminal. You might need to log in ++to another system because the files you want to edit are there, or ++because the Emacs executable file you want to run is there. ++ ++ The syntax of the @env{DISPLAY} environment variable is ++@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the ++host name of the X Window System server machine, @var{display} is an ++arbitrarily-assigned number that distinguishes your server (X terminal) ++from other servers on the same machine, and @var{screen} is a ++rarely-used field that allows an X server to control multiple terminal ++screens. The period and the @var{screen} field are optional. If ++included, @var{screen} is usually zero. ++ ++ For example, if your host is named @samp{glasperle} and your server is ++the first (or perhaps the only) server listed in the configuration, your ++@env{DISPLAY} is @samp{glasperle:0.0}. ++ ++ You can specify the display name explicitly when you run Emacs, either ++by changing the @env{DISPLAY} variable, or with the option @samp{-d ++@var{display}} or @samp{--display=@var{display}}. Here is an example: ++ ++@smallexample ++emacs --display=glasperle:0 & ++@end smallexample ++ ++ You can inhibit the direct use of the window system and GUI with the ++@samp{-nw} option. It tells Emacs to display using ordinary @acronym{ASCII} on ++its controlling terminal. This is also an initial option. ++ ++ Sometimes, security arrangements prevent a program on a remote system ++from displaying on your local system. In this case, trying to run Emacs ++produces messages like this: ++ ++@smallexample ++Xlib: connection to "glasperle:0.0" refused by server ++@end smallexample ++ ++@noindent ++You might be able to overcome this problem by using the @command{xhost} ++command on the local system to give permission for access from your ++remote machine. ++ ++@node Font X ++@appendixsec Font Specification Options ++@cindex font name (X Window System) ++ ++ By default, Emacs displays text in X using a twelve point monospace ++font. You can specify a different font using the command line option ++@samp{-fn @var{font}} (or @samp{--font}, which is an alias for ++@samp{-fn}). ++ ++@table @samp ++@item -fn @var{font} ++@opindex -fn ++@itemx --font=@var{font} ++@opindex --font ++@cindex specify default font from the command line ++Use @var{font} as the default font. ++@end table ++ ++When passing a font specification to Emacs on the command line, you ++may need to ``quote'' it, by enclosing it in quotation marks, if it ++contains characters that the shell treats specially (e.g. spaces). ++Here is an example: ++ ++@smallexample ++emacs -fn "DejaVu Sans Mono-12" ++@end smallexample ++ ++@cindex X defaults file ++@cindex X resources file ++ You can also specify the font using your X resources file (usually a ++file named @file{.Xdefaults} or @file{.Xresources} in your home ++directory), by adding a line like this: ++ ++@smallexample ++emacs.font: @var{font} ++@end smallexample ++ ++@noindent ++You must restart X, or use the @command{xrdb} command, for the X ++resources file to take effect. @xref{Resources}. When specifying a ++font in your X resources file, you should not quote it. ++ ++@cindex fontconfig ++ Emacs recognizes two types of fonts: @dfn{client-side} fonts, which ++are provided by the Xft and Fontconfig libraries, and ++@dfn{server-side} fonts, which are provided by the X server itself. ++Most client-side fonts support advanced font features such as ++antialiasing and subpixel hinting, while server-side fonts do not. ++ ++ There are four different ways to express a ``font name''. The first ++format consists of @dfn{Fontconfig patterns}. Fontconfig patterns ++match only client-side fonts provided by Xft and Fontconfig, and have ++the following form: ++ ++@smallexample ++@var{fontname}[-@var{fontsize}][:@var{name1}=@var{values1}][:@var{name2}=@var{values2}]... ++@end smallexample ++ ++@noindent ++Within this format, any of the elements in braces may be omitted. ++Here, @var{fontname} is the ``family name'' of the font, such as ++@samp{Monospace} or @samp{DejaVu Serif}; @var{fontsize} is the ``point ++size'' of the font (one ``printer's point'' is about 1/72 of an inch); ++and the @samp{@var{name}=@var{values}} entries specify settings such ++as the slant and weight of the font. Each @var{values} may be a ++single value, or a list of values separated by commas. In addition, ++some property values are valid with only one kind of property name, in ++which case the @samp{@var{name}=} part may be omitted. ++ ++Here is a list of common font properties: ++ ++@table @samp ++@item slant ++One of @samp{italic}, @samp{oblique} or @samp{roman}. ++ ++@item weight ++One of @samp{light}, @samp{medium}, @samp{demibold}, @samp{bold} or ++@samp{black}. ++ ++@item style ++Some fonts define special styles which are a combination of slant and ++weight. For instance, the font @samp{Dejavu Sans} defines the style ++@samp{book}. This property, if specified, overrides the slant and ++weight properties. ++ ++@item width ++One of @samp{condensed}, @samp{normal}, or @samp{expanded}. ++ ++@item spacing ++One of @samp{monospace}, @samp{proportional}, @samp{dual-width}, or ++@samp{charcell}. ++@end table ++ ++@noindent ++Here are some examples of Fontconfig patterns: ++ ++@smallexample ++Monospace ++Monospace-12 ++Monospace-12:bold ++DejaVu Sans Mono:bold:italic ++Monospace-12:weight=bold:slant=italic ++@end smallexample ++ ++See the Fontconfig manual for a more detailed description of ++Fontconfig patterns. This manual is located in the file ++@file{fontconfig-user.html}, which is distributed with Fontconfig. It ++is also available online at ++@url{http://fontconfig.org/fontconfig-user.html}. In particular, the ++manual describes additional font properties that influence how the ++font is hinted, antialiased, or scaled. ++ ++ The second way to specify a font is to use a @dfn{GTK font ++description}. Like Fontconfig patterns, GTK font descriptions match ++only client-side fonts provided by Xft and Fontconfig. They have the ++syntax ++ ++@smallexample ++@var{fontname} [@var{properties}] [@var{fontsize}] ++@end smallexample ++ ++@noindent ++where @var{fontname} is the family name, @var{properties} is a list of ++property values separated by spaces, and @var{fontsize} is the point ++size. The properties that you may specify are as follows: ++ ++@table @samp ++@item style ++One of @samp{roman}, @samp{italic} or @samp{oblique}. If omitted, the ++@samp{roman} style is used. ++@item weight ++One of @samp{medium}, @samp{ultra-light}, @samp{light}, ++@samp{semi-bold}, or @samp{bold}. If omitted, @samp{medium} weight is ++used. ++@end table ++ ++@noindent ++Here are some examples of GTK font descriptions: ++ ++@smallexample ++Monospace 12 ++Monospace Bold Italic 12 ++@end smallexample ++ ++@cindex XLFD ++@cindex X Logical Font Description ++ The third way to specify a font is to use an @dfn{XLFD} (@dfn{X ++Logical Font Description}), which is the traditional method for ++specifying fonts under X. Each XLFD consists of fourteen words or ++numbers, separated by dashes, like this: ++ ++@smallexample ++-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 ++@end smallexample ++ ++@noindent ++A wildcard character (@samp{*}) in an XLFD matches any sequence of ++characters (including none), and @samp{?} matches any single ++character. However, matching is implementation-dependent, and can be ++inaccurate when wildcards match dashes in a long name. For reliable ++results, supply all 14 dashes and use wildcards only within a field. ++Case is insignificant in an XLFD. The syntax for an XLFD is as ++follows: ++ ++@smallexample ++-@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} ++@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{registry}-@var{encoding} ++@end smallexample ++ ++@noindent ++The entries have the following meanings: ++ ++@table @var ++@item maker ++The name of the font manufacturer. ++@item family ++The name of the font family (e.g. @samp{courier}). ++@item weight ++The font weight---normally either @samp{bold}, @samp{medium} or ++@samp{light}. Some font names support other values. ++@item slant ++The font slant---normally @samp{r} (roman), @samp{i} (italic), ++@samp{o} (oblique), @samp{ri} (reverse italic), or @samp{ot} (other). ++Some font names support other values. ++@item widthtype ++The font width---normally @samp{condensed}, @samp{extended}, ++@samp{semicondensed} or @samp{normal} (some font names support other ++values). ++@item style ++An optional additional style name. Usually it is empty---most long ++font names have two hyphens in a row at this point. ++@item pixels ++The font height, in pixels. ++@item height ++The font height on the screen, measured in tenths of a printer's ++point. This is the point size of the font, times ten. For a given ++vertical resolution, @var{height} and @var{pixels} are proportional; ++therefore, it is common to specify just one of them and use @samp{*} ++for the other. ++@item horiz ++The horizontal resolution, in pixels per inch, of the screen for which ++the font is intended. ++@item vert ++The vertical resolution, in pixels per inch, of the screen for which ++the font is intended. Normally the resolution of the fonts on your ++system is the right value for your screen; therefore, you normally ++specify @samp{*} for this and @var{horiz}. ++@item spacing ++This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c} ++(character cell). ++@item width ++The average character width, in pixels, multiplied by ten. ++@item registry ++@itemx encoding ++The X font character set that the font depicts. (X font character ++sets are not the same as Emacs character sets, but they are similar.) ++You can use the @command{xfontsel} program to check which choices you ++have. Normally you should use @samp{iso8859} for @var{registry} and ++@samp{1} for @var{encoding}. ++@end table ++ ++ Some fonts have shorter nicknames, which you can use instead of a ++normal font specification. For instance, ++ ++@smallexample ++-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 ++@end smallexample ++ ++@noindent ++is equivalent to @samp{6x13}. This is the fourth and final method of ++specifying a font. ++ ++@cindex listing system fonts ++ You will probably want to use a fixed-width default font---that is, ++a font in which all characters have the same width. Here's how to use ++the @command{fc-list} command to list all fixed-width Xft and ++Fontconfig fonts available on your system: ++ ++@example ++fc-list :spacing=mono ++fc-list :spacing=charcell ++@end example ++ ++ For server-side X fonts, any font with @samp{m} or @samp{c} in the ++@var{spacing} field of the XLFD is a fixed-width font. Here's how to ++use the @command{xlsfonts} program to list all the fixed-width fonts ++available on your system: ++ ++@example ++xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+" ++xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' ++xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' ++@end example ++ ++@noindent ++To see what a particular font looks like, use the @command{xfd} command. ++For example: ++ ++@example ++xfd -fn 6x13 ++@end example ++ ++@noindent ++displays the entire font @samp{6x13}. ++ ++ While running Emacs, you can set the font of a specific kind of text ++(@pxref{Faces}), or of a particular frame (@pxref{Frame Parameters}). ++ ++@node Colors ++@appendixsec Window Color Options ++@cindex color of window, from command line ++@cindex text colors, from command line ++ ++@findex list-colors-display ++@cindex available colors ++ On a color display, you can specify which color to use for various ++parts of the Emacs display. To find out what colors are available on ++your system, type @kbd{M-x list-colors-display}, or press ++@kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu. ++(A particular window system might support many more colors, but the ++list displayed by @code{list-colors-display} shows their portable ++subset that can be safely used on any display supported by Emacs.) ++If you do not specify colors, on windowed displays the default for the ++background is white and the default for all other colors is black. On a ++monochrome display, the foreground is black, the background is white, ++and the border is gray if the display supports that. On terminals, the ++background is usually black and the foreground is white. ++ ++ Here is a list of the command-line options for specifying colors: ++ ++@table @samp ++@item -fg @var{color} ++@opindex -fg ++@itemx --foreground-color=@var{color} ++@opindex --foreground-color ++@cindex foreground color, command-line argument ++Specify the foreground color. @var{color} should be a standard color ++name, or a numeric specification of the color's red, green, and blue ++components as in @samp{#4682B4} or @samp{RGB:46/82/B4}. ++@item -bg @var{color} ++@opindex -bg ++@itemx --background-color=@var{color} ++@opindex --background-color ++@cindex background color, command-line argument ++Specify the background color. ++@item -bd @var{color} ++@opindex -bd ++@itemx --border-color=@var{color} ++@opindex --border-color ++@cindex border color, command-line argument ++Specify the color of the border of the X window. ++@item -cr @var{color} ++@opindex -cr ++@itemx --cursor-color=@var{color} ++@opindex --cursor-color ++@cindex cursor color, command-line argument ++Specify the color of the Emacs cursor which indicates where point is. ++@item -ms @var{color} ++@opindex -ms ++@itemx --mouse-color=@var{color} ++@opindex --mouse-color ++@cindex mouse pointer color, command-line argument ++Specify the color for the mouse cursor when the mouse is in the Emacs window. ++@item -r ++@opindex -r ++@itemx -rv ++@opindex -rv ++@itemx --reverse-video ++@opindex --reverse-video ++@cindex reverse video, command-line argument ++Reverse video---swap the foreground and background colors. ++@item --color=@var{mode} ++@opindex --color ++@cindex standard colors on a character terminal ++@cindex override character terminal color support ++For a character terminal only, specify the mode of color support. ++This option is intended for overriding the number of supported colors ++that the character terminal advertises in its @code{termcap} or ++@code{terminfo} database. The parameter @var{mode} can be one of the ++following: ++@table @samp ++@item never ++@itemx no ++Don't use colors even if the terminal's capabilities specify color ++support. ++@item default ++@itemx auto ++Same as when @option{--color} is not used at all: Emacs detects at ++startup whether the terminal supports colors, and if it does, turns on ++colored display. ++@item always ++@itemx yes ++@itemx ansi8 ++Turn on the color support unconditionally, and use color commands ++specified by the ANSI escape sequences for the 8 standard colors. ++@item @var{num} ++Use color mode for @var{num} colors. If @var{num} is -1, turn off ++color support (equivalent to @samp{never}); if it is 0, use the ++default color support for this terminal (equivalent to @samp{auto}); ++otherwise use an appropriate standard mode for @var{num} colors. ++Depending on your terminal's capabilities, Emacs might be able to turn ++on a color mode for 8, 16, 88, or 256 as the value of @var{num}. If ++there is no mode that supports @var{num} colors, Emacs acts as if ++@var{num} were 0, i.e.@: it uses the terminal's default color support ++mode. ++@end table ++If @var{mode} is omitted, it defaults to @var{ansi8}. ++@end table ++ ++ For example, to use a coral mouse cursor and a slate blue text cursor, ++enter: ++ ++@example ++emacs -ms coral -cr 'slate blue' & ++@end example ++ ++ You can reverse the foreground and background colors through the ++@samp{-rv} option or with the X resource @samp{reverseVideo}. ++ ++ The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on ++text-only terminals as well as on graphical displays. ++ ++@node Window Size X ++@appendixsec Options for Window Size and Position ++@cindex geometry of Emacs window ++@cindex position and size of Emacs frame ++@cindex width and height of Emacs frame ++@cindex specifying fullscreen for Emacs frame ++ ++ Here is a list of the command-line options for specifying size and ++position of the initial Emacs frame: ++ ++@table @samp ++@item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} ++@opindex -g ++@itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} ++@opindex --geometry ++@cindex geometry, command-line argument ++Specify the size @var{width} and @var{height} (measured in character ++columns and lines), and positions @var{xoffset} and @var{yoffset} ++(measured in pixels). The @var{width} and @var{height} parameters ++apply to all frames, whereas @var{xoffset} and @var{yoffset} only to ++the initial frame. ++ ++@item -fs ++@opindex -fs ++@itemx --fullscreen ++@opindex --fullscreen ++@cindex fullscreen, command-line argument ++Specify that width and height shall be the size of the screen. ++ ++@item -fh ++@opindex -fh ++@itemx --fullheight ++@opindex --fullheight ++@cindex fullheight, command-line argument ++Specify that the height shall be the height of the screen. ++ ++@item -fw ++@opindex -fw ++@itemx --fullwidth ++@opindex --fullwidth ++@cindex fullwidth, command-line argument ++Specify that the width shall be the width of the screen. ++@end table ++ ++@noindent ++In the @samp{--geometry} option, @code{@r{@{}+-@r{@}}} means either a plus ++ sign or a minus sign. A plus ++sign before @var{xoffset} means it is the distance from the left side of ++the screen; a minus sign means it counts from the right side. A plus ++sign before @var{yoffset} means it is the distance from the top of the ++screen, and a minus sign there indicates the distance from the bottom. ++The values @var{xoffset} and @var{yoffset} may themselves be positive or ++negative, but that doesn't change their meaning, only their direction. ++ ++ Emacs uses the same units as @command{xterm} does to interpret the geometry. ++The @var{width} and @var{height} are measured in characters, so a large font ++creates a larger frame than a small font. (If you specify a proportional ++font, Emacs uses its maximum bounds width as the width unit.) The ++@var{xoffset} and @var{yoffset} are measured in pixels. ++ ++ You do not have to specify all of the fields in the geometry ++specification. If you omit both @var{xoffset} and @var{yoffset}, the ++window manager decides where to put the Emacs frame, possibly by ++letting you place it with the mouse. For example, @samp{164x55} ++specifies a window 164 columns wide, enough for two ordinary width ++windows side by side, and 55 lines tall. ++ ++ The default frame width is 80 characters and the default height is ++40 lines. You can omit either the width or the height or both. If ++you start the geometry with an integer, Emacs interprets it as the ++width. If you start with an @samp{x} followed by an integer, Emacs ++interprets it as the height. Thus, @samp{81} specifies just the ++width; @samp{x45} specifies just the height. ++ ++ If you start with @samp{+} or @samp{-}, that introduces an offset, ++which means both sizes are omitted. Thus, @samp{-3} specifies the ++@var{xoffset} only. (If you give just one offset, it is always ++@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the ++@var{yoffset}, placing the frame near the bottom left of the screen. ++ ++ You can specify a default for any or all of the fields in your X ++resource file (@pxref{Resources}), and then override selected fields ++with a @samp{--geometry} option. ++ ++ Since the mode line and the echo area occupy the last 2 lines of the ++frame, the height of the initial text window is 2 less than the height ++specified in your geometry. In non-X-toolkit versions of Emacs, the ++menu bar also takes one line of the specified number. But in the X ++toolkit version, the menu bar is additional and does not count against ++the specified height. The tool bar, if present, is also additional. ++ ++ Enabling or disabling the menu bar or tool bar alters the amount of ++space available for ordinary text. Therefore, if Emacs starts up with ++a tool bar (which is the default), and handles the geometry ++specification assuming there is a tool bar, and then your ++initialization file disables the tool bar, you will end up with a ++frame geometry different from what you asked for. To get the intended ++size with no tool bar, use an X resource to specify ``no tool bar'' ++(@pxref{Table of Resources}); then Emacs will already know there's no ++tool bar when it processes the specified geometry. ++ ++ When using one of @samp{--fullscreen}, @samp{--fullwidth} or ++@samp{--fullheight} there may be some space around the frame ++anyway. That is because Emacs rounds the sizes so they are an ++even number of character heights and widths. ++ ++ Some window managers have options that can make them ignore both ++program-specified and user-specified positions. If these are set, ++Emacs fails to position the window correctly. ++ ++@node Borders X ++@appendixsec Internal and External Borders ++@cindex borders (X Window System) ++ ++ An Emacs frame has an internal border and an external border. The ++internal border is an extra strip of the background color around the ++text portion of the frame. Emacs itself draws the internal border. ++The external border is added by the window manager outside the frame; ++depending on the window manager you use, it may contain various boxes ++you can click on to move or iconify the window. ++ ++@table @samp ++@item -ib @var{width} ++@opindex -ib ++@itemx --internal-border=@var{width} ++@opindex --internal-border ++@cindex internal border width, command-line argument ++Specify @var{width} as the width of the internal border (between the text ++and the main border), in pixels. ++ ++@item -bw @var{width} ++@opindex -bw ++@itemx --border-width=@var{width} ++@opindex --border-width ++@cindex main border width, command-line argument ++Specify @var{width} as the width of the main border, in pixels. ++@end table ++ ++ When you specify the size of the frame, that does not count the ++borders. The frame's position is measured from the outside edge of the ++external border. ++ ++ Use the @samp{-ib @var{n}} option to specify an internal border ++@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to ++specify the width of the external border (though the window manager may ++not pay attention to what you specify). The default width of the ++external border is 2. ++ ++@node Title X ++@appendixsec Frame Titles ++ ++ An Emacs frame may or may not have a specified title. The frame ++title, if specified, appears in window decorations and icons as the ++name of the frame. If an Emacs frame has no specified title, the ++default title has the form @samp{@var{invocation-name}@@@var{machine}} ++(if there is only one frame) or the selected window's buffer name (if ++there is more than one frame). ++ ++ You can specify a title for the initial Emacs frame with a command ++line option: ++ ++@table @samp ++@item -T @var{title} ++@opindex -T ++@itemx --title=@var{title} ++@opindex --title ++@cindex frame title, command-line argument ++Specify @var{title} as the title for the initial Emacs frame. ++@end table ++ ++ The @samp{--name} option (@pxref{Resources}) also specifies the title ++for the initial Emacs frame. ++ ++@node Icons X ++@appendixsec Icons ++@cindex icons (X Window System) ++@cindex minimizing a frame at startup ++ ++@table @samp ++@item -iconic ++@opindex --iconic ++@itemx --iconic ++@cindex start iconified, command-line argument ++Start Emacs in an iconified (``minimized'') state. ++ ++@item -nbi ++@opindex -nbi ++@itemx --no-bitmap-icon ++@opindex --no-bitmap-icon ++@cindex Emacs icon, a gnu ++Do not use a picture of a gnu as the Emacs icon. ++@end table ++ ++ Most window managers allow you to ``iconify'' (or ``minimize'') an ++Emacs frame, hiding it from sight. Some window managers replace ++iconified windows with tiny ``icons'', while others remove them ++entirely from sight. The @samp{-iconic} option tells Emacs to begin ++running in an iconified state, rather than showing a frame right away. ++The text frame doesn't appear until you deiconify (or ``un-minimize'') ++it. ++ ++ By default, Emacs uses an icon containing the Emacs logo. On ++desktop environments such as Gnome, this icon is also displayed on the ++``taskbar''. The @samp{-nbi} or @samp{--no-bitmap-icon} option tells ++Emacs to let the window manager choose what sort of icon to ++use---usually just a small rectangle containing the frame's title. ++ ++@node Misc X ++@appendixsec Other Display Options ++ ++@table @samp ++@c @item -hb ++@c @opindex -hb ++@c @itemx --horizontal-scroll-bars ++@c @opindex --horizontal-scroll-bars ++@c @c @cindex horizontal scroll bars, command-line argument ++@c Enable horizontal scroll bars. Since horizontal scroll bars ++@c are not yet implemented, this actually does nothing. ++ ++@item -vb ++@opindex -vb ++@itemx --vertical-scroll-bars ++@opindex --vertical-scroll-bars ++@cindex vertical scroll bars, command-line argument ++Enable vertical scroll bars. ++ ++@item -lsp @var{pixels} ++@opindex -lsp ++@itemx --line-spacing=@var{pixels} ++@opindex --line-spacing ++@cindex line spacing, command-line argument ++Specify @var{pixels} as additional space to put between lines, in pixels. ++ ++@item -nbc ++@opindex -nbc ++@itemx --no-blinking-cursor ++@opindex --no-blinking-cursor ++@cindex blinking cursor disable, command-line argument ++Disable the blinking cursor on graphical displays. ++ ++@item -D ++@opindex -D ++@itemx --basic-display ++@opindex --basic-display ++Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips, ++and turn off the blinking cursor. This can be useful for making a ++test case that simplifies debugging of display problems. ++@end table ++ ++ The @samp{--xrm} option (@pxref{Resources}) specifies additional ++X resource values. ++ ++@ignore ++ arch-tag: fffecd9e-7329-4a51-a3cc-dd4a9889340e ++@end ignore +diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi +new file mode 100644 +index 0000000..eee844c +--- /dev/null ++++ b/doc/emacs/commands.texi +@@ -0,0 +1,201 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@iftex ++@chapter Characters, Keys and Commands ++ ++ This chapter explains the character sets used by Emacs for input ++commands, and the fundamental concepts of @dfn{keys} and ++@dfn{commands}, whereby Emacs interprets your keyboard and mouse ++input. ++@end iftex ++ ++@ifnottex ++@raisesections ++@end ifnottex ++ ++@node User Input, Keys, Screen, Top ++@section Kinds of User Input ++@cindex input with the keyboard ++@cindex keyboard input ++@cindex character set (keyboard) ++@cindex @acronym{ASCII} ++@cindex C- ++@cindex Control ++@cindex control characters ++ ++ GNU Emacs is primarily designed for use with the keyboard. While it ++is possible to use the mouse to issue editing commands through the ++menu bar and tool bar, that is not as efficient as using the keyboard. ++Therefore, this manual mainly documents how to edit with the keyboard. ++ ++ Keyboard input into Emacs is based on a heavily-extended version of ++@acronym{ASCII}. The simplest characters that you can input into ++Emacs correspond to graphic symbols such as @samp{a}, @samp{B}, ++@samp{3}, @samp{=}, the space character (conventionally denoted as ++@key{SPC}), and so on. Entering these using the keyboard is ++straightforward. Certain characters found on non-English keyboards ++also fall into this category (@pxref{International}). ++ ++ In addition to these simple characters, Emacs recognizes ++@dfn{control characters} such as @key{RET}, @key{TAB}, @key{DEL}, ++@key{ESC}, @key{F1}, @key{Home}, @key{left}, etc. Most keyboards have ++special keys for entering these. ++ ++@cindex modifier keys ++@cindex Control ++@cindex C- ++@cindex Meta ++@cindex M- ++ Emacs also recognizes control characters that are entered using ++@dfn{modifier keys}. Two commonly-used modifier keys are ++@key{Control} (which is usually labelled as @key{Ctrl}), and ++@key{Meta} (which is usually labeled as @key{Alt})@footnote{We refer ++to @key{Alt} as @key{Meta} for historical reasons.}. For example, ++@kbd{Control-a} is entered by holding down the @key{Ctrl} key while ++pressing @kbd{a}; we will refer to this as @kbd{C-a} for short. ++Similarly @kbd{Meta-a}, or @kbd{M-a} for short, is entered by holding ++down the @key{Alt} key and pressing @kbd{a}. ++ ++@cindex @key{ESC} replacing @key{Meta} key ++ You can also type Meta characters using two-character sequences ++starting with @key{ESC}. Thus, you can enter @kbd{M-a} by typing ++@kbd{@key{ESC} a}. You can enter @kbd{C-M-a} by typing @kbd{@key{ESC} ++C-a}. Unlike @key{Meta}, @key{ESC} is entered as a separate ++character. You don't hold down @key{ESC} while typing the next ++character; instead, press @key{ESC} and release it, then enter the ++next character. This feature is useful on certain text-only terminals ++where the @key{Meta} key does not function reliably. ++ ++ Modifier keys can apply not only to alphanumerical characters, but ++also to special input characters, such as the arrow keys and mouse ++buttons. ++ ++@cindex input event ++ @xref{Input Events,,, elisp, The Emacs Lisp Reference Manual}, for ++the full Lisp-level details about keyboard and mouse input, which are ++collectively referred to as @dfn{input events}. If you are not doing ++Lisp programming, but simply want to redefine the meaning of some ++characters or non-character events, see @ref{Customization}. ++ ++@cindex keys stolen by window manager ++@cindex window manager, keys stolen by ++ On graphical displays, the window manager is likely to block the ++character @kbd{M-@key{TAB}} before Emacs can see it. It may also ++block @kbd{M-@key{SPC}}, @kbd{C-M-d} and @kbd{C-M-l}. If you have ++these problems, we recommend that you customize your window manager to ++turn off those commands, or put them on key combinations that Emacs ++does not use. ++ ++@node Keys, Commands, User Input, Top ++@section Keys ++ ++ Some Emacs commands are invoked by just one input event; for ++example, @kbd{C-f} moves forward one character in the buffer. But ++Emacs also has commands that take two or more input events to invoke, ++such as @kbd{C-x C-f} and @kbd{C-x 4 C-f}. ++ ++@cindex key ++@cindex key sequence ++@cindex complete key ++@cindex prefix key ++ A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one ++or more input events that is meaningful as a unit. If a key sequence ++invokes a command, we call it a @dfn{complete key}; for example, ++@kbd{C-f}, @kbd{C-x C-f} and @kbd{C-x 4 C-f} are all complete keys. ++If a key sequence isn't long enough to invoke a command, we call it a ++@dfn{prefix key}; from the preceding example, we see that @kbd{C-x} ++and @kbd{C-x 4} are prefix keys. Every key is either a complete key ++or a prefix key. ++ ++ A prefix key combines with the following input event to make a ++longer key sequence, which may itself be complete or a prefix. For ++example, @kbd{C-x} is a prefix key, so @kbd{C-x} and the next input ++event combine to make a two-event key sequence. This two-event key ++sequence could itself be a prefix key (such as @kbd{C-x 4}), or a ++complete key (such as @kbd{C-x C-f}). There is no limit to the length ++of a key sequence, but in practice people rarely use sequences longer ++than three or four input events. ++ ++ You can't add input events onto a complete key. For example, the ++two-event sequence @kbd{C-f C-k} is not a key, because the @kbd{C-f} ++is a complete key in itself, so @kbd{C-f C-k} cannot have an ++independent meaning as a command. @kbd{C-f C-k} is two key sequences, ++not one.@refill ++ ++ By default, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h}, ++@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x ++n}, @kbd{C-x r}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x 6}, ++@key{ESC}, @kbd{M-g}, and @kbd{M-o}. (@key{F1} and @key{F2} are ++aliases for @kbd{C-h} and @kbd{C-x 6}.) This list is not cast in ++stone; if you customize Emacs, you can make new prefix keys. You ++could even eliminate some of the standard ones, though this is not ++recommended for most users; for example, if you remove the prefix ++definition of @kbd{C-x 4}, then @kbd{C-x 4 @var{anything}} would ++become an invalid key sequence. @xref{Key Bindings}. ++ ++ Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key ++displays a list of the commands starting with that prefix. The sole ++exception to this rule is @key{ESC}: @kbd{@key{ESC}C-h} is equivalent ++to @kbd{C-M-h}, which does something else entirely. You can, however, ++use @key{F1} to displays a list of the commands starting with ++@key{ESC}. ++ ++@node Commands, Entering Emacs, Keys, Top ++@section Keys and Commands ++ ++@cindex binding ++@cindex command ++@cindex function definition ++ This manual is full of passages that tell you what particular keys ++do. But Emacs does not assign meanings to keys directly. Instead, ++Emacs assigns meanings to named @dfn{commands}, and then gives keys ++their meanings by @dfn{binding} them to commands. ++ ++ Every command has a name chosen by a programmer. The name is ++usually made of a few English words separated by dashes; for example, ++@code{next-line} or @code{forward-word}. A command also has a ++@dfn{function definition} which is a Lisp program; this is how the ++command does its work. In Emacs Lisp, a command is a Lisp function ++with special properties that make it suitable for interactive use. ++For more information on commands and functions, see @ref{What Is a ++Function,, What Is a Function, elisp, The Emacs Lisp Reference ++Manual}. ++ ++ The bindings between keys and commands are recorded in tables called ++@dfn{keymaps}. @xref{Keymaps}. ++ ++ When we say that ``@kbd{C-n} moves down vertically one line'' we are ++glossing over a subtle distinction that is irrelevant in ordinary use, ++but vital for Emacs customization. The command @code{next-line} does ++a vertical move downward. @kbd{C-n} has this effect @emph{because} it ++is bound to @code{next-line}. If you rebind @kbd{C-n} to the command ++@code{forward-word}, @kbd{C-n} will move forward one word instead. ++ ++ In this manual, we will often speak of keys like @kbd{C-n} as ++commands, even though strictly speaking the key is bound to a command. ++Usually we state the name of the command which really does the work in ++parentheses after mentioning the key that runs it. For example, we ++will say that ``The command @kbd{C-n} (@code{next-line}) moves point ++vertically down,'' meaning that the command @code{next-line} moves ++vertically down, and the key @kbd{C-n} is normally bound to it. ++ ++ Since we are discussing customization, we should tell you about ++@dfn{variables}. Often the description of a command will say, ``To ++change this, set the variable @code{mumble-foo}.'' A variable is a ++name used to store a value. Most of the variables documented in this ++manual are meant for customization: some command or other part of ++Emacs examines the variable and behaves differently according to the ++value that you set. You can ignore the information about variables ++until you are interested in customizing them. Then read the basic ++information on variables (@pxref{Variables}) and the information about ++specific variables will make sense. ++ ++@ifnottex ++@lowersections ++@end ifnottex ++ ++@ignore ++ arch-tag: 9be43eef-d1f4-4d03-a916-c741ea713a45 ++@end ignore +diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi +new file mode 100644 +index 0000000..f0a6385 +--- /dev/null ++++ b/doc/emacs/custom.texi +@@ -0,0 +1,2579 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Customization, Quitting, Amusements, Top ++@chapter Customization ++@cindex customization ++ ++ This chapter describes some simple methods to customize the behavior ++of Emacs. ++ ++ Apart from the methods described here, see @ref{X Resources} for ++information about using X resources to customize Emacs, and see ++@ref{Keyboard Macros} for information about recording and replaying ++keyboard macros. Making more far-reaching and open-ended changes ++involves writing Emacs Lisp code; see ++@iftex ++@cite{The Emacs Lisp Reference Manual}. ++@end iftex ++@ifnottex ++@ref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp ++Reference Manual}. ++@end ifnottex ++ ++@menu ++* Minor Modes:: Each minor mode is a feature you can turn on ++ independently of any others. ++* Easy Customization:: Convenient way to browse and change settings. ++* Variables:: Many Emacs commands examine Emacs variables ++ to decide what to do; by setting variables, ++ you can control their functioning. ++* Key Bindings:: The keymaps say what command each key runs. ++ By changing them, you can "redefine keys". ++* Syntax:: The syntax table controls how words and ++ expressions are parsed. ++* Init File:: How to write common customizations in the ++ @file{.emacs} file. ++@end menu ++ ++@node Minor Modes ++@section Minor Modes ++@cindex minor modes ++@cindex mode, minor ++ ++ Minor modes are optional features which you can turn on or off. For ++example, Auto Fill mode is a minor mode in which @key{SPC} breaks ++lines between words as you type. Minor modes are independent of one ++another and of the selected major mode. Most minor modes say in the ++mode line when they are enabled; for example, @samp{Fill} in the mode ++line means that Auto Fill mode is enabled. ++ ++ Each minor mode is associated with a command, called the @dfn{mode ++command}, which turns it on or off. The name of this command consists ++of the name of the minor mode, followed by @samp{-mode}; for instance, ++the mode command for Auto Fill mode is @code{auto-fill-mode}. Calling ++the minor mode command with no prefix argument @dfn{toggles} the mode, ++turning it on if it was off, and off if it was on. A positive ++argument always turns the mode on, and a zero or negative argument ++always turns it off. Mode commands are usually invoked with ++@kbd{M-x}, but you can bind keys to them if you wish (@pxref{Key ++Bindings}). ++ ++ Most minor modes also have a @dfn{mode variable}, with the same name ++as the mode command. Its value is non-@code{nil} if the mode is ++enabled, and @code{nil} if it is disabled. In some minor modes---but ++not all---the value of the variable alone determines whether the mode ++is active: the mode command works simply by setting the variable, and ++changing the value of the variable has the same effect as calling the ++mode command. Because not all minor modes work this way, we recommend ++that you avoid changing the mode variables directly; use the mode ++commands instead. ++ ++ Some minor modes are @dfn{buffer-local}: they apply only to the ++current buffer, so you can enable the mode in certain buffers and not ++others. Other minor modes are @dfn{global}: while enabled, they ++affect everything you do in the Emacs session, in all buffers. Some ++global minor modes are enabled by default. ++ ++ The following is a list of some buffer-local minor modes: ++ ++@itemize @bullet ++@item ++Abbrev mode automatically expands text based on pre-defined ++abbreviation definitions. @xref{Abbrevs}. ++ ++@item ++Auto Fill mode inserts newlines as you type to prevent lines from ++becoming too long. @xref{Filling}. ++ ++@item ++Auto Save mode saves the buffer contents periodically to reduce the ++amount of work you can lose in case of a crash. @xref{Auto Save}. ++ ++@item ++Enriched mode enables editing and saving of formatted text. ++@xref{Formatted Text}. ++ ++@item ++Flyspell mode automatically highlights misspelled words. ++@xref{Spelling}. ++ ++@item ++Font-Lock mode automatically highlights certain textual units found in ++programs. It is enabled globally by default, but you can disable it ++in individual buffers. @xref{Faces}. ++ ++@findex linum-mode ++@cindex Linum mode ++@item ++Linum mode displays each line's line number in the window's left ++margin. Its mode command is @code{linum-mode}. ++ ++@item ++Outline minor mode provides similar facilities to the major mode ++called Outline mode. @xref{Outline Mode}. ++ ++@cindex Overwrite mode ++@cindex mode, Overwrite ++@findex overwrite-mode ++@kindex INSERT ++@item ++Overwrite mode causes ordinary printing characters to replace existing ++text instead of shoving it to the right. For example, if point is in ++front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing ++a @kbd{G} changes it to @samp{FOOGAR}, instead of producing ++@samp{FOOGBAR} as usual. In Overwrite mode, the command @kbd{C-q} ++inserts the next character whatever it may be, even if it is a ++digit---this gives you a way to insert a character instead of ++replacing an existing character. The mode command, ++@code{overwrite-mode}, is bound to the @key{Insert} key. ++ ++@findex binary-overwrite-mode ++@item ++Binary Overwrite mode is a variant of Overwrite mode for editing ++binary files; it treats newlines and tabs like other characters, so ++that they overwrite other characters and can be overwritten by them. ++In Binary Overwrite mode, digits after @kbd{C-q} specify an octal ++character code, as usual. ++ ++@item ++Visual Line mode performs ``word wrapping'', causing long lines to be ++wrapped at word boundaries. @xref{Visual Line Mode}. ++@end itemize ++ ++ Here are some useful global minor modes. Since Line Number mode and ++Transient Mark mode can be enabled or disabled just by setting the ++value of the minor mode variable, you @emph{can} set them differently ++for particular buffers, by explicitly making the corresponding ++variable local in those buffers. @xref{Locals}. ++ ++@itemize @bullet ++@item ++Column Number mode enables display of the current column number in the ++mode line. @xref{Mode Line}. ++ ++@item ++Delete Selection mode causes text insertion to first delete the text ++in the region, if the region is active. @xref{Using Region}. ++ ++@item ++Icomplete mode displays an indication of available completions when ++you are in the minibuffer and completion is active. @xref{Completion ++Options}. ++ ++@item ++Line Number mode enables display of the current line number in the ++mode line. It is enabled by default. @xref{Mode Line}. ++ ++@item ++Menu Bar mode gives each frame a menu bar. It is enabled by default. ++@xref{Menu Bars}. ++ ++@item ++Scroll Bar mode gives each window a scroll bar. It is enabled by ++default, but the scroll bar is only displayed on graphical terminals. ++@xref{Scroll Bars}. ++ ++@item ++Tool Bar mode gives each frame a tool bar. It is enabled by default, ++but the tool bar is only displayed on graphical terminals. @xref{Tool ++Bars}. ++ ++@item ++Transient Mark mode highlights the region, and makes many Emacs ++commands operate on the region when the mark is active. It is enabled ++by default. @xref{Mark}. ++@end itemize ++ ++@node Easy Customization ++@section Easy Customization Interface ++ ++@cindex settings ++ Emacs has many @dfn{settings} which have values that you can change. ++Many are documented in this manual. Most settings are @dfn{user ++options}---that is to say, Lisp variables (@pxref{Variables})---and ++their names appear in the Variable Index (@pxref{Variable Index}). ++The other settings are faces and their attributes (@pxref{Faces}). ++ ++@findex customize ++@cindex customization buffer ++ You can browse settings and change them using @kbd{M-x customize}. ++This creates a @dfn{customization buffer}, which lets you navigate ++through a logically organized list of settings, edit and set their ++values, and save them permanently in your initialization file ++(@pxref{Init File}). ++ ++@menu ++* Customization Groups:: How settings are classified in a structure. ++* Browsing Custom:: Browsing and searching for settings. ++* Changing a Variable:: How to edit an option's value and set the option. ++* Saving Customizations:: Specifying the file for saving customizations. ++* Face Customization:: How to edit the attributes of a face. ++* Specific Customization:: Making a customization buffer for specific ++ variables, faces, or groups. ++* Custom Themes:: How to define collections of customized options ++ that can be loaded and unloaded together. ++@end menu ++ ++@node Customization Groups ++@subsection Customization Groups ++@cindex customization groups ++ ++ For customization purposes, settings are organized into @dfn{groups} ++to help you find them. Groups are collected into bigger groups, all ++the way up to a master group called @code{Emacs}. ++ ++ @kbd{M-x customize} creates a customization buffer that shows the ++top-level @code{Emacs} group and the second-level groups immediately ++under it. It looks like this, in part: ++ ++@c we want the buffer example to all be on one page, but unfortunately ++@c that's quite a bit of text, so force all space to the bottom. ++@page ++@smallexample ++@group ++/- Emacs group: Customization of the One True Editor. -------------\ ++ [State]: visible group members are all at standard values. ++ ++ See also [Manual]. ++ ++[Editing] : Basic text editing facilities. ++ ++[External] : Interfacing to external utilities. ++ ++@var{more second-level groups} ++ ++\- Emacs group end ------------------------------------------------/ ++@end group ++@end smallexample ++ ++@noindent ++This says that the buffer displays the contents of the @code{Emacs} ++group. The other groups are listed because they are its contents. But ++they are listed differently, without indentation and dashes, because ++@emph{their} contents are not included. Each group has a single-line ++documentation string; the @code{Emacs} group also has a @samp{[State]} ++line. ++ ++@cindex editable fields (customization buffer) ++@cindex buttons (customization buffer) ++@cindex links (customization buffer) ++ Most of the text in the customization buffer is read-only, but it ++typically includes some @dfn{editable fields} that you can edit. ++There are also @dfn{buttons} and @dfn{links}, which do something when ++you @dfn{invoke} them. To invoke a button or a link, either click on ++it with @kbd{Mouse-1}, or move point to it and type @key{RET}. ++ ++ For example, the phrase @samp{[State]} that appears in a ++second-level group is a button. It operates on the same customization ++buffer. Each group name, such as @samp{[Editing]}, is a hypertext ++link to that group; invoking it creates a new customization buffer, ++showing the group and its contents. ++ ++ The @code{Emacs} group only contains other groups. These groups, in ++turn, can contain settings or still more groups. By browsing the ++hierarchy of groups, you will eventually find the feature you are ++interested in customizing. Then you can use the customization buffer ++to set that feature's settings. You can also go straight to a ++particular group by name, using the command @kbd{M-x customize-group}. ++ ++@node Browsing Custom ++@subsection Browsing and Searching for Options and Faces ++@findex customize-browse ++ ++ @kbd{M-x customize-browse} is another way to browse the available ++settings. This command creates a special customization buffer which ++shows only the names of groups and settings, and puts them in a ++structure. ++ ++ In this buffer, you can show the contents of a group by invoking the ++@samp{[+]} button. When the group contents are visible, this button ++changes to @samp{[-]}; invoking that hides the group contents again. ++ ++ Each group or setting in this buffer has a link which says ++@samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking this link ++creates an ordinary customization buffer showing just that group and ++its contents, just that user option, or just that face. This is the ++way to change settings that you find with @kbd{M-x customize-browse}. ++ ++ If you can guess part of the name of the settings you are interested ++in, @kbd{M-x customize-apropos} is another way to search for settings. ++However, unlike @code{customize} and @code{customize-browse}, ++@code{customize-apropos} can only find groups and settings that are ++loaded in the current Emacs session. @xref{Specific Customization,, ++Customizing Specific Items}. ++ ++@node Changing a Variable ++@subsection Changing a Variable ++ ++ Here is an example of what a variable (a user option) looks like in ++the customization buffer: ++ ++@smallexample ++Kill Ring Max: [Hide Value] 60 ++ [State]: STANDARD. ++Maximum length of kill ring before oldest elements are thrown away. ++@end smallexample ++ ++ The text following @samp{[Hide Value]}, @samp{60} in this case, indicates ++the current value of the variable. If you see @samp{[Show Value]} instead of ++@samp{[Hide Value]}, it means that the value is hidden; the customization ++buffer initially hides values that take up several lines. Invoke ++@samp{[Show Value]} to show the value. ++ ++ The line after the variable name indicates the @dfn{customization ++state} of the variable: in the example above, it says you have not ++changed the option yet. The @samp{[State]} button at the beginning of ++this line gives you a menu of various operations for customizing the ++variable. ++ ++ The line after the @samp{[State]} line displays the beginning of the ++variable's documentation string. If there are more lines of ++documentation, this line ends with a @samp{[More]} button; invoke that ++to show the full documentation string. ++ ++ To enter a new value for @samp{Kill Ring Max}, move point to the ++value and edit it textually. For example, you can type @kbd{M-d}, ++then insert another number. As you begin to alter the text, you will ++see the @samp{[State]} line change to say that you have edited the ++value: ++ ++@smallexample ++[State]: EDITED, shown value does not take effect until you set or @r{@dots{}} ++ save it. ++@end smallexample ++ ++@cindex user options, how to set ++@cindex variables, how to set ++@cindex settings, how to set ++ Editing the value does not actually set the variable. To do that, ++you must @dfn{set} the variable. To do this, invoke the ++@samp{[State]} button and choose @samp{Set for Current Session}. ++ ++ The state of the variable changes visibly when you set it: ++ ++@smallexample ++[State]: SET for current session only. ++@end smallexample ++ ++ You don't have to worry about specifying a value that is not valid; ++the @samp{Set for Current Session} operation checks for validity and ++will not install an unacceptable value. ++ ++@kindex M-TAB @r{(customization buffer)} ++@findex widget-complete ++ While editing a field that is a file name, directory name, ++command name, or anything else for which completion is defined, you ++can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. ++(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.) ++ ++ Some variables have a small fixed set of possible legitimate values. ++These variables don't let you edit the value textually. Instead, a ++@samp{[Value Menu]} button appears before the value; invoke this ++button to change the value. For a boolean ``on or off'' value, the ++button says @samp{[Toggle]}, and it changes to the other value. ++@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the ++changes take real effect when you use the @samp{Set for Current ++Session} operation. ++ ++ Some variables have values with complex structure. For example, the ++value of @code{file-coding-system-alist} is an association list. Here ++is how it appears in the customization buffer: ++ ++@smallexample ++File Coding System Alist: [Hide Value] ++[INS] [DEL] File regexp: \.elc\' ++ Choice: [Value Menu] Encoding/decoding pair: ++ Decoding: emacs-mule ++ Encoding: emacs-mule ++[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\' ++ Choice: [Value Menu] Encoding/decoding pair: ++ Decoding: raw-text ++ Encoding: raw-text-unix ++[INS] [DEL] File regexp: \.tar\' ++ Choice: [Value Menu] Encoding/decoding pair: ++ Decoding: no-conversion ++ Encoding: no-conversion ++[INS] [DEL] File regexp: ++ Choice: [Value Menu] Encoding/decoding pair: ++ Decoding: undecided ++ Encoding: nil ++[INS] ++ [State]: STANDARD. ++Alist to decide a coding system to use for a file I/O @r{@dots{}} ++ operation. [Hide Rest] ++The format is ((PATTERN . VAL) ...), ++where PATTERN is a regular expression matching a file name, ++@r{[@dots{}more lines of documentation@dots{}]} ++@end smallexample ++ ++@noindent ++Each association in the list appears on four lines, with several ++editable fields and/or buttons. You can edit the regexps and coding ++systems using ordinary editing commands. You can also invoke ++@samp{[Value Menu]} to switch to a different kind of value---for ++instance, to specify a function instead of a pair of coding systems. ++ ++To delete an association from the list, invoke the @samp{[DEL]} button ++for that item. To add an association, invoke @samp{[INS]} at the ++position where you want to add it. There is an @samp{[INS]} button ++between each pair of associations, another at the beginning and another ++at the end, so you can add a new association at any position in the ++list. ++ ++@kindex TAB @r{(customization buffer)} ++@kindex S-TAB @r{(customization buffer)} ++@findex widget-forward ++@findex widget-backward ++ Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful ++for moving through the customization buffer. @key{TAB} ++(@code{widget-forward}) moves forward to the next button or editable ++field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to ++the previous button or editable field. ++ ++ Typing @key{RET} on an editable field also moves forward, just like ++@key{TAB}. You can thus type @key{RET} when you are finished editing ++a field, to move on to the next button or field. To insert a newline ++within an editable field, use @kbd{C-o} or @kbd{C-q C-j}. ++ ++@cindex saving a setting ++@cindex settings, how to save ++ Setting the variable changes its value in the current Emacs session; ++@dfn{saving} the value changes it for future sessions as well. To ++save the variable, invoke @samp{[State]} and select the @samp{Save for ++Future Sessions} operation. This works by writing code so as to set ++the variable again, each time you start Emacs (@pxref{Saving ++Customizations}). ++ ++ You can also restore the variable to its standard value by invoking ++@samp{[State]} and selecting the @samp{Erase Customization} operation. ++There are actually four reset operations: ++ ++@table @samp ++@item Undo Edits ++If you have made some modifications and not yet set the variable, ++this restores the text in the customization buffer to match ++the actual value. ++ ++@item Reset to Saved ++This restores the value of the variable to the last saved value, ++and updates the text accordingly. ++ ++@item Erase Customization ++This sets the variable to its standard value, and updates the text ++accordingly. This also eliminates any saved value for the variable, ++so that you will get the standard value in future Emacs sessions. ++ ++@item Set to Backup Value ++This sets the variable to a previous value that was set in the ++customization buffer in this session. If you customize a variable ++and then reset it, which discards the customized value, ++you can get the discarded value back again with this operation. ++@end table ++ ++@cindex comments on customized settings ++ Sometimes it is useful to record a comment about a specific ++customization. Use the @samp{Add Comment} item from the ++@samp{[State]} menu to create a field for entering the comment. The ++comment you enter will be saved, and displayed again if you again view ++the same variable in a customization buffer, even in another session. ++ ++ The state of a group indicates whether anything in that group has been ++edited, set or saved. ++ ++ Near the top of the customization buffer there are two lines of buttons: ++ ++@smallexample ++ [Set for Current Session] [Save for Future Sessions] ++ [Undo Edits] [Reset to Saved] [Erase Customization] [Finish] ++@end smallexample ++ ++@vindex custom-buffer-done-function ++@noindent ++Invoking @samp{[Finish]} either buries or kills this customization ++buffer according to the setting of the option ++@code{custom-buffer-done-kill}; the default is to bury the buffer. ++Each of the other buttons performs an operation---set, save or ++reset---on each of the settings in the buffer that could meaningfully ++be set, saved or reset. They do not operate on settings whose values ++are hidden, nor on subgroups which are hidden or not visible in the buffer. ++ ++@node Saving Customizations ++@subsection Saving Customizations ++ ++@vindex custom-file ++ Saving customizations from the customization buffer works by writing ++code to a file. By reading this code, future sessions can set up the ++customizations again. Normally, the code is saved in your ++initialization file (@pxref{Init File}). ++ ++ You can choose to save your customizations in a file other than your ++initialization file. To make this work, you must add a couple of ++lines of code to your initialization file, to set the variable ++@code{custom-file} to the name of the desired file, and to load that ++file. For example: ++ ++@example ++(setq custom-file "~/.emacs-custom.el") ++(load custom-file) ++@end example ++ ++ You can use @code{custom-file} to specify different customization ++files for different Emacs versions, like this: ++ ++@example ++(cond ((< emacs-major-version 22) ++ ;; @r{Emacs 21 customization.} ++ (setq custom-file "~/.custom-21.el")) ++ ((and (= emacs-major-version 22) (< emacs-minor-version 3)) ++ ;; @r{Emacs 22 customization, before version 22.3.} ++ (setq custom-file "~/.custom-22.el")) ++ (t ++ ;; @r{Emacs version 22.3 or later.} ++ (setq custom-file "~/.emacs-custom.el"))) ++ ++(load custom-file) ++@end example ++ ++ If Emacs was invoked with the @option{-q} or @option{--no-init-file} ++options (@pxref{Initial Options}), it will not let you save your ++customizations in your initialization file. This is because saving ++customizations from such a session would wipe out all the other ++customizations you might have on your initialization file. ++ ++@node Face Customization ++@subsection Customizing Faces ++@cindex customizing faces ++@cindex bold font ++@cindex italic font ++@cindex fonts and faces ++ ++ In addition to variables, some customization groups also include ++faces. When you show the contents of a group, both the variables and ++the faces in the group appear in the customization buffer. Here is an ++example of how a face looks: ++ ++@smallexample ++Custom Changed Face:(sample) [Hide Face] ++ [State]: STANDARD. ++Face used when the customize item has been changed. ++Parent groups: [Custom Magic Faces] ++Attributes: [ ] Font Family: * ++ [ ] Width: * ++ [ ] Height: * ++ [ ] Weight: * ++ [ ] Slant: * ++ [ ] Underline: * ++ [ ] Overline: * ++ [ ] Strike-through: * ++ [ ] Box around text: * ++ [ ] Inverse-video: * ++ [X] Foreground: white (sample) ++ [X] Background: blue (sample) ++ [ ] Stipple: * ++ [ ] Inherit: * ++@end smallexample ++ ++ Each face attribute has its own line. The @samp{[@var{x}]} button ++before the attribute name indicates whether the attribute is ++@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]} ++means that it's disabled. You can enable or disable the attribute by ++clicking that button. When the attribute is enabled, you can change ++the attribute value in the usual ways. ++ ++ For the colors, you can specify a color name (use @kbd{M-x ++list-colors-display} for a list of them) or a hexadecimal color ++specification of the form @samp{#@var{rr}@var{gg}@var{bb}}. ++(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is ++green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a ++black-and-white display, the colors you can use for the background are ++@samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and ++@samp{gray3}. Emacs supports these shades of gray by using background ++stipple patterns instead of a color. ++ ++ Setting, saving and resetting a face work like the same operations for ++variables (@pxref{Changing a Variable}). ++ ++ A face can specify different appearances for different types of ++display. For example, a face can make text red on a color display, but ++use a bold font on a monochrome display. To specify multiple ++appearances for a face, select @samp{For All Kinds of Displays} in the ++menu you get from invoking @samp{[State]}. ++ ++@findex modify-face ++ Another more basic way to set the attributes of a specific face is ++with @kbd{M-x modify-face}. This command reads the name of a face, then ++reads the attributes one by one. For the color and stipple attributes, ++the attribute's current value is the default---type just @key{RET} if ++you don't want to change that attribute. Type @samp{none} if you want ++to clear out the attribute. ++ ++@node Specific Customization ++@subsection Customizing Specific Items ++ ++ Instead of finding the setting you want to change by navigating the ++structure of groups, here are other ways to specify the settings that ++you want to customize. ++ ++@table @kbd ++@item M-x customize-option @key{RET} @var{option} @key{RET} ++Set up a customization buffer with just one user option variable, ++@var{option}. ++@item M-x customize-face @key{RET} @var{face} @key{RET} ++Set up a customization buffer with just one face, @var{face}. ++@item M-x customize-group @key{RET} @var{group} @key{RET} ++Set up a customization buffer with just one group, @var{group}. ++@item M-x customize-apropos @key{RET} @var{regexp} @key{RET} ++Set up a customization buffer with all the settings and groups that ++match @var{regexp}. ++@item M-x customize-changed @key{RET} @var{version} @key{RET} ++Set up a customization buffer with all the settings and groups ++whose meaning has changed since Emacs version @var{version}. ++@item M-x customize-saved ++Set up a customization buffer containing all settings that you ++have saved with customization buffers. ++@item M-x customize-unsaved ++Set up a customization buffer containing all settings that you have ++set but not saved. ++@end table ++ ++@findex customize-option ++ If you want to alter a particular user option with the customization ++buffer, and you know its name, you can use the command @kbd{M-x ++customize-option} and specify the user option (variable) name. This ++sets up the customization buffer with just one user option---the one ++that you asked for. Editing, setting and saving the value work as ++described above, but only for the specified user option. Minibuffer ++completion is handy if you only know part of the name. However, this ++command can only see options that have been loaded in the current ++Emacs session. ++ ++@findex customize-face ++ Likewise, you can modify a specific face, chosen by name, using ++@kbd{M-x customize-face}. By default it operates on the face used ++on the character after point. ++ ++@findex customize-group ++ You can also set up the customization buffer with a specific group, ++using @kbd{M-x customize-group}. The immediate contents of the chosen ++group, including settings (user options and faces), and other groups, ++all appear as well (even if not already loaded). However, the ++subgroups' own contents are not included. ++ ++@findex customize-apropos ++ For a more general way of controlling what to customize, you can use ++@kbd{M-x customize-apropos}. You specify a regular expression as ++argument; then all @emph{loaded} settings and groups whose names match ++this regular expression are set up in the customization buffer. If ++you specify an empty regular expression, this includes @emph{all} ++loaded groups and settings---which takes a long time to set up. ++ ++@findex customize-changed ++ When you upgrade to a new Emacs version, you might want to consider ++customizing new settings, and settings whose meanings or default ++values have changed. To do this, use @kbd{M-x customize-changed} and ++specify a previous Emacs version number using the minibuffer. It ++creates a customization buffer which shows all the settings and groups ++whose definitions have been changed since the specified version, ++loading them if necessary. ++ ++@findex customize-saved ++@findex customize-unsaved ++ If you change settings and then decide the change was a mistake, you ++can use two special commands to revisit your previous changes. Use ++@kbd{M-x customize-saved} to look at the settings that you have saved. ++Use @kbd{M-x customize-unsaved} to look at the settings that you ++have set but not saved. ++ ++@node Custom Themes ++@subsection Customization Themes ++@cindex custom themes ++ ++ @dfn{Custom themes} are collections of settings that can be enabled ++or disabled as a unit. You can use Custom themes to switch quickly ++and easily between various collections of settings, and to transfer ++such collections from one computer to another. ++ ++@findex customize-create-theme ++ To define a Custom theme, use @kbd{M-x customize-create-theme}, ++which brings up a buffer named @samp{*New Custom Theme*}. At the top ++of the buffer is an editable field where you can specify the name of ++the theme. Click on the button labelled @samp{Insert Variable} to add ++a variable to the theme, and click on @samp{Insert Face} to add a ++face. You can edit these values in the @samp{*New Custom Theme*} ++buffer like in an ordinary Customize buffer. To remove an option from ++the theme, click on its @samp{State} button and select @samp{Delete}. ++ ++@vindex custom-theme-directory ++ After adding the desired options, click on @samp{Save Theme} to save ++the Custom theme. This writes the theme definition to a file ++@file{@var{foo}-theme.el} (where @var{foo} is the theme name you ++supplied), in the directory @file{~/.emacs.d/}. You can specify the ++directory by setting @code{custom-theme-directory}. ++ ++ You can view and edit the settings of a previously-defined theme by ++clicking on @samp{Visit Theme} and specifying the theme name. You can ++also import the variables and faces that you have set using Customize ++by visiting the ``special'' theme named @samp{user}. This theme, which ++records all the options that you set in the ordinary customization ++buffer, is always enabled, and always takes precedence over all other ++enabled Custom themes. Additionally, the @samp{user} theme is ++recorded with code in your @file{.emacs} file, rather than a ++@file{user-theme.el} file. ++ ++@vindex custom-enabled-themes ++ Once you have defined a Custom theme, you can use it by customizing ++the variable @code{custom-enabled-themes}. This is a list of Custom ++themes that are @dfn{enabled}, or put into effect. If you set ++@code{custom-enabled-themes} using the Customize interface, the theme ++definitions are automatically loaded from the theme files, if they ++aren't already. If you save the value of @code{custom-enabled-themes} ++for future Emacs sessions, those Custom themes will be enabled ++whenever Emacs is started up. ++ ++ If two enabled themes specify different values for an option, the ++theme occurring earlier in @code{custom-enabled-themes} takes effect. ++ ++@findex load-theme ++@findex enable-theme ++@findex disable-theme ++ You can temporarily enable a Custom theme with @kbd{M-x ++enable-theme}. This prompts for a theme name in the minibuffer, loads ++the theme from the theme file if necessary, and enables the theme. ++You can @dfn{disable} any enabled theme with the command @kbd{M-x ++disable-theme}; this returns the options specified in the theme to ++their original values. To re-enable the theme, type @kbd{M-x ++enable-theme} again. If a theme file is changed during your Emacs ++session, you can reload it by typing @kbd{M-x load-theme}. (This also ++enables the theme.) ++ ++@node Variables ++@section Variables ++@cindex variable ++@cindex option, user ++@cindex user option ++ ++ A @dfn{variable} is a Lisp symbol which has a value. The symbol's ++name is also called the @dfn{variable name}. A variable name can ++contain any characters that can appear in a file, but most variable ++names consist of ordinary words separated by hyphens. ++ ++ The name of the variable serves as a compact description of its ++role. Most variables also have a @dfn{documentation string}, which ++describes what the variable's purpose is, what kind of value it should ++have, and how the value will be used. You can view this documentation ++using the help command @kbd{C-h v} (@code{describe-variable}). ++@xref{Examining}. ++ ++ Emacs uses many Lisp variables for internal record keeping, but the ++most interesting variables for a non-programmer user are those meant ++for users to change---these are called @dfn{user options}. @xref{Easy ++Customization}, for information about using the Customize facility to ++set user options. In the following sections, we describe will other ++aspects of Emacs variables, such as how to set them outside Customize. ++ ++ Emacs Lisp allows any variable (with a few exceptions) to have any ++kind of value. However, many variables are meaningful only if ++assigned values of a certain type. For example, only numbers are ++meaningful values for @code{kill-ring-max}, which specifies the ++maximum length of the kill ring (@pxref{Earlier Kills}); if you give ++@code{kill-ring-max} a string value, commands such as @kbd{C-y} ++(@code{yank}) will signal an error. On the other hand, some variables ++don't care about type; for instance, if a variable has one effect for ++@code{nil} values and another effect for ``non-@code{nil}'' values, ++then any value that is not the symbol @code{nil} induces the second ++effect, regardless of its type (by convention, we usually use the ++value @code{t}---a symbol which stands for ``true''---to specify a ++non-@code{nil} value). If you set a variable using the customization ++buffer, you need not worry about giving it an invalid type: the ++customization buffer usually only allows you to enter meaningful ++values. When in doubt, use @kbd{C-h v} (@code{describe-variable}) to ++check the variable's documentation string to see kind of value it ++expects (@pxref{Examining}). ++ ++@menu ++* Examining:: Examining or setting one variable's value. ++* Hooks:: Hook variables let you specify programs for parts ++ of Emacs to run on particular occasions. ++* Locals:: Per-buffer values of variables. ++* File Variables:: How files can specify variable values. ++* Directory Variables:: How variable values can be specified by directory. ++@end menu ++ ++@node Examining ++@subsection Examining and Setting Variables ++@cindex setting variables ++ ++@table @kbd ++@item C-h v @var{var} @key{RET} ++Display the value and documentation of variable @var{var} ++(@code{describe-variable}). ++@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} ++Change the value of variable @var{var} to @var{value}. ++@end table ++ ++ To examine the value of a single variable, use @kbd{C-h v} ++(@code{describe-variable}), which reads a variable name using the ++minibuffer, with completion. It displays both the value and the ++documentation of the variable. For example, ++ ++@example ++C-h v fill-column @key{RET} ++@end example ++ ++@noindent ++displays something like this: ++ ++@smallexample ++fill-column is a variable defined in `C source code'. ++fill-column's value is 70 ++Local in buffer custom.texi; global value is 70 ++Automatically becomes buffer-local when set in any fashion. ++ ++ Automatically becomes buffer-local when set in any fashion. ++ This variable is safe as a file local variable if its value ++ satisfies the predicate `integerp'. ++ ++Documentation: ++*Column beyond which automatic line-wrapping should happen. ++Interactively, you can set the buffer local value using C-x f. ++ ++You can customize this variable. ++@end smallexample ++ ++@noindent ++The line that says ``You can customize the variable'' indicates that ++this variable is a user option. @kbd{C-h v} is not restricted to user ++options; it allows any variable name. ++ ++@findex set-variable ++ The most convenient way to set a specific user option variable is ++with @kbd{M-x set-variable}. This reads the variable name with the ++minibuffer (with completion), and then reads a Lisp expression for the ++new value using the minibuffer a second time (you can insert the old ++value into the minibuffer for editing via @kbd{M-n}). For example, ++ ++@example ++M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} ++@end example ++ ++@noindent ++sets @code{fill-column} to 75. ++ ++ @kbd{M-x set-variable} is limited to user option variables, but you can ++set any variable with a Lisp expression, using the function @code{setq}. ++Here is a @code{setq} expression to set @code{fill-column}: ++ ++@example ++(setq fill-column 75) ++@end example ++ ++ To execute an expression like this one, go to the @samp{*scratch*} ++buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp ++Interaction}. ++ ++ Setting variables, like all means of customizing Emacs except where ++otherwise stated, affects only the current Emacs session. The only ++way to alter the variable in future sessions is to put something in ++your initialization file to set it those sessions (@pxref{Init File}). ++ ++@node Hooks ++@subsection Hooks ++@cindex hook ++@cindex running a hook ++ ++ @dfn{Hooks} are an important mechanism for customizing Emacs. A ++hook is a Lisp variable which holds a list of functions, to be called ++on some well-defined occasion. (This is called @dfn{running the ++hook}.) The individual functions in the list are called the @dfn{hook ++functions} of the hook. With rare exceptions, hooks in Emacs are ++empty when Emacs starts up, so the only hook functions in any given ++hook are the ones you explicitly put there as customization. ++ ++ Most major modes run one or more @dfn{mode hooks} as the last step ++of initialization. This makes it easy for you to customize the ++behavior of the mode, by setting up a hook function to override the ++local variable assignments already made by the mode. But hooks are ++also used in other contexts. For example, the hook ++@code{kill-emacs-hook} runs just before quitting the Emacs job ++(@pxref{Exiting}). ++ ++@cindex normal hook ++ Most Emacs hooks are @dfn{normal hooks}. This means that running the ++hook operates by calling all the hook functions, unconditionally, with ++no arguments. We have made an effort to keep most hooks normal so that ++you can use them in a uniform way. Every variable in Emacs whose name ++ends in @samp{-hook} is a normal hook. ++ ++@cindex abnormal hook ++ There are also a few @dfn{abnormal hooks}. These variables' names end ++in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What ++makes these hooks abnormal is that there is something peculiar about the ++way its functions are called---perhaps they are given arguments, or ++perhaps the values they return are used in some way. For example, ++@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because ++as soon as one hook function returns a non-@code{nil} value, the rest ++are not called at all. The documentation of each abnormal hook variable ++explains in detail what is peculiar about it. ++ ++@findex add-hook ++ You can set a hook variable with @code{setq} like any other Lisp ++variable, but the recommended way to add a hook function to a hook ++(either normal or abnormal) is by calling @code{add-hook}. ++@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}. ++ ++ For example, here's how to set up a hook to turn on Auto Fill mode ++when entering Text mode and other modes based on Text mode: ++ ++@example ++(add-hook 'text-mode-hook 'turn-on-auto-fill) ++@end example ++ ++ The next example shows how to use a hook to customize the indentation ++of C code. (People often have strong personal preferences for one ++format compared to another.) Here the hook function is an anonymous ++lambda expression. ++ ++@example ++@group ++(setq my-c-style ++ '((c-comment-only-line-offset . 4) ++@end group ++@group ++ (c-cleanup-list . (scope-operator ++ empty-defun-braces ++ defun-close-semi)) ++@end group ++@group ++ (c-offsets-alist . ((arglist-close . c-lineup-arglist) ++ (substatement-open . 0))))) ++@end group ++ ++@group ++(add-hook 'c-mode-common-hook ++ '(lambda () ++ (c-add-style "my-style" my-c-style t))) ++@end group ++@end example ++ ++ It is best to design your hook functions so that the order in which ++they are executed does not matter. Any dependence on the order is ++``asking for trouble.'' However, the order is predictable: the most ++recently added hook functions are executed first. ++ ++@findex remove-hook ++ If you play with adding various different versions of a hook ++function by calling @code{add-hook} over and over, remember that all ++the versions you added will remain in the hook variable together. You ++can clear out individual functions by calling @code{remove-hook}, or ++do @code{(setq @var{hook-variable} nil)} to remove everything. ++ ++@node Locals ++@subsection Local Variables ++ ++@table @kbd ++@item M-x make-local-variable @key{RET} @var{var} @key{RET} ++Make variable @var{var} have a local value in the current buffer. ++@item M-x kill-local-variable @key{RET} @var{var} @key{RET} ++Make variable @var{var} use its global value in the current buffer. ++@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET} ++Mark variable @var{var} so that setting it will make it local to the ++buffer that is current at that time. ++@end table ++ ++@cindex local variables ++ Almost any variable can be made @dfn{local} to a specific Emacs ++buffer. This means that its value in that buffer is independent of its ++value in other buffers. A few variables are always local in every ++buffer. Every other Emacs variable has a @dfn{global} value which is in ++effect in all buffers that have not made the variable local. ++ ++@findex make-local-variable ++ @kbd{M-x make-local-variable} reads the name of a variable and makes ++it local to the current buffer. Changing its value subsequently in ++this buffer will not affect others, and changes in its global value ++will not affect this buffer. ++ ++@findex make-variable-buffer-local ++@cindex per-buffer variables ++ @kbd{M-x make-variable-buffer-local} marks a variable so it will ++become local automatically whenever it is set. More precisely, once a ++variable has been marked in this way, the usual ways of setting the ++variable automatically do @code{make-local-variable} first. We call ++such variables @dfn{per-buffer} variables. Many variables in Emacs ++are normally per-buffer; the variable's document string tells you when ++this is so. A per-buffer variable's global value is normally never ++effective in any buffer, but it still has a meaning: it is the initial ++value of the variable for each new buffer. ++ ++ Major modes (@pxref{Major Modes}) always make variables local to the ++buffer before setting the variables. This is why changing major modes ++in one buffer has no effect on other buffers. Minor modes also work ++by setting variables---normally, each minor mode has one controlling ++variable which is non-@code{nil} when the mode is enabled ++(@pxref{Minor Modes}). For many minor modes, the controlling variable ++is per buffer, and thus always buffer-local. Otherwise, you can make ++it local in a specific buffer like any other variable. ++ ++ A few variables cannot be local to a buffer because they are always ++local to each display instead (@pxref{Multiple Displays}). If you try to ++make one of these variables buffer-local, you'll get an error message. ++ ++@findex kill-local-variable ++ @kbd{M-x kill-local-variable} makes a specified variable cease to be ++local to the current buffer. The global value of the variable ++henceforth is in effect in this buffer. Setting the major mode kills ++all the local variables of the buffer except for a few variables ++specially marked as @dfn{permanent locals}. ++ ++@findex setq-default ++ To set the global value of a variable, regardless of whether the ++variable has a local value in the current buffer, you can use the Lisp ++construct @code{setq-default}. This construct is used just like ++@code{setq}, but it sets variables' global values instead of their local ++values (if any). When the current buffer does have a local value, the ++new global value may not be visible until you switch to another buffer. ++Here is an example: ++ ++@example ++(setq-default fill-column 75) ++@end example ++ ++@noindent ++@code{setq-default} is the only way to set the global value of a variable ++that has been marked with @code{make-variable-buffer-local}. ++ ++@findex default-value ++ Lisp programs can use @code{default-value} to look at a variable's ++default value. This function takes a symbol as argument and returns its ++default value. The argument is evaluated; usually you must quote it ++explicitly. For example, here's how to obtain the default value of ++@code{fill-column}: ++ ++@example ++(default-value 'fill-column) ++@end example ++ ++@node File Variables ++@subsection Local Variables in Files ++@cindex local variables in files ++@cindex file local variables ++ ++ A file can specify local variable values for use when you edit the ++file with Emacs. Visiting the file checks for local variable ++specifications; it automatically makes these variables local to the ++buffer, and sets them to the values specified in the file. ++ ++@menu ++* Specifying File Variables:: Specifying file local variables. ++* Safe File Variables:: Making sure file local variables are safe. ++@end menu ++ ++@node Specifying File Variables ++@subsubsection Specifying File Variables ++ ++ There are two ways to specify file local variable values: in the first ++line, or with a local variables list. Here's how to specify them in the ++first line: ++ ++@example ++-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- ++@end example ++ ++@noindent ++You can specify any number of variables/value pairs in this way, each ++pair with a colon and semicolon as shown above. @code{mode: ++@var{modename};} specifies the major mode; this should come first in the ++line. The @var{value}s are not evaluated; they are used literally. ++Here is an example that specifies Lisp mode and sets two variables with ++numeric values: ++ ++@smallexample ++;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*- ++@end smallexample ++ ++ You can also specify the coding system for a file in this way: just ++specify a value for the ``variable'' named @code{coding}. The ``value'' ++must be a coding system name that Emacs recognizes. @xref{Coding ++Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a ++particular Lisp file. @xref{Enabling Multibyte}. ++ ++ The @code{eval} pseudo-variable, described below, can be specified in ++the first line as well. ++ ++@cindex shell scripts, and local file variables ++@cindex man pages, and local file variables ++ In shell scripts, the first line is used to identify the script ++interpreter, so you cannot put any local variables there. To ++accommodate this, Emacs looks for local variable specifications in the ++@emph{second} line when the first line specifies an interpreter. ++The same is true for man pages which start with the magic string ++@samp{'\"} to specify a list of troff preprocessors (not all do, ++however). ++ ++ A @dfn{local variables list} goes near the end of the file. It ++starts with a line containing the string @samp{Local Variables:}, and ++ends with a line containing the string @samp{End:}. In between come ++the variable names and values, one set per line, as ++@samp{@var{variable}:@: @var{value}}. The @var{value}s are not ++evaluated; they are used literally. If a file has both a local ++variables list and a @samp{-*-} line, Emacs processes ++@emph{everything} in the @samp{-*-} line first, and @emph{everything} ++in the local variables list afterward. ++ ++ Here is an example of a local variables list: ++ ++@example ++/* Local Variables: */ ++/* mode:c */ ++/* comment-column:0 */ ++/* End: */ ++@end example ++ ++ In this example, each line starts with the prefix @samp{/*} and each ++line ends with the suffix @samp{*/}. Emacs recognizes these as the ++prefix and suffix by finding them surrounding the magic string ++@samp{Local Variables:}, on the first line of the list; it then ++automatically discards them from the other lines of the list. ++ ++ The usual reason for using a prefix and/or suffix is to embed the ++local variables list in a comment, so it won't confuse other programs ++that the file is intended as input for. The example above is for the ++C programming language, where comment lines start with @samp{/*} and ++end with @samp{*/}. Don't use a prefix (or a suffix) if you don't ++need one. ++ ++ If you write a multi-line string value, you should put the prefix ++and suffix on each line, even lines that start or end within the ++string. They will be stripped off for processing the list. If you ++want to split a long string across multiple lines of the file, you can ++use backslash-newline, which is ignored in Lisp string constants. ++Here's an example of doing this: ++ ++@example ++# Local Variables: ++# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ ++# -Dmumble=blaah" ++# End: ++@end example ++ ++ Some ``variable names'' have special meanings in a local variables ++list. Specifying the ``variable'' @code{mode} really sets the major ++mode, while any value specified for the ``variable'' @code{eval} is ++simply evaluated as an expression (its value is ignored). A value for ++@code{coding} specifies the coding system for character code ++conversion of this file, and a value of @code{t} for @code{unibyte} ++says to visit the file in a unibyte buffer. These four ``variables'' ++are not really variables; setting them in any other context has no ++special meaning. ++ ++ @emph{If @code{mode} is used to set a major mode, it should be the ++first ``variable'' in the list.} Otherwise, the entries that precede ++it will usually be ignored, since most modes kill all local variables ++as part of their initialization. ++ ++ You can use the @code{mode} ``variable'' to set minor modes as well ++as the major modes; in fact, you can use it more than once, first to ++set the major mode and then to set minor modes which are specific to ++particular buffers. But most minor modes should not be specified in ++the file at all, because they represent user preferences. ++ ++ For example, you may be tempted to try to turn on Auto Fill mode with ++a local variable list. That is a mistake. The choice of Auto Fill mode ++or not is a matter of individual taste, not a matter of the contents of ++particular files. If you want to use Auto Fill, set up major mode hooks ++with your @file{.emacs} file to turn it on (when appropriate) for you ++alone (@pxref{Init File}). Don't use a local variable list to impose ++your taste on everyone. ++ ++ The start of the local variables list must be no more than 3000 ++characters from the end of the file, and must be in the last page if ++the file is divided into pages. Otherwise, Emacs will not notice it ++is there. The purpose of this rule is so that Emacs need not take the ++time to search the whole file. ++ ++ Use the command @code{normal-mode} to reset the local variables and ++major mode of a buffer according to the file name and contents, ++including the local variables list if any. @xref{Choosing Modes}. ++ ++@node Safe File Variables ++@subsubsection Safety of File Variables ++ ++ File-local variables can be dangerous; when you visit someone else's ++file, there's no telling what its local variables list could do to ++your Emacs. Improper values of the @code{eval} ``variable,'' and ++other variables such as @code{load-path}, could execute Lisp code you ++didn't intend to run. ++ ++ Therefore, whenever Emacs encounters file local variable values that ++are not known to be safe, it displays the file's entire local ++variables list, and asks you for confirmation before setting them. ++You can type @kbd{y} or @key{SPC} to put the local variables list into ++effect, or @kbd{n} to ignore it. When Emacs is run in batch mode ++(@pxref{Initial Options}), it can't really ask you, so it assumes the ++answer @kbd{n}. ++ ++ Emacs normally recognizes certain variables/value pairs as safe. ++For instance, it is safe to give @code{comment-column} or ++@code{fill-column} any integer value. If a file specifies only ++known-safe variable/value pairs, Emacs does not ask for confirmation ++before setting them. Otherwise, you can tell Emacs to record all the ++variable/value pairs in this file as safe, by typing @kbd{!} at the ++confirmation prompt. When Emacs encounters these variable/value pairs ++subsequently, in the same file or others, it will assume they are ++safe. ++ ++@vindex safe-local-variable-values ++@cindex risky variable ++ Some variables, such as @code{load-path}, are considered ++particularly @dfn{risky}: there is seldom any reason to specify them ++as local variables, and changing them can be dangerous. If a file ++contains only risky local variables, Emacs neither offers nor accepts ++@kbd{!} as input at the confirmation prompt. If some of the local ++variables in a file are risky, and some are only potentially unsafe, you ++can enter @kbd{!} at the prompt. It applies all the variables, but only ++marks the non-risky ones as safe for the future. If you really want to ++record safe values for risky variables, do it directly by customizing ++@samp{safe-local-variable-values} (@pxref{Easy Customization}). ++ ++@vindex enable-local-variables ++ The variable @code{enable-local-variables} allows you to change the ++way Emacs processes local variables. Its default value is @code{t}, ++which specifies the behavior described above. If it is @code{nil}, ++Emacs simply ignores all file local variables. @code{:safe} means use ++only the safe values and ignore the rest. Any other value says to ++query you about each file that has local variables, without trying to ++determine whether the values are known to be safe. ++ ++@vindex enable-local-eval ++ The variable @code{enable-local-eval} controls whether Emacs ++processes @code{eval} variables. The three possibilities for the ++variable's value are @code{t}, @code{nil}, and anything else, just as ++for @code{enable-local-variables}. The default is @code{maybe}, which ++is neither @code{t} nor @code{nil}, so normally Emacs does ask for ++confirmation about processing @code{eval} variables. ++ ++@vindex safe-local-eval-forms ++ But there is an exception. The @code{safe-local-eval-forms} is a ++customizable list of eval forms which are safe. Emacs does not ask ++for confirmation when it finds these forms for the @code{eval} ++variable. ++ ++@node Directory Variables ++@subsection Per-Directory Local Variables ++@cindex local variables, for all files in a directory ++@cindex directory local variables ++@cindex per-directory local variables ++ ++ A @dfn{project} is a collection of files on which you work together. ++Usually, the project's files are kept in one or more directories. ++Occasionally, you may wish to define Emacs settings that are common to ++all the files that belong to the project. ++ ++ Emacs provides two ways to specify settings that are applicable to ++files in a specific directory: you can put a special file in that ++directory, or you can define a @dfn{project class} for that directory. ++ ++@cindex @file{.dir-locals.el} file ++ If you put a file with a special name @file{.dir-locals.el}@footnote{ ++On MS-DOS, the name of this file should be @file{_dir-locals.el}, due ++to limitations of the DOS filesystems. If the filesystem is limited ++to 8+3 file names, the name of the file will be truncated by the OS to ++@file{_dir-loc.el}. ++} in a directory, Emacs will read it when it visits any file in that ++directory or any of its subdirectories, and apply the settings it ++specifies to the file's buffer. Emacs searches for ++@file{.dir-locals.el} starting in the directory of the visited file, ++and moving up the directory tree. (To avoid slowdown, this search is ++skipped for remote files.) ++ ++ The @file{.dir-locals.el} file should hold a specially-constructed ++list. This list maps Emacs mode names (symbols) to alists; each alist ++specifies values for variables to use when the respective mode is ++turned on. The special mode name @samp{nil} means that its alist ++applies to any mode. Instead of a mode name, you can specify a string ++that is a name of a subdirectory of the project's directory; then the ++corresponding alist applies to all the files in that subdirectory. ++ ++ Here's an example of a @file{.dir-locals.el} file: ++ ++@example ++((nil . ((indent-tabs-mode . t) ++ (tab-width . 4) ++ (fill-column . 80))) ++ (c-mode . ((c-file-style . "BSD"))) ++ (java-mode . ((c-file-style . "BSD"))) ++ ("src/imported" ++ . ((nil . ((change-log-default-name . "ChangeLog.local")))))) ++@end example ++ ++@noindent ++This example shows some settings for a hypothetical project. It sets ++@samp{indent-tabs-mode}, @code{tab-width}, and @code{fill-column} for ++any file in the project's directory tree, and it sets the indentation ++style for any C or Java source file. Finally, it specifies a different ++@file{ChangeLog} file name for any file in the @file{src/imported} ++subdirectory of the directory where you put the @file{.dir-locals.el} ++file. ++ ++@findex dir-locals-set-class-variables ++@findex dir-locals-set-directory-class ++ Another method of specifying directory-local variables is to explicitly ++define a project class using @code{dir-locals-set-class-variables}, and ++then tell Emacs which directories correspond to that class, using ++@code{dir-locals-set-directory-class}. You can put calls to these functions ++in your @file{~/.emacs} init file; this can be useful when you can't put ++@file{.dir-locals.el} in the directory for some reason, or if you want ++to keep in a single place settings for several directories that don't ++have a common parent. For example, you could apply settings to an ++unwritable directory this way: ++ ++@example ++(dir-locals-set-class-variables 'unwritable-directory ++ '((nil . ((some-useful-setting . value))))) ++ ++(dir-locals-set-directory-class ++ "/usr/include/" 'unwritable-directory) ++@end example ++ ++ Unsafe directory-local variables are handled in the same way as ++unsafe file-local variables (@pxref{Safe File Variables}). ++ ++@node Key Bindings ++@section Customizing Key Bindings ++@cindex key bindings ++ ++ This section describes @dfn{key bindings}, which map keys to commands, ++and @dfn{keymaps}, which record key bindings. It also explains how ++to customize key bindings. ++ ++ Recall that a command is a Lisp function whose definition provides for ++interactive use. Like every Lisp function, a command has a function ++name, which usually consists of lower-case letters and hyphens. ++ ++@menu ++* Keymaps:: Generalities. The global keymap. ++* Prefix Keymaps:: Keymaps for prefix keys. ++* Local Keymaps:: Major and minor modes have their own keymaps. ++* Minibuffer Maps:: The minibuffer uses its own local keymaps. ++* Rebinding:: How to redefine one key's meaning conveniently. ++* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. ++* Modifier Keys:: Using modifier keys in key bindings. ++* Function Keys:: Rebinding terminal function keys. ++* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. ++* Mouse Buttons:: Rebinding mouse buttons in Emacs. ++* Disabling:: Disabling a command means confirmation is required ++ before it can be executed. This is done to protect ++ beginners from surprises. ++@end menu ++ ++@node Keymaps ++@subsection Keymaps ++@cindex keymap ++ ++ The bindings between key sequences and command functions are recorded ++in data structures called @dfn{keymaps}. Emacs has many of these, each ++used on particular occasions. ++ ++ A @dfn{key sequence} (@dfn{key}, for short) is a sequence of ++@dfn{input events} that have a meaning as a unit. Input events ++include characters, function keys and mouse buttons---all the inputs ++that you can send to the computer with your terminal. A key sequence ++gets its meaning from its @dfn{binding}, which says what command it ++runs. The role of keymaps is to record these bindings. ++ ++@cindex global keymap ++ The @dfn{global} keymap is the most important keymap because it is ++always in effect. The global keymap defines keys for Fundamental mode; ++most of these definitions are common to most or all major modes. Each ++major or minor mode can have its own keymap which overrides the global ++definitions of some keys. ++ ++ For example, a self-inserting character such as @kbd{g} is ++self-inserting because the global keymap binds it to the command ++@code{self-insert-command}. The standard Emacs editing characters such ++as @kbd{C-a} also get their standard meanings from the global keymap. ++Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work ++by storing the new binding in the proper place in the global map. ++@xref{Rebinding}. ++ ++@cindex function key ++ Most modern keyboards have function keys as well as character keys. ++Function keys send input events just as character keys do, and keymaps ++can have bindings for them. On text terminals, typing a function key ++actually sends the computer a sequence of characters; the precise ++details of the sequence depends on which function key and on the model ++of terminal you are using. (Often the sequence starts with ++@kbd{@key{ESC} [}.) If Emacs understands your terminal type properly, ++it recognizes the character sequences forming function keys wherever ++they occur in a key sequence. Thus, for most purposes, you can ++pretend the function keys reach Emacs directly and ignore their ++encoding as character sequences. ++ ++ Key sequences can mix function keys and characters. For example, if ++your keyboard has a @key{Home} function key, Emacs also recognizes key ++sequences like @kbd{C-x @key{Home}}. You can even mix mouse events ++with keyboard events, but we recommend against it, because such key ++sequences are inconvenient to use. ++ ++ As a user, you can redefine any key, but it is usually best to stick ++to key sequences that consist of @kbd{C-c} followed by a letter (upper ++or lower case). These keys are ``reserved for users,'' so they won't ++conflict with any properly designed Emacs extension. The function ++keys @key{F5} through @key{F9} are also reserved for users. If you ++redefine some other key, your definition may be overridden by certain ++extensions or major modes which redefine the same key. ++ ++@node Prefix Keymaps ++@subsection Prefix Keymaps ++ ++ Internally, Emacs records only single events in each keymap. ++Interpreting a key sequence of multiple events involves a chain of ++keymaps: the first keymap gives a definition for the first event, ++which is another keymap, which is used to look up the second event in ++the sequence, and so on. Thus, a prefix key such as @kbd{C-x} or ++@key{ESC} has its own keymap, which holds the definition for the event ++that immediately follows that prefix. ++ ++ The definition of a prefix key is usually the keymap to use for ++looking up the following event. The definition can also be a Lisp ++symbol whose function definition is the following keymap; the effect is ++the same, but it provides a command name for the prefix key that can be ++used as a description of what the prefix key is for. Thus, the binding ++of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function ++definition is the keymap for @kbd{C-x} commands. The definitions of ++@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in ++the global map, so these prefix keys are always available. ++ ++ Aside from ordinary prefix keys, there is a fictitious ``prefix key'' ++which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp ++Reference Manual}, for special information about menu bar key bindings. ++Mouse button events that invoke pop-up menus are also prefix keys; see ++@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more ++details. ++ ++ Some prefix keymaps are stored in variables with names: ++ ++@itemize @bullet ++@item ++@vindex ctl-x-map ++@code{ctl-x-map} is the variable name for the map used for characters that ++follow @kbd{C-x}. ++@item ++@vindex help-map ++@code{help-map} is for characters that follow @kbd{C-h}. ++@item ++@vindex esc-map ++@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta ++characters are actually defined by this map. ++@item ++@vindex ctl-x-4-map ++@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. ++@item ++@vindex mode-specific-map ++@code{mode-specific-map} is for characters that follow @kbd{C-c}. ++@end itemize ++ ++@node Local Keymaps ++@subsection Local Keymaps ++ ++@cindex local keymap ++ So far we have explained the ins and outs of the global map. Major ++modes customize Emacs by providing their own key bindings in @dfn{local ++keymaps}. For example, C mode overrides @key{TAB} to make it indent the ++current line for C code. Portions of text in the buffer can specify ++their own keymaps to substitute for the keymap of the buffer's major ++mode. ++ ++@cindex minor mode keymap ++ Minor modes can also have local keymaps. Whenever a minor mode is ++in effect, the definitions in its keymap override both the major ++mode's local keymap and the global keymap. ++ ++ A local keymap can locally redefine a key as a prefix key by defining ++it as a prefix keymap. If the key is also defined globally as a prefix, ++then its local and global definitions (both keymaps) effectively ++combine: both of them are used to look up the event that follows the ++prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as ++another keymap, and that keymap defines @kbd{C-z} as a command, this ++provides a local meaning for @kbd{C-c C-z}. This does not affect other ++sequences that start with @kbd{C-c}; if those sequences don't have their ++own local bindings, their global bindings remain in effect. ++ ++ Another way to think of this is that Emacs handles a multi-event key ++sequence by looking in several keymaps, one by one, for a binding of the ++whole key sequence. First it checks the minor mode keymaps for minor ++modes that are enabled, then it checks the major mode's keymap, and then ++it checks the global keymap. This is not precisely how key lookup ++works, but it's good enough for understanding the results in ordinary ++circumstances. ++ ++@cindex rebinding major mode keys ++ Most major modes construct their keymaps when the mode is used for ++the first time in a session. If you wish to change one of these ++keymaps, you must use the major mode's @dfn{mode hook} ++(@pxref{Hooks}). ++ ++@findex define-key ++ For example, the command @code{texinfo-mode} to select Texinfo mode ++runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook ++to add local bindings (not very useful, we admit) for @kbd{C-c n} and ++@kbd{C-c p} in Texinfo mode: ++ ++@example ++(add-hook 'texinfo-mode-hook ++ '(lambda () ++ (define-key texinfo-mode-map "\C-cp" ++ 'backward-paragraph) ++ (define-key texinfo-mode-map "\C-cn" ++ 'forward-paragraph))) ++@end example ++ ++@node Minibuffer Maps ++@subsection Minibuffer Keymaps ++ ++@cindex minibuffer keymaps ++@vindex minibuffer-local-map ++@vindex minibuffer-local-ns-map ++@vindex minibuffer-local-completion-map ++@vindex minibuffer-local-must-match-map ++@vindex minibuffer-local-filename-completion-map ++@vindex minibuffer-local-must-match-filename-map ++ The minibuffer has its own set of local keymaps; they contain various ++completion and exit commands. ++ ++@itemize @bullet ++@item ++@code{minibuffer-local-map} is used for ordinary input (no completion). ++@item ++@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits ++just like @key{RET}. This is used mainly for Mocklisp compatibility. ++@item ++@code{minibuffer-local-completion-map} is for permissive completion. ++@item ++@code{minibuffer-local-must-match-map} is for strict completion and ++for cautious completion. ++@item ++Finally, @code{minibuffer-local-filename-completion-map} and ++@code{minibuffer-local-must-match-filename-map} are like the two ++previous ones, but they are specifically for file name completion. ++They do not bind @key{SPC}. ++@end itemize ++ ++@node Rebinding ++@subsection Changing Key Bindings Interactively ++@cindex key rebinding, this session ++@cindex redefining keys, this session ++ ++ The way to redefine an Emacs key is to change its entry in a keymap. ++You can change the global keymap, in which case the change is effective in ++all major modes (except those that have their own overriding local ++definitions for the same key). Or you can change the current buffer's ++local map, which affects all buffers using the same major mode. ++ ++@findex global-set-key ++@findex local-set-key ++@findex global-unset-key ++@findex local-unset-key ++@table @kbd ++@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} ++Define @var{key} globally to run @var{cmd}. ++@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} ++Define @var{key} locally (in the major mode now in effect) to run ++@var{cmd}. ++@item M-x global-unset-key @key{RET} @var{key} ++Make @var{key} undefined in the global map. ++@item M-x local-unset-key @key{RET} @var{key} ++Make @var{key} undefined locally (in the major mode now in effect). ++@end table ++ ++ For example, suppose you like to execute commands in a subshell within ++an Emacs buffer, instead of suspending Emacs and executing commands in ++your login shell. Normally, @kbd{C-z} is bound to the function ++@code{suspend-emacs} (when not using the X Window System), but you can ++change @kbd{C-z} to invoke an interactive subshell within Emacs, by ++binding it to @code{shell} as follows: ++ ++@example ++M-x global-set-key @key{RET} C-z shell @key{RET} ++@end example ++ ++@noindent ++@code{global-set-key} reads the command name after the key. After you ++press the key, a message like this appears so that you can confirm that ++you are binding the key you want: ++ ++@example ++Set key C-z to command: ++@end example ++ ++ You can redefine function keys and mouse events in the same way; just ++type the function key or click the mouse when it's time to specify the ++key to rebind. ++ ++ You can rebind a key that contains more than one event in the same ++way. Emacs keeps reading the key to rebind until it is a complete key ++(that is, not a prefix key). Thus, if you type @kbd{C-f} for ++@var{key}, that's the end; it enters the minibuffer immediately to ++read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it ++reads another character; if that is @kbd{4}, another prefix character, ++it reads one more character, and so on. For example, ++ ++@example ++M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} ++@end example ++ ++@noindent ++redefines @kbd{C-x 4 $} to run the (fictitious) command ++@code{spell-other-window}. ++ ++ You can remove the global definition of a key with ++@code{global-unset-key}. This makes the key @dfn{undefined}; if you ++type it, Emacs will just beep. Similarly, @code{local-unset-key} makes ++a key undefined in the current major mode keymap, which makes the global ++definition (or lack of one) come back into effect in that major mode. ++ ++ If you have redefined (or undefined) a key and you subsequently wish ++to retract the change, undefining the key will not do the job---you need ++to redefine the key with its standard definition. To find the name of ++the standard definition of a key, go to a Fundamental mode buffer in a ++fresh Emacs and use @kbd{C-h c}. The documentation of keys in this ++manual also lists their command names. ++ ++ If you want to prevent yourself from invoking a command by mistake, it ++is better to disable the command than to undefine the key. A disabled ++command is less work to invoke when you really want to. ++@xref{Disabling}. ++ ++@node Init Rebinding ++@subsection Rebinding Keys in Your Init File ++@c This node is referenced in the tutorial. When renaming or deleting ++@c it, the tutorial needs to be adjusted. (TUTORIAL.de) ++ ++ If you have a set of key bindings that you like to use all the time, ++you can specify them in your initialization file by writing Lisp code ++(@pxref{Init File}). ++ ++@findex kbd ++ There are several ways to write a key binding using Lisp. The ++simplest is to use the @code{kbd} macro, which converts a textual ++representation of a key sequence---similar to how we have written key ++sequences in this manual---into a form that can be passed as an ++argument to @code{global-set-key}. For example, here's how to bind ++@kbd{C-z} to @code{shell} (@pxref{Interactive Shell}): ++ ++@example ++(global-set-key (kbd "C-z") 'shell) ++@end example ++ ++@noindent ++The single-quote before the command name, @code{shell}, marks it as a ++constant symbol rather than a variable. If you omit the quote, Emacs ++would try to evaluate @code{shell} as a variable. This probably ++causes an error; it certainly isn't what you want. ++ ++ Here are some additional examples, including binding function keys ++and mouse events: ++ ++@example ++(global-set-key (kbd "C-c y") 'clipboard-yank) ++(global-set-key (kbd "C-M-q") 'query-replace) ++(global-set-key (kbd "") 'flyspell-mode) ++(global-set-key (kbd "C-") 'linum-mode) ++(global-set-key (kbd "C-") 'forward-sentence) ++(global-set-key (kbd "") 'mouse-save-then-kill) ++(global-set-key (kbd "C-") 'mouse-yank-at-click) ++@end example ++ ++ Instead of using the @code{kbd} macro, you can use a Lisp string or ++vector to specify the key sequence. Using a string is simpler, but ++only works for @acronym{ASCII} characters and Meta-modified ++@acronym{ASCII} characters. For example, here's how to bind @kbd{C-x ++M-l} to @code{make-symbolic-link} (@pxref{Misc File Ops}): ++ ++@example ++(global-set-key "\C-x\M-l" 'make-symbolic-link) ++@end example ++ ++ To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the string, ++use the Emacs Lisp escape sequences @samp{\t}, @samp{\r}, @samp{\e}, ++and @samp{\d} respectively. Here is an example which binds @kbd{C-x ++@key{TAB}} to @code{indent-rigidly} (@pxref{Indentation}): ++ ++@example ++(global-set-key "\C-x\t" 'indent-rigidly) ++@end example ++ ++ When the key sequence includes function keys or mouse button events, ++or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, ++you must use a vector to specify the key sequence. Each element in ++the vector stands for an input event; the elements are separated by ++spaces and surrounded by a pair of square brackets. If an element is ++a symbol, simply write the symbol's name---no other delimiters or ++punctuation are needed. If a vector element is a character, write it ++as a Lisp character constant: @samp{?} followed by the character as it ++would appear in a string. Here are some examples: ++ ++@example ++(global-set-key [?\C-=] 'make-symbolic-link) ++(global-set-key [?\M-\C-=] 'make-symbolic-link) ++(global-set-key [?\H-a] 'make-symbolic-link) ++(global-set-key [f7] 'make-symbolic-link) ++(global-set-key [C-mouse-1] 'make-symbolic-link) ++@end example ++ ++@noindent ++You can use a vector for the simple cases too: ++ ++@example ++(global-set-key [?\C-z ?\M-l] 'make-symbolic-link) ++@end example ++ ++ Language and coding systems may cause problems with key bindings for ++non-@acronym{ASCII} characters. @xref{Init Non-ASCII}. ++ ++@node Modifier Keys ++@subsection Modifier Keys ++@cindex modifier keys ++ ++ The default key bindings in Emacs are set up so that modified ++alphabetical characters are case-insensitive. In other words, ++@kbd{C-A} does the same thing as @kbd{C-a}, and @kbd{M-A} does the ++same thing as @kbd{M-a}. This concerns only alphabetical characters, ++and does not apply to ``shifted'' versions of other keys; for ++instance, @kbd{C-@@} is not the same as @kbd{C-2}. ++ ++ When you customize Emacs, you can make modified alphabetical ++characters case-sensitive. For instance, you could make @kbd{M-a} and ++@kbd{M-A} run different commands. ++ ++ As a special exception, a @key{Control}-modified alphabetical ++character is always case-insensitive, for historical reasons: Emacs ++always treats @kbd{C-A} as @kbd{C-a}, @kbd{C-B} as @kbd{C-b}, and so ++forth. ++ ++ Although only the @key{Control} and @key{Meta} modifier keys are ++commonly used, Emacs supports three other modifier keys. These are ++called @key{Super}, @key{Hyper} and @key{Alt}. Few terminals provide ++ways to use these modifiers; the key labeled @key{Alt} on most ++keyboards usually issues the @key{Meta} modifier, not @key{Alt}. The ++standard key bindings in Emacs do not include any characters with ++these modifiers. However, you can customize Emacs to assign meanings ++to them. The modifier bits are labelled as @samp{s-}, @samp{H-} and ++@samp{A-} respectively. ++ ++ Even if your keyboard lacks these additional modifier keys, you can ++enter it using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to ++the next character, @kbd{C-x @@ s} adds the ``super'' flag, and ++@kbd{C-x @@ a} adds the ``alt'' flag. For instance, @kbd{C-x @@ h ++C-a} is a way to enter @kbd{Hyper-Control-a}. (Unfortunately, there ++is no way to add two modifiers by using @kbd{C-x @@} twice for the ++same character, because the first one goes to work on the @kbd{C-x}.) ++ ++@node Function Keys ++@subsection Rebinding Function Keys ++ ++ Key sequences can contain function keys as well as ordinary ++characters. Just as Lisp characters (actually integers) represent ++keyboard characters, Lisp symbols represent function keys. If the ++function key has a word as its label, then that word is also the name of ++the corresponding Lisp symbol. Here are the conventional Lisp names for ++common function keys: ++ ++@table @asis ++@item @code{left}, @code{up}, @code{right}, @code{down} ++Cursor arrow keys. ++ ++@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior} ++Other cursor repositioning keys. ++ ++@item @code{select}, @code{print}, @code{execute}, @code{backtab} ++@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline} ++@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar} ++Miscellaneous function keys. ++ ++@item @code{f1}, @code{f2}, @dots{} @code{f35} ++Numbered function keys (across the top of the keyboard). ++ ++@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide} ++@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter} ++@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal} ++Keypad keys (to the right of the regular keyboard), with names or punctuation. ++ ++@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9} ++Keypad keys with digits. ++ ++@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} ++Keypad PF keys. ++@end table ++ ++ These names are conventional, but some systems (especially when using ++X) may use different names. To make certain what symbol is used for a ++given function key on your terminal, type @kbd{C-h c} followed by that ++key. ++ ++ @xref{Init Rebinding}, for examples of binding function keys. ++ ++@cindex keypad ++ Many keyboards have a ``numeric keypad'' on the right hand side. ++The numeric keys in the keypad double up as cursor motion keys, ++toggled by a key labeled @samp{Num Lock}. By default, Emacs ++translates these keys to the corresponding keys in the main keyboard. ++For example, when @samp{Num Lock} is on, the key labeled @samp{8} on ++the numeric keypad produces @code{kp-8}, which is translated to ++@kbd{8}; when @samp{Num Lock} is off, the same key produces ++@code{kp-up}, which is translated to @key{UP}. If you rebind a key ++such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too. ++However, if you rebind a @samp{kp-} key directly, that won't affect ++its non-keypad equivalent. Note that the modified keys are not ++translated: for instance, if you hold down the @key{META} key while ++pressing the @samp{8} key on the numeric keypad, that generates ++@kbd{M-@key{kp-8}}. ++ ++ Emacs provides a convenient method for binding the numeric keypad ++keys, using the variables @code{keypad-setup}, ++@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and ++@code{keypad-numlock-shifted-setup}. These can be found in the ++@samp{keyboard} customization group (@pxref{Easy Customization}). You ++can rebind the keys to perform other tasks, such as issuing numeric ++prefix arguments. ++ ++@node Named ASCII Chars ++@subsection Named @acronym{ASCII} Control Characters ++ ++ @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} ++started out as names for certain @acronym{ASCII} control characters, ++used so often that they have special keys of their own. For instance, ++@key{TAB} was another name for @kbd{C-i}. Later, users found it ++convenient to distinguish in Emacs between these keys and the ``same'' ++control characters typed with the @key{CTRL} key. Therefore, on most ++modern terminals, they are no longer the same: @key{TAB} is different ++from @kbd{C-i}. ++ ++ Emacs can distinguish these two kinds of input if the keyboard does. ++It treats the ``special'' keys as function keys named @code{tab}, ++@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and ++@code{delete}. These function keys translate automatically into the ++corresponding @acronym{ASCII} characters @emph{if} they have no ++bindings of their own. As a result, neither users nor Lisp programs ++need to pay attention to the distinction unless they care to. ++ ++ If you do not want to distinguish between (for example) @key{TAB} and ++@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB} ++(octal code 011). If you do want to distinguish, make one binding for ++this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. ++ ++ With an ordinary @acronym{ASCII} terminal, there is no way to distinguish ++between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), ++because the terminal sends the same character in both cases. ++ ++@node Mouse Buttons ++@subsection Rebinding Mouse Buttons ++@cindex mouse button events ++@cindex rebinding mouse buttons ++@cindex click events ++@cindex drag events ++@cindex down events ++@cindex button down events ++ ++ Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary ++mouse events in Emacs are @dfn{click} events; these happen when you ++press a button and release it without moving the mouse. You can also ++get @dfn{drag} events, when you move the mouse while holding the button ++down. Drag events happen when you finally let go of the button. ++ ++ The symbols for basic click events are @code{mouse-1} for the leftmost ++button, @code{mouse-2} for the next, and so on. Here is how you can ++redefine the second mouse button to split the current window: ++ ++@example ++(global-set-key [mouse-2] 'split-window-vertically) ++@end example ++ ++ The symbols for drag events are similar, but have the prefix ++@samp{drag-} before the word @samp{mouse}. For example, dragging the ++first button generates a @code{drag-mouse-1} event. ++ ++ You can also define bindings for events that occur when a mouse button ++is pressed down. These events start with @samp{down-} instead of ++@samp{drag-}. Such events are generated only if they have key bindings. ++When you get a button-down event, a corresponding click or drag event ++will always follow. ++ ++@cindex double clicks ++@cindex triple clicks ++ If you wish, you can distinguish single, double, and triple clicks. A ++double click means clicking a mouse button twice in approximately the ++same place. The first click generates an ordinary click event. The ++second click, if it comes soon enough, generates a double-click event ++instead. The event type for a double-click event starts with ++@samp{double-}: for example, @code{double-mouse-3}. ++ ++ This means that you can give a special meaning to the second click at ++the same place, but it must act on the assumption that the ordinary ++single click definition has run when the first click was received. ++ ++ This constrains what you can do with double clicks, but user interface ++designers say that this constraint ought to be followed in any case. A ++double click should do something similar to the single click, only ++``more so.'' The command for the double-click event should perform the ++extra work for the double click. ++ ++ If a double-click event has no binding, it changes to the ++corresponding single-click event. Thus, if you don't define a ++particular double click specially, it executes the single-click command ++twice. ++ ++ Emacs also supports triple-click events whose names start with ++@samp{triple-}. Emacs does not distinguish quadruple clicks as event ++types; clicks beyond the third generate additional triple-click events. ++However, the full number of clicks is recorded in the event list, so ++if you know Emacs Lisp you can distinguish if you really want to ++(@pxref{Click Events,,, elisp, The Emacs Lisp Reference Manual}). ++We don't recommend distinct meanings for more than three clicks, but ++sometimes it is useful for subsequent clicks to cycle through the same ++set of three meanings, so that four clicks are equivalent to one ++click, five are equivalent to two, and six are equivalent to three. ++ ++ Emacs also records multiple presses in drag and button-down events. ++For example, when you press a button twice, then move the mouse while ++holding the button, Emacs gets a @samp{double-drag-} event. And at the ++moment when you press it down for the second time, Emacs gets a ++@samp{double-down-} event (which is ignored, like all button-down ++events, if it has no binding). ++ ++@vindex double-click-time ++ The variable @code{double-click-time} specifies how much time can ++elapse between clicks and still allow them to be grouped as a multiple ++click. Its value is in units of milliseconds. If the value is ++@code{nil}, double clicks are not detected at all. If the value is ++@code{t}, then there is no time limit. The default is 500. ++ ++@vindex double-click-fuzz ++ The variable @code{double-click-fuzz} specifies how much the mouse ++can move between clicks and still allow them to be grouped as a multiple ++click. Its value is in units of pixels on windowed displays and in ++units of 1/8 of a character cell on text-mode terminals; the default is ++3. ++ ++ The symbols for mouse events also indicate the status of the modifier ++keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-}, ++@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-} ++or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}. ++ ++ A frame includes areas that don't show text from the buffer, such as ++the mode line and the scroll bar. You can tell whether a mouse button ++comes from a special area of the screen by means of dummy ``prefix ++keys.'' For example, if you click the mouse in the mode line, you get ++the prefix key @code{mode-line} before the ordinary mouse-button symbol. ++Thus, here is how to define the command for clicking the first button in ++a mode line to run @code{scroll-up}: ++ ++@example ++(global-set-key [mode-line mouse-1] 'scroll-up) ++@end example ++ ++ Here is the complete list of these dummy prefix keys and their ++meanings: ++ ++@table @code ++@item mode-line ++The mouse was in the mode line of a window. ++@item vertical-line ++The mouse was in the vertical line separating side-by-side windows. (If ++you use scroll bars, they appear in place of these vertical lines.) ++@item vertical-scroll-bar ++The mouse was in a vertical scroll bar. (This is the only kind of ++scroll bar Emacs currently supports.) ++@item menu-bar ++The mouse was in the menu bar. ++@item header-line ++The mouse was in a header line. ++@ignore ++@item horizontal-scroll-bar ++The mouse was in a horizontal scroll bar. Horizontal scroll bars do ++horizontal scrolling, and people don't use them often. ++@end ignore ++@end table ++ ++ You can put more than one mouse button in a key sequence, but it isn't ++usual to do so. ++ ++@node Disabling ++@subsection Disabling Commands ++@cindex disabled command ++ ++ Disabling a command means that invoking it interactively asks for ++confirmation from the user. The purpose of disabling a command is to ++prevent users from executing it by accident; we do this for commands ++that might be confusing to the uninitiated. ++ ++ Attempting to invoke a disabled command interactively in Emacs ++displays a window containing the command's name, its documentation, ++and some instructions on what to do immediately; then Emacs asks for ++input saying whether to execute the command as requested, enable it ++and execute it, or cancel. If you decide to enable the command, you ++must then answer another question---whether to do this permanently, or ++just for the current session. (Enabling permanently works by ++automatically editing your @file{.emacs} file.) You can also type ++@kbd{!} to enable @emph{all} commands, for the current session only. ++ ++ The direct mechanism for disabling a command is to put a ++non-@code{nil} @code{disabled} property on the Lisp symbol for the ++command. Here is the Lisp program to do this: ++ ++@example ++(put 'delete-region 'disabled t) ++@end example ++ ++ If the value of the @code{disabled} property is a string, that string ++is included in the message displayed when the command is used: ++ ++@example ++(put 'delete-region 'disabled ++ "It's better to use `kill-region' instead.\n") ++@end example ++ ++@findex disable-command ++@findex enable-command ++ You can make a command disabled either by editing the @file{.emacs} ++file directly, or with the command @kbd{M-x disable-command}, which edits ++the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command} ++edits @file{.emacs} to enable a command permanently. @xref{Init File}. ++ ++ If Emacs was invoked with the @option{-q} or @option{--no-init-file} ++options (@pxref{Initial Options}), it will not edit your ++@file{~/.emacs} init file. Doing so could lose information ++because Emacs has not read your init file. ++ ++ Whether a command is disabled is independent of what key is used to ++invoke it; disabling also applies if the command is invoked using ++@kbd{M-x}. However, disabling a command has no effect on calling it ++as a function from Lisp programs. ++ ++@node Syntax ++@section The Syntax Table ++@cindex syntax table ++ ++ All the Emacs commands which parse words or balance parentheses are ++controlled by the @dfn{syntax table}. The syntax table says which ++characters are opening delimiters, which are parts of words, which are ++string quotes, and so on. It does this by assigning each character to ++one of fifteen-odd @dfn{syntax classes}. In some cases it specifies ++some additional information also. ++ ++ Each major mode has its own syntax table (though related major modes ++sometimes share one syntax table), which it installs in each buffer ++that uses the mode. The syntax table installed in the current buffer ++is the one that all commands use, so we call it ``the'' syntax table. ++ ++@kindex C-h s ++@findex describe-syntax ++ To display a description of the contents of the current syntax ++table, type @kbd{C-h s} (@code{describe-syntax}). The description of ++each character includes the string you would have to give to ++@code{modify-syntax-entry} to set up that character's current syntax, ++starting with the character which designates its syntax class, plus ++some English text to explain its meaning. ++ ++ A syntax table is actually a Lisp object, a char-table, whose ++elements are cons cells. For full information on the syntax table, ++see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp ++Reference Manual}. ++ ++@node Init File ++@section The Init File, @file{~/.emacs} ++@cindex init file ++@cindex Emacs initialization file ++@cindex key rebinding, permanent ++@cindex rebinding keys, permanently ++@cindex startup (init file) ++ ++ When Emacs is started, it normally tries to load a Lisp program from ++an @dfn{initialization file}, or @dfn{init file} for short. This ++file, if it exists, specifies how to initialize Emacs for you. Emacs ++looks for your init file using the filenames @file{~/.emacs}, ++@file{~/.emacs.el}, or @file{~/.emacs.d/init.el}; you can choose to ++use any one of these three names (@pxref{Find Init}). Here, @file{~/} ++stands for your home directory. ++ ++ You can use the command line switch @samp{-q} to prevent loading ++your init file, and @samp{-u} (or @samp{--user}) to specify a ++different user's init file (@pxref{Initial Options}). ++ ++@cindex @file{default.el}, the default init file ++ There can also be a @dfn{default init file}, which is the library ++named @file{default.el}, found via the standard search path for ++libraries. The Emacs distribution contains no such library; your site ++may create one for local customizations. If this library exists, it is ++loaded whenever you start Emacs (except when you specify @samp{-q}). ++But your init file, if any, is loaded first; if it sets ++@code{inhibit-default-init} non-@code{nil}, then @file{default} is not ++loaded. ++ ++@cindex site init file ++@cindex @file{site-start.el}, the site startup file ++ Your site may also have a @dfn{site startup file}; this is named ++@file{site-start.el}, if it exists. Like @file{default.el}, Emacs ++finds this file via the standard search path for Lisp libraries. ++Emacs loads this library before it loads your init file. To inhibit ++loading of this library, use the option @samp{--no-site-file}. ++@xref{Initial Options}. We recommend against using ++@file{site-start.el} for changes that some users may not like. It is ++better to put them in @file{default.el}, so that users can more easily ++override them. ++ ++ You can place @file{default.el} and @file{site-start.el} in any of ++the directories which Emacs searches for Lisp libraries. The variable ++@code{load-path} (@pxref{Lisp Libraries}) specifies these directories. ++Many sites put these files in the @file{site-lisp} subdirectory of the ++Emacs installation directory, typically ++@file{/usr/local/share/emacs/site-lisp}. ++ ++ Byte-compiling your init file is not recommended (@pxref{Byte ++Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference ++Manual}). It generally does not speed up startup very much, and often ++leads to problems when you forget to recompile the file. A better ++solution is to use the Emacs server to reduce the number of times you ++have to start Emacs (@pxref{Emacs Server}). If your init file defines ++many functions, consider moving them to a separate (byte-compiled) ++file that you load in your init file. ++ ++ If you are going to write actual Emacs Lisp programs that go beyond ++minor customization, you should read the @cite{Emacs Lisp Reference Manual}. ++@ifnottex ++@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference ++Manual}. ++@end ifnottex ++ ++@menu ++* Init Syntax:: Syntax of constants in Emacs Lisp. ++* Init Examples:: How to do some things with an init file. ++* Terminal Init:: Each terminal type can have an init file. ++* Find Init:: How Emacs finds the init file. ++* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. ++@end menu ++ ++@node Init Syntax ++@subsection Init File Syntax ++ ++ The init file contains one or more Lisp expressions. Each of these ++consists of a function name followed by arguments, all surrounded by ++parentheses. For example, @code{(setq fill-column 60)} calls the ++function @code{setq} to set the variable @code{fill-column} ++(@pxref{Filling}) to 60. ++ ++ You can set any Lisp variable with @code{setq}, but with certain ++variables @code{setq} won't do what you probably want in the ++@file{.emacs} file. Some variables automatically become buffer-local ++when set with @code{setq}; what you want in @file{.emacs} is to set ++the default value, using @code{setq-default}. Some customizable minor ++mode variables do special things to enable the mode when you set them ++with Customize, but ordinary @code{setq} won't do that; to enable the ++mode in your @file{.emacs} file, call the minor mode command. The ++following section has examples of both of these methods. ++ ++ The second argument to @code{setq} is an expression for the new ++value of the variable. This can be a constant, a variable, or a ++function call expression. In @file{.emacs}, constants are used most ++of the time. They can be: ++ ++@table @asis ++@item Numbers: ++Numbers are written in decimal, with an optional initial minus sign. ++ ++@item Strings: ++@cindex Lisp string syntax ++@cindex string syntax ++Lisp string syntax is the same as C string syntax with a few extra ++features. Use a double-quote character to begin and end a string constant. ++ ++In a string, you can include newlines and special characters literally. ++But often it is cleaner to use backslash sequences for them: @samp{\n} ++for newline, @samp{\b} for backspace, @samp{\r} for carriage return, ++@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for ++escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or ++@samp{\@var{ooo}} for the character whose octal code is @var{ooo}. ++Backslash and double-quote are the only characters for which backslash ++sequences are mandatory. ++ ++@samp{\C-} can be used as a prefix for a control character, as in ++@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for ++a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for ++@kbd{Control-Meta-A}.@refill ++ ++@xref{Init Non-ASCII}, for information about including ++non-@acronym{ASCII} in your init file. ++ ++@item Characters: ++Lisp character constant syntax consists of a @samp{?} followed by ++either a character or an escape sequence starting with @samp{\}. ++Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that ++strings and characters are not interchangeable in Lisp; some contexts ++require one and some contexts require the other. ++ ++@xref{Init Non-ASCII}, for information about binding commands to ++keys which send non-@acronym{ASCII} characters. ++ ++@item True: ++@code{t} stands for `true'. ++ ++@item False: ++@code{nil} stands for `false'. ++ ++@item Other Lisp objects: ++Write a single-quote (@code{'}) followed by the Lisp object you want. ++@end table ++ ++@node Init Examples ++@subsection Init File Examples ++ ++ Here are some examples of doing certain commonly desired things with ++Lisp expressions: ++ ++@itemize @bullet ++@item ++Add a directory to the variable @code{load-path}. You can then put ++Lisp libraries that are not included with Emacs in this directory, and ++load them with @kbd{M-x load-library}. @xref{Lisp Libraries}. ++ ++@example ++(add-to-list 'load-path "/path/to/lisp/libraries") ++@end example ++ ++@item ++Make @key{TAB} in C mode just insert a tab if point is in the middle of a ++line. ++ ++@example ++(setq c-tab-always-indent nil) ++@end example ++ ++Here we have a variable whose value is normally @code{t} for `true' ++and the alternative is @code{nil} for `false'. ++ ++@item ++Make searches case sensitive by default (in all buffers that do not ++override this). ++ ++@example ++(setq-default case-fold-search nil) ++@end example ++ ++This sets the default value, which is effective in all buffers that do ++not have local values for the variable. Setting @code{case-fold-search} ++with @code{setq} affects only the current buffer's local value, which ++is not what you probably want to do in an init file. ++ ++@item ++@vindex user-mail-address ++Specify your own email address, if Emacs can't figure it out correctly. ++ ++@example ++(setq user-mail-address "rumsfeld@@torture.gov") ++@end example ++ ++Various Emacs packages that need your own email address use the value of ++@code{user-mail-address}. ++ ++@item ++Make Text mode the default mode for new buffers. ++ ++@example ++(setq default-major-mode 'text-mode) ++@end example ++ ++Note that @code{text-mode} is used because it is the command for ++entering Text mode. The single-quote before it makes the symbol a ++constant; otherwise, @code{text-mode} would be treated as a variable ++name. ++ ++@need 1500 ++@item ++Set up defaults for the Latin-1 character set ++which supports most of the languages of Western Europe. ++ ++@example ++(set-language-environment "Latin-1") ++@end example ++ ++@need 1500 ++@item ++Turn off Line Number mode, a global minor mode. ++ ++@example ++(line-number-mode 0) ++@end example ++ ++@need 1500 ++@item ++Turn on Auto Fill mode automatically in Text mode and related modes. ++ ++@example ++(add-hook 'text-mode-hook ++ '(lambda () (auto-fill-mode 1))) ++@end example ++ ++This shows how to add a hook function to a normal hook variable ++(@pxref{Hooks}). The function we supply is a list starting with ++@code{lambda}, with a single-quote in front of it to make it a list ++constant rather than an expression. ++ ++It's beyond the scope of this manual to explain Lisp functions, but for ++this example it is enough to know that the effect is to execute ++@code{(auto-fill-mode 1)} when Text mode is entered. You can replace ++that with any other expression that you like, or with several ++expressions in a row. ++ ++Emacs comes with a function named @code{turn-on-auto-fill} whose ++definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler ++way to write the above example is as follows: ++ ++@example ++(add-hook 'text-mode-hook 'turn-on-auto-fill) ++@end example ++ ++@item ++Load the installed Lisp library named @file{foo} (actually a file ++@file{foo.elc} or @file{foo.el} in a standard Emacs directory). ++ ++@example ++(load "foo") ++@end example ++ ++When the argument to @code{load} is a relative file name, not starting ++with @samp{/} or @samp{~}, @code{load} searches the directories in ++@code{load-path} (@pxref{Lisp Libraries}). ++ ++@item ++Load the compiled Lisp file @file{foo.elc} from your home directory. ++ ++@example ++(load "~/foo.elc") ++@end example ++ ++Here an absolute file name is used, so no searching is done. ++ ++@item ++@cindex loading Lisp libraries automatically ++@cindex autoload Lisp libraries ++Tell Emacs to find the definition for the function @code{myfunction} ++by loading a Lisp library named @file{mypackage} (i.e.@: a file ++@file{mypackage.elc} or @file{mypackage.el}): ++ ++@example ++(autoload 'myfunction "mypackage" "Do what I say." t) ++@end example ++ ++@noindent ++Here the string @code{"Do what I say."} is the function's ++documentation string. You specify it in the @code{autoload} ++definition so it will be available for help commands even when the ++package is not loaded. The last argument, @code{t}, indicates that ++this function is interactive; that is, it can be invoked interactively ++by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. ++If the function is not interactive, omit the @code{t} or use ++@code{nil}. ++ ++@item ++Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link} ++(@pxref{Init Rebinding}). ++ ++@example ++(global-set-key "\C-xl" 'make-symbolic-link) ++@end example ++ ++or ++ ++@example ++(define-key global-map "\C-xl" 'make-symbolic-link) ++@end example ++ ++Note once again the single-quote used to refer to the symbol ++@code{make-symbolic-link} instead of its value as a variable. ++ ++@item ++Do the same thing for Lisp mode only. ++ ++@example ++(define-key lisp-mode-map "\C-xl" 'make-symbolic-link) ++@end example ++ ++@item ++Redefine all keys which now run @code{next-line} in Fundamental mode ++so that they run @code{forward-line} instead. ++ ++@findex substitute-key-definition ++@example ++(substitute-key-definition 'next-line 'forward-line ++ global-map) ++@end example ++ ++@item ++Make @kbd{C-x C-v} undefined. ++ ++@example ++(global-unset-key "\C-x\C-v") ++@end example ++ ++One reason to undefine a key is so that you can make it a prefix. ++Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a ++prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix ++definition. ++ ++@item ++Make @samp{$} have the syntax of punctuation in Text mode. ++Note the use of a character constant for @samp{$}. ++ ++@example ++(modify-syntax-entry ?\$ "." text-mode-syntax-table) ++@end example ++ ++@item ++Enable the use of the command @code{narrow-to-region} without confirmation. ++ ++@example ++(put 'narrow-to-region 'disabled nil) ++@end example ++ ++@item ++Adjusting the configuration to various platforms and Emacs versions. ++ ++Users typically want Emacs to behave the same on all systems, so the ++same init file is right for all platforms. However, sometimes it ++happens that a function you use for customizing Emacs is not available ++on some platforms or in older Emacs versions. To deal with that ++situation, put the customization inside a conditional that tests whether ++the function or facility is available, like this: ++ ++@example ++(if (fboundp 'blink-cursor-mode) ++ (blink-cursor-mode 0)) ++ ++(if (boundp 'coding-category-utf-8) ++ (set-coding-priority '(coding-category-utf-8))) ++@end example ++ ++@noindent ++You can also simply disregard the errors that occur if the ++function is not defined. ++ ++@example ++(condition case () ++ (set-face-background 'region "grey75") ++ (error nil)) ++@end example ++ ++A @code{setq} on a variable which does not exist is generally ++harmless, so those do not need a conditional. ++@end itemize ++ ++@node Terminal Init ++@subsection Terminal-specific Initialization ++ ++ Each terminal type can have a Lisp library to be loaded into Emacs when ++it is run on that type of terminal. For a terminal type named ++@var{termtype}, the library is called @file{term/@var{termtype}} and it is ++found by searching the directories @code{load-path} as usual and trying the ++suffixes @samp{.elc} and @samp{.el}. Normally it appears in the ++subdirectory @file{term} of the directory where most Emacs libraries are ++kept.@refill ++ ++ The usual purpose of the terminal-specific library is to map the ++escape sequences used by the terminal's function keys onto more ++meaningful names, using @code{input-decode-map} (or ++@code{function-key-map} before it). See the file ++@file{term/lk201.el} for an example of how this is done. Many function ++keys are mapped automatically according to the information in the ++Termcap data base; the terminal-specific library needs to map only the ++function keys that Termcap does not specify. ++ ++ When the terminal type contains a hyphen, only the part of the name ++before the first hyphen is significant in choosing the library name. ++Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use ++the library @file{term/aaa}. The code in the library can use ++@code{(getenv "TERM")} to find the full terminal type name.@refill ++ ++@vindex term-file-prefix ++ The library's name is constructed by concatenating the value of the ++variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} ++file can prevent the loading of the terminal-specific library by setting ++@code{term-file-prefix} to @code{nil}. ++ ++@vindex term-setup-hook ++ Emacs runs the hook @code{term-setup-hook} at the end of ++initialization, after both your @file{.emacs} file and any ++terminal-specific library have been read in. Add hook functions to this ++hook if you wish to override part of any of the terminal-specific ++libraries and to define initializations for terminals that do not have a ++library. @xref{Hooks}. ++ ++@node Find Init ++@subsection How Emacs Finds Your Init File ++ ++ Normally Emacs uses the environment variable @env{HOME} ++(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what ++@samp{~} means in a file name. If @file{.emacs} is not found inside ++@file{~/} (nor @file{.emacs.el}), Emacs looks for ++@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be ++byte-compiled). ++ ++ However, if you run Emacs from a shell started by @code{su}, Emacs ++tries to find your own @file{.emacs}, not that of the user you are ++currently pretending to be. The idea is that you should get your own ++editor customizations even if you are running as the super user. ++ ++ More precisely, Emacs first determines which user's init file to use. ++It gets your user name from the environment variables @env{LOGNAME} and ++@env{USER}; if neither of those exists, it uses effective user-ID. ++If that user name matches the real user-ID, then Emacs uses @env{HOME}; ++otherwise, it looks up the home directory corresponding to that user ++name in the system's data base of users. ++@c LocalWords: backtab ++ ++@node Init Non-ASCII ++@subsection Non-@acronym{ASCII} Characters in Init Files ++@cindex international characters in @file{.emacs} ++@cindex non-@acronym{ASCII} characters in @file{.emacs} ++@cindex non-@acronym{ASCII} keys, binding ++@cindex rebinding non-@acronym{ASCII} keys ++ ++ Language and coding systems may cause problems if your init file ++contains non-@acronym{ASCII} characters, such as accented letters, in ++strings or key bindings. ++ ++ If you want to use non-@acronym{ASCII} characters in your init file, ++you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on ++the first line of the init file, and specify a coding system that ++supports the character(s) in question. @xref{Recognize Coding}. This ++is because the defaults for decoding non-@acronym{ASCII} text might ++not yet be set up by the time Emacs reads those parts of your init ++file which use such strings, possibly leading Emacs to decode those ++strings incorrectly. You should then avoid adding Emacs Lisp code ++that modifies the coding system in other ways, such as calls to ++@code{set-language-environment}. ++ ++ To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init ++Rebinding}). The string syntax cannot be used, since the ++non-@acronym{ASCII} characters will be interpreted as meta keys. For ++instance: ++ ++@example ++(global-set-key [?@var{char}] 'some-function) ++@end example ++ ++@noindent ++Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. ++ ++ @strong{Warning:} if you change the keyboard encoding, or change ++between multibyte and unibyte mode, or anything that would alter which ++code @kbd{C-q} would insert for that character, this key binding may ++stop working. It is therefore advisable to use one and only one ++coding system, for your init file as well as the files you edit. For ++example, don't mix the @samp{latin-1} and @samp{latin-9} coding ++systems. ++ ++@ignore ++ arch-tag: c68abddb-4410-4fb5-925f-63394e971d93 ++@end ignore +diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi +new file mode 100644 +index 0000000..5d800f9 +--- /dev/null ++++ b/doc/emacs/dired-xtra.texi +@@ -0,0 +1,48 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@c This file is included either in emacs-xtra.texi (when producing the ++@c printed version) or in the main Emacs manual (for the on-line version). ++@node Subdir Switches ++@section Subdirectory Switches in Dired ++ ++You can insert subdirectories with specified @code{ls} switches in ++Dired buffers using @kbd{C-u i}. You can change the @code{ls} ++switches of an already inserted subdirectory using @kbd{C-u l}. ++ ++Dired preserves the switches if you revert the buffer. Deleting a ++subdirectory forgets about its switches. ++ ++Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) ++to reinsert or delete subdirectories that were inserted with explicit ++switches can bypass Dired's machinery for remembering (or forgetting) ++switches. Deleting a subdirectory using @code{dired-undo} does not ++forget its switches. When later reinserted using @kbd{i}, it will be ++reinserted using its old switches. Using @code{dired-undo} to ++reinsert a subdirectory that was deleted using the regular ++Dired commands (not @code{dired-undo}) will originally insert it with ++its old switches. Reverting the buffer, however, will relist it using ++the buffer's default switches. If any of this yields problems, you ++can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. ++ ++Dired does not remember the @code{R} switch. Inserting a subdirectory ++with switches that include the @code{R} switch is equivalent to ++inserting each of its subdirectories using all remaining switches. ++For instance, updating or killing a subdirectory that was inserted ++with the @code{R} switch will not update or kill its subdirectories. ++ ++The buffer's default switches do not affect subdirectories that were ++inserted using explicitly specified switches. In particular, ++commands such as @kbd{s} that change the buffer's switches do not ++affect such subdirectories. (They do, however, affect subdirectories ++without explicitly assigned switches.) ++ ++You can make Dired forget about all subdirectory switches and relist ++all subdirectories with the buffer's default switches using ++@kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. ++ ++@ignore ++ arch-tag: e3865701-9179-4ffb-bc34-d321111c688d ++@end ignore +diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi +new file mode 100644 +index 0000000..e58a0d7 +--- /dev/null ++++ b/doc/emacs/dired.texi +@@ -0,0 +1,1368 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Dired, Calendar/Diary, Rmail, Top ++@chapter Dired, the Directory Editor ++@c This node is referenced in the tutorial. When renaming or deleting ++@c it, the tutorial needs to be adjusted. ++@cindex Dired ++@cindex file management ++ ++ Dired makes an Emacs buffer containing a listing of a directory, and ++optionally some of its subdirectories as well. You can use the normal ++Emacs commands to move around in this buffer, and special Dired ++commands to operate on the listed files. ++ ++ The Dired buffer is ``read-only,'' and inserting text in it is not ++allowed. Ordinary printing characters such as @kbd{d} and @kbd{x} are ++redefined for special Dired commands. Some Dired commands @dfn{mark} ++or @dfn{flag} the @dfn{current file} (that is, the file on the current ++line); other commands operate on the marked files or on the flagged ++files. You first mark certain files in order to operate on all of ++them with one command. ++ ++ The Dired-X package provides various extra features for Dired mode. ++@xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}. ++ ++ You can also view a list of files in a directory with @kbd{C-x C-d} ++(@code{list-directory}). Unlike Dired, this command does not allow ++you to operate on the listed files. @xref{Directories}. ++ ++@menu ++* Enter: Dired Enter. How to invoke Dired. ++* Navigation: Dired Navigation. Special motion commands in the Dired buffer. ++* Deletion: Dired Deletion. Deleting files with Dired. ++* Flagging Many Files:: Flagging files based on their names. ++* Visit: Dired Visiting. Other file operations through Dired. ++* Marks vs Flags:: Flagging for deletion vs marking. ++* Operating on Files:: How to copy, rename, print, compress, etc. ++ either one file or several files. ++* Shell Commands in Dired:: Running a shell command on the marked files. ++* Transforming File Names:: Using patterns to rename multiple files. ++* Comparison in Dired:: Running `diff' by way of Dired. ++* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. ++@ifnottex ++* Subdir Switches:: Subdirectory switches in Dired. ++@end ifnottex ++* Subdirectory Motion:: Moving across subdirectories, and up and down. ++* Hiding Subdirectories:: Making subdirectories visible or invisible. ++* Updating: Dired Updating. Discarding lines for files of no interest. ++* Find: Dired and Find. Using `find' to choose the files for Dired. ++* Wdired:: Operating on files by editing the Dired buffer. ++* Image-Dired:: Viewing image thumbnails in Dired. ++* Misc: Misc Dired Features. Various other features. ++@end menu ++ ++@node Dired Enter ++@section Entering Dired ++ ++@findex dired ++@kindex C-x d ++@vindex dired-listing-switches ++ To invoke Dired, type @kbd{C-x d} (@code{dired}). This reads a ++directory name using the minibuffer, and opens a @dfn{Dired buffer} ++listing the files in that directory. You can also supply a wildcard ++file name pattern as the minibuffer argument, in which case the Dired ++buffer lists all files matching that pattern. The usual history and ++completion commands can be used in the minibuffer; in particular, ++@kbd{M-n} puts the name of the visited file (if any) in the minibuffer ++(@pxref{Minibuffer History}). ++ ++ You can also invoke Dired by giving @kbd{C-x C-f} (@code{find-file}) ++a directory name. ++ ++ The variable @code{dired-listing-switches} specifies the options to ++give to @code{ls} for listing the directory; this string @emph{must} ++contain @samp{-l}. If you use a numeric prefix argument with the ++@code{dired} command, you can specify the @code{ls} switches with the ++minibuffer before you enter the directory specification. No matter ++how they are specified, the @code{ls} switches can include short ++options (that is, single characters) requiring no arguments, and long ++options (starting with @samp{--}) whose arguments are specified with ++@samp{=}. ++ ++ On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls}; ++see @ref{ls in Lisp}, for options and peculiarities of that emulation. ++ ++@findex dired-other-window ++@kindex C-x 4 d ++@findex dired-other-frame ++@kindex C-x 5 d ++ To display the Dired buffer in another window rather than in the ++selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead ++of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a ++separate frame to display the Dired buffer. ++ ++@node Dired Navigation ++@section Navigation in the Dired Buffer ++ ++@kindex C-n @r{(Dired)} ++@kindex C-p @r{(Dired)} ++ All the usual Emacs cursor motion commands are available in Dired ++buffers. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the ++cursor at the beginning of the file name on the line, rather than at ++the beginning of the line. ++ ++@kindex SPC @r{(Dired)} ++ For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent ++to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines ++is so common in Dired that it deserves to be easy to type.) @key{DEL} ++(move up and unflag) is also often useful simply for moving up ++(@pxref{Dired Deletion}). ++ ++@findex dired-goto-file ++@kindex j @r{(Dired)} ++ @kbd{j} (@code{dired-goto-file}) prompts for a file name using the ++minibuffer, and moves point to the line in the Dired buffer describing ++that file. ++ ++@cindex searching Dired buffers ++@vindex dired-isearch-filenames ++ @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward ++incremental search in the Dired buffer, looking for matches only ++amongst the file names and ignoring the rest of the text in the ++buffer. @kbd{M-s f M-C-s} (@code{dired-isearch-filenames-regexp}) ++does the same, using a regular expression search. If you change the ++variable @var{dired-isearch-filenames} to @code{t}, then the ++usual search commands also limit themselves to the file names; for ++instance, @kbd{C-s} behaves like @kbd{M-s f C-s}. If the value is ++@code{dwim}, then search commands match the file names only when point ++was on a file name initially. @xref{Search}, for information about ++incremental search. ++ ++ Some additional navigation commands are available when the Dired ++buffer includes several directories. @xref{Subdirectory Motion}. ++ ++@node Dired Deletion ++@section Deleting Files with Dired ++@cindex flagging files (in Dired) ++@cindex deleting files (in Dired) ++ ++ One of the most frequent uses of Dired is to first @dfn{flag} files for ++deletion, then delete the files that were flagged. ++ ++@table @kbd ++@item d ++Flag this file for deletion. ++@item u ++Remove deletion flag on this line. ++@item @key{DEL} ++Move point to previous line and remove the deletion flag on that line. ++@item x ++Delete the files that are flagged for deletion. ++@end table ++ ++@kindex d @r{(Dired)} ++@findex dired-flag-file-deletion ++ You can flag a file for deletion by moving to the line describing ++the file and typing @kbd{d} (@code{dired-flag-file-deletion}). The ++deletion flag is visible as a @samp{D} at the beginning of the line. ++This command moves point to the next line, so that repeated @kbd{d} ++commands flag successive files. A numeric argument serves as a repeat ++count. ++ ++@kindex u @r{(Dired deletion)} ++@kindex DEL @r{(Dired)} ++ The reason for flagging files for deletion, rather than deleting ++files immediately, is to reduce the danger of deleting a file ++accidentally. Until you direct Dired to delete the flagged files, you ++can remove deletion flags using the commands @kbd{u} and @key{DEL}. ++@kbd{u} (@code{dired-unmark}) works just like @kbd{d}, but removes ++flags rather than making flags. @key{DEL} ++(@code{dired-unmark-backward}) moves upward, removing flags; it is ++like @kbd{u} with argument @minus{}1. ++ ++@kindex x @r{(Dired)} ++@findex dired-do-flagged-delete ++ To delete the flagged files, type @kbd{x} ++(@code{dired-do-flagged-delete}). This command first displays a list ++of all the file names flagged for deletion, and requests confirmation ++with @kbd{yes}. If you confirm, Dired deletes the flagged files, then ++deletes their lines from the text of the Dired buffer. The Dired ++buffer, with somewhat fewer lines, remains selected. ++ ++ If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you ++return immediately to Dired, with the deletion flags still present in ++the buffer, and no files actually deleted. ++ ++@cindex recursive deletion ++@vindex dired-recursive-deletes ++ You can delete empty directories just like other files, but normally ++Dired cannot delete directories that are nonempty. If the variable ++@code{dired-recursive-deletes} is non-@code{nil}, then Dired can ++delete nonempty directories including all their contents. That can ++be somewhat risky. ++ ++@vindex delete-by-moving-to-trash ++ On some systems, there is a facility called the ``Trash'' or ++``Recycle Bin'', but Emacs does @emph{not} use it by default. Thus, ++when you delete a file in Dired, it is gone forever. However, you can ++tell Emacs to use the Trash for file deletion, by changing the ++variable @code{delete-by-moving-to-trash} to @code{t}. @xref{Misc ++File Ops}, for more information about the Trash. ++ ++@node Flagging Many Files ++@section Flagging Many Files at Once ++@cindex flagging many files for deletion (in Dired) ++ ++ The @kbd{#}, @kbd{~}, @kbd{.}, @kbd{% &}, and @kbd{% d} commands ++flag many files for deletion, based on their file names: ++ ++@table @kbd ++@item # ++Flag all auto-save files (files whose names start and end with @samp{#}) ++for deletion (@pxref{Auto Save}). ++ ++@item ~ ++Flag all backup files (files whose names end with @samp{~}) for deletion ++(@pxref{Backup}). ++ ++@item .@: @r{(Period)} ++Flag excess numeric backup files for deletion. The oldest and newest ++few backup files of any one file are exempt; the middle ones are ++flagged. ++ ++@item % & ++Flag for deletion all files with certain kinds of names which suggest ++you could easily create those files again. ++ ++@item % d @var{regexp} @key{RET} ++Flag for deletion all files whose names match the regular expression ++@var{regexp}. ++@end table ++ ++@kindex # @r{(Dired)} ++@findex dired-flag-auto-save-files ++@cindex deleting auto-save files ++ @kbd{#} (@code{dired-flag-auto-save-files}) flags all files whose ++names look like auto-save files---that is, files whose names begin and ++end with @samp{#}. @xref{Auto Save}. ++ ++@kindex ~ @r{(Dired)} ++@findex dired-flag-backup-files ++ @kbd{~} (@code{dired-flag-backup-files}) flags all files whose names ++say they are backup files---that is, files whose names end in ++@samp{~}. @xref{Backup}. ++ ++@kindex . @r{(Dired)} ++@vindex dired-kept-versions ++@findex dired-clean-directory ++ @kbd{.} (period, @code{dired-clean-directory}) flags just some of ++the backup files for deletion: all but the oldest few and newest few ++backups of any one file. Normally, the number of newest versions kept ++for each file is given by the variable @code{dired-kept-versions} ++(@strong{not} @code{kept-new-versions}; that applies only when ++saving). The number of oldest versions to keep is given by the ++variable @code{kept-old-versions}. ++ ++ Period with a positive numeric argument, as in @kbd{C-u 3 .}, ++specifies the number of newest versions to keep, overriding ++@code{dired-kept-versions}. A negative numeric argument overrides ++@code{kept-old-versions}, using minus the value of the argument to ++specify the number of oldest versions of each file to keep. ++ ++@kindex % & @r{(Dired)} ++@findex dired-flag-garbage-files ++@vindex dired-garbage-files-regexp ++@cindex deleting some backup files ++ @kbd{% &} (@code{dired-flag-garbage-files}) flags files whose names ++match the regular expression specified by the variable ++@code{dired-garbage-files-regexp}. By default, this matches certain ++files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and ++@samp{.rej} files produced by @code{patch}. ++ ++@findex dired-flag-files-regexp ++@kindex % d @r{(Dired)} ++ @kbd{% d} flags all files whose names match a specified regular ++expression (@code{dired-flag-files-regexp}). Only the non-directory ++part of the file name is used in matching. You can use @samp{^} and ++@samp{$} to anchor matches. You can exclude certain subdirectories ++from marking by hiding them while you use @kbd{% d}. @xref{Hiding ++Subdirectories}. ++ ++@node Dired Visiting ++@section Visiting Files in Dired ++ ++ There are several Dired commands for visiting or examining the files ++listed in the Dired buffer. All of them apply to the current line's ++file; if that file is really a directory, these commands invoke Dired on ++that subdirectory (making a separate Dired buffer). ++ ++@table @kbd ++@item f ++@kindex f @r{(Dired)} ++@findex dired-find-file ++Visit the file described on the current line, like typing @kbd{C-x C-f} ++and supplying that file name (@code{dired-find-file}). @xref{Visiting}. ++ ++@item @key{RET} ++@itemx e ++@kindex RET @r{(Dired)} ++@kindex e @r{(Dired)} ++Equivalent to @kbd{f}. ++ ++@ignore @c This command seems too risky to document at all. ++@item a ++@kindex a @r{(Dired)} ++@findex dired-find-alternate-file ++Like @kbd{f}, but replaces the contents of the Dired buffer with ++that of an alternate file or directory (@code{dired-find-alternate-file}). ++@end ignore ++ ++@item o ++@kindex o @r{(Dired)} ++@findex dired-find-file-other-window ++Like @kbd{f}, but uses another window to display the file's buffer ++(@code{dired-find-file-other-window}). The Dired buffer remains visible ++in the first window. This is like using @kbd{C-x 4 C-f} to visit the ++file. @xref{Windows}. ++ ++@item C-o ++@kindex C-o @r{(Dired)} ++@findex dired-display-file ++Visit the file described on the current line, and display the buffer in ++another window, but do not select that window (@code{dired-display-file}). ++ ++@item Mouse-1 ++@itemx Mouse-2 ++@findex dired-mouse-find-file-other-window ++Visit the file named by the line you click on ++(@code{dired-mouse-find-file-other-window}). This uses another window ++to display the file, like the @kbd{o} command. ++ ++@item v ++@kindex v @r{(Dired)} ++@findex dired-view-file ++View the file described on the current line, using @kbd{M-x view-file} ++(@code{dired-view-file}). Viewing a file with @code{view-file} is ++like visiting it, but is slanted toward moving around in the file ++conveniently and does not allow changing the file. @xref{Misc File ++Ops, View File, Miscellaneous File Operations}. ++ ++@item ^ ++@kindex ^ @r{(Dired)} ++@findex dired-up-directory ++Visit the parent directory of the current directory ++(@code{dired-up-directory}). This is equivalent to moving to the line ++for @file{..} and typing @kbd{f} there. ++@end table ++ ++@node Marks vs Flags ++@section Dired Marks vs. Flags ++ ++@cindex marking many files (in Dired) ++ Instead of flagging a file with @samp{D}, you can @dfn{mark} the ++file with some other character (usually @samp{*}). Most Dired ++commands to operate on files use the files marked with @samp{*}. The ++only command that operates on flagged files is @kbd{x}, which deletes ++them. ++ ++ Here are some commands for marking with @samp{*}, for unmarking, and ++for operating on marks. (@xref{Dired Deletion}, for commands to flag ++and unflag files.) ++ ++@table @kbd ++@item m ++@itemx * m ++@kindex m @r{(Dired)} ++@kindex * m @r{(Dired)} ++@findex dired-mark ++Mark the current file with @samp{*} (@code{dired-mark}). With a numeric ++argument @var{n}, mark the next @var{n} files starting with the current ++file. (If @var{n} is negative, mark the previous @minus{}@var{n} ++files.) ++ ++@item * * ++@kindex * * @r{(Dired)} ++@findex dired-mark-executables ++@cindex marking executable files (in Dired) ++Mark all executable files with @samp{*} ++(@code{dired-mark-executables}). With a numeric argument, unmark all ++those files. ++ ++@item * @@ ++@kindex * @@ @r{(Dired)} ++@findex dired-mark-symlinks ++@cindex marking symbolic links (in Dired) ++Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}). ++With a numeric argument, unmark all those files. ++ ++@item * / ++@kindex * / @r{(Dired)} ++@findex dired-mark-directories ++@cindex marking subdirectories (in Dired) ++Mark with @samp{*} all files which are directories, except for ++@file{.} and @file{..} (@code{dired-mark-directories}). With a numeric ++argument, unmark all those files. ++ ++@item * s ++@kindex * s @r{(Dired)} ++@findex dired-mark-subdir-files ++Mark all the files in the current subdirectory, aside from @file{.} ++and @file{..} (@code{dired-mark-subdir-files}). ++ ++@item u ++@itemx * u ++@kindex u @r{(Dired)} ++@kindex * u @r{(Dired)} ++@findex dired-unmark ++Remove any mark on this line (@code{dired-unmark}). ++ ++@item @key{DEL} ++@itemx * @key{DEL} ++@kindex * DEL @r{(Dired)} ++@findex dired-unmark-backward ++@cindex unmarking files (in Dired) ++Move point to previous line and remove any mark on that line ++(@code{dired-unmark-backward}). ++ ++@item * ! ++@itemx U ++@kindex * ! @r{(Dired)} ++@kindex U @r{(Dired)} ++@findex dired-unmark-all-marks ++Remove all marks from all the files in this Dired buffer ++(@code{dired-unmark-all-marks}). ++ ++@item * ? @var{markchar} ++@itemx M-@key{DEL} ++@kindex * ? @r{(Dired)} ++@kindex M-DEL @r{(Dired)} ++@findex dired-unmark-all-files ++Remove all marks that use the character @var{markchar} ++(@code{dired-unmark-all-files}). The argument is a single ++character---do not use @key{RET} to terminate it. See the description ++of the @kbd{* c} command below, which lets you replace one mark ++character with another. ++ ++With a numeric argument, this command queries about each marked file, ++asking whether to remove its mark. You can answer @kbd{y} meaning yes, ++@kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining ++files without asking about them. ++ ++@item * C-n ++@itemx M-@} ++@findex dired-next-marked-file ++@kindex * C-n @r{(Dired)} ++@kindex M-@} @r{(Dired)} ++Move down to the next marked file (@code{dired-next-marked-file}) ++A file is ``marked'' if it has any kind of mark. ++ ++@item * C-p ++@itemx M-@{ ++@findex dired-prev-marked-file ++@kindex * C-p @r{(Dired)} ++@kindex M-@{ @r{(Dired)} ++Move up to the previous marked file (@code{dired-prev-marked-file}) ++ ++@item t ++@itemx * t ++@kindex t @r{(Dired)} ++@kindex * t @r{(Dired)} ++@findex dired-toggle-marks ++@cindex toggling marks (in Dired) ++Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*} ++become unmarked, and unmarked files are marked with @samp{*}. Files ++marked in any other way are not affected. ++ ++@item * c @var{old-markchar} @var{new-markchar} ++@kindex * c @r{(Dired)} ++@findex dired-change-marks ++Replace all marks that use the character @var{old-markchar} with marks ++that use the character @var{new-markchar} (@code{dired-change-marks}). ++This command is the primary way to create or use marks other than ++@samp{*} or @samp{D}. The arguments are single characters---do not use ++@key{RET} to terminate them. ++ ++You can use almost any character as a mark character by means of this ++command, to distinguish various classes of files. If @var{old-markchar} ++is a space (@samp{ }), then the command operates on all unmarked files; ++if @var{new-markchar} is a space, then the command unmarks the files it ++acts on. ++ ++To illustrate the power of this command, here is how to put @samp{D} ++flags on all the files that have no marks, while unflagging all those ++that already have @samp{D} flags: ++ ++@example ++* c D t * c SPC D * c t SPC ++@end example ++ ++This assumes that no files were already marked with @samp{t}. ++ ++@item % m @var{regexp} @key{RET} ++@itemx * % @var{regexp} @key{RET} ++@findex dired-mark-files-regexp ++@kindex % m @r{(Dired)} ++@kindex * % @r{(Dired)} ++Mark (with @samp{*}) all files whose names match the regular expression ++@var{regexp} (@code{dired-mark-files-regexp}). This command is like ++@kbd{% d}, except that it marks files with @samp{*} instead of flagging ++with @samp{D}. ++ ++Only the non-directory part of the file name is used in matching. Use ++@samp{^} and @samp{$} to anchor matches. You can exclude ++subdirectories by temporarily hiding them (@pxref{Hiding ++Subdirectories}). ++ ++@item % g @var{regexp} @key{RET} ++@findex dired-mark-files-containing-regexp ++@kindex % g @r{(Dired)} ++@cindex finding files containing regexp matches (in Dired) ++Mark (with @samp{*}) all files whose @emph{contents} contain a match for ++the regular expression @var{regexp} ++(@code{dired-mark-files-containing-regexp}). This command is like ++@kbd{% m}, except that it searches the file contents instead of the file ++name. ++ ++@item C-x u ++@itemx C-_ ++@itemx C-/ ++@kindex C-_ @r{(Dired)} ++@findex dired-undo ++Undo changes in the Dired buffer, such as adding or removing ++marks (@code{dired-undo}). @emph{This command does not revert the ++actual file operations, nor recover lost files!} It just undoes ++changes in the buffer itself. ++ ++In some cases, using this after commands that operate on files can ++cause trouble. For example, after renaming one or more files, ++@code{dired-undo} restores the original names in the Dired buffer, ++which gets the Dired buffer out of sync with the actual contents of ++the directory. ++@end table ++ ++@node Operating on Files ++@section Operating on Files ++@cindex operating on files in Dired ++ ++ This section describes the basic Dired commands to operate on one file ++or several files. All of these commands are capital letters; all of ++them use the minibuffer, either to read an argument or to ask for ++confirmation, before they act. All of them let you specify the ++files to manipulate in these ways: ++ ++@itemize @bullet ++@item ++If you give the command a numeric prefix argument @var{n}, it operates ++on the next @var{n} files, starting with the current file. (If @var{n} ++is negative, the command operates on the @minus{}@var{n} files preceding ++the current line.) ++ ++@item ++Otherwise, if some files are marked with @samp{*}, the command operates ++on all those files. ++ ++@item ++Otherwise, the command operates on the current file only. ++@end itemize ++ ++@noindent ++Certain other Dired commands, such as @kbd{!} and the @samp{%} ++commands, use the same conventions to decide which files to work on. ++ ++@vindex dired-dwim-target ++@cindex two directories (in Dired) ++ Commands which ask for a destination directory, such as those which ++copy and rename files or create links for them, try to guess the default ++target directory for the operation. Normally, they suggest the Dired ++buffer's default directory, but if the variable @code{dired-dwim-target} ++is non-@code{nil}, and if there is another Dired buffer displayed in the ++next window, that other buffer's directory is suggested instead. ++ ++ Here are the file-manipulating Dired commands that operate on files. ++ ++@table @kbd ++@findex dired-do-copy ++@kindex C @r{(Dired)} ++@cindex copying files (in Dired) ++@item C @var{new} @key{RET} ++Copy the specified files (@code{dired-do-copy}). The argument @var{new} ++is the directory to copy into, or (if copying a single file) the new ++name. This is like the shell command @code{cp}. ++ ++@vindex dired-copy-preserve-time ++If @code{dired-copy-preserve-time} is non-@code{nil}, then copying ++with this command preserves the modification time of the old file in ++the copy, like @samp{cp -p}. ++ ++@vindex dired-recursive-copies ++@cindex recursive copying ++The variable @code{dired-recursive-copies} controls whether to copy ++directories recursively (like @samp{cp -r}). The default is ++@code{nil}, which means that directories cannot be copied. ++ ++@item D ++@findex dired-do-delete ++@kindex D @r{(Dired)} ++Delete the specified files (@code{dired-do-delete}). This is like the ++shell command @code{rm}. ++ ++Like the other commands in this section, this command operates on the ++@emph{marked} files, or the next @var{n} files. By contrast, @kbd{x} ++(@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files. ++ ++@findex dired-do-rename ++@kindex R @r{(Dired)} ++@cindex renaming files (in Dired) ++@cindex moving files (in Dired) ++@item R @var{new} @key{RET} ++Rename the specified files (@code{dired-do-rename}). If you rename a ++single file, the argument @var{new} is the new name of the file. If ++you rename several files, the argument @var{new} is the directory into ++which to move the files (this is like the shell command @code{mv}). ++ ++Dired automatically changes the visited file name of buffers associated ++with renamed files so that they refer to the new names. ++ ++@findex dired-do-hardlink ++@kindex H @r{(Dired)} ++@cindex hard links (in Dired) ++@item H @var{new} @key{RET} ++Make hard links to the specified files (@code{dired-do-hardlink}). ++This is like the shell command @code{ln}. The argument @var{new} is ++the directory to make the links in, or (if making just one link) the ++name to give the link. ++ ++@findex dired-do-symlink ++@kindex S @r{(Dired)} ++@cindex symbolic links (creation in Dired) ++@item S @var{new} @key{RET} ++Make symbolic links to the specified files (@code{dired-do-symlink}). ++This is like @samp{ln -s}. The argument @var{new} is the directory to ++make the links in, or (if making just one link) the name to give the ++link. ++ ++@findex dired-do-chmod ++@kindex M @r{(Dired)} ++@cindex changing file permissions (in Dired) ++@item M @var{modespec} @key{RET} ++Change the mode (also called ``permission bits'') of the specified files ++(@code{dired-do-chmod}). This uses the @code{chmod} program, so ++@var{modespec} can be any argument that @code{chmod} can handle. ++ ++@findex dired-do-chgrp ++@kindex G @r{(Dired)} ++@cindex changing file group (in Dired) ++@item G @var{newgroup} @key{RET} ++Change the group of the specified files to @var{newgroup} ++(@code{dired-do-chgrp}). ++ ++@findex dired-do-chown ++@kindex O @r{(Dired)} ++@cindex changing file owner (in Dired) ++@item O @var{newowner} @key{RET} ++Change the owner of the specified files to @var{newowner} ++(@code{dired-do-chown}). (On most systems, only the superuser can do ++this.) ++ ++@vindex dired-chown-program ++The variable @code{dired-chown-program} specifies the name of the ++program to use to do the work (different systems put @code{chown} in ++different places). ++ ++@findex dired-do-touch ++@kindex T @r{(Dired)} ++@cindex changing file time (in Dired) ++@item T @var{timestamp} @key{RET} ++Touch the specified files (@code{dired-do-touch}). This means ++updating their modification times to the present time. This is like ++the shell command @code{touch}. ++ ++@findex dired-do-print ++@kindex P @r{(Dired)} ++@cindex printing files (in Dired) ++@item P @var{command} @key{RET} ++Print the specified files (@code{dired-do-print}). You must specify the ++command to print them with, but the minibuffer starts out with a ++suitable guess made using the variables @code{lpr-command} and ++@code{lpr-switches} (the same variables that @code{lpr-buffer} uses; ++@pxref{Printing}). ++ ++@findex dired-do-compress ++@kindex Z @r{(Dired)} ++@cindex compressing files (in Dired) ++@item Z ++Compress the specified files (@code{dired-do-compress}). If the file ++appears to be a compressed file already, uncompress it instead. ++ ++@findex dired-do-load ++@kindex L @r{(Dired)} ++@cindex loading several files (in Dired) ++@item L ++Load the specified Emacs Lisp files (@code{dired-do-load}). ++@xref{Lisp Libraries}. ++ ++@findex dired-do-byte-compile ++@kindex B @r{(Dired)} ++@cindex byte-compiling several files (in Dired) ++@item B ++Byte compile the specified Emacs Lisp files ++(@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte ++Compilation, elisp, The Emacs Lisp Reference Manual}. ++ ++@kindex A @r{(Dired)} ++@findex dired-do-search ++@cindex search multiple files (in Dired) ++@item A @var{regexp} @key{RET} ++Search all the specified files for the regular expression @var{regexp} ++(@code{dired-do-search}). ++ ++This command is a variant of @code{tags-search}. The search stops at ++the first match it finds; use @kbd{M-,} to resume the search and find ++the next match. @xref{Tags Search}. ++ ++@kindex Q @r{(Dired)} ++@findex dired-do-query-replace-regexp ++@cindex search and replace in multiple files (in Dired) ++@item Q @var{regexp} @key{RET} @var{to} @key{RET} ++Perform @code{query-replace-regexp} on each of the specified files, ++replacing matches for @var{regexp} with the string ++@var{to} (@code{dired-do-query-replace-regexp}). ++ ++This command is a variant of @code{tags-query-replace}. If you exit the ++query replace loop, you can use @kbd{M-,} to resume the scan and replace ++more matches. @xref{Tags Search}. ++@end table ++ ++@node Shell Commands in Dired ++@section Shell Commands in Dired ++@cindex shell commands, Dired ++ ++@findex dired-do-shell-command ++@kindex ! @r{(Dired)} ++@kindex X @r{(Dired)} ++The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a ++shell command string in the minibuffer and runs that shell command on ++one or more files. The files that the shell command operates on are ++determined in the usual way for Dired commands (@pxref{Operating on ++Files}). The command @kbd{X} is a synonym for @kbd{!}. ++ ++ The command @kbd{&} (@code{dired-do-async-shell-command}) does the ++same, except that it runs the shell command asynchronously. You can ++also do this with @kbd{!}, by appending a @samp{&} character to the ++end of the shell command. ++ ++ For both @kbd{!} and @kbd{&}, the working directory for the shell ++command is the top-level directory of the Dired buffer. ++ ++ If you tell @kbd{!} or @kbd{&} to operate on more than one file, the ++shell command string determines how those files are passed to the ++shell command: ++ ++@itemize @bullet ++@item ++If you use @samp{*} surrounded by whitespace in the command string, ++then the command runs just once, with the list of file names ++substituted for the @samp{*}. The order of file names is the order of ++appearance in the Dired buffer. ++ ++Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire ++list of file names, putting them into one tar file @file{foo.tar}. ++ ++If you want to use @samp{*} as a shell wildcard with whitespace around ++it, write @samp{*""}. In the shell, this is equivalent to @samp{*}; ++but since the @samp{*} is not surrounded by whitespace, Dired does not ++treat it specially. ++ ++@item ++Otherwise, if the command string contains @samp{?} surrounded by ++whitespace, Emacs runs the shell command once @emph{for each file}, ++substituting the current file name for @samp{?} each time. You can ++use @samp{?} more than once in the command; the same file name ++replaces each occurrence. ++ ++@item ++If the command string contains neither @samp{*} nor @samp{?}, Emacs ++runs the shell command once for each file, adding the file name is ++added at the end. For example, @kbd{! uudecode @key{RET}} runs ++@code{uudecode} on each file. ++@end itemize ++ ++ To iterate over the file names in a more complicated fashion, use an ++explicit shell loop. For example, here is how to uuencode each file, ++making the output file name by appending @samp{.uu} to the input file ++name: ++ ++@example ++for file in * ; do uuencode "$file" "$file" >"$file".uu; done ++@end example ++ ++ The @kbd{!} and @kbd{&} commands do not attempt to update the Dired ++buffer to show new or modified files, because they don't know what ++files will be changed. Use the @kbd{g} command to update the Dired ++buffer (@pxref{Dired Updating}). ++ ++ @xref{Single Shell}, for information about running shell commands ++outside Dired. ++ ++@node Transforming File Names ++@section Transforming File Names in Dired ++ ++ This section describes Dired commands which alter file names in a ++systematic way. Each command operates on some or all of the marked ++files, using a new name made by transforming the existing name. ++ ++ Like the basic Dired file-manipulation commands (@pxref{Operating on ++Files}), the commands described here operate either on the next ++@var{n} files, or on all files marked with @samp{*}, or on the current ++file. (To mark files, use the commands described in @ref{Marks vs ++Flags}.) ++ ++ All of the commands described in this section work ++@emph{interactively}: they ask you to confirm the operation for each ++candidate file. Thus, you can select more files than you actually ++need to operate on (e.g., with a regexp that matches many files), and ++then filter the selected names by typing @kbd{y} or @kbd{n} when the ++command prompts for confirmation. ++ ++@table @kbd ++@findex dired-upcase ++@kindex % u @r{(Dired)} ++@cindex upcase file names ++@item % u ++Rename each of the selected files to an upper-case name ++(@code{dired-upcase}). If the old file names are @file{Foo} ++and @file{bar}, the new names are @file{FOO} and @file{BAR}. ++ ++@item % l ++@findex dired-downcase ++@kindex % l @r{(Dired)} ++@cindex downcase file names ++Rename each of the selected files to a lower-case name ++(@code{dired-downcase}). If the old file names are @file{Foo} and ++@file{bar}, the new names are @file{foo} and @file{bar}. ++ ++@item % R @var{from} @key{RET} @var{to} @key{RET} ++@kindex % R @r{(Dired)} ++@findex dired-do-rename-regexp ++@itemx % C @var{from} @key{RET} @var{to} @key{RET} ++@kindex % C @r{(Dired)} ++@findex dired-do-copy-regexp ++@itemx % H @var{from} @key{RET} @var{to} @key{RET} ++@kindex % H @r{(Dired)} ++@findex dired-do-hardlink-regexp ++@itemx % S @var{from} @key{RET} @var{to} @key{RET} ++@kindex % S @r{(Dired)} ++@findex dired-do-symlink-regexp ++These four commands rename, copy, make hard links and make soft links, ++in each case computing the new name by regular-expression substitution ++from the name of the old file. ++@end table ++ ++ The four regular-expression substitution commands effectively ++perform a search-and-replace on the selected file names. They read ++two arguments: a regular expression @var{from}, and a substitution ++pattern @var{to}; they match each ``old'' file name against ++@var{from}, and then replace the matching part with @var{to}. You can ++use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or ++part of what the pattern matched in the old file name, as in ++@code{replace-regexp} (@pxref{Regexp Replace}). If the regular ++expression matches more than once in a file name, only the first match ++is replaced. ++ ++ For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each ++selected file by prepending @samp{x-} to its name. The inverse of this, ++removing @samp{x-} from the front of each file name, is also possible: ++one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is ++@kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor ++matches that should span the whole file name.) ++ ++ Normally, the replacement process does not consider the files' ++directory names; it operates on the file name within the directory. If ++you specify a numeric argument of zero, then replacement affects the ++entire absolute file name including directory name. (A non-zero ++argument specifies the number of files to operate on.) ++ ++ You may want to select the set of files to operate on using the same ++regexp @var{from} that you will use to operate on them. To do this, ++mark those files with @kbd{% m @var{from} @key{RET}}, then use the ++same regular expression in the command to operate on the files. To ++make this more convenient, the @kbd{%} commands to operate on files ++use the last regular expression specified in any @kbd{%} command as a ++default. ++ ++@node Comparison in Dired ++@section File Comparison with Dired ++@cindex file comparison (in Dired) ++@cindex compare files (in Dired) ++ ++ Here are two Dired commands that compare specified files using ++@code{diff}. They show the output in a buffer using Diff mode ++(@pxref{Comparing Files}). ++ ++@table @kbd ++@item = ++@findex dired-diff ++@kindex = @r{(Dired)} ++Compare the current file (the file at point) with another file (the ++file at the mark) using the @code{diff} program (@code{dired-diff}). ++The file at the mark is the first argument of @code{diff}, and the ++file at point is the second argument. This refers to the ordinary ++Emacs mark, not Dired marks; use @kbd{C-@key{SPC}} ++(@code{set-mark-command}) to set the mark at the first file's line ++(@pxref{Setting Mark}). ++ ++@findex dired-backup-diff ++@kindex M-= @r{(Dired)} ++@item M-= ++Compare the current file with its latest backup file ++(@code{dired-backup-diff}). If the current file is itself a backup, ++compare it with the file it is a backup of; this way, you can compare ++a file with any one of its backups. ++ ++The backup file is the first file given to @code{diff}. ++@end table ++ ++@node Subdirectories in Dired ++@section Subdirectories in Dired ++@cindex subdirectories in Dired ++@cindex expanding subdirectories in Dired ++ ++ A Dired buffer displays just one directory in the normal case; ++but you can optionally include its subdirectories as well. ++ ++ The simplest way to include multiple directories in one Dired buffer is ++to specify the options @samp{-lR} for running @code{ls}. (If you give a ++numeric argument when you run Dired, then you can specify these options ++in the minibuffer.) That produces a recursive directory listing showing ++all subdirectories at all levels. ++ ++ More often, you will want to show only specific subdirectories. You ++can do this with the @kbd{i} command: ++ ++@table @kbd ++@findex dired-maybe-insert-subdir ++@kindex i @r{(Dired)} ++@item i ++@cindex inserted subdirectory (Dired) ++@cindex in-situ subdirectory (Dired) ++Insert the contents of a subdirectory later in the buffer. ++@end table ++ ++Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line ++that describes a file which is a directory. It inserts the contents of ++that directory into the same Dired buffer, and moves there. Inserted ++subdirectory contents follow the top-level directory of the Dired ++buffer, just as they do in @samp{ls -lR} output. ++ ++If the subdirectory's contents are already present in the buffer, the ++@kbd{i} command just moves to it. ++ ++In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u ++C-@key{SPC}} takes you back to the old position in the buffer (the line ++describing that subdirectory). You can also use @samp{^} to return ++to the parent directory in the same Dired buffer. ++ ++Use the @kbd{l} command (@code{dired-do-redisplay}) to update the ++subdirectory's contents. Use @kbd{C-u k} on the subdirectory header ++line to delete the subdirectory (@pxref{Dired Updating}). You can also ++hide and show inserted subdirectories (@pxref{Hiding Subdirectories}). ++ ++@ifnottex ++@include dired-xtra.texi ++@end ifnottex ++ ++@node Subdirectory Motion ++@section Moving Over Subdirectories ++ ++ When a Dired buffer lists subdirectories, you can use the page motion ++commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories ++(@pxref{Pages}). ++ ++@cindex header line (Dired) ++@cindex directory header lines ++ The following commands move across, up and down in the tree of ++directories within one Dired buffer. They move to @dfn{directory header ++lines}, which are the lines that give a directory's name, at the ++beginning of the directory's contents. ++ ++@table @kbd ++@findex dired-next-subdir ++@kindex C-M-n @r{(Dired)} ++@item C-M-n ++Go to next subdirectory header line, regardless of level ++(@code{dired-next-subdir}). ++ ++@findex dired-prev-subdir ++@kindex C-M-p @r{(Dired)} ++@item C-M-p ++Go to previous subdirectory header line, regardless of level ++(@code{dired-prev-subdir}). ++ ++@findex dired-tree-up ++@kindex C-M-u @r{(Dired)} ++@item C-M-u ++Go up to the parent directory's header line (@code{dired-tree-up}). ++ ++@findex dired-tree-down ++@kindex C-M-d @r{(Dired)} ++@item C-M-d ++Go down in the directory tree, to the first subdirectory's header line ++(@code{dired-tree-down}). ++ ++@findex dired-prev-dirline ++@kindex < @r{(Dired)} ++@item < ++Move up to the previous directory-file line (@code{dired-prev-dirline}). ++These lines are the ones that describe a directory as a file in its ++parent directory. ++ ++@findex dired-next-dirline ++@kindex > @r{(Dired)} ++@item > ++Move down to the next directory-file line (@code{dired-prev-dirline}). ++@end table ++ ++@node Hiding Subdirectories ++@section Hiding Subdirectories ++@cindex hiding subdirectories (Dired) ++@cindex showing hidden subdirectories (Dired) ++ ++ @dfn{Hiding} a subdirectory means to make it invisible, except for its ++header line. ++ ++@table @kbd ++@item $ ++@findex dired-hide-subdir ++@kindex $ @r{(Dired)} ++Hide or show the subdirectory that point is in, and move point to the ++next subdirectory (@code{dired-hide-subdir}). This is a toggle. A ++numeric argument serves as a repeat count. ++ ++@item M-$ ++@findex dired-hide-all ++@kindex M-$ @r{(Dired)} ++Hide all subdirectories in this Dired buffer, leaving only their header ++lines (@code{dired-hide-all}). Or, if any subdirectory is currently ++hidden, make all subdirectories visible again. You can use this command ++to get an overview in very deep directory trees or to move quickly to ++subdirectories far away. ++@end table ++ ++ Ordinary Dired commands never consider files inside a hidden ++subdirectory. For example, the commands to operate on marked files ++ignore files in hidden directories even if they are marked. Thus you ++can use hiding to temporarily exclude subdirectories from operations ++without having to remove the Dired marks on files in those ++subdirectories. ++ ++@xref{Dired Updating}, for how to insert or delete a subdirectory listing. ++ ++@node Dired Updating ++@section Updating the Dired Buffer ++@cindex updating Dired buffer ++@cindex refreshing displayed files ++ ++ This section describes commands to update the Dired buffer to reflect ++outside (non-Dired) changes in the directories and files, and to delete ++part of the Dired buffer. ++ ++@table @kbd ++@item g ++Update the entire contents of the Dired buffer (@code{revert-buffer}). ++ ++@item l ++Update the specified files (@code{dired-do-redisplay}). You specify the ++files for @kbd{l} in the same way as for file operations. ++ ++@item k ++Delete the specified @emph{file lines}---not the files, just the lines ++(@code{dired-do-kill-lines}). ++ ++@item s ++Toggle between alphabetical order and date/time order ++(@code{dired-sort-toggle-or-edit}). ++ ++@item C-u s @var{switches} @key{RET} ++Refresh the Dired buffer using @var{switches} as ++@code{dired-listing-switches}. ++@end table ++ ++@kindex g @r{(Dired)} ++@findex revert-buffer @r{(Dired)} ++ Type @kbd{g} (@code{revert-buffer}) to update the contents of the ++Dired buffer, based on changes in the files and directories listed. ++This preserves all marks except for those on files that have vanished. ++Hidden subdirectories are updated but remain hidden. ++ ++@kindex l @r{(Dired)} ++@findex dired-do-redisplay ++ To update only some of the files, type @kbd{l} ++(@code{dired-do-redisplay}). Like the Dired file-operating commands, ++this command operates on the next @var{n} files (or previous ++@minus{}@var{n} files), or on the marked files if any, or on the ++current file. Updating the files means reading their current status, ++then updating their lines in the buffer to indicate that status. ++ ++ If you use @kbd{l} on a subdirectory header line, it updates the ++contents of the corresponding subdirectory. ++ ++@kindex k @r{(Dired)} ++@findex dired-do-kill-lines ++ To delete the specified @emph{file lines} from the buffer---not ++delete the files---type @kbd{k} (@code{dired-do-kill-lines}). Like ++the file-operating commands, this command operates on the next @var{n} ++files, or on the marked files if any; but it does not operate on the ++current file as a last resort. ++ ++ If you use @kbd{k} with a numeric prefix argument to kill the line ++for a file that is a directory, which you have inserted in the Dired ++buffer as a subdirectory, it deletes that subdirectory from the buffer ++as well. Typing @kbd{C-u k} on the header line for a subdirectory ++also deletes the subdirectory from the Dired buffer. ++ ++ The @kbd{g} command brings back any individual lines that you have ++killed in this way, but not subdirectories---you must use @kbd{i} to ++reinsert a subdirectory. ++ ++@cindex Dired sorting ++@cindex sorting Dired buffer ++@kindex s @r{(Dired)} ++@findex dired-sort-toggle-or-edit ++ The files in a Dired buffers are normally listed in alphabetical order ++by file names. Alternatively Dired can sort them by date/time. The ++Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches ++between these two sorting modes. The mode line in a Dired buffer ++indicates which way it is currently sorted---by name, or by date. ++ ++ @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for ++@code{dired-listing-switches}. ++ ++@node Dired and Find ++@section Dired and @code{find} ++@cindex @code{find} and Dired ++ ++ You can select a set of files for display in a Dired buffer more ++flexibly by using the @command{find} utility to choose the files. ++ ++@findex find-name-dired ++ To search for files with names matching a wildcard pattern use ++@kbd{M-x find-name-dired}. It reads arguments @var{directory} and ++@var{pattern}, and chooses all the files in @var{directory} or its ++subdirectories whose individual names match @var{pattern}. ++ ++ The files thus chosen are displayed in a Dired buffer, in which the ++ordinary Dired commands are available. ++ ++@findex find-grep-dired ++ If you want to test the contents of files, rather than their names, ++use @kbd{M-x find-grep-dired}. This command reads two minibuffer ++arguments, @var{directory} and @var{regexp}; it chooses all the files ++in @var{directory} or its subdirectories that contain a match for ++@var{regexp}. It works by running the programs @command{find} and ++@command{grep}. See also @kbd{M-x grep-find}, in @ref{Grep ++Searching}. Remember to write the regular expression for ++@command{grep}, not for Emacs. (An alternative method of showing ++files whose contents match a given regexp is the @kbd{% g ++@var{regexp}} command, see @ref{Marks vs Flags}.) ++ ++@findex find-dired ++ The most general command in this series is @kbd{M-x find-dired}, ++which lets you specify any condition that @command{find} can test. It ++takes two minibuffer arguments, @var{directory} and @var{find-args}; ++it runs @command{find} in @var{directory}, passing @var{find-args} to ++tell @command{find} what condition to test. To use this command, you ++need to know how to use @command{find}. ++ ++@vindex find-ls-option ++ The format of listing produced by these commands is controlled by the ++variable @code{find-ls-option}, whose default value specifies using ++options @samp{-ld} for @code{ls}. If your listings are corrupted, you ++may need to change the value of this variable. ++ ++@findex locate ++@findex locate-with-filter ++@cindex file database (locate) ++@vindex locate-command ++ The command @kbd{M-x locate} provides a similar interface to the ++@command{locate} program. @kbd{M-x locate-with-filter} is similar, but ++keeps only files whose names match a given regular expression. ++ ++ These buffers don't work entirely like ordinary Dired buffers: file ++operations work, but do not always automatically update the buffer. ++Reverting the buffer with @kbd{g} deletes all inserted subdirectories, ++and erases all flags and marks. ++ ++@node Wdired ++@section Editing the Dired Buffer ++ ++@cindex wdired mode ++@findex wdired-change-to-wdired-mode ++ Wdired is a special mode that allows you to perform file operations ++by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands ++for ``writable.'') To enter Wdired mode, type @kbd{C-x C-q} ++(@code{dired-toggle-read-only}) while in a Dired buffer. ++Alternatively, use the @samp{Immediate / Edit File Names} menu item. ++ ++@findex wdired-finish-edit ++ While in Wdired mode, you can rename files by editing the file names ++displayed in the Dired buffer. All the ordinary Emacs editing ++commands, including rectangle operations and @code{query-replace}, are ++available for this. Once you are done editing, type @kbd{C-c C-c} ++(@code{wdired-finish-edit}). This applies your changes and switches ++back to ordinary Dired mode. ++ ++ Apart from simply renaming files, you can move a file to another ++directory by typing in the new file name (either absolute or ++relative). To mark a file for deletion, delete the entire file name. ++To change the target of a symbolic link, edit the link target name ++which appears next to the link name. ++ ++ The rest of the text in the buffer, such as the file sizes and ++modification dates, is marked read-only, so you can't edit it. ++However, if you set @code{wdired-allow-to-change-permissions} to ++@code{t}, you can edit the file permissions. For example, you can ++change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file ++world-writable. These changes also take effect when you type @kbd{C-c ++C-c}. ++ ++@node Image-Dired ++@section Viewing Image Thumbnails in Dired ++@cindex image-dired mode ++@cindex image-dired ++ ++ Image-Dired is a facility for browsing image files. It provides viewing ++the images either as thumbnails or in full size, either inside Emacs ++or through an external viewer. ++ ++@kindex C-t d @r{(Image-Dired)} ++@findex image-dired-display-thumbs ++ To enter Image-Dired, mark the image files you want to look at in ++the Dired buffer, using @kbd{m} as usual. Then type @kbd{C-t d} ++(@code{image-dired-display-thumbs}). This creates and switches to a ++buffer containing image-dired, corresponding to the marked files. ++ ++ You can also enter Image-Dired directly by typing @kbd{M-x ++image-dired}. This prompts for a directory; specify one that has ++image files. This creates thumbnails for all the images in that ++directory, and displays them all in the ``thumbnail buffer.'' This ++takes a long time if the directory contains many image files, and it ++asks for confirmation if the number of image files exceeds ++@code{image-dired-show-all-from-dir-max-files}. ++ ++ With point in the thumbnail buffer, you can type @kbd{RET} ++(@code{image-dired-display-thumbnail-original-image}) to display a ++sized version of it in another window. This sizes the image to fit ++the window. Use the arrow keys to move around in the buffer. For ++easy browsing, use @kbd{SPC} ++(@code{image-dired-display-next-thumbnail-original}) to advance and ++display the next image. Typing @kbd{DEL} ++(@code{image-dired-display-previous-thumbnail-original}) backs up to ++the previous thumbnail and displays that instead. ++ ++@vindex image-dired-external-viewer ++ To view and the image in its original size, either provide a prefix ++argument (@kbd{C-u}) before pressing @kbd{RET}, or type ++@kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to ++display the image in an external viewer. You must first configure ++@code{image-dired-external-viewer}. ++ ++ You can delete images through Image-Dired also. Type @kbd{d} ++(@code{image-dired-flag-thumb-original-file}) to flag the image file ++for deletion in the Dired buffer. You can also delete the thumbnail ++image from the thumbnail buffer with @kbd{C-d} ++(@code{image-dired-delete-char}). ++ ++ More advanced features include @dfn{image tags}, which are metadata ++used to categorize image files. The tags are stored in a plain text ++file configured by @code{image-dired-db-file}. ++ ++ To tag image files, mark them in the dired buffer (you can also mark ++files in Dired from the thumbnail buffer by typing @kbd{m}) and type ++@kbd{C-t t} (@code{image-dired-tag-files}). This reads the tag name ++in the minibuffer. To mark files having a certain tag, type @kbd{C-t f} ++(@code{image-dired-mark-tagged-files}). After marking image files ++with a certain tag, you can use @kbd{C-t d} to view them. ++ ++ You can also tag a file directly from the thumbnail buffer by typing ++@kbd{t t} and you can remove a tag by typing @kbd{t r}. There is also ++a special ``tag'' called ``comment'' for each file (it is not a tag in ++the exact same sense as the other tags, it is handled slightly ++different). That is used to enter a comment or description about the ++image. You comment a file from the thumbnail buffer by typing ++@kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add ++a comment from Dired (@code{image-dired-dired-comment-files}). ++ ++ Image-Dired also provides simple image manipulation. In the ++thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees ++anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This ++rotation is lossless, and uses an external utility called JpegTRAN. ++ ++@node Misc Dired Features ++@section Other Dired Features ++ ++@kindex + @r{(Dired)} ++@findex dired-create-directory ++ The command @kbd{+} (@code{dired-create-directory}) reads a ++directory name, and creates the directory if it does not already ++exist. ++ ++@cindex searching multiple files via Dired ++ The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a ++``multi-file'' incremental search on the marked files. If a search ++fails at the end of a file, typing @kbd{C-s} advances to the next ++marked file and repeats the search; at the end of the last marked ++file, the search wraps around to the first marked file. The command ++@kbd{M-s a M-C-s} (@code{dired-do-isearch-regexp}) does the same with ++a regular expression search. @xref{Repeat Isearch}, for information ++about search repetition. ++ ++@cindex Adding to the kill ring in Dired. ++@kindex w @r{(Dired)} ++@findex dired-copy-filename-as-kill ++ The command @kbd{w} (@code{dired-copy-filename-as-kill}) puts the ++names of the marked (or next @var{n}) files into the kill ring, as if ++you had killed them with @kbd{C-w}. The names are separated by a ++space. ++ ++ With a zero prefix argument, this uses the absolute file name of ++each marked file. With just @kbd{C-u} as the prefix argument, it uses ++file names relative to the Dired buffer's default directory. (This ++can still contain slashes if in a subdirectory.) As a special case, ++if point is on a directory headerline, @kbd{w} gives you the absolute ++name of that directory. Any prefix argument or marked files are ++ignored in this case. ++ ++ The main purpose of this command is so that you can yank the file ++names into arguments for other Emacs commands. It also displays what ++it added to the kill ring, so you can use it to display the list of ++currently marked files in the echo area. ++ ++@findex dired-compare-directories ++ The command @kbd{M-x dired-compare-directories} is used to compare ++the current Dired buffer with another directory. It marks all the files ++that are ``different'' between the two directories. It puts these marks ++in all Dired buffers where these files are listed, which of course includes ++the current buffer. ++ ++ The default comparison method (used if you type @key{RET} at the ++prompt) is to compare just the file names---each file name that does ++not appear in the other directory is ``different.'' You can specify ++more stringent comparisons by entering a Lisp expression, which can ++refer to the variables @code{size1} and @code{size2}, the respective ++file sizes; @code{mtime1} and @code{mtime2}, the last modification ++times in seconds, as floating point numbers; and @code{fa1} and ++@code{fa2}, the respective file attribute lists (as returned by the ++function @code{file-attributes}). This expression is evaluated for ++each pair of like-named files, and if the expression's value is ++non-@code{nil}, those files are considered ``different.'' ++ ++ For instance, the sequence @code{M-x dired-compare-directories ++@key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this ++directory than in the other, and marks files older in the other ++directory than in this one. It also marks files with no counterpart, ++in both directories, as always. ++ ++@cindex drag and drop, Dired ++ On the X window system, Emacs supports the ``drag and drop'' ++protocol. You can drag a file object from another program, and drop ++it onto a Dired buffer; this either moves, copies, or creates a link ++to the file in that directory. Precisely which action is taken is ++determined by the originating program. Dragging files out of a Dired ++buffer is currently not supported. ++ ++@ignore ++ arch-tag: d105f9b9-fc1b-4c5f-a949-9b2cf3ca2fc1 ++@end ignore +diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi +new file mode 100644 +index 0000000..56a50bc +--- /dev/null ++++ b/doc/emacs/display.texi +@@ -0,0 +1,1317 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Display, Search, Registers, Top ++@chapter Controlling the Display ++ ++ Since only part of a large buffer fits in the window, Emacs tries to ++show a part that is likely to be interesting. Display-control ++commands and variables allow you to specify which part of the text you ++want to see, and how to display it. ++ ++@menu ++* Scrolling:: Commands to move text up and down in a window. ++* Auto Scrolling:: Redisplay scrolls text automatically when needed. ++* Horizontal Scrolling:: Moving text left and right in a window. ++* Follow Mode:: Follow mode lets two windows scroll as one. ++* Faces:: How to change the display style using faces. ++* Standard Faces:: Emacs' predefined faces. ++* Temporary Face Changes:: Commands to temporarily modify the default text face ++* Font Lock:: Minor mode for syntactic highlighting using faces. ++* Highlight Interactively:: Tell Emacs what text to highlight. ++* Fringes:: Enabling or disabling window fringes. ++* Displaying Boundaries:: Displaying top and bottom of the buffer. ++* Useless Whitespace:: Showing possibly-spurious trailing whitespace. ++* Selective Display:: Hiding lines with lots of indentation. ++* Optional Mode Line:: Optional mode line display features. ++* Text Display:: How text characters are normally displayed. ++* Cursor Display:: Features for displaying the cursor. ++* Line Truncation:: Truncating lines to fit the screen width instead ++ of continuing them to multiple screen lines. ++* Visual Line Mode:: Word wrap and screen line-based editing. ++* Display Custom:: Information on variables for customizing display. ++@end menu ++ ++@node Scrolling ++@section Scrolling ++ ++ If a buffer contains text that is too large to fit entirely within a ++window that is displaying the buffer, Emacs shows a contiguous portion of ++the text. The portion shown always contains point. ++ ++@cindex scrolling ++ @dfn{Scrolling} means moving text up or down in the window so that ++different parts of the text are visible. Scrolling ``forward'' or ++``up'' means that text moves up, and new text appears at the bottom. ++Scrolling ``backward'' or ``down'' moves text down, and new text ++appears at the top. ++ ++ Scrolling happens automatically if you move point past the bottom or ++top of the window. You can also scroll explicitly with these ++commands: ++ ++@table @kbd ++@item C-l ++Scroll the selected window to center point vertically within it and ++redisplay the screen (@code{recenter-top-bottom}). ++@item C-v ++@itemx @key{next} ++@itemx @key{PageDown} ++Scroll forward by nearly a full window (@code{scroll-up}). ++@item M-v ++@itemx @key{prior} ++@itemx @key{PageUp} ++Scroll backward (@code{scroll-down}). ++@item C-M-l ++Scroll heuristically to bring useful information onto the screen ++(@code{reposition-window}). ++@end table ++ ++@kindex C-l ++@findex recenter-top-bottom ++ The most basic scrolling command is @kbd{C-l} ++(@code{recenter-top-bottom}). This @dfn{recenters} the selected ++window, scrolling it so that the current screen line is exactly in the ++center of the window, or as close to the center as possible. It also ++clears the screen and redisplays all windows; this is useful in case ++the screen becomes garbled for any reason (@pxref{Screen Garbled}). ++ ++ Typing @kbd{C-l} twice in a row (@kbd{C-l C-l}) scrolls the window ++so that point is on the topmost screen line. Typing a third @kbd{C-l} ++scrolls the window so that point is on the bottom-most screen line. ++Each successive @kbd{C-l} cycles through these three screen positions. ++(If you change the variable @code{scroll-margin} to a non-zero value ++@var{n}, Emacs leaves @var{n} screen lines between point and the top ++or bottom of the window. @xref{Auto Scrolling}.) ++ ++ You can also supply @kbd{C-l} with a prefix argument. With a plain ++prefix argument, @kbd{C-u C-l}, Emacs simply recenters point. With a ++positive argument @var{n}, it scrolls to place point @var{n} lines ++down from the top of the window. An argument of zero puts point on ++the topmost line. A negative argument @var{-n} puts point @var{n} ++lines from the bottom of the window. For example, @kbd{C-u - 1 C-l} ++puts point on the bottom line, and @kbd{C-u - 5 C-l} puts it five ++lines from the bottom. When given an argument, @kbd{C-l} does not ++clear the screen or cycle through different screen positions. ++ ++@kindex C-v ++@kindex M-v ++@kindex next ++@kindex prior ++@kindex PageDown ++@kindex PageUp ++@findex scroll-up ++@findex scroll-down ++ To read the buffer a windowful at a time, use @kbd{C-v} ++(@code{scroll-up}). This scrolls forward by nearly the whole window ++height. The effect is to take the two lines at the bottom of the ++window and put them at the top, followed by lines that were not ++previously visible. If point was in the text that scrolled off the ++top, it ends up at the new top of the window. ++ ++ @kbd{M-v} (@code{scroll-down}) scrolls backward in a similar way. ++ ++@vindex next-screen-context-lines ++ The variable @code{next-screen-context-lines} controls the number of ++lines of overlap left by @kbd{C-v} or @kbd{M-v}; by default, it is 2. ++The function keys @key{next} and @key{prior}, or @key{PageDown} and ++@key{PageUp}, are equivalent to @kbd{C-v} and @kbd{M-v} respectively. ++ ++ You can supply @kbd{C-v} or @kbd{M-v} with a numeric prefix argument ++@var{n}. This scrolls the window by @var{n} lines, while attempting ++to leave point unchanged (so that the text and point move up or down ++together). @kbd{C-v} with a negative argument is like @kbd{M-v} and ++vice versa. ++ ++ The names of scroll commands are based on the direction that the ++text moves in the window. Thus, the command to scroll forward is ++called @code{scroll-up} because it moves the text upward on the ++screen. The keys @key{PageUp} and @key{PageDown} derive their names ++and customary meanings from a different convention that developed ++elsewhere; hence the strange result that @key{PageDown} runs ++@code{scroll-up}. ++ ++@vindex scroll-preserve-screen-position ++ Some users like the full-screen scroll commands to keep point at the ++same screen position. To enable this behavior, set the variable ++@code{scroll-preserve-screen-position} to a non-@code{nil} value. ++Then, whenever a command scrolls the text around point offscreen (or ++within @code{scroll-margin} lines of the edge), Emacs moves point to ++keep it at the same vertical and horizontal position within the ++window. This mode is convenient for browsing through a file by ++scrolling by screenfuls; if you come back to the screen where you ++started, point goes back to the line where it started. ++ ++@kindex C-M-l ++@findex reposition-window ++ The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current ++window heuristically in a way designed to get useful information onto ++the screen. For example, in a Lisp file, this command tries to get the ++entire current defun onto the screen if possible. ++ ++@node Auto Scrolling ++@section Automatic Scrolling ++ ++ Emacs performs @dfn{automatic scrolling} when point moves out of the ++visible portion of the text. ++ ++@vindex scroll-conservatively ++ Normally, this centers point vertically within the window. However, ++if you set @code{scroll-conservatively} to a small number @var{n}, ++then if you move point just a little off the screen (less than @var{n} ++lines), Emacs scrolls the text just far enough to bring point back on ++screen. By default, @code{scroll-conservatively} is@tie{}0. ++ ++@cindex aggressive scrolling ++@vindex scroll-up-aggressively ++@vindex scroll-down-aggressively ++ When the window does scroll by a longer distance, you can control ++how aggressively it scrolls by setting the variables ++@code{scroll-up-aggressively} and @code{scroll-down-aggressively}. ++The value of @code{scroll-up-aggressively} should be either ++@code{nil}, or a fraction @var{f} between 0 and 1. A fraction ++specifies where on the screen to put point when scrolling upward: when ++a window scrolls up because point is above the window start, the new ++start position is chosen to put point @var{f} parts of the window ++height from the top. Thus, larger @var{f} means more aggressive ++scrolling. The default value, @code{nil}, is equivalent to 0.5. ++ ++ Likewise, @code{scroll-down-aggressively} is used for scrolling ++down. The value specifies how far point should be placed from the ++bottom of the window; thus, as with @code{scroll-up-aggressively}, a ++larger value is more aggressive. ++ ++@vindex scroll-margin ++ The variable @code{scroll-margin} restricts how close point can come ++to the top or bottom of a window. Its value is a number of screen ++lines; if point comes within that many lines of the top or bottom of ++the window, Emacs performs automatic scrolling. By default, ++@code{scroll-margin} is 0. ++ ++@node Horizontal Scrolling ++@section Horizontal Scrolling ++@cindex horizontal scrolling ++ ++@vindex auto-hscroll-mode ++ @dfn{Horizontal scrolling} means shifting all the lines sideways ++within a window, so that some of the text near the left margin is not ++displayed. When the text in a window is scrolled horizontally, text ++lines are truncated rather than continued (@pxref{Line Truncation}). ++If a window shows truncated lines, Emacs performs automatic horizontal ++scrolling whenever point moves off the left or right edge of the ++screen. To disable automatic horizontal scrolling, set the variable ++@code{auto-hscroll-mode} to @code{nil}. ++ ++@vindex hscroll-margin ++ The variable @code{hscroll-margin} controls how close point can get ++to the window's edges before automatic scrolling occurs. It ++is measured in columns. If the value is 5, then moving point within 5 ++columns of an edge causes horizontal scrolling away from that edge. ++ ++@vindex hscroll-step ++ The variable @code{hscroll-step} determines how many columns to ++scroll the window when point gets too close to the edge. Zero, the ++default value, means to center point horizontally within the window. ++A positive integer value specifies the number of columns to scroll by. ++A floating-point number specifies the fraction of the window's width ++to scroll by. ++ ++ You can also perform explicit horizontal scrolling with the ++following commands: ++ ++@table @kbd ++@item C-x < ++Scroll text in current window to the left (@code{scroll-left}). ++@item C-x > ++Scroll to the right (@code{scroll-right}). ++@end table ++ ++@kindex C-x < ++@kindex C-x > ++@findex scroll-left ++@findex scroll-right ++ @kbd{C-x <} (@code{scroll-left}) scrolls the selected window to the ++left by the full width of the window, less two columns. (In other ++words, the text in the window moves left relative to the window.) ++With a numeric argument @var{n}, it scrolls by @var{n} columns. ++ ++ @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. ++The window cannot be scrolled any farther to the right once it is ++displayed normally, with each line starting at the window's left ++margin; attempting to do so has no effect. This means that you don't ++have to calculate the argument precisely for @w{@kbd{C-x >}}; any ++sufficiently large argument will restore the normal display. ++ ++ If you use those commands to scroll a window horizontally, that sets ++a lower bound for automatic horizontal scrolling. Automatic scrolling ++will continue to scroll the window, but never farther to the right ++than the amount you previously set by @code{scroll-left}. ++ ++@node Follow Mode ++@section Follow Mode ++@cindex Follow mode ++@cindex mode, Follow ++@findex follow-mode ++@cindex windows, synchronizing ++@cindex synchronizing windows ++ ++ @dfn{Follow mode} is a minor mode that makes two windows, both ++showing the same buffer, scroll as a single tall ``virtual window.'' ++To use Follow mode, go to a frame with just one window, split it into ++two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x ++follow-mode}. From then on, you can edit the buffer in either of the ++two windows, or scroll either one; the other window follows it. ++ ++ In Follow mode, if you move point outside the portion visible in one ++window and into the portion visible in the other window, that selects ++the other window---again, treating the two as if they were parts of ++one large window. ++ ++ To turn off Follow mode, type @kbd{M-x follow-mode} a second time. ++ ++@node Faces ++@section Faces: Controlling Text Display Style ++@cindex faces ++ ++ Emacs can display text in several different styles, which are called ++@dfn{faces}. Each face can specify various @dfn{face attributes}, ++such as the font, height, weight and slant, the foreground and ++background color, and underlining or overlining. A face does not have ++to specify all of these attributes; often it inherits most of them ++from another face. ++ ++ On a text-only terminal, not all face attributes are meaningful. ++Some text-only terminals support inverse video, bold, and underline ++attributes; some support colors. Text-only terminals generally do not ++support changing the height, width or font. ++ ++ Most major modes assign faces to the text automatically through the ++work of Font Lock mode. @xref{Font Lock}, for more information about ++Font Lock mode and syntactic highlighting. You can print the current ++buffer with the highlighting that appears on your screen using the ++command @code{ps-print-buffer-with-faces}. @xref{PostScript}. ++ ++ Enriched mode, the mode for editing formatted text, provides ++commands and menus for specifying faces for text in the buffer. ++@xref{Format Faces}. ++ ++@cindex face colors, setting ++ To alter the appearance of a face, use the customization buffer. ++@xref{Face Customization}. You can also use X resources to specify ++attributes of any particular face (@pxref{Resources}). When ++displaying a character, any attribute that isn't specified by its face ++is taken from the @code{default} face, whose attributes reflect the ++default settings of the frame itself. ++ ++@findex set-face-foreground ++@findex set-face-background ++ You can also change the foreground and background colors of a ++specific face with @kbd{M-x set-face-foreground} and @kbd{M-x ++set-face-background}. These commands prompt in the minibuffer for a ++face name and a color name, with completion, and then set that face to ++use the specified color. @xref{Face Customization}, for information ++about color names. These commands affect the face colors on all ++frames, both existing and those to be created in the future. These ++changes do not, however, persist for future Emacs sessions; to make ++lasting changes, use the customization buffer (@pxref{Face ++Customization}). ++ ++ You can also set foreground and background colors for the current ++frame only; see @ref{Frame Parameters}. ++ ++ Emacs can display variable-width fonts, but some of the Emacs ++commands that calculate width and indentation do not know how to ++calculate variable widths. This can sometimes lead to incorrect ++results when you use variable-width fonts. In particular, indentation ++commands can give inconsistent results, so we recommend you avoid ++variable-width fonts, especially for editing program source code. ++ ++@node Standard Faces ++@section Standard Faces ++ ++@findex list-faces-display ++ To see what faces are currently defined, and what they look like, ++type @kbd{M-x list-faces-display}. It's possible for a given face to ++look different in different frames; this command shows the appearance ++in the frame in which you type it. With a prefix argument, this ++prompts for a regular expression, and displays only faces with names ++matching that regular expression. ++ ++ Here are the standard faces for specifying text appearance. You can ++apply them to specific text when you want the effects they produce. ++ ++@table @code ++@item default ++This face is used for ordinary text that doesn't specify any face. ++@item bold ++This face uses a bold variant of the default font. ++@item italic ++This face uses an italic variant of the default font. ++@item bold-italic ++This face uses a bold italic variant of the default font. ++@item underline ++This face underlines text. ++@item fixed-pitch ++This face forces use of a fixed-width font. It's reasonable to ++customize this face to use a different fixed-width font, if you like, ++but you should not make it a variable-width font. ++@item variable-pitch ++This face forces use of a variable-width font. ++@item shadow ++This face is used for making the text less noticeable than the surrounding ++ordinary text. Usually this can be achieved by using shades of gray in ++contrast with either black or white default foreground color. ++@end table ++ ++ Here's an incomplete list of faces used to highlight parts of the ++text temporarily for specific purposes. (Many other modes define ++their own faces for this purpose.) ++ ++@table @code ++@item highlight ++This face is used for highlighting portions of text, in various modes. ++For example, mouse-sensitive text is highlighted using this face. ++@item isearch ++This face is used for highlighting the current Isearch match ++(@pxref{Incremental Search}). ++@item query-replace ++This face is used for highlighting the current Query Replace match ++(@pxref{Replace}). ++@item lazy-highlight ++This face is used for lazy highlighting of Isearch and Query Replace ++matches other than the current one. ++@item region ++This face is used for displaying a selected region (@pxref{Mark}). ++@item secondary-selection ++This face is used for displaying a secondary X selection (@pxref{Secondary ++Selection}). ++@item trailing-whitespace ++The face for highlighting excess spaces and tabs at the end of a line ++when @code{show-trailing-whitespace} is non-@code{nil}; see ++@ref{Useless Whitespace}. ++@item nobreak-space ++The face for displaying the character ``nobreak space.'' ++@item escape-glyph ++The face for highlighting the @samp{\} or @samp{^} that indicates ++a control character. It's also used when @samp{\} indicates a ++nobreak space or nobreak (soft) hyphen. ++@end table ++ ++ These faces control the appearance of parts of the Emacs frame. ++They exist as faces to provide a consistent way to customize the ++appearance of these parts of the frame. ++ ++@table @code ++@item mode-line ++This face is used for the mode line of the currently selected window, ++and for menu bars when toolkit menus are not used. By default, it's ++drawn with shadows for a ``raised'' effect on graphical displays, and ++drawn as the inverse of the default face on non-windowed terminals. ++@item mode-line-inactive ++Like @code{mode-line}, but used for mode lines of the windows other ++than the selected one (if @code{mode-line-in-non-selected-windows} is ++non-@code{nil}). This face inherits from @code{mode-line}, so changes ++in that face affect mode lines in all windows. ++@item mode-line-highlight ++Like @code{highlight}, but used for portions of text on mode lines. ++@item mode-line-buffer-id ++This face is used for buffer identification parts in the mode line. ++@item header-line ++Similar to @code{mode-line} for a window's header line, which appears ++at the top of a window just as the mode line appears at the bottom. ++Most windows do not have a header line---only some special modes, such ++Info mode, create one. ++@item vertical-border ++This face is used for the vertical divider between windows. ++By default this face inherits from the @code{mode-line-inactive} face ++on character terminals. On graphical displays the foreground color of ++this face is used for the vertical line between windows without ++scrollbars. ++@item minibuffer-prompt ++@cindex @code{minibuffer-prompt} face ++@vindex minibuffer-prompt-properties ++This face is used for the prompt strings displayed in the minibuffer. ++By default, Emacs automatically adds this face to the value of ++@code{minibuffer-prompt-properties}, which is a list of text ++properties used to display the prompt text. (This variable takes ++effect when you enter the minibuffer.) ++@item fringe ++@cindex @code{fringe} face ++The face for the fringes to the left and right of windows on graphic ++displays. (The fringes are the narrow portions of the Emacs frame ++between the text area and the window's right and left borders.) ++@xref{Fringes}. ++@item scroll-bar ++This face determines the visual appearance of the scroll bar. ++@xref{Scroll Bars}. ++@item border ++This face determines the color of the frame border. ++@item cursor ++This face determines the color of the cursor. ++@item mouse ++This face determines the color of the mouse pointer. ++@item tool-bar ++This face determines the color of tool bar icons. @xref{Tool Bars}. ++@item tooltip ++This face is used for tooltips. @xref{Tooltips}. ++@item menu ++@cindex menu bar appearance ++@cindex @code{menu} face, no effect if customized ++@cindex customization of @code{menu} face ++This face determines the colors and font of Emacs's menus. @xref{Menu ++Bars}. This has no effect in Emacs built with GTK and in the ++MS-Windows/Mac ports; you need to use system-wide styles and options ++to change the appearance of GTK, Windows, or Mac menus. Setting the ++font of LessTif/Motif menus is currently not supported; attempts to ++set the font are ignored in this case. ++@end table ++ ++@node Temporary Face Changes ++@section Temporary Face Changes ++ ++The following commands change the default face within a buffer. ++ ++@cindex adjust buffer face height ++@findex text-scale-adjust ++@kindex C-x C-+ ++@kindex C-x C-- ++@kindex C-x C-= ++@kindex C-x C-0 ++ To increase the height of the default face in the current buffer, ++type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type @kbd{C-x ++C--}. To restore the default (global) face height, type @kbd{C-x ++C-0}. These keys are all bound to the same command, ++@code{text-scale-adjust}, which looks at the last key typed to ++determine which action to take. ++ ++ The final key of these commands may be repeated without the leading ++@kbd{C-x}. For instance, @kbd{C-x C-= C-= C-=} increases the face ++height by three steps. Each step scales the height of the default ++face by the value of the variable @code{text-scale-mode-step}. As a ++special case, an argument of 0 removes any scaling currently active. ++ ++@cindex increase buffer face height ++@findex text-scale-increase ++@cindex decrease buffer face height ++@findex text-scale-decrease ++ The commands @code{text-scale-increase} and ++@code{text-scale-decrease} increase or decrease the height of the ++default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively. ++You may find it convenient to bind to these commands, rather than ++@code{text-scale-adjust}. ++ ++@findex text-scale-mode ++ The above commands automatically enable or disable the minor mode ++@code{text-scale-mode}, depending on whether the current font scaling ++is other than 1 or not. ++ ++@cindex variable pitch mode ++@findex variable-pitch-mode ++ To temporarily change the face in the current buffer to a ++variable-pitch (``proportional'') font, use the command @kbd{M-x ++variable-pitch-mode} to enable or disable the Variable Pitch minor ++mode. ++ ++@node Font Lock ++@section Font Lock mode ++@cindex Font Lock mode ++@cindex mode, Font Lock ++@cindex syntax highlighting and coloring ++ ++ Font Lock mode is a minor mode, always local to a particular buffer, ++which highlights (or ``fontifies'') the buffer contents according to ++the syntax of the text you are editing. It can recognize comments and ++strings in most programming languages; in several languages, it can ++also recognize and properly highlight various other important ++constructs, such as names of functions being defined or reserved ++keywords. Some special modes, such as Occur mode and Info mode, have ++completely specialized ways of assigning fonts for Font Lock mode. ++ ++@findex font-lock-mode ++ Font Lock mode is turned on by default in all modes which support it. ++You can toggle font-lock for each buffer with the command @kbd{M-x ++font-lock-mode}. Using a positive argument unconditionally turns Font ++Lock mode on, and a negative or zero argument turns it off. ++ ++@findex global-font-lock-mode ++@vindex global-font-lock-mode ++ If you do not wish Font Lock mode to be turned on by default, ++customize the variable @code{global-font-lock-mode} using the Customize ++interface (@pxref{Easy Customization}), or use the function ++@code{global-font-lock-mode} in your @file{.emacs} file, like this: ++ ++@example ++(global-font-lock-mode 0) ++@end example ++ ++@noindent ++This variable, like all the variables that control Font Lock mode, ++take effect whenever fontification is done; that is, potentially at ++any time. ++ ++@findex turn-on-font-lock ++ If you have disabled Global Font Lock mode, you can still enable Font ++Lock for specific major modes by adding the function ++@code{turn-on-font-lock} to the mode hooks (@pxref{Hooks}). For ++example, to enable Font Lock mode for editing C files, you can do this: ++ ++@example ++(add-hook 'c-mode-hook 'turn-on-font-lock) ++@end example ++ ++ Font Lock mode uses several specifically named faces to do its job, ++including @code{font-lock-string-face}, @code{font-lock-comment-face}, ++and others. The easiest way to find them all is to use @kbd{M-x ++customize-group @key{RET} font-lock-faces @key{RET}}. You can then ++use that customization buffer to customize the appearance of these ++faces. @xref{Face Customization}. ++ ++@vindex font-lock-maximum-decoration ++ The variable @code{font-lock-maximum-decoration} specifies the ++preferred level of fontification, for modes that provide multiple ++levels. Level 1 is the least amount of fontification; some modes ++support levels as high as 3. The normal default is ``as high as ++possible.'' You can specify an integer, which applies to all modes, or ++you can specify different numbers for particular major modes; for ++example, to use level 1 for C/C++ modes, and the default level ++otherwise, use this: ++ ++@example ++(setq font-lock-maximum-decoration ++ '((c-mode . 1) (c++-mode . 1))) ++@end example ++ ++@vindex font-lock-maximum-size ++ Fontification can be too slow for large buffers, so you can suppress ++it for buffers above a certain size. The variable ++@code{font-lock-maximum-size} specifies a buffer size, beyond which ++buffer fontification is suppressed. ++ ++@c @w is used below to prevent a bad page-break. ++@vindex font-lock-beginning-of-syntax-function ++@cindex incorrect fontification ++@cindex parenthesis in column zero and fontification ++@cindex brace in column zero and fontification ++ Comment and string fontification (or ``syntactic'' fontification) ++relies on analysis of the syntactic structure of the buffer text. For ++the sake of speed, some modes, including Lisp mode, rely on a special ++convention: an open-parenthesis or open-brace in the leftmost column ++always defines the @w{beginning} of a defun, and is thus always ++outside any string or comment. (@xref{Left Margin Paren}.) If you ++don't follow this convention, Font Lock mode can misfontify the text ++that follows an open-parenthesis or open-brace in the leftmost column ++that is inside a string or comment. ++ ++@cindex slow display during scrolling ++ The variable @code{font-lock-beginning-of-syntax-function} (always ++buffer-local) specifies how Font Lock mode can find a position ++guaranteed to be outside any comment or string. In modes which use the ++leftmost column parenthesis convention, the default value of the variable ++is @code{beginning-of-defun}---that tells Font Lock mode to use the ++convention. If you set this variable to @code{nil}, Font Lock no longer ++relies on the convention. This avoids incorrect results, but the price ++is that, in some cases, fontification for a changed text must rescan ++buffer text from the beginning of the buffer. This can considerably ++slow down redisplay while scrolling, particularly if you are close to ++the end of a large buffer. ++ ++@findex font-lock-add-keywords ++ Font Lock highlighting patterns already exist for many modes, but you ++may want to fontify additional patterns. You can use the function ++@code{font-lock-add-keywords}, to add your own highlighting patterns for ++a particular mode. For example, to highlight @samp{FIXME:} words in C ++comments, use this: ++ ++@example ++(add-hook 'c-mode-hook ++ (lambda () ++ (font-lock-add-keywords nil ++ '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t))))) ++@end example ++ ++@findex font-lock-remove-keywords ++ To remove keywords from the font-lock highlighting patterns, use the ++function @code{font-lock-remove-keywords}. @xref{Search-based ++Fontification,,, elisp, The Emacs Lisp Reference Manual}. ++ ++@cindex just-in-time (JIT) font-lock ++@cindex background syntax highlighting ++ Fontifying large buffers can take a long time. To avoid large ++delays when a file is visited, Emacs fontifies only the visible ++portion of a buffer. As you scroll through the buffer, each portion ++that becomes visible is fontified as soon as it is displayed; this ++type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT}) Lock. ++You can control how JIT Lock behaves, including telling it to perform ++fontification while idle, by customizing variables in the ++customization group @samp{jit-lock}. @xref{Specific Customization}. ++ ++@node Highlight Interactively ++@section Interactive Highlighting ++@cindex highlighting by matching ++@cindex interactive highlighting ++@cindex Highlight Changes mode ++ ++@findex highlight-changes-mode ++Highlight Changes mode is a minor mode that @dfn{highlights} the parts ++of the buffer were changed most recently, by giving that text a ++different face. To enable or disable Highlight Changes mode, use ++@kbd{M-x highlight-changes-mode}. ++ ++@cindex Hi Lock mode ++@findex hi-lock-mode ++ Hi Lock mode is a minor mode that highlights text that matches ++regular expressions you specify. For example, you can use it to ++highlight all the references to a certain variable in a program source ++file, highlight certain parts in a voluminous output of some program, ++or highlight certain names in an article. To enable or disable Hi ++Lock mode, use the command @kbd{M-x hi-lock-mode}. To enable Hi Lock ++mode for all buffers, use @kbd{M-x global-hi-lock-mode} or place ++@code{(global-hi-lock-mode 1)} in your @file{.emacs} file. ++ ++ Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except ++that you specify explicitly the regular expressions to highlight. You ++control them with these commands: ++ ++@table @kbd ++@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET} ++@kindex C-x w h ++@findex highlight-regexp ++Highlight text that matches @var{regexp} using face @var{face} ++(@code{highlight-regexp}). The highlighting will remain as long as ++the buffer is loaded. For example, to highlight all occurrences of ++the word ``whim'' using the default face (a yellow background) ++@kbd{C-x w h whim @key{RET} @key{RET}}. Any face can be used for ++highlighting, Hi Lock provides several of its own and these are ++pre-loaded into a history list. While being prompted for a face use ++@kbd{M-p} and @kbd{M-n} to cycle through them. ++ ++You can use this command multiple times, specifying various regular ++expressions to highlight in different ways. ++ ++@item C-x w r @var{regexp} @key{RET} ++@kindex C-x w r ++@findex unhighlight-regexp ++Unhighlight @var{regexp} (@code{unhighlight-regexp}). ++ ++If you invoke this from the menu, you select the expression to ++unhighlight from a list. If you invoke this from the keyboard, you ++use the minibuffer. It will show the most recently added regular ++expression; use @kbd{M-p} to show the next older expression and ++@kbd{M-n} to select the next newer expression. (You can also type the ++expression by hand, with completion.) When the expression you want to ++unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit ++the minibuffer and unhighlight it. ++ ++@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET} ++@kindex C-x w l ++@findex highlight-lines-matching-regexp ++@cindex lines, highlighting ++@cindex highlighting lines of text ++Highlight entire lines containing a match for @var{regexp}, using face ++@var{face} (@code{highlight-lines-matching-regexp}). ++ ++@item C-x w b ++@kindex C-x w b ++@findex hi-lock-write-interactive-patterns ++Insert all the current highlighting regexp/face pairs into the buffer ++at point, with comment delimiters to prevent them from changing your ++program. (This key binding runs the ++@code{hi-lock-write-interactive-patterns} command.) ++ ++These patterns are extracted from the comments, if appropriate, if you ++invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while ++Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}). ++ ++@item C-x w i ++@kindex C-x w i ++@findex hi-lock-find-patterns ++Extract regexp/face pairs from comments in the current buffer ++(@code{hi-lock-find-patterns}). Thus, you can enter patterns ++interactively with @code{highlight-regexp}, store them into the file ++with @code{hi-lock-write-interactive-patterns}, edit them (perhaps ++including different faces for different parenthesized parts of the ++match), and finally use this command (@code{hi-lock-find-patterns}) to ++have Hi Lock highlight the edited patterns. ++ ++@vindex hi-lock-file-patterns-policy ++The variable @code{hi-lock-file-patterns-policy} controls whether Hi ++Lock mode should automatically extract and highlight patterns found in ++a file when it is visited. Its value can be @code{nil} (never ++highlight), @code{t} (highlight the patterns), @code{ask} (query the ++user), or a function. If it is a function, ++@code{hi-lock-find-patterns} calls it with the patterns as argument; ++if the function returns non-@code{nil}, the patterns are used. The ++default is @code{nil}. Note that patterns are always highlighted if ++you call @code{hi-lock-find-patterns} directly, regardless of the ++value of this variable. ++ ++@vindex hi-lock-exclude-modes ++Also, @code{hi-lock-find-patterns} does nothing if the current major ++mode's symbol is a member of the list @code{hi-lock-exclude-modes}. ++@end table ++ ++@node Fringes ++@section Window Fringes ++@cindex fringes ++ ++ On a graphical display, each Emacs window normally has narrow ++@dfn{fringes} on the left and right edges. The fringes are used to ++display symbols that provide information about the text in the window. ++ ++ The most common use of the fringes is to indicate a continuation ++line, when one line of text is split into multiple lines on the ++screen. The left fringe shows a curving arrow for each screen line ++except the first, indicating that ``this is not the real beginning.'' ++The right fringe shows a curving arrow for each screen line except the ++last, indicating that ``this is not the real end.'' ++ ++ The fringes indicate line truncation with short horizontal arrows ++meaning ``there's more text on this line which is scrolled ++horizontally out of view;'' clicking the mouse on one of the arrows ++scrolls the display horizontally in the direction of the arrow. The ++fringes can also indicate other things, such as empty lines, or where a ++program you are debugging is executing (@pxref{Debuggers}). ++ ++@findex set-fringe-style ++@findex fringe-mode ++ You can enable and disable the fringes for all frames using ++@kbd{M-x fringe-mode}. To enable and disable the fringes ++for the selected frame, use @kbd{M-x set-fringe-style}. ++ ++@node Displaying Boundaries ++@section Displaying Boundaries ++ ++@vindex indicate-buffer-boundaries ++ On a graphical display, Emacs can indicate the buffer boundaries in ++the fringes. It indicates the first line and the last line with ++angle images in the fringes. This can be combined with up and down ++arrow images which say whether it is possible to scroll the window up ++and down. ++ ++ The buffer-local variable @code{indicate-buffer-boundaries} controls ++how the buffer boundaries and window scrolling is indicated in the ++fringes. If the value is @code{left} or @code{right}, both angle and ++arrow bitmaps are displayed in the left or right fringe, respectively. ++ ++ If value is an alist, each element @code{(@var{indicator} . ++@var{position})} specifies the position of one of the indicators. ++The @var{indicator} must be one of @code{top}, @code{bottom}, ++@code{up}, @code{down}, or @code{t} which specifies the default ++position for the indicators not present in the alist. ++The @var{position} is one of @code{left}, @code{right}, or @code{nil} ++which specifies not to show this indicator. ++ ++ For example, @code{((top . left) (t . right))} places the top angle ++bitmap in left fringe, the bottom angle bitmap in right fringe, and ++both arrow bitmaps in right fringe. To show just the angle bitmaps in ++the left fringe, but no arrow bitmaps, use @code{((top . left) ++(bottom . left))}. ++ ++@vindex default-indicate-buffer-boundaries ++ The value of the variable @code{default-indicate-buffer-boundaries} ++is the default value for @code{indicate-buffer-boundaries} in buffers ++that do not override it. ++ ++@node Useless Whitespace ++@section Useless Whitespace ++ ++@cindex trailing whitespace ++@cindex whitespace, trailing ++@vindex show-trailing-whitespace ++ It is easy to leave unnecessary spaces at the end of a line, or ++empty lines at the end of a file, without realizing it. In most ++cases, this @dfn{trailing whitespace} has no effect, but there are ++special circumstances where it matters, and it can be a nuisance. ++ ++ You can make trailing whitespace at the end of a line visible by ++setting the buffer-local variable @code{show-trailing-whitespace} to ++@code{t}. Then Emacs displays trailing whitespace, using the face ++@code{trailing-whitespace}. ++ ++ This feature does not apply when point is at the end of the line ++containing the whitespace. Strictly speaking, that is ``trailing ++whitespace'' nonetheless, but displaying it specially in that case ++looks ugly while you are typing in new text. In this special case, ++the location of point is enough to show you that the spaces are ++present. ++ ++@findex delete-trailing-whitespace ++ To delete all trailing whitespace within the buffer's accessible ++portion (@pxref{Narrowing}), type @kbd{M-x delete-trailing-whitespace ++@key{RET}}. This command does not remove newline characters. ++ ++@vindex indicate-empty-lines ++@vindex default-indicate-empty-lines ++@cindex unused lines ++@cindex fringes, and unused line indication ++ Emacs can indicate unused lines at the end of the window with a ++small image in the left fringe (@pxref{Fringes}). The image appears ++for window lines that do not correspond to any buffer text. Blank ++lines at the end of the buffer then stand out because they do not have ++this image in the fringe. ++ ++ To enable this feature, set the buffer-local variable ++@code{indicate-empty-lines} to a non-@code{nil} value. The default ++value of this variable is controlled by the variable ++@code{default-indicate-empty-lines}; by setting that variable, you ++can enable or disable this feature for all new buffers. (This feature ++currently doesn't work on text-only terminals.) ++ ++@node Selective Display ++@section Selective Display ++@cindex selective display ++@findex set-selective-display ++@kindex C-x $ ++ ++ Emacs has the ability to hide lines indented more than a given ++number of columns. You can use this to get an overview of a part of a ++program. ++ ++ To hide lines in the current buffer, type @kbd{C-x $} ++(@code{set-selective-display}) with a numeric argument @var{n}. Then ++lines with at least @var{n} columns of indentation disappear from the ++screen. The only indication of their presence is that three dots ++(@samp{@dots{}}) appear at the end of each visible line that is ++followed by one or more hidden ones. ++ ++ The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as ++if they were not there. ++ ++ The hidden lines are still present in the buffer, and most editing ++commands see them as usual, so you may find point in the middle of the ++hidden text. When this happens, the cursor appears at the end of the ++previous line, after the three dots. If point is at the end of the ++visible line, before the newline that ends it, the cursor appears before ++the three dots. ++ ++ To make all lines visible again, type @kbd{C-x $} with no argument. ++ ++@vindex selective-display-ellipses ++ If you set the variable @code{selective-display-ellipses} to ++@code{nil}, the three dots do not appear at the end of a line that ++precedes hidden lines. Then there is no visible indication of the ++hidden lines. This variable becomes local automatically when set. ++ ++ See also @ref{Outline Mode} for another way to hide part of ++the text in a buffer. ++ ++@node Optional Mode Line ++@section Optional Mode Line Features ++ ++@cindex buffer size display ++@cindex display of buffer size ++@findex size-indication-mode ++ The buffer percentage @var{pos} indicates the percentage of the ++buffer above the top of the window. You can additionally display the ++size of the buffer by typing @kbd{M-x size-indication-mode} to turn on ++Size Indication mode. The size will be displayed immediately ++following the buffer percentage like this: ++ ++@example ++@var{POS} of @var{SIZE} ++@end example ++ ++@noindent ++Here @var{SIZE} is the human readable representation of the number of ++characters in the buffer, which means that @samp{k} for 10^3, @samp{M} ++for 10^6, @samp{G} for 10^9, etc., are used to abbreviate. ++ ++@cindex line number display ++@cindex display of line number ++@findex line-number-mode ++ The current line number of point appears in the mode line when Line ++Number mode is enabled. Use the command @kbd{M-x line-number-mode} to ++turn this mode on and off; normally it is on. The line number appears ++after the buffer percentage @var{pos}, with the letter @samp{L} to ++indicate what it is. ++ ++@cindex Column Number mode ++@cindex mode, Column Number ++@findex column-number-mode ++ Similarly, you can display the current column number by turning on ++Column number mode with @kbd{M-x column-number-mode}. The column ++number is indicated by the letter @samp{C}. However, when both of ++these modes are enabled, the line and column numbers are displayed in ++parentheses, the line number first, rather than with @samp{L} and ++@samp{C}. For example: @samp{(561,2)}. @xref{Minor Modes}, for more ++information about minor modes and about how to use these commands. ++ ++@cindex narrowing, and line number display ++ If you have narrowed the buffer (@pxref{Narrowing}), the displayed ++line number is relative to the accessible portion of the buffer. ++Thus, it isn't suitable as an argument to @code{goto-line}. (Use ++@code{what-line} command to see the line number relative to the whole ++file.) ++ ++@vindex line-number-display-limit ++ If the buffer is very large (larger than the value of ++@code{line-number-display-limit}), Emacs won't compute the line ++number, because that would be too slow; therefore, the line number ++won't appear on the mode-line. To remove this limit, set ++@code{line-number-display-limit} to @code{nil}. ++ ++@vindex line-number-display-limit-width ++ Line-number computation can also be slow if the lines in the buffer ++are too long. For this reason, Emacs doesn't display line numbers if ++the average width, in characters, of lines near point is larger than ++the value of @code{line-number-display-limit-width}. The default ++value is 200 characters. ++ ++@findex display-time ++@cindex time (on mode line) ++ Emacs can optionally display the time and system load in all mode ++lines. To enable this feature, type @kbd{M-x display-time} or customize ++the option @code{display-time-mode}. The information added to the mode ++line usually appears after the buffer name, before the mode names and ++their parentheses. It looks like this: ++ ++@example ++@var{hh}:@var{mm}pm @var{l.ll} ++@end example ++ ++@noindent ++@vindex display-time-24hr-format ++Here @var{hh} and @var{mm} are the hour and minute, followed always by ++@samp{am} or @samp{pm}. @var{l.ll} is the average number of running ++processes in the whole system recently. (Some fields may be missing if ++your operating system cannot support them.) If you prefer time display ++in 24-hour format, set the variable @code{display-time-24hr-format} ++to @code{t}. ++ ++@cindex mail (on mode line) ++@vindex display-time-use-mail-icon ++@vindex display-time-mail-face ++@vindex display-time-mail-file ++@vindex display-time-mail-directory ++ The word @samp{Mail} appears after the load level if there is mail ++for you that you have not read yet. On a graphical display you can use ++an icon instead of @samp{Mail} by customizing ++@code{display-time-use-mail-icon}; this may save some space on the mode ++line. You can customize @code{display-time-mail-face} to make the mail ++indicator prominent. Use @code{display-time-mail-file} to specify ++the mail file to check, or set @code{display-time-mail-directory} ++to specify the directory to check for incoming mail (any nonempty regular ++file in the directory is considered as ``newly arrived mail''). ++ ++@cindex mail (on mode line) ++@findex display-battery-mode ++@vindex display-battery-mode ++@vindex battery-mode-line-format ++ When running Emacs on a laptop computer, you can display the battery ++charge on the mode-line, by using the command ++@code{display-battery-mode} or customizing the variable ++@code{display-battery-mode}. The variable ++@code{battery-mode-line-format} determines the way the battery charge ++is displayed; the exact mode-line message depends on the operating ++system, and it usually shows the current battery charge as a ++percentage of the total charge. ++ ++@cindex mode line, 3D appearance ++@cindex attributes of mode line, changing ++@cindex non-integral number of lines in a window ++ By default, the mode line is drawn on graphics displays with ++3D-style highlighting, like that of a button when it is not being ++pressed. If you don't like this effect, you can disable the 3D ++highlighting of the mode line, by customizing the attributes of the ++@code{mode-line} face. @xref{Face Customization}. ++ ++@cindex non-selected windows, mode line appearance ++ By default, the mode line of nonselected windows is displayed in a ++different face, called @code{mode-line-inactive}. Only the selected ++window is displayed in the @code{mode-line} face. This helps show ++which window is selected. When the minibuffer is selected, since ++it has no mode line, the window from which you activated the minibuffer ++has its mode line displayed using @code{mode-line}; as a result, ++ordinary entry to the minibuffer does not change any mode lines. ++ ++@vindex mode-line-in-non-selected-windows ++ You can disable use of @code{mode-line-inactive} by setting variable ++@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode ++lines are displayed in the @code{mode-line} face. ++ ++@vindex eol-mnemonic-unix ++@vindex eol-mnemonic-dos ++@vindex eol-mnemonic-mac ++@vindex eol-mnemonic-undecided ++ You can customize the mode line display for each of the end-of-line ++formats by setting each of the variables @code{eol-mnemonic-unix}, ++@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and ++@code{eol-mnemonic-undecided} to the strings you prefer. ++ ++@node Text Display ++@section How Text Is Displayed ++@cindex characters (in text) ++ ++ @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs ++buffers are displayed with their graphics, as are non-@acronym{ASCII} multibyte ++printing characters (octal codes above 0400). ++ ++@vindex tab-width ++@vindex default-tab-width ++ Some @acronym{ASCII} control characters are displayed in special ++ways. The newline character (octal code 012) is displayed by starting ++a new line. The tab character (octal code 011) is displayed by moving ++to the next tab stop column (normally every 8 columns). The number of ++spaces per tab is controlled by the variable @code{tab-width}, which ++must have an integer value between 1 and 1000, inclusive, and is made ++local by changing it. Note that how the tab character in the buffer ++is displayed has nothing to do with the definition of @key{TAB} as a ++command. The variable @code{default-tab-width} controls the default ++value of this variable for buffers where you have not set it locally. ++ ++ Other @acronym{ASCII} control characters are normally displayed as a caret ++(@samp{^}) followed by the non-control version of the character; thus, ++control-A is displayed as @samp{^A}. The caret appears in face ++@code{escape-glyph}. ++ ++ Non-@acronym{ASCII} characters 0200 through 0237 (octal) are ++displayed with octal escape sequences; thus, character code 0230 ++(octal) is displayed as @samp{\230}. The backslash appears in face ++@code{escape-glyph}. ++ ++@vindex ctl-arrow ++ If the variable @code{ctl-arrow} is @code{nil}, control characters in ++the buffer are displayed with octal escape sequences, except for newline ++and tab. Altering the value of @code{ctl-arrow} makes it local to the ++current buffer; until that time, the default value is in effect. The ++default is initially @code{t}. ++ ++ The display of character codes 0240 through 0377 (octal) may be ++either as escape sequences or as graphics. They do not normally occur ++in multibyte buffers, but if they do, they are displayed as Latin-1 ++graphics. In unibyte mode, if you enable European display they are ++displayed using their graphics (assuming your terminal supports them), ++otherwise as escape sequences. @xref{Unibyte Mode}. ++ ++@vindex nobreak-char-display ++@cindex no-break space, display ++@cindex no-break hyphen, display ++@cindex soft hyphen, display ++ Some character sets define ``no-break'' versions of the space and ++hyphen characters, which are used where a line should not be broken. ++Emacs normally displays these characters with special faces ++(respectively, @code{nobreak-space} and @code{escape-glyph}) to ++distinguish them from ordinary spaces and hyphens. You can turn off ++this feature by setting the variable @code{nobreak-char-display} to ++@code{nil}. If you set the variable to any other value, that means to ++prefix these characters with an escape character. ++ ++ You can customize the way any particular character code is displayed ++by means of a display table. @xref{Display Tables,, Display Tables, ++elisp, The Emacs Lisp Reference Manual}. ++ ++@node Cursor Display ++@section Displaying the Cursor ++ ++@findex blink-cursor-mode ++@vindex blink-cursor-alist ++@cindex cursor, locating visually ++@cindex cursor, blinking ++ You can customize the cursor's color, and whether it blinks, using ++the @code{cursor} Custom group (@pxref{Easy Customization}). On ++a graphical display, the command @kbd{M-x blink-cursor-mode} enables ++or disables the blinking of the cursor. (On text terminals, the ++terminal itself blinks the cursor, and Emacs has no control over it.) ++You can control how the cursor appears when it blinks off by setting ++the variable @code{blink-cursor-alist}. ++ ++@vindex visible-cursor ++ Some text terminals offer two different cursors: the normal cursor ++and the very visible cursor, where the latter may be e.g. bigger or ++blinking. By default Emacs uses the very visible cursor, and switches ++to it when you start or resume Emacs. If the variable ++@code{visible-cursor} is @code{nil} when Emacs starts or resumes, it ++doesn't switch, so it uses the normal cursor. ++ ++@cindex cursor in non-selected windows ++@vindex cursor-in-non-selected-windows ++ Normally, the cursor appears in non-selected windows without ++blinking, with the same appearance as when the blinking cursor blinks ++``off.'' For a box cursor, this is a hollow box; for a bar cursor, ++this is a thinner bar. To turn off cursors in non-selected windows, ++customize the variable @code{cursor-in-non-selected-windows} and ++assign it a @code{nil} value. ++ ++@vindex x-stretch-cursor ++@cindex wide block cursor ++ On graphical displays, Emacs can optionally draw the block cursor ++as wide as the character under the cursor---for example, if the cursor ++is on a tab character, it would cover the full width occupied by that ++tab character. To enable this feature, set the variable ++@code{x-stretch-cursor} to a non-@code{nil} value. ++ ++@findex hl-line-mode ++@findex global-hl-line-mode ++@cindex highlight current line ++ To make the cursor even more visible, you can use HL Line mode, a ++minor mode that highlights the line containing point. Use @kbd{M-x ++hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x ++global-hl-line-mode} enables or disables the same mode globally. ++ ++@node Line Truncation ++@section Truncation of Lines ++ ++@cindex truncation ++@cindex line truncation, and fringes ++ As an alternative to continuation (@pxref{Continuation Lines}), Emacs ++can display long lines by @dfn{truncation}. This means that all the ++characters that do not fit in the width of the screen or window do not ++appear at all. On graphical displays, a small straight arrow in the ++fringe indicates truncation at either end of the line. On text-only ++terminals, @samp{$} appears in the first column when there is text ++truncated to the left, and in the last column when there is text ++truncated to the right. ++ ++@vindex truncate-lines ++@findex toggle-truncate-lines ++ Horizontal scrolling automatically causes line truncation ++(@pxref{Horizontal Scrolling}). You can explicitly enable line ++truncation for a particular buffer with the command @kbd{M-x ++toggle-truncate-lines}. This works by locally changing the variable ++@code{truncate-lines}. If that variable is non-@code{nil}, long lines ++are truncated; if it is @code{nil}, they are continued onto multiple ++screen lines. Setting the variable @code{truncate-lines} in any way ++makes it local to the current buffer; until that time, the default ++value is in effect. The default value is normally @code{nil}. ++ ++@c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows. ++ If the variable @code{truncate-partial-width-windows} is ++non-@code{nil}, it forces truncation rather than continuation in any ++window less than the full width of the screen or frame, regardless of ++the value of @code{truncate-lines}. See also @ref{Display,, Display, ++elisp, The Emacs Lisp Reference Manual}. ++ ++@vindex overflow-newline-into-fringe ++ If the variable @code{overflow-newline-into-fringe} is ++non-@code{nil} on a graphical display, then Emacs does not continue or ++truncate a line which is exactly as wide as the window. Instead, the ++newline overflows into the right fringe, and the cursor appears in the ++fringe when positioned on that newline. ++ ++@node Visual Line Mode ++@section Visual Line Mode ++ ++@cindex word wrap ++ Another alternative to ordinary line continuation is to use ++@dfn{word wrap}. Here, each long logical line is divided into two or ++more screen lines, like in ordinary line continuation. However, Emacs ++attempts to wrap the line at word boundaries near the right window ++edge. This makes the text easier to read, as wrapping does not occur ++in the middle of words. ++ ++@cindex Visual Line mode ++@findex visual-line-mode ++@findex global-visual-line-mode ++ Word wrap is enabled by Visual Line mode, an optional minor mode. ++To turn on Visual Line mode in the current buffer, type @kbd{M-x ++visual-line-mode}; repeating this command turns it off. You can also ++turn on Visual Line mode using the menu bar: in the Options menu, ++select the @samp{Line Wrapping in this Buffer} submenu, followed by ++the @samp{Word Wrap (Visual Line Mode)} menu item. While Visual Line ++mode is enabled, the mode-line shows the string @samp{wrap} in the ++mode display. The command @kbd{M-x global-visual-line-mode} toggles ++Visual Line mode in all buffers. ++ ++@findex beginning-of-visual-line ++@findex end-of-visual-line ++@findex next-logical-line ++@findex previous-logical-line ++ In Visual Line mode, some editing commands work on screen lines ++instead of logical lines: @kbd{C-a} (@code{beginning-of-visual-line}) ++moves to the beginning of the screen line, @kbd{C-e} ++(@code{end-of-visual-line}) moves to the end of the screen line, and ++@kbd{C-k} (@code{kill-visual-line}) kills text to the end of the ++screen line. ++ ++ To move by logical lines, use the commands @kbd{M-x ++next-logical-line} and @kbd{M-x previous-logical-line}. These move ++point to the next logical line and the previous logical line ++respectively, regardless of whether Visual Line mode is enabled. If ++you use these commands frequently, it may be convenient to assign key ++bindings to them. @xref{Init Rebinding}. ++ ++ By default, word-wrapped lines do not display fringe indicators. ++Visual Line mode is often used to edit files that contain many long ++logical lines, so having a fringe indicator for each wrapped line ++would be visually distracting. You can change this by customizing the ++variable @code{visual-line-fringe-indicators}. ++ ++@node Display Custom ++@section Customization of Display ++ ++ This section describes variables (@pxref{Variables}) that you can ++change to customize how Emacs displays. Beginning users can skip ++it. ++@c the reason for that pxref is because an xref early in the ++@c ``echo area'' section leads here. ++ ++@vindex inverse-video ++ If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts ++to invert all the lines of the display from what they normally are. ++ ++@vindex visible-bell ++ If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts ++to make the whole screen blink when it would normally make an audible bell ++sound. This variable has no effect if your terminal does not have a way ++to make the screen blink. ++ ++@vindex echo-keystrokes ++ The variable @code{echo-keystrokes} controls the echoing of multi-character ++keys; its value is the number of seconds of pause required to cause echoing ++to start, or zero, meaning don't echo at all. The value takes effect when ++there is someting to echo. @xref{Echo Area}. ++ ++@vindex baud-rate ++ The variable @anchor{baud-rate}@code{baud-rate} holds the output ++speed of the terminal, as far as Emacs knows. Setting this variable ++does not change the speed of actual data transmission, but the value ++is used for calculations. On text-only terminals, it affects padding, ++and decisions about whether to scroll part of the screen or redraw it ++instead. It also affects the behavior of incremental search. ++ ++ On graphical displays, @code{baud-rate} is only used to determine ++how frequently to look for pending input during display updating. A ++higher value of @code{baud-rate} means that check for pending input ++will be done less frequently. ++ ++@cindex hourglass pointer display ++@vindex hourglass-delay ++ On graphical displays, Emacs can optionally display the mouse pointer ++in a special shape to say that Emacs is busy. To turn this feature on ++or off, customize the group @code{cursor}. You can also control the ++amount of time Emacs must remain busy before the busy indicator is ++displayed, by setting the variable @code{hourglass-delay}. ++ ++@vindex overline-margin ++ On graphical displays, the variable @code{overline-margin} specifies ++the vertical position of an overline above the text, including the ++height of the overline itself, in pixels. The default value is 2. ++ ++@vindex x-underline-at-descent-line ++ On graphical displays, Emacs normally draws an underline at the ++baseline level of the font. If @code{x-underline-at-descent-line} is ++non-@code{nil}, Emacs draws the underline at the same height as the ++font's descent line. ++ ++@findex tty-suppress-bold-inverse-default-colors ++ On some text-only terminals, bold face and inverse video together ++result in text that is hard to read. Call the function ++@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil} ++argument to suppress the effect of bold-face in this case. ++ ++@vindex no-redraw-on-reenter ++ On a text-only terminal, when you reenter Emacs after suspending, Emacs ++normally clears the screen and redraws the entire display. On some ++terminals with more than one page of memory, it is possible to arrange ++the termcap entry so that the @samp{ti} and @samp{te} strings (output ++to the terminal when Emacs is entered and exited, respectively) switch ++between pages of memory so as to use one page for Emacs and another ++page for other output. On such terminals, you might want to set the variable ++@code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to ++assume, when resumed, that the screen page it is using still contains ++what Emacs last wrote there. ++ ++@ignore ++ arch-tag: 2219f910-2ff0-4521-b059-1bd231a536c4 ++@end ignore +diff --git a/doc/emacs/doclicense.texi b/doc/emacs/doclicense.texi +new file mode 100644 +index 0000000..6e9f5a1 +--- /dev/null ++++ b/doc/emacs/doclicense.texi +@@ -0,0 +1,512 @@ ++@c -*-texinfo-*- ++@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, 2009 Free Software Foundation, Inc. ++@uref{http://fsf.org/} ++ ++Everyone is permitted to copy and distribute verbatim copies ++of this license document, but changing it is not allowed. ++@end display ++ ++@enumerate 0 ++@item ++PREAMBLE ++ ++The purpose of this License is to make a manual, textbook, or other ++functional and useful document @dfn{free} in the sense of freedom: to ++assure everyone the effective freedom to copy and redistribute it, ++with or without modifying it, either commercially or noncommercially. ++Secondarily, this License preserves for the author and publisher a way ++to get credit for their work, while not being considered responsible ++for modifications made by others. ++ ++This License is a kind of ``copyleft'', which means that derivative ++works of the document must themselves be free in the same sense. It ++complements the GNU General Public License, which is a copyleft ++license designed for free software. ++ ++We have designed this License in order to use it for manuals for free ++software, because free software needs free documentation: a free ++program should come with manuals providing the same freedoms that the ++software does. But this License is not limited to software manuals; ++it can be used for any textual work, regardless of subject matter or ++whether it is published as a printed book. We recommend this License ++principally for works whose purpose is instruction or reference. ++ ++@item ++APPLICABILITY AND DEFINITIONS ++ ++This License applies to any manual or other work, in any medium, that ++contains a notice placed by the copyright holder saying it can be ++distributed under the terms of this License. Such a notice grants a ++world-wide, royalty-free license, unlimited in duration, to use that ++work under the conditions stated herein. The ``Document'', below, ++refers to any such manual or work. Any member of the public is a ++licensee, and is addressed as ``you''. You accept the license if you ++copy, modify or distribute the work in a way requiring permission ++under copyright law. ++ ++A ``Modified Version'' of the Document means any work containing the ++Document or a portion of it, either copied verbatim, or with ++modifications and/or translated into another language. ++ ++A ``Secondary Section'' is a named appendix or a front-matter section ++of the Document that deals exclusively with the relationship of the ++publishers or authors of the Document to the Document's overall ++subject (or to related matters) and contains nothing that could fall ++directly within that overall subject. (Thus, if the Document is in ++part a textbook of mathematics, a Secondary Section may not explain ++any mathematics.) The relationship could be a matter of historical ++connection with the subject or with related matters, or of legal, ++commercial, philosophical, ethical or political position regarding ++them. ++ ++The ``Invariant Sections'' are certain Secondary Sections whose titles ++are designated, as being those of Invariant Sections, in the notice ++that says that the Document is released under this License. If a ++section does not fit the above definition of Secondary then it is not ++allowed to be designated as Invariant. The Document may contain zero ++Invariant Sections. If the Document does not identify any Invariant ++Sections then there are none. ++ ++The ``Cover Texts'' are certain short passages of text that are listed, ++as Front-Cover Texts or Back-Cover Texts, in the notice that says that ++the Document is released under this License. A Front-Cover Text may ++be at most 5 words, and a Back-Cover Text may be at most 25 words. ++ ++A ``Transparent'' copy of the Document means a machine-readable copy, ++represented in a format whose specification is available to the ++general public, that is suitable for revising the document ++straightforwardly with generic text editors or (for images composed of ++pixels) generic paint programs or (for drawings) some widely available ++drawing editor, and that is suitable for input to text formatters or ++for automatic translation to a variety of formats suitable for input ++to text formatters. A copy made in an otherwise Transparent file ++format whose markup, or absence of markup, has been arranged to thwart ++or discourage subsequent modification by readers is not Transparent. ++An image format is not Transparent if used for any substantial amount ++of text. A copy that is not ``Transparent'' is called ``Opaque''. ++ ++Examples of suitable formats for Transparent copies include plain ++@sc{ascii} without markup, Texinfo input format, La@TeX{} input ++format, @acronym{SGML} or @acronym{XML} using a publicly available ++@acronym{DTD}, and standard-conforming simple @acronym{HTML}, ++PostScript or @acronym{PDF} designed for human modification. Examples ++of transparent image formats include @acronym{PNG}, @acronym{XCF} and ++@acronym{JPG}. Opaque formats include proprietary formats that can be ++read and edited only by proprietary word processors, @acronym{SGML} or ++@acronym{XML} for which the @acronym{DTD} and/or processing tools are ++not generally available, and the machine-generated @acronym{HTML}, ++PostScript or @acronym{PDF} produced by some word processors for ++output purposes only. ++ ++The ``Title Page'' means, for a printed book, the title page itself, ++plus such following pages as are needed to hold, legibly, the material ++this License requires to appear in the title page. For works in ++formats which do not have any title page as such, ``Title Page'' means ++the text near the most prominent appearance of the work's title, ++preceding the beginning of the body of the text. ++ ++The ``publisher'' means any person or entity that distributes copies ++of the Document to the public. ++ ++A section ``Entitled XYZ'' means a named subunit of the Document whose ++title either is precisely XYZ or contains XYZ in parentheses following ++text that translates XYZ in another language. (Here XYZ stands for a ++specific section name mentioned below, such as ``Acknowledgements'', ++``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' ++of such a section when you modify the Document means that it remains a ++section ``Entitled XYZ'' according to this definition. ++ ++The Document may include Warranty Disclaimers next to the notice which ++states that this License applies to the Document. These Warranty ++Disclaimers are considered to be included by reference in this ++License, but only as regards disclaiming warranties: any other ++implication that these Warranty Disclaimers may have is void and has ++no effect on the meaning of this License. ++ ++@item ++VERBATIM COPYING ++ ++You may copy and distribute the Document in any medium, either ++commercially or noncommercially, provided that this License, the ++copyright notices, and the license notice saying this License applies ++to the Document are reproduced in all copies, and that you add no other ++conditions whatsoever to those of this License. You may not use ++technical measures to obstruct or control the reading or further ++copying of the copies you make or distribute. However, you may accept ++compensation in exchange for copies. If you distribute a large enough ++number of copies you must also follow the conditions in section 3. ++ ++You may also lend copies, under the same conditions stated above, and ++you may publicly display copies. ++ ++@item ++COPYING IN QUANTITY ++ ++If you publish printed copies (or copies in media that commonly have ++printed covers) of the Document, numbering more than 100, and the ++Document's license notice requires Cover Texts, you must enclose the ++copies in covers that carry, clearly and legibly, all these Cover ++Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on ++the back cover. Both covers must also clearly and legibly identify ++you as the publisher of these copies. The front cover must present ++the full title with all words of the title equally prominent and ++visible. You may add other material on the covers in addition. ++Copying with changes limited to the covers, as long as they preserve ++the title of the Document and satisfy these conditions, can be treated ++as verbatim copying in other respects. ++ ++If the required texts for either cover are too voluminous to fit ++legibly, you should put the first ones listed (as many as fit ++reasonably) on the actual cover, and continue the rest onto adjacent ++pages. ++ ++If you publish or distribute Opaque copies of the Document numbering ++more than 100, you must either include a machine-readable Transparent ++copy along with each Opaque copy, or state in or with each Opaque copy ++a computer-network location from which the general network-using ++public has access to download using public-standard network protocols ++a complete Transparent copy of the Document, free of added material. ++If you use the latter option, you must take reasonably prudent steps, ++when you begin distribution of Opaque copies in quantity, to ensure ++that this Transparent copy will remain thus accessible at the stated ++location until at least one year after the last time you distribute an ++Opaque copy (directly or through your agents or retailers) of that ++edition to the public. ++ ++It is requested, but not required, that you contact the authors of the ++Document well before redistributing any large number of copies, to give ++them a chance to provide you with an updated version of the Document. ++ ++@item ++MODIFICATIONS ++ ++You may copy and distribute a Modified Version of the Document under ++the conditions of sections 2 and 3 above, provided that you release ++the Modified Version under precisely this License, with the Modified ++Version filling the role of the Document, thus licensing distribution ++and modification of the Modified Version to whoever possesses a copy ++of it. In addition, you must do these things in the Modified Version: ++ ++@enumerate A ++@item ++Use in the Title Page (and on the covers, if any) a title distinct ++from that of the Document, and from those of previous versions ++(which should, if there were any, be listed in the History section ++of the Document). You may use the same title as a previous version ++if the original publisher of that version gives permission. ++ ++@item ++List on the Title Page, as authors, one or more persons or entities ++responsible for authorship of the modifications in the Modified ++Version, together with at least five of the principal authors of the ++Document (all of its principal authors, if it has fewer than five), ++unless they release you from this requirement. ++ ++@item ++State on the Title page the name of the publisher of the ++Modified Version, as the publisher. ++ ++@item ++Preserve all the copyright notices of the Document. ++ ++@item ++Add an appropriate copyright notice for your modifications ++adjacent to the other copyright notices. ++ ++@item ++Include, immediately after the copyright notices, a license notice ++giving the public permission to use the Modified Version under the ++terms of this License, in the form shown in the Addendum below. ++ ++@item ++Preserve in that license notice the full lists of Invariant Sections ++and required Cover Texts given in the Document's license notice. ++ ++@item ++Include an unaltered copy of this License. ++ ++@item ++Preserve the section Entitled ``History'', Preserve its Title, and add ++to it an item stating at least the title, year, new authors, and ++publisher of the Modified Version as given on the Title Page. If ++there is no section Entitled ``History'' in the Document, create one ++stating the title, year, authors, and publisher of the Document as ++given on its Title Page, then add an item describing the Modified ++Version as stated in the previous sentence. ++ ++@item ++Preserve the network location, if any, given in the Document for ++public access to a Transparent copy of the Document, and likewise ++the network locations given in the Document for previous versions ++it was based on. These may be placed in the ``History'' section. ++You may omit a network location for a work that was published at ++least four years before the Document itself, or if the original ++publisher of the version it refers to gives permission. ++ ++@item ++For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve ++the Title of the section, and preserve in the section all the ++substance and tone of each of the contributor acknowledgements and/or ++dedications given therein. ++ ++@item ++Preserve all the Invariant Sections of the Document, ++unaltered in their text and in their titles. Section numbers ++or the equivalent are not considered part of the section titles. ++ ++@item ++Delete any section Entitled ``Endorsements''. Such a section ++may not be included in the Modified Version. ++ ++@item ++Do not retitle any existing section to be Entitled ``Endorsements'' or ++to conflict in title with any Invariant Section. ++ ++@item ++Preserve any Warranty Disclaimers. ++@end enumerate ++ ++If the Modified Version includes new front-matter sections or ++appendices that qualify as Secondary Sections and contain no material ++copied from the Document, you may at your option designate some or all ++of these sections as invariant. To do this, add their titles to the ++list of Invariant Sections in the Modified Version's license notice. ++These titles must be distinct from any other section titles. ++ ++You may add a section Entitled ``Endorsements'', provided it contains ++nothing but endorsements of your Modified Version by various ++parties---for example, statements of peer review or that the text has ++been approved by an organization as the authoritative definition of a ++standard. ++ ++You may add a passage of up to five words as a Front-Cover Text, and a ++passage of up to 25 words as a Back-Cover Text, to the end of the list ++of Cover Texts in the Modified Version. Only one passage of ++Front-Cover Text and one of Back-Cover Text may be added by (or ++through arrangements made by) any one entity. If the Document already ++includes a cover text for the same cover, previously added by you or ++by arrangement made by the same entity you are acting on behalf of, ++you may not add another; but you may replace the old one, on explicit ++permission from the previous publisher that added the old one. ++ ++The author(s) and publisher(s) of the Document do not by this License ++give permission to use their names for publicity for or to assert or ++imply endorsement of any Modified Version. ++ ++@item ++COMBINING DOCUMENTS ++ ++You may combine the Document with other documents released under this ++License, under the terms defined in section 4 above for modified ++versions, provided that you include in the combination all of the ++Invariant Sections of all of the original documents, unmodified, and ++list them all as Invariant Sections of your combined work in its ++license notice, and that you preserve all their Warranty Disclaimers. ++ ++The combined work need only contain one copy of this License, and ++multiple identical Invariant Sections may be replaced with a single ++copy. If there are multiple Invariant Sections with the same name but ++different contents, make the title of each such section unique by ++adding at the end of it, in parentheses, the name of the original ++author or publisher of that section if known, or else a unique number. ++Make the same adjustment to the section titles in the list of ++Invariant Sections in the license notice of the combined work. ++ ++In the combination, you must combine any sections Entitled ``History'' ++in the various original documents, forming one section Entitled ++``History''; likewise combine any sections Entitled ``Acknowledgements'', ++and any sections Entitled ``Dedications''. You must delete all ++sections Entitled ``Endorsements.'' ++ ++@item ++COLLECTIONS OF DOCUMENTS ++ ++You may make a collection consisting of the Document and other documents ++released under this License, and replace the individual copies of this ++License in the various documents with a single copy that is included in ++the collection, provided that you follow the rules of this License for ++verbatim copying of each of the documents in all other respects. ++ ++You may extract a single document from such a collection, and distribute ++it individually under this License, provided you insert a copy of this ++License into the extracted document, and follow this License in all ++other respects regarding verbatim copying of that document. ++ ++@item ++AGGREGATION WITH INDEPENDENT WORKS ++ ++A compilation of the Document or its derivatives with other separate ++and independent documents or works, in or on a volume of a storage or ++distribution medium, is called an ``aggregate'' if the copyright ++resulting from the compilation is not used to limit the legal rights ++of the compilation's users beyond what the individual works permit. ++When the Document is included in an aggregate, this License does not ++apply to the other works in the aggregate which are not themselves ++derivative works of the Document. ++ ++If the Cover Text requirement of section 3 is applicable to these ++copies of the Document, then if the Document is less than one half of ++the entire aggregate, the Document's Cover Texts may be placed on ++covers that bracket the Document within the aggregate, or the ++electronic equivalent of covers if the Document is in electronic form. ++Otherwise they must appear on printed covers that bracket the whole ++aggregate. ++ ++@item ++TRANSLATION ++ ++Translation is considered a kind of modification, so you may ++distribute translations of the Document under the terms of section 4. ++Replacing Invariant Sections with translations requires special ++permission from their copyright holders, but you may include ++translations of some or all Invariant Sections in addition to the ++original versions of these Invariant Sections. You may include a ++translation of this License, and all the license notices in the ++Document, and any Warranty Disclaimers, provided that you also include ++the original English version of this License and the original versions ++of those notices and disclaimers. In case of a disagreement between ++the translation and the original version of this License or a notice ++or disclaimer, the original version will prevail. ++ ++If a section in the Document is Entitled ``Acknowledgements'', ++``Dedications'', or ``History'', the requirement (section 4) to Preserve ++its Title (section 1) will typically require changing the actual ++title. ++ ++@item ++TERMINATION ++ ++You may not copy, modify, sublicense, or distribute the Document ++except as expressly provided under this License. Any attempt ++otherwise to copy, modify, sublicense, or distribute it is void, and ++will automatically terminate your rights under this License. ++ ++However, if you cease all violation of this License, then your license ++from a particular copyright holder is reinstated (a) provisionally, ++unless and until the copyright holder explicitly and finally ++terminates your license, and (b) permanently, if the copyright holder ++fails to notify you of the violation by some reasonable means prior to ++60 days after the cessation. ++ ++Moreover, your license from a particular copyright holder is ++reinstated permanently if the copyright holder notifies you of the ++violation by some reasonable means, this is the first time you have ++received notice of violation of this License (for any work) from that ++copyright holder, and you cure the violation prior to 30 days after ++your receipt of the notice. ++ ++Termination of your rights under this section does not terminate the ++licenses of parties who have received copies or rights from you under ++this License. If your rights have been terminated and not permanently ++reinstated, receipt of a copy of some or all of the same material does ++not give you any rights to use it. ++ ++@item ++FUTURE REVISIONS OF THIS LICENSE ++ ++The Free Software Foundation may publish new, revised versions ++of the GNU Free Documentation License from time to time. Such new ++versions will be similar in spirit to the present version, but may ++differ in detail to address new problems or concerns. See ++@uref{http://www.gnu.org/copyleft/}. ++ ++Each version of the License is given a distinguishing version number. ++If the Document specifies that a particular numbered version of this ++License ``or any later version'' applies to it, you have the option of ++following the terms and conditions either of that specified version or ++of any later version that has been published (not as a draft) by the ++Free Software Foundation. If the Document does not specify a version ++number of this License, you may choose any version ever published (not ++as a draft) by the Free Software Foundation. If the Document ++specifies that a proxy can decide which future versions of this ++License can be used, that proxy's public statement of acceptance of a ++version permanently authorizes you to choose that version for the ++Document. ++ ++@item ++RELICENSING ++ ++``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any ++World Wide Web server that publishes copyrightable works and also ++provides prominent facilities for anybody to edit those works. A ++public wiki that anybody can edit is an example of such a server. A ++``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the ++site means any set of copyrightable works thus published on the MMC ++site. ++ ++``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 ++license published by Creative Commons Corporation, a not-for-profit ++corporation with a principal place of business in San Francisco, ++California, as well as future copyleft versions of that license ++published by that same organization. ++ ++``Incorporate'' means to publish or republish a Document, in whole or ++in part, as part of another Document. ++ ++An MMC is ``eligible for relicensing'' if it is licensed under this ++License, and if all works that were first published under this License ++somewhere other than this MMC, and subsequently incorporated in whole ++or in part into the MMC, (1) had no cover texts or invariant sections, ++and (2) were thus incorporated prior to November 1, 2008. ++ ++The operator of an MMC Site may republish an MMC contained in the site ++under CC-BY-SA on the same site at any time before August 1, 2009, ++provided the MMC is eligible for relicensing. ++ ++@end enumerate ++ ++@page ++@heading ADDENDUM: How to use this License for your documents ++ ++To use this License in a document you have written, include a copy of ++the License in the document and put the following copyright and ++license notices just after the title page: ++ ++@smallexample ++@group ++ Copyright (C) @var{year} @var{your name}. ++ Permission is granted to copy, distribute and/or modify this document ++ under the terms of the GNU Free Documentation License, Version 1.3 ++ or any later version published by the Free Software Foundation; ++ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover ++ Texts. A copy of the license is included in the section entitled ``GNU ++ Free Documentation License''. ++@end group ++@end smallexample ++ ++If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, ++replace the ``with@dots{}Texts.'' line with this: ++ ++@smallexample ++@group ++ with the Invariant Sections being @var{list their titles}, with ++ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts ++ being @var{list}. ++@end group ++@end smallexample ++ ++If you have Invariant Sections without Cover Texts, or some other ++combination of the three, merge those two alternatives to suit the ++situation. ++ ++If your document contains nontrivial examples of program code, we ++recommend releasing these examples in parallel under your choice of ++free software license, such as the GNU General Public License, ++to permit their use in free software. ++ ++ ++@c Local Variables: ++@c ispell-local-pdict: "ispell-dict" ++@c End: ++ ++@ignore ++ arch-tag: d68e7b7a-0c7c-4c15-905b-a9482214e25a ++@end ignore ++ +diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi +new file mode 100644 +index 0000000..0450450 +--- /dev/null ++++ b/doc/emacs/emacs-xtra.texi +@@ -0,0 +1,142 @@ ++\input texinfo @c -*-texinfo-*- ++@comment %**start of header ++@setfilename ../../info/emacs-xtra ++@settitle Specialized Emacs Features ++@c Merge all functions, variables, and keys into the concept index. ++@syncodeindex fn cp ++@syncodeindex vr cp ++@syncodeindex ky cp ++@comment %**end of header ++ ++@copying ++This manual describes specialized features of Emacs. ++ ++Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 ++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 Emacs 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.'' ++ ++This document is part of a collection distributed under the GNU Free ++Documentation License. If you want to distribute this document ++separately from the collection, you can do so by adding a copy of the ++license to the document, as described in section 6 of the license. ++@end quotation ++@end copying ++ ++@dircategory Emacs ++@direntry ++* Emacs-Xtra: (emacs-xtra). Specialized Emacs features. ++@end direntry ++ ++@titlepage ++@title Specialized Emacs Features ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top ++@top Specialized Emacs Features ++ ++@insertcopying ++ ++@end ifnottex ++ ++@menu ++* Introduction:: What documentation belongs here? ++@iftex ++* Picture Mode:: Editing pictures made up of characters using ++ the quarter-plane screen model. ++ ++* Autorevert:: Auto Reverting non-file buffers. ++* Subdir Switches:: Subdirectory switches in Dired. ++* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. ++* Emerge:: A convenient way of merging two versions of a program. ++* Advanced VC Usage:: Advanced VC (version control) features. ++* Fortran:: Fortran mode and its special features. ++* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). ++@end iftex ++* Index:: ++@end menu ++ ++@node Introduction ++@unnumbered Introduction ++ ++This manual contains detailed information about various features that ++are too specialized to be included in the printed Emacs manual. It is ++intended to be readable by anyone having a basic knowledge of Emacs. ++However, certain sections may be intended for a more specialized ++audience, such as Elisp authors. This should be clearly pointed out ++at the beginning of these sections. ++ ++@c Note to authors - you need to be careful about cross-references to ++@c topics in the Emacs manual. As a printed document, the xtra files ++@c are separate from the Emacs manual; but as an info document, they ++@c are part of the Emacs manual. Hence you need to use something like: ++@c @iftex ++@c @ref{Comparing Files,,, emacs, the Emacs Manual}, ++@c @end iftex ++@c @ifnottex ++@c @ref{Comparing Files}, ++@c @end ifnottex ++ ++Certain packages (or collections of related features) have their own ++manuals, separate from the main Emacs manual. This manual is ++intended as a complement, rather than an alternative, to reading those ++additional manuals. In a nutshell, it is a collection of smaller ++specialized features (or extra detail about standard features), too ++small or too obscure to justify their own manual, or inclusion in the ++printed Emacs manual. The chapters in this manual are, however, ++included (at the relevant places) in the main Emacs manual when it is ++formatted as an Info document. ++ ++Sections intended specifically for Elisp programmers can follow the ++style of the Elisp manual. Other sections should follow the style of ++the Emacs manual. ++ ++@iftex ++@c ``Picture Mode'' is a chapter, not a section, so it's outside @raisesections. ++@include picture-xtra.texi ++ ++@raisesections ++@include arevert-xtra.texi ++ ++@include dired-xtra.texi ++ ++@include cal-xtra.texi ++ ++@include emerge-xtra.texi ++ ++@include vc-xtra.texi ++ ++@include fortran-xtra.texi ++ ++@include msdog-xtra.texi ++ ++@lowersections ++@end iftex ++ ++@node Index ++@unnumbered Index ++ ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49 ++@end ignore +diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi +new file mode 100644 +index 0000000..2ba12b1 +--- /dev/null ++++ b/doc/emacs/emacs.texi +@@ -0,0 +1,1570 @@ ++\input texinfo ++ ++@setfilename ../../info/emacs ++@settitle GNU Emacs Manual ++ ++@c The edition number appears in several places in this file ++@set EDITION Sixteenth ++@set EMACSVER 23.1 ++ ++@copying ++This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@* ++updated for Emacs version @value{EMACSVER}. ++ ++Copyright @copyright{} 1985, 1986, 1987, 1993, 1994, 1995, 1996, 1997, ++1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++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 the ++Invariant Sections being ``The GNU Manifesto,'' ``Distribution'' and ++``GNU GENERAL PUBLIC LICENSE,'' 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 Emacs ++@direntry ++* Emacs: (emacs). The extensible self-documenting text editor. ++@end direntry ++ ++@c in general, keep the following line commented out, unless doing a ++@c copy of this manual that will be published. The manual should go ++@c onto the distribution in the full, 8.5 x 11" size. ++@c set smallbook ++ ++@ifset smallbook ++@smallbook ++@end ifset ++ ++@c per rms and peterb, use 10pt fonts for the main text, mostly to ++@c save on paper cost. ++@c Do this inside @tex for now, so current makeinfo does not complain. ++@tex ++@ifset smallbook ++@fonttextsize 10 ++@set EMACSVER 22 ++\global\let\urlcolor=\Black % don't print links in grayscale ++\global\let\linkcolor=\Black ++@end ifset ++\global\hbadness=6666 % don't worry about not-too-underfull boxes ++@end tex ++ ++@defcodeindex op ++@synindex pg cp ++ ++@iftex ++@kbdinputstyle code ++ ++@shorttitlepage GNU Emacs Manual ++@end iftex ++ ++@titlepage ++@sp 6 ++@center @titlefont{GNU Emacs Manual} ++@sp 4 ++@center @value{EDITION} Edition, Updated for Emacs Version @value{EMACSVER}. ++@sp 5 ++@center Richard Stallman ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++ ++@sp 2 ++Published by the Free Software Foundation @* ++51 Franklin Street, Fifth Floor @* ++Boston, MA 02110-1301 USA @* ++ISBN 1-882114-86-8 ++ ++@sp 2 ++Cover art by Etienne Suvasa. ++ ++@end titlepage ++ ++ ++@summarycontents ++@contents ++ ++ ++@ifnottex ++@node Top, Distrib, (dir), (dir) ++@top The Emacs Editor ++ ++Emacs is the extensible, customizable, self-documenting real-time ++display editor. This Info file describes how to edit with Emacs and ++some of how to customize it; it corresponds to GNU Emacs version ++@value{EMACSVER}. ++ ++@ifinfo ++To learn more about the Info documentation system, type @kbd{h}, ++to visit a programmed instruction sequence for the Info commands. ++@end ifinfo ++ ++For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The ++Emacs Lisp Reference Manual}. ++ ++@insertcopying ++@end ifnottex ++ ++@ignore ++These subcategories have been deleted for simplicity ++and to avoid conflicts. ++Completion ++Backup Files ++Auto-Saving: Protection Against Disasters ++Tags ++Text Mode ++Outline Mode ++@TeX{} Mode ++Formatted Text ++Shell Command History ++ ++The ones for Dired and Rmail have had the items turned into :: items ++to avoid conflicts. ++Also Running Shell Commands from Emacs ++and Sending Mail and Registers and Minibuffer. ++@end ignore ++ ++@menu ++* Distrib:: How to get the latest Emacs distribution. ++* Intro:: An introduction to Emacs concepts. ++@c Note that in the printed manual, the glossary and indices come last. ++* Glossary:: Terms used in this manual. ++ ++Indexes (each index contains a large menu) ++* Key Index:: An item for each standard Emacs key sequence. ++* Option Index:: An item for every command-line option. ++* Command Index:: An item for each command name. ++* Variable Index:: An item for each documented variable. ++* Concept Index:: An item for each concept. ++ ++* Acknowledgments:: Major contributors to GNU Emacs. ++ ++Important General Concepts ++* Screen:: How to interpret what you see on the screen. ++* User Input:: Kinds of input events (characters, buttons, ++ function keys). ++* Keys:: Key sequences: what you type to request one ++ editing action. ++* Commands:: Named functions run by key sequences to do editing. ++* Entering Emacs:: Starting Emacs from the shell. ++* Exiting:: Stopping or killing Emacs. ++ ++Fundamental Editing Commands ++* Basic:: The most basic editing commands. ++* Minibuffer:: Entering arguments that are prompted for. ++* M-x:: Invoking commands by their names. ++* Help:: Commands for asking Emacs about its commands. ++ ++Important Text-Changing Commands ++* Mark:: The mark: how to delimit a ``region'' of text. ++* Killing:: Killing (cutting) text. ++* Yanking:: Recovering killed text. Moving text. (Pasting.) ++* Accumulating Text:: Other ways of copying text. ++* Rectangles:: Operating on the text inside a rectangle on the screen. ++* CUA Bindings:: Using @kbd{C-x}, @kbd{C-c}, @kbd{C-v} for copy ++ and paste, with enhanced rectangle support. ++* Registers:: Saving a text string or a location in the buffer. ++* Display:: Controlling what text is displayed. ++* Search:: Finding or replacing occurrences of a string. ++* Fixit:: Commands especially useful for fixing typos. ++* Keyboard Macros:: A keyboard macro records a sequence of ++ keystrokes to be replayed with a single command. ++ ++Major Structures of Emacs ++* Files:: All about handling files. ++* Buffers:: Multiple buffers; editing several files at once. ++* Windows:: Viewing two pieces of text at once. ++* Frames:: Running the same Emacs session in multiple X windows. ++* International:: Using non-@acronym{ASCII} character sets. ++ ++Advanced Features ++* Major Modes:: Text mode vs. Lisp mode vs. C mode... ++* Indentation:: Editing the white space at the beginnings of lines. ++* Text:: Commands and modes for editing English. ++* Programs:: Commands and modes for editing programs. ++* Building:: Compiling, running and debugging programs. ++* Maintaining:: Features for maintaining large programs. ++* Abbrevs:: How to define text abbreviations to reduce ++ the number of characters you must type. ++@c AFAICS, the tex stuff generates its own index and does not use this one. ++@ifnottex ++* Picture Mode:: Editing pictures made up of characters using ++ the quarter-plane screen model. ++@end ifnottex ++* Sending Mail:: Sending mail in Emacs. ++* Rmail:: Reading mail in Emacs. ++* Dired:: You can ``edit'' a directory to manage files in it. ++* Calendar/Diary:: The calendar and diary facilities. ++* Document View:: Viewing PDF, PS and DVI files. ++* Gnus:: How to read netnews with Emacs. ++* Shell:: Executing shell commands from Emacs. ++* Emacs Server:: Using Emacs as an editing server for @code{mail}, etc. ++* Printing:: Printing hardcopies of buffers or regions. ++* Sorting:: Sorting lines, paragraphs or pages within Emacs. ++* Narrowing:: Restricting display and editing to a portion ++ of the buffer. ++* Two-Column:: Splitting apart columns to edit them ++ in side-by-side windows. ++* Editing Binary Files::Using Hexl mode to edit binary files. ++* Saving Emacs Sessions:: Saving Emacs state from one session to the next. ++* Recursive Edit:: A command can allow you to do editing ++ "within the command". This is called a ++ "recursive editing level". ++* Emulation:: Emulating some other editors with Emacs. ++* Hyperlinking:: Following links in buffers. ++* Dissociated Press:: Dissociating text for fun. ++* Amusements:: Various games and hacks. ++* Customization:: Modifying the behavior of Emacs. ++ ++Recovery from Problems ++* Quitting:: Quitting and aborting. ++* Lossage:: What to do if Emacs is hung or malfunctioning. ++* Bugs:: How and when to report a bug. ++* Contributing:: How to contribute improvements to Emacs. ++* Service:: How to get help for your own Emacs needs. ++ ++Appendices ++* Copying:: The GNU General Public License gives you permission ++ to redistribute GNU Emacs on certain terms; ++ it also explains that there is no warranty. ++* GNU Free Documentation License:: The license for this documentation. ++* Emacs Invocation:: Hairy startup options. ++* X Resources:: X resources for customizing Emacs. ++* Antinews:: Information about Emacs version 22. ++* Mac OS / GNUstep:: Using Emacs under Mac OS and GNUstep. ++* Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS. ++* Manifesto:: What's GNU? Gnu's Not Unix! ++ ++@c Do NOT modify the following 3 lines! They must have this form to ++@c be correctly identified by `texinfo-multiple-files-update'. In ++@c particular, the detailed menu header line MUST be identical to the ++@c value of `texinfo-master-menu-header'. See texnfo-upd.el. ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ --------------------------------- ++ ++Here are some other nodes which are really inferiors of the ones ++already listed, mentioned here so you can get to them in one step: ++ ++The Organization of the Screen ++ ++* Point:: The place in the text where editing commands operate. ++* Echo Area:: Short messages appear at the bottom of the screen. ++* Mode Line:: Interpreting the mode line. ++* Menu Bar:: How to use the menu bar. ++ ++Basic Editing Commands ++ ++* Inserting Text:: Inserting text by simply typing it. ++* Moving Point:: Moving the cursor to the place where you want to ++ change something. ++* Erasing:: Deleting and killing text. ++* Basic Undo:: Undoing recent changes in the text. ++* Basic Files:: Visiting, creating, and saving files. ++* Basic Help:: Asking what a character does. ++* Blank Lines:: Making and deleting blank lines. ++* Continuation Lines:: How Emacs displays lines too wide for the screen. ++* Position Info:: What page, line, row, or column is point on? ++* Arguments:: Numeric arguments for repeating a command N times. ++* Repeating:: Repeating the previous command quickly. ++ ++The Minibuffer ++ ++* Minibuffer File:: Entering file names with the minibuffer. ++* Minibuffer Edit:: How to edit in the minibuffer. ++* Completion:: An abbreviation facility for minibuffer input. ++* Minibuffer History:: Reusing recent minibuffer arguments. ++* Repetition:: Re-executing commands that used the minibuffer. ++* Passwords:: Entering passwords in the echo area. ++ ++Completion ++ ++* Completion Example:: Examples of using completion. ++* Completion Commands:: A list of completion commands. ++* Strict Completion:: Different types of completion. ++* Completion Options:: Options for completion. ++ ++Help ++ ++* Help Summary:: Brief list of all Help commands. ++* Key Help:: Asking what a key does in Emacs. ++* Name Help:: Asking about a command, variable or function name. ++* Apropos:: Asking what pertains to a given topic. ++* Help Mode:: Special features of Help mode and Help buffers. ++* Library Keywords:: Finding Lisp libraries by keywords (topics). ++* Language Help:: Help relating to international language support. ++* Misc Help:: Other help commands. ++* Help Files:: Commands to display pre-written help files. ++* Help Echo:: Help on active text and tooltips (`balloon help'). ++ ++The Mark and the Region ++ ++* Setting Mark:: Commands to set the mark. ++* Marking Objects:: Commands to put region around textual units. ++* Using Region:: Summary of ways to operate on contents of the region. ++* Mark Ring:: Previous mark positions saved so you can go back there. ++* Global Mark Ring:: Previous mark positions in various buffers. ++* Shift Selection:: Using shifted cursor motion keys. ++* Persistent Mark:: Keeping the mark active all the time. ++ ++Killing and Moving Text ++ ++* Deletion:: Commands for deleting small amounts of text and ++ blank areas. ++* Killing by Lines:: How to kill entire lines of text at one time. ++* Other Kill Commands:: Commands to kill large regions of text and ++ syntactic units such as words and sentences. ++ ++Yanking ++ ++* Kill Ring:: Where killed text is stored. Basic yanking. ++* Appending Kills:: Several kills in a row all yank together. ++* Earlier Kills:: Yanking something killed some time ago. ++ ++Registers ++ ++* RegPos:: Saving positions in registers. ++* RegText:: Saving text in registers. ++* RegRect:: Saving rectangles in registers. ++* RegConfig:: Saving window configurations in registers. ++* RegNumbers:: Numbers in registers. ++* RegFiles:: File names in registers. ++* Bookmarks:: Bookmarks are like registers, but persistent. ++ ++Controlling the Display ++ ++* Scrolling:: Commands to move text up and down in a window. ++* Auto Scrolling:: Redisplay scrolls text automatically when needed. ++* Horizontal Scrolling:: Moving text left and right in a window. ++* Follow Mode:: Follow mode lets two windows scroll as one. ++* Faces:: How to change the display style using faces. ++* Standard Faces:: Emacs' predefined faces. ++* Temporary Face Changes:: Commands to temporarily modify the default text face ++* Font Lock:: Minor mode for syntactic highlighting using faces. ++* Highlight Interactively:: Tell Emacs what text to highlight. ++* Fringes:: Enabling or disabling window fringes. ++* Displaying Boundaries:: Displaying top and bottom of the buffer. ++* Useless Whitespace:: Showing possibly-spurious trailing whitespace. ++* Selective Display:: Hiding lines with lots of indentation. ++* Optional Mode Line:: Optional mode line display features. ++* Text Display:: How text characters are normally displayed. ++* Cursor Display:: Features for displaying the cursor. ++* Line Truncation:: Truncating lines to fit the screen width instead ++ of continuing them to multiple screen lines. ++* Visual Line Mode:: Word wrap and screen line-based editing. ++* Display Custom:: Information on variables for customizing display. ++ ++Searching and Replacement ++ ++* Incremental Search:: Search happens as you type the string. ++* Nonincremental Search:: Specify entire string and then search. ++* Word Search:: Search for sequence of words. ++* Regexp Search:: Search for match for a regexp. ++* Regexps:: Syntax of regular expressions. ++* Regexp Backslash:: Regular expression constructs starting with `\'. ++* Regexp Example:: A complex regular expression explained. ++* Search Case:: To ignore case while searching, or not. ++* Replace:: Search, and replace some or all matches. ++* Other Repeating Search:: Operating on all matches for some regexp. ++ ++Incremental Search ++ ++* Basic Isearch:: Basic incremental search commands. ++* Repeat Isearch:: Searching for the same string again. ++* Error in Isearch:: When your string is not found. ++* Special Isearch:: Special input in incremental search. ++* Isearch Yank:: Commands that grab text into the search string ++ or else edit the search string. ++* Isearch Scroll:: Scrolling during an incremental search. ++* Isearch Minibuffer:: Incremental search of the minibuffer history. ++* Slow Isearch:: Incremental search features for slow terminals. ++ ++Replacement Commands ++ ++* Unconditional Replace:: Replacing all matches for a string. ++* Regexp Replace:: Replacing all matches for a regexp. ++* Replacement and Case:: How replacements preserve case of letters. ++* Query Replace:: How to use querying. ++ ++Commands for Fixing Typos ++ ++* Undo:: The Undo commands. ++* Transpose:: Exchanging two characters, words, lines, lists... ++* Fixing Case:: Correcting case of last word entered. ++* Spelling:: Apply spelling checker to a word, or a whole file. ++ ++Keyboard Macros ++ ++* Basic Keyboard Macro:: Defining and running keyboard macros. ++* Keyboard Macro Ring:: Where previous keyboard macros are saved. ++* Keyboard Macro Counter:: Inserting incrementing numbers in macros. ++* Keyboard Macro Query:: Making keyboard macros do different things each time. ++* Save Keyboard Macro:: Giving keyboard macros names; saving them in files. ++* Edit Keyboard Macro:: Editing keyboard macros. ++* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard ++ macro. ++ ++File Handling ++ ++* File Names:: How to type and edit file-name arguments. ++* Visiting:: Visiting a file prepares Emacs to edit the file. ++* Saving:: Saving makes your changes permanent. ++* Reverting:: Reverting cancels all the changes not saved. ++* Autorevert:: Auto Reverting non-file buffers. ++* Auto Save:: Auto Save periodically protects against loss of data. ++* File Aliases:: Handling multiple names for one file. ++* Directories:: Creating, deleting, and listing file directories. ++* Comparing Files:: Finding where two files differ. ++* Diff Mode:: Mode for editing file differences. ++* Misc File Ops:: Other things you can do on files. ++* Compressed Files:: Accessing compressed files. ++* File Archives:: Operating on tar, zip, jar etc. archive files. ++* Remote Files:: Accessing files on other sites. ++* Quoted File Names:: Quoting special characters in file names. ++* File Name Cache:: Completion against a list of files you often use. ++* File Conveniences:: Convenience Features for Finding Files. ++* Filesets:: Handling sets of files. ++ ++Saving Files ++ ++* Save Commands:: Commands for saving files. ++* Backup:: How Emacs saves the old version of your file. ++* Customize Save:: Customizing the saving of files. ++* Interlocking:: How Emacs protects against simultaneous editing ++ of one file by two users. ++* File Shadowing:: Copying files to "shadows" automatically. ++* Time Stamps:: Emacs can update time stamps on saved files. ++ ++Backup Files ++ ++* Backup Names:: How backup files are named. ++* Backup Deletion:: Emacs deletes excess numbered backups. ++* Backup Copying:: Backups can be made by copying or renaming. ++ ++Auto Reverting Non-File Buffers ++ ++* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. ++* Auto Reverting Dired:: Auto Revert of Dired buffers. ++* Supporting additional buffers:: How to add more Auto Revert support. ++ ++Auto-Saving: Protection Against Disasters ++ ++* Auto Save Files:: The file where auto-saved changes are ++ actually made until you save the file. ++* Auto Save Control:: Controlling when and how often to auto-save. ++* Recover:: Recovering text from auto-save files. ++ ++Using Multiple Buffers ++ ++* Select Buffer:: Creating a new buffer or reselecting an old one. ++* List Buffers:: Getting a list of buffers that exist. ++* Misc Buffer:: Renaming; changing read-onlyness; copying text. ++* Kill Buffer:: Killing buffers you no longer need. ++* Several Buffers:: How to go through the list of all buffers ++ and operate variously on several of them. ++* Indirect Buffers:: An indirect buffer shares the text of another buffer. ++* Buffer Convenience:: Convenience and customization features for ++ buffer handling. ++ ++Convenience Features and Customization of Buffer Handling ++ ++* Uniquify:: Making buffer names unique with directory parts. ++* Iswitchb:: Switching between buffers with substrings. ++* Buffer Menus:: Configurable buffer menu. ++ ++Multiple Windows ++ ++* Basic Window:: Introduction to Emacs windows. ++* Split Window:: New windows are made by splitting existing windows. ++* Other Window:: Moving to another window or doing something to it. ++* Pop Up Window:: Finding a file or buffer in another window. ++* Force Same Window:: Forcing certain buffers to appear in the selected ++ window rather than in another window. ++* Change Window:: Deleting windows and changing their sizes. ++* Window Convenience:: Convenience functions for window handling. ++ ++Frames and Graphical Displays ++ ++* Cut and Paste:: Mouse commands for cut and paste. ++* Mouse References:: Using the mouse to select an item from a list. ++* Menu Mouse Clicks:: Mouse clicks that bring up menus. ++* Mode Line Mouse:: Mouse clicks on the mode line. ++* Creating Frames:: Creating additional Emacs frames with various contents. ++* Frame Commands:: Iconifying, deleting, and switching frames. ++* Speedbar:: How to make and use a speedbar frame. ++* Multiple Displays:: How one Emacs job can talk to several displays. ++* Special Buffer Frames:: You can make certain buffers have their own frames. ++* Frame Parameters:: Changing the colors and other modes of frames. ++* Scroll Bars:: How to enable and disable scroll bars; how to use them. ++* Wheeled Mice:: Using mouse wheels for scrolling. ++* Drag and Drop:: Using drag and drop to open files and insert text. ++* Menu Bars:: Enabling and disabling the menu bar. ++* Tool Bars:: Enabling and disabling the tool bar. ++* Dialog Boxes:: Controlling use of dialog boxes. ++* Tooltips:: Displaying information at the current mouse position. ++* Mouse Avoidance:: Moving the mouse pointer out of the way. ++* Non-Window Terminals:: Multiple frames on terminals that show only one. ++* Text-Only Mouse:: Using the mouse in text-only terminals. ++ ++Killing and Yanking on Graphical Displays ++ ++* Mouse Commands:: Moving, cutting, and pasting, with the mouse. ++* Word and Line Mouse:: Mouse commands for selecting whole words or lines. ++* Cut/Paste Other App:: Transfering text between Emacs and other apps. ++* Secondary Selection:: Cutting without altering point and mark. ++* Clipboard:: Using the clipboard for selections. ++ ++International Character Set Support ++ ++* International Chars:: Basic concepts of multibyte characters. ++* Enabling Multibyte:: Controlling whether to use multibyte characters. ++* Language Environments:: Setting things up for the language you use. ++* Input Methods:: Entering text characters not on your keyboard. ++* Select Input Method:: Specifying your choice of input methods. ++* Coding Systems:: Character set conversion when you read and ++ write files, and so on. ++* Recognize Coding:: How Emacs figures out which conversion to use. ++* Specify Coding:: Specifying a file's coding system explicitly. ++* Output Coding:: Choosing coding systems for output. ++* Text Coding:: Choosing conversion to use for file text. ++* Communication Coding:: Coding systems for interprocess communication. ++* File Name Coding:: Coding systems for file @emph{names}. ++* Terminal Coding:: Specifying coding systems for converting ++ terminal input and output. ++* Fontsets:: Fontsets are collections of fonts ++ that cover the whole spectrum of characters. ++* Defining Fontsets:: Defining a new fontset. ++* Modifying Fontsets:: Modifying an existing fontset. ++* Undisplayable Characters::When characters don't display. ++* Unibyte Mode:: You can pick one European character set ++ to use without multibyte characters. ++* Charsets:: How Emacs groups its internal character codes. ++ ++Major Modes ++ ++* Choosing Modes:: How major modes are specified or chosen. ++ ++Indentation ++ ++* Indentation Commands:: Various commands and techniques for indentation. ++* Tab Stops:: You can set arbitrary "tab stops" and then ++ indent to the next tab stop when you want to. ++* Just Spaces:: You can request indentation using just spaces. ++ ++Commands for Human Languages ++ ++* Words:: Moving over and killing words. ++* Sentences:: Moving over and killing sentences. ++* Paragraphs:: Moving over paragraphs. ++* Pages:: Moving over pages. ++* Filling:: Filling or justifying text. ++* Case:: Changing the case of text. ++* Text Mode:: The major modes for editing text files. ++* Outline Mode:: Editing outlines. ++* TeX Mode:: Editing input to the formatter TeX. ++* HTML Mode:: Editing HTML, SGML, and XML files. ++* Nroff Mode:: Editing input to the formatter nroff. ++* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. ++* Text Based Tables:: Editing text-based tables in WYSIWYG fashion. ++ ++Filling Text ++ ++* Auto Fill:: Auto Fill mode breaks long lines automatically. ++* Fill Commands:: Commands to refill paragraphs and center lines. ++* Fill Prefix:: Filling paragraphs that are indented ++ or in a comment, etc. ++* Adaptive Fill:: How Emacs can determine the fill prefix automatically. ++* Refill:: Keeping paragraphs filled. ++* Longlines:: Editing text with very long lines. ++ ++Outline Mode ++ ++* Outline Format:: What the text of an outline looks like. ++* Outline Motion:: Special commands for moving through ++ outlines. ++* Outline Visibility:: Commands to control what is visible. ++* Outline Views:: Outlines and multiple views. ++* Foldout:: Folding means zooming in on outlines. ++ ++@TeX{} Mode ++ ++* TeX Editing:: Special commands for editing in TeX mode. ++* LaTeX Editing:: Additional commands for LaTeX input files. ++* TeX Print:: Commands for printing part of a file with TeX. ++* TeX Misc:: Customization of TeX mode, and related features. ++ ++Editing Formatted Text ++ ++* Requesting Formatted Text:: Entering and exiting Enriched mode. ++* Hard and Soft Newlines:: There are two different kinds of newlines. ++* Editing Format Info:: How to edit text properties. ++* Format Faces:: Bold, italic, underline, etc. ++* Format Colors:: Changing the color of text. ++* Format Indentation:: Changing the left and right margins. ++* Format Justification:: Centering, setting text flush with the ++ left or right margin, etc. ++* Format Properties:: The "special" text properties submenu. ++* Forcing Enriched Mode:: How to force use of Enriched mode. ++ ++@c The automatic texinfo menu update inserts some duplicate items here ++@c (faces, colors, indentation, justification, properties), because ++@c they are listed in two menus. But we already have them above, no ++@c need to list them twice. ++ ++Editing Text-based Tables ++ ++* Table Definition:: What is a text based table. ++* Table Creation:: How to create a table. ++* Table Recognition:: How to activate and deactivate tables. ++* Cell Commands:: Cell-oriented commands in a table. ++* Cell Justification:: Justifying cell contents. ++* Row Commands:: Manipulating rows of table cell. ++* Column Commands:: Manipulating columns of table cell. ++* Fixed Width Mode:: Fixing cell width. ++* Table Conversion:: Converting between plain text and tables. ++* Measuring Tables:: Analyzing table dimension. ++* Table Misc:: Table miscellany. ++ ++Editing Programs ++ ++* Program Modes:: Major modes for editing programs. ++* Defuns:: Commands to operate on major top-level parts ++ of a program. ++* Program Indent:: Adjusting indentation to show the nesting. ++* Parentheses:: Commands that operate on parentheses. ++* Comments:: Inserting, killing, and aligning comments. ++* Documentation:: Getting documentation of functions you plan to call. ++* Hideshow:: Displaying blocks selectively. ++* Symbol Completion:: Completion on symbol names of your program or language. ++* Glasses:: Making identifiersLikeThis more readable. ++* Misc for Programs:: Other Emacs features useful for editing programs. ++* C Modes:: Special commands of C, C++, Objective-C, ++ Java, and Pike modes. ++* Asm Mode:: Asm mode and its special features. ++* Fortran:: Fortran mode and its special features. ++ ++Top-Level Definitions, or Defuns ++ ++* Left Margin Paren:: An open-paren or similar opening delimiter ++ starts a defun if it is at the left margin. ++* Moving by Defuns:: Commands to move over or mark a major definition. ++* Imenu:: Making buffer indexes as menus. ++* Which Function:: Which Function mode shows which function you are in. ++ ++Indentation for Programs ++ ++* Basic Indent:: Indenting a single line. ++* Multi-line Indent:: Commands to reindent many lines at once. ++* Lisp Indent:: Specifying how each Lisp function should be indented. ++* C Indent:: Extra features for indenting C and related modes. ++* Custom C Indent:: Controlling indentation style for C and related modes. ++ ++Commands for Editing with Parentheses ++ ++* Expressions:: Expressions with balanced parentheses. ++* Moving by Parens:: Commands for moving up, down and across ++ in the structure of parentheses. ++* Matching:: Insertion of a close-delimiter flashes matching open. ++ ++Manipulating Comments ++ ++* Comment Commands:: Inserting, killing, and aligning comments. ++* Multi-Line Comments:: Commands for adding and editing multi-line comments. ++* Options for Comments::Customizing the comment features. ++ ++Documentation Lookup ++ ++* Info Lookup:: Looking up library functions and commands ++ in Info files. ++* Man Page:: Looking up man pages of library functions and commands. ++* Lisp Doc:: Looking up Emacs Lisp functions, etc. ++ ++C and Related Modes ++ ++* Motion in C:: Commands to move by C statements, etc. ++* Electric C:: Colon and other chars can automatically reindent. ++* Hungry Delete:: A more powerful DEL command. ++* Other C Commands:: Filling comments, viewing expansion of macros, ++ and other neat features. ++ ++Fortran Mode ++ ++* Fortran Motion:: Moving point by statements or subprograms. ++* Fortran Indent:: Indentation commands for Fortran. ++* Fortran Comments:: Inserting and aligning comments. ++* Fortran Autofill:: Auto fill support for Fortran. ++* Fortran Columns:: Measuring columns for valid Fortran. ++* Fortran Abbrev:: Built-in abbrevs for Fortran keywords. ++ ++Fortran Indentation ++ ++* ForIndent Commands:: Commands for indenting and filling Fortran. ++* ForIndent Cont:: How continuation lines indent. ++* ForIndent Num:: How line numbers auto-indent. ++* ForIndent Conv:: Conventions you must obey to avoid trouble. ++* ForIndent Vars:: Variables controlling Fortran indent style. ++ ++Compiling and Testing Programs ++ ++* Compilation:: Compiling programs in languages other ++ than Lisp (C, Pascal, etc.). ++* Compilation Mode:: The mode for visiting compiler errors. ++* Compilation Shell:: Customizing your shell properly ++ for use in the compilation buffer. ++* Grep Searching:: Searching with grep. ++* Flymake:: Finding syntax errors on the fly. ++* Debuggers:: Running symbolic debuggers for non-Lisp programs. ++* Executing Lisp:: Various modes for editing Lisp programs, ++ with different facilities for running ++ the Lisp programs. ++* Lisp Libraries:: Creating Lisp programs to run in Emacs. ++* Lisp Eval:: Executing a single Lisp expression in Emacs. ++* Lisp Interaction:: Executing Lisp in an Emacs buffer. ++* External Lisp:: Communicating through Emacs with a separate Lisp. ++ ++Running Debuggers Under Emacs ++ ++* Starting GUD:: How to start a debugger subprocess. ++* Debugger Operation:: Connection between the debugger and source buffers. ++* Commands of GUD:: Key bindings for common commands. ++* GUD Customization:: Defining your own commands for GUD. ++* GDB Graphical Interface:: An enhanced mode that uses GDB features to ++ implement a graphical debugging environment through ++ Emacs. ++ ++GDB Graphical Interface ++ ++* GDB-UI Layout:: Control the number of displayed buffers. ++* Source Buffers:: Use the mouse in the fringe/margin to ++ control your program. ++* Breakpoints Buffer:: A breakpoint control panel. ++* Stack Buffer:: Select a frame from the call stack. ++* Other GDB-UI Buffers::Input/output, locals, registers, ++ assembler, threads and memory buffers. ++* Watch Expressions:: Monitor variable values in the speedbar. ++ ++Maintaining Large Programs ++ ++* Version Control:: Using version control systems. ++* Change Log:: Maintaining a change history for your program. ++* Tags:: Go directly to any function in your program in one ++ command. Tags remembers which file it is in. ++* Emerge:: A convenient way of merging two versions of a program. ++ ++Version Control ++ ++* Introduction to VC:: How version control works in general. ++* VC Mode Line:: How the mode line shows version control status. ++* Basic VC Editing:: How to edit a file under version control. ++* Old Revisions:: Examining and comparing old versions. ++* Secondary VC Commands:: The commands used a little less frequently. ++* VC Directory Mode:: Listing files managed by version control. ++* Branches:: Multiple lines of development. ++* Remote Repositories:: Efficient access to remote CVS servers. ++* Revision Tags:: Symbolic names for revisions. ++* Miscellaneous VC:: Various other commands and features of VC. ++* Customizing VC:: Variables that change VC's behavior. ++ ++Introduction to Version Control ++ ++* Why Version Control?:: Understanding the problems it addresses. ++* Version Control Systems:: Supported version control back-end systems. ++* VCS Concepts:: Words and concepts related to version control. ++* Types of Log File:: The VCS log in contrast to the ChangeLog. ++ ++Basic Editing under Version Control ++ ++* VC With A Merging VCS:: Without locking: default mode for CVS. ++* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. ++* Advanced C-x v v:: Advanced features available with a prefix argument. ++* Log Buffer:: Features available in log entry buffers. ++ ++The Secondary Commands of VC ++ ++* Registering:: Putting a file under version control. ++* VC Status:: Viewing the VC status of files. ++* VC Undo:: Canceling changes before or after check-in. ++ ++VC Directory Mode ++ ++* VC Directory Buffer:: What the buffer looks like and means. ++* VC Directory Commands:: Commands to use in a VC directory buffer. ++ ++Multiple Branches of a File ++ ++* Switching Branches:: How to get to another existing branch. ++* Creating Branches:: How to start a new branch. ++* Merging:: Transferring changes between branches. ++* Multi-User Branching:: Multiple users working at multiple branches ++ in parallel. ++ ++Remote Repositories ++ ++* Version Backups:: Keeping local copies of repository versions. ++* Local Version Control:: Using another version system for local editing. ++ ++Revision Tags ++ ++* Making Revision Tags:: The tag facilities. ++* Revision Tag Caveats:: Things to be careful of when using tags. ++ ++Miscellaneous Commands and Features of VC ++ ++* Change Logs and VC:: Generating a change log file from log entries. ++* Renaming and VC:: A command to rename both the source and master ++ file correctly. ++* Version Headers:: Inserting version control headers into working files. ++ ++Customizing VC ++ ++* General VC Options:: Options that apply to multiple back ends. ++* RCS and SCCS:: Options for RCS and SCCS. ++* CVS Options:: Options for CVS. ++ ++Change Logs ++ ++* Change Log Commands:: Commands for editing change log files. ++* Format of ChangeLog:: What the change log file looks like. ++ ++Tags Tables ++ ++* Tag Syntax:: Tag syntax for various types of code and text files. ++* Create Tags Table:: Creating a tags table with @code{etags}. ++* Etags Regexps:: Create arbitrary tags using regular expressions. ++* Select Tags Table:: How to visit a tags table. ++* Find Tag:: Commands to find the definition of a specific tag. ++* Tags Search:: Using a tags table for searching and replacing. ++* List Tags:: Listing and finding tags defined in a file. ++ ++Merging Files with Emerge ++ ++* Overview of Emerge:: How to start Emerge. Basic concepts. ++* Submodes of Emerge:: Fast mode vs. Edit mode. ++ Skip Prefers mode and Auto Advance mode. ++* State of Difference:: You do the merge by specifying state A or B ++ for each difference. ++* Merge Commands:: Commands for selecting a difference, ++ changing states of differences, etc. ++* Exiting Emerge:: What to do when you've finished the merge. ++* Combining in Emerge:: How to keep both alternatives for a difference. ++* Fine Points of Emerge:: Miscellaneous issues. ++ ++Abbrevs ++ ++* Abbrev Concepts:: Fundamentals of defined abbrevs. ++* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. ++* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. ++* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. ++* Saving Abbrevs:: Saving the entire list of abbrevs for another session. ++* Dynamic Abbrevs:: Abbreviations for words already in the buffer. ++* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. ++ ++@ifnottex ++Editing Pictures ++ ++* Basic Picture:: Basic concepts and simple commands of Picture Mode. ++* Insert in Picture:: Controlling direction of cursor motion ++ after "self-inserting" characters. ++* Tabs in Picture:: Various features for tab stops and indentation. ++* Rectangles in Picture:: Clearing and superimposing rectangles. ++@end ifnottex ++ ++Sending Mail ++ ++* Mail Format:: Format of the mail being composed. ++* Mail Headers:: Details of some standard mail header fields. ++* Mail Aliases:: Abbreviating and grouping mail addresses. ++* Mail Mode:: Special commands for editing mail being composed. ++* Mail Amusements:: Distracting the NSA; adding fortune messages. ++* Mail Methods:: Using alternative mail-composition methods. ++ ++Mail Mode ++ ++* Mail Sending:: Commands to send the message. ++* Header Editing:: Commands to move to header fields and edit them. ++* Citing Mail:: Copying all or part of a message you are replying to. ++* Mail Mode Misc:: Spell checking, signatures, etc. ++ ++Reading Mail with Rmail ++ ++* Rmail Basics:: Basic concepts of Rmail, and simple use. ++* Rmail Scrolling:: Scrolling through a message. ++* Rmail Motion:: Moving to another message. ++* Rmail Deletion:: Deleting and expunging messages. ++* Rmail Inbox:: How mail gets into the Rmail file. ++* Rmail Files:: Using multiple Rmail files. ++* Rmail Output:: Copying message out to files. ++* Rmail Labels:: Classifying messages by labeling them. ++* Rmail Attributes:: Certain standard labels, called attributes. ++* Rmail Reply:: Sending replies to messages you are viewing. ++* Rmail Summary:: Summaries show brief info on many messages. ++* Rmail Sorting:: Sorting messages in Rmail. ++* Rmail Display:: How Rmail displays a message; customization. ++* Rmail Coding:: How Rmail handles decoding character sets. ++* Rmail Editing:: Editing message text and headers in Rmail. ++* Rmail Digest:: Extracting the messages from a digest message. ++* Rmail Rot13:: Reading messages encoded in the rot13 code. ++* Movemail:: More details of fetching new mail. ++* Remote Mailboxes:: Retrieving mail from remote mailboxes. ++* Other Mailbox Formats:: Retrieving mail from local mailboxes in ++ various formats. ++ ++Summaries ++ ++* Rmail Make Summary:: Making various sorts of summaries. ++* Rmail Summary Edit:: Manipulating messages from the summary. ++ ++Dired, the Directory Editor ++ ++* Dired Enter:: How to invoke Dired. ++* Dired Navigation:: Special motion commands in the Dired buffer. ++* Dired Deletion:: Deleting files with Dired. ++* Flagging Many Files:: Flagging files based on their names. ++* Dired Visiting:: Other file operations through Dired. ++* Marks vs Flags:: Flagging for deletion vs marking. ++* Operating on Files:: How to copy, rename, print, compress, etc. ++ either one file or several files. ++* Shell Commands in Dired:: Running a shell command on the marked files. ++* Transforming File Names:: Using patterns to rename multiple files. ++* Comparison in Dired:: Running `diff' by way of Dired. ++* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. ++* Subdir Switches:: Subdirectory switches in Dired. ++* Subdirectory Motion:: Moving across subdirectories, and up and down. ++* Hiding Subdirectories:: Making subdirectories visible or invisible. ++* Dired Updating:: Discarding lines for files of no interest. ++* Dired and Find:: Using `find' to choose the files for Dired. ++* Wdired:: Operating on files by editing the Dired buffer. ++* Image-Dired:: Viewing image thumbnails in Dired. ++* Misc Dired Features:: Various other features. ++ ++The Calendar and the Diary ++ ++* Calendar Motion:: Moving through the calendar; selecting a date. ++* Scroll Calendar:: Bringing earlier or later months onto the screen. ++* Counting Days:: How many days are there between two dates? ++* General Calendar:: Exiting or recomputing the calendar. ++* Writing Calendar Files:: Writing calendars to files of various formats. ++* Holidays:: Displaying dates of holidays. ++* Sunrise/Sunset:: Displaying local times of sunrise and sunset. ++* Lunar Phases:: Displaying phases of the moon. ++* Other Calendars:: Converting dates to other calendar systems. ++* Diary:: Displaying events from your diary. ++* Appointments:: Reminders when it's time to do something. ++* Importing Diary:: Converting diary events to/from other formats. ++* Daylight Saving:: How to specify when daylight saving time is active. ++* Time Intervals:: Keeping track of time intervals. ++* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. ++ ++Movement in the Calendar ++ ++* Calendar Unit Motion:: Moving by days, weeks, months, and years. ++* Move to Beginning or End:: Moving to start/end of weeks, months, and years. ++* Specified Dates:: Moving to the current date or another ++ specific date. ++ ++Conversion To and From Other Calendars ++ ++* Calendar Systems:: The calendars Emacs understands ++ (aside from Gregorian). ++* To Other Calendar:: Converting the selected date to various calendars. ++* From Other Calendar:: Moving to a date specified in another calendar. ++* Mayan Calendar:: Moving to a date specified in a Mayan calendar. ++ ++The Diary ++ ++* Displaying the Diary:: Viewing diary entries and associated calendar dates. ++* Format of Diary File:: Entering events in your diary. ++* Date Formats:: Various ways you can specify dates. ++* Adding to Diary:: Commands to create diary entries. ++* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. ++ ++Customizing the Calendar and Diary ++ ++* Calendar Customizing:: Calendar layout and hooks. ++* Holiday Customizing:: Defining your own holidays. ++* Date Display Format:: Changing the format. ++* Time Display Format:: Changing the format. ++* Diary Customizing:: Defaults you can set. ++* Non-Gregorian Diary:: Diary entries based on other calendars. ++* Fancy Diary Display:: Enhancing the diary display, sorting entries, ++ using included diary files. ++* Sexp Diary Entries:: Fancy things you can do. ++ ++Document Viewing ++ ++* Navigation:: Navigation inside DocView buffers. ++* Searching:: Searching inside documents. ++* Slicing:: Specifying which part of pages should be displayed. ++* Conversion:: Influencing and triggering conversion. ++ ++Gnus ++ ++* Buffers of Gnus:: The group, summary, and article buffers. ++* Gnus Startup:: What you should know about starting Gnus. ++* Summary of Gnus:: A short description of the basic Gnus commands. ++ ++Running Shell Commands from Emacs ++ ++* Single Shell:: How to run one shell command and return. ++* Interactive Shell:: Permanent shell taking input via Emacs. ++* Shell Mode:: Special Emacs commands used with permanent shell. ++* Shell Prompts:: Two ways to recognize shell prompts. ++* Shell History:: Repeating previous commands in a shell buffer. ++* Directory Tracking:: Keeping track when the subshell changes directory. ++* Shell Options:: Options for customizing Shell mode. ++* Terminal emulator:: An Emacs window as a terminal emulator. ++* Term Mode:: Special Emacs commands used in Term mode. ++* Paging in Term:: Paging in the terminal emulator. ++* Remote Host:: Connecting to another computer. ++* Serial Terminal:: Connecting to a serial port. ++ ++Shell Command History ++ ++* Shell Ring:: Fetching commands from the history list. ++* Shell History Copying::Moving to a command and then copying it. ++* History References:: Expanding @samp{!}-style history references. ++ ++Using Emacs as a Server ++ ++* Invoking emacsclient:: Connecting to the Emacs server. ++* emacsclient Options:: Emacs client startup options. ++ ++Printing Hard Copies ++ ++* PostScript:: Printing buffers or regions as PostScript. ++* PostScript Variables:: Customizing the PostScript printing commands. ++* Printing Package:: An optional advanced printing interface. ++ ++Hyperlinking and Navigation Features ++ ++* Browse-URL:: Following URLs. ++* Goto Address mode:: Activating URLs. ++* FFAP:: Finding files etc. at point. ++ ++Customization ++ ++* Minor Modes:: Each minor mode is a feature you can turn on ++ independently of any others. ++* Easy Customization:: Convenient way to browse and change settings. ++* Variables:: Many Emacs commands examine Emacs variables ++ to decide what to do; by setting variables, ++ you can control their functioning. ++* Key Bindings:: The keymaps say what command each key runs. ++ By changing them, you can "redefine keys". ++* Syntax:: The syntax table controls how words and ++ expressions are parsed. ++* Init File:: How to write common customizations in the ++ @file{.emacs} file. ++ ++Easy Customization Interface ++ ++* Customization Groups:: How settings are classified in a structure. ++* Browsing Custom:: Browsing and searching for settings. ++* Changing a Variable:: How to edit an option's value and set the option. ++* Saving Customizations:: Specifying the file for saving customizations. ++* Face Customization:: How to edit the attributes of a face. ++* Specific Customization:: Making a customization buffer for specific ++ variables, faces, or groups. ++* Custom Themes:: How to define collections of customized options ++ that can be loaded and unloaded together. ++ ++Variables ++ ++* Examining:: Examining or setting one variable's value. ++* Hooks:: Hook variables let you specify programs for parts ++ of Emacs to run on particular occasions. ++* Locals:: Per-buffer values of variables. ++* File Variables:: How files can specify variable values. ++* Directory Variables:: How variable values can be specified by directory. ++ ++Local Variables in Files ++ ++* Specifying File Variables:: Specifying file local variables. ++* Safe File Variables:: Making sure file local variables are safe. ++ ++Customizing Key Bindings ++ ++* Keymaps:: Generalities. The global keymap. ++* Prefix Keymaps:: Keymaps for prefix keys. ++* Local Keymaps:: Major and minor modes have their own keymaps. ++* Minibuffer Maps:: The minibuffer uses its own local keymaps. ++* Rebinding:: How to redefine one key's meaning conveniently. ++* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. ++* Modifier Keys:: Using modifier keys in key bindings. ++* Function Keys:: Rebinding terminal function keys. ++* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. ++* Mouse Buttons:: Rebinding mouse buttons in Emacs. ++* Disabling:: Disabling a command means confirmation is required ++ before it can be executed. This is done to protect ++ beginners from surprises. ++ ++The Init File, @file{~/.emacs} ++ ++* Init Syntax:: Syntax of constants in Emacs Lisp. ++* Init Examples:: How to do some things with an init file. ++* Terminal Init:: Each terminal type can have an init file. ++* Find Init:: How Emacs finds the init file. ++* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. ++ ++Dealing with Emacs Trouble ++ ++* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. ++* Stuck Recursive:: `[...]' in mode line around the parentheses. ++* Screen Garbled:: Garbage on the screen. ++* Text Garbled:: Garbage in the text. ++* Memory Full:: How to cope when you run out of memory. ++* After a Crash:: Recovering editing in an Emacs session that crashed. ++* Emergency Escape:: Emergency escape--- ++ What to do if Emacs stops responding. ++* Total Frustration:: When you are at your wits' end. ++ ++Reporting Bugs ++ ++* Bug Criteria:: Have you really found a bug? ++* Understanding Bug Reporting:: How to report a bug effectively. ++* Checklist:: Steps to follow for a good bug report. ++* Sending Patches:: How to send a patch for GNU Emacs. ++ ++Command Line Arguments for Emacs Invocation ++ ++* Action Arguments:: Arguments to visit files, load libraries, ++ and call functions. ++* Initial Options:: Arguments that take effect while starting Emacs. ++* Command Example:: Examples of using command line arguments. ++* Resume Arguments:: Specifying arguments when you resume a running Emacs. ++* Environment:: Environment variables that Emacs uses. ++* Display X:: Changing the default display and using remote login. ++* Font X:: Choosing a font for text, under X. ++* Colors:: Choosing display colors. ++* Window Size X:: Start-up window size, under X. ++* Borders X:: Internal and external borders, under X. ++* Title X:: Specifying the initial frame's title. ++* Icons X:: Choosing what sort of icon to use, under X. ++* Misc X:: Other display options. ++ ++Environment Variables ++ ++* General Variables:: Environment variables that all versions of Emacs use. ++* Misc Variables:: Certain system-specific variables. ++* MS-Windows Registry:: An alternative to the environment on MS-Windows. ++ ++X Options and Resources ++ ++* Resources:: Using X resources with Emacs (in general). ++* Table of Resources:: Table of specific X resources that affect Emacs. ++* Face Resources:: X resources for customizing faces. ++* Lucid Resources:: X resources for Lucid menus. ++* LessTif Resources:: X resources for LessTif and Motif menus. ++* GTK resources:: Resources for GTK widgets. ++ ++GTK resources ++ ++* GTK widget names:: How widgets in GTK are named in general. ++* GTK Names in Emacs:: GTK widget names in Emacs. ++* GTK styles:: What can be customized in a GTK widget. ++ ++Emacs and Mac OS / GNUstep ++ ++* Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or Mac OS. ++* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS. ++* Mac / GNUstep Events:: How window system events are handled. ++* GNUstep Support:: Details on status of GNUstep support. ++ ++Emacs and Microsoft Windows/MS-DOS ++ ++* Text and Binary:: Text files use CRLF to terminate lines. ++* Windows Files:: File-name conventions on Windows. ++* ls in Lisp:: Emulation of @code{ls} for Dired. ++* Windows HOME:: Where Emacs looks for your @file{.emacs}. ++* Windows Keyboard:: Windows-specific keyboard features. ++* Windows Mouse:: Windows-specific mouse features. ++* Windows Processes:: Running subprocesses on Windows. ++* Windows Printing:: How to specify the printer on MS-Windows. ++* Windows Fonts:: Specifying fonts on MS-Windows. ++* Windows Misc:: Miscellaneous Windows features. ++* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). ++ ++Emacs and MS-DOS ++ ++* MS-DOS Keyboard:: Keyboard conventions on MS-DOS. ++* MS-DOS Mouse:: Mouse conventions on MS-DOS. ++* MS-DOS Display:: Fonts, frames and display size on MS-DOS. ++* MS-DOS File Names:: File name conventions on MS-DOS. ++* MS-DOS Printing:: Printing specifics on MS-DOS. ++* MS-DOS and MULE:: Support for internationalization on MS-DOS. ++* MS-DOS Processes:: Running subprocesses on MS-DOS. ++ ++@end detailmenu ++@end menu ++ ++@iftex ++@unnumbered Preface ++ ++ This manual documents the use and simple customization of the Emacs ++editor. Simple Emacs customizations do not require you to be a ++programmer, but if you are not interested in customizing, you can ++ignore the customization hints. ++ ++ This is primarily a reference manual, but can also be used as a ++primer. If you are new to Emacs, we recommend you start with ++the integrated, learn-by-doing tutorial, before reading the manual. To ++run the tutorial, start Emacs and type @kbd{C-h t}. The tutorial ++describes commands, tells you when to try them, and explains the ++results. ++ ++ On first reading, just skim chapters 1 and 2, which describe the ++notational conventions of the manual and the general appearance of the ++Emacs display screen. Note which questions are answered in these ++chapters, so you can refer back later. After reading chapter 4, you ++should practice the commands shown there. The next few chapters ++describe fundamental techniques and concepts that are used constantly. ++You need to understand them thoroughly, so experiment with them ++until you are fluent. ++ ++ Chapters 14 through 19 describe intermediate-level features that are ++useful for many kinds of editing. Chapter 20 and following chapters ++describe optional but useful features; read those chapters when you ++need them. ++ ++ Read the Common Problems chapter if Emacs does not seem to be ++working properly. It explains how to cope with several common ++problems (@pxref{Lossage}), as well as when and how to report Emacs ++bugs (@pxref{Bugs}). ++ ++ To find the documentation of a particular command, look in the index. ++Keys (character commands) and command names have separate indexes. ++There is also a glossary, with a cross reference for each term. ++ ++ This manual is available as a printed book and also as an Info file. ++The Info file is for use with the Info program, which is the principal ++means of accessing on-line documentation in the GNU system. Both the ++Emacs Info file and an Info reader are included with GNU Emacs. The ++Info file and the printed book contain substantially the same text and ++are generated from the same source files, which are also distributed ++with GNU Emacs. ++ ++ GNU Emacs is a member of the Emacs editor family. There are many ++Emacs editors, all sharing common principles of organization. For ++information on the underlying philosophy of Emacs and the lessons ++learned from its development, see @cite{Emacs, the Extensible, ++Customizable Self-Documenting Display Editor}, available from ++@url{ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-519A.pdf}. ++ ++This edition of the manual is intended for use with GNU Emacs ++installed on GNU and Unix systems. GNU Emacs can also be used on ++MS-DOS (also called MS-DOG), Microsoft Windows, and Macintosh systems. ++Those systems use different file name syntax; in addition ++MS-DOS does not support all GNU Emacs features. @xref{Microsoft ++Windows}, for information about using Emacs on Windows. ++@xref{Mac OS / GNUstep}, for information about using Emacs on ++Macintosh (and GNUstep). ++@end iftex ++ ++@node Distrib, Intro, Top, Top ++@unnumbered Distribution ++ ++GNU Emacs is @dfn{free software}; this means that everyone is free to ++use it and free to redistribute it on certain conditions. GNU Emacs ++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 GNU Emacs that they might get from you. The precise ++conditions are found in the GNU General Public License that comes with ++Emacs and also appears in this manual@footnote{This manual is itself ++covered by the GNU Free Documentation License (see the reverse title ++page in the printed manual or view the full source for online formats ++to see the precise conditions). This license is similar in spirit to ++the General Public License, but is more suitable for documentation. ++@xref{GNU Free Documentation License}.}. @xref{Copying}. ++ ++One way to get a copy of GNU Emacs is from someone else who has it. ++You need not ask for our permission to do so, or tell any one else; ++just copy it. If you have access to the Internet, you can get the ++latest distribution version of GNU Emacs by anonymous FTP; see ++@url{http://www.gnu.org/software/emacs} on our website for more ++information. ++ ++You may also receive GNU Emacs when you buy a computer. Computer ++manufacturers are free to distribute copies on the same terms that apply to ++everyone else. These terms require them to give you the full sources, ++including whatever changes they may have made, and to permit you to ++redistribute the GNU Emacs received from them under the usual terms of the ++General Public License. In other words, the program must be free for you ++when you get it, not just free for the manufacturer. ++ ++@c FIXME no longer true? ++You can also order copies of GNU Emacs from the Free Software ++Foundation. This is a convenient and reliable way to get a copy; it is ++also a good way to help fund our work. We also sell hardcopy versions ++of this manual and @cite{An Introduction to Programming in Emacs Lisp}, ++by Robert J. Chassell. You can visit our online store at ++@url{http://shop.fsf.org/}. For further information, ++write to ++ ++@display ++Free Software Foundation ++51 Franklin Street, Fifth Floor ++Boston, MA 02110-1301 ++USA ++@end display ++ ++The income from sales goes to support the foundation's purpose: the ++development of new free software, and improvements to our existing ++programs including GNU Emacs. ++ ++@c FIXME you can't order a CD any more. ++If you find GNU Emacs useful, please @strong{send a donation} to the ++Free Software Foundation to support our work. Donations to the Free ++Software Foundation are tax deductible in the US. If you use GNU Emacs ++at your workplace, please suggest that the company make a donation. If ++company policy is unsympathetic to the idea of donating to charity, you ++might instead suggest ordering a CD-ROM from the Foundation ++occasionally, or subscribing to periodic updates. ++ ++@iftex ++@node Acknowledgments, Intro, Distrib, Top ++@unnumberedsec Acknowledgments ++ ++Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas ++Abrahamsson, Jay K.@: Adams, Michael Albinus, Nagy Andras, Ralf ++Angeli, Joe Arceneaux, Miles Bader, David Bakhash, Juanma Barranquero, ++Eli Barzilay, Steven L.@: Baur, Jay Belanger, Alexander L.@: Belikoff, ++Boaz Ben-Zvi, Karl Berry, Anna M.@: Bigatti, Ray Blaak, Jim Blandy, ++Johan Bockg@aa{}rd, Per Bothner, Terrence Brannon, Frank Bresz, Peter ++Breton, Emmanuel Briot, Kevin Broadey, Vincent Broman, David M.@: ++Brown, Georges Brun-Cottan, Joe Buehler, W@l{}odek Bzyl, Bill ++Carpenter, Per Cederqvist, Hans Chalupsky, Chong Yidong, Chris Chase, ++Bob Chassell, Andrew Choi, Sacha Chua, James Clark, Mike Clarkson, ++Glynn Clements, Andrew Csillag, Doug Cutting, Mathias Dahl, Satyaki ++Das, Michael DeCorte, Gary Delp, Matthieu Devin, Eri Ding, Jan ++Dj@"{a}rv, Carsten Dominik, Scott Draves, Benjamin Drieu, Viktor ++Dukhovni, John Eaton, Rolf Ebert, Paul Eggert, Stephen Eglen, ++Torbj@"orn Einarsson, Tsugutomo Enami, Hans Henrik Eriksen, Michael ++Ernst, Ata Etemadi, Frederick Farnbach, Oscar Figueiredo, Fred Fish, ++Karl Fogel, Gary Foster, Romain Francoise, Noah Friedman, Andreas ++Fuchs, Hallvard Furuseth, Keith Gabryelski, Peter S.@: Galbraith, ++Kevin Gallagher, Kevin Gallo, Juan Le@'{o}n Lahoz ++Garc@'{@dotless{i}}a, Howard Gayle, Stephen Gildea, Julien Gilles, ++David Gillespie, Bob Glickstein, Deepak Goel, Boris Goldowsky, ++Michelangelo Grigni, Odd Gripenstam, Kai Gro@ss{}johann, Michael ++Gschwind, Henry Guillaume, Doug Gwyn, Ken'ichi Handa, Lars Hansen, ++Chris Hanson, K. Shane Hartman, John Heidemann, Jon K.@: Hellan, ++Jesper Harder, Magnus Henoch, Markus Heritsch, Karl Heuer, Manabu ++Higashida, Anders Holst, Jeffrey C.@: Honig, Tassilo Horn, Kurt ++Hornik, Tom Houlder, Joakim Hove, Denis Howe, Lars Ingebrigtsen, ++Andrew Innes, Seiichiro Inoue, Pavel Janik, Paul Jarc, Ulf Jasper, ++Michael K. Johnson, Kyle Jones, Terry Jones, Simon Josefsson, Arne ++J@o{}rgensen, Tomoji Kagatani, Brewster Kahle, Lute Kamstra, David ++Kastrup, David Kaufman, Henry Kautz, Taichi Kawabata, Howard Kaye, ++Michael Kifer, Richard King, Peter Kleiweg, Shuhei Kobayashi, Pavel ++Kobiakov, Larry K.@: Kolodney, David M.@: Koppelman, Koseki Yoshinori, ++Robert Krawitz, Sebastian Kremer, Ryszard Kubiak, Geoff Kuenning, ++David K@aa{}gedal, Daniel LaLiberte, Mario Lang, Aaron Larson, James ++R.@: Larus, Vinicius Jose Latorre, Werner Lemberg, Frederic Lepied, ++Peter Liljenberg, Lars Lindberg, Chris Lindblad, Anders Lindgren, ++Thomas Link, Juri Linkov, Francis Litterio, Emilio C. Lopes, Károly ++Lőrentey, Dave Love, Sascha L@"{u}decke, Eric Ludlam, Alan Mackenzie, ++Christopher J.@: Madsen, Neil M.@: Mager, Ken Manheimer, Bill Mann, ++Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin, Thomas ++May, Roland McGrath, Will Mengarini, David Megginson, Ben A. Mesander, ++Wayne Mesard, Brad Miller, Lawrence Mitchell, Richard Mlynarik, Gerd ++Moellmann, Stefan Monnier, Morioka Tomohiko, Keith Moore, Glenn ++Morris, Diane Murray, Sen Nagata, Erik Naggum, Thomas Neumann, ++Thien-Thi Nguyen, Mike Newton, Jurgen Nickelsen, Dan Nicolaescu, ++Hrvoje Niksic, Jeff Norden, Andrew Norman, Alexandre Oliva, Bob Olson, ++Michael Olson, Takaaki Ota, Pieter E.@: J.@: Pareit, David Pearson, ++Jeff Peck, Damon Anton Permezel, Tom Perrine, William M.@: Perry, Per ++Persson, Jens Petersen, Daniel Pfeiffer, Richard L.@: Pieri, Fred ++Pierresteguy, Christian Plaunt, David Ponce, Francesco A.@: Potorti, ++Michael D. Prange, Mukesh Prasad, Ken Raeburn, Marko Rahamaa, Ashwin ++Ram, Eric S. Raymond, Paul Reilly, Edward M. Reingold, Alex Rezinsky, ++Rob Riepel, David Reitter, Adrian Robert, Nick Roberts, Roland B.@: ++Roberts, John Robinson, Danny Roozendaal, William Rosenblatt, ++Guillermo J.@: Rozas, Martin Rudalics, Ivar Rummelhoff, Jason Rumney, ++Wolfgang Rupprecht, Kevin Ryde, James B. Salem, Masahiko Sato, Jorgen ++Schaefer, Holger Schauer, William Schelter, Ralph Schleicher, Gregor ++Schmid, Michael Schmidt, Ronald S. Schnell, Philippe Schnoebelen, Jan ++Schormann, Alex Schroeder, Stephen Schoef, Raymond Scholz, Andreas ++Schwab, Randal Schwartz, Oliver Seidel, Manuel Serrano, Hovav Shacham, ++Stanislav Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Espen ++Skoglund, Rick Sladkey, Lynn Slater, Chris Smith, David Smith, Paul ++D.@: Smith, Andre Spiegel, Michael Staats, William Sommerfeld, Michael ++Staats, Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, ++Ken Stevens, Jonathan Stigelman, Martin Stjernholm, Kim F.@: Storm, ++Steve Strassman, Olaf Sylvester, Naoto Takahashi, Steven Tamm, ++Jean-Philippe Theberge, Jens T.@: Berger Thielemann, Spencer Thomas, ++Jim Thompson, Luc Teirlinck, Tom Tromey, Enami Tsugutomo, Eli ++Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh Vaidheeswarran, Neil ++W.@: Van Dyke, Didier Verna, Ulrik Vieth, Geoffrey Voelker, Johan ++Vromans, Inge Wallin, John Paul Wallington, Colin Walters, Barry ++Warsaw, Morten Welinder, Joseph Brian Wells, Rodney Whitby, John ++Wiegley, Ed Wilkinson, Mike Williams, Bill Wohler, Steven A. Wood, ++Dale R.@: Worley, Francis J.@: Wright, Felix S. T. Wu, Tom Wurgler, ++Katsumi Yamaoka, Yamamoto Mitsuharu, Masatake Yamato, Jonathan Yavner, ++Ryan Yeske, Ilya Zakharevich, Milan Zamazal, Victor Zandy, Eli ++Zaretskii, Jamie Zawinski, Shenghuo Zhu, Ian T.@: Zimmermann, Reto ++Zimmermann, Neal Ziring, Teodor Zlatanov, and Detlev Zundel. ++@end iftex ++ ++@node Intro, Glossary, Distrib, Top ++@unnumbered Introduction ++ ++ You are reading about GNU Emacs, the GNU incarnation of the ++advanced, self-documenting, customizable, extensible editor Emacs. ++(The `G' in `GNU' is not silent.) ++ ++ We call Emacs @dfn{advanced} because it can do much more than simple ++insertion and deletion of text. It can control subprocesses, indent ++programs automatically, show multiple files at once, and more. ++Emacs editing commands operate in terms of characters, words, lines, ++sentences, paragraphs, and pages, as well as expressions and comments ++in various programming languages. ++ ++ @dfn{Self-documenting} means that at any time you can use special ++commands, known as @dfn{help commands}, to find out what your options ++are, or to find out what any command does, or to find all the ++commands that pertain to a given topic. @xref{Help}. ++ ++ @dfn{Customizable} means that you can easily alter the behavior of ++Emacs commands in simple ways. For instance, if you use a programming ++language in which comments start with @samp{<**} and end with ++@samp{**>}, you can tell the Emacs comment manipulation commands to ++use those strings (@pxref{Comments}). To take another example, you ++can rebind the basic cursor motion commands (up, down, left and right) ++to any keys on the keyboard that you find comfortable. ++@xref{Customization}. ++ ++ @dfn{Extensible} means that you can go beyond simple customization ++and create entirely new commands. New commands are simply programs ++written in the Lisp language, which are run by Emacs's own Lisp ++interpreter. Existing commands can even be redefined in the middle of ++an editing session, without having to restart Emacs. Most of the ++editing commands in Emacs are written in Lisp; the few exceptions ++could have been written in Lisp but use C instead for efficiency. ++Writing an extension is programming, but non-programmers can use it ++afterwards. @xref{Top, Emacs Lisp Intro, Preface, eintr, An ++Introduction to Programming in Emacs Lisp}, if you want to learn Emacs ++Lisp programming. ++ ++@include screen.texi ++@include commands.texi ++@include entering.texi ++@include basic.texi ++@include mini.texi ++@include m-x.texi ++@include help.texi ++@include mark.texi ++@include killing.texi ++@include regs.texi ++@include display.texi ++@include search.texi ++@include fixit.texi ++@include kmacro.texi ++@c Includes arevert-xtra. ++@include files.texi ++@include buffers.texi ++@include windows.texi ++@include frames.texi ++@include mule.texi ++@include major.texi ++@include indent.texi ++@include text.texi ++@c Includes fortran-xtra. ++@include programs.texi ++@include building.texi ++@c Includes vc1-xtra, emerge-xtra. ++@include maintaining.texi ++@include abbrevs.texi ++@ifnottex ++@include picture-xtra.texi ++@end ifnottex ++@include sending.texi ++@include rmail.texi ++@c Includes dired-xtra. ++@include dired.texi ++@c Includes cal-xtra. ++@include calendar.texi ++@include misc.texi ++@include custom.texi ++@include trouble.texi ++ ++@node Copying, GNU Free Documentation License, Service, Top ++@appendix GNU GENERAL PUBLIC LICENSE ++@include gpl.texi ++ ++@node GNU Free Documentation License, Emacs Invocation, Copying, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@include cmdargs.texi ++@include xresources.texi ++ ++@include anti.texi ++@include macos.texi ++@c Includes msdog-xtra. ++@include msdog.texi ++@include gnu.texi ++@include glossary.texi ++@ifnottex ++@include ack.texi ++@end ifnottex ++ ++@c The Option Index is produced only in the on-line version, ++@c because the index entries related to command-line options ++@c tend to point to the same pages and all begin with a dash. ++@c This, and the need to keep the node links consistent, are ++@c the reasons for the funky @iftex/@ifnottex dance below. ++@c The Option Index is _not_ before Key Index, because that ++@c would require changes in the glossary.texi's @node line. ++@c It is not after Concept Index for similar reasons. ++ ++@iftex ++@node Key Index, Command Index, Glossary, Top ++@unnumbered Key (Character) Index ++@printindex ky ++@end iftex ++ ++@ifnottex ++@node Key Index, Option Index, Glossary, Top ++@unnumbered Key (Character) Index ++@printindex ky ++ ++@node Option Index, Command Index, Key Index, Top ++@unnumbered Command-Line Options Index ++@printindex op ++ ++@node Command Index, Variable Index, Option Index, Top ++@unnumbered Command and Function Index ++@printindex fn ++@end ifnottex ++ ++@iftex ++@node Command Index, Variable Index, Key Index, Top ++@unnumbered Command and Function Index ++@printindex fn ++@end iftex ++ ++@node Variable Index, Concept Index, Command Index, Top ++@unnumbered Variable Index ++@printindex vr ++ ++@node Concept Index, Acknowledgments, Variable Index, Top ++@unnumbered Concept Index ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: ed48740a-410b-46ea-9387-c9a9252a3392 ++@end ignore +diff --git a/doc/emacs/emerge-xtra.texi b/doc/emacs/emerge-xtra.texi +new file mode 100644 +index 0000000..c3b412f +--- /dev/null ++++ b/doc/emacs/emerge-xtra.texi +@@ -0,0 +1,417 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@c This file is included either in emacs-xtra.texi (when producing the ++@c printed version) or in the main Emacs manual (for the on-line version). ++@node Emerge ++@section Merging Files with Emerge ++@cindex Emerge ++@cindex merging files ++ ++ It's not unusual for programmers to get their signals crossed and ++modify the same program in two different directions. To recover from ++this confusion, you need to merge the two versions. Emerge makes this ++easier. For other ways to compare files, see ++@iftex ++@ref{Comparing Files,,, emacs, the Emacs Manual}, ++@end iftex ++@ifnottex ++@ref{Comparing Files}, ++@end ifnottex ++and @ref{Top, Ediff,, ediff, The Ediff Manual}. ++ ++@menu ++* Overview of Emerge:: How to start Emerge. Basic concepts. ++* Submodes of Emerge:: Fast mode vs. Edit mode. ++ Skip Prefers mode and Auto Advance mode. ++* State of Difference:: You do the merge by specifying state A or B ++ for each difference. ++* Merge Commands:: Commands for selecting a difference, ++ changing states of differences, etc. ++* Exiting Emerge:: What to do when you've finished the merge. ++* Combining in Emerge:: How to keep both alternatives for a difference. ++* Fine Points of Emerge:: Miscellaneous issues. ++@end menu ++ ++@node Overview of Emerge ++@subsection Overview of Emerge ++ ++ To start Emerge, run one of these four commands: ++ ++@table @kbd ++@item M-x emerge-files ++@findex emerge-files ++Merge two specified files. ++ ++@item M-x emerge-files-with-ancestor ++@findex emerge-files-with-ancestor ++Merge two specified files, with reference to a common ancestor. ++ ++@item M-x emerge-buffers ++@findex emerge-buffers ++Merge two buffers. ++ ++@item M-x emerge-buffers-with-ancestor ++@findex emerge-buffers-with-ancestor ++Merge two buffers with reference to a common ancestor in a third ++buffer. ++@end table ++ ++@cindex merge buffer (Emerge) ++@cindex A and B buffers (Emerge) ++ The Emerge commands compare two files or buffers, and display the ++comparison in three buffers: one for each input text (the @dfn{A buffer} ++and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging ++takes place. The merge buffer shows the full merged text, not just the ++differences. Wherever the two input texts differ, you can choose which ++one of them to include in the merge buffer. ++ ++ The Emerge commands that take input from existing buffers use only ++the accessible portions of those buffers, if they are narrowed. ++@iftex ++@xref{Narrowing,,, emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++@xref{Narrowing}. ++@end ifnottex ++ ++ ++ If a common ancestor version is available, from which the two texts to ++be merged were both derived, Emerge can use it to guess which ++alternative is right. Wherever one current version agrees with the ++ancestor, Emerge presumes that the other current version is a deliberate ++change which should be kept in the merged version. Use the ++@samp{with-ancestor} commands if you want to specify a common ancestor ++text. These commands read three file or buffer names---variant A, ++variant B, and the common ancestor. ++ ++ After the comparison is done and the buffers are prepared, the ++interactive merging starts. You control the merging by typing special ++@dfn{merge commands} in the merge buffer (@pxref{Merge Commands}). ++For each run of differences between the input texts, you can choose ++which one of them to keep, or edit them both together. ++ ++ The merge buffer uses a special major mode, Emerge mode, with commands ++for making these choices. But you can also edit the buffer with ++ordinary Emacs commands. ++ ++ At any given time, the attention of Emerge is focused on one ++particular difference, called the @dfn{selected} difference. This ++difference is marked off in the three buffers like this: ++ ++@example ++vvvvvvvvvvvvvvvvvvvv ++@var{text that differs} ++^^^^^^^^^^^^^^^^^^^^ ++@end example ++ ++@noindent ++Emerge numbers all the differences sequentially and the mode ++line always shows the number of the selected difference. ++ ++ Normally, the merge buffer starts out with the A version of the text. ++But when the A version of a difference agrees with the common ancestor, ++then the B version is initially preferred for that difference. ++ ++ Emerge leaves the merged text in the merge buffer when you exit. At ++that point, you can save it in a file with @kbd{C-x C-w}. If you give a ++numeric argument to @code{emerge-files} or ++@code{emerge-files-with-ancestor}, it reads the name of the output file ++using the minibuffer. (This is the last file name those commands read.) ++Then exiting from Emerge saves the merged text in the output file. ++ ++ Normally, Emerge commands save the output buffer in its file when you ++exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not ++save the output buffer, but you can save it yourself if you wish. ++ ++@node Submodes of Emerge ++@subsection Submodes of Emerge ++ ++ You can choose between two modes for giving merge commands: Fast mode ++and Edit mode. In Fast mode, basic merge commands are single ++characters, but ordinary Emacs commands are disabled. This is ++convenient if you use only merge commands. In Edit mode, all merge ++commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs ++commands are also available. This allows editing the merge buffer, but ++slows down Emerge operations. ++ ++ Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to ++Fast mode. The mode line indicates Edit and Fast modes with @samp{E} ++and @samp{F}. ++ ++ Emerge has two additional submodes that affect how particular merge ++commands work: Auto Advance mode and Skip Prefers mode. ++ ++ If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands ++advance to the next difference. This lets you go through the merge ++faster as long as you simply choose one of the alternatives from the ++input. The mode line indicates Auto Advance mode with @samp{A}. ++ ++ If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands ++skip over differences in states ``prefer-A'' and ``prefer-B'' ++(@pxref{State of Difference}). Thus you see only differences for ++which neither version is presumed ``correct.'' The mode line ++indicates Skip Prefers mode with @samp{S}. This mode is only relevant ++when there is an ancestor. ++ ++@findex emerge-auto-advance-mode ++@findex emerge-skip-prefers-mode ++ Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or ++clear Auto Advance mode. Use @kbd{s s} ++(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. ++These commands turn on the mode with a positive argument, turn it off ++with a negative or zero argument, and toggle the mode with no argument. ++ ++@node State of Difference ++@subsection State of a Difference ++ ++ In the merge buffer, a difference is marked with lines of @samp{v} and ++@samp{^} characters. Each difference has one of these seven states: ++ ++@table @asis ++@item A ++The difference is showing the A version. The @kbd{a} command always ++produces this state; the mode line indicates it with @samp{A}. ++ ++@item B ++The difference is showing the B version. The @kbd{b} command always ++produces this state; the mode line indicates it with @samp{B}. ++ ++@item default-A ++@itemx default-B ++The difference is showing the A or the B state by default, because you ++haven't made a choice. All differences start in the default-A state ++(and thus the merge buffer is a copy of the A buffer), except those for ++which one alternative is ``preferred'' (see below). ++ ++When you select a difference, its state changes from default-A or ++default-B to plain A or B. Thus, the selected difference never has ++state default-A or default-B, and these states are never displayed in ++the mode line. ++ ++The command @kbd{d a} chooses default-A as the default state, and @kbd{d ++b} chooses default-B. This chosen default applies to all differences ++that you have never selected and for which no alternative is preferred. ++If you are moving through the merge sequentially, the differences you ++haven't selected are those following the selected one. Thus, while ++moving sequentially, you can effectively make the A version the default ++for some sections of the merge buffer and the B version the default for ++others by using @kbd{d a} and @kbd{d b} between sections. ++ ++@item prefer-A ++@itemx prefer-B ++The difference is showing the A or B state because it is ++@dfn{preferred}. This means that you haven't made an explicit choice, ++but one alternative seems likely to be right because the other ++alternative agrees with the common ancestor. Thus, where the A buffer ++agrees with the common ancestor, the B version is preferred, because ++chances are it is the one that was actually changed. ++ ++These two states are displayed in the mode line as @samp{A*} and @samp{B*}. ++ ++@item combined ++The difference is showing a combination of the A and B states, as a ++result of the @kbd{x c} or @kbd{x C} commands. ++ ++Once a difference is in this state, the @kbd{a} and @kbd{b} commands ++don't do anything to it unless you give them a numeric argument. ++ ++The mode line displays this state as @samp{comb}. ++@end table ++ ++@node Merge Commands ++@subsection Merge Commands ++ ++ Here are the Merge commands for Fast mode; in Edit mode, precede them ++with @kbd{C-c C-c}: ++ ++@table @kbd ++@item p ++Select the previous difference. ++ ++@item n ++Select the next difference. ++ ++@item a ++Choose the A version of this difference. ++ ++@item b ++Choose the B version of this difference. ++ ++@item C-u @var{n} j ++Select difference number @var{n}. ++ ++@item . ++Select the difference containing point. ++@c [Does not work in the A or B buffer?] ++@c You can use this command in the merge buffer or in the A or B buffer. ++ ++@item q ++Quit---finish the merge. ++ ++@item C-] ++Abort---exit merging and do not save the output. ++ ++@item f ++Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) ++ ++@item e ++Go into Edit mode. ++ ++@item l ++Recenter (like @kbd{C-l}) all three windows. With an argument, ++reestablish the default three-window display. ++ ++@item - ++Specify part of a prefix numeric argument. ++ ++@item @var{digit} ++Also specify part of a prefix numeric argument. ++ ++@item d a ++Choose the A version as the default from here down in ++the merge buffer. ++ ++@item d b ++Choose the B version as the default from here down in ++the merge buffer. ++ ++@item c a ++Copy the A version of this difference into the kill ring. ++ ++@item c b ++Copy the B version of this difference into the kill ring. ++ ++@item i a ++Insert the A version of this difference at point. ++ ++@item i b ++Insert the B version of this difference at point. ++ ++@item m ++Put point and mark around the difference. ++ ++@item ^ ++Scroll all three windows down (like @kbd{M-v}). ++ ++@item v ++Scroll all three windows up (like @kbd{C-v}). ++ ++@item < ++Scroll all three windows left (like @kbd{C-x <}). ++ ++@item > ++Scroll all three windows right (like @kbd{C-x >}). ++ ++@item | ++Reset horizontal scroll on all three windows. ++ ++@item x 1 ++Shrink the merge window to one line. (Use @kbd{C-u l} to restore it ++to full size.) ++ ++@item x c ++Combine the two versions of this difference (@pxref{Combining in ++Emerge}). ++ ++@item x f ++Show the names of the files/buffers Emerge is operating on, in a Help ++window. (Use @kbd{C-u l} to restore windows.) ++ ++@item x j ++Join this difference with the following one. ++(@kbd{C-u x j} joins this difference with the previous one.) ++ ++@item x s ++Split this difference into two differences. Before you use this ++command, position point in each of the three buffers at the place where ++you want to split the difference. ++ ++@item x t ++Trim identical lines off the top and bottom of the difference. ++Such lines occur when the A and B versions are ++identical but differ from the ancestor version. ++@end table ++ ++@node Exiting Emerge ++@subsection Exiting Emerge ++ ++ The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing ++the results into the output file if you specified one. It restores the ++A and B buffers to their proper contents, or kills them if they were ++created by Emerge and you haven't changed them. It also disables the ++Emerge commands in the merge buffer, since executing them later could ++damage the contents of the various buffers. ++ ++ @kbd{C-]} aborts the merge. This means exiting without writing the ++output file. If you didn't specify an output file, then there is no ++real difference between aborting and finishing the merge. ++ ++ If the Emerge command was called from another Lisp program, then its ++return value is @code{t} for successful completion, or @code{nil} if you ++abort. ++ ++@node Combining in Emerge ++@subsection Combining the Two Versions ++ ++ Sometimes you want to keep @emph{both} alternatives for a particular ++difference. To do this, use @kbd{x c}, which edits the merge buffer ++like this: ++ ++@example ++@group ++#ifdef NEW ++@var{version from A buffer} ++#else /* not NEW */ ++@var{version from B buffer} ++#endif /* not NEW */ ++@end group ++@end example ++ ++@noindent ++@vindex emerge-combine-versions-template ++While this example shows C preprocessor conditionals delimiting the two ++alternative versions, you can specify the strings to use by setting ++the variable @code{emerge-combine-versions-template} to a string of your ++choice. In the string, @samp{%a} says where to put version A, and ++@samp{%b} says where to put version B. The default setting, which ++produces the results shown above, looks like this: ++ ++@example ++@group ++"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" ++@end group ++@end example ++ ++@node Fine Points of Emerge ++@subsection Fine Points of Emerge ++ ++ During the merge, you mustn't try to edit the A and B buffers yourself. ++Emerge modifies them temporarily, but ultimately puts them back the way ++they were. ++ ++ You can have any number of merges going at once---just don't use any one ++buffer as input to more than one merge at once, since the temporary ++changes made in these buffers would get in each other's way. ++ ++ Starting Emerge can take a long time because it needs to compare the ++files fully. Emacs can't do anything else until @code{diff} finishes. ++Perhaps in the future someone will change Emerge to do the comparison in ++the background when the input files are large---then you could keep on ++doing other things with Emacs until Emerge is ready to accept ++commands. ++ ++@vindex emerge-startup-hook ++ After setting up the merge, Emerge runs the hook ++@code{emerge-startup-hook}. ++@iftex ++@xref{Hooks,,, emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++@xref{Hooks}. ++@end ifnottex ++ ++@ignore ++ arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e ++@end ignore +diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi +new file mode 100644 +index 0000000..d7ebb39 +--- /dev/null ++++ b/doc/emacs/entering.texi +@@ -0,0 +1,190 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 2001, 2002, 2003, ++@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@iftex ++@chapter Entering and Exiting Emacs ++ ++ This chapter explains how to enter Emacs, and how to exit it. ++@end iftex ++ ++@ifnottex ++@raisesections ++@end ifnottex ++ ++@node Entering Emacs, Exiting, Commands, Top ++@section Entering Emacs ++@cindex entering Emacs ++@cindex starting Emacs ++ ++ The usual way to invoke Emacs is with the shell command ++@command{emacs}. From a terminal window running in the X Window ++System, you can also run Emacs in the background with ++@command{emacs&}; this way, Emacs won't tie up the terminal window, so ++you can use it to run other shell commands. ++ ++@cindex startup screen ++ When Emacs starts up, the initial frame displays a special buffer ++named @samp{*GNU Emacs*}. This buffer contains some information about ++Emacs, and includes @dfn{links} to common tasks that might be useful ++to beginning users. For instance, activating the @samp{Emacs ++Tutorial} link opens the Emacs tutorial; this does the same thing as ++the command @kbd{C-h t} (@code{help-with-tutorial}). To activate a ++link, either move point onto it and type @kbd{@key{RET}}, or click on ++it with @kbd{mouse-1} (the left mouse button). ++ ++ Using a command line argument, you can tell Emacs to visit one or ++more specific files as soon as it starts up. For example, ++@command{emacs foo.txt} starts Emacs with a buffer displaying the ++contents of the file @samp{foo.txt}. This feature exists mainly for ++compatibility with other editors, which are designed to edit one file ++at a time: once you are done with that file, you exit the editor, and ++start it again the next time you need it. ++ ++ Using Emacs in this way---starting it afresh each time you want to ++edit a file---is unnecessary and wasteful. Emacs can visit more than ++one file in a single editing session, and exiting the Emacs session ++loses valuable accumulated context, such as the kill ring, registers, ++undo history, and mark ring. These features, described later in the ++manual, are useful for performing edits across multiple files, or ++continuing edits to a single file. ++ ++ The recommended way to use Emacs is to start it only once, just ++after you log in, and do all your editing in the same Emacs session. ++Each time you edit a file, visit it with the existing Emacs, which ++eventually has many files in it ready for editing. @xref{Files}, for ++more information on visiting more than one file. ++ ++ To edit a file from another program while Emacs is running, you can ++use the @command{emacsclient} helper program to open a file in the ++already running Emacs. @xref{Emacs Server}. ++ ++ Emacs accepts other command line arguments that tell it to load ++certain Lisp files, call certain functions, and so forth. These ++features exist mainly for advanced users. @xref{Emacs Invocation}. ++ ++@vindex inhibit-startup-screen ++ If the variable @code{inhibit-startup-screen} is non-@code{nil}, ++Emacs does not display the startup screen. In that case, if one or ++more files were specified on the command line, Emacs simply displays ++those files; otherwise, it displays a buffer named @samp{*scratch*}, ++which can be used to evaluate Emacs Lisp expressions interactively. ++@xref{Lisp Interaction}. You can set the variable ++@code{inhibit-startup-screen} using the Customize facility ++(@pxref{Easy Customization}), or by editing your initialization file ++(@pxref{Init File}).@footnote{Note that setting ++@code{inhibit-startup-screen} in @file{site-start.el} doesn't work, ++because the startup screen is set up before reading ++@file{site-start.el}. @xref{Init File}, for information about ++@file{site-start.el}.} ++ ++ You can also force Emacs to display a file or directory at startup ++by setting the variable @code{initial-buffer-choice} to a ++non-@code{nil} value. (In that case, even if you specify one or more ++files on the command line, Emacs opens but does not display them.) ++The value of @code{initial-buffer-choice} can be either the name of ++the desired file or directory, or @code{t}, which means to display the ++@samp{*scratch*} buffer. ++ ++@node Exiting, Basic, Entering Emacs, Top ++@section Exiting Emacs ++@cindex exiting ++@cindex killing Emacs ++@cindex leaving Emacs ++@cindex quitting Emacs ++ ++@table @kbd ++@item C-x C-c ++Kill Emacs (@code{save-buffers-kill-terminal}). ++@item C-z ++On a text terminal, suspend Emacs (@code{suspend-emacs}); on a ++graphical display, iconify (or ``minimize'') the selected frame ++(@code{iconify-or-deiconify-frame}). ++@end table ++ ++@kindex C-x C-c ++@findex save-buffers-kill-terminal ++ @dfn{Killing} Emacs means terminating the Emacs program. To do ++this, type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}). A ++two-character key is used to make it harder to type by accident. If ++there are any modified file-visiting buffers when you type @kbd{C-x ++C-c}, Emacs first offers to save these buffers. If you do not save ++them all, it asks for confirmation again, since the unsaved changes ++will be lost. Emacs also asks for confirmation if any subprocesses ++are still running, since killing Emacs will also kill the subprocesses ++(@pxref{Shell}). ++ ++ @kbd{C-x C-c} behaves specially if you are using Emacs as a server. ++If you type it from a ``client frame'', it closes the client ++connection. @xref{Emacs Server}. ++ ++ Emacs can, optionally, record certain session information when you ++kill it, such as the files you were visiting at the time. This ++information is then available the next time you start Emacs. ++@xref{Saving Emacs Sessions}. ++ ++@vindex confirm-kill-emacs ++ If the value of the variable @code{confirm-kill-emacs} is ++non-@code{nil}, @kbd{C-x C-c} assumes that its value is a predicate ++function, and calls that function. If the result of the function call ++is non-@code{nil}, the session is killed, otherwise Emacs continues to ++run. One convenient function to use as the value of ++@code{confirm-kill-emacs} is the function @code{yes-or-no-p}. The ++default value of @code{confirm-kill-emacs} is @code{nil}. ++ ++@findex kill-emacs ++ To kill Emacs without being prompted about saving, type @kbd{M-x ++kill-emacs}. ++ ++@cindex minimizing a frame ++@cindex iconifying ++@cindex suspending ++ You can ``exit'' Emacs in two other ways. On a graphical display, ++you can @dfn{iconify} (or @dfn{minimize}) an Emacs frame; depending on ++the window system, this either replaces the Emacs frame with a tiny ++``icon'' or conceals the frame entirely (@pxref{Frames}). On a ++text-only terminal, you can @dfn{suspend} Emacs; this means stopping ++the Emacs program temporarily, returning control to its parent process ++(usually a shell). ++ ++@kindex C-z ++@findex iconify-or-deiconify-frame ++@findex suspend-emacs ++ On a graphical display, @kbd{C-z} runs the command ++@code{iconify-or-deiconify-frame}, which iconifies the selected Emacs ++frame. On a text terminal, @kbd{C-z} runs the command ++@code{suspend-emacs}, which suspends Emacs. ++ ++ After iconifying or suspending Emacs, you can return to it and ++continue editing wherever you left off. The way to do this depends on ++the window system or shell. In most common shells, you can resume ++Emacs after suspending it with the shell command @command{%emacs}. ++ ++@vindex cannot-suspend ++ On very old systems that don't support suspending programs, ++@kbd{C-z} starts an inferior shell that communicates directly with the ++terminal, and Emacs waits until you exit the subshell. (The way to ++exit the subshell is usually @kbd{C-d} or @command{exit}.) On these ++systems, you can only get back to the shell from which Emacs was run ++(to log out, for example) when you kill Emacs. Suspending can also ++fail if you run Emacs under a shell that doesn't support suspending ++jobs, even if the system itself does support it. In this case, you ++can set the variable @code{cannot-suspend} to a non-@code{nil} value ++to force @kbd{C-z} to start an inferior shell. ++ ++ Text-only terminals usually listen for certain special characters ++whose meaning is to kill or suspend the program you are running. ++@b{This terminal feature is turned off while you are in Emacs.} The ++meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were inspired ++by the use of @kbd{C-z} and @kbd{C-c} on several operating systems as ++the characters for stopping or killing a program, but that is their ++only relationship with the operating system. You can customize these ++keys to run any commands of your choice (@pxref{Keymaps}). ++ ++@ifnottex ++@lowersections ++@end ifnottex ++ ++@ignore ++ arch-tag: df798d8b-f253-4113-b585-f528f078a944 ++@end ignore +diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi +new file mode 100644 +index 0000000..54060b4 +--- /dev/null ++++ b/doc/emacs/files.texi +@@ -0,0 +1,1973 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, ++@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Files, Buffers, Keyboard Macros, Top ++@chapter File Handling ++@cindex files ++ ++ The operating system stores data permanently in named @dfn{files}, so ++most of the text you edit with Emacs comes from a file and is ultimately ++stored in a file. ++ ++ To edit a file, you must tell Emacs to read the file and prepare a ++buffer containing a copy of the file's text. This is called ++@dfn{visiting} the file. Editing commands apply directly to text in the ++buffer; that is, to the copy inside Emacs. Your changes appear in the ++file itself only when you @dfn{save} the buffer back into the file. ++ ++ In addition to visiting and saving files, Emacs can delete, copy, ++rename, and append to files, keep multiple versions of them, and operate ++on file directories. ++ ++@menu ++* File Names:: How to type and edit file-name arguments. ++* Visiting:: Visiting a file prepares Emacs to edit the file. ++* Saving:: Saving makes your changes permanent. ++* Reverting:: Reverting cancels all the changes not saved. ++@ifnottex ++* Autorevert:: Auto Reverting non-file buffers. ++@end ifnottex ++* Auto Save:: Auto Save periodically protects against loss of data. ++* File Aliases:: Handling multiple names for one file. ++* Directories:: Creating, deleting, and listing file directories. ++* Comparing Files:: Finding where two files differ. ++* Diff Mode:: Mode for editing file differences. ++* Misc File Ops:: Other things you can do on files. ++* Compressed Files:: Accessing compressed files. ++* File Archives:: Operating on tar, zip, jar etc. archive files. ++* Remote Files:: Accessing files on other sites. ++* Quoted File Names:: Quoting special characters in file names. ++* File Name Cache:: Completion against a list of files you often use. ++* File Conveniences:: Convenience Features for Finding Files. ++* Filesets:: Handling sets of files. ++@end menu ++ ++@node File Names ++@section File Names ++@cindex file names ++ ++ Many Emacs commands that operate on a file require you to specify ++the file name, using the minibuffer (@pxref{Minibuffer}). You can use ++@dfn{completion} to specify long file names (@pxref{Completion}). ++Note that file name completion ignores file names whose extensions ++appear in the variable @code{completion-ignored-extensions} ++(@pxref{Completion Options}). ++ ++ For most operations, there is a @dfn{default file name} which is ++used if you type just @key{RET} to enter an empty argument. Normally, ++the default file name is the name of the file visited in the current ++buffer. ++ ++@vindex default-directory ++@vindex insert-default-directory ++ Each buffer has a @dfn{default directory} which is normally the same ++as the directory of the file visited in that buffer. For example, if ++the default file name is @file{/u/rms/gnu/gnu.tasks}, the default ++directory is normally @file{/u/rms/gnu/}. The default directory is ++kept in the variable @code{default-directory}, which has a separate ++value in every buffer. When a command reads a file name using the ++minibuffer, the default directory usually serves as the initial ++contents of the minibuffer. To inhibit the insertion of the default ++directory, set the variable @code{insert-default-directory} to ++@code{nil}. ++ ++ If you enter a file name without a directory, that specifies a file ++in the default directory. If you specify a directory in a relative ++fashion, with a name that does not start with a slash, it is ++interpreted with respect to the default directory. For example, ++suppose the default directory is @file{/u/rms/gnu/}. Entering just ++@samp{foo} in the minibuffer, with a directory omitted, specifies the ++file @file{/u/rms/gnu/foo}; entering @samp{../.login} specifies ++@file{/u/rms/.login}; and entering @samp{new/foo} specifies ++@file{/u/rms/gnu/new/foo}. ++ ++ When typing a file name into the minibuffer, you can make use of a ++couple of shortcuts: a double slash is interpreted as ``ignore ++everything before the second slash in the pair,'' and @samp{~/} is ++interpreted as your home directory. @xref{Minibuffer File}, for more ++information about these shortcuts. ++ ++@findex cd ++@findex pwd ++ The command @kbd{M-x pwd} displays the default directory, and the ++command @kbd{M-x cd} sets it to a value read using the minibuffer. A ++buffer's default directory changes only when the @code{cd} command is ++used. A file-visiting buffer's default directory is initialized to ++the directory of the file it visits. If you create a buffer with ++@kbd{C-x b}, its default directory is copied from that of the buffer ++that was current at the time (@pxref{Select Buffer}). ++ ++@cindex environment variables in file names ++@cindex expansion of environment variables ++@cindex @code{$} in file names ++ @anchor{File Names with $}The character @samp{$} is used to ++substitute an environment variable into a file name. The name of the ++environment variable consists of all the alphanumeric characters after ++the @samp{$}; alternatively, it can be enclosed in braces after the ++@samp{$}. For example, if you have used the shell command ++@command{export FOO=rms/hacks} to set up an environment variable named ++@env{FOO}, then both @file{/u/$FOO/test.c} and ++@file{/u/$@{FOO@}/test.c} are abbreviations for ++@file{/u/rms/hacks/test.c}. If the environment variable is not ++defined, no substitution occurs, so that the character @samp{$} stands ++for itself. ++ ++ Note that environment variables affect Emacs only if they are ++applied before Emacs is started. ++ ++ To access a file with @samp{$} in its name, if the @samp{$} causes ++expansion, type @samp{$$}. This pair is converted to a single ++@samp{$} at the same time that variable substitution is performed for ++a single @samp{$}. Alternatively, quote the whole file name with ++@samp{/:} (@pxref{Quoted File Names}). File names which begin with a ++literal @samp{~} should also be quoted with @samp{/:}. ++ ++ You can include non-@acronym{ASCII} characters in file names if you set the ++variable @code{file-name-coding-system} to a non-@code{nil} value. ++@xref{File Name Coding}. ++ ++@node Visiting ++@section Visiting Files ++@cindex visiting files ++@cindex open file ++ ++@table @kbd ++@item C-x C-f ++Visit a file (@code{find-file}). ++@item C-x C-r ++Visit a file for viewing, without allowing changes to it ++(@code{find-file-read-only}). ++@item C-x C-v ++Visit a different file instead of the one visited last ++(@code{find-alternate-file}). ++@item C-x 4 f ++Visit a file, in another window (@code{find-file-other-window}). Don't ++alter what is displayed in the selected window. ++@item C-x 5 f ++Visit a file, in a new frame (@code{find-file-other-frame}). Don't ++alter what is displayed in the selected frame. ++@item M-x find-file-literally ++Visit a file with no conversion of the contents. ++@end table ++ ++@cindex files, visiting and saving ++@cindex saving files ++ @dfn{Visiting} a file means reading its contents into an Emacs ++buffer so you can edit them. Emacs makes a new buffer for each file ++that you visit. ++ ++ Emacs normally constructs the buffer name from the file name, ++omitting the directory name. For example, a file named ++@file{/usr/rms/emacs.tex} is visited in a buffer named ++@samp{emacs.tex}. If there is already a buffer with that name, Emacs ++constructs a unique name; the normal method is to append @samp{<2>}, ++@samp{<3>}, and so on, but you can select other methods. ++@xref{Uniquify}. ++ ++ Each window's mode line shows the name of the buffer that is being ++displayed in that window, so you can always tell what buffer you are ++editing. @pxref{Mode Line}. ++ ++ The changes you make with editing commands are made in the Emacs ++buffer. They do not take effect in the file that you visited, or any ++permanent place, until you @dfn{save} the buffer (@pxref{Saving}). ++ ++@cindex modified (buffer) ++ If a buffer contains changes that have not been saved, we say the ++buffer is @dfn{modified}. This implies that some changes will be lost ++if the buffer is not saved. The mode line displays two stars near the ++left margin to indicate that the buffer is modified. ++ ++@kindex C-x C-f ++@findex find-file ++ To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the ++minibuffer to enter the name of the desired file. The usual ++defaulting and completion behavior is available in this minibuffer ++(@pxref{Minibuffer File}). Note, also, that completion ignores ++certain file names (@pxref{Completion Options}). While in the ++minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}. ++ ++ Your can tell that @kbd{C-x C-f} has completed successfully by the ++appearance of new text on the screen and a new buffer name in the mode ++line. If the specified file does not exist and you could not create ++it, or exists but you can't read it, an error message is displayed in ++the echo area. ++ ++ If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make ++another copy. It selects the existing buffer containing that file. ++However, before doing so, it checks whether the file itself has changed ++since you visited or saved it last. If the file has changed, Emacs offers ++to reread it. ++ ++@vindex large-file-warning-threshold ++@cindex maximum buffer size exceeded, error message ++ If you try to visit a file larger than ++@code{large-file-warning-threshold} (the default is 10000000, which is ++about 10 megabytes), Emacs asks you for confirmation first. You can ++answer @kbd{y} to proceed with visiting the file. Note, however, that ++Emacs cannot visit files that are larger than the maximum Emacs buffer ++size, which is around 256 megabytes on 32-bit machines ++(@pxref{Buffers}). If you try, Emacs will display an error message ++saying that the maximum buffer size has been exceeded. ++ ++@cindex wildcard characters in file names ++@vindex find-file-wildcards ++ If the file name you specify contains shell-style wildcard ++characters, Emacs visits all the files that match it. (On ++case-insensitive filesystems, Emacs matches the wildcards disregarding ++the letter case.) Wildcards include @samp{?}, @samp{*}, and ++@samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file ++name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted ++File Names}, for information on how to visit a file whose name ++actually contains wildcard characters. You can disable the wildcard ++feature by customizing @code{find-file-wildcards}. ++ ++@cindex file selection dialog ++ On graphical displays, there are two additional methods for visiting ++files. Firstly, when Emacs is built with a suitable GUI toolkit, ++commands invoked with the mouse (by clicking on the menu bar or tool ++bar) use the toolkit's standard ``File Selection'' dialog instead of ++prompting for the file name in the minibuffer. On GNU/Linux and Unix ++platforms, Emacs does this when built with GTK, LessTif, and Motif ++toolkits; on MS-Windows and Mac, the GUI version does that by default. ++For information on how to customize this, see @ref{Dialog Boxes}. ++ ++ Secondly, Emacs supports ``drag and drop'': dropping a file into an ++ordinary Emacs window visits the file using that window. As an ++exception, dropping a file into a window displaying a Dired buffer ++moves or copies the file into the displayed directory. For details, ++see @ref{Drag and Drop}, and @ref{Misc Dired Features}. ++ ++@cindex creating files ++ What if you want to create a new file? Just visit it. Emacs ++displays @samp{(New file)} in the echo area, but in other respects ++behaves as if you had visited an existing empty file. If you make ++changes and save them, the file is created. ++ ++@cindex minibuffer confirmation ++@cindex confirming in the minibuffer ++@vindex confirm-nonexistent-file-or-buffer ++ When @key{TAB} completion results in a nonexistent file name and you ++type @key{RET} immediately to visit it, Emacs asks for confirmation; ++this is because it's possible that you expected completion to go ++further and give you an existing file's name. The string ++@samp{[Confirm]} appears for a short time after the file name to ++indicate the need to confirm in this way. Type @key{RET} to confirm ++and visit the nonexistent file. The variable ++@code{confirm-nonexistent-file-or-buffer} controls whether Emacs asks ++for confirmation before visiting a new file. The default value, ++@code{after-completion}, gives the behavior we have just described. ++If the value is @code{nil}, Emacs never asks for confirmation; for any ++other non-@code{nil} value, Emacs always asks for confirmation. This ++variable also affects the @code{switch-to-buffer} command ++(@pxref{Select Buffer}). @xref{Completion}, for more information ++about completion. ++ ++@kindex C-x C-v ++@findex find-alternate-file ++ If you visit a nonexistent file unintentionally (because you typed ++the wrong file name), type @kbd{C-x C-v} (@code{find-alternate-file}) ++to visit the file you really wanted. @kbd{C-x C-v} is similar to ++@kbd{C-x C-f}, but it kills the current buffer (after first offering ++to save it if it is modified). When @kbd{C-x C-v} reads the file name ++to visit, it inserts the entire default file name in the buffer, with ++point just after the directory part; this is convenient if you made a ++slight error in typing the name. ++ ++@vindex find-file-run-dired ++ If you ``visit'' a file that is actually a directory, Emacs invokes ++Dired, the Emacs directory browser; this lets you ``edit'' the ++contents of the directory. @xref{Dired}. You can disable this ++behavior by setting the variable @code{find-file-run-dired} to ++@code{nil}; in that case, it is an error to try to visit a directory. ++ ++ Files which are actually collections of other files, or @dfn{file ++archives}, are visited in special modes which invoke a Dired-like ++environment to allow operations on archive members. @xref{File ++Archives}, for more about these features. ++ ++ If you visit a file that the operating system won't let you modify, ++or that is marked read-only, Emacs makes the buffer read-only too, so ++that you won't go ahead and make changes that you'll have trouble ++saving afterward. You can make the buffer writable with @kbd{C-x C-q} ++(@code{toggle-read-only}). @xref{Misc Buffer}. ++ ++@kindex C-x C-r ++@findex find-file-read-only ++ If you want to visit a file as read-only in order to protect ++yourself from entering changes accidentally, visit it with the command ++@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. ++ ++@kindex C-x 4 f ++@findex find-file-other-window ++ @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} ++except that the buffer containing the specified file is selected in another ++window. The window that was selected before @kbd{C-x 4 f} continues to ++show the same buffer it was already showing. If this command is used when ++only one window is being displayed, that window is split in two, with one ++window showing the same buffer as before, and the other one showing the ++newly requested file. @xref{Windows}. ++ ++@kindex C-x 5 f ++@findex find-file-other-frame ++ @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a ++new frame, or makes visible any existing frame showing the file you ++seek. This feature is available only when you are using a window ++system. @xref{Frames}. ++ ++ Emacs recognizes from the contents of a file which end-of-line ++convention it uses to separate lines---newline (used on GNU/Linux and ++on Unix), carriage-return linefeed (used on Microsoft systems), or ++just carriage-return (used on the Macintosh)---and automatically ++converts the contents to the normal Emacs convention, which is that ++the newline character separates lines. This is a part of the general ++feature of coding system conversion (@pxref{Coding Systems}), and ++makes it possible to edit files imported from different operating ++systems with equal convenience. If you change the text and save the ++file, Emacs performs the inverse conversion, changing newlines back ++into carriage-return linefeed or just carriage-return if appropriate. ++ ++@findex find-file-literally ++ If you wish to edit a file as a sequence of @acronym{ASCII} ++characters with no special encoding or conversion, use the @kbd{M-x ++find-file-literally} command. This visits a file, like @kbd{C-x C-f}, ++but does not do format conversion (@pxref{Formatted Text}), character ++code conversion (@pxref{Coding Systems}), or automatic uncompression ++(@pxref{Compressed Files}), and does not add a final newline because ++of @code{require-final-newline} (@pxref{Customize Save}). If you have ++already visited the same file in the usual (non-literal) manner, this ++command asks you whether to visit it literally instead. ++ ++@vindex find-file-hook ++@vindex find-file-not-found-functions ++ Two special hook variables allow extensions to modify the operation of ++visiting files. Visiting a file that does not exist runs the functions ++in the list @code{find-file-not-found-functions}; this variable holds a list ++of functions, and the functions are called one by one (with no ++arguments) until one of them returns non-@code{nil}. This is not a ++normal hook, and the name ends in @samp{-functions} rather than @samp{-hook} ++to indicate that fact. ++ ++ Successful visiting of any file, whether existing or not, calls the ++functions in the list @code{find-file-hook}, with no arguments. ++This variable is a normal hook. In the case of a nonexistent file, the ++@code{find-file-not-found-functions} are run first. @xref{Hooks}. ++ ++ There are several ways to specify automatically the major mode for ++editing the file (@pxref{Choosing Modes}), and to specify local ++variables defined for that file (@pxref{File Variables}). ++ ++@node Saving ++@section Saving Files ++ ++ @dfn{Saving} a buffer in Emacs means writing its contents back into the file ++that was visited in the buffer. ++ ++@menu ++* Save Commands:: Commands for saving files. ++* Backup:: How Emacs saves the old version of your file. ++* Customize Save:: Customizing the saving of files. ++* Interlocking:: How Emacs protects against simultaneous editing ++ of one file by two users. ++* Shadowing: File Shadowing. Copying files to "shadows" automatically. ++* Time Stamps:: Emacs can update time stamps on saved files. ++@end menu ++ ++@node Save Commands ++@subsection Commands for Saving Files ++ ++ These are the commands that relate to saving and writing files. ++ ++@table @kbd ++@item C-x C-s ++Save the current buffer in its visited file on disk (@code{save-buffer}). ++@item C-x s ++Save any or all buffers in their visited files (@code{save-some-buffers}). ++@item M-~ ++Forget that the current buffer has been changed (@code{not-modified}). ++With prefix argument (@kbd{C-u}), mark the current buffer as changed. ++@item C-x C-w ++Save the current buffer with a specified file name (@code{write-file}). ++@item M-x set-visited-file-name ++Change the file name under which the current buffer will be saved. ++@end table ++ ++@kindex C-x C-s ++@findex save-buffer ++ When you wish to save the file and make your changes permanent, type ++@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} ++displays a message like this: ++ ++@example ++Wrote /u/rms/gnu/gnu.tasks ++@end example ++ ++@noindent ++If the selected buffer is not modified (no changes have been made in it ++since the buffer was created or last saved), saving is not really done, ++because it would have no effect. Instead, @kbd{C-x C-s} displays a message ++like this in the echo area: ++ ++@example ++(No changes need to be saved) ++@end example ++ ++With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer ++to be backed up when the next save is done. @xref{Backup}. ++ ++@kindex C-x s ++@findex save-some-buffers ++ The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any ++or all modified buffers. It asks you what to do with each buffer. The ++possible responses are analogous to those of @code{query-replace}: ++ ++@table @kbd ++@item y ++Save this buffer and ask about the rest of the buffers. ++@item n ++Don't save this buffer, but ask about the rest of the buffers. ++@item ! ++Save this buffer and all the rest with no more questions. ++@c following generates acceptable underfull hbox ++@item @key{RET} ++Terminate @code{save-some-buffers} without any more saving. ++@item . ++Save this buffer, then exit @code{save-some-buffers} without even asking ++about other buffers. ++@item C-r ++View the buffer that you are currently being asked about. When you exit ++View mode, you get back to @code{save-some-buffers}, which asks the ++question again. ++@item d ++Diff the buffer against its corresponding file, so you can see what ++changes you would be saving. This calls the command ++@code{diff-buffer-with-file} (@pxref{Comparing Files}). ++@item C-h ++Display a help message about these options. ++@end table ++ ++ @kbd{C-x C-c}, the key sequence to exit Emacs, invokes ++@code{save-some-buffers} and therefore asks the same questions. ++ ++@kindex M-~ ++@findex not-modified ++ If you have changed a buffer but do not wish to save the changes, ++you should take some action to prevent it. Otherwise, each time you ++use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer ++by mistake. One thing you can do is type @kbd{M-~} ++(@code{not-modified}), which clears out the indication that the buffer ++is modified. If you do this, none of the save commands will believe ++that the buffer needs to be saved. (@samp{~} is often used as a ++mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.) ++Alternatively, you can cancel all the changes made since the file was ++visited or saved, by reading the text from the file again. This is ++called @dfn{reverting}. @xref{Reverting}. (You could also undo all ++the changes by repeating the undo command @kbd{C-x u} until you have ++undone all the changes; but reverting is easier.) ++ ++@findex set-visited-file-name ++ @kbd{M-x set-visited-file-name} alters the name of the file that the ++current buffer is visiting. It reads the new file name using the ++minibuffer. Then it marks the buffer as visiting that file name, and ++changes the buffer name correspondingly. @code{set-visited-file-name} ++does not save the buffer in the newly visited file; it just alters the ++records inside Emacs in case you do save later. It also marks the ++buffer as ``modified'' so that @kbd{C-x C-s} in that buffer ++@emph{will} save. ++ ++@kindex C-x C-w ++@findex write-file ++ If you wish to mark the buffer as visiting a different file and save ++it right away, use @kbd{C-x C-w} (@code{write-file}). This is ++equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}, ++except that @kbd{C-x C-w} asks for confirmation if the file exists. ++@kbd{C-x C-s} used on a buffer that is not visiting a file has the ++same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the ++buffer as visiting that file, and saves it there. The default file ++name in a buffer that is not visiting a file is made by combining the ++buffer name with the buffer's default directory (@pxref{File Names}). ++ ++ If the new file name implies a major mode, then @kbd{C-x C-w} switches ++to that major mode, in most cases. The command ++@code{set-visited-file-name} also does this. @xref{Choosing Modes}. ++ ++ If Emacs is about to save a file and sees that the date of the latest ++version on disk does not match what Emacs last read or wrote, Emacs ++notifies you of this fact, because it probably indicates a problem caused ++by simultaneous editing and requires your immediate attention. ++@xref{Interlocking,, Simultaneous Editing}. ++ ++@node Backup ++@subsection Backup Files ++@cindex backup file ++@vindex make-backup-files ++@vindex vc-make-backup-files ++ ++ On most operating systems, rewriting a file automatically destroys all ++record of what the file used to contain. Thus, saving a file from Emacs ++throws away the old contents of the file---or it would, except that ++Emacs carefully copies the old contents to another file, called the ++@dfn{backup} file, before actually saving. ++ ++ Emacs makes a backup for a file only the first time the file is ++saved from a buffer. No matter how many times you subsequently save ++the file, its backup remains unchanged. However, if you kill the ++buffer and then visit the file again, a new backup file will be made. ++ ++ For most files, the variable @code{make-backup-files} determines ++whether to make backup files. On most operating systems, its default ++value is @code{t}, so that Emacs does write backup files. ++ ++ For files managed by a version control system (@pxref{Version ++Control}), the variable @code{vc-make-backup-files} determines whether ++to make backup files. By default it is @code{nil}, since backup files ++are redundant when you store all the previous versions in a version ++control system. ++@iftex ++@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. ++@end iftex ++@ifnottex ++@xref{General VC Options}. ++@end ifnottex ++ ++ At your option, Emacs can keep either a single backup for each file, ++or make a series of numbered backup files for each file that you edit. ++@xref{Backup Names}. ++ ++@vindex backup-enable-predicate ++@vindex temporary-file-directory ++@vindex small-temporary-file-directory ++ The default value of the @code{backup-enable-predicate} variable ++prevents backup files being written for files in the directories used ++for temporary files, specified by @code{temporary-file-directory} or ++@code{small-temporary-file-directory}. ++ ++ You can explicitly tell Emacs to make another backup file from a ++buffer, even though that buffer has been saved before. If you save ++the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made ++into a backup file if you save the buffer again. @kbd{C-u C-u C-x ++C-s} saves the buffer, but first makes the previous file contents into ++a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it ++makes a backup from the previous contents, and arranges to make ++another from the newly saved contents if you save again. ++ ++@menu ++* Names: Backup Names. How backup files are named. ++* Deletion: Backup Deletion. Emacs deletes excess numbered backups. ++* Copying: Backup Copying. Backups can be made by copying or renaming. ++@end menu ++ ++@node Backup Names ++@subsubsection Single or Numbered Backups ++ ++ When Emacs makes a backup file, its name is normally constructed by ++appending @samp{~} to the file name being edited; thus, the backup ++file for @file{eval.c} would be @file{eval.c~}. ++ ++ If access control stops Emacs from writing backup files under the usual ++names, it writes the backup file as @file{%backup%~} in your home ++directory. Only one such file can exist, so only the most recently ++made such backup is available. ++ ++ Emacs can also make @dfn{numbered backup files}. Numbered backup ++file names contain @samp{.~}, the number, and another @samp{~} after ++the original file name. Thus, the backup files of @file{eval.c} would ++be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way ++through names like @file{eval.c.~259~} and beyond. ++ ++@vindex version-control ++ The variable @code{version-control} determines whether to make ++single backup files or multiple numbered backup files. Its possible ++values are: ++ ++@table @code ++@item nil ++Make numbered backups for files that have numbered backups already. ++Otherwise, make single backups. This is the default. ++@item t ++Make numbered backups. ++@item never ++Never make numbered backups; always make single backups. ++@end table ++ ++@noindent ++The usual way to set this variable is globally, through your ++@file{.emacs} file or the customization buffer. However, you can set ++@code{version-control} locally in an individual buffer to control the ++making of backups for that buffer's file (@pxref{Locals}). You can ++have Emacs set @code{version-control} locally whenever you visit a ++given file (@pxref{File Variables}). Some modes, such as Rmail mode, ++set this variable. ++ ++@cindex @env{VERSION_CONTROL} environment variable ++ If you set the environment variable @env{VERSION_CONTROL}, to tell ++various GNU utilities what to do with backup files, Emacs also obeys the ++environment variable by setting the Lisp variable @code{version-control} ++accordingly at startup. If the environment variable's value is @samp{t} ++or @samp{numbered}, then @code{version-control} becomes @code{t}; if the ++value is @samp{nil} or @samp{existing}, then @code{version-control} ++becomes @code{nil}; if it is @samp{never} or @samp{simple}, then ++@code{version-control} becomes @code{never}. ++ ++@vindex backup-directory-alist ++ You can customize the variable @code{backup-directory-alist} to ++specify that files matching certain patterns should be backed up in ++specific directories. This variable applies to both single and ++numbered backups. A typical use is to add an element @code{("." ++. @var{dir})} to make all backups in the directory with absolute name ++@var{dir}; Emacs modifies the backup file names to avoid clashes ++between files with the same names originating in different ++directories. Alternatively, adding, @code{("." . ".~")} would make ++backups in the invisible subdirectory @file{.~} of the original file's ++directory. Emacs creates the directory, if necessary, to make the ++backup. ++ ++@vindex make-backup-file-name-function ++ If you define the variable @code{make-backup-file-name-function} to ++a suitable Lisp function, that overrides the usual way Emacs ++constructs backup file names. ++ ++@node Backup Deletion ++@subsubsection Automatic Deletion of Backups ++ ++ To prevent excessive consumption of disk space, Emacs can delete numbered ++backup versions automatically. Generally Emacs keeps the first few backups ++and the latest few backups, deleting any in between. This happens every ++time a new backup is made. ++ ++@vindex kept-old-versions ++@vindex kept-new-versions ++ The two variables @code{kept-old-versions} and ++@code{kept-new-versions} control this deletion. Their values are, ++respectively, the number of oldest (lowest-numbered) backups to keep ++and the number of newest (highest-numbered) ones to keep, each time a ++new backup is made. The backups in the middle (excluding those oldest ++and newest) are the excess middle versions---those backups are ++deleted. These variables' values are used when it is time to delete ++excess versions, just after a new backup version is made; the newly ++made backup is included in the count in @code{kept-new-versions}. By ++default, both variables are 2. ++ ++@vindex delete-old-versions ++ If @code{delete-old-versions} is @code{t}, Emacs deletes the excess ++backup files silently. If it is @code{nil}, the default, Emacs asks ++you whether it should delete the excess backup versions. If it has ++any other value, then Emacs never automatically deletes backups. ++ ++ Dired's @kbd{.} (Period) command can also be used to delete old versions. ++@xref{Dired Deletion}. ++ ++@node Backup Copying ++@subsubsection Copying vs.@: Renaming ++ ++ Backup files can be made by copying the old file or by renaming it. ++This makes a difference when the old file has multiple names (hard ++links). If the old file is renamed into the backup file, then the ++alternate names become names for the backup file. If the old file is ++copied instead, then the alternate names remain names for the file ++that you are editing, and the contents accessed by those names will be ++the new contents. ++ ++ The method of making a backup file may also affect the file's owner ++and group. If copying is used, these do not change. If renaming is used, ++you become the file's owner, and the file's group becomes the default ++(different operating systems have different defaults for the group). ++ ++ Having the owner change is usually a good idea, because then the owner ++always shows who last edited the file. Also, the owners of the backups ++show who produced those versions. Occasionally there is a file whose ++owner should not change; it is a good idea for such files to contain ++local variable lists to set @code{backup-by-copying-when-mismatch} ++locally (@pxref{File Variables}). ++ ++@vindex backup-by-copying ++@vindex backup-by-copying-when-linked ++@vindex backup-by-copying-when-mismatch ++@vindex backup-by-copying-when-privileged-mismatch ++@cindex file ownership, and backup ++@cindex backup, and user-id ++ The choice of renaming or copying is controlled by four variables. ++Renaming is the default choice. If the variable ++@code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise, ++if the variable @code{backup-by-copying-when-linked} is non-@code{nil}, ++then copying is used for files that have multiple names, but renaming ++may still be used when the file being edited has only one name. If the ++variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then ++copying is used if renaming would cause the file's owner or group to ++change. @code{backup-by-copying-when-mismatch} is @code{t} by default ++if you start Emacs as the superuser. The fourth variable, ++@code{backup-by-copying-when-privileged-mismatch}, gives the highest ++numeric user-id for which @code{backup-by-copying-when-mismatch} will be ++forced on. This is useful when low-numbered user-ids are assigned to ++special system users, such as @code{root}, @code{bin}, @code{daemon}, ++etc., which must maintain ownership of files. ++ ++ When a file is managed with a version control system (@pxref{Version ++Control}), Emacs does not normally make backups in the usual way for ++that file. But check-in and check-out are similar in some ways to ++making backups. One unfortunate similarity is that these operations ++typically break hard links, disconnecting the file name you visited from ++any alternate names for the same file. This has nothing to do with ++Emacs---the version control system does it. ++ ++@node Customize Save ++@subsection Customizing Saving of Files ++ ++@vindex require-final-newline ++ If the value of the variable @code{require-final-newline} is ++@code{t}, saving or writing a file silently puts a newline at the end ++if there isn't already one there. If the value is @code{visit}, Emacs ++adds a newline at the end of any file that doesn't have one, just ++after it visits the file. (This marks the buffer as modified, and you ++can undo it.) If the value is @code{visit-save}, that means to add ++newlines both on visiting and on saving. If the value is @code{nil}, ++Emacs leaves the end of the file unchanged; if it's neither @code{nil} ++nor @code{t}, Emacs asks you whether to add a newline. The default is ++@code{nil}. ++ ++@vindex mode-require-final-newline ++ Many major modes are designed for specific kinds of files that are ++always supposed to end in newlines. These major modes set the ++variable @code{require-final-newline} according to ++@code{mode-require-final-newline}. By setting the latter variable, ++you can control how these modes handle final newlines. ++ ++@vindex write-region-inhibit-fsync ++ When Emacs saves a file, it invokes the @code{fsync} system call to ++force the data immediately out to disk. This is important for safety ++if the system crashes or in case of power outage. However, it can be ++disruptive on laptops using power saving, because it requires the disk ++to spin up each time you save a file. Setting ++@code{write-region-inhibit-fsync} to a non-@code{nil} value disables ++this synchronization. Be careful---this means increased risk of data ++loss. ++ ++@node Interlocking ++@subsection Protection against Simultaneous Editing ++ ++@cindex file dates ++@cindex simultaneous editing ++ Simultaneous editing occurs when two users visit the same file, both ++make changes, and then both save them. If nobody were informed that ++this was happening, whichever user saved first would later find that his ++changes were lost. ++ ++ On some systems, Emacs notices immediately when the second user starts ++to change the file, and issues an immediate warning. On all systems, ++Emacs checks when you save the file, and warns if you are about to ++overwrite another user's changes. You can prevent loss of the other ++user's work by taking the proper corrective action instead of saving the ++file. ++ ++@findex ask-user-about-lock ++@cindex locking files ++ When you make the first modification in an Emacs buffer that is ++visiting a file, Emacs records that the file is @dfn{locked} by you. ++(It does this by creating a specially-named symbolic link in the same ++directory.) Emacs removes the lock when you save the changes. The ++idea is that the file is locked whenever an Emacs buffer visiting it ++has unsaved changes. ++ ++@cindex collision ++ If you begin to modify the buffer while the visited file is locked by ++someone else, this constitutes a @dfn{collision}. When Emacs detects a ++collision, it asks you what to do, by calling the Lisp function ++@code{ask-user-about-lock}. You can redefine this function for the sake ++of customization. The standard definition of this function asks you a ++question and accepts three possible answers: ++ ++@table @kbd ++@item s ++Steal the lock. Whoever was already changing the file loses the lock, ++and you gain the lock. ++@item p ++Proceed. Go ahead and edit the file despite its being locked by someone else. ++@item q ++Quit. This causes an error (@code{file-locked}), and the buffer ++contents remain unchanged---the modification you were trying to make ++does not actually take place. ++@end table ++ ++ Note that locking works on the basis of a file name; if a file has ++multiple names, Emacs does not realize that the two names are the same file ++and cannot prevent two users from editing it simultaneously under different ++names. However, basing locking on names means that Emacs can interlock the ++editing of new files that will not really exist until they are saved. ++ ++ Some systems are not configured to allow Emacs to make locks, and ++there are cases where lock files cannot be written. In these cases, ++Emacs cannot detect trouble in advance, but it still can detect the ++collision when you try to save a file and overwrite someone else's ++changes. Every time Emacs saves a buffer, it first checks the ++last-modification date of the existing file on disk to verify that it ++has not changed since the file was last visited or saved. If the date ++does not match, it implies that changes were made in the file in some ++other way, and these changes are about to be lost if Emacs actually ++does save. To prevent this, Emacs displays a warning message and asks ++for confirmation before saving. Occasionally you will know why the ++file was changed and know that it does not matter; then you can answer ++@kbd{yes} and proceed. Otherwise, you should cancel the save with ++@kbd{C-g} and investigate the situation. ++ ++ If Emacs or the operating system crashes, this may leave behind lock ++files which are stale, so you may occasionally get warnings about ++spurious collisions. When you determine that the collision is spurious, ++just use @kbd{p} to tell Emacs to go ahead anyway. ++ ++ The first thing you should do when notified that simultaneous editing ++has already taken place is to list the directory with @kbd{C-u C-x C-d} ++(@pxref{Directories}). This shows the file's current author. You ++should attempt to contact him to warn him not to continue editing. ++Often the next step is to save the contents of your Emacs buffer under a ++different name, and use @code{diff} to compare the two files.@refill ++ ++@node File Shadowing ++@subsection Shadowing Files ++@cindex shadow files ++@cindex file shadows ++@findex shadow-initialize ++ ++@table @kbd ++@item M-x shadow-initialize ++Set up file shadowing. ++@item M-x shadow-define-literal-group ++Declare a single file to be shared between sites. ++@item M-x shadow-define-regexp-group ++Make all files that match each of a group of files be shared between hosts. ++@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} ++Define a shadow file cluster @var{name}. ++@item M-x shadow-copy-files ++Copy all pending shadow files. ++@item M-x shadow-cancel ++Cancel the instruction to shadow some files. ++@end table ++ ++You can arrange to keep identical @dfn{shadow} copies of certain files ++in more than one place---possibly on different machines. To do this, ++first you must set up a @dfn{shadow file group}, which is a set of ++identically-named files shared between a list of sites. The file ++group is permanent and applies to further Emacs sessions as well as ++the current one. Once the group is set up, every time you exit Emacs, ++it will copy the file you edited to the other files in its group. You ++can also do the copying without exiting Emacs, by typing @kbd{M-x ++shadow-copy-files}. ++ ++To set up a shadow file group, use @kbd{M-x ++shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. ++See their documentation strings for further information. ++ ++Before copying a file to its shadows, Emacs asks for confirmation. ++You can answer ``no'' to bypass copying of this file, this time. If ++you want to cancel the shadowing permanently for a certain file, use ++@kbd{M-x shadow-cancel} to eliminate or change the shadow file group. ++ ++A @dfn{shadow cluster} is a group of hosts that share directories, so ++that copying to or from one of them is sufficient to update the file ++on all of them. Each shadow cluster has a name, and specifies the ++network address of a primary host (the one we copy files to), and a ++regular expression that matches the host names of all the other hosts ++in the cluster. You can define a shadow cluster with @kbd{M-x ++shadow-define-cluster}. ++ ++@node Time Stamps ++@subsection Updating Time Stamps Automatically ++@cindex time stamps ++@cindex modification dates ++@cindex locale, date format ++ ++You can arrange to put a time stamp in a file, so that it will be updated ++automatically each time you edit and save the file. The time stamp ++has to be in the first eight lines of the file, and you should ++insert it like this: ++ ++@example ++Time-stamp: <> ++@end example ++ ++@noindent ++or like this: ++ ++@example ++Time-stamp: " " ++@end example ++ ++@findex time-stamp ++ Then add the hook function @code{time-stamp} to the hook ++@code{before-save-hook}; that hook function will automatically update ++the time stamp, inserting the current date and time when you save the ++file. You can also use the command @kbd{M-x time-stamp} to update the ++time stamp manually. For other customizations, see the Custom group ++@code{time-stamp}. Note that non-numeric fields in the time stamp are ++formatted according to your locale setting (@pxref{Environment}). ++ ++@node Reverting ++@section Reverting a Buffer ++@findex revert-buffer ++@cindex drastic changes ++@cindex reread a file ++ ++ If you have made extensive changes to a file and then change your mind ++about them, you can get rid of them by reading in the previous version ++of the file. To do this, use @kbd{M-x revert-buffer}, which operates on ++the current buffer. Since reverting a buffer unintentionally could lose ++a lot of work, you must confirm this command with @kbd{yes}. ++ ++ @code{revert-buffer} tries to position point in such a way that, if ++the file was edited only slightly, you will be at approximately the ++same piece of text after reverting as before. However, if you have made ++drastic changes, point may wind up in a totally different piece of text. ++ ++ Reverting marks the buffer as ``not modified''. ++ ++ Some kinds of buffers that are not associated with files, such as ++Dired buffers, can also be reverted. For them, reverting means ++recalculating their contents. Buffers created explicitly with ++@kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error ++if you try. ++ ++@vindex revert-without-query ++ When you edit a file that changes automatically and frequently---for ++example, a log of output from a process that continues to run---it may ++be useful for Emacs to revert the file without querying you. To ++request this behavior, set the variable @code{revert-without-query} to ++a list of regular expressions. When a file name matches one of these ++regular expressions, @code{find-file} and @code{revert-buffer} will ++revert it automatically if it has changed---provided the buffer itself ++is not modified. (If you have edited the text, it would be wrong to ++discard your changes.) ++ ++@cindex Global Auto-Revert mode ++@cindex mode, Global Auto-Revert ++@cindex Auto-Revert mode ++@cindex mode, Auto-Revert ++@findex global-auto-revert-mode ++@findex auto-revert-mode ++@findex auto-revert-tail-mode ++@vindex auto-revert-interval ++ ++ In addition, you can tell Emacs to periodically revert a buffer by ++typing @kbd{M-x auto-revert-mode}. This turns on Auto-Revert mode, a ++minor mode that makes Emacs automatically revert the current buffer ++every five seconds. You can change this interval through the variable ++@code{auto-revert-interval}. Typing @kbd{M-x global-auto-revert-mode} ++enables Global Auto-Revert mode, which does the same for all file ++buffers. Auto-Revert mode and Global Auto-Revert modes do not check ++or revert remote files, because that is usually too slow. ++ ++ One use of Auto-Revert mode is to ``tail'' a file such as a system ++log, so that changes made to that file by other programs are ++continuously displayed. To do this, just move the point to the end of ++the buffer, and it will stay there as the file contents change. ++However, if you are sure that the file will only change by growing at ++the end, use Auto-Revert Tail mode instead ++(@code{auto-revert-tail-mode}). It is more efficient for this. ++ ++ @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that ++visit files under version control. ++ ++@ifnottex ++@include arevert-xtra.texi ++@end ifnottex ++ ++@node Auto Save ++@section Auto-Saving: Protection Against Disasters ++@cindex Auto Save mode ++@cindex mode, Auto Save ++@cindex crashes ++ ++ From time to time, Emacs automatically saves each visited file in a ++separate file, without altering the file you actually use. This is ++called @dfn{auto-saving}. It prevents you from losing more than a ++limited amount of work if the system crashes. ++ ++ When Emacs determines that it is time for auto-saving, it considers ++each buffer, and each is auto-saved if auto-saving is enabled for it ++and it has been changed since the last time it was auto-saved. The ++message @samp{Auto-saving...} is displayed in the echo area during ++auto-saving, if any files are actually auto-saved. Errors occurring ++during auto-saving are caught so that they do not interfere with the ++execution of commands you have been typing. ++ ++@menu ++* Files: Auto Save Files. The file where auto-saved changes are ++ actually made until you save the file. ++* Control: Auto Save Control. Controlling when and how often to auto-save. ++* Recover:: Recovering text from auto-save files. ++@end menu ++ ++@node Auto Save Files ++@subsection Auto-Save Files ++ ++ Auto-saving does not normally save in the files that you visited, ++because it can be very undesirable to save a change that you did not ++want to make permanent. Instead, auto-saving is done in a different ++file called the @dfn{auto-save file}, and the visited file is changed ++only when you request saving explicitly (such as with @kbd{C-x C-s}). ++ ++ Normally, the auto-save file name is made by appending @samp{#} to the ++front and rear of the visited file name. Thus, a buffer visiting file ++@file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that ++are not visiting files are auto-saved only if you request it explicitly; ++when they are auto-saved, the auto-save file name is made by appending ++@samp{#} to the front and rear of buffer name, then ++adding digits and letters at the end for uniqueness. For ++example, the @samp{*mail*} buffer in which you compose messages to be ++sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file ++names are made this way unless you reprogram parts of Emacs to do ++something different (the functions @code{make-auto-save-file-name} and ++@code{auto-save-file-name-p}). The file name to be used for auto-saving ++in a buffer is calculated when auto-saving is turned on in that buffer. ++ ++@cindex auto-save for remote files ++@vindex auto-save-file-name-transforms ++ The variable @code{auto-save-file-name-transforms} allows a degree ++of control over the auto-save file name. It lets you specify a series ++of regular expressions and replacements to transform the auto save ++file name. The default value puts the auto-save files for remote ++files (@pxref{Remote Files}) into the temporary file directory on the ++local machine. ++ ++ When you delete a substantial part of the text in a large buffer, auto ++save turns off temporarily in that buffer. This is because if you ++deleted the text unintentionally, you might find the auto-save file more ++useful if it contains the deleted text. To reenable auto-saving after ++this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x ++auto-save-mode}. ++ ++@vindex auto-save-visited-file-name ++ If you want auto-saving to be done in the visited file rather than ++in a separate auto-save file, set the variable ++@code{auto-save-visited-file-name} to a non-@code{nil} value. In this ++mode, there is no real difference between auto-saving and explicit ++saving. ++ ++@vindex delete-auto-save-files ++ A buffer's auto-save file is deleted when you save the buffer in its ++visited file. (You can inhibit this by setting the variable ++@code{delete-auto-save-files} to @code{nil}.) Changing the visited ++file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames ++any auto-save file to go with the new visited name. ++ ++@node Auto Save Control ++@subsection Controlling Auto-Saving ++ ++@vindex auto-save-default ++@findex auto-save-mode ++ Each time you visit a file, auto-saving is turned on for that file's ++buffer if the variable @code{auto-save-default} is non-@code{nil} (but not ++in batch mode; @pxref{Entering Emacs}). The default for this variable is ++@code{t}, so auto-saving is the usual practice for file-visiting buffers. ++Auto-saving can be turned on or off for any existing buffer with the ++command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x ++auto-save-mode} turns auto-saving on with a positive argument, off with a ++zero or negative argument; with no argument, it toggles. ++ ++@vindex auto-save-interval ++ Emacs does auto-saving periodically based on counting how many characters ++you have typed since the last time auto-saving was done. The variable ++@code{auto-save-interval} specifies how many characters there are between ++auto-saves. By default, it is 300. Emacs doesn't accept values that are ++too small: if you customize @code{auto-save-interval} to a value less ++than 20, Emacs will behave as if the value is 20. ++ ++@vindex auto-save-timeout ++ Auto-saving also takes place when you stop typing for a while. The ++variable @code{auto-save-timeout} says how many seconds Emacs should ++wait before it does an auto save (and perhaps also a garbage ++collection). (The actual time period is longer if the current buffer is ++long; this is a heuristic which aims to keep out of your way when you ++are editing long buffers, in which auto-save takes an appreciable amount ++of time.) Auto-saving during idle periods accomplishes two things: ++first, it makes sure all your work is saved if you go away from the ++terminal for a while; second, it may avoid some auto-saving while you ++are actually typing. ++ ++ Emacs also does auto-saving whenever it gets a fatal error. This ++includes killing the Emacs job with a shell command such as @samp{kill ++%emacs}, or disconnecting a phone line or network connection. ++ ++@findex do-auto-save ++ You can request an auto-save explicitly with the command @kbd{M-x ++do-auto-save}. ++ ++@node Recover ++@subsection Recovering Data from Auto-Saves ++ ++@findex recover-file ++ You can use the contents of an auto-save file to recover from a loss ++of data with the command @kbd{M-x recover-file @key{RET} @var{file} ++@key{RET}}. This visits @var{file} and then (after your confirmation) ++restores the contents from its auto-save file @file{#@var{file}#}. ++You can then save with @kbd{C-x C-s} to put the recovered text into ++@var{file} itself. For example, to recover file @file{foo.c} from its ++auto-save file @file{#foo.c#}, do:@refill ++ ++@example ++M-x recover-file @key{RET} foo.c @key{RET} ++yes @key{RET} ++C-x C-s ++@end example ++ ++ Before asking for confirmation, @kbd{M-x recover-file} displays a ++directory listing describing the specified file and the auto-save file, ++so you can compare their sizes and dates. If the auto-save file ++is older, @kbd{M-x recover-file} does not offer to read it. ++ ++@findex recover-session ++ If Emacs or the computer crashes, you can recover all the files you ++were editing from their auto save files with the command @kbd{M-x ++recover-session}. This first shows you a list of recorded interrupted ++sessions. Move point to the one you choose, and type @kbd{C-c C-c}. ++ ++ Then @code{recover-session} asks about each of the files that were ++being edited during that session, asking whether to recover that file. ++If you answer @kbd{y}, it calls @code{recover-file}, which works in its ++normal fashion. It shows the dates of the original file and its ++auto-save file, and asks once again whether to recover that file. ++ ++ When @code{recover-session} is done, the files you've chosen to ++recover are present in Emacs buffers. You should then save them. Only ++this---saving them---updates the files themselves. ++ ++@vindex auto-save-list-file-prefix ++ Emacs records information about interrupted sessions for later ++recovery in files named ++@file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. The ++directory used, @file{~/.emacs.d/auto-save-list/}, is determined by ++the variable @code{auto-save-list-file-prefix}. You can record ++sessions in a different place by customizing that variable. If you ++set @code{auto-save-list-file-prefix} to @code{nil} in your ++@file{.emacs} file, sessions are not recorded for recovery. ++ ++@node File Aliases ++@section File Name Aliases ++@cindex symbolic links (visiting) ++@cindex hard links (visiting) ++ ++ Symbolic links and hard links both make it possible for several file ++names to refer to the same file. Hard links are alternate names that ++refer directly to the file; all the names are equally valid, and no one ++of them is preferred. By contrast, a symbolic link is a kind of defined ++alias: when @file{foo} is a symbolic link to @file{bar}, you can use ++either name to refer to the file, but @file{bar} is the real name, while ++@file{foo} is just an alias. More complex cases occur when symbolic ++links point to directories. ++ ++@vindex find-file-existing-other-name ++@vindex find-file-suppress-same-file-warnings ++ ++ Normally, if you visit a file which Emacs is already visiting under ++a different name, Emacs displays a message in the echo area and uses ++the existing buffer visiting that file. This can happen on systems ++that support hard or symbolic links, or if you use a long file name on ++a system that truncates long file names, or on a case-insensitive file ++system. You can suppress the message by setting the variable ++@code{find-file-suppress-same-file-warnings} to a non-@code{nil} ++value. You can disable this feature entirely by setting the variable ++@code{find-file-existing-other-name} to @code{nil}: then if you visit ++the same file under two different names, you get a separate buffer for ++each file name. ++ ++@vindex find-file-visit-truename ++@cindex truenames of files ++@cindex file truenames ++ If the variable @code{find-file-visit-truename} is non-@code{nil}, ++then the file name recorded for a buffer is the file's @dfn{truename} ++(made by replacing all symbolic links with their target names), rather ++than the name you specify. Setting @code{find-file-visit-truename} also ++implies the effect of @code{find-file-existing-other-name}. ++ ++@node Directories ++@section File Directories ++ ++@cindex file directory ++@cindex directory listing ++ The file system groups files into @dfn{directories}. A @dfn{directory ++listing} is a list of all the files in a directory. Emacs provides ++commands to create and delete directories, and to make directory ++listings in brief format (file names only) and verbose format (sizes, ++dates, and authors included). Emacs also includes a directory browser ++feature called Dired; see @ref{Dired}. ++ ++@table @kbd ++@item C-x C-d @var{dir-or-pattern} @key{RET} ++Display a brief directory listing (@code{list-directory}). ++@item C-u C-x C-d @var{dir-or-pattern} @key{RET} ++Display a verbose directory listing. ++@item M-x make-directory @key{RET} @var{dirname} @key{RET} ++Create a new directory named @var{dirname}. ++@item M-x delete-directory @key{RET} @var{dirname} @key{RET} ++Delete the directory named @var{dirname}. It must be empty, ++or you get an error. ++@end table ++ ++@findex list-directory ++@kindex C-x C-d ++ The command to display a directory listing is @kbd{C-x C-d} ++(@code{list-directory}). It reads using the minibuffer a file name ++which is either a directory to be listed or a wildcard-containing ++pattern for the files to be listed. For example, ++ ++@example ++C-x C-d /u2/emacs/etc @key{RET} ++@end example ++ ++@noindent ++lists all the files in directory @file{/u2/emacs/etc}. Here is an ++example of specifying a file name pattern: ++ ++@example ++C-x C-d /u2/emacs/src/*.c @key{RET} ++@end example ++ ++ Normally, @kbd{C-x C-d} displays a brief directory listing containing ++just file names. A numeric argument (regardless of value) tells it to ++make a verbose listing including sizes, dates, and owners (like ++@samp{ls -l}). ++ ++@vindex list-directory-brief-switches ++@vindex list-directory-verbose-switches ++ The text of a directory listing is mostly obtained by running ++@code{ls} in an inferior process. Two Emacs variables control the ++switches passed to @code{ls}: @code{list-directory-brief-switches} is ++a string giving the switches to use in brief listings (@code{"-CF"} by ++default), and @code{list-directory-verbose-switches} is a string ++giving the switches to use in a verbose listing (@code{"-l"} by ++default). ++ ++@vindex directory-free-space-program ++@vindex directory-free-space-args ++ In verbose directory listings, Emacs adds information about the ++amount of free space on the disk that contains the directory. To do ++this, it runs the program specified by ++@code{directory-free-space-program} with arguments ++@code{directory-free-space-args}. ++ ++ The command @kbd{M-x delete-directory} prompts for a directory name ++using the minibuffer, and deletes the directory if it is empty. If ++the directory is not empty, this signals an error. On systems that ++have a ``Trash'' or ``Recycle Bin'' feature, you can make this command ++move the specified directory to the Trash or Recycle Bin, instead of ++deleting it outright, by changing the variable ++@code{delete-by-moving-to-trash} to @code{t}. @xref{Misc File Ops}, ++for more information about using the Trash. ++ ++@node Comparing Files ++@section Comparing Files ++@cindex comparing files ++ ++@findex diff ++@vindex diff-switches ++ The command @kbd{M-x diff} prompts for two file names, using the ++minibuffer, and displays the differences between the two files in a ++buffer named @samp{*diff*}. This works by running the @command{diff} ++program, using options taken from the variable @code{diff-switches}. ++The value of @code{diff-switches} should be a string; the default is ++@code{"-c"} to specify a context diff. @xref{Top,, Diff, diff, ++Comparing and Merging Files}, for more information about ++@command{diff} output formats. ++ ++ The output of the @code{diff} command is shown using a major mode ++called Diff mode. @xref{Diff Mode}. ++ ++@findex diff-backup ++ The command @kbd{M-x diff-backup} compares a specified file with its ++most recent backup. If you specify the name of a backup file, ++@code{diff-backup} compares it with the source file that it is a ++backup of. In all other respects, this behaves like @kbd{M-x diff}. ++ ++@findex diff-buffer-with-file ++ The command @kbd{M-x diff-buffer-with-file} compares a specified ++buffer with its corresponding file. This shows you what changes you ++would make to the file if you save the buffer. ++ ++@findex compare-windows ++ The command @kbd{M-x compare-windows} compares the text in the ++current window with that in the next window. (For more information ++about windows in Emacs, @ref{Windows}.) Comparison starts at point in ++each window, after pushing each initial point value on the mark ring ++in its respective buffer. Then it moves point forward in each window, ++one character at a time, until it reaches characters that don't match. ++Then the command exits. ++ ++ If point in the two windows is followed by non-matching text when ++the command starts, @kbd{M-x compare-windows} tries heuristically to ++advance up to matching text in the two windows, and then exits. So if ++you use @kbd{M-x compare-windows} repeatedly, each time it either ++skips one matching range or finds the start of another. ++ ++@vindex compare-ignore-case ++@vindex compare-ignore-whitespace ++ With a numeric argument, @code{compare-windows} ignores changes in ++whitespace. If the variable @code{compare-ignore-case} is ++non-@code{nil}, the comparison ignores differences in case as well. ++If the variable @code{compare-ignore-whitespace} is non-@code{nil}, ++@code{compare-windows} normally ignores changes in whitespace, and a ++prefix argument turns that off. ++ ++@cindex Smerge mode ++@findex smerge-mode ++@cindex failed merges ++@cindex merges, failed ++@cindex comparing 3 files (@code{diff3}) ++ You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor ++mode for editing output from the @command{diff3} program. This is ++typically the result of a failed merge from a version control system ++``update'' outside VC, due to conflicting changes to a file. Smerge ++mode provides commands to resolve conflicts by selecting specific ++changes. ++ ++@iftex ++@xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, ++@end iftex ++@ifnottex ++@xref{Emerge}, ++@end ifnottex ++for the Emerge facility, which provides a powerful interface for ++merging files. ++ ++@node Diff Mode ++@section Diff Mode ++@cindex Diff mode ++@findex diff-mode ++@cindex patches, editing ++ ++ Diff mode is a major mode used for the output of @kbd{M-x diff} and ++other similar commands, as well as the output of the @command{diff} ++program. This kind of output is called a @dfn{patch}, because it can ++be passed to the @command{patch} command to automatically apply the ++specified changes. To select Diff mode manually, type @kbd{M-x ++diff-mode}. ++ ++@cindex hunk, diff ++ The changes specified in a patch are grouped into @dfn{hunks}, which ++are contiguous chunks of text that contain one or more changed lines. ++Hunks can also include unchanged lines to provide context for the ++changes. Each hunk is preceded by a @dfn{hunk header}, which ++specifies the old and new line numbers at which the hunk occurs. Diff ++mode highlights each hunk header, to distinguish it from the actual ++contents of the hunk. ++ ++@vindex diff-update-on-the-fly ++ You can edit a Diff mode buffer like any other buffer. (If it is ++read-only, you need to make it writable first. @xref{Misc Buffer}.) ++Whenever you change a hunk, Diff mode attempts to automatically ++correct the line numbers in the hunk headers, to ensure that the diff ++remains ``correct''. To disable automatic line number correction, ++change the variable @code{diff-update-on-the-fly} to @code{nil}. ++ ++ Diff mode treats each hunk as an ``error message,'' similar to ++Compilation mode. Thus, you can use commands such as @kbd{C-x '} to ++visit the corresponding source locations. @xref{Compilation Mode}. ++ ++ In addition, Diff mode provides the following commands to navigate, ++manipulate and apply parts of patches: ++ ++@table @kbd ++@item M-n ++@findex diff-hunk-next ++Move to the next hunk-start (@code{diff-hunk-next}). ++ ++@item M-p ++@findex diff-hunk-prev ++Move to the previous hunk-start (@code{diff-hunk-prev}). ++ ++@item M-@} ++@findex diff-file-next ++Move to the next file-start, in a multi-file patch ++(@code{diff-file-next}). ++ ++@item M-@{ ++@findex diff-file-prev ++Move to the previous file-start, in a multi-file patch ++(@code{diff-file-prev}). ++ ++@item M-k ++@findex diff-hunk-kill ++Kill the hunk at point (@code{diff-hunk-kill}). ++ ++@item M-K ++@findex diff-file-kill ++In a multi-file patch, kill the current file part. ++(@code{diff-file-kill}). ++ ++@item C-c C-a ++@findex diff-apply-hunk ++Apply this hunk to its target file (@code{diff-apply-hunk}). With a ++prefix argument of @kbd{C-u}, revert this hunk. ++ ++@item C-c C-b ++@findex diff-refine-hunk ++Highlight the changes of the hunk at point with a finer granularity ++(@code{diff-refine-hunk}). This allows you to see exactly which parts ++of each changed line were actually changed. ++ ++@item C-c C-c ++@findex diff-goto-source ++Go to the source file and line corresponding to this hunk ++(@code{diff-goto-source}). ++ ++@item C-c C-e ++@findex diff-ediff-patch ++Start an Ediff session with the patch (@code{diff-ediff-patch}). ++@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. ++ ++@item C-c C-n ++@findex diff-restrict-view ++Restrict the view to the current hunk (@code{diff-restrict-view}). ++@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the ++view to the current file of a multiple-file patch. To widen again, ++use @kbd{C-x n w} (@code{widen}). ++ ++@item C-c C-r ++@findex diff-reverse-direction ++Reverse the direction of comparison for the entire buffer ++(@code{diff-reverse-direction}). ++ ++@item C-c C-s ++@findex diff-split-hunk ++Split the hunk at point (@code{diff-split-hunk}). This is for ++manually editing patches, and only works with the @dfn{unified diff ++format} produced by the @option{-u} or @option{--unified} options to ++the @command{diff} program. If you need to split a hunk in the ++@dfn{context diff format} produced by the @option{-c} or ++@option{--context} options to @command{diff}, first convert the buffer ++to the unified diff format with @kbd{C-c C-u}. ++ ++@item C-c C-d ++@findex diff-unified->context ++Convert the entire buffer to the @dfn{context diff format} ++(@code{diff-unified->context}). With a prefix argument, convert only ++the text within the region. ++ ++@item C-c C-u ++@findex diff-context->unified ++Convert the entire buffer to unified diff format ++(@code{diff-context->unified}). With a prefix argument, convert ++unified format to context format. When the mark is active, convert ++only the text within the region. ++ ++@item C-c C-w ++@findex diff-refine-hunk ++Refine the current hunk so that it disregards changes in whitespace ++(@code{diff-refine-hunk}). ++ ++@item C-x 4 A ++@findex diff-add-change-log-entries-other-window ++@findex add-change-log-entry-other-window@r{, in Diff mode} ++Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change ++Log}), for each one of the hunks ++(@code{diff-add-change-log-entries-other-window}). This creates a ++skeleton of the log of changes that you can later fill with the actual ++descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode ++operates on behalf of the current hunk's file, but gets the function ++name from the patch itself. This is useful for making log entries for ++functions that are deleted by the patch. ++ ++@item M-x diff-show-trailing-whitespaces RET ++@findex diff-show-trailing-whitespaces ++Highlight trailing whitespace characters, except for those used by the ++patch syntax (@pxref{Useless Whitespace}). ++@end table ++ ++ ++@node Misc File Ops ++@section Miscellaneous File Operations ++ ++ Emacs has commands for performing many other operations on files. ++All operate on one file; they do not accept wildcard file names. ++ ++@findex view-file ++@cindex viewing ++@cindex View mode ++@cindex mode, View ++ @kbd{M-x view-file} allows you to scan or read a file by sequential ++screenfuls. It reads a file name argument using the minibuffer. After ++reading the file into an Emacs buffer, @code{view-file} displays the ++beginning. You can then type @key{SPC} to scroll forward one windowful, ++or @key{DEL} to scroll backward. Various other commands are provided ++for moving around in the file, but none for changing it; type @kbd{?} ++while viewing for a list of them. They are mostly the same as normal ++Emacs cursor motion commands. To exit from viewing, type @kbd{q}. ++The commands for viewing are defined by a special minor mode called View ++mode. ++ ++ A related command, @kbd{M-x view-buffer}, views a buffer already present ++in Emacs. @xref{Misc Buffer}. ++ ++@kindex C-x i ++@findex insert-file ++ @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the ++contents of the specified file into the current buffer at point, ++leaving point unchanged before the contents. The position after the ++inserted contents is added to the mark ring, without activating the ++mark (@pxref{Mark Ring}). ++ ++@findex insert-file-literally ++ @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, ++except the file is inserted ``literally'': it is treated as a sequence ++of @acronym{ASCII} characters with no special encoding or conversion, ++similar to the @kbd{M-x find-file-literally} command ++(@pxref{Visiting}). ++ ++@findex write-region ++ @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it ++copies the contents of the region into the specified file. @kbd{M-x ++append-to-file} adds the text of the region to the end of the ++specified file. @xref{Accumulating Text}. The variable ++@code{write-region-inhibit-fsync} applies to these commands, as well ++as saving files; see @ref{Customize Save}. ++ ++@findex delete-file ++@cindex deletion (of files) ++@vindex delete-by-moving-to-trash ++ @kbd{M-x delete-file} deletes the specified file, like the @code{rm} ++command in the shell. If you are deleting many files in one ++directory, it may be more convenient to use Dired rather than ++@code{delete-file}. @xref{Dired}. ++ ++@cindex trash ++@cindex recycle bin ++ On some systems, there is a facility called the ``Trash'' (or ++``Recycle Bin''); ``deleting'' a file normally means moving it into ++the Trash, and you can bring the file back from the Trash if you later ++change your mind. By default, Emacs does @emph{not} use the Trash for ++file deletion---when Emacs deletes a file, it is gone forever. You ++can tell Emacs to use the Trash by changing the variable ++@code{delete-by-moving-to-trash} to @code{t}. This applies to file ++deletion via @kbd{M-x delete-file}, as well as @kbd{M-x ++delete-directory} (@pxref{Directories}) and file deletion in Dired ++(@pxref{Dired Deletion}). In addition, you can explicitly move a file ++into the Trash with the command @kbd{M-x move-file-to-trash}. ++ ++@findex rename-file ++ @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using ++the minibuffer, then renames file @var{old} as @var{new}. If the file name ++@var{new} already exists, you must confirm with @kbd{yes} or renaming is not ++done; this is because renaming causes the old meaning of the name @var{new} ++to be lost. If @var{old} and @var{new} are on different file systems, the ++file @var{old} is copied and deleted. ++ ++ If the argument @var{new} is just a directory name, the real new ++name is in that directory, with the same non-directory component as ++@var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET} ++renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all ++the remaining commands in this section. All of them ask for ++confirmation when the new file name already exists, too. ++ ++@findex add-name-to-file ++@cindex hard links (creation) ++ The similar command @kbd{M-x add-name-to-file} is used to add an ++additional name to an existing file without removing its old name. ++The new name is created as a ``hard link'' to the existing file. ++The new name must belong on the same file system that the file is on. ++On MS-Windows, this command works only if the file resides in an NTFS ++file system. On MS-DOS, it works by copying the file. ++ ++@findex copy-file ++@cindex copying files ++ @kbd{M-x copy-file} reads the file @var{old} and writes a new file ++named @var{new} with the same contents. ++ ++@findex make-symbolic-link ++@cindex symbolic links (creation) ++ @kbd{M-x make-symbolic-link} reads two file names @var{target} and ++@var{linkname}, then creates a symbolic link named @var{linkname}, ++which points at @var{target}. The effect is that future attempts to ++open file @var{linkname} will refer to whatever file is named ++@var{target} at the time the opening is done, or will get an error if ++the name @var{target} is nonexistent at that time. This command does ++not expand the argument @var{target}, so that it allows you to specify ++a relative name as the target of the link. ++ ++ Not all systems support symbolic links; on systems that don't ++support them, this command is not defined. ++ ++@findex set-file-modes ++@cindex file modes ++@cindex file permissions ++ @kbd{M-x set-file-modes} reads a file name followed by a @dfn{file ++mode}, and applies that file mode to the specified file. File modes, ++also called @dfn{file permissions}, determine whether a file can be ++read, written to, or executed, and by whom. This command reads file ++modes using the same symbolic or octal format accepted by the ++@command{chmod} command; for instance, @samp{u+x} means to add ++execution permission for the user who owns the file. It has no effect ++on operating systems that do not support file modes. @code{chmod} is a ++convenience alias for this function. ++ ++@node Compressed Files ++@section Accessing Compressed Files ++@cindex compression ++@cindex uncompression ++@cindex Auto Compression mode ++@cindex mode, Auto Compression ++@pindex gzip ++ ++ Emacs automatically uncompresses compressed files when you visit ++them, and automatically recompresses them if you alter them and save ++them. Emacs recognizes compressed files by their file names. File ++names ending in @samp{.gz} indicate a file compressed with ++@code{gzip}. Other endings indicate other compression programs. ++ ++ Automatic uncompression and compression apply to all the operations in ++which Emacs uses the contents of a file. This includes visiting it, ++saving it, inserting its contents into a buffer, loading it, and byte ++compiling it. ++ ++@findex auto-compression-mode ++@vindex auto-compression-mode ++ To disable this feature, type the command @kbd{M-x ++auto-compression-mode}. You can disable it permanently by ++customizing the variable @code{auto-compression-mode}. ++ ++@node File Archives ++@section File Archives ++@cindex mode, tar ++@cindex Tar mode ++@cindex file archives ++ ++ A file whose name ends in @samp{.tar} is normally an @dfn{archive} ++made by the @code{tar} program. Emacs views these files in a special ++mode called Tar mode which provides a Dired-like list of the contents ++(@pxref{Dired}). You can move around through the list just as you ++would in Dired, and visit the subfiles contained in the archive. ++However, not all Dired commands are available in Tar mode. ++ ++ If Auto Compression mode is enabled (@pxref{Compressed Files}), then ++Tar mode is used also for compressed archives---files with extensions ++@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. ++ ++ The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file ++into its own buffer. You can edit it there, and if you save the ++buffer, the edited version will replace the version in the Tar buffer. ++@kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts ++the file and displays it in another window, so you could edit the file ++and operate on the archive simultaneously. @kbd{d} marks a file for ++deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in ++Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} ++renames a file within the archive. @kbd{g} reverts the buffer from ++the archive on disk. ++ ++ The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission ++bits, group, and owner, respectively. ++ ++ If your display supports colors and the mouse, moving the mouse ++pointer across a file name highlights that file name, indicating that ++you can click on it. Clicking @kbd{Mouse-2} on the highlighted file ++name extracts the file into a buffer and displays that buffer. ++ ++ Saving the Tar buffer writes a new version of the archive to disk with ++the changes you made to the components. ++ ++ You don't need the @code{tar} program to use Tar mode---Emacs reads ++the archives directly. However, accessing compressed archives ++requires the appropriate uncompression program. ++ ++@cindex Archive mode ++@cindex mode, archive ++@cindex @code{arc} ++@cindex @code{jar} ++@cindex @code{rar} ++@cindex @code{zip} ++@cindex @code{lzh} ++@cindex @code{zoo} ++@pindex arc ++@pindex jar ++@pindex zip ++@pindex rar ++@pindex lzh ++@pindex zoo ++@cindex Java class archives ++@cindex unzip archives ++ A separate but similar Archive mode is used for archives produced by ++the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, ++@code{rar}, and @code{zoo}, which have extensions corresponding to the ++program names. Archive mode also works for those @code{exe} files ++that are self-extracting executables. ++ ++ The key bindings of Archive mode are similar to those in Tar mode, ++with the addition of the @kbd{m} key which marks a file for subsequent ++operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. ++Also, the @kbd{a} key toggles the display of detailed file ++information, for those archive types where it won't fit in a single ++line. Operations such as renaming a subfile, or changing its mode or ++owner, are supported only for some of the archive formats. ++ ++ Unlike Tar mode, Archive mode runs the archiving program to unpack ++and repack archives. Details of the program names and their options ++can be set in the @samp{Archive} Customize group. However, you don't ++need these programs to look at the archive table of contents, only to ++extract or manipulate the subfiles in the archive. ++ ++@node Remote Files ++@section Remote Files ++ ++@cindex Tramp ++@cindex FTP ++@cindex remote file access ++ You can refer to files on other machines using a special file name ++syntax: ++ ++@example ++@group ++/@var{host}:@var{filename} ++/@var{user}@@@var{host}:@var{filename} ++/@var{user}@@@var{host}#@var{port}:@var{filename} ++/@var{method}:@var{user}@@@var{host}:@var{filename} ++/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} ++@end group ++@end example ++ ++@noindent ++To carry out this request, Emacs uses a remote-login program such as ++@command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}. ++You can always specify in the file name which method to use---for ++example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, ++whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses ++@command{ssh}. When you don't specify a method in the file name, ++Emacs chooses the method as follows: ++ ++@enumerate ++@item ++If the host name starts with @samp{ftp.} (with dot), then Emacs uses ++FTP. ++@item ++If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses ++FTP. ++@item ++If the variable @code{tramp-default-method} is set to @samp{ftp}, ++then Emacs uses FTP. ++@item ++If @command{ssh-agent} is running, then Emacs uses @command{scp}. ++@item ++Otherwise, Emacs uses @command{ssh}. ++@end enumerate ++ ++@cindex disabling remote files ++@noindent ++You can entirely turn off the remote file name feature by setting the ++variable @code{tramp-mode} to @code{nil}. You can turn off the ++feature in individual cases by quoting the file name with @samp{/:} ++(@pxref{Quoted File Names}). ++ ++ Remote file access through FTP is handled by the Ange-FTP package, which ++is documented in the following. Remote file access through the other ++methods is handled by the Tramp package, which has its own manual. ++@xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. ++ ++When the Ange-FTP package is used, Emacs logs in through FTP using ++your user name or the name @var{user}. It may ask you for a password ++from time to time (@pxref{Passwords}); this is used for logging in on ++@var{host}. The form using @var{port} allows you to access servers ++running on a non-default TCP port. ++ ++@cindex backups for remote files ++@vindex ange-ftp-make-backup-files ++ If you want to disable backups for remote files, set the variable ++@code{ange-ftp-make-backup-files} to @code{nil}. ++ ++ By default, the auto-save files (@pxref{Auto Save Files}) for remote ++files are made in the temporary file directory on the local machine. ++This is achieved using the variable @code{auto-save-file-name-transforms}. ++ ++@cindex ange-ftp ++@vindex ange-ftp-default-user ++@cindex user name for remote file access ++ Normally, if you do not specify a user name in a remote file name, ++that means to use your own user name. But if you set the variable ++@code{ange-ftp-default-user} to a string, that string is used instead. ++ ++@cindex anonymous FTP ++@vindex ange-ftp-generate-anonymous-password ++ To visit files accessible by anonymous FTP, you use special user ++names @samp{anonymous} or @samp{ftp}. Passwords for these user names ++are handled specially. The variable ++@code{ange-ftp-generate-anonymous-password} controls what happens: if ++the value of this variable is a string, then that string is used as ++the password; if non-@code{nil} (the default), then the value of ++@code{user-mail-address} is used; if @code{nil}, then Emacs prompts ++you for a password as usual (@pxref{Passwords}). ++ ++@cindex firewall, and accessing remote files ++@cindex gateway, and remote file access with @code{ange-ftp} ++@vindex ange-ftp-smart-gateway ++@vindex ange-ftp-gateway-host ++ Sometimes you may be unable to access files on a remote machine ++because a @dfn{firewall} in between blocks the connection for security ++reasons. If you can log in on a @dfn{gateway} machine from which the ++target files @emph{are} accessible, and whose FTP server supports ++gatewaying features, you can still use remote file names; all you have ++to do is specify the name of the gateway machine by setting the ++variable @code{ange-ftp-gateway-host}, and set ++@code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able ++to make remote file names work, but the procedure is complex. You can ++read the instructions by typing @kbd{M-x finder-commentary @key{RET} ++ange-ftp @key{RET}}. ++ ++@node Quoted File Names ++@section Quoted File Names ++ ++@cindex quoting file names ++@cindex file names, quote special characters ++ You can @dfn{quote} an absolute file name to prevent special ++characters and syntax in it from having their special effects. ++The way to do this is to add @samp{/:} at the beginning. ++ ++ For example, you can quote a local file name which appears remote, to ++prevent it from being treated as a remote file name. Thus, if you have ++a directory named @file{/foo:} and a file named @file{bar} in it, you ++can refer to that file in Emacs as @samp{/:/foo:/bar}. ++ ++ @samp{/:} can also prevent @samp{~} from being treated as a special ++character for a user's home directory. For example, @file{/:/tmp/~hack} ++refers to a file whose name is @file{~hack} in directory @file{/tmp}. ++ ++ Quoting with @samp{/:} is also a way to enter in the minibuffer a ++file name that contains @samp{$}. In order for this to work, the ++@samp{/:} must be at the beginning of the minibuffer contents. (You ++can also double each @samp{$}; see @ref{File Names with $}.) ++ ++ You can also quote wildcard characters with @samp{/:}, for visiting. ++For example, @file{/:/tmp/foo*bar} visits the file ++@file{/tmp/foo*bar}. ++ ++ Another method of getting the same result is to enter ++@file{/tmp/foo[*]bar}, which is a wildcard specification that matches ++only @file{/tmp/foo*bar}. However, in many cases there is no need to ++quote the wildcard characters because even unquoted they give the ++right result. For example, if the only file name in @file{/tmp} that ++starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, ++then specifying @file{/tmp/foo*bar} will visit only ++@file{/tmp/foo*bar}. ++ ++@node File Name Cache ++@section File Name Cache ++ ++@cindex file name caching ++@cindex cache of file names ++@pindex find ++@kindex C-@key{TAB} ++@findex file-cache-minibuffer-complete ++ You can use the @dfn{file name cache} to make it easy to locate a ++file by name, without having to remember exactly where it is located. ++When typing a file name in the minibuffer, @kbd{C-@key{tab}} ++(@code{file-cache-minibuffer-complete}) completes it using the file ++name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the ++possible completions of what you had originally typed. (However, note ++that the @kbd{C-@key{tab}} character cannot be typed on most text-only ++terminals.) ++ ++ The file name cache does not fill up automatically. Instead, you ++load file names into the cache using these commands: ++ ++@findex file-cache-add-directory ++@table @kbd ++@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} ++Add each file name in @var{directory} to the file name cache. ++@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} ++Add each file name in @var{directory} and all of its nested ++subdirectories to the file name cache. ++@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} ++Add each file name in @var{directory} and all of its nested ++subdirectories to the file name cache, using @command{locate} to find ++them all. ++@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} ++Add each file name in each directory listed in @var{variable} ++to the file name cache. @var{variable} should be a Lisp variable ++such as @code{load-path} or @code{exec-path}, whose value is a list ++of directory names. ++@item M-x file-cache-clear-cache @key{RET} ++Clear the cache; that is, remove all file names from it. ++@end table ++ ++ The file name cache is not persistent: it is kept and maintained ++only for the duration of the Emacs session. You can view the contents ++of the cache with the @code{file-cache-display} command. ++ ++@node File Conveniences ++@section Convenience Features for Finding Files ++ ++ In this section, we introduce some convenient facilities for finding ++recently-opened files, reading file names from a buffer, and viewing ++image files. ++ ++@findex recentf-mode ++@vindex recentf-mode ++@findex recentf-save-list ++@findex recentf-edit-list ++ If you enable Recentf mode, with @kbd{M-x recentf-mode}, the ++@samp{File} menu includes a submenu containing a list of recently ++opened files. @kbd{M-x recentf-save-list} saves the current ++@code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} ++edits it. ++ ++ The @kbd{M-x ffap} command generalizes @code{find-file} with more ++powerful heuristic defaults (@pxref{FFAP}), often based on the text at ++point. Partial Completion mode offers other features extending ++@code{find-file}, which can be used with @code{ffap}. ++@xref{Completion Options}. ++ ++@findex image-mode ++@findex image-toggle-display ++@cindex images, viewing ++ Visiting image files automatically selects Image mode. This major ++mode allows you to toggle between displaying the file as an image in ++the Emacs buffer, and displaying its underlying text representation, ++using the command @kbd{C-c C-c} (@code{image-toggle-display}). This ++works only when Emacs can display the specific image type. If the ++displayed image is wider or taller than the frame, the usual point ++motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts ++of the image to be displayed. ++ ++@findex thumbs-mode ++@findex mode, thumbs ++ See also the Image-Dired package (@pxref{Image-Dired}) for viewing ++images as thumbnails. ++ ++@node Filesets ++@section Filesets ++@cindex filesets ++ ++@findex filesets-init ++ If you regularly edit a certain group of files, you can define them ++as a @dfn{fileset}. This lets you perform certain operations, such as ++visiting, @code{query-replace}, and shell commands on all the files ++at once. To make use of filesets, you must first add the expression ++@code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}). ++This adds a @samp{Filesets} menu to the menu bar. ++ ++@findex filesets-add-buffer ++@findex filesets-remove-buffer ++ The simplest way to define a fileset is by adding files to it one ++at a time. To add a file to fileset @var{name}, visit the file and ++type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If ++there is no fileset @var{name}, this creates a new one, which ++initially creates only the current file. The command @kbd{M-x ++filesets-remove-buffer} removes the current file from a fileset. ++ ++ You can also edit the list of filesets directly, with @kbd{M-x ++filesets-edit} (or by choosing @samp{Edit Filesets} from the ++@samp{Filesets} menu). The editing is performed in a Customize buffer ++(@pxref{Easy Customization}). Filesets need not be a simple list of ++files---you can also define filesets using regular expression matching ++file names. Some examples of these more complicated filesets are ++shown in the Customize buffer. Remember to select @samp{Save for ++future sessions} if you want to use the same filesets in future Emacs ++sessions. ++ ++ You can use the command @kbd{M-x filesets-open} to visit all the ++files in a fileset, and @kbd{M-x filesets-close} to close them. Use ++@kbd{M-x filesets-run-cmd} to run a shell command on all the files in ++a fileset. These commands are also available from the @samp{Filesets} ++menu, where each existing fileset is represented by a submenu. ++ ++ Emacs uses the concept of a fileset elsewhere @pxref{Version ++Control} to describe sets of files to be treated as a group for ++purposes of version control operations. Those filesets are unnamed ++and do not persist across Emacs sessions. ++ ++@ignore ++ arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250 ++@end ignore +diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi +new file mode 100644 +index 0000000..7acdc59 +--- /dev/null ++++ b/doc/emacs/fixit.texi +@@ -0,0 +1,429 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Fixit, Keyboard Macros, Search, Top ++@chapter Commands for Fixing Typos ++@cindex typos, fixing ++@cindex mistakes, correcting ++ ++ In this chapter we describe the commands that are especially useful ++when you catch a mistake in your text after you have made it, or ++change your mind while composing text on the fly. ++ ++ The most fundamental command for correcting erroneous editing is the ++undo command @kbd{C-/} (which is also bound to @kbd{C-x u} and ++@kbd{C-_}). This undoes a single command, or a part of a command (as ++in the case of @code{query-replace}), or several consecutive ++self-inserting characters. Consecutive repetitions of @kbd{C-/} undo ++earlier and earlier changes, back to the limit of the undo information ++available. ++ ++ Aside from the commands described here, you can erase text using ++deletion commands such as @key{DEL} (@code{delete-backward-char}). ++These were described earlier in this manual. @xref{Erasing}. ++ ++@menu ++* Undo:: The Undo commands. ++* Transpose:: Exchanging two characters, words, lines, lists... ++* Fixing Case:: Correcting case of last word entered. ++* Spelling:: Apply spelling checker to a word, or a whole file. ++@end menu ++ ++@node Undo ++@section Undo ++@cindex undo ++@cindex changes, undoing ++ ++ The @dfn{undo} command reverses recent changes in the buffer's text. ++Each buffer records changes individually, and the undo command always ++applies to the current buffer. You can undo all the changes in a ++buffer for as far as back its records go. Usually, each editing ++command makes a separate entry in the undo records, but some commands ++such as @code{query-replace} divide their changes into multiple ++entries for flexibility in undoing. Consecutive character insertion ++commands are usually grouped together into a single undo record, to ++make undoing less tedious. ++ ++@table @kbd ++@item C-/ ++@itemx C-x u ++@itemx C-_ ++Undo one entry in the current buffer's undo records (@code{undo}). ++@end table ++ ++@kindex C-x u ++@kindex C-_ ++@kindex C-/ ++@findex undo ++ To begin to undo, type @kbd{C-/} (or its aliases, @kbd{C-_} or ++@kbd{C-x u})@footnote{Aside from @kbd{C-/}, the @code{undo} command is ++also bound to @kbd{C-x u} because that is more straightforward for ++beginners to remember: @samp{u} stands for ``undo''. It is also bound ++to @kbd{C-_} because typing @kbd{C-/} on some text-only terminals ++actually enters @kbd{C-_}.}. This undoes the most recent change in ++the buffer, and moves point back to where it was before that change. ++ ++ Consecutive repetitions of @kbd{C-/} (or its aliases) undo earlier ++and earlier changes in the current buffer. If all the recorded ++changes have already been undone, the undo command signals an error. ++ ++@cindex redo ++@findex undo-only ++ Any command other than an undo command breaks the sequence of undo ++commands. Starting from that moment, the entire sequence of undo ++commands that you have just performed are themselves placed into the ++undo record, as a single set of changes. Therefore, to re-apply ++changes you have undone, type @kbd{C-f} or any other command that ++harmlessly breaks the sequence of undoing; then type @kbd{C-/} to undo ++the undo command. ++ ++ On the other hand, if you want to resume undoing, without redoing ++previous undo commands, use @kbd{M-x undo-only}. This is like ++@code{undo}, but will not redo changes you have just undone. ++ ++ If you notice that a buffer has been modified accidentally, the ++easiest way to recover is to type @kbd{C-/} repeatedly until the stars ++disappear from the front of the mode line (@pxref{Mode Line}). ++Whenever an undo command makes the stars disappear from the mode line, ++it means that the buffer contents are the same as they were when the ++file was last read in or saved. If you do not remember whether you ++changed the buffer deliberately, type @kbd{C-/} once. When you see ++the last change you made undone, you will see whether it was an ++intentional change. If it was an accident, leave it undone. If it ++was deliberate, redo the change as described above. ++ ++@cindex selective undo ++@kindex C-u C-/ ++ When there is an active region, any use of @code{undo} performs ++@dfn{selective undo}: it undoes the most recent change within the ++region, instead of the entire buffer. However, when Transient Mark ++mode is off (@pxref{Persistent Mark}), @kbd{C-/} always operates on ++the entire buffer, ignoring the region. In this case, you can perform ++selective undo by supplying a prefix argument to the @code{undo} ++command: @kbd{C-u C-/}. To undo further changes in the same region, ++repeat the @code{undo} command (no prefix argument is needed). ++ ++ Some specialized buffers do not make undo records. Buffers whose ++names start with spaces never do; these buffers are used internally by ++Emacs to hold text that users don't normally look at or edit. ++ ++@vindex undo-limit ++@vindex undo-strong-limit ++@vindex undo-outer-limit ++@cindex undo limit ++ When the undo records for a buffer becomes too large, Emacs discards ++the oldest undo records from time to time (during @dfn{garbage ++collection}). You can specify how much undo records to keep by ++setting the variables @code{undo-limit}, @code{undo-strong-limit}, and ++@code{undo-outer-limit}. Their values are expressed in bytes. ++ ++ The variable @code{undo-limit} sets a soft limit: Emacs keeps undo ++data for enough commands to reach this size, and perhaps exceed it, ++but does not keep data for any earlier commands beyond that. Its ++default value is 80000. The variable @code{undo-strong-limit} sets a ++stricter limit: any previous command (though not the most recent one) ++that pushes the size past this amount is forgotten. The default value ++of @code{undo-strong-limit} is 120000. ++ ++ Regardless of the values of those variables, the most recent change ++is never discarded unless it gets bigger than @code{undo-outer-limit} ++(normally 12,000,000). At that point, Emacs discards the undo data and ++warns you about it. This is the only situation in which you cannot ++undo the last command. If this happens, you can increase the value of ++@code{undo-outer-limit} to make it even less likely to happen in the ++future. But if you didn't expect the command to create such large ++undo data, then it is probably a bug and you should report it. ++@xref{Bugs,, Reporting Bugs}. ++ ++@node Transpose ++@section Transposing Text ++ ++@table @kbd ++@item C-t ++Transpose two characters (@code{transpose-chars}). ++@item M-t ++Transpose two words (@code{transpose-words}). ++@item C-M-t ++Transpose two balanced expressions (@code{transpose-sexps}). ++@item C-x C-t ++Transpose two lines (@code{transpose-lines}). ++@end table ++ ++@kindex C-t ++@findex transpose-chars ++ The common error of transposing two characters can be fixed, when they ++are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally, ++@kbd{C-t} transposes the two characters on either side of point. When ++given at the end of a line, rather than transposing the last character of ++the line with the newline, which would be useless, @kbd{C-t} transposes the ++last two characters on the line. So, if you catch your transposition error ++right away, you can fix it with just a @kbd{C-t}. If you don't catch it so ++fast, you must move the cursor back between the two transposed ++characters before you type @kbd{C-t}. If you transposed a space with ++the last character of the word before it, the word motion commands are ++a good way of getting there. Otherwise, a reverse search (@kbd{C-r}) ++is often the best way. @xref{Search}. ++ ++@kindex C-x C-t ++@findex transpose-lines ++@kindex M-t ++@findex transpose-words ++@c Don't index C-M-t and transpose-sexps here, they are indexed in ++@c programs.texi, in the "List Commands" node. ++@c @kindex C-M-t ++@c @findex transpose-sexps ++ @kbd{M-t} transposes the word before point with the word after point ++(@code{transpose-words}). It moves point forward over a word, ++dragging the word preceding or containing point forward as well. The ++punctuation characters between the words do not move. For example, ++@w{@samp{FOO, BAR}} transposes into @w{@samp{BAR, FOO}} rather than ++@samp{@w{BAR FOO,}}. ++ ++ @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for ++transposing two expressions (@pxref{Expressions}), and @kbd{C-x C-t} ++(@code{transpose-lines}) exchanges lines. They work like @kbd{M-t} ++except as regards what units of text they transpose. ++ ++ A numeric argument to a transpose command serves as a repeat count: it ++tells the transpose command to move the character (word, expression, line) ++before or containing point across several other characters (words, ++expressions, lines). For example, @kbd{C-u 3 C-t} moves the character before ++point forward across three other characters. It would change ++@samp{f@point{}oobar} into @samp{oobf@point{}ar}. This is equivalent to ++repeating @kbd{C-t} three times. @kbd{C-u - 4 M-t} moves the word ++before point backward across four words. @kbd{C-u - C-M-t} would cancel ++the effect of plain @kbd{C-M-t}.@refill ++ ++ A numeric argument of zero is assigned a special meaning (because ++otherwise a command with a repeat count of zero would do nothing): to ++transpose the character (word, expression, line) ending after point ++with the one ending after the mark. ++ ++@node Fixing Case ++@section Case Conversion ++ ++@table @kbd ++@item M-- M-l ++Convert last word to lower case. Note @kbd{Meta--} is Meta-minus. ++@item M-- M-u ++Convert last word to all upper case. ++@item M-- M-c ++Convert last word to lower case with capital initial. ++@end table ++ ++@kindex M-@t{-} M-l ++@kindex M-@t{-} M-u ++@kindex M-@t{-} M-c ++ A very common error is to type words in the wrong case. Because of this, ++the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a ++special feature when used with a negative argument: they do not move the ++cursor. As soon as you see you have mistyped the last word, you can simply ++case-convert it and go on typing. @xref{Case}.@refill ++ ++@node Spelling ++@section Checking and Correcting Spelling ++@cindex spelling, checking and correcting ++@cindex checking spelling ++@cindex correcting spelling ++ ++ This section describes the commands to check the spelling of a ++single word or of a portion of a buffer. These commands only work if ++the spelling checker program Aspell, Ispell or Hunspell is installed. ++Aspell, Ispell or Hunspell are not part of Emacs, but one or the other ++is usually installed in GNU/Linux and other free operating systems. ++@ifnottex ++@xref{Top, Aspell,, aspell, The Aspell Manual}. ++@end ifnottex ++ ++@table @kbd ++@item M-$ ++Check and correct spelling of the active region or the word at point ++(@code{ispell-word}). ++@item M-x ispell ++Check and correct spelling in the active region or the entire buffer. ++@item M-x ispell-buffer ++Check and correct spelling in the buffer. ++@item M-x ispell-region ++Check and correct spelling in the region. ++@item M-x ispell-message ++Check and correct spelling in a draft mail message, excluding cited ++material. ++@item M-x ispell-change-dictionary @key{RET} @var{dict} @key{RET} ++Restart the Aspell/Ispell/Hunspell process, using @var{dict} as the dictionary. ++@item M-x ispell-kill-ispell ++Kill the Aspell/Ispell/Hunspell subprocess. ++@item M-@key{TAB} ++@itemx @key{ESC} @key{TAB} ++Complete the word before point based on the spelling dictionary ++(@code{ispell-complete-word}). ++@item M-x flyspell-mode ++Enable Flyspell mode, which highlights all misspelled words. ++@item M-x flyspell-prog-mode ++Enable Flyspell mode for comments and strings only. ++@end table ++ ++@kindex M-$ ++@findex ispell-word ++ To check the spelling of the word around or before point, and ++optionally correct it as well, type @kbd{M-$} (@code{ispell-word}). ++If a region is active, @kbd{M-$} checks the spelling of all words ++within the region. @xref{Mark}. (When Transient Mark mode is off, ++@kbd{M-$} always acts on the word around or before point, ignoring the ++region. @xref{Persistent Mark}.) ++ ++@findex ispell ++@findex ispell-buffer ++@findex ispell-region ++@cindex spell-checking the active region ++ Similarly, the command @kbd{M-x ispell} performs spell-checking in ++the region if one is active, or in the entire buffer otherwise. The ++commands @kbd{M-x ispell-buffer} and @kbd{M-x ispell-region} ++explicitly perform spell-checking on the entire buffer or the region ++respectively. To check spelling in an email message you are writing, ++use @kbd{M-x ispell-message}; that command checks the whole buffer, ++except for material that is indented or appears to be cited from other ++messages. @xref{Sending Mail}. ++ ++ When one of these commands encounters what appears to be an ++incorrect word, it asks you what to do. It usually displays a list of ++numbered ``near-misses''---words that are close to the incorrect word. ++Then you must type a single-character response. Here are the valid ++responses: ++ ++@table @kbd ++@item @var{digit} ++Replace the word, just this time, with one of the displayed ++near-misses. Each near-miss is listed with a digit; type that digit ++to select it. ++ ++@item @key{SPC} ++Skip this word---continue to consider it incorrect, but don't change it ++here. ++ ++@item r @var{new} @key{RET} ++Replace the word, just this time, with @var{new}. (The replacement ++string will be rescanned for more spelling errors.) ++ ++@item R @var{new} @key{RET} ++Replace the word with @var{new}, and do a @code{query-replace} so you ++can replace it elsewhere in the buffer if you wish. (The replacements ++will be rescanned for more spelling errors.) ++ ++@item a ++Accept the incorrect word---treat it as correct, but only in this ++editing session. ++ ++@item A ++Accept the incorrect word---treat it as correct, but only in this ++editing session and for this buffer. ++ ++@item i ++Insert this word in your private dictionary file so that Aspell or Ispell ++or Hunspell will consider it correct from now on, even in future sessions. ++ ++@item m ++Like @kbd{i}, but you can also specify dictionary completion ++information. ++ ++@item u ++Insert the lower-case version of this word in your private dic@-tion@-ary ++file. ++ ++@item l @var{word} @key{RET} ++Look in the dictionary for words that match @var{word}. These words ++become the new list of ``near-misses''; you can select one of them as ++the replacement by typing a digit. You can use @samp{*} in @var{word} as a ++wildcard. ++ ++@item C-g ++@itemx X ++Quit interactive spell checking, leaving point at the word that was ++being checked. You can restart checking again afterward with @kbd{C-u ++M-$}. ++ ++@item x ++Quit interactive spell checking and move point back to where it was ++when you started spell checking. ++ ++@item q ++Quit interactive spell checking and kill the Aspell/Ispell/Hunspell ++subprocess. ++ ++@item ? ++Show the list of options. ++@end table ++ ++@findex ispell-complete-word ++ In Text mode and related modes, the command @kbd{M-@key{TAB}} ++(@code{ispell-complete-word}) shows a list of completions based on ++spelling correction. Insert the beginning of a word, and then type ++@kbd{M-@key{TAB}}; the command displays a completion list window. (If ++your window manager intercepts @kbd{M-@key{TAB}}, type @kbd{@key{ESC} ++@key{TAB}} or @kbd{C-M-i}.) To choose one of the completions listed, ++click @kbd{Mouse-2} or @kbd{Mouse-1} fast on it, or move the cursor ++there in the completions window and type @key{RET}. @xref{Text Mode}. ++ ++@cindex @code{ispell} program ++@findex ispell-kill-ispell ++ Once started, the Aspell or Ispell or Hunspell subprocess continues ++to run, waiting for something to do, so that subsequent spell checking ++commands complete more quickly. If you want to get rid of the ++process, use @kbd{M-x ispell-kill-ispell}. This is not usually ++necessary, since the process uses no time except when you do spelling ++correction. ++ ++@vindex ispell-dictionary ++@vindex ispell-local-dictionary ++@vindex ispell-personal-dictionary ++@vindex ispell-complete-word-dict ++ Ispell, Aspell and Hunspell use two dictionaries together for spell checking: ++the standard dictionary and your private dictionary. The standard ++dictionary is specified by @code{ispell-local-dictionary} or, ++if @code{nil}, by @code{ispell-dictionary}. If both are @code{nil} ++the default dictionary is selected. The command ++@kbd{M-x ispell-change-dictionary} sets the standard dictionary for ++the buffer and then restarts the subprocess, so that it will use a ++different standard dictionary. Personal dictionary is specified by ++@code{ispell-personal-dictionary}. If @code{nil}, default value is ++used. ++ ++ Set variable @code{ispell-dictionary} to select a specific default ++dictionary for all your documents. Set variable ++@code{ispell-local-dictionary} in the local variables section to ++select a specific dictionary for a given document. ++ ++ A separate dictionary is used for word completion. The variable ++@code{ispell-complete-word-dict} specifies the file name of this ++dictionary. The completion dictionary must be different because it ++cannot use root and affix information. For some languages, there ++is a spell checking dictionary but no word completion dictionary. ++ ++@cindex Flyspell mode ++@findex flyspell-mode ++ Flyspell mode is a fully-automatic way to check spelling as you edit ++in Emacs. It operates by checking words as you change or insert them. ++When it finds a word that it does not recognize, it highlights that ++word. This does not interfere with your editing, but when you see the ++highlighted word, you can move to it and fix it. Type @kbd{M-x ++flyspell-mode} to enable or disable this mode in the current buffer. ++@findex turn-on-flyspell ++To enable @code{flyspell-mode} in all text mode buffers, add ++@code{turn-on-flyspell} to @code{text-mode-hook}. ++ ++ ++ When Flyspell mode highlights a word as misspelled, you can click on ++it with @kbd{Mouse-2} to display a menu of possible corrections and ++actions. You can also correct the word by editing it manually in any ++way you like. ++ ++@findex flyspell-prog-mode ++ Flyspell Prog mode works just like ordinary Flyspell mode, except ++that it only checks words in comments and string constants. This ++feature is useful for editing programs. Type @kbd{M-x ++flyspell-prog-mode} to enable or disable this mode in the current ++buffer. ++ ++@ignore ++ arch-tag: 3359a443-96ed-448f-9f05-c8111ba8eac0 ++@end ignore +diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi +new file mode 100644 +index 0000000..e501fe0 +--- /dev/null ++++ b/doc/emacs/fortran-xtra.texi +@@ -0,0 +1,587 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@c This file is included either in emacs-xtra.texi (when producing the ++@c printed version) or in the main Emacs manual (for the on-line version). ++@node Fortran ++@section Fortran Mode ++@cindex Fortran mode ++@cindex mode, Fortran ++ ++@cindex Fortran fixed form and free form ++@cindex Fortran 77 and Fortran 90, 95, 2003 ++@findex f90-mode ++@findex fortran-mode ++ Fortran mode is meant for editing ``fixed form'' (and also ``tab ++format'') source code (normally Fortran 77). For editing more modern ++``free form'' source code (Fortran 90, 95, 2003), use F90 mode ++(@code{f90-mode}). Emacs normally uses Fortran mode for files with ++extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode for the ++extensions @samp{.f90} and @samp{.f95}. Customize ++@code{auto-mode-alist} to add more extensions. GNU Fortran supports ++both free and fixed form. This manual mainly documents Fortran mode, ++but the corresponding F90 mode features are mentioned when revelant. ++ ++ Fortran mode provides special motion commands for Fortran statements ++and subprograms, and indentation commands that understand Fortran ++conventions of nesting, line numbers and continuation statements. ++Fortran mode has support for Auto Fill mode that breaks long lines into ++proper Fortran continuation lines. Fortran mode also supports Hideshow ++minor mode ++@iftex ++(@pxref{Hideshow,,, emacs, the Emacs Manual}), ++@end iftex ++@ifnottex ++(@pxref{Hideshow}), ++@end ifnottex ++and Imenu ++@iftex ++(@pxref{Imenu,,, emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Imenu}). ++@end ifnottex ++ ++ Special commands for comments are provided because Fortran comments ++are unlike those of other languages. Built-in abbrevs optionally save ++typing when you insert Fortran keywords. ++ ++ Use @kbd{M-x fortran-mode} to switch to this major mode. This ++command runs the hook @code{fortran-mode-hook}. ++@iftex ++@xref{Hooks,,, emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++@xref{Hooks}. ++@end ifnottex ++ ++@menu ++* Motion: Fortran Motion. Moving point by statements or subprograms. ++* Indent: Fortran Indent. Indentation commands for Fortran. ++* Comments: Fortran Comments. Inserting and aligning comments. ++* Autofill: Fortran Autofill. Auto fill support for Fortran. ++* Columns: Fortran Columns. Measuring columns for valid Fortran. ++* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. ++@end menu ++ ++@node Fortran Motion ++@subsection Motion Commands ++ ++ In addition to the normal commands for moving by and operating on ++``defuns'' (Fortran subprograms---functions and subroutines, using the ++commands @code{fortran-beginning-of-subprogram} and ++@code{fortran-end-of-subprogram}; as well as modules for F90 mode), ++Fortran mode provides special commands to move by statements and other ++program units. ++ ++@table @kbd ++@kindex C-c C-n @r{(Fortran mode)} ++@findex fortran-next-statement ++@findex f90-next-statement ++@item C-c C-n ++Move to the beginning of the next statement ++(@code{fortran-next-statement}/@code{f90-next-statement}). ++ ++@kindex C-c C-p @r{(Fortran mode)} ++@findex fortran-previous-statement ++@findex f90-previous-statement ++@item C-c C-p ++Move to the beginning of the previous statement ++(@code{fortran-previous-statement}/@code{f90-previous-statement}). ++If there is no previous statement (i.e. if called from the first ++statement in the buffer), move to the start of the buffer. ++ ++@kindex C-c C-e @r{(F90 mode)} ++@findex f90-next-block ++@item C-c C-e ++Move point forward to the start of the next code block, or the end of ++the current block, whichever is encountered first. ++(@code{f90-next-block}). A code block is a subroutine, ++@code{if}--@code{endif} statement, and so forth. This command exists ++for F90 mode only, not Fortran mode. With a numeric argument, this ++moves forward that many blocks. ++ ++@kindex C-c C-a @r{(F90 mode)} ++@findex f90-previous-block ++@item C-c C-a ++Move point backward to the previous code block ++(@code{f90-previous-block}). This is like @code{f90-next-block}, but ++moves backwards. ++ ++@kindex C-M-n @r{(Fortran mode)} ++@findex fortran-end-of-block ++@findex f90-end-of-block ++@item C-M-n ++Move to the end of the current code block ++(@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric ++argument, move forward that number of blocks. The mark is set before ++moving point. The F90 mode version of this command checks for ++consistency of block types and labels (if present), but it does not ++check the outermost block since that may be incomplete. ++ ++@kindex C-M-p @r{(Fortran mode)} ++@findex fortran-beginning-of-block ++@findex f90-beginning-of-block ++@item C-M-p ++Move to the start of the current code block ++(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This ++is like @code{fortran-end-of-block}, but moves backwards. ++@end table ++ ++The commands @code{fortran-beginning-of-subprogram} and ++@code{fortran-end-of-subprogram} move to the start or end of the ++current subprogram, respectively. The commands @code{fortran-mark-do} ++and @code{fortran-mark-if} mark the end of the current @code{do} or ++@code{if} block, and move point to the start. ++ ++ ++@node Fortran Indent ++@subsection Fortran Indentation ++ ++ Special commands and features are needed for indenting fixed (or tab) ++form Fortran code in order to make sure various syntactic entities (line ++numbers, comment line indicators and continuation line flags) appear in ++the required columns. ++ ++@menu ++* Commands: ForIndent Commands. Commands for indenting and filling Fortran. ++* Contline: ForIndent Cont. How continuation lines indent. ++* Numbers: ForIndent Num. How line numbers auto-indent. ++* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. ++* Vars: ForIndent Vars. Variables controlling Fortran indent style. ++@end menu ++ ++@node ForIndent Commands ++@subsubsection Fortran Indentation and Filling Commands ++ ++@table @kbd ++@item C-M-j ++Break the current line at point and set up a continuation line ++(@code{fortran-split-line}). ++@item M-^ ++Join this line to the previous line (@code{fortran-join-line}). ++@item C-M-q ++Indent all the lines of the subprogram point is in ++(@code{fortran-indent-subprogram}). ++@item M-q ++Fill a comment block or statement (using @code{fortran-fill-paragraph} ++or @code{fortran-fill-statement}). ++@end table ++ ++@kindex C-M-q @r{(Fortran mode)} ++@findex fortran-indent-subprogram ++ The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command ++to reindent all the lines of the Fortran subprogram (function or ++subroutine) containing point. ++ ++@kindex C-M-j @r{(Fortran mode)} ++@findex fortran-split-line ++ The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits ++a line in the appropriate fashion for Fortran. In a non-comment line, ++the second half becomes a continuation line and is indented ++accordingly. In a comment line, both halves become separate comment ++lines. ++ ++@kindex M-^ @r{(Fortran mode)} ++@kindex C-c C-d @r{(Fortran mode)} ++@findex fortran-join-line ++ @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, ++which joins a continuation line back to the previous line, roughly as ++the inverse of @code{fortran-split-line}. The point must be on a ++continuation line when this command is invoked. ++ ++@kindex M-q @r{(Fortran mode)} ++@kbd{M-q} in Fortran mode fills the comment block or statement that ++point is in. This removes any excess statement continuations. ++ ++@node ForIndent Cont ++@subsubsection Continuation Lines ++@cindex Fortran continuation lines ++ ++@vindex fortran-continuation-string ++ Most Fortran 77 compilers allow two ways of writing continuation lines. ++If the first non-space character on a line is in column 5, then that ++line is a continuation of the previous line. We call this @dfn{fixed ++form}. (In GNU Emacs we always count columns from 0; but note that ++the Fortran standard counts from 1.) The variable ++@code{fortran-continuation-string} specifies what character to put in ++column 5. A line that starts with a tab character followed by any digit ++except @samp{0} is also a continuation line. We call this style of ++continuation @dfn{tab format}. (Fortran 90 introduced ``free form,'' ++with another style of continuation lines). ++ ++@vindex indent-tabs-mode @r{(Fortran mode)} ++@vindex fortran-analyze-depth ++@vindex fortran-tab-mode-default ++ Fortran mode can use either style of continuation line. When you ++enter Fortran mode, it tries to deduce the proper continuation style ++automatically from the buffer contents. It does this by scanning up to ++@code{fortran-analyze-depth} (default 100) lines from the start of the ++buffer. The first line that begins with either a tab character or six ++spaces determines the choice. If the scan fails (for example, if the ++buffer is new and therefore empty), the value of ++@code{fortran-tab-mode-default} (@code{nil} for fixed form, and ++non-@code{nil} for tab format) is used. @samp{/t} ++(@code{fortran-tab-mode-string}) in the mode line indicates tab format ++is selected. Fortran mode sets the value of @code{indent-tabs-mode} ++accordingly. ++ ++ If the text on a line starts with the Fortran continuation marker ++@samp{$}, or if it begins with any non-whitespace character in column ++5, Fortran mode treats it as a continuation line. When you indent a ++continuation line with @key{TAB}, it converts the line to the current ++continuation style. When you split a Fortran statement with ++@kbd{C-M-j}, the continuation marker on the newline is created according ++to the continuation style. ++ ++ The setting of continuation style affects several other aspects of ++editing in Fortran mode. In fixed form mode, the minimum column ++number for the body of a statement is 6. Lines inside of Fortran ++blocks that are indented to larger column numbers always use only the ++space character for whitespace. In tab format mode, the minimum ++column number for the statement body is 8, and the whitespace before ++column 8 must always consist of one tab character. ++ ++@node ForIndent Num ++@subsubsection Line Numbers ++ ++ If a number is the first non-whitespace in the line, Fortran ++indentation assumes it is a line number and moves it to columns 0 ++through 4. (Columns always count from 0 in GNU Emacs.) ++ ++@vindex fortran-line-number-indent ++ Line numbers of four digits or less are normally indented one space. ++The variable @code{fortran-line-number-indent} controls this; it ++specifies the maximum indentation a line number can have. The default ++value of the variable is 1. Fortran mode tries to prevent line number ++digits passing column 4, reducing the indentation below the specified ++maximum if necessary. If @code{fortran-line-number-indent} has the ++value 5, line numbers are right-justified to end in column 4. ++ ++@vindex fortran-electric-line-number ++ Simply inserting a line number is enough to indent it according to ++these rules. As each digit is inserted, the indentation is recomputed. ++To turn off this feature, set the variable ++@code{fortran-electric-line-number} to @code{nil}. ++ ++ ++@node ForIndent Conv ++@subsubsection Syntactic Conventions ++ ++ Fortran mode assumes that you follow certain conventions that simplify ++the task of understanding a Fortran program well enough to indent it ++properly: ++ ++@itemize @bullet ++@item ++Two nested @samp{do} loops never share a @samp{continue} statement. ++ ++@item ++Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} ++and others are written without embedded whitespace or line breaks. ++ ++Fortran compilers generally ignore whitespace outside of string ++constants, but Fortran mode does not recognize these keywords if they ++are not contiguous. Constructs such as @samp{else if} or @samp{end do} ++are acceptable, but the second word should be on the same line as the ++first and not on a continuation line. ++@end itemize ++ ++@noindent ++If you fail to follow these conventions, the indentation commands may ++indent some lines unaesthetically. However, a correct Fortran program ++retains its meaning when reindented even if the conventions are not ++followed. ++ ++@node ForIndent Vars ++@subsubsection Variables for Fortran Indentation ++ ++@vindex fortran-do-indent ++@vindex fortran-if-indent ++@vindex fortran-structure-indent ++@vindex fortran-continuation-indent ++@vindex fortran-check-all-num@dots{} ++@vindex fortran-minimum-statement-indent@dots{} ++ Several additional variables control how Fortran indentation works: ++ ++@table @code ++@item fortran-do-indent ++Extra indentation within each level of @samp{do} statement (default 3). ++ ++@item fortran-if-indent ++Extra indentation within each level of @samp{if}, @samp{select case}, or ++@samp{where} statements (default 3). ++ ++@item fortran-structure-indent ++Extra indentation within each level of @samp{structure}, @samp{union}, ++@samp{map}, or @samp{interface} statements (default 3). ++ ++@item fortran-continuation-indent ++Extra indentation for bodies of continuation lines (default 5). ++ ++@item fortran-check-all-num-for-matching-do ++In Fortran 77, a numbered @samp{do} statement is ended by any statement ++with a matching line number. It is common (but not compulsory) to use a ++@samp{continue} statement for this purpose. If this variable has a ++non-@code{nil} value, indenting any numbered statement must check for a ++@samp{do} that ends there. If you always end @samp{do} statements with ++a @samp{continue} line (or if you use the more modern @samp{enddo}), ++then you can speed up indentation by setting this variable to ++@code{nil}. The default is @code{nil}. ++ ++@item fortran-blink-matching-if ++If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} ++statement moves the cursor momentarily to the matching @samp{if} (or ++@samp{do}) statement to show where it is. The default is @code{nil}. ++ ++@item fortran-minimum-statement-indent-fixed ++Minimum indentation for Fortran statements when using fixed form ++continuation line style. Statement bodies are never indented less than ++this much. The default is 6. ++ ++@item fortran-minimum-statement-indent-tab ++Minimum indentation for Fortran statements for tab format continuation line ++style. Statement bodies are never indented less than this much. The ++default is 8. ++@end table ++ ++The variables controlling the indentation of comments are described in ++the following section. ++ ++@node Fortran Comments ++@subsection Fortran Comments ++ ++ The usual Emacs comment commands assume that a comment can follow a ++line of code. In Fortran 77, the standard comment syntax requires an ++entire line to be just a comment. Therefore, Fortran mode replaces the ++standard Emacs comment commands and defines some new variables. ++ ++@vindex fortran-comment-line-start ++ Fortran mode can also handle the Fortran 90 comment syntax where ++comments start with @samp{!} and can follow other text. Because only ++some Fortran 77 compilers accept this syntax, Fortran mode will not ++insert such comments unless you have said in advance to do so. To do ++this, set the variable @code{fortran-comment-line-start} to @samp{"!"}. ++If you use an unusual value, you may also need to adjust ++@code{fortran-comment-line-start-skip}. ++ ++ ++@table @kbd ++@item M-; ++Align comment or insert new comment (@code{comment-dwim}). ++ ++@item C-x ; ++Applies to nonstandard @samp{!} comments only. ++ ++@item C-c ; ++Turn all lines of the region into comments, or (with argument) turn them back ++into real code (@code{fortran-comment-region}). ++@end table ++ ++ @kbd{M-;} in Fortran mode runs the standard @code{comment-dwim}. ++This recognizes any kind of existing comment and aligns its text ++appropriately; if there is no existing comment, a comment is inserted ++and aligned. Inserting and aligning comments are not the same in ++Fortran mode as in other modes. ++ ++ When a new comment must be inserted, if the current line is blank, a ++full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} ++comment is inserted if you have said you want to use them. Otherwise a ++full-line comment is inserted on a new line before the current line. ++ ++ Nonstandard @samp{!} comments are aligned like comments in other ++languages, but full-line comments are different. In a standard full-line ++comment, the comment delimiter itself must always appear in column zero. ++What can be aligned is the text within the comment. You can choose from ++three styles of alignment by setting the variable ++@code{fortran-comment-indent-style} to one of these values: ++ ++@vindex fortran-comment-indent-style ++@vindex fortran-comment-line-extra-indent ++@table @code ++@item fixed ++Align the text at a fixed column, which is the sum of ++@code{fortran-comment-line-extra-indent} and the minimum statement ++indentation. This is the default. ++ ++The minimum statement indentation is ++@code{fortran-minimum-statement-indent-fixed} for fixed form ++continuation line style and @code{fortran-minimum-statement-indent-tab} ++for tab format style. ++ ++@item relative ++Align the text as if it were a line of code, but with an additional ++@code{fortran-comment-line-extra-indent} columns of indentation. ++ ++@item nil ++Don't move text in full-line comments automatically. ++@end table ++ ++@vindex fortran-comment-indent-char ++ In addition, you can specify the character to be used to indent within ++full-line comments by setting the variable ++@code{fortran-comment-indent-char} to the single-character string you want ++to use. ++ ++@vindex fortran-directive-re ++ Compiler directive lines, or preprocessor lines, have much the same ++appearance as comment lines. It is important, though, that such lines ++never be indented at all, no matter what the value of ++@code{fortran-comment-indent-style}. The variable ++@code{fortran-directive-re} is a regular expression that specifies which ++lines are directives. Matching lines are never indented, and receive ++distinctive font-locking. ++ ++ The normal Emacs comment command @kbd{C-x ;} has not been redefined. If ++you use @samp{!} comments, this command can be used with them. Otherwise ++it is useless in Fortran mode. ++ ++@kindex C-c ; @r{(Fortran mode)} ++@findex fortran-comment-region ++@vindex fortran-comment-region ++ The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the ++lines of the region into comments by inserting the string @samp{C$$$} at ++the front of each one. With a numeric argument, it turns the region ++back into live code by deleting @samp{C$$$} from the front of each line ++in it. The string used for these comments can be controlled by setting ++the variable @code{fortran-comment-region}. Note that here we have an ++example of a command and a variable with the same name; these two uses ++of the name never conflict because in Lisp and in Emacs it is always ++clear from the context which one is meant. ++ ++@node Fortran Autofill ++@subsection Auto Fill in Fortran Mode ++ ++ Fortran mode has specialized support for Auto Fill mode, which is a ++minor mode that automatically splits statements as you insert them ++when they become too wide. Splitting a statement involves making ++continuation lines using @code{fortran-continuation-string} ++(@pxref{ForIndent Cont}). This splitting happens when you type ++@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran ++indentation commands. You activate Auto Fill in Fortran mode in the ++normal way. ++@iftex ++@xref{Auto Fill,,, emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++@xref{Auto Fill}. ++@end ifnottex ++ ++@vindex fortran-break-before-delimiters ++ Auto Fill breaks lines at spaces or delimiters when the lines get ++longer than the desired width (the value of @code{fill-column}). The ++delimiters (besides whitespace) that Auto Fill can break at are ++@samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>}, ++and @samp{,}. The line break comes after the delimiter if the ++variable @code{fortran-break-before-delimiters} is @code{nil}. ++Otherwise (and by default), the break comes before the delimiter. ++ ++ To enable Auto Fill in all Fortran buffers, add ++@code{turn-on-auto-fill} to @code{fortran-mode-hook}. ++@iftex ++@xref{Hooks,,, emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++@xref{Hooks}. ++@end ifnottex ++ ++@node Fortran Columns ++@subsection Checking Columns in Fortran ++ ++@vindex fortran-line-length ++In standard Fortran 77, anything beyond column 72 is ignored. ++Most compilers provide an option to change this (for example, ++@samp{-ffixed-line-length-N} in gfortran). Customize the variable ++@code{fortran-line-length} to change the line length in Fortran mode. ++Anything beyond this point is font-locked as a comment. (Unless it is ++inside a string: strings that extend beyond @code{fortran-line-length} ++will confuse font-lock.) ++ ++@table @kbd ++@item C-c C-r ++Display a ``column ruler'' momentarily above the current line ++(@code{fortran-column-ruler}). ++@item C-c C-w ++Split the current window horizontally temporarily so that it is ++@code{fortran-line-length} columns wide ++(@code{fortran-window-create-momentarily}). This may help you avoid ++making lines longer than the character limit imposed by your Fortran ++compiler. ++@item C-u C-c C-w ++Split the current window horizontally so that it is ++@code{fortran-line-length} columns wide (@code{fortran-window-create}). ++You can then continue editing. ++@item M-x fortran-strip-sequence-nos ++Delete all text in column @code{fortran-line-length} and beyond. ++@end table ++ ++@kindex C-c C-r @r{(Fortran mode)} ++@findex fortran-column-ruler ++ The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column ++ruler momentarily above the current line. The comment ruler is two lines ++of text that show you the locations of columns with special significance in ++Fortran programs. Square brackets show the limits of the columns for line ++numbers, and curly brackets show the limits of the columns for the ++statement body. Column numbers appear above them. ++ ++ Note that the column numbers count from zero, as always in GNU Emacs. ++As a result, the numbers may be one less than those you are familiar ++with; but the positions they indicate in the line are standard for ++Fortran. ++ ++@vindex fortran-column-ruler-fixed ++@vindex fortran-column-ruler-tabs ++ The text used to display the column ruler depends on the value of the ++variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is ++@code{nil}, then the value of the variable ++@code{fortran-column-ruler-fixed} is used as the column ruler. ++Otherwise, the value of the variable @code{fortran-column-ruler-tab} is ++displayed. By changing these variables, you can change the column ruler ++display. ++ ++@kindex C-c C-w @r{(Fortran mode)} ++@findex fortran-window-create-momentarily ++ @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily ++splits the current window horizontally, making a window ++@code{fortran-line-length} columns wide, so you can see any lines that ++are too long. Type a space to restore the normal width. ++ ++@kindex C-u C-c C-w @r{(Fortran mode)} ++@findex fortran-window-create ++ You can also split the window horizontally and continue editing with ++the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x ++fortran-window-create}). By editing in this window you can ++immediately see when you make a line too wide to be correct Fortran. ++ ++@findex fortran-strip-sequence-nos ++ The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in ++column @code{fortran-line-length} and beyond, on all lines in the ++current buffer. This is the easiest way to get rid of old sequence ++numbers. ++ ++@node Fortran Abbrev ++@subsection Fortran Keyword Abbrevs ++ ++ Fortran mode provides many built-in abbrevs for common keywords and ++declarations. These are the same sort of abbrev that you can define ++yourself. To use them, you must turn on Abbrev mode. ++@iftex ++@xref{Abbrevs,,, emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++@xref{Abbrevs}. ++@end ifnottex ++ ++ The built-in abbrevs are unusual in one way: they all start with a ++semicolon. For example, one built-in Fortran abbrev is @samp{;c} for ++@samp{continue}. If you insert @samp{;c} and then insert a punctuation ++character such as a space or a newline, the @samp{;c} expands automatically ++to @samp{continue}, provided Abbrev mode is enabled.@refill ++ ++ Type @samp{;?} or @samp{;C-h} to display a list of all the built-in ++Fortran abbrevs and what they stand for. ++ ++@ignore ++ arch-tag: 23ed7c36-1517-4646-9235-2d5ade5f06f6 ++@end ignore +diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi +new file mode 100644 +index 0000000..a74345f +--- /dev/null ++++ b/doc/emacs/frames.texi +@@ -0,0 +1,1130 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, ++@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Frames, International, Windows, Top ++@chapter Frames and Graphical Displays ++@cindex frames ++ ++ When using a graphical display, you can create multiple system-level ++``windows'' in a single Emacs session. We refer to these system-level ++windows as @dfn{frames}. A frame initially contains a single Emacs ++window; however, you can subdivide this Emacs window into smaller ++windows, all fitting into the same frame. Each frame normally ++contains its own echo area and minibuffer. ++ ++ To avoid confusion, we reserve the word ``window'' for the ++subdivisions that Emacs implements, and never use it to refer to a ++frame. ++ ++ Any editing you do in one frame affects the other frames. For ++instance, if you put text in the kill ring in one frame, you can yank ++it in another frame. If you exit Emacs through @kbd{C-x C-c} in one ++frame, it terminates all the frames. To delete just one frame, use ++@kbd{C-x 5 0} (that is zero, not @kbd{o}). ++ ++ Emacs compiled for MS-DOS emulates some windowing functionality, ++so that you can use many of the features described in this chapter. ++@iftex ++@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}. ++@end iftex ++@ifnottex ++@xref{MS-DOS Mouse}. ++@end ifnottex ++ ++@menu ++* Cut and Paste:: Mouse commands for cut and paste. ++* Mouse References:: Using the mouse to select an item from a list. ++* Menu Mouse Clicks:: Mouse clicks that bring up menus. ++* Mode Line Mouse:: Mouse clicks on the mode line. ++* Creating Frames:: Creating additional Emacs frames with various contents. ++* Frame Commands:: Iconifying, deleting, and switching frames. ++* Speedbar:: How to make and use a speedbar frame. ++* Multiple Displays:: How one Emacs job can talk to several displays. ++* Special Buffer Frames:: You can make certain buffers have their own frames. ++* Frame Parameters:: Changing the colors and other modes of frames. ++* Scroll Bars:: How to enable and disable scroll bars; how to use them. ++* Wheeled Mice:: Using mouse wheels for scrolling. ++* Drag and Drop:: Using drag and drop to open files and insert text. ++* Menu Bars:: Enabling and disabling the menu bar. ++* Tool Bars:: Enabling and disabling the tool bar. ++* Dialog Boxes:: Controlling use of dialog boxes. ++* Tooltips:: Displaying information at the current mouse position. ++* Mouse Avoidance:: Moving the mouse pointer out of the way. ++* Non-Window Terminals:: Multiple frames on terminals that show only one. ++* Text-Only Mouse:: Using the mouse in text-only terminals. ++@end menu ++ ++@node Cut and Paste ++@section Killing and Yanking on Graphical Displays ++ ++ This section describes commands for selecting a region, killing, and ++yanking using the mouse. ++ ++@menu ++* Mouse Commands:: Moving, cutting, and pasting, with the mouse. ++* Word and Line Mouse:: Mouse commands for selecting whole words or lines. ++* Cut/Paste Other App:: Transfering text between Emacs and other apps. ++* Secondary Selection:: Cutting without altering point and mark. ++* Clipboard:: Using the clipboard for selections. ++@end menu ++ ++@node Mouse Commands ++@subsection Mouse Commands for Editing ++@cindex mouse buttons (what they do) ++ ++@kindex Mouse-1 ++@kindex Mouse-2 ++@kindex Mouse-3 ++@table @kbd ++@item Mouse-1 ++Move point to where you click (@code{mouse-set-point}). ++ ++@item Drag-Mouse-1 ++Activate the region around the text selected by dragging, and copy it ++to the kill ring (@code{mouse-set-region}). ++ ++@item Mouse-2 ++Yank the last killed text at the click position ++(@code{mouse-yank-at-click}). ++ ++@item Mouse-3 ++If the region is active, move the nearer end of the region to the ++click position; otherwise, set mark at the current value of point and ++point at the click position. Save the resulting region in the kill ++ring; on a second click, kill it (@code{mouse-save-then-kill}). ++@end table ++ ++@findex mouse-set-point ++ The most basic mouse command is @code{mouse-set-point}, which is ++called by clicking with the left mouse button, @kbd{Mouse-1}, in the ++text area of a window. This moves point to the position where you ++clicked. ++ ++@vindex x-mouse-click-focus-ignore-position ++ Normally, Emacs does not distinguish between ordinary mouse clicks ++and clicks that select a frame. When you click on a frame to select ++it, that also changes the selected window and cursor position ++according to the mouse click position. On the X window system, you ++can change this behavior by setting the variable ++@code{x-mouse-click-focus-ignore-position} to @code{t}. Then the ++first click selects the frame, but does not affect the selected window ++or cursor position. If you click again in the same place, that click ++will be in the selected frame, so it will change the window or cursor ++position. ++ ++@findex mouse-set-region ++@vindex mouse-drag-copy-region ++ Holding down @kbd{Mouse-1} and ``dragging'' the mouse over a stretch ++of text activates the region around that text ++(@code{mouse-set-region}). @xref{Mark}. Emacs places the mark where ++you started holding down the mouse button, and point where you release ++it. In addition, the region is copied into the kill ring (@pxref{Kill ++Ring}). If you don't want Emacs to copy the region, change the ++variable @code{mouse-drag-copy-region} to @code{nil}. ++ ++@vindex mouse-scroll-min-lines ++ If you move the mouse off the top or bottom of the window while ++dragging, the window scrolls at a steady rate until you move the mouse ++back into the window. This way, you can select regions that don't fit ++entirely on the screen. The number of lines scrolled per step depends ++on how far away from the window edge the mouse has gone; the variable ++@code{mouse-scroll-min-lines} specifies a minimum step size. ++ ++@findex mouse-yank-at-click ++@vindex mouse-yank-at-point ++ Clicking with the middle mouse button, @kbd{Mouse-2}, moves point to ++the position where you clicked and performs a yank ++(@code{mouse-yank-at-click}). @xref{Yanking}. If you change the ++variable @code{mouse-yank-at-point} to a non-@code{nil} value, ++@kbd{Mouse-2} does not move point. Then it does not matter where you ++click, or even which of the frame's windows you click on; the yank ++occurs at the existing point. This variable also affects yanking the ++primary and secondary selections (@pxref{Cut/Paste Other App}). ++ ++@findex mouse-save-then-kill ++ Clicking with the right mouse button, @kbd{Mouse-3}, runs the ++command @code{mouse-save-then-kill}. This performs several actions ++depending on where you click and the status of the region: ++ ++@itemize @bullet ++@item ++If no region is active, clicking @kbd{Mouse-3} activates the region, ++placing the mark where point was and point at the clicked position. ++In addition, the text in the region is copied to the kill ring. ++ ++@item ++If a region is active, clicking @kbd{Mouse-3} adjusts the nearer end ++of the region by moving it to the clicked position. The adjusted ++region's text is copied to the kill ring; if the text in the original ++region was already on the kill ring, it replaces it there. ++ ++@item ++If you originally specified the region using a double or triple ++@kbd{Mouse-1}, so that the region is defined to consist of entire ++words or lines, then adjusting the region with @kbd{Mouse-3} also ++proceeds by entire words or lines. ++ ++@item ++If you use @kbd{Mouse-3} a second time consecutively, at the same ++place, that kills the region already selected. Thus, the simplest way ++to kill text with the mouse is to click @kbd{Mouse-1} at one end, then ++click @kbd{Mouse-3} twice at the other end. To copy the text into the ++kill ring without deleting it from the buffer, press @kbd{Mouse-3} ++just once---or just drag across the text with @kbd{Mouse-1}. Then you ++can copy it elsewhere by yanking it. ++@end itemize ++ ++ Whenever you set the region using any of the mouse commands ++described above, the mark will be deactivated by any subsequent ++unshifted cursor motion command, in addition to the usual ways of ++deactivating the mark. @xref{Shift Selection}. While the region ++remains active, typing @key{Backspace} or @key{Delete} deletes the ++text in that region and deactivates the mark; this behavior follows a ++convention established by other graphical programs, and it does ++@emph{not} apply when you set the region any other way, including ++shift-selection (@pxref{Shift Selection}). ++ ++@cindex Delete Selection mode ++@cindex mode, Delete Selection ++@findex delete-selection-mode ++ Many graphical applications also follow the convention that ++insertion while text is selected deletes the selected text. You can ++make Emacs behave this way by enabling Delete Selection mode. ++@xref{Using Region}. ++ ++@node Word and Line Mouse ++@subsection Mouse Commands for Words and Lines ++ ++ These variants of @kbd{Mouse-1} select entire words or lines at a ++time. Emacs activates the region around the selected text, which is ++also copied to the kill ring. ++ ++@table @kbd ++@item Double-Mouse-1 ++Select the text around the word which you click on. ++ ++Double-clicking on a character with ``symbol'' syntax (such as ++underscore, in C mode) selects the symbol surrounding that character. ++Double-clicking on a character with open- or close-parenthesis syntax ++selects the parenthetical grouping which that character starts or ++ends. Double-clicking on a character with string-delimiter syntax ++(such as a singlequote or doublequote in C) selects the string ++constant (Emacs uses heuristics to figure out whether that character ++is the beginning or the end of it). ++ ++@item Double-Drag-Mouse-1 ++Select the text you drag across, in the form of whole words. ++ ++@item Triple-Mouse-1 ++Select the line you click on. ++ ++@item Triple-Drag-Mouse-1 ++Select the text you drag across, in the form of whole lines. ++@end table ++ ++@node Cut/Paste Other App ++@subsection Cut and Paste with Other Window Applications ++ ++@cindex X cutting and pasting ++@cindex X selection ++@cindex primary selection ++@cindex selection, primary ++ When running Emacs under the X window system, you can easily ++transfer text between Emacs and other X applications using the ++@dfn{primary selection} (also called the @dfn{X selection}). This is ++@emph{not} the same thing as the @dfn{clipboard}, which is a separate ++facility used on desktop environments such as Gnome, and on operating ++systems such as Microsoft Windows (@pxref{Clipboard}). ++ ++ Under X, whenever you select some text in Emacs by dragging or ++clicking the mouse (@pxref{Mouse Commands}), it is also saved in the ++primary selection. You can then @dfn{paste} that text into any other ++X application, usually by clicking @kbd{Mouse-2} in that application. ++Unlike the Emacs kill ring (@pxref{Kill Ring}), the primary selection ++has no ``memory'': each time you save something in the primary ++selection, either in Emacs or in another X application, the previous ++contents of the primary selection are lost. ++ ++ Whenever you kill some text using a command such as @kbd{C-w} ++(@code{kill-region}), or copy it into the kill ring using a command ++such as @kbd{M-w} (@code{kill-ring-save}), that text is also saved in ++the primary selection. @xref{Killing}. ++ ++@cindex cut buffer ++@vindex x-cut-buffer-max ++ Whenever Emacs saves some text to the primary selection, it may also ++save it to the @dfn{cut buffer}. The cut buffer is an obsolete ++predecessor to the primary selection; most modern applications do not ++make use of it. Because saving text to the cut buffer is slow and ++inefficient, Emacs only does it if the text is shorter than the value ++of @code{x-cut-buffer-max} (the default is 20000 characters). ++ ++ You can yank the primary selection into Emacs using the usual yank ++commands, such as @kbd{C-y} (@code{yank}) and @kbd{Mouse-2} ++(@code{mouse-yank-at-click}). These commands actually check the ++primary selection before referring to the kill ring; if no primary ++selection is available, the kill ring contents are used. To prevent ++yank commands from accessing the primary selection, set the variable ++@code{x-select-enable-primary} to @code{nil}. ++ ++ The standard coding system for the primary selection is ++@code{compound-text-with-extensions}. You may find that the pasted ++text is not what you expected. In such a case, you can specify ++another coding system for the selection by typing @kbd{C-x @key{RET} ++x} or @kbd{C-x @key{RET} X}. Alternatively, you can request a ++different data type by modifying the variable ++@code{x-select-request-type}. @xref{Communication Coding}. ++ ++@node Secondary Selection ++@subsection Secondary Selection ++@cindex secondary selection ++ ++ In addition to the primary selection, the X Window System provides a ++second similar facility known as the @dfn{secondary selection}. ++Nowadays, few X applications make use of the secondary selection, but ++you can access it using the following Emacs commands: ++ ++@table @kbd ++@findex mouse-set-secondary ++@kindex M-Drag-Mouse-1 ++@item M-Drag-Mouse-1 ++Set the secondary selection, with one end at the place where you press ++down the button, and the other end at the place where you release it ++(@code{mouse-set-secondary}). The selected text is highlighted, using ++the @code{secondary-selection} face, as you drag. The window scrolls ++automatically if you drag the mouse off the top or bottom of the ++window, just like @code{mouse-set-region} (@pxref{Mouse Commands}). ++ ++This command does not alter the kill ring. ++ ++@findex mouse-start-secondary ++@kindex M-Mouse-1 ++@item M-Mouse-1 ++Set one endpoint for the @dfn{secondary selection} ++(@code{mouse-start-secondary}). ++ ++@findex mouse-secondary-save-then-kill ++@kindex M-Mouse-3 ++@item M-Mouse-3 ++Set the secondary selection, with one end at the position clicked and ++the other at the position specified with @kbd{M-Mouse-1} ++(@code{mouse-secondary-save-then-kill}). This also puts the selected ++text in the kill ring. A second @kbd{M-Mouse-3} at the same place ++kills the secondary selection just made. ++ ++@findex mouse-yank-secondary ++@kindex M-Mouse-2 ++@item M-Mouse-2 ++Insert the secondary selection where you click, placing point at the ++end of the yanked text (@code{mouse-yank-secondary}). ++@end table ++ ++Double or triple clicking of @kbd{M-Mouse-1} operates on words and ++lines, much like @kbd{Mouse-1}. ++ ++If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2} yanks ++at point. Then it does not matter precisely where you click, or even ++which of the frame's windows you click on. @xref{Mouse Commands}. ++ ++@node Clipboard ++@subsection Using the Clipboard ++@cindex clipboard ++ ++ In desktop environments such as Gnome, and operating systems such as ++Microsoft Windows and Mac OS X, you can transfer data (usually text) ++between different applications using the @dfn{clipboard}. The ++clipboard is distinct from the primary selection and secondary ++selection discussed earlier. You can access the clipboard through the ++@samp{Edit} menu of the menu bar (@pxref{Menu Bar}). ++ ++@cindex cut ++@findex clipboard-kill-region ++ The command @code{clipboard-kill-region}, which is bound to the ++@code{Cut} menu item, kills the region and saves it in the clipboard. ++ ++@cindex copy ++@findex clipboard-kill-ring-save ++ The command @code{clipboard-kill-ring-save}, which is bound to the ++@code{Copy} menu item, copies the region to the kill ring and saves it ++in the clipboard. ++ ++@findex clipboard-yank ++@cindex paste ++ The @code{Paste} menu item in the Edit menu yanks the contents of ++the clipboard at point (@code{clipboard-yank}). ++ ++@vindex x-select-enable-clipboard ++ You can customize the variable @code{x-select-enable-clipboard} to ++make the Emacs yank functions consult the clipboard before the primary ++selection, and to make the kill functions to store in the clipboard as ++well as the primary selection. Otherwise, these commands do not ++access the clipboard at all. Using the clipboard is the default on ++MS-Windows and Mac OS, but not on other systems. ++ ++@node Mouse References ++@section Following References with the Mouse ++@kindex Mouse-1 @r{(selection)} ++@kindex Mouse-2 @r{(selection)} ++ ++@vindex mouse-highlight ++ Some Emacs buffers include @dfn{buttons}. A button is a piece of ++text that performs some action when you activate it, such as following ++a reference. Usually, a button's text is visually highlighted: it is ++underlined, or a box is drawn around it. If you move the mouse over a ++button, the shape of the mouse cursor changes and the button lights up ++(if you change the variable @code{mouse-highlight} to @code{nil}, ++Emacs disables this highlighting). ++ ++ You can activate a button by moving point to it and typing ++@key{RET}, or by clicking either @kbd{Mouse-1} or @kbd{Mouse-2} on the ++button. For example, typing @key{RET} or clicking on a file name in a ++Dired buffer visits that file (@pxref{Dired}). Doing it on an error ++message in the @samp{*Compilation*} buffer goes to the source code for ++that error message (@pxref{Compilation}). Doing it on a completion in ++the @samp{*Completions*} buffer chooses that completion ++(@pxref{Completion}). ++ ++ Although clicking @kbd{Mouse-1} on a button usually activates that ++button, if you hold the mouse button down for a short period of time ++before releasing it (specifically, for more than 450 milliseconds), ++then Emacs moves point where you clicked instead. This behavior ++allows you to use the mouse to move point over a button without ++following it. Dragging---moving the mouse while it is held down---has ++its usual behavior of setting the region, even if you drag from or ++onto a button. ++ ++@vindex mouse-1-click-in-non-selected-windows ++ Normally, clicking @kbd{Mouse-1} on a button activates the button ++even if it is in a nonselected window. If you change the variable ++@code{mouse-1-click-in-non-selected-windows} to @code{nil}, clicking ++@kbd{Mouse-1} on a button in an un-selected window moves point to the ++clicked position and selects that window, without activating the ++button. ++ ++@vindex mouse-1-click-follows-link ++ In Emacs versions before 22, only @kbd{Mouse-2} activates buttons ++and @kbd{Mouse-1} always sets point. If you prefer this older ++behavior, set the variable @code{mouse-1-click-follows-link} to ++@code{nil}. This variable also lets you choose various other ++alternatives for following links with the mouse. Type @kbd{C-h v ++mouse-1-click-follows-link @key{RET}} for more details. ++ ++@node Menu Mouse Clicks ++@section Mouse Clicks for Menus ++ ++ Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers ++bring up menus. ++ ++@table @kbd ++@item C-Mouse-1 ++@kindex C-Mouse-1 ++This menu is for selecting a buffer. ++ ++The MSB (``mouse select buffer'') global minor mode makes this ++menu smarter and more customizable. @xref{Buffer Menus}. ++ ++@item C-Mouse-2 ++@kindex C-Mouse-2 ++This menu is for specifying faces and other text properties ++for editing formatted text. @xref{Formatted Text}. ++ ++@item C-Mouse-3 ++@kindex C-Mouse-3 ++This menu is mode-specific. For most modes if Menu-bar mode is on, ++this menu has the same items as all the mode-specific menu-bar menus ++put together. Some modes may specify a different menu for this ++button.@footnote{Some systems use @kbd{Mouse-3} for a mode-specific ++menu. We took a survey of users, and found they preferred to keep ++@kbd{Mouse-3} for selecting and killing regions. Hence the decision ++to use @kbd{C-Mouse-3} for this menu. To use @kbd{Mouse-3} instead, ++do @code{(global-set-key [mouse-3] 'mouse-popup-menubar-stuff)}.} If ++Menu-bar mode is off, this menu contains all the items which would be ++present in the menu bar---not just the mode-specific ones---so that ++you can access them without having to display the menu bar. ++ ++@item S-Mouse-1 ++This menu is for changing the default face within the window's buffer. ++@xref{Temporary Face Changes}. ++@end table ++ ++@node Mode Line Mouse ++@section Mode Line Mouse Commands ++@cindex mode line, mouse ++@cindex mouse on mode line ++ ++ You can use mouse clicks on window mode lines to select and manipulate ++windows. ++ ++ Some areas of the mode line, such as the buffer name, and major and minor ++mode names, have their own special mouse bindings. These areas are ++highlighted when you hold the mouse over them, and information about ++the special bindings will be displayed (@pxref{Tooltips}). This ++section's commands do not apply in those areas. ++ ++@table @kbd ++@item Mouse-1 ++@kindex Mouse-1 @r{(mode line)} ++@kbd{Mouse-1} on a mode line selects the window it belongs to. By ++dragging @kbd{Mouse-1} on the mode line, you can move it, thus ++changing the height of the windows above and below. Changing heights ++with the mouse in this way never deletes windows, it just refuses to ++make any window smaller than the minimum height. ++ ++@item Mouse-2 ++@kindex Mouse-2 @r{(mode line)} ++@kbd{Mouse-2} on a mode line expands that window to fill its frame. ++ ++@item Mouse-3 ++@kindex Mouse-3 @r{(mode line)} ++@kbd{Mouse-3} on a mode line deletes the window it belongs to. If the ++frame has only one window, it buries the current buffer instead, and ++switches to another buffer. ++ ++@item C-Mouse-2 ++@kindex C-mouse-2 @r{(mode line)} ++@kbd{C-Mouse-2} on a mode line splits the window above ++horizontally, above the place in the mode line where you click. ++@end table ++ ++@kindex C-Mouse-2 @r{(scroll bar)} ++@kindex Mouse-1 @r{(scroll bar)} ++ Using @kbd{Mouse-1} on the divider between two side-by-side mode ++lines, you can move the vertical boundary left or right. Using ++@kbd{C-Mouse-2} on a scroll bar splits the corresponding window ++vertically. @xref{Split Window}. ++ ++@node Creating Frames ++@section Creating Frames ++@cindex creating frames ++ ++@kindex C-x 5 ++ The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with ++parallel subcommands. The difference is that @kbd{C-x 5} commands ++create a new frame rather than just a new window in the selected frame ++(@pxref{Pop Up Window}). If an existing visible or iconified ++(``minimized'') frame already displays the requested material, these ++commands use the existing frame, after raising or deiconifying ++(``un-minimizing'') as necessary. ++ ++ The various @kbd{C-x 5} commands differ in how they find or create the ++buffer to select: ++ ++@table @kbd ++@item C-x 5 2 ++@kindex C-x 5 2 ++@findex make-frame-command ++Create a new frame (@code{make-frame-command}). ++@item C-x 5 b @var{bufname} @key{RET} ++Select buffer @var{bufname} in another frame. This runs ++@code{switch-to-buffer-other-frame}. ++@item C-x 5 f @var{filename} @key{RET} ++Visit file @var{filename} and select its buffer in another frame. This ++runs @code{find-file-other-frame}. @xref{Visiting}. ++@item C-x 5 d @var{directory} @key{RET} ++Select a Dired buffer for directory @var{directory} in another frame. ++This runs @code{dired-other-frame}. @xref{Dired}. ++@item C-x 5 m ++Start composing a mail message in another frame. This runs ++@code{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. ++@xref{Sending Mail}. ++@item C-x 5 . ++Find a tag in the current tag table in another frame. This runs ++@code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}. ++@xref{Tags}. ++@item C-x 5 r @var{filename} @key{RET} ++@kindex C-x 5 r ++@findex find-file-read-only-other-frame ++Visit file @var{filename} read-only, and select its buffer in another ++frame. This runs @code{find-file-read-only-other-frame}. ++@xref{Visiting}. ++@end table ++ ++@cindex default-frame-alist ++@cindex initial-frame-alist ++@cindex face customization, in init file ++@cindex color customization, in init file ++ You can control the appearance of new frames you create by setting the ++frame parameters in @code{default-frame-alist}. You can use the ++variable @code{initial-frame-alist} to specify parameters that affect ++only the initial frame. @xref{Initial Parameters,,, elisp, The Emacs ++Lisp Reference Manual}, for more information. ++ ++@cindex font (default) ++ For instance, one way to specify the principal font for all your ++Emacs frames is to modify @code{default-frame-alist} to specify the ++@code{font} parameter (@pxref{Font X}): ++ ++@example ++(add-to-list 'default-frame-alist '(font . "10x20")) ++@end example ++ ++@noindent ++Here's a similar example for specifying a foreground color: ++ ++@example ++(add-to-list 'default-frame-alist '(foreground-color . "blue")) ++@end example ++ ++@noindent ++By putting such customizations in your init file, you can control the ++appearance of all the frames Emacs creates, including the initial one. ++@xref{Init File}. ++ ++@node Frame Commands ++@section Frame Commands ++ ++ The following commands let you create, delete and operate on frames: ++ ++@table @kbd ++@item C-z ++@kindex C-z @r{(X windows)} ++@findex iconify-or-deiconify-frame ++Iconify (``minimize'') the selected Emacs frame ++(@code{iconify-or-deiconify-frame}). @xref{Exiting}. ++ ++@item C-x 5 0 ++@kindex C-x 5 0 ++@findex delete-frame ++Delete the selected frame (@code{delete-frame}). This is not allowed ++if there is only one frame. ++ ++@item C-x 5 o ++@kindex C-x 5 o ++@findex other-frame ++Select another frame, raise it, and warp the mouse to it. If you ++repeat this command, it cycles through all the frames on your ++terminal. ++ ++@item C-x 5 1 ++@kindex C-x 5 1 ++@findex delete-other-frames ++Delete all frames except the selected one. ++@end table ++ ++@vindex focus-follows-mouse ++ To make the command @kbd{C-x 5 o} work properly, you should tell ++Emacs how the system (or the window manager) handles focus-switching ++between windows. There are two possibilities: either simply moving ++the mouse onto a window selects it (gives it focus), or you have to ++click on it to do so. On X, this focus policy also affects whether ++the focus is given to a frame that Emacs raises. Unfortunately there ++is no way Emacs can find out automatically which way the system ++handles this, so you have to explicitly say, by setting the variable ++@code{focus-follows-mouse}. If just moving the mouse onto a window ++selects it, that variable should be @code{t}; if a click is necessary, ++the variable should be @code{nil}. The default is @code{t}. ++ ++ The window manager that is part of MS-Windows always gives focus to ++a frame that raises, so this variable has no effect in the native ++MS-Windows build of Emacs. ++ ++@node Speedbar ++@section Speedbar Frames ++@cindex speedbar ++ ++@cindex attached frame (of speedbar) ++ The @dfn{speedbar} is a special frame for conveniently navigating in ++or operating on another frame. The speedbar, when it exists, is ++always associated with a specific frame, called its @dfn{attached ++frame}; all speedbar operations act on that frame. ++ ++ Type @kbd{M-x speedbar} to create the speedbar and associate it with ++the current frame. To dismiss the speedbar, type @kbd{M-x speedbar} ++again, or select the speedbar and type @kbd{q}. (You can also delete ++the speedbar frame like any other Emacs frame.) If you wish to ++associate the speedbar with a different frame, dismiss it and call ++@kbd{M-x speedbar} from that frame. ++ ++ The speedbar can operate in various modes. Its default mode is ++@dfn{File Display} mode, which shows the files in the current ++directory of the selected window of the attached frame, one file per ++line. Clicking on a file name visits that file in the selected window ++of the attached frame, and clicking on a directory name shows that ++directory in the speedbar (@pxref{Mouse References}). Each line also ++has a box, @samp{[+]} or @samp{<+>}, that you can click on to ++@dfn{expand} the contents of that item. Expanding a directory adds ++the contents of that directory to the speedbar display, underneath the ++directory's own line. Expanding an ordinary file adds a list of the ++tags in that file to the speedbar display; you can click on a tag name ++to jump to that tag in the selected window of the attached frame. ++When a file or directory is expanded, the @samp{[+]} changes to ++@samp{[-]}; you can click on that box to @dfn{contract} the item, ++hiding its contents. ++ ++ You navigate through the speedbar using the keyboard, too. Typing ++@kbd{RET} while point is on a line in the speedbar is equivalent to ++clicking the item on the current line, and @kbd{SPC} expands or ++contracts the item. @kbd{U} displays the parent directory of the ++current directory. To copy, delete, or rename the file on the current ++line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a ++new directory, type @kbd{M}. ++ ++ Another general-purpose speedbar mode is @dfn{Buffer Display} mode; ++in this mode, the speedbar displays a list of Emacs buffers. To ++switch to this mode, type @kbd{b} in the speedbar. To return to File ++Display mode, type @kbd{f}. You can also change the display mode by ++clicking @kbd{mouse-3} anywhere in the speedbar window (or ++@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the ++pop-up menu. ++ ++ Some major modes, including Rmail mode, Info, and GUD, have ++specialized ways of putting useful items into the speedbar for you to ++select. For example, in Rmail mode, the speedbar shows a list of Rmail ++files, and lets you move the current message to another Rmail file by ++clicking on its @samp{} box. ++ ++ For more details on using and programming the speedbar, @xref{Top, ++Speedbar,,speedbar, Speedbar Manual}. ++ ++@node Multiple Displays ++@section Multiple Displays ++@cindex multiple displays ++ ++ A single Emacs can talk to more than one X display. Initially, Emacs ++uses just one display---the one specified with the @env{DISPLAY} ++environment variable or with the @samp{--display} option (@pxref{Initial ++Options}). To connect to another display, use the command ++@code{make-frame-on-display}: ++ ++@findex make-frame-on-display ++@table @kbd ++@item M-x make-frame-on-display @key{RET} @var{display} @key{RET} ++Create a new frame on display @var{display}. ++@end table ++ ++ A single X server can handle more than one screen. When you open ++frames on two screens belonging to one server, Emacs knows they share a ++single keyboard, and it treats all the commands arriving from these ++screens as a single stream of input. ++ ++ When you open frames on different X servers, Emacs makes a separate ++input stream for each server. Each server also has its own selected ++frame. The commands you enter with a particular X server apply to ++that server's selected frame. ++ ++ It is even possible to use this feature to let two or more users ++type simultaneously on the two displays, within the same Emacs job. ++In practice, however, the different users can easily interfere with ++each others' edits if they are not careful. ++ ++@node Special Buffer Frames ++@section Special Buffer Frames ++ ++@vindex special-display-buffer-names ++ You can make certain chosen buffers, which Emacs normally displays ++in ``another window,'' appear in special frames of their own. To do ++this, set the variable @code{special-display-buffer-names} to a list ++of buffer names; any buffer whose name is in that list automatically ++gets a special frame, when an Emacs command wants to display it ``in ++another window.'' ++ ++ For example, if you set the variable this way, ++ ++@example ++(setq special-display-buffer-names ++ '("*Completions*" "*grep*" "*tex-shell*")) ++@end example ++ ++@noindent ++then completion lists, @code{grep} output and the @TeX{} mode shell ++buffer get individual frames of their own. These frames, and the ++windows in them, are never automatically split or reused for any other ++buffers. They continue to show the buffers they were created for, ++unless you alter them by hand. Killing the special buffer deletes its ++frame automatically. ++ ++@vindex special-display-regexps ++ More generally, you can set @code{special-display-regexps} to a list ++of regular expressions; then a buffer gets its own frame if its name ++matches any of those regular expressions. (Once again, this applies only ++to buffers that normally get displayed for you in ``another window.'') ++ ++@vindex special-display-frame-alist ++ The variable @code{special-display-frame-alist} specifies the frame ++parameters for these frames. It has a default value, so you don't need ++to set it. ++ ++ For those who know Lisp, an element of ++@code{special-display-buffer-names} or @code{special-display-regexps} ++can also be a list. Then the first element is the buffer name or ++regular expression; the rest of the list specifies how to create the ++frame. It can be an association list specifying frame parameter ++values; these values take precedence over parameter values specified ++in @code{special-display-frame-alist}. If you specify the symbol ++@code{same-window} as a ``frame parameter'' in this list, with a ++non-@code{nil} value, that means to use the selected window if ++possible. If you use the symbol @code{same-frame} as a ``frame ++parameter'' in this list, with a non-@code{nil} value, that means to ++use the selected frame if possible. ++ ++ Alternatively, the value can have this form: ++ ++@example ++(@var{function} @var{args}...) ++@end example ++ ++@noindent ++where @var{function} is a symbol. Then the frame is constructed by ++calling @var{function}; its first argument is the buffer, and its ++remaining arguments are @var{args}. ++ ++ An analogous feature lets you specify buffers which should be ++displayed in the selected window. @xref{Force Same Window}. The ++same-window feature takes precedence over the special-frame feature; ++therefore, if you add a buffer name to ++@code{special-display-buffer-names} and it has no effect, check to see ++whether that feature is also in use for the same buffer name. ++ ++@node Frame Parameters ++@section Setting Frame Parameters ++@cindex Auto-Raise mode ++@cindex Auto-Lower mode ++ ++ These commands are available for controlling the window management ++behavior of the selected frame: ++ ++@table @kbd ++@findex auto-raise-mode ++@item M-x auto-raise-mode ++Toggle whether or not the selected frame should auto-raise. Auto-raise ++means that every time you move the mouse onto the frame, it raises the ++frame. ++ ++Some window managers also implement auto-raise. If you enable ++auto-raise for Emacs frames in your window manager, it will work, but ++it is beyond Emacs' control, so @code{auto-raise-mode} has no effect ++on it. ++ ++@findex auto-lower-mode ++@item M-x auto-lower-mode ++Toggle whether or not the selected frame should auto-lower. ++Auto-lower means that every time you move the mouse off the frame, ++the frame moves to the bottom of the stack on the screen. ++ ++The command @code{auto-lower-mode} has no effect on auto-lower ++implemented by the window manager. To control that, you must use the ++appropriate window manager features. ++@end table ++ ++ In Emacs versions that use an X toolkit, the color-setting and ++font-setting functions don't affect menus and the menu bar, since they ++are displayed by their own widget classes. To change the appearance of ++the menus and menu bar, you must use X resources (@pxref{Resources}). ++@xref{Colors}, regarding colors. @xref{Font X}, regarding choice of ++font. ++ ++ Colors, fonts, and other attributes of the frame's display can also ++be customized by setting frame parameters in the variable ++@code{default-frame-alist} (@pxref{Creating Frames}). For a detailed ++description of frame parameters and customization, see @ref{Frame ++Parameters,,, elisp, The Emacs Lisp Reference Manual}. ++ ++@node Scroll Bars ++@section Scroll Bars ++@cindex Scroll Bar mode ++@cindex mode, Scroll Bar ++ ++ On graphical displays, Emacs normally makes a @dfn{scroll bar} at ++the left of each Emacs window, running the height of the ++window.@footnote{Placing it at the left is usually more useful with ++overlapping frames with text starting at the left margin.} ++ ++ When Emacs is compiled with GTK+ support on the X window system, or ++in operating systems such as Microsoft Windows or Mac OS, you can use ++the scroll bar as you do in other graphical applications. If you ++click @kbd{Mouse-1} on the scroll bar's up and down buttons, that ++scrolls the window by one line at a time. Clicking @kbd{Mouse-1} ++above or below the scroll bar's inner box scrolls the window by nearly ++the entire height of the window, like @kbd{M-v} and @kbd{C-v} ++respectively (@pxref{Moving Point}). Dragging the inner box with ++@kbd{Mouse-1} scrolls the window continuously. ++ ++ If Emacs is compiled without GTK+ support on the X window system, ++the scroll bar behaves differently. The scroll bar's inner box is ++drawn to represent the portion of the buffer currently displayed, with ++the entire height of the scroll bar representing the entire length of ++the buffer. @kbd{Mouse-1} anywhere on the scroll bar scrolls forward ++like @kbd{C-v}, and @kbd{Mouse-3} scrolls backward like @kbd{M-v}. ++Clicking @kbd{Mouse-2} in the scroll bar lets you move or drag the ++inner box up and down. ++ ++ You can also click @kbd{C-Mouse-2} in the scroll bar to split a ++window vertically. The split occurs on the line where you click. ++ ++@findex scroll-bar-mode ++@vindex scroll-bar-mode ++ You can toggle the use of the scroll bar with the command @kbd{M-x ++scroll-bar-mode}. With a prefix argument, this command turns use of ++scroll bars on if and only if the argument is positive. This command ++applies to all frames, including frames yet to be created. Customize ++the variable @code{scroll-bar-mode} to control the use of scroll bars ++at startup. You can use it to specify that they are placed at the ++right of windows if you prefer that. You have to set this variable ++through the @samp{Customize} interface (@pxref{Easy Customization}), ++or it will not work properly. You can also use the X resource ++@samp{verticalScrollBars} to control the initial setting of Scroll Bar ++mode. @xref{Resources}. ++ ++@findex toggle-scroll-bar ++ To enable or disable scroll bars for just the selected frame, use the ++command @kbd{M-x toggle-scroll-bar}. ++ ++@vindex scroll-bar-width ++@cindex width of the scroll bar ++ You can control the scroll bar width by changing the value of the ++@code{scroll-bar-width} frame parameter. ++ ++@node Wheeled Mice ++@section Scrolling With ``Wheeled'' Mice ++ ++@cindex mouse wheel ++@cindex wheel, mouse ++@findex mouse-wheel-mode ++@cindex Mouse Wheel minor mode ++@cindex mode, Mouse Wheel ++ Some mice have a ``wheel'' instead of a third button. You can ++usually click the wheel to act as either @kbd{Mouse-2} or ++@kbd{Mouse-3}, depending on the setup. You can also use the wheel to ++scroll windows instead of using the scroll bar or keyboard commands. ++Mouse wheel support only works if the system generates appropriate ++events; whenever possible, it is turned on by default. To toggle this ++feature, use @kbd{M-x mouse-wheel-mode}. ++ ++@vindex mouse-wheel-follow-mouse ++@vindex mouse-wheel-scroll-amount ++@vindex mouse-wheel-progressive-speed ++ The two variables @code{mouse-wheel-follow-mouse} and ++@code{mouse-wheel-scroll-amount} determine where and by how much ++buffers are scrolled. The variable ++@code{mouse-wheel-progressive-speed} determines whether the scroll ++speed is linked to how fast you move the wheel. ++ ++@node Drag and Drop ++@section Drag and Drop ++@cindex drag and drop ++ ++ Emacs supports @dfn{drag and drop} using the mouse. For instance, ++dropping text onto an Emacs frame inserts the text where it is dropped. ++Dropping a file onto an Emacs frame visits that file. As a special ++case, dropping the file on a Dired buffer moves or copies the file ++(according to the conventions of the application it came from) into the ++directory displayed in that buffer. ++ ++@vindex dnd-open-file-other-window ++ Dropping a file normally visits it in the window you drop it on. If ++you prefer to visit the file in a new window in such cases, customize ++the variable @code{dnd-open-file-other-window}. ++ ++ The XDND and Motif drag and drop protocols, and the old KDE 1.x ++protocol, are currently supported. ++ ++@node Menu Bars ++@section Menu Bars ++@cindex Menu Bar mode ++@cindex mode, Menu Bar ++@findex menu-bar-mode ++@vindex menu-bar-mode ++ ++ You can turn display of menu bars on or off with @kbd{M-x ++menu-bar-mode} or by customizing the variable @code{menu-bar-mode}. ++With no argument, this command toggles Menu Bar mode, a ++minor mode. With an argument, the command turns Menu Bar mode on if the ++argument is positive, off if the argument is not positive. You can use ++the X resource @samp{menuBarLines} to control the initial setting of ++Menu Bar mode. @xref{Resources}. ++ ++@kindex C-Mouse-3 @r{(when menu bar is disabled)} ++ Expert users often turn off the menu bar, especially on text-only ++terminals, where this makes one additional line available for text. ++If the menu bar is off, you can still pop up a menu of its contents ++with @kbd{C-Mouse-3} on a display which supports pop-up menus. ++@xref{Menu Mouse Clicks}. ++ ++ @xref{Menu Bar}, for information on how to invoke commands with the ++menu bar. @xref{X Resources}, for how to customize the menu bar ++menus' visual appearance. ++ ++@node Tool Bars ++@section Tool Bars ++@cindex Tool Bar mode ++@cindex mode, Tool Bar ++@cindex icons, toolbar ++ ++ The @dfn{tool bar} is a line (or lines) of icons at the top of the ++Emacs window, just below the menu bar. You can click on these icons ++with the mouse to do various jobs. ++ ++ The global tool bar contains general commands. Some major modes ++define their own tool bars to replace it. A few ``special'' modes ++that are not designed for ordinary editing remove some items from the ++global tool bar. ++ ++ Tool bars work only on a graphical display. The tool bar uses colored ++XPM icons if Emacs was built with XPM support. Otherwise, the tool ++bar uses monochrome icons (PBM or XBM format). ++ ++@findex tool-bar-mode ++@vindex tool-bar-mode ++ You can turn display of tool bars on or off with @kbd{M-x ++tool-bar-mode} or by customizing the option @code{tool-bar-mode}. ++ ++@node Dialog Boxes ++@section Using Dialog Boxes ++@cindex dialog boxes ++ ++@vindex use-dialog-box ++ A dialog box is a special kind of menu for asking you a yes-or-no ++question or some other special question. Many Emacs commands use a ++dialog box to ask a yes-or-no question, if you used the mouse to ++invoke the command that led to the question. ++ ++ To disable the use of dialog boxes, change the variable ++@code{use-dialog-box} to @code{nil}. In that case, Emacs always ++performs yes-or-no prompts using the echo area and keyboard input. ++This variable also controls whether to use file selection windows (but ++those are not supported on all platforms). ++ ++@vindex use-file-dialog ++@cindex file selection dialog, how to disable ++ A file selection window is a special kind of dialog box for asking ++for file names. You can customize the variable @code{use-file-dialog} ++to suppress the use of file selection windows, even if you still want ++other kinds of dialogs. This variable has no effect if you have ++suppressed all dialog boxes with the variable @code{use-dialog-box}. ++ ++@vindex x-gtk-show-hidden-files ++@vindex x-gtk-file-dialog-help-text ++@cindex hidden files, in GTK+ file chooser ++@cindex help text, in GTK+ file chooser ++ When Emacs is compiled with GTK+ support, it uses the GTK+ ``file ++chooser'' dialog. Emacs adds an additional toggle button to this ++dialog, which you can use to enable or disable the display of hidden ++files (files starting with a dot) in that dialog. If you want this ++toggle to be activated by default, change the variable ++@code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds ++help text to the GTK+ file chooser dialog; to disable this help text, ++change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. ++ ++@vindex x-gtk-use-old-file-dialog ++ In GTK+ versions 2.4 through 2.10, you can choose to use an older ++version of the GTK+ file dialog by setting the variable ++@code{x-gtk-use-old-file-dialog} to a non-@code{nil} value. If Emacs ++is built with a GTK+ version that has only one file dialog, this ++variable has no effect. ++ ++@node Tooltips ++@section Tooltips ++@cindex tooltips ++ ++ @dfn{Tooltips} are small windows that display text information at the ++current mouse position. They activate when there is a pause in mouse ++movement. There are two types of tooltip: help tooltips and GUD ++tooltips. ++ ++ @dfn{Help tooltips} typically display over text---including the mode ++line---but are also available for other parts of the Emacs frame, such ++as the tool bar and menu items. ++ ++@findex tooltip-mode ++ You can toggle display of help tooltips (Tooltip mode) with the ++command @kbd{M-x tooltip-mode}. When Tooltip mode is disabled, the ++help text is displayed in the echo area instead. ++ ++ @dfn{GUD tooltips} show values of variables. They are useful when ++you are debugging a program. @xref{Debugger Operation}. ++ ++@vindex tooltip-delay ++ The variables @code{tooltip-delay} specifies how long Emacs should ++wait before displaying a tooltip. For additional customization ++options for displaying tooltips, use @kbd{M-x customize-group ++@key{RET} tooltip @key{RET}}. @xref{X Resources}, for information on ++customizing the windows that display tooltips. ++ ++@node Mouse Avoidance ++@section Mouse Avoidance ++@cindex avoiding mouse in the way of your typing ++@cindex mouse avoidance ++ ++@vindex mouse-avoidance-mode ++Mouse Avoidance mode keeps the mouse pointer away from point, to avoid ++obscuring text you want to edit. Whenever it moves the mouse, it also ++raises the frame. To use Mouse Avoidance mode, customize the variable ++@code{mouse-avoidance-mode}. You can set this to various values to ++move the mouse in several ways: ++ ++@table @code ++@item banish ++Move the mouse to the upper-right corner on any key-press; ++@item exile ++Move the mouse to the corner only if the cursor gets too close, ++and allow it to return once the cursor is out of the way; ++@item jump ++If the cursor gets too close to the mouse, displace the mouse ++a random distance & direction; ++@item animate ++As @code{jump}, but shows steps along the way for illusion of motion; ++@item cat-and-mouse ++The same as @code{animate}; ++@item proteus ++As @code{animate}, but changes the shape of the mouse pointer too. ++@end table ++ ++@findex mouse-avoidance-mode ++You can also use the command @kbd{M-x mouse-avoidance-mode} to enable ++the mode. ++ ++@node Non-Window Terminals ++@section Non-Window Terminals ++@cindex non-window terminals ++@cindex single-frame terminals ++ ++ On a text-only terminal, Emacs can display only one Emacs frame at a ++time. However, you can still create multiple Emacs frames, and switch ++between them. Switching frames on these terminals is much like ++switching between different window configurations. ++ ++ Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x ++5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete ++the current frame. ++ ++ Each frame has a number to distinguish it. If your terminal can ++display only one frame at a time, the selected frame's number @var{n} ++appears near the beginning of the mode line, in the form ++@samp{F@var{n}}. ++ ++@findex set-frame-name ++@findex select-frame-by-name ++ @samp{F@var{n}} is in fact the frame's initial name. You can give ++frames more meaningful names if you wish, and you can select a frame ++by its name. Use the command @kbd{M-x set-frame-name @key{RET} ++@var{name} @key{RET}} to specify a new name for the selected frame, ++and use @kbd{M-x select-frame-by-name @key{RET} @var{name} @key{RET}} ++to select a frame according to its name. The name you specify appears ++in the mode line when the frame is selected. ++ ++@node Text-Only Mouse ++@section Using a Mouse in Terminal Emulators ++@cindex mouse support ++@cindex terminal emulators, mouse support ++ ++Some text-only terminals support mouse clicks in the terminal window. ++ ++@cindex xterm ++In a terminal emulator which is compatible with @code{xterm}, ++you can use @kbd{M-x xterm-mouse-mode} to give Emacs control over ++simple use of the mouse---basically, only non-modified single clicks ++are supported. The normal @code{xterm} mouse functionality for such ++clicks is still available by holding down the @kbd{SHIFT} key when you ++press the mouse button. Xterm Mouse mode is a global minor mode ++(@pxref{Minor Modes}). Repeating the command turns the mode off ++again. ++ ++@findex gpm-mouse-mode ++In the console on GNU/Linux, you can use @kbd{M-x gpm-mouse-mode} to ++enable terminal mouse support. You must have the gpm package ++installed and running on your system in order for this to work. ++ ++@ignore ++ arch-tag: 7dcf3a31-a43b-45d4-a900-445b10d77e49 ++@end ignore +diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi +new file mode 100644 +index 0000000..397482e +--- /dev/null ++++ b/doc/emacs/glossary.texi +@@ -0,0 +1,1378 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Glossary, Key Index, Intro, Top ++@unnumbered Glossary ++ ++@table @asis ++@item Abbrev ++An abbrev is a text string which expands into a different text string ++when present in the buffer. For example, you might define a few letters ++as an abbrev for a long phrase that you want to insert frequently. ++@xref{Abbrevs}. ++ ++@item Aborting ++Aborting means getting out of a recursive edit (q.v.@:). The ++commands @kbd{C-]} and @kbd{M-x top-level} are used for this. ++@xref{Quitting}. ++ ++@item Alt ++Alt is the name of a modifier bit that a keyboard input character may ++have. To make a character Alt, type it while holding down the @key{ALT} ++key. Such characters are given names that start with @kbd{Alt-} ++(usually written @kbd{A-} for short). (Note that many terminals have a ++key labeled @key{ALT} that is really a @key{META} key.) @xref{User ++Input, Alt}. ++ ++@item Argument ++See `numeric argument.' ++ ++@item @acronym{ASCII} character ++An @acronym{ASCII} character is either an @acronym{ASCII} control ++character or an @acronym{ASCII} printing character. @xref{User Input}. ++ ++@item @acronym{ASCII} control character ++An @acronym{ASCII} control character is the Control version of an upper-case ++letter, or the Control version of one of the characters @samp{@@[\]^_?}. ++ ++@item @acronym{ASCII} printing character ++@acronym{ASCII} printing characters include letters, digits, space, and these ++punctuation characters: @samp{!@@#$%^& *()_-+=|\~` @{@}[]:;"' <>,.?/}. ++ ++@item Auto Fill Mode ++Auto Fill mode is a minor mode (q.v.@:) in which text that you insert is ++automatically broken into lines of a given maximum width. ++@xref{Filling}. ++ ++@item Auto Saving ++Auto saving is the practice of periodically saving the contents of an ++Emacs buffer in a specially-named file, so that the information will ++be preserved if the buffer is lost due to a system error or user error. ++@xref{Auto Save}. ++ ++@item Autoloading ++Emacs can automatically load Lisp libraries when a Lisp program requests a ++function from those libraries. This is called `autoloading.' ++@xref{Lisp Libraries}. ++ ++@item Backtrace ++A backtrace is a trace of a series of function calls showing how a ++program arrived at a certain point. It is used mainly for finding and ++correcting bugs (q.v.@:). Emacs can display a backtrace when it signals ++an error or when you type @kbd{C-g} (see `quitting'). @xref{Checklist}. ++ ++@item Backup File ++A backup file records the contents that a file had before the current ++editing session. Emacs makes backup files automatically to help you ++track down or cancel changes you later regret making. @xref{Backup}. ++ ++@item Balancing Parentheses ++Emacs can balance parentheses (or other matching delimiters) either ++manually or automatically. You do manual balancing with the commands ++to move over parenthetical groupings (@pxref{Moving by Parens}). ++Automatic balancing works by blinking or highlighting the delimiter ++that matches the one you just inserted (@pxref{Matching,,Matching ++Parens}). ++ ++@item Balanced Expressions ++A balanced expression is a syntactically recognizable expression, such ++as a symbol, number, string constant, block, or parenthesized expression ++in C. @xref{Expressions,Balanced Expressions}. ++ ++@item Balloon Help ++See `tooltips.' ++ ++@item Base Buffer ++A base buffer is a buffer whose text is shared by an indirect buffer ++(q.v.@:). ++ ++@item Bind ++To bind a key sequence means to give it a binding (q.v.@:). ++@xref{Rebinding}. ++ ++@item Binding ++A key sequence gets its meaning in Emacs by having a binding, which is a ++command (q.v.@:), a Lisp function that is run when you type that ++sequence. @xref{Commands,Binding}. Customization often involves ++rebinding a character to a different command function. The bindings of ++all key sequences are recorded in the keymaps (q.v.@:). @xref{Keymaps}. ++ ++@item Blank Lines ++Blank lines are lines that contain only whitespace. Emacs has several ++commands for operating on the blank lines in the buffer. ++ ++@item Bookmark ++Bookmarks are akin to registers (q.v.@:) in that they record positions ++in buffers to which you can return later. Unlike registers, bookmarks ++persist between Emacs sessions. ++ ++@item Border ++A border is a thin space along the edge of the frame, used just for ++spacing, not for displaying anything. An Emacs frame has an ordinary ++external border, outside of everything including the menu bar, plus an ++internal border that surrounds the text windows, their scroll bars ++and fringes, and separates them from the menu bar and tool bar. You ++can customize both borders with options and resources (@pxref{Borders ++X}). Borders are not the same as fringes (q.v.@:). ++ ++@item Buffer ++The buffer is the basic editing unit; one buffer corresponds to one text ++being edited. You can have several buffers, but at any time you are ++editing only one, the `current buffer,' though several can be visible ++when you are using multiple windows or frames (q.v.@:). Most buffers ++are visiting (q.v.@:) some file. @xref{Buffers}. ++ ++@item Buffer Selection History ++Emacs keeps a buffer selection history which records how recently each ++Emacs buffer has been selected. This is used for choosing a buffer to ++select. @xref{Buffers}. ++ ++@item Bug ++A bug is an incorrect or unreasonable behavior of a program, or ++inaccurate or confusing documentation. Emacs developers treat bug ++reports, both in Emacs code and its documentation, very seriously and ++ask you to report any bugs you find. @xref{Bugs}. ++ ++@item Button Down Event ++A button down event is the kind of input event (q.v.@:) generated ++right away when you press down on a mouse button. @xref{Mouse Buttons}. ++ ++@item By Default ++See `default.' ++ ++@item Byte Compilation ++See `compilation.' ++ ++@item @kbd{C-} ++@kbd{C-} in the name of a character is an abbreviation for Control. ++@xref{User Input,C-}. ++ ++@item @kbd{C-M-} ++@kbd{C-M-} in the name of a character is an abbreviation for ++Control-Meta. If your terminal lacks a real @key{META} key, you type ++a Control-Meta character by typing @key{ESC} and then typing the ++corresponding Control character. @xref{User Input,C-M-}. ++ ++@item Case Conversion ++Case conversion means changing text from upper case to lower case or ++vice versa. @xref{Case}, for the commands for case conversion. ++ ++@item Character ++Characters form the contents of an Emacs buffer. Also, key sequences ++(q.v.@:) are usually made up of characters (though they may include ++other input events as well). @xref{User Input}. ++ ++@item Character Set ++Emacs supports a number of character sets, each of which represents a ++particular alphabet or script. @xref{International}. ++ ++@item Character Terminal ++See `text-only terminal.' ++ ++@item Click Event ++A click event is the kind of input event (q.v.@:) generated when you ++press a mouse button and release it without moving the mouse. ++@xref{Mouse Buttons}. ++ ++@item Clipboard ++A clipboard is a buffer provided by the window system for transferring ++text between applications. On the X Window system, the clipboard is ++provided in addition to the primary selection (q.v.@:); on MS-Windows and Mac, ++the clipboard is used @emph{instead} of the primary selection. ++@xref{Clipboard}. ++ ++@item Coding System ++A coding system is an encoding for representing text characters in a ++file or in a stream of information. Emacs has the ability to convert ++text to or from a variety of coding systems when reading or writing it. ++@xref{Coding Systems}. ++ ++@item Command ++A command is a Lisp function specially defined to be able to serve as a ++key binding in Emacs. When you type a key sequence (q.v.@:), its ++binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find ++the command to run. @xref{Commands}. ++ ++@item Command History ++See `minibuffer history.' ++ ++@item Command Name ++A command name is the name of a Lisp symbol which is a command ++(@pxref{Commands}). You can invoke any command by its name using ++@kbd{M-x} (@pxref{M-x,M-x,Running Commands by Name}). ++ ++@item Comment ++A comment is text in a program which is intended only for humans reading ++the program, and which is specially marked so that it will be ignored ++when the program is loaded or compiled. Emacs offers special commands ++for creating, aligning and killing comments. @xref{Comments}. ++ ++@item Common Lisp ++Common Lisp is a dialect of Lisp (q.v.@:) much larger and more powerful ++than Emacs Lisp. Emacs provides a subset of Common Lisp in the CL ++package. @xref{Top, Common Lisp, Overview, cl, Common Lisp Extensions}. ++ ++@item Compilation ++Compilation is the process of creating an executable program from source ++code. Emacs has commands for compiling files of Emacs Lisp code ++(@pxref{Byte Compilation,,, elisp, the Emacs Lisp ++Reference Manual}) and programs in C and other languages ++(@pxref{Compilation}). ++ ++@item Complete Key ++A complete key is a key sequence which fully specifies one action to be ++performed by Emacs. For example, @kbd{X} and @kbd{C-f} and @kbd{C-x m} ++are complete keys. Complete keys derive their meanings from being bound ++(q.v.@:) to commands (q.v.@:). Thus, @kbd{X} is conventionally bound to ++a command to insert @samp{X} in the buffer; @kbd{C-x m} is ++conventionally bound to a command to begin composing a mail message. ++@xref{Keys}. ++ ++@item Completion ++Completion is what Emacs does when it automatically expands an ++abbreviation for a name into the entire name. Completion is done for ++minibuffer (q.v.@:) arguments when the set of possible valid inputs ++is known; for example, on command names, buffer names, and ++file names. Completion usually occurs when @key{TAB}, @key{SPC} or ++@key{RET} is typed. @xref{Completion}.@refill ++ ++@item Continuation Line ++When a line of text is longer than the width of the window, it ++normally (but see `Truncation') takes up more than one screen line ++when displayed. We say that the text line is continued, and all ++screen lines used for it after the first are called continuation ++lines. @xref{Continuation Lines}. A related Emacs feature is ++`filling' (q.v.@:). ++ ++@item Control Character ++A control character is a character that you type by holding down the ++@key{CTRL} key. Some control characters also have their own keys, so ++that you can type them without using @key{CTRL}. For example, ++@key{RET}, @key{TAB}, @key{ESC} and @key{DEL} are all control ++characters. @xref{User Input}. ++ ++@item Copyleft ++A copyleft is a notice giving the public legal permission to ++redistribute and modify a program or other work of art, but requiring ++modified versions to carry similar permission. Copyright is normally ++used to keep users divided and helpless; with copyleft we turn that ++around to empower users and encourage them to cooperate. ++ ++The particular form of copyleft used by the GNU project is called the ++GNU General Public License. @xref{Copying}. ++ ++@item @key{CTRL} ++The @key{CTRL} or ``control'' key is what you hold down ++in order to enter a control character (q.v.). See also `@kbd{C-}.' ++ ++@item Current Buffer ++The current buffer in Emacs is the Emacs buffer on which most editing ++commands operate. You can select any Emacs buffer as the current one. ++@xref{Buffers}. ++ ++@item Current Line ++The current line is the line that point is on (@pxref{Point}). ++ ++@item Current Paragraph ++The current paragraph is the paragraph that point is in. If point is ++between two paragraphs, the current paragraph is the one that follows ++point. @xref{Paragraphs}. ++ ++@item Current Defun ++The current defun is the defun (q.v.@:) that point is in. If point is ++between defuns, the current defun is the one that follows point. ++@xref{Defuns}. ++ ++@item Cursor ++The cursor is the rectangle on the screen which indicates the position ++(called point; q.v.@:) at which insertion and deletion takes place. ++The cursor is on or under the character that follows point. Often ++people speak of `the cursor' when, strictly speaking, they mean ++`point.' @xref{Point,Cursor}. ++ ++@item Customization ++Customization is making minor changes in the way Emacs works, to ++reflect your preferences or needs. It is often done by setting ++variables (@pxref{Variables}) or faces (@pxref{Face Customization}), ++or by rebinding key sequences (@pxref{Keymaps}). ++ ++@cindex cut and paste ++@item Cut and Paste ++See `killing' and `yanking.' ++ ++@item Daemon ++A daemon is a standard term for a system-level process that runs in the ++background. Daemons are often started when the system first starts up. ++When Emacs runs in daemon-mode, it runs in the background and does not ++open a display. You can then connect to it with the ++@command{emacsclient} program. @xref{Emacs Server}. ++ ++@item Default Argument ++The default for an argument is the value that will be assumed if you ++do not specify one. When the minibuffer is used to read an argument, ++the default argument is used if you just type @key{RET}. ++@xref{Minibuffer}. ++ ++@item Default ++A default is the value that is used for a certain purpose if and when ++you do not specify a value to use. ++ ++@item Default Directory ++When you specify a file name that does not start with @samp{/} or @samp{~}, ++it is interpreted relative to the current buffer's default directory. ++(On MS-Windows and MS-DOS, file names which start with a drive letter ++@samp{@var{x}:} are treated as absolute, not relative.) ++@xref{Minibuffer File,Default Directory}. ++ ++@item Defun ++A defun is a major definition at the top level in a program. The name ++`defun' comes from Lisp, where most such definitions use the construct ++@code{defun}. @xref{Defuns}. ++ ++@item @key{DEL} ++@key{DEL} is a character that runs the command to delete one character ++of text before the cursor. It is typically either the @key{DELETE} ++key or the @key{BACKSPACE} key, whichever one is easy to type. ++@xref{Erasing,DEL}. ++ ++@item Deletion ++Deletion means erasing text without copying it into the kill ring ++(q.v.@:). The alternative is killing (q.v.@:). @xref{Killing,Deletion}. ++ ++@item Deletion of Files ++Deleting a file means erasing it from the file system. ++(Note that some systems use the concept of a ``trash can'', or ``recycle ++bin'', to allow you to ``undelete'' files.) ++@xref{Misc File Ops,Misc File Ops,Miscellaneous File Operations}. ++ ++@item Deletion of Messages ++Deleting a message (in Rmail, and other mail clients) means flagging ++it to be eliminated from your mail file. Until you expunge (q.v.@:) ++the Rmail file, you can still undelete the messages you have deleted. ++@xref{Rmail Deletion}. ++ ++@item Deletion of Windows ++Deleting a window means eliminating it from the screen. Other windows ++expand to use up the space. The text that was in the window is not ++lost, and you can create a new window with the same dimensions as the ++old if you wish. @xref{Windows}. ++ ++@item Directory ++File directories are named collections in the file system, within which ++you can place individual files or subdirectories. They are sometimes ++referred to as ``folders.'' @xref{Directories}. ++ ++@item Dired ++Dired is the Emacs facility that displays the contents of a file ++directory and allows you to ``edit the directory,'' performing ++operations on the files in the directory. @xref{Dired}. ++ ++@item Disabled Command ++A disabled command is one that you may not run without special ++confirmation. The usual reason for disabling a command is that it is ++confusing for beginning users. @xref{Disabling}. ++ ++@item Down Event ++Short for `button down event' (q.v.@:). ++ ++@item Drag Event ++A drag event is the kind of input event (q.v.@:) generated when you ++press a mouse button, move the mouse, and then release the button. ++@xref{Mouse Buttons}. ++ ++@item Dribble File ++A dribble file is a file into which Emacs writes all the characters that ++you type on the keyboard. Dribble files can be used to make a record ++for debugging Emacs bugs. Emacs does not make a dribble file unless you ++tell it to. @xref{Bugs}. ++ ++@item Echo Area ++The echo area is the bottom line of the screen, used for echoing the ++arguments to commands, for asking questions, and showing brief messages ++(including error messages). The messages are stored in the buffer ++@samp{*Messages*} so you can review them later. @xref{Echo Area}. ++ ++@item Echoing ++Echoing is acknowledging the receipt of input events by displaying ++them (in the echo area). Emacs never echoes single-character key ++sequences; longer key sequences echo only if you pause while typing ++them. ++ ++@item Electric ++We say that a character is electric if it is normally self-inserting ++(q.v.@:), but the current major mode (q.v.@:) redefines it to do something ++else as well. For example, some programming language major modes define ++particular delimiter characters to reindent the line, or insert one or ++more newlines in addition to self-insertion. ++ ++@item End Of Line ++End of line is a character or a sequence of characters that indicate ++the end of a text line. On GNU and Unix systems, this is a newline ++(q.v.@:), but other systems have other conventions. @xref{Coding ++Systems,end-of-line}. Emacs can recognize several end-of-line ++conventions in files and convert between them. ++ ++@item Environment Variable ++An environment variable is one of a collection of variables stored by ++the operating system, each one having a name and a value. Emacs can ++access environment variables set by its parent shell, and it can set ++variables in the environment it passes to programs it invokes. ++@xref{Environment}. ++ ++@item EOL ++See `end of line.' ++ ++@item Error ++An error occurs when an Emacs command cannot execute in the current ++circumstances. When an error occurs, execution of the command stops ++(unless the command has been programmed to do otherwise) and Emacs ++reports the error by displaying an error message (q.v.@:). ++@c Not helpful? ++@c Type-ahead is discarded. Then Emacs is ready to read another ++@c editing command. ++ ++@item Error Message ++An error message is output displayed by Emacs when you ask it to do ++something impossible (such as, killing text forward when point is at ++the end of the buffer), or when a command malfunctions in some way. ++Such messages appear in the echo area, accompanied by a beep. ++ ++@item @key{ESC} ++@key{ESC} is a character used as a prefix for typing Meta characters on ++keyboards lacking a @key{META} key. Unlike the @key{META} key (which, ++like the @key{SHIFT} key, is held down while another character is ++typed), you press the @key{ESC} key as you would press a letter key, and ++it applies to the next character you type. ++ ++@item Expression ++See `balanced expression.' ++ ++@item Expunging ++Expunging an Rmail, Gnus newsgroup, or Dired buffer is an operation ++that truly discards the messages or files you have previously flagged ++for deletion. ++ ++@item Face ++A face is a style of displaying characters. It specifies attributes ++such as font family and size, foreground and background colors, ++underline and strike-through, background stipple, etc. Emacs provides ++features to associate specific faces with portions of buffer text, in ++order to display that text as specified by the face attributes. ++@xref{Faces}. ++ ++@item File Locking ++Emacs uses file locking to notice when two different users ++start to edit one file at the same time. @xref{Interlocking}. ++ ++@item File Name ++A file name is a name that refers to a file. File names may be relative ++or absolute; the meaning of a relative file name depends on the current ++directory, but an absolute file name refers to the same file regardless ++of which directory is current. On GNU and Unix systems, an absolute ++file name starts with a slash (the root directory) or with @samp{~/} or ++@samp{~@var{user}/} (a home directory). On MS-Windows/MS-DOS, an ++absolute file name can also start with a drive letter and a colon, e.g. ++@samp{@var{d}:}. ++ ++Some people use the term ``pathname'' for file names, but we do not; ++we use the word ``path'' only in the term ``search path'' (q.v.@:). ++ ++@item File-Name Component ++A file-name component names a file directly within a particular ++directory. On GNU and Unix systems, a file name is a sequence of ++file-name components, separated by slashes. For example, @file{foo/bar} ++is a file name containing two components, @samp{foo} and @samp{bar}; it ++refers to the file named @samp{bar} in the directory named @samp{foo} in ++the current directory. MS-DOS/MS-Windows file names can also use ++backslashes to separate components, as in @file{foo\bar}. ++ ++@item Fill Prefix ++The fill prefix is a string that should be expected at the beginning ++of each line when filling is done. It is not regarded as part of the ++text to be filled. @xref{Filling}. ++ ++@item Filling ++Filling text means adjusting the position of line-breaks to shift text ++between consecutive lines, so that all the lines are approximately the ++same length. @xref{Filling}. Some other editors call this feature ++`line wrapping.' ++ ++@item Font Lock ++Font Lock is a mode that highlights parts of buffer text in different ++faces, according to the syntax. For example, all comments (q.v.@:) ++might be colored red. @xref{Font Lock}. ++ ++@item Fontset ++A fontset is a named collection of fonts. A fontset specification lists ++character sets and which font to use to display each of them. Fontsets ++make it easy to change several fonts at once by specifying the name of a ++fontset, rather than changing each font separately. @xref{Fontsets}. ++ ++@item Formatted Text ++Formatted text is text that displays with formatting information while ++you edit. Formatting information includes fonts, colors, and specified ++margins. @xref{Formatted Text}. ++ ++@item Formfeed Character ++See `page.' ++ ++@item Frame ++A frame is a rectangular cluster of Emacs windows. Emacs starts out ++with one frame, but you can create more. You can subdivide each frame ++into Emacs windows (q.v.@:). When you are using a window system ++(q.v.@:), more than one frame can be visible at the same time. ++@xref{Frames}. Some other editors use the term ``window'' for this, ++but in Emacs a window means something else. ++ ++@item Free Software ++Free software is software that gives you the freedom to share, study ++and modify it. Emacs is free software, part of the GNU project ++(q.v.@:), and distributed under a copyleft (q.v.@:) license called the ++GNU General Public License. @xref{Copying}. ++ ++@item Free Software Foundation ++The Free Software Foundation (FSF) is a charitable foundation ++dedicated to promoting the development of free software (q.v.@:). ++For more information, see @uref{http://fsf.org/, the FSF website}. ++ ++@item Fringe ++On a graphical display (q.v.@:), there's a narrow portion of the frame ++(q.v.@:) between the text area and the window's border. These ++`fringes' are used to display symbols that provide information about ++the buffer text (@pxref{Fringes}). Emacs displays the fringe using a ++special face (q.v.@:) called @code{fringe}. @xref{Faces,fringe}. ++ ++@item FSF ++See `Free Software Foundation.' ++ ++@item FTP ++FTP is an acronym for File Transfer Protocol. This is one standard ++method for retrieving remote files (q.v.@:). ++ ++@item Function Key ++A function key is a key on the keyboard that sends input but does not ++correspond to any character. @xref{Function Keys}. ++ ++@item Global ++Global means ``independent of the current environment; in effect ++throughout Emacs.'' It is the opposite of local (q.v.@:). Particular ++examples of the use of `global' appear below. ++ ++@item Global Abbrev ++A global definition of an abbrev (q.v.@:) is effective in all major ++modes that do not have local (q.v.@:) definitions for the same abbrev. ++@xref{Abbrevs}. ++ ++@item Global Keymap ++The global keymap (q.v.@:) contains key bindings that are in effect ++everywhere, except when overridden by local key bindings in a major ++mode's local keymap (q.v.@:). @xref{Keymaps}. ++ ++@item Global Mark Ring ++The global mark ring records the series of buffers you have recently ++set a mark (q.v.@:) in. In many cases you can use this to backtrack ++through buffers you have been editing, or in which you have found ++tags (see `tags table'). @xref{Global Mark Ring}. ++ ++@item Global Substitution ++Global substitution means replacing each occurrence of one string by ++another string throughout a large amount of text. @xref{Replace}. ++ ++@item Global Variable ++The global value of a variable (q.v.@:) takes effect in all buffers ++that do not have their own local (q.v.@:) values for the variable. ++@xref{Variables}. ++ ++@item GNU ++GNU is a recursive acronym for GNU's Not Unix, and it refers to a ++Unix-compatible operating system which is free software (q.v.@:). ++@xref{Manifesto}. GNU is normally used with Linux as the kernel since ++Linux works better than the GNU kernel. For more information, see ++@uref{http://www.gnu.org/, the GNU website}. ++ ++@item Graphic Character ++Graphic characters are those assigned pictorial images rather than ++just names. All the non-Meta (q.v.@:) characters except for the ++Control (q.v.@:) characters are graphic characters. These include ++letters, digits, punctuation, and spaces; they do not include ++@key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts ++that character (in ordinary editing modes). @xref{Inserting Text}. ++ ++@item Graphical Display ++A graphical display is one that can display images and multiple fonts. ++Usually it also has a window system (q.v.@:). ++ ++@item Highlighting ++Highlighting text means displaying it with a different foreground and/or ++background color to make it stand out from the rest of the text in the ++buffer. ++ ++Emacs uses highlighting in several ways. It highlights the region ++whenever it is active (@pxref{Mark}). Incremental search also ++highlights matches (@pxref{Incremental Search}). See also `font lock.' ++ ++@item Hardcopy ++Hardcopy means printed output. Emacs has various commands for ++printing the contents of Emacs buffers. @xref{Printing}. ++ ++@item @key{HELP} ++@key{HELP} is the Emacs name for @kbd{C-h} or @key{F1}. You can type ++@key{HELP} at any time to ask what options you have, or to ask what any ++command does. @xref{Help}. ++ ++@item Help Echo ++Help echo is a short message displayed in the echo area (q.v.@:) when ++the mouse pointer is located on portions of display that require some ++explanations. Emacs displays help echo for menu items, parts of the ++mode line, tool-bar buttons, etc. On graphics displays, the messages ++can be displayed as tooltips (q.v.@:). @xref{Tooltips}. ++ ++@item Home Directory ++Your home directory contains your personal files. On a multi-user GNU ++or Unix system, each user has his or her own home directory. When you ++start a new login session, your home directory is the default ++directory in which to start. A standard shorthand for your home ++directory is @samp{~}. Similarly, @samp{~@var{user}} represents the ++home directory of some other user. ++ ++@item Hook ++A hook is a list of functions to be called on specific occasions, such ++as saving a buffer in a file, major mode activation, etc. By ++customizing the various hooks, you can modify Emacs's behavior without ++changing any of its code. @xref{Hooks}. ++ ++@item Hyper ++Hyper is the name of a modifier bit that a keyboard input character may ++have. To make a character Hyper, type it while holding down the ++@key{HYPER} key. Such characters are given names that start with ++@kbd{Hyper-} (usually written @kbd{H-} for short). @xref{User Input}. ++ ++@item Iff ++``Iff'' means ``if and only if.'' This terminology comes from ++mathematics. Try to avoid using this term in documentation, since ++many are unfamiliar with it and mistake it for a typo. ++ ++@item Inbox ++An inbox is a file in which mail is delivered by the operating system. ++Rmail transfers mail from inboxes to Rmail files (q.v.@:) in which the ++mail is then stored permanently or until explicitly deleted. ++@xref{Rmail Inbox}. ++ ++@item Incremental Search ++Emacs provides an incremental search facility, whereby Emacs begins ++searching for a string as soon as you type the first character. ++As you type more characters, it refines the search. @xref{Incremental Search}. ++ ++@item Indentation ++Indentation means blank space at the beginning of a line. Most ++programming languages have conventions for using indentation to ++illuminate the structure of the program, and Emacs has special ++commands to adjust indentation. ++@xref{Indentation}. ++ ++@item Indirect Buffer ++An indirect buffer is a buffer that shares the text of another buffer, ++called its base buffer (q.v.@:). @xref{Indirect Buffers}. ++ ++@item Info ++Info is the hypertext format used by the GNU project for writing ++documentation. ++ ++@item Input Event ++An input event represents, within Emacs, one action taken by the user on ++the terminal. Input events include typing characters, typing function ++keys, pressing or releasing mouse buttons, and switching between Emacs ++frames. @xref{User Input}. ++ ++@item Input Method ++An input method is a system for entering non-@acronym{ASCII} text characters by ++typing sequences of @acronym{ASCII} characters (q.v.@:). @xref{Input Methods}. ++ ++@item Insertion ++Insertion means adding text into the buffer, either from the keyboard ++or from some other place in Emacs. ++ ++@item Interlocking ++Interlocking is a feature for warning when you start to alter a file ++that someone else is already editing. ++@xref{Interlocking,Interlocking,Simultaneous Editing}. ++ ++@item Isearch ++See `incremental search.' ++ ++@item Justification ++Justification means adding extra spaces within lines of text ++in order to adjust the position of the text edges. ++@xref{Format Justification}. ++ ++@item Key Binding ++See `binding.' ++ ++@item Keyboard Macro ++Keyboard macros are a way of defining new Emacs commands from ++sequences of existing ones, with no need to write a Lisp program. ++You can use a macro to record a sequence of commands, then ++play them back as many times as you like. ++@xref{Keyboard Macros}. ++ ++@cindex keyboard shortcuts ++@item Keyboard Shortcut ++A keyboard shortcut is a key sequence (q.v.@:) which invokes a ++command. What some programs call ``assigning a keyboard shortcut,'' ++Emacs calls ``binding a key sequence.'' See `binding.' ++ ++@item Key Sequence ++A key sequence (key, for short) is a sequence of input events (q.v.@:) ++that are meaningful as a single unit. If the key sequence is enough to ++specify one action, it is a complete key (q.v.@:); if it is not enough, ++it is a prefix key (q.v.@:). @xref{Keys}. ++ ++@item Keymap ++The keymap is the data structure that records the bindings (q.v.@:) of ++key sequences to the commands that they run. For example, the global ++keymap binds the character @kbd{C-n} to the command function ++@code{next-line}. @xref{Keymaps}. ++ ++@item Keyboard Translation Table ++The keyboard translation table is an array that translates the character ++codes that come from the terminal into the character codes that make up ++key sequences. ++ ++@item Kill Ring ++The kill ring is where all text you have killed recently is saved. ++You can reinsert any of the killed text still in the ring; this is ++called yanking (q.v.@:). @xref{Yanking}. ++ ++@item Killing ++Killing means erasing text and saving it on the kill ring so it can be ++yanked (q.v.@:) later. Some other systems call this ``cutting.'' ++Most Emacs commands that erase text perform killing, as opposed to ++deletion (q.v.@:). @xref{Killing}. ++ ++@item Killing a Job ++Killing a job (such as, an invocation of Emacs) means making it cease ++to exist. Any data within it, if not saved in a file, is lost. ++@xref{Exiting}. ++ ++@item Language Environment ++Your choice of language environment specifies defaults for the input ++method (q.v.@:) and coding system (q.v.@:). @xref{Language ++Environments}. These defaults are relevant if you edit ++non-@acronym{ASCII} text (@pxref{International}). ++ ++@item Line Wrapping ++See `filling.' ++ ++@item Lisp ++Lisp is a programming language. Most of Emacs is written in a dialect ++of Lisp, called Emacs Lisp, which is extended with special features that ++make it especially suitable for text editing tasks. ++ ++@item List ++A list is, approximately, a text string beginning with an open ++parenthesis and ending with the matching close parenthesis. In C mode ++and other non-Lisp modes, groupings surrounded by other kinds of matched ++delimiters appropriate to the language, such as braces, are also ++considered lists. Emacs has special commands for many operations on ++lists. @xref{Moving by Parens}. ++ ++@item Local ++Local means ``in effect only in a particular context''; the relevant ++kind of context is a particular function execution, a particular ++buffer, or a particular major mode. It is the opposite of `global' ++(q.v.@:). Specific uses of `local' in Emacs terminology appear below. ++ ++@item Local Abbrev ++A local abbrev definition is effective only if a particular major mode ++is selected. In that major mode, it overrides any global definition ++for the same abbrev. @xref{Abbrevs}. ++ ++@item Local Keymap ++A local keymap is used in a particular major mode; the key bindings ++(q.v.@:) in the current local keymap override global bindings of the ++same key sequences. @xref{Keymaps}. ++ ++@item Local Variable ++A local value of a variable (q.v.@:) applies to only one buffer. ++@xref{Locals}. ++ ++@item @kbd{M-} ++@kbd{M-} in the name of a character is an abbreviation for @key{META}, ++one of the modifier keys that can accompany any character. ++@xref{User Input,M-}. ++ ++@item @kbd{M-C-} ++@kbd{M-C-} in the name of a character is an abbreviation for ++Control-Meta; it means the same thing as `@kbd{C-M-}' (q.v.@:). ++ ++@item @kbd{M-x} ++@kbd{M-x} is the key sequence that is used to call an Emacs command by ++name. This is how you run commands that are not bound to key sequences. ++@xref{M-x,M-x,Running Commands by Name}. ++ ++@item Mail ++Mail means messages sent from one user to another through the computer ++system, to be read at the recipient's convenience. Emacs has commands for ++composing and sending mail, and for reading and editing the mail you have ++received. @xref{Sending Mail}. @xref{Rmail}, for one way to read ++mail with Emacs. ++ ++@item Mail Composition Method ++A mail composition method is a program runnable within Emacs for editing ++and sending a mail message. Emacs lets you select from several ++alternative mail composition methods. @xref{Mail Methods}. ++ ++@item Major Mode ++The Emacs major modes are a mutually exclusive set of options, each of ++which configures Emacs for editing a certain sort of text. Ideally, ++each programming language has its own major mode. @xref{Major Modes}. ++ ++@item Margin ++The space between the usable part of a window (including the ++fringe) and the window edge. ++ ++@item Mark ++The mark points to a position in the text. It specifies one end of the ++region (q.v.@:), point being the other end. Many commands operate on ++all the text from point to the mark. Each buffer has its own mark. ++@xref{Mark}. ++ ++@item Mark Ring ++The mark ring is used to hold several recent previous locations of the ++mark, just in case you want to move back to them. Each buffer has its ++own mark ring; in addition, there is a single global mark ring (q.v.@:). ++@xref{Mark Ring}. ++ ++@item Menu Bar ++The menu bar is a line at the top of an Emacs frame. It contains ++words you can click on with the mouse to bring up menus, or you can use ++a keyboard interface to navigate it. @xref{Menu Bars}. ++ ++@item Message ++See `mail.' ++ ++@item Meta ++Meta is the name of a modifier bit which you can use in a command ++character. To enter a meta character, you hold down the @key{META} ++key while typing the character. We refer to such characters with ++names that start with @kbd{Meta-} (usually written @kbd{M-} for ++short). For example, @kbd{M-<} is typed by holding down @key{META} ++and at the same time typing @kbd{<} (which itself is done, on most ++terminals, by holding down @key{SHIFT} and typing @kbd{,}). ++@xref{User Input,Meta}. ++ ++On some terminals, the @key{META} key is actually labeled @key{ALT} ++or @key{EDIT}. ++ ++@item Meta Character ++A Meta character is one whose character code includes the Meta bit. ++ ++@item Minibuffer ++The minibuffer is the window that appears when necessary inside the ++echo area (q.v.@:), used for reading arguments to commands. ++@xref{Minibuffer}. ++ ++@item Minibuffer History ++The minibuffer history records the text you have specified in the past ++for minibuffer arguments, so you can conveniently use the same text ++again. @xref{Minibuffer History}. ++ ++@item Minor Mode ++A minor mode is an optional feature of Emacs which can be switched on ++or off independently of all other features. Each minor mode has a ++command to turn it on or off. Some minor modes are global (q.v.@:), ++and some are local (q.v.@:). @xref{Minor Modes}. ++ ++@item Minor Mode Keymap ++A minor mode keymap is a keymap that belongs to a minor mode and is ++active when that mode is enabled. Minor mode keymaps take precedence ++over the buffer's local keymap, just as the local keymap takes ++precedence over the global keymap. @xref{Keymaps}. ++ ++@item Mode Line ++The mode line is the line at the bottom of each window (q.v.@:), giving ++status information on the buffer displayed in that window. @xref{Mode ++Line}. ++ ++@item Modified Buffer ++A buffer (q.v.@:) is modified if its text has been changed since the ++last time the buffer was saved (or since it was created, if it ++has never been saved). @xref{Saving}. ++ ++@item Moving Text ++Moving text means erasing it from one place and inserting it in ++another. The usual way to move text is by killing (q.v.@:) it and then ++yanking (q.v.@:) it. @xref{Killing}. ++ ++@item MULE ++MULE refers to the Emacs features for editing multilingual ++non-@acronym{ASCII} text using multibyte characters (q.v.@:). ++@xref{International}. ++ ++@item Multibyte Character ++A multibyte character is a character that takes up several bytes in a ++buffer. Emacs uses multibyte characters to represent non-@acronym{ASCII} text, ++since the number of non-@acronym{ASCII} characters is much more than 256. ++@xref{International Chars, International Characters}. ++ ++@item Named Mark ++A named mark is a register (q.v.@:) in its role of recording a ++location in text so that you can move point to that location. ++@xref{Registers}. ++ ++@item Narrowing ++Narrowing means creating a restriction (q.v.@:) that limits editing in ++the current buffer to only a part of the text. Text outside that part ++is inaccessible for editing (or viewing) until the boundaries are ++widened again, but it is still there, and saving the file saves it ++all. @xref{Narrowing}. ++ ++@item Newline ++Control-J characters in the buffer terminate lines of text and are ++therefore also called newlines. See `End of Line.' ++ ++@cindex nil ++@cindex t ++@item @code{nil} ++@code{nil} is a value usually interpreted as a logical ``false.'' Its ++opposite is @code{t}, interpreted as ``true.'' ++ ++@item Numeric Argument ++A numeric argument is a number, specified before a command, to change ++the effect of the command. Often the numeric argument serves as a ++repeat count. @xref{Arguments}. ++ ++@item Overwrite Mode ++Overwrite mode is a minor mode. When it is enabled, ordinary text ++characters replace the existing text after point rather than pushing ++it to the right. @xref{Minor Modes}. ++ ++@item Page ++A page is a unit of text, delimited by formfeed characters (@acronym{ASCII} ++control-L, code 014) coming at the beginning of a line. Some Emacs ++commands are provided for moving over and operating on pages. ++@xref{Pages}. ++ ++@item Paragraph ++Paragraphs are the medium-size unit of human-language text. There are ++special Emacs commands for moving over and operating on paragraphs. ++@xref{Paragraphs}. ++ ++@item Parsing ++We say that certain Emacs commands parse words or expressions in the ++text being edited. Really, all they know how to do is find the other ++end of a word or expression. @xref{Syntax}. ++ ++@item Point ++Point is the place in the buffer at which insertion and deletion ++occur. Point is considered to be between two characters, not at one ++character. The terminal's cursor (q.v.@:) indicates the location of ++point. @xref{Point}. ++ ++@item Prefix Argument ++See `numeric argument.' ++ ++@item Prefix Key ++A prefix key is a key sequence (q.v.@:) whose sole function is to ++introduce a set of longer key sequences. @kbd{C-x} is an example of ++prefix key; any two-character sequence starting with @kbd{C-x} is ++therefore a legitimate key sequence. @xref{Keys}. ++ ++@item Primary Rmail File ++Your primary Rmail file is the file named @samp{RMAIL} in your home ++directory. That's where Rmail stores your incoming mail, unless you ++specify a different file name. @xref{Rmail}. ++ ++@item Primary Selection ++The primary selection is one particular X selection (q.v.@:); it is the ++selection that most X applications use for transferring text to and from ++other applications. ++ ++The Emacs kill commands set the primary selection and the yank command ++uses the primary selection when appropriate. @xref{Killing}. ++ ++@item Prompt ++A prompt is text used to ask you for input. Displaying a prompt ++is called prompting. Emacs prompts always appear in the echo area ++(q.v.@:). One kind of prompting happens when the minibuffer is used to ++read an argument (@pxref{Minibuffer}); the echoing that happens when ++you pause in the middle of typing a multi-character key sequence is also ++a kind of prompting (@pxref{Echo Area}). ++ ++@item Query-Replace ++Query-replace is an interactive string replacement feature provided by ++Emacs. @xref{Query Replace}. ++ ++@item Quitting ++Quitting means canceling a partially typed command or a running ++command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}. ++ ++@item Quoting ++Quoting means depriving a character of its usual special significance. ++The most common kind of quoting in Emacs is with @kbd{C-q}. What ++constitutes special significance depends on the context and on ++convention. For example, an ``ordinary'' character as an Emacs command ++inserts itself; so in this context, a special character is any character ++that does not normally insert itself (such as @key{DEL}, for example), ++and quoting it makes it insert itself as if it were not special. Not ++all contexts allow quoting. @xref{Inserting Text,Quoting}. ++ ++@item Quoting File Names ++Quoting a file name turns off the special significance of constructs ++such as @samp{$}, @samp{~} and @samp{:}. @xref{Quoted File Names}. ++ ++@item Read-Only Buffer ++A read-only buffer is one whose text you are not allowed to change. ++Normally Emacs makes buffers read-only when they contain text which ++has a special significance to Emacs; for example, Dired buffers. ++Visiting a file that is write-protected also makes a read-only buffer. ++@xref{Buffers}. ++ ++@item Rectangle ++A rectangle consists of the text in a given range of columns on a given ++range of lines. Normally you specify a rectangle by putting point at ++one corner and putting the mark at the diagonally opposite corner. ++@xref{Rectangles}. ++ ++@item Recursive Editing Level ++A recursive editing level is a state in which part of the execution of ++a command involves asking you to edit some text. This text may ++or may not be the same as the text to which the command was applied. ++The mode line indicates recursive editing levels with square brackets ++(@samp{[} and @samp{]}). @xref{Recursive Edit}. ++ ++@item Redisplay ++Redisplay is the process of correcting the image on the screen to ++correspond to changes that have been made in the text being edited. ++@xref{Screen,Redisplay}. ++ ++@item Regexp ++See `regular expression.' ++ ++@item Region ++The region is the text between point (q.v.@:) and the mark (q.v.@:). ++Many commands operate on the text of the region. @xref{Mark,Region}. ++ ++@item Register ++Registers are named slots in which text, buffer positions, or ++rectangles can be saved for later use. @xref{Registers}. A related ++Emacs feature is `bookmarks' (q.v.@:). ++ ++@item Regular Expression ++A regular expression is a pattern that can match various text strings; ++for example, @samp{a[0-9]+} matches @samp{a} followed by one or more ++digits. @xref{Regexps}. ++ ++@item Remote File ++A remote file is a file that is stored on a system other than your own. ++Emacs can access files on other computers provided that they are ++connected to the same network as your machine, and (obviously) that ++you have a supported method to gain access to those files. ++@xref{Remote Files}. ++ ++@item Repeat Count ++See `numeric argument.' ++ ++@item Replacement ++See `global substitution.' ++ ++@item Restriction ++A buffer's restriction is the amount of text, at the beginning or the ++end of the buffer, that is temporarily inaccessible. Giving a buffer a ++nonzero amount of restriction is called narrowing (q.v.@:); removing ++a restriction is called widening (q.v.@:). @xref{Narrowing}. ++ ++@item @key{RET} ++@key{RET} is a character that in Emacs runs the command to insert a ++newline into the text. It is also used to terminate most arguments ++read in the minibuffer (q.v.@:). @xref{User Input,Return}. ++ ++@item Reverting ++Reverting means returning to the original state. Emacs lets you ++revert a buffer by re-reading its file from disk. @xref{Reverting}. ++ ++@item Rmail File ++An Rmail file is a file containing text in the format used by ++Rmail for storing mail. @xref{Rmail}. ++ ++@item Saving ++Saving a buffer means copying its text into the file that was visited ++(q.v.@:) in that buffer. This is the way text in files actually gets ++changed by your Emacs editing. @xref{Saving}. ++ ++@item Scroll Bar ++A scroll bar is a tall thin hollow box that appears at the side of a ++window. You can use mouse commands in the scroll bar to scroll the ++window. The scroll bar feature is supported only under windowing ++systems. @xref{Scroll Bars}. ++ ++@item Scrolling ++Scrolling means shifting the text in the Emacs window so as to see a ++different part of the buffer. @xref{Scrolling}. ++ ++@item Searching ++Searching means moving point to the next occurrence of a specified ++string or the next match for a specified regular expression. ++@xref{Search}. ++ ++@item Search Path ++A search path is a list of directory names, to be used for searching for ++files for certain purposes. For example, the variable @code{load-path} ++holds a search path for finding Lisp library files. @xref{Lisp Libraries}. ++ ++@item Secondary Selection ++The secondary selection is one particular X selection (q.v.@:); some X ++applications can use it for transferring text to and from other ++applications. Emacs has special mouse commands for transferring text ++using the secondary selection. @xref{Secondary Selection}. ++ ++@item Selected Frame ++The selected frame is the one your input currently operates on. ++@xref{Frames}. ++ ++@item Selected Window ++The selected window is the one your input currently operates on. ++@xref{Basic Window}. ++ ++@item Selecting a Buffer ++Selecting a buffer means making it the current (q.v.@:) buffer. ++@xref{Select Buffer}. ++ ++@item Selection ++Windowing systems allow an application program to specify ++selections whose values are text. A program can also read the ++selections that other programs have set up. This is the principal way ++of transferring text between window applications. Emacs has commands to ++work with the primary (q.v.@:) selection and the secondary (q.v.@:) ++selection, and also with the clipboard (q.v.@:). ++ ++@item Self-Documentation ++Self-documentation is the feature of Emacs that can tell you what any ++command does, or give you a list of all commands related to a topic ++you specify. You ask for self-documentation with the help character, ++@kbd{C-h}. @xref{Help}. ++ ++@item Self-Inserting Character ++A character is self-inserting if typing that character inserts that ++character in the buffer. Ordinary printing and whitespace characters ++are self-inserting in Emacs, except in certain special major modes. ++ ++@item Sentences ++Emacs has commands for moving by or killing by sentences. ++@xref{Sentences}. ++ ++@item Sexp ++A sexp (short for ``s-expression'') is the basic syntactic unit of ++Lisp in its textual form: either a list, or Lisp atom. Sexps are also ++the balanced expressions (q.v.@:) of the Lisp language; this is why ++the commands for editing balanced expressions have `sexp' in their ++name. @xref{Expressions,Sexps}. ++ ++@item Simultaneous Editing ++Simultaneous editing means two users modifying the same file at once. ++Simultaneous editing, if not detected, can cause one user to lose his ++or her work. Emacs detects all cases of simultaneous editing, and ++warns one of the users to investigate. ++@xref{Interlocking,Interlocking,Simultaneous Editing}. ++ ++@item @key{SPC} ++@key{SPC} is the space character, which you enter by pressing the ++space bar. ++ ++@item Speedbar ++The speedbar is a special tall frame that provides fast access to Emacs ++buffers, functions within those buffers, Info nodes, and other ++interesting parts of text within Emacs. @xref{Speedbar}. ++ ++@item Spell Checking ++Spell checking means checking correctness of the written form of each ++one of the words in a text. Emacs can use various external ++spelling-checker programs to check the spelling of parts of a buffer ++via a convenient user interface. @xref{Spelling}. ++ ++@item String ++A string is a kind of Lisp data object which contains a sequence of ++characters. Many Emacs variables are intended to have strings as ++values. The Lisp syntax for a string consists of the characters in the ++string with a @samp{"} before and another @samp{"} after. A @samp{"} ++that is part of the string must be written as @samp{\"} and a @samp{\} ++that is part of the string must be written as @samp{\\}. All other ++characters, including newline, can be included just by writing them ++inside the string; however, backslash sequences as in C, such as ++@samp{\n} for newline or @samp{\241} using an octal character code, are ++allowed as well. ++ ++@item String Substitution ++See `global substitution.' ++ ++@item Syntax Highlighting ++See `font lock.' ++ ++@item Syntax Table ++The syntax table tells Emacs which characters are part of a word, ++which characters balance each other like parentheses, etc. ++@xref{Syntax}. ++ ++@item Super ++Super is the name of a modifier bit that a keyboard input character may ++have. To make a character Super, type it while holding down the ++@key{SUPER} key. Such characters are given names that start with ++@kbd{Super-} (usually written @kbd{s-} for short). @xref{User Input}. ++ ++@item Suspending ++Suspending Emacs means stopping it temporarily and returning control ++to its parent process, which is usually a shell. Unlike killing a job ++(q.v.@:), you can later resume the suspended Emacs job without losing ++your buffers, unsaved edits, undo history, etc. @xref{Exiting}. ++ ++@item @key{TAB} ++@key{TAB} is the tab character. In Emacs it is typically used for ++indentation or completion. ++ ++@item Tags Table ++A tags table is a file that serves as an index to the function ++definitions in one or more other files. @xref{Tags}. ++ ++@item Termscript File ++A termscript file contains a record of all characters sent by Emacs to ++the terminal. It is used for tracking down bugs in Emacs redisplay. ++Emacs does not make a termscript file unless you tell it to. ++@xref{Bugs}. ++ ++@item Text ++`Text' has two meanings (@pxref{Text}): ++ ++@itemize @bullet ++@item ++Data consisting of a sequence of characters, as opposed to binary ++numbers, executable programs, and the like. The basic contents of an ++Emacs buffer (aside from the text properties, q.v.@:) are always text ++in this sense. ++@item ++Data consisting of written human language (as opposed to programs), ++or following the stylistic conventions of human language. ++@end itemize ++ ++@item Text-only Terminal ++A text-only terminal is a display that is limited to displaying text in ++character units. Such a terminal cannot control individual pixels it ++displays. Emacs supports a subset of display features on text-only ++terminals. ++ ++@item Text Properties ++Text properties are annotations recorded for particular characters in ++the buffer. Images in the buffer are recorded as text properties; ++they also specify formatting information. @xref{Editing Format Info}. ++ ++@item Tool Bar ++The tool bar is a line (sometimes multiple lines) of icons at the top ++of an Emacs frame. Clicking on one of these icons executes a command. ++You can think of this as a graphical relative of the menu bar (q.v.@:). ++@xref{Tool Bars}. ++ ++@item Tooltips ++Tooltips are small windows displaying a help echo (q.v.@:) text, which ++explains parts of the display, lists useful options available via mouse ++clicks, etc. @xref{Tooltips}. ++ ++@item Top Level ++Top level is the normal state of Emacs, in which you are editing the ++text of the file you have visited. You are at top level whenever you ++are not in a recursive editing level (q.v.@:) or the minibuffer ++(q.v.@:), and not in the middle of a command. You can get back to top ++level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}. ++ ++@item Transposition ++Transposing two units of text means putting each one into the place ++formerly occupied by the other. There are Emacs commands to transpose ++two adjacent characters, words, balanced expressions (q.v.@:) or lines ++(@pxref{Transpose}). ++ ++@item Truncation ++Truncating text lines in the display means leaving out any text on a ++line that does not fit within the right margin of the window ++displaying it. See also `continuation line.' ++@xref{Continuation Lines,Truncation}. ++ ++@item TTY ++See `text-only terminal.' ++ ++@item Undoing ++Undoing means making your previous editing go in reverse, bringing ++back the text that existed earlier in the editing session. ++@xref{Undo}. ++ ++@item Unix ++Unix is a class of multi-user computer operating systems with a long ++history. There are several implementations today. The GNU project ++(q.v.@:) aims to develop a complete Unix-like operating system that ++is free software (q.v.@:). ++ ++@item User Option ++A user option is a face (q.v.@:) or a variable (q.v.@:) that exists so ++that you can customize Emacs by setting it to a new value. ++@xref{Easy Customization}. ++ ++@item Variable ++A variable is an object in Lisp that can store an arbitrary value. ++Emacs uses some variables for internal purposes, and has others (known ++as `user options'; q.v.@:) just so that you can set their values to ++control the behavior of Emacs. The variables used in Emacs that you ++are likely to be interested in are listed in the Variables Index in ++this manual (@pxref{Variable Index}). @xref{Variables}, for ++information on variables. ++ ++@item Version Control ++Version control systems keep track of multiple versions of a source file. ++They provide a more powerful alternative to keeping backup files (q.v.@:). ++@xref{Version Control}. ++ ++@item Visiting ++Visiting a file means loading its contents into a buffer (q.v.@:) ++where they can be edited. @xref{Visiting}. ++ ++@item Whitespace ++Whitespace is any run of consecutive formatting characters (space, ++tab, newline, and backspace). ++ ++@item Widening ++Widening is removing any restriction (q.v.@:) on the current buffer; ++it is the opposite of narrowing (q.v.@:). @xref{Narrowing}. ++ ++@item Window ++Emacs divides a frame (q.v.@:) into one or more windows, each of which ++can display the contents of one buffer (q.v.@:) at any time. ++@xref{Screen}, for basic information on how Emacs uses the screen. ++@xref{Windows}, for commands to control the use of windows. Some ++other editors use the term ``window'' for what we call a `frame' ++(q.v.@:) in Emacs. ++ ++@item Window System ++A window system is software that operates on a graphical display ++(q.v.@:), to subdivide the screen so that multiple applications can ++have their] own windows at the same time. All modern operating systems ++include a window system. ++ ++@item Word Abbrev ++See `abbrev.' ++ ++@item Word Search ++Word search is searching for a sequence of words, considering the ++punctuation between them as insignificant. @xref{Word Search}. ++ ++@item WYSIWYG ++WYSIWYG stands for ``What you see is what you get.'' Emacs generally ++provides WYSIWYG editing for files of characters; in Enriched mode ++(@pxref{Formatted Text}), it provides WYSIWYG editing for files that ++include text formatting information. ++ ++@item Yanking ++Yanking means reinserting text previously killed (q.v.@:). It can be ++used to undo a mistaken kill, or for copying or moving text. Some ++other systems call this ``pasting.'' @xref{Yanking}. ++@end table ++ ++@ignore ++ arch-tag: 0dd53ce1-5f09-4ac2-b13b-cf22b0f28d23 ++@end ignore +diff --git a/doc/emacs/gnu.texi b/doc/emacs/gnu.texi +new file mode 100644 +index 0000000..f8d23b2 +--- /dev/null ++++ b/doc/emacs/gnu.texi +@@ -0,0 +1,555 @@ ++@c Copyright (C) 1985, 1986, 1987, 1993, 1995, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c ++@c Permission is granted to anyone to make or distribute verbatim copies ++@c of this document, in any medium, provided that the copyright notice and ++@c permission notice are preserved, and that the distributor grants the ++@c recipient permission for further redistribution as permitted by this ++@c notice. ++@c ++@c Modified versions may not be made. ++ ++@ifclear justgnu ++@node Manifesto,, Microsoft Windows, Top ++@unnumbered The GNU Manifesto ++@end ifclear ++@ifset justgnu ++@node Top ++@top The GNU Manifesto ++@end ifset ++ ++@quotation ++The GNU Manifesto which appears below was written by Richard Stallman at ++the beginning of the GNU project, to ask for participation and support. ++For the first few years, it was updated in minor ways to account for ++developments, but now it seems best to leave it unchanged as most people ++have seen it. ++ ++Since that time, we have learned about certain common misunderstandings ++that different wording could help avoid. Footnotes added in 1993 help ++clarify these points. ++ ++For up-to-date information about available GNU software, please see ++our web site, @uref{http://www.gnu.org}. For software tasks and other ++ways to contribute, see @uref{http://www.gnu.org/help}. ++@end quotation ++ ++@unnumberedsec What's GNU? Gnu's Not Unix! ++ ++GNU, which stands for Gnu's Not Unix, is the name for the complete ++Unix-compatible software system which I am writing so that I can give it ++away free to everyone who can use it.@footnote{The wording here was ++careless. The intention was that nobody would have to pay for ++@emph{permission} to use the GNU system. But the words don't make this ++clear, and people often interpret them as saying that copies of GNU ++should always be distributed at little or no charge. That was never the ++intent; later on, the manifesto mentions the possibility of companies ++providing the service of distribution for a profit. Subsequently I have ++learned to distinguish carefully between ``free'' in the sense of ++freedom and ``free'' in the sense of price. Free software is software ++that users have the freedom to distribute and change. Some users may ++obtain copies at no charge, while others pay to obtain copies---and if ++the funds help support improving the software, so much the better. The ++important thing is that everyone who has a copy has the freedom to ++cooperate with others in using it.} Several other volunteers are helping ++me. Contributions of time, money, programs and equipment are greatly ++needed. ++ ++So far we have an Emacs text editor with Lisp for writing editor commands, ++a source level debugger, a yacc-compatible parser generator, a linker, and ++around 35 utilities. A shell (command interpreter) is nearly completed. A ++new portable optimizing C compiler has compiled itself and may be released ++this year. An initial kernel exists but many more features are needed to ++emulate Unix. When the kernel and compiler are finished, it will be ++possible to distribute a GNU system suitable for program development. We ++will use @TeX{} as our text formatter, but an nroff is being worked on. We ++will use the free, portable X window system as well. After this we will ++add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of ++other things, plus on-line documentation. We hope to supply, eventually, ++everything useful that normally comes with a Unix system, and more. ++ ++GNU will be able to run Unix programs, but will not be identical to Unix. ++We will make all improvements that are convenient, based on our experience ++with other operating systems. In particular, we plan to have longer ++file names, file version numbers, a crashproof file system, file name ++completion perhaps, terminal-independent display support, and perhaps ++eventually a Lisp-based window system through which several Lisp programs ++and ordinary Unix programs can share a screen. Both C and Lisp will be ++available as system programming languages. We will try to support UUCP, ++MIT Chaosnet, and Internet protocols for communication. ++ ++GNU is aimed initially at machines in the 68000/16000 class with virtual ++memory, because they are the easiest machines to make it run on. The extra ++effort to make it run on smaller machines will be left to someone who wants ++to use it on them. ++ ++To avoid horrible confusion, please pronounce the `G' in the word `GNU' ++when it is the name of this project. ++ ++@unnumberedsec Why I Must Write GNU ++ ++I consider that the golden rule requires that if I like a program I must ++share it with other people who like it. Software sellers want to divide ++the users and conquer them, making each user agree not to share with ++others. I refuse to break solidarity with other users in this way. I ++cannot in good conscience sign a nondisclosure agreement or a software ++license agreement. For years I worked within the Artificial Intelligence ++Lab to resist such tendencies and other inhospitalities, but eventually ++they had gone too far: I could not remain in an institution where such ++things are done for me against my will. ++ ++So that I can continue to use computers without dishonor, I have decided to ++put together a sufficient body of free software so that I will be able to ++get along without any software that is not free. I have resigned from the ++AI lab to deny MIT any legal excuse to prevent me from giving GNU away. ++ ++@unnumberedsec Why GNU Will Be Compatible with Unix ++ ++Unix is not my ideal system, but it is not too bad. The essential features ++of Unix seem to be good ones, and I think I can fill in what Unix lacks ++without spoiling them. And a system compatible with Unix would be ++convenient for many other people to adopt. ++ ++@unnumberedsec How GNU Will Be Available ++ ++GNU is not in the public domain. Everyone will be permitted to modify and ++redistribute GNU, but no distributor will be allowed to restrict its ++further redistribution. That is to say, proprietary modifications will not ++be allowed. I want to make sure that all versions of GNU remain free. ++ ++@unnumberedsec Why Many Other Programmers Want to Help ++ ++I have found many other programmers who are excited about GNU and want to ++help. ++ ++Many programmers are unhappy about the commercialization of system ++software. It may enable them to make more money, but it requires them to ++feel in conflict with other programmers in general rather than feel as ++comrades. The fundamental act of friendship among programmers is the ++sharing of programs; marketing arrangements now typically used essentially ++forbid programmers to treat others as friends. The purchaser of software ++must choose between friendship and obeying the law. Naturally, many decide ++that friendship is more important. But those who believe in law often do ++not feel at ease with either choice. They become cynical and think that ++programming is just a way of making money. ++ ++By working on and using GNU rather than proprietary programs, we can be ++hospitable to everyone and obey the law. In addition, GNU serves as an ++example to inspire and a banner to rally others to join us in sharing. ++This can give us a feeling of harmony which is impossible if we use ++software that is not free. For about half the programmers I talk to, this ++is an important happiness that money cannot replace. ++ ++@unnumberedsec How You Can Contribute ++ ++I am asking computer manufacturers for donations of machines and money. ++I'm asking individuals for donations of programs and work. ++ ++One consequence you can expect if you donate machines is that GNU will run ++on them at an early date. The machines should be complete, ready to use ++systems, approved for use in a residential area, and not in need of ++sophisticated cooling or power. ++ ++I have found very many programmers eager to contribute part-time work for ++GNU. For most projects, such part-time distributed work would be very hard ++to coordinate; the independently-written parts would not work together. ++But for the particular task of replacing Unix, this problem is absent. A ++complete Unix system contains hundreds of utility programs, each of which ++is documented separately. Most interface specifications are fixed by Unix ++compatibility. If each contributor can write a compatible replacement for ++a single Unix utility, and make it work properly in place of the original ++on a Unix system, then these utilities will work right when put together. ++Even allowing for Murphy to create a few unexpected problems, assembling ++these components will be a feasible task. (The kernel will require closer ++communication and will be worked on by a small, tight group.) ++ ++If I get donations of money, I may be able to hire a few people full or ++part time. The salary won't be high by programmers' standards, but I'm ++looking for people for whom building community spirit is as important as ++making money. I view this as a way of enabling dedicated people to devote ++their full energies to working on GNU by sparing them the need to make a ++living in another way. ++ ++@unnumberedsec Why All Computer Users Will Benefit ++ ++Once GNU is written, everyone will be able to obtain good system ++software free, just like air.@footnote{This is another place I failed to ++distinguish carefully between the two different meanings of ``free.'' ++The statement as it stands is not false---you can get copies of GNU ++software at no charge, from your friends or over the net. But it does ++suggest the wrong idea.} ++ ++This means much more than just saving everyone the price of a Unix license. ++It means that much wasteful duplication of system programming effort will ++be avoided. This effort can go instead into advancing the state of the ++art. ++ ++Complete system sources will be available to everyone. As a result, a user ++who needs changes in the system will always be free to make them himself, ++or hire any available programmer or company to make them for him. Users ++will no longer be at the mercy of one programmer or company which owns the ++sources and is in sole position to make changes. ++ ++Schools will be able to provide a much more educational environment by ++encouraging all students to study and improve the system code. Harvard's ++computer lab used to have the policy that no program could be installed on ++the system if its sources were not on public display, and upheld it by ++actually refusing to install certain programs. I was very much inspired by ++this. ++ ++Finally, the overhead of considering who owns the system software and what ++one is or is not entitled to do with it will be lifted. ++ ++Arrangements to make people pay for using a program, including licensing of ++copies, always incur a tremendous cost to society through the cumbersome ++mechanisms necessary to figure out how much (that is, which programs) a ++person must pay for. And only a police state can force everyone to obey ++them. Consider a space station where air must be manufactured at great ++cost: charging each breather per liter of air may be fair, but wearing the ++metered gas mask all day and all night is intolerable even if everyone can ++afford to pay the air bill. And the TV cameras everywhere to see if you ++ever take the mask off are outrageous. It's better to support the air ++plant with a head tax and chuck the masks. ++ ++Copying all or parts of a program is as natural to a programmer as ++breathing, and as productive. It ought to be as free. ++ ++@unnumberedsec Some Easily Rebutted Objections to GNU's Goals ++ ++@quotation ++``Nobody will use it if it is free, because that means they can't rely ++on any support.'' ++ ++``You have to charge for the program to pay for providing the ++support.'' ++@end quotation ++ ++If people would rather pay for GNU plus service than get GNU free without ++service, a company to provide just service to people who have obtained GNU ++free ought to be profitable.@footnote{Several such companies now exist.} ++ ++We must distinguish between support in the form of real programming work ++and mere handholding. The former is something one cannot rely on from a ++software vendor. If your problem is not shared by enough people, the ++vendor will tell you to get lost. ++ ++If your business needs to be able to rely on support, the only way is to ++have all the necessary sources and tools. Then you can hire any available ++person to fix your problem; you are not at the mercy of any individual. ++With Unix, the price of sources puts this out of consideration for most ++businesses. With GNU this will be easy. It is still possible for there to ++be no available competent person, but this problem cannot be blamed on ++distribution arrangements. GNU does not eliminate all the world's problems, ++only some of them. ++ ++Meanwhile, the users who know nothing about computers need handholding: ++doing things for them which they could easily do themselves but don't know ++how. ++ ++Such services could be provided by companies that sell just hand-holding ++and repair service. If it is true that users would rather spend money and ++get a product with service, they will also be willing to buy the service ++having got the product free. The service companies will compete in quality ++and price; users will not be tied to any particular one. Meanwhile, those ++of us who don't need the service should be able to use the program without ++paying for the service. ++ ++@quotation ++``You cannot reach many people without advertising, ++and you must charge for the program to support that.'' ++ ++``It's no use advertising a program people can get free.'' ++@end quotation ++ ++There are various forms of free or very cheap publicity that can be used to ++inform numbers of computer users about something like GNU. But it may be ++true that one can reach more microcomputer users with advertising. If this ++is really so, a business which advertises the service of copying and ++mailing GNU for a fee ought to be successful enough to pay for its ++advertising and more. This way, only the users who benefit from the ++advertising pay for it. ++ ++On the other hand, if many people get GNU from their friends, and such ++companies don't succeed, this will show that advertising was not really ++necessary to spread GNU. Why is it that free market advocates don't ++want to let the free market decide this?@footnote{The Free Software ++Foundation raises most of its funds from a distribution service, ++although it is a charity rather than a company. If @emph{no one} ++chooses to obtain copies by ordering from the FSF, it will be unable ++to do its work. But this does not mean that proprietary restrictions ++are justified to force every user to pay. If a small fraction of all ++the users order copies from the FSF, that is sufficient to keep the FSF ++afloat. So we ask users to choose to support us in this way. Have you ++done your part?} ++ ++@quotation ++``My company needs a proprietary operating system ++to get a competitive edge.'' ++@end quotation ++ ++GNU will remove operating system software from the realm of competition. ++You will not be able to get an edge in this area, but neither will your ++competitors be able to get an edge over you. You and they will compete in ++other areas, while benefiting mutually in this one. If your business is ++selling an operating system, you will not like GNU, but that's tough on ++you. If your business is something else, GNU can save you from being ++pushed into the expensive business of selling operating systems. ++ ++I would like to see GNU development supported by gifts from many ++manufacturers and users, reducing the cost to each.@footnote{A group of ++computer companies recently pooled funds to support maintenance of the ++GNU C Compiler.} ++ ++@quotation ++``Don't programmers deserve a reward for their creativity?'' ++@end quotation ++ ++If anything deserves a reward, it is social contribution. Creativity can ++be a social contribution, but only in so far as society is free to use the ++results. If programmers deserve to be rewarded for creating innovative ++programs, by the same token they deserve to be punished if they restrict ++the use of these programs. ++ ++@quotation ++``Shouldn't a programmer be able to ask for a reward for his creativity?'' ++@end quotation ++ ++There is nothing wrong with wanting pay for work, or seeking to maximize ++one's income, as long as one does not use means that are destructive. But ++the means customary in the field of software today are based on ++destruction. ++ ++Extracting money from users of a program by restricting their use of it is ++destructive because the restrictions reduce the amount and the ways that ++the program can be used. This reduces the amount of wealth that humanity ++derives from the program. When there is a deliberate choice to restrict, ++the harmful consequences are deliberate destruction. ++ ++The reason a good citizen does not use such destructive means to become ++wealthier is that, if everyone did so, we would all become poorer from the ++mutual destructiveness. This is Kantian ethics; or, the Golden Rule. ++Since I do not like the consequences that result if everyone hoards ++information, I am required to consider it wrong for one to do so. ++Specifically, the desire to be rewarded for one's creativity does not ++justify depriving the world in general of all or part of that creativity. ++ ++@quotation ++``Won't programmers starve?'' ++@end quotation ++ ++I could answer that nobody is forced to be a programmer. Most of us cannot ++manage to get any money for standing on the street and making faces. But ++we are not, as a result, condemned to spend our lives standing on the ++street making faces, and starving. We do something else. ++ ++But that is the wrong answer because it accepts the questioner's implicit ++assumption: that without ownership of software, programmers cannot possibly ++be paid a cent. Supposedly it is all or nothing. ++ ++The real reason programmers will not starve is that it will still be ++possible for them to get paid for programming; just not paid as much as ++now. ++ ++Restricting copying is not the only basis for business in software. It is ++the most common basis because it brings in the most money. If it were ++prohibited, or rejected by the customer, software business would move to ++other bases of organization which are now used less often. There are ++always numerous ways to organize any kind of business. ++ ++Probably programming will not be as lucrative on the new basis as it is ++now. But that is not an argument against the change. It is not considered ++an injustice that sales clerks make the salaries that they now do. If ++programmers made the same, that would not be an injustice either. (In ++practice they would still make considerably more than that.) ++ ++@quotation ++``Don't people have a right to control how their creativity is used?'' ++@end quotation ++ ++``Control over the use of one's ideas'' really constitutes control over ++other people's lives; and it is usually used to make their lives more ++difficult. ++ ++People who have studied the issue of intellectual property ++rights@footnote{In the 80s I had not yet realized how confusing it was ++to speak of ``the issue'' of ``intellectual property.'' That term is ++obviously biased; more subtle is the fact that it lumps together ++various disparate laws which raise very different issues. Nowadays I ++urge people to reject the term ``intellectual property'' entirely, ++lest it lead others to suppose that those laws form one coherent ++issue. The way to be clear is to discuss patents, copyrights, and ++trademarks separately. See ++@uref{http://www.gnu.org/philosophy/not-ipr.xhtml} for more ++explanation of how this term spreads confusion and bias.} carefully ++(such as lawyers) say that there is no intrinsic right to intellectual ++property. The kinds of supposed intellectual property rights that the ++government recognizes were created by specific acts of legislation for ++specific purposes. ++ ++For example, the patent system was established to encourage inventors to ++disclose the details of their inventions. Its purpose was to help society ++rather than to help inventors. At the time, the life span of 17 years for ++a patent was short compared with the rate of advance of the state of the ++art. Since patents are an issue only among manufacturers, for whom the ++cost and effort of a license agreement are small compared with setting up ++production, the patents often do not do much harm. They do not obstruct ++most individuals who use patented products. ++ ++The idea of copyright did not exist in ancient times, when authors ++frequently copied other authors at length in works of non-fiction. This ++practice was useful, and is the only way many authors' works have survived ++even in part. The copyright system was created expressly for the purpose ++of encouraging authorship. In the domain for which it was ++invented---books, which could be copied economically only on a printing ++press---it did little harm, and did not obstruct most of the individuals ++who read the books. ++ ++All intellectual property rights are just licenses granted by society ++because it was thought, rightly or wrongly, that society as a whole would ++benefit by granting them. But in any particular situation, we have to ask: ++are we really better off granting such license? What kind of act are we ++licensing a person to do? ++ ++The case of programs today is very different from that of books a hundred ++years ago. The fact that the easiest way to copy a program is from one ++neighbor to another, the fact that a program has both source code and ++object code which are distinct, and the fact that a program is used rather ++than read and enjoyed, combine to create a situation in which a person who ++enforces a copyright is harming society as a whole both materially and ++spiritually; in which a person should not do so regardless of whether the ++law enables him to. ++ ++@quotation ++``Competition makes things get done better.'' ++@end quotation ++ ++The paradigm of competition is a race: by rewarding the winner, we ++encourage everyone to run faster. When capitalism really works this way, ++it does a good job; but its defenders are wrong in assuming it always works ++this way. If the runners forget why the reward is offered and become ++intent on winning, no matter how, they may find other strategies---such as, ++attacking other runners. If the runners get into a fist fight, they will ++all finish late. ++ ++Proprietary and secret software is the moral equivalent of runners in a ++fist fight. Sad to say, the only referee we've got does not seem to ++object to fights; he just regulates them (``For every ten yards you run, ++you can fire one shot''). He really ought to break them up, and penalize ++runners for even trying to fight. ++ ++@quotation ++``Won't everyone stop programming without a monetary incentive?'' ++@end quotation ++ ++Actually, many people will program with absolutely no monetary incentive. ++Programming has an irresistible fascination for some people, usually the ++people who are best at it. There is no shortage of professional musicians ++who keep at it even though they have no hope of making a living that way. ++ ++But really this question, though commonly asked, is not appropriate to the ++situation. Pay for programmers will not disappear, only become less. So ++the right question is, will anyone program with a reduced monetary ++incentive? My experience shows that they will. ++ ++For more than ten years, many of the world's best programmers worked at the ++Artificial Intelligence Lab for far less money than they could have had ++anywhere else. They got many kinds of non-monetary rewards: fame and ++appreciation, for example. And creativity is also fun, a reward in itself. ++ ++Then most of them left when offered a chance to do the same interesting ++work for a lot of money. ++ ++What the facts show is that people will program for reasons other than ++riches; but if given a chance to make a lot of money as well, they will ++come to expect and demand it. Low-paying organizations do poorly in ++competition with high-paying ones, but they do not have to do badly if the ++high-paying ones are banned. ++ ++@quotation ++``We need the programmers desperately. If they demand that we ++stop helping our neighbors, we have to obey.'' ++@end quotation ++ ++You're never so desperate that you have to obey this sort of demand. ++Remember: millions for defense, but not a cent for tribute! ++ ++@quotation ++``Programmers need to make a living somehow.'' ++@end quotation ++ ++In the short run, this is true. However, there are plenty of ways that ++programmers could make a living without selling the right to use a program. ++This way is customary now because it brings programmers and businessmen the ++most money, not because it is the only way to make a living. It is easy to ++find other ways if you want to find them. Here are a number of examples. ++ ++A manufacturer introducing a new computer will pay for the porting of ++operating systems onto the new hardware. ++ ++The sale of teaching, hand-holding and maintenance services could also ++employ programmers. ++ ++People with new ideas could distribute programs as ++freeware@footnote{Subsequently we have discovered the need to ++distinguish between ``free software'' and ``freeware''. The term ++``freeware'' means software you are free to redistribute, but usually ++you are not free to study and change the source code, so most of it is ++not free software. See ++@uref{http://www.gnu.org/philosophy/words-to-avoid.html} for more ++explanation.}, asking for donations from satisfied users, or selling ++hand-holding services. I have met people who are already working this ++way successfully. ++ ++Users with related needs can form users' groups, and pay dues. A group ++would contract with programming companies to write programs that the ++group's members would like to use. ++ ++All sorts of development can be funded with a Software Tax: ++ ++@quotation ++Suppose everyone who buys a computer has to pay x percent of ++the price as a software tax. The government gives this to ++an agency like the NSF to spend on software development. ++ ++But if the computer buyer makes a donation to software development ++himself, he can take a credit against the tax. He can donate to ++the project of his own choosing---often, chosen because he hopes to ++use the results when it is done. He can take a credit for any amount ++of donation up to the total tax he had to pay. ++ ++The total tax rate could be decided by a vote of the payers of ++the tax, weighted according to the amount they will be taxed on. ++ ++The consequences: ++ ++@itemize @bullet ++@item ++The computer-using community supports software development. ++@item ++This community decides what level of support is needed. ++@item ++Users who care which projects their share is spent on ++can choose this for themselves. ++@end itemize ++@end quotation ++ ++In the long run, making programs free is a step toward the post-scarcity ++world, where nobody will have to work very hard just to make a living. ++People will be free to devote themselves to activities that are fun, such ++as programming, after spending the necessary ten hours a week on required ++tasks such as legislation, family counseling, robot repair and asteroid ++prospecting. There will be no need to be able to make a living from ++programming. ++ ++We have already greatly reduced the amount of work that the whole society ++must do for its actual productivity, but only a little of this has ++translated itself into leisure for workers because much nonproductive ++activity is required to accompany productive activity. The main causes of ++this are bureaucracy and isometric struggles against competition. Free ++software will greatly reduce these drains in the area of software ++production. We must do this, in order for technical gains in productivity ++to translate into less work for us. ++ ++@ignore ++ arch-tag: 21eb38f8-6fa0-480a-91cd-f3dab7148542 ++@end ignore +diff --git a/doc/emacs/gpl.texi b/doc/emacs/gpl.texi +new file mode 100644 +index 0000000..7fe5c3e +--- /dev/null ++++ b/doc/emacs/gpl.texi +@@ -0,0 +1,721 @@ ++@c The GNU General Public License. ++@center Version 3, 29 June 2007 ++ ++@c This file is intended to be included within another document, ++@c hence no sectioning command or @node. ++ ++@display ++Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} ++ ++Everyone is permitted to copy and distribute verbatim copies of this ++license document, but changing it is not allowed. ++@end display ++ ++@heading Preamble ++ ++The GNU General Public License is a free, copyleft license for ++software and other kinds of works. ++ ++The licenses for most software and other practical works are designed ++to take away your freedom to share and change the works. By contrast, ++the GNU General Public License is intended to guarantee your freedom ++to share and change all versions of a program---to make sure it remains ++free software for all its users. We, the Free Software Foundation, ++use the GNU General Public License for most of our software; it ++applies also to any other work released this way by its authors. You ++can apply it to your programs, too. ++ ++When we speak of free software, we are referring to freedom, not ++price. Our General Public Licenses are designed to make sure that you ++have the freedom to distribute copies of free software (and charge for ++them 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. ++ ++To protect your rights, we need to prevent others from denying you ++these rights or asking you to surrender the rights. Therefore, you ++have certain responsibilities if you distribute copies of the ++software, or if you modify it: responsibilities to respect the freedom ++of others. ++ ++For example, if you distribute copies of such a program, whether ++gratis or for a fee, you must pass on to the recipients the same ++freedoms that you received. You must make sure that they, too, ++receive or can get the source code. And you must show them these ++terms so they know their rights. ++ ++Developers that use the GNU GPL protect your rights with two steps: ++(1) assert copyright on the software, and (2) offer you this License ++giving you legal permission to copy, distribute and/or modify it. ++ ++For the developers' and authors' protection, the GPL clearly explains ++that there is no warranty for this free software. For both users' and ++authors' sake, the GPL requires that modified versions be marked as ++changed, so that their problems will not be attributed erroneously to ++authors of previous versions. ++ ++Some devices are designed to deny users access to install or run ++modified versions of the software inside them, although the ++manufacturer can do so. This is fundamentally incompatible with the ++aim of protecting users' freedom to change the software. The ++systematic pattern of such abuse occurs in the area of products for ++individuals to use, which is precisely where it is most unacceptable. ++Therefore, we have designed this version of the GPL to prohibit the ++practice for those products. If such problems arise substantially in ++other domains, we stand ready to extend this provision to those ++domains in future versions of the GPL, as needed to protect the ++freedom of users. ++ ++Finally, every program is threatened constantly by software patents. ++States should not allow patents to restrict development and use of ++software on general-purpose computers, but in those that do, we wish ++to avoid the special danger that patents applied to a free program ++could make it effectively proprietary. To prevent this, the GPL ++assures that patents cannot be used to render the program non-free. ++ ++The precise terms and conditions for copying, distribution and ++modification follow. ++ ++@heading TERMS AND CONDITIONS ++ ++@enumerate 0 ++@item Definitions. ++ ++``This License'' refers to version 3 of the GNU General Public License. ++ ++``Copyright'' also means copyright-like laws that apply to other kinds ++of works, such as semiconductor masks. ++ ++``The Program'' refers to any copyrightable work licensed under this ++License. Each licensee is addressed as ``you''. ``Licensees'' and ++``recipients'' may be individuals or organizations. ++ ++To ``modify'' a work means to copy from or adapt all or part of the work ++in a fashion requiring copyright permission, other than the making of ++an exact copy. The resulting work is called a ``modified version'' of ++the earlier work or a work ``based on'' the earlier work. ++ ++A ``covered work'' means either the unmodified Program or a work based ++on the Program. ++ ++To ``propagate'' a work means to do anything with it that, without ++permission, would make you directly or secondarily liable for ++infringement under applicable copyright law, except executing it on a ++computer or modifying a private copy. Propagation includes copying, ++distribution (with or without modification), making available to the ++public, and in some countries other activities as well. ++ ++To ``convey'' a work means any kind of propagation that enables other ++parties to make or receive copies. Mere interaction with a user ++through a computer network, with no transfer of a copy, is not ++conveying. ++ ++An interactive user interface displays ``Appropriate Legal Notices'' to ++the extent that it includes a convenient and prominently visible ++feature that (1) displays an appropriate copyright notice, and (2) ++tells the user that there is no warranty for the work (except to the ++extent that warranties are provided), that licensees may convey the ++work under this License, and how to view a copy of this License. If ++the interface presents a list of user commands or options, such as a ++menu, a prominent item in the list meets this criterion. ++ ++@item Source Code. ++ ++The ``source code'' for a work means the preferred form of the work for ++making modifications to it. ``Object code'' means any non-source form ++of a work. ++ ++A ``Standard Interface'' means an interface that either is an official ++standard defined by a recognized standards body, or, in the case of ++interfaces specified for a particular programming language, one that ++is widely used among developers working in that language. ++ ++The ``System Libraries'' of an executable work include anything, other ++than the work as a whole, that (a) is included in the normal form of ++packaging a Major Component, but which is not part of that Major ++Component, and (b) serves only to enable use of the work with that ++Major Component, or to implement a Standard Interface for which an ++implementation is available to the public in source code form. A ++``Major Component'', in this context, means a major essential component ++(kernel, window system, and so on) of the specific operating system ++(if any) on which the executable work runs, or a compiler used to ++produce the work, or an object code interpreter used to run it. ++ ++The ``Corresponding Source'' for a work in object code form means all ++the source code needed to generate, install, and (for an executable ++work) run the object code and to modify the work, including scripts to ++control those activities. However, it does not include the work's ++System Libraries, or general-purpose tools or generally available free ++programs which are used unmodified in performing those activities but ++which are not part of the work. For example, Corresponding Source ++includes interface definition files associated with source files for ++the work, and the source code for shared libraries and dynamically ++linked subprograms that the work is specifically designed to require, ++such as by intimate data communication or control flow between those ++subprograms and other parts of the work. ++ ++The Corresponding Source need not include anything that users can ++regenerate automatically from other parts of the Corresponding Source. ++ ++The Corresponding Source for a work in source code form is that same ++work. ++ ++@item Basic Permissions. ++ ++All rights granted under this License are granted for the term of ++copyright on the Program, and are irrevocable provided the stated ++conditions are met. This License explicitly affirms your unlimited ++permission to run the unmodified Program. The output from running a ++covered work is covered by this License only if the output, given its ++content, constitutes a covered work. This License acknowledges your ++rights of fair use or other equivalent, as provided by copyright law. ++ ++You may make, run and propagate covered works that you do not convey, ++without conditions so long as your license otherwise remains in force. ++You may convey covered works to others for the sole purpose of having ++them make modifications exclusively for you, or provide you with ++facilities for running those works, provided that you comply with the ++terms of this License in conveying all material for which you do not ++control copyright. Those thus making or running the covered works for ++you must do so exclusively on your behalf, under your direction and ++control, on terms that prohibit them from making any copies of your ++copyrighted material outside their relationship with you. ++ ++Conveying under any other circumstances is permitted solely under the ++conditions stated below. Sublicensing is not allowed; section 10 ++makes it unnecessary. ++ ++@item Protecting Users' Legal Rights From Anti-Circumvention Law. ++ ++No covered work shall be deemed part of an effective technological ++measure under any applicable law fulfilling obligations under article ++11 of the WIPO copyright treaty adopted on 20 December 1996, or ++similar laws prohibiting or restricting circumvention of such ++measures. ++ ++When you convey a covered work, you waive any legal power to forbid ++circumvention of technological measures to the extent such ++circumvention is effected by exercising rights under this License with ++respect to the covered work, and you disclaim any intention to limit ++operation or modification of the work as a means of enforcing, against ++the work's users, your or third parties' legal rights to forbid ++circumvention of technological measures. ++ ++@item Conveying Verbatim Copies. ++ ++You may convey verbatim copies of the Program's source code as you ++receive it, in any medium, provided that you conspicuously and ++appropriately publish on each copy an appropriate copyright notice; ++keep intact all notices stating that this License and any ++non-permissive terms added in accord with section 7 apply to the code; ++keep intact all notices of the absence of any warranty; and give all ++recipients a copy of this License along with the Program. ++ ++You may charge any price or no price for each copy that you convey, ++and you may offer support or warranty protection for a fee. ++ ++@item Conveying Modified Source Versions. ++ ++You may convey a work based on the Program, or the modifications to ++produce it from the Program, in the form of source code under the ++terms of section 4, provided that you also meet all of these ++conditions: ++ ++@enumerate a ++@item ++The work must carry prominent notices stating that you modified it, ++and giving a relevant date. ++ ++@item ++The work must carry prominent notices stating that it is released ++under this License and any conditions added under section 7. This ++requirement modifies the requirement in section 4 to ``keep intact all ++notices''. ++ ++@item ++You must license the entire work, as a whole, under this License to ++anyone who comes into possession of a copy. This License will ++therefore apply, along with any applicable section 7 additional terms, ++to the whole of the work, and all its parts, regardless of how they ++are packaged. This License gives no permission to license the work in ++any other way, but it does not invalidate such permission if you have ++separately received it. ++ ++@item ++If the work has interactive user interfaces, each must display ++Appropriate Legal Notices; however, if the Program has interactive ++interfaces that do not display Appropriate Legal Notices, your work ++need not make them do so. ++@end enumerate ++ ++A compilation of a covered work with other separate and independent ++works, which are not by their nature extensions of the covered work, ++and which are not combined with it such as to form a larger program, ++in or on a volume of a storage or distribution medium, is called an ++``aggregate'' if the compilation and its resulting copyright are not ++used to limit the access or legal rights of the compilation's users ++beyond what the individual works permit. Inclusion of a covered work ++in an aggregate does not cause this License to apply to the other ++parts of the aggregate. ++ ++@item Conveying Non-Source Forms. ++ ++You may convey a covered work in object code form under the terms of ++sections 4 and 5, provided that you also convey the machine-readable ++Corresponding Source under the terms of this License, in one of these ++ways: ++ ++@enumerate a ++@item ++Convey the object code in, or embodied in, a physical product ++(including a physical distribution medium), accompanied by the ++Corresponding Source fixed on a durable physical medium customarily ++used for software interchange. ++ ++@item ++Convey the object code in, or embodied in, a physical product ++(including a physical distribution medium), accompanied by a written ++offer, valid for at least three years and valid for as long as you ++offer spare parts or customer support for that product model, to give ++anyone who possesses the object code either (1) a copy of the ++Corresponding Source for all the software in the product that is ++covered by this License, on a durable physical medium customarily used ++for software interchange, for a price no more than your reasonable ++cost of physically performing this conveying of source, or (2) access ++to copy the Corresponding Source from a network server at no charge. ++ ++@item ++Convey individual copies of the object code with a copy of the written ++offer to provide the Corresponding Source. This alternative is ++allowed only occasionally and noncommercially, and only if you ++received the object code with such an offer, in accord with subsection ++6b. ++ ++@item ++Convey the object code by offering access from a designated place ++(gratis or for a charge), and offer equivalent access to the ++Corresponding Source in the same way through the same place at no ++further charge. You need not require recipients to copy the ++Corresponding Source along with the object code. If the place to copy ++the object code is a network server, the Corresponding Source may be ++on a different server (operated by you or a third party) that supports ++equivalent copying facilities, provided you maintain clear directions ++next to the object code saying where to find the Corresponding Source. ++Regardless of what server hosts the Corresponding Source, you remain ++obligated to ensure that it is available for as long as needed to ++satisfy these requirements. ++ ++@item ++Convey the object code using peer-to-peer transmission, provided you ++inform other peers where the object code and Corresponding Source of ++the work are being offered to the general public at no charge under ++subsection 6d. ++ ++@end enumerate ++ ++A separable portion of the object code, whose source code is excluded ++from the Corresponding Source as a System Library, need not be ++included in conveying the object code work. ++ ++A ``User Product'' is either (1) a ``consumer product'', which means any ++tangible personal property which is normally used for personal, ++family, or household purposes, or (2) anything designed or sold for ++incorporation into a dwelling. In determining whether a product is a ++consumer product, doubtful cases shall be resolved in favor of ++coverage. For a particular product received by a particular user, ++``normally used'' refers to a typical or common use of that class of ++product, regardless of the status of the particular user or of the way ++in which the particular user actually uses, or expects or is expected ++to use, the product. A product is a consumer product regardless of ++whether the product has substantial commercial, industrial or ++non-consumer uses, unless such uses represent the only significant ++mode of use of the product. ++ ++``Installation Information'' for a User Product means any methods, ++procedures, authorization keys, or other information required to ++install and execute modified versions of a covered work in that User ++Product from a modified version of its Corresponding Source. The ++information must suffice to ensure that the continued functioning of ++the modified object code is in no case prevented or interfered with ++solely because modification has been made. ++ ++If you convey an object code work under this section in, or with, or ++specifically for use in, a User Product, and the conveying occurs as ++part of a transaction in which the right of possession and use of the ++User Product is transferred to the recipient in perpetuity or for a ++fixed term (regardless of how the transaction is characterized), the ++Corresponding Source conveyed under this section must be accompanied ++by the Installation Information. But this requirement does not apply ++if neither you nor any third party retains the ability to install ++modified object code on the User Product (for example, the work has ++been installed in ROM). ++ ++The requirement to provide Installation Information does not include a ++requirement to continue to provide support service, warranty, or ++updates for a work that has been modified or installed by the ++recipient, or for the User Product in which it has been modified or ++installed. Access to a network may be denied when the modification ++itself materially and adversely affects the operation of the network ++or violates the rules and protocols for communication across the ++network. ++ ++Corresponding Source conveyed, and Installation Information provided, ++in accord with this section must be in a format that is publicly ++documented (and with an implementation available to the public in ++source code form), and must require no special password or key for ++unpacking, reading or copying. ++ ++@item Additional Terms. ++ ++``Additional permissions'' are terms that supplement the terms of this ++License by making exceptions from one or more of its conditions. ++Additional permissions that are applicable to the entire Program shall ++be treated as though they were included in this License, to the extent ++that they are valid under applicable law. If additional permissions ++apply only to part of the Program, that part may be used separately ++under those permissions, but the entire Program remains governed by ++this License without regard to the additional permissions. ++ ++When you convey a copy of a covered work, you may at your option ++remove any additional permissions from that copy, or from any part of ++it. (Additional permissions may be written to require their own ++removal in certain cases when you modify the work.) You may place ++additional permissions on material, added by you to a covered work, ++for which you have or can give appropriate copyright permission. ++ ++Notwithstanding any other provision of this License, for material you ++add to a covered work, you may (if authorized by the copyright holders ++of that material) supplement the terms of this License with terms: ++ ++@enumerate a ++@item ++Disclaiming warranty or limiting liability differently from the terms ++of sections 15 and 16 of this License; or ++ ++@item ++Requiring preservation of specified reasonable legal notices or author ++attributions in that material or in the Appropriate Legal Notices ++displayed by works containing it; or ++ ++@item ++Prohibiting misrepresentation of the origin of that material, or ++requiring that modified versions of such material be marked in ++reasonable ways as different from the original version; or ++ ++@item ++Limiting the use for publicity purposes of names of licensors or ++authors of the material; or ++ ++@item ++Declining to grant rights under trademark law for use of some trade ++names, trademarks, or service marks; or ++ ++@item ++Requiring indemnification of licensors and authors of that material by ++anyone who conveys the material (or modified versions of it) with ++contractual assumptions of liability to the recipient, for any ++liability that these contractual assumptions directly impose on those ++licensors and authors. ++@end enumerate ++ ++All other non-permissive additional terms are considered ``further ++restrictions'' within the meaning of section 10. If the Program as you ++received it, or any part of it, contains a notice stating that it is ++governed by this License along with a term that is a further ++restriction, you may remove that term. If a license document contains ++a further restriction but permits relicensing or conveying under this ++License, you may add to a covered work material governed by the terms ++of that license document, provided that the further restriction does ++not survive such relicensing or conveying. ++ ++If you add terms to a covered work in accord with this section, you ++must place, in the relevant source files, a statement of the ++additional terms that apply to those files, or a notice indicating ++where to find the applicable terms. ++ ++Additional terms, permissive or non-permissive, may be stated in the ++form of a separately written license, or stated as exceptions; the ++above requirements apply either way. ++ ++@item Termination. ++ ++You may not propagate or modify a covered work except as expressly ++provided under this License. Any attempt otherwise to propagate or ++modify it is void, and will automatically terminate your rights under ++this License (including any patent licenses granted under the third ++paragraph of section 11). ++ ++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, you do not qualify to receive new licenses for the same ++material under section 10. ++ ++@item Acceptance Not Required for Having Copies. ++ ++You are not required to accept this License in order to receive or run ++a copy of the Program. Ancillary propagation of a covered work ++occurring solely as a consequence of using peer-to-peer transmission ++to receive a copy likewise does not require acceptance. However, ++nothing other than this License grants you permission to propagate or ++modify any covered work. These actions infringe copyright if you do ++not accept this License. Therefore, by modifying or propagating a ++covered work, you indicate your acceptance of this License to do so. ++ ++@item Automatic Licensing of Downstream Recipients. ++ ++Each time you convey a covered work, the recipient automatically ++receives a license from the original licensors, to run, modify and ++propagate that work, subject to this License. You are not responsible ++for enforcing compliance by third parties with this License. ++ ++An ``entity transaction'' is a transaction transferring control of an ++organization, or substantially all assets of one, or subdividing an ++organization, or merging organizations. If propagation of a covered ++work results from an entity transaction, each party to that ++transaction who receives a copy of the work also receives whatever ++licenses to the work the party's predecessor in interest had or could ++give under the previous paragraph, plus a right to possession of the ++Corresponding Source of the work from the predecessor in interest, if ++the predecessor has it or can get it with reasonable efforts. ++ ++You may not impose any further restrictions on the exercise of the ++rights granted or affirmed under this License. For example, you may ++not impose a license fee, royalty, or other charge for exercise of ++rights granted under this License, and you may not initiate litigation ++(including a cross-claim or counterclaim in a lawsuit) alleging that ++any patent claim is infringed by making, using, selling, offering for ++sale, or importing the Program or any portion of it. ++ ++@item Patents. ++ ++A ``contributor'' is a copyright holder who authorizes use under this ++License of the Program or a work on which the Program is based. The ++work thus licensed is called the contributor's ``contributor version''. ++ ++A contributor's ``essential patent claims'' are all patent claims owned ++or controlled by the contributor, whether already acquired or ++hereafter acquired, that would be infringed by some manner, permitted ++by this License, of making, using, or selling its contributor version, ++but do not include claims that would be infringed only as a ++consequence of further modification of the contributor version. For ++purposes of this definition, ``control'' includes the right to grant ++patent sublicenses in a manner consistent with the requirements of ++this License. ++ ++Each contributor grants you a non-exclusive, worldwide, royalty-free ++patent license under the contributor's essential patent claims, to ++make, use, sell, offer for sale, import and otherwise run, modify and ++propagate the contents of its contributor version. ++ ++In the following three paragraphs, a ``patent license'' is any express ++agreement or commitment, however denominated, not to enforce a patent ++(such as an express permission to practice a patent or covenant not to ++sue for patent infringement). To ``grant'' such a patent license to a ++party means to make such an agreement or commitment not to enforce a ++patent against the party. ++ ++If you convey a covered work, knowingly relying on a patent license, ++and the Corresponding Source of the work is not available for anyone ++to copy, free of charge and under the terms of this License, through a ++publicly available network server or other readily accessible means, ++then you must either (1) cause the Corresponding Source to be so ++available, or (2) arrange to deprive yourself of the benefit of the ++patent license for this particular work, or (3) arrange, in a manner ++consistent with the requirements of this License, to extend the patent ++license to downstream recipients. ``Knowingly relying'' means you have ++actual knowledge that, but for the patent license, your conveying the ++covered work in a country, or your recipient's use of the covered work ++in a country, would infringe one or more identifiable patents in that ++country that you have reason to believe are valid. ++ ++If, pursuant to or in connection with a single transaction or ++arrangement, you convey, or propagate by procuring conveyance of, a ++covered work, and grant a patent license to some of the parties ++receiving the covered work authorizing them to use, propagate, modify ++or convey a specific copy of the covered work, then the patent license ++you grant is automatically extended to all recipients of the covered ++work and works based on it. ++ ++A patent license is ``discriminatory'' if it does not include within the ++scope of its coverage, prohibits the exercise of, or is conditioned on ++the non-exercise of one or more of the rights that are specifically ++granted under this License. You may not convey a covered work if you ++are a party to an arrangement with a third party that is in the ++business of distributing software, under which you make payment to the ++third party based on the extent of your activity of conveying the ++work, and under which the third party grants, to any of the parties ++who would receive the covered work from you, a discriminatory patent ++license (a) in connection with copies of the covered work conveyed by ++you (or copies made from those copies), or (b) primarily for and in ++connection with specific products or compilations that contain the ++covered work, unless you entered into that arrangement, or that patent ++license was granted, prior to 28 March 2007. ++ ++Nothing in this License shall be construed as excluding or limiting ++any implied license or other defenses to infringement that may ++otherwise be available to you under applicable patent law. ++ ++@item No Surrender of Others' Freedom. ++ ++If conditions are imposed on you (whether by court order, agreement or ++otherwise) that contradict the conditions of this License, they do not ++excuse you from the conditions of this License. If you cannot convey ++a covered work so as to satisfy simultaneously your obligations under ++this License and any other pertinent obligations, then as a ++consequence you may not convey it at all. For example, if you agree ++to terms that obligate you to collect a royalty for further conveying ++from those to whom you convey the Program, the only way you could ++satisfy both those terms and this License would be to refrain entirely ++from conveying the Program. ++ ++@item Use with the GNU Affero General Public License. ++ ++Notwithstanding any other provision of this License, you have ++permission to link or combine any covered work with a work licensed ++under version 3 of the GNU Affero General Public License into a single ++combined work, and to convey the resulting work. The terms of this ++License will continue to apply to the part which is the covered work, ++but the special requirements of the GNU Affero General Public License, ++section 13, concerning interaction through a network will apply to the ++combination as such. ++ ++@item Revised Versions of this License. ++ ++The Free Software Foundation may publish revised and/or new versions ++of the GNU General Public 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. ++ ++Each version is given a distinguishing version number. If the Program ++specifies that a certain numbered version of the GNU General Public ++License ``or any later version'' applies to it, you have the option of ++following the terms and conditions either of that numbered version or ++of any later version published by the Free Software Foundation. If ++the Program does not specify a version number of the GNU General ++Public License, you may choose any version ever published by the Free ++Software Foundation. ++ ++If the Program specifies that a proxy can decide which future versions ++of the GNU General Public License can be used, that proxy's public ++statement of acceptance of a version permanently authorizes you to ++choose that version for the Program. ++ ++Later license versions may give you additional or different ++permissions. However, no additional obligations are imposed on any ++author or copyright holder as a result of your choosing to follow a ++later version. ++ ++@item Disclaimer of Warranty. ++ ++THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY ++APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT ++HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT ++WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT ++LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ++A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND ++PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE ++DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR ++CORRECTION. ++ ++@item Limitation of Liability. ++ ++IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING ++WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR ++CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, ++INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ++ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT ++NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR ++LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM ++TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER ++PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. ++ ++@item Interpretation of Sections 15 and 16. ++ ++If the disclaimer of warranty and limitation of liability provided ++above cannot be given local legal effect according to their terms, ++reviewing courts shall apply local law that most closely approximates ++an absolute waiver of all civil liability in connection with the ++Program, unless a warranty or assumption of liability accompanies a ++copy of the Program in return for a fee. ++ ++@end enumerate ++ ++@heading END OF TERMS AND CONDITIONS ++ ++@heading How to Apply These Terms to Your New Programs ++ ++If you develop a new program, and you want it to be of the greatest ++possible use to the public, the best way to achieve this is to make it ++free software which everyone can redistribute and change under these ++terms. ++ ++To do so, attach the following notices to the program. It is safest ++to attach them to the start of each source file to most effectively ++state the exclusion of warranty; and each file should have at least ++the ``copyright'' line and a pointer to where the full notice is found. ++ ++@smallexample ++@var{one line to give the program's name and a brief idea of what it does.} ++Copyright (C) @var{year} @var{name of author} ++ ++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 @url{http://www.gnu.org/licenses/}. ++@end smallexample ++ ++Also add information on how to contact you by electronic and paper mail. ++ ++If the program does terminal interaction, make it output a short ++notice like this when it starts in an interactive mode: ++ ++@smallexample ++@var{program} Copyright (C) @var{year} @var{name of author} ++This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. ++This is free software, and you are welcome to redistribute it ++under certain conditions; type @samp{show c} for details. ++@end smallexample ++ ++The hypothetical commands @samp{show w} and @samp{show c} should show ++the appropriate parts of the General Public License. Of course, your ++program's commands might be different; for a GUI interface, you would ++use an ``about box''. ++ ++You should also get your employer (if you work as a programmer) or school, ++if any, to sign a ``copyright disclaimer'' for the program, if necessary. ++For more information on this, and how to apply and follow the GNU GPL, see ++@url{http://www.gnu.org/licenses/}. ++ ++The GNU General Public License does not permit incorporating your ++program into proprietary programs. If your program is a subroutine ++library, you may consider it more useful to permit linking proprietary ++applications with the library. If this is what you want to do, use ++the GNU Lesser General Public License instead of this License. But ++first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. ++ ++@ignore ++ arch-tag: 8b9947e1-c830-4d70-8907-a97e556731ba ++@end ignore +diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi +new file mode 100644 +index 0000000..061b4cd +--- /dev/null ++++ b/doc/emacs/help.texi +@@ -0,0 +1,680 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Help, Mark, M-x, Top ++@chapter Help ++@kindex Help ++@cindex help ++@cindex self-documentation ++@findex help-command ++@kindex C-h ++@kindex F1 ++ ++ Emacs provides extensive help features, all accessible through the ++@dfn{help character}, @kbd{C-h}. This is a prefix key that is used ++for commands that display documentation; the next character you type ++should be a @dfn{help option}, to ask for a particular kind of help. ++You can cancel the @kbd{C-h} command with @kbd{C-g}. The function key ++@key{F1} is equivalent to @kbd{C-h}. ++ ++@kindex C-h C-h ++@findex help-for-help ++ @kbd{C-h} itself is one of the help options; @kbd{C-h C-h} displays ++a list of help options, with a brief description of each one ++(@code{help-for-help}). You can scroll the list with @key{SPC} and ++@key{DEL}, then type the help option you want. To cancel, type ++@kbd{C-g}. ++ ++ @kbd{C-h} or @key{F1} means ``help'' in various other contexts as ++well. For instance, you can type them after a prefix key to display ++a list of the keys that can follow the prefix key. (A few prefix keys ++don't support @kbd{C-h} in this way, because they define other ++meanings for it, but they all support @key{F1} for help.) ++ ++ Most help buffers use a special major mode, Help mode, which lets ++you scroll conveniently with @key{SPC} and @key{DEL}. You can also ++follow hyperlinks to URLs, and to other facilities including Info ++nodes and customization buffers. @xref{Help Mode}. ++ ++@cindex searching documentation efficiently ++@cindex looking for a subject in documentation ++ If you are looking for a certain feature, but don't know what it is ++called or where to look, we recommend three methods. First, try an ++apropos command, then try searching the manual index, then look in the ++FAQ and the package keywords. ++ ++@table @kbd ++@item C-h a @var{topics} @key{RET} ++This searches for commands whose names match the argument ++@var{topics}. The argument can be a keyword, a list of keywords, or a ++regular expression (@pxref{Regexps}). @xref{Apropos}. ++ ++@item C-h i d m emacs @key{RET} i @var{topic} @key{RET} ++This searches for @var{topic} in the indices of the on-line Emacs ++manual, and displays the first match found. Press @kbd{,} to see ++subsequent matches. You can use a regular expression as @var{topic}. ++ ++@item C-h i d m emacs @key{RET} s @var{topic} @key{RET} ++Similar, but searches the @emph{text} of the manual rather than the ++indices. ++ ++@item C-h C-f ++This displays the Emacs FAQ. You can use the Info commands ++to browse it. ++ ++@item C-h p ++This displays the available Emacs packages based on keywords. ++@xref{Library Keywords}. ++@end table ++ ++@menu ++* Help Summary:: Brief list of all Help commands. ++* Key Help:: Asking what a key does in Emacs. ++* Name Help:: Asking about a command, variable or function name. ++* Apropos:: Asking what pertains to a given topic. ++* Help Mode:: Special features of Help mode and Help buffers. ++* Library Keywords:: Finding Lisp libraries by keywords (topics). ++* Language Help:: Help relating to international language support. ++* Misc Help:: Other help commands. ++* Help Files:: Commands to display pre-written help files. ++* Help Echo:: Help on active text and tooltips (`balloon help'). ++@end menu ++ ++@iftex ++@node Help Summary ++@end iftex ++@ifnottex ++@node Help Summary ++@section Help Summary ++@end ifnottex ++ ++ Here is a summary of the Emacs interactive help commands. (The ++character that follows @kbd{C-h} is the ``help option.'') See ++@ref{Help Files}, for other help commands that display fixed files ++of information. ++ ++@table @kbd ++@item C-h a @var{topics} @key{RET} ++Display a list of commands whose names match @var{topics} ++(@code{apropos-command}; @pxref{Apropos}). ++@item C-h b ++Display all active key bindings; minor mode bindings first, then those ++of the major mode, then global bindings (@code{describe-bindings}). ++@item C-h c @var{key} ++Given a key sequence @var{key}, show the name of the command that it ++runs (@code{describe-key-briefly}). Here @kbd{c} stands for ++``character.'' For more extensive information on @var{key}, use ++@kbd{C-h k}. ++@item C-h d @var{topics} @key{RET} ++Display the commands and variables whose documentation matches ++@var{topics} (@code{apropos-documentation}). ++@item C-h e ++Display the @code{*Messages*} buffer ++(@code{view-echo-area-messages}). ++@item C-h f @var{function} @key{RET} ++Display documentation on the Lisp function named @var{function} ++(@code{describe-function}). Since commands are Lisp functions, ++this works for commands too. ++@item C-h h ++Display the @file{HELLO} file, which shows examples of various character ++sets. ++@item C-h i ++Run Info, the GNU documentation browser (@code{info}). ++The complete Emacs manual is available on-line in Info. ++@item C-h k @var{key} ++Display the name and documentation of the command that @var{key} runs ++(@code{describe-key}). ++@item C-h l ++Display a description of your last 300 keystrokes ++(@code{view-lossage}). ++@item C-h m ++Display documentation of the current major mode (@code{describe-mode}). ++@item C-h n ++Display news of recent Emacs changes (@code{view-emacs-news}). ++@item C-h p ++Find packages by topic keyword (@code{finder-by-keyword}). ++@item C-h r ++Display the Emacs manual in Info (@code{info-emacs-manual}). ++@item C-h s ++Display the current contents of the syntax table, with an explanation of ++what they mean (@code{describe-syntax}). @xref{Syntax}. ++@item C-h t ++Enter the Emacs interactive tutorial (@code{help-with-tutorial}). ++@item C-h v @var{var} @key{RET} ++Display the documentation of the Lisp variable @var{var} ++(@code{describe-variable}). ++@item C-h w @var{command} @key{RET} ++Show which keys run the command named @var{command} (@code{where-is}). ++@item C-h C @var{coding} @key{RET} ++Describe the coding system @var{coding} ++(@code{describe-coding-system}). ++@item C-h C @key{RET} ++Describe the coding systems currently in use. ++@item C-h F @var{command} @key{RET} ++Enter Info and go to the node that documents the Emacs command ++@var{command} (@code{Info-goto-emacs-command-node}). ++@item C-h I @var{method} @key{RET} ++Describe the input method @var{method} (@code{describe-input-method}). ++@item C-h K @var{key} ++Enter Info and go to the node that documents the key sequence ++@var{key} (@code{Info-goto-emacs-key-command-node}). ++@item C-h L @var{language-env} @key{RET} ++Display information on the character sets, coding systems, and input ++methods used in language environment @var{language-env} ++(@code{describe-language-environment}). ++@item C-h S @var{symbol} @key{RET} ++Display the Info documentation on symbol @var{symbol} according to the ++programming language you are editing (@code{info-lookup-symbol}). ++@item C-h . ++Display the help message for a special text area, if point is in one ++(@code{display-local-help}). (These include, for example, links in ++@samp{*Help*} buffers.) ++@end table ++ ++@node Key Help ++@section Documentation for a Key ++ ++@kindex C-h c ++@findex describe-key-briefly ++ The help commands to get information about a key sequence are ++@kbd{C-h c} and @w{@kbd{C-h k}}. @kbd{C-h c @var{key}} displays in ++the echo area the name of the command that @var{key} is bound to. For ++example, @kbd{C-h c C-f} displays @samp{forward-char}. Since command ++names are chosen to describe what the commands do, this gives you a ++very brief description of what @var{key} does. ++ ++@kindex C-h k ++@findex describe-key ++ @kbd{C-h k @var{key}} is similar but gives more information: it ++displays the documentation string of the command as well as its name. ++It displays this information in a window, since it may not fit in the ++echo area. ++ ++@kindex C-h K ++@findex Info-goto-emacs-key-command-node ++ To find the documentation of a key sequence @var{key}, type @kbd{C-h ++K @var{key}}. This displays the appropriate manual section which ++contains the documentation of @var{key}. ++ ++ @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key ++sequences, including function keys, menus, and mouse events. For ++instance, after @kbd{C-h k} you can select a menu item from the menu ++bar, to view the documentation string of the command it runs. ++ ++@kindex C-h w ++@findex where-is ++ @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to ++@var{command}. It displays the list in the echo area. If it says the ++command is not on any key, that means you must use @kbd{M-x} to run ++it. @kbd{C-h w} runs the command @code{where-is}. ++ ++@node Name Help ++@section Help by Command or Variable Name ++ ++@kindex C-h f ++@findex describe-function ++ @kbd{C-h f @var{function} @key{RET}} (@code{describe-function}) ++displays the documentation of Lisp function @var{function}, in a ++window. Since commands are Lisp functions, you can use this method to ++view the documentation of any command whose name you know. For ++example, ++ ++@example ++C-h f auto-fill-mode @key{RET} ++@end example ++ ++@noindent ++displays the documentation of @code{auto-fill-mode}. This is the only ++way to get the documentation of a command that is not bound to any key ++(one which you would normally run using @kbd{M-x}). ++ ++ @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp ++program. For example, if you have just written the expression ++@code{(make-vector len)} and want to check that you are using ++@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. ++Because @kbd{C-h f} allows all function names, not just command names, ++you may find that some of your favorite completion abbreviations that ++work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is ++unique among command names may not be unique among all function names. ++ ++ If you type @kbd{C-h f @key{RET}}, it describes the function called ++by the innermost Lisp expression in the buffer around point, ++@emph{provided} that function name is a valid, defined Lisp function. ++(That name appears as the default while you enter the argument.) For ++example, if point is located following the text @samp{(make-vector ++(car x)}, the innermost list containing point is the one that starts ++with @samp{(make-vector}, so @kbd{C-h f @key{RET}} will describe the ++function @code{make-vector}. ++ ++ @kbd{C-h f} is also useful just to verify that you spelled a ++function name correctly. If the minibuffer prompt for @kbd{C-h f} ++shows the function name from the buffer as the default, it means that ++name is defined as a Lisp function. Type @kbd{C-g} to cancel the ++@kbd{C-h f} command if you don't really want to view the ++documentation. ++ ++@kindex C-h v ++@findex describe-variable ++ @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but ++describes Lisp variables instead of Lisp functions. Its default is ++the Lisp symbol around or before point, if that is the name of a ++defined Lisp variable. @xref{Variables}. ++ ++ Help buffers that describe Emacs variables and functions normally ++have hyperlinks to the corresponding source definition, if you have ++the source files installed. (@xref{Hyperlinking}.) If you know Lisp ++(or C), this provides the ultimate documentation. If you don't know ++Lisp, you should learn it. (The Introduction to Emacs Lisp ++Programming, available from the FSF through fsf.org, is a good way to ++get started.) If Emacs feels you are just @emph{using} it, treating ++it as an object program, its feelings may be hurt. For real intimacy, ++read the Emacs source code. ++ ++@kindex C-h F ++@findex Info-goto-emacs-command-node ++ To find a command's documentation in a manual, use @kbd{C-h F} ++(@code{Info-goto-emacs-command-node}). This knows about various ++manuals, not just the Emacs manual, and finds the right one. ++ ++@node Apropos ++@section Apropos ++ ++ The @dfn{apropos} commands answer questions like, ``What are the ++commands for working with files?'' More precisely, you specify an ++@dfn{apropos pattern}, which means either a word, a list of words, or ++a regular expression. Each apropos command displays a list of items ++that match the pattern, in a separate buffer. ++ ++@table @kbd ++@item C-h a @var{pattern} @key{RET} ++Search for commands whose names match @var{pattern}. ++ ++@item M-x apropos @key{RET} @var{pattern} @key{RET} ++Search for functions and variables whose names match @var{pattern}. ++Both interactive functions (commands) and noninteractive functions can ++be found by this command. ++ ++@item M-x apropos-variable @key{RET} @var{pattern} @key{RET} ++Search for user-option variables whose names match @var{pattern}. ++ ++@item M-x apropos-value @key{RET} @var{pattern} @key{RET} ++Search for functions whose definitions match @var{pattern}, and ++variables whose values match @var{pattern}. ++ ++@item C-h d @var{pattern} @key{RET} ++Search for functions and variables whose @strong{documentation ++strings} match @var{pattern}. ++@end table ++ ++@kindex C-h a ++@findex apropos-command ++@cindex apropos ++ The simplest kind of apropos pattern is one word. Anything which ++contains that word matches the pattern. Thus, to find the commands ++that work on files, type @kbd{C-h a file @key{RET}}. This displays a ++list of all command names that contain @samp{file}, including ++@code{copy-file}, @code{find-file}, and so on. Each command name ++comes with a brief description and a list of keys you can currently ++invoke it with. In our example, it would say that you can invoke ++@code{find-file} by typing @kbd{C-x C-f}. ++ ++ The @kbd{a} in @kbd{C-h a} stands for ``Apropos''; @kbd{C-h a} ++runs the command @code{apropos-command}. This command normally checks ++only commands (interactive functions); if you specify a prefix ++argument, it checks noninteractive functions as well. ++ ++ For more information about a function definition, variable or symbol ++property listed in the apropos buffer, you can click on it with ++@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}. ++ ++ When you specify more than one word in the apropos pattern, a name ++must contain at least two of the words in order to match. Thus, if ++you are looking for commands to kill a chunk of text before point, you ++could try @kbd{C-h a kill back backward behind before @key{RET}}. The ++real command name @code{kill-backward} will match that; if there were ++a command @code{kill-text-before}, it would also match, since it ++contains two of the specified words. ++ ++ For even greater flexibility, you can specify a regular expression ++(@pxref{Regexps}). An apropos pattern is interpreted as a regular ++expression if it contains any of the regular expression special ++characters, @samp{^$*+?.\[}. ++ ++ Following the conventions for naming Emacs commands, here are some ++words that you'll find useful in apropos patterns. By using them in ++@kbd{C-h a}, you will also get a feel for the naming conventions. ++ ++@quotation ++char, line, word, sentence, paragraph, region, page, sexp, list, defun, ++rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, ++forward, backward, next, previous, up, down, search, goto, kill, delete, ++mark, insert, yank, fill, indent, case, change, set, what, list, find, ++view, describe, default. ++@end quotation ++ ++@findex apropos ++ Use @kbd{M-x apropos} instead of @kbd{C-h a} to list all the Lisp ++symbols that match an apropos pattern, not just the symbols that are ++commands. This command does not list key bindings by default; specify ++a numeric argument if you want it to list them. ++ ++@findex apropos-variable ++ Use @kbd{M-x apropos-variable} to list user-customizable variables ++that match an apropos pattern. If you specify a prefix argument, it ++lists all matching variables. ++ ++@kindex C-h d ++@findex apropos-documentation ++ The @code{apropos-documentation} command is like @code{apropos} ++except that it searches documentation strings instead of symbol names ++for matches. ++ ++@findex apropos-value ++ The @code{apropos-value} command is like @code{apropos} except that ++it searches variables' values for matches for the apropos pattern. ++With a prefix argument, it also checks symbols' function definitions ++and property lists. ++ ++@vindex apropos-do-all ++ If the variable @code{apropos-do-all} is non-@code{nil}, the apropos ++commands always behave as if they had been given a prefix argument. ++ ++@vindex apropos-sort-by-scores ++@cindex apropos search results, order by score ++ By default, apropos lists the search results in alphabetical order. ++If the variable @code{apropos-sort-by-scores} is non-@code{nil}, the ++apropos commands try to guess the relevance of each result, and ++display the most relevant ones first. ++ ++@vindex apropos-documentation-sort-by-scores ++ By default, apropos lists the search results for ++@code{apropos-documentation} in order of relevance of the match. If ++the variable @code{apropos-documentation-sort-by-scores} is ++@code{nil}, apropos lists the symbols found in alphabetical order. ++ ++@node Help Mode ++@section Help Mode Commands ++ ++ Help buffers provide the same commands as View mode (@pxref{Misc File ++Ops}), plus a few special commands of their own. ++ ++@table @kbd ++@item @key{SPC} ++Scroll forward. ++@item @key{DEL} ++Scroll backward. ++@item @key{RET} ++Follow a cross reference at point. ++@item @key{TAB} ++Move point forward to the next cross reference. ++@item S-@key{TAB} ++Move point back to the previous cross reference. ++@item Mouse-1 ++@itemx Mouse-2 ++Follow a cross reference that you click on. ++@item C-c C-c ++Show all documentation about the symbol at point. ++@end table ++ ++ When a function name (@pxref{M-x,, Running Commands by Name}), ++variable name (@pxref{Variables}), or face name (@pxref{Faces}) ++appears in the documentation, it normally appears inside paired ++single-quotes. To view the documentation of that command, variable or ++face, you can click on the name with @kbd{Mouse-1} or @kbd{Mouse-2}, ++or move point there and type @key{RET}. Use @kbd{C-c C-b} to retrace ++your steps. ++ ++@cindex URL, viewing in help ++@cindex help, viewing web pages ++@cindex viewing web pages in help ++@cindex web pages, viewing in help ++@findex browse-url ++ You can follow cross references to URLs (web pages) also. This uses ++the @code{browse-url} command to view the page in the browser you ++choose. @xref{Browse-URL}. ++ ++@kindex @key{TAB} @r{(Help mode)} ++@findex help-next-ref ++@kindex S-@key{TAB} @r{(Help mode)} ++@findex help-previous-ref ++ There are convenient commands to move point to cross references in ++the help text. @key{TAB} (@code{help-next-ref}) moves point down to ++the next cross reference. @kbd{S-@key{TAB}} moves up to the previous ++cross reference (@code{help-previous-ref}). ++ ++ To view all documentation about any symbol name that appears in the ++text, move point to the symbol name and type @kbd{C-c C-c} ++(@code{help-follow-symbol}). This shows all available documentation ++about the symbol as a variable, function and/or face. As above, use ++@kbd{C-c C-b} to retrace your steps. ++ ++@node Library Keywords ++@section Keyword Search for Lisp Libraries ++ ++@kindex C-h p ++@findex finder-by-keyword ++The @kbd{C-h p} command lets you search the standard Emacs Lisp ++libraries by topic keywords. Here is a partial list of keywords you can ++use: ++ ++@multitable {convenience} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} ++@item abbrev@tab abbreviation handling, typing shortcuts, macros. ++@item bib@tab code related to the @code{bib} bibliography processor. ++@item c@tab support for the C language and related languages. ++@item calendar@tab calendar and time management support. ++@item comm@tab communications, networking, remote access to files. ++@item convenience@tab convenience features for faster editing. ++@item data@tab support for editing files of data. ++@item docs@tab support for Emacs documentation. ++@item emulations@tab emulations of other editors. ++@item extensions@tab Emacs Lisp language extensions. ++@item faces@tab support for multiple fonts. ++@item files@tab support for editing and manipulating files. ++@item frames@tab support for Emacs frames and window systems. ++@item games@tab games, jokes and amusements. ++@item hardware@tab support for interfacing with exotic hardware. ++@item help@tab support for on-line help systems. ++@item hypermedia@tab support for links between text or other media types. ++@item i18n@tab internationalization and alternate character-set support. ++@item internal@tab code for Emacs internals, build process, defaults. ++@item languages@tab specialized modes for editing programming languages. ++@item lisp@tab Lisp support, including Emacs Lisp. ++@item local@tab code local to your site. ++@item maint@tab maintenance aids for the Emacs development group. ++@item mail@tab modes for electronic-mail handling. ++@item matching@tab various sorts of searching and matching. ++@item mouse@tab mouse support. ++@item multimedia@tab images and sound support. ++@item news@tab support for netnews reading and posting. ++@item oop@tab support for object-oriented programming. ++@item outlines@tab support for hierarchical outlining. ++@item processes@tab process, subshell, compilation, and job control support. ++@item terminals@tab support for terminal types. ++@item tex@tab supporting code for the @TeX{} formatter. ++@item tools@tab programming tools. ++@item unix@tab front-ends/assistants for, or emulators of, UNIX-like features. ++@item wp@tab word processing. ++@end multitable ++ ++@node Language Help ++@section Help for International Language Support ++ ++ You can use the command @kbd{C-h L} ++(@code{describe-language-environment}) to get information about a ++specific language environment. @xref{Language Environments}. This ++tells you which languages this language environment supports. It also ++lists the character sets, coding systems, and input methods that work ++with this language environment, and finally shows some sample text to ++illustrate scripts. ++ ++ The command @kbd{C-h h} (@code{view-hello-file}) displays the file ++@file{etc/HELLO}, which shows how to say ``hello'' in many languages. ++ ++ The command @kbd{C-h I} (@code{describe-input-method}) describes an ++input method---either a specified input method, or by default the ++input method currently in use. @xref{Input Methods}. ++ ++ The command @kbd{C-h C} (@code{describe-coding-system}) describes ++coding systems---either a specified coding system, or the ones ++currently in use. @xref{Coding Systems}. ++ ++@node Misc Help ++@section Other Help Commands ++ ++@kindex C-h i ++@findex info ++@cindex Info ++@cindex manuals, on-line ++@cindex on-line manuals ++ @kbd{C-h i} (@code{info}) runs the Info program, which browses ++structured documentation files. The entire Emacs manual is available ++within Info, along with many other manuals for the GNU system. Type ++@kbd{h} after entering Info to run a tutorial on using Info. ++ ++@cindex find Info manual by its file name ++ With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer ++@samp{*info*<@var{n}>}. This is useful if you want to browse multiple ++Info manuals simultaneously. If you specify just @kbd{C-u} as the ++prefix argument, @kbd{C-h i} prompts for the name of a documentation ++file, so you can browse a file which doesn't have an entry in the ++top-level Info menu. ++ ++ The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h ++K @var{key}}, described above, enter Info and go straight to the ++documentation of @var{function} or @var{key}. ++ ++@kindex C-h S ++@findex info-lookup-symbol ++ When editing a program, if you have an Info version of the manual ++for the programming language, you can use @kbd{C-h S} ++(@code{info-lookup-symbol}) to find an entry for a symbol (keyword, ++function or variable) in the proper manual. The details of how this ++command works depend on the major mode. ++ ++@kindex C-h l ++@findex view-lossage ++ If something surprising happens, and you are not sure what you typed, ++use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays your last ++300 input keystrokes. If you see commands that you don't know, you can ++use @kbd{C-h c} to find out what they do. ++ ++@kindex C-h e ++@findex view-echo-area-messages ++ To review recent echo area messages, use @kbd{C-h e} ++(@code{view-echo-area-messages}). This displays the buffer ++@code{*Messages*}, where those messages are kept. ++ ++@kindex C-h m ++@findex describe-mode ++ Each Emacs major mode typically redefines a few keys and makes other ++changes in how editing works. @kbd{C-h m} (@code{describe-mode}) ++displays documentation on the current major mode, which normally ++describes the commands and features that are changed in this mode. ++ ++@kindex C-h b ++@findex describe-bindings ++ @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s} ++(@code{describe-syntax}) show other information about the current ++environment within Emacs. @kbd{C-h b} displays a list of all the key ++bindings now in effect: first the local bindings of the current minor ++modes, then the local bindings defined by the current major mode, and ++finally the global bindings (@pxref{Key Bindings}). @kbd{C-h s} ++displays the contents of the syntax table, with explanations of each ++character's syntax (@pxref{Syntax}). ++ ++ You can get a list of subcommands for a particular prefix key by ++typing @kbd{C-h} after the prefix key. (There are a few prefix keys ++for which this does not work---those that provide their own bindings ++for @kbd{C-h}. One of these is @key{ESC}, because @kbd{@key{ESC} C-h} ++is actually @kbd{C-M-h}, which marks a defun.) ++ ++@node Help Files ++@section Help Files ++ ++ The Emacs help commands described above display dynamic help based ++on the current state within Emacs, or refer to manuals. Other help ++commands display pre-written, static help files. ++ ++ Except for @kbd{C-h g}, these commands all have the form @kbd{C-h ++C-@var{char}}; that is, @kbd{C-h} followed by a control character. ++ ++@kindex C-h C-c ++@findex describe-copying ++@kindex C-h C-d ++@findex view-emacs-debugging ++@kindex C-h C-e ++@findex view-external-packages ++@kindex C-h C-f ++@findex view-emacs-FAQ ++@kindex C-h g ++@findex describe-gnu-project ++@kindex C-h C-m ++@findex view-order-manuals ++@kindex C-h C-n ++@findex view-emacs-news ++@kindex C-h C-o ++@findex describe-distribution ++@kindex C-h C-p ++@findex view-emacs-problems ++@kindex C-h C-t ++@findex view-emacs-todo ++@kindex C-h C-w ++@findex describe-no-warranty ++ ++@table @kbd ++@item C-h C-c ++Display the Emacs copying conditions (@code{describe-copying}). ++These are the rules under which you can copy and redistribute Emacs. ++@item C-h C-d ++Display how to debug Emacs problems (@code{view-emacs-debugging}). ++@item C-h C-f ++Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). ++@item C-h g ++Display general information about the GNU Project ++(@code{describe-gnu-project}). ++@item C-h C-m ++Display how to order printed copies of Emacs manuals ++(@code{view-order-manuals}). ++@item C-h C-n ++Display the Emacs ``news'' file, which lists new features in the most ++recent version of Emacs (@code{view-emacs-news}). ++@item C-h C-o ++Display how to order or download the latest version of ++Emacs and other GNU software (@code{describe-distribution}). ++@item C-h C-p ++Display the list of known Emacs problems, sometimes with suggested ++workarounds (@code{view-emacs-problems}). ++@item C-h C-t ++Display the Emacs to-do list (@code{view-emacs-todo}). ++@item C-h C-w ++Display the full details on the complete absence of warranty for GNU ++Emacs (@code{describe-no-warranty}). ++@end table ++ ++@node Help Echo ++@section Help on Active Text and Tooltips ++ ++@cindex tooltips ++@cindex balloon help ++ When text on the screen is ``active'', so that it does something ++special in response to mouse clicks or @kbd{RET}, it often has associated ++help text. For instance, most parts of the mode line have help text. On ++terminals that support mouse tracking, Emacs displays the help text as a ++``tooltip'' (sometimes known as ``balloon help'') or in the echo area, ++whenever you leave the mouse stationary over the active text. ++@xref{Tooltips}. ++ ++@kindex C-h . ++@findex display-local-help ++@vindex help-at-pt-display-when-idle ++ If your terminal doesn't support mouse-tracking, you can display the ++help text for active buffer text using the keyboard. @kbd{C-h .} ++(@code{display-local-help}) displays any help text associated with the ++character after point, using the echo area. To display help text ++automatically whenever it is available on the character after point, set ++the variable @code{help-at-pt-display-when-idle} to @code{t}. ++ ++@ignore ++ arch-tag: 6f33ab62-bc75-4367-8057-fd67cc15c3a1 ++@end ignore +diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi +new file mode 100644 +index 0000000..9843bb3 +--- /dev/null ++++ b/doc/emacs/indent.texi +@@ -0,0 +1,251 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Indentation, Text, Major Modes, Top ++@chapter Indentation ++@cindex indentation ++@cindex tabs ++@cindex columns (indentation) ++ ++ This chapter describes the Emacs commands that add, remove, or ++adjust indentation. ++ ++@table @kbd ++@item @key{TAB} ++Indent the current line appropriately, in a mode-dependent fashion. ++@item @kbd{C-j} ++Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). ++@item M-^ ++Merge the previous and the current line (@code{delete-indentation}). ++This would cancel the effect of a preceding @kbd{C-j}. ++@item C-M-o ++Split the current line at point; text on the line after point becomes a ++new line indented to the same column where point is located ++(@code{split-line}). ++@item M-m ++Move (forward or back) to the first nonblank character on the current ++line (@code{back-to-indentation}). ++@item C-M-\ ++Indent lines in the region to the same column (@code{indent-region}). ++@item C-x @key{TAB} ++Shift lines in the region rigidly right or left (@code{indent-rigidly}). ++@item M-i ++Indent from point to the next prespecified tab stop column ++(@code{tab-to-tab-stop}). ++@item M-x indent-relative ++Indent from point to under an indentation point in the previous line. ++@end table ++ ++ In most major modes, the @key{TAB} key runs the command ++@code{indent-for-tab-command}, which either performs indentation or ++inserts whitespace at point, depending on the situation. ++ ++ In programming modes such as Lisp mode and C mode, @key{TAB} indents ++the current line if the region is inactive. If the region is active, ++it indents every line in the region (@pxref{Mark}). Indentation means ++adding or removing some combination of space and tab characters ++(@dfn{whitespace characters}) at the start of the line, in a way that ++makes sense given the text in the preceding lines. Exactly how ++indentation is performed depends on the major mode. @xref{Program ++Indent}. ++ ++ In text modes, @key{TAB} inserts some whitespace characters to ++advance point to the next tab stop (@pxref{Tab Stops}). For the ++purposes of this command, the position of the first non-whitespace ++character on the preceding line is treated as an additional tab stop. ++You can therefore use @key{TAB} to ``align'' point with the preceding ++line. If the region is active, @key{TAB} performs this action on ++every line in the region. ++ ++@vindex tab-width ++ Indentation is often performed with the help of @dfn{tab characters} ++(@acronym{ASCII} code 9), which are displayed as a stretch of empty space ++extending to the next @dfn{display tab stop}. By default, there is ++one display tab stop every eight columns; the number of columns is ++determined by the variable @code{tab-width}. You can insert a single ++tab character by typing @kbd{C-q @key{TAB}}. @xref{Text Display}. ++ ++@findex edit-tab-stops ++@findex tab-to-tab-stop ++@kindex M-i ++ The command @kbd{M-i} (@code{tab-to-tab-stop}) adjusts the ++whitespace characters around point, inserting just enough whitespace ++to advance point up to the next tab stop. By default, this involves ++deleting the existing whitespace and inserting a single tab character. ++ ++ Normally, most of these indentation commands insert an optimal mix ++of tabs and spaces to align to the desired column. @xref{Just ++Spaces}, for how to disable use of tabs. However, @kbd{C-q @key{TAB}} ++always inserts a tab, even when tabs are disabled for the indentation ++commands. ++ ++@menu ++* Indentation Commands:: Various commands and techniques for indentation. ++* Tab Stops:: You can set arbitrary "tab stops" and then ++ indent to the next tab stop when you want to. ++* Just Spaces:: You can request indentation using just spaces. ++@end menu ++ ++@node Indentation Commands, Tab Stops, Indentation, Indentation ++@section Indentation Commands and Techniques ++ ++@kindex M-m ++@findex back-to-indentation ++ To move over the indentation on a line, do @kbd{M-m} ++(@code{back-to-indentation}). This command, given anywhere on a line, ++positions point at the first nonblank character on the line, if any, ++or else at the end of the line. ++ ++ To insert an indented line before the current line, do @kbd{C-a C-o ++@key{TAB}}. To make an indented line after the current line, use ++@kbd{C-e C-j}. ++ ++ If you just want to insert a tab character in the buffer, type ++@kbd{C-q @key{TAB}}. ++ ++@kindex C-M-o ++@findex split-line ++ @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of ++the line vertically down, so that the current line becomes two lines. ++@kbd{C-M-o} first moves point forward over any spaces and tabs. Then it ++inserts after point a newline and enough indentation to reach the same ++column point is on. Point remains before the inserted newline; in this ++regard, @kbd{C-M-o} resembles @kbd{C-o}. ++ ++@kindex M-^ ++@findex delete-indentation ++ To join two lines cleanly, use the @kbd{M-^} ++(@code{delete-indentation}) command. It deletes the indentation at ++the front of the current line, and the line boundary as well, ++replacing them with a single space. As a special case (useful for ++Lisp code) the single space is omitted if the characters to be joined ++are consecutive open parentheses or closing parentheses, or if the ++junction follows another newline. To delete just the indentation of a ++line, go to the beginning of the line and use @kbd{M-\} ++(@code{delete-horizontal-space}), which deletes all spaces and tabs ++around the cursor. ++ ++ If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it ++appears after the newline that is deleted. @xref{Fill Prefix}. ++ ++@kindex C-M-\ ++@kindex C-x TAB ++@findex indent-region ++@findex indent-rigidly ++ There are also commands for changing the indentation of several lines ++at once. They apply to all the lines that begin in the region. ++@kbd{C-M-\} (@code{indent-region}) indents each line in the ``usual'' ++way, as if you had typed @key{TAB} at the beginning of the line. A ++numeric argument specifies the column to indent to, and each line is ++shifted left or right so that its first nonblank character appears in ++that column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of ++the lines in the region right by its argument (left, for negative ++arguments). The whole group of lines moves rigidly sideways, which is ++how the command gets its name. ++ ++@cindex remove indentation ++ To remove all indentation from all of the lines in the region, ++invoke @kbd{C-x @key{TAB}} with a large negative argument, such as ++-1000. ++ ++@findex indent-relative ++ @kbd{M-x indent-relative} indents at point based on the previous line ++(actually, the last nonempty line). It inserts whitespace at point, moving ++point, until it is underneath the next indentation point in the previous line. ++An indentation point is the end of a sequence of whitespace or the end of ++the line. If point is farther right than any indentation point in the ++previous line, @code{indent-relative} runs @code{tab-to-tab-stop} ++@ifnottex ++(@pxref{Tab Stops}), ++@end ifnottex ++@iftex ++(see next section), ++@end iftex ++unless it is called with a numeric argument, in which case it does ++nothing. ++ ++ @xref{Format Indentation}, for another way of specifying the ++indentation for part of your text. ++ ++@node Tab Stops, Just Spaces, Indentation Commands, Indentation ++@section Tab Stops ++ ++@cindex tab stops ++@cindex using tab stops in making tables ++@cindex tables, indentation for ++@kindex M-i ++@findex tab-to-tab-stop ++ For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}). ++This command inserts indentation before point, enough to reach the ++next tab stop column. ++ ++@findex edit-tab-stops ++@findex edit-tab-stops-note-changes ++@kindex C-c C-c @r{(Edit Tab Stops)} ++@vindex tab-stop-list ++ You can change the tab stops used by @kbd{M-i} and other indentation ++commands, so that they need not be spaced every eight characters, or ++even regularly spaced. The tab stops are stored in the variable ++@code{tab-stop-list}, as a list of column numbers in increasing order. ++ ++ A convenient way to set the tab stops is with @kbd{M-x ++edit-tab-stops}, which creates and selects a buffer containing a ++description of the tab stop settings. You can edit this buffer to ++specify different tab stops, and then type @kbd{C-c C-c} to make those ++new tab stops take effect. The buffer uses Overwrite mode ++(@pxref{Minor Modes}). @code{edit-tab-stops} records which buffer was ++current when you invoked it, and stores the tab stops back in that ++buffer; normally all buffers share the same tab stops and changing ++them in one buffer affects all, but if you happen to make ++@code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in ++that buffer will edit the local settings. ++ ++ Here is what the text representing the tab stops looks like for ordinary ++tab stops every eight columns. ++ ++@example ++ : : : : : : ++0 1 2 3 4 ++0123456789012345678901234567890123456789012345678 ++To install changes, type C-c C-c ++@end example ++ ++ The first line contains a colon at each tab stop. The remaining lines ++are present just to help you see where the colons are and know what to do. ++ ++ Note that the tab stops that control @code{tab-to-tab-stop} have ++nothing to do with how tab characters are displayed in the buffer. ++Tab characters are always displayed as empty spaces extending to the ++next display tab stop, which occurs every @code{tab-width} columns ++regardless of the contents of @code{tab-stop-list}. @xref{Text ++Display}. ++ ++@node Just Spaces,, Tab Stops, Indentation ++@section Tabs vs. Spaces ++ ++@vindex indent-tabs-mode ++ Emacs normally uses both tabs and spaces to indent lines. If you ++prefer, all indentation can be made from spaces only. To request ++this, set @code{indent-tabs-mode} to @code{nil}. This is a per-buffer ++variable, so altering the variable affects only the current buffer, ++but there is a default value which you can change as well. ++@xref{Locals}. ++ ++ A tab is not always displayed in the same way. By default, tabs are ++eight columns wide, but some people like to customize their editors to ++use a different tab width (e.g., by changing the variable ++@code{tab-width} in Emacs). By using spaces only, you can make sure ++that your file looks the same regardless of the tab width setting. ++ ++@findex tabify ++@findex untabify ++ There are also commands to convert tabs to spaces or vice versa, always ++preserving the columns of all nonblank text. @kbd{M-x tabify} scans the ++region for sequences of spaces, and converts sequences of at least two ++spaces to tabs if that can be done without changing indentation. @kbd{M-x ++untabify} changes all tabs in the region to appropriate numbers of spaces. ++ ++@ignore ++ arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb ++@end ignore +diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi +new file mode 100644 +index 0000000..7626b2c +--- /dev/null ++++ b/doc/emacs/killing.texi +@@ -0,0 +1,665 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++ ++@node Killing, Yanking, Mark, Top ++@chapter Killing and Moving Text ++ ++@ifnottex ++@raisesections ++@end ifnottex ++ ++ @dfn{Killing} means erasing text and copying it into the @dfn{kill ++ring}, from which you can bring it back into the buffer by ++@dfn{yanking} it. (Some applications use the terms ``cutting'' and ++``pasting'' for similar operations.) This is the most common way of ++moving or copying text within Emacs. It is very versatile, because ++there are commands for killing many different types of syntactic ++units. ++ ++@iftex ++@section Deletion and Killing ++@end iftex ++ ++@cindex killing text ++@cindex cutting text ++@cindex deletion ++ Most commands which erase text from the buffer save it in the kill ++ring. These are known as @dfn{kill} commands. The kill ring stores ++several recent kills, not just the last one, so killing is a very safe ++operation: when you make a new kill, you don't have to worry much ++about losing text that you previously killed. ++ ++ You can yank text from the kill ring into any position in a buffer, ++including a position in a different buffer; the kill ring is shared by ++all buffers. The @kbd{C-/} (@code{undo}) command can undo both kill ++and delete commands (@pxref{Undo}); the importance of the kill ring is ++that you can yank the text in a different place. ++ ++ Commands that erase text but do not save it in the kill ring are ++known as @dfn{delete} commands. These include @kbd{C-d} ++(@code{delete-char}) and @key{DEL} (@code{delete-backward-char}), ++which delete only one character at a time, and those commands that ++delete only spaces or newlines. Commands that can erase significant ++amounts of nontrivial data generally do a kill operation instead. The ++commands' names and individual descriptions use the words @samp{kill} ++and @samp{delete} to say which kind of operation they perform. ++ ++@vindex kill-read-only-ok ++@cindex read-only text, killing ++ Some specialized buffers contain @dfn{read-only text}, which cannot ++be modified and therefore cannot be killed. But some users like to ++use the kill commands to copy read-only text into the kill ring, ++without actually changing it. Therefore, the kill commands work ++specially in a read-only buffer: they move over text, and copy it to ++the kill ring, without actually deleting it from the buffer. ++Normally, kill commands beep and display an error message when this ++happens. But if you set the variable @code{kill-read-only-ok} to a ++non-@code{nil} value, they just print a message in the echo area to ++explain why the text has not been erased. ++ ++ You can also use the mouse to kill and yank. @xref{Cut and Paste}. ++ ++@menu ++* Deletion:: Commands for deleting small amounts of text and ++ blank areas. ++* Killing by Lines:: How to kill entire lines of text at one time. ++* Other Kill Commands:: Commands to kill large regions of text and ++ syntactic units such as words and sentences. ++@end menu ++ ++@need 1500 ++@node Deletion ++@subsection Deletion ++@findex delete-backward-char ++@findex delete-char ++ ++ Deletion means erasing text and not saving it in the kill ring. For ++the most part, the Emacs commands that delete text are those that ++erase just one character or only whitespace. ++ ++@table @kbd ++@item C-d ++@itemx @key{Delete} ++Delete next character (@code{delete-char}). ++@item @key{DEL} ++@itemx @key{Backspace} ++Delete previous character (@code{delete-backward-char}). ++@item M-\ ++Delete spaces and tabs around point (@code{delete-horizontal-space}). ++@item M-@key{SPC} ++Delete spaces and tabs around point, leaving one space ++(@code{just-one-space}). ++@item C-x C-o ++Delete blank lines around the current line (@code{delete-blank-lines}). ++@item M-^ ++Join two lines by deleting the intervening newline, along with any ++indentation following it (@code{delete-indentation}). ++@end table ++ ++ We have already described the basic deletion commands @kbd{C-d} ++(@code{delete-char}) and @key{DEL} (@code{delete-backward-char}). ++@xref{Erasing}. ++ ++@kindex M-\ ++@findex delete-horizontal-space ++@kindex M-SPC ++@findex just-one-space ++ The other delete commands are those that delete only whitespace ++characters: spaces, tabs and newlines. @kbd{M-\} ++(@code{delete-horizontal-space}) deletes all the spaces and tab ++characters before and after point. With a prefix argument, this only ++deletes spaces and tab characters before point. @kbd{M-@key{SPC}} ++(@code{just-one-space}) does likewise but leaves a single space after ++point, regardless of the number of spaces that existed previously ++(even if there were none before). With a numeric argument @var{n}, it ++leaves @var{n} spaces after point. ++ ++ @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines ++after the current line. If the current line is blank, it deletes all ++blank lines preceding the current line as well (leaving one blank line, ++the current line). On a solitary blank line, it deletes that line. ++ ++ @kbd{M-^} (@code{delete-indentation}) joins the current line and the ++previous line, by deleting a newline and all surrounding spaces, usually ++leaving a single space. @xref{Indentation,M-^}. ++ ++@node Killing by Lines ++@subsection Killing by Lines ++ ++@table @kbd ++@item C-k ++Kill rest of line or one or more lines (@code{kill-line}). ++@item C-S-backspace ++Kill an entire line at once (@code{kill-whole-line}) ++@end table ++ ++@kindex C-k ++@findex kill-line ++ The simplest kill command is @kbd{C-k}. If given at the beginning ++of a line, it kills all the text on the line@footnote{Here, ``line'' ++means a logical text line, not a screen line. @xref{Continuation ++Lines}.}, leaving it blank. When used on a blank line, it kills the ++whole line including its newline. ++ ++ More precisely, @kbd{C-k} kills from point up to the end of the ++line, unless it is at the end of a line. In that case it kills the ++newline following point, thus merging the next line into the current ++one. Spaces and tabs at the end of the line are ignored when deciding ++which case applies, so as long as point is after the last visible ++character in the line, you can be sure that @kbd{C-k} will kill the ++newline. To kill an entire non-blank line, go to the beginning and ++type @kbd{C-k} twice. ++ ++ When @kbd{C-k} is given a positive argument @var{n}, it kills ++@var{n} lines and the newlines that follow them (text on the current ++line before point is not killed). With a negative argument ++@minus{}@var{n}, it kills @var{n} lines preceding the current line, ++together with the text on the current line before point. @kbd{C-k} ++with an argument of zero kills the text before point on the current ++line. ++ ++@vindex kill-whole-line ++ If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at ++the very beginning of a line kills the entire line including the ++following newline. This variable is normally @code{nil}. ++ ++@kindex C-S-backspace ++@findex kill-whole-line ++ @kbd{C-S-backspace} (@code{kill-whole-line}) will kill a whole line ++including its newline regardless of the position of point within the ++line. Note that many character terminals will prevent you from typing ++the key sequence @kbd{C-S-backspace}. ++ ++@node Other Kill Commands ++@subsection Other Kill Commands ++@findex kill-region ++@kindex C-w ++ ++@table @kbd ++@item C-w ++Kill region (@code{kill-region}). @xref{Mark}. ++@item M-w ++Save region as last killed text without actually killing it ++(@code{kill-ring-save}). Some programs call this ``copying.'' ++@item M-d ++Kill word (@code{kill-word}). @xref{Words}. ++@item M-@key{DEL} ++Kill word backwards (@code{backward-kill-word}). ++@item C-x @key{DEL} ++Kill back to beginning of sentence (@code{backward-kill-sentence}). ++@xref{Sentences}. ++@item M-k ++Kill to end of sentence (@code{kill-sentence}). ++@item C-M-k ++Kill the following balanced expression (@code{kill-sexp}). @xref{Expressions}. ++@item M-z @var{char} ++Kill through the next occurrence of @var{char} (@code{zap-to-char}). ++@end table ++ ++ Apart from @kbd{C-k}, the most commonly-used kill command is ++@kbd{C-w} (@code{kill-region}), which kills the text in the region ++(i.e., between point and mark). @xref{Mark}. If the mark is inactive ++when you type @kbd{C-w}, it first reactivates the mark where it was ++last set. The mark is deactivated at the end of the command. ++ ++@kindex M-w ++@findex kill-ring-save ++ The command @kbd{M-w} (@code{kill-ring-save}) copies the region into ++the kill ring without removing it from the buffer. This is ++approximately equivalent to @kbd{C-w} followed by @kbd{C-/}, except ++that @kbd{M-w} does not alter the undo history. ++ ++ Emacs also provides commands to kill specific syntactic units: ++words, with @kbd{M-@key{DEL}} and @kbd{M-d} (@pxref{Words}); balanced ++expressions, with @kbd{C-M-k} (@pxref{Expressions}); and sentences, ++with @kbd{C-x @key{DEL}} and @kbd{M-k} (@pxref{Sentences}). ++ ++@kindex M-z ++@findex zap-to-char ++ The command @kbd{M-z} (@code{zap-to-char}) combines killing with ++searching: it reads a character and kills from point up to (and ++including) the next occurrence of that character in the buffer. A ++numeric argument acts as a repeat count; a negative argument means to ++search backward and kill text before point. ++ ++@node Yanking, Accumulating Text, Killing, Top ++@section Yanking ++@cindex moving text ++@cindex copying text ++@cindex kill ring ++@cindex yanking ++@cindex pasting ++ ++ @dfn{Yanking} means reinserting text previously killed. The usual ++way to move or copy text is to kill it and then yank it elsewhere one ++or more times. ++ ++@table @kbd ++@item C-y ++Yank last killed text (@code{yank}). ++@item M-y ++Replace text just yanked with an earlier batch of killed text ++(@code{yank-pop}). ++@item C-M-w ++Append next kill to last batch of killed text (@code{append-next-kill}). ++@end table ++ ++ On graphical displays with window systems, if there is a current ++selection in some other application, and you selected it more recently ++than you killed any text in Emacs, @kbd{C-y} copies the selection ++instead of text killed within Emacs. ++ ++@menu ++* Kill Ring:: Where killed text is stored. Basic yanking. ++* Appending Kills:: Several kills in a row all yank together. ++* Earlier Kills:: Yanking something killed some time ago. ++@end menu ++ ++@node Kill Ring ++@subsection The Kill Ring ++ ++ All killed text is recorded in the @dfn{kill ring}, a list of blocks ++of text that have been killed. There is only one kill ring, shared by ++all buffers, so you can kill text in one buffer and yank it in another ++buffer. This is the usual way to move text from one file to another. ++(There are several other methods: for instance, you could store the ++text in a register. @xref{Registers}, for information about ++registers. @xref{Accumulating Text}, for some other ways to move text ++around.) ++ ++@kindex C-y ++@findex yank ++ The command @kbd{C-y} (@code{yank}) reinserts the text of the most ++recent kill, leaving the cursor at the end of the text. It also adds ++the position of the beginning of the text to the mark ring, without ++activating the mark; this allows you to jump easily to that position ++with @kbd{C-x C-x} (@pxref{Setting Mark}). With a plain prefix ++argument (@kbd{C-u C-y}), it instead leaves the cursor in front of the ++text, and adds the position of the end of the text to the mark ring. ++Using other sort of prefix argument specifies an earlier kill; for ++example, @kbd{C-u 4 C-y} reinserts the fourth most recent kill. ++@xref{Earlier Kills}. ++ ++@cindex yanking and text properties ++@vindex yank-excluded-properties ++ The yank commands discard certain properties from the yanked text. ++These are properties that might lead to annoying results, such as ++causing the text to respond to the mouse or specifying key bindings. ++The list of properties to discard is stored in the variable ++@code{yank-excluded-properties}. Yanking of register contents and ++rectangles also discard these properties. @xref{Text Properties,,, ++elisp, the Emacs Lisp Reference Manual}, for more information about ++text properties. ++ ++@node Appending Kills ++@subsection Appending Kills ++ ++@cindex appending kills in the ring ++ Normally, each kill command pushes a new entry onto the kill ring. ++However, two or more kill commands in a row combine their text into a ++single entry, so that a single @kbd{C-y} yanks all the text as a unit, ++just as it was before it was killed. ++ ++ Thus, if you want to yank text as a unit, you need not kill all of it ++with one command; you can keep killing line after line, or word after ++word, until you have killed it all, and you can still get it all back at ++once. ++ ++ Commands that kill forward from point add onto the end of the previous ++killed text. Commands that kill backward from point add text onto the ++beginning. This way, any sequence of mixed forward and backward kill ++commands puts all the killed text into one entry without rearrangement. ++Numeric arguments do not break the sequence of appending kills. For ++example, suppose the buffer contains this text: ++ ++@example ++This is a line @point{}of sample text. ++@end example ++ ++@noindent ++with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d ++M-@key{DEL}}, killing alternately forward and backward, you end up with ++@samp{a line of sample} as one entry in the kill ring, and @samp{This ++is@ @ text.} in the buffer. (Note the double space between @samp{is} ++and @samp{text}, which you can clean up with @kbd{M-@key{SPC}} or ++@kbd{M-q}.) ++ ++ Another way to kill the same text is to move back two words with ++@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}. ++This produces exactly the same results in the buffer and in the kill ++ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going ++backward; once again, the result is the same. The text in the kill ring ++entry always has the same order that it had in the buffer before you ++killed it. ++ ++@kindex C-M-w ++@findex append-next-kill ++ If a kill command is separated from the last kill command by other ++commands (not just numeric arguments), it starts a new entry on the kill ++ring. But you can force it to append by first typing the command ++@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w} ++tells the following command, if it is a kill command, to append the text ++it kills to the last killed text, instead of starting a new entry. With ++@kbd{C-M-w}, you can kill several separated pieces of text and ++accumulate them to be yanked back in one place.@refill ++ ++ A kill command following @kbd{M-w} (@code{kill-ring-save}) does not ++append to the text that @kbd{M-w} copied into the kill ring. ++ ++@node Earlier Kills ++@subsection Yanking Earlier Kills ++ ++@cindex yanking previous kills ++@kindex M-y ++@findex yank-pop ++ To recover killed text that is no longer the most recent kill, use the ++@kbd{M-y} command (@code{yank-pop}). It takes the text previously ++yanked and replaces it with the text from an earlier kill. So, to ++recover the text of the next-to-the-last kill, first use @kbd{C-y} to ++yank the last kill, and then use @kbd{M-y} to replace it with the ++previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another ++@kbd{M-y}. ++ ++ You can understand @kbd{M-y} in terms of a ``last yank'' pointer which ++points at an entry in the kill ring. Each time you kill, the ``last ++yank'' pointer moves to the newly made entry at the front of the ring. ++@kbd{C-y} yanks the entry which the ``last yank'' pointer points to. ++@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the ++text in the buffer changes to match. Enough @kbd{M-y} commands can move ++the pointer to any entry in the ring, so you can get any entry into the ++buffer. Eventually the pointer reaches the end of the ring; the next ++@kbd{M-y} loops back around to the first entry again. ++ ++ @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does ++not change the order of the entries in the ring, which always runs from ++the most recent kill at the front to the oldest one still remembered. ++ ++ @kbd{M-y} can take a numeric argument, which tells it how many entries ++to advance the ``last yank'' pointer by. A negative argument moves the ++pointer toward the front of the ring; from the front of the ring, it ++moves ``around'' to the last entry and continues forward from there. ++ ++ Once the text you are looking for is brought into the buffer, you can ++stop doing @kbd{M-y} commands and it will stay there. It's just a copy ++of the kill ring entry, so editing it in the buffer does not change ++what's in the ring. As long as no new killing is done, the ``last ++yank'' pointer remains at the same place in the kill ring, so repeating ++@kbd{C-y} will yank another copy of the same previous kill. ++ ++ If you know how many @kbd{M-y} commands it would take to find the ++text you want, you can yank that text in one step using @kbd{C-y} with ++a numeric argument. @kbd{C-y} with an argument restores the text from ++the specified kill ring entry, counting back from the most recent as ++1. Thus, @kbd{C-u 2 C-y} gets the next-to-the-last block of killed ++text---it is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numeric ++argument starts counting from the ``last yank'' pointer, and sets the ++``last yank'' pointer to the entry that it yanks. ++ ++@vindex kill-ring-max ++ The length of the kill ring is controlled by the variable ++@code{kill-ring-max}; no more than that many blocks of killed text are ++saved. ++ ++@vindex kill-ring ++ The actual contents of the kill ring are stored in a variable named ++@code{kill-ring}; you can view the entire contents of the kill ring with ++the command @kbd{C-h v kill-ring}. ++ ++@node Accumulating Text, Rectangles, Yanking, Top ++@section Accumulating Text ++@findex append-to-buffer ++@findex prepend-to-buffer ++@findex copy-to-buffer ++@findex append-to-file ++ ++@cindex accumulating scattered text ++ Usually we copy or move text by killing it and yanking it, but there ++are other convenient methods for copying one block of text in many ++places, or for copying many scattered blocks of text into one place. ++Here we describe the commands to accumulate scattered pieces of text ++into a buffer or into a file. ++ ++@table @kbd ++@item M-x append-to-buffer ++Append region to the contents of a specified buffer. ++@item M-x prepend-to-buffer ++Prepend region to the contents of a specified buffer. ++@item M-x copy-to-buffer ++Copy region into a specified buffer, deleting that buffer's old contents. ++@item M-x insert-buffer ++Insert the contents of a specified buffer into current buffer at point. ++@item M-x append-to-file ++Append region to the contents of a specified file, at the end. ++@end table ++ ++ To accumulate text into a buffer, use @kbd{M-x append-to-buffer}. ++This reads a buffer name, then inserts a copy of the region into the ++buffer specified. If you specify a nonexistent buffer, ++@code{append-to-buffer} creates the buffer. The text is inserted ++wherever point is in that buffer. If you have been using the buffer for ++editing, the copied text goes into the middle of the text of the buffer, ++starting from wherever point happens to be at that moment. ++ ++ Point in that buffer is left at the end of the copied text, so ++successive uses of @code{append-to-buffer} accumulate the text in the ++specified buffer in the same order as they were copied. Strictly ++speaking, @code{append-to-buffer} does not always append to the text ++already in the buffer---it appends only if point in that buffer is at the end. ++However, if @code{append-to-buffer} is the only command you use to alter ++a buffer, then point is always at the end. ++ ++ @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer} ++except that point in the other buffer is left before the copied text, so ++successive prependings add text in reverse order. @kbd{M-x ++copy-to-buffer} is similar, except that any existing text in the other ++buffer is deleted, so the buffer is left containing just the text newly ++copied into it. ++ ++ The command @kbd{M-x insert-buffer} can be used to retrieve the ++accumulated text from another buffer. This prompts for the name of a ++buffer, and inserts a copy of all the text in that buffer into the ++current buffer at point, leaving point at the beginning of the ++inserted text. It also adds the position of the end of the inserted ++text to the mark ring, without activating the mark. @xref{Buffers}, ++for background information on buffers. ++ ++ Instead of accumulating text in a buffer, you can append text ++directly into a file with @kbd{M-x append-to-file}. This prompts for ++a filename, and adds the text of the region to the end of the ++specified file. The file is changed immediately on disk. ++ ++ You should use @code{append-to-file} only with files that are ++@emph{not} being visited in Emacs. Using it on a file that you are ++editing in Emacs would change the file behind Emacs's back, which ++can lead to losing some of your editing. ++ ++ Another way to move text around is to store it in a register. ++@xref{Registers}. ++ ++@node Rectangles, CUA Bindings, Accumulating Text, Top ++@section Rectangles ++@cindex rectangle ++@cindex columns (and rectangles) ++@cindex killing rectangular areas of text ++ ++ @dfn{Rectangle} commands operate on rectangular areas of the text: ++all the characters between a certain pair of columns, in a certain ++range of lines. Emacs has commands to kill rectangles, yank killed ++rectangles, clear them out, fill them with blanks or text, or delete ++them. Rectangle commands are useful with text in multicolumn formats, ++and for changing text into or out of such formats. ++ ++@cindex mark rectangle ++ When you must specify a rectangle for a command to work on, you do it ++by putting the mark at one corner and point at the opposite corner. The ++rectangle thus specified is called the @dfn{region-rectangle} because ++you control it in much the same way as the region is controlled. But ++remember that a given combination of point and mark values can be ++interpreted either as a region or as a rectangle, depending on the ++command that uses them. ++ ++ If point and the mark are in the same column, the rectangle they ++delimit is empty. If they are in the same line, the rectangle is one ++line high. This asymmetry between lines and columns comes about ++because point (and likewise the mark) is between two columns, but within ++a line. ++ ++@table @kbd ++@item C-x r k ++Kill the text of the region-rectangle, saving its contents as the ++``last killed rectangle'' (@code{kill-rectangle}). ++@item C-x r d ++Delete the text of the region-rectangle (@code{delete-rectangle}). ++@item C-x r y ++Yank the last killed rectangle with its upper left corner at point ++(@code{yank-rectangle}). ++@item C-x r o ++Insert blank space to fill the space of the region-rectangle ++(@code{open-rectangle}). This pushes the previous contents of the ++region-rectangle rightward. ++@item C-x r c ++Clear the region-rectangle by replacing all of its contents with spaces ++(@code{clear-rectangle}). ++@item M-x delete-whitespace-rectangle ++Delete whitespace in each of the lines on the specified rectangle, ++starting from the left edge column of the rectangle. ++@item C-x r t @var{string} @key{RET} ++Replace rectangle contents with @var{string} on each line ++(@code{string-rectangle}). ++@item M-x string-insert-rectangle @key{RET} @var{string} @key{RET} ++Insert @var{string} on each line of the rectangle. ++@end table ++ ++ The rectangle operations fall into two classes: commands for ++deleting and inserting rectangles, and commands for blank rectangles. ++ ++@kindex C-x r k ++@kindex C-x r d ++@findex kill-rectangle ++@findex delete-rectangle ++ There are two ways to get rid of the text in a rectangle: you can ++discard the text (delete it) or save it as the ``last killed'' ++rectangle. The commands for these two ways are @kbd{C-x r d} ++(@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). In ++either case, the portion of each line that falls inside the rectangle's ++boundaries is deleted, causing any following text on the line to ++move left into the gap. ++ ++ Note that ``killing'' a rectangle is not killing in the usual sense; the ++rectangle is not stored in the kill ring, but in a special place that ++can only record the most recent rectangle killed. This is because yanking ++a rectangle is so different from yanking linear text that different yank ++commands have to be used. It is hard to define yank-popping for rectangles, ++so we do not try. ++ ++@kindex C-x r y ++@findex yank-rectangle ++ To yank the last killed rectangle, type @kbd{C-x r y} ++(@code{yank-rectangle}). Yanking a rectangle is the opposite of killing ++one. Point specifies where to put the rectangle's upper left corner. ++The rectangle's first line is inserted there, the rectangle's second ++line is inserted at the same horizontal position, but one line ++vertically down, and so on. The number of lines affected is determined ++by the height of the saved rectangle. ++ ++ You can convert single-column lists into double-column lists using ++rectangle killing and yanking; kill the second half of the list as a ++rectangle and then yank it beside the first line of the list. ++@xref{Two-Column}, for another way to edit multi-column text. ++ ++ You can also copy rectangles into and out of registers with @kbd{C-x r ++r @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,Rectangle ++Registers}. ++ ++@kindex C-x r o ++@findex open-rectangle ++@kindex C-x r c ++@findex clear-rectangle ++ There are two commands you can use for making blank rectangles: ++@kbd{C-x r c} (@code{clear-rectangle}) which blanks out existing text, ++and @kbd{C-x r o} (@code{open-rectangle}) which inserts a blank ++rectangle. Clearing a rectangle is equivalent to deleting it and then ++inserting a blank rectangle of the same size. ++ ++@findex delete-whitespace-rectangle ++ The command @kbd{M-x delete-whitespace-rectangle} deletes horizontal ++whitespace starting from a particular column. This applies to each of ++the lines in the rectangle, and the column is specified by the left ++edge of the rectangle. The right edge of the rectangle does not make ++any difference to this command. ++ ++@kindex C-x r t ++@findex string-rectangle ++ The command @kbd{C-x r t} (@code{string-rectangle}) replaces the ++contents of a region-rectangle with a string on each line. The ++string's width need not be the same as the width of the rectangle. If ++the string's width is less, the text after the rectangle shifts left; ++if the string is wider than the rectangle, the text after the ++rectangle shifts right. ++ ++@findex string-insert-rectangle ++ The command @kbd{M-x string-insert-rectangle} is similar to ++@code{string-rectangle}, but inserts the string on each line, ++shifting the original text to the right. ++ ++@node CUA Bindings, Registers, Rectangles, Top ++@section CUA Bindings ++@findex cua-mode ++@vindex cua-mode ++@cindex CUA key bindings ++@vindex cua-enable-cua-keys ++ The command @kbd{M-x cua-mode} sets up key bindings that are ++compatible with the Common User Access (CUA) system used in many other ++applications. @kbd{C-x} means cut (kill), @kbd{C-c} copy, @kbd{C-v} ++paste (yank), and @kbd{C-z} undo. Standard Emacs commands like ++@kbd{C-x C-c} still work, because @kbd{C-x} and @kbd{C-c} only take ++effect when the mark is active (and the region is highlighted). ++However, if you don't want to override these bindings in Emacs at all, ++set @code{cua-enable-cua-keys} to @code{nil}. ++ ++ To enter an Emacs command like @kbd{C-x C-f} while the mark is ++active, use one of the following methods: either hold @kbd{Shift} ++together with the prefix key, e.g. @kbd{S-C-x C-f}, or quickly type ++the prefix key twice, e.g. @kbd{C-x C-x C-f}. ++ ++ In CUA mode, typed text replaces the active region as in ++Delete-Selection mode (@pxref{Mouse Commands}). ++ ++@cindex rectangle highlighting ++ CUA mode provides enhanced rectangle support with visible ++rectangle highlighting. Use @kbd{C-RET} to start a rectangle, ++extend it using the movement commands, and cut or copy it using ++@kbd{C-x} or @kbd{C-c}. @kbd{RET} moves the cursor to the next ++(clockwise) corner of the rectangle, so you can easily expand it in ++any direction. Normal text you type is inserted to the left or right ++of each line in the rectangle (on the same side as the cursor). ++ ++ With CUA you can easily copy text and rectangles into and out of ++registers by providing a one-digit numeric prefix to the kill, copy, ++and yank commands, e.g. @kbd{C-1 C-c} copies the region into register ++@code{1}, and @kbd{C-2 C-v} yanks the contents of register @code{2}. ++ ++@cindex global mark ++ CUA mode also has a global mark feature which allows easy moving and ++copying of text between buffers. Use @kbd{C-S-SPC} to toggle the ++global mark on and off. When the global mark is on, all text that you ++kill or copy is automatically inserted at the global mark, and text ++you type is inserted at the global mark rather than at the current ++position. ++ ++ For example, to copy words from various buffers into a word list in ++a given buffer, set the global mark in the target buffer, then ++navigate to each of the words you want in the list, mark it (e.g. with ++@kbd{S-M-f}), copy it to the list with @kbd{C-c} or @kbd{M-w}, and ++insert a newline after the word in the target list by pressing ++@key{RET}. ++ ++@ifnottex ++@lowersections ++@end ifnottex ++ ++@ignore ++ arch-tag: d8da8f96-0928-449a-816e-ff2d3497866c ++@end ignore +diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi +new file mode 100644 +index 0000000..0799095 +--- /dev/null ++++ b/doc/emacs/kmacro.texi +@@ -0,0 +1,575 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Keyboard Macros, Files, Fixit, Top ++@chapter Keyboard Macros ++@cindex defining keyboard macros ++@cindex keyboard macro ++ ++ In this chapter we describe how to record a sequence of editing ++commands so you can repeat it conveniently later. ++ ++ A @dfn{keyboard macro} is a command defined by an Emacs user to stand for ++another sequence of keys. For example, if you discover that you are ++about to type @kbd{C-n M-d C-d} forty times, you can speed your work by ++defining a keyboard macro to do @kbd{C-n M-d C-d}, and then executing ++it 39 more times. ++ ++ You define a keyboard macro by executing and recording the commands ++which are its definition. Put differently, as you define a keyboard ++macro, the definition is being executed for the first time. This way, ++you can see the effects of your commands, so that you don't have to ++figure them out in your head. When you close the definition, the ++keyboard macro is defined and also has been, in effect, executed once. ++You can then do the whole thing over again by invoking the macro. ++ ++ Keyboard macros differ from ordinary Emacs commands in that they are ++written in the Emacs command language rather than in Lisp. This makes it ++easier for the novice to write them, and makes them more convenient as ++temporary hacks. However, the Emacs command language is not powerful ++enough as a programming language to be useful for writing anything ++intelligent or general. For such things, Lisp must be used. ++ ++@menu ++* Basic Keyboard Macro:: Defining and running keyboard macros. ++* Keyboard Macro Ring:: Where previous keyboard macros are saved. ++* Keyboard Macro Counter:: Inserting incrementing numbers in macros. ++* Keyboard Macro Query:: Making keyboard macros do different things each time. ++* Save Keyboard Macro:: Giving keyboard macros names; saving them in files. ++* Edit Keyboard Macro:: Editing keyboard macros. ++* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard ++ macro. ++@end menu ++ ++@node Basic Keyboard Macro ++@section Basic Use ++ ++@table @kbd ++@item @key{F3} ++Start defining a keyboard macro ++(@code{kmacro-start-macro-or-insert-counter}). ++@item @key{F4} ++If a keyboard macro is being defined, end the definition; otherwise, ++execute the most recent keyboard macro ++(@code{kmacro-end-or-call-macro}). ++@item C-u @key{F3} ++Re-execute last keyboard macro, then append keys to its definition. ++@item C-u C-u @key{F3} ++Append keys to the last keyboard macro without re-executing it. ++@item C-x C-k r ++Run the last keyboard macro on each line that begins in the region ++(@code{apply-macro-to-region-lines}). ++@end table ++ ++@kindex F3 ++@kindex F4 ++@findex kmacro-start-macro-or-insert-counter ++@findex kmacro-end-or-call-macro ++@findex kmacro-end-and-call-macro ++ To start defining a keyboard macro, type @key{F3}. From then on, ++your keys continue to be executed, but also become part of the ++definition of the macro. @samp{Def} appears in the mode line to ++remind you of what is going on. When you are finished, type @key{F4} ++(@code{kmacro-end-or-call-macro}) to terminate the definition. For ++example, ++ ++@example ++@key{F3} M-f foo @key{F4} ++@end example ++ ++@noindent ++defines a macro to move forward a word and then insert @samp{foo}. ++Note that @key{F3} and @key{F4} do not become part of the macro. ++ ++ After defining the macro, you can call it with @key{F4}. For the ++above example, this has the same effect as typing @kbd{M-f foo} again. ++(Note the two roles of the @key{F4} command: it ends the macro if you ++are in the process of defining one, or calls the last macro ++otherwise.) You can also supply @key{F4} with a numeric prefix ++argument @samp{n}, which means to invoke the macro @samp{n} times. An ++argument of zero repeats the macro indefinitely, until it gets an ++error or you type @kbd{C-g} (or, on MS-DOS, @kbd{C-@key{BREAK}}). ++ ++ The above example demonstrates a handy trick that you can employ ++with keyboard macros: if you wish to repeat an operation at regularly ++spaced places in the text, include a motion command as part of the ++macro. In this case, repeating the macro inserts the string ++@samp{foo} after each successive word. ++ ++ After terminating the definition of a keyboard macro, you can append ++more keystrokes to its definition by typing @kbd{C-u @key{F3}}. This ++is equivalent to plain @key{F3} followed by retyping the whole ++definition so far. As a consequence, it re-executes the macro as ++previously defined. If you change the variable ++@code{kmacro-execute-before-append} to @code{nil}, the existing macro ++will not be re-executed before appending to it (the default is ++@code{t}). You can also add to the end of the definition of the last ++keyboard macro without re-executing it by typing @kbd{C-u C-u ++@key{F3}}. ++ ++ When a command reads an argument with the minibuffer, your ++minibuffer input becomes part of the macro along with the command. So ++when you replay the macro, the command gets the same argument as when ++you entered the macro. For example, ++ ++@example ++@key{F3} C-a C-k C-x b foo @key{RET} C-y C-x b @key{RET} @key{F4} ++@end example ++ ++@noindent ++defines a macro that kills the current line, yanks it into the buffer ++@samp{foo}, then returns to the original buffer. ++ ++ Most keyboard commands work as usual in a keyboard macro definition, ++with some exceptions. Typing @kbd{C-g} (@code{keyboard-quit}) quits ++the keyboard macro definition. Typing @kbd{C-M-c} ++(@code{exit-recursive-edit}) can be unreliable: it works as you'd ++expect if exiting a recursive edit that started within the macro, but ++if it exits a recursive edit that started before you invoked the ++keyboard macro, it also necessarily exits the keyboard macro too. ++Mouse events are also unreliable, even though you can use them in a ++keyboard macro: when the macro replays the mouse event, it uses the ++original mouse position of that event, the position that the mouse had ++while you were defining the macro. The effect of this may be hard to ++predict. ++ ++@findex apply-macro-to-region-lines ++@kindex C-x C-k r ++ The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines}) ++repeats the last defined keyboard macro on each line that begins in ++the region. It does this line by line, by moving point to the ++beginning of the line and then executing the macro. ++ ++@kindex C-x ( ++@kindex C-x ) ++@kindex C-x e ++@findex kmacro-start-macro ++@findex kmacro-end-macro ++ In addition to the @key{F3} and @key{F4} commands described above, ++Emacs also supports an older set of keybindings for defining and ++executing keyboard macros. To begin a macro definition, type @kbd{C-x ++(} (@code{kmacro-start-macro}); as with @key{F3}, a prefix argument ++appends this definition to the last keyboard macro. To end a macro ++definition, type @kbd{C-x )} (@code{kmacro-end-macro}). To execute ++the most recent macro, type @kbd{C-x e} ++(@code{kmacro-end-and-call-macro}). If you enter @kbd{C-x e} while ++defining a macro, the macro is terminated and executed immediately. ++Immediately after typing @kbd{C-x e}, you can type @key{e} repeatedly ++to immediately repeat the macro one or more times. You can also give ++@kbd{C-x e} a repeat argument, just like @key{F4}. ++ ++ @kbd{C-x )} can be given a repeat count as an argument. This means ++to repeat the macro right after defining it. The macro definition ++itself counts as the first repetition, since it is executed as you ++define it, so @kbd{C-u 4 C-x )} executes the macro immediately 3 ++additional times. ++ ++@node Keyboard Macro Ring ++@section The Keyboard Macro Ring ++ ++ All defined keyboard macros are recorded in the @dfn{keyboard macro ++ring}. There is only one keyboard macro ring, shared by all buffers. ++ ++@table @kbd ++@item C-x C-k C-k ++Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}). ++@item C-x C-k C-n ++Rotate the keyboard macro ring to the next macro (defined earlier) ++(@code{kmacro-cycle-ring-next}). ++@item C-x C-k C-p ++Rotate the keyboard macro ring to the previous macro (defined later) ++(@code{kmacro-cycle-ring-previous}). ++@end table ++ ++ All commands which operate on the keyboard macro ring use the ++same @kbd{C-x C-k} prefix. Most of these commands can be executed and ++repeated immediately after each other without repeating the @kbd{C-x ++C-k} prefix. For example, ++ ++@example ++C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d ++@end example ++ ++@noindent ++will rotate the keyboard macro ring to the ``second previous'' macro, ++execute the resulting head macro three times, rotate back to the ++original head macro, execute that once, rotate to the ``previous'' ++macro, execute that, and finally delete it from the macro ring. ++ ++@findex kmacro-end-or-call-macro-repeat ++@kindex C-x C-k C-k ++ The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat}) ++executes the keyboard macro at the head of the macro ring. You can ++repeat the macro immediately by typing another @kbd{C-k}, or you can ++rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}. ++ ++ When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves ++like @key{F4} except that, immediately afterward, you can use most key ++bindings of this section without the @kbd{C-x C-k} prefix. For ++instance, another @kbd{C-k} will re-execute the macro. ++ ++@findex kmacro-cycle-ring-next ++@kindex C-x C-k C-n ++@findex kmacro-cycle-ring-previous ++@kindex C-x C-k C-p ++ The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and ++@kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotate the ++macro ring, bringing the next or previous keyboard macro to the head ++of the macro ring. The definition of the new head macro is displayed ++in the echo area. You can continue to rotate the macro ring ++immediately by repeating just @kbd{C-n} and @kbd{C-p} until the ++desired macro is at the head of the ring. To execute the new macro ++ring head immediately, just type @kbd{C-k}. ++ ++ Note that Emacs treats the head of the macro ring as the ``last ++defined keyboard macro.'' For instance, @key{F4} will execute that ++macro, and @kbd{C-x C-k n} will give it a name. ++ ++@vindex kmacro-ring-max ++ The maximum number of macros stored in the keyboard macro ring is ++determined by the customizable variable @code{kmacro-ring-max}. ++ ++@node Keyboard Macro Counter ++@section The Keyboard Macro Counter ++ ++ Each keyboard macro has an associated counter, which is initialized ++to 0 when you start defining the macro. This counter allows you to ++insert a number into the buffer that depends on the number of times ++the macro has been called. The counter is incremented each time its ++value is inserted into the buffer. ++ ++@table @kbd ++@item @key{F3} ++In a keyboard macro definition, insert the keyboard macro counter ++value in the buffer (@code{kmacro-start-macro-or-insert-counter}). ++@item C-x C-k C-i ++Insert the keyboard macro counter value in the buffer ++(@code{kmacro-insert-counter}). ++@item C-x C-k C-c ++Set the keyboard macro counter (@code{kmacro-set-counter}). ++@item C-x C-k C-a ++Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}). ++@item C-x C-k C-f ++Specify the format for inserting the keyboard macro counter ++(@code{kmacro-set-format}). ++@end table ++ ++@findex kmacro-insert-counter ++@kindex C-x C-k C-i ++ When you are defining a keyboard macro, the command @key{F3} ++(@code{kmacro-start-macro-or-insert-counter}) inserts the current ++value of the keyboard macro's counter into the buffer, and increments ++the counter by 1. (If you are not defining a macro, @key{F3} begins a ++macro definition instead. @xref{Basic Keyboard Macro}.) You can use ++a numeric prefix argument to specify a different increment. If you ++just specify a @kbd{C-u} prefix, that is the same as an increment of ++zero: it inserts the current counter value without changing it. ++ ++ As an example, let us show how the keyboard macro counter can be ++used to build a numbered list. Consider the following key sequence: ++ ++@example ++@key{F3} C-a @key{F3} . @key{SPC} @key{F4} ++@end example ++ ++@noindent ++As part of this keyboard macro definition, the string @samp{0. } was ++inserted into the beginning of the current line. If you now move ++somewhere else in the buffer and type @key{F4} to invoke the macro, ++the string @samp{1. } is inserted at the beginning of that line. ++Subsequent invocations insert @samp{2. }, @samp{3. }, and so forth. ++ ++ The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) does ++the same thing as @key{F3}, but it can be used outside a keyboard ++macro definition. When no keyboard macro is being defined or ++executed, it inserts and increments the counter of the macro at the ++head of the keyboard macro ring. ++ ++@findex kmacro-set-counter ++@kindex C-x C-k C-c ++ The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) sets the ++current macro counter to the value of the numeric argument. If you use ++it inside the macro, it operates on each repetition of the macro. If ++you specify just @kbd{C-u} as the prefix, while executing the macro, ++that resets the counter to the value it had at the beginning of the ++current repetition of the macro (undoing any increments so far in this ++repetition). ++ ++@findex kmacro-add-counter ++@kindex C-x C-k C-a ++ The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the ++prefix argument to the current macro counter. With just @kbd{C-u} as ++argument, it resets the counter to the last value inserted by any ++keyboard macro. (Normally, when you use this, the last insertion ++will be in the same macro and it will be the same counter.) ++ ++@findex kmacro-set-format ++@kindex C-x C-k C-f ++ The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts for ++the format to use when inserting the macro counter. The default ++format is @samp{%d}, which means to insert the number in decimal ++without any padding. You can exit with empty minibuffer to reset the ++format to this default. You can specify any format string that the ++@code{format} function accepts and that makes sense with a single ++integer extra argument (@pxref{Formatting Strings,,, elisp, The Emacs ++Lisp Reference Manual}). Do not put the format string inside double ++quotes when you insert it in the minibuffer. ++ ++ If you use this command while no keyboard macro is being defined or ++executed, the new format affects all subsequent macro definitions. ++Existing macros continue to use the format in effect when they were ++defined. If you set the format while defining a keyboard macro, this ++affects the macro being defined from that point on, but it does not ++affect subsequent macros. Execution of the macro will, at each step, ++use the format in effect at that step during its definition. Changes ++to the macro format during execution of a macro, like the ++corresponding changes during its definition, have no effect on ++subsequent macros. ++ ++ The format set by @kbd{C-x C-k C-f} does not affect insertion of ++numbers stored in registers. ++ ++ If you use a register as a counter, incrementing it on each ++repetition of the macro, that accomplishes the same thing as a ++keyboard macro counter. @xref{RegNumbers}. For most purposes, it is ++simpler to use a keyboard macro counter. ++ ++@node Keyboard Macro Query ++@section Executing Macros with Variations ++ ++ In a keyboard macro, you can create an effect similar to that of ++@code{query-replace}, in that the macro asks you each time around ++whether to make a change. ++ ++@table @kbd ++@item C-x q ++When this point is reached during macro execution, ask for confirmation ++(@code{kbd-macro-query}). ++@end table ++ ++@kindex C-x q ++@findex kbd-macro-query ++ While defining the macro, type @kbd{C-x q} at the point where you ++want the query to occur. During macro definition, the @kbd{C-x q} ++does nothing, but when you run the macro later, @kbd{C-x q} asks you ++interactively whether to continue. ++ ++ The valid responses when @kbd{C-x q} asks are: ++ ++@table @asis ++@item @key{SPC} (or @kbd{y}) ++Continue executing the keyboard macro. ++ ++@item @key{DEL} (or @kbd{n}) ++Skip the remainder of this repetition of the macro, and start right ++away with the next repetition. ++ ++@item @key{RET} (or @kbd{q}) ++Skip the remainder of this repetition and cancel further repetitions. ++ ++@item @kbd{C-r} ++Enter a recursive editing level, in which you can perform editing ++which is not part of the macro. When you exit the recursive edit ++using @kbd{C-M-c}, you are asked again how to continue with the ++keyboard macro. If you type a @key{SPC} at this time, the rest of the ++macro definition is executed. It is up to you to leave point and the ++text in a state such that the rest of the macro will do what you want. ++@end table ++ ++ @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, ++performs a completely different function. It enters a recursive edit ++reading input from the keyboard, both when you type it during the ++definition of the macro, and when it is executed from the macro. During ++definition, the editing you do inside the recursive edit does not become ++part of the macro. During macro execution, the recursive edit gives you ++a chance to do some particularized editing on each repetition. ++@xref{Recursive Edit}. ++ ++@node Save Keyboard Macro ++@section Naming and Saving Keyboard Macros ++ ++@table @kbd ++@item C-x C-k n ++Give a command name (for the duration of the Emacs session) to the most ++recently defined keyboard macro (@code{kmacro-name-last-macro}). ++@item C-x C-k b ++Bind the most recently defined keyboard macro to a key sequence (for ++the duration of the session) (@code{kmacro-bind-to-key}). ++@item M-x insert-kbd-macro ++Insert in the buffer a keyboard macro's definition, as Lisp code. ++@end table ++ ++@cindex saving keyboard macros ++@findex kmacro-name-last-macro ++@kindex C-x C-k n ++ If you wish to save a keyboard macro for later use, you can give it ++a name using @kbd{C-x C-k n} (@code{kmacro-name-last-macro}). ++This reads a name as an argument using the minibuffer and defines that ++name to execute the last keyboard macro, in its current form. (If you ++later add to the definition of this macro, that does not alter the ++name's definition as a macro.) The macro name is a Lisp symbol, and ++defining it in this way makes it a valid command name for calling with ++@kbd{M-x} or for binding a key to with @code{global-set-key} ++(@pxref{Keymaps}). If you specify a name that has a prior definition ++other than a keyboard macro, an error message is shown and nothing is ++changed. ++ ++@cindex binding keyboard macros ++@findex kmacro-bind-to-key ++@kindex C-x C-k b ++ You can also bind the last keyboard macro (in its current form) to a ++key, using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the ++key sequence you want to bind. You can bind to any key sequence in ++the global keymap, but since most key sequences already have other ++bindings, you should select the key sequence carefully. If you try to ++bind to a key sequence with an existing binding (in any keymap), this ++command asks you for confirmation before replacing the existing binding. ++ ++ To avoid problems caused by overriding existing bindings, the key ++sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A} ++through @kbd{C-x C-k Z} are reserved for your own keyboard macro ++bindings. In fact, to bind to one of these key sequences, you only ++need to type the digit or letter rather than the whole key sequences. ++For example, ++ ++@example ++C-x C-k b 4 ++@end example ++ ++@noindent ++will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}. ++ ++@findex insert-kbd-macro ++ Once a macro has a command name, you can save its definition in a file. ++Then it can be used in another editing session. First, visit the file ++you want to save the definition in. Then use this command: ++ ++@example ++M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} ++@end example ++ ++@noindent ++This inserts some Lisp code that, when executed later, will define the ++same macro with the same definition it has now. (You need not ++understand Lisp code to do this, because @code{insert-kbd-macro} writes ++the Lisp code for you.) Then save the file. You can load the file ++later with @code{load-file} (@pxref{Lisp Libraries}). If the file you ++save in is your init file @file{~/.emacs} (@pxref{Init File}) then the ++macro will be defined each time you run Emacs. ++ ++ If you give @code{insert-kbd-macro} a numeric argument, it makes ++additional Lisp code to record the keys (if any) that you have bound ++to @var{macroname}, so that the macro will be reassigned the same keys ++when you load the file. ++ ++@node Edit Keyboard Macro ++@section Editing a Keyboard Macro ++ ++@table @kbd ++@item C-x C-k C-e ++Edit the last defined keyboard macro (@code{kmacro-edit-macro}). ++@item C-x C-k e @var{name} @key{RET} ++Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}). ++@item C-x C-k l ++Edit the last 300 keystrokes as a keyboard macro ++(@code{kmacro-edit-lossage}). ++@end table ++ ++@findex kmacro-edit-macro ++@kindex C-x C-k C-e ++@kindex C-x C-k RET ++ You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or ++@kbd{C-x C-k RET} (@code{kmacro-edit-macro}). This formats the macro ++definition in a buffer and enters a specialized major mode for editing ++it. Type @kbd{C-h m} once in that buffer to display details of how to ++edit the macro. When you are finished editing, type @kbd{C-c C-c}. ++ ++@findex edit-kbd-macro ++@kindex C-x C-k e ++ You can edit a named keyboard macro or a macro bound to a key by typing ++@kbd{C-x C-k e} (@code{edit-kbd-macro}). Follow that with the ++keyboard input that you would use to invoke the macro---@kbd{C-x e} or ++@kbd{M-x @var{name}} or some other key sequence. ++ ++@findex kmacro-edit-lossage ++@kindex C-x C-k l ++ You can edit the last 300 keystrokes as a macro by typing ++@kbd{C-x C-k l} (@code{kmacro-edit-lossage}). ++ ++@node Keyboard Macro Step-Edit ++@section Stepwise Editing a Keyboard Macro ++ ++@findex kmacro-step-edit-macro ++@kindex C-x C-k SPC ++ You can interactively replay and edit the last keyboard ++macro, one command at a time, by typing @kbd{C-x C-k SPC} ++(@code{kmacro-step-edit-macro}). Unless you quit the macro using ++@kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the ++macro ring. ++ ++ This macro editing feature shows the last macro in the minibuffer ++together with the first (or next) command to be executed, and prompts ++you for an action. You can enter @kbd{?} to get a summary of your ++options. These actions are available: ++ ++@itemize @bullet{} ++@item ++@kbd{SPC} and @kbd{y} execute the current command, and advance to the ++next command in the keyboard macro. ++@item ++@kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command. ++@item ++@kbd{f} skips the current command in this execution of the keyboard ++macro, but doesn't delete it from the macro. ++@item ++@kbd{@key{TAB}} executes the current command, as well as all similar ++commands immediately following the current command; for example, @key{TAB} ++may be used to insert a sequence of characters (corresponding to a ++sequence of @code{self-insert-command} commands). ++@item ++@kbd{c} continues execution (without further editing) until the end of ++the keyboard macro. If execution terminates normally, the edited ++macro replaces the original keyboard macro. ++@item ++@kbd{C-k} skips and deletes the rest of the keyboard macro, ++terminates step-editing, and replaces the original keyboard macro ++with the edited macro. ++@item ++@kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro; ++discarding any changes made to the keyboard macro. ++@item ++@kbd{i KEY... C-j} reads and executes a series of key sequences (not ++including the final @kbd{C-j}), and inserts them before the current ++command in the keyboard macro, without advancing over the current ++command. ++@item ++@kbd{I KEY...} reads one key sequence, executes it, and inserts it ++before the current command in the keyboard macro, without advancing ++over the current command. ++@item ++@kbd{r KEY... C-j} reads and executes a series of key sequences (not ++including the final @kbd{C-j}), and replaces the current command in ++the keyboard macro with them, advancing over the inserted key ++sequences. ++@item ++@kbd{R KEY...} reads one key sequence, executes it, and replaces the ++current command in the keyboard macro with that key sequence, ++advancing over the inserted key sequence. ++@item ++@kbd{a KEY... C-j} executes the current command, then reads and ++executes a series of key sequences (not including the final ++@kbd{C-j}), and inserts them after the current command in the keyboard ++macro; it then advances over the current command and the inserted key ++sequences. ++@item ++@kbd{A KEY... C-j} executes the rest of the commands in the keyboard ++macro, then reads and executes a series of key sequences (not ++including the final @kbd{C-j}), and appends them at the end of the ++keyboard macro; it then terminates the step-editing and replaces the ++original keyboard macro with the edited macro. ++@end itemize ++ ++@ignore ++ arch-tag: c1b0dd3b-3159-4c08-928f-52e763953e9c ++@end ignore +diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi +new file mode 100644 +index 0000000..1cd98a0 +--- /dev/null ++++ b/doc/emacs/m-x.texi +@@ -0,0 +1,75 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node M-x, Help, Minibuffer, Top ++@chapter Running Commands by Name ++ ++ Every Emacs command has a name that you can use to run it. For ++convenience, many commands also have key bindings. You can run those ++commands by typing the keys, or run them by name. Most Emacs commands ++have no key bindings, so the only way to run them is by name. ++(@xref{Key Bindings}, for how to set up key bindings.) ++ ++ By convention, a command name consists of one or more words, ++separated by hyphens; for example, @code{auto-fill-mode} or ++@code{manual-entry}. Command names mostly use complete English words ++to make them easier to remember. ++ ++@kindex M-x ++ To run a command by name, start with @kbd{M-x}, type the command ++name, then terminate it with @key{RET}. @kbd{M-x} uses the minibuffer ++to read the command name. The string @samp{M-x} appears at the ++beginning of the minibuffer as a @dfn{prompt} to remind you to enter a ++command name to be run. @key{RET} exits the minibuffer and runs the ++command. @xref{Minibuffer}, for more information on the minibuffer. ++ ++ You can use completion to enter the command name. For example, ++to invoke the command @code{forward-char}, you can type ++ ++@example ++M-x forward-char @key{RET} ++@end example ++ ++@noindent ++or ++ ++@example ++M-x forw @key{TAB} c @key{RET} ++@end example ++ ++@noindent ++Note that @code{forward-char} is the same command that you invoke with ++the key @kbd{C-f}. The existence of a key binding does not stop you ++from running the command by name. ++ ++ To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead ++of entering the command name. This takes you back to command level. ++ ++ To pass a numeric argument to the command you are invoking with ++@kbd{M-x}, specify the numeric argument before @kbd{M-x}. The ++argument value appears in the prompt while the command name is being ++read, and finally @kbd{M-x} passes the argument to that command. ++ ++@vindex suggest-key-bindings ++ When the command you run with @kbd{M-x} has a key binding, Emacs ++mentions this in the echo area after running the command. For ++example, if you type @kbd{M-x forward-word}, the message says that you ++can run the same command by typing @kbd{M-f}. You can turn off these ++messages by setting the variable @code{suggest-key-bindings} to ++@code{nil}. ++ ++ In this manual, when we speak of running a command by name, we often ++omit the @key{RET} that terminates the name. Thus we might say ++@kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode ++@key{RET}}. We mention the @key{RET} only for emphasis, such as when ++the command is followed by arguments. ++ ++@findex execute-extended-command ++ @kbd{M-x} works by running the command ++@code{execute-extended-command}, which is responsible for reading the ++name of another command and invoking it. ++ ++@ignore ++ arch-tag: b67bff53-9628-4666-b94e-eda972a7ba56 ++@end ignore +diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi +new file mode 100644 +index 0000000..3fd070a +--- /dev/null ++++ b/doc/emacs/macos.texi +@@ -0,0 +1,236 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, ++@c 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Mac OS / GNUstep, Microsoft Windows, Antinews, Top ++@appendix Emacs and Mac OS / GNUstep ++@cindex Mac OS X ++@cindex Macintosh ++@cindex GNUstep ++ ++ This section briefly describes the peculiarities of using Emacs built with ++the GNUstep libraries on GNU/Linux or other operating systems, or on Mac OS X ++with native window system support. For Mac OS X, Emacs can be built either ++without window system support, with X11, or with the Cocoa interface. This ++section only applies to the Cocoa build. Emacs 23 does not support Mac OS ++Classic. ++ ++ Emacs, when built on Mac OS X, uses the Cocoa application interface. ++For historical and technical reasons, Emacs uses the term ++@samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for ++instance, most of the commands and variables described in the ++following sections begin with @samp{ns-}, which is short for ++@samp{Nextstep}. NeXTstep was an application interface released by ++NeXT Inc during the 1980s, of which Cocoa is a direct descendant. ++Apart from Cocoa, there is one other NeXTstep-style system: GNUstep, ++which is free software. At the moment, Emacs has only incomplete ++support for GNUstep (@pxref{GNUstep Support}). ++ ++ As of the 23.1 release, Emacs is not as stable on Cocoa as on other ++platforms. We hope to improve this in future releases. ++ ++@menu ++* Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or Mac OS. ++* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS. ++* Mac / GNUstep Events:: How window system events are handled. ++* GNUstep Support:: Details on status of GNUstep support. ++@end menu ++ ++@node Mac / GNUstep Basics, Mac / GNUstep Customization, , Mac OS / GNUstep ++@section Basic Emacs usage under Mac OS and GNUstep ++ ++ By default, the @key{alt} and @key{option} keys are the same as ++@key{Meta} when running under Mac OS. The Mac @key{Cmd} key is the ++same as @key{Super}, and Emacs provides a set of keybindings using ++this modifier key that mimic other Mac / GNUstep applications (@pxref{Mac / ++GNUstep Events}). You can change these bindings in the usual way (@pxref{Key ++Bindings}). ++ ++ The standard Mac / GNUstep font and color panels are accessible via Lisp commands. ++ To use the color panel, drag from it to an Emacs frame to change the ++foreground color of the face at that position (if the @key{shift} key ++is held down, it changes the background color instead). To discard the ++settings, create a new frame and close the altered one. ++@c [unclear if the following holds.] ++@c To finalize the settings for either color or font, choose @samp{Save Options} in the @samp{Options} menu. ++ ++ @key{S-Mouse-1} (i.e., clicking the left mouse button ++while holding down the @key{Shift} key) adjusts the region to the ++click position, just like @key{Mouse-3} (@code{mouse-save-then-kill}); ++it does not pop up a menu for changing the default face, as ++@key{S-Mouse-1} normally does (@pxref{Temporary Face Changes}). This ++change makes Emacs behave more like other Mac / GNUstep applications. ++ ++ When you open or save files using the menus, or using the ++@key{Cmd-o} and @key{Cmd-S} bindings, Emacs uses graphical file ++dialogs to read file names. However, if you use the regular Emacs key ++sequences, such as @key{C-x C-f}, Emacs uses the minibuffer to read ++file names. ++ ++ On GNUstep, in an X-windows environment you need to use @key{Cmd-c} ++instead of one of the @key{C-w} or @key{M-w} commands to transfer text ++to the X primary selection; otherwise, Emacs will use the ++``clipboard'' selection. Likewise, @key{Cmd-y} (instead of @key{C-y}) ++yanks from the X primary selection instead of the kill-ring or ++clipboard. ++ ++ ++@subsection Grabbing environment variables ++ ++@c How is this any different to launching from a window manager menu ++@c in GNU/Linux? These are sometimes not login shells either. ++Many programs which may run under Emacs, like latex or man, depend on the ++settings of environment variables. If Emacs is launched from the shell, it ++will automatically inherit these environment variables and its subprocesses ++will inherit them from it. But if Emacs is launched from the Finder it ++is not a descendant of any shell, so its environment variables haven't been ++set, which often causes the subprocesses it launches to behave differently than ++they would when launched from the shell. ++ ++For the PATH and MANPATH variables, a system-wide method ++of setting PATH is recommended on Mac OS X 10.5 and later, using the ++@file{/etc/paths} files and the @file{/etc/paths.d} directory. ++ ++@node Mac / GNUstep Customization, Mac / GNUstep Events, Mac / GNUstep Basics, Mac OS / GNUstep ++@section Mac / GNUstep Customization ++ ++Emacs can be customized in several ways in addition to the standard ++customization buffers and the Options menu. ++ ++ ++@subsection Font and Color Panels ++ ++The Font Panel may be accessed with M-x ns-popup-font-panel. It ++will set the default font in the frame most recently used or clicked ++on. ++ ++@c To make the setting permanent, use @samp{Save Options} in the ++@c Options menu, or run @code{menu-bar-options-save}. ++ ++You can bring up a color panel with M-x ns-popup-color-panel. and ++drag the color you want over the emacs face you want to change. Normal ++dragging will alter the foreground color. Shift dragging will alter the ++background color. ++ ++@c To make the changes permanent select the "Save Options" ++@c item in the "Options" menu, or run @code{menu-bar-options-save}. ++ ++Useful in this context is the listing of all faces obtained by @key{M-x} ++@code{list-faces-display}. ++ ++@subsection Open files by dragging to an Emacs window ++ ++The default behaviour when a user drags files from another application ++into an Emacs frame is to insert the contents of all the dragged files ++into the current buffer. To remap the @code{ns-drag-file} event to ++open the dragged files in the current frame use the following line: ++ ++@lisp ++(define-key global-map [ns-drag-file] 'ns-find-file) ++@end lisp ++ ++ ++@node Mac / GNUstep Events, GNUstep Support, Mac / GNUstep Customization, Mac OS / GNUstep ++@section Windowing System Events under Mac OS / GNUstep ++ ++ Nextstep applications receive a number of special events which have ++no X equivalent. These are sent as specially defined ``keys'', which ++do not correspond to any sequence of keystrokes. Under Emacs, these ++``key'' events can be bound to functions just like ordinary ++keystrokes. Here is a list of these events. ++ ++@table @key ++@item ns-open-file ++@vindex ns-pop-up-frames ++This event occurs when another Nextstep application requests that ++Emacs open a file. A typical reason for this would be a user ++double-clicking a file in the Finder application. By default, Emacs ++responds to this event by opening a new frame and visiting the file in ++that frame (@code{ns-find-file}). As an exception, if the selected ++buffer is the @samp{*scratch*} buffer, Emacs visits the file in the ++selected frame. ++ ++You can change how Emacs responds to @key{ns-open-file} by changing ++the variable @code{ns-pop-up-frames}. Its default value, ++@code{'fresh}, is what we have just described. A value of @code{t} ++means to always visit the file in a new frame. A value of @code{nil} ++means to always visit the file in an existing frame. ++ ++@item ns-open-temp-file ++This event occurs when another application requests that Emacs open a ++temporary file. By default, this is handled by just generating a ++@code{ns-open-file} event, the results of which are described above. ++ ++You can bind @key{ns-pop-up-frames} and @key{ns-open-temp-file} to ++other Lisp functions. When the event is registered, the name of the ++file to open is stored in the variable @code{ns-input-file}. ++ ++@item ns-open-file-line ++Some applications, such as ProjectBuilder and gdb, request not only a ++particular file, but also a particular line or sequence of lines in ++the file. Emacs handles this by visiting that file and highlighting ++the requested line (@code{ns-open-file-select-line}). ++ ++@item ns-drag-file ++This event occurs when a user drags files from another application ++into an Emacs frame. The default behavior is to insert the contents ++of all the dragged files into the current buffer ++(@code{ns-insert-files}). The list of dragged files is stored in the ++variable @code{ns-input-file}. ++ ++@item ns-drag-color ++This event occurs when a user drags a color from the color well (or ++some other source) into an Emacs frame. The default behavior is to ++alter the foreground color of the area the color was dragged onto ++(@code{ns-set-foreground-at-mouse}). If this event is issued with a ++@key{Shift} modifier, Emacs changes the background color instead ++(@code{ns-set-background-at-mouse}). The name of the dragged color is ++stored in the variable @code{ns-input-color}. ++ ++@item ns-change-font ++This event occurs when the user selects a font in a Nextstep font ++panel (which can be opened with @kbd{Cmd-t}). The default behavior is ++to adjust the font of the selected frame ++(@code{ns-respond-to-changefont}). The name and size of the selected ++font are stored in the variables @code{ns-input-font} and ++@code{ns-input-fontsize}, respectively. ++ ++@item ns-power-off ++This event occurs when the user logs out and Emacs is still running, or when ++`Quit Emacs' is chosen from the application menu. ++The default behavior is to save all file-visiting buffers. ++@end table ++ ++ Emacs also allows users to make use of Nextstep services, via a set ++of commands whose names begin with @samp{ns-service-} and end with the ++name of the service. Type @kbd{M-x ns-service-@key{TAB}@key{TAB}} to ++see a list of these commands. These functions either operate on ++marked text (replacing it with the result) or take a string argument ++and return the result as a string. You can also use the Lisp function ++@code{ns-perform-service} to pass arbitrary strings to arbitrary ++services and receive the results back. Note that you may need to ++restart Emacs to access newly-available services. ++ ++ ++@node GNUstep Support, , Mac / GNUstep Events, Mac OS / GNUstep ++@section GNUstep Support ++ ++Emacs can be built and run under GNUstep, however there are still some ++issues to be addressed. Interested developers should contact ++@email{emacs-devel@@gnu.org}. ++ ++@c Presumably no longer relevant since CANNOT_DUMP removed 2009-05-06: ++@ignore ++In particular, it may be necessary to run @samp{make bootstrap} with a ++plain X configuration, then @samp{make clean} and @samp{./configure ++--with-ns} followed by @samp{make install}. ++ ++Currently CANNOT_DUMP is automatically enabled in GNUstep configurations, ++because the unex file(s) for GNUstep, mainly @samp{unexelf.c}, have not been ++updated yet with the ``zone'' code in and related to @samp{unexmacosx.c}. ++@end ignore ++ ++ ++@ignore ++ arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6 ++@end ignore +diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi +new file mode 100644 +index 0000000..114e2d0 +--- /dev/null ++++ b/doc/emacs/maintaining.texi +@@ -0,0 +1,2226 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, ++@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Maintaining, Abbrevs, Building, Top ++@chapter Maintaining Large Programs ++ ++ This chapter describes Emacs features for maintaining large ++programs. ++ ++@menu ++* Version Control:: Using version control systems. ++* Change Log:: Maintaining a change history for your program. ++* Tags:: Go directly to any function in your program in one ++ command. Tags remembers which file it is in. ++@ifnottex ++* Emerge:: A convenient way of merging two versions of a program. ++@end ifnottex ++@end menu ++ ++@node Version Control ++@section Version Control ++@cindex version control ++ ++ A @dfn{version control system} is a package that can record multiple ++versions of a source file, storing information such as the creation ++time of each version, who created it, and a description of what was ++changed in that version. ++ ++ The Emacs version control interface is called VC. Its commands work ++with several different version control systems; currently, it supports ++GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and ++Subversion. Of these, the GNU project distributes CVS, GNU Arch, RCS, ++and Bazaar. ++ ++ VC is enabled automatically whenever you visit a file that is ++governed by a version control system. To disable VC entirely, set the ++customizable variable @code{vc-handled-backends} to @code{nil} ++@iftex ++(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). ++@end iftex ++@ifnottex ++(@pxref{Customizing VC}). ++@end ifnottex ++ ++@menu ++* Introduction to VC:: How version control works in general. ++* VC Mode Line:: How the mode line shows version control status. ++* Basic VC Editing:: How to edit a file under version control. ++* Old Revisions:: Examining and comparing old versions. ++* Secondary VC Commands:: The commands used a little less frequently. ++* VC Directory Mode:: Listing files managed by version control. ++* Branches:: Multiple lines of development. ++@ifnottex ++* Remote Repositories:: Efficient access to remote CVS servers. ++* Revision Tags:: Symbolic names for revisions. ++* Miscellaneous VC:: Various other commands and features of VC. ++* Customizing VC:: Variables that change VC's behavior. ++@end ifnottex ++@end menu ++ ++@node Introduction to VC ++@subsection Introduction to Version Control ++ ++ VC allows you to use a version control system from within Emacs, ++integrating the version control operations smoothly with editing. ++Though VC cannot completely bridge the gaps between version control ++systems with widely differing capabilities, it does provide a uniform ++interface to many version control operations. Regardless of which ++version control system is in use, you will be able to do basic ++operations in much the same way. ++ ++ This section provides a general overview of version control, and ++describes the version control systems that VC supports. You can skip ++this section if you are already familiar with the version control system ++you want to use. ++ ++@menu ++* Why Version Control?:: Understanding the problems it addresses. ++* Version Control Systems:: Supported version control back-end systems. ++* VCS Concepts:: Words and concepts related to version control. ++* Types of Log File:: The VCS log in contrast to the ChangeLog. ++@end menu ++ ++@node Why Version Control? ++@subsubsection Understanding the problems it addresses ++ ++ Version control systems provide you with three important ++capabilities: ++ ++@itemize @bullet ++@item ++@dfn{Reversibility}: the ability to back up to a previous state if you ++discover that some modification you did was a mistake or a bad idea. ++ ++@item ++@dfn{Concurrency}: the ability to have many people modifying the same ++collection of files knowing that conflicting modifications can be ++detected and resolved. ++ ++@item ++@dfn{History}: the ability to attach historical data to your data, ++such as explanatory comments about the intention behind each change to ++it. Even for a programmer working solo, change histories are an ++important aid to memory; for a multi-person project, they are a ++vitally important form of communication among developers. ++@end itemize ++ ++@node Version Control Systems ++@subsubsection Supported Version Control Systems ++ ++@cindex back end (version control) ++ VC currently works with many different version control systems or ++@dfn{back ends}: ++ ++@itemize @bullet ++ ++@cindex SCCS ++@item ++SCCS was the first version control system ever built, and was long ago ++superseded by more advanced ones. VC compensates for certain features ++missing in SCCS (e.g., tag names for releases) by implementing them ++itself. Other VC features, such as multiple branches, are simply ++unavailable. Since SCCS is non-free, we recommend avoiding it. ++ ++@cindex CSSC ++@item ++CSSC is a free replacement for SCCS. You should use CSSC only if, for ++some reason, you cannot use a more recent and better-designed version ++control system. ++ ++@cindex RCS ++@item ++RCS is the free version control system around which VC was initially ++built. Almost everything you can do with RCS can be done through VC. ++However, you cannot use RCS over the network, and it only works at the ++level of individual files rather than projects. ++ ++@cindex CVS ++@item ++CVS is the free version control system that was, until recently (circa ++2008), used by the majority of free software projects. Nowadays, it ++is slowly being superseded by newer systems. CVS allows concurrent ++multi-user development either locally or over the network. It lacks ++support for atomic commits or file moving/renaming. VC supports all ++basic editing operations under CVS. For some less common tasks, you ++still need to call CVS from the command line. Note also that before ++using CVS you must set up a repository, which is a subject too complex ++to treat here. ++ ++@cindex SVN ++@cindex Subversion ++@item ++Subversion (SVN) is a free version control system designed to be ++similar to CVS but without its problems. It supports atomic commits ++of filesets, and versioning of directories, symbolic links, meta-data, ++renames, copies, and deletes. ++ ++@cindex GNU Arch ++@cindex Arch ++@item ++GNU Arch is a version control system designed for distributed work. ++It differs in many ways from older systems like CVS and RCS. It ++provides different methods for interoperating between users, support ++for offline operations, and good branching and merging features. It ++also supports atomic commits of filesets and file moving/renaming. VC ++does not support all operations provided by GNU Arch, so you must ++sometimes invoke it from the command line. ++ ++@cindex git ++@item ++Git is a distributed version control system invented by Linus Torvalds to support ++development of Linux (his kernel). It supports atomic commits of filesets and ++file moving/renaming. One significant feature of git is that it ++largely abolishes the notion of a single centralized repository; ++instead, each working copy of a git project is its own repository and ++coordination is done through repository-sync operations. VC supports ++most git operations, with the exception of news merges and repository ++syncing; these must be done from the command line. ++ ++@cindex hg ++@cindex Mercurial ++@item ++Mercurial (hg) is a distributed version control system broadly ++resembling GNU Arch and git, with atomic fileset commits and file ++moving/renaming. Like git, it is fully decentralized. VC supports ++most Mercurial commands, with the exception of repository sync ++operations; this needs to be done from the command line. ++ ++@cindex bzr ++@cindex Bazaar ++@item ++Bazaar (bzr) is a distributed version control system that supports both ++repository-based and distributed versioning, with atomic fileset ++commits and file moving/renaming. VC supports most basic editing ++operations under Bazaar. ++@end itemize ++ ++ Previous versions of VC supported a version control system known as ++Meta-CVS. This support has been dropped because of limited interest ++from users and developers. ++ ++@node VCS Concepts ++@subsubsection Concepts of Version Control ++ ++@cindex repository ++@cindex registered file ++ When a file is under version control, we say that it is ++@dfn{registered} in the version control system. The system has a ++@dfn{repository} which stores both the file's present state and its ++change history---enough to reconstruct the current version or any ++earlier version. The repository also contains other information, such ++as @dfn{log entries} that describe the changes made to each file. ++ ++@cindex work file ++@cindex checking out files ++ A file @dfn{checked out} of a repository is called the @dfn{work ++file}. You edit the work file and make changes in it, as you would ++with an ordinary file. After you are done with a set of changes, you ++@dfn{check in} or @dfn{commit} the file; this records the changes in ++the repository, along with a log entry for those changes. ++ ++@cindex revision ++@cindex revision ID ++ A copy of a file stored in a repository is called a @dfn{revision}. ++The history of a file is a sequence of revisions. Each revisions is ++named by a @dfn{revision ID}. The format of the revision ID depends ++on the version control system; in the simplest case, it is just an ++integer. ++ ++ To go beyond these basic concepts, you will need to understand three ++aspects in which version control systems differ. ++They can be locking-based or merging-based; they can be file-based or ++changeset-based; and they can be centralized or decentralized. VC ++handles all these modes of operation, but it cannot hide the differences. ++ ++@cindex locking versus merging ++ A version control system typically has some mechanism to coordinate ++between users who want to change the same file. There are two ways to ++do this: merging and locking. ++ ++ In a version control system that uses merging, each user may check ++out and modify a work file at any time. The system lets you ++@dfn{merge} your work file, which may contain changes that have not ++been checked in, with the latest changes that others have checked into ++the repository. ++ ++ Older version control systems use a @dfn{locking} scheme instead. ++Here, work files are normally read-only. To edit a file, you ask the ++version control system to make it writable for you by @dfn{locking} ++it; only one user can lock a given file at any given time. This ++procedure is analogous to, but different from, the locking that Emacs ++uses to detect simultaneous editing of ordinary files ++(@pxref{Interlocking}). When you check in your changes, that unlocks ++the file, and the work file becomes read-only again. Other users may ++then lock the file to make their own changes. ++ ++ Both locking and merging systems can have problems when multiple ++users try to modify the same file at the same time. Locking systems ++have @dfn{lock conflicts}; a user may try to check a file out and be ++unable to because it is locked. In merging systems, @dfn{merge ++conflicts} happen when you check in a change to a file that conflicts ++with a change checked in by someone else after your checkout. Both ++kinds of conflict have to be resolved by human judgment and ++communication. Experience has shown that merging is superior to ++locking, both in convenience to developers and in minimizing the ++number and severity of conflicts that actually occur. ++ ++ SCCS always uses locking. RCS is lock-based by default but can be ++told to operate in a merging style. CVS and Subversion are ++merge-based by default but can be told to operate in a locking mode. ++Distributed version control systems, such as GNU Arch, git, and ++Mercurial, are exclusively merging-based. ++ ++ VC mode supports both locking and merging version control. The ++terms ``checkin'' and ``checkout'' come from locking-based version ++control systems; newer version control systems have slightly different ++operations usually called ``commit'' and ``update'', but VC hides the ++differences between them as much as possible. ++ ++@cindex files versus changesets. ++ On SCCS, RCS, CVS, and other early version control systems, version ++control operations are @dfn{file-based}: each file has its own comment ++and revision history separate from that of all other files in the ++system. Later systems, beginning with Subversion, are ++@dfn{changeset-based}: a checkin may include changes to several files, ++and the entire set of changes is treated as a unit by the system. Any ++comment associated with the change does not belong to a single file, ++but to the changeset itself. ++ ++ Changeset-based version control is more flexible and powerful than ++file-based version control; usually, when a change to multiple files ++has to be reversed, it's good to be able to easily identify and remove ++all of it. ++ ++@cindex centralized vs. decentralized version control ++ Early version control systems were designed around a ++@dfn{centralized} model in which each project has only one repository ++used by all developers. SCCS, RCS, CVS, and Subversion share this ++kind of model. One of its drawbacks is that the repository is a choke ++point for reliability and efficiency. ++ ++ GNU Arch pioneered the concept of @dfn{decentralized} version ++control, later implemented in git, Mercurial, and Bazaar. A project ++may have several different repositories, and these systems support a ++sort of super-merge between repositories that tries to reconcile their ++change histories. At the limit, each developer has his/her own ++repository, and repository merges replace checkin/commit operations. ++ ++ VC's job is to help you manage the traffic between your personal ++workfiles and a repository. Whether that repository is a single ++master or one of a network of peer repositories is not something VC ++has to care about. Thus, the difference between a centralized and a ++decentralized version control system is invisible to VC mode. ++ ++@node Types of Log File ++@subsubsection Types of Log File ++@cindex types of log file ++@cindex log File, types of ++@cindex version control log ++ ++ Projects that use a version control system can have two types of log ++for changes. One is the log maintained by the version control system: ++each time you check in a change, you fill out a @dfn{log entry} for ++the change (@pxref{Log Buffer}). This is called the @dfn{version ++control log}. ++ ++ The other kind of log is the file @file{ChangeLog} (@pxref{Change ++Log}). It provides a chronological record of all changes to a large ++portion of a program---typically one directory and its subdirectories. ++A small program would use one @file{ChangeLog} file; a large program ++may have a @file{ChangeLog} file in each major directory. ++@xref{Change Log}. Programmers have used change logs since long ++before version control systems. ++ ++ Changeset-based version systems typically maintain a changeset-based ++modification log for the entire system, which makes change log files ++somewhat redundant. One advantage that they retain is that it is ++sometimes useful to be able to view the transaction history of a ++single directory separately from those of other directories. ++ ++ A project maintained with version control can use just the version ++control log, or it can use both kinds of logs. It can handle some ++files one way and some files the other way. Each project has its ++policy, which you should follow. ++ ++ When the policy is to use both, you typically want to write an entry ++for each change just once, then put it into both logs. You can write ++the entry in @file{ChangeLog}, then copy it to the log buffer with ++@kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}). Or ++you can write the entry in the log buffer while checking in the ++change, and later use the @kbd{C-x v a} command to copy it to ++@file{ChangeLog} ++@iftex ++(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). ++@end iftex ++@ifnottex ++(@pxref{Change Logs and VC}). ++@end ifnottex ++ ++@node VC Mode Line ++@subsection Version Control and the Mode Line ++ ++ When you visit a file that is under version control, Emacs indicates ++this on the mode line. For example, @samp{RCS-1.3} says that RCS is ++used for that file, and the current version is 1.3. ++ ++ The character between the back-end name and the revision ID ++indicates the version control status of the file. @samp{-} means that ++the work file is not locked (if locking is in use), or not modified (if ++locking is not in use). @samp{:} indicates that the file is locked, or ++that it is modified. If the file is locked by some other user (for ++instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. ++ ++ On a graphical display, you can move the mouse over this mode line ++indicator to pop up a ``tool-tip'', which displays a more verbose ++description of the version control status. Pressing @kbd{Mouse-1} ++over the indicator pops up a menu of VC commands. This menu is ++identical to the @samp{Tools / Version Control} menu item. ++ ++@vindex auto-revert-check-vc-info ++ When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is ++under version control, it updates the version control information in ++the mode line. However, Auto Revert mode may not properly update this ++information if the version control status changes without changes to ++the work file, from outside the current Emacs session. If you set ++@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates ++the version control status information every ++@code{auto-revert-interval} seconds, even if the work file itself is ++unchanged. The resulting CPU usage depends on the version control ++system, but is usually not excessive. ++ ++@node Basic VC Editing ++@subsection Basic Editing under Version Control ++ ++@cindex filesets, VC ++ Most VC commands operate on @dfn{VC filesets}. A VC fileset is a ++collection of one or more files that a VC operation acts on. When you ++type VC commands in a buffer visiting a version-controlled file, the ++VC fileset is simply that one file. When you type them in a VC ++Directory buffer, and some files in it are marked, the VC fileset ++consists of the marked files (@pxref{VC Directory Mode}). ++ ++ The principal VC command is an all-purpose command, @kbd{C-x v v} ++(@code{vc-next-action}), that performs either locking, merging or a ++check-in (depending on the situation) on the current VC fileset. You ++can use @kbd{C-x v v} in a file-visiting buffer or in a VC Directory ++buffer. ++ ++@table @kbd ++@itemx C-x v v ++Perform the appropriate next version control operation on the VC fileset. ++@end table ++ ++@findex vc-next-action ++@kindex C-x v v ++ The precise action of @kbd{C-x v v} depends on the state of the VC ++fileset, and whether the version control system uses locking or ++merging. This is described in detail in the subsequent sections. ++ ++ VC filesets are the way that VC mode bridges the gap between ++file-based and changeset-based version control systems. They are, ++essentially, a way to pass multiple file arguments as a group to ++version control commands. For example, on Subversion, a checkin with ++a multi-file VC fileset becomes a joint commit, as though you had ++typed @command{svn commit} with those file arguments at the shell ++command line. All files in a VC fileset must be under the same ++version control system; if they are not, Emacs signals an error when ++you attempt to execute a command on the fileset. ++ ++ Support for VC filesets and changeset-based version control systems ++is the main improvement to VC in Emacs 23. When you mark multi-file ++VC in a VC Directory buffer, VC operations treat them as a VC fileset, ++and operate on them all at once if the version control system is ++changeset-based. @xref{VC Directory Mode}. ++ ++ VC filesets are distinct from the ``named filesets'' used for ++viewing and visiting files in functional groups (@pxref{Filesets}). ++Unlike named filesets, VC filesets are not named and don't persist ++across sessions. ++ ++@menu ++* VC With A Merging VCS:: Without locking: default mode for CVS. ++* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. ++* Advanced C-x v v:: Advanced features available with a prefix argument. ++* Log Buffer:: Features available in log entry buffers. ++@end menu ++ ++@node VC With A Merging VCS ++@subsubsection Basic Version Control with Merging ++ ++ When your version control system is merging-based (the default for ++CVS and all newer version control systems), work files are always ++writable; you need not do anything special to begin editing a file. ++The status indicator on the mode line is @samp{-} if the file is ++unmodified; it flips to @samp{:} as soon as you save any changes ++(@pxref{VC Mode Line}). ++ ++ Here is what @kbd{C-x v v} does when using a merging-based system: ++ ++@itemize @bullet ++@item ++If the work file is the same as in the repository, it does nothing. ++ ++@item ++If you have not changed the work file, but some other user has checked ++in changes to the repository, @kbd{C-x v v} merges those changes into ++the work file. ++ ++@item ++If you have made modifications to the work file, @kbd{C-x v v} ++attempts to check in your changes. To do this, Emacs first reads the ++log entry for the new revision (@pxref{Log Buffer}). If some other ++user has checked in changes to the repository since you last checked ++it out, the checkin fails. In that case, type @kbd{C-x v v} again to ++merge those changes into your own work file; this puts the work file ++into a ``conflicted'' state. Type @kbd{C-x v v} to clear the ++``conflicted'' state; VC then regards the file as up-to-date and ++modified, and you can try to check it in again. ++ ++To pick up any recent changes from the repository @emph{without} ++trying to commit your own changes, type @kbd{C-x v m @key{RET}}. ++@xref{Merging}. ++@end itemize ++ ++ These rules also apply when you use RCS in its ``non-locking'' mode, ++except that changes will not be automatically merged from the ++repository. Nothing informs you if another user has checked in ++changes in the same file since you began editing it; when you check in ++your revision, his changes are removed (however, they remain in the ++repository and are thus not irrevocably lost). Therefore, you must ++verify that the current revision is unchanged before checking in your ++changes. In addition, locking is possible with RCS even in this mode: ++@kbd{C-x v v} with an unmodified file locks the file, just as it does ++with RCS in its normal locking mode (@pxref{VC With A Locking VCS}). ++ ++@node VC With A Locking VCS ++@subsubsection Basic Version Control with Locking ++ ++ Under a locking-based version control system (such as SCCS, and RCS ++in its default mode), @kbd{C-x v v} does the following: ++ ++ @itemize @bullet ++@item ++If the file is not locked, @kbd{C-x v v} locks it, and makes it ++writable so that you can change it. ++ ++@item ++If the file is locked by you, and contains changes, @kbd{C-x v v} ++checks in the changes. In order to do this, it first reads the log ++entry for the new revision. @xref{Log Buffer}. ++ ++@item ++If the file is locked by you, but you have not changed it since you ++locked it, @kbd{C-x v v} releases the lock and makes the file ++read-only again. ++ ++@item ++If the file is locked by some other user, @kbd{C-x v v} asks you whether ++you want to ``steal the lock'' from that user. If you say yes, the file ++becomes locked by you, but a message is sent to the person who had ++formerly locked the file, to inform him of what has happened. ++@end itemize ++ ++ These rules also apply when you use CVS in locking mode, except ++that there is no such thing as stealing a lock. ++ ++@node Advanced C-x v v ++@subsubsection Advanced Control in @kbd{C-x v v} ++ ++@cindex revision ID to check in/out ++ When you give a prefix argument to @code{vc-next-action} (@kbd{C-u ++C-x v v}), it still performs the next logical version control ++operation, but accepts additional arguments to specify precisely how ++to do the operation. ++ ++@itemize @bullet ++@item ++If the file is modified (or locked), you can specify the revision ID ++to use for the new version that you check in. This is one way ++to create a new branch (@pxref{Branches}). ++ ++@item ++If the file is not modified (and unlocked), you can specify the ++revision to select; this lets you start working from an older ++revision, or on another branch. If you do not enter any revision, ++that takes you to the highest (``head'') revision on the current ++branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to ++get the latest version of a file from the repository. ++ ++@item ++@cindex specific version control system ++Instead of the revision ID, you can also specify the name of a ++version control system. This is useful when one file is being managed ++with two version control systems at the same time ++@iftex ++(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs ++Features}). ++@end iftex ++@ifnottex ++(@pxref{Local Version Control}). ++@end ifnottex ++ ++@end itemize ++ ++@node Log Buffer ++@subsubsection Features of the Log Entry Buffer ++ ++ When you check in changes, Emacs pops up a buffer called ++@samp{*VC-Log*} for you to enter a log entry. ++ ++ After you have finished editing the log message, type @kbd{C-c C-c} ++to exit the buffer and commit the change. ++ ++@findex log-edit-show-files ++@findex log-edit-show-diff ++ In the @samp{*VC-Log*} buffer, typing @kbd{C-c C-f} ++(@code{log-edit-show-files}) displays a list of files in the VC ++fileset you are committing. If you called @kbd{C-x v v} directly from ++a work file, the VC fileset consists of that single file, so this ++command is not very useful. If you called @kbd{C-x v v} from a VC ++directory buffer, the VC fileset may consist of multiple files ++(@pxref{VC Directory Mode}). ++ ++@findex log-edit-insert-changelog ++ Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a ``diff'' of ++the changes you have made (i.e., the differences between the work file ++and the repository revision from which you started editing the file). ++The diff is displayed in a special buffer in another window. ++@xref{Comparing Files}. ++ ++ If you have written an entry in the @file{ChangeLog} (@pxref{Change ++Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull ++it into the @samp{*VC-Log*} buffer. If the topmost item in the ++@file{ChangeLog} was made under your user name on the current date, ++this command searches that item for entries that match the file(s) to ++be committed; if found, these entries are inserted. ++@iftex ++@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, ++@end iftex ++@ifnottex ++@xref{Change Logs and VC}, ++@end ifnottex ++for the opposite way of working---generating ChangeLog entries from ++the revision control log. ++ ++ To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that ++buffer. You can switch buffers and do other editing. As long as you ++don't try to check in another file, the entry you were editing remains ++in the @samp{*VC-Log*} buffer, and you can go back to that buffer at ++any time to complete the check-in. ++ ++ If you change several source files for the same reason, it is often ++convenient to specify the same log entry for many of the files. (This ++is the normal way to do things on a changeset-oriented system, where ++comments are attached to changesets rather than the history of ++individual files.) The most convenient way to do this is to mark all ++the files in VC Directory Mode and check in from there; the log buffer ++will carry the fileset information with it and do a group commit when ++you type @kbd{C-c C-c}. ++ ++ You can also browse the history of previous log entries to duplicate ++a checkin comment. This can be useful when you want several files to ++have checkin comments that vary only slightly from each other. The ++commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this ++work just like the minibuffer history commands (except that these ++versions are used outside the minibuffer). ++ ++@vindex vc-log-mode-hook ++ Each time you check in a change, the log entry buffer is put into VC ++Log Edit mode, which involves running two hooks: @code{text-mode-hook} ++and @code{vc-log-mode-hook}. @xref{Hooks}. ++ ++@node Old Revisions ++@subsection Examining And Comparing Old Revisions ++ ++ One of the convenient features of version control is the ability ++to examine any revision of a file, or compare two revisions. ++ ++@table @kbd ++@item C-x v ~ @var{revision} @key{RET} ++Examine revision @var{revision} of the visited file, in a buffer of its ++own. ++ ++@item C-x v = ++Compare the buffer contents associated with the current ++fileset with the working revision(s) from which you started editing. ++ ++@item C-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} ++Compare the specified two repository revisions of the current fileset. ++ ++@item C-x v g ++Display an annotated version of the file: for each line, show the ++latest revision in which it was modified. ++@end table ++ ++@findex vc-revision-other-window ++@kindex C-x v ~ ++ To examine an old revision, visit the work file and type @kbd{C-x v ++~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). Here, ++@var{revision} is either the desired revision ID (@pxref{VCS ++Concepts}), or the name of a tag or branch ++@iftex ++(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). ++@end iftex ++@ifnottex ++(@pxref{Tags}). ++@end ifnottex ++This command puts the text of the old revision in a file named ++@file{@var{filename}.~@var{revision}~}, and visits it in its own ++buffer in a separate window. ++ ++@findex vc-diff ++@kindex C-x v = ++ @kbd{C-x v =} (@code{vc-diff}) compares the current buffer contents ++of each file in the current VC fileset (saving them if necessary) with ++the repository revision from which you started editing. Note that the ++latter may or may not be the latest revision of the file(s). The diff ++is displayed in a special buffer in another window. @xref{Comparing ++Files}. ++ ++@findex vc-diff ++@kindex C-u C-x v = ++ To compare two arbitrary revisions of the current VC fileset, call ++@code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This ++prompts for two revision IDs, using the minibuffer, and displays the ++diff in a special buffer in another window. Instead of providing a ++revision ID, you can give an empty input, which specifies the current ++contents of the work file; or a tag or branch name ++@iftex ++(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). ++@end iftex ++@ifnottex ++(@pxref{Tags}). ++@end ifnottex ++If your version control system is file-based (e.g. CVS) rather than ++changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a ++revision ID for a multi-file fileset (as opposed to a symbolic tag ++name) is unlikely to return diffs that are connected in any meaningful ++way. ++ ++ If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that ++is neither visiting a version-controlled file nor a VC directory ++buffer, these commands generate a diff of all registered files in the ++current directory and its subdirectories. ++ ++@vindex vc-diff-switches ++@vindex vc-rcs-diff-switches ++ @kbd{C-x v =} works by running a variant of the @code{diff} utility ++designed to work with the version control system in use. The options ++to pass to the @code{diff} command are taken from the first non-@code{nil} ++value of @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, ++and @code{diff-switches} (@pxref{Comparing Files}), in that order. ++Since @code{nil} means to check the next variable in the sequence, ++either of the first two may use the value @code{t} to mean no switches at all. ++Most of the @samp{vc@dots{}diff-switches} variables default to ++@code{nil}, but some default to @code{t}. These are for those version ++control systems (e.g. SVN) whose @code{diff} implementations do not ++accept common options (e.g. @samp{-c}) likely to be in ++@code{diff-switches}. ++ ++ The buffer produced by @kbd{C-x v =} supports the commands of ++Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and ++@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always ++find the corresponding locations in the current work file. (Older ++revisions are not, in general, present as files on your disk.) ++ ++@findex vc-annotate ++@kindex C-x v g ++ For some back ends, you can display the file @dfn{annotated} with ++per-line revision information, by typing @kbd{C-x v g} ++(@code{vc-annotate}). This creates a new buffer (the ``annotate ++buffer'') displaying the file's text, with each part colored to show ++how old it is. Text colored red is new, blue means old, and ++intermediate colors indicate intermediate ages. By default, the color ++is scaled over the full range of ages, such that the oldest changes ++are blue, and the newest changes are red. ++ ++ When you give a prefix argument to this command, Emacs reads two ++arguments using the minibuffer: the ID of which revision to display and ++annotate (instead of the current file contents), and the time span in ++days the color range should cover. ++ ++ From the annotate buffer, these and other color scaling options are ++available from the @samp{VC-Annotate} menu. In this buffer, you can ++also use the following keys to browse the annotations of past revisions, ++view diffs, or view log entries: ++ ++@table @kbd ++@item p ++Annotate the previous revision, that is to say, the revision before ++the one currently annotated. A numeric prefix argument is a repeat ++count, so @kbd{C-u 10 p} would take you back 10 revisions. ++ ++@item n ++Annotate the next revision---the one after the revision currently ++annotated. A numeric prefix argument is a repeat count. ++ ++@item j ++Annotate the revision indicated by the current line. ++ ++@item a ++Annotate the revision before the one indicated by the current line. ++This is useful to see the state the file was in before the change on ++the current line was made. ++ ++@item f ++Show in a buffer the file revision indicated by the current line. ++ ++@item d ++Display the diff between the current line's revision and the previous ++revision. This is useful to see what the current line's revision ++actually changed in the file. ++ ++@item D ++Display the diff between the current line's revision and the previous ++revision for all files in the changeset (for VC systems that support ++changesets). This is useful to see what the current line's revision ++actually changed in the tree. ++ ++@item l ++Show the log of the current line's revision. This is useful to see ++the author's description of the changes in the revision on the current ++line. ++ ++@item w ++Annotate the working revision--the one you are editing. If you used ++@kbd{p} and @kbd{n} to browse to other revisions, use this key to ++return to your working revision. ++ ++@item v ++Toggle the annotation visibility. This is useful for looking just at ++the file contents without distraction from the annotations. ++@end table ++ ++@node Secondary VC Commands ++@subsection The Secondary Commands of VC ++ ++ This section explains the secondary commands of VC. ++ ++@menu ++* Registering:: Putting a file under version control. ++* VC Status:: Viewing the VC status of files. ++* VC Undo:: Canceling changes before or after check-in. ++@end menu ++ ++@node Registering ++@subsubsection Registering a File for Version Control ++ ++@kindex C-x v i ++@findex vc-register ++ You can put any file under version control by simply visiting it, and ++then typing @w{@kbd{C-x v i}} (@code{vc-register}). ++ ++@table @kbd ++@item C-x v i ++Register the visited file for version control. ++@end table ++ ++ To register the file, Emacs must choose which version control system ++to use for it. If the file's directory already contains files ++registered in a version control system, Emacs uses that system. If ++there is more than one system in use for a directory, Emacs uses the ++one that appears first in @code{vc-handled-backends} ++@iftex ++(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). ++@end iftex ++@ifnottex ++(@pxref{Customizing VC}). ++@end ifnottex ++On the other hand, if there are no files already registered, Emacs uses ++the first system from @code{vc-handled-backends} that could register ++the file (for example, you cannot register a file under CVS if its ++directory is not already part of a CVS tree); with the default value ++of @code{vc-handled-backends}, this means that Emacs uses RCS in this ++situation. ++ ++ If locking is in use, @kbd{C-x v i} leaves the file unlocked and ++read-only. Type @kbd{C-x v v} if you wish to start editing it. After ++registering a file with CVS, you must subsequently commit the initial ++revision by typing @kbd{C-x v v}. Until you do that, the revision ID ++appears as @samp{@@@@} in the mode line. ++ ++@vindex vc-default-init-revision ++@cindex initial revision ID to register ++ The default initial revision ID for a newly registered file ++varies by what VCS you are using; normally it will be 1.1 on VCSes ++that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs. ++You can specify a different default by setting the variable ++@code{vc-default-init-revision}, or you can give @kbd{C-x v i} a ++numeric argument; then it reads the initial revision ID for this ++particular file using the minibuffer. ++ ++@vindex vc-initial-comment ++ If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an ++initial comment to describe the purpose of this source file. Reading ++the initial comment works like reading a log entry (@pxref{Log Buffer}). ++ ++@node VC Status ++@subsubsection VC Status Commands ++ ++@table @kbd ++@item C-x v l ++Display revision control state and change history. ++@end table ++ ++@kindex C-x v l ++@findex vc-print-log ++ To view the detailed revision control status and history of a file, ++type @kbd{C-x v l} (@code{vc-print-log}). This pops up a special ++buffer named @samp{*vc-change-log*}, in a new window, that displays ++the history of changes to the current file, including the text of the ++log entries. The point is centered at the revision of the file that ++is currently being visited. ++ ++ In the @samp{*vc-change-log*} buffer, you can use the following keys ++to move between the logs of revisions and of files, to view past ++revisions, to modify change comments, to view annotations and to view ++diffs: ++ ++@table @kbd ++@item p ++Move to the previous revision-item in the buffer. (Revision entries in the log ++buffer are usually in reverse-chronological order, so the previous ++revision-item usually corresponds to a newer revision.) A numeric ++prefix argument is a repeat count. ++ ++@item n ++Move to the next revision-item (which most often corresponds to the ++previous revision of the file). A numeric prefix argument is a repeat ++count. ++ ++@item P ++Move to the log of the previous file, when the logs of multiple files ++are in the log buffer (@pxref{VC Directory Mode}). Otherwise, just ++move to the beginning of the log. A numeric prefix argument is a ++repeat count, so @kbd{C-u 10 P} would move backward 10 files. ++ ++@item N ++Move to the log of the next file, when the logs of multiple files are ++in the log buffer (@pxref{VC Directory Mode}). It also takes a ++numeric prefix argument as a repeat count. ++ ++@item a ++Annotate the revision indicated by the current line. ++ ++@item e ++Modify the change comment displayed at point. Note that not all VC ++systems support modifying change comments. ++ ++@item f ++Visit the revision indicated at the current line, like typing @kbd{C-x ++v ~} and specifying this revision's ID (@pxref{Old Revisions}). ++ ++@item d ++Display the diff (@pxref{Comparing Files}) between the revision ++indicated at the current line and the next earlier revision. This is ++useful to see what actually changed in the file when the revision ++indicated on the current line was committed. ++ ++@item D ++Display the changeset diff (@pxref{Comparing Files}) between the ++revision indicated at the current line and the next earlier revision. ++This is useful to see all the changes to all files that the revision ++indicated on the current line did when it was committed. ++@end table ++ ++@node VC Undo ++@subsubsection Undoing Version Control Actions ++ ++@table @kbd ++@item C-x v u ++Revert the buffer and the file to the working revision from which you started ++editing the file. ++ ++@item C-x v c ++Remove the last-entered change from the master for the visited file. ++This undoes your last check-in. ++@end table ++ ++@kindex C-x v u ++@findex vc-revert-buffer ++ If you want to discard your current set of changes and revert to the ++working revision from which you started editing the file, use @kbd{C-x ++v u} (@code{vc-revert-buffer}). If the version control system is ++locking-based, this leaves the file unlocked, and you must lock it ++again before making new changes. @kbd{C-x v u} requires confirmation, ++unless it sees that you haven't made any changes with respect to the ++master copy of the working revision. ++ ++ @kbd{C-x v u} is also the command to unlock a file if you lock it and ++then decide not to change it. ++ ++@kindex C-x v c ++@findex vc-rollback ++ To cancel a change that you already checked in, use @kbd{C-x v c} ++(@code{vc-rollback}). This command discards all record of the most ++recent checked-in revision, but only if your work file corresponds to ++that revision---you cannot use @kbd{C-x v c} to cancel a revision that ++is not the latest on its branch. Note that many version control ++systems do not support rollback at all; this command is something of a ++historical relic. ++ ++@node VC Directory Mode ++@subsection VC Directory Mode ++ ++@kindex C-x v d ++@findex vc-dir ++ When you are working on a large program, it is often useful to find ++out which files have changed within an entire directory tree, or to ++view the status of all files under version control at once, and to ++perform version control operations on collections of files. You can ++use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory ++listing that includes only files relevant for version control. This ++creates a @dfn{VC Directory buffer} and displays it in a separate ++window. ++ ++@cindex PCL-CVS ++@pindex cvs ++@cindex CVS directory mode ++ The VC Directory buffer works with all the version control systems ++that VC supports. For CVS, Emacs also offers a more powerful facility ++called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The ++Emacs Front-End to CVS}. ++ ++@menu ++* Buffer: VC Directory Buffer. What the buffer looks like and means. ++* Commands: VC Directory Commands. Commands to use in a VC directory buffer. ++@end menu ++ ++@node VC Directory Buffer ++@subsubsection The VC Directory Buffer ++ ++ The VC Directory buffer contains a list of version-controlled files ++in the current directory and its subdirectories. Files which are ++up-to-date (have no local differences from the repository copy) are ++usually hidden; if all files in a subdirectory are up-to-date, the ++subdirectory is hidden as well. There is an exception to this rule: ++if VC mode detects that a file has changed to an up-to-date state ++since you last looked at it, that file and its state are shown. ++ ++ If a directory uses more that one version control system, you can ++select which system to use for the @code{vc-dir} command by invoking ++@code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}. ++ ++ The line for an individual file shows the version control state of ++the file. Under RCS and SCCS, the name of the user locking the file ++is shown; under CVS, an abbreviated version of the @samp{cvs status} ++output is used. Here is an example using CVS: ++ ++@smallexample ++@group ++ ./ ++ modified file1.c ++ needs-update file2.c ++ needs-merge file3.c ++@end group ++@end smallexample ++ ++@noindent ++In this example, @samp{file1.c} is modified with respect to the ++repository, and @samp{file2.c} is not. @samp{file3.c} is modified, ++but other changes have also been checked in to the repository---you ++need to merge them with the work file before you can check it in. ++ ++@vindex vc-stay-local ++@vindex vc-cvs-stay-local ++ In the above, if the repository were on a remote machine, VC only ++contacts it when the variable @code{vc-stay-local} (or ++@code{vc-cvs-stay-local}) is @code{nil} ++@iftex ++(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}). ++@end iftex ++@ifnottex ++(@pxref{CVS Options}). ++@end ifnottex ++This is because access to the repository may be slow, or you may be ++working offline and not have access to the repository at all. As a ++consequence, VC would not be able to tell you that @samp{file3.c} is ++in the ``merge'' state; you would learn that only when you try to ++check-in your modified copy of the file, or use a command such as ++@kbd{C-x v m}. ++ ++ In practice, this is not a problem because CVS handles this case ++consistently whenever it arises. In VC, you'll simply get prompted to ++merge the remote changes into your work file first. The benefits of ++less network communication usually outweigh the disadvantage of not ++seeing remote changes immediately. ++ ++@vindex vc-directory-exclusion-list ++ When a VC directory displays subdirectories it omits some that ++should never contain any files under version control. By default, ++this includes Version Control subdirectories such as @samp{RCS} and ++@samp{CVS}; you can customize this by setting the variable ++@code{vc-directory-exclusion-list}. ++ ++@node VC Directory Commands ++@subsubsection VC Directory Commands ++ ++ VC Directory mode has a full set of navigation and marking commands ++for picking out filesets. Some of these are also available in a ++context menu invoked by the @kbd{mouse-2} button. ++ ++ Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also ++move vertically as in other list-browsing modes. @key{SPC} and ++@key{TAB} behave like down-arrow, and @key{BackTab} behaves like ++up-arrow. ++ ++ Both @kbd{C-m} and @kbd{f} visit the file on the current ++line. @kbd{o} visits that file in another window. @kbd{q} dismisses ++the directory buffer. ++ ++ @kbd{x} hides up-to-date files. ++ ++ @kbd{m} marks the file or directory on the current line. If the ++region is active, @kbd{m} marks all the files in the region. There ++are some restrictions when marking: a file cannot be marked if any of ++its parent directories are marked, and a directory cannot be marked if ++any files in it or in its child directories are marked. ++ ++ @kbd{M} marks all the files with the same VC state as the current ++file if the cursor is on a file. If the cursor is on a directory, it ++marks all child files. With a prefix argument: marks all files and ++directories. ++ ++ @kbd{u} unmarks the file or directory on the current line. If the ++region is active, it unmarks all the files in the region. ++ ++ @kbd{U} marks all the files with the same VC state as the current file ++if the cursor is on a file. If the cursor is on a directory, it ++unmarks all child files. With a prefix argument: unmarks all marked ++files and directories. ++ ++ It is possible to do search, search and replace, incremental search, ++and incremental regexp search on multiple files. These commands will ++work on all the marked files or the current file if nothing is marked. ++If a directory is marked, the files in that directory shown in the VC ++directory buffer will be used. ++ ++ @kbd{S} searches the marked files. ++ ++ @kbd{Q} does a query replace on the marked files. ++ ++ @kbd{M-s a C-s} does an incremental search on the marked files. ++ ++ @kbd{M-s a C-M-s} does an incremental search on the marked files. ++ ++ Commands are also accessible from the VC-dir menu. Note that some VC ++backends use the VC-dir menu to make available extra backend specific ++commands. ++ ++ Normal VC commands with the @kbd{C-x v} prefix work in VC directory ++buffers. Some single-key shortcuts are available as well; @kbd{=}, ++@kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with ++@kbd{C-x v}. ++ ++ The command @kbd{C-x v v} (@code{vc-next-action}) operates on all the ++marked files, so that you can check in several files at once. ++If the underlying VC supports atomic commits of multiple-file ++changesets, @kbd{C-x v v} with a selected set of modified but not ++committed files will commit all of them at once as a single changeset. ++ ++ When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple ++files, all of those files must be either in the same state or in ++compatible states (added, modified and removed states are considered ++compatible). Otherwise it signals an error. This differs from the ++behavior of older versions of VC, which did not have fileset ++operations and simply did @code{vc-next-action} on each file ++individually. ++ ++ If any files are in a state that calls for commit, @kbd{C-x v v} reads a ++single log entry and uses it for the changeset as a whole. If the ++underling VCS is file- rather than changeset-oriented, the log entry ++will be replicated into the history of each file. ++ ++@node Branches ++@subsection Multiple Branches of a File ++@cindex branch (version control) ++@cindex trunk (version control) ++ ++ One use of version control is to maintain multiple ``current'' ++revisions of a file. For example, you might have different revisions of a ++program in which you are gradually adding various unfinished new ++features. Each such independent line of development is called a ++@dfn{branch}. VC allows you to create branches, switch between ++different branches, and merge changes from one branch to another. ++Please note, however, that branches are not supported for SCCS. ++ ++ A file's main line of development is usually called the @dfn{trunk}. ++You can create multiple branches from the trunk. How the difference ++between trunk and branch is made visible is dependent on whether the ++VCS uses dot-pair or monotonic version IDs. ++ ++ In VCSes with dot-pair revision IDs, the revisions on the trunk are ++normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can ++start an independent branch. A branch starting at revision 1.2 would ++have revision ID 1.2.1.1, and consecutive revisions on this branch ++would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is ++a second branch also starting at revision 1.2, it would consist of ++revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. ++ ++ In VCSes with monotonic revision IDs, trunk revisions are IDed as ++1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and ++continue through 2.2, 2.3, etc. But naming conventions for branches ++and subbranches vary widely on these systems, and some (like ++Mercurial) never depart from the monotonic integer sequence at all. ++Consult the documentation of the VCS you are using. ++ ++@cindex head revision ++ If you omit the final component of a dot-pair revision ID, that is called a ++@dfn{branch ID}. It refers to the highest existing revision on that ++branch---the @dfn{head revision} of that branch. The branches in the ++dot-pair example above have branch IDs 1.2.1 and 1.2.2. ++ ++@menu ++* Switching Branches:: How to get to another existing branch. ++* Creating Branches:: How to start a new branch. ++* Merging:: Transferring changes between branches. ++* Multi-User Branching:: Multiple users working at multiple branches ++ in parallel. ++@end menu ++ ++@node Switching Branches ++@subsubsection Switching between Branches ++ ++ To switch between branches, type @kbd{C-u C-x v v} and specify the ++revision ID you want to select. On a locking-based system, this ++version is then visited @emph{unlocked} (write-protected), so you can ++examine it before locking it. Switching branches in this way is allowed ++only when the file is not locked. ++ ++ On a VCS with dot-pair IDs, you can omit the minor part, thus giving ++only the branch ID; this takes you to the head version on the ++chosen branch. If you only type @key{RET}, Emacs goes to the highest ++version on the trunk. ++ ++ After you have switched to any branch (including the main branch), you ++stay on it for subsequent VC commands, until you explicitly select some ++other branch. ++ ++@node Creating Branches ++@subsubsection Creating New Branches ++ ++ To create a new branch from a head revision (one that is the latest in ++the branch that contains it), first select that revision if necessary, ++lock it with @kbd{C-x v v}, and make whatever changes you want. Then, ++when you check in the changes, use @kbd{C-u C-x v v}. This lets you ++specify the revision ID for the new revision. You should specify a ++suitable branch ID for a branch starting at the current revision. ++For example, if the current revision is 2.5, the branch ID should be ++2.5.1, 2.5.2, and so on, depending on the number of existing branches at ++that point. ++ ++ To create a new branch at an older revision (one that is no longer the ++head of a branch), first select that revision (@pxref{Switching ++Branches}). Your procedure will then differ depending on whether you ++are using a locking or merging-based VCS. ++ ++ On a locking VCS, you will need to lock the old revision branch with ++@kbd{C-x v v}. You'll be asked to confirm, when you lock the old ++revision, that you really mean to create a new branch---if you say no, ++you'll be offered a chance to lock the latest revision instead. On ++a merging-based VCS you will skip this step. ++ ++ Then make your changes and type @kbd{C-x v v} again to check in a new ++revision. This automatically creates a new branch starting from the ++selected revision. You need not specially request a new branch, because ++that's the only way to add a new revision at a point that is not the head ++of a branch. ++ ++ After the branch is created, you ``stay'' on it. That means that ++subsequent check-ins create new revisions on that branch. To leave the ++branch, you must explicitly select a different revision with @kbd{C-u C-x ++v v}. To transfer changes from one branch to another, use the merge ++command, described in the next section. ++ ++@node Merging ++@subsubsection Merging Branches ++ ++@cindex merging changes ++ When you have finished the changes on a certain branch, you will ++often want to incorporate them into the file's main line of development ++(the trunk). This is not a trivial operation, because development might ++also have proceeded on the trunk, so that you must @dfn{merge} the ++changes into a file that has already been changed otherwise. VC allows ++you to do this (and other things) with the @code{vc-merge} command. ++ ++@table @kbd ++@item C-x v m (vc-merge) ++Merge changes into the work file. ++@end table ++ ++@kindex C-x v m ++@findex vc-merge ++ @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it ++into the current version of the work file. It firsts asks you in the ++minibuffer where the changes should come from. If you just type ++@key{RET}, Emacs merges any changes that were made on the same branch ++since you checked the file out (we call this @dfn{merging the news}). ++This is the common way to pick up recent changes from the repository, ++regardless of whether you have already changed the file yourself. ++ ++ You can also enter a branch ID or a pair of revision IDs in ++the minibuffer. Then @kbd{C-x v m} finds the changes from that ++branch, or the differences between the two revisions you specified, and ++merges them into the current revision of the current file. ++ ++ As an example, suppose that you have finished a certain feature on ++branch 1.3.1. In the meantime, development on the trunk has proceeded ++to revision 1.5. To merge the changes from the branch to the trunk, ++first go to the head revision of the trunk, by typing @kbd{C-u C-x v v ++@key{RET}}. Revision 1.5 is now current. If locking is used for the file, ++type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next, ++type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on ++branch 1.3.1 (relative to revision 1.3, where the branch started, up to ++the last revision on the branch) and merges it into the current revision ++of the work file. You can now check in the changed file, thus creating ++revision 1.6 containing the changes from the branch. ++ ++ It is possible to do further editing after merging the branch, before ++the next check-in. But it is usually wiser to check in the merged ++revision, then lock it and make the further changes. This will keep ++a better record of the history of changes. ++ ++@cindex conflicts ++@cindex resolving conflicts ++ When you merge changes into a file that has itself been modified, the ++changes might overlap. We call this situation a @dfn{conflict}, and ++reconciling the conflicting changes is called @dfn{resolving a ++conflict}. ++ ++ Whenever conflicts occur during merging, VC detects them, tells you ++about them in the echo area, and asks whether you want help in merging. ++If you say yes, it starts an Ediff session (@pxref{Top, ++Ediff, Ediff, ediff, The Ediff Manual}). ++ ++ If you say no, the conflicting changes are both inserted into the ++file, surrounded by @dfn{conflict markers}. The example below shows how ++a conflict region looks; the file is called @samp{name} and the current ++master file revision with user B's changes in it is 1.11. ++ ++@c @w here is so CVS won't think this is a conflict. ++@smallexample ++@group ++@w{<}<<<<<< name ++ @var{User A's version} ++======= ++ @var{User B's version} ++@w{>}>>>>>> 1.11 ++@end group ++@end smallexample ++ ++@cindex vc-resolve-conflicts ++ Then you can resolve the conflicts by editing the file manually. Or ++you can type @code{M-x vc-resolve-conflicts} after visiting the file. ++This starts an Ediff session, as described above. Don't forget to ++check in the merged version afterwards. ++ ++@node Multi-User Branching ++@subsubsection Multi-User Branching ++ ++ It is often useful for multiple developers to work simultaneously on ++different branches of a file. CVS and later systems allow this by ++default; for RCS, it is possible if you create multiple source ++directories. Each source directory should have a link named ++@file{RCS} which points to a common directory of RCS master files. ++Then each source directory can have its own choice of selected ++revisions, but all share the same common RCS records. ++ ++ This technique works reliably and automatically, provided that the ++source files contain RCS version headers ++@iftex ++(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). ++@end iftex ++@ifnottex ++(@pxref{Version Headers}). ++@end ifnottex ++The headers enable Emacs to be sure, at all times, which revision ++ID is present in the work file. ++ ++ If the files do not have version headers, you must instead tell Emacs ++explicitly in each session which branch you are working on. To do this, ++first find the file, then type @kbd{C-u C-x v v} and specify the correct ++branch ID. This ensures that Emacs knows which branch it is using ++during this particular editing session. ++ ++@ifnottex ++@include vc1-xtra.texi ++@end ifnottex ++ ++@node Change Log ++@section Change Logs ++ ++@cindex change log ++ A change log file contains a chronological record of when and why you ++have changed a program, consisting of a sequence of entries describing ++individual changes. Normally it is kept in a file called ++@file{ChangeLog} in the same directory as the file you are editing, or ++one of its parent directories. A single @file{ChangeLog} file can ++record changes for all the files in its directory and all its ++subdirectories. ++ ++@menu ++* Change Log Commands:: Commands for editing change log files. ++* Format of ChangeLog:: What the change log file looks like. ++@end menu ++ ++@node Change Log Commands ++@subsection Change Log Commands ++ ++@kindex C-x 4 a ++@findex add-change-log-entry-other-window ++ The Emacs command @kbd{C-x 4 a} adds a new entry to the change log ++file for the file you are editing ++(@code{add-change-log-entry-other-window}). If that file is actually ++a backup file, it makes an entry appropriate for the file's ++parent---that is useful for making log entries for functions that ++have been deleted in the current version. ++ ++ @kbd{C-x 4 a} visits the change log file and creates a new entry ++unless the most recent entry is for today's date and your name. It ++also creates a new item for the current file. For many languages, it ++can even guess the name of the function or other object that was ++changed. ++ ++@vindex add-log-keep-changes-together ++ When the variable @code{add-log-keep-changes-together} is ++non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file ++rather than starting a new item. ++ ++@vindex add-log-always-start-new-record ++ If @code{add-log-always-start-new-record} is non-@code{nil}, ++@kbd{C-x 4 a} always makes a new entry, even if the last entry ++was made by you and on the same date. ++ ++@vindex change-log-version-info-enabled ++@vindex change-log-version-number-regexp-list ++@cindex file version in change log entries ++ If the value of the variable @code{change-log-version-info-enabled} ++is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the ++change log entry. It finds the version number by searching the first ++ten percent of the file, using regular expressions from the variable ++@code{change-log-version-number-regexp-list}. ++ ++@cindex Change Log mode ++@findex change-log-mode ++ The change log file is visited in Change Log mode. In this major ++mode, each bunch of grouped items counts as one paragraph, and each ++entry is considered a page. This facilitates editing the entries. ++@kbd{C-j} and auto-fill indent each new line like the previous line; ++this is convenient for entering the contents of an entry. ++ ++You can use the @code{next-error} command (by default bound to ++@kbd{C-x `}) to move between entries in the Change Log, when Change ++Log mode is on. You will jump to the actual site in the file that was ++changed, not just to the next Change Log entry. You can also use ++@code{previous-error} to move back in the same list. ++ ++@findex change-log-merge ++ You can use the command @kbd{M-x change-log-merge} to merge other ++log files into a buffer in Change Log Mode, preserving the date ++ordering of entries. ++ ++ Version control systems are another way to keep track of changes in ++your program and keep a change log. In the VC log buffer, typing ++@kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant ++Change Log entry, if one exists (@pxref{Log Buffer}). You can also ++insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a} ++(@code{vc-update-change-log}) in the Change Log buffer ++@iftex ++(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). ++@end iftex ++@ifnottex ++(@pxref{Change Logs and VC}). ++@end ifnottex ++ ++@node Format of ChangeLog ++@subsection Format of ChangeLog ++ ++ A change log entry starts with a header line that contains the current ++date, your name, and your email address (taken from the variable ++@code{add-log-mailing-address}). Aside from these header lines, every ++line in the change log starts with a space or a tab. The bulk of the ++entry consists of @dfn{items}, each of which starts with a line starting ++with whitespace and a star. Here are two entries, both dated in May ++1993, with two items and one item respectively. ++ ++@iftex ++@medbreak ++@end iftex ++@smallexample ++1993-05-25 Richard Stallman ++ ++ * man.el: Rename symbols `man-*' to `Man-*'. ++ (manual-entry): Make prompt string clearer. ++ ++ * simple.el (blink-matching-paren-distance): ++ Change default to 12,000. ++ ++1993-05-24 Richard Stallman ++ ++ * vc.el (minor-mode-map-alist): Don't use it if it's void. ++ (vc-cancel-version): Doc fix. ++@end smallexample ++ ++ One entry can describe several changes; each change should have its ++own item, or its own line in an item. Normally there should be a ++blank line between items. When items are related (parts of the same ++change, in different places), group them by leaving no blank line ++between them. ++ ++ You should put a copyright notice and permission notice at the ++end of the change log file. Here is an example: ++ ++@smallexample ++Copyright 1997, 1998 Free Software Foundation, Inc. ++Copying and distribution of this file, with or without modification, are ++permitted provided the copyright notice and this notice are preserved. ++@end smallexample ++ ++@noindent ++Of course, you should substitute the proper years and copyright holder. ++ ++@node Tags ++@section Tags Tables ++@cindex tags and tag tables ++ ++ A @dfn{tag} is a reference to a subunit in a program or in a ++document. In program source code, tags reference syntactic elements ++of the program: functions, subroutines, data types, macros, etc. In a ++document, tags reference chapters, sections, appendices, etc. Each ++tag specifies the name of the file where the corresponding subunit is ++defined, and the position of the subunit's definition in that file. ++ ++ A @dfn{tags table} records the tags extracted by scanning the source ++code of a certain program or a certain document. Tags extracted from ++generated files reference the original files, rather than the ++generated files that were scanned during tag extraction. Examples of ++generated files include C files generated from Cweb source files, from ++a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed ++C files; and Fortran files produced by preprocessing @file{.fpp} ++source files. ++ ++ To produce a tags table, you use the @samp{etags} command, ++submitting it a document or the source code of a program. ++@samp{etags} writes the tags to a @dfn{tags table file}, or @dfn{tags ++file} in short. The conventional name for a tags file is @file{TAGS}. ++ ++ Emacs uses the information recorded in tags tables in commands that ++search or replace through multiple source files: these commands use ++the names of the source files recorded in the tags table to know which ++files to search. Other commands, such as @kbd{M-.}, which finds the ++definition of a function, use the recorded information about the ++function names and positions to find the source file and the position ++within that file where the function is defined. ++ ++@cindex C++ class browser, tags ++@cindex tags, C++ ++@cindex class browser, C++ ++@cindex Ebrowse ++ See also the Ebrowse facility, which is tailored for C++. ++@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}. ++ ++@menu ++* Tag Syntax:: Tag syntax for various types of code and text files. ++* Create Tags Table:: Creating a tags table with @code{etags}. ++* Etags Regexps:: Create arbitrary tags using regular expressions. ++* Select Tags Table:: How to visit a tags table. ++* Find Tag:: Commands to find the definition of a specific tag. ++* Tags Search:: Using a tags table for searching and replacing. ++* List Tags:: Listing and finding tags defined in a file. ++@end menu ++ ++@node Tag Syntax ++@subsection Source File Tag Syntax ++ ++ Here is how tag syntax is defined for the most popular languages: ++ ++@itemize @bullet ++@item ++In C code, any C function or typedef is a tag, and so are definitions of ++@code{struct}, @code{union} and @code{enum}. ++@code{#define} macro definitions, @code{#undef} and @code{enum} ++constants are also ++tags, unless you specify @samp{--no-defines} when making the tags table. ++Similarly, global variables are tags, unless you specify ++@samp{--no-globals}, and so are struct members, unless you specify ++@samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines} ++and @samp{--no-members} can make the tags table file much smaller. ++ ++You can tag function declarations and external variables in addition ++to function definitions by giving the @samp{--declarations} option to ++@code{etags}. ++ ++@item ++In C++ code, in addition to all the tag constructs of C code, member ++functions are also recognized; member variables are also recognized, ++unless you use the @samp{--no-members} option. Tags for variables and ++functions in classes are named @samp{@var{class}::@var{variable}} and ++@samp{@var{class}::@var{function}}. @code{operator} definitions have ++tag names like @samp{operator+}. ++ ++@item ++In Java code, tags include all the constructs recognized in C++, plus ++the @code{interface}, @code{extends} and @code{implements} constructs. ++Tags for variables and functions in classes are named ++@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. ++ ++@item ++In La@TeX{} text, the argument of any of the commands @code{\chapter}, ++@code{\section}, @code{\subsection}, @code{\subsubsection}, ++@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, ++@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry}, ++@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand}, ++@code{\newenvironment} or @code{\renewenvironment} is a tag.@refill ++ ++Other commands can make tags as well, if you specify them in the ++environment variable @env{TEXTAGS} before invoking @code{etags}. The ++value of this environment variable should be a colon-separated list of ++command names. For example, ++ ++@example ++TEXTAGS="mycommand:myothercommand" ++export TEXTAGS ++@end example ++ ++@noindent ++specifies (using Bourne shell syntax) that the commands ++@samp{\mycommand} and @samp{\myothercommand} also define tags. ++ ++@item ++In Lisp code, any function defined with @code{defun}, any variable ++defined with @code{defvar} or @code{defconst}, and in general the first ++argument of any expression that starts with @samp{(def} in column zero is ++a tag. ++ ++@item ++In Scheme code, tags include anything defined with @code{def} or with a ++construct whose name starts with @samp{def}. They also include variables ++set with @code{set!} at top level in the file. ++@end itemize ++ ++ Several other languages are also supported: ++ ++@itemize @bullet ++ ++@item ++In Ada code, functions, procedures, packages, tasks and types are ++tags. Use the @samp{--packages-only} option to create tags for ++packages only. ++ ++In Ada, the same name can be used for different kinds of entity ++(e.g.@:, for a procedure and for a function). Also, for things like ++packages, procedures and functions, there is the spec (i.e.@: the ++interface) and the body (i.e.@: the implementation). To make it ++easier to pick the definition you want, Ada tag name have suffixes ++indicating the type of entity: ++ ++@table @samp ++@item /b ++package body. ++@item /f ++function. ++@item /k ++task. ++@item /p ++procedure. ++@item /s ++package spec. ++@item /t ++type. ++@end table ++ ++ Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go ++directly to the body of the package @code{bidule}, while @kbd{M-x ++find-tag @key{RET} bidule @key{RET}} will just search for any tag ++@code{bidule}. ++ ++@item ++In assembler code, labels appearing at the beginning of a line, ++followed by a colon, are tags. ++ ++@item ++In Bison or Yacc input files, each rule defines as a tag the nonterminal ++it constructs. The portions of the file that contain C code are parsed ++as C code. ++ ++@item ++In Cobol code, tags are paragraph names; that is, any word starting in ++column 8 and followed by a period. ++ ++@item ++In Erlang code, the tags are the functions, records and macros defined ++in the file. ++ ++@item ++In Fortran code, functions, subroutines and block data are tags. ++ ++@item ++In HTML input files, the tags are the @code{title} and the @code{h1}, ++@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors ++and all occurrences of @code{id=}. ++ ++@item ++In Lua input files, all functions are tags. ++ ++@item ++In makefiles, targets are tags; additionally, variables are tags ++unless you specify @samp{--no-globals}. ++ ++@item ++In Objective C code, tags include Objective C definitions for classes, ++class categories, methods and protocols. Tags for variables and ++functions in classes are named @samp{@var{class}::@var{variable}} and ++@samp{@var{class}::@var{function}}. ++ ++@item ++In Pascal code, the tags are the functions and procedures defined in ++the file. ++ ++@item ++In Perl code, the tags are the packages, subroutines and variables ++defined by the @code{package}, @code{sub}, @code{my} and @code{local} ++keywords. Use @samp{--globals} if you want to tag global variables. ++Tags for subroutines are named @samp{@var{package}::@var{sub}}. The ++name for subroutines defined in the default package is ++@samp{main::@var{sub}}. ++ ++@item ++In PHP code, tags are functions, classes and defines. Vars are tags ++too, unless you use the @samp{--no-members} option. ++ ++@item ++In PostScript code, the tags are the functions. ++ ++@item ++In Prolog code, tags are predicates and rules at the beginning of ++line. ++ ++@item ++In Python code, @code{def} or @code{class} at the beginning of a line ++generate a tag. ++@end itemize ++ ++ You can also generate tags based on regexp matching (@pxref{Etags ++Regexps}) to handle other formats and languages. ++ ++@node Create Tags Table ++@subsection Creating Tags Tables ++@cindex @code{etags} program ++ ++ The @code{etags} program is used to create a tags table file. It knows ++the syntax of several languages, as described in ++@iftex ++the previous section. ++@end iftex ++@ifnottex ++@ref{Tag Syntax}. ++@end ifnottex ++Here is how to run @code{etags}: ++ ++@example ++etags @var{inputfiles}@dots{} ++@end example ++ ++@noindent ++The @code{etags} program reads the specified files, and writes a tags ++table named @file{TAGS} in the current working directory. You can ++optionally specify a different file name for the tags table by using the ++@samp{--output=@var{file}} option; specifying @file{-} as a file name ++prints the tags table to standard output. ++ ++ If the specified files don't exist, @code{etags} looks for ++compressed versions of them and uncompresses them to read them. Under ++MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz} ++if it is given @samp{mycode.c} on the command line and @file{mycode.c} ++does not exist. ++ ++ @code{etags} recognizes the language used in an input file based on ++its file name and contents. You can specify the language with the ++@samp{--language=@var{name}} option, described below. ++ ++ If the tags table data become outdated due to changes in the files ++described in the table, the way to update the tags table is the same ++way it was made in the first place. If the tags table fails to record ++a tag, or records it for the wrong file, then Emacs cannot possibly ++find its definition until you update the tags table. However, if the ++position recorded in the tags table becomes a little bit wrong (due to ++other editing), the worst consequence is a slight delay in finding the ++tag. Even if the stored position is very far wrong, Emacs will still ++find the tag, after searching most of the file for it. That delay is ++hardly noticeable with today's computers. ++ ++ Thus, there is no need to update the tags table after each edit. ++You should update a tags table when you define new tags that you want ++to have listed, or when you move tag definitions from one file to ++another, or when changes become substantial. ++ ++ One tags table can virtually include another. Specify the included ++tags file name with the @samp{--include=@var{file}} option when ++creating the file that is to include it. The latter file then acts as ++if it covered all the source files specified in the included file, as ++well as the files it directly contains. ++ ++ If you specify the source files with relative file names when you run ++@code{etags}, the tags file will contain file names relative to the ++directory where the tags file was initially written. This way, you can ++move an entire directory tree containing both the tags file and the ++source files, and the tags file will still refer correctly to the source ++files. If the tags file is @file{-} or is in the @file{/dev} directory, ++however, the file names are ++made relative to the current working directory. This is useful, for ++example, when writing the tags to @file{/dev/stdout}. ++ ++ When using a relative file name, it should not be a symbolic link ++pointing to a tags file in a different directory, because this would ++generally render the file names invalid. ++ ++ If you specify absolute file names as arguments to @code{etags}, then ++the tags file will contain absolute file names. This way, the tags file ++will still refer to the same files even if you move it, as long as the ++source files remain in the same place. Absolute file names start with ++@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. ++ ++ When you want to make a tags table from a great number of files, you ++may have problems listing them on the command line, because some systems ++have a limit on its length. The simplest way to circumvent this limit ++is to tell @code{etags} to read the file names from its standard input, ++by typing a dash in place of the file names, like this: ++ ++@smallexample ++find . -name "*.[chCH]" -print | etags - ++@end smallexample ++ ++ Use the option @samp{--language=@var{name}} to specify the language ++explicitly. You can intermix these options with file names; each one ++applies to the file names that follow it. Specify ++@samp{--language=auto} to tell @code{etags} to resume guessing the ++language from the file names and file contents. Specify ++@samp{--language=none} to turn off language-specific processing ++entirely; then @code{etags} recognizes tags by regexp matching alone ++(@pxref{Etags Regexps}). ++ ++ The option @samp{--parse-stdin=@var{file}} is mostly useful when ++calling @code{etags} from programs. It can be used (only once) in ++place of a file name on the command line. @code{Etags} will read from ++standard input and mark the produced tags as belonging to the file ++@var{file}. ++ ++ @samp{etags --help} outputs the list of the languages @code{etags} ++knows, and the file name rules for guessing the language. It also prints ++a list of all the available @code{etags} options, together with a short ++explanation. If followed by one or more @samp{--language=@var{lang}} ++options, it outputs detailed information about how tags are generated for ++@var{lang}. ++ ++@node Etags Regexps ++@subsection Etags Regexps ++ ++ The @samp{--regex} option provides a general way of recognizing tags ++based on regexp matching. You can freely intermix this option with ++file names, and each one applies to the source files that follow it. ++If you specify multiple @samp{--regex} options, all of them are used ++in parallel. The syntax is: ++ ++@smallexample ++--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers} ++@end smallexample ++ ++ The essential part of the option value is @var{tagregexp}, the ++regexp for matching tags. It is always used anchored, that is, it ++only matches at the beginning of a line. If you want to allow ++indented tags, use a regexp that matches initial whitespace; start it ++with @samp{[ \t]*}. ++ ++ In these regular expressions, @samp{\} quotes the next character, and ++all the GCC character escape sequences are supported (@samp{\a} for ++bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for ++escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for ++carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab). ++ ++ Ideally, @var{tagregexp} should not match more characters than are ++needed to recognize what you want to tag. If the syntax requires you ++to write @var{tagregexp} so it matches more characters beyond the tag ++itself, you should add a @var{nameregexp}, to pick out just the tag. ++This will enable Emacs to find tags more accurately and to do ++completion on tag names more reliably. You can find some examples ++below. ++ ++ The @var{modifiers} are a sequence of zero or more characters that ++modify the way @code{etags} does the matching. A regexp with no ++modifiers is applied sequentially to each line of the input file, in a ++case-sensitive way. The modifiers and their meanings are: ++ ++@table @samp ++@item i ++Ignore case when matching this regexp. ++@item m ++Match this regular expression against the whole file, so that ++multi-line matches are possible. ++@item s ++Match this regular expression against the whole file, and allow ++@samp{.} in @var{tagregexp} to match newlines. ++@end table ++ ++ The @samp{-R} option cancels all the regexps defined by preceding ++@samp{--regex} options. It too applies to the file names following ++it. Here's an example: ++ ++@smallexample ++etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ ++ bar.ber -R --lang=lisp los.er ++@end smallexample ++ ++@noindent ++Here @code{etags} chooses the parsing language for @file{voo.doo} and ++@file{bar.ber} according to their contents. @code{etags} also uses ++@var{reg1} to recognize additional tags in @file{voo.doo}, and both ++@var{reg1} and @var{reg2} to recognize additional tags in ++@file{bar.ber}. @var{reg1} is checked against each line of ++@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while ++@var{reg2} is checked against the whole @file{bar.ber} file, ++permitting multi-line matches, in a case-sensitive way. @code{etags} ++uses only the Lisp tags rules, with no user-specified regexp matching, ++to recognize tags in @file{los.er}. ++ ++ You can restrict a @samp{--regex} option to match only files of a ++given language by using the optional prefix @var{@{language@}}. ++(@samp{etags --help} prints the list of languages recognized by ++@code{etags}.) This is particularly useful when storing many ++predefined regular expressions for @code{etags} in a file. The ++following example tags the @code{DEFVAR} macros in the Emacs source ++files, for the C language only: ++ ++@smallexample ++--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' ++@end smallexample ++ ++@noindent ++When you have complex regular expressions, you can store the list of ++them in a file. The following option syntax instructs @code{etags} to ++read two files of regular expressions. The regular expressions ++contained in the second file are matched without regard to case. ++ ++@smallexample ++--regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file} ++@end smallexample ++ ++@noindent ++A regex file for @code{etags} contains one regular expression per ++line. Empty lines, and lines beginning with space or tab are ignored. ++When the first character in a line is @samp{@@}, @code{etags} assumes ++that the rest of the line is the name of another file of regular ++expressions; thus, one such file can include another file. All the ++other lines are taken to be regular expressions. If the first ++non-whitespace text on the line is @samp{--}, that line is a comment. ++ ++ For example, we can create a file called @samp{emacs.tags} with the ++following contents: ++ ++@smallexample ++ -- This is for GNU Emacs C source files ++@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ ++@end smallexample ++ ++@noindent ++and then use it like this: ++ ++@smallexample ++etags --regex=@@emacs.tags *.[ch] */*.[ch] ++@end smallexample ++ ++ Here are some more examples. The regexps are quoted to protect them ++from shell interpretation. ++ ++@itemize @bullet ++ ++@item ++Tag Octave files: ++ ++@smallexample ++etags --language=none \ ++ --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ ++ --regex='/###key \(.*\)/\1/' \ ++ --regex='/[ \t]*global[ \t].*/' \ ++ *.m ++@end smallexample ++ ++@noindent ++Note that tags are not generated for scripts, so that you have to add ++a line by yourself of the form @samp{###key @var{scriptname}} if you ++want to jump to it. ++ ++@item ++Tag Tcl files: ++ ++@smallexample ++etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl ++@end smallexample ++ ++@item ++Tag VHDL files: ++ ++@smallexample ++etags --language=none \ ++ --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ ++ --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ ++ \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' ++@end smallexample ++@end itemize ++ ++@node Select Tags Table ++@subsection Selecting a Tags Table ++ ++@vindex tags-file-name ++@findex visit-tags-table ++ Emacs has at any time one @dfn{selected} tags table, and all the ++commands for working with tags tables use the selected one. To select ++a tags table, type @kbd{M-x visit-tags-table}, which reads the tags ++table file name as an argument, with @file{TAGS} in the default ++directory as the default. ++ ++ Emacs does not actually read in the tags table contents until you ++try to use them; all @code{visit-tags-table} does is store the file ++name in the variable @code{tags-file-name}, and setting the variable ++yourself is just as good. The variable's initial value is @code{nil}; ++that value tells all the commands for working with tags tables that ++they must ask for a tags table file name to use. ++ ++ Using @code{visit-tags-table} when a tags table is already loaded ++gives you a choice: you can add the new tags table to the current list ++of tags tables, or start a new list. The tags commands use all the tags ++tables in the current list. If you start a new list, the new tags table ++is used @emph{instead} of others. If you add the new table to the ++current list, it is used @emph{as well as} the others. ++ ++@vindex tags-table-list ++ You can specify a precise list of tags tables by setting the variable ++@code{tags-table-list} to a list of strings, like this: ++ ++@c keep this on two lines for formatting in smallbook ++@example ++@group ++(setq tags-table-list ++ '("~/emacs" "/usr/local/lib/emacs/src")) ++@end group ++@end example ++ ++@noindent ++This tells the tags commands to look at the @file{TAGS} files in your ++@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} ++directory. The order depends on which file you are in and which tags ++table mentions that file, as explained above. ++ ++ Do not set both @code{tags-file-name} and @code{tags-table-list}. ++ ++@node Find Tag ++@subsection Finding a Tag ++ ++ The most important thing that a tags table enables you to do is to find ++the definition of a specific tag. ++ ++@table @kbd ++@item M-.@: @var{tag} @key{RET} ++Find first definition of @var{tag} (@code{find-tag}). ++@item C-u M-. ++Find next alternate definition of last tag specified. ++@item C-u - M-. ++Go back to previous tag found. ++@item C-M-. @var{pattern} @key{RET} ++Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). ++@item C-u C-M-. ++Find the next tag whose name matches the last pattern used. ++@item C-x 4 .@: @var{tag} @key{RET} ++Find first definition of @var{tag}, but display it in another window ++(@code{find-tag-other-window}). ++@item C-x 5 .@: @var{tag} @key{RET} ++Find first definition of @var{tag}, and create a new frame to select the ++buffer (@code{find-tag-other-frame}). ++@item M-* ++Pop back to where you previously invoked @kbd{M-.} and friends. ++@end table ++ ++@kindex M-. ++@findex find-tag ++ @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of ++a specified tag. It searches through the tags table for that tag, as a ++string, and then uses the tags table info to determine the file that the ++definition is in and the approximate character position in the file of ++the definition. Then @code{find-tag} visits that file, moves point to ++the approximate character position, and searches ever-increasing ++distances away to find the tag definition. ++ ++ If an empty argument is given (just type @key{RET}), the balanced ++expression in the buffer before or around point is used as the ++@var{tag} argument. @xref{Expressions}. ++ ++ You don't need to give @kbd{M-.} the full name of the tag; a part ++will do. This is because @kbd{M-.} finds tags in the table which ++contain @var{tag} as a substring. However, it prefers an exact match ++to a substring match. To find other tags that match the same ++substring, give @code{find-tag} a numeric argument, as in @kbd{C-u ++M-.}; this does not read a tag name, but continues searching the tags ++table's text for another tag containing the same substring last used. ++If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier ++alternative to @kbd{C-u M-.}. ++ ++@kindex C-x 4 . ++@findex find-tag-other-window ++@kindex C-x 5 . ++@findex find-tag-other-frame ++ Like most commands that can switch buffers, @code{find-tag} has a ++variant that displays the new buffer in another window, and one that ++makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes ++the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}}, ++which invokes @code{find-tag-other-frame}. ++ ++ To move back to places you've found tags recently, use @kbd{C-u - ++M-.}; more generally, @kbd{M-.} with a negative numeric argument. This ++command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative ++argument finds the previous tag location in another window. ++ ++@kindex M-* ++@findex pop-tag-mark ++@vindex find-tag-marker-ring-length ++ As well as going back to places you've found tags recently, you can go ++back to places @emph{from where} you found them. Use @kbd{M-*}, which ++invokes the command @code{pop-tag-mark}, for this. Typically you would ++find and study the definition of something with @kbd{M-.} and then ++return to where you were with @kbd{M-*}. ++ ++ Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to ++a depth determined by the variable @code{find-tag-marker-ring-length}. ++ ++@findex find-tag-regexp ++@kindex C-M-. ++ The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that ++match a specified regular expression. It is just like @kbd{M-.} except ++that it does regexp matching instead of substring matching. ++ ++@node Tags Search ++@subsection Searching and Replacing with Tags Tables ++@cindex search and replace in multiple files ++@cindex multiple-file search and replace ++ ++ The commands in this section visit and search all the files listed ++in the selected tags table, one by one. For these commands, the tags ++table serves only to specify a sequence of files to search. These ++commands scan the list of tags tables starting with the first tags ++table (if any) that describes the current file, proceed from there to ++the end of the list, and then scan from the beginning of the list ++until they have covered all the tables in the list. ++ ++@table @kbd ++@item M-x tags-search @key{RET} @var{regexp} @key{RET} ++Search for @var{regexp} through the files in the selected tags ++table. ++@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} ++Perform a @code{query-replace-regexp} on each file in the selected tags table. ++@item M-, ++Restart one of the commands above, from the current location of point ++(@code{tags-loop-continue}). ++@end table ++ ++@findex tags-search ++ @kbd{M-x tags-search} reads a regexp using the minibuffer, then ++searches for matches in all the files in the selected tags table, one ++file at a time. It displays the name of the file being searched so you ++can follow its progress. As soon as it finds an occurrence, ++@code{tags-search} returns. ++ ++@kindex M-, ++@findex tags-loop-continue ++ Having found one match, you probably want to find all the rest. To find ++one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the ++@code{tags-search}. This searches the rest of the current buffer, followed ++by the remaining files of the tags table.@refill ++ ++@findex tags-query-replace ++ @kbd{M-x tags-query-replace} performs a single ++@code{query-replace-regexp} through all the files in the tags table. It ++reads a regexp to search for and a string to replace with, just like ++ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x ++tags-search}, but repeatedly, processing matches according to your ++input. @xref{Replace}, for more information on query replace. ++ ++@vindex tags-case-fold-search ++@cindex case-sensitivity and tags search ++ You can control the case-sensitivity of tags search commands by ++customizing the value of the variable @code{tags-case-fold-search}. The ++default is to use the same setting as the value of ++@code{case-fold-search} (@pxref{Search Case}). ++ ++ It is possible to get through all the files in the tags table with a ++single invocation of @kbd{M-x tags-query-replace}. But often it is ++useful to exit temporarily, which you can do with any input event that ++has no special query replace meaning. You can resume the query ++replace subsequently by typing @kbd{M-,}; this command resumes the ++last tags search or replace command that you did. For instance, to ++skip the rest of the current file, you can type @kbd{M-> M-,}. ++ ++ The commands in this section carry out much broader searches than the ++@code{find-tag} family. The @code{find-tag} commands search only for ++definitions of tags that match your substring or regexp. The commands ++@code{tags-search} and @code{tags-query-replace} find every occurrence ++of the regexp, as ordinary search commands and replace commands do in ++the current buffer. ++ ++ These commands create buffers only temporarily for the files that they ++have to search (those which are not already visited in Emacs buffers). ++Buffers in which no match is found are quickly killed; the others ++continue to exist. ++ ++ It may have struck you that @code{tags-search} is a lot like ++@code{grep}. You can also run @code{grep} itself as an inferior of ++Emacs and have Emacs show you the matching lines one by one. ++@xref{Grep Searching}. ++ ++@node List Tags ++@subsection Tags Table Inquiries ++ ++@table @kbd ++@item M-x list-tags @key{RET} @var{file} @key{RET} ++Display a list of the tags defined in the program file @var{file}. ++@item M-x tags-apropos @key{RET} @var{regexp} @key{RET} ++Display a list of all tags matching @var{regexp}. ++@end table ++ ++@findex list-tags ++ @kbd{M-x list-tags} reads the name of one of the files described by ++the selected tags table, and displays a list of all the tags defined in ++that file. The ``file name'' argument is really just a string to ++compare against the file names recorded in the tags table; it is read as ++a string rather than as a file name. Therefore, completion and ++defaulting are not available, and you must enter the file name the same ++way it appears in the tags table. Do not include a directory as part of ++the file name unless the file name recorded in the tags table includes a ++directory. ++ ++@findex tags-apropos ++@vindex tags-apropos-verbose ++ @kbd{M-x tags-apropos} is like @code{apropos} for tags ++(@pxref{Apropos}). It finds all the tags in the selected tags table ++whose entries match @var{regexp}, and displays them. If the variable ++@code{tags-apropos-verbose} is non-@code{nil}, it displays the names ++of the tags files together with the tag names. ++ ++@vindex tags-tag-face ++@vindex tags-apropos-additional-actions ++ You can customize the appearance of the output by setting the ++variable @code{tags-tag-face} to a face. You can display additional ++output with @kbd{M-x tags-apropos} by customizing the variable ++@code{tags-apropos-additional-actions}---see its documentation for ++details. ++ ++ You can also use the collection of tag names to complete a symbol ++name in the buffer. @xref{Symbol Completion}. ++ ++@ifnottex ++@include emerge-xtra.texi ++@end ifnottex ++ ++@ignore ++ arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb ++@end ignore +diff --git a/doc/emacs/major.texi b/doc/emacs/major.texi +new file mode 100644 +index 0000000..545b708 +--- /dev/null ++++ b/doc/emacs/major.texi +@@ -0,0 +1,226 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Major Modes, Indentation, International, Top ++@chapter Major Modes ++@cindex major modes ++@cindex mode, major ++@kindex TAB @r{(and major modes)} ++@kindex DEL @r{(and major modes)} ++@kindex C-j @r{(and major modes)} ++ ++ Emacs provides many alternative @dfn{major modes}, each of which ++customizes Emacs for editing text of a particular sort. The major modes ++are mutually exclusive, and each buffer has one major mode at any time. ++The mode line normally shows the name of the current major mode, in ++parentheses (@pxref{Mode Line}). ++ ++ The least specialized major mode is called @dfn{Fundamental mode}. ++This mode has no mode-specific redefinitions or variable settings, so ++that each Emacs command behaves in its most general manner, and each ++user option variable is in its default state. For editing text of a ++specific type that Emacs knows about, such as Lisp code or English ++text, you should switch to the appropriate major mode, such as Lisp ++mode or Text mode. ++ ++ Selecting a major mode changes the meanings of a few keys to become ++more specifically adapted to the language being edited. The ones that ++are changed frequently are @key{TAB}, @key{DEL}, and @kbd{C-j}. The ++prefix key @kbd{C-c} normally contains mode-specific commands. In ++addition, the commands which handle comments use the mode to determine ++how comments are to be delimited. Many major modes redefine the ++syntactical properties of characters appearing in the buffer. ++@xref{Syntax}. ++ ++ The major modes fall into three major groups. The first group ++contains modes for normal text, either plain or with mark-up. It ++includes Text mode, HTML mode, SGML mode, @TeX{} mode and Outline ++mode. The second group contains modes for specific programming ++languages. These include Lisp mode (which has several variants), C ++mode, Fortran mode, and others. The remaining major modes are not ++intended for use on users' files; they are used in buffers created for ++specific purposes by Emacs, such as Dired mode for buffers made by ++Dired (@pxref{Dired}), Mail mode for buffers made by @kbd{C-x m} ++(@pxref{Sending Mail}), and Shell mode for buffers used for ++communicating with an inferior shell process (@pxref{Interactive ++Shell}). ++ ++ Most programming-language major modes specify that only blank lines ++separate paragraphs. This is to make the paragraph commands useful. ++(@xref{Paragraphs}.) They also cause Auto Fill mode to use the ++definition of @key{TAB} to indent the new lines it creates. This is ++because most lines in a program are usually indented ++(@pxref{Indentation}). ++ ++@menu ++* Choosing Modes:: How major modes are specified or chosen. ++@end menu ++ ++@node Choosing Modes,,Major Modes,Major Modes ++@section How Major Modes are Chosen ++ ++@cindex choosing a major mode ++ You can select a major mode explicitly for the current buffer, but ++most of the time Emacs determines which mode to use based on the file ++name or on special text in the file. ++ ++ To explicitly select a new major, you use an @kbd{M-x} command. ++Take the name of a major mode and add @code{-mode} to get the name of ++the command to select that mode. Thus, you can enter Lisp mode by ++executing @kbd{M-x lisp-mode}. ++ ++@vindex auto-mode-alist ++ When you visit a file, Emacs usually chooses the right major mode ++automatically. Normally, it makes the choice based on the file ++name---for example, files whose names end in @samp{.c} are normally ++edited in C mode---but sometimes it chooses the major mode based on ++the contents of the file. Here is the exact procedure: ++ ++ First, Emacs checks whether the file contains a file-local variable ++that specifies the major mode. If so, it uses that major mode, ++ignoring all other criteria. @xref{File Variables}. There are ++several methods to specify a major mode using a file-local variable; ++the simplest is to put the mode name in the first nonblank line, ++preceded and followed by @samp{-*-}. Other text may appear on the ++line as well. For example, ++ ++@example ++; -*-Lisp-*- ++@end example ++ ++@noindent ++tells Emacs to use Lisp mode. Note how the semicolon is used to make ++Lisp treat this line as a comment. Alternatively, you could write ++ ++@example ++; -*- mode: Lisp;-*- ++@end example ++ ++@noindent ++The latter format allows you to specify local variables as well, like ++this: ++ ++@example ++; -*- mode: Lisp; tab-width: 4; -*- ++@end example ++ ++@vindex interpreter-mode-alist ++ Second, Emacs checks whether the file's contents begin with ++@samp{#!}. If so, that indicates that the file can serve as an ++executable shell command, which works by running an interpreter named ++on the file's first line (the rest of the file is used as input to the ++interpreter). Therefore, Emacs tries to use the interpreter name to ++choose a mode. For instance, a file that begins with ++@samp{#!/usr/bin/perl} is opened in Perl mode. The variable ++@code{interpreter-mode-alist} specifies the correspondence between ++interpreter program names and major modes. ++ ++ When the first line starts with @samp{#!}, you usually cannot use ++the @samp{-*-} feature on the first line, because the system would get ++confused when running the interpreter. So Emacs looks for @samp{-*-} ++on the second line in such files as well as on the first line. The ++same is true for man pages which start with the magic string ++@samp{'\"} to specify a list of troff preprocessors. ++ ++@vindex magic-mode-alist ++ Third, Emacs tries to determine the major mode by looking at the ++text at the start of the buffer, based on the variable ++@code{magic-mode-alist}. By default, this variable is @code{nil} (an ++empty list), so Emacs skips this step; however, you can customize it ++in your init file (@pxref{Init File}). The value should be a list of ++elements of the form ++ ++@example ++(@var{regexp} . @var{mode-function}) ++@end example ++ ++@noindent ++where @var{regexp} is a regular expression (@pxref{Regexps}), and ++@var{mode-function} is a Lisp function that toggles a major mode. If ++the text at the beginning of the file matches @var{regexp}, Emacs ++chooses the major mode specified by @var{mode-function}. ++ ++Alternatively, an element of @code{magic-mode-alist} may have the form ++ ++@example ++(@var{match-function} . @var{mode-function}) ++@end example ++ ++@noindent ++where @var{match-function} is a Lisp function that is called at the ++beginning of the buffer; if the function returns non-@code{nil}, Emacs ++set the major mode wit @var{mode-function}. ++ ++ Fourth---if Emacs still hasn't found a suitable major mode---it ++looks at the file's name. The correspondence between file names and ++major modes is controlled by the variable @code{auto-mode-alist}. Its ++value is a list in which each element has this form, ++ ++@example ++(@var{regexp} . @var{mode-function}) ++@end example ++ ++@noindent ++or this form, ++ ++@example ++(@var{regexp} @var{mode-function} @var{flag}) ++@end example ++ ++@noindent ++For example, one element normally found in the list has the form ++@code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C ++mode for files whose names end in @file{.c}. (Note that @samp{\\} is ++needed in Lisp syntax to include a @samp{\} in the string, which must ++be used to suppress the special meaning of @samp{.} in regexps.) If ++the element has the form @code{(@var{regexp} @var{mode-function} ++@var{flag})} and @var{flag} is non-@code{nil}, then after calling ++@var{mode-function}, Emacs discards the suffix that matched ++@var{regexp} and searches the list again for another match. ++ ++@vindex auto-mode-case-fold ++ On systems with case-insensitive file names, such as Microsoft ++Windows, Emacs performs a single case-insensitive search through ++@code{auto-mode-alist}. On other systems, Emacs normally performs a ++single case-sensitive search through the alist. However, if you ++change the variable @code{auto-mode-case-fold} to @code{t}, Emacs ++performs a second case-insensitive search if the first search fails. ++ ++@vindex magic-fallback-mode-alist ++ Finally, if Emacs @emph{still} hasn't found a major mode to use, it ++compares the text at the start of the buffer to the variable ++@code{magic-fallback-mode-alist}. This variable works like ++@code{magic-mode-alist}, described above, except that is consulted ++only after @code{auto-mode-alist}. By default, ++@code{magic-fallback-mode-alist} contains forms that check for image ++files, HTML/XML/SGML files, and Postscript files. ++ ++@vindex default-major-mode ++ When you visit a file that does not specify a major mode to use, or ++when you create a new buffer with @kbd{C-x b}, the variable ++@code{default-major-mode} specifies which major mode to use. Normally ++its value is the symbol @code{fundamental-mode}, which specifies ++Fundamental mode. If @code{default-major-mode} is @code{nil}, the ++major mode is taken from the previously current buffer. ++ ++@findex normal-mode ++ If you change the major mode of a buffer, you can go back to the major ++mode Emacs would choose automatically: use the command @kbd{M-x ++normal-mode} to do this. This is the same function that ++@code{find-file} calls to choose the major mode. It also processes ++the file's @samp{-*-} line or local variables list (if any). ++@xref{File Variables}. ++ ++@vindex change-major-mode-with-file-name ++ The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to ++a new major mode if the new file name implies a mode (@pxref{Saving}). ++(@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) ++However, this does not happen if the buffer contents specify a major ++mode, and certain ``special'' major modes do not allow the mode to ++change. You can turn off this mode-changing feature by setting ++@code{change-major-mode-with-file-name} to @code{nil}. ++ ++@ignore ++ arch-tag: f2558800-cf32-4839-8acb-7d3b4df2a155 ++@end ignore +diff --git a/doc/emacs/makefile.w32-in b/doc/emacs/makefile.w32-in +new file mode 100644 +index 0000000..9c1a8cd +--- /dev/null ++++ b/doc/emacs/makefile.w32-in +@@ -0,0 +1,144 @@ ++#### -*- Makefile -*- for the Emacs Manual ++ ++# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++# Free Software Foundation, Inc. ++ ++# This file is part of GNU Emacs. ++ ++# GNU Emacs 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. ++ ++# GNU Emacs 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 GNU Emacs. If not, see . ++ ++ ++# Where to find the source code. The source code for Emacs's C kernel is ++# expected to be in $(srcdir)/src, and the source code for Emacs's ++# utility programs is expected to be in $(srcdir)/lib-src. This is ++# set by the configure script's `--srcdir' option. ++srcdir=. ++ ++infodir = $(srcdir)/../../info ++ ++# The makeinfo program is part of the Texinfo distribution. ++MAKEINFO = makeinfo --force ++MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat ++INFO_TARGETS = $(infodir)/emacs ++DVI_TARGETS = emacs.dvi ++INFOSOURCES = info.texi ++ ++# The following rule does not work with all versions of `make'. ++.SUFFIXES: .texi .dvi ++.texi.dvi: ++ texi2dvi $< ++ ++TEXI2DVI = texi2dvi ++ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ ++ "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C ++ ++EMACS_XTRA=\ ++ $(srcdir)/arevert-xtra.texi \ ++ $(srcdir)/cal-xtra.texi \ ++ $(srcdir)/dired-xtra.texi \ ++ $(srcdir)/picture-xtra.texi \ ++ $(srcdir)/emerge-xtra.texi \ ++ $(srcdir)/vc-xtra.texi \ ++ $(srcdir)/vc1-xtra.texi \ ++ $(srcdir)/fortran-xtra.texi \ ++ $(srcdir)/msdog-xtra.texi ++ ++EMACSSOURCES= \ ++ $(srcdir)/emacs.texi \ ++ $(srcdir)/doclicense.texi \ ++ $(srcdir)/screen.texi \ ++ $(srcdir)/commands.texi \ ++ $(srcdir)/entering.texi \ ++ $(srcdir)/basic.texi \ ++ $(srcdir)/mini.texi \ ++ $(srcdir)/m-x.texi \ ++ $(srcdir)/help.texi \ ++ $(srcdir)/mark.texi \ ++ $(srcdir)/killing.texi \ ++ $(srcdir)/regs.texi \ ++ $(srcdir)/display.texi \ ++ $(srcdir)/search.texi \ ++ $(srcdir)/fixit.texi \ ++ $(srcdir)/files.texi \ ++ $(srcdir)/buffers.texi \ ++ $(srcdir)/windows.texi \ ++ $(srcdir)/frames.texi \ ++ $(srcdir)/mule.texi \ ++ $(srcdir)/major.texi \ ++ $(srcdir)/indent.texi \ ++ $(srcdir)/text.texi \ ++ $(srcdir)/programs.texi \ ++ $(srcdir)/building.texi \ ++ $(srcdir)/maintaining.texi \ ++ $(srcdir)/abbrevs.texi \ ++ $(srcdir)/sending.texi \ ++ $(srcdir)/rmail.texi \ ++ $(srcdir)/dired.texi \ ++ $(srcdir)/calendar.texi \ ++ $(srcdir)/misc.texi \ ++ $(srcdir)/custom.texi \ ++ $(srcdir)/trouble.texi \ ++ $(srcdir)/cmdargs.texi \ ++ $(srcdir)/xresources.texi \ ++ $(srcdir)/anti.texi \ ++ $(srcdir)/macos.texi \ ++ $(srcdir)/msdog.texi \ ++ $(srcdir)/gnu.texi \ ++ $(srcdir)/glossary.texi \ ++ $(srcdir)/ack.texi \ ++ $(srcdir)/kmacro.texi \ ++ $(EMACS_XTRA) ++ ++info: $(INFO_TARGETS) ++ ++dvi: $(DVI_TARGETS) ++ ++# Note that all the Info targets build the Info files ++# in srcdir. There is no provision for Info files ++# to exist in the build directory. ++# In a distribution of Emacs, the Info files should be up to date. ++ ++$(infodir)/dir: ++ $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) ++ ++$(infodir)/emacs: $(EMACSSOURCES) ++ $(MAKEINFO) emacs.texi ++ ++emacs.dvi: $(EMACSSOURCES) ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs.texi ++ ++emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-xtra.texi ++ ++mostlyclean: ++ - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* ++ ++clean: mostlyclean ++ - $(DEL) *.dvi ++ - $(DEL) $(infodir)/emacs* ++ ++distclean: clean ++ - $(DEL) makefile ++ ++maintainer-clean: distclean ++ - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc ++# Don't delete these, because they are outside the current directory. ++# for file in $(INFO_TARGETS); do rm -f $${file}*; done ++ ++ ++# Formerly this directory had texindex.c and getopt.c in it ++# and this makefile built them to make texindex. ++# That caused trouble because this is run entirely in the source directory. ++# Since we expect to get texi2dvi from elsewhere, ++# it is ok to expect texindex from elsewhere also. +diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi +new file mode 100644 +index 0000000..ca50643 +--- /dev/null ++++ b/doc/emacs/mark.texi +@@ -0,0 +1,453 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Mark, Killing, Help, Top ++@chapter The Mark and the Region ++@cindex mark ++@cindex setting a mark ++@cindex region ++ ++ Many Emacs commands operate on an arbitrary contiguous part of the ++current buffer. To specify the text for such a command to operate on, ++you set @dfn{the mark} at one end of it, and move point to the other ++end. The text between point and the mark is called @dfn{the region}. ++The region always extends between point and the mark, no matter which ++one comes earlier in the text; each time you move point, the region ++changes. ++ ++ Setting the mark at a position in the text also @dfn{activates} it. ++When the mark is active, Emacs indicates the extent of the region by ++highlighting the text within it, using the @code{region} face ++(@pxref{Face Customization}). After certain non-motion commands, ++including any command that changes the text in the buffer, Emacs ++automatically @dfn{deactivates} the mark; this turns off the ++highlighting. You can also explicitly deactivate the mark at any ++time, by typing @kbd{C-g} (@pxref{Quitting}). ++ ++ This default behavior of the mark is known as Transient Mark mode. ++Disabling Transient Mark mode switches Emacs to an alternative ++behavior, in which the mark is always active, which was the default ++prior to Emacs 23. @xref{Persistent Mark}. ++ ++@vindex highlight-nonselected-windows ++ Setting the mark in one buffer has no effect on the marks in other ++buffers. When you return to a buffer with an active mark, the mark is ++at the same place as before. When multiple windows show the same ++buffer, they can have different values of point, and thus different ++regions, but they all share one common mark position. @xref{Windows}. ++Ordinarily, only the selected window highlights its region; however, ++if the variable @code{highlight-nonselected-windows} is ++non-@code{nil}, each window highlights its own region. ++ ++@menu ++* Setting Mark:: Commands to set the mark. ++* Marking Objects:: Commands to put region around textual units. ++* Using Region:: Summary of ways to operate on contents of the region. ++* Mark Ring:: Previous mark positions saved so you can go back there. ++* Global Mark Ring:: Previous mark positions in various buffers. ++* Shift Selection:: Using shifted cursor motion keys. ++* Persistent Mark:: Keeping the mark active all the time. ++@end menu ++ ++@node Setting Mark ++@section Setting the Mark ++ ++ Here are some commands for setting the mark: ++ ++@table @kbd ++@item C-@key{SPC} ++Set the mark at point, and activate it (@code{set-mark-command}). ++@item C-@@ ++The same. ++@item C-x C-x ++Set the mark at point, and move point where the mark was ++(@code{exchange-point-and-mark}). ++@item Drag-Mouse-1 ++Set point and the mark around the text you drag across. ++@item Mouse-3 ++Set the mark at point, then move point to where you click ++(@code{mouse-save-then-kill}). ++@item @samp{Shifted motion keys} ++Set the mark at point if the mark is inactive, then move point. ++@end table ++ ++@kindex C-SPC ++@kindex C-@@ ++@findex set-mark-command ++ The most common way to set the mark is with @kbd{C-@key{SPC}} ++(@code{set-mark-command})@footnote{There is no @kbd{C-@key{SPC}} ++character in @acronym{ASCII}; usually, typing @kbd{C-@key{SPC}} on a ++text terminal gives the character @kbd{C-@@}. This key is also bound ++to @code{set-mark-command}, so unless you are unlucky enough to have ++an text terminal that behaves differently, you might as well think of ++@kbd{C-@@} as @kbd{C-@key{SPC}}.}. This sets the mark where point is, ++and activates it. You can then move point away, leaving the mark ++behind. ++ ++ For example, suppose you wish to convert part of the buffer to upper ++case. To accomplish this, go to the beginning of the desired text, ++type @kbd{C-@key{SPC}}, and move point until the desired portion of ++text is highlighted. Now type @kbd{C-x C-u} (@code{upcase-region}). ++This converts the text in the region to upper case, and then ++deactivates the mark. ++ ++@kindex C-x C-x ++@findex exchange-point-and-mark ++ The command @kbd{C-x C-x} (@code{exchange-point-and-mark}) exchanges ++the positions of point and the mark, keeping the region unchanged. If ++the mark is inactive, Emacs first reactivates the mark wherever it was ++last set. @kbd{C-x C-x} is useful when you are satisfied with the ++position of point but want to move the other end of the region (where ++the mark is). Using @kbd{C-x C-x} a second time, if necessary, puts ++the mark at the new position with point back at its original position. ++ ++ You can also set the mark with the mouse. If you press the left ++mouse button (@kbd{down-mouse-1}) and drag the mouse across a range of ++text while holding down this button, this sets the mark where you ++first pressed the mouse button and puts point where you release it. ++Alternatively, clicking the right mouse button (@kbd{mouse-3}) sets ++the mark at point and then moves point to where you clicked. Using ++the mouse to mark a region also copies the region into the kill ring ++(@pxref{Kill Ring}). @xref{Mouse Commands}, for a more detailed ++description of these mouse commands. ++ ++@cindex shift-selection ++ Finally, you can set the mark by holding down the shift key while ++typing certain cursor motion commands (such as @kbd{S-@key{right}}, ++@kbd{S-C-f}, @kbd{S-C-n}, etc.) This is referred to as ++@dfn{shift-selection}. This sets the mark at point before moving ++point, but only if there is no active mark set via shift-selection. ++The mark set by mouse commands and by shift-selection behaves slightly ++differently from the usual mark: any subsequent unshifted cursor ++motion command deactivates it automatically. For details, @xref{Shift ++Selection}. ++ ++ Whenever the mark is active, you can deactivate it by typing ++@kbd{C-g} (@pxref{Quitting}). The mark is also automatically ++deactivated after certain non-motion commands. ++ ++@node Marking Objects ++@section Commands to Mark Textual Objects ++ ++@cindex marking sections of text ++ Here are the commands for placing point and the mark around a textual ++object such as a word, list, paragraph or page: ++ ++@table @kbd ++@item M-@@ ++Set mark after end of next word (@code{mark-word}). This does not ++move point. ++@item C-M-@@ ++Set mark after end of following balanced expression ++(@code{mark-sexp}). This does not move point. ++@item M-h ++Move point to the beginning of the current paragraph, and set mark at ++the end (@code{mark-paragraph}). ++@item C-M-h ++Move point to the beginning of the current defun, and set mark at the ++end (@code{mark-defun}). ++@item C-x C-p ++Move point to the beginning of the current page, and set mark at the ++end (@code{mark-page}). ++@item C-x h ++Move point to the beginning of the buffer, and set mark at the end ++(@code{mark-whole-buffer}). ++@end table ++ ++@findex mark-word ++@findex mark-sexp ++@kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next ++word, while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the ++next balanced expression (@pxref{Expressions}). These commands handle ++arguments just like @kbd{M-f} and @kbd{C-M-f}. ++ ++@kindex C-x h ++@findex mark-whole-buffer ++ The other commands in the above list set both point and mark, so as ++to delimit an object in the buffer. @kbd{M-h} (@code{mark-paragraph}) ++moves point to the beginning of the paragraph that surrounds or ++follows point, and sets the mark at the end of that paragraph ++(@pxref{Paragraphs}). As a special exception, repeated invocations of ++@kbd{M-h} extend the region to subsequent paragraphs. This is ++convenient for indenting, case-converting, or killing entire ++paragraphs. ++ ++ The @kbd{M-h} command accepts prefix arguments. If the argument's ++value is positive, @kbd{M-h} marks that many paragraphs starting with ++the one surrounding point; therefore, @kbd{C-u M-h} is equivalent to ++@kbd{M-h M-h M-h M-h}. If the prefix argument is @minus{}@var{n}, ++@kbd{M-h} marks @var{n} paragraphs running back from the one ++surrounding point; in this case, point moves forward to the end of ++that paragraph, and the mark goes at the start of the region. ++ ++ Similarly, @kbd{C-M-h} (@code{mark-defun}) sets mark and point ++around major top-level definitions (@pxref{Moving by Defuns}), and ++@kbd{C-x C-p} (@code{mark-page}) does the same for pages ++(@pxref{Pages}). These treat repeated invocations and prefix ++arguments similarly to @code{mark-paragraph}. ++ ++ Finally, @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire ++buffer as the region, by putting point at the beginning and the mark ++at the end. (In some programs this is called ``select all.'') ++ ++@node Using Region ++@section Operating on the Region ++ ++@cindex operations on a marked region ++ Once you have a region, here are some of the ways you can operate on ++it: ++ ++@itemize @bullet ++@item ++Kill it with @kbd{C-w} (@pxref{Killing}). ++@item ++Copy it to the kill ring with @kbd{M-w} (@pxref{Yanking}). ++@item ++Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}). ++@item ++Undo changes within it using @kbd{C-u C-/} (@pxref{Undo}). ++@item ++Replace text within it using @kbd{M-%} (@pxref{Query Replace}). ++@item ++Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}). ++@item ++Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}). ++@item ++Print hardcopy with @kbd{M-x print-region} (@pxref{Printing}). ++@item ++Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). ++@item ++Save it in a register with @kbd{C-x r s} (@pxref{Registers}). ++@item ++Save it in a buffer or a file (@pxref{Accumulating Text}). ++@end itemize ++ ++ Most commands that operate on the text in the region have the word ++@code{region} in their names. ++ ++ Some commands have a default behavior when the mark is inactive, but ++operate on the text in the region if the mark is active. For example, ++@kbd{M-$} (@code{ispell-word}) normally checks the spelling of the ++word at point, but it checks the text in the region if the region is ++active (@pxref{Spelling}). Normally, such commands use their default ++behavior if the region is empty (i.e., if mark and point are at the ++same position). If you want them to operate on the empty region, ++change the variable @code{use-empty-active-region} to @code{t}. ++ ++@cindex Delete Selection mode ++@cindex mode, Delete Selection ++@findex delete-selection-mode ++ If you enable Delete Selection mode, a minor mode, then inserting ++text while the mark is active causes the selected text to be deleted ++first. This also deactivates the mark. Many graphical applications ++follow this convention, but Emacs does not. To toggle Delete ++Selection mode on or off, type @kbd{M-x delete-selection-mode}. ++Another effect of this mode is that some keys, such as @key{DEL} and ++@kbd{C-d}, always kill the region if one exists. ++ ++@node Mark Ring ++@section The Mark Ring ++ ++@cindex mark ring ++ Aside from delimiting the region, the mark is also useful for ++remembering spots that you may want to go back to. Each buffer ++remembers 16 previous locations of the mark, in the @dfn{mark ring}. ++Commands that set the mark also push the old mark onto this ring. ++ ++@table @kbd ++@item C-@key{SPC} C-@key{SPC} ++Set the mark, pushing it onto the mark ring, without activating it. ++@item C-u C-@key{SPC} ++Move point to where the mark was, and restore the mark from the ring ++of former marks. ++@end table ++ ++@kindex C-SPC C-SPC ++ The command C-@key{SPC} C-@key{SPC} is handy when you want to use ++the mark to remember a position to which you may wish to return. It ++pushes the current point onto the mark ring, without activating the ++mark (which would cause Emacs to highlight the region). This is ++actually two consecutive invocations of @kbd{C-@key{SPC}} ++(@code{set-mark-command}); the first @kbd{C-@key{SPC}} sets the mark, ++and the second @kbd{C-@key{SPC}} deactivates it. (When Transient Mark ++mode is off, C-@key{SPC} C-@key{SPC} instead activates Transient Mark ++mode temporarily. @xref{Persistent Mark}.) ++ ++@kindex C-u C-SPC ++ To return to a marked position, use @code{set-mark-command} with a ++prefix argument: @kbd{C-u C-@key{SPC}}. This moves point to where the ++mark was, and deactivates the mark if it was active. Each subsequent ++@kbd{C-u C-@key{SPC}} jumps to a prior position stored in the mark ++ring. The positions you move through in this way are not lost; they ++go to the end of the ring. ++ ++@vindex set-mark-command-repeat-pop ++ If you set @code{set-mark-command-repeat-pop} to non-@code{nil}, ++then immediately after you type @kbd{C-u C-@key{SPC}}, you can type ++@kbd{C-@key{SPC}} instead of @kbd{C-u C-@key{SPC}} to cycle through ++the mark ring. By default, @code{set-mark-command-repeat-pop} is ++@code{nil}. ++ ++ Each buffer has its own mark ring. All editing commands use the ++current buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} ++always stays in the same buffer. ++ ++@vindex mark-ring-max ++ The variable @code{mark-ring-max} specifies the maximum number of ++entries to keep in the mark ring. If that many entries exist and ++another one is pushed, the earliest one in the list is discarded. Repeating ++@kbd{C-u C-@key{SPC}} cycles through the positions currently in the ++ring. ++ ++@vindex mark-even-if-inactive ++ If the variable @code{mark-even-if-inactive} is @code{nil}, commands ++can only use the mark and the region when it is active. This variable ++is non-@code{nil} by default. ++ ++ If you want to move back to the same place over and over, the mark ++ring may not be convenient enough. If so, you can record the position ++in a register for later retrieval (@pxref{RegPos,, Saving Positions in ++Registers}). ++ ++@node Global Mark Ring ++@section The Global Mark Ring ++@cindex global mark ring ++ ++ In addition to the ordinary mark ring that belongs to each buffer, ++Emacs has a single @dfn{global mark ring}. Each time you set a mark, ++in any buffer, this is recorded in the global mark ring in addition to ++the current buffer's own mark ring. ++ ++@kindex C-x C-@key{SPC} ++@findex pop-global-mark ++ The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to ++the buffer and position of the latest entry in the global ring. It also ++rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take ++you to earlier buffers and mark positions. ++ ++@node Shift Selection ++@section Shift Selection ++@cindex shift-selection ++ ++ If you hold down the shift key while typing a cursor motion command, ++this sets the mark before moving point, so that the region extends ++from the original position of point to its new position. This ++feature, newly introduced in Emacs 23, is referred to as ++@dfn{shift-selection}. It is similar to the way text is selected in ++other editors. ++ ++ The mark set via shift-selection behaves a little differently from ++what we have described above. Firstly, in addition to the usual ways ++of deactivating the mark (such as changing the buffer text or typing ++@kbd{C-g}), the mark is deactivated by any @emph{unshifted} cursor ++motion command. Secondly, any subsequent @emph{shifted} cursor motion ++command avoids setting the mark anew. Therefore, a series of shifted ++cursor motion commands will continuously extend the region. ++ ++ Shift-selection only works if the shifted cursor motion key is not ++already bound to a separate command (@pxref{Customization}). For ++example, if you bind @kbd{S-C-f} to another command, typing ++@kbd{S-C-f} runs that command instead of performing a shift-selected ++version of @kbd{C-f} (@code{forward-char}). ++ ++ A mark set via mouse commands behaves the same as a mark set via ++shift-selection (@pxref{Setting Mark}). For example, if you specify a ++region by dragging the mouse, you can continue to extend the region ++using shifted cursor motion commands. In either case, any unshifted ++cursor motion command deactivates the mark. ++ ++ To turn off shift-selection, set @code{shift-select-mode} to ++@code{nil}. Doing this does not disable setting the mark via mouse ++commands. ++ ++@node Persistent Mark ++@section Persistent Marks ++@cindex mode, Transient Mark ++@cindex Transient Mark mode ++@cindex highlighting region ++@cindex region highlighting ++@cindex Zmacs mode ++ ++ By default, the mark is activated by setting it, and deactivated by ++most non-motion commands (including all commands that change the text ++in the buffer). This behavior is called Transient Mark ++mode@footnote{It is also sometimes called @dfn{Zmacs mode}, because ++the Zmacs editor on the MIT Lisp Machine handled the mark in a similar ++way.}. ++ ++ Turning off Transient Mark mode switches Emacs to an alternative ++mode of operation, which was the default prior to Emacs 23. When ++Transient Mark mode is off, the mark is @emph{never} deactivated, but ++it can be set to different locations using commands such as ++@kbd{C-@key{SPC}}. Emacs does not highlight the region, because that ++would be a nuisance. As a special exception, the region is ++temporarily highlighted if you set it with the mouse (@pxref{Setting ++Mark}), or with shift-selection (@pxref{Shift Selection}). ++ ++@findex transient-mark-mode ++ To turn off Transient Mark mode, type @kbd{M-x transient-mark-mode}. ++This command toggles the mode; you can use the same command to turn ++Transient Mark mode on again. You can also turn off Transient Mark ++mode using the menu bar: in the @samp{Options} menu, toggle the ++@samp{Active Region Highlighting} menu item. ++ ++ Here are the details of how Emacs behaves when Transient Mark mode ++is off: ++ ++@itemize @bullet ++@item ++Emacs does not show where the mark is located---you have to remember. ++The usual solution to this problem is to set the mark and then use it ++soon, before you forget where it is. Alternatively, you can check the ++location of the mark by using @kbd{C-x C-x}, which exchanges the ++positions of the point and the mark (@pxref{Setting Mark}). ++ ++@item ++Many commands that insert text, such as @kbd{C-y} (@code{yank}), ++position point and the mark at opposite ends of the inserted text, so ++that the region consists of the text just inserted. You can tell when ++a command sets the mark because it displays @samp{Mark set} in the ++echo area. ++ ++@item ++Many commands that move point long distances, like @kbd{M-<} and ++@kbd{C-s}, first set the mark where point was. ++ ++@item ++Some commands, which ordinarily operate on the region when the mark is ++active, instead act on the entire buffer. For instance, @kbd{C-x u} ++normally reverses changes within the region if the mark is active; ++when Transient Mark mode is off, it acts on the entire buffer. ++However, you can type @kbd{C-u C-x u} to make it operate on the ++region. @xref{Undo}. Other commands that act this way are identified ++in their own documentation. ++@end itemize ++ ++ While Transient Mark mode is off, you can activate it temporarily ++using @kbd{C-@key{SPC} C-@key{SPC}} or @kbd{C-u C-x C-x}. ++ ++@table @kbd ++@item C-@key{SPC} C-@key{SPC} ++@kindex C-@key{SPC} C-@key{SPC} ++Set the mark at point (like plain @kbd{C-@key{SPC}}) and enable ++Transient Mark mode just once, until the mark is deactivated. (This ++is not really a separate command; you are using the @kbd{C-@key{SPC}} ++command twice.) ++ ++@item C-u C-x C-x ++@kindex C-u C-x C-x ++Activate the mark without changing it; enable Transient Mark mode just ++once, until the mark is deactivated. (This is the @kbd{C-x C-x} ++command, @code{exchange-point-and-mark}, with a prefix argument.) ++@end table ++ ++ These commands set or activate the mark, and enable Transient Mark ++mode only until the mark is deactivated. One reason you may want to ++use them is that some commands operate on the entire buffer instead of ++the region when Transient Mark mode is off. Enabling Transient Mark ++mode momentarily gives you a way to use these commands on the region. ++ ++@ignore ++ arch-tag: f35e4d82-911b-4cfc-a3d7-3c87b2abba20 ++@end ignore +diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi +new file mode 100644 +index 0000000..37d483d +--- /dev/null ++++ b/doc/emacs/mini.texi +@@ -0,0 +1,658 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Minibuffer, M-x, Basic, Top ++@chapter The Minibuffer ++@cindex minibuffer ++ ++ The @dfn{minibuffer} is where Emacs commands read complicated ++arguments, such as file names, buffer names, Emacs command names, or ++Lisp expressions. We call it the ``minibuffer'' because it's a ++special-purpose buffer with a small amount of screen space. You can ++use the usual Emacs editing commands in the minibuffer to edit the ++argument text. ++ ++@cindex prompt ++ When the minibuffer is in use, it appears in the echo area, with a ++cursor. The minibuffer display starts with a @dfn{prompt} in a ++distinct color, usually ending with a colon. The prompt states what ++kind of input is expected, and how it will be used. ++ ++ The simplest way to enter a minibuffer argument is to type the text, ++then @key{RET} to submit the argument and exit the minibuffer. You ++can cancel the minibuffer, and the command that wants the argument, by ++typing @kbd{C-g}. ++ ++@cindex default argument ++ Sometimes, a @dfn{default argument} appears in the prompt, inside ++parentheses before the colon. The default will be used as the ++argument value if you just type @key{RET}. For example, commands that ++read buffer names usually show a buffer name as the default; you can ++type @key{RET} to operate on that default buffer. ++ ++ Since the minibuffer appears in the echo area, it can conflict with ++other uses of the echo area. If an error occurs while the minibuffer ++is active, the error message hides the minibuffer for a few seconds, ++or until you type something; then the minibuffer comes back. If a ++command such as @kbd{C-x =} needs to display a message in the echo ++area, the message hides the minibuffer for a few seconds, or until you ++type something; then the minibuffer comes back. While the minibuffer ++is in use, keystrokes do not echo. ++ ++@menu ++* Minibuffer File:: Entering file names with the minibuffer. ++* Minibuffer Edit:: How to edit in the minibuffer. ++* Completion:: An abbreviation facility for minibuffer input. ++* Minibuffer History:: Reusing recent minibuffer arguments. ++* Repetition:: Re-executing commands that used the minibuffer. ++* Passwords:: Entering passwords in the echo area. ++@end menu ++ ++@node Minibuffer File ++@section Minibuffers for File Names ++ ++ Commands such as @kbd{C-x C-f} (@code{find-file}) use the minibuffer ++to read a file name argument (@pxref{Basic Files}). When the ++minibuffer is used to read a file name, it typically starts out with ++some initial text ending in a slash. This is the @dfn{default ++directory}. For example, it may start out like this: ++ ++@example ++Find File: /u2/emacs/src/ ++@end example ++ ++@noindent ++Here, @samp{Find File:@: } is the prompt and @samp{/u2/emacs/src/} is ++the default directory. If you now type @kbd{buffer.c} as input, that ++specifies the file @file{/u2/emacs/src/buffer.c}. @xref{File Names}, ++for information about the default directory. ++ ++ You can specify the parent directory by adding @file{..}: for ++example, @file{/u2/emacs/src/../lisp/simple.el} is equivalent to ++@file{/u2/emacs/lisp/simple.el}. Alternatively, you can use ++@kbd{M-@key{DEL}} to kill directory names backwards (@pxref{Words}). ++ ++ To specify a file in a completely different directory, you can kill ++the entire default with @kbd{C-a C-k} (@pxref{Minibuffer Edit}). ++Alternatively, you can ignore the default, and enter an absolute file ++name starting with a slash or a tilde after the default directory. ++For example, you can specify @file{/etc/termcap} as follows: ++ ++@example ++Find File: /u2/emacs/src//etc/termcap ++@end example ++ ++@noindent ++@cindex // in file name ++@cindex double slash in file name ++@cindex slashes repeated in file name ++@findex file-name-shadow-mode ++Emacs interprets a double slash as ``ignore everything before the ++second slash in the pair.'' In the example above, ++@file{/u2/emacs/src/} is ignored, so the argument you supplied is ++@file{/etc/termcap}. The ignored part of the file name is dimmed if ++the terminal allows it (to disable this dimming, turn off File Name ++Shadow mode with the command @kbd{M-x file-name-shadow-mode}.) ++ ++@cindex home directory shorthand ++ Emacs interprets @file{~/} as your home directory. Thus, ++@file{~/foo/bar.txt} specifies a file named @file{bar.txt}, inside a ++directory named @file{foo}, which is in turn located in your home ++directory. In addition, @file{~@var{user-id}/} means the home ++directory of a user whose login name is @var{user-id}. Any leading ++directory name in front of the @file{~} is ignored: thus, ++@file{/u2/emacs/~/foo/bar.txt} is equivalent to @file{~/foo/bar.txt}. ++ ++ On MS-Windows and MS-DOS systems, where a user doesn't always have a ++home directory, Emacs uses several alternatives. For MS-Windows, see ++@ref{Windows HOME}; for MS-DOS, see ++@ifnottex ++@ref{MS-DOS File Names, HOME on MS-DOS}. ++@end ifnottex ++@iftex ++@ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the Emacs Manual}, in ++the main Emacs manual. ++@end iftex ++On these systems, the @file{~@var{user-id}/} construct is supported ++only for the current user, i.e., only if @var{user-id} is the current ++user's login name. ++ ++@vindex insert-default-directory ++ To prevent Emacs from inserting the default directory when reading ++file names, change the variable @code{insert-default-directory} to ++@code{nil}. In that case, the minibuffer starts out empty. ++Nonetheless, relative file name arguments are still interpreted based ++on the same default directory. ++ ++@node Minibuffer Edit ++@section Editing in the Minibuffer ++ ++ The minibuffer is an Emacs buffer, albeit a peculiar one, and the ++usual Emacs commands are available for editing the argument text. ++(The prompt, however, is @dfn{read-only}, and cannot be changed.) ++ ++ Since @key{RET} in the minibuffer is defined to exit the minibuffer, ++you can't use it to insert a newline in the minibuffer. To do that, ++type @kbd{C-o} or @kbd{C-q C-j}. (The newline character is really the ++@acronym{ASCII} character control-J.) ++ ++ Inside a minibuffer, the keys @kbd{@key{TAB}}, @kbd{@key{SPC}}, and ++@kbd{@key{?}} are often bound to commands that perform ++@dfn{completion}. @xref{Completion}. You can use @kbd{C-q} ++(@code{quoted-insert}) to insert a @key{TAB}, @key{SPC}, or @key{?} ++character. For example, @kbd{C-q @key{TAB}} inserts a @key{TAB} ++character. @xref{Inserting Text}. ++ ++ For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a ++minibuffer moves point to the beginning of the argument text, not the ++beginning of the prompt. For example, this allows you to erase the ++entire argument with @kbd{C-a C-k}. ++ ++@cindex height of minibuffer ++@cindex size of minibuffer ++@cindex growing minibuffer ++@cindex resizing minibuffer ++ When the minibuffer is active, the echo area is treated much like an ++ordinary Emacs window. For instance, you can switch to another window ++(with @kbd{C-x o}), edit text there, then return to the minibuffer ++window to finish the argument. You can even kill text in another ++window, return to the minibuffer window, and yank the text into the ++argument. There are some restrictions on the minibuffer window, ++however: for instance, you cannot split it. @xref{Windows}. ++ ++@vindex resize-mini-windows ++ Normally, the minibuffer window occupies a single screen line. ++However, if you add two or more lines' worth of text into the ++minibuffer, it expands automatically to accomodate the text. The ++variable @code{resize-mini-windows} controls the resizing of the ++minibuffer. The default value is @code{grow-only}, which means the ++behavior we have just described. If the value is @code{t}, the ++minibuffer window will also shrink automatically if you remove some ++lines of text from the minibuffer, down to a minimum of one screen ++line. If the value is @code{nil}, the minibuffer window never changes ++size automatically, but you can use the usual window-resizing commands ++on it (@pxref{Windows}). ++ ++@vindex max-mini-window-height ++ The variable @code{max-mini-window-height} controls the maximum ++height for resizing the minibuffer window. A floating-point number ++specifies a fraction of the frame's height; an integer specifies the ++maximum number of lines; @code{nil} means do not resize the minibuffer ++window automatically. The default value is 0.25. ++ ++ The @kbd{C-M-v} command in the minibuffer scrolls the help text from ++commands that display help text of any sort in another window. You ++can also scroll the help text with @kbd{M-@key{prior}} and ++@kbd{M-@key{next}} (or, equivalently, @kbd{M-@key{PageUp}} and ++@kbd{M-@key{PageDown}}). This is especially useful with long lists of ++possible completions. @xref{Other Window}. ++ ++@vindex enable-recursive-minibuffers ++ Emacs normally disallows most commands that use the minibuffer while ++the minibuffer is active. To allow such commands in the minibuffer, ++set the variable @code{enable-recursive-minibuffers} to @code{t}. ++ ++@node Completion ++@section Completion ++@c This node is referenced in the tutorial. When renaming or deleting ++@c it, the tutorial needs to be adjusted. ++@cindex completion ++ ++ Sometimes, you can use a feature called @dfn{completion} to help you ++enter arguments. This means that after you type part of the argument, ++Emacs can fill in the rest, or some of it, based on what you have ++typed so far. ++ ++ When completion is available, certain keys (usually @key{TAB}, ++@key{RET}, and @key{SPC}) are rebound to complete the text in the ++minibuffer into a longer string chosen from a set of @dfn{completion ++alternatives}. The set of completion alternatives depends on the ++command that requested the argument, and on what you have typed so ++far. In addition, you can usually type @kbd{?} to display a list of ++possible completions. ++ ++ For example, @kbd{M-x} uses the minibuffer to read the name of a ++command, so completion works by matching the minibuffer text against ++the names of existing Emacs commands. So, to run the command ++@code{insert-buffer}, you can type @kbd{M-x ins @key{SPC} b @key{RET}} ++instead of the full @kbd{M-x insert-buffer @key{RET}}. ++ ++ Case is significant in completion when it is significant in the ++argument you are entering, such as command names. Thus, ++@samp{insert-buffer} is not a valid completion for @samp{IN}. ++Completion ignores case distinctions for certain arguments in which ++case does not matter. ++ ++@menu ++* Example: Completion Example. Examples of using completion. ++* Commands: Completion Commands. A list of completion commands. ++* Strict Completion:: Different types of completion. ++* Options: Completion Options. Options for completion. ++@end menu ++ ++@node Completion Example ++@subsection Completion Example ++ ++@kindex TAB @r{(completion)} ++ A concrete example may help here. If you type @kbd{M-x a u ++@key{TAB}}, the @key{TAB} looks for alternatives (in this case, ++command names) that start with @samp{au}. There are several, ++including @code{auto-fill-mode} and @code{autoconf-mode}, but they all ++begin with @code{auto}, so the @samp{au} in the minibuffer completes ++to @samp{auto}. ++ ++ If you type @key{TAB} again immediately, it cannot determine the ++next character; it could be @samp{-}, @samp{a}, or @samp{c}. So it ++does not add any characters; instead, @key{TAB} displays a list of all ++possible completions in another window. ++ ++ Next, type @kbd{- f}. The minibuffer now contains @samp{auto-f}, ++and the only command name that starts with this is ++@code{auto-fill-mode}. If you now type @key{TAB}, completion fills in ++the rest of the argument @samp{auto-fill-mode} into the minibuffer. ++You have been able to enter @samp{auto-fill-mode} by typing just ++@kbd{a u @key{TAB} - f @key{TAB}}. ++ ++@node Completion Commands ++@subsection Completion Commands ++ ++ Here is a list of the completion commands defined in the minibuffer ++when completion is allowed. ++ ++@table @kbd ++@item @key{TAB} ++@findex minibuffer-complete ++Complete the text in the minibuffer as much as possible; if unable to ++complete, display a list of possible completions ++(@code{minibuffer-complete}). ++@item @key{SPC} ++Complete up to one word from the minibuffer text before point ++(@code{minibuffer-complete-word}). @key{SPC} for completion is not ++available when entering a file name, since file names often include ++spaces. ++@item @key{RET} ++Submit the text in the minibuffer as the argument, possibly completing ++first as described in the next ++@iftex ++subsection (@code{minibuffer-complete-and-exit}). ++@end iftex ++@ifnottex ++node (@code{minibuffer-complete-and-exit}). @xref{Strict Completion}. ++@end ifnottex ++@item ? ++Display a list of possible completions of the text before point ++(@code{minibuffer-completion-help}). ++@end table ++ ++@kindex TAB ++@findex minibuffer-complete ++ @key{TAB} (@code{minibuffer-complete}) is the most fundamental ++completion command. It searches for all possible completion ++alternatives that match the existing minibuffer text, and attempts to ++complete as much as it can. The matching of completion alternatives ++to the minibuffer text is performed according to somewhat intricate ++rules, which are designed so that plausible completions are offered ++under most circumstances. A valid completion alternative must satisfy ++the following criteria: ++ ++@itemize @bullet ++@item ++The minibuffer text before point must be the same as the beginning of ++the completion alternative. If there is any minibuffer text after ++point, it must be a substring of the remainder of the completion ++alternative. ++ ++@item ++If no completion alternative satisfies the above rules, try using ++@dfn{partial completion} rules: divide the minibuffer text into words ++separated by hyphens or spaces, and complete each word separately. ++Thus, when completing command names, @samp{em-l-m} completes to ++@samp{emacs-lisp-mode}. ++ ++@item ++If there is still no completion alternative, try the first rule again, ++but ignore the minibuffer text after point (i.e., don't try matching ++it). ++@end itemize ++ ++@noindent ++When performing these comparisons, a @samp{*} in the minibuffer text ++acts as a @dfn{wildcard}---it matches any character at the ++corresponding position in the completion alternative. ++ ++@kindex SPC ++@findex minibuffer-complete-word ++ @key{SPC} (@code{minibuffer-complete-word}) completes like ++@key{TAB}, but only up to the next hyphen or space. If you have ++@samp{auto-f} in the minibuffer and type @key{SPC}, it finds that the ++completion is @samp{auto-fill-mode}, but it only inserts @samp{ill-}, ++giving @samp{auto-fill-}. Another @key{SPC} at this point completes ++all the way to @samp{auto-fill-mode}. ++ ++ If @key{TAB} or @key{SPC} is unable to complete, it displays a list ++of possible completions (if there are any) in a separate window. You ++can choose a completion from this list using the following commands: ++ ++@table @kbd ++@findex mouse-choose-completion ++@item Mouse-1 ++@itemx Mouse-2 ++Clicking mouse button 1 or 2 on a completion possibility chooses that ++completion (@code{mouse-choose-completion}). ++ ++@findex switch-to-completions ++@item M-v ++@itemx @key{PageUp} ++@itemx @key{prior} ++Typing @kbd{M-v}, while in the minibuffer, selects the window showing ++the completion list buffer (@code{switch-to-completions}). This paves ++the way for using the commands below. Typing @key{PageUp} or ++@key{prior} does the same, as does selecting that window in other ++ways. ++ ++@findex choose-completion ++@item @key{RET} ++Typing @key{RET}, while in the completion list buffer, chooses the ++completion that point is in or next to (@code{choose-completion}). To ++use this command, you must first switch to the completion list window. ++ ++@findex next-completion ++@item @key{Right} ++Typing the right-arrow key @key{Right}, while in the completion list ++buffer, moves point to the following completion possibility ++(@code{next-completion}). ++ ++@findex previous-completion ++@item @key{Left} ++Typing the left-arrow key @key{Left}, while in the completion list ++buffer, moves point to the previous completion possibility ++(@code{previous-completion}). ++@end table ++ ++@node Strict Completion ++@subsection Strict Completion ++ ++ There are three different ways that @key{RET} can do completion, ++depending on how the argument will be used. ++ ++@itemize @bullet ++@item ++@dfn{Strict} completion accepts only known completion candidates. For ++example, when @kbd{C-x k} reads the name of a buffer to kill, only the ++name of an existing buffer makes sense. In strict completion, ++@key{RET} refuses to exit if the text in the minibuffer does not ++complete to an exact match. ++ ++@item ++@dfn{Cautious} completion is similar to strict completion, except that ++@key{RET} exits only if the text is an already exact match. ++Otherwise, @key{RET} does not exit, but it does complete the text. If ++that completes to an exact match, a second @key{RET} will exit. ++ ++Cautious completion is used for reading file names for files that must ++already exist, for example. ++ ++@item ++@dfn{Permissive} completion allows any input; the completion ++candidates are just suggestions. For example, when @kbd{C-x C-f} ++reads the name of a file to visit, any file name is allowed, including ++nonexistent file (in case you want to create a file). In permissive ++completion, @key{RET} does not complete, it just submits the argument ++as you have entered it. ++@end itemize ++ ++ The completion commands display a list of all possible completions ++whenever they can't determine even one more character by completion. ++Also, typing @kbd{?} explicitly requests such a list. You can scroll ++the list with @kbd{C-M-v} (@pxref{Other Window}). ++ ++@node Completion Options ++@subsection Completion Options ++ ++@vindex completion-auto-help ++ If @code{completion-auto-help} is set to @code{nil}, the completion ++commands never display the completion list buffer; you must type ++@kbd{?} to display the list. If the value is @code{lazy}, Emacs only ++shows the completion list buffer on the second attempt to complete. ++In other words, if there is nothing to complete, the first @key{TAB} ++echoes @samp{Next char not unique}; the second @key{TAB} does the ++completion list buffer. ++ ++@vindex completion-ignored-extensions ++@cindex ignored file names, in completion ++ When completing file names, certain file names are usually ignored. ++The variable @code{completion-ignored-extensions} contains a list of ++strings; a file name ending in any of those strings is ignored as a ++completion candidate. The standard value of this variable has several ++elements including @code{".o"}, @code{".elc"}, and @code{"~"}. For ++example, if a directory contains @samp{foo.c} and @samp{foo.elc}, ++@samp{foo} completes to @samp{foo.c}. However, if @emph{all} possible ++completions end in ``ignored'' strings, they are not ignored: in the ++previous example, @samp{foo.e} completes to @samp{foo.elc}. ++Displaying a list of possible completions disregards ++@code{completion-ignored-extensions}; it shows them all. ++ ++ If an element of @code{completion-ignored-extensions} ends in a ++slash (@file{/}), it's a subdirectory name; that directory and its ++contents are ignored. Elements of ++@code{completion-ignored-extensions} that do not end in a slash are ++ordinary file names. ++ ++@cindex case-sensitivity and completion ++@vindex read-file-name-completion-ignore-case ++@vindex read-buffer-completion-ignore-case ++ When completing file names, Emacs ignores case differences if the ++variable @code{read-file-name-completion-ignore-case} is ++non-@code{nil}. The default value is @code{nil} on systems that have ++case-sensitive file-names, such as GNU/Linux; it is non-@code{nil} on ++systems that have case-insensitive file-names, such as Microsoft ++Windows. When completing buffer names, Emacs ignores case differences ++if @code{read-buffer-completion-ignore-case} is non-@code{nil} (the ++default value is @code{nil}). ++ ++@vindex completion-styles ++ You can customize the matching rules for completion alternatives ++using the variable @code{completion-styles}. Its value should be a ++list of symbols, each representing a @dfn{completion style}; valid ++style symbols are @code{basic}, @code{partial-completion}, ++@code{emacs22}, and @code{emacs21}. When completing, Emacs attempts ++to use the first completion style in the list; if this does not return ++any completion alternatives, it tries the next completion style in the ++list, and so on. The completion rules described in @ref{Completion ++Commands} correspond to the default value of @code{completion-styles}, ++which is @code{(basic partial-completion emacs22)}. ++ ++@cindex Icomplete mode ++@findex icomplete-mode ++ Icomplete mode presents a constantly-updated display that tells you ++what completions are available for the text you've entered so far. The ++command to enable or disable this minor mode is @kbd{M-x ++icomplete-mode}. ++ ++@node Minibuffer History ++@section Minibuffer History ++@cindex minibuffer history ++@cindex history of minibuffer input ++ ++ Every argument that you enter with the minibuffer is saved in a ++@dfn{minibuffer history list} so you can easily use it again later. ++You can use the following arguments to quickly fetch an earlier ++argument into the minibuffer: ++ ++@table @kbd ++@item M-p ++@itemx @key{Up} ++Move to the previous item in the minibuffer history, an earlier ++argument (@code{previous-history-element}). ++@item M-n ++@itemx @key{Down} ++Move to the next item in the minibuffer history ++(@code{next-history-element}). ++@item M-r @var{regexp} @key{RET} ++Move to an earlier item in the minibuffer history that ++matches @var{regexp} (@code{previous-matching-history-element}). ++@item M-s @var{regexp} @key{RET} ++Move to a later item in the minibuffer history that matches ++@var{regexp} (@code{next-matching-history-element}). ++@end table ++ ++@kindex M-p @r{(minibuffer history)} ++@kindex M-n @r{(minibuffer history)} ++@findex next-history-element ++@findex previous-history-element ++ While in the minibuffer, typing @kbd{M-p} or @key{Up} ++(@code{previous-history-element}) moves up through the minibuffer ++history list, one item at a time. Each @kbd{M-p} fetches an earlier ++item from the history list into the minibuffer, replacing its existing ++contents. Similarly, typing @kbd{M-n} or @key{Down} ++(@code{next-history-element}) moves back down the history list, ++fetching later entries into the minibuffer. You can think of these ++commands as ``backwards'' and ``forwards'' through the history list. ++ ++ If you type @kbd{M-n} in the minibuffer when there are no later ++entries in the minibuffer history (e.g., if you haven't previously ++typed @kbd{M-p}), Emacs tries fetching from a list of default ++argument: values that you are likely to enter. You can think of this ++as moving through the ``future list'' instead of the ``history list''. ++ ++ The input that @kbd{M-p} or @kbd{M-n} fetches into the minibuffer ++entirely replaces the existing contents of the minibuffer, so you can ++simply type @key{RET} to use it as an argument. You can also edit the ++text before you reuse it; this does not change the history element ++that you ``moved'' to, but your new argument does go at the end of the ++history list in its own right. ++ ++@findex previous-matching-history-element ++@findex next-matching-history-element ++@kindex M-r @r{(minibuffer history)} ++@kindex M-s @r{(minibuffer history)} ++ There are also commands to search forward or backward through the ++history; they search for history elements that match a regular ++expression. @kbd{M-r} (@code{previous-matching-history-element}) ++searches older elements in the history, while @kbd{M-s} ++(@code{next-matching-history-element}) searches newer elements. These ++commands are unusual: they use the minibuffer to read the regular ++expression even though they are invoked from the minibuffer. As with ++incremental searching, an upper-case letter in the regular expression ++makes the search case-sensitive (@pxref{Search Case}). You can also ++search through the history using an incremental search (@pxref{Isearch ++Minibuffer}). ++ ++ All uses of the minibuffer record your input on a history list, but ++there are separate history lists for different kinds of arguments. ++For example, there is a list for file names, used by all the commands ++that read file names. (As a special feature, this history list ++records the absolute file name, even if the name you entered was not ++absolute.) ++ ++ There are several other specific history lists, including one for ++buffer names, one for arguments of commands like @code{query-replace}, ++one used by @kbd{M-x} for command names, and one used by ++@code{compile} for compilation commands. Finally, there is one ++``miscellaneous'' history list that most minibuffer arguments use. ++ ++@vindex history-length ++ The variable @code{history-length} specifies the maximum length of a ++minibuffer history list; adding a new element deletes the oldest ++element if the list gets too long. If the value of ++@code{history-length} is @code{t}, there is no maximum length. ++ ++@vindex history-delete-duplicates ++ The variable @code{history-delete-duplicates} specifies whether to ++delete duplicates in history. If it is non-@code{nil}, adding a new ++element deletes from the list all other elements that are equal to it. ++The default is @code{nil}. ++ ++@node Repetition ++@section Repeating Minibuffer Commands ++@cindex command history ++@cindex history of commands ++ ++ Every command that uses the minibuffer once is recorded on a special ++history list, the @dfn{command history}, together with the values of ++its arguments, so that you can repeat the entire command. In ++particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} ++uses the minibuffer to read the command name. ++ ++@findex list-command-history ++@table @kbd ++@item C-x @key{ESC} @key{ESC} ++Re-execute a recent minibuffer command from the command history ++ (@code{repeat-complex-command}). ++@item M-x list-command-history ++Display the entire command history, showing all the commands ++@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. ++@end table ++ ++@kindex C-x ESC ESC ++@findex repeat-complex-command ++ @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent command ++that used the minibuffer. With no argument, it repeats the last such ++command. A numeric argument specifies which command to repeat; 1 ++means the last one, 2 the previous, and so on. ++ ++ @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command ++into a Lisp expression and then entering a minibuffer initialized with ++the text for that expression. Even if you don't understand Lisp ++syntax, it will probably be obvious which command is displayed for ++repetition. If you type just @key{RET}, that repeats the command ++unchanged. You can also change the command by editing the Lisp ++expression before you execute it. The repeated command is added to ++the front of the command history unless it is identical to the most ++recently item. ++ ++ Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can ++use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r}, ++@kbd{M-s}; @pxref{Minibuffer History}) to move through the history list ++of saved entire commands. After finding the desired previous command, ++you can edit its expression as usual and then repeat it by typing ++@key{RET}. ++ ++@vindex isearch-resume-in-command-history ++ Incremental search does not, strictly speaking, use the minibuffer. ++Therefore, although it behaves like a complex command, it normally ++does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. ++You can make incremental search commands appear in the history by ++setting @code{isearch-resume-in-command-history} to a non-@code{nil} ++value. @xref{Incremental Search}. ++ ++@vindex command-history ++ The list of previous minibuffer-using commands is stored as a Lisp ++list in the variable @code{command-history}. Each element is a Lisp ++expression which describes one command and its arguments. Lisp programs ++can re-execute a command by calling @code{eval} with the ++@code{command-history} element. ++ ++@node Passwords ++@section Entering passwords ++ ++Sometimes, you may need to enter a password into Emacs. For instance, ++when you tell Emacs to visit a file on another machine via a network ++protocol such as FTP, you often need to supply a password to gain ++access to the machine (@pxref{Remote Files}). ++ ++ Entering a password is, in a basic sense, similar to using a ++minibuffer. Emacs displays a prompt in the echo area (such as ++@samp{Password: }); after you type the required password, press ++@key{RET} to submit it. To prevent others from seeing your password, ++every character you type is displayed as a dot (@samp{.}) instead of ++its usual form. ++ ++ Most of the features and commands associated with the minibuffer can ++@emph{not} be used when entering a password. There is no history or ++completion, and you cannot change windows or perform any other action ++with Emacs until you have submitted the password. ++ ++ While you are typing the password, you may press @key{DEL} to delete ++backwards, removing the last character entered. @key{C-u} deletes ++everything you have typed so far. @kbd{C-g} quits the password prompt ++(@pxref{Quitting}). @kbd{C-y} inserts the current kill into the ++password (@pxref{Killing}). You may type either @key{RET} or ++@key{ESC} to submit the password. Any other self-inserting character ++key inserts the associated character into the password, and all other ++input is ignored. ++ ++@ignore ++ arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f ++@end ignore +diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi +new file mode 100644 +index 0000000..29f7f27 +--- /dev/null ++++ b/doc/emacs/misc.texi +@@ -0,0 +1,2852 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@iftex ++@chapter Miscellaneous Commands ++ ++ This chapter contains several brief topics that do not fit anywhere ++else: viewing ``document files'', reading netnews, running shell ++commands and shell subprocesses, using a single shared Emacs for ++utilities that expect to run an editor as a subprocess, printing ++hardcopy, sorting text, narrowing display to part of the buffer, ++editing double-column files and binary files, saving an Emacs session ++for later resumption, following hyperlinks, browsing images, emulating ++other editors, and various diversions and amusements. ++ ++@end iftex ++ ++@ifnottex ++@raisesections ++@end ifnottex ++ ++@node Document View, Gnus, Calendar/Diary, Top ++@section Document Viewing ++@cindex DVI file ++@cindex PDF file ++@cindex PS file ++@cindex Postscript file ++@cindex DocView mode ++@cindex mode, DocView ++@cindex document viewer (DocView) ++@findex doc-view-mode ++ ++DocView mode (@code{doc-view-mode}) is a viewer for DVI, Postscript ++(PS), and PDF documents. It provides features such as slicing, ++zooming, and searching inside documents. It works by converting the ++document to a set of images using the @command{gs} (GhostScript) ++command, and displaying those images. ++ ++@findex doc-view-toggle-display ++@findex doc-view-toggle-display ++@cindex doc-view-minor-mode ++ When you visit a PDF or DVI file, Emacs automatically switches to ++DocView mode. When you visit a Postscript file, Emacs switches to PS ++mode, a major mode for editing Postscript files as text; however, it ++also enables DocView minor mode, so you can type @kbd{C-c C-c} to view ++the document with DocView. (PDF and DVI files, unlike Postscript ++files, are not usually human-editable.) In either case, repeating ++@kbd{C-c C-c} (@code{doc-view-toggle-display}) toggles between DocView ++and the file text. ++ ++ You can explicitly toggle DocView mode with the command @code{M-x ++doc-view-mode}, and DocView minor mode with the command @code{M-x ++doc-view-minor-mode}. ++ ++ When DocView mode starts, it displays a welcome screen and begins ++formatting the file, page by page. It displays the first page once ++that has been formatted. ++ ++@findex doc-view-enlarge ++@findex doc-view-shrink ++@vindex doc-view-resolution ++ When in DocView mode, you can enlarge or shrink the document with ++@kbd{+} (@code{doc-view-enlarge}) and @kbd{-} ++(@code{doc-view-shrink}). To specify the default size for DocView, ++set or customize the variable @code{doc-view-resolution}. ++ ++ To kill the DocView buffer, type @kbd{k} ++(@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q} ++(@code{quit-window}). ++ ++@menu ++* Navigation:: Navigation inside DocView buffers. ++* Searching:: Searching inside documents. ++* Slicing:: Specifying which part of pages should be displayed. ++* Conversion:: Influencing and triggering conversion. ++@end menu ++ ++@node Navigation ++@subsection Navigation ++ ++When in DocView mode, you can scroll the current page using the usual ++Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and ++the arrow keys. ++ ++@findex doc-view-next-page ++@findex doc-view-previous-page ++ To display the next page, type @kbd{n}, @key{next} or @kbd{C-x ]} ++(@code{doc-view-next-page}). To display the previous page, type ++@kbd{p}, @key{prior} or @kbd{C-x [} (@code{doc-view-previous-page}). ++ ++@findex doc-view-scroll-up-or-next-page ++@findex doc-view-scroll-down-or-previous-page ++ The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a ++convenient way to advance through the document. It scrolls within the ++current page or advances to the next. @key{DEL} moves backwards in a ++similar way (@code{doc-view-scroll-down-or-previous-page}). ++ ++@findex doc-view-first-page ++@findex doc-view-last-page ++@findex doc-view-goto-page ++ To go to the first page, type @kbd{M-<} ++(@code{doc-view-first-page}); to go to the last one, type @kbd{M->} ++(@code{doc-view-last-page}). To jump to a page by its number, type ++@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}). ++ ++@node Searching ++@subsection Searching ++ ++While in DocView mode, you can search the file's text for a regular ++expression (@pxref{Regexps}). The interface for searching is inspired ++by @code{isearch} (@pxref{Incremental Search}). ++ ++@findex doc-view-search ++@findex doc-view-search-backward ++@findex doc-view-show-tooltip ++ To begin a search, type @kbd{C-s} (@code{doc-view-search}) or ++@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular ++expression using a minibuffer, then echoes the number of matches found ++within the document. You can move forward and back among the matches ++by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show ++the match inside the page image; instead, it displays a tooltip (at ++the mouse position) listing all matching lines in the current page. ++To force display of this tooltip, type @kbd{C-t} ++(@code{doc-view-show-tooltip}). ++ ++ To start a new search, use the search command with a prefix ++argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r} ++for a backward search. ++ ++@node Slicing ++@subsection Slicing ++ ++Documents often have wide margins for printing. They are annoying ++when reading the document on the screen, because they use up screen ++space and can cause inconvenient scrolling. ++ ++@findex doc-view-set-slice ++@findex doc-view-set-slice-using-mouse ++ With DocView you can hide these margins by selecting a @dfn{slice} ++of pages to display. A slice is a rectangle within the page area; ++once you specify a slice in DocView, it applies to whichever page you ++look at. ++ ++ To specify the slice numerically, type @kbd{s s} ++(@code{doc-view-set-slice}); then enter the top left pixel position ++and the slice's width and height. ++@c ??? how does this work? ++ ++ A more convenient graphical way to specify the slice is with @kbd{s ++m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to ++select the slice. ++@c ??? How does this work? ++ ++@findex doc-view-reset-slice ++ To cancel the selected slice, type @kbd{s r} ++(@code{doc-view-reset-slice}). Then DocView shows the entire page ++including its entire margins. ++ ++@node Conversion ++@subsection Conversion ++ ++@vindex doc-view-cache-directory ++@findex doc-view-clear-cache ++For efficiency, DocView caches the images produced by @command{gs}. ++The name of this directory is given by the variable ++@code{doc-view-cache-directory}. You can clear the cache directory by ++typing @code{M-x doc-view-clear-cache}. ++ ++@findex doc-view-kill-proc ++@findex doc-view-kill-proc-and-buffer ++ To force a reconversion of the currently viewed document, type ++@kbd{r} or @kbd{g} (@code{revert-buffer}). To kill the converter ++process associated with the current buffer, type @kbd{K} ++(@code{doc-view-kill-proc}). The command @kbd{k} ++(@code{doc-view-kill-proc-and-buffer}) kills the converter process and ++the DocView buffer. ++ ++ The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-} ++(@code{doc-view-shrink}) need to reconvert the document at the new ++size. The current page is converted first. ++ ++@node Gnus, Shell, Document View, Top ++@section Gnus ++@cindex Gnus ++@cindex reading netnews ++ ++Gnus is an Emacs package primarily designed for reading and posting ++Usenet news. It can also be used to read and respond to messages from a ++number of other sources---mail, remote directories, digests, and so on. ++Here we introduce Gnus and describe several basic features. ++@ifnottex ++For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. ++@end ifnottex ++@iftex ++For full details on Gnus, type @kbd{M-x info} and then select the Gnus ++manual. ++@end iftex ++ ++@findex gnus ++To start Gnus, type @kbd{M-x gnus @key{RET}}. ++ ++@menu ++* Buffers of Gnus:: The group, summary, and article buffers. ++* Gnus Startup:: What you should know about starting Gnus. ++* Summary of Gnus:: A short description of the basic Gnus commands. ++@end menu ++ ++@node Buffers of Gnus ++@subsection Gnus Buffers ++ ++Unlike most Emacs packages, Gnus uses several buffers to display ++information and to receive commands. The three Gnus buffers users use ++most are the @dfn{group buffer}, the @dfn{summary buffer} and the ++@dfn{article buffer}. ++ ++The @dfn{group buffer} contains a list of newsgroups. This is the ++first buffer Gnus displays when it starts up. It normally displays ++only the groups to which you subscribe and that contain unread ++articles. Use this buffer to select a specific group. ++ ++The @dfn{summary buffer} lists one line for each article in a single ++group. By default, the author, the subject and the line number are ++displayed for each article, but this is customizable, like most aspects ++of Gnus display. The summary buffer is created when you select a group ++in the group buffer, and is killed when you exit the group. Use this ++buffer to select an article. ++ ++The @dfn{article buffer} displays the article. In normal Gnus usage, ++you see this buffer but you don't select it---all useful ++article-oriented commands work in the summary buffer. But you can ++select the article buffer, and execute all Gnus commands from that ++buffer, if you want to. ++ ++@node Gnus Startup ++@subsection When Gnus Starts Up ++ ++At startup, Gnus reads your @file{.newsrc} news initialization file ++and attempts to communicate with the local news server, which is a ++repository of news articles. The news server need not be the same ++computer you are logged in on. ++ ++If you start Gnus and connect to the server, but do not see any ++newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get ++a listing of all the groups. Then type @kbd{u} to toggle ++subscription to groups. ++ ++The first time you start Gnus, Gnus subscribes you to a few selected ++groups. All other groups start out as @dfn{killed groups} for you; you ++can list them with @kbd{A k}. All new groups that subsequently come to ++exist at the news server become @dfn{zombie groups} for you; type @kbd{A ++z} to list them. You can subscribe to a group shown in these lists ++using the @kbd{u} command. ++ ++When you quit Gnus with @kbd{q}, it automatically records in your ++@file{.newsrc} and @file{.newsrc.eld} initialization files the ++subscribed or unsubscribed status of all groups. You should normally ++not edit these files manually, but you may if you know how. ++ ++@node Summary of Gnus ++@subsection Summary of Gnus Commands ++ ++Reading news is a two-step process: ++ ++@enumerate ++@item ++Choose a group in the group buffer. ++ ++@item ++Select articles from the summary buffer. Each article selected is ++displayed in the article buffer in a large window, below the summary ++buffer in its small window. ++@end enumerate ++ ++ Each Gnus buffer has its own special commands; the meanings of any ++given key in the various Gnus buffers are usually analogous, even if ++not identical. Here are commands for the group and summary buffers: ++ ++@table @kbd ++@kindex q @r{(Gnus Group mode)} ++@findex gnus-group-exit ++@item q ++In the group buffer, update your @file{.newsrc} initialization file ++and quit Gnus. ++ ++In the summary buffer, exit the current group and return to the ++group buffer. Thus, typing @kbd{q} twice quits Gnus. ++ ++@kindex L @r{(Gnus Group mode)} ++@findex gnus-group-list-all-groups ++@item L ++In the group buffer, list all the groups available on your news ++server (except those you have killed). This may be a long list! ++ ++@kindex l @r{(Gnus Group mode)} ++@findex gnus-group-list-groups ++@item l ++In the group buffer, list only the groups to which you subscribe and ++which contain unread articles. ++ ++@kindex u @r{(Gnus Group mode)} ++@findex gnus-group-unsubscribe-current-group ++@cindex subscribe groups ++@cindex unsubscribe groups ++@item u ++In the group buffer, unsubscribe from (or subscribe to) the group listed ++in the line that point is on. When you quit Gnus by typing @kbd{q}, ++Gnus lists in your @file{.newsrc} file which groups you have subscribed ++to. The next time you start Gnus, you won't see this group, ++because Gnus normally displays only subscribed-to groups. ++ ++@kindex C-k @r{(Gnus)} ++@findex gnus-group-kill-group ++@item C-k ++In the group buffer, ``kill'' the current line's group---don't ++even list it in @file{.newsrc} from now on. This affects future ++Gnus sessions as well as the present session. ++ ++When you quit Gnus by typing @kbd{q}, Gnus writes information ++in the file @file{.newsrc} describing all newsgroups except those you ++have ``killed.'' ++ ++@kindex SPC @r{(Gnus)} ++@findex gnus-group-read-group ++@item @key{SPC} ++In the group buffer, select the group on the line under the cursor ++and display the first unread article in that group. ++ ++@need 1000 ++In the summary buffer, ++ ++@itemize @bullet ++@item ++Select the article on the line under the cursor if none is selected. ++ ++@item ++Scroll the text of the selected article (if there is one). ++ ++@item ++Select the next unread article if at the end of the current article. ++@end itemize ++ ++Thus, you can move through all the articles by repeatedly typing @key{SPC}. ++ ++@kindex DEL @r{(Gnus)} ++@item @key{DEL} ++In the group buffer, move point to the previous group containing ++unread articles. ++ ++@findex gnus-summary-prev-page ++In the summary buffer, scroll the text of the article backwards. ++ ++@kindex n @r{(Gnus)} ++@findex gnus-group-next-unread-group ++@findex gnus-summary-next-unread-article ++@item n ++Move point to the next unread group, or select the next unread article. ++ ++@kindex p @r{(Gnus)} ++@findex gnus-group-prev-unread-group ++@findex gnus-summary-prev-unread-article ++@item p ++Move point to the previous unread group, or select the previous ++unread article. ++ ++@kindex C-n @r{(Gnus Group mode)} ++@findex gnus-group-next-group ++@kindex C-p @r{(Gnus Group mode)} ++@findex gnus-group-prev-group ++@kindex C-n @r{(Gnus Summary mode)} ++@findex gnus-summary-next-subject ++@kindex C-p @r{(Gnus Summary mode)} ++@findex gnus-summary-prev-subject ++@item C-n ++@itemx C-p ++Move point to the next or previous item, even if it is marked as read. ++This does not select the article or group on that line. ++ ++@kindex s @r{(Gnus Summary mode)} ++@findex gnus-summary-isearch-article ++@item s ++In the summary buffer, do an incremental search of the current text in ++the article buffer, just as if you switched to the article buffer and ++typed @kbd{C-s}. ++ ++@kindex M-s @r{(Gnus Summary mode)} ++@findex gnus-summary-search-article-forward ++@item M-s @var{regexp} @key{RET} ++In the summary buffer, search forward for articles containing a match ++for @var{regexp}. ++ ++@end table ++ ++@ignore ++@node Where to Look ++@subsection Where to Look Further ++ ++@c Too many references to the name of the manual if done with xref in TeX! ++Gnus is powerful and customizable. Here are references to a few ++@ifnottex ++additional topics: ++ ++@end ifnottex ++@iftex ++additional topics in @cite{The Gnus Manual}: ++ ++@itemize @bullet ++@item ++Follow discussions on specific topics.@* ++See section ``Threading.'' ++ ++@item ++Read digests. See section ``Document Groups.'' ++ ++@item ++Refer to and jump to the parent of the current article.@* ++See section ``Finding the Parent.'' ++ ++@item ++Refer to articles by using Message-IDs included in the messages.@* ++See section ``Article Keymap.'' ++ ++@item ++Save articles. See section ``Saving Articles.'' ++ ++@item ++Have Gnus score articles according to various criteria, like author ++name, subject, or string in the body of the articles.@* ++See section ``Scoring.'' ++ ++@item ++Send an article to a newsgroup.@* ++See section ``Composing Messages.'' ++@end itemize ++@end iftex ++@ifnottex ++@itemize @bullet ++@item ++Follow discussions on specific topics.@* ++@xref{Threading, , Reading Based on Conversation Threads, ++gnus, The Gnus Manual}. ++ ++@item ++Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}. ++ ++@item ++Refer to and jump to the parent of the current article.@* ++@xref{Finding the Parent, , , gnus, The Gnus Manual}. ++ ++@item ++Refer to articles by using Message-IDs included in the messages.@* ++@xref{Article Keymap, , , gnus, The Gnus Manual}. ++ ++@item ++Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}. ++ ++@item ++Have Gnus score articles according to various criteria, like author ++name, subject, or string in the body of the articles.@* ++@xref{Scoring, , , gnus, The Gnus Manual}. ++ ++@item ++Send an article to a newsgroup.@* ++@xref{Composing Messages, , , gnus, The Gnus Manual}. ++@end itemize ++@end ifnottex ++@end ignore ++ ++@node Shell, Emacs Server, Gnus, Top ++@section Running Shell Commands from Emacs ++@cindex subshell ++@cindex shell commands ++ ++ Emacs has commands for passing single command lines to inferior shell ++processes; it can also run a shell interactively with input and output ++to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal ++emulator window. ++ ++@table @kbd ++@item M-! @var{cmd} @key{RET} ++Run the shell command line @var{cmd} and display the output ++(@code{shell-command}). ++@item M-| @var{cmd} @key{RET} ++Run the shell command line @var{cmd} with region contents as input; ++optionally replace the region with the output ++(@code{shell-command-on-region}). ++@item M-x shell ++Run a subshell with input and output through an Emacs buffer. ++You can then give commands interactively. ++@item M-x term ++Run a subshell with input and output through an Emacs buffer. ++You can then give commands interactively. ++Full terminal emulation is available. ++@end table ++ ++ @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It ++is documented in a separate manual. @xref{Top,Eshell,Eshell, eshell, ++Eshell: The Emacs Shell}. ++ ++@menu ++* Single Shell:: How to run one shell command and return. ++* Interactive Shell:: Permanent shell taking input via Emacs. ++* Shell Mode:: Special Emacs commands used with permanent shell. ++* Shell Prompts:: Two ways to recognize shell prompts. ++* History: Shell History. Repeating previous commands in a shell buffer. ++* Directory Tracking:: Keeping track when the subshell changes directory. ++* Options: Shell Options. Options for customizing Shell mode. ++* Terminal emulator:: An Emacs window as a terminal emulator. ++* Term Mode:: Special Emacs commands used in Term mode. ++* Paging in Term:: Paging in the terminal emulator. ++* Remote Host:: Connecting to another computer. ++* Serial Terminal:: Connecting to a serial port. ++@end menu ++ ++@node Single Shell ++@subsection Single Shell Commands ++ ++@kindex M-! ++@findex shell-command ++ @kbd{M-!} (@code{shell-command}) reads a line of text using the ++minibuffer and executes it as a shell command in a subshell made just ++for that command. Standard input for the command comes from the null ++device. If the shell command produces any output, the output appears ++either in the echo area (if it is short), or in an Emacs buffer named ++@samp{*Shell Command Output*}, which is displayed in another window ++but not selected (if the output is long). ++ ++ For instance, one way to decompress a file @file{foo.gz} from Emacs ++is to type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command ++normally creates the file @file{foo} and produces no terminal output. ++ ++ A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal ++output into the current buffer instead of a separate buffer. It puts ++point before the output, and sets the mark after the output. For ++instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the ++uncompressed equivalent of @file{foo.gz} into the current buffer. ++ ++ If the shell command line ends in @samp{&}, it runs asynchronously. ++For a synchronous shell command, @code{shell-command} returns the ++command's exit status (0 means success), when it is called from a Lisp ++program. You do not get any status information for an asynchronous ++command, since it hasn't finished yet when @code{shell-command} returns. ++ ++@kindex M-| ++@findex shell-command-on-region ++ @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but ++passes the contents of the region as the standard input to the shell ++command, instead of no input. With a numeric argument, meaning insert ++the output in the current buffer, it deletes the old region and the ++output replaces it as the contents of the region. It returns the ++command's exit status, like @kbd{M-!}. ++ ++ One use for @kbd{M-|} is to run @code{gpg} to see what keys are in ++the buffer. For instance, if the buffer contains a GPG key, type ++@kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to ++the @code{gpg} program. That program will ignore everything except ++the encoded keys, and will output a list of the keys the buffer ++contains. ++ ++@vindex shell-file-name ++ Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify ++the shell to use. This variable is initialized based on your ++@env{SHELL} environment variable when Emacs is started. If the file ++name is relative, Emacs searches the directories in the list ++@code{exec-path}; this list is initialized based on the environment ++variable @env{PATH} when Emacs is started. Your init file can ++override either or both of these default initializations (@pxref{Init ++File}). ++ ++ Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete, ++unless you end the command with @samp{&} to make it asynchronous. To ++stop waiting, type @kbd{C-g} to quit; that terminates the shell ++command with the signal @code{SIGINT}---the same signal that @kbd{C-c} ++normally generates in the shell. Emacs then waits until the command ++actually terminates. If the shell command doesn't stop (because it ++ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends ++the command a @code{SIGKILL} signal which is impossible to ignore. ++ ++ Asynchronous commands ending in @samp{&} feed their output into ++the buffer @samp{*Async Shell Command*}. Output arrives in that ++buffer regardless of whether it is visible in a window. ++ ++ To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command ++@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}. ++ ++@vindex shell-command-default-error-buffer ++ Error output from these commands is normally intermixed with the ++regular output. But if the variable ++@code{shell-command-default-error-buffer} has a string as value, and ++it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output ++before point in that buffer. ++ ++@node Interactive Shell ++@subsection Interactive Inferior Shell ++ ++@findex shell ++ To run a subshell interactively, use @kbd{M-x shell}. This creates ++(or reuses) a buffer named @samp{*shell*} and runs a subshell with ++input coming from and output going to that buffer. That is to say, ++any ``terminal output'' from the subshell goes into the buffer, ++advancing point, and any ``terminal input'' for the subshell comes ++from text in the buffer. To give input to the subshell, go to the end ++of the buffer and type the input, terminated by @key{RET}. ++ ++ Emacs does not wait for the subshell to do anything. You can switch ++windows or buffers and edit them while the shell is waiting, or while it is ++running a command. Output from the subshell waits until Emacs has time to ++process it; this happens whenever Emacs is waiting for keyboard input or ++for time to elapse. ++ ++@cindex @code{comint-highlight-input} face ++@cindex @code{comint-highlight-prompt} face ++ Input lines, once you submit them, are displayed using the face ++@code{comint-highlight-input}, and prompts are displayed using the ++face @code{comint-highlight-prompt}. This makes it easier to see ++previous input lines in the buffer. @xref{Faces}. ++ ++ To make multiple subshells, you can invoke @kbd{M-x shell} with a ++prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer ++name and create (or reuse) a subshell in that buffer. You can also ++rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then ++create a new @samp{*shell*} buffer using plain @kbd{M-x shell}. ++Subshells in different buffers run independently and in parallel. ++ ++@vindex explicit-shell-file-name ++@cindex environment variables for subshells ++@cindex @env{ESHELL} environment variable ++@cindex @env{SHELL} environment variable ++ The file name used to load the subshell is the value of the variable ++@code{explicit-shell-file-name}, if that is non-@code{nil}. ++Otherwise, the environment variable @env{ESHELL} is used, or the ++environment variable @env{SHELL} if there is no @env{ESHELL}. If the ++file name specified is relative, the directories in the list ++@code{exec-path} are searched; this list is initialized based on the ++environment variable @env{PATH} when Emacs is started. Your init file ++can override either or both of these default initializations. ++(@pxref{Init File}). ++ ++ Emacs sends the new shell the contents of the file ++@file{~/.emacs_@var{shellname}} as input, if it exists, where ++@var{shellname} is the name of the file that the shell was loaded ++from. For example, if you use bash, the file sent to it is ++@file{~/.emacs_bash}. If this file is not found, Emacs tries to fallback ++on @file{~/.emacs.d/init_@var{shellname}.sh}. ++ ++ To specify a coding system for the shell, you can use the command ++@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can ++also change the coding system for a running subshell by typing ++@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication ++Coding}. ++ ++@cindex @env{INSIDE_EMACS} environment variable ++ Emacs sets the environment variable @env{INSIDE_EMACS} in the ++subshell to a comma-separated list including the Emacs version. ++Programs can check this variable to determine whether they are running ++inside an Emacs subshell. ++ ++@cindex @env{EMACS} environment variable ++ Emacs also sets the @env{EMACS} environment variable (to @code{t}) if ++it is not already defined. @strong{Warning:} This environment ++variable is deprecated. Programs that check this variable should be ++changed to check @env{INSIDE_EMACS} instead. ++ ++@node Shell Mode ++@subsection Shell Mode ++@cindex Shell mode ++@cindex mode, Shell ++ ++ Shell buffers use Shell mode, which defines several special keys ++attached to the @kbd{C-c} prefix. They are chosen to resemble the usual ++editing and job control characters present in shells that are not under ++Emacs, except that you must type @kbd{C-c} first. Here is a complete list ++of the special key bindings of Shell mode: ++ ++@table @kbd ++@item @key{RET} ++@kindex RET @r{(Shell mode)} ++@findex comint-send-input ++At end of buffer send line as input; otherwise, copy current line to ++end of buffer and send it (@code{comint-send-input}). Copying a line ++in this way omits any prompt at the beginning of the line (text output ++by programs preceding your input). @xref{Shell Prompts}, for how ++Shell mode recognizes prompts. ++ ++@item @key{TAB} ++@kindex TAB @r{(Shell mode)} ++@findex comint-dynamic-complete ++Complete the command name or file name before point in the shell buffer ++(@code{comint-dynamic-complete}). @key{TAB} also completes history ++references (@pxref{History References}) and environment variable names. ++ ++@vindex shell-completion-fignore ++@vindex comint-completion-fignore ++The variable @code{shell-completion-fignore} specifies a list of file ++name extensions to ignore in Shell mode completion. The default ++setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to ++ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other ++related Comint modes use the variable @code{comint-completion-fignore} ++instead. ++ ++@item M-? ++@kindex M-? @r{(Shell mode)} ++@findex comint-dynamic-list-filename@dots{} ++Display temporarily a list of the possible completions of the file name ++before point in the shell buffer ++(@code{comint-dynamic-list-filename-completions}). ++ ++@item C-d ++@kindex C-d @r{(Shell mode)} ++@findex comint-delchar-or-maybe-eof ++Either delete a character or send @acronym{EOF} ++(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell ++buffer, @kbd{C-d} sends @acronym{EOF} to the subshell. Typed at any other ++position in the buffer, @kbd{C-d} deletes a character as usual. ++ ++@item C-c C-a ++@kindex C-c C-a @r{(Shell mode)} ++@findex comint-bol-or-process-mark ++Move to the beginning of the line, but after the prompt if any ++(@code{comint-bol-or-process-mark}). If you repeat this command twice ++in a row, the second time it moves back to the process mark, which is ++the beginning of the input that you have not yet sent to the subshell. ++(Normally that is the same place---the end of the prompt on this ++line---but after @kbd{C-c @key{SPC}} the process mark may be in a ++previous line.) ++ ++@item C-c @key{SPC} ++Accumulate multiple lines of input, then send them together. This ++command inserts a newline before point, but does not send the preceding ++text as input to the subshell---at least, not yet. Both lines, the one ++before this newline and the one after, will be sent together (along with ++the newline that separates them), when you type @key{RET}. ++ ++@item C-c C-u ++@kindex C-c C-u @r{(Shell mode)} ++@findex comint-kill-input ++Kill all text pending at end of buffer to be sent as input ++(@code{comint-kill-input}). If point is not at end of buffer, ++this only kills the part of this text that precedes point. ++ ++@item C-c C-w ++@kindex C-c C-w @r{(Shell mode)} ++Kill a word before point (@code{backward-kill-word}). ++ ++@item C-c C-c ++@kindex C-c C-c @r{(Shell mode)} ++@findex comint-interrupt-subjob ++Interrupt the shell or its current subjob if any ++(@code{comint-interrupt-subjob}). This command also kills ++any shell input pending in the shell buffer and not yet sent. ++ ++@item C-c C-z ++@kindex C-c C-z @r{(Shell mode)} ++@findex comint-stop-subjob ++Stop the shell or its current subjob if any (@code{comint-stop-subjob}). ++This command also kills any shell input pending in the shell buffer and ++not yet sent. ++ ++@item C-c C-\ ++@findex comint-quit-subjob ++@kindex C-c C-\ @r{(Shell mode)} ++Send quit signal to the shell or its current subjob if any ++(@code{comint-quit-subjob}). This command also kills any shell input ++pending in the shell buffer and not yet sent. ++ ++@item C-c C-o ++@kindex C-c C-o @r{(Shell mode)} ++@findex comint-delete-output ++Delete the last batch of output from a shell command ++(@code{comint-delete-output}). This is useful if a shell command spews ++out lots of output that just gets in the way. This command used to be ++called @code{comint-kill-output}. ++ ++@item C-c C-s ++@kindex C-c C-s @r{(Shell mode)} ++@findex comint-write-output ++Write the last batch of output from a shell command to a file ++(@code{comint-write-output}). With a prefix argument, the file is ++appended to instead. Any prompt at the end of the output is not ++written. ++ ++@item C-c C-r ++@itemx C-M-l ++@kindex C-c C-r @r{(Shell mode)} ++@kindex C-M-l @r{(Shell mode)} ++@findex comint-show-output ++Scroll to display the beginning of the last batch of output at the top ++of the window; also move the cursor there (@code{comint-show-output}). ++ ++@item C-c C-e ++@kindex C-c C-e @r{(Shell mode)} ++@findex comint-show-maximum-output ++Scroll to put the end of the buffer at the bottom of the window ++(@code{comint-show-maximum-output}). ++ ++@item C-c C-f ++@kindex C-c C-f @r{(Shell mode)} ++@findex shell-forward-command ++@vindex shell-command-regexp ++Move forward across one shell command, but not beyond the current line ++(@code{shell-forward-command}). The variable @code{shell-command-regexp} ++specifies how to recognize the end of a command. ++ ++@item C-c C-b ++@kindex C-c C-b @r{(Shell mode)} ++@findex shell-backward-command ++Move backward across one shell command, but not beyond the current line ++(@code{shell-backward-command}). ++ ++@item M-x dirs ++Ask the shell what its current directory is, so that Emacs can agree ++with the shell. ++ ++@item M-x send-invisible @key{RET} @var{text} @key{RET} ++@findex send-invisible ++Send @var{text} as input to the shell, after reading it without ++echoing. This is useful when a shell command runs a program that asks ++for a password. ++ ++Please note that Emacs will not echo passwords by default. If you ++really want them to be echoed, evaluate the following Lisp ++expression: ++ ++@example ++(remove-hook 'comint-output-filter-functions ++ 'comint-watch-for-password-prompt) ++@end example ++ ++@item M-x comint-continue-subjob ++@findex comint-continue-subjob ++Continue the shell process. This is useful if you accidentally suspend ++the shell process.@footnote{You should not suspend the shell process. ++Suspending a subjob of the shell is a completely different matter---that ++is normal practice, but you must use the shell to continue the subjob; ++this command won't do it.} ++ ++@item M-x comint-strip-ctrl-m ++@findex comint-strip-ctrl-m ++Discard all control-M characters from the current group of shell output. ++The most convenient way to use this command is to make it run ++automatically when you get output from the subshell. To do that, ++evaluate this Lisp expression: ++ ++@example ++(add-hook 'comint-output-filter-functions ++ 'comint-strip-ctrl-m) ++@end example ++ ++@item M-x comint-truncate-buffer ++@findex comint-truncate-buffer ++This command truncates the shell buffer to a certain maximum number of ++lines, specified by the variable @code{comint-buffer-maximum-size}. ++Here's how to do this automatically each time you get output from the ++subshell: ++ ++@example ++(add-hook 'comint-output-filter-functions ++ 'comint-truncate-buffer) ++@end example ++@end table ++ ++@cindex Comint mode ++@cindex mode, Comint ++ Shell mode is a derivative of Comint mode, a general-purpose mode for ++communicating with interactive subprocesses. Most of the features of ++Shell mode actually come from Comint mode, as you can see from the ++command names listed above. The special features of Shell mode include ++the directory tracking feature, and a few user commands. ++ ++ Other Emacs features that use variants of Comint mode include GUD ++(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}). ++ ++@findex comint-run ++ You can use @kbd{M-x comint-run} to execute any program of your choice ++in a subprocess using unmodified Comint mode---without the ++specializations of Shell mode. ++ ++@node Shell Prompts ++@subsection Shell Prompts ++ ++@vindex shell-prompt-pattern ++@vindex comint-prompt-regexp ++@vindex comint-use-prompt-regexp ++@cindex prompt, shell ++ A prompt is text output by a program to show that it is ready to ++accept new user input. Normally, Comint mode (and thus Shell mode) ++considers the prompt to be any text output by a program at the ++beginning of an input line. However, if the variable ++@code{comint-use-prompt-regexp} is non-@code{nil}, then Comint mode ++uses a regular expression to recognize prompts. In Shell mode, ++@code{shell-prompt-pattern} specifies the regular expression. ++ ++ The value of @code{comint-use-prompt-regexp} also affects many ++motion and paragraph commands. If the value is non-@code{nil}, the ++general Emacs motion commands behave as they normally do in buffers ++without special text properties. However, if the value is @code{nil}, ++the default, then Comint mode divides the buffer into two types of ++``fields'' (ranges of consecutive characters having the same ++@code{field} text property): input and output. Prompts are part of ++the output. Most Emacs motion commands do not cross field boundaries, ++unless they move over multiple lines. For instance, when point is in ++input on the same line as a prompt, @kbd{C-a} puts point at the ++beginning of the input if @code{comint-use-prompt-regexp} is ++@code{nil} and at the beginning of the line otherwise. ++ ++ In Shell mode, only shell prompts start new paragraphs. Thus, a ++paragraph consists of a prompt and the input and output that follow ++it. However, if @code{comint-use-prompt-regexp} is @code{nil}, the ++default, most paragraph commands do not cross field boundaries. This ++means that prompts, ranges of input, and ranges of non-prompt output ++behave mostly like separate paragraphs; with this setting, numeric ++arguments to most paragraph commands yield essentially undefined ++behavior. For the purpose of finding paragraph boundaries, Shell mode ++uses @code{shell-prompt-pattern}, regardless of ++@code{comint-use-prompt-regexp}. ++ ++@node Shell History ++@subsection Shell Command History ++ ++ Shell buffers support three ways of repeating earlier commands. You ++can use keys like those used for the minibuffer history; these work ++much as they do in the minibuffer, inserting text from prior commands ++while point remains always at the end of the buffer. You can move ++through the buffer to previous inputs in their original place, then ++resubmit them or copy them to the end. Or you can use a ++@samp{!}-style history reference. ++ ++@menu ++* Ring: Shell Ring. Fetching commands from the history list. ++* Copy: Shell History Copying. Moving to a command and then copying it. ++* History References:: Expanding @samp{!}-style history references. ++@end menu ++ ++@node Shell Ring ++@subsubsection Shell History Ring ++ ++@table @kbd ++@findex comint-previous-input ++@kindex M-p @r{(Shell mode)} ++@item M-p ++@itemx C-@key{UP} ++Fetch the next earlier old shell command. ++ ++@kindex M-n @r{(Shell mode)} ++@findex comint-next-input ++@item M-n ++@itemx C-@key{DOWN} ++Fetch the next later old shell command. ++ ++@kindex M-r @r{(Shell mode)} ++@kindex M-s @r{(Shell mode)} ++@findex comint-previous-matching-input ++@findex comint-next-matching-input ++@item M-r @var{regexp} @key{RET} ++@itemx M-s @var{regexp} @key{RET} ++Search backwards or forwards for old shell commands that match @var{regexp}. ++ ++@item C-c C-x ++@kindex C-c C-x @r{(Shell mode)} ++@findex comint-get-next-from-history ++Fetch the next subsequent command from the history. ++ ++@item C-c . ++@kindex C-c . @r{(Shell mode)} ++@findex comint-input-previous-argument ++Fetch one argument from an old shell command. ++ ++@item C-c C-l ++@kindex C-c C-l @r{(Shell mode)} ++@findex comint-dynamic-list-input-ring ++Display the buffer's history of shell commands in another window ++(@code{comint-dynamic-list-input-ring}). ++@end table ++ ++ Shell buffers provide a history of previously entered shell commands. To ++reuse shell commands from the history, use the editing commands @kbd{M-p}, ++@kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer ++history commands except that they operate on the text at the end of the ++shell buffer, where you would normally insert text to send to the shell. ++ ++ @kbd{M-p} fetches an earlier shell command to the end of the shell ++buffer. Successive use of @kbd{M-p} fetches successively earlier ++shell commands, each replacing any text that was already present as ++potential shell input. @kbd{M-n} does likewise except that it finds ++successively more recent shell commands from the buffer. ++@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like ++@kbd{M-n}. ++ ++ The history search commands @kbd{M-r} and @kbd{M-s} read a regular ++expression and search through the history for a matching command. Aside ++from the choice of which command to fetch, they work just like @kbd{M-p} ++and @kbd{M-n}. If you enter an empty regexp, these commands reuse the ++same regexp used last time. ++ ++ When you find the previous input you want, you can resubmit it by ++typing @key{RET}, or you can edit it first and then resubmit it if you ++wish. Any partial input you were composing before navigating the ++history list is restored when you go to the beginning or end of the ++history ring. ++ ++ Often it is useful to reexecute several successive shell commands that ++were previously executed in sequence. To do this, first find and ++reexecute the first command of the sequence. Then type @kbd{C-c C-x}; ++that will fetch the following command---the one that follows the command ++you just repeated. Then type @key{RET} to reexecute this command. You ++can reexecute several successive commands by typing @kbd{C-c C-x ++@key{RET}} over and over. ++ ++ The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) ++copies an individual argument from a previous command, like @kbd{ESC ++.} in Bash. The simplest use copies the last argument from the ++previous shell command. With a prefix argument @var{n}, it copies the ++@var{n}th argument instead. Repeating @kbd{C-c .} copies from an ++earlier shell command instead, always using the same value of @var{n} ++(don't give a prefix argument when you repeat the @kbd{C-c .} ++command). ++ ++ These commands get the text of previous shell commands from a special ++history list, not from the shell buffer itself. Thus, editing the shell ++buffer, or even killing large parts of it, does not affect the history ++that these commands access. ++ ++@vindex shell-input-ring-file-name ++ Some shells store their command histories in files so that you can ++refer to commands from previous shell sessions. Emacs reads ++the command history file for your chosen shell, to initialize its own ++command history. The file name is @file{~/.bash_history} for bash, ++@file{~/.sh_history} for ksh, and @file{~/.history} for other shells. ++ ++@node Shell History Copying ++@subsubsection Shell History Copying ++ ++@table @kbd ++@kindex C-c C-p @r{(Shell mode)} ++@findex comint-previous-prompt ++@item C-c C-p ++Move point to the previous prompt (@code{comint-previous-prompt}). ++ ++@kindex C-c C-n @r{(Shell mode)} ++@findex comint-next-prompt ++@item C-c C-n ++Move point to the following prompt (@code{comint-next-prompt}). ++ ++@kindex C-c RET @r{(Shell mode)} ++@findex comint-copy-old-input ++@item C-c @key{RET} ++Copy the input command at point, inserting the copy at the end of the ++buffer (@code{comint-copy-old-input}). This is useful if you move ++point back to a previous command. After you copy the command, you can ++submit the copy as input with @key{RET}. If you wish, you can edit ++the copy before resubmitting it. If you use this command on an output ++line, it copies that line to the end of the buffer. ++ ++@item Mouse-2 ++If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy ++the old input command that you click on, inserting the copy at the end ++of the buffer (@code{comint-insert-input}). If ++@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is ++not over old input, just yank as usual. ++@end table ++ ++ Moving to a previous input and then copying it with @kbd{C-c ++@key{RET}} or @kbd{Mouse-2} produces the same results---the same ++buffer contents---that you would get by using @kbd{M-p} enough times ++to fetch that previous input from the history list. However, @kbd{C-c ++@key{RET}} copies the text from the buffer, which can be different ++from what is in the history list if you edit the input text in the ++buffer after it has been sent. ++ ++@node History References ++@subsubsection Shell History References ++@cindex history reference ++ ++ Various shells including csh and bash support @dfn{history ++references} that begin with @samp{!} and @samp{^}. Shell mode ++recognizes these constructs, and can perform the history substitution ++for you. ++ ++ If you insert a history reference and type @key{TAB}, this searches ++the input history for a matching command, performs substitution if ++necessary, and places the result in the buffer in place of the history ++reference. For example, you can fetch the most recent command ++beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the ++command if you wish, and then resubmit the command to the shell by ++typing @key{RET}. ++ ++@vindex comint-input-autoexpand ++@findex comint-magic-space ++ Shell mode can optionally expand history references in the buffer ++when you send them to the shell. To request this, set the variable ++@code{comint-input-autoexpand} to @code{input}. You can make ++@key{SPC} perform history expansion by binding @key{SPC} to the ++command @code{comint-magic-space}. ++ ++ Shell mode recognizes history references when they follow a prompt. ++@xref{Shell Prompts}, for how Shell mode recognizes prompts. ++ ++@node Directory Tracking ++@subsection Directory Tracking ++@cindex directory tracking ++ ++@vindex shell-pushd-regexp ++@vindex shell-popd-regexp ++@vindex shell-cd-regexp ++ Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd} ++commands given to the inferior shell, so it can keep the ++@samp{*shell*} buffer's default directory the same as the shell's ++working directory. It recognizes these commands syntactically, by ++examining lines of input that are sent. ++ ++ If you use aliases for these commands, you can tell Emacs to ++recognize them also. For example, if the value of the variable ++@code{shell-pushd-regexp} matches the beginning of a shell command ++line, that line is regarded as a @code{pushd} command. Change this ++variable when you add aliases for @samp{pushd}. Likewise, ++@code{shell-popd-regexp} and @code{shell-cd-regexp} are used to ++recognize commands with the meaning of @samp{popd} and @samp{cd}. ++These commands are recognized only at the beginning of a shell command ++line. ++ ++@ignore @c This seems to have been deleted long ago. ++@vindex shell-set-directory-error-hook ++ If Emacs gets an error while trying to handle what it believes is a ++@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook ++@code{shell-set-directory-error-hook} (@pxref{Hooks}). ++@end ignore ++ ++@findex dirs ++ If Emacs gets confused about changes in the current directory of the ++subshell, use the command @kbd{M-x dirs} to ask the shell what its ++current directory is. This command works for shells that support the ++most common command syntax; it may not work for unusual shells. ++ ++@findex dirtrack-mode ++ You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an ++alternative method of tracking changes in the current directory. This ++method relies on your shell prompt containing the full current working ++directory at all times. ++ ++@node Shell Options ++@subsection Shell Mode Options ++ ++@vindex comint-scroll-to-bottom-on-input ++ If the variable @code{comint-scroll-to-bottom-on-input} is ++non-@code{nil}, insertion and yank commands scroll the selected window ++to the bottom before inserting. The default is @code{nil}. ++ ++@vindex comint-scroll-show-maximum-output ++ If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then ++arrival of output when point is at the end tries to scroll the last ++line of text to the bottom line of the window, showing as much useful ++text as possible. (This mimics the scrolling behavior of most ++terminals.) The default is @code{t}. ++ ++@vindex comint-move-point-for-output ++ By setting @code{comint-move-point-for-output}, you can opt for ++having point jump to the end of the buffer whenever output arrives---no ++matter where in the buffer point was before. If the value is ++@code{this}, point jumps in the selected window. If the value is ++@code{all}, point jumps in each window that shows the Comint buffer. If ++the value is @code{other}, point jumps in all nonselected windows that ++show the current buffer. The default value is @code{nil}, which means ++point does not jump to the end. ++ ++@vindex comint-prompt-read-only ++ If you set @code{comint-prompt-read-only}, the prompts in the Comint ++buffer are read-only. ++ ++@vindex comint-input-ignoredups ++ The variable @code{comint-input-ignoredups} controls whether successive ++identical inputs are stored in the input history. A non-@code{nil} ++value means to omit an input that is the same as the previous input. ++The default is @code{nil}, which means to store each input even if it is ++equal to the previous input. ++ ++@vindex comint-completion-addsuffix ++@vindex comint-completion-recexact ++@vindex comint-completion-autolist ++ Three variables customize file name completion. The variable ++@code{comint-completion-addsuffix} controls whether completion inserts a ++space or a slash to indicate a fully completed file or directory name ++(non-@code{nil} means do insert a space or slash). ++@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB} ++to choose the shortest possible completion if the usual Emacs completion ++algorithm cannot add even a single character. ++@code{comint-completion-autolist}, if non-@code{nil}, says to list all ++the possible completions whenever completion is not exact. ++ ++@vindex shell-completion-execonly ++ Command completion normally considers only executable files. ++If you set @code{shell-completion-execonly} to @code{nil}, ++it considers nonexecutable files as well. ++ ++@findex shell-pushd-tohome ++@findex shell-pushd-dextract ++@findex shell-pushd-dunique ++ You can configure the behavior of @samp{pushd}. Variables control ++whether @samp{pushd} behaves like @samp{cd} if no argument is given ++(@code{shell-pushd-tohome}), pop rather than rotate with a numeric ++argument (@code{shell-pushd-dextract}), and only add directories to the ++directory stack if they are not already on it ++(@code{shell-pushd-dunique}). The values you choose should match the ++underlying shell, of course. ++ ++ If you want Shell mode to handle color output from shell commands, ++you can enable ANSI Color mode. Here is how to do this: ++ ++@example ++(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on) ++@end example ++ ++@node Terminal emulator ++@subsection Emacs Terminal Emulator ++@findex term ++ ++ To run a subshell in a terminal emulator, use @kbd{M-x term}. This ++creates (or reuses) a buffer named @samp{*terminal*}, and runs a ++subshell with input coming from your keyboard, and output going to ++that buffer. ++ ++ The terminal emulator uses Term mode, which has two input modes. In ++line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. ++ ++ In char mode, each character is sent directly to the inferior ++subshell, as ``terminal input.'' Any ``echoing'' of your input is the ++responsibility of the subshell. The sole exception is the terminal ++escape character, which by default is @kbd{C-c} (@pxref{Term Mode}). ++Any ``terminal output'' from the subshell goes into the buffer, ++advancing point. ++ ++ Some programs (such as Emacs itself) need to control the appearance ++on the terminal screen in detail. They do this by sending special ++control codes. The exact control codes needed vary from terminal to ++terminal, but nowadays most terminals and terminal emulators ++(including @code{xterm}) understand the ANSI-standard (VT100-style) ++escape sequences. Term mode recognizes these escape sequences, and ++handles each one appropriately, changing the buffer so that the ++appearance of the window matches what it would be on a real terminal. ++You can actually run Emacs inside an Emacs Term window. ++ ++ You can use Term mode to communicate with a device connected to a ++serial port of your computer. @xref{Serial Terminal}. ++ ++ The file name used to load the subshell is determined the same way ++as for Shell mode. To make multiple terminal emulators, rename the ++buffer @samp{*terminal*} to something different using @kbd{M-x ++rename-uniquely}, just as with Shell mode. ++ ++ Unlike Shell mode, Term mode does not track the current directory by ++examining your input. But some shells can tell Term what the current ++directory is. This is done automatically by @code{bash} version 1.15 ++and later. ++ ++@node Term Mode ++@subsection Term Mode ++@cindex Term mode ++@cindex mode, Term ++ ++ The terminal emulator uses Term mode, which has two input modes. In ++line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. ++In char mode, each character is sent directly to the inferior ++subshell, except for the Term escape character, normally @kbd{C-c}. ++ ++ To switch between line and char mode, use these commands: ++ ++@table @kbd ++@kindex C-c C-j @r{(Term mode)} ++@findex term-char-mode ++@item C-c C-j ++Switch to line mode. Do nothing if already in line mode. ++ ++@kindex C-c C-k @r{(Term mode)} ++@findex term-line-mode ++@item C-c C-k ++Switch to char mode. Do nothing if already in char mode. ++@end table ++ ++ The following commands are only available in char mode: ++ ++@table @kbd ++@item C-c C-c ++Send a literal @key{C-c} to the sub-shell. ++ ++@item C-c @var{char} ++This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For ++example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which ++is normally @samp{other-window}. ++@end table ++ ++@node Paging in Term ++@subsection Page-At-A-Time Output ++@cindex page-at-a-time ++ ++ Term mode has a page-at-a-time feature. When enabled it makes ++output pause at the end of each screenful. ++ ++@table @kbd ++@kindex C-c C-q @r{(Term mode)} ++@findex term-pager-toggle ++@item C-c C-q ++Toggle the page-at-a-time feature. This command works in both line ++and char modes. When page-at-a-time is enabled, the mode-line ++displays the word @samp{page}. ++@end table ++ ++ With page-at-a-time enabled, whenever Term receives more than a ++screenful of output since your last input, it pauses, displaying ++@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next ++screenful of output. Type @kbd{?} to see your other options. The ++interface is similar to the @code{more} program. ++ ++@node Remote Host ++@subsection Remote Host Shell ++@cindex remote host ++@cindex connecting to remote host ++@cindex Telnet ++@cindex Rlogin ++ ++ You can login to a remote computer, using whatever commands you ++would from a regular terminal (e.g.@: using the @code{telnet} or ++@code{rlogin} commands), from a Term window. ++ ++ A program that asks you for a password will normally suppress ++echoing of the password, so the password will not show up in the ++buffer. This will happen just as if you were using a real terminal, ++if the buffer is in char mode. If it is in line mode, the password is ++temporarily visible, but will be erased when you hit return. (This ++happens automatically; there is no special password processing.) ++ ++ When you log in to a different machine, you need to specify the type ++of terminal you're using, by setting the @env{TERM} environment ++variable in the environment for the remote login command. (If you use ++bash, you do that by writing the variable assignment before the remote ++login command, without separating comma.) Terminal types @samp{ansi} ++or @samp{vt100} will work on most systems. ++ ++@c If you are talking to a Bourne-compatible ++@c shell, and your system understands the @env{TERMCAP} variable, ++@c you can use the command @kbd{M-x shell-send-termcap}, which ++@c sends a string specifying the terminal type and size. ++@c (This command is also useful after the window has changed size.) ++ ++@c You can of course run @samp{gdb} on that remote computer. One useful ++@c trick: If you invoke gdb with the @code{--fullname} option, ++@c it will send special commands to Emacs that will cause Emacs to ++@c pop up the source files you're debugging. This will work ++@c whether or not gdb is running on a different computer than Emacs, ++@c as long as Emacs can access the source files specified by gdb. ++ ++@ignore ++ You cannot log in to a remote computer using the Shell mode. ++@c (This will change when Shell is re-written to use Term.) ++Instead, Emacs provides two commands for logging in to another computer ++and communicating with it through an Emacs buffer using Comint mode: ++ ++@table @kbd ++@item M-x telnet @key{RET} @var{hostname} @key{RET} ++Set up a Telnet connection to the computer named @var{hostname}. ++@item M-x rlogin @key{RET} @var{hostname} @key{RET} ++Set up an Rlogin connection to the computer named @var{hostname}. ++@end table ++ ++@findex telnet ++ Use @kbd{M-x telnet} to set up a Telnet connection to another ++computer. (Telnet is the standard Internet protocol for remote login.) ++It reads the host name of the other computer as an argument with the ++minibuffer. Once the connection is established, talking to the other ++computer works like talking to a subshell: you can edit input with the ++usual Emacs commands, and send it a line at a time by typing @key{RET}. ++The output is inserted in the Telnet buffer interspersed with the input. ++ ++@findex rlogin ++@vindex rlogin-explicit-args ++ Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is ++another remote login communication protocol, essentially much like the ++Telnet protocol but incompatible with it, and supported only by certain ++systems. Rlogin's advantages are that you can arrange not to have to ++give your user name and password when communicating between two machines ++you frequently use, and that you can make an 8-bit-clean connection. ++(To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")} ++before you run Rlogin.) ++ ++ @kbd{M-x rlogin} sets up the default file directory of the Emacs ++buffer to access the remote host via FTP (@pxref{File Names}), and it ++tracks the shell commands that change the current directory, just like ++Shell mode. ++ ++@findex rlogin-directory-tracking-mode ++ There are two ways of doing directory tracking in an Rlogin ++buffer---either with remote directory names ++@file{/@var{host}:@var{dir}/} or with local names (that works if the ++``remote'' machine shares file systems with your machine of origin). ++You can use the command @code{rlogin-directory-tracking-mode} to switch ++modes. No argument means use remote directory names, a positive ++argument means use local names, and a negative argument means turn ++off directory tracking. ++ ++@end ignore ++ ++@node Serial Terminal ++@subsection Serial Terminal ++@cindex terminal, serial ++@findex serial-term ++ ++ If you have a device connected to a serial port of your computer, ++you can use Emacs to communicate with it. @kbd{M-x serial-term} will ++ask you for a serial port name and speed and will then open a new ++window in @ref{Term Mode}. ++ ++ The speed of the serial port is measured in bits per second. The ++most common speed is 9600 bits per second. You can change the speed ++interactively by clicking on the mode line. ++ ++ A serial port can be configured even more by clicking on ``8N1'' in ++the mode line. By default, a serial port is configured as ``8N1'', ++which means that each byte consists of 8 data bits, No parity check ++bit, and 1 stopbit. ++ ++ When you have opened the serial port connection, you will see output ++from the device in the window. Also, what you type in the window is ++sent to the device. ++ ++ If the speed or the configuration is wrong, you cannot communicate ++with your device and will probably only see garbage output in the ++window. ++ ++@node Emacs Server, Printing, Shell, Top ++@section Using Emacs as a Server ++@pindex emacsclient ++@cindex Emacs as a server ++@cindex server, using Emacs as ++@cindex @env{EDITOR} environment variable ++ ++ Various programs such as @command{mail} can invoke your choice of ++editor to edit a particular piece of text, such as a message that you ++are sending. By convention, most of these programs use the ++environment variable @env{EDITOR} to specify which editor to run. If ++you set @env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an ++inconvenient way, by starting a new Emacs process. This is ++inconvenient because the new Emacs process doesn't share buffers, a ++command history, or other kinds of information with any existing Emacs ++process. ++ ++ You can solve this problem by setting up Emacs as an @dfn{edit ++server}, so that it ``listens'' for external edit requests and acts ++accordingly. There are two ways to start an Emacs server: ++ ++@findex server-start ++ The first is to run the command @code{server-start} in an existing ++Emacs process: either type @kbd{M-x server-start}, or put the ++expression @code{(server-start)} in your initialization file ++(@pxref{Init File}). The existing Emacs process is the server; when ++you exit Emacs, the server dies with the Emacs process. ++ ++@cindex daemon, Emacs ++ The second way to start an Emacs server is to run Emacs as a ++@dfn{daemon}, using the @samp{--daemon} command-line option. ++@xref{Initial Options}. When Emacs is started this way, it calls ++@code{server-start} after initialization, and returns control to the ++calling terminal instead of opening an initial frame; it then waits in ++the background, listening for edit requests. ++ ++@cindex @env{TEXEDIT} environment variable ++ Once an Emacs server is set up, you can use a shell command called ++@command{emacsclient} to connect to the existing Emacs process and ++tell it to visit a file. If you set the @env{EDITOR} environment ++variable to @samp{emacsclient}, programs such as @command{mail} will ++use the existing Emacs process for editing.@footnote{Some programs use ++a different environment variable; for example, to make @TeX{} use ++@samp{emacsclient}, set the @env{TEXEDIT} environment variable to ++@samp{emacsclient +%d %s}.} ++ ++@vindex server-name ++ You can run multiple Emacs servers on the same machine by giving ++each one a unique ``server name'', using the variable ++@code{server-name}. For example, @kbd{M-x set-variable @key{RET} ++server-name @key{RET} foo @key{RET}} sets the server name to ++@samp{foo}. The @code{emacsclient} program can specify a server by ++name, using the @samp{-s} option (@pxref{emacsclient Options}). ++ ++@menu ++* Invoking emacsclient:: Connecting to the Emacs server. ++* emacsclient Options:: Emacs client startup options. ++@end menu ++ ++@node Invoking emacsclient ++@subsection Invoking @code{emacsclient} ++@cindex @code{emacsclient} invocation ++ ++ The simplest way to use the @command{emacsclient} program is to run ++the shell command @samp{emacsclient @var{file}}, where @var{file} is a ++file name. This connects to an Emacs server, and tells that Emacs ++process to visit @var{file} in one of its existing frames---either a ++graphical frame, or one in a text-only terminal (@pxref{Frames}). You ++can then select that frame to begin editing. ++ ++ If there is no Emacs server, the @command{emacsclient} program halts ++with an error message. If the Emacs process has no existing ++frame---which can happen if it was started as a daemon (@pxref{Emacs ++Server})---then Emacs opens a frame on the terminal in which you ++called @command{emacsclient}, as though you had used the @samp{-t} ++option (@pxref{emacsclient Options}). ++ ++ On a graphical display, switching to the Emacs server is ++straightforward---just select its (system-level) window. If you are ++using a text-only terminal, there are two ways to switch between ++@command{emacsclient}'s shell and the Emacs server: (i) run the Emacs ++server and @command{emacsclient} on different virtual terminals, and ++switch to the Emacs server's virtual terminal after calling ++@command{emacsclient}; or (ii) call @command{emacsclient} from within ++the Emacs server itself, using Shell mode (@pxref{Interactive Shell}) ++or Term mode (@pxref{Term Mode}); @code{emacsclient} blocks only the ++subshell under Emacs, and you can still use Emacs to edit the file. ++ ++@kindex C-x # ++@findex server-edit ++ When you finish editing @var{file} in the Emacs server, type ++@kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file ++and sends a message back to the @command{emacsclient} program, telling ++it to exit. Programs that use @env{EDITOR} usually wait for the ++``editor''---in the case @command{emacsclient}---to exit before doing ++something else. ++ ++ You can also call @command{emacsclient} with multiple file name ++arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the ++Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs ++selects the buffer visiting @var{file1}, and buries the other buffers ++at the bottom of the buffer list (@pxref{Buffers}). The ++@command{emacsclient} program exits once all the specified files are ++finished (i.e., once you have typed @kbd{C-x #} in each server ++buffer). ++ ++@vindex server-kill-new-buffers ++@vindex server-temp-file-regexp ++ Finishing with a server buffer also kills the buffer, unless it ++already existed in the Emacs session before the server was asked to ++create it. However, if you set @code{server-kill-new-buffers} to ++@code{nil}, then a different criterion is used: finishing with a ++server buffer kills it if the file name matches the regular expression ++@code{server-temp-file-regexp}. This is set up to distinguish certain ++``temporary'' files. ++ ++ Each @kbd{C-x #} checks for other pending external requests to edit ++various files, and selects the next such file. You can switch to a ++server buffer manually if you wish; you don't have to arrive at it ++with @kbd{C-x #}. But @kbd{C-x #} is the way to tell ++@command{emacsclient} that you are finished. ++ ++@vindex server-window ++ If you set the variable @code{server-window} to a window or a frame, ++@kbd{C-x #} always displays the next server buffer in that window or ++in that frame. ++ ++@node emacsclient Options ++@subsection @code{emacsclient} Options ++@cindex @code{emacsclient} options ++ ++ You can pass some optional arguments to the @command{emacsclient} ++program, such as: ++ ++@example ++emacsclient -c +12 @var{file1} +4:3 @var{file2} ++@end example ++ ++@noindent ++The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments ++specify line numbers, or line and column numbers, for the next file ++argument. These behave like the command line arguments for Emacs ++itself. @xref{Action Arguments}. ++ ++ The other optional arguments recognized by @command{emacsclient} are ++listed below: ++ ++@table @samp ++@item -a @var{command} ++@itemx --alternate-editor=@var{command} ++Specify a command to run if @code{emacsclient} fails to contact Emacs. ++This is useful when running @code{emacsclient} in a script. For ++example, the following setting for the @env{EDITOR} environment ++variable will always give you an editor, even if no Emacs server is ++running: ++ ++@example ++EDITOR="emacsclient --alternate-editor emacs +%d %s" ++@end example ++ ++@noindent ++As a special exception, if @var{command} is the empty string, then ++@code{emacsclient} starts Emacs in daemon mode and then tries ++connecting again. ++ ++@cindex @env{ALTERNATE_EDITOR} environment variable ++The environment variable @env{ALTERNATE_EDITOR} has the same effect as ++the @samp{-a} option. If both are present, the latter takes ++precedence. ++ ++@item -c ++Create a new graphical frame, instead of using an existing Emacs ++frame. Emacs 23 can create a graphical frame even if it was started ++in a text-only terminal, provided it is able to connect to a graphical ++display. If no graphical display is available, Emacs creates a new ++text-only terminal frame (@pxref{Frames}). If you omit a filename ++argument while supplying the @samp{-c} option, the new frame displays ++the @samp{*scratch*} buffer (@pxref{Buffers}). ++ ++@item -d @var{display} ++@itemx --display=@var{display} ++Tell Emacs to open the given files on the X display @var{display} ++(assuming there is more than one X display available). ++ ++@item -e ++@itemx --eval ++Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some ++files. When this option is given, the arguments to ++@command{emacsclient} are interpreted as a list of expressions to ++evaluate, @emph{not} as a list of files to visit. ++ ++@item -f @var{server-file} ++@itemx --server-file=@var{server-file} ++@cindex @env{EMACS_SERVER_FILE} environment variable ++@cindex server file ++@vindex server-use-tcp ++@vindex server-host ++Specify a @dfn{server file} for connecting to an Emacs server via TCP. ++ ++An Emacs server usually uses an operating system feature called a ++``local socket'' to listen for connections. Some operating systems, ++such as Microsoft Windows, do not support local sockets; in that case, ++Emacs uses TCP instead. When you start the Emacs server, Emacs ++creates a server file containing some TCP information that ++@command{emacsclient} needs for making the connection. By default, ++the server file is in @file{~/.emacs.d/server/}. On Microsoft ++Windows, if @command{emacsclient} does not find the server file there, ++it looks in the @file{.emacs.d/server/} subdirectory of the directory ++pointed to by the @env{APPDATA} environment variable. You can tell ++@command{emacsclient} to use a specific server file with the @samp{-f} ++or @samp{--server-file} option, or by setting the ++@env{EMACS_SERVER_FILE} environment variable. ++ ++Even if local sockets are available, you can tell Emacs to use TCP by ++setting the variable @code{server-use-tcp} to @code{t}. One advantage ++of TCP is that the server can accept connections from remote machines. ++For this to work, you must (i) set the variable @code{server-host} to ++the hostname or IP address of the machine on which the Emacs server ++runs, and (ii) provide @command{emacsclient} with the server file. ++(One convenient way to do the latter is to put the server file on a ++networked file system such as NFS.) ++ ++@item -n ++@itemx --no-wait ++Let @command{emacsclient} exit immediately, instead of waiting until ++all server buffers are finished. You can take as long as you like to ++edit the server buffers within Emacs, and they are @emph{not} killed ++when you type @kbd{C-x #} in them. ++ ++@item -s @var{server-name} ++@itemx --socket-name=@var{server-name} ++Connect to the Emacs server named @var{server-name}. The server name ++is given by the variable @code{server-name} on the Emacs server. If ++this option is omitted, @command{emacsclient} connects to the first ++server it finds. (This option is not supported on MS-Windows.) ++ ++@item -t ++@itemx --tty ++@itemx -nw ++Create a new Emacs frame on the current text-only terminal, instead of ++using an existing Emacs frame. Emacs 23 can open a text-only terminal ++even if it was started in another text-only terminal, or on a ++graphical display. If you omit a filename argument while supplying ++this option, the new frame displays the @samp{*scratch*} buffer. ++@xref{Buffers}. ++@end table ++ ++ If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) in an ++Emacs frame created with @command{emacsclient}, via the @samp{-c} or ++@samp{-t} options, Emacs deletes the frame instead of killing the ++Emacs process itself. On a text-only terminal frame created with the ++@samp{-t} option, this returns control to the terminal. Emacs also ++marks all the server buffers for the client as finished, as though you ++had typed @kbd{C-x #} in all of them. ++ ++ When Emacs is started as a daemon, all frames are considered client ++frames, so @kbd{C-x C-c} will never kill Emacs. To kill the Emacs ++process, type @kbd{M-x kill-emacs}. ++ ++@node Printing, Sorting, Emacs Server, Top ++@section Printing Hard Copies ++@cindex hardcopy ++@cindex printing ++ ++ Emacs provides commands for printing hard copies of either an entire ++buffer or just part of one, with or without page headers. You can ++invoke the printing commands directly, as detailed in the following ++section, or using the @samp{File} menu on the menu bar. See also the ++hardcopy commands of Dired (@pxref{Misc File Ops}) and the diary ++(@pxref{Displaying the Diary}). ++ ++@table @kbd ++@item M-x print-buffer ++Print hardcopy of current buffer with page headings containing the file ++name and page number. ++@item M-x lpr-buffer ++Print hardcopy of current buffer without page headings. ++@item M-x print-region ++Like @code{print-buffer} but print only the current region. ++@item M-x lpr-region ++Like @code{lpr-buffer} but print only the current region. ++@end table ++ ++@findex print-buffer ++@findex print-region ++@findex lpr-buffer ++@findex lpr-region ++@vindex lpr-switches ++ The hardcopy commands (aside from the PostScript commands) pass extra ++switches to the @code{lpr} program based on the value of the variable ++@code{lpr-switches}. Its value should be a list of strings, each string ++an option starting with @samp{-}. For example, to specify a line width ++of 80 columns for all the printing you do in Emacs, set ++@code{lpr-switches} like this: ++ ++@example ++(setq lpr-switches '("-w80")) ++@end example ++ ++@vindex printer-name ++ You can specify the printer to use by setting the variable ++@code{printer-name}. ++ ++@vindex lpr-headers-switches ++@vindex lpr-commands ++@vindex lpr-add-switches ++ The variable @code{lpr-command} specifies the name of the printer ++program to run; the default value depends on your operating system type. ++On most systems, the default is @code{"lpr"}. The variable ++@code{lpr-headers-switches} similarly specifies the extra switches to ++use to make page headers. The variable @code{lpr-add-switches} controls ++whether to supply @samp{-T} and @samp{-J} options (suitable for ++@code{lpr}) to the printer program: @code{nil} means don't add them. ++@code{lpr-add-switches} should be @code{nil} if your printer program is ++not compatible with @code{lpr}. ++ ++@menu ++* PostScript:: Printing buffers or regions as PostScript. ++* PostScript Variables:: Customizing the PostScript printing commands. ++* Printing Package:: An optional advanced printing interface. ++@end menu ++ ++@node PostScript, PostScript Variables,, Printing ++@section PostScript Hardcopy ++ ++ These commands convert buffer contents to PostScript, ++either printing it or leaving it in another Emacs buffer. ++ ++@table @kbd ++@item M-x ps-print-buffer ++Print hardcopy of the current buffer in PostScript form. ++@item M-x ps-print-region ++Print hardcopy of the current region in PostScript form. ++@item M-x ps-print-buffer-with-faces ++Print hardcopy of the current buffer in PostScript form, showing the ++faces used in the text by means of PostScript features. ++@item M-x ps-print-region-with-faces ++Print hardcopy of the current region in PostScript form, showing the ++faces used in the text. ++@item M-x ps-spool-buffer ++Generate and spool a PostScript image for the current buffer text. ++@item M-x ps-spool-region ++Generate and spool a PostScript image for the current region. ++@item M-x ps-spool-buffer-with-faces ++Generate and spool a PostScript image for the current buffer, showing the faces used. ++@item M-x ps-spool-region-with-faces ++Generate and spool a PostScript image for the current region, showing the faces used. ++@item M-x ps-despool ++Send the spooled PostScript to the printer. ++@item M-x handwrite ++Generate/print PostScript for the current buffer as if handwritten. ++@end table ++ ++@findex ps-print-region ++@findex ps-print-buffer ++@findex ps-print-region-with-faces ++@findex ps-print-buffer-with-faces ++ The PostScript commands, @code{ps-print-buffer} and ++@code{ps-print-region}, print buffer contents in PostScript form. One ++command prints the entire buffer; the other, just the region. The ++corresponding @samp{-with-faces} commands, ++@code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces}, ++use PostScript features to show the faces (fonts and colors) in the text ++properties of the text being printed. The @samp{-with-faces} commands only ++work if they are used in a window system, so it has a way to determine color ++values. ++ ++ Interactively, when you use a prefix argument (@kbd{C-u}), the command ++prompts the user for a file name, and saves the PostScript image in that file ++instead of sending it to the printer. ++ ++ Noninteractively, the argument @var{filename} is treated as follows: if it is ++@code{nil}, send the image to the printer. If @var{filename} is a string, save ++the PostScript image in a file with that name. ++ ++ If you are using a color display, you can print a buffer of program ++code with color highlighting by turning on Font-Lock mode in that ++buffer, and using @code{ps-print-buffer-with-faces}. ++ ++@findex ps-spool-region ++@findex ps-spool-buffer ++@findex ps-spool-region-with-faces ++@findex ps-spool-buffer-with-faces ++ The commands whose names have @samp{spool} instead of @samp{print}, ++generate the PostScript output in an Emacs buffer instead of sending ++it to the printer. ++ ++ Use the command @code{ps-despool} to send the spooled images to the printer. ++ ++@findex ps-despool ++ This command sends the PostScript generated by @samp{-spool-} commands (see ++commands above) to the printer. ++ ++ Interactively, when you use a prefix argument (@kbd{C-u}), the command ++prompts the user for a file name, and saves the spooled PostScript image in ++that file instead of sending it to the printer. ++ ++ Noninteractively, the argument @var{filename} is treated as follows: if it is ++@code{nil}, send the image to the printer. If @var{filename} is a string, save ++the PostScript image in a file with that name. ++ ++@findex handwrite ++@cindex handwriting ++@kbd{M-x handwrite} is more frivolous. It generates a PostScript ++rendition of the current buffer as a cursive handwritten document. It ++can be customized in group @code{handwrite}. This function only ++supports ISO 8859-1 characters. ++ ++@ifnottex ++ The following section describes variables for customizing these commands. ++@end ifnottex ++ ++@node PostScript Variables, Printing Package, PostScript, Printing ++@section Variables for PostScript Hardcopy ++ ++@vindex ps-lpr-command ++@vindex ps-lpr-switches ++@vindex ps-printer-name ++ All the PostScript hardcopy commands use the variables ++@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print ++the output. @code{ps-lpr-command} specifies the command name to run, ++@code{ps-lpr-switches} specifies command line options to use, and ++@code{ps-printer-name} specifies the printer. If you don't set the ++first two variables yourself, they take their initial values from ++@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name} ++is @code{nil}, @code{printer-name} is used. ++ ++@vindex ps-print-header ++ The variable @code{ps-print-header} controls whether these commands ++add header lines to each page---set it to @code{nil} to turn headers ++off. ++ ++@cindex color emulation on black-and-white printers ++@vindex ps-print-color-p ++ If your printer doesn't support colors, you should turn off color ++processing by setting @code{ps-print-color-p} to @code{nil}. By ++default, if the display supports colors, Emacs produces hardcopy output ++with color information; on black-and-white printers, colors are emulated ++with shades of gray. This might produce illegible output, even if your ++screen colors only use shades of gray. ++ ++ Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to ++print colors on black/white printers. ++ ++@vindex ps-use-face-background ++ By default, PostScript printing ignores the background colors of the ++faces, unless the variable @code{ps-use-face-background} is ++non-@code{nil}. This is to avoid unwanted interference with the zebra ++stripes and background image/text. ++ ++@vindex ps-paper-type ++@vindex ps-page-dimensions-database ++ The variable @code{ps-paper-type} specifies which size of paper to ++format for; legitimate values include @code{a4}, @code{a3}, ++@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger}, ++@code{legal}, @code{letter}, @code{letter-small}, @code{statement}, ++@code{tabloid}. The default is @code{letter}. You can define ++additional paper sizes by changing the variable ++@code{ps-page-dimensions-database}. ++ ++@vindex ps-landscape-mode ++ The variable @code{ps-landscape-mode} specifies the orientation of ++printing on the page. The default is @code{nil}, which stands for ++``portrait'' mode. Any non-@code{nil} value specifies ``landscape'' ++mode. ++ ++@vindex ps-number-of-columns ++ The variable @code{ps-number-of-columns} specifies the number of ++columns; it takes effect in both landscape and portrait mode. The ++default is 1. ++ ++@vindex ps-font-family ++@vindex ps-font-size ++@vindex ps-font-info-database ++ The variable @code{ps-font-family} specifies which font family to use ++for printing ordinary text. Legitimate values include @code{Courier}, ++@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and ++@code{Times}. The variable @code{ps-font-size} specifies the size of ++the font for ordinary text. It defaults to 8.5 points. ++ ++@vindex ps-multibyte-buffer ++@cindex Intlfonts for PostScript printing ++@cindex fonts for PostScript printing ++ Emacs supports more scripts and characters than a typical PostScript ++printer. Thus, some of the characters in your buffer might not be ++printable using the fonts built into your printer. You can augment ++the fonts supplied with the printer with those from the GNU Intlfonts ++package, or you can instruct Emacs to use Intlfonts exclusively. The ++variable @code{ps-multibyte-buffer} controls this: the default value, ++@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1 ++characters; a value of @code{non-latin-printer} is for printers which ++have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean ++characters built into them. A value of @code{bdf-font} arranges for ++the BDF fonts from the Intlfonts package to be used for @emph{all} ++characters. Finally, a value of @code{bdf-font-except-latin} ++instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1 ++characters, and Intlfonts BDF fonts for the rest. ++ ++@vindex bdf-directory-list ++ To be able to use the BDF fonts, Emacs needs to know where to find ++them. The variable @code{bdf-directory-list} holds the list of ++directories where Emacs should look for the fonts; the default value ++includes a single directory @file{/usr/local/share/emacs/fonts/bdf}. ++ ++ Many other customization variables for these commands are defined and ++described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}. ++ ++@node Printing Package,, PostScript Variables, Printing ++@section Printing Package ++@cindex Printing package ++ ++ The basic Emacs facilities for printing hardcopy can be extended ++using the Printing package. This provides an easy-to-use interface ++for choosing what to print, previewing PostScript files before ++printing, and setting various printing options such as print headers, ++landscape or portrait modes, duplex modes, and so forth. On GNU/Linux ++or Unix systems, the Printing package relies on the @file{gs} and ++@file{gv} utilities, which are distributed as part of the GhostScript ++program. On MS-Windows, the @file{gstools} port of Ghostscript can be ++used. ++ ++@findex pr-interface ++ To use the Printing package, add @code{(require 'printing)} to your ++init file (@pxref{Init File}), followed by @code{(pr-update-menus)}. ++This function replaces the usual printing commands in the menu bar ++with a @samp{Printing} submenu that contains various printing options. ++You can also type @kbd{M-x pr-interface RET}; this creates a ++@samp{*Printing Interface*} buffer, similar to a customization buffer, ++where you can set the printing options. After selecting what and how ++to print, you start the print job using the @samp{Print} button (click ++@kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For ++further information on the various options, use the @samp{Interface ++Help} button. ++ ++@node Sorting, Narrowing, Printing, Top ++@section Sorting Text ++@cindex sorting ++ ++ Emacs provides several commands for sorting text in the buffer. All ++operate on the contents of the region. ++They divide the text of the region into many @dfn{sort records}, ++identify a @dfn{sort key} for each record, and then reorder the records ++into the order determined by the sort keys. The records are ordered so ++that their keys are in alphabetical order, or, for numeric sorting, in ++numeric order. In alphabetic sorting, all upper-case letters `A' through ++`Z' come before lower-case `a', in accord with the @acronym{ASCII} character ++sequence. ++ ++ The various sort commands differ in how they divide the text into sort ++records and in which part of each record is used as the sort key. Most of ++the commands make each line a separate sort record, but some commands use ++paragraphs or pages as sort records. Most of the sort commands use each ++entire sort record as its own sort key, but some use only a portion of the ++record as the sort key. ++ ++@findex sort-lines ++@findex sort-paragraphs ++@findex sort-pages ++@findex sort-fields ++@findex sort-numeric-fields ++@vindex sort-numeric-base ++@table @kbd ++@item M-x sort-lines ++Divide the region into lines, and sort by comparing the entire ++text of a line. A numeric argument means sort into descending order. ++ ++@item M-x sort-paragraphs ++Divide the region into paragraphs, and sort by comparing the entire ++text of a paragraph (except for leading blank lines). A numeric ++argument means sort into descending order. ++ ++@item M-x sort-pages ++Divide the region into pages, and sort by comparing the entire ++text of a page (except for leading blank lines). A numeric ++argument means sort into descending order. ++ ++@item M-x sort-fields ++Divide the region into lines, and sort by comparing the contents of ++one field in each line. Fields are defined as separated by ++whitespace, so the first run of consecutive non-whitespace characters ++in a line constitutes field 1, the second such run constitutes field ++2, etc. ++ ++Specify which field to sort by with a numeric argument: 1 to sort by ++field 1, etc. A negative argument means count fields from the right ++instead of from the left; thus, minus 1 means sort by the last field. ++If several lines have identical contents in the field being sorted, they ++keep the same relative order that they had in the original buffer. ++ ++@item M-x sort-numeric-fields ++Like @kbd{M-x sort-fields} except the specified field is converted ++to an integer for each line, and the numbers are compared. @samp{10} ++comes before @samp{2} when considered as text, but after it when ++considered as a number. By default, numbers are interpreted according ++to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or ++@samp{0} are interpreted as hexadecimal and octal, respectively. ++ ++@item M-x sort-columns ++Like @kbd{M-x sort-fields} except that the text within each line ++used for comparison comes from a fixed range of columns. See below ++for an explanation. ++ ++@item M-x reverse-region ++Reverse the order of the lines in the region. This is useful for ++sorting into descending order by fields or columns, since those sort ++commands do not have a feature for doing that. ++@end table ++ ++ For example, if the buffer contains this: ++ ++@smallexample ++On systems where clash detection (locking of files being edited) is ++implemented, Emacs also checks the first time you modify a buffer ++whether the file has changed on disk since it was last visited or ++saved. If it has, you are asked to confirm that you want to change ++the buffer. ++@end smallexample ++ ++@noindent ++applying @kbd{M-x sort-lines} to the entire buffer produces this: ++ ++@smallexample ++On systems where clash detection (locking of files being edited) is ++implemented, Emacs also checks the first time you modify a buffer ++saved. If it has, you are asked to confirm that you want to change ++the buffer. ++whether the file has changed on disk since it was last visited or ++@end smallexample ++ ++@noindent ++where the upper-case @samp{O} sorts before all lower-case letters. If ++you use @kbd{C-u 2 M-x sort-fields} instead, you get this: ++ ++@smallexample ++implemented, Emacs also checks the first time you modify a buffer ++saved. If it has, you are asked to confirm that you want to change ++the buffer. ++On systems where clash detection (locking of files being edited) is ++whether the file has changed on disk since it was last visited or ++@end smallexample ++ ++@noindent ++where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, ++@samp{systems} and @samp{the}. ++ ++@findex sort-columns ++ @kbd{M-x sort-columns} requires more explanation. You specify the ++columns by putting point at one of the columns and the mark at the other ++column. Because this means you cannot put point or the mark at the ++beginning of the first line of the text you want to sort, this command ++uses an unusual definition of ``region'': all of the line point is in is ++considered part of the region, and so is all of the line the mark is in, ++as well as all the lines in between. ++ ++ For example, to sort a table by information found in columns 10 to 15, ++you could put the mark on column 10 in the first line of the table, and ++point on column 15 in the last line of the table, and then run ++@code{sort-columns}. Equivalently, you could run it with the mark on ++column 15 in the first line and point on column 10 in the last line. ++ ++ This can be thought of as sorting the rectangle specified by point and ++the mark, except that the text on each line to the left or right of the ++rectangle moves along with the text inside the rectangle. ++@xref{Rectangles}. ++ ++@vindex sort-fold-case ++ Many of the sort commands ignore case differences when comparing, if ++@code{sort-fold-case} is non-@code{nil}. ++ ++@node Narrowing, Two-Column, Sorting, Top ++@section Narrowing ++@cindex widening ++@cindex restriction ++@cindex narrowing ++@cindex accessible portion ++ ++ @dfn{Narrowing} means focusing in on some portion of the buffer, ++making the rest temporarily inaccessible. The portion which you can ++still get to is called the @dfn{accessible portion}. Canceling the ++narrowing, which makes the entire buffer once again accessible, is ++called @dfn{widening}. The bounds of narrowing in effect in a buffer ++are called the buffer's @dfn{restriction}. ++ ++ Narrowing can make it easier to concentrate on a single subroutine or ++paragraph by eliminating clutter. It can also be used to limit the ++range of operation of a replace command or repeating keyboard macro. ++ ++@table @kbd ++@item C-x n n ++Narrow down to between point and mark (@code{narrow-to-region}). ++@item C-x n w ++Widen to make the entire buffer accessible again (@code{widen}). ++@item C-x n p ++Narrow down to the current page (@code{narrow-to-page}). ++@item C-x n d ++Narrow down to the current defun (@code{narrow-to-defun}). ++@end table ++ ++ When you have narrowed down to a part of the buffer, that part appears ++to be all there is. You can't see the rest, you can't move into it ++(motion commands won't go outside the accessible part), you can't change ++it in any way. However, it is not gone, and if you save the file all ++the inaccessible text will be saved. The word @samp{Narrow} appears in ++the mode line whenever narrowing is in effect. ++ ++@kindex C-x n n ++@findex narrow-to-region ++ The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}). ++It sets the current buffer's restrictions so that the text in the current ++region remains accessible, but all text before the region or after the ++region is inaccessible. Point and mark do not change. ++ ++@kindex C-x n p ++@findex narrow-to-page ++@kindex C-x n d ++@findex narrow-to-defun ++ Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow ++down to the current page. @xref{Pages}, for the definition of a page. ++@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun ++containing point (@pxref{Defuns}). ++ ++@kindex C-x n w ++@findex widen ++ The way to cancel narrowing is to widen with @kbd{C-x n w} ++(@code{widen}). This makes all text in the buffer accessible again. ++ ++ You can get information on what part of the buffer you are narrowed down ++to using the @kbd{C-x =} command. @xref{Position Info}. ++ ++ Because narrowing can easily confuse users who do not understand it, ++@code{narrow-to-region} is normally a disabled command. Attempting to use ++this command asks for confirmation and gives you the option of enabling it; ++if you enable the command, confirmation will no longer be required for ++it. @xref{Disabling}. ++ ++@node Two-Column, Editing Binary Files, Narrowing, Top ++@section Two-Column Editing ++@cindex two-column editing ++@cindex splitting columns ++@cindex columns, splitting ++ ++ Two-column mode lets you conveniently edit two side-by-side columns of ++text. It uses two side-by-side windows, each showing its own ++buffer. ++ ++ There are three ways to enter two-column mode: ++ ++@table @asis ++@item @kbd{@key{F2} 2} or @kbd{C-x 6 2} ++@kindex F2 2 ++@kindex C-x 6 2 ++@findex 2C-two-columns ++Enter two-column mode with the current buffer on the left, and on the ++right, a buffer whose name is based on the current buffer's name ++(@code{2C-two-columns}). If the right-hand buffer doesn't already ++exist, it starts out empty; the current buffer's contents are not ++changed. ++ ++This command is appropriate when the current buffer is empty or contains ++just one column and you want to add another column. ++ ++@item @kbd{@key{F2} s} or @kbd{C-x 6 s} ++@kindex F2 s ++@kindex C-x 6 s ++@findex 2C-split ++Split the current buffer, which contains two-column text, into two ++buffers, and display them side by side (@code{2C-split}). The current ++buffer becomes the left-hand buffer, but the text in the right-hand ++column is moved into the right-hand buffer. The current column ++specifies the split point. Splitting starts with the current line and ++continues to the end of the buffer. ++ ++This command is appropriate when you have a buffer that already contains ++two-column text, and you wish to separate the columns temporarily. ++ ++@item @kbd{@key{F2} b @var{buffer} @key{RET}} ++@itemx @kbd{C-x 6 b @var{buffer} @key{RET}} ++@kindex F2 b ++@kindex C-x 6 b ++@findex 2C-associate-buffer ++Enter two-column mode using the current buffer as the left-hand buffer, ++and using buffer @var{buffer} as the right-hand buffer ++(@code{2C-associate-buffer}). ++@end table ++ ++ @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which ++is a string that appears on each line between the two columns. You can ++specify the width of the separator with a numeric argument to ++@kbd{@key{F2} s}; that many characters, before point, constitute the ++separator string. By default, the width is 1, so the column separator ++is the character before point. ++ ++ When a line has the separator at the proper place, @kbd{@key{F2} s} ++puts the text after the separator into the right-hand buffer, and ++deletes the separator. Lines that don't have the column separator at ++the proper place remain unsplit; they stay in the left-hand buffer, and ++the right-hand buffer gets an empty line to correspond. (This is the ++way to write a line that ``spans both columns while in two-column ++mode'': write it in the left-hand buffer, and put an empty line in the ++right-hand buffer.) ++ ++@kindex F2 RET ++@kindex C-x 6 RET ++@findex 2C-newline ++ The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}} ++(@code{2C-newline}) inserts a newline in each of the two buffers at ++corresponding positions. This is the easiest way to add a new line to ++the two-column text while editing it in split buffers. ++ ++@kindex F2 1 ++@kindex C-x 6 1 ++@findex 2C-merge ++ When you have edited both buffers as you wish, merge them with ++@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the ++text from the right-hand buffer as a second column in the other buffer. ++To go back to two-column editing, use @kbd{@key{F2} s}. ++ ++@kindex F2 d ++@kindex C-x 6 d ++@findex 2C-dissociate ++ Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers, ++leaving each as it stands (@code{2C-dissociate}). If the other buffer, ++the one not current when you type @kbd{@key{F2} d}, is empty, ++@kbd{@key{F2} d} kills it. ++ ++@node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top ++@section Editing Binary Files ++ ++@cindex Hexl mode ++@cindex mode, Hexl ++@cindex editing binary files ++@cindex hex editing ++ There is a special major mode for editing binary files: Hexl mode. To ++use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit ++the file. This command converts the file's contents to hexadecimal and ++lets you edit the translation. When you save the file, it is converted ++automatically back to binary. ++ ++ You can also use @kbd{M-x hexl-mode} to translate an existing buffer ++into hex. This is useful if you visit a file normally and then discover ++it is a binary file. ++ ++ Ordinary text characters overwrite in Hexl mode. This is to reduce ++the risk of accidentally spoiling the alignment of data in the file. ++There are special commands for insertion. Here is a list of the ++commands of Hexl mode: ++ ++@c I don't think individual index entries for these commands are useful--RMS. ++@table @kbd ++@item C-M-d ++Insert a byte with a code typed in decimal. ++ ++@item C-M-o ++Insert a byte with a code typed in octal. ++ ++@item C-M-x ++Insert a byte with a code typed in hex. ++ ++@item C-x [ ++Move to the beginning of a 1k-byte ``page.'' ++ ++@item C-x ] ++Move to the end of a 1k-byte ``page.'' ++ ++@item M-g ++Move to an address specified in hex. ++ ++@item M-j ++Move to an address specified in decimal. ++ ++@item C-c C-c ++Leave Hexl mode, going back to the major mode this buffer had before you ++invoked @code{hexl-mode}. ++@end table ++ ++@noindent ++Other Hexl commands let you insert strings (sequences) of binary ++bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a ++hexl-@key{RET}} for details. ++ ++ ++@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top ++@section Saving Emacs Sessions ++@cindex saving sessions ++@cindex restore session ++@cindex remember editing session ++@cindex reload files ++@cindex desktop ++ ++ Use the desktop library to save the state of Emacs from one session ++to another. Once you save the Emacs @dfn{desktop}---the buffers, ++their file names, major modes, buffer positions, and so on---then ++subsequent Emacs sessions reload the saved desktop. ++ ++@findex desktop-save ++@vindex desktop-save-mode ++ You can save the desktop manually with the command @kbd{M-x ++desktop-save}. You can also enable automatic saving of the desktop ++when you exit Emacs, and automatic restoration of the last saved ++desktop when Emacs starts: use the Customization buffer (@pxref{Easy ++Customization}) to set @code{desktop-save-mode} to @code{t} for future ++sessions, or add this line in your init file (@pxref{Init File}): ++ ++@example ++(desktop-save-mode 1) ++@end example ++ ++@findex desktop-change-dir ++@findex desktop-revert ++ If you turn on @code{desktop-save-mode} in your init file, then when ++Emacs starts, it looks for a saved desktop in the current directory. ++Thus, you can have separate saved desktops in different directories, ++and the starting directory determines which one Emacs reloads. You ++can save the current desktop and reload one saved in another directory ++by typing @kbd{M-x desktop-change-dir}. Typing @kbd{M-x ++desktop-revert} reverts to the desktop previously reloaded. ++ ++ Specify the option @samp{--no-desktop} on the command line when you ++don't want it to reload any saved desktop. This turns off ++@code{desktop-save-mode} for the current session. Starting Emacs with ++the @samp{--no-init-file} option also disables desktop reloading, ++since it bypasses the init file, where @code{desktop-save-mode} is ++usually turned on. ++ ++@vindex desktop-restore-eager ++ By default, all the buffers in the desktop are restored at one go. ++However, this may be slow if there are a lot of buffers in the ++desktop. You can specify the maximum number of buffers to restore ++immediately with the variable @code{desktop-restore-eager}; the ++remaining buffers are restored ``lazily,'' when Emacs is idle. ++ ++@findex desktop-clear ++@vindex desktop-globals-to-clear ++@vindex desktop-clear-preserve-buffers-regexp ++ Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills ++all buffers except for internal ones, and clears the global variables ++listed in @code{desktop-globals-to-clear}. If you want this to ++preserve certain buffers, customize the variable ++@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular ++expression matching the names of buffers not to kill. ++ ++ If you want to save minibuffer history from one session to ++another, use the @code{savehist} library. ++ ++@node Recursive Edit, Emulation, Saving Emacs Sessions, Top ++@section Recursive Editing Levels ++@cindex recursive editing level ++@cindex editing level, recursive ++ ++ A @dfn{recursive edit} is a situation in which you are using Emacs ++commands to perform arbitrary editing while in the middle of another ++Emacs command. For example, when you type @kbd{C-r} inside of a ++@code{query-replace}, you enter a recursive edit in which you can change ++the current buffer. On exiting from the recursive edit, you go back to ++the @code{query-replace}. ++ ++@kindex C-M-c ++@findex exit-recursive-edit ++@cindex exiting recursive edit ++ @dfn{Exiting} the recursive edit means returning to the unfinished ++command, which continues execution. The command to exit is @kbd{C-M-c} ++(@code{exit-recursive-edit}). ++ ++ You can also @dfn{abort} the recursive edit. This is like exiting, ++but also quits the unfinished command immediately. Use the command ++@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}. ++ ++ The mode line shows you when you are in a recursive edit by displaying ++square brackets around the parentheses that always surround the major and ++minor mode names. Every window's mode line shows this in the same way, ++since being in a recursive edit is true of Emacs as a whole rather than ++any particular window or buffer. ++ ++ It is possible to be in recursive edits within recursive edits. For ++example, after typing @kbd{C-r} in a @code{query-replace}, you may type a ++command that enters the debugger. This begins a recursive editing level ++for the debugger, within the recursive editing level for @kbd{C-r}. ++Mode lines display a pair of square brackets for each recursive editing ++level currently in progress. ++ ++ Exiting the inner recursive edit (such as with the debugger @kbd{c} ++command) resumes the command running in the next level up. When that ++command finishes, you can then use @kbd{C-M-c} to exit another recursive ++editing level, and so on. Exiting applies to the innermost level only. ++Aborting also gets out of only one level of recursive edit; it returns ++immediately to the command level of the previous recursive edit. If you ++wish, you can then abort the next recursive editing level. ++ ++ Alternatively, the command @kbd{M-x top-level} aborts all levels of ++recursive edits, returning immediately to the top-level command ++reader. It also exits the minibuffer, if it is active. ++ ++ The text being edited inside the recursive edit need not be the same text ++that you were editing at top level. It depends on what the recursive edit ++is for. If the command that invokes the recursive edit selects a different ++buffer first, that is the buffer you will edit recursively. In any case, ++you can switch buffers within the recursive edit in the normal manner (as ++long as the buffer-switching keys have not been rebound). You could ++probably do all the rest of your editing inside the recursive edit, ++visiting files and all. But this could have surprising effects (such as ++stack overflow) from time to time. So remember to exit or abort the ++recursive edit when you no longer need it. ++ ++ In general, we try to minimize the use of recursive editing levels in ++GNU Emacs. This is because they constrain you to ``go back'' in a ++particular order---from the innermost level toward the top level. When ++possible, we present different activities in separate buffers so that ++you can switch between them as you please. Some commands switch to a ++new major mode which provides a command to switch back. These ++approaches give you more flexibility to go back to unfinished tasks in ++the order you choose. ++ ++@node Emulation, Hyperlinking, Recursive Edit, Top ++@section Emulation ++@cindex emulating other editors ++@cindex other editors ++@cindex EDT ++@cindex vi ++@cindex PC key bindings ++@cindex scrolling all windows ++@cindex PC selection ++@cindex Motif key bindings ++@cindex Macintosh key bindings ++@cindex WordStar ++ ++ GNU Emacs can be programmed to emulate (more or less) most other ++editors. Standard facilities can emulate these: ++ ++@table @asis ++@item CRiSP/Brief (PC editor) ++@findex crisp-mode ++@vindex crisp-override-meta-x ++@findex scroll-all-mode ++@cindex CRiSP mode ++@cindex Brief emulation ++@cindex emulation of Brief ++@cindex mode, CRiSP ++You can turn on key bindings to emulate the CRiSP/Brief editor with ++@kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs ++unless you set the variable @code{crisp-override-meta-x}. You can ++also use the command @kbd{M-x scroll-all-mode} or set the variable ++@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature ++(scrolling all windows together). ++ ++@item EDT (DEC VMS editor) ++@findex edt-emulation-on ++@findex edt-emulation-off ++Turn on EDT emulation with the command @kbd{M-x edt-emulation-on}, ++while @kbd{M-x edt-emulation-off} restores normal Emacs command ++bindings. ++ ++Most of the EDT emulation commands are keypad keys, and most standard ++Emacs key bindings are still available. The EDT emulation rebindings ++are done in the global keymap, so there is no problem switching ++buffers or major modes while in EDT emulation. ++ ++@item TPU (DEC VMS editor) ++@findex tpu-edt-on ++@cindex TPU ++@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT. ++ ++@item vi (Berkeley editor) ++@findex viper-mode ++Viper is the newest emulator for vi. It implements several levels of ++emulation; level 1 is closest to vi itself, while level 5 departs ++somewhat from strict emulation to take advantage of the capabilities of ++Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you ++the rest of the way and ask for the emulation level. @inforef{Top, ++Viper, viper}. ++ ++@item vi (another emulator) ++@findex vi-mode ++@kbd{M-x vi-mode} enters a major mode that replaces the previously ++established major mode. All of the vi commands that, in real vi, enter ++``input'' mode are programmed instead to return to the previous major ++mode. Thus, ordinary Emacs serves as vi's ``input'' mode. ++ ++Because vi emulation works through major modes, it does not work ++to switch buffers during emulation. Return to normal Emacs first. ++ ++If you plan to use vi emulation much, you probably want to bind a key ++to the @code{vi-mode} command. ++ ++@item vi (alternate emulator) ++@findex vip-mode ++@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi ++more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator ++is changed from ordinary Emacs so you can use @key{ESC} to go back to ++emulated vi command mode. To get from emulated vi command mode back to ++ordinary Emacs, type @kbd{C-z}. ++ ++This emulation does not work through major modes, and it is possible ++to switch buffers in various ways within the emulator. It is not ++so necessary to assign a key to the command @code{vip-mode} as ++it is with @code{vi-mode} because terminating insert mode does ++not use it. ++ ++@inforef{Top, VIP, vip}, for full information. ++ ++@item WordStar (old wordprocessor) ++@findex wordstar-mode ++@kbd{M-x wordstar-mode} provides a major mode with WordStar-like ++key bindings. ++@end table ++ ++@node Hyperlinking, Dissociated Press, Emulation, Top ++@section Hyperlinking and Navigation Features ++ ++@cindex hyperlinking ++@cindex navigation ++ Various modes documented elsewhere have hypertext features so that ++you can follow links, usually by clicking @kbd{Mouse-2} on the link or ++typing @key{RET} while point is on the link. Clicking @kbd{Mouse-1} ++quickly on the link also follows it. (Hold @kbd{Mouse-1} for longer ++if you want to set point instead.) ++ ++ Info mode, Help mode and the Dired-like modes are examples of modes ++that have links in the buffer. The Tags facility links between uses ++and definitions in source files, see @ref{Tags}. Imenu provides ++navigation amongst items indexed in the current buffer, see ++@ref{Imenu}. Info-lookup provides mode-specific lookup of definitions ++in Info indexes, see @ref{Documentation}. Speedbar maintains a frame ++in which links to files, and locations in files are displayed, see ++@ref{Speedbar}. ++ ++ Other non-mode-specific facilities described in this section enable ++following links from the current buffer in a context-sensitive ++fashion. ++ ++@menu ++* Browse-URL:: Following URLs. ++* Goto Address mode:: Activating URLs. ++* FFAP:: Finding files etc. at point. ++@end menu ++ ++@node Browse-URL ++@subsection Following URLs ++@cindex World Wide Web ++@cindex Web ++@findex browse-url ++@findex browse-url-at-point ++@findex browse-url-at-mouse ++@cindex Browse-URL ++@cindex URLs ++ ++@table @kbd ++@item M-x browse-url @key{RET} @var{url} @key{RET} ++Load a URL into a Web browser. ++@end table ++ ++The Browse-URL package provides facilities for following URLs specifying ++links on the World Wide Web. Usually this works by invoking a web ++browser, but you can, for instance, arrange to invoke @code{compose-mail} ++from @samp{mailto:} URLs. ++ ++ The general way to use this feature is to type @kbd{M-x browse-url}, ++which displays a specified URL. If point is located near a plausible ++URL, that URL is used as the default. Other commands are available ++which you might like to bind to keys, such as ++@code{browse-url-at-point} and @code{browse-url-at-mouse}. ++ ++@vindex browse-url-browser-function ++ You can customize Browse-URL's behavior via various options in the ++@code{browse-url} Customize group, particularly ++@code{browse-url-browser-function}. You can invoke actions dependent ++on the type of URL by defining @code{browse-url-browser-function} as ++an association list. The package's commentary available via @kbd{C-h ++p} under the @samp{hypermedia} keyword provides more information. ++Packages with facilities for following URLs should always go through ++Browse-URL, so that the customization options for Browse-URL will ++affect all browsing in Emacs. ++ ++@node Goto Address mode ++@subsection Activating URLs ++@findex goto-address-mode ++@cindex Goto Address mode ++@cindex URLs, activating ++ ++@table @kbd ++@item M-x goto-address-mode ++Activate URLs and e-mail addresses in the current buffer. ++@end table ++ ++ You can make URLs in the current buffer active with @kbd{M-x ++goto-address-mode}. This minor mode finds all the URLs in the buffer, ++highlights them, and turns them into @dfn{buttons}: if you click on a ++URL with @kbd{Mouse-1} or @kbd{Mouse-2} (@pxref{Mouse References}), or ++move to the URL and type @kbd{C-c @key{RET}}, that displays the web ++page that the URL specifies. For a @samp{mailto} URL, it sends mail ++instead, using your selected mail-composition method (@pxref{Mail ++Methods}). ++ ++ It can be useful to add @code{goto-address-mode} to mode hooks and ++the hooks used to display an incoming message (e.g., ++@code{rmail-show-message-hook} for Rmail, and @code{mh-show-mode-hook} ++for MH-E). This is not needed for Gnus, which has a similar feature ++of its own. ++ ++@node FFAP ++@subsection Finding Files and URLs at Point ++@findex find-file-at-point ++@findex ffap ++@findex dired-at-point ++@findex ffap-next ++@findex ffap-menu ++@cindex finding file at point ++ ++ FFAP mode replaces certain key bindings for finding files, including ++@kbd{C-x C-f}, with commands that provide more sensitive defaults. ++These commands behave like the ordinary ones when given a prefix ++argument. Otherwise, they get the default file name or URL from the ++text around point. If what is found in the buffer has the form of a ++URL rather than a file name, the commands use @code{browse-url} to ++view it. ++ ++ This feature is useful for following references in mail or news ++buffers, @file{README} files, @file{MANIFEST} files, and so on. The ++@samp{ffap} package's commentary available via @kbd{C-h p} under the ++@samp{files} keyword and the @code{ffap} Custom group provide details. ++ ++@cindex FFAP minor mode ++@findex ffap-mode ++ You can turn on FFAP minor mode by calling @code{ffap-bindings} to ++make the following key bindings and to install hooks for using ++@code{ffap} in Rmail, Gnus and VM article buffers. ++ ++@table @kbd ++@item C-x C-f @var{filename} @key{RET} ++@kindex C-x C-f @r{(FFAP)} ++Find @var{filename}, guessing a default from text around point ++(@code{find-file-at-point}). ++@item C-x C-r ++@kindex C-x C-r @r{(FFAP)} ++@code{ffap-read-only}, analogous to @code{find-file-read-only}. ++@item C-x C-v ++@kindex C-x C-v @r{(FFAP)} ++@code{ffap-alternate-file}, analogous to @code{find-alternate-file}. ++@item C-x d @var{directory} @key{RET} ++@kindex C-x d @r{(FFAP)} ++Start Dired on @var{directory}, defaulting to the directory name at ++point (@code{dired-at-point}). ++@item C-x C-d ++@code{ffap-list-directory}, analogous to @code{list-directory}. ++@item C-x 4 f ++@kindex C-x 4 f @r{(FFAP)} ++@code{ffap-other-window}, analogous to @code{find-file-other-window}. ++@item C-x 4 r ++@code{ffap-read-only-other-window}, analogous to ++@code{find-file-read-only-other-window}. ++@item C-x 4 d ++@code{ffap-dired-other-window}, analogous to @code{dired-other-window}. ++@item C-x 5 f ++@kindex C-x 5 f @r{(FFAP)} ++@code{ffap-other-frame}, analogous to @code{find-file-other-frame}. ++@item C-x 5 r ++@code{ffap-read-only-other-frame}, analogous to ++@code{find-file-read-only-other-frame}. ++@item C-x 5 d ++@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}. ++@item M-x ffap-next ++Search buffer for next file name or URL, then find that file or URL. ++@item S-Mouse-3 ++@kindex S-Mouse-3 @r{(FFAP)} ++@code{ffap-at-mouse} finds the file guessed from text around the position ++of a mouse click. ++@item C-S-Mouse-3 ++@kindex C-S-Mouse-3 @r{(FFAP)} ++Display a menu of files and URLs mentioned in current buffer, then ++find the one you select (@code{ffap-menu}). ++@end table ++ ++@node Dissociated Press, Amusements, Hyperlinking, Top ++@section Dissociated Press ++ ++@findex dissociated-press ++ @kbd{M-x dissociated-press} is a command for scrambling a file of text ++either word by word or character by character. Starting from a buffer of ++straight English, it produces extremely amusing output. The input comes ++from the current Emacs buffer. Dissociated Press writes its output in a ++buffer named @samp{*Dissociation*}, and redisplays that buffer after every ++couple of lines (approximately) so you can read the output as it comes out. ++ ++ Dissociated Press asks every so often whether to continue generating ++output. Answer @kbd{n} to stop it. You can also stop at any time by ++typing @kbd{C-g}. The dissociation output remains in the ++@samp{*Dissociation*} buffer for you to copy elsewhere if you wish. ++ ++@cindex presidentagon ++ Dissociated Press operates by jumping at random from one point in ++the buffer to another. In order to produce plausible output rather ++than gibberish, it insists on a certain amount of overlap between the ++end of one run of consecutive words or characters and the start of the ++next. That is, if it has just output `president' and then decides to ++jump to a different point in the buffer, it might spot the `ent' in ++`pentagon' and continue from there, producing `presidentagon'. Long ++sample texts produce the best results. ++ ++@cindex againformation ++ A positive argument to @kbd{M-x dissociated-press} tells it to operate ++character by character, and specifies the number of overlap characters. A ++negative argument tells it to operate word by word, and specifies the number ++of overlap words. In this mode, whole words are treated as the elements to ++be permuted, rather than characters. No argument is equivalent to an ++argument of two. For your againformation, the output goes only into the ++buffer @samp{*Dissociation*}. The buffer you start with is not changed. ++ ++@cindex Markov chain ++@cindex ignoriginal ++@cindex techniquitous ++ Dissociated Press produces results fairly like those of a Markov ++chain based on a frequency table constructed from the sample text. It ++is, however, an independent, ignoriginal invention. Dissociated Press ++techniquitously copies several consecutive characters from the sample ++text between random jumps, unlike a Markov chain which would jump ++randomly after each word or character. This makes for more plausible ++sounding results, and runs faster. ++ ++@cindex outragedy ++@cindex buggestion ++@cindex properbose ++@cindex mustatement ++@cindex developediment ++@cindex userenced ++ It is a mustatement that too much use of Dissociated Press can be a ++developediment to your real work, sometimes to the point of outragedy. ++And keep dissociwords out of your documentation, if you want it to be well ++userenced and properbose. Have fun. Your buggestions are welcome. ++ ++@node Amusements, Customization, Dissociated Press, Top ++@section Other Amusements ++@cindex boredom ++@findex hanoi ++@findex yow ++@findex gomoku ++@cindex tower of Hanoi ++ ++ If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are ++considerably bored, give it a numeric argument. If you are very, very ++bored, try an argument of 9. Sit back and watch. ++ ++@cindex Go Moku ++ If you want a little more personal involvement, try @kbd{M-x gomoku}, ++which plays the game Go Moku with you. ++ ++@findex blackbox ++@findex mpuz ++@findex 5x5 ++@cindex puzzles ++ @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles. ++@code{blackbox} challenges you to determine the location of objects ++inside a box by tomography. @code{mpuz} displays a multiplication ++puzzle with letters standing for digits in a code that you must ++guess---to guess a value, type a letter and then the digit you think it ++stands for. The aim of @code{5x5} is to fill in all the squares. ++ ++@findex decipher ++@cindex ciphers ++@cindex cryptanalysis ++@kbd{M-x decipher} helps you to cryptanalyze a buffer which is encrypted ++in a simple monoalphabetic substitution cipher. ++ ++@findex dunnet ++ @kbd{M-x dunnet} runs an adventure-style exploration game, which is ++a bigger sort of puzzle. ++ ++@findex lm ++@cindex landmark game ++@kbd{M-x lm} runs a relatively non-participatory game in which a robot ++attempts to maneuver towards a tree at the center of the window based on ++unique olfactory cues from each of the four directions. ++ ++@findex life ++@cindex Life ++@kbd{M-x life} runs Conway's ``Life'' cellular automaton. ++ ++@findex morse-region ++@findex unmorse-region ++@cindex Morse code ++@cindex --/---/.-./.../. ++@kbd{M-x morse-region} converts text in a region to Morse code and ++@kbd{M-x unmorse-region} converts it back. No cause for remorse. ++ ++@findex pong ++@cindex Pong game ++@kbd{M-x pong} plays a Pong-like game, bouncing the ball off opposing ++bats. ++ ++@findex solitaire ++@cindex solitaire ++@kbd{M-x solitaire} plays a game of solitaire in which you jump pegs ++across other pegs. ++ ++@findex studlify-region ++@cindex StudlyCaps ++@kbd{M-x studlify-region} studlify-cases the region, producing ++text like this: ++ ++@example ++M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region. ++@end example ++ ++@findex tetris ++@cindex Tetris ++@findex snake ++@cindex Snake ++@kbd{M-x tetris} runs an implementation of the well-known Tetris game. ++Likewise, @kbd{M-x snake} provides an implementation of Snake. ++ ++ When you are frustrated, try the famous Eliza program. Just do ++@kbd{M-x doctor}. End each input by typing @key{RET} twice. ++ ++@cindex Zippy ++ When you are feeling strange, type @kbd{M-x yow}. ++ ++@findex zone ++The command @kbd{M-x zone} plays games with the display when Emacs is ++idle. ++ ++@ifnottex ++@lowersections ++@end ifnottex ++ ++@ignore ++ arch-tag: 8f094220-c0d5-4e9e-af7d-3e0da8187474 ++@end ignore +diff --git a/doc/emacs/msdog-xtra.texi b/doc/emacs/msdog-xtra.texi +new file mode 100644 +index 0000000..78b70f7 +--- /dev/null ++++ b/doc/emacs/msdog-xtra.texi +@@ -0,0 +1,619 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@c This file is included either in emacs-xtra.texi (when producing the ++@c printed version) or in the main Emacs manual (for the on-line version). ++@node MS-DOS ++@section Emacs and MS-DOS ++@cindex MS-DOG ++@cindex MS-DOS peculiarities ++ ++ This section briefly describes the peculiarities of using Emacs on ++the MS-DOS ``operating system'' (also known as ``MS-DOG''). ++@iftex ++Information about Emacs and Microsoft's current operating system ++Windows (also known as ``Losedows'') is in the main Emacs manual ++(@pxref{Microsoft Windows,,, emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++Information about peculiarities common to MS-DOS and Microsoft's ++current operating systems Windows (also known as ``Losedows'') is in ++@ref{Microsoft Windows}. ++@end ifnottex ++ ++ If you build Emacs for MS-DOS, the binary will also run on Windows ++3.X, Windows NT, Windows 9X/ME, Windows 2000/XP, or OS/2 as a DOS ++application; all of this chapter applies for all of those systems, if ++you use an Emacs that was built for MS-DOS. ++ ++@iftex ++ @xref{Text and Binary,,,emacs, the Emacs Manual}, for information ++@end iftex ++@ifnottex ++ @xref{Text and Binary}, for information ++@end ifnottex ++about Emacs' special handling of text files under MS-DOS (and Windows). ++ ++@menu ++* Keyboard: MS-DOS Keyboard. Keyboard conventions on MS-DOS. ++* Mouse: MS-DOS Mouse. Mouse conventions on MS-DOS. ++* Display: MS-DOS Display. Fonts, frames and display size on MS-DOS. ++* Files: MS-DOS File Names. File name conventions on MS-DOS. ++* Printing: MS-DOS Printing. Printing specifics on MS-DOS. ++* I18N: MS-DOS and MULE. Support for internationalization on MS-DOS. ++* Processes: MS-DOS Processes. Running subprocesses on MS-DOS. ++@end menu ++ ++@node MS-DOS Keyboard ++@subsection Keyboard Usage on MS-DOS ++ ++@kindex DEL @r{(MS-DOS)} ++@kindex BS @r{(MS-DOS)} ++ The key that is called @key{DEL} in Emacs (because that's how it is ++designated on most workstations) is known as @key{BS} (backspace) on a ++PC. That is why the PC-specific terminal initialization remaps the ++@key{BS} key to act as @key{DEL}; the @key{DELETE} key is remapped to act ++as @kbd{C-d} for the same reasons. ++ ++@kindex C-g @r{(MS-DOS)} ++@kindex C-BREAK @r{(MS-DOS)} ++@cindex quitting on MS-DOS ++ Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit ++character, just like @kbd{C-g}. This is because Emacs cannot detect ++that you have typed @kbd{C-g} until it is ready for more input. As a ++consequence, you cannot use @kbd{C-g} to stop a running command ++@iftex ++(@pxref{Quitting,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Quitting}). ++@end ifnottex ++By contrast, @kbd{C-@key{BREAK}} @emph{is} detected as soon as you ++type it (as @kbd{C-g} is on other systems), so it can be used to stop ++a running command and for emergency escape ++@iftex ++(@pxref{Emergency Escape,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Emergency Escape}). ++@end ifnottex ++ ++@cindex Meta (under MS-DOS) ++@cindex Hyper (under MS-DOS) ++@cindex Super (under MS-DOS) ++@vindex dos-super-key ++@vindex dos-hyper-key ++ The PC keyboard maps use the left @key{ALT} key as the @key{META} key. ++You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: ++choose either the right @key{CTRL} key or the right @key{ALT} key by ++setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 ++or 2 respectively. If neither @code{dos-super-key} nor ++@code{dos-hyper-key} is 1, then by default the right @key{ALT} key is ++also mapped to the @key{META} key. However, if the MS-DOS international ++keyboard support program @file{KEYB.COM} is installed, Emacs will ++@emph{not} map the right @key{ALT} to @key{META}, since it is used for ++accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard ++layouts; in this case, you may only use the left @key{ALT} as @key{META} ++key. ++ ++@kindex C-j @r{(MS-DOS)} ++@vindex dos-keypad-mode ++ The variable @code{dos-keypad-mode} is a flag variable that controls ++what key codes are returned by keys in the numeric keypad. You can also ++define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the ++following line into your @file{_emacs} file: ++ ++@smallexample ++;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.} ++(define-key function-key-map [kp-enter] [?\C-j]) ++@end smallexample ++ ++@node MS-DOS Mouse ++@subsection Mouse Usage on MS-DOS ++ ++@cindex mouse support under MS-DOS ++ Emacs on MS-DOS supports a mouse (on the default terminal only). ++The mouse commands work as documented, including those that use menus ++and the menu bar ++@iftex ++(@pxref{Menu Bar,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Menu Bar}). ++@end ifnottex ++ Scroll bars don't work in MS-DOS Emacs. PC mice usually have only ++two buttons; these act as @kbd{Mouse-1} and @kbd{Mouse-2}, but if you ++press both of them together, that has the effect of @kbd{Mouse-3}. If ++the mouse does have 3 buttons, Emacs detects that at startup, and all ++the 3 buttons function normally, as on X. ++ ++ Help strings for menu-bar and pop-up menus are displayed in the echo ++area when the mouse pointer moves across the menu items. Highlighting ++of mouse-sensitive text ++@iftex ++(@pxref{Mouse References,,,emacs, the Emacs Manual}) ++@end iftex ++@ifnottex ++(@pxref{Mouse References}) ++@end ifnottex ++is also supported. ++ ++@cindex mouse, set number of buttons ++@findex msdos-set-mouse-buttons ++ Some versions of mouse drivers don't report the number of mouse ++buttons correctly. For example, mice with a wheel report that they ++have 3 buttons, but only 2 of them are passed to Emacs; the clicks on ++the wheel, which serves as the middle button, are not passed. In ++these cases, you can use the @kbd{M-x msdos-set-mouse-buttons} command ++to tell Emacs how many mouse buttons to expect. You could make such a ++setting permanent by adding this fragment to your @file{_emacs} init ++file: ++ ++@example ++;; @r{Treat the mouse like a 2-button mouse.} ++(msdos-set-mouse-buttons 2) ++@end example ++ ++@cindex Windows clipboard support ++ Emacs built for MS-DOS supports clipboard operations when it runs on ++Windows. Commands that put text on the kill ring, or yank text from ++the ring, check the Windows clipboard first, just as Emacs does on the ++X Window System ++@iftex ++(@pxref{Mouse Commands,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Mouse Commands}). ++@end ifnottex ++Only the primary selection and the cut buffer are supported by MS-DOS ++Emacs on Windows; the secondary selection always appears as empty. ++ ++ Due to the way clipboard access is implemented by Windows, the ++length of text you can put into the clipboard is limited by the amount ++of free DOS memory that is available to Emacs. Usually, up to 620KB of ++text can be put into the clipboard, but this limit depends on the system ++configuration and is lower if you run Emacs as a subprocess of ++another program. If the killed text does not fit, Emacs outputs a ++message saying so, and does not put the text into the clipboard. ++ ++ Null characters also cannot be put into the Windows clipboard. If the ++killed text includes null characters, Emacs does not put such text into ++the clipboard, and displays in the echo area a message to that effect. ++ ++@vindex dos-display-scancodes ++ The variable @code{dos-display-scancodes}, when non-@code{nil}, ++directs Emacs to display the @acronym{ASCII} value and the keyboard scan code of ++each keystroke; this feature serves as a complement to the ++@code{view-lossage} command, for debugging. ++ ++@node MS-DOS Display ++@subsection Display on MS-DOS ++@cindex faces under MS-DOS ++@cindex fonts, emulating under MS-DOS ++ ++ Display on MS-DOS cannot use font variants, like bold or italic, but ++it does support multiple faces, each of which can specify a foreground ++and a background color. Therefore, you can get the full functionality ++of Emacs packages that use fonts (such as @code{font-lock}, Enriched ++Text mode, and others) by defining the relevant faces to use different ++colors. Use the @code{list-colors-display} command ++@iftex ++(@pxref{Frame Parameters,,,emacs, the Emacs Manual}) ++@end iftex ++@ifnottex ++(@pxref{Frame Parameters}) ++@end ifnottex ++and the @code{list-faces-display} command ++@iftex ++(@pxref{Faces,,,emacs, the Emacs Manual}) ++@end iftex ++@ifnottex ++(@pxref{Faces}) ++@end ifnottex ++to see what colors and faces are available and what they look like. ++ ++ @xref{MS-DOS and MULE}, later in this chapter, for information on ++how Emacs displays glyphs and characters that aren't supported by the ++native font built into the DOS display. ++ ++@cindex cursor shape on MS-DOS ++ When Emacs starts, it changes the cursor shape to a solid box. This ++is for compatibility with other systems, where the box cursor is the ++default in Emacs. This default shape can be changed to a bar by ++specifying the @code{cursor-type} parameter in the variable ++@code{default-frame-alist} ++@iftex ++(@pxref{Creating Frames,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Creating Frames}). ++@end ifnottex ++The MS-DOS terminal doesn't support a vertical-bar cursor, ++so the bar cursor is horizontal, and the @code{@var{width}} parameter, ++if specified by the frame parameters, actually determines its height. ++For this reason, the @code{bar} and @code{hbar} cursor types produce ++the same effect on MS-DOS. As an extension, the bar cursor ++specification can include the starting scan line of the cursor as well ++as its width, like this: ++ ++@example ++ '(cursor-type bar @var{width} . @var{start}) ++@end example ++ ++@noindent ++In addition, if the @var{width} parameter is negative, the cursor bar ++begins at the top of the character cell. ++ ++@cindex frames on MS-DOS ++ The MS-DOS terminal can only display a single frame at a time. The ++Emacs frame facilities work on MS-DOS much as they do on text-only ++terminals ++@iftex ++(@pxref{Frames,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Frames}). ++@end ifnottex ++When you run Emacs from a DOS window on MS-Windows, you can make the ++visible frame smaller than the full screen, but Emacs still cannot ++display more than a single frame at a time. ++ ++@cindex frame size under MS-DOS ++@findex mode4350 ++@findex mode25 ++ The @code{mode4350} command switches the display to 43 or 50 ++lines, depending on your hardware; the @code{mode25} command switches ++to the default 80x25 screen size. ++ ++ By default, Emacs only knows how to set screen sizes of 80 columns by ++25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has ++special video modes that will switch the display to other sizes, you can ++have Emacs support those too. When you ask Emacs to switch the frame to ++@var{n} rows by @var{m} columns dimensions, it checks if there is a ++variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so, ++uses its value (which must be an integer) as the video mode to switch ++to. (Emacs switches to that video mode by calling the BIOS @code{Set ++Video Mode} function with the value of ++@code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.) ++For example, suppose your adapter will switch to 66x80 dimensions when ++put into video mode 85. Then you can make Emacs support this screen ++size by putting the following into your @file{_emacs} file: ++ ++@example ++(setq screen-dimensions-66x80 85) ++@end example ++ ++ Since Emacs on MS-DOS can only set the frame size to specific ++supported dimensions, it cannot honor every possible frame resizing ++request. When an unsupported size is requested, Emacs chooses the next ++larger supported size beyond the specified size. For example, if you ++ask for 36x80 frame, you will get 40x80 instead. ++ ++ The variables @code{screen-dimensions-@var{n}x@var{m}} are used only ++when they exactly match the specified size; the search for the next ++larger supported size ignores them. In the above example, even if your ++VGA supports 38x80 dimensions and you define a variable ++@code{screen-dimensions-38x80} with a suitable value, you will still get ++40x80 screen when you ask for a 36x80 frame. If you want to get the ++38x80 size in this case, you can do it by setting the variable named ++@code{screen-dimensions-36x80} with the same video mode value as ++@code{screen-dimensions-38x80}. ++ ++ Changing frame dimensions on MS-DOS has the effect of changing all the ++other frames to the new dimensions. ++ ++@node MS-DOS File Names ++@subsection File Names on MS-DOS ++@cindex file names under MS-DOS ++@cindex init file, default name under MS-DOS ++ ++ On MS-DOS, file names are case-insensitive and limited to eight ++characters, plus optionally a period and three more characters. Emacs ++knows enough about these limitations to handle file names that were ++meant for other operating systems. For instance, leading dots ++@samp{.} in file names are invalid in MS-DOS, so Emacs transparently ++converts them to underscores @samp{_}; thus your default init file ++@iftex ++(@pxref{Init File,,,emacs, the Emacs Manual}) ++@end iftex ++@ifnottex ++(@pxref{Init File}) ++@end ifnottex ++is called @file{_emacs} on MS-DOS. Excess characters before or after ++the period are generally ignored by MS-DOS itself; thus, if you visit ++the file @file{LongFileName.EvenLongerExtension}, you will silently ++get @file{longfile.eve}, but Emacs will still display the long file ++name on the mode line. Other than that, it's up to you to specify ++file names which are valid under MS-DOS; the transparent conversion as ++described above only works on file names built into Emacs. ++ ++@cindex backup file names on MS-DOS ++ The above restrictions on the file names on MS-DOS make it almost ++impossible to construct the name of a backup file ++@iftex ++(@pxref{Backup Names,,,emacs, the Emacs Manual}) ++@end iftex ++@ifnottex ++(@pxref{Backup Names}) ++@end ifnottex ++without losing some of the original file name characters. For ++example, the name of a backup file for @file{docs.txt} is ++@file{docs.tx~} even if single backup is used. ++ ++@cindex file names under Windows 95/NT ++@cindex long file names in DOS box under Windows 95/NT ++ If you run Emacs as a DOS application under Windows 9X, Windows ME, or ++Windows 2000/XP, you can turn on support for long file names. If you do ++that, Emacs doesn't truncate file names or convert them to lower case; ++instead, it uses the file names that you specify, verbatim. To enable ++long file name support, set the environment variable @env{LFN} to ++@samp{y} before starting Emacs. Unfortunately, Windows NT doesn't allow ++DOS programs to access long file names, so Emacs built for MS-DOS will ++only see their short 8+3 aliases. ++ ++@cindex @env{HOME} directory under MS-DOS ++ MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends ++that the directory where it is installed is the value of the @env{HOME} ++environment variable. That is, if your Emacs binary, ++@file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then ++Emacs acts as if @env{HOME} were set to @samp{c:/utils/emacs}. In ++particular, that is where Emacs looks for the init file @file{_emacs}. ++With this in mind, you can use @samp{~} in file names as an alias for ++the home directory, as you would on GNU or Unix. You can also set ++@env{HOME} variable in the environment before starting Emacs; its ++value will then override the above default behavior. ++ ++ Emacs on MS-DOS handles the directory name @file{/dev} specially, ++because of a feature in the emulator libraries of DJGPP that pretends ++I/O devices have names in that directory. We recommend that you avoid ++using an actual directory named @file{/dev} on any disk. ++ ++@node MS-DOS Printing ++@subsection Printing and MS-DOS ++ ++ Printing commands, such as @code{lpr-buffer} ++@iftex ++(@pxref{Printing,,,emacs, the Emacs Manual}) and @code{ps-print-buffer} ++(@pxref{PostScript,,,emacs, the Emacs Manual}) ++@end iftex ++@ifnottex ++(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}) ++@end ifnottex ++can work on MS-DOS by sending the output to one of the printer ports, ++if a Posix-style @code{lpr} program is unavailable. The same Emacs ++variables control printing on all systems, but in some cases they have ++different default values on MS-DOS. ++ ++@iftex ++@xref{Windows Printing,,,emacs, the Emacs Manual}, ++@end iftex ++@ifnottex ++@xref{Windows Printing}, ++@end ifnottex ++for details about setting up printing to a networked printer. ++ ++ Some printers expect DOS codepage encoding of non-@acronym{ASCII} text, even ++though they are connected to a Windows machine which uses a different ++encoding for the same locale. For example, in the Latin-1 locale, DOS ++uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and ++MULE}. When you print to such printers from Windows, you can use the ++@kbd{C-x RET c} (@code{universal-coding-system-argument}) command before ++@kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS ++codepage that you specify. For example, @kbd{C-x RET c cp850-dos RET ++M-x lpr-region RET} will print the region while converting it to the ++codepage 850 encoding. ++ ++@vindex dos-printer ++@vindex dos-ps-printer ++ For backwards compatibility, the value of @code{dos-printer} ++(@code{dos-ps-printer}), if it has a value, overrides the value of ++@code{printer-name} (@code{ps-printer-name}), on MS-DOS. ++ ++ ++@node MS-DOS and MULE ++@subsection International Support on MS-DOS ++@cindex international support @r{(MS-DOS)} ++ ++ Emacs on MS-DOS supports the same international character sets as it ++does on GNU, Unix and other platforms ++@iftex ++(@pxref{International,,,emacs, the Emacs Manual}), ++@end iftex ++@ifnottex ++(@pxref{International}), ++@end ifnottex ++including coding systems for converting between the different ++character sets. However, due to incompatibilities between ++MS-DOS/MS-Windows and other systems, there are several DOS-specific ++aspects of this support that you should be aware of. This section ++describes these aspects. ++ ++ The description below is largely specific to the MS-DOS port of ++Emacs, especially where it talks about practical implications for ++Emacs users. ++ ++@table @kbd ++@item M-x dos-codepage-setup ++Set up Emacs display and coding systems as appropriate for the current ++DOS codepage. ++@end table ++ ++@cindex codepage, MS-DOS ++@cindex DOS codepages ++ MS-DOS is designed to support one character set of 256 characters at ++any given time, but gives you a variety of character sets to choose ++from. The alternative character sets are known as @dfn{DOS codepages}. ++Each codepage includes all 128 @acronym{ASCII} characters, but the other 128 ++characters (codes 128 through 255) vary from one codepage to another. ++Each DOS codepage is identified by a 3-digit number, such as 850, 862, ++etc. ++ ++ In contrast to X, which lets you use several fonts at the same time, ++MS-DOS normally doesn't allow use of several codepages in a single ++session. MS-DOS was designed to load a single codepage at system ++startup, and require you to reboot in order to change ++it@footnote{Normally, one particular codepage is burnt into the ++display memory, while other codepages can be installed by modifying ++system configuration files, such as @file{CONFIG.SYS}, and rebooting. ++While there is third-party software that allows changing the codepage ++without rebooting, we describe here how a stock MS-DOS system ++behaves.}. Much the same limitation applies when you run DOS ++executables on other systems such as MS-Windows. ++ ++@vindex dos-codepage ++ For multibyte operation on MS-DOS, Emacs needs to know which ++characters the chosen DOS codepage can display. So it queries the ++system shortly after startup to get the chosen codepage number, and ++stores the number in the variable @code{dos-codepage}. Some systems ++return the default value 437 for the current codepage, even though the ++actual codepage is different. (This typically happens when you use the ++codepage built into the display hardware.) You can specify a different ++codepage for Emacs to use by setting the variable @code{dos-codepage} in ++your init file. ++ ++@cindex language environment, automatic selection on @r{MS-DOS} ++ Multibyte Emacs supports only certain DOS codepages: those which can ++display Far-Eastern scripts, like the Japanese codepage 932, and those ++that encode a single ISO 8859 character set. ++ ++ The Far-Eastern codepages can directly display one of the MULE ++character sets for these countries, so Emacs simply sets up to use the ++appropriate terminal coding system that is supported by the codepage. ++The special features described in the rest of this section mostly ++pertain to codepages that encode ISO 8859 character sets. ++ ++ For the codepages which correspond to one of the ISO character sets, ++Emacs knows the character set based on the codepage number. Emacs ++automatically creates a coding system to support reading and writing ++files that use the current codepage, and uses this coding system by ++default. The name of this coding system is @code{cp@var{nnn}}, where ++@var{nnn} is the codepage number.@footnote{The standard Emacs coding ++systems for ISO 8859 are not quite right for the purpose, because ++typically the DOS codepage does not match the standard ISO character ++codes. For example, the letter @samp{@,{c}} (@samp{c} with cedilla) has ++code 231 in the standard Latin-1 character set, but the corresponding ++DOS codepage 850 uses code 135 for this glyph.} ++ ++@cindex mode line @r{(MS-DOS)} ++ All the @code{cp@var{nnn}} coding systems use the letter @samp{D} ++(for ``DOS'') as their mode-line mnemonic. Since both the terminal ++coding system and the default coding system for file I/O are set to ++the proper @code{cp@var{nnn}} coding system at startup, it is normal ++for the mode line on MS-DOS to begin with @samp{-DD\-}. ++@iftex ++@xref{Mode Line,,,emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++@xref{Mode Line}. ++@end ifnottex ++Far-Eastern DOS terminals do not use the @code{cp@var{nnn}} coding ++systems, and thus their initial mode line looks like the Emacs ++default. ++ ++ Since the codepage number also indicates which script you are using, ++Emacs automatically runs @code{set-language-environment} to select the ++language environment for that script ++@iftex ++(@pxref{Language Environments,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Language Environments}). ++@end ifnottex ++ ++ If a buffer contains a character belonging to some other ISO 8859 ++character set, not the one that the chosen DOS codepage supports, Emacs ++displays it using a sequence of @acronym{ASCII} characters. For example, if the ++current codepage doesn't have a glyph for the letter @samp{@`o} (small ++@samp{o} with a grave accent), it is displayed as @samp{@{`o@}}, where ++the braces serve as a visual indication that this is a single character. ++(This may look awkward for some non-Latin characters, such as those from ++Greek or Hebrew alphabets, but it is still readable by a person who ++knows the language.) Even though the character may occupy several ++columns on the screen, it is really still just a single character, and ++all Emacs commands treat it as one. ++ ++@cindex MS-Windows codepages ++ MS-Windows provides its own codepages, which are different from the ++DOS codepages for the same locale. For example, DOS codepage 850 ++supports the same character set as Windows codepage 1252; DOS codepage ++855 supports the same character set as Windows codepage 1251, etc. ++The MS-Windows version of Emacs uses the current codepage for display ++when invoked with the @samp{-nw} option. ++ ++@node MS-DOS Processes ++@subsection Subprocesses on MS-DOS ++ ++@cindex compilation under MS-DOS ++@cindex inferior processes under MS-DOS ++@findex compile @r{(MS-DOS)} ++@findex grep @r{(MS-DOS)} ++ Because MS-DOS is a single-process ``operating system,'' ++asynchronous subprocesses are not available. In particular, Shell ++mode and its variants do not work. Most Emacs features that use ++asynchronous subprocesses also don't work on MS-DOS, including ++Shell mode and GUD. When in doubt, try and see; commands that ++don't work output an error message saying that asynchronous processes ++aren't supported. ++ ++ Compilation under Emacs with @kbd{M-x compile}, searching files with ++@kbd{M-x grep} and displaying differences between files with @kbd{M-x ++diff} do work, by running the inferior processes synchronously. This ++means you cannot do any more editing until the inferior process ++finishes. ++ ++ Spell checking also works, by means of special support for synchronous ++invocation of the @code{ispell} program. This is slower than the ++asynchronous invocation on other platforms ++ ++ Instead of the Shell mode, which doesn't work on MS-DOS, you can use ++the @kbd{M-x eshell} command. This invokes the Eshell package that ++implements a Posix-like shell entirely in Emacs Lisp. ++ ++ By contrast, Emacs compiled as a native Windows application ++@strong{does} support asynchronous subprocesses. ++@iftex ++@xref{Windows Processes,,,emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++@xref{Windows Processes}. ++@end ifnottex ++ ++@cindex printing under MS-DOS ++ Printing commands, such as @code{lpr-buffer} ++@iftex ++(@pxref{Printing,,,emacs, the Emacs Manual}) and ++@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}), ++work in MS-DOS by sending the output to one of the printer ports. ++@xref{MS-DOS Printing,,,emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}), ++work in MS-DOS by sending the output to one of the printer ports. ++@xref{MS-DOS Printing}. ++@end ifnottex ++ ++ When you run a subprocess synchronously on MS-DOS, make sure the ++program terminates and does not try to read keyboard input. If the ++program does not terminate on its own, you will be unable to terminate ++it, because MS-DOS provides no general way to terminate a process. ++Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these ++cases. ++ ++ Accessing files on other machines is not supported on MS-DOS. Other ++network-oriented commands such as sending mail, Web browsing, remote ++login, etc., don't work either, unless network access is built into ++MS-DOS with some network redirector. ++ ++@cindex directory listing on MS-DOS ++@vindex dired-listing-switches @r{(MS-DOS)} ++ Dired on MS-DOS uses the @code{ls-lisp} package where other ++platforms use the system @code{ls} command. Therefore, Dired on ++MS-DOS supports only some of the possible options you can mention in ++the @code{dired-listing-switches} variable. The options that work are ++@samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, @samp{-r}, @samp{-S}, ++@samp{-s}, @samp{-t}, and @samp{-u}. ++ ++@ignore ++ arch-tag: 868d50ff-07f8-4a13-a807-dab6f1cdb431 ++@end ignore +diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdog.texi +new file mode 100644 +index 0000000..3634090 +--- /dev/null ++++ b/doc/emacs/msdog.texi +@@ -0,0 +1,921 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Microsoft Windows, Manifesto, Mac OS / GNUstep, Top ++@appendix Emacs and Microsoft Windows/MS-DOS ++@cindex Microsoft Windows ++@cindex MS-Windows, Emacs peculiarities ++ ++ This section describes peculiarities of using Emacs on Microsoft ++Windows. Some of these peculiarities are also relevant to Microsoft's ++older MS-DOS ``operating system'' (also known as ``MS-DOG''). ++However, Emacs features that are relevant @emph{only} to MS-DOS are ++described in a separate ++@iftex ++manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}). ++@end iftex ++@ifnottex ++section (@pxref{MS-DOS}). ++@end ifnottex ++ ++ ++ The behavior of Emacs on MS-Windows is reasonably similar to what is ++documented in the rest of the manual, including support for long file ++names, multiple frames, scroll bars, mouse menus, and subprocesses. ++However, a few special considerations apply, and they are described ++here. ++ ++@menu ++* Text and Binary:: Text files use CRLF to terminate lines. ++* Windows Files:: File-name conventions on Windows. ++* ls in Lisp:: Emulation of @code{ls} for Dired. ++* Windows HOME:: Where Emacs looks for your @file{.emacs}. ++* Windows Keyboard:: Windows-specific keyboard features. ++* Windows Mouse:: Windows-specific mouse features. ++* Windows Processes:: Running subprocesses on Windows. ++* Windows Printing:: How to specify the printer on MS-Windows. ++* Windows Fonts:: Specifying fonts on MS-Windows. ++* Windows Misc:: Miscellaneous Windows features. ++@ifnottex ++* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). ++@end ifnottex ++@end menu ++ ++@node Text and Binary ++@section Text Files and Binary Files ++@cindex text and binary files on MS-DOS/MS-Windows ++ ++ GNU Emacs uses newline characters to separate text lines. This is the ++convention used on GNU, Unix, and other Posix-compliant systems. ++ ++@cindex end-of-line conversion on MS-DOS/MS-Windows ++ By contrast, MS-DOS and MS-Windows normally use carriage-return linefeed, ++a two-character sequence, to separate text lines. (Linefeed is the same ++character as newline.) Therefore, convenient editing of typical files ++with Emacs requires conversion of these end-of-line (EOL) sequences. ++And that is what Emacs normally does: it converts carriage-return ++linefeed into newline when reading files, and converts newline into ++carriage-return linefeed when writing files. The same mechanism that ++handles conversion of international character codes does this conversion ++also (@pxref{Coding Systems}). ++ ++@cindex cursor location, on MS-DOS ++@cindex point location, on MS-DOS ++ One consequence of this special format-conversion of most files is ++that character positions as reported by Emacs (@pxref{Position Info}) do ++not agree with the file size information known to the operating system. ++ ++ In addition, if Emacs recognizes from a file's contents that it uses ++newline rather than carriage-return linefeed as its line separator, it ++does not perform EOL conversion when reading or writing that file. ++Thus, you can read and edit files from GNU and Unix systems on MS-DOS ++with no special effort, and they will retain their Unix-style ++end-of-line convention after you edit them. ++ ++ The mode line indicates whether end-of-line translation was used for ++the current buffer. If MS-DOS end-of-line translation is in use for the ++buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after ++the coding system mnemonic near the beginning of the mode line ++(@pxref{Mode Line}). If no EOL translation was performed, the string ++@samp{(Unix)} is displayed instead of the backslash, to alert you that the ++file's EOL format is not the usual carriage-return linefeed. ++ ++@cindex DOS-to-Unix conversion of files ++ To visit a file and specify whether it uses DOS-style or Unix-style ++end-of-line, specify a coding system (@pxref{Text Coding}). For ++example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt} ++visits the file @file{foobar.txt} without converting the EOLs; if some ++line ends with a carriage-return linefeed pair, Emacs will display ++@samp{^M} at the end of that line. Similarly, you can direct Emacs to ++save a buffer in a specified EOL format with the @kbd{C-x @key{RET} f} ++command. For example, to save a buffer with Unix EOL format, type ++@kbd{C-x @key{RET} f unix @key{RET} C-x C-s}. If you visit a file ++with DOS EOL conversion, then save it with Unix EOL format, that ++effectively converts the file to Unix EOL style, like @code{dos2unix}. ++ ++@cindex untranslated file system ++@findex add-untranslated-filesystem ++ When you use NFS, Samba, or some other similar method to access file ++systems that reside on computers using GNU or Unix systems, Emacs ++should not perform end-of-line translation on any files in these file ++systems---not even when you create a new file. To request this, ++designate these file systems as @dfn{untranslated} file systems by ++calling the function @code{add-untranslated-filesystem}. It takes one ++argument: the file system name, including a drive letter and ++optionally a directory. For example, ++ ++@example ++(add-untranslated-filesystem "Z:") ++@end example ++ ++@noindent ++designates drive Z as an untranslated file system, and ++ ++@example ++(add-untranslated-filesystem "Z:\\foo") ++@end example ++ ++@noindent ++designates directory @file{\foo} on drive Z as an untranslated file ++system. ++ ++ Most often you would use @code{add-untranslated-filesystem} in your ++@file{.emacs} file, or in @file{site-start.el} so that all the users at ++your site get the benefit of it. ++ ++@findex remove-untranslated-filesystem ++ To countermand the effect of @code{add-untranslated-filesystem}, use ++the function @code{remove-untranslated-filesystem}. This function takes ++one argument, which should be a string just like the one that was used ++previously with @code{add-untranslated-filesystem}. ++ ++ Designating a file system as untranslated does not affect character ++set conversion, only end-of-line conversion. Essentially, it directs ++Emacs to create new files with the Unix-style convention of using ++newline at the end of a line. @xref{Coding Systems}. ++ ++@vindex file-name-buffer-file-type-alist ++@cindex binary files, on MS-DOS/MS-Windows ++ Some kinds of files should not be converted at all, because their ++contents are not really text. Therefore, Emacs on MS-Windows distinguishes ++certain files as @dfn{binary files}. (This distinction is not part of ++MS-Windows; it is made by Emacs only.) Binary files include executable ++programs, compressed archives, etc. Emacs uses the file name to decide ++whether to treat a file as binary: the variable ++@code{file-name-buffer-file-type-alist} defines the file-name patterns ++that indicate binary files. If a file name matches one of the patterns ++for binary files (those whose associations are of the type ++@code{(@var{pattern} . t)}, Emacs reads and writes that file using the ++@code{no-conversion} coding system (@pxref{Coding Systems}) which turns ++off @emph{all} coding-system conversions, not only the EOL conversion. ++@code{file-name-buffer-file-type-alist} also includes file-name patterns ++for files which are known to be Windows-style text files with ++carriage-return linefeed EOL format, such as @file{CONFIG.SYS}; Emacs ++always writes those files with Windows-style EOLs. ++ ++ If a file which belongs to an untranslated file system matches one of ++the file-name patterns in @code{file-name-buffer-file-type-alist}, the ++EOL conversion is determined by @code{file-name-buffer-file-type-alist}. ++ ++@node Windows Files ++@section File Names on MS-Windows ++@cindex file names on MS-Windows ++ ++ MS-Windows and MS-DOS normally use a backslash, @samp{\}, to ++separate name units within a file name, instead of the slash used on ++other systems. Emacs on MS-DOS/MS-Windows permits use of either slash or ++backslash, and also knows about drive letters in file names. ++ ++@cindex file-name completion, on MS-Windows ++ On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by ++default ignores letter-case in file names during completion. ++ ++@vindex w32-get-true-file-attributes ++ The variable @code{w32-get-true-file-attributes} controls whether ++Emacs should issue additional system calls to determine more ++accurately file attributes in primitives like @code{file-attributes} ++and @code{directory-files-and-attributes}. These additional calls are ++needed to report correct file ownership, link counts and file types ++for special files such as pipes. Without these system calls, file ++ownership will be attributed to the current user, link counts will be ++always reported as 1, and special files will be reported as regular ++files. ++ ++ If the value of this variable is @code{local} (the default), Emacs ++will issue these additional system calls only for files on local fixed ++drives. Any other non-@code{nil} value means do this even for ++removable and remote volumes, where this could potentially slow down ++Dired and other related features. The value of @code{nil} means never ++issue those system calls. Non-@code{nil} values are more useful on ++NTFS volumes, which support hard links and file security, than on FAT, ++FAT32, and XFAT volumes. ++ ++@node ls in Lisp ++@section Emulation of @code{ls} on MS-Windows ++@cindex Dired, and MS-Windows/MS-DOS ++@cindex @code{ls} emulation ++ ++ Dired normally uses the external program @code{ls} (or its close ++work-alike) to produce the directory listing displayed in Dired ++buffers (@pxref{Dired}). However, MS-Windows and MS-DOS systems don't ++come with such a program, although several ports of @sc{gnu} @code{ls} ++are available. Therefore, Emacs on those systems @emph{emulates} ++@code{ls} in Lisp, by using the @file{ls-lisp.el} package. While ++@file{ls-lisp.el} provides a reasonably full emulation of @code{ls}, ++there are some options and features peculiar to that emulation; ++@iftex ++for more details, see the documentation of the variables whose names ++begin with @code{ls-lisp}. ++@end iftex ++@ifnottex ++they are described in this section. ++ ++ The @code{ls} emulation supports many of the @code{ls} switches, but ++it doesn't support all of them. Here's the list of the switches it ++does support: @option{-A}, @option{-a}, @option{-B}, @option{-C}, ++@option{-c}, @option{-i}, @option{-G}, @option{-g}, @option{-R}, ++@option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U}, ++@option{-u}, and @option{-X}. The @option{-F} switch is partially ++supported (it appends the character that classifies the file, but does ++not prevent symlink following). ++ ++@vindex ls-lisp-use-insert-directory-program ++ On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs ++is built, so the Lisp emulation of @code{ls} is always used on those ++platforms. If you have a ported @code{ls}, setting ++@code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value ++will revert to using an external program named by the variable ++@code{insert-directory-program}. ++ ++@vindex ls-lisp-ignore-case ++ By default, @file{ls-lisp.el} uses a case-sensitive sort order for ++the directory listing it produces; this is so the listing looks the ++same as on other platforms. If you wish that the files be sorted in ++case-insensitive order, set the variable @code{ls-lisp-ignore-case} to ++a non-@code{nil} value. ++ ++@vindex ls-lisp-dirs-first ++ By default, files and subdirectories are sorted together, to emulate ++the behavior of @code{ls}. However, native MS-Windows/MS-DOS file ++managers list the directories before the files; if you want that ++behavior, customize the option @code{ls-lisp-dirs-first} to a ++non-@code{nil} value. ++ ++@vindex ls-lisp-verbosity ++ The variable @code{ls-lisp-verbosity} controls the file attributes ++that @file{ls-lisp.el} displays. The value should be a list that ++contains one or more of the symbols @code{links}, @code{uid}, and ++@code{gid}. @code{links} means display the count of different file ++names that are associated with (a.k.a.@: @dfn{links to}) the file's ++data; this is only useful on NTFS volumes. @code{uid} means display ++the numerical identifier of the user who owns the file. @code{gid} ++means display the numerical identifier of the file owner's group. The ++default value is @code{(links uid gid)} i.e.@: all the 3 optional ++attributes are displayed. ++ ++@vindex ls-lisp-emulation ++ The variable @code{ls-lisp-emulation} controls the flavour of the ++@code{ls} emulation by setting the defaults for the 3 options ++described above: @code{ls-lisp-ignore-case}, ++@code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}. The value of ++this option can be one of the following symbols: ++ ++@table @code ++@item GNU ++@itemx nil ++Emulate @sc{gnu} systems; this is the default. This sets ++@code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to ++@code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}. ++@item UNIX ++Emulate Unix systems. Like @code{GNU}, but sets ++@code{ls-lisp-verbosity} to @code{(links uid)}. ++@item MacOS ++Emulate MacOS. Sets @code{ls-lisp-ignore-case} to @code{t}, and ++@code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}. ++@item MS-Windows ++Emulate MS-Windows. Sets @code{ls-lisp-ignore-case} and ++@code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to ++@code{(links)} on Windows NT/2K/XP/2K3 and to @code{nil} on Windows 9X. ++Note that the default emulation is @emph{not} @code{MS-Windows}, even ++on Windows, since many users of Emacs on those platforms prefer the ++@sc{gnu} defaults. ++@end table ++ ++@noindent ++Any other value of @code{ls-lisp-emulation} means the same as ++@code{GNU}. Note that this option needs to be set @emph{before} ++@file{ls-lisp.el} is loaded, which means that on MS-Windows and MS-DOS ++you will have to set the value from your @file{.emacs} file and then ++restart Emacs, since @file{ls-lisp.el} is preloaded. ++ ++@vindex ls-lisp-support-shell-wildcards ++ The variable @code{ls-lisp-support-shell-wildcards} controls how ++file-name patterns are supported: if it is non-@code{nil} (the ++default), they are treated as shell-style wildcards; otherwise they ++are treated as Emacs regular expressions. ++ ++@vindex ls-lisp-format-time-list ++ The variable @code{ls-lisp-format-time-list} defines how to format ++the date and time of files. @emph{The value of this variable is ++ignored}, unless Emacs cannot determine the current locale. (However, ++if the value of @code{ls-lisp-use-localized-time-format} is ++non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if ++the current locale is available; see below.) ++ ++The value of @code{ls-lisp-format-time-list} is a list of 2 strings. ++The first string is used if the file was modified within the current ++year, while the second string is used for older files. In each of ++these two strings you can use @samp{%}-sequences to substitute parts ++of the time. For example: ++@lisp ++("%b %e %H:%M" "%b %e %Y") ++@end lisp ++ ++@noindent ++Note that the strings substituted for these @samp{%}-sequences depend ++on the current locale. @xref{Time Parsing,,, elisp, The Emacs Lisp ++Reference Manual}, for more about format time specs. ++ ++@vindex ls-lisp-use-localized-time-format ++ Normally, Emacs formats the file time stamps in either traditional ++or ISO-style time format. However, if the value of the variable ++@code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs ++formats file time stamps according to what ++@code{ls-lisp-format-time-list} specifies. The @samp{%}-sequences in ++@code{ls-lisp-format-time-list} produce locale-dependent month and day ++names, which might cause misalignment of columns in Dired display. ++@end ifnottex ++ ++@node Windows HOME ++@section HOME Directory on MS-Windows ++@cindex @code{HOME} directory on MS-Windows ++ ++ The Windows equivalent of the @code{HOME} directory is the ++@dfn{user-specific application data directory}. The actual location ++depends on your Windows version and system configuration; typical values ++are @file{C:\Documents and Settings\@var{username}\Application Data} on ++Windows 2K/XP and later, and either @file{C:\WINDOWS\Application Data} ++or @file{C:\WINDOWS\Profiles\@var{username}\Application Data} on the ++older Windows 9X/ME systems. ++ ++@cindex init file @file{.emacs} on MS-Windows ++ The home directory is where your init file @file{.emacs} is stored. ++When Emacs starts, it first checks whether the environment variable ++@env{HOME} is set. If it is, it looks for the init file in the ++directory pointed by @env{HOME}. If @env{HOME} is not defined, Emacs ++checks for an existing @file{.emacs} file in @file{C:\}, the root ++directory of drive @file{C:}@footnote{ ++The check in @file{C:\} is for compatibility with older versions of Emacs, ++which didn't check the application data directory. ++}. If there's no such file in @file{C:\}, Emacs next uses the Windows ++system calls to find out the exact location of your application data ++directory. If that system call fails, Emacs falls back to @file{C:\}. ++ ++ Whatever the final place is, Emacs sets the value of the @env{HOME} ++environment variable to point to it, and it will use that location for ++other files and directories it normally creates in the user's home ++directory. ++ ++ You can always find out where Emacs thinks is your home directory's ++location by typing @kbd{C-x d ~/ @key{RET}}. This should present the ++list of files in the home directory, and show its full name on the ++first line. Likewise, to visit your init file, type @kbd{C-x C-f ++~/.emacs @key{RET}}. ++ ++@cindex @file{_emacs} init file, MS-Windows ++ Because MS-DOS does not allow file names with leading dots, and ++because older Windows systems made it hard to create files with such ++names, the Windows port of Emacs supports an alternative name ++@file{_emacs} as a fallback, if such a file exists in the home ++directory, whereas @file{.emacs} does not. ++ ++@node Windows Keyboard ++@section Keyboard Usage on MS-Windows ++@cindex keyboard, MS-Windows ++ ++ This section describes the Windows-specific features related to ++keyboard input in Emacs. ++ ++@cindex MS-Windows keyboard shortcuts ++ Many key combinations (known as ``keyboard shortcuts'') that have ++conventional uses in MS-Windows programs conflict with traditional ++Emacs key bindings. (These Emacs key bindings were established years ++before Microsoft was founded.) Examples of conflicts include ++@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}. ++You can redefine some of them with meanings more like the MS-Windows ++meanings by enabling CUA Mode (@pxref{CUA Bindings}). ++ ++@kindex F10 @r{(MS-Windows)} ++@cindex menu bar access using keyboard @r{(MS-Windows)} ++ The @key{F10} key on Windows activates the menu bar in a way that ++makes it possible to use the menus without a mouse. In this mode, the ++arrow keys traverse the menus, @key{RET} selects a highlighted menu ++item, and @key{ESC} closes the menu. ++ ++@iftex ++@inforef{Windows Keyboard, , emacs}, for information about additional ++Windows-specific variables in this category. ++@end iftex ++@ifnottex ++@vindex w32-alt-is-meta ++@cindex @code{Alt} key (MS-Windows) ++ By default, the key labeled @key{Alt} is mapped as the @key{META} ++key. If you wish it to produce the @code{Alt} modifier instead, set ++the variable @code{w32-alt-is-meta} to a @code{nil} value. ++ ++@findex w32-register-hot-key ++@findex w32-unregister-hot-key ++ MS-Windows reserves certain key combinations, such as ++@kbd{Alt-@key{TAB}}, for its own use. These key combinations are ++intercepted by the system before Emacs can see them. You can use the ++@code{w32-register-hot-key} function to allow a key sequence to be ++seen by Emacs instead of being grabbed by Windows. This functions ++registers a key sequence as a @dfn{hot key}, overriding the special ++meaning of that key sequence for Windows. (MS-Windows is told that ++the key sequence is a hot key only when one of the Emacs windows has ++focus, so that the special keys still have their usual meaning for ++other Windows applications.) ++ ++ The argument to @code{w32-register-hot-key} must be a single key, ++with or without modifiers, in vector form that would be acceptable to ++@code{define-key}. The meta modifier is interpreted as the @key{ALT} ++key if @code{w32-alt-is-meta} is @code{t} (the default), and the hyper ++modifier is always interpreted as the Windows key (usually labeled ++with @key{start} and the Windows logo). If the function succeeds in ++registering the key sequence, it returns the hotkey ID, a number; ++otherwise it returns @code{nil}. ++ ++@kindex M-TAB@r{, (MS-Windows)} ++@cindex @kbd{M-@key{TAB}} vs @kbd{Alt-@key{TAB}} (MS-Windows) ++@cindex @kbd{Alt-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows) ++ For example, @code{(w32-register-hot-key [M-tab])} lets you use ++@kbd{M-TAB} normally in Emacs, for instance, to complete the word or ++symbol at point at top level, or to complete the current search string ++against previously sought strings during incremental search. ++ ++ The function @code{w32-unregister-hot-key} reverses the effect of ++@code{w32-register-hot-key} for its argument key sequence. ++ ++@vindex w32-capslock-is-shiftlock ++ By default, the @key{CapsLock} key only affects normal character ++keys (it converts lower-case characters to their upper-case ++variants). However, if you set the variable ++@code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the ++@key{CapsLock} key will affect non-character keys as well, as if you ++pressed the @key{Shift} key while typing the non-character key. ++ ++@vindex w32-enable-caps-lock ++ If the variable @code{w32-enable-caps-lock} is set to a @code{nil} ++value, the @key{CapsLock} key produces the symbol @code{capslock} ++instead of the shifted version of they keys. The default value is ++@code{t}. ++ ++@vindex w32-enable-num-lock ++@cindex keypad keys (MS-Windows) ++ Similarly, if @code{w32-enable-num-lock} is @code{nil}, the ++@key{NumLock} key will produce the symbol @code{kp-numlock}. The ++default is @code{t}, which causes @key{NumLock} to work as expected: ++toggle the meaning of the keys on the numeric keypad. ++@end ifnottex ++ ++@vindex w32-apps-modifier ++ The variable @code{w32-apps-modifier} controls the effect of the ++@key{Apps} key (usually located between the right @key{Alt} and the ++right @key{Ctrl} keys). Its value can be one of the symbols ++@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, ++or @code{shift} for the respective modifier, or @code{nil} to appear ++as the key @code{apps}. The default is @code{nil}. ++ ++@vindex w32-lwindow-modifier ++@vindex w32-rwindow-modifier ++@vindex w32-scroll-lock-modifier ++ The variable @code{w32-lwindow-modifier} determines the effect of ++the left Windows key (usually labeled with @key{start} and the Windows ++logo). If its value is @code{nil} (the default), the key will produce ++the symbol @code{lwindow}. Setting it to one of the symbols ++@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, ++or @code{shift} will produce the respective modifier. A similar ++variable @code{w32-rwindow-modifier} controls the effect of the right ++Windows key, and @code{w32-scroll-lock-modifier} does the same for the ++@key{ScrLock} key. If these variables are set to @code{nil}, the ++right Windows key produces the symbol @code{rwindow} and @key{ScrLock} ++produces the symbol @code{scroll}. ++ ++@vindex w32-pass-alt-to-system ++@cindex Windows system menu ++@cindex @code{Alt} key invokes menu (Windows) ++ Emacs compiled as a native Windows application normally turns off ++the Windows feature that tapping the @key{ALT} key invokes the Windows ++menu. The reason is that the @key{ALT} serves as @key{META} in Emacs. ++When using Emacs, users often press the @key{META} key temporarily and ++then change their minds; if this has the effect of bringing up the ++Windows menu, it alters the meaning of subsequent commands. Many ++users find this frustrating. ++ ++ You can re-enable Windows' default handling of tapping the @key{ALT} ++key by setting @code{w32-pass-alt-to-system} to a non-@code{nil} ++value. ++ ++@ifnottex ++@vindex w32-pass-lwindow-to-system ++@vindex w32-pass-rwindow-to-system ++ The variables @code{w32-pass-lwindow-to-system} and ++@code{w32-pass-rwindow-to-system} determine whether the respective ++keys are passed to Windows or swallowed by Emacs. If the value is ++@code{nil}, the respective key is silently swallowed by Emacs, ++otherwise it is passed to Windows. The default is @code{t} for both ++of these variables. Passing each of these keys to Windows produces ++its normal effect: for example, @kbd{@key{Lwindow}} opens the ++@code{Start} menu, etc.@footnote{ ++Some combinations of the ``Windows'' keys with other keys are caught ++by Windows at low level in a way that Emacs currently cannot prevent. ++For example, @kbd{@key{Lwindow} r} always pops up the Windows ++@samp{Run} dialog. Customizing the value of ++@code{w32-phantom-key-code} might help in some cases, though.} ++ ++@vindex w32-recognize-altgr ++@kindex AltGr @r{(MS-Windows)} ++@cindex AltGr key (MS-Windows) ++ The variable @code{w32-recognize-altgr} controls whether the ++@key{AltGr} key (if it exists on your keyboard), or its equivalent, ++the combination of the right @key{Alt} and left @key{Ctrl} keys ++pressed together, is recognized as the @key{AltGr} key. The default ++is @code{t}, which means these keys produce @code{AltGr}; setting it ++to @code{nil} causes @key{AltGr} or the equivalent key combination to ++be interpreted as the combination of @key{CTRL} and @key{META} ++modifiers. ++@end ifnottex ++ ++@node Windows Mouse ++@section Mouse Usage on MS-Windows ++@cindex mouse, and MS-Windows ++ ++ This section describes the Windows-specific variables related to ++mouse. ++ ++@vindex w32-mouse-button-tolerance ++@cindex simulation of middle mouse button ++ The variable @code{w32-mouse-button-tolerance} specifies the ++time interval, in milliseconds, for faking middle mouse button press ++on 2-button mice. If both mouse buttons are depressed within this ++time interval, Emacs generates a middle mouse button click event ++instead of a double click on one of the buttons. ++ ++@vindex w32-pass-extra-mouse-buttons-to-system ++ If the variable @code{w32-pass-extra-mouse-buttons-to-system} is ++non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to ++Windows. ++ ++@vindex w32-swap-mouse-buttons ++ The variable @code{w32-swap-mouse-buttons} controls which of the 3 ++mouse buttons generates the @kbd{mouse-2} events. When it is ++@code{nil} (the default), the middle button generates @kbd{mouse-2} ++and the right button generates @kbd{mouse-3} events. If this variable ++is non-@code{nil}, the roles of these two buttons are reversed. ++ ++@node Windows Processes ++@section Subprocesses on Windows 9X/ME and Windows NT/2K/XP ++@cindex subprocesses on MS-Windows ++ ++@cindex DOS applications, running from Emacs ++ Emacs compiled as a native Windows application (as opposed to the DOS ++version) includes full support for asynchronous subprocesses. ++In the Windows version, synchronous and asynchronous subprocesses work ++fine on both ++Windows 9X/ME and Windows NT/2K/XP as long as you run only 32-bit Windows ++applications. However, when you run a DOS application in a subprocess, ++you may encounter problems or be unable to run the application at all; ++and if you run two DOS applications at the same time in two ++subprocesses, you may have to reboot your system. ++ ++Since the standard command interpreter (and most command line utilities) ++on Windows 9X are DOS applications, these problems are significant when ++using that system. But there's nothing we can do about them; only ++Microsoft can fix them. ++ ++If you run just one DOS application subprocess, the subprocess should ++work as expected as long as it is ``well-behaved'' and does not perform ++direct screen access or other unusual actions. If you have a CPU ++monitor application, your machine will appear to be 100% busy even when ++the DOS application is idle, but this is only an artifact of the way CPU ++monitors measure processor load. ++ ++You must terminate the DOS application before you start any other DOS ++application in a different subprocess. Emacs is unable to interrupt or ++terminate a DOS subprocess. The only way you can terminate such a ++subprocess is by giving it a command that tells its program to exit. ++ ++If you attempt to run two DOS applications at the same time in separate ++subprocesses, the second one that is started will be suspended until the ++first one finishes, even if either or both of them are asynchronous. ++ ++@cindex kill DOS application ++If you can go to the first subprocess, and tell it to exit, the second ++subprocess should continue normally. However, if the second subprocess ++is synchronous, Emacs itself will be hung until the first subprocess ++finishes. If it will not finish without user input, then you have no ++choice but to reboot if you are running on Windows 9X. If you are ++running on Windows NT/2K/XP, you can use a process viewer application to kill ++the appropriate instance of NTVDM instead (this will terminate both DOS ++subprocesses). ++ ++If you have to reboot Windows 9X in this situation, do not use the ++@code{Shutdown} command on the @code{Start} menu; that usually hangs the ++system. Instead, type @kbd{CTL-ALT-@key{DEL}} and then choose ++@code{Shutdown}. That usually works, although it may take a few minutes ++to do its job. ++ ++@vindex w32-quote-process-args ++ The variable @code{w32-quote-process-args} controls how Emacs quotes ++the process arguments. Non-@code{nil} means quote with the @code{"} ++character. If the value is a character, use that character to escape ++any quote characters that appear; otherwise chose a suitable escape ++character based on the type of the program. ++ ++@ifnottex ++@findex w32-shell-execute ++ The function @code{w32-shell-execute} can be useful for writing ++customized commands that run MS-Windows applications registered to ++handle a certain standard Windows operation for a specific type of ++document or file. This function is a wrapper around the Windows ++@code{ShellExecute} API. See the MS-Windows API documentation for ++more details. ++@end ifnottex ++ ++@node Windows Printing ++@section Printing and MS-Windows ++ ++ Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and ++@code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and ++MS-Windows by sending the output to one of the printer ports, if a ++Posix-style @code{lpr} program is unavailable. The same Emacs ++variables control printing on all systems, but in some cases they have ++different default values on MS-DOS and MS-Windows. ++ ++ Emacs on Windows automatically determines your default printer and ++sets the variable @code{printer-name} to that printer's name. But in ++some rare cases this can fail, or you may wish to use a different ++printer from within Emacs. The rest of this section explains how to ++tell Emacs which printer to use. ++ ++@vindex printer-name@r{, (MS-DOS/MS-Windows)} ++ If you want to use your local printer, then set the Lisp variable ++@code{lpr-command} to @code{""} (its default value on Windows) and ++@code{printer-name} to the name of the printer port---for example, ++@code{"PRN"}, the usual local printer port or @code{"LPT2"}, or ++@code{"COM1"} for a serial printer. You can also set ++@code{printer-name} to a file name, in which case ``printed'' output ++is actually appended to that file. If you set @code{printer-name} to ++@code{"NUL"}, printed output is silently discarded (sent to the system ++null device). ++ ++ You can also use a printer shared by another machine by setting ++@code{printer-name} to the UNC share name for that printer---for ++example, @code{"//joes_pc/hp4si"}. (It doesn't matter whether you use ++forward slashes or backslashes here.) To find out the names of shared ++printers, run the command @samp{net view} from the command prompt to ++obtain a list of servers, and @samp{net view @var{server-name}} to see ++the names of printers (and directories) shared by that server. ++Alternatively, click the @samp{Network Neighborhood} icon on your ++desktop, and look for machines which share their printers via the ++network. ++ ++@cindex @samp{net use}, and printing on MS-Windows ++@cindex networked printers (MS-Windows) ++ If the printer doesn't appear in the output of @samp{net view}, or ++if setting @code{printer-name} to the UNC share name doesn't produce a ++hardcopy on that printer, you can use the @samp{net use} command to ++connect a local print port such as @code{"LPT2"} to the networked ++printer. For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{ ++Note that the @samp{net use} command requires the UNC share name to be ++typed with the Windows-style backslashes, while the value of ++@code{printer-name} can be set with either forward- or backslashes.} ++causes Windows to @dfn{capture} the @code{LPT2} port and redirect the ++printed material to the printer connected to the machine @code{joes_pc}. ++After this command, setting @code{printer-name} to @code{"LPT2"} ++should produce the hardcopy on the networked printer. ++ ++ With some varieties of Windows network software, you can instruct ++Windows to capture a specific printer port such as @code{"LPT2"}, and ++redirect it to a networked printer via the @w{@code{Control ++Panel->Printers}} applet instead of @samp{net use}. ++ ++ If you set @code{printer-name} to a file name, it's best to use an ++absolute file name. Emacs changes the working directory according to ++the default directory of the current buffer, so if the file name in ++@code{printer-name} is relative, you will end up with several such ++files, each one in the directory of the buffer from which the printing ++was done. ++ ++ If the value of @code{printer-name} is correct, but printing does ++not produce the hardcopy on your printer, it is possible that your ++printer does not support printing plain text (some cheap printers omit ++this functionality). In that case, try the PostScript print commands, ++described below. ++ ++@findex print-buffer @r{(MS-DOS)} ++@findex print-region @r{(MS-DOS)} ++@vindex lpr-headers-switches @r{(MS-DOS)} ++ The commands @code{print-buffer} and @code{print-region} call the ++@code{pr} program, or use special switches to the @code{lpr} program, to ++produce headers on each printed page. MS-DOS and MS-Windows don't ++normally have these programs, so by default, the variable ++@code{lpr-headers-switches} is set so that the requests to print page ++headers are silently ignored. Thus, @code{print-buffer} and ++@code{print-region} produce the same output as @code{lpr-buffer} and ++@code{lpr-region}, respectively. If you do have a suitable @code{pr} ++program (for example, from GNU Coreutils), set ++@code{lpr-headers-switches} to @code{nil}; Emacs will then call ++@code{pr} to produce the page headers, and print the resulting output as ++specified by @code{printer-name}. ++ ++@vindex print-region-function @r{(MS-DOS)} ++@cindex lpr usage under MS-DOS ++@vindex lpr-command @r{(MS-DOS)} ++@vindex lpr-switches @r{(MS-DOS)} ++ Finally, if you do have an @code{lpr} work-alike, you can set the ++variable @code{lpr-command} to @code{"lpr"}. Then Emacs will use ++@code{lpr} for printing, as on other systems. (If the name of the ++program isn't @code{lpr}, set @code{lpr-command} to specify where to ++find it.) The variable @code{lpr-switches} has its standard meaning ++when @code{lpr-command} is not @code{""}. If the variable ++@code{printer-name} has a string value, it is used as the value for the ++@code{-P} option to @code{lpr}, as on Unix. ++ ++@findex ps-print-buffer @r{(MS-DOS)} ++@findex ps-spool-buffer @r{(MS-DOS)} ++@vindex ps-printer-name @r{(MS-DOS)} ++@vindex ps-lpr-command @r{(MS-DOS)} ++@vindex ps-lpr-switches @r{(MS-DOS)} ++ A parallel set of variables, @code{ps-lpr-command}, ++@code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript ++Variables}), defines how PostScript files should be printed. These ++variables are used in the same way as the corresponding variables ++described above for non-PostScript printing. Thus, the value of ++@code{ps-printer-name} is used as the name of the device (or file) to ++which PostScript output is sent, just as @code{printer-name} is used ++for non-PostScript printing. (There are two distinct sets of ++variables in case you have two printers attached to two different ++ports, and only one of them is a PostScript printer.) ++ ++@cindex Ghostscript, use for PostScript printing ++ The default value of the variable @code{ps-lpr-command} is @code{""}, ++which causes PostScript output to be sent to the printer port specified ++by @code{ps-printer-name}, but @code{ps-lpr-command} can also be set to ++the name of a program which will accept PostScript files. Thus, if you ++have a non-PostScript printer, you can set this variable to the name of ++a PostScript interpreter program (such as Ghostscript). Any switches ++that need to be passed to the interpreter program are specified using ++@code{ps-lpr-switches}. (If the value of @code{ps-printer-name} is a ++string, it will be added to the list of switches as the value for the ++@code{-P} option. This is probably only useful if you are using ++@code{lpr}, so when using an interpreter typically you would set ++@code{ps-printer-name} to something other than a string so it is ++ignored.) ++ ++ For example, to use Ghostscript for printing on the system's default ++printer, put this in your @file{.emacs} file: ++ ++@example ++(setq ps-printer-name t) ++(setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe") ++(setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH" ++ "-sDEVICE=mswinpr2" ++ "-sPAPERSIZE=a4")) ++@end example ++ ++@noindent ++(This assumes that Ghostscript is installed in the ++@file{D:/gs6.01} directory.) ++ ++@node Windows Fonts ++@section Specifying Fonts on MS-Windows ++@cindex font specification (MS Windows) ++ ++ Starting with Emacs 23, fonts are specified by their name, size ++and optional properties. The format for specifying fonts comes from the ++fontconfig library used in modern Free desktops: ++ ++@example ++ [Family[-PointSize]][:Option1=Value1[:Option2=Value2[...]]] ++@end example ++ ++ The old XLFD based format is also supported for backwards compatibility. ++ ++ Emacs 23 supports a number of backends. Currently, the @code{gdi} ++and @code{uniscribe} font backends are supported on Windows. The ++@code{gdi} font backend is available on all versions of Windows, and ++supports all fonts that are natively supported by Windows. The ++@code{uniscribe} font backend is available on Windows 2000 and later, ++and supports Truetype and Opentype fonts. Some languages requiring ++complex layout can only be properly supported by the uniscribe ++backend. By default, both backends are enabled if supported, with ++@code{uniscribe} taking priority over @code{gdi}. ++ ++@cindex font properties (MS Windows) ++@noindent ++Optional properties common to all font backends on MS-Windows are: ++ ++@table @code ++ ++@vindex font-weight-table @r{(MS-Windows)} ++@item weight ++Specifies the weight of the font. Special values @code{light}, ++@code{medium}, @code{demibold}, @code{bold}, and @code{black} can be specified ++without @code{weight=} (e.g., @kbd{Courier New-12:bold}). Otherwise, ++the weight should be a numeric value between 100 and 900, or one of the ++named weights in @code{font-weight-table}. If unspecified, a regular font ++is assumed. ++ ++@vindex font-slant-table @r{(MS-Windows)} ++@item slant ++Specifies whether the font is italic. Special values ++@code{roman}, @code{italic} and @code{oblique} can be specified ++without @code{slant=} (e.g., @kbd{Courier New-12:italic}). ++Otherwise, the slant should be a numeric value, or one of the named ++slants in @code{font-slant-table}. On Windows, any slant above 150 is ++treated as italics, and anything below as roman. ++ ++@item family ++Specifies the font family, but normally this will be specified ++at the start of the font name. ++ ++@item pixelsize ++Specifies the font size in pixels. This can be used instead ++of the point size specified after the family name. ++ ++@item adstyle ++Specifies additional style information for the font. ++On MS-Windows, the values @code{mono}, @code{sans}, @code{serif}, ++@code{script} and @code{decorative} are recognized. These are most useful ++as a fallback with the font family left unspecified. ++ ++@vindex w32-charset-info-alist ++@item registry ++Specifies the character set registry that the font is ++expected to cover. Most Truetype and Opentype fonts will be unicode fonts ++that cover several national character sets, but you can narrow down the ++selection of fonts to those that support a particular character set by ++using a specific registry from @code{w32-charset-info-alist} here. ++ ++@item spacing ++Specifies how the font is spaced. The @code{p} spacing specifies ++a proportional font, and @code{m} or @code{c} specify a monospaced font. ++ ++@item foundry ++Not used on Windows, but for informational purposes and to ++prevent problems with code that expects it to be set, is set internally to ++@code{raster} for bitmapped fonts, @code{outline} for scalable fonts, ++or @code{unknown} if the type cannot be determined as one of those. ++@end table ++ ++@cindex font properties (MS Windows gdi backend) ++Options specific to @code{GDI} fonts: ++ ++@table @code ++ ++@cindex font scripts (MS Windows) ++@cindex font unicode subranges (MS Windows) ++@item script ++Specifies a unicode subrange the font should support. ++ ++The following scripts are recognized on Windows: @code{latin}, @code{greek}, ++@code{coptic}, @code{cyrillic}, @code{armenian}, @code{hebrew}, @code{arabic}, ++@code{syriac}, @code{nko}, @code{thaana}, @code{devanagari}, @code{bengali}, ++@code{gurmukhi}, @code{gujarati}, @code{oriya}, @code{tamil}, @code{telugu}, ++@code{kannada}, @code{malayam}, @code{sinhala}, @code{thai}, @code{lao}, ++@code{tibetan}, @code{myanmar}, @code{georgian}, @code{hangul}, ++@code{ethiopic}, @code{cherokee}, @code{canadian-aboriginal}, @code{ogham}, ++@code{runic}, @code{khmer}, @code{mongolian}, @code{symbol}, @code{braille}, ++@code{han}, @code{ideographic-description}, @code{cjk-misc}, @code{kana}, ++@code{bopomofo}, @code{kanbun}, @code{yi}, @code{byzantine-musical-symbol}, ++@code{musical-symbol}, and @code{mathematical}. ++ ++@cindex font antialiasing (MS Windows) ++@item antialias ++Specifies the antialiasing to use for the font. The value @code{none} ++means no antialiasing, @code{standard} means use standard antialiasing, ++@code{subpixel} means use subpixel antialiasing (known as Cleartype on Windows), ++and @code{natural} means use subpixel antialiasing with adjusted spacing between ++letters. If unspecified, the font will use the system default antialiasing. ++@end table ++ ++@node Windows Misc ++@section Miscellaneous Windows-specific features ++ ++ This section describes miscellaneous Windows-specific features. ++ ++@vindex w32-use-visible-system-caret ++@cindex screen reader software, MS-Windows ++ The variable @code{w32-use-visible-system-caret} is a flag that ++determines whether to make the system caret visible. The default when ++no screen reader software is in use is @code{nil}, which means Emacs ++draws its own cursor to indicate the position of point. A ++non-@code{nil} value means Emacs will indicate point location by the ++system caret; this facilitates use of screen reader software, and is ++the default when such software is detected when running Emacs. ++When this variable is non-@code{nil}, other variables affecting the ++cursor display have no effect. ++ ++@iftex ++@inforef{Windows Misc, , emacs}, for information about additional ++Windows-specific variables in this category. ++@end iftex ++ ++@ifnottex ++@vindex w32-grab-focus-on-raise ++@cindex frame focus policy, MS-Windows ++ The variable @code{w32-grab-focus-on-raise}, if set to a ++non-@code{nil} value causes a frame to grab focus when it is raised. ++The default is @code{t}, which fits well with the Windows default ++click-to-focus policy. ++@end ifnottex ++ ++@ifnottex ++@include msdog-xtra.texi ++@end ifnottex ++ ++@ignore ++ arch-tag: f39d2590-5dcc-4318-88d9-0eb73ca10fa2 ++@end ignore +diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi +new file mode 100644 +index 0000000..98713c7 +--- /dev/null ++++ b/doc/emacs/mule.texi +@@ -0,0 +1,1672 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1997, 1999, 2000, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node International, Major Modes, Frames, Top ++@chapter International Character Set Support ++@c This node is referenced in the tutorial. When renaming or deleting ++@c it, the tutorial needs to be adjusted. (TUTORIAL.de) ++@cindex MULE ++@cindex international scripts ++@cindex multibyte characters ++@cindex encoding of characters ++ ++@cindex Celtic ++@cindex Chinese ++@cindex Cyrillic ++@cindex Czech ++@cindex Devanagari ++@cindex Hindi ++@cindex Marathi ++@cindex Ethiopic ++@cindex German ++@cindex Greek ++@cindex Hebrew ++@cindex IPA ++@cindex Japanese ++@cindex Korean ++@cindex Lao ++@cindex Latin ++@cindex Polish ++@cindex Romanian ++@cindex Slovak ++@cindex Slovenian ++@cindex Thai ++@cindex Tibetan ++@cindex Turkish ++@cindex Vietnamese ++@cindex Dutch ++@cindex Spanish ++ Emacs supports a wide variety of international character sets, ++including European and Vietnamese variants of the Latin alphabet, as ++well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek, ++Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA, ++Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts. ++Emacs also supports various encodings of these characters used by ++other internationalized software, such as word processors and mailers. ++ ++ Emacs allows editing text with international characters by supporting ++all the related activities: ++ ++@itemize @bullet ++@item ++You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and ++pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as ++compilers, spell-checkers, and mailers). Setting your language ++environment (@pxref{Language Environments}) takes care of setting up the ++coding systems and other options for a specific language or culture. ++Alternatively, you can specify how Emacs should encode or decode text ++for each command; see @ref{Text Coding}. ++ ++@item ++You can display non-@acronym{ASCII} characters encoded by the various ++scripts. This works by using appropriate fonts on graphics displays ++(@pxref{Defining Fontsets}), and by sending special codes to text-only ++displays (@pxref{Terminal Coding}). If some characters are displayed ++incorrectly, refer to @ref{Undisplayable Characters}, which describes ++possible problems and explains how to solve them. ++ ++@item ++You can insert non-@acronym{ASCII} characters or search for them. To do that, ++you can specify an input method (@pxref{Select Input Method}) suitable ++for your language, or use the default input method set up when you set ++your language environment. If ++your keyboard can produce non-@acronym{ASCII} characters, you can select an ++appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs ++will accept those characters. Latin-1 characters can also be input by ++using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}. ++ ++On X Window systems, your locale should be set to an appropriate value ++to make sure Emacs interprets keyboard input correctly; see ++@ref{Language Environments, locales}. ++@end itemize ++ ++ The rest of this chapter describes these issues in detail. ++ ++@menu ++* International Chars:: Basic concepts of multibyte characters. ++* Enabling Multibyte:: Controlling whether to use multibyte characters. ++* Language Environments:: Setting things up for the language you use. ++* Input Methods:: Entering text characters not on your keyboard. ++* Select Input Method:: Specifying your choice of input methods. ++* Coding Systems:: Character set conversion when you read and ++ write files, and so on. ++* Recognize Coding:: How Emacs figures out which conversion to use. ++* Specify Coding:: Specifying a file's coding system explicitly. ++* Output Coding:: Choosing coding systems for output. ++* Text Coding:: Choosing conversion to use for file text. ++* Communication Coding:: Coding systems for interprocess communication. ++* File Name Coding:: Coding systems for file @emph{names}. ++* Terminal Coding:: Specifying coding systems for converting ++ terminal input and output. ++* Fontsets:: Fontsets are collections of fonts ++ that cover the whole spectrum of characters. ++* Defining Fontsets:: Defining a new fontset. ++* Modifying Fontsets:: Modifying an existing fontset. ++* Undisplayable Characters:: When characters don't display. ++* Unibyte Mode:: You can pick one European character set ++ to use without multibyte characters. ++* Charsets:: How Emacs groups its internal character codes. ++@end menu ++ ++@node International Chars ++@section Introduction to International Character Sets ++ ++ The users of international character sets and scripts have ++established many more-or-less standard coding systems for storing ++files. These coding systems are typically @dfn{multibyte}, meaning ++that sequences of two or more bytes are used to represent individual ++non-@acronym{ASCII} characters. ++ ++@cindex Unicode ++ Internally, Emacs uses its own multibyte character encoding, which ++is a superset of the @dfn{Unicode} standard. This internal encoding ++allows characters from almost every known script to be intermixed in a ++single buffer or string. Emacs translates between the multibyte ++character encoding and various other coding systems when reading and ++writing files, and when exchanging data with subprocesses. ++ ++@kindex C-h h ++@findex view-hello-file ++@cindex undisplayable characters ++@cindex @samp{?} in display ++ The command @kbd{C-h h} (@code{view-hello-file}) displays the file ++@file{etc/HELLO}, which shows how to say ``hello'' in many languages. ++This illustrates various scripts. If some characters can't be ++displayed on your terminal, they appear as @samp{?} or as hollow boxes ++(@pxref{Undisplayable Characters}). ++ ++ Keyboards, even in the countries where these character sets are ++used, generally don't have keys for all the characters in them. You ++can insert characters that your keyboard does not support, using ++@kbd{C-q} (@code{quoted-insert}) or @kbd{C-x 8 @key{RET}} ++(@code{ucs-insert}). @xref{Inserting Text}. Emacs also supports ++various @dfn{input methods}, typically one for each script or ++language, which make it easier to type characters in the script. ++@xref{Input Methods}. ++ ++@kindex C-x RET ++ The prefix key @kbd{C-x @key{RET}} is used for commands that pertain ++to multibyte characters, coding systems, and input methods. ++ ++@kindex C-x = ++@findex what-cursor-position ++ The command @kbd{C-x =} (@code{what-cursor-position}) shows ++information about the character at point. In addition to the ++character position, which was described in @ref{Position Info}, this ++command displays how the character is encoded. For instance, it ++displays the following line in the echo area for the character ++@samp{c}: ++ ++@smallexample ++Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 ++@end smallexample ++ ++ The four values after @samp{Char:} describe the character that ++follows point, first by showing it and then by giving its character ++code in decimal, octal and hex. For a non-@acronym{ASCII} multibyte ++character, these are followed by @samp{file} and the character's ++representation, in hex, in the buffer's coding system, if that coding ++system encodes the character safely and with a single byte ++(@pxref{Coding Systems}). If the character's encoding is longer than ++one byte, Emacs shows @samp{file ...}. ++ ++ As a special case, if the character lies in the range 128 (0200 ++octal) through 159 (0237 octal), it stands for a ``raw'' byte that ++does not correspond to any specific displayable character. Such a ++``character'' lies within the @code{eight-bit-control} character set, ++and is displayed as an escaped octal character code. In this case, ++@kbd{C-x =} shows @samp{part of display ...} instead of @samp{file}. ++ ++@cindex character set of character at point ++@cindex font of character at point ++@cindex text properties at point ++@cindex face at point ++ With a prefix argument (@kbd{C-u C-x =}), this command displays a ++detailed description of the character in a window: ++ ++@itemize @bullet ++@item ++The character set name, and the codes that identify the character ++within that character set; @acronym{ASCII} characters are identified ++as belonging to the @code{ascii} character set. ++ ++@item ++The character's syntax and categories. ++ ++@item ++The character's encodings, both internally in the buffer, and externally ++if you were to save the file. ++ ++@item ++What keys to type to input the character in the current input method ++(if it supports the character). ++ ++@item ++If you are running Emacs on a graphical display, the font name and ++glyph code for the character. If you are running Emacs on a text-only ++terminal, the code(s) sent to the terminal. ++ ++@item ++The character's text properties (@pxref{Text Properties,,, ++elisp, the Emacs Lisp Reference Manual}), including any non-default ++faces used to display the character, and any overlays containing it ++(@pxref{Overlays,,, elisp, the same manual}). ++@end itemize ++ ++ Here's an example showing the Latin-1 character A with grave accent, ++in a buffer whose coding system is @code{utf-8-unix}: ++ ++@smallexample ++ character: @`A (192, #o300, #xc0) ++preferred charset: unicode (Unicode (ISO10646)) ++ code point: 0xC0 ++ syntax: w which means: word ++ category: j:Japanese l:Latin v:Vietnamese ++ buffer code: #xC3 #x80 ++ file code: not encodable by coding system undecided-unix ++ display: by this font (glyph code) ++ xft:-unknown-DejaVu Sans Mono-normal-normal-normal-*-13-*-*-*-m-0-iso10646-1 (#x82) ++ ++Character code properties: customize what to show ++ name: LATIN CAPITAL LETTER A WITH GRAVE ++ general-category: Lu (Letter, Uppercase) ++ decomposition: (65 768) ('A' 'Ì€') ++ old-name: LATIN CAPITAL LETTER A GRAVE ++ ++There are text properties here: ++ auto-composed t ++@end smallexample ++ ++@node Enabling Multibyte ++@section Enabling Multibyte Characters ++ ++ By default, Emacs starts in multibyte mode: it stores the contents ++of buffers and strings using an internal encoding that represents ++non-@acronym{ASCII} characters using multi-byte sequences. Multibyte ++mode allows you to use all the supported languages and scripts without ++limitations. ++ ++@cindex turn multibyte support on or off ++ Under very special circumstances, you may want to disable multibyte ++character support, either for Emacs as a whole, or for a single ++buffer. When multibyte characters are disabled in a buffer, we call ++that @dfn{unibyte mode}. In unibyte mode, each character in the ++buffer has a character code ranging from 0 through 255 (0377 octal); 0 ++through 127 (0177 octal) represent @acronym{ASCII} characters, and 128 ++(0200 octal) through 255 (0377 octal) represent non-@acronym{ASCII} ++characters. ++ ++ To edit a particular file in unibyte representation, visit it using ++@code{find-file-literally}. @xref{Visiting}. You can convert a ++multibyte buffer to unibyte by saving it to a file, killing the ++buffer, and visiting the file again with @code{find-file-literally}. ++Alternatively, you can use @kbd{C-x @key{RET} c} ++(@code{universal-coding-system-argument}) and specify @samp{raw-text} ++as the coding system with which to visit or save a file. @xref{Text ++Coding}. Unlike @code{find-file-literally}, finding a file as ++@samp{raw-text} doesn't disable format conversion, uncompression, or ++auto mode selection. ++ ++@vindex enable-multibyte-characters ++@vindex default-enable-multibyte-characters ++@cindex environment variables, and non-@acronym{ASCII} characters ++ To turn off multibyte character support by default, start Emacs with ++the @samp{--unibyte} option (@pxref{Initial Options}), or set the ++environment variable @env{EMACS_UNIBYTE}. You can also customize ++@code{enable-multibyte-characters} or, equivalently, directly set the ++variable @code{default-enable-multibyte-characters} to @code{nil} in ++your init file to have basically the same effect as @samp{--unibyte}. ++With @samp{--unibyte}, multibyte strings are not created during ++initialization from the values of environment variables, ++@file{/etc/passwd} entries etc., even if those contain ++non-@acronym{ASCII} characters. ++ ++@cindex Lisp files, and multibyte operation ++@cindex multibyte operation, and Lisp files ++@cindex unibyte operation, and Lisp files ++@cindex init file, and non-@acronym{ASCII} characters ++ Emacs normally loads Lisp files as multibyte, regardless of whether ++you used @samp{--unibyte}. This includes the Emacs initialization ++file, @file{.emacs}, and the initialization files of Emacs packages ++such as Gnus. However, you can specify unibyte loading for a ++particular Lisp file, by putting @w{@samp{-*-unibyte: t;-*-}} in a ++comment on the first line (@pxref{File Variables}). Then that file is ++always loaded as unibyte text. The motivation for these conventions ++is that it is more reliable to always load any particular Lisp file in ++the same way. However, you can load a Lisp file as unibyte, on any ++one occasion, by typing @kbd{C-x @key{RET} c raw-text @key{RET}} ++immediately before loading it. ++ ++ The mode line indicates whether multibyte character support is ++enabled in the current buffer. If it is, there are two or more ++characters (most often two dashes) near the beginning of the mode ++line, before the indication of the visited file's end-of-line ++convention (colon, backslash, etc.). When multibyte characters ++are not enabled, nothing precedes the colon except a single dash. ++@xref{Mode Line}, for more details about this. ++ ++@findex toggle-enable-multibyte-characters ++ To convert a unibyte session to a multibyte session, set ++@code{default-enable-multibyte-characters} to @code{t}. Buffers which ++were created in the unibyte session before you turn on multibyte ++support will stay unibyte. You can turn on multibyte support in a ++specific buffer by invoking the command ++@code{toggle-enable-multibyte-characters} in that buffer. ++ ++@node Language Environments ++@section Language Environments ++@cindex language environments ++ ++ All supported character sets are supported in Emacs buffers whenever ++multibyte characters are enabled; there is no need to select a ++particular language in order to display its characters in an Emacs ++buffer. However, it is important to select a @dfn{language ++environment} in order to set various defaults. Roughly speaking, the ++language environment represents a choice of preferred script rather ++than a choice of language. ++ ++ The language environment controls which coding systems to recognize ++when reading text (@pxref{Recognize Coding}). This applies to files, ++incoming mail, and any other text you read into Emacs. It may also ++specify the default coding system to use when you create a file. Each ++language environment also specifies a default input method. ++ ++@findex set-language-environment ++@vindex current-language-environment ++ To select a language environment, customize the variable ++@code{current-language-environment} or use the command @kbd{M-x ++set-language-environment}. It makes no difference which buffer is ++current when you use this command, because the effects apply globally ++to the Emacs session. The supported language environments include: ++ ++@cindex Euro sign ++@cindex UTF-8 ++@quotation ++ASCII, Belarusian, Bengali, Brazilian Portuguese, Bulgarian, ++Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Chinese-GBK, ++Chinese-GB18030, Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8, ++Czech, Devanagari, Dutch, English, Esperanto, Ethiopic, French, ++Georgian, German, Greek, Gujarati, Hebrew, IPA, Italian, Japanese, ++Kannada, Khmer, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4, ++Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated Latin-1 ++with the Euro sign), Latvian, Lithuanian, Malayalam, Oriya, Polish, ++Punjabi, Romanian, Russian, Sinhala, Slovak, Slovenian, Spanish, ++Swedish, TaiViet, Tajik, Tamil, Telugu, Thai, Tibetan, Turkish, UTF-8 ++(for a setup which prefers Unicode characters and files encoded in ++UTF-8), Ukrainian, Vietnamese, Welsh, and Windows-1255 (for a setup ++which prefers Cyrillic characters and files encoded in Windows-1255). ++@end quotation ++ ++@cindex fonts for various scripts ++@cindex Intlfonts package, installation ++ To display the script(s) used by your language environment on a ++graphical display, you need to have a suitable font. If some of the ++characters appear as empty boxes, you should install the GNU Intlfonts ++package, which includes fonts for most supported scripts.@footnote{If ++you run Emacs on X, you need to inform the X server about the location ++of the newly installed fonts with the following commands: ++ ++@example ++ xset fp+ /usr/local/share/emacs/fonts ++ xset fp rehash ++@end example ++} ++@xref{Fontsets}, for more details about setting up your fonts. ++ ++@findex set-locale-environment ++@vindex locale-language-names ++@vindex locale-charset-language-names ++@cindex locales ++ Some operating systems let you specify the character-set locale you ++are using by setting the locale environment variables @env{LC_ALL}, ++@env{LC_CTYPE}, or @env{LANG}.@footnote{If more than one of these is ++set, the first one that is nonempty specifies your locale for this ++purpose.} During startup, Emacs looks up your character-set locale's ++name in the system locale alias table, matches its canonical name ++against entries in the value of the variables ++@code{locale-charset-language-names} and @code{locale-language-names}, ++and selects the corresponding language environment if a match is found. ++(The former variable overrides the latter.) It also adjusts the display ++table and terminal coding system, the locale coding system, the ++preferred coding system as needed for the locale, and---last but not ++least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard. ++ ++ If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG} ++environment variables while running Emacs, you may want to invoke the ++@code{set-locale-environment} function afterwards to readjust the ++language environment from the new locale. ++ ++@vindex locale-preferred-coding-systems ++ The @code{set-locale-environment} function normally uses the preferred ++coding system established by the language environment to decode system ++messages. But if your locale matches an entry in the variable ++@code{locale-preferred-coding-systems}, Emacs uses the corresponding ++coding system instead. For example, if the locale @samp{ja_JP.PCK} ++matches @code{japanese-shift-jis} in ++@code{locale-preferred-coding-systems}, Emacs uses that encoding even ++though it might normally use @code{japanese-iso-8bit}. ++ ++ You can override the language environment chosen at startup with ++explicit use of the command @code{set-language-environment}, or with ++customization of @code{current-language-environment} in your init ++file. ++ ++@kindex C-h L ++@findex describe-language-environment ++ To display information about the effects of a certain language ++environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env} ++@key{RET}} (@code{describe-language-environment}). This tells you ++which languages this language environment is useful for, and lists the ++character sets, coding systems, and input methods that go with it. It ++also shows some sample text to illustrate scripts used in this ++language environment. If you give an empty input for @var{lang-env}, ++this command describes the chosen language environment. ++@anchor{Describe Language Environment} ++ ++@vindex set-language-environment-hook ++ You can customize any language environment with the normal hook ++@code{set-language-environment-hook}. The command ++@code{set-language-environment} runs that hook after setting up the new ++language environment. The hook functions can test for a specific ++language environment by checking the variable ++@code{current-language-environment}. This hook is where you should ++put non-default settings for specific language environment, such as ++coding systems for keyboard input and terminal output, the default ++input method, etc. ++ ++@vindex exit-language-environment-hook ++ Before it starts to set up the new language environment, ++@code{set-language-environment} first runs the hook ++@code{exit-language-environment-hook}. This hook is useful for undoing ++customizations that were made with @code{set-language-environment-hook}. ++For instance, if you set up a special key binding in a specific language ++environment using @code{set-language-environment-hook}, you should set ++up @code{exit-language-environment-hook} to restore the normal binding ++for that key. ++ ++@node Input Methods ++@section Input Methods ++ ++@cindex input methods ++ An @dfn{input method} is a kind of character conversion designed ++specifically for interactive input. In Emacs, typically each language ++has its own input method; sometimes several languages which use the same ++characters can share one input method. A few languages support several ++input methods. ++ ++ The simplest kind of input method works by mapping @acronym{ASCII} letters ++into another alphabet; this allows you to use one other alphabet ++instead of @acronym{ASCII}. The Greek and Russian input methods ++work this way. ++ ++ A more powerful technique is composition: converting sequences of ++characters into one letter. Many European input methods use composition ++to produce a single non-@acronym{ASCII} letter from a sequence that consists of a ++letter followed by accent characters (or vice versa). For example, some ++methods convert the sequence @kbd{a'} into a single accented letter. ++These input methods have no special commands of their own; all they do ++is compose sequences of printing characters. ++ ++ The input methods for syllabic scripts typically use mapping followed ++by composition. The input methods for Thai and Korean work this way. ++First, letters are mapped into symbols for particular sounds or tone ++marks; then, sequences of these which make up a whole syllable are ++mapped into one syllable sign. ++ ++ Chinese and Japanese require more complex methods. In Chinese input ++methods, first you enter the phonetic spelling of a Chinese word (in ++input method @code{chinese-py}, among others), or a sequence of ++portions of the character (input methods @code{chinese-4corner} and ++@code{chinese-sw}, and others). One input sequence typically ++corresponds to many possible Chinese characters. You select the one ++you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n}, ++@kbd{C-p}, and digits, which have special meanings in this situation. ++ ++ The possible characters are conceptually arranged in several rows, ++with each row holding up to 10 alternatives. Normally, Emacs displays ++just one row at a time, in the echo area; @code{(@var{i}/@var{j})} ++appears at the beginning, to indicate that this is the @var{i}th row ++out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to ++display the next row or the previous row. ++ ++ Type @kbd{C-f} and @kbd{C-b} to move forward and backward among ++the alternatives in the current row. As you do this, Emacs highlights ++the current alternative with a special color; type @code{C-@key{SPC}} ++to select the current alternative and use it as input. The ++alternatives in the row are also numbered; the number appears before ++the alternative. Typing a digit @var{n} selects the @var{n}th ++alternative of the current row and uses it as input. ++ ++ @key{TAB} in these Chinese input methods displays a buffer showing ++all the possible characters at once; then clicking @kbd{Mouse-2} on ++one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b}, ++@kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they ++do the highlighting in the buffer showing the possible characters, ++rather than in the echo area. ++ ++ In Japanese input methods, first you input a whole word using ++phonetic spelling; then, after the word is in the buffer, Emacs ++converts it into one or more characters using a large dictionary. One ++phonetic spelling corresponds to a number of different Japanese words; ++to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through ++the alternatives. ++ ++ Sometimes it is useful to cut off input method processing so that the ++characters you have just entered will not combine with subsequent ++characters. For example, in input method @code{latin-1-postfix}, the ++sequence @kbd{e '} combines to form an @samp{e} with an accent. What if ++you want to enter them as separate characters? ++ ++ One way is to type the accent twice; this is a special feature for ++entering the separate letter and accent. For example, @kbd{e ' '} gives ++you the two characters @samp{e'}. Another way is to type another letter ++after the @kbd{e}---something that won't combine with that---and ++immediately delete it. For example, you could type @kbd{e e @key{DEL} ++'} to get separate @samp{e} and @samp{'}. ++ ++ Another method, more general but not quite as easy to type, is to use ++@kbd{C-\ C-\} between two characters to stop them from combining. This ++is the command @kbd{C-\} (@code{toggle-input-method}) used twice. ++@ifnottex ++@xref{Select Input Method}. ++@end ifnottex ++ ++@cindex incremental search, input method interference ++ @kbd{C-\ C-\} is especially useful inside an incremental search, ++because it stops waiting for more characters to combine, and starts ++searching for what you have already entered. ++ ++ To find out how to input the character after point using the current ++input method, type @kbd{C-u C-x =}. @xref{Position Info}. ++ ++@vindex input-method-verbose-flag ++@vindex input-method-highlight-flag ++ The variables @code{input-method-highlight-flag} and ++@code{input-method-verbose-flag} control how input methods explain ++what is happening. If @code{input-method-highlight-flag} is ++non-@code{nil}, the partial sequence is highlighted in the buffer (for ++most input methods---some disable this feature). If ++@code{input-method-verbose-flag} is non-@code{nil}, the list of ++possible characters to type next is displayed in the echo area (but ++not when you are in the minibuffer). ++ ++@node Select Input Method ++@section Selecting an Input Method ++ ++@table @kbd ++@item C-\ ++Enable or disable use of the selected input method. ++ ++@item C-x @key{RET} C-\ @var{method} @key{RET} ++Select a new input method for the current buffer. ++ ++@item C-h I @var{method} @key{RET} ++@itemx C-h C-\ @var{method} @key{RET} ++@findex describe-input-method ++@kindex C-h I ++@kindex C-h C-\ ++Describe the input method @var{method} (@code{describe-input-method}). ++By default, it describes the current input method (if any). This ++description should give you the full details of how to use any ++particular input method. ++ ++@item M-x list-input-methods ++Display a list of all the supported input methods. ++@end table ++ ++@findex set-input-method ++@vindex current-input-method ++@kindex C-x RET C-\ ++ To choose an input method for the current buffer, use @kbd{C-x ++@key{RET} C-\} (@code{set-input-method}). This command reads the ++input method name from the minibuffer; the name normally starts with the ++language environment that it is meant to be used with. The variable ++@code{current-input-method} records which input method is selected. ++ ++@findex toggle-input-method ++@kindex C-\ ++ Input methods use various sequences of @acronym{ASCII} characters to ++stand for non-@acronym{ASCII} characters. Sometimes it is useful to ++turn off the input method temporarily. To do this, type @kbd{C-\} ++(@code{toggle-input-method}). To reenable the input method, type ++@kbd{C-\} again. ++ ++ If you type @kbd{C-\} and you have not yet selected an input method, ++it prompts for you to specify one. This has the same effect as using ++@kbd{C-x @key{RET} C-\} to specify an input method. ++ ++ When invoked with a numeric argument, as in @kbd{C-u C-\}, ++@code{toggle-input-method} always prompts you for an input method, ++suggesting the most recently selected one as the default. ++ ++@vindex default-input-method ++ Selecting a language environment specifies a default input method for ++use in various buffers. When you have a default input method, you can ++select it in the current buffer by typing @kbd{C-\}. The variable ++@code{default-input-method} specifies the default input method ++(@code{nil} means there is none). ++ ++ In some language environments, which support several different input ++methods, you might want to use an input method different from the ++default chosen by @code{set-language-environment}. You can instruct ++Emacs to select a different default input method for a certain ++language environment, if you wish, by using ++@code{set-language-environment-hook} (@pxref{Language Environments, ++set-language-environment-hook}). For example: ++ ++@lisp ++(defun my-chinese-setup () ++ "Set up my private Chinese environment." ++ (if (equal current-language-environment "Chinese-GB") ++ (setq default-input-method "chinese-tonepy"))) ++(add-hook 'set-language-environment-hook 'my-chinese-setup) ++@end lisp ++ ++@noindent ++This sets the default input method to be @code{chinese-tonepy} ++whenever you choose a Chinese-GB language environment. ++ ++You can instruct Emacs to activate a certain input method ++automatically. For example: ++ ++@lisp ++(add-hook 'text-mode-hook ++ (lambda () (set-input-method "german-prefix"))) ++@end lisp ++ ++@noindent ++This activates the input method ``german-prefix'' automatically in the ++Text mode. ++ ++@findex quail-set-keyboard-layout ++ Some input methods for alphabetic scripts work by (in effect) ++remapping the keyboard to emulate various keyboard layouts commonly used ++for those scripts. How to do this remapping properly depends on your ++actual keyboard layout. To specify which layout your keyboard has, use ++the command @kbd{M-x quail-set-keyboard-layout}. ++ ++@findex quail-show-key ++ You can use the command @kbd{M-x quail-show-key} to show what key (or ++key sequence) to type in order to input the character following point, ++using the selected keyboard layout. The command @kbd{C-u C-x =} also ++shows that information in addition to the other information about the ++character. ++ ++@findex list-input-methods ++ To see a list of all the supported input methods, type @kbd{M-x ++list-input-methods}. The list gives information about each input ++method, including the string that stands for it in the mode line. ++ ++@node Coding Systems ++@section Coding Systems ++@cindex coding systems ++ ++ Users of various languages have established many more-or-less standard ++coding systems for representing them. Emacs does not use these coding ++systems internally; instead, it converts from various coding systems to ++its own system when reading data, and converts the internal coding ++system to other coding systems when writing data. Conversion is ++possible in reading or writing files, in sending or receiving from the ++terminal, and in exchanging data with subprocesses. ++ ++ Emacs assigns a name to each coding system. Most coding systems are ++used for one language, and the name of the coding system starts with ++the language name. Some coding systems are used for several ++languages; their names usually start with @samp{iso}. There are also ++special coding systems, such as @code{no-conversion}, @code{raw-text}, ++and @code{emacs-internal}. ++ ++@cindex international files from DOS/Windows systems ++ A special class of coding systems, collectively known as ++@dfn{codepages}, is designed to support text encoded by MS-Windows and ++MS-DOS software. The names of these coding systems are ++@code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the ++codepage. You can use these encodings just like any other coding ++system; for example, to visit a file encoded in codepage 850, type ++@kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename} ++@key{RET}}. ++ ++ In addition to converting various representations of non-@acronym{ASCII} ++characters, a coding system can perform end-of-line conversion. Emacs ++handles three different conventions for how to separate lines in a file: ++newline, carriage-return linefeed, and just carriage-return. ++ ++@table @kbd ++@item C-h C @var{coding} @key{RET} ++Describe coding system @var{coding}. ++ ++@item C-h C @key{RET} ++Describe the coding systems currently in use. ++ ++@item M-x list-coding-systems ++Display a list of all the supported coding systems. ++@end table ++ ++@kindex C-h C ++@findex describe-coding-system ++ The command @kbd{C-h C} (@code{describe-coding-system}) displays ++information about particular coding systems, including the end-of-line ++conversion specified by those coding systems. You can specify a coding ++system name as the argument; alternatively, with an empty argument, it ++describes the coding systems currently selected for various purposes, ++both in the current buffer and as the defaults, and the priority list ++for recognizing coding systems (@pxref{Recognize Coding}). ++ ++@findex list-coding-systems ++ To display a list of all the supported coding systems, type @kbd{M-x ++list-coding-systems}. The list gives information about each coding ++system, including the letter that stands for it in the mode line ++(@pxref{Mode Line}). ++ ++@cindex end-of-line conversion ++@cindex line endings ++@cindex MS-DOS end-of-line conversion ++@cindex Macintosh end-of-line conversion ++ Each of the coding systems that appear in this list---except for ++@code{no-conversion}, which means no conversion of any kind---specifies ++how and whether to convert printing characters, but leaves the choice of ++end-of-line conversion to be decided based on the contents of each file. ++For example, if the file appears to use the sequence carriage-return ++linefeed to separate lines, DOS end-of-line conversion will be used. ++ ++ Each of the listed coding systems has three variants which specify ++exactly what to do for end-of-line conversion: ++ ++@table @code ++@item @dots{}-unix ++Don't do any end-of-line conversion; assume the file uses ++newline to separate lines. (This is the convention normally used ++on Unix and GNU systems.) ++ ++@item @dots{}-dos ++Assume the file uses carriage-return linefeed to separate lines, and do ++the appropriate conversion. (This is the convention normally used on ++Microsoft systems.@footnote{It is also specified for MIME @samp{text/*} ++bodies and in other network transport contexts. It is different ++from the SGML reference syntax record-start/record-end format which ++Emacs doesn't support directly.}) ++ ++@item @dots{}-mac ++Assume the file uses carriage-return to separate lines, and do the ++appropriate conversion. (This is the convention normally used on the ++Macintosh system.) ++@end table ++ ++ These variant coding systems are omitted from the ++@code{list-coding-systems} display for brevity, since they are entirely ++predictable. For example, the coding system @code{iso-latin-1} has ++variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and ++@code{iso-latin-1-mac}. ++ ++@cindex @code{undecided}, coding system ++ The coding systems @code{unix}, @code{dos}, and @code{mac} are ++aliases for @code{undecided-unix}, @code{undecided-dos}, and ++@code{undecided-mac}, respectively. These coding systems specify only ++the end-of-line conversion, and leave the character code conversion to ++be deduced from the text itself. ++ ++ The coding system @code{raw-text} is good for a file which is mainly ++@acronym{ASCII} text, but may contain byte values above 127 which are ++not meant to encode non-@acronym{ASCII} characters. With ++@code{raw-text}, Emacs copies those byte values unchanged, and sets ++@code{enable-multibyte-characters} to @code{nil} in the current buffer ++so that they will be interpreted properly. @code{raw-text} handles ++end-of-line conversion in the usual way, based on the data ++encountered, and has the usual three variants to specify the kind of ++end-of-line conversion to use. ++ ++ In contrast, the coding system @code{no-conversion} specifies no ++character code conversion at all---none for non-@acronym{ASCII} byte values and ++none for end of line. This is useful for reading or writing binary ++files, tar files, and other files that must be examined verbatim. It, ++too, sets @code{enable-multibyte-characters} to @code{nil}. ++ ++ The easiest way to edit a file with no conversion of any kind is with ++the @kbd{M-x find-file-literally} command. This uses ++@code{no-conversion}, and also suppresses other Emacs features that ++might convert the file contents before you see them. @xref{Visiting}. ++ ++ The coding system @code{emacs-internal} (or @code{utf-8-emacs}, ++which is equivalent) means that the file contains non-@acronym{ASCII} ++characters stored with the internal Emacs encoding. This coding ++system handles end-of-line conversion based on the data encountered, ++and has the usual three variants to specify the kind of end-of-line ++conversion. ++ ++@node Recognize Coding ++@section Recognizing Coding Systems ++ ++ Whenever Emacs reads a given piece of text, it tries to recognize ++which coding system to use. This applies to files being read, output ++from subprocesses, text from X selections, etc. Emacs can select the ++right coding system automatically most of the time---once you have ++specified your preferences. ++ ++ Some coding systems can be recognized or distinguished by which byte ++sequences appear in the data. However, there are coding systems that ++cannot be distinguished, not even potentially. For example, there is no ++way to distinguish between Latin-1 and Latin-2; they use the same byte ++values with different meanings. ++ ++ Emacs handles this situation by means of a priority list of coding ++systems. Whenever Emacs reads a file, if you do not specify the coding ++system to use, Emacs checks the data against each coding system, ++starting with the first in priority and working down the list, until it ++finds a coding system that fits the data. Then it converts the file ++contents assuming that they are represented in this coding system. ++ ++ The priority list of coding systems depends on the selected language ++environment (@pxref{Language Environments}). For example, if you use ++French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use ++Czech, you probably want Latin-2 to be preferred. This is one of the ++reasons to specify a language environment. ++ ++@findex prefer-coding-system ++ However, you can alter the coding system priority list in detail ++with the command @kbd{M-x prefer-coding-system}. This command reads ++the name of a coding system from the minibuffer, and adds it to the ++front of the priority list, so that it is preferred to all others. If ++you use this command several times, each use adds one element to the ++front of the priority list. ++ ++ If you use a coding system that specifies the end-of-line conversion ++type, such as @code{iso-8859-1-dos}, what this means is that Emacs ++should attempt to recognize @code{iso-8859-1} with priority, and should ++use DOS end-of-line conversion when it does recognize @code{iso-8859-1}. ++ ++@vindex file-coding-system-alist ++ Sometimes a file name indicates which coding system to use for the ++file. The variable @code{file-coding-system-alist} specifies this ++correspondence. There is a special function ++@code{modify-coding-system-alist} for adding elements to this list. For ++example, to read and write all @samp{.txt} files using the coding system ++@code{chinese-iso-8bit}, you can execute this Lisp expression: ++ ++@smallexample ++(modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit) ++@end smallexample ++ ++@noindent ++The first argument should be @code{file}, the second argument should be ++a regular expression that determines which files this applies to, and ++the third argument says which coding system to use for these files. ++ ++@vindex inhibit-eol-conversion ++@cindex DOS-style end-of-line display ++ Emacs recognizes which kind of end-of-line conversion to use based on ++the contents of the file: if it sees only carriage-returns, or only ++carriage-return linefeed sequences, then it chooses the end-of-line ++conversion accordingly. You can inhibit the automatic use of ++end-of-line conversion by setting the variable @code{inhibit-eol-conversion} ++to non-@code{nil}. If you do that, DOS-style files will be displayed ++with the @samp{^M} characters visible in the buffer; some people ++prefer this to the more subtle @samp{(DOS)} end-of-line type ++indication near the left edge of the mode line (@pxref{Mode Line, ++eol-mnemonic}). ++ ++@vindex inhibit-iso-escape-detection ++@cindex escape sequences in files ++ By default, the automatic detection of coding system is sensitive to ++escape sequences. If Emacs sees a sequence of characters that begin ++with an escape character, and the sequence is valid as an ISO-2022 ++code, that tells Emacs to use one of the ISO-2022 encodings to decode ++the file. ++ ++ However, there may be cases that you want to read escape sequences ++in a file as is. In such a case, you can set the variable ++@code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code ++detection ignores any escape sequences, and never uses an ISO-2022 ++encoding. The result is that all escape sequences become visible in ++the buffer. ++ ++ The default value of @code{inhibit-iso-escape-detection} is ++@code{nil}. We recommend that you not change it permanently, only for ++one specific operation. That's because many Emacs Lisp source files ++in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the ++coding system @code{iso-2022-7bit}, and they won't be ++decoded correctly when you visit those files if you suppress the ++escape sequence detection. ++ ++@vindex auto-coding-alist ++@vindex auto-coding-regexp-alist ++@vindex auto-coding-functions ++ The variables @code{auto-coding-alist}, ++@code{auto-coding-regexp-alist} and @code{auto-coding-functions} are ++the strongest way to specify the coding system for certain patterns of ++file names, or for files containing certain patterns; these variables ++even override @samp{-*-coding:-*-} tags in the file itself. Emacs ++uses @code{auto-coding-alist} for tar and archive files, to prevent it ++from being confused by a @samp{-*-coding:-*-} tag in a member of the ++archive and thinking it applies to the archive file as a whole. ++Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that ++RMAIL files, whose names in general don't match any particular ++pattern, are decoded correctly. One of the builtin ++@code{auto-coding-functions} detects the encoding for XML files. ++ ++@vindex rmail-decode-mime-charset ++@vindex rmail-file-coding-system ++ When you get new mail in Rmail, each message is translated ++automatically from the coding system it is written in, as if it were a ++separate file. This uses the priority list of coding systems that you ++have specified. If a MIME message specifies a character set, Rmail ++obeys that specification, unless @code{rmail-decode-mime-charset} is ++@code{nil}. For reading and saving Rmail files themselves, Emacs uses ++the coding system specified by the variable ++@code{rmail-file-coding-system}. The default value is @code{nil}, ++which means that Rmail files are not translated (they are read and ++written in the Emacs internal character code). ++ ++@node Specify Coding ++@section Specifying a File's Coding System ++ ++ If Emacs recognizes the encoding of a file incorrectly, you can ++reread the file using the correct coding system by typing @kbd{C-x ++@key{RET} r @var{coding-system} @key{RET}}. To see what coding system ++Emacs actually used to decode the file, look at the coding system ++mnemonic letter near the left edge of the mode line (@pxref{Mode ++Line}), or type @kbd{C-h C @key{RET}}. ++ ++@vindex coding ++ You can specify the coding system for a particular file in the file ++itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning, ++or a local variables list at the end (@pxref{File Variables}). You do ++this by defining a value for the ``variable'' named @code{coding}. ++Emacs does not really have a variable @code{coding}; instead of ++setting a variable, this uses the specified coding system for the ++file. For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies ++use of the Latin-1 coding system, as well as C mode. When you specify ++the coding explicitly in the file, that overrides ++@code{file-coding-system-alist}. ++ ++@node Output Coding ++@section Choosing Coding Systems for Output ++ ++@vindex buffer-file-coding-system ++ Once Emacs has chosen a coding system for a buffer, it stores that ++coding system in @code{buffer-file-coding-system}. That makes it the ++default for operations that write from this buffer into a file, such ++as @code{save-buffer} and @code{write-region}. You can specify a ++different coding system for further file output from the buffer using ++@code{set-buffer-file-coding-system} (@pxref{Text Coding}). ++ ++ You can insert any character Emacs supports into any Emacs buffer, ++but most coding systems can only handle a subset of these characters. ++Therefore, it's possible that the characters you insert cannot be ++encoded with the coding system that will be used to save the buffer. ++For example, you could visit a text file in Polish, encoded in ++@code{iso-8859-2}, and add some Russian words to it. When you save ++that buffer, Emacs cannot use the current value of ++@code{buffer-file-coding-system}, because the characters you added ++cannot be encoded by that coding system. ++ ++ When that happens, Emacs tries the most-preferred coding system (set ++by @kbd{M-x prefer-coding-system} or @kbd{M-x ++set-language-environment}). If that coding system can safely encode ++all of the characters in the buffer, Emacs uses it, and stores its ++value in @code{buffer-file-coding-system}. Otherwise, Emacs displays ++a list of coding systems suitable for encoding the buffer's contents, ++and asks you to choose one of those coding systems. ++ ++ If you insert the unsuitable characters in a mail message, Emacs ++behaves a bit differently. It additionally checks whether the ++most-preferred coding system is recommended for use in MIME messages; ++if not, Emacs tells you that the most-preferred coding system is not ++recommended and prompts you for another coding system. This is so you ++won't inadvertently send a message encoded in a way that your ++recipient's mail software will have difficulty decoding. (You can ++still use an unsuitable coding system if you type its name in response ++to the question.) ++ ++@vindex sendmail-coding-system ++ When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has ++four different ways to determine the coding system to use for encoding ++the message text. It tries the buffer's own value of ++@code{buffer-file-coding-system}, if that is non-@code{nil}. Otherwise, ++it uses the value of @code{sendmail-coding-system}, if that is ++non-@code{nil}. The third way is to use the default coding system for ++new files, which is controlled by your choice of language environment, ++if that is non-@code{nil}. If all of these three values are @code{nil}, ++Emacs encodes outgoing mail using the Latin-1 coding system. ++ ++@node Text Coding ++@section Specifying a Coding System for File Text ++ ++ In cases where Emacs does not automatically choose the right coding ++system for a file's contents, you can use these commands to specify ++one: ++ ++@table @kbd ++@item C-x @key{RET} f @var{coding} @key{RET} ++Use coding system @var{coding} for saving or revisiting the visited ++file in the current buffer. ++ ++@item C-x @key{RET} c @var{coding} @key{RET} ++Specify coding system @var{coding} for the immediately following ++command. ++ ++@item C-x @key{RET} r @var{coding} @key{RET} ++Revisit the current file using the coding system @var{coding}. ++ ++@item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET} ++Convert a region that was decoded using coding system @var{wrong}, ++decoding it using coding system @var{right} instead. ++@end table ++ ++@kindex C-x RET f ++@findex set-buffer-file-coding-system ++ The command @kbd{C-x @key{RET} f} ++(@code{set-buffer-file-coding-system}) sets the file coding system for ++the current buffer---in other words, it says which coding system to ++use when saving or reverting the visited file. You specify which ++coding system using the minibuffer. If you specify a coding system ++that cannot handle all of the characters in the buffer, Emacs warns ++you about the troublesome characters when you actually save the ++buffer. ++ ++@cindex specify end-of-line conversion ++ You can also use this command to specify the end-of-line conversion ++(@pxref{Coding Systems, end-of-line conversion}) for encoding the ++current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will ++cause Emacs to save the current buffer's text with DOS-style CRLF line ++endings. ++ ++@kindex C-x RET c ++@findex universal-coding-system-argument ++ Another way to specify the coding system for a file is when you visit ++the file. First use the command @kbd{C-x @key{RET} c} ++(@code{universal-coding-system-argument}); this command uses the ++minibuffer to read a coding system name. After you exit the minibuffer, ++the specified coding system is used for @emph{the immediately following ++command}. ++ ++ So if the immediately following command is @kbd{C-x C-f}, for example, ++it reads the file using that coding system (and records the coding ++system for when you later save the file). Or if the immediately following ++command is @kbd{C-x C-w}, it writes the file using that coding system. ++When you specify the coding system for saving in this way, instead ++of with @kbd{C-x @key{RET} f}, there is no warning if the buffer ++contains characters that the coding system cannot handle. ++ ++ Other file commands affected by a specified coding system include ++@kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants ++of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that ++start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the ++immediately following command does not use the coding system, then ++@kbd{C-x @key{RET} c} ultimately has no effect. ++ ++ An easy way to visit a file with no conversion is with the @kbd{M-x ++find-file-literally} command. @xref{Visiting}. ++ ++@vindex default-buffer-file-coding-system ++ The variable @code{default-buffer-file-coding-system} specifies the ++choice of coding system to use when you create a new file. It applies ++when you find a new file, and when you create a buffer and then save it ++in a file. Selecting a language environment typically sets this ++variable to a good choice of default coding system for that language ++environment. ++ ++@kindex C-x RET r ++@findex revert-buffer-with-coding-system ++ If you visit a file with a wrong coding system, you can correct this ++with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}). ++This visits the current file again, using a coding system you specify. ++ ++@findex recode-region ++ If a piece of text has already been inserted into a buffer using the ++wrong coding system, you can redo the decoding of it using @kbd{M-x ++recode-region}. This prompts you for the proper coding system, then ++for the wrong coding system that was actually used, and does the ++conversion. It first encodes the region using the wrong coding system, ++then decodes it again using the proper coding system. ++ ++@node Communication Coding ++@section Coding Systems for Interprocess Communication ++ ++ This section explains how to specify coding systems for use ++in communication with other processes. ++ ++@table @kbd ++@item C-x @key{RET} x @var{coding} @key{RET} ++Use coding system @var{coding} for transferring selections to and from ++other window-based applications. ++ ++@item C-x @key{RET} X @var{coding} @key{RET} ++Use coding system @var{coding} for transferring @emph{one} ++selection---the next one---to or from another window-based application. ++ ++@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET} ++Use coding systems @var{input-coding} and @var{output-coding} for ++subprocess input and output in the current buffer. ++ ++@item C-x @key{RET} c @var{coding} @key{RET} ++Specify coding system @var{coding} for the immediately following ++command. ++@end table ++ ++@kindex C-x RET x ++@kindex C-x RET X ++@findex set-selection-coding-system ++@findex set-next-selection-coding-system ++ The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system}) ++specifies the coding system for sending selected text to other windowing ++applications, and for receiving the text of selections made in other ++applications. This command applies to all subsequent selections, until ++you override it by using the command again. The command @kbd{C-x ++@key{RET} X} (@code{set-next-selection-coding-system}) specifies the ++coding system for the next selection made in Emacs or read by Emacs. ++ ++@vindex x-select-request-type ++ The variable @code{x-select-request-type} specifies the data type to ++request from the X Window System for receiving text selections from ++other applications. If the value is @code{nil} (the default), Emacs ++tries @code{COMPOUND_TEXT} and @code{UTF8_STRING}, in this order, and ++uses various heuristics to choose the more appropriate of the two ++results; if none of these succeed, Emacs falls back on @code{STRING}. ++If the value of @code{x-select-request-type} is one of the symbols ++@code{COMPOUND_TEXT}, @code{UTF8_STRING}, @code{STRING}, or ++@code{TEXT}, Emacs uses only that request type. If the value is a ++list of some of these symbols, Emacs tries only the request types in ++the list, in order, until one of them succeeds, or until the list is ++exhausted. ++ ++@kindex C-x RET p ++@findex set-buffer-process-coding-system ++ The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system}) ++specifies the coding system for input and output to a subprocess. This ++command applies to the current buffer; normally, each subprocess has its ++own buffer, and thus you can use this command to specify translation to ++and from a particular subprocess by giving the command in the ++corresponding buffer. ++ ++ You can also use @kbd{C-x @key{RET} c} just before the command that ++runs or starts a subprocess, to specify the coding system to use for ++communication with that subprocess. ++ ++ The default for translation of process input and output depends on the ++current language environment. ++ ++@vindex locale-coding-system ++@cindex decoding non-@acronym{ASCII} keyboard input on X ++ The variable @code{locale-coding-system} specifies a coding system ++to use when encoding and decoding system strings such as system error ++messages and @code{format-time-string} formats and time stamps. That ++coding system is also used for decoding non-@acronym{ASCII} keyboard input on X ++Window systems. You should choose a coding system that is compatible ++with the underlying system's text representation, which is normally ++specified by one of the environment variables @env{LC_ALL}, ++@env{LC_CTYPE}, and @env{LANG}. (The first one, in the order ++specified above, whose value is nonempty is the one that determines ++the text representation.) ++ ++@vindex x-select-request-type ++ The variable @code{x-select-request-type} specifies a selection data ++type of selection to request from the X server. The default value is ++@code{nil}, which means Emacs tries @code{COMPOUND_TEXT} and ++@code{UTF8_STRING}, and uses whichever result seems more appropriate. ++You can explicitly specify the data type by setting the variable to ++one of the symbols @code{COMPOUND_TEXT}, @code{UTF8_STRING}, ++@code{STRING} and @code{TEXT}. ++ ++@node File Name Coding ++@section Coding Systems for File Names ++ ++@table @kbd ++@item C-x @key{RET} F @var{coding} @key{RET} ++Use coding system @var{coding} for encoding and decoding file ++@emph{names}. ++@end table ++ ++@vindex file-name-coding-system ++@cindex file names with non-@acronym{ASCII} characters ++ The variable @code{file-name-coding-system} specifies a coding ++system to use for encoding file names. It has no effect on reading ++and writing the @emph{contents} of files. ++ ++@findex set-file-name-coding-system ++@kindex C-x @key{RET} F ++ If you set the variable to a coding system name (as a Lisp symbol or ++a string), Emacs encodes file names using that coding system for all ++file operations. This makes it possible to use non-@acronym{ASCII} ++characters in file names---or, at least, those non-@acronym{ASCII} ++characters which the specified coding system can encode. Use @kbd{C-x ++@key{RET} F} (@code{set-file-name-coding-system}) to specify this ++interactively. ++ ++ If @code{file-name-coding-system} is @code{nil}, Emacs uses a ++default coding system determined by the selected language environment. ++In the default language environment, non-@acronym{ASCII} characters in ++file names are not encoded specially; they appear in the file system ++using the internal Emacs representation. ++ ++ @strong{Warning:} if you change @code{file-name-coding-system} (or the ++language environment) in the middle of an Emacs session, problems can ++result if you have already visited files whose names were encoded using ++the earlier coding system and cannot be encoded (or are encoded ++differently) under the new coding system. If you try to save one of ++these buffers under the visited file name, saving may use the wrong file ++name, or it may get an error. If such a problem happens, use @kbd{C-x ++C-w} to specify a new file name for that buffer. ++ ++@findex recode-file-name ++ If a mistake occurs when encoding a file name, use the command ++@kbd{M-x recode-file-name} to change the file name's coding ++system. This prompts for an existing file name, its old coding ++system, and the coding system to which you wish to convert. ++ ++@node Terminal Coding ++@section Coding Systems for Terminal I/O ++ ++@table @kbd ++@item C-x @key{RET} k @var{coding} @key{RET} ++Use coding system @var{coding} for keyboard input. ++ ++@item C-x @key{RET} t @var{coding} @key{RET} ++Use coding system @var{coding} for terminal output. ++@end table ++ ++@kindex C-x RET t ++@findex set-terminal-coding-system ++ The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system}) ++specifies the coding system for terminal output. If you specify a ++character code for terminal output, all characters output to the ++terminal are translated into that coding system. ++ ++ This feature is useful for certain character-only terminals built to ++support specific languages or character sets---for example, European ++terminals that support one of the ISO Latin character sets. You need to ++specify the terminal coding system when using multibyte text, so that ++Emacs knows which characters the terminal can actually handle. ++ ++ By default, output to the terminal is not translated at all, unless ++Emacs can deduce the proper coding system from your terminal type or ++your locale specification (@pxref{Language Environments}). ++ ++@kindex C-x RET k ++@findex set-keyboard-coding-system ++@vindex keyboard-coding-system ++ The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}) ++or the variable @code{keyboard-coding-system} specifies the coding ++system for keyboard input. Character-code translation of keyboard ++input is useful for terminals with keys that send non-@acronym{ASCII} ++graphic characters---for example, some terminals designed for ISO ++Latin-1 or subsets of it. ++ ++ By default, keyboard input is translated based on your system locale ++setting. If your terminal does not really support the encoding ++implied by your locale (for example, if you find it inserts a ++non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set ++@code{keyboard-coding-system} to @code{nil} to turn off encoding. ++You can do this by putting ++ ++@lisp ++(set-keyboard-coding-system nil) ++@end lisp ++ ++@noindent ++in your init file. ++ ++ There is a similarity between using a coding system translation for ++keyboard input, and using an input method: both define sequences of ++keyboard input that translate into single characters. However, input ++methods are designed to be convenient for interactive use by humans, and ++the sequences that are translated are typically sequences of @acronym{ASCII} ++printing characters. Coding systems typically translate sequences of ++non-graphic characters. ++ ++@node Fontsets ++@section Fontsets ++@cindex fontsets ++ ++ A font typically defines shapes for a single alphabet or script. ++Therefore, displaying the entire range of scripts that Emacs supports ++requires a collection of many fonts. In Emacs, such a collection is ++called a @dfn{fontset}. A fontset is defined by a list of font specs, ++each assigned to handle a range of character codes, and may fall back ++on another fontset for characters which are not covered by the fonts ++it specifies. ++ ++ Each fontset has a name, like a font. However, while fonts are ++stored in the system and the available font names are defined by the ++system, fontsets are defined within Emacs itself. Once you have ++defined a fontset, you can use it within Emacs by specifying its name, ++anywhere that you could use a single font. Of course, Emacs fontsets ++can use only the fonts that the system supports; if certain characters ++appear on the screen as hollow boxes, this means that the fontset in ++use for them has no font for those characters.@footnote{The Emacs ++installation instructions have information on additional font ++support.} ++ ++ Emacs creates three fontsets automatically: the @dfn{standard ++fontset}, the @dfn{startup fontset} and the @dfn{default fontset}. ++The default fontset is most likely to have fonts for a wide variety of ++non-@acronym{ASCII} characters and is the default fallback for the ++other two fontsets, and if you set a default font rather than fontset. ++However it does not specify font family names, so results can be ++somewhat random if you use it directly. You can specify use of a ++specific fontset with the @samp{-fn} option. For example, ++ ++@example ++emacs -fn fontset-standard ++@end example ++ ++@noindent ++You can also specify a fontset with the @samp{Font} resource (@pxref{X ++Resources}). ++ ++ If no fontset is specified for use, then Emacs uses an ++@acronym{ASCII} font, with @samp{fontset-default} as a fallback for ++characters the font does not cover. The standard fontset is only used if ++explicitly requested, despite its name. ++ ++ A fontset does not necessarily specify a font for every character ++code. If a fontset specifies no font for a certain character, or if it ++specifies a font that does not exist on your system, then it cannot ++display that character properly. It will display that character as an ++empty box instead. ++ ++@node Defining Fontsets ++@section Defining fontsets ++ ++@vindex standard-fontset-spec ++@vindex w32-standard-fontset-spec ++@vindex ns-standard-fontset-spec ++@cindex standard fontset ++ When running on X, Emacs creates a standard fontset automatically according to the value ++of @code{standard-fontset-spec}. This fontset's name is ++ ++@example ++-*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard ++@end example ++ ++@noindent ++or just @samp{fontset-standard} for short. ++ ++ On GNUstep and Mac, fontset-standard is created using the value of ++@code{ns-standard-fontset-spec}, and on Windows it is ++created using the value of @code{w32-standard-fontset-spec}. ++ ++ Bold, italic, and bold-italic variants of the standard fontset are ++created automatically. Their names have @samp{bold} instead of ++@samp{medium}, or @samp{i} instead of @samp{r}, or both. ++ ++@cindex startup fontset ++ Emacs generates a fontset automatically, based on any default ++@acronym{ASCII} font that you specify with the @samp{Font} resource or ++the @samp{-fn} argument, or the default font that Emacs found when it ++started. This is the @dfn{startup fontset} and its name is ++@code{fontset-startup}. It does this by replacing the ++@var{charset_registry} field with @samp{fontset}, and replacing ++@var{charset_encoding} field with @samp{startup}, then using the ++resulting string to specify a fontset. ++ ++ For instance, if you start Emacs this way, ++ ++@example ++emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1" ++@end example ++ ++@noindent ++Emacs generates the following fontset and uses it for the initial X ++window frame: ++ ++@example ++-*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup ++@end example ++ ++ The startup fontset will use the font that you specify or a variant ++with a different registry and encoding for all the characters which ++are supported by that font, and fallback on @samp{fontset-default} for ++other characters. ++ ++ With the X resource @samp{Emacs.Font}, you can specify a fontset name ++just like an actual font name. But be careful not to specify a fontset ++name in a wildcard resource like @samp{Emacs*Font}---that wildcard ++specification matches various other resources, such as for menus, and ++menus cannot handle fontsets. ++ ++ You can specify additional fontsets using X resources named ++@samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0. ++The resource value should have this form: ++ ++@smallexample ++@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}} ++@end smallexample ++ ++@noindent ++@var{fontpattern} should have the form of a standard X font name, except ++for the last two fields. They should have the form ++@samp{fontset-@var{alias}}. ++ ++ The fontset has two names, one long and one short. The long name is ++@var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You ++can refer to the fontset by either name. ++ ++ The construct @samp{@var{charset}:@var{font}} specifies which font to ++use (in this fontset) for one particular character set. Here, ++@var{charset} is the name of a character set, and @var{font} is the ++font to use for that character set. You can use this construct any ++number of times in defining one fontset. ++ ++ For the other character sets, Emacs chooses a font based on ++@var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values ++that describe the character set. For the @acronym{ASCII} character font, ++@samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}. ++ ++ In addition, when several consecutive fields are wildcards, Emacs ++collapses them into a single wildcard. This is to prevent use of ++auto-scaled fonts. Fonts made by scaling larger fonts are not usable ++for editing, and scaling a smaller font is not useful because it is ++better to use the smaller font in its own size, which is what Emacs ++does. ++ ++ Thus if @var{fontpattern} is this, ++ ++@example ++-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 ++@end example ++ ++@noindent ++the font specification for @acronym{ASCII} characters would be this: ++ ++@example ++-*-fixed-medium-r-normal-*-24-*-ISO8859-1 ++@end example ++ ++@noindent ++and the font specification for Chinese GB2312 characters would be this: ++ ++@example ++-*-fixed-medium-r-normal-*-24-*-gb2312*-* ++@end example ++ ++ You may not have any Chinese font matching the above font ++specification. Most X distributions include only Chinese fonts that ++have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In ++such a case, @samp{Fontset-@var{n}} can be specified as below: ++ ++@smallexample ++Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ ++ chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* ++@end smallexample ++ ++@noindent ++Then, the font specifications for all but Chinese GB2312 characters have ++@samp{fixed} in the @var{family} field, and the font specification for ++Chinese GB2312 characters has a wild card @samp{*} in the @var{family} ++field. ++ ++@findex create-fontset-from-fontset-spec ++ The function that processes the fontset resource value to create the ++fontset is called @code{create-fontset-from-fontset-spec}. You can also ++call this function explicitly to create a fontset. ++ ++ @xref{Font X}, for more information about font naming in X. ++ ++@node Modifying Fontsets ++@section Modifying Fontsets ++@cindex fontsets, modifying ++@findex set-fontset-font ++ ++ Fontsets do not always have to be created from scratch. If only ++minor changes are required it may be easier to modify an existing ++fontset. Modifying @samp{fontset-default} will also affect other ++fontsets that use it as a fallback, so can be an effective way of ++fixing problems with the fonts that Emacs chooses for a particular ++script. ++ ++Fontsets can be modified using the function @code{set-fontset-font}, ++specifying a character, a charset, a script, or a range of characters ++to modify the font for, and a font-spec for the font to be used. Some ++examples are: ++ ++@example ++;; Use Liberation Mono for latin-3 charset. ++(set-fontset-font "fontset-default" 'iso-8859-3 "Liberation Mono") ++ ++;; Prefer a big5 font for han characters ++(set-fontset-font "fontset-default" 'han (font-spec :registry "big5") ++ nil 'prepend) ++ ++;; Use DejaVu Sans Mono as a fallback in fontset-startup before ++;; resorting to fontset-default. ++(set-fontset-font "fontset-startup" nil "DejaVu Sans Mono" nil 'append) ++ ++;; Use MyPrivateFont for the Unicode private use area. ++(set-fontset-font "fontset-default" '(#xe000 . #xf8ff) "MyPrivateFont") ++ ++@end example ++ ++ ++@node Undisplayable Characters ++@section Undisplayable Characters ++ ++ There may be a some non-@acronym{ASCII} characters that your terminal cannot ++display. Most text-only terminals support just a single character ++set (use the variable @code{default-terminal-coding-system} ++(@pxref{Terminal Coding}) to tell Emacs which one); characters which ++can't be encoded in that coding system are displayed as @samp{?} by ++default. ++ ++ Graphical displays can display a broader range of characters, but ++you may not have fonts installed for all of them; characters that have ++no font appear as a hollow box. ++ ++ If you use Latin-1 characters but your terminal can't display ++Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences ++instead, e.g.@: @samp{"o} for o-umlaut. Load the library ++@file{iso-ascii} to do this. ++ ++@vindex latin1-display ++ If your terminal can display Latin-1, you can display characters ++from other European character sets using a mixture of equivalent ++Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable ++@code{latin1-display} to enable this. The mnemonic @acronym{ASCII} ++sequences mostly correspond to those of the prefix input methods. ++ ++@node Unibyte Mode ++@section Unibyte Editing Mode ++ ++@cindex European character sets ++@cindex accented characters ++@cindex ISO Latin character sets ++@cindex Unibyte operation ++ The ISO 8859 Latin-@var{n} character sets define character codes in ++the range 0240 to 0377 octal (160 to 255 decimal) to handle the ++accented letters and punctuation needed by various European languages ++(and some non-European ones). If you disable multibyte characters, ++Emacs can still handle @emph{one} of these character codes at a time. ++To specify @emph{which} of these codes to use, invoke @kbd{M-x ++set-language-environment} and specify a suitable language environment ++such as @samp{Latin-@var{n}}. ++ ++ For more information about unibyte operation, see @ref{Enabling ++Multibyte}. Note particularly that you probably want to ensure that ++your initialization files are read as unibyte if they contain ++non-@acronym{ASCII} characters. ++ ++@vindex unibyte-display-via-language-environment ++ Emacs can also display those characters, provided the terminal or font ++in use supports them. This works automatically. Alternatively, on a ++graphical display, Emacs can also display single-byte characters ++through fontsets, in effect by displaying the equivalent multibyte ++characters according to the current language environment. To request ++this, set the variable @code{unibyte-display-via-language-environment} ++to a non-@code{nil} value. ++ ++@cindex @code{iso-ascii} library ++ If your terminal does not support display of the Latin-1 character ++set, Emacs can display these characters as @acronym{ASCII} sequences which at ++least give you a clear idea of what the characters are. To do this, ++load the library @code{iso-ascii}. Similar libraries for other ++Latin-@var{n} character sets could be implemented, but we don't have ++them yet. ++ ++@findex standard-display-8bit ++@cindex 8-bit display ++ Normally non-ISO-8859 characters (decimal codes between 128 and 159 ++inclusive) are displayed as octal escapes. You can change this for ++non-standard ``extended'' versions of ISO-8859 character sets by using the ++function @code{standard-display-8bit} in the @code{disp-table} library. ++ ++ There are two ways to input single-byte non-@acronym{ASCII} ++characters: ++ ++@itemize @bullet ++@cindex 8-bit input ++@item ++You can use an input method for the selected language environment. ++@xref{Input Methods}. When you use an input method in a unibyte buffer, ++the non-@acronym{ASCII} character you specify with it is converted to unibyte. ++ ++@item ++If your keyboard can generate character codes 128 (decimal) and up, ++representing non-@acronym{ASCII} characters, you can type those character codes ++directly. ++ ++On a graphical display, you should not need to do anything special to use ++these keys; they should simply work. On a text-only terminal, you ++should use the command @code{M-x set-keyboard-coding-system} or the ++variable @code{keyboard-coding-system} to specify which coding system ++your keyboard uses (@pxref{Terminal Coding}). Enabling this feature ++will probably require you to use @kbd{ESC} to type Meta characters; ++however, on a console terminal or in @code{xterm}, you can arrange for ++Meta to be converted to @kbd{ESC} and still be able type 8-bit ++characters present directly on the keyboard or using @kbd{Compose} or ++@kbd{AltGr} keys. @xref{User Input}. ++ ++@kindex C-x 8 ++@cindex @code{iso-transl} library ++@cindex compose character ++@cindex dead character ++@item ++For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose ++character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing ++characters. @kbd{C-x 8} is good for insertion (in the minibuffer as ++well as other buffers), for searching, and in any other context where ++a key sequence is allowed. ++ ++@kbd{C-x 8} works by loading the @code{iso-transl} library. Once that ++library is loaded, the @key{ALT} modifier key, if the keyboard has ++one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together ++with an accent character to modify the following letter. In addition, ++if the keyboard has keys for the Latin-1 ``dead accent characters,'' ++they too are defined to compose with the following character, once ++@code{iso-transl} is loaded. ++ ++Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations. ++@end itemize ++ ++@node Charsets ++@section Charsets ++@cindex charsets ++ ++ Emacs defines most of popular character sets (e.g. ascii, ++iso-8859-1, cp1250, big5, unicode) as @dfn{charsets} and a few of its ++own charsets (e.g. emacs, unicode-bmp, eight-bit). All supported ++characters belong to one or more charsets. Usually you don't have to ++take care of ``charset'', but knowing about it may help understanding ++the behavior of Emacs in some cases. ++ ++ One example is a font selection. In each language environment, ++charsets have different priorities. Emacs, at first, tries to use a ++font that matches with charsets of higher priority. For instance, in ++Japanese language environment, the charset @code{japanese-jisx0208} ++has the highest priority (@pxref{Describe Language Environment}). So, ++Emacs tries to use a font whose @code{registry} property is ++``JISX0208.1983-0'' for characters belonging to that charset. ++ ++ Another example is a use of @code{charset} text property. When ++Emacs reads a file encoded in a coding systems that uses escape ++sequences to switch charsets (e.g. iso-2022-int-1), the buffer text ++keep the information of the original charset by @code{charset} text ++property. By using this information, Emacs can write the file with ++the same byte sequence as the original. ++ ++@findex list-charset-chars ++@cindex characters in a certain charset ++@findex describe-character-set ++ There are two commands for obtaining information about Emacs ++charsets. The command @kbd{M-x list-charset-chars} prompts for a ++charset name, and displays all the characters in that character set. ++The command @kbd{M-x describe-character-set} prompts for a charset ++name and displays information about that charset, including its ++internal representation within Emacs. ++ ++@findex list-character-sets ++ To display a list of all the supported charsets, type @kbd{M-x ++list-character-sets}. The list gives the names of charsets and ++additional information to identity each charset (see ISO/IEC's this ++page for the detail). In the ++list, charsets are categorized into two; the normal charsets are ++listed first, and the supplementary charsets are listed last. A ++charset in the latter category is used for defining another charset ++(as a parent or a subset), or was used only in Emacs of the older ++versions. ++ ++ To find out which charset a character in the buffer belongs to, ++put point before it and type @kbd{C-u C-x =}. ++ ++@ignore ++ arch-tag: 310ba60d-31ef-4ce7-91f1-f282dd57b6b3 ++@end ignore +diff --git a/doc/emacs/picture-xtra.texi b/doc/emacs/picture-xtra.texi +new file mode 100644 +index 0000000..64476b6 +--- /dev/null ++++ b/doc/emacs/picture-xtra.texi +@@ -0,0 +1,291 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@c This file is included either in emacs-xtra.texi (when producing the ++@c printed version) or in the main Emacs manual (for the on-line version). ++@node Picture Mode ++@chapter Editing Pictures ++@cindex pictures ++@cindex making pictures out of text characters ++@findex picture-mode ++ ++ To edit a picture made out of text characters (for example, a picture ++of the division of a register into fields, as a comment in a program), ++use the command @kbd{M-x picture-mode} to enter Picture mode. ++ ++ In Picture mode, editing is based on the @dfn{quarter-plane} model of ++text, according to which the text characters lie studded on an area that ++stretches infinitely far to the right and downward. The concept of the end ++of a line does not exist in this model; the most you can say is where the ++last nonblank character on the line is found. ++ ++ Of course, Emacs really always considers text as a sequence of ++characters, and lines really do have ends. But Picture mode replaces ++the most frequently-used commands with variants that simulate the ++quarter-plane model of text. They do this by inserting spaces or by ++converting tabs to spaces. ++ ++ Most of the basic editing commands of Emacs are redefined by Picture mode ++to do essentially the same thing but in a quarter-plane way. In addition, ++Picture mode defines various keys starting with the @kbd{C-c} prefix to ++run special picture editing commands. ++ ++ One of these keys, @kbd{C-c C-c}, is particularly important. Often ++a picture is part of a larger file that is usually edited in some ++other major mode. Picture mode records the name of the previous major ++mode so you can use the @kbd{C-c C-c} command ++(@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c ++C-c} also deletes spaces from the ends of lines, unless given a ++numeric argument. ++ ++ The special commands of Picture mode all work in other modes (provided ++the @file{picture} library is loaded), but are not bound to keys except ++in Picture mode. The descriptions below talk of moving ``one column'' ++and so on, but all the picture mode commands handle numeric arguments as ++their normal equivalents do. ++ ++@vindex picture-mode-hook ++ Turning on Picture mode runs the hook @code{picture-mode-hook}. ++Additional extensions to Picture mode can be found in ++@file{artist.el}. ++ ++@menu ++* Basic Picture:: Basic concepts and simple commands of Picture Mode. ++* Insert in Picture:: Controlling direction of cursor motion ++ after "self-inserting" characters. ++* Tabs in Picture:: Various features for tab stops and indentation. ++* Rectangles in Picture:: Clearing and superimposing rectangles. ++@end menu ++ ++@node Basic Picture ++@section Basic Editing in Picture Mode ++ ++@findex picture-forward-column ++@findex picture-backward-column ++@findex picture-move-down ++@findex picture-move-up ++@cindex editing in Picture mode ++ ++ Most keys do the same thing in Picture mode that they usually do, but ++do it in a quarter-plane style. For example, @kbd{C-f} is rebound to ++run @code{picture-forward-column}, a command which moves point one ++column to the right, inserting a space if necessary so that the actual ++end of the line makes no difference. @kbd{C-b} is rebound to run ++@code{picture-backward-column}, which always moves point left one ++column, converting a tab to multiple spaces if necessary. @kbd{C-n} and ++@kbd{C-p} are rebound to run @code{picture-move-down} and ++@code{picture-move-up}, which can either insert spaces or convert tabs ++as necessary to make sure that point stays in exactly the same column. ++@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last ++nonblank character on the line. There is no need to change @kbd{C-a}, ++as the choice of screen model does not affect beginnings of ++lines. ++ ++@findex picture-newline ++ Insertion of text is adapted to the quarter-plane screen model ++through the use of Overwrite mode ++@iftex ++(@pxref{Minor Modes,,, emacs, the Emacs Manual}.) ++@end iftex ++@ifnottex ++(@pxref{Minor Modes}.) ++@end ifnottex ++Self-inserting characters replace existing text, column by column, ++rather than pushing existing text to the right. @key{RET} runs ++@code{picture-newline}, which just moves to the beginning of the ++following line so that new text will replace that line. ++ ++@findex picture-backward-clear-column ++@findex picture-clear-column ++@findex picture-clear-line ++ In Picture mode, the commands that normally delete or kill text, ++instead erase text (replacing it with spaces). @key{DEL} ++(@code{picture-backward-clear-column}) replaces the preceding ++character with a space rather than removing it; this moves point ++backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the next ++character or characters with spaces, but does not move point. (If you ++want to clear characters to spaces and move forward over them, use ++@key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the ++contents of lines, but does not delete the newlines from the buffer. ++ ++@findex picture-open-line ++ To do actual insertion, you must use special commands. @kbd{C-o} ++(@code{picture-open-line}) creates a blank line after the current ++line; it never splits a line. @kbd{C-M-o} (@code{split-line}) makes ++sense in Picture mode, so it is not changed. @kbd{C-j} ++(@code{picture-duplicate-line}) inserts another line with the same ++contents below the current line. ++ ++@kindex C-c C-d @r{(Picture mode)} ++ To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d} ++(which is defined as @code{delete-char}, as @kbd{C-d} is in other ++modes), or one of the picture rectangle commands (@pxref{Rectangles in ++Picture}). ++ ++@node Insert in Picture ++@section Controlling Motion after Insert ++ ++@findex picture-movement-up ++@findex picture-movement-down ++@findex picture-movement-left ++@findex picture-movement-right ++@findex picture-movement-nw ++@findex picture-movement-ne ++@findex picture-movement-sw ++@findex picture-movement-se ++@kindex C-c < @r{(Picture mode)} ++@kindex C-c > @r{(Picture mode)} ++@kindex C-c ^ @r{(Picture mode)} ++@kindex C-c . @r{(Picture mode)} ++@kindex C-c ` @r{(Picture mode)} ++@kindex C-c ' @r{(Picture mode)} ++@kindex C-c / @r{(Picture mode)} ++@kindex C-c \ @r{(Picture mode)} ++ Since ``self-inserting'' characters in Picture mode overwrite and move ++point, there is no essential restriction on how point should be moved. ++Normally point moves right, but you can specify any of the eight ++orthogonal or diagonal directions for motion after a ``self-inserting'' ++character. This is useful for drawing lines in the buffer. ++ ++@table @kbd ++@item C-c < ++@itemx C-c @key{LEFT} ++Move left after insertion (@code{picture-movement-left}). ++@item C-c > ++@itemx C-c @key{RIGHT} ++Move right after insertion (@code{picture-movement-right}). ++@item C-c ^ ++@itemx C-c @key{UP} ++Move up after insertion (@code{picture-movement-up}). ++@item C-c . ++@itemx C-c @key{DOWN} ++Move down after insertion (@code{picture-movement-down}). ++@item C-c ` ++@itemx C-c @key{HOME} ++Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). ++@item C-c ' ++@itemx C-c @key{prior} ++Move up and right (``northeast'') after insertion ++(@code{picture-movement-ne}). ++@item C-c / ++@itemx C-c @key{END} ++Move down and left (``southwest'') after insertion ++@*(@code{picture-movement-sw}). ++@item C-c \ ++@itemx C-c @key{next} ++Move down and right (``southeast'') after insertion ++@*(@code{picture-movement-se}). ++@end table ++ ++@kindex C-c C-f @r{(Picture mode)} ++@kindex C-c C-b @r{(Picture mode)} ++@findex picture-motion ++@findex picture-motion-reverse ++ Two motion commands move based on the current Picture insertion ++direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the ++same direction as motion after ``insertion'' currently does, while @kbd{C-c ++C-b} (@code{picture-motion-reverse}) moves in the opposite direction. ++ ++@node Tabs in Picture ++@section Picture Mode Tabs ++ ++@kindex M-TAB @r{(Picture mode)} ++@findex picture-tab-search ++@vindex picture-tab-chars ++ Two kinds of tab-like action are provided in Picture mode. Use ++@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing. ++With no argument, it moves to a point underneath the next ++``interesting'' character that follows whitespace in the previous ++nonblank line. ``Next'' here means ``appearing at a horizontal position ++greater than the one point starts out at.'' With an argument, as in ++@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting ++character in the current line. @kbd{M-@key{TAB}} does not change the ++text; it only moves point. ``Interesting'' characters are defined by ++the variable @code{picture-tab-chars}, which should define a set of ++characters. The syntax for this variable is like the syntax used inside ++of @samp{[@dots{}]} in a regular expression---but without the @samp{[} ++and the @samp{]}. Its default value is @code{"!-~"}. ++ ++@findex picture-tab ++ @key{TAB} itself runs @code{picture-tab}, which operates based on the ++current tab stop settings; it is the Picture mode equivalent of ++@code{tab-to-tab-stop}. Normally it just moves point, but with a numeric ++argument it clears the text that it moves over. ++ ++@kindex C-c TAB @r{(Picture mode)} ++@findex picture-set-tab-stops ++ The context-based and tab-stop-based forms of tabbing are brought ++together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}). ++This command sets the tab stops to the positions which @kbd{M-@key{TAB}} ++would consider significant in the current line. The use of this command, ++together with @key{TAB}, can get the effect of context-based tabbing. But ++@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. ++ ++ It may be convenient to prevent use of actual tab characters in ++pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing ++up the picture. You can do this by setting the variable ++@code{indent-tabs-mode} to @code{nil}. ++ ++@node Rectangles in Picture ++@section Picture Mode Rectangle Commands ++@cindex rectangles and Picture mode ++@cindex Picture mode and rectangles ++ ++ Picture mode defines commands for working on rectangular pieces of ++the text in ways that fit with the quarter-plane model. The standard ++rectangle commands may also be useful. ++@iftex ++@xref{Rectangles,,, emacs, the Emacs Manual}. ++@end iftex ++@ifnottex ++@xref{Rectangles}. ++@end ifnottex ++ ++@table @kbd ++@item C-c C-k ++Clear out the region-rectangle with spaces ++(@code{picture-clear-rectangle}). With argument, delete the text. ++@item C-c C-w @var{r} ++Similar, but save rectangle contents in register @var{r} first ++(@code{picture-clear-rectangle-to-register}). ++@item C-c C-y ++Copy last killed rectangle into the buffer by overwriting, with upper ++left corner at point (@code{picture-yank-rectangle}). With argument, ++insert instead. ++@item C-c C-x @var{r} ++Similar, but use the rectangle in register @var{r} ++(@code{picture-yank-rectangle-from-register}). ++@end table ++ ++@kindex C-c C-k @r{(Picture mode)} ++@kindex C-c C-w @r{(Picture mode)} ++@findex picture-clear-rectangle ++@findex picture-clear-rectangle-to-register ++ The picture rectangle commands @kbd{C-c C-k} ++(@code{picture-clear-rectangle}) and @kbd{C-c C-w} ++(@code{picture-clear-rectangle-to-register}) differ from the standard ++rectangle commands in that they normally clear the rectangle instead of ++deleting it; this is analogous with the way @kbd{C-d} is changed in Picture ++mode. ++ ++ However, deletion of rectangles can be useful in Picture mode, so ++these commands delete the rectangle if given a numeric argument. ++@kbd{C-c C-k} either with or without a numeric argument saves the ++rectangle for @kbd{C-c C-y}. ++ ++@kindex C-c C-y @r{(Picture mode)} ++@kindex C-c C-x @r{(Picture mode)} ++@findex picture-yank-rectangle ++@findex picture-yank-rectangle-from-register ++ The Picture mode commands for yanking rectangles differ from the ++standard ones in that they overwrite instead of inserting. This is ++the same way that Picture mode insertion of other text differs from ++other modes. @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts ++(by overwriting) the rectangle that was most recently killed, while ++@kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does ++likewise for the rectangle found in a specified register. ++ ++@ignore ++ arch-tag: 10e423ad-d896-42f2-a7e8-7018adeaf8c2 ++@end ignore +diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi +new file mode 100644 +index 0000000..14db827 +--- /dev/null ++++ b/doc/emacs/programs.texi +@@ -0,0 +1,1775 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, ++@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Programs, Building, Text, Top ++@chapter Editing Programs ++@cindex Lisp editing ++@cindex C editing ++@cindex program editing ++ ++ Emacs provides many features to facilitate editing programs. Some ++of these features can ++ ++@itemize @bullet ++@item ++Find or move over top-level definitions (@pxref{Defuns}). ++@item ++Apply the usual indentation conventions of the language ++(@pxref{Program Indent}). ++@item ++Balance parentheses (@pxref{Parentheses}). ++@item ++Insert, kill or align comments (@pxref{Comments}). ++@item ++Highlight program syntax (@pxref{Font Lock}). ++@end itemize ++ ++ This chapter describes these features and many more. ++ ++@menu ++* Program Modes:: Major modes for editing programs. ++* Defuns:: Commands to operate on major top-level parts ++ of a program. ++* Program Indent:: Adjusting indentation to show the nesting. ++* Parentheses:: Commands that operate on parentheses. ++* Comments:: Inserting, killing, and aligning comments. ++* Documentation:: Getting documentation of functions you plan to call. ++* Hideshow:: Displaying blocks selectively. ++* Symbol Completion:: Completion on symbol names of your program or language. ++* Glasses:: Making identifiersLikeThis more readable. ++* Misc for Programs:: Other Emacs features useful for editing programs. ++* C Modes:: Special commands of C, C++, Objective-C, ++ Java, and Pike modes. ++* Asm Mode:: Asm mode and its special features. ++@ifnottex ++* Fortran:: Fortran mode and its special features. ++@end ifnottex ++@end menu ++ ++@node Program Modes ++@section Major Modes for Programming Languages ++@cindex modes for programming languages ++ ++ Emacs has specialized major modes for various programming languages. ++@xref{Major Modes}. A programming language major mode typically ++specifies the syntax of expressions, the customary rules for ++indentation, how to do syntax highlighting for the language, and how ++to find the beginning or end of a function definition. It often ++customizes or provides facilities for compiling and debugging programs ++as well. ++ ++ Ideally, Emacs should provide a major mode for each programming ++language that you might want to edit; if it doesn't have a mode for ++your favorite language, you can contribute one. But often the mode ++for one language can serve for other syntactically similar languages. ++The major mode for language @var{l} is called @code{@var{l}-mode}, ++and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. ++@xref{Choosing Modes}. ++ ++@cindex Perl mode ++@cindex Icon mode ++@cindex Makefile mode ++@cindex Tcl mode ++@cindex CPerl mode ++@cindex DSSSL mode ++@cindex Octave mode ++@cindex Metafont mode ++@cindex Modula2 mode ++@cindex Prolog mode ++@cindex Python mode ++@cindex Ruby mode ++@cindex Simula mode ++@cindex VHDL mode ++@cindex M4 mode ++@cindex Shell-script mode ++@cindex Delphi mode ++@cindex PostScript mode ++@cindex Conf mode ++@cindex DNS mode ++ The existing programming language major modes include Lisp, Scheme ++(a variant of Lisp) and the Scheme-based DSSSL expression language, ++Ada, ASM, AWK, C, C++, Delphi (Object Pascal), Fortran, Icon, IDL ++(CORBA), IDLWAVE, Java, Metafont (@TeX{}'s companion for font ++creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike, ++PostScript, Prolog, Python, Ruby, Simula, Tcl, and VHDL. An ++alternative mode for Perl is called CPerl mode. Modes are available ++for the scripting languages of the common GNU and Unix shells, VMS ++DCL, and MS-DOS/MS-Windows @samp{BAT} files. There are also major ++modes for editing makefiles, DNS master files, and various sorts of ++configuration files. ++ ++@kindex DEL @r{(programming modes)} ++@findex c-electric-backspace ++ In most programming languages, indentation should vary from line to ++line to illustrate the structure of the program. So the major modes ++for programming languages arrange for @key{TAB} to update the ++indentation of the current line (@pxref{Program Indent}). They also ++rebind @key{DEL} to treat a tab as if it were the equivalent number of ++spaces; this lets you delete one column of indentation without ++worrying whether the whitespace consists of spaces or tabs. Use ++@kbd{C-b C-d} to delete a tab character before point, in these modes. ++ ++ Separate manuals are available for the modes for Ada (@pxref{Top, , Ada ++Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK ++(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes ++(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran ++mode, see ++@iftex ++@ref{Fortran,,, emacs-xtra, Specialized Emacs Features}. ++@end iftex ++@ifnottex ++@ref{Fortran}. ++@end ifnottex ++ ++@cindex mode hook ++@vindex c-mode-hook ++@vindex lisp-mode-hook ++@vindex emacs-lisp-mode-hook ++@vindex lisp-interaction-mode-hook ++@vindex scheme-mode-hook ++ Turning on a major mode runs a normal hook called the @dfn{mode ++hook}, which is the value of a Lisp variable. Each major mode has a ++mode hook, and the hook's name is always made from the mode command's ++name by adding @samp{-hook}. For example, turning on C mode runs the ++hook @code{c-mode-hook}, while turning on Lisp mode runs the hook ++@code{lisp-mode-hook}. The purpose of the mode hook is to give you a ++place to set up customizations for that major mode. @xref{Hooks}. ++ ++@node Defuns ++@section Top-Level Definitions, or Defuns ++ ++ In Emacs, a major definition at the top level in the buffer, such as ++a function, is called a @dfn{defun}. The name comes from Lisp, but in ++Emacs we use it for all languages. ++ ++@menu ++* Left Margin Paren:: An open-paren or similar opening delimiter ++ starts a defun if it is at the left margin. ++* Moving by Defuns:: Commands to move over or mark a major definition. ++* Imenu:: Making buffer indexes as menus. ++* Which Function:: Which Function mode shows which function you are in. ++@end menu ++ ++@node Left Margin Paren ++@subsection Left Margin Convention ++ ++@cindex open-parenthesis in leftmost column ++@cindex ( in leftmost column ++ Many programming-language modes assume by default that any opening ++delimiter found at the left margin is the start of a top-level ++definition, or defun. Therefore, @strong{don't put an opening ++delimiter at the left margin unless it should have that significance}. ++For instance, never put an open-parenthesis at the left margin in a ++Lisp file unless it is the start of a top-level list. ++ ++ The convention speeds up many Emacs operations, which would ++otherwise have to scan back to the beginning of the buffer to analyze ++the syntax of the code. ++ ++ If you don't follow this convention, not only will you have trouble ++when you explicitly use the commands for motion by defuns; other ++features that use them will also give you trouble. This includes the ++indentation commands (@pxref{Program Indent}) and Font Lock mode ++(@pxref{Font Lock}). ++ ++ The most likely problem case is when you want an opening delimiter ++at the start of a line inside a string. To avoid trouble, put an ++escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some ++other Lisp dialects) before the opening delimiter. This will not ++affect the contents of the string, but will prevent that opening ++delimiter from starting a defun. Here's an example: ++ ++@example ++ (insert "Foo: ++\(bar) ++") ++@end example ++ ++ To help you catch violations of this convention, Font Lock mode ++highlights confusing opening delimiters (those that ought to be ++quoted) in bold red. ++ ++ If you need to override this convention, you can do so by setting ++this user option: ++ ++@defvar open-paren-in-column-0-is-defun-start ++If this user option is set to @code{t} (the default), opening ++parentheses or braces at column zero always start defuns. When it's ++@code{nil}, defuns are found by searching for parens or braces at the ++outermost level. ++@end defvar ++ ++ Usually, you should leave this option at its default value of ++@code{t}. If your buffer contains parentheses or braces in column ++zero which don't start defuns, and it is somehow impractical to remove ++these parentheses or braces, it might be helpful to set the option to ++@code{nil}. Be aware that this might make scrolling and display in ++large buffers quite sluggish. Furthermore, the parentheses and braces ++must be correctly matched throughout the buffer for it to work ++properly. ++ ++@node Moving by Defuns ++@subsection Moving by Defuns ++@cindex defuns ++ ++ These commands move point or set up the region based on top-level ++major definitions, also called @dfn{defuns}. ++ ++@table @kbd ++@item C-M-a ++Move to beginning of current or preceding defun ++(@code{beginning-of-defun}). ++@item C-M-e ++Move to end of current or following defun (@code{end-of-defun}). ++@item C-M-h ++Put region around whole current or following defun (@code{mark-defun}). ++@end table ++ ++@cindex move to beginning or end of function ++@cindex function, move to beginning or end ++@kindex C-M-a ++@kindex C-M-e ++@kindex C-M-h ++@findex beginning-of-defun ++@findex end-of-defun ++@findex mark-defun ++ The commands to move to the beginning and end of the current defun ++are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} ++(@code{end-of-defun}). If you repeat one of these commands, or use a ++positive numeric argument, each repetition moves to the next defun in ++the direction of motion. ++ ++ @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward ++@var{n} times to the next beginning of a defun. This is not exactly ++the same place that @kbd{C-M-e} with argument @var{n} would move to; ++the end of this defun is not usually exactly the same place as the ++beginning of the following defun. (Whitespace, comments, and perhaps ++declarations can separate them.) Likewise, @kbd{C-M-e} with a ++negative argument moves back to an end of a defun, which is not quite ++the same as @kbd{C-M-a} with a positive argument. ++ ++@kindex C-M-h @r{(C mode)} ++@findex c-mark-function ++ To operate on the current defun, use @kbd{C-M-h} ++(@code{mark-defun}), which sets the mark at the end of the current ++defun and puts point at its beginning. @xref{Marking Objects}. This ++is the easiest way to get ready to kill the defun in order to move it ++to a different place in the file. If you use the command while point ++is between defuns, it uses the following defun. If you use the ++command while the mark is already active, it sets the mark but does ++not move point; furthermore, each successive use of @kbd{C-M-h} ++extends the end of the region to include one more defun. ++ ++ In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, ++which is almost the same as @code{mark-defun}; the difference is that ++it backs up over the argument declarations, function name and returned ++data type so that the entire C function is inside the region. This is ++an example of how major modes adjust the standard key bindings so that ++they do their standard jobs in a way better fitting a particular ++language. Other major modes may replace any or all of these key ++bindings for that purpose. ++ ++@node Imenu ++@subsection Imenu ++@cindex index of buffer definitions ++@cindex buffer definitions index ++ ++ The Imenu facility offers a way to find the major definitions in ++a file by name. It is also useful in text formatter major modes, ++where it treats each chapter, section, etc., as a definition. ++(@xref{Tags}, for a more powerful feature that handles multiple files ++together.) ++ ++@findex imenu ++ If you type @kbd{M-x imenu}, it reads the name of a definition using ++the minibuffer, then moves point to that definition. You can use ++completion to specify the name; the command always displays the whole ++list of valid names. ++ ++@findex imenu-add-menubar-index ++ Alternatively, you can bind the command @code{imenu} to a mouse ++click. Then it displays mouse menus for you to select a definition ++name. You can also add the buffer's index to the menu bar by calling ++@code{imenu-add-menubar-index}. If you want to have this menu bar ++item available for all buffers in a certain major mode, you can do ++this by adding @code{imenu-add-menubar-index} to its mode hook. But ++if you have done that, you will have to wait a little while each time ++you visit a file in that mode, while Emacs finds all the definitions ++in that buffer. ++ ++@vindex imenu-auto-rescan ++ When you change the contents of a buffer, if you add or delete ++definitions, you can update the buffer's index based on the ++new contents by invoking the @samp{*Rescan*} item in the menu. ++Rescanning happens automatically if you set @code{imenu-auto-rescan} to ++a non-@code{nil} value. There is no need to rescan because of small ++changes in the text. ++ ++@vindex imenu-sort-function ++ You can customize the way the menus are sorted by setting the ++variable @code{imenu-sort-function}. By default, names are ordered as ++they occur in the buffer; if you want alphabetic sorting, use the ++symbol @code{imenu--sort-by-name} as the value. You can also ++define your own comparison function by writing Lisp code. ++ ++ Imenu provides the information to guide Which Function mode ++@ifnottex ++(@pxref{Which Function}). ++@end ifnottex ++@iftex ++(see below). ++@end iftex ++The Speedbar can also use it (@pxref{Speedbar}). ++ ++@node Which Function ++@subsection Which Function Mode ++@cindex current function name in mode line ++ ++ Which Function mode is a minor mode that displays the current ++function name in the mode line, updating it as you move around in a ++buffer. ++ ++@findex which-function-mode ++@vindex which-func-modes ++ To either enable or disable Which Function mode, use the command ++@kbd{M-x which-function-mode}. This command applies to all buffers, ++both existing ones and those yet to be created. However, it takes ++effect only in certain major modes, those listed in the value of ++@code{which-func-modes}. If the value of @code{which-func-modes} is ++@code{t} rather than a list of modes, then Which Function mode applies ++to all major modes that know how to support it---in other words, all ++the major modes that support Imenu. ++ ++@node Program Indent ++@section Indentation for Programs ++@cindex indentation for programs ++ ++ The best way to keep a program properly indented is to use Emacs to ++reindent it as you change it. Emacs has commands to indent either a ++single line, a specified number of lines, or all of the lines inside a ++single parenthetical grouping. ++ ++@menu ++* Basic Indent:: Indenting a single line. ++* Multi-line Indent:: Commands to reindent many lines at once. ++* Lisp Indent:: Specifying how each Lisp function should be indented. ++* C Indent:: Extra features for indenting C and related modes. ++* Custom C Indent:: Controlling indentation style for C and related modes. ++@end menu ++ ++@cindex pretty-printer ++ Emacs also provides a Lisp pretty-printer in the library @code{pp}. ++This program reformats a Lisp object with indentation chosen to look nice. ++ ++@node Basic Indent ++@subsection Basic Program Indentation Commands ++ ++ The basic indentation commands indent a single line according to the ++usual conventions of the language you are editing. ++ ++@table @kbd ++@item @key{TAB} ++Adjust indentation of current line. ++@item C-j ++Insert a newline, then adjust indentation of following line ++(@code{newline-and-indent}). ++@end table ++ ++@kindex TAB @r{(programming modes)} ++@findex c-indent-command ++@findex indent-line-function ++@findex indent-for-tab-command ++ The basic indentation command is @key{TAB}. In any ++programming-language major mode, @key{TAB} gives the current line the ++correct indentation as determined from the previous lines. It does ++this by inserting or deleting whitespace at the beginning of the ++current line. If point was inside the whitespace at the beginning of ++the line, @key{TAB} puts it at the end of that whitespace; otherwise, ++@key{TAB} keeps point fixed with respect to the characters around it. ++If the region is active (@pxref{Mark}), @key{TAB} indents every line ++within the region instead of just the current line. The function that ++@key{TAB} runs depends on the major mode; for instance, it is ++@code{c-indent-line-or-region} in C mode. Each function is aware of ++the syntax and conventions for its particular language. ++ ++ Use @kbd{C-q @key{TAB}} to insert a tab character at point. ++ ++@kindex C-j ++@findex newline-and-indent ++ When entering lines of new code, use @kbd{C-j} ++(@code{newline-and-indent}), which inserts a newline and then adjusts ++indentation after it. (It also deletes any trailing whitespace which ++remains before the new newline.) For instance, @kbd{C-j} at the end ++of a line creates a blank line with appropriate indentation. In ++programming language modes, it is equivalent to @key{RET} @key{TAB}. ++ ++ When Emacs indents a line that starts within a parenthetical ++grouping, it usually places the start of the line under the preceding ++line within the group, or under the text after the parenthesis. If ++you manually give one of these lines a nonstandard indentation, the ++lines below will tend to follow it. This behavior is convenient in ++cases where you have overridden the standard result of @key{TAB} ++indentation (e.g., for aesthetic purposes). ++ ++ Many programming-language modes assume that an open-parenthesis, ++open-brace or other opening delimiter at the left margin is the start ++of a function. This assumption speeds up indentation commands. If ++the text you are editing contains opening delimiters in column zero ++that aren't the beginning of a functions---even if these delimiters ++occur inside strings or comments---then you must set ++@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin ++Paren}. ++ ++ Normally, Emacs indents lines using an ``optimal'' mix of tab and ++space characters. If you want Emacs to use spaces only, set ++@code{indent-tabs-mode} (@pxref{Just Spaces}). ++ ++@node Multi-line Indent ++@subsection Indenting Several Lines ++ ++ Sometimes, you may want to reindent several lines of code at a time. ++One way to do this is to use the mark; when the mark is active and the ++region is non-empty, @key{TAB} indents every line within the region. ++In addition, Emacs provides several other commands for indenting large ++chunks of code: ++ ++@table @kbd ++@item C-M-q ++Reindent all the lines within one parenthetical grouping. ++@item C-M-\ ++Reindent all lines in the region (@code{indent-region}). ++@item C-u @key{TAB} ++Shift an entire parenthetical grouping rigidly sideways so that its ++first line is properly indented. ++@item M-x indent-code-rigidly ++Shift all the lines in the region rigidly sideways, but do not alter ++lines that start inside comments and strings. ++@end table ++ ++@kindex C-M-q ++@findex indent-pp-sexp ++ To reindent the contents of a single parenthetical grouping, ++position point before the beginning of the grouping and type ++@kbd{C-M-q}. This changes the relative indentation within the ++grouping, without affecting its overall indentation (i.e., the ++indentation of the line where the grouping starts). The function that ++@kbd{C-M-q} runs depends on the major mode; it is ++@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode, ++etc. To correct the overall indentation as well, type @key{TAB} ++first. ++ ++ @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to the region. ++This is useful when Transient Mark mode is disabled (@pxref{Persistent ++Mark}), because in that case @key{TAB} does not act on the region. ++ ++@kindex C-u TAB ++ If you like the relative indentation within a grouping but not the ++indentation of its first line, move point to that first line and type ++@kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes, ++@key{TAB} with a numeric argument reindents the current line as usual, ++then reindents by the same amount all the lines in the parenthetical ++grouping starting on the current line. It is clever, though, and does ++not alter lines that start inside strings. Neither does it alter C ++preprocessor lines when in C mode, but it does reindent any ++continuation lines that may be attached to them. ++ ++@findex indent-code-rigidly ++ The command @kbd{M-x indent-code-rigidly} rigidly shifts all the ++lines in the region sideways, like @code{indent-rigidly} does ++(@pxref{Indentation Commands}). It doesn't alter the indentation of ++lines that start inside a string, unless the region also starts inside ++that string. The prefix arg specifies the number of columns to ++indent. ++ ++@node Lisp Indent ++@subsection Customizing Lisp Indentation ++@cindex customizing Lisp indentation ++ ++ The indentation pattern for a Lisp expression can depend on the function ++called by the expression. For each Lisp function, you can choose among ++several predefined patterns of indentation, or define an arbitrary one with ++a Lisp program. ++ ++ The standard pattern of indentation is as follows: the second line of the ++expression is indented under the first argument, if that is on the same ++line as the beginning of the expression; otherwise, the second line is ++indented underneath the function name. Each following line is indented ++under the previous line whose nesting depth is the same. ++ ++@vindex lisp-indent-offset ++ If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides ++the usual indentation pattern for the second line of an expression, so that ++such lines are always indented @code{lisp-indent-offset} more columns than ++the containing list. ++ ++@vindex lisp-body-indent ++ Certain functions override the standard pattern. Functions whose ++names start with @code{def} treat the second lines as the start of ++a @dfn{body}, by indenting the second line @code{lisp-body-indent} ++additional columns beyond the open-parenthesis that starts the ++expression. ++ ++@cindex @code{lisp-indent-function} property ++ You can override the standard pattern in various ways for individual ++functions, according to the @code{lisp-indent-function} property of ++the function name. Normally you would use this for macro definitions ++and specify it using the @code{declare} construct (@pxref{Defining ++Macros,,, elisp, the Emacs Lisp Reference Manual}). ++ ++@node C Indent ++@subsection Commands for C Indentation ++ ++ Here are special features for indentation in C mode and related modes: ++ ++@table @code ++@item C-c C-q ++@kindex C-c C-q @r{(C mode)} ++@findex c-indent-defun ++Reindent the current top-level function definition or aggregate type ++declaration (@code{c-indent-defun}). ++ ++@item C-M-q ++@kindex C-M-q @r{(C mode)} ++@findex c-indent-exp ++Reindent each line in the balanced expression that follows point ++(@code{c-indent-exp}). A prefix argument inhibits warning messages ++about invalid syntax. ++ ++@item @key{TAB} ++@findex c-indent-command ++Reindent the current line, and/or in some cases insert a tab character ++(@code{c-indent-command}). ++ ++@vindex c-tab-always-indent ++If @code{c-tab-always-indent} is @code{t}, this command always reindents ++the current line and does nothing else. This is the default. ++ ++If that variable is @code{nil}, this command reindents the current line ++only if point is at the left margin or in the line's indentation; ++otherwise, it inserts a tab (or the equivalent number of spaces, ++if @code{indent-tabs-mode} is @code{nil}). ++ ++Any other value (not @code{nil} or @code{t}) means always reindent the ++line, and also insert a tab if within a comment or a string. ++@end table ++ ++ To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This ++first selects the whole buffer as the region, then reindents that ++region. ++ ++ To reindent the current block, use @kbd{C-M-u C-M-q}. This moves ++to the front of the block and then reindents it all. ++ ++@node Custom C Indent ++@subsection Customizing C Indentation ++@cindex style (for indentation) ++ ++ C mode and related modes use a flexible mechanism for customizing ++indentation. C mode indents a source line in two steps: first it ++classifies the line syntactically according to its contents and ++context; second, it determines the indentation offset associated by ++your selected @dfn{style} with the syntactic construct and adds this ++onto the indentation of the @dfn{anchor statement}. ++ ++@table @kbd ++@item C-c . @key{RET} @var{style} @key{RET} ++Select a predefined style @var{style} (@code{c-set-style}). ++@end table ++ ++ A @dfn{style} is a named collection of customizations that can be ++used in C mode and the related modes. @ref{Styles,,, ccmode, The CC ++Mode Manual}, for a complete description. Emacs comes with several ++predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, ++@code{stroustrup}, @code{linux}, @code{python}, @code{java}, ++@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these ++styles are primarily intended for one language, but any of them can be ++used with any of the languages supported by these modes. To find out ++what a style looks like, select it and reindent some code, e.g., by ++typing @key{C-M-q} at the start of a function definition. ++ ++@kindex C-c . @r{(C mode)} ++@findex c-set-style ++ To choose a style for the current buffer, use the command @w{@kbd{C-c ++.}}. Specify a style name as an argument (case is not significant). ++This command affects the current buffer only, and it affects only ++future invocations of the indentation commands; it does not reindent ++the code already in the buffer. To reindent the whole buffer in the ++new style, you can type @kbd{C-x h C-M-\}. ++ ++@vindex c-default-style ++ You can also set the variable @code{c-default-style} to specify the ++default style for various major modes. Its value should be either the ++style's name (a string) or an alist, in which each element specifies ++one major mode and which indentation style to use for it. For ++example, ++ ++@example ++(setq c-default-style ++ '((java-mode . "java") (awk-mode . "awk") (other . "gnu"))) ++@end example ++ ++@noindent ++specifies explicit choices for Java and AWK modes, and the default ++@samp{gnu} style for the other C-like modes. (These settings are ++actually the defaults.) This variable takes effect when you select ++one of the C-like major modes; thus, if you specify a new default ++style for Java mode, you can make it take effect in an existing Java ++mode buffer by typing @kbd{M-x java-mode} there. ++ ++ The @code{gnu} style specifies the formatting recommended by the GNU ++Project for C; it is the default, so as to encourage use of our ++recommended style. ++ ++ @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and ++@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more ++information on customizing indentation for C and related modes, ++including how to override parts of an existing style and how to define ++your own styles. ++ ++@node Parentheses ++@section Commands for Editing with Parentheses ++ ++@findex check-parens ++@cindex unbalanced parentheses and quotes ++ This section describes the commands and features that take advantage ++of the parenthesis structure in a program, or help you keep it ++balanced. ++ ++ When talking about these facilities, the term ``parenthesis'' also ++includes braces, brackets, or whatever delimiters are defined to match ++in pairs. The major mode controls which delimiters are significant, ++through the syntax table (@pxref{Syntax}). In Lisp, only parentheses ++count; in C, these commands apply to braces and brackets too. ++ ++ You can use @kbd{M-x check-parens} to find any unbalanced ++parentheses and unbalanced string quotes in the buffer. ++ ++@menu ++* Expressions:: Expressions with balanced parentheses. ++* Moving by Parens:: Commands for moving up, down and across ++ in the structure of parentheses. ++* Matching:: Insertion of a close-delimiter flashes matching open. ++@end menu ++ ++@node Expressions ++@subsection Expressions with Balanced Parentheses ++ ++@cindex sexp ++@cindex expression ++@cindex balanced expression ++ These commands deal with balanced expressions, also called ++@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an ++expression in Lisp.}. ++ ++@table @kbd ++@item C-M-f ++Move forward over a balanced expression (@code{forward-sexp}). ++@item C-M-b ++Move backward over a balanced expression (@code{backward-sexp}). ++@item C-M-k ++Kill balanced expression forward (@code{kill-sexp}). ++@item C-M-t ++Transpose expressions (@code{transpose-sexps}). ++@item C-M-@@ ++@itemx C-M-@key{SPC} ++Put mark after following expression (@code{mark-sexp}). ++@end table ++ ++ Each programming language major mode customizes the definition of ++balanced expressions to suit that language. Balanced expressions ++typically include symbols, numbers, and string constants, as well as ++any pair of matching delimiters and their contents. Some languages ++have obscure forms of expression syntax that nobody has bothered to ++implement in Emacs. ++ ++@cindex Control-Meta ++ By convention, the keys for these commands are all Control-Meta ++characters. They usually act on expressions just as the corresponding ++Meta characters act on words. For instance, the command @kbd{C-M-b} ++moves backward over a balanced expression, just as @kbd{M-b} moves ++back over a word. ++ ++@kindex C-M-f ++@kindex C-M-b ++@findex forward-sexp ++@findex backward-sexp ++ To move forward over a balanced expression, use @kbd{C-M-f} ++(@code{forward-sexp}). If the first significant character after point ++is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or ++@samp{@{} in C), @kbd{C-M-f} moves past the matching closing ++delimiter. If the character begins a symbol, string, or number, ++@kbd{C-M-f} moves over that. ++ ++ The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a ++balanced expression. The detailed rules are like those above for ++@kbd{C-M-f}, but with directions reversed. If there are prefix ++characters (single-quote, backquote and comma, in Lisp) preceding the ++expression, @kbd{C-M-b} moves back over them as well. The balanced ++expression commands move across comments as if they were whitespace, ++in most modes. ++ ++ @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the ++specified number of times; with a negative argument, it moves in the ++opposite direction. ++ ++@cindex killing expressions ++@kindex C-M-k ++@findex kill-sexp ++ Killing a whole balanced expression can be done with @kbd{C-M-k} ++(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f} ++would move over. ++ ++@cindex transposition of expressions ++@kindex C-M-t ++@findex transpose-sexps ++ A somewhat random-sounding command which is nevertheless handy is ++@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous ++balanced expression across the next one. An argument serves as a ++repeat count, moving the previous expression over that many following ++ones. A negative argument drags the previous balanced expression ++backwards across those before it (thus canceling out the effect of ++@kbd{C-M-t} with a positive argument). An argument of zero, rather ++than doing nothing, transposes the balanced expressions ending at or ++after point and the mark. ++ ++@kindex C-M-@@ ++@kindex C-M-@key{SPC} ++@findex mark-sexp ++ To set the region around the next balanced expression in the buffer, ++use @kbd{C-M-@key{SPC}} (@code{mark-sexp}), which sets mark at the ++same place that @kbd{C-M-f} would move to. @kbd{C-M-@key{SPC}} treats ++numeric arguments in the same way as @kbd{C-M-f}; in particular, a ++negative argument puts the mark at the beginning of the previous ++balanced expression. The alias @kbd{C-M-@@} is equivalent to ++@kbd{C-M-@key{SPC}}. While the mark is active, each successive use of ++@kbd{C-M-@key{SPC}} extends the region by shifting the mark by one ++sexp. ++ ++ In languages that use infix operators, such as C, it is not possible ++to recognize all balanced expressions as such because there can be ++multiple possibilities at a given position. For example, C mode does ++not treat @samp{foo + bar} as a single expression, even though it ++@emph{is} one C expression; instead, it recognizes @samp{foo} as one ++expression and @samp{bar} as another, with the @samp{+} as punctuation ++between them. Both @samp{foo + bar} and @samp{foo} are legitimate ++choices for ``the expression following point'' when point is at the ++@samp{f}, so the expression commands must perforce choose one or the ++other to operate on. Note that @samp{(foo + bar)} is recognized as a ++single expression in C mode, because of the parentheses. ++ ++@node Moving by Parens ++@subsection Moving in the Parenthesis Structure ++ ++@cindex parenthetical groupings ++@cindex parentheses, moving across ++@cindex matching parenthesis and braces, moving to ++@cindex braces, moving across ++@cindex list commands ++ ++ The Emacs commands for handling parenthetical groupings see nothing ++except parentheses (or whatever characters must balance in the ++language you are working with). They ignore strings and comments ++(including any parentheses within them) and ignore parentheses quoted ++by an escape character. They are mainly intended for editing ++programs, but can be useful for editing any text that has parentheses. ++They are sometimes called ``list'' commands because in Lisp these ++groupings are lists. ++ ++These commands assume that the starting point is not inside a string ++or a comment. Sometimes you can invoke them usefully from one of ++these places (for example, when you have a parenthesised clause in a ++comment) but this is unreliable. ++ ++@table @kbd ++@item C-M-n ++Move forward over a parenthetical group (@code{forward-list}). ++@item C-M-p ++Move backward over a parenthetical group (@code{backward-list}). ++@item C-M-u ++Move up in parenthesis structure (@code{backward-up-list}). ++@item C-M-d ++Move down in parenthesis structure (@code{down-list}). ++@end table ++ ++@kindex C-M-n ++@kindex C-M-p ++@findex forward-list ++@findex backward-list ++ The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and ++@kbd{C-M-p} (@code{backward-list}) move forward or backward over one ++(or @var{n}) parenthetical groupings. ++ ++@kindex C-M-u ++@findex backward-up-list ++ @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the ++parenthesis structure. To move @emph{up} one (or @var{n}) levels, use ++@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up ++past one unmatched opening delimiter. A positive argument serves as a ++repeat count; a negative argument reverses the direction of motion, so ++that the command moves forward and up one or more levels. ++ ++@kindex C-M-d ++@findex down-list ++ To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} ++(@code{down-list}). In Lisp mode, where @samp{(} is the only opening ++delimiter, this is nearly the same as searching for a @samp{(}. An ++argument specifies the number of levels to go down. ++ ++@node Matching ++@subsection Automatic Display Of Matching Parentheses ++@cindex matching parentheses ++@cindex parentheses, displaying matches ++ ++ The Emacs parenthesis-matching feature is designed to show ++automatically how parentheses (and other matching delimiters) match in ++the text. Whenever you type a self-inserting character that is a ++closing delimiter, the cursor moves momentarily to the location of the ++matching opening delimiter, provided that is on the screen. If it is ++not on the screen, Emacs displays some of the text near it in the echo ++area. Either way, you can tell which grouping you are closing off. ++ ++ If the opening delimiter and closing delimiter are mismatched---such ++as in @samp{[x)}---a warning message is displayed in the echo area. ++ ++@vindex blink-matching-paren ++@vindex blink-matching-paren-distance ++@vindex blink-matching-delay ++ Three variables control parenthesis match display: ++ ++ @code{blink-matching-paren} turns the feature on or off: @code{nil} ++disables it, but the default is @code{t} to enable match display. ++ ++ @code{blink-matching-delay} says how many seconds to leave the ++cursor on the matching opening delimiter, before bringing it back to ++the real location of point; the default is 1, but on some systems it ++is useful to specify a fraction of a second. ++ ++ @code{blink-matching-paren-distance} specifies how many characters ++back to search to find the matching opening delimiter. If the match ++is not found in that distance, scanning stops, and nothing is displayed. ++This is to prevent the scan for the matching delimiter from wasting ++lots of time when there is no match. The default is 25600. ++ ++@cindex Show Paren mode ++@cindex highlighting matching parentheses ++@findex show-paren-mode ++ Show Paren mode provides a more powerful kind of automatic matching. ++Whenever point is before an opening delimiter or after a closing ++delimiter, both that delimiter and its opposite delimiter are ++highlighted. Use the command @kbd{M-x show-paren-mode} to enable or ++disable this mode. ++ ++ Show Paren mode uses the faces @code{show-paren-match} and ++@code{show-paren-mismatch} to highlight parentheses; you can customize ++them to control how highlighting looks. @xref{Face Customization}. ++ ++@node Comments ++@section Manipulating Comments ++@cindex comments ++ ++ Because comments are such an important part of programming, Emacs ++provides special commands for editing and inserting comments. It can ++also do spell checking on comments with Flyspell Prog mode ++(@pxref{Spelling}). ++ ++@menu ++* Comment Commands:: Inserting, killing, and aligning comments. ++* Multi-Line Comments:: Commands for adding and editing multi-line comments. ++* Options for Comments::Customizing the comment features. ++@end menu ++ ++@node Comment Commands ++@subsection Comment Commands ++@cindex indentation for comments ++@cindex alignment for comments ++ ++ The commands in this table insert, kill and align comments: ++ ++@table @asis ++@item @kbd{M-;} ++Insert or realign comment on current line; alternatively, comment or ++uncomment the region (@code{comment-dwim}). ++@item @kbd{C-u M-;} ++Kill comment on current line (@code{comment-kill}). ++@item @kbd{C-x ;} ++Set comment column (@code{comment-set-column}). ++@item @kbd{C-M-j} ++@itemx @kbd{M-j} ++Like @key{RET} followed by inserting and aligning a comment ++(@code{comment-indent-new-line}). @xref{Multi-Line Comments}. ++@item @kbd{M-x comment-region} ++@itemx @kbd{C-c C-c} (in C-like modes) ++Add or remove comment delimiters on all the lines in the region. ++@end table ++ ++@kindex M-; ++@findex comment-dwim ++ The command to create or align a comment is @kbd{M-;} ++(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What ++I Mean''; it indicates that this command can be used for many ++different jobs relating to comments, depending on the situation where ++you use it. ++ ++ When a region is active, @kbd{M-;} either adds or removes comment ++delimiters on each line of the region. @xref{Mark}. If every line in ++the region is a comment, it removes comment delimiters from each; ++otherwise, it adds comment delimiters to each. You can also use the ++commands @code{comment-region} and @code{uncomment-region} to ++explicitly comment or uncomment the text in the region ++(@pxref{Multi-Line Comments}). If you supply a prefix argument to ++@kbd{M-;} when a region is active, that specifies how many comment ++delimiters to add or how many to delete. ++ ++ If the region is not active, @kbd{M-;} inserts a new comment if ++there is no comment already on the line. The new comment is normally ++aligned at a specific column called the @dfn{comment column}; if the ++text of the line extends past the comment column, @kbd{M-;} aligns the ++comment start string to a suitable boundary (usually, at least one ++space is inserted). The comment begins with the string Emacs thinks ++comments should start with (the value of @code{comment-start}; see ++below). Emacs places point after that string, so you can insert the ++text of the comment right away. If the major mode has specified a ++string to terminate comments, @kbd{M-;} inserts that string after ++point, to keep the syntax valid. ++ ++ You can also use @kbd{M-;} to align an existing comment. If a line ++already contains the comment-start string, @kbd{M-;} realigns it to ++the conventional alignment and moves point after it. (Exception: ++comments starting in column 0 are not moved.) Even when an existing ++comment is properly aligned, @kbd{M-;} is still useful for moving ++directly to the start of the text inside the comment. ++ ++@findex comment-kill ++@kindex C-u M-; ++ @kbd{C-u M-;} kills any comment on the current line, along with the ++whitespace before it. To reinsert the comment on another line, move ++to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to ++realign it. ++ ++ Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;} ++(@code{comment-dwim}) with a prefix argument. That command is ++programmed so that when it receives a prefix argument it calls ++@code{comment-kill}. However, @code{comment-kill} is a valid command ++in its own right, and you can bind it directly to a key if you wish. ++ ++ Some major modes have special rules for aligning certain kinds of ++comments in certain contexts. For example, in Lisp code, comments which ++start with two semicolons are indented as if they were lines of code, ++instead of at the comment column. Comments which start with three ++semicolons are supposed to start at the left margin and are often used ++for sectioning purposes. Emacs understands ++these conventions by indenting a double-semicolon comment using @key{TAB}, ++and by not changing the indentation of a triple-semicolon comment at all. ++ ++@example ++;; This function is just an example. ++;;; Here either two or three semicolons are appropriate. ++(defun foo (x) ++;;; And now, the first part of the function: ++ ;; The following line adds one. ++ (1+ x)) ; This line adds one. ++@end example ++ ++ For C-like modes, you can configure the exact effect of @kbd{M-;} by ++setting the variables @code{c-indent-comment-alist} and ++@code{c-indent-comments-syntactically-p}. For example, on a line ++ending in a closing brace, @kbd{M-;} puts the comment one space after ++the brace rather than at @code{comment-column}. For full details see ++@ref{Comment Commands,,, ccmode, The CC Mode Manual}. ++ ++@node Multi-Line Comments ++@subsection Multiple Lines of Comments ++ ++@kindex C-M-j ++@kindex M-j ++@cindex blank lines in programs ++@findex comment-indent-new-line ++ ++ If you are typing a comment and wish to continue it on another line, ++you can use the command @kbd{C-M-j} or @kbd{M-j} ++(@code{comment-indent-new-line}). If @code{comment-multi-line} ++(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new ++line within the comment. Otherwise it closes the comment and starts a ++new comment on a new line. When Auto Fill mode is on, going past the ++fill column while typing a comment causes the comment to be continued ++in just this fashion. ++ ++@kindex C-c C-c (C mode) ++@findex comment-region ++ To turn existing lines into comment lines, use the @kbd{M-x ++comment-region} command (or type @kbd{C-c C-c} in C-like modes). It ++adds comment delimiters to the lines that start in the region, thus ++commenting them out. With a negative argument, it does the ++opposite---it deletes comment delimiters from the lines in the region. ++ ++ With a positive argument, @code{comment-region} duplicates the last ++character of the comment start sequence it adds; the argument ++specifies how many copies of the character to insert. Thus, in Lisp ++mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. ++Duplicating the comment delimiter is a way of calling attention to the ++comment. It can also affect how the comment is aligned or indented. ++In Lisp, for proper indentation, you should use an argument of two or ++three, if between defuns; if within a defun, it must be three. ++ ++ You can configure C Mode such that when you type a @samp{/} at the ++start of a line in a multi-line block comment, this closes the ++comment. Enable the @code{comment-close-slash} clean-up for this. ++@xref{Clean-ups,,, ccmode, The CC Mode Manual}. ++ ++@node Options for Comments ++@subsection Options Controlling Comments ++ ++@vindex comment-column ++@kindex C-x ; ++@findex comment-set-column ++ The @dfn{comment column}, the column at which Emacs tries to place ++comments, is stored in the variable @code{comment-column}. You can ++set it to a number explicitly. Alternatively, the command @kbd{C-x ;} ++(@code{comment-set-column}) sets the comment column to the column ++point is at. @kbd{C-u C-x ;} sets the comment column to match the ++last comment before point in the buffer, and then does a @kbd{M-;} to ++align the current line's comment under the previous one. ++ ++ The variable @code{comment-column} is per-buffer: setting the variable ++in the normal fashion affects only the current buffer, but there is a ++default value which you can change with @code{setq-default}. ++@xref{Locals}. Many major modes initialize this variable for the ++current buffer. ++ ++@vindex comment-start-skip ++ The comment commands recognize comments based on the regular ++expression that is the value of the variable @code{comment-start-skip}. ++Make sure this regexp does not match the null string. It may match more ++than the comment starting delimiter in the strictest sense of the word; ++for example, in C mode the value of the variable is ++@c This stops M-q from breaking the line inside that @code. ++@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces ++after the @samp{/*} itself, and accepts C++ style comments also. ++(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in ++the string, which is needed to deny the first star its special meaning ++in regexp syntax. @xref{Regexp Backslash}.) ++ ++@vindex comment-start ++@vindex comment-end ++ When a comment command makes a new comment, it inserts the value of ++@code{comment-start} to begin it. The value of @code{comment-end} is ++inserted after point, so that it will follow the text that you will ++insert into the comment. When @code{comment-end} is non-empty, it ++should start with a space. For example, in C mode, ++@code{comment-start} has the value @w{@code{"/* "}} and ++@code{comment-end} has the value @w{@code{" */"}}. ++ ++@vindex comment-padding ++ The variable @code{comment-padding} specifies how many spaces ++@code{comment-region} should insert on each line between the comment ++delimiter and the line's original text. The default is 1, to insert ++one space. @code{nil} means 0. Alternatively, @code{comment-padding} ++can hold the actual string to insert. ++ ++@vindex comment-multi-line ++ The variable @code{comment-multi-line} controls how @kbd{C-M-j} ++(@code{indent-new-comment-line}) behaves when used inside a comment. ++Specifically, when @code{comment-multi-line} is @code{nil}, the ++command inserts a comment terminator, begins a new line, and finally ++inserts a comment starter. Otherwise it does not insert the ++terminator and starter, so it effectively continues the current ++comment across multiple lines. In languages that allow multi-line ++comments, the choice of value for this variable is a matter of taste. ++The default for this variable depends on the major mode. ++ ++@vindex comment-indent-function ++ The variable @code{comment-indent-function} should contain a function ++that will be called to compute the alignment for a newly inserted ++comment or for aligning an existing comment. It is set differently by ++various major modes. The function is called with no arguments, but with ++point at the beginning of the comment, or at the end of a line if a new ++comment is to be inserted. It should return the column in which the ++comment ought to start. For example, in Lisp mode, the indent hook ++function bases its decision on how many semicolons begin an existing ++comment, and on the code in the preceding lines. ++ ++@node Documentation ++@section Documentation Lookup ++ ++ Emacs provides several features you can use to look up the ++documentation of functions, variables and commands that you plan to ++use in your program. ++ ++@menu ++* Info Lookup:: Looking up library functions and commands ++ in Info files. ++* Man Page:: Looking up man pages of library functions and commands. ++* Lisp Doc:: Looking up Emacs Lisp functions, etc. ++@end menu ++ ++@node Info Lookup ++@subsection Info Documentation Lookup ++ ++@findex info-lookup-symbol ++@findex info-lookup-file ++@kindex C-h S ++ For major modes that apply to languages which have documentation in ++Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the ++Info documentation for a symbol used in the program. You specify the ++symbol with the minibuffer; the default is the symbol appearing in the ++buffer at point. For example, in C mode this looks for the symbol in ++the C Library Manual. The command only works if the appropriate ++manual's Info files are installed. ++ ++ The major mode determines where to look for documentation for the ++symbol---which Info files to look in, and which indices to search. ++You can also use @kbd{M-x info-lookup-file} to look for documentation ++for a file name. ++ ++ If you use @kbd{C-h S} in a major mode that does not support it, ++it asks you to specify the ``symbol help mode.'' You should enter ++a command such as @code{c-mode} that would select a major ++mode which @kbd{C-h S} does support. ++ ++@node Man Page ++@subsection Man Page Lookup ++ ++@cindex manual page ++ On Unix, the main form of on-line documentation was the @dfn{manual ++page} or @dfn{man page}. In the GNU operating system, we aim to ++replace man pages with better-organized manuals that you can browse ++with Info (@pxref{Misc Help}). This process is not finished, so it is ++still useful to read manual pages. ++ ++@findex manual-entry ++ You can read the man page for an operating system command, library ++function, or system call, with the @kbd{M-x man} command. It ++runs the @code{man} program to format the man page; if the system ++permits, it runs @code{man} asynchronously, so that you can keep on ++editing while the page is being formatted. (On MS-DOS and MS-Windows ++3, you cannot edit while Emacs waits for @code{man} to finish.) The ++result goes in a buffer named @samp{*Man @var{topic}*}. These buffers ++use a special major mode, Man mode, that facilitates scrolling and ++jumping to other manual pages. For details, type @kbd{C-h m} while in ++a man page buffer. ++ ++@cindex sections of manual pages ++ Each man page belongs to one of ten or more @dfn{sections}, each ++named by a digit or by a digit and a letter. Sometimes there are ++multiple man pages with the same name in different sections. To read ++a man page from a specific section, type ++@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}} ++when @kbd{M-x manual-entry} prompts for the topic. For example, to ++read the man page for the C library function @code{chmod} (as opposed ++to a command of the same name), type @kbd{M-x manual-entry @key{RET} ++chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in ++section @samp{2}.) ++ ++@vindex Man-switches ++ If you do not specify a section, the results depend on how the ++@code{man} program works on your system. Some of them display only ++the first man page they find. Others display all man pages that have ++the specified name, so you can move between them with the @kbd{M-n} ++and @kbd{M-p} keys@footnote{On some systems, the @code{man} program ++accepts a @samp{-a} command-line option which tells it to display all ++the man pages for the specified topic. If you want this behavior, you ++can add this option to the value of the variable @code{Man-switches}.}. ++The mode line shows how many manual pages are present in the Man buffer. ++ ++@vindex Man-fontify-manpage-flag ++ By default, Emacs highlights the text in man pages. For a long man ++page, highlighting can take substantial time. You can turn off ++highlighting of man pages by setting the variable ++@code{Man-fontify-manpage-flag} to @code{nil}. ++ ++@findex Man-fontify-manpage ++ If you insert the text of a man page into an Emacs buffer in some ++other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to ++perform the same conversions that @kbd{M-x manual-entry} does. ++ ++@findex woman ++@cindex manual pages, on MS-DOS/MS-Windows ++ An alternative way of reading manual pages is the @kbd{M-x woman} ++command@footnote{The name of the command, @code{woman}, is an acronym ++for ``w/o (without) man,'' since it doesn't use the @code{man} ++program.}. Unlike @kbd{M-x man}, it does not run any external ++programs to format and display the man pages; instead it does the job ++in Emacs Lisp, so it works on systems such as MS-Windows, where the ++@code{man} program (and other programs it uses) are not generally ++available. ++ ++ @kbd{M-x woman} prompts for a name of a manual page, and provides ++completion based on the list of manual pages that are installed on ++your machine; the list of available manual pages is computed ++automatically the first time you invoke @code{woman}. The word at ++point in the current buffer is used to suggest the default for the ++name the manual page. ++ ++ With a numeric argument, @kbd{M-x woman} recomputes the list of the ++manual pages used for completion. This is useful if you add or delete ++manual pages. ++ ++ If you type a name of a manual page and @kbd{M-x woman} finds that ++several manual pages by the same name exist in different sections, it ++pops up a window with possible candidates asking you to choose one of ++them. ++ ++ For more information about setting up and using @kbd{M-x woman}, see ++@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan ++Manual}. ++ ++@node Lisp Doc ++@subsection Emacs Lisp Documentation Lookup ++ ++ As you edit Lisp code to be run in Emacs, you can use the commands ++@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} ++(@code{describe-variable}) to view documentation of functions and ++variables that you want to use. These commands use the minibuffer to ++read the name of a function or variable to document, and display the ++documentation in a window. Their default arguments are based on the ++code in the neighborhood of point. For @kbd{C-h f}, the default is ++the function called in the innermost list containing point. @kbd{C-h ++v} uses the symbol name around or adjacent to point as its default. ++ ++@cindex Eldoc mode ++@findex eldoc-mode ++ A more automatic but less powerful method is Eldoc mode. This minor ++mode constantly displays in the echo area the argument list for the ++function being called at point. (In other words, it finds the ++function call that point is contained in, and displays the argument ++list of that function.) If point is over a documented variable, it ++shows the first line of the variable's docstring. Eldoc mode applies ++in Emacs Lisp and Lisp Interaction modes, and perhaps a few others ++that provide special support for looking up doc strings. Use the ++command @kbd{M-x eldoc-mode} to enable or disable this feature. ++ ++@node Hideshow ++@section Hideshow minor mode ++ ++@findex hs-minor-mode ++ Hideshow minor mode provides selective display of portions of a ++program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} ++to enable or disable this mode, or add @code{hs-minor-mode} to the ++mode hook for certain major modes in order to enable it automatically ++for those modes. ++ ++ Just what constitutes a block depends on the major mode. In C mode ++or C++ mode, they are delimited by braces, while in Lisp mode and ++similar modes they are delimited by parentheses. Multi-line comments ++also count as blocks. ++ ++@findex hs-hide-all ++@findex hs-hide-block ++@findex hs-show-all ++@findex hs-show-block ++@findex hs-show-region ++@findex hs-hide-level ++@findex hs-minor-mode ++@kindex C-c @@ C-h ++@kindex C-c @@ C-s ++@kindex C-c @@ C-M-h ++@kindex C-c @@ C-M-s ++@kindex C-c @@ C-r ++@kindex C-c @@ C-l ++@kindex S-Mouse-2 ++@table @kbd ++@item C-c @@ C-h ++Hide the current block (@code{hs-hide-block}). ++@item C-c @@ C-s ++Show the current block (@code{hs-show-block}). ++@item C-c @@ C-c ++Either hide or show the current block (@code{hs-toggle-hiding}). ++@item S-Mouse-2 ++Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). ++@item C-c @@ C-M-h ++Hide all top-level blocks (@code{hs-hide-all}). ++@item C-c @@ C-M-s ++Show everything in the buffer (@code{hs-show-all}). ++@item C-c @@ C-l ++Hide all blocks @var{n} levels below this block ++(@code{hs-hide-level}). ++@end table ++ ++@vindex hs-hide-comments-when-hiding-all ++@vindex hs-isearch-open ++@vindex hs-special-modes-alist ++ These variables exist for customizing Hideshow mode. ++ ++@table @code ++@item hs-hide-comments-when-hiding-all ++Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. ++ ++@item hs-isearch-open ++Specifies what kind of hidden blocks incremental search should make ++visible. The value should be one of these four symbols: ++ ++@table @code ++@item code ++Open only code blocks. ++@item comment ++Open only comments. ++@item t ++Open both code blocks and comments. ++@item nil ++Open neither code blocks nor comments. ++@end table ++ ++@item hs-special-modes-alist ++A list of elements, each specifying how to initialize Hideshow ++variables for one major mode. See the variable's documentation string ++for more information. ++@end table ++ ++@node Symbol Completion ++@section Completion for Symbol Names ++@cindex completion (symbol names) ++ ++ In Emacs, completion is something you normally do in the minibuffer ++(@pxref{Completion}). But one kind of completion is available in all ++buffers: completion for symbol names. ++ ++@kindex M-TAB ++ The character @kbd{M-@key{TAB}} runs a command to complete the ++partial symbol before point against the set of meaningful symbol ++names. This command inserts at point any additional characters that ++it can determine from the partial name. ++ ++ If your window manager defines @kbd{M-@key{TAB}} to switch windows, ++you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead. ++However, most window managers let you customize these shortcuts, so ++you can change any that interfere with the way you use Emacs. ++ ++ If the partial name in the buffer has multiple possible completions ++that differ in the very next character, so that it is impossible to ++complete even one more character, @kbd{M-@key{TAB}} displays a list of ++all possible completions in another window. ++ ++@cindex tags-based completion ++@cindex Info index completion ++@findex complete-symbol ++ In most programming language major modes, @kbd{M-@key{TAB}} runs the ++command @code{complete-symbol}, which provides two kinds of completion. ++Normally it does completion based on a tags table (@pxref{Tags}); with a ++numeric argument (regardless of the value), it does completion based on ++the names listed in the Info file indexes for your language. Thus, to ++complete the name of a symbol defined in your own program, use ++@kbd{M-@key{TAB}} with no argument; to complete the name of a standard ++library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based ++completion works only if there is an Info file for the standard library ++functions of your language, and only if it is installed at your site. ++ ++@cindex Lisp symbol completion ++@cindex completion (Lisp symbols) ++@findex lisp-complete-symbol ++ In Emacs-Lisp mode, the name space for completion normally consists of ++nontrivial symbols present in Emacs---those that have function ++definitions, values or properties. However, if there is an ++open-parenthesis immediately before the beginning of the partial symbol, ++only symbols with function definitions are considered as completions. ++The command which implements this is @code{lisp-complete-symbol}. ++ ++ In Text mode and related modes, @kbd{M-@key{TAB}} completes words ++based on the spell-checker's dictionary. @xref{Spelling}. ++ ++@node Glasses ++@section Glasses minor mode ++@cindex Glasses mode ++@cindex identifiers, making long ones readable ++@cindex StudlyCaps, making them readable ++@findex glasses-mode ++ ++ Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} ++readable by altering the way they display. It knows two different ++ways to do this: by displaying underscores between a lower-case letter ++and the following capital letter, and by emboldening the capital ++letters. It does not alter the buffer text, only the way they ++display, so you can use it even on read-only buffers. You can use the ++command @kbd{M-x glasses-mode} to enable or disable the mode in the ++current buffer; you can also add @code{glasses-mode} to the mode hook ++of the programming language major modes in which you normally want ++to use Glasses mode. ++ ++@node Misc for Programs ++@section Other Features Useful for Editing Programs ++ ++ A number of Emacs commands that aren't designed specifically for ++editing programs are useful for that nonetheless. ++ ++ The Emacs commands that operate on words, sentences and paragraphs ++are useful for editing code. Most symbols names contain words ++(@pxref{Words}); sentences can be found in strings and comments ++(@pxref{Sentences}). Paragraphs in the strict sense can be found in ++program code (in long comments), but the paragraph commands are useful ++in other places too, because programming language major modes define ++paragraphs to begin and end at blank lines (@pxref{Paragraphs}). ++Judicious use of blank lines to make the program clearer will also ++provide useful chunks of text for the paragraph commands to work on. ++Auto Fill mode, if enabled in a programming language major mode, ++indents the new lines which it creates. ++ ++ The selective display feature is useful for looking at the overall ++structure of a function (@pxref{Selective Display}). This feature ++hides the lines that are indented more than a specified amount. ++Programming modes often support Outline minor mode (@pxref{Outline ++Mode}). The Foldout package provides folding-editor features ++(@pxref{Foldout}). ++ ++ The ``automatic typing'' features may be useful for writing programs. ++@xref{Top,,Autotyping, autotype, Autotyping}. ++ ++@node C Modes ++@section C and Related Modes ++@cindex C mode ++@cindex Java mode ++@cindex Pike mode ++@cindex IDL mode ++@cindex CORBA IDL mode ++@cindex Objective C mode ++@cindex C++ mode ++@cindex AWK mode ++@cindex mode, Java ++@cindex mode, C ++@cindex mode, C++ ++@cindex mode, Objective C ++@cindex mode, CORBA IDL ++@cindex mode, Pike ++@cindex mode, AWK ++ ++ This section gives a brief description of the special features ++available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. ++(These are called ``C mode and related modes.'') @xref{Top, , CC Mode, ++ccmode, CC Mode}, for a more extensive description of these modes ++and their special features. ++ ++@menu ++* Motion in C:: Commands to move by C statements, etc. ++* Electric C:: Colon and other chars can automatically reindent. ++* Hungry Delete:: A more powerful DEL command. ++* Other C Commands:: Filling comments, viewing expansion of macros, ++ and other neat features. ++@end menu ++ ++@node Motion in C ++@subsection C Mode Motion Commands ++ ++ This section describes commands for moving point, in C mode and ++related modes. ++ ++@table @code ++@item M-x c-beginning-of-defun ++@itemx M-x c-end-of-defun ++@findex c-beginning-of-defun ++@findex c-end-of-defun ++Move point to the beginning or end of the current function or ++top-level definition. These are found by searching for the least ++enclosing braces. (By contrast, @code{beginning-of-defun} and ++@code{end-of-defun} search for braces in column zero.) If you are ++editing code where the opening brace of a function isn't placed in ++column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to ++these commands. @xref{Moving by Defuns}. ++ ++@item C-c C-u ++@kindex C-c C-u @r{(C mode)} ++@findex c-up-conditional ++Move point back to the containing preprocessor conditional, leaving the ++mark behind. A prefix argument acts as a repeat count. With a negative ++argument, move point forward to the end of the containing ++preprocessor conditional. ++ ++@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so ++the function will stop at a @samp{#elif} when going backward, but not ++when going forward. ++ ++@item C-c C-p ++@kindex C-c C-p @r{(C mode)} ++@findex c-backward-conditional ++Move point back over a preprocessor conditional, leaving the mark ++behind. A prefix argument acts as a repeat count. With a negative ++argument, move forward. ++ ++@item C-c C-n ++@kindex C-c C-n @r{(C mode)} ++@findex c-forward-conditional ++Move point forward across a preprocessor conditional, leaving the mark ++behind. A prefix argument acts as a repeat count. With a negative ++argument, move backward. ++ ++@item M-a ++@kindex M-a (C mode) ++@findex c-beginning-of-statement ++Move point to the beginning of the innermost C statement ++(@code{c-beginning-of-statement}). If point is already at the beginning ++of a statement, move to the beginning of the preceding statement. With ++prefix argument @var{n}, move back @var{n} @minus{} 1 statements. ++ ++In comments or in strings which span more than one line, this command ++moves by sentences instead of statements. ++ ++@item M-e ++@kindex M-e (C mode) ++@findex c-end-of-statement ++Move point to the end of the innermost C statement or sentence; like ++@kbd{M-a} except that it moves in the other direction ++(@code{c-end-of-statement}). ++@end table ++ ++@node Electric C ++@subsection Electric C Characters ++ ++ In C mode and related modes, certain printing characters are ++@dfn{electric}---in addition to inserting themselves, they also ++reindent the current line, and optionally also insert newlines. The ++``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, ++@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and ++@kbd{)}. ++ ++ You might find electric indentation inconvenient if you are editing ++chaotically indented code. If you are new to CC Mode, you might find ++it disconcerting. You can toggle electric action with the command ++@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line ++after the mode name: ++ ++@table @kbd ++@item C-c C-l ++@kindex C-c C-l @r{(C mode)} ++@findex c-toggle-electric-state ++Toggle electric action (@code{c-toggle-electric-state}). With a ++prefix argument, this command enables electric action if the argument ++is positive, disables it if it is negative. ++@end table ++ ++ Electric characters insert newlines only when, in addition to the ++electric state, the @dfn{auto-newline} feature is enabled (indicated ++by @samp{/la} in the mode line after the mode name). You can turn ++this feature on or off with the command @kbd{C-c C-a}: ++ ++@table @kbd ++@item C-c C-a ++@kindex C-c C-a @r{(C mode)} ++@findex c-toggle-auto-newline ++Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a ++prefix argument, this command turns the auto-newline feature on if the ++argument is positive, and off if it is negative. ++@end table ++ ++ Usually the CC Mode style configures the exact circumstances in ++which Emacs inserts auto-newlines. You can also configure this ++directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. ++ ++@node Hungry Delete ++@subsection Hungry Delete Feature in C ++@cindex hungry deletion (C Mode) ++ ++ If you want to delete an entire block of whitespace at point, you ++can use @dfn{hungry deletion}. This deletes all the contiguous ++whitespace either before point or after point in a single operation. ++@dfn{Whitespace} here includes tabs and newlines, but not comments or ++preprocessor commands. ++ ++@table @kbd ++@item C-c C-@key{DEL} ++@itemx C-c @key{DEL} ++@findex c-hungry-delete-backwards ++@kindex C-c C-@key{DEL} (C Mode) ++@kindex C-c @key{DEL} (C Mode) ++@code{c-hungry-delete-backwards}---Delete the entire block of whitespace ++preceding point. ++ ++@item C-c C-d ++@itemx C-c C-@key{DELETE} ++@itemx C-c @key{DELETE} ++@findex c-hungry-delete-forward ++@kindex C-c C-d (C Mode) ++@kindex C-c C-@key{DELETE} (C Mode) ++@kindex C-c @key{DELETE} (C Mode) ++@code{c-hungry-delete-forward}---Delete the entire block of whitespace ++following point. ++@end table ++ ++ As an alternative to the above commands, you can enable @dfn{hungry ++delete mode}. When this feature is enabled (indicated by @samp{/h} in ++the mode line after the mode name), a single @key{DEL} deletes all ++preceding whitespace, not just one space, and a single @kbd{C-c C-d} ++(but @emph{not} plain @key{DELETE}) deletes all following whitespace. ++ ++@table @kbd ++@item M-x c-toggle-hungry-state ++@findex c-toggle-hungry-state ++Toggle the hungry-delete feature ++(@code{c-toggle-hungry-state})@footnote{This command had the binding ++@kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now ++bound to @code{c-hungry-delete-forward}.}. With a prefix argument, ++this command turns the hungry-delete feature on if the argument is ++positive, and off if it is negative. ++@end table ++ ++@vindex c-hungry-delete-key ++ The variable @code{c-hungry-delete-key} controls whether the ++hungry-delete feature is enabled. ++ ++@node Other C Commands ++@subsection Other Commands for C Mode ++ ++@table @kbd ++@item C-c C-w ++@itemx M-x c-subword-mode ++@findex c-subword-mode ++Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word ++commands recognize upper case letters in ++@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by ++the flag @samp{/w} on the mode line after the mode name ++(e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in ++non-CC Mode buffers. ++ ++In the GNU project, we recommend using underscores to separate words ++within an identifier in C or C++, rather than using case distinctions. ++ ++@item M-x c-context-line-break ++@findex c-context-line-break ++This command inserts a line break and indents the new line in a manner ++appropriate to the context. In normal code, it does the work of ++@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it ++additionally inserts a @samp{\} at the line break, and within comments ++it's like @kbd{M-j} (@code{c-indent-new-comment-line}). ++ ++@code{c-context-line-break} isn't bound to a key by default, but it ++needs a binding to be useful. The following code will bind it to ++@kbd{C-j}. We use @code{c-initialization-hook} here to make sure ++the keymap is loaded before we try to change it. ++ ++@smallexample ++(defun my-bind-clb () ++ (define-key c-mode-base-map "\C-j" 'c-context-line-break)) ++(add-hook 'c-initialization-hook 'my-bind-clb) ++@end smallexample ++ ++@item C-M-h ++Put mark at the end of a function definition, and put point at the ++beginning (@code{c-mark-function}). ++ ++@item M-q ++@kindex M-q @r{(C mode)} ++@findex c-fill-paragraph ++Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). ++If any part of the current line is a comment or within a comment, this ++command fills the comment or the paragraph of it that point is in, ++preserving the comment indentation and comment delimiters. ++ ++@item C-c C-e ++@cindex macro expansion in C ++@cindex expansion of C macros ++@findex c-macro-expand ++@kindex C-c C-e @r{(C mode)} ++Run the C preprocessor on the text in the region, and show the result, ++which includes the expansion of all the macro calls ++(@code{c-macro-expand}). The buffer text before the region is also ++included in preprocessing, for the sake of macros defined there, but the ++output from this part isn't shown. ++ ++When you are debugging C code that uses macros, sometimes it is hard to ++figure out precisely how the macros expand. With this command, you ++don't have to figure it out; you can see the expansions. ++ ++@item C-c C-\ ++@findex c-backslash-region ++@kindex C-c C-\ @r{(C mode)} ++Insert or align @samp{\} characters at the ends of the lines of the ++region (@code{c-backslash-region}). This is useful after writing or ++editing a C macro definition. ++ ++If a line already ends in @samp{\}, this command adjusts the amount of ++whitespace before it. Otherwise, it inserts a new @samp{\}. However, ++the last line in the region is treated specially; no @samp{\} is ++inserted on that line, and any @samp{\} there is deleted. ++ ++@item M-x cpp-highlight-buffer ++@cindex preprocessor highlighting ++@findex cpp-highlight-buffer ++Highlight parts of the text according to its preprocessor conditionals. ++This command displays another buffer named @samp{*CPP Edit*}, which ++serves as a graphic menu for selecting how to display particular kinds ++of conditionals and their contents. After changing various settings, ++click on @samp{[A]pply these settings} (or go to that buffer and type ++@kbd{a}) to rehighlight the C mode buffer accordingly. ++ ++@item C-c C-s ++@findex c-show-syntactic-information ++@kindex C-c C-s @r{(C mode)} ++Display the syntactic information about the current source line ++(@code{c-show-syntactic-information}). This information directs how ++the line is indented. ++ ++@item M-x cwarn-mode ++@itemx M-x global-cwarn-mode ++@findex cwarn-mode ++@findex global-cwarn-mode ++@vindex global-cwarn-mode ++@cindex CWarn mode ++@cindex suspicious constructions in C, C++ ++CWarn minor mode highlights certain suspicious C and C++ constructions: ++ ++@itemize @bullet{} ++@item ++Assignments inside expressions. ++@item ++Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} ++(except after a @samp{do @dots{} while} statement); ++@item ++C++ functions with reference parameters. ++@end itemize ++ ++@noindent ++You can enable the mode for one buffer with the command @kbd{M-x ++cwarn-mode}, or for all suitable buffers with the command @kbd{M-x ++global-cwarn-mode} or by customizing the variable ++@code{global-cwarn-mode}. You must also enable Font Lock mode to make ++it work. ++ ++@item M-x hide-ifdef-mode ++@findex hide-ifdef-mode ++@cindex Hide-ifdef mode ++@vindex hide-ifdef-shadow ++Hide-ifdef minor mode hides selected code within @samp{#if} and ++@samp{#ifdef} preprocessor blocks. If you change the variable ++@code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode ++``shadows'' preprocessor blocks by displaying them with a less ++prominent face, instead of hiding them entirely. See the ++documentation string of @code{hide-ifdef-mode} for more information. ++ ++@item M-x ff-find-related-file ++@cindex related files ++@findex ff-find-related-file ++@vindex ff-related-file-alist ++Find a file ``related'' in a special way to the file visited by the ++current buffer. Typically this will be the header file corresponding ++to a C/C++ source file, or vice versa. The variable ++@code{ff-related-file-alist} specifies how to compute related file ++names. ++@end table ++ ++@node Asm Mode ++@section Asm Mode ++ ++@cindex Asm mode ++@cindex assembler mode ++Asm mode is a major mode for editing files of assembler code. It ++defines these commands: ++ ++@table @kbd ++@item @key{TAB} ++@code{tab-to-tab-stop}. ++@item C-j ++Insert a newline and then indent using @code{tab-to-tab-stop}. ++@item : ++Insert a colon and then remove the indentation from before the label ++preceding colon. Then do @code{tab-to-tab-stop}. ++@item ; ++Insert or align a comment. ++@end table ++ ++ The variable @code{asm-comment-char} specifies which character ++starts comments in assembler syntax. ++ ++@ifnottex ++@include fortran-xtra.texi ++@end ifnottex ++ ++@ignore ++ arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 ++@end ignore +diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi +new file mode 100644 +index 0000000..aeb3f6b +--- /dev/null ++++ b/doc/emacs/regs.texi +@@ -0,0 +1,336 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Registers, Display, CUA Bindings, Top ++@chapter Registers ++@cindex registers ++ ++ Emacs @dfn{registers} are compartments where you can save text, ++rectangles, positions, and other things for later use. Once you save ++text or a rectangle in a register, you can copy it into the buffer ++once, or many times; once you save a position in a register, you can ++jump back to that position once, or many times. ++ ++ Each register has a name that consists of a single character, which ++we will denote by @var{r}; @var{r} can be a letter (such as @samp{a}) ++or a number (such as @samp{1}); case matters, so register @samp{a} is ++not the same as register @samp{A}. ++ ++@findex view-register ++ A register can store a position, a piece of text, a rectangle, a ++number, a window configuration, or a file name, but only one thing at ++any given time. Whatever you store in a register remains there until ++you store something else in that register. To see what register ++@var{r} contains, use @kbd{M-x view-register}: ++ ++@table @kbd ++@item M-x view-register @key{RET} @var{r} ++Display a description of what register @var{r} contains. ++@end table ++ ++ @dfn{Bookmarks} record files and positions in them, so you can ++return to those positions when you look at the file again. ++Bookmarks are similar enough in spirit to registers that they ++seem to belong in this chapter. ++ ++@menu ++* Position: RegPos. Saving positions in registers. ++* Text: RegText. Saving text in registers. ++* Rectangle: RegRect. Saving rectangles in registers. ++* Configurations: RegConfig. Saving window configurations in registers. ++* Numbers: RegNumbers. Numbers in registers. ++* Files: RegFiles. File names in registers. ++* Bookmarks:: Bookmarks are like registers, but persistent. ++@end menu ++ ++@node RegPos ++@section Saving Positions in Registers ++@cindex saving position in a register ++ ++@table @kbd ++@item C-x r @key{SPC} @var{r} ++Record the position of point and the current buffer in register ++@var{r} (@code{point-to-register}). ++@item C-x r j @var{r} ++Jump to the position and buffer saved in register @var{r} ++(@code{jump-to-register}). ++@end table ++ ++@kindex C-x r SPC ++@findex point-to-register ++ Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by ++a character @kbd{@var{r}}, saves both the position of point and the ++current buffer in register @var{r}. The register retains this ++information until you store something else in it. ++ ++@kindex C-x r j ++@findex jump-to-register ++ The command @kbd{C-x r j @var{r}} switches to the buffer recorded in ++register @var{r}, and moves point to the recorded position. The ++contents of the register are not changed, so you can jump to the saved ++position any number of times. ++ ++ If you use @kbd{C-x r j} to go to a saved position, but the buffer it ++was saved from has been killed, @kbd{C-x r j} tries to create the buffer ++again by visiting the same file. Of course, this works only for buffers ++that were visiting files. ++ ++@node RegText ++@section Saving Text in Registers ++@cindex saving text in a register ++ ++ When you want to insert a copy of the same piece of text several ++times, it may be inconvenient to yank it from the kill ring, since each ++subsequent kill moves that entry further down the ring. An alternative ++is to store the text in a register and later retrieve it. ++ ++@table @kbd ++@item C-x r s @var{r} ++Copy region into register @var{r} (@code{copy-to-register}). ++@item C-x r i @var{r} ++Insert text from register @var{r} (@code{insert-register}). ++@item M-x append-to-register @key{RET} @var{r} ++Append region to text in register @var{r}. ++@item M-x prepend-to-register @key{RET} @var{r} ++Prepend region to text in register @var{r}. ++@end table ++ ++@kindex C-x r s ++@findex copy-to-register ++ @kbd{C-x r s @var{r}} stores a copy of the text of the region into ++the register named @var{r}. If the mark is inactive, Emacs first ++reactivates the mark where it was last set. The mark is deactivated ++at the end of this command. @xref{Mark}. @kbd{C-u C-x r s @var{r}}, ++the same command with a prefix argument, copies the text into register ++@var{r} and deletes the text from the buffer as well; you can think of ++this as ``moving'' the region text into the register. ++ ++@findex append-to-register ++@findex prepend-to-register ++ @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of ++the text in the region to the text already stored in the register ++named @var{r}. If invoked with a prefix argument, it deletes the ++region after appending it to the register. The command ++@code{prepend-to-register} is similar, except that it @emph{prepends} ++the region text to the text in the register instead of ++@emph{appending} it. ++ ++@kindex C-x r i ++@findex insert-register ++ @kbd{C-x r i @var{r}} inserts in the buffer the text from register ++@var{r}. Normally it leaves point before the text and places the mark ++after, but with a numeric argument (@kbd{C-u}) it puts point after the ++text and the mark before. ++ ++@node RegRect ++@section Saving Rectangles in Registers ++@cindex saving rectangle in a register ++ ++ A register can contain a rectangle instead of linear text. ++@xref{Rectangles}, for basic information on how to specify a rectangle ++in the buffer. ++ ++@table @kbd ++@findex copy-rectangle-to-register ++@kindex C-x r r ++@item C-x r r @var{r} ++Copy the region-rectangle into register @var{r} ++(@code{copy-rectangle-to-register}). With numeric argument, delete it as ++well. ++@item C-x r i @var{r} ++Insert the rectangle stored in register @var{r} (if it contains a ++rectangle) (@code{insert-register}). ++@end table ++ ++ The @kbd{C-x r i @var{r}} command inserts a text string if the ++register contains one, and inserts a rectangle if the register contains ++one. ++ ++ See also the command @code{sort-columns}, which you can think of ++as sorting a rectangle. @xref{Sorting}. ++ ++@node RegConfig ++@section Saving Window Configurations in Registers ++@cindex saving window configuration in a register ++ ++@findex window-configuration-to-register ++@findex frame-configuration-to-register ++@kindex C-x r w ++@kindex C-x r f ++ You can save the window configuration of the selected frame in a ++register, or even the configuration of all windows in all frames, and ++restore the configuration later. @xref{Windows}, for information ++about window configurations. ++ ++@table @kbd ++@item C-x r w @var{r} ++Save the state of the selected frame's windows in register @var{r} ++(@code{window-configuration-to-register}). ++@item C-x r f @var{r} ++Save the state of all frames, including all their windows, in register ++@var{r} (@code{frame-configuration-to-register}). ++@end table ++ ++ Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. ++This is the same command used to restore a cursor position. When you ++restore a frame configuration, any existing frames not included in the ++configuration become invisible. If you wish to delete these frames ++instead, use @kbd{C-u C-x r j @var{r}}. ++ ++@node RegNumbers ++@section Keeping Numbers in Registers ++@cindex saving number in a register ++ ++ There are commands to store a number in a register, to insert ++the number in the buffer in decimal, and to increment it. These commands ++can be useful in keyboard macros (@pxref{Keyboard Macros}). ++ ++@table @kbd ++@item C-u @var{number} C-x r n @var{r} ++@kindex C-x r n ++@findex number-to-register ++Store @var{number} into register @var{r} (@code{number-to-register}). ++@item C-u @var{number} C-x r + @var{r} ++@kindex C-x r + ++@findex increment-register ++Increment the number in register @var{r} by @var{number} ++(@code{increment-register}). ++@item C-x r i @var{r} ++Insert the number from register @var{r} into the buffer. ++@end table ++ ++ @kbd{C-x r i} is the same command used to insert any other sort of ++register contents into the buffer. @kbd{C-x r +} with no numeric ++argument increments the register value by 1; @kbd{C-x r n} with no ++numeric argument stores zero in the register. ++ ++@node RegFiles ++@section Keeping File Names in Registers ++@cindex saving file name in a register ++ ++ If you visit certain file names frequently, you can visit them more ++conveniently if you put their names in registers. Here's the Lisp code ++used to put a file name in a register: ++ ++@smallexample ++(set-register ?@var{r} '(file . @var{name})) ++@end smallexample ++ ++@need 3000 ++@noindent ++For example, ++ ++@smallexample ++(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog")) ++@end smallexample ++ ++@noindent ++puts the file name shown in register @samp{z}. ++ ++ To visit the file whose name is in register @var{r}, type @kbd{C-x r j ++@var{r}}. (This is the same command used to jump to a position or ++restore a frame configuration.) ++ ++@node Bookmarks ++@section Bookmarks ++@cindex bookmarks ++ ++ @dfn{Bookmarks} are somewhat like registers in that they record ++positions you can jump to. Unlike registers, they have long names, and ++they persist automatically from one Emacs session to the next. The ++prototypical use of bookmarks is to record ``where you were reading'' in ++various files. ++ ++@table @kbd ++@item C-x r m @key{RET} ++Set the bookmark for the visited file, at point. ++ ++@item C-x r m @var{bookmark} @key{RET} ++@findex bookmark-set ++Set the bookmark named @var{bookmark} at point (@code{bookmark-set}). ++ ++@item C-x r b @var{bookmark} @key{RET} ++@findex bookmark-jump ++Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}). ++ ++@item C-x r l ++@findex list-bookmarks ++List all bookmarks (@code{list-bookmarks}). ++ ++@item M-x bookmark-save ++@findex bookmark-save ++Save all the current bookmark values in the default bookmark file. ++@end table ++ ++@kindex C-x r m ++@findex bookmark-set ++@kindex C-x r b ++@findex bookmark-jump ++ The prototypical use for bookmarks is to record one current position ++in each of several files. So the command @kbd{C-x r m}, which sets a ++bookmark, uses the visited file name as the default for the bookmark ++name. If you name each bookmark after the file it points to, then you ++can conveniently revisit any of those files with @kbd{C-x r b}, and move ++to the position of the bookmark at the same time. ++ ++@kindex C-x r l ++ To display a list of all your bookmarks in a separate buffer, type ++@kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer, ++you can use it to edit your bookmark definitions or annotate the ++bookmarks. Type @kbd{C-h m} in the bookmark buffer for more ++information about its special editing commands. ++ ++ When you kill Emacs, Emacs offers to save your bookmark values in your ++default bookmark file, @file{~/.emacs.bmk}, if you have changed any ++bookmark values. You can also save the bookmarks at any time with the ++@kbd{M-x bookmark-save} command. The bookmark commands load your ++default bookmark file automatically. This saving and loading is how ++bookmarks persist from one Emacs session to the next. ++ ++@vindex bookmark-save-flag ++ If you set the variable @code{bookmark-save-flag} to 1, each command ++that sets a bookmark will also save your bookmarks; this way, you ++don't lose any bookmark values even if Emacs crashes. (The value, if ++a number, says how many bookmark modifications should go by between ++saving.) ++ ++@vindex bookmark-search-size ++ Bookmark position values are saved with surrounding context, so that ++@code{bookmark-jump} can find the proper position even if the file is ++modified slightly. The variable @code{bookmark-search-size} says how ++many characters of context to record on each side of the bookmark's ++position. ++ ++ Here are some additional commands for working with bookmarks: ++ ++@table @kbd ++@item M-x bookmark-load @key{RET} @var{filename} @key{RET} ++@findex bookmark-load ++Load a file named @var{filename} that contains a list of bookmark ++values. You can use this command, as well as @code{bookmark-write}, to ++work with other files of bookmark values in addition to your default ++bookmark file. ++ ++@item M-x bookmark-write @key{RET} @var{filename} @key{RET} ++@findex bookmark-write ++Save all the current bookmark values in the file @var{filename}. ++ ++@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET} ++@findex bookmark-delete ++Delete the bookmark named @var{bookmark}. ++ ++@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET} ++@findex bookmark-insert-location ++Insert in the buffer the name of the file that bookmark @var{bookmark} ++points to. ++ ++@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET} ++@findex bookmark-insert ++Insert in the buffer the @emph{contents} of the file that bookmark ++@var{bookmark} points to. ++@end table ++ ++@ignore ++ arch-tag: b00af991-ebc3-4b3a-8e82-a3ac81ff2e64 ++@end ignore +diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi +new file mode 100644 +index 0000000..0b5dd77 +--- /dev/null ++++ b/doc/emacs/rmail.texi +@@ -0,0 +1,1484 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Rmail, Dired, Sending Mail, Top ++@chapter Reading Mail with Rmail ++@cindex Rmail ++@cindex reading mail ++@findex rmail ++@findex rmail-mode ++@vindex rmail-mode-hook ++ ++ Rmail is an Emacs subsystem for reading and disposing of mail that ++you receive. Rmail stores mail messages in files called Rmail files. ++Reading the messages in an Rmail file is done in a special major mode, ++Rmail mode, which redefines most letters to run commands for managing mail. ++@menu ++* Basic: Rmail Basics. Basic concepts of Rmail, and simple use. ++* Scroll: Rmail Scrolling. Scrolling through a message. ++* Motion: Rmail Motion. Moving to another message. ++* Deletion: Rmail Deletion. Deleting and expunging messages. ++* Inbox: Rmail Inbox. How mail gets into the Rmail file. ++* Files: Rmail Files. Using multiple Rmail files. ++* Output: Rmail Output. Copying messages out to files. ++* Labels: Rmail Labels. Classifying messages by labeling them. ++* Attrs: Rmail Attributes. Certain standard labels, called attributes. ++* Reply: Rmail Reply. Sending replies to messages you are viewing. ++* Summary: Rmail Summary. Summaries show brief info on many messages. ++* Sort: Rmail Sorting. Sorting messages in Rmail. ++* Display: Rmail Display. How Rmail displays a message; customization. ++* Coding: Rmail Coding. How Rmail handles decoding character sets. ++* Editing: Rmail Editing. Editing message text and headers in Rmail. ++* Digest: Rmail Digest. Extracting the messages from a digest message. ++* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code. ++* Movemail:: More details of fetching new mail. ++* Remote Mailboxes:: Retrieving mail from remote mailboxes. ++* Other Mailbox Formats:: Retrieving mail from local mailboxes in ++ various formats. ++@end menu ++ ++@node Rmail Basics ++@section Basic Concepts of Rmail ++ ++@cindex primary Rmail file ++@vindex rmail-file-name ++ Using Rmail in the simplest fashion, you have one Rmail file ++@file{~/RMAIL} in which all of your mail is saved. It is called your ++@dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary ++Rmail file, merges new mail in from your inboxes, displays the first ++message you haven't read yet, and lets you begin reading. The variable ++@code{rmail-file-name} specifies the name of the primary Rmail file. ++ ++ Rmail displays only one message in the Rmail file at a time. ++The message that is shown is called the @dfn{current message}. Rmail ++mode's special commands can do such things as delete the current ++message, copy it into another file, send a reply, or move to another ++message. You can also create multiple Rmail files and use Rmail to move ++messages between them. ++ ++@cindex message number ++ Within the Rmail file, messages are normally arranged sequentially in ++order of receipt; you can specify other ways to sort them (@pxref{Rmail ++Sorting}). Messages are identified by consecutive integers which are ++their @dfn{message numbers}. The number of the current message is ++displayed in Rmail's mode line, followed by the total number of messages ++in the file. You can move to a message by specifying its message number ++with the @kbd{j} key (@pxref{Rmail Motion}). ++ ++@kindex s @r{(Rmail)} ++@findex rmail-expunge-and-save ++ Following the usual conventions of Emacs, changes in an Rmail file ++become permanent only when you save the file. You can save it with ++@kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted ++messages from the file first (@pxref{Rmail Deletion}). To save the ++file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail ++file after merging new mail from an inbox file (@pxref{Rmail Inbox}). ++ ++@kindex q @r{(Rmail)} ++@findex rmail-quit ++@kindex b @r{(Rmail)} ++@findex rmail-bury ++ You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges ++and saves the Rmail file, then buries the Rmail buffer as well as its ++summary buffer, if present (@pxref{Rmail Summary}). But there is no ++need to ``exit'' formally. If you switch from Rmail to editing in ++other buffers, and never switch back, you have exited. Just make sure ++to save the Rmail file eventually (like any other file you have ++changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save ++Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the ++Rmail buffer and its summary buffer without expunging and saving the ++Rmail file. ++ ++@node Rmail Scrolling ++@section Scrolling Within a Message ++ ++ When Rmail displays a message that does not fit on the screen, you ++must scroll through it to read the rest. You could do this with ++@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so ++frequent that it deserves to be easier. ++ ++@table @kbd ++@item @key{SPC} ++Scroll forward (@code{scroll-up}). ++@item @key{DEL} ++Scroll backward (@code{scroll-down}). ++@item . ++Scroll to start of message (@code{rmail-beginning-of-message}). ++@item / ++Scroll to end of message (@code{rmail-end-of-message}). ++@end table ++ ++@kindex SPC @r{(Rmail)} ++@kindex DEL @r{(Rmail)} ++ Since the most common thing to do while reading a message is to scroll ++through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of ++@kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down}) ++ ++@kindex . @r{(Rmail)} ++@kindex / @r{(Rmail)} ++@findex rmail-beginning-of-message ++@findex rmail-end-of-message ++ The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the ++beginning of the selected message. This is not quite the same as @kbd{M-<}: ++for one thing, it does not set the mark; for another, it resets the buffer ++boundaries of the current message if you have changed them. Similarly, ++the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end ++of the selected message. ++@c The comment about buffer boundaries is still true in mbox Rmail, if ++@c less likely to be relevant. ++ ++@node Rmail Motion ++@section Moving Among Messages ++ ++ The most basic thing to do with a message is to read it. The way to ++do this in Rmail is to make the message current. The usual practice is ++to move sequentially through the file, since this is the order of ++receipt of messages. When you enter Rmail, you are positioned at the ++first message that you have not yet made current (that is, the first one ++that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move ++forward to see the other new messages; move backward to re-examine old ++messages. ++ ++@table @kbd ++@item n ++Move to the next nondeleted message, skipping any intervening deleted ++messages (@code{rmail-next-undeleted-message}). ++@item p ++Move to the previous nondeleted message ++(@code{rmail-previous-undeleted-message}). ++@item M-n ++Move to the next message, including deleted messages ++(@code{rmail-next-message}). ++@item M-p ++Move to the previous message, including deleted messages ++(@code{rmail-previous-message}). ++@item C-c C-n ++Move to the next message with the same subject as the current one ++(@code{rmail-next-same-subject}). ++@item C-c C-p ++Move to the previous message with the same subject as the current one ++(@code{rmail-previous-same-subject}). ++@item j ++Move to the first message. With argument @var{n}, move to ++message number @var{n} (@code{rmail-show-message}). ++@item > ++Move to the last message (@code{rmail-last-message}). ++@item < ++Move to the first message (@code{rmail-first-message}). ++ ++@item M-s @var{regexp} @key{RET} ++Move to the next message containing a match for @var{regexp} ++(@code{rmail-search}). ++ ++@item - M-s @var{regexp} @key{RET} ++Move to the previous message containing a match for @var{regexp}. ++@end table ++ ++@kindex n @r{(Rmail)} ++@kindex p @r{(Rmail)} ++@kindex M-n @r{(Rmail)} ++@kindex M-p @r{(Rmail)} ++@findex rmail-next-undeleted-message ++@findex rmail-previous-undeleted-message ++@findex rmail-next-message ++@findex rmail-previous-message ++ @kbd{n} and @kbd{p} are the usual way of moving among messages in ++Rmail. They move through the messages sequentially, but skip over ++deleted messages, which is usually what you want to do. Their command ++definitions are named @code{rmail-next-undeleted-message} and ++@code{rmail-previous-undeleted-message}. If you do not want to skip ++deleted messages---for example, if you want to move to a message to ++undelete it---use the variants @kbd{M-n} and @kbd{M-p} ++(@code{rmail-next-message} and @code{rmail-previous-message}). A ++numeric argument to any of these commands serves as a repeat ++count. ++ ++ In Rmail, you can specify a numeric argument by typing just the ++digits. You don't need to type @kbd{C-u} first. ++ ++@kindex M-s @r{(Rmail)} ++@findex rmail-search ++@cindex searching in Rmail ++ The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of ++search. The usual incremental search command @kbd{C-s} works in Rmail, ++but it searches only within the current message. The purpose of ++@kbd{M-s} is to search for another message. It reads a regular ++expression (@pxref{Regexps}) nonincrementally, then searches starting at ++the beginning of the following message for a match. It then selects ++that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp ++used the previous time. ++ ++ To search backward in the file for another message, give @kbd{M-s} a ++negative argument. In Rmail you can do this with @kbd{- M-s}. This ++begins searching from the end of the previous message. ++ ++ It is also possible to search for a message based on labels. ++@xref{Rmail Labels}. ++ ++@kindex C-c C-n @r{(Rmail)} ++@kindex C-c C-p @r{(Rmail)} ++@findex rmail-next-same-subject ++@findex rmail-previous-same-subject ++ The @kbd{C-c C-n} (@code{rmail-next-same-subject}) command moves to ++the next message with the same subject as the current one. A prefix ++argument serves as a repeat count. With a negative argument, this ++command moves backward, acting like @kbd{C-c C-p} ++(@code{rmail-previous-same-subject}). When comparing subjects, these ++commands ignore the prefixes typically added to the subjects of replies. ++ ++@kindex j @r{(Rmail)} ++@kindex > @r{(Rmail)} ++@kindex < @r{(Rmail)} ++@findex rmail-show-message ++@findex rmail-last-message ++@findex rmail-first-message ++ To move to a message specified by absolute message number, use @kbd{j} ++(@code{rmail-show-message}) with the message number as argument. With ++no argument, @kbd{j} selects the first message. @kbd{<} ++(@code{rmail-first-message}) also selects the first message. @kbd{>} ++(@code{rmail-last-message}) selects the last message. ++ ++@node Rmail Deletion ++@section Deleting Messages ++ ++@cindex deletion (Rmail) ++ When you no longer need to keep a message, you can @dfn{delete} it. This ++flags it as ignorable, and some Rmail commands pretend it is no longer ++present; but it still has its place in the Rmail file, and still has its ++message number. ++ ++@cindex expunging (Rmail) ++ @dfn{Expunging} the Rmail file actually removes the deleted messages. ++The remaining messages are renumbered consecutively. ++@c The following is neither true (there is also unforward, sorting, ++@c etc), nor especially interesting. ++@c Expunging is the only action that changes the message number of any ++@c message, except for undigestifying (@pxref{Rmail Digest}). ++ ++@table @kbd ++@item d ++Delete the current message, and move to the next nondeleted message ++(@code{rmail-delete-forward}). ++@item C-d ++Delete the current message, and move to the previous nondeleted ++message (@code{rmail-delete-backward}). ++@item u ++Undelete the current message, or move back to the previous deleted ++message and undelete it (@code{rmail-undelete-previous-message}). ++@item x ++Expunge the Rmail file (@code{rmail-expunge}). ++@end table ++ ++@kindex d @r{(Rmail)} ++@kindex C-d @r{(Rmail)} ++@findex rmail-delete-forward ++@findex rmail-delete-backward ++ There are two Rmail commands for deleting messages. Both delete the ++current message and select another message. @kbd{d} ++(@code{rmail-delete-forward}) moves to the following message, skipping ++messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward}) ++moves to the previous nondeleted message. If there is no nondeleted ++message to move to in the specified direction, the message that was just ++deleted remains current. @kbd{d} with a prefix argument is equivalent ++to @kbd{C-d}. Note that the Rmail summary versions of these commands ++behave slightly differently (@pxref{Rmail Summary Edit}). ++ ++@c mention other hooks, eg show message hook? ++@vindex rmail-delete-message-hook ++ Whenever Rmail deletes a message, it runs the hook ++@code{rmail-delete-message-hook}. When the hook functions are invoked, ++the message has been marked deleted, but it is still the current message ++in the Rmail buffer. ++ ++@cindex undeletion (Rmail) ++@kindex x @r{(Rmail)} ++@findex rmail-expunge ++@kindex u @r{(Rmail)} ++@findex rmail-undelete-previous-message ++ To make all the deleted messages finally vanish from the Rmail file, ++type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still ++@dfn{undelete} the deleted messages. The undeletion command, @kbd{u} ++(@code{rmail-undelete-previous-message}), is designed to cancel the ++effect of a @kbd{d} command in most cases. It undeletes the current ++message if the current message is deleted. Otherwise it moves backward ++to previous messages until a deleted message is found, and undeletes ++that message. ++ ++ You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} ++moves back to and undeletes the message that the @kbd{d} deleted. But ++this does not work when the @kbd{d} skips a few already-deleted messages ++that follow the message being deleted; then the @kbd{u} command ++undeletes the last of the messages that were skipped. There is no clean ++way to avoid this problem. However, by repeating the @kbd{u} command, ++you can eventually get back to the message that you intend to ++undelete. You can also select a particular deleted message with ++the @kbd{M-p} command, then type @kbd{u} to undelete it. ++ ++ A deleted message has the @samp{deleted} attribute, and as a result ++@samp{deleted} appears in the mode line when the current message is ++deleted. In fact, deleting or undeleting a message is nothing more than ++adding or removing this attribute. @xref{Rmail Attributes}. ++ ++@node Rmail Inbox ++@section Rmail Files and Inboxes ++@cindex inbox file ++ ++ When you receive mail locally, the operating system places incoming ++mail for you in a file that we call your @dfn{inbox}. When you start ++up Rmail, it runs a C program called @code{movemail} to copy the new ++messages from your local inbox into your primary Rmail file, which ++also contains other messages saved from previous Rmail sessions. It ++is in this file that you actually read the mail with Rmail. This ++operation is called @dfn{getting new mail}. You can get new mail at ++any time in Rmail by typing @kbd{g}. ++ ++@vindex rmail-primary-inbox-list ++@cindex @env{MAIL} environment variable ++ The variable @code{rmail-primary-inbox-list} contains a list of the ++files which are inboxes for your primary Rmail file. If you don't set ++this variable explicitly, Rmail uses the @env{MAIL} environment ++variable, or, as a last resort, a default inbox based on ++@code{rmail-spool-directory}. The default inbox file depends on your ++operating system; often it is @file{/var/mail/@var{username}}, ++@file{/var/spool/mail/@var{username}}, or ++@file{/usr/spool/mail/@var{username}}. ++ ++ You can specify the inbox file(s) for any Rmail file for the current ++session with the command @code{set-rmail-inbox-list}; see @ref{Rmail ++Files}. ++ ++ There are two reasons for having separate Rmail files and inboxes. ++ ++@enumerate ++@item ++The inbox file format varies between operating systems and according to ++the other mail software in use. Only one part of Rmail needs to know ++about the alternatives, and it need only understand how to convert all ++of them to Rmail's own format. ++ ++@item ++It is very cumbersome to access an inbox file without danger of losing ++mail, because it is necessary to interlock with mail delivery. ++Moreover, different operating systems use different interlocking ++techniques. The strategy of moving mail out of the inbox once and for ++all into a separate Rmail file avoids the need for interlocking in all ++the rest of Rmail, since only Rmail operates on the Rmail file. ++@end enumerate ++ ++ Rmail was originally written to use the Babyl format as its internal ++format. Since then, we have recognized that the usual inbox format ++(@samp{mbox}) on Unix and GNU systems is adequate for the job, and so ++since Emacs 23 Rmail uses that as its internal format. The Rmail file ++is still separate from the inbox file, even though their format is the ++same. ++ ++@vindex rmail-preserve-inbox ++ When getting new mail, Rmail first copies the new mail from the ++inbox file to the Rmail file; then it saves the Rmail file; then it ++clears out the inbox file. This way, a system crash may cause ++duplication of mail between the inbox and the Rmail file, but cannot ++lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then ++Rmail does not clear out the inbox file when it gets new mail. You ++may wish to set this, for example, on a portable computer you use to ++check your mail via POP while traveling, so that your mail will remain ++on the server and you can save it later on your workstation. ++ ++ In some cases, Rmail copies the new mail from the inbox file ++indirectly. First it runs the @code{movemail} program to move the mail ++from the inbox to an intermediate file called ++@file{.newmail-@var{inboxname}}, in the same directory as the Rmail ++file. Then Rmail merges the new mail from that file, saves the Rmail ++file, and only then deletes the intermediate file. If there is a crash ++at the wrong time, this file continues to exist, and Rmail will use it ++again the next time it gets new mail from that inbox. ++ ++ If Rmail is unable to convert the data in ++@file{.newmail-@var{inboxname}} into mbox format, it renames the file to ++@file{RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the name ++unique) so that Rmail will not have trouble with the data again. You ++should look at the file, find whatever message confuses Rmail (probably ++one that includes the control-underscore character, octal code 037), and ++delete it. Then you can use @kbd{1 g} to get new mail from the ++corrected file. ++ ++@node Rmail Files ++@section Multiple Rmail Files ++ ++ Rmail operates by default on your @dfn{primary Rmail file}, which is named ++@file{~/RMAIL} and receives your incoming mail from your system inbox file. ++But you can also have other Rmail files and edit them with Rmail. These ++files can receive mail through their own inboxes, or you can move messages ++into them with explicit Rmail commands (@pxref{Rmail Output}). ++ ++@table @kbd ++@item i @var{file} @key{RET} ++Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}). ++ ++@item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET} ++Specify inbox file names for current Rmail file to get mail from. ++ ++@item g ++Merge new mail from current Rmail file's inboxes ++(@code{rmail-get-new-mail}). ++ ++@item C-u g @var{file} @key{RET} ++Merge new mail from inbox file @var{file}. ++@end table ++ ++@kindex i @r{(Rmail)} ++@findex rmail-input ++ To run Rmail on a file other than your primary Rmail file, you can use ++the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file ++in Rmail mode. You can use @kbd{M-x rmail-input} even when not in ++Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the ++same thing. ++ ++ The file you read with @kbd{i} should normally be a valid mbox file. ++If it is not, Rmail tries to convert its text to mbox format, and ++visits the converted text in the buffer. If you save the buffer, that ++converts the file. ++ ++ If you specify a file name that doesn't exist, @kbd{i} initializes a ++new buffer for creating a new Rmail file. ++ ++@vindex rmail-secondary-file-directory ++@vindex rmail-secondary-file-regexp ++ You can also select an Rmail file from a menu. In the Classify menu, ++choose the Input Rmail File item; then choose the Rmail file you want. ++The variables @code{rmail-secondary-file-directory} and ++@code{rmail-secondary-file-regexp} specify which files to offer in the ++menu: the first variable says which directory to find them in; the ++second says which files in that directory to offer (all those that match ++the regular expression). If no files match, you cannot select this menu ++item. These variables also apply to choosing a file for output ++(@pxref{Rmail Output}). ++ ++@ignore ++@findex set-rmail-inbox-list ++ Each Rmail file can contain a list of inbox file names; you can specify ++this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files} ++@key{RET}}. The argument can contain any number of file names, separated ++by commas. It can also be empty, which specifies that this file should ++have no inboxes. Once you specify a list of inboxes in an Rmail file, ++the Rmail file remembers it permanently until you specify a different list. ++@end ignore ++ ++@vindex rmail-inbox-list ++ The inbox files to use are specified by the variable ++@code{rmail-inbox-list}, which is buffer-local in Rmail mode. As a ++special exception, if you have specified no inbox files for your primary ++Rmail file, it uses the @env{MAIL} environment variable, or your ++standard system inbox. ++ ++@kindex g @r{(Rmail)} ++@findex rmail-get-new-mail ++ The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the ++current Rmail file from its inboxes. If the Rmail file has no ++inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also ++merges new mail into your primary Rmail file. ++ ++ To merge mail from a file that is not the usual inbox, give the ++@kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file ++name and merges mail from that file. The inbox file is not deleted or ++changed in any way when @kbd{g} with an argument is used. This is, ++therefore, a general way of merging one file of messages into another. ++ ++@node Rmail Output ++@section Copying Messages Out to Files ++ ++ These commands copy messages from an Rmail file into another file. ++ ++@table @kbd ++@item o @var{file} @key{RET} ++Append a full copy of the current message to the file @var{file} ++(@code{rmail-output}). ++ ++@item C-o @var{file} @key{RET} ++Append a copy of the current message, as displayed, to the file ++@var{file} (@code{rmail-output-as-seen}). ++ ++@item w @var{file} @key{RET} ++Output just the message body to the file @var{file}, taking the default ++file name from the message @samp{Subject} header. ++@end table ++ ++@kindex o @r{(Rmail)} ++@findex rmail-output-as-seen ++@kindex C-o @r{(Rmail)} ++@findex rmail-output ++ The commands @kbd{o} and @kbd{C-o} copy the current message into a ++specified file, adding it at the end. The two commands differ mainly ++in how much to copy: @kbd{o} copies the full message headers, even if ++they are not all visible, while @kbd{C-o} copies exactly the headers ++currently displayed and no more. @xref{Rmail Display}. In addition, ++@kbd{o} converts the message to Babyl format (used by Rmail in Emacs ++version 22 and before) if the file is in Babyl format; @kbd{C-o} ++cannot output to Babyl files at all. ++ ++ If the output file is currently visited in an Emacs buffer, the ++output commands append the message to that buffer. It is up to you to ++save the buffer eventually in its file. ++ ++@kindex w @r{(Rmail)} ++@findex rmail-output-body-to-file ++ Sometimes you may receive a message whose body holds the contents of a ++file. You can save the body to a file (excluding the message header) ++with the @kbd{w} command (@code{rmail-output-body-to-file}). Often ++these messages contain the intended file name in the @samp{Subject} ++field, so the @kbd{w} command uses the @samp{Subject} field as the ++default for the output file name. However, the file name is read using ++the minibuffer, so you can specify a different name if you wish. ++ ++ You can also output a message to an Rmail file chosen with a menu. ++In the Classify menu, choose the Output Rmail File menu item; then ++choose the Rmail file you want. This outputs the current message to ++that file, like the @kbd{o} command. The variables ++@code{rmail-secondary-file-directory} and ++@code{rmail-secondary-file-regexp} specify which files to offer in the ++menu: the first variable says which directory to find them in; the ++second says which files in that directory to offer (all those that ++match the regular expression). If no files match, you cannot select ++this menu item. ++ ++@vindex rmail-delete-after-output ++ Copying a message with @kbd{o} or @kbd{C-o} gives the original copy ++of the message the @samp{filed} attribute, so that @samp{filed} ++appears in the mode line when such a message is current. ++ ++ If you like to keep just a single copy of every mail message, set ++the variable @code{rmail-delete-after-output} to @code{t}; then the ++@kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message ++after copying it. (You can undelete it afterward if you wish.) ++ ++@vindex rmail-output-file-alist ++ The variable @code{rmail-output-file-alist} lets you specify ++intelligent defaults for the output file, based on the contents of the ++current message. The value should be a list whose elements have this ++form: ++ ++@example ++(@var{regexp} . @var{name-exp}) ++@end example ++ ++@noindent ++If there's a match for @var{regexp} in the current message, then the ++default file name for output is @var{name-exp}. If multiple elements ++match the message, the first matching element decides the default file ++name. The subexpression @var{name-exp} may be a string constant giving ++the file name to use, or more generally it may be any Lisp expression ++that returns a file name as a string. @code{rmail-output-file-alist} ++applies to both @kbd{o} and @kbd{C-o}. ++ ++@node Rmail Labels ++@section Labels ++@cindex label (Rmail) ++@cindex attribute (Rmail) ++ ++ Each message can have various @dfn{labels} assigned to it as a means ++of classification. Each label has a name; different names are different ++labels. Any given label is either present or absent on a particular ++message. A few label names have standard meanings and are given to ++messages automatically by Rmail when appropriate; these special labels ++are called @dfn{attributes}. ++@ifnottex ++(@xref{Rmail Attributes}.) ++@end ifnottex ++All other labels are assigned only by users. ++ ++@table @kbd ++@item a @var{label} @key{RET} ++Assign the label @var{label} to the current message (@code{rmail-add-label}). ++@item k @var{label} @key{RET} ++Remove the label @var{label} from the current message (@code{rmail-kill-label}). ++@item C-M-n @var{labels} @key{RET} ++Move to the next message that has one of the labels @var{labels} ++(@code{rmail-next-labeled-message}). ++@item C-M-p @var{labels} @key{RET} ++Move to the previous message that has one of the labels @var{labels} ++(@code{rmail-previous-labeled-message}). ++@item l @var{labels} @key{RET} ++@itemx C-M-l @var{labels} @key{RET} ++Make a summary of all messages containing any of the labels @var{labels} ++(@code{rmail-summary-by-labels}). ++@end table ++ ++@kindex a @r{(Rmail)} ++@kindex k @r{(Rmail)} ++@findex rmail-add-label ++@findex rmail-kill-label ++ The @kbd{a} (@code{rmail-add-label}) and @kbd{k} ++(@code{rmail-kill-label}) commands allow you to assign or remove any ++label on the current message. If the @var{label} argument is empty, it ++means to assign or remove the same label most recently assigned or ++removed. ++ ++ Once you have given messages labels to classify them as you wish, there ++are three ways to use the labels: in moving, in summaries, and in sorting. ++ ++@kindex C-M-n @r{(Rmail)} ++@kindex C-M-p @r{(Rmail)} ++@findex rmail-next-labeled-message ++@findex rmail-previous-labeled-message ++ The command @kbd{C-M-n @var{labels} @key{RET}} ++(@code{rmail-next-labeled-message}) moves to the next message that has ++one of the labels @var{labels}. The argument @var{labels} specifies one ++or more label names, separated by commas. @kbd{C-M-p} ++(@code{rmail-previous-labeled-message}) is similar, but moves backwards ++to previous messages. A numeric argument to either command serves as a ++repeat count. ++ ++ The command @kbd{C-M-l @var{labels} @key{RET}} ++(@code{rmail-summary-by-labels}) displays a summary containing only the ++messages that have at least one of a specified set of labels. The ++argument @var{labels} is one or more label names, separated by commas. ++@xref{Rmail Summary}, for information on summaries. ++ ++ If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or ++@kbd{C-M-l} is empty, it means to use the last set of labels specified ++for any of these commands. ++ ++ @xref{Rmail Sorting}, for information on sorting messages with labels. ++ ++@node Rmail Attributes ++@section Rmail Attributes ++ ++ Some labels such as @samp{deleted} and @samp{filed} have built-in ++meanings, and Rmail assigns them to messages automatically at ++appropriate times; these labels are called @dfn{attributes}. Here is ++a list of Rmail attributes: ++ ++@table @samp ++@item unseen ++Means the message has never been current. Assigned to messages when ++they come from an inbox file, and removed when a message is made ++current. When you start Rmail, it initially shows the first message ++that has this attribute. ++@item deleted ++Means the message is deleted. Assigned by deletion commands and ++removed by undeletion commands (@pxref{Rmail Deletion}). ++@item filed ++Means the message has been copied to some other file. Assigned by the ++@kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}). ++@item answered ++Means you have mailed an answer to the message. Assigned by the @kbd{r} ++command (@code{rmail-reply}). @xref{Rmail Reply}. ++@item forwarded ++Means you have forwarded the message. Assigned by the @kbd{f} command ++(@code{rmail-forward}). @xref{Rmail Reply}. ++@item edited ++Means you have edited the text of the message within Rmail. ++@xref{Rmail Editing}. ++@item resent ++Means you have resent the message. Assigned by the command @kbd{M-x ++rmail-resend}. @xref{Rmail Reply}. ++@item retried ++Means you have retried a failed outgoing message. Assigned by the ++command @kbd{M-x rmail-retry-failure}. @xref{Rmail Reply}. ++@end table ++ ++ All other labels are assigned or removed only by users, and have no ++standard meaning. ++ ++@node Rmail Reply ++@section Sending Replies ++ ++ Rmail has several commands that use Mail mode to send outgoing mail. ++@xref{Sending Mail}, for information on using Mail mode, including ++certain features meant to work with Rmail. What this section documents ++are the special commands of Rmail for entering Mail mode. Note that the ++usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5 ++m}---also work normally in Rmail mode. ++ ++@table @kbd ++@item m ++Send a message (@code{rmail-mail}). ++@item c ++Continue editing the already started outgoing message (@code{rmail-continue}). ++@item r ++Send a reply to the current Rmail message (@code{rmail-reply}). ++@item f ++Forward the current message to other users (@code{rmail-forward}). ++@item C-u f ++Resend the current message to other users (@code{rmail-resend}). ++@item M-m ++Try sending a bounced message a second time (@code{rmail-retry-failure}). ++@end table ++ ++@kindex r @r{(Rmail)} ++@findex rmail-reply ++@cindex reply to a message ++ The most common reason to send a message while in Rmail is to reply ++to the message you are reading. To do this, type @kbd{r} ++(@code{rmail-reply}). This displays the @samp{*mail*} buffer in ++another window, much like @kbd{C-x 4 m}, but preinitializes the ++@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and ++@samp{References} header fields based on the message you are replying ++to. The @samp{To} field starts out as the address of the person who ++sent the message you received, and the @samp{CC} field starts out with ++all the other recipients of that message. ++ ++@vindex rmail-dont-reply-to-names ++ You can exclude certain recipients from being included automatically ++in replies, using the variable @code{rmail-dont-reply-to-names}. Its ++value should be a regular expression; any recipients that match are ++excluded from the @samp{CC} field. They are also excluded from the ++@samp{To} field, unless this would leave the field empty. If this ++variable is nil, then the first time you compose a reply it is ++initialized to a default value that matches your own address, and any ++name starting with @samp{info-}. (Those names are excluded because ++there is a convention of using them for large mailing lists to broadcast ++announcements.) ++ ++ To omit the @samp{CC} field completely for a particular reply, enter ++the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}. ++This means to reply only to the sender of the original message. ++ ++ Once the @samp{*mail*} buffer has been initialized, editing and ++sending the mail goes as usual (@pxref{Sending Mail}). You can edit the ++presupplied header fields if they are not what you want. You can also ++use the commands of Mail mode (@pxref{Mail Mode}), including @kbd{C-c ++C-y} which yanks in the message that you are replying to. You can ++also switch to the Rmail buffer, select a different message there, switch ++back, and yank the new current message. ++ ++@kindex M-m @r{(Rmail)} ++@findex rmail-retry-failure ++@cindex retrying a failed message ++@vindex rmail-retry-ignored-headers ++ Sometimes a message does not reach its destination. Mailers usually ++send the failed message back to you, enclosed in a @dfn{failure ++message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure}) ++prepares to send the same message a second time: it sets up a ++@samp{*mail*} buffer with the same text and header fields as before. If ++you type @kbd{C-c C-c} right away, you send the message again exactly ++the same as the first time. Alternatively, you can edit the text or ++headers and then send it. The variable ++@code{rmail-retry-ignored-headers}, in the same format as ++@code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which ++headers are stripped from the failed message when retrying it. ++ ++@kindex f @r{(Rmail)} ++@findex rmail-forward ++@cindex forwarding a message ++ Another frequent reason to send mail in Rmail is to @dfn{forward} the ++current message to other users. @kbd{f} (@code{rmail-forward}) makes ++this easy by preinitializing the @samp{*mail*} buffer with the current ++message as the text, and a subject designating a forwarded message. All ++you have to do is fill in the recipients and send. When you forward a ++message, recipients get a message which is ``from'' you, and which has ++the original message in its contents. ++ ++@findex unforward-rmail-message ++ Forwarding a message encloses it between two delimiter lines. It also ++modifies every line that starts with a dash, by inserting @w{@samp{- }} ++at the start of the line. When you receive a forwarded message, if it ++contains something besides ordinary text---for example, program source ++code---you might find it useful to undo that transformation. You can do ++this by selecting the forwarded message and typing @kbd{M-x ++unforward-rmail-message}. This command extracts the original forwarded ++message, deleting the inserted @w{@samp{- }} strings, and inserts it ++into the Rmail file as a separate message immediately following the ++current one. ++ ++@findex rmail-resend ++ @dfn{Resending} is an alternative similar to forwarding; the ++difference is that resending sends a message that is ``from'' the ++original sender, just as it reached you---with a few added header fields ++(@samp{Resent-From} and @samp{Resent-To}) to indicate that it came via ++you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs ++@code{rmail-forward}, which invokes @code{rmail-resend} if you provide a ++numeric argument.) ++ ++@kindex m @r{(Rmail)} ++@findex rmail-mail ++ Use the @kbd{m} (@code{rmail-mail}) command to start editing an ++outgoing message that is not a reply. It leaves the header fields empty. ++Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer ++accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be ++used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f} ++can do. ++ ++@kindex c @r{(Rmail)} ++@findex rmail-continue ++ The @kbd{c} (@code{rmail-continue}) command resumes editing the ++@samp{*mail*} buffer, to finish editing an outgoing message you were ++already composing, or to alter a message you have sent. ++ ++@vindex rmail-mail-new-frame ++ If you set the variable @code{rmail-mail-new-frame} to a ++non-@code{nil} value, then all the Rmail commands to start sending a ++message create a new frame to edit it in. This frame is deleted when ++you send the message, or when you use the @samp{Cancel} item in the ++@samp{Mail} menu. ++ ++ All the Rmail commands to send a message use the mail-composition ++method that you have chosen (@pxref{Mail Methods}). ++ ++@node Rmail Summary ++@section Summaries ++@cindex summary (Rmail) ++ ++ A @dfn{summary} is a buffer containing one line per message to give ++you an overview of the mail in an Rmail file. Each line shows the ++message number and date, the sender, the line count, the labels, and ++the subject. Moving point in the summary buffer selects messages as ++you move to their summary lines. Almost all Rmail commands are valid ++in the summary buffer also; when used there, they apply to the message ++described by the current line of the summary. ++ ++ A summary buffer applies to a single Rmail file only; if you are ++editing multiple Rmail files, each one can have its own summary buffer. ++The summary buffer name is made by appending @samp{-summary} to the ++Rmail buffer's name. Normally only one summary buffer is displayed at a ++time. ++ ++@menu ++* Rmail Make Summary:: Making various sorts of summaries. ++* Rmail Summary Edit:: Manipulating messages from the summary. ++@end menu ++ ++@node Rmail Make Summary ++@subsection Making Summaries ++ ++ Here are the commands to create a summary for the current Rmail ++buffer. Once the Rmail buffer has a summary, changes in the Rmail ++buffer (such as deleting or expunging messages, and getting new mail) ++automatically update the summary. ++ ++@table @kbd ++@item h ++@itemx C-M-h ++Summarize all messages (@code{rmail-summary}). ++@item l @var{labels} @key{RET} ++@itemx C-M-l @var{labels} @key{RET} ++Summarize messages that have one or more of the specified labels ++(@code{rmail-summary-by-labels}). ++@item C-M-r @var{rcpts} @key{RET} ++Summarize messages that match the specified recipients ++(@code{rmail-summary-by-recipients}). ++@item C-M-t @var{topic} @key{RET} ++Summarize messages that have a match for the specified regexp ++@var{topic} in their subjects (@code{rmail-summary-by-topic}). ++@item C-M-s @var{regexp} @key{RET} ++Summarize messages whose headers match the specified regular expression ++@var{regexp} (@code{rmail-summary-by-regexp}). ++@item C-M-f @var{senders} @key{RET} ++Summarize messages that match the specified senders. ++(@code{rmail-summary-by-senders}). ++@end table ++ ++@kindex h @r{(Rmail)} ++@findex rmail-summary ++ The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer ++for the current Rmail buffer with a summary of all the messages in the buffer. ++It then displays and selects the summary buffer in another window. ++ ++@kindex l @r{(Rmail)} ++@kindex C-M-l @r{(Rmail)} ++@findex rmail-summary-by-labels ++ @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes ++a partial summary mentioning only the messages that have one or more of the ++labels @var{labels}. @var{labels} should contain label names separated by ++commas. ++ ++@kindex C-M-r @r{(Rmail)} ++@findex rmail-summary-by-recipients ++ @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients}) ++makes a partial summary mentioning only the messages that have one or ++more recipients matching the regular expression @var{rcpts}. You can ++use commas to separate multiple regular expressions. These are matched ++against the @samp{To}, @samp{From}, and @samp{CC} headers (with a prefix ++argument, this header is not included). ++ ++@kindex C-M-t @r{(Rmail)} ++@findex rmail-summary-by-topic ++ @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic}) ++makes a partial summary mentioning only the messages whose subjects have ++a match for the regular expression @var{topic}. You can use commas to ++separate multiple regular expressions. With a prefix argument, the ++match is against the whole message, not just the subject. ++ ++@kindex C-M-s @r{(Rmail)} ++@findex rmail-summary-by-regexp ++ @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp}) ++makes a partial summary that mentions only the messages whose headers ++(including the date and the subject lines) match the regular ++expression @var{regexp}. ++ ++@kindex C-M-f @r{(Rmail)} ++@findex rmail-summary-by-senders ++ @kbd{C-M-f @var{senders} @key{RET}} (@code{rmail-summary-by-senders}) ++makes a partial summary that mentions only the messages whose @samp{From} ++fields match the regular expression @var{senders}. You can use commas to ++separate multiple regular expressions. ++ ++ Note that there is only one summary buffer for any Rmail buffer; ++making any kind of summary discards any previous summary. ++ ++@vindex rmail-summary-window-size ++@vindex rmail-summary-line-count-flag ++ The variable @code{rmail-summary-window-size} says how many lines to ++use for the summary window. The variable ++@code{rmail-summary-line-count-flag} controls whether the summary line ++for a message should include the line count of the message. Setting ++this option to nil might speed up the generation of summaries. ++ ++@node Rmail Summary Edit ++@subsection Editing in Summaries ++ ++ You can use the Rmail summary buffer to do almost anything you can do ++in the Rmail buffer itself. In fact, once you have a summary buffer, ++there's no need to switch back to the Rmail buffer. ++ ++ You can select and display various messages in the Rmail buffer, from ++the summary buffer, just by moving point in the summary buffer to ++different lines. It doesn't matter what Emacs command you use to move ++point; whichever line point is on at the end of the command, that ++message is selected in the Rmail buffer. ++ ++ Almost all Rmail commands work in the summary buffer as well as in the ++Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current ++message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the ++summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u} ++serves as a repeat count. A negative argument reverses the meaning of ++@kbd{d} and @kbd{C-d}. Also, if there are no more undeleted messages in ++the relevant direction, the delete commands go to the first or last ++message, rather than staying on the current message.) @kbd{o} and ++@kbd{C-o} output the current message to a FILE; @kbd{r} starts a reply ++to it; etc. You can scroll the current message while remaining in the ++summary buffer using @key{SPC} and @key{DEL}. ++@c rmail-summary-scroll-between-messages not mentioned. ++ ++@findex rmail-summary-undelete-many ++@kbd{M-u} (@code{rmail-summary-undelete-many}) undeletes all deleted ++messages in the summary. A prefix argument means to undelete that many ++of the previous deleted messages. ++ ++ The Rmail commands to move between messages also work in the summary ++buffer, but with a twist: they move through the set of messages included ++in the summary. They also ensure the Rmail buffer appears on the screen ++(unlike cursor motion commands, which update the contents of the Rmail ++buffer but don't display it in a window unless it already appears). ++Here is a list of these commands: ++ ++@table @kbd ++@item n ++Move to next line, skipping lines saying `deleted', and select its ++message (@code{rmail-summary-next-msg}). ++@item p ++Move to previous line, skipping lines saying `deleted', and select ++its message (@code{rmail-summary-previous-msg}). ++@item M-n ++Move to next line and select its message (@code{rmail-summary-next-all}). ++@item M-p ++Move to previous line and select its message ++(@code{rmail-summary-previous-all}). ++@item > ++Move to the last line, and select its message ++(@code{rmail-summary-last-message}). ++@item < ++Move to the first line, and select its message ++(@code{rmail-summary-first-message}). ++@item j ++@itemx @key{RET} ++Select the message on the current line (ensuring that the Rmail buffer ++appears on the screen; @code{rmail-summary-goto-msg}). With argument ++@var{n}, select message number @var{n} and move to its line in the ++summary buffer; this signals an error if the message is not listed in ++the summary buffer. ++@item M-s @var{pattern} @key{RET} ++Search through messages for @var{pattern} starting with the current ++message; select the message found, and move point in the summary buffer ++to that message's line (@code{rmail-summary-search}). A prefix argument ++acts as a repeat count; a negative argument means search backward ++(equivalent to @code{rmail-summary-search-backward}.) ++@item C-M-n @var{labels} @key{RET} ++Move to the next message with at least one of the specified labels ++(@code{rmail-summary-next-labeled-message}). @var{labels} is a ++comma-separated list of labels. A prefix argument acts as a repeat ++count. ++@item C-M-p @var{labels} @key{RET} ++Move to the previous message with at least one of the specified labels ++(@code{rmail-summary-previous-labeled-message}). ++@item C-c C-n @key{RET} ++Move to the next message with the same subject as the current message ++(@code{rmail-summary-next-same-subject}). A prefix argument acts as a ++repeat count. ++@item C-c C-p @key{RET} ++Move to the previous message with the same subject as the current message ++(@code{rmail-summary-previous-same-subject}). ++@end table ++ ++@vindex rmail-redisplay-summary ++ Deletion, undeletion, and getting new mail, and even selection of a ++different message all update the summary buffer when you do them in the ++Rmail buffer. If the variable @code{rmail-redisplay-summary} is ++non-@code{nil}, these actions also bring the summary buffer back onto ++the screen. ++ ++@kindex Q @r{(Rmail summary)} ++@findex rmail-summary-wipe ++@kindex q @r{(Rmail summary)} ++@findex rmail-summary-quit ++@kindex b @r{(Rmail summary)} ++@findex rmail-summary-bury ++ When you are finished using the summary, type @kbd{Q} ++(@code{rmail-summary-wipe}) to delete the summary buffer's window. You ++can also exit Rmail while in the summary: @kbd{q} ++(@code{rmail-summary-quit}) deletes the summary window, then exits from ++Rmail by saving the Rmail file and switching to another buffer. ++Alternatively, @kbd{b} (@code{rmail-summary-bury}) simply buries the ++Rmail summary and buffer. ++ ++@node Rmail Sorting ++@section Sorting the Rmail File ++@cindex sorting Rmail file ++@cindex Rmail file sorting ++ ++@table @kbd ++@findex rmail-sort-by-date ++@item C-c C-s C-d ++@itemx M-x rmail-sort-by-date ++Sort messages of current Rmail buffer by date. ++ ++@findex rmail-sort-by-subject ++@item C-c C-s C-s ++@itemx M-x rmail-sort-by-subject ++Sort messages of current Rmail buffer by subject. ++ ++@findex rmail-sort-by-author ++@item C-c C-s C-a ++@itemx M-x rmail-sort-by-author ++Sort messages of current Rmail buffer by author's name. ++ ++@findex rmail-sort-by-recipient ++@item C-c C-s C-r ++@itemx M-x rmail-sort-by-recipient ++Sort messages of current Rmail buffer by recipient's names. ++ ++@findex rmail-sort-by-correspondent ++@item C-c C-s C-c ++@itemx M-x rmail-sort-by-correspondent ++Sort messages of current Rmail buffer by the name of the other ++correspondent. ++ ++@findex rmail-sort-by-lines ++@item C-c C-s C-l ++@itemx M-x rmail-sort-by-lines ++Sort messages of current Rmail buffer by number of lines. ++ ++@findex rmail-sort-by-labels ++@item C-c C-s C-k @key{RET} @var{labels} @key{RET} ++@itemx M-x rmail-sort-by-labels @key{RET} @var{labels} @key{RET} ++Sort messages of current Rmail buffer by labels. The argument ++@var{labels} should be a comma-separated list of labels. The order of ++these labels specifies the order of messages; messages with the first ++label come first, messages with the second label come second, and so on. ++Messages that have none of these labels come last. ++@end table ++ ++ The Rmail sort commands perform a @emph{stable sort}: if there is no ++reason to prefer either one of two messages, their order remains ++unchanged. You can use this to sort by more than one criterion. For ++example, if you use @code{rmail-sort-by-date} and then ++@code{rmail-sort-by-author}, messages from the same author appear in ++order by date. ++ ++ With a prefix argument, all these commands reverse the order of ++comparison. This means they sort messages from newest to oldest, from ++biggest to smallest, or in reverse alphabetical order. ++ ++ The same keys in the summary buffer run similar functions; for ++example, @kbd{C-c C-s C-l} runs @code{rmail-summary-sort-by-lines}. ++Note that these commands always sort the whole Rmail buffer, even if the ++summary is only showing a subset of messages. ++ ++ Note that you cannot undo a sort, so you may wish to save the Rmail ++buffer before sorting it. ++ ++@node Rmail Display ++@section Display of Messages ++ ++ Rmail reformats the header of each message before displaying it for ++the first time. Reformatting hides uninteresting header fields to ++reduce clutter. You can use the @kbd{t} command to show the entire ++header or to repeat the header reformatting operation. ++ ++@table @kbd ++@item t ++Toggle display of complete header (@code{rmail-toggle-header}). ++@end table ++ ++@vindex rmail-ignored-headers ++@vindex rmail-nonignored-headers ++ Reformatting the header involves deleting most header fields, on the ++grounds that they are not interesting. The variable ++@code{rmail-ignored-headers} holds a regular expression that specifies ++which header fields to hide in this way---if it matches the beginning ++of a header field, that whole field is hidden. However, the variable ++@code{rmail-nonignored-headers} provides a further override: a header ++matching that regular expression is shown even if it matches ++@code{rmail-ignored-headers} too. ++ ++@vindex rmail-displayed-headers ++ As an alternative to the previous two variables, you can set ++@code{rmail-displayed-headers} instead. If non-@code{nil}, this should ++be a regular expression specifying which headers to display. ++ ++@kindex t @r{(Rmail)} ++@findex rmail-toggle-header ++ To see the complete, original header, use the @kbd{t} command ++(@code{rmail-toggle-header}). This discards the reformatted headers of ++the current message and displays it with the original header. Repeating ++@kbd{t} reformats the message again, which shows only the interesting ++headers according to the current values of the above variables. ++Selecting the message again also reformats it if necessary. ++ ++ When the @kbd{t} command has a prefix argument, a positive argument ++means to show the reformatted header, and a zero or negative argument ++means to show the full header. ++ ++@vindex rmail-highlighted-headers ++ Rmail highlights certain header fields that are especially ++interesting---by default, the @samp{From} and @samp{Subject} fields. ++The variable @code{rmail-highlighted-headers} holds a regular expression ++that specifies the header fields to highlight; if it matches the ++beginning of a header field, that whole field is highlighted. To turn ++off this feature, set @code{rmail-highlighted-headers} to @code{nil}. ++Customize the face @code{rmail-highlight} to adjust the style of the ++highlighting. ++ ++ You can highlight and activate URLs in incoming messages using ++Goto Address mode: ++ ++@c FIXME goto-addr.el commentary says to use goto-address instead. ++@smallexample ++(add-hook 'rmail-show-message-hook (lambda () (goto-address-mode 1))) ++@end smallexample ++ ++@noindent ++Then you can browse these URLs by clicking on them with @kbd{Mouse-2} ++(or @kbd{Mouse-1} quickly) or by moving to one and typing @kbd{C-c ++@key{RET}}. @xref{Goto Address mode, Activating URLs, Activating URLs}. ++ ++@cindex MIME messages (Rmail) ++@findex rmail-mime ++@kindex v @r{(Rmail)} ++ The @kbd{v} (@code{rmail-mime}) command creates a temporary buffer ++displaying the current MIME message. By default, it displays plain text ++and multipart messages, and offers buttons to save attachments. ++ ++@node Rmail Coding ++@section Rmail and Coding Systems ++ ++@cindex decoding mail messages (Rmail) ++ Rmail automatically decodes messages which contain non-@acronym{ASCII} ++characters, just as Emacs does with files you visit and with subprocess ++output. Rmail uses the standard @samp{charset=@var{charset}} header in ++the message, if any, to determine how the message was encoded by the ++sender. It maps @var{charset} into the corresponding Emacs coding ++system (@pxref{Coding Systems}), and uses that coding system to decode ++message text. If the message header doesn't have the @samp{charset} ++specification, or if @var{charset} is not recognized, ++Rmail chooses the coding system with the usual Emacs heuristics and ++defaults (@pxref{Recognize Coding}). ++ ++@cindex fixing incorrectly decoded mail messages ++ Occasionally, a message is decoded incorrectly, either because Emacs ++guessed the wrong coding system in the absence of the @samp{charset} ++specification, or because the specification was inaccurate. For ++example, a misconfigured mailer could send a message with a ++@samp{charset=iso-8859-1} header when the message is actually encoded ++in @code{koi8-r}. When you see the message text garbled, or some of ++its characters displayed as empty boxes, this may have happened. ++ ++@findex rmail-redecode-body ++ You can correct the problem by decoding the message again using the ++right coding system, if you can figure out or guess which one is ++right. To do this, invoke the @kbd{M-x rmail-redecode-body} command. ++It reads the name of a coding system, and then redecodes the message ++using the coding system you specified. If you specified the right ++coding system, the result should be readable. ++ ++@node Rmail Editing ++@section Editing Within a Message ++ ++ Most of the usual Emacs keybindings are available in Rmail mode, though a ++few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for ++other purposes. However, the Rmail buffer is normally read only, and ++most of the letters are redefined as Rmail commands. If you want to ++edit the text of a message, you must use the Rmail command @kbd{e}. ++ ++@table @kbd ++@item e ++Edit the current message as ordinary text. ++@end table ++ ++@kindex e @r{(Rmail)} ++@findex rmail-edit-current-message ++ The @kbd{e} command (@code{rmail-edit-current-message}) switches from ++Rmail mode into Rmail Edit mode, another major mode which is nearly the ++same as Text mode. The mode line indicates this change. ++ ++ In Rmail Edit mode, letters insert themselves as usual and the Rmail ++commands are not available. You can edit the message body and header ++fields. When you are finished editing the message, type @kbd{C-c C-c} ++to switch back to Rmail mode. Alternatively, you can return to Rmail ++mode but cancel any editing that you have done, by typing @kbd{C-c C-]}. ++ ++@vindex rmail-edit-mode-hook ++ Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then ++it runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}). ++Returning to ordinary Rmail mode adds the attribute @samp{edited} to ++the message, if you have made any changes in it. ++ ++@node Rmail Digest ++@section Digest Messages ++@cindex digest message ++@cindex undigestify ++ ++ A @dfn{digest message} is a message which exists to contain and carry ++several other messages. Digests are used on some moderated mailing ++lists; all the messages that arrive for the list during a period of time ++such as one day are put inside a single digest which is then sent to the ++subscribers. Transmitting the single digest uses much less computer ++time than transmitting the individual messages even though the total ++size is the same, because the per-message overhead in network mail ++transmission is considerable. ++ ++@findex undigestify-rmail-message ++ When you receive a digest message, the most convenient way to read it is ++to @dfn{undigestify} it: to turn it back into many individual messages. ++Then you can read and delete the individual messages as it suits you. ++To do this, select the digest message and type the command @kbd{M-x ++undigestify-rmail-message}. This extracts the submessages as separate ++Rmail messages, and inserts them following the digest. The digest ++message itself is flagged as deleted. ++ ++@node Rmail Rot13 ++@section Reading Rot13 Messages ++@cindex rot13 code ++ ++ Mailing list messages that might offend some readers are sometimes ++encoded in a simple code called @dfn{rot13}---so named because it ++rotates the alphabet by 13 letters. This code is not for secrecy, as it ++provides none; rather, it enables those who might be offended to avoid ++seeing the real text of the message. ++ ++@findex rot13-other-window ++ To view a buffer which uses the rot13 code, use the command @kbd{M-x ++rot13-other-window}. This displays the current buffer in another window ++which applies the code when displaying the text. ++ ++@node Movemail ++@section @code{movemail} program ++@cindex @code{movemail} program ++ ++ Rmail uses the @code{movemail} program to move mail from your inbox to ++your Rmail file (@pxref{Rmail Inbox}). When loaded for the first time, ++Rmail attempts to locate the @code{movemail} program and determine its ++version. There are two versions of the @code{movemail} program: the ++native one, shipped with GNU Emacs (the ``emacs version'') and the one ++included in GNU mailutils (the ``mailutils version,'' ++@pxref{movemail,,,mailutils,GNU mailutils}). They support the same ++command line syntax and the same basic subset of options. However, the ++Mailutils version offers additional features. ++ ++ The Emacs version of @code{movemail} is able to retrieve mail from the ++usual UNIX mailbox formats and from remote mailboxes using the POP3 ++protocol. ++ ++ The Mailutils version is able to handle a wide set of mailbox ++formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH} ++mailboxes, etc. It is able to access remote mailboxes using the POP3 or ++IMAP4 protocol, and can retrieve mail from them using a TLS encrypted ++channel. It also accepts mailbox arguments in @acronym{URL} form. ++The detailed description of mailbox @acronym{URL}s can be found in ++@ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL} is: ++ ++@smallexample ++@var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name} ++@end smallexample ++ ++@noindent ++where square brackets denote optional elements. ++ ++@table @var ++@item proto ++Specifies the @dfn{mailbox protocol}, or @dfn{format} to ++use. The exact semantics of the rest of @acronym{URL} elements depends ++on the actual value of @var{proto} (see below). ++ ++@item user ++User name to access the remote mailbox. ++ ++@item password ++User password to access the remote mailbox. ++ ++@item host-or-file-name ++Hostname of the remote server for remote mailboxes or file name of a ++local mailbox. ++@end table ++ ++@noindent ++@var{Proto} can be one of: ++ ++@table @code ++@item mbox ++Usual UNIX mailbox format. In this case, neither @var{user} nor ++@var{pass} are used, and @var{host-or-file-name} denotes the file name of ++the mailbox file, e.g., @code{mbox://var/spool/mail/smith}. ++ ++@item mh ++A local mailbox in the @acronym{MH} format. @var{User} and ++@var{pass} are not used. @var{Host-or-file-name} denotes the name of ++@acronym{MH} folder, e.g., @code{mh://Mail/inbox}. ++ ++@item maildir ++A local mailbox in the @acronym{maildir} format. @var{User} and ++@var{pass} are not used, and @var{host-or-file-name} denotes the name of ++@code{maildir} mailbox, e.g., @code{maildir://mail/inbox}. ++ ++@item file ++Any local mailbox format. Its actual format is detected automatically ++by @code{movemail}. ++ ++@item pop ++A remote mailbox to be accessed via POP3 protocol. @var{User} ++specifies the remote user name to use, @var{pass} may be used to ++specify the user password, @var{host-or-file-name} is the name or IP ++address of the remote mail server to connect to; e.g., ++@code{pop://smith:guessme@@remote.server.net}. ++ ++@item imap ++A remote mailbox to be accessed via IMAP4 protocol. @var{User} ++specifies the remote user name to use, @var{pass} may be used to ++specify the user password, @var{host-or-file-name} is the name or IP ++address of the remote mail server to connect to; ++e.g., @code{imap://smith:guessme@@remote.server.net}. ++@end table ++ ++ Alternatively, you can specify the file name of the mailbox to use. ++This is equivalent to specifying the @samp{file} protocol: ++ ++@smallexample ++/var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user} ++@end smallexample ++ ++@vindex rmail-movemail-program ++@vindex rmail-movemail-search-path ++ The variable @code{rmail-movemail-program} controls which version of ++@code{movemail} to use. If that is a string, it specifies the ++absolute file name of the @code{movemail} executable. If it is ++@code{nil}, Rmail searches for @code{movemail} in the directories ++listed in @code{rmail-movemail-search-path} and @code{exec-path}, then ++in @code{exec-directory}. ++ ++@node Remote Mailboxes ++@section Retrieving Mail from Remote Mailboxes ++@pindex movemail ++ ++ Some sites use a method called POP for accessing users' inbox data ++instead of storing the data in inbox files. By default, the @code{Emacs ++movemail} can work with POP (unless the Emacs @code{configure} script ++was run with the option @samp{--without-pop}). ++ ++Similarly, the Mailutils @code{movemail} by default supports POP, unless ++it was configured with the @samp{--disable-pop} option. ++ ++Both versions of @code{movemail} only work with POP3, not with older ++versions of POP. ++ ++@cindex @env{MAILHOST} environment variable ++@cindex POP mailboxes ++ No matter which flavor of @code{movemail} you use, you can specify ++a POP inbox by using a POP @dfn{URL} (@pxref{Movemail}). A POP ++@acronym{URL} is a ``file name'' of the form ++@samp{pop://@var{username}@@@var{hostname}}, where ++@var{hostname} is the host name or IP address of the remote mail ++server and @var{username} is the user name on that server. ++Additionally, you may specify the password in the mailbox @acronym{URL}: ++@samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this ++case, @var{password} takes preference over the one set by ++@code{rmail-remote-password} (see below). This is especially useful ++if you have several remote mailboxes with different passwords. ++ ++ For backward compatibility, Rmail also supports an alternative way of ++specifying remote POP mailboxes. Specifying an inbox name in the form ++@samp{po:@var{username}:@var{hostname}} is equivalent to ++@samp{pop://@var{username}@@@var{hostname}}. If you omit the ++@var{:hostname} part, the @env{MAILHOST} environment variable specifies ++the machine on which to look for the POP server. ++ ++@c FIXME mention --with-hesiod "support Hesiod to get the POP server host"? ++ ++@cindex IMAP mailboxes ++ Another method for accessing remote mailboxes is IMAP. This method is ++supported only by the Mailutils @code{movemail}. To specify an IMAP ++mailbox in the inbox list, use the following mailbox @acronym{URL}: ++@samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The ++@var{password} part is optional, as described above. ++ ++@vindex rmail-remote-password ++@vindex rmail-remote-password-required ++ Accessing a remote mailbox may require a password. Rmail uses the ++following algorithm to retrieve it: ++ ++@enumerate ++@item ++If a @var{password} is present in the mailbox URL (see above), it is ++used. ++@item ++If the variable @code{rmail-remote-password-required} is @code{nil}, ++Rmail assumes no password is required. ++@item ++If the variable @code{rmail-remote-password} is non-@code{nil}, its ++value is used. ++@item ++Otherwise, Rmail will ask you for the password to use. ++@end enumerate ++ ++@vindex rmail-movemail-flags ++ If you need to pass additional command-line flags to @code{movemail}, ++set the variable @code{rmail-movemail-flags} a list of the flags you ++wish to use. Do not use this variable to pass the @samp{-p} flag to ++preserve your inbox contents; use @code{rmail-preserve-inbox} instead. ++ ++@cindex Kerberos POP authentication ++ The @code{movemail} program installed at your site may support ++Kerberos authentication (the Emacs @code{movemail} does so if Emacs was ++configured with the option @code{--with-kerberos} or ++@code{--with-kerberos5}). If it is supported, it is used by default ++whenever you attempt to retrieve POP mail when ++@code{rmail-remote-password} and @code{rmail-remote-password-required} ++are unset. ++ ++@cindex reverse order in POP inboxes ++ Some POP servers store messages in reverse order. If your server does ++this, and you would rather read your mail in the order in which it was ++received, you can tell @code{movemail} to reverse the order of ++downloaded messages by adding the @samp{-r} flag to ++@code{rmail-movemail-flags}. ++ ++@cindex TLS encryption (Rmail) ++ Mailutils @code{movemail} supports TLS encryption. If you wish to ++use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}. ++ ++@node Other Mailbox Formats ++@section Retrieving Mail from Local Mailboxes in Various Formats ++ ++ If your incoming mail is stored on a local machine in a format other ++than UNIX mailbox, you will need the Mailutils @code{movemail} to ++retrieve it. @xref{Movemail}, for the detailed description of ++@code{movemail} versions. For example, to access mail from a inbox in ++@code{maildir} format located in @file{/var/spool/mail/in}, you would ++include the following in the Rmail inbox list: ++ ++@smallexample ++maildir://var/spool/mail/in ++@end smallexample ++ ++@ignore ++ arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23 ++@end ignore +diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi +new file mode 100644 +index 0000000..234bcea +--- /dev/null ++++ b/doc/emacs/screen.texi +@@ -0,0 +1,325 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Screen, User Input, Acknowledgments, Top ++@chapter The Organization of the Screen ++@cindex screen ++@cindex parts of the screen ++ ++ On a text-only terminal, the Emacs display occupies the entire ++terminal screen. On a graphical display, such as on GNU/Linux using ++the X Window System, Emacs creates its own windows to use. We use the ++term @dfn{frame} to mean the entire terminal screen or graphical ++window used by Emacs. Emacs uses both kinds of frames, in the same ++way, to display your editing. Emacs normally starts out with just one ++frame, but you can create additional frames if you wish ++(@pxref{Frames}). ++ ++ The frame consists of several distinct regions. At the top of the ++frame is a @dfn{menu bar}, which allows you to access commands via a ++series of menus. On a graphical display, directly below the menu bar ++is a @dfn{tool bar}, a row of icons that perform editing commands if ++you click on them. At the very bottom of the frame is a special ++@dfn{echo area}, where short informative messages are displayed and ++where you enter information when Emacs asks for it. ++ ++ The main area of the frame, below the tool bar (if one exists) and ++above the echo area, is called @dfn{the window}. This is where Emacs ++displays the @dfn{buffer}: the text that you are editing. On a ++graphical display, the window possesses a @dfn{scroll bar} on one ++side, which you can use to display different parts of the buffer in ++the window. The last line of the window is a @dfn{mode line}. This ++displays various information about what is going on in the buffer, ++such as whether there are unsaved changes, the editing modes that are ++in use, the current line number, and so forth. ++ ++ When you start Emacs, there is normally only one window in the ++frame. However, you can subdivide this window horizontally or ++vertically to create multiple windows, each of which can independently ++display a buffer (@pxref{Windows}). In this manual, the word ++``window'' refers to the initial large window if not subdivided, or ++any one of the multiple windows you have subdivided it into. ++ ++ At any time, one window is the @dfn{selected window}. On graphical ++displays, the selected window normally shows a more prominent cursor ++(usually solid and blinking) while other windows show a weaker cursor ++(such as a hollow box). Text terminals have just one cursor, so it ++always appears in the selected window. The buffer displayed in the ++selected window is called the @dfn{current buffer}, and it is where ++editing happens. Most Emacs commands implicitly apply to the current ++buffer; the text displayed in unselected windows is mostly visible for ++reference. If you use multiple frames on a graphical display, ++selecting a particular frame selects a window in that frame. ++ ++@menu ++* Point:: The place in the text where editing commands operate. ++* Echo Area:: Short messages appear at the bottom of the screen. ++* Mode Line:: Interpreting the mode line. ++* Menu Bar:: How to use the menu bar. ++@end menu ++ ++@node Point ++@section Point ++@cindex point ++@cindex cursor ++ ++ The active cursor shows the location at which editing commands will ++take effect, which is called @dfn{point}@footnote{The term ``point'' ++comes from the character @samp{.}, which was the command in TECO (the ++language in which the original Emacs was written) for accessing the ++value now called ``point.''}. Many Emacs commands move point to ++different places in the buffer; for example, you can place point by ++clicking mouse button 1 (normally the left button) at the desired ++location. ++ ++ While the cursor appears to be @emph{on} a character, you should ++think of point as @emph{between} two characters; it points @emph{before} ++the character that appears under the cursor. For example, if your text ++looks like @samp{frob} with the cursor over the @samp{b}, then point is ++between the @samp{o} and the @samp{b}. If you insert the character ++@samp{!} at that position, the result is @samp{fro!b}, with point ++between the @samp{!} and the @samp{b}. Thus, the cursor remains over ++the @samp{b}, as before. ++ ++ Sometimes people speak of ``the cursor'' when they mean ``point,'' or ++speak of commands that move point as ``cursor motion'' commands. ++ ++ If you are editing several files in Emacs, each in its own buffer, ++each buffer has its own point location. A buffer that is not ++currently displayed remembers its point location in case you display ++it again later. When Emacs displays multiple windows, each window has ++its own point location. If the same buffer appears in more than one ++window, each window has its own point position in that buffer. ++ ++ On a graphical display, Emacs shows a cursor in each window; the ++selected window's cursor is solid and blinking, and the other cursors ++are hollow. On a text-only terminal, there is just one cursor, in the ++selected window; even though the unselected windows have their own ++point positions, they do not display a cursor. @xref{Cursor Display}, ++for customizable variables that control cursor display. ++ ++@node Echo Area ++@section The Echo Area ++@cindex echo area ++ ++ The line at the very bottom of the frame is the @dfn{echo area}. It ++is used to display small amounts of text for various purposes. ++ ++ @dfn{Echoing} means displaying the characters that you type. ++Single-character commands, including most simple editing operations, ++are not echoed. Multi-character commands are echoed if you pause ++while typing them: if you pause for more than a second in the middle ++of a command, Emacs echoes all the characters of the command so far, ++to prompt you for the rest of the command. The echoed characters are ++displayed in the echo area. Once echoing has started, the rest of the ++command echoes immediately as you type it. This behavior is designed ++to give confident users fast response, while giving hesitant users ++maximum feedback. @xref{Display Custom}. ++ ++@cindex error message in the echo area ++ If a command cannot do its job, it may display an @dfn{error ++message}. Error messages are also displayed in the echo area. They ++may be accompanied by beeping or by flashing the screen. ++ ++ Some commands display informative messages in the echo area. Unlike ++error messages, these messages are not announced with a beep or flash. ++Sometimes the message tells you what the command has done, when this ++is not obvious from looking at the text being edited. Other times, ++the sole purpose of a command is to show you a message giving you ++specific information. For example, @kbd{C-x =} (hold down @key{CTRL} ++and type @kbd{x}, then let go of @key{CTRL} and type @kbd{=}) displays ++a message describing the character position of point in the text and ++its current column in the window. Commands that take a long time ++often display messages ending in @samp{...} while they are working, ++and add @samp{done} at the end when they are finished. They may also ++indicate progress with percentages. ++ ++@cindex @samp{*Messages*} buffer ++@cindex saved echo area messages ++@cindex messages saved from echo area ++@vindex message-log-max ++ Informative echo-area messages are saved in a special buffer named ++@samp{*Messages*}. (We have not explained buffers yet; see ++@ref{Buffers}, for more information about them.) If you miss a ++message that appeared briefly on the screen, you can switch to the ++@samp{*Messages*} buffer to see it again. The @samp{*Messages*} ++buffer is limited to a certain number of lines, specified by the ++variable @code{message-log-max}. (We have not explained variables ++either; see @ref{Variables}, for more information about them.) Beyond ++this limit, one line is deleted from the beginning whenever a new ++message line is added at the end. ++ ++@cindex minibuffer ++ The echo area is also used to display the @dfn{minibuffer}, a ++special window where you can input arguments to commands, such as the ++name of a file to be edited. When the minibuffer is in use, the text ++displayed in the echo area begins with a @dfn{prompt string} (usually ++ending with a colon); also, the active cursor appears within the ++minibuffer, which is temporarily considered the selected window. You ++can always get out of the minibuffer by typing @kbd{C-g}. ++@xref{Minibuffer}. ++ ++@node Mode Line ++@section The Mode Line ++@cindex mode line ++@cindex top level ++ ++ At the bottom of each window is a @dfn{mode line}, which describes ++what is going on in the current buffer. When there is only one ++window, the mode line appears right above the echo area; it is the ++next-to-last line in the frame. On a graphical display, the mode line ++is drawn with a 3D box appearance, and the mode line of the selected ++window has a brighter color than that of unselected windows to make it ++stand out. On a text-only terminal, the mode line is usually drawn in ++inverse video. ++ ++ The text displayed in the mode line has the following format: ++ ++@example ++-@var{cs}:@var{ch}-@var{fr} @var{buf} @var{pos} @var{line} (@var{major} @var{minor})------ ++@end example ++ ++@noindent ++The @var{cs} string and the colon character after it describe the ++character set and newline convention used for the current buffer. ++Normally, Emacs handles these settings intelligently, but it is ++sometimes useful to have this information. ++ ++ @var{cs} describes the character set of the buffer (@pxref{Coding ++Systems}). If it is a dash (@samp{-}), that indicates the default ++state of affairs: no special character set handling, except for the ++end-of-line translations described in the next paragraph. @samp{=} ++means no conversion whatsoever. Letters represent various nontrivial ++@dfn{coding systems}---for example, @samp{1} represents ISO Latin-1. ++On a text-only terminal, @var{cs} is preceded by two additional ++characters that describe the coding system for keyboard input and the ++coding system for terminal output. Furthermore, if you are using an ++input method, @var{cs} is preceded by a string that identifies the ++input method, which takes the form @samp{@var{i}>}, @samp{@var{i}+}, ++or @samp{@var{i}@@} (@pxref{Input Methods}). ++ ++@cindex end-of-line conversion, mode-line indication ++ The character after @var{cs} is usually a colon. However, under ++some circumstances a different string is displayed, which indicates a ++nontrivial end-of-line convention. Usually, lines of text are ++separated by @dfn{newline characters}, but two other conventions are ++sometimes used. The MS-DOS convention is to use a ``carriage-return'' ++character followed by a ``linefeed'' character; when editing such ++files, the colon changes to either a backslash (@samp{\}) or ++@samp{(DOS)}, depending on the operating system. The Macintosh ++end-of-line convention is to use a ``carriage-return'' character ++instead of a newline; when editing such files, the colon indicator ++changes to either a forward slash (@samp{/}) or @samp{(Mac)}. On some ++systems, Emacs displays @samp{(Unix)} instead of the colon for files ++that use newline as the line separator. ++ ++ The next element on the mode line is the string indicated by ++@var{ch}. This shows two dashes (@samp{--}) if the buffer displayed ++in the window has the same contents as the corresponding file on the ++disk; i.e., if the buffer is ``unmodified''. If the buffer is ++modified, it shows two stars (@samp{**}). For a read-only buffer, it ++shows @samp{%*} if the buffer is modified, and @samp{%%} otherwise. ++ ++ The character after @var{ch} is normally a dash (@samp{-}). ++However, if the default-directory for the current buffer is on a ++remote machine, @samp{@@} is displayed instead (@pxref{File Names}). ++ ++ @var{fr} gives the selected frame name (@pxref{Frames}). It appears ++only on text-only terminals. The initial frame's name is @samp{F1}. ++ ++ @var{buf} is the name of the buffer displayed in the window. ++Usually, this is the same as the name of a file you are editing. ++@xref{Buffers}. ++ ++ @var{pos} tells you whether there is additional text above the top of ++the window, or below the bottom. If your buffer is small and it is all ++visible in the window, @var{pos} is @samp{All}. Otherwise, it is ++@samp{Top} if you are looking at the beginning of the buffer, @samp{Bot} ++if you are looking at the end of the buffer, or @samp{@var{nn}%}, where ++@var{nn} is the percentage of the buffer above the top of the window. ++With Size Indication mode, you can display the size of the buffer as ++well. @xref{Optional Mode Line}. ++ ++ @var{line} is the character @samp{L} followed by the line number at ++point. (You can display the current column number too, by turning on ++Column Number mode. @xref{Optional Mode Line}.) ++ ++ @var{major} is the name of the @dfn{major mode} used in the buffer. ++A major mode is a principal editing mode for the buffer, such as Text ++mode, Lisp mode, C mode, and so forth. @xref{Major Modes}. ++ ++ Some major modes display additional information after the major mode ++name. For example, Rmail buffers display the current message number and ++the total number of messages. Compilation buffers and Shell buffers ++display the status of the subprocess. ++ ++ @var{minor} is a list of some of the @dfn{minor modes} turned on in ++the buffer. Minor modes are optional editing modes that provide ++additional features on top of the major mode. @xref{Minor Modes}. ++ ++ Some features are listed together with the minor modes whenever they ++are turned on, even through they are not really minor modes. ++@samp{Narrow} means that the buffer being displayed has editing ++restricted to only a portion of its text (@pxref{Narrowing}). ++@samp{Def} means that a keyboard macro is currently being defined ++(@pxref{Keyboard Macros}). ++ ++ In addition, if Emacs is inside a recursive editing level, square ++brackets (@samp{[@dots{}]}) appear around the parentheses that ++surround the modes. If Emacs is in one recursive editing level within ++another, double square brackets appear, and so on. Since recursive ++editing levels affect Emacs globally, not just one buffer, the square ++brackets appear in every window's mode line or not in any of them. ++@xref{Recursive Edit}.@refill ++ ++ You can change the appearance of the mode line as well as the format ++of its contents. @xref{Optional Mode Line}. In addition, the mode ++line is mouse-sensitive; clicking on different parts of the mode line ++performs various commands. @xref{Mode Line Mouse}. ++ ++@node Menu Bar ++@section The Menu Bar ++@cindex menu bar ++ ++ Each Emacs frame normally has a @dfn{menu bar} at the top which you ++can use to perform common operations. There's no need to list them ++here, as you can more easily see them yourself. ++ ++@kindex M-` ++@kindex F10 ++@findex tmm-menubar ++@findex menu-bar-open ++ On a graphical display, you can use the mouse to choose a command ++from the menu bar. A right-arrow at the end of a menu item means it ++leads to a subsidiary menu, or @dfn{submenu}. A @samp{...} at the end ++of a menu item means that the command invoked will prompt you for ++further input before it actually does anything. ++ ++ Some of the commands in the menu bar have ordinary key bindings as ++well; if so, a key binding is shown in parentheses after the item ++itself. To view the full command name and documentation for a menu ++item, type @kbd{C-h k}, and then select the menu bar with the mouse in ++the usual way (@pxref{Key Help}). ++ ++ Instead of using the mouse, you can also invoke the first menu bar ++item by pressing @key{F10} (to run the command @code{menu-bar-open}). ++You can then navigate the menus with the arrow keys. To activate a ++selected menu item, press @key{RET}; to cancel menu navigation, press ++@key{ESC}. ++ ++ On text-only terminals with no mouse, you can use the menu bar by ++typing @kbd{M-`} or @key{F10} (these run the command ++@code{tmm-menubar}). This lets you select a menu item with the ++keyboard. A provisional choice appears in the echo area. You can use ++the up and down arrow keys to move through the menu to different ++items, and then you can type @key{RET} to select the item. ++ ++ Each menu item also has an assigned letter or digit which designates ++that item; it is usually the initial of some word in the item's name. ++This letter or digit is separated from the item name by @samp{=>}. You ++can type the item's letter or digit to select the item. ++ ++@ignore ++ arch-tag: 104ba40e-d972-4866-a542-a98be94bdf2f ++@end ignore +diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi +new file mode 100644 +index 0000000..304ca1c +--- /dev/null ++++ b/doc/emacs/search.texi +@@ -0,0 +1,1371 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Search, Fixit, Display, Top ++@chapter Searching and Replacement ++@cindex searching ++@cindex finding strings within text ++ ++ Like other editors, Emacs has commands to search for occurrences of ++a string. Emacs also has commands to replace occurrences of a string ++with a different string. There are also commands that do the same ++thing, but search for patterns instead of fixed strings. ++ ++ You can also search multiple files under the control of a tags table ++(@pxref{Tags Search}) or through the Dired @kbd{A} command ++(@pxref{Operating on Files}), or ask the @code{grep} program to do it ++(@pxref{Grep Searching}). ++ ++ ++@menu ++* Incremental Search:: Search happens as you type the string. ++* Nonincremental Search:: Specify entire string and then search. ++* Word Search:: Search for sequence of words. ++* Regexp Search:: Search for match for a regexp. ++* Regexps:: Syntax of regular expressions. ++* Regexp Backslash:: Regular expression constructs starting with `\'. ++* Regexp Example:: A complex regular expression explained. ++* Search Case:: To ignore case while searching, or not. ++* Replace:: Search, and replace some or all matches. ++* Other Repeating Search:: Operating on all matches for some regexp. ++@end menu ++ ++@node Incremental Search ++@section Incremental Search ++@cindex incremental search ++@cindex isearch ++ ++ The principal search command in Emacs is @dfn{incremental}: it ++begins searching as soon as you type the first character of the search ++string. As you type in the search string, Emacs shows you where the ++string (as you have typed it so far) would be found. When you have ++typed enough characters to identify the place you want, you can stop. ++Depending on what you plan to do next, you may or may not need to ++terminate the search explicitly with @key{RET}. ++ ++@table @kbd ++@item C-s ++Incremental search forward (@code{isearch-forward}). ++@item C-r ++Incremental search backward (@code{isearch-backward}). ++@end table ++ ++@menu ++* Basic Isearch:: Basic incremental search commands. ++* Repeat Isearch:: Searching for the same string again. ++* Error in Isearch:: When your string is not found. ++* Special Isearch:: Special input in incremental search. ++* Isearch Yank:: Commands that grab text into the search string ++ or else edit the search string. ++* Isearch Scroll:: Scrolling during an incremental search. ++* Isearch Minibuffer:: Incremental search of the minibuffer history. ++* Slow Isearch:: Incremental search features for slow terminals. ++@end menu ++ ++@node Basic Isearch ++@subsection Basics of Incremental Search ++ ++@table @kbd ++@item C-s ++Begin incremental search (@code{isearch-forward}). ++@item C-r ++Begin reverse incremental search (@code{isearch-backward}). ++@end table ++ ++@kindex C-s ++@findex isearch-forward ++ @kbd{C-s} (@code{isearch-forward}) starts a forward incremental ++search. It reads characters from the keyboard, and moves point just ++past the end of the next occurrence of those characters in the buffer. ++ ++ For instance, if you type @kbd{C-s} and then @kbd{F}, that puts the ++cursor after the first @samp{F} that occurs in the buffer after the ++starting point. Then if you then type @kbd{O}, the cursor moves to ++just after the first @samp{FO}; the @samp{F} in that @samp{FO} might ++not be the first @samp{F} previously found. After another @kbd{O}, ++the cursor moves to just after the first @samp{FOO}. ++ ++@cindex faces for highlighting search matches ++ At each step, Emacs highlights the @dfn{current match}---the buffer ++text that matches the search string---using the @code{isearch} face ++(@pxref{Faces}). The current search string is also displayed in the ++echo area. ++ ++ If you make a mistake typing the search string, type @key{DEL}. ++Each @key{DEL} cancels the last character of the search string. ++ ++ When you are satisfied with the place you have reached, type ++@key{RET}. This stops searching, leaving the cursor where the search ++brought it. Also, any command not specially meaningful in searches ++stops the searching and is then executed. Thus, typing @kbd{C-a} ++exits the search and then moves to the beginning of the line. ++@key{RET} is necessary only if the next command you want to type is a ++printing character, @key{DEL}, @key{RET}, or another character that is ++special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, ++@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others ++described below). ++ ++ As a special exception, entering @key{RET} when the search string is ++empty launches nonincremental search (@pxref{Nonincremental Search}). ++ ++ When you exit the incremental search, it adds the original value of ++point to the mark ring, without activating the mark; you can thus use ++@kbd{C-u C-@key{SPC}} to return to where you were before beginning the ++search. @xref{Mark Ring}. It only does this if the mark was not ++already active. ++ ++@kindex C-r ++@findex isearch-backward ++ To search backwards, use @kbd{C-r} (@code{isearch-backward}) instead ++of @kbd{C-s} to start the search. A backward search finds matches ++that end before the starting point, just as a forward search finds ++matches that begin after it. ++ ++@node Repeat Isearch ++@subsection Repeating Incremental Search ++ ++ Suppose you search forward for @samp{FOO} and find a match, but not ++the one you expected to find: the @samp{FOO} you were aiming for ++occurs later in the buffer. In this event, type another @kbd{C-s} to ++move to the next occurrence of the search string. You can repeat this ++any number of times. If you overshoot, you can cancel some @kbd{C-s} ++characters with @key{DEL}. Similarly, each @kbd{C-r} in a backward ++incremental search repeats the backward search. ++ ++@cindex lazy search highlighting ++@vindex isearch-lazy-highlight ++ If you pause for a little while during incremental search, Emacs ++highlights all the other possible matches for the search string that ++are present on the screen. This helps you anticipate where you can ++get to by typing @kbd{C-s} or @kbd{C-r} to repeat the search. The ++other matches are highlighted differently from the current match, ++using the customizable face @code{lazy-highlight} (@pxref{Faces}). If ++you don't like this feature, you can disable it by setting ++@code{isearch-lazy-highlight} to @code{nil}. ++ ++ After exiting a search, you can search for the same string again by ++typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that ++invokes incremental search, and the second @kbd{C-s} means ``search ++again.'' Similarly, @kbd{C-r C-r} searches backward for the last ++search string. In determining the last search string, it doesn't ++matter whether the string was searched for with @kbd{C-s} or ++@kbd{C-r}. ++ ++ If you are searching forward but you realize you were looking for ++something before the starting point, type @kbd{C-r} to switch to a ++backward search, leaving the search string unchanged. Similarly, ++@kbd{C-s} in a backward search switches to a forward search. ++ ++ If a search is failing and you ask to repeat it by typing another ++@kbd{C-s}, it starts again from the beginning of the buffer. ++Repeating a failing reverse search with @kbd{C-r} starts again from ++the end. This is called @dfn{wrapping around}, and @samp{Wrapped} ++appears in the search prompt once this has happened. If you keep on ++going past the original starting point of the search, it changes to ++@samp{Overwrapped}, which means that you are revisiting matches that ++you have already seen. ++ ++@cindex search ring ++ To reuse earlier search strings, use the @dfn{search ring}. The ++commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a ++search string to reuse. These commands leave the selected search ring ++element in the minibuffer, where you can edit it. To edit the current ++search string in the minibuffer without replacing it with items from ++the search ring, type @kbd{M-e}. Type @kbd{C-s} or @kbd{C-r} to ++terminate editing the string and search for it. ++ ++@node Error in Isearch ++@subsection Errors in Incremental Search ++ ++ If your string is not found at all, the echo area says @samp{Failing ++I-Search}. The cursor is after the place where Emacs found as much of ++your string as it could. Thus, if you search for @samp{FOOT}, and ++there is no @samp{FOOT}, you might see the cursor after the @samp{FOO} ++in @samp{FOOL}. In the echo area, the part of the search string that ++failed to match is highlighted using the customizable face ++@code{isearch-fail}. ++ ++ At this point, there are several things you can do. If your string ++was mistyped, you can use @key{DEL} to erase some of it and correct ++it. If you like the place you have found, you can type @key{RET} to ++remain there. Or you can type @kbd{C-g}, which removes from the ++search string the characters that could not be found (the @samp{T} in ++@samp{FOOT}), leaving those that were found (the @samp{FOO} in ++@samp{FOOT}). A second @kbd{C-g} at that point cancels the search ++entirely, returning point to where it was when the search started. ++ ++@cindex quitting (in search) ++ The quit command, @kbd{C-g}, does special things during searches; ++just what it does depends on the status of the search. If the search ++has found what you specified and is waiting for input, @kbd{C-g} ++cancels the entire search, moving the cursor back to where you started ++the search. If @kbd{C-g} is typed when there are characters in the ++search string that have not been found---because Emacs is still ++searching for them, or because it has failed to find them---then the ++search string characters which have not been found are discarded from ++the search string. With them gone, the search is now successful and ++waiting for more input, so a second @kbd{C-g} will cancel the entire ++search. ++ ++@node Special Isearch ++@subsection Special Input for Incremental Search ++ ++ Some of the characters you type during incremental search have ++special effects. ++ ++ If the search string you entered contains only lower-case letters, ++the search is case-insensitive; as long as an upper-case letter exists ++in the search string, the search becomes case-sensitive. If you ++delete the upper-case character from the search string, it ceases to ++have this effect. @xref{Search Case}. ++ ++ To search for a newline character, type @kbd{C-j}. ++ ++ To search for other control characters, such as @key{control-S}, ++quote it by typing @kbd{C-q} first (@pxref{Inserting Text}). To ++search for non-@acronym{ASCII} characters, you can either use ++@kbd{C-q} and enter its octal code, or use an input method ++(@pxref{Input Methods}). If an input method is enabled in the current ++buffer when you start the search, you can use it in the search string ++also. While typing the search string, you can toggle the input method ++with the command @kbd{C-\} (@code{isearch-toggle-input-method}). You ++can also turn on a non-default input method with @kbd{C-^} ++(@code{isearch-toggle-specified-input-method}), which prompts for the ++name of the input method. When an input method is active during ++incremental search, the search prompt includes the input method ++mnemonic, like this: ++ ++@example ++I-search [@var{im}]: ++@end example ++ ++@noindent ++@findex isearch-toggle-input-method ++@findex isearch-toggle-specified-input-method ++where @var{im} is the mnemonic of the active input method. Any input ++method you enable during incremental search remains enabled in the ++current buffer afterwards. ++ ++@kindex M-% @r{(Incremental search)} ++ Typing @kbd{M-%} in incremental search invokes @code{query-replace} ++or @code{query-replace-regexp} (depending on search mode) with the ++current search string used as the string to replace. @xref{Query ++Replace}. ++ ++@kindex M-TAB @r{(Incremental search)} ++ Typing @kbd{M-@key{TAB}} in incremental search invokes ++@code{isearch-complete}, which attempts to complete the search string ++using the search ring as a list of completion alternatives. ++@xref{Completion}. In many operating systems, the @kbd{M-@key{TAB}} ++key sequence is captured by the window manager; you then need to ++rebind @code{isearch-complete} to another key sequence if you want to ++use it (@pxref{Rebinding}). ++ ++@vindex isearch-mode-map ++ When incremental search is active, you can type @kbd{C-h C-h} to ++access interactive help options, including a list of special ++keybindings. These keybindings are part of the keymap ++@code{isearch-mode-map} (@pxref{Keymaps}). ++ ++@node Isearch Yank ++@subsection Isearch Yanking ++ ++ Within incremental search, you can use @kbd{C-w} and @kbd{C-y} to grab ++text from the buffer into the search string. This makes it convenient ++to search for another occurrence of text at point. ++ ++ @kbd{C-w} copies the character or word after point and adds it to ++the search string, advancing point over it. (The decision, whether to ++copy a character or a word, is heuristic.) ++ ++ @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the ++current line into the search string. If point is already at the end ++of a line, it grabs the entire next line. If the search is currently ++case-insensitive, both @kbd{C-y} and @kbd{C-w} convert the text they ++copy to lower case, so that the search remains case-insensitive. ++ ++ @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one ++character at a time: @kbd{C-M-w} deletes the last character from the ++search string and @kbd{C-M-y} copies the character after point to the ++end of the search string. An alternative method to add the character ++after point into the search string is to enter the minibuffer by ++@kbd{M-e} and to type @kbd{C-f} at the end of the search string in the ++minibuffer. ++ ++ The character @kbd{M-y} copies text from the kill ring into the ++search string. It uses the same text that @kbd{C-y} would yank. ++@kbd{Mouse-2} in the echo area does the same. @xref{Yanking}. ++ ++@node Isearch Scroll ++@subsection Scrolling During Incremental Search ++ ++@vindex isearch-allow-scroll ++ You can enable the use of vertical scrolling during incremental ++search (without exiting the search) by setting the customizable ++variable @code{isearch-allow-scroll} to a non-@code{nil} value. This ++applies to using the vertical scroll-bar and to certain keyboard ++commands such as @key{prior} (@code{scroll-down}), @key{next} ++(@code{scroll-up}) and @kbd{C-l} (@code{recenter}). You must run ++these commands via their key sequences to stay in the search---typing ++@kbd{M-x} will terminate the search. You can give prefix arguments to ++these commands in the usual way. ++ ++ This feature won't let you scroll the current match out of visibility, ++however. ++ ++ The feature also affects some other commands, such as @kbd{C-x 2} ++(@code{split-window-vertically}) and @kbd{C-x ^} ++(@code{enlarge-window}) which don't exactly scroll but do affect where ++the text appears on the screen. In general, it applies to any command ++whose name has a non-@code{nil} @code{isearch-scroll} property. So you ++can control which commands are affected by changing these properties. ++ ++ For example, to make @kbd{C-h l} usable within an incremental search ++in all future Emacs sessions, use @kbd{C-h c} to find what command it ++runs. (You type @kbd{C-h c C-h l}; it says @code{view-lossage}.) ++Then you can put the following line in your @file{.emacs} file ++(@pxref{Init File}): ++ ++@example ++(put 'view-lossage 'isearch-scroll t) ++@end example ++ ++@noindent ++This feature can be applied to any command that doesn't permanently ++change point, the buffer contents, the match data, the current buffer, ++or the selected window and frame. The command must not itself attempt ++an incremental search. ++ ++@node Isearch Minibuffer ++@subsection Searching the Minibuffer ++@cindex minibuffer history, searching ++ ++If you start an incremental search while the minibuffer is active, ++Emacs searches the contents of the minibuffer. Unlike searching an ++ordinary buffer, the search string is not shown in the echo area, ++because that is used to display the minibuffer. ++ ++If an incremental search fails in the minibuffer, it tries searching ++the minibuffer history. @xref{Minibuffer History}. You can visualize ++the minibuffer and its history as a series of ``pages'', with the ++earliest history element on the first page and the current minibuffer ++on the last page. A forward search, @kbd{C-s}, searches forward to ++later pages; a reverse search, @kbd{C-r}, searches backwards to ++earlier pages. Like in ordinary buffer search, a failing search can ++wrap around, going from the last page to the first page or vice versa. ++ ++When the current match is on a history element, that history element ++is pulled into the minibuffer. If you exit the incremental search ++normally (e.g. by typing @key{RET}), it remains in the minibuffer ++afterwards. Cancelling the search, with @kbd{C-g}, restores the ++contents of the minibuffer when you began the search. ++ ++@node Slow Isearch ++@subsection Slow Terminal Incremental Search ++ ++ Incremental search on a slow terminal uses a modified style of display ++that is designed to take less time. Instead of redisplaying the buffer at ++each place the search gets to, it creates a new single-line window and uses ++that to display the line that the search has found. The single-line window ++comes into play as soon as point moves outside of the text that is already ++on the screen. ++ ++ When you terminate the search, the single-line window is removed. ++Emacs then redisplays the window in which the search was done, to show ++its new position of point. ++ ++@vindex search-slow-speed ++ The slow terminal style of display is used when the terminal baud rate is ++less than or equal to the value of the variable @code{search-slow-speed}, ++initially 1200. See also the discussion of the variable @code{baud-rate} ++(@pxref{baud-rate,, Customization of Display}). ++ ++@vindex search-slow-window-lines ++ The number of lines to use in slow terminal search display is controlled ++by the variable @code{search-slow-window-lines}. Its normal value is 1. ++ ++@node Nonincremental Search ++@section Nonincremental Search ++@cindex nonincremental search ++ ++ Emacs also has conventional nonincremental search commands, which require ++you to type the entire search string before searching begins. ++ ++@table @kbd ++@item C-s @key{RET} @var{string} @key{RET} ++Search for @var{string}. ++@item C-r @key{RET} @var{string} @key{RET} ++Search backward for @var{string}. ++@end table ++ ++ To start a nonincremental search, first type @kbd{C-s @key{RET}}. ++This enters the minibuffer to read the search string; terminate the ++string with @key{RET}, and then the search takes place. If the string ++is not found, the search command signals an error. ++ ++ When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental ++search as usual. That command is specially programmed to invoke ++nonincremental search, @code{search-forward}, if the string you ++specify is empty. (Such an empty argument would otherwise be ++useless.) @kbd{C-r @key{RET}} does likewise, for a reverse ++incremental search. ++ ++@findex search-forward ++@findex search-backward ++ Forward and backward nonincremental searches are implemented by the ++commands @code{search-forward} and @code{search-backward}. These ++commands may be bound to other keys in the usual manner. ++ ++@node Word Search ++@section Word Search ++@cindex word search ++ ++ A @dfn{word search} finds a sequence of words without regard to the ++type of punctuation between them. For instance, if you enter a search ++string that consists of two words separated by a single space, the ++search matches any sequence of those two words separated by one or ++more spaces, newlines, or other punctuation characters. This is ++particularly useful for searching text documents, because you don't ++have to worry whether the words you are looking for are separated by ++newlines or spaces. ++ ++@table @kbd ++@item M-s w ++If incremental search is active, toggle word search mode ++(@code{isearch-toggle-word}); otherwise, begin an incremental forward ++word search (@code{isearch-forward-word}). ++@item M-s w @key{RET} @var{words} @key{RET} ++Search for @var{words}, using a forward nonincremental word search. ++@item M-s w C-r @key{RET} @var{words} @key{RET} ++Search backward for @var{words}, using a nonincremental word search. ++@end table ++ ++@kindex M-s w ++@findex isearch-forward-word ++ To begin a forward incremental word search, type @kbd{M-s w}. If ++incremental search is not already active, this runs the command ++@code{isearch-forward-word}. If incremental search is already active ++(whether a forward or backward search), @kbd{M-s w} switches to a word ++search while keeping the direction of the search and the current ++search string unchanged. You can toggle word search back off by ++typing @kbd{M-s w} again. ++ ++@findex word-search-forward ++@findex word-search-backward ++ To begin a nonincremental word search, type @kbd{M-s w @key{RET}} ++for a forward search, or @kbd{M-s w C-r @key{RET}} for a backward search. ++These run the commands @code{word-search-forward} and ++@code{word-search-backward} respectively. ++ ++ A nonincremental word search differs slightly from the incremental ++version in the way it finds a match: the last word in the search ++string must be an exact match for a whole word. In an incremental ++word search, the last word in the search string can match part of a ++word; this allows the matching to proceed incrementally as you type. ++ ++@node Regexp Search ++@section Regular Expression Search ++@cindex regular expression ++@cindex regexp ++ ++ A @dfn{regular expression} (or @dfn{regexp} for short) is a pattern ++that denotes a class of alternative strings to match. GNU Emacs ++provides both incremental and nonincremental ways to search for a ++match for a regexp. The syntax of regular expressions is explained in ++the following section. ++ ++@table @kbd ++@item C-M-s ++Begin incremental regexp search (@code{isearch-forward-regexp}). ++@item C-M-r ++Begin reverse incremental regexp search (@code{isearch-backward-regexp}). ++@end table ++ ++@kindex C-M-s ++@findex isearch-forward-regexp ++@kindex C-M-r ++@findex isearch-backward-regexp ++ Incremental search for a regexp is done by typing @kbd{C-M-s} ++(@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a ++prefix argument (whose value does not matter), or by typing @kbd{M-r} ++within a forward incremental search. This command reads a ++search string incrementally just like @kbd{C-s}, but it treats the ++search string as a regexp rather than looking for an exact match ++against the text in the buffer. Each time you add text to the search ++string, you make the regexp longer, and the new regexp is searched ++for. To search backward for a regexp, use @kbd{C-M-r} ++(@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, ++or @kbd{M-r} within a backward incremental search. ++ ++ All of the special key sequences in an ordinary incremental search ++do similar things in an incremental regexp search. For instance, ++typing @kbd{C-s} immediately after starting the search retrieves the ++last incremental search regexp used and searches forward for it. ++Incremental regexp and non-regexp searches have independent defaults. ++They also have separate search rings, which you can access with ++@kbd{M-p} and @kbd{M-n}. ++ ++@vindex search-whitespace-regexp ++ If you type @key{SPC} in incremental regexp search, it matches any ++sequence of whitespace characters, including newlines. If you want to ++match just a space, type @kbd{C-q @key{SPC}}. You can control what a ++bare space matches by setting the variable ++@code{search-whitespace-regexp} to the desired regexp. ++ ++ In some cases, adding characters to the regexp in an incremental ++regexp search can make the cursor move back and start again. For ++example, if you have searched for @samp{foo} and you add @samp{\|bar}, ++the cursor backs up in case the first @samp{bar} precedes the first ++@samp{foo}. @xref{Regexps}. ++ ++ Forward and backward regexp search are not symmetrical, because ++regexp matching in Emacs always operates forward, starting with the ++beginning of the regexp. Thus, forward regexp search scans forward, ++trying a forward match at each possible starting position. Backward ++regexp search scans backward, trying a forward match at each possible ++starting position. These search methods are not mirror images. ++ ++@findex re-search-forward ++@findex re-search-backward ++ Nonincremental search for a regexp is done by the functions ++@code{re-search-forward} and @code{re-search-backward}. You can ++invoke these with @kbd{M-x}, or by way of incremental regexp search ++with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}. ++ ++ If you use the incremental regexp search commands with a prefix ++argument, they perform ordinary string search, like ++@code{isearch-forward} and @code{isearch-backward}. @xref{Incremental ++Search}. ++ ++@node Regexps ++@section Syntax of Regular Expressions ++@cindex syntax of regexps ++ ++ This manual describes regular expression features that users ++typically want to use. There are additional features that are ++mainly used in Lisp programs; see @ref{Regular Expressions,,, ++elisp, The Emacs Lisp Reference Manual}. ++ ++ Regular expressions have a syntax in which a few characters are ++special constructs and the rest are @dfn{ordinary}. An ordinary ++character is a simple regular expression which matches that same ++character and nothing else. The special characters are @samp{$}, ++@samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, and ++@samp{\}. The character @samp{]} is special if it ends a character ++alternative (see later). The character @samp{-} is special inside a ++character alternative. Any other character appearing in a regular ++expression is ordinary, unless a @samp{\} precedes it. (When you use ++regular expressions in a Lisp program, each @samp{\} must be doubled, ++see the example near the end of this section.) ++ ++ For example, @samp{f} is not a special character, so it is ordinary, and ++therefore @samp{f} is a regular expression that matches the string ++@samp{f} and no other string. (It does @emph{not} match the string ++@samp{ff}.) Likewise, @samp{o} is a regular expression that matches ++only @samp{o}. (When case distinctions are being ignored, these regexps ++also match @samp{F} and @samp{O}, but we consider this a generalization ++of ``the same string,'' rather than an exception.) ++ ++ Any two regular expressions @var{a} and @var{b} can be concatenated. The ++result is a regular expression which matches a string if @var{a} matches ++some amount of the beginning of that string and @var{b} matches the rest of ++the string.@refill ++ ++ As a simple example, we can concatenate the regular expressions @samp{f} ++and @samp{o} to get the regular expression @samp{fo}, which matches only ++the string @samp{fo}. Still trivial. To do something nontrivial, you ++need to use one of the special characters. Here is a list of them. ++ ++@table @asis ++@item @kbd{.}@: @r{(Period)} ++is a special character that matches any single character except a newline. ++Using concatenation, we can make regular expressions like @samp{a.b}, which ++matches any three-character string that begins with @samp{a} and ends with ++@samp{b}.@refill ++ ++@item @kbd{*} ++is not a construct by itself; it is a postfix operator that means to ++match the preceding regular expression repetitively as many times as ++possible. Thus, @samp{o*} matches any number of @samp{o}s (including no ++@samp{o}s). ++ ++@samp{*} always applies to the @emph{smallest} possible preceding ++expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating ++@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. ++ ++The matcher processes a @samp{*} construct by matching, immediately, ++as many repetitions as can be found. Then it continues with the rest ++of the pattern. If that fails, backtracking occurs, discarding some ++of the matches of the @samp{*}-modified construct in case that makes ++it possible to match the rest of the pattern. For example, in matching ++@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first ++tries to match all three @samp{a}s; but the rest of the pattern is ++@samp{ar} and there is only @samp{r} left to match, so this try fails. ++The next alternative is for @samp{a*} to match only two @samp{a}s. ++With this choice, the rest of the regexp matches successfully.@refill ++ ++@item @kbd{+} ++is a postfix operator, similar to @samp{*} except that it must match ++the preceding expression at least once. So, for example, @samp{ca+r} ++matches the strings @samp{car} and @samp{caaaar} but not the string ++@samp{cr}, whereas @samp{ca*r} matches all three strings. ++ ++@item @kbd{?} ++is a postfix operator, similar to @samp{*} except that it can match the ++preceding expression either once or not at all. For example, ++@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. ++ ++@item @kbd{*?}, @kbd{+?}, @kbd{??} ++@cindex non-greedy regexp matching ++are non-greedy variants of the operators above. The normal operators ++@samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as ++much as they can, as long as the overall regexp can still match. With ++a following @samp{?}, they are non-greedy: they will match as little ++as possible. ++ ++Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a} ++and the string @samp{abbbb}; but if you try to match them both against ++the text @samp{abbb}, @samp{ab*} will match it all (the longest valid ++match), while @samp{ab*?} will match just @samp{a} (the shortest ++valid match). ++ ++Non-greedy operators match the shortest possible string starting at a ++given starting point; in a forward search, though, the earliest ++possible starting point for match is always the one chosen. Thus, if ++you search for @samp{a.*?$} against the text @samp{abbab} followed by ++a newline, it matches the whole string. Since it @emph{can} match ++starting at the first @samp{a}, it does. ++ ++@item @kbd{\@{@var{n}\@}} ++is a postfix operator that specifies repetition @var{n} times---that ++is, the preceding regular expression must match exactly @var{n} times ++in a row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} ++and nothing else. ++ ++@item @kbd{\@{@var{n},@var{m}\@}} ++is a postfix operator that specifies repetition between @var{n} and ++@var{m} times---that is, the preceding regular expression must match ++at least @var{n} times, but no more than @var{m} times. If @var{m} is ++omitted, then there is no upper limit, but the preceding regular ++expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is ++equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to ++@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. ++ ++@item @kbd{[ @dots{} ]} ++is a @dfn{character set}, which begins with @samp{[} and is terminated ++by @samp{]}. In the simplest case, the characters between the two ++brackets are what this set can match. ++ ++Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and ++@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s ++(including the empty string), from which it follows that @samp{c[ad]*r} ++matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. ++ ++You can also include character ranges in a character set, by writing the ++starting and ending characters with a @samp{-} between them. Thus, ++@samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be ++intermixed freely with individual characters, as in @samp{[a-z$%.]}, ++which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or ++period. ++ ++Note that the usual regexp special characters are not special inside a ++character set. A completely different set of special characters exists ++inside character sets: @samp{]}, @samp{-} and @samp{^}. ++ ++To include a @samp{]} in a character set, you must make it the first ++character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To ++include a @samp{-}, write @samp{-} as the first or last character of the ++set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]} ++and @samp{-}. ++ ++To include @samp{^} in a set, put it anywhere but at the beginning of ++the set. (At the beginning, it complements the set---see below.) ++ ++When you use a range in case-insensitive search, you should write both ++ends of the range in upper case, or both in lower case, or both should ++be non-letters. The behavior of a mixed-case range such as @samp{A-z} ++is somewhat ill-defined, and it may change in future Emacs versions. ++ ++@item @kbd{[^ @dots{} ]} ++@samp{[^} begins a @dfn{complemented character set}, which matches any ++character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches ++all characters @emph{except} @acronym{ASCII} letters and digits. ++ ++@samp{^} is not special in a character set unless it is the first ++character. The character following the @samp{^} is treated as if it ++were first (in other words, @samp{-} and @samp{]} are not special there). ++ ++A complemented character set can match a newline, unless newline is ++mentioned as one of the characters not to match. This is in contrast to ++the handling of regexps in programs such as @code{grep}. ++ ++@item @kbd{^} ++is a special character that matches the empty string, but only at the ++beginning of a line in the text being matched. Otherwise it fails to ++match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at ++the beginning of a line. ++ ++For historical compatibility reasons, @samp{^} can be used with this ++meaning only at the beginning of the regular expression, or after ++@samp{\(} or @samp{\|}. ++ ++@item @kbd{$} ++is similar to @samp{^} but matches only at the end of a line. Thus, ++@samp{x+$} matches a string of one @samp{x} or more at the end of a line. ++ ++For historical compatibility reasons, @samp{$} can be used with this ++meaning only at the end of the regular expression, or before @samp{\)} ++or @samp{\|}. ++ ++@item @kbd{\} ++has two functions: it quotes the special characters (including ++@samp{\}), and it introduces additional special constructs. ++ ++Because @samp{\} quotes special characters, @samp{\$} is a regular ++expression that matches only @samp{$}, and @samp{\[} is a regular ++expression that matches only @samp{[}, and so on. ++ ++See the following section for the special constructs that begin ++with @samp{\}. ++@end table ++ ++ Note: for historical compatibility, special characters are treated as ++ordinary ones if they are in contexts where their special meanings make no ++sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is ++no preceding expression on which the @samp{*} can act. It is poor practice ++to depend on this behavior; it is better to quote the special character anyway, ++regardless of where it appears. ++ ++As a @samp{\} is not special inside a character alternative, it can ++never remove the special meaning of @samp{-} or @samp{]}. So you ++should not quote these characters when they have no special meaning ++either. This would not clarify anything, since backslashes can ++legitimately precede these characters where they @emph{have} special ++meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), ++which matches any single character except a backslash. ++ ++@node Regexp Backslash ++@section Backslash in Regular Expressions ++ ++ For the most part, @samp{\} followed by any character matches only ++that character. However, there are several exceptions: two-character ++sequences starting with @samp{\} that have special meanings. The ++second character in the sequence is always an ordinary character when ++used on its own. Here is a table of @samp{\} constructs. ++ ++@table @kbd ++@item \| ++specifies an alternative. Two regular expressions @var{a} and @var{b} ++with @samp{\|} in between form an expression that matches some text if ++either @var{a} matches it or @var{b} matches it. It works by trying to ++match @var{a}, and if that fails, by trying to match @var{b}. ++ ++Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} ++but no other string.@refill ++ ++@samp{\|} applies to the largest possible surrounding expressions. Only a ++surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of ++@samp{\|}.@refill ++ ++Full backtracking capability exists to handle multiple uses of @samp{\|}. ++ ++@item \( @dots{} \) ++is a grouping construct that serves three purposes: ++ ++@enumerate ++@item ++To enclose a set of @samp{\|} alternatives for other operations. ++Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. ++ ++@item ++To enclose a complicated expression for the postfix operators @samp{*}, ++@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches ++@samp{bananana}, etc., with any (zero or more) number of @samp{na} ++strings.@refill ++ ++@item ++To record a matched substring for future reference. ++@end enumerate ++ ++This last application is not a consequence of the idea of a ++parenthetical grouping; it is a separate feature that is assigned as a ++second meaning to the same @samp{\( @dots{} \)} construct. In practice ++there is usually no conflict between the two meanings; when there is ++a conflict, you can use a ``shy'' group. ++ ++@item \(?: @dots{} \) ++@cindex shy group, in regexp ++specifies a ``shy'' group that does not record the matched substring; ++you can't refer back to it with @samp{\@var{d}}. This is useful ++in mechanically combining regular expressions, so that you ++can add groups for syntactic purposes without interfering with ++the numbering of the groups that are meant to be referred to. ++ ++@item \@var{d} ++@cindex back reference, in regexp ++matches the same text that matched the @var{d}th occurrence of a ++@samp{\( @dots{} \)} construct. This is called a @dfn{back ++reference}. ++ ++After the end of a @samp{\( @dots{} \)} construct, the matcher remembers ++the beginning and end of the text matched by that construct. Then, ++later on in the regular expression, you can use @samp{\} followed by the ++digit @var{d} to mean ``match the same text matched the @var{d}th time ++by the @samp{\( @dots{} \)} construct.'' ++ ++The strings matching the first nine @samp{\( @dots{} \)} constructs ++appearing in a regular expression are assigned numbers 1 through 9 in ++the order that the open-parentheses appear in the regular expression. ++So you can use @samp{\1} through @samp{\9} to refer to the text matched ++by the corresponding @samp{\( @dots{} \)} constructs. ++ ++For example, @samp{\(.*\)\1} matches any newline-free string that is ++composed of two identical halves. The @samp{\(.*\)} matches the first ++half, which may be anything, but the @samp{\1} that follows must match ++the same exact text. ++ ++If a particular @samp{\( @dots{} \)} construct matches more than once ++(which can easily happen if it is followed by @samp{*}), only the last ++match is recorded. ++ ++@item \` ++matches the empty string, but only at the beginning of the string or ++buffer (or its accessible portion) being matched against. ++ ++@item \' ++matches the empty string, but only at the end of the string or buffer ++(or its accessible portion) being matched against. ++ ++@item \= ++matches the empty string, but only at point. ++ ++@item \b ++matches the empty string, but only at the beginning or ++end of a word. Thus, @samp{\bfoo\b} matches any occurrence of ++@samp{foo} as a separate word. @samp{\bballs?\b} matches ++@samp{ball} or @samp{balls} as a separate word.@refill ++ ++@samp{\b} matches at the beginning or end of the buffer ++regardless of what text appears next to it. ++ ++@item \B ++matches the empty string, but @emph{not} at the beginning or ++end of a word. ++ ++@item \< ++matches the empty string, but only at the beginning of a word. ++@samp{\<} matches at the beginning of the buffer only if a ++word-constituent character follows. ++ ++@item \> ++matches the empty string, but only at the end of a word. @samp{\>} ++matches at the end of the buffer only if the contents end with a ++word-constituent character. ++ ++@item \w ++matches any word-constituent character. The syntax table ++determines which characters these are. @xref{Syntax}. ++ ++@item \W ++matches any character that is not a word-constituent. ++ ++@item \_< ++matches the empty string, but only at the beginning of a symbol. ++A symbol is a sequence of one or more symbol-constituent characters. ++A symbol-constituent character is a character whose syntax is either ++@samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the ++buffer only if a symbol-constituent character follows. ++ ++@item \_> ++matches the empty string, but only at the end of a symbol. @samp{\_>} ++matches at the end of the buffer only if the contents end with a ++symbol-constituent character. ++ ++@item \s@var{c} ++matches any character whose syntax is @var{c}. Here @var{c} is a ++character that designates a particular syntax class: thus, @samp{w} ++for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.} ++for ordinary punctuation, etc. @xref{Syntax}. ++ ++@item \S@var{c} ++matches any character whose syntax is not @var{c}. ++ ++@cindex categories of characters ++@cindex characters which belong to a specific language ++@findex describe-categories ++@item \c@var{c} ++matches any character that belongs to the category @var{c}. For ++example, @samp{\cc} matches Chinese characters, @samp{\cg} matches ++Greek characters, etc. For the description of the known categories, ++type @kbd{M-x describe-categories @key{RET}}. ++ ++@item \C@var{c} ++matches any character that does @emph{not} belong to category ++@var{c}. ++@end table ++ ++ The constructs that pertain to words and syntax are controlled by the ++setting of the syntax table (@pxref{Syntax}). ++ ++@node Regexp Example ++@section Regular Expression Example ++ ++ Here is an example of a regexp---the regexp that Emacs uses, by ++default, to recognize the end of a sentence, not including the ++following space (i.e., the variable @code{sentence-end-base}): ++ ++@example ++@verbatim ++[.?!][]\"'â€â€)}]* ++@end verbatim ++@end example ++ ++@noindent ++This contains two parts in succession: a character set matching ++period, @samp{?}, or @samp{!}, and a character set matching ++close-brackets, quotes, or parentheses, repeated zero or more times. ++ ++@node Search Case ++@section Searching and Case ++ ++ Searches in Emacs normally ignore the case of the text they are ++searching through, if you specify the text in lower case. Thus, if ++you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo} ++are also considered a match. Regexps, and in particular character ++sets, are included: @samp{[ab]} would match @samp{a} or @samp{A} or ++@samp{b} or @samp{B}.@refill ++ ++ An upper-case letter anywhere in the incremental search string makes ++the search case-sensitive. Thus, searching for @samp{Foo} does not find ++@samp{foo} or @samp{FOO}. This applies to regular expression search as ++well as to string search. The effect ceases if you delete the ++upper-case letter from the search string. ++ ++ Typing @kbd{M-c} within an incremental search toggles the case ++sensitivity of that search. The effect does not extend beyond the ++current incremental search to the next one, but it does override the ++effect of adding or removing an upper-case letter in the current ++search. ++ ++@vindex case-fold-search ++@vindex default-case-fold-search ++ If you set the variable @code{case-fold-search} to @code{nil}, then ++all letters must match exactly, including case. This is a per-buffer ++variable; altering the variable affects only the current buffer, but ++there is a default value in @code{default-case-fold-search} that you ++can also set. @xref{Locals}. This variable applies to nonincremental ++searches also, including those performed by the replace commands ++(@pxref{Replace}) and the minibuffer history matching commands ++(@pxref{Minibuffer History}). ++ ++ Several related variables control case-sensitivity of searching and ++matching for specific commands or activities. For instance, ++@code{tags-case-fold-search} controls case sensitivity for ++@code{find-tag}. To find these variables, do @kbd{M-x ++apropos-variable @key{RET} case-fold-search @key{RET}}. ++ ++@node Replace ++@section Replacement Commands ++@cindex replacement ++@cindex search-and-replace commands ++@cindex string substitution ++@cindex global substitution ++ ++ Emacs provides several commands for performing search-and-replace ++operations. In addition to the simple @kbd{M-x replace-string} ++command, there is @kbd{M-%} (@code{query-replace}), which presents ++each occurrence of the pattern and asks you whether to replace it. ++ ++ The replace commands normally operate on the text from point to the ++end of the buffer. When the mark is active, they operate on the ++region instead (@pxref{Mark}). The basic replace commands replace one ++@dfn{search string} (or regexp) with one @dfn{replacement string}. It ++is possible to perform several replacements in parallel, using the ++command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}). ++ ++@menu ++* Unconditional Replace:: Replacing all matches for a string. ++* Regexp Replace:: Replacing all matches for a regexp. ++* Replacement and Case:: How replacements preserve case of letters. ++* Query Replace:: How to use querying. ++@end menu ++ ++@node Unconditional Replace, Regexp Replace, Replace, Replace ++@subsection Unconditional Replacement ++@findex replace-string ++ ++@table @kbd ++@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} ++Replace every occurrence of @var{string} with @var{newstring}. ++@end table ++ ++ To replace every instance of @samp{foo} after point with @samp{bar}, ++use the command @kbd{M-x replace-string} with the two arguments ++@samp{foo} and @samp{bar}. Replacement happens only in the text after ++point, so if you want to cover the whole buffer you must go to the ++beginning first. All occurrences up to the end of the buffer are ++replaced; to limit replacement to part of the buffer, activate the ++region around that part. When the region is active, replacement is ++limited to the region (@pxref{Mark}). ++ ++ When @code{replace-string} exits, it leaves point at the last ++occurrence replaced. It adds the prior position of point (where the ++@code{replace-string} command was issued) to the mark ring, without ++activating the mark; use @kbd{C-u C-@key{SPC}} to move back there. ++@xref{Mark Ring}. ++ ++ A prefix argument restricts replacement to matches that are ++surrounded by word boundaries. The argument's value doesn't matter. ++ ++ @xref{Replacement and Case}, for details about case-sensitivity in ++replace commands. ++ ++@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace ++@subsection Regexp Replacement ++@findex replace-regexp ++ ++ The @kbd{M-x replace-string} command replaces exact matches for a ++single string. The similar command @kbd{M-x replace-regexp} replaces ++any match for a specified pattern. ++ ++@table @kbd ++@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} ++Replace every match for @var{regexp} with @var{newstring}. ++@end table ++ ++@cindex back reference, in regexp replacement ++ In @code{replace-regexp}, the @var{newstring} need not be constant: ++it can refer to all or part of what is matched by the @var{regexp}. ++@samp{\&} in @var{newstring} stands for the entire match being ++replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a ++digit, stands for whatever matched the @var{d}th parenthesized ++grouping in @var{regexp}. (This is called a ``back reference.'') ++@samp{\#} refers to the count of replacements already made in this ++command, as a decimal number. In the first replacement, @samp{\#} ++stands for @samp{0}; in the second, for @samp{1}; and so on. For ++example, ++ ++@example ++M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} ++@end example ++ ++@noindent ++replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} ++with @samp{cddr-safe}. ++ ++@example ++M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} ++@end example ++ ++@noindent ++performs the inverse transformation. To include a @samp{\} in the ++text to replace with, you must enter @samp{\\}. ++ ++ If you want to enter part of the replacement string by hand each ++time, use @samp{\?} in the replacement string. Each replacement will ++ask you to edit the replacement string in the minibuffer, putting ++point where the @samp{\?} was. ++ ++ The remainder of this subsection is intended for specialized tasks ++and requires knowledge of Lisp. Most readers can skip it. ++ ++ You can use Lisp expressions to calculate parts of the ++replacement string. To do this, write @samp{\,} followed by the ++expression in the replacement string. Each replacement calculates the ++value of the expression and converts it to text without quoting (if ++it's a string, this means using the string's contents), and uses it in ++the replacement string in place of the expression itself. If the ++expression is a symbol, one space in the replacement string after the ++symbol name goes with the symbol name, so the value replaces them ++both. ++ ++ Inside such an expression, you can use some special sequences. ++@samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire ++match as a string, and to a submatch as a string. @var{n} may be ++multiple digits, and the value of @samp{\@var{n}} is @code{nil} if ++subexpression @var{n} did not match. You can also use @samp{\#&} and ++@samp{\#@var{n}} to refer to those matches as numbers (this is valid ++when the match or submatch has the form of a numeral). @samp{\#} here ++too stands for the number of already-completed replacements. ++ ++ Repeating our example to exchange @samp{x} and @samp{y}, we can thus ++do it also this way: ++ ++@example ++M-x replace-regexp @key{RET} \(x\)\|y @key{RET} ++\,(if \1 "y" "x") @key{RET} ++@end example ++ ++ For computing replacement strings for @samp{\,}, the @code{format} ++function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs ++Lisp Reference Manual}). For example, to add consecutively numbered ++strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are ++already occupied), you can use ++ ++@example ++M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET} ++\,(format "%-72sABC%05d" \& \#) @key{RET} ++@end example ++ ++@node Replacement and Case, Query Replace, Regexp Replace, Replace ++@subsection Replace Commands and Case ++ ++ If the first argument of a replace command is all lower case, the ++command ignores case while searching for occurrences to ++replace---provided @code{case-fold-search} is non-@code{nil}. If ++@code{case-fold-search} is set to @code{nil}, case is always significant ++in all searches. ++ ++@vindex case-replace ++ In addition, when the @var{newstring} argument is all or partly lower ++case, replacement commands try to preserve the case pattern of each ++occurrence. Thus, the command ++ ++@example ++M-x replace-string @key{RET} foo @key{RET} bar @key{RET} ++@end example ++ ++@noindent ++replaces a lower case @samp{foo} with a lower case @samp{bar}, an ++all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with ++@samp{Bar}. (These three alternatives---lower case, all caps, and ++capitalized, are the only ones that @code{replace-string} can ++distinguish.) ++ ++ If upper-case letters are used in the replacement string, they remain ++upper case every time that text is inserted. If upper-case letters are ++used in the first argument, the second argument is always substituted ++exactly as given, with no case conversion. Likewise, if either ++@code{case-replace} or @code{case-fold-search} is set to @code{nil}, ++replacement is done without case conversion. ++ ++@node Query Replace,, Replacement and Case, Replace ++@subsection Query Replace ++@cindex query replace ++ ++@table @kbd ++@item M-% @var{string} @key{RET} @var{newstring} @key{RET} ++@itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} ++Replace some occurrences of @var{string} with @var{newstring}. ++@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET} ++@itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} ++Replace some matches for @var{regexp} with @var{newstring}. ++@end table ++ ++@kindex M-% ++@findex query-replace ++ If you want to change only some of the occurrences of @samp{foo} to ++@samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}). ++This command finds occurrences of @samp{foo} one by one, displays each ++occurrence and asks you whether to replace it. Aside from querying, ++@code{query-replace} works just like @code{replace-string} ++(@pxref{Unconditional Replace}). In particular, it preserves case ++provided @code{case-replace} is non-@code{nil}, as it normally is ++(@pxref{Replacement and Case}). A numeric argument means consider ++only occurrences that are bounded by word-delimiter characters. ++ ++@kindex C-M-% ++@findex query-replace-regexp ++ @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). ++It works like @code{replace-regexp} except that it queries ++like @code{query-replace}. ++ ++@cindex faces for highlighting query replace ++ These commands highlight the current match using the face ++@code{query-replace}. They highlight other matches using ++@code{lazy-highlight} just like incremental search (@pxref{Incremental ++Search}). By default, @code{query-replace-regexp} will show ++substituted replacement string for the current match in the ++minibuffer. If you want to keep special sequences @samp{\&} and ++@samp{\@var{n}} unexpanded, customize ++@code{query-replace-show-replacement} variable. ++ ++ The characters you can type when you are shown a match for the string ++or regexp are: ++ ++@ignore @c Not worth it. ++@kindex SPC @r{(query-replace)} ++@kindex DEL @r{(query-replace)} ++@kindex , @r{(query-replace)} ++@kindex RET @r{(query-replace)} ++@kindex . @r{(query-replace)} ++@kindex ! @r{(query-replace)} ++@kindex ^ @r{(query-replace)} ++@kindex C-r @r{(query-replace)} ++@kindex C-w @r{(query-replace)} ++@kindex C-l @r{(query-replace)} ++@end ignore ++ ++@c WideCommands ++@table @kbd ++@item @key{SPC} ++to replace the occurrence with @var{newstring}. ++ ++@item @key{DEL} ++to skip to the next occurrence without replacing this one. ++ ++@item , @r{(Comma)} ++to replace this occurrence and display the result. You are then asked ++for another input character to say what to do next. Since the ++replacement has already been made, @key{DEL} and @key{SPC} are ++equivalent in this situation; both move to the next occurrence. ++ ++You can type @kbd{C-r} at this point (see below) to alter the replaced ++text. You can also type @kbd{C-x u} to undo the replacement; this exits ++the @code{query-replace}, so if you want to do further replacement you ++must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart ++(@pxref{Repetition}). ++ ++@item @key{RET} ++to exit without doing any more replacements. ++ ++@item .@: @r{(Period)} ++to replace this occurrence and then exit without searching for more ++occurrences. ++ ++@item ! ++to replace all remaining occurrences without asking again. ++ ++@item ^ ++to go back to the position of the previous occurrence (or what used to ++be an occurrence), in case you changed it by mistake or want to ++reexamine it. ++ ++@item C-r ++to enter a recursive editing level, in case the occurrence needs to be ++edited rather than just replaced with @var{newstring}. When you are ++done, exit the recursive editing level with @kbd{C-M-c} to proceed to ++the next occurrence. @xref{Recursive Edit}. ++ ++@item C-w ++to delete the occurrence, and then enter a recursive editing level as in ++@kbd{C-r}. Use the recursive edit to insert text to replace the deleted ++occurrence of @var{string}. When done, exit the recursive editing level ++with @kbd{C-M-c} to proceed to the next occurrence. ++ ++@item e ++to edit the replacement string in the minibuffer. When you exit the ++minibuffer by typing @key{RET}, the minibuffer contents replace the ++current occurrence of the pattern. They also become the new ++replacement string for any further occurrences. ++ ++@item C-l ++to redisplay the screen. Then you must type another character to ++specify what to do with this occurrence. ++ ++@item C-h ++to display a message summarizing these options. Then you must type ++another character to specify what to do with this occurrence. ++@end table ++ ++ Some other characters are aliases for the ones listed above: @kbd{y}, ++@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and ++@key{RET}. ++ ++ Aside from this, any other character exits the @code{query-replace}, ++and is then reread as part of a key sequence. Thus, if you type ++@kbd{C-k}, it exits the @code{query-replace} and then kills to end of ++line. ++ ++ To restart a @code{query-replace} once it is exited, use @kbd{C-x ++@key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it ++used the minibuffer to read its arguments. @xref{Repetition, C-x ESC ++ESC}. ++ ++ @xref{Operating on Files}, for the Dired @kbd{Q} command which ++performs query replace on selected files. See also @ref{Transforming ++File Names}, for Dired commands to rename, copy, or link files by ++replacing regexp matches in file names. ++ ++@node Other Repeating Search ++@section Other Search-and-Loop Commands ++ ++ Here are some other commands that find matches for a regular ++expression. They all ignore case in matching, if the pattern contains ++no upper-case letters and @code{case-fold-search} is non-@code{nil}. ++Aside from @code{occur} and its variants, all operate on the text from ++point to the end of the buffer, or on the region if it is active. ++ ++@findex list-matching-lines ++@findex occur ++@findex multi-occur ++@findex multi-occur-in-matching-buffers ++@findex how-many ++@findex flush-lines ++@findex keep-lines ++ ++@table @kbd ++@item M-x occur @key{RET} @var{regexp} @key{RET} ++Display a list showing each line in the buffer that contains a match ++for @var{regexp}. To limit the search to part of the buffer, narrow ++to that part (@pxref{Narrowing}). A numeric argument @var{n} ++specifies that @var{n} lines of context are to be displayed before and ++after each matching line. Currently, @code{occur} can not correctly ++handle multiline matches. ++ ++@kindex RET @r{(Occur mode)} ++@kindex o @r{(Occur mode)} ++@kindex C-o @r{(Occur mode)} ++The buffer @samp{*Occur*} containing the output serves as a menu for ++finding the occurrences in their original context. Click ++@kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position ++point there and type @key{RET}; this switches to the buffer that was ++searched and moves point to the original of the chosen occurrence. ++@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} ++does not select it. ++ ++After using @kbd{M-x occur}, you can use @code{next-error} to visit ++the occurrences found, one by one. @ref{Compilation Mode}. ++ ++@kindex M-s o ++@item M-s o ++Run @code{occur} using the search string of the last incremental ++string search. You can also run @kbd{M-s o} when an incremental ++search is active; this uses the current search string. ++ ++@item M-x list-matching-lines ++Synonym for @kbd{M-x occur}. ++ ++@item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET} ++This function is just like @code{occur}, except it is able to search ++through multiple buffers. It asks you to specify the buffer names one by one. ++ ++@item M-x multi-occur-in-matching-buffers @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET} ++This function is similar to @code{multi-occur}, except the buffers to ++search are specified by a regular expression that matches visited ++file names. With a prefix argument, it uses the regular expression to match ++buffer names instead. ++ ++@item M-x how-many @key{RET} @var{regexp} @key{RET} ++Print the number of matches for @var{regexp} that exist in the buffer ++after point. If the region is active, this operates on the region ++instead. ++ ++@item M-x flush-lines @key{RET} @var{regexp} @key{RET} ++This command deletes each line that contains a match for @var{regexp}, ++operating on the text after point; it deletes the current line if it ++contains a match starting after point. If the region is active, it ++operates on the region instead; if a line partially contained in the ++region contains a match entirely contained in the region, it is ++deleted. ++ ++If a match is split across lines, @code{flush-lines} deletes all those ++lines. It deletes the lines before starting to look for the next ++match; hence, it ignores a match starting on the same line at which ++another match ended. ++ ++@item M-x keep-lines @key{RET} @var{regexp} @key{RET} ++This command deletes each line that @emph{does not} contain a match ++for @var{regexp}, operating on the text after point; if point is not ++at the beginning of a line, it always keeps the current line. If the ++region is active, the command operates on the region instead; it never ++deletes lines that are only partially contained in the region (a ++newline that ends a line counts as part of that line). ++ ++If a match is split across lines, this command keeps all those lines. ++@end table ++ ++@ignore ++ arch-tag: fd9d8e77-66af-491c-b212-d80999613e3e ++@end ignore +diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi +new file mode 100644 +index 0000000..ff8fe8d +--- /dev/null ++++ b/doc/emacs/sending.texi +@@ -0,0 +1,812 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Sending Mail ++@chapter Sending Mail ++@cindex sending mail ++@cindex mail ++@cindex message ++ ++ To send a message in Emacs, you start by typing a command (@kbd{C-x m}) ++to select and initialize the @samp{*mail*} buffer. Then you edit the text ++and headers of the message in this buffer, and type another command ++(@kbd{C-c C-s} or @kbd{C-c C-c}) to send the message. ++ ++@table @kbd ++@item C-x m ++Begin composing a message to send (@code{compose-mail}). ++@item C-x 4 m ++Likewise, but display the message in another window ++(@code{compose-mail-other-window}). ++@item C-x 5 m ++Likewise, but make a new frame (@code{compose-mail-other-frame}). ++@item C-c C-s ++In Mail mode, send the message (@code{mail-send}). ++@item C-c C-c ++Send the message and bury the mail buffer (@code{mail-send-and-exit}). ++@end table ++ ++@kindex C-x m ++@findex compose-mail ++@kindex C-x 4 m ++@findex compose-mail-other-window ++@kindex C-x 5 m ++@findex compose-mail-other-frame ++ The command @kbd{C-x m} (@code{compose-mail}) selects a buffer named ++@samp{*mail*} and initializes it with the skeleton of an outgoing ++message. @kbd{C-x 4 m} (@code{compose-mail-other-window}) selects the ++@samp{*mail*} buffer in a different window, leaving the previous current ++buffer visible. @kbd{C-x 5 m} (@code{compose-mail-other-frame}) creates ++a new frame to select the @samp{*mail*} buffer. ++ ++ Because the mail-composition buffer is an ordinary Emacs buffer, you can ++switch to other buffers while in the middle of composing mail, and switch ++back later (or never). If you use the @kbd{C-x m} command again when you ++have been composing another message but have not sent it, you are asked to ++confirm before the old message is erased. If you answer @kbd{n}, the ++@samp{*mail*} buffer remains selected with its old contents, so you can ++finish the old message and send it. @kbd{C-u C-x m} is another way to do ++this. Sending the message marks the @samp{*mail*} buffer ``unmodified,'' ++which avoids the need for confirmation when @kbd{C-x m} is next used. ++ ++ If you are composing a message in the @samp{*mail*} buffer and want to ++send another message before finishing the first, rename the ++@samp{*mail*} buffer using @kbd{M-x rename-uniquely} (@pxref{Misc ++Buffer}). Then you can use @kbd{C-x m} or its variants described above ++to make a new @samp{*mail*} buffer. Once you've done that, you can work ++with each mail buffer independently. ++ ++@vindex mail-default-directory ++ The variable @code{mail-default-directory} controls the default ++directory for mail buffers, and also says where to put their auto-save ++files. ++ ++@c Not mentioned: mail-bury-selects-summary. Really an Rmail feature. ++ ++@ignore ++@c Commented out because it is not user-oriented; ++@c it doesn't say how to do some job. -- rms. ++@cindex directory servers ++@cindex LDAP ++@cindex PH/QI ++@cindex names and addresses ++There is an interface to directory servers using various protocols such ++as LDAP or the CCSO white pages directory system (PH/QI), described in a ++separate manual. It may be useful for looking up names and addresses. ++@xref{Top,,EUDC, eudc, EUDC Manual}. ++@end ignore ++ ++@menu ++* Format: Mail Format. Format of the mail being composed. ++* Headers: Mail Headers. Details of some standard mail header fields. ++* Aliases: Mail Aliases. Abbreviating and grouping mail addresses. ++* Mode: Mail Mode. Special commands for editing mail being composed. ++* Amuse: Mail Amusements. Distracting the NSA; adding fortune messages. ++* Methods: Mail Methods. Using alternative mail-composition methods. ++@end menu ++ ++@node Mail Format ++@section The Format of the Mail Buffer ++ ++ In addition to the @dfn{text} or @dfn{body}, a message has @dfn{header ++fields} which say who sent it, when, to whom, why, and so on. Some ++header fields, such as @samp{Date} and @samp{Message-Id}, are created ++automatically when you send the message. Others, such as the recipient ++names, must be specified by you in order to send the message properly. ++ ++ In the mail buffer, you can insert and edit header fields using ++ordinary editing commands. Mail mode provides commands to help you ++edit some header fields, and some are automatically preinitialized in ++the buffer, when appropriate. ++ ++@vindex mail-header-separator ++ The line in the buffer that says ++ ++@example ++--text follows this line-- ++@end example ++ ++@noindent ++is a special delimiter that separates the headers you have specified from ++the text. Whatever follows this line is the text of the message; the ++headers precede it. The delimiter line itself does not appear in the ++message actually sent. The text used for the delimiter line is controlled ++by the variable @code{mail-header-separator}. ++ ++ Here is an example of what the headers and text in the mail buffer ++might look like. ++ ++@example ++To: gnu@@gnu.org ++CC: lungfish@@spam.org, byob@@spam.org ++Subject: The Emacs Manual ++--text follows this line-- ++Please ignore this message. ++@end example ++ ++@node Mail Headers ++@section Mail Header Fields ++@cindex headers (of mail message) ++ ++ A header field in the mail buffer starts with a field name at the ++beginning of a line, terminated by a colon. Upper and lower case are ++equivalent in field names (and in mailing addresses also). After the ++colon and optional whitespace comes the contents of the field. ++ ++ You can use any name you like for a header field, but normally people ++use only standard field names with accepted meanings. Here is a table ++of fields commonly used in outgoing messages. Emacs preinitializes some ++of these when you start to compose a mail, depending on various options ++you can set. You can delete or alter any header field before you send ++the message, if you wish. ++ ++@table @samp ++@item To ++This field contains the mailing addresses to which the message is ++addressed. If you list more than one address, use commas, not spaces, ++to separate them. ++ ++@item Subject ++The contents of the @samp{Subject} field should be a piece of text ++that says what the message is about. The reason @samp{Subject} fields ++are useful is that most mail-reading programs can provide a summary of ++messages, listing the subject of each message but not its text. ++ ++@item CC ++This field contains additional mailing addresses to send the message to, ++like @samp{To} except that these readers should not regard the message ++as directed at them. ++ ++@item BCC ++This field contains additional mailing addresses to send the message to, ++which should not appear in the header of the message actually sent. ++Copies sent this way are called @dfn{blind carbon copies}. ++ ++@vindex mail-self-blind ++@cindex copy of every outgoing message ++To send a blind carbon copy of every outgoing message to yourself, set ++the variable @code{mail-self-blind} to @code{t}. To send a blind carbon ++copy of every message to some other @var{address}, set the variable ++@code{mail-default-headers} to @code{"Bcc: @var{address}\n"}. ++ ++@item FCC ++This field contains the name of one file and directs Emacs to append a ++copy of the message to that file when you send the message. Emacs ++writes the message in mbox format, unless the file is in Babyl format ++(used by Rmail before Emacs 23), in which case Emacs writes Babyl. If ++an Rmail buffer is visiting the file, Emacs updates it accordingly. ++To specify more than one file, use several @samp{FCC} fields, with one ++file name in each field. ++ ++@vindex mail-archive-file-name ++To put a fixed file name in the @samp{FCC} field each time you start ++editing an outgoing message, set the variable ++@code{mail-archive-file-name} to that file name. Unless you remove the ++@samp{FCC} field before sending, the message will be written into that ++file when it is sent. ++ ++@item From ++Use the @samp{From} field to say who you are. You might need to change ++this if the account you are using to send the mail is not your own. The ++contents of the @samp{From} field should be a valid mailing address, ++since replies will normally go there. ++ ++@vindex mail-setup-with-from ++Emacs initializes this field (unless the variable ++@code{mail-setup-with-from} is @code{nil}) using ++@code{user-mail-address} as the default. If there is no @samp{From} ++field when you send a mail, Emacs adds one. ++ ++@item Reply-to ++Use this field to direct replies to a different address. Most ++mail-reading programs (including Rmail) automatically send replies to ++the @samp{Reply-to} address in preference to the @samp{From} address. ++By adding a @samp{Reply-to} field to your header, you can work around ++any problems your @samp{From} address may cause for replies. ++ ++@cindex @env{REPLYTO} environment variable ++@vindex mail-default-reply-to ++To put a fixed @samp{Reply-to} address into every outgoing message, set ++the variable @code{mail-default-reply-to} to that address (as a string). ++Then Emacs initializes the message with a @samp{Reply-to} field as ++specified. When you first compose a mail, if ++@code{mail-default-reply-to} is @code{nil}, Emacs initializes it from the ++environment variable @env{REPLYTO}. ++ ++@item Mail-reply-to ++ This field takes precedence over @samp{Reply-to}. It is used because ++some mailing lists set the @samp{Reply-to} field for their own purposes ++(a somewhat controversial practice). ++ ++@item Mail-followup-to ++ This field contains one or more addresses. It is typically used when ++you reply to a message from a mailing list that you are subscribed to. ++It usually indicates that you want replies to go to the list, and that ++you do not need an extra copy sent directly to you. ++ ++@vindex mail-mailing-lists ++ The variable @code{mail-mailing-lists} holds a list of mailing list ++addresses that you are subscribed to. If it is non-@code{nil}, Emacs ++inserts an appropriate @samp{Mail-followup-to} header when sending mail ++to a mailing list. ++ ++@c There is also "Sent-via", added by C-c C-v, but it does not seem ++@c particularly useful (?). ++ ++@item In-reply-to ++This field contains a piece of text describing the message you are ++replying to. Some mail systems can use this information to correlate ++related pieces of mail. Normally this field is filled in by Rmail ++when you reply to a message in Rmail, and you never need to ++think about it (@pxref{Rmail}). ++ ++@item References ++This field lists the Message-Ids of related previous messages (a ++Message-Id is a unique identifier generated when a message is sent). ++Rmail sets up this field automatically when you reply to a message. ++@end table ++ ++ The @samp{To}, @samp{CC}, and @samp{BCC} header fields can appear ++any number of times, and each such header field can contain multiple ++addresses, separated by commas. This way, you can specify any number ++of places to send the message. These fields can also have ++continuation lines: one or more lines starting with whitespace, ++following the starting line of the field, are considered part of the ++field. Here's an example of a @samp{To} field with a continuation ++line: ++ ++@example ++@group ++To: foo@@here.net, this@@there.net, ++ me@@gnu.cambridge.mass.usa.earth.spiral3281 ++@end group ++@end example ++ ++@vindex mail-from-style ++ When you send the message, if you didn't write a @samp{From} field ++yourself, Emacs puts in one for you, using @code{user-mail-address}. ++The variable @code{mail-from-style} controls the format: ++ ++@table @code ++@item nil ++Use just the email address, as in @samp{king@@grassland.com}. ++@item parens ++Use both email address and full name, as in:@* ++@samp{king@@grassland.com (Elvis Parsley)}. ++@item angles ++Use both email address and full name, as in:@* ++@samp{Elvis Parsley }. ++@item system-default ++Allow the system to insert the @samp{From} field. ++@end table ++ ++@c There is also mail-specify-envelope-from and mail-envelope-from, but ++@c these are probably not topics for the Emacs manual. ++ ++@vindex mail-default-headers ++ You can direct Emacs to insert certain default headers into the ++outgoing message by setting the variable @code{mail-default-headers} ++to a string. Then @code{C-x m} inserts this string into the message ++headers. If the default header fields are not appropriate for a ++particular message, edit them as necessary before sending the message. ++ ++@node Mail Aliases ++@section Mail Aliases ++@cindex mail aliases ++@cindex @file{.mailrc} file ++@cindex mailrc file ++ ++ You can define @dfn{mail aliases} in a file named @file{~/.mailrc}. ++These are short mnemonic names which stand for mail addresses or groups of ++mail addresses. Like many other mail programs, Emacs expands aliases ++when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and ++@samp{Reply-to} fields, plus their @samp{Resent-} variants. ++@c The list is defined by mail-address-field-regexp. ++ ++ To define an alias in @file{~/.mailrc}, write a line in the following ++format: ++ ++@example ++alias @var{shortaddress} @var{fulladdresses} ++@end example ++ ++@noindent ++Here @var{fulladdresses} stands for one or more mail addresses for ++@var{shortaddress} to expand into. Separate multiple addresses with ++spaces; if an address contains a space, quote the whole address with a ++pair of double quotes. ++ ++For instance, to make @code{maingnu} stand for ++@code{gnu@@gnu.org} plus a local address of your own, put in ++this line:@refill ++ ++@example ++alias maingnu gnu@@gnu.org local-gnu ++@end example ++ ++@noindent ++Addresses specified in this way should use double quotes around an ++entire address when the address contains spaces. But you need not ++include double quotes around parts of the address, such as the person's ++full name. Emacs puts them in if they are needed. For example, ++ ++@example ++alias jsmith "John Q. Smith " ++@end example ++ ++@noindent ++is correct in @samp{.mailrc}. Emacs will insert the address as ++@samp{"John Q. Smith" }. ++ ++ Emacs also recognizes ``include'' commands in @samp{.mailrc} files. ++They look like this: ++ ++@example ++source @var{filename} ++@end example ++ ++@noindent ++The file @file{~/.mailrc} is used primarily by other mail-reading ++programs; it can contain various other commands. Emacs ignores ++everything in it except for alias definitions and include commands. ++ ++@findex define-mail-alias ++ Another way to define a mail alias, within Emacs alone, is with the ++@code{define-mail-alias} command. It prompts for the alias and then the ++full address. You can use it to define aliases in your @file{.emacs} ++file, like this: ++ ++@example ++(define-mail-alias "maingnu" "gnu@@gnu.org") ++@end example ++ ++@vindex mail-aliases ++ @code{define-mail-alias} records aliases by adding them to a ++variable named @code{mail-aliases}. If you are comfortable with ++manipulating Lisp lists, you can set @code{mail-aliases} directly. The ++initial value of @code{mail-aliases} is @code{t}, which means that ++Emacs should read @file{.mailrc} to get the proper value. ++ ++@vindex mail-personal-alias-file ++ You can specify a different file name to use instead of ++@file{~/.mailrc} by setting the variable ++@code{mail-personal-alias-file}. ++ ++@c There is also mail-alias-file for the system aliases. ++ ++@findex expand-mail-aliases ++ Normally, Emacs expands aliases when you send the message. You do not ++need to expand mail aliases before sending the message, but you can ++expand them if you want to see where the mail will actually go. To do ++this, use the command @kbd{M-x expand-mail-aliases}; it expands all mail ++aliases currently present in the mail headers that hold addresses. ++ ++ If you like, you can have mail aliases expand as abbrevs, as soon as ++you type them in (@pxref{Abbrevs}). To enable this feature, execute the ++following: ++ ++@example ++(add-hook 'mail-mode-hook 'mail-abbrevs-setup) ++@end example ++ ++@noindent ++@findex define-mail-abbrev ++@vindex mail-abbrevs ++This can go in your @file{.emacs} file. @xref{Hooks}. If you use this ++feature, you must use @code{define-mail-abbrev} instead of ++@code{define-mail-alias}; the latter does not work with this package. ++Note that the mail abbreviation package uses the variable ++@code{mail-abbrevs} instead of @code{mail-aliases}, and that all alias ++names are converted to lower case. ++ ++@kindex C-c C-a @r{(Mail mode)} ++@findex mail-abbrev-insert-alias ++ The mail abbreviation package also provides the @kbd{C-c C-a} ++(@code{mail-abbrev-insert-alias}) command, which reads an alias ++name (with completion) and inserts its definition at point. This is ++useful when editing the message text itself or a header field such as ++@samp{Subject} in which Emacs does not normally expand aliases. ++ ++ Note that abbrevs expand only if you insert a word-separator character ++afterward. However, you can rebind @kbd{C-n} and @kbd{M->} to cause ++expansion as well. Here's how to do that: ++ ++@smallexample ++(add-hook 'mail-mode-hook ++ (lambda () ++ (define-key ++ mail-mode-map [remap next-line] 'mail-abbrev-next-line) ++ (define-key ++ mail-mode-map [remap end-of-buffer] 'mail-abbrev-end-of-buffer))) ++@end smallexample ++ ++@node Mail Mode ++@section Mail Mode ++@cindex Mail mode ++@cindex mode, Mail ++ ++ The major mode used in the mail buffer is Mail mode, which is much ++like Text mode except that various special commands are provided on the ++@kbd{C-c} prefix. These commands all have to do specifically with ++editing or sending the message. ++ ++ Mail mode is normally used in buffers set up automatically by the ++@code{mail} command and related commands. However, you can also switch ++to Mail mode in a file-visiting buffer. This is a useful thing to do if ++you have saved the text of a draft message in a file. ++ ++@menu ++* Mail Sending:: Commands to send the message. ++* Header Editing:: Commands to move to header fields and edit them. ++* Citing Mail:: Copying all or part of a message you are replying to. ++* Mail Mode Misc:: Spell checking, signatures, etc. ++@end menu ++ ++@node Mail Sending ++@subsection Mail Sending ++ ++ Mail mode has two commands for sending the message you have been ++editing: ++ ++@table @kbd ++@item C-c C-s ++Send the message, and leave the mail buffer selected (@code{mail-send}). ++@item C-c C-c ++Send the message, and select some other buffer (@code{mail-send-and-exit}). ++@end table ++ ++@kindex C-c C-s @r{(Mail mode)} ++@kindex C-c C-c @r{(Mail mode)} ++@findex mail-send ++@findex mail-send-and-exit ++@vindex mail-send-hook ++ @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail ++buffer unmodified, but leaves that buffer selected so that you can ++modify the message (perhaps with new recipients) and send it again. ++@kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the ++window or switches to another buffer. It puts the mail buffer at the ++lowest priority for reselection by default, since you are finished with ++using it. This is the usual way to send the message. Sending a message ++runs the hook @code{mail-send-hook}. ++ ++@c Options not mentioned: mail-interactive, mail-use-dsn. ++ ++ In a file-visiting buffer, sending the message does not clear the ++modified flag, because only saving the file should do that. Also, you ++don't get a warning if you try to send the same message twice. ++ ++@c This is indexed in mule.texi, node "Recognize Coding". ++@c @vindex sendmail-coding-system ++ When you send a message that contains non-@acronym{ASCII} characters, they need ++to be encoded with a coding system (@pxref{Coding Systems}). Usually ++the coding system is specified automatically by your chosen language ++environment (@pxref{Language Environments}). You can explicitly specify ++the coding system for outgoing mail by setting the variable ++@code{sendmail-coding-system} (@pxref{Recognize Coding}). ++ ++ If the coding system thus determined does not handle the characters in ++a particular message, Emacs asks you to select the coding system to use, ++showing a list of possible coding systems. ++ ++@c Not mentioned: mail-send-nonascii. ++ ++@cindex SMTP ++@cindex Feedmail ++@cindex Sendmail ++@cindex Mailclient ++@vindex send-mail-function ++ The variable @code{send-mail-function} controls how the default mail ++user agent sends mail. It should be set to a function. In most cases, ++the default is @code{sendmail-send-it}, which delivers mail using the ++Sendmail installation on the local host. On Mac OS X and MS-Windows, ++however, the default is normally @code{mailclient-send-it}, which ++passes the mail buffer on to the system's designated mail client (see ++@file{mailclient.el}). To send mail through an SMTP server, set ++@code{send-mail-function} to @code{smtpmail-send-it} and set up the ++Emacs SMTP library (@pxref{Top,,Emacs SMTP Library, smtpmail, Sending ++mail via SMTP}). Another option is @code{feedmail-send-it} (see the ++commentary section of the @file{feedmail.el} package). ++ ++@node Header Editing ++@subsection Mail Header Editing ++ ++ Mail mode provides special commands to move to particular header ++fields and to complete addresses in headers. ++ ++@table @kbd ++@item C-c C-f C-t ++Move to the @samp{To} header field, creating one if there is none ++(@code{mail-to}). ++@item C-c C-f C-s ++Move to the @samp{Subject} header field, creating one if there is ++none (@code{mail-subject}). ++@item C-c C-f C-c ++Move to the @samp{CC} header field, creating one if there is none ++(@code{mail-cc}). ++@item C-c C-f C-b ++Move to the @samp{BCC} header field, creating one if there is none ++(@code{mail-bcc}). ++@item C-c C-f C-r ++Move to the @samp{Reply-To} header field, creating one if there is none ++(@code{mail-reply-to}). ++@item C-c C-f C-a ++Move to the @samp{Mail-Reply-To} header field, creating one if there is none ++(@code{mail-mail-reply-to}). ++@item C-c C-f C-l ++Move to the @samp{Mail-Followup-To} header field, creating one if there is none ++(@code{mail-mail-followup-to}). ++@item C-c C-f C-f ++Add a new @samp{FCC} header field, with file-name completion ++(@code{mail-fcc}). ++@c There is also C-c C-v, mail-sent-via, which adds one or more ++@c "Sent-via" headers, but I don't know what the point of that header is. ++@item M-@key{TAB} ++Complete a mailing address (@code{mail-complete}). ++@end table ++ ++@kindex C-c C-f C-t @r{(Mail mode)} ++@findex mail-to ++@kindex C-c C-f C-s @r{(Mail mode)} ++@findex mail-subject ++@kindex C-c C-f C-c @r{(Mail mode)} ++@findex mail-cc ++@kindex C-c C-f C-b @r{(Mail mode)} ++@findex mail-bcc ++@kindex C-c C-f C-r @r{(Mail mode)} ++@findex mail-reply-to ++@kindex C-c C-f C-a @r{(Mail mode)} ++@findex mail-mail-reply-to ++@kindex C-c C-f C-l @r{(Mail mode)} ++@findex mail-mail-followup-to ++@kindex C-c C-f C-f @r{(Mail mode)} ++@findex mail-fcc ++ There are several commands to move point to particular header fields, ++all based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). ++They are listed in the table above. If the field in question does not ++exist, these commands create one (the exception is @code{mail-fcc}, ++which creates a new field each time). We provide special motion ++commands for these particular fields because they are the fields users ++most often want to edit. ++ ++@findex mail-complete ++@kindex M-TAB @r{(Mail mode)} ++@c `mail-complete-alist' specifies the headers. ++ While editing a header field that contains mailing addresses, such ++as @samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing ++address by typing @kbd{M-@key{TAB}} (@code{mail-complete}). It ++inserts the full name corresponding to the address, if it can ++determine the full name. The variable @code{mail-complete-style} ++controls whether to insert the full name, and what style to use, as in ++@code{mail-from-style} (@pxref{Mail Headers}). (If your window ++manager defines @kbd{M-@key{TAB}} to switch windows, you can type ++@kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.) ++ ++ For completion purposes, the valid mailing addresses are taken to be ++the local users' names plus your personal mail aliases (@pxref{Mail ++Aliases}). You can specify additional sources of valid addresses; ++browse the customization group @samp{mailalias} to see the variables for ++customizing this feature (@pxref{Customization Groups}). ++ ++ If you type @kbd{M-@key{TAB}} in the body of the message, or on a ++unrecognized header, @code{mail-complete} invokes the function specified ++by @code{mail-complete-function}. By default, this is ++@code{ispell-complete-word}, as in Text mode. ++ ++@node Citing Mail ++@subsection Citing Mail ++@cindex citing mail ++ ++ Mail mode also has commands for yanking or @dfn{citing} all or part of ++a message that you are replying to. These commands are active only when ++you started sending a message using an Rmail command. ++ ++@table @kbd ++@item C-c C-y ++Yank the selected message from Rmail (@code{mail-yank-original}). ++@item C-c C-r ++Yank the region from the Rmail buffer (@code{mail-yank-region}). ++@item C-c C-q ++Fill each paragraph cited from another message ++(@code{mail-fill-yanked-message}). ++@c There is also mail-split-line, but it does not seem very useful. ++@end table ++ ++@kindex C-c C-y @r{(Mail mode)} ++@findex mail-yank-original ++ When mail sending is invoked from the Rmail mail reader using an Rmail ++command, @kbd{C-c C-y} can be used inside the mail buffer to insert the ++text of the message you are replying to. Normally it indents each line ++of that message three spaces and eliminates most header fields (as ++specified by the variable @code{mail-yank-ignored-headers}). A numeric ++argument specifies the number of spaces to indent (the variable ++@code{mail-indentation-spaces} specifies the default number). An ++argument of just @kbd{C-u} says not to indent at all and not to ++eliminate anything. @kbd{C-c C-y} always uses the current message from ++the Rmail buffer, so you can insert several old messages by selecting ++one in Rmail, switching to @samp{*mail*} and yanking it, then switching ++back to Rmail to select another. ++ ++@vindex mail-yank-prefix ++ You can specify the text for @kbd{C-c C-y} to insert at the beginning ++of each line: set @code{mail-yank-prefix} to the desired string. (A ++value of @code{nil} means to use indentation; this is the default.) ++However, @kbd{C-u C-c C-y} never adds anything at the beginning of the ++inserted lines, regardless of the value of @code{mail-yank-prefix}. ++ ++@kindex C-c C-r @r{(Mail mode)} ++@findex mail-yank-region ++ To yank just a part of an incoming message, set the region in Rmail to ++the part you want; then go to the @samp{*Mail*} message and type ++@kbd{C-c C-r} (@code{mail-yank-region}). Each line that is copied is ++indented or prefixed according to @code{mail-yank-prefix}. ++ ++@kindex C-c C-q @r{(Mail mode)} ++@findex mail-fill-yanked-message ++ After using @kbd{C-c C-y} or @kbd{C-c C-r}, you can type @kbd{C-c C-q} ++(@code{mail-fill-yanked-message}) to fill the paragraphs of the yanked ++old message or messages. One use of @kbd{C-c C-q} fills all such ++paragraphs, each one individually. To fill a single paragraph of the ++quoted message, use @kbd{M-q}. If filling does not automatically ++handle the type of citation prefix you use, try setting the fill prefix ++explicitly. @xref{Filling}. ++ ++@vindex mail-citation-hook ++ You can customize mail citation through the hook ++@code{mail-citation-hook}. For example, you can use the Supercite ++package, which provides more flexible citation ++(@pxref{Introduction,,,sc, Supercite}). ++ ++@c No need to mention: mail-citation-prefix-regexp. ++ ++@node Mail Mode Misc ++@subsection Mail Mode Miscellany ++ ++@table @kbd ++@item C-c C-t ++Move to the beginning of the message body text (@code{mail-text}). ++@item C-c C-w ++Insert a signature at the end of the message text (@code{mail-signature}). ++@item C-c C-i @var{file} @key{RET} ++Insert the contents of @var{file} at the end of the message text ++(@code{mail-attach-file}). ++@item M-x ispell-message ++Perform spelling correction on the message text, but not on citations from ++other messages, or the message headers. ++@end table ++ ++@kindex C-c C-t @r{(Mail mode)} ++@findex mail-text ++ @kbd{C-c C-t} (@code{mail-text}) moves point to just after the header ++separator line---that is, to the beginning of the message body text. ++ ++@kindex C-c C-w @r{(Mail mode)} ++@findex mail-signature ++@vindex mail-signature ++ @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text ++(your @dfn{mail signature}) at the end of the message to say more about who ++you are. For example, it may contain telephone numbers, or your ++physical location. The text comes from the variable ++@code{mail-signature}. It can be a fixed string, or a Lisp expression ++that returns a string. If it is @code{t} or @code{nil}, the function ++inserts the contents of the file @code{mail-signature-file}. By ++default, this is the file @file{~/.signature} in your home directory. ++ ++ If the variable @code{mail-signature} has a non-@code{nil} value, ++starting a mail automatically inserts your signature. Otherwise, you ++must explicitly use the command @code{mail-signature}. If you want to ++omit your signature from a particular message, just delete it from the ++buffer before you send the message. ++ ++ Convention says that the start of your signature should be marked by a ++line whose contents are @samp{-- }. If your signature comes from a ++file, this prefix is added for you, but in all other cases you must add ++it yourself. The remainder of your signature should be no more than ++four lines. ++ ++@findex ispell-message ++ You can do spelling correction on the message text you have written ++with the command @kbd{M-x ispell-message}. If you have yanked an ++incoming message into the outgoing draft, this command skips what was ++yanked, but it checks the text that you yourself inserted. (It looks ++for indentation or @code{mail-yank-prefix} to distinguish the cited ++lines from your input.) @xref{Spelling}. ++ ++@kindex C-c C-i @r{(Mail mode)} ++@findex mail-attach-file ++ To include a file in the outgoing message, you can use @kbd{C-x i}, ++the usual command to insert a file in the current buffer. But it is ++often more convenient to use a special command, @kbd{C-c C-i} ++(@code{mail-attach-file}). This command inserts the file contents at ++the end of the buffer, after your signature (if any), with a delimiter ++line that includes the file name. Note that this is not a MIME ++attachment. ++ ++@vindex mail-mode-hook ++@vindex mail-setup-hook ++ Turning on Mail mode (which @kbd{C-x m} does automatically) runs the ++normal hooks @code{text-mode-hook} and @code{mail-mode-hook}. ++Initializing a new outgoing message runs the normal hook ++@code{mail-setup-hook}; if you want to add special fields to your mail ++header or make other changes to the appearance of the mail buffer, use ++that hook. @xref{Hooks}. ++ ++ The main difference between these hooks is just when they are ++invoked. Whenever you type @kbd{M-x mail}, @code{mail-mode-hook} runs ++as soon as the @samp{*mail*} buffer is created. Then the ++@code{mail-setup} function inserts the default contents of the buffer. ++After these default contents are inserted, @code{mail-setup-hook} runs. ++ ++ If you use @kbd{M-x mail} to continue an existing composition, ++@code{mail-mode-hook} runs immediately after switching to the ++@samp{*mail*} buffer. If the buffer is unmodified, or if you decide to ++erase it and start again, @code{mail-setup-hook} runs after the default ++contents are inserted. ++ ++@node Mail Amusements ++@section Mail Amusements ++ ++@findex spook ++@cindex NSA ++ @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing ++mail message. The keywords are chosen from a list of words that suggest ++you are discussing something subversive. ++ ++ The idea behind this feature is the suspicion that the ++NSA@footnote{The US National Security Agency.} and other intelligence ++agencies snoop on all electronic mail messages that contain keywords ++suggesting they might find them interesting. (The agencies say that ++they don't, but that's what they @emph{would} say.) The idea is that if ++lots of people add suspicious words to their messages, the agencies will ++get so busy with spurious input that they will have to give up reading ++it all. Whether or not this is true, it at least amuses some people. ++ ++@findex fortune-to-signature ++@cindex fortune cookies ++ You can use the @code{fortune} program to put a ``fortune cookie'' ++message into outgoing mail. To do this, add ++@code{fortune-to-signature} to @code{mail-setup-hook}: ++ ++@example ++(add-hook 'mail-setup-hook 'fortune-to-signature) ++@end example ++ ++@noindent ++You will probably need to set the variable @code{fortune-file} before ++using this. ++ ++@node Mail Methods ++@section Mail-Composition Methods ++@cindex mail-composition methods ++ ++@cindex MH mail interface ++@cindex Message mode for sending mail ++ In this chapter we have described the usual Emacs mode for editing ++and sending mail---Mail mode. Emacs has alternative facilities for ++editing and sending mail, including ++MH-E and Message mode, not documented in this manual. ++@xref{Top,,MH-E,mh-e, The Emacs Interface to MH}. @xref{Top,,Message,message, ++Message Manual}. You can choose any of them as your preferred method. ++The commands @code{C-x m}, @code{C-x 4 m} and @code{C-x 5 m} use ++whichever agent you have specified, as do various other Emacs commands ++and facilities that send mail. ++ ++@vindex mail-user-agent ++ To specify your mail-composition method, customize the variable ++@code{mail-user-agent}. Currently legitimate values include ++@code{sendmail-user-agent} (Mail mode), @code{mh-e-user-agent}, ++@code{message-user-agent} and @code{gnus-user-agent}. ++ ++ If you select a different mail-composition method, the information ++in this chapter about the @samp{*mail*} buffer and Mail mode does not ++apply; the other methods use a different format of text in a different ++buffer, and their commands are different as well. ++ ++@vindex read-mail-command ++ Similarly, to specify your preferred method for reading mail, ++customize the variable @code{read-mail-command}. The default is ++@code{rmail} (@pxref{Rmail}). ++ ++@ignore ++ arch-tag: d8a3dfc3-5d87-45c5-a7f2-69871b8e4fd6 ++@end ignore +diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi +new file mode 100644 +index 0000000..3202d28 +--- /dev/null ++++ b/doc/emacs/text.texi +@@ -0,0 +1,2929 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Text, Programs, Indentation, Top ++@chapter Commands for Human Languages ++@cindex text ++@cindex manipulating text ++ ++ This chapter describes Emacs commands that act on @dfn{text}, by ++which we mean sequences of characters in a human language (as opposed ++to, say, a computer programming language). These commands act in ways ++that take into account the syntactic and stylistic conventions of ++human languages: conventions involving words, sentences, paragraphs, ++and capital letters. There are also commands for @dfn{filling}, which ++means rearranging the lines of a paragraph to be approximately equal ++in length. These commands, while intended primarily for editing text, ++are also often useful for editing programs. ++ ++ Emacs has several major modes for editing human-language text. If ++the file contains ordinary text, use Text mode, which customizes Emacs ++in small ways for the syntactic conventions of text. Outline mode ++provides special commands for operating on text with an outline ++structure. ++@iftex ++@xref{Outline Mode}. ++@end iftex ++ ++ Emacs has other major modes for text which contains ``embedded'' ++commands, such as @TeX{} and La@TeX{} (@pxref{TeX Mode}); HTML, SGML, ++and XML (@pxref{HTML Mode}); and Groff and Nroff (@pxref{Nroff Mode}). ++In addition, you can edit formatted text in WYSIWYG style (``what you ++see is what you get''), using Enriched mode (@pxref{Formatted Text}). ++ ++@cindex ASCII art ++ If you need to edit pictures made out of text characters (commonly ++referred to as ``ASCII art''), use Picture mode, a special major mode ++for editing such pictures. ++@iftex ++@xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}. ++@end iftex ++@ifnottex ++@xref{Picture Mode}. ++@end ifnottex ++ ++ ++@cindex skeletons ++@cindex templates ++@cindex autotyping ++@cindex automatic typing ++ The ``automatic typing'' features may be useful when writing text. ++@inforef{Top,, autotype}. ++ ++@menu ++* Words:: Moving over and killing words. ++* Sentences:: Moving over and killing sentences. ++* Paragraphs:: Moving over paragraphs. ++* Pages:: Moving over pages. ++* Filling:: Filling or justifying text. ++* Case:: Changing the case of text. ++* Text Mode:: The major modes for editing text files. ++* Outline Mode:: Editing outlines. ++* TeX Mode:: Editing input to the formatter TeX. ++* HTML Mode:: Editing HTML, SGML, and XML files. ++* Nroff Mode:: Editing input to the formatter nroff. ++* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. ++* Text Based Tables:: Editing text-based tables in WYSIWYG fashion. ++@end menu ++ ++@node Words ++@section Words ++@cindex words ++@cindex Meta commands and words ++ ++ Emacs has commands for moving over or operating on words. By convention, ++the keys for them are all Meta characters. ++ ++@table @kbd ++@item M-f ++Move forward over a word (@code{forward-word}). ++@item M-b ++Move backward over a word (@code{backward-word}). ++@item M-d ++Kill up to the end of a word (@code{kill-word}). ++@item M-@key{DEL} ++Kill back to the beginning of a word (@code{backward-kill-word}). ++@item M-@@ ++Mark the end of the next word (@code{mark-word}). ++@item M-t ++Transpose two words or drag a word across others ++(@code{transpose-words}). ++@end table ++ ++ Notice how these keys form a series that parallels the character-based ++@kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is ++cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}. ++ ++@kindex M-f ++@kindex M-b ++@findex forward-word ++@findex backward-word ++ The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b} ++(@code{backward-word}) move forward and backward over words. These ++@key{Meta}-based key sequences are analogous to the key sequences ++@kbd{C-f} and @kbd{C-b}, which move over single characters. The ++analogy extends to numeric arguments, which serve as repeat counts. ++@kbd{M-f} with a negative argument moves backward, and @kbd{M-b} with ++a negative argument moves forward. Forward motion stops right after ++the last letter of the word, while backward motion stops right before ++the first letter. ++ ++@kindex M-d ++@findex kill-word ++ @kbd{M-d} (@code{kill-word}) kills the word after point. To be ++precise, it kills everything from point to the place @kbd{M-f} would ++move to. Thus, if point is in the middle of a word, @kbd{M-d} kills ++just the part after point. If some punctuation comes between point ++and the next word, it is killed along with the word. (If you wish to ++kill only the next word but not the punctuation before it, simply do ++@kbd{M-f} to get the end, and kill the word backwards with ++@kbd{M-@key{DEL}}.) @kbd{M-d} takes arguments just like @kbd{M-f}. ++ ++@findex backward-kill-word ++@kindex M-DEL ++ @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before ++point. It kills everything from point back to where @kbd{M-b} would ++move to. For instance, if point is after the space in @w{@samp{FOO, ++BAR}}, it kills @w{@samp{FOO, }}. If you wish to kill just ++@samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead ++of @kbd{M-@key{DEL}}. ++ ++@c Don't index M-t and transpose-words here, they are indexed in ++@c fixit.texi, in the node "Transpose". ++@c @kindex M-t ++@c @findex transpose-words ++ @kbd{M-t} (@code{transpose-words}) exchanges the word before or ++containing point with the following word. The delimiter characters between ++the words do not move. For example, @w{@samp{FOO, BAR}} transposes into ++@w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for ++more on transposition. ++ ++@kindex M-@@ ++@findex mark-word ++ To operate on the next @var{n} words with an operation which acts on ++the region, use the command @kbd{M-@@} (@code{mark-word}). This ++command does not move point, but sets the mark where @kbd{M-f} would ++move to. Once the mark is active, each additional @kbd{M-@@} advances ++the mark by one additional word. @kbd{M-@@} also accepts a numeric ++argument that says how many words to scan for the place to put the ++mark. ++ ++ The word commands' understanding of word boundaries is controlled ++by the syntax table. Any character can, for example, be declared to ++be a word delimiter. @xref{Syntax}. ++ ++@node Sentences ++@section Sentences ++@cindex sentences ++@cindex manipulating sentences ++ ++ The Emacs commands for manipulating sentences and paragraphs are mostly ++on Meta keys, so as to be like the word-handling commands. ++ ++@table @kbd ++@item M-a ++Move back to the beginning of the sentence (@code{backward-sentence}). ++@item M-e ++Move forward to the end of the sentence (@code{forward-sentence}). ++@item M-k ++Kill forward to the end of the sentence (@code{kill-sentence}). ++@item C-x @key{DEL} ++Kill back to the beginning of the sentence (@code{backward-kill-sentence}). ++@end table ++ ++@kindex M-a ++@kindex M-e ++@findex backward-sentence ++@findex forward-sentence ++ The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and ++@code{forward-sentence}) move to the beginning and end of the current ++sentence, respectively. They were chosen to resemble @kbd{C-a} and ++@kbd{C-e}, which move to the beginning and end of a line. Unlike ++them, @kbd{M-a} and @kbd{M-e} move over successive sentences if ++repeated. ++ ++ Moving backward over a sentence places point just before the first ++character of the sentence; moving forward places point right after the ++punctuation that ends the sentence. Neither one moves over the ++whitespace at the sentence boundary. ++ ++@kindex M-k ++@findex kill-sentence ++ Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to ++go with them, @kbd{M-a} and @kbd{M-e} have a corresponding kill ++command: @kbd{M-k} (@code{kill-sentence}) kills from point to the end ++of the sentence. With a positive numeric argument @var{n}, it kills ++the next @var{n} sentences; with a negative argument @minus{}@var{n}, ++it kills back to the beginning of the @var{n}th preceding sentence. ++ ++@kindex C-x DEL ++@findex backward-kill-sentence ++ The @kbd{C-x @key{DEL}} (@code{backward-kill-sentence}) kills back ++to the beginning of a sentence. ++ ++ The sentence commands assume that you follow the American typist's ++convention of putting two spaces at the end of a sentence; they consider ++a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!} ++followed by the end of a line or two spaces, with any number of ++@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between. ++A sentence also begins or ends wherever a paragraph begins or ends. ++It is useful to follow this convention, because it makes a distinction ++between periods that end a sentence and periods that indicate ++abbreviations; that enables the Emacs sentence commands to distinguish, ++too. These commands do not stop for periods that indicate abbreviations. ++ ++@vindex sentence-end-double-space ++ If you want to use just one space between sentences, you can set the ++variable @code{sentence-end-double-space} to @code{nil} to make the ++sentence commands stop for single spaces. However, this has a ++drawback: there is no way to distinguish between periods that end ++sentences and those that indicate abbreviations. For convenient and ++reliable editing, we therefore recommend you follow the two-space ++convention. The variable @code{sentence-end-double-space} also ++affects filling (@pxref{Fill Commands}) in related ways. ++ ++@vindex sentence-end ++ The variable @code{sentence-end} controls how to recognize the end ++of a sentence. If non-@code{nil}, its value should be a regular ++expression, which is used to match the last few characters of a ++sentence, together with the whitespace following the sentence ++(@pxref{Regexps}). If the value is @code{nil}, the default, then ++Emacs computes sentence ends according to various criteria such as the ++value of @code{sentence-end-double-space}. ++ ++@vindex sentence-end-without-period ++ Some languages do not use periods to indicate the end of a sentence. ++For example, sentences in Thai end with a double space but without a ++period. Set the variable @code{sentence-end-without-period} to ++@code{t} in such cases. ++ ++@node Paragraphs ++@section Paragraphs ++@cindex paragraphs ++@cindex manipulating paragraphs ++@kindex M-@{ ++@kindex M-@} ++@findex backward-paragraph ++@findex forward-paragraph ++ ++ The Emacs commands for manipulating paragraphs are also on Meta keys. ++ ++@table @kbd ++@item M-@{ ++Move back to previous paragraph beginning (@code{backward-paragraph}). ++@item M-@} ++Move forward to next paragraph end (@code{forward-paragraph}). ++@item M-h ++Put point and mark around this or next paragraph (@code{mark-paragraph}). ++@end table ++ ++ @kbd{M-@{} moves to the beginning of the current or previous ++paragraph, while @kbd{M-@}} moves to the end of the current or next ++paragraph. Blank lines and text-formatter command lines separate ++paragraphs and are not considered part of any paragraph. If there is ++a blank line before the paragraph, @kbd{M-@{} moves to the blank line, ++because that is convenient in practice. ++ ++ In Text mode, an indented line is not a paragraph break. If you ++want indented lines to have this effect, use Paragraph-Indent Text ++mode instead. @xref{Text Mode}. ++ ++ In major modes for programs, paragraphs begin and end only at blank ++lines. This makes the paragraph commands useful, even though there ++are no paragraphs as such in a program. ++ ++ When you have set a fill prefix, then paragraphs are delimited by ++all lines which don't start with the fill prefix. @xref{Filling}. ++ ++@kindex M-h ++@findex mark-paragraph ++ When you wish to operate on a paragraph, type @kbd{M-h} ++(@code{mark-paragraph}) to set the region around it. For example, ++@kbd{M-h C-w} kills the paragraph around or after point. @kbd{M-h} ++puts point at the beginning and mark at the end of the paragraph point ++was in. If point is between paragraphs (in a run of blank lines, or ++at a boundary), the paragraph following point is surrounded by point ++and mark. If there are blank lines preceding the first line of the ++paragraph, one of these blank lines is included in the region. If the ++region is already active, the command sets the mark without changing ++point; furthermore, each subsequent @kbd{M-h} further advances the ++mark by one paragraph. ++ ++@vindex paragraph-start ++@vindex paragraph-separate ++ The precise definition of a paragraph boundary is controlled by the ++variables @code{paragraph-separate} and @code{paragraph-start}. The ++value of @code{paragraph-start} is a regexp that should match any line ++that either starts or separates paragraphs. The value of ++@code{paragraph-separate} is another regexp that should match only lines ++that separate paragraphs without being part of any paragraph (for ++example, blank lines). Lines that start a new paragraph and are ++contained in it must match only @code{paragraph-start}, not ++@code{paragraph-separate}. Each regular expression must match at the ++left margin. For example, in Fundamental mode, @code{paragraph-start} ++is @w{@code{"\f\\|[ \t]*$"}}, and @code{paragraph-separate} is ++@w{@code{"[ \t\f]*$"}}. ++ ++ Normally it is desirable for page boundaries to separate paragraphs. ++The default values of these variables recognize the usual separator for ++pages. ++ ++@node Pages ++@section Pages ++ ++@cindex pages ++@cindex formfeed character ++ Within some text files, text is divided into @dfn{pages}, which are ++delimited by the @dfn{formfeed character} (@acronym{ASCII} code 12, ++sometimes denoted as @key{control-L}). When you print hardcopy for a ++file, the formfeed character forces a page break: each page of the ++file goes on a separate page on paper. Most Emacs commands treat the ++formfeed character just like any other character: you can insert it ++with @kbd{C-q C-l}, and delete it with @key{DEL}. However, since ++pages are often meaningful divisions of the file, Emacs provides ++commands to move over them and operate on them. ++ ++@table @kbd ++@item C-x [ ++Move point to previous page boundary (@code{backward-page}). ++@item C-x ] ++Move point to next page boundary (@code{forward-page}). ++@item C-x C-p ++Put point and mark around this page (or another page) (@code{mark-page}). ++@item C-x l ++Count the lines in this page (@code{count-lines-page}). ++@end table ++ ++@kindex C-x [ ++@kindex C-x ] ++@findex forward-page ++@findex backward-page ++ The @kbd{C-x [} (@code{backward-page}) command moves point to immediately ++after the previous page delimiter. If point is already right after a page ++delimiter, it skips that one and stops at the previous one. A numeric ++argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page}) ++command moves forward past the next page delimiter. ++ ++@kindex C-x C-p ++@findex mark-page ++ The @kbd{C-x C-p} command (@code{mark-page}) puts point at the ++beginning of the current page and the mark at the end. The page ++delimiter at the end is included (the mark follows it). The page ++delimiter at the front is excluded (point follows it). ++ ++ @kbd{C-x C-p C-w} is a handy way to kill a page to move it ++elsewhere. If you move to another page delimiter with @kbd{C-x [} and ++@kbd{C-x ]}, then yank the killed page, all the pages will be properly ++delimited once again. The reason @kbd{C-x C-p} includes only the ++following page delimiter in the region is to ensure that. ++ ++ A numeric argument to @kbd{C-x C-p} specifies which page to go to, ++relative to the current one. Zero means the current page. One means ++the next page, and @minus{}1 means the previous one. ++ ++@kindex C-x l ++@findex count-lines-page ++ The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding ++where to break a page in two. It displays in the echo area the total number ++of lines in the current page, and then divides it up into those preceding ++the current line and those following, as in ++ ++@example ++Page has 96 (72+25) lines ++@end example ++ ++@noindent ++ Notice that the sum is off by one; this is correct if point is not at the ++beginning of a line. ++ ++@vindex page-delimiter ++ The variable @code{page-delimiter} controls where pages begin. Its ++value is a regular expression that matches the beginning of a line ++that separates pages (@pxref{Regexps}). The normal value of this ++variable is @code{"^\f"}, which matches a formfeed character at the ++beginning of a line. ++ ++@node Filling ++@section Filling Text ++@cindex filling text ++ ++ @dfn{Filling} text means breaking it up into lines that fit a ++specified width. Emacs does filling in two ways. In Auto Fill mode, ++inserting text with self-inserting characters also automatically fills ++it. There are also explicit fill commands that you can use when editing ++text leaves it unfilled. When you edit formatted text, you can specify ++a style of filling for each portion of the text (@pxref{Formatted ++Text}). ++ ++@menu ++* Auto Fill:: Auto Fill mode breaks long lines automatically. ++* Fill Commands:: Commands to refill paragraphs and center lines. ++* Fill Prefix:: Filling paragraphs that are indented ++ or in a comment, etc. ++* Adaptive Fill:: How Emacs can determine the fill prefix automatically. ++* Refill:: Keeping paragraphs filled. ++* Longlines:: Editing text with very long lines. ++@end menu ++ ++@node Auto Fill ++@subsection Auto Fill Mode ++@cindex Auto Fill mode ++@cindex mode, Auto Fill ++ ++ @dfn{Auto Fill} mode is a minor mode in which lines are broken ++automatically when they become too wide. Breaking happens only when ++you type a @key{SPC} or @key{RET}. ++ ++@table @kbd ++@item M-x auto-fill-mode ++Enable or disable Auto Fill mode. ++@item @key{SPC} ++@itemx @key{RET} ++In Auto Fill mode, break lines when appropriate. ++@end table ++ ++@findex auto-fill-mode ++ @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off ++if it was on. With a positive numeric argument it always turns Auto ++Fill mode on, and with a negative argument always turns it off. You can ++see when Auto Fill mode is in effect by the presence of the word ++@samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is ++a minor mode which is enabled or disabled for each buffer individually. ++@xref{Minor Modes}. ++ ++ In Auto Fill mode, lines are broken automatically at spaces when they ++get longer than the desired width. Line breaking and rearrangement ++takes place only when you type @key{SPC} or @key{RET}. If you wish to ++insert a space or newline without permitting line-breaking, type ++@kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a ++control-J). Also, @kbd{C-o} inserts a newline without line breaking. ++ ++ Auto Fill mode works well with programming-language modes, because it ++indents new lines with @key{TAB}. If a line ending in a comment gets ++too long, the text of the comment is split into two comment lines. ++Optionally, new comment delimiters are inserted at the end of the first ++line and the beginning of the second so that each line is a separate ++comment; the variable @code{comment-multi-line} controls the choice ++(@pxref{Comments}). ++ ++ Adaptive filling (@pxref{Adaptive Fill}) works for Auto Filling as ++well as for explicit fill commands. It takes a fill prefix ++automatically from the second or first line of a paragraph. ++ ++ Auto Fill mode does not refill entire paragraphs; it can break lines but ++cannot merge lines. So editing in the middle of a paragraph can result in ++a paragraph that is not correctly filled. The easiest way to make the ++paragraph properly filled again is usually with the explicit fill commands. ++@ifnottex ++@xref{Fill Commands}. ++@end ifnottex ++ ++ Many users like Auto Fill mode and want to use it in all text files. ++The section on init files says how to arrange this permanently for yourself. ++@xref{Init File}. ++ ++@node Fill Commands ++@subsection Explicit Fill Commands ++ ++@table @kbd ++@item M-q ++Fill current paragraph (@code{fill-paragraph}). ++@item C-x f ++Set the fill column (@code{set-fill-column}). ++@item M-x fill-region ++Fill each paragraph in the region (@code{fill-region}). ++@item M-x fill-region-as-paragraph ++Fill the region, considering it as one paragraph. ++@item M-o M-s ++Center a line. ++@end table ++ ++@kindex M-q ++@findex fill-paragraph ++ To refill a paragraph, use the command @kbd{M-q} ++(@code{fill-paragraph}). This operates on the paragraph that point is ++inside, or the one after point if point is between paragraphs. ++Refilling works by removing all the line-breaks, then inserting new ++ones where necessary. When there is an active region, this command ++operates on the text within the region like @code{fill-region}. ++ ++@findex fill-region ++ To refill many paragraphs, use @kbd{M-x fill-region}, which ++finds the paragraphs in the region and fills each of them. ++ ++@findex fill-region-as-paragraph ++ @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h} ++for finding paragraph boundaries (@pxref{Paragraphs}). For more ++control, you can use @kbd{M-x fill-region-as-paragraph}, which refills ++everything between point and mark as a single paragraph. This command ++deletes any blank lines within the region, so separate blocks of text ++end up combined into one block. ++ ++@cindex justification ++ A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text ++as well as filling it. This means that extra spaces are inserted to ++make the right margin line up exactly at the fill column. To remove ++the extra spaces, use @kbd{M-q} with no argument. (Likewise for ++@code{fill-region}.) Another way to control justification, and choose ++other styles of filling, is with the @code{justification} text ++property; see @ref{Format Justification}. ++ ++@kindex M-o M-s @r{(Text mode)} ++@cindex centering ++@findex center-line ++ The command @kbd{M-o M-s} (@code{center-line}) centers the current line ++within the current fill column. With an argument @var{n}, it centers ++@var{n} lines individually and moves past them. This binding is ++made by Text mode and is available only in that and related modes ++(@pxref{Text Mode}). ++ ++@vindex fill-column ++@kindex C-x f ++@findex set-fill-column ++ The maximum line width for filling is in the variable ++@code{fill-column}. Altering the value of @code{fill-column} makes it ++local to the current buffer; until that time, the default value is in ++effect. The default is initially 70. @xref{Locals}. The easiest way ++to set @code{fill-column} is to use the command @kbd{C-x f} ++(@code{set-fill-column}). With a numeric argument, it uses that as the ++new fill column. With just @kbd{C-u} as argument, it sets ++@code{fill-column} to the current horizontal position of point. ++ ++ Emacs commands normally consider a period followed by two spaces or by ++a newline as the end of a sentence; a period followed by just one space ++indicates an abbreviation and not the end of a sentence. To preserve ++the distinction between these two ways of using a period, the fill ++commands do not break a line after a period followed by just one space. ++ ++ If the variable @code{sentence-end-double-space} is @code{nil}, the ++fill commands expect and leave just one space at the end of a sentence. ++Ordinarily this variable is @code{t}, so the fill commands insist on ++two spaces for the end of a sentence, as explained above. @xref{Sentences}. ++ ++@vindex colon-double-space ++ If the variable @code{colon-double-space} is non-@code{nil}, the ++fill commands put two spaces after a colon. ++ ++@vindex fill-nobreak-predicate ++ The variable @code{fill-nobreak-predicate} is a hook (an abnormal ++hook, @pxref{Hooks}) specifying additional conditions where ++line-breaking is not allowed. Each function is called with no ++arguments, with point at a place where Emacs is considering breaking ++the line. If a function returns a non-@code{nil} value, then that's ++a bad place to break the line. Two standard functions you can use are ++@code{fill-single-word-nobreak-p} (don't break after the first word of ++a sentence or before the last) and @code{fill-french-nobreak-p} (don't ++break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). ++ ++@node Fill Prefix ++@subsection The Fill Prefix ++ ++@cindex fill prefix ++ To fill a paragraph in which each line starts with a special marker ++(which might be a few spaces, giving an indented paragraph), you can use ++the @dfn{fill prefix} feature. The fill prefix is a string that Emacs ++expects every line to start with, and which is not included in filling. ++You can specify a fill prefix explicitly; Emacs can also deduce the ++fill prefix automatically (@pxref{Adaptive Fill}). ++ ++@table @kbd ++@item C-x . ++Set the fill prefix (@code{set-fill-prefix}). ++@item M-q ++Fill a paragraph using current fill prefix (@code{fill-paragraph}). ++@item M-x fill-individual-paragraphs ++Fill the region, considering each change of indentation as starting a ++new paragraph. ++@item M-x fill-nonuniform-paragraphs ++Fill the region, considering only paragraph-separator lines as starting ++a new paragraph. ++@end table ++ ++@kindex C-x . ++@findex set-fill-prefix ++ To specify a fill prefix for the current buffer, move to a line that ++starts with the desired prefix, put point at the end of the prefix, ++and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period ++after the @kbd{C-x}.) To turn off the fill prefix, specify an empty ++prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line. ++ ++ When a fill prefix is in effect, the fill commands remove the fill ++prefix from each line of the paragraph before filling and insert it on ++each line after filling. (The beginning of the first line of the ++paragraph is left unchanged, since often that is intentionally ++different.) Auto Fill mode also inserts the fill prefix automatically ++when it makes a new line. The @kbd{C-o} command inserts the fill ++prefix on new lines it creates, when you use it at the beginning of a ++line (@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes ++the prefix (if it occurs) after the newline that it deletes ++(@pxref{Indentation}). ++ ++ For example, if @code{fill-column} is 40 and you set the fill prefix ++to @samp{;; }, then @kbd{M-q} in the following text ++ ++@example ++;; This is an ++;; example of a paragraph ++;; inside a Lisp-style comment. ++@end example ++ ++@noindent ++produces this: ++ ++@example ++;; This is an example of a paragraph ++;; inside a Lisp-style comment. ++@end example ++ ++ Lines that do not start with the fill prefix are considered to start ++paragraphs, both in @kbd{M-q} and the paragraph commands; this gives ++good results for paragraphs with hanging indentation (every line ++indented except the first one). Lines which are blank or indented once ++the prefix is removed also separate or start paragraphs; this is what ++you want if you are writing multi-paragraph comments with a comment ++delimiter on each line. ++ ++@findex fill-individual-paragraphs ++ You can use @kbd{M-x fill-individual-paragraphs} to set the fill ++prefix for each paragraph automatically. This command divides the ++region into paragraphs, treating every change in the amount of ++indentation as the start of a new paragraph, and fills each of these ++paragraphs. Thus, all the lines in one ``paragraph'' have the same ++amount of indentation. That indentation serves as the fill prefix for ++that paragraph. ++ ++@findex fill-nonuniform-paragraphs ++ @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides ++the region into paragraphs in a different way. It considers only ++paragraph-separating lines (as defined by @code{paragraph-separate}) as ++starting a new paragraph. Since this means that the lines of one ++paragraph may have different amounts of indentation, the fill prefix ++used is the smallest amount of indentation of any of the lines of the ++paragraph. This gives good results with styles that indent a paragraph's ++first line more or less that the rest of the paragraph. ++ ++@vindex fill-prefix ++ The fill prefix is stored in the variable @code{fill-prefix}. Its value ++is a string, or @code{nil} when there is no fill prefix. This is a ++per-buffer variable; altering the variable affects only the current buffer, ++but there is a default value which you can change as well. @xref{Locals}. ++ ++ The @code{indentation} text property provides another way to control ++the amount of indentation paragraphs receive. @xref{Format Indentation}. ++ ++@node Adaptive Fill ++@subsection Adaptive Filling ++ ++@cindex adaptive filling ++ The fill commands can deduce the proper fill prefix for a paragraph ++automatically in certain cases: either whitespace or certain punctuation ++characters at the beginning of a line are propagated to all lines of the ++paragraph. ++ ++ If the paragraph has two or more lines, the fill prefix is taken from ++the paragraph's second line, but only if it appears on the first line as ++well. ++ ++ If a paragraph has just one line, fill commands @emph{may} take a ++prefix from that line. The decision is complicated because there are ++three reasonable things to do in such a case: ++ ++@itemize @bullet ++@item ++Use the first line's prefix on all the lines of the paragraph. ++ ++@item ++Indent subsequent lines with whitespace, so that they line up under the ++text that follows the prefix on the first line, but don't actually copy ++the prefix from the first line. ++ ++@item ++Don't do anything special with the second and following lines. ++@end itemize ++ ++ All three of these styles of formatting are commonly used. So the ++fill commands try to determine what you would like, based on the prefix ++that appears and on the major mode. Here is how. ++ ++@vindex adaptive-fill-first-line-regexp ++ If the prefix found on the first line matches ++@code{adaptive-fill-first-line-regexp}, or if it appears to be a ++comment-starting sequence (this depends on the major mode), then the ++prefix found is used for filling the paragraph, provided it would not ++act as a paragraph starter on subsequent lines. ++ ++ Otherwise, the prefix found is converted to an equivalent number of ++spaces, and those spaces are used as the fill prefix for the rest of the ++lines, provided they would not act as a paragraph starter on subsequent ++lines. ++ ++ In Text mode, and other modes where only blank lines and page ++delimiters separate paragraphs, the prefix chosen by adaptive filling ++never acts as a paragraph starter, so it can always be used for filling. ++ ++@vindex adaptive-fill-mode ++@vindex adaptive-fill-regexp ++ The variable @code{adaptive-fill-regexp} determines what kinds of line ++beginnings can serve as a fill prefix: any characters at the start of ++the line that match this regular expression are used. If you set the ++variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is ++never chosen automatically. ++ ++@vindex adaptive-fill-function ++ You can specify more complex ways of choosing a fill prefix ++automatically by setting the variable @code{adaptive-fill-function} to a ++function. This function is called with point after the left margin of a ++line, and it should return the appropriate fill prefix based on that ++line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets ++a chance to find a prefix. ++ ++@node Refill ++@subsection Refill Mode ++@cindex refilling text, word processor style ++@cindex modes, Refill ++@cindex Refill minor mode ++ ++ Refill minor mode provides support for keeping paragraphs filled as ++you type or modify them in other ways. It provides an effect similar ++to typical word processor behavior. This works by running a ++paragraph-filling command at suitable times. ++ ++ To toggle the use of Refill mode in the current buffer, type ++@kbd{M-x refill-mode}. When you are typing text, only characters ++which normally trigger auto filling, like the space character, will ++trigger refilling. This is to avoid making it too slow. Apart from ++self-inserting characters, other commands which modify the text cause ++refilling. ++ ++ The current implementation is preliminary and not robust. You can ++get better ``line wrapping'' behavior using Longlines mode. ++@xref{Longlines}. However, Longlines mode has an important ++side-effect: the newlines that it inserts for you are not saved to ++disk, so the files that you make with Longlines mode will appear to be ++completely unfilled if you edit them without Longlines mode. ++ ++@node Longlines ++@subsection Long Lines Mode ++@cindex refilling text, word processor style ++@cindex modes, Long Lines ++@cindex word wrap ++@cindex Long Lines minor mode ++ ++ Sometimes, you may come across ``unfilled'' text files, which Emacs ++normally displays as a bunch of extremely long lines. Comfortably ++reading and editing such files normally requires ``word wrap'', a ++feature that breaks up each long text line into multiple screen lines ++in a readable manner---by putting the breaks at word boundaries. Many ++text editors, such as those built into many web browsers, perform word ++wrapping by default. ++ ++ There are two different minor modes in Emacs that perform word ++wrapping. The first is Visual Line mode, which does it by altering ++the behavior of screen line continuation. @xref{Visual Line Mode}, ++for information about Visual Line mode. ++ ++@findex longlines-mode ++ Instead of using Visual Line mode, you can use a minor mode called ++Long Lines mode. Long Lines mode wraps lines by inserting or deleting ++@dfn{soft newlines} as you type (@pxref{Hard and Soft Newlines}). ++These soft newlines won't show up when you save the buffer into a ++file, or when you copy the text into the kill ring, clipboard, or a ++register. Unlike Visual Line mode, Lone Lines mode breaks long lines ++at the fill column (@pxref{Fill Commands}), rather than the right ++window edge. To enable Long Lines mode, type @kbd{M-x ++longlines-mode}. If the text is full of long lines, this also ++immediately ``wraps'' them all. ++ ++@findex longlines-auto-wrap ++ The word wrap performed by Long Lines mode is @emph{not} the same as ++ordinary filling (@pxref{Fill Commands}). It does not contract ++multiple spaces into a single space, recognize fill prefixes ++(@pxref{Fill Prefix}), or perform adaptive filling (@pxref{Adaptive ++Fill}). The reason for this is that a wrapped line is still, ++conceptually, a single line. Each soft newline is equivalent to ++exactly one space in that long line, and vice versa. However, you can ++still call filling functions such as @kbd{M-q}, and these will work as ++expected, inserting soft newlines that won't show up on disk or when ++the text is copied. You can even rely entirely on the normal fill ++commands by turning off automatic line wrapping, with @kbd{C-u M-x ++longlines-auto-wrap}. To turn automatic line wrapping back on, type ++@kbd{M-x longlines-auto-wrap}. ++ ++@findex longlines-show-hard-newlines ++ Type @kbd{RET} to insert a hard newline, one which automatic ++refilling will not remove. If you want to see where all the hard ++newlines are, type @kbd{M-x longlines-show-hard-newlines}. This will ++mark each hard newline with a special symbol. The same command with a ++prefix argument turns this display off. ++ ++ Long Lines mode does not change normal text files that are already ++filled, since the existing newlines are considered hard newlines. ++Before Long Lines can do anything, you need to transform each ++paragraph into a long line. One way is to set @code{fill-column} to a ++large number (e.g., @kbd{C-u 9999 C-x f}), re-fill all the paragraphs, ++and then set @code{fill-column} back to its original value. ++ ++@node Case ++@section Case Conversion Commands ++@cindex case conversion ++ ++ Emacs has commands for converting either a single word or any arbitrary ++range of text to upper case or to lower case. ++ ++@table @kbd ++@item M-l ++Convert following word to lower case (@code{downcase-word}). ++@item M-u ++Convert following word to upper case (@code{upcase-word}). ++@item M-c ++Capitalize the following word (@code{capitalize-word}). ++@item C-x C-l ++Convert region to lower case (@code{downcase-region}). ++@item C-x C-u ++Convert region to upper case (@code{upcase-region}). ++@end table ++ ++@kindex M-l ++@kindex M-u ++@kindex M-c ++@cindex words, case conversion ++@cindex converting text to upper or lower case ++@cindex capitalizing words ++@findex downcase-word ++@findex upcase-word ++@findex capitalize-word ++ The word conversion commands are the most useful. @kbd{M-l} ++(@code{downcase-word}) converts the word after point to lower case, moving ++past it. Thus, repeating @kbd{M-l} converts successive words. ++@kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while ++@kbd{M-c} (@code{capitalize-word}) puts the first letter of the word ++into upper case and the rest into lower case. All these commands convert ++several words at once if given an argument. They are especially convenient ++for converting a large amount of text from all upper case to mixed case, ++because you can move through the text using @kbd{M-l}, @kbd{M-u} or ++@kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead ++to skip a word. ++ ++ When given a negative argument, the word case conversion commands apply ++to the appropriate number of words before point, but do not move point. ++This is convenient when you have just typed a word in the wrong case: you ++can give the case conversion command and continue typing. ++ ++ If a word case conversion command is given in the middle of a word, ++it applies only to the part of the word which follows point. (This is ++comparable to what @kbd{M-d} (@code{kill-word}) does.) With a ++negative argument, case conversion applies only to the part of the ++word before point. ++ ++@kindex C-x C-l ++@kindex C-x C-u ++@findex downcase-region ++@findex upcase-region ++ The other case conversion commands are @kbd{C-x C-u} ++(@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which ++convert everything between point and mark to the specified case. Point and ++mark do not move. ++ ++ The region case conversion commands @code{upcase-region} and ++@code{downcase-region} are normally disabled. This means that they ask ++for confirmation if you try to use them. When you confirm, you may ++enable the command, which means it will not ask for confirmation again. ++@xref{Disabling}. ++ ++@node Text Mode ++@section Text Mode ++@cindex Text mode ++@cindex mode, Text ++@findex text-mode ++ ++ When you edit files of text in a human language, it's more convenient ++to use Text mode rather than Fundamental mode. To enter Text mode, type ++@kbd{M-x text-mode}. ++ ++ In Text mode, only blank lines and page delimiters separate ++paragraphs. As a result, paragraphs can be indented, and adaptive ++filling determines what indentation to use when filling a paragraph. ++@xref{Adaptive Fill}. ++ ++@kindex TAB @r{(Text mode)} ++ Text mode defines @key{TAB} to run @code{indent-relative} ++(@pxref{Indentation}), so that you can conveniently indent a line like ++the previous line. ++ ++ Text mode turns off the features concerned with comments except when ++you explicitly invoke them. It changes the syntax table so that ++single-quotes are considered part of words. However, if a word starts ++with single-quotes, these are treated as a prefix for purposes such as ++capitalization. That is, @kbd{M-c} will convert @samp{'hello'} into ++@samp{'Hello'}, as expected. ++ ++@cindex Paragraph-Indent Text mode ++@cindex mode, Paragraph-Indent Text ++@findex paragraph-indent-text-mode ++@findex paragraph-indent-minor-mode ++ If you indent the first lines of paragraphs, then you should use ++Paragraph-Indent Text mode rather than Text mode. In this mode, you ++do not need to have blank lines between paragraphs, because the ++first-line indentation is sufficient to start a paragraph; however ++paragraphs in which every line is indented are not supported. Use ++@kbd{M-x paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x ++paragraph-indent-minor-mode} to enable an equivalent minor mode in ++situations where you can't change the major mode---in mail ++composition, for instance. ++ ++@kindex M-TAB @r{(Text mode)} ++ Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} ++as the command @code{ispell-complete-word}, which performs completion ++of the partial word in the buffer before point, using the spelling ++dictionary as the space of possible words. @xref{Spelling}. If your ++window manager defines @kbd{M-@key{TAB}} to switch windows, you can ++type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}. ++ ++@vindex text-mode-hook ++ Entering Text mode runs the hook @code{text-mode-hook}. Other major ++modes related to Text mode also run this hook, followed by hooks of ++their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{} ++mode, Outline mode, and Mail mode. Hook functions on ++@code{text-mode-hook} can look at the value of @code{major-mode} to see ++which of these modes is actually being entered. @xref{Hooks}. ++ ++@node Outline Mode ++@section Outline Mode ++@cindex Outline mode ++@cindex mode, Outline ++@cindex invisible lines ++ ++@findex outline-mode ++@findex outline-minor-mode ++@vindex outline-minor-mode-prefix ++ Outline mode is a major mode much like Text mode but intended for ++editing outlines. It allows you to make parts of the text temporarily ++invisible so that you can see the outline structure. Type @kbd{M-x ++outline-mode} to switch to Outline mode as the major mode of the current ++buffer. ++ ++ When Outline mode makes a line invisible, the line does not appear ++on the screen. The screen appears exactly as if the invisible line ++were deleted, except that an ellipsis (three periods in a row) appears ++at the end of the previous visible line. (Multiple consecutive ++invisible lines produce just one ellipsis.) ++ ++ Editing commands that operate on lines, such as @kbd{C-n} and ++@kbd{C-p}, treat the text of the invisible line as part of the previous ++visible line. Killing the ellipsis at the end of a visible line ++really kills all the following invisible lines. ++ ++ Outline minor mode provides the same commands as the major mode, ++Outline mode, but you can use it in conjunction with other major modes. ++Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in ++the current buffer. You can also specify this in the text of a file, ++with a file local variable of the form @samp{mode: outline-minor} ++(@pxref{File Variables}). ++ ++@kindex C-c @@ @r{(Outline minor mode)} ++ The major mode, Outline mode, provides special key bindings on the ++@kbd{C-c} prefix. Outline minor mode provides similar bindings with ++@kbd{C-c @@} as the prefix; this is to reduce the conflicts with the ++major mode's special commands. (The variable ++@code{outline-minor-mode-prefix} controls the prefix used.) ++ ++@vindex outline-mode-hook ++ Entering Outline mode runs the hook @code{text-mode-hook} followed by ++the hook @code{outline-mode-hook} (@pxref{Hooks}). ++ ++@menu ++* Format: Outline Format. What the text of an outline looks like. ++* Motion: Outline Motion. Special commands for moving through ++ outlines. ++* Visibility: Outline Visibility. Commands to control what is visible. ++* Views: Outline Views. Outlines and multiple views. ++* Foldout:: Folding means zooming in on outlines. ++@end menu ++ ++@node Outline Format ++@subsection Format of Outlines ++ ++@cindex heading lines (Outline mode) ++@cindex body lines (Outline mode) ++ Outline mode assumes that the lines in the buffer are of two types: ++@dfn{heading lines} and @dfn{body lines}. A heading line represents a ++topic in the outline. Heading lines start with one or more stars; the ++number of stars determines the depth of the heading in the outline ++structure. Thus, a heading line with one star is a major topic; all the ++heading lines with two stars between it and the next one-star heading ++are its subtopics; and so on. Any line that is not a heading line is a ++body line. Body lines belong with the preceding heading line. Here is ++an example: ++ ++@example ++* Food ++This is the body, ++which says something about the topic of food. ++ ++** Delicious Food ++This is the body of the second-level header. ++ ++** Distasteful Food ++This could have ++a body too, with ++several lines. ++ ++*** Dormitory Food ++ ++* Shelter ++Another first-level topic with its header line. ++@end example ++ ++ A heading line together with all following body lines is called ++collectively an @dfn{entry}. A heading line together with all following ++deeper heading lines and their body lines is called a @dfn{subtree}. ++ ++@vindex outline-regexp ++ You can customize the criterion for distinguishing heading lines by ++setting the variable @code{outline-regexp}. (The recommended ways to ++do this are in a major mode function or with a file local variable.) ++Any line whose beginning has a match for this regexp is considered a ++heading line. Matches that start within a line (not at the left ++margin) do not count. ++ ++ The length of the matching text determines the level of the heading; ++longer matches make a more deeply nested level. Thus, for example, if ++a text formatter has commands @samp{@@chapter}, @samp{@@section} and ++@samp{@@subsection} to divide the document into chapters and sections, ++you could make those lines count as heading lines by setting ++@code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note ++the trick: the two words @samp{chapter} and @samp{section} are equally ++long, but by defining the regexp to match only @samp{chap} we ensure ++that the length of the text matched on a chapter heading is shorter, ++so that Outline mode will know that sections are contained in ++chapters. This works as long as no other command starts with ++@samp{@@chap}. ++ ++@vindex outline-level ++ You can explicitly specify a rule for calculating the level of a ++heading line by setting the variable @code{outline-level}. The value ++of @code{outline-level} should be a function that takes no arguments ++and returns the level of the current heading. The recommended ways to ++set this variable are in a major mode command or with a file local ++variable. ++ ++@node Outline Motion ++@subsection Outline Motion Commands ++ ++ Outline mode provides special motion commands that move backward and ++forward to heading lines. ++ ++@table @kbd ++@item C-c C-n ++Move point to the next visible heading line ++(@code{outline-next-visible-heading}). ++@item C-c C-p ++Move point to the previous visible heading line ++(@code{outline-previous-visible-heading}). ++@item C-c C-f ++Move point to the next visible heading line at the same level ++as the one point is on (@code{outline-forward-same-level}). ++@item C-c C-b ++Move point to the previous visible heading line at the same level ++(@code{outline-backward-same-level}). ++@item C-c C-u ++Move point up to a lower-level (more inclusive) visible heading line ++(@code{outline-up-heading}). ++@end table ++ ++@findex outline-next-visible-heading ++@findex outline-previous-visible-heading ++@kindex C-c C-n @r{(Outline mode)} ++@kindex C-c C-p @r{(Outline mode)} ++ @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next ++heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves ++similarly backward. Both accept numeric arguments as repeat counts. The ++names emphasize that invisible headings are skipped, but this is not really ++a special feature. All editing commands that look for lines ignore the ++invisible lines automatically. ++ ++@findex outline-up-heading ++@findex outline-forward-same-level ++@findex outline-backward-same-level ++@kindex C-c C-f @r{(Outline mode)} ++@kindex C-c C-b @r{(Outline mode)} ++@kindex C-c C-u @r{(Outline mode)} ++ More powerful motion commands understand the level structure of headings. ++@kbd{C-c C-f} (@code{outline-forward-same-level}) and ++@kbd{C-c C-b} (@code{outline-backward-same-level}) move from one ++heading line to another visible heading at the same depth in ++the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves ++backward to another heading that is less deeply nested. ++ ++@node Outline Visibility ++@subsection Outline Visibility Commands ++ ++ The other special commands of outline mode are used to make lines visible ++or invisible. Their names all start with @code{hide} or @code{show}. ++Most of them fall into pairs of opposites. They are not undoable; instead, ++you can undo right past them. Making lines visible or invisible is simply ++not recorded by the undo mechanism. ++ ++ Many of these commands act on the ``current'' heading line. If ++point is on a heading line, that is the current heading line; if point ++is on a body line, the current heading line is the nearest preceding ++header line. ++ ++@table @kbd ++@item C-c C-c ++Make the current heading line's body invisible (@code{hide-entry}). ++@item C-c C-e ++Make the current heading line's body visible (@code{show-entry}). ++@item C-c C-d ++Make everything under the current heading invisible, not including the ++heading itself (@code{hide-subtree}). ++@item C-c C-s ++Make everything under the current heading visible, including body, ++subheadings, and their bodies (@code{show-subtree}). ++@item C-c C-l ++Make the body of the current heading line, and of all its subheadings, ++invisible (@code{hide-leaves}). ++@item C-c C-k ++Make all subheadings of the current heading line, at all levels, ++visible (@code{show-branches}). ++@item C-c C-i ++Make immediate subheadings (one level down) of the current heading ++line visible (@code{show-children}). ++@item C-c C-t ++Make all body lines in the buffer invisible (@code{hide-body}). ++@item C-c C-a ++Make all lines in the buffer visible (@code{show-all}). ++@item C-c C-q ++Hide everything except the top @var{n} levels of heading lines ++(@code{hide-sublevels}). ++@item C-c C-o ++Hide everything except for the heading or body that point is in, plus ++the headings leading up from there to the top level of the outline ++(@code{hide-other}). ++@end table ++ ++@findex hide-entry ++@findex show-entry ++@kindex C-c C-c @r{(Outline mode)} ++@kindex C-c C-e @r{(Outline mode)} ++ Two commands that are exact opposites are @kbd{C-c C-c} ++(@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They apply ++to the body lines directly following the current heading line. ++Subheadings and their bodies are not affected. ++ ++@findex hide-subtree ++@findex show-subtree ++@kindex C-c C-s @r{(Outline mode)} ++@kindex C-c C-d @r{(Outline mode)} ++@cindex subtree (Outline mode) ++ Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) ++and @kbd{C-c C-s} (@code{show-subtree}). Both apply to the current ++heading line's @dfn{subtree}: its body, all its subheadings, both ++direct and indirect, and all of their bodies. In other words, the ++subtree contains everything following the current heading line, up to ++and not including the next heading of the same or higher rank. ++ ++@findex hide-leaves ++@findex show-branches ++@kindex C-c C-l @r{(Outline mode)} ++@kindex C-c C-k @r{(Outline mode)} ++ Intermediate between a visible subtree and an invisible one is having ++all the subheadings visible but none of the body. There are two ++commands for doing this, depending on whether you want to hide the ++bodies or make the subheadings visible. They are @kbd{C-c C-l} ++(@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}). ++ ++@kindex C-c C-i @r{(Outline mode)} ++@findex show-children ++ A little weaker than @code{show-branches} is @kbd{C-c C-i} ++(@code{show-children}). It makes just the direct subheadings ++visible---those one level down. Deeper subheadings remain invisible, if ++they were invisible. ++ ++@findex hide-body ++@findex show-all ++@kindex C-c C-t @r{(Outline mode)} ++@kindex C-c C-a @r{(Outline mode)} ++ Two commands have a blanket effect on the whole file. @kbd{C-c C-t} ++(@code{hide-body}) makes all body lines invisible, so that you see just ++the outline structure (as a special exception, it will not hide lines ++at the top of the file, preceding the first header line, even though ++these are technically body lines). @kbd{C-c C-a} (@code{show-all}) ++makes all lines visible. These commands can be thought of as a pair ++of opposites even though @kbd{C-c C-a} applies to more than just body ++lines. ++ ++@findex hide-sublevels ++@kindex C-c C-q @r{(Outline mode)} ++ The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the ++top level headings. With a numeric argument @var{n}, it hides everything ++except the top @var{n} levels of heading lines. ++ ++@findex hide-other ++@kindex C-c C-o @r{(Outline mode)} ++ The command @kbd{C-c C-o} (@code{hide-other}) hides everything except ++the heading and body text that point is in, plus its parents (the headers ++leading up from there to top level in the outline) and the top level ++headings. ++ ++@findex reveal-mode ++ When incremental search finds text that is hidden by Outline mode, ++it makes that part of the buffer visible. If you exit the search ++at that position, the text remains visible. You can also ++automatically make text visible as you navigate in it by using ++@kbd{M-x reveal-mode}. ++ ++@node Outline Views ++@subsection Viewing One Outline in Multiple Views ++ ++@cindex multiple views of outline ++@cindex views of an outline ++@cindex outline with multiple views ++@cindex indirect buffers and outlines ++ You can display two views of a single outline at the same time, in ++different windows. To do this, you must create an indirect buffer using ++@kbd{M-x make-indirect-buffer}. The first argument of this command is ++the existing outline buffer name, and its second argument is the name to ++use for the new indirect buffer. @xref{Indirect Buffers}. ++ ++ Once the indirect buffer exists, you can display it in a window in the ++normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline ++mode commands to show and hide parts of the text operate on each buffer ++independently; as a result, each buffer can have its own view. If you ++want more than two views on the same outline, create additional indirect ++buffers. ++ ++@node Foldout ++@subsection Folding Editing ++ ++@cindex folding editing ++ The Foldout package extends Outline mode and Outline minor mode with ++``folding'' commands. The idea of folding is that you zoom in on a ++nested portion of the outline, while hiding its relatives at higher ++levels. ++ ++ Consider an Outline mode buffer with all the text and subheadings under ++level-1 headings hidden. To look at what is hidden under one of these ++headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose ++the body, or @kbd{C-c C-i} to expose the child (level-2) headings. ++ ++@kindex C-c C-z ++@findex foldout-zoom-subtree ++ With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}). ++This exposes the body and child subheadings, and narrows the buffer so ++that only the @w{level-1} heading, the body and the level-2 headings are ++visible. Now to look under one of the level-2 headings, position the ++cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body ++and its level-3 child subheadings and narrows the buffer again. Zooming ++in on successive subheadings can be done as much as you like. A string ++in the mode line shows how deep you've gone. ++ ++ When zooming in on a heading, to see only the child subheadings specify ++a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children ++can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2 ++C-c C-z} exposes two levels of child subheadings. Alternatively, the ++body can be specified with a negative argument: @kbd{M-- C-c C-z}. The ++whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x ++show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}. ++ ++ While you're zoomed in, you can still use Outline mode's exposure and ++hiding functions without disturbing Foldout. Also, since the buffer is ++narrowed, ``global'' editing actions will only affect text under the ++zoomed-in heading. This is useful for restricting changes to a ++particular chapter or section of your document. ++ ++@kindex C-c C-x ++@findex foldout-exit-fold ++ To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}). ++This hides all the text and subheadings under the top-level heading and ++returns you to the previous view of the buffer. Specifying a numeric ++argument exits that many levels of folds. Specifying a zero argument ++exits all folds. ++ ++ To cancel the narrowing of a fold without hiding the text and ++subheadings, specify a negative argument. For example, @kbd{M--2 C-c ++C-x} exits two folds and leaves the text and subheadings exposed. ++ ++ Foldout mode also provides mouse commands for entering and exiting ++folds, and for showing and hiding text: ++ ++@table @asis ++@item @kbd{C-M-Mouse-1} zooms in on the heading clicked on ++@itemize @w{} ++@item ++single click: expose body. ++@item ++double click: expose subheadings. ++@item ++triple click: expose body and subheadings. ++@item ++quad click: expose entire subtree. ++@end itemize ++@item @kbd{C-M-Mouse-2} exposes text under the heading clicked on ++@itemize @w{} ++@item ++single click: expose body. ++@item ++double click: expose subheadings. ++@item ++triple click: expose body and subheadings. ++@item ++quad click: expose entire subtree. ++@end itemize ++@item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold ++@itemize @w{} ++@item ++single click: hide subtree. ++@item ++double click: exit fold and hide text. ++@item ++triple click: exit fold without hiding text. ++@item ++quad click: exit all folds and hide text. ++@end itemize ++@end table ++ ++@vindex foldout-mouse-modifiers ++ You can specify different modifier keys (instead of ++@kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if ++you have already loaded the @file{foldout.el} library, you must reload ++it in order for this to take effect. ++ ++ To use the Foldout package, you can type @kbd{M-x load-library ++@key{RET} foldout @key{RET}}; or you can arrange for to do that ++automatically by putting this in your @file{.emacs} file: ++ ++@example ++(eval-after-load "outline" '(require 'foldout)) ++@end example ++ ++@node TeX Mode ++@section @TeX{} Mode ++@cindex @TeX{} mode ++@cindex La@TeX{} mode ++@cindex Sli@TeX{} mode ++@cindex Doc@TeX{} mode ++@cindex mode, @TeX{} ++@cindex mode, La@TeX{} ++@cindex mode, Sli@TeX{} ++@cindex mode, Doc@TeX{} ++@findex tex-mode ++@findex plain-tex-mode ++@findex latex-mode ++@findex slitex-mode ++@findex doctex-mode ++@findex bibtex-mode ++ ++ Emacs provides special major modes for editing files written in ++@TeX{} and its related formats. @TeX{} is a powerful text formatter ++written by Donald Knuth; like GNU Emacs, it is free software. ++La@TeX{} is a simplified input format for @TeX{}, implemented using ++@TeX{} macros. Doc@TeX{} is a special file format in which the ++La@TeX{} sources are written, combining sources with documentation. ++Sli@TeX{} is an obsolete special form of La@TeX{}.@footnote{It has ++been replaced by the @samp{slides} document class, which comes with ++La@TeX{}.} ++ ++@vindex tex-default-mode ++ @TeX{} mode has four variants: Plain @TeX{} mode, La@TeX{} mode, ++Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ ++only slightly, and are designed for editing the four different ++formats. Emacs selects the appropriate mode by looking at the ++contents of the buffer. (This is done by the @code{tex-mode} command, ++which is normally called automatically when you visit a @TeX{}-like ++file. @xref{Choosing Modes}.) If the contents are insufficient to ++determine this, Emacs chooses the mode specified by the variable ++@code{tex-default-mode}; its default value is @code{latex-mode}. If ++Emacs does not guess right, you can select the correct variant of ++@TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x ++latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}. ++ ++ Emacs also provides Bib@TeX{} mode, a major mode for editing ++Bib@TeX{} files. Bib@TeX{} is a tool for storing and formatting ++bibliographic references, which is commonly used together with ++La@TeX{}. In addition, the Ref@TeX{} package provides a minor mode ++which can be used in conjunction with La@TeX{} mode to manage ++bibliographic references. @inforef{Top,, reftex}. ++ ++@menu ++* Editing: TeX Editing. Special commands for editing in TeX mode. ++* LaTeX: LaTeX Editing. Additional commands for LaTeX input files. ++* Printing: TeX Print. Commands for printing part of a file with TeX. ++* Misc: TeX Misc. Customization of TeX mode, and related features. ++@end menu ++ ++@node TeX Editing ++@subsection @TeX{} Editing Commands ++ ++@table @kbd ++@item " ++Insert, according to context, either @samp{``} or @samp{"} or ++@samp{''} (@code{tex-insert-quote}). ++@item C-j ++Insert a paragraph break (two newlines) and check the previous ++paragraph for unbalanced braces or dollar signs ++(@code{tex-terminate-paragraph}). ++@item M-x tex-validate-region ++Check each paragraph in the region for unbalanced braces or dollar signs. ++@item C-c @{ ++Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}). ++@item C-c @} ++Move forward past the next unmatched close brace (@code{up-list}). ++@end table ++ ++@findex tex-insert-quote ++@kindex " @r{(@TeX{} mode)} ++ In @TeX{}, the character @samp{"} is not normally used; instead, ++quotations begin with @samp{``} and end with @samp{''}. For ++convenience, @TeX{} mode overrides the normal meaning of the key ++@kbd{"} with a command that inserts a pair of single-quotes or ++backquotes (@code{tex-insert-quote}). To be precise, it inserts ++@samp{``} after whitespace or an open brace, @samp{"} after a ++backslash, and @samp{''} after any other character. ++ ++ As a special exception, if you type @kbd{"} when the text before ++point is either @samp{``} or @samp{''}, Emacs replaces that preceding ++text with a single @samp{"} character. You can therefore type ++@kbd{""} to insert @samp{"}, should you ever need to do so. (You can ++also use @kbd{C-q "} to insert this character.) ++ ++ To disable the @kbd{"} expansion feature, eliminate that binding in ++the local map (@pxref{Key Bindings}). ++ ++ In @TeX{} mode, @samp{$} has a special syntax code which attempts to ++understand the way @TeX{} math mode delimiters match. When you insert a ++@samp{$} that is meant to exit math mode, the position of the matching ++@samp{$} that entered math mode is displayed for a second. This is the ++same feature that displays the open brace that matches a close brace that ++is inserted. However, there is no way to tell whether a @samp{$} enters ++math mode or leaves it; so when you insert a @samp{$} that enters math ++mode, the previous @samp{$} position is shown as if it were a match, even ++though they are actually unrelated. ++ ++@findex tex-insert-braces ++@kindex C-c @{ @r{(@TeX{} mode)} ++@findex up-list ++@kindex C-c @} @r{(@TeX{} mode)} ++ @TeX{} uses braces as delimiters that must match. Some users prefer ++to keep braces balanced at all times, rather than inserting them ++singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of ++braces. It leaves point between the two braces so you can insert the ++text that belongs inside. Afterward, use the command @kbd{C-c @}} ++(@code{up-list}) to move forward past the close brace. ++ ++@findex tex-validate-region ++@findex tex-terminate-paragraph ++@kindex C-j @r{(@TeX{} mode)} ++ There are two commands for checking the matching of braces. @kbd{C-j} ++(@code{tex-terminate-paragraph}) checks the paragraph before point, and ++inserts two newlines to start a new paragraph. It outputs a message in ++the echo area if any mismatch is found. @kbd{M-x tex-validate-region} ++checks a region, paragraph by paragraph. The errors are listed in the ++@samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in ++that buffer to go to a particular mismatch. ++ ++ Note that Emacs commands count square brackets and parentheses in ++@TeX{} mode, not just braces. This is not strictly correct for the ++purpose of checking @TeX{} syntax. However, parentheses and square ++brackets are likely to be used in text as matching delimiters, and it ++is useful for the various motion commands and automatic match display ++to work with them. ++ ++@node LaTeX Editing ++@subsection La@TeX{} Editing Commands ++ ++ La@TeX{} mode (and its obsolete variant, Sli@TeX{} mode) provide a ++few extra features not applicable to plain @TeX{}: ++ ++@table @kbd ++@item C-c C-o ++Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position ++point on a line between them (@code{tex-latex-block}). ++@item C-c C-e ++Close the innermost La@TeX{} block not yet closed ++(@code{tex-close-latex-block}). ++@end table ++ ++@findex tex-latex-block ++@kindex C-c C-o @r{(La@TeX{} mode)} ++@vindex latex-block-names ++ In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to ++group blocks of text. To insert a @samp{\begin} and a matching ++@samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c ++C-o} (@code{tex-latex-block}). A blank line is inserted between the ++two, and point is left there. You can use completion when you enter the ++block type; to specify additional block type names beyond the standard ++list, set the variable @code{latex-block-names}. For example, here's ++how to add @samp{theorem}, @samp{corollary}, and @samp{proof}: ++ ++@example ++(setq latex-block-names '("theorem" "corollary" "proof")) ++@end example ++ ++@findex tex-close-latex-block ++@kindex C-c C-e @r{(La@TeX{} mode)} ++ In La@TeX{} input, @samp{\begin} and @samp{\end} commands must ++balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to ++insert automatically a matching @samp{\end} to match the last unmatched ++@samp{\begin}. It indents the @samp{\end} to match the corresponding ++@samp{\begin}. It inserts a newline after @samp{\end} if point is at ++the beginning of a line. ++ ++@node TeX Print ++@subsection @TeX{} Printing Commands ++ ++ You can invoke @TeX{} as an inferior of Emacs on either the entire ++contents of the buffer or just a region at a time. Running @TeX{} in ++this way on just one chapter is a good way to see what your changes ++look like without taking the time to format the entire file. ++ ++@table @kbd ++@item C-c C-r ++Invoke @TeX{} on the current region, together with the buffer's header ++(@code{tex-region}). ++@item C-c C-b ++Invoke @TeX{} on the entire current buffer (@code{tex-buffer}). ++@item C-c @key{TAB} ++Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}). ++@item C-c C-f ++Invoke @TeX{} on the current file (@code{tex-file}). ++@item C-c C-l ++Recenter the window showing output from the inferior @TeX{} so that ++the last line can be seen (@code{tex-recenter-output-buffer}). ++@item C-c C-k ++Kill the @TeX{} subprocess (@code{tex-kill-job}). ++@item C-c C-p ++Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c ++C-f} command (@code{tex-print}). ++@item C-c C-v ++Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c ++C-f} command (@code{tex-view}). ++@item C-c C-q ++Show the printer queue (@code{tex-show-print-queue}). ++@item C-c C-c ++Invoke some other compilation command on the entire current buffer ++(@code{tex-compile}). ++@end table ++ ++@findex tex-buffer ++@kindex C-c C-b @r{(@TeX{} mode)} ++@findex tex-print ++@kindex C-c C-p @r{(@TeX{} mode)} ++@findex tex-view ++@kindex C-c C-v @r{(@TeX{} mode)} ++@findex tex-show-print-queue ++@kindex C-c C-q @r{(@TeX{} mode)} ++ You can pass the current buffer through an inferior @TeX{} by means of ++@kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a ++temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}). ++Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to ++view the progress of your output towards being printed. If your terminal ++has the ability to display @TeX{} output files, you can preview the ++output on the terminal with @kbd{C-c C-v} (@code{tex-view}). ++ ++@cindex @env{TEXINPUTS} environment variable ++@vindex tex-directory ++ You can specify the directory to use for running @TeX{} by setting the ++variable @code{tex-directory}. @code{"."} is the default value. If ++your environment variable @env{TEXINPUTS} contains relative directory ++names, or if your files contains @samp{\input} commands with relative ++file names, then @code{tex-directory} @emph{must} be @code{"."} or you ++will get the wrong results. Otherwise, it is safe to specify some other ++directory, such as @code{"/tmp"}. ++ ++@vindex tex-run-command ++@vindex latex-run-command ++@vindex slitex-run-command ++@vindex tex-dvi-print-command ++@vindex tex-dvi-view-command ++@vindex tex-show-queue-command ++ If you want to specify which shell commands are used in the inferior @TeX{}, ++you can do so by setting the values of the variables @code{tex-run-command}, ++@code{latex-run-command}, @code{slitex-run-command}, ++@code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and ++@code{tex-show-queue-command}. The default values may ++(or may not) be appropriate for your system. ++ ++ Normally, the file name given to these commands comes at the end of ++the command string; for example, @samp{latex @var{filename}}. In some ++cases, however, the file name needs to be embedded in the command; an ++example is when you need to provide the file name as an argument to one ++command whose output is piped to another. You can specify where to put ++the file name with @samp{*} in the command string. For example, ++ ++@example ++(setq tex-dvi-print-command "dvips -f * | lpr") ++@end example ++ ++@findex tex-kill-job ++@kindex C-c C-k @r{(@TeX{} mode)} ++@findex tex-recenter-output-buffer ++@kindex C-c C-l @r{(@TeX{} mode)} ++ The terminal output from @TeX{}, including any error messages, appears ++in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can ++switch to this buffer and feed it input (this works as in Shell mode; ++@pxref{Interactive Shell}). Without switching to this buffer you can ++scroll it so that its last line is visible by typing @kbd{C-c ++C-l}. ++ ++ Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if ++you see that its output is no longer useful. Using @kbd{C-c C-b} or ++@kbd{C-c C-r} also kills any @TeX{} process still running. ++ ++@findex tex-region ++@kindex C-c C-r @r{(@TeX{} mode)} ++ You can also pass an arbitrary region through an inferior @TeX{} by typing ++@kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because most files ++of @TeX{} input contain commands at the beginning to set parameters and ++define macros, without which no later part of the file will format ++correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a ++part of the file as containing essential commands; it is included before ++the specified region as part of the input to @TeX{}. The designated part ++of the file is called the @dfn{header}. ++ ++@cindex header (@TeX{} mode) ++ To indicate the bounds of the header in Plain @TeX{} mode, you insert two ++special strings in the file. Insert @samp{%**start of header} before the ++header, and @samp{%**end of header} after it. Each string must appear ++entirely on one line, but there may be other text on the line before or ++after. The lines containing the two strings are included in the header. ++If @samp{%**start of header} does not appear within the first 100 lines of ++the buffer, @kbd{C-c C-r} assumes that there is no header. ++ ++ In La@TeX{} mode, the header begins with @samp{\documentclass} or ++@samp{\documentstyle} and ends with @samp{\begin@{document@}}. These ++are commands that La@TeX{} requires you to use in any case, so nothing ++special needs to be done to identify the header. ++ ++@findex tex-file ++@kindex C-c C-f @r{(@TeX{} mode)} ++ The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their ++work in a temporary directory, and do not have available any of the auxiliary ++files needed by @TeX{} for cross-references; these commands are generally ++not suitable for running the final copy in which all of the cross-references ++need to be correct. ++ ++ When you want the auxiliary files for cross references, use @kbd{C-c ++C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file, ++in that file's directory. Before running @TeX{}, it offers to save any ++modified buffers. Generally, you need to use (@code{tex-file}) twice to ++get the cross-references right. ++ ++@vindex tex-start-options ++ The value of the variable @code{tex-start-options} specifies ++options for the @TeX{} run. ++ ++@vindex tex-start-commands ++ The value of the variable @code{tex-start-commands} specifies @TeX{} ++commands for starting @TeX{}. The default value causes @TeX{} to run ++in nonstop mode. To run @TeX{} interactively, set the variable to ++@code{""}. ++ ++@vindex tex-main-file ++ Large @TeX{} documents are often split into several files---one main ++file, plus subfiles. Running @TeX{} on a subfile typically does not ++work; you have to run it on the main file. In order to make ++@code{tex-file} useful when you are editing a subfile, you can set the ++variable @code{tex-main-file} to the name of the main file. Then ++@code{tex-file} runs @TeX{} on that file. ++ ++ The most convenient way to use @code{tex-main-file} is to specify it ++in a local variable list in each of the subfiles. @xref{File ++Variables}. ++ ++@findex tex-bibtex-file ++@kindex C-c TAB @r{(@TeX{} mode)} ++@vindex tex-bibtex-command ++ For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary ++file for the current buffer's file. Bib@TeX{} looks up bibliographic ++citations in a data base and prepares the cited references for the ++bibliography section. The command @kbd{C-c @key{TAB}} ++(@code{tex-bibtex-file}) runs the shell command ++(@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the ++current buffer's file. Generally, you need to do @kbd{C-c C-f} ++(@code{tex-file}) once to generate the @samp{.aux} file, then do ++@kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f} ++(@code{tex-file}) twice more to get the cross-references correct. ++ ++@findex tex-compile ++@kindex C-c C-c @r{(@TeX{} mode)} ++ To invoke some other compilation program on the current @TeX{} ++buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows ++how to pass arguments to many common programs, including ++@file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can ++select your desired compilation program using the standard completion ++keys (@pxref{Completion}). ++ ++@node TeX Misc ++@subsection @TeX{} Mode Miscellany ++ ++@vindex tex-shell-hook ++@vindex tex-mode-hook ++@vindex latex-mode-hook ++@vindex slitex-mode-hook ++@vindex plain-tex-mode-hook ++ Entering any variant of @TeX{} mode runs the hooks ++@code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either ++@code{plain-tex-mode-hook}, @code{latex-mode-hook}, or ++@code{slitex-mode-hook}, whichever is appropriate. Starting the ++@TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}. ++ ++@findex iso-iso2tex ++@findex iso-tex2iso ++@findex iso-iso2gtex ++@findex iso-gtex2iso ++@cindex Latin-1 @TeX{} encoding ++@cindex @TeX{} encoding ++ The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x ++iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert ++between Latin-1 encoded files and @TeX{}-encoded equivalents. ++@ignore ++@c Too cryptic to be useful, too cryptic for me to make it better -- rms. ++ They ++are included by default in the @code{format-alist} variable, so they ++can be used with @kbd{M-x format-find-file}, for instance. ++@end ignore ++ ++@ignore @c Not worth documenting if it is only for Czech -- rms. ++@findex tildify-buffer ++@findex tildify-region ++@cindex ties, @TeX{}, inserting ++@cindex hard spaces, @TeX{}, inserting ++ The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region} ++insert @samp{~} (@dfn{tie}) characters where they are conventionally ++required. This is set up for Czech---customize the group ++@samp{tildify} for other languages or for other sorts of markup. ++@end ignore ++ ++@cindex Ref@TeX{} package ++@cindex references, La@TeX{} ++@cindex La@TeX{} references ++ For managing all kinds of references for La@TeX{}, you can use ++Ref@TeX{}. @inforef{Top,, reftex}. ++ ++@node HTML Mode ++@section SGML, XML, and HTML Modes ++@cindex SGML mode ++@cindex HTML mode ++@cindex XML mode ++@cindex mode, SGML ++@cindex mode, HTML ++@cindex mode, XML ++@findex sgml-mode ++@findex html-mode ++@findex xml-mode ++ ++ The major modes for SGML, XML, and HTML provide indentation support ++and commands for operating on tags. XML mode is actually identical to ++SGML mode (to be precise, @code{xml-mode} is an alias for ++@code{sgml-mode}), because XML is a strict subset of SGML. HTML mode ++is a slightly customized variant of SGML mode. ++ ++@vindex sgml-xml-mode ++ In XML, every opening tag must have an explicit closing tag. When ++the variable @code{sgml-xml-mode} is non-@code{nil}, the tag insertion ++commands described below always insert explicit closing tags as well. ++When you visit a file, Emacs determines whether it is XML by examining ++the file contents, and sets @code{sgml-xml-mode} accordingly. ++ ++@table @kbd ++@item C-c C-n ++@kindex C-c C-n @r{(SGML mode)} ++@findex sgml-name-char ++Interactively specify a special character and insert the SGML ++@samp{&}-command for that character. ++ ++@item C-c C-t ++@kindex C-c C-t @r{(SGML mode)} ++@findex sgml-tag ++Interactively specify a tag and its attributes (@code{sgml-tag}). ++This command asks you for a tag name and for the attribute values, ++then inserts both the opening tag and the closing tag, leaving point ++between them. ++ ++With a prefix argument @var{n}, the command puts the tag around the ++@var{n} words already present in the buffer after point. Whenever a ++region is active, it puts the tag around the region (when Transient ++Mark mode is off, it does this when a numeric argument of @minus{}1 is ++supplied.) ++ ++@item C-c C-a ++@kindex C-c C-a @r{(SGML mode)} ++@findex sgml-attributes ++Interactively insert attribute values for the current tag ++(@code{sgml-attributes}). ++ ++@item C-c C-f ++@kindex C-c C-f @r{(SGML mode)} ++@findex sgml-skip-tag-forward ++Skip across a balanced tag group (which extends from an opening tag ++through its corresponding closing tag) (@code{sgml-skip-tag-forward}). ++A numeric argument acts as a repeat count. ++ ++@item C-c C-b ++@kindex C-c C-b @r{(SGML mode)} ++@findex sgml-skip-tag-backward ++Skip backward across a balanced tag group (which extends from an ++opening tag through its corresponding closing tag) ++(@code{sgml-skip-tag-forward}). A numeric argument acts as a repeat ++count. ++ ++@item C-c C-d ++@kindex C-c C-d @r{(SGML mode)} ++@findex sgml-delete-tag ++Delete the tag at or after point, and delete the matching tag too ++(@code{sgml-delete-tag}). If the tag at or after point is an opening ++tag, delete the closing tag too; if it is a closing tag, delete the ++opening tag too. ++ ++@item C-c ? @var{tag} @key{RET} ++@kindex C-c ? @r{(SGML mode)} ++@findex sgml-tag-help ++Display a description of the meaning of tag @var{tag} ++(@code{sgml-tag-help}). If the argument @var{tag} is empty, describe ++the tag at point. ++ ++@item C-c / ++@kindex C-c / @r{(SGML mode)} ++@findex sgml-close-tag ++Insert a close tag for the innermost unterminated tag ++(@code{sgml-close-tag}). If called from within a tag or a comment, ++close this element instead of inserting a close tag. ++ ++@item C-c 8 ++@kindex C-c 8 @r{(SGML mode)} ++@findex sgml-name-8bit-mode ++Toggle a minor mode in which Latin-1 characters insert the ++corresponding SGML commands that stand for them, instead of the ++characters themselves (@code{sgml-name-8bit-mode}). ++ ++@item C-c C-v ++@kindex C-c C-v @r{(SGML mode)} ++@findex sgml-validate ++Run a shell command (which you must specify) to validate the current ++buffer as SGML (@code{sgml-validate}). ++ ++@item C-c TAB ++@kindex C-c TAB @r{(SGML mode)} ++@findex sgml-tags-invisible ++Toggle the visibility of existing tags in the buffer. This can be ++used as a cheap preview. ++@end table ++ ++@cindex nXML mode ++@cindex mode, nXML ++@findex nxml-mode ++@cindex XML schema ++ Emacs also provides a more advanced mode for editing XML ++documents, called nXML mode (@code{nxml-mode}). nXML mode is aware of ++many existing XML schema, and uses them to provide completion of XML ++elements via @kbd{C-@key{RET}} or @kbd{M-@key{TAB}}, as well as ++``on-the-fly'' validation of XML, with errors highlighted via Font ++Lock (@pxref{Font Lock}). It is described in its own manual. ++@xref{Top, nXML Mode,,nxml-mode, nXML Mode}. ++ ++@node Nroff Mode ++@section Nroff Mode ++ ++@cindex nroff ++@findex nroff-mode ++ Nroff mode is a mode like Text mode but modified to handle nroff commands ++present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It ++differs from Text mode in only a few ways. All nroff command lines are ++considered paragraph separators, so that filling will never garble the ++nroff commands. Pages are separated by @samp{.bp} commands. Comments ++start with backslash-doublequote. Also, three special commands are ++provided that are not in Text mode: ++ ++@findex forward-text-line ++@findex backward-text-line ++@findex count-text-lines ++@kindex M-n @r{(Nroff mode)} ++@kindex M-p @r{(Nroff mode)} ++@kindex M-? @r{(Nroff mode)} ++@table @kbd ++@item M-n ++Move to the beginning of the next line that isn't an nroff command ++(@code{forward-text-line}). An argument is a repeat count. ++@item M-p ++Like @kbd{M-n} but move up (@code{backward-text-line}). ++@item M-? ++Displays in the echo area the number of text lines (lines that are not ++nroff commands) in the region (@code{count-text-lines}). ++@end table ++ ++@findex electric-nroff-mode ++ The other feature of Nroff mode is that you can turn on Electric Nroff ++mode. This is a minor mode that you can turn on or off with @kbd{M-x ++electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each ++time you use @key{RET} to end a line that contains an nroff command that ++opens a kind of grouping, the matching nroff command to close that ++grouping is automatically inserted on the following line. For example, ++if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}}, ++this inserts the matching command @samp{.)b} on a new line following ++point. ++ ++ If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}), ++heading lines are lines of the form @samp{.H} followed by a number (the ++header level). ++ ++@vindex nroff-mode-hook ++ Entering Nroff mode runs the hook @code{text-mode-hook}, followed by ++the hook @code{nroff-mode-hook} (@pxref{Hooks}). ++ ++@node Formatted Text ++@section Editing Formatted Text ++ ++@cindex Enriched mode ++@cindex mode, Enriched ++@cindex formatted text ++@cindex WYSIWYG ++@cindex word processing ++ @dfn{Enriched mode} is a minor mode for editing files that contain ++formatted text in WYSIWYG fashion, as in a word processor. Currently, ++formatted text in Enriched mode can specify fonts, colors, underlining, ++margins, and types of filling and justification. In the future, we plan ++to implement other formatting features as well. ++ ++ Enriched mode is a minor mode (@pxref{Minor Modes}). It is ++typically used in conjunction with Text mode (@pxref{Text Mode}), but ++you can also use it with other major modes such as Outline mode and ++Paragraph-Indent Text mode. ++ ++@cindex text/enriched MIME format ++ Potentially, Emacs can store formatted text files in various file ++formats. Currently, only one format is implemented: @dfn{text/enriched} ++format, which is defined by the MIME protocol. @xref{Format ++Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual}, ++for details of how Emacs recognizes and converts file formats. ++ ++ The Emacs distribution contains a formatted text file that can serve as ++an example. Its name is @file{etc/enriched.doc}. It contains samples ++illustrating all the features described in this section. It also ++contains a list of ideas for future enhancements. ++ ++@menu ++* Requesting Formatted Text:: Entering and exiting Enriched mode. ++* Hard and Soft Newlines:: There are two different kinds of newlines. ++* Editing Format Info:: How to edit text properties. ++* Faces: Format Faces. Bold, italic, underline, etc. ++* Color: Format Colors. Changing the color of text. ++* Indent: Format Indentation. Changing the left and right margins. ++* Justification: Format Justification. ++ Centering, setting text flush with the ++ left or right margin, etc. ++* Special: Format Properties. The "special" text properties submenu. ++* Forcing Enriched Mode:: How to force use of Enriched mode. ++@end menu ++ ++@node Requesting Formatted Text ++@subsection Requesting to Edit Formatted Text ++ ++ Whenever you visit a file that Emacs saved in the text/enriched ++format, Emacs automatically converts the formatting information in the ++file into Emacs's own internal format (known as @dfn{text ++properties}), and turns on Enriched mode. ++ ++@findex enriched-mode ++ To create a new file of formatted text, first visit the nonexistent ++file, then type @kbd{M-x enriched-mode} before you start inserting text. ++This command turns on Enriched mode. Do this before you begin inserting ++text, to ensure that the text you insert is handled properly. ++ ++ More generally, the command @code{enriched-mode} turns Enriched mode ++on if it was off, and off if it was on. With a prefix argument, this ++command turns Enriched mode on if the argument is positive, and turns ++the mode off otherwise. ++ ++ When you save a buffer while Enriched mode is enabled in it, Emacs ++automatically converts the text to text/enriched format while writing it ++into the file. When you visit the file again, Emacs will automatically ++recognize the format, reconvert the text, and turn on Enriched mode ++again. ++ ++@vindex enriched-translations ++ You can add annotations for saving additional text properties, which ++Emacs normally does not save, by adding to @code{enriched-translations}. ++Note that the text/enriched standard requires any non-standard ++annotations to have names starting with @samp{x-}, as in ++@samp{x-read-only}. This ensures that they will not conflict with ++standard annotations that may be added later. ++ ++ @xref{Text Properties,,, elisp, the Emacs Lisp Reference Manual}, ++for more information about text properties. ++ ++@node Hard and Soft Newlines ++@subsection Hard and Soft Newlines ++@cindex hard newline ++@cindex soft newline ++@cindex newlines, hard and soft ++ ++@cindex use-hard-newlines ++ In formatted text, Emacs distinguishes between two different kinds of ++newlines, @dfn{hard} newlines and @dfn{soft} newlines. (You can enable ++or disable this feature separately in any buffer with the command ++@code{use-hard-newlines}.) ++ ++ Hard newlines are used to separate paragraphs, or items in a list, or ++anywhere that there should always be a line break regardless of the ++margins. The @key{RET} command (@code{newline}) and @kbd{C-o} ++(@code{open-line}) insert hard newlines. ++ ++ Soft newlines are used to make text fit between the margins. All the ++fill commands, including Auto Fill, insert soft newlines---and they ++delete only soft newlines. ++ ++ Although hard and soft newlines look the same, it is important to bear ++the difference in mind. Do not use @key{RET} to break lines in the ++middle of filled paragraphs, or else you will get hard newlines that are ++barriers to further filling. Instead, let Auto Fill mode break lines, ++so that if the text or the margins change, Emacs can refill the lines ++properly. @xref{Auto Fill}. ++ ++ On the other hand, in tables and lists, where the lines should always ++remain as you type them, you can use @key{RET} to end lines. For these ++lines, you may also want to set the justification style to ++@code{unfilled}. @xref{Format Justification}. ++ ++@node Editing Format Info ++@subsection Editing Format Information ++ ++ There are two ways to alter the formatting information for a formatted ++text file: with keyboard commands, and with the mouse. ++ ++ The easiest way to add properties to your document is with the Text ++Properties menu. You can get to this menu in two ways: from the Edit ++menu in the menu bar (use @kbd{@key{F10} e t} if you have no mouse), ++or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle ++mouse button). There are also keyboard commands described in the ++following section. ++ ++ These items in the Text Properties menu run commands directly: ++ ++@table @code ++@findex facemenu-remove-face-props ++@item Remove Face Properties ++Delete from the region all face and color text properties ++(@code{facemenu-remove-face-props}). ++ ++@findex facemenu-remove-all ++@item Remove Text Properties ++Delete @emph{all} text properties from the region ++(@code{facemenu-remove-all}). ++ ++@findex describe-text-properties ++@cindex text properties of characters ++@cindex overlays at character position ++@cindex widgets at buffer position ++@cindex buttons at buffer position ++@item Describe Properties ++List all the text properties, widgets, buttons, and overlays of the ++character following point (@code{describe-text-properties}). ++ ++@item Display Faces ++Display a list of all the defined faces (@code{list-faces-display}). ++ ++@item Display Colors ++Display a list of all the defined colors (@code{list-colors-display}). ++@end table ++ ++@ifinfo ++ Other items in the Text Properties menu lead to submenus: ++ ++@menu ++* Faces: Format Faces. Bold, italic, underline, etc. ++* Color: Format Colors. Changing the color of text. ++* Indent: Format Indentation. Changing the left and right margins. ++* Justification: Format Justification. ++ Centering, setting text flush with the ++ left or right margin, etc. ++* Special: Format Properties. The "special" text properties submenu. ++@end menu ++@end ifinfo ++@ifnotinfo ++ The rest lead to submenus which are described in the following sections. ++@end ifnotinfo ++ ++@node Format Faces ++@subsection Faces in Formatted Text ++ ++ The Faces submenu under Text Properties lists various Emacs faces ++including @code{bold}, @code{italic}, and @code{underline} ++(@pxref{Faces}). These menu items operate on the region if it is ++active and nonempty. Otherwise, they specify to use that face for an ++immediately following self-inserting character. There is also an item ++@samp{Other} with which you can enter a face name through the ++minibuffer (@pxref{Standard Faces}). ++ ++ Instead of the Faces submenu, you can use these keyboard commands: ++ ++@table @kbd ++@kindex M-o d @r{(Enriched mode)} ++@findex facemenu-set-default ++@item M-o d ++Remove all @code{face} properties from the region (which includes ++specified colors), or force the following inserted character to have no ++@code{face} property (@code{facemenu-set-default}). ++@kindex M-o b @r{(Enriched mode)} ++@findex facemenu-set-bold ++@item M-o b ++Add the face @code{bold} to the region or to the following inserted ++character (@code{facemenu-set-bold}). ++@kindex M-o i @r{(Enriched mode)} ++@findex facemenu-set-italic ++@item M-o i ++Add the face @code{italic} to the region or to the following inserted ++character (@code{facemenu-set-italic}). ++@kindex M-o l @r{(Enriched mode)} ++@findex facemenu-set-bold-italic ++@item M-o l ++Add the face @code{bold-italic} to the region or to the following ++inserted character (@code{facemenu-set-bold-italic}). ++@kindex M-o u @r{(Enriched mode)} ++@findex facemenu-set-underline ++@item M-o u ++Add the face @code{underline} to the region or to the following inserted ++character (@code{facemenu-set-underline}). ++@kindex M-o o @r{(Enriched mode)} ++@findex facemenu-set-face ++@item M-o o @var{face} @key{RET} ++Add the face @var{face} to the region or to the following inserted ++character (@code{facemenu-set-face}). ++@end table ++ ++ With a prefix argument, all these commands apply to an immediately ++following self-inserting character, disregarding the region. ++ ++ A self-inserting character normally inherits the @code{face} ++property (and most other text properties) from the preceding character ++in the buffer. If you use the above commands to specify face for the ++next self-inserting character, or the next section's commands to ++specify a foreground or background color for it, then it does not ++inherit the @code{face} property from the preceding character; instead ++it uses whatever you specified. It will still inherit other text ++properties, though. ++ ++ Strictly speaking, these commands apply only to the first following ++self-inserting character that you type. But if you insert additional ++characters after it, they will inherit from the first one. So it ++appears that these commands apply to all of them. ++ ++ Enriched mode defines two additional faces: @code{excerpt} and ++@code{fixed}. These correspond to codes used in the text/enriched file ++format. ++ ++ The @code{excerpt} face is intended for quotations. This face is the ++same as @code{italic} unless you customize it (@pxref{Face Customization}). ++ ++ The @code{fixed} face means, ``Use a fixed-width font for this part ++of the text.'' Applying the @code{fixed} face to a part of the text ++will cause that part of the text to appear in a fixed-width font, even ++if the default font is variable-width. This applies to Emacs and to ++other systems that display text/enriched format. So if you ++specifically want a certain part of the text to use a fixed-width ++font, you should specify the @code{fixed} face for that part. ++ ++ By default, the @code{fixed} face looks the same as @code{bold}. ++This is an attempt to distinguish it from @code{default}. You may ++wish to customize @code{fixed} to some other fixed-width medium font. ++@xref{Face Customization}. ++ ++ If your terminal cannot display different faces, you will not be ++able to see them, but you can still edit documents containing faces, ++and even add faces and colors to documents. The faces you specify ++will be visible when the file is viewed on a terminal that can display ++them. ++ ++@node Format Colors ++@subsection Colors in Formatted Text ++ ++ You can specify foreground and background colors for portions of the ++text. Under Text Properties, there is a submenu for specifying the ++foreground color, and a submenu for specifying the background color. ++Each one lists all the colors that you have used in Enriched mode in ++the current Emacs session. ++ ++ If the region is active, the command applies to the text in the ++region; otherwise, it applies to any immediately following ++self-inserting input. When Transient Mark mode is off ++(@pxref{Persistent Mark}), it always applies to the region unless a ++prefix argument is given, in which case it applies to the following ++input. ++ ++ Each of the two color submenus contains one additional item: ++@samp{Other}. You can use this item to specify a color that is not ++listed in the menu; it reads the color name with the minibuffer. To ++display a list of available colors and their names, use the ++@samp{Display Colors} menu item in the Text Properties menu ++(@pxref{Editing Format Info}). ++ ++ Any color that you specify in this way, or that is mentioned in a ++formatted text file that you read in, is added to the corresponding ++color menu for the duration of the Emacs session. ++ ++@findex facemenu-set-foreground ++@findex facemenu-set-background ++ There are no predefined key bindings for specifying colors, but you can do so ++with the extended commands @kbd{M-x facemenu-set-foreground} and ++@kbd{M-x facemenu-set-background}. Both of these commands read the name ++of the color with the minibuffer. ++ ++@node Format Indentation ++@subsection Indentation in Formatted Text ++ ++ When editing formatted text, you can specify different amounts of ++indentation for the right or left margin of an entire paragraph or a ++part of a paragraph. The margins you specify automatically affect the ++Emacs fill commands (@pxref{Filling}) and line-breaking commands. ++ ++ The Indentation submenu of Text Properties provides a convenient ++interface for specifying these properties. The submenu contains four ++items: ++ ++@table @code ++@kindex C-x TAB @r{(Enriched mode)} ++@findex increase-left-margin ++@item Indent More ++Indent the region by 4 columns (@code{increase-left-margin}). In ++Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if ++you supply a numeric argument, that says how many columns to add to the ++margin (a negative argument reduces the number of columns). ++ ++@item Indent Less ++Remove 4 columns of indentation from the region. ++ ++@item Indent Right More ++Make the text narrower by indenting 4 columns at the right margin. ++ ++@item Indent Right Less ++Remove 4 columns of indentation from the right margin. ++@end table ++ ++ You can use these commands repeatedly to increase or decrease the ++indentation. ++ ++ The most common way to use them is to change the indentation of an ++entire paragraph. For other uses, the effects of refilling can be ++hard to predict, except in some special cases like the one described ++next. ++ ++ The most common other use is to format paragraphs with @dfn{hanging ++indents}, which means that the first line is indented less than ++subsequent lines. To set up a hanging indent, increase the ++indentation of the region starting after the first word of the ++paragraph and running until the end of the paragraph. ++ ++ Indenting the first line of a paragraph is easier. Set the margin for ++the whole paragraph where you want it to be for the body of the ++paragraph, then indent the first line by inserting extra spaces or tabs. ++ ++@vindex standard-indent ++ The variable @code{standard-indent} specifies how many columns these ++commands should add to or subtract from the indentation. The default ++value is 4. The overall default right margin for Enriched mode is ++controlled by the variable @code{fill-column}, as usual. ++ ++@kindex C-c [ @r{(Enriched mode)} ++@kindex C-c ] @r{(Enriched mode)} ++@findex set-left-margin ++@findex set-right-margin ++ There are also two commands for setting the left or right margin of ++the region absolutely: @code{set-left-margin} and ++@code{set-right-margin}. Enriched mode binds these commands to ++@kbd{C-c [} and @kbd{C-c ]}, respectively. You can specify the ++margin width either with a numeric argument or in the minibuffer. ++ ++ Sometimes, as a result of editing, the filling of a paragraph becomes ++messed up---parts of the paragraph may extend past the left or right ++margins. When this happens, use @kbd{M-q} (@code{fill-paragraph}) to ++refill the paragraph. ++ ++ The fill prefix, if any, works in addition to the specified paragraph ++indentation: @kbd{C-x .} does not include the specified indentation's ++whitespace in the new value for the fill prefix, and the fill commands ++look for the fill prefix after the indentation on each line. @xref{Fill ++Prefix}. ++ ++@node Format Justification ++@subsection Justification in Formatted Text ++ ++ When editing formatted text, you can specify various styles of ++justification for a paragraph. The style you specify automatically ++affects the Emacs fill commands. ++ ++ The Justification submenu of Text Properties provides a convenient ++interface for specifying the style. The submenu contains five items: ++ ++@table @code ++@item Left ++This is the most common style of justification (at least for English). ++Lines are aligned at the left margin but left uneven at the right. ++ ++@item Right ++This aligns each line with the right margin. Spaces and tabs are added ++on the left, if necessary, to make lines line up on the right. ++ ++@item Full ++This justifies the text, aligning both edges of each line. Justified ++text looks very nice in a printed book, where the spaces can all be ++adjusted equally, but it does not look as nice with a fixed-width font ++on the screen. Perhaps a future version of Emacs will be able to adjust ++the width of spaces in a line to achieve elegant justification. ++ ++@item Center ++This centers every line between the current margins. ++ ++@item Unfilled ++This turns off filling entirely. Each line will remain as you wrote it; ++the fill and auto-fill functions will have no effect on text which has ++this setting. You can, however, still indent the left margin. In ++unfilled regions, all newlines are treated as hard newlines (@pxref{Hard ++and Soft Newlines}) . ++@end table ++ ++ In Enriched mode, you can also specify justification from the keyboard ++using the @kbd{M-j} prefix character: ++ ++@table @kbd ++@kindex M-j l @r{(Enriched mode)} ++@findex set-justification-left ++@item M-j l ++Make the region left-filled (@code{set-justification-left}). ++@kindex M-j r @r{(Enriched mode)} ++@findex set-justification-right ++@item M-j r ++Make the region right-filled (@code{set-justification-right}). ++@kindex M-j b @r{(Enriched mode)} ++@findex set-justification-full ++@item M-j b ++Make the region fully justified (@code{set-justification-full}). ++@kindex M-j c @r{(Enriched mode)} ++@kindex M-S @r{(Enriched mode)} ++@findex set-justification-center ++@item M-j c ++@itemx M-S ++Make the region centered (@code{set-justification-center}). ++@kindex M-j u @r{(Enriched mode)} ++@findex set-justification-none ++@item M-j u ++Make the region unfilled (@code{set-justification-none}). ++@end table ++ ++ Justification styles apply to entire paragraphs. All the ++justification-changing commands operate on the paragraph containing ++point, or, if the region is active, on all paragraphs which overlap the ++region. ++ ++@vindex default-justification ++ The default justification style is specified by the variable ++@code{default-justification}. Its value should be one of the symbols ++@code{left}, @code{right}, @code{full}, @code{center}, or @code{none}. ++This is a per-buffer variable. Setting the variable directly affects ++only the current buffer. However, customizing it in a Custom buffer ++sets (as always) the default value for buffers that do not override it. ++@xref{Locals}, and @ref{Easy Customization}. ++ ++@node Format Properties ++@subsection Setting Other Text Properties ++ ++ The Special Properties submenu of Text Properties can add or remove ++three other useful text properties: @code{read-only}, @code{invisible} ++and @code{intangible}. The @code{intangible} property disallows ++moving point within the text, the @code{invisible} text property hides ++text from display, and the @code{read-only} property disallows ++alteration of the text. ++ ++ Each of these special properties has a menu item to add it to the ++region. The last menu item, @samp{Remove Special}, removes all of these ++special properties from the text in the region. ++ ++ Currently, the @code{invisible} and @code{intangible} properties are ++@emph{not} saved in the text/enriched format. The @code{read-only} ++property is saved, but it is not a standard part of the text/enriched ++format, so other editors may not respect it. ++ ++@node Forcing Enriched Mode ++@subsection Forcing Enriched Mode ++ ++ Normally, Emacs knows when you are editing formatted text because it ++recognizes the special annotations used in the file that you visited. ++However, sometimes you must take special actions to convert file ++contents or turn on Enriched mode: ++ ++@itemize @bullet ++@item ++When you visit a file that was created with some other editor, Emacs may ++not recognize the file as being in the text/enriched format. In this ++case, when you visit the file you will see the formatting commands ++rather than the formatted text. Type @kbd{M-x format-decode-buffer} to ++translate it. This also automatically turns on Enriched mode. ++ ++@item ++When you @emph{insert} a file into a buffer, rather than visiting it, ++Emacs does the necessary conversions on the text which you insert, but ++it does not enable Enriched mode. If you wish to do that, type @kbd{M-x ++enriched-mode}. ++@end itemize ++ ++ The command @code{format-decode-buffer} translates text in various ++formats into Emacs's internal format. It asks you to specify the format ++to translate from; however, normally you can type just @key{RET}, which ++tells Emacs to guess the format. ++ ++@findex format-find-file ++ If you wish to look at a text/enriched file in its raw form, as a ++sequence of characters rather than as formatted text, use the @kbd{M-x ++find-file-literally} command. This visits a file, like ++@code{find-file}, but does not do format conversion. It also inhibits ++character code conversion (@pxref{Coding Systems}) and automatic ++uncompression (@pxref{Compressed Files}). To disable format conversion ++but allow character code conversion and/or automatic uncompression if ++appropriate, use @code{format-find-file} with suitable arguments. ++ ++@node Text Based Tables ++@section Editing Text-based Tables ++@cindex table mode ++@cindex text-based tables ++ ++ Table mode provides an easy and intuitive way to create and edit WYSIWYG ++text-based tables. Here is an example of such a table: ++ ++@smallexample ++@group +++-----------------+--------------------------------+-----------------+ ++| Command | Description | Key Binding | +++-----------------+--------------------------------+-----------------+ ++| forward-char |Move point right N characters | C-f | ++| |(left if N is negative). | | ++| | | | ++| |On reaching end of buffer, stop | | ++| |and signal error. | | +++-----------------+--------------------------------+-----------------+ ++| backward-char |Move point left N characters | C-b | ++| |(right if N is negative). | | ++| | | | ++| |On attempt to pass beginning or | | ++| |end of buffer, stop and signal | | ++| |error. | | +++-----------------+--------------------------------+-----------------+ ++@end group ++@end smallexample ++ ++ Table mode allows the contents of the table such as this one to be ++easily manipulated by inserting or deleting characters inside a cell. ++A cell is effectively a localized rectangular edit region and edits to ++a cell do not affect the contents of the surrounding cells. If the ++contents do not fit into a cell, then the cell is automatically ++expanded in the vertical and/or horizontal directions and the rest of ++the table is restructured and reformatted in accordance with the ++growth of the cell. ++ ++@menu ++* Table Definition:: What is a text based table. ++* Table Creation:: How to create a table. ++* Table Recognition:: How to activate and deactivate tables. ++* Cell Commands:: Cell-oriented commands in a table. ++* Cell Justification:: Justifying cell contents. ++* Row Commands:: Manipulating rows of table cell. ++* Column Commands:: Manipulating columns of table cell. ++* Fixed Width Mode:: Fixing cell width. ++* Table Conversion:: Converting between plain text and tables. ++* Measuring Tables:: Analyzing table dimension. ++* Table Misc:: Table miscellany. ++@end menu ++ ++@node Table Definition ++@subsection What is a Text-based Table? ++ ++ Keep the following examples of valid tables in mind as a reference ++while you read this section: ++ ++@example ++ +--+----+---+ +-+ +--+-----+ ++ | | | | | | | | | ++ +--+----+---+ +-+ | +--+--+ ++ | | | | | | | | ++ +--+----+---+ +--+--+ | ++ | | | ++ +-----+--+ ++@end example ++ ++ A table consists of a rectangular frame whose inside is divided into ++cells. Each cell must be at least one character wide and one ++character high, not counting its border lines. A cell can be ++subdivided into multiple rectangular cells, but cells cannot overlap. ++ ++ The table frame and cell border lines are made of three special ++characters. These variables specify those characters: ++ ++@table @code ++@vindex table-cell-vertical-char ++@item table-cell-vertical-char ++Holds the character used for vertical lines. The default value is ++@samp{|}. ++ ++@vindex table-cell-horizontal-chars ++@item table-cell-horizontal-chars ++Holds the characters used for horizontal lines. The default value is ++@samp{"-="}. ++ ++@vindex table-cell-intersection-char ++@item table-cell-intersection-char ++Holds the character used at where horizontal line and vertical line ++meet. The default value is @samp{+}. ++@end table ++ ++@noindent ++Based on this definition, the following five tables are examples of invalid ++tables: ++ ++@example ++ +-----+ +-----+ +--+ +-++--+ ++ ++ | | | | | | | || | ++ ++ | +-+ | | | | | | || | ++ | | | | +--+ | +--+--+ +-++--+ ++ | +-+ | | | | | | | +-++--+ ++ | | | | | | | | | || | ++ +-----+ +--+--+ +--+--+ +-++--+ ++ a b c d e ++@end example ++ ++From left to right: ++ ++@enumerate a ++@item ++Overlapped cells or non-rectangular cells are not allowed. ++@item ++Same as a. ++@item ++The border must be rectangular. ++@item ++Cells must have a minimum width/height of one character. ++@item ++Same as d. ++@end enumerate ++ ++@node Table Creation ++@subsection How to Create a Table? ++@cindex create a text-based table ++@cindex table creation ++ ++@findex table-insert ++ The command to create a table is @code{table-insert}. When called ++interactively, it asks for the number of columns, number of rows, cell ++width and cell height. The number of columns is the number of cells ++horizontally side by side. The number of rows is the number of cells ++vertically within the table's height. The cell width is a number of ++characters that each cell holds, left to right. The cell height is a ++number of lines each cell holds. The cell width and the cell height ++can be either an integer (when the value is constant across the table) ++or a series of integer, separated by spaces or commas, where each ++number corresponds to the next cell within a row from left to right, ++or the next cell within a column from top to bottom. ++ ++@node Table Recognition ++@subsection Table Recognition ++@cindex table recognition ++ ++@findex table-recognize ++@findex table-unrecognize ++ Table mode maintains special text properties in the buffer to allow ++editing in a convenient fashion. When a buffer with tables is saved ++to its file, these text properties are lost, so when you visit this ++file again later, Emacs does not see a table, but just formatted text. ++To resurrect the table text properties, issue the @kbd{M-x ++table-recognize} command. It scans the current buffer, recognizes ++valid table cells, and attaches appropriate text properties to allow ++for table editing. The converse command, @code{table-unrecognize}, is ++used to remove the special text properties and convert the buffer back ++to plain text. ++ ++ Special commands exist to enable or disable tables within a region, ++enable or disable individual tables, and enable/disable individual ++cells. These commands are: ++ ++@table @kbd ++@findex table-recognize-region ++@item M-x table-recognize-region ++Recognize tables within the current region and activate them. ++@findex table-unrecognize-region ++@item M-x table-unrecognize-region ++Deactivate tables within the current region. ++@findex table-recognize-table ++@item M-x table-recognize-table ++Recognize the table under point and activate it. ++@findex table-unrecognize-table ++@item M-x table-unrecognize-table ++Deactivate the table under point. ++@findex table-recognize-cell ++@item M-x table-recognize-cell ++Recognize the cell under point and activate it. ++@findex table-unrecognize-cell ++@item M-x table-unrecognize-cell ++Deactivate the cell under point. ++@end table ++ ++ For another way of converting text into tables, see @ref{Table ++Conversion}. ++ ++@node Cell Commands ++@subsection Commands for Table Cells ++ ++@findex table-forward-cell ++@findex table-backward-cell ++ The commands @code{table-forward-cell} and ++@code{table-backward-cell} move point from the current cell to an ++adjacent cell forward and backward respectively. The order of the ++cells is cyclic: when point is in the last cell of a table, typing ++@kbd{M-x table-forward-cell} moves to the first cell in the table. ++Likewise @kbd{M-x table-backward-cell} from the first cell in a table ++moves to the last cell. ++ ++@findex table-span-cell ++ The command @code{table-span-cell} merges the current cell with the ++adjacent cell in a specified direction---right, left, above or below. ++You specify the direction with the minibuffer. It does not allow ++merges which don't result in a legitimate cell layout. ++ ++@findex table-split-cell ++@cindex text-based tables, split a cell ++@cindex split table cell ++ The command @code{table-split-cell} splits the current cell ++vertically or horizontally. This command is a wrapper to the ++direction specific commands @code{table-split-cell-vertically} and ++@code{table-split-cell-horizontally}. You specify the direction with ++a minibuffer argument. ++ ++@findex table-split-cell-vertically ++ The command @code{table-split-cell-vertically} splits the current ++cell vertically and creates a pair of cells above and below where ++point is located. The content in the original cell is split as well. ++ ++@findex table-split-cell-horizontally ++ The command @code{table-split-cell-horizontally} splits the current ++cell horizontally and creates a pair of cells right and left of where ++point is located. If the cell being split is not empty, this asks you ++how to handle the cell contents. The three options are: @code{split}, ++@code{left}, or @code{right}. @code{split} splits the contents at ++point literally, while the @code{left} and @code{right} options move ++the entire contents into the left or right cell respectively. ++ ++@cindex enlarge a table cell ++@cindex shrink a table cell ++ The next four commands enlarge or shrink a cell. They use numeric ++arguments (@pxref{Arguments}) to specify how many columns or rows to ++enlarge or shrink a particular table. ++ ++@table @kbd ++@findex table-heighten-cell ++@item M-x table-heighten-cell ++Enlarge the current cell vertically. ++@findex table-shorten-cell ++@item M-x table-shorten-cell ++Shrink the current cell vertically. ++@findex table-widen-cell ++@item M-x table-widen-cell ++Enlarge the current cell horizontally. ++@findex table-narrow-cell ++@item M-x table-narrow-cell ++Shrink the current cell horizontally. ++@end table ++ ++@node Cell Justification ++@subsection Cell Justification ++@cindex cell text justification ++ ++ You can specify text justification for each cell. The justification ++is remembered independently for each cell and the subsequent editing ++of cell contents is subject to the specified justification. ++ ++@findex table-justify ++ The command @code{table-justify} ask you to specify what to justify: ++a cell, a column, or a row. If you select cell justification, this ++command sets the justification only for the current cell. Selecting ++column or row justification sets the justification for all the cells ++within a column or row respectively. The command then ask you which ++kind of justification to apply: @code{left}, @code{center}, ++@code{right}, @code{top}, @code{middle}, @code{bottom}, or ++@code{none}. Horizontal justification and vertical justification are ++specified independently. The options @code{left}, @code{center}, and ++@code{right} specify horizontal justification while the options ++@code{top}, @code{middle}, @code{bottom}, and @code{none} specify ++vertical justification. The vertical justification @code{none} ++effectively removes vertical justification. Horizontal justification ++must be one of @code{left}, @code{center}, or @code{right}. ++ ++@vindex table-detect-cell-alignment ++ Justification information is stored in the buffer as a part of text ++property. Therefore, this information is ephemeral and does not ++survive through the loss of the buffer (closing the buffer and ++revisiting the buffer erase any previous text properties). To ++countermand for this, the command @code{table-recognize} and other ++recognition commands (@pxref{Table Recognition}) are equipped with a ++convenience feature (turned on by default). During table recognition, ++the contents of a cell are examined to determine which justification ++was originally applied to the cell and then applies this justification ++to the cell. This is a speculative algorithm and is therefore not ++perfect, however, the justification is deduced correctly most of the ++time. To disable this feature, customize the variable ++@code{table-detect-cell-alignment} and set it to @code{nil}. ++ ++@node Row Commands ++@subsection Commands for Table Rows ++@cindex table row commands ++ ++@cindex insert row in table ++@findex table-insert-row ++ The command @code{table-insert-row} inserts a row of cells before ++the current row in a table. The current row where point is located is ++pushed down after the newly inserted row. A numeric prefix argument ++specifies the number of rows to insert. Note that in order to insert ++rows @emph{after} the last row at the bottom of a table, you must ++place point below the table---that is, outside the table---prior to ++invoking this command. ++ ++@cindex delete row in table ++@findex table-delete-row ++ The command @code{table-delete-row} deletes a row of cells at point. ++A numeric prefix argument specifies the number of rows to delete. ++ ++@node Column Commands ++@subsection Commands for Table Columns ++@cindex table column commands ++ ++@cindex insert column in table ++@findex table-insert-column ++ The command @code{table-insert-column} inserts a column of cells to ++the left of the current row in a table. This pushes the current ++column to the right. To insert a column to the right side of the ++rightmost column, place point to the right of the rightmost column, ++which is outside of the table, prior to invoking this command. A ++numeric prefix argument specifies the number of columns to insert. ++ ++@cindex delete column in table ++ A command @code{table-delete-column} deletes a column of cells at ++point. A numeric prefix argument specifies the number of columns to ++delete. ++ ++@node Fixed Width Mode ++@subsection Fix Width of Cells ++@cindex fix width of table cells ++ ++@findex table-fixed-width-mode ++ The command @code{table-fixed-width-mode} toggles fixed width mode ++on and off. When fixed width mode is turned on, editing inside a ++cell never changes the cell width; when it is off, the cell width ++expands automatically in order to prevent a word from being folded ++into multiple lines. By default, fixed width mode is disabled. ++ ++@node Table Conversion ++@subsection Conversion Between Plain Text and Tables ++@cindex text to table ++@cindex table to text ++ ++@findex table-capture ++ The command @code{table-capture} captures plain text in a region and ++turns it into a table. Unlike @code{table-recognize} (@pxref{Table ++Recognition}), the original text does not have a table appearance but ++may hold a logical table structure. For example, some elements ++separated by known patterns form a two dimensional structure which can ++be turned into a table. ++ ++ Here's an example of data that @code{table-capture} can operate on. ++The numbers are horizontally separated by a comma and vertically ++separated by a newline character. ++ ++@example ++1, 2, 3, 4 ++5, 6, 7, 8 ++, 9, 10 ++@end example ++ ++@noindent ++Invoking @kbd{M-x table-capture} on that text produces this table: ++ ++@example +++-----+-----+-----+-----+ ++|1 |2 |3 |4 | +++-----+-----+-----+-----+ ++|5 |6 |7 |8 | +++-----+-----+-----+-----+ ++| |9 |10 | | +++-----+-----+-----+-----+ ++@end example ++ ++@noindent ++The conversion uses @samp{,} for the column delimiter and newline for ++a row delimiter, cells are left justified, and minimum cell width is ++5. ++ ++@findex table-release ++ The command @code{table-release} does the opposite of ++@code{table-capture}. It releases a table by removing the table frame ++and cell borders. This leaves the table contents as plain text. One ++of the useful applications of @code{table-capture} and ++@code{table-release} is to edit a text in layout. Look at the ++following three paragraphs (the latter two are indented with header ++lines): ++ ++@example ++@samp{table-capture} is a powerful command, but mastering its ++power requires some practice. Here are some things it can do: ++ ++Parse Cell Items By using column delimiter regular ++ expression and raw delimiter regular ++ expression, it parses the specified text ++ area and extracts cell items from ++ non-table text and then forms a table out ++ of them. ++ ++Capture Text Area When no delimiters are specified it ++ creates a single cell table. The text in ++ the specified region is placed in that ++ cell. ++@end example ++ ++@noindent ++Applying @code{table-capture} to a region containing the above three ++paragraphs, with empty strings for column delimiter regexp and row ++delimiter regexp, creates a table with a single cell like the ++following one. ++ ++@c The first line's right-hand frame in the following two examples ++@c sticks out to accommodate for the removal of @samp in the ++@c produced output!! ++@smallexample ++@group +++-----------------------------------------------------------------+ ++|@samp{table-capture} is a powerful command, but mastering its | ++|power requires some practice. Here are some things it can do: | ++| | ++|Parse Cell Items By using column delimiter regular | ++| expression and raw delimiter regular | ++| expression, it parses the specified text | ++| area and extracts cell items from | ++| non-table text and then forms a table out | ++| of them. | ++| | ++|Capture Text Area When no delimiters are specified it | ++| creates a single cell table. The text in | ++| the specified region is placed in that | ++| cell. | +++-----------------------------------------------------------------+ ++@end group ++@end smallexample ++ ++@noindent ++By splitting the cell appropriately we now have a table consisting of ++paragraphs occupying its own cell. Each cell can now be edited ++independently without affecting the layout of other cells. ++ ++@smallexample +++-----------------------------------------------------------------+ ++|@samp{table-capture} is a powerful command, but mastering its | ++|power requires some practice. Here are some things it can do: | +++---------------------+-------------------------------------------+ ++|Parse Cell Items |By using column delimiter regular | ++| |expression and raw delimiter regular | ++| |expression, it parses the specified text | ++| |area and extracts cell items from | ++| |non-table text and then forms a table out | ++| |of them. | +++---------------------+-------------------------------------------+ ++|Capture Text Area |When no delimiters are specified it | ++| |creates a single cell table. The text in | ++| |the specified region is placed in that | ++| |cell. | +++---------------------+-------------------------------------------+ ++@end smallexample ++ ++@noindent ++By applying @code{table-release}, which does the opposite process, the ++contents become once again plain text. @code{table-release} works as ++a companion command to @code{table-capture}. ++ ++@node Measuring Tables ++@subsection Analyzing Table Dimensions ++@cindex table dimensions ++ ++@findex table-query-dimension ++ The command @code{table-query-dimension} analyzes a table structure ++and reports information regarding its dimensions. In case of the ++above example table, the @code{table-query-dimension} command displays ++in echo area: ++ ++@smallexample ++Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5 ++@end smallexample ++ ++@noindent ++This indicates that the current cell is 21 character wide and 6 lines ++high, the entire table is 67 characters wide and 16 lines high. The ++table has 2 columns and 3 rows. It has a total of 5 cells, since the ++first row has a spanned cell. ++ ++@node Table Misc ++@subsection Table Miscellany ++ ++@cindex insert string into table cells ++@findex table-insert-sequence ++ The command @code{table-insert-sequence} inserts a string into each ++cell. Each string is a part of a sequence i.e.@: a series of ++increasing integer numbers. ++ ++@cindex table in language format ++@cindex table for HTML and LaTeX ++@findex table-generate-source ++ The command @code{table-generate-source} generates a table formatted ++for a specific markup language. It asks for a language (which must be ++one of @code{html}, @code{latex}, or @code{cals}), a destination ++buffer where to put the result, and the table caption (a string), and ++then inserts the generated table in the proper syntax into the ++destination buffer. The default destination buffer is ++@code{table.@var{lang}}, where @var{lang} is the language you ++specified. ++ ++@ignore ++ arch-tag: 8db54ed8-2036-49ca-b0df-23811d03dc70 ++@end ignore +diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi +new file mode 100644 +index 0000000..68c5fe9 +--- /dev/null ++++ b/doc/emacs/trouble.texi +@@ -0,0 +1,1055 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@iftex ++@chapter Dealing with Common Problems ++ ++ If you type an Emacs command you did not intend, the results are often ++mysterious. This chapter tells what you can do to cancel your mistake or ++recover from a mysterious situation. Emacs bugs and system crashes are ++also considered. ++@end iftex ++ ++@ifnottex ++@raisesections ++@end ifnottex ++ ++@node Quitting, Lossage, Customization, Top ++@section Quitting and Aborting ++@cindex quitting ++ ++@table @kbd ++@item C-g ++@itemx C-@key{BREAK} @r{(MS-DOS only)} ++Quit: cancel running or partially typed command. ++@item C-] ++Abort innermost recursive editing level and cancel the command which ++invoked it (@code{abort-recursive-edit}). ++@item @key{ESC} @key{ESC} @key{ESC} ++Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). ++@item M-x top-level ++Abort all recursive editing levels that are currently executing. ++@item C-/ ++@itemx C-x u ++@itemx C-_ ++Cancel a previously made change in the buffer contents (@code{undo}). ++@end table ++ ++ There are two ways of canceling a command before it has finished: ++@dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or ++@kbd{M-x top-level}. Quitting cancels a partially typed command, or ++one which is still running. Aborting exits a recursive editing level ++and cancels the command that invoked the recursive edit. ++(@xref{Recursive Edit}.) ++ ++@cindex quitting ++@kindex C-g ++ Quitting with @kbd{C-g} is the way to get rid of a partially typed ++command, or a numeric argument that you don't want. Furthermore, if ++you are in the middle of a command that is running, @kbd{C-g} stops ++the command in a relatively safe way. For example, if you quit out of ++a kill command that is taking a long time, either your text will ++@emph{all} still be in the buffer, or it will @emph{all} be in the ++kill ring, or maybe both. If the region is active, @kbd{C-g} ++deactivates the mark, unless Transient Mark mode is off ++(@pxref{Persistent Mark}). If you are in the middle of an incremental ++search, @kbd{C-g} does special things; it may take two successive ++@kbd{C-g} characters to get out of a search. @xref{Incremental ++Search}, for details. ++ ++ On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character ++like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to ++recognize @kbd{C-g} while a command is running, between interactions ++with the user. By contrast, it @emph{is} feasible to recognize ++@kbd{C-@key{BREAK}} at all times. ++@iftex ++@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}. ++@end iftex ++@ifnottex ++@xref{MS-DOS Keyboard}. ++@end ifnottex ++ ++@findex keyboard-quit ++ @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} ++the instant @kbd{C-g} is typed; Emacs Lisp checks this variable ++frequently, and quits if it is non-@code{nil}. @kbd{C-g} is only ++actually executed as a command if you type it while Emacs is waiting for ++input. In that case, the command it runs is @code{keyboard-quit}. ++ ++ On a text terminal, if you quit with @kbd{C-g} a second time before ++the first @kbd{C-g} is recognized, you activate the ``emergency ++escape'' feature and return to the shell. @xref{Emergency Escape}. ++ ++@cindex NFS and quitting ++ There are some situations where you cannot quit. When Emacs is ++waiting for the operating system to do something, quitting is ++impossible unless special pains are taken for the particular system ++call within Emacs where the waiting occurs. We have done this for the ++system calls that users are likely to want to quit from, but it's ++possible you will encounter a case not handled. In one very common ++case---waiting for file input or output using NFS---Emacs itself knows ++how to quit, but many NFS implementations simply do not allow user ++programs to stop waiting for NFS when the NFS server is hung. ++ ++@cindex aborting recursive edit ++@findex abort-recursive-edit ++@kindex C-] ++ Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get ++out of a recursive editing level and cancel the command which invoked ++it. Quitting with @kbd{C-g} does not do this, and could not do this, ++because it is used to cancel a partially typed command @emph{within} the ++recursive editing level. Both operations are useful. For example, if ++you are in a recursive edit and type @kbd{C-u 8} to enter a numeric ++argument, you can cancel that argument with @kbd{C-g} and remain in the ++recursive edit. ++ ++@findex keyboard-escape-quit ++@kindex ESC ESC ESC ++ The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}} ++(@code{keyboard-escape-quit}) can either quit or abort. (We defined ++it this way because @key{ESC} means ``get out'' in many PC programs.) ++It can cancel a prefix argument, clear a selected region, or get out ++of a Query Replace, like @kbd{C-g}. It can get out of the minibuffer ++or a recursive edit, like @kbd{C-]}. It can also get out of splitting ++the frame into multiple windows, as with @kbd{C-x 1}. One thing it ++cannot do, however, is stop a command that is running. That's because ++it executes as an ordinary command, and Emacs doesn't notice it until ++it is ready for the next command. ++ ++@findex top-level ++ The command @kbd{M-x top-level} is equivalent to ``enough'' ++@kbd{C-]} commands to get you out of all the levels of recursive edits ++that you are in; it also exits the minibuffer if it is active. ++@kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level} ++goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} ++are like all other commands, and unlike @kbd{C-g}, in that they take ++effect only when Emacs is ready for a command. @kbd{C-]} is an ++ordinary key and has its meaning only because of its binding in the ++keymap. @xref{Recursive Edit}. ++ ++ @kbd{C-/} (@code{undo}) is not strictly speaking a way of canceling ++a command, but you can think of it as canceling a command that already ++finished executing. @xref{Undo}, for more information about the undo ++facility. ++ ++@node Lossage, Bugs, Quitting, Top ++@section Dealing with Emacs Trouble ++ ++ This section describes various conditions in which Emacs fails to work ++normally, and how to recognize them and correct them. For a list of ++additional problems you might encounter, see @ref{Bugs and problems, , ++Bugs and problems, efaq, GNU Emacs FAQ}, and the file @file{etc/PROBLEMS} ++in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type ++@kbd{C-h C-p} to read the @file{PROBLEMS} file. ++ ++@menu ++* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. ++* Stuck Recursive:: `[...]' in mode line around the parentheses. ++* Screen Garbled:: Garbage on the screen. ++* Text Garbled:: Garbage in the text. ++* Memory Full:: How to cope when you run out of memory. ++* After a Crash:: Recovering editing in an Emacs session that crashed. ++* Emergency Escape:: Emergency escape--- ++ What to do if Emacs stops responding. ++* Total Frustration:: When you are at your wits' end. ++@end menu ++ ++@node DEL Does Not Delete ++@subsection If @key{DEL} Fails to Delete ++@cindex @key{DEL} vs @key{BACKSPACE} ++@cindex @key{BACKSPACE} vs @key{DEL} ++@cindex usual erasure key ++ ++ Every keyboard has a large key, usually labelled @key{Backspace}, ++which is ordinarily used to erase the last character that you typed. ++We call this key @dfn{the usual erasure key}. In Emacs, it is ++supposed to be equivalent to @key{DEL}. ++ ++ When Emacs starts up on a graphical display, it determines ++automatically which key should be @key{DEL}. In some unusual cases, ++Emacs gets the wrong information from the system. If the usual ++erasure key deletes forwards instead of backwards, that is probably ++what happened---Emacs ought to be treating the @key{Backspace} key as ++@key{DEL}, but it isn't. ++ ++ Some keyboards also have a @key{Delete} key, which is ordinarily ++used to forwards. If this key deletes backward in Emacs, that too ++suggests Emacs got the wrong information---but in the opposite sense. ++ ++ On a text-only terminal, if you find the usual erasure key prompts ++for a Help command, like @kbd{Control-h}, instead of deleting a ++character, it means that key is actually sending the @key{BS} ++character. Emacs ought to be treating @key{BS} as @key{DEL}, but it ++isn't. ++ ++ In all of those cases, the immediate remedy is the same: use the ++command @kbd{M-x normal-erase-is-backspace-mode}. This toggles ++between the two modes that Emacs supports for handling @key{DEL}, so ++if Emacs starts in the wrong mode, this should switch to the right ++mode. On a text-only terminal, if you want to ask for help when ++@key{BS} is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also ++work, if it sends character code 127. ++ ++@findex normal-erase-is-backspace-mode ++ To fix the problem automatically for every Emacs session, you can ++put one of the following lines into your @file{.emacs} file ++(@pxref{Init File}). For the first case above, where @key{Backspace} ++deletes forwards instead of backwards, use this line to make ++@key{Backspace} act as @key{DEL} (resulting in behavior compatible ++with Emacs 20 and previous versions): ++ ++@lisp ++(normal-erase-is-backspace-mode 0) ++@end lisp ++ ++@noindent ++For the other two cases, use this line: ++ ++@lisp ++(normal-erase-is-backspace-mode 1) ++@end lisp ++ ++@vindex normal-erase-is-backspace ++ Another way to fix the problem for every Emacs session is to ++customize the variable @code{normal-erase-is-backspace}: the value ++@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is ++@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy ++Customization}. ++ ++@node Stuck Recursive ++@subsection Recursive Editing Levels ++ ++ Recursive editing levels are important and useful features of Emacs, but ++they can seem like malfunctions if you do not understand them. ++ ++ If the mode line has square brackets @samp{[@dots{}]} around the parentheses ++that contain the names of the major and minor modes, you have entered a ++recursive editing level. If you did not do this on purpose, or if you ++don't understand what that means, you should just get out of the recursive ++editing level. To do so, type @kbd{M-x top-level}. This is called getting ++back to top level. @xref{Recursive Edit}. ++ ++@node Screen Garbled ++@subsection Garbage on the Screen ++ ++ If the text on a text terminal looks wrong, the first thing to do is ++see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay ++the entire screen. If the screen appears correct after this, the ++problem was entirely in the previous screen update. (Otherwise, see ++the following section.) ++ ++ Display updating problems often result from an incorrect terminfo ++entry for the terminal you are using. The file @file{etc/TERMS} in ++the Emacs distribution gives the fixes for known problems of this ++sort. @file{INSTALL} contains general advice for these problems in ++one of its sections. To investigate the possibility that you have ++this sort of problem, try Emacs on another terminal made by a ++different manufacturer. If problems happen frequently on one kind of ++terminal but not another kind, it is likely to be a bad terminfo entry, ++though it could also be due to a bug in Emacs that appears for ++terminals that have or that lack specific features. ++ ++@node Text Garbled ++@subsection Garbage in the Text ++ ++ If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to ++see what commands you typed to produce the observed results. Then try ++undoing the changes step by step using @kbd{C-x u}, until it gets back ++to a state you consider correct. ++ ++ If a large portion of text appears to be missing at the beginning or ++end of the buffer, check for the word @samp{Narrow} in the mode line. ++If it appears, the text you don't see is probably still present, but ++temporarily off-limits. To make it accessible again, type @kbd{C-x n ++w}. @xref{Narrowing}. ++ ++@node Memory Full ++@subsection Running out of Memory ++@cindex memory full ++@cindex out of memory ++ ++ If you get the error message @samp{Virtual memory exceeded}, save ++your modified buffers with @kbd{C-x s}. This method of saving them ++has the smallest need for additional memory. Emacs keeps a reserve of ++memory which it makes available when this error happens; that should ++be enough to enable @kbd{C-x s} to complete its work. When the ++reserve has been used, @samp{!MEM FULL!} appears at the beginning of ++the mode line, indicating there is no more reserve. ++ ++ Once you have saved your modified buffers, you can exit this Emacs ++session and start another, or you can use @kbd{M-x kill-some-buffers} ++to free space in the current Emacs job. If this frees up sufficient ++space, Emacs will refill its memory reserve, and @samp{!MEM FULL!} ++will disappear from the mode line. That means you can safely go on ++editing in the same Emacs session. ++ ++ Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run ++out of memory, because the buffer menu needs a fair amount of memory ++itself, and the reserve supply may not be enough. ++ ++@node After a Crash ++@subsection Recovery After a Crash ++ ++ If Emacs or the computer crashes, you can recover the files you were ++editing at the time of the crash from their auto-save files. To do ++this, start Emacs again and type the command @kbd{M-x recover-session}. ++ ++ This command initially displays a buffer which lists interrupted ++session files, each with its date. You must choose which session to ++recover from. Typically the one you want is the most recent one. Move ++point to the one you choose, and type @kbd{C-c C-c}. ++ ++ Then @code{recover-session} considers each of the files that you ++were editing during that session; for each such file, it asks whether ++to recover that file. If you answer @kbd{y} for a file, it shows the ++dates of that file and its auto-save file, then asks once again ++whether to recover that file. For the second question, you must ++confirm with @kbd{yes}. If you do, Emacs visits the file but gets the ++text from the auto-save file. ++ ++ When @code{recover-session} is done, the files you've chosen to ++recover are present in Emacs buffers. You should then save them. Only ++this---saving them---updates the files themselves. ++ ++ As a last resort, if you had buffers with content which were not ++associated with any files, or if the autosave was not recent enough to ++have recorded important changes, you can use the ++@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to ++retrieve them from a core dump--provided that a core dump was saved, ++and that the Emacs executable was not stripped of its debugging ++symbols. ++ ++ As soon as you get the core dump, rename it to another name such as ++@file{core.emacs}, so that another crash won't overwrite it. ++ ++ To use this script, run @code{gdb} with the file name of your Emacs ++executable and the file name of the core dump, e.g. @samp{gdb ++/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the ++recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}. ++Then type the command @code{ybuffer-list} to see which buffers are ++available. For each buffer, it lists a buffer number. To save a ++buffer, use @code{ysave-buffer}; you specify the buffer number, and ++the file name to write that buffer into. You should use a file name ++which does not already exist; if the file does exist, the script does ++not make a backup of its old contents. ++ ++@node Emergency Escape ++@subsection Emergency Escape ++ ++ On text-only terminals, the @dfn{emergency escape} feature suspends ++Emacs immediately if you type @kbd{C-g} a second time before Emacs can ++actually respond to the first one by quitting. This is so you can ++always get out of GNU Emacs no matter how badly it might be hung. ++When things are working properly, Emacs recognizes and handles the ++first @kbd{C-g} so fast that the second one won't trigger emergency ++escape. However, if some problem prevents Emacs from handling the ++first @kbd{C-g} properly, then the second one will get you back to the ++shell. ++ ++ When you resume Emacs after a suspension caused by emergency escape, ++it asks two questions before going back to what it had been doing: ++ ++@example ++Auto-save? (y or n) ++Abort (and dump core)? (y or n) ++@end example ++ ++@noindent ++Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. ++ ++ Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of ++all modified buffers in which auto-saving is enabled. Saying @kbd{n} ++skips this. ++ ++ Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to ++crash, dumping core. This is to enable a wizard to figure out why ++Emacs was failing to quit in the first place. Execution does not ++continue after a core dump. ++ ++ If you answer this question @kbd{n}, Emacs execution resumes. With ++luck, Emacs will ultimately do the requested quit. If not, each ++subsequent @kbd{C-g} invokes emergency escape again. ++ ++ If Emacs is not really hung, just slow, you may invoke the double ++@kbd{C-g} feature without really meaning to. Then just resume and ++answer @kbd{n} to both questions, and you will get back to the former ++state. The quit you requested will happen by and by. ++ ++ Emergency escape is active only for text terminals. On graphical ++displays, you can use the mouse to kill Emacs or switch to another ++program. ++ ++ On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause ++emergency escape---but there are cases where it won't work, when ++system call hangs or when Emacs is stuck in a tight loop in C code. ++ ++@node Total Frustration ++@subsection Help for Total Frustration ++@cindex Eliza ++@cindex doctor ++ ++ If using Emacs (or something else) becomes terribly frustrating and none ++of the techniques described above solve the problem, Emacs can still help ++you. ++ ++ First, if the Emacs you are using is not responding to commands, type ++@kbd{C-g C-g} to get out of it and then start a new one. ++ ++@findex doctor ++ Second, type @kbd{M-x doctor @key{RET}}. ++ ++ The Emacs psychotherapist will help you feel better. Each time you ++say something to the psychotherapist, you must end it by typing ++@key{RET} @key{RET}. This indicates you are finished typing. ++ ++@node Bugs, Contributing, Lossage, Top ++@section Reporting Bugs ++ ++@cindex bugs ++ Sometimes you will encounter a bug in Emacs. Although we cannot ++promise we can or will fix the bug, and we might not even agree that it ++is a bug, we want to hear about problems you encounter. Often we agree ++they are bugs and want to fix them. ++ ++ To make it possible for us to fix a bug, you must report it. In order ++to do so effectively, you must know when and how to do it. ++ ++ Before reporting a bug, it is a good idea to see if it is already ++known. You can find the list of known problems in the file ++@file{etc/PROBLEMS} in the Emacs distribution; type @kbd{C-h C-e} to read ++it. Some additional user-level problems can be found in @ref{Bugs and ++problems, , Bugs and problems, efaq, GNU Emacs FAQ}. Looking up your ++problem in these two documents might provide you with a solution or a ++work-around, or give you additional information about related issues. ++ ++@menu ++* Criteria: Bug Criteria. Have you really found a bug? ++* Understanding Bug Reporting:: How to report a bug effectively. ++* Checklist:: Steps to follow for a good bug report. ++* Sending Patches:: How to send a patch for GNU Emacs. ++@end menu ++ ++@node Bug Criteria ++@subsection When Is There a Bug ++ ++ If Emacs accesses an invalid memory location (``segmentation ++fault''), or exits with an operating system error message that ++indicates a problem in the program (as opposed to something like ++``disk full''), then it is certainly a bug. ++ ++ If Emacs updates the display in a way that does not correspond to what is ++in the buffer, then it is certainly a bug. If a command seems to do the ++wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a ++case of incorrect display updating. ++ ++ Taking forever to complete a command can be a bug, but you must make ++certain that it was really Emacs's fault. Some commands simply take a ++long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then @kbd{C-h l} ++to see whether the input Emacs received was what you intended to type; ++if the input was such that you @emph{know} it should have been processed ++quickly, report a bug. If you don't know whether the command should ++take a long time, find out by looking in the manual or by asking for ++assistance. ++ ++ If a command you are familiar with causes an Emacs error message in a ++case where its usual definition ought to be reasonable, it is probably a ++bug. ++ ++ If a command does the wrong thing, that is a bug. But be sure you know ++for certain what it ought to have done. If you aren't familiar with the ++command, or don't know for certain how the command is supposed to work, ++then it might actually be working right. Rather than jumping to ++conclusions, show the problem to someone who knows for certain. ++ ++ Finally, a command's intended definition may not be the best ++possible definition for editing with. This is a very important sort ++of problem, but it is also a matter of judgment. Also, it is easy to ++come to such a conclusion out of ignorance of some of the existing ++features. It is probably best not to complain about such a problem ++until you have checked the documentation in the usual ways, feel ++confident that you understand it, and know for certain that what you ++want is not available. Ask other Emacs users, too. If you are not ++sure what the command is supposed to do after a careful reading of the ++manual, check the index and glossary for any terms that may be ++unclear. ++ ++ If after careful rereading of the manual you still do not understand ++what the command should do, that indicates a bug in the manual, which ++you should report. The manual's job is to make everything clear to ++people who are not Emacs experts---including you. It is just as ++important to report documentation bugs as program bugs. ++ ++ If the on-line documentation string of a function or variable disagrees ++with the manual, one of them must be wrong; that is a bug. ++ ++@node Understanding Bug Reporting ++@subsection Understanding Bug Reporting ++ ++@findex emacs-version ++ When you decide that there is a bug, it is important to report it and to ++report it in a way which is useful. What is most useful is an exact ++description of what commands you type, starting with the shell command to ++run Emacs, until the problem happens. ++ ++ The most important principle in reporting a bug is to report ++@emph{facts}. Hypotheses and verbal descriptions are no substitute for ++the detailed raw data. Reporting the facts is straightforward, but many ++people strain to posit explanations and report them instead of the ++facts. If the explanations are based on guesses about how Emacs is ++implemented, they will be useless; meanwhile, lacking the facts, we will ++have no real information about the bug. ++ ++ For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh ++@key{RET}}, visiting a file which (you know) happens to be rather ++large, and Emacs displays @samp{I feel pretty today}. The best way to ++report the bug is with a sentence like the preceding one, because it ++gives all the facts. ++ ++ A bad way would be to assume that the problem is due to the size of ++the file and say, ``I visited a large file, and Emacs displayed @samp{I ++feel pretty today}.'' This is what we mean by ``guessing ++explanations.'' The problem is just as likely to be due to the fact ++that there is a @samp{z} in the file name. If this is so, then when we ++got your report, we would try out the problem with some ``large file,'' ++probably with no @samp{z} in its name, and not see any problem. There ++is no way in the world that we could guess that we should try visiting a ++file with a @samp{z} in its name. ++ ++ Alternatively, the problem might be due to the fact that the file starts ++with exactly 25 spaces. For this reason, you should make sure that you ++inform us of the exact contents of any file that is needed to reproduce the ++bug. What if the problem only occurs when you have typed the @kbd{C-x C-a} ++command previously? This is why we ask you to give the exact sequence of ++characters you typed since starting the Emacs session. ++ ++ You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless ++you @emph{know} that it makes no difference which visiting command is used. ++Similarly, rather than saying ``if I have three characters on the line,'' ++say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is ++the way you entered the text. ++ ++ So please don't guess any explanations when you report a bug. If you ++want to actually @emph{debug} the problem, and report explanations that ++are more than guesses, that is useful---but please include the facts as ++well. ++ ++@node Checklist ++@subsection Checklist for Bug Reports ++ ++@cindex reporting bugs ++ The best way to send a bug report is to mail it electronically to the ++Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}, or to ++@email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs beta ++release. (If you want to suggest a change as an improvement, use the ++same address.) ++ ++ If you'd like to read the bug reports, you can find them on the ++newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a ++spectator you should not criticize anything about what you see there. ++The purpose of bug reports is to give information to the Emacs ++maintainers. Spectators are welcome only as long as they do not ++interfere with this. In particular, some bug reports contain fairly ++large amounts of data; spectators should not complain about this. ++ ++ Please do not post bug reports using netnews; mail is more reliable ++than netnews about reporting your correct address, which we may need ++in order to ask you for more information. If your data is more than ++500,000 bytes, please don't include it directly in the bug report; ++instead, offer to send it on request, or make it available by ftp and ++say where. ++ ++@findex report-emacs-bug ++ A convenient way to send a bug report for Emacs is to use the command ++@kbd{M-x report-emacs-bug}. This sets up a mail buffer (@pxref{Sending ++Mail}) and automatically inserts @emph{some} of the essential ++information. However, it cannot supply all the necessary information; ++you should still read and follow the guidelines below, so you can enter ++the other crucial information by hand before you send the message. ++ ++ To enable maintainers to investigate a bug, your report ++should include all these things: ++ ++@itemize @bullet ++@item ++The version number of Emacs. Without this, we won't know whether there ++is any point in looking for the bug in the current version of GNU ++Emacs. ++ ++You can get the version number by typing @kbd{M-x emacs-version ++@key{RET}}. If that command does not work, you probably have something ++other than GNU Emacs, so you will have to report the bug somewhere ++else. ++ ++@item ++The type of machine you are using, and the operating system name and ++version number. @kbd{M-x emacs-version @key{RET}} provides this ++information too. Copy its output from the @samp{*Messages*} buffer, so ++that you get it all and get it accurately. ++ ++@item ++The operands given to the @code{configure} command when Emacs was ++installed. ++ ++@item ++A complete list of any modifications you have made to the Emacs source. ++(We may not have time to investigate the bug unless it happens in an ++unmodified Emacs. But if you've made modifications and you don't tell ++us, you are sending us on a wild goose chase.) ++ ++Be precise about these changes. A description in English is not ++enough---send a context diff for them. ++ ++Adding files of your own, or porting to another machine, is a ++modification of the source. ++ ++@item ++Details of any other deviations from the standard procedure for installing ++GNU Emacs. ++ ++@item ++The complete text of any files needed to reproduce the bug. ++ ++ If you can tell us a way to cause the problem without visiting any files, ++please do so. This makes it much easier to debug. If you do need files, ++make sure you arrange for us to see their exact contents. For example, it ++can matter whether there are spaces at the ends of lines, or a ++newline after the last line in the buffer (nothing ought to care whether ++the last line is terminated, but try telling the bugs that). ++ ++@item ++The precise commands we need to type to reproduce the bug. ++ ++@findex open-dribble-file ++@cindex dribble file ++@cindex logging keystrokes ++The easy way to record the input to Emacs precisely is to write a ++dribble file. To start the file, execute the Lisp expression ++ ++@example ++(open-dribble-file "~/dribble") ++@end example ++ ++@noindent ++using @kbd{M-:} or from the @samp{*scratch*} buffer just after ++starting Emacs. From then on, Emacs copies all your input to the ++specified dribble file until the Emacs process is killed. ++ ++@item ++@findex open-termscript ++@cindex termscript file ++@cindex @env{TERM} environment variable ++For possible display bugs, the terminal type (the value of environment ++variable @env{TERM}), the complete termcap entry for the terminal from ++@file{/etc/termcap} (since that file is not identical on all machines), ++and the output that Emacs actually sent to the terminal. ++ ++The way to collect the terminal output is to execute the Lisp expression ++ ++@example ++(open-termscript "~/termscript") ++@end example ++ ++@noindent ++using @kbd{M-:} or from the @samp{*scratch*} buffer just after ++starting Emacs. From then on, Emacs copies all terminal output to the ++specified termscript file as well, until the Emacs process is killed. ++If the problem happens when Emacs starts up, put this expression into ++your @file{.emacs} file so that the termscript file will be open when ++Emacs displays the screen for the first time. ++ ++Be warned: it is often difficult, and sometimes impossible, to fix a ++terminal-dependent bug without access to a terminal of the type that ++stimulates the bug. ++ ++@item ++If non-@acronym{ASCII} text or internationalization is relevant, the locale that ++was current when you started Emacs. On GNU/Linux and Unix systems, or ++if you use a Posix-style shell such as Bash, you can use this shell ++command to view the relevant values: ++ ++@smallexample ++echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \ ++ LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG ++@end smallexample ++ ++Alternatively, use the @command{locale} command, if your system has it, ++to display your locale settings. ++ ++You can use the @kbd{M-!} command to execute these commands from ++Emacs, and then copy the output from the @samp{*Messages*} buffer into ++the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL ++@key{RET}} will display the value of @code{LC_ALL} in the echo area, and ++you can copy its output from the @samp{*Messages*} buffer. ++ ++@item ++A description of what behavior you observe that you believe is ++incorrect. For example, ``The Emacs process gets a fatal signal,'' or, ++``The resulting text is as follows, which I think is wrong.'' ++ ++Of course, if the bug is that Emacs gets a fatal signal, then one can't ++miss it. But if the bug is incorrect text, the maintainer might fail to ++notice what is wrong. Why leave it to chance? ++ ++Even if the problem you experience is a fatal signal, you should still ++say so explicitly. Suppose something strange is going on, such as, your ++copy of the source is out of sync, or you have encountered a bug in the ++C library on your system. (This has happened!) Your copy might crash ++and the copy here might not. If you @emph{said} to expect a crash, then ++when Emacs here fails to crash, we would know that the bug was not ++happening. If you don't say to expect a crash, then we would not know ++whether the bug was happening---we would not be able to draw any ++conclusion from our observations. ++ ++@item ++If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual ++fails to describe the actual behavior of Emacs, or that the text is ++confusing, copy in the text from the online manual which you think is ++at fault. If the section is small, just the section name is enough. ++ ++@item ++If the manifestation of the bug is an Emacs error message, it is ++important to report the precise text of the error message, and a ++backtrace showing how the Lisp program in Emacs arrived at the error. ++ ++To get the error message text accurately, copy it from the ++@samp{*Messages*} buffer into the bug report. Copy all of it, not just ++part. ++ ++@findex toggle-debug-on-error ++@pindex Edebug ++To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} ++before the error happens (that is to say, you must give that command ++and then make the bug happen). This causes the error to start the Lisp ++debugger, which shows you a backtrace. Copy the text of the ++debugger's backtrace into the bug report. @xref{Debugger,, The Lisp ++Debugger, elisp, the Emacs Lisp Reference Manual}, for information on ++debugging Emacs Lisp programs with the Edebug package. ++ ++This use of the debugger is possible only if you know how to make the ++bug happen again. If you can't make it happen again, at least copy ++the whole error message. ++ ++@item ++Check whether any programs you have loaded into the Lisp world, ++including your @file{.emacs} file, set any variables that may affect the ++functioning of Emacs. Also, see whether the problem happens in a ++freshly started Emacs without loading your @file{.emacs} file (start ++Emacs with the @code{-q} switch to prevent loading the init file). If ++the problem does @emph{not} occur then, you must report the precise ++contents of any programs that you must load into the Lisp world in order ++to cause the problem to occur. ++ ++@item ++If the problem does depend on an init file or other Lisp programs that ++are not part of the standard Emacs system, then you should make sure it ++is not a bug in those programs by complaining to their maintainers ++first. After they verify that they are using Emacs in a way that is ++supposed to work, they should report the bug. ++ ++@item ++If you wish to mention something in the GNU Emacs source, show the line ++of code with a few lines of context. Don't just give a line number. ++ ++The line numbers in the development sources don't match those in your ++sources. It would take extra work for the maintainers to determine what ++code is in your version at a given line number, and we could not be ++certain. ++ ++@item ++Additional information from a C debugger such as GDB might enable ++someone to find a problem on a machine which he does not have available. ++If you don't know how to use GDB, please read the GDB manual---it is not ++very long, and using GDB is easy. You can find the GDB distribution, ++including the GDB manual in online form, in most of the same places you ++can find the Emacs distribution. To run Emacs under GDB, you should ++switch to the @file{src} subdirectory in which Emacs was compiled, then ++do @samp{gdb emacs}. It is important for the directory @file{src} to be ++current so that GDB will read the @file{.gdbinit} file in this ++directory. ++ ++However, you need to think when you collect the additional information ++if you want it to show what causes the bug. ++ ++@cindex backtrace for bug reports ++For example, many people send just a backtrace, but that is not very ++useful by itself. A simple backtrace with arguments often conveys ++little about what is happening inside GNU Emacs, because most of the ++arguments listed in the backtrace are pointers to Lisp objects. The ++numeric values of these pointers have no significance whatever; all that ++matters is the contents of the objects they point to (and most of the ++contents are themselves pointers). ++ ++@findex debug_print ++To provide useful information, you need to show the values of Lisp ++objects in Lisp notation. Do this for each variable which is a Lisp ++object, in several stack frames near the bottom of the stack. Look at ++the source to see which variables are Lisp objects, because the debugger ++thinks of them as integers. ++ ++To show a variable's value in Lisp syntax, first print its value, then ++use the user-defined GDB command @code{pr} to print the Lisp object in ++Lisp syntax. (If you must use another debugger, call the function ++@code{debug_print} with the object as an argument.) The @code{pr} ++command is defined by the file @file{.gdbinit}, and it works only if you ++are debugging a running process (not with a core dump). ++ ++To make Lisp errors stop Emacs and return to GDB, put a breakpoint at ++@code{Fsignal}. ++ ++For a short listing of Lisp functions running, type the GDB ++command @code{xbacktrace}. ++ ++The file @file{.gdbinit} defines several other commands that are useful ++for examining the data types and contents of Lisp objects. Their names ++begin with @samp{x}. These commands work at a lower level than ++@code{pr}, and are less convenient, but they may work even when ++@code{pr} does not, such as when debugging a core dump or when Emacs has ++had a fatal signal. ++ ++@cindex debugging Emacs, tricks and techniques ++More detailed advice and other useful techniques for debugging Emacs ++are available in the file @file{etc/DEBUG} in the Emacs distribution. ++That file also includes instructions for investigating problems ++whereby Emacs stops responding (many people assume that Emacs is ++``hung,'' whereas in fact it might be in an infinite loop). ++ ++To find the file @file{etc/DEBUG} in your Emacs installation, use the ++directory name stored in the variable @code{data-directory}. ++@end itemize ++ ++Here are some things that are not necessary in a bug report: ++ ++@itemize @bullet ++@item ++A description of the envelope of the bug---this is not necessary for a ++reproducible bug. ++ ++Often people who encounter a bug spend a lot of time investigating ++which changes to the input file will make the bug go away and which ++changes will not affect it. ++ ++This is often time-consuming and not very useful, because the way we ++will find the bug is by running a single example under the debugger ++with breakpoints, not by pure deduction from a series of examples. ++You might as well save time by not searching for additional examples. ++It is better to send the bug report right away, go back to editing, ++and find another bug to report. ++ ++Of course, if you can find a simpler example to report @emph{instead} of ++the original one, that is a convenience. Errors in the output will be ++easier to spot, running under the debugger will take less time, etc. ++ ++However, simplification is not vital; if you can't do this or don't have ++time to try, please report the bug with your original test case. ++ ++@item ++A core dump file. ++ ++Debugging the core dump might be useful, but it can only be done on ++your machine, with your Emacs executable. Therefore, sending the core ++dump file to the Emacs maintainers won't be useful. Above all, don't ++include the core file in an email bug report! Such a large message ++can be extremely inconvenient. ++ ++@item ++A system-call trace of Emacs execution. ++ ++System-call traces are very useful for certain special kinds of ++debugging, but in most cases they give little useful information. It is ++therefore strange that many people seem to think that @emph{the} way to ++report information about a crash is to send a system-call trace. Perhaps ++this is a habit formed from experience debugging programs that don't ++have source code or debugging symbols. ++ ++In most programs, a backtrace is normally far, far more informative than ++a system-call trace. Even in Emacs, a simple backtrace is generally ++more informative, though to give full information you should supplement ++the backtrace by displaying variable values and printing them as Lisp ++objects with @code{pr} (see above). ++ ++@item ++A patch for the bug. ++ ++A patch for the bug is useful if it is a good one. But don't omit the ++other information that a bug report needs, such as the test case, on the ++assumption that a patch is sufficient. We might see problems with your ++patch and decide to fix the problem another way, or we might not ++understand it at all. And if we can't understand what bug you are ++trying to fix, or why your patch should be an improvement, we mustn't ++install it. ++ ++@ifnottex ++@xref{Sending Patches}, for guidelines on how to make it easy for us to ++understand and install your patches. ++@end ifnottex ++ ++@item ++A guess about what the bug is or what it depends on. ++ ++Such guesses are usually wrong. Even experts can't guess right about ++such things without first using the debugger to find the facts. ++@end itemize ++ ++@node Sending Patches ++@subsection Sending Patches for GNU Emacs ++ ++@cindex sending patches for GNU Emacs ++@cindex patches, sending ++ If you would like to write bug fixes or improvements for GNU Emacs, ++that is very helpful. When you send your changes, please follow these ++guidelines to make it easy for the maintainers to use them. If you ++don't follow these guidelines, your information might still be useful, ++but using it will take extra work. Maintaining GNU Emacs is a lot of ++work in the best of circumstances, and we can't keep up unless you do ++your best to help. ++ ++@itemize @bullet ++@item ++Send an explanation with your changes of what problem they fix or what ++improvement they bring about. For a bug fix, just include a copy of the ++bug report, and explain why the change fixes the bug. ++ ++(Referring to a bug report is not as good as including it, because then ++we will have to look it up, and we have probably already deleted it if ++we've already fixed the bug.) ++ ++@item ++Always include a proper bug report for the problem you think you have ++fixed. We need to convince ourselves that the change is right before ++installing it. Even if it is correct, we might have trouble ++understanding it if we don't have a way to reproduce the problem. ++ ++@item ++Include all the comments that are appropriate to help people reading the ++source in the future understand why this change was needed. ++ ++@item ++Don't mix together changes made for different reasons. ++Send them @emph{individually}. ++ ++If you make two changes for separate reasons, then we might not want to ++install them both. We might want to install just one. If you send them ++all jumbled together in a single set of diffs, we have to do extra work ++to disentangle them---to figure out which parts of the change serve ++which purpose. If we don't have time for this, we might have to ignore ++your changes entirely. ++ ++If you send each change as soon as you have written it, with its own ++explanation, then two changes never get tangled up, and we can consider ++each one properly without any extra work to disentangle them. ++ ++@item ++Send each change as soon as that change is finished. Sometimes people ++think they are helping us by accumulating many changes to send them all ++together. As explained above, this is absolutely the worst thing you ++could do. ++ ++Since you should send each change separately, you might as well send it ++right away. That gives us the option of installing it immediately if it ++is important. ++ ++@item ++Use @samp{diff -c} to make your diffs. Diffs without context are hard ++to install reliably. More than that, they are hard to study; we must ++always study a patch to decide whether we want to install it. Unidiff ++format is better than contextless diffs, but not as easy to read as ++@samp{-c} format. ++ ++If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when ++making diffs of C code. This shows the name of the function that each ++change occurs in. ++ ++@item ++Avoid any ambiguity as to which is the old version and which is the new. ++Please make the old version the first argument to diff, and the new ++version the second argument. And please give one version or the other a ++name that indicates whether it is the old version or your new changed ++one. ++ ++@item ++Write the change log entries for your changes. This is both to save us ++the extra work of writing them, and to help explain your changes so we ++can understand them. ++ ++The purpose of the change log is to show people where to find what was ++changed. So you need to be specific about what functions you changed; ++in large functions, it's often helpful to indicate where within the ++function the change was. ++ ++On the other hand, once you have shown people where to find the change, ++you need not explain its purpose in the change log. Thus, if you add a ++new function, all you need to say about it is that it is new. If you ++feel that the purpose needs explaining, it probably does---but put the ++explanation in comments in the code. It will be more useful there. ++ ++Please read the @file{ChangeLog} files in the @file{src} and ++@file{lisp} directories to see what sorts of information to put in, ++and to learn the style that we use. @xref{Change Log}. ++ ++@item ++When you write the fix, keep in mind that we can't install a change that ++would break other systems. Please think about what effect your change ++will have if compiled on another type of system. ++ ++Sometimes people send fixes that @emph{might} be an improvement in ++general---but it is hard to be sure of this. It's hard to install ++such changes because we have to study them very carefully. Of course, ++a good explanation of the reasoning by which you concluded the change ++was correct can help convince us. ++ ++The safest changes are changes to the configuration files for a ++particular machine. These are safe because they can't create new bugs ++on other machines. ++ ++Please help us keep up with the workload by designing the patch in a ++form that is clearly safe to install. ++@end itemize ++ ++@node Contributing, Service, Bugs, Top ++@section Contributing to Emacs Development ++ ++If you would like to help pretest Emacs releases to assure they work ++well, or if you would like to work on improving Emacs, please contact ++the maintainers at @email{emacs-devel@@gnu.org}. A pretester ++should be prepared to investigate bugs as well as report them. If you'd ++like to work on improving Emacs, please ask for suggested projects or ++suggest your own ideas. ++ ++If you have already written an improvement, please tell us about it. If ++you have not yet started work, it is useful to contact ++@email{emacs-devel@@gnu.org} before you start; it might be ++possible to suggest ways to make your extension fit in better with the ++rest of Emacs. ++ ++The development version of Emacs can be downloaded from the CVS ++repository where it is actively maintained by a group of developers. ++See the Emacs project page ++@url{http://savannah.gnu.org/projects/emacs/} for details. ++ ++@node Service, Copying, Contributing, Top ++@section How To Get Help with GNU Emacs ++ ++If you need help installing, using or changing GNU Emacs, there are two ++ways to find it: ++ ++@itemize @bullet ++@item ++Send a message to the mailing list ++@email{help-gnu-emacs@@gnu.org}, or post your request on ++newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup ++interconnect, so it does not matter which one you use.) ++ ++@item ++Look in the service directory for someone who might help you for a fee. ++The service directory is found in the file named @file{etc/SERVICE} in the ++Emacs distribution. ++@end itemize ++ ++@ifnottex ++@lowersections ++@end ifnottex ++ ++@ignore ++ arch-tag: c9cba76d-b2cb-4e0c-ae3f-19d5ef35817c ++@end ignore +diff --git a/doc/emacs/vc-xtra.texi b/doc/emacs/vc-xtra.texi +new file mode 100644 +index 0000000..fe6ab3b +--- /dev/null ++++ b/doc/emacs/vc-xtra.texi +@@ -0,0 +1,30 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@c This file is included in emacs-xtra.texi when producing the printed ++@c version. ++@iftex ++@node Advanced VC Usage ++@section Advanced VC Usage ++ ++ Commonly used features of Emacs' version control (VC) support are ++described in the main Emacs manual (@pxref{Version Control,,,emacs, ++the Emacs Manual}). This chapter describes more advanced VC usage. ++ ++@menu ++* Remote Repositories:: Efficient access to remote VCS servers. ++* Revision Tags:: Symbolic names for revisions. ++* Miscellaneous VC:: Various other commands and features of VC. ++* Customizing VC:: Variables that change VC's behavior. ++@end menu ++@end iftex ++ ++@iftex ++@include vc1-xtra.texi ++@end iftex ++ ++@ignore ++ arch-tag: 11a18d0e-1baf-49da-8e38-f61195ae4dc3 ++@end ignore +diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi +new file mode 100644 +index 0000000..0e9cf15 +--- /dev/null ++++ b/doc/emacs/vc1-xtra.texi +@@ -0,0 +1,793 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@c ++@c This file is included either in vc-xtra.texi (when producing the ++@c printed version) or in the main Emacs manual (for the on-line version). ++ ++@node Remote Repositories ++@subsection Remote Repositories ++@cindex remote repositories ++ ++ A common way of using CVS and other more advanced VCSes is to set up ++a central repository on some Internet host, then have each ++developer check out a personal working copy of the files on his local ++machine. Committing changes to the repository, and picking up changes ++from other users into one's own working area, then works by direct ++interactions with the repository server. ++ ++ One difficulty is that access to a repository server is often slow, ++and that developers might need to work off-line as well. While only ++third-generation decentralized VCses such as GNU Arch or Mercurial ++really solve this problem, VC is designed to reduce the amount of ++network interaction necessary. ++ ++ If you are using a truly decentralized VCS you can skip the rest of ++this section. It describes backup and local-repository techniques ++that are only useful for Subversion and earlier VCSes. ++ ++@menu ++* Version Backups:: Keeping local copies of repository versions. ++* Local Version Control:: Using another version system for local editing. ++@end menu ++ ++@node Version Backups ++@subsubsection Version Backups ++@cindex version backups ++ ++@cindex automatic version backups ++ When VC sees that the repository for a file is on a remote ++machine, it automatically makes local backups of unmodified versions ++of the file---@dfn{automatic version backups}. This means that you ++can compare the file to the repository version (@kbd{C-x v =}), or ++revert to that version (@kbd{C-x v u}), without any network ++interactions. ++ ++ The local copy of the unmodified file is called a @dfn{version ++backup} to indicate that it corresponds exactly to a version that is ++stored in the repository. Note that version backups are not the same ++as ordinary Emacs backup files ++@iftex ++(@pxref{Backup,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Backup}). ++@end ifnottex ++But they follow a similar naming convention. ++ ++ For a file that comes from a remote repository, VC makes a ++version backup whenever you save the first changes to the file, and ++removes it after you have committed your modified version to the ++repository. You can disable the making of automatic version backups by ++setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}). ++ ++@cindex manual version backups ++ The name of the automatic version backup for version @var{version} ++of file @var{file} is @code{@var{file}.~@var{version}.~}. This is ++almost the same as the name used by @kbd{C-x v ~} ++@iftex ++(@pxref{Old Revisions,,,emacs, the Emacs Manual}), ++@end iftex ++@ifnottex ++(@pxref{Old Revisions}), ++@end ifnottex ++the only difference being the additional dot (@samp{.}) after the ++version number. This similarity is intentional, because both kinds of ++files store the same kind of information. The file made by @kbd{C-x v ++~} acts as a @dfn{manual version backup}. ++ ++ All the VC commands that operate on old versions of a file can use ++both kinds of version backups. For instance, @kbd{C-x v ~} uses ++either an automatic or a manual version backup, if possible, to get ++the contents of the version you request. Likewise, @kbd{C-x v =} and ++@kbd{C-x v u} use either an automatic or a manual version backup, if ++one of them exists, to get the contents of a version to compare or ++revert to. If you changed a file outside of Emacs, so that no ++automatic version backup was created for the previous text, you can ++create a manual backup of that version using @kbd{C-x v ~}, and thus ++obtain the benefit of the local copy for Emacs commands. ++ ++ The only difference in Emacs's handling of manual and automatic ++version backups, once they exist, is that Emacs deletes automatic ++version backups when you commit to the repository. By contrast, ++manual version backups remain until you delete them. ++ ++@node Local Version Control ++@subsubsection Local Version Control ++@cindex local version control ++@cindex local back end (version control) ++ ++When you make many changes to a file that comes from a remote ++repository, it can be convenient to have version control on your local ++machine as well. You can then record intermediate versions, revert to ++a previous state, etc., before you actually commit your changes to the ++remote server. ++ ++VC lets you do this by putting a file under a second, local version ++control system, so that the file is effectively registered in two ++systems at the same time. For the description here, we will assume ++that the remote system is CVS, and you use RCS locally, although the ++mechanism works with any combination of version control systems ++(@dfn{back ends}). ++ ++To make it work with other back ends, you must make sure that the ++``more local'' back end comes before the ``more remote'' back end in ++the setting of @code{vc-handled-backends} (@pxref{Customizing VC}). By ++default, this variable is set up so that you can use remote CVS and ++local RCS as described here. ++ ++To start using local RCS for a file that comes from a remote CVS ++server, you must @emph{register the file in RCS}, by typing @kbd{C-u ++C-x v v rcs @key{RET}}. (In other words, use @code{vc-next-action} with a ++prefix argument, and specify RCS as the back end.) ++ ++You can do this at any time; it does not matter whether you have ++already modified the file with respect to the version in the CVS ++repository. If possible, VC tries to make the RCS master start with ++the unmodified repository version, then checks in any local changes ++as a new version. This works if you have not made any changes yet, or ++if the unmodified repository version exists locally as a version ++backup (@pxref{Version Backups}). If the unmodified version is not ++available locally, the RCS master starts with the modified version; ++the only drawback to this is that you cannot compare your changes ++locally to what is stored in the repository. ++ ++The version number of the RCS master is derived from the current CVS ++version, starting a branch from it. For example, if the current CVS ++version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in ++the RCS master will be identical to version 1.23 under CVS; your first ++changes are checked in as 1.23.1.1. (If the unmodified file is not ++available locally, VC will check in the modified file twice, both as ++1.23 and 1.23.1.1, to make the revision numbers consistent.) ++ ++If you do not use locking under CVS (the default), locking is also ++disabled for RCS, so that editing under RCS works exactly as under ++CVS. ++ ++When you are done with local editing, you can commit the final version ++back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}. ++This initializes the log entry buffer ++@iftex ++(@pxref{Log Buffer,,,emacs, the Emacs Manual}) ++@end iftex ++@ifnottex ++(@pxref{Log Buffer}) ++@end ifnottex ++to contain all the log entries you have recorded in the RCS master; ++you can edit them as you wish, and then commit in CVS by typing ++@kbd{C-c C-c}. If the commit is successful, VC removes the RCS ++master, so that the file is once again registered under CVS only. ++(The RCS master is not actually deleted, just renamed by appending ++@samp{~} to the name, so that you can refer to it later if you wish.) ++ ++While using local RCS, you can pick up recent changes from the CVS ++repository into your local file, or commit some of your changes back ++to CVS, without terminating local RCS version control. To do this, ++switch to the CVS back end temporarily, with the @kbd{C-x v b} command: ++ ++@table @kbd ++@item C-x v b ++Switch to another back end that the current file is registered ++under (@code{vc-switch-backend}). ++ ++@item C-u C-x v b @var{backend} @key{RET} ++Switch to @var{backend} for the current file. ++@end table ++ ++@kindex C-x v b ++@findex vc-switch-backend ++@kbd{C-x v b} does not change the buffer contents, or any files; it ++only changes VC's perspective on how to handle the file. Any ++subsequent VC commands for that file will operate on the back end that ++is currently selected. ++ ++If the current file is registered in more than one back end, typing ++@kbd{C-x v b} ``cycles'' through all of these back ends. With a ++prefix argument, it asks for the back end to use in the minibuffer. ++ ++Thus, if you are using local RCS, and you want to pick up some recent ++changes in the file from remote CVS, first visit the file, then type ++@kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m ++@key{RET}} to merge the news ++@iftex ++(@pxref{Merging,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Merging}). ++@end ifnottex ++You can then switch back to RCS by typing @kbd{C-x v b} again, and ++continue to edit locally. ++ ++But if you do this, the revision numbers in the RCS master no longer ++correspond to those of CVS. Technically, this is not a problem, but ++it can become difficult to keep track of what is in the CVS repository ++and what is not. So we suggest that you return from time to time to ++CVS-only operation, by committing your local changes back to the ++repository using @kbd{C-u C-x v v cvs @key{RET}}. ++ ++@node Revision Tags ++@subsection Revision Tags ++@cindex tags and version control ++ ++ In a VCS with per-file revision numbers (such as SCCS, RCS, or CVS) ++@dfn{tag} is a named set of file versions (one for each registered ++file) that you can treat as a unit. In a VCS with per-repository ++version numbers (Subversion and most later ones) a tag is simply ++a symbolic name for a revision. ++ ++ One important kind of tag is a @dfn{release}, a (theoretically) ++stable version of the system that is ready for distribution to users. ++ ++@menu ++* Making Revision Tags:: The tag facilities. ++* Revision Tag Caveats:: Things to be careful of when using tags. ++@end menu ++ ++@node Making Revision Tags ++@subsubsection Making and Using Revision Tags ++ ++ There are two basic commands for tags; one makes a ++tag with a given name, the other retrieves a named tag. ++ ++@table @code ++@kindex C-x v s ++@findex vc-create-tag ++@item C-x v s @var{name} @key{RET} ++Define the working revision of every registered file in or under the ++current directory as a tag named @var{name} ++(@code{vc-create-tag}). ++ ++@kindex C-x v r ++@findex vc-retrieve-tag ++@item C-x v r @var{name} @key{RET} ++For all registered files at or below the current directory level, ++retrieve the tagged revision @var{name}. This command will ++switch to a branch if @var{name} is a branch name and your VCS ++distinguishes branches from tags. ++(@code{vc-retrieve-tag}). ++ ++This command reports an error if any files are locked at or below the ++current directory, without changing anything; this is to avoid ++overwriting work in progress. ++@end table ++ ++Tags are inexpensive, so you need not hesitate to create them whenever ++they are useful. Branches vary in cost depending on your VCS; in ++older ones they may be expensive. ++ ++ You can give a tag or branch name as an argument to @kbd{C-x v =} or ++@kbd{C-x v ~} ++@iftex ++(@pxref{Old Revisions,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Old Revisions}). ++@end ifnottex ++Thus, you can use it to compare a tagged version against the current files, ++or two tagged versions against each other. ++ ++@node Revision Tag Caveats ++@subsubsection Revision Tag Caveats ++ ++ For SCCS, VC implements tags itself; these tags are visible only ++through VC. Most later systems (including CVS, Subversion, bzr, git, ++and hg) have a native tag facility, and VC uses it where ++available; those tags will be visible even when you bypass VC. ++ ++ There is no support for VC tags using GNU Arch yet. ++ ++ Under older VCSes (SCCS, RCS, CVS, early versions of Subversion), ++renaming and deletion could create some difficulties with tags. This is ++not a VC-specific problem, but a general design issue in version ++control systems that was not solved effectively until the earliest ++third-generation systems. ++ ++ In a file-oriented VCS, when you rename a registered file you need ++to rename its master along with it; the command @code{vc-rename-file} ++will do this automatically. If you are using SCCS, you must also ++update the records of the tag, to mention the file by its new name ++(@code{vc-rename-file} does this, too). An old tag that refers to a ++master file that no longer exists under the recorded name is invalid; ++VC can no longer retrieve it. It would be beyond the scope of this ++manual to explain enough about RCS and SCCS to explain how to update ++the tags by hand. ++ ++ Using @code{vc-rename-file} makes the tag remain valid for ++retrieval, but it does not solve all problems. For example, some of the ++files in your program probably refer to others by name. At the very ++least, the makefile probably mentions the file that you renamed. If you ++retrieve an old tag, the renamed file is retrieved under its new ++name, which is not the name that the makefile expects. So the program ++won't really work as retrieved. ++ ++@node Miscellaneous VC ++@subsection Miscellaneous Commands and Features of VC ++ ++ This section explains the less-frequently-used features of VC. ++ ++@menu ++* Change Logs and VC:: Generating a change log file from log entries. ++* Renaming and VC:: A command to rename both the source and master ++ file correctly. ++* Version Headers:: Inserting version control headers into working files. ++@end menu ++ ++@node Change Logs and VC ++@subsubsection Change Logs and VC ++ ++ If you use RCS or CVS for a program and also maintain a change log ++file for it ++@iftex ++(@pxref{Change Log,,,emacs, the Emacs Manual}), ++@end iftex ++@ifnottex ++(@pxref{Change Log}), ++@end ifnottex ++you can generate change log entries automatically from the version ++control log entries: ++ ++@table @kbd ++@item C-x v a ++@kindex C-x v a ++@findex vc-update-change-log ++Visit the current directory's change log file and, for registered files ++in that directory, create new entries for versions checked in since the ++most recent entry in the change log file. ++(@code{vc-update-change-log}). ++ ++This command works with RCS or CVS only, not with any of the other ++back ends. ++ ++@item C-u C-x v a ++As above, but only find entries for the current buffer's file. ++ ++@item M-1 C-x v a ++As above, but find entries for all the currently visited files that are ++maintained with version control. This works only with RCS, and it puts ++all entries in the log for the default directory, which may not be ++appropriate. ++@end table ++ ++ For example, suppose the first line of @file{ChangeLog} is dated ++1999-04-10, and that the only check-in since then was by Nathaniel ++Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log ++messages that start with `#'.}. Then @kbd{C-x v a} visits ++@file{ChangeLog} and inserts text like this: ++ ++@iftex ++@medbreak ++@end iftex ++@smallexample ++@group ++1999-05-22 Nathaniel Bowditch ++ ++ * rcs2log: Ignore log messages that start with `#'. ++@end group ++@end smallexample ++@iftex ++@medbreak ++@end iftex ++ ++@noindent ++You can then edit the new change log entry further as you wish. ++ ++ Some of the new change log entries may duplicate what's already in ++ChangeLog. You will have to remove these duplicates by hand. ++ ++ Normally, the log entry for file @file{foo} is displayed as @samp{* ++foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted ++if the text of the log entry starts with @w{@samp{(@var{functionname}): ++}}. For example, if the log entry for @file{vc.el} is ++@samp{(vc-do-command): Check call-process status.}, then the text in ++@file{ChangeLog} looks like this: ++ ++@iftex ++@medbreak ++@end iftex ++@smallexample ++@group ++1999-05-06 Nathaniel Bowditch ++ ++ * vc.el (vc-do-command): Check call-process status. ++@end group ++@end smallexample ++@iftex ++@medbreak ++@end iftex ++ ++ When @kbd{C-x v a} adds several change log entries at once, it groups ++related log entries together if they all are checked in by the same ++author at nearly the same time. If the log entries for several such ++files all have the same text, it coalesces them into a single entry. ++For example, suppose the most recent check-ins have the following log ++entries: ++ ++@flushleft ++@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} ++@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} ++@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} ++@end flushleft ++ ++@noindent ++They appear like this in @file{ChangeLog}: ++ ++@iftex ++@medbreak ++@end iftex ++@smallexample ++@group ++1999-04-01 Nathaniel Bowditch ++ ++ * vc.texinfo: Fix expansion typos. ++ ++ * vc.el, vc-hooks.el: Don't call expand-file-name. ++@end group ++@end smallexample ++@iftex ++@medbreak ++@end iftex ++ ++ Normally, @kbd{C-x v a} separates log entries by a blank line, but you ++can mark several related log entries to be clumped together (without an ++intervening blank line) by starting the text of each related log entry ++with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label ++itself is not copied to @file{ChangeLog}. For example, suppose the log ++entries are: ++ ++@flushleft ++@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} ++@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} ++@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} ++@end flushleft ++ ++@noindent ++Then the text in @file{ChangeLog} looks like this: ++ ++@iftex ++@medbreak ++@end iftex ++@smallexample ++@group ++1999-04-01 Nathaniel Bowditch ++ ++ * vc.texinfo: Fix expansion typos. ++ * vc.el, vc-hooks.el: Don't call expand-file-name. ++@end group ++@end smallexample ++@iftex ++@medbreak ++@end iftex ++ ++ A log entry whose text begins with @samp{#} is not copied to ++@file{ChangeLog}. For example, if you merely fix some misspellings in ++comments, you can log the change with an entry beginning with @samp{#} ++to avoid putting such trivia into @file{ChangeLog}. ++ ++@node Renaming and VC ++@subsubsection Renaming VC Work Files and Master Files ++ ++@findex vc-rename-file ++ When you rename a registered file, you must also rename its master ++file correspondingly to get proper results. Use @code{vc-rename-file} ++to rename the source file as you specify, and rename its master file ++accordingly. It also updates any tags (@pxref{Revision Tags}) that ++mention the file, so that they use the new name; despite this, the ++tag thus modified may not completely work (@pxref{Revision Tag Caveats}). ++ ++ Some back ends do not provide an explicit rename operation to their ++repositories. After issuing @code{vc-rename-file}, use @kbd{C-x v v} ++on the original and renamed buffers and provide the necessary edit ++log. ++ ++ You cannot use @code{vc-rename-file} on a file that is locked by ++someone else. ++ ++@node Version Headers ++@subsubsection Inserting Version Control Headers ++ ++ Sometimes it is convenient to put version identification strings ++directly into working files. Certain special strings called ++@dfn{version headers} are replaced in each successive version by the ++number of that version, the name of the user who created it, and other ++relevant information. All of the back ends that VC supports have such ++a mechanism, except GNU Arch. ++ ++ VC does not normally use the information contained in these headers. ++The exception is RCS---with RCS, version headers are sometimes more ++reliable than the master file to determine which version of the file ++you are editing. Note that in a multi-branch environment, version ++headers are necessary to make VC behave correctly ++@iftex ++(@pxref{Multi-User Branching,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++(@pxref{Multi-User Branching}). ++@end ifnottex ++ ++ Searching for RCS version headers is controlled by the variable ++@code{vc-consult-headers}. If it is non-@code{nil} (the default), ++Emacs searches for headers to determine the version number you are ++editing. Setting it to @code{nil} disables this feature. ++ ++ Note that although CVS uses the same kind of version headers as RCS ++does, VC never searches for these headers if you are using CVS, ++regardless of the above setting. ++ ++@kindex C-x v h ++@findex vc-insert-headers ++ You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to ++insert a suitable header string. ++ ++@table @kbd ++@item C-x v h ++Insert headers in a file for use with your version-control system. ++@end table ++ ++@vindex vc-@var{backend}-header ++ The default header string is @samp{@w{$}Id$} for RCS and ++@samp{@w{%}W%} for SCCS. You can specify other headers to insert by ++setting the variables @code{vc-@var{backend}-header} where ++@var{backend} is @code{rcs} or @code{sccs}. ++ ++ Instead of a single string, you can specify a list of strings; then ++each string in the list is inserted as a separate header on a line of ++its own. ++ ++ It may be necessary to use apparently-superfluous backslashes when ++writing the strings that you put in this variable. For instance, you ++might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra ++backslash prevents the string constant from being interpreted as a ++header, if the Emacs Lisp file containing it is maintained with ++version control. ++ ++@vindex vc-comment-alist ++ Each header is inserted surrounded by tabs, inside comment delimiters, ++on a new line at point. Normally the ordinary comment ++start and comment end strings of the current mode are used, but for ++certain modes, there are special comment delimiters for this purpose; ++the variable @code{vc-comment-alist} specifies them. Each element of ++this list has the form @code{(@var{mode} @var{starter} @var{ender})}. ++ ++@vindex vc-static-header-alist ++ The variable @code{vc-static-header-alist} specifies further strings ++to add based on the name of the buffer. Its value should be a list of ++elements of the form @code{(@var{regexp} . @var{format})}. Whenever ++@var{regexp} matches the buffer name, @var{format} is inserted as part ++of the header. A header line is inserted for each element that matches ++the buffer name, and for each string specified by ++@code{vc-@var{backend}-header}. The header line is made by processing the ++string from @code{vc-@var{backend}-header} with the format taken from the ++element. The default value for @code{vc-static-header-alist} is as follows: ++ ++@example ++@group ++(("\\.c$" . ++ "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ ++#endif /* lint */\n")) ++@end group ++@end example ++ ++@noindent ++It specifies insertion of text of this form: ++ ++@example ++@group ++ ++#ifndef lint ++static char vcid[] = "@var{string}"; ++#endif /* lint */ ++@end group ++@end example ++ ++@noindent ++Note that the text above starts with a blank line. ++ ++ If you use more than one version header in a file, put them close ++together in the file. The mechanism in @code{revert-buffer} that ++preserves markers may not handle markers positioned between two version ++headers. ++ ++@node Customizing VC ++@subsection Customizing VC ++ ++@vindex vc-handled-backends ++The variable @code{vc-handled-backends} determines which version ++control systems VC should handle. The default value is @code{(RCS CVS ++SVN SCCS BZR GIT HG Arch)}, so it contains all the version systems ++that are currently supported. If you want VC to ignore one or more of ++these systems, exclude its name from the list. To disable VC entirely, ++set this variable to @code{nil}. ++ ++The order of systems in the list is significant: when you visit a file ++registered in more than one system (@pxref{Local Version Control}), VC ++uses the system that comes first in @code{vc-handled-backends} by ++default. The order is also significant when you register a file for ++the first time, see ++@iftex ++@ref{Registering,,,emacs, the Emacs Manual}, ++@end iftex ++@ifnottex ++@ref{Registering}, ++@end ifnottex ++for details. ++ ++@menu ++* General VC Options:: Options that apply to multiple back ends. ++* RCS and SCCS:: Options for RCS and SCCS. ++* CVS Options:: Options for CVS. ++@end menu ++ ++@node General VC Options ++@subsubsection General Options ++ ++@vindex vc-make-backup-files ++ Emacs normally does not save backup files for source files that are ++maintained with version control. If you want to make backup files even ++for files that use version control, set the variable ++@code{vc-make-backup-files} to a non-@code{nil} value. ++ ++@vindex vc-keep-workfiles ++ Normally the work file exists all the time, whether it is locked or ++not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking ++in a new version with @kbd{C-x v v} deletes the work file; but any ++attempt to visit the file with Emacs creates it again. (With CVS, work ++files are always kept.) ++ ++@vindex vc-follow-symlinks ++ Editing a version-controlled file through a symbolic link can be ++dangerous. It bypasses the version control system---you can edit the ++file without locking it, and fail to check your changes in. Also, ++your changes might overwrite those of another user. To protect against ++this, VC checks each symbolic link that you visit, to see if it points ++to a file under version control. ++ ++ The variable @code{vc-follow-symlinks} controls what to do when a ++symbolic link points to a version-controlled file. If it is @code{nil}, ++VC only displays a warning message. If it is @code{t}, VC automatically ++follows the link, and visits the real file instead, telling you about ++this in the echo area. If the value is @code{ask} (the default), VC ++asks you each time whether to follow the link. ++ ++@vindex vc-suppress-confirm ++ If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} ++and @kbd{C-x v i} can save the current buffer without asking, and ++@kbd{C-x v u} also operates without asking for confirmation. (This ++variable does not affect @kbd{C-x v c}; that operation is so drastic ++that it should always ask for confirmation.) ++ ++@vindex vc-command-messages ++ VC mode does much of its work by running the shell commands for RCS, ++CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC ++displays messages to indicate which shell commands it runs, and ++additional messages when the commands finish. ++ ++@vindex vc-path ++ You can specify additional directories to search for version control ++programs by setting the variable @code{vc-path}. These directories ++are searched before the usual search path. It is rarely necessary to ++set this variable, because VC normally finds the proper files ++automatically. ++ ++@node RCS and SCCS ++@subsubsection Options for RCS and SCCS ++ ++@cindex non-strict locking (RCS) ++@cindex locking, non-strict (RCS) ++ By default, RCS uses locking to coordinate the activities of several ++users, but there is a mode called @dfn{non-strict locking} in which ++you can check-in changes without locking the file first. Use ++@samp{rcs -U} to switch to non-strict locking for a particular file, ++see the @code{rcs} manual page for details. ++ ++ When deducing the version control state of an RCS file, VC first ++looks for an RCS version header string in the file (@pxref{Version ++Headers}). If there is no header string, VC normally looks at the ++file permissions of the work file; this is fast. But there might be ++situations when the file permissions cannot be trusted. In this case ++the master file has to be consulted, which is rather expensive. Also ++the master file can only tell you @emph{if} there's any lock on the ++file, but not whether your work file really contains that locked ++version. ++ ++@vindex vc-consult-headers ++ You can tell VC not to use version headers to determine the file ++status by setting @code{vc-consult-headers} to @code{nil}. VC then ++always uses the file permissions (if it is supposed to trust them), or ++else checks the master file. ++ ++@vindex vc-mistrust-permissions ++ You can specify the criterion for whether to trust the file ++permissions by setting the variable @code{vc-mistrust-permissions}. ++Its value can be @code{t} (always mistrust the file permissions and ++check the master file), @code{nil} (always trust the file ++permissions), or a function of one argument which makes the decision. ++The argument is the directory name of the @file{RCS} subdirectory. A ++non-@code{nil} value from the function says to mistrust the file ++permissions. If you find that the file permissions of work files are ++changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. ++Then VC always checks the master file to determine the file's status. ++ ++ VC determines the version control state of files under SCCS much as ++with RCS. It does not consider SCCS version headers, though. Thus, ++the variable @code{vc-mistrust-permissions} affects SCCS use, but ++@code{vc-consult-headers} does not. ++ ++@node CVS Options ++@subsubsection Options specific for CVS ++ ++@cindex locking (CVS) ++ By default, CVS does not use locking to coordinate the activities of ++several users; anyone can change a work file at any time. However, ++there are ways to restrict this, resulting in behavior that resembles ++locking. ++ ++@cindex CVSREAD environment variable (CVS) ++ For one thing, you can set the @env{CVSREAD} environment variable ++(the value you use makes no difference). If this variable is defined, ++CVS makes your work files read-only by default. In Emacs, you must ++type @kbd{C-x v v} to make the file writable, so that editing works ++in fact similar as if locking was used. Note however, that no actual ++locking is performed, so several users can make their files writable ++at the same time. When setting @env{CVSREAD} for the first time, make ++sure to check out all your modules anew, so that the file protections ++are set correctly. ++ ++@cindex cvs watch feature ++@cindex watching files (CVS) ++ Another way to achieve something similar to locking is to use the ++@dfn{watch} feature of CVS. If a file is being watched, CVS makes it ++read-only by default, and you must also use @kbd{C-x v v} in Emacs to ++make it writable. VC calls @code{cvs edit} to make the file writable, ++and CVS takes care to notify other developers of the fact that you ++intend to change the file. See the CVS documentation for details on ++using the watch feature. ++ ++@vindex vc-stay-local ++@vindex vc-cvs-stay-local ++@cindex remote repositories (CVS) ++ When a file's repository is on a remote machine, VC tries to keep ++network interactions to a minimum. This is controlled by the variable ++@code{vc-cvs-stay-local}. There is another variable, ++@code{vc-stay-local}, which enables the feature also for other back ++ends that support it, including CVS. In the following, we will talk ++only about @code{vc-cvs-stay-local}, but everything applies to ++@code{vc-stay-local} as well. ++ ++If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses ++only the entry in the local CVS subdirectory to determine the file's ++state (and possibly information returned by previous CVS commands). ++One consequence of this is that when you have modified a file, and ++somebody else has already checked in other changes to the file, you ++are not notified of it until you actually try to commit. (But you can ++try to pick up any recent changes from the repository first, using ++@kbd{C-x v m @key{RET}}, ++@iftex ++@pxref{Merging,,,emacs, the Emacs Manual}). ++@end iftex ++@ifnottex ++@pxref{Merging}). ++@end ifnottex ++ ++ When @code{vc-cvs-stay-local} is @code{t}, VC also makes local ++version backups, so that simple diff and revert operations are ++completely local (@pxref{Version Backups}). ++ ++ On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil}, ++then VC queries the remote repository @emph{before} it decides what to ++do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local ++repositories. It also does not make any version backups. ++ ++ You can also set @code{vc-cvs-stay-local} to a regular expression ++that is matched against the repository host name; VC then stays local ++only for repositories from hosts that match the pattern. ++ ++@vindex vc-cvs-global-switches ++ You can specify additional command line options to pass to all CVS ++operations in the variable @code{vc-cvs-global-switches}. These ++switches are inserted immediately after the @code{cvs} command, before ++the name of the operation to invoke. ++ ++@ignore ++ arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263 ++@end ignore +diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi +new file mode 100644 +index 0000000..cda043c +--- /dev/null ++++ b/doc/emacs/windows.texi +@@ -0,0 +1,403 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node Windows, Frames, Buffers, Top ++@chapter Multiple Windows ++@cindex windows in Emacs ++@cindex multiple windows in Emacs ++ ++ Emacs can split a frame into two or many windows. Multiple windows ++can display parts of different buffers, or different parts of one ++buffer. Multiple frames always imply multiple windows, because each ++frame has its own set of windows. Each window belongs to one and only ++one frame. ++ ++@menu ++* Basic Window:: Introduction to Emacs windows. ++* Split Window:: New windows are made by splitting existing windows. ++* Other Window:: Moving to another window or doing something to it. ++* Pop Up Window:: Finding a file or buffer in another window. ++* Force Same Window:: Forcing certain buffers to appear in the selected ++ window rather than in another window. ++* Change Window:: Deleting windows and changing their sizes. ++* Window Convenience:: Convenience functions for window handling. ++@end menu ++ ++@node Basic Window ++@section Concepts of Emacs Windows ++ ++ Each Emacs window displays one Emacs buffer at any time. A single ++buffer may appear in more than one window; if it does, any changes in ++its text are displayed in all the windows where it appears. But these ++windows can show different parts of the buffer, because each window ++has its own value of point. ++ ++@cindex selected window ++ At any time, one Emacs window is the @dfn{selected window}; the ++buffer this window is displaying is the current buffer. The terminal's ++cursor shows the location of point in this window. Each other window ++has a location of point as well. On text-only terminals, there is no ++way to show where those locations are, since the terminal has only one ++cursor. On a graphical display, the location of point in a ++non-selected window is indicated by a hollow box; the cursor in the ++selected window is blinking or solid. ++ ++ Commands to move point affect the value of point for the selected Emacs ++window only. They do not change the value of point in other Emacs ++windows, even those showing the same buffer. The same is true for commands ++such as @kbd{C-x b} to switch buffers in the selected window; ++they do not affect other windows at all. However, there are other commands ++such as @kbd{C-x 4 b} that select a different window and switch buffers in ++it. Also, all commands that display information in a window, including ++(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b} ++(@code{list-buffers}), work by switching buffers in a nonselected window ++without affecting the selected window. ++ ++ When multiple windows show the same buffer, they can have different ++regions, because they can have different values of point. However, ++they all have the same value for the mark, because each buffer has ++only one mark position. ++ ++ Each window has its own mode line, which displays the buffer name, ++modification status and major and minor modes of the buffer that is ++displayed in the window. The selected window's mode line appears in a ++different color. @xref{Mode Line}, for full details on the mode line. ++ ++@node Split Window ++@section Splitting Windows ++ ++@table @kbd ++@item C-x 2 ++Split the selected window into two windows, one above the other ++(@code{split-window-vertically}). ++@item C-x 3 ++Split the selected window into two windows positioned side by side ++(@code{split-window-horizontally}). ++@item C-Mouse-2 ++In the mode line or scroll bar of a window, split that window. ++@end table ++ ++@kindex C-x 2 ++@findex split-window-vertically ++ The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the ++selected window into two windows, one above the other. Both windows start ++out displaying the same buffer, with the same value of point. By default ++the two windows each get half the height of the window that was split; a ++numeric argument specifies how many lines to give to the top window. ++ ++@kindex C-x 3 ++@findex split-window-horizontally ++ @kbd{C-x 3} (@code{split-window-horizontally}) breaks the selected ++window into two side-by-side windows. A numeric argument specifies how ++many columns to give the one on the left. If you are not using ++scrollbars, a vertical line separates the two windows. ++You can customize its color with the face @code{vertical-border}. ++Windows that are not the full width of the screen have mode lines, but ++they are truncated. On terminals where Emacs does not support ++highlighting, truncated mode lines sometimes do not appear in inverse ++video. ++ ++@kindex C-Mouse-2 @r{(scroll bar)} ++ You can split a window horizontally or vertically by clicking ++@kbd{C-Mouse-2} in the mode line or the scroll bar. The line of ++splitting goes through the place where you click: if you click on the ++mode line, the new scroll bar goes above the spot; if you click in the ++scroll bar, the mode line of the split window is side by side with ++your click. ++ ++@vindex truncate-partial-width-windows ++ When a window occupies less than the full width of the frame, it may ++become too narrow for most of the text lines in its buffer. If most of ++its lines are continued (@pxref{Continuation Lines}), the buffer may ++become difficult to read. Therefore, Emacs automatically truncates ++lines if the window width becomes narrower than 50 columns. This ++truncation occurs regardless of the value of the variable ++@code{truncate-lines} (@pxref{Line Truncation}); it is instead ++controlled by the variable @code{truncate-partial-width-windows}. If ++the value of @code{truncate-partial-width-windows} is a positive integer ++(the default is 50), that specifies the minimum width for a ++partial-width window before automatic line truncation occurs; if the ++value is @code{nil}, automatic line truncation is disabled; and for any ++other non-@code{nil} value, Emacs truncates lines in every partial-width ++window regardless of its width. ++ ++ Horizontal scrolling is often used in side-by-side windows. ++@xref{Horizontal Scrolling}. ++ ++@vindex split-window-keep-point ++ If @code{split-window-keep-point} is non-@code{nil}, the default, ++both of the windows resulting from @kbd{C-x 2} inherit the value of ++point from the window that was split. This means that scrolling is ++inevitable. If this variable is @code{nil}, then @kbd{C-x 2} tries to ++avoid scrolling the text currently visible on the screen, by putting ++point in each window at a position already visible in the window. It ++also selects whichever window contains the screen line that the cursor ++was previously on. Some users prefer that mode on slow terminals. ++ ++@node Other Window ++@section Using Other Windows ++ ++@table @kbd ++@item C-x o ++Select another window (@code{other-window}). That is @kbd{o}, not zero. ++@item C-M-v ++Scroll the next window (@code{scroll-other-window}). ++@item M-x compare-windows ++Find next place where the text in the selected window does not match ++the text in the next window. ++@item Mouse-1 ++@kbd{Mouse-1}, in a window's mode line, selects that window ++but does not move point in it (@code{mouse-select-window}). ++@end table ++ ++@kindex C-x o ++@findex other-window ++ To select a different window, click with @kbd{Mouse-1} on its mode ++line. With the keyboard, you can switch windows by typing @kbd{C-x o} ++(@code{other-window}). That is an @kbd{o}, for ``other,'' not a zero. ++When there are more than two windows, this command moves through all the ++windows in a cyclic order, generally top to bottom and left to right. ++After the rightmost and bottommost window, it goes back to the one at ++the upper left corner. A numeric argument means to move several steps ++in the cyclic order of windows. A negative argument moves around the ++cycle in the opposite order. When the minibuffer is active, the ++minibuffer is the last window in the cycle; you can switch from the ++minibuffer window to one of the other windows, and later switch back and ++finish supplying the minibuffer argument that is requested. ++@xref{Minibuffer Edit}. ++ ++@kindex C-M-v ++@findex scroll-other-window ++ The usual scrolling commands (@pxref{Display}) apply to the selected ++window only, but there is one command to scroll the next window. ++@kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that ++@kbd{C-x o} would select. It takes arguments, positive and negative, ++like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the window ++that contains the minibuffer help display, if any, rather than the ++next window in the standard cyclic order.) ++ ++ The command @kbd{M-x compare-windows} lets you compare two files or ++buffers visible in two windows, by moving through them to the next ++mismatch. @xref{Comparing Files}, for details. ++ ++@vindex mouse-autoselect-window ++ If you set @code{mouse-autoselect-window} to a non-@code{nil} value, ++moving the mouse into a different window selects that window. This ++feature is off by default. ++ ++@node Pop Up Window ++@section Displaying in Another Window ++ ++@cindex selecting buffers in other windows ++@kindex C-x 4 ++ @kbd{C-x 4} is a prefix key for commands that select another window ++(splitting the window if there is only one) and select a buffer in that ++window. Different @kbd{C-x 4} commands have different ways of finding the ++buffer to select. ++ ++@table @kbd ++@item C-x 4 b @var{bufname} @key{RET} ++Select buffer @var{bufname} in another window. This runs ++@code{switch-to-buffer-other-window}. ++@item C-x 4 C-o @var{bufname} @key{RET} ++Display buffer @var{bufname} in another window, but ++don't select that buffer or that window. This runs ++@code{display-buffer}. ++@item C-x 4 f @var{filename} @key{RET} ++Visit file @var{filename} and select its buffer in another window. This ++runs @code{find-file-other-window}. @xref{Visiting}. ++@item C-x 4 d @var{directory} @key{RET} ++Select a Dired buffer for directory @var{directory} in another window. ++This runs @code{dired-other-window}. @xref{Dired}. ++@item C-x 4 m ++Start composing a mail message in another window. This runs ++@code{mail-other-window}; its same-window analogue is @kbd{C-x m} ++(@pxref{Sending Mail}). ++@item C-x 4 . ++Find a tag in the current tags table, in another window. This runs ++@code{find-tag-other-window}, the multiple-window variant of @kbd{M-.} ++(@pxref{Tags}). ++@item C-x 4 r @var{filename} @key{RET} ++Visit file @var{filename} read-only, and select its buffer in another ++window. This runs @code{find-file-read-only-other-window}. ++@xref{Visiting}. ++@end table ++ ++@vindex split-height-threshold ++@vindex split-width-threshold ++ By default, these commands split the window vertically when there is ++only one. You can customize the variables @code{split-height-threshold} ++and @code{split-width-threshold} to split the window horizontally ++instead. ++ ++ ++@node Force Same Window ++@section Forcing Display in the Same Window ++ ++ Certain Emacs commands switch to a specific buffer with special ++contents. For example, @kbd{M-x shell} switches to a buffer named ++@samp{*shell*}. By convention, all these commands are written to pop up ++the buffer in a separate window. But you can specify that certain of ++these buffers should appear in the selected window. ++ ++@vindex same-window-buffer-names ++ If you add a buffer name to the list @code{same-window-buffer-names}, ++the effect is that such commands display that particular buffer by ++switching to it in the selected window. For example, if you add the ++element @code{"*grep*"} to the list, the @code{grep} command will ++display its output buffer in the selected window. ++ ++ The default value of @code{same-window-buffer-names} is not ++@code{nil}: it specifies buffer names @samp{*info*}, @samp{*mail*} and ++@samp{*shell*} (as well as others used by more obscure Emacs packages). ++This is why @kbd{M-x shell} normally switches to the @samp{*shell*} ++buffer in the selected window. If you delete this element from the ++value of @code{same-window-buffer-names}, the behavior of @kbd{M-x ++shell} will change---it will pop up the buffer in another window ++instead. ++ ++@vindex same-window-regexps ++ You can specify these buffers more generally with the variable ++@code{same-window-regexps}. Set it to a list of regular expressions; ++then any buffer whose name matches one of those regular expressions is ++displayed by switching to it in the selected window. (Once again, this ++applies only to buffers that normally get displayed for you in a ++separate window.) The default value of this variable specifies Telnet ++and rlogin buffers. ++ ++ An analogous feature lets you specify buffers which should be ++displayed in their own individual frames. @xref{Special Buffer Frames}. ++ ++@node Change Window ++@section Deleting and Rearranging Windows ++ ++@table @kbd ++@item C-x 0 ++Delete the selected window (@code{delete-window}). The last character ++in this key sequence is a zero. ++@item C-x 1 ++Delete all windows in the selected frame except the selected window ++(@code{delete-other-windows}). ++@item C-x 4 0 ++Delete the selected window and kill the buffer that was showing in it ++(@code{kill-buffer-and-window}). The last character in this key ++sequence is a zero. ++@item C-x ^ ++Make selected window taller (@code{enlarge-window}). ++@item C-x @} ++Make selected window wider (@code{enlarge-window-horizontally}). ++@item C-x @{ ++Make selected window narrower (@code{shrink-window-horizontally}). ++@item C-x - ++Shrink this window if its buffer doesn't need so many lines ++(@code{shrink-window-if-larger-than-buffer}). ++@item C-x + ++Make all windows the same height (@code{balance-windows}). ++@end table ++ ++@kindex C-x 0 ++@findex delete-window ++ To delete a window, type @kbd{C-x 0} (@code{delete-window}). (That is ++a zero.) The space occupied by the deleted window is given to an ++adjacent window (but not the minibuffer window, even if that is active ++at the time). Once a window is deleted, its attributes are forgotten; ++only restoring a window configuration can bring it back. Deleting the ++window has no effect on the buffer it used to display; the buffer ++continues to exist, and you can select it in any window with @kbd{C-x ++b}. ++ ++@findex kill-buffer-and-window ++@kindex C-x 4 0 ++ @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command ++than @kbd{C-x 0}; it kills the current buffer and then deletes the ++selected window. ++ ++@kindex C-x 1 ++@findex delete-other-windows ++ @kbd{C-x 1} (@code{delete-other-windows}) is more powerful in a ++different way; it deletes all the windows except the selected one (and ++the minibuffer); the selected window expands to use the whole frame ++except for the echo area. ++ ++@kindex C-x ^ ++@findex enlarge-window ++@kindex C-x @} ++@findex enlarge-window-horizontally ++@vindex window-min-height ++@vindex window-min-width ++ To readjust the division of space among vertically adjacent windows, ++use @kbd{C-x ^} (@code{enlarge-window}). It makes the currently ++selected window one line bigger, or as many lines as is specified ++with a numeric argument. With a negative argument, it makes the ++selected window smaller. @kbd{C-x @}} ++(@code{enlarge-window-horizontally}) makes the selected window wider by ++the specified number of columns. @kbd{C-x @{} ++(@code{shrink-window-horizontally}) makes the selected window narrower ++by the specified number of columns. ++ ++ When you make a window bigger, the space comes from its peers. If ++this makes any window too small, it is deleted and its space is given ++to an adjacent window. The minimum size is specified by the variables ++@code{window-min-height} and @code{window-min-width}. ++ ++@kindex C-x - ++@findex shrink-window-if-larger-than-buffer ++ The command @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) ++reduces the height of the selected window, if it is taller than ++necessary to show the whole text of the buffer it is displaying. It ++gives the extra lines to other windows in the frame. ++ ++@kindex C-x + ++@findex balance-windows ++ You can also use @kbd{C-x +} (@code{balance-windows}) to even out the ++heights of all the windows in the selected frame. ++ ++ Mouse clicks on the mode line provide another way to change window ++heights and to delete windows. @xref{Mode Line Mouse}. ++ ++@node Window Convenience ++@section Window Handling Convenience Features and Customization ++ ++@findex winner-mode ++@cindex Winner mode ++@cindex mode, Winner ++@cindex undoing window configuration changes ++@cindex window configuration changes, undoing ++ @kbd{M-x winner-mode} is a global minor mode that records the ++changes in the window configuration (i.e. how the frames are ++partitioned into windows), so that you can ``undo'' them. To undo, ++use @kbd{C-c left} (@code{winner-undo}). If you change your mind ++while undoing, you can redo the changes you had undone using @kbd{C-c ++right} (@code{M-x winner-redo}). Another way to enable Winner mode is ++by customizing the variable @code{winner-mode}. ++ ++@cindex Windmove package ++@cindex directional window selection ++@findex windmove-right ++@findex windmove-default-keybindings ++ The Windmove commands move directionally between neighboring windows in ++a frame. @kbd{M-x windmove-right} selects the window immediately to the ++right of the currently selected one, and similarly for the ``left,'' ``up,'' ++and ``down'' counterparts. @kbd{M-x windmove-default-keybindings} binds ++these commands to @kbd{S-right} etc. (Not all terminals support shifted ++arrow keys, however.) ++ ++ Follow minor mode (@kbd{M-x follow-mode}) synchronizes several ++windows on the same buffer so that they always display adjacent ++sections of that buffer. @xref{Follow Mode}. ++ ++@vindex scroll-all-mode ++@cindex scrolling windows together ++@cindex Scroll-all mode ++@cindex mode, Scroll-all ++ @kbd{M-x scroll-all-mode} provides commands to scroll all visible ++windows together. You can also turn it on by customizing the variable ++@code{scroll-all-mode}. The commands provided are @kbd{M-x ++scroll-all-scroll-down-all}, @kbd{M-x scroll-all-page-down-all} and ++their corresponding ``up'' equivalents. To make this mode useful, ++you should bind these commands to appropriate keys. ++ ++@ignore ++ arch-tag: 8bea7453-d4b1-49b1-9bf4-cfe4383e1113 ++@end ignore +diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi +new file mode 100644 +index 0000000..a2deb15 +--- /dev/null ++++ b/doc/emacs/xresources.texi +@@ -0,0 +1,1195 @@ ++@c This is part of the Emacs manual. ++@c Copyright (C) 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, ++@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See file emacs.texi for copying conditions. ++@node X Resources, Antinews, Emacs Invocation, Top ++@appendix X Options and Resources ++ ++ You can customize some X-related aspects of Emacs behavior using X ++resources, as is usual for programs that use X. On MS-Windows, you ++can customize some of the same aspects using the system registry. ++@xref{MS-Windows Registry}. ++ ++ When Emacs is built using an ``X toolkit'', such as Lucid or ++LessTif, you need to use X resources to customize the appearance of ++the widgets, including the menu-bar, scroll-bar, and dialog boxes. ++This is because the libraries that implement these don't provide for ++customization through Emacs. GTK+ widgets use a separate system of ++@ifnottex ++``GTK resources'', which we will also describe. ++@end ifnottex ++@iftex ++``GTK resources.'' In this chapter we describe the most commonly used ++resource specifications. For full documentation, see the online ++manual. ++ ++@c Add xref for LessTif/Motif menu resources. ++@end iftex ++ ++ ++@menu ++* Resources:: Using X resources with Emacs (in general). ++* Table of Resources:: Table of specific X resources that affect Emacs. ++* Face Resources:: X resources for customizing faces. ++* Lucid Resources:: X resources for Lucid menus. ++* LessTif Resources:: X resources for LessTif and Motif menus. ++* GTK resources:: Resources for GTK widgets. ++@end menu ++ ++@node Resources ++@appendixsec X Resources ++@cindex resources ++@cindex X resources ++@cindex @file{~/.Xdefaults} file ++@cindex @file{~/.Xresources} file ++ ++ Programs running under the X Window System organize their user ++options under a hierarchy of classes and resources. You can specify ++default values for these options in your @dfn{X resource file}, ++usually named @file{~/.Xdefaults} or @file{~/.Xresources}. Changes in ++this file do not take effect immediately, because the X server stores ++its own list of resources; to update it, use the command ++@command{xrdb}---for instance, @samp{xrdb ~/.Xdefaults}. ++ ++@cindex Registry (MS-Windows) ++ (MS-Windows systems do not support X resource files; on Windows, ++Emacs looks for X resources in the Windows Registry, first under the ++key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} and then under the key ++@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}. The menu and scroll ++bars are native widgets on MS-Windows, so they are only customizable ++via the system-wide settings in the Display Control Panel. You can ++also set resources using the @samp{-xrm} command line option, as ++explained below.) ++ ++ Each line in the X resource file specifies a value for one option or ++for a collection of related options. Each resource specification ++consists of a @dfn{program name} and a @dfn{resource name}. Case ++distinctions are significant in each of these names. Here is an ++example: ++ ++@example ++emacs.borderWidth: 2 ++@end example ++ ++@ifnottex ++ The program name is the name of the executable file to which the ++resource applies. For Emacs, this is normally @samp{emacs}. To ++specify a definition that applies to all instances of Emacs, ++regardless of the name of the Emacs executable, use @samp{Emacs}. ++ ++ The resource name is the name of a program setting. For instance, ++Emacs recognizes a @samp{borderWidth} resource that controls the width ++of the external border for graphical frames. ++ ++ Resources are grouped into named classes. For instance, the ++@samp{BorderWidth} class contains both the @samp{borderWidth} resource ++(which we just described), as well as the @samp{internalBorder} ++resource, which controls the width of the internal border for ++graphical frames. Instead of using a resource name, you can use a ++class name to specify the same value for all resources in that class. ++Here's an example: ++ ++@example ++emacs.BorderWidth: 2 ++@end example ++ ++ If you specify a value for a class, it becomes the default for all ++resources in that class. You can specify values for individual ++resources as well; these override the class value, for those ++particular resources. The following example specifies 2 as the ++default width for all borders, but overrides this value with 4 for the ++external border: ++ ++@example ++emacs.BorderWidth: 2 ++emacs.borderWidth: 4 ++@end example ++@end ifnottex ++ ++ The order in which the lines appear in the file does not matter. ++Also, command-line options always override the X resources file. ++ ++@ifnottex ++ The following X command-line options affect how X resources are ++processed: ++ ++@table @samp ++@item -name @var{name} ++@opindex --name ++@itemx --name=@var{name} ++@cindex resource name, command-line argument ++This option sets the program name of the initial Emacs frame to ++@var{name}. It also sets the title of the initial frame to ++@var{name}. This option does not affect subsequent frames. ++ ++If you don't specify this option, the default is to use the Emacs ++executable's name as the program name. ++ ++For consistency, @samp{-name} also specifies the name to use for other ++resource values that do not belong to any particular frame. ++ ++The resources that name Emacs invocations also belong to a class, ++named @samp{Emacs}. If you write @samp{Emacs} instead of ++@samp{emacs}, the resource applies to all frames in all Emacs jobs, ++regardless of frame titles and regardless of the name of the ++executable file. ++ ++@item -xrm @var{resource-values} ++@opindex --xrm ++@itemx --xrm=@var{resource-values} ++@cindex resource values, command-line argument ++This option specifies X resource values for the present Emacs job. ++ ++@var{resource-values} should have the same format that you would use ++inside a file of X resources. To include multiple resource ++specifications in @var{resource-values}, put a newline between them, ++just as you would in a file. You can also use @samp{#include ++"@var{filename}"} to include a file full of resource specifications. ++Resource values specified with @samp{-xrm} take precedence over all ++other resource specifications. ++@end table ++@end ifnottex ++ ++ One way to experiment with the effect of different resource settings ++is to use the @code{editres} program. See the @code{editres} man page ++for more details. ++ ++@node Table of Resources ++@appendixsec Table of X Resources for Emacs ++ ++ This table lists the resource names that designate options for ++Emacs, not counting those for the appearance of the menu bar, each ++with the class that it belongs to: ++ ++@table @asis ++@item @code{background} (class @code{Background}) ++Background color name. ++ ++@ifnottex ++@item @code{bitmapIcon} (class @code{BitmapIcon}) ++Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window ++manager choose an icon if @samp{off}. ++@end ifnottex ++ ++@item @code{borderColor} (class @code{BorderColor}) ++Color name for the external border. ++ ++@ifnottex ++@item @code{borderWidth} (class @code{BorderWidth}) ++Width in pixels of the external border. ++@end ifnottex ++ ++@item @code{cursorColor} (class @code{Foreground}) ++Color name for text cursor (point). ++ ++@ifnottex ++@item @code{cursorBlink} (class @code{CursorBlink}) ++Specifies whether to make the cursor blink. The default is @samp{on}. Use ++@samp{off} or @samp{false} to turn cursor blinking off. ++@end ifnottex ++ ++@item @code{font} (class @code{Font}) ++Font name for the @code{default} font. @xref{Font X}. You can also ++specify a fontset name (@pxref{Fontsets}). ++ ++@item @code{fontBackend} (class @code{FontBackend}) ++The backend(s) to use for drawing fonts; if multiple backends are ++specified, they must be comma-delimited and given in order of ++precedence. On X, for instance, the value @samp{x,xft} tells Emacs to ++draw fonts using the X core font driver, falling back on the Xft font ++driver if that fails. Normally, you can leave this resource unset, in ++which case Emacs tries using all font backends available on your ++graphical device. ++ ++@item @code{foreground} (class @code{Foreground}) ++Color name for text. ++ ++@item @code{geometry} (class @code{Geometry}) ++Window size and position. Be careful not to specify this resource as ++@samp{emacs*geometry}, because that may affect individual menus as well ++as the Emacs frame itself. ++ ++If this resource specifies a position, that position applies only to the ++initial Emacs frame (or, in the case of a resource for a specific frame ++name, only that frame). However, the size, if specified here, applies to ++all frames. ++ ++@ifnottex ++@item @code{fullscreen} (class @code{Fullscreen}) ++The desired fullscreen size. The value can be one of @code{fullboth}, ++@code{fullwidth} or @code{fullheight}, which correspond to ++the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh} ++(@pxref{Window Size X}). ++ ++Note that this applies to the initial frame only. ++@end ifnottex ++ ++@item @code{iconName} (class @code{Title}) ++Name to display in the icon. ++ ++@item @code{internalBorder} (class @code{BorderWidth}) ++Width in pixels of the internal border. ++ ++@item @code{lineSpacing} (class @code{LineSpacing}) ++@cindex line spacing ++@cindex leading ++Additional space (@dfn{leading}) between lines, in pixels. ++ ++@item @code{menuBar} (class @code{MenuBar}) ++@cindex menu bar ++Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}. ++@ifnottex ++@xref{Lucid Resources}, and @ref{LessTif Resources}, ++@end ifnottex ++@iftex ++@xref{Lucid Resources}, ++@end iftex ++for how to control the appearance of the menu bar if you have one. ++ ++@ifnottex ++@item @code{minibuffer} (class @code{Minibuffer}) ++If @samp{none}, don't make a minibuffer in this frame. ++It will use a separate minibuffer frame instead. ++ ++@item @code{paneFont} (class @code{Font}) ++@cindex font for menus ++Font name for menu pane titles, in non-toolkit versions of Emacs. ++@end ifnottex ++ ++@item @code{pointerColor} (class @code{Foreground}) ++Color of the mouse cursor. ++ ++@ifnottex ++@item @code{privateColormap} (class @code{PrivateColormap}) ++If @samp{on}, use a private color map, in the case where the ``default ++visual'' of class PseudoColor and Emacs is using it. ++ ++@item @code{reverseVideo} (class @code{ReverseVideo}) ++Switch foreground and background default colors if @samp{on}, use colors as ++specified if @samp{off}. ++@end ifnottex ++ ++@item @code{screenGamma} (class @code{ScreenGamma}) ++@cindex gamma correction ++Gamma correction for colors, equivalent to the frame parameter ++@code{screen-gamma}. ++ ++@item @code{scrollBarWidth} (class @code{ScrollBarWidth}) ++@cindex scrollbar width ++The scroll bar width in pixels, equivalent to the frame parameter ++@code{scroll-bar-width}. ++ ++@ifnottex ++@item @code{selectionFont} (class @code{SelectionFont}) ++Font name for pop-up menu items, in non-toolkit versions of Emacs. (For ++toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif ++Resources}.) ++ ++@item @code{selectionTimeout} (class @code{SelectionTimeout}) ++Number of milliseconds to wait for a selection reply. ++If the selection owner doesn't reply in this time, we give up. ++A value of 0 means wait as long as necessary. ++ ++@item @code{synchronous} (class @code{Synchronous}) ++@cindex debugging X problems ++@cindex synchronous X mode ++Run Emacs in synchronous mode if @samp{on}. Synchronous mode is ++useful for debugging X problems. ++@end ifnottex ++ ++@item @code{title} (class @code{Title}) ++Name to display in the title bar of the initial Emacs frame. ++ ++@item @code{toolBar} (class @code{ToolBar}) ++@cindex tool bar ++Number of lines to reserve for the tool bar. A zero value suppresses ++the tool bar. If the value is non-zero and ++@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size ++will be changed automatically so that all tool bar items are visible. ++ If the value of @code{auto-resize-tool-bars} is @code{grow-only}, ++the tool bar expands automatically, but does not contract automatically. ++To contract the tool bar, you must redraw the frame by entering @kbd{C-l}. ++ ++@item @code{useXIM} (class @code{UseXIM}) ++@cindex XIM ++@cindex X input methods ++@cindex input methods, X ++Turn off use of X input methods (XIM) if @samp{false} or @samp{off}. ++This is only relevant if your Emacs is actually built with XIM ++support. It is potentially useful to turn off XIM for efficiency, ++especially slow X client/server links. ++ ++@item @code{verticalScrollBars} (class @code{ScrollBars}) ++Give frames scroll bars if @samp{on}; don't have scroll bars if ++@samp{off}. ++ ++@ifnottex ++@item @code{visualClass} (class @code{VisualClass}) ++Specify the ``visual'' that X should use. This tells X how to handle ++colors. ++ ++The value should start with one of @samp{TrueColor}, ++@samp{PseudoColor}, @samp{DirectColor}, @samp{StaticColor}, ++@samp{GrayScale}, and @samp{StaticGray}, followed by ++@samp{-@var{depth}}, where @var{depth} is the number of color planes. ++Most terminals only allow a few ``visuals,'' and the @samp{dpyinfo} ++program outputs information saying which ones. ++@end ifnottex ++@end table ++ ++@node Face Resources ++@appendixsec X Resources for Faces ++ ++ You can use resources to customize the appearance of particular ++faces (@pxref{Faces}): ++ ++@table @code ++@item @var{face}.attributeForeground ++Foreground color for face @var{face}. ++@item @var{face}.attributeBackground ++Background color for face @var{face}. ++@item @var{face}.attributeUnderline ++Underline flag for face @var{face}. Use @samp{on} or @samp{true} for ++yes. ++@item @var{face}.attributeStrikeThrough ++@itemx @var{face}.attributeOverline ++@itemx @var{face}.attributeBox ++@itemx @var{face}.attributeInverse ++Likewise, for other boolean font attributes. ++@item @var{face}.attributeStipple ++The name of a pixmap data file to use for the stipple pattern, or ++@code{false} to not use stipple for the face @var{face}. ++@item @var{face}.attributeBackgroundPixmap ++The background pixmap for the face @var{face}. Should be a name of a ++pixmap file or @code{false}. ++@item @var{face}.attributeFont ++Font name (full XFD name or valid X abbreviation) for face @var{face}. ++Instead of this, you can specify the font through separate attributes. ++@end table ++ ++ Instead of using @code{attributeFont} to specify a font name, you can ++select a font through these separate attributes: ++ ++@table @code ++@item @var{face}.attributeFamily ++Font family for face @var{face}. ++@item @var{face}.attributeHeight ++Height of the font to use for face @var{face}: either an integer ++specifying the height in units of 1/10@dmn{pt}, or a floating point ++number that specifies a scale factor to scale the underlying face's ++default font, or a function to be called with the default height which ++will return a new height. ++@item @var{face}.attributeWidth ++@itemx @var{face}.attributeWeight ++@itemx @var{face}.attributeSlant ++Each of these resources corresponds to a like-named font attribute, ++and you write the resource value the same as the symbol you would use ++for the font attribute value. ++@item @var{face}.attributeBold ++Bold flag for face @var{face}---instead of @code{attributeWeight}. Use @samp{on} or @samp{true} for ++yes. ++@item @var{face}.attributeItalic ++Italic flag for face @var{face}---instead of @code{attributeSlant}. ++@end table ++ ++@node Lucid Resources ++@appendixsec Lucid Menu X Resources ++@cindex Menu X Resources (Lucid widgets) ++@cindex Lucid Widget X Resources ++ ++@ifnottex ++ If the Emacs installed at your site was built to use the X toolkit ++with the Lucid menu widgets, then the menu bar is a separate widget and ++has its own resources. The resource names contain @samp{pane.menubar} ++(following, as always, the name of the Emacs invocation, or @samp{Emacs}, ++which stands for all Emacs invocations). Specify them like this: ++ ++@example ++Emacs.pane.menubar.@var{resource}: @var{value} ++@end example ++ ++@noindent ++For example, to specify the font @samp{8x16} for the menu-bar items, ++write this: ++@end ifnottex ++@iftex ++ If the Emacs installed at your site was built to use the X toolkit ++with the Lucid menu widgets, then the menu bar is a separate widget ++and has its own resources. The resource specifications start with ++@samp{Emacs.pane.menubar}---for instance, to specify the font ++@samp{8x16} for the menu-bar items, write this: ++@end iftex ++ ++@example ++Emacs.pane.menubar.font: 8x16 ++@end example ++ ++@noindent ++Resources for @emph{non-menubar} toolkit pop-up menus have ++@samp{menu*} instead of @samp{pane.menubar}. For example, to specify ++the font @samp{8x16} for the pop-up menu items, write this: ++ ++@example ++Emacs.menu*.font: 8x16 ++@end example ++ ++@noindent ++For dialog boxes, use @samp{dialog*}: ++ ++@example ++Emacs.dialog*.font: 8x16 ++@end example ++ ++@noindent ++The Lucid menus can display multilingual text in your locale. For ++more information about fontsets see the man page for ++@code{XCreateFontSet}. To enable multilingual menu text you specify a ++@code{fontSet} resource instead of the font resource. If both ++@code{font} and @code{fontSet} resources are specified, the ++@code{fontSet} resource is used. ++ ++ Thus, to specify @samp{-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*} ++for both the popup and menu bar menus, write this: ++ ++@example ++Emacs*menu*fontSet: -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,* ++@end example ++ ++@noindent ++The @samp{*menu*} as a wildcard matches @samp{pane.menubar} and ++@samp{menu@dots{}}. ++ ++Experience shows that on some systems you may need to add ++@samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On ++some other systems, you must not add @samp{shell.}. The generic wildcard ++approach should work on both kinds of systems. ++ ++ Here is a list of the specific resources for menu bars and pop-up menus: ++ ++@table @code ++@item font ++Font for menu item text. ++@item fontSet ++Fontset for menu item text. ++@item foreground ++Color of the foreground. ++@item background ++Color of the background. ++@item buttonForeground ++In the menu bar, the color of the foreground for a selected item. ++@ifnottex ++@item horizontalSpacing ++Horizontal spacing in pixels between items. Default is 3. ++@item verticalSpacing ++Vertical spacing in pixels between items. Default is 2. ++@item arrowSpacing ++Horizontal spacing between the arrow (which indicates a submenu) and ++the associated text. Default is 10. ++@item shadowThickness ++Thickness of shadow line around the widget. Default is 1. ++ ++Also determines the thickness of shadow lines around other objects, ++for instance 3D buttons and arrows. If you have the impression that ++the arrows in the menus do not stand out clearly enough or that the ++difference between ``in'' and ``out'' buttons is difficult to see, set ++this to 2. If you have no problems with visibility, the default ++probably looks better. The background color may also have some effect ++on the contrast. ++@end ifnottex ++@item margin ++The margin of the menu bar, in characters. Default is 1. ++@end table ++ ++@ifnottex ++@node LessTif Resources ++@appendixsec LessTif Menu X Resources ++@cindex Menu X Resources (LessTif widgets) ++@cindex LessTif Widget X Resources ++ ++ If the Emacs installed at your site was built to use the X toolkit ++with the LessTif or Motif widgets, then the menu bar, the dialog ++boxes, the pop-up menus, and the file-selection box are separate ++widgets and have their own resources. ++ ++ The resource names for the menu bar contain @samp{pane.menubar} ++(following, as always, the name of the Emacs invocation, or ++@samp{Emacs}, which stands for all Emacs invocations). Specify them ++like this: ++ ++@smallexample ++Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value} ++@end smallexample ++ ++ Each individual string in the menu bar is a subwidget; the subwidget's ++name is the same as the menu item string. For example, the word ++@samp{File} in the menu bar is part of a subwidget named ++@samp{emacs.pane.menubar.File}. Most likely, you want to specify the ++same resources for the whole menu bar. To do this, use @samp{*} instead ++of a specific subwidget name. For example, to specify the font ++@samp{8x16} for the menu-bar items, write this: ++ ++@smallexample ++Emacs.pane.menubar.*.fontList: 8x16 ++@end smallexample ++ ++@noindent ++This also specifies the resource value for submenus. ++ ++ Each item in a submenu in the menu bar also has its own name for X ++resources; for example, the @samp{File} submenu has an item named ++@samp{Save (current buffer)}. A resource specification for a submenu ++item looks like this: ++ ++@smallexample ++Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value} ++@end smallexample ++ ++@noindent ++For example, here's how to specify the font for the @samp{Save (current ++buffer)} item: ++ ++@smallexample ++Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16 ++@end smallexample ++ ++@noindent ++For an item in a second-level submenu, such as @samp{Complete Word} ++under @samp{Spell Checking} under @samp{Tools}, the resource fits this ++template: ++ ++@smallexample ++Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value} ++@end smallexample ++ ++@noindent ++For example, ++ ++@smallexample ++Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value} ++@end smallexample ++ ++@noindent ++(This should be one long line.) ++ ++ It's impossible to specify a resource for all the menu-bar items ++without also specifying it for the submenus as well. So if you want the ++submenu items to look different from the menu bar itself, you must ask ++for that in two steps. First, specify the resource for all of them; ++then, override the value for submenus alone. Here is an example: ++ ++@smallexample ++Emacs.pane.menubar.*.fontList: 8x16 ++Emacs.pane.menubar.popup_*.fontList: 8x16 ++@end smallexample ++ ++@noindent ++For LessTif pop-up menus, use @samp{menu*} instead of ++@samp{pane.menubar}. For example, to specify the font @samp{8x16} for ++the pop-up menu items, write this: ++ ++@smallexample ++Emacs.menu*.fontList: 8x16 ++@end smallexample ++ ++@noindent ++For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}: ++ ++@example ++Emacs.dialog*.fontList: 8x16 ++Emacs.dialog*.foreground: hotpink ++@end example ++ ++To specify resources for the LessTif file-selection box, use ++@samp{fsb*}, like this: ++ ++@example ++Emacs.fsb*.fontList: 8x16 ++@end example ++ ++@iftex ++@medbreak ++@end iftex ++ Here is a list of the specific resources for LessTif menu bars and ++pop-up menus: ++ ++@table @code ++@item armColor ++The color to show in an armed button. ++@item fontList ++The font to use. ++@item marginBottom ++@itemx marginHeight ++@itemx marginLeft ++@itemx marginRight ++@itemx marginTop ++@itemx marginWidth ++Amount of space to leave around the item, within the border. ++@item borderWidth ++The width of the border around the menu item, on all sides. ++@item shadowThickness ++The width of the border shadow. ++@item bottomShadowColor ++The color for the border shadow, on the bottom and the right. ++@item topShadowColor ++The color for the border shadow, on the top and the left. ++@end table ++@end ifnottex ++ ++ ++@node GTK resources ++@appendixsec GTK resources ++@iftex ++ The most common way to customize the GTK widgets Emacs uses (menus, dialogs ++tool bars and scroll bars) is by choosing an appropriate theme, for example ++with the GNOME theme selector. You can also do Emacs specific customization ++by inserting GTK style directives in the file @file{~/.emacs.d/gtkrc}. Some GTK ++themes ignore customizations in @file{~/.emacs.d/gtkrc} so not everything ++works with all themes. To customize Emacs font, background, faces, etc., use ++the normal X resources (@pxref{Resources}). We will present some examples of ++customizations here, but for a more detailed description, see the online manual ++ ++ The first example is just one line. It changes the font on all GTK widgets ++to courier with size 12: ++ ++@smallexample ++gtk-font-name = "courier 12" ++@end smallexample ++ ++ The thing to note is that the font name is not an X font name, like ++-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*, but a Pango font name. A Pango ++font name is basically of the format "family style size", where the style ++is optional as in the case above. A name with a style could be for example: ++ ++@smallexample ++gtk-font-name = "helvetica bold 10" ++@end smallexample ++ ++ To customize widgets you first define a style and then apply the style to ++the widgets. Here is an example that sets the font for menus, but not ++for other widgets: ++ ++@smallexample ++# @r{Define the style @samp{menufont}.} ++style "menufont" ++@{ ++ font_name = "helvetica bold 14" # This is a Pango font name ++@} ++ ++# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.} ++widget "*emacs-menuitem*" style "menufont" ++@end smallexample ++ ++The widget name in this example contains wildcards, so the style will be ++applied to all widgets that match "*emacs-menuitem*". The widgets are ++named by the way they are contained, from the outer widget to the inner widget. ++So to apply the style "my_style" (not shown) with the full, absolute name, for ++the menubar and the scroll bar in Emacs we use: ++ ++@smallexample ++widget "Emacs.pane.menubar" style "my_style" ++widget "Emacs.pane.emacs.verticalScrollBar" style "my_style" ++@end smallexample ++ ++But to avoid having to type it all, wildcards are often used. @samp{*} ++matches zero or more characters and @samp{?} matches one character. So "*" ++matches all widgets. ++ ++ Each widget has a class (for example GtkMenuItem) and a name (emacs-menuitem). ++You can assign styles by name or by class. In this example we have used the ++class: ++ ++@smallexample ++style "menufont" ++@{ ++ font_name = "helvetica bold 14" ++@} ++ ++widget_class "*GtkMenuBar" style "menufont" ++@end smallexample ++ ++@noindent ++The names and classes for the GTK widgets Emacs uses are: ++ ++@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some} ++@item @code{emacs-filedialog} ++@tab @code{GtkFileSelection} ++@item @code{emacs-dialog} ++@tab @code{GtkDialog} ++@item @code{Emacs} ++@tab @code{GtkWindow} ++@item @code{pane} ++@tab @code{GtkVHbox} ++@item @code{emacs} ++@tab @code{GtkFixed} ++@item @code{verticalScrollBar} ++@tab @code{GtkVScrollbar} ++@item @code{emacs-toolbar} ++@tab @code{GtkToolbar} ++@item @code{menubar} ++@tab @code{GtkMenuBar} ++@item @code{emacs-menuitem} ++@tab anything in menus ++@end multitable ++ ++ GTK absolute names are quite strange when it comes to menus ++and dialogs. The names do not start with @samp{Emacs}, as they are ++free-standing windows and not contained (in the GTK sense) by the ++Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this: ++ ++@smallexample ++widget "*emacs-dialog*" style "my_dialog_style" ++widget "*emacs-filedialog* style "my_file_style" ++widget "*emacs-menuitem* style "my_menu_style" ++@end smallexample ++ ++ If you specify a customization in @file{~/.emacs.d/gtkrc}, then it ++automatically applies only to Emacs, since other programs don't read ++that file. For example, the drop down menu in the file dialog can not ++be customized by any absolute widget name, only by an absolute class ++name. This is because the widgets in the drop down menu do not ++have names and the menu is not contained in the Emacs GtkWindow. To ++have all menus in Emacs look the same, use this in ++@file{~/.emacs.d/gtkrc}: ++ ++@smallexample ++widget_class "*Menu*" style "my_menu_style" ++@end smallexample ++ ++ Here is a more elaborate example, showing how to change the parts of ++the scroll bar: ++ ++@smallexample ++style "scroll" ++@{ ++ fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.} ++ bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.} ++ bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.} ++ bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.} ++@} ++ ++widget "*verticalScrollBar*" style "scroll" ++@end smallexample ++@end iftex ++ ++@ifnottex ++@cindex GTK resources and customization ++@cindex resource files for GTK ++@cindex @file{~/.gtkrc-2.0} file ++@cindex @file{~/.emacs.d/gtkrc} file ++ ++ If Emacs was built to use the GTK widget set, then the menu bar, tool bar, ++scroll bar and the dialogs are customized with the standard GTK ++customization file, @file{~/.gtkrc-2.0}, or with the Emacs specific ++file @file{~/.emacs.d/gtkrc}. We recommend that you use ++@file{~/.emacs.d/gtkrc} for customizations, since @file{~/.gtkrc-2.0} ++seems to be ignored when running GConf with GNOME. These files apply ++only to GTK widget features. To customize Emacs font, background, ++faces, etc., use the normal X resources (@pxref{Resources}). ++ ++ Some GTK themes override these mechanisms, which means that using ++these mechanisms will not work to customize them. ++ ++ In these files you first define a style and say what it means; then ++you specify to apply the style to various widget types (@pxref{GTK ++widget names}). Here is an example of how to change the font for ++Emacs menus: ++ ++@smallexample ++# @r{Define the style @samp{menufont}.} ++style "menufont" ++@{ ++ font_name = "helvetica bold 14" # This is a Pango font name ++@} ++ ++# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.} ++widget "*emacs-menuitem*" style "menufont" ++@end smallexample ++ ++ Here is a more elaborate example, showing how to change the parts of ++the scroll bar: ++ ++@smallexample ++style "scroll" ++@{ ++ fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.} ++ bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.} ++ bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.} ++ bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.} ++@} ++ ++widget "*verticalScrollBar*" style "scroll" ++@end smallexample ++ ++ There are also parameters that affect GTK as a whole. For example, ++the property @code{gtk-font-name} sets the default font for GTK. You ++must use Pango font names (@pxref{GTK styles}). A GTK resources file ++that just sets a default font looks like this: ++ ++@smallexample ++gtk-font-name = "courier 12" ++@end smallexample ++ ++ The GTK resources file is fully described in the GTK API document. ++This can be found in ++@file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html}, ++where @file{prefix} is the directory in which the GTK libraries were ++installed (usually @file{/usr} or @file{/usr/local}). You can also ++find the document online, at ++@uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}. ++ ++@menu ++* GTK widget names:: How widgets in GTK are named in general. ++* GTK Names in Emacs:: GTK widget names in Emacs. ++* GTK styles:: What can be customized in a GTK widget. ++@end menu ++ ++@node GTK widget names ++@appendixsubsec GTK widget names ++@cindex GTK widget names ++ ++ A GTK widget is specified by its @dfn{widget class} and ++@dfn{widget name}. The widget class is the type of the widget: for ++example, @code{GtkMenuBar}. The widget name is the name given to a ++specific widget. A widget always has a class, but need not have a ++name. ++ ++ @dfn{Absolute names} are sequences of widget names or widget ++classes, corresponding to hierarchies of widgets embedded within ++other widgets. For example, if a @code{GtkWindow} named @code{top} ++contains a @code{GtkVBox} named @code{box}, which in turn contains ++a @code{GtkMenuBar} called @code{menubar}, the absolute class name ++of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and ++its absolute widget name is @code{top.box.menubar}. ++ ++ When assigning a style to a widget, you can use the absolute class ++name or the absolute widget name. ++ ++ There are two commands to specify changes for widgets: ++ ++@table @asis ++@item @code{widget_class} ++specifies a style for widgets based on the absolute class name. ++ ++@item @code{widget} ++specifies a style for widgets based on the absolute class name, ++or just the class. ++@end table ++ ++@noindent ++You must specify the class and the style in double-quotes, and put ++these commands at the top level in the GTK customization file, like ++this: ++ ++@smallexample ++style "menufont" ++@{ ++ font_name = "helvetica bold 14" ++@} ++ ++widget "top.box.menubar" style "menufont" ++widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont" ++@end smallexample ++ ++ Matching of absolute names uses shell wildcard syntax: @samp{*} ++matches zero or more characters and @samp{?} matches one character. ++This example assigns @code{base_style} to all widgets: ++ ++@smallexample ++widget "*" style "base_style" ++@end smallexample ++ ++ Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar} ++and the corresponding absolute widget name @code{top.box.menubar}, all ++these examples specify @code{my_style} for the menu bar: ++ ++@smallexample ++widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style" ++widget_class "GtkWindow.*.GtkMenuBar" style "my_style" ++widget_class "*GtkMenuBar" style "my_style" ++widget "top.box.menubar" style "my_style" ++widget "*box*menubar" style "my_style" ++widget "*menubar" style "my_style" ++widget "*menu*" style "my_style" ++@end smallexample ++ ++@node GTK Names in Emacs ++@appendixsubsec GTK Widget Names in Emacs ++@cindex GTK widget names ++@cindex GTK widget classes ++ ++ In Emacs, the top level widget for a frame is a @code{GtkWindow} ++that contains a @code{GtkVBox}. The @code{GtkVBox} contains the ++@code{GtkMenuBar} and a @code{GtkFixed} widget. The vertical scroll ++bars, @code{GtkVScrollbar}, are contained in the @code{GtkFixed} ++widget. The text you write in Emacs is drawn in the @code{GtkFixed} ++widget. ++ ++ Dialogs in Emacs are @code{GtkDialog} widgets. The file dialog is a ++@code{GtkFileSelection} widget. ++ ++@noindent ++To set a style for the menu bar using the absolute class name, use: ++ ++@smallexample ++widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style" ++@end smallexample ++ ++@noindent ++For the scroll bar, the absolute class name is: ++ ++@smallexample ++widget_class ++ "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" ++ style "my_style" ++@end smallexample ++ ++@noindent ++The names for the emacs widgets, and their classes, are: ++ ++@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some} ++@item @code{emacs-filedialog} ++@tab @code{GtkFileSelection} ++@item @code{emacs-dialog} ++@tab @code{GtkDialog} ++@item @code{Emacs} ++@tab @code{GtkWindow} ++@item @code{pane} ++@tab @code{GtkVHbox} ++@item @code{emacs} ++@tab @code{GtkFixed} ++@item @code{verticalScrollBar} ++@tab @code{GtkVScrollbar} ++@item @code{emacs-toolbar} ++@tab @code{GtkToolbar} ++@item @code{menubar} ++@tab @code{GtkMenuBar} ++@item @code{emacs-menuitem} ++@tab anything in menus ++@end multitable ++ ++@noindent ++Thus, for Emacs you can write the two examples above as: ++ ++@smallexample ++widget "Emacs.pane.menubar" style "my_style" ++widget "Emacs.pane.emacs.verticalScrollBar" style "my_style" ++@end smallexample ++ ++ GTK absolute names are quite strange when it comes to menus ++and dialogs. The names do not start with @samp{Emacs}, as they are ++free-standing windows and not contained (in the GTK sense) by the ++Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this: ++ ++@smallexample ++widget "*emacs-dialog*" style "my_dialog_style" ++widget "*emacs-filedialog* style "my_file_style" ++widget "*emacs-menuitem* style "my_menu_style" ++@end smallexample ++ ++ If you specify a customization in @file{~/.emacs.d/gtkrc}, then it ++automatically applies only to Emacs, since other programs don't read ++that file. For example, the drop down menu in the file dialog can not ++be customized by any absolute widget name, only by an absolute class ++name. This is because the widgets in the drop down menu do not ++have names and the menu is not contained in the Emacs GtkWindow. To ++have all menus in Emacs look the same, use this in ++@file{~/.emacs.d/gtkrc}: ++ ++@smallexample ++widget_class "*Menu*" style "my_menu_style" ++@end smallexample ++ ++@node GTK styles ++@appendixsubsec GTK styles ++@cindex GTK styles ++ ++ In a GTK style you specify the appearance widgets shall have. You ++can specify foreground and background color, background pixmap and ++font. The edit widget (where you edit the text) in Emacs is a GTK ++widget, but trying to specify a style for the edit widget will have no ++effect. This is so that Emacs compiled for GTK is compatible with ++Emacs compiled for other X toolkits. The settings for foreground, ++background and font for the edit widget is taken from the X resources; ++@pxref{Resources}. Here is an example of two style declarations, ++@samp{default} and @samp{ruler}: ++ ++@smallexample ++pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" ++ ++style "default" ++@{ ++ font_name = "helvetica 12" ++ ++ bg[NORMAL] = @{ 0.83, 0.80, 0.73 @} ++ bg[SELECTED] = @{ 0.0, 0.55, 0.55 @} ++ bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @} ++ bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @} ++ bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @} ++ ++ fg[NORMAL] = "black" ++ fg[SELECTED] = @{ 0.9, 0.9, 0.9 @} ++ fg[ACTIVE] = "black" ++ fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @} ++ ++ base[INSENSITIVE] = "#777766" ++ text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @} ++ ++ bg_pixmap[NORMAL] = "background.xpm" ++ bg_pixmap[INSENSITIVE] = "background.xpm" ++ bg_pixmap[ACTIVE] = "background.xpm" ++ bg_pixmap[PRELIGHT] = "" ++ ++@} ++ ++style "ruler" = "default" ++@{ ++ font_name = "helvetica 8" ++@} ++ ++@end smallexample ++ ++ The style @samp{ruler} inherits from @samp{default}. This way you can build ++on existing styles. The syntax for fonts and colors is described below. ++ ++ As this example shows, it is possible to specify several values for ++foreground and background depending on the widget's @dfn{state}. The ++possible states are: ++ ++@table @code ++@item NORMAL ++This is the default state for widgets. ++@item ACTIVE ++This is the state for a widget that is ready to do something. It is ++also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"} ++sets the scroll bar trough to red. Buttons that have been pressed but ++not released yet (``armed'') are in this state. ++@item PRELIGHT ++This is the state for a widget that can be manipulated, when the mouse ++pointer is over it---for example when the mouse is over the thumb in ++the scroll bar or over a menu item. When the mouse is over a button ++that is not pressed, the button is in this state. ++@item SELECTED ++This is the state for data that has been selected by the user. It can ++be selected text or items selected in a list. This state is not used ++in Emacs. ++@item INSENSITIVE ++This is the state for widgets that are visible, but they can not be ++manipulated in the usual way---for example, buttons that can't be ++pressed, and disabled menu items. To display disabled menu items in ++yellow, use @code{fg[INSENSITIVE] = "yellow"}. ++@end table ++ ++ Here are the things that can go in a style declaration: ++ ++@table @code ++@item bg[@var{state}] = @var{color} ++This specifies the background color for the widget. Note that ++editable text doesn't use @code{bg}; it uses @code{base} instead. ++ ++@item base[@var{state}] = @var{color} ++This specifies the background color for editable text. In Emacs, this ++color is used for the background of the text fields in the file ++dialog. ++ ++@item bg_pixmap[@var{state}] = "@var{pixmap}" ++This specifies an image background (instead of a background color). ++@var{pixmap} should be the image file name. GTK can use a number of ++image file formats, including XPM, XBM, GIF, JPEG and PNG. If you ++want a widget to use the same image as its parent, use ++@samp{}. If you don't want any image, use @samp{}. ++@samp{} is the way to cancel a background image inherited from a ++parent style. ++ ++You can't specify the file by its absolute file name. GTK looks for ++the pixmap file in directories specified in @code{pixmap_path}. ++@code{pixmap_path} is a colon-separated list of directories within ++double quotes, specified at the top level in a @file{gtkrc} file ++(i.e. not inside a style definition; see example above): ++ ++@smallexample ++pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" ++@end smallexample ++ ++@item fg[@var{state}] = @var{color} ++This specifies the foreground color for widgets to use. It is the ++color of text in menus and buttons, and the color for the arrows in ++the scroll bar. For editable text, use @code{text}. ++ ++@item text[@var{state}] = @var{color} ++This is the color for editable text. In Emacs, this color is used for the ++text fields in the file dialog. ++ ++@item font_name = "@var{font}" ++This specifies the font for text in the widget. @var{font} is a ++Pango font name, for example @samp{Sans Italic 10}, @samp{Helvetica ++Bold 12}, @samp{Courier 14}, @samp{Times 18}. See below for exact ++syntax. The names are case insensitive. ++@end table ++ ++ There are three ways to specify a color: by name, in hexadecimal ++form, and with an RGB triplet. ++ ++@noindent ++A color name is written within double quotes, for example @code{"red"}. ++ ++@noindent ++Hexadecimal form is the same as in X: ++@code{#@var{rrrr}@var{gggg}@var{bbbb}}, where all three color specs ++must have the same number of hex digits (1, 2, 3 or 4). ++ ++@noindent ++An RGB triplet looks like @code{@{ @var{r}, @var{g}, @var{b} @}}, ++where @var{r}, @var{g} and @var{b} are either integers in the range ++0-65535 or floats in the range 0.0-1.0. ++ ++ Pango font names have the form ``@var{family-list} @var{style-options} ++@var{size}.'' ++@cindex Pango font name ++@noindent ++@var{family-list} is a comma separated list of font families optionally ++terminated by a comma. This way you can specify several families and the ++first one found will be used. @var{family} corresponds to the second part in ++an X font name, for example in ++ ++@smallexample ++-adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1 ++@end smallexample ++ ++@noindent ++the family name is @samp{times}. ++ ++@noindent ++@var{style-options} is a whitespace separated list of words where each word ++is a style, variant, weight, or stretch. The default value for all of ++these is @code{normal}. ++ ++@noindent ++A `style' corresponds to the fourth part of an X font name. In X font ++names it is the character @samp{r}, @samp{i} or @samp{o}; in Pango ++font names the corresponding values are @code{normal}, @code{italic}, ++or @code{oblique}. ++ ++@noindent ++A `variant' is either @code{normal} or @code{small-caps}. ++Small caps is a font with the lower case characters replaced by ++smaller variants of the capital characters. ++ ++@noindent ++Weight describes the ``boldness'' of a font. It corresponds to the third ++part of an X font name. It is one of @code{ultra-light}, @code{light}, ++@code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}. ++ ++@noindent ++Stretch gives the width of the font relative to other designs within a ++family. It corresponds to the fifth part of an X font name. It is one of ++@code{ultra-condensed}, @code{extra-condensed}, @code{condensed}, ++@code{semi-condensed}, @code{normal}, @code{semi-expanded}, ++@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}. ++ ++@noindent ++@var{size} is a decimal number that describes the font size in points. ++@end ifnottex ++ ++@ignore ++ arch-tag: 9b6ff773-48b6-41f6-b2f9-f114b8bdd97f ++@end ignore +diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog +new file mode 100644 +index 0000000..83d9f4b +--- /dev/null ++++ b/doc/lispintro/ChangeLog +@@ -0,0 +1,356 @@ ++2009-07-29 Chong Yidong ++ ++ * Version 23.1 released. ++ ++2009-07-28 Chong Yidong ++ ++ * emacs-lisp-intro.texi (Simple Extension): Bump emacs versions in ++ examples. ++ ++2009-07-10 Glenn Morris ++ ++ * emacs-lisp-intro.texi (Top): Add missing @detailmenu entry. ++ ++2009-07-09 Glenn Morris ++ ++ * Makefile.in (texinfodir): Rename from usermanualdir, and update. ++ ++2009-07-06 Glenn Morris ++ ++ * emacs-lisp-intro.texi (defvar and asterisk): Minor rephrasing. ++ ++2009-06-14 Chong Yidong ++ ++ * emacs-lisp-intro.texi (edebug): Fix typo. ++ ++2009-02-22 Karl Berry ++ ++ * emacs-lisp-intro.texi (Default Configuration): fix dup word "by by". ++ ++2009-02-20 Juanma Barranquero ++ ++ * emacs-lisp-intro.texi (current-kill, Code for current-kill) ++ (Body of current-kill): Remove duplicate words. ++ ++2008-11-19 Glenn Morris ++ ++ * doclicense.texi: New file. ++ * emacs-lisp-intro.texi: Relicense under FDL 1.3 or later. ++ Include doclicense.texi rather than having license in the file itself. ++ ++2008-10-16 Sean Sieger (tiny change) ++ ++ * emacs-lisp-intro.texi (Recursion with list): Fix typo. ++ ++2008-10-04 Karl Berry ++ ++ * emacs-lisp-intro.texi: Apply similar formatting changes as for ++ the emacs and lispref manuals, to save pages. A couple minor ++ rewordings and reformatting of code to avoid overfull and ++ underfull lines. ++ (edition-number): Bump to 3.08. ++ (update-date): Bump to 4 October 2008. ++ ++2008-06-20 Eli Zaretskii ++ ++ * makefile.w32-in (distclean): Remove makefile. ++ ++2008-06-16 Glenn Morris ++ ++ * Makefile.am, Makefile.old, aclocal.m4, configure, configure.in: ++ * install-sh, missing, mkinstalldirs: Remove obsolete files. ++ ++2008-05-13 Chong Yidong ++ ++ * emacs-lisp-intro.texi (Lisp Atoms): Rephrase "in addition" to ++ avoid confusion with addition operation discussed in previous ++ paragraph. ++ ++2008-01-31 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Update back cover text. ++ ++2007-09-12 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Add email address to Thank You correctly. ++ ++2007-09-06 Romain Francoise ++ ++ * Makefile.in (maintainer-clean): Delete info files. ++ ++2007-09-06 Glenn Morris ++ ++ Move from lispintro/ to doc/lispintro/. ++ * Makefile.in (infodir): Go up one more level. ++ (usermanualdir): Change from ../man to ../emacs. ++ * makefile.w32-in (infodir, ENVADD): Go up one more level. ++ * emacs-lisp-intro.texi (setfilename): Go up one more level. ++ ++2007-07-30 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Fix typo on line 5173, change `thee' to ++ `these'. ++ ++2007-07-25 Glenn Morris ++ ++ * Relicense all FSF files to GPLv3 or later. ++ ++2007-06-02 Chong Yidong ++ ++ * Version 22.1 released. ++ ++2007-01-30 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi (else): Rephrase message of first ++ if-then-else example so it is right both in itself and in the ++ "true" case of the expression, which asks whether 4 is greater ++ than 5. ++ ++2006-11-27 Andreas Schwab ++ ++ * Makefile.in (usermanualdir): Define. ++ (emacs-lisp-intro.dvi): Pass -I options to texi2dvi instead of ++ using TEXINPUTS. ++ ++ * emacs-lisp-intro.texi: Input texinfo instead of ../man/texinfo ++ to fix building outside source directory. ++ ++2006-11-09 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Copy descriptions from detailed master ++ menu to menus within body. ++ ++ * emacs-lisp-intro.texi (at the beginning): Add `other shell ++ commands' to produce additional output formats; total is now ten. ++ (A Loop with an Incrementing Counter, and others): Ensure Info ++ menus will appear in short windows. ++ (Disentangle beginning-of-buffer): Replace `version 21' with `more ++ recent versions'. ++ (Simple Extension): Show how to handle multiple versions by adding ++ an alternative with a test of `>= 21'. ++ ++2006-11-06 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Finish minor changes seen from DVI output. ++ Replace 22.1.100 with 22.1.1. ++ (current-kill): Mention functions that directly or indirectly call ++ `kill-new', which sets `kill-ring-yank-pointer'. ++ (Understanding current-kill): Change `lasted' to `last'. Remove ++ extraneous parenthesis. Reword item about returning `car' of list. ++ (yank): Remove mention of `rotate-yank-pointer'. ++ (Y Axis Element): Add comment regarding replacement of blank space. ++ (print-Y-axis Penultimate): Explain that `print-graph' will pass ++ `height-of-top-line' so `print-Y-axis' does not have a bug. ++ ++2006-11-05 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Yet more minor changes: ++ (defcustom): Said that `:options' is usually for a hook. Remove ++ extraneous space in parenthetical remark concerning ++ `text-mode-hook-identify'. At end, mention other defines, too. ++ (Beginning a .emacs File): Reverse words about comments so they ++ parallel numbers of listed semi-colons. ++ (Text and Auto-fill): Remove extraneous blank line in example. ++ (Mail Aliases): Remove extraneous blank line in example. ++ (Keybindings): Reformat as needed with `key' rather than `kbd'. ++ (Keybindings, Miscellaneous, Mode Line): For small book format, start ++ section name on top of new page. ++ (Simple Extension): Replace longer expression with ++ `emacs-major-version'. Remove comment about `number-to-string' ++ function. ++ (Miscellaneous): Add filename option, `-H', to `grep' example ++ (debug, debug-on-entry): Replace `GNU Emacs 22' with `a recent ++ GNU Emacs'. ++ (edebug): More properly state where to place point for 'M-x ++ edebug-defun'. ++ ++ * emacs-lisp-intro.texi: More minor changes. ++ Center images for TeX output. ++ (kill-new function): Remove indentation for sentence talking about ++ momentarily skipping code. ++ (cons & search-fwd Review): Document @code{funcall}. Document ++ @code{re-search-forward} with existing @code{search-forward}. ++ Reference chapter on regular expression searches. ++ (Recursion with list): Specify a more recent version as being Emacs. ++ (Recursion with list, Every, recursive-graph-body-print): Change ++ `if ... progn' expression to `when'. ++ (Recursive triangle function): For printing in small book, ensure ++ section name is not last on bottom of preceding page. ++ (Keep): Remove extraneous space in function definition example. ++ (sentence-end): Specify `in English' for glyphs that end a sentence. ++ Note that in GNU Emacs 22, the name refers to both a variable and a ++ function. ++ (fwd-sentence while loops): Write a function as one, not as a form ++ (fwd-para let): Add `which' to sentence with `parstart' and `parsep'. ++ (etags): Move sentences involving `find-tag' and sources. State ++ location of Emacs `src' directory. ++ (Design count-words-region): Better explain two backslashes in a row. ++ (Find a File): Fix grammar; add a `to' and write `to visit'. Change ++ `named' to `selected'. ++ (lengths-list-file): Remove extraneous parenthesis from reference. ++ (lengths-list-many-files): Explain `expand-file-name' better. ++ (Files List): Rephrase sentence regarding Lisp sources directory ++ ++2006-11-04 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Replace 22.0.100 with 22.1.100. ++ (defcustom): Note that the value set by defconst is a variable. ++ (Buffer Size & Locations): Parenthetical remark about evaluation. ++ (Finding More): Change text to include C sources by inference. ++ ++ * emacs-lisp-intro.texi: Minor fixes. ++ Replace all tabs with eight spaces each so printed text looks correct. ++ Remove extraneous comma in a printed node name produced by `ref'. ++ (insert-buffer): Add a missing beginning parenthesis. ++ (beginning-of-buffer): Add `beginning of' to note about accessible ++ portion. ++ (narrow Exercise): Write closing parenthesis at end of correct ++ paragraph. ++ (zap-to-char): Remove extraneous `a' from first sentence. ++ (Complete zap-to-char): Remove two extraneous sentences. ++ (zap-to-char body): Move sentences on documentation two nodes earlier. ++ (Lisp macro): Add definition of `unless' macro. ++ (last-command & this-command): Remove comment that `we have not yet ++ seen' the @code{eq} function. ++ (kill-append function): Reformat `kill-append' function definition so ++ it prints well. ++ (kill-new function): Indent the sentence beginning `notice'. Replace ++ `the same as' with `similar to'. Repair typo. Remove obsolete ++ references to `yank' and `yank-pop. End section with a note that `we ++ will digress into C.' ++ ++2006-11-02 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi (kill-ring-yank-pointer): Revert addition ++ of extraneous quotation mark to rotate-yank-pointer. ++ ++2006-11-01 Juri Linkov ++ ++ * emacs-lisp-intro.texi: Fix unbalanced quotes. ++ ++2006-10-31 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Revised text for kill-region, ++ copy-region-as-kill, kill-append, kill-new, forward-sentence, ++ forward-paragraph, find-file, current-kill, yank, and yank-pop. ++ Removed INSTALL MANIFEST from the directory since those files are ++ now irrelevant. Updated Info file in ../info. Changed numbering ++ so is now Revised Third Edition and this instance's edition-number ++ is 3.00. Did not update ISBN number. ++ ++ * emacs-lisp-intro.texi: Remove version reference for X colors. ++ Document `='. Remove mention that :eval was new in 21. Updated ++ instance's edition-number to 3.01. ++ ++2006-10-30 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Many changes since it turned out that ++ many `simple' functions were rewritten. Changes to the text ++ regarding zap-to-char, mark-whole-buffer, append-to-buffer, ++ copy-to-buffer, beginning-of-buffer, what-line, and possibly ++ others. (I have not reviewed all yet.) This instance does build ++ for Info and TeX. ++ ++2006-10-29 Chong Yidong ++ ++ * Makefile.in: Use relative paths to avoid advertising filesystem ++ contents during compilation. ++ ++2006-08-21 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Deleted in directory copy of texinfo.tex ++ and pointed towards ../man/texinfo.tex so only one file ++ needs updating. Added comment of what to do when building on own. ++ ++ * texinfo.tex: Changed to version 2006-02-13.16 ++ to enable a DVI build using the more recent versions of TeX. ++ ++2006-05-25 David Kastrup ++ ++ * emacs-lisp-intro.texi (setcar): Replace an antelope rather than ++ a giraffe with a hippopotamus. ++ ++2006-05-19 Thien-Thi Nguyen ++ ++ * emacs-lisp-intro.texi (Digression concerning error): Fix typo. ++ ++2005-09-16 Romain Francoise ++ ++ * emacs-lisp-intro.texi (GNU Free Documentation License): ++ Specify GFDL version 1.2. ++ ++2005-07-30 Eli Zaretskii ++ ++ * makefile.w32-in (info): Don't run install-info. ++ ($(infodir)/dir): New target, produced by running install-info. ++ ++2005-07-04 Lute Kamstra ++ ++ Update FSF's address in GPL notices. ++ ++ * emacs-lisp-intro.texi: Update FSF's address. ++ ++2004-04-23 Juanma Barranquero ++ ++ * makefile.w32-in: Add "-*- makefile -*-" mode tag. ++ ++2004-02-29 Juanma Barranquero ++ ++ * makefile.w32-in (mostlyclean, clean, maintainer-clean): ++ Use $(DEL) instead of rm, and ignore exit code. ++ ++2003-11-16 Kevin Ryde ++ ++ * emacs-lisp-intro.texi: [CVS commitment by ] ++ Corrections to cross references, ++ (Interactive Options): elisp "interactive" -> "Using Interactive". ++ (defvar and asterisk): Remove emacs "Edit Options" reference, ++ edit-options is no longer described in the emacs manual. ++ (Lists diagrammed): elisp "List Type" -> "Cons Cell Type". ++ ++2003-09-03 Peter Runestig ++ ++ * makefile.w32-in: New file. ++ ++2001-11-29 Eli Zaretskii ++ ++ * emacs-lisp-intro.texi (Index): @ignore extraneous text. ++ Use @dircategory and @direntry to define the DIR entry. ++ ++2001-11-25 Robert J. Chassell ++ ++ * emacs-lisp-intro.texi: Move @contents to the beginning of the ++ file. Set the size to @smallbook. ++ ++2001-11-24 Eli Zaretskii ++ ++ * Makefile.in: New file. ++ ++ * README: Update. ++ ++ * *.eps: Rename to avoid clashes in DOS 8+3 namespace. ++ ++;; Local Variables: ++;; coding: utf-8 ++;; add-log-time-zone-rule: t ++;; End: ++ ++ Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, ++ 2008, 2009 Free Software Foundation, Inc. ++ ++ This file is part of GNU Emacs. ++ ++ GNU Emacs 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. ++ ++ GNU Emacs 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 GNU Emacs. If not, see . ++ ++;;; arch-tag: ee4f8e1f-e14c-4d2e-86de-4dd697e6f1c3 +diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in +new file mode 100644 +index 0000000..151cf2f +--- /dev/null ++++ b/doc/lispintro/Makefile.in +@@ -0,0 +1,73 @@ ++#### Makefile for the Emacs Lisp Introduction manual ++ ++# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, ++# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++ ++# This file is part of GNU Emacs. ++ ++# GNU Emacs 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. ++ ++# GNU Emacs 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 GNU Emacs. If not, see . ++ ++ ++SHELL = @SHELL@ ++ ++srcdir = @srcdir@ ++VPATH = @srcdir@ ++ ++infodir = ../../info ++# Directory with the (customized) texinfo.tex file. ++texinfodir = $(srcdir)/../misc ++ ++INFO_SOURCES = ${srcdir}/emacs-lisp-intro.texi ++# The file name eintr must fit within 5 characters, to allow for ++# -NN extensions to fit into DOS 8+3 limits without clashing ++INFO_TARGETS = ${infodir}/eintr ++DVI_TARGETS = emacs-lisp-intro.dvi ++ ++MAKEINFO = makeinfo ++TEXI2DVI = texi2dvi ++DVIPS = dvips ++ ++.SUFFIXES: .dvi .ps .texi ++ ++info: $(INFO_TARGETS) ++ ++dvi: $(DVI_TARGETS) ++ ++${infodir}/eintr: ${INFO_SOURCES} ++ cd $(srcdir); $(MAKEINFO) emacs-lisp-intro.texi -o $(infodir)/eintr ++ ++emacs-lisp-intro.dvi: ${INFO_SOURCES} ++ $(TEXI2DVI) -I $(srcdir) -I $(texinfodir) $(srcdir)/emacs-lisp-intro.texi ++ ++emacs-lisp-intro.html: $(INFO_SOURCES) ++ $(MAKEINFO) --html -o $@ $(srcdir)/emacs-lisp-intro.texi ++ ++.dvi.ps: ++ $(DVIPS) $< -o $@ ++ ++mostlyclean: ++ rm -f *.log *.cp *.fn *.ky *.pg *.vr *.tp ++ ++clean: mostlyclean ++ rm -f *.dvi ++ ++distclean: clean ++ ++maintainer-clean: distclean ++ rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc ++ cd $(infodir); rm -f eintr eintr-[1-9] ++ ++# 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/doc/lispintro/README b/doc/lispintro/README +new file mode 100644 +index 0000000..40187ca +--- /dev/null ++++ b/doc/lispintro/README +@@ -0,0 +1,73 @@ ++Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++ Free Software Foundation, Inc. ++See the end of the file for license conditions. ++ ++ ++This directory contains the source of the "Introduction to Programming ++in Emacs Lisp" written by Robert J. Chassell, bob@gnu.org. This ++manual is an elementary introduction to programming in Emacs Lisp for ++people who are not programmers, and who are not necessarily interested ++in programming, but who do want to customize or extend their computing ++environment. ++ ++This third edition of 2006 Oct 31 updates the previous editions to GNU ++Emacs 22. ++ ++The Texinfo source file `emacs-lisp-intro.texi', formats without ++reported error using `pdfeTeXk', Version 3.141592-1.21a-2.2 (Web2C ++7.5.4) and texinfo.tex version 2006-08-26.17 started by `texi2dvi' ++version 4.8, and with `makeinfo' version 4.8. ++ ++This directory contains the following Encapsulated PostScript figures: ++ ++ cons-1.eps, cons-2.eps, cons-2a.eps, cons-3.eps, cons-4.eps, cons-5.eps ++ drawers.eps, lambda-1.eps, lambda-2.eps, lambda-3.eps ++ ++See the beginning of the `emacs-lisp-intro.texi' file for appropriate ++settings. These figures are not necessary; they are merely nice to ++look at --- without them you get the same figures printed with ASCII ++characters. ++ ++Whether and how you print PostScript depends on your site. You not ++only need to set 'print-postscript-figures' before creating the .dvi ++file, but then must convert the .dvi file to .ps with a 'dvips' or ++equivalent command. ++ ++On some systems you will see an error message when `psfig.tex' is ++loaded for the last two .eps files: ++ ++ ! No room for a new \write . ++ ++If this happens, try `epsf.tex' instead of `psfig.tex', or try typing ++RET at the error; the formatting may continue successfully. ++ ++Or else find the section that says: ++ ++ @c !!! Clear print-postscript-figures if the computer formatting this ++ @c document is too small and cannot handle all the diagrams and figures. ++ @c clear print-postscript-figures ++ ++and change the file so it reads: @clear print-postscript-figures ++This will prevent TeX from attempting to load the last few .eps files. ++ ++You will find additional instructions on formatting in the beginning ++of the Texinfo file 'emacs-lisp-intro.texi'. Best Wishes! ++ ++2006 Oct 31 ++Robert J. Chassell, bob@gnu.org ++ ++ ++This file is part of GNU Emacs. ++ ++GNU Emacs 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. ++ ++GNU Emacs 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 GNU Emacs. If not, see . +diff --git a/doc/lispintro/cons-1.eps b/doc/lispintro/cons-1.eps +new file mode 100644 +index 0000000..76e00db +--- /dev/null ++++ b/doc/lispintro/cons-1.eps +@@ -0,0 +1,582 @@ ++%! ++%%BoundingBox: 35 711 289 757 ++%%Title: cons-cell-diagram1 ++%%CreationDate: Wed Mar 8 14:26:58 1995 ++%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++% ++% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 ++% ++ ++% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 132 dict def ++tgifdict begin ++ ++% ++% Using a zero value radius for an ellipse or an arc would result ++% in a non-invertible CTM matrix which causes problem when this ++% when this PostScript is wrapped inside other routines, such as ++% the multi.ps package from ++% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such ++% error by uncommenting the sole line of the procedure below: ++% ++/tgif_min_radius ++ { ++% dup 0.01 lt { pop 0.01 } if ++ } bind def ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarrowtipdict 8 dict def ++tgifarrowtipdict /mtrx matrix put ++ ++/tgifarrowtip ++ { tgifarrowtipdict begin ++ /dy exch def ++ /dx exch def ++ /h exch def ++ /w exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ dy dx atan rotate ++ 0 0 moveto ++ w neg h lineto ++ w neg h neg lineto ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarcdict 8 dict def ++tgifarcdict /mtrx matrix put ++ ++/tgifarcn ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarc ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arcn ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifsetuserscreendict 22 dict def ++tgifsetuserscreendict begin ++ /tempctm matrix def ++ /temprot matrix def ++ /tempscale matrix def ++ ++ /concatprocs ++ { /proc2 exch cvlit def ++ /proc1 exch cvlit def ++ /newproc proc1 length proc2 length add array def ++ newproc 0 proc1 putinterval ++ newproc proc1 length proc2 putinterval ++ newproc cvx ++ } def ++ /resmatrix matrix def ++ /findresolution ++ { 72 0 resmatrix defaultmatrix dtransform ++ /yres exch def /xres exch def ++ xres dup mul yres dup mul add sqrt ++ } def ++end ++ ++/tgifsetuserscreen ++ { tgifsetuserscreendict begin ++ /spotfunction exch def ++ /screenangle exch def ++ /cellsize exch def ++ ++ /m tempctm currentmatrix def ++ /rm screenangle temprot rotate def ++ /sm cellsize dup tempscale scale def ++ ++ sm rm m m concatmatrix m concatmatrix pop ++ ++ 1 0 m dtransform /y1 exch def /x1 exch def ++ ++ /veclength x1 dup mul y1 dup mul add sqrt def ++ /frequency findresolution veclength div def ++ ++ /newscreenangle y1 x1 atan def ++ ++ m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt ++ ++ {{neg} /spotfunction load concatprocs ++ /spotfunction exch def ++ } if ++ ++ frequency newscreenangle /spotfunction load setscreen ++ end ++ } def ++ ++/tgifsetpatterndict 18 dict def ++tgifsetpatterndict begin ++ /bitison ++ { /ybit exch def /xbit exch def ++ /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def ++ ++ /mask 1 7 xbit 8 mod sub bitshift def ++ bytevalue mask and 0 ne ++ } def ++end ++ ++/tgifbitpatternspotfunction ++ { tgifsetpatterndict begin ++ /y exch def /x exch def ++ ++ /xindex x 1 add 2 div bpside mul cvi def ++ /yindex y 1 add 2 div bpside mul cvi def ++ ++ xindex yindex bitison ++ { /onbits onbits 1 add def 1 } ++ { /offbits offbits 1 add def 0 } ++ ifelse ++ end ++ } def ++ ++/tgifsetpattern ++ { tgifsetpatterndict begin ++ /cellsz exch def ++ /angle exch def ++ /bwidth exch def ++ /bpside exch def ++ /bstring exch def ++ ++ /onbits 0 def /offbits 0 def ++ cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen ++ {} settransfer ++ offbits offbits onbits add div setgray ++ end ++ } def ++ ++/tgifxpmdict 4 dict def ++/tgifbwpicstr 1 string def ++/tgifcolorpicstr 3 string def ++ ++/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def ++ ++/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def ++ ++/tgifbwspot ++ { tgifxpmdict begin ++ /index exch def ++ tgifbwpicstr 0 ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add ++ cvi put ++ tgifbwpicstr ++ end ++ } def ++ ++/tgifcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul cvi tgifcolorpicstr 2 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 1 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 0 3 -1 roll put ++ tgifcolorpicstr ++ end ++ } def ++ ++/tgifnewcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop setrgbcolor ++ end ++ } def ++ ++/tgifcolordict 4 dict def ++ ++/colorimage where ++ { pop } ++ { /colorimage ++ { tgifcolordict begin ++ pop pop pop pop pop ++ /ih exch def ++ /iw exch def ++ /x 0 def ++ /y 0 def ++ 1 1 ih ++ { pop 1 1 iw ++ { pop currentfile ++ tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot ++ x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto ++ closepath fill ++ /x x 1 add def ++ } for ++ /y y 1 add def ++ /x 0 def ++ } for ++ end ++ } def ++ } ifelse ++ ++/tgifpatdict 10 dict def ++ ++/tgifpatbyte ++ { currentdict /retstr get exch ++ pat i cellsz mod get put ++ } def ++ ++/tgifpatproc ++ { 0 1 widthlim {tgifpatbyte} for retstr ++ /i i 1 add def ++ } def ++ ++/tgifpatfill ++ { tgifpatdict begin ++ /h exch def ++ /w exch def ++ /lty exch def ++ /ltx exch def ++ /cellsz exch def ++ /pat exch def ++ ++ /widthlim w cellsz div cvi 1 sub def ++ /retstr widthlim 1 add string def ++ /i 0 def ++ ++ ltx lty translate ++ w h true [1 0 0 1 0 0] {tgifpatproc} imagemask ++ ltx neg lty neg translate ++ end ++ } def ++ ++/pat1 def ++/pat2 <0000000000000000> def ++/pat3 <8000000008000000> def ++/pat4 <8800000022000000> def ++/pat5 <8800220088002200> def ++/pat6 <8822882288228822> def ++/pat7 def ++/pat8 <77dd77dd77dd77dd> def ++/pat9 <77ffddff77ffddff> def ++/pat10 <77ffffff77ffffff> def ++/pat11 <7fffffff7fffffff> def ++/pat12 <8040200002040800> def ++/pat13 <40a00000040a0000> def ++/pat14 def ++/pat15 def ++/pat16 def ++/pat17 <038448300c020101> def ++/pat18 <081c22c180010204> def ++/pat19 <8080413e080814e3> def ++/pat20 <8040201008040201> def ++/pat21 <8844221188442211> def ++/pat22 <77bbddee77bbddee> def ++/pat23 def ++/pat24 <7fbfdfeff7fbfdfe> def ++/pat25 <3e1f8fc7e3f1f87c> def ++/pat26 <0102040810204080> def ++/pat27 <1122448811224488> def ++/pat28 def ++/pat29 <83070e1c3870e0c1> def ++/pat30 def ++/pat31 <7cf8f1e3c78f1f3e> def ++ ++/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def ++ ++/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def ++ ++/tgifreencsmalldict 12 dict def ++/tgifReEncodeSmall ++ { tgifreencsmalldict begin ++ /newcodesandnames exch def ++ /newfontname exch def ++ /basefontname exch def ++ ++ /basefontdict basefontname findfont def ++ /newfont basefontdict maxlength dict def ++ ++ basefontdict ++ { exch dup /FID ne ++ { dup /Encoding eq ++ { exch dup length array copy newfont 3 1 roll put } ++ { exch newfont 3 1 roll put } ++ ifelse ++ } ++ { pop pop } ++ ifelse ++ } ++ forall ++ ++ newfont /FontName newfontname put ++ newcodesandnames aload pop ++ ++ newcodesandnames length 2 idiv ++ { newfont /Encoding get 3 1 roll put} ++ repeat ++ ++ newfontname newfont definefont pop ++ end ++ } def ++ ++/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def ++ ++/tgifboxdict 6 dict def ++/tgifboxstroke ++ { tgifboxdict begin ++ /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ 1.415 setmiterlimit ++ w 1 eq { w setlinewidth } if ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ w 1 eq { 1 setlinewidth } if ++ 1 setmiterlimit ++ end ++ } def ++/tgifboxfill ++ { tgifboxdict begin ++ /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ end ++ } def ++ ++end ++ ++%%PageBoundingBox: 35 711 289 757 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 setmiterlimit ++1 setlinewidth ++ ++0 setgray ++ ++72 0 mul 72 11.00 mul translate ++72 128 div 100 mul 100 div dup neg scale ++ ++gsave ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 66 66 moveto 130 66 lineto 130 98 lineto 66 98 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 98 66 moveto ++ 98 98 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 114 82 moveto ++ 0 80 atan dup cos 8 mul 194 exch sub ++ exch sin 8 mul 82 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 194 82 8 3 80 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 146 136 moveto (rose) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 82 82 moveto ++ 82 131 lineto ++ 0 48 atan dup cos 8 mul 130 exch sub ++ exch sin 8 mul 131 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 130 131 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 199 66 moveto 263 66 lineto 263 98 lineto 199 98 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 231 66 moveto ++ 231 98 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 247 82 moveto ++ 0 93 atan dup cos 8 mul 340 exch sub ++ exch sin 8 mul 82 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 340 82 8 3 93 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 279 136 moveto (violet) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 215 82 moveto ++ 215 131 lineto ++ 0 48 atan dup cos 8 mul 263 exch sub ++ exch sin 8 mul 131 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 263 131 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 342 64 moveto 406 64 lineto 406 96 lineto 342 96 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 373 64 moveto ++ 373 96 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 389 81 moveto ++ 0 48 atan dup cos 8 mul 437 exch sub ++ exch sin 8 mul 81 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 437 81 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 421 135 moveto (buttercup) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 357 81 moveto ++ 357 130 lineto ++ 0 48 atan dup cos 8 mul 405 exch sub ++ exch sin 8 mul 130 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 405 130 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 449 87 moveto (nil) show ++ grestore ++ ++grestore ++tgifsavedpage restore ++end ++%MatchingCreationDate: Wed Mar 8 14:26:58 1995 +diff --git a/doc/lispintro/cons-2.eps b/doc/lispintro/cons-2.eps +new file mode 100644 +index 0000000..9083ef0 +--- /dev/null ++++ b/doc/lispintro/cons-2.eps +@@ -0,0 +1,604 @@ ++%! ++%%BoundingBox: 15 712 321 775 ++%%Title: cons-cell-diagram2 ++%%CreationDate: Wed Mar 8 14:26:39 1995 ++%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++% ++% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 ++% ++ ++% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 132 dict def ++tgifdict begin ++ ++% ++% Using a zero value radius for an ellipse or an arc would result ++% in a non-invertible CTM matrix which causes problem when this ++% when this PostScript is wrapped inside other routines, such as ++% the multi.ps package from ++% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such ++% error by uncommenting the sole line of the procedure below: ++% ++/tgif_min_radius ++ { ++% dup 0.01 lt { pop 0.01 } if ++ } bind def ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarrowtipdict 8 dict def ++tgifarrowtipdict /mtrx matrix put ++ ++/tgifarrowtip ++ { tgifarrowtipdict begin ++ /dy exch def ++ /dx exch def ++ /h exch def ++ /w exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ dy dx atan rotate ++ 0 0 moveto ++ w neg h lineto ++ w neg h neg lineto ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarcdict 8 dict def ++tgifarcdict /mtrx matrix put ++ ++/tgifarcn ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarc ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arcn ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifsetuserscreendict 22 dict def ++tgifsetuserscreendict begin ++ /tempctm matrix def ++ /temprot matrix def ++ /tempscale matrix def ++ ++ /concatprocs ++ { /proc2 exch cvlit def ++ /proc1 exch cvlit def ++ /newproc proc1 length proc2 length add array def ++ newproc 0 proc1 putinterval ++ newproc proc1 length proc2 putinterval ++ newproc cvx ++ } def ++ /resmatrix matrix def ++ /findresolution ++ { 72 0 resmatrix defaultmatrix dtransform ++ /yres exch def /xres exch def ++ xres dup mul yres dup mul add sqrt ++ } def ++end ++ ++/tgifsetuserscreen ++ { tgifsetuserscreendict begin ++ /spotfunction exch def ++ /screenangle exch def ++ /cellsize exch def ++ ++ /m tempctm currentmatrix def ++ /rm screenangle temprot rotate def ++ /sm cellsize dup tempscale scale def ++ ++ sm rm m m concatmatrix m concatmatrix pop ++ ++ 1 0 m dtransform /y1 exch def /x1 exch def ++ ++ /veclength x1 dup mul y1 dup mul add sqrt def ++ /frequency findresolution veclength div def ++ ++ /newscreenangle y1 x1 atan def ++ ++ m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt ++ ++ {{neg} /spotfunction load concatprocs ++ /spotfunction exch def ++ } if ++ ++ frequency newscreenangle /spotfunction load setscreen ++ end ++ } def ++ ++/tgifsetpatterndict 18 dict def ++tgifsetpatterndict begin ++ /bitison ++ { /ybit exch def /xbit exch def ++ /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def ++ ++ /mask 1 7 xbit 8 mod sub bitshift def ++ bytevalue mask and 0 ne ++ } def ++end ++ ++/tgifbitpatternspotfunction ++ { tgifsetpatterndict begin ++ /y exch def /x exch def ++ ++ /xindex x 1 add 2 div bpside mul cvi def ++ /yindex y 1 add 2 div bpside mul cvi def ++ ++ xindex yindex bitison ++ { /onbits onbits 1 add def 1 } ++ { /offbits offbits 1 add def 0 } ++ ifelse ++ end ++ } def ++ ++/tgifsetpattern ++ { tgifsetpatterndict begin ++ /cellsz exch def ++ /angle exch def ++ /bwidth exch def ++ /bpside exch def ++ /bstring exch def ++ ++ /onbits 0 def /offbits 0 def ++ cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen ++ {} settransfer ++ offbits offbits onbits add div setgray ++ end ++ } def ++ ++/tgifxpmdict 4 dict def ++/tgifbwpicstr 1 string def ++/tgifcolorpicstr 3 string def ++ ++/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def ++ ++/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def ++ ++/tgifbwspot ++ { tgifxpmdict begin ++ /index exch def ++ tgifbwpicstr 0 ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add ++ cvi put ++ tgifbwpicstr ++ end ++ } def ++ ++/tgifcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul cvi tgifcolorpicstr 2 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 1 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 0 3 -1 roll put ++ tgifcolorpicstr ++ end ++ } def ++ ++/tgifnewcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop setrgbcolor ++ end ++ } def ++ ++/tgifcolordict 4 dict def ++ ++/colorimage where ++ { pop } ++ { /colorimage ++ { tgifcolordict begin ++ pop pop pop pop pop ++ /ih exch def ++ /iw exch def ++ /x 0 def ++ /y 0 def ++ 1 1 ih ++ { pop 1 1 iw ++ { pop currentfile ++ tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot ++ x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto ++ closepath fill ++ /x x 1 add def ++ } for ++ /y y 1 add def ++ /x 0 def ++ } for ++ end ++ } def ++ } ifelse ++ ++/tgifpatdict 10 dict def ++ ++/tgifpatbyte ++ { currentdict /retstr get exch ++ pat i cellsz mod get put ++ } def ++ ++/tgifpatproc ++ { 0 1 widthlim {tgifpatbyte} for retstr ++ /i i 1 add def ++ } def ++ ++/tgifpatfill ++ { tgifpatdict begin ++ /h exch def ++ /w exch def ++ /lty exch def ++ /ltx exch def ++ /cellsz exch def ++ /pat exch def ++ ++ /widthlim w cellsz div cvi 1 sub def ++ /retstr widthlim 1 add string def ++ /i 0 def ++ ++ ltx lty translate ++ w h true [1 0 0 1 0 0] {tgifpatproc} imagemask ++ ltx neg lty neg translate ++ end ++ } def ++ ++/pat1 def ++/pat2 <0000000000000000> def ++/pat3 <8000000008000000> def ++/pat4 <8800000022000000> def ++/pat5 <8800220088002200> def ++/pat6 <8822882288228822> def ++/pat7 def ++/pat8 <77dd77dd77dd77dd> def ++/pat9 <77ffddff77ffddff> def ++/pat10 <77ffffff77ffffff> def ++/pat11 <7fffffff7fffffff> def ++/pat12 <8040200002040800> def ++/pat13 <40a00000040a0000> def ++/pat14 def ++/pat15 def ++/pat16 def ++/pat17 <038448300c020101> def ++/pat18 <081c22c180010204> def ++/pat19 <8080413e080814e3> def ++/pat20 <8040201008040201> def ++/pat21 <8844221188442211> def ++/pat22 <77bbddee77bbddee> def ++/pat23 def ++/pat24 <7fbfdfeff7fbfdfe> def ++/pat25 <3e1f8fc7e3f1f87c> def ++/pat26 <0102040810204080> def ++/pat27 <1122448811224488> def ++/pat28 def ++/pat29 <83070e1c3870e0c1> def ++/pat30 def ++/pat31 <7cf8f1e3c78f1f3e> def ++ ++/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def ++ ++/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def ++ ++/tgifreencsmalldict 12 dict def ++/tgifReEncodeSmall ++ { tgifreencsmalldict begin ++ /newcodesandnames exch def ++ /newfontname exch def ++ /basefontname exch def ++ ++ /basefontdict basefontname findfont def ++ /newfont basefontdict maxlength dict def ++ ++ basefontdict ++ { exch dup /FID ne ++ { dup /Encoding eq ++ { exch dup length array copy newfont 3 1 roll put } ++ { exch newfont 3 1 roll put } ++ ifelse ++ } ++ { pop pop } ++ ifelse ++ } ++ forall ++ ++ newfont /FontName newfontname put ++ newcodesandnames aload pop ++ ++ newcodesandnames length 2 idiv ++ { newfont /Encoding get 3 1 roll put} ++ repeat ++ ++ newfontname newfont definefont pop ++ end ++ } def ++ ++/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def ++ ++/tgifboxdict 6 dict def ++/tgifboxstroke ++ { tgifboxdict begin ++ /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ 1.415 setmiterlimit ++ w 1 eq { w setlinewidth } if ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ w 1 eq { 1 setlinewidth } if ++ 1 setmiterlimit ++ end ++ } def ++/tgifboxfill ++ { tgifboxdict begin ++ /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ end ++ } def ++ ++end ++ ++%%PageBoundingBox: 15 712 321 775 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 setmiterlimit ++1 setlinewidth ++ ++0 setgray ++ ++72 0 mul 72 11.00 mul translate ++72 128 div 100 mul 100 div dup neg scale ++ ++gsave ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 32 47 moveto (bouquet) show ++ grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 122 65 moveto 186 65 lineto 186 97 lineto 122 97 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 154 65 moveto ++ 154 97 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 170 81 moveto ++ 0 80 atan dup cos 8 mul 250 exch sub ++ exch sin 8 mul 81 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 250 81 8 3 80 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 202 135 moveto (rose) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 138 81 moveto ++ 138 130 lineto ++ 0 48 atan dup cos 8 mul 186 exch sub ++ exch sin 8 mul 130 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 186 130 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 255 65 moveto 319 65 lineto 319 97 lineto 255 97 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 287 65 moveto ++ 287 97 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 303 81 moveto ++ 0 93 atan dup cos 8 mul 396 exch sub ++ exch sin 8 mul 81 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 396 81 8 3 93 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 335 135 moveto (violet) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 271 81 moveto ++ 271 130 lineto ++ 0 48 atan dup cos 8 mul 319 exch sub ++ exch sin 8 mul 130 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 319 130 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 398 63 moveto 462 63 lineto 462 95 lineto 398 95 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 429 63 moveto ++ 429 95 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 445 80 moveto ++ 0 48 atan dup cos 8 mul 493 exch sub ++ exch sin 8 mul 80 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 493 80 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 477 134 moveto (buttercup) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 413 80 moveto ++ 413 129 lineto ++ 0 48 atan dup cos 8 mul 461 exch sub ++ exch sin 8 mul 129 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 461 129 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 505 86 moveto (nil) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 66 53 moveto ++ 66 81 lineto ++ 0 46 atan dup cos 8 mul 112 exch sub ++ exch sin 8 mul 81 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 112 81 8 3 46 0 tgifarrowtip ++ closepath fill ++grestore ++ ++grestore ++tgifsavedpage restore ++end ++%MatchingCreationDate: Wed Mar 8 14:26:39 1995 +diff --git a/doc/lispintro/cons-2a.eps b/doc/lispintro/cons-2a.eps +new file mode 100644 +index 0000000..e492b15 +--- /dev/null ++++ b/doc/lispintro/cons-2a.eps +@@ -0,0 +1,598 @@ ++%! ++%%BoundingBox: 15 702 300 767 ++%%Title: cons-cell-diagram2a ++%%CreationDate: Tue Mar 14 15:09:30 1995 ++%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++% ++% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 ++% ++ ++% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 132 dict def ++tgifdict begin ++ ++% ++% Using a zero value radius for an ellipse or an arc would result ++% in a non-invertible CTM matrix which causes problem when this ++% when this PostScript is wrapped inside other routines, such as ++% the multi.ps package from ++% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such ++% error by uncommenting the sole line of the procedure below: ++% ++/tgif_min_radius ++ { ++% dup 0.01 lt { pop 0.01 } if ++ } bind def ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarrowtipdict 8 dict def ++tgifarrowtipdict /mtrx matrix put ++ ++/tgifarrowtip ++ { tgifarrowtipdict begin ++ /dy exch def ++ /dx exch def ++ /h exch def ++ /w exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ dy dx atan rotate ++ 0 0 moveto ++ w neg h lineto ++ w neg h neg lineto ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarcdict 8 dict def ++tgifarcdict /mtrx matrix put ++ ++/tgifarcn ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarc ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arcn ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifsetuserscreendict 22 dict def ++tgifsetuserscreendict begin ++ /tempctm matrix def ++ /temprot matrix def ++ /tempscale matrix def ++ ++ /concatprocs ++ { /proc2 exch cvlit def ++ /proc1 exch cvlit def ++ /newproc proc1 length proc2 length add array def ++ newproc 0 proc1 putinterval ++ newproc proc1 length proc2 putinterval ++ newproc cvx ++ } def ++ /resmatrix matrix def ++ /findresolution ++ { 72 0 resmatrix defaultmatrix dtransform ++ /yres exch def /xres exch def ++ xres dup mul yres dup mul add sqrt ++ } def ++end ++ ++/tgifsetuserscreen ++ { tgifsetuserscreendict begin ++ /spotfunction exch def ++ /screenangle exch def ++ /cellsize exch def ++ ++ /m tempctm currentmatrix def ++ /rm screenangle temprot rotate def ++ /sm cellsize dup tempscale scale def ++ ++ sm rm m m concatmatrix m concatmatrix pop ++ ++ 1 0 m dtransform /y1 exch def /x1 exch def ++ ++ /veclength x1 dup mul y1 dup mul add sqrt def ++ /frequency findresolution veclength div def ++ ++ /newscreenangle y1 x1 atan def ++ ++ m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt ++ ++ {{neg} /spotfunction load concatprocs ++ /spotfunction exch def ++ } if ++ ++ frequency newscreenangle /spotfunction load setscreen ++ end ++ } def ++ ++/tgifsetpatterndict 18 dict def ++tgifsetpatterndict begin ++ /bitison ++ { /ybit exch def /xbit exch def ++ /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def ++ ++ /mask 1 7 xbit 8 mod sub bitshift def ++ bytevalue mask and 0 ne ++ } def ++end ++ ++/tgifbitpatternspotfunction ++ { tgifsetpatterndict begin ++ /y exch def /x exch def ++ ++ /xindex x 1 add 2 div bpside mul cvi def ++ /yindex y 1 add 2 div bpside mul cvi def ++ ++ xindex yindex bitison ++ { /onbits onbits 1 add def 1 } ++ { /offbits offbits 1 add def 0 } ++ ifelse ++ end ++ } def ++ ++/tgifsetpattern ++ { tgifsetpatterndict begin ++ /cellsz exch def ++ /angle exch def ++ /bwidth exch def ++ /bpside exch def ++ /bstring exch def ++ ++ /onbits 0 def /offbits 0 def ++ cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen ++ {} settransfer ++ offbits offbits onbits add div setgray ++ end ++ } def ++ ++/tgifxpmdict 4 dict def ++/tgifbwpicstr 1 string def ++/tgifcolorpicstr 3 string def ++ ++/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def ++ ++/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def ++ ++/tgifbwspot ++ { tgifxpmdict begin ++ /index exch def ++ tgifbwpicstr 0 ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add ++ cvi put ++ tgifbwpicstr ++ end ++ } def ++ ++/tgifcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul cvi tgifcolorpicstr 2 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 1 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 0 3 -1 roll put ++ tgifcolorpicstr ++ end ++ } def ++ ++/tgifnewcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop setrgbcolor ++ end ++ } def ++ ++/tgifcolordict 4 dict def ++ ++/colorimage where ++ { pop } ++ { /colorimage ++ { tgifcolordict begin ++ pop pop pop pop pop ++ /ih exch def ++ /iw exch def ++ /x 0 def ++ /y 0 def ++ 1 1 ih ++ { pop 1 1 iw ++ { pop currentfile ++ tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot ++ x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto ++ closepath fill ++ /x x 1 add def ++ } for ++ /y y 1 add def ++ /x 0 def ++ } for ++ end ++ } def ++ } ifelse ++ ++/tgifpatdict 10 dict def ++ ++/tgifpatbyte ++ { currentdict /retstr get exch ++ pat i cellsz mod get put ++ } def ++ ++/tgifpatproc ++ { 0 1 widthlim {tgifpatbyte} for retstr ++ /i i 1 add def ++ } def ++ ++/tgifpatfill ++ { tgifpatdict begin ++ /h exch def ++ /w exch def ++ /lty exch def ++ /ltx exch def ++ /cellsz exch def ++ /pat exch def ++ ++ /widthlim w cellsz div cvi 1 sub def ++ /retstr widthlim 1 add string def ++ /i 0 def ++ ++ ltx lty translate ++ w h true [1 0 0 1 0 0] {tgifpatproc} imagemask ++ ltx neg lty neg translate ++ end ++ } def ++ ++/pat1 def ++/pat2 <0000000000000000> def ++/pat3 <8000000008000000> def ++/pat4 <8800000022000000> def ++/pat5 <8800220088002200> def ++/pat6 <8822882288228822> def ++/pat7 def ++/pat8 <77dd77dd77dd77dd> def ++/pat9 <77ffddff77ffddff> def ++/pat10 <77ffffff77ffffff> def ++/pat11 <7fffffff7fffffff> def ++/pat12 <8040200002040800> def ++/pat13 <40a00000040a0000> def ++/pat14 def ++/pat15 def ++/pat16 def ++/pat17 <038448300c020101> def ++/pat18 <081c22c180010204> def ++/pat19 <8080413e080814e3> def ++/pat20 <8040201008040201> def ++/pat21 <8844221188442211> def ++/pat22 <77bbddee77bbddee> def ++/pat23 def ++/pat24 <7fbfdfeff7fbfdfe> def ++/pat25 <3e1f8fc7e3f1f87c> def ++/pat26 <0102040810204080> def ++/pat27 <1122448811224488> def ++/pat28 def ++/pat29 <83070e1c3870e0c1> def ++/pat30 def ++/pat31 <7cf8f1e3c78f1f3e> def ++ ++/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def ++ ++/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def ++ ++/tgifreencsmalldict 12 dict def ++/tgifReEncodeSmall ++ { tgifreencsmalldict begin ++ /newcodesandnames exch def ++ /newfontname exch def ++ /basefontname exch def ++ ++ /basefontdict basefontname findfont def ++ /newfont basefontdict maxlength dict def ++ ++ basefontdict ++ { exch dup /FID ne ++ { dup /Encoding eq ++ { exch dup length array copy newfont 3 1 roll put } ++ { exch newfont 3 1 roll put } ++ ifelse ++ } ++ { pop pop } ++ ifelse ++ } ++ forall ++ ++ newfont /FontName newfontname put ++ newcodesandnames aload pop ++ ++ newcodesandnames length 2 idiv ++ { newfont /Encoding get 3 1 roll put} ++ repeat ++ ++ newfontname newfont definefont pop ++ end ++ } def ++ ++/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def ++ ++/tgifboxdict 6 dict def ++/tgifboxstroke ++ { tgifboxdict begin ++ /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ 1.415 setmiterlimit ++ w 1 eq { w setlinewidth } if ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ w 1 eq { 1 setlinewidth } if ++ 1 setmiterlimit ++ end ++ } def ++/tgifboxfill ++ { tgifboxdict begin ++ /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ end ++ } def ++ ++end ++ ++%%PageBoundingBox: 15 702 300 767 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 setmiterlimit ++1 setlinewidth ++ ++0 setgray ++ ++72 0 mul 72 11.00 mul translate ++72 128 div 100 mul 100 div dup neg scale ++ ++gsave ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 32 62 moveto (bouquet) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 64 80 moveto ++ 64 120 lineto ++ 0 49 atan dup cos 8 mul 113 exch sub ++ exch sin 8 mul 120 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 113 120 8 3 49 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 128 110 moveto (car) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 128 142 moveto (rose) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 192 110 moveto (cdr) show ++ grestore ++ ++% OVAL ++gsave ++ newpath 207 124 4 4 tgifellipse stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 217 123 moveto ++ 0 38 atan dup cos 8 mul 255 exch sub ++ exch sin 8 mul 123 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 255 123 8 3 38 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 268 111 moveto (car) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 264 143 moveto (violet) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 332 111 moveto (cdr) show ++ grestore ++ ++% OVAL ++gsave ++ newpath 347 125 4 4 tgifellipse stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 357 124 moveto ++ 0 38 atan dup cos 8 mul 395 exch sub ++ exch sin 8 mul 124 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 395 124 8 3 38 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 408 112 moveto (car) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 408 136 moveto (butter-) show ++ 408 153 moveto (cup) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 496 113 moveto (cdr) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 495 137 moveto (nil) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 178 86 moveto ++ 178 157 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 485 84 moveto ++ 485 157 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 327 85 moveto ++ 327 157 lineto ++ stroke ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 120 86 moveto 234 86 lineto 234 157 lineto 120 157 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 257 85 moveto 371 85 lineto 371 157 lineto 257 157 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 397 84 moveto 531 84 lineto 531 157 lineto 397 157 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++grestore ++tgifsavedpage restore ++end ++%MatchingCreationDate: Tue Mar 14 15:09:30 1995 +diff --git a/doc/lispintro/cons-3.eps b/doc/lispintro/cons-3.eps +new file mode 100644 +index 0000000..bb08120 +--- /dev/null ++++ b/doc/lispintro/cons-3.eps +@@ -0,0 +1,628 @@ ++%! ++%%BoundingBox: -1 691 324 757 ++%%Title: cons-cell-diagram3 ++%%CreationDate: Wed Mar 8 14:25:41 1995 ++%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++% ++% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 ++% ++ ++% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 132 dict def ++tgifdict begin ++ ++% ++% Using a zero value radius for an ellipse or an arc would result ++% in a non-invertible CTM matrix which causes problem when this ++% when this PostScript is wrapped inside other routines, such as ++% the multi.ps package from ++% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such ++% error by uncommenting the sole line of the procedure below: ++% ++/tgif_min_radius ++ { ++% dup 0.01 lt { pop 0.01 } if ++ } bind def ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarrowtipdict 8 dict def ++tgifarrowtipdict /mtrx matrix put ++ ++/tgifarrowtip ++ { tgifarrowtipdict begin ++ /dy exch def ++ /dx exch def ++ /h exch def ++ /w exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ dy dx atan rotate ++ 0 0 moveto ++ w neg h lineto ++ w neg h neg lineto ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarcdict 8 dict def ++tgifarcdict /mtrx matrix put ++ ++/tgifarcn ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarc ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arcn ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifsetuserscreendict 22 dict def ++tgifsetuserscreendict begin ++ /tempctm matrix def ++ /temprot matrix def ++ /tempscale matrix def ++ ++ /concatprocs ++ { /proc2 exch cvlit def ++ /proc1 exch cvlit def ++ /newproc proc1 length proc2 length add array def ++ newproc 0 proc1 putinterval ++ newproc proc1 length proc2 putinterval ++ newproc cvx ++ } def ++ /resmatrix matrix def ++ /findresolution ++ { 72 0 resmatrix defaultmatrix dtransform ++ /yres exch def /xres exch def ++ xres dup mul yres dup mul add sqrt ++ } def ++end ++ ++/tgifsetuserscreen ++ { tgifsetuserscreendict begin ++ /spotfunction exch def ++ /screenangle exch def ++ /cellsize exch def ++ ++ /m tempctm currentmatrix def ++ /rm screenangle temprot rotate def ++ /sm cellsize dup tempscale scale def ++ ++ sm rm m m concatmatrix m concatmatrix pop ++ ++ 1 0 m dtransform /y1 exch def /x1 exch def ++ ++ /veclength x1 dup mul y1 dup mul add sqrt def ++ /frequency findresolution veclength div def ++ ++ /newscreenangle y1 x1 atan def ++ ++ m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt ++ ++ {{neg} /spotfunction load concatprocs ++ /spotfunction exch def ++ } if ++ ++ frequency newscreenangle /spotfunction load setscreen ++ end ++ } def ++ ++/tgifsetpatterndict 18 dict def ++tgifsetpatterndict begin ++ /bitison ++ { /ybit exch def /xbit exch def ++ /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def ++ ++ /mask 1 7 xbit 8 mod sub bitshift def ++ bytevalue mask and 0 ne ++ } def ++end ++ ++/tgifbitpatternspotfunction ++ { tgifsetpatterndict begin ++ /y exch def /x exch def ++ ++ /xindex x 1 add 2 div bpside mul cvi def ++ /yindex y 1 add 2 div bpside mul cvi def ++ ++ xindex yindex bitison ++ { /onbits onbits 1 add def 1 } ++ { /offbits offbits 1 add def 0 } ++ ifelse ++ end ++ } def ++ ++/tgifsetpattern ++ { tgifsetpatterndict begin ++ /cellsz exch def ++ /angle exch def ++ /bwidth exch def ++ /bpside exch def ++ /bstring exch def ++ ++ /onbits 0 def /offbits 0 def ++ cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen ++ {} settransfer ++ offbits offbits onbits add div setgray ++ end ++ } def ++ ++/tgifxpmdict 4 dict def ++/tgifbwpicstr 1 string def ++/tgifcolorpicstr 3 string def ++ ++/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def ++ ++/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def ++ ++/tgifbwspot ++ { tgifxpmdict begin ++ /index exch def ++ tgifbwpicstr 0 ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add ++ cvi put ++ tgifbwpicstr ++ end ++ } def ++ ++/tgifcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul cvi tgifcolorpicstr 2 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 1 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 0 3 -1 roll put ++ tgifcolorpicstr ++ end ++ } def ++ ++/tgifnewcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop setrgbcolor ++ end ++ } def ++ ++/tgifcolordict 4 dict def ++ ++/colorimage where ++ { pop } ++ { /colorimage ++ { tgifcolordict begin ++ pop pop pop pop pop ++ /ih exch def ++ /iw exch def ++ /x 0 def ++ /y 0 def ++ 1 1 ih ++ { pop 1 1 iw ++ { pop currentfile ++ tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot ++ x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto ++ closepath fill ++ /x x 1 add def ++ } for ++ /y y 1 add def ++ /x 0 def ++ } for ++ end ++ } def ++ } ifelse ++ ++/tgifpatdict 10 dict def ++ ++/tgifpatbyte ++ { currentdict /retstr get exch ++ pat i cellsz mod get put ++ } def ++ ++/tgifpatproc ++ { 0 1 widthlim {tgifpatbyte} for retstr ++ /i i 1 add def ++ } def ++ ++/tgifpatfill ++ { tgifpatdict begin ++ /h exch def ++ /w exch def ++ /lty exch def ++ /ltx exch def ++ /cellsz exch def ++ /pat exch def ++ ++ /widthlim w cellsz div cvi 1 sub def ++ /retstr widthlim 1 add string def ++ /i 0 def ++ ++ ltx lty translate ++ w h true [1 0 0 1 0 0] {tgifpatproc} imagemask ++ ltx neg lty neg translate ++ end ++ } def ++ ++/pat1 def ++/pat2 <0000000000000000> def ++/pat3 <8000000008000000> def ++/pat4 <8800000022000000> def ++/pat5 <8800220088002200> def ++/pat6 <8822882288228822> def ++/pat7 def ++/pat8 <77dd77dd77dd77dd> def ++/pat9 <77ffddff77ffddff> def ++/pat10 <77ffffff77ffffff> def ++/pat11 <7fffffff7fffffff> def ++/pat12 <8040200002040800> def ++/pat13 <40a00000040a0000> def ++/pat14 def ++/pat15 def ++/pat16 def ++/pat17 <038448300c020101> def ++/pat18 <081c22c180010204> def ++/pat19 <8080413e080814e3> def ++/pat20 <8040201008040201> def ++/pat21 <8844221188442211> def ++/pat22 <77bbddee77bbddee> def ++/pat23 def ++/pat24 <7fbfdfeff7fbfdfe> def ++/pat25 <3e1f8fc7e3f1f87c> def ++/pat26 <0102040810204080> def ++/pat27 <1122448811224488> def ++/pat28 def ++/pat29 <83070e1c3870e0c1> def ++/pat30 def ++/pat31 <7cf8f1e3c78f1f3e> def ++ ++/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def ++ ++/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def ++ ++/tgifreencsmalldict 12 dict def ++/tgifReEncodeSmall ++ { tgifreencsmalldict begin ++ /newcodesandnames exch def ++ /newfontname exch def ++ /basefontname exch def ++ ++ /basefontdict basefontname findfont def ++ /newfont basefontdict maxlength dict def ++ ++ basefontdict ++ { exch dup /FID ne ++ { dup /Encoding eq ++ { exch dup length array copy newfont 3 1 roll put } ++ { exch newfont 3 1 roll put } ++ ifelse ++ } ++ { pop pop } ++ ifelse ++ } ++ forall ++ ++ newfont /FontName newfontname put ++ newcodesandnames aload pop ++ ++ newcodesandnames length 2 idiv ++ { newfont /Encoding get 3 1 roll put} ++ repeat ++ ++ newfontname newfont definefont pop ++ end ++ } def ++ ++/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def ++ ++/tgifboxdict 6 dict def ++/tgifboxstroke ++ { tgifboxdict begin ++ /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ 1.415 setmiterlimit ++ w 1 eq { w setlinewidth } if ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ w 1 eq { 1 setlinewidth } if ++ 1 setmiterlimit ++ end ++ } def ++/tgifboxfill ++ { tgifboxdict begin ++ /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ end ++ } def ++ ++end ++ ++%%PageBoundingBox: -1 691 324 757 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 setmiterlimit ++1 setlinewidth ++ ++0 setgray ++ ++72 0 mul 72 11.00 mul translate ++72 128 div 100 mul 100 div dup neg scale ++ ++gsave ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 128 102 moveto 192 102 lineto 192 134 lineto 128 134 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 160 102 moveto ++ 160 134 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 176 124 moveto ++ 0 80 atan dup cos 8 mul 256 exch sub ++ exch sin 8 mul 124 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 256 124 8 3 80 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 208 172 moveto (rose) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 144 118 moveto ++ 144 167 lineto ++ 0 48 atan dup cos 8 mul 192 exch sub ++ exch sin 8 mul 167 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 192 167 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 261 102 moveto 325 102 lineto 325 134 lineto 261 134 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 293 102 moveto ++ 293 134 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 309 118 moveto ++ 0 93 atan dup cos 8 mul 402 exch sub ++ exch sin 8 mul 118 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 402 118 8 3 93 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 341 172 moveto (violet) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 277 118 moveto ++ 277 167 lineto ++ 0 48 atan dup cos 8 mul 325 exch sub ++ exch sin 8 mul 167 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 325 167 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 404 100 moveto 468 100 lineto 468 132 lineto 404 132 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 435 100 moveto ++ 435 132 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 451 117 moveto ++ 0 48 atan dup cos 8 mul 499 exch sub ++ exch sin 8 mul 117 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 499 117 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 483 171 moveto (buttercup) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 419 117 moveto ++ 419 166 lineto ++ 0 48 atan dup cos 8 mul 467 exch sub ++ exch sin 8 mul 166 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 467 166 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 511 123 moveto (nil) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 131 80 moveto (flowers) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 210 75 moveto ++ 237 75 lineto ++ 237 113 lineto ++ 0 18 atan dup cos 8 mul 255 exch sub ++ exch sin 8 mul 113 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 255 113 8 3 18 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 2 80 moveto (bouquet) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 81 77 moveto ++ 108 77 lineto ++ 108 115 lineto ++ 0 18 atan dup cos 8 mul 126 exch sub ++ exch sin 8 mul 115 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 126 115 8 3 18 0 tgifarrowtip ++ closepath fill ++grestore ++ ++grestore ++tgifsavedpage restore ++end ++%MatchingCreationDate: Wed Mar 8 14:25:41 1995 +diff --git a/doc/lispintro/cons-4.eps b/doc/lispintro/cons-4.eps +new file mode 100644 +index 0000000..a19a96d +--- /dev/null ++++ b/doc/lispintro/cons-4.eps +@@ -0,0 +1,681 @@ ++%! ++%%BoundingBox: 6 681 355 758 ++%%Title: cons-cell-diagram4 ++%%CreationDate: Wed Mar 8 14:25:06 1995 ++%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++% ++% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 ++% ++ ++% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 132 dict def ++tgifdict begin ++ ++% ++% Using a zero value radius for an ellipse or an arc would result ++% in a non-invertible CTM matrix which causes problem when this ++% when this PostScript is wrapped inside other routines, such as ++% the multi.ps package from ++% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such ++% error by uncommenting the sole line of the procedure below: ++% ++/tgif_min_radius ++ { ++% dup 0.01 lt { pop 0.01 } if ++ } bind def ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarrowtipdict 8 dict def ++tgifarrowtipdict /mtrx matrix put ++ ++/tgifarrowtip ++ { tgifarrowtipdict begin ++ /dy exch def ++ /dx exch def ++ /h exch def ++ /w exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ dy dx atan rotate ++ 0 0 moveto ++ w neg h lineto ++ w neg h neg lineto ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarcdict 8 dict def ++tgifarcdict /mtrx matrix put ++ ++/tgifarcn ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarc ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arcn ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifsetuserscreendict 22 dict def ++tgifsetuserscreendict begin ++ /tempctm matrix def ++ /temprot matrix def ++ /tempscale matrix def ++ ++ /concatprocs ++ { /proc2 exch cvlit def ++ /proc1 exch cvlit def ++ /newproc proc1 length proc2 length add array def ++ newproc 0 proc1 putinterval ++ newproc proc1 length proc2 putinterval ++ newproc cvx ++ } def ++ /resmatrix matrix def ++ /findresolution ++ { 72 0 resmatrix defaultmatrix dtransform ++ /yres exch def /xres exch def ++ xres dup mul yres dup mul add sqrt ++ } def ++end ++ ++/tgifsetuserscreen ++ { tgifsetuserscreendict begin ++ /spotfunction exch def ++ /screenangle exch def ++ /cellsize exch def ++ ++ /m tempctm currentmatrix def ++ /rm screenangle temprot rotate def ++ /sm cellsize dup tempscale scale def ++ ++ sm rm m m concatmatrix m concatmatrix pop ++ ++ 1 0 m dtransform /y1 exch def /x1 exch def ++ ++ /veclength x1 dup mul y1 dup mul add sqrt def ++ /frequency findresolution veclength div def ++ ++ /newscreenangle y1 x1 atan def ++ ++ m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt ++ ++ {{neg} /spotfunction load concatprocs ++ /spotfunction exch def ++ } if ++ ++ frequency newscreenangle /spotfunction load setscreen ++ end ++ } def ++ ++/tgifsetpatterndict 18 dict def ++tgifsetpatterndict begin ++ /bitison ++ { /ybit exch def /xbit exch def ++ /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def ++ ++ /mask 1 7 xbit 8 mod sub bitshift def ++ bytevalue mask and 0 ne ++ } def ++end ++ ++/tgifbitpatternspotfunction ++ { tgifsetpatterndict begin ++ /y exch def /x exch def ++ ++ /xindex x 1 add 2 div bpside mul cvi def ++ /yindex y 1 add 2 div bpside mul cvi def ++ ++ xindex yindex bitison ++ { /onbits onbits 1 add def 1 } ++ { /offbits offbits 1 add def 0 } ++ ifelse ++ end ++ } def ++ ++/tgifsetpattern ++ { tgifsetpatterndict begin ++ /cellsz exch def ++ /angle exch def ++ /bwidth exch def ++ /bpside exch def ++ /bstring exch def ++ ++ /onbits 0 def /offbits 0 def ++ cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen ++ {} settransfer ++ offbits offbits onbits add div setgray ++ end ++ } def ++ ++/tgifxpmdict 4 dict def ++/tgifbwpicstr 1 string def ++/tgifcolorpicstr 3 string def ++ ++/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def ++ ++/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def ++ ++/tgifbwspot ++ { tgifxpmdict begin ++ /index exch def ++ tgifbwpicstr 0 ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add ++ cvi put ++ tgifbwpicstr ++ end ++ } def ++ ++/tgifcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul cvi tgifcolorpicstr 2 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 1 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 0 3 -1 roll put ++ tgifcolorpicstr ++ end ++ } def ++ ++/tgifnewcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop setrgbcolor ++ end ++ } def ++ ++/tgifcolordict 4 dict def ++ ++/colorimage where ++ { pop } ++ { /colorimage ++ { tgifcolordict begin ++ pop pop pop pop pop ++ /ih exch def ++ /iw exch def ++ /x 0 def ++ /y 0 def ++ 1 1 ih ++ { pop 1 1 iw ++ { pop currentfile ++ tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot ++ x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto ++ closepath fill ++ /x x 1 add def ++ } for ++ /y y 1 add def ++ /x 0 def ++ } for ++ end ++ } def ++ } ifelse ++ ++/tgifpatdict 10 dict def ++ ++/tgifpatbyte ++ { currentdict /retstr get exch ++ pat i cellsz mod get put ++ } def ++ ++/tgifpatproc ++ { 0 1 widthlim {tgifpatbyte} for retstr ++ /i i 1 add def ++ } def ++ ++/tgifpatfill ++ { tgifpatdict begin ++ /h exch def ++ /w exch def ++ /lty exch def ++ /ltx exch def ++ /cellsz exch def ++ /pat exch def ++ ++ /widthlim w cellsz div cvi 1 sub def ++ /retstr widthlim 1 add string def ++ /i 0 def ++ ++ ltx lty translate ++ w h true [1 0 0 1 0 0] {tgifpatproc} imagemask ++ ltx neg lty neg translate ++ end ++ } def ++ ++/pat1 def ++/pat2 <0000000000000000> def ++/pat3 <8000000008000000> def ++/pat4 <8800000022000000> def ++/pat5 <8800220088002200> def ++/pat6 <8822882288228822> def ++/pat7 def ++/pat8 <77dd77dd77dd77dd> def ++/pat9 <77ffddff77ffddff> def ++/pat10 <77ffffff77ffffff> def ++/pat11 <7fffffff7fffffff> def ++/pat12 <8040200002040800> def ++/pat13 <40a00000040a0000> def ++/pat14 def ++/pat15 def ++/pat16 def ++/pat17 <038448300c020101> def ++/pat18 <081c22c180010204> def ++/pat19 <8080413e080814e3> def ++/pat20 <8040201008040201> def ++/pat21 <8844221188442211> def ++/pat22 <77bbddee77bbddee> def ++/pat23 def ++/pat24 <7fbfdfeff7fbfdfe> def ++/pat25 <3e1f8fc7e3f1f87c> def ++/pat26 <0102040810204080> def ++/pat27 <1122448811224488> def ++/pat28 def ++/pat29 <83070e1c3870e0c1> def ++/pat30 def ++/pat31 <7cf8f1e3c78f1f3e> def ++ ++/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def ++ ++/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def ++ ++/tgifreencsmalldict 12 dict def ++/tgifReEncodeSmall ++ { tgifreencsmalldict begin ++ /newcodesandnames exch def ++ /newfontname exch def ++ /basefontname exch def ++ ++ /basefontdict basefontname findfont def ++ /newfont basefontdict maxlength dict def ++ ++ basefontdict ++ { exch dup /FID ne ++ { dup /Encoding eq ++ { exch dup length array copy newfont 3 1 roll put } ++ { exch newfont 3 1 roll put } ++ ifelse ++ } ++ { pop pop } ++ ifelse ++ } ++ forall ++ ++ newfont /FontName newfontname put ++ newcodesandnames aload pop ++ ++ newcodesandnames length 2 idiv ++ { newfont /Encoding get 3 1 roll put} ++ repeat ++ ++ newfontname newfont definefont pop ++ end ++ } def ++ ++/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def ++ ++/tgifboxdict 6 dict def ++/tgifboxstroke ++ { tgifboxdict begin ++ /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ 1.415 setmiterlimit ++ w 1 eq { w setlinewidth } if ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ w 1 eq { 1 setlinewidth } if ++ 1 setmiterlimit ++ end ++ } def ++/tgifboxfill ++ { tgifboxdict begin ++ /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ end ++ } def ++ ++end ++ ++%%PageBoundingBox: 6 681 355 758 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 setmiterlimit ++1 setlinewidth ++ ++0 setgray ++ ++72 0 mul 72 11.00 mul translate ++72 128 div 100 mul 100 div dup neg scale ++ ++gsave ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 274 102 moveto ++ 274 134 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 289 122 moveto ++ 0 56 atan dup cos 8 mul 345 exch sub ++ exch sin 8 mul 122 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 345 122 8 3 56 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 350 100 moveto 414 100 lineto 414 132 lineto 350 132 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 382 100 moveto ++ 382 132 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 397 114 moveto ++ 0 59 atan dup cos 8 mul 456 exch sub ++ exch sin 8 mul 114 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 456 114 8 3 59 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 430 170 moveto (violet) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 366 116 moveto ++ 366 165 lineto ++ 0 48 atan dup cos 8 mul 414 exch sub ++ exch sin 8 mul 165 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 414 165 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 219 78 moveto (flowers) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 298 73 moveto ++ 325 73 lineto ++ 325 111 lineto ++ 0 18 atan dup cos 8 mul 343 exch sub ++ exch sin 8 mul 111 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 343 111 8 3 18 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 459 95 moveto 523 95 lineto 523 127 lineto 459 127 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 490 95 moveto ++ 490 127 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 506 112 moveto ++ 0 48 atan dup cos 8 mul 554 exch sub ++ exch sin 8 mul 112 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 554 112 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 566 118 moveto (nil) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 538 151 moveto (buttercup) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 474 109 moveto ++ 474 146 lineto ++ 0 48 atan dup cos 8 mul 522 exch sub ++ exch sin 8 mul 146 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 522 146 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 244 102 moveto 308 102 lineto 308 134 lineto 244 134 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 324 189 moveto (rose) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 260 117 moveto ++ 260 184 lineto ++ 0 48 atan dup cos 8 mul 308 exch sub ++ exch sin 8 mul 184 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 308 184 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 146 101 moveto 210 101 lineto 210 133 lineto 146 133 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 177 101 moveto ++ 177 133 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 193 118 moveto ++ 0 48 atan dup cos 8 mul 241 exch sub ++ exch sin 8 mul 118 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 241 118 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 187 178 moveto (lily) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 163 118 moveto ++ 163 171 lineto ++ 0 18 atan dup cos 8 mul 181 exch sub ++ exch sin 8 mul 171 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 181 171 8 3 18 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 16 78 moveto (bouquet) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 95 73 moveto ++ 122 73 lineto ++ 122 111 lineto ++ 0 18 atan dup cos 8 mul 140 exch sub ++ exch sin 8 mul 111 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 140 111 8 3 18 0 tgifarrowtip ++ closepath fill ++grestore ++ ++grestore ++tgifsavedpage restore ++end ++%MatchingCreationDate: Wed Mar 8 14:25:06 1995 +diff --git a/doc/lispintro/cons-5.eps b/doc/lispintro/cons-5.eps +new file mode 100644 +index 0000000..2102dce +--- /dev/null ++++ b/doc/lispintro/cons-5.eps +@@ -0,0 +1,626 @@ ++%! ++%%BoundingBox: 15 680 305 764 ++%%Title: cons-cell-diagram5 ++%%CreationDate: Wed Mar 8 14:27:28 1995 ++%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++% ++% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 ++% ++ ++% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 132 dict def ++tgifdict begin ++ ++% ++% Using a zero value radius for an ellipse or an arc would result ++% in a non-invertible CTM matrix which causes problem when this ++% when this PostScript is wrapped inside other routines, such as ++% the multi.ps package from ++% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such ++% error by uncommenting the sole line of the procedure below: ++% ++/tgif_min_radius ++ { ++% dup 0.01 lt { pop 0.01 } if ++ } bind def ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarrowtipdict 8 dict def ++tgifarrowtipdict /mtrx matrix put ++ ++/tgifarrowtip ++ { tgifarrowtipdict begin ++ /dy exch def ++ /dx exch def ++ /h exch def ++ /w exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ dy dx atan rotate ++ 0 0 moveto ++ w neg h lineto ++ w neg h neg lineto ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarcdict 8 dict def ++tgifarcdict /mtrx matrix put ++ ++/tgifarcn ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarc ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arcn ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifsetuserscreendict 22 dict def ++tgifsetuserscreendict begin ++ /tempctm matrix def ++ /temprot matrix def ++ /tempscale matrix def ++ ++ /concatprocs ++ { /proc2 exch cvlit def ++ /proc1 exch cvlit def ++ /newproc proc1 length proc2 length add array def ++ newproc 0 proc1 putinterval ++ newproc proc1 length proc2 putinterval ++ newproc cvx ++ } def ++ /resmatrix matrix def ++ /findresolution ++ { 72 0 resmatrix defaultmatrix dtransform ++ /yres exch def /xres exch def ++ xres dup mul yres dup mul add sqrt ++ } def ++end ++ ++/tgifsetuserscreen ++ { tgifsetuserscreendict begin ++ /spotfunction exch def ++ /screenangle exch def ++ /cellsize exch def ++ ++ /m tempctm currentmatrix def ++ /rm screenangle temprot rotate def ++ /sm cellsize dup tempscale scale def ++ ++ sm rm m m concatmatrix m concatmatrix pop ++ ++ 1 0 m dtransform /y1 exch def /x1 exch def ++ ++ /veclength x1 dup mul y1 dup mul add sqrt def ++ /frequency findresolution veclength div def ++ ++ /newscreenangle y1 x1 atan def ++ ++ m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt ++ ++ {{neg} /spotfunction load concatprocs ++ /spotfunction exch def ++ } if ++ ++ frequency newscreenangle /spotfunction load setscreen ++ end ++ } def ++ ++/tgifsetpatterndict 18 dict def ++tgifsetpatterndict begin ++ /bitison ++ { /ybit exch def /xbit exch def ++ /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def ++ ++ /mask 1 7 xbit 8 mod sub bitshift def ++ bytevalue mask and 0 ne ++ } def ++end ++ ++/tgifbitpatternspotfunction ++ { tgifsetpatterndict begin ++ /y exch def /x exch def ++ ++ /xindex x 1 add 2 div bpside mul cvi def ++ /yindex y 1 add 2 div bpside mul cvi def ++ ++ xindex yindex bitison ++ { /onbits onbits 1 add def 1 } ++ { /offbits offbits 1 add def 0 } ++ ifelse ++ end ++ } def ++ ++/tgifsetpattern ++ { tgifsetpatterndict begin ++ /cellsz exch def ++ /angle exch def ++ /bwidth exch def ++ /bpside exch def ++ /bstring exch def ++ ++ /onbits 0 def /offbits 0 def ++ cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen ++ {} settransfer ++ offbits offbits onbits add div setgray ++ end ++ } def ++ ++/tgifxpmdict 4 dict def ++/tgifbwpicstr 1 string def ++/tgifcolorpicstr 3 string def ++ ++/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def ++ ++/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def ++ ++/tgifbwspot ++ { tgifxpmdict begin ++ /index exch def ++ tgifbwpicstr 0 ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add ++ cvi put ++ tgifbwpicstr ++ end ++ } def ++ ++/tgifcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul cvi tgifcolorpicstr 2 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 1 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 0 3 -1 roll put ++ tgifcolorpicstr ++ end ++ } def ++ ++/tgifnewcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop setrgbcolor ++ end ++ } def ++ ++/tgifcolordict 4 dict def ++ ++/colorimage where ++ { pop } ++ { /colorimage ++ { tgifcolordict begin ++ pop pop pop pop pop ++ /ih exch def ++ /iw exch def ++ /x 0 def ++ /y 0 def ++ 1 1 ih ++ { pop 1 1 iw ++ { pop currentfile ++ tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot ++ x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto ++ closepath fill ++ /x x 1 add def ++ } for ++ /y y 1 add def ++ /x 0 def ++ } for ++ end ++ } def ++ } ifelse ++ ++/tgifpatdict 10 dict def ++ ++/tgifpatbyte ++ { currentdict /retstr get exch ++ pat i cellsz mod get put ++ } def ++ ++/tgifpatproc ++ { 0 1 widthlim {tgifpatbyte} for retstr ++ /i i 1 add def ++ } def ++ ++/tgifpatfill ++ { tgifpatdict begin ++ /h exch def ++ /w exch def ++ /lty exch def ++ /ltx exch def ++ /cellsz exch def ++ /pat exch def ++ ++ /widthlim w cellsz div cvi 1 sub def ++ /retstr widthlim 1 add string def ++ /i 0 def ++ ++ ltx lty translate ++ w h true [1 0 0 1 0 0] {tgifpatproc} imagemask ++ ltx neg lty neg translate ++ end ++ } def ++ ++/pat1 def ++/pat2 <0000000000000000> def ++/pat3 <8000000008000000> def ++/pat4 <8800000022000000> def ++/pat5 <8800220088002200> def ++/pat6 <8822882288228822> def ++/pat7 def ++/pat8 <77dd77dd77dd77dd> def ++/pat9 <77ffddff77ffddff> def ++/pat10 <77ffffff77ffffff> def ++/pat11 <7fffffff7fffffff> def ++/pat12 <8040200002040800> def ++/pat13 <40a00000040a0000> def ++/pat14 def ++/pat15 def ++/pat16 def ++/pat17 <038448300c020101> def ++/pat18 <081c22c180010204> def ++/pat19 <8080413e080814e3> def ++/pat20 <8040201008040201> def ++/pat21 <8844221188442211> def ++/pat22 <77bbddee77bbddee> def ++/pat23 def ++/pat24 <7fbfdfeff7fbfdfe> def ++/pat25 <3e1f8fc7e3f1f87c> def ++/pat26 <0102040810204080> def ++/pat27 <1122448811224488> def ++/pat28 def ++/pat29 <83070e1c3870e0c1> def ++/pat30 def ++/pat31 <7cf8f1e3c78f1f3e> def ++ ++/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def ++ ++/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def ++ ++/tgifreencsmalldict 12 dict def ++/tgifReEncodeSmall ++ { tgifreencsmalldict begin ++ /newcodesandnames exch def ++ /newfontname exch def ++ /basefontname exch def ++ ++ /basefontdict basefontname findfont def ++ /newfont basefontdict maxlength dict def ++ ++ basefontdict ++ { exch dup /FID ne ++ { dup /Encoding eq ++ { exch dup length array copy newfont 3 1 roll put } ++ { exch newfont 3 1 roll put } ++ ifelse ++ } ++ { pop pop } ++ ifelse ++ } ++ forall ++ ++ newfont /FontName newfontname put ++ newcodesandnames aload pop ++ ++ newcodesandnames length 2 idiv ++ { newfont /Encoding get 3 1 roll put} ++ repeat ++ ++ newfontname newfont definefont pop ++ end ++ } def ++ ++/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def ++ ++/tgifboxdict 6 dict def ++/tgifboxstroke ++ { tgifboxdict begin ++ /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ 1.415 setmiterlimit ++ w 1 eq { w setlinewidth } if ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ w 1 eq { 1 setlinewidth } if ++ 1 setmiterlimit ++ end ++ } def ++/tgifboxfill ++ { tgifboxdict begin ++ /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ end ++ } def ++ ++end ++ ++%%PageBoundingBox: 15 680 305 764 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 setmiterlimit ++1 setlinewidth ++ ++0 setgray ++ ++72 0 mul 72 11.00 mul translate ++72 128 div 100 mul 100 div dup neg scale ++ ++gsave ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 156 105 moveto ++ 156 137 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 171 125 moveto ++ 0 56 atan dup cos 8 mul 227 exch sub ++ exch sin 8 mul 125 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 227 125 8 3 56 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 232 103 moveto 296 103 lineto 296 135 lineto 232 135 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 264 103 moveto ++ 264 135 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 279 117 moveto ++ 0 59 atan dup cos 8 mul 338 exch sub ++ exch sin 8 mul 117 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 338 117 8 3 59 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 289 172 moveto (a different piece of text) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 248 119 moveto ++ 248 168 lineto ++ 0 29 atan dup cos 8 mul 277 exch sub ++ exch sin 8 mul 168 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 277 168 8 3 29 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 147 66 moveto (kill-ring-yank-pointer) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 207 76 moveto ++ 207 114 lineto ++ 0 18 atan dup cos 8 mul 225 exch sub ++ exch sin 8 mul 114 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 225 114 8 3 18 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 341 98 moveto 405 98 lineto 405 130 lineto 341 130 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 372 98 moveto ++ 372 130 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 388 115 moveto ++ 0 48 atan dup cos 8 mul 436 exch sub ++ exch sin 8 mul 115 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 436 115 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 448 121 moveto (nil) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 397 154 moveto (yet more text) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 356 112 moveto ++ 356 149 lineto ++ 0 35 atan dup cos 8 mul 391 exch sub ++ exch sin 8 mul 149 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 391 149 8 3 35 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% BOX ++gsave ++ 1.415 setmiterlimit ++ newpath ++ 126 105 moveto 190 105 lineto 190 137 lineto 126 137 lineto ++ closepath stroke ++ 1 setmiterlimit ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 206 192 moveto (some text) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 142 120 moveto ++ 142 187 lineto ++ 0 48 atan dup cos 8 mul 190 exch sub ++ exch sin 8 mul 187 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 190 187 8 3 48 0 tgifarrowtip ++ closepath fill ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 32 66 moveto (kill-ring) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 65 81 moveto ++ 65 121 lineto ++ 0 51 atan dup cos 8 mul 116 exch sub ++ exch sin 8 mul 121 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 116 121 8 3 51 0 tgifarrowtip ++ closepath fill ++grestore ++ ++grestore ++tgifsavedpage restore ++end ++%MatchingCreationDate: Wed Mar 8 14:27:28 1995 +diff --git a/doc/lispintro/doclicense.texi b/doc/lispintro/doclicense.texi +new file mode 100644 +index 0000000..1aa7613 +--- /dev/null ++++ b/doc/lispintro/doclicense.texi +@@ -0,0 +1,512 @@ ++@c -*-texinfo-*- ++@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, 2009 Free Software Foundation, Inc. ++@uref{http://fsf.org/} ++ ++Everyone is permitted to copy and distribute verbatim copies ++of this license document, but changing it is not allowed. ++@end display ++ ++@enumerate 0 ++@item ++PREAMBLE ++ ++The purpose of this License is to make a manual, textbook, or other ++functional and useful document @dfn{free} in the sense of freedom: to ++assure everyone the effective freedom to copy and redistribute it, ++with or without modifying it, either commercially or noncommercially. ++Secondarily, this License preserves for the author and publisher a way ++to get credit for their work, while not being considered responsible ++for modifications made by others. ++ ++This License is a kind of ``copyleft'', which means that derivative ++works of the document must themselves be free in the same sense. It ++complements the GNU General Public License, which is a copyleft ++license designed for free software. ++ ++We have designed this License in order to use it for manuals for free ++software, because free software needs free documentation: a free ++program should come with manuals providing the same freedoms that the ++software does. But this License is not limited to software manuals; ++it can be used for any textual work, regardless of subject matter or ++whether it is published as a printed book. We recommend this License ++principally for works whose purpose is instruction or reference. ++ ++@item ++APPLICABILITY AND DEFINITIONS ++ ++This License applies to any manual or other work, in any medium, that ++contains a notice placed by the copyright holder saying it can be ++distributed under the terms of this License. Such a notice grants a ++world-wide, royalty-free license, unlimited in duration, to use that ++work under the conditions stated herein. The ``Document'', below, ++refers to any such manual or work. Any member of the public is a ++licensee, and is addressed as ``you''. You accept the license if you ++copy, modify or distribute the work in a way requiring permission ++under copyright law. ++ ++A ``Modified Version'' of the Document means any work containing the ++Document or a portion of it, either copied verbatim, or with ++modifications and/or translated into another language. ++ ++A ``Secondary Section'' is a named appendix or a front-matter section ++of the Document that deals exclusively with the relationship of the ++publishers or authors of the Document to the Document's overall ++subject (or to related matters) and contains nothing that could fall ++directly within that overall subject. (Thus, if the Document is in ++part a textbook of mathematics, a Secondary Section may not explain ++any mathematics.) The relationship could be a matter of historical ++connection with the subject or with related matters, or of legal, ++commercial, philosophical, ethical or political position regarding ++them. ++ ++The ``Invariant Sections'' are certain Secondary Sections whose titles ++are designated, as being those of Invariant Sections, in the notice ++that says that the Document is released under this License. If a ++section does not fit the above definition of Secondary then it is not ++allowed to be designated as Invariant. The Document may contain zero ++Invariant Sections. If the Document does not identify any Invariant ++Sections then there are none. ++ ++The ``Cover Texts'' are certain short passages of text that are listed, ++as Front-Cover Texts or Back-Cover Texts, in the notice that says that ++the Document is released under this License. A Front-Cover Text may ++be at most 5 words, and a Back-Cover Text may be at most 25 words. ++ ++A ``Transparent'' copy of the Document means a machine-readable copy, ++represented in a format whose specification is available to the ++general public, that is suitable for revising the document ++straightforwardly with generic text editors or (for images composed of ++pixels) generic paint programs or (for drawings) some widely available ++drawing editor, and that is suitable for input to text formatters or ++for automatic translation to a variety of formats suitable for input ++to text formatters. A copy made in an otherwise Transparent file ++format whose markup, or absence of markup, has been arranged to thwart ++or discourage subsequent modification by readers is not Transparent. ++An image format is not Transparent if used for any substantial amount ++of text. A copy that is not ``Transparent'' is called ``Opaque''. ++ ++Examples of suitable formats for Transparent copies include plain ++@sc{ascii} without markup, Texinfo input format, La@TeX{} input ++format, @acronym{SGML} or @acronym{XML} using a publicly available ++@acronym{DTD}, and standard-conforming simple @acronym{HTML}, ++PostScript or @acronym{PDF} designed for human modification. Examples ++of transparent image formats include @acronym{PNG}, @acronym{XCF} and ++@acronym{JPG}. Opaque formats include proprietary formats that can be ++read and edited only by proprietary word processors, @acronym{SGML} or ++@acronym{XML} for which the @acronym{DTD} and/or processing tools are ++not generally available, and the machine-generated @acronym{HTML}, ++PostScript or @acronym{PDF} produced by some word processors for ++output purposes only. ++ ++The ``Title Page'' means, for a printed book, the title page itself, ++plus such following pages as are needed to hold, legibly, the material ++this License requires to appear in the title page. For works in ++formats which do not have any title page as such, ``Title Page'' means ++the text near the most prominent appearance of the work's title, ++preceding the beginning of the body of the text. ++ ++The ``publisher'' means any person or entity that distributes copies ++of the Document to the public. ++ ++A section ``Entitled XYZ'' means a named subunit of the Document whose ++title either is precisely XYZ or contains XYZ in parentheses following ++text that translates XYZ in another language. (Here XYZ stands for a ++specific section name mentioned below, such as ``Acknowledgements'', ++``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' ++of such a section when you modify the Document means that it remains a ++section ``Entitled XYZ'' according to this definition. ++ ++The Document may include Warranty Disclaimers next to the notice which ++states that this License applies to the Document. These Warranty ++Disclaimers are considered to be included by reference in this ++License, but only as regards disclaiming warranties: any other ++implication that these Warranty Disclaimers may have is void and has ++no effect on the meaning of this License. ++ ++@item ++VERBATIM COPYING ++ ++You may copy and distribute the Document in any medium, either ++commercially or noncommercially, provided that this License, the ++copyright notices, and the license notice saying this License applies ++to the Document are reproduced in all copies, and that you add no other ++conditions whatsoever to those of this License. You may not use ++technical measures to obstruct or control the reading or further ++copying of the copies you make or distribute. However, you may accept ++compensation in exchange for copies. If you distribute a large enough ++number of copies you must also follow the conditions in section 3. ++ ++You may also lend copies, under the same conditions stated above, and ++you may publicly display copies. ++ ++@item ++COPYING IN QUANTITY ++ ++If you publish printed copies (or copies in media that commonly have ++printed covers) of the Document, numbering more than 100, and the ++Document's license notice requires Cover Texts, you must enclose the ++copies in covers that carry, clearly and legibly, all these Cover ++Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on ++the back cover. Both covers must also clearly and legibly identify ++you as the publisher of these copies. The front cover must present ++the full title with all words of the title equally prominent and ++visible. You may add other material on the covers in addition. ++Copying with changes limited to the covers, as long as they preserve ++the title of the Document and satisfy these conditions, can be treated ++as verbatim copying in other respects. ++ ++If the required texts for either cover are too voluminous to fit ++legibly, you should put the first ones listed (as many as fit ++reasonably) on the actual cover, and continue the rest onto adjacent ++pages. ++ ++If you publish or distribute Opaque copies of the Document numbering ++more than 100, you must either include a machine-readable Transparent ++copy along with each Opaque copy, or state in or with each Opaque copy ++a computer-network location from which the general network-using ++public has access to download using public-standard network protocols ++a complete Transparent copy of the Document, free of added material. ++If you use the latter option, you must take reasonably prudent steps, ++when you begin distribution of Opaque copies in quantity, to ensure ++that this Transparent copy will remain thus accessible at the stated ++location until at least one year after the last time you distribute an ++Opaque copy (directly or through your agents or retailers) of that ++edition to the public. ++ ++It is requested, but not required, that you contact the authors of the ++Document well before redistributing any large number of copies, to give ++them a chance to provide you with an updated version of the Document. ++ ++@item ++MODIFICATIONS ++ ++You may copy and distribute a Modified Version of the Document under ++the conditions of sections 2 and 3 above, provided that you release ++the Modified Version under precisely this License, with the Modified ++Version filling the role of the Document, thus licensing distribution ++and modification of the Modified Version to whoever possesses a copy ++of it. In addition, you must do these things in the Modified Version: ++ ++@enumerate A ++@item ++Use in the Title Page (and on the covers, if any) a title distinct ++from that of the Document, and from those of previous versions ++(which should, if there were any, be listed in the History section ++of the Document). You may use the same title as a previous version ++if the original publisher of that version gives permission. ++ ++@item ++List on the Title Page, as authors, one or more persons or entities ++responsible for authorship of the modifications in the Modified ++Version, together with at least five of the principal authors of the ++Document (all of its principal authors, if it has fewer than five), ++unless they release you from this requirement. ++ ++@item ++State on the Title page the name of the publisher of the ++Modified Version, as the publisher. ++ ++@item ++Preserve all the copyright notices of the Document. ++ ++@item ++Add an appropriate copyright notice for your modifications ++adjacent to the other copyright notices. ++ ++@item ++Include, immediately after the copyright notices, a license notice ++giving the public permission to use the Modified Version under the ++terms of this License, in the form shown in the Addendum below. ++ ++@item ++Preserve in that license notice the full lists of Invariant Sections ++and required Cover Texts given in the Document's license notice. ++ ++@item ++Include an unaltered copy of this License. ++ ++@item ++Preserve the section Entitled ``History'', Preserve its Title, and add ++to it an item stating at least the title, year, new authors, and ++publisher of the Modified Version as given on the Title Page. If ++there is no section Entitled ``History'' in the Document, create one ++stating the title, year, authors, and publisher of the Document as ++given on its Title Page, then add an item describing the Modified ++Version as stated in the previous sentence. ++ ++@item ++Preserve the network location, if any, given in the Document for ++public access to a Transparent copy of the Document, and likewise ++the network locations given in the Document for previous versions ++it was based on. These may be placed in the ``History'' section. ++You may omit a network location for a work that was published at ++least four years before the Document itself, or if the original ++publisher of the version it refers to gives permission. ++ ++@item ++For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve ++the Title of the section, and preserve in the section all the ++substance and tone of each of the contributor acknowledgements and/or ++dedications given therein. ++ ++@item ++Preserve all the Invariant Sections of the Document, ++unaltered in their text and in their titles. Section numbers ++or the equivalent are not considered part of the section titles. ++ ++@item ++Delete any section Entitled ``Endorsements''. Such a section ++may not be included in the Modified Version. ++ ++@item ++Do not retitle any existing section to be Entitled ``Endorsements'' or ++to conflict in title with any Invariant Section. ++ ++@item ++Preserve any Warranty Disclaimers. ++@end enumerate ++ ++If the Modified Version includes new front-matter sections or ++appendices that qualify as Secondary Sections and contain no material ++copied from the Document, you may at your option designate some or all ++of these sections as invariant. To do this, add their titles to the ++list of Invariant Sections in the Modified Version's license notice. ++These titles must be distinct from any other section titles. ++ ++You may add a section Entitled ``Endorsements'', provided it contains ++nothing but endorsements of your Modified Version by various ++parties---for example, statements of peer review or that the text has ++been approved by an organization as the authoritative definition of a ++standard. ++ ++You may add a passage of up to five words as a Front-Cover Text, and a ++passage of up to 25 words as a Back-Cover Text, to the end of the list ++of Cover Texts in the Modified Version. Only one passage of ++Front-Cover Text and one of Back-Cover Text may be added by (or ++through arrangements made by) any one entity. If the Document already ++includes a cover text for the same cover, previously added by you or ++by arrangement made by the same entity you are acting on behalf of, ++you may not add another; but you may replace the old one, on explicit ++permission from the previous publisher that added the old one. ++ ++The author(s) and publisher(s) of the Document do not by this License ++give permission to use their names for publicity for or to assert or ++imply endorsement of any Modified Version. ++ ++@item ++COMBINING DOCUMENTS ++ ++You may combine the Document with other documents released under this ++License, under the terms defined in section 4 above for modified ++versions, provided that you include in the combination all of the ++Invariant Sections of all of the original documents, unmodified, and ++list them all as Invariant Sections of your combined work in its ++license notice, and that you preserve all their Warranty Disclaimers. ++ ++The combined work need only contain one copy of this License, and ++multiple identical Invariant Sections may be replaced with a single ++copy. If there are multiple Invariant Sections with the same name but ++different contents, make the title of each such section unique by ++adding at the end of it, in parentheses, the name of the original ++author or publisher of that section if known, or else a unique number. ++Make the same adjustment to the section titles in the list of ++Invariant Sections in the license notice of the combined work. ++ ++In the combination, you must combine any sections Entitled ``History'' ++in the various original documents, forming one section Entitled ++``History''; likewise combine any sections Entitled ``Acknowledgements'', ++and any sections Entitled ``Dedications''. You must delete all ++sections Entitled ``Endorsements.'' ++ ++@item ++COLLECTIONS OF DOCUMENTS ++ ++You may make a collection consisting of the Document and other documents ++released under this License, and replace the individual copies of this ++License in the various documents with a single copy that is included in ++the collection, provided that you follow the rules of this License for ++verbatim copying of each of the documents in all other respects. ++ ++You may extract a single document from such a collection, and distribute ++it individually under this License, provided you insert a copy of this ++License into the extracted document, and follow this License in all ++other respects regarding verbatim copying of that document. ++ ++@item ++AGGREGATION WITH INDEPENDENT WORKS ++ ++A compilation of the Document or its derivatives with other separate ++and independent documents or works, in or on a volume of a storage or ++distribution medium, is called an ``aggregate'' if the copyright ++resulting from the compilation is not used to limit the legal rights ++of the compilation's users beyond what the individual works permit. ++When the Document is included in an aggregate, this License does not ++apply to the other works in the aggregate which are not themselves ++derivative works of the Document. ++ ++If the Cover Text requirement of section 3 is applicable to these ++copies of the Document, then if the Document is less than one half of ++the entire aggregate, the Document's Cover Texts may be placed on ++covers that bracket the Document within the aggregate, or the ++electronic equivalent of covers if the Document is in electronic form. ++Otherwise they must appear on printed covers that bracket the whole ++aggregate. ++ ++@item ++TRANSLATION ++ ++Translation is considered a kind of modification, so you may ++distribute translations of the Document under the terms of section 4. ++Replacing Invariant Sections with translations requires special ++permission from their copyright holders, but you may include ++translations of some or all Invariant Sections in addition to the ++original versions of these Invariant Sections. You may include a ++translation of this License, and all the license notices in the ++Document, and any Warranty Disclaimers, provided that you also include ++the original English version of this License and the original versions ++of those notices and disclaimers. In case of a disagreement between ++the translation and the original version of this License or a notice ++or disclaimer, the original version will prevail. ++ ++If a section in the Document is Entitled ``Acknowledgements'', ++``Dedications'', or ``History'', the requirement (section 4) to Preserve ++its Title (section 1) will typically require changing the actual ++title. ++ ++@item ++TERMINATION ++ ++You may not copy, modify, sublicense, or distribute the Document ++except as expressly provided under this License. Any attempt ++otherwise to copy, modify, sublicense, or distribute it is void, and ++will automatically terminate your rights under this License. ++ ++However, if you cease all violation of this License, then your license ++from a particular copyright holder is reinstated (a) provisionally, ++unless and until the copyright holder explicitly and finally ++terminates your license, and (b) permanently, if the copyright holder ++fails to notify you of the violation by some reasonable means prior to ++60 days after the cessation. ++ ++Moreover, your license from a particular copyright holder is ++reinstated permanently if the copyright holder notifies you of the ++violation by some reasonable means, this is the first time you have ++received notice of violation of this License (for any work) from that ++copyright holder, and you cure the violation prior to 30 days after ++your receipt of the notice. ++ ++Termination of your rights under this section does not terminate the ++licenses of parties who have received copies or rights from you under ++this License. If your rights have been terminated and not permanently ++reinstated, receipt of a copy of some or all of the same material does ++not give you any rights to use it. ++ ++@item ++FUTURE REVISIONS OF THIS LICENSE ++ ++The Free Software Foundation may publish new, revised versions ++of the GNU Free Documentation License from time to time. Such new ++versions will be similar in spirit to the present version, but may ++differ in detail to address new problems or concerns. See ++@uref{http://www.gnu.org/copyleft/}. ++ ++Each version of the License is given a distinguishing version number. ++If the Document specifies that a particular numbered version of this ++License ``or any later version'' applies to it, you have the option of ++following the terms and conditions either of that specified version or ++of any later version that has been published (not as a draft) by the ++Free Software Foundation. If the Document does not specify a version ++number of this License, you may choose any version ever published (not ++as a draft) by the Free Software Foundation. If the Document ++specifies that a proxy can decide which future versions of this ++License can be used, that proxy's public statement of acceptance of a ++version permanently authorizes you to choose that version for the ++Document. ++ ++@item ++RELICENSING ++ ++``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any ++World Wide Web server that publishes copyrightable works and also ++provides prominent facilities for anybody to edit those works. A ++public wiki that anybody can edit is an example of such a server. A ++``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the ++site means any set of copyrightable works thus published on the MMC ++site. ++ ++``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 ++license published by Creative Commons Corporation, a not-for-profit ++corporation with a principal place of business in San Francisco, ++California, as well as future copyleft versions of that license ++published by that same organization. ++ ++``Incorporate'' means to publish or republish a Document, in whole or ++in part, as part of another Document. ++ ++An MMC is ``eligible for relicensing'' if it is licensed under this ++License, and if all works that were first published under this License ++somewhere other than this MMC, and subsequently incorporated in whole ++or in part into the MMC, (1) had no cover texts or invariant sections, ++and (2) were thus incorporated prior to November 1, 2008. ++ ++The operator of an MMC Site may republish an MMC contained in the site ++under CC-BY-SA on the same site at any time before August 1, 2009, ++provided the MMC is eligible for relicensing. ++ ++@end enumerate ++ ++@page ++@heading ADDENDUM: How to use this License for your documents ++ ++To use this License in a document you have written, include a copy of ++the License in the document and put the following copyright and ++license notices just after the title page: ++ ++@smallexample ++@group ++ Copyright (C) @var{year} @var{your name}. ++ Permission is granted to copy, distribute and/or modify this document ++ under the terms of the GNU Free Documentation License, Version 1.3 ++ or any later version published by the Free Software Foundation; ++ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover ++ Texts. A copy of the license is included in the section entitled ``GNU ++ Free Documentation License''. ++@end group ++@end smallexample ++ ++If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, ++replace the ``with@dots{}Texts.'' line with this: ++ ++@smallexample ++@group ++ with the Invariant Sections being @var{list their titles}, with ++ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts ++ being @var{list}. ++@end group ++@end smallexample ++ ++If you have Invariant Sections without Cover Texts, or some other ++combination of the three, merge those two alternatives to suit the ++situation. ++ ++If your document contains nontrivial examples of program code, we ++recommend releasing these examples in parallel under your choice of ++free software license, such as the GNU General Public License, ++to permit their use in free software. ++ ++ ++@c Local Variables: ++@c ispell-local-pdict: "ispell-dict" ++@c End: ++ ++@ignore ++ arch-tag: 839f250e-4800-4bc9-bd28-49ec7968331f ++@end ignore ++ +diff --git a/doc/lispintro/drawers.eps b/doc/lispintro/drawers.eps +new file mode 100644 +index 0000000..01813d1 +--- /dev/null ++++ b/doc/lispintro/drawers.eps +@@ -0,0 +1,511 @@ ++%!PS-Adobe-3.0 EPSF-3.0 ++%%BoundingBox: 34 577 324 778 ++%%Title: chest-of-drawers-diagram-new ++%%CreationDate: Fri Sep 14 17:40:57 2001 ++%%Creator: Tgif-4.1.35 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++%%ProducedBy: (unknown) ++%%Pages: 1 ++%%DocumentFonts: (atend) ++%%EndComments ++%%BeginProlog ++ ++% Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 53 dict def ++tgifdict begin ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/TGEL % tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/TGMAX ++ { exch dup 3 1 roll exch dup 3 1 roll gt { pop } { exch pop } ifelse ++ } def ++/TGMIN ++ { exch dup 3 1 roll exch dup 3 1 roll lt { pop } { exch pop } ifelse ++ } def ++/TGSW { stringwidth pop } def ++ ++/bd { bind def } bind def ++ ++/GS { gsave } bd ++/GR { grestore } bd ++/NP { newpath } bd ++/CP { closepath } bd ++/CHP { charpath } bd ++/CT { curveto } bd ++/L { lineto } bd ++/RL { rlineto } bd ++/M { moveto } bd ++/RM { rmoveto } bd ++/S { stroke } bd ++/F { fill } bd ++/TR { translate } bd ++/RO { rotate } bd ++/SC { scale } bd ++/MU { mul } bd ++/DI { div } bd ++/DU { dup } bd ++/NE { neg } bd ++/AD { add } bd ++/SU { sub } bd ++/PO { pop } bd ++/EX { exch } bd ++/CO { concat } bd ++/CL { clip } bd ++/EC { eoclip } bd ++/EF { eofill } bd ++/IM { image } bd ++/IMM { imagemask } bd ++/ARY { array } bd ++/SG { setgray } bd ++/RG { setrgbcolor } bd ++/SD { setdash } bd ++/W { setlinewidth } bd ++/SM { setmiterlimit } bd ++/SLC { setlinecap } bd ++/SLJ { setlinejoin } bd ++/SH { show } bd ++/FF { findfont } bd ++/MS { makefont setfont } bd ++/AR { arcto 4 {pop} repeat } bd ++/CURP { currentpoint } bd ++/FLAT { flattenpath strokepath clip newpath } bd ++/TGSM { tgiforigctm setmatrix } def ++/TGRM { savematrix setmatrix } def ++ ++end ++ ++%%EndProlog ++%%Page: 1 1 ++ ++%%PageBoundingBox: 34 577 324 778 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 SM ++1 W ++ ++0 SG ++ ++72 0 MU 72 11 MU TR ++72 128 DI 100.000 MU 100 DI DU NE SC ++ ++GS ++ ++/tgiforigctm matrix currentmatrix def ++ ++% BOX ++0 SG ++GS ++ 10 SM ++ GS ++ NP 64 104 M 255 104 L 255 360 L 64 360 L CP ++ S ++ GR ++GR ++ ++% POLY/OPEN-SPLINE ++0 SG ++GS ++ NP ++ 65 296 M ++ 254 296 L ++ TGSM ++ 1 W ++ S ++GR ++ ++% POLY/OPEN-SPLINE ++0 SG ++GS ++ NP ++ 63 233 M ++ 255 233 L ++ TGSM ++ 1 W ++ S ++GR ++ ++% POLY/OPEN-SPLINE ++0 SG ++GS ++ NP ++ 63 169 M ++ 255 169 L ++ TGSM ++ 1 W ++ S ++GR ++ ++% POLY/OPEN-SPLINE ++0 SG ++GS ++ NP ++ 251 362 M ++ 251 361 L ++ 251 379 L ++ 244 379 L ++ 229 361 L ++ TGSM ++ 1 W ++ S ++GR ++ ++% OVAL ++0 SG ++GS ++ GS ++ NP 160 72 10 6 TGEL ++ S ++ GR ++GR ++ ++% POLY/OPEN-SPLINE ++0 SG ++GS ++ NP ++ 63 104 M ++ 128 64 L ++ 138 69 L ++ TGSM ++ 1 W ++ S ++GR ++ ++% POLY/OPEN-SPLINE ++0 SG ++GS ++ NP ++ 255 103 M ++ 190 63 L ++ 180 68 L ++ TGSM ++ 1 W ++ S ++GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 160 152 M ++ GS ++ GS ++ 0 ++ /Courier FF [17 0 0 -17 0 0] MS ++ (symbol name) TGSW ++ AD ++ GR ++ 2 DI NE 0 RM ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ (symbol name) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 160 41 M ++ GS ++ GS ++ 0 ++ /Courier FF [17 0 0 -17 0 0] MS ++ (Chest of Drawers) TGSW ++ AD ++ GR ++ 2 DI NE 0 RM ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ (Chest of Drawers) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 344 41 M ++ GS ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ (Contents of Drawers) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 344 160 M ++ GS ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ (bouquet) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 344 220 M ++ GS ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ ([none]) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 344 279 M ++ GS ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ (\(rose violet buttercup\)) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 344 337 M ++ GS ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ ([not described here]) SH ++ GR ++ GR ++ ++% POLY/OPEN-SPLINE ++0 SG ++GS ++ NP ++ 68 362 M ++ 68 361 L ++ 68 379 L ++ 75 379 L ++ 90 361 L ++ TGSM ++ 1 W ++ S ++GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 158 132 M ++ GS ++ GS ++ 0 ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (directions to) TGSW ++ AD ++ GR ++ 2 DI NE 0 RM ++ 0 SG ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (directions to) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 345 139 M ++ GS ++ 0 SG ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (map to) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 350 259 M ++ GS ++ 0 SG ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (map to) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 159 213 M ++ GS ++ GS ++ 0 ++ /Courier FF [17 0 0 -17 0 0] MS ++ (symbol definition) TGSW ++ AD ++ GR ++ 2 DI NE 0 RM ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ (symbol definition) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 159 195 M ++ GS ++ GS ++ 0 ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (directions to) TGSW ++ AD ++ GR ++ 2 DI NE 0 RM ++ 0 SG ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (directions to) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 160 276 M ++ GS ++ GS ++ 0 ++ /Courier FF [17 0 0 -17 0 0] MS ++ (variable name) TGSW ++ AD ++ GR ++ 2 DI NE 0 RM ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ (variable name) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 158 260 M ++ GS ++ GS ++ 0 ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (directions to) TGSW ++ AD ++ GR ++ 2 DI NE 0 RM ++ 0 SG ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (directions to) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 160 339 M ++ GS ++ GS ++ 0 ++ /Courier FF [17 0 0 -17 0 0] MS ++ (property list) TGSW ++ AD ++ GR ++ 2 DI NE 0 RM ++ 0 SG ++ /Courier FF [17 0 0 -17 0 0] MS ++ (property list) SH ++ GR ++ GR ++ ++% TEXT ++NP ++0 SG ++ GS ++ 1 W ++ 158 323 M ++ GS ++ GS ++ 0 ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (directions to) TGSW ++ AD ++ GR ++ 2 DI NE 0 RM ++ 0 SG ++ /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS ++ (directions to) SH ++ GR ++ GR ++ ++GR ++tgifsavedpage restore ++end ++showpage ++ ++%%Trailer ++%MatchingCreationDate: Fri Sep 14 17:40:57 2001 ++%%DocumentFonts: NewCenturySchlbk-Roman ++%%+ Courier ++%%EOF +diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi +new file mode 100644 +index 0000000..3f2d5f0 +--- /dev/null ++++ b/doc/lispintro/emacs-lisp-intro.texi +@@ -0,0 +1,22281 @@ ++\input texinfo @c -*-texinfo-*- ++@comment %**start of header ++@setfilename ../../info/eintr ++@c setfilename emacs-lisp-intro.info ++@c sethtmlfilename emacs-lisp-intro.html ++@settitle Programming in Emacs Lisp ++@syncodeindex vr cp ++@syncodeindex fn cp ++@finalout ++ ++@c --------- ++@c <<<< For hard copy printing, this file is now ++@c set for smallbook, which works for all sizes ++@c of paper, and with Postscript figures >>>> ++@set smallbook ++@ifset smallbook ++@smallbook ++@clear largebook ++@end ifset ++@set print-postscript-figures ++@c set largebook ++@c clear print-postscript-figures ++@c --------- ++ ++@comment %**end of header ++ ++@c per rms and peterb, use 10pt fonts for the main text, mostly to ++@c save on paper cost. ++@c Do this inside @tex for now, so current makeinfo does not complain. ++@tex ++@ifset smallbook ++@fonttextsize 10 ++\global\let\urlcolor=\Black % don't print links in grayscale ++\global\let\linkcolor=\Black ++@end ifset ++\global\hbadness=6666 % don't worry about not-too-underfull boxes ++@end tex ++ ++@set edition-number 3.08 ++@set update-date 4 October 2008 ++@ignore ++ ## Summary of shell commands to create various output formats: ++ ++ pushd /usr/local/src/emacs/lispintro/ ++ ## pushd /u/intro/ ++ ++ ## Info output ++ makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi ++ ++ ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr")) ++ ++ ## DVI output ++ texi2dvi emacs-lisp-intro.texi ++ ++ ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi & ++ ++ ## HTML output ++ makeinfo --html --no-split --verbose emacs-lisp-intro.texi ++ ++ ## galeon emacs-lisp-intro.html ++ ++ ## Plain text output ++ makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ ++ --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi ++ ++ popd ++ ++# as user `root' ++# insert thumbdrive ++ mtusb # mount -v -t ext3 /dev/sda /mnt ++ cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi ++ umtusb # umount -v /mnt ++# remove thumbdrive ++ ++ ## Other shell commands ++ ++ pushd /usr/local/src/emacs/lispintro/ ++ ## pushd /u/intro/ ++ ++ ## PDF ++ texi2dvi --pdf emacs-lisp-intro.texi ++ # xpdf emacs-lisp-intro.pdf & ++ ++ ## DocBook -- note file extension ++ makeinfo --docbook --no-split --paragraph-indent=0 \ ++ --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi ++ ++ ## XML with a Texinfo DTD -- note file extension ++ makeinfo --xml --no-split --paragraph-indent=0 \ ++ --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi ++ ++ ## PostScript (needs DVI) ++ # gv emacs-lisp-intro.ps & ++ # Create DVI if we lack it ++ # texi2dvi emacs-lisp-intro.texi ++ dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps ++ ++ ## RTF (needs HTML) ++ # Use OpenOffice to view RTF ++ # Create HTML if we lack it ++ # makeinfo --no-split --html emacs-lisp-intro.texi ++ /usr/local/src/html2rtf.pl emacs-lisp-intro.html ++ ++ ## LaTeX (needs RTF) ++ /usr/bin/rtf2latex emacs-lisp-intro.rtf ++ ++ popd ++ ++@end ignore ++ ++@c ================ Included Figures ================ ++ ++@c Set print-postscript-figures if you print PostScript figures. ++@c If you clear this, the ten figures will be printed as ASCII diagrams. ++@c (This is not relevant to Info, since Info only handles ASCII.) ++@c Your site may require editing changes to print PostScript; in this ++@c case, search for `print-postscript-figures' and make appropriate changes. ++ ++@c ================ How to Create an Info file ================ ++ ++@c If you have `makeinfo' installed, run the following command ++ ++@c makeinfo emacs-lisp-intro.texi ++ ++@c or, if you want a single, large Info file, and no paragraph indents: ++@c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi ++ ++@c After creating the Info file, edit your Info `dir' file, if the ++@c `dircategory' section below does not enable your system to ++@c install the manual automatically. ++@c (The `dir' file is often in the `/usr/local/share/info/' directory.) ++ ++@c ================ How to Create an HTML file ================ ++ ++@c To convert to HTML format ++@c makeinfo --html --no-split --verbose emacs-lisp-intro.texi ++ ++@c ================ How to Print a Book in Various Sizes ================ ++ ++@c This book can be printed in any of three different sizes. ++@c In the above header, set @-commands appropriately. ++ ++@c 7 by 9.25 inches: ++@c @smallbook ++@c @clear largebook ++ ++@c 8.5 by 11 inches: ++@c @c smallbook ++@c @set largebook ++ ++@c European A4 size paper: ++@c @c smallbook ++@c @afourpaper ++@c @set largebook ++ ++@c ================ How to Typeset and Print ================ ++ ++@c If you do not include PostScript figures, run either of the ++@c following command sequences, or similar commands suited to your ++@c system: ++ ++@c texi2dvi emacs-lisp-intro.texi ++@c lpr -d emacs-lisp-intro.dvi ++ ++@c or else: ++ ++@c tex emacs-lisp-intro.texi ++@c texindex emacs-lisp-intro.?? ++@c tex emacs-lisp-intro.texi ++@c lpr -d emacs-lisp-intro.dvi ++ ++@c If you include the PostScript figures, and you have old software, ++@c you may need to convert the .dvi file to a .ps file before ++@c printing. Run either of the following command sequences, or one ++@c similar: ++@c ++@c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps ++@c ++@c or else: ++@c ++@c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps ++@c ++ ++@c (Note: if you edit the book so as to change the length of the ++@c table of contents, you may have to change the value of `pageno' below.) ++ ++@c ================ End of Formatting Sections ================ ++ ++@c For next or subsequent edition: ++@c create function using with-output-to-temp-buffer ++@c create a major mode, with keymaps ++@c run an asynchronous process, like grep or diff ++ ++@c For 8.5 by 11 inch format: do not use such a small amount of ++@c whitespace between paragraphs as smallbook format ++@ifset largebook ++@tex ++\global\parskip 6pt plus 1pt ++@end tex ++@end ifset ++ ++@c For all sized formats: print within-book cross ++@c reference with ``...'' rather than [...] ++ ++@c This works with the texinfo.tex file, version 2003-05-04.08, ++@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution. ++ ++@tex ++\if \xrefprintnodename ++ \global\def\xrefprintnodename#1{\unskip, ``#1''} ++ \else ++ \global\def\xrefprintnodename#1{ ``#1''} ++\fi ++% \global\def\xrefprintnodename#1{, ``#1''} ++@end tex ++ ++@c ---------------------------------------------------- ++ ++@dircategory Emacs ++@direntry ++* Emacs Lisp Intro: (eintr). ++ A simple introduction to Emacs Lisp programming. ++@end direntry ++ ++@copying ++This is an @cite{Introduction to Programming in Emacs Lisp}, for ++people who are not programmers. ++@sp 1 ++Edition @value{edition-number}, @value{update-date} ++@sp 1 ++Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, ++ 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@sp 1 ++ ++@iftex ++Published by the:@* ++ ++GNU Press, @hfill @uref{http://www.gnupress.org}@* ++a division of the @hfill General: @email{press@@gnu.org}@* ++Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@* ++51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@* ++Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@* ++@end iftex ++ ++@ifnottex ++Published by the: ++ ++@example ++GNU Press, Website: http://www.gnupress.org ++a division of the General: press@@gnu.org ++Free Software Foundation, Inc. Orders: sales@@gnu.org ++51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942 ++Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652 ++@end example ++@end ifnottex ++ ++@sp 1 ++@c Printed copies are available for $30 each.@* ++ISBN 1-882114-43-4 ++ ++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; there ++being no Invariant Section, 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 copying ++ ++@c half title; two lines here, so do not use `shorttitlepage' ++@tex ++{\begingroup% ++ \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% ++ \endgroup}% ++{\begingroup\hbox{}\vskip 0.25in \chaprm% ++ \centerline{Programming in Emacs Lisp}% ++ \endgroup\page\hbox{}\page} ++@end tex ++ ++@titlepage ++@sp 6 ++@center @titlefont{An Introduction to} ++@sp 2 ++@center @titlefont{Programming in Emacs Lisp} ++@sp 2 ++@center Revised Third Edition ++@sp 4 ++@center by Robert J. Chassell ++ ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@iftex ++@headings off ++@evenheading @thispage @| @| @thischapter ++@oddheading @thissection @| @| @thispage ++@end iftex ++ ++@ifnothtml ++@c Keep T.O.C. short by tightening up for largebook ++@ifset largebook ++@tex ++\global\parskip 2pt plus 1pt ++\global\advance\baselineskip by -1pt ++@end tex ++@end ifset ++@end ifnothtml ++ ++@shortcontents ++@contents ++ ++@ifnottex ++@node Top, Preface, (dir), (dir) ++@top An Introduction to Programming in Emacs Lisp ++ ++@insertcopying ++ ++This master menu first lists each chapter and index; then it lists ++every node in every chapter. ++@end ifnottex ++ ++@c >>>> Set pageno appropriately <<<< ++ ++@c The first page of the Preface is a roman numeral; it is the first ++@c right handed page after the Table of Contents; hence the following ++@c setting must be for an odd negative number. ++ ++@c iftex ++@c global@pageno = -11 ++@c end iftex ++ ++@menu ++* Preface:: What to look for. ++* List Processing:: What is Lisp? ++* Practicing Evaluation:: Running several programs. ++* Writing Defuns:: How to write function definitions. ++* Buffer Walk Through:: Exploring a few buffer-related functions. ++* More Complex:: A few, even more complex functions. ++* Narrowing & Widening:: Restricting your and Emacs attention to ++ a region. ++* car cdr & cons:: Fundamental functions in Lisp. ++* Cutting & Storing Text:: Removing text and saving it. ++* List Implementation:: How lists are implemented in the computer. ++* Yanking:: Pasting stored text. ++* Loops & Recursion:: How to repeat a process. ++* Regexp Search:: Regular expression searches. ++* Counting Words:: A review of repetition and regexps. ++* Words in a defun:: Counting words in a @code{defun}. ++* Readying a Graph:: A prototype graph printing function. ++* Emacs Initialization:: How to write a @file{.emacs} file. ++* Debugging:: How to run the Emacs Lisp debuggers. ++* Conclusion:: Now you have the basics. ++* the-the:: An appendix: how to find reduplicated words. ++* Kill Ring:: An appendix: how the kill ring works. ++* Full Graph:: How to create a graph with labelled axes. ++* Free Software and Free Manuals:: ++* GNU Free Documentation License:: ++* Index:: ++* About the Author:: ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ ++Preface ++ ++* Why:: Why learn Emacs Lisp? ++* On Reading this Text:: Read, gain familiarity, pick up habits.... ++* Who You Are:: For whom this is written. ++* Lisp History:: ++* Note for Novices:: You can read this as a novice. ++* Thank You:: ++ ++List Processing ++ ++* Lisp Lists:: What are lists? ++* Run a Program:: Any list in Lisp is a program ready to run. ++* Making Errors:: Generating an error message. ++* Names & Definitions:: Names of symbols and function definitions. ++* Lisp Interpreter:: What the Lisp interpreter does. ++* Evaluation:: Running a program. ++* Variables:: Returning a value from a variable. ++* Arguments:: Passing information to a function. ++* set & setq:: Setting the value of a variable. ++* Summary:: The major points. ++* Error Message Exercises:: ++ ++Lisp Lists ++ ++* Numbers Lists:: List have numbers, other lists, in them. ++* Lisp Atoms:: Elemental entities. ++* Whitespace in Lists:: Formatting lists to be readable. ++* Typing Lists:: How GNU Emacs helps you type lists. ++ ++The Lisp Interpreter ++ ++* Complications:: Variables, Special forms, Lists within. ++* Byte Compiling:: Specially processing code for speed. ++ ++Evaluation ++ ++* How the Interpreter Acts:: Returns and Side Effects... ++* Evaluating Inner Lists:: Lists within lists... ++ ++Variables ++ ++* fill-column Example:: ++* Void Function:: The error message for a symbol ++ without a function. ++* Void Variable:: The error message for a symbol without a value. ++ ++Arguments ++ ++* Data types:: Types of data passed to a function. ++* Args as Variable or List:: An argument can be the value ++ of a variable or list. ++* Variable Number of Arguments:: Some functions may take a ++ variable number of arguments. ++* Wrong Type of Argument:: Passing an argument of the wrong type ++ to a function. ++* message:: A useful function for sending messages. ++ ++Setting the Value of a Variable ++ ++* Using set:: Setting values. ++* Using setq:: Setting a quoted value. ++* Counting:: Using @code{setq} to count. ++ ++Practicing Evaluation ++ ++* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} ++ causes evaluation. ++* Buffer Names:: Buffers and files are different. ++* Getting Buffers:: Getting a buffer itself, not merely its name. ++* Switching Buffers:: How to change to another buffer. ++* Buffer Size & Locations:: Where point is located and the size of ++ the buffer. ++* Evaluation Exercise:: ++ ++How To Write Function Definitions ++ ++* Primitive Functions:: ++* defun:: The @code{defun} special form. ++* Install:: Install a function definition. ++* Interactive:: Making a function interactive. ++* Interactive Options:: Different options for @code{interactive}. ++* Permanent Installation:: Installing code permanently. ++* let:: Creating and initializing local variables. ++* if:: What if? ++* else:: If--then--else expressions. ++* Truth & Falsehood:: What Lisp considers false and true. ++* save-excursion:: Keeping track of point, mark, and buffer. ++* Review:: ++* defun Exercises:: ++ ++Install a Function Definition ++ ++* Effect of installation:: ++* Change a defun:: How to change a function definition. ++ ++Make a Function Interactive ++ ++* Interactive multiply-by-seven:: An overview. ++* multiply-by-seven in detail:: The interactive version. ++ ++@code{let} ++ ++* Prevent confusion:: ++* Parts of let Expression:: ++* Sample let Expression:: ++* Uninitialized let Variables:: ++ ++The @code{if} Special Form ++ ++* if in more detail:: ++* type-of-animal in detail:: An example of an @code{if} expression. ++ ++Truth and Falsehood in Emacs Lisp ++ ++* nil explained:: @code{nil} has two meanings. ++ ++@code{save-excursion} ++ ++* Point and mark:: A review of various locations. ++* Template for save-excursion:: ++ ++A Few Buffer--Related Functions ++ ++* Finding More:: How to find more information. ++* simplified-beginning-of-buffer:: Shows @code{goto-char}, ++ @code{point-min}, and @code{push-mark}. ++* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. ++* append-to-buffer:: Uses @code{save-excursion} and ++ @code{insert-buffer-substring}. ++* Buffer Related Review:: Review. ++* Buffer Exercises:: ++ ++The Definition of @code{mark-whole-buffer} ++ ++* mark-whole-buffer overview:: ++* Body of mark-whole-buffer:: Only three lines of code. ++ ++The Definition of @code{append-to-buffer} ++ ++* append-to-buffer overview:: ++* append interactive:: A two part interactive expression. ++* append-to-buffer body:: Incorporates a @code{let} expression. ++* append save-excursion:: How the @code{save-excursion} works. ++ ++A Few More Complex Functions ++ ++* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. ++* insert-buffer:: Read-only, and with @code{or}. ++* beginning-of-buffer:: Shows @code{goto-char}, ++ @code{point-min}, and @code{push-mark}. ++* Second Buffer Related Review:: ++* optional Exercise:: ++ ++The Definition of @code{insert-buffer} ++ ++* insert-buffer code:: ++* insert-buffer interactive:: When you can read, but not write. ++* insert-buffer body:: The body has an @code{or} and a @code{let}. ++* if & or:: Using an @code{if} instead of an @code{or}. ++* Insert or:: How the @code{or} expression works. ++* Insert let:: Two @code{save-excursion} expressions. ++* New insert-buffer:: ++ ++The Interactive Expression in @code{insert-buffer} ++ ++* Read-only buffer:: When a buffer cannot be modified. ++* b for interactive:: An existing buffer or else its name. ++ ++Complete Definition of @code{beginning-of-buffer} ++ ++* Optional Arguments:: ++* beginning-of-buffer opt arg:: Example with optional argument. ++* beginning-of-buffer complete:: ++ ++@code{beginning-of-buffer} with an Argument ++ ++* Disentangle beginning-of-buffer:: ++* Large buffer case:: ++* Small buffer case:: ++ ++Narrowing and Widening ++ ++* Narrowing advantages:: The advantages of narrowing ++* save-restriction:: The @code{save-restriction} special form. ++* what-line:: The number of the line that point is on. ++* narrow Exercise:: ++ ++@code{car}, @code{cdr}, @code{cons}: Fundamental Functions ++ ++* Strange Names:: An historical aside: why the strange names? ++* car & cdr:: Functions for extracting part of a list. ++* cons:: Constructing a list. ++* nthcdr:: Calling @code{cdr} repeatedly. ++* nth:: ++* setcar:: Changing the first element of a list. ++* setcdr:: Changing the rest of a list. ++* cons Exercise:: ++ ++@code{cons} ++ ++* Build a list:: ++* length:: How to find the length of a list. ++ ++Cutting and Storing Text ++ ++* Storing Text:: Text is stored in a list. ++* zap-to-char:: Cutting out text up to a character. ++* kill-region:: Cutting text out of a region. ++* copy-region-as-kill:: A definition for copying text. ++* Digression into C:: Minor note on C programming language macros. ++* defvar:: How to give a variable an initial value. ++* cons & search-fwd Review:: ++* search Exercises:: ++ ++@code{zap-to-char} ++ ++* Complete zap-to-char:: The complete implementation. ++* zap-to-char interactive:: A three part interactive expression. ++* zap-to-char body:: A short overview. ++* search-forward:: How to search for a string. ++* progn:: The @code{progn} special form. ++* Summing up zap-to-char:: Using @code{point} and @code{search-forward}. ++ ++@code{kill-region} ++ ++* Complete kill-region:: The function definition. ++* condition-case:: Dealing with a problem. ++* Lisp macro:: ++ ++@code{copy-region-as-kill} ++ ++* Complete copy-region-as-kill:: The complete function definition. ++* copy-region-as-kill body:: The body of @code{copy-region-as-kill}. ++ ++The Body of @code{copy-region-as-kill} ++ ++* last-command & this-command:: ++* kill-append function:: ++* kill-new function:: ++ ++Initializing a Variable with @code{defvar} ++ ++* See variable current value:: ++* defvar and asterisk:: ++ ++How Lists are Implemented ++ ++* Lists diagrammed:: ++* Symbols as Chest:: Exploring a powerful metaphor. ++* List Exercise:: ++ ++Yanking Text Back ++ ++* Kill Ring Overview:: ++* kill-ring-yank-pointer:: The kill ring is a list. ++* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. ++ ++Loops and Recursion ++ ++* while:: Causing a stretch of code to repeat. ++* dolist dotimes:: ++* Recursion:: Causing a function to call itself. ++* Looping exercise:: ++ ++@code{while} ++ ++* Looping with while:: Repeat so long as test returns true. ++* Loop Example:: A @code{while} loop that uses a list. ++* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. ++* Incrementing Loop:: A loop with an incrementing counter. ++* Incrementing Loop Details:: ++* Decrementing Loop:: A loop with a decrementing counter. ++ ++Details of an Incrementing Loop ++ ++* Incrementing Example:: Counting pebbles in a triangle. ++* Inc Example parts:: The parts of the function definition. ++* Inc Example altogether:: Putting the function definition together. ++ ++Loop with a Decrementing Counter ++ ++* Decrementing Example:: More pebbles on the beach. ++* Dec Example parts:: The parts of the function definition. ++* Dec Example altogether:: Putting the function definition together. ++ ++Save your time: @code{dolist} and @code{dotimes} ++ ++* dolist:: ++* dotimes:: ++ ++Recursion ++ ++* Building Robots:: Same model, different serial number ... ++* Recursive Definition Parts:: Walk until you stop ... ++* Recursion with list:: Using a list as the test whether to recurse. ++* Recursive triangle function:: ++* Recursion with cond:: ++* Recursive Patterns:: Often used templates. ++* No Deferment:: Don't store up work ... ++* No deferment solution:: ++ ++Recursion in Place of a Counter ++ ++* Recursive Example arg of 1 or 2:: ++* Recursive Example arg of 3 or 4:: ++ ++Recursive Patterns ++ ++* Every:: ++* Accumulate:: ++* Keep:: ++ ++Regular Expression Searches ++ ++* sentence-end:: The regular expression for @code{sentence-end}. ++* re-search-forward:: Very similar to @code{search-forward}. ++* forward-sentence:: A straightforward example of regexp search. ++* forward-paragraph:: A somewhat complex example. ++* etags:: How to create your own @file{TAGS} table. ++* Regexp Review:: ++* re-search Exercises:: ++ ++@code{forward-sentence} ++ ++* Complete forward-sentence:: ++* fwd-sentence while loops:: Two @code{while} loops. ++* fwd-sentence re-search:: A regular expression search. ++ ++@code{forward-paragraph}: a Goldmine of Functions ++ ++* forward-paragraph in brief:: Key parts of the function definition. ++* fwd-para let:: The @code{let*} expression. ++* fwd-para while:: The forward motion @code{while} loop. ++ ++Counting: Repetition and Regexps ++ ++* Why Count Words:: ++* count-words-region:: Use a regexp, but find a problem. ++* recursive-count-words:: Start with case of no words in region. ++* Counting Exercise:: ++ ++The @code{count-words-region} Function ++ ++* Design count-words-region:: The definition using a @code{while} loop. ++* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. ++ ++Counting Words in a @code{defun} ++ ++* Divide and Conquer:: ++* Words and Symbols:: What to count? ++* Syntax:: What constitutes a word or symbol? ++* count-words-in-defun:: Very like @code{count-words}. ++* Several defuns:: Counting several defuns in a file. ++* Find a File:: Do you want to look at a file? ++* lengths-list-file:: A list of the lengths of many definitions. ++* Several files:: Counting in definitions in different files. ++* Several files recursively:: Recursively counting in different files. ++* Prepare the data:: Prepare the data for display in a graph. ++ ++Count Words in @code{defuns} in Different Files ++ ++* lengths-list-many-files:: Return a list of the lengths of defuns. ++* append:: Attach one list to another. ++ ++Prepare the Data for Display in a Graph ++ ++* Data for Display in Detail:: ++* Sorting:: Sorting lists. ++* Files List:: Making a list of files. ++* Counting function definitions:: ++ ++Readying a Graph ++ ++* Columns of a graph:: ++* graph-body-print:: How to print the body of a graph. ++* recursive-graph-body-print:: ++* Printed Axes:: ++* Line Graph Exercise:: ++ ++Your @file{.emacs} File ++ ++* Default Configuration:: ++* Site-wide Init:: You can write site-wide init files. ++* defcustom:: Emacs will write code for you. ++* Beginning a .emacs File:: How to write a @code{.emacs file}. ++* Text and Auto-fill:: Automatically wrap lines. ++* Mail Aliases:: Use abbreviations for email addresses. ++* Indent Tabs Mode:: Don't use tabs with @TeX{} ++* Keybindings:: Create some personal keybindings. ++* Keymaps:: More about key binding. ++* Loading Files:: Load (i.e., evaluate) files automatically. ++* Autoload:: Make functions available. ++* Simple Extension:: Define a function; bind it to a key. ++* X11 Colors:: Colors in X. ++* Miscellaneous:: ++* Mode Line:: How to customize your mode line. ++ ++Debugging ++ ++* debug:: How to use the built-in debugger. ++* debug-on-entry:: Start debugging when you call a function. ++* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. ++* edebug:: How to use Edebug, a source level debugger. ++* Debugging Exercises:: ++ ++Handling the Kill Ring ++ ++* What the Kill Ring Does:: ++* current-kill:: ++* yank:: Paste a copy of a clipped element. ++* yank-pop:: Insert element pointed to. ++* ring file:: ++ ++The @code{current-kill} Function ++ ++* Code for current-kill:: ++* Understanding current-kill:: ++ ++@code{current-kill} in Outline ++ ++* Body of current-kill:: ++* Digression concerning error:: How to mislead humans, but not computers. ++* Determining the Element:: ++ ++A Graph with Labelled Axes ++ ++* Labelled Example:: ++* print-graph Varlist:: @code{let} expression in @code{print-graph}. ++* print-Y-axis:: Print a label for the vertical axis. ++* print-X-axis:: Print a horizontal label. ++* Print Whole Graph:: The function to print a complete graph. ++ ++The @code{print-Y-axis} Function ++ ++* print-Y-axis in Detail:: ++* Height of label:: What height for the Y axis? ++* Compute a Remainder:: How to compute the remainder of a division. ++* Y Axis Element:: Construct a line for the Y axis. ++* Y-axis-column:: Generate a list of Y axis labels. ++* print-Y-axis Penultimate:: A not quite final version. ++ ++The @code{print-X-axis} Function ++ ++* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. ++* X Axis Tic Marks:: Create tic marks for the horizontal axis. ++ ++Printing the Whole Graph ++ ++* The final version:: A few changes. ++* Test print-graph:: Run a short test. ++* Graphing words in defuns:: Executing the final code. ++* lambda:: How to write an anonymous function. ++* mapcar:: Apply a function to elements of a list. ++* Another Bug:: Yet another bug @dots{} most insidious. ++* Final printed graph:: The graph itself! ++ ++@end detailmenu ++@end menu ++ ++@node Preface, List Processing, Top, Top ++@comment node-name, next, previous, up ++@unnumbered Preface ++ ++Most of the GNU Emacs integrated environment is written in the programming ++language called Emacs Lisp. The code written in this programming ++language is the software---the sets of instructions---that tell the ++computer what to do when you give it commands. Emacs is designed so ++that you can write new code in Emacs Lisp and easily install it as an ++extension to the editor. ++ ++(GNU Emacs is sometimes called an ``extensible editor'', but it does ++much more than provide editing capabilities. It is better to refer to ++Emacs as an ``extensible computing environment''. However, that ++phrase is quite a mouthful. It is easier to refer to Emacs simply as ++an editor. Moreover, everything you do in Emacs---find the Mayan date ++and phases of the moon, simplify polynomials, debug code, manage ++files, read letters, write books---all these activities are kinds of ++editing in the most general sense of the word.) ++ ++@menu ++* Why:: Why learn Emacs Lisp? ++* On Reading this Text:: Read, gain familiarity, pick up habits.... ++* Who You Are:: For whom this is written. ++* Lisp History:: ++* Note for Novices:: You can read this as a novice. ++* Thank You:: ++@end menu ++ ++@node Why, On Reading this Text, Preface, Preface ++@ifnottex ++@unnumberedsec Why Study Emacs Lisp? ++@end ifnottex ++ ++Although Emacs Lisp is usually thought of in association only with Emacs, ++it is a full computer programming language. You can use Emacs Lisp as ++you would any other programming language. ++ ++Perhaps you want to understand programming; perhaps you want to extend ++Emacs; or perhaps you want to become a programmer. This introduction to ++Emacs Lisp is designed to get you started: to guide you in learning the ++fundamentals of programming, and more importantly, to show you how you ++can teach yourself to go further. ++ ++@node On Reading this Text, Who You Are, Why, Preface ++@comment node-name, next, previous, up ++@unnumberedsec On Reading this Text ++ ++All through this document, you will see little sample programs you can ++run inside of Emacs. If you read this document in Info inside of GNU ++Emacs, you can run the programs as they appear. (This is easy to do and ++is explained when the examples are presented.) Alternatively, you can ++read this introduction as a printed book while sitting beside a computer ++running Emacs. (This is what I like to do; I like printed books.) If ++you don't have a running Emacs beside you, you can still read this book, ++but in this case, it is best to treat it as a novel or as a travel guide ++to a country not yet visited: interesting, but not the same as being ++there. ++ ++Much of this introduction is dedicated to walk-throughs or guided tours ++of code used in GNU Emacs. These tours are designed for two purposes: ++first, to give you familiarity with real, working code (code you use ++every day); and, second, to give you familiarity with the way Emacs ++works. It is interesting to see how a working environment is ++implemented. ++Also, I ++hope that you will pick up the habit of browsing through source code. ++You can learn from it and mine it for ideas. Having GNU Emacs is like ++having a dragon's cave of treasures. ++ ++In addition to learning about Emacs as an editor and Emacs Lisp as a ++programming language, the examples and guided tours will give you an ++opportunity to get acquainted with Emacs as a Lisp programming ++environment. GNU Emacs supports programming and provides tools that ++you will want to become comfortable using, such as @kbd{M-.} (the key ++which invokes the @code{find-tag} command). You will also learn about ++buffers and other objects that are part of the environment. ++Learning about these features of Emacs is like learning new routes ++around your home town. ++ ++@ignore ++In addition, I have written several programs as extended examples. ++Although these are examples, the programs are real. I use them. ++Other people use them. You may use them. Beyond the fragments of ++programs used for illustrations, there is very little in here that is ++`just for teaching purposes'; what you see is used. This is a great ++advantage of Emacs Lisp: it is easy to learn to use it for work. ++@end ignore ++ ++Finally, I hope to convey some of the skills for using Emacs to ++learn aspects of programming that you don't know. You can often use ++Emacs to help you understand what puzzles you or to find out how to do ++something new. This self-reliance is not only a pleasure, but an ++advantage. ++ ++@node Who You Are, Lisp History, On Reading this Text, Preface ++@comment node-name, next, previous, up ++@unnumberedsec For Whom This is Written ++ ++This text is written as an elementary introduction for people who are ++not programmers. If you are a programmer, you may not be satisfied with ++this primer. The reason is that you may have become expert at reading ++reference manuals and be put off by the way this text is organized. ++ ++An expert programmer who reviewed this text said to me: ++ ++@quotation ++@i{I prefer to learn from reference manuals. I ``dive into'' each ++paragraph, and ``come up for air'' between paragraphs.} ++ ++@i{When I get to the end of a paragraph, I assume that that subject is ++done, finished, that I know everything I need (with the ++possible exception of the case when the next paragraph starts talking ++about it in more detail). I expect that a well written reference manual ++will not have a lot of redundancy, and that it will have excellent ++pointers to the (one) place where the information I want is.} ++@end quotation ++ ++This introduction is not written for this person! ++ ++Firstly, I try to say everything at least three times: first, to ++introduce it; second, to show it in context; and third, to show it in a ++different context, or to review it. ++ ++Secondly, I hardly ever put all the information about a subject in one ++place, much less in one paragraph. To my way of thinking, that imposes ++too heavy a burden on the reader. Instead I try to explain only what ++you need to know at the time. (Sometimes I include a little extra ++information so you won't be surprised later when the additional ++information is formally introduced.) ++ ++When you read this text, you are not expected to learn everything the ++first time. Frequently, you need only make, as it were, a `nodding ++acquaintance' with some of the items mentioned. My hope is that I have ++structured the text and given you enough hints that you will be alert to ++what is important, and concentrate on it. ++ ++You will need to ``dive into'' some paragraphs; there is no other way ++to read them. But I have tried to keep down the number of such ++paragraphs. This book is intended as an approachable hill, rather than ++as a daunting mountain. ++ ++This introduction to @cite{Programming in Emacs Lisp} has a companion ++document, ++@iftex ++@cite{The GNU Emacs Lisp Reference Manual}. ++@end iftex ++@ifnottex ++@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU ++Emacs Lisp Reference Manual}. ++@end ifnottex ++The reference manual has more detail than this introduction. In the ++reference manual, all the information about one topic is concentrated ++in one place. You should turn to it if you are like the programmer ++quoted above. And, of course, after you have read this ++@cite{Introduction}, you will find the @cite{Reference Manual} useful ++when you are writing your own programs. ++ ++@node Lisp History, Note for Novices, Who You Are, Preface ++@unnumberedsec Lisp History ++@cindex Lisp history ++ ++Lisp was first developed in the late 1950s at the Massachusetts ++Institute of Technology for research in artificial intelligence. The ++great power of the Lisp language makes it superior for other purposes as ++well, such as writing editor commands and integrated environments. ++ ++@cindex Maclisp ++@cindex Common Lisp ++GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT ++in the 1960s. It is somewhat inspired by Common Lisp, which became a ++standard in the 1980s. However, Emacs Lisp is much simpler than Common ++Lisp. (The standard Emacs distribution contains an optional extensions ++file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) ++ ++@node Note for Novices, Thank You, Lisp History, Preface ++@comment node-name, next, previous, up ++@unnumberedsec A Note for Novices ++ ++If you don't know GNU Emacs, you can still read this document ++profitably. However, I recommend you learn Emacs, if only to learn to ++move around your computer screen. You can teach yourself how to use ++Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This ++means you press and release the @key{CTRL} key and the @kbd{h} at the ++same time, and then press and release @kbd{t}.) ++ ++Also, I often refer to one of Emacs' standard commands by listing the ++keys which you press to invoke the command and then giving the name of ++the command in parentheses, like this: @kbd{M-C-\} ++(@code{indent-region}). What this means is that the ++@code{indent-region} command is customarily invoked by typing ++@kbd{M-C-\}. (You can, if you wish, change the keys that are typed to ++invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, , ++Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your ++@key{META} key, @key{CTRL} key and @key{\} key all at the same time. ++(On many modern keyboards the @key{META} key is labelled ++@key{ALT}.) ++Sometimes a combination like this is called a keychord, since it is ++similar to the way you play a chord on a piano. If your keyboard does ++not have a @key{META} key, the @key{ESC} key prefix is used in place ++of it. In this case, @kbd{M-C-\} means that you press and release your ++@key{ESC} key and then type the @key{CTRL} key and the @key{\} key at ++the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key ++along with the key that is labelled @key{ALT} and, at the same time, ++press the @key{\} key. ++ ++In addition to typing a lone keychord, you can prefix what you type ++with @kbd{C-u}, which is called the `universal argument'. The ++@kbd{C-u} keychord passes an argument to the subsequent command. ++Thus, to indent a region of plain text by 6 spaces, mark the region, ++and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number, ++Emacs either passes the number 4 to the command or otherwise runs the ++command differently than it would otherwise.) @xref{Arguments, , ++Numeric Arguments, emacs, The GNU Emacs Manual}. ++ ++If you are reading this in Info using GNU Emacs, you can read through ++this whole document just by pressing the space bar, @key{SPC}. ++(To learn about Info, type @kbd{C-h i} and then select Info.) ++ ++A note on terminology: when I use the word Lisp alone, I often am ++referring to the various dialects of Lisp in general, but when I speak ++of Emacs Lisp, I am referring to GNU Emacs Lisp in particular. ++ ++@node Thank You, , Note for Novices, Preface ++@comment node-name, next, previous, up ++@unnumberedsec Thank You ++ ++My thanks to all who helped me with this book. My especial thanks to ++@r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland ++McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@: ++Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both ++@w{Philip Johnson} and @w{David Stampe} for their patient ++encouragement. My mistakes are my own. ++ ++@flushright ++Robert J. Chassell ++@email{bob@@gnu.org} ++@end flushright ++ ++@c ================ Beginning of main text ================ ++ ++@c Start main text on right-hand (verso) page ++ ++@tex ++\par\vfill\supereject ++\headings off ++\ifodd\pageno ++ \par\vfill\supereject ++\else ++ \par\vfill\supereject ++ \page\hbox{}\page ++ \par\vfill\supereject ++\fi ++@end tex ++ ++@iftex ++@headings off ++@evenheading @thispage @| @| @thischapter ++@oddheading @thissection @| @| @thispage ++@global@pageno = 1 ++@end iftex ++ ++@node List Processing, Practicing Evaluation, Preface, Top ++@comment node-name, next, previous, up ++@chapter List Processing ++ ++To the untutored eye, Lisp is a strange programming language. In Lisp ++code there are parentheses everywhere. Some people even claim that ++the name stands for `Lots of Isolated Silly Parentheses'. But the ++claim is unwarranted. Lisp stands for LISt Processing, and the ++programming language handles @emph{lists} (and lists of lists) by ++putting them between parentheses. The parentheses mark the boundaries ++of the list. Sometimes a list is preceded by a single apostrophe or ++quotation mark, @samp{'}@footnote{The single apostrophe or quotation ++mark is an abbreviation for the function @code{quote}; you need not ++think about functions now; functions are defined in @ref{Making ++Errors, , Generate an Error Message}.} Lists are the basis of Lisp. ++ ++@menu ++* Lisp Lists:: What are lists? ++* Run a Program:: Any list in Lisp is a program ready to run. ++* Making Errors:: Generating an error message. ++* Names & Definitions:: Names of symbols and function definitions. ++* Lisp Interpreter:: What the Lisp interpreter does. ++* Evaluation:: Running a program. ++* Variables:: Returning a value from a variable. ++* Arguments:: Passing information to a function. ++* set & setq:: Setting the value of a variable. ++* Summary:: The major points. ++* Error Message Exercises:: ++@end menu ++ ++@node Lisp Lists, Run a Program, List Processing, List Processing ++@comment node-name, next, previous, up ++@section Lisp Lists ++@cindex Lisp Lists ++ ++In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}. ++This list is preceded by a single apostrophe. It could just as well be ++written as follows, which looks more like the kind of list you are likely ++to be familiar with: ++ ++@smallexample ++@group ++'(rose ++ violet ++ daisy ++ buttercup) ++@end group ++@end smallexample ++ ++@noindent ++The elements of this list are the names of the four different flowers, ++separated from each other by whitespace and surrounded by parentheses, ++like flowers in a field with a stone wall around them. ++@cindex Flowers in a field ++ ++@menu ++* Numbers Lists:: List have numbers, other lists, in them. ++* Lisp Atoms:: Elemental entities. ++* Whitespace in Lists:: Formatting lists to be readable. ++* Typing Lists:: How GNU Emacs helps you type lists. ++@end menu ++ ++@node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists ++@ifnottex ++@unnumberedsubsec Numbers, Lists inside of Lists ++@end ifnottex ++ ++Lists can also have numbers in them, as in this list: @code{(+ 2 2)}. ++This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each ++separated by whitespace. ++ ++In Lisp, both data and programs are represented the same way; that is, ++they are both lists of words, numbers, or other lists, separated by ++whitespace and surrounded by parentheses. (Since a program looks like ++data, one program may easily serve as data for another; this is a very ++powerful feature of Lisp.) (Incidentally, these two parenthetical ++remarks are @emph{not} Lisp lists, because they contain @samp{;} and ++@samp{.} as punctuation marks.) ++ ++@need 1200 ++Here is another list, this time with a list inside of it: ++ ++@smallexample ++'(this list has (a list inside of it)) ++@end smallexample ++ ++The components of this list are the words @samp{this}, @samp{list}, ++@samp{has}, and the list @samp{(a list inside of it)}. The interior ++list is made up of the words @samp{a}, @samp{list}, @samp{inside}, ++@samp{of}, @samp{it}. ++ ++@node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists ++@comment node-name, next, previous, up ++@subsection Lisp Atoms ++@cindex Lisp Atoms ++ ++In Lisp, what we have been calling words are called @dfn{atoms}. This ++term comes from the historical meaning of the word atom, which means ++`indivisible'. As far as Lisp is concerned, the words we have been ++using in the lists cannot be divided into any smaller parts and still ++mean the same thing as part of a program; likewise with numbers and ++single character symbols like @samp{+}. On the other hand, unlike an ++ancient atom, a list can be split into parts. (@xref{car cdr & cons, ++, @code{car} @code{cdr} & @code{cons} Fundamental Functions}.) ++ ++In a list, atoms are separated from each other by whitespace. They can be ++right next to a parenthesis. ++ ++@cindex @samp{empty list} defined ++Technically speaking, a list in Lisp consists of parentheses surrounding ++atoms separated by whitespace or surrounding other lists or surrounding ++both atoms and other lists. A list can have just one atom in it or ++have nothing in it at all. A list with nothing in it looks like this: ++@code{()}, and is called the @dfn{empty list}. Unlike anything else, an ++empty list is considered both an atom and a list at the same time. ++ ++@cindex Symbolic expressions, introduced ++@cindex @samp{expression} defined ++@cindex @samp{form} defined ++The printed representation of both atoms and lists are called ++@dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}. ++The word @dfn{expression} by itself can refer to either the printed ++representation, or to the atom or list as it is held internally in the ++computer. Often, people use the term @dfn{expression} ++indiscriminately. (Also, in many texts, the word @dfn{form} is used ++as a synonym for expression.) ++ ++Incidentally, the atoms that make up our universe were named such when ++they were thought to be indivisible; but it has been found that physical ++atoms are not indivisible. Parts can split off an atom or it can ++fission into two parts of roughly equal size. Physical atoms were named ++prematurely, before their truer nature was found. In Lisp, certain ++kinds of atom, such as an array, can be separated into parts; but the ++mechanism for doing this is different from the mechanism for splitting a ++list. As far as list operations are concerned, the atoms of a list are ++unsplittable. ++ ++As in English, the meanings of the component letters of a Lisp atom ++are different from the meaning the letters make as a word. For ++example, the word for the South American sloth, the @samp{ai}, is ++completely different from the two words, @samp{a}, and @samp{i}. ++ ++There are many kinds of atom in nature but only a few in Lisp: for ++example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such ++as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have ++listed in the examples above are all symbols. In everyday Lisp ++conversation, the word ``atom'' is not often used, because programmers ++usually try to be more specific about what kind of atom they are dealing ++with. Lisp programming is mostly about symbols (and sometimes numbers) ++within lists. (Incidentally, the preceding three word parenthetical ++remark is a proper list in Lisp, since it consists of atoms, which in ++this case are symbols, separated by whitespace and enclosed by ++parentheses, without any non-Lisp punctuation.) ++ ++@need 1250 ++Text between double quotation marks---even sentences or ++paragraphs---is also an atom. Here is an example: ++@cindex Text between double quotation marks ++ ++@smallexample ++'(this list includes "text between quotation marks.") ++@end smallexample ++ ++@cindex @samp{string} defined ++@noindent ++In Lisp, all of the quoted text including the punctuation mark and the ++blank spaces is a single atom. This kind of atom is called a ++@dfn{string} (for `string of characters') and is the sort of thing that ++is used for messages that a computer can print for a human to read. ++Strings are a different kind of atom than numbers or symbols and are ++used differently. ++ ++@node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists ++@comment node-name, next, previous, up ++@subsection Whitespace in Lists ++@cindex Whitespace in lists ++ ++@need 1200 ++The amount of whitespace in a list does not matter. From the point of view ++of the Lisp language, ++ ++@smallexample ++@group ++'(this list ++ looks like this) ++@end group ++@end smallexample ++ ++@need 800 ++@noindent ++is exactly the same as this: ++ ++@smallexample ++'(this list looks like this) ++@end smallexample ++ ++Both examples show what to Lisp is the same list, the list made up of ++the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and ++@samp{this} in that order. ++ ++Extra whitespace and newlines are designed to make a list more readable ++by humans. When Lisp reads the expression, it gets rid of all the extra ++whitespace (but it needs to have at least one space between atoms in ++order to tell them apart.) ++ ++Odd as it seems, the examples we have seen cover almost all of what Lisp ++lists look like! Every other list in Lisp looks more or less like one ++of these examples, except that the list may be longer and more complex. ++In brief, a list is between parentheses, a string is between quotation ++marks, a symbol looks like a word, and a number looks like a number. ++(For certain situations, square brackets, dots and a few other special ++characters may be used; however, we will go quite far without them.) ++ ++@node Typing Lists, , Whitespace in Lists, Lisp Lists ++@comment node-name, next, previous, up ++@subsection GNU Emacs Helps You Type Lists ++@cindex Help typing lists ++@cindex Formatting help ++ ++When you type a Lisp expression in GNU Emacs using either Lisp ++Interaction mode or Emacs Lisp mode, you have available to you several ++commands to format the Lisp expression so it is easy to read. For ++example, pressing the @key{TAB} key automatically indents the line the ++cursor is on by the right amount. A command to properly indent the ++code in a region is customarily bound to @kbd{M-C-\}. Indentation is ++designed so that you can see which elements of a list belong to which ++list---elements of a sub-list are indented more than the elements of ++the enclosing list. ++ ++In addition, when you type a closing parenthesis, Emacs momentarily ++jumps the cursor back to the matching opening parenthesis, so you can ++see which one it is. This is very useful, since every list you type ++in Lisp must have its closing parenthesis match its opening ++parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs ++Manual}, for more information about Emacs' modes.) ++ ++@node Run a Program, Making Errors, Lisp Lists, List Processing ++@comment node-name, next, previous, up ++@section Run a Program ++@cindex Run a program ++@cindex Program, running one ++ ++@cindex @samp{evaluate} defined ++A list in Lisp---any list---is a program ready to run. If you run it ++(for which the Lisp jargon is @dfn{evaluate}), the computer will do one ++of three things: do nothing except return to you the list itself; send ++you an error message; or, treat the first symbol in the list as a ++command to do something. (Usually, of course, it is the last of these ++three things that you really want!) ++ ++@c use code for the single apostrophe, not samp. ++The single apostrophe, @code{'}, that I put in front of some of the ++example lists in preceding sections is called a @dfn{quote}; when it ++precedes a list, it tells Lisp to do nothing with the list, other than ++take it as it is written. But if there is no quote preceding a list, ++the first item of the list is special: it is a command for the computer ++to obey. (In Lisp, these commands are called @emph{functions}.) The list ++@code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp ++understands that the @code{+} is an instruction to do something with the ++rest of the list: add the numbers that follow. ++ ++@need 1250 ++If you are reading this inside of GNU Emacs in Info, here is how you can ++evaluate such a list: place your cursor immediately after the right ++hand parenthesis of the following list and then type @kbd{C-x C-e}: ++ ++@smallexample ++(+ 2 2) ++@end smallexample ++ ++@c use code for the number four, not samp. ++@noindent ++You will see the number @code{4} appear in the echo area. (In the ++jargon, what you have just done is ``evaluate the list.'' The echo area ++is the line at the bottom of the screen that displays or ``echoes'' ++text.) Now try the same thing with a quoted list: place the cursor ++right after the following list and type @kbd{C-x C-e}: ++ ++@smallexample ++'(this is a quoted list) ++@end smallexample ++ ++@noindent ++You will see @code{(this is a quoted list)} appear in the echo area. ++ ++@cindex Lisp interpreter, explained ++@cindex Interpreter, Lisp, explained ++In both cases, what you are doing is giving a command to the program ++inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the ++interpreter a command to evaluate the expression. The name of the Lisp ++interpreter comes from the word for the task done by a human who comes ++up with the meaning of an expression---who ``interprets'' it. ++ ++You can also evaluate an atom that is not part of a list---one that is ++not surrounded by parentheses; again, the Lisp interpreter translates ++from the humanly readable expression to the language of the computer. ++But before discussing this (@pxref{Variables}), we will discuss what the ++Lisp interpreter does when you make an error. ++ ++@node Making Errors, Names & Definitions, Run a Program, List Processing ++@comment node-name, next, previous, up ++@section Generate an Error Message ++@cindex Generate an error message ++@cindex Error message generation ++ ++Partly so you won't worry if you do it accidentally, we will now give ++a command to the Lisp interpreter that generates an error message. ++This is a harmless activity; and indeed, we will often try to generate ++error messages intentionally. Once you understand the jargon, error ++messages can be informative. Instead of being called ``error'' ++messages, they should be called ``help'' messages. They are like ++signposts to a traveller in a strange country; deciphering them can be ++hard, but once understood, they can point the way. ++ ++The error message is generated by a built-in GNU Emacs debugger. We ++will `enter the debugger'. You get out of the debugger by typing @code{q}. ++ ++What we will do is evaluate a list that is not quoted and does not ++have a meaningful command as its first element. Here is a list almost ++exactly the same as the one we just used, but without the single-quote ++in front of it. Position the cursor right after it and type @kbd{C-x ++C-e}: ++ ++@smallexample ++(this is an unquoted list) ++@end smallexample ++ ++@noindent ++What you see depends on which version of Emacs you are running. GNU ++Emacs version 22 provides more information than version 20 and before. ++First, the more recent result of generating an error; then the ++earlier, version 20 result. ++ ++@need 1250 ++@noindent ++In GNU Emacs version 22, a @file{*Backtrace*} window will open up and ++you will see the following in it: ++ ++@smallexample ++@group ++---------- Buffer: *Backtrace* ---------- ++Debugger entered--Lisp error: (void-function this) ++ (this is an unquoted list) ++ eval((this is an unquoted list)) ++ eval-last-sexp-1(nil) ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++---------- Buffer: *Backtrace* ---------- ++@end group ++@end smallexample ++ ++@need 1200 ++@noindent ++Your cursor will be in this window (you may have to wait a few seconds ++before it becomes visible). To quit the debugger and make the ++debugger window go away, type: ++ ++@smallexample ++q ++@end smallexample ++ ++@noindent ++Please type @kbd{q} right now, so you become confident that you can ++get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter ++it. ++ ++@cindex @samp{function} defined ++Based on what we already know, we can almost read this error message. ++ ++You read the @file{*Backtrace*} buffer from the bottom up; it tells ++you what Emacs did. When you typed @kbd{C-x C-e}, you made an ++interactive call to the command @code{eval-last-sexp}. @code{eval} is ++an abbreviation for `evaluate' and @code{sexp} is an abbreviation for ++`symbolic expression'. The command means `evaluate last symbolic ++expression', which is the expression just before your cursor. ++ ++Each line above tells you what the Lisp interpreter evaluated next. ++The most recent action is at the top. The buffer is called the ++@file{*Backtrace*} buffer because it enables you to track Emacs ++backwards. ++ ++@need 800 ++At the top of the @file{*Backtrace*} buffer, you see the line: ++ ++@smallexample ++Debugger entered--Lisp error: (void-function this) ++@end smallexample ++ ++@noindent ++The Lisp interpreter tried to evaluate the first atom of the list, the ++word @samp{this}. It is this action that generated the error message ++@samp{void-function this}. ++ ++The message contains the words @samp{void-function} and @samp{this}. ++ ++@cindex @samp{function} defined ++The word @samp{function} was mentioned once before. It is a very ++important word. For our purposes, we can define it by saying that a ++@dfn{function} is a set of instructions to the computer that tell the ++computer to do something. ++ ++Now we can begin to understand the error message: @samp{void-function ++this}. The function (that is, the word @samp{this}) does not have a ++definition of any set of instructions for the computer to carry out. ++ ++The slightly odd word, @samp{void-function}, is designed to cover the ++way Emacs Lisp is implemented, which is that when a symbol does not ++have a function definition attached to it, the place that should ++contain the instructions is `void'. ++ ++On the other hand, since we were able to add 2 plus 2 successfully, by ++evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must ++have a set of instructions for the computer to obey and those ++instructions must be to add the numbers that follow the @code{+}. ++ ++@need 1250 ++In GNU Emacs version 20, and in earlier versions, you will see only ++one line of error message; it will appear in the echo area and look ++like this: ++ ++@smallexample ++Symbol's function definition is void:@: this ++@end smallexample ++ ++@noindent ++(Also, your terminal may beep at you---some do, some don't; and others ++blink. This is just a device to get your attention.) The message goes ++away as soon as you type another key, even just to move the cursor. ++ ++We know the meaning of the word @samp{Symbol}. It refers to the first ++atom of the list, the word @samp{this}. The word @samp{function} ++refers to the instructions that tell the computer what to do. ++(Technically, the symbol tells the computer where to find the ++instructions, but this is a complication we can ignore for the ++moment.) ++ ++The error message can be understood: @samp{Symbol's function ++definition is void:@: this}. The symbol (that is, the word ++@samp{this}) lacks instructions for the computer to carry out. ++ ++@node Names & Definitions, Lisp Interpreter, Making Errors, List Processing ++@comment node-name, next, previous, up ++@section Symbol Names and Function Definitions ++@cindex Symbol names ++ ++We can articulate another characteristic of Lisp based on what we have ++discussed so far---an important characteristic: a symbol, like ++@code{+}, is not itself the set of instructions for the computer to ++carry out. Instead, the symbol is used, perhaps temporarily, as a way ++of locating the definition or set of instructions. What we see is the ++name through which the instructions can be found. Names of people ++work the same way. I can be referred to as @samp{Bob}; however, I am ++not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the ++consciousness consistently associated with a particular life-form. ++The name is not me, but it can be used to refer to me. ++ ++In Lisp, one set of instructions can be attached to several names. ++For example, the computer instructions for adding numbers can be ++linked to the symbol @code{plus} as well as to the symbol @code{+} ++(and are in some dialects of Lisp). Among humans, I can be referred ++to as @samp{Robert} as well as @samp{Bob} and by other words as well. ++ ++On the other hand, a symbol can have only one function definition ++attached to it at a time. Otherwise, the computer would be confused as ++to which definition to use. If this were the case among people, only ++one person in the world could be named @samp{Bob}. However, the function ++definition to which the name refers can be changed readily. ++(@xref{Install, , Install a Function Definition}.) ++ ++Since Emacs Lisp is large, it is customary to name symbols in a way ++that identifies the part of Emacs to which the function belongs. ++Thus, all the names for functions that deal with Texinfo start with ++@samp{texinfo-} and those for functions that deal with reading mail ++start with @samp{rmail-}. ++ ++@node Lisp Interpreter, Evaluation, Names & Definitions, List Processing ++@comment node-name, next, previous, up ++@section The Lisp Interpreter ++@cindex Lisp interpreter, what it does ++@cindex Interpreter, what it does ++ ++Based on what we have seen, we can now start to figure out what the ++Lisp interpreter does when we command it to evaluate a list. ++First, it looks to see whether there is a quote before the list; if ++there is, the interpreter just gives us the list. On the other ++hand, if there is no quote, the interpreter looks at the first element ++in the list and sees whether it has a function definition. If it does, ++the interpreter carries out the instructions in the function definition. ++Otherwise, the interpreter prints an error message. ++ ++This is how Lisp works. Simple. There are added complications which we ++will get to in a minute, but these are the fundamentals. Of course, to ++write Lisp programs, you need to know how to write function definitions ++and attach them to names, and how to do this without confusing either ++yourself or the computer. ++ ++@menu ++* Complications:: Variables, Special forms, Lists within. ++* Byte Compiling:: Specially processing code for speed. ++@end menu ++ ++@node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter ++@ifnottex ++@unnumberedsubsec Complications ++@end ifnottex ++ ++Now, for the first complication. In addition to lists, the Lisp ++interpreter can evaluate a symbol that is not quoted and does not have ++parentheses around it. The Lisp interpreter will attempt to determine ++the symbol's value as a @dfn{variable}. This situation is described ++in the section on variables. (@xref{Variables}.) ++ ++@cindex Special form ++The second complication occurs because some functions are unusual and do ++not work in the usual manner. Those that don't are called @dfn{special ++forms}. They are used for special jobs, like defining a function, and ++there are not many of them. In the next few chapters, you will be ++introduced to several of the more important special forms. ++ ++The third and final complication is this: if the function that the ++Lisp interpreter is looking at is not a special form, and if it is part ++of a list, the Lisp interpreter looks to see whether the list has a list ++inside of it. If there is an inner list, the Lisp interpreter first ++figures out what it should do with the inside list, and then it works on ++the outside list. If there is yet another list embedded inside the ++inner list, it works on that one first, and so on. It always works on ++the innermost list first. The interpreter works on the innermost list ++first, to evaluate the result of that list. The result may be ++used by the enclosing expression. ++ ++Otherwise, the interpreter works left to right, from one expression to ++the next. ++ ++@node Byte Compiling, , Complications, Lisp Interpreter ++@subsection Byte Compiling ++@cindex Byte compiling ++ ++One other aspect of interpreting: the Lisp interpreter is able to ++interpret two kinds of entity: humanly readable code, on which we will ++focus exclusively, and specially processed code, called @dfn{byte ++compiled} code, which is not humanly readable. Byte compiled code ++runs faster than humanly readable code. ++ ++You can transform humanly readable code into byte compiled code by ++running one of the compile commands such as @code{byte-compile-file}. ++Byte compiled code is usually stored in a file that ends with a ++@file{.elc} extension rather than a @file{.el} extension. You will ++see both kinds of file in the @file{emacs/lisp} directory; the files ++to read are those with @file{.el} extensions. ++ ++As a practical matter, for most things you might do to customize or ++extend Emacs, you do not need to byte compile; and I will not discuss ++the topic here. @xref{Byte Compilation, , Byte Compilation, elisp, ++The GNU Emacs Lisp Reference Manual}, for a full description of byte ++compilation. ++ ++@node Evaluation, Variables, Lisp Interpreter, List Processing ++@comment node-name, next, previous, up ++@section Evaluation ++@cindex Evaluation ++ ++When the Lisp interpreter works on an expression, the term for the ++activity is called @dfn{evaluation}. We say that the interpreter ++`evaluates the expression'. I've used this term several times before. ++The word comes from its use in everyday language, `to ascertain the ++value or amount of; to appraise', according to @cite{Webster's New ++Collegiate Dictionary}. ++ ++@menu ++* How the Interpreter Acts:: Returns and Side Effects... ++* Evaluating Inner Lists:: Lists within lists... ++@end menu ++ ++@node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation ++@ifnottex ++@unnumberedsubsec How the Lisp Interpreter Acts ++@end ifnottex ++ ++@cindex @samp{returned value} explained ++After evaluating an expression, the Lisp interpreter will most likely ++@dfn{return} the value that the computer produces by carrying out the ++instructions it found in the function definition, or perhaps it will ++give up on that function and produce an error message. (The interpreter ++may also find itself tossed, so to speak, to a different function or it ++may attempt to repeat continually what it is doing for ever and ever in ++what is called an `infinite loop'. These actions are less common; and ++we can ignore them.) Most frequently, the interpreter returns a value. ++ ++@cindex @samp{side effect} defined ++At the same time the interpreter returns a value, it may do something ++else as well, such as move a cursor or copy a file; this other kind of ++action is called a @dfn{side effect}. Actions that we humans think are ++important, such as printing results, are often ``side effects'' to the ++Lisp interpreter. The jargon can sound peculiar, but it turns out that ++it is fairly easy to learn to use side effects. ++ ++In summary, evaluating a symbolic expression most commonly causes the ++Lisp interpreter to return a value and perhaps carry out a side effect; ++or else produce an error. ++ ++@node Evaluating Inner Lists, , How the Interpreter Acts, Evaluation ++@comment node-name, next, previous, up ++@subsection Evaluating Inner Lists ++@cindex Inner list evaluation ++@cindex Evaluating inner lists ++ ++If evaluation applies to a list that is inside another list, the outer ++list may use the value returned by the first evaluation as information ++when the outer list is evaluated. This explains why inner expressions ++are evaluated first: the values they return are used by the outer ++expressions. ++ ++@need 1250 ++We can investigate this process by evaluating another addition example. ++Place your cursor after the following expression and type @kbd{C-x C-e}: ++ ++@smallexample ++(+ 2 (+ 3 3)) ++@end smallexample ++ ++@noindent ++The number 8 will appear in the echo area. ++ ++What happens is that the Lisp interpreter first evaluates the inner ++expression, @code{(+ 3 3)}, for which the value 6 is returned; then it ++evaluates the outer expression as if it were written @code{(+ 2 6)}, which ++returns the value 8. Since there are no more enclosing expressions to ++evaluate, the interpreter prints that value in the echo area. ++ ++Now it is easy to understand the name of the command invoked by the ++keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The ++letters @code{sexp} are an abbreviation for `symbolic expression', and ++@code{eval} is an abbreviation for `evaluate'. The command means ++`evaluate last symbolic expression'. ++ ++As an experiment, you can try evaluating the expression by putting the ++cursor at the beginning of the next line immediately following the ++expression, or inside the expression. ++ ++@need 800 ++Here is another copy of the expression: ++ ++@smallexample ++(+ 2 (+ 3 3)) ++@end smallexample ++ ++@noindent ++If you place the cursor at the beginning of the blank line that ++immediately follows the expression and type @kbd{C-x C-e}, you will ++still get the value 8 printed in the echo area. Now try putting the ++cursor inside the expression. If you put it right after the next to ++last parenthesis (so it appears to sit on top of the last parenthesis), ++you will get a 6 printed in the echo area! This is because the command ++evaluates the expression @code{(+ 3 3)}. ++ ++Now put the cursor immediately after a number. Type @kbd{C-x C-e} and ++you will get the number itself. In Lisp, if you evaluate a number, you ++get the number itself---this is how numbers differ from symbols. If you ++evaluate a list starting with a symbol like @code{+}, you will get a ++value returned that is the result of the computer carrying out the ++instructions in the function definition attached to that name. If a ++symbol by itself is evaluated, something different happens, as we will ++see in the next section. ++ ++@node Variables, Arguments, Evaluation, List Processing ++@comment node-name, next, previous, up ++@section Variables ++@cindex Variables ++ ++In Emacs Lisp, a symbol can have a value attached to it just as it can ++have a function definition attached to it. The two are different. ++The function definition is a set of instructions that a computer will ++obey. A value, on the other hand, is something, such as number or a ++name, that can vary (which is why such a symbol is called a variable). ++The value of a symbol can be any expression in Lisp, such as a symbol, ++number, list, or string. A symbol that has a value is often called a ++@dfn{variable}. ++ ++A symbol can have both a function definition and a value attached to ++it at the same time. Or it can have just one or the other. ++The two are separate. This is somewhat similar ++to the way the name Cambridge can refer to the city in Massachusetts ++and have some information attached to the name as well, such as ++``great programming center''. ++ ++@ignore ++(Incidentally, in Emacs Lisp, a symbol can have two ++other things attached to it, too: a property list and a documentation ++string; these are discussed later.) ++@end ignore ++ ++Another way to think about this is to imagine a symbol as being a chest ++of drawers. The function definition is put in one drawer, the value in ++another, and so on. What is put in the drawer holding the value can be ++changed without affecting the contents of the drawer holding the ++function definition, and vice-verse. ++ ++@menu ++* fill-column Example:: ++* Void Function:: The error message for a symbol ++ without a function. ++* Void Variable:: The error message for a symbol without a value. ++@end menu ++ ++@node fill-column Example, Void Function, Variables, Variables ++@ifnottex ++@unnumberedsubsec @code{fill-column}, an Example Variable ++@end ifnottex ++ ++@findex fill-column, @r{an example variable} ++@cindex Example variable, @code{fill-column} ++@cindex Variable, example of, @code{fill-column} ++The variable @code{fill-column} illustrates a symbol with a value ++attached to it: in every GNU Emacs buffer, this symbol is set to some ++value, usually 72 or 70, but sometimes to some other value. To find the ++value of this symbol, evaluate it by itself. If you are reading this in ++Info inside of GNU Emacs, you can do this by putting the cursor after ++the symbol and typing @kbd{C-x C-e}: ++ ++@smallexample ++fill-column ++@end smallexample ++ ++@noindent ++After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo ++area. This is the value for which @code{fill-column} is set for me as I ++write this. It may be different for you in your Info buffer. Notice ++that the value returned as a variable is printed in exactly the same way ++as the value returned by a function carrying out its instructions. From ++the point of view of the Lisp interpreter, a value returned is a value ++returned. What kind of expression it came from ceases to matter once ++the value is known. ++ ++A symbol can have any value attached to it or, to use the jargon, we can ++@dfn{bind} the variable to a value: to a number, such as 72; to a ++string, @code{"such as this"}; to a list, such as @code{(spruce pine ++oak)}; we can even bind a variable to a function definition. ++ ++A symbol can be bound to a value in several ways. @xref{set & setq, , ++Setting the Value of a Variable}, for information about one way to do ++this. ++ ++@node Void Function, Void Variable, fill-column Example, Variables ++@comment node-name, next, previous, up ++@subsection Error Message for a Symbol Without a Function ++@cindex Symbol without function error ++@cindex Error for symbol without function ++ ++When we evaluated @code{fill-column} to find its value as a variable, ++we did not place parentheses around the word. This is because we did ++not intend to use it as a function name. ++ ++If @code{fill-column} were the first or only element of a list, the ++Lisp interpreter would attempt to find the function definition ++attached to it. But @code{fill-column} has no function definition. ++Try evaluating this: ++ ++@smallexample ++(fill-column) ++@end smallexample ++ ++@need 1250 ++@noindent ++In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer ++that says: ++ ++@smallexample ++@group ++---------- Buffer: *Backtrace* ---------- ++Debugger entered--Lisp error: (void-function fill-column) ++ (fill-column) ++ eval((fill-column)) ++ eval-last-sexp-1(nil) ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++---------- Buffer: *Backtrace* ---------- ++@end group ++@end smallexample ++ ++@noindent ++(Remember, to quit the debugger and make the debugger window go away, ++type @kbd{q} in the @file{*Backtrace*} buffer.) ++ ++@ignore ++@need 800 ++In GNU Emacs 20 and before, you will produce an error message that says: ++ ++@smallexample ++Symbol's function definition is void:@: fill-column ++@end smallexample ++ ++@noindent ++(The message will go away as soon as you move the cursor or type ++another key.) ++@end ignore ++ ++@node Void Variable, , Void Function, Variables ++@comment node-name, next, previous, up ++@subsection Error Message for a Symbol Without a Value ++@cindex Symbol without value error ++@cindex Error for symbol without value ++ ++If you attempt to evaluate a symbol that does not have a value bound to ++it, you will receive an error message. You can see this by ++experimenting with our 2 plus 2 addition. In the following expression, ++put your cursor right after the @code{+}, before the first number 2, ++type @kbd{C-x C-e}: ++ ++@smallexample ++(+ 2 2) ++@end smallexample ++ ++@need 1500 ++@noindent ++In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that ++says: ++ ++@smallexample ++@group ++---------- Buffer: *Backtrace* ---------- ++Debugger entered--Lisp error: (void-variable +) ++ eval(+) ++ eval-last-sexp-1(nil) ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++---------- Buffer: *Backtrace* ---------- ++@end group ++@end smallexample ++ ++@noindent ++(As with the other times we entered the debugger, you can quit by ++typing @kbd{q} in the @file{*Backtrace*} buffer.) ++ ++This backtrace is different from the very first error message we saw, ++which said, @samp{Debugger entered--Lisp error: (void-function this)}. ++In this case, the function does not have a value as a variable; while ++in the other error message, the function (the word `this') did not ++have a definition. ++ ++In this experiment with the @code{+}, what we did was cause the Lisp ++interpreter to evaluate the @code{+} and look for the value of the ++variable instead of the function definition. We did this by placing the ++cursor right after the symbol rather than after the parenthesis of the ++enclosing list as we did before. As a consequence, the Lisp interpreter ++evaluated the preceding s-expression, which in this case was the ++@code{+} by itself. ++ ++Since @code{+} does not have a value bound to it, just the function ++definition, the error message reported that the symbol's value as a ++variable was void. ++ ++@ignore ++@need 800 ++In GNU Emacs version 20 and before, your error message will say: ++ ++@example ++Symbol's value as variable is void:@: + ++@end example ++ ++@noindent ++The meaning is the same as in GNU Emacs 22. ++@end ignore ++ ++@node Arguments, set & setq, Variables, List Processing ++@comment node-name, next, previous, up ++@section Arguments ++@cindex Arguments ++@cindex Passing information to functions ++ ++To see how information is passed to functions, let's look again at ++our old standby, the addition of two plus two. In Lisp, this is written ++as follows: ++ ++@smallexample ++(+ 2 2) ++@end smallexample ++ ++If you evaluate this expression, the number 4 will appear in your echo ++area. What the Lisp interpreter does is add the numbers that follow ++the @code{+}. ++ ++@cindex @samp{argument} defined ++The numbers added by @code{+} are called the @dfn{arguments} of the ++function @code{+}. These numbers are the information that is given to ++or @dfn{passed} to the function. ++ ++The word `argument' comes from the way it is used in mathematics and ++does not refer to a disputation between two people; instead it refers to ++the information presented to the function, in this case, to the ++@code{+}. In Lisp, the arguments to a function are the atoms or lists ++that follow the function. The values returned by the evaluation of ++these atoms or lists are passed to the function. Different functions ++require different numbers of arguments; some functions require none at ++all.@footnote{It is curious to track the path by which the word `argument' ++came to have two different meanings, one in mathematics and the other in ++everyday English. According to the @cite{Oxford English Dictionary}, ++the word derives from the Latin for @samp{to make clear, prove}; thus it ++came to mean, by one thread of derivation, `the evidence offered as ++proof', which is to say, `the information offered', which led to its ++meaning in Lisp. But in the other thread of derivation, it came to mean ++`to assert in a manner against which others may make counter ++assertions', which led to the meaning of the word as a disputation. ++(Note here that the English word has two different definitions attached ++to it at the same time. By contrast, in Emacs Lisp, a symbol cannot ++have two different function definitions at the same time.)} ++ ++@menu ++* Data types:: Types of data passed to a function. ++* Args as Variable or List:: An argument can be the value ++ of a variable or list. ++* Variable Number of Arguments:: Some functions may take a ++ variable number of arguments. ++* Wrong Type of Argument:: Passing an argument of the wrong type ++ to a function. ++* message:: A useful function for sending messages. ++@end menu ++ ++@node Data types, Args as Variable or List, Arguments, Arguments ++@comment node-name, next, previous, up ++@subsection Arguments' Data Types ++@cindex Data types ++@cindex Types of data ++@cindex Arguments' data types ++ ++The type of data that should be passed to a function depends on what ++kind of information it uses. The arguments to a function such as ++@code{+} must have values that are numbers, since @code{+} adds numbers. ++Other functions use different kinds of data for their arguments. ++ ++@need 1250 ++@findex concat ++For example, the @code{concat} function links together or unites two or ++more strings of text to produce a string. The arguments are strings. ++Concatenating the two character strings @code{abc}, @code{def} produces ++the single string @code{abcdef}. This can be seen by evaluating the ++following: ++ ++@smallexample ++(concat "abc" "def") ++@end smallexample ++ ++@noindent ++The value produced by evaluating this expression is @code{"abcdef"}. ++ ++A function such as @code{substring} uses both a string and numbers as ++arguments. The function returns a part of the string, a substring of ++the first argument. This function takes three arguments. Its first ++argument is the string of characters, the second and third arguments are ++numbers that indicate the beginning and end of the substring. The ++numbers are a count of the number of characters (including spaces and ++punctuations) from the beginning of the string. ++ ++@need 800 ++For example, if you evaluate the following: ++ ++@smallexample ++(substring "The quick brown fox jumped." 16 19) ++@end smallexample ++ ++@noindent ++you will see @code{"fox"} appear in the echo area. The arguments are the ++string and the two numbers. ++ ++Note that the string passed to @code{substring} is a single atom even ++though it is made up of several words separated by spaces. Lisp counts ++everything between the two quotation marks as part of the string, ++including the spaces. You can think of the @code{substring} function as ++a kind of `atom smasher' since it takes an otherwise indivisible atom ++and extracts a part. However, @code{substring} is only able to extract ++a substring from an argument that is a string, not from another type of ++atom such as a number or symbol. ++ ++@node Args as Variable or List, Variable Number of Arguments, Data types, Arguments ++@comment node-name, next, previous, up ++@subsection An Argument as the Value of a Variable or List ++ ++An argument can be a symbol that returns a value when it is evaluated. ++For example, when the symbol @code{fill-column} by itself is evaluated, ++it returns a number. This number can be used in an addition. ++ ++@need 1250 ++Position the cursor after the following expression and type @kbd{C-x ++C-e}: ++ ++@smallexample ++(+ 2 fill-column) ++@end smallexample ++ ++@noindent ++The value will be a number two more than what you get by evaluating ++@code{fill-column} alone. For me, this is 74, because my value of ++@code{fill-column} is 72. ++ ++As we have just seen, an argument can be a symbol that returns a value ++when evaluated. In addition, an argument can be a list that returns a ++value when it is evaluated. For example, in the following expression, ++the arguments to the function @code{concat} are the strings ++@w{@code{"The "}} and @w{@code{" red foxes."}} and the list ++@code{(number-to-string (+ 2 fill-column))}. ++ ++@c For GNU Emacs 22, need number-to-string ++@smallexample ++(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") ++@end smallexample ++ ++@noindent ++If you evaluate this expression---and if, as with my Emacs, ++@code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will ++appear in the echo area. (Note that you must put spaces after the ++word @samp{The} and before the word @samp{red} so they will appear in ++the final string. The function @code{number-to-string} converts the ++integer that the addition function returns to a string. ++@code{number-to-string} is also known as @code{int-to-string}.) ++ ++@node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments ++@comment node-name, next, previous, up ++@subsection Variable Number of Arguments ++@cindex Variable number of arguments ++@cindex Arguments, variable number of ++ ++Some functions, such as @code{concat}, @code{+} or @code{*}, take any ++number of arguments. (The @code{*} is the symbol for multiplication.) ++This can be seen by evaluating each of the following expressions in ++the usual way. What you will see in the echo area is printed in this ++text after @samp{@result{}}, which you may read as `evaluates to'. ++ ++@need 1250 ++In the first set, the functions have no arguments: ++ ++@smallexample ++@group ++(+) @result{} 0 ++ ++(*) @result{} 1 ++@end group ++@end smallexample ++ ++@need 1250 ++In this set, the functions have one argument each: ++ ++@smallexample ++@group ++(+ 3) @result{} 3 ++ ++(* 3) @result{} 3 ++@end group ++@end smallexample ++ ++@need 1250 ++In this set, the functions have three arguments each: ++ ++@smallexample ++@group ++(+ 3 4 5) @result{} 12 ++ ++(* 3 4 5) @result{} 60 ++@end group ++@end smallexample ++ ++@node Wrong Type of Argument, message, Variable Number of Arguments, Arguments ++@comment node-name, next, previous, up ++@subsection Using the Wrong Type Object as an Argument ++@cindex Wrong type of argument ++@cindex Argument, wrong type of ++ ++When a function is passed an argument of the wrong type, the Lisp ++interpreter produces an error message. For example, the @code{+} ++function expects the values of its arguments to be numbers. As an ++experiment we can pass it the quoted symbol @code{hello} instead of a ++number. Position the cursor after the following expression and type ++@kbd{C-x C-e}: ++ ++@smallexample ++(+ 2 'hello) ++@end smallexample ++ ++@noindent ++When you do this you will generate an error message. What has happened ++is that @code{+} has tried to add the 2 to the value returned by ++@code{'hello}, but the value returned by @code{'hello} is the symbol ++@code{hello}, not a number. Only numbers can be added. So @code{+} ++could not carry out its addition. ++ ++@need 1250 ++In GNU Emacs version 22, you will create and enter a ++@file{*Backtrace*} buffer that says: ++ ++@noindent ++@smallexample ++@group ++---------- Buffer: *Backtrace* ---------- ++Debugger entered--Lisp error: ++ (wrong-type-argument number-or-marker-p hello) ++ +(2 hello) ++ eval((+ 2 (quote hello))) ++ eval-last-sexp-1(nil) ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++---------- Buffer: *Backtrace* ---------- ++@end group ++@end smallexample ++ ++@need 1250 ++As usual, the error message tries to be helpful and makes sense after you ++learn how to read it.@footnote{@code{(quote hello)} is an expansion of ++the abbreviation @code{'hello}.} ++ ++The first part of the error message is straightforward; it says ++@samp{wrong type argument}. Next comes the mysterious jargon word ++@w{@samp{number-or-marker-p}}. This word is trying to tell you what ++kind of argument the @code{+} expected. ++ ++The symbol @code{number-or-marker-p} says that the Lisp interpreter is ++trying to determine whether the information presented it (the value of ++the argument) is a number or a marker (a special object representing a ++buffer position). What it does is test to see whether the @code{+} is ++being given numbers to add. It also tests to see whether the ++argument is something called a marker, which is a specific feature of ++Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. ++When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command, ++its position is kept as a marker. The mark can be considered a ++number---the number of characters the location is from the beginning ++of the buffer.) In Emacs Lisp, @code{+} can be used to add the ++numeric value of marker positions as numbers. ++ ++The @samp{p} of @code{number-or-marker-p} is the embodiment of a ++practice started in the early days of Lisp programming. The @samp{p} ++stands for `predicate'. In the jargon used by the early Lisp ++researchers, a predicate refers to a function to determine whether some ++property is true or false. So the @samp{p} tells us that ++@code{number-or-marker-p} is the name of a function that determines ++whether it is true or false that the argument supplied is a number or ++a marker. Other Lisp symbols that end in @samp{p} include @code{zerop}, ++a function that tests whether its argument has the value of zero, and ++@code{listp}, a function that tests whether its argument is a list. ++ ++Finally, the last part of the error message is the symbol @code{hello}. ++This is the value of the argument that was passed to @code{+}. If the ++addition had been passed the correct type of object, the value passed ++would have been a number, such as 37, rather than a symbol like ++@code{hello}. But then you would not have got the error message. ++ ++@ignore ++@need 1250 ++In GNU Emacs version 20 and before, the echo area displays an error ++message that says: ++ ++@smallexample ++Wrong type argument:@: number-or-marker-p, hello ++@end smallexample ++ ++This says, in different words, the same as the top line of the ++@file{*Backtrace*} buffer. ++@end ignore ++ ++@node message, , Wrong Type of Argument, Arguments ++@comment node-name, next, previous, up ++@subsection The @code{message} Function ++@findex message ++ ++Like @code{+}, the @code{message} function takes a variable number of ++arguments. It is used to send messages to the user and is so useful ++that we will describe it here. ++ ++@need 1250 ++A message is printed in the echo area. For example, you can print a ++message in your echo area by evaluating the following list: ++ ++@smallexample ++(message "This message appears in the echo area!") ++@end smallexample ++ ++The whole string between double quotation marks is a single argument ++and is printed @i{in toto}. (Note that in this example, the message ++itself will appear in the echo area within double quotes; that is ++because you see the value returned by the @code{message} function. In ++most uses of @code{message} in programs that you write, the text will ++be printed in the echo area as a side-effect, without the quotes. ++@xref{multiply-by-seven in detail, , @code{multiply-by-seven} in ++detail}, for an example of this.) ++ ++However, if there is a @samp{%s} in the quoted string of characters, the ++@code{message} function does not print the @samp{%s} as such, but looks ++to the argument that follows the string. It evaluates the second ++argument and prints the value at the location in the string where the ++@samp{%s} is. ++ ++@need 1250 ++You can see this by positioning the cursor after the following ++expression and typing @kbd{C-x C-e}: ++ ++@smallexample ++(message "The name of this buffer is: %s." (buffer-name)) ++@end smallexample ++ ++@noindent ++In Info, @code{"The name of this buffer is: *info*."} will appear in the ++echo area. The function @code{buffer-name} returns the name of the ++buffer as a string, which the @code{message} function inserts in place ++of @code{%s}. ++ ++To print a value as an integer, use @samp{%d} in the same way as ++@samp{%s}. For example, to print a message in the echo area that ++states the value of the @code{fill-column}, evaluate the following: ++ ++@smallexample ++(message "The value of fill-column is %d." fill-column) ++@end smallexample ++ ++@noindent ++On my system, when I evaluate this list, @code{"The value of ++fill-column is 72."} appears in my echo area@footnote{Actually, you ++can use @code{%s} to print a number. It is non-specific. @code{%d} ++prints only the part of a number left of a decimal point, and not ++anything that is not a number.}. ++ ++If there is more than one @samp{%s} in the quoted string, the value of ++the first argument following the quoted string is printed at the ++location of the first @samp{%s} and the value of the second argument is ++printed at the location of the second @samp{%s}, and so on. ++ ++@need 1250 ++For example, if you evaluate the following, ++ ++@smallexample ++@group ++(message "There are %d %s in the office!" ++ (- fill-column 14) "pink elephants") ++@end group ++@end smallexample ++ ++@noindent ++a rather whimsical message will appear in your echo area. On my system ++it says, @code{"There are 58 pink elephants in the office!"}. ++ ++The expression @code{(- fill-column 14)} is evaluated and the resulting ++number is inserted in place of the @samp{%d}; and the string in double ++quotes, @code{"pink elephants"}, is treated as a single argument and ++inserted in place of the @samp{%s}. (That is to say, a string between ++double quotes evaluates to itself, like a number.) ++ ++Finally, here is a somewhat complex example that not only illustrates ++the computation of a number, but also shows how you can use an ++expression within an expression to generate the text that is substituted ++for @samp{%s}: ++ ++@smallexample ++@group ++(message "He saw %d %s" ++ (- fill-column 32) ++ (concat "red " ++ (substring ++ "The quick brown foxes jumped." 16 21) ++ " leaping.")) ++@end group ++@end smallexample ++ ++In this example, @code{message} has three arguments: the string, ++@code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and ++the expression beginning with the function @code{concat}. The value ++resulting from the evaluation of @code{(- fill-column 32)} is inserted ++in place of the @samp{%d}; and the value returned by the expression ++beginning with @code{concat} is inserted in place of the @samp{%s}. ++ ++When your fill column is 70 and you evaluate the expression, the ++message @code{"He saw 38 red foxes leaping."} appears in your echo ++area. ++ ++@node set & setq, Summary, Arguments, List Processing ++@comment node-name, next, previous, up ++@section Setting the Value of a Variable ++@cindex Variable, setting value ++@cindex Setting value of variable ++ ++@cindex @samp{bind} defined ++There are several ways by which a variable can be given a value. One of ++the ways is to use either the function @code{set} or the function ++@code{setq}. Another way is to use @code{let} (@pxref{let}). (The ++jargon for this process is to @dfn{bind} a variable to a value.) ++ ++The following sections not only describe how @code{set} and @code{setq} ++work but also illustrate how arguments are passed. ++ ++@menu ++* Using set:: Setting values. ++* Using setq:: Setting a quoted value. ++* Counting:: Using @code{setq} to count. ++@end menu ++ ++@node Using set, Using setq, set & setq, set & setq ++@comment node-name, next, previous, up ++@subsection Using @code{set} ++@findex set ++ ++To set the value of the symbol @code{flowers} to the list @code{'(rose ++violet daisy buttercup)}, evaluate the following expression by ++positioning the cursor after the expression and typing @kbd{C-x C-e}. ++ ++@smallexample ++(set 'flowers '(rose violet daisy buttercup)) ++@end smallexample ++ ++@noindent ++The list @code{(rose violet daisy buttercup)} will appear in the echo ++area. This is what is @emph{returned} by the @code{set} function. As a ++side effect, the symbol @code{flowers} is bound to the list; that is, ++the symbol @code{flowers}, which can be viewed as a variable, is given ++the list as its value. (This process, by the way, illustrates how a ++side effect to the Lisp interpreter, setting the value, can be the ++primary effect that we humans are interested in. This is because every ++Lisp function must return a value if it does not get an error, but it ++will only have a side effect if it is designed to have one.) ++ ++After evaluating the @code{set} expression, you can evaluate the symbol ++@code{flowers} and it will return the value you just set. Here is the ++symbol. Place your cursor after it and type @kbd{C-x C-e}. ++ ++@smallexample ++flowers ++@end smallexample ++ ++@noindent ++When you evaluate @code{flowers}, the list ++@code{(rose violet daisy buttercup)} appears in the echo area. ++ ++Incidentally, if you evaluate @code{'flowers}, the variable with a quote ++in front of it, what you will see in the echo area is the symbol itself, ++@code{flowers}. Here is the quoted symbol, so you can try this: ++ ++@smallexample ++'flowers ++@end smallexample ++ ++Note also, that when you use @code{set}, you need to quote both ++arguments to @code{set}, unless you want them evaluated. Since we do ++not want either argument evaluated, neither the variable ++@code{flowers} nor the list @code{(rose violet daisy buttercup)}, both ++are quoted. (When you use @code{set} without quoting its first ++argument, the first argument is evaluated before anything else is ++done. If you did this and @code{flowers} did not have a value ++already, you would get an error message that the @samp{Symbol's value ++as variable is void}; on the other hand, if @code{flowers} did return ++a value after it was evaluated, the @code{set} would attempt to set ++the value that was returned. There are situations where this is the ++right thing for the function to do; but such situations are rare.) ++ ++@node Using setq, Counting, Using set, set & setq ++@comment node-name, next, previous, up ++@subsection Using @code{setq} ++@findex setq ++ ++As a practical matter, you almost always quote the first argument to ++@code{set}. The combination of @code{set} and a quoted first argument ++is so common that it has its own name: the special form @code{setq}. ++This special form is just like @code{set} except that the first argument ++is quoted automatically, so you don't need to type the quote mark ++yourself. Also, as an added convenience, @code{setq} permits you to set ++several different variables to different values, all in one expression. ++ ++To set the value of the variable @code{carnivores} to the list ++@code{'(lion tiger leopard)} using @code{setq}, the following expression ++is used: ++ ++@smallexample ++(setq carnivores '(lion tiger leopard)) ++@end smallexample ++ ++@noindent ++This is exactly the same as using @code{set} except the first argument ++is automatically quoted by @code{setq}. (The @samp{q} in @code{setq} ++means @code{quote}.) ++ ++@need 1250 ++With @code{set}, the expression would look like this: ++ ++@smallexample ++(set 'carnivores '(lion tiger leopard)) ++@end smallexample ++ ++Also, @code{setq} can be used to assign different values to ++different variables. The first argument is bound to the value ++of the second argument, the third argument is bound to the value of the ++fourth argument, and so on. For example, you could use the following to ++assign a list of trees to the symbol @code{trees} and a list of herbivores ++to the symbol @code{herbivores}: ++ ++@smallexample ++@group ++(setq trees '(pine fir oak maple) ++ herbivores '(gazelle antelope zebra)) ++@end group ++@end smallexample ++ ++@noindent ++(The expression could just as well have been on one line, but it might ++not have fit on a page; and humans find it easier to read nicely ++formatted lists.) ++ ++Although I have been using the term `assign', there is another way of ++thinking about the workings of @code{set} and @code{setq}; and that is to ++say that @code{set} and @code{setq} make the symbol @emph{point} to the ++list. This latter way of thinking is very common and in forthcoming ++chapters we shall come upon at least one symbol that has `pointer' as ++part of its name. The name is chosen because the symbol has a value, ++specifically a list, attached to it; or, expressed another way, ++the symbol is set to ``point'' to the list. ++ ++@node Counting, , Using setq, set & setq ++@comment node-name, next, previous, up ++@subsection Counting ++@cindex Counting ++ ++Here is an example that shows how to use @code{setq} in a counter. You ++might use this to count how many times a part of your program repeats ++itself. First set a variable to zero; then add one to the number each ++time the program repeats itself. To do this, you need a variable that ++serves as a counter, and two expressions: an initial @code{setq} ++expression that sets the counter variable to zero; and a second ++@code{setq} expression that increments the counter each time it is ++evaluated. ++ ++@smallexample ++@group ++(setq counter 0) ; @r{Let's call this the initializer.} ++ ++(setq counter (+ counter 1)) ; @r{This is the incrementer.} ++ ++counter ; @r{This is the counter.} ++@end group ++@end smallexample ++ ++@noindent ++(The text following the @samp{;} are comments. @xref{Change a ++defun, , Change a Function Definition}.) ++ ++If you evaluate the first of these expressions, the initializer, ++@code{(setq counter 0)}, and then evaluate the third expression, ++@code{counter}, the number @code{0} will appear in the echo area. If ++you then evaluate the second expression, the incrementer, @code{(setq ++counter (+ counter 1))}, the counter will get the value 1. So if you ++again evaluate @code{counter}, the number @code{1} will appear in the ++echo area. Each time you evaluate the second expression, the value of ++the counter will be incremented. ++ ++When you evaluate the incrementer, @code{(setq counter (+ counter 1))}, ++the Lisp interpreter first evaluates the innermost list; this is the ++addition. In order to evaluate this list, it must evaluate the variable ++@code{counter} and the number @code{1}. When it evaluates the variable ++@code{counter}, it receives its current value. It passes this value and ++the number @code{1} to the @code{+} which adds them together. The sum ++is then returned as the value of the inner list and passed to the ++@code{setq} which sets the variable @code{counter} to this new value. ++Thus, the value of the variable, @code{counter}, is changed. ++ ++@node Summary, Error Message Exercises, set & setq, List Processing ++@comment node-name, next, previous, up ++@section Summary ++ ++Learning Lisp is like climbing a hill in which the first part is the ++steepest. You have now climbed the most difficult part; what remains ++becomes easier as you progress onwards. ++ ++@need 1000 ++In summary, ++ ++@itemize @bullet ++ ++@item ++Lisp programs are made up of expressions, which are lists or single atoms. ++ ++@item ++Lists are made up of zero or more atoms or inner lists, separated by whitespace and ++surrounded by parentheses. A list can be empty. ++ ++@item ++Atoms are multi-character symbols, like @code{forward-paragraph}, single ++character symbols like @code{+}, strings of characters between double ++quotation marks, or numbers. ++ ++@item ++A number evaluates to itself. ++ ++@item ++A string between double quotes also evaluates to itself. ++ ++@item ++When you evaluate a symbol by itself, its value is returned. ++ ++@item ++When you evaluate a list, the Lisp interpreter looks at the first symbol ++in the list and then at the function definition bound to that symbol. ++Then the instructions in the function definition are carried out. ++ ++@item ++A single quotation mark, ++@ifinfo ++' ++@end ifinfo ++@ifnotinfo ++@code{'} ++@end ifnotinfo ++, tells the Lisp interpreter that it should ++return the following expression as written, and not evaluate it as it ++would if the quote were not there. ++ ++@item ++Arguments are the information passed to a function. The arguments to a ++function are computed by evaluating the rest of the elements of the list ++of which the function is the first element. ++ ++@item ++A function always returns a value when it is evaluated (unless it gets ++an error); in addition, it may also carry out some action called a ++``side effect''. In many cases, a function's primary purpose is to ++create a side effect. ++@end itemize ++ ++@node Error Message Exercises, , Summary, List Processing ++@comment node-name, next, previous, up ++@section Exercises ++ ++A few simple exercises: ++ ++@itemize @bullet ++@item ++Generate an error message by evaluating an appropriate symbol that is ++not within parentheses. ++ ++@item ++Generate an error message by evaluating an appropriate symbol that is ++between parentheses. ++ ++@item ++Create a counter that increments by two rather than one. ++ ++@item ++Write an expression that prints a message in the echo area when ++evaluated. ++@end itemize ++ ++@node Practicing Evaluation, Writing Defuns, List Processing, Top ++@comment node-name, next, previous, up ++@chapter Practicing Evaluation ++@cindex Practicing evaluation ++@cindex Evaluation practice ++ ++Before learning how to write a function definition in Emacs Lisp, it is ++useful to spend a little time evaluating various expressions that have ++already been written. These expressions will be lists with the ++functions as their first (and often only) element. Since some of the ++functions associated with buffers are both simple and interesting, we ++will start with those. In this section, we will evaluate a few of ++these. In another section, we will study the code of several other ++buffer-related functions, to see how they were written. ++ ++@menu ++* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} ++ causes evaluation. ++* Buffer Names:: Buffers and files are different. ++* Getting Buffers:: Getting a buffer itself, not merely its name. ++* Switching Buffers:: How to change to another buffer. ++* Buffer Size & Locations:: Where point is located and the size of ++ the buffer. ++* Evaluation Exercise:: ++@end menu ++ ++@node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation ++@ifnottex ++@unnumberedsec How to Evaluate ++@end ifnottex ++ ++@i{Whenever you give an editing command} to Emacs Lisp, such as the ++command to move the cursor or to scroll the screen, @i{you are evaluating ++an expression,} the first element of which is a function. @i{This is ++how Emacs works.} ++ ++@cindex @samp{interactive function} defined ++@cindex @samp{command} defined ++When you type keys, you cause the Lisp interpreter to evaluate an ++expression and that is how you get your results. Even typing plain text ++involves evaluating an Emacs Lisp function, in this case, one that uses ++@code{self-insert-command}, which simply inserts the character you ++typed. The functions you evaluate by typing keystrokes are called ++@dfn{interactive} functions, or @dfn{commands}; how you make a function ++interactive will be illustrated in the chapter on how to write function ++definitions. @xref{Interactive, , Making a Function Interactive}. ++ ++In addition to typing keyboard commands, we have seen a second way to ++evaluate an expression: by positioning the cursor after a list and ++typing @kbd{C-x C-e}. This is what we will do in the rest of this ++section. There are other ways to evaluate an expression as well; these ++will be described as we come to them. ++ ++Besides being used for practicing evaluation, the functions shown in the ++next few sections are important in their own right. A study of these ++functions makes clear the distinction between buffers and files, how to ++switch to a buffer, and how to determine a location within it. ++ ++@node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation ++@comment node-name, next, previous, up ++@section Buffer Names ++@findex buffer-name ++@findex buffer-file-name ++ ++The two functions, @code{buffer-name} and @code{buffer-file-name}, show ++the difference between a file and a buffer. When you evaluate the ++following expression, @code{(buffer-name)}, the name of the buffer ++appears in the echo area. When you evaluate @code{(buffer-file-name)}, ++the name of the file to which the buffer refers appears in the echo ++area. Usually, the name returned by @code{(buffer-name)} is the same as ++the name of the file to which it refers, and the name returned by ++@code{(buffer-file-name)} is the full path-name of the file. ++ ++A file and a buffer are two different entities. A file is information ++recorded permanently in the computer (unless you delete it). A buffer, ++on the other hand, is information inside of Emacs that will vanish at ++the end of the editing session (or when you kill the buffer). Usually, ++a buffer contains information that you have copied from a file; we say ++the buffer is @dfn{visiting} that file. This copy is what you work on ++and modify. Changes to the buffer do not change the file, until you ++save the buffer. When you save the buffer, the buffer is copied to the file ++and is thus saved permanently. ++ ++@need 1250 ++If you are reading this in Info inside of GNU Emacs, you can evaluate ++each of the following expressions by positioning the cursor after it and ++typing @kbd{C-x C-e}. ++ ++@example ++@group ++(buffer-name) ++ ++(buffer-file-name) ++@end group ++@end example ++ ++@noindent ++When I do this in Info, the value returned by evaluating ++@code{(buffer-name)} is @file{"*info*"}, and the value returned by ++evaluating @code{(buffer-file-name)} is @file{nil}. ++ ++On the other hand, while I am writing this document, the value ++returned by evaluating @code{(buffer-name)} is ++@file{"introduction.texinfo"}, and the value returned by evaluating ++@code{(buffer-file-name)} is ++@file{"/gnu/work/intro/introduction.texinfo"}. ++ ++@cindex @code{nil}, history of word ++The former is the name of the buffer and the latter is the name of the ++file. In Info, the buffer name is @file{"*info*"}. Info does not ++point to any file, so the result of evaluating ++@code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is ++from the Latin word for `nothing'; in this case, it means that the ++buffer is not associated with any file. (In Lisp, @code{nil} is also ++used to mean `false' and is a synonym for the empty list, @code{()}.) ++ ++When I am writing, the name of my buffer is ++@file{"introduction.texinfo"}. The name of the file to which it ++points is @file{"/gnu/work/intro/introduction.texinfo"}. ++ ++(In the expressions, the parentheses tell the Lisp interpreter to ++treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as ++functions; without the parentheses, the interpreter would attempt to ++evaluate the symbols as variables. @xref{Variables}.) ++ ++In spite of the distinction between files and buffers, you will often ++find that people refer to a file when they mean a buffer and vice-verse. ++Indeed, most people say, ``I am editing a file,'' rather than saying, ++``I am editing a buffer which I will soon save to a file.'' It is ++almost always clear from context what people mean. When dealing with ++computer programs, however, it is important to keep the distinction in mind, ++since the computer is not as smart as a person. ++ ++@cindex Buffer, history of word ++The word `buffer', by the way, comes from the meaning of the word as a ++cushion that deadens the force of a collision. In early computers, a ++buffer cushioned the interaction between files and the computer's ++central processing unit. The drums or tapes that held a file and the ++central processing unit were pieces of equipment that were very ++different from each other, working at their own speeds, in spurts. The ++buffer made it possible for them to work together effectively. ++Eventually, the buffer grew from being an intermediary, a temporary ++holding place, to being the place where work is done. This ++transformation is rather like that of a small seaport that grew into a ++great city: once it was merely the place where cargo was warehoused ++temporarily before being loaded onto ships; then it became a business ++and cultural center in its own right. ++ ++Not all buffers are associated with files. For example, a ++@file{*scratch*} buffer does not visit any file. Similarly, a ++@file{*Help*} buffer is not associated with any file. ++ ++In the old days, when you lacked a @file{~/.emacs} file and started an ++Emacs session by typing the command @code{emacs} alone, without naming ++any files, Emacs started with the @file{*scratch*} buffer visible. ++Nowadays, you will see a splash screen. You can follow one of the ++commands suggested on the splash screen, visit a file, or press the ++spacebar to reach the @file{*scratch*} buffer. ++ ++If you switch to the @file{*scratch*} buffer, type ++@code{(buffer-name)}, position the cursor after it, and then type ++@kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"} ++will be returned and will appear in the echo area. @code{"*scratch*"} ++is the name of the buffer. When you type @code{(buffer-file-name)} in ++the @file{*scratch*} buffer and evaluate that, @code{nil} will appear ++in the echo area, just as it does when you evaluate ++@code{(buffer-file-name)} in Info. ++ ++Incidentally, if you are in the @file{*scratch*} buffer and want the ++value returned by an expression to appear in the @file{*scratch*} ++buffer itself rather than in the echo area, type @kbd{C-u C-x C-e} ++instead of @kbd{C-x C-e}. This causes the value returned to appear ++after the expression. The buffer will look like this: ++ ++@smallexample ++(buffer-name)"*scratch*" ++@end smallexample ++ ++@noindent ++You cannot do this in Info since Info is read-only and it will not allow ++you to change the contents of the buffer. But you can do this in any ++buffer you can edit; and when you write code or documentation (such as ++this book), this feature is very useful. ++ ++@node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation ++@comment node-name, next, previous, up ++@section Getting Buffers ++@findex current-buffer ++@findex other-buffer ++@cindex Getting a buffer ++ ++The @code{buffer-name} function returns the @emph{name} of the buffer; ++to get the buffer @emph{itself}, a different function is needed: the ++@code{current-buffer} function. If you use this function in code, what ++you get is the buffer itself. ++ ++A name and the object or entity to which the name refers are different ++from each other. You are not your name. You are a person to whom ++others refer by name. If you ask to speak to George and someone hands you ++a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r}, ++@samp{g}, and @samp{e} written on it, you might be amused, but you would ++not be satisfied. You do not want to speak to the name, but to the ++person to whom the name refers. A buffer is similar: the name of the ++scratch buffer is @file{*scratch*}, but the name is not the buffer. To ++get a buffer itself, you need to use a function such as ++@code{current-buffer}. ++ ++However, there is a slight complication: if you evaluate ++@code{current-buffer} in an expression on its own, as we will do here, ++what you see is a printed representation of the name of the buffer ++without the contents of the buffer. Emacs works this way for two ++reasons: the buffer may be thousands of lines long---too long to be ++conveniently displayed; and, another buffer may have the same contents ++but a different name, and it is important to distinguish between them. ++ ++@need 800 ++Here is an expression containing the function: ++ ++@smallexample ++(current-buffer) ++@end smallexample ++ ++@noindent ++If you evaluate this expression in Info in Emacs in the usual way, ++@file{#} will appear in the echo area. The special ++format indicates that the buffer itself is being returned, rather than ++just its name. ++ ++Incidentally, while you can type a number or symbol into a program, you ++cannot do that with the printed representation of a buffer: the only way ++to get a buffer itself is with a function such as @code{current-buffer}. ++ ++A related function is @code{other-buffer}. This returns the most ++recently selected buffer other than the one you are in currently, not ++a printed representation of its name. If you have recently switched ++back and forth from the @file{*scratch*} buffer, @code{other-buffer} ++will return that buffer. ++ ++@need 800 ++You can see this by evaluating the expression: ++ ++@smallexample ++(other-buffer) ++@end smallexample ++ ++@noindent ++You should see @file{#} appear in the echo area, or ++the name of whatever other buffer you switched back from most ++recently@footnote{Actually, by default, if the buffer from which you ++just switched is visible to you in another window, @code{other-buffer} ++will choose the most recent buffer that you cannot see; this is a ++subtlety that I often forget.}. ++ ++@node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation ++@comment node-name, next, previous, up ++@section Switching Buffers ++@findex switch-to-buffer ++@findex set-buffer ++@cindex Switching to a buffer ++ ++The @code{other-buffer} function actually provides a buffer when it is ++used as an argument to a function that requires one. We can see this ++by using @code{other-buffer} and @code{switch-to-buffer} to switch to a ++different buffer. ++ ++But first, a brief introduction to the @code{switch-to-buffer} ++function. When you switched back and forth from Info to the ++@file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most ++likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or ++rather, to save typing, you probably only typed @kbd{RET} if the ++default buffer was @file{*scratch*}, or if it was different, then you ++typed just part of the name, such as @code{*sc}, pressed your ++@kbd{TAB} key to cause it to expand to the full name, and then typed ++your @kbd{RET} key.} when prompted in the minibuffer for the name of ++the buffer to which you wanted to switch. The keystrokes, @kbd{C-x ++b}, cause the Lisp interpreter to evaluate the interactive function ++@code{switch-to-buffer}. As we said before, this is how Emacs works: ++different keystrokes call or run different functions. For example, ++@kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls ++@code{forward-sentence}, and so on. ++ ++By writing @code{switch-to-buffer} in an expression, and giving it a ++buffer to switch to, we can switch buffers just the way @kbd{C-x b} ++does. ++ ++@need 1000 ++Here is the Lisp expression: ++ ++@smallexample ++(switch-to-buffer (other-buffer)) ++@end smallexample ++ ++@noindent ++The symbol @code{switch-to-buffer} is the first element of the list, ++so the Lisp interpreter will treat it as a function and carry out the ++instructions that are attached to it. But before doing that, the ++interpreter will note that @code{other-buffer} is inside parentheses ++and work on that symbol first. @code{other-buffer} is the first (and ++in this case, the only) element of this list, so the Lisp interpreter ++calls or runs the function. It returns another buffer. Next, the ++interpreter runs @code{switch-to-buffer}, passing to it, as an ++argument, the other buffer, which is what Emacs will switch to. If ++you are reading this in Info, try this now. Evaluate the expression. ++(To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this ++expression will move you to your most recent other buffer that you ++cannot see. If you really want to go to your most recently selected ++buffer, even if you can still see it, you need to evaluate the ++following more complex expression: ++ ++@smallexample ++(switch-to-buffer (other-buffer (current-buffer) t)) ++@end smallexample ++ ++@c noindent ++In this case, the first argument to @code{other-buffer} tells it which ++buffer to skip---the current one---and the second argument tells ++@code{other-buffer} it is OK to switch to a visible buffer. ++In regular use, @code{switch-to-buffer} takes you to an invisible ++window since you would most likely use @kbd{C-x o} (@code{other-window}) ++to go to another visible buffer.} ++ ++In the programming examples in later sections of this document, you will ++see the function @code{set-buffer} more often than ++@code{switch-to-buffer}. This is because of a difference between ++computer programs and humans: humans have eyes and expect to see the ++buffer on which they are working on their computer terminals. This is ++so obvious, it almost goes without saying. However, programs do not ++have eyes. When a computer program works on a buffer, that buffer does ++not need to be visible on the screen. ++ ++@code{switch-to-buffer} is designed for humans and does two different ++things: it switches the buffer to which Emacs' attention is directed; and ++it switches the buffer displayed in the window to the new buffer. ++@code{set-buffer}, on the other hand, does only one thing: it switches ++the attention of the computer program to a different buffer. The buffer ++on the screen remains unchanged (of course, normally nothing happens ++there until the command finishes running). ++ ++@cindex @samp{call} defined ++Also, we have just introduced another jargon term, the word @dfn{call}. ++When you evaluate a list in which the first symbol is a function, you ++are calling that function. The use of the term comes from the notion of ++the function as an entity that can do something for you if you `call' ++it---just as a plumber is an entity who can fix a leak if you call him ++or her. ++ ++@node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation ++@comment node-name, next, previous, up ++@section Buffer Size and the Location of Point ++@cindex Size of buffer ++@cindex Buffer size ++@cindex Point location ++@cindex Location of point ++ ++Finally, let's look at several rather simple functions, ++@code{buffer-size}, @code{point}, @code{point-min}, and ++@code{point-max}. These give information about the size of a buffer and ++the location of point within it. ++ ++The function @code{buffer-size} tells you the size of the current ++buffer; that is, the function returns a count of the number of ++characters in the buffer. ++ ++@smallexample ++(buffer-size) ++@end smallexample ++ ++@noindent ++You can evaluate this in the usual way, by positioning the ++cursor after the expression and typing @kbd{C-x C-e}. ++ ++@cindex @samp{point} defined ++In Emacs, the current position of the cursor is called @dfn{point}. ++The expression @code{(point)} returns a number that tells you where the ++cursor is located as a count of the number of characters from the ++beginning of the buffer up to point. ++ ++@need 1250 ++You can see the character count for point in this buffer by evaluating ++the following expression in the usual way: ++ ++@smallexample ++(point) ++@end smallexample ++ ++@noindent ++As I write this, the value of @code{point} is 65724. The @code{point} ++function is frequently used in some of the examples later in this ++book. ++ ++@need 1250 ++The value of point depends, of course, on its location within the ++buffer. If you evaluate point in this spot, the number will be larger: ++ ++@smallexample ++(point) ++@end smallexample ++ ++@noindent ++For me, the value of point in this location is 66043, which means that ++there are 319 characters (including spaces) between the two ++expressions. (Doubtless, you will see different numbers, since I will ++have edited this since I first evaluated point.) ++ ++@cindex @samp{narrowing} defined ++The function @code{point-min} is somewhat similar to @code{point}, but ++it returns the value of the minimum permissible value of point in the ++current buffer. This is the number 1 unless @dfn{narrowing} is in ++effect. (Narrowing is a mechanism whereby you can restrict yourself, ++or a program, to operations on just a part of a buffer. ++@xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the ++function @code{point-max} returns the value of the maximum permissible ++value of point in the current buffer. ++ ++@node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation ++@section Exercise ++ ++Find a file with which you are working and move towards its middle. ++Find its buffer name, file name, length, and your position in the file. ++ ++@node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top ++@comment node-name, next, previous, up ++@chapter How To Write Function Definitions ++@cindex Definition writing ++@cindex Function definition writing ++@cindex Writing a function definition ++ ++When the Lisp interpreter evaluates a list, it looks to see whether the ++first symbol on the list has a function definition attached to it; or, ++put another way, whether the symbol points to a function definition. If ++it does, the computer carries out the instructions in the definition. A ++symbol that has a function definition is called, simply, a function ++(although, properly speaking, the definition is the function and the ++symbol refers to it.) ++ ++@menu ++* Primitive Functions:: ++* defun:: The @code{defun} special form. ++* Install:: Install a function definition. ++* Interactive:: Making a function interactive. ++* Interactive Options:: Different options for @code{interactive}. ++* Permanent Installation:: Installing code permanently. ++* let:: Creating and initializing local variables. ++* if:: What if? ++* else:: If--then--else expressions. ++* Truth & Falsehood:: What Lisp considers false and true. ++* save-excursion:: Keeping track of point, mark, and buffer. ++* Review:: ++* defun Exercises:: ++@end menu ++ ++@node Primitive Functions, defun, Writing Defuns, Writing Defuns ++@ifnottex ++@unnumberedsec An Aside about Primitive Functions ++@end ifnottex ++@cindex Primitive functions ++@cindex Functions, primitive ++ ++@cindex C language primitives ++@cindex Primitives written in C ++All functions are defined in terms of other functions, except for a few ++@dfn{primitive} functions that are written in the C programming ++language. When you write functions' definitions, you will write them in ++Emacs Lisp and use other functions as your building blocks. Some of the ++functions you will use will themselves be written in Emacs Lisp (perhaps ++by you) and some will be primitives written in C. The primitive ++functions are used exactly like those written in Emacs Lisp and behave ++like them. They are written in C so we can easily run GNU Emacs on any ++computer that has sufficient power and can run C. ++ ++Let me re-emphasize this: when you write code in Emacs Lisp, you do not ++distinguish between the use of functions written in C and the use of ++functions written in Emacs Lisp. The difference is irrelevant. I ++mention the distinction only because it is interesting to know. Indeed, ++unless you investigate, you won't know whether an already-written ++function is written in Emacs Lisp or C. ++ ++@node defun, Install, Primitive Functions, Writing Defuns ++@comment node-name, next, previous, up ++@section The @code{defun} Special Form ++@findex defun ++@cindex Special form of @code{defun} ++ ++@cindex @samp{function definition} defined ++In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to ++it that tells the computer what to do when the function is called. ++This code is called the @dfn{function definition} and is created by ++evaluating a Lisp expression that starts with the symbol @code{defun} ++(which is an abbreviation for @emph{define function}). Because ++@code{defun} does not evaluate its arguments in the usual way, it is ++called a @dfn{special form}. ++ ++In subsequent sections, we will look at function definitions from the ++Emacs source code, such as @code{mark-whole-buffer}. In this section, ++we will describe a simple function definition so you can see how it ++looks. This function definition uses arithmetic because it makes for a ++simple example. Some people dislike examples using arithmetic; however, ++if you are such a person, do not despair. Hardly any of the code we ++will study in the remainder of this introduction involves arithmetic or ++mathematics. The examples mostly involve text in one way or another. ++ ++A function definition has up to five parts following the word ++@code{defun}: ++ ++@enumerate ++@item ++The name of the symbol to which the function definition should be ++attached. ++ ++@item ++A list of the arguments that will be passed to the function. If no ++arguments will be passed to the function, this is an empty list, ++@code{()}. ++ ++@item ++Documentation describing the function. (Technically optional, but ++strongly recommended.) ++ ++@item ++Optionally, an expression to make the function interactive so you can ++use it by typing @kbd{M-x} and then the name of the function; or by ++typing an appropriate key or keychord. ++ ++@cindex @samp{body} defined ++@item ++The code that instructs the computer what to do: the @dfn{body} of the ++function definition. ++@end enumerate ++ ++It is helpful to think of the five parts of a function definition as ++being organized in a template, with slots for each part: ++ ++@smallexample ++@group ++(defun @var{function-name} (@var{arguments}@dots{}) ++ "@var{optional-documentation}@dots{}" ++ (interactive @var{argument-passing-info}) ; @r{optional} ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++As an example, here is the code for a function that multiplies its ++argument by 7. (This example is not interactive. @xref{Interactive, ++, Making a Function Interactive}, for that information.) ++ ++@smallexample ++@group ++(defun multiply-by-seven (number) ++ "Multiply NUMBER by seven." ++ (* 7 number)) ++@end group ++@end smallexample ++ ++This definition begins with a parenthesis and the symbol @code{defun}, ++followed by the name of the function. ++ ++@cindex @samp{argument list} defined ++The name of the function is followed by a list that contains the ++arguments that will be passed to the function. This list is called ++the @dfn{argument list}. In this example, the list has only one ++element, the symbol, @code{number}. When the function is used, the ++symbol will be bound to the value that is used as the argument to the ++function. ++ ++Instead of choosing the word @code{number} for the name of the argument, ++I could have picked any other name. For example, I could have chosen ++the word @code{multiplicand}. I picked the word `number' because it ++tells what kind of value is intended for this slot; but I could just as ++well have chosen the word `multiplicand' to indicate the role that the ++value placed in this slot will play in the workings of the function. I ++could have called it @code{foogle}, but that would have been a bad ++choice because it would not tell humans what it means. The choice of ++name is up to the programmer and should be chosen to make the meaning of ++the function clear. ++ ++Indeed, you can choose any name you wish for a symbol in an argument ++list, even the name of a symbol used in some other function: the name ++you use in an argument list is private to that particular definition. ++In that definition, the name refers to a different entity than any use ++of the same name outside the function definition. Suppose you have a ++nick-name `Shorty' in your family; when your family members refer to ++`Shorty', they mean you. But outside your family, in a movie, for ++example, the name `Shorty' refers to someone else. Because a name in an ++argument list is private to the function definition, you can change the ++value of such a symbol inside the body of a function without changing ++its value outside the function. The effect is similar to that produced ++by a @code{let} expression. (@xref{let, , @code{let}}.) ++ ++@ignore ++Note also that we discuss the word `number' in two different ways: as a ++symbol that appears in the code, and as the name of something that will ++be replaced by a something else during the evaluation of the function. ++In the first case, @code{number} is a symbol, not a number; it happens ++that within the function, it is a variable who value is the number in ++question, but our primary interest in it is as a symbol. On the other ++hand, when we are talking about the function, our interest is that we ++will substitute a number for the word @var{number}. To keep this ++distinction clear, we use different typography for the two ++circumstances. When we talk about this function, or about how it works, ++we refer to this number by writing @var{number}. In the function ++itself, we refer to it by writing @code{number}. ++@end ignore ++ ++The argument list is followed by the documentation string that ++describes the function. This is what you see when you type ++@w{@kbd{C-h f}} and the name of a function. Incidentally, when you ++write a documentation string like this, you should make the first line ++a complete sentence since some commands, such as @code{apropos}, print ++only the first line of a multi-line documentation string. Also, you ++should not indent the second line of a documentation string, if you ++have one, because that looks odd when you use @kbd{C-h f} ++(@code{describe-function}). The documentation string is optional, but ++it is so useful, it should be included in almost every function you ++write. ++ ++@findex * @r{(multiplication)} ++The third line of the example consists of the body of the function ++definition. (Most functions' definitions, of course, are longer than ++this.) In this function, the body is the list, @code{(* 7 number)}, which ++says to multiply the value of @var{number} by 7. (In Emacs Lisp, ++@code{*} is the function for multiplication, just as @code{+} is the ++function for addition.) ++ ++When you use the @code{multiply-by-seven} function, the argument ++@code{number} evaluates to the actual number you want used. Here is an ++example that shows how @code{multiply-by-seven} is used; but don't try ++to evaluate this yet! ++ ++@smallexample ++(multiply-by-seven 3) ++@end smallexample ++ ++@noindent ++The symbol @code{number}, specified in the function definition in the ++next section, is given or ``bound to'' the value 3 in the actual use of ++the function. Note that although @code{number} was inside parentheses ++in the function definition, the argument passed to the ++@code{multiply-by-seven} function is not in parentheses. The ++parentheses are written in the function definition so the computer can ++figure out where the argument list ends and the rest of the function ++definition begins. ++ ++If you evaluate this example, you are likely to get an error message. ++(Go ahead, try it!) This is because we have written the function ++definition, but not yet told the computer about the definition---we have ++not yet installed (or `loaded') the function definition in Emacs. ++Installing a function is the process that tells the Lisp interpreter the ++definition of the function. Installation is described in the next ++section. ++ ++@node Install, Interactive, defun, Writing Defuns ++@comment node-name, next, previous, up ++@section Install a Function Definition ++@cindex Install a Function Definition ++@cindex Definition installation ++@cindex Function definition installation ++ ++If you are reading this inside of Info in Emacs, you can try out the ++@code{multiply-by-seven} function by first evaluating the function ++definition and then evaluating @code{(multiply-by-seven 3)}. A copy of ++the function definition follows. Place the cursor after the last ++parenthesis of the function definition and type @kbd{C-x C-e}. When you ++do this, @code{multiply-by-seven} will appear in the echo area. (What ++this means is that when a function definition is evaluated, the value it ++returns is the name of the defined function.) At the same time, this ++action installs the function definition. ++ ++@smallexample ++@group ++(defun multiply-by-seven (number) ++ "Multiply NUMBER by seven." ++ (* 7 number)) ++@end group ++@end smallexample ++ ++@noindent ++By evaluating this @code{defun}, you have just installed ++@code{multiply-by-seven} in Emacs. The function is now just as much a ++part of Emacs as @code{forward-word} or any other editing function you ++use. (@code{multiply-by-seven} will stay installed until you quit ++Emacs. To reload code automatically whenever you start Emacs, see ++@ref{Permanent Installation, , Installing Code Permanently}.) ++ ++@menu ++* Effect of installation:: ++* Change a defun:: How to change a function definition. ++@end menu ++ ++@node Effect of installation, Change a defun, Install, Install ++@ifnottex ++@unnumberedsubsec The effect of installation ++@end ifnottex ++ ++You can see the effect of installing @code{multiply-by-seven} by ++evaluating the following sample. Place the cursor after the following ++expression and type @kbd{C-x C-e}. The number 21 will appear in the ++echo area. ++ ++@smallexample ++(multiply-by-seven 3) ++@end smallexample ++ ++If you wish, you can read the documentation for the function by typing ++@kbd{C-h f} (@code{describe-function}) and then the name of the ++function, @code{multiply-by-seven}. When you do this, a ++@file{*Help*} window will appear on your screen that says: ++ ++@smallexample ++@group ++multiply-by-seven is a Lisp function. ++(multiply-by-seven NUMBER) ++ ++Multiply NUMBER by seven. ++@end group ++@end smallexample ++ ++@noindent ++(To return to a single window on your screen, type @kbd{C-x 1}.) ++ ++@node Change a defun, , Effect of installation, Install ++@comment node-name, next, previous, up ++@subsection Change a Function Definition ++@cindex Changing a function definition ++@cindex Function definition, how to change ++@cindex Definition, how to change ++ ++If you want to change the code in @code{multiply-by-seven}, just rewrite ++it. To install the new version in place of the old one, evaluate the ++function definition again. This is how you modify code in Emacs. It is ++very simple. ++ ++As an example, you can change the @code{multiply-by-seven} function to ++add the number to itself seven times instead of multiplying the number ++by seven. It produces the same answer, but by a different path. At ++the same time, we will add a comment to the code; a comment is text ++that the Lisp interpreter ignores, but that a human reader may find ++useful or enlightening. The comment is that this is the ``second ++version''. ++ ++@smallexample ++@group ++(defun multiply-by-seven (number) ; @r{Second version.} ++ "Multiply NUMBER by seven." ++ (+ number number number number number number number)) ++@end group ++@end smallexample ++ ++@cindex Comments in Lisp code ++The comment follows a semicolon, @samp{;}. In Lisp, everything on a ++line that follows a semicolon is a comment. The end of the line is the ++end of the comment. To stretch a comment over two or more lines, begin ++each line with a semicolon. ++ ++@xref{Beginning a .emacs File, , Beginning a @file{.emacs} ++File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp ++Reference Manual}, for more about comments. ++ ++You can install this version of the @code{multiply-by-seven} function by ++evaluating it in the same way you evaluated the first function: place ++the cursor after the last parenthesis and type @kbd{C-x C-e}. ++ ++In summary, this is how you write code in Emacs Lisp: you write a ++function; install it; test it; and then make fixes or enhancements and ++install it again. ++ ++@node Interactive, Interactive Options, Install, Writing Defuns ++@comment node-name, next, previous, up ++@section Make a Function Interactive ++@cindex Interactive functions ++@findex interactive ++ ++You make a function interactive by placing a list that begins with ++the special form @code{interactive} immediately after the ++documentation. A user can invoke an interactive function by typing ++@kbd{M-x} and then the name of the function; or by typing the keys to ++which it is bound, for example, by typing @kbd{C-n} for ++@code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}. ++ ++Interestingly, when you call an interactive function interactively, ++the value returned is not automatically displayed in the echo area. ++This is because you often call an interactive function for its side ++effects, such as moving forward by a word or line, and not for the ++value returned. If the returned value were displayed in the echo area ++each time you typed a key, it would be very distracting. ++ ++@menu ++* Interactive multiply-by-seven:: An overview. ++* multiply-by-seven in detail:: The interactive version. ++@end menu ++ ++@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive ++@ifnottex ++@unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview ++@end ifnottex ++ ++Both the use of the special form @code{interactive} and one way to ++display a value in the echo area can be illustrated by creating an ++interactive version of @code{multiply-by-seven}. ++ ++@need 1250 ++Here is the code: ++ ++@smallexample ++@group ++(defun multiply-by-seven (number) ; @r{Interactive version.} ++ "Multiply NUMBER by seven." ++ (interactive "p") ++ (message "The result is %d" (* 7 number))) ++@end group ++@end smallexample ++ ++@noindent ++You can install this code by placing your cursor after it and typing ++@kbd{C-x C-e}. The name of the function will appear in your echo area. ++Then, you can use this code by typing @kbd{C-u} and a number and then ++typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase ++@samp{The result is @dots{}} followed by the product will appear in the ++echo area. ++ ++Speaking more generally, you invoke a function like this in either of two ++ways: ++ ++@enumerate ++@item ++By typing a prefix argument that contains the number to be passed, and ++then typing @kbd{M-x} and the name of the function, as with ++@kbd{C-u 3 M-x forward-sentence}; or, ++ ++@item ++By typing whatever key or keychord the function is bound to, as with ++@kbd{C-u 3 M-e}. ++@end enumerate ++ ++@noindent ++Both the examples just mentioned work identically to move point forward ++three sentences. (Since @code{multiply-by-seven} is not bound to a key, ++it could not be used as an example of key binding.) ++ ++(@xref{Keybindings, , Some Keybindings}, to learn how to bind a command ++to a key.) ++ ++A prefix argument is passed to an interactive function by typing the ++@key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by ++typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you ++type @kbd{C-u} without a number, it defaults to 4). ++ ++@node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive ++@comment node-name, next, previous, up ++@subsection An Interactive @code{multiply-by-seven} ++ ++Let's look at the use of the special form @code{interactive} and then at ++the function @code{message} in the interactive version of ++@code{multiply-by-seven}. You will recall that the function definition ++looks like this: ++ ++@smallexample ++@group ++(defun multiply-by-seven (number) ; @r{Interactive version.} ++ "Multiply NUMBER by seven." ++ (interactive "p") ++ (message "The result is %d" (* 7 number))) ++@end group ++@end smallexample ++ ++In this function, the expression, @code{(interactive "p")}, is a list of ++two elements. The @code{"p"} tells Emacs to pass the prefix argument to ++the function and use its value for the argument of the function. ++ ++@need 1000 ++The argument will be a number. This means that the symbol ++@code{number} will be bound to a number in the line: ++ ++@smallexample ++(message "The result is %d" (* 7 number)) ++@end smallexample ++ ++@need 1250 ++@noindent ++For example, if your prefix argument is 5, the Lisp interpreter will ++evaluate the line as if it were: ++ ++@smallexample ++(message "The result is %d" (* 7 5)) ++@end smallexample ++ ++@noindent ++(If you are reading this in GNU Emacs, you can evaluate this expression ++yourself.) First, the interpreter will evaluate the inner list, which ++is @code{(* 7 5)}. This returns a value of 35. Next, it ++will evaluate the outer list, passing the values of the second and ++subsequent elements of the list to the function @code{message}. ++ ++As we have seen, @code{message} is an Emacs Lisp function especially ++designed for sending a one line message to a user. (@xref{message, , ++The @code{message} function}.) In summary, the @code{message} ++function prints its first argument in the echo area as is, except for ++occurrences of @samp{%d} or @samp{%s} (and various other %-sequences ++which we have not mentioned). When it sees a control sequence, the ++function looks to the second or subsequent arguments and prints the ++value of the argument in the location in the string where the control ++sequence is located. ++ ++In the interactive @code{multiply-by-seven} function, the control string ++is @samp{%d}, which requires a number, and the value returned by ++evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35 ++is printed in place of the @samp{%d} and the message is @samp{The result ++is 35}. ++ ++(Note that when you call the function @code{multiply-by-seven}, the ++message is printed without quotes, but when you call @code{message}, the ++text is printed in double quotes. This is because the value returned by ++@code{message} is what appears in the echo area when you evaluate an ++expression whose first element is @code{message}; but when embedded in a ++function, @code{message} prints the text as a side effect without ++quotes.) ++ ++@node Interactive Options, Permanent Installation, Interactive, Writing Defuns ++@comment node-name, next, previous, up ++@section Different Options for @code{interactive} ++@cindex Options for @code{interactive} ++@cindex Interactive options ++ ++In the example, @code{multiply-by-seven} used @code{"p"} as the ++argument to @code{interactive}. This argument told Emacs to interpret ++your typing either @kbd{C-u} followed by a number or @key{META} ++followed by a number as a command to pass that number to the function ++as its argument. Emacs has more than twenty characters predefined for ++use with @code{interactive}. In almost every case, one of these ++options will enable you to pass the right information interactively to ++a function. (@xref{Interactive Codes, , Code Characters for ++@code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.) ++ ++@need 1250 ++Consider the function @code{zap-to-char}. Its interactive expression ++is ++ ++@smallexample ++(interactive "p\ncZap to char: ") ++@end smallexample ++ ++The first part of the argument to @code{interactive} is @samp{p}, with ++which you are already familiar. This argument tells Emacs to ++interpret a `prefix', as a number to be passed to the function. You ++can specify a prefix either by typing @kbd{C-u} followed by a number ++or by typing @key{META} followed by a number. The prefix is the ++number of specified characters. Thus, if your prefix is three and the ++specified character is @samp{x}, then you will delete all the text up ++to and including the third next @samp{x}. If you do not set a prefix, ++then you delete all the text up to and including the specified ++character, but no more. ++ ++The @samp{c} tells the function the name of the character to which to delete. ++ ++More formally, a function with two or more arguments can have ++information passed to each argument by adding parts to the string that ++follows @code{interactive}. When you do this, the information is ++passed to each argument in the same order it is specified in the ++@code{interactive} list. In the string, each part is separated from ++the next part by a @samp{\n}, which is a newline. For example, you ++can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }. ++This causes Emacs to pass the value of the prefix argument (if there ++is one) and the character. ++ ++In this case, the function definition looks like the following, where ++@code{arg} and @code{char} are the symbols to which @code{interactive} ++binds the prefix argument and the specified character: ++ ++@smallexample ++@group ++(defun @var{name-of-function} (arg char) ++ "@var{documentation}@dots{}" ++ (interactive "p\ncZap to char: ") ++ @var{body-of-function}@dots{}) ++@end group ++@end smallexample ++ ++@noindent ++(The space after the colon in the prompt makes it look better when you ++are prompted. @xref{copy-to-buffer, , The Definition of ++@code{copy-to-buffer}}, for an example.) ++ ++When a function does not take arguments, @code{interactive} does not ++require any. Such a function contains the simple expression ++@code{(interactive)}. The @code{mark-whole-buffer} function is like ++this. ++ ++Alternatively, if the special letter-codes are not right for your ++application, you can pass your own arguments to @code{interactive} as ++a list. ++ ++@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}, ++for an example. @xref{Using Interactive, , Using @code{Interactive}, ++elisp, The GNU Emacs Lisp Reference Manual}, for a more complete ++explanation about this technique. ++ ++@node Permanent Installation, let, Interactive Options, Writing Defuns ++@comment node-name, next, previous, up ++@section Install Code Permanently ++@cindex Install code permanently ++@cindex Permanent code installation ++@cindex Code installation ++ ++When you install a function definition by evaluating it, it will stay ++installed until you quit Emacs. The next time you start a new session ++of Emacs, the function will not be installed unless you evaluate the ++function definition again. ++ ++At some point, you may want to have code installed automatically ++whenever you start a new session of Emacs. There are several ways of ++doing this: ++ ++@itemize @bullet ++@item ++If you have code that is just for yourself, you can put the code for the ++function definition in your @file{.emacs} initialization file. When you ++start Emacs, your @file{.emacs} file is automatically evaluated and all ++the function definitions within it are installed. ++@xref{Emacs Initialization, , Your @file{.emacs} File}. ++ ++@item ++Alternatively, you can put the function definitions that you want ++installed in one or more files of their own and use the @code{load} ++function to cause Emacs to evaluate and thereby install each of the ++functions in the files. ++@xref{Loading Files, , Loading Files}. ++ ++@item ++Thirdly, if you have code that your whole site will use, it is usual ++to put it in a file called @file{site-init.el} that is loaded when ++Emacs is built. This makes the code available to everyone who uses ++your machine. (See the @file{INSTALL} file that is part of the Emacs ++distribution.) ++@end itemize ++ ++Finally, if you have code that everyone who uses Emacs may want, you ++can post it on a computer network or send a copy to the Free Software ++Foundation. (When you do this, please license the code and its ++documentation under a license that permits other people to run, copy, ++study, modify, and redistribute the code and which protects you from ++having your work taken from you.) If you send a copy of your code to ++the Free Software Foundation, and properly protect yourself and ++others, it may be included in the next release of Emacs. In large ++part, this is how Emacs has grown over the past years, by donations. ++ ++@node let, if, Permanent Installation, Writing Defuns ++@comment node-name, next, previous, up ++@section @code{let} ++@findex let ++ ++The @code{let} expression is a special form in Lisp that you will need ++to use in most function definitions. ++ ++@code{let} is used to attach or bind a symbol to a value in such a way ++that the Lisp interpreter will not confuse the variable with a ++variable of the same name that is not part of the function. ++ ++To understand why the @code{let} special form is necessary, consider ++the situation in which you own a home that you generally refer to as ++`the house', as in the sentence, ``The house needs painting.'' If you ++are visiting a friend and your host refers to `the house', he is ++likely to be referring to @emph{his} house, not yours, that is, to a ++different house. ++ ++If your friend is referring to his house and you think he is referring ++to your house, you may be in for some confusion. The same thing could ++happen in Lisp if a variable that is used inside of one function has ++the same name as a variable that is used inside of another function, ++and the two are not intended to refer to the same value. The ++@code{let} special form prevents this kind of confusion. ++ ++@menu ++* Prevent confusion:: ++* Parts of let Expression:: ++* Sample let Expression:: ++* Uninitialized let Variables:: ++@end menu ++ ++@node Prevent confusion, Parts of let Expression, let, let ++@ifnottex ++@unnumberedsubsec @code{let} Prevents Confusion ++@end ifnottex ++ ++@cindex @samp{local variable} defined ++@cindex @samp{variable, local}, defined ++The @code{let} special form prevents confusion. @code{let} creates a ++name for a @dfn{local variable} that overshadows any use of the same ++name outside the @code{let} expression. This is like understanding ++that whenever your host refers to `the house', he means his house, not ++yours. (Symbols used in argument lists work the same way. ++@xref{defun, , The @code{defun} Special Form}.) ++ ++Local variables created by a @code{let} expression retain their value ++@emph{only} within the @code{let} expression itself (and within ++expressions called within the @code{let} expression); the local ++variables have no effect outside the @code{let} expression. ++ ++Another way to think about @code{let} is that it is like a @code{setq} ++that is temporary and local. The values set by @code{let} are ++automatically undone when the @code{let} is finished. The setting ++only affects expressions that are inside the bounds of the @code{let} ++expression. In computer science jargon, we would say ``the binding of ++a symbol is visible only in functions called in the @code{let} form; ++in Emacs Lisp, scoping is dynamic, not lexical.'' ++ ++@code{let} can create more than one variable at once. Also, ++@code{let} gives each variable it creates an initial value, either a ++value specified by you, or @code{nil}. (In the jargon, this is called ++`binding the variable to the value'.) After @code{let} has created ++and bound the variables, it executes the code in the body of the ++@code{let}, and returns the value of the last expression in the body, ++as the value of the whole @code{let} expression. (`Execute' is a jargon ++term that means to evaluate a list; it comes from the use of the word ++meaning `to give practical effect to' (@cite{Oxford English ++Dictionary}). Since you evaluate an expression to perform an action, ++`execute' has evolved as a synonym to `evaluate'.) ++ ++@node Parts of let Expression, Sample let Expression, Prevent confusion, let ++@comment node-name, next, previous, up ++@subsection The Parts of a @code{let} Expression ++@cindex @code{let} expression, parts of ++@cindex Parts of @code{let} expression ++ ++@cindex @samp{varlist} defined ++A @code{let} expression is a list of three parts. The first part is ++the symbol @code{let}. The second part is a list, called a ++@dfn{varlist}, each element of which is either a symbol by itself or a ++two-element list, the first element of which is a symbol. The third ++part of the @code{let} expression is the body of the @code{let}. The ++body usually consists of one or more lists. ++ ++@need 800 ++A template for a @code{let} expression looks like this: ++ ++@smallexample ++(let @var{varlist} @var{body}@dots{}) ++@end smallexample ++ ++@noindent ++The symbols in the varlist are the variables that are given initial ++values by the @code{let} special form. Symbols by themselves are given ++the initial value of @code{nil}; and each symbol that is the first ++element of a two-element list is bound to the value that is returned ++when the Lisp interpreter evaluates the second element. ++ ++Thus, a varlist might look like this: @code{(thread (needles 3))}. In ++this case, in a @code{let} expression, Emacs binds the symbol ++@code{thread} to an initial value of @code{nil}, and binds the symbol ++@code{needles} to an initial value of 3. ++ ++When you write a @code{let} expression, what you do is put the ++appropriate expressions in the slots of the @code{let} expression ++template. ++ ++If the varlist is composed of two-element lists, as is often the case, ++the template for the @code{let} expression looks like this: ++ ++@smallexample ++@group ++(let ((@var{variable} @var{value}) ++ (@var{variable} @var{value}) ++ @dots{}) ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++@node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let ++@comment node-name, next, previous, up ++@subsection Sample @code{let} Expression ++@cindex Sample @code{let} expression ++@cindex @code{let} expression sample ++ ++The following expression creates and gives initial values ++to the two variables @code{zebra} and @code{tiger}. The body of the ++@code{let} expression is a list which calls the @code{message} function. ++ ++@smallexample ++@group ++(let ((zebra 'stripes) ++ (tiger 'fierce)) ++ (message "One kind of animal has %s and another is %s." ++ zebra tiger)) ++@end group ++@end smallexample ++ ++Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. ++ ++The two variables are @code{zebra} and @code{tiger}. Each variable is ++the first element of a two-element list and each value is the second ++element of its two-element list. In the varlist, Emacs binds the ++variable @code{zebra} to the value @code{stripes}@footnote{According ++to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras ++become impossibly dangerous as they grow older'' but the claim here is ++that they do not become fierce like a tiger. (1997, W. W. Norton and ++Co., ISBN 0-393-03894-2, page 171)}, and binds the ++variable @code{tiger} to the value @code{fierce}. In this example, ++both values are symbols preceded by a quote. The values could just as ++well have been another list or a string. The body of the @code{let} ++follows after the list holding the variables. In this example, the ++body is a list that uses the @code{message} function to print a string ++in the echo area. ++ ++@need 1500 ++You may evaluate the example in the usual fashion, by placing the ++cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do ++this, the following will appear in the echo area: ++ ++@smallexample ++"One kind of animal has stripes and another is fierce." ++@end smallexample ++ ++As we have seen before, the @code{message} function prints its first ++argument, except for @samp{%s}. In this example, the value of the variable ++@code{zebra} is printed at the location of the first @samp{%s} and the ++value of the variable @code{tiger} is printed at the location of the ++second @samp{%s}. ++ ++@node Uninitialized let Variables, , Sample let Expression, let ++@comment node-name, next, previous, up ++@subsection Uninitialized Variables in a @code{let} Statement ++@cindex Uninitialized @code{let} variables ++@cindex @code{let} variables uninitialized ++ ++If you do not bind the variables in a @code{let} statement to specific ++initial values, they will automatically be bound to an initial value of ++@code{nil}, as in the following expression: ++ ++@smallexample ++@group ++(let ((birch 3) ++ pine ++ fir ++ (oak 'some)) ++ (message ++ "Here are %d variables with %s, %s, and %s value." ++ birch pine fir oak)) ++@end group ++@end smallexample ++ ++@noindent ++Here, the varlist is @code{((birch 3) pine fir (oak 'some))}. ++ ++@need 1250 ++If you evaluate this expression in the usual way, the following will ++appear in your echo area: ++ ++@smallexample ++"Here are 3 variables with nil, nil, and some value." ++@end smallexample ++ ++@noindent ++In this example, Emacs binds the symbol @code{birch} to the number 3, ++binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds ++the symbol @code{oak} to the value @code{some}. ++ ++Note that in the first part of the @code{let}, the variables @code{pine} ++and @code{fir} stand alone as atoms that are not surrounded by ++parentheses; this is because they are being bound to @code{nil}, the ++empty list. But @code{oak} is bound to @code{some} and so is a part of ++the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the ++number 3 and so is in a list with that number. (Since a number ++evaluates to itself, the number does not need to be quoted. Also, the ++number is printed in the message using a @samp{%d} rather than a ++@samp{%s}.) The four variables as a group are put into a list to ++delimit them from the body of the @code{let}. ++ ++@node if, else, let, Writing Defuns ++@comment node-name, next, previous, up ++@section The @code{if} Special Form ++@findex if ++@cindex Conditional with @code{if} ++ ++A third special form, in addition to @code{defun} and @code{let}, is the ++conditional @code{if}. This form is used to instruct the computer to ++make decisions. You can write function definitions without using ++@code{if}, but it is used often enough, and is important enough, to be ++included here. It is used, for example, in the code for the ++function @code{beginning-of-buffer}. ++ ++The basic idea behind an @code{if}, is that ``@emph{if} a test is true, ++@emph{then} an expression is evaluated.'' If the test is not true, the ++expression is not evaluated. For example, you might make a decision ++such as, ``if it is warm and sunny, then go to the beach!'' ++ ++@menu ++* if in more detail:: ++* type-of-animal in detail:: An example of an @code{if} expression. ++@end menu ++ ++@node if in more detail, type-of-animal in detail, if, if ++@ifnottex ++@unnumberedsubsec @code{if} in more detail ++@end ifnottex ++ ++@cindex @samp{if-part} defined ++@cindex @samp{then-part} defined ++An @code{if} expression written in Lisp does not use the word `then'; ++the test and the action are the second and third elements of the list ++whose first element is @code{if}. Nonetheless, the test part of an ++@code{if} expression is often called the @dfn{if-part} and the second ++argument is often called the @dfn{then-part}. ++ ++Also, when an @code{if} expression is written, the true-or-false-test ++is usually written on the same line as the symbol @code{if}, but the ++action to carry out if the test is true, the ``then-part'', is written ++on the second and subsequent lines. This makes the @code{if} ++expression easier to read. ++ ++@smallexample ++@group ++(if @var{true-or-false-test} ++ @var{action-to-carry-out-if-test-is-true}) ++@end group ++@end smallexample ++ ++@noindent ++The true-or-false-test will be an expression that ++is evaluated by the Lisp interpreter. ++ ++Here is an example that you can evaluate in the usual manner. The test ++is whether the number 5 is greater than the number 4. Since it is, the ++message @samp{5 is greater than 4!} will be printed. ++ ++@smallexample ++@group ++(if (> 5 4) ; @r{if-part} ++ (message "5 is greater than 4!")) ; @r{then-part} ++@end group ++@end smallexample ++ ++@noindent ++(The function @code{>} tests whether its first argument is greater than ++its second argument and returns true if it is.) ++@findex > (greater than) ++ ++Of course, in actual use, the test in an @code{if} expression will not ++be fixed for all time as it is by the expression @code{(> 5 4)}. ++Instead, at least one of the variables used in the test will be bound to ++a value that is not known ahead of time. (If the value were known ahead ++of time, we would not need to run the test!) ++ ++For example, the value may be bound to an argument of a function ++definition. In the following function definition, the character of the ++animal is a value that is passed to the function. If the value bound to ++@code{characteristic} is @code{fierce}, then the message, @samp{It's a ++tiger!} will be printed; otherwise, @code{nil} will be returned. ++ ++@smallexample ++@group ++(defun type-of-animal (characteristic) ++ "Print message in echo area depending on CHARACTERISTIC. ++If the CHARACTERISTIC is the symbol `fierce', ++then warn of a tiger." ++ (if (equal characteristic 'fierce) ++ (message "It's a tiger!"))) ++@end group ++@end smallexample ++ ++@need 1500 ++@noindent ++If you are reading this inside of GNU Emacs, you can evaluate the ++function definition in the usual way to install it in Emacs, and then you ++can evaluate the following two expressions to see the results: ++ ++@smallexample ++@group ++(type-of-animal 'fierce) ++ ++(type-of-animal 'zebra) ++ ++@end group ++@end smallexample ++ ++@c Following sentences rewritten to prevent overfull hbox. ++@noindent ++When you evaluate @code{(type-of-animal 'fierce)}, you will see the ++following message printed in the echo area: @code{"It's a tiger!"}; and ++when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil} ++printed in the echo area. ++ ++@node type-of-animal in detail, , if in more detail, if ++@comment node-name, next, previous, up ++@subsection The @code{type-of-animal} Function in Detail ++ ++Let's look at the @code{type-of-animal} function in detail. ++ ++The function definition for @code{type-of-animal} was written by filling ++the slots of two templates, one for a function definition as a whole, and ++a second for an @code{if} expression. ++ ++@need 1250 ++The template for every function that is not interactive is: ++ ++@smallexample ++@group ++(defun @var{name-of-function} (@var{argument-list}) ++ "@var{documentation}@dots{}" ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++@need 800 ++The parts of the function that match this template look like this: ++ ++@smallexample ++@group ++(defun type-of-animal (characteristic) ++ "Print message in echo area depending on CHARACTERISTIC. ++If the CHARACTERISTIC is the symbol `fierce', ++then warn of a tiger." ++ @var{body: the} @code{if} @var{expression}) ++@end group ++@end smallexample ++ ++The name of function is @code{type-of-animal}; it is passed the value ++of one argument. The argument list is followed by a multi-line ++documentation string. The documentation string is included in the ++example because it is a good habit to write documentation string for ++every function definition. The body of the function definition ++consists of the @code{if} expression. ++ ++@need 800 ++The template for an @code{if} expression looks like this: ++ ++@smallexample ++@group ++(if @var{true-or-false-test} ++ @var{action-to-carry-out-if-the-test-returns-true}) ++@end group ++@end smallexample ++ ++@need 1250 ++In the @code{type-of-animal} function, the code for the @code{if} ++looks like this: ++ ++@smallexample ++@group ++(if (equal characteristic 'fierce) ++ (message "It's a tiger!"))) ++@end group ++@end smallexample ++ ++@need 800 ++Here, the true-or-false-test is the expression: ++ ++@smallexample ++(equal characteristic 'fierce) ++@end smallexample ++ ++@noindent ++In Lisp, @code{equal} is a function that determines whether its first ++argument is equal to its second argument. The second argument is the ++quoted symbol @code{'fierce} and the first argument is the value of the ++symbol @code{characteristic}---in other words, the argument passed to ++this function. ++ ++In the first exercise of @code{type-of-animal}, the argument ++@code{fierce} is passed to @code{type-of-animal}. Since @code{fierce} ++is equal to @code{fierce}, the expression, @code{(equal characteristic ++'fierce)}, returns a value of true. When this happens, the @code{if} ++evaluates the second argument or then-part of the @code{if}: ++@code{(message "It's tiger!")}. ++ ++On the other hand, in the second exercise of @code{type-of-animal}, the ++argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra} ++is not equal to @code{fierce}, so the then-part is not evaluated and ++@code{nil} is returned by the @code{if} expression. ++ ++@node else, Truth & Falsehood, if, Writing Defuns ++@comment node-name, next, previous, up ++@section If--then--else Expressions ++@cindex Else ++ ++An @code{if} expression may have an optional third argument, called ++the @dfn{else-part}, for the case when the true-or-false-test returns ++false. When this happens, the second argument or then-part of the ++overall @code{if} expression is @emph{not} evaluated, but the third or ++else-part @emph{is} evaluated. You might think of this as the cloudy ++day alternative for the decision ``if it is warm and sunny, then go to ++the beach, else read a book!''. ++ ++The word ``else'' is not written in the Lisp code; the else-part of an ++@code{if} expression comes after the then-part. In the written Lisp, the ++else-part is usually written to start on a line of its own and is ++indented less than the then-part: ++ ++@smallexample ++@group ++(if @var{true-or-false-test} ++ @var{action-to-carry-out-if-the-test-returns-true} ++ @var{action-to-carry-out-if-the-test-returns-false}) ++@end group ++@end smallexample ++ ++For example, the following @code{if} expression prints the message @samp{4 ++is not greater than 5!} when you evaluate it in the usual way: ++ ++@smallexample ++@group ++(if (> 4 5) ; @r{if-part} ++ (message "4 falsely greater than 5!") ; @r{then-part} ++ (message "4 is not greater than 5!")) ; @r{else-part} ++@end group ++@end smallexample ++ ++@noindent ++Note that the different levels of indentation make it easy to ++distinguish the then-part from the else-part. (GNU Emacs has several ++commands that automatically indent @code{if} expressions correctly. ++@xref{Typing Lists, , GNU Emacs Helps You Type Lists}.) ++ ++We can extend the @code{type-of-animal} function to include an ++else-part by simply incorporating an additional part to the @code{if} ++expression. ++ ++@need 1500 ++You can see the consequences of doing this if you evaluate the following ++version of the @code{type-of-animal} function definition to install it ++and then evaluate the two subsequent expressions to pass different ++arguments to the function. ++ ++@smallexample ++@group ++(defun type-of-animal (characteristic) ; @r{Second version.} ++ "Print message in echo area depending on CHARACTERISTIC. ++If the CHARACTERISTIC is the symbol `fierce', ++then warn of a tiger; ++else say it's not fierce." ++ (if (equal characteristic 'fierce) ++ (message "It's a tiger!") ++ (message "It's not fierce!"))) ++@end group ++@end smallexample ++@sp 1 ++ ++@smallexample ++@group ++(type-of-animal 'fierce) ++ ++(type-of-animal 'zebra) ++ ++@end group ++@end smallexample ++ ++@c Following sentence rewritten to prevent overfull hbox. ++@noindent ++When you evaluate @code{(type-of-animal 'fierce)}, you will see the ++following message printed in the echo area: @code{"It's a tiger!"}; but ++when you evaluate @code{(type-of-animal 'zebra)}, you will see ++@code{"It's not fierce!"}. ++ ++(Of course, if the @var{characteristic} were @code{ferocious}, the ++message @code{"It's not fierce!"} would be printed; and it would be ++misleading! When you write code, you need to take into account the ++possibility that some such argument will be tested by the @code{if} ++and write your program accordingly.) ++ ++@node Truth & Falsehood, save-excursion, else, Writing Defuns ++@comment node-name, next, previous, up ++@section Truth and Falsehood in Emacs Lisp ++@cindex Truth and falsehood in Emacs Lisp ++@cindex Falsehood and truth in Emacs Lisp ++@findex nil ++ ++There is an important aspect to the truth test in an @code{if} ++expression. So far, we have spoken of `true' and `false' as values of ++predicates as if they were new kinds of Emacs Lisp objects. In fact, ++`false' is just our old friend @code{nil}. Anything else---anything ++at all---is `true'. ++ ++The expression that tests for truth is interpreted as @dfn{true} ++if the result of evaluating it is a value that is not @code{nil}. In ++other words, the result of the test is considered true if the value ++returned is a number such as 47, a string such as @code{"hello"}, or a ++symbol (other than @code{nil}) such as @code{flowers}, or a list (so ++long as it is not empty), or even a buffer! ++ ++@menu ++* nil explained:: @code{nil} has two meanings. ++@end menu ++ ++@node nil explained, , Truth & Falsehood, Truth & Falsehood ++@ifnottex ++@unnumberedsubsec An explanation of @code{nil} ++@end ifnottex ++ ++Before illustrating a test for truth, we need an explanation of @code{nil}. ++ ++In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the ++empty list. Second, it means false and is the value returned when a ++true-or-false-test tests false. @code{nil} can be written as an empty ++list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is ++concerned, @code{()} and @code{nil} are the same. Humans, however, tend ++to use @code{nil} for false and @code{()} for the empty list. ++ ++In Emacs Lisp, any value that is not @code{nil}---is not the empty ++list---is considered true. This means that if an evaluation returns ++something that is not an empty list, an @code{if} expression will test ++true. For example, if a number is put in the slot for the test, it ++will be evaluated and will return itself, since that is what numbers ++do when evaluated. In this conditional, the @code{if} expression will ++test true. The expression tests false only when @code{nil}, an empty ++list, is returned by evaluating the expression. ++ ++You can see this by evaluating the two expressions in the following examples. ++ ++In the first example, the number 4 is evaluated as the test in the ++@code{if} expression and returns itself; consequently, the then-part ++of the expression is evaluated and returned: @samp{true} appears in ++the echo area. In the second example, the @code{nil} indicates false; ++consequently, the else-part of the expression is evaluated and ++returned: @samp{false} appears in the echo area. ++ ++@smallexample ++@group ++(if 4 ++ 'true ++ 'false) ++@end group ++ ++@group ++(if nil ++ 'true ++ 'false) ++@end group ++@end smallexample ++ ++@need 1250 ++Incidentally, if some other useful value is not available for a test that ++returns true, then the Lisp interpreter will return the symbol @code{t} ++for true. For example, the expression @code{(> 5 4)} returns @code{t} ++when evaluated, as you can see by evaluating it in the usual way: ++ ++@smallexample ++(> 5 4) ++@end smallexample ++ ++@need 1250 ++@noindent ++On the other hand, this function returns @code{nil} if the test is false. ++ ++@smallexample ++(> 4 5) ++@end smallexample ++ ++@node save-excursion, Review, Truth & Falsehood, Writing Defuns ++@comment node-name, next, previous, up ++@section @code{save-excursion} ++@findex save-excursion ++@cindex Region, what it is ++@cindex Preserving point, mark, and buffer ++@cindex Point, mark, buffer preservation ++@findex point ++@findex mark ++ ++The @code{save-excursion} function is the fourth and final special form ++that we will discuss in this chapter. ++ ++In Emacs Lisp programs used for editing, the @code{save-excursion} ++function is very common. It saves the location of point and mark, ++executes the body of the function, and then restores point and mark to ++their previous positions if their locations were changed. Its primary ++purpose is to keep the user from being surprised and disturbed by ++unexpected movement of point or mark. ++ ++@menu ++* Point and mark:: A review of various locations. ++* Template for save-excursion:: ++@end menu ++ ++@node Point and mark, Template for save-excursion, save-excursion, save-excursion ++@ifnottex ++@unnumberedsubsec Point and Mark ++@end ifnottex ++ ++Before discussing @code{save-excursion}, however, it may be useful ++first to review what point and mark are in GNU Emacs. @dfn{Point} is ++the current location of the cursor. Wherever the cursor ++is, that is point. More precisely, on terminals where the cursor ++appears to be on top of a character, point is immediately before the ++character. In Emacs Lisp, point is an integer. The first character in ++a buffer is number one, the second is number two, and so on. The ++function @code{point} returns the current position of the cursor as a ++number. Each buffer has its own value for point. ++ ++The @dfn{mark} is another position in the buffer; its value can be set ++with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If ++a mark has been set, you can use the command @kbd{C-x C-x} ++(@code{exchange-point-and-mark}) to cause the cursor to jump to the mark ++and set the mark to be the previous position of point. In addition, if ++you set another mark, the position of the previous mark is saved in the ++mark ring. Many mark positions can be saved this way. You can jump the ++cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more ++times. ++ ++The part of the buffer between point and mark is called @dfn{the ++region}. Numerous commands work on the region, including ++@code{center-region}, @code{count-lines-region}, @code{kill-region}, and ++@code{print-region}. ++ ++The @code{save-excursion} special form saves the locations of point and ++mark and restores those positions after the code within the body of the ++special form is evaluated by the Lisp interpreter. Thus, if point were ++in the beginning of a piece of text and some code moved point to the end ++of the buffer, the @code{save-excursion} would put point back to where ++it was before, after the expressions in the body of the function were ++evaluated. ++ ++In Emacs, a function frequently moves point as part of its internal ++workings even though a user would not expect this. For example, ++@code{count-lines-region} moves point. To prevent the user from being ++bothered by jumps that are both unexpected and (from the user's point of ++view) unnecessary, @code{save-excursion} is often used to keep point and ++mark in the location expected by the user. The use of ++@code{save-excursion} is good housekeeping. ++ ++To make sure the house stays clean, @code{save-excursion} restores the ++values of point and mark even if something goes wrong in the code inside ++of it (or, to be more precise and to use the proper jargon, ``in case of ++abnormal exit''). This feature is very helpful. ++ ++In addition to recording the values of point and mark, ++@code{save-excursion} keeps track of the current buffer, and restores ++it, too. This means you can write code that will change the buffer and ++have @code{save-excursion} switch you back to the original buffer. ++This is how @code{save-excursion} is used in @code{append-to-buffer}. ++(@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) ++ ++@node Template for save-excursion, , Point and mark, save-excursion ++@comment node-name, next, previous, up ++@subsection Template for a @code{save-excursion} Expression ++ ++@need 800 ++The template for code using @code{save-excursion} is simple: ++ ++@smallexample ++@group ++(save-excursion ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++@noindent ++The body of the function is one or more expressions that will be ++evaluated in sequence by the Lisp interpreter. If there is more than ++one expression in the body, the value of the last one will be returned ++as the value of the @code{save-excursion} function. The other ++expressions in the body are evaluated only for their side effects; and ++@code{save-excursion} itself is used only for its side effect (which ++is restoring the positions of point and mark). ++ ++@need 1250 ++In more detail, the template for a @code{save-excursion} expression ++looks like this: ++ ++@smallexample ++@group ++(save-excursion ++ @var{first-expression-in-body} ++ @var{second-expression-in-body} ++ @var{third-expression-in-body} ++ @dots{} ++ @var{last-expression-in-body}) ++@end group ++@end smallexample ++ ++@noindent ++An expression, of course, may be a symbol on its own or a list. ++ ++In Emacs Lisp code, a @code{save-excursion} expression often occurs ++within the body of a @code{let} expression. It looks like this: ++ ++@smallexample ++@group ++(let @var{varlist} ++ (save-excursion ++ @var{body}@dots{})) ++@end group ++@end smallexample ++ ++@node Review, defun Exercises, save-excursion, Writing Defuns ++@comment node-name, next, previous, up ++@section Review ++ ++In the last few chapters we have introduced a fair number of functions ++and special forms. Here they are described in brief, along with a few ++similar functions that have not been mentioned yet. ++ ++@table @code ++@item eval-last-sexp ++Evaluate the last symbolic expression before the current location of ++point. The value is printed in the echo area unless the function is ++invoked with an argument; in that case, the output is printed in the ++current buffer. This command is normally bound to @kbd{C-x C-e}. ++ ++@item defun ++Define function. This special form has up to five parts: the name, ++a template for the arguments that will be passed to the function, ++documentation, an optional interactive declaration, and the body of the ++definition. ++ ++@need 1250 ++For example, in an early version of Emacs, the function definition was ++as follows. (It is slightly more complex now that it seeks the first ++non-whitespace character rather than the first visible character.) ++ ++@smallexample ++@group ++(defun back-to-indentation () ++ "Move point to first visible character on line." ++ (interactive) ++ (beginning-of-line 1) ++ (skip-chars-forward " \t")) ++@end group ++@end smallexample ++ ++@ignore ++In GNU Emacs 22, ++ ++(defun backward-to-indentation (&optional arg) ++ "Move backward ARG lines and position at first nonblank character." ++ (interactive "p") ++ (forward-line (- (or arg 1))) ++ (skip-chars-forward " \t")) ++ ++(defun back-to-indentation () ++ "Move point to the first non-whitespace character on this line." ++ (interactive) ++ (beginning-of-line 1) ++ (skip-syntax-forward " " (line-end-position)) ++ ;; Move back over chars that have whitespace syntax but have the p flag. ++ (backward-prefix-chars)) ++@end ignore ++ ++@item interactive ++Declare to the interpreter that the function can be used ++interactively. This special form may be followed by a string with one ++or more parts that pass the information to the arguments of the ++function, in sequence. These parts may also tell the interpreter to ++prompt for information. Parts of the string are separated by ++newlines, @samp{\n}. ++ ++@need 1000 ++Common code characters are: ++ ++@table @code ++@item b ++The name of an existing buffer. ++ ++@item f ++The name of an existing file. ++ ++@item p ++The numeric prefix argument. (Note that this `p' is lower case.) ++ ++@item r ++Point and the mark, as two numeric arguments, smallest first. This ++is the only code letter that specifies two successive arguments ++rather than one. ++@end table ++ ++@xref{Interactive Codes, , Code Characters for @samp{interactive}, ++elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of ++code characters. ++ ++@item let ++Declare that a list of variables is for use within the body of the ++@code{let} and give them an initial value, either @code{nil} or a ++specified value; then evaluate the rest of the expressions in the body ++of the @code{let} and return the value of the last one. Inside the ++body of the @code{let}, the Lisp interpreter does not see the values of ++the variables of the same names that are bound outside of the ++@code{let}. ++ ++@need 1250 ++For example, ++ ++@smallexample ++@group ++(let ((foo (buffer-name)) ++ (bar (buffer-size))) ++ (message ++ "This buffer is %s and has %d characters." ++ foo bar)) ++@end group ++@end smallexample ++ ++@item save-excursion ++Record the values of point and mark and the current buffer before ++evaluating the body of this special form. Restore the values of point ++and mark and buffer afterward. ++ ++@need 1250 ++For example, ++ ++@smallexample ++@group ++(message "We are %d characters into this buffer." ++ (- (point) ++ (save-excursion ++ (goto-char (point-min)) (point)))) ++@end group ++@end smallexample ++ ++@item if ++Evaluate the first argument to the function; if it is true, evaluate ++the second argument; else evaluate the third argument, if there is one. ++ ++The @code{if} special form is called a @dfn{conditional}. There are ++other conditionals in Emacs Lisp, but @code{if} is perhaps the most ++commonly used. ++ ++@need 1250 ++For example, ++ ++@smallexample ++@group ++(if (= 22 emacs-major-version) ++ (message "This is version 22 Emacs") ++ (message "This is not version 22 Emacs")) ++@end group ++@end smallexample ++ ++@need 1250 ++@item < ++@itemx > ++@itemx <= ++@itemx >= ++The @code{<} function tests whether its first argument is smaller than ++its second argument. A corresponding function, @code{>}, tests whether ++the first argument is greater than the second. Likewise, @code{<=} ++tests whether the first argument is less than or equal to the second and ++@code{>=} tests whether the first argument is greater than or equal to ++the second. In all cases, both arguments must be numbers or markers ++(markers indicate positions in buffers). ++ ++@need 800 ++@item = ++The @code{=} function tests whether two arguments, both numbers or ++markers, are equal. ++ ++@need 1250 ++@item equal ++@itemx eq ++Test whether two objects are the same. @code{equal} uses one meaning ++of the word `same' and @code{eq} uses another: @code{equal} returns ++true if the two objects have a similar structure and contents, such as ++two copies of the same book. On the other hand, @code{eq}, returns ++true if both arguments are actually the same object. ++@findex equal ++@findex eq ++ ++@need 1250 ++@item string< ++@itemx string-lessp ++@itemx string= ++@itemx string-equal ++The @code{string-lessp} function tests whether its first argument is ++smaller than the second argument. A shorter, alternative name for the ++same function (a @code{defalias}) is @code{string<}. ++ ++The arguments to @code{string-lessp} must be strings or symbols; the ++ordering is lexicographic, so case is significant. The print names of ++symbols are used instead of the symbols themselves. ++ ++@cindex @samp{empty string} defined ++An empty string, @samp{""}, a string with no characters in it, is ++smaller than any string of characters. ++ ++@code{string-equal} provides the corresponding test for equality. Its ++shorter, alternative name is @code{string=}. There are no string test ++functions that correspond to @var{>}, @code{>=}, or @code{<=}. ++ ++@item message ++Print a message in the echo area. The first argument is a string that ++can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of ++arguments that follow the string. The argument used by @samp{%s} must ++be a string or a symbol; the argument used by @samp{%d} must be a ++number. The argument used by @samp{%c} must be an @sc{ascii} code ++number; it will be printed as the character with that @sc{ascii} code. ++(Various other %-sequences have not been mentioned.) ++ ++@item setq ++@itemx set ++The @code{setq} function sets the value of its first argument to the ++value of the second argument. The first argument is automatically ++quoted by @code{setq}. It does the same for succeeding pairs of ++arguments. Another function, @code{set}, takes only two arguments and ++evaluates both of them before setting the value returned by its first ++argument to the value returned by its second argument. ++ ++@item buffer-name ++Without an argument, return the name of the buffer, as a string. ++ ++@itemx buffer-file-name ++Without an argument, return the name of the file the buffer is ++visiting. ++ ++@item current-buffer ++Return the buffer in which Emacs is active; it may not be ++the buffer that is visible on the screen. ++ ++@item other-buffer ++Return the most recently selected buffer (other than the buffer passed ++to @code{other-buffer} as an argument and other than the current ++buffer). ++ ++@item switch-to-buffer ++Select a buffer for Emacs to be active in and display it in the current ++window so users can look at it. Usually bound to @kbd{C-x b}. ++ ++@item set-buffer ++Switch Emacs' attention to a buffer on which programs will run. Don't ++alter what the window is showing. ++ ++@item buffer-size ++Return the number of characters in the current buffer. ++ ++@item point ++Return the value of the current position of the cursor, as an ++integer counting the number of characters from the beginning of the ++buffer. ++ ++@item point-min ++Return the minimum permissible value of point in ++the current buffer. This is 1, unless narrowing is in effect. ++ ++@item point-max ++Return the value of the maximum permissible value of point in the ++current buffer. This is the end of the buffer, unless narrowing is in ++effect. ++@end table ++ ++@need 1500 ++@node defun Exercises, , Review, Writing Defuns ++@section Exercises ++ ++@itemize @bullet ++@item ++Write a non-interactive function that doubles the value of its ++argument, a number. Make that function interactive. ++ ++@item ++Write a function that tests whether the current value of ++@code{fill-column} is greater than the argument passed to the function, ++and if so, prints an appropriate message. ++@end itemize ++ ++@node Buffer Walk Through, More Complex, Writing Defuns, Top ++@comment node-name, next, previous, up ++@chapter A Few Buffer--Related Functions ++ ++In this chapter we study in detail several of the functions used in GNU ++Emacs. This is called a ``walk-through''. These functions are used as ++examples of Lisp code, but are not imaginary examples; with the ++exception of the first, simplified function definition, these functions ++show the actual code used in GNU Emacs. You can learn a great deal from ++these definitions. The functions described here are all related to ++buffers. Later, we will study other functions. ++ ++@menu ++* Finding More:: How to find more information. ++* simplified-beginning-of-buffer:: Shows @code{goto-char}, ++ @code{point-min}, and @code{push-mark}. ++* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. ++* append-to-buffer:: Uses @code{save-excursion} and ++ @code{insert-buffer-substring}. ++* Buffer Related Review:: Review. ++* Buffer Exercises:: ++@end menu ++ ++@node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through ++@section Finding More Information ++ ++@findex describe-function, @r{introduced} ++@cindex Find function documentation ++In this walk-through, I will describe each new function as we come to ++it, sometimes in detail and sometimes briefly. If you are interested, ++you can get the full documentation of any Emacs Lisp function at any ++time by typing @kbd{C-h f} and then the name of the function (and then ++@key{RET}). Similarly, you can get the full documentation for a ++variable by typing @kbd{C-h v} and then the name of the variable (and ++then @key{RET}). ++ ++@cindex Find source of function ++@c In version 22, tells location both of C and of Emacs Lisp ++Also, @code{describe-function} will tell you the location of the ++function definition. ++ ++Put point into the name of the file that contains the function and ++press the @key{RET} key. In this case, @key{RET} means ++@code{push-button} rather than `return' or `enter'. Emacs will take ++you directly to the function definition. ++ ++@ignore ++Not In version 22 ++ ++If you move point over the file name and press ++the @key{RET} key, which in this case means @code{help-follow} rather ++than `return' or `enter', Emacs will take you directly to the function ++definition. ++@end ignore ++ ++More generally, if you want to see a function in its original source ++file, you can use the @code{find-tags} function to jump to it. ++@code{find-tags} works with a wide variety of languages, not just ++Lisp, and C, and it works with non-programming text as well. For ++example, @code{find-tags} will jump to the various nodes in the ++Texinfo source file of this document. ++The @code{find-tags} function depends on `tags tables' that record ++the locations of the functions, variables, and other items to which ++@code{find-tags} jumps. ++ ++To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the ++period key while holding down the @key{META} key, or else type the ++@key{ESC} key and then type the period key), and then, at the prompt, ++type in the name of the function whose source code you want to see, ++such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will ++switch buffers and display the source code for the function on your ++screen. To switch back to your current buffer, type @kbd{C-x b ++@key{RET}}. (On some keyboards, the @key{META} key is labelled ++@key{ALT}.) ++ ++@c !!! 22.1.1 tags table location in this paragraph ++@cindex TAGS table, specifying ++@findex find-tags ++Depending on how the initial default values of your copy of Emacs are ++set, you may also need to specify the location of your `tags table', ++which is a file called @file{TAGS}. For example, if you are ++interested in Emacs sources, the tags table you will most likely want, ++if it has already been created for you, will be in a subdirectory of ++the @file{/usr/local/share/emacs/} directory; thus you would use the ++@code{M-x visit-tags-table} command and specify a pathname such as ++@file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table ++has not already been created, you will have to create it yourself. It ++will in a file such as @file{/usr/local/src/emacs/src/TAGS}. ++ ++@need 1250 ++To create a @file{TAGS} file in a specific directory, switch to that ++directory in Emacs using @kbd{M-x cd} command, or list the directory ++with @kbd{C-x d} (@code{dired}). Then run the compile command, with ++@w{@code{etags *.el}} as the command to execute: ++ ++@smallexample ++M-x compile RET etags *.el RET ++@end smallexample ++ ++For more information, see @ref{etags, , Create Your Own @file{TAGS} File}. ++ ++After you become more familiar with Emacs Lisp, you will find that you will ++frequently use @code{find-tags} to navigate your way around source code; ++and you will create your own @file{TAGS} tables. ++ ++@cindex Library, as term for `file' ++Incidentally, the files that contain Lisp code are conventionally ++called @dfn{libraries}. The metaphor is derived from that of a ++specialized library, such as a law library or an engineering library, ++rather than a general library. Each library, or file, contains ++functions that relate to a particular topic or activity, such as ++@file{abbrev.el} for handling abbreviations and other typing ++shortcuts, and @file{help.el} for on-line help. (Sometimes several ++libraries provide code for a single activity, as the various ++@file{rmail@dots{}} files provide code for reading electronic mail.) ++In @cite{The GNU Emacs Manual}, you will see sentences such as ``The ++@kbd{C-h p} command lets you search the standard Emacs Lisp libraries ++by topic keywords.'' ++ ++@node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through ++@comment node-name, next, previous, up ++@section A Simplified @code{beginning-of-buffer} Definition ++@findex simplified-beginning-of-buffer ++ ++The @code{beginning-of-buffer} command is a good function to start with ++since you are likely to be familiar with it and it is easy to ++understand. Used as an interactive command, @code{beginning-of-buffer} ++moves the cursor to the beginning of the buffer, leaving the mark at the ++previous position. It is generally bound to @kbd{M-<}. ++ ++In this section, we will discuss a shortened version of the function ++that shows how it is most frequently used. This shortened function ++works as written, but it does not contain the code for a complex option. ++In another section, we will describe the entire function. ++(@xref{beginning-of-buffer, , Complete Definition of ++@code{beginning-of-buffer}}.) ++ ++Before looking at the code, let's consider what the function ++definition has to contain: it must include an expression that makes ++the function interactive so it can be called by typing @kbd{M-x ++beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it ++must include code to leave a mark at the original position in the ++buffer; and it must include code to move the cursor to the beginning ++of the buffer. ++ ++@need 1250 ++Here is the complete text of the shortened version of the function: ++ ++@smallexample ++@group ++(defun simplified-beginning-of-buffer () ++ "Move point to the beginning of the buffer; ++leave mark at previous position." ++ (interactive) ++ (push-mark) ++ (goto-char (point-min))) ++@end group ++@end smallexample ++ ++Like all function definitions, this definition has five parts following ++the special form @code{defun}: ++ ++@enumerate ++@item ++The name: in this example, @code{simplified-beginning-of-buffer}. ++ ++@item ++A list of the arguments: in this example, an empty list, @code{()}, ++ ++@item ++The documentation string. ++ ++@item ++The interactive expression. ++ ++@item ++The body. ++@end enumerate ++ ++@noindent ++In this function definition, the argument list is empty; this means that ++this function does not require any arguments. (When we look at the ++definition for the complete function, we will see that it may be passed ++an optional argument.) ++ ++The interactive expression tells Emacs that the function is intended to ++be used interactively. In this example, @code{interactive} does not have ++an argument because @code{simplified-beginning-of-buffer} does not ++require one. ++ ++@need 800 ++The body of the function consists of the two lines: ++ ++@smallexample ++@group ++(push-mark) ++(goto-char (point-min)) ++@end group ++@end smallexample ++ ++The first of these lines is the expression, @code{(push-mark)}. When ++this expression is evaluated by the Lisp interpreter, it sets a mark at ++the current position of the cursor, wherever that may be. The position ++of this mark is saved in the mark ring. ++ ++The next line is @code{(goto-char (point-min))}. This expression ++jumps the cursor to the minimum point in the buffer, that is, to the ++beginning of the buffer (or to the beginning of the accessible portion ++of the buffer if it is narrowed. @xref{Narrowing & Widening, , ++Narrowing and Widening}.) ++ ++The @code{push-mark} command sets a mark at the place where the cursor ++was located before it was moved to the beginning of the buffer by the ++@code{(goto-char (point-min))} expression. Consequently, you can, if ++you wish, go back to where you were originally by typing @kbd{C-x C-x}. ++ ++That is all there is to the function definition! ++ ++@findex describe-function ++When you are reading code such as this and come upon an unfamiliar ++function, such as @code{goto-char}, you can find out what it does by ++using the @code{describe-function} command. To use this command, type ++@kbd{C-h f} and then type in the name of the function and press ++@key{RET}. The @code{describe-function} command will print the ++function's documentation string in a @file{*Help*} window. For ++example, the documentation for @code{goto-char} is: ++ ++@smallexample ++@group ++Set point to POSITION, a number or marker. ++Beginning of buffer is position (point-min), end is (point-max). ++@end group ++@end smallexample ++ ++@noindent ++The function's one argument is the desired position. ++ ++@noindent ++(The prompt for @code{describe-function} will offer you the symbol ++under or preceding the cursor, so you can save typing by positioning ++the cursor right over or after the function and then typing @kbd{C-h f ++@key{RET}}.) ++ ++The @code{end-of-buffer} function definition is written in the same way as ++the @code{beginning-of-buffer} definition except that the body of the ++function contains the expression @code{(goto-char (point-max))} in place ++of @code{(goto-char (point-min))}. ++ ++@node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through ++@comment node-name, next, previous, up ++@section The Definition of @code{mark-whole-buffer} ++@findex mark-whole-buffer ++ ++The @code{mark-whole-buffer} function is no harder to understand than the ++@code{simplified-beginning-of-buffer} function. In this case, however, ++we will look at the complete function, not a shortened version. ++ ++The @code{mark-whole-buffer} function is not as commonly used as the ++@code{beginning-of-buffer} function, but is useful nonetheless: it ++marks a whole buffer as a region by putting point at the beginning and ++a mark at the end of the buffer. It is generally bound to @kbd{C-x ++h}. ++ ++@menu ++* mark-whole-buffer overview:: ++* Body of mark-whole-buffer:: Only three lines of code. ++@end menu ++ ++@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer ++@ifnottex ++@unnumberedsubsec An overview of @code{mark-whole-buffer} ++@end ifnottex ++ ++@need 1250 ++In GNU Emacs 22, the code for the complete function looks like this: ++ ++@smallexample ++@group ++(defun mark-whole-buffer () ++ "Put point at beginning and mark at end of buffer. ++You probably should not use this function in Lisp programs; ++it is usually a mistake for a Lisp function to use any subroutine ++that uses or sets the mark." ++ (interactive) ++ (push-mark (point)) ++ (push-mark (point-max) nil t) ++ (goto-char (point-min))) ++@end group ++@end smallexample ++ ++@need 1250 ++Like all other functions, the @code{mark-whole-buffer} function fits ++into the template for a function definition. The template looks like ++this: ++ ++@smallexample ++@group ++(defun @var{name-of-function} (@var{argument-list}) ++ "@var{documentation}@dots{}" ++ (@var{interactive-expression}@dots{}) ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++Here is how the function works: the name of the function is ++@code{mark-whole-buffer}; it is followed by an empty argument list, ++@samp{()}, which means that the function does not require arguments. ++The documentation comes next. ++ ++The next line is an @code{(interactive)} expression that tells Emacs ++that the function will be used interactively. These details are similar ++to the @code{simplified-beginning-of-buffer} function described in the ++previous section. ++ ++@need 1250 ++@node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer ++@comment node-name, next, previous, up ++@subsection Body of @code{mark-whole-buffer} ++ ++The body of the @code{mark-whole-buffer} function consists of three ++lines of code: ++ ++@c GNU Emacs 22 ++@smallexample ++@group ++(push-mark (point)) ++(push-mark (point-max) nil t) ++(goto-char (point-min)) ++@end group ++@end smallexample ++ ++The first of these lines is the expression, @code{(push-mark (point))}. ++ ++This line does exactly the same job as the first line of the body of ++the @code{simplified-beginning-of-buffer} function, which is written ++@code{(push-mark)}. In both cases, the Lisp interpreter sets a mark ++at the current position of the cursor. ++ ++I don't know why the expression in @code{mark-whole-buffer} is written ++@code{(push-mark (point))} and the expression in ++@code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps ++whoever wrote the code did not know that the arguments for ++@code{push-mark} are optional and that if @code{push-mark} is not ++passed an argument, the function automatically sets mark at the ++location of point by default. Or perhaps the expression was written ++so as to parallel the structure of the next line. In any case, the ++line causes Emacs to determine the position of point and set a mark ++there. ++ ++In earlier versions of GNU Emacs, the next line of ++@code{mark-whole-buffer} was @code{(push-mark (point-max))}. This ++expression sets a mark at the point in the buffer that has the highest ++number. This will be the end of the buffer (or, if the buffer is ++narrowed, the end of the accessible portion of the buffer. ++@xref{Narrowing & Widening, , Narrowing and Widening}, for more about ++narrowing.) After this mark has been set, the previous mark, the one ++set at point, is no longer set, but Emacs remembers its position, just ++as all other recent marks are always remembered. This means that you ++can, if you wish, go back to that position by typing @kbd{C-u ++C-@key{SPC}} twice. ++ ++@need 1250 ++In GNU Emacs 22, the @code{(point-max)} is slightly more complicated. ++The line reads ++ ++@smallexample ++(push-mark (point-max) nil t) ++@end smallexample ++ ++@noindent ++The expression works nearly the same as before. It sets a mark at the ++highest numbered place in the buffer that it can. However, in this ++version, @code{push-mark} has two additional arguments. The second ++argument to @code{push-mark} is @code{nil}. This tells the function ++it @emph{should} display a message that says `Mark set' when it pushes ++the mark. The third argument is @code{t}. This tells ++@code{push-mark} to activate the mark when Transient Mark mode is ++turned on. Transient Mark mode highlights the currently active ++region. It is often turned off. ++ ++Finally, the last line of the function is @code{(goto-char ++(point-min)))}. This is written exactly the same way as it is written ++in @code{beginning-of-buffer}. The expression moves the cursor to ++the minimum point in the buffer, that is, to the beginning of the buffer ++(or to the beginning of the accessible portion of the buffer). As a ++result of this, point is placed at the beginning of the buffer and mark ++is set at the end of the buffer. The whole buffer is, therefore, the ++region. ++ ++@node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through ++@comment node-name, next, previous, up ++@section The Definition of @code{append-to-buffer} ++@findex append-to-buffer ++ ++The @code{append-to-buffer} command is more complex than the ++@code{mark-whole-buffer} command. What it does is copy the region ++(that is, the part of the buffer between point and mark) from the ++current buffer to a specified buffer. ++ ++@menu ++* append-to-buffer overview:: ++* append interactive:: A two part interactive expression. ++* append-to-buffer body:: Incorporates a @code{let} expression. ++* append save-excursion:: How the @code{save-excursion} works. ++@end menu ++ ++@node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer ++@ifnottex ++@unnumberedsubsec An Overview of @code{append-to-buffer} ++@end ifnottex ++ ++@findex insert-buffer-substring ++The @code{append-to-buffer} command uses the ++@code{insert-buffer-substring} function to copy the region. ++@code{insert-buffer-substring} is described by its name: it takes a ++string of characters from part of a buffer, a ``substring'', and ++inserts them into another buffer. ++ ++Most of @code{append-to-buffer} is ++concerned with setting up the conditions for ++@code{insert-buffer-substring} to work: the code must specify both the ++buffer to which the text will go, the window it comes from and goes ++to, and the region that will be copied. ++ ++@need 1250 ++Here is the complete text of the function: ++ ++@smallexample ++@group ++(defun append-to-buffer (buffer start end) ++ "Append to specified buffer the text of the region. ++It is inserted into that buffer before its point. ++@end group ++ ++@group ++When calling from a program, give three arguments: ++BUFFER (or buffer name), START and END. ++START and END specify the portion of the current buffer to be copied." ++ (interactive ++ (list (read-buffer "Append to buffer: " (other-buffer ++ (current-buffer) t)) ++ (region-beginning) (region-end))) ++@end group ++@group ++ (let ((oldbuf (current-buffer))) ++ (save-excursion ++ (let* ((append-to (get-buffer-create buffer)) ++ (windows (get-buffer-window-list append-to t t)) ++ point) ++ (set-buffer append-to) ++ (setq point (point)) ++ (barf-if-buffer-read-only) ++ (insert-buffer-substring oldbuf start end) ++ (dolist (window windows) ++ (when (= (window-point window) point) ++ (set-window-point window (point)))))))) ++@end group ++@end smallexample ++ ++The function can be understood by looking at it as a series of ++filled-in templates. ++ ++The outermost template is for the function definition. In this ++function, it looks like this (with several slots filled in): ++ ++@smallexample ++@group ++(defun append-to-buffer (buffer start end) ++ "@var{documentation}@dots{}" ++ (interactive @dots{}) ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++The first line of the function includes its name and three arguments. ++The arguments are the @code{buffer} to which the text will be copied, and ++the @code{start} and @code{end} of the region in the current buffer that ++will be copied. ++ ++The next part of the function is the documentation, which is clear and ++complete. As is conventional, the three arguments are written in ++upper case so you will notice them easily. Even better, they are ++described in the same order as in the argument list. ++ ++Note that the documentation distinguishes between a buffer and its ++name. (The function can handle either.) ++ ++@node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer ++@comment node-name, next, previous, up ++@subsection The @code{append-to-buffer} Interactive Expression ++ ++Since the @code{append-to-buffer} function will be used interactively, ++the function must have an @code{interactive} expression. (For a ++review of @code{interactive}, see @ref{Interactive, , Making a ++Function Interactive}.) The expression reads as follows: ++ ++@smallexample ++@group ++(interactive ++ (list (read-buffer ++ "Append to buffer: " ++ (other-buffer (current-buffer) t)) ++ (region-beginning) ++ (region-end))) ++@end group ++@end smallexample ++ ++@noindent ++This expression is not one with letters standing for parts, as ++described earlier. Instead, it starts a list with these parts: ++ ++The first part of the list is an expression to read the name of a ++buffer and return it as a string. That is @code{read-buffer}. The ++function requires a prompt as its first argument, @samp{"Append to ++buffer: "}. Its second argument tells the command what value to ++provide if you don't specify anything. ++ ++In this case that second argument is an expression containing the ++function @code{other-buffer}, an exception, and a @samp{t}, standing ++for true. ++ ++The first argument to @code{other-buffer}, the exception, is yet ++another function, @code{current-buffer}. That is not going to be ++returned. The second argument is the symbol for true, @code{t}. that ++tells @code{other-buffer} that it may show visible buffers (except in ++this case, it will not show the current buffer, which makes sense). ++ ++@need 1250 ++The expression looks like this: ++ ++@smallexample ++(other-buffer (current-buffer) t) ++@end smallexample ++ ++The second and third arguments to the @code{list} expression are ++@code{(region-beginning)} and @code{(region-end)}. These two ++functions specify the beginning and end of the text to be appended. ++ ++@need 1250 ++Originally, the command used the letters @samp{B} and @samp{r}. ++The whole @code{interactive} expression looked like this: ++ ++@smallexample ++(interactive "BAppend to buffer:@: \nr") ++@end smallexample ++ ++@noindent ++But when that was done, the default value of the buffer switched to ++was invisible. That was not wanted. ++ ++(The prompt was separated from the second argument with a newline, ++@samp{\n}. It was followed by an @samp{r} that told Emacs to bind the ++two arguments that follow the symbol @code{buffer} in the function's ++argument list (that is, @code{start} and @code{end}) to the values of ++point and mark. That argument worked fine.) ++ ++@node append-to-buffer body, append save-excursion, append interactive, append-to-buffer ++@comment node-name, next, previous, up ++@subsection The Body of @code{append-to-buffer} ++ ++@ignore ++in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el ++ ++(defun append-to-buffer (buffer start end) ++ "Append to specified buffer the text of the region. ++It is inserted into that buffer before its point. ++ ++When calling from a program, give three arguments: ++BUFFER (or buffer name), START and END. ++START and END specify the portion of the current buffer to be copied." ++ (interactive ++ (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) ++ (region-beginning) (region-end))) ++ (let ((oldbuf (current-buffer))) ++ (save-excursion ++ (let* ((append-to (get-buffer-create buffer)) ++ (windows (get-buffer-window-list append-to t t)) ++ point) ++ (set-buffer append-to) ++ (setq point (point)) ++ (barf-if-buffer-read-only) ++ (insert-buffer-substring oldbuf start end) ++ (dolist (window windows) ++ (when (= (window-point window) point) ++ (set-window-point window (point)))))))) ++@end ignore ++ ++The body of the @code{append-to-buffer} function begins with @code{let}. ++ ++As we have seen before (@pxref{let, , @code{let}}), the purpose of a ++@code{let} expression is to create and give initial values to one or ++more variables that will only be used within the body of the ++@code{let}. This means that such a variable will not be confused with ++any variable of the same name outside the @code{let} expression. ++ ++We can see how the @code{let} expression fits into the function as a ++whole by showing a template for @code{append-to-buffer} with the ++@code{let} expression in outline: ++ ++@smallexample ++@group ++(defun append-to-buffer (buffer start end) ++ "@var{documentation}@dots{}" ++ (interactive @dots{}) ++ (let ((@var{variable} @var{value})) ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++The @code{let} expression has three elements: ++ ++@enumerate ++@item ++The symbol @code{let}; ++ ++@item ++A varlist containing, in this case, a single two-element list, ++@code{(@var{variable} @var{value})}; ++ ++@item ++The body of the @code{let} expression. ++@end enumerate ++ ++@need 800 ++In the @code{append-to-buffer} function, the varlist looks like this: ++ ++@smallexample ++(oldbuf (current-buffer)) ++@end smallexample ++ ++@noindent ++In this part of the @code{let} expression, the one variable, ++@code{oldbuf}, is bound to the value returned by the ++@code{(current-buffer)} expression. The variable, @code{oldbuf}, is ++used to keep track of the buffer in which you are working and from ++which you will copy. ++ ++The element or elements of a varlist are surrounded by a set of ++parentheses so the Lisp interpreter can distinguish the varlist from ++the body of the @code{let}. As a consequence, the two-element list ++within the varlist is surrounded by a circumscribing set of parentheses. ++The line looks like this: ++ ++@smallexample ++@group ++(let ((oldbuf (current-buffer))) ++ @dots{} ) ++@end group ++@end smallexample ++ ++@noindent ++The two parentheses before @code{oldbuf} might surprise you if you did ++not realize that the first parenthesis before @code{oldbuf} marks the ++boundary of the varlist and the second parenthesis marks the beginning ++of the two-element list, @code{(oldbuf (current-buffer))}. ++ ++@node append save-excursion, , append-to-buffer body, append-to-buffer ++@comment node-name, next, previous, up ++@subsection @code{save-excursion} in @code{append-to-buffer} ++ ++The body of the @code{let} expression in @code{append-to-buffer} ++consists of a @code{save-excursion} expression. ++ ++The @code{save-excursion} function saves the locations of point and ++mark, and restores them to those positions after the expressions in the ++body of the @code{save-excursion} complete execution. In addition, ++@code{save-excursion} keeps track of the original buffer, and ++restores it. This is how @code{save-excursion} is used in ++@code{append-to-buffer}. ++ ++@need 1500 ++@cindex Indentation for formatting ++@cindex Formatting convention ++Incidentally, it is worth noting here that a Lisp function is normally ++formatted so that everything that is enclosed in a multi-line spread is ++indented more to the right than the first symbol. In this function ++definition, the @code{let} is indented more than the @code{defun}, and ++the @code{save-excursion} is indented more than the @code{let}, like ++this: ++ ++@smallexample ++@group ++(defun @dots{} ++ @dots{} ++ @dots{} ++ (let@dots{} ++ (save-excursion ++ @dots{} ++@end group ++@end smallexample ++ ++@need 1500 ++@noindent ++This formatting convention makes it easy to see that the lines in ++the body of the @code{save-excursion} are enclosed by the parentheses ++associated with @code{save-excursion}, just as the ++@code{save-excursion} itself is enclosed by the parentheses associated ++with the @code{let}: ++ ++@smallexample ++@group ++(let ((oldbuf (current-buffer))) ++ (save-excursion ++ @dots{} ++ (set-buffer @dots{}) ++ (insert-buffer-substring oldbuf start end) ++ @dots{})) ++@end group ++@end smallexample ++ ++@need 1200 ++The use of the @code{save-excursion} function can be viewed as a process ++of filling in the slots of a template: ++ ++@smallexample ++@group ++(save-excursion ++ @var{first-expression-in-body} ++ @var{second-expression-in-body} ++ @dots{} ++ @var{last-expression-in-body}) ++@end group ++@end smallexample ++ ++@need 1200 ++@noindent ++In this function, the body of the @code{save-excursion} contains only ++one expression, the @code{let*} expression. You know about a ++@code{let} function. The @code{let*} function is different. It has a ++@samp{*} in its name. It enables Emacs to set each variable in its ++varlist in sequence, one after another. ++ ++Its critical feature is that variables later in the varlist can make ++use of the values to which Emacs set variables earlier in the varlist. ++@xref{fwd-para let, , The @code{let*} expression}. ++ ++We will skip functions like @code{let*} and focus on two: the ++@code{set-buffer} function and the @code{insert-buffer-substring} ++function. ++ ++@need 1250 ++In the old days, the @code{set-buffer} expression was simply ++ ++@smallexample ++(set-buffer (get-buffer-create buffer)) ++@end smallexample ++ ++@need 1250 ++@noindent ++but now it is ++ ++@smallexample ++(set-buffer append-to) ++@end smallexample ++ ++@noindent ++@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier ++on in the @code{let*} expression. That extra binding would not be ++necessary except for that @code{append-to} is used later in the ++varlist as an argument to @code{get-buffer-window-list}. ++ ++@ignore ++in GNU Emacs 22 ++ ++ (let ((oldbuf (current-buffer))) ++ (save-excursion ++ (let* ((append-to (get-buffer-create buffer)) ++ (windows (get-buffer-window-list append-to t t)) ++ point) ++ (set-buffer append-to) ++ (setq point (point)) ++ (barf-if-buffer-read-only) ++ (insert-buffer-substring oldbuf start end) ++ (dolist (window windows) ++ (when (= (window-point window) point) ++ (set-window-point window (point)))))))) ++@end ignore ++ ++The @code{append-to-buffer} function definition inserts text from the ++buffer in which you are currently to a named buffer. It happens that ++@code{insert-buffer-substring} copies text from another buffer to the ++current buffer, just the reverse---that is why the ++@code{append-to-buffer} definition starts out with a @code{let} that ++binds the local symbol @code{oldbuf} to the value returned by ++@code{current-buffer}. ++ ++@need 1250 ++The @code{insert-buffer-substring} expression looks like this: ++ ++@smallexample ++(insert-buffer-substring oldbuf start end) ++@end smallexample ++ ++@noindent ++The @code{insert-buffer-substring} function copies a string ++@emph{from} the buffer specified as its first argument and inserts the ++string into the present buffer. In this case, the argument to ++@code{insert-buffer-substring} is the value of the variable created ++and bound by the @code{let}, namely the value of @code{oldbuf}, which ++was the current buffer when you gave the @code{append-to-buffer} ++command. ++ ++After @code{insert-buffer-substring} has done its work, ++@code{save-excursion} will restore the action to the original buffer ++and @code{append-to-buffer} will have done its job. ++ ++@need 800 ++Written in skeletal form, the workings of the body look like this: ++ ++@smallexample ++@group ++(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) ++ (save-excursion ; @r{Keep track of buffer.} ++ @var{change-buffer} ++ @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}) ++ ++ @var{change-back-to-original-buffer-when-finished} ++@var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished} ++@end group ++@end smallexample ++ ++In summary, @code{append-to-buffer} works as follows: it saves the ++value of the current buffer in the variable called @code{oldbuf}. It ++gets the new buffer (creating one if need be) and switches Emacs' ++attention to it. Using the value of @code{oldbuf}, it inserts the ++region of text from the old buffer into the new buffer; and then using ++@code{save-excursion}, it brings you back to your original buffer. ++ ++In looking at @code{append-to-buffer}, you have explored a fairly ++complex function. It shows how to use @code{let} and ++@code{save-excursion}, and how to change to and come back from another ++buffer. Many function definitions use @code{let}, ++@code{save-excursion}, and @code{set-buffer} this way. ++ ++@node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through ++@comment node-name, next, previous, up ++@section Review ++ ++Here is a brief summary of the various functions discussed in this chapter. ++ ++@table @code ++@item describe-function ++@itemx describe-variable ++Print the documentation for a function or variable. ++Conventionally bound to @kbd{C-h f} and @kbd{C-h v}. ++ ++@item find-tag ++Find the file containing the source for a function or variable and ++switch buffers to it, positioning point at the beginning of the item. ++Conventionally bound to @kbd{M-.} (that's a period following the ++@key{META} key). ++ ++@item save-excursion ++Save the location of point and mark and restore their values after the ++arguments to @code{save-excursion} have been evaluated. Also, remember ++the current buffer and return to it. ++ ++@item push-mark ++Set mark at a location and record the value of the previous mark on the ++mark ring. The mark is a location in the buffer that will keep its ++relative position even if text is added to or removed from the buffer. ++ ++@item goto-char ++Set point to the location specified by the value of the argument, which ++can be a number, a marker, or an expression that returns the number of ++a position, such as @code{(point-min)}. ++ ++@item insert-buffer-substring ++Copy a region of text from a buffer that is passed to the function as ++an argument and insert the region into the current buffer. ++ ++@item mark-whole-buffer ++Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. ++ ++@item set-buffer ++Switch the attention of Emacs to another buffer, but do not change the ++window being displayed. Used when the program rather than a human is ++to work on a different buffer. ++ ++@item get-buffer-create ++@itemx get-buffer ++Find a named buffer or create one if a buffer of that name does not ++exist. The @code{get-buffer} function returns @code{nil} if the named ++buffer does not exist. ++@end table ++ ++@need 1500 ++@node Buffer Exercises, , Buffer Related Review, Buffer Walk Through ++@section Exercises ++ ++@itemize @bullet ++@item ++Write your own @code{simplified-end-of-buffer} function definition; ++then test it to see whether it works. ++ ++@item ++Use @code{if} and @code{get-buffer} to write a function that prints a ++message telling you whether a buffer exists. ++ ++@item ++Using @code{find-tag}, find the source for the @code{copy-to-buffer} ++function. ++@end itemize ++ ++@node More Complex, Narrowing & Widening, Buffer Walk Through, Top ++@comment node-name, next, previous, up ++@chapter A Few More Complex Functions ++ ++In this chapter, we build on what we have learned in previous chapters ++by looking at more complex functions. The @code{copy-to-buffer} ++function illustrates use of two @code{save-excursion} expressions in ++one definition, while the @code{insert-buffer} function illustrates ++use of an asterisk in an @code{interactive} expression, use of ++@code{or}, and the important distinction between a name and the object ++to which the name refers. ++ ++@menu ++* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. ++* insert-buffer:: Read-only, and with @code{or}. ++* beginning-of-buffer:: Shows @code{goto-char}, ++ @code{point-min}, and @code{push-mark}. ++* Second Buffer Related Review:: ++* optional Exercise:: ++@end menu ++ ++@node copy-to-buffer, insert-buffer, More Complex, More Complex ++@comment node-name, next, previous, up ++@section The Definition of @code{copy-to-buffer} ++@findex copy-to-buffer ++ ++After understanding how @code{append-to-buffer} works, it is easy to ++understand @code{copy-to-buffer}. This function copies text into a ++buffer, but instead of adding to the second buffer, it replaces all the ++previous text in the second buffer. ++ ++@need 800 ++The body of @code{copy-to-buffer} looks like this, ++ ++@smallexample ++@group ++@dots{} ++(interactive "BCopy to buffer: \nr") ++(let ((oldbuf (current-buffer))) ++ (with-current-buffer (get-buffer-create buffer) ++ (barf-if-buffer-read-only) ++ (erase-buffer) ++ (save-excursion ++ (insert-buffer-substring oldbuf start end))))) ++@end group ++@end smallexample ++ ++The @code{copy-to-buffer} function has a simpler @code{interactive} ++expression than @code{append-to-buffer}. ++ ++@need 800 ++The definition then says ++ ++@smallexample ++(with-current-buffer (get-buffer-create buffer) @dots{} ++@end smallexample ++ ++First, look at the earliest inner expression; that is evaluated first. ++That expression starts with @code{get-buffer-create buffer}. The ++function tells the computer to use the buffer with the name specified ++as the one to which you are copying, or if such a buffer does not ++exist, to create it. Then, the @code{with-current-buffer} function ++evaluates its body with that buffer temporarily current. ++ ++(This demonstrates another way to shift the computer's attention but ++not the user's. The @code{append-to-buffer} function showed how to do ++the same with @code{save-excursion} and @code{set-buffer}. ++@code{with-current-buffer} is a newer, and arguably easier, ++mechanism.) ++ ++The @code{barf-if-buffer-read-only} function sends you an error ++message saying the buffer is read-only if you cannot modify it. ++ ++The next line has the @code{erase-buffer} function as its sole ++contents. That function erases the buffer. ++ ++Finally, the last two lines contain the @code{save-excursion} ++expression with @code{insert-buffer-substring} as its body. ++The @code{insert-buffer-substring} expression copies the text from ++the buffer you are in (and you have not seen the computer shift its ++attention, so you don't know that that buffer is now called ++@code{oldbuf}). ++ ++Incidentally, this is what is meant by `replacement'. To replace text, ++Emacs erases the previous text and then inserts new text. ++ ++@need 1250 ++In outline, the body of @code{copy-to-buffer} looks like this: ++ ++@smallexample ++@group ++(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) ++ (@var{with-the-buffer-you-are-copying-to} ++ (@var{but-do-not-erase-or-copy-to-a-read-only-buffer}) ++ (erase-buffer) ++ (save-excursion ++ @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}))) ++@end group ++@end smallexample ++ ++@node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex ++@comment node-name, next, previous, up ++@section The Definition of @code{insert-buffer} ++@findex insert-buffer ++ ++@code{insert-buffer} is yet another buffer-related function. This ++command copies another buffer @emph{into} the current buffer. It is the ++reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they ++copy a region of text @emph{from} the current buffer to another buffer. ++ ++Here is a discussion based on the original code. The code was ++simplified in 2003 and is harder to understand. ++ ++(@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see ++a discussion of the new body.) ++ ++In addition, this code illustrates the use of @code{interactive} with a ++buffer that might be @dfn{read-only} and the important distinction ++between the name of an object and the object actually referred to. ++ ++@menu ++* insert-buffer code:: ++* insert-buffer interactive:: When you can read, but not write. ++* insert-buffer body:: The body has an @code{or} and a @code{let}. ++* if & or:: Using an @code{if} instead of an @code{or}. ++* Insert or:: How the @code{or} expression works. ++* Insert let:: Two @code{save-excursion} expressions. ++* New insert-buffer:: ++@end menu ++ ++@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer ++@ifnottex ++@unnumberedsubsec The Code for @code{insert-buffer} ++@end ifnottex ++ ++@need 800 ++Here is the earlier code: ++ ++@smallexample ++@group ++(defun insert-buffer (buffer) ++ "Insert after point the contents of BUFFER. ++Puts mark after the inserted text. ++BUFFER may be a buffer or a buffer name." ++ (interactive "*bInsert buffer:@: ") ++@end group ++@group ++ (or (bufferp buffer) ++ (setq buffer (get-buffer buffer))) ++ (let (start end newmark) ++ (save-excursion ++ (save-excursion ++ (set-buffer buffer) ++ (setq start (point-min) end (point-max))) ++@end group ++@group ++ (insert-buffer-substring buffer start end) ++ (setq newmark (point))) ++ (push-mark newmark))) ++@end group ++@end smallexample ++ ++@need 1200 ++As with other function definitions, you can use a template to see an ++outline of the function: ++ ++@smallexample ++@group ++(defun insert-buffer (buffer) ++ "@var{documentation}@dots{}" ++ (interactive "*bInsert buffer:@: ") ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++@node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer ++@comment node-name, next, previous, up ++@subsection The Interactive Expression in @code{insert-buffer} ++@findex interactive, @r{example use of} ++ ++In @code{insert-buffer}, the argument to the @code{interactive} ++declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert ++buffer:@: }. ++ ++@menu ++* Read-only buffer:: When a buffer cannot be modified. ++* b for interactive:: An existing buffer or else its name. ++@end menu ++ ++@node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive ++@comment node-name, next, previous, up ++@unnumberedsubsubsec A Read-only Buffer ++@cindex Read-only buffer ++@cindex Asterisk for read-only buffer ++@findex * @r{for read-only buffer} ++ ++The asterisk is for the situation when the current buffer is a ++read-only buffer---a buffer that cannot be modified. If ++@code{insert-buffer} is called when the current buffer is read-only, a ++message to this effect is printed in the echo area and the terminal ++may beep or blink at you; you will not be permitted to insert anything ++into current buffer. The asterisk does not need to be followed by a ++newline to separate it from the next argument. ++ ++@node b for interactive, , Read-only buffer, insert-buffer interactive ++@comment node-name, next, previous, up ++@unnumberedsubsubsec @samp{b} in an Interactive Expression ++ ++The next argument in the interactive expression starts with a lower ++case @samp{b}. (This is different from the code for ++@code{append-to-buffer}, which uses an upper-case @samp{B}. ++@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) ++The lower-case @samp{b} tells the Lisp interpreter that the argument ++for @code{insert-buffer} should be an existing buffer or else its ++name. (The upper-case @samp{B} option provides for the possibility ++that the buffer does not exist.) Emacs will prompt you for the name ++of the buffer, offering you a default buffer, with name completion ++enabled. If the buffer does not exist, you receive a message that ++says ``No match''; your terminal may beep at you as well. ++ ++The new and simplified code generates a list for @code{interactive}. ++It uses the @code{barf-if-buffer-read-only} and @code{read-buffer} ++functions with which we are already familiar and the @code{progn} ++special form with which we are not. (It will be described later.) ++ ++@node insert-buffer body, if & or, insert-buffer interactive, insert-buffer ++@comment node-name, next, previous, up ++@subsection The Body of the @code{insert-buffer} Function ++ ++The body of the @code{insert-buffer} function has two major parts: an ++@code{or} expression and a @code{let} expression. The purpose of the ++@code{or} expression is to ensure that the argument @code{buffer} is ++bound to a buffer and not just the name of a buffer. The body of the ++@code{let} expression contains the code which copies the other buffer ++into the current buffer. ++ ++@need 1250 ++In outline, the two expressions fit into the @code{insert-buffer} ++function like this: ++ ++@smallexample ++@group ++(defun insert-buffer (buffer) ++ "@var{documentation}@dots{}" ++ (interactive "*bInsert buffer:@: ") ++ (or @dots{} ++ @dots{} ++@end group ++@group ++ (let (@var{varlist}) ++ @var{body-of-}@code{let}@dots{} ) ++@end group ++@end smallexample ++ ++To understand how the @code{or} expression ensures that the argument ++@code{buffer} is bound to a buffer and not to the name of a buffer, it ++is first necessary to understand the @code{or} function. ++ ++Before doing this, let me rewrite this part of the function using ++@code{if} so that you can see what is done in a manner that will be familiar. ++ ++@node if & or, Insert or, insert-buffer body, insert-buffer ++@comment node-name, next, previous, up ++@subsection @code{insert-buffer} With an @code{if} Instead of an @code{or} ++ ++The job to be done is to make sure the value of @code{buffer} is a ++buffer itself and not the name of a buffer. If the value is the name, ++then the buffer itself must be got. ++ ++You can imagine yourself at a conference where an usher is wandering ++around holding a list with your name on it and looking for you: the ++usher is ``bound'' to your name, not to you; but when the usher finds ++you and takes your arm, the usher becomes ``bound'' to you. ++ ++@need 800 ++In Lisp, you might describe this situation like this: ++ ++@smallexample ++@group ++(if (not (holding-on-to-guest)) ++ (find-and-take-arm-of-guest)) ++@end group ++@end smallexample ++ ++We want to do the same thing with a buffer---if we do not have the ++buffer itself, we want to get it. ++ ++@need 1200 ++Using a predicate called @code{bufferp} that tells us whether we have a ++buffer (rather than its name), we can write the code like this: ++ ++@smallexample ++@group ++(if (not (bufferp buffer)) ; @r{if-part} ++ (setq buffer (get-buffer buffer))) ; @r{then-part} ++@end group ++@end smallexample ++ ++@noindent ++Here, the true-or-false-test of the @code{if} expression is ++@w{@code{(not (bufferp buffer))}}; and the then-part is the expression ++@w{@code{(setq buffer (get-buffer buffer))}}. ++ ++In the test, the function @code{bufferp} returns true if its argument is ++a buffer---but false if its argument is the name of the buffer. (The ++last character of the function name @code{bufferp} is the character ++@samp{p}; as we saw earlier, such use of @samp{p} is a convention that ++indicates that the function is a predicate, which is a term that means ++that the function will determine whether some property is true or false. ++@xref{Wrong Type of Argument, , Using the Wrong Type Object as an ++Argument}.) ++ ++@need 1200 ++The function @code{not} precedes the expression @code{(bufferp buffer)}, ++so the true-or-false-test looks like this: ++ ++@smallexample ++(not (bufferp buffer)) ++@end smallexample ++ ++@noindent ++@code{not} is a function that returns true if its argument is false ++and false if its argument is true. So if @code{(bufferp buffer)} ++returns true, the @code{not} expression returns false and vice-verse: ++what is ``not true'' is false and what is ``not false'' is true. ++ ++Using this test, the @code{if} expression works as follows: when the ++value of the variable @code{buffer} is actually a buffer rather than ++its name, the true-or-false-test returns false and the @code{if} ++expression does not evaluate the then-part. This is fine, since we do ++not need to do anything to the variable @code{buffer} if it really is ++a buffer. ++ ++On the other hand, when the value of @code{buffer} is not a buffer ++itself, but the name of a buffer, the true-or-false-test returns true ++and the then-part of the expression is evaluated. In this case, the ++then-part is @code{(setq buffer (get-buffer buffer))}. This ++expression uses the @code{get-buffer} function to return an actual ++buffer itself, given its name. The @code{setq} then sets the variable ++@code{buffer} to the value of the buffer itself, replacing its previous ++value (which was the name of the buffer). ++ ++@node Insert or, Insert let, if & or, insert-buffer ++@comment node-name, next, previous, up ++@subsection The @code{or} in the Body ++ ++The purpose of the @code{or} expression in the @code{insert-buffer} ++function is to ensure that the argument @code{buffer} is bound to a ++buffer and not just to the name of a buffer. The previous section shows ++how the job could have been done using an @code{if} expression. ++However, the @code{insert-buffer} function actually uses @code{or}. ++To understand this, it is necessary to understand how @code{or} works. ++ ++@findex or ++An @code{or} function can have any number of arguments. It evaluates ++each argument in turn and returns the value of the first of its ++arguments that is not @code{nil}. Also, and this is a crucial feature ++of @code{or}, it does not evaluate any subsequent arguments after ++returning the first non-@code{nil} value. ++ ++@need 800 ++The @code{or} expression looks like this: ++ ++@smallexample ++@group ++(or (bufferp buffer) ++ (setq buffer (get-buffer buffer))) ++@end group ++@end smallexample ++ ++@noindent ++The first argument to @code{or} is the expression @code{(bufferp buffer)}. ++This expression returns true (a non-@code{nil} value) if the buffer is ++actually a buffer, and not just the name of a buffer. In the @code{or} ++expression, if this is the case, the @code{or} expression returns this ++true value and does not evaluate the next expression---and this is fine ++with us, since we do not want to do anything to the value of ++@code{buffer} if it really is a buffer. ++ ++On the other hand, if the value of @code{(bufferp buffer)} is @code{nil}, ++which it will be if the value of @code{buffer} is the name of a buffer, ++the Lisp interpreter evaluates the next element of the @code{or} ++expression. This is the expression @code{(setq buffer (get-buffer ++buffer))}. This expression returns a non-@code{nil} value, which ++is the value to which it sets the variable @code{buffer}---and this ++value is a buffer itself, not the name of a buffer. ++ ++The result of all this is that the symbol @code{buffer} is always ++bound to a buffer itself rather than to the name of a buffer. All ++this is necessary because the @code{set-buffer} function in a ++following line only works with a buffer itself, not with the name to a ++buffer. ++ ++@need 1250 ++Incidentally, using @code{or}, the situation with the usher would be ++written like this: ++ ++@smallexample ++(or (holding-on-to-guest) (find-and-take-arm-of-guest)) ++@end smallexample ++ ++@node Insert let, New insert-buffer, Insert or, insert-buffer ++@comment node-name, next, previous, up ++@subsection The @code{let} Expression in @code{insert-buffer} ++ ++After ensuring that the variable @code{buffer} refers to a buffer itself ++and not just to the name of a buffer, the @code{insert-buffer function} ++continues with a @code{let} expression. This specifies three local ++variables, @code{start}, @code{end}, and @code{newmark} and binds them ++to the initial value @code{nil}. These variables are used inside the ++remainder of the @code{let} and temporarily hide any other occurrence of ++variables of the same name in Emacs until the end of the @code{let}. ++ ++@need 1200 ++The body of the @code{let} contains two @code{save-excursion} ++expressions. First, we will look at the inner @code{save-excursion} ++expression in detail. The expression looks like this: ++ ++@smallexample ++@group ++(save-excursion ++ (set-buffer buffer) ++ (setq start (point-min) end (point-max))) ++@end group ++@end smallexample ++ ++@noindent ++The expression @code{(set-buffer buffer)} changes Emacs' attention ++from the current buffer to the one from which the text will copied. ++In that buffer, the variables @code{start} and @code{end} are set to ++the beginning and end of the buffer, using the commands ++@code{point-min} and @code{point-max}. Note that we have here an ++illustration of how @code{setq} is able to set two variables in the ++same expression. The first argument of @code{setq} is set to the ++value of its second, and its third argument is set to the value of its ++fourth. ++ ++After the body of the inner @code{save-excursion} is evaluated, the ++@code{save-excursion} restores the original buffer, but @code{start} and ++@code{end} remain set to the values of the beginning and end of the ++buffer from which the text will be copied. ++ ++@need 1250 ++The outer @code{save-excursion} expression looks like this: ++ ++@smallexample ++@group ++(save-excursion ++ (@var{inner-}@code{save-excursion}@var{-expression} ++ (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end}) ++ (insert-buffer-substring buffer start end) ++ (setq newmark (point))) ++@end group ++@end smallexample ++ ++@noindent ++The @code{insert-buffer-substring} function copies the text ++@emph{into} the current buffer @emph{from} the region indicated by ++@code{start} and @code{end} in @code{buffer}. Since the whole of the ++second buffer lies between @code{start} and @code{end}, the whole of ++the second buffer is copied into the buffer you are editing. Next, ++the value of point, which will be at the end of the inserted text, is ++recorded in the variable @code{newmark}. ++ ++After the body of the outer @code{save-excursion} is evaluated, point ++and mark are relocated to their original places. ++ ++However, it is convenient to locate a mark at the end of the newly ++inserted text and locate point at its beginning. The @code{newmark} ++variable records the end of the inserted text. In the last line of ++the @code{let} expression, the @code{(push-mark newmark)} expression ++function sets a mark to this location. (The previous location of the ++mark is still accessible; it is recorded on the mark ring and you can ++go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is ++located at the beginning of the inserted text, which is where it was ++before you called the insert function, the position of which was saved ++by the first @code{save-excursion}. ++ ++@need 1250 ++The whole @code{let} expression looks like this: ++ ++@smallexample ++@group ++(let (start end newmark) ++ (save-excursion ++ (save-excursion ++ (set-buffer buffer) ++ (setq start (point-min) end (point-max))) ++ (insert-buffer-substring buffer start end) ++ (setq newmark (point))) ++ (push-mark newmark)) ++@end group ++@end smallexample ++ ++Like the @code{append-to-buffer} function, the @code{insert-buffer} ++function uses @code{let}, @code{save-excursion}, and ++@code{set-buffer}. In addition, the function illustrates one way to ++use @code{or}. All these functions are building blocks that we will ++find and use again and again. ++ ++@node New insert-buffer, , Insert let, insert-buffer ++@comment node-name, next, previous, up ++@subsection New Body for @code{insert-buffer} ++@findex insert-buffer, new version body ++@findex new version body for insert-buffer ++ ++The body in the GNU Emacs 22 version is more confusing than the original. ++ ++@need 1250 ++It consists of two expressions, ++ ++@smallexample ++@group ++ (push-mark ++ (save-excursion ++ (insert-buffer-substring (get-buffer buffer)) ++ (point))) ++ ++ nil ++@end group ++@end smallexample ++ ++@noindent ++except, and this is what confuses novices, very important work is done ++inside the @code{push-mark} expression. ++ ++The @code{get-buffer} function returns a buffer with the name ++provided. You will note that the function is @emph{not} called ++@code{get-buffer-create}; it does not create a buffer if one does not ++already exist. The buffer returned by @code{get-buffer}, an existing ++buffer, is passed to @code{insert-buffer-substring}, which inserts the ++whole of the buffer (since you did not specify anything else). ++ ++The location into which the buffer is inserted is recorded by ++@code{push-mark}. Then the function returns @code{nil}, the value of ++its last command. Put another way, the @code{insert-buffer} function ++exists only to produce a side effect, inserting another buffer, not to ++return any value. ++ ++@node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex ++@comment node-name, next, previous, up ++@section Complete Definition of @code{beginning-of-buffer} ++@findex beginning-of-buffer ++ ++The basic structure of the @code{beginning-of-buffer} function has ++already been discussed. (@xref{simplified-beginning-of-buffer, , A ++Simplified @code{beginning-of-buffer} Definition}.) ++This section describes the complex part of the definition. ++ ++As previously described, when invoked without an argument, ++@code{beginning-of-buffer} moves the cursor to the beginning of the ++buffer (in truth, the beginning of the accessible portion of the ++buffer), leaving the mark at the previous position. However, when the ++command is invoked with a number between one and ten, the function ++considers that number to be a fraction of the length of the buffer, ++measured in tenths, and Emacs moves the cursor that fraction of the ++way from the beginning of the buffer. Thus, you can either call this ++function with the key command @kbd{M-<}, which will move the cursor to ++the beginning of the buffer, or with a key command such as @kbd{C-u 7 ++M-<} which will move the cursor to a point 70% of the way through the ++buffer. If a number bigger than ten is used for the argument, it ++moves to the end of the buffer. ++ ++The @code{beginning-of-buffer} function can be called with or without an ++argument. The use of the argument is optional. ++ ++@menu ++* Optional Arguments:: ++* beginning-of-buffer opt arg:: Example with optional argument. ++* beginning-of-buffer complete:: ++@end menu ++ ++@node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer ++@subsection Optional Arguments ++ ++Unless told otherwise, Lisp expects that a function with an argument in ++its function definition will be called with a value for that argument. ++If that does not happen, you get an error and a message that says ++@samp{Wrong number of arguments}. ++ ++@cindex Optional arguments ++@cindex Keyword ++@findex optional ++However, optional arguments are a feature of Lisp: a particular ++@dfn{keyword} is used to tell the Lisp interpreter that an argument is ++optional. The keyword is @code{&optional}. (The @samp{&} in front of ++@samp{optional} is part of the keyword.) In a function definition, if ++an argument follows the keyword @code{&optional}, no value need be ++passed to that argument when the function is called. ++ ++@need 1200 ++The first line of the function definition of @code{beginning-of-buffer} ++therefore looks like this: ++ ++@smallexample ++(defun beginning-of-buffer (&optional arg) ++@end smallexample ++ ++@need 1250 ++In outline, the whole function looks like this: ++ ++@smallexample ++@group ++(defun beginning-of-buffer (&optional arg) ++ "@var{documentation}@dots{}" ++ (interactive "P") ++ (or (@var{is-the-argument-a-cons-cell} arg) ++ (and @var{are-both-transient-mark-mode-and-mark-active-true}) ++ (push-mark)) ++ (let (@var{determine-size-and-set-it}) ++ (goto-char ++ (@var{if-there-is-an-argument} ++ @var{figure-out-where-to-go} ++ @var{else-go-to} ++ (point-min)))) ++ @var{do-nicety} ++@end group ++@end smallexample ++ ++The function is similar to the @code{simplified-beginning-of-buffer} ++function except that the @code{interactive} expression has @code{"P"} ++as an argument and the @code{goto-char} function is followed by an ++if-then-else expression that figures out where to put the cursor if ++there is an argument that is not a cons cell. ++ ++(Since I do not explain a cons cell for many more chapters, please ++consider ignoring the function @code{consp}. @xref{List ++Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type, ++, Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference ++Manual}.) ++ ++The @code{"P"} in the @code{interactive} expression tells Emacs to ++pass a prefix argument, if there is one, to the function in raw form. ++A prefix argument is made by typing the @key{META} key followed by a ++number, or by typing @kbd{C-u} and then a number. (If you don't type ++a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase ++@code{"p"} in the @code{interactive} expression causes the function to ++convert a prefix arg to a number.) ++ ++The true-or-false-test of the @code{if} expression looks complex, but ++it is not: it checks whether @code{arg} has a value that is not ++@code{nil} and whether it is a cons cell. (That is what @code{consp} ++does; it checks whether its argument is a cons cell.) If @code{arg} ++has a value that is not @code{nil} (and is not a cons cell), which ++will be the case if @code{beginning-of-buffer} is called with a ++numeric argument, then this true-or-false-test will return true and ++the then-part of the @code{if} expression will be evaluated. On the ++other hand, if @code{beginning-of-buffer} is not called with an ++argument, the value of @code{arg} will be @code{nil} and the else-part ++of the @code{if} expression will be evaluated. The else-part is ++simply @code{point-min}, and when this is the outcome, the whole ++@code{goto-char} expression is @code{(goto-char (point-min))}, which ++is how we saw the @code{beginning-of-buffer} function in its ++simplified form. ++ ++@node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer ++@subsection @code{beginning-of-buffer} with an Argument ++ ++When @code{beginning-of-buffer} is called with an argument, an ++expression is evaluated which calculates what value to pass to ++@code{goto-char}. This expression is rather complicated at first sight. ++It includes an inner @code{if} expression and much arithmetic. It looks ++like this: ++ ++@smallexample ++@group ++(if (> (buffer-size) 10000) ++ ;; @r{Avoid overflow for large buffer sizes!} ++ (* (prefix-numeric-value arg) ++ (/ size 10)) ++ (/ ++ (+ 10 ++ (* ++ size (prefix-numeric-value arg))) 10))) ++@end group ++@end smallexample ++ ++@menu ++* Disentangle beginning-of-buffer:: ++* Large buffer case:: ++* Small buffer case:: ++@end menu ++ ++@node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg ++@ifnottex ++@unnumberedsubsubsec Disentangle @code{beginning-of-buffer} ++@end ifnottex ++ ++Like other complex-looking expressions, the conditional expression ++within @code{beginning-of-buffer} can be disentangled by looking at it ++as parts of a template, in this case, the template for an if-then-else ++expression. In skeletal form, the expression looks like this: ++ ++@smallexample ++@group ++(if (@var{buffer-is-large} ++ @var{divide-buffer-size-by-10-and-multiply-by-arg} ++ @var{else-use-alternate-calculation} ++@end group ++@end smallexample ++ ++The true-or-false-test of this inner @code{if} expression checks the ++size of the buffer. The reason for this is that the old version 18 ++Emacs used numbers that are no bigger than eight million or so and in ++the computation that followed, the programmer feared that Emacs might ++try to use over-large numbers if the buffer were large. The term ++`overflow', mentioned in the comment, means numbers that are over ++large. More recent versions of Emacs use larger numbers, but this ++code has not been touched, if only because people now look at buffers ++that are far, far larger than ever before. ++ ++There are two cases: if the buffer is large and if it is not. ++ ++@node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg ++@comment node-name, next, previous, up ++@unnumberedsubsubsec What happens in a large buffer ++ ++In @code{beginning-of-buffer}, the inner @code{if} expression tests ++whether the size of the buffer is greater than 10,000 characters. To do ++this, it uses the @code{>} function and the computation of @code{size} ++that comes from the let expression. ++ ++In the old days, the function @code{buffer-size} was used. Not only ++was that function called several times, it gave the size of the whole ++buffer, not the accessible part. The computation makes much more ++sense when it handles just the accessible part. (@xref{Narrowing & ++Widening, , Narrowing and Widening}, for more information on focusing ++attention to an `accessible' part.) ++ ++@need 800 ++The line looks like this: ++ ++@smallexample ++(if (> size 10000) ++@end smallexample ++ ++@need 1200 ++@noindent ++When the buffer is large, the then-part of the @code{if} expression is ++evaluated. It reads like this (after formatting for easy reading): ++ ++@smallexample ++@group ++(* ++ (prefix-numeric-value arg) ++ (/ size 10)) ++@end group ++@end smallexample ++ ++@noindent ++This expression is a multiplication, with two arguments to the function ++@code{*}. ++ ++The first argument is @code{(prefix-numeric-value arg)}. When ++@code{"P"} is used as the argument for @code{interactive}, the value ++passed to the function as its argument is passed a ``raw prefix ++argument'', and not a number. (It is a number in a list.) To perform ++the arithmetic, a conversion is necessary, and ++@code{prefix-numeric-value} does the job. ++ ++@findex / @r{(division)} ++@cindex Division ++The second argument is @code{(/ size 10)}. This expression divides ++the numeric value by ten --- the numeric value of the size of the ++accessible portion of the buffer. This produces a number that tells ++how many characters make up one tenth of the buffer size. (In Lisp, ++@code{/} is used for division, just as @code{*} is used for ++multiplication.) ++ ++@need 1200 ++In the multiplication expression as a whole, this amount is multiplied ++by the value of the prefix argument---the multiplication looks like this: ++ ++@smallexample ++@group ++(* @var{numeric-value-of-prefix-arg} ++ @var{number-of-characters-in-one-tenth-of-the-accessible-buffer}) ++@end group ++@end smallexample ++ ++@noindent ++If, for example, the prefix argument is @samp{7}, the one-tenth value ++will be multiplied by 7 to give a position 70% of the way through. ++ ++@need 1200 ++The result of all this is that if the accessible portion of the buffer ++is large, the @code{goto-char} expression reads like this: ++ ++@smallexample ++@group ++(goto-char (* (prefix-numeric-value arg) ++ (/ size 10))) ++@end group ++@end smallexample ++ ++This puts the cursor where we want it. ++ ++@node Small buffer case, , Large buffer case, beginning-of-buffer opt arg ++@comment node-name, next, previous, up ++@unnumberedsubsubsec What happens in a small buffer ++ ++If the buffer contains fewer than 10,000 characters, a slightly ++different computation is performed. You might think this is not ++necessary, since the first computation could do the job. However, in ++a small buffer, the first method may not put the cursor on exactly the ++desired line; the second method does a better job. ++ ++@need 800 ++The code looks like this: ++ ++@c Keep this on one line. ++@smallexample ++(/ (+ 10 (* size (prefix-numeric-value arg))) 10)) ++@end smallexample ++ ++@need 1200 ++@noindent ++This is code in which you figure out what happens by discovering how the ++functions are embedded in parentheses. It is easier to read if you ++reformat it with each expression indented more deeply than its ++enclosing expression: ++ ++@smallexample ++@group ++ (/ ++ (+ 10 ++ (* ++ size ++ (prefix-numeric-value arg))) ++ 10)) ++@end group ++@end smallexample ++ ++@need 1200 ++@noindent ++Looking at parentheses, we see that the innermost operation is ++@code{(prefix-numeric-value arg)}, which converts the raw argument to ++a number. In the following expression, this number is multiplied by ++the size of the accessible portion of the buffer: ++ ++@smallexample ++(* size (prefix-numeric-value arg)) ++@end smallexample ++ ++@noindent ++This multiplication creates a number that may be larger than the size of ++the buffer---seven times larger if the argument is 7, for example. Ten ++is then added to this number and finally the large number is divided by ++ten to provide a value that is one character larger than the percentage ++position in the buffer. ++ ++The number that results from all this is passed to @code{goto-char} and ++the cursor is moved to that point. ++ ++@need 1500 ++@node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer ++@comment node-name, next, previous, up ++@subsection The Complete @code{beginning-of-buffer} ++ ++@need 1000 ++Here is the complete text of the @code{beginning-of-buffer} function: ++@sp 1 ++ ++@c In GNU Emacs 22 ++@smallexample ++@group ++(defun beginning-of-buffer (&optional arg) ++ "Move point to the beginning of the buffer; ++leave mark at previous position. ++With \\[universal-argument] prefix, ++do not set mark at previous position. ++With numeric arg N, ++put point N/10 of the way from the beginning. ++ ++If the buffer is narrowed, ++this command uses the beginning and size ++of the accessible part of the buffer. ++@end group ++ ++@group ++Don't use this command in Lisp programs! ++\(goto-char (point-min)) is faster ++and avoids clobbering the mark." ++ (interactive "P") ++ (or (consp arg) ++ (and transient-mark-mode mark-active) ++ (push-mark)) ++@end group ++@group ++ (let ((size (- (point-max) (point-min)))) ++ (goto-char (if (and arg (not (consp arg))) ++ (+ (point-min) ++ (if (> size 10000) ++ ;; Avoid overflow for large buffer sizes! ++ (* (prefix-numeric-value arg) ++ (/ size 10)) ++ (/ (+ 10 (* size (prefix-numeric-value arg))) ++ 10))) ++ (point-min)))) ++ (if arg (forward-line 1))) ++@end group ++@end smallexample ++ ++@ignore ++From before GNU Emacs 22 ++@smallexample ++@group ++(defun beginning-of-buffer (&optional arg) ++ "Move point to the beginning of the buffer; ++leave mark at previous position. ++With arg N, put point N/10 of the way ++from the true beginning. ++@end group ++@group ++Don't use this in Lisp programs! ++\(goto-char (point-min)) is faster ++and does not set the mark." ++ (interactive "P") ++ (push-mark) ++@end group ++@group ++ (goto-char ++ (if arg ++ (if (> (buffer-size) 10000) ++ ;; @r{Avoid overflow for large buffer sizes!} ++ (* (prefix-numeric-value arg) ++ (/ (buffer-size) 10)) ++@end group ++@group ++ (/ (+ 10 (* (buffer-size) ++ (prefix-numeric-value arg))) ++ 10)) ++ (point-min))) ++ (if arg (forward-line 1))) ++@end group ++@end smallexample ++@end ignore ++ ++@noindent ++Except for two small points, the previous discussion shows how this ++function works. The first point deals with a detail in the ++documentation string, and the second point concerns the last line of ++the function. ++ ++@need 800 ++In the documentation string, there is reference to an expression: ++ ++@smallexample ++\\[universal-argument] ++@end smallexample ++ ++@noindent ++A @samp{\\} is used before the first square bracket of this ++expression. This @samp{\\} tells the Lisp interpreter to substitute ++whatever key is currently bound to the @samp{[@dots{}]}. In the case ++of @code{universal-argument}, that is usually @kbd{C-u}, but it might ++be different. (@xref{Documentation Tips, , Tips for Documentation ++Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more ++information.) ++ ++@need 1200 ++Finally, the last line of the @code{beginning-of-buffer} command says ++to move point to the beginning of the next line if the command is ++invoked with an argument: ++ ++@smallexample ++(if arg (forward-line 1))) ++@end smallexample ++ ++@noindent ++This puts the cursor at the beginning of the first line after the ++appropriate tenths position in the buffer. This is a flourish that ++means that the cursor is always located @emph{at least} the requested ++tenths of the way through the buffer, which is a nicety that is, ++perhaps, not necessary, but which, if it did not occur, would be sure ++to draw complaints. ++ ++On the other hand, it also means that if you specify the command with ++a @kbd{C-u}, but without a number, that is to say, if the `raw prefix ++argument' is simply a cons cell, then the command puts you at the ++beginning of the second line @dots{} I don't know whether this is ++intended or whether no one has dealt with the code to avoid this ++happening. ++ ++@node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex ++@comment node-name, next, previous, up ++@section Review ++ ++Here is a brief summary of some of the topics covered in this chapter. ++ ++@table @code ++@item or ++Evaluate each argument in sequence, and return the value of the first ++argument that is not @code{nil}; if none return a value that is not ++@code{nil}, return @code{nil}. In brief, return the first true value ++of the arguments; return a true value if one @emph{or} any of the ++others are true. ++ ++@item and ++Evaluate each argument in sequence, and if any are @code{nil}, return ++@code{nil}; if none are @code{nil}, return the value of the last ++argument. In brief, return a true value only if all the arguments are ++true; return a true value if one @emph{and} each of the others is ++true. ++ ++@item &optional ++A keyword used to indicate that an argument to a function definition ++is optional; this means that the function can be evaluated without the ++argument, if desired. ++ ++@item prefix-numeric-value ++Convert the `raw prefix argument' produced by @code{(interactive ++"P")} to a numeric value. ++ ++@item forward-line ++Move point forward to the beginning of the next line, or if the argument ++is greater than one, forward that many lines. If it can't move as far ++forward as it is supposed to, @code{forward-line} goes forward as far as ++it can and then returns a count of the number of additional lines it was ++supposed to move but couldn't. ++ ++@item erase-buffer ++Delete the entire contents of the current buffer. ++ ++@item bufferp ++Return @code{t} if its argument is a buffer; otherwise return @code{nil}. ++@end table ++ ++@node optional Exercise, , Second Buffer Related Review, More Complex ++@section @code{optional} Argument Exercise ++ ++Write an interactive function with an optional argument that tests ++whether its argument, a number, is greater than or equal to, or else, ++less than the value of @code{fill-column}, and tells you which, in a ++message. However, if you do not pass an argument to the function, use ++56 as a default value. ++ ++@node Narrowing & Widening, car cdr & cons, More Complex, Top ++@comment node-name, next, previous, up ++@chapter Narrowing and Widening ++@cindex Focusing attention (narrowing) ++@cindex Narrowing ++@cindex Widening ++ ++Narrowing is a feature of Emacs that makes it possible for you to focus ++on a specific part of a buffer, and work without accidentally changing ++other parts. Narrowing is normally disabled since it can confuse ++novices. ++ ++@menu ++* Narrowing advantages:: The advantages of narrowing ++* save-restriction:: The @code{save-restriction} special form. ++* what-line:: The number of the line that point is on. ++* narrow Exercise:: ++@end menu ++ ++@node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening ++@ifnottex ++@unnumberedsec The Advantages of Narrowing ++@end ifnottex ++ ++With narrowing, the rest of a buffer is made invisible, as if it weren't ++there. This is an advantage if, for example, you want to replace a word ++in one part of a buffer but not in another: you narrow to the part you want ++and the replacement is carried out only in that section, not in the rest ++of the buffer. Searches will only work within a narrowed region, not ++outside of one, so if you are fixing a part of a document, you can keep ++yourself from accidentally finding parts you do not need to fix by ++narrowing just to the region you want. ++(The key binding for @code{narrow-to-region} is @kbd{C-x n n}.) ++ ++However, narrowing does make the rest of the buffer invisible, which ++can scare people who inadvertently invoke narrowing and think they ++have deleted a part of their file. Moreover, the @code{undo} command ++(which is usually bound to @kbd{C-x u}) does not turn off narrowing ++(nor should it), so people can become quite desperate if they do not ++know that they can return the rest of a buffer to visibility with the ++@code{widen} command. ++(The key binding for @code{widen} is @kbd{C-x n w}.) ++ ++Narrowing is just as useful to the Lisp interpreter as to a human. ++Often, an Emacs Lisp function is designed to work on just part of a ++buffer; or conversely, an Emacs Lisp function needs to work on all of a ++buffer that has been narrowed. The @code{what-line} function, for ++example, removes the narrowing from a buffer, if it has any narrowing ++and when it has finished its job, restores the narrowing to what it was. ++On the other hand, the @code{count-lines} function, which is called by ++@code{what-line}, uses narrowing to restrict itself to just that portion ++of the buffer in which it is interested and then restores the previous ++situation. ++ ++@node save-restriction, what-line, Narrowing advantages, Narrowing & Widening ++@comment node-name, next, previous, up ++@section The @code{save-restriction} Special Form ++@findex save-restriction ++ ++In Emacs Lisp, you can use the @code{save-restriction} special form to ++keep track of whatever narrowing is in effect, if any. When the Lisp ++interpreter meets with @code{save-restriction}, it executes the code ++in the body of the @code{save-restriction} expression, and then undoes ++any changes to narrowing that the code caused. If, for example, the ++buffer is narrowed and the code that follows @code{save-restriction} ++gets rid of the narrowing, @code{save-restriction} returns the buffer ++to its narrowed region afterwards. In the @code{what-line} command, ++any narrowing the buffer may have is undone by the @code{widen} ++command that immediately follows the @code{save-restriction} command. ++Any original narrowing is restored just before the completion of the ++function. ++ ++@need 1250 ++The template for a @code{save-restriction} expression is simple: ++ ++@smallexample ++@group ++(save-restriction ++ @var{body}@dots{} ) ++@end group ++@end smallexample ++ ++@noindent ++The body of the @code{save-restriction} is one or more expressions that ++will be evaluated in sequence by the Lisp interpreter. ++ ++Finally, a point to note: when you use both @code{save-excursion} and ++@code{save-restriction}, one right after the other, you should use ++@code{save-excursion} outermost. If you write them in reverse order, ++you may fail to record narrowing in the buffer to which Emacs switches ++after calling @code{save-excursion}. Thus, when written together, ++@code{save-excursion} and @code{save-restriction} should be written ++like this: ++ ++@smallexample ++@group ++(save-excursion ++ (save-restriction ++ @var{body}@dots{})) ++@end group ++@end smallexample ++ ++In other circumstances, when not written together, the ++@code{save-excursion} and @code{save-restriction} special forms must ++be written in the order appropriate to the function. ++ ++@need 1250 ++For example, ++ ++@smallexample ++@group ++ (save-restriction ++ (widen) ++ (save-excursion ++ @var{body}@dots{})) ++@end group ++@end smallexample ++ ++@ignore ++Emacs 22 ++/usr/local/src/emacs/lisp/simple.el ++ ++(defun what-line () ++ "Print the current buffer line number and narrowed line number of point." ++ (interactive) ++ (let ((start (point-min)) ++ (n (line-number-at-pos))) ++ (if (= start 1) ++ (message "Line %d" n) ++ (save-excursion ++ (save-restriction ++ (widen) ++ (message "line %d (narrowed line %d)" ++ (+ n (line-number-at-pos start) -1) n)))))) ++ ++(defun line-number-at-pos (&optional pos) ++ "Return (narrowed) buffer line number at position POS. ++If POS is nil, use current buffer location. ++Counting starts at (point-min), so the value refers ++to the contents of the accessible portion of the buffer." ++ (let ((opoint (or pos (point))) start) ++ (save-excursion ++ (goto-char (point-min)) ++ (setq start (point)) ++ (goto-char opoint) ++ (forward-line 0) ++ (1+ (count-lines start (point)))))) ++ ++(defun count-lines (start end) ++ "Return number of lines between START and END. ++This is usually the number of newlines between them, ++but can be one more if START is not equal to END ++and the greater of them is not at the start of a line." ++ (save-excursion ++ (save-restriction ++ (narrow-to-region start end) ++ (goto-char (point-min)) ++ (if (eq selective-display t) ++ (save-match-data ++ (let ((done 0)) ++ (while (re-search-forward "[\n\C-m]" nil t 40) ++ (setq done (+ 40 done))) ++ (while (re-search-forward "[\n\C-m]" nil t 1) ++ (setq done (+ 1 done))) ++ (goto-char (point-max)) ++ (if (and (/= start end) ++ (not (bolp))) ++ (1+ done) ++ done))) ++ (- (buffer-size) (forward-line (buffer-size))))))) ++@end ignore ++ ++@node what-line, narrow Exercise, save-restriction, Narrowing & Widening ++@comment node-name, next, previous, up ++@section @code{what-line} ++@findex what-line ++@cindex Widening, example of ++ ++The @code{what-line} command tells you the number of the line in which ++the cursor is located. The function illustrates the use of the ++@code{save-restriction} and @code{save-excursion} commands. Here is the ++original text of the function: ++ ++@smallexample ++@group ++(defun what-line () ++ "Print the current line number (in the buffer) of point." ++ (interactive) ++ (save-restriction ++ (widen) ++ (save-excursion ++ (beginning-of-line) ++ (message "Line %d" ++ (1+ (count-lines 1 (point))))))) ++@end group ++@end smallexample ++ ++(In recent versions of GNU Emacs, the @code{what-line} function has ++been expanded to tell you your line number in a narrowed buffer as ++well as your line number in a widened buffer. The recent version is ++more complex than the version shown here. If you feel adventurous, ++you might want to look at it after figuring out how this version ++works. You will probably need to use @kbd{C-h f} ++(@code{describe-function}). The newer version uses a conditional to ++determine whether the buffer has been narrowed. ++ ++(Also, it uses @code{line-number-at-pos}, which among other simple ++expressions, such as @code{(goto-char (point-min))}, moves point to ++the beginning of the current line with @code{(forward-line 0)} rather ++than @code{beginning-of-line}.) ++ ++The @code{what-line} function as shown here has a documentation line ++and is interactive, as you would expect. The next two lines use the ++functions @code{save-restriction} and @code{widen}. ++ ++The @code{save-restriction} special form notes whatever narrowing is in ++effect, if any, in the current buffer and restores that narrowing after ++the code in the body of the @code{save-restriction} has been evaluated. ++ ++The @code{save-restriction} special form is followed by @code{widen}. ++This function undoes any narrowing the current buffer may have had ++when @code{what-line} was called. (The narrowing that was there is ++the narrowing that @code{save-restriction} remembers.) This widening ++makes it possible for the line counting commands to count from the ++beginning of the buffer. Otherwise, they would have been limited to ++counting within the accessible region. Any original narrowing is ++restored just before the completion of the function by the ++@code{save-restriction} special form. ++ ++The call to @code{widen} is followed by @code{save-excursion}, which ++saves the location of the cursor (i.e., of point) and of the mark, and ++restores them after the code in the body of the @code{save-excursion} ++uses the @code{beginning-of-line} function to move point. ++ ++(Note that the @code{(widen)} expression comes between the ++@code{save-restriction} and @code{save-excursion} special forms. When ++you write the two @code{save- @dots{}} expressions in sequence, write ++@code{save-excursion} outermost.) ++ ++@need 1200 ++The last two lines of the @code{what-line} function are functions to ++count the number of lines in the buffer and then print the number in the ++echo area. ++ ++@smallexample ++@group ++(message "Line %d" ++ (1+ (count-lines 1 (point))))))) ++@end group ++@end smallexample ++ ++The @code{message} function prints a one-line message at the bottom of ++the Emacs screen. The first argument is inside of quotation marks and ++is printed as a string of characters. However, it may contain a ++@samp{%d} expression to print a following argument. @samp{%d} prints ++the argument as a decimal, so the message will say something such as ++@samp{Line 243}. ++ ++@need 1200 ++The number that is printed in place of the @samp{%d} is computed by the ++last line of the function: ++ ++@smallexample ++(1+ (count-lines 1 (point))) ++@end smallexample ++ ++@ignore ++GNU Emacs 22 ++ ++(defun count-lines (start end) ++ "Return number of lines between START and END. ++This is usually the number of newlines between them, ++but can be one more if START is not equal to END ++and the greater of them is not at the start of a line." ++ (save-excursion ++ (save-restriction ++ (narrow-to-region start end) ++ (goto-char (point-min)) ++ (if (eq selective-display t) ++ (save-match-data ++ (let ((done 0)) ++ (while (re-search-forward "[\n\C-m]" nil t 40) ++ (setq done (+ 40 done))) ++ (while (re-search-forward "[\n\C-m]" nil t 1) ++ (setq done (+ 1 done))) ++ (goto-char (point-max)) ++ (if (and (/= start end) ++ (not (bolp))) ++ (1+ done) ++ done))) ++ (- (buffer-size) (forward-line (buffer-size))))))) ++@end ignore ++ ++@noindent ++What this does is count the lines from the first position of the ++buffer, indicated by the @code{1}, up to @code{(point)}, and then add ++one to that number. (The @code{1+} function adds one to its ++argument.) We add one to it because line 2 has only one line before ++it, and @code{count-lines} counts only the lines @emph{before} the ++current line. ++ ++After @code{count-lines} has done its job, and the message has been ++printed in the echo area, the @code{save-excursion} restores point and ++mark to their original positions; and @code{save-restriction} restores ++the original narrowing, if any. ++ ++@node narrow Exercise, , what-line, Narrowing & Widening ++@section Exercise with Narrowing ++ ++Write a function that will display the first 60 characters of the ++current buffer, even if you have narrowed the buffer to its latter ++half so that the first line is inaccessible. Restore point, mark, and ++narrowing. For this exercise, you need to use a whole potpourri of ++functions, including @code{save-restriction}, @code{widen}, ++@code{goto-char}, @code{point-min}, @code{message}, and ++@code{buffer-substring}. ++ ++@cindex Properties, mention of @code{buffer-substring-no-properties} ++(@code{buffer-substring} is a previously unmentioned function you will ++have to investigate yourself; or perhaps you will have to use ++@code{buffer-substring-no-properties} or ++@code{filter-buffer-substring} @dots{}, yet other functions. Text ++properties are a feature otherwise not discussed here. @xref{Text ++Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference ++Manual}.) ++ ++Additionally, do you really need @code{goto-char} or @code{point-min}? ++Or can you write the function without them? ++ ++@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top ++@comment node-name, next, previous, up ++@chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions ++@findex car, @r{introduced} ++@findex cdr, @r{introduced} ++ ++In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental ++functions. The @code{cons} function is used to construct lists, and ++the @code{car} and @code{cdr} functions are used to take them apart. ++ ++In the walk through of the @code{copy-region-as-kill} function, we ++will see @code{cons} as well as two variants on @code{cdr}, ++namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) ++ ++@menu ++* Strange Names:: An historical aside: why the strange names? ++* car & cdr:: Functions for extracting part of a list. ++* cons:: Constructing a list. ++* nthcdr:: Calling @code{cdr} repeatedly. ++* nth:: ++* setcar:: Changing the first element of a list. ++* setcdr:: Changing the rest of a list. ++* cons Exercise:: ++@end menu ++ ++@node Strange Names, car & cdr, car cdr & cons, car cdr & cons ++@ifnottex ++@unnumberedsec Strange Names ++@end ifnottex ++ ++The name of the @code{cons} function is not unreasonable: it is an ++abbreviation of the word `construct'. The origins of the names for ++@code{car} and @code{cdr}, on the other hand, are esoteric: @code{car} ++is an acronym from the phrase `Contents of the Address part of the ++Register'; and @code{cdr} (pronounced `could-er') is an acronym from ++the phrase `Contents of the Decrement part of the Register'. These ++phrases refer to specific pieces of hardware on the very early ++computer on which the original Lisp was developed. Besides being ++obsolete, the phrases have been completely irrelevant for more than 25 ++years to anyone thinking about Lisp. Nonetheless, although a few ++brave scholars have begun to use more reasonable names for these ++functions, the old terms are still in use. In particular, since the ++terms are used in the Emacs Lisp source code, we will use them in this ++introduction. ++ ++@node car & cdr, cons, Strange Names, car cdr & cons ++@comment node-name, next, previous, up ++@section @code{car} and @code{cdr} ++ ++The @sc{car} of a list is, quite simply, the first item in the list. ++Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is ++@code{rose}. ++ ++@need 1200 ++If you are reading this in Info in GNU Emacs, you can see this by ++evaluating the following: ++ ++@smallexample ++(car '(rose violet daisy buttercup)) ++@end smallexample ++ ++@noindent ++After evaluating the expression, @code{rose} will appear in the echo ++area. ++ ++Clearly, a more reasonable name for the @code{car} function would be ++@code{first} and this is often suggested. ++ ++@code{car} does not remove the first item from the list; it only reports ++what it is. After @code{car} has been applied to a list, the list is ++still the same as it was. In the jargon, @code{car} is ++`non-destructive'. This feature turns out to be important. ++ ++The @sc{cdr} of a list is the rest of the list, that is, the ++@code{cdr} function returns the part of the list that follows the ++first item. Thus, while the @sc{car} of the list @code{'(rose violet ++daisy buttercup)} is @code{rose}, the rest of the list, the value ++returned by the @code{cdr} function, is @code{(violet daisy ++buttercup)}. ++ ++@need 800 ++You can see this by evaluating the following in the usual way: ++ ++@smallexample ++(cdr '(rose violet daisy buttercup)) ++@end smallexample ++ ++@noindent ++When you evaluate this, @code{(violet daisy buttercup)} will appear in ++the echo area. ++ ++Like @code{car}, @code{cdr} does not remove any elements from the ++list---it just returns a report of what the second and subsequent ++elements are. ++ ++Incidentally, in the example, the list of flowers is quoted. If it were ++not, the Lisp interpreter would try to evaluate the list by calling ++@code{rose} as a function. In this example, we do not want to do that. ++ ++Clearly, a more reasonable name for @code{cdr} would be @code{rest}. ++ ++(There is a lesson here: when you name new functions, consider very ++carefully what you are doing, since you may be stuck with the names ++for far longer than you expect. The reason this document perpetuates ++these names is that the Emacs Lisp source code uses them, and if I did ++not use them, you would have a hard time reading the code; but do, ++please, try to avoid using these terms yourself. The people who come ++after you will be grateful to you.) ++ ++When @code{car} and @code{cdr} are applied to a list made up of symbols, ++such as the list @code{(pine fir oak maple)}, the element of the list ++returned by the function @code{car} is the symbol @code{pine} without ++any parentheses around it. @code{pine} is the first element in the ++list. However, the @sc{cdr} of the list is a list itself, @code{(fir ++oak maple)}, as you can see by evaluating the following expressions in ++the usual way: ++ ++@smallexample ++@group ++(car '(pine fir oak maple)) ++ ++(cdr '(pine fir oak maple)) ++@end group ++@end smallexample ++ ++On the other hand, in a list of lists, the first element is itself a ++list. @code{car} returns this first element as a list. For example, ++the following list contains three sub-lists, a list of carnivores, a ++list of herbivores and a list of sea mammals: ++ ++@smallexample ++@group ++(car '((lion tiger cheetah) ++ (gazelle antelope zebra) ++ (whale dolphin seal))) ++@end group ++@end smallexample ++ ++@noindent ++In this example, the first element or @sc{car} of the list is the list of ++carnivores, @code{(lion tiger cheetah)}, and the rest of the list is ++@code{((gazelle antelope zebra) (whale dolphin seal))}. ++ ++@smallexample ++@group ++(cdr '((lion tiger cheetah) ++ (gazelle antelope zebra) ++ (whale dolphin seal))) ++@end group ++@end smallexample ++ ++It is worth saying again that @code{car} and @code{cdr} are ++non-destructive---that is, they do not modify or change lists to which ++they are applied. This is very important for how they are used. ++ ++Also, in the first chapter, in the discussion about atoms, I said that ++in Lisp, ``certain kinds of atom, such as an array, can be separated ++into parts; but the mechanism for doing this is different from the ++mechanism for splitting a list. As far as Lisp is concerned, the ++atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The ++@code{car} and @code{cdr} functions are used for splitting lists and ++are considered fundamental to Lisp. Since they cannot split or gain ++access to the parts of an array, an array is considered an atom. ++Conversely, the other fundamental function, @code{cons}, can put ++together or construct a list, but not an array. (Arrays are handled ++by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU ++Emacs Lisp Reference Manual}.) ++ ++@node cons, nthcdr, car & cdr, car cdr & cons ++@comment node-name, next, previous, up ++@section @code{cons} ++@findex cons, @r{introduced} ++ ++The @code{cons} function constructs lists; it is the inverse of ++@code{car} and @code{cdr}. For example, @code{cons} can be used to make ++a four element list from the three element list, @code{(fir oak maple)}: ++ ++@smallexample ++(cons 'pine '(fir oak maple)) ++@end smallexample ++ ++@need 800 ++@noindent ++After evaluating this list, you will see ++ ++@smallexample ++(pine fir oak maple) ++@end smallexample ++ ++@noindent ++appear in the echo area. @code{cons} causes the creation of a new ++list in which the element is followed by the elements of the original ++list. ++ ++We often say that `@code{cons} puts a new element at the beginning of ++a list; it attaches or pushes elements onto the list', but this ++phrasing can be misleading, since @code{cons} does not change an ++existing list, but creates a new one. ++ ++Like @code{car} and @code{cdr}, @code{cons} is non-destructive. ++ ++@menu ++* Build a list:: ++* length:: How to find the length of a list. ++@end menu ++ ++@node Build a list, length, cons, cons ++@ifnottex ++@unnumberedsubsec Build a list ++@end ifnottex ++ ++@code{cons} must have a list to attach to.@footnote{Actually, you can ++@code{cons} an element to an atom to produce a dotted pair. Dotted ++pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted ++Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You ++cannot start from absolutely nothing. If you are building a list, you ++need to provide at least an empty list at the beginning. Here is a ++series of @code{cons} expressions that build up a list of flowers. If ++you are reading this in Info in GNU Emacs, you can evaluate each of ++the expressions in the usual way; the value is printed in this text ++after @samp{@result{}}, which you may read as `evaluates to'. ++ ++@smallexample ++@group ++(cons 'buttercup ()) ++ @result{} (buttercup) ++@end group ++ ++@group ++(cons 'daisy '(buttercup)) ++ @result{} (daisy buttercup) ++@end group ++ ++@group ++(cons 'violet '(daisy buttercup)) ++ @result{} (violet daisy buttercup) ++@end group ++ ++@group ++(cons 'rose '(violet daisy buttercup)) ++ @result{} (rose violet daisy buttercup) ++@end group ++@end smallexample ++ ++@noindent ++In the first example, the empty list is shown as @code{()} and a list ++made up of @code{buttercup} followed by the empty list is constructed. ++As you can see, the empty list is not shown in the list that was ++constructed. All that you see is @code{(buttercup)}. The empty list is ++not counted as an element of a list because there is nothing in an empty ++list. Generally speaking, an empty list is invisible. ++ ++The second example, @code{(cons 'daisy '(buttercup))} constructs a new, ++two element list by putting @code{daisy} in front of @code{buttercup}; ++and the third example constructs a three element list by putting ++@code{violet} in front of @code{daisy} and @code{buttercup}. ++ ++@node length, , Build a list, cons ++@comment node-name, next, previous, up ++@subsection Find the Length of a List: @code{length} ++@findex length ++ ++You can find out how many elements there are in a list by using the Lisp ++function @code{length}, as in the following examples: ++ ++@smallexample ++@group ++(length '(buttercup)) ++ @result{} 1 ++@end group ++ ++@group ++(length '(daisy buttercup)) ++ @result{} 2 ++@end group ++ ++@group ++(length (cons 'violet '(daisy buttercup))) ++ @result{} 3 ++@end group ++@end smallexample ++ ++@noindent ++In the third example, the @code{cons} function is used to construct a ++three element list which is then passed to the @code{length} function as ++its argument. ++ ++@need 1200 ++We can also use @code{length} to count the number of elements in an ++empty list: ++ ++@smallexample ++@group ++(length ()) ++ @result{} 0 ++@end group ++@end smallexample ++ ++@noindent ++As you would expect, the number of elements in an empty list is zero. ++ ++An interesting experiment is to find out what happens if you try to find ++the length of no list at all; that is, if you try to call @code{length} ++without giving it an argument, not even an empty list: ++ ++@smallexample ++(length ) ++@end smallexample ++ ++@need 800 ++@noindent ++What you see, if you evaluate this, is the error message ++ ++@smallexample ++Lisp error: (wrong-number-of-arguments length 0) ++@end smallexample ++ ++@noindent ++This means that the function receives the wrong number of ++arguments, zero, when it expects some other number of arguments. In ++this case, one argument is expected, the argument being a list whose ++length the function is measuring. (Note that @emph{one} list is ++@emph{one} argument, even if the list has many elements inside it.) ++ ++The part of the error message that says @samp{length} is the name of ++the function. ++ ++@ignore ++@code{length} is still a subroutine, but you need C-h f to discover that. ++ ++In an earlier version: ++ This is written with a special notation, @samp{# (length string) 0) ++ (if yank-handler ++ (put-text-property 0 (length string) ++ 'yank-handler yank-handler string)) ++ (if yank-handler ++ (signal 'args-out-of-range ++ (list string "yank-handler specified for empty string")))) ++@end group ++@group ++ (if (fboundp 'menu-bar-update-yank-menu) ++ (menu-bar-update-yank-menu string (and replace (car kill-ring)))) ++@end group ++@group ++ (if (and replace kill-ring) ++ (setcar kill-ring string) ++ (push string kill-ring) ++ (if (> (length kill-ring) kill-ring-max) ++ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) ++@end group ++@group ++ (setq kill-ring-yank-pointer kill-ring) ++ (if interprogram-cut-function ++ (funcall interprogram-cut-function string (not replace)))) ++@end group ++@end smallexample ++@ignore ++was: ++(defun kill-new (string &optional replace) ++ "Make STRING the latest kill in the kill ring. ++Set the kill-ring-yank pointer to point to it. ++If `interprogram-cut-function' is non-nil, apply it to STRING. ++Optional second argument REPLACE non-nil means that STRING will replace ++the front of the kill ring, rather than being added to the list." ++ (and (fboundp 'menu-bar-update-yank-menu) ++ (menu-bar-update-yank-menu string (and replace (car kill-ring)))) ++ (if (and replace kill-ring) ++ (setcar kill-ring string) ++ (setq kill-ring (cons string kill-ring)) ++ (if (> (length kill-ring) kill-ring-max) ++ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) ++ (setq kill-ring-yank-pointer kill-ring) ++ (if interprogram-cut-function ++ (funcall interprogram-cut-function string (not replace)))) ++@end ignore ++ ++(Notice that the function is not interactive.) ++ ++As usual, we can look at this function in parts. ++ ++The function definition has an optional @code{yank-handler} argument, ++which when invoked tells the function how to deal with properties ++added to the text, such as `bold' or `italics'. We will skip that. ++ ++@need 1200 ++The first line of the documentation makes sense: ++ ++@smallexample ++Make STRING the latest kill in the kill ring. ++@end smallexample ++ ++@noindent ++Let's skip over the rest of the documentation for the moment. ++ ++@noindent ++Also, let's skip over the initial @code{if} expression and those lines ++of code involving @code{menu-bar-update-yank-menu}. We will explain ++them below. ++ ++@need 1200 ++The critical lines are these: ++ ++@smallexample ++@group ++ (if (and replace kill-ring) ++ ;; @r{then} ++ (setcar kill-ring string) ++@end group ++@group ++ ;; @r{else} ++ (push string kill-ring) ++@end group ++@group ++ (setq kill-ring (cons string kill-ring)) ++ (if (> (length kill-ring) kill-ring-max) ++ ;; @r{avoid overly long kill ring} ++ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) ++@end group ++@group ++ (setq kill-ring-yank-pointer kill-ring) ++ (if interprogram-cut-function ++ (funcall interprogram-cut-function string (not replace)))) ++@end group ++@end smallexample ++ ++The conditional test is @w{@code{(and replace kill-ring)}}. ++This will be true when two conditions are met: the kill ring has ++something in it, and the @code{replace} variable is true. ++ ++@need 1250 ++When the @code{kill-append} function sets @code{replace} to be true ++and when the kill ring has at least one item in it, the @code{setcar} ++expression is executed: ++ ++@smallexample ++(setcar kill-ring string) ++@end smallexample ++ ++The @code{setcar} function actually changes the first element of the ++@code{kill-ring} list to the value of @code{string}. It replaces the ++first element. ++ ++@need 1250 ++On the other hand, if the kill ring is empty, or replace is false, the ++else-part of the condition is executed: ++ ++@smallexample ++(push string kill-ring) ++@end smallexample ++ ++@noindent ++@need 1250 ++@code{push} puts its first argument onto the second. It is similar to ++the older ++ ++@smallexample ++(setq kill-ring (cons string kill-ring)) ++@end smallexample ++ ++@noindent ++@need 1250 ++or the newer ++ ++@smallexample ++(add-to-list kill-ring string) ++@end smallexample ++ ++@noindent ++When it is false, the expression first constructs a new version of the ++kill ring by prepending @code{string} to the existing kill ring as a ++new element (that is what the @code{push} does). Then it executes a ++second @code{if} clause. This second @code{if} clause keeps the kill ++ring from growing too long. ++ ++Let's look at these two expressions in order. ++ ++The @code{push} line of the else-part sets the new value of the kill ++ring to what results from adding the string being killed to the old ++kill ring. ++ ++We can see how this works with an example. ++ ++@need 800 ++First, ++ ++@smallexample ++(setq example-list '("here is a clause" "another clause")) ++@end smallexample ++ ++@need 1200 ++@noindent ++After evaluating this expression with @kbd{C-x C-e}, you can evaluate ++@code{example-list} and see what it returns: ++ ++@smallexample ++@group ++example-list ++ @result{} ("here is a clause" "another clause") ++@end group ++@end smallexample ++ ++@need 1200 ++@noindent ++Now, we can add a new element on to this list by evaluating the ++following expression: ++@findex push, @r{example} ++ ++@smallexample ++(push "a third clause" example-list) ++@end smallexample ++ ++@need 800 ++@noindent ++When we evaluate @code{example-list}, we find its value is: ++ ++@smallexample ++@group ++example-list ++ @result{} ("a third clause" "here is a clause" "another clause") ++@end group ++@end smallexample ++ ++@noindent ++Thus, the third clause is added to the list by @code{push}. ++ ++@need 1200 ++Now for the second part of the @code{if} clause. This expression ++keeps the kill ring from growing too long. It looks like this: ++ ++@smallexample ++@group ++(if (> (length kill-ring) kill-ring-max) ++ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)) ++@end group ++@end smallexample ++ ++The code checks whether the length of the kill ring is greater than ++the maximum permitted length. This is the value of ++@code{kill-ring-max} (which is 60, by default). If the length of the ++kill ring is too long, then this code sets the last element of the ++kill ring to @code{nil}. It does this by using two functions, ++@code{nthcdr} and @code{setcdr}. ++ ++We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}). ++It sets the @sc{cdr} of a list, just as @code{setcar} sets the ++@sc{car} of a list. In this case, however, @code{setcdr} will not be ++setting the @sc{cdr} of the whole kill ring; the @code{nthcdr} ++function is used to cause it to set the @sc{cdr} of the next to last ++element of the kill ring---this means that since the @sc{cdr} of the ++next to last element is the last element of the kill ring, it will set ++the last element of the kill ring. ++ ++@findex nthcdr, @r{example} ++The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a ++list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr} ++@dots{} It does this @var{N} times and returns the results. ++(@xref{nthcdr, , @code{nthcdr}}.) ++ ++@findex setcdr, @r{example} ++Thus, if we had a four element list that was supposed to be three ++elements long, we could set the @sc{cdr} of the next to last element ++to @code{nil}, and thereby shorten the list. (If you set the last ++element to some other value than @code{nil}, which you could do, then ++you would not have shortened the list. @xref{setcdr, , ++@code{setcdr}}.) ++ ++You can see shortening by evaluating the following three expressions ++in turn. First set the value of @code{trees} to @code{(maple oak pine ++birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil} ++and then find the value of @code{trees}: ++ ++@smallexample ++@group ++(setq trees '(maple oak pine birch)) ++ @result{} (maple oak pine birch) ++@end group ++ ++@group ++(setcdr (nthcdr 2 trees) nil) ++ @result{} nil ++ ++trees ++ @result{} (maple oak pine) ++@end group ++@end smallexample ++ ++@noindent ++(The value returned by the @code{setcdr} expression is @code{nil} since ++that is what the @sc{cdr} is set to.) ++ ++To repeat, in @code{kill-new}, the @code{nthcdr} function takes the ++@sc{cdr} a number of times that is one less than the maximum permitted ++size of the kill ring and @code{setcdr} sets the @sc{cdr} of that ++element (which will be the rest of the elements in the kill ring) to ++@code{nil}. This prevents the kill ring from growing too long. ++ ++@need 800 ++The next to last expression in the @code{kill-new} function is ++ ++@smallexample ++(setq kill-ring-yank-pointer kill-ring) ++@end smallexample ++ ++The @code{kill-ring-yank-pointer} is a global variable that is set to be ++the @code{kill-ring}. ++ ++Even though the @code{kill-ring-yank-pointer} is called a ++@samp{pointer}, it is a variable just like the kill ring. However, the ++name has been chosen to help humans understand how the variable is used. ++ ++@need 1200 ++Now, to return to an early expression in the body of the function: ++ ++@smallexample ++@group ++ (if (fboundp 'menu-bar-update-yank-menu) ++ (menu-bar-update-yank-menu string (and replace (car kill-ring)))) ++@end group ++@end smallexample ++ ++@noindent ++It starts with an @code{if} expression ++ ++In this case, the expression tests first to see whether ++@code{menu-bar-update-yank-menu} exists as a function, and if so, ++calls it. The @code{fboundp} function returns true if the symbol it ++is testing has a function definition that `is not void'. If the ++symbol's function definition were void, we would receive an error ++message, as we did when we created errors intentionally (@pxref{Making ++Errors, , Generate an Error Message}). ++ ++@noindent ++The then-part contains an expression whose first element is the ++function @code{and}. ++ ++@findex and ++The @code{and} special form evaluates each of its arguments until one ++of the arguments returns a value of @code{nil}, in which case the ++@code{and} expression returns @code{nil}; however, if none of the ++arguments returns a value of @code{nil}, the value resulting from ++evaluating the last argument is returned. (Since such a value is not ++@code{nil}, it is considered true in Emacs Lisp.) In other words, an ++@code{and} expression returns a true value only if all its arguments ++are true. (@xref{Second Buffer Related Review}.) ++ ++The expression determines whether the second argument to ++@code{menu-bar-update-yank-menu} is true or not. ++@ignore ++ ;; If we're supposed to be extending an existing string, and that ++ ;; string really is at the front of the menu, then update it in place. ++@end ignore ++ ++@code{menu-bar-update-yank-menu} is one of the functions that make it ++possible to use the `Select and Paste' menu in the Edit item of a menu ++bar; using a mouse, you can look at the various pieces of text you ++have saved and select one piece to paste. ++ ++The last expression in the @code{kill-new} function adds the newly ++copied string to whatever facility exists for copying and pasting ++among different programs running in a windowing system. In the X ++Windowing system, for example, the @code{x-select-text} function takes ++the string and stores it in memory operated by X. You can paste the ++string in another program, such as an Xterm. ++ ++@need 1200 ++The expression looks like this: ++ ++@smallexample ++@group ++ (if interprogram-cut-function ++ (funcall interprogram-cut-function string (not replace)))) ++@end group ++@end smallexample ++ ++If an @code{interprogram-cut-function} exists, then Emacs executes ++@code{funcall}, which in turn calls its first argument as a function ++and passes the remaining arguments to it. (Incidentally, as far as I ++can see, this @code{if} expression could be replaced by an @code{and} ++expression similar to the one in the first part of the function.) ++ ++We are not going to discuss windowing systems and other programs ++further, but merely note that this is a mechanism that enables GNU ++Emacs to work easily and well with other programs. ++ ++This code for placing text in the kill ring, either concatenated with ++an existing element or as a new element, leads us to the code for ++bringing back text that has been cut out of the buffer---the yank ++commands. However, before discussing the yank commands, it is better ++to learn how lists are implemented in a computer. This will make ++clear such mysteries as the use of the term `pointer'. But before ++that, we will digress into C. ++ ++@ignore ++@c is this true in Emacs 22? Does not seems to be ++ ++ (If the @w{@code{(< end beg))}} ++expression is true, @code{kill-append} prepends the string to the just ++previously clipped text. For a detailed discussion, see ++@ref{kill-append function, , The @code{kill-append} function}.) ++ ++If you then yank back the text, i.e., `paste' it, you get both ++pieces of text at once. That way, if you delete two words in a row, ++and then yank them back, you get both words, in their proper order, ++with one yank. (The @w{@code{(< end beg))}} expression makes sure the ++order is correct.) ++ ++On the other hand, if the previous command is not @code{kill-region}, ++then the @code{kill-new} function is called, which adds the text to ++the kill ring as the latest item, and sets the ++@code{kill-ring-yank-pointer} variable to point to it. ++@end ignore ++@ignore ++ ++@c Evidently, changed for Emacs 22. The zap-to-char command does not ++@c use the delete-and-extract-region function ++ ++2006 Oct 26, the Digression into C is now OK but should come after ++copy-region-as-kill and filter-buffer-substring ++ ++2006 Oct 24 ++In Emacs 22, ++copy-region-as-kill is short, 12 lines, and uses ++filter-buffer-substring, which is longer, 39 lines ++and has delete-and-extract-region in it. ++delete-and-extract-region is written in C. ++ ++see Initializing a Variable with @code{defvar} ++@end ignore ++ ++@node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text ++@comment node-name, next, previous, up ++@section Digression into C ++@findex delete-and-extract-region ++@cindex C, a digression into ++@cindex Digression into C ++ ++The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, , ++@code{copy-region-as-kill}}) uses the @code{filter-buffer-substring} ++function, which in turn uses the @code{delete-and-extract-region} ++function. It removes the contents of a region and you cannot get them ++back. ++ ++Unlike the other code discussed here, the ++@code{delete-and-extract-region} function is not written in Emacs ++Lisp; it is written in C and is one of the primitives of the GNU Emacs ++system. Since it is very simple, I will digress briefly from Lisp and ++describe it here. ++ ++@c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c ++@c the DEFUN for buffer-substring-no-properties ++ ++@need 1500 ++Like many of the other Emacs primitives, ++@code{delete-and-extract-region} is written as an instance of a C ++macro, a macro being a template for code. The complete macro looks ++like this: ++ ++@smallexample ++@group ++DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties, ++ Sbuffer_substring_no_properties, 2, 2, 0, ++ doc: /* Return the characters of part of the buffer, ++without the text properties. ++The two arguments START and END are character positions; ++they can be in either order. */) ++ (start, end) ++ Lisp_Object start, end; ++@{ ++ register int b, e; ++ ++ validate_region (&start, &end); ++ b = XINT (start); ++ e = XINT (end); ++ ++ return make_buffer_string (b, e, 0); ++@} ++@end group ++@end smallexample ++ ++Without going into the details of the macro writing process, let me ++point out that this macro starts with the word @code{DEFUN}. The word ++@code{DEFUN} was chosen since the code serves the same purpose as ++@code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in ++@file{emacs/src/lisp.h}.) ++ ++The word @code{DEFUN} is followed by seven parts inside of ++parentheses: ++ ++@itemize @bullet ++@item ++The first part is the name given to the function in Lisp, ++@code{delete-and-extract-region}. ++ ++@item ++The second part is the name of the function in C, ++@code{Fdelete_and_extract_region}. By convention, it starts with ++@samp{F}. Since C does not use hyphens in names, underscores are used ++instead. ++ ++@item ++The third part is the name for the C constant structure that records ++information on this function for internal use. It is the name of the ++function in C but begins with an @samp{S} instead of an @samp{F}. ++ ++@item ++The fourth and fifth parts specify the minimum and maximum number of ++arguments the function can have. This function demands exactly 2 ++arguments. ++ ++@item ++The sixth part is nearly like the argument that follows the ++@code{interactive} declaration in a function written in Lisp: a letter ++followed, perhaps, by a prompt. The only difference from the Lisp is ++when the macro is called with no arguments. Then you write a @code{0} ++(which is a `null string'), as in this macro. ++ ++If you were to specify arguments, you would place them between ++quotation marks. The C macro for @code{goto-char} includes ++@code{"NGoto char: "} in this position to indicate that the function ++expects a raw prefix, in this case, a numerical location in a buffer, ++and provides a prompt. ++ ++@item ++The seventh part is a documentation string, just like the one for a ++function written in Emacs Lisp, except that every newline must be ++written explicitly as @samp{\n} followed by a backslash and carriage ++return. ++ ++@need 1000 ++Thus, the first two lines of documentation for @code{goto-char} are ++written like this: ++ ++@smallexample ++@group ++ "Set point to POSITION, a number or marker.\n\ ++Beginning of buffer is position (point-min), end is (point-max)." ++@end group ++@end smallexample ++@end itemize ++ ++@need 1200 ++In a C macro, the formal parameters come next, with a statement of ++what kind of object they are, followed by what might be called the `body' ++of the macro. For @code{delete-and-extract-region} the `body' ++consists of the following four lines: ++ ++@smallexample ++@group ++validate_region (&start, &end); ++if (XINT (start) == XINT (end)) ++ return build_string (""); ++return del_range_1 (XINT (start), XINT (end), 1, 1); ++@end group ++@end smallexample ++ ++The @code{validate_region} function checks whether the values ++passed as the beginning and end of the region are the proper type and ++are within range. If the beginning and end positions are the same, ++then return and empty string. ++ ++The @code{del_range_1} function actually deletes the text. It is a ++complex function we will not look into. It updates the buffer and ++does other things. However, it is worth looking at the two arguments ++passed to @code{del_range}. These are @w{@code{XINT (start)}} and ++@w{@code{XINT (end)}}. ++ ++As far as the C language is concerned, @code{start} and @code{end} are ++two integers that mark the beginning and end of the region to be ++deleted@footnote{More precisely, and requiring more expert knowledge ++to understand, the two integers are of type `Lisp_Object', which can ++also be a C union instead of an integer type.}. ++ ++In early versions of Emacs, these two numbers were thirty-two bits ++long, but the code is slowly being generalized to handle other ++lengths. Three of the available bits are used to specify the type of ++information; the remaining bits are used as `content'. ++ ++@samp{XINT} is a C macro that extracts the relevant number from the ++longer collection of bits; the three other bits are discarded. ++ ++@need 800 ++The command in @code{delete-and-extract-region} looks like this: ++ ++@smallexample ++del_range_1 (XINT (start), XINT (end), 1, 1); ++@end smallexample ++ ++@noindent ++It deletes the region between the beginning position, @code{start}, ++and the ending position, @code{end}. ++ ++From the point of view of the person writing Lisp, Emacs is all very ++simple; but hidden underneath is a great deal of complexity to make it ++all work. ++ ++@node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text ++@comment node-name, next, previous, up ++@section Initializing a Variable with @code{defvar} ++@findex defvar ++@cindex Initializing a variable ++@cindex Variable initialization ++ ++@ignore ++2006 Oct 24 ++In Emacs 22, ++copy-region-as-kill is short, 12 lines, and uses ++filter-buffer-substring, which is longer, 39 lines ++and has delete-and-extract-region in it. ++delete-and-extract-region is written in C. ++ ++see Initializing a Variable with @code{defvar} ++ ++@end ignore ++ ++The @code{copy-region-as-kill} function is written in Emacs Lisp. Two ++functions within it, @code{kill-append} and @code{kill-new}, copy a ++region in a buffer and save it in a variable called the ++@code{kill-ring}. This section describes how the @code{kill-ring} ++variable is created and initialized using the @code{defvar} special ++form. ++ ++(Again we note that the term @code{kill-ring} is a misnomer. The text ++that is clipped out of the buffer can be brought back; it is not a ring ++of corpses, but a ring of resurrectable text.) ++ ++In Emacs Lisp, a variable such as the @code{kill-ring} is created and ++given an initial value by using the @code{defvar} special form. The ++name comes from ``define variable''. ++ ++The @code{defvar} special form is similar to @code{setq} in that it sets ++the value of a variable. It is unlike @code{setq} in two ways: first, ++it only sets the value of the variable if the variable does not already ++have a value. If the variable already has a value, @code{defvar} does ++not override the existing value. Second, @code{defvar} has a ++documentation string. ++ ++(Another special form, @code{defcustom}, is designed for variables ++that people customize. It has more features than @code{defvar}. ++(@xref{defcustom, , Setting Variables with @code{defcustom}}.) ++ ++@menu ++* See variable current value:: ++* defvar and asterisk:: ++@end menu ++ ++@node See variable current value, defvar and asterisk, defvar, defvar ++@ifnottex ++@unnumberedsubsec Seeing the Current Value of a Variable ++@end ifnottex ++ ++You can see the current value of a variable, any variable, by using ++the @code{describe-variable} function, which is usually invoked by ++typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring} ++(followed by @key{RET}) when prompted, you will see what is in your ++current kill ring---this may be quite a lot! Conversely, if you have ++been doing nothing this Emacs session except read this document, you ++may have nothing in it. Also, you will see the documentation for ++@code{kill-ring}: ++ ++@smallexample ++@group ++Documentation: ++List of killed text sequences. ++Since the kill ring is supposed to interact nicely with cut-and-paste ++facilities offered by window systems, use of this variable should ++@end group ++@group ++interact nicely with `interprogram-cut-function' and ++`interprogram-paste-function'. The functions `kill-new', ++`kill-append', and `current-kill' are supposed to implement this ++interaction; you may want to use them instead of manipulating the kill ++ring directly. ++@end group ++@end smallexample ++ ++@need 800 ++The kill ring is defined by a @code{defvar} in the following way: ++ ++@smallexample ++@group ++(defvar kill-ring nil ++ "List of killed text sequences. ++@dots{}") ++@end group ++@end smallexample ++ ++@noindent ++In this variable definition, the variable is given an initial value of ++@code{nil}, which makes sense, since if you have saved nothing, you want ++nothing back if you give a @code{yank} command. The documentation ++string is written just like the documentation string of a @code{defun}. ++As with the documentation string of the @code{defun}, the first line of ++the documentation should be a complete sentence, since some commands, ++like @code{apropos}, print only the first line of documentation. ++Succeeding lines should not be indented; otherwise they look odd when ++you use @kbd{C-h v} (@code{describe-variable}). ++ ++@node defvar and asterisk, , See variable current value, defvar ++@subsection @code{defvar} and an asterisk ++@findex defvar @r{for a user customizable variable} ++@findex defvar @r{with an asterisk} ++ ++In the past, Emacs used the @code{defvar} special form both for ++internal variables that you would not expect a user to change and for ++variables that you do expect a user to change. Although you can still ++use @code{defvar} for user customizable variables, please use ++@code{defcustom} instead, since that special form provides a path into ++the Customization commands. (@xref{defcustom, , Specifying Variables ++using @code{defcustom}}.) ++ ++When you specified a variable using the @code{defvar} special form, ++you could distinguish a variable that a user might want to change from ++others by typing an asterisk, @samp{*}, in the first column of its ++documentation string. For example: ++ ++@smallexample ++@group ++(defvar shell-command-default-error-buffer nil ++ "*Buffer name for `shell-command' @dots{} error output. ++@dots{} ") ++@end group ++@end smallexample ++ ++@findex set-variable ++@noindent ++You could (and still can) use the @code{set-variable} command to ++change the value of @code{shell-command-default-error-buffer} ++temporarily. However, options set using @code{set-variable} are set ++only for the duration of your editing session. The new values are not ++saved between sessions. Each time Emacs starts, it reads the original ++value, unless you change the value within your @file{.emacs} file, ++either by setting it manually or by using @code{customize}. ++@xref{Emacs Initialization, , Your @file{.emacs} File}. ++ ++For me, the major use of the @code{set-variable} command is to suggest ++variables that I might want to set in my @file{.emacs} file. There ++are now more than 700 such variables --- far too many to remember ++readily. Fortunately, you can press @key{TAB} after calling the ++@code{M-x set-variable} command to see the list of variables. ++(@xref{Examining, , Examining and Setting Variables, emacs, ++The GNU Emacs Manual}.) ++ ++@need 1250 ++@node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text ++@comment node-name, next, previous, up ++@section Review ++ ++Here is a brief summary of some recently introduced functions. ++ ++@table @code ++@item car ++@itemx cdr ++@code{car} returns the first element of a list; @code{cdr} returns the ++second and subsequent elements of a list. ++ ++@need 1250 ++For example: ++ ++@smallexample ++@group ++(car '(1 2 3 4 5 6 7)) ++ @result{} 1 ++(cdr '(1 2 3 4 5 6 7)) ++ @result{} (2 3 4 5 6 7) ++@end group ++@end smallexample ++ ++@item cons ++@code{cons} constructs a list by prepending its first argument to its ++second argument. ++ ++@need 1250 ++For example: ++ ++@smallexample ++@group ++(cons 1 '(2 3 4)) ++ @result{} (1 2 3 4) ++@end group ++@end smallexample ++ ++@item funcall ++@code{funcall} evaluates its first argument as a function. It passes ++its remaining arguments to its first argument. ++ ++@item nthcdr ++Return the result of taking @sc{cdr} `n' times on a list. ++@iftex ++The ++@tex ++$n^{th}$ ++@end tex ++@code{cdr}. ++@end iftex ++The `rest of the rest', as it were. ++ ++@need 1250 ++For example: ++ ++@smallexample ++@group ++(nthcdr 3 '(1 2 3 4 5 6 7)) ++ @result{} (4 5 6 7) ++@end group ++@end smallexample ++ ++@item setcar ++@itemx setcdr ++@code{setcar} changes the first element of a list; @code{setcdr} ++changes the second and subsequent elements of a list. ++ ++@need 1250 ++For example: ++ ++@smallexample ++@group ++(setq triple '(1 2 3)) ++ ++(setcar triple '37) ++ ++triple ++ @result{} (37 2 3) ++ ++(setcdr triple '("foo" "bar")) ++ ++triple ++ @result{} (37 "foo" "bar") ++@end group ++@end smallexample ++ ++@item progn ++Evaluate each argument in sequence and then return the value of the ++last. ++ ++@need 1250 ++For example: ++ ++@smallexample ++@group ++(progn 1 2 3 4) ++ @result{} 4 ++@end group ++@end smallexample ++ ++@item save-restriction ++Record whatever narrowing is in effect in the current buffer, if any, ++and restore that narrowing after evaluating the arguments. ++ ++@item search-forward ++Search for a string, and if the string is found, move point. With a ++regular expression, use the similar @code{re-search-forward}. ++(@xref{Regexp Search, , Regular Expression Searches}, for an ++explanation of regular expression patterns and searches.) ++ ++@need 1250 ++@noindent ++@code{search-forward} and @code{re-search-forward} take four ++arguments: ++ ++@enumerate ++@item ++The string or regular expression to search for. ++ ++@item ++Optionally, the limit of the search. ++ ++@item ++Optionally, what to do if the search fails, return @code{nil} or an ++error message. ++ ++@item ++Optionally, how many times to repeat the search; if negative, the ++search goes backwards. ++@end enumerate ++ ++@item kill-region ++@itemx delete-and-extract-region ++@itemx copy-region-as-kill ++ ++@code{kill-region} cuts the text between point and mark from the ++buffer and stores that text in the kill ring, so you can get it back ++by yanking. ++ ++@code{copy-region-as-kill} copies the text between point and mark into ++the kill ring, from which you can get it by yanking. The function ++does not cut or remove the text from the buffer. ++@end table ++ ++@code{delete-and-extract-region} removes the text between point and ++mark from the buffer and throws it away. You cannot get it back. ++(This is not an interactive command.) ++ ++@need 1500 ++@node search Exercises, , cons & search-fwd Review, Cutting & Storing Text ++@section Searching Exercises ++ ++@itemize @bullet ++@item ++Write an interactive function that searches for a string. If the ++search finds the string, leave point after it and display a message ++that says ``Found!''. (Do not use @code{search-forward} for the name ++of this function; if you do, you will overwrite the existing version of ++@code{search-forward} that comes with Emacs. Use a name such as ++@code{test-search} instead.) ++ ++@item ++Write a function that prints the third element of the kill ring in the ++echo area, if any; if the kill ring does not contain a third element, ++print an appropriate message. ++@end itemize ++ ++@node List Implementation, Yanking, Cutting & Storing Text, Top ++@comment node-name, next, previous, up ++@chapter How Lists are Implemented ++@cindex Lists in a computer ++ ++In Lisp, atoms are recorded in a straightforward fashion; if the ++implementation is not straightforward in practice, it is, nonetheless, ++straightforward in theory. The atom @samp{rose}, for example, is ++recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s}, ++@samp{e}. A list, on the other hand, is kept differently. The mechanism ++is equally simple, but it takes a moment to get used to the idea. A ++list is kept using a series of pairs of pointers. In the series, the ++first pointer in each pair points to an atom or to another list, and the ++second pointer in each pair points to the next pair, or to the symbol ++@code{nil}, which marks the end of the list. ++ ++A pointer itself is quite simply the electronic address of what is ++pointed to. Hence, a list is kept as a series of electronic addresses. ++ ++@menu ++* Lists diagrammed:: ++* Symbols as Chest:: Exploring a powerful metaphor. ++* List Exercise:: ++@end menu ++ ++@node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation ++@ifnottex ++@unnumberedsec Lists diagrammed ++@end ifnottex ++ ++For example, the list @code{(rose violet buttercup)} has three elements, ++@samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the ++electronic address of @samp{rose} is recorded in a segment of computer ++memory along with the address that gives the electronic address of where ++the atom @samp{violet} is located; and that address (the one that tells ++where @samp{violet} is located) is kept along with an address that tells ++where the address for the atom @samp{buttercup} is located. ++ ++@need 1200 ++This sounds more complicated than it is and is easier seen in a diagram: ++ ++@c clear print-postscript-figures ++@c !!! cons-cell-diagram #1 ++@ifnottex ++@smallexample ++@group ++ ___ ___ ___ ___ ___ ___ ++ |___|___|--> |___|___|--> |___|___|--> nil ++ | | | ++ | | | ++ --> rose --> violet --> buttercup ++@end group ++@end smallexample ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{cons-1} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@smallexample ++@group ++ ___ ___ ___ ___ ___ ___ ++ |___|___|--> |___|___|--> |___|___|--> nil ++ | | | ++ | | | ++ --> rose --> violet --> buttercup ++@end group ++@end smallexample ++@end iftex ++@end ifclear ++ ++@noindent ++In the diagram, each box represents a word of computer memory that ++holds a Lisp object, usually in the form of a memory address. The boxes, ++i.e.@: the addresses, are in pairs. Each arrow points to what the address ++is the address of, either an atom or another pair of addresses. The ++first box is the electronic address of @samp{rose} and the arrow points ++to @samp{rose}; the second box is the address of the next pair of boxes, ++the first part of which is the address of @samp{violet} and the second ++part of which is the address of the next pair. The very last box ++points to the symbol @code{nil}, which marks the end of the list. ++ ++@need 1200 ++When a variable is set to a list with a function such as @code{setq}, ++it stores the address of the first box in the variable. Thus, ++evaluation of the expression ++ ++@smallexample ++(setq bouquet '(rose violet buttercup)) ++@end smallexample ++ ++@need 1250 ++@noindent ++creates a situation like this: ++ ++@c cons-cell-diagram #2 ++@ifnottex ++@smallexample ++@group ++bouquet ++ | ++ | ___ ___ ___ ___ ___ ___ ++ --> |___|___|--> |___|___|--> |___|___|--> nil ++ | | | ++ | | | ++ --> rose --> violet --> buttercup ++@end group ++@end smallexample ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{cons-2} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@smallexample ++@group ++bouquet ++ | ++ | ___ ___ ___ ___ ___ ___ ++ --> |___|___|--> |___|___|--> |___|___|--> nil ++ | | | ++ | | | ++ --> rose --> violet --> buttercup ++@end group ++@end smallexample ++@end iftex ++@end ifclear ++ ++@noindent ++In this example, the symbol @code{bouquet} holds the address of the first ++pair of boxes. ++ ++@need 1200 ++This same list can be illustrated in a different sort of box notation ++like this: ++ ++@c cons-cell-diagram #2a ++@ifnottex ++@smallexample ++@group ++bouquet ++ | ++ | -------------- --------------- ---------------- ++ | | car | cdr | | car | cdr | | car | cdr | ++ -->| rose | o------->| violet | o------->| butter- | nil | ++ | | | | | | | cup | | ++ -------------- --------------- ---------------- ++@end group ++@end smallexample ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{cons-2a} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@smallexample ++@group ++bouquet ++ | ++ | -------------- --------------- ---------------- ++ | | car | cdr | | car | cdr | | car | cdr | ++ -->| rose | o------->| violet | o------->| butter- | nil | ++ | | | | | | | cup | | ++ -------------- --------------- ---------------- ++@end group ++@end smallexample ++@end iftex ++@end ifclear ++ ++(Symbols consist of more than pairs of addresses, but the structure of ++a symbol is made up of addresses. Indeed, the symbol @code{bouquet} ++consists of a group of address-boxes, one of which is the address of ++the printed word @samp{bouquet}, a second of which is the address of a ++function definition attached to the symbol, if any, a third of which ++is the address of the first pair of address-boxes for the list ++@code{(rose violet buttercup)}, and so on. Here we are showing that ++the symbol's third address-box points to the first pair of ++address-boxes for the list.) ++ ++If a symbol is set to the @sc{cdr} of a list, the list itself is not ++changed; the symbol simply has an address further down the list. (In ++the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus, ++evaluation of the following expression ++ ++@smallexample ++(setq flowers (cdr bouquet)) ++@end smallexample ++ ++@need 800 ++@noindent ++produces this: ++ ++@c cons-cell-diagram #3 ++@ifnottex ++@sp 1 ++@smallexample ++@group ++bouquet flowers ++ | | ++ | ___ ___ | ___ ___ ___ ___ ++ --> | | | --> | | | | | | ++ |___|___|----> |___|___|--> |___|___|--> nil ++ | | | ++ | | | ++ --> rose --> violet --> buttercup ++@end group ++@end smallexample ++@sp 1 ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{cons-3} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@sp 1 ++@smallexample ++@group ++bouquet flowers ++ | | ++ | ___ ___ | ___ ___ ___ ___ ++ --> | | | --> | | | | | | ++ |___|___|----> |___|___|--> |___|___|--> nil ++ | | | ++ | | | ++ --> rose --> violet --> buttercup ++@end group ++@end smallexample ++@sp 1 ++@end iftex ++@end ifclear ++ ++@noindent ++The value of @code{flowers} is @code{(violet buttercup)}, which is ++to say, the symbol @code{flowers} holds the address of the pair of ++address-boxes, the first of which holds the address of @code{violet}, ++and the second of which holds the address of @code{buttercup}. ++ ++A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted ++pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp ++Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair ++Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more ++information about cons cells and dotted pairs. ++ ++@need 1200 ++The function @code{cons} adds a new pair of addresses to the front of ++a series of addresses like that shown above. For example, evaluating ++the expression ++ ++@smallexample ++(setq bouquet (cons 'lily bouquet)) ++@end smallexample ++ ++@need 1500 ++@noindent ++produces: ++ ++@c cons-cell-diagram #4 ++@ifnottex ++@sp 1 ++@smallexample ++@group ++bouquet flowers ++ | | ++ | ___ ___ ___ ___ | ___ ___ ___ ___ ++ --> | | | | | | --> | | | | | | ++ |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil ++ | | | | ++ | | | | ++ --> lily --> rose --> violet --> buttercup ++@end group ++@end smallexample ++@sp 1 ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{cons-4} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@sp 1 ++@smallexample ++@group ++bouquet flowers ++ | | ++ | ___ ___ ___ ___ | ___ ___ ___ ___ ++ --> | | | | | | --> | | | | | | ++ |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil ++ | | | | ++ | | | | ++ --> lily --> rose --> violet --> buttercup ++@end group ++@end smallexample ++@sp 1 ++@end iftex ++@end ifclear ++ ++@need 1200 ++@noindent ++However, this does not change the value of the symbol ++@code{flowers}, as you can see by evaluating the following, ++ ++@smallexample ++(eq (cdr (cdr bouquet)) flowers) ++@end smallexample ++ ++@noindent ++which returns @code{t} for true. ++ ++Until it is reset, @code{flowers} still has the value ++@code{(violet buttercup)}; that is, it has the address of the cons ++cell whose first address is of @code{violet}. Also, this does not ++alter any of the pre-existing cons cells; they are all still there. ++ ++Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address ++of the next cons cell in the series; to get the @sc{car} of a list, ++you get the address of the first element of the list; to @code{cons} a ++new element on a list, you add a new cons cell to the front of the list. ++That is all there is to it! The underlying structure of Lisp is ++brilliantly simple! ++ ++And what does the last address in a series of cons cells refer to? It ++is the address of the empty list, of @code{nil}. ++ ++In summary, when a Lisp variable is set to a value, it is provided with ++the address of the list to which the variable refers. ++ ++@node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation ++@section Symbols as a Chest of Drawers ++@cindex Symbols as a Chest of Drawers ++@cindex Chest of Drawers, metaphor for a symbol ++@cindex Drawers, Chest of, metaphor for a symbol ++ ++In an earlier section, I suggested that you might imagine a symbol as ++being a chest of drawers. The function definition is put in one ++drawer, the value in another, and so on. What is put in the drawer ++holding the value can be changed without affecting the contents of the ++drawer holding the function definition, and vice-verse. ++ ++Actually, what is put in each drawer is the address of the value or ++function definition. It is as if you found an old chest in the attic, ++and in one of its drawers you found a map giving you directions to ++where the buried treasure lies. ++ ++(In addition to its name, symbol definition, and variable value, a ++symbol has a `drawer' for a @dfn{property list} which can be used to ++record other information. Property lists are not discussed here; see ++@ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp ++Reference Manual}.) ++ ++@need 1500 ++Here is a fanciful representation: ++ ++@c chest-of-drawers diagram ++@ifnottex ++@sp 1 ++@smallexample ++@group ++ Chest of Drawers Contents of Drawers ++ ++ __ o0O0o __ ++ / \ ++ --------------------- ++ | directions to | [map to] ++ | symbol name | bouquet ++ | | ++ +---------------------+ ++ | directions to | ++ | symbol definition | [none] ++ | | ++ +---------------------+ ++ | directions to | [map to] ++ | variable value | (rose violet buttercup) ++ | | ++ +---------------------+ ++ | directions to | ++ | property list | [not described here] ++ | | ++ +---------------------+ ++ |/ \| ++@end group ++@end smallexample ++@sp 1 ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{drawers} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@sp 1 ++@smallexample ++@group ++ Chest of Drawers Contents of Drawers ++ ++ __ o0O0o __ ++ / \ ++ --------------------- ++ | directions to | [map to] ++ | symbol name | bouquet ++ | | ++ +---------------------+ ++ | directions to | ++ | symbol definition | [none] ++ | | ++ +---------------------+ ++ | directions to | [map to] ++ | variable value | (rose violet buttercup) ++ | | ++ +---------------------+ ++ | directions to | ++ | property list | [not described here] ++ | | ++ +---------------------+ ++ |/ \| ++@end group ++@end smallexample ++@sp 1 ++@end iftex ++@end ifclear ++ ++@node List Exercise, , Symbols as Chest, List Implementation ++@section Exercise ++ ++Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two ++more flowers on to this list and set this new list to ++@code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish. ++What does the @code{more-flowers} list now contain? ++ ++@node Yanking, Loops & Recursion, List Implementation, Top ++@comment node-name, next, previous, up ++@chapter Yanking Text Back ++@findex yank ++@cindex Text retrieval ++@cindex Retrieving text ++@cindex Pasting text ++ ++Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, ++you can bring it back with a `yank' command. The text that is cut out of ++the buffer is put in the kill ring and the yank commands insert the ++appropriate contents of the kill ring back into a buffer (not necessarily ++the original buffer). ++ ++A simple @kbd{C-y} (@code{yank}) command inserts the first item from ++the kill ring into the current buffer. If the @kbd{C-y} command is ++followed immediately by @kbd{M-y}, the first element is replaced by ++the second element. Successive @kbd{M-y} commands replace the second ++element with the third, fourth, or fifth element, and so on. When the ++last element in the kill ring is reached, it is replaced by the first ++element and the cycle is repeated. (Thus the kill ring is called a ++`ring' rather than just a `list'. However, the actual data structure ++that holds the text is a list. ++@xref{Kill Ring, , Handling the Kill Ring}, for the details of how the ++list is handled as a ring.) ++ ++@menu ++* Kill Ring Overview:: ++* kill-ring-yank-pointer:: The kill ring is a list. ++* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. ++@end menu ++ ++@node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking ++@comment node-name, next, previous, up ++@section Kill Ring Overview ++@cindex Kill ring overview ++ ++The kill ring is a list of textual strings. This is what it looks like: ++ ++@smallexample ++("some text" "a different piece of text" "yet more text") ++@end smallexample ++ ++If this were the contents of my kill ring and I pressed @kbd{C-y}, the ++string of characters saying @samp{some text} would be inserted in this ++buffer where my cursor is located. ++ ++The @code{yank} command is also used for duplicating text by copying it. ++The copied text is not cut from the buffer, but a copy of it is put on the ++kill ring and is inserted by yanking it back. ++ ++Three functions are used for bringing text back from the kill ring: ++@code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop}, ++which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer}, ++which is used by the two other functions. ++ ++These functions refer to the kill ring through a variable called the ++@code{kill-ring-yank-pointer}. Indeed, the insertion code for both the ++@code{yank} and @code{yank-pop} functions is: ++ ++@smallexample ++(insert (car kill-ring-yank-pointer)) ++@end smallexample ++ ++@noindent ++(Well, no more. In GNU Emacs 22, the function has been replaced by ++@code{insert-for-yank} which calls @code{insert-for-yank-1} ++repetitively for each @code{yank-handler} segment. In turn, ++@code{insert-for-yank-1} strips text properties from the inserted text ++according to @code{yank-excluded-properties}. Otherwise, it is just ++like @code{insert}. We will stick with plain @code{insert} since it ++is easier to understand.) ++ ++To begin to understand how @code{yank} and @code{yank-pop} work, it is ++first necessary to look at the @code{kill-ring-yank-pointer} variable. ++ ++@node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking ++@comment node-name, next, previous, up ++@section The @code{kill-ring-yank-pointer} Variable ++ ++@code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is ++a variable. It points to something by being bound to the value of what ++it points to, like any other Lisp variable. ++ ++@need 1000 ++Thus, if the value of the kill ring is: ++ ++@smallexample ++("some text" "a different piece of text" "yet more text") ++@end smallexample ++ ++@need 1250 ++@noindent ++and the @code{kill-ring-yank-pointer} points to the second clause, the ++value of @code{kill-ring-yank-pointer} is: ++ ++@smallexample ++("a different piece of text" "yet more text") ++@end smallexample ++ ++As explained in the previous chapter (@pxref{List Implementation}), the ++computer does not keep two different copies of the text being pointed to ++by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The ++words ``a different piece of text'' and ``yet more text'' are not ++duplicated. Instead, the two Lisp variables point to the same pieces of ++text. Here is a diagram: ++ ++@c cons-cell-diagram #5 ++@ifnottex ++@smallexample ++@group ++kill-ring kill-ring-yank-pointer ++ | | ++ | ___ ___ | ___ ___ ___ ___ ++ ---> | | | --> | | | | | | ++ |___|___|----> |___|___|--> |___|___|--> nil ++ | | | ++ | | | ++ | | --> "yet more text" ++ | | ++ | --> "a different piece of text" ++ | ++ --> "some text" ++@end group ++@end smallexample ++@sp 1 ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{cons-5} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@smallexample ++@group ++kill-ring kill-ring-yank-pointer ++ | | ++ | ___ ___ | ___ ___ ___ ___ ++ ---> | | | --> | | | | | | ++ |___|___|----> |___|___|--> |___|___|--> nil ++ | | | ++ | | | ++ | | --> "yet more text" ++ | | ++ | --> "a different piece of text ++ | ++ --> "some text" ++@end group ++@end smallexample ++@sp 1 ++@end iftex ++@end ifclear ++ ++Both the variable @code{kill-ring} and the variable ++@code{kill-ring-yank-pointer} are pointers. But the kill ring itself is ++usually described as if it were actually what it is composed of. The ++@code{kill-ring} is spoken of as if it were the list rather than that it ++points to the list. Conversely, the @code{kill-ring-yank-pointer} is ++spoken of as pointing to a list. ++ ++These two ways of talking about the same thing sound confusing at first but ++make sense on reflection. The kill ring is generally thought of as the ++complete structure of data that holds the information of what has recently ++been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer} ++on the other hand, serves to indicate---that is, to `point to'---that part ++of the kill ring of which the first element (the @sc{car}) will be ++inserted. ++ ++@ignore ++In GNU Emacs 22, the @code{kill-new} function calls ++ ++@code{(setq kill-ring-yank-pointer kill-ring)} ++ ++(defun rotate-yank-pointer (arg) ++ "Rotate the yanking point in the kill ring. ++With argument, rotate that many kills forward (or backward, if negative)." ++ (interactive "p") ++ (current-kill arg)) ++ ++(defun current-kill (n &optional do-not-move) ++ "Rotate the yanking point by N places, and then return that kill. ++If N is zero, `interprogram-paste-function' is set, and calling it ++returns a string, then that string is added to the front of the ++kill ring and returned as the latest kill. ++If optional arg DO-NOT-MOVE is non-nil, then don't actually move the ++yanking point; just return the Nth kill forward." ++ (let ((interprogram-paste (and (= n 0) ++ interprogram-paste-function ++ (funcall interprogram-paste-function)))) ++ (if interprogram-paste ++ (progn ++ ;; Disable the interprogram cut function when we add the new ++ ;; text to the kill ring, so Emacs doesn't try to own the ++ ;; selection, with identical text. ++ (let ((interprogram-cut-function nil)) ++ (kill-new interprogram-paste)) ++ interprogram-paste) ++ (or kill-ring (error "Kill ring is empty")) ++ (let ((ARGth-kill-element ++ (nthcdr (mod (- n (length kill-ring-yank-pointer)) ++ (length kill-ring)) ++ kill-ring))) ++ (or do-not-move ++ (setq kill-ring-yank-pointer ARGth-kill-element)) ++ (car ARGth-kill-element))))) ++ ++@end ignore ++ ++@need 1500 ++@node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking ++@section Exercises with @code{yank} and @code{nthcdr} ++ ++@itemize @bullet ++@item ++Using @kbd{C-h v} (@code{describe-variable}), look at the value of ++your kill ring. Add several items to your kill ring; look at its ++value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way ++around the kill ring. How many items were in your kill ring? Find ++the value of @code{kill-ring-max}. Was your kill ring full, or could ++you have kept more blocks of text within it? ++ ++@item ++Using @code{nthcdr} and @code{car}, construct a series of expressions ++to return the first, second, third, and fourth elements of a list. ++@end itemize ++ ++@node Loops & Recursion, Regexp Search, Yanking, Top ++@comment node-name, next, previous, up ++@chapter Loops and Recursion ++@cindex Loops and recursion ++@cindex Recursion and loops ++@cindex Repetition (loops) ++ ++Emacs Lisp has two primary ways to cause an expression, or a series of ++expressions, to be evaluated repeatedly: one uses a @code{while} ++loop, and the other uses @dfn{recursion}. ++ ++Repetition can be very valuable. For example, to move forward four ++sentences, you need only write a program that will move forward one ++sentence and then repeat the process four times. Since a computer does ++not get bored or tired, such repetitive action does not have the ++deleterious effects that excessive or the wrong kinds of repetition can ++have on humans. ++ ++People mostly write Emacs Lisp functions using @code{while} loops and ++their kin; but you can use recursion, which provides a very powerful ++way to think about and then to solve problems@footnote{You can write ++recursive functions to be frugal or wasteful of mental or computer ++resources; as it happens, methods that people find easy---that are ++frugal of `mental resources'---sometimes use considerable computer ++resources. Emacs was designed to run on machines that we now consider ++limited and its default settings are conservative. You may want to ++increase the values of @code{max-specpdl-size} and ++@code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to ++15 and 30 times their default value.}. ++ ++@menu ++* while:: Causing a stretch of code to repeat. ++* dolist dotimes:: ++* Recursion:: Causing a function to call itself. ++* Looping exercise:: ++@end menu ++ ++@node while, dolist dotimes, Loops & Recursion, Loops & Recursion ++@comment node-name, next, previous, up ++@section @code{while} ++@cindex Loops ++@findex while ++ ++The @code{while} special form tests whether the value returned by ++evaluating its first argument is true or false. This is similar to what ++the Lisp interpreter does with an @code{if}; what the interpreter does ++next, however, is different. ++ ++In a @code{while} expression, if the value returned by evaluating the ++first argument is false, the Lisp interpreter skips the rest of the ++expression (the @dfn{body} of the expression) and does not evaluate it. ++However, if the value is true, the Lisp interpreter evaluates the body ++of the expression and then again tests whether the first argument to ++@code{while} is true or false. If the value returned by evaluating the ++first argument is again true, the Lisp interpreter again evaluates the ++body of the expression. ++ ++@need 1200 ++The template for a @code{while} expression looks like this: ++ ++@smallexample ++@group ++(while @var{true-or-false-test} ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++@menu ++* Looping with while:: Repeat so long as test returns true. ++* Loop Example:: A @code{while} loop that uses a list. ++* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. ++* Incrementing Loop:: A loop with an incrementing counter. ++* Incrementing Loop Details:: ++* Decrementing Loop:: A loop with a decrementing counter. ++@end menu ++ ++@node Looping with while, Loop Example, while, while ++@ifnottex ++@unnumberedsubsec Looping with @code{while} ++@end ifnottex ++ ++So long as the true-or-false-test of the @code{while} expression ++returns a true value when it is evaluated, the body is repeatedly ++evaluated. This process is called a loop since the Lisp interpreter ++repeats the same thing again and again, like an airplane doing a loop. ++When the result of evaluating the true-or-false-test is false, the ++Lisp interpreter does not evaluate the rest of the @code{while} ++expression and `exits the loop'. ++ ++Clearly, if the value returned by evaluating the first argument to ++@code{while} is always true, the body following will be evaluated ++again and again @dots{} and again @dots{} forever. Conversely, if the ++value returned is never true, the expressions in the body will never ++be evaluated. The craft of writing a @code{while} loop consists of ++choosing a mechanism such that the true-or-false-test returns true ++just the number of times that you want the subsequent expressions to ++be evaluated, and then have the test return false. ++ ++The value returned by evaluating a @code{while} is the value of the ++true-or-false-test. An interesting consequence of this is that a ++@code{while} loop that evaluates without error will return @code{nil} ++or false regardless of whether it has looped 1 or 100 times or none at ++all. A @code{while} expression that evaluates successfully never ++returns a true value! What this means is that @code{while} is always ++evaluated for its side effects, which is to say, the consequences of ++evaluating the expressions within the body of the @code{while} loop. ++This makes sense. It is not the mere act of looping that is desired, ++but the consequences of what happens when the expressions in the loop ++are repeatedly evaluated. ++ ++@node Loop Example, print-elements-of-list, Looping with while, while ++@comment node-name, next, previous, up ++@subsection A @code{while} Loop and a List ++ ++A common way to control a @code{while} loop is to test whether a list ++has any elements. If it does, the loop is repeated; but if it does not, ++the repetition is ended. Since this is an important technique, we will ++create a short example to illustrate it. ++ ++A simple way to test whether a list has elements is to evaluate the ++list: if it has no elements, it is an empty list and will return the ++empty list, @code{()}, which is a synonym for @code{nil} or false. On ++the other hand, a list with elements will return those elements when it ++is evaluated. Since Emacs Lisp considers as true any value that is not ++@code{nil}, a list that returns elements will test true in a ++@code{while} loop. ++ ++@need 1200 ++For example, you can set the variable @code{empty-list} to @code{nil} by ++evaluating the following @code{setq} expression: ++ ++@smallexample ++(setq empty-list ()) ++@end smallexample ++ ++@noindent ++After evaluating the @code{setq} expression, you can evaluate the ++variable @code{empty-list} in the usual way, by placing the cursor after ++the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your ++echo area: ++ ++@smallexample ++empty-list ++@end smallexample ++ ++On the other hand, if you set a variable to be a list with elements, the ++list will appear when you evaluate the variable, as you can see by ++evaluating the following two expressions: ++ ++@smallexample ++@group ++(setq animals '(gazelle giraffe lion tiger)) ++ ++animals ++@end group ++@end smallexample ++ ++Thus, to create a @code{while} loop that tests whether there are any ++items in the list @code{animals}, the first part of the loop will be ++written like this: ++ ++@smallexample ++@group ++(while animals ++ @dots{} ++@end group ++@end smallexample ++ ++@noindent ++When the @code{while} tests its first argument, the variable ++@code{animals} is evaluated. It returns a list. So long as the list ++has elements, the @code{while} considers the results of the test to be ++true; but when the list is empty, it considers the results of the test ++to be false. ++ ++To prevent the @code{while} loop from running forever, some mechanism ++needs to be provided to empty the list eventually. An oft-used ++technique is to have one of the subsequent forms in the @code{while} ++expression set the value of the list to be the @sc{cdr} of the list. ++Each time the @code{cdr} function is evaluated, the list will be made ++shorter, until eventually only the empty list will be left. At this ++point, the test of the @code{while} loop will return false, and the ++arguments to the @code{while} will no longer be evaluated. ++ ++For example, the list of animals bound to the variable @code{animals} ++can be set to be the @sc{cdr} of the original list with the ++following expression: ++ ++@smallexample ++(setq animals (cdr animals)) ++@end smallexample ++ ++@noindent ++If you have evaluated the previous expressions and then evaluate this ++expression, you will see @code{(giraffe lion tiger)} appear in the echo ++area. If you evaluate the expression again, @code{(lion tiger)} will ++appear in the echo area. If you evaluate it again and yet again, ++@code{(tiger)} appears and then the empty list, shown by @code{nil}. ++ ++A template for a @code{while} loop that uses the @code{cdr} function ++repeatedly to cause the true-or-false-test eventually to test false ++looks like this: ++ ++@smallexample ++@group ++(while @var{test-whether-list-is-empty} ++ @var{body}@dots{} ++ @var{set-list-to-cdr-of-list}) ++@end group ++@end smallexample ++ ++This test and use of @code{cdr} can be put together in a function that ++goes through a list and prints each element of the list on a line of its ++own. ++ ++@node print-elements-of-list, Incrementing Loop, Loop Example, while ++@subsection An Example: @code{print-elements-of-list} ++@findex print-elements-of-list ++ ++The @code{print-elements-of-list} function illustrates a @code{while} ++loop with a list. ++ ++@cindex @file{*scratch*} buffer ++The function requires several lines for its output. If you are ++reading this in a recent instance of GNU Emacs, ++@c GNU Emacs 21, GNU Emacs 22, or a later version, ++you can evaluate the following expression inside of Info, as usual. ++ ++If you are using an earlier version of Emacs, you need to copy the ++necessary expressions to your @file{*scratch*} buffer and evaluate ++them there. This is because the echo area had only one line in the ++earlier versions. ++ ++You can copy the expressions by marking the beginning of the region ++with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to ++the end of the region and then copying the region using @kbd{M-w} ++(@code{kill-ring-save}, which calls @code{copy-region-as-kill} and ++then provides visual feedback). In the @file{*scratch*} ++buffer, you can yank the expressions back by typing @kbd{C-y} ++(@code{yank}). ++ ++After you have copied the expressions to the @file{*scratch*} buffer, ++evaluate each expression in turn. Be sure to evaluate the last ++expression, @code{(print-elements-of-list animals)}, by typing ++@kbd{C-u C-x C-e}, that is, by giving an argument to ++@code{eval-last-sexp}. This will cause the result of the evaluation ++to be printed in the @file{*scratch*} buffer instead of being printed ++in the echo area. (Otherwise you will see something like this in your ++echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which ++each @samp{^J} stands for a `newline'.) ++ ++@need 1500 ++In a recent instance of GNU Emacs, you can evaluate these expressions ++directly in the Info buffer, and the echo area will grow to show the ++results. ++ ++@smallexample ++@group ++(setq animals '(gazelle giraffe lion tiger)) ++ ++(defun print-elements-of-list (list) ++ "Print each element of LIST on a line of its own." ++ (while list ++ (print (car list)) ++ (setq list (cdr list)))) ++ ++(print-elements-of-list animals) ++@end group ++@end smallexample ++ ++@need 1200 ++@noindent ++When you evaluate the three expressions in sequence, you will see ++this: ++ ++@smallexample ++@group ++gazelle ++ ++giraffe ++ ++lion ++ ++tiger ++nil ++@end group ++@end smallexample ++ ++Each element of the list is printed on a line of its own (that is what ++the function @code{print} does) and then the value returned by the ++function is printed. Since the last expression in the function is the ++@code{while} loop, and since @code{while} loops always return ++@code{nil}, a @code{nil} is printed after the last element of the list. ++ ++@node Incrementing Loop, Incrementing Loop Details, print-elements-of-list, while ++@comment node-name, next, previous, up ++@subsection A Loop with an Incrementing Counter ++ ++A loop is not useful unless it stops when it ought. Besides ++controlling a loop with a list, a common way of stopping a loop is to ++write the first argument as a test that returns false when the correct ++number of repetitions are complete. This means that the loop must ++have a counter---an expression that counts how many times the loop ++repeats itself. ++ ++@node Incrementing Loop Details, Decrementing Loop, Incrementing Loop, while ++@ifnottex ++@unnumberedsubsec Details of an Incrementing Loop ++@end ifnottex ++ ++The test for a loop with an incrementing counter can be an expression ++such as @code{(< count desired-number)} which returns @code{t} for ++true if the value of @code{count} is less than the ++@code{desired-number} of repetitions and @code{nil} for false if the ++value of @code{count} is equal to or is greater than the ++@code{desired-number}. The expression that increments the count can ++be a simple @code{setq} such as @code{(setq count (1+ count))}, where ++@code{1+} is a built-in function in Emacs Lisp that adds 1 to its ++argument. (The expression @w{@code{(1+ count)}} has the same result ++as @w{@code{(+ count 1)}}, but is easier for a human to read.) ++ ++@need 1250 ++The template for a @code{while} loop controlled by an incrementing ++counter looks like this: ++ ++@smallexample ++@group ++@var{set-count-to-initial-value} ++(while (< count desired-number) ; @r{true-or-false-test} ++ @var{body}@dots{} ++ (setq count (1+ count))) ; @r{incrementer} ++@end group ++@end smallexample ++ ++@noindent ++Note that you need to set the initial value of @code{count}; usually it ++is set to 1. ++ ++@menu ++* Incrementing Example:: Counting pebbles in a triangle. ++* Inc Example parts:: The parts of the function definition. ++* Inc Example altogether:: Putting the function definition together. ++@end menu ++ ++@node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details ++@unnumberedsubsubsec Example with incrementing counter ++ ++Suppose you are playing on the beach and decide to make a triangle of ++pebbles, putting one pebble in the first row, two in the second row, ++three in the third row and so on, like this: ++ ++@sp 1 ++@c pebble diagram ++@ifnottex ++@smallexample ++@group ++ * ++ * * ++ * * * ++ * * * * ++@end group ++@end smallexample ++@end ifnottex ++@iftex ++@smallexample ++@group ++ @bullet{} ++ @bullet{} @bullet{} ++ @bullet{} @bullet{} @bullet{} ++ @bullet{} @bullet{} @bullet{} @bullet{} ++@end group ++@end smallexample ++@end iftex ++@sp 1 ++ ++@noindent ++(About 2500 years ago, Pythagoras and others developed the beginnings of ++number theory by considering questions such as this.) ++ ++Suppose you want to know how many pebbles you will need to make a ++triangle with 7 rows? ++ ++Clearly, what you need to do is add up the numbers from 1 to 7. There ++are two ways to do this; start with the smallest number, one, and add up ++the list in sequence, 1, 2, 3, 4 and so on; or start with the largest ++number and add the list going down: 7, 6, 5, 4 and so on. Because both ++mechanisms illustrate common ways of writing @code{while} loops, we will ++create two examples, one counting up and the other counting down. In ++this first example, we will start with 1 and add 2, 3, 4 and so on. ++ ++If you are just adding up a short list of numbers, the easiest way to do ++it is to add up all the numbers at once. However, if you do not know ++ahead of time how many numbers your list will have, or if you want to be ++prepared for a very long list, then you need to design your addition so ++that what you do is repeat a simple process many times instead of doing ++a more complex process once. ++ ++For example, instead of adding up all the pebbles all at once, what you ++can do is add the number of pebbles in the first row, 1, to the number ++in the second row, 2, and then add the total of those two rows to the ++third row, 3. Then you can add the number in the fourth row, 4, to the ++total of the first three rows; and so on. ++ ++The critical characteristic of the process is that each repetitive ++action is simple. In this case, at each step we add only two numbers, ++the number of pebbles in the row and the total already found. This ++process of adding two numbers is repeated again and again until the last ++row has been added to the total of all the preceding rows. In a more ++complex loop the repetitive action might not be so simple, but it will ++be simpler than doing everything all at once. ++ ++@node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details ++@unnumberedsubsubsec The parts of the function definition ++ ++The preceding analysis gives us the bones of our function definition: ++first, we will need a variable that we can call @code{total} that will ++be the total number of pebbles. This will be the value returned by ++the function. ++ ++Second, we know that the function will require an argument: this ++argument will be the total number of rows in the triangle. It can be ++called @code{number-of-rows}. ++ ++Finally, we need a variable to use as a counter. We could call this ++variable @code{counter}, but a better name is @code{row-number}. That ++is because what the counter does in this function is count rows, and a ++program should be written to be as understandable as possible. ++ ++When the Lisp interpreter first starts evaluating the expressions in the ++function, the value of @code{total} should be set to zero, since we have ++not added anything to it. Then the function should add the number of ++pebbles in the first row to the total, and then add the number of ++pebbles in the second to the total, and then add the number of ++pebbles in the third row to the total, and so on, until there are no ++more rows left to add. ++ ++Both @code{total} and @code{row-number} are used only inside the ++function, so they can be declared as local variables with @code{let} ++and given initial values. Clearly, the initial value for @code{total} ++should be 0. The initial value of @code{row-number} should be 1, ++since we start with the first row. This means that the @code{let} ++statement will look like this: ++ ++@smallexample ++@group ++ (let ((total 0) ++ (row-number 1)) ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++After the internal variables are declared and bound to their initial ++values, we can begin the @code{while} loop. The expression that serves ++as the test should return a value of @code{t} for true so long as the ++@code{row-number} is less than or equal to the @code{number-of-rows}. ++(If the expression tests true only so long as the row number is less ++than the number of rows in the triangle, the last row will never be ++added to the total; hence the row number has to be either less than or ++equal to the number of rows.) ++ ++@need 1500 ++@findex <= @r{(less than or equal)} ++Lisp provides the @code{<=} function that returns true if the value of ++its first argument is less than or equal to the value of its second ++argument and false otherwise. So the expression that the @code{while} ++will evaluate as its test should look like this: ++ ++@smallexample ++(<= row-number number-of-rows) ++@end smallexample ++ ++The total number of pebbles can be found by repeatedly adding the number ++of pebbles in a row to the total already found. Since the number of ++pebbles in the row is equal to the row number, the total can be found by ++adding the row number to the total. (Clearly, in a more complex ++situation, the number of pebbles in the row might be related to the row ++number in a more complicated way; if this were the case, the row number ++would be replaced by the appropriate expression.) ++ ++@smallexample ++(setq total (+ total row-number)) ++@end smallexample ++ ++@noindent ++What this does is set the new value of @code{total} to be equal to the ++sum of adding the number of pebbles in the row to the previous total. ++ ++After setting the value of @code{total}, the conditions need to be ++established for the next repetition of the loop, if there is one. This ++is done by incrementing the value of the @code{row-number} variable, ++which serves as a counter. After the @code{row-number} variable has ++been incremented, the true-or-false-test at the beginning of the ++@code{while} loop tests whether its value is still less than or equal to ++the value of the @code{number-of-rows} and if it is, adds the new value ++of the @code{row-number} variable to the @code{total} of the previous ++repetition of the loop. ++ ++@need 1200 ++The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the ++@code{row-number} variable can be incremented with this expression: ++ ++@smallexample ++(setq row-number (1+ row-number)) ++@end smallexample ++ ++@node Inc Example altogether, , Inc Example parts, Incrementing Loop Details ++@unnumberedsubsubsec Putting the function definition together ++ ++We have created the parts for the function definition; now we need to ++put them together. ++ ++@need 800 ++First, the contents of the @code{while} expression: ++ ++@smallexample ++@group ++(while (<= row-number number-of-rows) ; @r{true-or-false-test} ++ (setq total (+ total row-number)) ++ (setq row-number (1+ row-number))) ; @r{incrementer} ++@end group ++@end smallexample ++ ++Along with the @code{let} expression varlist, this very nearly ++completes the body of the function definition. However, it requires ++one final element, the need for which is somewhat subtle. ++ ++The final touch is to place the variable @code{total} on a line by ++itself after the @code{while} expression. Otherwise, the value returned ++by the whole function is the value of the last expression that is ++evaluated in the body of the @code{let}, and this is the value ++returned by the @code{while}, which is always @code{nil}. ++ ++This may not be evident at first sight. It almost looks as if the ++incrementing expression is the last expression of the whole function. ++But that expression is part of the body of the @code{while}; it is the ++last element of the list that starts with the symbol @code{while}. ++Moreover, the whole of the @code{while} loop is a list within the body ++of the @code{let}. ++ ++@need 1250 ++In outline, the function will look like this: ++ ++@smallexample ++@group ++(defun @var{name-of-function} (@var{argument-list}) ++ "@var{documentation}@dots{}" ++ (let (@var{varlist}) ++ (while (@var{true-or-false-test}) ++ @var{body-of-while}@dots{} ) ++ @dots{} )) ; @r{Need final expression here.} ++@end group ++@end smallexample ++ ++The result of evaluating the @code{let} is what is going to be returned ++by the @code{defun} since the @code{let} is not embedded within any ++containing list, except for the @code{defun} as a whole. However, if ++the @code{while} is the last element of the @code{let} expression, the ++function will always return @code{nil}. This is not what we want! ++Instead, what we want is the value of the variable @code{total}. This ++is returned by simply placing the symbol as the last element of the list ++starting with @code{let}. It gets evaluated after the preceding ++elements of the list are evaluated, which means it gets evaluated after ++it has been assigned the correct value for the total. ++ ++It may be easier to see this by printing the list starting with ++@code{let} all on one line. This format makes it evident that the ++@var{varlist} and @code{while} expressions are the second and third ++elements of the list starting with @code{let}, and the @code{total} is ++the last element: ++ ++@smallexample ++@group ++(let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total) ++@end group ++@end smallexample ++ ++@need 1200 ++Putting everything together, the @code{triangle} function definition ++looks like this: ++ ++@smallexample ++@group ++(defun triangle (number-of-rows) ; @r{Version with} ++ ; @r{ incrementing counter.} ++ "Add up the number of pebbles in a triangle. ++The first row has one pebble, the second row two pebbles, ++the third row three pebbles, and so on. ++The argument is NUMBER-OF-ROWS." ++@end group ++@group ++ (let ((total 0) ++ (row-number 1)) ++ (while (<= row-number number-of-rows) ++ (setq total (+ total row-number)) ++ (setq row-number (1+ row-number))) ++ total)) ++@end group ++@end smallexample ++ ++@need 1200 ++After you have installed @code{triangle} by evaluating the function, you ++can try it out. Here are two examples: ++ ++@smallexample ++@group ++(triangle 4) ++ ++(triangle 7) ++@end group ++@end smallexample ++ ++@noindent ++The sum of the first four numbers is 10 and the sum of the first seven ++numbers is 28. ++ ++@node Decrementing Loop, , Incrementing Loop Details, while ++@comment node-name, next, previous, up ++@subsection Loop with a Decrementing Counter ++ ++Another common way to write a @code{while} loop is to write the test ++so that it determines whether a counter is greater than zero. So long ++as the counter is greater than zero, the loop is repeated. But when ++the counter is equal to or less than zero, the loop is stopped. For ++this to work, the counter has to start out greater than zero and then ++be made smaller and smaller by a form that is evaluated ++repeatedly. ++ ++The test will be an expression such as @code{(> counter 0)} which ++returns @code{t} for true if the value of @code{counter} is greater ++than zero, and @code{nil} for false if the value of @code{counter} is ++equal to or less than zero. The expression that makes the number ++smaller and smaller can be a simple @code{setq} such as @code{(setq ++counter (1- counter))}, where @code{1-} is a built-in function in ++Emacs Lisp that subtracts 1 from its argument. ++ ++@need 1250 ++The template for a decrementing @code{while} loop looks like this: ++ ++@smallexample ++@group ++(while (> counter 0) ; @r{true-or-false-test} ++ @var{body}@dots{} ++ (setq counter (1- counter))) ; @r{decrementer} ++@end group ++@end smallexample ++ ++@menu ++* Decrementing Example:: More pebbles on the beach. ++* Dec Example parts:: The parts of the function definition. ++* Dec Example altogether:: Putting the function definition together. ++@end menu ++ ++@node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop ++@unnumberedsubsubsec Example with decrementing counter ++ ++To illustrate a loop with a decrementing counter, we will rewrite the ++@code{triangle} function so the counter decreases to zero. ++ ++This is the reverse of the earlier version of the function. In this ++case, to find out how many pebbles are needed to make a triangle with ++3 rows, add the number of pebbles in the third row, 3, to the number ++in the preceding row, 2, and then add the total of those two rows to ++the row that precedes them, which is 1. ++ ++Likewise, to find the number of pebbles in a triangle with 7 rows, add ++the number of pebbles in the seventh row, 7, to the number in the ++preceding row, which is 6, and then add the total of those two rows to ++the row that precedes them, which is 5, and so on. As in the previous ++example, each addition only involves adding two numbers, the total of ++the rows already added up and the number of pebbles in the row that is ++being added to the total. This process of adding two numbers is ++repeated again and again until there are no more pebbles to add. ++ ++We know how many pebbles to start with: the number of pebbles in the ++last row is equal to the number of rows. If the triangle has seven ++rows, the number of pebbles in the last row is 7. Likewise, we know how ++many pebbles are in the preceding row: it is one less than the number in ++the row. ++ ++@node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop ++@unnumberedsubsubsec The parts of the function definition ++ ++We start with three variables: the total number of rows in the ++triangle; the number of pebbles in a row; and the total number of ++pebbles, which is what we want to calculate. These variables can be ++named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and ++@code{total}, respectively. ++ ++Both @code{total} and @code{number-of-pebbles-in-row} are used only ++inside the function and are declared with @code{let}. The initial ++value of @code{total} should, of course, be zero. However, the ++initial value of @code{number-of-pebbles-in-row} should be equal to ++the number of rows in the triangle, since the addition will start with ++the longest row. ++ ++@need 1250 ++This means that the beginning of the @code{let} expression will look ++like this: ++ ++@smallexample ++@group ++(let ((total 0) ++ (number-of-pebbles-in-row number-of-rows)) ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++The total number of pebbles can be found by repeatedly adding the number ++of pebbles in a row to the total already found, that is, by repeatedly ++evaluating the following expression: ++ ++@smallexample ++(setq total (+ total number-of-pebbles-in-row)) ++@end smallexample ++ ++@noindent ++After the @code{number-of-pebbles-in-row} is added to the @code{total}, ++the @code{number-of-pebbles-in-row} should be decremented by one, since ++the next time the loop repeats, the preceding row will be ++added to the total. ++ ++The number of pebbles in a preceding row is one less than the number of ++pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be ++used to compute the number of pebbles in the preceding row. This can be ++done with the following expression: ++ ++@smallexample ++@group ++(setq number-of-pebbles-in-row ++ (1- number-of-pebbles-in-row)) ++@end group ++@end smallexample ++ ++Finally, we know that the @code{while} loop should stop making repeated ++additions when there are no pebbles in a row. So the test for ++the @code{while} loop is simply: ++ ++@smallexample ++(while (> number-of-pebbles-in-row 0) ++@end smallexample ++ ++@node Dec Example altogether, , Dec Example parts, Decrementing Loop ++@unnumberedsubsubsec Putting the function definition together ++ ++We can put these expressions together to create a function definition ++that works. However, on examination, we find that one of the local ++variables is unneeded! ++ ++@need 1250 ++The function definition looks like this: ++ ++@smallexample ++@group ++;;; @r{First subtractive version.} ++(defun triangle (number-of-rows) ++ "Add up the number of pebbles in a triangle." ++ (let ((total 0) ++ (number-of-pebbles-in-row number-of-rows)) ++ (while (> number-of-pebbles-in-row 0) ++ (setq total (+ total number-of-pebbles-in-row)) ++ (setq number-of-pebbles-in-row ++ (1- number-of-pebbles-in-row))) ++ total)) ++@end group ++@end smallexample ++ ++As written, this function works. ++ ++However, we do not need @code{number-of-pebbles-in-row}. ++ ++@cindex Argument as local variable ++When the @code{triangle} function is evaluated, the symbol ++@code{number-of-rows} will be bound to a number, giving it an initial ++value. That number can be changed in the body of the function as if ++it were a local variable, without any fear that such a change will ++effect the value of the variable outside of the function. This is a ++very useful characteristic of Lisp; it means that the variable ++@code{number-of-rows} can be used anywhere in the function where ++@code{number-of-pebbles-in-row} is used. ++ ++@need 800 ++Here is a second version of the function written a bit more cleanly: ++ ++@smallexample ++@group ++(defun triangle (number) ; @r{Second version.} ++ "Return sum of numbers 1 through NUMBER inclusive." ++ (let ((total 0)) ++ (while (> number 0) ++ (setq total (+ total number)) ++ (setq number (1- number))) ++ total)) ++@end group ++@end smallexample ++ ++In brief, a properly written @code{while} loop will consist of three parts: ++ ++@enumerate ++@item ++A test that will return false after the loop has repeated itself the ++correct number of times. ++ ++@item ++An expression the evaluation of which will return the value desired ++after being repeatedly evaluated. ++ ++@item ++An expression to change the value passed to the true-or-false-test so ++that the test returns false after the loop has repeated itself the right ++number of times. ++@end enumerate ++ ++@node dolist dotimes, Recursion, while, Loops & Recursion ++@comment node-name, next, previous, up ++@section Save your time: @code{dolist} and @code{dotimes} ++ ++In addition to @code{while}, both @code{dolist} and @code{dotimes} ++provide for looping. Sometimes these are quicker to write than the ++equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, , ++Macros, elisp, The GNU Emacs Lisp Reference Manual}. ) ++ ++@code{dolist} works like a @code{while} loop that `@sc{cdr}s down a ++list': @code{dolist} automatically shortens the list each time it ++loops---takes the @sc{cdr} of the list---and binds the @sc{car} of ++each shorter version of the list to the first of its arguments. ++ ++@code{dotimes} loops a specific number of times: you specify the number. ++ ++@menu ++* dolist:: ++* dotimes:: ++@end menu ++ ++@node dolist, dotimes, dolist dotimes, dolist dotimes ++@unnumberedsubsubsec The @code{dolist} Macro ++@findex dolist ++ ++Suppose, for example, you want to reverse a list, so that ++``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''. ++ ++@need 1250 ++In practice, you would use the @code{reverse} function, like this: ++ ++@smallexample ++@group ++(setq animals '(gazelle giraffe lion tiger)) ++ ++(reverse animals) ++@end group ++@end smallexample ++ ++@need 800 ++@noindent ++Here is how you could reverse the list using a @code{while} loop: ++ ++@smallexample ++@group ++(setq animals '(gazelle giraffe lion tiger)) ++ ++(defun reverse-list-with-while (list) ++ "Using while, reverse the order of LIST." ++ (let (value) ; make sure list starts empty ++ (while list ++ (setq value (cons (car list) value)) ++ (setq list (cdr list))) ++ value)) ++ ++(reverse-list-with-while animals) ++@end group ++@end smallexample ++ ++@need 800 ++@noindent ++And here is how you could use the @code{dolist} macro: ++ ++@smallexample ++@group ++(setq animals '(gazelle giraffe lion tiger)) ++ ++(defun reverse-list-with-dolist (list) ++ "Using dolist, reverse the order of LIST." ++ (let (value) ; make sure list starts empty ++ (dolist (element list value) ++ (setq value (cons element value))))) ++ ++(reverse-list-with-dolist animals) ++@end group ++@end smallexample ++ ++@need 1250 ++@noindent ++In Info, you can place your cursor after the closing parenthesis of ++each expression and type @kbd{C-x C-e}; in each case, you should see ++ ++@smallexample ++(tiger lion giraffe gazelle) ++@end smallexample ++ ++@noindent ++in the echo area. ++ ++For this example, the existing @code{reverse} function is obviously best. ++The @code{while} loop is just like our first example (@pxref{Loop ++Example, , A @code{while} Loop and a List}). The @code{while} first ++checks whether the list has elements; if so, it constructs a new list ++by adding the first element of the list to the existing list (which in ++the first iteration of the loop is @code{nil}). Since the second ++element is prepended in front of the first element, and the third ++element is prepended in front of the second element, the list is reversed. ++ ++In the expression using a @code{while} loop, ++the @w{@code{(setq list (cdr list))}} ++expression shortens the list, so the @code{while} loop eventually ++stops. In addition, it provides the @code{cons} expression with a new ++first element by creating a new and shorter list at each repetition of ++the loop. ++ ++The @code{dolist} expression does very much the same as the ++@code{while} expression, except that the @code{dolist} macro does some ++of the work you have to do when writing a @code{while} expression. ++ ++Like a @code{while} loop, a @code{dolist} loops. What is different is ++that it automatically shortens the list each time it loops --- it ++`@sc{cdr}s down the list' on its own --- and it automatically binds ++the @sc{car} of each shorter version of the list to the first of its ++arguments. ++ ++In the example, the @sc{car} of each shorter version of the list is ++referred to using the symbol @samp{element}, the list itself is called ++@samp{list}, and the value returned is called @samp{value}. The ++remainder of the @code{dolist} expression is the body. ++ ++The @code{dolist} expression binds the @sc{car} of each shorter ++version of the list to @code{element} and then evaluates the body of ++the expression; and repeats the loop. The result is returned in ++@code{value}. ++ ++@node dotimes, , dolist, dolist dotimes ++@unnumberedsubsubsec The @code{dotimes} Macro ++@findex dotimes ++ ++The @code{dotimes} macro is similar to @code{dolist}, except that it ++loops a specific number of times. ++ ++The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 ++and so forth each time around the loop, and the value of the third ++argument is returned. You need to provide the value of the second ++argument, which is how many times the macro loops. ++ ++@need 1250 ++For example, the following binds the numbers from 0 up to, but not ++including, the number 3 to the first argument, @var{number}, and then ++constructs a list of the three numbers. (The first number is 0, the ++second number is 1, and the third number is 2; this makes a total of ++three numbers in all, starting with zero as the first number.) ++ ++@smallexample ++@group ++(let (value) ; otherwise a value is a void variable ++ (dotimes (number 3 value) ++ (setq value (cons number value)))) ++ ++@result{} (2 1 0) ++@end group ++@end smallexample ++ ++@noindent ++@code{dotimes} returns @code{value}, so the way to use ++@code{dotimes} is to operate on some expression @var{number} number of ++times and then return the result, either as a list or an atom. ++ ++@need 1250 ++Here is an example of a @code{defun} that uses @code{dotimes} to add ++up the number of pebbles in a triangle. ++ ++@smallexample ++@group ++(defun triangle-using-dotimes (number-of-rows) ++ "Using dotimes, add up the number of pebbles in a triangle." ++(let ((total 0)) ; otherwise a total is a void variable ++ (dotimes (number number-of-rows total) ++ (setq total (+ total (1+ number)))))) ++ ++(triangle-using-dotimes 4) ++@end group ++@end smallexample ++ ++@node Recursion, Looping exercise, dolist dotimes, Loops & Recursion ++@comment node-name, next, previous, up ++@section Recursion ++@cindex Recursion ++ ++A recursive function contains code that tells the Lisp interpreter to ++call a program that runs exactly like itself, but with slightly ++different arguments. The code runs exactly the same because it has ++the same name. However, even though the program has the same name, it ++is not the same entity. It is different. In the jargon, it is a ++different `instance'. ++ ++Eventually, if the program is written correctly, the `slightly ++different arguments' will become sufficiently different from the first ++arguments that the final instance will stop. ++ ++@menu ++* Building Robots:: Same model, different serial number ... ++* Recursive Definition Parts:: Walk until you stop ... ++* Recursion with list:: Using a list as the test whether to recurse. ++* Recursive triangle function:: ++* Recursion with cond:: ++* Recursive Patterns:: Often used templates. ++* No Deferment:: Don't store up work ... ++* No deferment solution:: ++@end menu ++ ++@node Building Robots, Recursive Definition Parts, Recursion, Recursion ++@comment node-name, next, previous, up ++@subsection Building Robots: Extending the Metaphor ++@cindex Building robots ++@cindex Robots, building ++ ++It is sometimes helpful to think of a running program as a robot that ++does a job. In doing its job, a recursive function calls on a second ++robot to help it. The second robot is identical to the first in every ++way, except that the second robot helps the first and has been ++passed different arguments than the first. ++ ++In a recursive function, the second robot may call a third; and the ++third may call a fourth, and so on. Each of these is a different ++entity; but all are clones. ++ ++Since each robot has slightly different instructions---the arguments ++will differ from one robot to the next---the last robot should know ++when to stop. ++ ++Let's expand on the metaphor in which a computer program is a robot. ++ ++A function definition provides the blueprints for a robot. When you ++install a function definition, that is, when you evaluate a ++@code{defun} special form, you install the necessary equipment to ++build robots. It is as if you were in a factory, setting up an ++assembly line. Robots with the same name are built according to the ++same blueprints. So they have, as it were, the same `model number', ++but a different `serial number'. ++ ++We often say that a recursive function `calls itself'. What we mean ++is that the instructions in a recursive function cause the Lisp ++interpreter to run a different function that has the same name and ++does the same job as the first, but with different arguments. ++ ++It is important that the arguments differ from one instance to the ++next; otherwise, the process will never stop. ++ ++@node Recursive Definition Parts, Recursion with list, Building Robots, Recursion ++@comment node-name, next, previous, up ++@subsection The Parts of a Recursive Definition ++@cindex Parts of a Recursive Definition ++@cindex Recursive Definition Parts ++ ++A recursive function typically contains a conditional expression which ++has three parts: ++ ++@enumerate ++@item ++A true-or-false-test that determines whether the function is called ++again, here called the @dfn{do-again-test}. ++ ++@item ++The name of the function. When this name is called, a new instance of ++the function---a new robot, as it were---is created and told what to do. ++ ++@item ++An expression that returns a different value each time the function is ++called, here called the @dfn{next-step-expression}. Consequently, the ++argument (or arguments) passed to the new instance of the function ++will be different from that passed to the previous instance. This ++causes the conditional expression, the @dfn{do-again-test}, to test ++false after the correct number of repetitions. ++@end enumerate ++ ++Recursive functions can be much simpler than any other kind of ++function. Indeed, when people first start to use them, they often look ++so mysteriously simple as to be incomprehensible. Like riding a ++bicycle, reading a recursive function definition takes a certain knack ++which is hard at first but then seems simple. ++ ++@need 1200 ++There are several different common recursive patterns. A very simple ++pattern looks like this: ++ ++@smallexample ++@group ++(defun @var{name-of-recursive-function} (@var{argument-list}) ++ "@var{documentation}@dots{}" ++ (if @var{do-again-test} ++ @var{body}@dots{} ++ (@var{name-of-recursive-function} ++ @var{next-step-expression}))) ++@end group ++@end smallexample ++ ++Each time a recursive function is evaluated, a new instance of it is ++created and told what to do. The arguments tell the instance what to do. ++ ++An argument is bound to the value of the next-step-expression. Each ++instance runs with a different value of the next-step-expression. ++ ++The value in the next-step-expression is used in the do-again-test. ++ ++The value returned by the next-step-expression is passed to the new ++instance of the function, which evaluates it (or some ++transmogrification of it) to determine whether to continue or stop. ++The next-step-expression is designed so that the do-again-test returns ++false when the function should no longer be repeated. ++ ++The do-again-test is sometimes called the @dfn{stop condition}, ++since it stops the repetitions when it tests false. ++ ++@node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion ++@comment node-name, next, previous, up ++@subsection Recursion with a List ++ ++The example of a @code{while} loop that printed the elements of a list ++of numbers can be written recursively. Here is the code, including ++an expression to set the value of the variable @code{animals} to a list. ++ ++If you are using GNU Emacs 20 or before, this example must be copied ++to the @file{*scratch*} buffer and each expression must be evaluated ++there. Use @kbd{C-u C-x C-e} to evaluate the ++@code{(print-elements-recursively animals)} expression so that the ++results are printed in the buffer; otherwise the Lisp interpreter will ++try to squeeze the results into the one line of the echo area. ++ ++Also, place your cursor immediately after the last closing parenthesis ++of the @code{print-elements-recursively} function, before the comment. ++Otherwise, the Lisp interpreter will try to evaluate the comment. ++ ++If you are using a more recent version of Emacs, you can evaluate this ++expression directly in Info. ++ ++@findex print-elements-recursively ++@smallexample ++@group ++(setq animals '(gazelle giraffe lion tiger)) ++ ++(defun print-elements-recursively (list) ++ "Print each element of LIST on a line of its own. ++Uses recursion." ++ (when list ; @r{do-again-test} ++ (print (car list)) ; @r{body} ++ (print-elements-recursively ; @r{recursive call} ++ (cdr list)))) ; @r{next-step-expression} ++ ++(print-elements-recursively animals) ++@end group ++@end smallexample ++ ++The @code{print-elements-recursively} function first tests whether ++there is any content in the list; if there is, the function prints the ++first element of the list, the @sc{car} of the list. Then the ++function `invokes itself', but gives itself as its argument, not the ++whole list, but the second and subsequent elements of the list, the ++@sc{cdr} of the list. ++ ++Put another way, if the list is not empty, the function invokes ++another instance of code that is similar to the initial code, but is a ++different thread of execution, with different arguments than the first ++instance. ++ ++Put in yet another way, if the list is not empty, the first robot ++assembles a second robot and tells it what to do; the second robot is ++a different individual from the first, but is the same model. ++ ++When the second evaluation occurs, the @code{when} expression is ++evaluated and if true, prints the first element of the list it ++receives as its argument (which is the second element of the original ++list). Then the function `calls itself' with the @sc{cdr} of the list ++it is invoked with, which (the second time around) is the @sc{cdr} of ++the @sc{cdr} of the original list. ++ ++Note that although we say that the function `calls itself', what we ++mean is that the Lisp interpreter assembles and instructs a new ++instance of the program. The new instance is a clone of the first, ++but is a separate individual. ++ ++Each time the function `invokes itself', it invokes itself on a ++shorter version of the original list. It creates a new instance that ++works on a shorter list. ++ ++Eventually, the function invokes itself on an empty list. It creates ++a new instance whose argument is @code{nil}. The conditional expression ++tests the value of @code{list}. Since the value of @code{list} is ++@code{nil}, the @code{when} expression tests false so the then-part is ++not evaluated. The function as a whole then returns @code{nil}. ++ ++@need 1200 ++When you evaluate the expression @code{(print-elements-recursively ++animals)} in the @file{*scratch*} buffer, you see this result: ++ ++@smallexample ++@group ++gazelle ++ ++giraffe ++ ++lion ++ ++tiger ++nil ++@end group ++@end smallexample ++ ++@need 2000 ++@node Recursive triangle function, Recursion with cond, Recursion with list, Recursion ++@comment node-name, next, previous, up ++@subsection Recursion in Place of a Counter ++@findex triangle-recursively ++ ++@need 1200 ++The @code{triangle} function described in a previous section can also ++be written recursively. It looks like this: ++ ++@smallexample ++@group ++(defun triangle-recursively (number) ++ "Return the sum of the numbers 1 through NUMBER inclusive. ++Uses recursion." ++ (if (= number 1) ; @r{do-again-test} ++ 1 ; @r{then-part} ++ (+ number ; @r{else-part} ++ (triangle-recursively ; @r{recursive call} ++ (1- number))))) ; @r{next-step-expression} ++ ++(triangle-recursively 7) ++@end group ++@end smallexample ++ ++@noindent ++You can install this function by evaluating it and then try it by ++evaluating @code{(triangle-recursively 7)}. (Remember to put your ++cursor immediately after the last parenthesis of the function ++definition, before the comment.) The function evaluates to 28. ++ ++To understand how this function works, let's consider what happens in the ++various cases when the function is passed 1, 2, 3, or 4 as the value of ++its argument. ++ ++@menu ++* Recursive Example arg of 1 or 2:: ++* Recursive Example arg of 3 or 4:: ++@end menu ++ ++@node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function ++@ifnottex ++@unnumberedsubsubsec An argument of 1 or 2 ++@end ifnottex ++ ++First, what happens if the value of the argument is 1? ++ ++The function has an @code{if} expression after the documentation ++string. It tests whether the value of @code{number} is equal to 1; if ++so, Emacs evaluates the then-part of the @code{if} expression, which ++returns the number 1 as the value of the function. (A triangle with ++one row has one pebble in it.) ++ ++Suppose, however, that the value of the argument is 2. In this case, ++Emacs evaluates the else-part of the @code{if} expression. ++ ++@need 1200 ++The else-part consists of an addition, the recursive call to ++@code{triangle-recursively} and a decrementing action; and it looks like ++this: ++ ++@smallexample ++(+ number (triangle-recursively (1- number))) ++@end smallexample ++ ++When Emacs evaluates this expression, the innermost expression is ++evaluated first; then the other parts in sequence. Here are the steps ++in detail: ++ ++@table @i ++@item Step 1 @w{ } Evaluate the innermost expression. ++ ++The innermost expression is @code{(1- number)} so Emacs decrements the ++value of @code{number} from 2 to 1. ++ ++@item Step 2 @w{ } Evaluate the @code{triangle-recursively} function. ++ ++The Lisp interpreter creates an individual instance of ++@code{triangle-recursively}. It does not matter that this function is ++contained within itself. Emacs passes the result Step 1 as the ++argument used by this instance of the @code{triangle-recursively} ++function ++ ++In this case, Emacs evaluates @code{triangle-recursively} with an ++argument of 1. This means that this evaluation of ++@code{triangle-recursively} returns 1. ++ ++@item Step 3 @w{ } Evaluate the value of @code{number}. ++ ++The variable @code{number} is the second element of the list that ++starts with @code{+}; its value is 2. ++ ++@item Step 4 @w{ } Evaluate the @code{+} expression. ++ ++The @code{+} expression receives two arguments, the first ++from the evaluation of @code{number} (Step 3) and the second from the ++evaluation of @code{triangle-recursively} (Step 2). ++ ++The result of the addition is the sum of 2 plus 1, and the number 3 is ++returned, which is correct. A triangle with two rows has three ++pebbles in it. ++@end table ++ ++@node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function ++@unnumberedsubsubsec An argument of 3 or 4 ++ ++Suppose that @code{triangle-recursively} is called with an argument of ++3. ++ ++@table @i ++@item Step 1 @w{ } Evaluate the do-again-test. ++ ++The @code{if} expression is evaluated first. This is the do-again ++test and returns false, so the else-part of the @code{if} expression ++is evaluated. (Note that in this example, the do-again-test causes ++the function to call itself when it tests false, not when it tests ++true.) ++ ++@item Step 2 @w{ } Evaluate the innermost expression of the else-part. ++ ++The innermost expression of the else-part is evaluated, which decrements ++3 to 2. This is the next-step-expression. ++ ++@item Step 3 @w{ } Evaluate the @code{triangle-recursively} function. ++ ++The number 2 is passed to the @code{triangle-recursively} function. ++ ++We already know what happens when Emacs evaluates @code{triangle-recursively} with ++an argument of 2. After going through the sequence of actions described ++earlier, it returns a value of 3. So that is what will happen here. ++ ++@item Step 4 @w{ } Evaluate the addition. ++ ++3 will be passed as an argument to the addition and will be added to the ++number with which the function was called, which is 3. ++@end table ++ ++@noindent ++The value returned by the function as a whole will be 6. ++ ++Now that we know what will happen when @code{triangle-recursively} is ++called with an argument of 3, it is evident what will happen if it is ++called with an argument of 4: ++ ++@quotation ++@need 800 ++In the recursive call, the evaluation of ++ ++@smallexample ++(triangle-recursively (1- 4)) ++@end smallexample ++ ++@need 800 ++@noindent ++will return the value of evaluating ++ ++@smallexample ++(triangle-recursively 3) ++@end smallexample ++ ++@noindent ++which is 6 and this value will be added to 4 by the addition in the ++third line. ++@end quotation ++ ++@noindent ++The value returned by the function as a whole will be 10. ++ ++Each time @code{triangle-recursively} is evaluated, it evaluates a ++version of itself---a different instance of itself---with a smaller ++argument, until the argument is small enough so that it does not ++evaluate itself. ++ ++Note that this particular design for a recursive function ++requires that operations be deferred. ++ ++Before @code{(triangle-recursively 7)} can calculate its answer, it ++must call @code{(triangle-recursively 6)}; and before ++@code{(triangle-recursively 6)} can calculate its answer, it must call ++@code{(triangle-recursively 5)}; and so on. That is to say, the ++calculation that @code{(triangle-recursively 7)} makes must be ++deferred until @code{(triangle-recursively 6)} makes its calculation; ++and @code{(triangle-recursively 6)} must defer until ++@code{(triangle-recursively 5)} completes; and so on. ++ ++If each of these instances of @code{triangle-recursively} are thought ++of as different robots, the first robot must wait for the second to ++complete its job, which must wait until the third completes, and so ++on. ++ ++There is a way around this kind of waiting, which we will discuss in ++@ref{No Deferment, , Recursion without Deferments}. ++ ++@node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion ++@comment node-name, next, previous, up ++@subsection Recursion Example Using @code{cond} ++@findex cond ++ ++The version of @code{triangle-recursively} described earlier is written ++with the @code{if} special form. It can also be written using another ++special form called @code{cond}. The name of the special form ++@code{cond} is an abbreviation of the word @samp{conditional}. ++ ++Although the @code{cond} special form is not used as often in the ++Emacs Lisp sources as @code{if}, it is used often enough to justify ++explaining it. ++ ++@need 800 ++The template for a @code{cond} expression looks like this: ++ ++@smallexample ++@group ++(cond ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++@noindent ++where the @var{body} is a series of lists. ++ ++@need 800 ++Written out more fully, the template looks like this: ++ ++@smallexample ++@group ++(cond ++ (@var{first-true-or-false-test} @var{first-consequent}) ++ (@var{second-true-or-false-test} @var{second-consequent}) ++ (@var{third-true-or-false-test} @var{third-consequent}) ++ @dots{}) ++@end group ++@end smallexample ++ ++When the Lisp interpreter evaluates the @code{cond} expression, it ++evaluates the first element (the @sc{car} or true-or-false-test) of ++the first expression in a series of expressions within the body of the ++@code{cond}. ++ ++If the true-or-false-test returns @code{nil} the rest of that ++expression, the consequent, is skipped and the true-or-false-test of the ++next expression is evaluated. When an expression is found whose ++true-or-false-test returns a value that is not @code{nil}, the ++consequent of that expression is evaluated. The consequent can be one ++or more expressions. If the consequent consists of more than one ++expression, the expressions are evaluated in sequence and the value of ++the last one is returned. If the expression does not have a consequent, ++the value of the true-or-false-test is returned. ++ ++If none of the true-or-false-tests test true, the @code{cond} expression ++returns @code{nil}. ++ ++@need 1250 ++Written using @code{cond}, the @code{triangle} function looks like this: ++ ++@smallexample ++@group ++(defun triangle-using-cond (number) ++ (cond ((<= number 0) 0) ++ ((= number 1) 1) ++ ((> number 1) ++ (+ number (triangle-using-cond (1- number)))))) ++@end group ++@end smallexample ++ ++@noindent ++In this example, the @code{cond} returns 0 if the number is less than or ++equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+ ++number (triangle-using-cond (1- number)))} if the number is greater than ++1. ++ ++@node Recursive Patterns, No Deferment, Recursion with cond, Recursion ++@comment node-name, next, previous, up ++@subsection Recursive Patterns ++@cindex Recursive Patterns ++ ++Here are three common recursive patterns. Each involves a list. ++Recursion does not need to involve lists, but Lisp is designed for lists ++and this provides a sense of its primal capabilities. ++ ++@menu ++* Every:: ++* Accumulate:: ++* Keep:: ++@end menu ++ ++@node Every, Accumulate, Recursive Patterns, Recursive Patterns ++@comment node-name, next, previous, up ++@unnumberedsubsubsec Recursive Pattern: @emph{every} ++@cindex Every, type of recursive pattern ++@cindex Recursive pattern: every ++ ++In the @code{every} recursive pattern, an action is performed on every ++element of a list. ++ ++@need 1500 ++The basic pattern is: ++ ++@itemize @bullet ++@item ++If a list be empty, return @code{nil}. ++@item ++Else, act on the beginning of the list (the @sc{car} of the list) ++ @itemize @minus ++ @item ++ through a recursive call by the function on the rest (the ++ @sc{cdr}) of the list, ++ @item ++ and, optionally, combine the acted-on element, using @code{cons}, ++ with the results of acting on the rest. ++ @end itemize ++@end itemize ++ ++@need 1500 ++Here is example: ++ ++@smallexample ++@group ++(defun square-each (numbers-list) ++ "Square each of a NUMBERS LIST, recursively." ++ (if (not numbers-list) ; do-again-test ++ nil ++ (cons ++ (* (car numbers-list) (car numbers-list)) ++ (square-each (cdr numbers-list))))) ; next-step-expression ++@end group ++ ++@group ++(square-each '(1 2 3)) ++ @result{} (1 4 9) ++@end group ++@end smallexample ++ ++@need 1200 ++@noindent ++If @code{numbers-list} is empty, do nothing. But if it has content, ++construct a list combining the square of the first number in the list ++with the result of the recursive call. ++ ++(The example follows the pattern exactly: @code{nil} is returned if ++the numbers' list is empty. In practice, you would write the ++conditional so it carries out the action when the numbers' list is not ++empty.) ++ ++The @code{print-elements-recursively} function (@pxref{Recursion with ++list, , Recursion with a List}) is another example of an @code{every} ++pattern, except in this case, rather than bring the results together ++using @code{cons}, we print each element of output. ++ ++@need 1250 ++The @code{print-elements-recursively} function looks like this: ++ ++@smallexample ++@group ++(setq animals '(gazelle giraffe lion tiger)) ++@end group ++ ++@group ++(defun print-elements-recursively (list) ++ "Print each element of LIST on a line of its own. ++Uses recursion." ++ (when list ; @r{do-again-test} ++ (print (car list)) ; @r{body} ++ (print-elements-recursively ; @r{recursive call} ++ (cdr list)))) ; @r{next-step-expression} ++ ++(print-elements-recursively animals) ++@end group ++@end smallexample ++ ++@need 1500 ++The pattern for @code{print-elements-recursively} is: ++ ++@itemize @bullet ++@item ++When the list is empty, do nothing. ++@item ++But when the list has at least one element, ++ @itemize @minus ++ @item ++ act on the beginning of the list (the @sc{car} of the list), ++ @item ++ and make a recursive call on the rest (the @sc{cdr}) of the list. ++ @end itemize ++@end itemize ++ ++@node Accumulate, Keep, Every, Recursive Patterns ++@comment node-name, next, previous, up ++@unnumberedsubsubsec Recursive Pattern: @emph{accumulate} ++@cindex Accumulate, type of recursive pattern ++@cindex Recursive pattern: accumulate ++ ++Another recursive pattern is called the @code{accumulate} pattern. In ++the @code{accumulate} recursive pattern, an action is performed on ++every element of a list and the result of that action is accumulated ++with the results of performing the action on the other elements. ++ ++This is very like the `every' pattern using @code{cons}, except that ++@code{cons} is not used, but some other combiner. ++ ++@need 1500 ++The pattern is: ++ ++@itemize @bullet ++@item ++If a list be empty, return zero or some other constant. ++@item ++Else, act on the beginning of the list (the @sc{car} of the list), ++ @itemize @minus ++ @item ++ and combine that acted-on element, using @code{+} or ++ some other combining function, with ++ @item ++ a recursive call by the function on the rest (the @sc{cdr}) of the list. ++ @end itemize ++@end itemize ++ ++@need 1500 ++Here is an example: ++ ++@smallexample ++@group ++(defun add-elements (numbers-list) ++ "Add the elements of NUMBERS-LIST together." ++ (if (not numbers-list) ++ 0 ++ (+ (car numbers-list) (add-elements (cdr numbers-list))))) ++@end group ++ ++@group ++(add-elements '(1 2 3 4)) ++ @result{} 10 ++@end group ++@end smallexample ++ ++@xref{Files List, , Making a List of Files}, for an example of the ++accumulate pattern. ++ ++@node Keep, , Accumulate, Recursive Patterns ++@comment node-name, next, previous, up ++@unnumberedsubsubsec Recursive Pattern: @emph{keep} ++@cindex Keep, type of recursive pattern ++@cindex Recursive pattern: keep ++ ++A third recursive pattern is called the @code{keep} pattern. ++In the @code{keep} recursive pattern, each element of a list is tested; ++the element is acted on and the results are kept only if the element ++meets a criterion. ++ ++Again, this is very like the `every' pattern, except the element is ++skipped unless it meets a criterion. ++ ++@need 1500 ++The pattern has three parts: ++ ++@itemize @bullet ++@item ++If a list be empty, return @code{nil}. ++@item ++Else, if the beginning of the list (the @sc{car} of the list) passes ++ a test ++ @itemize @minus ++ @item ++ act on that element and combine it, using @code{cons} with ++ @item ++ a recursive call by the function on the rest (the @sc{cdr}) of the list. ++ @end itemize ++@item ++Otherwise, if the beginning of the list (the @sc{car} of the list) fails ++the test ++ @itemize @minus ++ @item ++ skip on that element, ++ @item ++ and, recursively call the function on the rest (the @sc{cdr}) of the list. ++ @end itemize ++@end itemize ++ ++@need 1500 ++Here is an example that uses @code{cond}: ++ ++@smallexample ++@group ++(defun keep-three-letter-words (word-list) ++ "Keep three letter words in WORD-LIST." ++ (cond ++ ;; First do-again-test: stop-condition ++ ((not word-list) nil) ++ ++ ;; Second do-again-test: when to act ++ ((eq 3 (length (symbol-name (car word-list)))) ++ ;; combine acted-on element with recursive call on shorter list ++ (cons (car word-list) (keep-three-letter-words (cdr word-list)))) ++ ++ ;; Third do-again-test: when to skip element; ++ ;; recursively call shorter list with next-step expression ++ (t (keep-three-letter-words (cdr word-list))))) ++@end group ++ ++@group ++(keep-three-letter-words '(one two three four five six)) ++ @result{} (one two six) ++@end group ++@end smallexample ++ ++It goes without saying that you need not use @code{nil} as the test for ++when to stop; and you can, of course, combine these patterns. ++ ++@node No Deferment, No deferment solution, Recursive Patterns, Recursion ++@subsection Recursion without Deferments ++@cindex Deferment in recursion ++@cindex Recursion without Deferments ++ ++Let's consider again what happens with the @code{triangle-recursively} ++function. We will find that the intermediate calculations are ++deferred until all can be done. ++ ++@need 800 ++Here is the function definition: ++ ++@smallexample ++@group ++(defun triangle-recursively (number) ++ "Return the sum of the numbers 1 through NUMBER inclusive. ++Uses recursion." ++ (if (= number 1) ; @r{do-again-test} ++ 1 ; @r{then-part} ++ (+ number ; @r{else-part} ++ (triangle-recursively ; @r{recursive call} ++ (1- number))))) ; @r{next-step-expression} ++@end group ++@end smallexample ++ ++What happens when we call this function with a argument of 7? ++ ++The first instance of the @code{triangle-recursively} function adds ++the number 7 to the value returned by a second instance of ++@code{triangle-recursively}, an instance that has been passed an ++argument of 6. That is to say, the first calculation is: ++ ++@smallexample ++(+ 7 (triangle-recursively 6)) ++@end smallexample ++ ++@noindent ++The first instance of @code{triangle-recursively}---you may want to ++think of it as a little robot---cannot complete its job. It must hand ++off the calculation for @code{(triangle-recursively 6)} to a second ++instance of the program, to a second robot. This second individual is ++completely different from the first one; it is, in the jargon, a ++`different instantiation'. Or, put another way, it is a different ++robot. It is the same model as the first; it calculates triangle ++numbers recursively; but it has a different serial number. ++ ++And what does @code{(triangle-recursively 6)} return? It returns the ++number 6 added to the value returned by evaluating ++@code{triangle-recursively} with an argument of 5. Using the robot ++metaphor, it asks yet another robot to help it. ++ ++@need 800 ++Now the total is: ++ ++@smallexample ++(+ 7 6 (triangle-recursively 5)) ++@end smallexample ++ ++@need 800 ++And what happens next? ++ ++@smallexample ++(+ 7 6 5 (triangle-recursively 4)) ++@end smallexample ++ ++Each time @code{triangle-recursively} is called, except for the last ++time, it creates another instance of the program---another robot---and ++asks it to make a calculation. ++ ++@need 800 ++Eventually, the full addition is set up and performed: ++ ++@smallexample ++(+ 7 6 5 4 3 2 1) ++@end smallexample ++ ++This design for the function defers the calculation of the first step ++until the second can be done, and defers that until the third can be ++done, and so on. Each deferment means the computer must remember what ++is being waited on. This is not a problem when there are only a few ++steps, as in this example. But it can be a problem when there are ++more steps. ++ ++@node No deferment solution, , No Deferment, Recursion ++@subsection No Deferment Solution ++@cindex No deferment solution ++@cindex Defermentless solution ++@cindex Solution without deferment ++ ++The solution to the problem of deferred operations is to write in a ++manner that does not defer operations@footnote{The phrase @dfn{tail ++recursive} is used to describe such a process, one that uses ++`constant space'.}. This requires ++writing to a different pattern, often one that involves writing two ++function definitions, an `initialization' function and a `helper' ++function. ++ ++The `initialization' function sets up the job; the `helper' function ++does the work. ++ ++@need 1200 ++Here are the two function definitions for adding up numbers. They are ++so simple, I find them hard to understand. ++ ++@smallexample ++@group ++(defun triangle-initialization (number) ++ "Return the sum of the numbers 1 through NUMBER inclusive. ++This is the `initialization' component of a two function ++duo that uses recursion." ++ (triangle-recursive-helper 0 0 number)) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun triangle-recursive-helper (sum counter number) ++ "Return SUM, using COUNTER, through NUMBER inclusive. ++This is the `helper' component of a two function duo ++that uses recursion." ++ (if (> counter number) ++ sum ++ (triangle-recursive-helper (+ sum counter) ; @r{sum} ++ (1+ counter) ; @r{counter} ++ number))) ; @r{number} ++@end group ++@end smallexample ++ ++@need 1250 ++Install both function definitions by evaluating them, then call ++@code{triangle-initialization} with 2 rows: ++ ++@smallexample ++@group ++(triangle-initialization 2) ++ @result{} 3 ++@end group ++@end smallexample ++ ++The `initialization' function calls the first instance of the `helper' ++function with three arguments: zero, zero, and a number which is the ++number of rows in the triangle. ++ ++The first two arguments passed to the `helper' function are ++initialization values. These values are changed when ++@code{triangle-recursive-helper} invokes new instances.@footnote{The ++jargon is mildly confusing: @code{triangle-recursive-helper} uses a ++process that is iterative in a procedure that is recursive. The ++process is called iterative because the computer need only record the ++three values, @code{sum}, @code{counter}, and @code{number}; the ++procedure is recursive because the function `calls itself'. On the ++other hand, both the process and the procedure used by ++@code{triangle-recursively} are called recursive. The word ++`recursive' has different meanings in the two contexts.} ++ ++Let's see what happens when we have a triangle that has one row. (This ++triangle will have one pebble in it!) ++ ++@need 1200 ++@code{triangle-initialization} will call its helper with ++the arguments @w{@code{0 0 1}}. That function will run the conditional ++test whether @code{(> counter number)}: ++ ++@smallexample ++(> 0 1) ++@end smallexample ++ ++@need 1200 ++@noindent ++and find that the result is false, so it will invoke ++the else-part of the @code{if} clause: ++ ++@smallexample ++@group ++ (triangle-recursive-helper ++ (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} ++ (1+ counter) ; @r{increment counter} @result{} @r{counter} ++ number) ; @r{number stays the same} ++@end group ++@end smallexample ++ ++@need 800 ++@noindent ++which will first compute: ++ ++@smallexample ++@group ++(triangle-recursive-helper (+ 0 0) ; @r{sum} ++ (1+ 0) ; @r{counter} ++ 1) ; @r{number} ++@exdent which is: ++ ++(triangle-recursive-helper 0 1 1) ++@end group ++@end smallexample ++ ++Again, @code{(> counter number)} will be false, so again, the Lisp ++interpreter will evaluate @code{triangle-recursive-helper}, creating a ++new instance with new arguments. ++ ++@need 800 ++This new instance will be; ++ ++@smallexample ++@group ++ (triangle-recursive-helper ++ (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} ++ (1+ counter) ; @r{increment counter} @result{} @r{counter} ++ number) ; @r{number stays the same} ++ ++@exdent which is: ++ ++(triangle-recursive-helper 1 2 1) ++@end group ++@end smallexample ++ ++In this case, the @code{(> counter number)} test will be true! So the ++instance will return the value of the sum, which will be 1, as ++expected. ++ ++Now, let's pass @code{triangle-initialization} an argument ++of 2, to find out how many pebbles there are in a triangle with two rows. ++ ++That function calls @code{(triangle-recursive-helper 0 0 2)}. ++ ++@need 800 ++In stages, the instances called will be: ++ ++@smallexample ++@group ++ @r{sum counter number} ++(triangle-recursive-helper 0 1 2) ++ ++(triangle-recursive-helper 1 2 2) ++ ++(triangle-recursive-helper 3 3 2) ++@end group ++@end smallexample ++ ++When the last instance is called, the @code{(> counter number)} test ++will be true, so the instance will return the value of @code{sum}, ++which will be 3. ++ ++This kind of pattern helps when you are writing functions that can use ++many resources in a computer. ++ ++@need 1500 ++@node Looping exercise, , Recursion, Loops & Recursion ++@section Looping Exercise ++ ++@itemize @bullet ++@item ++Write a function similar to @code{triangle} in which each row has a ++value which is the square of the row number. Use a @code{while} loop. ++ ++@item ++Write a function similar to @code{triangle} that multiplies instead of ++adds the values. ++ ++@item ++Rewrite these two functions recursively. Rewrite these functions ++using @code{cond}. ++ ++@c comma in printed title causes problem in Info cross reference ++@item ++Write a function for Texinfo mode that creates an index entry at the ++beginning of a paragraph for every @samp{@@dfn} within the paragraph. ++(In a Texinfo file, @samp{@@dfn} marks a definition. This book is ++written in Texinfo.) ++ ++Many of the functions you will need are described in two of the ++previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing ++Text}, and @ref{Yanking, , Yanking Text Back}. If you use ++@code{forward-paragraph} to put the index entry at the beginning of ++the paragraph, you will have to use @w{@kbd{C-h f}} ++(@code{describe-function}) to find out how to make the command go ++backwards. ++ ++For more information, see ++@ifinfo ++@ref{Indicating, , Indicating Definitions, texinfo}. ++@end ifinfo ++@ifhtml ++@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to ++a Texinfo manual in the current directory. Or, if you are on the ++Internet, see ++@uref{http://www.gnu.org/software/texinfo/manual/texinfo/} ++@end ifhtml ++@iftex ++``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU ++Documentation Format}. ++@end iftex ++@end itemize ++ ++@node Regexp Search, Counting Words, Loops & Recursion, Top ++@comment node-name, next, previous, up ++@chapter Regular Expression Searches ++@cindex Searches, illustrating ++@cindex Regular expression searches ++@cindex Patterns, searching for ++@cindex Motion by sentence and paragraph ++@cindex Sentences, movement by ++@cindex Paragraphs, movement by ++ ++Regular expression searches are used extensively in GNU Emacs. The ++two functions, @code{forward-sentence} and @code{forward-paragraph}, ++illustrate these searches well. They use regular expressions to find ++where to move point. The phrase `regular expression' is often written ++as `regexp'. ++ ++Regular expression searches are described in @ref{Regexp Search, , ++Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in ++@ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference ++Manual}. In writing this chapter, I am presuming that you have at ++least a mild acquaintance with them. The major point to remember is ++that regular expressions permit you to search for patterns as well as ++for literal strings of characters. For example, the code in ++@code{forward-sentence} searches for the pattern of possible ++characters that could mark the end of a sentence, and moves point to ++that spot. ++ ++Before looking at the code for the @code{forward-sentence} function, it ++is worth considering what the pattern that marks the end of a sentence ++must be. The pattern is discussed in the next section; following that ++is a description of the regular expression search function, ++@code{re-search-forward}. The @code{forward-sentence} function ++is described in the section following. Finally, the ++@code{forward-paragraph} function is described in the last section of ++this chapter. @code{forward-paragraph} is a complex function that ++introduces several new features. ++ ++@menu ++* sentence-end:: The regular expression for @code{sentence-end}. ++* re-search-forward:: Very similar to @code{search-forward}. ++* forward-sentence:: A straightforward example of regexp search. ++* forward-paragraph:: A somewhat complex example. ++* etags:: How to create your own @file{TAGS} table. ++* Regexp Review:: ++* re-search Exercises:: ++@end menu ++ ++@node sentence-end, re-search-forward, Regexp Search, Regexp Search ++@comment node-name, next, previous, up ++@section The Regular Expression for @code{sentence-end} ++@findex sentence-end ++ ++The symbol @code{sentence-end} is bound to the pattern that marks the ++end of a sentence. What should this regular expression be? ++ ++Clearly, a sentence may be ended by a period, a question mark, or an ++exclamation mark. Indeed, in English, only clauses that end with one ++of those three characters should be considered the end of a sentence. ++This means that the pattern should include the character set: ++ ++@smallexample ++[.?!] ++@end smallexample ++ ++However, we do not want @code{forward-sentence} merely to jump to a ++period, a question mark, or an exclamation mark, because such a character ++might be used in the middle of a sentence. A period, for example, is ++used after abbreviations. So other information is needed. ++ ++According to convention, you type two spaces after every sentence, but ++only one space after a period, a question mark, or an exclamation mark in ++the body of a sentence. So a period, a question mark, or an exclamation ++mark followed by two spaces is a good indicator of an end of sentence. ++However, in a file, the two spaces may instead be a tab or the end of a ++line. This means that the regular expression should include these three ++items as alternatives. ++ ++@need 800 ++This group of alternatives will look like this: ++ ++@smallexample ++@group ++\\($\\| \\| \\) ++ ^ ^^ ++ TAB SPC ++@end group ++@end smallexample ++ ++@noindent ++Here, @samp{$} indicates the end of the line, and I have pointed out ++where the tab and two spaces are inserted in the expression. Both are ++inserted by putting the actual characters into the expression. ++ ++Two backslashes, @samp{\\}, are required before the parentheses and ++vertical bars: the first backslash quotes the following backslash in ++Emacs; and the second indicates that the following character, the ++parenthesis or the vertical bar, is special. ++ ++@need 1000 ++Also, a sentence may be followed by one or more carriage returns, like ++this: ++ ++@smallexample ++@group ++[ ++]* ++@end group ++@end smallexample ++ ++@noindent ++Like tabs and spaces, a carriage return is inserted into a regular ++expression by inserting it literally. The asterisk indicates that the ++@key{RET} is repeated zero or more times. ++ ++But a sentence end does not consist only of a period, a question mark or ++an exclamation mark followed by appropriate space: a closing quotation ++mark or a closing brace of some kind may precede the space. Indeed more ++than one such mark or brace may precede the space. These require a ++expression that looks like this: ++ ++@smallexample ++[]\"')@}]* ++@end smallexample ++ ++In this expression, the first @samp{]} is the first character in the ++expression; the second character is @samp{"}, which is preceded by a ++@samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last ++three characters are @samp{'}, @samp{)}, and @samp{@}}. ++ ++All this suggests what the regular expression pattern for matching the ++end of a sentence should be; and, indeed, if we evaluate ++@code{sentence-end} we find that it returns the following value: ++ ++@smallexample ++@group ++sentence-end ++ @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[ ++]*" ++@end group ++@end smallexample ++ ++@noindent ++(Well, not in GNU Emacs 22; that is because of an effort to make the ++process simpler and to handle more glyphs and languages. When the ++value of @code{sentence-end} is @code{nil}, then use the value defined ++by the function @code{sentence-end}. (Here is a use of the difference ++between a value and a function in Emacs Lisp.) The function returns a ++value constructed from the variables @code{sentence-end-base}, ++@code{sentence-end-double-space}, @code{sentence-end-without-period}, ++and @code{sentence-end-without-space}. The critical variable is ++@code{sentence-end-base}; its global value is similar to the one ++described above but it also contains two additional quotation marks. ++These have differing degrees of curliness. The ++@code{sentence-end-without-period} variable, when true, tells Emacs ++that a sentence may end without a period, such as text in Thai.) ++ ++@ignore ++@noindent ++(Note that here the @key{TAB}, two spaces, and @key{RET} are shown ++literally in the pattern.) ++ ++This regular expression can be deciphered as follows: ++ ++@table @code ++@item [.?!] ++The first part of the pattern is the three characters, a period, a question ++mark and an exclamation mark, within square brackets. The pattern must ++begin with one or other of these characters. ++ ++@item []\"')@}]* ++The second part of the pattern is the group of closing braces and ++quotation marks, which can appear zero or more times. These may follow ++the period, question mark or exclamation mark. In a regular expression, ++the backslash, @samp{\}, followed by the double quotation mark, ++@samp{"}, indicates the class of string-quote characters. Usually, the ++double quotation mark is the only character in this class. The ++asterisk, @samp{*}, indicates that the items in the previous group (the ++group surrounded by square brackets, @samp{[]}) may be repeated zero or ++more times. ++ ++@item \\($\\| \\| \\) ++The third part of the pattern is one or other of: either the end of a ++line, or two blank spaces, or a tab. The double back-slashes are used ++to prevent Emacs from reading the parentheses and vertical bars as part ++of the search pattern; the parentheses are used to mark the group and ++the vertical bars are used to indicated that the patterns to either side ++of them are alternatives. The dollar sign is used to indicate the end ++of a line and both the two spaces and the tab are each inserted as is to ++indicate what they are. ++ ++@item [@key{RET}]* ++Finally, the last part of the pattern indicates that the end of the line ++or the whitespace following the period, question mark or exclamation ++mark may, but need not, be followed by one or more carriage returns. In ++the pattern, the carriage return is inserted as an actual carriage ++return between square brackets but here it is shown as @key{RET}. ++@end table ++@end ignore ++ ++@node re-search-forward, forward-sentence, sentence-end, Regexp Search ++@comment node-name, next, previous, up ++@section The @code{re-search-forward} Function ++@findex re-search-forward ++ ++The @code{re-search-forward} function is very like the ++@code{search-forward} function. (@xref{search-forward, , The ++@code{search-forward} Function}.) ++ ++@code{re-search-forward} searches for a regular expression. If the ++search is successful, it leaves point immediately after the last ++character in the target. If the search is backwards, it leaves point ++just before the first character in the target. You may tell ++@code{re-search-forward} to return @code{t} for true. (Moving point ++is therefore a `side effect'.) ++ ++Like @code{search-forward}, the @code{re-search-forward} function takes ++four arguments: ++ ++@enumerate ++@item ++The first argument is the regular expression that the function searches ++for. The regular expression will be a string between quotations marks. ++ ++@item ++The optional second argument limits how far the function will search; it is a ++bound, which is specified as a position in the buffer. ++ ++@item ++The optional third argument specifies how the function responds to ++failure: @code{nil} as the third argument causes the function to ++signal an error (and print a message) when the search fails; any other ++value causes it to return @code{nil} if the search fails and @code{t} ++if the search succeeds. ++ ++@item ++The optional fourth argument is the repeat count. A negative repeat ++count causes @code{re-search-forward} to search backwards. ++@end enumerate ++ ++@need 800 ++The template for @code{re-search-forward} looks like this: ++ ++@smallexample ++@group ++(re-search-forward "@var{regular-expression}" ++ @var{limit-of-search} ++ @var{what-to-do-if-search-fails} ++ @var{repeat-count}) ++@end group ++@end smallexample ++ ++The second, third, and fourth arguments are optional. However, if you ++want to pass a value to either or both of the last two arguments, you ++must also pass a value to all the preceding arguments. Otherwise, the ++Lisp interpreter will mistake which argument you are passing the value ++to. ++ ++@need 1200 ++In the @code{forward-sentence} function, the regular expression will be ++the value of the variable @code{sentence-end}. In simple form, that is: ++ ++@smallexample ++@group ++"[.?!][]\"')@}]*\\($\\| \\| \\)[ ++]*" ++@end group ++@end smallexample ++ ++@noindent ++The limit of the search will be the end of the paragraph (since a ++sentence cannot go beyond a paragraph). If the search fails, the ++function will return @code{nil}; and the repeat count will be provided ++by the argument to the @code{forward-sentence} function. ++ ++@node forward-sentence, forward-paragraph, re-search-forward, Regexp Search ++@comment node-name, next, previous, up ++@section @code{forward-sentence} ++@findex forward-sentence ++ ++The command to move the cursor forward a sentence is a straightforward ++illustration of how to use regular expression searches in Emacs Lisp. ++Indeed, the function looks longer and more complicated than it is; this ++is because the function is designed to go backwards as well as forwards; ++and, optionally, over more than one sentence. The function is usually ++bound to the key command @kbd{M-e}. ++ ++@menu ++* Complete forward-sentence:: ++* fwd-sentence while loops:: Two @code{while} loops. ++* fwd-sentence re-search:: A regular expression search. ++@end menu ++ ++@node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence ++@ifnottex ++@unnumberedsubsec Complete @code{forward-sentence} function definition ++@end ifnottex ++ ++@need 1250 ++Here is the code for @code{forward-sentence}: ++ ++@c in GNU Emacs 22 ++@smallexample ++@group ++(defun forward-sentence (&optional arg) ++ "Move forward to next `sentence-end'. With argument, repeat. ++With negative argument, move backward repeatedly to `sentence-beginning'. ++ ++The variable `sentence-end' is a regular expression that matches ends of ++sentences. Also, every paragraph boundary terminates sentences as well." ++@end group ++@group ++ (interactive "p") ++ (or arg (setq arg 1)) ++ (let ((opoint (point)) ++ (sentence-end (sentence-end))) ++ (while (< arg 0) ++ (let ((pos (point)) ++ (par-beg (save-excursion (start-of-paragraph-text) (point)))) ++ (if (and (re-search-backward sentence-end par-beg t) ++ (or (< (match-end 0) pos) ++ (re-search-backward sentence-end par-beg t))) ++ (goto-char (match-end 0)) ++ (goto-char par-beg))) ++ (setq arg (1+ arg))) ++@end group ++@group ++ (while (> arg 0) ++ (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) ++ (if (re-search-forward sentence-end par-end t) ++ (skip-chars-backward " \t\n") ++ (goto-char par-end))) ++ (setq arg (1- arg))) ++ (constrain-to-field nil opoint t))) ++@end group ++@end smallexample ++ ++@ignore ++GNU Emacs 21 ++@smallexample ++@group ++(defun forward-sentence (&optional arg) ++ "Move forward to next sentence-end. With argument, repeat. ++With negative argument, move backward repeatedly to sentence-beginning. ++Sentence ends are identified by the value of sentence-end ++treated as a regular expression. Also, every paragraph boundary ++terminates sentences as well." ++@end group ++@group ++ (interactive "p") ++ (or arg (setq arg 1)) ++ (while (< arg 0) ++ (let ((par-beg ++ (save-excursion (start-of-paragraph-text) (point)))) ++ (if (re-search-backward ++ (concat sentence-end "[^ \t\n]") par-beg t) ++ (goto-char (1- (match-end 0))) ++ (goto-char par-beg))) ++ (setq arg (1+ arg))) ++ (while (> arg 0) ++ (let ((par-end ++ (save-excursion (end-of-paragraph-text) (point)))) ++ (if (re-search-forward sentence-end par-end t) ++ (skip-chars-backward " \t\n") ++ (goto-char par-end))) ++ (setq arg (1- arg)))) ++@end group ++@end smallexample ++@end ignore ++ ++The function looks long at first sight and it is best to look at its ++skeleton first, and then its muscle. The way to see the skeleton is to ++look at the expressions that start in the left-most columns: ++ ++@smallexample ++@group ++(defun forward-sentence (&optional arg) ++ "@var{documentation}@dots{}" ++ (interactive "p") ++ (or arg (setq arg 1)) ++ (let ((opoint (point)) (sentence-end (sentence-end))) ++ (while (< arg 0) ++ (let ((pos (point)) ++ (par-beg (save-excursion (start-of-paragraph-text) (point)))) ++ @var{rest-of-body-of-while-loop-when-going-backwards} ++ (while (> arg 0) ++ (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) ++ @var{rest-of-body-of-while-loop-when-going-forwards} ++ @var{handle-forms-and-equivalent} ++@end group ++@end smallexample ++ ++This looks much simpler! The function definition consists of ++documentation, an @code{interactive} expression, an @code{or} ++expression, a @code{let} expression, and @code{while} loops. ++ ++Let's look at each of these parts in turn. ++ ++We note that the documentation is thorough and understandable. ++ ++The function has an @code{interactive "p"} declaration. This means ++that the processed prefix argument, if any, is passed to the ++function as its argument. (This will be a number.) If the function ++is not passed an argument (it is optional) then the argument ++@code{arg} will be bound to 1. ++ ++When @code{forward-sentence} is called non-interactively without an ++argument, @code{arg} is bound to @code{nil}. The @code{or} expression ++handles this. What it does is either leave the value of @code{arg} as ++it is, but only if @code{arg} is bound to a value; or it sets the ++value of @code{arg} to 1, in the case when @code{arg} is bound to ++@code{nil}. ++ ++Next is a @code{let}. That specifies the values of two local ++variables, @code{point} and @code{sentence-end}. The local value of ++point, from before the search, is used in the ++@code{constrain-to-field} function which handles forms and ++equivalents. The @code{sentence-end} variable is set by the ++@code{sentence-end} function. ++ ++@node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence ++@unnumberedsubsec The @code{while} loops ++ ++Two @code{while} loops follow. The first @code{while} has a ++true-or-false-test that tests true if the prefix argument for ++@code{forward-sentence} is a negative number. This is for going ++backwards. The body of this loop is similar to the body of the second ++@code{while} clause, but it is not exactly the same. We will skip ++this @code{while} loop and concentrate on the second @code{while} ++loop. ++ ++@need 1500 ++The second @code{while} loop is for moving point forward. Its skeleton ++looks like this: ++ ++@smallexample ++@group ++(while (> arg 0) ; @r{true-or-false-test} ++ (let @var{varlist} ++ (if (@var{true-or-false-test}) ++ @var{then-part} ++ @var{else-part} ++ (setq arg (1- arg)))) ; @code{while} @r{loop decrementer} ++@end group ++@end smallexample ++ ++The @code{while} loop is of the decrementing kind. ++(@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It ++has a true-or-false-test that tests true so long as the counter (in ++this case, the variable @code{arg}) is greater than zero; and it has a ++decrementer that subtracts 1 from the value of the counter every time ++the loop repeats. ++ ++If no prefix argument is given to @code{forward-sentence}, which is ++the most common way the command is used, this @code{while} loop will ++run once, since the value of @code{arg} will be 1. ++ ++The body of the @code{while} loop consists of a @code{let} expression, ++which creates and binds a local variable, and has, as its body, an ++@code{if} expression. ++ ++@need 1250 ++The body of the @code{while} loop looks like this: ++ ++@smallexample ++@group ++(let ((par-end ++ (save-excursion (end-of-paragraph-text) (point)))) ++ (if (re-search-forward sentence-end par-end t) ++ (skip-chars-backward " \t\n") ++ (goto-char par-end))) ++@end group ++@end smallexample ++ ++The @code{let} expression creates and binds the local variable ++@code{par-end}. As we shall see, this local variable is designed to ++provide a bound or limit to the regular expression search. If the ++search fails to find a proper sentence ending in the paragraph, it will ++stop on reaching the end of the paragraph. ++ ++But first, let us examine how @code{par-end} is bound to the value of ++the end of the paragraph. What happens is that the @code{let} sets the ++value of @code{par-end} to the value returned when the Lisp interpreter ++evaluates the expression ++ ++@smallexample ++@group ++(save-excursion (end-of-paragraph-text) (point)) ++@end group ++@end smallexample ++ ++@noindent ++In this expression, @code{(end-of-paragraph-text)} moves point to the ++end of the paragraph, @code{(point)} returns the value of point, and then ++@code{save-excursion} restores point to its original position. Thus, ++the @code{let} binds @code{par-end} to the value returned by the ++@code{save-excursion} expression, which is the position of the end of ++the paragraph. (The @code{end-of-paragraph-text} function uses ++@code{forward-paragraph}, which we will discuss shortly.) ++ ++@need 1200 ++Emacs next evaluates the body of the @code{let}, which is an @code{if} ++expression that looks like this: ++ ++@smallexample ++@group ++(if (re-search-forward sentence-end par-end t) ; @r{if-part} ++ (skip-chars-backward " \t\n") ; @r{then-part} ++ (goto-char par-end))) ; @r{else-part} ++@end group ++@end smallexample ++ ++The @code{if} tests whether its first argument is true and if so, ++evaluates its then-part; otherwise, the Emacs Lisp interpreter ++evaluates the else-part. The true-or-false-test of the @code{if} ++expression is the regular expression search. ++ ++It may seem odd to have what looks like the `real work' of ++the @code{forward-sentence} function buried here, but this is a common ++way this kind of operation is carried out in Lisp. ++ ++@node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence ++@unnumberedsubsec The regular expression search ++ ++The @code{re-search-forward} function searches for the end of the ++sentence, that is, for the pattern defined by the @code{sentence-end} ++regular expression. If the pattern is found---if the end of the sentence is ++found---then the @code{re-search-forward} function does two things: ++ ++@enumerate ++@item ++The @code{re-search-forward} function carries out a side effect, which ++is to move point to the end of the occurrence found. ++ ++@item ++The @code{re-search-forward} function returns a value of true. This is ++the value received by the @code{if}, and means that the search was ++successful. ++@end enumerate ++ ++@noindent ++The side effect, the movement of point, is completed before the ++@code{if} function is handed the value returned by the successful ++conclusion of the search. ++ ++When the @code{if} function receives the value of true from a successful ++call to @code{re-search-forward}, the @code{if} evaluates the then-part, ++which is the expression @code{(skip-chars-backward " \t\n")}. This ++expression moves backwards over any blank spaces, tabs or carriage ++returns until a printed character is found and then leaves point after ++the character. Since point has already been moved to the end of the ++pattern that marks the end of the sentence, this action leaves point ++right after the closing printed character of the sentence, which is ++usually a period. ++ ++On the other hand, if the @code{re-search-forward} function fails to ++find a pattern marking the end of the sentence, the function returns ++false. The false then causes the @code{if} to evaluate its third ++argument, which is @code{(goto-char par-end)}: it moves point to the ++end of the paragraph. ++ ++(And if the text is in a form or equivalent, and point may not move ++fully, then the @code{constrain-to-field} function comes into play.) ++ ++Regular expression searches are exceptionally useful and the pattern ++illustrated by @code{re-search-forward}, in which the search is the ++test of an @code{if} expression, is handy. You will see or write code ++incorporating this pattern often. ++ ++@node forward-paragraph, etags, forward-sentence, Regexp Search ++@comment node-name, next, previous, up ++@section @code{forward-paragraph}: a Goldmine of Functions ++@findex forward-paragraph ++ ++@ignore ++@c in GNU Emacs 22 ++(defun forward-paragraph (&optional arg) ++ "Move forward to end of paragraph. ++With argument ARG, do it ARG times; ++a negative argument ARG = -N means move backward N paragraphs. ++ ++A line which `paragraph-start' matches either separates paragraphs ++\(if `paragraph-separate' matches it also) or is the first line of a paragraph. ++A paragraph end is the beginning of a line which is not part of the paragraph ++to which the end of the previous line belongs, or the end of the buffer. ++Returns the count of paragraphs left to move." ++ (interactive "p") ++ (or arg (setq arg 1)) ++ (let* ((opoint (point)) ++ (fill-prefix-regexp ++ (and fill-prefix (not (equal fill-prefix "")) ++ (not paragraph-ignore-fill-prefix) ++ (regexp-quote fill-prefix))) ++ ;; Remove ^ from paragraph-start and paragraph-sep if they are there. ++ ;; These regexps shouldn't be anchored, because we look for them ++ ;; starting at the left-margin. This allows paragraph commands to ++ ;; work normally with indented text. ++ ;; This hack will not find problem cases like "whatever\\|^something". ++ (parstart (if (and (not (equal "" paragraph-start)) ++ (equal ?^ (aref paragraph-start 0))) ++ (substring paragraph-start 1) ++ paragraph-start)) ++ (parsep (if (and (not (equal "" paragraph-separate)) ++ (equal ?^ (aref paragraph-separate 0))) ++ (substring paragraph-separate 1) ++ paragraph-separate)) ++ (parsep ++ (if fill-prefix-regexp ++ (concat parsep "\\|" ++ fill-prefix-regexp "[ \t]*$") ++ parsep)) ++ ;; This is used for searching. ++ (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)")) ++ start found-start) ++ (while (and (< arg 0) (not (bobp))) ++ (if (and (not (looking-at parsep)) ++ (re-search-backward "^\n" (max (1- (point)) (point-min)) t) ++ (looking-at parsep)) ++ (setq arg (1+ arg)) ++ (setq start (point)) ++ ;; Move back over paragraph-separating lines. ++ (forward-char -1) (beginning-of-line) ++ (while (and (not (bobp)) ++ (progn (move-to-left-margin) ++ (looking-at parsep))) ++ (forward-line -1)) ++ (if (bobp) ++ nil ++ (setq arg (1+ arg)) ++ ;; Go to end of the previous (non-separating) line. ++ (end-of-line) ++ ;; Search back for line that starts or separates paragraphs. ++ (if (if fill-prefix-regexp ++ ;; There is a fill prefix; it overrides parstart. ++ (let (multiple-lines) ++ (while (and (progn (beginning-of-line) (not (bobp))) ++ (progn (move-to-left-margin) ++ (not (looking-at parsep))) ++ (looking-at fill-prefix-regexp)) ++ (unless (= (point) start) ++ (setq multiple-lines t)) ++ (forward-line -1)) ++ (move-to-left-margin) ++ ;; This deleted code caused a long hanging-indent line ++ ;; not to be filled together with the following lines. ++ ;; ;; Don't move back over a line before the paragraph ++ ;; ;; which doesn't start with fill-prefix ++ ;; ;; unless that is the only line we've moved over. ++ ;; (and (not (looking-at fill-prefix-regexp)) ++ ;; multiple-lines ++ ;; (forward-line 1)) ++ (not (bobp))) ++ (while (and (re-search-backward sp-parstart nil 1) ++ (setq found-start t) ++ ;; Found a candidate, but need to check if it is a ++ ;; REAL parstart. ++ (progn (setq start (point)) ++ (move-to-left-margin) ++ (not (looking-at parsep))) ++ (not (and (looking-at parstart) ++ (or (not use-hard-newlines) ++ (bobp) ++ (get-text-property ++ (1- start) 'hard))))) ++ (setq found-start nil) ++ (goto-char start)) ++ found-start) ++ ;; Found one. ++ (progn ++ ;; Move forward over paragraph separators. ++ ;; We know this cannot reach the place we started ++ ;; because we know we moved back over a non-separator. ++ (while (and (not (eobp)) ++ (progn (move-to-left-margin) ++ (looking-at parsep))) ++ (forward-line 1)) ++ ;; If line before paragraph is just margin, back up to there. ++ (end-of-line 0) ++ (if (> (current-column) (current-left-margin)) ++ (forward-char 1) ++ (skip-chars-backward " \t") ++ (if (not (bolp)) ++ (forward-line 1)))) ++ ;; No starter or separator line => use buffer beg. ++ (goto-char (point-min)))))) ++ ++ (while (and (> arg 0) (not (eobp))) ++ ;; Move forward over separator lines... ++ (while (and (not (eobp)) ++ (progn (move-to-left-margin) (not (eobp))) ++ (looking-at parsep)) ++ (forward-line 1)) ++ (unless (eobp) (setq arg (1- arg))) ++ ;; ... and one more line. ++ (forward-line 1) ++ (if fill-prefix-regexp ++ ;; There is a fill prefix; it overrides parstart. ++ (while (and (not (eobp)) ++ (progn (move-to-left-margin) (not (eobp))) ++ (not (looking-at parsep)) ++ (looking-at fill-prefix-regexp)) ++ (forward-line 1)) ++ (while (and (re-search-forward sp-parstart nil 1) ++ (progn (setq start (match-beginning 0)) ++ (goto-char start) ++ (not (eobp))) ++ (progn (move-to-left-margin) ++ (not (looking-at parsep))) ++ (or (not (looking-at parstart)) ++ (and use-hard-newlines ++ (not (get-text-property (1- start) 'hard))))) ++ (forward-char 1)) ++ (if (< (point) (point-max)) ++ (goto-char start)))) ++ (constrain-to-field nil opoint t) ++ ;; Return the number of steps that could not be done. ++ arg)) ++@end ignore ++ ++The @code{forward-paragraph} function moves point forward to the end ++of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a ++number of functions that are important in themselves, including ++@code{let*}, @code{match-beginning}, and @code{looking-at}. ++ ++The function definition for @code{forward-paragraph} is considerably ++longer than the function definition for @code{forward-sentence} ++because it works with a paragraph, each line of which may begin with a ++fill prefix. ++ ++A fill prefix consists of a string of characters that are repeated at ++the beginning of each line. For example, in Lisp code, it is a ++convention to start each line of a paragraph-long comment with ++@samp{;;; }. In Text mode, four blank spaces make up another common ++fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , , ++emacs, The GNU Emacs Manual}, for more information about fill ++prefixes.) ++ ++The existence of a fill prefix means that in addition to being able to ++find the end of a paragraph whose lines begin on the left-most ++column, the @code{forward-paragraph} function must be able to find the ++end of a paragraph when all or many of the lines in the buffer begin ++with the fill prefix. ++ ++Moreover, it is sometimes practical to ignore a fill prefix that ++exists, especially when blank lines separate paragraphs. ++This is an added complication. ++ ++@menu ++* forward-paragraph in brief:: Key parts of the function definition. ++* fwd-para let:: The @code{let*} expression. ++* fwd-para while:: The forward motion @code{while} loop. ++@end menu ++ ++@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph ++@ifnottex ++@unnumberedsubsec Shortened @code{forward-paragraph} function definition ++@end ifnottex ++ ++Rather than print all of the @code{forward-paragraph} function, we ++will only print parts of it. Read without preparation, the function ++can be daunting! ++ ++@need 800 ++In outline, the function looks like this: ++ ++@smallexample ++@group ++(defun forward-paragraph (&optional arg) ++ "@var{documentation}@dots{}" ++ (interactive "p") ++ (or arg (setq arg 1)) ++ (let* ++ @var{varlist} ++ (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code} ++ @dots{} ++ (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code} ++ @dots{} ++@end group ++@end smallexample ++ ++The first parts of the function are routine: the function's argument ++list consists of one optional argument. Documentation follows. ++ ++The lower case @samp{p} in the @code{interactive} declaration means ++that the processed prefix argument, if any, is passed to the function. ++This will be a number, and is the repeat count of how many paragraphs ++point will move. The @code{or} expression in the next line handles ++the common case when no argument is passed to the function, which occurs ++if the function is called from other code rather than interactively. ++This case was described earlier. (@xref{forward-sentence, The ++@code{forward-sentence} function}.) Now we reach the end of the ++familiar part of this function. ++ ++@node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph ++@unnumberedsubsec The @code{let*} expression ++ ++The next line of the @code{forward-paragraph} function begins a ++@code{let*} expression. This is a different than @code{let}. The ++symbol is @code{let*} not @code{let}. ++ ++The @code{let*} special form is like @code{let} except that Emacs sets ++each variable in sequence, one after another, and variables in the ++latter part of the varlist can make use of the values to which Emacs ++set variables in the earlier part of the varlist. ++ ++@ignore ++( refappend save-excursion, , code save-excursion in code append-to-buffer .) ++@end ignore ++ ++(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) ++ ++In the @code{let*} expression in this function, Emacs binds a total of ++seven variables: @code{opoint}, @code{fill-prefix-regexp}, ++@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and ++@code{found-start}. ++ ++The variable @code{parsep} appears twice, first, to remove instances ++of @samp{^}, and second, to handle fill prefixes. ++ ++The variable @code{opoint} is just the value of @code{point}. As you ++can guess, it is used in a @code{constrain-to-field} expression, just ++as in @code{forward-sentence}. ++ ++The variable @code{fill-prefix-regexp} is set to the value returned by ++evaluating the following list: ++ ++@smallexample ++@group ++(and fill-prefix ++ (not (equal fill-prefix "")) ++ (not paragraph-ignore-fill-prefix) ++ (regexp-quote fill-prefix)) ++@end group ++@end smallexample ++ ++@noindent ++This is an expression whose first element is the @code{and} special form. ++ ++As we learned earlier (@pxref{kill-new function, , The @code{kill-new} ++function}), the @code{and} special form evaluates each of its ++arguments until one of the arguments returns a value of @code{nil}, in ++which case the @code{and} expression returns @code{nil}; however, if ++none of the arguments returns a value of @code{nil}, the value ++resulting from evaluating the last argument is returned. (Since such ++a value is not @code{nil}, it is considered true in Lisp.) In other ++words, an @code{and} expression returns a true value only if all its ++arguments are true. ++@findex and ++ ++In this case, the variable @code{fill-prefix-regexp} is bound to a ++non-@code{nil} value only if the following four expressions produce a ++true (i.e., a non-@code{nil}) value when they are evaluated; otherwise, ++@code{fill-prefix-regexp} is bound to @code{nil}. ++ ++@table @code ++@item fill-prefix ++When this variable is evaluated, the value of the fill prefix, if any, ++is returned. If there is no fill prefix, this variable returns ++@code{nil}. ++ ++@item (not (equal fill-prefix "") ++This expression checks whether an existing fill prefix is an empty ++string, that is, a string with no characters in it. An empty string is ++not a useful fill prefix. ++ ++@item (not paragraph-ignore-fill-prefix) ++This expression returns @code{nil} if the variable ++@code{paragraph-ignore-fill-prefix} has been turned on by being set to a ++true value such as @code{t}. ++ ++@item (regexp-quote fill-prefix) ++This is the last argument to the @code{and} special form. If all the ++arguments to the @code{and} are true, the value resulting from ++evaluating this expression will be returned by the @code{and} expression ++and bound to the variable @code{fill-prefix-regexp}, ++@end table ++ ++@findex regexp-quote ++@noindent ++The result of evaluating this @code{and} expression successfully is that ++@code{fill-prefix-regexp} will be bound to the value of ++@code{fill-prefix} as modified by the @code{regexp-quote} function. ++What @code{regexp-quote} does is read a string and return a regular ++expression that will exactly match the string and match nothing else. ++This means that @code{fill-prefix-regexp} will be set to a value that ++will exactly match the fill prefix if the fill prefix exists. ++Otherwise, the variable will be set to @code{nil}. ++ ++The next two local variables in the @code{let*} expression are ++designed to remove instances of @samp{^} from @code{parstart} and ++@code{parsep}, the local variables which indicate the paragraph start ++and the paragraph separator. The next expression sets @code{parsep} ++again. That is to handle fill prefixes. ++ ++This is the setting that requires the definition call @code{let*} ++rather than @code{let}. The true-or-false-test for the @code{if} ++depends on whether the variable @code{fill-prefix-regexp} evaluates to ++@code{nil} or some other value. ++ ++If @code{fill-prefix-regexp} does not have a value, Emacs evaluates ++the else-part of the @code{if} expression and binds @code{parsep} to ++its local value. (@code{parsep} is a regular expression that matches ++what separates paragraphs.) ++ ++But if @code{fill-prefix-regexp} does have a value, Emacs evaluates ++the then-part of the @code{if} expression and binds @code{parsep} to a ++regular expression that includes the @code{fill-prefix-regexp} as part ++of the pattern. ++ ++Specifically, @code{parsep} is set to the original value of the ++paragraph separate regular expression concatenated with an alternative ++expression that consists of the @code{fill-prefix-regexp} followed by ++optional whitespace to the end of the line. The whitespace is defined ++by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the ++regexp as an alternative to @code{parsep}. ++ ++According to a comment in the code, the next local variable, ++@code{sp-parstart}, is used for searching, and then the final two, ++@code{start} and @code{found-start}, are set to @code{nil}. ++ ++Now we get into the body of the @code{let*}. The first part of the body ++of the @code{let*} deals with the case when the function is given a ++negative argument and is therefore moving backwards. We will skip this ++section. ++ ++@node fwd-para while, , fwd-para let, forward-paragraph ++@unnumberedsubsec The forward motion @code{while} loop ++ ++The second part of the body of the @code{let*} deals with forward ++motion. It is a @code{while} loop that repeats itself so long as the ++value of @code{arg} is greater than zero. In the most common use of ++the function, the value of the argument is 1, so the body of the ++@code{while} loop is evaluated exactly once, and the cursor moves ++forward one paragraph. ++ ++@ignore ++(while (and (> arg 0) (not (eobp))) ++ ++ ;; Move forward over separator lines... ++ (while (and (not (eobp)) ++ (progn (move-to-left-margin) (not (eobp))) ++ (looking-at parsep)) ++ (forward-line 1)) ++ (unless (eobp) (setq arg (1- arg))) ++ ;; ... and one more line. ++ (forward-line 1) ++ ++ (if fill-prefix-regexp ++ ;; There is a fill prefix; it overrides parstart. ++ (while (and (not (eobp)) ++ (progn (move-to-left-margin) (not (eobp))) ++ (not (looking-at parsep)) ++ (looking-at fill-prefix-regexp)) ++ (forward-line 1)) ++ ++ (while (and (re-search-forward sp-parstart nil 1) ++ (progn (setq start (match-beginning 0)) ++ (goto-char start) ++ (not (eobp))) ++ (progn (move-to-left-margin) ++ (not (looking-at parsep))) ++ (or (not (looking-at parstart)) ++ (and use-hard-newlines ++ (not (get-text-property (1- start) 'hard))))) ++ (forward-char 1)) ++ ++ (if (< (point) (point-max)) ++ (goto-char start)))) ++@end ignore ++ ++This part handles three situations: when point is between paragraphs, ++when there is a fill prefix and when there is no fill prefix. ++ ++@need 800 ++The @code{while} loop looks like this: ++ ++@smallexample ++@group ++;; @r{going forwards and not at the end of the buffer} ++(while (and (> arg 0) (not (eobp))) ++ ++ ;; @r{between paragraphs} ++ ;; Move forward over separator lines... ++ (while (and (not (eobp)) ++ (progn (move-to-left-margin) (not (eobp))) ++ (looking-at parsep)) ++ (forward-line 1)) ++ ;; @r{This decrements the loop} ++ (unless (eobp) (setq arg (1- arg))) ++ ;; ... and one more line. ++ (forward-line 1) ++@end group ++ ++@group ++ (if fill-prefix-regexp ++ ;; There is a fill prefix; it overrides parstart; ++ ;; we go forward line by line ++ (while (and (not (eobp)) ++ (progn (move-to-left-margin) (not (eobp))) ++ (not (looking-at parsep)) ++ (looking-at fill-prefix-regexp)) ++ (forward-line 1)) ++@end group ++ ++@group ++ ;; There is no fill prefix; ++ ;; we go forward character by character ++ (while (and (re-search-forward sp-parstart nil 1) ++ (progn (setq start (match-beginning 0)) ++ (goto-char start) ++ (not (eobp))) ++ (progn (move-to-left-margin) ++ (not (looking-at parsep))) ++ (or (not (looking-at parstart)) ++ (and use-hard-newlines ++ (not (get-text-property (1- start) 'hard))))) ++ (forward-char 1)) ++@end group ++ ++@group ++ ;; and if there is no fill prefix and if we are not at the end, ++ ;; go to whatever was found in the regular expression search ++ ;; for sp-parstart ++ (if (< (point) (point-max)) ++ (goto-char start)))) ++@end group ++@end smallexample ++ ++@findex eobp ++We can see that this is a decrementing counter @code{while} loop, ++using the expression @code{(setq arg (1- arg))} as the decrementer. ++That expression is not far from the @code{while}, but is hidden in ++another Lisp macro, an @code{unless} macro. Unless we are at the end ++of the buffer --- that is what the @code{eobp} function determines; it ++is an abbreviation of @samp{End Of Buffer P} --- we decrease the value ++of @code{arg} by one. ++ ++(If we are at the end of the buffer, we cannot go forward any more and ++the next loop of the @code{while} expression will test false since the ++test is an @code{and} with @code{(not (eobp))}. The @code{not} ++function means exactly as you expect; it is another name for ++@code{null}, a function that returns true when its argument is false.) ++ ++Interestingly, the loop count is not decremented until we leave the ++space between paragraphs, unless we come to the end of buffer or stop ++seeing the local value of the paragraph separator. ++ ++That second @code{while} also has a @code{(move-to-left-margin)} ++expression. The function is self-explanatory. It is inside a ++@code{progn} expression and not the last element of its body, so it is ++only invoked for its side effect, which is to move point to the left ++margin of the current line. ++ ++@findex looking-at ++The @code{looking-at} function is also self-explanatory; it returns ++true if the text after point matches the regular expression given as ++its argument. ++ ++The rest of the body of the loop looks difficult at first, but makes ++sense as you come to understand it. ++ ++@need 800 ++First consider what happens if there is a fill prefix: ++ ++@smallexample ++@group ++ (if fill-prefix-regexp ++ ;; There is a fill prefix; it overrides parstart; ++ ;; we go forward line by line ++ (while (and (not (eobp)) ++ (progn (move-to-left-margin) (not (eobp))) ++ (not (looking-at parsep)) ++ (looking-at fill-prefix-regexp)) ++ (forward-line 1)) ++@end group ++@end smallexample ++ ++@noindent ++This expression moves point forward line by line so long ++as four conditions are true: ++ ++@enumerate ++@item ++Point is not at the end of the buffer. ++ ++@item ++We can move to the left margin of the text and are ++not at the end of the buffer. ++ ++@item ++The text following point does not separate paragraphs. ++ ++@item ++The pattern following point is the fill prefix regular expression. ++@end enumerate ++ ++The last condition may be puzzling, until you remember that point was ++moved to the beginning of the line early in the @code{forward-paragraph} ++function. This means that if the text has a fill prefix, the ++@code{looking-at} function will see it. ++ ++@need 1250 ++Consider what happens when there is no fill prefix. ++ ++@smallexample ++@group ++ (while (and (re-search-forward sp-parstart nil 1) ++ (progn (setq start (match-beginning 0)) ++ (goto-char start) ++ (not (eobp))) ++ (progn (move-to-left-margin) ++ (not (looking-at parsep))) ++ (or (not (looking-at parstart)) ++ (and use-hard-newlines ++ (not (get-text-property (1- start) 'hard))))) ++ (forward-char 1)) ++@end group ++@end smallexample ++ ++@noindent ++This @code{while} loop has us searching forward for ++@code{sp-parstart}, which is the combination of possible whitespace ++with a the local value of the start of a paragraph or of a paragraph ++separator. (The latter two are within an expression starting ++@code{\(?:} so that they are not referenced by the ++@code{match-beginning} function.) ++ ++@need 800 ++The two expressions, ++ ++@smallexample ++@group ++(setq start (match-beginning 0)) ++(goto-char start) ++@end group ++@end smallexample ++ ++@noindent ++mean go to the start of the text matched by the regular expression ++search. ++ ++The @code{(match-beginning 0)} expression is new. It returns a number ++specifying the location of the start of the text that was matched by ++the last search. ++ ++The @code{match-beginning} function is used here because of a ++characteristic of a forward search: a successful forward search, ++regardless of whether it is a plain search or a regular expression ++search, moves point to the end of the text that is found. In this ++case, a successful search moves point to the end of the pattern for ++@code{sp-parstart}. ++ ++However, we want to put point at the end of the current paragraph, not ++somewhere else. Indeed, since the search possibly includes the ++paragraph separator, point may end up at the beginning of the next one ++unless we use an expression that includes @code{match-beginning}. ++ ++@findex match-beginning ++When given an argument of 0, @code{match-beginning} returns the ++position that is the start of the text matched by the most recent ++search. In this case, the most recent search looks for ++@code{sp-parstart}. The @code{(match-beginning 0)} expression returns ++the beginning position of that pattern, rather than the end position ++of that pattern. ++ ++(Incidentally, when passed a positive number as an argument, the ++@code{match-beginning} function returns the location of point at that ++parenthesized expression in the last search unless that parenthesized ++expression begins with @code{\(?:}. I don't know why @code{\(?:} ++appears here since the argument is 0.) ++ ++@need 1250 ++The last expression when there is no fill prefix is ++ ++@smallexample ++@group ++(if (< (point) (point-max)) ++ (goto-char start)))) ++@end group ++@end smallexample ++ ++@noindent ++This says that if there is no fill prefix and if we are not at the ++end, point should move to the beginning of whatever was found by the ++regular expression search for @code{sp-parstart}. ++ ++The full definition for the @code{forward-paragraph} function not only ++includes code for going forwards, but also code for going backwards. ++ ++If you are reading this inside of GNU Emacs and you want to see the ++whole function, you can type @kbd{C-h f} (@code{describe-function}) ++and the name of the function. This gives you the function ++documentation and the name of the library containing the function's ++source. Place point over the name of the library and press the RET ++key; you will be taken directly to the source. (Be sure to install ++your sources! Without them, you are like a person who tries to drive ++a car with his eyes shut!) ++ ++@node etags, Regexp Review, forward-paragraph, Regexp Search ++@section Create Your Own @file{TAGS} File ++@findex etags ++@cindex @file{TAGS} file, create own ++ ++Besides @kbd{C-h f} (@code{describe-function}), another way to see the ++source of a function is to type @kbd{M-.} (@code{find-tag}) and the ++name of the function when prompted for it. This is a good habit to ++get into. The @kbd{M-.} (@code{find-tag}) command takes you directly ++to the source for a function, variable, or node. The function depends ++on tags tables to tell it where to go. ++ ++If the @code{find-tag} function first asks you for the name of a ++@file{TAGS} table, give it the name of a @file{TAGS} file such as ++@file{/usr/local/src/emacs/src/TAGS}. (The exact path to your ++@file{TAGS} file depends on how your copy of Emacs was installed. I ++just told you the location that provides both my C and my Emacs Lisp ++sources.) ++ ++You can also create your own @file{TAGS} file for directories that ++lack one. ++ ++You often need to build and install tags tables yourself. They are ++not built automatically. A tags table is called a @file{TAGS} file; ++the name is in upper case letters. ++ ++You can create a @file{TAGS} file by calling the @code{etags} program ++that comes as a part of the Emacs distribution. Usually, @code{etags} ++is compiled and installed when Emacs is built. (@code{etags} is not ++an Emacs Lisp function or a part of Emacs; it is a C program.) ++ ++@need 1250 ++To create a @file{TAGS} file, first switch to the directory in which ++you want to create the file. In Emacs you can do this with the ++@kbd{M-x cd} command, or by visiting a file in the directory, or by ++listing the directory with @kbd{C-x d} (@code{dired}). Then run the ++compile command, with @w{@code{etags *.el}} as the command to execute ++ ++@smallexample ++M-x compile RET etags *.el RET ++@end smallexample ++ ++@noindent ++to create a @file{TAGS} file for Emacs Lisp. ++ ++For example, if you have a large number of files in your ++@file{~/emacs} directory, as I do---I have 137 @file{.el} files in it, ++of which I load 12---you can create a @file{TAGS} file for the Emacs ++Lisp files in that directory. ++ ++@need 1250 ++The @code{etags} program takes all the usual shell `wildcards'. For ++example, if you have two directories for which you want a single ++@file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where ++@file{../elisp/} is the second directory: ++ ++@smallexample ++M-x compile RET etags *.el ../elisp/*.el RET ++@end smallexample ++ ++@need 1250 ++Type ++ ++@smallexample ++M-x compile RET etags --help RET ++@end smallexample ++ ++@noindent ++to see a list of the options accepted by @code{etags} as well as a ++list of supported languages. ++ ++The @code{etags} program handles more than 20 languages, including ++Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java, ++LaTeX, Pascal, Perl, Postscript, Python, TeX, Texinfo, makefiles, and ++most assemblers. The program has no switches for specifying the ++language; it recognizes the language in an input file according to its ++file name and contents. ++ ++@file{etags} is very helpful when you are writing code yourself and ++want to refer back to functions you have already written. Just run ++@code{etags} again at intervals as you write new functions, so they ++become part of the @file{TAGS} file. ++ ++If you think an appropriate @file{TAGS} file already exists for what ++you want, but do not know where it is, you can use the @code{locate} ++program to attempt to find it. ++ ++Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list ++for you the full path names of all your @file{TAGS} files. On my ++system, this command lists 34 @file{TAGS} files. On the other hand, a ++`plain vanilla' system I recently installed did not contain any ++@file{TAGS} files. ++ ++If the tags table you want has been created, you can use the @code{M-x ++visit-tags-table} command to specify it. Otherwise, you will need to ++create the tag table yourself and then use @code{M-x ++visit-tags-table}. ++ ++@subsubheading Building Tags in the Emacs sources ++@cindex Building Tags in the Emacs sources ++@cindex Tags in the Emacs sources ++@findex make tags ++ ++The GNU Emacs sources come with a @file{Makefile} that contains a ++sophisticated @code{etags} command that creates, collects, and merges ++tags tables from all over the Emacs sources and puts the information ++into one @file{TAGS} file in the @file{src/} directory. (The ++@file{src/} directory is below the top level of your Emacs directory.) ++ ++@need 1250 ++To build this @file{TAGS} file, go to the top level of your Emacs ++source directory and run the compile command @code{make tags}: ++ ++@smallexample ++M-x compile RET make tags RET ++@end smallexample ++ ++@noindent ++(The @code{make tags} command works well with the GNU Emacs sources, ++as well as with some other source packages.) ++ ++For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs ++Manual}. ++ ++@node Regexp Review, re-search Exercises, etags, Regexp Search ++@comment node-name, next, previous, up ++@section Review ++ ++Here is a brief summary of some recently introduced functions. ++ ++@table @code ++@item while ++Repeatedly evaluate the body of the expression so long as the first ++element of the body tests true. Then return @code{nil}. (The ++expression is evaluated only for its side effects.) ++ ++@need 1250 ++For example: ++ ++@smallexample ++@group ++(let ((foo 2)) ++ (while (> foo 0) ++ (insert (format "foo is %d.\n" foo)) ++ (setq foo (1- foo)))) ++ ++ @result{} foo is 2. ++ foo is 1. ++ nil ++@end group ++@end smallexample ++ ++@noindent ++(The @code{insert} function inserts its arguments at point; the ++@code{format} function returns a string formatted from its arguments ++the way @code{message} formats its arguments; @code{\n} produces a new ++line.) ++ ++@item re-search-forward ++Search for a pattern, and if the pattern is found, move point to rest ++just after it. ++ ++@noindent ++Takes four arguments, like @code{search-forward}: ++ ++@enumerate ++@item ++A regular expression that specifies the pattern to search for. ++(Remember to put quotation marks around this argument!) ++ ++@item ++Optionally, the limit of the search. ++ ++@item ++Optionally, what to do if the search fails, return @code{nil} or an ++error message. ++ ++@item ++Optionally, how many times to repeat the search; if negative, the ++search goes backwards. ++@end enumerate ++ ++@item let* ++Bind some variables locally to particular values, ++and then evaluate the remaining arguments, returning the value of the ++last one. While binding the local variables, use the local values of ++variables bound earlier, if any. ++ ++@need 1250 ++For example: ++ ++@smallexample ++@group ++(let* ((foo 7) ++ (bar (* 3 foo))) ++ (message "`bar' is %d." bar)) ++ @result{} `bar' is 21. ++@end group ++@end smallexample ++ ++@item match-beginning ++Return the position of the start of the text found by the last regular ++expression search. ++ ++@item looking-at ++Return @code{t} for true if the text after point matches the argument, ++which should be a regular expression. ++ ++@item eobp ++Return @code{t} for true if point is at the end of the accessible part ++of a buffer. The end of the accessible part is the end of the buffer ++if the buffer is not narrowed; it is the end of the narrowed part if ++the buffer is narrowed. ++@end table ++ ++@need 1500 ++@node re-search Exercises, , Regexp Review, Regexp Search ++@section Exercises with @code{re-search-forward} ++ ++@itemize @bullet ++@item ++Write a function to search for a regular expression that matches two ++or more blank lines in sequence. ++ ++@item ++Write a function to search for duplicated words, such as `the the'. ++@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs ++Manual}, for information on how to write a regexp (a regular ++expression) to match a string that is composed of two identical ++halves. You can devise several regexps; some are better than others. ++The function I use is described in an appendix, along with several ++regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. ++@end itemize ++ ++@node Counting Words, Words in a defun, Regexp Search, Top ++@chapter Counting: Repetition and Regexps ++@cindex Repetition for word counting ++@cindex Regular expressions for word counting ++ ++Repetition and regular expression searches are powerful tools that you ++often use when you write code in Emacs Lisp. This chapter illustrates ++the use of regular expression searches through the construction of ++word count commands using @code{while} loops and recursion. ++ ++@menu ++* Why Count Words:: ++* count-words-region:: Use a regexp, but find a problem. ++* recursive-count-words:: Start with case of no words in region. ++* Counting Exercise:: ++@end menu ++ ++@node Why Count Words, count-words-region, Counting Words, Counting Words ++@ifnottex ++@unnumberedsec Counting words ++@end ifnottex ++ ++The standard Emacs distribution contains a function for counting the ++number of lines within a region. However, there is no corresponding ++function for counting words. ++ ++Certain types of writing ask you to count words. Thus, if you write ++an essay, you may be limited to 800 words; if you write a novel, you ++may discipline yourself to write 1000 words a day. It seems odd to me ++that Emacs lacks a word count command. Perhaps people use Emacs ++mostly for code or types of documentation that do not require word ++counts; or perhaps they restrict themselves to the operating system ++word count command, @code{wc}. Alternatively, people may follow ++the publishers' convention and compute a word count by dividing the ++number of characters in a document by five. In any event, here are ++commands to count words. ++ ++@node count-words-region, recursive-count-words, Why Count Words, Counting Words ++@comment node-name, next, previous, up ++@section The @code{count-words-region} Function ++@findex count-words-region ++ ++A word count command could count words in a line, paragraph, region, ++or buffer. What should the command cover? You could design the ++command to count the number of words in a complete buffer. However, ++the Emacs tradition encourages flexibility---you may want to count ++words in just a section, rather than all of a buffer. So it makes ++more sense to design the command to count the number of words in a ++region. Once you have a @code{count-words-region} command, you can, ++if you wish, count words in a whole buffer by marking it with ++@w{@kbd{C-x h}} (@code{mark-whole-buffer}). ++ ++Clearly, counting words is a repetitive act: starting from the ++beginning of the region, you count the first word, then the second ++word, then the third word, and so on, until you reach the end of the ++region. This means that word counting is ideally suited to recursion ++or to a @code{while} loop. ++ ++@menu ++* Design count-words-region:: The definition using a @code{while} loop. ++* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. ++@end menu ++ ++@node Design count-words-region, Whitespace Bug, count-words-region, count-words-region ++@ifnottex ++@unnumberedsubsec Designing @code{count-words-region} ++@end ifnottex ++ ++First, we will implement the word count command with a @code{while} ++loop, then with recursion. The command will, of course, be ++interactive. ++ ++@need 800 ++The template for an interactive function definition is, as always: ++ ++@smallexample ++@group ++(defun @var{name-of-function} (@var{argument-list}) ++ "@var{documentation}@dots{}" ++ (@var{interactive-expression}@dots{}) ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++What we need to do is fill in the slots. ++ ++The name of the function should be self-explanatory and similar to the ++existing @code{count-lines-region} name. This makes the name easier ++to remember. @code{count-words-region} is a good choice. ++ ++The function counts words within a region. This means that the ++argument list must contain symbols that are bound to the two ++positions, the beginning and end of the region. These two positions ++can be called @samp{beginning} and @samp{end} respectively. The first ++line of the documentation should be a single sentence, since that is ++all that is printed as documentation by a command such as ++@code{apropos}. The interactive expression will be of the form ++@samp{(interactive "r")}, since that will cause Emacs to pass the ++beginning and end of the region to the function's argument list. All ++this is routine. ++ ++The body of the function needs to be written to do three tasks: ++first, to set up conditions under which the @code{while} loop can ++count words, second, to run the @code{while} loop, and third, to send ++a message to the user. ++ ++When a user calls @code{count-words-region}, point may be at the ++beginning or the end of the region. However, the counting process ++must start at the beginning of the region. This means we will want ++to put point there if it is not already there. Executing ++@code{(goto-char beginning)} ensures this. Of course, we will want to ++return point to its expected position when the function finishes its ++work. For this reason, the body must be enclosed in a ++@code{save-excursion} expression. ++ ++The central part of the body of the function consists of a ++@code{while} loop in which one expression jumps point forward word by ++word, and another expression counts those jumps. The true-or-false-test ++of the @code{while} loop should test true so long as point should jump ++forward, and false when point is at the end of the region. ++ ++We could use @code{(forward-word 1)} as the expression for moving point ++forward word by word, but it is easier to see what Emacs identifies as a ++`word' if we use a regular expression search. ++ ++A regular expression search that finds the pattern for which it is ++searching leaves point after the last character matched. This means ++that a succession of successful word searches will move point forward ++word by word. ++ ++As a practical matter, we want the regular expression search to jump ++over whitespace and punctuation between words as well as over the ++words themselves. A regexp that refuses to jump over interword ++whitespace would never jump more than one word! This means that ++the regexp should include the whitespace and punctuation that follows ++a word, if any, as well as the word itself. (A word may end a buffer ++and not have any following whitespace or punctuation, so that part of ++the regexp must be optional.) ++ ++Thus, what we want for the regexp is a pattern defining one or more ++word constituent characters followed, optionally, by one or more ++characters that are not word constituents. The regular expression for ++this is: ++ ++@smallexample ++\w+\W* ++@end smallexample ++ ++@noindent ++The buffer's syntax table determines which characters are and are not ++word constituents. (@xref{Syntax, , What Constitutes a Word or ++Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The ++Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , ++Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.) ++ ++@need 800 ++The search expression looks like this: ++ ++@smallexample ++(re-search-forward "\\w+\\W*") ++@end smallexample ++ ++@noindent ++(Note that paired backslashes precede the @samp{w} and @samp{W}. A ++single backslash has special meaning to the Emacs Lisp interpreter. ++It indicates that the following character is interpreted differently ++than usual. For example, the two characters, @samp{\n}, stand for ++@samp{newline}, rather than for a backslash followed by @samp{n}. Two ++backslashes in a row stand for an ordinary, `unspecial' backslash, so ++Emacs Lisp interpreter ends of seeing a single backslash followed by a ++letter. So it discovers the letter is special.) ++ ++We need a counter to count how many words there are; this variable ++must first be set to 0 and then incremented each time Emacs goes ++around the @code{while} loop. The incrementing expression is simply: ++ ++@smallexample ++(setq count (1+ count)) ++@end smallexample ++ ++Finally, we want to tell the user how many words there are in the ++region. The @code{message} function is intended for presenting this ++kind of information to the user. The message has to be phrased so ++that it reads properly regardless of how many words there are in the ++region: we don't want to say that ``there are 1 words in the region''. ++The conflict between singular and plural is ungrammatical. We can ++solve this problem by using a conditional expression that evaluates ++different messages depending on the number of words in the region. ++There are three possibilities: no words in the region, one word in the ++region, and more than one word. This means that the @code{cond} ++special form is appropriate. ++ ++@need 1500 ++All this leads to the following function definition: ++ ++@smallexample ++@group ++;;; @r{First version; has bugs!} ++(defun count-words-region (beginning end) ++ "Print number of words in the region. ++Words are defined as at least one word-constituent ++character followed by at least one character that ++is not a word-constituent. The buffer's syntax ++table determines which characters these are." ++ (interactive "r") ++ (message "Counting words in region ... ") ++@end group ++ ++@group ++;;; @r{1. Set up appropriate conditions.} ++ (save-excursion ++ (goto-char beginning) ++ (let ((count 0)) ++@end group ++ ++@group ++;;; @r{2. Run the} while @r{loop.} ++ (while (< (point) end) ++ (re-search-forward "\\w+\\W*") ++ (setq count (1+ count))) ++@end group ++ ++@group ++;;; @r{3. Send a message to the user.} ++ (cond ((zerop count) ++ (message ++ "The region does NOT have any words.")) ++ ((= 1 count) ++ (message ++ "The region has 1 word.")) ++ (t ++ (message ++ "The region has %d words." count)))))) ++@end group ++@end smallexample ++ ++@noindent ++As written, the function works, but not in all circumstances. ++ ++@node Whitespace Bug, , Design count-words-region, count-words-region ++@comment node-name, next, previous, up ++@subsection The Whitespace Bug in @code{count-words-region} ++ ++The @code{count-words-region} command described in the preceding ++section has two bugs, or rather, one bug with two manifestations. ++First, if you mark a region containing only whitespace in the middle ++of some text, the @code{count-words-region} command tells you that the ++region contains one word! Second, if you mark a region containing ++only whitespace at the end of the buffer or the accessible portion of ++a narrowed buffer, the command displays an error message that looks ++like this: ++ ++@smallexample ++Search failed: "\\w+\\W*" ++@end smallexample ++ ++If you are reading this in Info in GNU Emacs, you can test for these ++bugs yourself. ++ ++First, evaluate the function in the usual manner to install it. ++@ifinfo ++Here is a copy of the definition. Place your cursor after the closing ++parenthesis and type @kbd{C-x C-e} to install it. ++ ++@smallexample ++@group ++;; @r{First version; has bugs!} ++(defun count-words-region (beginning end) ++ "Print number of words in the region. ++Words are defined as at least one word-constituent character followed ++by at least one character that is not a word-constituent. The buffer's ++syntax table determines which characters these are." ++@end group ++@group ++ (interactive "r") ++ (message "Counting words in region ... ") ++@end group ++ ++@group ++;;; @r{1. Set up appropriate conditions.} ++ (save-excursion ++ (goto-char beginning) ++ (let ((count 0)) ++@end group ++ ++@group ++;;; @r{2. Run the} while @r{loop.} ++ (while (< (point) end) ++ (re-search-forward "\\w+\\W*") ++ (setq count (1+ count))) ++@end group ++ ++@group ++;;; @r{3. Send a message to the user.} ++ (cond ((zerop count) ++ (message "The region does NOT have any words.")) ++ ((= 1 count) (message "The region has 1 word.")) ++ (t (message "The region has %d words." count)))))) ++@end group ++@end smallexample ++@end ifinfo ++ ++@need 1000 ++If you wish, you can also install this keybinding by evaluating it: ++ ++@smallexample ++(global-set-key "\C-c=" 'count-words-region) ++@end smallexample ++ ++To conduct the first test, set mark and point to the beginning and end ++of the following line and then type @kbd{C-c =} (or @kbd{M-x ++count-words-region} if you have not bound @kbd{C-c =}): ++ ++@smallexample ++ one two three ++@end smallexample ++ ++@noindent ++Emacs will tell you, correctly, that the region has three words. ++ ++Repeat the test, but place mark at the beginning of the line and place ++point just @emph{before} the word @samp{one}. Again type the command ++@kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you ++that the region has no words, since it is composed only of the ++whitespace at the beginning of the line. But instead Emacs tells you ++that the region has one word! ++ ++For the third test, copy the sample line to the end of the ++@file{*scratch*} buffer and then type several spaces at the end of the ++line. Place mark right after the word @samp{three} and point at the ++end of line. (The end of the line will be the end of the buffer.) ++Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before. ++Again, Emacs should tell you that the region has no words, since it is ++composed only of the whitespace at the end of the line. Instead, ++Emacs displays an error message saying @samp{Search failed}. ++ ++The two bugs stem from the same problem. ++ ++Consider the first manifestation of the bug, in which the command ++tells you that the whitespace at the beginning of the line contains ++one word. What happens is this: The @code{M-x count-words-region} ++command moves point to the beginning of the region. The @code{while} ++tests whether the value of point is smaller than the value of ++@code{end}, which it is. Consequently, the regular expression search ++looks for and finds the first word. It leaves point after the word. ++@code{count} is set to one. The @code{while} loop repeats; but this ++time the value of point is larger than the value of @code{end}, the ++loop is exited; and the function displays a message saying the number ++of words in the region is one. In brief, the regular expression ++search looks for and finds the word even though it is outside ++the marked region. ++ ++In the second manifestation of the bug, the region is whitespace at ++the end of the buffer. Emacs says @samp{Search failed}. What happens ++is that the true-or-false-test in the @code{while} loop tests true, so ++the search expression is executed. But since there are no more words ++in the buffer, the search fails. ++ ++In both manifestations of the bug, the search extends or attempts to ++extend outside of the region. ++ ++The solution is to limit the search to the region---this is a fairly ++simple action, but as you may have come to expect, it is not quite as ++simple as you might think. ++ ++As we have seen, the @code{re-search-forward} function takes a search ++pattern as its first argument. But in addition to this first, ++mandatory argument, it accepts three optional arguments. The optional ++second argument bounds the search. The optional third argument, if ++@code{t}, causes the function to return @code{nil} rather than signal ++an error if the search fails. The optional fourth argument is a ++repeat count. (In Emacs, you can see a function's documentation by ++typing @kbd{C-h f}, the name of the function, and then @key{RET}.) ++ ++In the @code{count-words-region} definition, the value of the end of ++the region is held by the variable @code{end} which is passed as an ++argument to the function. Thus, we can add @code{end} as an argument ++to the regular expression search expression: ++ ++@smallexample ++(re-search-forward "\\w+\\W*" end) ++@end smallexample ++ ++However, if you make only this change to the @code{count-words-region} ++definition and then test the new version of the definition on a ++stretch of whitespace, you will receive an error message saying ++@samp{Search failed}. ++ ++What happens is this: the search is limited to the region, and fails ++as you expect because there are no word-constituent characters in the ++region. Since it fails, we receive an error message. But we do not ++want to receive an error message in this case; we want to receive the ++message that "The region does NOT have any words." ++ ++The solution to this problem is to provide @code{re-search-forward} ++with a third argument of @code{t}, which causes the function to return ++@code{nil} rather than signal an error if the search fails. ++ ++However, if you make this change and try it, you will see the message ++``Counting words in region ... '' and @dots{} you will keep on seeing ++that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}). ++ ++Here is what happens: the search is limited to the region, as before, ++and it fails because there are no word-constituent characters in the ++region, as expected. Consequently, the @code{re-search-forward} ++expression returns @code{nil}. It does nothing else. In particular, ++it does not move point, which it does as a side effect if it finds the ++search target. After the @code{re-search-forward} expression returns ++@code{nil}, the next expression in the @code{while} loop is evaluated. ++This expression increments the count. Then the loop repeats. The ++true-or-false-test tests true because the value of point is still less ++than the value of end, since the @code{re-search-forward} expression ++did not move point. @dots{} and the cycle repeats @dots{} ++ ++The @code{count-words-region} definition requires yet another ++modification, to cause the true-or-false-test of the @code{while} loop ++to test false if the search fails. Put another way, there are two ++conditions that must be satisfied in the true-or-false-test before the ++word count variable is incremented: point must still be within the ++region and the search expression must have found a word to count. ++ ++Since both the first condition and the second condition must be true ++together, the two expressions, the region test and the search ++expression, can be joined with an @code{and} special form and embedded in ++the @code{while} loop as the true-or-false-test, like this: ++ ++@smallexample ++(and (< (point) end) (re-search-forward "\\w+\\W*" end t)) ++@end smallexample ++ ++@c colon in printed section title causes problem in Info cross reference ++@c also trouble with an overfull hbox ++@iftex ++@noindent ++(For information about @code{and}, see ++@ref{kill-new function, , The @code{kill-new} function}.) ++@end iftex ++@ifinfo ++@noindent ++(@xref{kill-new function, , The @code{kill-new} function}, for ++information about @code{and}.) ++@end ifinfo ++ ++The @code{re-search-forward} expression returns @code{t} if the search ++succeeds and as a side effect moves point. Consequently, as words are ++found, point is moved through the region. When the search expression ++fails to find another word, or when point reaches the end of the ++region, the true-or-false-test tests false, the @code{while} loop ++exits, and the @code{count-words-region} function displays one or ++other of its messages. ++ ++After incorporating these final changes, the @code{count-words-region} ++works without bugs (or at least, without bugs that I have found!). ++Here is what it looks like: ++ ++@smallexample ++@group ++;;; @r{Final version:} @code{while} ++(defun count-words-region (beginning end) ++ "Print number of words in the region." ++ (interactive "r") ++ (message "Counting words in region ... ") ++@end group ++ ++@group ++;;; @r{1. Set up appropriate conditions.} ++ (save-excursion ++ (let ((count 0)) ++ (goto-char beginning) ++@end group ++ ++@group ++;;; @r{2. Run the} while @r{loop.} ++ (while (and (< (point) end) ++ (re-search-forward "\\w+\\W*" end t)) ++ (setq count (1+ count))) ++@end group ++ ++@group ++;;; @r{3. Send a message to the user.} ++ (cond ((zerop count) ++ (message ++ "The region does NOT have any words.")) ++ ((= 1 count) ++ (message ++ "The region has 1 word.")) ++ (t ++ (message ++ "The region has %d words." count)))))) ++@end group ++@end smallexample ++ ++@node recursive-count-words, Counting Exercise, count-words-region, Counting Words ++@comment node-name, next, previous, up ++@section Count Words Recursively ++@cindex Count words recursively ++@cindex Recursively counting words ++@cindex Words, counted recursively ++ ++You can write the function for counting words recursively as well as ++with a @code{while} loop. Let's see how this is done. ++ ++First, we need to recognize that the @code{count-words-region} ++function has three jobs: it sets up the appropriate conditions for ++counting to occur; it counts the words in the region; and it sends a ++message to the user telling how many words there are. ++ ++If we write a single recursive function to do everything, we will ++receive a message for every recursive call. If the region contains 13 ++words, we will receive thirteen messages, one right after the other. ++We don't want this! Instead, we must write two functions to do the ++job, one of which (the recursive function) will be used inside of the ++other. One function will set up the conditions and display the ++message; the other will return the word count. ++ ++Let us start with the function that causes the message to be displayed. ++We can continue to call this @code{count-words-region}. ++ ++This is the function that the user will call. It will be interactive. ++Indeed, it will be similar to our previous versions of this ++function, except that it will call @code{recursive-count-words} to ++determine how many words are in the region. ++ ++@need 1250 ++We can readily construct a template for this function, based on our ++previous versions: ++ ++@smallexample ++@group ++;; @r{Recursive version; uses regular expression search} ++(defun count-words-region (beginning end) ++ "@var{documentation}@dots{}" ++ (@var{interactive-expression}@dots{}) ++@end group ++@group ++ ++;;; @r{1. Set up appropriate conditions.} ++ (@var{explanatory message}) ++ (@var{set-up functions}@dots{} ++@end group ++@group ++ ++;;; @r{2. Count the words.} ++ @var{recursive call} ++@end group ++@group ++ ++;;; @r{3. Send a message to the user.} ++ @var{message providing word count})) ++@end group ++@end smallexample ++ ++The definition looks straightforward, except that somehow the count ++returned by the recursive call must be passed to the message ++displaying the word count. A little thought suggests that this can be ++done by making use of a @code{let} expression: we can bind a variable ++in the varlist of a @code{let} expression to the number of words in ++the region, as returned by the recursive call; and then the ++@code{cond} expression, using binding, can display the value to the ++user. ++ ++Often, one thinks of the binding within a @code{let} expression as ++somehow secondary to the `primary' work of a function. But in this ++case, what you might consider the `primary' job of the function, ++counting words, is done within the @code{let} expression. ++ ++@need 1250 ++Using @code{let}, the function definition looks like this: ++ ++@smallexample ++@group ++(defun count-words-region (beginning end) ++ "Print number of words in the region." ++ (interactive "r") ++@end group ++ ++@group ++;;; @r{1. Set up appropriate conditions.} ++ (message "Counting words in region ... ") ++ (save-excursion ++ (goto-char beginning) ++@end group ++ ++@group ++;;; @r{2. Count the words.} ++ (let ((count (recursive-count-words end))) ++@end group ++ ++@group ++;;; @r{3. Send a message to the user.} ++ (cond ((zerop count) ++ (message ++ "The region does NOT have any words.")) ++ ((= 1 count) ++ (message ++ "The region has 1 word.")) ++ (t ++ (message ++ "The region has %d words." count)))))) ++@end group ++@end smallexample ++ ++Next, we need to write the recursive counting function. ++ ++A recursive function has at least three parts: the `do-again-test', the ++`next-step-expression', and the recursive call. ++ ++The do-again-test determines whether the function will or will not be ++called again. Since we are counting words in a region and can use a ++function that moves point forward for every word, the do-again-test ++can check whether point is still within the region. The do-again-test ++should find the value of point and determine whether point is before, ++at, or after the value of the end of the region. We can use the ++@code{point} function to locate point. Clearly, we must pass the ++value of the end of the region to the recursive counting function as an ++argument. ++ ++In addition, the do-again-test should also test whether the search finds a ++word. If it does not, the function should not call itself again. ++ ++The next-step-expression changes a value so that when the recursive ++function is supposed to stop calling itself, it stops. More ++precisely, the next-step-expression changes a value so that at the ++right time, the do-again-test stops the recursive function from ++calling itself again. In this case, the next-step-expression can be ++the expression that moves point forward, word by word. ++ ++The third part of a recursive function is the recursive call. ++ ++Somewhere, also, we also need a part that does the `work' of the ++function, a part that does the counting. A vital part! ++ ++@need 1250 ++But already, we have an outline of the recursive counting function: ++ ++@smallexample ++@group ++(defun recursive-count-words (region-end) ++ "@var{documentation}@dots{}" ++ @var{do-again-test} ++ @var{next-step-expression} ++ @var{recursive call}) ++@end group ++@end smallexample ++ ++Now we need to fill in the slots. Let's start with the simplest cases ++first: if point is at or beyond the end of the region, there cannot ++be any words in the region, so the function should return zero. ++Likewise, if the search fails, there are no words to count, so the ++function should return zero. ++ ++On the other hand, if point is within the region and the search ++succeeds, the function should call itself again. ++ ++@need 800 ++Thus, the do-again-test should look like this: ++ ++@smallexample ++@group ++(and (< (point) region-end) ++ (re-search-forward "\\w+\\W*" region-end t)) ++@end group ++@end smallexample ++ ++Note that the search expression is part of the do-again-test---the ++function returns @code{t} if its search succeeds and @code{nil} if it ++fails. (@xref{Whitespace Bug, , The Whitespace Bug in ++@code{count-words-region}}, for an explanation of how ++@code{re-search-forward} works.) ++ ++The do-again-test is the true-or-false test of an @code{if} clause. ++Clearly, if the do-again-test succeeds, the then-part of the @code{if} ++clause should call the function again; but if it fails, the else-part ++should return zero since either point is outside the region or the ++search failed because there were no words to find. ++ ++But before considering the recursive call, we need to consider the ++next-step-expression. What is it? Interestingly, it is the search ++part of the do-again-test. ++ ++In addition to returning @code{t} or @code{nil} for the ++do-again-test, @code{re-search-forward} moves point forward as a side ++effect of a successful search. This is the action that changes the ++value of point so that the recursive function stops calling itself ++when point completes its movement through the region. Consequently, ++the @code{re-search-forward} expression is the next-step-expression. ++ ++@need 1200 ++In outline, then, the body of the @code{recursive-count-words} ++function looks like this: ++ ++@smallexample ++@group ++(if @var{do-again-test-and-next-step-combined} ++ ;; @r{then} ++ @var{recursive-call-returning-count} ++ ;; @r{else} ++ @var{return-zero}) ++@end group ++@end smallexample ++ ++How to incorporate the mechanism that counts? ++ ++If you are not used to writing recursive functions, a question like ++this can be troublesome. But it can and should be approached ++systematically. ++ ++We know that the counting mechanism should be associated in some way ++with the recursive call. Indeed, since the next-step-expression moves ++point forward by one word, and since a recursive call is made for ++each word, the counting mechanism must be an expression that adds one ++to the value returned by a call to @code{recursive-count-words}. ++ ++@need 800 ++Consider several cases: ++ ++@itemize @bullet ++@item ++If there are two words in the region, the function should return ++a value resulting from adding one to the value returned when it counts ++the first word, plus the number returned when it counts the remaining ++words in the region, which in this case is one. ++ ++@item ++If there is one word in the region, the function should return ++a value resulting from adding one to the value returned when it counts ++that word, plus the number returned when it counts the remaining ++words in the region, which in this case is zero. ++ ++@item ++If there are no words in the region, the function should return zero. ++@end itemize ++ ++From the sketch we can see that the else-part of the @code{if} returns ++zero for the case of no words. This means that the then-part of the ++@code{if} must return a value resulting from adding one to the value ++returned from a count of the remaining words. ++ ++@need 1200 ++The expression will look like this, where @code{1+} is a function that ++adds one to its argument. ++ ++@smallexample ++(1+ (recursive-count-words region-end)) ++@end smallexample ++ ++@need 1200 ++The whole @code{recursive-count-words} function will then look like ++this: ++ ++@smallexample ++@group ++(defun recursive-count-words (region-end) ++ "@var{documentation}@dots{}" ++ ++;;; @r{1. do-again-test} ++ (if (and (< (point) region-end) ++ (re-search-forward "\\w+\\W*" region-end t)) ++@end group ++ ++@group ++;;; @r{2. then-part: the recursive call} ++ (1+ (recursive-count-words region-end)) ++ ++;;; @r{3. else-part} ++ 0)) ++@end group ++@end smallexample ++ ++@need 1250 ++Let's examine how this works: ++ ++If there are no words in the region, the else part of the @code{if} ++expression is evaluated and consequently the function returns zero. ++ ++If there is one word in the region, the value of point is less than ++the value of @code{region-end} and the search succeeds. In this case, ++the true-or-false-test of the @code{if} expression tests true, and the ++then-part of the @code{if} expression is evaluated. The counting ++expression is evaluated. This expression returns a value (which will ++be the value returned by the whole function) that is the sum of one ++added to the value returned by a recursive call. ++ ++Meanwhile, the next-step-expression has caused point to jump over the ++first (and in this case only) word in the region. This means that ++when @code{(recursive-count-words region-end)} is evaluated a second ++time, as a result of the recursive call, the value of point will be ++equal to or greater than the value of region end. So this time, ++@code{recursive-count-words} will return zero. The zero will be added ++to one, and the original evaluation of @code{recursive-count-words} ++will return one plus zero, which is one, which is the correct amount. ++ ++Clearly, if there are two words in the region, the first call to ++@code{recursive-count-words} returns one added to the value returned ++by calling @code{recursive-count-words} on a region containing the ++remaining word---that is, it adds one to one, producing two, which is ++the correct amount. ++ ++Similarly, if there are three words in the region, the first call to ++@code{recursive-count-words} returns one added to the value returned ++by calling @code{recursive-count-words} on a region containing the ++remaining two words---and so on and so on. ++ ++@need 1250 ++@noindent ++With full documentation the two functions look like this: ++ ++@need 1250 ++@noindent ++The recursive function: ++ ++@findex recursive-count-words ++@smallexample ++@group ++(defun recursive-count-words (region-end) ++ "Number of words between point and REGION-END." ++@end group ++ ++@group ++;;; @r{1. do-again-test} ++ (if (and (< (point) region-end) ++ (re-search-forward "\\w+\\W*" region-end t)) ++@end group ++ ++@group ++;;; @r{2. then-part: the recursive call} ++ (1+ (recursive-count-words region-end)) ++ ++;;; @r{3. else-part} ++ 0)) ++@end group ++@end smallexample ++ ++@need 800 ++@noindent ++The wrapper: ++ ++@smallexample ++@group ++;;; @r{Recursive version} ++(defun count-words-region (beginning end) ++ "Print number of words in the region. ++@end group ++ ++@group ++Words are defined as at least one word-constituent ++character followed by at least one character that is ++not a word-constituent. The buffer's syntax table ++determines which characters these are." ++@end group ++@group ++ (interactive "r") ++ (message "Counting words in region ... ") ++ (save-excursion ++ (goto-char beginning) ++ (let ((count (recursive-count-words end))) ++@end group ++@group ++ (cond ((zerop count) ++ (message ++ "The region does NOT have any words.")) ++@end group ++@group ++ ((= 1 count) ++ (message "The region has 1 word.")) ++ (t ++ (message ++ "The region has %d words." count)))))) ++@end group ++@end smallexample ++ ++@node Counting Exercise, , recursive-count-words, Counting Words ++@section Exercise: Counting Punctuation ++ ++Using a @code{while} loop, write a function to count the number of ++punctuation marks in a region---period, comma, semicolon, colon, ++exclamation mark, and question mark. Do the same using recursion. ++ ++@node Words in a defun, Readying a Graph, Counting Words, Top ++@chapter Counting Words in a @code{defun} ++@cindex Counting words in a @code{defun} ++@cindex Word counting in a @code{defun} ++ ++Our next project is to count the number of words in a function ++definition. Clearly, this can be done using some variant of ++@code{count-word-region}. @xref{Counting Words, , Counting Words: ++Repetition and Regexps}. If we are just going to count the words in ++one definition, it is easy enough to mark the definition with the ++@kbd{C-M-h} (@code{mark-defun}) command, and then call ++@code{count-word-region}. ++ ++However, I am more ambitious: I want to count the words and symbols in ++every definition in the Emacs sources and then print a graph that ++shows how many functions there are of each length: how many contain 40 ++to 49 words or symbols, how many contain 50 to 59 words or symbols, ++and so on. I have often been curious how long a typical function is, ++and this will tell. ++ ++@menu ++* Divide and Conquer:: ++* Words and Symbols:: What to count? ++* Syntax:: What constitutes a word or symbol? ++* count-words-in-defun:: Very like @code{count-words}. ++* Several defuns:: Counting several defuns in a file. ++* Find a File:: Do you want to look at a file? ++* lengths-list-file:: A list of the lengths of many definitions. ++* Several files:: Counting in definitions in different files. ++* Several files recursively:: Recursively counting in different files. ++* Prepare the data:: Prepare the data for display in a graph. ++@end menu ++ ++@node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun ++@ifnottex ++@unnumberedsec Divide and Conquer ++@end ifnottex ++ ++Described in one phrase, the histogram project is daunting; but ++divided into numerous small steps, each of which we can take one at a ++time, the project becomes less fearsome. Let us consider what the ++steps must be: ++ ++@itemize @bullet ++@item ++First, write a function to count the words in one definition. This ++includes the problem of handling symbols as well as words. ++ ++@item ++Second, write a function to list the numbers of words in each function ++in a file. This function can use the @code{count-words-in-defun} ++function. ++ ++@item ++Third, write a function to list the numbers of words in each function ++in each of several files. This entails automatically finding the ++various files, switching to them, and counting the words in the ++definitions within them. ++ ++@item ++Fourth, write a function to convert the list of numbers that we ++created in step three to a form that will be suitable for printing as ++a graph. ++ ++@item ++Fifth, write a function to print the results as a graph. ++@end itemize ++ ++This is quite a project! But if we take each step slowly, it will not ++be difficult. ++ ++@node Words and Symbols, Syntax, Divide and Conquer, Words in a defun ++@section What to Count? ++@cindex Words and symbols in defun ++ ++When we first start thinking about how to count the words in a ++function definition, the first question is (or ought to be) what are ++we going to count? When we speak of `words' with respect to a Lisp ++function definition, we are actually speaking, in large part, of ++`symbols'. For example, the following @code{multiply-by-seven} ++function contains the five symbols @code{defun}, ++@code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In ++addition, in the documentation string, it contains the four words ++@samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The ++symbol @samp{number} is repeated, so the definition contains a total ++of ten words and symbols. ++ ++@smallexample ++@group ++(defun multiply-by-seven (number) ++ "Multiply NUMBER by seven." ++ (* 7 number)) ++@end group ++@end smallexample ++ ++@noindent ++However, if we mark the @code{multiply-by-seven} definition with ++@kbd{C-M-h} (@code{mark-defun}), and then call ++@code{count-words-region} on it, we will find that ++@code{count-words-region} claims the definition has eleven words, not ++ten! Something is wrong! ++ ++The problem is twofold: @code{count-words-region} does not count the ++@samp{*} as a word, and it counts the single symbol, ++@code{multiply-by-seven}, as containing three words. The hyphens are ++treated as if they were interword spaces rather than intraword ++connectors: @samp{multiply-by-seven} is counted as if it were written ++@samp{multiply by seven}. ++ ++The cause of this confusion is the regular expression search within ++the @code{count-words-region} definition that moves point forward word ++by word. In the canonical version of @code{count-words-region}, the ++regexp is: ++ ++@smallexample ++"\\w+\\W*" ++@end smallexample ++ ++@noindent ++This regular expression is a pattern defining one or more word ++constituent characters possibly followed by one or more characters ++that are not word constituents. What is meant by `word constituent ++characters' brings us to the issue of syntax, which is worth a section ++of its own. ++ ++@node Syntax, count-words-in-defun, Words and Symbols, Words in a defun ++@section What Constitutes a Word or Symbol? ++@cindex Syntax categories and tables ++ ++Emacs treats different characters as belonging to different ++@dfn{syntax categories}. For example, the regular expression, ++@samp{\\w+}, is a pattern specifying one or more @emph{word ++constituent} characters. Word constituent characters are members of ++one syntax category. Other syntax categories include the class of ++punctuation characters, such as the period and the comma, and the ++class of whitespace characters, such as the blank space and the tab ++character. (For more information, see @ref{Syntax, Syntax, The Syntax ++Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax ++Tables, elisp, The GNU Emacs Lisp Reference Manual}.) ++ ++Syntax tables specify which characters belong to which categories. ++Usually, a hyphen is not specified as a `word constituent character'. ++Instead, it is specified as being in the `class of characters that are ++part of symbol names but not words.' This means that the ++@code{count-words-region} function treats it in the same way it treats ++an interword white space, which is why @code{count-words-region} ++counts @samp{multiply-by-seven} as three words. ++ ++There are two ways to cause Emacs to count @samp{multiply-by-seven} as ++one symbol: modify the syntax table or modify the regular expression. ++ ++We could redefine a hyphen as a word constituent character by ++modifying the syntax table that Emacs keeps for each mode. This ++action would serve our purpose, except that a hyphen is merely the ++most common character within symbols that is not typically a word ++constituent character; there are others, too. ++ ++Alternatively, we can redefine the regular expression used in the ++@code{count-words} definition so as to include symbols. This ++procedure has the merit of clarity, but the task is a little tricky. ++ ++@need 1200 ++The first part is simple enough: the pattern must match ``at least one ++character that is a word or symbol constituent''. Thus: ++ ++@smallexample ++"\\(\\w\\|\\s_\\)+" ++@end smallexample ++ ++@noindent ++The @samp{\\(} is the first part of the grouping construct that ++includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated ++by the @samp{\\|}. The @samp{\\w} matches any word-constituent ++character and the @samp{\\s_} matches any character that is part of a ++symbol name but not a word-constituent character. The @samp{+} ++following the group indicates that the word or symbol constituent ++characters must be matched at least once. ++ ++However, the second part of the regexp is more difficult to design. ++What we want is to follow the first part with ``optionally one or more ++characters that are not constituents of a word or symbol''. At first, ++I thought I could define this with the following: ++ ++@smallexample ++"\\(\\W\\|\\S_\\)*" ++@end smallexample ++ ++@noindent ++The upper case @samp{W} and @samp{S} match characters that are ++@emph{not} word or symbol constituents. Unfortunately, this ++expression matches any character that is either not a word constituent ++or not a symbol constituent. This matches any character! ++ ++I then noticed that every word or symbol in my test region was ++followed by white space (blank space, tab, or newline). So I tried ++placing a pattern to match one or more blank spaces after the pattern ++for one or more word or symbol constituents. This failed, too. Words ++and symbols are often separated by whitespace, but in actual code ++parentheses may follow symbols and punctuation may follow words. So ++finally, I designed a pattern in which the word or symbol constituents ++are followed optionally by characters that are not white space and ++then followed optionally by white space. ++ ++@need 800 ++Here is the full regular expression: ++ ++@smallexample ++"\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" ++@end smallexample ++ ++@node count-words-in-defun, Several defuns, Syntax, Words in a defun ++@section The @code{count-words-in-defun} Function ++@cindex Counting words in a @code{defun} ++ ++We have seen that there are several ways to write a ++@code{count-word-region} function. To write a ++@code{count-words-in-defun}, we need merely adapt one of these ++versions. ++ ++The version that uses a @code{while} loop is easy to understand, so I ++am going to adapt that. Because @code{count-words-in-defun} will be ++part of a more complex program, it need not be interactive and it need ++not display a message but just return the count. These considerations ++simplify the definition a little. ++ ++On the other hand, @code{count-words-in-defun} will be used within a ++buffer that contains function definitions. Consequently, it is ++reasonable to ask that the function determine whether it is called ++when point is within a function definition, and if it is, to return ++the count for that definition. This adds complexity to the ++definition, but saves us from needing to pass arguments to the ++function. ++ ++@need 1250 ++These considerations lead us to prepare the following template: ++ ++@smallexample ++@group ++(defun count-words-in-defun () ++ "@var{documentation}@dots{}" ++ (@var{set up}@dots{} ++ (@var{while loop}@dots{}) ++ @var{return count}) ++@end group ++@end smallexample ++ ++@noindent ++As usual, our job is to fill in the slots. ++ ++First, the set up. ++ ++We are presuming that this function will be called within a buffer ++containing function definitions. Point will either be within a ++function definition or not. For @code{count-words-in-defun} to work, ++point must move to the beginning of the definition, a counter must ++start at zero, and the counting loop must stop when point reaches the ++end of the definition. ++ ++The @code{beginning-of-defun} function searches backwards for an ++opening delimiter such as a @samp{(} at the beginning of a line, and ++moves point to that position, or else to the limit of the search. In ++practice, this means that @code{beginning-of-defun} moves point to the ++beginning of an enclosing or preceding function definition, or else to ++the beginning of the buffer. We can use @code{beginning-of-defun} to ++place point where we wish to start. ++ ++The @code{while} loop requires a counter to keep track of the words or ++symbols being counted. A @code{let} expression can be used to create ++a local variable for this purpose, and bind it to an initial value of zero. ++ ++The @code{end-of-defun} function works like @code{beginning-of-defun} ++except that it moves point to the end of the definition. ++@code{end-of-defun} can be used as part of an expression that ++determines the position of the end of the definition. ++ ++The set up for @code{count-words-in-defun} takes shape rapidly: first ++we move point to the beginning of the definition, then we create a ++local variable to hold the count, and finally, we record the position ++of the end of the definition so the @code{while} loop will know when to stop ++looping. ++ ++@need 1250 ++The code looks like this: ++ ++@smallexample ++@group ++(beginning-of-defun) ++(let ((count 0) ++ (end (save-excursion (end-of-defun) (point)))) ++@end group ++@end smallexample ++ ++@noindent ++The code is simple. The only slight complication is likely to concern ++@code{end}: it is bound to the position of the end of the definition ++by a @code{save-excursion} expression that returns the value of point ++after @code{end-of-defun} temporarily moves it to the end of the ++definition. ++ ++The second part of the @code{count-words-in-defun}, after the set up, ++is the @code{while} loop. ++ ++The loop must contain an expression that jumps point forward word by ++word and symbol by symbol, and another expression that counts the ++jumps. The true-or-false-test for the @code{while} loop should test ++true so long as point should jump forward, and false when point is at ++the end of the definition. We have already redefined the regular ++expression for this (@pxref{Syntax}), so the loop is straightforward: ++ ++@smallexample ++@group ++(while (and (< (point) end) ++ (re-search-forward ++ "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t) ++ (setq count (1+ count))) ++@end group ++@end smallexample ++ ++The third part of the function definition returns the count of words ++and symbols. This part is the last expression within the body of the ++@code{let} expression, and can be, very simply, the local variable ++@code{count}, which when evaluated returns the count. ++ ++@need 1250 ++Put together, the @code{count-words-in-defun} definition looks like this: ++ ++@findex count-words-in-defun ++@smallexample ++@group ++(defun count-words-in-defun () ++ "Return the number of words and symbols in a defun." ++ (beginning-of-defun) ++ (let ((count 0) ++ (end (save-excursion (end-of-defun) (point)))) ++@end group ++@group ++ (while ++ (and (< (point) end) ++ (re-search-forward ++ "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" ++ end t)) ++ (setq count (1+ count))) ++ count)) ++@end group ++@end smallexample ++ ++How to test this? The function is not interactive, but it is easy to ++put a wrapper around the function to make it interactive; we can use ++almost the same code as for the recursive version of ++@code{count-words-region}: ++ ++@smallexample ++@group ++;;; @r{Interactive version.} ++(defun count-words-defun () ++ "Number of words and symbols in a function definition." ++ (interactive) ++ (message ++ "Counting words and symbols in function definition ... ") ++@end group ++@group ++ (let ((count (count-words-in-defun))) ++ (cond ++ ((zerop count) ++ (message ++ "The definition does NOT have any words or symbols.")) ++@end group ++@group ++ ((= 1 count) ++ (message ++ "The definition has 1 word or symbol.")) ++ (t ++ (message ++ "The definition has %d words or symbols." count))))) ++@end group ++@end smallexample ++ ++@need 800 ++@noindent ++Let's re-use @kbd{C-c =} as a convenient keybinding: ++ ++@smallexample ++(global-set-key "\C-c=" 'count-words-defun) ++@end smallexample ++ ++Now we can try out @code{count-words-defun}: install both ++@code{count-words-in-defun} and @code{count-words-defun}, and set the ++keybinding, and then place the cursor within the following definition: ++ ++@smallexample ++@group ++(defun multiply-by-seven (number) ++ "Multiply NUMBER by seven." ++ (* 7 number)) ++ @result{} 10 ++@end group ++@end smallexample ++ ++@noindent ++Success! The definition has 10 words and symbols. ++ ++The next problem is to count the numbers of words and symbols in ++several definitions within a single file. ++ ++@node Several defuns, Find a File, count-words-in-defun, Words in a defun ++@section Count Several @code{defuns} Within a File ++ ++A file such as @file{simple.el} may have a hundred or more function ++definitions within it. Our long term goal is to collect statistics on ++many files, but as a first step, our immediate goal is to collect ++statistics on one file. ++ ++The information will be a series of numbers, each number being the ++length of a function definition. We can store the numbers in a list. ++ ++We know that we will want to incorporate the information regarding one ++file with information about many other files; this means that the ++function for counting definition lengths within one file need only ++return the list of lengths. It need not and should not display any ++messages. ++ ++The word count commands contain one expression to jump point forward ++word by word and another expression to count the jumps. The function ++to return the lengths of definitions can be designed to work the same ++way, with one expression to jump point forward definition by ++definition and another expression to construct the lengths' list. ++ ++This statement of the problem makes it elementary to write the ++function definition. Clearly, we will start the count at the ++beginning of the file, so the first command will be @code{(goto-char ++(point-min))}. Next, we start the @code{while} loop; and the ++true-or-false test of the loop can be a regular expression search for ++the next function definition---so long as the search succeeds, point ++is moved forward and then the body of the loop is evaluated. The body ++needs an expression that constructs the lengths' list. @code{cons}, ++the list construction command, can be used to create the list. That ++is almost all there is to it. ++ ++@need 800 ++Here is what this fragment of code looks like: ++ ++@smallexample ++@group ++(goto-char (point-min)) ++(while (re-search-forward "^(defun" nil t) ++ (setq lengths-list ++ (cons (count-words-in-defun) lengths-list))) ++@end group ++@end smallexample ++ ++What we have left out is the mechanism for finding the file that ++contains the function definitions. ++ ++In previous examples, we either used this, the Info file, or we ++switched back and forth to some other buffer, such as the ++@file{*scratch*} buffer. ++ ++Finding a file is a new process that we have not yet discussed. ++ ++@node Find a File, lengths-list-file, Several defuns, Words in a defun ++@comment node-name, next, previous, up ++@section Find a File ++@cindex Find a File ++ ++To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file}) ++command. This command is almost, but not quite right for the lengths ++problem. ++ ++@need 1200 ++Let's look at the source for @code{find-file}: ++ ++@smallexample ++@group ++(defun find-file (filename) ++ "Edit file FILENAME. ++Switch to a buffer visiting file FILENAME, ++creating one if none already exists." ++ (interactive "FFind file: ") ++ (switch-to-buffer (find-file-noselect filename))) ++@end group ++@end smallexample ++ ++@noindent ++(The most recent version of the @code{find-file} function definition ++permits you to specify optional wildcards to visit multiple files; that ++makes the definition more complex and we will not discuss it here, ++since it is not relevant. You can see its source using either ++@kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).) ++ ++@ignore ++In Emacs 22 ++(defun find-file (filename &optional wildcards) ++ "Edit file FILENAME. ++Switch to a buffer visiting file FILENAME, ++creating one if none already exists. ++Interactively, the default if you just type RET is the current directory, ++but the visited file name is available through the minibuffer history: ++type M-n to pull it into the minibuffer. ++ ++Interactively, or if WILDCARDS is non-nil in a call from Lisp, ++expand wildcards (if any) and visit multiple files. You can ++suppress wildcard expansion by setting `find-file-wildcards' to nil. ++ ++To visit a file without any kind of conversion and without ++automatically choosing a major mode, use \\[find-file-literally]." ++ (interactive (find-file-read-args "Find file: " nil)) ++ (let ((value (find-file-noselect filename nil nil wildcards))) ++ (if (listp value) ++ (mapcar 'switch-to-buffer (nreverse value)) ++ (switch-to-buffer value)))) ++@end ignore ++ ++The definition I am showing possesses short but complete documentation ++and an interactive specification that prompts you for a file name when ++you use the command interactively. The body of the definition ++contains two functions, @code{find-file-noselect} and ++@code{switch-to-buffer}. ++ ++According to its documentation as shown by @kbd{C-h f} (the ++@code{describe-function} command), the @code{find-file-noselect} ++function reads the named file into a buffer and returns the buffer. ++(Its most recent version includes an optional wildcards argument, ++too, as well as another to read a file literally and an other you ++suppress warning messages. These optional arguments are irrelevant.) ++ ++However, the @code{find-file-noselect} function does not select the ++buffer in which it puts the file. Emacs does not switch its attention ++(or yours if you are using @code{find-file-noselect}) to the selected ++buffer. That is what @code{switch-to-buffer} does: it switches the ++buffer to which Emacs attention is directed; and it switches the ++buffer displayed in the window to the new buffer. We have discussed ++buffer switching elsewhere. (@xref{Switching Buffers}.) ++ ++In this histogram project, we do not need to display each file on the ++screen as the program determines the length of each definition within ++it. Instead of employing @code{switch-to-buffer}, we can work with ++@code{set-buffer}, which redirects the attention of the computer ++program to a different buffer but does not redisplay it on the screen. ++So instead of calling on @code{find-file} to do the job, we must write ++our own expression. ++ ++The task is easy: use @code{find-file-noselect} and @code{set-buffer}. ++ ++@node lengths-list-file, Several files, Find a File, Words in a defun ++@section @code{lengths-list-file} in Detail ++ ++The core of the @code{lengths-list-file} function is a @code{while} ++loop containing a function to move point forward `defun by defun' and ++a function to count the number of words and symbols in each defun. ++This core must be surrounded by functions that do various other tasks, ++including finding the file, and ensuring that point starts out at the ++beginning of the file. The function definition looks like this: ++@findex lengths-list-file ++ ++@smallexample ++@group ++(defun lengths-list-file (filename) ++ "Return list of definitions' lengths within FILE. ++The returned list is a list of numbers. ++Each number is the number of words or ++symbols in one function definition." ++@end group ++@group ++ (message "Working on `%s' ... " filename) ++ (save-excursion ++ (let ((buffer (find-file-noselect filename)) ++ (lengths-list)) ++ (set-buffer buffer) ++ (setq buffer-read-only t) ++ (widen) ++ (goto-char (point-min)) ++ (while (re-search-forward "^(defun" nil t) ++ (setq lengths-list ++ (cons (count-words-in-defun) lengths-list))) ++ (kill-buffer buffer) ++ lengths-list))) ++@end group ++@end smallexample ++ ++@noindent ++The function is passed one argument, the name of the file on which it ++will work. It has four lines of documentation, but no interactive ++specification. Since people worry that a computer is broken if they ++don't see anything going on, the first line of the body is a ++message. ++ ++The next line contains a @code{save-excursion} that returns Emacs' ++attention to the current buffer when the function completes. This is ++useful in case you embed this function in another function that ++presumes point is restored to the original buffer. ++ ++In the varlist of the @code{let} expression, Emacs finds the file and ++binds the local variable @code{buffer} to the buffer containing the ++file. At the same time, Emacs creates @code{lengths-list} as a local ++variable. ++ ++Next, Emacs switches its attention to the buffer. ++ ++In the following line, Emacs makes the buffer read-only. Ideally, ++this line is not necessary. None of the functions for counting words ++and symbols in a function definition should change the buffer. ++Besides, the buffer is not going to be saved, even if it were changed. ++This line is entirely the consequence of great, perhaps excessive, ++caution. The reason for the caution is that this function and those ++it calls work on the sources for Emacs and it is inconvenient if they ++are inadvertently modified. It goes without saying that I did not ++realize a need for this line until an experiment went awry and started ++to modify my Emacs source files @dots{} ++ ++Next comes a call to widen the buffer if it is narrowed. This ++function is usually not needed---Emacs creates a fresh buffer if none ++already exists; but if a buffer visiting the file already exists Emacs ++returns that one. In this case, the buffer may be narrowed and must ++be widened. If we wanted to be fully `user-friendly', we would ++arrange to save the restriction and the location of point, but we ++won't. ++ ++The @code{(goto-char (point-min))} expression moves point to the ++beginning of the buffer. ++ ++Then comes a @code{while} loop in which the `work' of the function is ++carried out. In the loop, Emacs determines the length of each ++definition and constructs a lengths' list containing the information. ++ ++Emacs kills the buffer after working through it. This is to save ++space inside of Emacs. My version of GNU Emacs 19 contained over 300 ++source files of interest; GNU Emacs 22 contains over a thousand source ++files. Another function will apply @code{lengths-list-file} to each ++of the files. ++ ++Finally, the last expression within the @code{let} expression is the ++@code{lengths-list} variable; its value is returned as the value of ++the whole function. ++ ++You can try this function by installing it in the usual fashion. Then ++place your cursor after the following expression and type @kbd{C-x ++C-e} (@code{eval-last-sexp}). ++ ++@c !!! 22.1.1 lisp sources location here ++@smallexample ++(lengths-list-file ++ "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el") ++@end smallexample ++ ++@noindent ++(You may need to change the pathname of the file; the one here is for ++GNU Emacs version 22.1.1. To change the expression, copy it to ++the @file{*scratch*} buffer and edit it. ++ ++@need 1200 ++@noindent ++(Also, to see the full length of the list, rather than a truncated ++version, you may have to evaluate the following: ++ ++@smallexample ++(custom-set-variables '(eval-expression-print-length nil)) ++@end smallexample ++ ++@noindent ++(@xref{defcustom, , Specifying Variables using @code{defcustom}}. ++Then evaluate the @code{lengths-list-file} expression.) ++ ++@need 1200 ++The lengths' list for @file{debug.el} takes less than a second to ++produce and looks like this in GNU Emacs 22: ++ ++@smallexample ++(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587) ++@end smallexample ++ ++@need 1500 ++(Using my old machine, the version 19 lengths' list for @file{debug.el} ++took seven seconds to produce and looked like this: ++ ++@smallexample ++(75 41 80 62 20 45 44 68 45 12 34 235) ++@end smallexample ++ ++(The newer version of @file{debug.el} contains more defuns than the ++earlier one; and my new machine is much faster than the old one.) ++ ++Note that the length of the last definition in the file is first in ++the list. ++ ++@node Several files, Several files recursively, lengths-list-file, Words in a defun ++@section Count Words in @code{defuns} in Different Files ++ ++In the previous section, we created a function that returns a list of ++the lengths of each definition in a file. Now, we want to define a ++function to return a master list of the lengths of the definitions in ++a list of files. ++ ++Working on each of a list of files is a repetitious act, so we can use ++either a @code{while} loop or recursion. ++ ++@menu ++* lengths-list-many-files:: Return a list of the lengths of defuns. ++* append:: Attach one list to another. ++@end menu ++ ++@node lengths-list-many-files, append, Several files, Several files ++@ifnottex ++@unnumberedsubsec Determine the lengths of @code{defuns} ++@end ifnottex ++ ++The design using a @code{while} loop is routine. The argument passed ++the function is a list of files. As we saw earlier (@pxref{Loop ++Example}), you can write a @code{while} loop so that the body of the ++loop is evaluated if such a list contains elements, but to exit the ++loop if the list is empty. For this design to work, the body of the ++loop must contain an expression that shortens the list each time the ++body is evaluated, so that eventually the list is empty. The usual ++technique is to set the value of the list to the value of the @sc{cdr} ++of the list each time the body is evaluated. ++ ++@need 800 ++The template looks like this: ++ ++@smallexample ++@group ++(while @var{test-whether-list-is-empty} ++ @var{body}@dots{} ++ @var{set-list-to-cdr-of-list}) ++@end group ++@end smallexample ++ ++Also, we remember that a @code{while} loop returns @code{nil} (the ++result of evaluating the true-or-false-test), not the result of any ++evaluation within its body. (The evaluations within the body of the ++loop are done for their side effects.) However, the expression that ++sets the lengths' list is part of the body---and that is the value ++that we want returned by the function as a whole. To do this, we ++enclose the @code{while} loop within a @code{let} expression, and ++arrange that the last element of the @code{let} expression contains ++the value of the lengths' list. (@xref{Incrementing Example, , Loop ++Example with an Incrementing Counter}.) ++ ++@findex lengths-list-many-files ++@need 1250 ++These considerations lead us directly to the function itself: ++ ++@smallexample ++@group ++;;; @r{Use @code{while} loop.} ++(defun lengths-list-many-files (list-of-files) ++ "Return list of lengths of defuns in LIST-OF-FILES." ++@end group ++@group ++ (let (lengths-list) ++ ++;;; @r{true-or-false-test} ++ (while list-of-files ++ (setq lengths-list ++ (append ++ lengths-list ++ ++;;; @r{Generate a lengths' list.} ++ (lengths-list-file ++ (expand-file-name (car list-of-files))))) ++@end group ++ ++@group ++;;; @r{Make files' list shorter.} ++ (setq list-of-files (cdr list-of-files))) ++ ++;;; @r{Return final value of lengths' list.} ++ lengths-list)) ++@end group ++@end smallexample ++ ++@code{expand-file-name} is a built-in function that converts a file ++name to the absolute, long, path name form. The function employs the ++name of the directory in which the function is called. ++ ++@c !!! 22.1.1 lisp sources location here ++@need 1500 ++Thus, if @code{expand-file-name} is called on @code{debug.el} when ++Emacs is visiting the ++@file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory, ++ ++@smallexample ++debug.el ++@end smallexample ++ ++@need 800 ++@noindent ++becomes ++ ++@c !!! 22.1.1 lisp sources location here ++@smallexample ++/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el ++@end smallexample ++ ++The only other new element of this function definition is the as yet ++unstudied function @code{append}, which merits a short section for ++itself. ++ ++@node append, , lengths-list-many-files, Several files ++@subsection The @code{append} Function ++ ++@need 800 ++The @code{append} function attaches one list to another. Thus, ++ ++@smallexample ++(append '(1 2 3 4) '(5 6 7 8)) ++@end smallexample ++ ++@need 800 ++@noindent ++produces the list ++ ++@smallexample ++(1 2 3 4 5 6 7 8) ++@end smallexample ++ ++This is exactly how we want to attach two lengths' lists produced by ++@code{lengths-list-file} to each other. The results contrast with ++@code{cons}, ++ ++@smallexample ++(cons '(1 2 3 4) '(5 6 7 8)) ++@end smallexample ++ ++@need 1250 ++@noindent ++which constructs a new list in which the first argument to @code{cons} ++becomes the first element of the new list: ++ ++@smallexample ++((1 2 3 4) 5 6 7 8) ++@end smallexample ++ ++@node Several files recursively, Prepare the data, Several files, Words in a defun ++@section Recursively Count Words in Different Files ++ ++Besides a @code{while} loop, you can work on each of a list of files ++with recursion. A recursive version of @code{lengths-list-many-files} ++is short and simple. ++ ++The recursive function has the usual parts: the `do-again-test', the ++`next-step-expression', and the recursive call. The `do-again-test' ++determines whether the function should call itself again, which it ++will do if the @code{list-of-files} contains any remaining elements; ++the `next-step-expression' resets the @code{list-of-files} to the ++@sc{cdr} of itself, so eventually the list will be empty; and the ++recursive call calls itself on the shorter list. The complete ++function is shorter than this description! ++@findex recursive-lengths-list-many-files ++ ++@smallexample ++@group ++(defun recursive-lengths-list-many-files (list-of-files) ++ "Return list of lengths of each defun in LIST-OF-FILES." ++ (if list-of-files ; @r{do-again-test} ++ (append ++ (lengths-list-file ++ (expand-file-name (car list-of-files))) ++ (recursive-lengths-list-many-files ++ (cdr list-of-files))))) ++@end group ++@end smallexample ++ ++@noindent ++In a sentence, the function returns the lengths' list for the first of ++the @code{list-of-files} appended to the result of calling itself on ++the rest of the @code{list-of-files}. ++ ++Here is a test of @code{recursive-lengths-list-many-files}, along with ++the results of running @code{lengths-list-file} on each of the files ++individually. ++ ++Install @code{recursive-lengths-list-many-files} and ++@code{lengths-list-file}, if necessary, and then evaluate the ++following expressions. You may need to change the files' pathnames; ++those here work when this Info file and the Emacs sources are located ++in their customary places. To change the expressions, copy them to ++the @file{*scratch*} buffer, edit them, and then evaluate them. ++ ++The results are shown after the @samp{@result{}}. (These results are ++for files from Emacs version 22.1.1; files from other versions of ++Emacs may produce different results.) ++ ++@c !!! 22.1.1 lisp sources location here ++@smallexample ++@group ++(cd "/usr/local/share/emacs/22.1.1/") ++ ++(lengths-list-file "./lisp/macros.el") ++ @result{} (283 263 480 90) ++@end group ++ ++@group ++(lengths-list-file "./lisp/mail/mailalias.el") ++ @result{} (38 32 29 95 178 180 321 218 324) ++@end group ++ ++@group ++(lengths-list-file "./lisp/makesum.el") ++ @result{} (85 181) ++@end group ++ ++@group ++ (recursive-lengths-list-many-files ++ '("./lisp/macros.el" ++ "./lisp/mail/mailalias.el" ++ "./lisp/makesum.el")) ++ @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181) ++@end group ++@end smallexample ++ ++The @code{recursive-lengths-list-many-files} function produces the ++output we want. ++ ++The next step is to prepare the data in the list for display in a graph. ++ ++@node Prepare the data, , Several files recursively, Words in a defun ++@section Prepare the Data for Display in a Graph ++ ++The @code{recursive-lengths-list-many-files} function returns a list ++of numbers. Each number records the length of a function definition. ++What we need to do now is transform this data into a list of numbers ++suitable for generating a graph. The new list will tell how many ++functions definitions contain less than 10 words and ++symbols, how many contain between 10 and 19 words and symbols, how ++many contain between 20 and 29 words and symbols, and so on. ++ ++In brief, we need to go through the lengths' list produced by the ++@code{recursive-lengths-list-many-files} function and count the number ++of defuns within each range of lengths, and produce a list of those ++numbers. ++ ++@menu ++* Data for Display in Detail:: ++* Sorting:: Sorting lists. ++* Files List:: Making a list of files. ++* Counting function definitions:: ++@end menu ++ ++@node Data for Display in Detail, Sorting, Prepare the data, Prepare the data ++@ifnottex ++@unnumberedsubsec The Data for Display in Detail ++@end ifnottex ++ ++Based on what we have done before, we can readily foresee that it ++should not be too hard to write a function that `@sc{cdr}s' down the ++lengths' list, looks at each element, determines which length range it ++is in, and increments a counter for that range. ++ ++However, before beginning to write such a function, we should consider ++the advantages of sorting the lengths' list first, so the numbers are ++ordered from smallest to largest. First, sorting will make it easier ++to count the numbers in each range, since two adjacent numbers will ++either be in the same length range or in adjacent ranges. Second, by ++inspecting a sorted list, we can discover the highest and lowest ++number, and thereby determine the largest and smallest length range ++that we will need. ++ ++@node Sorting, Files List, Data for Display in Detail, Prepare the data ++@subsection Sorting Lists ++@findex sort ++ ++Emacs contains a function to sort lists, called (as you might guess) ++@code{sort}. The @code{sort} function takes two arguments, the list ++to be sorted, and a predicate that determines whether the first of ++two list elements is ``less'' than the second. ++ ++As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong ++Type Object as an Argument}), a predicate is a function that ++determines whether some property is true or false. The @code{sort} ++function will reorder a list according to whatever property the ++predicate uses; this means that @code{sort} can be used to sort ++non-numeric lists by non-numeric criteria---it can, for example, ++alphabetize a list. ++ ++@need 1250 ++The @code{<} function is used when sorting a numeric list. For example, ++ ++@smallexample ++(sort '(4 8 21 17 33 7 21 7) '<) ++@end smallexample ++ ++@need 800 ++@noindent ++produces this: ++ ++@smallexample ++(4 7 7 8 17 21 21 33) ++@end smallexample ++ ++@noindent ++(Note that in this example, both the arguments are quoted so that the ++symbols are not evaluated before being passed to @code{sort} as ++arguments.) ++ ++Sorting the list returned by the ++@code{recursive-lengths-list-many-files} function is straightforward; ++it uses the @code{<} function: ++ ++@ignore ++2006 Oct 29 ++In GNU Emacs 22, eval ++(progn ++ (cd "/usr/local/share/emacs/22.0.50/") ++ (sort ++ (recursive-lengths-list-many-files ++ '("./lisp/macros.el" ++ "./lisp/mail/mailalias.el" ++ "./lisp/makesum.el")) ++ '<)) ++ ++@end ignore ++ ++@smallexample ++@group ++(sort ++ (recursive-lengths-list-many-files ++ '("./lisp/macros.el" ++ "./lisp/mailalias.el" ++ "./lisp/makesum.el")) ++ '<) ++@end group ++@end smallexample ++ ++@need 800 ++@noindent ++which produces: ++ ++@smallexample ++(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480) ++@end smallexample ++ ++@noindent ++(Note that in this example, the first argument to @code{sort} is not ++quoted, since the expression must be evaluated so as to produce the ++list that is passed to @code{sort}.) ++ ++@node Files List, Counting function definitions, Sorting, Prepare the data ++@subsection Making a List of Files ++ ++The @code{recursive-lengths-list-many-files} function requires a list ++of files as its argument. For our test examples, we constructed such ++a list by hand; but the Emacs Lisp source directory is too large for ++us to do for that. Instead, we will write a function to do the job ++for us. In this function, we will use both a @code{while} loop and a ++recursive call. ++ ++@findex directory-files ++We did not have to write a function like this for older versions of ++GNU Emacs, since they placed all the @samp{.el} files in one ++directory. Instead, we were able to use the @code{directory-files} ++function, which lists the names of files that match a specified ++pattern within a single directory. ++ ++However, recent versions of Emacs place Emacs Lisp files in ++sub-directories of the top level @file{lisp} directory. This ++re-arrangement eases navigation. For example, all the mail related ++files are in a @file{lisp} sub-directory called @file{mail}. But at ++the same time, this arrangement forces us to create a file listing ++function that descends into the sub-directories. ++ ++@findex files-in-below-directory ++We can create this function, called @code{files-in-below-directory}, ++using familiar functions such as @code{car}, @code{nthcdr}, and ++@code{substring} in conjunction with an existing function called ++@code{directory-files-and-attributes}. This latter function not only ++lists all the filenames in a directory, including the names ++of sub-directories, but also their attributes. ++ ++To restate our goal: to create a function that will enable us ++to feed filenames to @code{recursive-lengths-list-many-files} ++as a list that looks like this (but with more elements): ++ ++@smallexample ++@group ++("./lisp/macros.el" ++ "./lisp/mail/rmail.el" ++ "./lisp/makesum.el") ++@end group ++@end smallexample ++ ++The @code{directory-files-and-attributes} function returns a list of ++lists. Each of the lists within the main list consists of 13 ++elements. The first element is a string that contains the name of the ++file -- which, in GNU/Linux, may be a `directory file', that is to ++say, a file with the special attributes of a directory. The second ++element of the list is @code{t} for a directory, a string ++for symbolic link (the string is the name linked to), or @code{nil}. ++ ++For example, the first @samp{.el} file in the @file{lisp/} directory ++is @file{abbrev.el}. Its name is ++@file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a ++directory or a symbolic link. ++ ++@need 1000 ++This is how @code{directory-files-and-attributes} lists that file and ++its attributes: ++ ++@smallexample ++@group ++("abbrev.el" ++nil ++1 ++1000 ++100 ++@end group ++@group ++(17733 259) ++(17491 28834) ++(17596 62124) ++13157 ++"-rw-rw-r--" ++@end group ++@group ++nil ++2971624 ++773) ++@end group ++@end smallexample ++ ++@need 1200 ++On the other hand, @file{mail/} is a directory within the @file{lisp/} ++directory. The beginning of its listing looks like this: ++ ++@smallexample ++@group ++("mail" ++t ++@dots{} ++) ++@end group ++@end smallexample ++ ++(To learn about the different attributes, look at the documentation of ++@code{file-attributes}. Bear in mind that the @code{file-attributes} ++function does not list the filename, so its first element is ++@code{directory-files-and-attributes}'s second element.) ++ ++We will want our new function, @code{files-in-below-directory}, to ++list the @samp{.el} files in the directory it is told to check, and in ++any directories below that directory. ++ ++This gives us a hint on how to construct ++@code{files-in-below-directory}: within a directory, the function ++should add @samp{.el} filenames to a list; and if, within a directory, ++the function comes upon a sub-directory, it should go into that ++sub-directory and repeat its actions. ++ ++However, we should note that every directory contains a name that ++refers to itself, called @file{.}, (``dot'') and a name that refers to ++its parent directory, called @file{..} (``double dot''). (In ++@file{/}, the root directory, @file{..} refers to itself, since ++@file{/} has no parent.) Clearly, we do not want our ++@code{files-in-below-directory} function to enter those directories, ++since they always lead us, directly or indirectly, to the current ++directory. ++ ++Consequently, our @code{files-in-below-directory} function must do ++several tasks: ++ ++@itemize @bullet ++@item ++Check to see whether it is looking at a filename that ends in ++@samp{.el}; and if so, add its name to a list. ++ ++@item ++Check to see whether it is looking at a filename that is the name of a ++directory; and if so, ++ ++@itemize @minus ++@item ++Check to see whether it is looking at @file{.} or @file{..}; and if ++so skip it. ++ ++@item ++Or else, go into that directory and repeat the process. ++@end itemize ++@end itemize ++ ++Let's write a function definition to do these tasks. We will use a ++@code{while} loop to move from one filename to another within a ++directory, checking what needs to be done; and we will use a recursive ++call to repeat the actions on each sub-directory. The recursive ++pattern is `accumulate' ++(@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}), ++using @code{append} as the combiner. ++ ++@ignore ++(directory-files "/usr/local/src/emacs/lisp/" t "\\.el$") ++(shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'") ++ ++(directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$") ++(shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'") ++@end ignore ++ ++@c /usr/local/share/emacs/22.1.1/lisp/ ++ ++@need 800 ++Here is the function: ++ ++@smallexample ++@group ++(defun files-in-below-directory (directory) ++ "List the .el files in DIRECTORY and in its sub-directories." ++ ;; Although the function will be used non-interactively, ++ ;; it will be easier to test if we make it interactive. ++ ;; The directory will have a name such as ++ ;; "/usr/local/share/emacs/22.1.1/lisp/" ++ (interactive "DDirectory name: ") ++@end group ++@group ++ (let (el-files-list ++ (current-directory-list ++ (directory-files-and-attributes directory t))) ++ ;; while we are in the current directory ++ (while current-directory-list ++@end group ++@group ++ (cond ++ ;; check to see whether filename ends in `.el' ++ ;; and if so, append its name to a list. ++ ((equal ".el" (substring (car (car current-directory-list)) -3)) ++ (setq el-files-list ++ (cons (car (car current-directory-list)) el-files-list))) ++@end group ++@group ++ ;; check whether filename is that of a directory ++ ((eq t (car (cdr (car current-directory-list)))) ++ ;; decide whether to skip or recurse ++ (if ++ (equal "." ++ (substring (car (car current-directory-list)) -1)) ++ ;; then do nothing since filename is that of ++ ;; current directory or parent, "." or ".." ++ () ++@end group ++@group ++ ;; else descend into the directory and repeat the process ++ (setq el-files-list ++ (append ++ (files-in-below-directory ++ (car (car current-directory-list))) ++ el-files-list))))) ++ ;; move to the next filename in the list; this also ++ ;; shortens the list so the while loop eventually comes to an end ++ (setq current-directory-list (cdr current-directory-list))) ++ ;; return the filenames ++ el-files-list)) ++@end group ++@end smallexample ++ ++@c (files-in-below-directory "/usr/local/src/emacs/lisp/") ++@c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") ++ ++The @code{files-in-below-directory} @code{directory-files} function ++takes one argument, the name of a directory. ++ ++@need 1250 ++Thus, on my system, ++ ++@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/")) ++ ++@c !!! 22.1.1 lisp sources location here ++@smallexample ++@group ++(length ++ (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")) ++@end group ++@end smallexample ++ ++@noindent ++tells me that in and below my Lisp sources directory are 1031 ++@samp{.el} files. ++ ++@code{files-in-below-directory} returns a list in reverse alphabetical ++order. An expression to sort the list in alphabetical order looks ++like this: ++ ++@smallexample ++@group ++(sort ++ (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") ++ 'string-lessp) ++@end group ++@end smallexample ++ ++@ignore ++(defun test () ++ "Test how long it takes to find lengths of all sorted elisp defuns." ++ (insert "\n" (current-time-string) "\n") ++ (sit-for 0) ++ (sort ++ (recursive-lengths-list-many-files ++ (files-in-below-directory "/usr/local/src/emacs/lisp/")) ++ '<) ++ (insert (format "%s" (current-time-string)))) ++@end ignore ++ ++@node Counting function definitions, , Files List, Prepare the data ++@subsection Counting function definitions ++ ++Our immediate goal is to generate a list that tells us how many ++function definitions contain fewer than 10 words and symbols, how many ++contain between 10 and 19 words and symbols, how many contain between ++20 and 29 words and symbols, and so on. ++ ++With a sorted list of numbers, this is easy: count how many elements ++of the list are smaller than 10, then, after moving past the numbers ++just counted, count how many are smaller than 20, then, after moving ++past the numbers just counted, count how many are smaller than 30, and ++so on. Each of the numbers, 10, 20, 30, 40, and the like, is one ++larger than the top of that range. We can call the list of such ++numbers the @code{top-of-ranges} list. ++ ++@need 1200 ++If we wished, we could generate this list automatically, but it is ++simpler to write a list manually. Here it is: ++@vindex top-of-ranges ++ ++@smallexample ++@group ++(defvar top-of-ranges ++ '(10 20 30 40 50 ++ 60 70 80 90 100 ++ 110 120 130 140 150 ++ 160 170 180 190 200 ++ 210 220 230 240 250 ++ 260 270 280 290 300) ++ "List specifying ranges for `defuns-per-range'.") ++@end group ++@end smallexample ++ ++To change the ranges, we edit this list. ++ ++Next, we need to write the function that creates the list of the ++number of definitions within each range. Clearly, this function must ++take the @code{sorted-lengths} and the @code{top-of-ranges} lists ++as arguments. ++ ++The @code{defuns-per-range} function must do two things again and ++again: it must count the number of definitions within a range ++specified by the current top-of-range value; and it must shift to the ++next higher value in the @code{top-of-ranges} list after counting the ++number of definitions in the current range. Since each of these ++actions is repetitive, we can use @code{while} loops for the job. ++One loop counts the number of definitions in the range defined by the ++current top-of-range value, and the other loop selects each of the ++top-of-range values in turn. ++ ++Several entries of the @code{sorted-lengths} list are counted for each ++range; this means that the loop for the @code{sorted-lengths} list ++will be inside the loop for the @code{top-of-ranges} list, like a ++small gear inside a big gear. ++ ++The inner loop counts the number of definitions within the range. It ++is a simple counting loop of the type we have seen before. ++(@xref{Incrementing Loop, , A loop with an incrementing counter}.) ++The true-or-false test of the loop tests whether the value from the ++@code{sorted-lengths} list is smaller than the current value of the ++top of the range. If it is, the function increments the counter and ++tests the next value from the @code{sorted-lengths} list. ++ ++@need 1250 ++The inner loop looks like this: ++ ++@smallexample ++@group ++(while @var{length-element-smaller-than-top-of-range} ++ (setq number-within-range (1+ number-within-range)) ++ (setq sorted-lengths (cdr sorted-lengths))) ++@end group ++@end smallexample ++ ++The outer loop must start with the lowest value of the ++@code{top-of-ranges} list, and then be set to each of the succeeding ++higher values in turn. This can be done with a loop like this: ++ ++@smallexample ++@group ++(while top-of-ranges ++ @var{body-of-loop}@dots{} ++ (setq top-of-ranges (cdr top-of-ranges))) ++@end group ++@end smallexample ++ ++@need 1200 ++Put together, the two loops look like this: ++ ++@smallexample ++@group ++(while top-of-ranges ++ ++ ;; @r{Count the number of elements within the current range.} ++ (while @var{length-element-smaller-than-top-of-range} ++ (setq number-within-range (1+ number-within-range)) ++ (setq sorted-lengths (cdr sorted-lengths))) ++ ++ ;; @r{Move to next range.} ++ (setq top-of-ranges (cdr top-of-ranges))) ++@end group ++@end smallexample ++ ++In addition, in each circuit of the outer loop, Emacs should record ++the number of definitions within that range (the value of ++@code{number-within-range}) in a list. We can use @code{cons} for ++this purpose. (@xref{cons, , @code{cons}}.) ++ ++The @code{cons} function works fine, except that the list it ++constructs will contain the number of definitions for the highest ++range at its beginning and the number of definitions for the lowest ++range at its end. This is because @code{cons} attaches new elements ++of the list to the beginning of the list, and since the two loops are ++working their way through the lengths' list from the lower end first, ++the @code{defuns-per-range-list} will end up largest number first. ++But we will want to print our graph with smallest values first and the ++larger later. The solution is to reverse the order of the ++@code{defuns-per-range-list}. We can do this using the ++@code{nreverse} function, which reverses the order of a list. ++@findex nreverse ++ ++@need 800 ++For example, ++ ++@smallexample ++(nreverse '(1 2 3 4)) ++@end smallexample ++ ++@need 800 ++@noindent ++produces: ++ ++@smallexample ++(4 3 2 1) ++@end smallexample ++ ++Note that the @code{nreverse} function is ``destructive''---that is, ++it changes the list to which it is applied; this contrasts with the ++@code{car} and @code{cdr} functions, which are non-destructive. In ++this case, we do not want the original @code{defuns-per-range-list}, ++so it does not matter that it is destroyed. (The @code{reverse} ++function provides a reversed copy of a list, leaving the original list ++as is.) ++@findex reverse ++ ++@need 1250 ++Put all together, the @code{defuns-per-range} looks like this: ++ ++@smallexample ++@group ++(defun defuns-per-range (sorted-lengths top-of-ranges) ++ "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." ++ (let ((top-of-range (car top-of-ranges)) ++ (number-within-range 0) ++ defuns-per-range-list) ++@end group ++ ++@group ++ ;; @r{Outer loop.} ++ (while top-of-ranges ++@end group ++ ++@group ++ ;; @r{Inner loop.} ++ (while (and ++ ;; @r{Need number for numeric test.} ++ (car sorted-lengths) ++ (< (car sorted-lengths) top-of-range)) ++@end group ++ ++@group ++ ;; @r{Count number of definitions within current range.} ++ (setq number-within-range (1+ number-within-range)) ++ (setq sorted-lengths (cdr sorted-lengths))) ++ ++ ;; @r{Exit inner loop but remain within outer loop.} ++@end group ++ ++@group ++ (setq defuns-per-range-list ++ (cons number-within-range defuns-per-range-list)) ++ (setq number-within-range 0) ; @r{Reset count to zero.} ++@end group ++ ++@group ++ ;; @r{Move to next range.} ++ (setq top-of-ranges (cdr top-of-ranges)) ++ ;; @r{Specify next top of range value.} ++ (setq top-of-range (car top-of-ranges))) ++@end group ++ ++@group ++ ;; @r{Exit outer loop and count the number of defuns larger than} ++ ;; @r{ the largest top-of-range value.} ++ (setq defuns-per-range-list ++ (cons ++ (length sorted-lengths) ++ defuns-per-range-list)) ++@end group ++ ++@group ++ ;; @r{Return a list of the number of definitions within each range,} ++ ;; @r{ smallest to largest.} ++ (nreverse defuns-per-range-list))) ++@end group ++@end smallexample ++ ++@need 1200 ++@noindent ++The function is straightforward except for one subtle feature. The ++true-or-false test of the inner loop looks like this: ++ ++@smallexample ++@group ++(and (car sorted-lengths) ++ (< (car sorted-lengths) top-of-range)) ++@end group ++@end smallexample ++ ++@need 800 ++@noindent ++instead of like this: ++ ++@smallexample ++(< (car sorted-lengths) top-of-range) ++@end smallexample ++ ++The purpose of the test is to determine whether the first item in the ++@code{sorted-lengths} list is less than the value of the top of the ++range. ++ ++The simple version of the test works fine unless the ++@code{sorted-lengths} list has a @code{nil} value. In that case, the ++@code{(car sorted-lengths)} expression function returns ++@code{nil}. The @code{<} function cannot compare a number to ++@code{nil}, which is an empty list, so Emacs signals an error and ++stops the function from attempting to continue to execute. ++ ++The @code{sorted-lengths} list always becomes @code{nil} when the ++counter reaches the end of the list. This means that any attempt to ++use the @code{defuns-per-range} function with the simple version of ++the test will fail. ++ ++We solve the problem by using the @code{(car sorted-lengths)} ++expression in conjunction with the @code{and} expression. The ++@code{(car sorted-lengths)} expression returns a non-@code{nil} ++value so long as the list has at least one number within it, but ++returns @code{nil} if the list is empty. The @code{and} expression ++first evaluates the @code{(car sorted-lengths)} expression, and ++if it is @code{nil}, returns false @emph{without} evaluating the ++@code{<} expression. But if the @code{(car sorted-lengths)} ++expression returns a non-@code{nil} value, the @code{and} expression ++evaluates the @code{<} expression, and returns that value as the value ++of the @code{and} expression. ++ ++@c colon in printed section title causes problem in Info cross reference ++This way, we avoid an error. ++@iftex ++@noindent ++(For information about @code{and}, see ++@ref{kill-new function, , The @code{kill-new} function}.) ++@end iftex ++@ifinfo ++@noindent ++(@xref{kill-new function, , The @code{kill-new} function}, for ++information about @code{and}.) ++@end ifinfo ++ ++Here is a short test of the @code{defuns-per-range} function. First, ++evaluate the expression that binds (a shortened) ++@code{top-of-ranges} list to the list of values, then evaluate the ++expression for binding the @code{sorted-lengths} list, and then ++evaluate the @code{defuns-per-range} function. ++ ++@smallexample ++@group ++;; @r{(Shorter list than we will use later.)} ++(setq top-of-ranges ++ '(110 120 130 140 150 ++ 160 170 180 190 200)) ++ ++(setq sorted-lengths ++ '(85 86 110 116 122 129 154 176 179 200 265 300 300)) ++ ++(defuns-per-range sorted-lengths top-of-ranges) ++@end group ++@end smallexample ++ ++@need 800 ++@noindent ++The list returned looks like this: ++ ++@smallexample ++(2 2 2 0 0 1 0 2 0 0 4) ++@end smallexample ++ ++@noindent ++Indeed, there are two elements of the @code{sorted-lengths} list ++smaller than 110, two elements between 110 and 119, two elements ++between 120 and 129, and so on. There are four elements with a value ++of 200 or larger. ++ ++@c The next step is to turn this numbers' list into a graph. ++@node Readying a Graph, Emacs Initialization, Words in a defun, Top ++@chapter Readying a Graph ++@cindex Readying a graph ++@cindex Graph prototype ++@cindex Prototype graph ++@cindex Body of graph ++ ++Our goal is to construct a graph showing the numbers of function ++definitions of various lengths in the Emacs lisp sources. ++ ++As a practical matter, if you were creating a graph, you would ++probably use a program such as @code{gnuplot} to do the job. ++(@code{gnuplot} is nicely integrated into GNU Emacs.) In this case, ++however, we create one from scratch, and in the process we will ++re-acquaint ourselves with some of what we learned before and learn ++more. ++ ++In this chapter, we will first write a simple graph printing function. ++This first definition will be a @dfn{prototype}, a rapidly written ++function that enables us to reconnoiter this unknown graph-making ++territory. We will discover dragons, or find that they are myth. ++After scouting the terrain, we will feel more confident and enhance ++the function to label the axes automatically. ++ ++@menu ++* Columns of a graph:: ++* graph-body-print:: How to print the body of a graph. ++* recursive-graph-body-print:: ++* Printed Axes:: ++* Line Graph Exercise:: ++@end menu ++ ++@node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph ++@ifnottex ++@unnumberedsec Printing the Columns of a Graph ++@end ifnottex ++ ++Since Emacs is designed to be flexible and work with all kinds of ++terminals, including character-only terminals, the graph will need to ++be made from one of the `typewriter' symbols. An asterisk will do; as ++we enhance the graph-printing function, we can make the choice of ++symbol a user option. ++ ++We can call this function @code{graph-body-print}; it will take a ++@code{numbers-list} as its only argument. At this stage, we will not ++label the graph, but only print its body. ++ ++The @code{graph-body-print} function inserts a vertical column of ++asterisks for each element in the @code{numbers-list}. The height of ++each line is determined by the value of that element of the ++@code{numbers-list}. ++ ++Inserting columns is a repetitive act; that means that this function can ++be written either with a @code{while} loop or recursively. ++ ++Our first challenge is to discover how to print a column of asterisks. ++Usually, in Emacs, we print characters onto a screen horizontally, ++line by line, by typing. We have two routes we can follow: write our ++own column-insertion function or discover whether one exists in Emacs. ++ ++To see whether there is one in Emacs, we can use the @kbd{M-x apropos} ++command. This command is like the @kbd{C-h a} (@code{command-apropos}) ++command, except that the latter finds only those functions that are ++commands. The @kbd{M-x apropos} command lists all symbols that match ++a regular expression, including functions that are not interactive. ++@findex apropos ++ ++What we want to look for is some command that prints or inserts ++columns. Very likely, the name of the function will contain either ++the word `print' or the word `insert' or the word `column'. ++Therefore, we can simply type @kbd{M-x apropos RET ++print\|insert\|column RET} and look at the result. On my system, this ++command once too takes quite some time, and then produced a list of 79 ++functions and variables. Now it does not take much time at all and ++produces a list of 211 functions and variables. Scanning down the ++list, the only function that looks as if it might do the job is ++@code{insert-rectangle}. ++ ++@need 1200 ++Indeed, this is the function we want; its documentation says: ++ ++@smallexample ++@group ++insert-rectangle: ++Insert text of RECTANGLE with upper left corner at point. ++RECTANGLE's first line is inserted at point, ++its second line is inserted at a point vertically under point, etc. ++RECTANGLE should be a list of strings. ++After this command, the mark is at the upper left corner ++and point is at the lower right corner. ++@end group ++@end smallexample ++ ++We can run a quick test, to make sure it does what we expect of it. ++ ++Here is the result of placing the cursor after the ++@code{insert-rectangle} expression and typing @kbd{C-u C-x C-e} ++(@code{eval-last-sexp}). The function inserts the strings ++@samp{"first"}, @samp{"second"}, and @samp{"third"} at and below ++point. Also the function returns @code{nil}. ++ ++@smallexample ++@group ++(insert-rectangle '("first" "second" "third"))first ++ second ++ thirdnil ++@end group ++@end smallexample ++ ++@noindent ++Of course, we won't be inserting the text of the ++@code{insert-rectangle} expression itself into the buffer in which we ++are making the graph, but will call the function from our program. We ++shall, however, have to make sure that point is in the buffer at the ++place where the @code{insert-rectangle} function will insert its ++column of strings. ++ ++If you are reading this in Info, you can see how this works by ++switching to another buffer, such as the @file{*scratch*} buffer, ++placing point somewhere in the buffer, typing @kbd{M-:}, typing the ++@code{insert-rectangle} expression into the minibuffer at the prompt, ++and then typing @key{RET}. This causes Emacs to evaluate the ++expression in the minibuffer, but to use as the value of point the ++position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the ++keybinding for @code{eval-expression}. Also, @code{nil} does not ++appear in the @file{*scratch*} buffer since the expression is ++evaluated in the minibuffer.) ++ ++We find when we do this that point ends up at the end of the last ++inserted line---that is to say, this function moves point as a ++side-effect. If we were to repeat the command, with point at this ++position, the next insertion would be below and to the right of the ++previous insertion. We don't want this! If we are going to make a ++bar graph, the columns need to be beside each other. ++ ++So we discover that each cycle of the column-inserting @code{while} ++loop must reposition point to the place we want it, and that place ++will be at the top, not the bottom, of the column. Moreover, we ++remember that when we print a graph, we do not expect all the columns ++to be the same height. This means that the top of each column may be ++at a different height from the previous one. We cannot simply ++reposition point to the same line each time, but moved over to the ++right---or perhaps we can@dots{} ++ ++We are planning to make the columns of the bar graph out of asterisks. ++The number of asterisks in the column is the number specified by the ++current element of the @code{numbers-list}. We need to construct a ++list of asterisks of the right length for each call to ++@code{insert-rectangle}. If this list consists solely of the requisite ++number of asterisks, then we will have position point the right number ++of lines above the base for the graph to print correctly. This could ++be difficult. ++ ++Alternatively, if we can figure out some way to pass ++@code{insert-rectangle} a list of the same length each time, then we ++can place point on the same line each time, but move it over one ++column to the right for each new column. If we do this, however, some ++of the entries in the list passed to @code{insert-rectangle} must be ++blanks rather than asterisks. For example, if the maximum height of ++the graph is 5, but the height of the column is 3, then ++@code{insert-rectangle} requires an argument that looks like this: ++ ++@smallexample ++(" " " " "*" "*" "*") ++@end smallexample ++ ++This last proposal is not so difficult, so long as we can determine ++the column height. There are two ways for us to specify the column ++height: we can arbitrarily state what it will be, which would work ++fine for graphs of that height; or we can search through the list of ++numbers and use the maximum height of the list as the maximum height ++of the graph. If the latter operation were difficult, then the former ++procedure would be easiest, but there is a function built into Emacs ++that determines the maximum of its arguments. We can use that ++function. The function is called @code{max} and it returns the ++largest of all its arguments, which must be numbers. Thus, for ++example, ++ ++@smallexample ++(max 3 4 6 5 7 3) ++@end smallexample ++ ++@noindent ++returns 7. (A corresponding function called @code{min} returns the ++smallest of all its arguments.) ++@findex max ++@findex min ++ ++However, we cannot simply call @code{max} on the @code{numbers-list}; ++the @code{max} function expects numbers as its argument, not a list of ++numbers. Thus, the following expression, ++ ++@smallexample ++(max '(3 4 6 5 7 3)) ++@end smallexample ++ ++@need 800 ++@noindent ++produces the following error message; ++ ++@smallexample ++Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) ++@end smallexample ++ ++@findex apply ++We need a function that passes a list of arguments to a function. ++This function is @code{apply}. This function `applies' its first ++argument (a function) to its remaining arguments, the last of which ++may be a list. ++ ++@need 1250 ++For example, ++ ++@smallexample ++(apply 'max 3 4 7 3 '(4 8 5)) ++@end smallexample ++ ++@noindent ++returns 8. ++ ++(Incidentally, I don't know how you would learn of this function ++without a book such as this. It is possible to discover other ++functions, like @code{search-forward} or @code{insert-rectangle}, by ++guessing at a part of their names and then using @code{apropos}. Even ++though its base in metaphor is clear---`apply' its first argument to ++the rest---I doubt a novice would come up with that particular word ++when using @code{apropos} or other aid. Of course, I could be wrong; ++after all, the function was first named by someone who had to invent ++it.) ++ ++The second and subsequent arguments to @code{apply} are optional, so ++we can use @code{apply} to call a function and pass the elements of a ++list to it, like this, which also returns 8: ++ ++@smallexample ++(apply 'max '(4 8 5)) ++@end smallexample ++ ++This latter way is how we will use @code{apply}. The ++@code{recursive-lengths-list-many-files} function returns a numbers' ++list to which we can apply @code{max} (we could also apply @code{max} to ++the sorted numbers' list; it does not matter whether the list is ++sorted or not.) ++ ++@need 800 ++Hence, the operation for finding the maximum height of the graph is this: ++ ++@smallexample ++(setq max-graph-height (apply 'max numbers-list)) ++@end smallexample ++ ++Now we can return to the question of how to create a list of strings ++for a column of the graph. Told the maximum height of the graph ++and the number of asterisks that should appear in the column, the ++function should return a list of strings for the ++@code{insert-rectangle} command to insert. ++ ++Each column is made up of asterisks or blanks. Since the function is ++passed the value of the height of the column and the number of ++asterisks in the column, the number of blanks can be found by ++subtracting the number of asterisks from the height of the column. ++Given the number of blanks and the number of asterisks, two ++@code{while} loops can be used to construct the list: ++ ++@smallexample ++@group ++;;; @r{First version.} ++(defun column-of-graph (max-graph-height actual-height) ++ "Return list of strings that is one column of a graph." ++ (let ((insert-list nil) ++ (number-of-top-blanks ++ (- max-graph-height actual-height))) ++@end group ++ ++@group ++ ;; @r{Fill in asterisks.} ++ (while (> actual-height 0) ++ (setq insert-list (cons "*" insert-list)) ++ (setq actual-height (1- actual-height))) ++@end group ++ ++@group ++ ;; @r{Fill in blanks.} ++ (while (> number-of-top-blanks 0) ++ (setq insert-list (cons " " insert-list)) ++ (setq number-of-top-blanks ++ (1- number-of-top-blanks))) ++@end group ++ ++@group ++ ;; @r{Return whole list.} ++ insert-list)) ++@end group ++@end smallexample ++ ++If you install this function and then evaluate the following ++expression you will see that it returns the list as desired: ++ ++@smallexample ++(column-of-graph 5 3) ++@end smallexample ++ ++@need 800 ++@noindent ++returns ++ ++@smallexample ++(" " " " "*" "*" "*") ++@end smallexample ++ ++As written, @code{column-of-graph} contains a major flaw: the symbols ++used for the blank and for the marked entries in the column are ++`hard-coded' as a space and asterisk. This is fine for a prototype, ++but you, or another user, may wish to use other symbols. For example, ++in testing the graph function, you many want to use a period in place ++of the space, to make sure the point is being repositioned properly ++each time the @code{insert-rectangle} function is called; or you might ++want to substitute a @samp{+} sign or other symbol for the asterisk. ++You might even want to make a graph-column that is more than one ++display column wide. The program should be more flexible. The way to ++do that is to replace the blank and the asterisk with two variables ++that we can call @code{graph-blank} and @code{graph-symbol} and define ++those variables separately. ++ ++Also, the documentation is not well written. These considerations ++lead us to the second version of the function: ++ ++@smallexample ++@group ++(defvar graph-symbol "*" ++ "String used as symbol in graph, usually an asterisk.") ++@end group ++ ++@group ++(defvar graph-blank " " ++ "String used as blank in graph, usually a blank space. ++graph-blank must be the same number of columns wide ++as graph-symbol.") ++@end group ++@end smallexample ++ ++@noindent ++(For an explanation of @code{defvar}, see ++@ref{defvar, , Initializing a Variable with @code{defvar}}.) ++ ++@smallexample ++@group ++;;; @r{Second version.} ++(defun column-of-graph (max-graph-height actual-height) ++ "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols. ++ ++@end group ++@group ++The graph-symbols are contiguous entries at the end ++of the list. ++The list will be inserted as one column of a graph. ++The strings are either graph-blank or graph-symbol." ++@end group ++ ++@group ++ (let ((insert-list nil) ++ (number-of-top-blanks ++ (- max-graph-height actual-height))) ++@end group ++ ++@group ++ ;; @r{Fill in @code{graph-symbols}.} ++ (while (> actual-height 0) ++ (setq insert-list (cons graph-symbol insert-list)) ++ (setq actual-height (1- actual-height))) ++@end group ++ ++@group ++ ;; @r{Fill in @code{graph-blanks}.} ++ (while (> number-of-top-blanks 0) ++ (setq insert-list (cons graph-blank insert-list)) ++ (setq number-of-top-blanks ++ (1- number-of-top-blanks))) ++ ++ ;; @r{Return whole list.} ++ insert-list)) ++@end group ++@end smallexample ++ ++If we wished, we could rewrite @code{column-of-graph} a third time to ++provide optionally for a line graph as well as for a bar graph. This ++would not be hard to do. One way to think of a line graph is that it ++is no more than a bar graph in which the part of each bar that is ++below the top is blank. To construct a column for a line graph, the ++function first constructs a list of blanks that is one shorter than ++the value, then it uses @code{cons} to attach a graph symbol to the ++list; then it uses @code{cons} again to attach the `top blanks' to ++the list. ++ ++It is easy to see how to write such a function, but since we don't ++need it, we will not do it. But the job could be done, and if it were ++done, it would be done with @code{column-of-graph}. Even more ++important, it is worth noting that few changes would have to be made ++anywhere else. The enhancement, if we ever wish to make it, is ++simple. ++ ++Now, finally, we come to our first actual graph printing function. ++This prints the body of a graph, not the labels for the vertical and ++horizontal axes, so we can call this @code{graph-body-print}. ++ ++@node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph ++@section The @code{graph-body-print} Function ++@findex graph-body-print ++ ++After our preparation in the preceding section, the ++@code{graph-body-print} function is straightforward. The function ++will print column after column of asterisks and blanks, using the ++elements of a numbers' list to specify the number of asterisks in each ++column. This is a repetitive act, which means we can use a ++decrementing @code{while} loop or recursive function for the job. In ++this section, we will write the definition using a @code{while} loop. ++ ++The @code{column-of-graph} function requires the height of the graph ++as an argument, so we should determine and record that as a local variable. ++ ++This leads us to the following template for the @code{while} loop ++version of this function: ++ ++@smallexample ++@group ++(defun graph-body-print (numbers-list) ++ "@var{documentation}@dots{}" ++ (let ((height @dots{} ++ @dots{})) ++@end group ++ ++@group ++ (while numbers-list ++ @var{insert-columns-and-reposition-point} ++ (setq numbers-list (cdr numbers-list))))) ++@end group ++@end smallexample ++ ++@noindent ++We need to fill in the slots of the template. ++ ++Clearly, we can use the @code{(apply 'max numbers-list)} expression to ++determine the height of the graph. ++ ++The @code{while} loop will cycle through the @code{numbers-list} one ++element at a time. As it is shortened by the @code{(setq numbers-list ++(cdr numbers-list))} expression, the @sc{car} of each instance of the ++list is the value of the argument for @code{column-of-graph}. ++ ++At each cycle of the @code{while} loop, the @code{insert-rectangle} ++function inserts the list returned by @code{column-of-graph}. Since ++the @code{insert-rectangle} function moves point to the lower right of ++the inserted rectangle, we need to save the location of point at the ++time the rectangle is inserted, move back to that position after the ++rectangle is inserted, and then move horizontally to the next place ++from which @code{insert-rectangle} is called. ++ ++If the inserted columns are one character wide, as they will be if ++single blanks and asterisks are used, the repositioning command is ++simply @code{(forward-char 1)}; however, the width of a column may be ++greater than one. This means that the repositioning command should be ++written @code{(forward-char symbol-width)}. The @code{symbol-width} ++itself is the length of a @code{graph-blank} and can be found using ++the expression @code{(length graph-blank)}. The best place to bind ++the @code{symbol-width} variable to the value of the width of graph ++column is in the varlist of the @code{let} expression. ++ ++@need 1250 ++These considerations lead to the following function definition: ++ ++@smallexample ++@group ++(defun graph-body-print (numbers-list) ++ "Print a bar graph of the NUMBERS-LIST. ++The numbers-list consists of the Y-axis values." ++ ++ (let ((height (apply 'max numbers-list)) ++ (symbol-width (length graph-blank)) ++ from-position) ++@end group ++ ++@group ++ (while numbers-list ++ (setq from-position (point)) ++ (insert-rectangle ++ (column-of-graph height (car numbers-list))) ++ (goto-char from-position) ++ (forward-char symbol-width) ++@end group ++@group ++ ;; @r{Draw graph column by column.} ++ (sit-for 0) ++ (setq numbers-list (cdr numbers-list))) ++@end group ++@group ++ ;; @r{Place point for X axis labels.} ++ (forward-line height) ++ (insert "\n") ++)) ++@end group ++@end smallexample ++ ++@noindent ++The one unexpected expression in this function is the ++@w{@code{(sit-for 0)}} expression in the @code{while} loop. This ++expression makes the graph printing operation more interesting to ++watch than it would be otherwise. The expression causes Emacs to ++`sit' or do nothing for a zero length of time and then redraw the ++screen. Placed here, it causes Emacs to redraw the screen column by ++column. Without it, Emacs would not redraw the screen until the ++function exits. ++ ++We can test @code{graph-body-print} with a short list of numbers. ++ ++@enumerate ++@item ++Install @code{graph-symbol}, @code{graph-blank}, ++@code{column-of-graph}, which are in ++@iftex ++@ref{Readying a Graph, , Readying a Graph}, ++@end iftex ++@ifinfo ++@ref{Columns of a graph}, ++@end ifinfo ++and @code{graph-body-print}. ++ ++@need 800 ++@item ++Copy the following expression: ++ ++@smallexample ++(graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3)) ++@end smallexample ++ ++@item ++Switch to the @file{*scratch*} buffer and place the cursor where you ++want the graph to start. ++ ++@item ++Type @kbd{M-:} (@code{eval-expression}). ++ ++@item ++Yank the @code{graph-body-print} expression into the minibuffer ++with @kbd{C-y} (@code{yank)}. ++ ++@item ++Press @key{RET} to evaluate the @code{graph-body-print} expression. ++@end enumerate ++ ++@need 800 ++Emacs will print a graph like this: ++ ++@smallexample ++@group ++ * ++ * ** ++ * **** ++ *** **** ++ ********* * ++ ************ ++ ************* ++@end group ++@end smallexample ++ ++@node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph ++@section The @code{recursive-graph-body-print} Function ++@findex recursive-graph-body-print ++ ++The @code{graph-body-print} function may also be written recursively. ++The recursive solution is divided into two parts: an outside `wrapper' ++that uses a @code{let} expression to determine the values of several ++variables that need only be found once, such as the maximum height of ++the graph, and an inside function that is called recursively to print ++the graph. ++ ++@need 1250 ++The `wrapper' is uncomplicated: ++ ++@smallexample ++@group ++(defun recursive-graph-body-print (numbers-list) ++ "Print a bar graph of the NUMBERS-LIST. ++The numbers-list consists of the Y-axis values." ++ (let ((height (apply 'max numbers-list)) ++ (symbol-width (length graph-blank)) ++ from-position) ++ (recursive-graph-body-print-internal ++ numbers-list ++ height ++ symbol-width))) ++@end group ++@end smallexample ++ ++The recursive function is a little more difficult. It has four parts: ++the `do-again-test', the printing code, the recursive call, and the ++`next-step-expression'. The `do-again-test' is a @code{when} ++expression that determines whether the @code{numbers-list} contains ++any remaining elements; if it does, the function prints one column of ++the graph using the printing code and calls itself again. The ++function calls itself again according to the value produced by the ++`next-step-expression' which causes the call to act on a shorter ++version of the @code{numbers-list}. ++ ++@smallexample ++@group ++(defun recursive-graph-body-print-internal ++ (numbers-list height symbol-width) ++ "Print a bar graph. ++Used within recursive-graph-body-print function." ++@end group ++ ++@group ++ (when numbers-list ++ (setq from-position (point)) ++ (insert-rectangle ++ (column-of-graph height (car numbers-list))) ++@end group ++@group ++ (goto-char from-position) ++ (forward-char symbol-width) ++ (sit-for 0) ; @r{Draw graph column by column.} ++ (recursive-graph-body-print-internal ++ (cdr numbers-list) height symbol-width))) ++@end group ++@end smallexample ++ ++@need 1250 ++After installation, this expression can be tested; here is a sample: ++ ++@smallexample ++(recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1)) ++@end smallexample ++ ++@need 800 ++Here is what @code{recursive-graph-body-print} produces: ++ ++@smallexample ++@group ++ * ++ ** * ++ **** * ++ **** *** ++ * ********* ++ ************ ++ ************* ++@end group ++@end smallexample ++ ++Either of these two functions, @code{graph-body-print} or ++@code{recursive-graph-body-print}, create the body of a graph. ++ ++@node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph ++@section Need for Printed Axes ++ ++A graph needs printed axes, so you can orient yourself. For a do-once ++project, it may be reasonable to draw the axes by hand using Emacs' ++Picture mode; but a graph drawing function may be used more than once. ++ ++For this reason, I have written enhancements to the basic ++@code{print-graph-body} function that automatically print labels for ++the horizontal and vertical axes. Since the label printing functions ++do not contain much new material, I have placed their description in ++an appendix. @xref{Full Graph, , A Graph with Labelled Axes}. ++ ++@node Line Graph Exercise, , Printed Axes, Readying a Graph ++@section Exercise ++ ++Write a line graph version of the graph printing functions. ++ ++@node Emacs Initialization, Debugging, Readying a Graph, Top ++@chapter Your @file{.emacs} File ++@cindex @file{.emacs} file ++@cindex Customizing your @file{.emacs} file ++@cindex Initialization file ++ ++``You don't have to like Emacs to like it'' -- this seemingly ++paradoxical statement is the secret of GNU Emacs. The plain, `out of ++the box' Emacs is a generic tool. Most people who use it, customize ++it to suit themselves. ++ ++GNU Emacs is mostly written in Emacs Lisp; this means that by writing ++expressions in Emacs Lisp you can change or extend Emacs. ++ ++@menu ++* Default Configuration:: ++* Site-wide Init:: You can write site-wide init files. ++* defcustom:: Emacs will write code for you. ++* Beginning a .emacs File:: How to write a @code{.emacs file}. ++* Text and Auto-fill:: Automatically wrap lines. ++* Mail Aliases:: Use abbreviations for email addresses. ++* Indent Tabs Mode:: Don't use tabs with @TeX{} ++* Keybindings:: Create some personal keybindings. ++* Keymaps:: More about key binding. ++* Loading Files:: Load (i.e., evaluate) files automatically. ++* Autoload:: Make functions available. ++* Simple Extension:: Define a function; bind it to a key. ++* X11 Colors:: Colors in X. ++* Miscellaneous:: ++* Mode Line:: How to customize your mode line. ++@end menu ++ ++@node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization ++@ifnottex ++@unnumberedsec Emacs' Default Configuration ++@end ifnottex ++ ++There are those who appreciate Emacs' default configuration. After ++all, Emacs starts you in C mode when you edit a C file, starts you in ++Fortran mode when you edit a Fortran file, and starts you in ++Fundamental mode when you edit an unadorned file. This all makes ++sense, if you do not know who is going to use Emacs. Who knows what a ++person hopes to do with an unadorned file? Fundamental mode is the ++right default for such a file, just as C mode is the right default for ++editing C code. (Enough programming languages have syntaxes ++that enable them to share or nearly share features, so C mode is ++now provided by CC mode, the `C Collection'.) ++ ++But when you do know who is going to use Emacs---you, ++yourself---then it makes sense to customize Emacs. ++ ++For example, I seldom want Fundamental mode when I edit an ++otherwise undistinguished file; I want Text mode. This is why I ++customize Emacs: so it suits me. ++ ++You can customize and extend Emacs by writing or adapting a ++@file{~/.emacs} file. This is your personal initialization file; its ++contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You ++may also add @file{.el} to @file{~/.emacs} and call it a ++@file{~/.emacs.el} file. In the past, you were forbidden to type the ++extra keystrokes that the name @file{~/.emacs.el} requires, but now ++you may. The new format is consistent with the Emacs Lisp file ++naming conventions; the old format saves typing.} ++ ++A @file{~/.emacs} file contains Emacs Lisp code. You can write this ++code yourself; or you can use Emacs' @code{customize} feature to write ++the code for you. You can combine your own expressions and ++auto-written Customize expressions in your @file{.emacs} file. ++ ++(I myself prefer to write my own expressions, except for those, ++particularly fonts, that I find easier to manipulate using the ++@code{customize} command. I combine the two methods.) ++ ++Most of this chapter is about writing expressions yourself. It ++describes a simple @file{.emacs} file; for more information, see ++@ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and ++@ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference ++Manual}. ++ ++@node Site-wide Init, defcustom, Default Configuration, Emacs Initialization ++@section Site-wide Initialization Files ++ ++@cindex @file{default.el} init file ++@cindex @file{site-init.el} init file ++@cindex @file{site-load.el} init file ++In addition to your personal initialization file, Emacs automatically ++loads various site-wide initialization files, if they exist. These ++have the same form as your @file{.emacs} file, but are loaded by ++everyone. ++ ++Two site-wide initialization files, @file{site-load.el} and ++@file{site-init.el}, are loaded into Emacs and then `dumped' if a ++`dumped' version of Emacs is created, as is most common. (Dumped ++copies of Emacs load more quickly. However, once a file is loaded and ++dumped, a change to it does not lead to a change in Emacs unless you ++load it yourself or re-dump Emacs. @xref{Building Emacs, , Building ++Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the ++@file{INSTALL} file.) ++ ++Three other site-wide initialization files are loaded automatically ++each time you start Emacs, if they exist. These are ++@file{site-start.el}, which is loaded @emph{before} your @file{.emacs} ++file, and @file{default.el}, and the terminal type file, which are both ++loaded @emph{after} your @file{.emacs} file. ++ ++Settings and definitions in your @file{.emacs} file will overwrite ++conflicting settings and definitions in a @file{site-start.el} file, ++if it exists; but the settings and definitions in a @file{default.el} ++or terminal type file will overwrite those in your @file{.emacs} file. ++(You can prevent interference from a terminal type file by setting ++@code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A ++Simple Extension}.) ++ ++@c Rewritten to avoid overfull hbox. ++The @file{INSTALL} file that comes in the distribution contains ++descriptions of the @file{site-init.el} and @file{site-load.el} files. ++ ++The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files ++control loading. These files are in the @file{lisp} directory of the ++Emacs distribution and are worth perusing. ++ ++The @file{loaddefs.el} file contains a good many suggestions as to ++what to put into your own @file{.emacs} file, or into a site-wide ++initialization file. ++ ++@node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization ++@section Specifying Variables using @code{defcustom} ++@findex defcustom ++ ++You can specify variables using @code{defcustom} so that you and ++others can then use Emacs' @code{customize} feature to set their ++values. (You cannot use @code{customize} to write function ++definitions; but you can write @code{defuns} in your @file{.emacs} ++file. Indeed, you can write any Lisp expression in your @file{.emacs} ++file.) ++ ++The @code{customize} feature depends on the @code{defcustom} special ++form. Although you can use @code{defvar} or @code{setq} for variables ++that users set, the @code{defcustom} special form is designed for the ++job. ++ ++You can use your knowledge of @code{defvar} for writing the ++first three arguments for @code{defcustom}. The first argument to ++@code{defcustom} is the name of the variable. The second argument is ++the variable's initial value, if any; and this value is set only if ++the value has not already been set. The third argument is the ++documentation. ++ ++The fourth and subsequent arguments to @code{defcustom} specify types ++and options; these are not featured in @code{defvar}. (These ++arguments are optional.) ++ ++Each of these arguments consists of a keyword followed by a value. ++Each keyword starts with the colon character @samp{:}. ++ ++@need 1250 ++For example, the customizable user option variable ++@code{text-mode-hook} looks like this: ++ ++@smallexample ++@group ++(defcustom text-mode-hook nil ++ "Normal hook run when entering Text mode and many related modes." ++ :type 'hook ++ :options '(turn-on-auto-fill flyspell-mode) ++ :group 'data) ++@end group ++@end smallexample ++ ++@noindent ++The name of the variable is @code{text-mode-hook}; it has no default ++value; and its documentation string tells you what it does. ++ ++The @code{:type} keyword tells Emacs the kind of data to which ++@code{text-mode-hook} should be set and how to display the value in a ++Customization buffer. ++ ++The @code{:options} keyword specifies a suggested list of values for ++the variable. Usually, @code{:options} applies to a hook. ++The list is only a suggestion; it is not exclusive; a person who sets ++the variable may set it to other values; the list shown following the ++@code{:options} keyword is intended to offer convenient choices to a ++user. ++ ++Finally, the @code{:group} keyword tells the Emacs Customization ++command in which group the variable is located. This tells where to ++find it. ++ ++The @code{defcustom} function recognizes more than a dozen keywords. ++For more information, see @ref{Customization, , Writing Customization ++Definitions, elisp, The GNU Emacs Lisp Reference Manual}. ++ ++Consider @code{text-mode-hook} as an example. ++ ++There are two ways to customize this variable. You can use the ++customization command or write the appropriate expressions yourself. ++ ++@need 800 ++Using the customization command, you can type: ++ ++@smallexample ++M-x customize ++@end smallexample ++ ++@noindent ++and find that the group for editing files of data is called `data'. ++Enter that group. Text Mode Hook is the first member. You can click ++on its various options, such as @code{turn-on-auto-fill}, to set the ++values. After you click on the button to ++ ++@smallexample ++Save for Future Sessions ++@end smallexample ++ ++@noindent ++Emacs will write an expression into your @file{.emacs} file. ++It will look like this: ++ ++@smallexample ++@group ++(custom-set-variables ++ ;; custom-set-variables was added by Custom. ++ ;; If you edit it by hand, you could mess it up, so be careful. ++ ;; Your init file should contain only one such instance. ++ ;; If there is more than one, they won't work right. ++ '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) ++@end group ++@end smallexample ++ ++@noindent ++(The @code{text-mode-hook-identify} function tells ++@code{toggle-text-mode-auto-fill} which buffers are in Text mode. ++It comes on automatically.) ++ ++The @code{custom-set-variables} function works somewhat differently ++than a @code{setq}. While I have never learned the differences, I ++modify the @code{custom-set-variables} expressions in my @file{.emacs} ++file by hand: I make the changes in what appears to me to be a ++reasonable manner and have not had any problems. Others prefer to use ++the Customization command and let Emacs do the work for them. ++ ++Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. ++This function sets the various font faces. Over time, I have set a ++considerable number of faces. Some of the time, I re-set them using ++@code{customize}; other times, I simply edit the ++@code{custom-set-faces} expression in my @file{.emacs} file itself. ++ ++The second way to customize your @code{text-mode-hook} is to set it ++yourself in your @file{.emacs} file using code that has nothing to do ++with the @code{custom-set-@dots{}} functions. ++ ++@need 800 ++When you do this, and later use @code{customize}, you will see a ++message that says ++ ++@smallexample ++CHANGED outside Customize; operating on it here may be unreliable. ++@end smallexample ++ ++@need 800 ++This message is only a warning. If you click on the button to ++ ++@smallexample ++Save for Future Sessions ++@end smallexample ++ ++@noindent ++Emacs will write a @code{custom-set-@dots{}} expression near the end ++of your @file{.emacs} file that will be evaluated after your ++hand-written expression. It will, therefore, overrule your ++hand-written expression. No harm will be done. When you do this, ++however, be careful to remember which expression is active; if you ++forget, you may confuse yourself. ++ ++So long as you remember where the values are set, you will have no ++trouble. In any event, the values are always set in your ++initialization file, which is usually called @file{.emacs}. ++ ++I myself use @code{customize} for hardly anything. Mostly, I write ++expressions myself. ++ ++@findex defsubst ++@findex defconst ++Incidentally, to be more complete concerning defines: @code{defsubst} ++defines an inline function. The syntax is just like that of ++@code{defun}. @code{defconst} defines a symbol as a constant. The ++intent is that neither programs nor users should ever change a value ++set by @code{defconst}. (You can change it; the value set is a ++variable; but please do not.) ++ ++@node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization ++@section Beginning a @file{.emacs} File ++@cindex @file{.emacs} file, beginning of ++ ++When you start Emacs, it loads your @file{.emacs} file unless you tell ++it not to by specifying @samp{-q} on the command line. (The ++@code{emacs -q} command gives you a plain, out-of-the-box Emacs.) ++ ++A @file{.emacs} file contains Lisp expressions. Often, these are no ++more than expressions to set values; sometimes they are function ++definitions. ++ ++@xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs ++Manual}, for a short description of initialization files. ++ ++This chapter goes over some of the same ground, but is a walk among ++extracts from a complete, long-used @file{.emacs} file---my own. ++ ++The first part of the file consists of comments: reminders to myself. ++By now, of course, I remember these things, but when I started, I did ++not. ++ ++@need 1200 ++@smallexample ++@group ++;;;; Bob's .emacs file ++; Robert J. Chassell ++; 26 September 1985 ++@end group ++@end smallexample ++ ++@noindent ++Look at that date! I started this file a long time ago. I have been ++adding to it ever since. ++ ++@smallexample ++@group ++; Each section in this file is introduced by a ++; line beginning with four semicolons; and each ++; entry is introduced by a line beginning with ++; three semicolons. ++@end group ++@end smallexample ++ ++@noindent ++This describes the usual conventions for comments in Emacs Lisp. ++Everything on a line that follows a semicolon is a comment. Two, ++three, and four semicolons are used as subsection and section markers. ++(@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for ++more about comments.) ++ ++@smallexample ++@group ++;;;; The Help Key ++; Control-h is the help key; ++; after typing control-h, type a letter to ++; indicate the subject about which you want help. ++; For an explanation of the help facility, ++; type control-h two times in a row. ++@end group ++@end smallexample ++ ++@noindent ++Just remember: type @kbd{C-h} two times for help. ++ ++@smallexample ++@group ++; To find out about any mode, type control-h m ++; while in that mode. For example, to find out ++; about mail mode, enter mail mode and then type ++; control-h m. ++@end group ++@end smallexample ++ ++@noindent ++`Mode help', as I call this, is very helpful. Usually, it tells you ++all you need to know. ++ ++Of course, you don't need to include comments like these in your ++@file{.emacs} file. I included them in mine because I kept forgetting ++about Mode help or the conventions for comments---but I was able to ++remember to look here to remind myself. ++ ++@node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization ++@section Text and Auto Fill Mode ++ ++Now we come to the part that `turns on' Text mode and ++Auto Fill mode. ++ ++@smallexample ++@group ++;;; Text mode and Auto Fill mode ++; The next two lines put Emacs into Text mode ++; and Auto Fill mode, and are for writers who ++; want to start writing prose rather than code. ++(setq default-major-mode 'text-mode) ++(add-hook 'text-mode-hook 'turn-on-auto-fill) ++@end group ++@end smallexample ++ ++Here is the first part of this @file{.emacs} file that does something ++besides remind a forgetful human! ++ ++The first of the two lines in parentheses tells Emacs to turn on Text ++mode when you find a file, @emph{unless} that file should go into some ++other mode, such as C mode. ++ ++@cindex Per-buffer, local variables list ++@cindex Local variables list, per-buffer, ++@cindex Automatic mode selection ++@cindex Mode selection, automatic ++When Emacs reads a file, it looks at the extension to the file name, ++if any. (The extension is the part that comes after a @samp{.}.) If ++the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns ++on C mode. Also, Emacs looks at first nonblank line of the file; if ++the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs ++possesses a list of extensions and specifications that it uses ++automatically. In addition, Emacs looks near the last page for a ++per-buffer, ``local variables list'', if any. ++ ++@ifinfo ++@xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU ++Emacs Manual}. ++ ++@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs ++Manual}. ++@end ifinfo ++@iftex ++See sections ``How Major Modes are Chosen'' and ``Local Variables in ++Files'' in @cite{The GNU Emacs Manual}. ++@end iftex ++ ++Now, back to the @file{.emacs} file. ++ ++@need 800 ++Here is the line again; how does it work? ++ ++@cindex Text Mode turned on ++@smallexample ++(setq default-major-mode 'text-mode) ++@end smallexample ++ ++@noindent ++This line is a short, but complete Emacs Lisp expression. ++ ++We are already familiar with @code{setq}. It sets the following variable, ++@code{default-major-mode}, to the subsequent value, which is ++@code{text-mode}. The single quote mark before @code{text-mode} tells ++Emacs to deal directly with the @code{text-mode} variable, not with ++whatever it might stand for. @xref{set & setq, , Setting the Value of ++a Variable}, for a reminder of how @code{setq} works. The main point ++is that there is no difference between the procedure you use to set ++a value in your @file{.emacs} file and the procedure you use anywhere ++else in Emacs. ++ ++@need 800 ++Here is the next line: ++ ++@cindex Auto Fill mode turned on ++@findex add-hook ++@smallexample ++(add-hook 'text-mode-hook 'turn-on-auto-fill) ++@end smallexample ++ ++@noindent ++In this line, the @code{add-hook} command adds ++@code{turn-on-auto-fill} to the variable. ++ ++@code{turn-on-auto-fill} is the name of a program, that, you guessed ++it!, turns on Auto Fill mode. ++ ++Every time Emacs turns on Text mode, Emacs runs the commands `hooked' ++onto Text mode. So every time Emacs turns on Text mode, Emacs also ++turns on Auto Fill mode. ++ ++In brief, the first line causes Emacs to enter Text mode when you edit a ++file, unless the file name extension, a first non-blank line, or local ++variables to tell Emacs otherwise. ++ ++Text mode among other actions, sets the syntax table to work ++conveniently for writers. In Text mode, Emacs considers an apostrophe ++as part of a word like a letter; but Emacs does not consider a period ++or a space as part of a word. Thus, @kbd{M-f} moves you over ++@samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after ++the @samp{t} of @samp{it's}. ++ ++The second line causes Emacs to turn on Auto Fill mode when it turns ++on Text mode. In Auto Fill mode, Emacs automatically breaks a line ++that is too wide and brings the excessively wide part of the line down ++to the next line. Emacs breaks lines between words, not within them. ++ ++When Auto Fill mode is turned off, lines continue to the right as you ++type them. Depending on how you set the value of ++@code{truncate-lines}, the words you type either disappear off the ++right side of the screen, or else are shown, in a rather ugly and ++unreadable manner, as a continuation line on the screen. ++ ++@need 1250 ++In addition, in this part of my @file{.emacs} file, I tell the Emacs ++fill commands to insert two spaces after a colon: ++ ++@smallexample ++(setq colon-double-space t) ++@end smallexample ++ ++@node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization ++@section Mail Aliases ++ ++Here is a @code{setq} that `turns on' mail aliases, along with more ++reminders. ++ ++@smallexample ++@group ++;;; Mail mode ++; To enter mail mode, type `C-x m' ++; To enter RMAIL (for reading mail), ++; type `M-x rmail' ++(setq mail-aliases t) ++@end group ++@end smallexample ++ ++@cindex Mail aliases ++@noindent ++This @code{setq} command sets the value of the variable ++@code{mail-aliases} to @code{t}. Since @code{t} means true, the line ++says, in effect, ``Yes, use mail aliases.'' ++ ++Mail aliases are convenient short names for long email addresses or ++for lists of email addresses. The file where you keep your `aliases' ++is @file{~/.mailrc}. You write an alias like this: ++ ++@smallexample ++alias geo george@@foobar.wiz.edu ++@end smallexample ++ ++@noindent ++When you write a message to George, address it to @samp{geo}; the ++mailer will automatically expand @samp{geo} to the full address. ++ ++@node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization ++@section Indent Tabs Mode ++@cindex Tabs, preventing ++@findex indent-tabs-mode ++ ++By default, Emacs inserts tabs in place of multiple spaces when it ++formats a region. (For example, you might indent many lines of text ++all at once with the @code{indent-region} command.) Tabs look fine on ++a terminal or with ordinary printing, but they produce badly indented ++output when you use @TeX{} or Texinfo since @TeX{} ignores tabs. ++ ++@need 1250 ++The following turns off Indent Tabs mode: ++ ++@smallexample ++@group ++;;; Prevent Extraneous Tabs ++(setq-default indent-tabs-mode nil) ++@end group ++@end smallexample ++ ++Note that this line uses @code{setq-default} rather than the ++@code{setq} command that we have seen before. The @code{setq-default} ++command sets values only in buffers that do not have their own local ++values for the variable. ++ ++@ifinfo ++@xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}. ++ ++@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs ++Manual}. ++@end ifinfo ++@iftex ++See sections ``Tabs vs.@: Spaces'' and ``Local Variables in ++Files'' in @cite{The GNU Emacs Manual}. ++@end iftex ++ ++@need 1700 ++@node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization ++@section Some Keybindings ++ ++Now for some personal keybindings: ++ ++@smallexample ++@group ++;;; Compare windows ++(global-set-key "\C-cw" 'compare-windows) ++@end group ++@end smallexample ++ ++@findex compare-windows ++@code{compare-windows} is a nifty command that compares the text in ++your current window with text in the next window. It makes the ++comparison by starting at point in each window, moving over text in ++each window as far as they match. I use this command all the time. ++ ++This also shows how to set a key globally, for all modes. ++ ++@cindex Setting a key globally ++@cindex Global set key ++@cindex Key setting globally ++@findex global-set-key ++The command is @code{global-set-key}. It is followed by the ++keybinding. In a @file{.emacs} file, the keybinding is written as ++shown: @code{\C-c} stands for `control-c', which means `press the ++control key and the @key{c} key at the same time'. The @code{w} means ++`press the @key{w} key'. The keybinding is surrounded by double ++quotation marks. In documentation, you would write this as ++@w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as ++@kbd{M-c}, rather than a @key{CTRL} key, you would write ++@w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, , ++Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for ++details.) ++ ++The command invoked by the keys is @code{compare-windows}. Note that ++@code{compare-windows} is preceded by a single quote; otherwise, Emacs ++would first try to evaluate the symbol to determine its value. ++ ++These three things, the double quotation marks, the backslash before ++the @samp{C}, and the single quote mark are necessary parts of ++keybinding that I tend to forget. Fortunately, I have come to ++remember that I should look at my existing @file{.emacs} file, and ++adapt what is there. ++ ++As for the keybinding itself: @kbd{C-c w}. This combines the prefix ++key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This ++set of keys, @kbd{C-c} followed by a single character, is strictly ++reserved for individuals' own use. (I call these `own' keys, since ++these are for my own use.) You should always be able to create such a ++keybinding for your own use without stomping on someone else's ++keybinding. If you ever write an extension to Emacs, please avoid ++taking any of these keys for public use. Create a key like @kbd{C-c ++C-w} instead. Otherwise, we will run out of `own' keys. ++ ++@need 1250 ++Here is another keybinding, with a comment: ++ ++@smallexample ++@group ++;;; Keybinding for `occur' ++; I use occur a lot, so let's bind it to a key: ++(global-set-key "\C-co" 'occur) ++@end group ++@end smallexample ++ ++@findex occur ++The @code{occur} command shows all the lines in the current buffer ++that contain a match for a regular expression. Matching lines are ++shown in a buffer called @file{*Occur*}. That buffer serves as a menu ++to jump to occurrences. ++ ++@findex global-unset-key ++@cindex Unbinding key ++@cindex Key unbinding ++@need 1250 ++Here is how to unbind a key, so it does not ++work: ++ ++@smallexample ++@group ++;;; Unbind `C-x f' ++(global-unset-key "\C-xf") ++@end group ++@end smallexample ++ ++There is a reason for this unbinding: I found I inadvertently typed ++@w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a ++file, as I intended, I accidentally set the width for filled text, ++almost always to a width I did not want. Since I hardly ever reset my ++default width, I simply unbound the key. ++ ++@findex list-buffers, @r{rebound} ++@findex buffer-menu, @r{bound to key} ++@need 1250 ++The following rebinds an existing key: ++ ++@smallexample ++@group ++;;; Rebind `C-x C-b' for `buffer-menu' ++(global-set-key "\C-x\C-b" 'buffer-menu) ++@end group ++@end smallexample ++ ++By default, @kbd{C-x C-b} runs the ++@code{list-buffers} command. This command lists ++your buffers in @emph{another} window. Since I ++almost always want to do something in that ++window, I prefer the @code{buffer-menu} ++command, which not only lists the buffers, ++but moves point into that window. ++ ++@node Keymaps, Loading Files, Keybindings, Emacs Initialization ++@section Keymaps ++@cindex Keymaps ++@cindex Rebinding keys ++ ++Emacs uses @dfn{keymaps} to record which keys call which commands. ++When you use @code{global-set-key} to set the keybinding for a single ++command in all parts of Emacs, you are specifying the keybinding in ++@code{current-global-map}. ++ ++Specific modes, such as C mode or Text mode, have their own keymaps; ++the mode-specific keymaps override the global map that is shared by ++all buffers. ++ ++The @code{global-set-key} function binds, or rebinds, the global ++keymap. For example, the following binds the key @kbd{C-x C-b} to the ++function @code{buffer-menu}: ++ ++@smallexample ++(global-set-key "\C-x\C-b" 'buffer-menu) ++@end smallexample ++ ++Mode-specific keymaps are bound using the @code{define-key} function, ++which takes a specific keymap as an argument, as well as the key and ++the command. For example, my @file{.emacs} file contains the ++following expression to bind the @code{texinfo-insert-@@group} command ++to @kbd{C-c C-c g}: ++ ++@smallexample ++@group ++(define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group) ++@end group ++@end smallexample ++ ++@noindent ++The @code{texinfo-insert-@@group} function itself is a little extension ++to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I ++use this command all the time and prefer to type the three strokes ++@kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}. ++(@samp{@@group} and its matching @samp{@@end group} are commands that ++keep all enclosed text together on one page; many multi-line examples ++in this book are surrounded by @samp{@@group @dots{} @@end group}.) ++ ++@need 1250 ++Here is the @code{texinfo-insert-@@group} function definition: ++ ++@smallexample ++@group ++(defun texinfo-insert-@@group () ++ "Insert the string @@group in a Texinfo buffer." ++ (interactive) ++ (beginning-of-line) ++ (insert "@@group\n")) ++@end group ++@end smallexample ++ ++(Of course, I could have used Abbrev mode to save typing, rather than ++write a function to insert a word; but I prefer key strokes consistent ++with other Texinfo mode key bindings.) ++ ++You will see numerous @code{define-key} expressions in ++@file{loaddefs.el} as well as in the various mode libraries, such as ++@file{cc-mode.el} and @file{lisp-mode.el}. ++ ++@xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs ++Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp ++Reference Manual}, for more information about keymaps. ++ ++@node Loading Files, Autoload, Keymaps, Emacs Initialization ++@section Loading Files ++@cindex Loading files ++@c findex load ++ ++Many people in the GNU Emacs community have written extensions to ++Emacs. As time goes by, these extensions are often included in new ++releases. For example, the Calendar and Diary packages are now part ++of the standard GNU Emacs, as is Calc. ++ ++You can use a @code{load} command to evaluate a complete file and ++thereby install all the functions and variables in the file into Emacs. ++For example: ++ ++@c (auto-compression-mode t) ++ ++@smallexample ++(load "~/emacs/slowsplit") ++@end smallexample ++ ++This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it ++exists, the faster, byte compiled @file{slowsplit.elc} file from the ++@file{emacs} sub-directory of your home directory. The file contains ++the function @code{split-window-quietly}, which John Robinson wrote in ++1989. ++ ++The @code{split-window-quietly} function splits a window with the ++minimum of redisplay. I installed it in 1989 because it worked well ++with the slow 1200 baud terminals I was then using. Nowadays, I only ++occasionally come across such a slow connection, but I continue to use ++the function because I like the way it leaves the bottom half of a ++buffer in the lower of the new windows and the top half in the upper ++window. ++ ++@need 1250 ++To replace the key binding for the default ++@code{split-window-vertically}, you must also unset that key and bind ++the keys to @code{split-window-quietly}, like this: ++ ++@smallexample ++@group ++(global-unset-key "\C-x2") ++(global-set-key "\C-x2" 'split-window-quietly) ++@end group ++@end smallexample ++ ++@vindex load-path ++If you load many extensions, as I do, then instead of specifying the ++exact location of the extension file, as shown above, you can specify ++that directory as part of Emacs' @code{load-path}. Then, when Emacs ++loads a file, it will search that directory as well as its default ++list of directories. (The default list is specified in @file{paths.h} ++when Emacs is built.) ++ ++@need 1250 ++The following command adds your @file{~/emacs} directory to the ++existing load path: ++ ++@smallexample ++@group ++;;; Emacs Load Path ++(setq load-path (cons "~/emacs" load-path)) ++@end group ++@end smallexample ++ ++Incidentally, @code{load-library} is an interactive interface to the ++@code{load} function. The complete function looks like this: ++ ++@findex load-library ++@smallexample ++@group ++(defun load-library (library) ++ "Load the library named LIBRARY. ++This is an interface to the function `load'." ++ (interactive ++ (list (completing-read "Load library: " ++ (apply-partially 'locate-file-completion-table ++ load-path ++ (get-load-suffixes))))) ++ (load library)) ++@end group ++@end smallexample ++ ++The name of the function, @code{load-library}, comes from the use of ++`library' as a conventional synonym for `file'. The source for the ++@code{load-library} command is in the @file{files.el} library. ++ ++Another interactive command that does a slightly different job is ++@code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for ++Emacs, emacs, The GNU Emacs Manual}, for information on the ++distinction between @code{load-library} and this command. ++ ++@node Autoload, Simple Extension, Loading Files, Emacs Initialization ++@section Autoloading ++@findex autoload ++ ++Instead of installing a function by loading the file that contains it, ++or by evaluating the function definition, you can make the function ++available but not actually install it until it is first called. This ++is called @dfn{autoloading}. ++ ++When you execute an autoloaded function, Emacs automatically evaluates ++the file that contains the definition, and then calls the function. ++ ++Emacs starts quicker with autoloaded functions, since their libraries ++are not loaded right away; but you need to wait a moment when you ++first use such a function, while its containing file is evaluated. ++ ++Rarely used functions are frequently autoloaded. The ++@file{loaddefs.el} library contains hundreds of autoloaded functions, ++from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may ++come to use a `rare' function frequently. When you do, you should ++load that function's file with a @code{load} expression in your ++@file{.emacs} file. ++ ++In my @file{.emacs} file, I load 14 libraries that contain functions ++that would otherwise be autoloaded. (Actually, it would have been ++better to include these files in my `dumped' Emacs, but I forgot. ++@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp ++Reference Manual}, and the @file{INSTALL} file for more about ++dumping.) ++ ++You may also want to include autoloaded expressions in your @file{.emacs} ++file. @code{autoload} is a built-in function that takes up to five ++arguments, the final three of which are optional. The first argument ++is the name of the function to be autoloaded; the second is the name ++of the file to be loaded. The third argument is documentation for the ++function, and the fourth tells whether the function can be called ++interactively. The fifth argument tells what type of ++object---@code{autoload} can handle a keymap or macro as well as a ++function (the default is a function). ++ ++@need 800 ++Here is a typical example: ++ ++@smallexample ++@group ++(autoload 'html-helper-mode ++ "html-helper-mode" "Edit HTML documents" t) ++@end group ++@end smallexample ++ ++@noindent ++(@code{html-helper-mode} is an older alternative to @code{html-mode}, ++which is a standard part of the distribution.) ++ ++@noindent ++This expression autoloads the @code{html-helper-mode} function. It ++takes it from the @file{html-helper-mode.el} file (or from the byte ++compiled version @file{html-helper-mode.elc}, if that exists.) The ++file must be located in a directory specified by @code{load-path}. ++The documentation says that this is a mode to help you edit documents ++written in the HyperText Markup Language. You can call this mode ++interactively by typing @kbd{M-x html-helper-mode}. (You need to ++duplicate the function's regular documentation in the autoload ++expression because the regular function is not yet loaded, so its ++documentation is not available.) ++ ++@xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference ++Manual}, for more information. ++ ++@node Simple Extension, X11 Colors, Autoload, Emacs Initialization ++@section A Simple Extension: @code{line-to-top-of-window} ++@findex line-to-top-of-window ++@cindex Simple extension in @file{.emacs} file ++ ++Here is a simple extension to Emacs that moves the line point is on to ++the top of the window. I use this all the time, to make text easier ++to read. ++ ++You can put the following code into a separate file and then load it ++from your @file{.emacs} file, or you can include it within your ++@file{.emacs} file. ++ ++@need 1250 ++Here is the definition: ++ ++@smallexample ++@group ++;;; Line to top of window; ++;;; replace three keystroke sequence C-u 0 C-l ++(defun line-to-top-of-window () ++ "Move the line point is on to top of window." ++ (interactive) ++ (recenter 0)) ++@end group ++@end smallexample ++ ++@need 1250 ++Now for the keybinding. ++ ++Nowadays, function keys as well as mouse button events and ++non-@sc{ascii} characters are written within square brackets, without ++quotation marks. (In Emacs version 18 and before, you had to write ++different function key bindings for each different make of terminal.) ++ ++I bind @code{line-to-top-of-window} to my @key{F6} function key like ++this: ++ ++@smallexample ++(global-set-key [f6] 'line-to-top-of-window) ++@end smallexample ++ ++For more information, see @ref{Init Rebinding, , Rebinding Keys in ++Your Init File, emacs, The GNU Emacs Manual}. ++ ++@cindex Conditional 'twixt two versions of Emacs ++@cindex Version of Emacs, choosing ++@cindex Emacs version, choosing ++If you run two versions of GNU Emacs, such as versions 22 and 23, and ++use one @file{.emacs} file, you can select which code to evaluate with ++the following conditional: ++ ++@smallexample ++@group ++(cond ++ ((= 22 emacs-major-version) ++ ;; evaluate version 21 code ++ ( @dots{} )) ++ ((= 23 emacs-major-version) ++ ;; evaluate version 22 code ++ ( @dots{} ))) ++@end group ++@end smallexample ++ ++For example, in contrast to version 20, more recent versions blink ++their cursors by default. I hate such blinking, as well as other ++features, so I placed the following in my @file{.emacs} ++file@footnote{When I start instances of Emacs that do not load my ++@file{.emacs} file or any site file, I also turn off blinking: ++ ++@smallexample ++emacs -q --no-site-file -eval '(blink-cursor-mode nil)' ++ ++@exdent Or nowadays, using an even more sophisticated set of options, ++ ++emacs -Q - D ++@end smallexample ++}: ++ ++@smallexample ++@group ++(when (>= emacs-major-version 21) ++ (blink-cursor-mode 0) ++ ;; Insert newline when you press `C-n' (next-line) ++ ;; at the end of the buffer ++ (setq next-line-add-newlines t) ++@end group ++@group ++ ;; Turn on image viewing ++ (auto-image-file-mode t) ++@end group ++@group ++ ;; Turn on menu bar (this bar has text) ++ ;; (Use numeric argument to turn on) ++ (menu-bar-mode 1) ++@end group ++@group ++ ;; Turn off tool bar (this bar has icons) ++ ;; (Use numeric argument to turn on) ++ (tool-bar-mode nil) ++@end group ++@group ++ ;; Turn off tooltip mode for tool bar ++ ;; (This mode causes icon explanations to pop up) ++ ;; (Use numeric argument to turn on) ++ (tooltip-mode nil) ++ ;; If tooltips turned on, make tips appear promptly ++ (setq tooltip-delay 0.1) ; default is 0.7 second ++ ) ++@end group ++@end smallexample ++ ++@node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization ++@section X11 Colors ++ ++You can specify colors when you use Emacs with the MIT X Windowing ++system. ++ ++I dislike the default colors and specify my own. ++ ++@need 1250 ++Here are the expressions in my @file{.emacs} ++file that set values: ++ ++@smallexample ++@group ++;; Set cursor color ++(set-cursor-color "white") ++ ++;; Set mouse color ++(set-mouse-color "white") ++ ++;; Set foreground and background ++(set-foreground-color "white") ++(set-background-color "darkblue") ++@end group ++ ++@group ++;;; Set highlighting colors for isearch and drag ++(set-face-foreground 'highlight "white") ++(set-face-background 'highlight "blue") ++@end group ++ ++@group ++(set-face-foreground 'region "cyan") ++(set-face-background 'region "blue") ++@end group ++ ++@group ++(set-face-foreground 'secondary-selection "skyblue") ++(set-face-background 'secondary-selection "darkblue") ++@end group ++ ++@group ++;; Set calendar highlighting colors ++(setq calendar-load-hook ++ '(lambda () ++ (set-face-foreground 'diary-face "skyblue") ++ (set-face-background 'holiday-face "slate blue") ++ (set-face-foreground 'holiday-face "white"))) ++@end group ++@end smallexample ++ ++The various shades of blue soothe my eye and prevent me from seeing ++the screen flicker. ++ ++Alternatively, I could have set my specifications in various X ++initialization files. For example, I could set the foreground, ++background, cursor, and pointer (i.e., mouse) colors in my ++@file{~/.Xresources} file like this: ++ ++@smallexample ++@group ++Emacs*foreground: white ++Emacs*background: darkblue ++Emacs*cursorColor: white ++Emacs*pointerColor: white ++@end group ++@end smallexample ++ ++In any event, since it is not part of Emacs, I set the root color of ++my X window in my @file{~/.xinitrc} file, like this@footnote{I also ++run more modern window managers, such as Enlightenment, Gnome, or KDE; ++in those cases, I often specify an image rather than a plain color.}: ++ ++@smallexample ++xsetroot -solid Navy -fg white & ++@end smallexample ++ ++@need 1700 ++@node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization ++@section Miscellaneous Settings for a @file{.emacs} File ++ ++@need 1250 ++Here are a few miscellaneous settings: ++@sp 1 ++ ++@itemize @minus ++@item ++Set the shape and color of the mouse cursor: ++ ++@smallexample ++@group ++; Cursor shapes are defined in ++; `/usr/include/X11/cursorfont.h'; ++; for example, the `target' cursor is number 128; ++; the `top_left_arrow' cursor is number 132. ++@end group ++ ++@group ++(let ((mpointer (x-get-resource "*mpointer" ++ "*emacs*mpointer"))) ++ ;; If you have not set your mouse pointer ++ ;; then set it, otherwise leave as is: ++ (if (eq mpointer nil) ++ (setq mpointer "132")) ; top_left_arrow ++@end group ++@group ++ (setq x-pointer-shape (string-to-int mpointer)) ++ (set-mouse-color "white")) ++@end group ++@end smallexample ++ ++@item ++Or you can set the values of a variety of features in an alist, like ++this: ++ ++@smallexample ++@group ++(setq-default ++ default-frame-alist ++ '((cursor-color . "white") ++ (mouse-color . "white") ++ (foreground-color . "white") ++ (background-color . "DodgerBlue4") ++ ;; (cursor-type . bar) ++ (cursor-type . box) ++@end group ++@group ++ (tool-bar-lines . 0) ++ (menu-bar-lines . 1) ++ (width . 80) ++ (height . 58) ++ (font . ++ "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1") ++ )) ++@end group ++@end smallexample ++ ++@item ++Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL} ++into @kbd{@key{CTRL}-h}.@* ++(Some older keyboards needed this, although I have not seen the ++problem recently.) ++ ++@smallexample ++@group ++;; Translate `C-h' to . ++; (keyboard-translate ?\C-h ?\C-?) ++ ++;; Translate to `C-h'. ++(keyboard-translate ?\C-? ?\C-h) ++@end group ++@end smallexample ++ ++@item Turn off a blinking cursor! ++ ++@smallexample ++@group ++(if (fboundp 'blink-cursor-mode) ++ (blink-cursor-mode -1)) ++@end group ++@end smallexample ++ ++@noindent ++or start GNU Emacs with the command @code{emacs -nbc}. ++ ++@need 1250 ++@item When using `grep'@* ++@samp{-i}@w{ } Ignore case distinctions@* ++@samp{-n}@w{ } Prefix each line of output with line number@* ++@samp{-H}@w{ } Print the filename for each match.@* ++@samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-} ++ ++@smallexample ++(setq grep-command "grep -i -nH -e ") ++@end smallexample ++ ++@ignore ++@c Evidently, no longer needed in GNU Emacs 22 ++ ++item Automatically uncompress compressed files when visiting them ++ ++smallexample ++(load "uncompress") ++end smallexample ++ ++@end ignore ++ ++@item Find an existing buffer, even if it has a different name@* ++This avoids problems with symbolic links. ++ ++@smallexample ++(setq find-file-existing-other-name t) ++@end smallexample ++ ++@item Set your language environment and default input method ++ ++@smallexample ++@group ++(set-language-environment "latin-1") ++;; Remember you can enable or disable multilingual text input ++;; with the @code{toggle-input-method'} (@kbd{C-\}) command ++(setq default-input-method "latin-1-prefix") ++@end group ++@end smallexample ++ ++If you want to write with Chinese `GB' characters, set this instead: ++ ++@smallexample ++@group ++(set-language-environment "Chinese-GB") ++(setq default-input-method "chinese-tonepy") ++@end group ++@end smallexample ++@end itemize ++ ++@subsubheading Fixing Unpleasant Key Bindings ++@cindex Key bindings, fixing ++@cindex Bindings, key, fixing unpleasant ++ ++Some systems bind keys unpleasantly. Sometimes, for example, the ++@key{CTRL} key appears in an awkward spot rather than at the far left ++of the home row. ++ ++Usually, when people fix these sorts of keybindings, they do not ++change their @file{~/.emacs} file. Instead, they bind the proper keys ++on their consoles with the @code{loadkeys} or @code{install-keymap} ++commands in their boot script and then include @code{xmodmap} commands ++in their @file{.xinitrc} or @file{.Xsession} file for X Windows. ++ ++@need 1250 ++@noindent ++For a boot script: ++ ++@smallexample ++@group ++loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz ++@exdent or ++install-keymap emacs2 ++@end group ++@end smallexample ++ ++@need 1250 ++@noindent ++For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps ++Lock} key is at the far left of the home row: ++ ++@smallexample ++@group ++# Bind the key labeled `Caps Lock' to `Control' ++# (Such a broken user interface suggests that keyboard manufacturers ++# think that computers are typewriters from 1885.) ++ ++xmodmap -e "clear Lock" ++xmodmap -e "add Control = Caps_Lock" ++@end group ++@end smallexample ++ ++@need 1250 ++@noindent ++In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} ++key to a @key{META} key: ++ ++@smallexample ++@group ++# Some ill designed keyboards have a key labeled ALT and no Meta ++xmodmap -e "keysym Alt_L = Meta_L Alt_L" ++@end group ++@end smallexample ++ ++@need 1700 ++@node Mode Line, , Miscellaneous, Emacs Initialization ++@section A Modified Mode Line ++@vindex default-mode-line-format ++@cindex Mode line format ++ ++Finally, a feature I really like: a modified mode line. ++ ++When I work over a network, I forget which machine I am using. Also, ++I tend to I lose track of where I am, and which line point is on. ++ ++So I reset my mode line to look like this: ++ ++@smallexample ++-:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top ++@end smallexample ++ ++I am visiting a file called @file{foo.texi}, on my machine ++@file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in ++Texinfo mode, and am at the top of the buffer. ++ ++@need 1200 ++My @file{.emacs} file has a section that looks like this: ++ ++@smallexample ++@group ++;; Set a Mode Line that tells me which machine, which directory, ++;; and which line I am on, plus the other customary information. ++(setq default-mode-line-format ++ (quote ++ (#("-" 0 1 ++ (help-echo ++ "mouse-1: select window, mouse-2: delete others ...")) ++ mode-line-mule-info ++ mode-line-modified ++ mode-line-frame-identification ++ " " ++@end group ++@group ++ mode-line-buffer-identification ++ " " ++ (:eval (substring ++ (system-name) 0 (string-match "\\..+" (system-name)))) ++ ":" ++ default-directory ++ #(" " 0 1 ++ (help-echo ++ "mouse-1: select window, mouse-2: delete others ...")) ++ (line-number-mode " Line %l ") ++ global-mode-string ++@end group ++@group ++ #(" %[(" 0 6 ++ (help-echo ++ "mouse-1: select window, mouse-2: delete others ...")) ++ (:eval (mode-line-mode-name)) ++ mode-line-process ++ minor-mode-alist ++ #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...))) ++ ")%] " ++ (-3 . "%P") ++ ;; "-%-" ++ ))) ++@end group ++@end smallexample ++ ++@noindent ++Here, I redefine the default mode line. Most of the parts are from ++the original; but I make a few changes. I set the @emph{default} mode ++line format so as to permit various modes, such as Info, to override ++it. ++ ++Many elements in the list are self-explanatory: ++@code{mode-line-modified} is a variable that tells whether the buffer ++has been modified, @code{mode-name} tells the name of the mode, and so ++on. However, the format looks complicated because of two features we ++have not discussed. ++ ++@cindex Properties, in mode line example ++The first string in the mode line is a dash or hyphen, @samp{-}. In ++the old days, it would have been specified simply as @code{"-"}. But ++nowadays, Emacs can add properties to a string, such as highlighting ++or, as in this case, a help feature. If you place your mouse cursor ++over the hyphen, some help information appears (By default, you must ++wait seven-tenths of a second before the information appears. You can ++change that timing by changing the value of @code{tooltip-delay}.) ++ ++@need 1000 ++The new string format has a special syntax: ++ ++@smallexample ++#("-" 0 1 (help-echo "mouse-1: select window, ...")) ++@end smallexample ++ ++@noindent ++The @code{#(} begins a list. The first element of the list is the ++string itself, just one @samp{-}. The second and third ++elements specify the range over which the fourth element applies. A ++range starts @emph{after} a character, so a zero means the range ++starts just before the first character; a 1 means that the range ends ++just after the first character. The third element is the property for ++the range. It consists of a property list, a ++property name, in this case, @samp{help-echo}, followed by a value, in this ++case, a string. The second, third, and fourth elements of this new ++string format can be repeated. ++ ++@xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp ++Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, ++elisp, The GNU Emacs Lisp Reference Manual}, for more information. ++ ++@code{mode-line-buffer-identification} ++displays the current buffer name. It is a list ++beginning @code{(#("%12b" 0 4 @dots{}}. ++The @code{#(} begins the list. ++ ++The @samp{"%12b"} displays the current buffer name, using the ++@code{buffer-name} function with which we are familiar; the `12' ++specifies the maximum number of characters that will be displayed. ++When a name has fewer characters, whitespace is added to fill out to ++this number. (Buffer names can and often should be longer than 12 ++characters; this length works well in a typical 80 column wide ++window.) ++ ++@code{:eval} says to evaluate the following form and use the result as ++a string to display. In this case, the expression displays the first ++component of the full system name. The end of the first component is ++a @samp{.} (`period'), so I use the @code{string-match} function to ++tell me the length of the first component. The substring from the ++zeroth character to that length is the name of the machine. ++ ++@need 1250 ++This is the expression: ++ ++@smallexample ++@group ++(:eval (substring ++ (system-name) 0 (string-match "\\..+" (system-name)))) ++@end group ++@end smallexample ++ ++@samp{%[} and @samp{%]} cause a pair of square brackets ++to appear for each recursive editing level. @samp{%n} says `Narrow' ++when narrowing is in effect. @samp{%P} tells you the percentage of ++the buffer that is above the bottom of the window, or `Top', `Bottom', ++or `All'. (A lower case @samp{p} tell you the percentage above the ++@emph{top} of the window.) @samp{%-} inserts enough dashes to fill ++out the line. ++ ++Remember, ``You don't have to like Emacs to like it'' --- your own ++Emacs can have different colors, different commands, and different ++keys than a default Emacs. ++ ++On the other hand, if you want to bring up a plain `out of the box' ++Emacs, with no customization, type: ++ ++@smallexample ++emacs -q ++@end smallexample ++ ++@noindent ++This will start an Emacs that does @emph{not} load your ++@file{~/.emacs} initialization file. A plain, default Emacs. Nothing ++more. ++ ++@node Debugging, Conclusion, Emacs Initialization, Top ++@chapter Debugging ++@cindex debugging ++ ++GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The ++first is built into the internals of Emacs and is always with you; ++the second requires that you instrument a function before you can use it. ++ ++Both debuggers are described extensively in @ref{Debugging, , ++Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}. ++In this chapter, I will walk through a short example of each. ++ ++@menu ++* debug:: How to use the built-in debugger. ++* debug-on-entry:: Start debugging when you call a function. ++* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. ++* edebug:: How to use Edebug, a source level debugger. ++* Debugging Exercises:: ++@end menu ++ ++@node debug, debug-on-entry, Debugging, Debugging ++@section @code{debug} ++@findex debug ++ ++Suppose you have written a function definition that is intended to ++return the sum of the numbers 1 through a given number. (This is the ++@code{triangle} function discussed earlier. @xref{Decrementing ++Example, , Example with Decrementing Counter}, for a discussion.) ++@c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.) ++ ++However, your function definition has a bug. You have mistyped ++@samp{1=} for @samp{1-}. Here is the broken definition: ++ ++@findex triangle-bugged ++@smallexample ++@group ++(defun triangle-bugged (number) ++ "Return sum of numbers 1 through NUMBER inclusive." ++ (let ((total 0)) ++ (while (> number 0) ++ (setq total (+ total number)) ++ (setq number (1= number))) ; @r{Error here.} ++ total)) ++@end group ++@end smallexample ++ ++If you are reading this in Info, you can evaluate this definition in ++the normal fashion. You will see @code{triangle-bugged} appear in the ++echo area. ++ ++@need 1250 ++Now evaluate the @code{triangle-bugged} function with an ++argument of 4: ++ ++@smallexample ++(triangle-bugged 4) ++@end smallexample ++ ++@noindent ++In a recent GNU Emacs, you will create and enter a @file{*Backtrace*} ++buffer that says: ++ ++@noindent ++@smallexample ++@group ++---------- Buffer: *Backtrace* ---------- ++Debugger entered--Lisp error: (void-function 1=) ++ (1= number) ++ (setq number (1= number)) ++ (while (> number 0) (setq total (+ total number)) ++ (setq number (1= number))) ++ (let ((total 0)) (while (> number 0) (setq total ...) ++ (setq number ...)) total) ++ triangle-bugged(4) ++@end group ++@group ++ eval((triangle-bugged 4)) ++ eval-last-sexp-1(nil) ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++---------- Buffer: *Backtrace* ---------- ++@end group ++@end smallexample ++ ++@noindent ++(I have reformatted this example slightly; the debugger does not fold ++long lines. As usual, you can quit the debugger by typing @kbd{q} in ++the @file{*Backtrace*} buffer.) ++ ++In practice, for a bug as simple as this, the `Lisp error' line will ++tell you what you need to know to correct the definition. The ++function @code{1=} is `void'. ++ ++@ignore ++@need 800 ++In GNU Emacs 20 and before, you will see: ++ ++@smallexample ++Symbol's function definition is void:@: 1= ++@end smallexample ++ ++@noindent ++which has the same meaning as the @file{*Backtrace*} buffer line in ++version 21. ++@end ignore ++ ++However, suppose you are not quite certain what is going on? ++You can read the complete backtrace. ++ ++In this case, you need to run a recent GNU Emacs, which automatically ++starts the debugger that puts you in the @file{*Backtrace*} buffer; or ++else, you need to start the debugger manually as described below. ++ ++Read the @file{*Backtrace*} buffer from the bottom up; it tells you ++what Emacs did that led to the error. Emacs made an interactive call ++to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation ++of the @code{triangle-bugged} expression. Each line above tells you ++what the Lisp interpreter evaluated next. ++ ++@need 1250 ++The third line from the top of the buffer is ++ ++@smallexample ++(setq number (1= number)) ++@end smallexample ++ ++@noindent ++Emacs tried to evaluate this expression; in order to do so, it tried ++to evaluate the inner expression shown on the second line from the ++top: ++ ++@smallexample ++(1= number) ++@end smallexample ++ ++@need 1250 ++@noindent ++This is where the error occurred; as the top line says: ++ ++@smallexample ++Debugger entered--Lisp error: (void-function 1=) ++@end smallexample ++ ++@noindent ++You can correct the mistake, re-evaluate the function definition, and ++then run your test again. ++ ++@node debug-on-entry, debug-on-quit, debug, Debugging ++@section @code{debug-on-entry} ++@findex debug-on-entry ++ ++A recent GNU Emacs starts the debugger automatically when your ++function has an error. ++ ++@ignore ++GNU Emacs version 20 and before did not; it simply ++presented you with an error message. You had to start the debugger ++manually. ++@end ignore ++ ++Incidentally, you can start the debugger manually for all versions of ++Emacs; the advantage is that the debugger runs even if you do not have ++a bug in your code. Sometimes your code will be free of bugs! ++ ++You can enter the debugger when you call the function by calling ++@code{debug-on-entry}. ++ ++@need 1250 ++@noindent ++Type: ++ ++@smallexample ++M-x debug-on-entry RET triangle-bugged RET ++@end smallexample ++ ++@need 1250 ++@noindent ++Now, evaluate the following: ++ ++@smallexample ++(triangle-bugged 5) ++@end smallexample ++ ++@noindent ++All versions of Emacs will create a @file{*Backtrace*} buffer and tell ++you that it is beginning to evaluate the @code{triangle-bugged} ++function: ++ ++@smallexample ++@group ++---------- Buffer: *Backtrace* ---------- ++Debugger entered--entering a function: ++* triangle-bugged(5) ++ eval((triangle-bugged 5)) ++@end group ++@group ++ eval-last-sexp-1(nil) ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++---------- Buffer: *Backtrace* ---------- ++@end group ++@end smallexample ++ ++In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate ++the first expression in @code{triangle-bugged}; the buffer will look ++like this: ++ ++@smallexample ++@group ++---------- Buffer: *Backtrace* ---------- ++Debugger entered--beginning evaluation of function call form: ++* (let ((total 0)) (while (> number 0) (setq total ...) ++ (setq number ...)) total) ++* triangle-bugged(5) ++ eval((triangle-bugged 5)) ++@end group ++@group ++ eval-last-sexp-1(nil) ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++---------- Buffer: *Backtrace* ---------- ++@end group ++@end smallexample ++ ++@noindent ++Now, type @kbd{d} again, eight times, slowly. Each time you type ++@kbd{d}, Emacs will evaluate another expression in the function ++definition. ++ ++@need 1750 ++Eventually, the buffer will look like this: ++ ++@smallexample ++@group ++---------- Buffer: *Backtrace* ---------- ++Debugger entered--beginning evaluation of function call form: ++* (setq number (1= number)) ++* (while (> number 0) (setq total (+ total number)) ++ (setq number (1= number))) ++@group ++@end group ++* (let ((total 0)) (while (> number 0) (setq total ...) ++ (setq number ...)) total) ++* triangle-bugged(5) ++ eval((triangle-bugged 5)) ++@group ++@end group ++ eval-last-sexp-1(nil) ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++---------- Buffer: *Backtrace* ---------- ++@end group ++@end smallexample ++ ++@need 1500 ++@noindent ++Finally, after you type @kbd{d} two more times, Emacs will reach the ++error, and the top two lines of the @file{*Backtrace*} buffer will look ++like this: ++ ++@smallexample ++@group ++---------- Buffer: *Backtrace* ---------- ++Debugger entered--Lisp error: (void-function 1=) ++* (1= number) ++@dots{} ++---------- Buffer: *Backtrace* ---------- ++@end group ++@end smallexample ++ ++By typing @kbd{d}, you were able to step through the function. ++ ++You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this ++quits the trace, but does not cancel @code{debug-on-entry}. ++ ++@findex cancel-debug-on-entry ++To cancel the effect of @code{debug-on-entry}, call ++@code{cancel-debug-on-entry} and the name of the function, like this: ++ ++@smallexample ++M-x cancel-debug-on-entry RET triangle-bugged RET ++@end smallexample ++ ++@noindent ++(If you are reading this in Info, cancel @code{debug-on-entry} now.) ++ ++@node debug-on-quit, edebug, debug-on-entry, Debugging ++@section @code{debug-on-quit} and @code{(debug)} ++ ++In addition to setting @code{debug-on-error} or calling @code{debug-on-entry}, ++there are two other ways to start @code{debug}. ++ ++@findex debug-on-quit ++You can start @code{debug} whenever you type @kbd{C-g} ++(@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to ++@code{t}. This is useful for debugging infinite loops. ++ ++@need 1500 ++@cindex @code{(debug)} in code ++Or, you can insert a line that says @code{(debug)} into your code ++where you want the debugger to start, like this: ++ ++@smallexample ++@group ++(defun triangle-bugged (number) ++ "Return sum of numbers 1 through NUMBER inclusive." ++ (let ((total 0)) ++ (while (> number 0) ++ (setq total (+ total number)) ++ (debug) ; @r{Start debugger.} ++ (setq number (1= number))) ; @r{Error here.} ++ total)) ++@end group ++@end smallexample ++ ++The @code{debug} function is described in detail in @ref{Debugger, , ++The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}. ++ ++@node edebug, Debugging Exercises, debug-on-quit, Debugging ++@section The @code{edebug} Source Level Debugger ++@cindex Source level debugger ++@findex edebug ++ ++Edebug is a source level debugger. Edebug normally displays the ++source of the code you are debugging, with an arrow at the left that ++shows which line you are currently executing. ++ ++You can walk through the execution of a function, line by line, or run ++quickly until reaching a @dfn{breakpoint} where execution stops. ++ ++Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs ++Lisp Reference Manual}. ++ ++@need 1250 ++Here is a bugged function definition for @code{triangle-recursively}. ++@xref{Recursive triangle function, , Recursion in place of a counter}, ++for a review of it. ++ ++@smallexample ++@group ++(defun triangle-recursively-bugged (number) ++ "Return sum of numbers 1 through NUMBER inclusive. ++Uses recursion." ++ (if (= number 1) ++ 1 ++ (+ number ++ (triangle-recursively-bugged ++ (1= number))))) ; @r{Error here.} ++@end group ++@end smallexample ++ ++@noindent ++Normally, you would install this definition by positioning your cursor ++after the function's closing parenthesis and typing @kbd{C-x C-e} ++(@code{eval-last-sexp}) or else by positioning your cursor within the ++definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default, ++the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp ++Interaction mode.) ++ ++@need 1500 ++However, to prepare this function definition for Edebug, you must ++first @dfn{instrument} the code using a different command. You can do ++this by positioning your cursor within or just after the definition ++and typing ++ ++@smallexample ++M-x edebug-defun RET ++@end smallexample ++ ++@noindent ++This will cause Emacs to load Edebug automatically if it is not ++already loaded, and properly instrument the function. ++ ++After instrumenting the function, place your cursor after the ++following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}): ++ ++@smallexample ++(triangle-recursively-bugged 3) ++@end smallexample ++ ++@noindent ++You will be jumped back to the source for ++@code{triangle-recursively-bugged} and the cursor positioned at the ++beginning of the @code{if} line of the function. Also, you will see ++an arrowhead at the left hand side of that line. The arrowhead marks ++the line where the function is executing. (In the following examples, ++we show the arrowhead with @samp{=>}; in a windowing system, you may ++see the arrowhead as a solid triangle in the window `fringe'.) ++ ++@smallexample ++=>@point{}(if (= number 1) ++@end smallexample ++ ++@noindent ++@iftex ++In the example, the location of point is displayed with a star, ++@samp{@point{}} (in Info, it is displayed as @samp{-!-}). ++@end iftex ++@ifnottex ++In the example, the location of point is displayed as @samp{@point{}} ++(in a printed book, it is displayed with a five pointed star). ++@end ifnottex ++ ++If you now press @key{SPC}, point will move to the next expression to ++be executed; the line will look like this: ++ ++@smallexample ++=>(if @point{}(= number 1) ++@end smallexample ++ ++@noindent ++As you continue to press @key{SPC}, point will move from expression to ++expression. At the same time, whenever an expression returns a value, ++that value will be displayed in the echo area. For example, after you ++move point past @code{number}, you will see the following: ++ ++@smallexample ++Result: 3 (#o3, #x3, ?\C-c) ++@end smallexample ++ ++@noindent ++This means the value of @code{number} is 3, which is octal three, ++hexadecimal three, and @sc{ascii} `control-c' (the third letter of the ++alphabet, in case you need to know this information). ++ ++You can continue moving through the code until you reach the line with ++the error. Before evaluation, that line looks like this: ++ ++@smallexample ++=> @point{}(1= number))))) ; @r{Error here.} ++@end smallexample ++ ++@need 1250 ++@noindent ++When you press @key{SPC} once again, you will produce an error message ++that says: ++ ++@smallexample ++Symbol's function definition is void:@: 1= ++@end smallexample ++ ++@noindent ++This is the bug. ++ ++Press @kbd{q} to quit Edebug. ++ ++To remove instrumentation from a function definition, simply ++re-evaluate it with a command that does not instrument it. ++For example, you could place your cursor after the definition's ++closing parenthesis and type @kbd{C-x C-e}. ++ ++Edebug does a great deal more than walk with you through a function. ++You can set it so it races through on its own, stopping only at an ++error or at specified stopping points; you can cause it to display the ++changing values of various expressions; you can find out how many ++times a function is called, and more. ++ ++Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs ++Lisp Reference Manual}. ++ ++@need 1500 ++@node Debugging Exercises, , edebug, Debugging ++@section Debugging Exercises ++ ++@itemize @bullet ++@item ++Install the @code{count-words-region} function and then cause it to ++enter the built-in debugger when you call it. Run the command on a ++region containing two words. You will need to press @kbd{d} a ++remarkable number of times. On your system, is a `hook' called after ++the command finishes? (For information on hooks, see @ref{Command ++Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference ++Manual}.) ++ ++@item ++Copy @code{count-words-region} into the @file{*scratch*} buffer, ++instrument the function for Edebug, and walk through its execution. ++The function does not need to have a bug, although you can introduce ++one if you wish. If the function lacks a bug, the walk-through ++completes without problems. ++ ++@item ++While running Edebug, type @kbd{?} to see a list of all the Edebug commands. ++(The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@: ++@kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix ++for commands made outside of the Edebug debugging buffer.) ++ ++@item ++In the Edebug debugging buffer, use the @kbd{p} ++(@code{edebug-bounce-point}) command to see where in the region the ++@code{count-words-region} is working. ++ ++@item ++Move point to some spot further down the function and then type the ++@kbd{h} (@code{edebug-goto-here}) command to jump to that location. ++ ++@item ++Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to ++walk through the function on its own; use an upper case @kbd{T} for ++@code{edebug-Trace-fast-mode}. ++ ++@item ++Set a breakpoint, then run Edebug in Trace mode until it reaches the ++stopping point. ++@end itemize ++ ++@node Conclusion, the-the, Debugging, Top ++@chapter Conclusion ++ ++We have now reached the end of this Introduction. You have now ++learned enough about programming in Emacs Lisp to set values, to write ++simple @file{.emacs} files for yourself and your friends, and write ++simple customizations and extensions to Emacs. ++ ++This is a place to stop. Or, if you wish, you can now go onward, and ++teach yourself. ++ ++You have learned some of the basic nuts and bolts of programming. But ++only some. There are a great many more brackets and hinges that are ++easy to use that we have not touched. ++ ++A path you can follow right now lies among the sources to GNU Emacs ++and in ++@ifnotinfo ++@cite{The GNU Emacs Lisp Reference Manual}. ++@end ifnotinfo ++@ifinfo ++@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU ++Emacs Lisp Reference Manual}. ++@end ifinfo ++ ++The Emacs Lisp sources are an adventure. When you read the sources and ++come across a function or expression that is unfamiliar, you need to ++figure out or find out what it does. ++ ++Go to the Reference Manual. It is a thorough, complete, and fairly ++easy-to-read description of Emacs Lisp. It is written not only for ++experts, but for people who know what you know. (The @cite{Reference ++Manual} comes with the standard GNU Emacs distribution. Like this ++introduction, it comes as a Texinfo source file, so you can read it ++on-line and as a typeset, printed book.) ++ ++Go to the other on-line help that is part of GNU Emacs: the on-line ++documentation for all functions and variables, and @code{find-tags}, ++the program that takes you to sources. ++ ++Here is an example of how I explore the sources. Because of its name, ++@file{simple.el} is the file I looked at first, a long time ago. As ++it happens some of the functions in @file{simple.el} are complicated, ++or at least look complicated at first sight. The @code{open-line} ++function, for example, looks complicated. ++ ++You may want to walk through this function slowly, as we did with the ++@code{forward-sentence} function. (@xref{forward-sentence, The ++@code{forward-sentence} function}.) Or you may want to skip that ++function and look at another, such as @code{split-line}. You don't ++need to read all the functions. According to ++@code{count-words-in-defun}, the @code{split-line} function contains ++102 words and symbols. ++ ++Even though it is short, @code{split-line} contains expressions ++we have not studied: @code{skip-chars-forward}, @code{indent-to}, ++@code{current-column} and @code{insert-and-inherit}. ++ ++Consider the @code{skip-chars-forward} function. (It is part of the ++function definition for @code{back-to-indentation}, which is shown in ++@ref{Review, , Review}.) ++ ++In GNU Emacs, you can find out more about @code{skip-chars-forward} by ++typing @kbd{C-h f} (@code{describe-function}) and the name of the ++function. This gives you the function documentation. ++ ++You may be able to guess what is done by a well named function such as ++@code{indent-to}; or you can look it up, too. Incidentally, the ++@code{describe-function} function itself is in @file{help.el}; it is ++one of those long, but decipherable functions. You can look up ++@code{describe-function} using the @kbd{C-h f} command! ++ ++In this instance, since the code is Lisp, the @file{*Help*} buffer ++contains the name of the library containing the function's source. ++You can put point over the name of the library and press the RET key, ++which in this situation is bound to @code{help-follow}, and be taken ++directly to the source, in the same way as @kbd{M-.} ++(@code{find-tag}). ++ ++The definition for @code{describe-function} illustrates how to ++customize the @code{interactive} expression without using the standard ++character codes; and it shows how to create a temporary buffer. ++ ++(The @code{indent-to} function is written in C rather than Emacs Lisp; ++it is a `built-in' function. @code{help-follow} takes you to its ++source as does @code{find-tag}, when properly set up.) ++ ++You can look at a function's source using @code{find-tag}, which is ++bound to @kbd{M-.} Finally, you can find out what the Reference ++Manual has to say by visiting the manual in Info, and typing @kbd{i} ++(@code{Info-index}) and the name of the function, or by looking up the ++function in the index to a printed copy of the manual. ++ ++Similarly, you can find out what is meant by ++@code{insert-and-inherit}. ++ ++Other interesting source files include @file{paragraphs.el}, ++@file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el} ++file includes short, easily understood functions as well as longer ++ones. The @file{loaddefs.el} file contains the many standard ++autoloads and many keymaps. I have never looked at it all; only at ++parts. @file{loadup.el} is the file that loads the standard parts of ++Emacs; it tells you a great deal about how Emacs is built. ++(@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp ++Reference Manual}, for more about building.) ++ ++As I said, you have learned some nuts and bolts; however, and very ++importantly, we have hardly touched major aspects of programming; I ++have said nothing about how to sort information, except to use the ++predefined @code{sort} function; I have said nothing about how to store ++information, except to use variables and lists; I have said nothing ++about how to write programs that write programs. These are topics for ++another, and different kind of book, a different kind of learning. ++ ++What you have done is learn enough for much practical work with GNU ++Emacs. What you have done is get started. This is the end of a ++beginning. ++ ++@c ================ Appendix ================ ++ ++@node the-the, Kill Ring, Conclusion, Top ++@appendix The @code{the-the} Function ++@findex the-the ++@cindex Duplicated words function ++@cindex Words, duplicated ++ ++Sometimes when you you write text, you duplicate words---as with ``you ++you'' near the beginning of this sentence. I find that most ++frequently, I duplicate ``the''; hence, I call the function for ++detecting duplicated words, @code{the-the}. ++ ++@need 1250 ++As a first step, you could use the following regular expression to ++search for duplicates: ++ ++@smallexample ++\\(\\w+[ \t\n]+\\)\\1 ++@end smallexample ++ ++@noindent ++This regexp matches one or more word-constituent characters followed ++by one or more spaces, tabs, or newlines. However, it does not detect ++duplicated words on different lines, since the ending of the first ++word, the end of the line, is different from the ending of the second ++word, a space. (For more information about regular expressions, see ++@ref{Regexp Search, , Regular Expression Searches}, as well as ++@ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs ++Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp, ++The GNU Emacs Lisp Reference Manual}.) ++ ++You might try searching just for duplicated word-constituent ++characters but that does not work since the pattern detects doubles ++such as the two occurrences of `th' in `with the'. ++ ++Another possible regexp searches for word-constituent characters ++followed by non-word-constituent characters, reduplicated. Here, ++@w{@samp{\\w+}} matches one or more word-constituent characters and ++@w{@samp{\\W*}} matches zero or more non-word-constituent characters. ++ ++@smallexample ++\\(\\(\\w+\\)\\W*\\)\\1 ++@end smallexample ++ ++@noindent ++Again, not useful. ++ ++Here is the pattern that I use. It is not perfect, but good enough. ++@w{@samp{\\b}} matches the empty string, provided it is at the beginning ++or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of ++any characters that are @emph{not} an @@-sign, space, newline, or tab. ++ ++@smallexample ++\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b ++@end smallexample ++ ++One can write more complicated expressions, but I found that this ++expression is good enough, so I use it. ++ ++Here is the @code{the-the} function, as I include it in my ++@file{.emacs} file, along with a handy global key binding: ++ ++@smallexample ++@group ++(defun the-the () ++ "Search forward for for a duplicated word." ++ (interactive) ++ (message "Searching for for duplicated words ...") ++ (push-mark) ++@end group ++@group ++ ;; This regexp is not perfect ++ ;; but is fairly good over all: ++ (if (re-search-forward ++ "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move) ++ (message "Found duplicated word.") ++ (message "End of buffer"))) ++@end group ++ ++@group ++;; Bind `the-the' to C-c \ ++(global-set-key "\C-c\\" 'the-the) ++@end group ++@end smallexample ++ ++@sp 1 ++Here is test text: ++ ++@smallexample ++@group ++one two two three four five ++five six seven ++@end group ++@end smallexample ++ ++You can substitute the other regular expressions shown above in the ++function definition and try each of them on this list. ++ ++@node Kill Ring, Full Graph, the-the, Top ++@appendix Handling the Kill Ring ++@cindex Kill ring handling ++@cindex Handling the kill ring ++@cindex Ring, making a list like a ++ ++The kill ring is a list that is transformed into a ring by the ++workings of the @code{current-kill} function. The @code{yank} and ++@code{yank-pop} commands use the @code{current-kill} function. ++ ++This appendix describes the @code{current-kill} function as well as ++both the @code{yank} and the @code{yank-pop} commands, but first, ++consider the workings of the kill ring. ++ ++@menu ++* What the Kill Ring Does:: ++* current-kill:: ++* yank:: Paste a copy of a clipped element. ++* yank-pop:: Insert element pointed to. ++* ring file:: ++@end menu ++ ++@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring ++@ifnottex ++@unnumberedsec What the Kill Ring Does ++@end ifnottex ++ ++@need 1250 ++The kill ring has a default maximum length of sixty items; this number ++is too large for an explanation. Instead, set it to four. Please ++evaluate the following: ++ ++@smallexample ++@group ++(setq old-kill-ring-max kill-ring-max) ++(setq kill-ring-max 4) ++@end group ++@end smallexample ++ ++@noindent ++Then, please copy each line of the following indented example into the ++kill ring. You may kill each line with @kbd{C-k} or mark it and copy ++it with @kbd{M-w}. ++ ++@noindent ++(In a read-only buffer, such as the @file{*info*} buffer, the kill ++command, @kbd{C-k} (@code{kill-line}), will not remove the text, ++merely copy it to the kill ring. However, your machine may beep at ++you. Alternatively, for silence, you may copy the region of each line ++with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark ++each line for this command to succeed, but it does not matter at which ++end you put point or mark.) ++ ++@need 1250 ++@noindent ++Please invoke the calls in order, so that five elements attempt to ++fill the kill ring: ++ ++@smallexample ++@group ++first some text ++second piece of text ++third line ++fourth line of text ++fifth bit of text ++@end group ++@end smallexample ++ ++@need 1250 ++@noindent ++Then find the value of @code{kill-ring} by evaluating ++ ++@smallexample ++kill-ring ++@end smallexample ++ ++@need 800 ++@noindent ++It is: ++ ++@smallexample ++@group ++("fifth bit of text" "fourth line of text" ++"third line" "second piece of text") ++@end group ++@end smallexample ++ ++@noindent ++The first element, @samp{first some text}, was dropped. ++ ++@need 1250 ++To return to the old value for the length of the kill ring, evaluate: ++ ++@smallexample ++(setq kill-ring-max old-kill-ring-max) ++@end smallexample ++ ++@node current-kill, yank, What the Kill Ring Does, Kill Ring ++@comment node-name, next, previous, up ++@appendixsec The @code{current-kill} Function ++@findex current-kill ++ ++The @code{current-kill} function changes the element in the kill ring ++to which @code{kill-ring-yank-pointer} points. (Also, the ++@code{kill-new} function sets @code{kill-ring-yank-pointer} to point ++to the latest element of the kill ring. The @code{kill-new} ++function is used directly or indirectly by @code{kill-append}, ++@code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line}, ++and @code{kill-region}.) ++ ++@menu ++* Code for current-kill:: ++* Understanding current-kill:: ++@end menu ++ ++@node Code for current-kill, Understanding current-kill, current-kill, current-kill ++@ifnottex ++@unnumberedsubsec The code for @code{current-kill} ++@end ifnottex ++ ++ ++@need 1500 ++The @code{current-kill} function is used by @code{yank} and by ++@code{yank-pop}. Here is the code for @code{current-kill}: ++ ++@smallexample ++@group ++(defun current-kill (n &optional do-not-move) ++ "Rotate the yanking point by N places, and then return that kill. ++If N is zero, `interprogram-paste-function' is set, and calling it ++returns a string, then that string is added to the front of the ++kill ring and returned as the latest kill. ++@end group ++@group ++If optional arg DO-NOT-MOVE is non-nil, then don't actually move the ++yanking point; just return the Nth kill forward." ++ (let ((interprogram-paste (and (= n 0) ++ interprogram-paste-function ++ (funcall interprogram-paste-function)))) ++@end group ++@group ++ (if interprogram-paste ++ (progn ++ ;; Disable the interprogram cut function when we add the new ++ ;; text to the kill ring, so Emacs doesn't try to own the ++ ;; selection, with identical text. ++ (let ((interprogram-cut-function nil)) ++ (kill-new interprogram-paste)) ++ interprogram-paste) ++@end group ++@group ++ (or kill-ring (error "Kill ring is empty")) ++ (let ((ARGth-kill-element ++ (nthcdr (mod (- n (length kill-ring-yank-pointer)) ++ (length kill-ring)) ++ kill-ring))) ++ (or do-not-move ++ (setq kill-ring-yank-pointer ARGth-kill-element)) ++ (car ARGth-kill-element))))) ++@end group ++@end smallexample ++ ++Remember also that the @code{kill-new} function sets ++@code{kill-ring-yank-pointer} to the latest element of the kill ++ring, which means that all the functions that call it set the value ++indirectly: @code{kill-append}, @code{copy-region-as-kill}, ++@code{kill-ring-save}, @code{kill-line}, and @code{kill-region}. ++ ++@need 1500 ++Here is the line in @code{kill-new}, which is explained in ++@ref{kill-new function, , The @code{kill-new} function}. ++ ++@smallexample ++(setq kill-ring-yank-pointer kill-ring) ++@end smallexample ++ ++@node Understanding current-kill, , Code for current-kill, current-kill ++@ifnottex ++@unnumberedsubsec @code{current-kill} in Outline ++@end ifnottex ++ ++The @code{current-kill} function looks complex, but as usual, it can ++be understood by taking it apart piece by piece. First look at it in ++skeletal form: ++ ++@smallexample ++@group ++(defun current-kill (n &optional do-not-move) ++ "Rotate the yanking point by N places, and then return that kill." ++ (let @var{varlist} ++ @var{body}@dots{}) ++@end group ++@end smallexample ++ ++This function takes two arguments, one of which is optional. It has a ++documentation string. It is @emph{not} interactive. ++ ++@menu ++* Body of current-kill:: ++* Digression concerning error:: How to mislead humans, but not computers. ++* Determining the Element:: ++@end menu ++ ++@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill ++@ifnottex ++@unnumberedsubsubsec The Body of @code{current-kill} ++@end ifnottex ++ ++The body of the function definition is a @code{let} expression, which ++itself has a body as well as a @var{varlist}. ++ ++The @code{let} expression declares a variable that will be only usable ++within the bounds of this function. This variable is called ++@code{interprogram-paste} and is for copying to another program. It ++is not for copying within this instance of GNU Emacs. Most window ++systems provide a facility for interprogram pasting. Sadly, that ++facility usually provides only for the last element. Most windowing ++systems have not adopted a ring of many possibilities, even though ++Emacs has provided it for decades. ++ ++The @code{if} expression has two parts, one if there exists ++@code{interprogram-paste} and one if not. ++ ++@need 2000 ++Let us consider the `if not' or else-part of the @code{current-kill} ++function. (The then-part uses the @code{kill-new} function, which ++we have already described. @xref{kill-new function, , The ++@code{kill-new} function}.) ++ ++@smallexample ++@group ++(or kill-ring (error "Kill ring is empty")) ++(let ((ARGth-kill-element ++ (nthcdr (mod (- n (length kill-ring-yank-pointer)) ++ (length kill-ring)) ++ kill-ring))) ++ (or do-not-move ++ (setq kill-ring-yank-pointer ARGth-kill-element)) ++ (car ARGth-kill-element)) ++@end group ++@end smallexample ++ ++@noindent ++The code first checks whether the kill ring has content; otherwise it ++signals an error. ++ ++@need 1000 ++Note that the @code{or} expression is very similar to testing length ++with an @code{if}: ++ ++@findex zerop ++@findex error ++@smallexample ++@group ++(if (zerop (length kill-ring)) ; @r{if-part} ++ (error "Kill ring is empty")) ; @r{then-part} ++ ;; No else-part ++@end group ++@end smallexample ++ ++@noindent ++If there is not anything in the kill ring, its length must be zero and ++an error message sent to the user: @samp{Kill ring is empty}. The ++@code{current-kill} function uses an @code{or} expression which is ++simpler. But an @code{if} expression reminds us what goes on. ++ ++This @code{if} expression uses the function @code{zerop} which returns ++true if the value it is testing is zero. When @code{zerop} tests ++true, the then-part of the @code{if} is evaluated. The then-part is a ++list starting with the function @code{error}, which is a function that ++is similar to the @code{message} function ++(@pxref{message, , The @code{message} Function}) in that ++it prints a one-line message in the echo area. However, in addition ++to printing a message, @code{error} also stops evaluation of the ++function within which it is embedded. This means that the rest of the ++function will not be evaluated if the length of the kill ring is zero. ++ ++Then the @code{current-kill} function selects the element to return. ++The selection depends on the number of places that @code{current-kill} ++rotates and on where @code{kill-ring-yank-pointer} points. ++ ++Next, either the optional @code{do-not-move} argument is true or the ++current value of @code{kill-ring-yank-pointer} is set to point to the ++list. Finally, another expression returns the first element of the ++list even if the @code{do-not-move} argument is true. ++ ++@node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill ++@ifnottex ++@unnumberedsubsubsec Digression about the word `error' ++@end ifnottex ++ ++In my opinion, it is slightly misleading, at least to humans, to use ++the term `error' as the name of the @code{error} function. A better ++term would be `cancel'. Strictly speaking, of course, you cannot ++point to, much less rotate a pointer to a list that has no length, so ++from the point of view of the computer, the word `error' is correct. ++But a human expects to attempt this sort of thing, if only to find out ++whether the kill ring is full or empty. This is an act of ++exploration. ++ ++From the human point of view, the act of exploration and discovery is ++not necessarily an error, and therefore should not be labelled as one, ++even in the bowels of a computer. As it is, the code in Emacs implies ++that a human who is acting virtuously, by exploring his or her ++environment, is making an error. This is bad. Even though the computer ++takes the same steps as it does when there is an `error', a term such as ++`cancel' would have a clearer connotation. ++ ++@node Determining the Element, , Digression concerning error, Understanding current-kill ++@ifnottex ++@unnumberedsubsubsec Determining the Element ++@end ifnottex ++ ++Among other actions, the else-part of the @code{if} expression sets ++the value of @code{kill-ring-yank-pointer} to ++@code{ARGth-kill-element} when the kill ring has something in it and ++the value of @code{do-not-move} is @code{nil}. ++ ++@need 800 ++The code looks like this: ++ ++@smallexample ++@group ++(nthcdr (mod (- n (length kill-ring-yank-pointer)) ++ (length kill-ring)) ++ kill-ring))) ++@end group ++@end smallexample ++ ++This needs some examination. Unless it is not supposed to move the ++pointer, the @code{current-kill} function changes where ++@code{kill-ring-yank-pointer} points. ++That is what the ++@w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}} ++expression does. Also, clearly, @code{ARGth-kill-element} is being ++set to be equal to some @sc{cdr} of the kill ring, using the ++@code{nthcdr} function that is described in an earlier section. ++(@xref{copy-region-as-kill}.) How does it do this? ++ ++As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function ++works by repeatedly taking the @sc{cdr} of a list---it takes the ++@sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{} ++ ++@need 800 ++The two following expressions produce the same result: ++ ++@smallexample ++@group ++(setq kill-ring-yank-pointer (cdr kill-ring)) ++ ++(setq kill-ring-yank-pointer (nthcdr 1 kill-ring)) ++@end group ++@end smallexample ++ ++However, the @code{nthcdr} expression is more complicated. It uses ++the @code{mod} function to determine which @sc{cdr} to select. ++ ++(You will remember to look at inner functions first; indeed, we will ++have to go inside the @code{mod}.) ++ ++The @code{mod} function returns the value of its first argument modulo ++the second; that is to say, it returns the remainder after dividing ++the first argument by the second. The value returned has the same ++sign as the second argument. ++ ++@need 800 ++Thus, ++ ++@smallexample ++@group ++(mod 12 4) ++ @result{} 0 ;; @r{because there is no remainder} ++(mod 13 4) ++ @result{} 1 ++@end group ++@end smallexample ++ ++@need 1250 ++In this case, the first argument is often smaller than the second. ++That is fine. ++ ++@smallexample ++@group ++(mod 0 4) ++ @result{} 0 ++(mod 1 4) ++ @result{} 1 ++@end group ++@end smallexample ++ ++We can guess what the @code{-} function does. It is like @code{+} but ++subtracts instead of adds; the @code{-} function subtracts its second ++argument from its first. Also, we already know what the @code{length} ++function does (@pxref{length}). It returns the length of a list. ++ ++And @code{n} is the name of the required argument to the ++@code{current-kill} function. ++ ++@need 1250 ++So when the first argument to @code{nthcdr} is zero, the @code{nthcdr} ++expression returns the whole list, as you can see by evaluating the ++following: ++ ++@smallexample ++@group ++;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four} ++;; @r{and} (mod (- 0 4) 4) @result{} 0 ++(nthcdr (mod (- 0 4) 4) ++ '("fourth line of text" ++ "third line" ++ "second piece of text" ++ "first some text")) ++@end group ++@end smallexample ++ ++@need 1250 ++When the first argument to the @code{current-kill} function is one, ++the @code{nthcdr} expression returns the list without its first ++element. ++ ++@smallexample ++@group ++(nthcdr (mod (- 1 4) 4) ++ '("fourth line of text" ++ "third line" ++ "second piece of text" ++ "first some text")) ++@end group ++@end smallexample ++ ++@cindex @samp{global variable} defined ++@cindex @samp{variable, global}, defined ++Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer} ++are @dfn{global variables}. That means that any expression in Emacs ++Lisp can access them. They are not like the local variables set by ++@code{let} or like the symbols in an argument list. ++Local variables can only be accessed ++within the @code{let} that defines them or the function that specifies ++them in an argument list (and within expressions called by them). ++ ++@ignore ++@c texi2dvi fails when the name of the section is within ifnottex ... ++(@xref{Prevent confusion, , @code{let} Prevents Confusion}, and ++@ref{defun, , The @code{defun} Special Form}.) ++@end ignore ++ ++@node yank, yank-pop, current-kill, Kill Ring ++@comment node-name, next, previous, up ++@appendixsec @code{yank} ++@findex yank ++ ++After learning about @code{current-kill}, the code for the ++@code{yank} function is almost easy. ++ ++The @code{yank} function does not use the ++@code{kill-ring-yank-pointer} variable directly. It calls ++@code{insert-for-yank} which calls @code{current-kill} which sets the ++@code{kill-ring-yank-pointer} variable. ++ ++@need 1250 ++The code looks like this: ++ ++@c in GNU Emacs 22 ++@smallexample ++@group ++(defun yank (&optional arg) ++ "Reinsert (\"paste\") the last stretch of killed text. ++More precisely, reinsert the stretch of killed text most recently ++killed OR yanked. Put point at end, and set mark at beginning. ++With just \\[universal-argument] as argument, same but put point at ++beginning (and mark at end). With argument N, reinsert the Nth most ++recently killed stretch of killed text. ++ ++When this command inserts killed text into the buffer, it honors ++`yank-excluded-properties' and `yank-handler' as described in the ++doc string for `insert-for-yank-1', which see. ++ ++See also the command \\[yank-pop]." ++@end group ++@group ++ (interactive "*P") ++ (setq yank-window-start (window-start)) ++ ;; If we don't get all the way thru, make last-command indicate that ++ ;; for the following command. ++ (setq this-command t) ++ (push-mark (point)) ++@end group ++@group ++ (insert-for-yank (current-kill (cond ++ ((listp arg) 0) ++ ((eq arg '-) -2) ++ (t (1- arg))))) ++ (if (consp arg) ++ ;; This is like exchange-point-and-mark, ++ ;; but doesn't activate the mark. ++ ;; It is cleaner to avoid activation, even though the command ++ ;; loop would deactivate the mark because we inserted text. ++ (goto-char (prog1 (mark t) ++ (set-marker (mark-marker) (point) (current-buffer))))) ++@end group ++@group ++ ;; If we do get all the way thru, make this-command indicate that. ++ (if (eq this-command t) ++ (setq this-command 'yank)) ++ nil) ++@end group ++@end smallexample ++ ++The key expression is @code{insert-for-yank}, which inserts the string ++returned by @code{current-kill}, but removes some text properties from ++it. ++ ++However, before getting to that expression, the function sets the value ++of @code{yank-window-start} to the position returned by the ++@code{(window-start)} expression, the position at which the display ++currently starts. The @code{yank} function also sets ++@code{this-command} and pushes the mark. ++ ++After it yanks the appropriate element, if the optional argument is a ++@sc{cons} rather than a number or nothing, it puts point at beginning ++of the yanked text and mark at its end. ++ ++(The @code{prog1} function is like @code{progn} but returns the value ++of its first argument rather than the value of its last argument. Its ++first argument is forced to return the buffer's mark as an integer. ++You can see the documentation for these functions by placing point ++over them in this buffer and then typing @kbd{C-h f} ++(@code{describe-function}) followed by a @kbd{RET}; the default is the ++function.) ++ ++The last part of the function tells what to do when it succeeds. ++ ++@node yank-pop, ring file, yank, Kill Ring ++@comment node-name, next, previous, up ++@appendixsec @code{yank-pop} ++@findex yank-pop ++ ++After understanding @code{yank} and @code{current-kill}, you know how ++to approach the @code{yank-pop} function. Leaving out the ++documentation to save space, it looks like this: ++ ++@c GNU Emacs 22 ++@smallexample ++@group ++(defun yank-pop (&optional arg) ++ "@dots{}" ++ (interactive "*p") ++ (if (not (eq last-command 'yank)) ++ (error "Previous command was not a yank")) ++@end group ++@group ++ (setq this-command 'yank) ++ (unless arg (setq arg 1)) ++ (let ((inhibit-read-only t) ++ (before (< (point) (mark t)))) ++@end group ++@group ++ (if before ++ (funcall (or yank-undo-function 'delete-region) (point) (mark t)) ++ (funcall (or yank-undo-function 'delete-region) (mark t) (point))) ++ (setq yank-undo-function nil) ++@end group ++@group ++ (set-marker (mark-marker) (point) (current-buffer)) ++ (insert-for-yank (current-kill arg)) ++ ;; Set the window start back where it was in the yank command, ++ ;; if possible. ++ (set-window-start (selected-window) yank-window-start t) ++@end group ++@group ++ (if before ++ ;; This is like exchange-point-and-mark, ++ ;; but doesn't activate the mark. ++ ;; It is cleaner to avoid activation, even though the command ++ ;; loop would deactivate the mark because we inserted text. ++ (goto-char (prog1 (mark t) ++ (set-marker (mark-marker) ++ (point) ++ (current-buffer)))))) ++ nil) ++@end group ++@end smallexample ++ ++The function is interactive with a small @samp{p} so the prefix ++argument is processed and passed to the function. The command can ++only be used after a previous yank; otherwise an error message is ++sent. This check uses the variable @code{last-command} which is set ++by @code{yank} and is discussed elsewhere. ++(@xref{copy-region-as-kill}.) ++ ++The @code{let} clause sets the variable @code{before} to true or false ++depending whether point is before or after mark and then the region ++between point and mark is deleted. This is the region that was just ++inserted by the previous yank and it is this text that will be ++replaced. ++ ++@code{funcall} calls its first argument as a function, passing ++remaining arguments to it. The first argument is whatever the ++@code{or} expression returns. The two remaining arguments are the ++positions of point and mark set by the preceding @code{yank} command. ++ ++There is more, but that is the hardest part. ++ ++@node ring file, , yank-pop, Kill Ring ++@comment node-name, next, previous, up ++@appendixsec The @file{ring.el} File ++@cindex @file{ring.el} file ++ ++Interestingly, GNU Emacs posses a file called @file{ring.el} that ++provides many of the features we just discussed. But functions such ++as @code{kill-ring-yank-pointer} do not use this library, possibly ++because they were written earlier. ++ ++@node Full Graph, Free Software and Free Manuals, Kill Ring, Top ++@appendix A Graph with Labelled Axes ++ ++Printed axes help you understand a graph. They convey scale. In an ++earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we ++wrote the code to print the body of a graph. Here we write the code ++for printing and labelling vertical and horizontal axes, along with the ++body itself. ++ ++@menu ++* Labelled Example:: ++* print-graph Varlist:: @code{let} expression in @code{print-graph}. ++* print-Y-axis:: Print a label for the vertical axis. ++* print-X-axis:: Print a horizontal label. ++* Print Whole Graph:: The function to print a complete graph. ++@end menu ++ ++@node Labelled Example, print-graph Varlist, Full Graph, Full Graph ++@ifnottex ++@unnumberedsec Labelled Example Graph ++@end ifnottex ++ ++Since insertions fill a buffer to the right and below point, the new ++graph printing function should first print the Y or vertical axis, ++then the body of the graph, and finally the X or horizontal axis. ++This sequence lays out for us the contents of the function: ++ ++@enumerate ++@item ++Set up code. ++ ++@item ++Print Y axis. ++ ++@item ++Print body of graph. ++ ++@item ++Print X axis. ++@end enumerate ++ ++@need 800 ++Here is an example of how a finished graph should look: ++ ++@smallexample ++@group ++ 10 - ++ * ++ * * ++ * ** ++ * *** ++ 5 - * ******* ++ * *** ******* ++ ************* ++ *************** ++ 1 - **************** ++ | | | | ++ 1 5 10 15 ++@end group ++@end smallexample ++ ++@noindent ++In this graph, both the vertical and the horizontal axes are labelled ++with numbers. However, in some graphs, the horizontal axis is time ++and would be better labelled with months, like this: ++ ++@smallexample ++@group ++ 5 - * ++ * ** * ++ ******* ++ ********** ** ++ 1 - ************** ++ | ^ | ++ Jan June Jan ++@end group ++@end smallexample ++ ++Indeed, with a little thought, we can easily come up with a variety of ++vertical and horizontal labelling schemes. Our task could become ++complicated. But complications breed confusion. Rather than permit ++this, it is better choose a simple labelling scheme for our first ++effort, and to modify or replace it later. ++ ++@need 1200 ++These considerations suggest the following outline for the ++@code{print-graph} function: ++ ++@smallexample ++@group ++(defun print-graph (numbers-list) ++ "@var{documentation}@dots{}" ++ (let ((height @dots{} ++ @dots{})) ++@end group ++@group ++ (print-Y-axis height @dots{} ) ++ (graph-body-print numbers-list) ++ (print-X-axis @dots{} ))) ++@end group ++@end smallexample ++ ++We can work on each part of the @code{print-graph} function definition ++in turn. ++ ++@node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph ++@comment node-name, next, previous, up ++@appendixsec The @code{print-graph} Varlist ++@cindex @code{print-graph} varlist ++ ++In writing the @code{print-graph} function, the first task is to write ++the varlist in the @code{let} expression. (We will leave aside for the ++moment any thoughts about making the function interactive or about the ++contents of its documentation string.) ++ ++The varlist should set several values. Clearly, the top of the label ++for the vertical axis must be at least the height of the graph, which ++means that we must obtain this information here. Note that the ++@code{print-graph-body} function also requires this information. There ++is no reason to calculate the height of the graph in two different ++places, so we should change @code{print-graph-body} from the way we ++defined it earlier to take advantage of the calculation. ++ ++Similarly, both the function for printing the X axis labels and the ++@code{print-graph-body} function need to learn the value of the width of ++each symbol. We can perform the calculation here and change the ++definition for @code{print-graph-body} from the way we defined it in the ++previous chapter. ++ ++The length of the label for the horizontal axis must be at least as long ++as the graph. However, this information is used only in the function ++that prints the horizontal axis, so it does not need to be calculated here. ++ ++These thoughts lead us directly to the following form for the varlist ++in the @code{let} for @code{print-graph}: ++ ++@smallexample ++@group ++(let ((height (apply 'max numbers-list)) ; @r{First version.} ++ (symbol-width (length graph-blank))) ++@end group ++@end smallexample ++ ++@noindent ++As we shall see, this expression is not quite right. ++ ++@need 2000 ++@node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph ++@comment node-name, next, previous, up ++@appendixsec The @code{print-Y-axis} Function ++@cindex Axis, print vertical ++@cindex Y axis printing ++@cindex Vertical axis printing ++@cindex Print vertical axis ++ ++The job of the @code{print-Y-axis} function is to print a label for ++the vertical axis that looks like this: ++ ++@smallexample ++@group ++ 10 - ++ ++ ++ ++ ++ 5 - ++ ++ ++ ++ 1 - ++@end group ++@end smallexample ++ ++@noindent ++The function should be passed the height of the graph, and then should ++construct and insert the appropriate numbers and marks. ++ ++@menu ++* print-Y-axis in Detail:: ++* Height of label:: What height for the Y axis? ++* Compute a Remainder:: How to compute the remainder of a division. ++* Y Axis Element:: Construct a line for the Y axis. ++* Y-axis-column:: Generate a list of Y axis labels. ++* print-Y-axis Penultimate:: A not quite final version. ++@end menu ++ ++@node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis ++@ifnottex ++@unnumberedsubsec The @code{print-Y-axis} Function in Detail ++@end ifnottex ++ ++It is easy enough to see in the figure what the Y axis label should ++look like; but to say in words, and then to write a function ++definition to do the job is another matter. It is not quite true to ++say that we want a number and a tic every five lines: there are only ++three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4), ++but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8, ++and 9). It is better to say that we want a number and a tic mark on ++the base line (number 1) and then that we want a number and a tic on ++the fifth line from the bottom and on every line that is a multiple of ++five. ++ ++@node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis ++@ifnottex ++@unnumberedsubsec What height should the label be? ++@end ifnottex ++ ++The next issue is what height the label should be? Suppose the maximum ++height of tallest column of the graph is seven. Should the highest ++label on the Y axis be @samp{5 -}, and should the graph stick up above ++the label? Or should the highest label be @samp{7 -}, and mark the peak ++of the graph? Or should the highest label be @code{10 -}, which is a ++multiple of five, and be higher than the topmost value of the graph? ++ ++The latter form is preferred. Most graphs are drawn within rectangles ++whose sides are an integral number of steps long---5, 10, 15, and so ++on for a step distance of five. But as soon as we decide to use a ++step height for the vertical axis, we discover that the simple ++expression in the varlist for computing the height is wrong. The ++expression is @code{(apply 'max numbers-list)}. This returns the ++precise height, not the maximum height plus whatever is necessary to ++round up to the nearest multiple of five. A more complex expression ++is required. ++ ++As usual in cases like this, a complex problem becomes simpler if it is ++divided into several smaller problems. ++ ++First, consider the case when the highest value of the graph is an ++integral multiple of five---when it is 5, 10, 15, or some higher ++multiple of five. We can use this value as the Y axis height. ++ ++A fairly simply way to determine whether a number is a multiple of ++five is to divide it by five and see if the division results in a ++remainder. If there is no remainder, the number is a multiple of ++five. Thus, seven divided by five has a remainder of two, and seven ++is not an integral multiple of five. Put in slightly different ++language, more reminiscent of the classroom, five goes into seven ++once, with a remainder of two. However, five goes into ten twice, ++with no remainder: ten is an integral multiple of five. ++ ++@node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis ++@appendixsubsec Side Trip: Compute a Remainder ++ ++@findex % @r{(remainder function)} ++@cindex Remainder function, @code{%} ++In Lisp, the function for computing a remainder is @code{%}. The ++function returns the remainder of its first argument divided by its ++second argument. As it happens, @code{%} is a function in Emacs Lisp ++that you cannot discover using @code{apropos}: you find nothing if you ++type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to ++learn of the existence of @code{%} is to read about it in a book such ++as this or in the Emacs Lisp sources. ++ ++You can try the @code{%} function by evaluating the following two ++expressions: ++ ++@smallexample ++@group ++(% 7 5) ++ ++(% 10 5) ++@end group ++@end smallexample ++ ++@noindent ++The first expression returns 2 and the second expression returns 0. ++ ++To test whether the returned value is zero or some other number, we ++can use the @code{zerop} function. This function returns @code{t} if ++its argument, which must be a number, is zero. ++ ++@smallexample ++@group ++(zerop (% 7 5)) ++ @result{} nil ++ ++(zerop (% 10 5)) ++ @result{} t ++@end group ++@end smallexample ++ ++Thus, the following expression will return @code{t} if the height ++of the graph is evenly divisible by five: ++ ++@smallexample ++(zerop (% height 5)) ++@end smallexample ++ ++@noindent ++(The value of @code{height}, of course, can be found from @code{(apply ++'max numbers-list)}.) ++ ++On the other hand, if the value of @code{height} is not a multiple of ++five, we want to reset the value to the next higher multiple of five. ++This is straightforward arithmetic using functions with which we are ++already familiar. First, we divide the value of @code{height} by five ++to determine how many times five goes into the number. Thus, five ++goes into twelve twice. If we add one to this quotient and multiply by ++five, we will obtain the value of the next multiple of five that is ++larger than the height. Five goes into twelve twice. Add one to two, ++and multiply by five; the result is fifteen, which is the next multiple ++of five that is higher than twelve. The Lisp expression for this is: ++ ++@smallexample ++(* (1+ (/ height 5)) 5) ++@end smallexample ++ ++@noindent ++For example, if you evaluate the following, the result is 15: ++ ++@smallexample ++(* (1+ (/ 12 5)) 5) ++@end smallexample ++ ++All through this discussion, we have been using `five' as the value ++for spacing labels on the Y axis; but we may want to use some other ++value. For generality, we should replace `five' with a variable to ++which we can assign a value. The best name I can think of for this ++variable is @code{Y-axis-label-spacing}. ++ ++@need 1250 ++Using this term, and an @code{if} expression, we produce the ++following: ++ ++@smallexample ++@group ++(if (zerop (% height Y-axis-label-spacing)) ++ height ++ ;; @r{else} ++ (* (1+ (/ height Y-axis-label-spacing)) ++ Y-axis-label-spacing)) ++@end group ++@end smallexample ++ ++@noindent ++This expression returns the value of @code{height} itself if the height ++is an even multiple of the value of the @code{Y-axis-label-spacing} or ++else it computes and returns a value of @code{height} that is equal to ++the next higher multiple of the value of the @code{Y-axis-label-spacing}. ++ ++We can now include this expression in the @code{let} expression of the ++@code{print-graph} function (after first setting the value of ++@code{Y-axis-label-spacing}): ++@vindex Y-axis-label-spacing ++ ++@smallexample ++@group ++(defvar Y-axis-label-spacing 5 ++ "Number of lines from one Y axis label to next.") ++@end group ++ ++@group ++@dots{} ++(let* ((height (apply 'max numbers-list)) ++ (height-of-top-line ++ (if (zerop (% height Y-axis-label-spacing)) ++ height ++@end group ++@group ++ ;; @r{else} ++ (* (1+ (/ height Y-axis-label-spacing)) ++ Y-axis-label-spacing))) ++ (symbol-width (length graph-blank)))) ++@dots{} ++@end group ++@end smallexample ++ ++@noindent ++(Note use of the @code{let*} function: the initial value of height is ++computed once by the @code{(apply 'max numbers-list)} expression and ++then the resulting value of @code{height} is used to compute its ++final value. @xref{fwd-para let, , The @code{let*} expression}, for ++more about @code{let*}.) ++ ++@node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis ++@appendixsubsec Construct a Y Axis Element ++ ++When we print the vertical axis, we want to insert strings such as ++@w{@samp{5 -}} and @w{@samp{10 - }} every five lines. ++Moreover, we want the numbers and dashes to line up, so shorter ++numbers must be padded with leading spaces. If some of the strings ++use two digit numbers, the strings with single digit numbers must ++include a leading blank space before the number. ++ ++@findex number-to-string ++To figure out the length of the number, the @code{length} function is ++used. But the @code{length} function works only with a string, not with ++a number. So the number has to be converted from being a number to ++being a string. This is done with the @code{number-to-string} function. ++For example, ++ ++@smallexample ++@group ++(length (number-to-string 35)) ++ @result{} 2 ++ ++(length (number-to-string 100)) ++ @result{} 3 ++@end group ++@end smallexample ++ ++@noindent ++(@code{number-to-string} is also called @code{int-to-string}; you will ++see this alternative name in various sources.) ++ ++In addition, in each label, each number is followed by a string such ++as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker. ++This variable is defined with @code{defvar}: ++ ++@vindex Y-axis-tic ++@smallexample ++@group ++(defvar Y-axis-tic " - " ++ "String that follows number in a Y axis label.") ++@end group ++@end smallexample ++ ++The length of the Y label is the sum of the length of the Y axis tic ++mark and the length of the number of the top of the graph. ++ ++@smallexample ++(length (concat (number-to-string height) Y-axis-tic))) ++@end smallexample ++ ++This value will be calculated by the @code{print-graph} function in ++its varlist as @code{full-Y-label-width} and passed on. (Note that we ++did not think to include this in the varlist when we first proposed it.) ++ ++To make a complete vertical axis label, a tic mark is concatenated ++with a number; and the two together may be preceded by one or more ++spaces depending on how long the number is. The label consists of ++three parts: the (optional) leading spaces, the number, and the tic ++mark. The function is passed the value of the number for the specific ++row, and the value of the width of the top line, which is calculated ++(just once) by @code{print-graph}. ++ ++@smallexample ++@group ++(defun Y-axis-element (number full-Y-label-width) ++ "Construct a NUMBERed label element. ++A numbered element looks like this ` 5 - ', ++and is padded as needed so all line up with ++the element for the largest number." ++@end group ++@group ++ (let* ((leading-spaces ++ (- full-Y-label-width ++ (length ++ (concat (number-to-string number) ++ Y-axis-tic))))) ++@end group ++@group ++ (concat ++ (make-string leading-spaces ? ) ++ (number-to-string number) ++ Y-axis-tic))) ++@end group ++@end smallexample ++ ++The @code{Y-axis-element} function concatenates together the leading ++spaces, if any; the number, as a string; and the tic mark. ++ ++To figure out how many leading spaces the label will need, the ++function subtracts the actual length of the label---the length of the ++number plus the length of the tic mark---from the desired label width. ++ ++@findex make-string ++Blank spaces are inserted using the @code{make-string} function. This ++function takes two arguments: the first tells it how long the string ++will be and the second is a symbol for the character to insert, in a ++special format. The format is a question mark followed by a blank ++space, like this, @samp{? }. @xref{Character Type, , Character Type, ++elisp, The GNU Emacs Lisp Reference Manual}, for a description of the ++syntax for characters. (Of course, you might want to replace the ++blank space by some other character @dots{} You know what to do.) ++ ++The @code{number-to-string} function is used in the concatenation ++expression, to convert the number to a string that is concatenated ++with the leading spaces and the tic mark. ++ ++@node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis ++@appendixsubsec Create a Y Axis Column ++ ++The preceding functions provide all the tools needed to construct a ++function that generates a list of numbered and blank strings to insert ++as the label for the vertical axis: ++ ++@findex Y-axis-column ++@smallexample ++@group ++(defun Y-axis-column (height width-of-label) ++ "Construct list of Y axis labels and blank strings. ++For HEIGHT of line above base and WIDTH-OF-LABEL." ++ (let (Y-axis) ++@group ++@end group ++ (while (> height 1) ++ (if (zerop (% height Y-axis-label-spacing)) ++ ;; @r{Insert label.} ++ (setq Y-axis ++ (cons ++ (Y-axis-element height width-of-label) ++ Y-axis)) ++@group ++@end group ++ ;; @r{Else, insert blanks.} ++ (setq Y-axis ++ (cons ++ (make-string width-of-label ? ) ++ Y-axis))) ++ (setq height (1- height))) ++ ;; @r{Insert base line.} ++ (setq Y-axis ++ (cons (Y-axis-element 1 width-of-label) Y-axis)) ++ (nreverse Y-axis))) ++@end group ++@end smallexample ++ ++In this function, we start with the value of @code{height} and ++repetitively subtract one from its value. After each subtraction, we ++test to see whether the value is an integral multiple of the ++@code{Y-axis-label-spacing}. If it is, we construct a numbered label ++using the @code{Y-axis-element} function; if not, we construct a ++blank label using the @code{make-string} function. The base line ++consists of the number one followed by a tic mark. ++ ++@need 2000 ++@node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis ++@appendixsubsec The Not Quite Final Version of @code{print-Y-axis} ++ ++The list constructed by the @code{Y-axis-column} function is passed to ++the @code{print-Y-axis} function, which inserts the list as a column. ++ ++@findex print-Y-axis ++@smallexample ++@group ++(defun print-Y-axis (height full-Y-label-width) ++ "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH. ++Height must be the maximum height of the graph. ++Full width is the width of the highest label element." ++;; Value of height and full-Y-label-width ++;; are passed by `print-graph'. ++@end group ++@group ++ (let ((start (point))) ++ (insert-rectangle ++ (Y-axis-column height full-Y-label-width)) ++ ;; @r{Place point ready for inserting graph.} ++ (goto-char start) ++ ;; @r{Move point forward by value of} full-Y-label-width ++ (forward-char full-Y-label-width))) ++@end group ++@end smallexample ++ ++The @code{print-Y-axis} uses the @code{insert-rectangle} function to ++insert the Y axis labels created by the @code{Y-axis-column} function. ++In addition, it places point at the correct position for printing the body of ++the graph. ++ ++You can test @code{print-Y-axis}: ++ ++@enumerate ++@item ++Install ++ ++@smallexample ++@group ++Y-axis-label-spacing ++Y-axis-tic ++Y-axis-element ++Y-axis-column ++print-Y-axis ++@end group ++@end smallexample ++ ++@item ++Copy the following expression: ++ ++@smallexample ++(print-Y-axis 12 5) ++@end smallexample ++ ++@item ++Switch to the @file{*scratch*} buffer and place the cursor where you ++want the axis labels to start. ++ ++@item ++Type @kbd{M-:} (@code{eval-expression}). ++ ++@item ++Yank the @code{graph-body-print} expression into the minibuffer ++with @kbd{C-y} (@code{yank)}. ++ ++@item ++Press @key{RET} to evaluate the expression. ++@end enumerate ++ ++Emacs will print labels vertically, the top one being @w{@samp{10 -@w{ ++}}}. (The @code{print-graph} function will pass the value of ++@code{height-of-top-line}, which in this case will end up as 15, ++thereby getting rid of what might appear as a bug.) ++ ++@need 2000 ++@node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph ++@appendixsec The @code{print-X-axis} Function ++@cindex Axis, print horizontal ++@cindex X axis printing ++@cindex Print horizontal axis ++@cindex Horizontal axis printing ++ ++X axis labels are much like Y axis labels, except that the ticks are on a ++line above the numbers. Labels should look like this: ++ ++@smallexample ++@group ++ | | | | ++ 1 5 10 15 ++@end group ++@end smallexample ++ ++The first tic is under the first column of the graph and is preceded by ++several blank spaces. These spaces provide room in rows above for the Y ++axis labels. The second, third, fourth, and subsequent ticks are all ++spaced equally, according to the value of @code{X-axis-label-spacing}. ++ ++The second row of the X axis consists of numbers, preceded by several ++blank spaces and also separated according to the value of the variable ++@code{X-axis-label-spacing}. ++ ++The value of the variable @code{X-axis-label-spacing} should itself be ++measured in units of @code{symbol-width}, since you may want to change ++the width of the symbols that you are using to print the body of the ++graph without changing the ways the graph is labelled. ++ ++@menu ++* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. ++* X Axis Tic Marks:: Create tic marks for the horizontal axis. ++@end menu ++ ++@node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis ++@ifnottex ++@unnumberedsubsec Similarities and differences ++@end ifnottex ++ ++The @code{print-X-axis} function is constructed in more or less the ++same fashion as the @code{print-Y-axis} function except that it has ++two lines: the line of tic marks and the numbers. We will write a ++separate function to print each line and then combine them within the ++@code{print-X-axis} function. ++ ++This is a three step process: ++ ++@enumerate ++@item ++Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}. ++ ++@item ++Write a function to print the X numbers, @code{print-X-axis-numbered-line}. ++ ++@item ++Write a function to print both lines, the @code{print-X-axis} function, ++using @code{print-X-axis-tic-line} and ++@code{print-X-axis-numbered-line}. ++@end enumerate ++ ++@node X Axis Tic Marks, , Similarities differences, print-X-axis ++@appendixsubsec X Axis Tic Marks ++ ++The first function should print the X axis tic marks. We must specify ++the tic marks themselves and their spacing: ++ ++@smallexample ++@group ++(defvar X-axis-label-spacing ++ (if (boundp 'graph-blank) ++ (* 5 (length graph-blank)) 5) ++ "Number of units from one X axis label to next.") ++@end group ++@end smallexample ++ ++@noindent ++(Note that the value of @code{graph-blank} is set by another ++@code{defvar}. The @code{boundp} predicate checks whether it has ++already been set; @code{boundp} returns @code{nil} if it has not. If ++@code{graph-blank} were unbound and we did not use this conditional ++construction, in a recent GNU Emacs, we would enter the debugger and ++see an error message saying @samp{@w{Debugger entered--Lisp error:} ++@w{(void-variable graph-blank)}}.) ++ ++@need 1200 ++Here is the @code{defvar} for @code{X-axis-tic-symbol}: ++ ++@smallexample ++@group ++(defvar X-axis-tic-symbol "|" ++ "String to insert to point to a column in X axis.") ++@end group ++@end smallexample ++ ++@need 1250 ++The goal is to make a line that looks like this: ++ ++@smallexample ++ | | | | ++@end smallexample ++ ++The first tic is indented so that it is under the first column, which is ++indented to provide space for the Y axis labels. ++ ++A tic element consists of the blank spaces that stretch from one tic to ++the next plus a tic symbol. The number of blanks is determined by the ++width of the tic symbol and the @code{X-axis-label-spacing}. ++ ++@need 1250 ++The code looks like this: ++ ++@smallexample ++@group ++;;; X-axis-tic-element ++@dots{} ++(concat ++ (make-string ++ ;; @r{Make a string of blanks.} ++ (- (* symbol-width X-axis-label-spacing) ++ (length X-axis-tic-symbol)) ++ ? ) ++ ;; @r{Concatenate blanks with tic symbol.} ++ X-axis-tic-symbol) ++@dots{} ++@end group ++@end smallexample ++ ++Next, we determine how many blanks are needed to indent the first tic ++mark to the first column of the graph. This uses the value of ++@code{full-Y-label-width} passed it by the @code{print-graph} function. ++ ++@need 1250 ++The code to make @code{X-axis-leading-spaces} ++looks like this: ++ ++@smallexample ++@group ++;; X-axis-leading-spaces ++@dots{} ++(make-string full-Y-label-width ? ) ++@dots{} ++@end group ++@end smallexample ++ ++We also need to determine the length of the horizontal axis, which is ++the length of the numbers list, and the number of ticks in the horizontal ++axis: ++ ++@smallexample ++@group ++;; X-length ++@dots{} ++(length numbers-list) ++@end group ++ ++@group ++;; tic-width ++@dots{} ++(* symbol-width X-axis-label-spacing) ++@end group ++ ++@group ++;; number-of-X-ticks ++(if (zerop (% (X-length tic-width))) ++ (/ (X-length tic-width)) ++ (1+ (/ (X-length tic-width)))) ++@end group ++@end smallexample ++ ++@need 1250 ++All this leads us directly to the function for printing the X axis tic line: ++ ++@findex print-X-axis-tic-line ++@smallexample ++@group ++(defun print-X-axis-tic-line ++ (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) ++ "Print ticks for X axis." ++ (insert X-axis-leading-spaces) ++ (insert X-axis-tic-symbol) ; @r{Under first column.} ++@end group ++@group ++ ;; @r{Insert second tic in the right spot.} ++ (insert (concat ++ (make-string ++ (- (* symbol-width X-axis-label-spacing) ++ ;; @r{Insert white space up to second tic symbol.} ++ (* 2 (length X-axis-tic-symbol))) ++ ? ) ++ X-axis-tic-symbol)) ++@end group ++@group ++ ;; @r{Insert remaining ticks.} ++ (while (> number-of-X-tics 1) ++ (insert X-axis-tic-element) ++ (setq number-of-X-tics (1- number-of-X-tics)))) ++@end group ++@end smallexample ++ ++The line of numbers is equally straightforward: ++ ++@need 1250 ++First, we create a numbered element with blank spaces before each number: ++ ++@findex X-axis-element ++@smallexample ++@group ++(defun X-axis-element (number) ++ "Construct a numbered X axis element." ++ (let ((leading-spaces ++ (- (* symbol-width X-axis-label-spacing) ++ (length (number-to-string number))))) ++ (concat (make-string leading-spaces ? ) ++ (number-to-string number)))) ++@end group ++@end smallexample ++ ++Next, we create the function to print the numbered line, starting with ++the number ``1'' under the first column: ++ ++@findex print-X-axis-numbered-line ++@smallexample ++@group ++(defun print-X-axis-numbered-line ++ (number-of-X-tics X-axis-leading-spaces) ++ "Print line of X-axis numbers" ++ (let ((number X-axis-label-spacing)) ++ (insert X-axis-leading-spaces) ++ (insert "1") ++@end group ++@group ++ (insert (concat ++ (make-string ++ ;; @r{Insert white space up to next number.} ++ (- (* symbol-width X-axis-label-spacing) 2) ++ ? ) ++ (number-to-string number))) ++@end group ++@group ++ ;; @r{Insert remaining numbers.} ++ (setq number (+ number X-axis-label-spacing)) ++ (while (> number-of-X-tics 1) ++ (insert (X-axis-element number)) ++ (setq number (+ number X-axis-label-spacing)) ++ (setq number-of-X-tics (1- number-of-X-tics))))) ++@end group ++@end smallexample ++ ++Finally, we need to write the @code{print-X-axis} that uses ++@code{print-X-axis-tic-line} and ++@code{print-X-axis-numbered-line}. ++ ++The function must determine the local values of the variables used by both ++@code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and ++then it must call them. Also, it must print the carriage return that ++separates the two lines. ++ ++The function consists of a varlist that specifies five local variables, ++and calls to each of the two line printing functions: ++ ++@findex print-X-axis ++@smallexample ++@group ++(defun print-X-axis (numbers-list) ++ "Print X axis labels to length of NUMBERS-LIST." ++ (let* ((leading-spaces ++ (make-string full-Y-label-width ? )) ++@end group ++@group ++ ;; symbol-width @r{is provided by} graph-body-print ++ (tic-width (* symbol-width X-axis-label-spacing)) ++ (X-length (length numbers-list)) ++@end group ++@group ++ (X-tic ++ (concat ++ (make-string ++@end group ++@group ++ ;; @r{Make a string of blanks.} ++ (- (* symbol-width X-axis-label-spacing) ++ (length X-axis-tic-symbol)) ++ ? ) ++@end group ++@group ++ ;; @r{Concatenate blanks with tic symbol.} ++ X-axis-tic-symbol)) ++@end group ++@group ++ (tic-number ++ (if (zerop (% X-length tic-width)) ++ (/ X-length tic-width) ++ (1+ (/ X-length tic-width))))) ++@end group ++@group ++ (print-X-axis-tic-line tic-number leading-spaces X-tic) ++ (insert "\n") ++ (print-X-axis-numbered-line tic-number leading-spaces))) ++@end group ++@end smallexample ++ ++@need 1250 ++You can test @code{print-X-axis}: ++ ++@enumerate ++@item ++Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing}, ++@code{print-X-axis-tic-line}, as well as @code{X-axis-element}, ++@code{print-X-axis-numbered-line}, and @code{print-X-axis}. ++ ++@item ++Copy the following expression: ++ ++@smallexample ++@group ++(progn ++ (let ((full-Y-label-width 5) ++ (symbol-width 1)) ++ (print-X-axis ++ '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16)))) ++@end group ++@end smallexample ++ ++@item ++Switch to the @file{*scratch*} buffer and place the cursor where you ++want the axis labels to start. ++ ++@item ++Type @kbd{M-:} (@code{eval-expression}). ++ ++@item ++Yank the test expression into the minibuffer ++with @kbd{C-y} (@code{yank)}. ++ ++@item ++Press @key{RET} to evaluate the expression. ++@end enumerate ++ ++@need 1250 ++Emacs will print the horizontal axis like this: ++@sp 1 ++ ++@smallexample ++@group ++ | | | | | ++ 1 5 10 15 20 ++@end group ++@end smallexample ++ ++@node Print Whole Graph, , print-X-axis, Full Graph ++@appendixsec Printing the Whole Graph ++@cindex Printing the whole graph ++@cindex Whole graph printing ++@cindex Graph, printing all ++ ++Now we are nearly ready to print the whole graph. ++ ++The function to print the graph with the proper labels follows the ++outline we created earlier (@pxref{Full Graph, , A Graph with Labelled ++Axes}), but with additions. ++ ++@need 1250 ++Here is the outline: ++ ++@smallexample ++@group ++(defun print-graph (numbers-list) ++ "@var{documentation}@dots{}" ++ (let ((height @dots{} ++ @dots{})) ++@end group ++@group ++ (print-Y-axis height @dots{} ) ++ (graph-body-print numbers-list) ++ (print-X-axis @dots{} ))) ++@end group ++@end smallexample ++ ++@menu ++* The final version:: A few changes. ++* Test print-graph:: Run a short test. ++* Graphing words in defuns:: Executing the final code. ++* lambda:: How to write an anonymous function. ++* mapcar:: Apply a function to elements of a list. ++* Another Bug:: Yet another bug @dots{} most insidious. ++* Final printed graph:: The graph itself! ++@end menu ++ ++@node The final version, Test print-graph, Print Whole Graph, Print Whole Graph ++@ifnottex ++@unnumberedsubsec Changes for the Final Version ++@end ifnottex ++ ++The final version is different from what we planned in two ways: ++first, it contains additional values calculated once in the varlist; ++second, it carries an option to specify the labels' increment per row. ++This latter feature turns out to be essential; otherwise, a graph may ++have more rows than fit on a display or on a sheet of paper. ++ ++@need 1500 ++This new feature requires a change to the @code{Y-axis-column} ++function, to add @code{vertical-step} to it. The function looks like ++this: ++ ++@findex Y-axis-column @r{Final version.} ++@smallexample ++@group ++;;; @r{Final version.} ++(defun Y-axis-column ++ (height width-of-label &optional vertical-step) ++ "Construct list of labels for Y axis. ++HEIGHT is maximum height of graph. ++WIDTH-OF-LABEL is maximum width of label. ++VERTICAL-STEP, an option, is a positive integer ++that specifies how much a Y axis label increments ++for each line. For example, a step of 5 means ++that each line is five units of the graph." ++@end group ++@group ++ (let (Y-axis ++ (number-per-line (or vertical-step 1))) ++ (while (> height 1) ++ (if (zerop (% height Y-axis-label-spacing)) ++@end group ++@group ++ ;; @r{Insert label.} ++ (setq Y-axis ++ (cons ++ (Y-axis-element ++ (* height number-per-line) ++ width-of-label) ++ Y-axis)) ++@end group ++@group ++ ;; @r{Else, insert blanks.} ++ (setq Y-axis ++ (cons ++ (make-string width-of-label ? ) ++ Y-axis))) ++ (setq height (1- height))) ++@end group ++@group ++ ;; @r{Insert base line.} ++ (setq Y-axis (cons (Y-axis-element ++ (or vertical-step 1) ++ width-of-label) ++ Y-axis)) ++ (nreverse Y-axis))) ++@end group ++@end smallexample ++ ++The values for the maximum height of graph and the width of a symbol ++are computed by @code{print-graph} in its @code{let} expression; so ++@code{graph-body-print} must be changed to accept them. ++ ++@findex graph-body-print @r{Final version.} ++@smallexample ++@group ++;;; @r{Final version.} ++(defun graph-body-print (numbers-list height symbol-width) ++ "Print a bar graph of the NUMBERS-LIST. ++The numbers-list consists of the Y-axis values. ++HEIGHT is maximum height of graph. ++SYMBOL-WIDTH is number of each column." ++@end group ++@group ++ (let (from-position) ++ (while numbers-list ++ (setq from-position (point)) ++ (insert-rectangle ++ (column-of-graph height (car numbers-list))) ++ (goto-char from-position) ++ (forward-char symbol-width) ++@end group ++@group ++ ;; @r{Draw graph column by column.} ++ (sit-for 0) ++ (setq numbers-list (cdr numbers-list))) ++ ;; @r{Place point for X axis labels.} ++ (forward-line height) ++ (insert "\n"))) ++@end group ++@end smallexample ++ ++@need 1250 ++Finally, the code for the @code{print-graph} function: ++ ++@findex print-graph @r{Final version.} ++@smallexample ++@group ++;;; @r{Final version.} ++(defun print-graph ++ (numbers-list &optional vertical-step) ++ "Print labelled bar graph of the NUMBERS-LIST. ++The numbers-list consists of the Y-axis values. ++@end group ++ ++@group ++Optionally, VERTICAL-STEP, a positive integer, ++specifies how much a Y axis label increments for ++each line. For example, a step of 5 means that ++each row is five units." ++@end group ++@group ++ (let* ((symbol-width (length graph-blank)) ++ ;; @code{height} @r{is both the largest number} ++ ;; @r{and the number with the most digits.} ++ (height (apply 'max numbers-list)) ++@end group ++@group ++ (height-of-top-line ++ (if (zerop (% height Y-axis-label-spacing)) ++ height ++ ;; @r{else} ++ (* (1+ (/ height Y-axis-label-spacing)) ++ Y-axis-label-spacing))) ++@end group ++@group ++ (vertical-step (or vertical-step 1)) ++ (full-Y-label-width ++ (length ++@end group ++@group ++ (concat ++ (number-to-string ++ (* height-of-top-line vertical-step)) ++ Y-axis-tic)))) ++@end group ++ ++@group ++ (print-Y-axis ++ height-of-top-line full-Y-label-width vertical-step) ++@end group ++@group ++ (graph-body-print ++ numbers-list height-of-top-line symbol-width) ++ (print-X-axis numbers-list))) ++@end group ++@end smallexample ++ ++@node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph ++@appendixsubsec Testing @code{print-graph} ++ ++@need 1250 ++We can test the @code{print-graph} function with a short list of numbers: ++ ++@enumerate ++@item ++Install the final versions of @code{Y-axis-column}, ++@code{graph-body-print}, and @code{print-graph} (in addition to the ++rest of the code.) ++ ++@item ++Copy the following expression: ++ ++@smallexample ++(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1)) ++@end smallexample ++ ++@item ++Switch to the @file{*scratch*} buffer and place the cursor where you ++want the axis labels to start. ++ ++@item ++Type @kbd{M-:} (@code{eval-expression}). ++ ++@item ++Yank the test expression into the minibuffer ++with @kbd{C-y} (@code{yank)}. ++ ++@item ++Press @key{RET} to evaluate the expression. ++@end enumerate ++ ++@need 1250 ++Emacs will print a graph that looks like this: ++ ++@smallexample ++@group ++10 - ++ ++ ++ * ++ ** * ++ 5 - **** * ++ **** *** ++ * ********* ++ ************ ++ 1 - ************* ++ ++ | | | | ++ 1 5 10 15 ++@end group ++@end smallexample ++ ++@need 1200 ++On the other hand, if you pass @code{print-graph} a ++@code{vertical-step} value of 2, by evaluating this expression: ++ ++@smallexample ++(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) ++@end smallexample ++ ++@need 1250 ++@noindent ++The graph looks like this: ++ ++@smallexample ++@group ++20 - ++ ++ ++ * ++ ** * ++10 - **** * ++ **** *** ++ * ********* ++ ************ ++ 2 - ************* ++ ++ | | | | ++ 1 5 10 15 ++@end group ++@end smallexample ++ ++@noindent ++(A question: is the `2' on the bottom of the vertical axis a bug or a ++feature? If you think it is a bug, and should be a `1' instead, (or ++even a `0'), you can modify the sources.) ++ ++@node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph ++@appendixsubsec Graphing Numbers of Words and Symbols ++ ++Now for the graph for which all this code was written: a graph that ++shows how many function definitions contain fewer than 10 words and ++symbols, how many contain between 10 and 19 words and symbols, how ++many contain between 20 and 29 words and symbols, and so on. ++ ++This is a multi-step process. First make sure you have loaded all the ++requisite code. ++ ++@need 1500 ++It is a good idea to reset the value of @code{top-of-ranges} in case ++you have set it to some different value. You can evaluate the ++following: ++ ++@smallexample ++@group ++(setq top-of-ranges ++ '(10 20 30 40 50 ++ 60 70 80 90 100 ++ 110 120 130 140 150 ++ 160 170 180 190 200 ++ 210 220 230 240 250 ++ 260 270 280 290 300) ++@end group ++@end smallexample ++ ++@noindent ++Next create a list of the number of words and symbols in each range. ++ ++@need 1500 ++@noindent ++Evaluate the following: ++ ++@smallexample ++@group ++(setq list-for-graph ++ (defuns-per-range ++ (sort ++ (recursive-lengths-list-many-files ++ (directory-files "/usr/local/emacs/lisp" ++ t ".+el$")) ++ '<) ++ top-of-ranges)) ++@end group ++@end smallexample ++ ++@noindent ++On my old machine, this took about an hour. It looked though 303 Lisp ++files in my copy of Emacs version 19.23. After all that computing, ++the @code{list-for-graph} had this value: ++ ++@smallexample ++@group ++(537 1027 955 785 594 483 349 292 224 199 166 120 116 99 ++90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) ++@end group ++@end smallexample ++ ++@noindent ++This means that my copy of Emacs had 537 function definitions with ++fewer than 10 words or symbols in them, 1,027 function definitions ++with 10 to 19 words or symbols in them, 955 function definitions with ++20 to 29 words or symbols in them, and so on. ++ ++Clearly, just by looking at this list we can see that most function ++definitions contain ten to thirty words and symbols. ++ ++Now for printing. We do @emph{not} want to print a graph that is ++1,030 lines high @dots{} Instead, we should print a graph that is ++fewer than twenty-five lines high. A graph that height can be ++displayed on almost any monitor, and easily printed on a sheet of paper. ++ ++This means that each value in @code{list-for-graph} must be reduced to ++one-fiftieth its present value. ++ ++Here is a short function to do just that, using two functions we have ++not yet seen, @code{mapcar} and @code{lambda}. ++ ++@smallexample ++@group ++(defun one-fiftieth (full-range) ++ "Return list, each number one-fiftieth of previous." ++ (mapcar '(lambda (arg) (/ arg 50)) full-range)) ++@end group ++@end smallexample ++ ++@node lambda, mapcar, Graphing words in defuns, Print Whole Graph ++@appendixsubsec A @code{lambda} Expression: Useful Anonymity ++@cindex Anonymous function ++@findex lambda ++ ++@code{lambda} is the symbol for an anonymous function, a function ++without a name. Every time you use an anonymous function, you need to ++include its whole body. ++ ++@need 1250 ++@noindent ++Thus, ++ ++@smallexample ++(lambda (arg) (/ arg 50)) ++@end smallexample ++ ++@noindent ++is a function definition that says `return the value resulting from ++dividing whatever is passed to me as @code{arg} by 50'. ++ ++@need 1200 ++Earlier, for example, we had a function @code{multiply-by-seven}; it ++multiplied its argument by 7. This function is similar, except it ++divides its argument by 50; and, it has no name. The anonymous ++equivalent of @code{multiply-by-seven} is: ++ ++@smallexample ++(lambda (number) (* 7 number)) ++@end smallexample ++ ++@noindent ++(@xref{defun, , The @code{defun} Special Form}.) ++ ++@need 1250 ++@noindent ++If we want to multiply 3 by 7, we can write: ++ ++@c !!! Clear print-postscript-figures if the computer formatting this ++@c document is too small and cannot handle all the diagrams and figures. ++@c clear print-postscript-figures ++@c set print-postscript-figures ++@c lambda example diagram #1 ++@ifnottex ++@smallexample ++@group ++(multiply-by-seven 3) ++ \_______________/ ^ ++ | | ++ function argument ++@end group ++@end smallexample ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{lambda-1} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@smallexample ++@group ++(multiply-by-seven 3) ++ \_______________/ ^ ++ | | ++ function argument ++@end group ++@end smallexample ++@end iftex ++@end ifclear ++ ++@noindent ++This expression returns 21. ++ ++@need 1250 ++@noindent ++Similarly, we can write: ++ ++@c lambda example diagram #2 ++@ifnottex ++@smallexample ++@group ++((lambda (number) (* 7 number)) 3) ++ \____________________________/ ^ ++ | | ++ anonymous function argument ++@end group ++@end smallexample ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{lambda-2} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@smallexample ++@group ++((lambda (number) (* 7 number)) 3) ++ \____________________________/ ^ ++ | | ++ anonymous function argument ++@end group ++@end smallexample ++@end iftex ++@end ifclear ++ ++@need 1250 ++@noindent ++If we want to divide 100 by 50, we can write: ++ ++@c lambda example diagram #3 ++@ifnottex ++@smallexample ++@group ++((lambda (arg) (/ arg 50)) 100) ++ \______________________/ \_/ ++ | | ++ anonymous function argument ++@end group ++@end smallexample ++@end ifnottex ++@ifset print-postscript-figures ++@sp 1 ++@tex ++@center @image{lambda-3} ++%%%% old method of including an image ++% \input /usr/local/lib/tex/inputs/psfig.tex ++% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}} ++% \catcode`\@=0 % ++@end tex ++@sp 1 ++@end ifset ++@ifclear print-postscript-figures ++@iftex ++@smallexample ++@group ++((lambda (arg) (/ arg 50)) 100) ++ \______________________/ \_/ ++ | | ++ anonymous function argument ++@end group ++@end smallexample ++@end iftex ++@end ifclear ++ ++@noindent ++This expression returns 2. The 100 is passed to the function, which ++divides that number by 50. ++ ++@xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs ++Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda ++expressions derive from the Lambda Calculus. ++ ++@node mapcar, Another Bug, lambda, Print Whole Graph ++@appendixsubsec The @code{mapcar} Function ++@findex mapcar ++ ++@code{mapcar} is a function that calls its first argument with each ++element of its second argument, in turn. The second argument must be ++a sequence. ++ ++The @samp{map} part of the name comes from the mathematical phrase, ++`mapping over a domain', meaning to apply a function to each of the ++elements in a domain. The mathematical phrase is based on the ++metaphor of a surveyor walking, one step at a time, over an area he is ++mapping. And @samp{car}, of course, comes from the Lisp notion of the ++first of a list. ++ ++@need 1250 ++@noindent ++For example, ++ ++@smallexample ++@group ++(mapcar '1+ '(2 4 6)) ++ @result{} (3 5 7) ++@end group ++@end smallexample ++ ++@noindent ++The function @code{1+} which adds one to its argument, is executed on ++@emph{each} element of the list, and a new list is returned. ++ ++Contrast this with @code{apply}, which applies its first argument to ++all the remaining. ++(@xref{Readying a Graph, , Readying a Graph}, for a explanation of ++@code{apply}.) ++ ++@need 1250 ++In the definition of @code{one-fiftieth}, the first argument is the ++anonymous function: ++ ++@smallexample ++(lambda (arg) (/ arg 50)) ++@end smallexample ++ ++@noindent ++and the second argument is @code{full-range}, which will be bound to ++@code{list-for-graph}. ++ ++@need 1250 ++The whole expression looks like this: ++ ++@smallexample ++(mapcar '(lambda (arg) (/ arg 50)) full-range)) ++@end smallexample ++ ++@xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs ++Lisp Reference Manual}, for more about @code{mapcar}. ++ ++Using the @code{one-fiftieth} function, we can generate a list in ++which each element is one-fiftieth the size of the corresponding ++element in @code{list-for-graph}. ++ ++@smallexample ++@group ++(setq fiftieth-list-for-graph ++ (one-fiftieth list-for-graph)) ++@end group ++@end smallexample ++ ++@need 1250 ++The resulting list looks like this: ++ ++@smallexample ++@group ++(10 20 19 15 11 9 6 5 4 3 3 2 2 ++1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4) ++@end group ++@end smallexample ++ ++@noindent ++This, we are almost ready to print! (We also notice the loss of ++information: many of the higher ranges are 0, meaning that fewer than ++50 defuns had that many words or symbols---but not necessarily meaning ++that none had that many words or symbols.) ++ ++@node Another Bug, Final printed graph, mapcar, Print Whole Graph ++@appendixsubsec Another Bug @dots{} Most Insidious ++@cindex Bug, most insidious type ++@cindex Insidious type of bug ++ ++I said `almost ready to print'! Of course, there is a bug in the ++@code{print-graph} function @dots{} It has a @code{vertical-step} ++option, but not a @code{horizontal-step} option. The ++@code{top-of-range} scale goes from 10 to 300 by tens. But the ++@code{print-graph} function will print only by ones. ++ ++This is a classic example of what some consider the most insidious ++type of bug, the bug of omission. This is not the kind of bug you can ++find by studying the code, for it is not in the code; it is an omitted ++feature. Your best actions are to try your program early and often; ++and try to arrange, as much as you can, to write code that is easy to ++understand and easy to change. Try to be aware, whenever you can, ++that whatever you have written, @emph{will} be rewritten, if not soon, ++eventually. A hard maxim to follow. ++ ++It is the @code{print-X-axis-numbered-line} function that needs the ++work; and then the @code{print-X-axis} and the @code{print-graph} ++functions need to be adapted. Not much needs to be done; there is one ++nicety: the numbers ought to line up under the tic marks. This takes ++a little thought. ++ ++@need 1250 ++Here is the corrected @code{print-X-axis-numbered-line}: ++ ++@smallexample ++@group ++(defun print-X-axis-numbered-line ++ (number-of-X-tics X-axis-leading-spaces ++ &optional horizontal-step) ++ "Print line of X-axis numbers" ++ (let ((number X-axis-label-spacing) ++ (horizontal-step (or horizontal-step 1))) ++@end group ++@group ++ (insert X-axis-leading-spaces) ++ ;; @r{Delete extra leading spaces.} ++ (delete-char ++ (- (1- ++ (length (number-to-string horizontal-step))))) ++ (insert (concat ++ (make-string ++@end group ++@group ++ ;; @r{Insert white space.} ++ (- (* symbol-width ++ X-axis-label-spacing) ++ (1- ++ (length ++ (number-to-string horizontal-step))) ++ 2) ++ ? ) ++ (number-to-string ++ (* number horizontal-step)))) ++@end group ++@group ++ ;; @r{Insert remaining numbers.} ++ (setq number (+ number X-axis-label-spacing)) ++ (while (> number-of-X-tics 1) ++ (insert (X-axis-element ++ (* number horizontal-step))) ++ (setq number (+ number X-axis-label-spacing)) ++ (setq number-of-X-tics (1- number-of-X-tics))))) ++@end group ++@end smallexample ++ ++@need 1500 ++If you are reading this in Info, you can see the new versions of ++@code{print-X-axis} @code{print-graph} and evaluate them. If you are ++reading this in a printed book, you can see the changed lines here ++(the full text is too much to print). ++ ++@iftex ++@smallexample ++@group ++(defun print-X-axis (numbers-list horizontal-step) ++ @dots{} ++ (print-X-axis-numbered-line ++ tic-number leading-spaces horizontal-step)) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun print-graph ++ (numbers-list ++ &optional vertical-step horizontal-step) ++ @dots{} ++ (print-X-axis numbers-list horizontal-step)) ++@end group ++@end smallexample ++@end iftex ++ ++@ifnottex ++@smallexample ++@group ++(defun print-X-axis (numbers-list horizontal-step) ++ "Print X axis labels to length of NUMBERS-LIST. ++Optionally, HORIZONTAL-STEP, a positive integer, ++specifies how much an X axis label increments for ++each column." ++@end group ++@group ++;; Value of symbol-width and full-Y-label-width ++;; are passed by `print-graph'. ++ (let* ((leading-spaces ++ (make-string full-Y-label-width ? )) ++ ;; symbol-width @r{is provided by} graph-body-print ++ (tic-width (* symbol-width X-axis-label-spacing)) ++ (X-length (length numbers-list)) ++@end group ++@group ++ (X-tic ++ (concat ++ (make-string ++ ;; @r{Make a string of blanks.} ++ (- (* symbol-width X-axis-label-spacing) ++ (length X-axis-tic-symbol)) ++ ? ) ++@end group ++@group ++ ;; @r{Concatenate blanks with tic symbol.} ++ X-axis-tic-symbol)) ++ (tic-number ++ (if (zerop (% X-length tic-width)) ++ (/ X-length tic-width) ++ (1+ (/ X-length tic-width))))) ++@end group ++ ++@group ++ (print-X-axis-tic-line ++ tic-number leading-spaces X-tic) ++ (insert "\n") ++ (print-X-axis-numbered-line ++ tic-number leading-spaces horizontal-step))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun print-graph ++ (numbers-list &optional vertical-step horizontal-step) ++ "Print labelled bar graph of the NUMBERS-LIST. ++The numbers-list consists of the Y-axis values. ++@end group ++ ++@group ++Optionally, VERTICAL-STEP, a positive integer, ++specifies how much a Y axis label increments for ++each line. For example, a step of 5 means that ++each row is five units. ++@end group ++ ++@group ++Optionally, HORIZONTAL-STEP, a positive integer, ++specifies how much an X axis label increments for ++each column." ++ (let* ((symbol-width (length graph-blank)) ++ ;; @code{height} @r{is both the largest number} ++ ;; @r{and the number with the most digits.} ++ (height (apply 'max numbers-list)) ++@end group ++@group ++ (height-of-top-line ++ (if (zerop (% height Y-axis-label-spacing)) ++ height ++ ;; @r{else} ++ (* (1+ (/ height Y-axis-label-spacing)) ++ Y-axis-label-spacing))) ++@end group ++@group ++ (vertical-step (or vertical-step 1)) ++ (full-Y-label-width ++ (length ++ (concat ++ (number-to-string ++ (* height-of-top-line vertical-step)) ++ Y-axis-tic)))) ++@end group ++@group ++ (print-Y-axis ++ height-of-top-line full-Y-label-width vertical-step) ++ (graph-body-print ++ numbers-list height-of-top-line symbol-width) ++ (print-X-axis numbers-list horizontal-step))) ++@end group ++@end smallexample ++@end ifnottex ++ ++@c qqq ++@ignore ++Graphing Definitions Re-listed ++ ++@need 1250 ++Here are all the graphing definitions in their final form: ++ ++@smallexample ++@group ++(defvar top-of-ranges ++ '(10 20 30 40 50 ++ 60 70 80 90 100 ++ 110 120 130 140 150 ++ 160 170 180 190 200 ++ 210 220 230 240 250) ++ "List specifying ranges for `defuns-per-range'.") ++@end group ++ ++@group ++(defvar graph-symbol "*" ++ "String used as symbol in graph, usually an asterisk.") ++@end group ++ ++@group ++(defvar graph-blank " " ++ "String used as blank in graph, usually a blank space. ++graph-blank must be the same number of columns wide ++as graph-symbol.") ++@end group ++ ++@group ++(defvar Y-axis-tic " - " ++ "String that follows number in a Y axis label.") ++@end group ++ ++@group ++(defvar Y-axis-label-spacing 5 ++ "Number of lines from one Y axis label to next.") ++@end group ++ ++@group ++(defvar X-axis-tic-symbol "|" ++ "String to insert to point to a column in X axis.") ++@end group ++ ++@group ++(defvar X-axis-label-spacing ++ (if (boundp 'graph-blank) ++ (* 5 (length graph-blank)) 5) ++ "Number of units from one X axis label to next.") ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun count-words-in-defun () ++ "Return the number of words and symbols in a defun." ++ (beginning-of-defun) ++ (let ((count 0) ++ (end (save-excursion (end-of-defun) (point)))) ++@end group ++ ++@group ++ (while ++ (and (< (point) end) ++ (re-search-forward ++ "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" ++ end t)) ++ (setq count (1+ count))) ++ count)) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun lengths-list-file (filename) ++ "Return list of definitions' lengths within FILE. ++The returned list is a list of numbers. ++Each number is the number of words or ++symbols in one function definition." ++@end group ++ ++@group ++ (message "Working on `%s' ... " filename) ++ (save-excursion ++ (let ((buffer (find-file-noselect filename)) ++ (lengths-list)) ++ (set-buffer buffer) ++ (setq buffer-read-only t) ++ (widen) ++ (goto-char (point-min)) ++@end group ++ ++@group ++ (while (re-search-forward "^(defun" nil t) ++ (setq lengths-list ++ (cons (count-words-in-defun) lengths-list))) ++ (kill-buffer buffer) ++ lengths-list))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun lengths-list-many-files (list-of-files) ++ "Return list of lengths of defuns in LIST-OF-FILES." ++ (let (lengths-list) ++;;; @r{true-or-false-test} ++ (while list-of-files ++ (setq lengths-list ++ (append ++ lengths-list ++@end group ++@group ++;;; @r{Generate a lengths' list.} ++ (lengths-list-file ++ (expand-file-name (car list-of-files))))) ++;;; @r{Make files' list shorter.} ++ (setq list-of-files (cdr list-of-files))) ++;;; @r{Return final value of lengths' list.} ++ lengths-list)) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun defuns-per-range (sorted-lengths top-of-ranges) ++ "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." ++ (let ((top-of-range (car top-of-ranges)) ++ (number-within-range 0) ++ defuns-per-range-list) ++@end group ++ ++@group ++ ;; @r{Outer loop.} ++ (while top-of-ranges ++ ++ ;; @r{Inner loop.} ++ (while (and ++ ;; @r{Need number for numeric test.} ++ (car sorted-lengths) ++ (< (car sorted-lengths) top-of-range)) ++ ++ ;; @r{Count number of definitions within current range.} ++ (setq number-within-range (1+ number-within-range)) ++ (setq sorted-lengths (cdr sorted-lengths))) ++@end group ++ ++@group ++ ;; @r{Exit inner loop but remain within outer loop.} ++ ++ (setq defuns-per-range-list ++ (cons number-within-range defuns-per-range-list)) ++ (setq number-within-range 0) ; @r{Reset count to zero.} ++ ++ ;; @r{Move to next range.} ++ (setq top-of-ranges (cdr top-of-ranges)) ++ ;; @r{Specify next top of range value.} ++ (setq top-of-range (car top-of-ranges))) ++@end group ++ ++@group ++ ;; @r{Exit outer loop and count the number of defuns larger than} ++ ;; @r{ the largest top-of-range value.} ++ (setq defuns-per-range-list ++ (cons ++ (length sorted-lengths) ++ defuns-per-range-list)) ++ ++ ;; @r{Return a list of the number of definitions within each range,} ++ ;; @r{ smallest to largest.} ++ (nreverse defuns-per-range-list))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun column-of-graph (max-graph-height actual-height) ++ "Return list of MAX-GRAPH-HEIGHT strings; ++ACTUAL-HEIGHT are graph-symbols. ++The graph-symbols are contiguous entries at the end ++of the list. ++The list will be inserted as one column of a graph. ++The strings are either graph-blank or graph-symbol." ++@end group ++ ++@group ++ (let ((insert-list nil) ++ (number-of-top-blanks ++ (- max-graph-height actual-height))) ++ ++ ;; @r{Fill in @code{graph-symbols}.} ++ (while (> actual-height 0) ++ (setq insert-list (cons graph-symbol insert-list)) ++ (setq actual-height (1- actual-height))) ++@end group ++ ++@group ++ ;; @r{Fill in @code{graph-blanks}.} ++ (while (> number-of-top-blanks 0) ++ (setq insert-list (cons graph-blank insert-list)) ++ (setq number-of-top-blanks ++ (1- number-of-top-blanks))) ++ ++ ;; @r{Return whole list.} ++ insert-list)) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun Y-axis-element (number full-Y-label-width) ++ "Construct a NUMBERed label element. ++A numbered element looks like this ` 5 - ', ++and is padded as needed so all line up with ++the element for the largest number." ++@end group ++@group ++ (let* ((leading-spaces ++ (- full-Y-label-width ++ (length ++ (concat (number-to-string number) ++ Y-axis-tic))))) ++@end group ++@group ++ (concat ++ (make-string leading-spaces ? ) ++ (number-to-string number) ++ Y-axis-tic))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun print-Y-axis ++ (height full-Y-label-width &optional vertical-step) ++ "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH. ++Height must be the maximum height of the graph. ++Full width is the width of the highest label element. ++Optionally, print according to VERTICAL-STEP." ++@end group ++@group ++;; Value of height and full-Y-label-width ++;; are passed by `print-graph'. ++ (let ((start (point))) ++ (insert-rectangle ++ (Y-axis-column height full-Y-label-width vertical-step)) ++@end group ++@group ++ ;; @r{Place point ready for inserting graph.} ++ (goto-char start) ++ ;; @r{Move point forward by value of} full-Y-label-width ++ (forward-char full-Y-label-width))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun print-X-axis-tic-line ++ (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) ++ "Print ticks for X axis." ++ (insert X-axis-leading-spaces) ++ (insert X-axis-tic-symbol) ; @r{Under first column.} ++@end group ++@group ++ ;; @r{Insert second tic in the right spot.} ++ (insert (concat ++ (make-string ++ (- (* symbol-width X-axis-label-spacing) ++ ;; @r{Insert white space up to second tic symbol.} ++ (* 2 (length X-axis-tic-symbol))) ++ ? ) ++ X-axis-tic-symbol)) ++@end group ++@group ++ ;; @r{Insert remaining ticks.} ++ (while (> number-of-X-tics 1) ++ (insert X-axis-tic-element) ++ (setq number-of-X-tics (1- number-of-X-tics)))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun X-axis-element (number) ++ "Construct a numbered X axis element." ++ (let ((leading-spaces ++ (- (* symbol-width X-axis-label-spacing) ++ (length (number-to-string number))))) ++ (concat (make-string leading-spaces ? ) ++ (number-to-string number)))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun graph-body-print (numbers-list height symbol-width) ++ "Print a bar graph of the NUMBERS-LIST. ++The numbers-list consists of the Y-axis values. ++HEIGHT is maximum height of graph. ++SYMBOL-WIDTH is number of each column." ++@end group ++@group ++ (let (from-position) ++ (while numbers-list ++ (setq from-position (point)) ++ (insert-rectangle ++ (column-of-graph height (car numbers-list))) ++ (goto-char from-position) ++ (forward-char symbol-width) ++@end group ++@group ++ ;; @r{Draw graph column by column.} ++ (sit-for 0) ++ (setq numbers-list (cdr numbers-list))) ++ ;; @r{Place point for X axis labels.} ++ (forward-line height) ++ (insert "\n"))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun Y-axis-column ++ (height width-of-label &optional vertical-step) ++ "Construct list of labels for Y axis. ++HEIGHT is maximum height of graph. ++WIDTH-OF-LABEL is maximum width of label. ++@end group ++@group ++VERTICAL-STEP, an option, is a positive integer ++that specifies how much a Y axis label increments ++for each line. For example, a step of 5 means ++that each line is five units of the graph." ++ (let (Y-axis ++ (number-per-line (or vertical-step 1))) ++@end group ++@group ++ (while (> height 1) ++ (if (zerop (% height Y-axis-label-spacing)) ++ ;; @r{Insert label.} ++ (setq Y-axis ++ (cons ++ (Y-axis-element ++ (* height number-per-line) ++ width-of-label) ++ Y-axis)) ++@end group ++@group ++ ;; @r{Else, insert blanks.} ++ (setq Y-axis ++ (cons ++ (make-string width-of-label ? ) ++ Y-axis))) ++ (setq height (1- height))) ++@end group ++@group ++ ;; @r{Insert base line.} ++ (setq Y-axis (cons (Y-axis-element ++ (or vertical-step 1) ++ width-of-label) ++ Y-axis)) ++ (nreverse Y-axis))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun print-X-axis-numbered-line ++ (number-of-X-tics X-axis-leading-spaces ++ &optional horizontal-step) ++ "Print line of X-axis numbers" ++ (let ((number X-axis-label-spacing) ++ (horizontal-step (or horizontal-step 1))) ++@end group ++@group ++ (insert X-axis-leading-spaces) ++ ;; line up number ++ (delete-char (- (1- (length (number-to-string horizontal-step))))) ++ (insert (concat ++ (make-string ++ ;; @r{Insert white space up to next number.} ++ (- (* symbol-width X-axis-label-spacing) ++ (1- (length (number-to-string horizontal-step))) ++ 2) ++ ? ) ++ (number-to-string (* number horizontal-step)))) ++@end group ++@group ++ ;; @r{Insert remaining numbers.} ++ (setq number (+ number X-axis-label-spacing)) ++ (while (> number-of-X-tics 1) ++ (insert (X-axis-element (* number horizontal-step))) ++ (setq number (+ number X-axis-label-spacing)) ++ (setq number-of-X-tics (1- number-of-X-tics))))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun print-X-axis (numbers-list horizontal-step) ++ "Print X axis labels to length of NUMBERS-LIST. ++Optionally, HORIZONTAL-STEP, a positive integer, ++specifies how much an X axis label increments for ++each column." ++@end group ++@group ++;; Value of symbol-width and full-Y-label-width ++;; are passed by `print-graph'. ++ (let* ((leading-spaces ++ (make-string full-Y-label-width ? )) ++ ;; symbol-width @r{is provided by} graph-body-print ++ (tic-width (* symbol-width X-axis-label-spacing)) ++ (X-length (length numbers-list)) ++@end group ++@group ++ (X-tic ++ (concat ++ (make-string ++ ;; @r{Make a string of blanks.} ++ (- (* symbol-width X-axis-label-spacing) ++ (length X-axis-tic-symbol)) ++ ? ) ++@end group ++@group ++ ;; @r{Concatenate blanks with tic symbol.} ++ X-axis-tic-symbol)) ++ (tic-number ++ (if (zerop (% X-length tic-width)) ++ (/ X-length tic-width) ++ (1+ (/ X-length tic-width))))) ++@end group ++ ++@group ++ (print-X-axis-tic-line ++ tic-number leading-spaces X-tic) ++ (insert "\n") ++ (print-X-axis-numbered-line ++ tic-number leading-spaces horizontal-step))) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun one-fiftieth (full-range) ++ "Return list, each number of which is 1/50th previous." ++ (mapcar '(lambda (arg) (/ arg 50)) full-range)) ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(defun print-graph ++ (numbers-list &optional vertical-step horizontal-step) ++ "Print labelled bar graph of the NUMBERS-LIST. ++The numbers-list consists of the Y-axis values. ++@end group ++ ++@group ++Optionally, VERTICAL-STEP, a positive integer, ++specifies how much a Y axis label increments for ++each line. For example, a step of 5 means that ++each row is five units. ++@end group ++ ++@group ++Optionally, HORIZONTAL-STEP, a positive integer, ++specifies how much an X axis label increments for ++each column." ++ (let* ((symbol-width (length graph-blank)) ++ ;; @code{height} @r{is both the largest number} ++ ;; @r{and the number with the most digits.} ++ (height (apply 'max numbers-list)) ++@end group ++@group ++ (height-of-top-line ++ (if (zerop (% height Y-axis-label-spacing)) ++ height ++ ;; @r{else} ++ (* (1+ (/ height Y-axis-label-spacing)) ++ Y-axis-label-spacing))) ++@end group ++@group ++ (vertical-step (or vertical-step 1)) ++ (full-Y-label-width ++ (length ++ (concat ++ (number-to-string ++ (* height-of-top-line vertical-step)) ++ Y-axis-tic)))) ++@end group ++@group ++ ++ (print-Y-axis ++ height-of-top-line full-Y-label-width vertical-step) ++ (graph-body-print ++ numbers-list height-of-top-line symbol-width) ++ (print-X-axis numbers-list horizontal-step))) ++@end group ++@end smallexample ++@c qqq ++@end ignore ++ ++@page ++@node Final printed graph, , Another Bug, Print Whole Graph ++@appendixsubsec The Printed Graph ++ ++When made and installed, you can call the @code{print-graph} command ++like this: ++@sp 1 ++ ++@smallexample ++@group ++(print-graph fiftieth-list-for-graph 50 10) ++@end group ++@end smallexample ++@sp 1 ++ ++@noindent ++Here is the graph: ++@sp 2 ++ ++@smallexample ++@group ++1000 - * ++ ** ++ ** ++ ** ++ ** ++ 750 - *** ++ *** ++ *** ++ *** ++ **** ++ 500 - ***** ++ ****** ++ ****** ++ ****** ++ ******* ++ 250 - ******** ++ ********* * ++ *********** * ++ ************* * ++ 50 - ***************** * * ++ | | | | | | | | ++ 10 50 100 150 200 250 300 350 ++@end group ++@end smallexample ++ ++@sp 2 ++ ++@noindent ++The largest group of functions contain 10 -- 19 words and symbols each. ++ ++@node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top ++@appendix Free Software and Free Manuals ++ ++@strong{by Richard M. Stallman} ++@sp 1 ++ ++The biggest deficiency in free operating systems is not in the ++software---it is the lack of good free manuals that we can include in ++these systems. Many of our most important programs do not come with ++full manuals. Documentation is an essential part of any software ++package; when an important free software package does not come with a ++free manual, that is a major gap. We have many such gaps today. ++ ++Once upon a time, many years ago, I thought I would learn Perl. I got ++a copy of a free manual, but I found it hard to read. When I asked ++Perl users about alternatives, they told me that there were better ++introductory manuals---but those were not free. ++ ++Why was this? The authors of the good manuals had written them for ++O'Reilly Associates, which published them with restrictive terms---no ++copying, no modification, source files not available---which exclude ++them from the free software community. ++ ++That wasn't the first time this sort of thing has happened, and (to ++our community's great loss) it was far from the last. Proprietary ++manual publishers have enticed a great many authors to restrict their ++manuals since then. Many times I have heard a GNU user eagerly tell me ++about a manual that he is writing, with which he expects to help the ++GNU project---and then had my hopes dashed, as he proceeded to explain ++that he had signed a contract with a publisher that would restrict it ++so that we cannot use it. ++ ++Given that writing good English is a rare skill among programmers, we ++can ill afford to lose manuals this way. ++ ++@c (texinfo)uref ++(The Free Software Foundation ++@uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, , ++sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html, ++GNU manuals}, too.) ++ ++Free documentation, like free software, is a matter of freedom, not ++price. The problem with these manuals was not that O'Reilly Associates ++charged a price for printed copies---that in itself is fine. (The Free ++Software Foundation sells printed copies of free GNU manuals, too.) ++But GNU manuals are available in source code form, while these manuals ++are available only on paper. GNU manuals come with permission to copy ++and modify; the Perl manuals do not. These restrictions are the ++problems. ++ ++The criterion for a free manual is pretty much the same as for free ++software: it is a matter of giving all users certain ++freedoms. Redistribution (including commercial redistribution) must be ++permitted, so that the manual can accompany every copy of the program, ++on-line or on paper. Permission for modification is crucial too. ++ ++As a general rule, I don't believe that it is essential for people to ++have permission to modify all sorts of articles and books. The issues ++for writings are not necessarily the same as those for software. For ++example, I don't think you or I are obliged to give permission to ++modify articles like this one, which describe our actions and our ++views. ++ ++But there is a particular reason why the freedom to modify is crucial ++for documentation for free software. When people exercise their right ++to modify the software, and add or change its features, if they are ++conscientious they will change the manual too---so they can provide ++accurate and usable documentation with the modified program. A manual ++which forbids programmers to be conscientious and finish the job, or ++more precisely requires them to write a new manual from scratch if ++they change the program, does not fill our community's needs. ++ ++While a blanket prohibition on modification is unacceptable, some ++kinds of limits on the method of modification pose no problem. For ++example, requirements to preserve the original author's copyright ++notice, the distribution terms, or the list of authors, are ok. It is ++also no problem to require modified versions to include notice that ++they were modified, even to have entire sections that may not be ++deleted or changed, as long as these sections deal with nontechnical ++topics. (Some GNU manuals have them.) ++ ++These kinds of restrictions are not a problem because, as a practical ++matter, they don't stop the conscientious programmer from adapting the ++manual to fit the modified program. In other words, they don't block ++the free software community from making full use of the manual. ++ ++However, it must be possible to modify all the technical content of ++the manual, and then distribute the result in all the usual media, ++through all the usual channels; otherwise, the restrictions do block ++the community, the manual is not free, and so we need another manual. ++ ++Unfortunately, it is often hard to find someone to write another ++manual when a proprietary manual exists. The obstacle is that many ++users think that a proprietary manual is good enough---so they don't ++see the need to write a free manual. They do not see that the free ++operating system has a gap that needs filling. ++ ++Why do users think that proprietary manuals are good enough? Some have ++not considered the issue. I hope this article will do something to ++change that. ++ ++Other users consider proprietary manuals acceptable for the same ++reason so many people consider proprietary software acceptable: they ++judge in purely practical terms, not using freedom as a ++criterion. These people are entitled to their opinions, but since ++those opinions spring from values which do not include freedom, they ++are no guide for those of us who do value freedom. ++ ++Please spread the word about this issue. We continue to lose manuals ++to proprietary publishing. If we spread the word that proprietary ++manuals are not sufficient, perhaps the next person who wants to help ++GNU by writing documentation will realize, before it is too late, that ++he must above all make it free. ++ ++We can also encourage commercial publishers to sell free, copylefted ++manuals instead of proprietary ones. One way you can help this is to ++check the distribution terms of a manual before you buy it, and prefer ++copylefted manuals to non-copylefted ones. ++ ++@sp 2 ++@noindent ++Note: The Free Software Foundation maintains a page on its Web site ++that lists free books available from other publishers:@* ++@uref{http://www.gnu.org/doc/other-free-books.html} ++ ++@node GNU Free Documentation License, Index, Free Software and Free Manuals, Top ++@appendix GNU Free Documentation License ++ ++@cindex FDL, GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index, About the Author, GNU Free Documentation License, Top ++@comment node-name, next, previous, up ++@unnumbered Index ++ ++@ignore ++MENU ENTRY: NODE NAME. ++@end ignore ++ ++@printindex cp ++ ++@iftex ++@c Place biographical information on right-hand (verso) page ++ ++@tex ++\par\vfill\supereject ++\ifodd\pageno ++ \global\evenheadline={\hfil} \global\evenfootline={\hfil} ++ \global\oddheadline={\hfil} \global\oddfootline={\hfil} ++ %\page\hbox{}\page ++\else ++% \par\vfill\supereject ++ \global\evenheadline={\hfil} \global\evenfootline={\hfil} ++ \global\oddheadline={\hfil} \global\oddfootline={\hfil} ++ %\page\hbox{}%\page ++ %\page\hbox{}%\page ++\fi ++@end tex ++ ++@c page ++@w{ } ++ ++@c ================ Biographical information ================ ++ ++@w{ } ++@sp 8 ++@center About the Author ++@sp 1 ++@end iftex ++ ++@ifnottex ++@node About the Author, , Index, Top ++@unnumbered About the Author ++@end ifnottex ++ ++@quotation ++Robert J. Chassell has worked with GNU Emacs since 1985. He writes ++and edits, teaches Emacs and Emacs Lisp, and speaks throughout the ++world on software freedom. Chassell was a founding Director and ++Treasurer of the Free Software Foundation, Inc. He is co-author of ++the @cite{Texinfo} manual, and has edited more than a dozen other ++books. He graduated from Cambridge University, in England. He has an ++abiding interest in social and economic history and flies his own ++airplane. ++@end quotation ++ ++@c @page ++@c @w{ } ++@c ++@c @c Prevent page number on blank verso, so eject it first. ++@c @tex ++@c \par\vfill\supereject ++@c @end tex ++ ++@c @iftex ++@c @headings off ++@c @evenheading @thispage @| @| @thistitle ++@c @oddheading @| @| @thispage ++@c @end iftex ++ ++@bye ++ ++@ignore ++ arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf ++@end ignore +diff --git a/doc/lispintro/lambda-1.eps b/doc/lispintro/lambda-1.eps +new file mode 100644 +index 0000000..9b928e2 +--- /dev/null ++++ b/doc/lispintro/lambda-1.eps +@@ -0,0 +1,469 @@ ++%! ++%%BoundingBox: 33 710 173 759 ++%%Title: lambda-diagram1 ++%%CreationDate: Wed Mar 8 14:31:53 1995 ++%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++% ++% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 ++% ++ ++% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 132 dict def ++tgifdict begin ++ ++% ++% Using a zero value radius for an ellipse or an arc would result ++% in a non-invertible CTM matrix which causes problem when this ++% when this PostScript is wrapped inside other routines, such as ++% the multi.ps package from ++% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such ++% error by uncommenting the sole line of the procedure below: ++% ++/tgif_min_radius ++ { ++% dup 0.01 lt { pop 0.01 } if ++ } bind def ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarrowtipdict 8 dict def ++tgifarrowtipdict /mtrx matrix put ++ ++/tgifarrowtip ++ { tgifarrowtipdict begin ++ /dy exch def ++ /dx exch def ++ /h exch def ++ /w exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ dy dx atan rotate ++ 0 0 moveto ++ w neg h lineto ++ w neg h neg lineto ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarcdict 8 dict def ++tgifarcdict /mtrx matrix put ++ ++/tgifarcn ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarc ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arcn ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifsetuserscreendict 22 dict def ++tgifsetuserscreendict begin ++ /tempctm matrix def ++ /temprot matrix def ++ /tempscale matrix def ++ ++ /concatprocs ++ { /proc2 exch cvlit def ++ /proc1 exch cvlit def ++ /newproc proc1 length proc2 length add array def ++ newproc 0 proc1 putinterval ++ newproc proc1 length proc2 putinterval ++ newproc cvx ++ } def ++ /resmatrix matrix def ++ /findresolution ++ { 72 0 resmatrix defaultmatrix dtransform ++ /yres exch def /xres exch def ++ xres dup mul yres dup mul add sqrt ++ } def ++end ++ ++/tgifsetuserscreen ++ { tgifsetuserscreendict begin ++ /spotfunction exch def ++ /screenangle exch def ++ /cellsize exch def ++ ++ /m tempctm currentmatrix def ++ /rm screenangle temprot rotate def ++ /sm cellsize dup tempscale scale def ++ ++ sm rm m m concatmatrix m concatmatrix pop ++ ++ 1 0 m dtransform /y1 exch def /x1 exch def ++ ++ /veclength x1 dup mul y1 dup mul add sqrt def ++ /frequency findresolution veclength div def ++ ++ /newscreenangle y1 x1 atan def ++ ++ m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt ++ ++ {{neg} /spotfunction load concatprocs ++ /spotfunction exch def ++ } if ++ ++ frequency newscreenangle /spotfunction load setscreen ++ end ++ } def ++ ++/tgifsetpatterndict 18 dict def ++tgifsetpatterndict begin ++ /bitison ++ { /ybit exch def /xbit exch def ++ /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def ++ ++ /mask 1 7 xbit 8 mod sub bitshift def ++ bytevalue mask and 0 ne ++ } def ++end ++ ++/tgifbitpatternspotfunction ++ { tgifsetpatterndict begin ++ /y exch def /x exch def ++ ++ /xindex x 1 add 2 div bpside mul cvi def ++ /yindex y 1 add 2 div bpside mul cvi def ++ ++ xindex yindex bitison ++ { /onbits onbits 1 add def 1 } ++ { /offbits offbits 1 add def 0 } ++ ifelse ++ end ++ } def ++ ++/tgifsetpattern ++ { tgifsetpatterndict begin ++ /cellsz exch def ++ /angle exch def ++ /bwidth exch def ++ /bpside exch def ++ /bstring exch def ++ ++ /onbits 0 def /offbits 0 def ++ cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen ++ {} settransfer ++ offbits offbits onbits add div setgray ++ end ++ } def ++ ++/tgifxpmdict 4 dict def ++/tgifbwpicstr 1 string def ++/tgifcolorpicstr 3 string def ++ ++/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def ++ ++/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def ++ ++/tgifbwspot ++ { tgifxpmdict begin ++ /index exch def ++ tgifbwpicstr 0 ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add ++ cvi put ++ tgifbwpicstr ++ end ++ } def ++ ++/tgifcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul cvi tgifcolorpicstr 2 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 1 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 0 3 -1 roll put ++ tgifcolorpicstr ++ end ++ } def ++ ++/tgifnewcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop setrgbcolor ++ end ++ } def ++ ++/tgifcolordict 4 dict def ++ ++/colorimage where ++ { pop } ++ { /colorimage ++ { tgifcolordict begin ++ pop pop pop pop pop ++ /ih exch def ++ /iw exch def ++ /x 0 def ++ /y 0 def ++ 1 1 ih ++ { pop 1 1 iw ++ { pop currentfile ++ tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot ++ x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto ++ closepath fill ++ /x x 1 add def ++ } for ++ /y y 1 add def ++ /x 0 def ++ } for ++ end ++ } def ++ } ifelse ++ ++/tgifpatdict 10 dict def ++ ++/tgifpatbyte ++ { currentdict /retstr get exch ++ pat i cellsz mod get put ++ } def ++ ++/tgifpatproc ++ { 0 1 widthlim {tgifpatbyte} for retstr ++ /i i 1 add def ++ } def ++ ++/tgifpatfill ++ { tgifpatdict begin ++ /h exch def ++ /w exch def ++ /lty exch def ++ /ltx exch def ++ /cellsz exch def ++ /pat exch def ++ ++ /widthlim w cellsz div cvi 1 sub def ++ /retstr widthlim 1 add string def ++ /i 0 def ++ ++ ltx lty translate ++ w h true [1 0 0 1 0 0] {tgifpatproc} imagemask ++ ltx neg lty neg translate ++ end ++ } def ++ ++/pat1 def ++/pat2 <0000000000000000> def ++/pat3 <8000000008000000> def ++/pat4 <8800000022000000> def ++/pat5 <8800220088002200> def ++/pat6 <8822882288228822> def ++/pat7 def ++/pat8 <77dd77dd77dd77dd> def ++/pat9 <77ffddff77ffddff> def ++/pat10 <77ffffff77ffffff> def ++/pat11 <7fffffff7fffffff> def ++/pat12 <8040200002040800> def ++/pat13 <40a00000040a0000> def ++/pat14 def ++/pat15 def ++/pat16 def ++/pat17 <038448300c020101> def ++/pat18 <081c22c180010204> def ++/pat19 <8080413e080814e3> def ++/pat20 <8040201008040201> def ++/pat21 <8844221188442211> def ++/pat22 <77bbddee77bbddee> def ++/pat23 def ++/pat24 <7fbfdfeff7fbfdfe> def ++/pat25 <3e1f8fc7e3f1f87c> def ++/pat26 <0102040810204080> def ++/pat27 <1122448811224488> def ++/pat28 def ++/pat29 <83070e1c3870e0c1> def ++/pat30 def ++/pat31 <7cf8f1e3c78f1f3e> def ++ ++/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def ++ ++/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def ++ ++/tgifreencsmalldict 12 dict def ++/tgifReEncodeSmall ++ { tgifreencsmalldict begin ++ /newcodesandnames exch def ++ /newfontname exch def ++ /basefontname exch def ++ ++ /basefontdict basefontname findfont def ++ /newfont basefontdict maxlength dict def ++ ++ basefontdict ++ { exch dup /FID ne ++ { dup /Encoding eq ++ { exch dup length array copy newfont 3 1 roll put } ++ { exch newfont 3 1 roll put } ++ ifelse ++ } ++ { pop pop } ++ ifelse ++ } ++ forall ++ ++ newfont /FontName newfontname put ++ newcodesandnames aload pop ++ ++ newcodesandnames length 2 idiv ++ { newfont /Encoding get 3 1 roll put} ++ repeat ++ ++ newfontname newfont definefont pop ++ end ++ } def ++ ++/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def ++ ++/tgifboxdict 6 dict def ++/tgifboxstroke ++ { tgifboxdict begin ++ /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ 1.415 setmiterlimit ++ w 1 eq { w setlinewidth } if ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ w 1 eq { 1 setlinewidth } if ++ 1 setmiterlimit ++ end ++ } def ++/tgifboxfill ++ { tgifboxdict begin ++ /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ end ++ } def ++ ++end ++ ++%%PageBoundingBox: 33 710 173 759 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 setmiterlimit ++1 setlinewidth ++ ++0 setgray ++ ++72 0 mul 72 11.00 mul translate ++72 128 div 100 mul 100 div dup neg scale ++ ++gsave ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 63 75 moveto (\(multiply-by-seven 3\)) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 80 80 moveto ++ 96 96 lineto ++ 224 96 lineto ++ 240 80 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 264 119 moveto ++ -22 0 atan dup cos 8 mul 264 exch sub ++ exch sin 8 mul 97 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 264 97 8 3 0 -22 tgifarrowtip ++ closepath fill ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 160 103 moveto ++ 160 119 lineto ++ stroke ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 112 139 moveto (function) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 224 139 moveto (argument) show ++ grestore ++ ++grestore ++tgifsavedpage restore ++end ++%MatchingCreationDate: Wed Mar 8 14:31:53 1995 +diff --git a/doc/lispintro/lambda-2.eps b/doc/lispintro/lambda-2.eps +new file mode 100644 +index 0000000..1b94821 +--- /dev/null ++++ b/doc/lispintro/lambda-2.eps +@@ -0,0 +1,469 @@ ++%! ++%%BoundingBox: 33 730 240 777 ++%%Title: lambda-diagram2 ++%%CreationDate: Wed Mar 8 14:33:09 1995 ++%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++% ++% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 ++% ++ ++% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 132 dict def ++tgifdict begin ++ ++% ++% Using a zero value radius for an ellipse or an arc would result ++% in a non-invertible CTM matrix which causes problem when this ++% when this PostScript is wrapped inside other routines, such as ++% the multi.ps package from ++% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such ++% error by uncommenting the sole line of the procedure below: ++% ++/tgif_min_radius ++ { ++% dup 0.01 lt { pop 0.01 } if ++ } bind def ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarrowtipdict 8 dict def ++tgifarrowtipdict /mtrx matrix put ++ ++/tgifarrowtip ++ { tgifarrowtipdict begin ++ /dy exch def ++ /dx exch def ++ /h exch def ++ /w exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ dy dx atan rotate ++ 0 0 moveto ++ w neg h lineto ++ w neg h neg lineto ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarcdict 8 dict def ++tgifarcdict /mtrx matrix put ++ ++/tgifarcn ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarc ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arcn ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifsetuserscreendict 22 dict def ++tgifsetuserscreendict begin ++ /tempctm matrix def ++ /temprot matrix def ++ /tempscale matrix def ++ ++ /concatprocs ++ { /proc2 exch cvlit def ++ /proc1 exch cvlit def ++ /newproc proc1 length proc2 length add array def ++ newproc 0 proc1 putinterval ++ newproc proc1 length proc2 putinterval ++ newproc cvx ++ } def ++ /resmatrix matrix def ++ /findresolution ++ { 72 0 resmatrix defaultmatrix dtransform ++ /yres exch def /xres exch def ++ xres dup mul yres dup mul add sqrt ++ } def ++end ++ ++/tgifsetuserscreen ++ { tgifsetuserscreendict begin ++ /spotfunction exch def ++ /screenangle exch def ++ /cellsize exch def ++ ++ /m tempctm currentmatrix def ++ /rm screenangle temprot rotate def ++ /sm cellsize dup tempscale scale def ++ ++ sm rm m m concatmatrix m concatmatrix pop ++ ++ 1 0 m dtransform /y1 exch def /x1 exch def ++ ++ /veclength x1 dup mul y1 dup mul add sqrt def ++ /frequency findresolution veclength div def ++ ++ /newscreenangle y1 x1 atan def ++ ++ m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt ++ ++ {{neg} /spotfunction load concatprocs ++ /spotfunction exch def ++ } if ++ ++ frequency newscreenangle /spotfunction load setscreen ++ end ++ } def ++ ++/tgifsetpatterndict 18 dict def ++tgifsetpatterndict begin ++ /bitison ++ { /ybit exch def /xbit exch def ++ /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def ++ ++ /mask 1 7 xbit 8 mod sub bitshift def ++ bytevalue mask and 0 ne ++ } def ++end ++ ++/tgifbitpatternspotfunction ++ { tgifsetpatterndict begin ++ /y exch def /x exch def ++ ++ /xindex x 1 add 2 div bpside mul cvi def ++ /yindex y 1 add 2 div bpside mul cvi def ++ ++ xindex yindex bitison ++ { /onbits onbits 1 add def 1 } ++ { /offbits offbits 1 add def 0 } ++ ifelse ++ end ++ } def ++ ++/tgifsetpattern ++ { tgifsetpatterndict begin ++ /cellsz exch def ++ /angle exch def ++ /bwidth exch def ++ /bpside exch def ++ /bstring exch def ++ ++ /onbits 0 def /offbits 0 def ++ cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen ++ {} settransfer ++ offbits offbits onbits add div setgray ++ end ++ } def ++ ++/tgifxpmdict 4 dict def ++/tgifbwpicstr 1 string def ++/tgifcolorpicstr 3 string def ++ ++/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def ++ ++/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def ++ ++/tgifbwspot ++ { tgifxpmdict begin ++ /index exch def ++ tgifbwpicstr 0 ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add ++ cvi put ++ tgifbwpicstr ++ end ++ } def ++ ++/tgifcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul cvi tgifcolorpicstr 2 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 1 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 0 3 -1 roll put ++ tgifcolorpicstr ++ end ++ } def ++ ++/tgifnewcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop setrgbcolor ++ end ++ } def ++ ++/tgifcolordict 4 dict def ++ ++/colorimage where ++ { pop } ++ { /colorimage ++ { tgifcolordict begin ++ pop pop pop pop pop ++ /ih exch def ++ /iw exch def ++ /x 0 def ++ /y 0 def ++ 1 1 ih ++ { pop 1 1 iw ++ { pop currentfile ++ tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot ++ x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto ++ closepath fill ++ /x x 1 add def ++ } for ++ /y y 1 add def ++ /x 0 def ++ } for ++ end ++ } def ++ } ifelse ++ ++/tgifpatdict 10 dict def ++ ++/tgifpatbyte ++ { currentdict /retstr get exch ++ pat i cellsz mod get put ++ } def ++ ++/tgifpatproc ++ { 0 1 widthlim {tgifpatbyte} for retstr ++ /i i 1 add def ++ } def ++ ++/tgifpatfill ++ { tgifpatdict begin ++ /h exch def ++ /w exch def ++ /lty exch def ++ /ltx exch def ++ /cellsz exch def ++ /pat exch def ++ ++ /widthlim w cellsz div cvi 1 sub def ++ /retstr widthlim 1 add string def ++ /i 0 def ++ ++ ltx lty translate ++ w h true [1 0 0 1 0 0] {tgifpatproc} imagemask ++ ltx neg lty neg translate ++ end ++ } def ++ ++/pat1 def ++/pat2 <0000000000000000> def ++/pat3 <8000000008000000> def ++/pat4 <8800000022000000> def ++/pat5 <8800220088002200> def ++/pat6 <8822882288228822> def ++/pat7 def ++/pat8 <77dd77dd77dd77dd> def ++/pat9 <77ffddff77ffddff> def ++/pat10 <77ffffff77ffffff> def ++/pat11 <7fffffff7fffffff> def ++/pat12 <8040200002040800> def ++/pat13 <40a00000040a0000> def ++/pat14 def ++/pat15 def ++/pat16 def ++/pat17 <038448300c020101> def ++/pat18 <081c22c180010204> def ++/pat19 <8080413e080814e3> def ++/pat20 <8040201008040201> def ++/pat21 <8844221188442211> def ++/pat22 <77bbddee77bbddee> def ++/pat23 def ++/pat24 <7fbfdfeff7fbfdfe> def ++/pat25 <3e1f8fc7e3f1f87c> def ++/pat26 <0102040810204080> def ++/pat27 <1122448811224488> def ++/pat28 def ++/pat29 <83070e1c3870e0c1> def ++/pat30 def ++/pat31 <7cf8f1e3c78f1f3e> def ++ ++/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def ++ ++/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def ++ ++/tgifreencsmalldict 12 dict def ++/tgifReEncodeSmall ++ { tgifreencsmalldict begin ++ /newcodesandnames exch def ++ /newfontname exch def ++ /basefontname exch def ++ ++ /basefontdict basefontname findfont def ++ /newfont basefontdict maxlength dict def ++ ++ basefontdict ++ { exch dup /FID ne ++ { dup /Encoding eq ++ { exch dup length array copy newfont 3 1 roll put } ++ { exch newfont 3 1 roll put } ++ ifelse ++ } ++ { pop pop } ++ ifelse ++ } ++ forall ++ ++ newfont /FontName newfontname put ++ newcodesandnames aload pop ++ ++ newcodesandnames length 2 idiv ++ { newfont /Encoding get 3 1 roll put} ++ repeat ++ ++ newfontname newfont definefont pop ++ end ++ } def ++ ++/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def ++ ++/tgifboxdict 6 dict def ++/tgifboxstroke ++ { tgifboxdict begin ++ /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ 1.415 setmiterlimit ++ w 1 eq { w setlinewidth } if ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ w 1 eq { 1 setlinewidth } if ++ 1 setmiterlimit ++ end ++ } def ++/tgifboxfill ++ { tgifboxdict begin ++ /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ end ++ } def ++ ++end ++ ++%%PageBoundingBox: 33 730 240 777 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 setmiterlimit ++1 setlinewidth ++ ++0 setgray ++ ++72 0 mul 72 11.00 mul translate ++72 128 div 100 mul 100 div dup neg scale ++ ++gsave ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 63 43 moveto (\(\(lambda \(number\) \(* 7 number\)\) 3\)) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 80 48 moveto ++ 96 64 lineto ++ 336 64 lineto ++ 353 49 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 395 85 moveto ++ -21 0 atan dup cos 8 mul 395 exch sub ++ exch sin 8 mul 64 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 395 64 8 3 0 -21 tgifarrowtip ++ closepath fill ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 208 69 moveto ++ 208 85 lineto ++ stroke ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 112 102 moveto (anonymous function) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 344 102 moveto (argument) show ++ grestore ++ ++grestore ++tgifsavedpage restore ++end ++%MatchingCreationDate: Wed Mar 8 14:33:09 1995 +diff --git a/doc/lispintro/lambda-3.eps b/doc/lispintro/lambda-3.eps +new file mode 100644 +index 0000000..f930b0e +--- /dev/null ++++ b/doc/lispintro/lambda-3.eps +@@ -0,0 +1,469 @@ ++%! ++%%BoundingBox: 33 728 211 777 ++%%Title: lambda-diagram3 ++%%CreationDate: Wed Mar 8 14:33:49 1995 ++%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) ++% ++% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 ++% ++ ++% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++% Free Software Foundation, Inc. ++% ++% This file is part of GNU Emacs. ++% ++% GNU Emacs 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. ++% ++% GNU Emacs 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 GNU Emacs. If not, see . ++ ++/tgifdict 132 dict def ++tgifdict begin ++ ++% ++% Using a zero value radius for an ellipse or an arc would result ++% in a non-invertible CTM matrix which causes problem when this ++% when this PostScript is wrapped inside other routines, such as ++% the multi.ps package from ++% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such ++% error by uncommenting the sole line of the procedure below: ++% ++/tgif_min_radius ++ { ++% dup 0.01 lt { pop 0.01 } if ++ } bind def ++ ++/tgifellipsedict 6 dict def ++tgifellipsedict /mtrx matrix put ++ ++/tgifellipse ++ { tgifellipsedict begin ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 0 360 arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarrowtipdict 8 dict def ++tgifarrowtipdict /mtrx matrix put ++ ++/tgifarrowtip ++ { tgifarrowtipdict begin ++ /dy exch def ++ /dx exch def ++ /h exch def ++ /w exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ dy dx atan rotate ++ 0 0 moveto ++ w neg h lineto ++ w neg h neg lineto ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarcdict 8 dict def ++tgifarcdict /mtrx matrix put ++ ++/tgifarcn ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arc ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifarc ++ { tgifarcdict begin ++ /endangle exch def ++ /startangle exch def ++ /yrad exch def ++ /xrad exch def ++ /y exch def ++ /x exch def ++ /savematrix mtrx currentmatrix def ++ x y translate ++ xrad yrad scale ++ 0 0 1 startangle endangle arcn ++ savematrix setmatrix ++ end ++ } def ++ ++/tgifsetuserscreendict 22 dict def ++tgifsetuserscreendict begin ++ /tempctm matrix def ++ /temprot matrix def ++ /tempscale matrix def ++ ++ /concatprocs ++ { /proc2 exch cvlit def ++ /proc1 exch cvlit def ++ /newproc proc1 length proc2 length add array def ++ newproc 0 proc1 putinterval ++ newproc proc1 length proc2 putinterval ++ newproc cvx ++ } def ++ /resmatrix matrix def ++ /findresolution ++ { 72 0 resmatrix defaultmatrix dtransform ++ /yres exch def /xres exch def ++ xres dup mul yres dup mul add sqrt ++ } def ++end ++ ++/tgifsetuserscreen ++ { tgifsetuserscreendict begin ++ /spotfunction exch def ++ /screenangle exch def ++ /cellsize exch def ++ ++ /m tempctm currentmatrix def ++ /rm screenangle temprot rotate def ++ /sm cellsize dup tempscale scale def ++ ++ sm rm m m concatmatrix m concatmatrix pop ++ ++ 1 0 m dtransform /y1 exch def /x1 exch def ++ ++ /veclength x1 dup mul y1 dup mul add sqrt def ++ /frequency findresolution veclength div def ++ ++ /newscreenangle y1 x1 atan def ++ ++ m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt ++ ++ {{neg} /spotfunction load concatprocs ++ /spotfunction exch def ++ } if ++ ++ frequency newscreenangle /spotfunction load setscreen ++ end ++ } def ++ ++/tgifsetpatterndict 18 dict def ++tgifsetpatterndict begin ++ /bitison ++ { /ybit exch def /xbit exch def ++ /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def ++ ++ /mask 1 7 xbit 8 mod sub bitshift def ++ bytevalue mask and 0 ne ++ } def ++end ++ ++/tgifbitpatternspotfunction ++ { tgifsetpatterndict begin ++ /y exch def /x exch def ++ ++ /xindex x 1 add 2 div bpside mul cvi def ++ /yindex y 1 add 2 div bpside mul cvi def ++ ++ xindex yindex bitison ++ { /onbits onbits 1 add def 1 } ++ { /offbits offbits 1 add def 0 } ++ ifelse ++ end ++ } def ++ ++/tgifsetpattern ++ { tgifsetpatterndict begin ++ /cellsz exch def ++ /angle exch def ++ /bwidth exch def ++ /bpside exch def ++ /bstring exch def ++ ++ /onbits 0 def /offbits 0 def ++ cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen ++ {} settransfer ++ offbits offbits onbits add div setgray ++ end ++ } def ++ ++/tgifxpmdict 4 dict def ++/tgifbwpicstr 1 string def ++/tgifcolorpicstr 3 string def ++ ++/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def ++ ++/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def ++ ++/tgifbwspot ++ { tgifxpmdict begin ++ /index exch def ++ tgifbwpicstr 0 ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add ++ cvi put ++ tgifbwpicstr ++ end ++ } def ++ ++/tgifcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop ++ 255 mul cvi tgifcolorpicstr 2 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 1 3 -1 roll put ++ 255 mul cvi tgifcolorpicstr 0 3 -1 roll put ++ tgifcolorpicstr ++ end ++ } def ++ ++/tgifnewcolorspot ++ { tgifxpmdict begin ++ /index exch def ++ pixels index 3 mul 3 getinterval aload pop setrgbcolor ++ end ++ } def ++ ++/tgifcolordict 4 dict def ++ ++/colorimage where ++ { pop } ++ { /colorimage ++ { tgifcolordict begin ++ pop pop pop pop pop ++ /ih exch def ++ /iw exch def ++ /x 0 def ++ /y 0 def ++ 1 1 ih ++ { pop 1 1 iw ++ { pop currentfile ++ tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot ++ x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto ++ closepath fill ++ /x x 1 add def ++ } for ++ /y y 1 add def ++ /x 0 def ++ } for ++ end ++ } def ++ } ifelse ++ ++/tgifpatdict 10 dict def ++ ++/tgifpatbyte ++ { currentdict /retstr get exch ++ pat i cellsz mod get put ++ } def ++ ++/tgifpatproc ++ { 0 1 widthlim {tgifpatbyte} for retstr ++ /i i 1 add def ++ } def ++ ++/tgifpatfill ++ { tgifpatdict begin ++ /h exch def ++ /w exch def ++ /lty exch def ++ /ltx exch def ++ /cellsz exch def ++ /pat exch def ++ ++ /widthlim w cellsz div cvi 1 sub def ++ /retstr widthlim 1 add string def ++ /i 0 def ++ ++ ltx lty translate ++ w h true [1 0 0 1 0 0] {tgifpatproc} imagemask ++ ltx neg lty neg translate ++ end ++ } def ++ ++/pat1 def ++/pat2 <0000000000000000> def ++/pat3 <8000000008000000> def ++/pat4 <8800000022000000> def ++/pat5 <8800220088002200> def ++/pat6 <8822882288228822> def ++/pat7 def ++/pat8 <77dd77dd77dd77dd> def ++/pat9 <77ffddff77ffddff> def ++/pat10 <77ffffff77ffffff> def ++/pat11 <7fffffff7fffffff> def ++/pat12 <8040200002040800> def ++/pat13 <40a00000040a0000> def ++/pat14 def ++/pat15 def ++/pat16 def ++/pat17 <038448300c020101> def ++/pat18 <081c22c180010204> def ++/pat19 <8080413e080814e3> def ++/pat20 <8040201008040201> def ++/pat21 <8844221188442211> def ++/pat22 <77bbddee77bbddee> def ++/pat23 def ++/pat24 <7fbfdfeff7fbfdfe> def ++/pat25 <3e1f8fc7e3f1f87c> def ++/pat26 <0102040810204080> def ++/pat27 <1122448811224488> def ++/pat28 def ++/pat29 <83070e1c3870e0c1> def ++/pat30 def ++/pat31 <7cf8f1e3c78f1f3e> def ++ ++/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def ++ ++/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def ++ ++/tgifreencsmalldict 12 dict def ++/tgifReEncodeSmall ++ { tgifreencsmalldict begin ++ /newcodesandnames exch def ++ /newfontname exch def ++ /basefontname exch def ++ ++ /basefontdict basefontname findfont def ++ /newfont basefontdict maxlength dict def ++ ++ basefontdict ++ { exch dup /FID ne ++ { dup /Encoding eq ++ { exch dup length array copy newfont 3 1 roll put } ++ { exch newfont 3 1 roll put } ++ ifelse ++ } ++ { pop pop } ++ ifelse ++ } ++ forall ++ ++ newfont /FontName newfontname put ++ newcodesandnames aload pop ++ ++ newcodesandnames length 2 idiv ++ { newfont /Encoding get 3 1 roll put} ++ repeat ++ ++ newfontname newfont definefont pop ++ end ++ } def ++ ++/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def ++ ++/tgifboxdict 6 dict def ++/tgifboxstroke ++ { tgifboxdict begin ++ /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ 1.415 setmiterlimit ++ w 1 eq { w setlinewidth } if ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ w 1 eq { 1 setlinewidth } if ++ 1 setmiterlimit ++ end ++ } def ++/tgifboxfill ++ { tgifboxdict begin ++ /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def ++ pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if ++ newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath ++ pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse ++ pat pat1 ne pat pat2 ne and { grestore } if ++ end ++ } def ++ ++end ++ ++%%PageBoundingBox: 33 728 211 777 ++tgifdict begin ++/tgifsavedpage save def ++ ++1 setmiterlimit ++1 setlinewidth ++ ++0 setgray ++ ++72 0 mul 72 11.00 mul translate ++72 128 div 100 mul 100 div dup neg scale ++ ++gsave ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 63 43 moveto (\(\(lambda \(arg\) \(/ arg 50\)\) 100\)) show ++ grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 80 48 moveto ++ 96 64 lineto ++ 284 64 lineto ++ 299 48 lineto ++ stroke ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 354 86 moveto ++ -25 0 atan dup cos 8 mul 354 exch sub ++ exch sin 8 mul 61 exch sub lineto ++ stroke ++grestore ++gsave ++ newpath ++ 354 61 8 3 0 -25 tgifarrowtip ++ closepath fill ++grestore ++ ++% POLY/OPEN-SPLINE ++gsave ++ newpath ++ 199 70 moveto ++ 199 86 lineto ++ stroke ++grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 101 106 moveto (anonymous function) show ++ grestore ++ ++% TEXT ++0 setgray ++/Courier findfont [17 0 0 -17 0 0] makefont setfont ++ gsave ++ 293 106 moveto (argument) show ++ grestore ++ ++grestore ++tgifsavedpage restore ++end ++%MatchingCreationDate: Wed Mar 8 14:33:49 1995 +diff --git a/doc/lispintro/makefile.w32-in b/doc/lispintro/makefile.w32-in +new file mode 100644 +index 0000000..951f133 +--- /dev/null ++++ b/doc/lispintro/makefile.w32-in +@@ -0,0 +1,74 @@ ++#### -*- Makefile -*- for the Emacs Lisp Introduction manual. ++ ++# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++# Free Software Foundation, Inc. ++ ++# This file is part of GNU Emacs. ++ ++# GNU Emacs 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. ++ ++# GNU Emacs 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 GNU Emacs. If not, see . ++ ++ ++srcdir = . ++ ++infodir = $(srcdir)/../../info ++ ++INFO_SOURCES = $(srcdir)/emacs-lisp-intro.texi ++# The file name eintr must fit within 5 characters, to allow for ++# -NN extensions to fit into DOS 8+3 limits without clashing ++INFO_TARGETS = $(infodir)/eintr ++DVI_TARGETS = emacs-lisp-intro.dvi ++ ++MAKEINFO = makeinfo ++INSTALL_INFO = install-info ++TEXI2DVI = texi2dvi ++DVIPS = dvips ++ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ ++ "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C ++ ++.SUFFIXES: .dvi .ps .texi ++ ++info: $(INFO_TARGETS) ++ ++$(infodir)/dir: ++ $(INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) ++ ++dvi: $(DVI_TARGETS) ++ ++$(infodir)/eintr: $(INFO_SOURCES) ++ $(MAKEINFO) -o $@ $(srcdir)/emacs-lisp-intro.texi ++ ++emacs-lisp-intro.dvi: $(INFO_SOURCES) ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-lisp-intro.texi ++ ++emacs-lisp-intro.html: $(INFO_SOURCES) ++ $(MAKEINFO) --html -o $@ $(srcdir)/emacs-lisp-intro.texi ++ ++.dvi.ps: ++ $(DVIPS) $< -o $@ ++ ++mostlyclean: ++ - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr *.tp ++ ++clean: mostlyclean ++ - $(DEL) *.dvi $(infodir)/eintr* ++ ++distclean: clean ++ - $(DEL) makefile ++ ++maintainer-clean: distclean ++ - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc ++ ++# 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/doc/lispref/ChangeLog b/doc/lispref/ChangeLog +new file mode 100644 +index 0000000..cee4597 +--- /dev/null ++++ b/doc/lispref/ChangeLog +@@ -0,0 +1,8156 @@ ++2009-07-29 Chong Yidong ++ ++ * Version 23.1 released. ++ ++2009-07-18 Chong Yidong ++ ++ * processes.texi (Shell Arguments): Copyedits. ++ ++2009-07-18 Glenn Morris ++ ++ * loading.texi (Repeated Loading): Fix typo. ++ ++2009-07-15 Glenn Morris ++ ++ * edebug.texi: Minor re-phrasings throughout. ++ (Edebug Execution Modes): Sit-for affects continue mode too. ++ (Jumping): Use `forward-sexp' rather than its keybinding. ++ (Edebug Misc): Fix Q binding. ++ (Edebug Eval): Remove cl version. ++ (Printing in Edebug): Clarify print-length etc. ++ (Instrumenting Macro Calls): Defopt edebug-eval-macro-args. ++ (Specification List): Remove edebug-unwrap findex entry. ++ (Specification Examples): defmacro is actually not the same as defun. ++ Escape "`" in example. ++ ++2009-07-11 Kevin Ryde ++ ++ * hooks.texi (Standard Hooks): Fix cross-references. ++ ++ * loading.texi (Named Features): Refer to eval-after-load. ++ ++2009-07-11 Glenn Morris ++ ++ * searching.texi (Regexp Backslash): Fix typo. ++ ++ * elisp.texi (Top): Display copyright notice at start of non-TeX. ++ ++2009-07-10 Glenn Morris ++ ++ * elisp.texi, vol1.texi, vol2.texi: Update @detailmenu. ++ ++ * customize.texi (Customization Types): ++ * display.texi (Abstract Display): ++ * objects.texi (Character Type, String Type): ++ Merge in some menu descriptions from elisp.texi. ++ ++ * files.texi (Format Conversion): ++ * hash.texi (Hash Tables): ++ * minibuf.texi (Completion): ++ * modes.texi (Multiline Font Lock): ++ * os.texi (System Interface): ++ End menu description with period. ++ ++2009-07-09 Glenn Morris ++ ++ * back.texi: Don't hard-code texinfo location. ++ ++ * two-volume.make (texinfodir): New, with location of texinfo.tex. ++ (tex): Add texinfodir to TEXINPUTS. ++ (elisp1med-init, elisp2med-init): Use texinfodir. ++ ++ * Makefile.in (texinfodir): Rename from usermanualdir, and update. ++ (clean): Add two-volume.make intermediate files. ++ ++ * elisp.texi, vol1.texi, vol2.texi: ++ Use a DATE variable with the publication date, and update it. ++ Fix antinews menu description. ++ ++ * vol1.texi, vol2.texi: Update VERSION to match elisp.texi. ++ Update the detailed node listing to match elisp.texi. ++ ++ * README: Update edition to match elisp.texi. ++ ++ * objects.texi (General Escape Syntax): ++ * nonascii.texi (Character Sets): ++ Use consistent case for "Unicode Standard". ++ ++ * anti.texi (Antinews): ++ * customize.texi (Variable Definitions): ++ * functions.texi (Declaring Functions): ++ * nonascii.texi (Character Properties): ++ * processes.texi (Serial Ports): ++ * text.texi (Special Properties): ++ * tips.texi (Coding Conventions): ++ Minor rearrangements to improve TeX line-filling. ++ ++ * commands.texi (Using Interactive): Fix cross-reference. ++ ++2009-07-01 Andreas Schwab ++ ++ * help.texi (Help Functions): Fix description of help-buffer and ++ help-setup-xref to use @defun instead of @deffn. ++ ++2009-06-24 Chong Yidong ++ ++ * display.texi (Window Systems): Add ns to the list. ++ ++2009-06-17 Martin Rudalics ++ ++ * windows.texi (Dedicated Windows): Fix typo. ++ (Resizing Windows): Replace @defun by @deffn. ++ ++2009-06-17 Glenn Morris ++ ++ * variables.texi (Directory Local Variables): ++ Update for 2009-04-11 name-change of dir-locals-directory-alist. ++ ++2009-06-09 Kenichi Handa ++ ++ * nonascii.texi (Character Sets): State clearly that FROM and TO ++ are codepoints of CHARSET. ++ ++2009-06-07 Chong Yidong ++ ++ * minibuf.texi (Reading File Names): Fix introductory text. ++ Suggested by stan@derbycityprints.com. ++ (High-Level Completion): Fix typo. ++ ++2009-05-28 Chong Yidong ++ ++ * frames.texi (Text Terminal Colors): Multi-tty is already ++ implemented, but tty-local colors are not. ++ ++2009-05-27 Chong Yidong ++ ++ * hooks.texi (Standard Hooks): Remove mention of obsolete ++ redisplay-end-trigger-functions. ++ ++ * internals.texi (Window Internals): Remove mention of obsolete ++ redisplay-end-trigger-functions. ++ ++2009-05-21 Martin Rudalics ++ ++ * abbrevs.texi (Abbrev Mode): abbrev-mode is an option. ++ ++ * backups.texi (Making Backups): backup-directory-alist and ++ make-backup-file-name-function are options. ++ (Auto-Saving): auto-save-list-file-prefix is an option. ++ ++ * buffers.texi (Killing Buffers): buffer-offer-save is an ++ option. ++ ++ * display.texi (Refresh Screen): no-redraw-on-reenter is an ++ option. ++ (Echo Area Customization): echo-keystrokes is an option. ++ (Selective Display): selective-display-ellipses is an option. ++ (Temporary Displays): temp-buffer-show-function is an option. ++ (Face Attributes): underline-minimum-offset and x-bitmap-file-path ++ are options. ++ (Font Selection): face-font-family-alternatives, ++ face-font-selection-order, face-font-registry-alternatives, and ++ scalable-fonts-allowed are options. ++ (Fringe Indicators): indicate-buffer-boundaries is an option. ++ (Fringe Cursors): overflow-newline-into-fringe is an option. ++ (Scroll Bars): scroll-bar-mode is an option. ++ ++ * eval.texi (Eval): max-lisp-eval-depth is an option. ++ ++ * files.texi (Visiting Functions): find-file-hook is an option. ++ (Directory Names): directory-abbrev-alist is an option. ++ (Unique File Names): temporary-file-directory and ++ small-temporary-file-directory are options. ++ ++ * frames.texi (Initial Parameters): initial-frame-alist, ++ minibuffer-frame-alist and default-frame-alist are options. ++ (Cursor Parameters): blink-cursor-alist and ++ cursor-in-non-selected-windows ar options. ++ (Window System Selections): selection-coding-system is an ++ option. ++ (Display Feature Testing): display-mm-dimensions-alist is an ++ option. ++ ++ * help.texi (Help Functions): help-char and help-event-list are ++ options. ++ ++ * keymaps.texi (Functions for Key Lookup): meta-prefix-char is ++ an option. ++ ++ * minibuf.texi (Minibuffer History): history-length and ++ history-delete-duplicates are options. ++ (High-Level Completion): read-buffer-function and ++ read-buffer-completion-ignore-case are options. ++ (Reading File Names): read-file-name-completion-ignore-case is ++ an option. ++ ++ * modes.texi (Mode Line Top): mode-line-format is an option. ++ (Mode Line Variables): mode-line-position and mode-line-modes ++ are options. ++ ++ * nonascii.texi (Text Representations): ++ enable-multibyte-characters is an option. ++ (Default Coding Systems): auto-coding-regexp-alist, ++ file-coding-system-alist, auto-coding-alist and ++ auto-coding-functions are options. ++ (Specifying Coding Systems): inhibit-eol-conversion is an ++ option. ++ ++ * os.texi (Init File): site-run-file is an option. ++ (System Environment): mail-host-address is an option. ++ (User Identification): user-mail-address is an option. ++ (Terminal Output): baud-rate is an option. ++ ++ * positions.texi (Word Motion): words-include-escapes is an ++ option. ++ ++ * searching.texi (Standard Regexps): page-delimiter, ++ paragraph-separate, paragraph-separate and sentence-end are ++ options. ++ ++ * text.texi (Margins): left-margin and fill-nobreak-predicate ++ are options. ++ ++ * variables.texi (Local Variables): max-specpdl-size is an ++ option. ++ ++ * windows.texi (Choosing Window): ++ split-window-preferred-function, special-display-function and ++ display-buffer-function are options. ++ ++2009-05-20 Chong Yidong ++ ++ Fix errors spotted by Martin Rudalics. ++ ++ * syntax.texi (Position Parse): Document rationale for ignored ++ arguments to syntax-ppss-flush-cache. ++ ++ * processes.texi (Input to Processes): Mark PROCESS arg to ++ process-running-child-p as optional. ++ (Network Options): Document NO-ERROR arg to ++ set-network-process-option. ++ ++ * buffers.texi (Indirect Buffers): Mark clone-indirect-buffer as a ++ command. ++ ++ * searching.texi (POSIX Regexps): Mark posix-search-forward and ++ posix-search-backward as commands. ++ ++ * os.texi (Killing Emacs): Mark kill-emacs as a command. ++ (Suspending Emacs): Mark suspend-emacs as a command. ++ (Processor Run Time): Mark emacs-uptime and emacs-init-time as ++ commands. ++ (Terminal Output): Remove obsolete function baud-rate. Document ++ TERMINAL arg for send-string-to-terminal. ++ ++ * nonascii.texi (Terminal I/O Encoding): Document TERMINAL arg for ++ terminal-coding-system and set-terminal-coding-system. ++ (Explicit Encoding): Mark DESTINATION arg of decode-coding-region ++ as optional. ++ (Character Sets): Document RESTRICTION arg of char-charset. ++ (Character Codes): Mark POS argument to get-byte as optional. ++ ++ * minibuf.texi (Minibuffer Misc): Document ARGS arg for ++ minibuffer-message. ++ ++ * files.texi (Create/Delete Dirs): Mark make-directory and ++ delete-directory as commands. ++ ++ * abbrevs.texi (Abbrev Tables): Fix arglist for make-abbrev-table. ++ ++ * text.texi (Base 64): Mark base64-decode-string and ++ base64-encode-string as commands. ++ (Columns): Mark move-to-column as a command. ++ (Mode-Specific Indent): Document RIGID arg to ++ indent-for-tab-command. ++ (Region Indent): Mark TO-COLUMN arg to indent-region as optional. ++ Mark indent-code-rigidly as a command. ++ (Substitution): Mark translate-region as a command. ++ ++ * frames.texi (Size and Position): Remove obsolete functions ++ screen-height and screen-width. ++ ++2009-05-19 Chong Yidong ++ ++ * windows.texi (Cyclic Window Ordering, Cyclic Window Ordering) ++ (Displaying Buffers, Resizing Windows): Correct mistakes; ++ next-window, previous-window, and pop-to-buffer are not commands, ++ and fit-window-to-buffer" is a command. (Pointed out by Martin ++ Rudalics.) ++ ++2009-05-17 Richard M Stallman ++ ++ * modes.texi (Precalculated Fontification): Clarify text. ++ ++2009-05-17 Martin Rudalics ++ ++ * windows.texi (Selecting Windows): Clarify descriptions of ++ with-selected-window and get-lru-window. ++ (Cyclic Window Ordering): Refer to particular frame when talking ++ about how splitting affects the ordering. ++ (Displaying Buffers): Fix descriptions of switch-to-buffer and ++ switch-to-buffer-other-window. Explain how setting of ++ display-buffer-reuse-frames affects pop-to-buffer. ++ (Choosing Window): Clarify some details in descriptions of ++ display-buffer-reuse-frames, pop-up-frames, and ++ pop-up-frame-function. ++ (Dedicated Windows): Clarify some details. ++ (Textual Scrolling): Replace term vscroll by term vertical ++ scroll position. ++ (Vertical Scrolling): Fix typo. ++ (Window Hooks): Relate text on jit-lock-register to window ++ scrolling and size changes. ++ ++2009-05-14 Chong Yidong ++ ++ * frames.texi (Initial Parameters): Clarify what the initial ++ minibuffer frame is. ++ (Buffer Parameters): Note that the minibuffer parameter can not be ++ altered. ++ ++ * anti.texi (Antinews): Copyedits. Rearrange some entries. ++ Document display-buffer changes. ++ ++2009-05-13 Chong Yidong ++ ++ * anti.texi (Antinews): Rewrite for Emacs 22. ++ ++ * abbrevs.texi (Abbrevs): Add xref to Creating Symbols when ++ obarrays are first mentioned. Define "system abbrev" more ++ prominently, and add it to the index. ++ (Abbrev Mode, Abbrev Tables, Defining Abbrevs, Abbrev Properties): ++ Copyedits. ++ (Abbrev Expansion): Document abbrev-insert. ++ ++2009-05-12 Chong Yidong ++ ++ * frames.texi (Font and Color Parameters): Rename from Color ++ Parameters. Document font-backend parameter. ++ ++ * vol2.texi (Top): Update node listing. ++ * vol1.texi (Top): Update node listing. ++ * elisp.texi (Top): Update node listing. ++ ++2009-05-11 Martin Rudalics ++ ++ * windows.texi (Choosing Window): Don't explicitly refer to ++ split-window-sensibly's window argument in descriptions of ++ split-height-threshold and split-width-threshold. ++ ++2009-05-10 Martin Rudalics ++ ++ * windows.texi (Choosing Window): Fix rewrite of window ++ splitting section. ++ ++2009-05-09 Eli Zaretskii ++ ++ * nonascii.texi (Default Coding Systems): Document ++ find-auto-coding, set-auto-coding, and auto-coding-alist. Add ++ indexing. ++ (Lisp and Coding Systems): Add index entries. ++ ++2009-05-09 Martin Rudalics ++ ++ * windows.texi (Choosing Window): Describe split-window-sensibly ++ and rewrite section on window splitting accordingly. ++ (Textual Scrolling): Replace `...' by @code{...}. ++ ++2009-05-04 Chong Yidong ++ ++ * hooks.texi (Standard Hooks): Add abbrev-expand-functions. ++ Remove obsoleted pre-abbrev-expand-hook. ++ ++ * locals.texi (Standard Buffer-Local Variables): Consolidate table ++ entries. ++ ++ * internals.texi (Object Internals): Don't assume 32-bit machines ++ are the norm. ++ (Buffer Internals): Consolidate table entries for readability. ++ (Window Internals): Synch field names to window.h. ++ (Process Internals): Synch field names to process.h. ++ ++2009-04-29 Chong Yidong ++ ++ * variables.texi (File Local Variables): Note that read-circle is ++ bound to nil when reading file-local variables. ++ ++ * streams.texi (Input Functions): Document read-circle. ++ (Output Variables): Add xref to Circular Objects. ++ ++2009-04-25 Chong Yidong ++ ++ * tips.texi (Coding Conventions): Copyedits. Add xref to Named ++ Features and Coding System Basics. Node that "p" stands for ++ "predicate". Recommend utf-8-emacs instead of emacs-mule. ++ (Key Binding Conventions): Emacs does use S-down-mouse-1, for ++ mouse-appearance-menu. ++ (Programming Tips): Add xref to Progress. ++ ++2009-04-22 Chong Yidong ++ ++ * os.texi (Command-Line Arguments): Document ++ command-line-args-left. ++ (Suspending Emacs): Adapt text to multi-tty case. Document use of ++ terminal objects for tty arguments. ++ (Startup Summary): Add xref to Session Management. ++ (Session Management): Mention emacs-session-restore. Copyedits. ++ ++2009-04-20 Chong Yidong ++ ++ * os.texi (Startup Summary): Copyedits. The init file is not ++ necessarily named .emacs now. Document initial-buffer-choice and ++ initial-scratch-message. Note where Emacs exits in batch mode. ++ Document inhibit-splash-screen as an alias. ++ (Init File): Be neutral about which init file name to use. ++ ++2009-04-16 Chong Yidong ++ ++ * os.texi (System Interface): Fix Texinfo usage. ++ ++2009-04-15 Chong Yidong ++ ++ * searching.texi (Regexp Backslash): Also refer to shy groups as ++ non-capturing or unnumbered groups. ++ (Regexp Functions): Add cross-reference to Regexp Backslash. ++ ++ * display.texi (Truncation): Overlays can use line-prefix and ++ wrap-prefix too. ++ (Overlay Properties): Document wrap-prefix and line-prefix. ++ (Face Attributes): Document underline-minimum-offset. ++ (Face Remapping): Copyedits. ++ (Low-Level Font): Copyedits. ++ (Image Cache): Note that the image cache is shared between frames. ++ (Line Height): Emphasize that line-spacing only takes effect on ++ graphical terminals. ++ ++2009-04-13 Chong Yidong ++ ++ * display.texi (Refresh Screen): Note that a passage about screen ++ refreshing is text terminal only. ++ (Forcing Redisplay): Delete misleading comment---sit-for calls ++ redisplay, not the other way around. ++ (Truncation): Note new values of truncate-partial-width-windows. ++ Copyedits. ++ (Invisible Text): Document invisible-p. ++ ++2009-04-11 Eli Zaretskii ++ ++ * display.texi (Overlays): Overlays don't scale well. See ++ http://lists.gnu.org/archive/html/emacs-devel/2009-04/msg00243.html. ++ ++2009-04-10 Chong Yidong ++ ++ * syntax.texi (Syntax Table Functions): Document cons cell ++ argument for modify-syntax-entry. ++ (Categories): Document cons cell argument for ++ modify-category-entry. ++ ++ * searching.texi (String Search): Document word-search-forward-lax ++ and word-search-backward-lax. ++ (Searching and Case): Describe isearch behavior more precisely. ++ ++ * keymaps.texi (Tool Bar): Mention that some platforms do not ++ support multi-line toolbars. Suggested by Stephen Eglen. ++ ++ * frames.texi (Layout Parameters): Mention that Nextstep also ++ allows only one tool-bar line. Suggested by Stephen Eglen. ++ ++ * nonascii.texi (Text Representations): Copyedits. ++ (Coding System Basics): Also mention utf-8-emacs. ++ (Converting Representations, Selecting a Representation) ++ (Scanning Charsets, Translation of Characters, Encoding and I/O): ++ Copyedits. ++ (Character Codes): Mention role of codepoints 1114112 to 4194175. ++ ++2009-04-09 Chong Yidong ++ ++ * text.texi (Yank Commands): Note that yank uses push-mark. ++ (Filling): Clarify REGION argument of fill-paragraph. Document ++ fill-forward-paragraph-function. ++ (Special Properties): Remove "new in Emacs 22" declaration. ++ (Clickable Text): Merge with Links and Mouse-1 node. ++ ++ * display.texi (Button Properties, Button Buffer Commands): Change ++ xref to Clickable Text. ++ ++ * tips.texi (Key Binding Conventions): Change xref to Clickable ++ Text. ++ ++ * elisp.texi (Top): Update node listing. ++ ++2009-04-05 Chong Yidong ++ ++ * markers.texi (The Mark): Copyedits. Improve description of ++ handle-shift-selection. ++ (The Region): Move use-region-p here from The Mark. ++ ++ * positions.texi (Screen Lines): Document (cols . lines) argument ++ for vertical-motion. ++ ++2009-04-04 Chong Yidong ++ ++ * frames.texi (Frames): Clean up introduction. Document `ns' ++ return value for framep. ++ (Creating Frames): Note how the terminal is chosen. ++ (Multiple Terminals, Multiple Displays): Merge into a single node. ++ (Color Parameters): Fix typo. ++ ++ * variables.texi (Local Variables, Buffer-Local Variables) ++ (Creating Buffer-Local): Change link to Multiple Terminals. ++ ++ * os.texi (X11 Keysyms): Change link to Multiple Terminals. ++ ++ * keymaps.texi (Controlling Active Maps): Change link to Multiple ++ Terminals. ++ ++ * commands.texi (Command Loop Info, Keyboard Macros): Change link ++ to Multiple Terminals. ++ ++ * elisp.texi (Top): Update node listing. ++ * vol2.texi (Top): Update node listing. ++ * vol1.texi (Top): Update node listing. ++ ++ * buffers.texi (Current Buffer): Note that the append-to-buffer ++ example is no longer in synch with the latest code. Tie the two ++ examples together. ++ ++ * files.texi (File Attributes): Move note about MS-DOS from ++ Changing Files to File Attributes. ++ (Create/Delete Dirs): Note that mkdir is an alias for this. ++ ++2009-04-01 Markus Triska ++ ++ * processes.texi (Filter Functions): Suggest how to handle output ++ batches. ++ ++2009-03-30 Chong Yidong ++ ++ * help.texi (Accessing Documentation): Update example to use ++ help-setup-xref and with-help-window. ++ (Help Functions): Remove print-help-return-message, which is ++ semi-obsolete due to with-help-window. Document help-buffer and ++ help-setup-xref. ++ ++2009-03-29 Chong Yidong ++ ++ * help.texi (Accessing Documentation, Help Functions): Remove ++ information about long-obsolete Emacs versions. ++ ++ * modes.texi (Mode Line Variables): The default values of the mode ++ line variables are now more complicated. ++ ++2009-03-28 Chong Yidong ++ ++ * modes.texi (Major Mode Conventions): Note that specialness is ++ inherited. ++ (Derived Modes): Note that define-derive-mode sets the mode-class ++ property. ++ ++ * keymaps.texi (Prefix Keys): The M-g prefix key is now named ++ goto-map. Add search-map to the list. ++ ++2009-03-27 Eli Zaretskii ++ ++ * os.texi (System Environment): Update the list of system-type ++ values. ++ ++ * markers.texi (The Mark) : Update for ++ removal of the optional argument DEACTIVATE. ++ ++2009-03-25 Chong Yidong ++ ++ * commands.texi (Focus Events): Most X window managers don't use ++ focus-follows-mouse nowadays. ++ ++2009-03-24 Chong Yidong ++ ++ * commands.texi (Defining Commands): Clarify introduction. ++ (Using Interactive): Not that interactive can be put in a symbol ++ property. ++ (Interactive Call): Note that a symbol with a non-nil ++ interactive-form property satisfies commandp. ++ ++2009-03-23 Juanma Barranquero ++ ++ * minibuf.texi (Intro to Minibuffers): Fix typos. ++ ++2009-03-23 Chong Yidong ++ ++ * minibuf.texi (Intro to Minibuffers): Remove long-obsolete info ++ about minibuffers in old Emacs versions. Copyedits. Emphasize ++ that enable-recursive-minibuffers defaults to nil. ++ (Text from Minibuffer): Simplify introduction. ++ ++2009-03-22 Alan Mackenzie ++ ++ * commands.texi (Using Interactive): Clarify string argument to ++ `interactive' - even promptless elements need \n separators. ++ ++2009-03-18 Chong Yidong ++ ++ * minibuf.texi (Completion Styles): New node. ++ ++ * elisp.texi (Top): Update node listing. ++ ++2009-03-17 Chong Yidong ++ ++ * minibuf.texi (Basic Completion): Note that ++ read-file-name-completion-ignore-case and ++ read-buffer-completion-ignore-case can override ++ completion-ignore-case. ++ (Minibuffer Completion): Document completing-read changes. ++ (Completion Commands): Avoid mentioning partial completion mode. ++ Document minibuffer-completion-confirm changes, and ++ minibuffer-confirm-exit-commands. ++ (High-Level Completion): Document new require-match behavior for ++ read-buffer. Document read-buffer-completion-ignore-case. ++ (Reading File Names): Document new require-match behavior for ++ read-file-name. ++ ++2009-03-14 Chong Yidong ++ ++ * debugging.texi (Error Debugging): Don't mislead the reader into ++ thinking that debug-on-error enters debugger for C-f at EOB. ++ (Error Debugging): Setting debug-on-init within the init file ++ works, and has for some time. ++ ++2009-03-13 Kenichi Handa ++ ++ * display.texi (Fontsets): Update the description. ++ ++2009-03-13 Chong Yidong ++ ++ * advice.texi (Advising Primitives): Link to What Is a Function. ++ ++2009-03-12 Chong Yidong ++ ++ * compile.texi (Speed of Byte-Code): Update example. ++ (Disassembly): Update examples. ++ ++ * loading.texi (Repeated Loading): Simplify examples. ++ ++ * customize.texi (Common Keywords): It's not necessary to use :tag ++ to remove hyphens, as custom-unlispify-tag-name does it ++ automatically. ++ (Variable Definitions): Link to File Local Variables. Document ++ customized-value symbol property. ++ (Customization Types): Move menu to end of node. ++ ++2009-03-10 Chong Yidong ++ ++ * macros.texi (Compiling Macros): Omit misleading sentence, which ++ implied that macros can only be used in the same file they are ++ defined. ++ (Backquote): Remove obsolete information about Emacs 19. ++ ++2009-03-05 John Foerch (tiny change) ++ ++ * display.texi (Display Margins): Fix paren typo. ++ ++2009-02-27 Chong Yidong ++ ++ * elisp.texi (Top): Update node listing. ++ ++ * variables.texi (Variables): Clarify introduction. ++ (Global Variables): Mention that setq is a special form. ++ (Local Variables): Use active voice. ++ (Tips for Defining): Mention marking variables as safe. ++ (Buffer-Local Variables): Mention terminal-local and frame-local ++ variables together. ++ (File Local Variables): Copyedits. ++ (Frame-Local Variables): Note that they are not really useful. ++ (Future Local Variables): Node deleted. ++ ++ * objects.texi (General Escape Syntax): Update explanation of ++ unicode escape syntax. ++ ++2009-02-23 Chong Yidong ++ ++ * control.texi (Control Structures): Add cindex entry for "textual ++ order". ++ ++ * eval.texi (Intro Eval): Copyedits. Standardize on "form" ++ instead of "expression" throughout. ++ (Function Indirection): Copyedits. Use active voice. ++ (Eval): The default value of max-lisp-eval-depth is now 400. ++ ++2009-02-23 Miles Bader ++ ++ * processes.texi (System Processes): Rename `system-process-attributes' ++ to `process-attributes'. ++ ++2009-02-22 Chong Yidong ++ ++ * symbols.texi (Property Lists): Emphasize that property lists are ++ not restricted to symbol cells. ++ (Other Plists): Copyedit. ++ ++ * sequences.texi (Sequences Arrays Vectors): Make introduction ++ more concise. ++ (Arrays): Mention char-tables and bool-vectors too. ++ (Vectors): Don't repeat information given in Arrays node. Link to ++ nodes that explain the vector usage examples. ++ (Char-Tables): Note that char-table elements can have arbitrary ++ type. Explain effect of omitted char-table-extra-slots property. ++ Link to Property Lists node. ++ ++2009-02-22 Chong Yidong ++ ++ * lists.texi (Building Lists): Remove obsolete Emacs 20 usage of ++ `append'. ++ (List Elements): Copyedits. ++ ++ * sequences.texi (Vector Functions): Remove obsolete Emacs 20 use ++ of `vconcat'. ++ ++ * strings.texi (Creating Strings): Copyedits. Remove obsolete ++ Emacs 20 usage of `concat'. ++ (Case Conversion): Copyedits. ++ ++2009-02-21 Chong Yidong ++ ++ * objects.texi (Lisp Data Types, Syntax for Strings, Buffer Type): ++ Minor edits. ++ (Frame Configuration Type): Emphasize that it is not primitive. ++ (Font Type): New node. ++ (Type Predicates): Add fontp; type-of now recognizes font object ++ types. ++ ++ * intro.texi (Version Info): Update version numbers in examples. ++ (Acknowledgements): List more contributors. ++ ++ * elisp.texi: Bump version number to 3.0. ++ (Top): Link to Font Type node. ++ ++2009-02-20 Juanma Barranquero ++ ++ * modes.texi (Major Mode Conventions): Remove duplicate words. ++ (Customizing Keywords): Fix typo. ++ ++2009-02-14 Eli Zaretskii ++ ++ * nonascii.texi (User-Chosen Coding Systems): Document that ++ select-safe-coding-system suggests raw-text if there are raw bytes ++ in the region. ++ (Explicit Encoding): Warn not to use `undecided' when encoding. ++ ++2009-02-11 Glenn Morris ++ ++ * frames.texi (Visibility of Frames): Mention the effect multiple ++ workspaces/desktops can have on visibility. ++ ++2009-02-07 Eli Zaretskii ++ ++ * text.texi (Commands for Insertion): ++ * commands.texi (Event Mod): ++ * keymaps.texi (Searching Keymaps): ++ * nonascii.texi (Translation of Characters): Reinstate ++ documentation of translation-table-for-input. ++ (Explicit Encoding): Document the `charset' text property produced ++ by decode-coding-region and decode-coding-string. ++ ++2009-01-27 Alan Mackenzie ++ ++ * modes.texi (Search-based Fontification): Correct a typo. ++ ++2009-01-25 Juanma Barranquero ++ ++ * abbrevs.texi (Abbrev Table Properties): Fix typo. ++ Reported by Seweryn Kokot . (Bug#2039) ++ ++2009-01-24 Eli Zaretskii ++ ++ * display.texi (Window Systems): Document the value of ++ `initial-window-system' under --daemon. ++ ++ * os.texi (System Environment): Remove description of the ++ `environment' function which has been deleted. ++ ++2009-01-22 Dan Nicolaescu ++ ++ * frames.texi (Multiple Displays): Remove documentation for ++ removed function make-frame-on-tty. ++ ++2009-01-22 Chong Yidong ++ ++ * files.texi (Format Conversion Piecemeal): Clarify behavior of ++ write-region-annotate-functions. Document ++ write-region-post-annotation-function. ++ ++2009-01-19 Chong Yidong ++ ++ * display.texi (Font Lookup): Document WIDTH argument of ++ x-list-fonts. ++ ++2009-01-17 Eli Zaretskii ++ ++ * maps.texi (Standard Keymaps): Rename function-key-map to ++ local-function-key-map. ++ ++ * keymaps.texi (Translation Keymaps): Rename function-key-map to ++ local-function-key-map. ++ ++ * nonascii.texi (Terminal I/O Encoding): `keyboard-coding-system' ++ and `set-keyboard-coding-system' now accept an optional terminal ++ argument. ++ ++ * commands.texi (Event Mod): `keyboard-translate-table' is now ++ terminal-local. ++ (Function Keys): Rename function-key-map to ++ local-function-key-map. ++ ++ * elisp.texi (Top): Make @detailmenu be consistent with changes in ++ frames.texi. ++ ++ * hooks.texi (Standard Hooks): Document `delete-frame-functions' ++ `delete-terminal-functions', `suspend-tty-functions' and ++ `resume-tty-functions'. ++ ++ * frames.texi (Frames): Document `frame-terminal' and ++ `terminal-live-p'. ++ (Multiple Displays): Document `make-frame-on-tty'. ++ (Multiple Terminals): Document `terminal-list', `delete-terminal', ++ `terminal-name', and `get-device-terminal'. ++ (Terminal Parameters): Document `terminal-parameters', ++ `terminal-parameter', and `set-terminal-parameter'. ++ ++ * os.texi (System Environment): Document `environment' and ++ `initial-environment'. ++ (Suspending Emacs): Update for multi-tty; document ++ `suspend-tty', `resume-tty', and `controlling-tty-p'. ++ ++ * nonascii.texi (Coding System Basics): More accurate description ++ of `raw-text'. ++ ++2009-01-12 Juanma Barranquero ++ ++ * display.texi (Low-Level Font): Fix typo. ++ ++2009-01-10 Chong Yidong ++ ++ * elisp.texi (Top): Update node listing. ++ ++ * display.texi (PostScript Images): Node deleted. ++ ++2009-01-10 Eli Zaretskii ++ ++ * processes.texi (Decoding Output): Document that null bytes force ++ no-conversion for reading process output. ++ ++ * files.texi (Reading from Files): Document that null bytes force ++ no-conversion when visiting files. ++ ++ * processes.texi (Serial Ports): Improve wording, suggested by RMS. ++ ++ * nonascii.texi (Lisp and Coding Systems): Document ++ inhibit-null-byte-detection and inhibit-iso-escape-detection. ++ (Character Properties): Improve wording. ++ ++2009-01-09 Chong Yidong ++ ++ * display.texi (Font Lookup): Remove obsolete function ++ x-font-family-list. x-list-fonts accepts Fontconfig/GTK syntax. ++ (Low-Level Font): Rename from Fonts, move to end of Faces section. ++ (Font Selection): Reorder order of variable descriptions. Minor ++ clarifications. ++ ++ * elisp.texi (Top): Update node listing. ++ ++2009-01-09 Glenn Morris ++ ++ * commands.texi (Command Loop Info): Say that last-command-char and ++ last-input-char are obsolete aliases. ++ ++ * edebug.texi (Edebug Recursive Edit): Remove separate references to ++ last-input-char and last-command-char, since they are just aliases for ++ last-input-event and last-command-event. ++ ++ * minibuf.texi (Minibuffer Commands): Use last-command-event rather than ++ last-command-char. ++ ++2009-01-08 Chong Yidong ++ ++ * elisp.texi: Update node listing. ++ ++ * display.texi (Faces): Put Font Selection node after Auto Faces. ++ (Face Attributes): Don't link to Font Lookup. Document ++ font-family-list. ++ (Fonts): New node. ++ ++2009-01-08 Jason Rumney ++ ++ * frames.texi (Pointer Shape): Clarify that only X supports ++ changing the standard pointer shapes. (Bug#1485) ++ ++2009-01-08 Chong Yidong ++ ++ * display.texi (Attribute Functions): Note that a function value ++ :height is relative, and that compatibility functions work by ++ calling set-face-attribute. ++ (Displaying Faces): Reorder list in order of increasing priority. ++ (Face Remapping): New node. Content moved here from Displaying ++ Faces. ++ (Glyphs): Link to Face Functions. ++ ++2009-01-08 Chong Yidong ++ ++ * display.texi (Faces): Don't discuss face id here. facep does ++ not return t. ++ (Defining Faces): Minor clarification. ++ (Face Attributes): Rearrange items to match docstring of ++ set-face-attribute. Add :foundry attribute. Document new role of ++ :font attribute. Texinfo usage fix. ++ (Attribute Functions): Copyedits. ++ (Face Functions): Note that face number is seldom used. ++ ++2009-01-05 Richard M Stallman ++ ++ * strings.texi (Predicates for Strings): Minor clarification. ++ ++ * functions.texi (Function Safety): Texinfo usage fix. ++ ++2009-01-04 Eduard Wiebe (tiny patch) ++ ++ * objects.texi (General Escape Syntax): Fix typo. ++ ++2009-01-03 Martin Rudalics ++ ++ * windows.texi (Choosing Window): Say that pop-up-frame-alist ++ works via the default value of pop-up-frame-function. ++ ++2009-01-02 Eli Zaretskii ++ ++ * processes.texi (System Processes): Document the `time' and ++ `ctime' attributes of `system-process-attributes'. ++ ++2009-01-01 Chong Yidong ++ ++ * display.texi (Face Attributes): Clarify :height attribute. ++ ++2008-12-31 Martin Rudalics ++ ++ * buffers.texi (The Buffer List): Clarify what moves a buffer to ++ the front of the buffer list. Add entries for `last-buffer' and ++ `unbury-buffer'. ++ ++2008-12-27 Eli Zaretskii ++ ++ * elisp.texi (Top): Add @detailmenu items for "Multiple Terminals" ++ and its subsections. ++ ++ * frames.texi (Multiple Terminals, Low-level Terminal) ++ (Terminal Parameters, Frames on Other TTY devices): New sections. ++ (Frames): Add an xref to "Multiple Terminals". ++ ++ * elisp.texi (Top): Add @detailmenu item for "Terminal Type". ++ ++ * objects.texi (Terminal Type): New node. ++ (Editing Types): Add it to the menu. ++ ++ * elisp.texi (Top): Add a @detailmenu item for "Directory Local ++ Variables". ++ ++ * variables.texi (Directory Local Variables): New node. ++ (Variables): Add a menu item for it. ++ ++ * loading.texi (Autoload): Document `generate-autoload-cookie' and ++ `generated-autoload-file'. ++ ++2008-12-20 Eli Zaretskii ++ ++ * os.texi (Startup Summary): Add xref to documentation of ++ `initial-window-system'. ++ ++ * display.texi (Window Systems): Document `window-system' the ++ function. The variable `window-system' is now frame-local. ++ Document `initial-window-system'. ++ ++2008-12-19 Martin Rudalics ++ ++ * windows.texi (Windows): Rewrite description of ++ fit-window-to-buffer. ++ ++2008-12-13 Glenn Morris ++ ++ * modes.texi (Font Lock Basics): Fix level description. (Bug#1534) ++ (Levels of Font Lock): Refer to font-lock-maximum-decoration. ++ ++2008-12-12 Glenn Morris ++ ++ * debugging.texi (Error Debugging): Refer forwards to ++ eval-expression-debug-on-error. ++ ++2008-12-05 Eli Zaretskii ++ ++ * strings.texi (String Basics): Only unibyte strings that ++ represent key sequences hold 8-bit raw bytes. ++ ++ * nonascii.texi (Coding System Basics): Rewrite @ignore'd ++ paragraph to speak about `undecided'. ++ (Character Properties): Don't explain the meaning of each ++ property; instead, identify their Unicode Standard names. ++ (Character Sets): Document `map-charset-chars'. ++ ++2008-12-02 Glenn Morris ++ ++ * files.texi (Format Conversion Round-Trip): Rewrite format-write-file ++ section yet again. ++ ++2008-11-29 Eli Zaretskii ++ ++ * nonascii.texi (Character Properties): New Section. ++ (Specifying Coding Systems): Document ++ `coding-system-priority-list', `set-coding-system-priority', and ++ `with-coding-priority'. ++ (Lisp and Coding Systems): Document `check-coding-systems-region' ++ and `coding-system-charset-list'. ++ (Coding System Basics): Document `coding-system-aliases'. ++ ++ * elisp.texi (Top): Add a @detailmenu entry for "Character ++ Properties". ++ ++ * objects.texi (Character Type): Correct the range of Emacs ++ characters. Add an @xref to "Character Codes". ++ ++ * strings.texi (String Basics): Add an @xref to "Character Codes". ++ ++ * numbers.texi (Integer Basics): Add an @xref to `max-char'. ++ ++ * nonascii.texi (Explicit Encoding): Update for Emacs 23. ++ (Character Codes): Document `max-char'. ++ ++2008-11-28 Eli Zaretskii ++ ++ * nonascii.texi (Text Representations, Converting Representations) ++ (Character Sets, Scanning Charsets, Translation of Characters): ++ Make text more accurate. ++ ++2008-11-28 Glenn Morris ++ ++ * files.texi (Format Conversion Round-Trip): Improve previous change. ++ ++2008-11-26 Chong Yidong ++ ++ * modes.texi (Auto Major Mode): Fix example. ++ ++2008-11-25 Glenn Morris ++ ++ * control.texi (Signaling Errors): Fix `wrong-type-argument' name. ++ ++ * files.texi (Format Conversion Round-Trip): ++ Use active voice for previous change. ++ ++2008-11-25 Chong Yidong ++ ++ * os.texi (Processor Run Time): ++ * processes.texi (Transaction Queues): ++ * markers.texi (The Mark): ++ * windows.texi (Choosing Window, Selecting Windows): ++ * files.texi (Changing Files, Magic File Names): ++ * commands.texi (Key Sequence Input): ++ * functions.texi (Declaring Functions): ++ * strings.texi (Predicates for Strings): ++ * intro.texi (nil and t): Fix typos (pointed out by Drew Adams). ++ ++2008-11-24 Chong Yidong ++ ++ * help.texi (Accessing Documentation): Update example. ++ ++ * variables.texi (Defining Variables): Note that `*' is not ++ necessary if defcustom is used. ++ ++2008-11-22 Eli Zaretskii ++ ++ * elisp.texi (Top): Remove "Chars and Bytes" and "Splitting ++ Characters" from @detailmenu. ++ ++ * nonascii.texi (Character Codes, Character Sets) ++ (Scanning Charsets, Translation of Characters): Update for Emacs 23. ++ (Chars and Bytes, Splitting Characters): Sections removed. ++ ++2008-11-22 Lute Kamstra ++ ++ * positions.texi (Text Lines): Update goto-line documentation. ++ ++2008-11-21 Martin Rudalics ++ ++ * frames.texi (Frames): Fix typo, add cross references, reword. ++ (Initial Parameters): Reword special-display-frame-alist text. ++ (Frames and Windows): Reword. Describe argument norecord for ++ set-frame-selected-window. ++ (Input Focus): Describe argument norecord for select-frame. ++ Remove comment on MS-Windows behavior for focus-follows-mouse. ++ (Raising and Lowering): Mention windows-frames dichotomy in ++ metaphor. ++ ++ * windows.texi (Displaying Buffers, Vertical Scrolling) ++ (Horizontal Scrolling): Fix indenting and rewording issues ++ introduced with 2008-11-07 change. ++ ++2008-11-20 Glenn Morris ++ ++ * files.texi (Format Conversion Round-Trip): Mention `preserve' ++ element of `format-alist'. ++ ++2008-11-19 Glenn Morris ++ ++ * doclicense.texi: Update to FDL 1.3. ++ * elisp.texi, vol1.texi, vol2.texi: Relicense under FDL 1.3 or later. ++ ++2008-11-18 Chong Yidong ++ ++ * windows.texi (Window Hooks): Remove *-end-trigger-functions ++ vars, which are obsolete. Mention jit-lock-register. ++ ++ * modes.texi (Other Font Lock Variables): Document ++ jit-lock-register and jit-lock-unregister. ++ ++ * frames.texi (Color Parameters): Document alpha parameter. ++ ++2008-11-16 Martin Rudalics ++ ++ * windows.texi (Splitting Windows, Deleting Windows) ++ (Selecting Windows, Cyclic Window Ordering) ++ (Buffers and Windows, Displaying Buffers, Choosing Window) ++ (Dedicated Windows, Window Point, Window Start and End) ++ (Textual Scrolling, Vertical Scrolling, Horizontal Scrolling) ++ (Size of Window, Resizing Windows, Window Configurations) ++ (Window Parameters): Avoid @var at beginning of sentences and ++ reword accordingly. ++ ++2008-11-11 Lute Kamstra ++ ++ * files.texi (File Name Components): Fix file-name-extension ++ documentation. ++ ++2008-11-11 Juanma Barranquero ++ ++ * frames.texi (Basic Parameters): Remove display-environment-variable ++ and term-environment-variable. ++ ++2008-11-08 Eli Zaretskii ++ ++ * windows.texi (Basic Windows, Splitting Windows) ++ (Deleting Windows, Selecting Windows, Cyclic Window Ordering) ++ (Buffers and Windows, Displaying Buffers, Dedicated Windows) ++ (Resizing Windows, Window Configurations, Window Parameters): ++ Fix wording and markup. ++ ++2008-11-07 Martin Rudalics ++ ++ * windows.texi (Windows): Update entries. ++ (Basic Windows): Remove listing of attributes. Reword. ++ (Splitting Windows, Deleting Windows): Reword. ++ (Selecting Windows, Cyclic Window Ordering): Reword with special ++ emphasis on order of recently selected windows and buffer list. ++ (Buffers and Windows, Choosing Window): Reword with special ++ emphasis on dedicated windows. ++ (Displaying Buffers): Reword. For switch-to-buffer mention that ++ it may fall back on pop-to-buffer. For other-window try to ++ explain how it treats the cyclic ordering of windows. ++ (Dedicated Windows): New node and section discussing dedicated ++ windows and associated functions. ++ (Window Point): Add entry for window-point-insertion-type. Reword. ++ (Window Start and End): Rename node and section title. Reword. ++ (Textual Scrolling, Vertical Scrolling, Horizontal Scrolling): ++ Minor rewording. ++ (Size of Window): Reword, in particular text on window-width. ++ (Resizing Windows): Reword. Add text on balancing windows. ++ (Window Configurations): Reword. Mention window parameters. ++ (Window Parameters): New node and section on window parameters. ++ (Window Hooks): Reword. Mention that ++ window-configuration-change-hook is run "buffer-locally". ++ * elisp.texi (Top): Update Windows entries in @detailmenu ++ section. ++ ++2008-11-04 Juanma Barranquero ++ ++ * searching.texi (Regexp Search): Fix typo. ++ ++2008-11-03 Seweryn Kokot (tiny change) ++ ++ * searching.texi (Regexp Search): Document GREEDY arg. ++ (Simple Match Data): Fix return value. ++ ++2008-11-01 Eli Zaretskii ++ ++ * nonascii.texi (Text Representations): Rewrite to make consistent ++ with Emacs 23 internal representation of characters. Document ++ `unibyte-string'. ++ ++2008-10-28 Chong Yidong ++ ++ * processes.texi (Process Information): Note that process-status ++ does not accept buffer names. ++ ++2008-10-27 Seweryn Kokot (tiny change) ++ ++ * positions.texi (Skipping Characters): Correct return value of ++ skip-chars-forward. ++ ++2008-10-25 Martin Rudalics ++ ++ * windows.texi (Deleting Windows): Update documentation of ++ delete-windows-on. ++ (Buffers and Windows): Update documentations of ++ get-buffer-window and get-buffer-window-list. ++ (Displaying Buffers): Update documentation of ++ replace-buffer-in-windows. ++ ++ * buffers.texi (Current Buffer): Reword set-buffer and ++ with-current-buffer documentations. ++ (Creating Buffers): Reword documentation of get-buffer-create. ++ ++2008-10-23 Martin Rudalics ++ ++ * buffers.texi (Current Buffer): Reword documentation of ++ set-buffer. ++ (Buffer Names): Reword documentation of buffer-name. ++ (The Buffer List): For bury-buffer explain what happens with the ++ buffer's window. ++ (Creating Buffers): Say that get-buffer-create's arg is called ++ buffer-or-name. ++ ++2008-10-22 Chong Yidong ++ ++ * advice.texi (Computed Advice): Explain what DEFINITION is. ++ ++ * nonascii.texi (Character Codes): Remove obsolete function ++ char-valid-p, and document characterp instead. ++ ++2008-10-22 Martin Rudalics ++ ++ * windows.texi (Displaying Buffers): Reword documentation of ++ pop-to-buffer. ++ (Choosing Window): Rewrite documentation of display-buffer and ++ its options. ++ ++ * buffers.texi (Killing Buffers): Update documentation of ++ kill-buffer. ++ ++2008-10-21 Eli Zaretskii ++ ++ * processes.texi (Serial Ports): Fix wording and improve markup. ++ ++ * searching.texi (Regexp Search): Document `string-match-p' and ++ `looking-at-p'. ++ (POSIX Regexps): Add an xref for "non-greedy". ++ (Regexp Special): Add @cindex entry for "non-greedy". ++ ++ * display.texi (Attribute Functions): Document `face-all-attributes'. ++ (Image Cache) : Minor wording fixes. ++ ++ * frames.texi (Color Names): Add an xref to `read-color'. ++ ++ * minibuf.texi (High-Level Completion): Document `read-color'. ++ ++ * elisp.texi (Top): Add "Swapping Text" to @detailmenu. ++ ++ * positions.texi (Narrowing): Add an xref to "Swapping Text". ++ ++ * buffers.texi (Swapping Text): New section, documents ++ `buffer-swap-text'. ++ ++2008-10-21 Martin Rudalics ++ ++ * windows.texi (Resizing Windows): Minor wording fix. ++ ++2008-10-20 Eli Zaretskii ++ ++ * processes.texi (Shell Arguments): Document `split-string-and-unquote' ++ and `combine-and-quote-strings'. ++ ++ * strings.texi (Creating Strings): Add xrefs for them. ++ ++2008-10-19 Eli Zaretskii ++ ++ * elisp.texi (Top): Make descriptive text for "Reading File Names" ++ match the corresponding menu in minibuf.texi. ++ ++ * minibuf.texi (Reading File Names): Document `read-shell-command' ++ and `minibuffer-local-shell-command-map'. ++ ++2008-10-19 Martin Rudalics ++ ++ * windows.texi (Resizing Windows): Remove var{} around "window" in ++ documentation of enlarge-window. ++ Rewrite documentation of window-min-height and window-min-width. ++ ++2008-10-19 Eli Zaretskii ++ ++ * functions.texi (Calling Functions): Document `apply-partially'. ++ ++ * hooks.texi (Standard Hooks): Mention ++ `before-hack-local-variables-hook' and `hack-local-variables-hook'. ++ ++ * variables.texi (File Local Variables): Document ++ `file-local-variables-alist', `before-hack-local-variables-hook' ++ and `hack-local-variables-hook'. ++ ++ * processes.texi (Synchronous Processes): Document `process-lines'. ++ ++ * customize.texi (Variable Definitions): Document ++ `custom-reevaluate-setting'. ++ ++2008-10-18 Martin Rudalics ++ ++ * windows.texi (Choosing Window, Deleting Windows) ++ (Displaying Buffers): Expand documentation of dedicated windows. ++ ++2008-10-18 Eli Zaretskii ++ ++ * files.texi (Changing Files): Document symbolic input of file ++ modes to `set-file-modes'. Document `read-file-modes' and ++ `file-modes-symbolic-to-number'. ++ ++ * maps.texi (Standard Keymaps): Document `multi-query-replace-map' ++ and `search-map'. ++ ++ * searching.texi (Search and Replace): Document ++ `replace-search-function' and `replace-re-search-function'. ++ Document `multi-query-replace-map'. ++ ++ * minibuf.texi (Text from Minibuffer): Document `read-regexp'. ++ (Completion Commands, Reading File Names): Rename ++ `minibuffer-local-must-match-filename-map' to ++ `minibuffer-local-filename-must-match-map'. ++ (Minibuffer Completion): The `require-match' argument to ++ `completing-read' can now have the value `confirm-only'. ++ ++ * windows.texi (Displaying Buffers): Minor wording fix. ++ (Choosing Window): `split-height-threshold' can now be nil. ++ Document `split-width-threshold'. `pop-up-frames' can have the ++ value `graphic-only'. ++ ++2008-10-17 Eli Zaretskii ++ ++ * os.texi (Startup Summary): Document `before-init-time' and ++ `after-init-time'. Document `initial-window-system' and ++ `window-system-initialization-alist'. Document reading the ++ abbrevs file. Document the call to `server-start' under --daemon. ++ Rearrange a bit to be consistent with the code flow. ++ (Processor Run Time): Document `emacs-uptime' and `emacs-init-time'. ++ (Time Parsing): Document `format-seconds'. ++ ++2008-10-17 Martin Rudalics ++ ++ * windows.texi (Basic Windows, Splitting Windows): Fix whitespace ++ and reword. ++ ++2008-10-16 Eli Zaretskii ++ ++ * markers.texi (The Mark): Document use-region-p. ++ ++2008-10-15 Eli Zaretskii ++ ++ * internals.texi (Writing Emacs Primitives): The interactive spec ++ of a primitive can be a Lisp form. ++ ++ * markers.texi (The Mark): Document the `lambda' and `(only . OLD)' ++ values of transient-mark-mode. Document handle-shift-selection. ++ ++ * commands.texi (Using Interactive, Interactive Codes): Document `^'. ++ (Interactive Examples): Show an example of `^'. ++ (Key Sequence Input): Document this-command-keys-shift-translated. ++ (Defining Commands, Using Interactive): The interactive-form of a ++ function can be added via its symbol's property. ++ ++ * positions.texi (List Motion): beginning-of-defun-function can ++ now accept an argument. ++ ++ * text.texi (Low-Level Kill Ring): interprogram-paste-function can ++ now return a list of strings. ++ ++ * control.texi (Handling Errors): Document ignore-errors. ++ ++ * frames.texi (Creating Frames): Document frame-inherited-parameters. ++ (Parameter Access): Document set-frame-parameter. ++ ++ * variables.texi (Creating Buffer-Local): Add an xref to "Setting ++ Hooks" for the effect of kill-all-local-variables on local hook ++ functions. ++ ++ * modes.texi (Major Mode Conventions, Mode Line Variables): ++ `mode-name' need not be a string. xref to "Mode Line Data" for ++ details, and to "Emulating Mode Line" for computing a string ++ value. ++ ++2008-10-14 Eli Zaretskii ++ ++ * processes.texi (System Processes): New section. ++ (Processes, Signals to Processes): Add xrefs to it. ++ ++ * objects.texi (Editing Types): A `process' is a subprocess of ++ Emacs, not just any process running on the OS. ++ ++ * elisp.texi (Top): Adjust the @detailmenu for the above two ++ changes. ++ ++ * sequences.texi (Char-Tables): Remove documentation of ++ set-char-table-default, which has no effect since Emacs 23. ++ : Don't mention generic ++ characters and charsets. Add a cons cell as a possible argument. ++ ++ * nonascii.texi (Splitting Characters) ++ (Translation of Characters): Don't mention generic characters. ++ ++ * display.texi (Fontsets): Don't mention generic characters. ++ ++ * sequences.texi (Char-Tables): `map-char-table' can now call its ++ argument FUNCTION with a cons cell as KEY. ++ ++2008-10-13 Eli Zaretskii ++ ++ * objects.texi (Primitive Function Type): Move "@cindex special ++ forms" from here... ++ ++ * eval.texi (Special Forms): ...to here. ++ ++ * functions.texi (What Is a Function): `functionp' returns nil for ++ special forms. Add an xref. ++ ++ * elisp.texi (Top): Add a @detailmenu entry for "Frame-Local ++ Variables". ++ ++ * variables.texi (Frame-Local Variables): New section. ++ (Buffer-Local Variables): Add an xref to it. ++ (Intro to Buffer-Local, Creating Buffer-Local): A variable cannot ++ have both frame-local and buffer-local binding. ++ ++ * frames.texi (Frames): Mention multiple tty frames. ++ (Frame Parameters, Parameter Access): Mention frame-local variable ++ bindings. ++ ++2008-09-20 Glenn Morris ++ ++ * display.texi (Defining Faces): Recommend against face variables. ++ ++2008-09-16 Juanma Barranquero ++ ++ * display.texi (Echo Area Customization): Fix typo. ++ ++2008-09-09 Juanma Barranquero ++ ++ * loading.texi (Where Defined): Add `defface' item. ++ ++2008-09-06 Martin Rudalics ++ ++ * loading.texi (Where Defined): Fix description of symbol-file. ++ ++2008-08-26 Jason Rumney ++ ++ * display.texi (TIFF Images): New section describing :index property. ++ ++2008-08-23 Chong Yidong ++ ++ * display.texi (Temporary Displays): Remove unnecessary comment ++ about usage of temp-buffer-show-hook. ++ ++2008-08-05 Chong Yidong ++ ++ * symbols.texi (Other Plists): Fix incorrect example. ++ Suggested by Florian Beck. ++ ++2008-07-31 Juanma Barranquero ++ ++ * os.texi: Fix previous change. ++ ++2008-07-31 Dan Nicolaescu ++ ++ * os.texi: ++ * intro.texi: ++ * files.texi: Remove VMS support. ++ ++2008-07-27 Dan Nicolaescu ++ ++ * os.texi: ++ * frames.texi: ++ * display.texi: Remove mentions of Mac Carbon. ++ ++2008-07-01 Miles Bader ++ ++ * text.texi (Special Properties): ++ * display.texi (Truncation): Add wrap-prefix and line-prefix. ++ ++2008-06-28 Johan Bockgård ++ ++ * display.texi (Other Image Types): Fix copy/paste error; say ++ "PBM", not "XBM". ++ ++2008-06-26 Dan Nicolaescu ++ ++ * os.texi: Remove references to obsolete systems. ++ ++2008-06-20 Eli Zaretskii ++ ++ * makefile.w32-in (distclean): Remove makefile. ++ ++2008-06-17 Glenn Morris ++ ++ * Makefile.in (emacsver, miscmanualdir, VERSION, manual, install) ++ (elisp, dist): Remove rules and variables that are obsolete now ++ the lisp manual is no longer distributed separately. ++ ++2008-06-16 Glenn Morris ++ ++ * configure, configure.in, mkinstalldirs: Remove unused files. ++ ++ * book-spine.texinfo: Set version to 23.0.60. ++ * vol1.texi (EMACSVER): ++ * vol2.texi (EMACSVER): Set to 23.0.60. ++ ++ * elisp.texi, vol1.texi, vol2.texi: Update Back-Cover Text ++ as per maintain.info. ++ ++2008-06-15 Glenn Morris ++ ++ * makefile.w32-in (manual): Use "23" rather than "21". ++ ++ * Makefile.in (emacsver): New, set by configure. ++ (manual): Use emacsver. ++ ++ * intro.texi: Report bugs using M-x report-emacs-bug. ++ ++ * elisp.texi (EMACSVER): Remove duplicate, outdated setting. ++ ++2008-06-13 Daniel Engeler ++ ++ * elisp.texi, internals.texi, processes.texi: Add documentation ++ about serial port access. ++ ++2008-06-05 Miles Bader ++ ++ * display.texi (Displaying Faces): Update to reflect function ++ renamings in face-remap.el. ++ ++2008-06-05 Juanma Barranquero ++ ++ * display.texi (Fontsets): Fix typos. ++ ++2008-06-03 Miles Bader ++ ++ * display.texi (Displaying Faces): Add add-relative-face-remapping, ++ remove-relative-face-remapping, set-base-face-remapping, ++ and set-default-base-face-remapping. ++ ++2008-06-01 Miles Bader ++ ++ * display.texi (Displaying Faces): Add face-remapping-alist. ++ ++2008-05-30 Stefan Monnier ++ ++ * tips.texi (Coding Conventions): Do not encourage the use of "-flag" ++ variable names. ++ ++2008-05-03 Eric S. Raymond ++ ++ * keymaps.texi: Clarify that (current-local-map) and ++ (current-global-map) return references, not copies. ++ ++2008-05-02 Juri Linkov ++ ++ * minibuf.texi (Text from Minibuffer): Document a list of ++ default values for `read-from-minibuffer'. ++ ++2008-04-24 Juanma Barranquero ++ ++ * nonascii.texi (Translation of Characters): Fix previous change. ++ ++2008-04-20 Chong Yidong ++ ++ * display.texi (Overlay Properties): Clarify role of underlying ++ textprop and overlay keymaps for display strings. ++ ++ * keymaps.texi (Active Keymaps): Ditto. ++ ++2008-04-19 Stefan Monnier ++ ++ * minibuf.texi (Programmed Completion): ++ Replace dynamic-completion-table with the new completion-table-dynamic. ++ ++2008-04-07 Chong Yidong ++ ++ * intro.texi (Some Terms): Change "fonts in this manual" index ++ entry to "typographic conventions". ++ ++2008-04-05 Eli Zaretskii ++ ++ * objects.texi (Text Props and Strings): Add indexing for read ++ syntax of text properties. ++ ++2008-03-25 Stefan Monnier ++ ++ * processes.texi (Decoding Output): Remove process-filter-multibyte ++ functions. ++ ++2008-03-15 Martin Rudalics ++ ++ * display.texi (Finding Overlays): Say that empty overlays at ++ the end of the buffer are reported too. ++ ++2008-03-13 Glenn Morris ++ ++ * elisp.texi (EMACSVER): Set to 23.0.60. ++ ++2008-02-26 Chong Yidong ++ ++ * strings.texi (Formatting Strings): Treat - and 0 as flag characters. ++ ++2008-02-22 Glenn Morris ++ ++ * frames.texi (Position Parameters): Clarify the description of ++ `left' and `top', using information from "Geometry". ++ (Geometry): Give a pointer to "Position Parameters", rather than ++ repeating information. ++ ++2008-02-11 Glenn Morris ++ ++ * objects.texi (Equality Predicates): No longer talk about "two" ++ functions. ++ ++2008-02-11 Lawrence Mitchell (tiny change) ++ ++ * objects.texi (Equality Predicates): Add defun for ++ equal-including-properties. ++ ++2008-02-10 Glenn Morris ++ ++ * objects.texi (Equality Predicates): ++ Mention equal-including-properties. ++ ++2008-02-07 Richard Stallman ++ ++ * windows.texi (Window Start): Mention the feature of moving ++ window-start to start of line. ++ ++2008-02-07 Jan Djärv ++ ++ * keymaps.texi (Tool Bar): Document rtl property. ++ ++2008-01-27 Thien-Thi Nguyen ++ ++ * display.texi (Button Types): ++ For define-button-type, clarify type of NAME. ++ ++2008-01-19 Martin Rudalics ++ ++ * buffers.texi (Buffer Modification): Fix typo. ++ ++2008-01-06 Dan Nicolaescu ++ ++ * os.texi (System Environment): Remove references to OSes that are ++ not supported anymore. ++ ++2008-01-05 Dan Nicolaescu ++ ++ * os.texi (System Environment): Remove mention for Masscomp. ++ ++2008-01-04 Richard Stallman ++ ++ * display.texi (Faces): Don't talk about internal face vector as arg ++ to facep. ++ ++ * customize.texi (Type Keywords): Fix previous change. ++ ++ * text.texi (Links and Mouse-1): Fix xref for commands.texi change. ++ * elisp.texi (Top): Fix menu for commands.texi change. ++ ++2007-12-30 Richard Stallman ++ ++ * commands.texi (Accessing Mouse): Renamed from Accessing Events. ++ (Accessing Scroll): New node broken out of Accessing Mouse. ++ ++2007-12-28 Richard Stallman ++ ++ * frames.texi (Size Parameters): Fix typo. ++ (Basic Parameters): For `title', refer to title bar. ++ (Size and Position): Explain meaning of frame pixel width and height. ++ ++2007-12-23 Richard Stallman ++ ++ * customize.texi (Type Keywords): Uncomment :validate and clarify it. ++ Improve some of the commented-out keywords' text too. ++ ++2007-12-14 Martin Rudalics ++ ++ * nonascii.texi (Encoding and I/O): Reword to avoid saying ++ "visit the current buffer". ++ ++ * os.texi (System Interface): Fix typo. ++ ++2007-12-04 Richard Stallman ++ ++ * objects.texi (Symbol Type): Fix typo. ++ ++2007-12-03 Richard Stallman ++ ++ * hooks.texi (Standard Hooks): Add link to Hooks for Loading. ++ ++2007-12-01 Glenn Morris ++ ++ * functions.texi (Declaring Functions): Improve previous change. ++ ++2007-11-30 Glenn Morris ++ ++ * functions.texi (Declaring Functions): Add optional fourth ++ argument of declare-function, and setting third argument to `t'. ++ ++2007-11-29 Richard Stallman ++ ++ * customize.texi (Composite Types): Document `group' type. ++ ++2007-11-29 Glenn Morris ++ ++ * functions.texi (Declaring Functions): Add findex. Mention ++ `external' files. ++ ++2007-11-26 Juanma Barranquero ++ ++ * functions.texi (Declaring Functions): Fix directive. ++ ++2007-11-25 Richard Stallman ++ ++ * help.texi (Help Functions): Clean up last change. ++ ++ * advice.texi (Preactivation, Activation of Advice): Minor cleanup. ++ ++ * loading.texi (Named Features): Minor cleanup. ++ ++ * macros.texi (Eval During Expansion): Minor cleanup. ++ ++ * variables.texi (Variable Aliases): Minor cleanup. ++ ++2007-11-24 Richard Stallman ++ ++ * functions.texi (Declaring Functions): Clarify previous change. ++ ++ * compile.texi (Compiler Errors): Clarify previous change. ++ ++2007-11-24 Richard Stallman ++ ++ * display.texi (Refresh Screen, Forcing Redisplay): ++ Clarify the text and move items around. ++ ++2007-11-24 Glenn Morris ++ ++ * functions.texi (Declaring Functions): New section. ++ * compile.texi (Compiler Errors): Mention declaring functions, ++ defvar with no initvalue, and byte-compile-warnings. ++ ++2007-11-15 Martin Rudalics ++ ++ * vol1.texi (Top): Remove Frame-Local Variables from Node Listing. ++ * vol2.texi (Top): Remove Frame-Local Variables from Node Listing. ++ ++2007-11-13 Martin Rudalics ++ ++ * help.texi (Help Functions): Document new macro `with-help-window'. ++ ++2007-11-10 Paul Pogonyshev ++ ++ * searching.texi (Replacing Match): Describe new ++ `match-substitute-replacement'. ++ ++2007-10-31 Richard Stallman ++ ++ * strings.texi (Creating Strings): Null strings from concat not unique. ++ ++2007-10-26 Richard Stallman ++ ++ * objects.texi (Equality Predicates): Null strings are uniquified. ++ ++ * minibuf.texi: Minor clarifications in previous change. ++ ++2007-10-25 Glenn Morris ++ ++ * customize.texi (Variable Definitions): Add :risky and :safe keywords. ++ ++2007-10-24 Richard Stallman ++ ++ * elisp.texi (Top): Delete Frame-Local Variables from subnode menu. ++ ++ * variables.texi (Frame-Local Variables): Node deleted. ++ (Variables): Delete Frame-Local Variables from menu. ++ (Local Variables, Buffer-Local Variables, Intro to Buffer-Local) ++ (Default Value): Don't mention frame-local vars. ++ ++ * os.texi (Idle Timers): current-idle-time returns nil if not idle. ++ ++ * loading.texi (Unloading): Document FEATURE-unload-function ++ instead of FEATURE-unload-hook. ++ ++ * frames.texi (Multiple Displays): Don't mention frame-local vars. ++ ++2007-10-22 Juri Linkov ++ ++ * minibuf.texi (Text from Minibuffer, Minibuffer Completion) ++ (High-Level Completion): Document a list of default value strings ++ in the DEFAULT argument, for which minibuffer functions return the ++ first element. ++ ++2007-10-17 Juri Linkov ++ ++ * text.texi (Filling): Update arguments of fill-paragraph. ++ fill-paragraph operates on the active region in Transient Mark mode. ++ Remove fill-paragraph-or-region. ++ ++2007-10-13 Karl Berry ++ ++ * elisp.texi (@dircategory): Move to after @copying, ++ since we want @copying as close as possible to the beginning of ++ the output. ++ ++2007-10-12 Richard Stallman ++ ++ * elisp.texi (Top): Add Distinguish Interactive to subnode menu. ++ ++ * commands.texi (Distinguish Interactive): New node, ++ broken out from Interactive Call and rewritten. ++ (Command Loop): Put Distinguish Interactive in menu. ++ ++2007-10-09 Richard Stallman ++ ++ * text.texi (Examining Properties): Mention overlay priority. ++ ++ * display.texi (Display Margins): Correct the description ++ of margin display specifications. ++ (Replacing Specs): New subnode broken out of Display Property. ++ ++2007-10-06 Juri Linkov ++ ++ * text.texi (Filling): Document fill-paragraph-or-region. ++ ++2007-10-05 Juanma Barranquero ++ ++ * display.texi (Auto Faces): Fix typo. ++ ++2007-10-02 Richard Stallman ++ ++ * display.texi (Display Property): Explain some display specs ++ don't let you move point in. ++ ++ * frames.texi (Cursor Parameters): Describe ++ cursor-in-non-selected-windows here. Explain more values. ++ ++ * windows.texi (Basic Windows): Don't describe ++ cursor-in-non-selected-windows here. ++ ++2007-10-01 Eli Zaretskii ++ ++ * processes.texi (Misc Network): Note that these functions are ++ supported only on some systems. ++ ++2007-10-01 Richard Stallman ++ ++ * display.texi (Overlay Properties): Explain nil as priority. ++ Explain that conflicts are unpredictable if not resolved by ++ priorities. ++ ++2007-09-23 Richard Stallman ++ ++ * macros.texi (Backquote): Minor clarification. ++ ++2007-09-19 Richard Stallman ++ ++ * display.texi (Display Property): Explain multiple display specs. ++ Clarify when they work in parallel and when one overrides. ++ Fix error in example. ++ ++2007-09-06 Glenn Morris ++ ++ Move from lispref/ to doc/lispref/. Change all setfilename ++ commands to use ../../info. ++ * Makefile.in (infodir): Go up one more level. ++ (usermanualdir): Change from ../man to ../emacs. ++ (miscmanualdir): New. ++ (dist): Use new variable miscmanualdir. ++ * makefile.w32-in (infodir, texinputdir): Go up one more level. ++ (usermanualdir): Change from ../man to ../emacs. ++ ++2007-08-30 Martin Rudalics ++ ++ * commands.texi (Command Loop Info): Advise against changing ++ most variables described here. Explain new variable ++ last-repeatable-command. ++ ++2007-08-29 Glenn Morris ++ ++ * elisp.texi (EMACSVER): Increase to 23.0.50. ++ ++2007-08-29 Dan Nicolaescu ++ ++ * frames.texi (Basic Parameters): Add display-environment-variable ++ and term-environment-variable. ++ ++2007-08-28 Juri Linkov ++ ++ * display.texi (Image Formats, Other Image Types): Add SVG. ++ ++2007-08-28 Juri Linkov ++ ++ * display.texi (Images): Move formats-related text to new node ++ "Image Formats". ++ (Image Formats): New node. ++ ++2007-08-27 Richard Stallman ++ ++ * windows.texi (Window Configurations): Clarify what ++ a window configuration saves. ++ ++2007-08-25 Richard Stallman ++ ++ * display.texi (Images): Delete redundant @findex. ++ ++2007-08-16 Richard Stallman ++ ++ * processes.texi (Asynchronous Processes): Clarify ++ doc of start-file-process. ++ ++2007-08-08 Martin Rudalics ++ ++ * modes.texi (Example Major Modes): Fix typo. ++ ++2007-08-08 Glenn Morris ++ ++ * intro.texi (nil and t): Do not use `iff' in documentation. ++ ++ * tips.texi (Documentation Tips): Recommend against `iff'. ++ ++2007-08-07 Chong Yidong ++ ++ * display.texi (Image Cache): Document image-refresh. ++ ++2007-08-06 Martin Rudalics ++ ++ * windows.texi (Size of Window): Document window-full-width-p. ++ ++2007-07-25 Glenn Morris ++ ++ * gpl.texi (GPL): Replace license with GPLv3. ++ ++ * Relicense all FSF files to GPLv3 or later. ++ ++2007-07-24 Michael Albinus ++ ++ * processes.texi (Synchronous Processes): ++ Add `process-file-shell-command'. ++ (Asynchronous Processes): Mention restricted use of ++ `process-filter' and `process-sentinel' in ++ `start-file-process'. Add `start-file-process-shell-command'. ++ ++2007-07-17 Michael Albinus ++ ++ * files.texi (Magic File Names): Introduce optional parameter ++ IDENTIFICATION for `file-remote-p'. ++ ++2007-07-16 Richard Stallman ++ ++ * display.texi (Defining Faces): Fix previous change. ++ ++2007-07-14 Richard Stallman ++ ++ * control.texi (Handling Errors): Document `debug' in handler list. ++ ++2007-07-10 Richard Stallman ++ ++ * display.texi (Defining Faces): Explain C-M-x feature for defface. ++ ++2007-07-09 Richard Stallman ++ ++ * files.texi (Magic File Names): Rewrite previous change. ++ ++2007-07-08 Michael Albinus ++ ++ * files.texi (Magic File Names): Introduce optional parameter ++ CONNECTED for `file-remote-p'. ++ ++2007-07-07 Michael Albinus ++ ++ * processes.texi (Asynchronous Processes): ++ * files.texi (Magic File Names): Add `start-file-process'. ++ ++2007-06-27 Richard Stallman ++ ++ * files.texi (Format Conversion Piecemeal): Clarify ++ `after-insert-file-functions' calling convention. ++ ++2007-06-27 Michael Albinus ++ ++ * files.texi (Magic File Names): Remove `dired-call-process'. ++ Add `process-file'. ++ ++2007-06-27 Kenichi Handa ++ ++ * text.texi (Special Properties): Fix description about ++ `composition' property. ++ ++2007-06-26 Kenichi Handa ++ ++ * nonascii.texi (Default Coding Systems): Document about the ++ return value `undecided'. ++ ++2007-06-25 David Kastrup ++ ++ * keymaps.texi (Active Keymaps): Document new POSITION argument of ++ `current-active-maps'. ++ ++2007-06-24 Karl Berry ++ ++ * elisp.texi, vol1.texi, vol2.texi: New Back-Cover Text. ++ ++2007-06-15 Juanma Barranquero ++ ++ * display.texi (Overlay Arrow): Doc fix. ++ ++2007-06-14 Karl Berry ++ ++ * anti.texi (Antinews): Typo. ++ ++2007-06-14 Chong Yidong ++ ++ * display.texi (Image Cache): Document image-refresh. ++ ++2007-06-12 Karl Berry ++ ++ * vol1.texi, vol2.texi, two-volume-cross-refs.txt: Update. ++ * two-volume.make: New file. ++ * .cvsignore: Ignore two-volume files. ++ ++2007-06-12 Tom Tromey ++ ++ * os.texi (Init File): Document user-emacs-directory. ++ ++2007-06-03 Nick Roberts ++ ++ * commands.texi (Click Events): Describe width and height when ++ object is nil. ++ ++2007-05-30 Nick Roberts ++ ++ * commands.texi (Click Events): Layout more logically. Describe ++ width and height. ++ (Drag Events, Motion Events): Update to new format for position. ++ ++2007-06-02 Richard Stallman ++ ++ * frames.texi (Color Parameters): Add xref to (emacs)Standard Faces. ++ ++2007-06-02 Chong Yidong ++ ++ * Version 22.1 released. ++ ++2007-06-01 Stefan Monnier ++ ++ * text.texi (Special Properties): Correct meaning of fontified face. ++ ++2007-05-30 Richard Stallman ++ ++ * text.texi (Special Properties): Add link to Adjusting Point. ++ ++2007-05-12 Richard Stallman ++ ++ * text.texi (Margins): indent-to-left-margin is not the default. ++ (Mode-Specific Indent): For indent-line-function, the default ++ is indent-relative. ++ ++ * modes.texi (Example Major Modes): Explain last line of text-mode ++ is redundant. ++ ++2007-05-10 Richard Stallman ++ ++ * keymaps.texi (Scanning Keymaps): Update where-is-internal example. ++ ++ * help.texi (Keys in Documentation): Add reference to ++ Documentation Tips. ++ ++ * files.texi (Format Conversion): TO-FN gets three arguments. ++ ++ * modes.texi (Auto Major Mode): Document file-start-mode-alist. ++ ++2007-05-10 Thien-Thi Nguyen ++ ++ * elisp.texi (Top): Remove "Saving Properties" from detailed menu. ++ * files.texi (Format Conversion): Expand intro; add menu. ++ (Format Conversion Overview, Format Conversion Round-Trip) ++ (Format Conversion Piecemeal): New nodes/subsections. ++ * hooks.texi: Xref "Format Conversion" , not "Saving Properties". ++ * text.texi (Text Properties): Remove "Saving Properties" from menu. ++ (Saving Properties): Delete node/subsection. ++ ++2007-05-07 Karl Berry ++ ++ * elisp.texi (EMACSVER): Back to 22. ++ ++2007-05-06 Richard Stallman ++ ++ * processes.texi (Accepting Output): Revert most of previous change. ++ ++2007-05-05 Richard Stallman ++ ++ * processes.texi (Accepting Output): accept-process-output ++ uses microseconds, not milliseconds. But that arg is obsolete. ++ ++2007-05-04 Karl Berry ++ ++ * elisp.texi (EMACSVER) [smallbook]: 22.1, not 22. ++ ++2007-05-04 Eli Zaretskii ++ ++ * tips.texi (Documentation Tips): Rearrange items to place the ++ more important ones first. Add an index entry for hyperlinks. ++ ++2007-05-03 Karl Berry ++ ++ * elisp.texi (\urlcolor, \linkcolor) [smallbook]: \Black for printing. ++ (EMACSVER) [smallbook]: 22 for printed version. ++ ++ * control.texi (Signaling Errors) : texinfo.tex is fixed, ++ so restore anchor to normal position after defun. Found by Kevin Ryde. ++ ++2007-04-26 Glenn Morris ++ ++ * elisp.texi (EMACSVER): Increase to 22.1.50. ++ ++2007-04-28 Karl Berry ++ ++ * elisp.texi: Improve line breaks on copyright page, ++ similar layout to emacs manual, 8.5x11 by default. ++ ++2007-04-24 Richard Stallman ++ ++ * text.texi (Special Properties): Add xref to Overlay Properties. ++ ++ * display.texi (Overlay Properties): Add xref to Special Properties. ++ ++2007-04-22 Richard Stallman ++ ++ * keymaps.texi (Extended Menu Items): Move the info about ++ format with cached keyboard binding. ++ ++2007-04-21 Richard Stallman ++ ++ * text.texi (Special Properties): Clarify previous change. ++ ++ * files.texi (File Name Expansion): Clarify previous change. ++ ++ * display.texi (Attribute Functions): Fix example for ++ face-attribute-relative-p. ++ ++2007-04-19 Kenichi Handa ++ ++ * text.texi (Special Properties): Document composition property. ++ ++2007-04-19 Glenn Morris ++ ++ * files.texi (File Name Expansion): Mention "superroot". ++ ++2007-04-15 Chong Yidong ++ ++ * frames.texi (Multiple Displays): Add note about "multi-monitor" ++ setups. ++ (Display Feature Testing): Note that display refers to all ++ physical monitors for multi-monitor setups. ++ ++2007-04-14 Richard Stallman ++ ++ * lists.texi (Sets And Lists): Clarify `delete' examples. ++ Remove spurious xref to same node. ++ Clarify xref for add-to-list. ++ ++2007-04-12 Nick Roberts ++ ++ * keymaps.texi (Format of Keymaps): Remove spurious ")" from ++ value of lisp-mode-map. ++ ++2007-04-11 Karl Berry ++ ++ * anti.texi (Antinews): ++ * display.texi (Overlay Properties, Defining Images): ++ * processes.texi (Synchronous Processes, Sentinels): ++ * syntax.texi (Syntax Table Internals): ++ * searching.texi (Regexp Special): ++ * nonascii.texi (Default Coding Systems): ++ * text.texi (Special Properties): ++ * minibuf.texi (Basic Completion): Wording to improve breaks in ++ 8.5x11 format. ++ * elisp.texi (smallbook): New @set to more easily switch between ++ smallbook and 8.5x11. ++ ++2007-04-11 Richard Stallman ++ ++ * text.texi (Lazy Properties): Minor fix. ++ ++2007-04-08 Karl Berry ++ ++ * symbols.texi (Plists and Alists): Period after "vs" in index entries. ++ * macros.texi (Backquote): Downcase Backquote in index entries for ++ consistency. ++ ++2007-04-08 Richard Stallman ++ ++ * text.texi (Adaptive Fill): Just describe default, ++ don't show it (since it contains non-ASCII chars). ++ ++2007-04-07 Karl Berry ++ ++ * text.texi (Adaptive Fill) [@iftex]: Omit binary characters in ++ adaptive-fill-regexp's value, since they are not in the standard ++ TeX fonts. ++ ++2007-04-07 Guanpeng Xu ++ ++ * display.texi (Defining Faces): Fix example. ++ ++2007-04-07 Karl Berry ++ ++ * display.texi (Button Buffer Commands): Improve page break. ++ ++2007-04-07 Richard Stallman ++ ++ * advice.texi (Activation of Advice): Remove redundant index entry. ++ ++ * backups.texi: Improve index entries. Remove redundant ones. ++ ++ * compile.texi (Byte Compilation): Improve index entry. ++ ++ * hash.texi (Creating Hash): Improve index entry. ++ ++ * symbols.texi (Definitions): Improve index entry. ++ ++ * edebug.texi: Improve index entries. Remove redundant/useless ones. ++ ++ * maps.texi (Standard Keymaps): Remove useless index entry. ++ ++ * help.texi (Documentation Basics): Remove redundant index entries. ++ ++ * customize.texi: Improve index entries. ++ Remove redundant/useless ones. ++ ++ * locals.texi (Standard Buffer-Local Variables): Clarify intro text. ++ ++ * streams.texi (Output Variables): Improve index entry. ++ ++ * abbrevs.texi (Abbrevs): Remove useless index entry. ++ ++ * macros.texi (Expansion): Remove useless index entry. ++ ++ * text.texi: Improve index entries. Remove redundant/useless ones. ++ (Text Properties, Examining Properties) ++ (Special Properties): Use "property category" instead of "category" ++ to refer to the `category' property. ++ ++ * positions.texi: Improve index entries. Remove useless one. ++ ++ * lists.texi: Improve index entries. Remove redundant/useless ones. ++ ++ * os.texi: Improve index entries. ++ (Timers): Fix previous change. ++ ++ * buffers.texi: Improve index entries. ++ (Modification Time): Get rid of term "obsolete buffer". ++ ++ * debugging.texi: Improve index entries. ++ (Test Coverage): Add xref to other test coverage ftr. ++ ++ * eval.texi: Improve index entry. Remove redundant ones. ++ ++ * numbers.texi: Improve index entries. Remove redundant/useless ones. ++ ++ * files.texi: Improve index entries. Remove redundant/useless ones. ++ ++ * objects.texi: Improve index entries. ++ ++ * processes.texi: Improve index entries. ++ ++ * modes.texi: Improve index entry. Remove redundant one. ++ ++ * nonascii.texi: Improve index entries. ++ ++ * internals.texi: Improve index entries. ++ ++ * syntax.texi: Improve index entries. ++ ++ * keymaps.texi (Active Keymaps): Improve index entries. ++ ++ * commands.texi: Improve index entries. Remove redundant/useless ones. ++ ++ * frames.texi: Improve index entries. Remove redundant/useless ones. ++ ++ * markers.texi: Improve index entries. Remove redundant ones. ++ ++ * tips.texi: Improve index entries. ++ ++ * loading.texi (Unloading): Improve index entry. ++ ++ * variables.texi: Improve index entries. Remove redundant one. ++ ++ * sequences.texi: Improve index entry. ++ ++ * display.texi: Improve index entries. Remove redundant ones. ++ ++ * windows.texi: Improve index entries. ++ ++ * searching.texi: Improve index entries. Remove redundant one. ++ ++ * strings.texi (Case Tables): Improve last change. ++ ++2007-04-04 Chong Yidong ++ ++ * strings.texi (Case Tables): Document with-case-table and ++ ascii-case-table. ++ ++2007-04-03 Karl Berry ++ ++ * processes.texi (Network): Reword to improve page break. ++ ++2007-04-03 Eli Zaretskii ++ ++ * functions.texi (Inline Functions): Describe more disadvantages ++ of defsubst, and make advice against it stronger. ++ ++2007-04-02 Karl Berry ++ ++ * backups.texi (Backup Names): Avoid widow words. ++ * modes.texi (Example Major Modes): Align last comment. ++ ++2007-04-01 Chong Yidong ++ ++ * keymaps.texi (Remapping Commands): Document new arg to ++ command-remapping. ++ ++2007-04-01 Karl Berry ++ ++ * processes.texi (Low-Level Network): Typo. ++ * loading.texi (Hooks for Loading): Avoid double "the". ++ * keymaps.texi (Key Sequences): No double "and". ++ (Changing Key Bindings): Shorten to improve line break. ++ ++2007-03-31 Glenn Morris ++ ++ * os.texi (Timers): Fix description of run-at-time TIME formats. ++ ++2007-03-31 Richard Stallman ++ ++ * display.texi (Invisible Text): Correct buffer-invisibility-spec ++ regarding ellipsis. ++ ++2007-03-31 Eli Zaretskii ++ ++ * intro.texi (nil and t): ++ * symbols.texi (Plists and Alists): ++ * variables.texi (Variable Aliases, Constant Variables): ++ * functions.texi (Defining Functions): ++ * advice.texi (Advising Primitives): ++ * debugging.texi (Syntax Errors, Compilation Errors): ++ * minibuf.texi (Minibuffer Windows): ++ * commands.texi (Adjusting Point): ++ * modes.texi (Syntactic Font Lock, Faces for Font Lock) ++ (Auto Major Mode, Major Mode Conventions): ++ * help.texi (Describing Characters): ++ * files.texi (Create/Delete Dirs, Information about Files) ++ (File Locks, Writing to Files, Reading from Files) ++ (Saving Buffers): ++ * windows.texi (Resizing Windows, Cyclic Window Ordering): ++ * frames.texi (Finding All Frames): ++ * positions.texi (Buffer End, Motion): ++ * markers.texi (The Region): ++ * text.texi (Deletion, Near Point): ++ * display.texi (Displaying Messages, Truncation): ++ * os.texi (Processor Run Time): ++ * tips.texi (Key Binding Conventions, Programming Tips) ++ (Warning Tips, Documentation Tips, Comment Tips): ++ * internals.texi (Memory Usage): Improve indexing. ++ ++ * variables.texi (Frame-Local Variables): ++ * functions.texi (Argument List): ++ * loading.texi (Library Search): ++ * streams.texi (Output Variables): ++ * keymaps.texi (Translation Keymaps, Searching Keymaps): ++ * searching.texi (Replacing Match, Search and Replace): ++ * processes.texi (Byte Packing, Decoding Output) ++ (Accepting Output, Network Servers, Shell Arguments): ++ * display.texi (Abstract Display, Image Cache, Scroll Bars): ++ * windows.texi (Window Point, Window Start): ++ * frames.texi (Management Parameters, Frame Parameters, Frame Titles): ++ * commands.texi (Reading Input, Keyboard Events): ++ * minibuf.texi (Reading File Names, Minibuffer Completion) ++ (Recursive Mini): ++ * positions.texi (List Motion): ++ * hash.texi (Hash Tables, Creating Hash, Defining Hash): ++ * numbers.texi (Arithmetic Operations, Math Functions) ++ (Predicates on Numbers, Comparison of Numbers): ++ (Numeric Conversions): ++ * locals.texi (Standard Buffer-Local Variables): ++ * maps.texi (Standard Keymaps): ++ * os.texi (User Identification, System Environment, Recording Input) ++ (X11 Keysyms): ++ * nonascii.texi (Non-ASCII Characters, Splitting Characters): ++ * backups.texi (Backups and Auto-Saving): ++ * customize.texi (Customization, Group Definitions) ++ (Variable Definitions): ++ * compile.texi (Byte Compilation): Improve index entries. ++ ++2007-03-31 Karl Berry ++ ++ * macros.texi (Defining Macros): Avoid widow syllable. ++ ++2007-03-31 Eli Zaretskii ++ ++ * elisp.texi (Top): Postscript -> PostScript. ++ ++ * display.texi (Images, Postscript Images): Postscript -> PostScript. ++ ++2007-03-31 Markus Triska ++ ++ * internals.texi (Writing Emacs Primitives): Untabify `For'. ++ ++2007-03-30 Karl Berry ++ ++ * lists.texi (List-related Predicates): Remove spurious @need. ++ (Setcdr): Use @smallexample to improve page break. ++ (Association Lists) : Reword to improve page break. ++ ++ * strings.texi (String Conversion): Insert blank line to improve ++ page break. ++ ++ * numbers.texi (Random Numbers): Use @minus{}. ++ (Math Functions): Use @minus{}. ++ ++ * intro.texi (Acknowledgements): Avoid line breaks before middle ++ initials. ++ ++2007-03-24 Eli Zaretskii ++ ++ * errors.texi (Standard Errors): Add an index entry. ++ ++2007-03-19 Richard Stallman ++ ++ * os.texi (Recording Input): recent-keys now gives 300 keys. ++ ++2007-03-12 Glenn Morris ++ ++ * os.texi: Replace "daylight savings" with "daylight saving" ++ throughout. ++ ++2007-03-05 Richard Stallman ++ ++ * variables.texi (File Local Variables): Update ++ enable-local-variables values. ++ ++2007-03-04 Richard Stallman ++ ++ * syntax.texi (Control Parsing): Minor clarification. ++ ++ * strings.texi (Formatting Strings): Clarify width, precision, flags. ++ ++ * sequences.texi (Sequence Functions): Move string-bytes away, ++ add xref. ++ ++ * nonascii.texi (Text Representations): Move string-bytes here. ++ ++ * modes.texi (Major Mode Conventions): Fundamental mode is exception. ++ ++ * minibuf.texi (Basic Completion): Minor clarification. ++ ++ * markers.texi (The Mark): Clarify existence vs activation of mark. ++ Other cleanup. ++ ++ * display.texi (Finding Overlays): Write better example. ++ ++ * compile.texi (Eval During Compile): Clarify putting macros ++ in eval-when-compile. ++ ++2007-02-25 Vinicius Jose Latorre (tiny change) ++ ++ * loading.texi (How Programs Do Loading): Fix anchor position at ++ load-read-function definition doc. ++ ++2007-02-21 Kim F. Storm ++ ++ * strings.texi (Text Comparison): Mention that assoc-string ++ converts symbols to strings before testing. ++ ++2007-02-17 Kim F. Storm ++ ++ * processes.texi (Bindat Spec): Vector types can have optional ++ element type. ++ (Bindat Examples): Fix example. Add vector with element type. ++ ++2007-02-16 Andreas Schwab ++ ++ * strings.texi (Formatting Strings): Document '+' flag. ++ ++2007-02-15 Juanma Barranquero ++ ++ * strings.texi (Modifying Strings): Clarify that `clear-string' ++ always converts the string to unibyte. ++ ++2007-02-14 Kim F. Storm ++ ++ * display.texi (Glyphs): Add make-glyph-code, glyph-char, glyph-face. ++ Rewrite glyph code description to refer to these functions. ++ Remove details of encoding face number and char into integer code. ++ ++2007-02-03 Alan Mackenzie ++ ++ * loading.texi (Hooks for Loading): Make the description of ++ `eval-after-load' more detailed, and amend the description of ++ after-load-alist, in accordance with changes from 2006-05. ++ ++2007-02-03 Chong Yidong ++ ++ * modes.texi (Defining Minor Modes): Document that a :require ++ keyword or similar may be required to make saved customization ++ variables work. ++ ++2007-02-03 Eli Zaretskii ++ ++ * elisp.texi (Top): Make the detailed menu headers compliant with ++ Texinfo guidelines and with what texnfo-upd.el expects. Add ++ comments to prevent people from inadvertently modifying the key ++ parts needed by `texinfo-multiple-files-update'. ++ ++2007-02-02 Eli Zaretskii ++ ++ * elisp.texi (Top): Update the top-level menus. ++ ++ * syntax.texi (Categories): Add index entries. ++ ++2007-02-01 Juanma Barranquero ++ ++ * display.texi (Attribute Functions): Fix name and description of ++ the UNDERLINE arg of `set-face-underline-p'. ++ ++2007-01-29 Eli Zaretskii ++ ++ * elisp.texi (Top): Add "Standard Errors", "Standard Buffer-Local ++ Variables", and "Standard Keymaps" to the detailed menu. ++ ++ * variables.texi (Future Local Variables): Add index entry. ++ ++2007-01-28 Richard Stallman ++ ++ * tips.texi (Coding Conventions): Clarify the tip about macros ++ that define a function or a variable. ++ ++ * files.texi (File Attributes): UID and GID can be floats. ++ (Magic File Names): Explain why deferring all operations to ++ the standard handler does not work. ++ ++2007-01-23 Martin Rudalics ++ ++ * backups.texi (Reverting): Use "buffer" instead of "file" ++ when talking about major and minor modes. ++ ++2007-01-21 Richard Stallman ++ ++ * help.texi (Documentation): Add xref to Documentation Tips. ++ ++2007-01-14 Juanma Barranquero ++ ++ * tips.texi (Coding Conventions): Fix typos. ++ ++2007-01-05 Richard Stallman ++ ++ * modes.texi (Defining Minor Modes): Fix previous change. ++ ++2007-01-03 Richard Stallman ++ ++ * customize.texi (Variable Definitions, Customization Types): ++ Don't use * in doc string for defcustom. ++ ++2007-01-02 Richard Stallman ++ ++ * variables.texi (Variable Aliases): Clarify that aliases vars ++ always have the same value. ++ ++ * processes.texi (Bindat Spec): Fix Texinfo usage. ++ ++ * modes.texi (Defining Minor Modes): Explain effect of command ++ defined with define-global-minor-mode on new buffers. ++ ++2006-12-30 Kim F. Storm ++ ++ * keymaps.texi (Tool Bar): Describe `grow-only' value of ++ `auto-resize-tool-bars'. ++ ++2006-12-30 Richard Stallman ++ ++ * keymaps.texi (Active Keymaps): Fix previous change. ++ ++2006-12-30 Nick Roberts ++ ++ * keymaps.texi (Active Keymaps): Make xref to lookup-key. ++ ++2006-12-30 Kim F. Storm ++ ++ * processes.texi (Bindat Spec): Clarify using field names in ++ length specifications. ++ ++2006-12-29 Kim F. Storm ++ ++ * processes.texi (Bindat Spec): Explain eval forms and lengths better. ++ Add count and index variables for eval forms in repeat blocks. ++ ++2006-12-24 Richard Stallman ++ ++ * customize.texi (Variable Definitions): Document ++ new name custom-add-frequent-value. ++ ++2006-12-19 Kim F. Storm ++ ++ * commands.texi (Misc Events): User signals now result in sigusr1 ++ and sigusr2 events which are handled through special-event-map. ++ (Special Events): User signals and drag-n-drop are special. ++ ++2006-12-17 Richard Stallman ++ ++ * loading.texi (Named Features): Explain subfeatures better. ++ ++ * customize.texi: Use "option" only for user options. ++ For the keyword values inside defcustom etc, say "keywords". ++ For :options value's elements, say "elements". ++ :group should not be omitted. ++ ++ * syntax.texi (Parsing Expressions): Split up node. ++ (Motion via Parsing, Position Parse, Parser State) ++ (Low-Level Parsing, Control Parsing): New subnodes. ++ (Parser State): Document syntax-ppss-toplevel-pos. ++ ++ * positions.texi (List Motion): Punctuation fix. ++ ++ * files.texi (File Name Completion): Document PREDICATE arg ++ to file-name-completion. ++ ++2006-12-16 Eli Zaretskii ++ ++ * internals.texi (Building Emacs, Writing Emacs Primitives): ++ Add index entries. ++ ++2006-12-11 Richard Stallman ++ ++ * modes.texi (Font Lock Basics): Explain how nil for font-lock-defaults ++ affects face menu. Explain how to make it non-nil without enabling ++ any fontification. ++ ++2006-12-10 Chong Yidong ++ ++ * modes.texi (Font Lock Basics): Document nil value of ++ font-lock-defaults. ++ ++2006-12-10 Glenn Morris ++ ++ * abbrevs.texi (Defining Abbrevs): Mention `define-abbrev' 'force ++ value for system-flag argument. Abbrev tables may not be empty ++ when major modes are loaded. ++ ++2006-12-08 Juanma Barranquero ++ ++ * makefile.w32-in (maintainer-clean): Partially revert last ++ change; delete "elisp-?" and "elisp-??" instead of "elisp-*" ++ to protect elisp-covers.texi. ++ ++2006-12-07 Juanma Barranquero ++ ++ * makefile.w32-in (maintainer-clean): Depend on `distclean'. ++ Don't remove elisp* info files; they are already deleted by the ++ `clean' and `distclean' targets, and they are in the $(infodir) ++ directory, not the current one. ++ ++2006-12-04 Kim F. Storm ++ ++ * commands.texi (Misc Events): Update signal events. ++ (Event Examples): Add signal example. ++ ++2006-11-29 Richard Stallman ++ ++ * frames.texi (Visibility of Frames): Explain visible windows ++ can be covered by others. Add xref for raise-frame. ++ ++2006-11-28 Richard Stallman ++ ++ * searching.texi (Regexp Special): Update when ^ is special. ++ ++2006-11-27 Eli Zaretskii ++ ++ * customize.texi (Customization, Common Keywords) ++ (Group Definitions, Variable Definitions, Composite Types) ++ (Type Keywords, Customization Types): Add index entries for ++ various customization keywords. ++ ++2006-11-23 Stefan Monnier ++ ++ * modes.texi (Multiline Font Lock): Rephrase some parts for clarity. ++ ++2006-11-10 Jan Djärv ++ ++ * frames.texi (Window System Selections): Remove clipboard from ++ description of selection-coding-system. ++ ++2006-11-06 Richard Stallman ++ ++ * lists.texi (List Variables): Document COMPARE-FN. ++ ++ * keymaps.texi: Avoid use of "binding" to mean a relation; ++ use it only to refer to the meaning associated with a key. ++ (Keymaps): Change menu node description. ++ ++ * elisp.texi (Top): Change menu node description. ++ ++ * display.texi (Managing Overlays): Document overlay-recenter. ++ ++2006-10-29 Chong Yidong ++ ++ * Makefile.in: Use relative paths to avoid advertising filesystem ++ contents during compilation. ++ ++2006-10-23 Kim F. Storm ++ ++ * commands.texi (Event Input Misc): Update unread-command-events. ++ ++2006-10-23 Nick Roberts ++ ++ * lists.texi (Sets And Lists): Fix typos. ++ ++2006-10-18 Juanma Barranquero ++ ++ * control.texi (Processing of Errors): Use @var for an argument, ++ not @code. ++ ++2006-10-16 Richard Stallman ++ ++ * edebug.texi (Edebug Recursive Edit): Minor cleanup. ++ ++ * keymaps.texi (Format of Keymaps): Show all the keymap element ++ patterns that result from menu items. ++ (Key Lookup): Minor cleanups. ++ ++ * modes.texi (Precalculated Fontification): Don't say that ++ not setting font-lock-defaults avoids loading font-lock. ++ ++ * help.texi (Documentation): Move xref to Emacs Manual here. ++ (Documentation Basics): From here. ++ Also doc emacs-lisp-docstring-fill-column. ++ ++ * elisp.texi: Update version and ISBN. ++ ++ * commands.texi (Interactive Call): Clarify KEYS arg to ++ call-interactively is a vector. ++ (Command Loop Info): Delete anchor in this-command-keys. ++ Add anchor in this-command-keys-vector. ++ (Recursive Editing): Document how recursive-edit ++ handles the current buffer. ++ ++2006-10-13 Chong Yidong ++ ++ * frames.texi (Frame Titles): %c and %l are ignored in ++ frame-title-format. ++ ++2006-10-11 Richard Stallman ++ ++ * keymaps.texi (Key Sequences): Clarify use of kbd. ++ ++2006-10-10 Kim F. Storm ++ ++ * lists.texi (Sets And Lists): Add memql. ++ ++2006-10-03 Richard Stallman ++ ++ * searching.texi (Char Classes): Document :multibyte: and :unibyte:. ++ Clarify :ascii: and :nonascii:. ++ ++2006-09-29 Juri Linkov ++ ++ * modes.texi (%-Constructs): Reorder coding systems in the ++ documentation of %z to the real order displayed in the modeline. ++ ++2006-09-25 Richard Stallman ++ ++ * os.texi (Timers): Describe timer-max-repeats. ++ ++2006-09-25 Chong Yidong ++ ++ * os.texi (Timers): Mention with-local-quit. ++ ++2006-09-24 Richard Stallman ++ ++ * searching.texi (Searching and Matching): Mention property search. ++ ++ * commands.texi (Command Loop Info): Explain how read-event affects ++ this-command-keys. ++ ++2006-09-20 Richard Stallman ++ ++ * os.texi (Timers): Clarify about REPEAT when timer is delayed. ++ ++ * windows.texi (Window Start): Minor cleanups. ++ ++2006-09-20 Kim F. Storm ++ ++ * windows.texi (Window Start): pos-visible-in-window-p allows ++ specifying t for position to mean "end of window". ++ Add window-line-height. ++ ++ * anti.texi (Antinews): Mention window-line-height. ++ ++2006-09-19 David Kastrup ++ ++ * keymaps.texi (Searching Keymaps): Small clarification. ++ ++2006-09-18 Richard Stallman ++ ++ * keymaps.texi (Creating Keymaps): Explain that keymap prompt strings ++ cause keyboard menus. ++ (Menu Keymaps): Likewise. ++ (Defining Menus, Keyboard Menus): Clarify. ++ ++ * text.texi (Fields): Clarify explanation of constrain-to-field. ++ ++2006-09-16 Eli Zaretskii ++ ++ * variables.texi (Tips for Defining): Fix a typo. ++ ++2006-09-15 Richard Stallman ++ ++ * keymaps.texi (Remapping Commands, Searching Keymaps) ++ (Active Keymaps): Clean up previous change. ++ ++2006-09-15 Jay Belanger ++ ++ * gpl.texi: Replace "Library Public License" by "Lesser Public ++ License" throughout. ++ ++2006-09-15 David Kastrup ++ ++ * keymaps.texi (Active Keymaps): Adapt description to use ++ `get-char-property' instead `get-text-property'. Explain how ++ mouse events change this. Explain the new optional argument of ++ `key-binding' and its mouse-dependent lookup. ++ (Searching Keymaps): Adapt description similarly. ++ (Remapping Commands): Explain the new optional argument of ++ `command-remapping'. ++ ++2006-09-14 Richard Stallman ++ ++ * keymaps.texi (Searching Keymaps): Clarification. ++ (Active Keymaps): Refer to Searching Keymaps instead of duplication. ++ ++2006-09-13 Richard Stallman ++ ++ * objects.texi (Character Type): Node split. ++ Add xref to Describing Characters. ++ (Basic Char Syntax, General Escape Syntax) ++ (Ctl-Char Syntax, Meta-Char Syntax): New subnodes. ++ ++2006-09-11 Richard Stallman ++ ++ * display.texi (Display Table Format): Wording clarification. ++ (Glyphs): Clarifications. ++ ++2006-09-10 Chong Yidong ++ ++ * keymaps.texi (Active Keymaps): Mention that key-binding checks ++ local maps. ++ ++2006-09-10 Kim F. Storm ++ ++ * display.texi (Forcing Redisplay): Document return value of ++ function redisplay. ++ ++2006-09-09 Richard Stallman ++ ++ * windows.texi (Window Hooks): Explain limits of ++ window-scroll-functions. ++ ++ * display.texi (Fringe Indicators): Update for last change in ++ indicate-buffer-boundaries. ++ ++2006-09-08 Richard Stallman ++ ++ * processes.texi (Bindat Spec): Suggest names ending in -bindat-spec. ++ ++2006-09-06 Kim F. Storm ++ ++ * frames.texi (Display Feature Testing): display-mm-dimensions-alist. ++ ++ * windows.texi (Window Start): Update pos-visible-in-window-p. ++ ++2006-09-04 Richard Stallman ++ ++ * processes.texi (Accepting Output): Explain SECONDS=0 for ++ accept-process-output. ++ ++ * os.texi (Idle Timers): Explain why timer functions should not ++ loop until (input-pending-p). ++ ++2006-09-02 Eli Zaretskii ++ ++ * makefile.w32-in (usermanualdir): New variable. ++ (elisp.dvi): Use it. ++ ++2006-09-01 Eli Zaretskii ++ ++ * buffers.texi (Buffer Modification): Fix last change. ++ ++2006-09-01 Chong Yidong ++ ++ * buffers.texi (Buffer Modification): Document ++ buffer-chars-modified-tick. ++ ++2006-08-31 Richard Stallman ++ ++ * modes.texi (Syntactic Font Lock): Mention specific faces once again. ++ ++2006-08-31 Richard Bielawski (tiny change) ++ ++ * modes.texi (Syntactic Font Lock): ++ Mention font-lock-syntactic-face-function ++ instead of specific faces. ++ ++2006-08-29 Chong Yidong ++ ++ * display.texi (Images): Add xrref to display-images-p. ++ ++2006-08-28 Kenichi Handa ++ ++ * nonascii.texi (Lisp and Coding Systems): Fix description of ++ detect-coding-region. ++ ++2006-08-27 Michael Olson ++ ++ * processes.texi (Transaction Queues): Remove stray quote ++ character. ++ ++2006-08-25 Richard Stallman ++ ++ * os.texi (Idle Timers): run-with-idle-timer allows Lisp time value. ++ Add xref. ++ ++2006-08-24 Chong Yidong ++ ++ * os.texi (Timers): Avoid waiting inside timers. ++ ++2006-08-21 Lute Kamstra ++ ++ * Makefile.in: Use ../man/texinfo.tex to build elisp.dvi. ++ ++2006-08-20 Richard Stallman ++ ++ * os.texi (Idle Timers): New node, split out from Timers. ++ Document current-idle-time. ++ * commands.texi (Reading One Event): Update xref. ++ * elisp.texi (Top): Update subnode menu. ++ ++2006-08-16 Richard Stallman ++ ++ * keymaps.texi (Extended Menu Items): Show format of cached ++ bindings in extended menu items. ++ ++ * customize.texi (Variable Definitions): Explain when the ++ standard value expression is evaluated. ++ ++2006-08-15 Chong Yidong ++ ++ * commands.texi (Reading One Event): Explain idleness in ++ `read-event'. ++ ++2006-08-12 Chong Yidong ++ ++ * text.texi (Near Point): Say "cursor" not "terminal cursor". ++ (Commands for Insertion): Removed split-line since it's not ++ relevant for Lisp programming. ++ (Yank Commands): Rewrite introduction. ++ (Undo): Clarify. ++ (Maintaining Undo): Clarify. Document undo-ask-before-discard. ++ (Filling): Remove redundant comment. Clarify return value of ++ current-justification. ++ (Margins): Minor clarifications. ++ (Adaptive Fill): Update default value of adaptive-fill-regexp. ++ (Sorting): Update definition of sort-lines. ++ (Columns): Clarify behavior of sort-columns. ++ (Indent Tabs): Link to Tab Stops in Emacs manual. ++ (Special Properties): Clarify. ++ (Clickable Text): Mention Buttons package. ++ ++2006-08-12 Kevin Ryde ++ ++ * os.texi (Time Parsing): Add %z to description of ++ format-time-string, as per docstring. Add cross reference to ++ glibc manual for strftime. ++ ++2006-08-08 Richard Stallman ++ ++ * modes.texi: Clean up wording in previous change. ++ ++2006-08-07 Chong Yidong ++ ++ * modes.texi (Hooks): Clarify. ++ (Major Mode Basics): Mention define-derived-mode explicitly. ++ (Major Mode Conventions): Rebinding RET is OK for some modes. ++ Mention change-major-mode-hook and after-change-major-mode-hook. ++ (Example Major Modes): Moved to end of Modes section. ++ (Mode Line Basics): Clarify. ++ (Mode Line Data): Mention help-echo and local-map in strings. ++ Explain reason for treatment of non-risky variables. ++ (Properties in Mode): Clarify. ++ (Faces for Font Lock): Add font-lock-negation-char-face. ++ ++2006-08-04 Eli Zaretskii ++ ++ * strings.texi (Formatting Strings): Warn against arbitrary ++ strings as first arg to `format'. ++ ++2006-07-31 Thien-Thi Nguyen ++ ++ * text.texi (Clickable Text): Mention `help-echo' text property. ++ Update intro, examples and associated explanations. ++ ++2006-07-31 Richard Stallman ++ ++ * commands.texi: Update xrefs. ++ (Event Mod): New node, cut out from old Translating Input. ++ ++ * maps.texi: Update xrefs. ++ ++ * keymaps.texi (Translation Keymaps): New node. ++ Update xrefs from Translating Input to Translation Keymaps. ++ ++ * elisp.texi (Top): Update subnode menu. ++ ++ * display.texi (Face Functions): Fix explanations of FRAME=t or nil. ++ ++ * os.texi (System Interface): Fix menu descriptions of some nodes. ++ (Translating Input): Node deleted. ++ ++2006-07-31 Nick Roberts ++ ++ * modes.texi (Minor Mode Conventions): Update xref for add-to-list. ++ ++ * lists.texi (Sets And Lists): Likewise. ++ ++2006-07-30 Thien-Thi Nguyen ++ ++ * text.texi (Fields): Mention POS ++ requirement when narrowing is in effect. ++ ++2006-07-28 Richard Stallman ++ ++ * display.texi (Face Attributes): Simplify wording. ++ (Attribute Functions): Clarify meaning of new-frame default ++ attribute settings. ++ ++ * customize.texi (Common Keywords): Document how to use ++ :package-version in a package not in Emacs. ++ ++2006-07-28 Kim F. Storm ++ ++ * commands.texi (Reading One Event): Fix last change. ++ ++2006-07-26 Chong Yidong ++ ++ * commands.texi (Reading One Event): Document SECONDS argument for ++ read-event, read-char, and read-char-exclusive. ++ ++2006-07-25 Stefan Monnier ++ ++ * modes.texi (Multiline Font Lock): Can't use jit-lock-defer-multiline ++ to ensure correct identification. ++ ++2006-07-24 Richard Stallman ++ ++ * text.texi (Clickable Text): Clarify. ++ ++ * sequences.texi (Vector Functions): Delete duplicate xref. ++ ++ * objects.texi (Function Type): Clarify. ++ ++ * modes.texi (Keymaps and Minor Modes): List punct chars for minor ++ modes. ++ ++ * lists.texi (List Variables): New node. ++ Material moved from other nodes. ++ ++ * variables.texi (Setting Variables): add-to-list and ++ add-to-ordered-list moved to List Variables node. ++ ++2006-07-23 Thien-Thi Nguyen ++ ++ * text.texi (Links and Mouse-1): ++ For mouse-on-link-p, expand on arg POS. ++ ++2006-07-21 Kim F. Storm ++ ++ * display.texi (Forcing Redisplay): Don't mention systems which ++ don't support sub-second timers for redisplay-preemption-period. ++ ++ * os.texi (Terminal Output): Clarify text vs graphical terminal. ++ ++2006-07-21 Eli Zaretskii ++ ++ * frames.texi (Input Focus): Document that focus-follows-mouse has ++ no effect on MS-Windows. ++ ++2006-07-18 Richard Stallman ++ ++ * display.texi (Forcing Redisplay): Cleanups in previous change. ++ ++ * processes.texi (Low-Level Network): Make menu more convenient. ++ ++2006-07-18 Kim F. Storm ++ ++ * display.texi (Forcing Redisplay): redisplay-preemption-period ++ only used on window systems. Add xref to Terminal Output. ++ ++ * os.texi (Terminal Output): baud-rate only controls preemption on ++ non-window systems. Add xref to Forcing Redisplay. ++ ++ * processes.texi (Low-Level Network): Rename node "Make Network" ++ to "Network Processes". ++ ++2006-07-18 Karl Berry ++ ++ * variables.texi, functions.texi, customize.texi, loading.texi: ++ * edebug.texi, minibuf.texi: Fix page breaks through chapter 20. ++ ++2006-07-17 Chong Yidong ++ ++ * commands.texi (Waiting): Document batch-mode sit-for behavior. ++ ++2006-07-17 Richard Stallman ++ ++ * eval.texi, elisp.texi, text.texi: Use real doublequote inside menus. ++ Put period and comma inside quotes. ++ ++ * loading.texi, markers.texi: Use real doublequote inside menus. ++ ++ * windows.texi: Put point and comma inside quotes. ++ (Textual Scrolling): Use @samp for error message. ++ ++ * variables.texi, tips.texi, syntax.texi, symbols.texi: ++ * strings.texi, streams.texi, processes.texi, os.texi: ++ * objects.texi, numbers.texi, modes.texi, minibuf.texi: ++ * lists.texi, keymaps.texi, intro.texi, hash.texi, internals.texi: ++ * gpl.texi, functions.texi, files.texi, frames.texi, doclicense.texi: ++ * display.texi, control.texi, commands.texi, buffers.texi, anti.texi: ++ Put point and comma inside quotes. ++ ++ * control.texi (Processing of Errors): Add command-error-function. ++ ++ * variables.texi (File Local Variables): Clarify that ++ file local variables make buffer-local bindings. ++ ++ * modes.texi (Syntactic Font Lock): Give default for ++ font-lock-syntax-table. ++ ++2006-07-17 Nick Roberts ++ ++ * text.texi (Special Properties): Clean up previous change. ++ ++2006-07-16 Karl Berry ++ ++ * objects.texi, numbers.texi, strings.texi, lists.texi, hash.texi: ++ * control.texi: Fix bad page breaks through chapter 10 (control). ++ ++ * anti.texi (Antinews): Reorder face-attribute fns to avoid ++ underfull hbox. ++ ++2006-07-15 Nick Roberts ++ ++ * text.texi (Special Properties): Describe fontified text property ++ in relation to a character (not text). ++ ++2006-07-15 Kim F. Storm ++ ++ * maps.texi (Standard Keymaps): Add xref for minibuffer maps. ++ Add apropos-mode-map, custom-mode-map, esc-map, global-map, ++ grep-mode-map, help-map, help-mode-map, kmacro-map, and tool-bar-map. ++ ++ * anti.texi (Antinews): Mention redisplay function. ++ The kbd macro existed, but was not documented, before 22.x. ++ Function pos-visible-in-window-p is not new in 22.x, just enhanced. ++ ++2006-07-14 Nick Roberts ++ ++ * display.texi (Displaying Messages): Add anchor. ++ ++ * frames.texi (Dialog Boxes): Use it. ++ ++2006-07-12 Richard Stallman ++ ++ * objects.texi (Frame Type): Explain nature of frames better. ++ ++ * frames.texi (Frames): Explain nature of frames better. ++ ++2006-07-12 Ken Manheimer ++ ++ * tips.texi (Coding Conventions): Explain why use cl at compile time. ++ ++2006-07-12 YAMAMOTO Mitsuharu ++ ++ * frames.texi (Window System Selections): Mention scrap support for Mac. ++ Default value of x-select-enable-clipboard is t on Mac. ++ ++ * os.texi (Getting Out): Suspending is not allowed on Mac, either. ++ ++2006-07-11 Kim F. Storm ++ ++ * display.texi (Forcing Redisplay): Add `redisplay' function. ++ Don't mention (sit-for -1) -- use (redisplay t) instead. ++ ++ * commands.texi (Waiting): (sit-for -1) is no longer special. ++ (sit-for 0) is equivalent to (redisplay). ++ Iconifying/deiconifying no longer makes sit-for return. ++ ++2006-07-10 Nick Roberts ++ ++ * display.texi (Buttons): Fix typo. ++ ++ * index.texi, elisp.texi (New Symbols): Comment node out. ++ ++2006-07-09 Richard Stallman ++ ++ * display.texi (Truncation): Clean up previous change. ++ ++2006-07-08 Richard Stallman ++ ++ * commands.texi (Interactive Call): Use 3 as prefix in example ++ for execute-extended-command. ++ ++ * display.texi (Attribute Functions): Move paragraph about ++ compatibility with Emacs < 21. ++ ++2006-07-09 Kim F. Storm ++ ++ * display.texi (Refresh Screen): Clarify force-window-update. ++ (Truncation): "Normally" indicated by fringe arrows. ++ ++2006-07-08 Eli Zaretskii ++ ++ * windows.texi (Textual Scrolling, Resizing Windows): ++ * variables.texi (Constant Variables): ++ * text.texi (Buffer Contents, Deletion, Changing Properties) ++ (Property Search, Special Properties, Sticky Properties) ++ (Links and Mouse-1, Fields, Change Hooks): ++ * syntax.texi (Syntax Table Functions, Parsing Expressions) ++ (Categories): ++ * symbols.texi (Other Plists): ++ * streams.texi (Output Variables): ++ * processes.texi (Input to Processes, Query Before Exit): ++ * positions.texi (Word Motion, Text Lines, List Motion): ++ * os.texi (Init File, System Environment, Sound Output) ++ (Session Management): ++ * nonascii.texi (Text Representations, Character Sets) ++ (Chars and Bytes, Locales): ++ * modes.texi (Defining Minor Modes, Header Lines): ++ * minibuf.texi (Minibuffer Contents): ++ * markers.texi (Information from Markers): ++ * lists.texi (List Elements, Building Lists, Association Lists): ++ * keymaps.texi (Tool Bar): ++ * hash.texi (Creating Hash, Hash Access, Defining Hash, Other Hash): ++ * functions.texi (What Is a Function, Mapping Functions): ++ * frames.texi (Creating Frames, Parameter Access, Pointer Shape) ++ (Color Names, Text Terminal Colors, Display Feature Testing): ++ * files.texi (Visiting Functions, File Name Components) ++ (Unique File Names, Contents of Directories): ++ * display.texi (Forcing Redisplay, Displaying Messages) ++ (Temporary Displays, Font Selection, Auto Faces) ++ (Font Lookup, Fringe Indicators, Display Margins) ++ (Image Descriptors, Showing Images, Image Cache, Button Types) ++ (Making Buttons, Manipulating Buttons, Button Buffer Commands) ++ (Display Table Format, Glyphs): ++ * control.texi (Iteration): ++ * commands.texi (Command Loop Info, Adjusting Point): ++ * backups.texi (Making Backups, Auto-Saving): ++ Remove @tindex entries. ++ ++2006-07-07 Kim F. Storm ++ ++ * display.texi (Fringe Cursors): Fix typo. ++ (Customizing Bitmaps): Fix define-fringe-bitmap entry. ++ (Overlay Arrow): Default is overlay-arrow fringe indicator. ++ ++2006-07-05 Richard Stallman ++ ++ * text.texi (Buffer Contents): Add example of text props ++ in result of buffer-substring. ++ (Text Properties): Explain better about use of specific property names. ++ (Property Search): Some cleanups; reorder some functions. ++ ++ * keymaps.texi (Changing Key Bindings): Cleanup. ++ Add xref to Key Binding Conventions. ++ ++ * display.texi (Attribute Functions): Add examples for ++ face-attribute-relative-p. ++ ++ * tips.texi (Coding Conventions): Cleanup last change. ++ ++2006-07-05 Karl Berry ++ ++ * elisp.texi: Use @fonttextsize 10pt, a la emacs.texi. ++ Remove @setchapternewpage odd. ++ Result is 1013 pages, down from 1100. ++ ++ * anti.texi, customize.texi, display.texi, internals.texi: ++ * minibuf.texi, modes.texi, tips.texi: ++ Fix overfull/underfull boxes. ++ ++2006-07-05 Thien-Thi Nguyen ++ ++ * edebug.texi (Instrumenting): ++ Add Edebug-specific findex for eval-buffer. ++ * loading.texi (Loading): ++ Replace eval-current-buffer with eval-buffer. ++ ++2006-06-30 Nick Roberts ++ ++ * locals.texi (Standard Buffer-Local Variables): Update the list ++ of variables. ++ ++2006-06-26 Nick Roberts ++ ++ * files.texi (File Name Completion): Point user to the node ++ "Reading File Names". ++ ++2006-06-24 Eli Zaretskii ++ ++ * files.texi (Contents of Directories): Document case-insensitive ++ behavior on respective filesystems. ++ ++ * objects.texi (Character Type): Document that Emacs signals an ++ error for unsupported Unicode characters specified as \uNNNN. ++ ++2006-06-19 Richard Stallman ++ ++ * processes.texi (Bindat Spec): Clarify previous change. ++ ++2006-06-16 Richard Stallman ++ ++ * tips.texi (Coding Conventions): Better explain conventions ++ for definition constructs. ++ ++ * text.texi (Special Properties): String value of `read-only' ++ serves as the error message. ++ ++ * objects.texi (Character Type): Clarify prev. change. ++ (Non-ASCII in Strings): Mention \u and \U. ++ ++ * commands.texi (Using Interactive): Explain problem of ++ markers, etc., in command-history. ++ ++2006-06-14 Kim F. Storm ++ ++ * commands.texi (Waiting): Negative arg to sit-for forces ++ redisplay even if input is pending. ++ ++ * display.texi (Forcing Redisplay): Use (sit-for -1) to force a ++ redisplay. Remove incorrect example of binding redisplay-dont-pause ++ around (sit-for 0). ++ ++2006-06-13 Richard Stallman ++ ++ * display.texi (Forcing Redisplay): Clarify previous change. ++ ++2006-06-13 Romain Francoise ++ ++ * display.texi (Forcing Redisplay): Fix typo. ++ ++2006-06-13 Kim F. Storm ++ ++ * display.texi (Forcing Redisplay): Add redisplay-preemption-period. ++ ++2006-06-10 Luc Teirlinck ++ ++ * tips.texi (Coding Conventions): Add `@end itemize'. ++ ++2006-06-10 Richard Stallman ++ ++ * tips.texi (Coding Conventions): Explain use of coding systems ++ to ensure one decoding for strings. ++ ++2006-06-09 Aidan Kehoe ++ ++ * objects.texi (Character Type): Describe the \uABCD and \U00ABCDEF ++ syntax. ++ ++2006-06-07 Eli Zaretskii ++ ++ * display.texi (Font Selection): Remove description of ++ clear-face-cache. ++ ++ * compile.texi (Eval During Compile): Fix a typo. Add index ++ entries for possible uses of eval-when-compile. ++ ++2006-06-04 Thien-Thi Nguyen ++ ++ * display.texi (Abstract Display): Fix typo. ++ ++2006-06-03 Eli Zaretskii ++ ++ * minibuf.texi (Minibuffer History) : ++ Reword variable's description. ++ ++2006-06-01 Richard Stallman ++ ++ * windows.texi (Splitting Windows): Clarify splitting nonselected ++ window. ++ ++2006-05-31 Juri Linkov ++ ++ * minibuf.texi (Minibuffer History): Add history-add-new-input. ++ ++2006-05-30 Richard Stallman ++ ++ * display.texi (Line Height): Fix errors in description of ++ default line height and line-height property. ++ ++ * nonascii.texi (Default Coding Systems): Further clarification. ++ ++2006-05-29 Luc Teirlinck ++ ++ * internals.texi (Pure Storage): Mention that an overflow in pure ++ space causes a memory leak. ++ (Garbage Collection): If there was an overflow in pure space, ++ `garbage-collect' returns nil. ++ ++2006-05-30 Eli Zaretskii ++ ++ * nonascii.texi (Default Coding Systems): Fix it some more. ++ ++2006-05-29 Eli Zaretskii ++ ++ * nonascii.texi (Default Coding Systems): Fix last change. ++ ++2006-05-29 Kenichi Handa ++ ++ * nonascii.texi (find-operation-coding-system): Describe the new ++ argument format (FILENAME . BUFFER). ++ ++2006-05-28 Richard Stallman ++ ++ * tips.texi (Coding Conventions): Better explain reasons not to ++ advise other packages or use `eval-after-load'. ++ ++2006-05-29 Kim F. Storm ++ ++ * processes.texi (Bindat Functions): Rename `pos' and `raw-data' to ++ `bindat-idx' and `bindat-raw' for clarity. ++ ++2006-05-27 Thien-Thi Nguyen ++ ++ * processes.texi (Bindat Spec): Expand on `repeat' handler. ++ ++ * display.texi (Display): Add "Abstract Display" to menu. ++ (Abstract Display, Abstract Display Functions) ++ (Abstract Display Example): New nodes. ++ * elisp.texi (Top): Add "Abstract Display" to menu. ++ ++2006-05-27 Chong Yidong ++ ++ * keymaps.texi (Key Sequences): Link to input events definition. ++ (Format of Keymaps): Delete material duplicated in Keymap Basics. ++ ++ * files.texi (Changing Files): Document updated argument list for ++ copy-file. ++ ++2006-05-27 Thien-Thi Nguyen ++ ++ * processes.texi (Bindat Functions): Explain term "total length". ++ Use it in bindat-length and bindat-pack descriptions. ++ ++2006-05-26 Eli Zaretskii ++ ++ * tips.texi (Coding Conventions): Advise against using ++ eval-after-load in packages. Add an index entry. ++ ++2006-05-25 Juri Linkov ++ ++ * minibuf.texi (Text from Minibuffer): Undocument keep-all. ++ ++ * modes.texi (%-Constructs): Add %e, %z, %Z. ++ ++2006-05-25 Richard Stallman ++ ++ * elisp.texi (Top): Update subnode menu. ++ ++ * keymaps.texi (Keymap Basics): New node, split out of Key Sequences. ++ (Keymaps): Update menu. ++ ++2006-05-25 Chong Yidong ++ ++ * keymaps.texi (Key Sequences): Some clarifications. ++ ++2006-05-25 Thien-Thi Nguyen ++ ++ * processes.texi (Bindat Functions): Say "unibyte string" ++ explicitly for bindat-unpack and bindat-pack descriptions. ++ (Bindat Examples): Don't call `string-make-unibyte' in example. ++ ++2006-05-25 Chong Yidong ++ ++ * keymaps.texi (Key Sequences): Renamed from Keymap Terminology. ++ Explain string and vector representations of key sequences. ++ ++ * keymaps.texi (Changing Key Bindings): ++ * commands.texi (Interactive Codes): ++ * help.texi (Describing Characters): Refer to it. ++ ++2006-05-23 Luc Teirlinck ++ ++ * frames.texi (Pointer Shape): @end table -> @end defvar. ++ ++2006-05-22 Richard Stallman ++ ++ * elisp.texi (Top): Update subnode menus. ++ ++ * frames.texi (Pointer Shape): Node renamed from Pointer Shapes. ++ Contents rewritten; material from old Pointer Shape node moved here. ++ ++ * display.texi (Pointer Shape): Node deleted. ++ (Image Descriptors): Minor cleanup. ++ ++2006-05-21 Richard Stallman ++ ++ * syntax.texi (Parsing Expressions): Update info on which STATE ++ elements are ignored. ++ ++2006-05-19 Luc Teirlinck ++ ++ * hooks.texi (Standard Hooks): Correct typo. ++ ++ * gpl.texi (GPL): ifinfo -> ifnottex. ++ ++2006-05-19 Michael Ernst (tiny change) ++ ++ * searching.texi (Simple Match Data): Warn about match data being ++ set anew by every search. ++ ++2006-05-17 Richard Stallman ++ ++ * minibuf.texi (Minibuffer History): Clarify. ++ ++ * searching.texi (Regexp Special): Clarify nested regexp warning. ++ ++2006-05-16 Kim F. Storm ++ ++ * minibuf.texi (Minibuffer History): Update add-to-history. ++ ++2006-05-15 Oliver Scholz (tiny change) ++ ++ * nonascii.texi (Explicit Encoding): Fix ++ typo (encoding<->decoding). ++ ++2006-05-14 Richard Stallman ++ ++ * buffers.texi (Creating Buffers): Cleanup. ++ ++ * files.texi (Visiting Functions): Rewrite in find-file-noselect. ++ ++2006-05-13 Eli Zaretskii ++ ++ * buffers.texi (Current Buffer): Document that with-temp-buffer ++ disables undo. ++ ++ * os.texi (Terminal-Specific): More accurate description of how ++ Emacs searches for the terminal-specific libraries. ++ ++2006-05-12 Eli Zaretskii ++ ++ * hooks.texi (Standard Hooks) [iftex]: Convert @xref's to ++ emacs-xtra to @inforef's. ++ ++ * text.texi (Undo): Document that undo is turned off in buffers ++ whose names begin with a space. ++ ++ * buffers.texi (Buffer Names): Add index entries for buffers whose ++ names begin with a space. ++ (Creating Buffers): Document that undo is turned off in buffers ++ whose names begin with a space. ++ ++ * files.texi (Visiting Functions, Reading from Files) ++ (Saving Buffers): Mention code and EOL conversions by file I/O ++ primitives and subroutines. ++ ++ * nonascii.texi (Lisp and Coding Systems): Document ++ coding-system-eol-type. Add index entries for eol conversion. ++ ++ * display.texi (Defining Faces): Mention `mac', and add an xref to ++ where window-system is described. ++ ++2006-05-10 Richard Stallman ++ ++ * internals.texi (Writing Emacs Primitives): Clarify GCPRO rules. ++ ++2006-05-10 Reiner Steib ++ ++ * variables.texi (File Local Variables): Recommend to quote lambda ++ expressions in safe-local-variable property. ++ ++2006-05-09 Richard Stallman ++ ++ * variables.texi (File Local Variables): Document ++ safe-local-eval-forms and safe-local-eval-function. ++ ++2006-05-07 Kim F. Storm ++ ++ * minibuf.texi (Minibuffer History): Remove keep-dups arg ++ from add-to-history. ++ ++2006-05-07 Romain Francoise ++ ++ * commands.texi (Event Input Misc): ++ * compile.texi (Eval During Compile): ++ * internals.texi (Buffer Internals): ++ * minibuf.texi (Initial Input): ++ * nonascii.texi (Scanning Charsets): ++ * numbers.texi (Comparison of Numbers): ++ * windows.texi (Textual Scrolling, Vertical Scrolling): ++ Fix various typos. ++ ++2006-05-06 Eli Zaretskii ++ ++ * hooks.texi (Standard Hooks): Replace inforef to emacs-xtra by ++ conditional xref's to either emacs or emacs-xtra, depending on ++ @iftex/@ifnottex. ++ ++ * minibuf.texi (Minibuffer History): Document add-to-history. ++ ++2006-05-05 Eli Zaretskii ++ ++ * internals.texi (Pure Storage): Mention the pure overflow message ++ at startup. ++ ++2006-05-05 Johan Bockgård ++ ++ * keymaps.texi (Active Keymaps): Fix pseudo-Lisp syntax. ++ (Searching Keymaps): Fix pseudo-Lisp description of keymap ++ search. ++ ++2006-05-01 Richard Stallman ++ ++ * intro.texi (nil and t): Clarify. ++ ++ * variables.texi (File Local Variables): Suggest using booleanp. ++ ++2006-05-01 Juanma Barranquero ++ ++ * objects.texi (Type Predicates): Fix typos. ++ ++2006-05-01 Stefan Monnier ++ ++ * intro.texi (nil and t): Add booleanp. ++ ++ * objects.texi (Type Predicates): Add links for booleanp and ++ string-or-null-p. ++ ++2006-04-29 Richard Stallman ++ ++ * modes.texi (Multiline Font Lock): Rename from ++ Multi line Font Lock Elements. Much clarification. ++ (Font Lock Multiline, Region to Fontify): Much clarification. ++ ++2006-04-29 Stefan Monnier ++ ++ * variables.texi (File Local Variables): Remove the special case t for ++ safe-local-variable. ++ ++2006-04-26 Richard Stallman ++ ++ * syntax.texi (Parsing Expressions): Minor cleanup. ++ ++2006-04-18 Richard Stallman ++ ++ * tips.texi (Coding Conventions): Explain when the package's ++ prefix should appear later on (not at the start of the name). ++ ++ * searching.texi (String Search): Clarify effect of NOERROR. ++ ++ * modes.texi (Imenu): Clarify what special items do. ++ ++ * hooks.texi (Standard Hooks): Delete text about old hook names. ++ ++2006-04-17 Romain Francoise ++ ++ * variables.texi (Local Variables): Update the default value of ++ `max-specpdl-size'. ++ ++2006-04-15 Michael Olson ++ ++ * processes.texi (Transaction Queues): Mention the new optional ++ `delay-question' argument for `tq-enqueue'. ++ ++2006-04-13 Bill Wohler ++ ++ * customize.texi (Common Keywords): Use dotted notation for ++ :package-version value. Specify its values. Improve documentation ++ for customize-package-emacs-version-alist. ++ ++2006-04-12 Bill Wohler ++ ++ * customize.texi (Common Keywords): Move description of ++ customize-package-emacs-version-alist to @defvar. ++ ++2006-04-10 Bill Wohler ++ ++ * customize.texi (Common Keywords): Add :package-version. ++ ++2006-04-10 Kim F. Storm ++ ++ * text.texi (Buffer Contents): Add NOPROPS arg to ++ filter-buffer-substring. ++ ++2006-04-08 Kevin Ryde ++ ++ * os.texi (Command-Line Arguments): Update xref to emacs manual ++ "Command Arguments" -> "Emacs Invocation", per change there. ++ ++2006-04-08 Thien-Thi Nguyen ++ ++ * display.texi (Other Display Specs): Arrange a @code{DOTTED-LIST} to ++ be on one line to help makeinfo not render two spaces after the dot. ++ ++2006-04-07 Reiner Steib ++ ++ * strings.texi (Predicates for Strings): Add string-or-null-p. ++ ++2006-03-28 Kim F. Storm ++ ++ * processes.texi (Accepting Output): Remove obsolete (and incorrect) ++ remarks about systems that don't support fractional seconds. ++ ++2006-03-25 Karl Berry ++ ++ * elisp.texi: Use @copyright{} instead of (C), and do not indent ++ the year list. ++ ++2006-03-21 Nick Roberts ++ ++ * display.texi (Fringe Indicators): Fix typos. ++ ++2006-03-19 Luc Teirlinck ++ ++ * tips.texi (Documentation Tips): One can now also write `program' ++ in front of a quoted symbol in a docstring to prevent making a ++ hyperlink. ++ ++2006-03-19 Alan Mackenzie ++ ++ * text.texi (Special Properties): Clarify `fontified' property. ++ ++2006-03-16 Richard Stallman ++ ++ * display.texi (Defining Images): Minor cleanup. ++ ++2006-03-16 Bill Wohler ++ ++ * display.texi (Defining Images): In image-load-path-for-library, ++ prefer user's images. ++ ++2006-03-15 Stefan Monnier ++ ++ * modes.texi (Region to Fontify): Remove font-lock-lines-before. ++ ++2006-03-15 Bill Wohler ++ ++ * display.texi (Defining Images): Fix example in ++ image-load-path-for-library by not recommending that one binds ++ image-load-path. Just defvar it to placate compiler and only use ++ it if previously defined. ++ ++2006-03-14 Bill Wohler ++ ++ * display.texi (Defining Images): In image-load-path-for-library, ++ always return list of directories. Update example. ++ ++2006-03-14 Alan Mackenzie ++ ++ * modes.texi: New node, "Region to Fontify" (for Font Lock). ++ This describes font-lock-extend-region-function. ++ ("Other Font Lock Variables"): Move "font-lock-lines-before" to ++ the new node "Region to Fontify". ++ ++2006-03-13 Richard Stallman ++ ++ * display.texi (Invisible Text): The impossible position is ++ now before the invisible text, not after. ++ (Defining Images): Clean up last change. ++ ++2006-03-11 Bill Wohler ++ ++ * display.texi (Defining Images): Add image-load-path-for-library. ++ ++2006-03-11 Luc Teirlinck ++ ++ * text.texi (Adaptive Fill): Fix Texinfo usage. ++ ++ * strings.texi (Creating Strings): Fix Texinfo usage. ++ ++ * searching.texi (Regexp Special): Use @samp for regular ++ expressions that are not in Lisp syntax. ++ ++2006-03-08 Luc Teirlinck ++ ++ * searching.texi (Regexp Special): Put remark between parentheses ++ to avoid misreading. ++ ++2006-03-07 Luc Teirlinck ++ ++ * searching.texi (Syntax of Regexps): More accurately describe ++ which characters are special in which situations. ++ (Regexp Special): Recommend _not_ to quote `]' or `-' when they ++ are not special. Describe in detail when `[' and `]' are special. ++ (Regexp Backslash): Plenty of regexps with unbalanced square ++ brackets are valid, so reword that statement. ++ ++2006-03-02 Kim F. Storm ++ ++ * keymaps.texi (Tool Bar): Add tool-bar-border. ++ ++2006-02-28 Luc Teirlinck ++ ++ * loading.texi (Load Suffixes): Rephrase last paragraph. Fix typos. ++ ++2006-02-27 Luc Teirlinck ++ ++ * elisp.texi (Top): Include "Load Suffixes" in the detailed menu. ++ ++ * files.texi (Locating Files): Suggest additional values for the ++ SUFFIXES arg of `locate-file'. Update pxref. ++ ++ * loading.texi (Loading): Include new node "Load Suffixes" in menu. ++ (How Programs Do Loading): Discuss the effects of Auto Compression ++ mode on `load'. ++ (Load Suffixes): New node. ++ (Library Search): Delete description of `load-suffixes'; it was ++ moved to "Load Suffixes". ++ (Autoload, Named Features): Mention `load-suffixes'. ++ ++2006-02-21 Giorgos Keramidas (tiny change) ++ ++ * display.texi (Fringe Indicators, Fringe Cursors): Fix typos. ++ ++ * windows.texi (Window Tree): Fix typo. ++ ++2006-02-20 Kim F. Storm ++ ++ * display.texi (Fringe Indicators): New section. ++ Move indicate-empty-lines, indicate-buffer-boundaries, and ++ default-indicate-buffer-boundaries here. ++ Add fringe-indicator-alist and default-fringes-indicator-alist. ++ Add list of logical fringe indicator symbols. ++ Update list of standard bitmap names. ++ (Fringe Cursors): New section. ++ Move overflow-newline-into-fringe here. ++ Add fringe-cursor-alist and default-fringes-cursor-alist. ++ Add list of fringe cursor symbols. ++ ++2006-02-20 Juanma Barranquero ++ ++ * commands.texi (Using Interactive): Fix reference to node ++ "Minibuffers". ++ ++2006-02-19 Richard M. Stallman ++ ++ * minibuf.texi (High-Level Completion): ++ Add xref to read-input-method-name. ++ ++ * files.texi (Relative File Names): Move file-relative-name here. ++ (File Name Expansion): From here. Minor clarifications. ++ ++ * commands.texi (Using Interactive): Add xrefs about reading input. ++ Clarify remarks about that moving point and mark. ++ Put string case before list case. ++ ++2006-02-16 Johan Bockgård ++ ++ * display.texi (Other Display Specs, Image Descriptors): ++ Revert erroneous changes. The previous description of ++ image-descriptors as `(image . PROPS)' was correct. ++ ++2006-02-14 Richard M. Stallman ++ ++ * variables.texi (File Local Variables): Clarifications. ++ ++2006-02-14 Juanma Barranquero ++ ++ * variables.texi (File Local Variables): Use @code for a cons ++ cell, not @var. ++ ++2006-02-13 Chong Yidong ++ ++ * variables.texi (File Local Variables): Document new file local ++ variable behavior. ++ ++2006-02-10 Kim F. Storm ++ ++ * eval.texi (Function Indirection): Add NOERROR to indirect-function. ++ ++2006-02-08 Juanma Barranquero ++ ++ * modes.texi (%-Constructs): Remove obsolete info about ++ `global-mode-string'. ++ ++2006-02-07 Richard M. Stallman ++ ++ * commands.texi (Prefix Command Arguments): Minor cleanup. ++ ++ * display.texi: "Graphical display", not window system. ++ ++ * functions.texi (What Is a Function): Fix xref. ++ ++ * keymaps.texi (Key Lookup): Clarify wrt commands vs other functions. ++ (Changing Key Bindings): Clarify when remapping is better than ++ substitute-key-definition. ++ ++2006-02-02 Richard M. Stallman ++ ++ * minibuf.texi (Basic Completion): Completion alists are risky. ++ ++ * keymaps.texi (Active Keymaps): Clarifications. ++ (Searching Keymaps): New node. ++ (Keymaps): Update menu. ++ ++ * frames.texi (Layout Parameters): Minor clarification. ++ (Drag and Drop): New node. ++ (Frames): Update menu. ++ ++2006-01-29 Chong Yidong ++ ++ * display.texi (Other Display Specs, Image Descriptors): ++ Image description is a list, not a cons cell. ++ ++2006-01-28 Luc Teirlinck ++ ++ * lists.texi (Cons Cells): Minor correction (the cdr of a dotted ++ list is not necessarily a list). ++ ++2006-01-27 Eli Zaretskii ++ ++ * frames.texi (Layout Parameters): border-width and ++ internal-border-width belong to the frame, not the window. ++ ++2006-01-19 Richard M. Stallman ++ ++ * nonascii.texi (Translation of Characters): Search cmds use ++ translation-table-for-input. Automatically made local. ++ ++ * markers.texi (Overview of Markers): Count insertion type ++ as one of a marker's attributes. ++ ++ * keymaps.texi (Controlling Active Maps): New node, split out of ++ Active Keymaps. ++ (Keymaps): Menu updated. ++ (Active Keymaps): Give pseudocode to explain how the active ++ maps are searched. current-active-maps and key-binding moved here. ++ (Functions for Key Lookup): current-active-maps and key-binding moved. ++ Clarifications. ++ (Searching the Keymaps): New subnode. ++ ++ * elisp.texi (Top): Menu clarification. ++ ++ * display.texi (Other Display Specs): Delete duplicate entry for ++ just a string as display spec. Move text about recursive display ++ specs on such a string. ++ ++ * commands.texi (Key Sequence Input): Clarify. ++ Move num-nonmacro-input-events out. ++ (Reading One Event): num-nonmacro-input-events moved here. ++ ++2006-01-14 Nick Roberts ++ ++ * advice.texi (Simple Advice): Update example to fit argument ++ change in previous-line. ++ ++2006-01-05 Richard M. Stallman ++ ++ * markers.texi (The Mark): Fix in `mark'. ++ ++2006-01-04 Richard M. Stallman ++ ++ * processes.texi (Misc Network, Make Network): Minor cleanups. ++ ++2006-01-04 Kim F. Storm ++ ++ * processes.texi (Make Network): Add IPv6 addresses and handling. ++ (Network Feature Testing): Mention (:family ipv6). ++ (Misc Network): Add IPv6 formats to format-network-address. ++ ++2005-12-30 Richard M. Stallman ++ ++ * text.texi (Changing Properties): ++ Don't use return value of set-text-properties. ++ ++2005-12-29 Luc Teirlinck ++ ++ * modes.texi (Mode Line Format): Correct typo in menu. ++ ++2005-12-29 Richard M. Stallman ++ ++ * modes.texi (Mode Line Top): New node. ++ (Mode Line Data): Some text moved to new node. ++ Explain the data structure more concretely. ++ (Mode Line Basics): Clarifications. ++ (Mode Line Variables): Clarify intro paragraph. ++ (%-Constructs): Clarify intro paragraph. ++ (Mode Line Format): Update menu. ++ ++2005-12-28 Luc Teirlinck ++ ++ * minibuf.texi (Basic Completion): Update lazy-completion-table ++ examples for removal of ARGS argument. ++ ++2005-12-23 Richard M. Stallman ++ ++ * text.texi (Undo): Restore some explanation from the version ++ that was deleted. ++ ++2005-12-23 Eli Zaretskii ++ ++ * text.texi (Undo): Remove duplicate descriptions of `apply ++ funname' and `apply delta' elements of the undo list. ++ ++2005-12-20 Richard M. Stallman ++ ++ * help.texi (Help Functions): Update documentation of `apropos'. ++ ++2005-12-20 Luc Teirlinck ++ ++ * customize.texi (Type Keywords): Delete xref to "Text help-echo", ++ because it is confusing. If the :help-echo keyword is a function, ++ it is not directly used as the :help-echo overlay property, as the ++ xref seems to suggest (it does not take the appropriate args). ++ ++2005-12-19 Luc Teirlinck ++ ++ * customize.texi (Common Keywords): Fix Texinfo usage. ++ (Group Definitions, Variable Definitions): Update for new ++ conventions for using `*' in docstrings. ++ ++ * tips.texi (Documentation Tips): Update for new conventions for ++ using `*' in docstrings. ++ ++2005-12-16 Richard M. Stallman ++ ++ * minibuf.texi (Minibuffer Contents): Minor cleanup. ++ ++2005-12-16 Juri Linkov ++ ++ * minibuf.texi (Minibuffer Contents): Add minibuffer-completion-contents. ++ ++2005-12-14 Romain Francoise ++ ++ * modes.texi (Customizing Keywords): Rename `append' to `how'. ++ Fix typo. ++ ++2005-12-11 Juri Linkov ++ ++ * minibuf.texi (Completion Commands): Add mention of read-file-name ++ for filename completion keymaps. ++ (Reading File Names): Add mention of filename completion keymaps ++ for read-file-name and xref to `Completion Commands'. ++ ++2005-12-10 Richard M. Stallman ++ ++ * customize.texi (Common Keywords): State caveats for use of :tag. ++ ++2005-12-08 Richard M. Stallman ++ ++ * minibuf.texi (Intro to Minibuffers): Replace list of local maps ++ with xrefs and better explanation. ++ (Completion Commands): Add the filename completion maps. ++ ++ * objects.texi (Character Type): Clarify that \s is not space ++ if a dash follows. ++ ++2005-12-05 Richard M. Stallman ++ ++ * windows.texi (Resizing Windows): Delete preserve-before args. ++ ++2005-12-05 Stefan Monnier ++ ++ * keymaps.texi (Format of Keymaps): Remove mention of a quirk ++ in full keymaps, since the quirk has been fixed. ++ ++2005-12-03 Eli Zaretskii ++ ++ * hooks.texi (Standard Hooks): Add index entries. Mention ++ `compilation-finish-functions'. ++ ++2005-11-27 Richard M. Stallman ++ ++ * windows.texi (Resizing Windows): Add adjust-window-trailing-edge. ++ ++2005-11-21 Juri Linkov ++ ++ * customize.texi (Common Keywords): Update links types ++ custom-manual and url-link. Add link types emacs-library-link, ++ file-link, function-link, variable-link, custom-group-link. ++ ++2005-11-20 Chong Yidong ++ ++ * display.texi: Revert 2005-11-20 change. ++ ++2005-11-20 Thien-Thi Nguyen ++ ++ * processes.texi (Bindat Functions): ++ Say "third" to refer to zero-based index "2". ++ ++2005-11-18 Luc Teirlinck ++ ++ * loading.texi (Library Search): Update the default value of ++ `load-suffixes'. ++ ++2005-11-17 Chong Yidong ++ ++ * display.texi (Attribute Functions): Mention :ignore-defface. ++ ++2005-11-16 Stefan Monnier ++ ++ * modes.texi (Minor Mode Conventions): Use custom-set-minor-mode. ++ (Minor Mode Conventions): Mention the use of a hook. ++ ++2005-11-06 Richard M. Stallman ++ ++ * files.texi (Magic File Names): find-file-name-handler checks the ++ `operations' property of the handler. ++ ++2005-11-03 Richard M. Stallman ++ ++ * variables.texi (Frame-Local Variables): Small clarification. ++ ++2005-10-29 Chong Yidong ++ ++ * os.texi (Init File): Document ~/.emacs.d/init.el. ++ ++2005-10-29 Richard M. Stallman ++ ++ * internals.texi (Garbage Collection): Document memory-full. ++ ++2005-10-28 Bill Wohler ++ ++ * tips.texi (Documentation Tips): Help mode now creates hyperlinks ++ for URLs. ++ ++2005-10-28 Richard M. Stallman ++ ++ * minibuf.texi (Completion Commands): Clean up prev change. ++ ++2005-10-26 Kevin Ryde ++ ++ * compile.texi (Eval During Compile): Explain recommended uses ++ of eval-when-compile and eval-and-compile. ++ ++2005-10-27 Masatake YAMATO ++ ++ * minibuf.texi (Completion Commands): ++ Write about new optional argument for `display-completion-list'. ++ ++2005-10-23 Richard M. Stallman ++ ++ * display.texi (Overlay Arrow): Clarify about local bindings of ++ overlay-arrow-position. ++ ++2005-10-22 Eli Zaretskii ++ ++ * internals.texi (Building Emacs): Fix last change. ++ ++2005-10-22 Richard M. Stallman ++ ++ * internals.texi (Building Emacs): Document eval-at-startup. ++ ++2005-10-21 Richard M. Stallman ++ ++ * loading.texi (Where Defined): load-history contains abs file names. ++ symbol-file returns abs file names. ++ ++2005-10-19 Kim F. Storm ++ ++ * display.texi (Showing Images): Add max-image-size integer value. ++ ++2005-10-18 Chong Yidong ++ ++ * display.texi (Showing Images): Document max-image-size. ++ ++2005-10-17 Richard M. Stallman ++ ++ * commands.texi (Quitting): Minor clarification. ++ ++ * processes.texi (Sentinels): Clarify about output and quitting. ++ (Filter Functions): Mention with-local-quit. ++ ++2005-10-17 Juri Linkov ++ ++ * buffers.texi (Current Buffer): ++ * commands.texi (Event Input Misc): ++ * compile.texi (Eval During Compile, Compiler Errors): ++ * customize.texi (Group Definitions): ++ * display.texi (Progress, Defining Faces): ++ * files.texi (Writing to Files): ++ * modes.texi (Mode Hooks, Defining Minor Modes): ++ * streams.texi (Output Functions): ++ * syntax.texi (Syntax Table Functions): ++ * text.texi (Change Hooks): ++ Replace `...' with `@dots{}' in `@defmac' and `@defspec'. ++ ++ * commands.texi (Quitting): Replace arg `forms' with `body' in ++ `with-local-quit'. ++ ++ * positions.texi (Excursions): Replace arg `forms' with `body' in ++ `save-excursion'. ++ ++2005-10-08 Kim F. Storm ++ ++ * windows.texi (Window Tree): Rename window-split-tree to window-tree. ++ Rename manual section accordingly. ++ ++2005-10-04 Kim F. Storm ++ ++ * windows.texi (Window Split Tree): New section describing ++ new function window-split-tree function. ++ ++2005-10-03 Nick Roberts ++ ++ * display.texi (Fringe Size/Pos): Simplify and add detail. ++ ++2005-09-30 Romain Francoise ++ ++ * minibuf.texi (High-Level Completion): Explain that the prompt ++ given to `read-buffer' should end with a colon and a space. ++ Update usage examples. ++ ++2005-09-29 Juri Linkov ++ ++ * display.texi (Displaying Messages): Rename argument name ++ `string' to `format-string' in functions `message', `message-box', ++ `message-or-box'. ++ ++2005-09-26 Chong Yidong ++ ++ * errors.texi (Standard Errors): Correct xrefs. ++ ++2005-09-18 Chong Yidong ++ ++ * display.texi (Defining Images): Update documentation for ++ `image-load-path'. ++ ++2005-09-17 Richard M. Stallman ++ ++ * display.texi (Defining Images): Clean up previous change. ++ ++2005-09-16 Romain Francoise ++ ++ * elisp.texi: Specify GFDL version 1.2. ++ ++ * doclicense.texi (GNU Free Documentation License): Update to ++ version 1.2. ++ ++2005-09-15 Chong Yidong ++ ++ * display.texi (Defining Images): Document `image-load-path'. ++ ++2005-09-15 Richard M. Stallman ++ ++ * objects.texi (Printed Representation): Minor cleanup. ++ (Box Diagrams): Minor fix. ++ (Cons Cell Type): Move (...) index item here. ++ (Box Diagrams): From here. ++ (Array Type): Minor fix. ++ (Type Predicates): Delete index "predicates". ++ (Hash Table Type): Clarify xref. ++ (Dotted Pair Notation): Minor fix. ++ ++2005-09-10 Chong Yidong ++ ++ * files.texi (Saving Buffers): Fix typo. ++ ++2005-09-08 Richard M. Stallman ++ ++ * tips.texi (Programming Tips): Correct the "default" prompt spec. ++ ++2005-09-08 Chong Yidong ++ ++ * locals.texi (Standard Buffer-Local Variables): Don't include ++ mode variables for minor modes. ++ Fix xrefs for buffer-display-count, buffer-display-table, ++ buffer-offer-save, buffer-saved-size, cache-long-line-scans, ++ enable-multibyte-characters, fill-column, header-line-format, ++ left-fringe-width, left-margin, and right-fringe-width. ++ ++ * hooks.texi (Standard Hooks): All hooks should conform to the ++ standard naming convention now. ++ Fix xref for `echo-area-clear-hook'. ++ ++ * display.texi (Usual Display): Note that indicate-empty-lines and ++ tab-width are buffer-local. ++ ++ * files.texi (Saving Buffers): Add xref to `Killing Buffers'. ++ ++ * modes.texi (Mode Help): Note that major-mode is buffer-local. ++ ++ * nonascii.texi (Encoding and I/O): Note that ++ buffer-file-coding-system is buffer-local. ++ ++ * positions.texi (List Motion): Note that defun-prompt-regexp is ++ buffer-local. ++ ++ * text.texi (Auto Filling): Note that auto-fill-function is ++ buffer-local. ++ (Undo): Note that buffer-undo-list is buffer-local. ++ ++ * windows.texi (Buffers and Windows): Document ++ buffer-display-count. ++ ++2005-09-06 Richard M. Stallman ++ ++ * tips.texi (Coding Conventions): Sometimes it is ok to put the ++ package prefix elsewhere than at the start of the name. ++ ++2005-09-03 Richard M. Stallman ++ ++ * tips.texi (Programming Tips): Add conventions for minibuffer ++ questions and prompts. ++ ++2005-09-03 Joshua Varner (tiny change) ++ ++ * intro.texi (nil and t): Minor cleanup. ++ Delete spurious mention of keyword symbols. ++ (Evaluation Notation): Add index entry. ++ (A Sample Function Description): Minor cleanup. ++ (A Sample Variable Description): Not all vars can be set. ++ ++2005-09-03 Thien-Thi Nguyen ++ ++ * text.texi (Buffer Contents): Use "\n" in examples' result strings. ++ ++ (Insertion): Document precise type of `insert-char' arg COUNT. ++ ++2005-09-02 Stefan Monnier ++ ++ * modes.texi (Other Font Lock Variables): Sync the default of ++ font-lock-lines-before. ++ ++2005-08-31 Michael Albinus ++ ++ * files.texi (Magic File Names): Add `make-auto-save-file-name'. ++ ++2005-08-29 Richard M. Stallman ++ ++ * elisp.texi (Top): Update subnode menu. ++ ++ * searching.texi (Searching and Matching): Move node. ++ Rearrange contents and add overall explanation. ++ (Searching and Case): Move node. ++ (Searching and Matching): Update menu. ++ ++2005-08-27 Eli Zaretskii ++ ++ * os.texi (Startup Summary): Fix the description of the initial ++ startup message display. ++ ++2005-08-25 Richard M. Stallman ++ ++ * searching.texi (Search and Replace): Add replace-regexp-in-string. ++ ++2005-08-25 Emilio C. Lopes ++ ++ * display.texi (Finding Overlays): Fix `find-overlay-prop' in ++ `next-overlay-change' example. ++ ++2005-08-22 Juri Linkov ++ ++ * display.texi (Attribute Functions): Add set-face-inverse-video-p. ++ Fix invert-face. Fix args of face-background. ++ ++ * display.texi (Standard Faces): Delete node. ++ (Faces): Add xref to `(emacs)Standard Faces'. ++ (Displaying Faces): Fix xref to `Standard Faces'. ++ ++ * modes.texi (Mode Line Data): Fix xref to Standard Faces. ++ ++2005-08-20 Alan Mackenzie ++ ++ * buffers.texi (The Buffer List): Clarify the manipulation of the ++ buffer list. ++ ++2005-08-14 Richard M. Stallman ++ ++ * modes.texi (Auto Major Mode): interpreter-mode-alist key is not ++ a regexp. ++ ++2005-08-11 Richard M. Stallman ++ ++ * elisp.texi (Top): Update subnode lists. ++ ++ * display.texi (Inverse Video): Node deleted. ++ ++ * tips.texi (Key Binding Conventions, Programming Tips, Warning Tips): ++ New nodes split out of Coding Conventions. ++ ++ * searching.texi (Regular Expressions): Document re-builder. ++ ++ * os.texi (Time Parsing): New node split out of Time Conversion. ++ ++ * processes.texi (Misc Network, Network Feature Testing) ++ (Network Options, Make Network): New nodes split out of ++ Low-Level Network. ++ ++2005-08-09 Richard M. Stallman ++ ++ * frames.texi (Geometry): New node, split from Size and Position. ++ (Frame Parameters): Refer to Geometry. ++ ++ * buffers.texi (The Buffer List): Fix xrefs. ++ ++ * windows.texi (Splitting Windows): Fix xref. ++ ++ * frames.texi (Layout Parameters): Add xref. ++ ++ * display.texi (Line Height, Scroll Bars): Fix xrefs. ++ ++ * keymaps.texi (Menu Bar): Fix xref. ++ ++ * locals.texi (Standard Buffer-Local Variables): Fix xref. ++ ++ * modes.texi (%-Constructs): Fix xref. ++ ++ * frames.texi (Window Frame Parameters): Node split up. ++ (Basic Parameters, Position Parameters, Size Parameters) ++ (Layout Parameters, Buffer Parameters, Management Parameters) ++ (Cursor Parameters, Color Parameters): New subnodes. ++ ++2005-08-09 Luc Teirlinck ++ ++ * positions.texi (Screen Lines): Update xref for previous change ++ in minibuf.texi. ++ ++ * minibuf.texi (Intro to Minibuffers): Update pxref for previous ++ change in minibuf.texi. ++ ++2005-08-09 Richard M. Stallman ++ ++ * tips.texi (Coding Conventions): Minor cleanup. ++ ++ * modes.texi (Defining Minor Modes): Explain when init-value ++ can be non-nil. ++ ++ * elisp.texi (Top): Update submenu for Minibuffer. ++ ++ * minibuf.texi (Minibuffer Misc): Node split up. ++ (Minibuffer Commands, Minibuffer Windows, Minibuffer Contents) ++ (Recursive Mini): New nodes split out from Minibuffer Misc. ++ (Minibuffer Misc): Document max-mini-window-height. ++ ++ * hash.texi (Defining Hash): Delete stray paren in example. ++ ++ * display.texi (Echo Area Customization): Don't define ++ max-mini-window-height here; xref instead. ++ ++ * commands.texi (Event Input Misc): Update while-no-input. ++ ++ * advice.texi (Advising Functions): Explain when to use advice ++ and when to use a hook. ++ ++2005-07-30 Eli Zaretskii ++ ++ * makefile.w32-in (info): Don't run install-info. ++ ($(infodir)/dir): New target, produced by running install-info. ++ ++2005-07-27 Luc Teirlinck ++ ++ * modes.texi (Defining Minor Modes): The keyword for the initial ++ value is :init-value, not :initial-value. ++ ++2005-07-23 Eli Zaretskii ++ ++ * loading.texi (Autoload): Make the `doctor' example be consistent ++ with what's in current loaddefs.el. Describe the "fn" magic in ++ the usage portion of the doc string. ++ ++2005-07-22 Richard M. Stallman ++ ++ * internals.texi (Garbage Collection): Clarify previous change. ++ ++2005-07-21 Stefan Monnier ++ ++ * internals.texi (Garbage Collection): Add gc-cons-percentage. ++ ++2005-07-18 Juri Linkov ++ ++ * commands.texi (Accessing Events): ++ * frames.texi (Text Terminal Colors, Resources): ++ * markers.texi (The Mark): ++ * modes.texi (Defining Minor Modes): ++ Delete duplicate duplicate words. ++ ++2005-07-16 Richard M. Stallman ++ ++ * display.texi (Managing Overlays): Clarify make-overlay ++ args for insertion types. ++ ++2005-07-13 Luc Teirlinck ++ ++ * customize.texi (Variable Definitions): ++ Add `custom-initialize-safe-set' and `custom-initialize-safe-default'. ++ `standard-value' is a list too. ++ (Defining New Types): Use @key{RET} instead of @key{ret}. ++ ++2005-07-13 Francis Litterio (tiny change) ++ ++ * os.texi (Translating Input): Fix typo. ++ ++2005-07-08 Richard M. Stallman ++ ++ * README: Update edition number and size estimate. ++ ++ * elisp.texi (VERSION): Set to 2.9. ++ ++2005-07-07 Richard M. Stallman ++ ++ * book-spine.texinfo: Update Emacs version. ++ ++ * display.texi (Inverse Video): Delete mode-line-inverse-video. ++ ++2005-07-06 Richard M. Stallman ++ ++ * searching.texi (Regexp Search): Clarify what re-search-forward ++ does when the search fails. ++ ++2005-07-05 Lute Kamstra ++ ++ * Update FSF's address in GPL notices. ++ ++ * doclicense.texi (GNU Free Documentation License): ++ * gpl.texi (GPL): ++ * tips.texi (Coding Conventions, Library Headers): ++ * vol1.texi: ++ * vol2.texi: Update FSF's address. ++ ++2005-07-04 Richard M. Stallman ++ ++ * hooks.texi (Standard Hooks): Add occur-hook. ++ ++2005-07-03 Luc Teirlinck ++ ++ * display.texi (The Echo Area): Correct menu. ++ ++2005-07-03 Richard M. Stallman ++ ++ * elisp.texi (Top): Update subnode menu for Display. ++ ++ * display.texi (Displaying Messages): New node, with most ++ of what was in The Echo Area. ++ (Progress): Moved under The Echo Area. ++ (Logging Messages): New node with new text. ++ (Echo Area Customization): New node, the rest of what was ++ in The Echo Area. Document message-truncate-lines with @defvar. ++ (Display): Update menu. ++ ++ * windows.texi (Textual Scrolling): Doc 3 values for ++ scroll-preserve-screen-position. ++ ++ * text.texi (Special Properties): Change hook functions ++ should bind inhibit-modification-hooks around altering buffer text. ++ ++ * keymaps.texi (Key Binding Commands): Call binding BINDING ++ rather than DEFINITION. ++ ++2005-06-29 Juanma Barranquero ++ ++ * variables.texi (Defining Variables): `user-variable-p' returns t ++ for aliases of user options, nil for alias loops. ++ ++2005-06-28 Richard M. Stallman ++ ++ * keymaps.texi (Creating Keymaps): Put make-sparse-keymap before ++ make-keymap. ++ ++2005-06-27 Luc Teirlinck ++ ++ * variables.texi (Setting Variables): Correct and clarify ++ description of `add-to-ordered-list'. ++ ++2005-06-26 Richard M. Stallman ++ ++ * display.texi (Faces): Minor cleanup. ++ ++2005-06-25 Luc Teirlinck ++ ++ * display.texi (Faces): `facep' returns t for strings that are ++ face names. ++ ++2005-06-25 Richard M. Stallman ++ ++ * objects.texi (Equality Predicates): Clarify meaning of equal. ++ ++ * windows.texi (Selecting Windows): save-selected-window ++ and with-selected-window save and restore the current buffer. ++ ++2005-06-24 Richard M. Stallman ++ ++ * numbers.texi (Float Basics): Explain how to test for NaN, ++ and printing the sign of NaNs. ++ ++2005-06-24 Eli Zaretskii ++ ++ * makefile.w32-in (MAKEINFO): Use --force. ++ ++2005-06-23 Richard M. Stallman ++ ++ * display.texi (Face Functions): Correct Texinfo usage. ++ ++2005-06-23 Luc Teirlinck ++ ++ * lists.texi (Rings): `ring-elements' now returns the elements of ++ RING in order. ++ ++2005-06-23 Juanma Barranquero ++ ++ * markers.texi (The Mark): Texinfo usage fix. ++ ++2005-06-23 Kim F. Storm ++ ++ * searching.texi (Entire Match Data): Remove evaporate option for ++ match-data. Do not mention evaporate option for set-match-data. ++ ++2005-06-22 Glenn Morris ++ ++ * display.texi (Face Functions): Mention face aliases. ++ ++2005-06-21 Richard M. Stallman ++ ++ * anti.texi (Antinews): Texinfo usage fix. ++ ++2005-06-21 Karl Berry ++ ++ * elisp.texi: Use @copying. ++ ++ * elisp.texi: Put @summarycontents and @contents before the Top ++ node, instead of the end of the file, so that the contents appear ++ in the right place in the dvi/pdf output. ++ ++2005-06-21 Juri Linkov ++ ++ * display.texi (Defining Faces): Add `customized-face'. ++ ++2005-06-20 Kim F. Storm ++ ++ * variables.texi (Setting Variables): Any type of element can be ++ given order in add-to-ordered-list. Compare elements with eq. ++ ++ * lists.texi (Rearrangement): Sort predicate may just return non-nil. ++ ++2005-06-20 Karl Berry ++ ++ * syntax.texi (Syntax Flags): Make last column very slightly wider ++ to avoid "generic comment" breaking on two lines and causing an ++ underfull box. ++ ++2005-06-19 Luc Teirlinck ++ ++ * lists.texi (Rings): Various minor clarifications and corrections. ++ ++2005-06-18 Richard M. Stallman ++ ++ * functions.texi (Obsolete Functions): Simplify. ++ ++ * variables.texi (Variable Aliases): Simplify. ++ ++ * anti.texi, backups.texi, compile.texi, customization.texi: ++ * debugging.texi, display.texi, edebug.texi, errors.texi, frames.texi: ++ * functions.texi, help.texi, keymaps.texi, modes.texi, nonascii.texi: ++ * os.texi, processes.texi, searching.texi, strings.texi, text.texi: ++ * variables.texi: Fix formatting ugliness. ++ ++ * elisp.texi: Add links to Rings and Byte Packing. ++ Update version and copyright years. ++ ++ * minibuf.texi: Fix formatting ugliness. ++ (Completion Commands): Move keymap vars to the end ++ and vars completing-read binds to the top. ++ ++2005-06-17 Luc Teirlinck ++ ++ * processes.texi: Fix typos. ++ (Bindat Spec): Correct Texinfo error. ++ (Byte Packing): Fix ungrammatical sentence. ++ ++2005-06-17 Thien-Thi Nguyen ++ ++ * lists.texi (Rings): New node. ++ (Lists): Add it to menu. ++ ++ * processes.texi (Byte Packing): New node. ++ (Processes): Add it to menu. ++ ++2005-06-17 Richard M. Stallman ++ ++ * syntax.texi (Parsing Expressions): Fix texinfo usage. ++ ++ * help.texi (Documentation Basics): Explain the xref to ++ Documentation Tips. ++ ++ * debugging.texi (Debugger Commands): Minor fix. ++ ++2005-06-16 Luc Teirlinck ++ ++ * edebug.texi (Instrumenting): Eliminate duplicate link. ++ (Specification List): Replace references to "below", referring to ++ a later node, with one @ref to that node. ++ ++ * os.texi (Timers): Timers should save and restore the match data ++ if they change it. ++ ++ * debugging.texi (Debugger Commands): Mention that the Lisp ++ debugger can not step through primitive functions. ++ ++2005-06-16 Juanma Barranquero ++ ++ * functions.texi (Obsolete Functions): Update argument names of ++ `make-obsolete' and `define-obsolete-function-alias'. ++ ++ * variables.texi (Variable Aliases): Update argument names of ++ `defvaralias', `make-obsolete-variable' and ++ `define-obsolete-variable-alias'. ++ ++2005-06-15 Kim F. Storm ++ ++ * searching.texi (Entire Match Data): Rephrase warnings about ++ evaporate arg to match-data and set-match-data. ++ ++2005-06-14 Luc Teirlinck ++ ++ * elisp.texi (Top): Update detailed menu. ++ ++ * edebug.texi (Edebug): Update menu. ++ (Instrumenting): Update xrefs. ++ (Edebug Execution Modes): Correct xref. ++ (Jumping): Clarify description of `h' command. ++ Eliminate redundant @ref. ++ (Breaks): New node. ++ (Breakpoints): Is now a subsubsection. ++ (Global Break Condition): Mention `C-x X X'. ++ (Edebug Views): Clarify `v' and `p'. Mention `C-x X w'. ++ (Trace Buffer): Clarify STRING arg of `edebug-tracing'. ++ (Edebug Display Update): Correct pxref. ++ (Edebug and Macros): New node. ++ (Instrumenting Macro Calls): Is now a subsubsection. ++ Neither arg of `def-edebug-spec' is evaluated. ++ (Instrumenting Macro Calls): Mention `edebug-eval-macro-args'. ++ (Specification Examples): Fix typo. ++ ++2005-06-14 Lute Kamstra ++ ++ * debugging.texi (Function Debugging): Primitives can break on ++ entry too. ++ ++2005-06-14 Kim F. Storm ++ ++ * variables.texi (Setting Variables): Add add-to-ordered-list. ++ ++2005-06-13 Stefan Monnier ++ ++ * syntax.texi (Parsing Expressions): Document aux functions and vars of ++ syntax-ppss: syntax-ppss-flush-cache and syntax-begin-function. ++ ++2005-06-13 Lute Kamstra ++ ++ * text.texi (Special Properties): Fix cross reference. ++ ++2005-06-11 Luc Teirlinck ++ ++ * debugging.texi (Function Debugging): Delete mention of empty ++ string argument to `cancel-debug-on-entry'. Delete inaccurate ++ description of the return value of that command. ++ ++2005-06-11 Alan Mackenzie ++ ++ * text.texi (Adaptive Fill): Amplify the description of ++ fill-context-prefix. ++ ++2005-06-10 Luc Teirlinck ++ ++ * syntax.texi (Parsing Expressions): Fix Texinfo error. ++ ++2005-06-10 Stefan Monnier ++ ++ * syntax.texi (Parsing Expressions): Document syntax-ppss. ++ ++2005-06-10 Luc Teirlinck ++ ++ * debugging.texi (Error Debugging): Minor rewording. ++ (Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry' ++ is optional. ++ ++2005-06-10 Lute Kamstra ++ ++ * elisp.texi: Use EMACSVER to refer to the current version of Emacs. ++ (Top): Give it a title. Correct version number. Give the ++ detailed node listing a more prominent header. ++ * intro.texi: Don't set VERSION here a second time. ++ Mention Emacs's version too. ++ * anti.texi (Antinews): Use EMACSVER to refer to the current ++ version of Emacs. ++ ++2005-06-09 Kim F. Storm ++ ++ * searching.texi (Entire Match Data): Explain new `reseat' argument to ++ match-data and set-match-data. ++ ++2005-06-08 Richard M. Stallman ++ ++ * searching.texi (Entire Match Data): Clarify when match-data ++ returns markers and when integers. ++ ++ * display.texi (Defining Faces): Explain that face name should not ++ end in `-face'. ++ ++ * modes.texi (Mode Line Data): Minor cleanup. ++ (Customizing Keywords): Node split out of Search-based Fontification. ++ Add example of using font-lock-add-keywords from a hook. ++ Clarify when MODE should be non-nil, and when nil. ++ ++2005-06-06 Richard M. Stallman ++ ++ * modes.texi (Mode Line Data): Explain what happens when the car ++ of a list is a void symbol. ++ (Search-based Fontification): Explain MODE arg to ++ font-lock-add-keywords and warn about calls from major modes. ++ ++2005-06-08 Juri Linkov ++ ++ * display.texi (Standard Faces): Add `shadow' face. ++ ++2005-05-29 Luc Teirlinck ++ ++ * modes.texi (Major Mode Conventions): A derived mode only needs ++ to put the call to the parent mode inside `delay-mode-hooks'. ++ ++2005-05-29 Richard M. Stallman ++ ++ * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook is ++ new, and what that implies. Clarify. ++ ++ * files.texi (Locating Files): Clean up the text. ++ ++ * frames.texi (Window Frame Parameters): Document user-size. ++ Shorten entry for top by referring to left. ++ ++2005-05-26 Richard M. Stallman ++ ++ * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook ++ is new, and what the implications are. Other clarifications. ++ ++2005-05-24 Richard M. Stallman ++ ++ * frames.texi (Dialog Boxes): Minor fixes. ++ ++2005-05-25 Masatake YAMATO ++ ++ * display.texi (Standard Faces): Write about `mode-line-highlight'. ++ ++2005-05-24 Luc Teirlinck ++ ++ * frames.texi (Dialog Boxes): HEADER argument to `x-popup-dialog' ++ is optional. ++ ++2005-05-24 Nick Roberts ++ ++ * frames.texi (Dialog Boxes): Describe new optional argument. ++ ++2005-05-23 Lute Kamstra ++ ++ * modes.texi (Font Lock Basics, Syntactic Font Lock): Recommend ++ syntax-begin-function over font-lock-beginning-of-syntax-function. ++ ++2005-05-21 Luc Teirlinck ++ ++ * minibuf.texi (Reading File Names): Update description of ++ `read-directory-name'. ++ ++ * modes.texi (Derived Modes): Clarify :group keyword. ++ ++2005-05-21 Eli Zaretskii ++ ++ * files.texi (Locating Files): New subsection. ++ Describe locate-file and executable-find. ++ ++2005-05-21 Kevin Ryde ++ ++ * frames.texi (Initial Parameters): Update cross reference to ++ "Emacs Invocation". ++ ++2005-05-19 Luc Teirlinck ++ ++ * keymaps.texi (Active Keymaps): Add anchor. ++ ++ * modes.texi (Hooks): Delete confusing and unnecessary sentence. ++ (Major Mode Conventions): Refer to `Auto Major Mode' in more ++ appropriate place. ++ (Derived Modes): Small clarifications. ++ (Minor Mode Conventions, Keymaps and Minor Modes): ++ Replace references to nodes with references to anchors. ++ (Mode Line Data): Warn that `(:eval FORM)' should not load any files. ++ Clarify description of lists whose first element is an integer. ++ (Mode Line Variables): Add anchor. ++ (%-Constructs): Clarify description of integer after %. ++ (Emulating Mode Line): Describe nil value for FACE. ++ ++2005-05-18 Luc Teirlinck ++ ++ * modes.texi (Derived Modes): Correct references to non-existing ++ variable standard-syntax-table. ++ ++2005-05-17 Lute Kamstra ++ ++ * modes.texi (Defining Minor Modes): Mention the mode hook. ++ ++2005-05-15 Kim F. Storm ++ ++ * processes.texi (Network): Remove open-network-stream-nowait. ++ (Network Servers): Remove open-network-stream-server. ++ ++2005-05-15 Luc Teirlinck ++ ++ * elisp.texi (Top): Update detailed menu. ++ ++ * variables.texi: Reorder nodes. ++ (Variables): Update menu. ++ (File Local Variables): Do not refer to the `-*-' line as ++ a "local variables list". Add pxref. ++ ++2005-05-14 Luc Teirlinck ++ ++ * elisp.texi (Top): Update detailed menu for node changes. ++ ++ * modes.texi (Modes): Update Menu. ++ (Hooks): Move to beginning of chapter. ++ Most minor modes run mode hooks too. ++ `add-hook' can handle void hooks or hooks whose value is a single ++ function. ++ (Major Modes): Update Menu. ++ (Major Mode Basics): New node, split off from `Major Modes'. ++ (Major Mode Conventions): Correct xref. Explain how to handle ++ auto-mode-alist if the major mode command has an autoload cookie. ++ (Auto Major Mode): Major update. Add magic-mode-alist. ++ (Derived Modes): Major update. ++ (Mode Line Format): Update Menu. ++ (Mode Line Basics): New node, split off from `Mode Line Format'. ++ ++ * loading.texi (Autoload): Mention `autoload cookie' as synonym ++ for `magic autoload comment'. Add index entries and anchor. ++ ++2005-05-14 Richard M. Stallman ++ ++ * tips.texi (Coding Conventions): Explain how important it is ++ that just loading certain files not change Emacs behavior. ++ ++ * modes.texi (Defining Minor Modes): Define define-global-minor-mode. ++ ++2005-05-12 Lute Kamstra ++ ++ * modes.texi (Generic Modes): Update. ++ (Major Modes): Refer to node "Generic Modes". ++ ++ * elisp.texi (Top): Update to the current structure of the manual. ++ * processes.texi (Processes): Add menu description. ++ * customize.texi (Customization): Add menu descriptions. ++ ++2005-05-11 Thien-Thi Nguyen ++ ++ * processes.texi (Signals to Processes) ++ (Low-Level Network): Fix typos. ++ ++2005-05-11 Lute Kamstra ++ ++ * elisp.texi (Top): Add some nodes from the chapter "Major and ++ Minor Modes" to the detailed node listing. ++ ++2005-05-10 Richard M. Stallman ++ ++ * keymaps.texi (Extended Menu Items): Menu item filter functions ++ can be called at any time. ++ ++2005-05-08 Luc Teirlinck ++ ++ * variables.texi (File Local Variables): `(hack-local-variables t)' ++ now also checks whether a mode is specified in the local variables ++ list. ++ ++2005-05-05 Kevin Ryde ++ ++ * display.texi (The Echo Area): Correct format function cross ++ reference. ++ ++2005-05-05 Luc Teirlinck ++ ++ * variables.texi (Variable Aliases): Change description of ++ `define-obsolete-variable-alias'. ++ ++ * functions.texi (Functions): Add "Obsolete Functions" to menu. ++ (Defining Functions): Add xref. ++ (Obsolete Functions): New node. ++ (Function Safety): Standardize capitalization of section title. ++ ++ * frames.texi (Pop-Up Menus): Complete description of `x-popup-menu'. ++ (Dialog Boxes): Complete description of `x-popup-dialog'. ++ ++2005-05-04 Richard M. Stallman ++ ++ * commands.texi (Interactive Codes): Fix Texinfo usage. ++ Document U more clearly. ++ ++2005-05-01 Luc Teirlinck ++ ++ * variables.texi (Variable Aliases): `make-obsolete-variable' is a ++ function and not a macro. ++ ++ * frames.texi (Pop-Up Menus): Correct and clarify description of ++ `x-popup-menu'. ++ (Dialog Boxes): Clarify description of `x-popup-dialog'. ++ ++2005-05-01 Richard M. Stallman ++ ++ * edebug.texi (Checking Whether to Stop): Fix previous change. ++ ++2005-05-01 Luc Teirlinck ++ ++ * display.texi: Fix typos and Texinfo usage. ++ ++ * edebug.texi (Checking Whether to Stop): executing-macro -> ++ executing-kbd-macro. ++ ++2005-05-01 Richard M. Stallman ++ ++ * display.texi (Invisible Text): Correct add-to-invisibility-spec. ++ ++2005-04-30 Richard M. Stallman ++ ++ * files.texi (Magic File Names): Document `operations' property. ++ ++2005-04-29 Lute Kamstra ++ ++ * modes.texi (Generic Modes): New node. ++ (Major Modes): Add it to the menu. ++ (Derived Modes): Add "derived mode" to concept index. ++ ++2005-04-28 Lute Kamstra ++ ++ * modes.texi (Defining Minor Modes): Fix previous change. ++ (Font Lock Mode): Simplify. ++ (Font Lock Basics): Say that font-lock-defaults is buffer-local ++ when set and that some parts are optional. Add cross references. ++ (Search-based Fontification): Say how to specify font-lock-keywords. ++ Add cross references. Add font-lock-multiline to index. ++ Move font-lock-keywords-case-fold-search here from node "Other Font ++ Lock Variables". Document font-lock-add-keywords and ++ font-lock-remove-keywords. ++ (Other Font Lock Variables): Move font-lock-keywords-only, ++ font-lock-syntax-table, font-lock-beginning-of-syntax-function, ++ and font-lock-syntactic-face-function to node "Syntactic Font ++ Lock". Move font-lock-keywords-case-fold-search to node ++ "Search-based Fontification". Document font-lock-inhibit-thing-lock ++ and font-lock-{,un}fontify-{buffer,region}-function. ++ (Precalculated Fontification): Remove reference to deleted variable ++ font-lock-core-only. ++ (Faces for Font Lock): Add font-lock-comment-delimiter-face. ++ (Syntactic Font Lock): Add intro. Move font-lock-keywords-only, ++ font-lock-syntax-table, font-lock-beginning-of-syntax-function, ++ and font-lock-syntactic-face-function here from node "Other Font ++ Lock Variables". Move font-lock-syntactic-keywords to "Setting ++ Syntax Properties". Add cross references. ++ (Setting Syntax Properties): New node. ++ Move font-lock-syntactic-keywords here from "Syntactic Font Lock". ++ * syntax.texi (Syntax Properties): Add cross reference. ++ * hooks.texi (Standard Hooks): Add Font-Lock hooks. ++ ++2005-04-26 Richard M. Stallman ++ ++ * display.texi (Defining Faces): ++ Document `default' elements of defface spec. ++ ++ * modes.texi (Major Mode Conventions): Explain customizing ElDoc mode. ++ ++ * variables.texi (Variable Aliases): Clarify text. ++ ++2005-04-25 Chong Yidong ++ ++ * windows.texi (Window Hooks): Remove reference to obsolete Lazy Lock. ++ ++2005-04-25 Luc Teirlinck ++ ++ * hooks.texi (Standard Hooks): Most minor modes have mode hooks too. ++ ++2005-04-24 Eli Zaretskii ++ ++ * syntax.texi (Syntax Table Internals): Elaborate documentation of ++ syntax-after and syntax-class. ++ ++ * files.texi (Changing Files): Fix last change's cross-reference. ++ (Unique File Names): Don't mention "numbers" in the documentation ++ of make-temp-file and make-temp-name. ++ ++2005-04-23 Richard M. Stallman ++ ++ * files.texi (Changing Files): Document MUSTBENEW arg in copy-file. ++ ++2005-04-22 Nick Roberts ++ ++ * windows.texi (Cyclic Window Ordering): Clarify window-list. ++ ++2005-04-22 Nick Roberts ++ ++ * variables.texi (Variable Aliases): Describe make-obsolete-variable ++ and define-obsolete-variable-alias. ++ ++2005-04-22 Kim F. Storm ++ ++ * symbols.texi (Symbol Plists): Remove safe-get, as get is now safe. ++ (Other Plists): Remove safe-plist-get, as plist-get is now safe. ++ ++2005-04-21 Lute Kamstra ++ ++ * lists.texi (Association Lists): Document rassq-delete-all. ++ ++2005-04-19 Richard M. Stallman ++ ++ * modes.texi (Search-based Fontification): Explain that ++ facespec is an expression to be evaluated. ++ ++2005-04-19 Kevin Ryde ++ ++ * streams.texi (Output Functions): Fix xref. ++ * strings.texi (String Conversion): Fix xref. ++ ++2005-04-19 Kim F. Storm ++ ++ * symbols.texi (Symbol Plists): Add safe-get. ++ Mention that `get' may signal an error. ++ ++2005-04-18 Nick Roberts ++ ++ * customize.texi (Variable Definitions): Replace tooltip-mode ++ example with save-place. ++ ++2005-04-17 Richard M. Stallman ++ ++ * buffers.texi (Indirect Buffers): Clarify. ++ ++ * positions.texi (Positions): Clarify converting marker to integer. ++ ++ * strings.texi (String Basics): Mention string-match; clarify. ++ ++2005-04-08 Lute Kamstra ++ ++ * modes.texi (Search-based Fontification): Fix cross references. ++ Use consistent terminology. Document anchored highlighting. ++ ++2005-04-05 Lute Kamstra ++ ++ * modes.texi (Defining Minor Modes): Document :group keyword ++ argument and its default value. ++ ++2005-04-03 Lute Kamstra ++ ++ * hooks.texi (Standard Hooks): Add some hooks. Add cross ++ references and/or descriptions. Delete major mode hooks; mention ++ them as a category instead. Rename or delete obsolete hooks. ++ ++2005-04-02 Richard M. Stallman ++ ++ * nonascii.texi (Coding System Basics): Another wording cleanup. ++ ++2005-04-01 Richard M. Stallman ++ ++ * nonascii.texi (Coding System Basics): Clarify previous change. ++ ++2005-04-01 Kenichi Handa ++ ++ * nonascii.texi (Coding System Basics): Describe about roundtrip ++ identity of coding systems. ++ ++2005-03-29 Chong Yidong ++ ++ * text.texi (Buffer Contents): Add filter-buffer-substring and ++ buffer-substring-filters. ++ ++2005-03-26 Chong Yidong ++ ++ * anti.texi (Antinews): Mention `G' interactive code. ++ ++ * tips.texi (Compilation Tips): Mention benchmark.el. ++ ++2005-03-27 Luc Teirlinck ++ ++ * modes.texi (Other Font Lock Variables): `font-lock-fontify-block' ++ is now bound to M-o M-o. ++ ++ * keymaps.texi (Prefix Keys): `facemenu-keymap' is now on M-o. ++ ++2005-03-26 Glenn Morris ++ ++ * calendar.texi: Delete file (and move contents to emacs-xtra.texi ++ in the Emacs Manual). ++ * Makefile.in (srcs): Remove calendar.texi. ++ * makefile.w32-in (srcs): Remove calendar.texi. ++ * display.texi (Display): Change name of next node. ++ * os.texi (System In): Change name of previous node. ++ * elisp.texi (Top): Remove Calendar references. ++ * vol1.texi (Top): Remove Calendar references. ++ * vol2.texi (Top): Remove Calendar references. ++ ++2005-03-25 Richard M. Stallman ++ ++ * display.texi (Standard Faces, Fringe Bitmaps, Customizing Bitmaps): ++ Cleanup previous change. ++ ++2005-03-25 Chong Yidong ++ ++ * display.texi (Face Attributes): Faces earlier in an :inherit ++ list take precedence. ++ (Scroll Bars): Fix description of vertical-scroll-bars. ++ Document frame-current-scroll-bars and window-current-scroll-bars. ++ ++ * markers.texi (The Mark): Document temporary Transient Mark mode. ++ ++ * minibuf.texi (Reading File Names): ++ Document read-file-name-completion-ignore-case. ++ ++ * positions.texi (Screen Lines): Document nil for width argument ++ to compute-motion. ++ ++2005-03-23 Kim F. Storm ++ ++ * display.texi (Standard Faces): Other faces used in the fringe ++ implicitly inherits from the fringe face. ++ (Fringe Bitmaps): FACE in right-fringe and left-fringe display ++ properties implicitly inherits from fringe face. ++ (Customizing Bitmaps): Likewise for set-fringe-bitmap-face. ++ ++2005-03-20 Chong Yidong ++ ++ * display.texi (Invisible Text): State default value of ++ line-move-ignore-invisible. ++ (Managing Overlays): Document remove-overlays. ++ (Standard Faces): Document escape-glyph face. ++ ++ * minibuf.texi (Reading File Names): Document read-file-name-function. ++ ++ * modes.texi (Other Font Lock Variables): ++ Document font-lock-lines-before. ++ ++ * positions.texi (Skipping Characters): skip-chars-forward allows ++ character classes. ++ ++2005-03-18 Lute Kamstra ++ ++ * edebug.texi (Instrumenting Macro Calls): Fix another typo. ++ ++2005-03-17 Richard M. Stallman ++ ++ * text.texi (Undo): Document extensible undo entries. ++ ++ * searching.texi (String Search, Regexp Search): Cleanups. ++ ++ * nonascii.texi (Character Codes): Minor fix. ++ ++ * display.texi (Display Property): Explain the significance ++ of having text properties that are eq. ++ (Other Display Specs): Explain string as display spec. ++ ++ * commands.texi (Interactive Codes): Document G option. ++ ++2005-03-17 Chong Yidong ++ ++ * text.texi (Filling): Add sentence-end-without-period and ++ sentence-end-without-space. ++ (Changing Properties): Minor fix. ++ ++ * anti.texi: Total rewrite. ++ ++2005-03-15 Lute Kamstra ++ ++ * edebug.texi (Instrumenting Macro Calls): Fix typos. ++ ++2005-03-08 Kim F. Storm ++ ++ * display.texi (Specified Space): Property :width is support on ++ non-graphic terminals, :height is not. ++ ++2005-03-07 Richard M. Stallman ++ ++ * display.texi (Overlay Arrow, Fringe Bitmaps, Customizing Bitmaps): ++ Now subnodes of Fringes. ++ (Overlay Arrow): Document overlay-arrow-variable-list. ++ (Fringe Size/Pos): New node, broken out of Fringes. ++ (Display): Explain clearing vs redisplay better. ++ (Truncation): Clarify use of bitmaps. ++ (The Echo Area): Clarify the uses of the echo area. ++ Add max-mini-window-height. ++ (Progress): Clarify. ++ (Invisible Text): Explain that main loop moves point out. ++ (Selective Display): Say "hidden", not "invisible". ++ (Managing Overlays): Move up. Describe relation to Undo here. ++ (Overlay Properties): Clarify intro. ++ (Finding Overlays): Explain return values when nothing found. ++ (Width): truncate-string-to-width has added arg. ++ (Displaying Faces): Clarify and update mode line face handling. ++ (Face Functions): Minor cleanup. ++ (Conditional Display): Merge into Other Display Specs. ++ (Pixel Specification, Other Display Specs): Minor cleanups. ++ (Images, Image Descriptors): Minor cleanups. ++ (GIF Images): Patents have expired. ++ (Showing Images): Explain default text for insert-image. ++ (Manipulating Button Types): Merge into Manipulating Buttons. ++ (Making Buttons): Explain return values. ++ (Button Buffer Commands): Add xref. ++ (Inverse Video): Update mode-line-inverse-video. ++ (Display Table Format): Clarify. ++ (Active Display Table): Give defaults for window-display-table. ++ ++ * calendar.texi (Calendar Customizing): calendar-holiday-marker ++ and calendar-today-marker are strings, not chars. ++ (Holiday Customizing): Minor fix. ++ ++ * internals.texi (Writing Emacs Primitives): Update `or' example. ++ Update limit on # args of subr. ++ ++ * edebug.texi (Using Edebug): Arrow is in fringe. ++ (Instrumenting): Arg to eval-defun works without loading edebug. ++ (Edebug Execution Modes): Add xref. ++ ++ * customize.texi (Common Keywords): Clarify :require. ++ Mention :version here. ++ (Variable Definitions, Group Definitions): Not here. ++ (Variable Definitions): Clarify symbol arg to :initialize and :set fns. ++ ++2005-03-07 Chong Yidong ++ * nonascii.texi (Text Representations): Clarify position-bytes. ++ (Character Sets): Add list-charset-chars. ++ (Scanning Charsets): Add charset-after. ++ (Encoding and I/O): Minor fix. ++ ++2005-03-06 Richard M. Stallman ++ ++ * windows.texi (Vertical Scrolling): Get rid of "Emacs 21". ++ (Resizing Windows): Likewise. ++ ++ * text.texi (Change Hooks): Get rid of "Emacs 21". ++ ++ * strings.texi (Formatting Strings): Get rid of "Emacs 21". ++ ++ * streams.texi (Output Variables): Get rid of "Emacs 21". ++ ++ * searching.texi (Regexp Special, Char Classes): Get rid of "Emacs 21". ++ ++ * os.texi (Translating Input): Replace flow-control example ++ with a less obsolete example that uses `keyboard-translate'. ++ ++ * objects.texi (Hash Table Type, Circular Objects): ++ Get rid of "Emacs 21". ++ ++ * modes.texi (Mode Line Format): Get rid of "Emacs 21". ++ (Mode Line Data, Properties in Mode, Header Lines): Likewise. ++ ++ * minibuf.texi (Minibuffer Misc): Get rid of "Emacs 21". ++ ++ * lists.texi (List Elements, Building Lists): Get rid of "Emacs 21". ++ ++ * keymaps.texi (Menu Separators, Tool Bar): Get rid of "Emacs 21". ++ (Menu Bar): Fix when menu-bar-update-hook is called. ++ ++ * hash.texi (Hash Tables): Get rid of "Emacs 21". ++ ++ * frames.texi (Text Terminal Colors): Get rid of "Emacs 21", ++ and make it read better. ++ ++ * files.texi (Writing to Files): Get rid of "Emacs 21". ++ (Unique File Names): Likewise. ++ ++ * elisp.texi: Update Emacs version to 22. ++ ++ * display.texi (Forcing Redisplay): Get rid of "Emacs 21". ++ (Overlay Properties, Face Attributes): Likewise. ++ (Managing Overlays): Fix punctuation. ++ (Attribute Functions): Clarify set-face-font; get rid of ++ info about old Emacs versions. ++ (Auto Faces, Font Lookup, Display Property, Images): ++ Get rid of "Emacs 21". ++ ++ * calendar.texi (Calendar Customizing): Get rid of "Emacs 21". ++ ++2005-03-05 Richard M. Stallman ++ ++ * debugging.texi (Error Debugging): Remove stack-trace-on-error. ++ ++2005-03-04 Lute Kamstra ++ ++ * debugging.texi (Error Debugging): Document stack-trace-on-error. ++ ++2005-03-03 Lute Kamstra ++ ++ * edebug.texi (Instrumenting Macro Calls): Fix typo. ++ ++2005-03-01 Lute Kamstra ++ ++ * debugging.texi (Debugger Commands): Update `j'. ++ ++2005-02-28 Lute Kamstra ++ ++ * debugging.texi (Debugging): Fix typo. ++ (Error Debugging): Document eval-expression-debug-on-error. ++ (Function Debugging): Update example. ++ (Using Debugger): Mention starred stack frames. ++ (Debugger Commands): Document `j' and `l'. ++ (Invoking the Debugger): `d' and `j' exit recursive edit too. ++ Update the messages that the debugger displays. ++ (Internals of Debugger): Add cross reference. Update example. ++ (Excess Open): Minor improvement. ++ (Excess Close): Minor improvement. ++ ++2005-02-26 Richard M. Stallman ++ ++ * tips.texi (Coding Conventions): Clarify. ++ Put all the major mode key reservations together. ++ Mention the Mouse-1 => Mouse-2 conventions. ++ ++ * syntax.texi (Syntax Class Table): Clarify. ++ (Syntax Table Functions): syntax-after moved from here. ++ (Syntax Table Internals): syntax-after moved to here. ++ (Parsing Expressions): Update info on number of values ++ and what's meaningful in the STATE argument. ++ (Categories): Fix typo. ++ ++ * sequences.texi (Arrays): Cleanup. ++ (Char-Tables): Clarify. ++ ++ * processes.texi (Deleting Processes): Cleanups, add xref. ++ (Subprocess Creation): Explain nil in exec-path. Cleanup. ++ (Process Information): set-process-coding-system, some args optional. ++ (Input to Processes): Explain various types for PROCESS args. ++ Rename them from PROCESS-NAME to PROCESS. ++ (Signals to Processes): Likewise. ++ (Decoding Output): Cleanup. ++ (Query Before Exit): Clarify. ++ ++ * os.texi (Startup Summary): Correct the options; add missing ones. ++ (Terminal Output, Batch Mode): Clarify. ++ (Flow Control): Node deleted. ++ ++ * markers.texi (The Mark): Clarify. ++ ++ * macros.texi (Expansion): Cleanup. ++ (Indenting Macros): indent-spec allows ints, not floats. ++ ++ * keymaps.texi (Keymaps): Clarify. ++ (Format of Keymaps): Update lisp-mode-map example. ++ (Active Keymaps, Key Lookup): Clarify. ++ (Changing Key Bindings): Add xref to `kbd'. ++ (Key Binding Commands, Simple Menu Items): Clarify. ++ (Mouse Menus, Menu Bar): Clarify. ++ (Menu Example): Replace print example with menu-bar-replace-menu. ++ ++ * help.texi (Documentation Basics): Add function-documentation prop. ++ ++ * elisp.texi (Top): Don't refer to Flow Control node. ++ ++ * commands.texi (Command Overview): Improve xrefs. ++ (Adjusting Point): Adjusting point applies to intangible and invis. ++ (Key Sequence Input): Doc extra read-key-sequence args. ++ Likewise for read-key-sequence-vector. ++ ++ * backups.texi (Rename or Copy): Minor fix. ++ (Numbered Backups): For version-control, say the default. ++ (Auto-Saving): make-auto-save-file-name example is simplified. ++ ++ * advice.texi (Advising Functions): Don't imply one part of Emacs ++ should advise another part. Markup changes. ++ (Defining Advice): Move transitional para. ++ (Activation of Advice): Cleanup. ++ Explain if COMPILE is nil or negative. ++ ++ * abbrevs.texi (Abbrev Expansion): Clarify, fix typo. ++ ++2005-02-24 Lute Kamstra ++ ++ * modes.texi (Defining Minor Modes): Explain that INIT-VALUE, ++ LIGHTER, and KEYMAP can be omitted when KEYWORD-ARGS are used. ++ ++2005-02-23 Lute Kamstra ++ ++ * modes.texi (Defining Minor Modes): define-minor-mode can be used ++ to define global minor modes as well. ++ ++ * display.texi (Managing Overlays): overlay-buffer returns nil for ++ deleted overlays. ++ ++2005-02-22 Kim F. Storm ++ ++ * minibuf.texi (Basic Completion): Allow symbols in addition to ++ strings in try-completion and all-completions. ++ ++2005-02-14 Lute Kamstra ++ ++ * elisp.texi (Top): Remove reference to deleted node. ++ ++ * lists.texi (Lists): Remove reference to deleted node. ++ (Cons Cells): Fix typo. ++ ++ * loading.texi (Where Defined): Fix typo. ++ ++2005-02-14 Richard M. Stallman ++ ++ * variables.texi (Creating Buffer-Local): change-major-mode-hook ++ is useful for discarding some minor modes. ++ ++ * symbols.texi (Symbol Components): Reorder examples. ++ ++ * streams.texi (Input Functions): State standard-input default. ++ (Output Variables): State standard-output default. ++ ++ * objects.texi (Printed Representation): Clarify read syntax vs print. ++ (Floating Point Type): Explain meaning better. ++ (Symbol Type): Explain uniqueness better. ++ (Cons Cell Type): Explain empty list sooner. CAR and CDR later. ++ List examples sooner. ++ (Box Diagrams): New subnode broken out. ++ Some examples moved from old Lists as Boxes node. ++ (Dotted Pair Notation): Clarify intro. ++ (Array Type): Clarify. ++ (Type Predicates): Add hash-table-p. ++ ++ * numbers.texi (Integer Basics): Clarify radix explanation. ++ (Predicates on Numbers): Minor clarification. ++ (Comparison of Numbers): Minor clarification. Clarify eql. ++ Typos in min, max. ++ (Math Functions): Clarify overflow in expt. ++ ++ * minibuf.texi (Text from Minibuffer): Minor clarification. ++ Mention arrow keys. ++ ++ * loading.texi (Autoload): defun's doc string overrides autoload's ++ doc string. ++ (Repeated Loading): Modernize "add to list" examples. ++ (Where Defined): Finish updating table of load-history elts. ++ ++ * lists.texi (List-related Predicates): Minor wording improvement. ++ (Lists as Boxes): Node deleted. ++ (Building Lists): Explain trivial cases of number-sequence. ++ ++ * hash.texi (Hash Tables): Add desc to menu items. ++ (Creating Hash): Explain "full" means "make larger". ++ (Hash Access): Any object can be a key. ++ State value of maphash. ++ ++ * functions.texi (What Is a Function): Wording cleanup. ++ (Function Documentation): Minor cleanup. ++ Explain purpose of calling convention at end of doc string. ++ (Function Names): Wording cleanup. ++ (Calling Functions): Wording cleanup. ++ Explain better how funcall calls the function. ++ (Function Cells): Delete example of saving and redefining function. ++ ++ * control.texi (Combining Conditions): Wording cleanup. ++ (Iteration): dolist and dotimes bind VAR locally. ++ (Cleanups): Xref to Atomic Changes. ++ ++ * compile.texi (Byte Compilation): Delete 19.29 info. ++ (Compilation Functions): Macros' difficulties don't affect defsubst. ++ (Docs and Compilation): Delete 19.29 info. ++ ++2005-02-10 Richard M. Stallman ++ ++ * objects.texi (Symbol Type): Minor correction. ++ ++2005-02-06 Lute Kamstra ++ ++ * modes.texi (Example Major Modes): Fix typos. ++ ++2005-02-06 Richard M. Stallman ++ ++ * text.texi (Margins): fill-nobreak-predicate can be one function. ++ ++ * strings.texi (Modifying Strings): clear-string can make unibyte. ++ (Formatting Strings): format gives error if values missing. ++ ++ * positions.texi (Character Motion): Mention default arg ++ for forward-char. backward-char refers to forward-char. ++ (Word Motion): Mention default arg for forward-word. ++ (Buffer End Motion): Mention default arg for beginning-of-buffer. ++ Simplify end-of-buffer. ++ (Text Lines): Mention default arg for forward-line. ++ (List Motion): Mention default arg for beginning/end-of-defun. ++ (Skipping Characters): Minor fixes in explaining character-set. ++ ++ * modes.texi (Major Mode Conventions): Mention "system abbrevs". ++ Mode inheritance applies only when default-major-mode is nil. ++ Clarifications. ++ (Example Major Modes): Update Text mode and Lisp mode examples. ++ (Minor Mode Conventions): Mention define-minor-mode at top. ++ (Defining Minor Modes): In Hungry example, don't define C-M-DEL. ++ (Mode Line Format): Update mode line face display info. ++ (Properties in Mode): Mention effect of risky vars. ++ (Imenu): Define imenu-add-to-menubar. ++ (Font Lock Mode): Add descriptions to menu lines. ++ (Faces for Font Lock): Add font-lock-doc-face. ++ ++2005-02-05 Lute Kamstra ++ ++ * text.texi (Maintaining Undo): Remove obsolete function. ++ ++2005-02-05 Eli Zaretskii ++ ++ * frames.texi (Color Names): Add pointer to the X docs about RGB ++ color specifications. Improve indexing ++ (Text Terminal Colors): Replace the description of RGB values by ++ an xref to "Color Names". ++ ++2005-02-03 Richard M. Stallman ++ ++ * windows.texi (Basic Windows): Add cursor-in-non-selected-windows. ++ Clarify. ++ (Selecting Windows): Clarify save-selected-window. ++ (Cyclic Window Ordering): Clarify walk-windows. ++ (Window Point): Clarify. ++ (Window Start): Add comment to example. ++ (Resizing Windows): Add `interactive' specs in examples. ++ Document fit-window-to-buffer. ++ ++ * text.texi (User-Level Deletion): just-one-space takes numeric arg. ++ (Undo, Maintaining Undo): Clarify last change. ++ (Sorting): In sort-numeric-fields, explain about octal and hex. ++ Mention sort-numeric-base. ++ (Format Properties): Add xref for hard newlines. ++ ++ * frames.texi (Window Frame Parameters): Explain pixel=char on tty. ++ (Pop-Up Menus): Fix typo. ++ (Color Names): Explain all types of color names. ++ Explain color-values on B&W terminal. ++ (Text Terminal Colors): Explain "rgb values" are lists. Fix arg names. ++ ++ * files.texi (File Locks): Not supported on MS systems. ++ (Testing Accessibility): Clarify. ++ ++ * edebug.texi (Printing in Edebug): Fix edebug-print-circle. ++ (Coverage Testing): Fix typo. ++ ++ * commands.texi (Misc Events): Remove stray space. ++ ++ * buffers.texi (Buffer Names): Clarify generate-new-buffer-name. ++ (Modification Time): Clarify when visited-file-modtime returns 0. ++ (The Buffer List): Clarify bury-buffer. ++ (Killing Buffers): Clarify. ++ (Indirect Buffers): Add clone-indirect-buffer. ++ ++2005-02-02 Matt Hodges ++ ++ * edebug.texi (Printing in Edebug): Fix default value of ++ edebug-print-circle. ++ (Coverage Testing): Fix displayed frequency count data. ++ ++2005-02-02 Luc Teirlinck ++ ++ * text.texi (Maintaining Undo): Add `undo-outer-limit'. ++ ++2005-02-02 Kim F. Storm ++ ++ * text.texi (Undo) : Describe `apply' elements. ++ ++2005-01-29 Eli Zaretskii ++ ++ * commands.texi (Misc Events): Describe the help-echo event. ++ ++ * text.texi (Special Properties) : Use `pos' ++ consistently in description of the help-echo property. ++ Use @code{nil} instead of @var{nil}. ++ ++ * display.texi (Overlay Properties): Fix the index entry for ++ help-echo overlay property. ++ ++ * customize.texi (Type Keywords): Uncomment the xref to the ++ help-echo property documentation. ++ ++2005-01-23 Kim F. Storm ++ ++ * windows.texi (Window Start): Fix `pos-visible-in-window-p' ++ return value. Third element FULLY replaced by PARTIAL which ++ specifies number of invisible pixels if row is only partially visible. ++ (Textual Scrolling): Mention auto-window-vscroll. ++ (Vertical Scrolling): New defvar auto-window-vscroll. ++ ++2005-01-16 Luc Teirlinck ++ ++ * keymaps.texi (Changing Key Bindings): `suppress-keymap' now uses ++ command remapping. ++ ++2005-01-15 Richard M. Stallman ++ ++ * display.texi (Defining Images): Mention DATA-P arg of create-image. ++ ++2005-01-14 Kim F. Storm ++ ++ * commands.texi (Accessing Events): Add WHOLE arg to posn-at-x-y. ++ ++ * text.texi (Links and Mouse-1): Fix string and vector item. ++ ++2005-01-13 Richard M. Stallman ++ ++ * keymaps.texi (Active Keymaps): Rewrite the text, and update the ++ descriptions of overriding-local-map and overriding-terminal-local-map. ++ ++ * text.texi (Links and Mouse-1): Clarify text. ++ ++2005-01-13 Kim F. Storm ++ ++ * modes.texi (Emulating Mode Line): Update format-mode-line entry. ++ ++2005-01-13 Francis Litterio (tiny change) ++ ++ * keymaps.texi (Active Keymaps): Fix overriding-local-map description. ++ ++2005-01-12 Kim F. Storm ++ ++ * text.texi (Links and Mouse-1): Rename section from Enabling ++ Mouse-1 to Following Links. Change xrefs. ++ Add examples for define-button-type and define-widget. ++ ++ * display.texi (Button Properties, Button Buffer Commands): ++ Clarify mouse-1 and follow-link functionality. ++ ++2005-01-12 Richard M. Stallman ++ ++ * text.texi (Enabling Mouse-1 to Follow Links): Redo prev. change. ++ ++ * display.texi (Beeping): Fix Texinfo usage. ++ ++ * modes.texi (Emulating Mode Line): Doc FACE arg in format-header-line. ++ ++2005-01-11 Kim F. Storm ++ ++ * display.texi (Button Properties, Button Buffer Commands): ++ Mention mouse-1 binding. Add follow-link keyword. ++ ++ * text.texi (Text Properties): Add "Enable Mouse-1" to submenu. ++ (Enabling Mouse-1 to Follow Links): New subsection. ++ ++2005-01-06 Richard M. Stallman ++ ++ * text.texi (Special Properties): Minor change. ++ ++ * os.texi (Timers): Clarify previous change. ++ ++ * modes.texi (Emulating Mode Line): format-mode-line requires 1 arg. ++ ++2005-01-01 Luc Teirlinck ++ ++ * display.texi (Face Attributes): Correct xref to renamed node. ++ ++2005-01-01 Richard M. Stallman ++ ++ * display.texi (Face Attributes): Describe hex color specs. ++ ++2004-12-31 Richard M. Stallman ++ ++ * os.texi (Timers): Update previous change. ++ ++2004-12-30 Kim F. Storm ++ ++ * display.texi (Line Height): Total line-height is now specified ++ in line-height property of form (HEIGHT TOTAL). Swap (FACE . RATIO) ++ in cons cells. (nil . RATIO) is relative to actual line height. ++ Use line-height `t' instead of `0' to get minimum height. ++ ++2004-12-29 Richard M. Stallman ++ ++ * os.texi (Timers): Discuss timers vs editing the buffer and undo. ++ ++2004-12-28 Richard M. Stallman ++ ++ * commands.texi (Quitting): Clarify value of with-local-quit. ++ ++ * elisp.texi (Top): Fix previous change. ++ ++ * loading.texi (Loading): Fix previous change. ++ ++2004-12-27 Richard M. Stallman ++ ++ * Makefile.in (MAKEINFO): Specify --force. ++ ++ * buffers.texi (Killing Buffers): Add buffer-save-without-query. ++ ++ * modes.texi (Emulating Mode Line): Document format's BUFFER arg. ++ ++ * display.texi (Line Height): Further clarify. ++ ++ * elisp.texi (Top): Update Loading submenu. ++ ++ * loading.texi (Where Defined): New node. ++ (Unloading): load-history moved to Where Defined. ++ ++2004-12-21 Richard M. Stallman ++ ++ * commands.texi (Event Input Misc): Add while-no-input. ++ ++2004-12-11 Richard M. Stallman ++ ++ * display.texi (Line Height): Rewrite text for clarity. ++ ++2004-12-11 Kim F. Storm ++ ++ * display.texi (Display): Add node "Line Height" to menu. ++ (Line Height): New node. Move full description of line-spacing ++ and line-height text properties here from text.texi. ++ (Scroll Bars): Add vertical-scroll-bar variable. ++ ++ * frames.texi (Window Frame Parameters): Remove line-height defvar. ++ ++ * locals.texi (Standard Buffer-Local Variables): Fix xref for ++ line-spacing and vertical-scroll-bar. ++ ++ * text.texi (Special Properties): Just mention line-spacing and ++ line-height here, add xref to new "Line Height" node. ++ ++2004-12-09 Thien-Thi Nguyen ++ ++ * frames.texi (Window Frame Parameters): New @defvar for `line-spacing'. ++ ++ * locals.texi (Standard Buffer-Local Variables): ++ Add @xref for `line-spacing'. ++ ++2004-12-05 Richard M. Stallman ++ ++ * Makefile.in (maintainer-clean): Remove the info files ++ in $(infodir) where they are created. ++ ++2004-12-03 Richard M. Stallman ++ ++ * windows.texi (Selecting Windows): get-lru-window and ++ get-largest-window don't consider dedicated windows. ++ ++ * text.texi (Undo): Document undo-in-progress. ++ ++2004-11-26 Richard M. Stallman ++ ++ * locals.texi (Standard Buffer-Local Variables): Undo prev change. ++ Remove a few vars that are not always buffer-local. ++ ++2004-11-24 Luc Teirlinck ++ ++ * locals.texi (Standard Buffer-Local Variables): Comment out ++ xref's to non-existent node `Yet to be written'. ++ ++2004-11-24 Richard M. Stallman ++ ++ * processes.texi (Synchronous Processes): Grammar fix. ++ ++ * numbers.texi (Comparison of Numbers): Add eql. ++ ++ * locals.texi (Standard Buffer-Local Variables): Add many vars. ++ ++ * intro.texi (Printing Notation): Fix previous change. ++ ++ * display.texi (Customizing Bitmaps): Move indicate-buffer-boundaries ++ and default-indicate-buffer-boundaries from here. ++ (Usual Display): To here. ++ (Scroll Bars): Add scroll-bar-mode and scroll-bar-width. ++ (Usual Display): Move tab-width up. ++ ++ * customize.texi (Variable Definitions): Replace ++ show-paren-mode example with tooltip-mode. ++ (Simple Types, Composite Types, Defining New Types): ++ Minor cleanups. ++ ++2004-11-21 Jesper Harder ++ ++ * processes.texi (Synchronous Processes, Output from Processes): ++ Markup fix. ++ ++2004-11-20 Richard M. Stallman ++ ++ * positions.texi (Skipping Characters): skip-chars-forward ++ now handles char classes. ++ ++ * intro.texi (Printing Notation): Avoid confusion of `print' ++ when explaining @print. ++ ++ * macros.texi (Argument Evaluation): Fix 1st `for' expansion example. ++ ++ * display.texi (Display Table Format): Minor fix. ++ ++ * streams.texi (Output Functions): Fix print example. ++ ++ * Makefile.in (elisp): New target. ++ (dist): Depend on $(infodir)/elisp, not elisp. ++ Copy the info files from $(infodir). ++ ++ * minibuf.texi (Text from Minibuffer): Document KEEP-ALL arg in ++ read-from-minibuffer. ++ ++ * searching.texi (Regexp Search): Rename that to search-spaces-regexp. ++ ++2004-11-19 Richard M. Stallman ++ ++ * searching.texi (Regexp Search): Add search-whitespace-regexp. ++ ++2004-11-19 CHENG Gao (tiny change) ++ ++ * tips.texi (Coding Conventions): Fix typo. ++ ++2004-11-16 Richard M. Stallman ++ ++ * tips.texi (Coding Conventions): Separate defvar and require ++ methods to avoid warnings. Use require only when there are many ++ functions and variables from that package. ++ ++ * minibuf.texi (Minibuffer Completion): When ignoring case, ++ predicate must not be case-sensitive. ++ ++ * debugging.texi (Function Debugging, Explicit Debug): Clarified. ++ (Test Coverage): Don't talk about "splotches". Clarified. ++ ++2004-11-16 Thien-Thi Nguyen ++ ++ * frames.texi (Window Frame Parameters): Fix typo. ++ ++2004-11-15 Kim F. Storm ++ ++ * symbols.texi (Other Plists): Note that plist-get may signal error. ++ Add safe-plist-get. ++ ++2004-11-15 Thien-Thi Nguyen ++ ++ * modes.texi (Font Lock Basics): Fix typo. ++ ++2004-11-08 Richard M. Stallman ++ ++ * syntax.texi (Syntax Table Functions): Add syntax-after. ++ ++2004-11-06 Lars Brinkhoff ++ ++ * os.texi (Processor Run Time): New section documenting ++ get-internal-run-time. ++ ++2004-11-06 Eli Zaretskii ++ ++ * Makefile.in (install, maintainer-clean): Don't use "elisp-*" as ++ it nukes elisp-cover.texi. ++ (dist): Change elisp-[0-9] to elisp-[1-9], as there could be no ++ elisp-0 etc. ++ ++2004-11-05 Luc Teirlinck ++ ++ * commands.texi (Keyboard Macros): Document `append' return value ++ of `defining-kbd-macro'. ++ ++2004-11-01 Richard M. Stallman ++ ++ * commands.texi (Interactive Call): Add called-interactively-p. ++ ++2004-10-29 Simon Josefsson ++ ++ * minibuf.texi (Reading a Password): Revert. ++ ++2004-10-28 Richard M. Stallman ++ ++ * frames.texi (Display Feature Testing): Explain about "vendor". ++ ++2004-10-27 Richard M. Stallman ++ ++ * commands.texi (Interactive Codes): `N' uses numeric prefix, ++ not raw. Clarify `n'. ++ (Interactive Call): Rewrite interactive-p, focusing on when ++ and how to use it. ++ (Misc Events): Clarify previous change. ++ ++ * advice.texi (Simple Advice): Clarify what job the example does. ++ (Around-Advice): Clarify ad-do-it. ++ (Activation of Advice): An option of ad-default-compilation-action ++ is `never', not `nil'. ++ ++2004-10-26 Kim F. Storm ++ ++ * commands.texi (Interactive Codes): Add U code letter. ++ ++2004-10-25 Simon Josefsson ++ ++ * minibuf.texi (Reading a Password): Add. ++ ++2004-10-24 Jason Rumney ++ ++ * commands.texi (Misc Events): Remove mouse-wheel. Add wheel-up ++ and wheel-down. ++ ++2004-10-24 Kai Grossjohann ++ ++ * processes.texi (Synchronous Processes): Document process-file. ++ ++2004-10-22 Kenichi Handa ++ ++ * text.texi (translate-region): Document that it accepts also a ++ char-table. ++ ++2004-10-22 David Ponce ++ ++ * windows.texi (Resizing Windows): Document the `preserve-before' ++ argument of the functions `enlarge-window' and `shrink-window'. ++ ++2004-10-19 Jason Rumney ++ ++ * makefile.w32-in (elisp): Change order of arguments to makeinfo. ++ ++2004-10-09 Luc Teirlinck ++ ++ * text.texi (Filling): Add anchor for definition of ++ `sentence-end-double-space'. ++ ++ * searching.texi (Regexp Example): Update description of how ++ Emacs currently recognizes the end of a sentence. ++ (Standard Regexps): Update definition of the variable ++ `sentence-end'. Add definition of the function `sentence-end'. ++ ++2004-10-08 Paul Pogonyshev ++ ++ * display.texi (Progress): New node. ++ ++2004-10-05 Kim F. Storm ++ ++ * display.texi (Fringe Bitmaps): Update fringe-bitmaps-at-pos. ++ ++2004-09-29 Kim F. Storm ++ ++ * display.texi (Fringe Bitmaps): Use symbols rather than numbers ++ to identify bitmaps. Remove -fringe-bitmap suffix for standard ++ fringe bitmap symbols, as they now have their own namespace. ++ (Customizing Bitmaps) : Clarify bit ordering ++ vs. pixels. Signal error if no free bitmap slots. ++ (Pixel Specification): Change IMAGE to @var{image}. ++ ++2004-09-28 Richard M. Stallman ++ ++ * text.texi (Special Properties): Clarify line-spacing and line-height. ++ ++ * searching.texi (Regexp Search): Add looking-back. ++ ++2004-09-25 Luc Teirlinck ++ ++ * display.texi: Correct typos. ++ (Image Descriptors): Correct xref's. ++ ++2004-09-25 Richard M. Stallman ++ ++ * text.texi (Special Properties): Cleanups in `cursor'. ++ Rewrites in `line-height' and `line-spacing'; exchange them. ++ ++ * display.texi (Fringes): Rewrite previous change. ++ (Fringe Bitmaps): Merge text from Display Fringe Bitmaps. Rewrite. ++ (Display Fringe Bitmaps): Node deleted, text moved. ++ (Customizing Bitmaps): Split off from Fringe Bitmaps. Rewrite. ++ (Scroll Bars): Clarify set-window-scroll-bars. ++ (Pointer Shape): Rewrite. ++ (Specified Space): Clarify :align-to, etc. ++ (Pixel Specification): Use @var. Clarify new text. ++ (Other Display Specs): Clarify `slice'. ++ (Image Descriptors): Cleanups. ++ (Showing Images): Cleanups. ++ ++2004-09-24 Luc Teirlinck ++ ++ * hooks.texi (Standard Hooks): Add `after-change-major-mode-hook'. ++ ++ * modes.texi: Various minor changes in addition to: ++ (Major Mode Conventions): Final call to `run-mode-hooks' should ++ not be inside the `delay-mode-hooks' form. ++ (Mode Hooks): New node. ++ (Hooks): Delete obsolete example. ++ Move definitions of `run-mode-hooks' and `delay-mode-hooks' to new ++ node "Mode Hooks". ++ ++2004-09-22 Luc Teirlinck ++ ++ * display.texi: Correct various typos. ++ (Display): Rename node "Pointer Shapes" to "Pointer ++ Shape". (There is already a node called "Pointer Shapes" in ++ frames.texi.) ++ (Images): Remove non-existent node "Image Slices" from menu. ++ ++2004-09-23 Kim F. Storm ++ ++ * text.texi (Special Properties): Add `cursor', `pointer', ++ `line-height', and `line-spacing' properties. ++ ++ * display.texi (Display): Add 'Fringe Bitmaps' and 'Pointer ++ Shapes' to menu. ++ (Standard Faces): Doc fix for fringe face. ++ (Fringes): Add `overflow-newline-into-fringe' and ++ 'indicate-buffer-boundaries'. ++ (Fringe Bitmaps, Pointer Shapes): New nodes. ++ (Display Property): Add 'Pixel Specification' and 'Display Fringe ++ Bitmaps' to menu. ++ (Specified Space): Describe pixel width and height. ++ (Pixel Specification): New node. ++ (Other Display Specs): Add `slice' property. ++ (Display Fringe Bitmaps): New node. ++ (Images): Add 'Image Slices' to menu. ++ (Image Descriptors): Add `:pointer' and `:map' properties. ++ (Showing Images): Add slice arg to `insert-image'. Add ++ 'insert-sliced-image'. ++ ++2004-09-20 Richard M. Stallman ++ ++ * commands.texi (Key Sequence Input): ++ Clarify downcasing in read-key-sequence. ++ ++2004-09-08 Juri Linkov ++ ++ * minibuf.texi (Minibuffer History): Add `history-delete-duplicates'. ++ ++2004-09-07 Luc Teirlinck ++ ++ * locals.texi (Standard Buffer-Local Variables): Add ++ `buffer-auto-save-file-format'. ++ * internals.texi (Buffer Internals): Describe new ++ auto_save_file_format field of the buffer structure. ++ * files.texi (Format Conversion): `auto-save-file-format' has been ++ renamed `buffer-auto-save-file-format'. ++ ++2004-08-27 Luc Teirlinck ++ ++ * abbrevs.texi (Abbrev Expansion): `abbrev-start-location' can be ++ an integer or a marker. ++ (Abbrev Expansion): Replace example for `pre-abbrev-expand-hook'. ++ ++2004-08-22 Richard M. Stallman ++ ++ * modes.texi (Major Mode Conventions): Discuss rebinding of ++ standard key bindings. ++ ++2004-08-18 Kim F. Storm ++ ++ * processes.texi (Accepting Output): Add `just-this-one' arg to ++ `accept-process-output'. ++ (Output from Processes): New var `process-adaptive-read-buffering'. ++ ++2004-08-10 Luc Teirlinck ++ ++ * keymaps.texi: Various changes in addition to: ++ (Keymap Terminology): `kbd' uses same syntax as Edit Macro mode. ++ Give more varied examples for `kbd'. ++ (Creating Keymaps): Char tables have slots for all characters ++ without modifiers. ++ (Active Keymaps): `overriding-local-map' and ++ `overriding-terminal-local-map' also override text property and ++ overlay keymaps. ++ (Functions for Key Lookup): Mention OLP arg to `current-active-maps'. ++ (Scanning Keymaps): `accessible-keymaps' uses `[]' instead of `""' ++ to denote a prefix of no events. ++ `map-keymap' includes parent's bindings _recursively_. ++ Clarify and correct description of `where-is-internal'. ++ Mention BUFFER-OR-NAME arg to `describe-bindings'. ++ (Menu Example): For menus intended for use with the keyboard, the ++ menu items should be bound to characters or real function keys. ++ ++2004-08-08 Luc Teirlinck ++ ++ * objects.texi (Character Type): Reposition `@anchor' to prevent ++ double space inside sentence in Info. ++ ++ * hooks.texi (Standard Hooks): `disabled-command-hook' has been ++ renamed to `disabled-command-function'. ++ * commands.texi (Key Sequence Input): Remove unnecessary anchor. ++ (Command Loop Info): Replace reference to it. ++ (Disabling Commands): `disabled-command-hook' has been renamed to ++ `disabled-command-function'. ++ ++2004-08-07 Luc Teirlinck ++ ++ * os.texi (Translating Input): Only non-prefix bindings in ++ `key-translation-map' override actual key bindings. Warn about ++ possible indirect effect of actual key bindings on non-prefix ++ bindings in `key-translation-map'. ++ ++2004-08-06 Luc Teirlinck ++ ++ * minibuf.texi (High-Level Completion): Add anchor for definition ++ of `read-variable'. ++ ++ * commands.texi: Various changes in addition to: ++ (Using Interactive): Clarify description of `interactive-form'. ++ (Interactive Call): Mention default for KEYS argument to ++ `call-interactively'. ++ (Command Loop Info): Clarify description of `this-command-keys'. ++ Mention KEEP-RECORD argument to `clear-this-command-keys'. ++ Value of `last-event-frame' can be `macro'. ++ (Repeat Events): `double-click-fuzz' is also used to distinguish ++ clicks and drags. ++ (Classifying Events): Clarify descriptions of `event-modifiers' ++ `event-basic-type' and `event-convert-list'. ++ (Accessing Events): `posn-timestamp' takes POSITION argument. ++ (Quoted Character Input): Clarify description of ++ `read-quoted-char' and fix example. ++ (Quitting): Add `with-local-quit'. ++ (Disabling Commands): Correct and clarify descriptions of ++ `enable-command' and `disable-command'. ++ Mention what happens if `disabled-command-hook' is nil. ++ (Keyboard Macros): Mention LOOPFUNC arg to `execute-kbd-macro'. ++ Describe `executing-kbd-macro' instead of obsolete `executing-macro'. ++ ++2004-07-24 Luc Teirlinck ++ ++ * frames.texi: Various changes in addition to: ++ (Creating Frames): Expand and clarify description of `make-frame'. ++ (Window Frame Parameters): Either none or both of the `icon-left' ++ and `icon-top' parameters must be specified. Put descriptions of ++ `menu-bar-lines' and `toolbar-lines' closer together and change ++ them accordingly. ++ (Frame Titles): `multiple-frames' is not guaranteed to be accurate ++ except while processing `frame-title-format' or `icon-title-format'. ++ (Deleting Frames): Correct description of `delete-frame'. ++ Non-nil return values of `frame-live-p' are like those of `framep'. ++ (Frames and Windows): Mention return value of ++ `set-frame-selected-window'. ++ (Visibility of Frames): Mention `force' argument to ++ `make-frame-invisible'. `frame-visible-p' returns t for all ++ frames on text-only terminals. ++ (Frame Configurations): Restoring a frame configuration does not ++ restore deleted frames. ++ (Window System Selections): `x-set-selection' returns DATA. ++ (Resources): Add example. ++ (Display Feature Testing): Clarify descriptions of ++ `display-pixel-height', `display-pixel-width', `x-server-version' ++ and `x-server-vendor'. ++ ++ * windows.texi (Choosing Window): Add anchor. ++ * minibuf.texi (Minibuffer Misc): Add anchor. ++ ++2004-07-23 John Paul Wallington ++ ++ * macros.texi (Defining Macros): Declaration keyword for setting ++ Edebug spec is `debug' not `edebug'. ++ ++2004-07-19 Luc Teirlinck ++ ++ * windows.texi: Various small changes in addition to: ++ (Window Point): Mention return value of `set-window-point'. ++ (Window Start): `pos-visible-in-window-p' disregards horizontal ++ scrolling. Explain return value if PARTIALLY is non-nil. ++ (Vertical Scrolling): Mention PIXELS-P argument to `window-vscroll' ++ and `set-window-vscroll'. ++ (Size of Window): The argument WINDOW to `window-inside-edges', ++ `window-pixel-edges' and `window-inside-pixel-edges' is optional. ++ (Resizing Windows): Explain return value of ++ `shrink-window-if-larger-than-buffer'. ++ `window-size-fixed' automatically becomes buffer local when set. ++ (Window Configurations): Explain return value of ++ `set-window-configuration'. ++ ++ * minibuf.texi (Minibuffer Misc): Add anchor for ++ `minibuffer-scroll-window'. ++ ++ * positions.texi (Text Lines): Add anchor for `count-lines'. ++ ++2004-07-17 Richard M. Stallman ++ ++ * display.texi (Overlay Properties): Adding `evaporate' prop ++ deletes empty overlay immediately. ++ ++ * abbrevs.texi (Abbrev Expansion): Clarify pre-abbrev-expand-hook, ++ fix example. ++ ++2004-07-16 Jim Blandy ++ ++ * searching.texi (Regexp Backslash): Document new \_< and \_> ++ operators. ++ ++2004-07-16 Juanma Barranquero ++ ++ * display.texi (Images): Fix Texinfo usage. ++ ++2004-07-14 Luc Teirlinck ++ ++ * buffers.texi (Modification Time): `visited-file-modtime' now ++ returns a list of two integers, instead of a cons. ++ ++2004-07-13 Luc Teirlinck ++ ++ * windows.texi: Various changes in addition to: ++ (Splitting Windows): Add `split-window-keep-point'. ++ ++2004-07-09 Richard M. Stallman ++ ++ * frames.texi (Input Focus): Minor fix. ++ ++2004-07-07 Luc Teirlinck ++ ++ * frames.texi (Input Focus): Clarify descriptions of ++ `select-frame-set-input-focus' and `select-frame'. ++ ++2004-07-06 Luc Teirlinck ++ ++ * os.texi: Various small changes in addition to: ++ (Killing Emacs): Expand and clarify description of ++ `kill-emacs-query-functions' and `kill-emacs-hook'. ++ (System Environment): Expand and clarify description of `getenv' ++ and `setenv'. ++ (Timers): Clarify description of `run-at-time'. ++ (Translating Input): Correct description of ++ `extra-keyboard-modifiers'. ++ (Flow Control): Correct description of `enable-flow-control'. ++ ++2004-07-06 Thien-Thi Nguyen ++ ++ * os.texi: Update copyright. ++ (Session Management): Grammar fix. ++ Clarify which Emacs does the restarting. ++ Use @samp for *scratch* buffer. ++ ++2004-07-04 Alan Mackenzie ++ ++ * frames.texi (Input Focus): Add documentation for ++ `select-frame-set-input-focus'. Replace refs to non-existent ++ `switch-frame' with `select-frame'. Minor corrections and tidying ++ up of text-only terminal stuff. ++ ++2004-07-02 Richard M. Stallman ++ ++ * files.texi (Saving Buffers): Cleanup write-contents-function. ++ (Magic File Names): Cleanup file-remote-p. ++ ++2004-07-02 Kai Großjohann ++ ++ * files.texi (Magic File Names): `file-remote-p' returns an ++ identifier of the remote system, not just t. ++ ++2004-07-02 David Kastrup ++ ++ * searching.texi (Entire Match Data): Add explanation about new ++ match-data behavior when @var{integers} is non-nil. ++ ++2004-06-24 Richard M. Stallman ++ ++ * commands.texi (Misc Events): Describe usr1-signal, usr2-signal event. ++ ++ * customize.texi (Variable Definitions): Note about doc strings ++ and :set. ++ ++ * keymaps.texi (Keymap Terminology): Document `kbd'. ++ (Changing Key Bindings, Key Binding Commands): Use kbd in examples. ++ ++ * display.texi (Invisible Text): Setting buffer-invisibility-spec ++ makes it buffer-local. ++ ++ * files.texi (Saving Buffers): Correct previous change. ++ ++ * commands.texi (Accessing Events): ++ Clarify posn-col-row and posn-actual-col-row. ++ ++2004-06-24 David Ponce ++ ++ * commands.texi (Accessing Events): New functions ++ posn-at-point and posn-at-x-y. Add example to posn-x-y. ++ ++2004-06-23 Luc Teirlinck ++ ++ * lists.texi, files.texi, processes.texi, macros.texi, hash.texi: ++ * frames.texi, buffers.texi, backups.texi, variables.texi: ++ * loading.texi, eval.texi, functions.texi, control.texi: ++ * symbols.texi, minibuf.texi: Reposition @anchor's. ++ ++ * help.texi: Various small changes in addition to the following. ++ (Describing Characters): Describe PREFIX argument to ++ `key-description'. Correct and clarify definition of ++ `text-char-description'. Describe NEED-VECTOR argument to ++ `read-kbd-macro'. ++ (Help Functions): Clarify definition of `apropos'. ++ ++2004-06-23 Lars Hansen ++ ++ * files.texi (Saving Buffers): Correct description of ++ `write-contents-functions'. ++ ++2004-06-21 Juanma Barranquero ++ ++ * display.texi (Images): Remove redundant @vindex directives. ++ Rewrite `image-library-alist' doc in active voice. ++ ++2004-06-14 Juanma Barranquero ++ ++ * display.texi (Images): Document new delayed library loading, ++ variable `image-library-alist' and (existing but undocumented) ++ function `image-type-available-p'. ++ ++2004-06-05 Richard M. Stallman ++ ++ * minibuf.texi (Minibuffer Completion): For INITIAL arg, ++ refer the user to the Initial Input node. ++ (Text from Minibuffer): Likewise. ++ (Initial Input): New node. Document this feature ++ and say it is mostly deprecated. ++ ++2004-05-30 Richard M. Stallman ++ ++ * loading.texi (Named Features): Clarify return value ++ and meaning of NOERROR. ++ ++ * variables.texi (File Local Variables): Minor cleanup. ++ ++2004-05-30 Michael Albinus ++ ++ * files.texi (Magic File Names): Add `file-remote-p' as operation ++ of file name handlers. ++ ++2004-05-29 Richard M. Stallman ++ ++ * modes.texi (Minor Mode Conventions): (-) has no special meaning ++ as arg to a minor mode command. ++ ++2004-05-22 Richard M. Stallman ++ ++ * syntax.texi (Syntax Class Table): Word syntax not just for English. ++ ++ * streams.texi (Output Variables): Doc float-output-format. ++ ++ * searching.texi (Regexp Special): Nested repetition can be infloop. ++ ++ * eval.texi (Eval): Increasing max-lisp-eval-depth can cause ++ real stack overflow. ++ ++ * compile.texi: Minor cleanups. ++ ++2004-05-22 Luc Teirlinck ++ ++ * lists.texi (Cons Cells): Explain dotted lists, true lists, ++ circular lists. ++ (List Elements): Explain handling of circular and dotted lists. ++ ++2004-05-19 Thien-Thi Nguyen ++ ++ * modes.texi (Search-based Fontification): Fix typo. ++ ++2004-05-10 Juanma Barranquero ++ ++ * modes.texi (Mode Line Variables): Fix description of ++ global-mode-string, which is now after which-func-mode, not the ++ buffer name. ++ ++2004-05-07 Lars Hansen ++ ++ * modes.texi (Desktop Save Mode): Add. ++ (Modes): Add menu entry Desktop Save Mode. ++ ++ * hooks.texi: Add desktop-after-read-hook, ++ desktop-no-desktop-file-hook and desktop-save-hook. ++ ++ * locals.texi: Add desktop-save-buffer. ++ ++2004-04-30 Jesper Harder ++ ++ * display.texi: emacs -> Emacs. ++ ++2004-04-27 Matthew Mundell ++ ++ * files.texi (Changing Files): Document set-file-times. ++ ++2004-04-23 Juanma Barranquero ++ ++ * makefile.w32-in: Add "-*- makefile -*-" mode tag. ++ ++2004-04-18 Jesper Harder ++ ++ * tips.texi (Coding Conventions): defopt -> defcustom. ++ ++2004-04-16 Luc Teirlinck ++ ++ * sequences.texi: Various clarifications. ++ ++2004-04-14 Luc Teirlinck ++ ++ * buffers.texi (Read Only Buffers): Mention optional ARG to ++ `toggle-read-only'. ++ ++2004-04-14 Nick Roberts ++ ++ * windows.texi (Selecting Windows): Note that get-lru-window ++ returns a full-width window if possible. ++ ++2004-04-13 Luc Teirlinck ++ ++ * buffers.texi: Various changes in addition to: ++ (Buffer File Name): Add `find-buffer-visiting'. ++ (Buffer Modification): Mention optional ARG to `not-modified'. ++ (Indirect Buffers): Mention optional CLONE argument to ++ `make-indirect-buffer'. ++ ++ * files.texi: Various changes in addition to: ++ (Visiting Functions): `find-file-hook' is now a normal hook. ++ (File Name Expansion): Explain difference between the way that ++ `expand-file-name' and `file-truename' treat `..'. ++ (Contents of Directories): Mention optional ID-FORMAT argument to ++ `directory-files-and-attributes'. ++ (Format Conversion): Mention new optional CONFIRM argument to ++ `format-write-file'. ++ ++2004-04-12 Miles Bader ++ ++ * macros.texi (Expansion): Add description of `macroexpand-all'. ++ ++2004-04-05 Jesper Harder ++ ++ * variables.texi (Variable Aliases): Mention ++ cyclic-variable-indirection. ++ ++ * errors.texi (Standard Errors): Ditto. ++ ++2004-04-04 Luc Teirlinck ++ ++ * backups.texi: Various small changes in addition to: ++ (Making Backups): Mention return value of `backup-buffer'. ++ (Auto-Saving): Mention optional FORCE argument to ++ `delete-auto-save-file-if-necessary'. ++ (Reverting): Mention optional PRESERVE-MODES argument to ++ `revert-buffer'. Correct description of `revert-buffer-function'. ++ ++2004-03-22 Juri Linkov ++ ++ * sequences.texi (Sequence Functions): Replace xref to `Vectors' ++ with `Vector Functions'. ++ ++ * text.texi (Sorting): Add missing quote. ++ ++2004-03-14 Luc Teirlinck ++ ++ * intro.texi (Lisp History): Replace xref to `cl' manual with ++ inforef. ++ ++2004-03-12 Richard M. Stallman ++ ++ * intro.texi (Version Info): Add arg to emacs-version. ++ (Lisp History): Change xref to CL manual. ++ ++2004-03-09 Luc Teirlinck ++ ++ * minibuf.texi (Completion Commands): Add xref to Emacs manual ++ for Partial Completion mode. ++ ++2004-03-07 Thien-Thi Nguyen ++ ++ * customize.texi: Fix typo. Remove eol whitespace. ++ ++2004-03-04 Richard M. Stallman ++ ++ * processes.texi: Fix typos. ++ ++ * lists.texi (Building Lists): Minor clarification. ++ ++ * hash.texi (Creating Hash): Correct the meaning of t for WEAK ++ in make-hash-table. ++ ++2004-02-29 Juanma Barranquero ++ ++ * makefile.w32-in (clean, maintainer-clean): Use $(DEL) instead of ++ rm, and ignore exit code. ++ ++2004-02-27 Dan Nicolaescu ++ ++ * display.texi (Defining Faces): Add description for min-colors. ++ Update example. ++ ++2004-02-23 Luc Teirlinck ++ ++ * abbrevs.texi: Various corrections and clarifications in addition ++ to the following: ++ (Abbrev Tables): Delete add-abbrev (as suggested by RMS). ++ ++2004-02-22 Matthew Mundell (tiny change) ++ ++ * calendar.texi (Holiday Customizing): Quote arg of holiday-sexp. ++ ++2004-02-21 Luc Teirlinck ++ ++ * text.texi: Various small changes in addition to the following: ++ (User-Level Deletion): Mention optional BACKWARD-ONLY argument ++ to delete-horizontal-space. ++ (Kill Functions, Yanking, Low-Level Kill Ring): Clarify and correct ++ description of yank-handler text property at various places. ++ ++ * frames.texi (Window System Selections): Add anchor. ++ ++ * syntax.texi (Syntax Table Functions): Clarify and correct ++ descriptions of make-syntax-table and copy-syntax-table. ++ (Motion and Syntax): Clarify SYNTAXES argument to ++ skip-syntax-forward. ++ (Parsing Expressions): Mention that the return value of ++ parse-partial-sexp is currently a list of ten rather than nine ++ elements. ++ (Categories): Various corrections and clarifications. ++ ++2004-02-17 Luc Teirlinck ++ ++ * markers.texi (Marker Insertion Types): Minor change. ++ ++ * locals.texi (Standard Buffer-Local Variables): ++ * commands.texi (Interactive Codes, Using Interactive): ++ * functions.texi (Related Topics): Fix xrefs. ++ ++2004-02-16 Luc Teirlinck ++ ++ * lists.texi (Sets And Lists): Update description of delete-dups. ++ ++2004-02-16 Jesper Harder (tiny change) ++ ++ * keymaps.texi (Tool Bar): tool-bar-item => tool-bar-button. ++ ++2004-02-16 Jan Djärv ++ ++ * frames.texi (Parameter Access): frame-parameters arg is optional. ++ modify-frame-parameters handles nil for FRAME. ++ (Window Frame Parameters): menu-bar-lines and tool-bar-lines ++ are all-or-nothing for certain toolkits. ++ Mention parameter wait-for-wm. ++ (Frames and Windows): In frame-first-window and frame-selected-window ++ the arg is optional. ++ (Input Focus): In redirect-frame-focus the second arg is optional. ++ (Window System Selections): Mention selection type CLIPBOARD. ++ Mention data-type UTF8_STRING. ++ Mention numbering of cut buffers. ++ (Resources): Describe x-resource-name. ++ ++2004-02-16 Richard M. Stallman ++ ++ * windows.texi (Buffers and Windows): Delete false table ++ about all-frames. ++ ++ * syntax.texi (Parsing Expressions): Delete old caveat ++ about parse-sexp-ignore-comments. ++ ++ * streams.texi (Output Variables): Add print-quoted. ++ ++ * lists.texi (Building Lists): Minor cleanup. ++ ++ * hash.texi (Creating Hash): Correct and clarify doc of WEAK values. ++ ++ * display.texi (Overlays): Explain overlays use markers. ++ (Managing Overlays): Explain front-advance and rear-advance ++ in more detail. ++ ++ * loading.texi (Unloading): Document unload-feature-special-hooks. ++ Get rid of fns-NNN.el file. ++ ++2004-02-16 Matthew Mundell (tiny change) ++ ++ * help.texi (Describing Characters): Fix text-char-description ++ example output. ++ ++ * edebug.texi (Using Edebug): Fix example. ++ ++ * debugging.texi (Internals of Debugger): Fix return value. ++ ++ * files.texi (Changing Files): Fix argname. ++ ++ * calendar.texi: Fix parens, and default values. ++ ++ * display.texi, frames.texi, internals.texi, modes.texi: Minor fixes. ++ * nonascii.texi, objects.texi, os.texi: Minor fixes. ++ * searching.texi, text.texi, tips.texi, windows.texi: Minor fixes. ++ ++ * positions.texi (Text Lines): Don't add -1 in current-line. ++ ++2004-02-16 Richard M. Stallman ++ ++ * compile.texi (Compiler Errors): if-boundp feature applies to cond. ++ ++2004-02-16 Jesper Harder (tiny change) ++ ++ * processes.texi (Low-Level Network): Fix a typo. ++ ++2004-02-12 Kim F. Storm ++ ++ * display.texi (Fringes): Use consistent wording. ++ Note that window-fringe's window arg is optional. ++ (Scroll Bars): Use consistent wording. ++ ++2004-02-11 Luc Teirlinck ++ ++ * tips.texi (Comment Tips): Document the new conventions for ++ commenting out code. ++ ++2004-02-07 Jan Djärv ++ ++ * positions.texi (Text Lines): Added missing end defun. ++ ++2004-02-07 Kim F. Storm ++ ++ * positions.texi (Text Lines): Add line-number-at-pos. ++ ++2004-02-06 John Paul Wallington ++ ++ * display.texi (Button Properties, Button Buffer Commands): ++ mouse-2 invokes button, not down-mouse-1. ++ ++2004-02-04 Jason Rumney ++ ++ * makefile.w32-in: Sync with Makefile.in changes. ++ ++2004-02-03 Luc Teirlinck ++ ++ * minibuf.texi (Text from Minibuffer): Various corrections and ++ clarifications. ++ (Object from Minibuffer): Correct Lisp description of ++ read-minibuffer. ++ (Minibuffer History): Clarify description of cons values for ++ HISTORY arguments. ++ (Basic Completion): Various corrections and clarifications. Add ++ completion-regexp-list. ++ (Minibuffer Completion): Correct and clarify description of ++ completing-read. ++ (Completion Commands): Mention Partial Completion mode. Various ++ other minor changes. ++ (High-Level Completion): Various corrections and clarifications. ++ (Reading File Names): Ditto. ++ (Minibuffer Misc): Ditto. ++ ++2004-01-26 Luc Teirlinck ++ ++ * strings.texi (Text Comparison): assoc-string also matches ++ elements of alists that are strings instead of conses. ++ (Formatting Strings): Standardize Texinfo usage. Update index ++ entries. ++ ++2004-01-20 Luc Teirlinck ++ ++ * lists.texi (Sets And Lists): Add delete-dups. ++ ++2004-01-15 Luc Teirlinck ++ ++ * edebug.texi (Instrumenting Macro Calls): `declare' is not a ++ special form. ++ * macros.texi (Defining Macros): Update description of `declare', ++ which now is a macro. ++ (Wrong Time): Fix typos. ++ ++2004-01-14 Luc Teirlinck ++ ++ * compile.texi (Compilation Functions): Expand descriptions of ++ `compile-defun', `byte-compile-file', `byte-recompile-directory' ++ and `batch-byte-compile'. In particular, mention and describe ++ all optional arguments. ++ (Disassembly): Correct and clarify the description of `disassemble'. ++ ++2004-01-11 Luc Teirlinck ++ ++ * searching.texi: Various small changes in addition to the ++ following. ++ (Regexp Example): Adapt to new value of `sentence-end'. ++ (Regexp Functions): The PAREN argument to `regexp-opt' can be ++ `words'. ++ (Search and Replace): Add usage note for `perform-replace'. ++ (Entire Match Data): Mention INTEGERS and REUSE arguments to ++ `match-data'. ++ (Standard Regexps): Update for new values of `paragraph-start' ++ and `sentence-end'. ++ ++2004-01-07 Luc Teirlinck ++ ++ * files.texi (Saving Buffers): Clarify descriptions of ++ `write-contents-functions' and `before-save-hook'. ++ Make the defvar's for `before-save-hook' and `after-save-hook' ++ into defopt's. ++ ++2004-01-07 Kim F. Storm ++ ++ * commands.texi (Click Events): Describe new image and ++ width/height elements of click events. ++ (Accessing Events): Add posn-string, posn-image, and ++ posn-object-width-height. Change posn-object to return either ++ image or string object. ++ ++2004-01-01 Simon Josefsson ++ ++ * hooks.texi (Standard Hooks): Add before-save-hook. ++ * files.texi (Saving Buffers): Likewise. ++ ++2004-01-03 Richard M. Stallman ++ ++ * frames.texi (Frames and Windows): Delete frame-root-window. ++ ++2004-01-03 Luc Teirlinck ++ ++ * eval.texi, hash.texi, help.texi, symbols.texi: Add anchors. ++ ++ * functions.texi: Various small changes in addition to the ++ following. ++ (What Is a Function): `functionp' returns nil for macros. Clarify ++ behavior of this and following functions for symbol arguments. ++ (Function Documentation): Add `\' in front of (fn @var{arglist}) ++ and explain why. ++ (Defining Functions): Mention DOCSTRING argument to `defalias'. ++ Add anchor. ++ (Mapping Functions): Add anchor. Unquote nil in mapcar* example. ++ ++2004-01-01 Miles Bader ++ ++ * display.texi (Buttons): New section. ++ ++2003-12-31 Andreas Schwab ++ ++ * numbers.texi (Math Functions): sqrt reports a domain-error ++ error. ++ (Float Basics): Use `(/ 0.0 0.0)' instead of `(sqrt -1.0)'. ++ ++2003-12-30 Luc Teirlinck ++ ++ * tips.texi (Documentation Tips): Update item on hyperlinks in ++ documentation strings. ++ ++ * errors.texi (Standard Errors): Various small corrections and ++ additions. ++ ++ * control.texi: Various small changes in addition to the ++ following. ++ (Signaling Errors): Provide some more details on how `signal' ++ constructs the error message. Add anchor to the definition of ++ `signal'. ++ (Error Symbols): Describe special treatment of `quit'. ++ (Cleanups): Rename BODY argument of `unwind-protect' to BODY-FORM ++ to emphasize that it has to be a single form. ++ ++ * buffers.texi: Add anchor. ++ ++2003-12-29 Richard M. Stallman ++ ++ * windows.texi (Choosing Window): Add same-window-p, special-display-p. ++ (Window Configurations): Add window-configuration-frame. ++ ++ * variables.texi (Creating Buffer-Local): Add local-variable-if-set-p. ++ ++ * text.texi (Examining Properties): Add get-char-property-and-overlay. ++ Change arg name in get-char-property. ++ (Special Properties): Update handling of keymap property. ++ ++ * strings.texi (Modifying Strings): Add clear-string. ++ (Text Comparison): Add assoc-string and remove ++ assoc-ignore-case, assoc-ignore-representation. ++ ++ * os.texi (Time of Day): Add set-time-zone-rule. ++ ++ * numbers.texi (Math Functions): asin, acos, log, log10 ++ report domain-error errors. ++ ++ * nonascii.texi (Converting Representations): ++ Add multibyte-char-to-unibyte and unibyte-char-to-multibyte. ++ (Encoding and I/O): Add file-name-coding-system. ++ ++ * modes.texi (Search-based Fontification): Explain that ++ face specs are symbols with face names as values. ++ ++ * minibuf.texi (Minibuffer Misc): Add set-minibuffer-window. ++ ++ * lists.texi (Building Lists): remq moved elsewhere. ++ (Sets And Lists): remq moved here. ++ (Association Lists): Refer to assoc-string. ++ ++ * internals.texi (Garbage Collection): Add memory-use-counts. ++ ++ * frames.texi (Frames and Windows): Add set-frame-selected-window ++ and frame-root-window. ++ ++ * files.texi (Contents of Directories): ++ Add directory-files-and-attributes. ++ ++ * display.texi (Refresh Screen): Add force-window-update. ++ (Invisible Text): Explain about moving point out of invis text. ++ (Overlay Properties): Add overlay-properties. ++ (Managing Overlays): Add overlayp. ++ (GIF Images): Invalid image number displays a hollow box. ++ ++ * buffers.texi (Buffer Modification): Add restore-buffer-modified-p. ++ (Killing Buffers): Add buffer-live-p. ++ ++2003-12-25 Markus Rost ++ ++ * display.texi (Fringes): Fix typo "set-buffer-window". ++ ++2003-12-24 Luc Teirlinck ++ ++ * display.texi, eval.texi, help.texi, internals.texi, loading.texi: ++ * nonascii.texi, processes.texi, tips.texi, variables.texi: ++ Add or change various xrefs and anchors. ++ ++ * commands.texi: Replace all occurrences of @acronym{CAR} with ++ @sc{car}, for consistency with the rest of the Elisp manual. ++ `car' and `cdr' are historically acronyms, but are no longer ++ widely thought of as such. ++ ++ * internals.texi (Pure Storage): Mention that `purecopy' does not ++ copy text properties. ++ (Object Internals): Now 29 bits are used (in most implementations) ++ to address Lisp objects. ++ ++ * variables.texi (Variables with Restricted Values): New node. ++ ++ * objects.texi (Lisp Data Types): Mention that certain variables ++ can only take on a restricted set of values and add an xref to ++ the new node "Variables with Restricted Values". ++ ++ * eval.texi (Function Indirection): Describe the errors that ++ `indirect-function' can signal. ++ (Eval): Clarify the descriptions of `eval-region' and `values'. ++ Describe `eval-buffer' instead of `eval-current-buffer' and ++ mention `eval-current-buffer' as an alias for `current-buffer'. ++ Correct the description and mention all optional arguments. ++ ++ * nonascii.texi: Various small changes in addition to the ++ following. ++ (Converting Representations): Clarify behavior of ++ `string-make-multibyte' and `string-to-multibyte' for unibyte all ++ ASCII arguments. ++ (Character Sets): Document the variable `charset-list' and adapt ++ the definition of the function `charset-list' accordingly. ++ (Translation of Characters): Clarify use of generic characters in ++ `make-translation-table'. Clarify and correct the description of ++ the use of translation tables in encoding and decoding. ++ (User-Chosen Coding Systems): Correct and clarify the description ++ of `select-safe-coding-system'. ++ (Default Coding Systems): Clarify description of ++ `file-coding-system-alist'. ++ ++2003-11-30 Luc Teirlinck ++ ++ * strings.texi (Text Comparison): Correctly describe when two ++ strings are `equal'. Combine and clarify descriptions of ++ `assoc-ignore-case' and `assoc-ignore-representation'. ++ ++ * objects.texi (Non-ASCII in Strings): Clarify description of ++ when a string is unibyte or multibyte. ++ (Bool-Vector Type): Update examples. ++ (Equality Predicates): Correctly describe when two strings are ++ `equal'. ++ ++2003-11-29 Luc Teirlinck ++ ++ * lists.texi (Building Lists): `append' no longer accepts integer ++ arguments. Update the description of `number-sequence' to reflect ++ recent changes. ++ (Sets And Lists): Describe `member-ignore-case' after `member'. ++ ++2003-11-27 Kim F. Storm ++ ++ * commands.texi (Click Events): Click object may be an images. ++ Describe (dx . dy) element of click positions. ++ (Accessing Events): Remove duplicate posn-timestamp. ++ New functions posn-object and posn-object-x-y. ++ ++2003-11-23 Kim F. Storm ++ ++ * commands.texi (Click Events): Describe enhancements to event ++ position lists, including new text-pos and (col . row) items. ++ Mention left-fringe and right-fringe area events. ++ (Accessing Events): New functions posn-area and ++ posn-actual-col-row. Mention posn-timestamp. Mention that ++ posn-point in non-text area still returns buffer position. ++ Clarify posn-col-row. ++ ++2003-11-21 Lars Hansen ++ ++ * files.texi (File Attributes): Describe new parameter ID-FORMAT. ++ * anti.texi (File Attributes): Describe removed parameter ++ ID-FORMAT. ++ ++2003-11-20 Luc Teirlinck ++ ++ * positions.texi (Positions): Mention that, if a marker is used as ++ a position, its buffer is ignored. ++ ++ * markers.texi (Overview of Markers): Mention it here too. ++ ++2003-11-12 Luc Teirlinck ++ ++ * numbers.texi (Numeric Conversions): Not just `floor', but also ++ `truncate', `ceiling' and `round' accept optional argument DIVISOR. ++ ++2003-11-10 Luc Teirlinck ++ ++ * markers.texi (Creating Markers): Specify insertion type of ++ created markers. Add xref to `Marker Insertion Types'. ++ Second argument to `copy-marker' is optional. ++ (Marker Insertion Types): Mention that most markers are created ++ with insertion type nil. ++ (The Mark): Correctly describe when `mark' signals an error. ++ (The Region): Correctly describe when `region-beginning' and ++ `region-end' signal an error. ++ ++2003-11-08 Luc Teirlinck ++ ++ * hash.texi (Creating Hash): Clarify description of `eql'. ++ `makehash' is obsolete. ++ (Hash Access): Add Common Lisp notes for `remhash' and `clrhash'. ++ ++ * positions.texi (Point): Change description of `buffer-end', so ++ that it is also correct for floating point arguments. ++ (List Motion): Correct argument lists of `beginning-of-defun' and ++ `end-of-defun'. ++ (Excursions): Add xref to `Marker Insertion Types'. ++ (Narrowing): Argument to `narrow-to-page' is optional. ++ ++2003-11-06 Luc Teirlinck ++ ++ * streams.texi (Output Streams): Clarify behavior of point for ++ marker output streams. ++ ++2003-11-04 Luc Teirlinck ++ ++ * variables.texi (Defining Variables): Second argument to ++ `defconst' is not optional. ++ (Setting Variables): Mention optional argument APPEND to ++ `add-to-list'. ++ (Creating Buffer-Local): Expand description of ++ `make-variable-buffer-local'. ++ (Frame-Local Variables): Expand description of ++ `make-variable-frame-local'. ++ (Variable Aliases): Correct description of optional argument ++ DOCSTRING to `defvaralias'. Mention return value of ++ `defvaralias'. ++ (File Local Variables): Add xref to `File variables' in Emacs ++ Manual. Correct description of `hack-local-variables'. Mention ++ `safe-local-variable' property. Mention optional second argument ++ to `risky-local-variable-p'. ++ ++2003-11-03 Luc Teirlinck ++ ++ * symbols.texi (Symbol Plists): Mention return value of `setplist'. ++ ++2003-11-02 Jesper Harder (tiny change) ++ ++ * lispref/anti.texi, lispref/backups.texi, lispref/commands.texi ++ lispref/customize.texi, lispref/display.texi, lispref/files.texi, ++ lispref/internals.texi, lispref/keymaps.texi, lispref/loading.texi, ++ lispref/modes.texi, lispref/nonascii.texi, lispref/numbers.texi, ++ lispref/objects.texi, lispref/os.texi, lispref/positions.texi, ++ lispref/processes.texi, lispref/searching.texi, ++ lispref/sequences.texi, lispref/streams.texi, lispref/strings.texi, ++ lispref/syntax.texi, lispref/text.texi: Replace @sc{foo} with ++ @acronym{FOO}. ++ ++2003-10-27 Luc Teirlinck ++ ++ * strings.texi (Creating Strings): Argument START to `substring' ++ can not be `nil'. Expand description of ++ `substring-no-properties'. Correct description of `split-string', ++ especially with respect to empty matches. Prevent very bad line ++ break in definition of `split-string-default-separators'. ++ (Text Comparison): `string=' and `string<' also accept symbols as ++ arguments. ++ (String Conversion): More completely describe argument BASE in ++ `string-to-number'. ++ (Formatting Strings): `%s' and `%S' in `format' do require ++ corresponding object. Clarify behavior of numeric prefix after ++ `%' in `format'. ++ (Case Conversion): The argument to `upcase-initials' can be a ++ character. ++ ++2003-10-27 Kenichi Handa ++ ++ * display.texi (Fontsets): Fix texinfo usage. ++ ++2003-10-25 Kenichi Handa ++ ++ * display.texi (Fontsets): Add description of the function ++ set-fontset-font. ++ ++2003-10-23 Luc Teirlinck ++ ++ * display.texi (Temporary Displays): Add xref to `Documentation ++ Tips'. ++ ++ * functions.texi (Function Safety): Use inforef instead of pxref ++ for SES. ++ ++2003-10-23 Andreas Schwab ++ ++ * Makefile.in (TEX, texinputdir): Don't define. ++ (TEXI2DVI): Define. ++ (srcs): Remove $(srcdir)/index.perm and $(srcdir)/index.unperm, ++ add $(srcdir)/index.texi. ++ ($(infodir)/elisp): Remove index.texi dependency. ++ (elisp.dvi): Likewise. Use $(TEXI2DVI). ++ (index.texi): Remove target. ++ (dist): Don't link $(srcdir)/permute-index. ++ (clean): Don't remove index.texi. ++ ++ * permute-index, index.perm: Remove. ++ * index.texi: Rename from index.unperm. ++ ++2003-10-22 Luc Teirlinck ++ ++ * tips.texi (Documentation Tips): Document new behavior for face ++ and variable hyperlinks in Help mode. ++ ++2003-10-21 Luc Teirlinck ++ ++ * objects.texi (Integer Type): Update for extra bit of integer range. ++ (Character Type): Ditto. ++ ++2003-10-16 Eli Zaretskii ++ ++ * numbers.texi (Integer Basics): Add index entries for reading ++ numbers in hex, octal, and binary. ++ ++2003-10-16 Lute Kamstra ++ ++ * modes.texi (Mode Line Format): Mention force-mode-line-update's ++ argument. ++ ++2003-10-13 Luc Teirlinck ++ ++ * windows.texi (Choosing Window): Fix typo. ++ * edebug.texi (Edebug Execution Modes): Fix typo. ++ ++2003-10-13 Richard M. Stallman ++ ++ * windows.texi (Basic Windows): A window has fringe settings, ++ display margins and scroll-bar settings. ++ (Splitting Windows): Doc split-window return value. ++ Clean up one-window-p. ++ (Selecting Windows): Fix typo. ++ (Cyclic Window Ordering): Explain frame as ALL-FRAMES in next-window. ++ (Buffers and Windows): In set-window-buffer, explain effect ++ on fringe settings and scroll bar settings. ++ (Displaying Buffers): In pop-to-buffer, explain nil as buffer arg. ++ (Choosing Window): Use defopt for pop-up-frame-function. ++ For special-display-buffer-names, explain same-window and same-frame. ++ Clarify window-dedicated-p return value. ++ (Textual Scrolling): scroll-up and scroll-down can get an error. ++ (Horizontal Scrolling): Clarify auto-hscroll-mode. ++ Clarify set-window-hscroll. ++ (Size of Window): Don't mention tool bar in window-height. ++ (Coordinates and Windows): Explain what coordinates-in-window-p ++ returns for fringes and display margins. ++ (Window Configurations): Explain saving fringes, etc. ++ ++ * tips.texi (Library Headers): Clean up Documentation. ++ ++ * syntax.texi (Parsing Expressions): Clean up forward-comment ++ and parse-sexp-lookup-properties. ++ ++ * sequences.texi (Sequence Functions): sequencep accepts bool-vectors. ++ ++ * os.texi (System Environment): Clean up text for load-average errors. ++ ++ * modes.texi (Hooks): Don't explain local hook details at front. ++ Clarify run-hooks and run-hook-with-args a little. ++ Clean up add-hook and remove-hook. ++ ++ * edebug.texi (Edebug Execution Modes): Clarify t. ++ Document edebug-sit-for-seconds. ++ (Coverage Testing): Document C-x X = and =. ++ (Instrumenting Macro Calls): Fix typo. ++ (Specification List): Don't index the specification keywords. ++ ++2003-10-10 Kim F. Storm ++ ++ * processes.texi (Network): Introduce make-network-process. ++ ++2003-10-09 Luc Teirlinck ++ ++ * tips.texi (Library Headers): Fix typo. ++ ++2003-10-07 Juri Linkov ++ ++ * modes.texi (Imenu): Mention imenu-create-index-function's ++ default value. Explain submenus better. ++ ++2003-10-07 Lute Kamstra ++ ++ * modes.texi (Faces for Font Lock): Fix typo. ++ (Hooks): Explain how buffer-local hook variables can refer to ++ global hook variables. ++ Various minor clarifications. ++ ++2003-10-06 Lute Kamstra ++ ++ * tips.texi (Coding Conventions): Mention naming conventions for ++ hooks. ++ ++2003-10-05 Luc Teirlinck ++ ++ * loading.texi (Library Search): Correct default value of ++ load-suffixes. ++ (Named Features): Fix typo. ++ ++2003-10-05 Richard M. Stallman ++ ++ * loading.texi (Named Features): In `provide', ++ say how to test for subfeatures. ++ (Unloading): In unload-feature, use new var name ++ unload-feature-special-hooks. ++ ++2003-10-03 Lute Kamstra ++ ++ * modes.texi (Major Mode Conventions): Mention third way to set up ++ Imenu. ++ (Imenu): A number of small fixes. ++ Delete documentation of internal variable imenu--index-alist. ++ Document the return value format of imenu-create-index-function ++ functions. ++ ++2003-09-30 Richard M. Stallman ++ ++ * processes.texi (Network): Say what stopped datagram connections do. ++ ++ * lists.texi (Association Lists): Clarify `assq-delete-all'. ++ ++ * display.texi (Overlay Properties): Clarify `evaporate' property. ++ ++2003-09-29 Lute Kamstra ++ ++ * modes.texi (Mode Line Data): Explain when symbols in mode-line ++ constructs should be marked as risky. ++ Change cons cell into proper list. ++ (Mode Line Variables): Change cons cell into proper list. ++ ++2003-09-26 Lute Kamstra ++ ++ * modes.texi (Mode Line Data): Document the :propertize construct. ++ (Mode Line Variables): Reorder the descriptions of the variables ++ to match their order in the default mode-line-format. ++ Describe the new variables mode-line-position and mode-line-modes. ++ Update the default values of mode-line-frame-identification, ++ minor-mode-alist, and default-mode-line-format. ++ (Properties in Mode): Mention the :propertize construct. ++ ++2003-09-26 Richard M. Stallman ++ ++ * buffers.texi, commands.texi, debugging.texi, eval.texi: ++ * loading.texi, minibuf.texi, text.texi, variables.texi: ++ Avoid @strong{Note:}. ++ ++2003-09-26 Richard M. Stallman ++ ++ * keymaps.texi (Remapping Commands): Fix typo. ++ ++2003-09-23 Luc Teirlinck ++ ++ * processes.texi (Low-Level Network): Fix typo. ++ ++2003-09-23 Kim F. Storm ++ ++ * processes.texi (Network, Network Servers): Fix typos. ++ (Low-Level Network): Add timeout value for :server keyword. ++ Add new option keywords to make-network-process. ++ Add set-network-process-options. ++ Explain how to test availability of network options. ++ ++2003-09-19 Richard M. Stallman ++ ++ * text.texi (Motion by Indent): Arg to ++ backward-to-indentation and forward-to-indentation is optional. ++ ++ * strings.texi (Creating Strings): Add substring-no-properties. ++ ++ * processes.texi ++ (Process Information): Add list-processes arg QUERY-ONLY. ++ Delete process-contact from here. ++ Add new status values for process-status. ++ Add process-get, process-put, process-plist, set-process-plist. ++ (Synchronous Processes): Add call-process-shell-command. ++ (Signals to Processes): signal-process allows process objects. ++ (Network): Complete rewrite. ++ (Network Servers, Datagrams, Low-Level Network): New nodes. ++ ++ * positions.texi (Word Motion): forward-word, backward-word ++ arg is optional. Reword. ++ ++ * abbrevs.texi (Defining Abbrevs): Index no-self-insert. ++ ++ * variables.texi (Creating Buffer-Local): ++ Delete duplicate definition of buffer-local-value. ++ (File Local Variables): Explain about discarding text props. ++ ++2003-09-11 Richard M. Stallman ++ ++ * minibuf.texi (Intro to Minibuffers): Explain that the minibuffer ++ changes variables that record input events. ++ (Minibuffer Misc): Add minibuffer-selected-window. ++ ++ * lists.texi (Building Lists): Add copy-tree. ++ ++ * display.texi (Fontsets): Add char-displayable-p. ++ (Scroll Bars): New node. ++ ++2003-09-08 Lute Kamstra ++ ++ * modes.texi (%-Constructs): Document new `%i' and `%I' ++ constructs. ++ ++2003-09-03 Peter Runestig ++ ++ * makefile.w32-in: New file. ++ ++2003-08-29 Richard M. Stallman ++ ++ * display.texi (Overlay Properties): Clarify how priorities ++ affect use of the properties. ++ ++2003-08-19 Luc Teirlinck ++ ++ * customize.texi (Type Keywords): Correct the description of ++ `:help-echo' in the case where `motion-doc' is a function. ++ ++2003-08-14 John Paul Wallington ++ ++ * modes.texi (Emulating Mode Line): Subsection, not section. ++ ++2003-08-13 Richard M. Stallman ++ ++ * elisp.texi (Top): Update subnode lists in menu. ++ ++ * text.texi (Insertion): Add insert-buffer-substring-no-properties. ++ (Kill Functions): kill-region has new arg yank-handler. ++ (Yanking): New node. ++ (Yank Commands): Add yank-undo-function. ++ (Low-Level Kill Ring): ++ kill-new and kill-append have new arg yank-handler. ++ (Changing Properties): Add remove-list-of-text-properties. ++ (Atomic Changes): New node. ++ ++ * symbols.texi (Other Plists): Add lax-plist-get, lax-plist-put. ++ ++ * streams.texi (Output Variables): Add eval-expression-print-length ++ and eval-expression-print-level. ++ ++ * os.texi (Time Conversion): For encode-time, explain limits on year. ++ ++ * objects.texi (Character Type): Define anchor "modifier bits". ++ ++ * modes.texi (Emulating Mode Line): New node. ++ (Search-based Fontification): Font Lock uses font-lock-face property. ++ (Other Font Lock Variables): Likewise. ++ ++ * keymaps.texi (Format of Keymaps): Keymaps contain char tables, ++ not vectors. ++ (Active Keymaps): Add emulation-mode-map-alists. ++ (Functions for Key Lookup): key-binding has new arg no-remap. ++ (Remapping Commands): New node. ++ (Scanning Keymaps): where-is-internal has new arg no-remap. ++ (Tool Bar): Add tool-bar-local-item-from-menu. ++ Clarify when to use tool-bar-add-item-from-menu. ++ ++ * commands.texi (Interactive Call): commandp has new arg. ++ (Command Loop Info): Add this-original-command. ++ ++2003-08-06 John Paul Wallington ++ ++ * compile.texi (Compiler Errors): Say `@end defmac' after `@defmac'. ++ ++ * display.texi (Warning Basics): Fix typo. ++ (Fringes): Add closing curly bracket and fix typo. ++ ++ * elisp.texi (Top): Fix typo. ++ ++2003-08-05 Richard M. Stallman ++ ++ * elisp.texi: Update lists of subnodes. ++ ++ * windows.texi (Buffers and Windows): set-window-buffer has new arg. ++ ++ * variables.texi (Local Variables): Use lc for example variable names. ++ ++ * tips.texi (Library Headers): Explain where to put -*-. ++ ++ * strings.texi (Creating Strings): Fix xref for vconcat. ++ ++ * sequences.texi (Vector Functions): ++ vconcat no longer allows integer args. ++ ++ * minibuf.texi (Reading File Names): read-file-name has new ++ arg PREDICATE. New function read-directory-name. ++ ++ * macros.texi (Defining Macros): Give definition of `declare' ++ (Indenting Macros): New node. ++ ++ * frames.texi (Parameter Access): Add modify-all-frames-parameters. ++ (Window Frame Parameters): Make separate table of parameters ++ that are coupled with specific face attributes. ++ (Deleting Frames): delete-frame-hooks renamed to ++ delete-frame-functions. ++ ++ * files.texi (Magic File Names): Add file-remote-p. ++ Clarify file-local-copy. ++ ++ * edebug.texi (Instrumenting Macro Calls): Don't define `declare' ++ here; instead xref Defining Macros. ++ ++ * display.texi (Warnings): New node, and subnodes. ++ (Fringes): New node. ++ ++ * debugging.texi (Test Coverage): New node. ++ ++ * compile.texi (Compiler Errors): Explain with-no-warnings ++ and other ways to suppress warnings. ++ ++ * commands.texi (Interactive Call): Minor clarification. ++ ++ * buffers.texi (Buffer File Name): set-visited-file-name ++ renames the buffer too. ++ ++ * abbrevs.texi (Abbrev Tables): Add copy-abbrev-table. ++ ++2003-07-24 Markus Rost ++ ++ * abbrevs.texi (Abbrev Expansion): Use \s syntax in example. ++ ++2003-07-22 Markus Rost ++ ++ * internals.texi (Garbage Collection): Fix previous change. ++ ++2003-07-22 Richard M. Stallman ++ ++ * files.texi (Truenames): Add LIMIT arg to file-chase-links. ++ ++ * display.texi (Width): Use \s syntax in example. ++ (Font Selection): Add face-font-rescale-alist. ++ ++ * modes.texi (Imenu): Add xref to Emacs Manual node on Imenu. ++ Remove spurious indent in example. ++ ++ * lists.texi (Building Lists): Add number-sequence. ++ ++ * internals.texi (Garbage Collection): Add gcs-done, gc-elapsed. ++ ++ * functions.texi (Function Documentation): Explain how to ++ show calling convention explicitly in the doc string. ++ ++ * windows.texi (Selecting Windows): save-selected-window saves ++ selected window of each frame. ++ (Window Configurations): Minor change. ++ ++ * syntax.texi (Syntax Table Functions): Use \s syntax in examples. ++ ++ * streams.texi (Output Variables): Add print-continuous-numbering ++ and print-number-table. ++ ++ * processes.texi (Decoding Output): New node. ++ ++ * os.texi (Time Conversion): decode-time arg is optional. ++ ++ * objects.texi (Character Type): Don't use space as example for \. ++ Make list of char names and \-sequences correspond. ++ Explain that \s is not used in strings. `\ ' needs space after. ++ ++ * nonascii.texi (Converting Representations): Add string-to-multibyte. ++ (Translation of Characters): Add translation-table-for-input. ++ (Default Coding Systems): Add auto-coding-functions. ++ (Explicit Encoding): Add decode-coding-inserted-region. ++ (Locales): Add locale-info. ++ ++ * minibuf.texi (Basic Completion): Describe test-completion. ++ Collections can be lists of strings. ++ Clean up lazy-completion-table. ++ (Programmed Completion): Mention test-completion. ++ Clarify why lambda expressions are not accepted. ++ (Minibuffer Misc): Describe minibufferp. ++ ++2003-07-14 Richard M. Stallman ++ ++ * buffers.texi (Killing Buffers): kill-buffer-hook is perm local. ++ ++ * windows.texi (Selecting Windows): New arg to select-window. ++ (Selecting Windows): Add with-selected-window. ++ (Size of Window): Add window-inside-edges, etc. ++ ++ * internals.texi (Garbage Collection): Add post-gc-hook. ++ ++ * processes.texi (Subprocess Creation): Add exec-suffixes. ++ ++ * keymaps.texi (Functions for Key Lookup): Add current-active-maps. ++ (Scanning Keymaps): Add map-keymaps. ++ (Defining Menus): Add keymap-prompt. ++ ++ * numbers.texi (Integer Basics): Add most-positive-fixnum, ++ most-negative-fixnum. ++ ++ * compile.texi (Byte Compilation): Explain no-byte-compile ++ (Compiler Errors): New node. ++ ++ * os.texi (User Identification): user-uid, user-real-uid ++ can return float. ++ ++ * modes.texi (Major Mode Conventions): Explain about run-mode-hooks ++ and about derived modes. ++ (Minor Modes): Add minor-mode-list. ++ (Defining Minor Modes): Keyword args for define-minor-mode. ++ (Search-based Fontification): Explain managing other properties. ++ (Other Font Lock Variables): Add font-lock-extra-managed-props. ++ (Faces for Font Lock): Add font-lock-preprocessor-face. ++ (Hooks): Add run-mode-hooks and delay-mode-hooks. ++ ++ * variables.texi (Creating Buffer-Local): Add buffer-local-value. ++ (Variable Aliases): Clarify defvaralias. ++ ++ * loading.texi (Library Search): Add load-suffixes. ++ ++ * minibuf.texi (Basic Completion): Add lazy-completion-table. ++ (Programmed Completion): Add dynamic-completion-table. ++ ++ * files.texi (Changing Files): copy-file allows dir as NEWNAME. ++ (Magic File Names): Specify precedence order of handlers. ++ ++ * commands.texi (Command Overview): Emacs server runs pre-command-hook ++ and post-command-hook. ++ (Waiting): New calling convention for sit-for. ++ ++ * text.texi (Special Properties): local-map and keymap properties ++ apply based on their stickiness. ++ ++2003-07-07 Richard M. Stallman ++ ++ * modes.texi (Minor Mode Conventions): Specify only some kinds ++ of list values as args to minor modes. ++ ++ * files.texi (File Name Expansion): Warn about iterative use ++ of substitute-in-file-name. ++ ++ * advice.texi (Activation of Advice): Clean up previous change. ++ ++2003-07-06 Markus Rost ++ ++ * advice.texi (Activation of Advice): Note that ad-start-advice is ++ turned on by default. ++ ++2003-06-30 Richard M. Stallman ++ ++ * text.texi (Buffer Contents): Document current-word. ++ (Change Hooks): Not called for *Messages*. ++ ++ * functions.texi (Defining Functions): Explain about redefining ++ primitives. ++ (Function Safety): Renamed. Minor changes. ++ Comment out the detailed criteria for what is safe. ++ ++2003-06-22 Andreas Schwab ++ ++ * objects.texi (Symbol Type): Fix description of examples. ++ ++2003-06-16 Andreas Schwab ++ ++ * hash.texi (Creating Hash): Fix description of :weakness. ++ ++2003-06-13 Kai Großjohann ++ ++ * files.texi (Changing Files): copy-file copies file modes, too. ++ ++2003-05-28 Richard M. Stallman ++ ++ * strings.texi (Creating Strings): Clarify split-string. ++ ++2003-05-22 Stephen J. Turnbull ++ ++ * strings.texi (Creating Strings): Update split-string specification ++ and examples. ++ ++2003-05-19 Richard M. Stallman ++ ++ * elisp.texi: Correct invariant section names. ++ ++2003-04-20 Richard M. Stallman ++ ++ * os.texi (Timers): Explain about timers and quitting. ++ ++2003-04-19 Richard M. Stallman ++ ++ * internals.texi (Writing Emacs Primitives): Strings are ++ no longer special for GCPROs. Mention GCPRO5, GCPRO6. ++ Explain GCPRO convention for varargs function args. ++ ++2003-04-16 Richard M. Stallman ++ ++ * minibuf.texi (Minibuffer Misc): Document fn minibuffer-message. ++ ++2003-04-08 Richard M. Stallman ++ ++ * files.texi (Kinds of Files): Correct return value of file-symlink-p. ++ ++2003-02-13 Kim F. Storm ++ ++ * objects.texi (Character Type): New \s escape for space. ++ ++2003-01-31 Joe Buehler ++ ++ * os.texi (System Environment): Added cygwin system-type. ++ ++2003-01-25 Richard M. Stallman ++ ++ * keymaps.texi: Document that a symbol can act as a keymap. ++ ++2003-01-13 Richard M. Stallman ++ ++ * text.texi (Changing Properties): Say string indices are origin-0. ++ ++ * positions.texi (Screen Lines) : ++ Correct order of elts in return value. ++ ++ * keymaps.texi (Changing Key Bindings) : Mention ++ how to define a default binding. ++ ++2002-12-07 Markus Rost ++ ++ * loading.texi (Unloading): Fix recent change for load-history. ++ ++ * customize.texi (Simple Types): Clarify description of custom ++ type 'number. Describe new custom type 'float. ++ ++2002-12-04 Markus Rost ++ ++ * variables.texi (File Local Variables): Fix typo. ++ ++2002-10-23 Kai Großjohann ++ ++ From Michael Albinus . ++ ++ * README: Target for Info file is `make info'. ++ ++ * files.texi (File Name Components): Fixed typos in ++ `file-name-sans-extension'. ++ (Magic File Names): Complete list of operations for magic file ++ name handlers. ++ ++2002-09-16 Jonathan Yavner ++ ++ * variables.texi (File Local Variables): New function ++ risky-local-variable-p. ++ ++2002-09-15 Jonathan Yavner ++ ++ * functions.texi (Function safety): New node about unsafep. ++ ++2002-08-05 Per Abrahamsen ++ ++ * customize.texi (Splicing into Lists): Fixed example. ++ Reported by Fabrice Bauzac ++ ++2002-06-17 Juanma Barranquero ++ ++ * frames.texi (Display Feature Testing): Fix typo. ++ ++2002-06-12 Andreas Schwab ++ ++ * frames.texi (Initial Parameters, Resources): Fix references to ++ the Emacs manual. ++ ++2002-05-13 Kim F. Storm ++ ++ * variables.texi (Intro to Buffer-Local): Updated warning and ++ example relating to changing buffer inside let. ++ ++2002-03-10 Jan Djärv ++ ++ * os.texi (Session Management): New node about X Session management. ++ ++2002-01-18 Eli Zaretskii ++ ++ * elisp.texi (VERSION): Set to 2.9. Update the version of Emacs ++ to which the manual corresponds, and the copyright years. ++ ++ * Makefile.in (VERSION): Set to 2.9. ++ ++2001-11-29 Eli Zaretskii ++ ++ * elisp.texi: Change the category in @dircategory to "Emacs", to ++ make it consistent with info/dir. ++ ++2001-11-25 Miles Bader ++ ++ * text.texi (Fields): Describe new `limit' arg in ++ field-beginning/field-end. ++ ++2001-11-17 Eli Zaretskii ++ ++ * permute-index: Don't depend on csh-specific features. Replace ++ the interpreter name with /bin/sh. ++ ++ * two-volume-cross-refs.txt: New file. ++ * two.el: New file. ++ * spellfile: New file. ++ ++2001-11-16 Eli Zaretskii ++ ++ * permute-index: New file. ++ ++ * vol1.texi, vol2.texi: Renamed from elisp-vol1.texi and ++ elisp-vol2.texi, respectively, to avoid file-name clashes in DOS ++ 8+3 restricted namespace. ++ ++ * Makefile.in (infodir): Define relative to $(srcdir). ++ ($(infodir)/elisp): Don't chdir into $(srcdir), but add it to the ++ include directories list via -I switch to makeinfo. ++ (index.texi): Use cp if both hard and symbolic links fail. ++ ++2001-11-10 Eli Zaretskii ++ ++ * Makefile.in (distclean): Add. ++ ++ The following changes make ELisp manual part of the Emacs ++ distribution: ++ ++ * Makefile.in: Add Copyright notice. ++ (prefix): Remove. ++ (infodir): Change value to "../info". ++ (VPATH): New variable. ++ (MAKE): Don't define. ++ (texmacrodir): Don't define. ++ (texinputdir): Append the existing value of TEXINPUTS. ++ ($(infodir)/elisp): Instead of just "elisp". Reformat the ++ command to be compatible with man/Makefile.in, and to put the ++ output into ../info. ++ (info): Add target. ++ (installall): Target removed. ++ ++2001-10-31 Pavel Janík ++ ++ * tips.texi (Coding Conventions): Fix typo. ++ ++2001-10-23 Gerd Moellmann ++ ++ * Makefile.in (srcs): Add gpl.texi and doclicense.texi. ++ ++2001-10-22 Eli Zaretskii ++ ++ * files.texi (File Name Components): Update the description of ++ file-name-sans-extension and file-name-extension, as they now ++ ignore leading dots. ++ ++2001-10-20 Gerd Moellmann ++ ++ * (Version 21.1 released.) ++ ++2001-10-19 Miles Bader ++ ++ * positions.texi (Text Lines): Describe behavior of ++ `beginning-of-line'/`end-of-line' in the presence of field properties. ++ ++2001-10-17 Gerd Moellmann ++ ++ * Makefile.in (VERSION): Set to 2.8. ++ (manual): Use `manual-21'. ++ ++ * elisp.texi (VERSION): Add and use it where the version ++ number was used. Set it to 2.8. ++ ++ * intro.texi: Likewise. ++ ++2001-10-13 Eli Zaretskii ++ ++ * files.texi (File Name Completion): Document the significance of ++ a trailing slash in elements of completion-ignored-extensions. ++ ++2001-10-06 Miles Bader ++ ++ * variables.texi (Variable Aliases): It's `@defmac', not `@defmacro'. ++ ++2001-10-04 Gerd Moellmann ++ ++ * variables.texi (Variable Aliases): New node. ++ ++2001-10-04 Gerd Moellmann ++ ++ * Branch for 21.1. ++ ++2001-10-02 Miles Bader ++ ++ * minibuf.texi (Minibuffer Misc): Add entries for ++ `minibuffer-contents', `minibuffer-contents-no-properties', and ++ `delete-minibuffer-contents'. ++ Correct description for `minibuffer-prompt-end'. ++ ++ * text.texi (Property Search): Correct descriptions of ++ `next-char-property-change' and `previous-char-property-change'. ++ Add entries for `next-single-char-property-change' and ++ `previous-single-char-property-change'. ++ Make operand names a bit more consistent. ++ ++2001-09-30 Eli Zaretskii ++ ++ * frames.texi (Finding All Frames): Document that next-frame and ++ previous-frame are local to current terminal. ++ ++2001-09-26 Eli Zaretskii ++ ++ * keymaps.texi (Creating Keymaps): Fix the description of the ++ result of make-keymap. ++ ++2001-09-23 Eli Zaretskii ++ ++ * display.texi (Font Lookup, Attribute Functions) ++ (Image Descriptors): Add cross-references to the definition of ++ selected frame. ++ ++ * buffers.texi (The Buffer List): Add cross-references to the ++ definition of selected frame. ++ ++ * frames.texi (Input Focus): Clarify which frame is _the_ selected ++ frame at any given time. ++ (Multiple Displays, Size and Position): Add a cross-reference to ++ the definition of the selected frame. ++ ++2001-09-08 Eli Zaretskii ++ ++ * strings.texi (String Conversion) : Document ++ that a float is returned for integers that are too large. ++ ++ * frames.texi (Mouse Position): Document mouse-position-function. ++ (Display Feature Testing): Document display-images-p. ++ (Window Frame Parameters): Document the cursor-type variable. ++ ++ * numbers.texi (Integer Basics): Document CL style read syntax for ++ integers in bases other than 10. ++ ++ * positions.texi (List Motion): Document ++ open-paren-in-column-0-is-defun-start. ++ ++ * lists.texi (Sets And Lists): Document member-ignore-case. ++ ++ * internals.texi (Garbage Collection): Document the used and free ++ strings report. ++ (Memory Usage): Document strings-consed. ++ ++ * os.texi (Time of Day): Document float-time. ++ (Recording Input): Document that clear-this-command-keys clears ++ the vector to be returned by recent-keys. ++ ++ * keymaps.texi (Scanning Keymaps) : The ++ argument keymap can be a list. ++ ++ * nonascii.texi (User-Chosen Coding Systems) ++ : Document the new argument ++ accept-default-p and the variable ++ select-safe-coding-system-accept-default-p. Tell what happens if ++ buffer-file-coding-system is undecided. ++ (Default Coding Systems): Document auto-coding-regexp-alist. ++ ++ * display.texi (The Echo Area) : Document ++ message-truncate-lines. ++ (Glyphs): Document that the glyph table is unused on windowed ++ displays. ++ ++ * help.texi (Describing Characters) : ++ Document the new argument no-angles. ++ (Accessing Documentation) : Document that ++ a non-string property is evaluated. ++ : Document that the function-documentation property ++ is looked for. ++ ++ * windows.texi (Selecting Windows): Document some-window. ++ ++ * text.texi (MD5 Checksum): New node, documents the md5 primitive. ++ ++ * hooks.texi (Standard Hooks): Add kbd-macro-termination-hook and ++ apropos-mode-hook. ++ ++ * commands.texi (Using Interactive): Document interactive-form. ++ (Keyboard Macros): Document kbd-macro-termination-hook. ++ (Command Loop Info): Document that clear-this-command-keys clears ++ the vector to be returned by recent-keys. ++ ++2001-09-04 Werner LEMBERG ++ ++ * Makefile.in (srcdir, texinputdir): New variables. ++ (srcs, index.texi, install): Use $(srcdir). ++ (.PHONY): Remove elisp.dvi. ++ (elisp): Use -I switch for makeinfo. ++ (elisp.dvi): Use $(srcdir) and $(texinputdir). ++ (installall, dist): Use $(srcdir). ++ Fix path to texinfo.tex. ++ (maintainer-clean): Add elisp.dvi and elisp.oaux. ++ ++2001-08-30 Gerd Moellmann ++ ++ * display.texi (Conditional Display): Adjust to API change. ++ ++ * configure: New file. ++ ++2001-07-30 Gerd Moellmann ++ ++ * commands.texi (Repeat Events): Add description of ++ double-click-fuzz. ++ ++2001-05-08 Stefan Monnier ++ ++ * syntax.texi (Syntax Class Table): Add the missing designator for ++ comment and string fences. ++ (Syntax Properties): Add a xref to syntax table internals. ++ (Syntax Table Internals): Document string-to-syntax. ++ ++2001-05-07 Gerd Moellmann ++ ++ * Makefile.in (install): Use install-info command line options ++ like in Emacs' Makefile.in. ++ ++2000-12-09 Miles Bader ++ ++ * windows.texi (Window Start): Update documentation for ++ `pos-visible-in-window-p'. ++ ++2000-11-12 Stefan Monnier ++ ++ * lists.texi (Building Lists): Add footnote to explain how to add ++ to the end of a list. ++ ++2000-10-25 Gerd Moellmann ++ ++ * files.texi (Visiting Functions): Typos. ++ ++2000-10-25 Kenichi Handa ++ ++ * files.texi (Visiting Functions): Return value of ++ find-file-noselect may be a list of buffers if wildcards are used. ++ ++2000-10-24 Miles Bader ++ ++ * display.texi (Defining Faces): Document `graphic' display type ++ in face specs. ++ ++2000-10-18 Kai Großjohann ++ ++ * hooks.texi (Standard Hooks): Replace obsolete ++ `after-make-frame-hook' with `after-make-frame-functions'. ++ ++ * frames.texi (Creating Frames): Ditto. ++ ++ * variables.texi (Future Local Variables): Ditto. ++ ++2000-10-16 Gerd Moellmann ++ ++ * display.texi (Other Image Types): Add description of :foreground ++ and :background properties of mono PBM images. ++ ++2000-08-17 Werner LEMBERG ++ ++ * .cvsignore: New file. ++ ++2000-01-05 Gerd Moellmann ++ ++ * tindex.pl: New script. ++ ++1999-12-03 Dave Love ++ ++ * Makefile.in (MAKEINFO): New parameter. ++ ++1999-09-17 Richard Stallman ++ ++ * Makefile.in (srcs): Add hash.texi. ++ (VERSION): Update to 20.6. ++ ++1999-09-13 Richard Stallman ++ ++ * Makefile.in (index.texi): If cannot make a symlink, make a hard link. ++ ++1998-08-29 Karl Heuer ++ ++ * configure.in: New file. ++ * Makefile.in: Renamed from Makefile. ++ (prefix, infodir): Use value obtained from configure. ++ (emacslibdir): Obsolete variable deleted. ++ (dist): Distribute configure.in, configure, Makefile.in. ++ ++1998-06-12 Richard Stallman ++ ++ * Makefile (INSTALL_INFO): New variable. ++ (install): Run install-info. ++ ++1998-05-09 Richard Stallman ++ ++ * Makefile (elisp.dvi): Add missing backslash. ++ ++1998-05-02 Richard Stallman ++ ++ * Makefile (elisp.dvi): Don't depend on texindex or on elisp.tps. ++ Run texindex without `./'. Always run texindex on elisp.tp. ++ (elisp.tps): Target deleted. ++ ++1998-04-05 Richard Stallman ++ ++ * Makefile (srcs): Add nonascii.texi and customize.texi. ++ (dist): Start by deleting `temp'. ++ ++1998-02-17 Richard Stallman ++ ++ * Makefile (makeinfo, texindex): Targets deleted. ++ (makeinfo.o, texindex.o): Targets deleted. ++ (clean, dist): Don't do anything with them or with getopt*. ++ ++1998-01-30 Richard Stallman ++ ++ * Makefile (SHELL): Defined. ++ ++1998-01-27 Richard Stallman ++ ++ * Makefile (elisp.tps): New target. ++ (elisp.dvi): Depend on elisp.tps. ++ ++1996-04-03 Karl Heuer ++ ++ * README: Update phone number. ++ ++ * Makefile (elisp): Make this be the default target. ++ Depend on makeinfo.c instead of makeinfo. ++ (install): Don't depend on elisp.dvi, since we don't install that. ++ Use mkinstalldirs. ++ (dist): Add mkinstalldirs. ++ ++1995-06-19 Richard Stallman ++ ++ * Makefile (VERSION): Update version number. ++ (maintainer-clean): Renamed from realclean. ++ ++1995-06-07 Karl Heuer ++ ++ * Makefile (realclean): New target. ++ (elisp): Remove any old elisp-* files first. ++ ++1993-11-23 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) ++ ++ * Makefile (VERSION): New variable. ++ (dist): Make packaged directory name `elisp-manual-19-$(VERSION)'. ++ Compressed file suffix should be `.gz', not `.z'. ++ ++1993-11-22 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Makefile (elisp): Depend on makeinfo. ++ ++1993-11-19 Noah Friedman (friedman@gnu.ai.mit.edu) ++ ++ * Makefile (srcs): Add anti.texi. ++ ++1993-05-28 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Makefile (infodir, prefix): New vars. ++ (install): Use infodir. ++ (emacsinfodir): Deleted. ++ ++1993-05-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Makefile (srcs): Add calendar.texi. ++ ++ * Makefile (dist): Copy texindex.c and makeinfo.c. ++ Limit elisp-* files to those with one or two digits. ++ ++1993-05-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * Makefile (dist): Changed to use Gzip instead of compress. ++ ++1993-04-23 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) ++ ++ * loading.texi (Unloading): define-function changed back to ++ defalias. It may not stay this way, but at least it's ++ consistent with the known-good version of the code patch. ++ ++1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) ++ ++ * modes.texi (Hooks): Document new optional arg of add-hook. ++ ++1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) ++ ++ * variables.texi: Document nil initial value of buffer-local variables. ++ ++ * tips.texi: Add new section on standard library headers. ++ ++1993-02-27 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * Makefile (srcs): Add frame.texi to the list of sources. ++ ++1993-02-23 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * Makefile (dist): Don't bother excluding autosave files; they'll ++ never make it into the temp directory anyway, and the hash marks ++ in the name are problematic for make and the Bourne shell. ++ (srcs): ++ ++1993-02-12 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) ++ ++ * Makefile (dist): Don't include backup files or autosave files in ++ the distribution tar file. ++ ++1991-11-26 Richard Stallman (rms@mole.gnu.ai.mit.edu) ++ ++ * Makefile (srcs): Added index.perm. ++ (elisp.dvi): Remove erroneous shell comment. ++ Expect output of permute-index in permuted.fns. ++ Save old elisp.aux in elisp.oaux. ++ (clean): Added index.texi to be deleted. ++ ++1990-08-11 Richard Stallman (rms@sugar-bombs.ai.mit.edu) ++ ++ * Makefile (elisp.dvi, index.texi): Use shell if instead of ifdef. ++ ++1990-06-26 David Lawrence (tale@geech) ++ ++ * files.texi: Noted that completion-ignored-extensions is ignored ++ when making *Completions*. ++ ++1990-06-08 Jay Fenlason (hack@ai.mit.edu) ++ ++ * Makefile make dist now depends on elisp.dvi, since it tries ++ to include it in the dist file. ++ ++1990-03-28 Jim Kingdon (kingdon@mole.ai.mit.edu) ++ ++ * functions.texinfo (Mapping Functions): Add missing quote. ++ ++1989-06-19 Richard Stallman (rms@sugar-bombs.ai.mit.edu) ++ ++ * texinfo.tex (frenchspacing): Use decimal codes for char to be set. ++ (defunargs): Turn off \hyphenchar of \sl font temporarily. ++ ++1989-05-10 Robert J. Chassell (bob@rice-chex.ai.mit.edu) ++ ++ * @result{}, @expansion{}, @print{}, @quiv{}, @point{}, ++ and @error{} are the terms now being used. The files in the ++ directory have been changed to reflect this. ++ ++ * All instances of @indentedresultt{} have been changed to ++ ` @result{}', using 5 spaces at the begining of the line. ++ ++1989-04-24 Robert J. Chassell (bob@rice-chex.ai.mit.edu) ++ ++ * @result{}, @expandsto{}, @prints{}, @quiv{}, @error{}, and the ++ experimental @indentedresult{}, @indentedexpandsto{} are part of ++ the texinfo.tex in this directory. These TeX macros are not ++ stable yet. ++ ++1989-04-17 Robert J. Chassell (bob@rice-chex.ai.mit.edu) ++ ++ * texinfo.tex: Temporarily added ++ \let\result=\dblarrow ++ \def\error{{\it ERROR} \longdblarrow} ++ We need to do this better soon. ++ ++1989-04-11 Robert J. Chassell (bob@rice-chex.ai.mit.edu) ++ ++ * Applied Karl Berry's patches to *.texinfo files, but not to ++ texinfo.tex; those diffs are in `berry-texinfo-tex-diffs'. (Karl's ++ new title page format is also not applied, since it requires ++ texinfo.tex changes.) ++ ++ * Cleaned up `Makefile' and defined the `emacslibdir' directory ++ for the Project GNU development environment. ++ ++;; Local Variables: ++;; coding: utf-8 ++;; add-log-time-zone-rule: t ++;; End: ++ ++ Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, ++ 2007, 2008, 2009 Free Software Foundation, Inc. ++ ++ This file is part of GNU Emacs. ++ ++ GNU Emacs 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. ++ ++ GNU Emacs 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 GNU Emacs. If not, see . ++ ++;;; arch-tag: 985ae0ce-df29-475b-b3f8-4bbcbf6f7fda +diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in +new file mode 100644 +index 0000000..7c8f1af +--- /dev/null ++++ b/doc/lispref/Makefile.in +@@ -0,0 +1,115 @@ ++# Makefile for the GNU Emacs Lisp Reference Manual. ++ ++# Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, ++# 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++# Free Software Foundation, Inc. ++ ++# This file is part of GNU Emacs. ++ ++# GNU Emacs 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. ++ ++# GNU Emacs 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 GNU Emacs. If not, see . ++ ++ ++# Standard configure variables. ++srcdir = @srcdir@ ++ ++# Tell make where to find source files; this is needed for the makefiles. ++VPATH=@srcdir@ ++ ++infodir = ../../info ++# Directory with the (customized) texinfo.tex file. ++texinfodir = $(srcdir)/../misc ++ ++TEXI2DVI = texi2dvi ++SHELL = /bin/sh ++INSTALL_INFO = install-info ++MAKEINFO = makeinfo --force ++ ++# List of all the texinfo files in the manual: ++ ++srcs = \ ++ $(srcdir)/abbrevs.texi \ ++ $(srcdir)/advice.texi \ ++ $(srcdir)/anti.texi \ ++ $(srcdir)/back.texi \ ++ $(srcdir)/backups.texi \ ++ $(srcdir)/buffers.texi \ ++ $(srcdir)/commands.texi \ ++ $(srcdir)/compile.texi \ ++ $(srcdir)/control.texi \ ++ $(srcdir)/customize.texi \ ++ $(srcdir)/debugging.texi \ ++ $(srcdir)/display.texi \ ++ $(srcdir)/edebug.texi \ ++ $(srcdir)/elisp.texi \ ++ $(srcdir)/errors.texi \ ++ $(srcdir)/eval.texi \ ++ $(srcdir)/files.texi \ ++ $(srcdir)/frames.texi \ ++ $(srcdir)/functions.texi \ ++ $(srcdir)/hash.texi \ ++ $(srcdir)/help.texi \ ++ $(srcdir)/hooks.texi \ ++ $(srcdir)/internals.texi \ ++ $(srcdir)/intro.texi \ ++ $(srcdir)/keymaps.texi \ ++ $(srcdir)/lists.texi \ ++ $(srcdir)/loading.texi \ ++ $(srcdir)/locals.texi \ ++ $(srcdir)/macros.texi \ ++ $(srcdir)/maps.texi \ ++ $(srcdir)/markers.texi \ ++ $(srcdir)/minibuf.texi \ ++ $(srcdir)/modes.texi \ ++ $(srcdir)/nonascii.texi \ ++ $(srcdir)/numbers.texi \ ++ $(srcdir)/objects.texi \ ++ $(srcdir)/os.texi \ ++ $(srcdir)/positions.texi \ ++ $(srcdir)/processes.texi \ ++ $(srcdir)/searching.texi \ ++ $(srcdir)/sequences.texi \ ++ $(srcdir)/streams.texi \ ++ $(srcdir)/strings.texi \ ++ $(srcdir)/symbols.texi \ ++ $(srcdir)/syntax.texi \ ++ $(srcdir)/text.texi \ ++ $(srcdir)/tips.texi \ ++ $(srcdir)/variables.texi \ ++ $(srcdir)/windows.texi \ ++ $(srcdir)/index.texi \ ++ $(srcdir)/gpl.texi \ ++ $(srcdir)/doclicense.texi ++ ++ ++.PHONY: clean ++ ++# The info file is named `elisp'. ++info: $(infodir)/elisp ++ ++$(infodir)/elisp: $(srcs) ++ cd $(srcdir); $(MAKEINFO) -I. -I$(infodir) elisp.texi -o $(infodir)/elisp ++ ++elisp.dvi: $(srcs) ++ $(TEXI2DVI) -I $(srcdir) -I $(texinfodir) $(srcdir)/elisp.texi ++ ++clean: ++ rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ ++ *.vr *.vrs *.pg *.pgs *.ky *.kys elisp[12]* ++ rm -f make.out core ++ ++distclean: clean ++ ++maintainer-clean: clean ++ rm -f elisp.dvi elisp.oaux ++ cd $(infodir); rm -f elisp elisp-[1-9] elisp-[1-9][0-9] +diff --git a/doc/lispref/README b/doc/lispref/README +new file mode 100644 +index 0000000..8895713 +--- /dev/null ++++ b/doc/lispref/README +@@ -0,0 +1,50 @@ ++Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++ Free Software Foundation, Inc. ++See the end of the file for license conditions. ++ ++ ++README for Edition 3.0 of the Emacs Lisp Reference Manual. ++ ++* This directory contains the texinfo source files for the Emacs Lisp ++Reference Manual. ++ ++* Report bugs in the Lisp Manual or in Emacs using M-x report-emacs-bug. ++To ask questions, use the newsgroup gnu.emacs.help. ++ ++* The Emacs Lisp Reference Manual is quite large. It totals around ++1100 pages in smallbook format; the info files total around 3.0 megabytes. ++ ++* You can format this manual either for Info or for printing hardcopy ++using TeX. ++ ++* You can buy nicely printed copies from the Free Software Foundation. ++Buying a manual from the Free Software Foundation helps support our GNU ++development work. See . ++ ++* The master file for formatting this manual for Tex is called ++`elisp.texi'. It contains @include commands to include all the ++chapters that make up the manual. In addition, `elisp.texi' has ++the title page in a new format designed by Karl Berry, using the ++@titlespec command. ++ ++* This distribution contains a Makefile that you can use with GNU Make. ++ ++** To create a DVI file with a sorted index, run `make elisp.dvi'. ++ ++** To make an Info file, you need to install Texinfo, then run `make info'. ++ ++ ++This file is part of GNU Emacs. ++ ++GNU Emacs 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. ++ ++GNU Emacs 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 GNU Emacs. If not, see . +diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi +new file mode 100644 +index 0000000..9e14c3d +--- /dev/null ++++ b/doc/lispref/abbrevs.texi +@@ -0,0 +1,523 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2001, 2002, 2003, ++@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/abbrevs ++@node Abbrevs, Processes, Syntax Tables, Top ++@chapter Abbrevs and Abbrev Expansion ++@cindex abbrev ++@c @cindex abbrev table Redundant with "abbrev". ++ ++ An abbreviation or @dfn{abbrev} is a string of characters that may be ++expanded to a longer string. The user can insert the abbrev string and ++find it replaced automatically with the expansion of the abbrev. This ++saves typing. ++ ++ The set of abbrevs currently in effect is recorded in an @dfn{abbrev ++table}. Each buffer has a local abbrev table, but normally all buffers ++in the same major mode share one abbrev table. There is also a global ++abbrev table. Normally both are used. ++ ++ An abbrev table is represented as an obarray. @xref{Creating ++Symbols}, for information about obarrays. Each abbreviation is ++represented by a symbol in the obarray. The symbol's name is the ++abbreviation; its value is the expansion; its function definition is ++the hook function for performing the expansion (@pxref{Defining ++Abbrevs}); and its property list cell contains various additional ++properties, including the use count and the number of times the ++abbreviation has been expanded (@pxref{Abbrev Properties}). ++ ++@cindex system abbrev ++ Certain abbrevs, called @dfn{system abbrevs}, are defined by a major ++mode instead of the user. A system abbrev is identified by its ++non-@code{nil} @code{:system} property (@pxref{Abbrev Properties}). ++When abbrevs are saved to an abbrev file, system abbrevs are omitted. ++@xref{Abbrev Files}. ++ ++ Because the symbols used for abbrevs are not interned in the usual ++obarray, they will never appear as the result of reading a Lisp ++expression; in fact, normally they are never used except by the code ++that handles abbrevs. Therefore, it is safe to use them in an ++extremely nonstandard way. ++ ++ For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev ++Mode, emacs, The GNU Emacs Manual}. ++ ++@menu ++* Abbrev Mode:: Setting up Emacs for abbreviation. ++* Tables: Abbrev Tables. Creating and working with abbrev tables. ++* Defining Abbrevs:: Specifying abbreviations and their expansions. ++* Files: Abbrev Files. Saving abbrevs in files. ++* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. ++* Standard Abbrev Tables:: Abbrev tables used by various major modes. ++* Abbrev Properties:: How to read and set abbrev properties. ++ Which properties have which effect. ++* Abbrev Table Properties:: How to read and set abbrev table properties. ++ Which properties have which effect. ++@end menu ++ ++@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs ++@comment node-name, next, previous, up ++@section Setting Up Abbrev Mode ++ ++ Abbrev mode is a minor mode controlled by the variable ++@code{abbrev-mode}. ++ ++@defopt abbrev-mode ++If this variable is non-@code{nil}, abbrevs are automatically expanded ++in the buffer. If the value is @code{nil}, abbrevs may be defined, ++but they are not expanded automatically. ++ ++This variable automatically becomes buffer-local when set in any fashion. ++@end defopt ++ ++@defvar default-abbrev-mode ++This is the value of @code{abbrev-mode} for buffers that do not ++override it. It is the same as @code{(default-value 'abbrev-mode)}. ++@end defvar ++ ++@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs ++@section Abbrev Tables ++ ++ This section describes how to create and manipulate abbrev tables. ++ ++@defun make-abbrev-table &optional props ++This function creates and returns a new, empty abbrev table---an ++obarray containing no symbols. It is a vector filled with zeros. ++@var{props} is a property list that is applied to the new table ++(@pxref{Abbrev Table Properties}). ++@end defun ++ ++@defun abbrev-table-p object ++This function returns a non-@code{nil} value if @var{object} is an ++abbrev table. ++@end defun ++ ++@defun clear-abbrev-table abbrev-table ++This function undefines all the abbrevs in @var{abbrev-table}, leaving ++it empty. It always returns @code{nil}. ++@end defun ++ ++@defun copy-abbrev-table abbrev-table ++This function returns a copy of @var{abbrev-table}---a new abbrev ++table containing the same abbrev definitions. There is one difference ++between the contents of @var{abbrev-table} and the returned copy: all ++abbrevs in the latter have their property lists set to @code{nil}. ++@end defun ++ ++@defun define-abbrev-table tabname definitions &optional docstring &rest props ++This function defines @var{tabname} (a symbol) as an abbrev table ++name, i.e., as a variable whose value is an abbrev table. It defines ++abbrevs in the table according to @var{definitions}, a list of ++elements of the form @code{(@var{abbrevname} @var{expansion} ++[@var{hook}] [@var{props}...])}. These elements are passed as ++arguments to @code{define-abbrev}. The return value is always ++@code{nil}. ++ ++The optional string @var{docstring} is the documentation string of the ++variable @var{tabname}. The property list @var{props} is applied to ++the abbrev table (@pxref{Abbrev Table Properties}). ++ ++If this function is called more than once for the same @var{tabname}, ++subsequent calls add the definitions in @var{definitions} to ++@var{tabname}, rather than overriding the entire original contents. ++(A subsequent call only overrides abbrevs explicitly redefined or ++undefined in @var{definitions}.) ++@end defun ++ ++@defvar abbrev-table-name-list ++This is a list of symbols whose values are abbrev tables. ++@code{define-abbrev-table} adds the new abbrev table name to this list. ++@end defvar ++ ++@defun insert-abbrev-table-description name &optional human ++This function inserts before point a description of the abbrev table ++named @var{name}. The argument @var{name} is a symbol whose value is an ++abbrev table. The return value is always @code{nil}. ++ ++If @var{human} is non-@code{nil}, the description is human-oriented. ++System abbrevs are listed and identified as such. Otherwise the ++description is a Lisp expression---a call to @code{define-abbrev-table} ++that would define @var{name} as it is currently defined, but without ++the system abbrevs. (The mode or package using @var{name} is supposed ++to add these to @var{name} separately.) ++@end defun ++ ++@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs ++@comment node-name, next, previous, up ++@section Defining Abbrevs ++ ++ @code{define-abbrev} is the low-level basic function for defining an ++abbrev in an abbrev table. ++ ++ When a major mode defines a system abbrev, it should call ++@code{define-abbrev} and specify a @code{t} for the @code{:system} ++property. Be aware that any saved non-``system'' abbrevs are restored ++at startup, i.e. before some major modes are loaded. Therefore, major ++modes should not assume that their abbrev tables are empty when they ++are first loaded. ++ ++@defun define-abbrev abbrev-table name expansion &optional hook &rest props ++This function defines an abbrev named @var{name}, in ++@var{abbrev-table}, to expand to @var{expansion} and call @var{hook}, ++with properties @var{props} (@pxref{Abbrev Properties}). The return ++value is @var{name}. The @code{:system} property in @var{props} is ++treated specially here: if it has the value @code{force}, then it will ++overwrite an existing definition even for a non-``system'' abbrev of ++the same name. ++ ++@var{name} should be a string. The argument @var{expansion} is ++normally the desired expansion (a string), or @code{nil} to undefine ++the abbrev. If it is anything but a string or @code{nil}, then the ++abbreviation ``expands'' solely by running @var{hook}. ++ ++The argument @var{hook} is a function or @code{nil}. If @var{hook} is ++non-@code{nil}, then it is called with no arguments after the abbrev is ++replaced with @var{expansion}; point is located at the end of ++@var{expansion} when @var{hook} is called. ++ ++@cindex @code{no-self-insert} property ++If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert} ++property is non-@code{nil}, @var{hook} can explicitly control whether ++to insert the self-inserting input character that triggered the ++expansion. If @var{hook} returns non-@code{nil} in this case, that ++inhibits insertion of the character. By contrast, if @var{hook} ++returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as ++if expansion had not really occurred. ++ ++Normally, @code{define-abbrev} sets the variable ++@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev. ++(This is so that some commands will offer to save the abbrevs.) It ++does not do this for a system abbrev, since those aren't saved anyway. ++@end defun ++ ++@defopt only-global-abbrevs ++If this variable is non-@code{nil}, it means that the user plans to use ++global abbrevs only. This tells the commands that define mode-specific ++abbrevs to define global ones instead. This variable does not alter the ++behavior of the functions in this section; it is examined by their ++callers. ++@end defopt ++ ++@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs ++@section Saving Abbrevs in Files ++ ++ A file of saved abbrev definitions is actually a file of Lisp code. ++The abbrevs are saved in the form of a Lisp program to define the same ++abbrev tables with the same contents. Therefore, you can load the file ++with @code{load} (@pxref{How Programs Do Loading}). However, the ++function @code{quietly-read-abbrev-file} is provided as a more ++convenient interface. ++ ++ User-level facilities such as @code{save-some-buffers} can save ++abbrevs in a file automatically, under the control of variables ++described here. ++ ++@defopt abbrev-file-name ++This is the default file name for reading and saving abbrevs. ++@end defopt ++ ++@defun quietly-read-abbrev-file &optional filename ++This function reads abbrev definitions from a file named @var{filename}, ++previously written with @code{write-abbrev-file}. If @var{filename} is ++omitted or @code{nil}, the file specified in @code{abbrev-file-name} is ++used. @code{save-abbrevs} is set to @code{t} so that changes will be ++saved. ++ ++This function does not display any messages. It returns @code{nil}. ++@end defun ++ ++@defopt save-abbrevs ++A non-@code{nil} value for @code{save-abbrevs} means that Emacs should ++offer the user to save abbrevs when files are saved. If the value is ++@code{silently}, Emacs saves the abbrevs without asking the user. ++@code{abbrev-file-name} specifies the file to save the abbrevs in. ++@end defopt ++ ++@defvar abbrevs-changed ++This variable is set non-@code{nil} by defining or altering any ++abbrevs (except system abbrevs). This serves as a flag for various ++Emacs commands to offer to save your abbrevs. ++@end defvar ++ ++@deffn Command write-abbrev-file &optional filename ++Save all abbrev definitions (except system abbrevs), for all abbrev ++tables listed in @code{abbrev-table-name-list}, in the file ++@var{filename}, in the form of a Lisp program that when loaded will ++define the same abbrevs. If @var{filename} is @code{nil} or omitted, ++@code{abbrev-file-name} is used. This function returns @code{nil}. ++@end deffn ++ ++@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs ++@comment node-name, next, previous, up ++@section Looking Up and Expanding Abbreviations ++ ++ Abbrevs are usually expanded by certain interactive commands, ++including @code{self-insert-command}. This section describes the ++subroutines used in writing such commands, as well as the variables they ++use for communication. ++ ++@defun abbrev-symbol abbrev &optional table ++This function returns the symbol representing the abbrev named ++@var{abbrev}. The value returned is @code{nil} if that abbrev is not ++defined. The optional second argument @var{table} is the abbrev table ++in which to look it up. If @var{table} is @code{nil}, this function ++tries first the current buffer's local abbrev table, and second the ++global abbrev table. ++@end defun ++ ++@defun abbrev-expansion abbrev &optional table ++This function returns the string that @var{abbrev} would expand into (as ++defined by the abbrev tables used for the current buffer). If ++@var{abbrev} is not a valid abbrev, the function returns @code{nil}. ++The optional argument @var{table} specifies the abbrev table to use, ++as in @code{abbrev-symbol}. ++@end defun ++ ++@deffn Command expand-abbrev ++This command expands the abbrev before point, if any. If point does not ++follow an abbrev, this command does nothing. The command returns the ++abbrev symbol if it did expansion, @code{nil} otherwise. ++ ++If the abbrev symbol has a hook function which is a symbol whose ++@code{no-self-insert} property is non-@code{nil}, and if the hook ++function returns @code{nil} as its value, then @code{expand-abbrev} ++returns @code{nil} even though expansion did occur. ++@end deffn ++ ++@deffn abbrev-insert abbrev &optional name start end ++This function inserts the abbrev expansion of @code{abbrev}, replacing ++the text between @code{start} and @code{end}. If @code{start} is ++omitted, it defaults to point. @code{name}, if non-@code{nil}, should ++be the name by which this abbrev was found (a string); it is used to ++figure out whether to adjust the capitalization of the expansion. The ++function returns @code{abbrev} if the abbrev was successfully ++inserted. ++@end deffn ++ ++@deffn Command abbrev-prefix-mark &optional arg ++This command marks the current location of point as the beginning of ++an abbrev. The next call to @code{expand-abbrev} will use the text ++from here to point (where it is then) as the abbrev to expand, rather ++than using the previous word as usual. ++ ++First, this command expands any abbrev before point, unless @var{arg} ++is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.) ++Then it inserts a hyphen before point, to indicate the start of the ++next abbrev to be expanded. The actual expansion removes the hyphen. ++@end deffn ++ ++@defopt abbrev-all-caps ++When this is set non-@code{nil}, an abbrev entered entirely in upper ++case is expanded using all upper case. Otherwise, an abbrev entered ++entirely in upper case is expanded by capitalizing each word of the ++expansion. ++@end defopt ++ ++@defvar abbrev-start-location ++The value of this variable is a buffer position (an integer or a marker) ++for @code{expand-abbrev} to use as the start of the next abbrev to be ++expanded. The value can also be @code{nil}, which means to use the ++word before point instead. @code{abbrev-start-location} is set to ++@code{nil} each time @code{expand-abbrev} is called. This variable is ++also set by @code{abbrev-prefix-mark}. ++@end defvar ++ ++@defvar abbrev-start-location-buffer ++The value of this variable is the buffer for which ++@code{abbrev-start-location} has been set. Trying to expand an abbrev ++in any other buffer clears @code{abbrev-start-location}. This variable ++is set by @code{abbrev-prefix-mark}. ++@end defvar ++ ++@defvar last-abbrev ++This is the @code{abbrev-symbol} of the most recent abbrev expanded. This ++information is left by @code{expand-abbrev} for the sake of the ++@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding ++Abbrevs, emacs, The GNU Emacs Manual}). ++@end defvar ++ ++@defvar last-abbrev-location ++This is the location of the most recent abbrev expanded. This contains ++information left by @code{expand-abbrev} for the sake of the ++@code{unexpand-abbrev} command. ++@end defvar ++ ++@defvar last-abbrev-text ++This is the exact expansion text of the most recent abbrev expanded, ++after case conversion (if any). Its value is @code{nil} if the abbrev ++has already been unexpanded. This contains information left by ++@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. ++@end defvar ++ ++@defvar abbrev-expand-functions ++This is a special hook run @emph{around} the @code{expand-abbrev} ++function. Each function on this hook is called with a single ++argument: a function that performs the normal abbrev expansion. The ++hook function can hence do anything it wants before and after ++performing the expansion. It can also choose not to call its ++argument, thus overriding the default behavior; or it may even call it ++several times. The function should return the abbrev symbol if ++expansion took place. ++@end defvar ++ ++ The following sample code shows a simple use of ++@code{abbrev-expand-functions}. It assumes that @code{foo-mode} is a ++mode for editing certain files in which lines that start with @samp{#} ++are comments. You want to use Text mode abbrevs for those lines. The ++regular local abbrev table, @code{foo-mode-abbrev-table} is ++appropriate for all other lines. Then you can put the following code ++in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the ++definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. ++ ++@smallexample ++(defun foo-mode-abbrev-expand-function (expand) ++ (if (not (save-excursion (forward-line 0) (eq (char-after) ?#))) ++ ;; Performs normal expansion. ++ (funcall expand) ++ ;; We're inside a comment: use the text-mode abbrevs. ++ (let ((local-abbrev-table text-mode-abbrev-table)) ++ (funcall expand)))) ++ ++(add-hook 'foo-mode-hook ++ #'(lambda () ++ (add-hook 'abbrev-expand-functions ++ 'foo-mode-abbrev-expand-function ++ nil t))) ++@end smallexample ++ ++@node Standard Abbrev Tables, Abbrev Properties, Abbrev Expansion, Abbrevs ++@comment node-name, next, previous, up ++@section Standard Abbrev Tables ++ ++ Here we list the variables that hold the abbrev tables for the ++preloaded major modes of Emacs. ++ ++@defvar global-abbrev-table ++This is the abbrev table for mode-independent abbrevs. The abbrevs ++defined in it apply to all buffers. Each buffer may also have a local ++abbrev table, whose abbrev definitions take precedence over those in the ++global table. ++@end defvar ++ ++@defvar local-abbrev-table ++The value of this buffer-local variable is the (mode-specific) ++abbreviation table of the current buffer. It can also be a list of ++such tables. ++@end defvar ++ ++@defvar abbrev-minor-mode-table-alist ++The value of this variable is a list of elements of the form ++@code{(@var{mode} . @var{abbrev-table})} where @var{mode} is the name ++of a variable: if the variable is bound to a non-@code{nil} value, ++then the @var{abbrev-table} is active, otherwise it is ignored. ++@var{abbrev-table} can also be a list of abbrev tables. ++@end defvar ++ ++@defvar fundamental-mode-abbrev-table ++This is the local abbrev table used in Fundamental mode; in other words, ++it is the local abbrev table in all buffers in Fundamental mode. ++@end defvar ++ ++@defvar text-mode-abbrev-table ++This is the local abbrev table used in Text mode. ++@end defvar ++ ++@defvar lisp-mode-abbrev-table ++This is the local abbrev table used in Lisp mode and Emacs Lisp mode. ++@end defvar ++ ++@node Abbrev Properties, Abbrev Table Properties, Standard Abbrev Tables, Abbrevs ++@section Abbrev Properties ++ ++Abbrevs have properties, some of which influence the way they work. ++You can provide them as arguments to @code{define-abbrev} and you can ++manipulate them with the following functions: ++ ++@defun abbrev-put abbrev prop val ++Set the property @var{prop} of @var{abbrev} to value @var{val}. ++@end defun ++ ++@defun abbrev-get abbrev prop ++Return the property @var{prop} of @var{abbrev}, or @code{nil} if the ++abbrev has no such property. ++@end defun ++ ++The following properties have special meanings: ++ ++@table @code ++@item :count ++This property counts the number of times the abbrev has ++been expanded. If not explicitly set, it is initialized to 0 by ++@code{define-abbrev}. ++ ++@item :system ++If non-@code{nil}, this property marks the abbrev as a system abbrev. ++Such abbrevs are not saved (@pxref{Abbrev Files}). ++ ++@item :enable-function ++If non-@code{nil}, this property should be a function of no ++arguments which returns @code{nil} if the abbrev should not be used ++and @code{t} otherwise. ++ ++@item :case-fixed ++If non-@code{nil}, this property indicates that the case of the ++abbrev's name is significant and should only match a text with the ++same pattern of capitalization. It also disables the code that ++modifies the capitalization of the expansion. ++@end table ++ ++@node Abbrev Table Properties, , Abbrev Properties, Abbrevs ++@section Abbrev Table Properties ++ ++Like abbrevs, abbrev tables have properties, some of which influence ++the way they work. You can provide them as arguments to ++@code{define-abbrev-table} and you can manipulate them with the ++functions: ++ ++@defun abbrev-table-put table prop val ++Set the property @var{prop} of abbrev table @var{table} to value @var{val}. ++@end defun ++ ++@defun abbrev-table-get table prop ++Return the property @var{prop} of abbrev table @var{table}, or @code{nil} ++if the abbrev has no such property. ++@end defun ++ ++The following properties have special meaning: ++ ++@table @code ++@item :enable-function ++This is like the @code{:enable-function} abbrev property except that ++it applies to all abbrevs in the table and is used even before trying ++to find the abbrev before point so it can dynamically modify the ++abbrev table. ++ ++@item :case-fixed ++This is like the @code{:case-fixed} abbrev property except that it ++applies to all abbrevs in the table. ++ ++@item :regexp ++If non-@code{nil}, this property is a regular expression that ++indicates how to extract the name of the abbrev before point before ++looking it up in the table. When the regular expression matches ++before point, the abbrev name is expected to be in submatch 1. ++If this property is @code{nil}, @code{expand-function} defaults to ++@code{"\\<\\(\\w+\\)\\W"}. This property allows the use of abbrevs ++whose name contains characters of non-word syntax. ++ ++@item :parents ++This property holds the list of tables from which to inherit ++other abbrevs. ++ ++@item :abbrev-table-modiff ++This property holds a counter incremented each time a new abbrev is ++added to the table. ++ ++@end table ++ ++ ++@ignore ++ arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec ++@end ignore +diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi +new file mode 100644 +index 0000000..57cfc61 +--- /dev/null ++++ b/doc/lispref/advice.texi +@@ -0,0 +1,783 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/advising ++@node Advising Functions, Debugging, Byte Compilation, Top ++@chapter Advising Emacs Lisp Functions ++@cindex advising functions ++ ++ The @dfn{advice} feature lets you add to the existing definition of ++a function, by @dfn{advising the function}. This is a cleaner method ++for a library to customize functions defined within Emacs---cleaner ++than redefining the whole function. ++ ++@cindex piece of advice ++ Each function can have multiple @dfn{pieces of advice}, separately ++defined. Each defined piece of advice can be @dfn{enabled} or ++@dfn{disabled} explicitly. All the enabled pieces of advice for any given ++function actually take effect when you @dfn{activate} advice for that ++function, or when you define or redefine the function. Note that ++enabling a piece of advice and activating advice for a function ++are not the same thing. ++ ++ @strong{Usage Note:} Advice is useful for altering the behavior of ++existing calls to an existing function. If you want the new behavior ++for new calls, or for key bindings, you should define a new function ++(or a new command) which uses the existing function. ++ ++ @strong{Usage note:} Advising a function can cause confusion in ++debugging, since people who debug calls to the original function may ++not notice that it has been modified with advice. Therefore, if you ++have the possibility to change the code of that function (or ask ++someone to do so) to run a hook, please solve the problem that way. ++Advice should be reserved for the cases where you cannot get the ++function changed. ++ ++ In particular, this means that a file in Emacs should not put advice ++on a function in Emacs. There are currently a few exceptions to this ++convention, but we aim to correct them. ++ ++@menu ++* Simple Advice:: A simple example to explain the basics of advice. ++* Defining Advice:: Detailed description of @code{defadvice}. ++* Around-Advice:: Wrapping advice around a function's definition. ++* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. ++* Activation of Advice:: Advice doesn't do anything until you activate it. ++* Enabling Advice:: You can enable or disable each piece of advice. ++* Preactivation:: Preactivation is a way of speeding up the ++ loading of compiled advice. ++* Argument Access in Advice:: How advice can access the function's arguments. ++* Advising Primitives:: Accessing arguments when advising a primitive. ++* Combined Definition:: How advice is implemented. ++@end menu ++ ++@node Simple Advice ++@section A Simple Advice Example ++ ++ The command @code{next-line} moves point down vertically one or more ++lines; it is the standard binding of @kbd{C-n}. When used on the last ++line of the buffer, this command inserts a newline to create a line to ++move to if @code{next-line-add-newlines} is non-@code{nil} (its default ++is @code{nil}.) ++ ++ Suppose you wanted to add a similar feature to @code{previous-line}, ++which would insert a new line at the beginning of the buffer for the ++command to move to (when @code{next-line-add-newlines} is ++non-@code{nil}). How could you do this? ++ ++ You could do it by redefining the whole function, but that is not ++modular. The advice feature provides a cleaner alternative: you can ++effectively add your code to the existing function definition, without ++actually changing or even seeing that definition. Here is how to do ++this: ++ ++@example ++(defadvice previous-line (before next-line-at-end ++ (&optional arg try-vscroll)) ++ "Insert an empty line when moving up from the top line." ++ (if (and next-line-add-newlines (= arg 1) ++ (save-excursion (beginning-of-line) (bobp))) ++ (progn ++ (beginning-of-line) ++ (newline)))) ++@end example ++ ++ This expression defines a @dfn{piece of advice} for the function ++@code{previous-line}. This piece of advice is named ++@code{next-line-at-end}, and the symbol @code{before} says that it is ++@dfn{before-advice} which should run before the regular definition of ++@code{previous-line}. @code{(&optional arg try-vscroll)} specifies ++how the advice code can refer to the function's arguments. ++ ++ When this piece of advice runs, it creates an additional line, in the ++situation where that is appropriate, but does not move point to that ++line. This is the correct way to write the advice, because the normal ++definition will run afterward and will move back to the newly inserted ++line. ++ ++ Defining the advice doesn't immediately change the function ++@code{previous-line}. That happens when you @dfn{activate} the advice, ++like this: ++ ++@example ++(ad-activate 'previous-line) ++@end example ++ ++@noindent ++This is what actually begins to use the advice that has been defined so ++far for the function @code{previous-line}. Henceforth, whenever that ++function is run, whether invoked by the user with @kbd{C-p} or ++@kbd{M-x}, or called from Lisp, it runs the advice first, and its ++regular definition second. ++ ++ This example illustrates before-advice, which is one @dfn{class} of ++advice: it runs before the function's base definition. There are two ++other advice classes: @dfn{after-advice}, which runs after the base ++definition, and @dfn{around-advice}, which lets you specify an ++expression to wrap around the invocation of the base definition. ++ ++@node Defining Advice ++@section Defining Advice ++@cindex defining advice ++@cindex advice, defining ++ ++ To define a piece of advice, use the macro @code{defadvice}. A call ++to @code{defadvice} has the following syntax, which is based on the ++syntax of @code{defun} and @code{defmacro}, but adds more: ++ ++@findex defadvice ++@example ++(defadvice @var{function} (@var{class} @var{name} ++ @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]} ++ @var{flags}...) ++ @r{[}@var{documentation-string}@r{]} ++ @r{[}@var{interactive-form}@r{]} ++ @var{body-forms}...) ++@end example ++ ++@noindent ++Here, @var{function} is the name of the function (or macro or special ++form) to be advised. From now on, we will write just ``function'' when ++describing the entity being advised, but this always includes macros and ++special forms. ++ ++ In place of the argument list in an ordinary definition, an advice ++definition calls for several different pieces of information. ++ ++@cindex class of advice ++@cindex before-advice ++@cindex after-advice ++@cindex around-advice ++@var{class} specifies the @dfn{class} of the advice---one of @code{before}, ++@code{after}, or @code{around}. Before-advice runs before the function ++itself; after-advice runs after the function itself; around-advice is ++wrapped around the execution of the function itself. After-advice and ++around-advice can override the return value by setting ++@code{ad-return-value}. ++ ++@defvar ad-return-value ++While advice is executing, after the function's original definition has ++been executed, this variable holds its return value, which will ++ultimately be returned to the caller after finishing all the advice. ++After-advice and around-advice can arrange to return some other value ++by storing it in this variable. ++@end defvar ++ ++The argument @var{name} is the name of the advice, a non-@code{nil} ++symbol. The advice name uniquely identifies one piece of advice, within all ++the pieces of advice in a particular class for a particular ++@var{function}. The name allows you to refer to the piece of ++advice---to redefine it, or to enable or disable it. ++ ++The optional @var{position} specifies where, in the current list of ++advice of the specified @var{class}, this new advice should be placed. ++It should be either @code{first}, @code{last} or a number that specifies ++a zero-based position (@code{first} is equivalent to 0). If no position ++is specified, the default is @code{first}. Position values outside the ++range of existing positions in this class are mapped to the beginning or ++the end of the range, whichever is closer. The @var{position} value is ++ignored when redefining an existing piece of advice. ++ ++The optional @var{arglist} can be used to define the argument list for ++the sake of advice. This becomes the argument list of the combined ++definition that is generated in order to run the advice (@pxref{Combined ++Definition}). Therefore, the advice expressions can use the argument ++variables in this list to access argument values. ++ ++The argument list used in advice need not be the same as the argument ++list used in the original function, but must be compatible with it, so ++that it can handle the ways the function is actually called. If two ++pieces of advice for a function both specify an argument list, they must ++specify the same argument list. ++ ++@xref{Argument Access in Advice}, for more information about argument ++lists and advice, and a more flexible way for advice to access the ++arguments. ++ ++The remaining elements, @var{flags}, are symbols that specify further ++information about how to use this piece of advice. Here are the valid ++symbols and their meanings: ++ ++@table @code ++@item activate ++Activate the advice for @var{function} now. Changes in a function's ++advice always take effect the next time you activate advice for the ++function; this flag says to do so, for @var{function}, immediately after ++defining this piece of advice. ++ ++@cindex forward advice ++This flag has no immediate effect if @var{function} itself is not defined yet (a ++situation known as @dfn{forward advice}), because it is impossible to ++activate an undefined function's advice. However, defining ++@var{function} will automatically activate its advice. ++ ++@item protect ++Protect this piece of advice against non-local exits and errors in ++preceding code and advice. Protecting advice places it as a cleanup in ++an @code{unwind-protect} form, so that it will execute even if the ++previous code gets an error or uses @code{throw}. @xref{Cleanups}. ++ ++@item compile ++Compile the combined definition that is used to run the advice. This ++flag is ignored unless @code{activate} is also specified. ++@xref{Combined Definition}. ++ ++@item disable ++Initially disable this piece of advice, so that it will not be used ++unless subsequently explicitly enabled. @xref{Enabling Advice}. ++ ++@item preactivate ++Activate advice for @var{function} when this @code{defadvice} is ++compiled or macroexpanded. This generates a compiled advised definition ++according to the current advice state, which will be used during ++activation if appropriate. @xref{Preactivation}. ++ ++This is useful only if this @code{defadvice} is byte-compiled. ++@end table ++ ++The optional @var{documentation-string} serves to document this piece of ++advice. When advice is active for @var{function}, the documentation for ++@var{function} (as returned by @code{documentation}) combines the ++documentation strings of all the advice for @var{function} with the ++documentation string of its original function definition. ++ ++The optional @var{interactive-form} form can be supplied to change the ++interactive behavior of the original function. If more than one piece ++of advice has an @var{interactive-form}, then the first one (the one ++with the smallest position) found among all the advice takes precedence. ++ ++The possibly empty list of @var{body-forms} specifies the body of the ++advice. The body of an advice can access or change the arguments, the ++return value, the binding environment, and perform any other kind of ++side effect. ++ ++@strong{Warning:} When you advise a macro, keep in mind that macros are ++expanded when a program is compiled, not when a compiled program is run. ++All subroutines used by the advice need to be available when the byte ++compiler expands the macro. ++ ++@deffn Command ad-unadvise function ++This command deletes the advice from @var{function}. ++@end deffn ++ ++@deffn Command ad-unadvise-all ++This command deletes all pieces of advice from all functions. ++@end deffn ++ ++@node Around-Advice ++@section Around-Advice ++ ++ Around-advice lets you ``wrap'' a Lisp expression ``around'' the ++original function definition. You specify where the original function ++definition should go by means of the special symbol @code{ad-do-it}. ++Where this symbol occurs inside the around-advice body, it is replaced ++with a @code{progn} containing the forms of the surrounded code. Here ++is an example: ++ ++@example ++(defadvice foo (around foo-around) ++ "Ignore case in `foo'." ++ (let ((case-fold-search t)) ++ ad-do-it)) ++@end example ++ ++@noindent ++Its effect is to make sure that case is ignored in ++searches when the original definition of @code{foo} is run. ++ ++@defvar ad-do-it ++This is not really a variable, rather a place-holder that looks like a ++variable. You use it in around-advice to specify the place to run the ++function's original definition and other ``earlier'' around-advice. ++@end defvar ++ ++If the around-advice does not use @code{ad-do-it}, then it does not run ++the original function definition. This provides a way to override the ++original definition completely. (It also overrides lower-positioned ++pieces of around-advice). ++ ++If the around-advice uses @code{ad-do-it} more than once, the original ++definition is run at each place. In this way, around-advice can execute ++the original definition (and lower-positioned pieces of around-advice) ++several times. Another way to do that is by using @code{ad-do-it} ++inside of a loop. ++ ++@node Computed Advice ++@section Computed Advice ++ ++The macro @code{defadvice} resembles @code{defun} in that the code for ++the advice, and all other information about it, are explicitly stated in ++the source code. You can also create advice whose details are computed, ++using the function @code{ad-add-advice}. ++ ++@defun ad-add-advice function advice class position ++Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to ++@var{function} in class @var{class}. The argument @var{advice} has ++this form: ++ ++@example ++(@var{name} @var{protected} @var{enabled} @var{definition}) ++@end example ++ ++@noindent ++Here, @var{protected} and @var{enabled} are flags; if @var{protected} ++is non-@code{nil}, the advice is protected against non-local exits ++(@pxref{Defining Advice}), and if @var{enabled} is @code{nil} the ++advice is initially disabled (@pxref{Enabling Advice}). ++@var{definition} should have the form ++ ++@example ++(advice . @var{lambda}) ++@end example ++ ++@noindent ++where @var{lambda} is a lambda expression; this lambda expression is ++called in order to perform the advice. @xref{Lambda Expressions}. ++ ++If the @var{function} argument to @code{ad-add-advice} already has one ++or more pieces of advice in the specified @var{class}, then ++@var{position} specifies where in the list to put the new piece of ++advice. The value of @var{position} can either be @code{first}, ++@code{last}, or a number (counting from 0 at the beginning of the ++list). Numbers outside the range are mapped to the beginning or the ++end of the range, whichever is closer. The @var{position} value is ++ignored when redefining an existing piece of advice. ++ ++If @var{function} already has a piece of @var{advice} with the same ++name, then the position argument is ignored and the old advice is ++replaced with the new one. ++@end defun ++ ++@node Activation of Advice ++@section Activation of Advice ++@cindex activating advice ++@cindex advice, activating ++ ++By default, advice does not take effect when you define it---only when ++you @dfn{activate} advice for the function that was advised. However, ++the advice will be activated automatically if you define or redefine ++the function later. You can request the activation of advice for a ++function when you define the advice, by specifying the @code{activate} ++flag in the @code{defadvice}. But normally you activate the advice ++for a function by calling the function @code{ad-activate} or one of ++the other activation commands listed below. ++ ++Separating the activation of advice from the act of defining it permits ++you to add several pieces of advice to one function efficiently, without ++redefining the function over and over as each advice is added. More ++importantly, it permits defining advice for a function before that ++function is actually defined. ++ ++When a function's advice is first activated, the function's original ++definition is saved, and all enabled pieces of advice for that function ++are combined with the original definition to make a new definition. ++(Pieces of advice that are currently disabled are not used; see ++@ref{Enabling Advice}.) This definition is installed, and optionally ++byte-compiled as well, depending on conditions described below. ++ ++In all of the commands to activate advice, if @var{compile} is ++@code{t} (or anything but @code{nil} or a negative number), the ++command also compiles the combined definition which implements the ++advice. If it is @code{nil} or a negative number, what happens ++depends on @code{ad-default-compilation-action} as described below. ++ ++@deffn Command ad-activate function &optional compile ++This command activates all the advice defined for @var{function}. ++@end deffn ++ ++ Activating advice does nothing if @var{function}'s advice is already ++active. But if there is new advice, added since the previous time you ++activated advice for @var{function}, it activates the new advice. ++ ++@deffn Command ad-deactivate function ++This command deactivates the advice for @var{function}. ++@cindex deactivating advice ++@c @cindex advice, deactivating "advice, activating" is just above ++@end deffn ++ ++@deffn Command ad-update function &optional compile ++This command activates the advice for @var{function} ++if its advice is already activated. This is useful ++if you change the advice. ++@end deffn ++ ++@deffn Command ad-activate-all &optional compile ++This command activates the advice for all functions. ++@end deffn ++ ++@deffn Command ad-deactivate-all ++This command deactivates the advice for all functions. ++@end deffn ++ ++@deffn Command ad-update-all &optional compile ++This command activates the advice for all functions ++whose advice is already activated. This is useful ++if you change the advice of some functions. ++@end deffn ++ ++@deffn Command ad-activate-regexp regexp &optional compile ++This command activates all pieces of advice whose names match ++@var{regexp}. More precisely, it activates all advice for any function ++which has at least one piece of advice that matches @var{regexp}. ++@end deffn ++ ++@deffn Command ad-deactivate-regexp regexp ++This command deactivates all pieces of advice whose names match ++@var{regexp}. More precisely, it deactivates all advice for any ++function which has at least one piece of advice that matches ++@var{regexp}. ++@end deffn ++ ++@deffn Command ad-update-regexp regexp &optional compile ++This command activates pieces of advice whose names match @var{regexp}, ++but only those for functions whose advice is already activated. ++@cindex reactivating advice ++ ++Reactivating a function's advice is useful for putting into effect all ++the changes that have been made in its advice (including enabling and ++disabling specific pieces of advice; @pxref{Enabling Advice}) since the ++last time it was activated. ++@end deffn ++ ++@deffn Command ad-start-advice ++Turn on automatic advice activation when a function is defined or ++redefined. This is the default mode. ++@end deffn ++ ++@deffn Command ad-stop-advice ++Turn off automatic advice activation when a function is defined or ++redefined. ++@end deffn ++ ++@defopt ad-default-compilation-action ++This variable controls whether to compile the combined definition ++that results from activating advice for a function. ++ ++A value of @code{always} specifies to compile unconditionally. ++A value of @code{never} specifies never compile the advice. ++ ++A value of @code{maybe} specifies to compile if the byte compiler is ++already loaded. A value of @code{like-original} specifies to compile ++the advice if the original definition of the advised function is ++compiled or a built-in function. ++ ++This variable takes effect only if the @var{compile} argument of ++@code{ad-activate} (or any of the above functions) did not force ++compilation. ++@end defopt ++ ++ If the advised definition was constructed during ``preactivation'' ++(@pxref{Preactivation}), then that definition must already be compiled, ++because it was constructed during byte-compilation of the file that ++contained the @code{defadvice} with the @code{preactivate} flag. ++ ++@node Enabling Advice ++@section Enabling and Disabling Advice ++@cindex enabling advice ++@cindex advice, enabling and disabling ++@cindex disabling advice ++ ++ Each piece of advice has a flag that says whether it is enabled or ++not. By enabling or disabling a piece of advice, you can turn it on ++and off without having to undefine and redefine it. For example, here is ++how to disable a particular piece of advice named @code{my-advice} for ++the function @code{foo}: ++ ++@example ++(ad-disable-advice 'foo 'before 'my-advice) ++@end example ++ ++ This function by itself only changes the enable flag for a piece of ++advice. To make the change take effect in the advised definition, you ++must activate the advice for @code{foo} again: ++ ++@example ++(ad-activate 'foo) ++@end example ++ ++@deffn Command ad-disable-advice function class name ++This command disables the piece of advice named @var{name} in class ++@var{class} on @var{function}. ++@end deffn ++ ++@deffn Command ad-enable-advice function class name ++This command enables the piece of advice named @var{name} in class ++@var{class} on @var{function}. ++@end deffn ++ ++ You can also disable many pieces of advice at once, for various ++functions, using a regular expression. As always, the changes take real ++effect only when you next reactivate advice for the functions in ++question. ++ ++@deffn Command ad-disable-regexp regexp ++This command disables all pieces of advice whose names match ++@var{regexp}, in all classes, on all functions. ++@end deffn ++ ++@deffn Command ad-enable-regexp regexp ++This command enables all pieces of advice whose names match ++@var{regexp}, in all classes, on all functions. ++@end deffn ++ ++@node Preactivation ++@section Preactivation ++@cindex preactivating advice ++@cindex advice, preactivating ++ ++ Constructing a combined definition to execute advice is moderately ++expensive. When a library advises many functions, this can make loading ++the library slow. In that case, you can use @dfn{preactivation} to ++construct suitable combined definitions in advance. ++ ++ To use preactivation, specify the @code{preactivate} flag when you ++define the advice with @code{defadvice}. This @code{defadvice} call ++creates a combined definition which embodies this piece of advice ++(whether enabled or not) plus any other currently enabled advice for the ++same function, and the function's own definition. If the ++@code{defadvice} is compiled, that compiles the combined definition ++also. ++ ++ When the function's advice is subsequently activated, if the enabled ++advice for the function matches what was used to make this combined ++definition, then the existing combined definition is used, thus avoiding ++the need to construct one. Thus, preactivation never causes wrong ++results---but it may fail to do any good, if the enabled advice at the ++time of activation doesn't match what was used for preactivation. ++ ++ Here are some symptoms that can indicate that a preactivation did not ++work properly, because of a mismatch. ++ ++@itemize @bullet ++@item ++Activation of the advised ++function takes longer than usual. ++@item ++The byte compiler gets ++loaded while an advised function gets activated. ++@item ++@code{byte-compile} is included in the value of @code{features} even ++though you did not ever explicitly use the byte compiler. ++@end itemize ++ ++Compiled preactivated advice works properly even if the function itself ++is not defined until later; however, the function needs to be defined ++when you @emph{compile} the preactivated advice. ++ ++There is no elegant way to find out why preactivated advice is not being ++used. What you can do is to trace the function ++@code{ad-cache-id-verification-code} (with the function ++@code{trace-function-background}) before the advised function's advice ++is activated. After activation, check the value returned by ++@code{ad-cache-id-verification-code} for that function: @code{verified} ++means that the preactivated advice was used, while other values give ++some information about why they were considered inappropriate. ++ ++ @strong{Warning:} There is one known case that can make preactivation ++fail, in that a preconstructed combined definition is used even though ++it fails to match the current state of advice. This can happen when two ++packages define different pieces of advice with the same name, in the ++same class, for the same function. But you should avoid that anyway. ++ ++@node Argument Access in Advice ++@section Argument Access in Advice ++ ++ The simplest way to access the arguments of an advised function in the ++body of a piece of advice is to use the same names that the function ++definition uses. To do this, you need to know the names of the argument ++variables of the original function. ++ ++ While this simple method is sufficient in many cases, it has a ++disadvantage: it is not robust, because it hard-codes the argument names ++into the advice. If the definition of the original function changes, ++the advice might break. ++ ++ Another method is to specify an argument list in the advice itself. ++This avoids the need to know the original function definition's argument ++names, but it has a limitation: all the advice on any particular ++function must use the same argument list, because the argument list ++actually used for all the advice comes from the first piece of advice ++for that function. ++ ++ A more robust method is to use macros that are translated into the ++proper access forms at activation time, i.e., when constructing the ++advised definition. Access macros access actual arguments by position ++regardless of how these actual arguments get distributed onto the ++argument variables of a function. This is robust because in Emacs Lisp ++the meaning of an argument is strictly determined by its position in the ++argument list. ++ ++@defmac ad-get-arg position ++This returns the actual argument that was supplied at @var{position}. ++@end defmac ++ ++@defmac ad-get-args position ++This returns the list of actual arguments supplied starting at ++@var{position}. ++@end defmac ++ ++@defmac ad-set-arg position value ++This sets the value of the actual argument at @var{position} to ++@var{value} ++@end defmac ++ ++@defmac ad-set-args position value-list ++This sets the list of actual arguments starting at @var{position} to ++@var{value-list}. ++@end defmac ++ ++ Now an example. Suppose the function @code{foo} is defined as ++ ++@example ++(defun foo (x y &optional z &rest r) ...) ++@end example ++ ++@noindent ++and is then called with ++ ++@example ++(foo 0 1 2 3 4 5 6) ++@end example ++ ++@noindent ++which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is ++@code{(3 4 5 6)} within the body of @code{foo}. Here is what ++@code{ad-get-arg} and @code{ad-get-args} return in this case: ++ ++@example ++(ad-get-arg 0) @result{} 0 ++(ad-get-arg 1) @result{} 1 ++(ad-get-arg 2) @result{} 2 ++(ad-get-arg 3) @result{} 3 ++(ad-get-args 2) @result{} (2 3 4 5 6) ++(ad-get-args 4) @result{} (4 5 6) ++@end example ++ ++ Setting arguments also makes sense in this example: ++ ++@example ++(ad-set-arg 5 "five") ++@end example ++ ++@noindent ++has the effect of changing the sixth argument to @code{"five"}. If this ++happens in advice executed before the body of @code{foo} is run, then ++@var{r} will be @code{(3 4 "five" 6)} within that body. ++ ++ Here is an example of setting a tail of the argument list: ++ ++@example ++(ad-set-args 0 '(5 4 3 2 1 0)) ++@end example ++ ++@noindent ++If this happens in advice executed before the body of @code{foo} is run, ++then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} ++will be 3, and @var{r} will be @code{(2 1 0)} inside the body of ++@code{foo}. ++ ++ These argument constructs are not really implemented as Lisp macros. ++Instead they are implemented specially by the advice mechanism. ++ ++@node Advising Primitives ++@section Advising Primitives ++@cindex advising primitives ++ ++ Advising a primitive function (@pxref{What Is a Function}) is risky. ++Some primitive functions are used by the advice mechanism; advising ++them could cause an infinite recursion. Also, many primitive ++functions are called directly from C code. Calls to the primitive ++from Lisp code will take note of the advice, but calls from C code ++will ignore the advice. ++ ++When the advice facility constructs the combined definition, it needs ++to know the argument list of the original function. This is not ++always possible for primitive functions. When advice cannot determine ++the argument list, it uses @code{(&rest ad-subr-args)}, which always ++works but is inefficient because it constructs a list of the argument ++values. You can use @code{ad-define-subr-args} to declare the proper ++argument names for a primitive function: ++ ++@defun ad-define-subr-args function arglist ++This function specifies that @var{arglist} should be used as the ++argument list for function @var{function}. ++@end defun ++ ++For example, ++ ++@example ++(ad-define-subr-args 'fset '(sym newdef)) ++@end example ++ ++@noindent ++specifies the argument list for the function @code{fset}. ++ ++@node Combined Definition ++@section The Combined Definition ++ ++ Suppose that a function has @var{n} pieces of before-advice ++(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of ++around-advice and @var{k} pieces of after-advice. Assuming no piece ++of advice is protected, the combined definition produced to implement ++the advice for a function looks like this: ++ ++@example ++(lambda @var{arglist} ++ @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} ++ (let (ad-return-value) ++ @r{before-0-body-form}... ++ .... ++ @r{before-@var{n}@minus{}1-body-form}... ++ @r{around-0-body-form}... ++ @r{around-1-body-form}... ++ .... ++ @r{around-@var{m}@minus{}1-body-form}... ++ (setq ad-return-value ++ @r{apply original definition to @var{arglist}}) ++ @r{end-of-around-@var{m}@minus{}1-body-form}... ++ .... ++ @r{end-of-around-1-body-form}... ++ @r{end-of-around-0-body-form}... ++ @r{after-0-body-form}... ++ .... ++ @r{after-@var{k}@minus{}1-body-form}... ++ ad-return-value)) ++@end example ++ ++Macros are redefined as macros, which means adding @code{macro} to ++the beginning of the combined definition. ++ ++The interactive form is present if the original function or some piece ++of advice specifies one. When an interactive primitive function is ++advised, advice uses a special method: it calls the primitive with ++@code{call-interactively} so that it will read its own arguments. ++In this case, the advice cannot access the arguments. ++ ++The body forms of the various advice in each class are assembled ++according to their specified order. The forms of around-advice @var{l} ++are included in one of the forms of around-advice @var{l} @minus{} 1. ++ ++The innermost part of the around advice onion is ++ ++@display ++apply original definition to @var{arglist} ++@end display ++ ++@noindent ++whose form depends on the type of the original function. The variable ++@code{ad-return-value} is set to whatever this returns. The variable is ++visible to all pieces of advice, which can access and modify it before ++it is actually returned from the advised function. ++ ++The semantic structure of advised functions that contain protected ++pieces of advice is the same. The only difference is that ++@code{unwind-protect} forms ensure that the protected advice gets ++executed even if some previous piece of advice had an error or a ++non-local exit. If any around-advice is protected, then the whole ++around-advice onion is protected as a result. ++ ++@ignore ++ arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f ++@end ignore +diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi +new file mode 100644 +index 0000000..df4efdf +--- /dev/null ++++ b/doc/lispref/anti.texi +@@ -0,0 +1,160 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1999, 2002, 2003, 2004, 2005, 2006, 2007, 2008, ++@c 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++ ++@c This node must have no pointers. ++ ++@node Antinews, GNU Free Documentation License, System Interface, Top ++@appendix Emacs 22 Antinews ++@c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries ++@c with the above version number. ++ ++For those users who live backwards in time, here is information about ++downgrading to Emacs version 22.3. We hope you will enjoy the greater ++simplicity that results from the absence of many Emacs @value{EMACSVER} ++features. ++ ++@section Old Lisp Features in Emacs 22 ++ ++@itemize @bullet ++@item ++The internal character representation used by Emacs is not longer ++based on Unicode. In this representation, called @code{emacs-mule}, ++each character belongs to one and only one script. Emacs makes no ++attempt to distinguish between ``similar'' characters occurring in ++different scripts. ++ ++@item ++The @code{^} interactive spec code, the function ++@code{handle-shift-selection}, and the variable ++@code{this-command-keys-shift-translated} have all been removed. ++Shift-translated keys are no longer treated specially, making Emacs' ++handling of keybindings much more consistent. ++ ++@item ++Temporarily-active regions are not created by giving the variable ++@code{transient-mark-mode} values of the form @code{(only ++. @var{oldvar})}. We instead use a more more complicated scheme: ++setting @code{transient-mark-mode} to @code{only} enables Transient ++Mark mode for the following command only, during which the value of ++@code{transient-mark-mode} is set to @code{identity}; if it is still ++@code{identity} at the end of the command, Transient Mark mode is ++disabled. ++ ++@item ++Many minibuffer functions, such as @code{read-file-name} and ++@code{minibuffer-complete}, have been rewritten in C for greater ++speed. The completion code has been considerably simplified; the ++completion style can no longer be changed via ++@code{completion-styles-alist}, and @code{completing-read} no longer ++recognizes the special values @code{confirm-only} and ++@code{confirm-after-completion} for its @var{require-match} argument. ++ ++@item ++Emacs no longer supports explicitly-numbered groups in regular ++expressions. ++ ++@item ++The @code{permanent-local-hook} function property has no special ++meaning. ++ ++@item ++The @code{functionp} function now returns @code{t} for special forms. ++ ++@item ++The @code{interactive-form} symbol property has no special meaning. ++Once you supply a function with an interactive form, the only way to ++change it is to redefine the function. ++ ++@item ++The @code{ignore-errors} macro has been moved into the @code{cl} ++package. ++ ++@item ++Variables can now be both buffer-local and frame-local; buffer-local ++bindings take precedence over frame-local bindings. ++ ++@item ++Faces can no longer be remapped. ++ ++@item ++Lisp programs now specify fonts by their names, which are strings ++following the XLFD (X logical font descriptor) format. Fonts are no ++longer represented using a special set of ``font'' data types. The ++various functions that act on these data types, such as @code{fontp}, ++@code{font-spec}, and @code{list-fonts}, have all been deleted. ++ ++@item ++Emacs does not recognize the @code{FontBackend} X resource and the ++@code{font-backend} frame parameter. On the X Window System, fonts ++are always drawn using the X core font driver. ++ ++@item ++Display terminals are no longer represented using a ``terminal'' data ++type; this is not necessary, because we have removed the ability to ++display on graphical and text-only terminals simultaneously. For the ++same reason, the @code{window-system} variable is no longer ++frame-local, and the @code{window-system} function has been removed. ++ ++@item ++The functions @code{list-system-processes} and ++@code{process-attributes} have been removed. To get information about ++system processes, call an external program, such as @command{ps}. ++ ++@item ++The function @code{locate-user-emacs-file} and the variable ++@code{user-emacs-directory} have been removed. Instead, use ++hard-coded values pointing to @file{~/.emacs.d}. ++ ++@item ++@code{vertical-motion} can no longer be told to move to a specific ++column; it always puts point on the first column of a line. ++ ++@item ++Windows no longer have parameters. ++ ++@item ++The @code{display-buffer} function has been rewritten in C. Its ++window-splitting heuristics are a little less sophisticated, and a ++little less documented. Window-splitting is handled internally, ++instead of using @code{split-window-preferred-function} (which has ++been removed). Windows are never split horizontally; the variable ++@code{split-width-threshold} has been removed. ++ ++@item ++The @code{mode-name} variable now accepts only string values, and ++cannot take the form of a mode-line construct. ++ ++@item ++The behavior of @code{map-char-table} has changed. It calls the ++mapping function for every single character in the table, instead of ++using cons cells to represent contiguous character code ranges. ++ ++@item ++Several keymaps have been eliminated: @code{input-decode-map}, ++@code{local-function-key-map}, @code{search-map}, ++@code{multi-query-replace-map}, and ++@code{minibuffer-local-shell-command-map}. ++ ++@item ++Many functions have been removed, including: @code{buffer-swap-text}, ++@code{emacs-init-time}, @code{emacs-uptime}, @code{use-region-p}, ++@code{region-active-p}, @code{start-file-process}, ++@code{process-lines}, @code{image-refresh}, ++@code{match-substitute-replacement}, @code{word-search-forward-lax}, ++and @code{word-search-backward-lax}. ++ ++@item ++Many variables have been removed, including @code{read-circle}, ++@code{after-init-time} and @code{before-init-time}, ++@code{generate-autoload-cookie}, @code{file-local-variables-alist}, ++@code{replace-search-function} and @code{replace-re-search-function}, ++@code{inhibit-changing-match-data}, @code{wrap-prefix}, and ++@code{line-prefix}, ++@end itemize ++ ++@ignore ++ arch-tag: 1d0ef137-2bad-430e-ae8e-d820d569b5a6 ++@end ignore +diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi +new file mode 100644 +index 0000000..c423b56 +--- /dev/null ++++ b/doc/lispref/back.texi +@@ -0,0 +1,42 @@ ++\input texinfo @c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@c ++@c %**start of header ++@setfilename back-cover ++@settitle GNU Emacs Lisp Reference Manual ++@c %**end of header ++. ++@sp 7 ++@center @titlefont {GNU Emacs Lisp} ++@sp 1 ++ ++@quotation ++ Most of the GNU Emacs text editor is written in the programming ++language called Emacs Lisp. You can write new code in Emacs Lisp and ++install it as an extension to the editor. However, Emacs Lisp is more ++than a mere ``extension language''; it is a full computer programming ++language in its own right. You can use it as you would any other ++programming language. ++ ++ Because Emacs Lisp is designed for use in an editor, it has special ++features for scanning and parsing text as well as features for handling ++files, buffers, displays, subprocesses, and so on. Emacs Lisp is ++closely integrated with the editing facilities; thus, editing commands ++are functions that can also conveniently be called from Lisp programs, ++and parameters for customization are ordinary Lisp variables. ++ ++ This manual describes Emacs Lisp. Generally speaking, the earlier ++chapters describe features of Emacs Lisp that have counterparts in ++many programming languages, and later chapters describe features that ++are peculiar to Emacs Lisp or relate specifically to editing. ++@end quotation ++ ++@hfil ++@bye ++ ++@ignore ++ arch-tag: ac7694c8-1f02-4b42-9531-33ba13b179e1 ++@end ignore +diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi +new file mode 100644 +index 0000000..6de8594 +--- /dev/null ++++ b/doc/lispref/backups.texi +@@ -0,0 +1,756 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2001, 2002, 2003, ++@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/backups ++@node Backups and Auto-Saving, Buffers, Files, Top ++@chapter Backups and Auto-Saving ++@cindex backups and auto-saving ++ ++ Backup files and auto-save files are two methods by which Emacs tries ++to protect the user from the consequences of crashes or of the user's ++own errors. Auto-saving preserves the text from earlier in the current ++editing session; backup files preserve file contents prior to the ++current session. ++ ++@menu ++* Backup Files:: How backup files are made; how their names are chosen. ++* Auto-Saving:: How auto-save files are made; how their names are chosen. ++* Reverting:: @code{revert-buffer}, and how to customize what it does. ++@end menu ++ ++@node Backup Files ++@section Backup Files ++@cindex backup file ++ ++ A @dfn{backup file} is a copy of the old contents of a file you are ++editing. Emacs makes a backup file the first time you save a buffer ++into its visited file. Thus, normally, the backup file contains the ++contents of the file as it was before the current editing session. ++The contents of the backup file normally remain unchanged once it ++exists. ++ ++ Backups are usually made by renaming the visited file to a new name. ++Optionally, you can specify that backup files should be made by copying ++the visited file. This choice makes a difference for files with ++multiple names; it also can affect whether the edited file remains owned ++by the original owner or becomes owned by the user editing it. ++ ++ By default, Emacs makes a single backup file for each file edited. ++You can alternatively request numbered backups; then each new backup ++file gets a new name. You can delete old numbered backups when you ++don't want them any more, or Emacs can delete them automatically. ++ ++@menu ++* Making Backups:: How Emacs makes backup files, and when. ++* Rename or Copy:: Two alternatives: renaming the old file or copying it. ++* Numbered Backups:: Keeping multiple backups for each source file. ++* Backup Names:: How backup file names are computed; customization. ++@end menu ++ ++@node Making Backups ++@subsection Making Backup Files ++ ++@defun backup-buffer ++ This function makes a backup of the file visited by the current ++buffer, if appropriate. It is called by @code{save-buffer} before ++saving the buffer the first time. ++ ++If a backup was made by renaming, the return value is a cons cell of ++the form (@var{modes} . @var{backupname}), where @var{modes} are the ++mode bits of the original file, as returned by @code{file-modes} ++(@pxref{File Attributes,, Other Information about Files}), and ++@var{backupname} is the name of the backup. In all other cases, that ++is, if a backup was made by copying or if no backup was made, this ++function returns @code{nil}. ++@end defun ++ ++@defvar buffer-backed-up ++ This buffer-local variable says whether this buffer's file has ++been backed up on account of this buffer. If it is non-@code{nil}, ++the backup file has been written. Otherwise, the file should be backed ++up when it is next saved (if backups are enabled). This is a ++permanent local; @code{kill-all-local-variables} does not alter@tie{}it. ++@end defvar ++ ++@defopt make-backup-files ++This variable determines whether or not to make backup files. If it ++is non-@code{nil}, then Emacs creates a backup of each file when it is ++saved for the first time---provided that @code{backup-inhibited} ++is @code{nil} (see below). ++ ++The following example shows how to change the @code{make-backup-files} ++variable only in the Rmail buffers and not elsewhere. Setting it ++@code{nil} stops Emacs from making backups of these files, which may ++save disk space. (You would put this code in your init file.) ++ ++@smallexample ++@group ++(add-hook 'rmail-mode-hook ++ (function (lambda () ++ (make-local-variable ++ 'make-backup-files) ++ (setq make-backup-files nil)))) ++@end group ++@end smallexample ++@end defopt ++ ++@defvar backup-enable-predicate ++This variable's value is a function to be called on certain occasions to ++decide whether a file should have backup files. The function receives ++one argument, an absolute file name to consider. If the function returns ++@code{nil}, backups are disabled for that file. Otherwise, the other ++variables in this section say whether and how to make backups. ++ ++@findex normal-backup-enable-predicate ++The default value is @code{normal-backup-enable-predicate}, which checks ++for files in @code{temporary-file-directory} and ++@code{small-temporary-file-directory}. ++@end defvar ++ ++@defvar backup-inhibited ++If this variable is non-@code{nil}, backups are inhibited. It records ++the result of testing @code{backup-enable-predicate} on the visited file ++name. It can also coherently be used by other mechanisms that inhibit ++backups based on which file is visited. For example, VC sets this ++variable non-@code{nil} to prevent making backups for files managed ++with a version control system. ++ ++This is a permanent local, so that changing the major mode does not lose ++its value. Major modes should not set this variable---they should set ++@code{make-backup-files} instead. ++@end defvar ++ ++@defopt backup-directory-alist ++This variable's value is an alist of filename patterns and backup ++directory names. Each element looks like ++@smallexample ++(@var{regexp} . @var{directory}) ++@end smallexample ++ ++@noindent ++Backups of files with names matching @var{regexp} will be made in ++@var{directory}. @var{directory} may be relative or absolute. If it is ++absolute, so that all matching files are backed up into the same ++directory, the file names in this directory will be the full name of the ++file backed up with all directory separators changed to @samp{!} to ++prevent clashes. This will not work correctly if your filesystem ++truncates the resulting name. ++ ++For the common case of all backups going into one directory, the alist ++should contain a single element pairing @samp{"."} with the appropriate ++directory name. ++ ++If this variable is @code{nil}, or it fails to match a filename, the ++backup is made in the original file's directory. ++ ++On MS-DOS filesystems without long names this variable is always ++ignored. ++@end defopt ++ ++@defopt make-backup-file-name-function ++This variable's value is a function to use for making backups instead ++of the default @code{make-backup-file-name}. A value of @code{nil} ++gives the default @code{make-backup-file-name} behavior. ++@xref{Backup Names,, Naming Backup Files}. ++ ++This could be buffer-local to do something special for specific ++files. If you define it, you may need to change ++@code{backup-file-name-p} and @code{file-name-sans-versions} too. ++@end defopt ++ ++ ++@node Rename or Copy ++@subsection Backup by Renaming or by Copying? ++@cindex backup files, rename or copy ++ ++ There are two ways that Emacs can make a backup file: ++ ++@itemize @bullet ++@item ++Emacs can rename the original file so that it becomes a backup file, and ++then write the buffer being saved into a new file. After this ++procedure, any other names (i.e., hard links) of the original file now ++refer to the backup file. The new file is owned by the user doing the ++editing, and its group is the default for new files written by the user ++in that directory. ++ ++@item ++Emacs can copy the original file into a backup file, and then overwrite ++the original file with new contents. After this procedure, any other ++names (i.e., hard links) of the original file continue to refer to the ++current (updated) version of the file. The file's owner and group will ++be unchanged. ++@end itemize ++ ++ The first method, renaming, is the default. ++ ++ The variable @code{backup-by-copying}, if non-@code{nil}, says to use ++the second method, which is to copy the original file and overwrite it ++with the new buffer contents. The variable @code{file-precious-flag}, ++if non-@code{nil}, also has this effect (as a sideline of its main ++significance). @xref{Saving Buffers}. ++ ++@defopt backup-by-copying ++If this variable is non-@code{nil}, Emacs always makes backup files by ++copying. ++@end defopt ++ ++ The following three variables, when non-@code{nil}, cause the second ++method to be used in certain special cases. They have no effect on the ++treatment of files that don't fall into the special cases. ++ ++@defopt backup-by-copying-when-linked ++If this variable is non-@code{nil}, Emacs makes backups by copying for ++files with multiple names (hard links). ++ ++This variable is significant only if @code{backup-by-copying} is ++@code{nil}, since copying is always used when that variable is ++non-@code{nil}. ++@end defopt ++ ++@defopt backup-by-copying-when-mismatch ++If this variable is non-@code{nil}, Emacs makes backups by copying in cases ++where renaming would change either the owner or the group of the file. ++ ++The value has no effect when renaming would not alter the owner or ++group of the file; that is, for files which are owned by the user and ++whose group matches the default for a new file created there by the ++user. ++ ++This variable is significant only if @code{backup-by-copying} is ++@code{nil}, since copying is always used when that variable is ++non-@code{nil}. ++@end defopt ++ ++@defopt backup-by-copying-when-privileged-mismatch ++This variable, if non-@code{nil}, specifies the same behavior as ++@code{backup-by-copying-when-mismatch}, but only for certain user-id ++values: namely, those less than or equal to a certain number. You set ++this variable to that number. ++ ++Thus, if you set @code{backup-by-copying-when-privileged-mismatch} ++to 0, backup by copying is done for the superuser only, ++when necessary to prevent a change in the owner of the file. ++ ++The default is 200. ++@end defopt ++ ++@node Numbered Backups ++@subsection Making and Deleting Numbered Backup Files ++ ++ If a file's name is @file{foo}, the names of its numbered backup ++versions are @file{foo.~@var{v}~}, for various integers @var{v}, like ++this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{}, ++@file{foo.~259~}, and so on. ++ ++@defopt version-control ++This variable controls whether to make a single non-numbered backup ++file or multiple numbered backups. ++ ++@table @asis ++@item @code{nil} ++Make numbered backups if the visited file already has numbered backups; ++otherwise, do not. This is the default. ++ ++@item @code{never} ++Do not make numbered backups. ++ ++@item @var{anything else} ++Make numbered backups. ++@end table ++@end defopt ++ ++ The use of numbered backups ultimately leads to a large number of ++backup versions, which must then be deleted. Emacs can do this ++automatically or it can ask the user whether to delete them. ++ ++@defopt kept-new-versions ++The value of this variable is the number of newest versions to keep ++when a new numbered backup is made. The newly made backup is included ++in the count. The default value is@tie{}2. ++@end defopt ++ ++@defopt kept-old-versions ++The value of this variable is the number of oldest versions to keep ++when a new numbered backup is made. The default value is@tie{}2. ++@end defopt ++ ++ If there are backups numbered 1, 2, 3, 5, and 7, and both of these ++variables have the value 2, then the backups numbered 1 and 2 are kept ++as old versions and those numbered 5 and 7 are kept as new versions; ++backup version 3 is excess. The function @code{find-backup-file-name} ++(@pxref{Backup Names}) is responsible for determining which backup ++versions to delete, but does not delete them itself. ++ ++@defopt delete-old-versions ++If this variable is @code{t}, then saving a file deletes excess ++backup versions silently. If it is @code{nil}, that means ++to ask for confirmation before deleting excess backups. ++Otherwise, they are not deleted at all. ++@end defopt ++ ++@defopt dired-kept-versions ++This variable specifies how many of the newest backup versions to keep ++in the Dired command @kbd{.} (@code{dired-clean-directory}). That's the ++same thing @code{kept-new-versions} specifies when you make a new backup ++file. The default is@tie{}2. ++@end defopt ++ ++@node Backup Names ++@subsection Naming Backup Files ++ ++ The functions in this section are documented mainly because you can ++customize the naming conventions for backup files by redefining them. ++If you change one, you probably need to change the rest. ++ ++@defun backup-file-name-p filename ++This function returns a non-@code{nil} value if @var{filename} is a ++possible name for a backup file. It just checks the name, not whether ++a file with the name @var{filename} exists. ++ ++@smallexample ++@group ++(backup-file-name-p "foo") ++ @result{} nil ++@end group ++@group ++(backup-file-name-p "foo~") ++ @result{} 3 ++@end group ++@end smallexample ++ ++The standard definition of this function is as follows: ++ ++@smallexample ++@group ++(defun backup-file-name-p (file) ++ "Return non-nil if FILE is a backup file \ ++name (numeric or not)..." ++ (string-match "~\\'" file)) ++@end group ++@end smallexample ++ ++@noindent ++Thus, the function returns a non-@code{nil} value if the file name ends ++with a @samp{~}. (We use a backslash to split the documentation ++string's first line into two lines in the text, but produce just one ++line in the string itself.) ++ ++This simple expression is placed in a separate function to make it easy ++to redefine for customization. ++@end defun ++ ++@defun make-backup-file-name filename ++This function returns a string that is the name to use for a ++non-numbered backup file for file @var{filename}. On Unix, this is just ++@var{filename} with a tilde appended. ++ ++The standard definition of this function, on most operating systems, is ++as follows: ++ ++@smallexample ++@group ++(defun make-backup-file-name (file) ++ "Create the non-numeric backup file name for FILE..." ++ (concat file "~")) ++@end group ++@end smallexample ++ ++You can change the backup-file naming convention by redefining this ++function. The following example redefines @code{make-backup-file-name} ++to prepend a @samp{.} in addition to appending a tilde: ++ ++@smallexample ++@group ++(defun make-backup-file-name (filename) ++ (expand-file-name ++ (concat "." (file-name-nondirectory filename) "~") ++ (file-name-directory filename))) ++@end group ++ ++@group ++(make-backup-file-name "backups.texi") ++ @result{} ".backups.texi~" ++@end group ++@end smallexample ++ ++Some parts of Emacs, including some Dired commands, assume that backup ++file names end with @samp{~}. If you do not follow that convention, it ++will not cause serious problems, but these commands may give ++less-than-desirable results. ++@end defun ++ ++@defun find-backup-file-name filename ++This function computes the file name for a new backup file for ++@var{filename}. It may also propose certain existing backup files for ++deletion. @code{find-backup-file-name} returns a list whose @sc{car} is ++the name for the new backup file and whose @sc{cdr} is a list of backup ++files whose deletion is proposed. The value can also be @code{nil}, ++which means not to make a backup. ++ ++Two variables, @code{kept-old-versions} and @code{kept-new-versions}, ++determine which backup versions should be kept. This function keeps ++those versions by excluding them from the @sc{cdr} of the value. ++@xref{Numbered Backups}. ++ ++In this example, the value says that @file{~rms/foo.~5~} is the name ++to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess'' ++version that the caller should consider deleting now. ++ ++@smallexample ++@group ++(find-backup-file-name "~rms/foo") ++ @result{} ("~rms/foo.~5~" "~rms/foo.~3~") ++@end group ++@end smallexample ++@end defun ++ ++@c Emacs 19 feature ++@defun file-newest-backup filename ++This function returns the name of the most recent backup file for ++@var{filename}, or @code{nil} if that file has no backup files. ++ ++Some file comparison commands use this function so that they can ++automatically compare a file with its most recent backup. ++@end defun ++ ++@node Auto-Saving ++@section Auto-Saving ++@c @cindex auto-saving Lots of symbols starting with auto-save here. ++ ++ Emacs periodically saves all files that you are visiting; this is ++called @dfn{auto-saving}. Auto-saving prevents you from losing more ++than a limited amount of work if the system crashes. By default, ++auto-saves happen every 300 keystrokes, or after around 30 seconds of ++idle time. @xref{Auto Save, Auto Save, Auto-Saving: Protection Against ++Disasters, emacs, The GNU Emacs Manual}, for information on auto-save ++for users. Here we describe the functions used to implement auto-saving ++and the variables that control them. ++ ++@defvar buffer-auto-save-file-name ++This buffer-local variable is the name of the file used for ++auto-saving the current buffer. It is @code{nil} if the buffer ++should not be auto-saved. ++ ++@example ++@group ++buffer-auto-save-file-name ++ @result{} "/xcssun/users/rms/lewis/#backups.texi#" ++@end group ++@end example ++@end defvar ++ ++@deffn Command auto-save-mode arg ++When used interactively without an argument, this command is a toggle ++switch: it turns on auto-saving of the current buffer if it is off, and ++vice versa. With an argument @var{arg}, the command turns auto-saving ++on if the value of @var{arg} is @code{t}, a nonempty list, or a positive ++integer. Otherwise, it turns auto-saving off. ++@end deffn ++ ++@defun auto-save-file-name-p filename ++This function returns a non-@code{nil} value if @var{filename} is a ++string that could be the name of an auto-save file. It assumes ++the usual naming convention for auto-save files: a name that ++begins and ends with hash marks (@samp{#}) is a possible auto-save file ++name. The argument @var{filename} should not contain a directory part. ++ ++@example ++@group ++(make-auto-save-file-name) ++ @result{} "/xcssun/users/rms/lewis/#backups.texi#" ++@end group ++@group ++(auto-save-file-name-p "#backups.texi#") ++ @result{} 0 ++@end group ++@group ++(auto-save-file-name-p "backups.texi") ++ @result{} nil ++@end group ++@end example ++ ++The standard definition of this function is as follows: ++ ++@example ++@group ++(defun auto-save-file-name-p (filename) ++ "Return non-nil if FILENAME can be yielded by..." ++ (string-match "^#.*#$" filename)) ++@end group ++@end example ++ ++This function exists so that you can customize it if you wish to ++change the naming convention for auto-save files. If you redefine it, ++be sure to redefine the function @code{make-auto-save-file-name} ++correspondingly. ++@end defun ++ ++@defun make-auto-save-file-name ++This function returns the file name to use for auto-saving the current ++buffer. This is just the file name with hash marks (@samp{#}) prepended ++and appended to it. This function does not look at the variable ++@code{auto-save-visited-file-name} (described below); callers of this ++function should check that variable first. ++ ++@example ++@group ++(make-auto-save-file-name) ++ @result{} "/xcssun/users/rms/lewis/#backups.texi#" ++@end group ++@end example ++ ++Here is a simplified version of the standard definition of this ++function: ++ ++@example ++@group ++(defun make-auto-save-file-name () ++ "Return file name to use for auto-saves \ ++of current buffer.." ++ (if buffer-file-name ++@end group ++@group ++ (concat ++ (file-name-directory buffer-file-name) ++ "#" ++ (file-name-nondirectory buffer-file-name) ++ "#") ++ (expand-file-name ++ (concat "#%" (buffer-name) "#")))) ++@end group ++@end example ++ ++This exists as a separate function so that you can redefine it to ++customize the naming convention for auto-save files. Be sure to ++change @code{auto-save-file-name-p} in a corresponding way. ++@end defun ++ ++@defopt auto-save-visited-file-name ++If this variable is non-@code{nil}, Emacs auto-saves buffers in ++the files they are visiting. That is, the auto-save is done in the same ++file that you are editing. Normally, this variable is @code{nil}, so ++auto-save files have distinct names that are created by ++@code{make-auto-save-file-name}. ++ ++When you change the value of this variable, the new value does not take ++effect in an existing buffer until the next time auto-save mode is ++reenabled in it. If auto-save mode is already enabled, auto-saves ++continue to go in the same file name until @code{auto-save-mode} is ++called again. ++@end defopt ++ ++@defun recent-auto-save-p ++This function returns @code{t} if the current buffer has been ++auto-saved since the last time it was read in or saved. ++@end defun ++ ++@defun set-buffer-auto-saved ++This function marks the current buffer as auto-saved. The buffer will ++not be auto-saved again until the buffer text is changed again. The ++function returns @code{nil}. ++@end defun ++ ++@defopt auto-save-interval ++The value of this variable specifies how often to do auto-saving, in ++terms of number of input events. Each time this many additional input ++events are read, Emacs does auto-saving for all buffers in which that is ++enabled. Setting this to zero disables autosaving based on the ++number of characters typed. ++@end defopt ++ ++@defopt auto-save-timeout ++The value of this variable is the number of seconds of idle time that ++should cause auto-saving. Each time the user pauses for this long, ++Emacs does auto-saving for all buffers in which that is enabled. (If ++the current buffer is large, the specified timeout is multiplied by a ++factor that increases as the size increases; for a million-byte ++buffer, the factor is almost 4.) ++ ++If the value is zero or @code{nil}, then auto-saving is not done as a ++result of idleness, only after a certain number of input events as ++specified by @code{auto-save-interval}. ++@end defopt ++ ++@defvar auto-save-hook ++This normal hook is run whenever an auto-save is about to happen. ++@end defvar ++ ++@defopt auto-save-default ++If this variable is non-@code{nil}, buffers that are visiting files ++have auto-saving enabled by default. Otherwise, they do not. ++@end defopt ++ ++@deffn Command do-auto-save &optional no-message current-only ++This function auto-saves all buffers that need to be auto-saved. It ++saves all buffers for which auto-saving is enabled and that have been ++changed since the previous auto-save. ++ ++If any buffers are auto-saved, @code{do-auto-save} normally displays a ++message saying @samp{Auto-saving...} in the echo area while ++auto-saving is going on. However, if @var{no-message} is ++non-@code{nil}, the message is inhibited. ++ ++If @var{current-only} is non-@code{nil}, only the current buffer ++is auto-saved. ++@end deffn ++ ++@defun delete-auto-save-file-if-necessary &optional force ++This function deletes the current buffer's auto-save file if ++@code{delete-auto-save-files} is non-@code{nil}. It is called every ++time a buffer is saved. ++ ++Unless @var{force} is non-@code{nil}, this function only deletes the ++file if it was written by the current Emacs session since the last ++true save. ++@end defun ++ ++@defopt delete-auto-save-files ++This variable is used by the function ++@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil}, ++Emacs deletes auto-save files when a true save is done (in the visited ++file). This saves disk space and unclutters your directory. ++@end defopt ++ ++@defun rename-auto-save-file ++This function adjusts the current buffer's auto-save file name if the ++visited file name has changed. It also renames an existing auto-save ++file, if it was made in the current Emacs session. If the visited ++file name has not changed, this function does nothing. ++@end defun ++ ++@defvar buffer-saved-size ++The value of this buffer-local variable is the length of the current ++buffer, when it was last read in, saved, or auto-saved. This is ++used to detect a substantial decrease in size, and turn off auto-saving ++in response. ++ ++If it is @minus{}1, that means auto-saving is temporarily shut off in ++this buffer due to a substantial decrease in size. Explicitly saving ++the buffer stores a positive value in this variable, thus reenabling ++auto-saving. Turning auto-save mode off or on also updates this ++variable, so that the substantial decrease in size is forgotten. ++@end defvar ++ ++@defvar auto-save-list-file-name ++This variable (if non-@code{nil}) specifies a file for recording the ++names of all the auto-save files. Each time Emacs does auto-saving, it ++writes two lines into this file for each buffer that has auto-saving ++enabled. The first line gives the name of the visited file (it's empty ++if the buffer has none), and the second gives the name of the auto-save ++file. ++ ++When Emacs exits normally, it deletes this file; if Emacs crashes, you ++can look in the file to find all the auto-save files that might contain ++work that was otherwise lost. The @code{recover-session} command uses ++this file to find them. ++ ++The default name for this file specifies your home directory and starts ++with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the ++host name. ++@end defvar ++ ++@defopt auto-save-list-file-prefix ++After Emacs reads your init file, it initializes ++@code{auto-save-list-file-name} (if you have not already set it ++non-@code{nil}) based on this prefix, adding the host name and process ++ID. If you set this to @code{nil} in your init file, then Emacs does ++not initialize @code{auto-save-list-file-name}. ++@end defopt ++ ++@node Reverting ++@section Reverting ++ ++ If you have made extensive changes to a file and then change your mind ++about them, you can get rid of them by reading in the previous version ++of the file with the @code{revert-buffer} command. @xref{Reverting, , ++Reverting a Buffer, emacs, The GNU Emacs Manual}. ++ ++@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes ++This command replaces the buffer text with the text of the visited ++file on disk. This action undoes all changes since the file was visited ++or saved. ++ ++By default, if the latest auto-save file is more recent than the visited ++file, and the argument @var{ignore-auto} is @code{nil}, ++@code{revert-buffer} asks the user whether to use that auto-save ++instead. When you invoke this command interactively, @var{ignore-auto} ++is @code{t} if there is no numeric prefix argument; thus, the ++interactive default is not to check the auto-save file. ++ ++Normally, @code{revert-buffer} asks for confirmation before it changes ++the buffer; but if the argument @var{noconfirm} is non-@code{nil}, ++@code{revert-buffer} does not ask for confirmation. ++ ++Normally, this command reinitializes the buffer's major and minor modes ++using @code{normal-mode}. But if @var{preserve-modes} is ++non-@code{nil}, the modes remain unchanged. ++ ++Reverting tries to preserve marker positions in the buffer by using the ++replacement feature of @code{insert-file-contents}. If the buffer ++contents and the file contents are identical before the revert ++operation, reverting preserves all the markers. If they are not ++identical, reverting does change the buffer; in that case, it preserves ++the markers in the unchanged text (if any) at the beginning and end of ++the buffer. Preserving any additional markers would be problematical. ++@end deffn ++ ++You can customize how @code{revert-buffer} does its work by setting ++the variables described in the rest of this section. ++ ++@defopt revert-without-query ++This variable holds a list of files that should be reverted without ++query. The value is a list of regular expressions. If the visited file ++name matches one of these regular expressions, and the file has changed ++on disk but the buffer is not modified, then @code{revert-buffer} ++reverts the file without asking the user for confirmation. ++@end defopt ++ ++ Some major modes customize @code{revert-buffer} by making ++buffer-local bindings for these variables: ++ ++@defvar revert-buffer-function ++@anchor{Definition of revert-buffer-function} ++The value of this variable is the function to use to revert this ++buffer. If non-@code{nil}, it should be a function with two optional ++arguments to do the work of reverting. The two optional arguments, ++@var{ignore-auto} and @var{noconfirm}, are the arguments that ++@code{revert-buffer} received. If the value is @code{nil}, reverting ++works the usual way. ++ ++Modes such as Dired mode, in which the text being edited does not ++consist of a file's contents but can be regenerated in some other ++fashion, can give this variable a buffer-local value that is a function to ++regenerate the contents. ++@end defvar ++ ++@defvar revert-buffer-insert-file-contents-function ++The value of this variable, if non-@code{nil}, specifies the function to use to ++insert the updated contents when reverting this buffer. The function ++receives two arguments: first the file name to use; second, @code{t} if ++the user has asked to read the auto-save file. ++ ++The reason for a mode to set this variable instead of ++@code{revert-buffer-function} is to avoid duplicating or replacing the ++rest of what @code{revert-buffer} does: asking for confirmation, ++clearing the undo list, deciding the proper major mode, and running the ++hooks listed below. ++@end defvar ++ ++@defvar before-revert-hook ++This normal hook is run by @code{revert-buffer} before ++inserting the modified contents---but only if ++@code{revert-buffer-function} is @code{nil}. ++@end defvar ++ ++@defvar after-revert-hook ++This normal hook is run by @code{revert-buffer} after inserting ++the modified contents---but only if @code{revert-buffer-function} is ++@code{nil}. ++@end defvar ++ ++@ignore ++ arch-tag: 295a6321-e5ab-46d5-aef5-0bb4f447a67f ++@end ignore +diff --git a/doc/lispref/book-spine.texinfo b/doc/lispref/book-spine.texinfo +new file mode 100644 +index 0000000..4f4c91a +--- /dev/null ++++ b/doc/lispref/book-spine.texinfo +@@ -0,0 +1,29 @@ ++\input texinfo @c -*-texinfo-*- ++@c %**start of header ++@setfilename book-spine ++@settitle book-spine ++@c %**end of header ++ ++@c need dot in text so first space command works! ++. ++@sp 7 ++ ++@center @titlefont{GNU Emacs Lisp Reference Manual} ++@sp 5 ++@center GNU ++@center Emacs Version 23.1 ++@center for Unix Users ++@sp 5 ++ ++@center by ++@center Bil Lewis, ++@center Dan LaLiberte, ++@center and the ++@center GNU Manual Group ++@sp 5 ++@center Free Software Foundation ++@bye ++ ++@ignore ++ arch-tag: 4466c7ca-e549-4119-948c-6eed34e1ff87 ++@end ignore +diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi +new file mode 100644 +index 0000000..5d03865 +--- /dev/null ++++ b/doc/lispref/buffers.texi +@@ -0,0 +1,1221 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/buffers ++@node Buffers, Windows, Backups and Auto-Saving, Top ++@chapter Buffers ++@cindex buffer ++ ++ A @dfn{buffer} is a Lisp object containing text to be edited. Buffers ++are used to hold the contents of files that are being visited; there may ++also be buffers that are not visiting files. While several buffers may ++exist at one time, only one buffer is designated the @dfn{current ++buffer} at any time. Most editing commands act on the contents of the ++current buffer. Each buffer, including the current buffer, may or may ++not be displayed in any windows. ++ ++@menu ++* Buffer Basics:: What is a buffer? ++* Current Buffer:: Designating a buffer as current ++ so that primitives will access its contents. ++* Buffer Names:: Accessing and changing buffer names. ++* Buffer File Name:: The buffer file name indicates which file is visited. ++* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. ++* Modification Time:: Determining whether the visited file was changed ++ ``behind Emacs's back''. ++* Read Only Buffers:: Modifying text is not allowed in a read-only buffer. ++* The Buffer List:: How to look at all the existing buffers. ++* Creating Buffers:: Functions that create buffers. ++* Killing Buffers:: Buffers exist until explicitly killed. ++* Indirect Buffers:: An indirect buffer shares text with some other buffer. ++* Swapping Text:: Swapping text between two buffers. ++* Buffer Gap:: The gap in the buffer. ++@end menu ++ ++@node Buffer Basics ++@comment node-name, next, previous, up ++@section Buffer Basics ++ ++@ifnottex ++ A @dfn{buffer} is a Lisp object containing text to be edited. Buffers ++are used to hold the contents of files that are being visited; there may ++also be buffers that are not visiting files. Although several buffers ++normally exist, only one buffer is designated the @dfn{current ++buffer} at any time. Most editing commands act on the contents of the ++current buffer. Each buffer, including the current buffer, may or may ++not be displayed in any windows. ++@end ifnottex ++ ++ Buffers in Emacs editing are objects that have distinct names and hold ++text that can be edited. Buffers appear to Lisp programs as a special ++data type. You can think of the contents of a buffer as a string that ++you can extend; insertions and deletions may occur in any part of the ++buffer. @xref{Text}. ++ ++ A Lisp buffer object contains numerous pieces of information. Some of ++this information is directly accessible to the programmer through ++variables, while other information is accessible only through ++special-purpose functions. For example, the visited file name is ++directly accessible through a variable, while the value of point is ++accessible only through a primitive function. ++ ++ Buffer-specific information that is directly accessible is stored in ++@dfn{buffer-local} variable bindings, which are variable values that are ++effective only in a particular buffer. This feature allows each buffer ++to override the values of certain variables. Most major modes override ++variables such as @code{fill-column} or @code{comment-column} in this ++way. For more information about buffer-local variables and functions ++related to them, see @ref{Buffer-Local Variables}. ++ ++ For functions and variables related to visiting files in buffers, see ++@ref{Visiting Files} and @ref{Saving Buffers}. For functions and ++variables related to the display of buffers in windows, see ++@ref{Buffers and Windows}. ++ ++@defun bufferp object ++This function returns @code{t} if @var{object} is a buffer, ++@code{nil} otherwise. ++@end defun ++ ++@node Current Buffer ++@section The Current Buffer ++@cindex selecting a buffer ++@cindex changing to another buffer ++@cindex current buffer ++ ++ There are, in general, many buffers in an Emacs session. At any time, ++one of them is designated as the @dfn{current buffer}. This is the ++buffer in which most editing takes place, because most of the primitives ++for examining or changing text in a buffer operate implicitly on the ++current buffer (@pxref{Text}). Normally the buffer that is displayed on ++the screen in the selected window is the current buffer, but this is not ++always so: a Lisp program can temporarily designate any buffer as ++current in order to operate on its contents, without changing what is ++displayed on the screen. ++ ++ The way to designate a current buffer in a Lisp program is by calling ++@code{set-buffer}. The specified buffer remains current until a new one ++is designated. ++ ++ When an editing command returns to the editor command loop, the ++command loop designates the buffer displayed in the selected window as ++current, to prevent confusion: the buffer that the cursor is in when ++Emacs reads a command is the buffer that the command will apply to. ++(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to ++switch visibly to a different buffer so that the user can edit it. For ++that, you must use the functions described in @ref{Displaying Buffers}. ++ ++ @strong{Warning:} Lisp functions that change to a different current buffer ++should not depend on the command loop to set it back afterwards. ++Editing commands written in Emacs Lisp can be called from other programs ++as well as from the command loop; it is convenient for the caller if ++the subroutine does not change which buffer is current (unless, of ++course, that is the subroutine's purpose). Therefore, you should ++normally use @code{set-buffer} within a @code{save-current-buffer} or ++@code{save-excursion} (@pxref{Excursions}) form that will restore the ++current buffer when your function is done. Here, as an example, is a ++simplified version of the command @code{append-to-buffer}: ++ ++@example ++@group ++(defun append-to-buffer (buffer start end) ++ "Append to specified buffer the text of the region." ++ (interactive "BAppend to buffer: \nr") ++ (let ((oldbuf (current-buffer))) ++ (save-current-buffer ++ (set-buffer (get-buffer-create buffer)) ++ (insert-buffer-substring oldbuf start end)))) ++@end group ++@end example ++ ++@noindent ++This function binds a local variable to record the current buffer, and ++then @code{save-current-buffer} arranges to make it current again. ++Next, @code{set-buffer} makes the specified buffer current. Finally, ++@code{insert-buffer-substring} copies the string from the original ++current buffer to the specified (and now current) buffer. ++ ++ If the buffer appended to happens to be displayed in some window, ++the next redisplay will show how its text has changed. Otherwise, you ++will not see the change immediately on the screen. The buffer becomes ++current temporarily during the execution of the command, but this does ++not cause it to be displayed. ++ ++ If you make local bindings (with @code{let} or function arguments) for ++a variable that may also have buffer-local bindings, make sure that the ++same buffer is current at the beginning and at the end of the local ++binding's scope. Otherwise you might bind it in one buffer and unbind ++it in another! There are two ways to do this. In simple cases, you may ++see that nothing ever changes the current buffer within the scope of the ++binding. Otherwise, use @code{save-current-buffer} or ++@code{save-excursion} to make sure that the buffer current at the ++beginning is current again whenever the variable is unbound. ++ ++ Do not rely on using @code{set-buffer} to change the current buffer ++back, because that won't do the job if a quit happens while the wrong ++buffer is current. For instance, in the previous example, it would ++have been wrong to do this: ++ ++@example ++@group ++ (let ((oldbuf (current-buffer))) ++ (set-buffer (get-buffer-create buffer)) ++ (insert-buffer-substring oldbuf start end) ++ (set-buffer oldbuf)) ++@end group ++@end example ++ ++@noindent ++Using @code{save-current-buffer}, as we did, handles quitting, errors, ++and @code{throw}, as well as ordinary evaluation. ++ ++@defun current-buffer ++This function returns the current buffer. ++ ++@example ++@group ++(current-buffer) ++ @result{} # ++@end group ++@end example ++@end defun ++ ++@defun set-buffer buffer-or-name ++This function makes @var{buffer-or-name} the current buffer. ++@var{buffer-or-name} must be an existing buffer or the name of an ++existing buffer. The return value is the buffer made current. ++ ++This function does not display the buffer in any window, so the user ++cannot necessarily see the buffer. But Lisp programs will now operate ++on it. ++@end defun ++ ++@defspec save-current-buffer body@dots{} ++The @code{save-current-buffer} special form saves the identity of the ++current buffer, evaluates the @var{body} forms, and finally restores ++that buffer as current. The return value is the value of the last ++form in @var{body}. The current buffer is restored even in case of an ++abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). ++ ++If the buffer that used to be current has been killed by the time of ++exit from @code{save-current-buffer}, then it is not made current again, ++of course. Instead, whichever buffer was current just before exit ++remains current. ++@end defspec ++ ++@defmac with-current-buffer buffer-or-name body@dots{} ++The @code{with-current-buffer} macro saves the identity of the current ++buffer, makes @var{buffer-or-name} current, evaluates the @var{body} ++forms, and finally restores the current buffer. @var{buffer-or-name} ++must specify an existing buffer or the name of an existing buffer. ++ ++The return value is the value of the last form in @var{body}. The ++current buffer is restored even in case of an abnormal exit via ++@code{throw} or error (@pxref{Nonlocal Exits}). ++@end defmac ++ ++@defmac with-temp-buffer body@dots{} ++@anchor{Definition of with-temp-buffer} ++The @code{with-temp-buffer} macro evaluates the @var{body} forms ++with a temporary buffer as the current buffer. It saves the identity of ++the current buffer, creates a temporary buffer and makes it current, ++evaluates the @var{body} forms, and finally restores the previous ++current buffer while killing the temporary buffer. By default, undo ++information (@pxref{Undo}) is not recorded in the buffer created by ++this macro (but @var{body} can enable that, if needed). ++ ++The return value is the value of the last form in @var{body}. You can ++return the contents of the temporary buffer by using ++@code{(buffer-string)} as the last form. ++ ++The current buffer is restored even in case of an abnormal exit via ++@code{throw} or error (@pxref{Nonlocal Exits}). ++ ++See also @code{with-temp-file} in @ref{Definition of with-temp-file,, ++Writing to Files}. ++@end defmac ++ ++@node Buffer Names ++@section Buffer Names ++@cindex buffer names ++ ++ Each buffer has a unique name, which is a string. Many of the ++functions that work on buffers accept either a buffer or a buffer name ++as an argument. Any argument called @var{buffer-or-name} is of this ++sort, and an error is signaled if it is neither a string nor a buffer. ++Any argument called @var{buffer} must be an actual buffer ++object, not a name. ++ ++@cindex hidden buffers ++@cindex buffers without undo information ++ Buffers that are ephemeral and generally uninteresting to the user ++have names starting with a space, so that the @code{list-buffers} and ++@code{buffer-menu} commands don't mention them (but if such a buffer ++visits a file, it @strong{is} mentioned). A name starting with ++space also initially disables recording undo information; see ++@ref{Undo}. ++ ++@defun buffer-name &optional buffer ++This function returns the name of @var{buffer} as a string. ++@var{buffer} defaults to the current buffer. ++ ++If @code{buffer-name} returns @code{nil}, it means that @var{buffer} ++has been killed. @xref{Killing Buffers}. ++ ++@example ++@group ++(buffer-name) ++ @result{} "buffers.texi" ++@end group ++ ++@group ++(setq foo (get-buffer "temp")) ++ @result{} # ++@end group ++@group ++(kill-buffer foo) ++ @result{} nil ++@end group ++@group ++(buffer-name foo) ++ @result{} nil ++@end group ++@group ++foo ++ @result{} # ++@end group ++@end example ++@end defun ++ ++@deffn Command rename-buffer newname &optional unique ++This function renames the current buffer to @var{newname}. An error ++is signaled if @var{newname} is not a string. ++ ++@c Emacs 19 feature ++Ordinarily, @code{rename-buffer} signals an error if @var{newname} is ++already in use. However, if @var{unique} is non-@code{nil}, it modifies ++@var{newname} to make a name that is not in use. Interactively, you can ++make @var{unique} non-@code{nil} with a numeric prefix argument. ++(This is how the command @code{rename-uniquely} is implemented.) ++ ++This function returns the name actually given to the buffer. ++@end deffn ++ ++@defun get-buffer buffer-or-name ++This function returns the buffer specified by @var{buffer-or-name}. ++If @var{buffer-or-name} is a string and there is no buffer with that ++name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it ++is returned as given; that is not very useful, so the argument is usually ++a name. For example: ++ ++@example ++@group ++(setq b (get-buffer "lewis")) ++ @result{} # ++@end group ++@group ++(get-buffer b) ++ @result{} # ++@end group ++@group ++(get-buffer "Frazzle-nots") ++ @result{} nil ++@end group ++@end example ++ ++See also the function @code{get-buffer-create} in @ref{Creating Buffers}. ++@end defun ++ ++@c Emacs 19 feature ++@defun generate-new-buffer-name starting-name &optional ignore ++This function returns a name that would be unique for a new buffer---but ++does not create the buffer. It starts with @var{starting-name}, and ++produces a name not currently in use for any buffer by appending a ++number inside of @samp{<@dots{}>}. It starts at 2 and keeps ++incrementing the number until it is not the name of an existing buffer. ++ ++If the optional second argument @var{ignore} is non-@code{nil}, it ++should be a string, a potential buffer name. It means to consider ++that potential buffer acceptable, if it is tried, even it is the name ++of an existing buffer (which would normally be rejected). Thus, if ++buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and ++@samp{foo<4>} exist, ++ ++@example ++(generate-new-buffer-name "foo") ++ @result{} "foo<5>" ++(generate-new-buffer-name "foo" "foo<3>") ++ @result{} "foo<3>" ++(generate-new-buffer-name "foo" "foo<6>") ++ @result{} "foo<5>" ++@end example ++ ++See the related function @code{generate-new-buffer} in @ref{Creating ++Buffers}. ++@end defun ++ ++@node Buffer File Name ++@section Buffer File Name ++@cindex visited file ++@cindex buffer file name ++@cindex file name of buffer ++ ++ The @dfn{buffer file name} is the name of the file that is visited in ++that buffer. When a buffer is not visiting a file, its buffer file name ++is @code{nil}. Most of the time, the buffer name is the same as the ++nondirectory part of the buffer file name, but the buffer file name and ++the buffer name are distinct and can be set independently. ++@xref{Visiting Files}. ++ ++@defun buffer-file-name &optional buffer ++This function returns the absolute file name of the file that ++@var{buffer} is visiting. If @var{buffer} is not visiting any file, ++@code{buffer-file-name} returns @code{nil}. If @var{buffer} is not ++supplied, it defaults to the current buffer. ++ ++@example ++@group ++(buffer-file-name (other-buffer)) ++ @result{} "/usr/user/lewis/manual/files.texi" ++@end group ++@end example ++@end defun ++ ++@defvar buffer-file-name ++This buffer-local variable contains the name of the file being visited ++in the current buffer, or @code{nil} if it is not visiting a file. It ++is a permanent local variable, unaffected by ++@code{kill-all-local-variables}. ++ ++@example ++@group ++buffer-file-name ++ @result{} "/usr/user/lewis/manual/buffers.texi" ++@end group ++@end example ++ ++It is risky to change this variable's value without doing various other ++things. Normally it is better to use @code{set-visited-file-name} (see ++below); some of the things done there, such as changing the buffer name, ++are not strictly necessary, but others are essential to avoid confusing ++Emacs. ++@end defvar ++ ++@defvar buffer-file-truename ++This buffer-local variable holds the abbreviated truename of the file ++visited in the current buffer, or @code{nil} if no file is visited. ++It is a permanent local, unaffected by ++@code{kill-all-local-variables}. @xref{Truenames}, and ++@ref{Definition of abbreviate-file-name}. ++@end defvar ++ ++@defvar buffer-file-number ++This buffer-local variable holds the file number and directory device ++number of the file visited in the current buffer, or @code{nil} if no ++file or a nonexistent file is visited. It is a permanent local, ++unaffected by @code{kill-all-local-variables}. ++ ++The value is normally a list of the form @code{(@var{filenum} ++@var{devnum})}. This pair of numbers uniquely identifies the file among ++all files accessible on the system. See the function ++@code{file-attributes}, in @ref{File Attributes}, for more information ++about them. ++ ++If @code{buffer-file-name} is the name of a symbolic link, then both ++numbers refer to the recursive target. ++@end defvar ++ ++@defun get-file-buffer filename ++This function returns the buffer visiting file @var{filename}. If ++there is no such buffer, it returns @code{nil}. The argument ++@var{filename}, which must be a string, is expanded (@pxref{File Name ++Expansion}), then compared against the visited file names of all live ++buffers. Note that the buffer's @code{buffer-file-name} must match ++the expansion of @var{filename} exactly. This function will not ++recognize other names for the same file. ++ ++@example ++@group ++(get-file-buffer "buffers.texi") ++ @result{} # ++@end group ++@end example ++ ++In unusual circumstances, there can be more than one buffer visiting ++the same file name. In such cases, this function returns the first ++such buffer in the buffer list. ++@end defun ++ ++@defun find-buffer-visiting filename &optional predicate ++This is like @code{get-file-buffer}, except that it can return any ++buffer visiting the file @emph{possibly under a different name}. That ++is, the buffer's @code{buffer-file-name} does not need to match the ++expansion of @var{filename} exactly, it only needs to refer to the ++same file. If @var{predicate} is non-@code{nil}, it should be a ++function of one argument, a buffer visiting @var{filename}. The ++buffer is only considered a suitable return value if @var{predicate} ++returns non-@code{nil}. If it can not find a suitable buffer to ++return, @code{find-buffer-visiting} returns @code{nil}. ++@end defun ++ ++@deffn Command set-visited-file-name filename &optional no-query along-with-file ++If @var{filename} is a non-empty string, this function changes the ++name of the file visited in the current buffer to @var{filename}. (If the ++buffer had no visited file, this gives it one.) The @emph{next time} ++the buffer is saved it will go in the newly-specified file. ++ ++This command marks the buffer as modified, since it does not (as far ++as Emacs knows) match the contents of @var{filename}, even if it ++matched the former visited file. It also renames the buffer to ++correspond to the new file name, unless the new name is already in ++use. ++ ++If @var{filename} is @code{nil} or the empty string, that stands for ++``no visited file.'' In this case, @code{set-visited-file-name} marks ++the buffer as having no visited file, without changing the buffer's ++modified flag. ++ ++Normally, this function asks the user for confirmation if there ++already is a buffer visiting @var{filename}. If @var{no-query} is ++non-@code{nil}, that prevents asking this question. If there already ++is a buffer visiting @var{filename}, and the user confirms or ++@var{query} is non-@code{nil}, this function makes the new buffer name ++unique by appending a number inside of @samp{<@dots{}>} to @var{filename}. ++ ++If @var{along-with-file} is non-@code{nil}, that means to assume that ++the former visited file has been renamed to @var{filename}. In this ++case, the command does not change the buffer's modified flag, nor the ++buffer's recorded last file modification time as reported by ++@code{visited-file-modtime} (@pxref{Modification Time}). If ++@var{along-with-file} is @code{nil}, this function clears the recorded ++last file modification time, after which @code{visited-file-modtime} ++returns zero. ++ ++@c Wordy to avoid overfull hbox. --rjc 16mar92 ++When the function @code{set-visited-file-name} is called interactively, it ++prompts for @var{filename} in the minibuffer. ++@end deffn ++ ++@defvar list-buffers-directory ++This buffer-local variable specifies a string to display in a buffer ++listing where the visited file name would go, for buffers that don't ++have a visited file name. Dired buffers use this variable. ++@end defvar ++ ++@node Buffer Modification ++@section Buffer Modification ++@cindex buffer modification ++@cindex modification flag (of buffer) ++ ++ Emacs keeps a flag called the @dfn{modified flag} for each buffer, to ++record whether you have changed the text of the buffer. This flag is ++set to @code{t} whenever you alter the contents of the buffer, and ++cleared to @code{nil} when you save it. Thus, the flag shows whether ++there are unsaved changes. The flag value is normally shown in the mode ++line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving ++Buffers}) and auto-saving (@pxref{Auto-Saving}). ++ ++ Some Lisp programs set the flag explicitly. For example, the function ++@code{set-visited-file-name} sets the flag to @code{t}, because the text ++does not match the newly-visited file, even if it is unchanged from the ++file formerly visited. ++ ++ The functions that modify the contents of buffers are described in ++@ref{Text}. ++ ++@defun buffer-modified-p &optional buffer ++This function returns @code{t} if the buffer @var{buffer} has been modified ++since it was last read in from a file or saved, or @code{nil} ++otherwise. If @var{buffer} is not supplied, the current buffer ++is tested. ++@end defun ++ ++@defun set-buffer-modified-p flag ++This function marks the current buffer as modified if @var{flag} is ++non-@code{nil}, or as unmodified if the flag is @code{nil}. ++ ++Another effect of calling this function is to cause unconditional ++redisplay of the mode line for the current buffer. In fact, the ++function @code{force-mode-line-update} works by doing this: ++ ++@example ++@group ++(set-buffer-modified-p (buffer-modified-p)) ++@end group ++@end example ++@end defun ++ ++@defun restore-buffer-modified-p flag ++Like @code{set-buffer-modified-p}, but does not force redisplay ++of mode lines. ++@end defun ++ ++@deffn Command not-modified &optional arg ++This command marks the current buffer as unmodified, and not needing ++to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as ++modified, so that it will be saved at the next suitable occasion. ++Interactively, @var{arg} is the prefix argument. ++ ++Don't use this function in programs, since it prints a message in the ++echo area; use @code{set-buffer-modified-p} (above) instead. ++@end deffn ++ ++@defun buffer-modified-tick &optional buffer ++This function returns @var{buffer}'s modification-count. This is a ++counter that increments every time the buffer is modified. If ++@var{buffer} is @code{nil} (or omitted), the current buffer is used. ++The counter can wrap around occasionally. ++@end defun ++ ++@defun buffer-chars-modified-tick &optional buffer ++This function returns @var{buffer}'s character-change modification-count. ++Changes to text properties leave this counter unchanged; however, each ++time text is inserted or removed from the buffer, the counter is reset ++to the value that would be returned by @code{buffer-modified-tick}. ++By comparing the values returned by two @code{buffer-chars-modified-tick} ++calls, you can tell whether a character change occurred in that buffer ++in between the calls. If @var{buffer} is @code{nil} (or omitted), the ++current buffer is used. ++@end defun ++ ++@node Modification Time ++@comment node-name, next, previous, up ++@section Buffer Modification Time ++@cindex comparing file modification time ++@cindex modification time of buffer ++ ++ Suppose that you visit a file and make changes in its buffer, and ++meanwhile the file itself is changed on disk. At this point, saving the ++buffer would overwrite the changes in the file. Occasionally this may ++be what you want, but usually it would lose valuable information. Emacs ++therefore checks the file's modification time using the functions ++described below before saving the file. (@xref{File Attributes}, ++for how to examine a file's modification time.) ++ ++@defun verify-visited-file-modtime buffer ++This function compares what @var{buffer} has recorded for the ++modification time of its visited file against the actual modification ++time of the file as recorded by the operating system. The two should be ++the same unless some other process has written the file since Emacs ++visited or saved it. ++ ++The function returns @code{t} if the last actual modification time and ++Emacs's recorded modification time are the same, @code{nil} otherwise. ++It also returns @code{t} if the buffer has no recorded last ++modification time, that is if @code{visited-file-modtime} would return ++zero. ++ ++It always returns @code{t} for buffers that are not visiting a file, ++even if @code{visited-file-modtime} returns a non-zero value. For ++instance, it always returns @code{t} for dired buffers. It returns ++@code{t} for buffers that are visiting a file that does not exist and ++never existed, but @code{nil} for file-visiting buffers whose file has ++been deleted. ++@end defun ++ ++@defun clear-visited-file-modtime ++This function clears out the record of the last modification time of ++the file being visited by the current buffer. As a result, the next ++attempt to save this buffer will not complain of a discrepancy in ++file modification times. ++ ++This function is called in @code{set-visited-file-name} and other ++exceptional places where the usual test to avoid overwriting a changed ++file should not be done. ++@end defun ++ ++@c Emacs 19 feature ++@defun visited-file-modtime ++This function returns the current buffer's recorded last file ++modification time, as a list of the form @code{(@var{high} @var{low})}. ++(This is the same format that @code{file-attributes} uses to return ++time values; see @ref{File Attributes}.) ++ ++If the buffer has no recorded last modification time, this function ++returns zero. This case occurs, for instance, if the buffer is not ++visiting a file or if the time has been explicitly cleared by ++@code{clear-visited-file-modtime}. Note, however, that ++@code{visited-file-modtime} returns a list for some non-file buffers ++too. For instance, in a Dired buffer listing a directory, it returns ++the last modification time of that directory, as recorded by Dired. ++ ++For a new buffer visiting a not yet existing file, @var{high} is ++@minus{}1 and @var{low} is 65535, that is, ++@ifnottex ++@w{2**16 - 1.} ++@end ifnottex ++@tex ++@math{2^{16}-1}. ++@end tex ++@end defun ++ ++@c Emacs 19 feature ++@defun set-visited-file-modtime &optional time ++This function updates the buffer's record of the last modification time ++of the visited file, to the value specified by @var{time} if @var{time} ++is not @code{nil}, and otherwise to the last modification time of the ++visited file. ++ ++If @var{time} is neither @code{nil} nor zero, it should have the form ++@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in ++either case containing two integers, each of which holds 16 bits of the ++time. ++ ++This function is useful if the buffer was not read from the file ++normally, or if the file itself has been changed for some known benign ++reason. ++@end defun ++ ++@defun ask-user-about-supersession-threat filename ++This function is used to ask a user how to proceed after an attempt to ++modify an buffer visiting file @var{filename} when the file is newer ++than the buffer text. Emacs detects this because the modification ++time of the file on disk is newer than the last save-time of the ++buffer. This means some other program has probably altered the file. ++ ++@kindex file-supersession ++Depending on the user's answer, the function may return normally, in ++which case the modification of the buffer proceeds, or it may signal a ++@code{file-supersession} error with data @code{(@var{filename})}, in which ++case the proposed buffer modification is not allowed. ++ ++This function is called automatically by Emacs on the proper ++occasions. It exists so you can customize Emacs by redefining it. ++See the file @file{userlock.el} for the standard definition. ++ ++See also the file locking mechanism in @ref{File Locks}. ++@end defun ++ ++@node Read Only Buffers ++@section Read-Only Buffers ++@cindex read-only buffer ++@cindex buffer, read-only ++ ++ If a buffer is @dfn{read-only}, then you cannot change its contents, ++although you may change your view of the contents by scrolling and ++narrowing. ++ ++ Read-only buffers are used in two kinds of situations: ++ ++@itemize @bullet ++@item ++A buffer visiting a write-protected file is normally read-only. ++ ++Here, the purpose is to inform the user that editing the buffer with the ++aim of saving it in the file may be futile or undesirable. The user who ++wants to change the buffer text despite this can do so after clearing ++the read-only flag with @kbd{C-x C-q}. ++ ++@item ++Modes such as Dired and Rmail make buffers read-only when altering the ++contents with the usual editing commands would probably be a mistake. ++ ++The special commands of these modes bind @code{buffer-read-only} to ++@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to ++@code{t} around the places where they themselves change the text. ++@end itemize ++ ++@defvar buffer-read-only ++This buffer-local variable specifies whether the buffer is read-only. ++The buffer is read-only if this variable is non-@code{nil}. ++@end defvar ++ ++@defvar inhibit-read-only ++If this variable is non-@code{nil}, then read-only buffers and, ++depending on the actual value, some or all read-only characters may be ++modified. Read-only characters in a buffer are those that have ++non-@code{nil} @code{read-only} properties (either text properties or ++overlay properties). @xref{Special Properties}, for more information ++about text properties. @xref{Overlays}, for more information about ++overlays and their properties. ++ ++If @code{inhibit-read-only} is @code{t}, all @code{read-only} character ++properties have no effect. If @code{inhibit-read-only} is a list, then ++@code{read-only} character properties have no effect if they are members ++of the list (comparison is done with @code{eq}). ++@end defvar ++ ++@deffn Command toggle-read-only &optional arg ++This command toggles whether the current buffer is read-only. It is ++intended for interactive use; do not use it in programs. At any given ++point in a program, you should know whether you want the read-only flag ++on or off; so you can set @code{buffer-read-only} explicitly to the ++proper value, @code{t} or @code{nil}. ++ ++If @var{arg} is non-@code{nil}, it should be a raw prefix argument. ++@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if ++the numeric value of that prefix argument is positive and to ++@code{nil} otherwise. @xref{Prefix Command Arguments}. ++@end deffn ++ ++@defun barf-if-buffer-read-only ++This function signals a @code{buffer-read-only} error if the current ++buffer is read-only. @xref{Using Interactive}, for another way to ++signal an error if the current buffer is read-only. ++@end defun ++ ++@node The Buffer List ++@section The Buffer List ++@cindex buffer list ++ ++ The @dfn{buffer list} is a list of all live buffers. The order of the ++buffers in this list is based primarily on how recently each buffer has ++been displayed in a window. Several functions, notably ++@code{other-buffer}, use this ordering. A buffer list displayed for the ++user also follows this order. ++ ++ Creating a buffer adds it to the end of the buffer list, and killing a ++buffer removes it from that list. A buffer moves to the front of this ++list whenever it is chosen for display in a window (@pxref{Displaying ++Buffers}) or a window displaying it is selected (@pxref{Selecting ++Windows}). A buffer moves to the end of the list when it is buried (see ++@code{bury-buffer}, below). There are no functions available to the ++Lisp programmer which directly manipulate the buffer list. ++ ++ In addition to the fundamental buffer list just described, Emacs ++maintains a local buffer list for each frame, in which the buffers that ++have been displayed (or had their windows selected) in that frame come ++first. (This order is recorded in the frame's @code{buffer-list} frame ++parameter; see @ref{Buffer Parameters}.) Buffers never displayed in ++that frame come afterward, ordered according to the fundamental buffer ++list. ++ ++@defun buffer-list &optional frame ++This function returns the buffer list, including all buffers, even those ++whose names begin with a space. The elements are actual buffers, not ++their names. ++ ++If @var{frame} is a frame, this returns @var{frame}'s local buffer list. ++If @var{frame} is @code{nil} or omitted, the fundamental buffer list is ++used: the buffers appear in order of most recent display or selection, ++regardless of which frames they were displayed on. ++ ++@example ++@group ++(buffer-list) ++ @result{} (# ++ # # ++ # #) ++@end group ++ ++@group ++;; @r{Note that the name of the minibuffer} ++;; @r{begins with a space!} ++(mapcar (function buffer-name) (buffer-list)) ++ @result{} ("buffers.texi" " *Minibuf-1*" ++ "buffer.c" "*Help*" "TAGS") ++@end group ++@end example ++@end defun ++ ++ The list returned by @code{buffer-list} is constructed specifically; ++it is not an internal Emacs data structure, and modifying it has no ++effect on the order of buffers. If you want to change the order of ++buffers in the fundamental buffer list, here is an easy way: ++ ++@example ++(defun reorder-buffer-list (new-list) ++ (while new-list ++ (bury-buffer (car new-list)) ++ (setq new-list (cdr new-list)))) ++@end example ++ ++ With this method, you can specify any order for the list, but there is ++no danger of losing a buffer or adding something that is not a valid ++live buffer. ++ ++ To change the order or value of a specific frame's buffer list, set ++that frame's @code{buffer-list} parameter with ++@code{modify-frame-parameters} (@pxref{Parameter Access}). ++ ++@defun other-buffer &optional buffer visible-ok frame ++This function returns the first buffer in the buffer list other than ++@var{buffer}. Usually, this is the buffer appearing in the most ++recently selected window (in frame @var{frame} or else the selected ++frame, @pxref{Input Focus}), aside from @var{buffer}. Buffers whose ++names start with a space are not considered at all. ++ ++If @var{buffer} is not supplied (or if it is not a live buffer), then ++@code{other-buffer} returns the first buffer in the selected frame's ++local buffer list. (If @var{frame} is non-@code{nil}, it returns the ++first buffer in @var{frame}'s local buffer list instead.) ++ ++If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, ++then @code{other-buffer} uses that predicate to decide which buffers to ++consider. It calls the predicate once for each buffer, and if the value ++is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. ++ ++@c Emacs 19 feature ++If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning ++a buffer visible in any window on any visible frame, except as a last ++resort. If @var{visible-ok} is non-@code{nil}, then it does not matter ++whether a buffer is displayed somewhere or not. ++ ++If no suitable buffer exists, the buffer @samp{*scratch*} is returned ++(and created, if necessary). ++@end defun ++ ++@defun last-buffer &optional buffer visible-ok frame ++This function returns the last buffer in @var{frame}'s buffer list other ++than @var{BUFFER}. If @var{frame} is omitted or @code{nil}, it uses the ++selected frame's buffer list. ++ ++The argument @var{visible-ok} is handled as with @code{other-buffer}, ++see above. If no suitable buffer can be found, the buffer ++@samp{*scratch*} is returned. ++@end defun ++ ++@deffn Command bury-buffer &optional buffer-or-name ++This command puts @var{buffer-or-name} at the end of the buffer list, ++without changing the order of any of the other buffers on the list. ++This buffer therefore becomes the least desirable candidate for ++@code{other-buffer} to return. The argument can be either a buffer ++itself or the name of one. ++ ++@code{bury-buffer} operates on each frame's @code{buffer-list} parameter ++as well as the fundamental buffer list; therefore, the buffer that you ++bury will come last in the value of @code{(buffer-list @var{frame})} and ++in the value of @code{(buffer-list)}. ++ ++If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the ++current buffer. In addition, if the buffer is displayed in the selected ++window, this switches to some other buffer (obtained using ++@code{other-buffer}) in the selected window. @xref{Displaying Buffers}. ++But if the selected window is dedicated to its buffer, it deletes that ++window if there are other windows left on its frame. Otherwise, if the ++selected window is the only window on its frame, it iconifies that ++frame. If @var{buffer-or-name} is displayed in some other window, it ++remains displayed there. ++ ++To replace a buffer in all the windows that display it, use ++@code{replace-buffer-in-windows}. @xref{Buffers and Windows}. ++@end deffn ++ ++@deffn Command unbury-buffer ++This command switches to the last buffer in the local buffer list of the ++selected frame. More precisely, it calls the function ++@code{switch-to-buffer} (@pxref{Displaying Buffers}), to display the ++buffer returned by @code{last-buffer}, see above, in the selected ++window. ++@end deffn ++ ++ ++@node Creating Buffers ++@section Creating Buffers ++@cindex creating buffers ++@cindex buffers, creating ++ ++ This section describes the two primitives for creating buffers. ++@code{get-buffer-create} creates a buffer if it finds no existing buffer ++with the specified name; @code{generate-new-buffer} always creates a new ++buffer and gives it a unique name. ++ ++ Other functions you can use to create buffers include ++@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and ++@code{create-file-buffer} (@pxref{Visiting Files}). Starting a ++subprocess can also create a buffer (@pxref{Processes}). ++ ++@defun get-buffer-create buffer-or-name ++This function returns a buffer named @var{buffer-or-name}. The buffer ++returned does not become the current buffer---this function does not ++change which buffer is current. ++ ++@var{buffer-or-name} must be either a string or an existing buffer. If ++it is a string and a live buffer with that name already exists, ++@code{get-buffer-create} returns that buffer. If no such buffer exists, ++it creates a new buffer. If @var{buffer-or-name} is a buffer instead of ++a string, it is returned as given, even if it is dead. ++ ++@example ++@group ++(get-buffer-create "foo") ++ @result{} # ++@end group ++@end example ++ ++The major mode for a newly created buffer is set to Fundamental mode. ++(The variable @code{default-major-mode} is handled at a higher level; ++see @ref{Auto Major Mode}.) If the name begins with a space, the ++buffer initially disables undo information recording (@pxref{Undo}). ++@end defun ++ ++@defun generate-new-buffer name ++This function returns a newly created, empty buffer, but does not make ++it current. If there is no buffer named @var{name}, then that is the ++name of the new buffer. If that name is in use, this function adds ++suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an ++integer. It tries successive integers starting with 2 until it finds an ++available name. ++ ++An error is signaled if @var{name} is not a string. ++ ++@example ++@group ++(generate-new-buffer "bar") ++ @result{} # ++@end group ++@group ++(generate-new-buffer "bar") ++ @result{} #> ++@end group ++@group ++(generate-new-buffer "bar") ++ @result{} #> ++@end group ++@end example ++ ++The major mode for the new buffer is set to Fundamental mode. The ++variable @code{default-major-mode} is handled at a higher level. ++@xref{Auto Major Mode}. ++ ++See the related function @code{generate-new-buffer-name} in @ref{Buffer ++Names}. ++@end defun ++ ++@node Killing Buffers ++@section Killing Buffers ++@cindex killing buffers ++@cindex buffers, killing ++ ++ @dfn{Killing a buffer} makes its name unknown to Emacs and makes the ++memory space it occupied available for other use. ++ ++ The buffer object for the buffer that has been killed remains in ++existence as long as anything refers to it, but it is specially marked ++so that you cannot make it current or display it. Killed buffers retain ++their identity, however; if you kill two distinct buffers, they remain ++distinct according to @code{eq} although both are dead. ++ ++ If you kill a buffer that is current or displayed in a window, Emacs ++automatically selects or displays some other buffer instead. This means ++that killing a buffer can in general change the current buffer. ++Therefore, when you kill a buffer, you should also take the precautions ++associated with changing the current buffer (unless you happen to know ++that the buffer being killed isn't current). @xref{Current Buffer}. ++ ++ If you kill a buffer that is the base buffer of one or more indirect ++buffers, the indirect buffers are automatically killed as well. ++ ++ The @code{buffer-name} of a killed buffer is @code{nil}. You can use ++this feature to test whether a buffer has been killed: ++ ++@example ++@group ++(defun buffer-killed-p (buffer) ++ "Return t if BUFFER is killed." ++ (not (buffer-name buffer))) ++@end group ++@end example ++ ++@deffn Command kill-buffer &optional buffer-or-name ++This function kills the buffer @var{buffer-or-name}, freeing all its ++memory for other uses or to be returned to the operating system. If ++@var{buffer-or-name} is @code{nil} or omitted, it kills the current ++buffer. ++ ++Any processes that have this buffer as the @code{process-buffer} are ++sent the @code{SIGHUP} signal, which normally causes them to terminate. ++(The basic meaning of @code{SIGHUP} is that a dialup line has been ++disconnected.) @xref{Signals to Processes}. ++ ++If the buffer is visiting a file and contains unsaved changes, ++@code{kill-buffer} asks the user to confirm before the buffer is killed. ++It does this even if not called interactively. To prevent the request ++for confirmation, clear the modified flag before calling ++@code{kill-buffer}. @xref{Buffer Modification}. ++ ++This function calls @code{replace-buffer-in-windows} for cleaning up ++all windows currently displaying the buffer to be killed. ++ ++Killing a buffer that is already dead has no effect. ++ ++This function returns @code{t} if it actually killed the buffer. It ++returns @code{nil} if the user refuses to confirm or if ++@var{buffer-or-name} was already dead. ++ ++@smallexample ++(kill-buffer "foo.unchanged") ++ @result{} t ++(kill-buffer "foo.changed") ++ ++---------- Buffer: Minibuffer ---------- ++Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} ++---------- Buffer: Minibuffer ---------- ++ ++ @result{} t ++@end smallexample ++@end deffn ++ ++@defvar kill-buffer-query-functions ++After confirming unsaved changes, @code{kill-buffer} calls the functions ++in the list @code{kill-buffer-query-functions}, in order of appearance, ++with no arguments. The buffer being killed is the current buffer when ++they are called. The idea of this feature is that these functions will ++ask for confirmation from the user. If any of them returns @code{nil}, ++@code{kill-buffer} spares the buffer's life. ++@end defvar ++ ++@defvar kill-buffer-hook ++This is a normal hook run by @code{kill-buffer} after asking all the ++questions it is going to ask, just before actually killing the buffer. ++The buffer to be killed is current when the hook functions run. ++@xref{Hooks}. This variable is a permanent local, so its local binding ++is not cleared by changing major modes. ++@end defvar ++ ++@defopt buffer-offer-save ++This variable, if non-@code{nil} in a particular buffer, tells ++@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the ++second optional argument to that function is @code{t}) to offer to ++save that buffer, just as they offer to save file-visiting buffers. ++@xref{Definition of save-some-buffers}. The variable ++@code{buffer-offer-save} automatically becomes buffer-local when set ++for any reason. @xref{Buffer-Local Variables}. ++@end defopt ++ ++@defvar buffer-save-without-query ++This variable, if non-@code{nil} in a particular buffer, tells ++@code{save-buffers-kill-emacs} and @code{save-some-buffers} to save ++this buffer (if it's modified) without asking the user. The variable ++automatically becomes buffer-local when set for any reason. ++@end defvar ++ ++@defun buffer-live-p object ++This function returns @code{t} if @var{object} is a buffer which has ++not been killed, @code{nil} otherwise. ++@end defun ++ ++@node Indirect Buffers ++@section Indirect Buffers ++@cindex indirect buffers ++@cindex base buffer ++ ++ An @dfn{indirect buffer} shares the text of some other buffer, which ++is called the @dfn{base buffer} of the indirect buffer. In some ways it ++is the analogue, for buffers, of a symbolic link among files. The base ++buffer may not itself be an indirect buffer. ++ ++ The text of the indirect buffer is always identical to the text of its ++base buffer; changes made by editing either one are visible immediately ++in the other. This includes the text properties as well as the characters ++themselves. ++ ++ In all other respects, the indirect buffer and its base buffer are ++completely separate. They have different names, independent values of ++point, independent narrowing, independent markers and overlays (though ++inserting or deleting text in either buffer relocates the markers and ++overlays for both), independent major modes, and independent ++buffer-local variable bindings. ++ ++ An indirect buffer cannot visit a file, but its base buffer can. If ++you try to save the indirect buffer, that actually saves the base ++buffer. ++ ++ Killing an indirect buffer has no effect on its base buffer. Killing ++the base buffer effectively kills the indirect buffer in that it cannot ++ever again be the current buffer. ++ ++@deffn Command make-indirect-buffer base-buffer name &optional clone ++This creates and returns an indirect buffer named @var{name} whose ++base buffer is @var{base-buffer}. The argument @var{base-buffer} may ++be a live buffer or the name (a string) of an existing buffer. If ++@var{name} is the name of an existing buffer, an error is signaled. ++ ++If @var{clone} is non-@code{nil}, then the indirect buffer originally ++shares the ``state'' of @var{base-buffer} such as major mode, minor ++modes, buffer local variables and so on. If @var{clone} is omitted ++or @code{nil} the indirect buffer's state is set to the default state ++for new buffers. ++ ++If @var{base-buffer} is an indirect buffer, its base buffer is used as ++the base for the new buffer. If, in addition, @var{clone} is ++non-@code{nil}, the initial state is copied from the actual base ++buffer, not from @var{base-buffer}. ++@end deffn ++ ++@deffn clone-indirect-buffer newname display-flag &optional norecord ++This function creates and returns a new indirect buffer that shares ++the current buffer's base buffer and copies the rest of the current ++buffer's attributes. (If the current buffer is not indirect, it is ++used as the base buffer.) ++ ++If @var{display-flag} is non-@code{nil}, that means to display the new ++buffer by calling @code{pop-to-buffer}. If @var{norecord} is ++non-@code{nil}, that means not to put the new buffer to the front of ++the buffer list. ++@end deffn ++ ++@defun buffer-base-buffer &optional buffer ++This function returns the base buffer of @var{buffer}, which defaults ++to the current buffer. If @var{buffer} is not indirect, the value is ++@code{nil}. Otherwise, the value is another buffer, which is never an ++indirect buffer. ++@end defun ++ ++@node Swapping Text ++@section Swapping Text Between Two Buffers ++@cindex swap text between buffers ++@cindex virtual buffers ++ ++ Specialized modes sometimes need to let the user access from the ++same buffer several vastly different types of text. For example, you ++may need to display a summary of the buffer text, in addition to ++letting the user access the text itself. ++ ++ This could be implemented with multiple buffers (kept in sync when ++the user edits the text), or with narrowing (@pxref{Narrowing}). But ++these alternatives might sometimes become tedious or prohibitively ++expensive, especially if each type of text requires expensive ++buffer-global operations in order to provide correct display and ++editing commands. ++ ++ Emacs provides another facility for such modes: you can quickly swap ++buffer text between two buffers with @code{buffer-swap-text}. This ++function is very fast because it doesn't move any text, it only ++changes the internal data structures of the buffer object to point to ++a different chunk of text. Using it, you can pretend that a group of ++two or more buffers are actually a single virtual buffer that holds ++the contents of all the individual buffers together. ++ ++@defun buffer-swap-text buffer ++This function swaps text between the current buffer and its argument ++@var{buffer}. It signals an error if one of the two buffers is an ++indirect buffer (@pxref{Indirect Buffers}) or is a base buffer of an ++indirect buffer. ++ ++All the buffer properties that are related to the buffer text are ++swapped as well: the positions of point and mark, all the markers, the ++overlays, the text properties, the undo list, the value of the ++@code{enable-multibyte-characters} flag (@pxref{Text Representations, ++enable-multibyte-characters}), etc. ++@end defun ++ ++@node Buffer Gap ++@section The Buffer Gap ++ ++ Emacs buffers are implemented using an invisible @dfn{gap} to make ++insertion and deletion faster. Insertion works by filling in part of ++the gap, and deletion adds to the gap. Of course, this means that the ++gap must first be moved to the locus of the insertion or deletion. ++Emacs moves the gap only when you try to insert or delete. This is why ++your first editing command in one part of a large buffer, after ++previously editing in another far-away part, sometimes involves a ++noticeable delay. ++ ++ This mechanism works invisibly, and Lisp code should never be affected ++by the gap's current location, but these functions are available for ++getting information about the gap status. ++ ++@defun gap-position ++This function returns the current gap position in the current buffer. ++@end defun ++ ++@defun gap-size ++This function returns the current gap size of the current buffer. ++@end defun ++ ++@ignore ++ arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c ++@end ignore +diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi +new file mode 100644 +index 0000000..147fdf2 +--- /dev/null ++++ b/doc/lispref/commands.texi +@@ -0,0 +1,3362 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/commands ++@node Command Loop, Keymaps, Minibuffers, Top ++@chapter Command Loop ++@cindex editor command loop ++@cindex command loop ++ ++ When you run Emacs, it enters the @dfn{editor command loop} almost ++immediately. This loop reads key sequences, executes their definitions, ++and displays the results. In this chapter, we describe how these things ++are done, and the subroutines that allow Lisp programs to do them. ++ ++@menu ++* Command Overview:: How the command loop reads commands. ++* Defining Commands:: Specifying how a function should read arguments. ++* Interactive Call:: Calling a command, so that it will read arguments. ++* Distinguish Interactive:: Making a command distinguish interactive calls. ++* Command Loop Info:: Variables set by the command loop for you to examine. ++* Adjusting Point:: Adjustment of point after a command. ++* Input Events:: What input looks like when you read it. ++* Reading Input:: How to read input events from the keyboard or mouse. ++* Special Events:: Events processed immediately and individually. ++* Waiting:: Waiting for user input or elapsed time. ++* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. ++* Prefix Command Arguments:: How the commands to set prefix args work. ++* Recursive Editing:: Entering a recursive edit, ++ and why you usually shouldn't. ++* Disabling Commands:: How the command loop handles disabled commands. ++* Command History:: How the command history is set up, and how accessed. ++* Keyboard Macros:: How keyboard macros are implemented. ++@end menu ++ ++@node Command Overview ++@section Command Loop Overview ++ ++ The first thing the command loop must do is read a key sequence, which ++is a sequence of events that translates into a command. It does this by ++calling the function @code{read-key-sequence}. Your Lisp code can also ++call this function (@pxref{Key Sequence Input}). Lisp programs can also ++do input at a lower level with @code{read-event} (@pxref{Reading One ++Event}) or discard pending input with @code{discard-input} ++(@pxref{Event Input Misc}). ++ ++ The key sequence is translated into a command through the currently ++active keymaps. @xref{Key Lookup}, for information on how this is done. ++The result should be a keyboard macro or an interactively callable ++function. If the key is @kbd{M-x}, then it reads the name of another ++command, which it then calls. This is done by the command ++@code{execute-extended-command} (@pxref{Interactive Call}). ++ ++ To execute a command requires first reading the arguments for it. ++This is done by calling @code{command-execute} (@pxref{Interactive ++Call}). For commands written in Lisp, the @code{interactive} ++specification says how to read the arguments. This may use the prefix ++argument (@pxref{Prefix Command Arguments}) or may read with prompting ++in the minibuffer (@pxref{Minibuffers}). For example, the command ++@code{find-file} has an @code{interactive} specification which says to ++read a file name using the minibuffer. The command's function body does ++not use the minibuffer; if you call this command from Lisp code as a ++function, you must supply the file name string as an ordinary Lisp ++function argument. ++ ++ If the command is a string or vector (i.e., a keyboard macro) then ++@code{execute-kbd-macro} is used to execute it. You can call this ++function yourself (@pxref{Keyboard Macros}). ++ ++ To terminate the execution of a running command, type @kbd{C-g}. This ++character causes @dfn{quitting} (@pxref{Quitting}). ++ ++@defvar pre-command-hook ++The editor command loop runs this normal hook before each command. At ++that time, @code{this-command} contains the command that is about to ++run, and @code{last-command} describes the previous command. ++@xref{Command Loop Info}. ++@end defvar ++ ++@defvar post-command-hook ++The editor command loop runs this normal hook after each command ++(including commands terminated prematurely by quitting or by errors), ++and also when the command loop is first entered. At that time, ++@code{this-command} refers to the command that just ran, and ++@code{last-command} refers to the command before that. ++@end defvar ++ ++ Quitting is suppressed while running @code{pre-command-hook} and ++@code{post-command-hook}. If an error happens while executing one of ++these hooks, it terminates execution of the hook, and clears the hook ++variable to @code{nil} so as to prevent an infinite loop of errors. ++ ++ A request coming into the Emacs server (@pxref{Emacs Server,,, ++emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard ++command does. ++ ++@node Defining Commands ++@section Defining Commands ++@cindex defining commands ++@cindex commands, defining ++@cindex functions, making them interactive ++@cindex interactive function ++ ++ The special form @code{interactive} turns a Lisp function into a ++command. The @code{interactive} form must be located at top-level in ++the function body (usually as the first form in the body), or in the ++@code{interactive-form} property of the function symbol. When the ++@code{interactive} form is located in the function body, it does ++nothing when actually executed. Its presence serves as a flag, which ++tells the Emacs command loop that the function can be called ++interactively. The argument of the @code{interactive} form controls ++the reading of arguments for an interactive call. ++ ++@menu ++* Using Interactive:: General rules for @code{interactive}. ++* Interactive Codes:: The standard letter-codes for reading arguments ++ in various ways. ++* Interactive Examples:: Examples of how to read interactive arguments. ++@end menu ++ ++@node Using Interactive ++@subsection Using @code{interactive} ++@cindex arguments, interactive entry ++ ++ This section describes how to write the @code{interactive} form that ++makes a Lisp function an interactively-callable command, and how to ++examine a command's @code{interactive} form. ++ ++@defspec interactive arg-descriptor ++This special form declares that a function is a command, and that it ++may therefore be called interactively (via @kbd{M-x} or by entering a ++key sequence bound to it). The argument @var{arg-descriptor} declares ++how to compute the arguments to the command when the command is called ++interactively. ++ ++A command may be called from Lisp programs like any other function, but ++then the caller supplies the arguments and @var{arg-descriptor} has no ++effect. ++ ++@cindex @code{interactive-form}, function property ++The @code{interactive} form must be located at top-level in the ++function body, or in the function symbol's @code{interactive-form} ++property (@pxref{Symbol Plists}). It has its effect because the ++command loop looks for it before calling the function ++(@pxref{Interactive Call}). Once the function is called, all its body ++forms are executed; at this time, if the @code{interactive} form ++occurs within the body, the form simply returns @code{nil} without ++even evaluating its argument. ++ ++By convention, you should put the @code{interactive} form in the ++function body, as the first top-level form. If there is an ++@code{interactive} form in both the @code{interactive-form} symbol ++property and the function body, the former takes precedence. The ++@code{interactive-form} symbol property can be used to add an ++interactive form to an existing function, or change how its arguments ++are processed interactively, without redefining the function. ++@end defspec ++ ++There are three possibilities for the argument @var{arg-descriptor}: ++ ++@itemize @bullet ++@item ++It may be omitted or @code{nil}; then the command is called with no ++arguments. This leads quickly to an error if the command requires one ++or more arguments. ++ ++@item ++It may be a string; its contents are a sequence of elements separated ++by newlines, one for each parameter@footnote{Some elements actually ++supply two parameters.}. Each element consists of a code character ++(@pxref{Interactive Codes}) optionally followed by a prompt (which ++some code characters use and some ignore). Here is an example: ++ ++@smallexample ++(interactive "P\nbFrobnicate buffer: ") ++@end smallexample ++ ++@noindent ++The code letter @samp{P} sets the command's first argument to the raw ++command prefix (@pxref{Prefix Command Arguments}). @samp{bFrobnicate ++buffer: } prompts the user with @samp{Frobnicate buffer: } to enter ++the name of an existing buffer, which becomes the second and final ++argument. ++ ++@c Emacs 19 feature ++The prompt string can use @samp{%} to include previous argument values ++(starting with the first argument) in the prompt. This is done using ++@code{format} (@pxref{Formatting Strings}). For example, here is how ++you could read the name of an existing buffer followed by a new name to ++give to that buffer: ++ ++@smallexample ++@group ++(interactive "bBuffer to rename: \nsRename buffer %s to: ") ++@end group ++@end smallexample ++ ++@cindex @samp{*} in @code{interactive} ++@cindex read-only buffers in interactive ++If @samp{*} appears at the beginning of the string, then an error is ++signaled if the buffer is read-only. ++ ++@cindex @samp{@@} in @code{interactive} ++@c Emacs 19 feature ++If @samp{@@} appears at the beginning of the string, and if the key ++sequence used to invoke the command includes any mouse events, then ++the window associated with the first of those events is selected ++before the command is run. ++ ++@cindex @samp{^} in @code{interactive} ++@cindex shift-selection, and @code{interactive} spec ++If @samp{^} appears at the beginning of the string, and if the command ++was invoked through @dfn{shift-translation}, set the mark and activate ++the region temporarily, or extend an already active region, before the ++command is run. If the command was invoked without shift-translation, ++and the region is temporarily active, deactivate the region before the ++command is run. Shift-translation is controlled on the user level by ++@code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU ++Emacs Manual}. ++ ++You can use @samp{*}, @samp{@@}, and @code{^} together; the order does ++not matter. Actual reading of arguments is controlled by the rest of ++the prompt string (starting with the first character that is not ++@samp{*}, @samp{@@}, or @samp{^}). ++ ++@item ++It may be a Lisp expression that is not a string; then it should be a ++form that is evaluated to get a list of arguments to pass to the ++command. Usually this form will call various functions to read input ++from the user, most often through the minibuffer (@pxref{Minibuffers}) ++or directly from the keyboard (@pxref{Reading Input}). ++ ++Providing point or the mark as an argument value is also common, but ++if you do this @emph{and} read input (whether using the minibuffer or ++not), be sure to get the integer values of point or the mark after ++reading. The current buffer may be receiving subprocess output; if ++subprocess output arrives while the command is waiting for input, it ++could relocate point and the mark. ++ ++Here's an example of what @emph{not} to do: ++ ++@smallexample ++(interactive ++ (list (region-beginning) (region-end) ++ (read-string "Foo: " nil 'my-history))) ++@end smallexample ++ ++@noindent ++Here's how to avoid the problem, by examining point and the mark after ++reading the keyboard input: ++ ++@smallexample ++(interactive ++ (let ((string (read-string "Foo: " nil 'my-history))) ++ (list (region-beginning) (region-end) string))) ++@end smallexample ++ ++@strong{Warning:} the argument values should not include any data ++types that can't be printed and then read. Some facilities save ++@code{command-history} in a file to be read in the subsequent ++sessions; if a command's arguments contain a data type that prints ++using @samp{#<@dots{}>} syntax, those facilities won't work. ++ ++There are, however, a few exceptions: it is ok to use a limited set of ++expressions such as @code{(point)}, @code{(mark)}, ++@code{(region-beginning)}, and @code{(region-end)}, because Emacs ++recognizes them specially and puts the expression (rather than its ++value) into the command history. To see whether the expression you ++wrote is one of these exceptions, run the command, then examine ++@code{(car command-history)}. ++@end itemize ++ ++@cindex examining the @code{interactive} form ++@defun interactive-form function ++This function returns the @code{interactive} form of @var{function}. ++If @var{function} is an interactively callable function ++(@pxref{Interactive Call}), the value is the command's ++@code{interactive} form @code{(interactive @var{spec})}, which ++specifies how to compute its arguments. Otherwise, the value is ++@code{nil}. If @var{function} is a symbol, its function definition is ++used. ++@end defun ++ ++@node Interactive Codes ++@comment node-name, next, previous, up ++@subsection Code Characters for @code{interactive} ++@cindex interactive code description ++@cindex description for interactive codes ++@cindex codes, interactive, description of ++@cindex characters for interactive codes ++ ++ The code character descriptions below contain a number of key words, ++defined here as follows: ++ ++@table @b ++@item Completion ++@cindex interactive completion ++Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name ++completion because the argument is read using @code{completing-read} ++(@pxref{Completion}). @kbd{?} displays a list of possible completions. ++ ++@item Existing ++Require the name of an existing object. An invalid name is not ++accepted; the commands to exit the minibuffer do not exit if the current ++input is not valid. ++ ++@item Default ++@cindex default argument string ++A default value of some sort is used if the user enters no text in the ++minibuffer. The default depends on the code character. ++ ++@item No I/O ++This code letter computes an argument without reading any input. ++Therefore, it does not use a prompt string, and any prompt string you ++supply is ignored. ++ ++Even though the code letter doesn't use a prompt string, you must follow ++it with a newline if it is not the last code character in the string. ++ ++@item Prompt ++A prompt immediately follows the code character. The prompt ends either ++with the end of the string or with a newline. ++ ++@item Special ++This code character is meaningful only at the beginning of the ++interactive string, and it does not look for a prompt or a newline. ++It is a single, isolated character. ++@end table ++ ++@cindex reading interactive arguments ++ Here are the code character descriptions for use with @code{interactive}: ++ ++@table @samp ++@item * ++Signal an error if the current buffer is read-only. Special. ++ ++@item @@ ++Select the window mentioned in the first mouse event in the key ++sequence that invoked this command. Special. ++ ++@item ^ ++If the command was invoked through shift-translation, set the mark and ++activate the region temporarily, or extend an already active region, ++before the command is run. If the command was invoked without ++shift-translation, and the region is temporarily active, deactivate ++the region before the command is run. Special. ++ ++@item a ++A function name (i.e., a symbol satisfying @code{fboundp}). Existing, ++Completion, Prompt. ++ ++@item b ++The name of an existing buffer. By default, uses the name of the ++current buffer (@pxref{Buffers}). Existing, Completion, Default, ++Prompt. ++ ++@item B ++A buffer name. The buffer need not exist. By default, uses the name of ++a recently used buffer other than the current buffer. Completion, ++Default, Prompt. ++ ++@item c ++A character. The cursor does not move into the echo area. Prompt. ++ ++@item C ++A command name (i.e., a symbol satisfying @code{commandp}). Existing, ++Completion, Prompt. ++ ++@item d ++@cindex position argument ++The position of point, as an integer (@pxref{Point}). No I/O. ++ ++@item D ++A directory name. The default is the current default directory of the ++current buffer, @code{default-directory} (@pxref{File Name Expansion}). ++Existing, Completion, Default, Prompt. ++ ++@item e ++The first or next mouse event in the key sequence that invoked the command. ++More precisely, @samp{e} gets events that are lists, so you can look at ++the data in the lists. @xref{Input Events}. No I/O. ++ ++You can use @samp{e} more than once in a single command's interactive ++specification. If the key sequence that invoked the command has ++@var{n} events that are lists, the @var{n}th @samp{e} provides the ++@var{n}th such event. Events that are not lists, such as function keys ++and @acronym{ASCII} characters, do not count where @samp{e} is concerned. ++ ++@item f ++A file name of an existing file (@pxref{File Names}). The default ++directory is @code{default-directory}. Existing, Completion, Default, ++Prompt. ++ ++@item F ++A file name. The file need not exist. Completion, Default, Prompt. ++ ++@item G ++A file name. The file need not exist. If the user enters just a ++directory name, then the value is just that directory name, with no ++file name within the directory added. Completion, Default, Prompt. ++ ++@item i ++An irrelevant argument. This code always supplies @code{nil} as ++the argument's value. No I/O. ++ ++@item k ++A key sequence (@pxref{Key Sequences}). This keeps reading events ++until a command (or undefined command) is found in the current key ++maps. The key sequence argument is represented as a string or vector. ++The cursor does not move into the echo area. Prompt. ++ ++If @samp{k} reads a key sequence that ends with a down-event, it also ++reads and discards the following up-event. You can get access to that ++up-event with the @samp{U} code character. ++ ++This kind of input is used by commands such as @code{describe-key} and ++@code{global-set-key}. ++ ++@item K ++A key sequence, whose definition you intend to change. This works like ++@samp{k}, except that it suppresses, for the last input event in the key ++sequence, the conversions that are normally used (when necessary) to ++convert an undefined key into a defined one. ++ ++@item m ++@cindex marker argument ++The position of the mark, as an integer. No I/O. ++ ++@item M ++Arbitrary text, read in the minibuffer using the current buffer's input ++method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU ++Emacs Manual}). Prompt. ++ ++@item n ++A number, read with the minibuffer. If the input is not a number, the ++user has to try again. @samp{n} never uses the prefix argument. ++Prompt. ++ ++@item N ++The numeric prefix argument; but if there is no prefix argument, read ++a number as with @kbd{n}. The value is always a number. @xref{Prefix ++Command Arguments}. Prompt. ++ ++@item p ++@cindex numeric prefix argument usage ++The numeric prefix argument. (Note that this @samp{p} is lower case.) ++No I/O. ++ ++@item P ++@cindex raw prefix argument usage ++The raw prefix argument. (Note that this @samp{P} is upper case.) No ++I/O. ++ ++@item r ++@cindex region argument ++Point and the mark, as two numeric arguments, smallest first. This is ++the only code letter that specifies two successive arguments rather than ++one. No I/O. ++ ++@item s ++Arbitrary text, read in the minibuffer and returned as a string ++(@pxref{Text from Minibuffer}). Terminate the input with either ++@kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of ++these characters in the input.) Prompt. ++ ++@item S ++An interned symbol whose name is read in the minibuffer. Any whitespace ++character terminates the input. (Use @kbd{C-q} to include whitespace in ++the string.) Other characters that normally terminate a symbol (e.g., ++parentheses and brackets) do not do so here. Prompt. ++ ++@item U ++A key sequence or @code{nil}. Can be used after a @samp{k} or ++@samp{K} argument to get the up-event that was discarded (if any) ++after @samp{k} or @samp{K} read a down-event. If no up-event has been ++discarded, @samp{U} provides @code{nil} as the argument. No I/O. ++ ++@item v ++A variable declared to be a user option (i.e., satisfying the ++predicate @code{user-variable-p}). This reads the variable using ++@code{read-variable}. @xref{Definition of read-variable}. Existing, ++Completion, Prompt. ++ ++@item x ++A Lisp object, specified with its read syntax, terminated with a ++@kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from ++Minibuffer}. Prompt. ++ ++@item X ++@cindex evaluated expression argument ++A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates ++the form so that its value becomes the argument for the command. ++Prompt. ++ ++@item z ++A coding system name (a symbol). If the user enters null input, the ++argument value is @code{nil}. @xref{Coding Systems}. Completion, ++Existing, Prompt. ++ ++@item Z ++A coding system name (a symbol)---but only if this command has a prefix ++argument. With no prefix argument, @samp{Z} provides @code{nil} as the ++argument value. Completion, Existing, Prompt. ++@end table ++ ++@node Interactive Examples ++@comment node-name, next, previous, up ++@subsection Examples of Using @code{interactive} ++@cindex examples of using @code{interactive} ++@cindex @code{interactive}, examples of using ++ ++ Here are some examples of @code{interactive}: ++ ++@example ++@group ++(defun foo1 () ; @r{@code{foo1} takes no arguments,} ++ (interactive) ; @r{just moves forward two words.} ++ (forward-word 2)) ++ @result{} foo1 ++@end group ++ ++@group ++(defun foo2 (n) ; @r{@code{foo2} takes one argument,} ++ (interactive "^p") ; @r{which is the numeric prefix.} ++ ; @r{under @code{shift-select-mode},} ++ ; @r{will activate or extend region.} ++ (forward-word (* 2 n))) ++ @result{} foo2 ++@end group ++ ++@group ++(defun foo3 (n) ; @r{@code{foo3} takes one argument,} ++ (interactive "nCount:") ; @r{which is read with the Minibuffer.} ++ (forward-word (* 2 n))) ++ @result{} foo3 ++@end group ++ ++@group ++(defun three-b (b1 b2 b3) ++ "Select three existing buffers. ++Put them into three windows, selecting the last one." ++@end group ++ (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") ++ (delete-other-windows) ++ (split-window (selected-window) 8) ++ (switch-to-buffer b1) ++ (other-window 1) ++ (split-window (selected-window) 8) ++ (switch-to-buffer b2) ++ (other-window 1) ++ (switch-to-buffer b3)) ++ @result{} three-b ++@group ++(three-b "*scratch*" "declarations.texi" "*mail*") ++ @result{} nil ++@end group ++@end example ++ ++@node Interactive Call ++@section Interactive Call ++@cindex interactive call ++ ++ After the command loop has translated a key sequence into a command, ++it invokes that command using the function @code{command-execute}. If ++the command is a function, @code{command-execute} calls ++@code{call-interactively}, which reads the arguments and calls the ++command. You can also call these functions yourself. ++ ++@defun commandp object &optional for-call-interactively ++Returns @code{t} if @var{object} is suitable for calling interactively; ++that is, if @var{object} is a command. Otherwise, returns @code{nil}. ++ ++Interactively-callable objects include strings and vectors (which are ++treated as keyboard macros), lambda expressions that contain a ++top-level @code{interactive} form (@pxref{Using Interactive}), ++byte-code function objects made from such lambda expressions, autoload ++objects that are declared as interactive (non-@code{nil} fourth ++argument to @code{autoload}), and some primitive functions. ++ ++A symbol satisfies @code{commandp} if it has a non-@code{nil} ++@code{interactive-form} property, or if its function definition ++satisfies @code{commandp}. Keys and keymaps are not commands. ++Rather, they are used to look up commands (@pxref{Keymaps}). ++ ++If @var{for-call-interactively} is non-@code{nil}, then ++@code{commandp} returns @code{t} only for objects that ++@code{call-interactively} could call---thus, not for keyboard macros. ++ ++See @code{documentation} in @ref{Accessing Documentation}, for a ++realistic example of using @code{commandp}. ++@end defun ++ ++@defun call-interactively command &optional record-flag keys ++This function calls the interactively callable function @var{command}, ++reading arguments according to its interactive calling specifications. ++It returns whatever @var{command} returns. An error is signaled if ++@var{command} is not a function or if it cannot be called ++interactively (i.e., is not a command). Note that keyboard macros ++(strings and vectors) are not accepted, even though they are ++considered commands, because they are not functions. If @var{command} ++is a symbol, then @code{call-interactively} uses its function definition. ++ ++@cindex record command history ++If @var{record-flag} is non-@code{nil}, then this command and its ++arguments are unconditionally added to the list @code{command-history}. ++Otherwise, the command is added only if it uses the minibuffer to read ++an argument. @xref{Command History}. ++ ++The argument @var{keys}, if given, should be a vector which specifies ++the sequence of events to supply if the command inquires which events ++were used to invoke it. If @var{keys} is omitted or @code{nil}, the ++default is the return value of @code{this-command-keys-vector}. ++@xref{Definition of this-command-keys-vector}. ++@end defun ++ ++@defun command-execute command &optional record-flag keys special ++@cindex keyboard macro execution ++This function executes @var{command}. The argument @var{command} must ++satisfy the @code{commandp} predicate; i.e., it must be an interactively ++callable function or a keyboard macro. ++ ++A string or vector as @var{command} is executed with ++@code{execute-kbd-macro}. A function is passed to ++@code{call-interactively}, along with the optional @var{record-flag} ++and @var{keys}. ++ ++A symbol is handled by using its function definition in its place. A ++symbol with an @code{autoload} definition counts as a command if it was ++declared to stand for an interactively callable function. Such a ++definition is handled by loading the specified library and then ++rechecking the definition of the symbol. ++ ++The argument @var{special}, if given, means to ignore the prefix ++argument and not clear it. This is used for executing special events ++(@pxref{Special Events}). ++@end defun ++ ++@deffn Command execute-extended-command prefix-argument ++@cindex read command name ++This function reads a command name from the minibuffer using ++@code{completing-read} (@pxref{Completion}). Then it uses ++@code{command-execute} to call the specified command. Whatever that ++command returns becomes the value of @code{execute-extended-command}. ++ ++@cindex execute with prefix argument ++If the command asks for a prefix argument, it receives the value ++@var{prefix-argument}. If @code{execute-extended-command} is called ++interactively, the current raw prefix argument is used for ++@var{prefix-argument}, and thus passed on to whatever command is run. ++ ++@c !!! Should this be @kindex? ++@cindex @kbd{M-x} ++@code{execute-extended-command} is the normal definition of @kbd{M-x}, ++so it uses the string @w{@samp{M-x }} as a prompt. (It would be better ++to take the prompt from the events used to invoke ++@code{execute-extended-command}, but that is painful to implement.) A ++description of the value of the prefix argument, if any, also becomes ++part of the prompt. ++ ++@example ++@group ++(execute-extended-command 3) ++---------- Buffer: Minibuffer ---------- ++3 M-x forward-word RET ++---------- Buffer: Minibuffer ---------- ++ @result{} t ++@end group ++@end example ++@end deffn ++ ++@node Distinguish Interactive ++@section Distinguish Interactive Calls ++ ++ Sometimes a command should display additional visual feedback (such ++as an informative message in the echo area) for interactive calls ++only. There are three ways to do this. The recommended way to test ++whether the function was called using @code{call-interactively} is to ++give it an optional argument @code{print-message} and use the ++@code{interactive} spec to make it non-@code{nil} in interactive ++calls. Here's an example: ++ ++@example ++(defun foo (&optional print-message) ++ (interactive "p") ++ (when print-message ++ (message "foo"))) ++@end example ++ ++@noindent ++We use @code{"p"} because the numeric prefix argument is never ++@code{nil}. Defined in this way, the function does display the ++message when called from a keyboard macro. ++ ++ The above method with the additional argument is usually best, ++because it allows callers to say ``treat this call as interactive.'' ++But you can also do the job in a simpler way by testing ++@code{called-interactively-p}. ++ ++@defun called-interactively-p ++This function returns @code{t} when the calling function was called ++using @code{call-interactively}. ++ ++If the containing function was called by Lisp evaluation (or with ++@code{apply} or @code{funcall}), then it was not called interactively. ++@end defun ++ ++ Here's an example of using @code{called-interactively-p}: ++ ++@example ++@group ++(defun foo () ++ (interactive) ++ (when (called-interactively-p) ++ (message "foo")) ++ 'haha) ++ @result{} foo ++@end group ++ ++@group ++;; @r{Type @kbd{M-x foo}.} ++ @print{} foo ++@end group ++ ++@group ++(foo) ++ @result{} haha ++@end group ++@end example ++ ++ Here is another example that contrasts direct and indirect ++calls to @code{called-interactively-p}. ++ ++@example ++@group ++(defun bar () ++ (interactive) ++ (setq foobar (list (foo) (called-interactively-p)))) ++ @result{} bar ++@end group ++ ++@group ++;; @r{Type @kbd{M-x bar}.} ++;; @r{This does not display a message.} ++@end group ++ ++@group ++foobar ++ @result{} (nil t) ++@end group ++@end example ++ ++ If you want to treat commands run in keyboard macros just like calls ++from Lisp programs, test @code{interactive-p} instead of ++@code{called-interactively-p}. ++ ++@defun interactive-p ++This function returns @code{t} if the containing function (the one ++whose code includes the call to @code{interactive-p}) was called in ++direct response to user input. This means that it was called with the ++function @code{call-interactively}, and that a keyboard macro is ++not running, and that Emacs is not running in batch mode. ++@end defun ++ ++@node Command Loop Info ++@comment node-name, next, previous, up ++@section Information from the Command Loop ++ ++The editor command loop sets several Lisp variables to keep status ++records for itself and for commands that are run. With the exception of ++@code{this-command} and @code{last-command} it's generally a bad idea to ++change any of these variables in a Lisp program. ++ ++@defvar last-command ++This variable records the name of the previous command executed by the ++command loop (the one before the current command). Normally the value ++is a symbol with a function definition, but this is not guaranteed. ++ ++The value is copied from @code{this-command} when a command returns to ++the command loop, except when the command has specified a prefix ++argument for the following command. ++ ++This variable is always local to the current terminal and cannot be ++buffer-local. @xref{Multiple Terminals}. ++@end defvar ++ ++@defvar real-last-command ++This variable is set up by Emacs just like @code{last-command}, ++but never altered by Lisp programs. ++@end defvar ++ ++@defvar last-repeatable-command ++This variable stores the most recently executed command that was not ++part of an input event. This is the command @code{repeat} will try to ++repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}. ++@end defvar ++ ++@defvar this-command ++@cindex current command ++This variable records the name of the command now being executed by ++the editor command loop. Like @code{last-command}, it is normally a symbol ++with a function definition. ++ ++The command loop sets this variable just before running a command, and ++copies its value into @code{last-command} when the command finishes ++(unless the command specified a prefix argument for the following ++command). ++ ++@cindex kill command repetition ++Some commands set this variable during their execution, as a flag for ++whatever command runs next. In particular, the functions for killing text ++set @code{this-command} to @code{kill-region} so that any kill commands ++immediately following will know to append the killed text to the ++previous kill. ++@end defvar ++ ++If you do not want a particular command to be recognized as the previous ++command in the case where it got an error, you must code that command to ++prevent this. One way is to set @code{this-command} to @code{t} at the ++beginning of the command, and set @code{this-command} back to its proper ++value at the end, like this: ++ ++@example ++(defun foo (args@dots{}) ++ (interactive @dots{}) ++ (let ((old-this-command this-command)) ++ (setq this-command t) ++ @r{@dots{}do the work@dots{}} ++ (setq this-command old-this-command))) ++@end example ++ ++@noindent ++We do not bind @code{this-command} with @code{let} because that would ++restore the old value in case of error---a feature of @code{let} which ++in this case does precisely what we want to avoid. ++ ++@defvar this-original-command ++This has the same value as @code{this-command} except when command ++remapping occurs (@pxref{Remapping Commands}). In that case, ++@code{this-command} gives the command actually run (the result of ++remapping), and @code{this-original-command} gives the command that ++was specified to run but remapped into another command. ++@end defvar ++ ++@defun this-command-keys ++This function returns a string or vector containing the key sequence ++that invoked the present command, plus any previous commands that ++generated the prefix argument for this command. Any events read by the ++command using @code{read-event} without a timeout get tacked on to the end. ++ ++However, if the command has called @code{read-key-sequence}, it ++returns the last read key sequence. @xref{Key Sequence Input}. The ++value is a string if all events in the sequence were characters that ++fit in a string. @xref{Input Events}. ++ ++@example ++@group ++(this-command-keys) ++;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} ++ @result{} "^U^X^E" ++@end group ++@end example ++@end defun ++ ++@defun this-command-keys-vector ++@anchor{Definition of this-command-keys-vector} ++Like @code{this-command-keys}, except that it always returns the events ++in a vector, so you don't need to deal with the complexities of storing ++input events in a string (@pxref{Strings of Events}). ++@end defun ++ ++@defun clear-this-command-keys &optional keep-record ++This function empties out the table of events for ++@code{this-command-keys} to return. Unless @var{keep-record} is ++non-@code{nil}, it also empties the records that the function ++@code{recent-keys} (@pxref{Recording Input}) will subsequently return. ++This is useful after reading a password, to prevent the password from ++echoing inadvertently as part of the next command in certain cases. ++@end defun ++ ++@defvar last-nonmenu-event ++This variable holds the last input event read as part of a key sequence, ++not counting events resulting from mouse menus. ++ ++One use of this variable is for telling @code{x-popup-menu} where to pop ++up a menu. It is also used internally by @code{y-or-n-p} ++(@pxref{Yes-or-No Queries}). ++@end defvar ++ ++@defvar last-command-event ++@defvarx last-command-char ++This variable is set to the last input event that was read by the ++command loop as part of a command. The principal use of this variable ++is in @code{self-insert-command}, which uses it to decide which ++character to insert. ++ ++@example ++@group ++last-command-event ++;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} ++ @result{} 5 ++@end group ++@end example ++ ++@noindent ++The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}. ++ ++The alias @code{last-command-char} is obsolete. ++@end defvar ++ ++@c Emacs 19 feature ++@defvar last-event-frame ++This variable records which frame the last input event was directed to. ++Usually this is the frame that was selected when the event was ++generated, but if that frame has redirected input focus to another ++frame, the value is the frame to which the event was redirected. ++@xref{Input Focus}. ++ ++If the last event came from a keyboard macro, the value is @code{macro}. ++@end defvar ++ ++@node Adjusting Point ++@section Adjusting Point After Commands ++@cindex adjusting point ++@cindex invisible/intangible text, and point ++@cindex @code{display} property, and point display ++@cindex @code{composition} property, and point display ++ ++ It is not easy to display a value of point in the middle of a ++sequence of text that has the @code{display}, @code{composition} or ++@code{intangible} property, or is invisible. Therefore, after a ++command finishes and returns to the command loop, if point is within ++such a sequence, the command loop normally moves point to the edge of ++the sequence. ++ ++ A command can inhibit this feature by setting the variable ++@code{disable-point-adjustment}: ++ ++@defvar disable-point-adjustment ++If this variable is non-@code{nil} when a command returns to the ++command loop, then the command loop does not check for those text ++properties, and does not move point out of sequences that have them. ++ ++The command loop sets this variable to @code{nil} before each command, ++so if a command sets it, the effect applies only to that command. ++@end defvar ++ ++@defvar global-disable-point-adjustment ++If you set this variable to a non-@code{nil} value, the feature of ++moving point out of these sequences is completely turned off. ++@end defvar ++ ++@node Input Events ++@section Input Events ++@cindex events ++@cindex input events ++ ++The Emacs command loop reads a sequence of @dfn{input events} that ++represent keyboard or mouse activity. The events for keyboard activity ++are characters or symbols; mouse events are always lists. This section ++describes the representation and meaning of input events in detail. ++ ++@defun eventp object ++This function returns non-@code{nil} if @var{object} is an input event ++or event type. ++ ++Note that any symbol might be used as an event or an event type. ++@code{eventp} cannot distinguish whether a symbol is intended by Lisp ++code to be used as an event. Instead, it distinguishes whether the ++symbol has actually been used in an event that has been read as input in ++the current Emacs session. If a symbol has not yet been so used, ++@code{eventp} returns @code{nil}. ++@end defun ++ ++@menu ++* Keyboard Events:: Ordinary characters--keys with symbols on them. ++* Function Keys:: Function keys--keys with names, not symbols. ++* Mouse Events:: Overview of mouse events. ++* Click Events:: Pushing and releasing a mouse button. ++* Drag Events:: Moving the mouse before releasing the button. ++* Button-Down Events:: A button was pushed and not yet released. ++* Repeat Events:: Double and triple click (or drag, or down). ++* Motion Events:: Just moving the mouse, not pushing a button. ++* Focus Events:: Moving the mouse between frames. ++* Misc Events:: Other events the system can generate. ++* Event Examples:: Examples of the lists for mouse events. ++* Classifying Events:: Finding the modifier keys in an event symbol. ++ Event types. ++* Accessing Mouse:: Functions to extract info from mouse events. ++* Accessing Scroll:: Functions to get info from scroll bar events. ++* Strings of Events:: Special considerations for putting ++ keyboard character events in a string. ++@end menu ++ ++@node Keyboard Events ++@subsection Keyboard Events ++@cindex keyboard events ++ ++There are two kinds of input you can get from the keyboard: ordinary ++keys, and function keys. Ordinary keys correspond to characters; the ++events they generate are represented in Lisp as characters. The event ++type of a character event is the character itself (an integer); see ++@ref{Classifying Events}. ++ ++@cindex modifier bits (of input character) ++@cindex basic code (of input character) ++An input character event consists of a @dfn{basic code} between 0 and ++524287, plus any or all of these @dfn{modifier bits}: ++ ++@table @asis ++@item meta ++The ++@tex ++@math{2^{27}} ++@end tex ++@ifnottex ++2**27 ++@end ifnottex ++bit in the character code indicates a character ++typed with the meta key held down. ++ ++@item control ++The ++@tex ++@math{2^{26}} ++@end tex ++@ifnottex ++2**26 ++@end ifnottex ++bit in the character code indicates a non-@acronym{ASCII} ++control character. ++ ++@sc{ascii} control characters such as @kbd{C-a} have special basic ++codes of their own, so Emacs needs no special bit to indicate them. ++Thus, the code for @kbd{C-a} is just 1. ++ ++But if you type a control combination not in @acronym{ASCII}, such as ++@kbd{%} with the control key, the numeric value you get is the code ++for @kbd{%} plus ++@tex ++@math{2^{26}} ++@end tex ++@ifnottex ++2**26 ++@end ifnottex ++(assuming the terminal supports non-@acronym{ASCII} ++control characters). ++ ++@item shift ++The ++@tex ++@math{2^{25}} ++@end tex ++@ifnottex ++2**25 ++@end ifnottex ++bit in the character code indicates an @acronym{ASCII} control ++character typed with the shift key held down. ++ ++For letters, the basic code itself indicates upper versus lower case; ++for digits and punctuation, the shift key selects an entirely different ++character with a different basic code. In order to keep within the ++@acronym{ASCII} character set whenever possible, Emacs avoids using the ++@tex ++@math{2^{25}} ++@end tex ++@ifnottex ++2**25 ++@end ifnottex ++bit for those characters. ++ ++However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from ++@kbd{C-a}, so Emacs uses the ++@tex ++@math{2^{25}} ++@end tex ++@ifnottex ++2**25 ++@end ifnottex ++bit in @kbd{C-A} and not in ++@kbd{C-a}. ++ ++@item hyper ++The ++@tex ++@math{2^{24}} ++@end tex ++@ifnottex ++2**24 ++@end ifnottex ++bit in the character code indicates a character ++typed with the hyper key held down. ++ ++@item super ++The ++@tex ++@math{2^{23}} ++@end tex ++@ifnottex ++2**23 ++@end ifnottex ++bit in the character code indicates a character ++typed with the super key held down. ++ ++@item alt ++The ++@tex ++@math{2^{22}} ++@end tex ++@ifnottex ++2**22 ++@end ifnottex ++bit in the character code indicates a character typed with ++the alt key held down. (On some terminals, the key labeled @key{ALT} ++is actually the meta key.) ++@end table ++ ++ It is best to avoid mentioning specific bit numbers in your program. ++To test the modifier bits of a character, use the function ++@code{event-modifiers} (@pxref{Classifying Events}). When making key ++bindings, you can use the read syntax for characters with modifier bits ++(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with ++@code{define-key}, you can use lists such as @code{(control hyper ?x)} to ++specify the characters (@pxref{Changing Key Bindings}). The function ++@code{event-convert-list} converts such a list into an event type ++(@pxref{Classifying Events}). ++ ++@node Function Keys ++@subsection Function Keys ++ ++@cindex function keys ++Most keyboards also have @dfn{function keys}---keys that have names or ++symbols that are not characters. Function keys are represented in Emacs ++Lisp as symbols; the symbol's name is the function key's label, in lower ++case. For example, pressing a key labeled @key{F1} places the symbol ++@code{f1} in the input stream. ++ ++The event type of a function key event is the event symbol itself. ++@xref{Classifying Events}. ++ ++Here are a few special cases in the symbol-naming convention for ++function keys: ++ ++@table @asis ++@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete} ++These keys correspond to common @acronym{ASCII} control characters that have ++special keys on most keyboards. ++ ++In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the ++terminal can distinguish between them, Emacs conveys the distinction to ++Lisp programs by representing the former as the integer 9, and the ++latter as the symbol @code{tab}. ++ ++Most of the time, it's not useful to distinguish the two. So normally ++@code{local-function-key-map} (@pxref{Translation Keymaps}) is set up ++to map @code{tab} into 9. Thus, a key binding for character code 9 ++(the character @kbd{C-i}) also applies to @code{tab}. Likewise for ++the other symbols in this group. The function @code{read-char} ++likewise converts these events into characters. ++ ++In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace} ++converts into the character code 127 (@key{DEL}), not into code 8 ++(@key{BS}). This is what most users prefer. ++ ++@item @code{left}, @code{up}, @code{right}, @code{down} ++Cursor arrow keys ++@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{} ++Keypad keys (to the right of the regular keyboard). ++@item @code{kp-0}, @code{kp-1}, @dots{} ++Keypad keys with digits. ++@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} ++Keypad PF keys. ++@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down} ++Keypad arrow keys. Emacs normally translates these into the ++corresponding non-keypad keys @code{home}, @code{left}, @dots{} ++@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete} ++Additional keypad duplicates of keys ordinarily found elsewhere. Emacs ++normally translates these into the like-named non-keypad keys. ++@end table ++ ++You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER}, ++@key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to ++represent them is with prefixes in the symbol name: ++ ++@table @samp ++@item A- ++The alt modifier. ++@item C- ++The control modifier. ++@item H- ++The hyper modifier. ++@item M- ++The meta modifier. ++@item S- ++The shift modifier. ++@item s- ++The super modifier. ++@end table ++ ++Thus, the symbol for the key @key{F3} with @key{META} held down is ++@code{M-f3}. When you use more than one prefix, we recommend you ++write them in alphabetical order; but the order does not matter in ++arguments to the key-binding lookup and modification functions. ++ ++@node Mouse Events ++@subsection Mouse Events ++ ++Emacs supports four kinds of mouse events: click events, drag events, ++button-down events, and motion events. All mouse events are represented ++as lists. The @sc{car} of the list is the event type; this says which ++mouse button was involved, and which modifier keys were used with it. ++The event type can also distinguish double or triple button presses ++(@pxref{Repeat Events}). The rest of the list elements give position ++and time information. ++ ++For key lookup, only the event type matters: two events of the same type ++necessarily run the same command. The command can access the full ++values of these events using the @samp{e} interactive code. ++@xref{Interactive Codes}. ++ ++A key sequence that starts with a mouse event is read using the keymaps ++of the buffer in the window that the mouse was in, not the current ++buffer. This does not imply that clicking in a window selects that ++window or its buffer---that is entirely under the control of the command ++binding of the key sequence. ++ ++@node Click Events ++@subsection Click Events ++@cindex click event ++@cindex mouse click event ++ ++When the user presses a mouse button and releases it at the same ++location, that generates a @dfn{click} event. All mouse click event ++share the same format: ++ ++@example ++(@var{event-type} @var{position} @var{click-count}) ++@end example ++ ++@table @asis ++@item @var{event-type} ++This is a symbol that indicates which mouse button was used. It is ++one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the ++buttons are numbered left to right. ++ ++You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, ++@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift ++and super, just as you would with function keys. ++ ++This symbol also serves as the event type of the event. Key bindings ++describe events by their types; thus, if there is a key binding for ++@code{mouse-1}, that binding would apply to all events whose ++@var{event-type} is @code{mouse-1}. ++ ++@item @var{position} ++This is the position where the mouse click occurred. The actual ++format of @var{position} depends on what part of a window was clicked ++on. ++ ++For mouse click events in the text area, mode line, header line, or in ++the marginal areas, @var{position} has this form: ++ ++@example ++(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} ++ @var{object} @var{text-pos} (@var{col} . @var{row}) ++ @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) ++@end example ++ ++@table @asis ++@item @var{window} ++This is the window in which the click occurred. ++ ++@item @var{pos-or-area} ++This is the buffer position of the character clicked on in the text ++area, or if clicked outside the text area, it is the window area in ++which the click occurred. It is one of the symbols @code{mode-line}, ++@code{header-line}, @code{vertical-line}, @code{left-margin}, ++@code{right-margin}, @code{left-fringe}, or @code{right-fringe}. ++ ++In one special case, @var{pos-or-area} is a list containing a symbol (one ++of the symbols listed above) instead of just the symbol. This happens ++after the imaginary prefix keys for the event are inserted into the ++input stream. @xref{Key Sequence Input}. ++ ++ ++@item @var{x}, @var{y} ++These are the pixel coordinates of the click, relative to ++the top left corner of @var{window}, which is @code{(0 . 0)}. ++For the mode or header line, @var{y} does not have meaningful data. ++For the vertical line, @var{x} does not have meaningful data. ++ ++@item @var{timestamp} ++This is the time at which the event occurred, in milliseconds. ++ ++@item @var{object} ++This is the object on which the click occurred. It is either ++@code{nil} if there is no string property, or it has the form ++(@var{string} . @var{string-pos}) when there is a string-type text ++property at the click position. ++ ++@table @asis ++@item @var{string} ++This is the string on which the click occurred, including any ++properties. ++ ++@item @var{string-pos} ++This is the position in the string on which the click occurred, ++relevant if properties at the click need to be looked up. ++@end table ++ ++@item @var{text-pos} ++For clicks on a marginal area or on a fringe, this is the buffer ++position of the first visible character in the corresponding line in ++the window. For other events, it is the current buffer position in ++the window. ++ ++@item @var{col}, @var{row} ++These are the actual coordinates of the glyph under the @var{x}, ++@var{y} position, possibly padded with default character width ++glyphs if @var{x} is beyond the last glyph on the line. ++ ++@item @var{image} ++This is the image object on which the click occurred. It is either ++@code{nil} if there is no image at the position clicked on, or it is ++an image object as returned by @code{find-image} if click was in an image. ++ ++@item @var{dx}, @var{dy} ++These are the pixel coordinates of the click, relative to ++the top left corner of @var{object}, which is @code{(0 . 0)}. If ++@var{object} is @code{nil}, the coordinates are relative to the top ++left corner of the character glyph clicked on. ++ ++@item @var{width}, @var{height} ++These are the pixel width and height of @var{object} or, if this is ++@code{nil}, those of the character glyph clicked on. ++@end table ++ ++@sp 1 ++For mouse clicks on a scroll-bar, @var{position} has this form: ++ ++@example ++(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part}) ++@end example ++ ++@table @asis ++@item @var{window} ++This is the window whose scroll-bar was clicked on. ++ ++@item @var{area} ++This is the scroll bar where the click occurred. It is one of the ++symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}. ++ ++@item @var{portion} ++This is the distance of the click from the top or left end of ++the scroll bar. ++ ++@item @var{whole} ++This is the length of the entire scroll bar. ++ ++@item @var{timestamp} ++This is the time at which the event occurred, in milliseconds. ++ ++@item @var{part} ++This is the part of the scroll-bar which was clicked on. It is one ++of the symbols @code{above-handle}, @code{handle}, @code{below-handle}, ++@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}. ++@end table ++ ++@item @var{click-count} ++This is the number of rapid repeated presses so far of the same mouse ++button. @xref{Repeat Events}. ++@end table ++ ++@node Drag Events ++@subsection Drag Events ++@cindex drag event ++@cindex mouse drag event ++ ++With Emacs, you can have a drag event without even changing your ++clothes. A @dfn{drag event} happens every time the user presses a mouse ++button and then moves the mouse to a different character position before ++releasing the button. Like all mouse events, drag events are ++represented in Lisp as lists. The lists record both the starting mouse ++position and the final position, like this: ++ ++@example ++(@var{event-type} ++ (@var{window1} START-POSITION) ++ (@var{window2} END-POSITION)) ++@end example ++ ++For a drag event, the name of the symbol @var{event-type} contains the ++prefix @samp{drag-}. For example, dragging the mouse with button 2 ++held down generates a @code{drag-mouse-2} event. The second and third ++elements of the event give the starting and ending position of the ++drag. They have the same form as @var{position} in a click event ++(@pxref{Click Events}) that is not on the scroll bar part of the ++window. You can access the second element of any mouse event in the ++same way, with no need to distinguish drag events from others. ++ ++The @samp{drag-} prefix follows the modifier key prefixes such as ++@samp{C-} and @samp{M-}. ++ ++If @code{read-key-sequence} receives a drag event that has no key ++binding, and the corresponding click event does have a binding, it ++changes the drag event into a click event at the drag's starting ++position. This means that you don't have to distinguish between click ++and drag events unless you want to. ++ ++@node Button-Down Events ++@subsection Button-Down Events ++@cindex button-down event ++ ++Click and drag events happen when the user releases a mouse button. ++They cannot happen earlier, because there is no way to distinguish a ++click from a drag until the button is released. ++ ++If you want to take action as soon as a button is pressed, you need to ++handle @dfn{button-down} events.@footnote{Button-down is the ++conservative antithesis of drag.} These occur as soon as a button is ++pressed. They are represented by lists that look exactly like click ++events (@pxref{Click Events}), except that the @var{event-type} symbol ++name contains the prefix @samp{down-}. The @samp{down-} prefix follows ++modifier key prefixes such as @samp{C-} and @samp{M-}. ++ ++The function @code{read-key-sequence} ignores any button-down events ++that don't have command bindings; therefore, the Emacs command loop ++ignores them too. This means that you need not worry about defining ++button-down events unless you want them to do something. The usual ++reason to define a button-down event is so that you can track mouse ++motion (by reading motion events) until the button is released. ++@xref{Motion Events}. ++ ++@node Repeat Events ++@subsection Repeat Events ++@cindex repeat events ++@cindex double-click events ++@cindex triple-click events ++@cindex mouse events, repeated ++ ++If you press the same mouse button more than once in quick succession ++without moving the mouse, Emacs generates special @dfn{repeat} mouse ++events for the second and subsequent presses. ++ ++The most common repeat events are @dfn{double-click} events. Emacs ++generates a double-click event when you click a button twice; the event ++happens when you release the button (as is normal for all click ++events). ++ ++The event type of a double-click event contains the prefix ++@samp{double-}. Thus, a double click on the second mouse button with ++@key{meta} held down comes to the Lisp program as ++@code{M-double-mouse-2}. If a double-click event has no binding, the ++binding of the corresponding ordinary click event is used to execute ++it. Thus, you need not pay attention to the double click feature ++unless you really want to. ++ ++When the user performs a double click, Emacs generates first an ordinary ++click event, and then a double-click event. Therefore, you must design ++the command binding of the double click event to assume that the ++single-click command has already run. It must produce the desired ++results of a double click, starting from the results of a single click. ++ ++This is convenient, if the meaning of a double click somehow ``builds ++on'' the meaning of a single click---which is recommended user interface ++design practice for double clicks. ++ ++If you click a button, then press it down again and start moving the ++mouse with the button held down, then you get a @dfn{double-drag} event ++when you ultimately release the button. Its event type contains ++@samp{double-drag} instead of just @samp{drag}. If a double-drag event ++has no binding, Emacs looks for an alternate binding as if the event ++were an ordinary drag. ++ ++Before the double-click or double-drag event, Emacs generates a ++@dfn{double-down} event when the user presses the button down for the ++second time. Its event type contains @samp{double-down} instead of just ++@samp{down}. If a double-down event has no binding, Emacs looks for an ++alternate binding as if the event were an ordinary button-down event. ++If it finds no binding that way either, the double-down event is ++ignored. ++ ++To summarize, when you click a button and then press it again right ++away, Emacs generates a down event and a click event for the first ++click, a double-down event when you press the button again, and finally ++either a double-click or a double-drag event. ++ ++If you click a button twice and then press it again, all in quick ++succession, Emacs generates a @dfn{triple-down} event, followed by ++either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of ++these events contain @samp{triple} instead of @samp{double}. If any ++triple event has no binding, Emacs uses the binding that it would use ++for the corresponding double event. ++ ++If you click a button three or more times and then press it again, the ++events for the presses beyond the third are all triple events. Emacs ++does not have separate event types for quadruple, quintuple, etc.@: ++events. However, you can look at the event list to find out precisely ++how many times the button was pressed. ++ ++@defun event-click-count event ++This function returns the number of consecutive button presses that led ++up to @var{event}. If @var{event} is a double-down, double-click or ++double-drag event, the value is 2. If @var{event} is a triple event, ++the value is 3 or greater. If @var{event} is an ordinary mouse event ++(not a repeat event), the value is 1. ++@end defun ++ ++@defopt double-click-fuzz ++To generate repeat events, successive mouse button presses must be at ++approximately the same screen position. The value of ++@code{double-click-fuzz} specifies the maximum number of pixels the ++mouse may be moved (horizontally or vertically) between two successive ++clicks to make a double-click. ++ ++This variable is also the threshold for motion of the mouse to count ++as a drag. ++@end defopt ++ ++@defopt double-click-time ++To generate repeat events, the number of milliseconds between ++successive button presses must be less than the value of ++@code{double-click-time}. Setting @code{double-click-time} to ++@code{nil} disables multi-click detection entirely. Setting it to ++@code{t} removes the time limit; Emacs then detects multi-clicks by ++position only. ++@end defopt ++ ++@node Motion Events ++@subsection Motion Events ++@cindex motion event ++@cindex mouse motion events ++ ++Emacs sometimes generates @dfn{mouse motion} events to describe motion ++of the mouse without any button activity. Mouse motion events are ++represented by lists that look like this: ++ ++@example ++(mouse-movement (POSITION)) ++@end example ++ ++The second element of the list describes the current position of the ++mouse, just as in a click event (@pxref{Click Events}). ++ ++The special form @code{track-mouse} enables generation of motion events ++within its body. Outside of @code{track-mouse} forms, Emacs does not ++generate events for mere motion of the mouse, and these events do not ++appear. @xref{Mouse Tracking}. ++ ++@node Focus Events ++@subsection Focus Events ++@cindex focus event ++ ++Window systems provide general ways for the user to control which window ++gets keyboard input. This choice of window is called the @dfn{focus}. ++When the user does something to switch between Emacs frames, that ++generates a @dfn{focus event}. The normal definition of a focus event, ++in the global keymap, is to select a new frame within Emacs, as the user ++would expect. @xref{Input Focus}. ++ ++Focus events are represented in Lisp as lists that look like this: ++ ++@example ++(switch-frame @var{new-frame}) ++@end example ++ ++@noindent ++where @var{new-frame} is the frame switched to. ++ ++Some X window managers are set up so that just moving the mouse into a ++window is enough to set the focus there. Usually, there is no need ++for a Lisp program to know about the focus change until some other ++kind of input arrives. Emacs generates a focus event only when the ++user actually types a keyboard key or presses a mouse button in the ++new frame; just moving the mouse between frames does not generate a ++focus event. ++ ++A focus event in the middle of a key sequence would garble the ++sequence. So Emacs never generates a focus event in the middle of a key ++sequence. If the user changes focus in the middle of a key ++sequence---that is, after a prefix key---then Emacs reorders the events ++so that the focus event comes either before or after the multi-event key ++sequence, and not within it. ++ ++@node Misc Events ++@subsection Miscellaneous System Events ++ ++A few other event types represent occurrences within the system. ++ ++@table @code ++@cindex @code{delete-frame} event ++@item (delete-frame (@var{frame})) ++This kind of event indicates that the user gave the window manager ++a command to delete a particular window, which happens to be an Emacs frame. ++ ++The standard definition of the @code{delete-frame} event is to delete @var{frame}. ++ ++@cindex @code{iconify-frame} event ++@item (iconify-frame (@var{frame})) ++This kind of event indicates that the user iconified @var{frame} using ++the window manager. Its standard definition is @code{ignore}; since the ++frame has already been iconified, Emacs has no work to do. The purpose ++of this event type is so that you can keep track of such events if you ++want to. ++ ++@cindex @code{make-frame-visible} event ++@item (make-frame-visible (@var{frame})) ++This kind of event indicates that the user deiconified @var{frame} using ++the window manager. Its standard definition is @code{ignore}; since the ++frame has already been made visible, Emacs has no work to do. ++ ++@cindex @code{wheel-up} event ++@cindex @code{wheel-down} event ++@item (wheel-up @var{position}) ++@item (wheel-down @var{position}) ++These kinds of event are generated by moving a mouse wheel. Their ++usual meaning is a kind of scroll or zoom. ++ ++The element @var{position} is a list describing the position of the ++event, in the same format as used in a mouse-click event. ++ ++This kind of event is generated only on some kinds of systems. On some ++systems, @code{mouse-4} and @code{mouse-5} are used instead. For ++portable code, use the variables @code{mouse-wheel-up-event} and ++@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine ++what event types to expect for the mouse wheel. ++ ++@cindex @code{drag-n-drop} event ++@item (drag-n-drop @var{position} @var{files}) ++This kind of event is generated when a group of files is ++selected in an application outside of Emacs, and then dragged and ++dropped onto an Emacs frame. ++ ++The element @var{position} is a list describing the position of the ++event, in the same format as used in a mouse-click event, and ++@var{files} is the list of file names that were dragged and dropped. ++The usual way to handle this event is by visiting these files. ++ ++This kind of event is generated, at present, only on some kinds of ++systems. ++ ++@cindex @code{help-echo} event ++@item help-echo ++This kind of event is generated when a mouse pointer moves onto a ++portion of buffer text which has a @code{help-echo} text property. ++The generated event has this form: ++ ++@example ++(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos}) ++@end example ++ ++@noindent ++The precise meaning of the event parameters and the way these ++parameters are used to display the help-echo text are described in ++@ref{Text help-echo}. ++ ++@cindex @code{sigusr1} event ++@cindex @code{sigusr2} event ++@cindex user signals ++@item sigusr1 ++@itemx sigusr2 ++These events are generated when the Emacs process receives ++the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no ++additional data because signals do not carry additional information. ++ ++To catch a user signal, bind the corresponding event to an interactive ++command in the @code{special-event-map} (@pxref{Active Keymaps}). ++The command is called with no arguments, and the specific signal event is ++available in @code{last-input-event}. For example: ++ ++@smallexample ++(defun sigusr-handler () ++ (interactive) ++ (message "Caught signal %S" last-input-event)) ++ ++(define-key special-event-map [sigusr1] 'sigusr-handler) ++@end smallexample ++ ++To test the signal handler, you can make Emacs send a signal to itself: ++ ++@smallexample ++(signal-process (emacs-pid) 'sigusr1) ++@end smallexample ++@end table ++ ++ If one of these events arrives in the middle of a key sequence---that ++is, after a prefix key---then Emacs reorders the events so that this ++event comes either before or after the multi-event key sequence, not ++within it. ++ ++@node Event Examples ++@subsection Event Examples ++ ++If the user presses and releases the left mouse button over the same ++location, that generates a sequence of events like this: ++ ++@smallexample ++(down-mouse-1 (# 2613 (0 . 38) -864320)) ++(mouse-1 (# 2613 (0 . 38) -864180)) ++@end smallexample ++ ++While holding the control key down, the user might hold down the ++second mouse button, and drag the mouse from one line to the next. ++That produces two events, as shown here: ++ ++@smallexample ++(C-down-mouse-2 (# 3440 (0 . 27) -731219)) ++(C-drag-mouse-2 (# 3440 (0 . 27) -731219) ++ (# 3510 (0 . 28) -729648)) ++@end smallexample ++ ++While holding down the meta and shift keys, the user might press the ++second mouse button on the window's mode line, and then drag the mouse ++into another window. That produces a pair of events like these: ++ ++@smallexample ++(M-S-down-mouse-2 (# mode-line (33 . 31) -457844)) ++(M-S-drag-mouse-2 (# mode-line (33 . 31) -457844) ++ (# 161 (33 . 3) ++ -453816)) ++@end smallexample ++ ++To handle a SIGUSR1 signal, define an interactive function, and ++bind it to the @code{signal usr1} event sequence: ++ ++@smallexample ++(defun usr1-handler () ++ (interactive) ++ (message "Got USR1 signal")) ++(global-set-key [signal usr1] 'usr1-handler) ++@end smallexample ++ ++@node Classifying Events ++@subsection Classifying Events ++@cindex event type ++ ++ Every event has an @dfn{event type}, which classifies the event for ++key binding purposes. For a keyboard event, the event type equals the ++event value; thus, the event type for a character is the character, and ++the event type for a function key symbol is the symbol itself. For ++events that are lists, the event type is the symbol in the @sc{car} of ++the list. Thus, the event type is always a symbol or a character. ++ ++ Two events of the same type are equivalent where key bindings are ++concerned; thus, they always run the same command. That does not ++necessarily mean they do the same things, however, as some commands look ++at the whole event to decide what to do. For example, some commands use ++the location of a mouse event to decide where in the buffer to act. ++ ++ Sometimes broader classifications of events are useful. For example, ++you might want to ask whether an event involved the @key{META} key, ++regardless of which other key or mouse button was used. ++ ++ The functions @code{event-modifiers} and @code{event-basic-type} are ++provided to get such information conveniently. ++ ++@defun event-modifiers event ++This function returns a list of the modifiers that @var{event} has. The ++modifiers are symbols; they include @code{shift}, @code{control}, ++@code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition, ++the modifiers list of a mouse event symbol always contains one of ++@code{click}, @code{drag}, and @code{down}. For double or triple ++events, it also contains @code{double} or @code{triple}. ++ ++The argument @var{event} may be an entire event object, or just an ++event type. If @var{event} is a symbol that has never been used in an ++event that has been read as input in the current Emacs session, then ++@code{event-modifiers} can return @code{nil}, even when @var{event} ++actually has modifiers. ++ ++Here are some examples: ++ ++@example ++(event-modifiers ?a) ++ @result{} nil ++(event-modifiers ?A) ++ @result{} (shift) ++(event-modifiers ?\C-a) ++ @result{} (control) ++(event-modifiers ?\C-%) ++ @result{} (control) ++(event-modifiers ?\C-\S-a) ++ @result{} (control shift) ++(event-modifiers 'f5) ++ @result{} nil ++(event-modifiers 's-f5) ++ @result{} (super) ++(event-modifiers 'M-S-f5) ++ @result{} (meta shift) ++(event-modifiers 'mouse-1) ++ @result{} (click) ++(event-modifiers 'down-mouse-1) ++ @result{} (down) ++@end example ++ ++The modifiers list for a click event explicitly contains @code{click}, ++but the event symbol name itself does not contain @samp{click}. ++@end defun ++ ++@defun event-basic-type event ++This function returns the key or mouse button that @var{event} ++describes, with all modifiers removed. The @var{event} argument is as ++in @code{event-modifiers}. For example: ++ ++@example ++(event-basic-type ?a) ++ @result{} 97 ++(event-basic-type ?A) ++ @result{} 97 ++(event-basic-type ?\C-a) ++ @result{} 97 ++(event-basic-type ?\C-\S-a) ++ @result{} 97 ++(event-basic-type 'f5) ++ @result{} f5 ++(event-basic-type 's-f5) ++ @result{} f5 ++(event-basic-type 'M-S-f5) ++ @result{} f5 ++(event-basic-type 'down-mouse-1) ++ @result{} mouse-1 ++@end example ++@end defun ++ ++@defun mouse-movement-p object ++This function returns non-@code{nil} if @var{object} is a mouse movement ++event. ++@end defun ++ ++@defun event-convert-list list ++This function converts a list of modifier names and a basic event type ++to an event type which specifies all of them. The basic event type ++must be the last element of the list. For example, ++ ++@example ++(event-convert-list '(control ?a)) ++ @result{} 1 ++(event-convert-list '(control meta ?a)) ++ @result{} -134217727 ++(event-convert-list '(control super f1)) ++ @result{} C-s-f1 ++@end example ++@end defun ++ ++@node Accessing Mouse ++@subsection Accessing Mouse Events ++@cindex mouse events, data in ++ ++ This section describes convenient functions for accessing the data in ++a mouse button or motion event. ++ ++ These two functions return the starting or ending position of a ++mouse-button event, as a list of this form: ++ ++@example ++(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} ++ @var{object} @var{text-pos} (@var{col} . @var{row}) ++ @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) ++@end example ++ ++@defun event-start event ++This returns the starting position of @var{event}. ++ ++If @var{event} is a click or button-down event, this returns the ++location of the event. If @var{event} is a drag event, this returns the ++drag's starting position. ++@end defun ++ ++@defun event-end event ++This returns the ending position of @var{event}. ++ ++If @var{event} is a drag event, this returns the position where the user ++released the mouse button. If @var{event} is a click or button-down ++event, the value is actually the starting position, which is the only ++position such events have. ++@end defun ++ ++@cindex mouse position list, accessing ++ These functions take a position list as described above, and ++return various parts of it. ++ ++@defun posn-window position ++Return the window that @var{position} is in. ++@end defun ++ ++@defun posn-area position ++Return the window area recorded in @var{position}. It returns @code{nil} ++when the event occurred in the text area of the window; otherwise, it ++is a symbol identifying the area in which the event occurred. ++@end defun ++ ++@defun posn-point position ++Return the buffer position in @var{position}. When the event occurred ++in the text area of the window, in a marginal area, or on a fringe, ++this is an integer specifying a buffer position. Otherwise, the value ++is undefined. ++@end defun ++ ++@defun posn-x-y position ++Return the pixel-based x and y coordinates in @var{position}, as a ++cons cell @code{(@var{x} . @var{y})}. These coordinates are relative ++to the window given by @code{posn-window}. ++ ++This example shows how to convert these window-relative coordinates ++into frame-relative coordinates: ++ ++@example ++(defun frame-relative-coordinates (position) ++ "Return frame-relative coordinates from POSITION." ++ (let* ((x-y (posn-x-y position)) ++ (window (posn-window position)) ++ (edges (window-inside-pixel-edges window))) ++ (cons (+ (car x-y) (car edges)) ++ (+ (cdr x-y) (cadr edges))))) ++@end example ++@end defun ++ ++@defun posn-col-row position ++Return the row and column (in units of the frame's default character ++height and width) of @var{position}, as a cons cell @code{(@var{col} . ++@var{row})}. These are computed from the @var{x} and @var{y} values ++actually found in @var{position}. ++@end defun ++ ++@defun posn-actual-col-row position ++Return the actual row and column in @var{position}, as a cons cell ++@code{(@var{col} . @var{row})}. The values are the actual row number ++in the window, and the actual character number in that row. It returns ++@code{nil} if @var{position} does not include actual positions values. ++You can use @code{posn-col-row} to get approximate values. ++@end defun ++ ++@defun posn-string position ++Return the string object in @var{position}, either @code{nil}, or a ++cons cell @code{(@var{string} . @var{string-pos})}. ++@end defun ++ ++@defun posn-image position ++Return the image object in @var{position}, either @code{nil}, or an ++image @code{(image ...)}. ++@end defun ++ ++@defun posn-object position ++Return the image or string object in @var{position}, either ++@code{nil}, an image @code{(image ...)}, or a cons cell ++@code{(@var{string} . @var{string-pos})}. ++@end defun ++ ++@defun posn-object-x-y position ++Return the pixel-based x and y coordinates relative to the upper left ++corner of the object in @var{position} as a cons cell @code{(@var{dx} ++. @var{dy})}. If the @var{position} is a buffer position, return the ++relative position in the character at that position. ++@end defun ++ ++@defun posn-object-width-height position ++Return the pixel width and height of the object in @var{position} as a ++cons cell @code{(@var{width} . @var{height})}. If the @var{position} ++is a buffer position, return the size of the character at that position. ++@end defun ++ ++@cindex timestamp of a mouse event ++@defun posn-timestamp position ++Return the timestamp in @var{position}. This is the time at which the ++event occurred, in milliseconds. ++@end defun ++ ++ These functions compute a position list given particular buffer ++position or screen position. You can access the data in this position ++list with the functions described above. ++ ++@defun posn-at-point &optional pos window ++This function returns a position list for position @var{pos} in ++@var{window}. @var{pos} defaults to point in @var{window}; ++@var{window} defaults to the selected window. ++ ++@code{posn-at-point} returns @code{nil} if @var{pos} is not visible in ++@var{window}. ++@end defun ++ ++@defun posn-at-x-y x y &optional frame-or-window whole ++This function returns position information corresponding to pixel ++coordinates @var{x} and @var{y} in a specified frame or window, ++@var{frame-or-window}, which defaults to the selected window. ++The coordinates @var{x} and @var{y} are relative to the ++frame or window used. ++If @var{whole} is @code{nil}, the coordinates are relative ++to the window text area, otherwise they are relative to ++the entire window area including scroll bars, margins and fringes. ++@end defun ++ ++@node Accessing Scroll ++@subsection Accessing Scroll Bar Events ++@cindex scroll bar events, data in ++ ++ These functions are useful for decoding scroll bar events. ++ ++@defun scroll-bar-event-ratio event ++This function returns the fractional vertical position of a scroll bar ++event within the scroll bar. The value is a cons cell ++@code{(@var{portion} . @var{whole})} containing two integers whose ratio ++is the fractional position. ++@end defun ++ ++@defun scroll-bar-scale ratio total ++This function multiplies (in effect) @var{ratio} by @var{total}, ++rounding the result to an integer. The argument @var{ratio} is not a ++number, but rather a pair @code{(@var{num} . @var{denom})}---typically a ++value returned by @code{scroll-bar-event-ratio}. ++ ++This function is handy for scaling a position on a scroll bar into a ++buffer position. Here's how to do that: ++ ++@example ++(+ (point-min) ++ (scroll-bar-scale ++ (posn-x-y (event-start event)) ++ (- (point-max) (point-min)))) ++@end example ++ ++Recall that scroll bar events have two integers forming a ratio, in place ++of a pair of x and y coordinates. ++@end defun ++ ++@node Strings of Events ++@subsection Putting Keyboard Events in Strings ++@cindex keyboard events in strings ++@cindex strings with keyboard events ++ ++ In most of the places where strings are used, we conceptualize the ++string as containing text characters---the same kind of characters found ++in buffers or files. Occasionally Lisp programs use strings that ++conceptually contain keyboard characters; for example, they may be key ++sequences or keyboard macro definitions. However, storing keyboard ++characters in a string is a complex matter, for reasons of historical ++compatibility, and it is not always possible. ++ ++ We recommend that new programs avoid dealing with these complexities ++by not storing keyboard events in strings. Here is how to do that: ++ ++@itemize @bullet ++@item ++Use vectors instead of strings for key sequences, when you plan to use ++them for anything other than as arguments to @code{lookup-key} and ++@code{define-key}. For example, you can use ++@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and ++@code{this-command-keys-vector} instead of @code{this-command-keys}. ++ ++@item ++Use vectors to write key sequence constants containing meta characters, ++even when passing them directly to @code{define-key}. ++ ++@item ++When you have to look at the contents of a key sequence that might be a ++string, use @code{listify-key-sequence} (@pxref{Event Input Misc}) ++first, to convert it to a list. ++@end itemize ++ ++ The complexities stem from the modifier bits that keyboard input ++characters can include. Aside from the Meta modifier, none of these ++modifier bits can be included in a string, and the Meta modifier is ++allowed only in special cases. ++ ++ The earliest GNU Emacs versions represented meta characters as codes ++in the range of 128 to 255. At that time, the basic character codes ++ranged from 0 to 127, so all keyboard character codes did fit in a ++string. Many Lisp programs used @samp{\M-} in string constants to stand ++for meta characters, especially in arguments to @code{define-key} and ++similar functions, and key sequences and sequences of events were always ++represented as strings. ++ ++ When we added support for larger basic character codes beyond 127, and ++additional modifier bits, we had to change the representation of meta ++characters. Now the flag that represents the Meta modifier in a ++character is ++@tex ++@math{2^{27}} ++@end tex ++@ifnottex ++2**27 ++@end ifnottex ++and such numbers cannot be included in a string. ++ ++ To support programs with @samp{\M-} in string constants, there are ++special rules for including certain meta characters in a string. ++Here are the rules for interpreting a string as a sequence of input ++characters: ++ ++@itemize @bullet ++@item ++If the keyboard character value is in the range of 0 to 127, it can go ++in the string unchanged. ++ ++@item ++The meta variants of those characters, with codes in the range of ++@tex ++@math{2^{27}} ++@end tex ++@ifnottex ++2**27 ++@end ifnottex ++to ++@tex ++@math{2^{27} + 127}, ++@end tex ++@ifnottex ++2**27+127, ++@end ifnottex ++can also go in the string, but you must change their ++numeric values. You must set the ++@tex ++@math{2^{7}} ++@end tex ++@ifnottex ++2**7 ++@end ifnottex ++bit instead of the ++@tex ++@math{2^{27}} ++@end tex ++@ifnottex ++2**27 ++@end ifnottex ++bit, resulting in a value between 128 and 255. Only a unibyte string ++can include these codes. ++ ++@item ++Non-@acronym{ASCII} characters above 256 can be included in a multibyte string. ++ ++@item ++Other keyboard character events cannot fit in a string. This includes ++keyboard events in the range of 128 to 255. ++@end itemize ++ ++ Functions such as @code{read-key-sequence} that construct strings of ++keyboard input characters follow these rules: they construct vectors ++instead of strings, when the events won't fit in a string. ++ ++ When you use the read syntax @samp{\M-} in a string, it produces a ++code in the range of 128 to 255---the same code that you get if you ++modify the corresponding keyboard event to put it in the string. Thus, ++meta events in strings work consistently regardless of how they get into ++the strings. ++ ++ However, most programs would do well to avoid these issues by ++following the recommendations at the beginning of this section. ++ ++@node Reading Input ++@section Reading Input ++@cindex read input ++@cindex keyboard input ++ ++ The editor command loop reads key sequences using the function ++@code{read-key-sequence}, which uses @code{read-event}. These and other ++functions for event input are also available for use in Lisp programs. ++See also @code{momentary-string-display} in @ref{Temporary Displays}, ++and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for ++functions and variables for controlling terminal input modes and ++debugging terminal input. ++ ++ For higher-level input facilities, see @ref{Minibuffers}. ++ ++@menu ++* Key Sequence Input:: How to read one key sequence. ++* Reading One Event:: How to read just one event. ++* Event Mod:: How Emacs modifies events as they are read. ++* Invoking the Input Method:: How reading an event uses the input method. ++* Quoted Character Input:: Asking the user to specify a character. ++* Event Input Misc:: How to reread or throw away input events. ++@end menu ++ ++@node Key Sequence Input ++@subsection Key Sequence Input ++@cindex key sequence input ++ ++ The command loop reads input a key sequence at a time, by calling ++@code{read-key-sequence}. Lisp programs can also call this function; ++for example, @code{describe-key} uses it to read the key to describe. ++ ++@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop ++This function reads a key sequence and returns it as a string or ++vector. It keeps reading events until it has accumulated a complete key ++sequence; that is, enough to specify a non-prefix command using the ++currently active keymaps. (Remember that a key sequence that starts ++with a mouse event is read using the keymaps of the buffer in the ++window that the mouse was in, not the current buffer.) ++ ++If the events are all characters and all can fit in a string, then ++@code{read-key-sequence} returns a string (@pxref{Strings of Events}). ++Otherwise, it returns a vector, since a vector can hold all kinds of ++events---characters, symbols, and lists. The elements of the string or ++vector are the events in the key sequence. ++ ++Reading a key sequence includes translating the events in various ++ways. @xref{Translation Keymaps}. ++ ++The argument @var{prompt} is either a string to be displayed in the ++echo area as a prompt, or @code{nil}, meaning not to display a prompt. ++The argument @var{continue-echo}, if non-@code{nil}, means to echo ++this key as a continuation of the previous key. ++ ++Normally any upper case event is converted to lower case if the ++original event is undefined and the lower case equivalent is defined. ++The argument @var{dont-downcase-last}, if non-@code{nil}, means do not ++convert the last event to lower case. This is appropriate for reading ++a key sequence to be defined. ++ ++The argument @var{switch-frame-ok}, if non-@code{nil}, means that this ++function should process a @code{switch-frame} event if the user ++switches frames before typing anything. If the user switches frames ++in the middle of a key sequence, or at the start of the sequence but ++@var{switch-frame-ok} is @code{nil}, then the event will be put off ++until after the current key sequence. ++ ++The argument @var{command-loop}, if non-@code{nil}, means that this ++key sequence is being read by something that will read commands one ++after another. It should be @code{nil} if the caller will read just ++one key sequence. ++ ++In the following example, Emacs displays the prompt @samp{?} in the ++echo area, and then the user types @kbd{C-x C-f}. ++ ++@example ++(read-key-sequence "?") ++ ++@group ++---------- Echo Area ---------- ++?@kbd{C-x C-f} ++---------- Echo Area ---------- ++ ++ @result{} "^X^F" ++@end group ++@end example ++ ++The function @code{read-key-sequence} suppresses quitting: @kbd{C-g} ++typed while reading with this function works like any other character, ++and does not set @code{quit-flag}. @xref{Quitting}. ++@end defun ++ ++@defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop ++This is like @code{read-key-sequence} except that it always ++returns the key sequence as a vector, never as a string. ++@xref{Strings of Events}. ++@end defun ++ ++@cindex upper case key sequence ++@cindex downcasing in @code{lookup-key} ++@cindex shift-translation ++If an input character is upper-case (or has the shift modifier) and ++has no key binding, but its lower-case equivalent has one, then ++@code{read-key-sequence} converts the character to lower case. Note ++that @code{lookup-key} does not perform case conversion in this way. ++ ++@vindex this-command-keys-shift-translated ++When reading input results in such a @dfn{shift-translation}, Emacs ++sets the variable @code{this-command-keys-shift-translated} to a ++non-@code{nil} value. Lisp programs can examine this variable if they ++need to modify their behavior when invoked by shift-translated keys. ++For example, the function @code{handle-shift-selection} examines the ++value of this variable to determine how to activate or deactivate the ++region (@pxref{The Mark, handle-shift-selection}). ++ ++The function @code{read-key-sequence} also transforms some mouse events. ++It converts unbound drag events into click events, and discards unbound ++button-down events entirely. It also reshuffles focus events and ++miscellaneous window events so that they never appear in a key sequence ++with any other events. ++ ++@cindex @code{header-line} prefix key ++@cindex @code{mode-line} prefix key ++@cindex @code{vertical-line} prefix key ++@cindex @code{horizontal-scroll-bar} prefix key ++@cindex @code{vertical-scroll-bar} prefix key ++@cindex @code{menu-bar} prefix key ++@cindex mouse events, in special parts of frame ++When mouse events occur in special parts of a window, such as a mode ++line or a scroll bar, the event type shows nothing special---it is the ++same symbol that would normally represent that combination of mouse ++button and modifier keys. The information about the window part is kept ++elsewhere in the event---in the coordinates. But ++@code{read-key-sequence} translates this information into imaginary ++``prefix keys,'' all of which are symbols: @code{header-line}, ++@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, ++@code{vertical-line}, and @code{vertical-scroll-bar}. You can define ++meanings for mouse clicks in special window parts by defining key ++sequences using these imaginary prefix keys. ++ ++For example, if you call @code{read-key-sequence} and then click the ++mouse on the window's mode line, you get two events, like this: ++ ++@example ++(read-key-sequence "Click on the mode line: ") ++ @result{} [mode-line ++ (mouse-1 ++ (# mode-line ++ (40 . 63) 5959987))] ++@end example ++ ++@defvar num-input-keys ++@c Emacs 19 feature ++This variable's value is the number of key sequences processed so far in ++this Emacs session. This includes key sequences read from the terminal ++and key sequences read from keyboard macros being executed. ++@end defvar ++ ++@node Reading One Event ++@subsection Reading One Event ++@cindex reading a single event ++@cindex event, reading only one ++ ++ The lowest level functions for command input are those that read a ++single event. ++ ++None of the three functions below suppresses quitting. ++ ++@defun read-event &optional prompt inherit-input-method seconds ++This function reads and returns the next event of command input, waiting ++if necessary until an event is available. Events can come directly from ++the user or from a keyboard macro. ++ ++If the optional argument @var{prompt} is non-@code{nil}, it should be a ++string to display in the echo area as a prompt. Otherwise, ++@code{read-event} does not display any message to indicate it is waiting ++for input; instead, it prompts by echoing: it displays descriptions of ++the events that led to or were read by the current command. @xref{The ++Echo Area}. ++ ++If @var{inherit-input-method} is non-@code{nil}, then the current input ++method (if any) is employed to make it possible to enter a ++non-@acronym{ASCII} character. Otherwise, input method handling is disabled ++for reading this event. ++ ++If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} ++moves the cursor temporarily to the echo area, to the end of any message ++displayed there. Otherwise @code{read-event} does not move the cursor. ++ ++If @var{seconds} is non-@code{nil}, it should be a number specifying ++the maximum time to wait for input, in seconds. If no input arrives ++within that time, @code{read-event} stops waiting and returns ++@code{nil}. A floating-point value for @var{seconds} means to wait ++for a fractional number of seconds. Some systems support only a whole ++number of seconds; on these systems, @var{seconds} is rounded down. ++If @var{seconds} is @code{nil}, @code{read-event} waits as long as ++necessary for input to arrive. ++ ++If @var{seconds} is @code{nil}, Emacs is considered idle while waiting ++for user input to arrive. Idle timers---those created with ++@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this ++period. However, if @var{seconds} is non-@code{nil}, the state of ++idleness remains unchanged. If Emacs is non-idle when ++@code{read-event} is called, it remains non-idle throughout the ++operation of @code{read-event}; if Emacs is idle (which can happen if ++the call happens inside an idle timer), it remains idle. ++ ++If @code{read-event} gets an event that is defined as a help character, ++then in some cases @code{read-event} processes the event directly without ++returning. @xref{Help Functions}. Certain other events, called ++@dfn{special events}, are also processed directly within ++@code{read-event} (@pxref{Special Events}). ++ ++Here is what happens if you call @code{read-event} and then press the ++right-arrow function key: ++ ++@example ++@group ++(read-event) ++ @result{} right ++@end group ++@end example ++@end defun ++ ++@defun read-char &optional prompt inherit-input-method seconds ++This function reads and returns a character of command input. If the ++user generates an event which is not a character (i.e. a mouse click or ++function key event), @code{read-char} signals an error. The arguments ++work as in @code{read-event}. ++ ++In the first example, the user types the character @kbd{1} (@acronym{ASCII} ++code 49). The second example shows a keyboard macro definition that ++calls @code{read-char} from the minibuffer using @code{eval-expression}. ++@code{read-char} reads the keyboard macro's very next character, which ++is @kbd{1}. Then @code{eval-expression} displays its return value in ++the echo area. ++ ++@example ++@group ++(read-char) ++ @result{} 49 ++@end group ++ ++@group ++;; @r{We assume here you use @kbd{M-:} to evaluate this.} ++(symbol-function 'foo) ++ @result{} "^[:(read-char)^M1" ++@end group ++@group ++(execute-kbd-macro 'foo) ++ @print{} 49 ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun read-char-exclusive &optional prompt inherit-input-method seconds ++This function reads and returns a character of command input. If the ++user generates an event which is not a character, ++@code{read-char-exclusive} ignores it and reads another event, until it ++gets a character. The arguments work as in @code{read-event}. ++@end defun ++ ++@defvar num-nonmacro-input-events ++This variable holds the total number of input events received so far ++from the terminal---not counting those generated by keyboard macros. ++@end defvar ++ ++@node Event Mod ++@subsection Modifying and Translating Input Events ++ ++ Emacs modifies every event it reads according to ++@code{extra-keyboard-modifiers}, then translates it through ++@code{keyboard-translate-table} (if applicable), before returning it ++from @code{read-event}. ++ ++@c Emacs 19 feature ++@defvar extra-keyboard-modifiers ++This variable lets Lisp programs ``press'' the modifier keys on the ++keyboard. The value is a character. Only the modifiers of the ++character matter. Each time the user types a keyboard key, it is ++altered as if those modifier keys were held down. For instance, if ++you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all ++keyboard input characters typed during the scope of the binding will ++have the control and meta modifiers applied to them. The character ++@code{?\C-@@}, equivalent to the integer 0, does not count as a control ++character for this purpose, but as a character with no modifiers. ++Thus, setting @code{extra-keyboard-modifiers} to zero cancels any ++modification. ++ ++When using a window system, the program can ``press'' any of the ++modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} ++keys can be virtually pressed. ++ ++Note that this variable applies only to events that really come from ++the keyboard, and has no effect on mouse events or any other events. ++@end defvar ++ ++@defvar keyboard-translate-table ++This terminal-local variable is the translate table for keyboard ++characters. It lets you reshuffle the keys on the keyboard without ++changing any command bindings. Its value is normally a char-table, or ++else @code{nil}. (It can also be a string or vector, but this is ++considered obsolete.) ++ ++If @code{keyboard-translate-table} is a char-table ++(@pxref{Char-Tables}), then each character read from the keyboard is ++looked up in this char-table. If the value found there is ++non-@code{nil}, then it is used instead of the actual input character. ++ ++Note that this translation is the first thing that happens to a ++character after it is read from the terminal. Record-keeping features ++such as @code{recent-keys} and dribble files record the characters after ++translation. ++ ++Note also that this translation is done before the characters are ++supplied to input methods (@pxref{Input Methods}). Use ++@code{translation-table-for-input} (@pxref{Translation of Characters}), ++if you want to translate characters after input methods operate. ++@end defvar ++ ++@defun keyboard-translate from to ++This function modifies @code{keyboard-translate-table} to translate ++character code @var{from} into character code @var{to}. It creates ++the keyboard translate table if necessary. ++@end defun ++ ++ Here's an example of using the @code{keyboard-translate-table} to ++make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste ++operations: ++ ++@example ++(keyboard-translate ?\C-x 'control-x) ++(keyboard-translate ?\C-c 'control-c) ++(keyboard-translate ?\C-v 'control-v) ++(global-set-key [control-x] 'kill-region) ++(global-set-key [control-c] 'kill-ring-save) ++(global-set-key [control-v] 'yank) ++@end example ++ ++@noindent ++On a graphical terminal that supports extended @acronym{ASCII} input, ++you can still get the standard Emacs meanings of one of those ++characters by typing it with the shift key. That makes it a different ++character as far as keyboard translation is concerned, but it has the ++same usual meaning. ++ ++ @xref{Translation Keymaps}, for mechanisms that translate event sequences ++at the level of @code{read-key-sequence}. ++ ++@node Invoking the Input Method ++@subsection Invoking the Input Method ++ ++ The event-reading functions invoke the current input method, if any ++(@pxref{Input Methods}). If the value of @code{input-method-function} ++is non-@code{nil}, it should be a function; when @code{read-event} reads ++a printing character (including @key{SPC}) with no modifier bits, it ++calls that function, passing the character as an argument. ++ ++@defvar input-method-function ++If this is non-@code{nil}, its value specifies the current input method ++function. ++ ++@strong{Warning:} don't bind this variable with @code{let}. It is often ++buffer-local, and if you bind it around reading input (which is exactly ++when you @emph{would} bind it), switching buffers asynchronously while ++Emacs is waiting will cause the value to be restored in the wrong ++buffer. ++@end defvar ++ ++ The input method function should return a list of events which should ++be used as input. (If the list is @code{nil}, that means there is no ++input, so @code{read-event} waits for another event.) These events are ++processed before the events in @code{unread-command-events} ++(@pxref{Event Input Misc}). Events ++returned by the input method function are not passed to the input method ++function again, even if they are printing characters with no modifier ++bits. ++ ++ If the input method function calls @code{read-event} or ++@code{read-key-sequence}, it should bind @code{input-method-function} to ++@code{nil} first, to prevent recursion. ++ ++ The input method function is not called when reading the second and ++subsequent events of a key sequence. Thus, these characters are not ++subject to input method processing. The input method function should ++test the values of @code{overriding-local-map} and ++@code{overriding-terminal-local-map}; if either of these variables is ++non-@code{nil}, the input method should put its argument into a list and ++return that list with no further processing. ++ ++@node Quoted Character Input ++@subsection Quoted Character Input ++@cindex quoted character input ++ ++ You can use the function @code{read-quoted-char} to ask the user to ++specify a character, and allow the user to specify a control or meta ++character conveniently, either literally or as an octal character code. ++The command @code{quoted-insert} uses this function. ++ ++@defun read-quoted-char &optional prompt ++@cindex octal character input ++@cindex control characters, reading ++@cindex nonprinting characters, reading ++This function is like @code{read-char}, except that if the first ++character read is an octal digit (0-7), it reads any number of octal ++digits (but stopping if a non-octal digit is found), and returns the ++character represented by that numeric character code. If the ++character that terminates the sequence of octal digits is @key{RET}, ++it is discarded. Any other terminating character is used as input ++after this function returns. ++ ++Quitting is suppressed when the first character is read, so that the ++user can enter a @kbd{C-g}. @xref{Quitting}. ++ ++If @var{prompt} is supplied, it specifies a string for prompting the ++user. The prompt string is always displayed in the echo area, followed ++by a single @samp{-}. ++ ++In the following example, the user types in the octal number 177 (which ++is 127 in decimal). ++ ++@example ++(read-quoted-char "What character") ++ ++@group ++---------- Echo Area ---------- ++What character @kbd{1 7 7}- ++---------- Echo Area ---------- ++ ++ @result{} 127 ++@end group ++@end example ++@end defun ++ ++@need 2000 ++@node Event Input Misc ++@subsection Miscellaneous Event Input Features ++ ++This section describes how to ``peek ahead'' at events without using ++them up, how to check for pending input, and how to discard pending ++input. See also the function @code{read-passwd} (@pxref{Reading a ++Password}). ++ ++@defvar unread-command-events ++@cindex next input ++@cindex peeking at input ++This variable holds a list of events waiting to be read as command ++input. The events are used in the order they appear in the list, and ++removed one by one as they are used. ++ ++The variable is needed because in some cases a function reads an event ++and then decides not to use it. Storing the event in this variable ++causes it to be processed normally, by the command loop or by the ++functions to read command input. ++ ++@cindex prefix argument unreading ++For example, the function that implements numeric prefix arguments reads ++any number of digits. When it finds a non-digit event, it must unread ++the event so that it can be read normally by the command loop. ++Likewise, incremental search uses this feature to unread events with no ++special meaning in a search, because these events should exit the search ++and then execute normally. ++ ++The reliable and easy way to extract events from a key sequence so as to ++put them in @code{unread-command-events} is to use ++@code{listify-key-sequence} (@pxref{Strings of Events}). ++ ++Normally you add events to the front of this list, so that the events ++most recently unread will be reread first. ++ ++Events read from this list are not normally added to the current ++command's key sequence (as returned by e.g. @code{this-command-keys}), ++as the events will already have been added once as they were read for ++the first time. An element of the form @code{(@code{t} . @var{event})} ++forces @var{event} to be added to the current command's key sequence. ++@end defvar ++ ++@defun listify-key-sequence key ++This function converts the string or vector @var{key} to a list of ++individual events, which you can put in @code{unread-command-events}. ++@end defun ++ ++@defvar unread-command-char ++This variable holds a character to be read as command input. ++A value of -1 means ``empty.'' ++ ++This variable is mostly obsolete now that you can use ++@code{unread-command-events} instead; it exists only to support programs ++written for Emacs versions 18 and earlier. ++@end defvar ++ ++@defun input-pending-p ++@cindex waiting for command key input ++This function determines whether any command input is currently ++available to be read. It returns immediately, with value @code{t} if ++there is available input, @code{nil} otherwise. On rare occasions it ++may return @code{t} when no input is available. ++@end defun ++ ++@defvar last-input-event ++@defvarx last-input-char ++This variable records the last terminal input event read, whether ++as part of a command or explicitly by a Lisp program. ++ ++In the example below, the Lisp program reads the character @kbd{1}, ++@acronym{ASCII} code 49. It becomes the value of @code{last-input-event}, ++while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate ++this expression) remains the value of @code{last-command-event}. ++ ++@example ++@group ++(progn (print (read-char)) ++ (print last-command-event) ++ last-input-event) ++ @print{} 49 ++ @print{} 5 ++ @result{} 49 ++@end group ++@end example ++ ++The alias @code{last-input-char} is obsolete. ++@end defvar ++ ++@defmac while-no-input body@dots{} ++This construct runs the @var{body} forms and returns the value of the ++last one---but only if no input arrives. If any input arrives during ++the execution of the @var{body} forms, it aborts them (working much ++like a quit). The @code{while-no-input} form returns @code{nil} if ++aborted by a real quit, and returns @code{t} if aborted by arrival of ++other input. ++ ++If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil}, ++arrival of input during those parts won't cause an abort until ++the end of that part. ++ ++If you want to be able to distinguish all possible values computed ++by @var{body} from both kinds of abort conditions, write the code ++like this: ++ ++@example ++(while-no-input ++ (list ++ (progn . @var{body}))) ++@end example ++@end defmac ++ ++@defun discard-input ++@cindex flushing input ++@cindex discarding input ++@cindex keyboard macro, terminating ++This function discards the contents of the terminal input buffer and ++cancels any keyboard macro that might be in the process of definition. ++It returns @code{nil}. ++ ++In the following example, the user may type a number of characters right ++after starting the evaluation of the form. After the @code{sleep-for} ++finishes sleeping, @code{discard-input} discards any characters typed ++during the sleep. ++ ++@example ++(progn (sleep-for 2) ++ (discard-input)) ++ @result{} nil ++@end example ++@end defun ++ ++@node Special Events ++@section Special Events ++ ++@cindex special events ++Special events are handled at a very low level---as soon as they are ++read. The @code{read-event} function processes these events itself, and ++never returns them. Instead, it keeps waiting for the first event ++that is not special and returns that one. ++ ++Events that are handled in this way do not echo, they are never grouped ++into key sequences, and they never appear in the value of ++@code{last-command-event} or @code{(this-command-keys)}. They do not ++discard a numeric argument, they cannot be unread with ++@code{unread-command-events}, they may not appear in a keyboard macro, ++and they are not recorded in a keyboard macro while you are defining ++one. ++ ++These events do, however, appear in @code{last-input-event} immediately ++after they are read, and this is the way for the event's definition to ++find the actual event. ++ ++The events types @code{iconify-frame}, @code{make-frame-visible}, ++@code{delete-frame}, @code{drag-n-drop}, and user signals like ++@code{sigusr1} are normally handled in this way. The keymap which ++defines how to handle special events---and which events are special---is ++in the variable @code{special-event-map} (@pxref{Active Keymaps}). ++ ++@node Waiting ++@section Waiting for Elapsed Time or Input ++@cindex waiting ++ ++ The wait functions are designed to wait for a certain amount of time ++to pass or until there is input. For example, you may wish to pause in ++the middle of a computation to allow the user time to view the display. ++@code{sit-for} pauses and updates the screen, and returns immediately if ++input comes in, while @code{sleep-for} pauses without updating the ++screen. ++ ++@defun sit-for seconds &optional nodisp ++This function performs redisplay (provided there is no pending input ++from the user), then waits @var{seconds} seconds, or until input is ++available. The usual purpose of @code{sit-for} is to give the user ++time to read text that you display. The value is @code{t} if ++@code{sit-for} waited the full time with no input arriving ++(@pxref{Event Input Misc}). Otherwise, the value is @code{nil}. ++ ++The argument @var{seconds} need not be an integer. If it is a floating ++point number, @code{sit-for} waits for a fractional number of seconds. ++Some systems support only a whole number of seconds; on these systems, ++@var{seconds} is rounded down. ++ ++The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)}, ++i.e. it requests a redisplay, without any delay, if there is no pending input. ++@xref{Forcing Redisplay}. ++ ++If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not ++redisplay, but it still returns as soon as input is available (or when ++the timeout elapses). ++ ++In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be ++interrupted, even by input from the standard input descriptor. It is ++thus equivalent to @code{sleep-for}, which is described below. ++ ++It is also possible to call @code{sit-for} with three arguments, ++as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})}, ++but that is considered obsolete. ++@end defun ++ ++@defun sleep-for seconds &optional millisec ++This function simply pauses for @var{seconds} seconds without updating ++the display. It pays no attention to available input. It returns ++@code{nil}. ++ ++The argument @var{seconds} need not be an integer. If it is a floating ++point number, @code{sleep-for} waits for a fractional number of seconds. ++Some systems support only a whole number of seconds; on these systems, ++@var{seconds} is rounded down. ++ ++The optional argument @var{millisec} specifies an additional waiting ++period measured in milliseconds. This adds to the period specified by ++@var{seconds}. If the system doesn't support waiting fractions of a ++second, you get an error if you specify nonzero @var{millisec}. ++ ++Use @code{sleep-for} when you wish to guarantee a delay. ++@end defun ++ ++ @xref{Time of Day}, for functions to get the current time. ++ ++@node Quitting ++@section Quitting ++@cindex @kbd{C-g} ++@cindex quitting ++@cindex interrupt Lisp functions ++ ++ Typing @kbd{C-g} while a Lisp function is running causes Emacs to ++@dfn{quit} whatever it is doing. This means that control returns to the ++innermost active command loop. ++ ++ Typing @kbd{C-g} while the command loop is waiting for keyboard input ++does not cause a quit; it acts as an ordinary input character. In the ++simplest case, you cannot tell the difference, because @kbd{C-g} ++normally runs the command @code{keyboard-quit}, whose effect is to quit. ++However, when @kbd{C-g} follows a prefix key, they combine to form an ++undefined key. The effect is to cancel the prefix key as well as any ++prefix argument. ++ ++ In the minibuffer, @kbd{C-g} has a different definition: it aborts out ++of the minibuffer. This means, in effect, that it exits the minibuffer ++and then quits. (Simply quitting would return to the command loop ++@emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit ++directly when the command reader is reading input is so that its meaning ++can be redefined in the minibuffer in this way. @kbd{C-g} following a ++prefix key is not redefined in the minibuffer, and it has its normal ++effect of canceling the prefix key and prefix argument. This too ++would not be possible if @kbd{C-g} always quit directly. ++ ++ When @kbd{C-g} does directly quit, it does so by setting the variable ++@code{quit-flag} to @code{t}. Emacs checks this variable at appropriate ++times and quits if it is not @code{nil}. Setting @code{quit-flag} ++non-@code{nil} in any way thus causes a quit. ++ ++ At the level of C code, quitting cannot happen just anywhere; only at the ++special places that check @code{quit-flag}. The reason for this is ++that quitting at other places might leave an inconsistency in Emacs's ++internal state. Because quitting is delayed until a safe place, quitting ++cannot make Emacs crash. ++ ++ Certain functions such as @code{read-key-sequence} or ++@code{read-quoted-char} prevent quitting entirely even though they wait ++for input. Instead of quitting, @kbd{C-g} serves as the requested ++input. In the case of @code{read-key-sequence}, this serves to bring ++about the special behavior of @kbd{C-g} in the command loop. In the ++case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used ++to quote a @kbd{C-g}. ++ ++@cindex preventing quitting ++ You can prevent quitting for a portion of a Lisp function by binding ++the variable @code{inhibit-quit} to a non-@code{nil} value. Then, ++although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the ++usual result of this---a quit---is prevented. Eventually, ++@code{inhibit-quit} will become @code{nil} again, such as when its ++binding is unwound at the end of a @code{let} form. At that time, if ++@code{quit-flag} is still non-@code{nil}, the requested quit happens ++immediately. This behavior is ideal when you wish to make sure that ++quitting does not happen within a ``critical section'' of the program. ++ ++@cindex @code{read-quoted-char} quitting ++ In some functions (such as @code{read-quoted-char}), @kbd{C-g} is ++handled in a special way that does not involve quitting. This is done ++by reading the input with @code{inhibit-quit} bound to @code{t}, and ++setting @code{quit-flag} to @code{nil} before @code{inhibit-quit} ++becomes @code{nil} again. This excerpt from the definition of ++@code{read-quoted-char} shows how this is done; it also shows that ++normal quitting is permitted after the first character of input. ++ ++@example ++(defun read-quoted-char (&optional prompt) ++ "@dots{}@var{documentation}@dots{}" ++ (let ((message-log-max nil) done (first t) (code 0) char) ++ (while (not done) ++ (let ((inhibit-quit first) ++ @dots{}) ++ (and prompt (message "%s-" prompt)) ++ (setq char (read-event)) ++ (if inhibit-quit (setq quit-flag nil))) ++ @r{@dots{}set the variable @code{code}@dots{}}) ++ code)) ++@end example ++ ++@defvar quit-flag ++If this variable is non-@code{nil}, then Emacs quits immediately, unless ++@code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets ++@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}. ++@end defvar ++ ++@defvar inhibit-quit ++This variable determines whether Emacs should quit when @code{quit-flag} ++is set to a value other than @code{nil}. If @code{inhibit-quit} is ++non-@code{nil}, then @code{quit-flag} has no special effect. ++@end defvar ++ ++@defmac with-local-quit body@dots{} ++This macro executes @var{body} forms in sequence, but allows quitting, at ++least locally, within @var{body} even if @code{inhibit-quit} was ++non-@code{nil} outside this construct. It returns the value of the ++last form in @var{body}, unless exited by quitting, in which case ++it returns @code{nil}. ++ ++If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit}, ++it only executes the @var{body}, and setting @code{quit-flag} causes ++a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so ++that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag} ++triggers a special kind of local quit. This ends the execution of ++@var{body} and exits the @code{with-local-quit} body with ++@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit ++will happen as soon as that is allowed. If @code{quit-flag} is ++already non-@code{nil} at the beginning of @var{body}, the local quit ++happens immediately and the body doesn't execute at all. ++ ++This macro is mainly useful in functions that can be called from ++timers, process filters, process sentinels, @code{pre-command-hook}, ++@code{post-command-hook}, and other places where @code{inhibit-quit} is ++normally bound to @code{t}. ++@end defmac ++ ++@deffn Command keyboard-quit ++This function signals the @code{quit} condition with @code{(signal 'quit ++nil)}. This is the same thing that quitting does. (See @code{signal} ++in @ref{Errors}.) ++@end deffn ++ ++ You can specify a character other than @kbd{C-g} to use for quitting. ++See the function @code{set-input-mode} in @ref{Terminal Input}. ++ ++@node Prefix Command Arguments ++@section Prefix Command Arguments ++@cindex prefix argument ++@cindex raw prefix argument ++@cindex numeric prefix argument ++ ++ Most Emacs commands can use a @dfn{prefix argument}, a number ++specified before the command itself. (Don't confuse prefix arguments ++with prefix keys.) The prefix argument is at all times represented by a ++value, which may be @code{nil}, meaning there is currently no prefix ++argument. Each command may use the prefix argument or ignore it. ++ ++ There are two representations of the prefix argument: @dfn{raw} and ++@dfn{numeric}. The editor command loop uses the raw representation ++internally, and so do the Lisp variables that store the information, but ++commands can request either representation. ++ ++ Here are the possible values of a raw prefix argument: ++ ++@itemize @bullet ++@item ++@code{nil}, meaning there is no prefix argument. Its numeric value is ++1, but numerous commands make a distinction between @code{nil} and the ++integer 1. ++ ++@item ++An integer, which stands for itself. ++ ++@item ++A list of one element, which is an integer. This form of prefix ++argument results from one or a succession of @kbd{C-u}'s with no ++digits. The numeric value is the integer in the list, but some ++commands make a distinction between such a list and an integer alone. ++ ++@item ++The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was ++typed, without following digits. The equivalent numeric value is ++@minus{}1, but some commands make a distinction between the integer ++@minus{}1 and the symbol @code{-}. ++@end itemize ++ ++We illustrate these possibilities by calling the following function with ++various prefixes: ++ ++@example ++@group ++(defun display-prefix (arg) ++ "Display the value of the raw prefix arg." ++ (interactive "P") ++ (message "%s" arg)) ++@end group ++@end example ++ ++@noindent ++Here are the results of calling @code{display-prefix} with various ++raw prefix arguments: ++ ++@example ++ M-x display-prefix @print{} nil ++ ++C-u M-x display-prefix @print{} (4) ++ ++C-u C-u M-x display-prefix @print{} (16) ++ ++C-u 3 M-x display-prefix @print{} 3 ++ ++M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)} ++ ++C-u - M-x display-prefix @print{} - ++ ++M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)} ++ ++C-u - 7 M-x display-prefix @print{} -7 ++ ++M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)} ++@end example ++ ++ Emacs uses two variables to store the prefix argument: ++@code{prefix-arg} and @code{current-prefix-arg}. Commands such as ++@code{universal-argument} that set up prefix arguments for other ++commands store them in @code{prefix-arg}. In contrast, ++@code{current-prefix-arg} conveys the prefix argument to the current ++command, so setting it has no effect on the prefix arguments for future ++commands. ++ ++ Normally, commands specify which representation to use for the prefix ++argument, either numeric or raw, in the @code{interactive} specification. ++(@xref{Using Interactive}.) Alternatively, functions may look at the ++value of the prefix argument directly in the variable ++@code{current-prefix-arg}, but this is less clean. ++ ++@defun prefix-numeric-value arg ++This function returns the numeric meaning of a valid raw prefix argument ++value, @var{arg}. The argument may be a symbol, a number, or a list. ++If it is @code{nil}, the value 1 is returned; if it is @code{-}, the ++value @minus{}1 is returned; if it is a number, that number is returned; ++if it is a list, the @sc{car} of that list (which should be a number) is ++returned. ++@end defun ++ ++@defvar current-prefix-arg ++This variable holds the raw prefix argument for the @emph{current} ++command. Commands may examine it directly, but the usual method for ++accessing it is with @code{(interactive "P")}. ++@end defvar ++ ++@defvar prefix-arg ++The value of this variable is the raw prefix argument for the ++@emph{next} editing command. Commands such as @code{universal-argument} ++that specify prefix arguments for the following command work by setting ++this variable. ++@end defvar ++ ++@defvar last-prefix-arg ++The raw prefix argument value used by the previous command. ++@end defvar ++ ++ The following commands exist to set up prefix arguments for the ++following command. Do not call them for any other reason. ++ ++@deffn Command universal-argument ++This command reads input and specifies a prefix argument for the ++following command. Don't call this command yourself unless you know ++what you are doing. ++@end deffn ++ ++@deffn Command digit-argument arg ++This command adds to the prefix argument for the following command. The ++argument @var{arg} is the raw prefix argument as it was before this ++command; it is used to compute the updated prefix argument. Don't call ++this command yourself unless you know what you are doing. ++@end deffn ++ ++@deffn Command negative-argument arg ++This command adds to the numeric argument for the next command. The ++argument @var{arg} is the raw prefix argument as it was before this ++command; its value is negated to form the new prefix argument. Don't ++call this command yourself unless you know what you are doing. ++@end deffn ++ ++@node Recursive Editing ++@section Recursive Editing ++@cindex recursive command loop ++@cindex recursive editing level ++@cindex command loop, recursive ++ ++ The Emacs command loop is entered automatically when Emacs starts up. ++This top-level invocation of the command loop never exits; it keeps ++running as long as Emacs does. Lisp programs can also invoke the ++command loop. Since this makes more than one activation of the command ++loop, we call it @dfn{recursive editing}. A recursive editing level has ++the effect of suspending whatever command invoked it and permitting the ++user to do arbitrary editing before resuming that command. ++ ++ The commands available during recursive editing are the same ones ++available in the top-level editing loop and defined in the keymaps. ++Only a few special commands exit the recursive editing level; the others ++return to the recursive editing level when they finish. (The special ++commands for exiting are always available, but they do nothing when ++recursive editing is not in progress.) ++ ++ All command loops, including recursive ones, set up all-purpose error ++handlers so that an error in a command run from the command loop will ++not exit the loop. ++ ++@cindex minibuffer input ++ Minibuffer input is a special kind of recursive editing. It has a few ++special wrinkles, such as enabling display of the minibuffer and the ++minibuffer window, but fewer than you might suppose. Certain keys ++behave differently in the minibuffer, but that is only because of the ++minibuffer's local map; if you switch windows, you get the usual Emacs ++commands. ++ ++@cindex @code{throw} example ++@kindex exit ++@cindex exit recursive editing ++@cindex aborting ++ To invoke a recursive editing level, call the function ++@code{recursive-edit}. This function contains the command loop; it also ++contains a call to @code{catch} with tag @code{exit}, which makes it ++possible to exit the recursive editing level by throwing to @code{exit} ++(@pxref{Catch and Throw}). If you throw a value other than @code{t}, ++then @code{recursive-edit} returns normally to the function that called ++it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. ++Throwing a @code{t} value causes @code{recursive-edit} to quit, so that ++control returns to the command loop one level up. This is called ++@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). ++ ++ Most applications should not use recursive editing, except as part of ++using the minibuffer. Usually it is more convenient for the user if you ++change the major mode of the current buffer temporarily to a special ++major mode, which should have a command to go back to the previous mode. ++(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to ++give the user different text to edit ``recursively,'' create and select ++a new buffer in a special mode. In this mode, define a command to ++complete the processing and go back to the previous buffer. (The ++@kbd{m} command in Rmail does this.) ++ ++ Recursive edits are useful in debugging. You can insert a call to ++@code{debug} into a function definition as a sort of breakpoint, so that ++you can look around when the function gets there. @code{debug} invokes ++a recursive edit but also provides the other features of the debugger. ++ ++ Recursive editing levels are also used when you type @kbd{C-r} in ++@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}). ++ ++@defun recursive-edit ++@cindex suspend evaluation ++This function invokes the editor command loop. It is called ++automatically by the initialization of Emacs, to let the user begin ++editing. When called from a Lisp program, it enters a recursive editing ++level. ++ ++If the current buffer is not the same as the selected window's buffer, ++@code{recursive-edit} saves and restores the current buffer. Otherwise, ++if you switch buffers, the buffer you switched to is current after ++@code{recursive-edit} returns. ++ ++In the following example, the function @code{simple-rec} first ++advances point one word, then enters a recursive edit, printing out a ++message in the echo area. The user can then do any editing desired, and ++then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}. ++ ++@example ++(defun simple-rec () ++ (forward-word 1) ++ (message "Recursive edit in progress") ++ (recursive-edit) ++ (forward-word 1)) ++ @result{} simple-rec ++(simple-rec) ++ @result{} nil ++@end example ++@end defun ++ ++@deffn Command exit-recursive-edit ++This function exits from the innermost recursive edit (including ++minibuffer input). Its definition is effectively @code{(throw 'exit ++nil)}. ++@end deffn ++ ++@deffn Command abort-recursive-edit ++This function aborts the command that requested the innermost recursive ++edit (including minibuffer input), by signaling @code{quit} ++after exiting the recursive edit. Its definition is effectively ++@code{(throw 'exit t)}. @xref{Quitting}. ++@end deffn ++ ++@deffn Command top-level ++This function exits all recursive editing levels; it does not return a ++value, as it jumps completely out of any computation directly back to ++the main command loop. ++@end deffn ++ ++@defun recursion-depth ++This function returns the current depth of recursive edits. When no ++recursive edit is active, it returns 0. ++@end defun ++ ++@node Disabling Commands ++@section Disabling Commands ++@cindex disabled command ++ ++ @dfn{Disabling a command} marks the command as requiring user ++confirmation before it can be executed. Disabling is used for commands ++which might be confusing to beginning users, to prevent them from using ++the commands by accident. ++ ++@kindex disabled ++ The low-level mechanism for disabling a command is to put a ++non-@code{nil} @code{disabled} property on the Lisp symbol for the ++command. These properties are normally set up by the user's ++init file (@pxref{Init File}) with Lisp expressions such as this: ++ ++@example ++(put 'upcase-region 'disabled t) ++@end example ++ ++@noindent ++For a few commands, these properties are present by default (you can ++remove them in your init file if you wish). ++ ++ If the value of the @code{disabled} property is a string, the message ++saying the command is disabled includes that string. For example: ++ ++@example ++(put 'delete-region 'disabled ++ "Text deleted this way cannot be yanked back!\n") ++@end example ++ ++ @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on ++what happens when a disabled command is invoked interactively. ++Disabling a command has no effect on calling it as a function from Lisp ++programs. ++ ++@deffn Command enable-command command ++Allow @var{command} (a symbol) to be executed without special ++confirmation from now on, and alter the user's init file (@pxref{Init ++File}) so that this will apply to future sessions. ++@end deffn ++ ++@deffn Command disable-command command ++Require special confirmation to execute @var{command} from now on, and ++alter the user's init file so that this will apply to future sessions. ++@end deffn ++ ++@defvar disabled-command-function ++The value of this variable should be a function. When the user ++invokes a disabled command interactively, this function is called ++instead of the disabled command. It can use @code{this-command-keys} ++to determine what the user typed to run the command, and thus find the ++command itself. ++ ++The value may also be @code{nil}. Then all commands work normally, ++even disabled ones. ++ ++By default, the value is a function that asks the user whether to ++proceed. ++@end defvar ++ ++@node Command History ++@section Command History ++@cindex command history ++@cindex complex command ++@cindex history of commands ++ ++ The command loop keeps a history of the complex commands that have ++been executed, to make it convenient to repeat these commands. A ++@dfn{complex command} is one for which the interactive argument reading ++uses the minibuffer. This includes any @kbd{M-x} command, any ++@kbd{M-:} command, and any command whose @code{interactive} ++specification reads an argument from the minibuffer. Explicit use of ++the minibuffer during the execution of the command itself does not cause ++the command to be considered complex. ++ ++@defvar command-history ++This variable's value is a list of recent complex commands, each ++represented as a form to evaluate. It continues to accumulate all ++complex commands for the duration of the editing session, but when it ++reaches the maximum size (@pxref{Minibuffer History}), the oldest ++elements are deleted as new ones are added. ++ ++@example ++@group ++command-history ++@result{} ((switch-to-buffer "chistory.texi") ++ (describe-key "^X^[") ++ (visit-tags-table "~/emacs/src/") ++ (find-tag "repeat-complex-command")) ++@end group ++@end example ++@end defvar ++ ++ This history list is actually a special case of minibuffer history ++(@pxref{Minibuffer History}), with one special twist: the elements are ++expressions rather than strings. ++ ++ There are a number of commands devoted to the editing and recall of ++previous commands. The commands @code{repeat-complex-command}, and ++@code{list-command-history} are described in the user manual ++(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the ++minibuffer, the usual minibuffer history commands are available. ++ ++@node Keyboard Macros ++@section Keyboard Macros ++@cindex keyboard macros ++ ++ A @dfn{keyboard macro} is a canned sequence of input events that can ++be considered a command and made the definition of a key. The Lisp ++representation of a keyboard macro is a string or vector containing the ++events. Don't confuse keyboard macros with Lisp macros ++(@pxref{Macros}). ++ ++@defun execute-kbd-macro kbdmacro &optional count loopfunc ++This function executes @var{kbdmacro} as a sequence of events. If ++@var{kbdmacro} is a string or vector, then the events in it are executed ++exactly as if they had been input by the user. The sequence is ++@emph{not} expected to be a single key sequence; normally a keyboard ++macro definition consists of several key sequences concatenated. ++ ++If @var{kbdmacro} is a symbol, then its function definition is used in ++place of @var{kbdmacro}. If that is another symbol, this process repeats. ++Eventually the result should be a string or vector. If the result is ++not a symbol, string, or vector, an error is signaled. ++ ++The argument @var{count} is a repeat count; @var{kbdmacro} is executed that ++many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is ++executed once. If it is 0, @var{kbdmacro} is executed over and over until it ++encounters an error or a failing search. ++ ++If @var{loopfunc} is non-@code{nil}, it is a function that is called, ++without arguments, prior to each iteration of the macro. If ++@var{loopfunc} returns @code{nil}, then this stops execution of the macro. ++ ++@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}. ++@end defun ++ ++@defvar executing-kbd-macro ++This variable contains the string or vector that defines the keyboard ++macro that is currently executing. It is @code{nil} if no macro is ++currently executing. A command can test this variable so as to behave ++differently when run from an executing macro. Do not set this variable ++yourself. ++@end defvar ++ ++@defvar defining-kbd-macro ++This variable is non-@code{nil} if and only if a keyboard macro is ++being defined. A command can test this variable so as to behave ++differently while a macro is being defined. The value is ++@code{append} while appending to the definition of an existing macro. ++The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and ++@code{end-kbd-macro} set this variable---do not set it yourself. ++ ++The variable is always local to the current terminal and cannot be ++buffer-local. @xref{Multiple Terminals}. ++@end defvar ++ ++@defvar last-kbd-macro ++This variable is the definition of the most recently defined keyboard ++macro. Its value is a string or vector, or @code{nil}. ++ ++The variable is always local to the current terminal and cannot be ++buffer-local. @xref{Multiple Terminals}. ++@end defvar ++ ++@defvar kbd-macro-termination-hook ++This normal hook (@pxref{Standard Hooks}) is run when a keyboard ++macro terminates, regardless of what caused it to terminate (reaching ++the macro end or an error which ended the macro prematurely). ++@end defvar ++ ++@ignore ++ arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1 ++@end ignore +diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi +new file mode 100644 +index 0000000..227f86f +--- /dev/null ++++ b/doc/lispref/compile.texi +@@ -0,0 +1,802 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/compile ++@node Byte Compilation, Advising Functions, Loading, Top ++@chapter Byte Compilation ++@cindex byte compilation ++@cindex byte-code ++@cindex compilation (Emacs Lisp) ++ ++ Emacs Lisp has a @dfn{compiler} that translates functions written ++in Lisp into a special representation called @dfn{byte-code} that can be ++executed more efficiently. The compiler replaces Lisp function ++definitions with byte-code. When a byte-code function is called, its ++definition is evaluated by the @dfn{byte-code interpreter}. ++ ++ Because the byte-compiled code is evaluated by the byte-code ++interpreter, instead of being executed directly by the machine's ++hardware (as true compiled code is), byte-code is completely ++transportable from machine to machine without recompilation. It is not, ++however, as fast as true compiled code. ++ ++ Compiling a Lisp file with the Emacs byte compiler always reads the ++file as multibyte text, even if Emacs was started with @samp{--unibyte}, ++unless the file specifies otherwise. This is so that compilation gives ++results compatible with running the same file without compilation. ++@xref{Loading Non-ASCII}. ++ ++ In general, any version of Emacs can run byte-compiled code produced ++by recent earlier versions of Emacs, but the reverse is not true. ++ ++@vindex no-byte-compile ++ If you do not want a Lisp file to be compiled, ever, put a file-local ++variable binding for @code{no-byte-compile} into it, like this: ++ ++@example ++;; -*-no-byte-compile: t; -*- ++@end example ++ ++ @xref{Compilation Errors}, for how to investigate errors occurring in ++byte compilation. ++ ++@menu ++* Speed of Byte-Code:: An example of speedup from byte compilation. ++* Compilation Functions:: Byte compilation functions. ++* Docs and Compilation:: Dynamic loading of documentation strings. ++* Dynamic Loading:: Dynamic loading of individual functions. ++* Eval During Compile:: Code to be evaluated when you compile. ++* Compiler Errors:: Handling compiler error messages. ++* Byte-Code Objects:: The data type used for byte-compiled functions. ++* Disassembly:: Disassembling byte-code; how to read byte-code. ++@end menu ++ ++@node Speed of Byte-Code ++@section Performance of Byte-Compiled Code ++ ++ A byte-compiled function is not as efficient as a primitive function ++written in C, but runs much faster than the version written in Lisp. ++Here is an example: ++ ++@example ++@group ++(defun silly-loop (n) ++ "Return time before and after N iterations of a loop." ++ (let ((t1 (current-time-string))) ++ (while (> (setq n (1- n)) ++ 0)) ++ (list t1 (current-time-string)))) ++@result{} silly-loop ++@end group ++ ++@group ++(silly-loop 50000000) ++@result{} ("Wed Mar 11 21:10:19 2009" ++ "Wed Mar 11 21:10:41 2009") ; @r{22 seconds} ++@end group ++ ++@group ++(byte-compile 'silly-loop) ++@result{} @r{[Compiled code not shown]} ++@end group ++ ++@group ++(silly-loop 50000000) ++@result{} ("Wed Mar 11 21:12:26 2009" ++ "Wed Mar 11 21:12:32 2009") ; @r{6 seconds} ++@end group ++@end example ++ ++ In this example, the interpreted code required 22 seconds to run, ++whereas the byte-compiled code required 6 seconds. These results are ++representative, but actual results will vary greatly. ++ ++@node Compilation Functions ++@comment node-name, next, previous, up ++@section The Compilation Functions ++@cindex compilation functions ++ ++ You can byte-compile an individual function or macro definition with ++the @code{byte-compile} function. You can compile a whole file with ++@code{byte-compile-file}, or several files with ++@code{byte-recompile-directory} or @code{batch-byte-compile}. ++ ++ The byte compiler produces error messages and warnings about each file ++in a buffer called @samp{*Compile-Log*}. These report things in your ++program that suggest a problem but are not necessarily erroneous. ++ ++@cindex macro compilation ++ Be careful when writing macro calls in files that you may someday ++byte-compile. Macro calls are expanded when they are compiled, so the ++macros must already be defined for proper compilation. For more ++details, see @ref{Compiling Macros}. If a program does not work the ++same way when compiled as it does when interpreted, erroneous macro ++definitions are one likely cause (@pxref{Problems with Macros}). ++Inline (@code{defsubst}) functions are less troublesome; if you ++compile a call to such a function before its definition is known, the ++call will still work right, it will just run slower. ++ ++ Normally, compiling a file does not evaluate the file's contents or ++load the file. But it does execute any @code{require} calls at top ++level in the file. One way to ensure that necessary macro definitions ++are available during compilation is to require the file that defines ++them (@pxref{Named Features}). To avoid loading the macro definition files ++when someone @emph{runs} the compiled program, write ++@code{eval-when-compile} around the @code{require} calls (@pxref{Eval ++During Compile}). ++ ++@defun byte-compile symbol ++This function byte-compiles the function definition of @var{symbol}, ++replacing the previous definition with the compiled one. The function ++definition of @var{symbol} must be the actual code for the function; ++i.e., the compiler does not follow indirection to another symbol. ++@code{byte-compile} returns the new, compiled definition of ++@var{symbol}. ++ ++ If @var{symbol}'s definition is a byte-code function object, ++@code{byte-compile} does nothing and returns @code{nil}. Lisp records ++only one function definition for any symbol, and if that is already ++compiled, non-compiled code is not available anywhere. So there is no ++way to ``compile the same definition again.'' ++ ++@example ++@group ++(defun factorial (integer) ++ "Compute factorial of INTEGER." ++ (if (= 1 integer) 1 ++ (* integer (factorial (1- integer))))) ++@result{} factorial ++@end group ++ ++@group ++(byte-compile 'factorial) ++@result{} ++#[(integer) ++ "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" ++ [integer 1 * factorial] ++ 4 "Compute factorial of INTEGER."] ++@end group ++@end example ++ ++@noindent ++The result is a byte-code function object. The string it contains is ++the actual byte-code; each character in it is an instruction or an ++operand of an instruction. The vector contains all the constants, ++variable names and function names used by the function, except for ++certain primitives that are coded as special instructions. ++ ++If the argument to @code{byte-compile} is a @code{lambda} expression, ++it returns the corresponding compiled code, but does not store ++it anywhere. ++@end defun ++ ++@deffn Command compile-defun &optional arg ++This command reads the defun containing point, compiles it, and ++evaluates the result. If you use this on a defun that is actually a ++function definition, the effect is to install a compiled version of that ++function. ++ ++@code{compile-defun} normally displays the result of evaluation in the ++echo area, but if @var{arg} is non-@code{nil}, it inserts the result ++in the current buffer after the form it compiled. ++@end deffn ++ ++@deffn Command byte-compile-file filename &optional load ++This function compiles a file of Lisp code named @var{filename} into a ++file of byte-code. The output file's name is made by changing the ++@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in ++@samp{.el}, it adds @samp{.elc} to the end of @var{filename}. ++ ++Compilation works by reading the input file one form at a time. If it ++is a definition of a function or macro, the compiled function or macro ++definition is written out. Other forms are batched together, then each ++batch is compiled, and written so that its compiled code will be ++executed when the file is read. All comments are discarded when the ++input file is read. ++ ++This command returns @code{t} if there were no errors and @code{nil} ++otherwise. When called interactively, it prompts for the file name. ++ ++If @var{load} is non-@code{nil}, this command loads the compiled file ++after compiling it. Interactively, @var{load} is the prefix argument. ++ ++@example ++@group ++% ls -l push* ++-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el ++@end group ++ ++@group ++(byte-compile-file "~/emacs/push.el") ++ @result{} t ++@end group ++ ++@group ++% ls -l push* ++-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el ++-rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc ++@end group ++@end example ++@end deffn ++ ++@deffn Command byte-recompile-directory directory &optional flag force ++@cindex library compilation ++This command recompiles every @samp{.el} file in @var{directory} (or ++its subdirectories) that needs recompilation. A file needs ++recompilation if a @samp{.elc} file exists but is older than the ++@samp{.el} file. ++ ++When a @samp{.el} file has no corresponding @samp{.elc} file, ++@var{flag} says what to do. If it is @code{nil}, this command ignores ++these files. If @var{flag} is 0, it compiles them. If it is neither ++@code{nil} nor 0, it asks the user whether to compile each such file, ++and asks about each subdirectory as well. ++ ++Interactively, @code{byte-recompile-directory} prompts for ++@var{directory} and @var{flag} is the prefix argument. ++ ++If @var{force} is non-@code{nil}, this command recompiles every ++@samp{.el} file that has a @samp{.elc} file. ++ ++The returned value is unpredictable. ++@end deffn ++ ++@defun batch-byte-compile &optional noforce ++This function runs @code{byte-compile-file} on files specified on the ++command line. This function must be used only in a batch execution of ++Emacs, as it kills Emacs on completion. An error in one file does not ++prevent processing of subsequent files, but no output file will be ++generated for it, and the Emacs process will terminate with a nonzero ++status code. ++ ++If @var{noforce} is non-@code{nil}, this function does not recompile ++files that have an up-to-date @samp{.elc} file. ++ ++@example ++% emacs -batch -f batch-byte-compile *.el ++@end example ++@end defun ++ ++@defun byte-code code-string data-vector max-stack ++@cindex byte-code interpreter ++This function actually interprets byte-code. A byte-compiled function ++is actually defined with a body that calls @code{byte-code}. Don't call ++this function yourself---only the byte compiler knows how to generate ++valid calls to this function. ++ ++In Emacs version 18, byte-code was always executed by way of a call to ++the function @code{byte-code}. Nowadays, byte-code is usually executed ++as part of a byte-code function object, and only rarely through an ++explicit call to @code{byte-code}. ++@end defun ++ ++@node Docs and Compilation ++@section Documentation Strings and Compilation ++@cindex dynamic loading of documentation ++ ++ Functions and variables loaded from a byte-compiled file access their ++documentation strings dynamically from the file whenever needed. This ++saves space within Emacs, and makes loading faster because the ++documentation strings themselves need not be processed while loading the ++file. Actual access to the documentation strings becomes slower as a ++result, but this normally is not enough to bother users. ++ ++ Dynamic access to documentation strings does have drawbacks: ++ ++@itemize @bullet ++@item ++If you delete or move the compiled file after loading it, Emacs can no ++longer access the documentation strings for the functions and variables ++in the file. ++ ++@item ++If you alter the compiled file (such as by compiling a new version), ++then further access to documentation strings in this file will ++probably give nonsense results. ++@end itemize ++ ++ If your site installs Emacs following the usual procedures, these ++problems will never normally occur. Installing a new version uses a new ++directory with a different name; as long as the old version remains ++installed, its files will remain unmodified in the places where they are ++expected to be. ++ ++ However, if you have built Emacs yourself and use it from the ++directory where you built it, you will experience this problem ++occasionally if you edit and recompile Lisp files. When it happens, you ++can cure the problem by reloading the file after recompiling it. ++ ++ You can turn off this feature at compile time by setting ++@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful ++mainly if you expect to change the file, and you want Emacs processes ++that have already loaded it to keep working when the file changes. ++You can do this globally, or for one source file by specifying a ++file-local binding for the variable. One way to do that is by adding ++this string to the file's first line: ++ ++@example ++-*-byte-compile-dynamic-docstrings: nil;-*- ++@end example ++ ++@defvar byte-compile-dynamic-docstrings ++If this is non-@code{nil}, the byte compiler generates compiled files ++that are set up for dynamic loading of documentation strings. ++@end defvar ++ ++@cindex @samp{#@@@var{count}} ++@cindex @samp{#$} ++ The dynamic documentation string feature writes compiled files that ++use a special Lisp reader construct, @samp{#@@@var{count}}. This ++construct skips the next @var{count} characters. It also uses the ++@samp{#$} construct, which stands for ``the name of this file, as a ++string.'' It is usually best not to use these constructs in Lisp source ++files, since they are not designed to be clear to humans reading the ++file. ++ ++@node Dynamic Loading ++@section Dynamic Loading of Individual Functions ++ ++@cindex dynamic loading of functions ++@cindex lazy loading ++ When you compile a file, you can optionally enable the @dfn{dynamic ++function loading} feature (also known as @dfn{lazy loading}). With ++dynamic function loading, loading the file doesn't fully read the ++function definitions in the file. Instead, each function definition ++contains a place-holder which refers to the file. The first time each ++function is called, it reads the full definition from the file, to ++replace the place-holder. ++ ++ The advantage of dynamic function loading is that loading the file ++becomes much faster. This is a good thing for a file which contains ++many separate user-callable functions, if using one of them does not ++imply you will probably also use the rest. A specialized mode which ++provides many keyboard commands often has that usage pattern: a user may ++invoke the mode, but use only a few of the commands it provides. ++ ++ The dynamic loading feature has certain disadvantages: ++ ++@itemize @bullet ++@item ++If you delete or move the compiled file after loading it, Emacs can no ++longer load the remaining function definitions not already loaded. ++ ++@item ++If you alter the compiled file (such as by compiling a new version), ++then trying to load any function not already loaded will usually yield ++nonsense results. ++@end itemize ++ ++ These problems will never happen in normal circumstances with ++installed Emacs files. But they are quite likely to happen with Lisp ++files that you are changing. The easiest way to prevent these problems ++is to reload the new compiled file immediately after each recompilation. ++ ++ The byte compiler uses the dynamic function loading feature if the ++variable @code{byte-compile-dynamic} is non-@code{nil} at compilation ++time. Do not set this variable globally, since dynamic loading is ++desirable only for certain files. Instead, enable the feature for ++specific source files with file-local variable bindings. For example, ++you could do it by writing this text in the source file's first line: ++ ++@example ++-*-byte-compile-dynamic: t;-*- ++@end example ++ ++@defvar byte-compile-dynamic ++If this is non-@code{nil}, the byte compiler generates compiled files ++that are set up for dynamic function loading. ++@end defvar ++ ++@defun fetch-bytecode function ++If @var{function} is a byte-code function object, this immediately ++finishes loading the byte code of @var{function} from its ++byte-compiled file, if it is not fully loaded already. Otherwise, ++it does nothing. It always returns @var{function}. ++@end defun ++ ++@node Eval During Compile ++@section Evaluation During Compilation ++ ++ These features permit you to write code to be evaluated during ++compilation of a program. ++ ++@defspec eval-and-compile body@dots{} ++This form marks @var{body} to be evaluated both when you compile the ++containing code and when you run it (whether compiled or not). ++ ++You can get a similar result by putting @var{body} in a separate file ++and referring to that file with @code{require}. That method is ++preferable when @var{body} is large. Effectively @code{require} is ++automatically @code{eval-and-compile}, the package is loaded both when ++compiling and executing. ++ ++@code{autoload} is also effectively @code{eval-and-compile} too. It's ++recognized when compiling, so uses of such a function don't produce ++``not known to be defined'' warnings. ++ ++Most uses of @code{eval-and-compile} are fairly sophisticated. ++ ++If a macro has a helper function to build its result, and that macro ++is used both locally and outside the package, then ++@code{eval-and-compile} should be used to get the helper both when ++compiling and then later when running. ++ ++If functions are defined programmatically (with @code{fset} say), then ++@code{eval-and-compile} can be used to have that done at compile-time ++as well as run-time, so calls to those functions are checked (and ++warnings about ``not known to be defined'' suppressed). ++@end defspec ++ ++@defspec eval-when-compile body@dots{} ++This form marks @var{body} to be evaluated at compile time but not when ++the compiled program is loaded. The result of evaluation by the ++compiler becomes a constant which appears in the compiled program. If ++you load the source file, rather than compiling it, @var{body} is ++evaluated normally. ++ ++@cindex compile-time constant ++If you have a constant that needs some calculation to produce, ++@code{eval-when-compile} can do that at compile-time. For example, ++ ++@lisp ++(defvar my-regexp ++ (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) ++@end lisp ++ ++@cindex macros, at compile time ++If you're using another package, but only need macros from it (the ++byte compiler will expand those), then @code{eval-when-compile} can be ++used to load it for compiling, but not executing. For example, ++ ++@lisp ++(eval-when-compile ++ (require 'my-macro-package)) ;; only macros needed from this ++@end lisp ++ ++The same sort of thing goes for macros and @code{defsubst} functions ++defined locally and only for use within the file. They are needed for ++compiling the file, but in most cases they are not needed for ++execution of the compiled file. For example, ++ ++@lisp ++(eval-when-compile ++ (unless (fboundp 'some-new-thing) ++ (defmacro 'some-new-thing () ++ (compatibility code)))) ++@end lisp ++ ++@noindent ++This is often good for code that's only a fallback for compatibility ++with other versions of Emacs. ++ ++@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common ++Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the ++Common Lisp @samp{#.} reader macro (but not when interpreting) is closer ++to what @code{eval-when-compile} does. ++@end defspec ++ ++@node Compiler Errors ++@section Compiler Errors ++@cindex compiler errors ++ ++ Byte compilation outputs all errors and warnings into the buffer ++@samp{*Compile-Log*}. The messages include file names and line ++numbers that identify the location of the problem. The usual Emacs ++commands for operating on compiler diagnostics work properly on ++these messages. ++ ++ However, the warnings about functions that were used but not ++defined are always ``located'' at the end of the file, so these ++commands won't find the places they are really used. To do that, ++you must search for the function names. ++ ++ You can suppress the compiler warning for calling an undefined ++function @var{func} by conditionalizing the function call on an ++@code{fboundp} test, like this: ++ ++@example ++(if (fboundp '@var{func}) ...(@var{func} ...)...) ++@end example ++ ++@noindent ++The call to @var{func} must be in the @var{then-form} of the ++@code{if}, and @var{func} must appear quoted in the call to ++@code{fboundp}. (This feature operates for @code{cond} as well.) ++ ++ You can tell the compiler that a function is defined using ++@code{declare-function} (@pxref{Declaring Functions}). Likewise, you ++can tell the compiler that a variable is defined using @code{defvar} ++with no initial value. ++ ++ You can suppress the compiler warning for a specific use of an ++undefined variable @var{variable} by conditionalizing its use on a ++@code{boundp} test, like this: ++ ++@example ++(if (boundp '@var{variable}) ...@var{variable}...) ++@end example ++ ++@noindent ++The reference to @var{variable} must be in the @var{then-form} of the ++@code{if}, and @var{variable} must appear quoted in the call to ++@code{boundp}. ++ ++ You can suppress any and all compiler warnings within a certain ++expression using the construct @code{with-no-warnings}: ++ ++@c This is implemented with a defun, but conceptually it is ++@c a special form. ++ ++@defspec with-no-warnings body@dots{} ++In execution, this is equivalent to @code{(progn @var{body}...)}, ++but the compiler does not issue warnings for anything that occurs ++inside @var{body}. ++ ++We recommend that you use this construct around the smallest ++possible piece of code, to avoid missing possible warnings other than one ++one you intend to suppress. ++@end defspec ++ ++ More precise control of warnings is possible by setting the variable ++@code{byte-compile-warnings}. ++ ++@node Byte-Code Objects ++@section Byte-Code Function Objects ++@cindex compiled function ++@cindex byte-code function ++ ++ Byte-compiled functions have a special data type: they are ++@dfn{byte-code function objects}. ++ ++ Internally, a byte-code function object is much like a vector; ++however, the evaluator handles this data type specially when it appears ++as a function to be called. The printed representation for a byte-code ++function object is like that for a vector, with an additional @samp{#} ++before the opening @samp{[}. ++ ++ A byte-code function object must have at least four elements; there is ++no maximum number, but only the first six elements have any normal use. ++They are: ++ ++@table @var ++@item arglist ++The list of argument symbols. ++ ++@item byte-code ++The string containing the byte-code instructions. ++ ++@item constants ++The vector of Lisp objects referenced by the byte code. These include ++symbols used as function names and variable names. ++ ++@item stacksize ++The maximum stack size this function needs. ++ ++@item docstring ++The documentation string (if any); otherwise, @code{nil}. The value may ++be a number or a list, in case the documentation string is stored in a ++file. Use the function @code{documentation} to get the real ++documentation string (@pxref{Accessing Documentation}). ++ ++@item interactive ++The interactive spec (if any). This can be a string or a Lisp ++expression. It is @code{nil} for a function that isn't interactive. ++@end table ++ ++Here's an example of a byte-code function object, in printed ++representation. It is the definition of the command ++@code{backward-sexp}. ++ ++@example ++#[(&optional arg) ++ "^H\204^F^@@\301^P\302^H[!\207" ++ [arg 1 forward-sexp] ++ 2 ++ 254435 ++ "p"] ++@end example ++ ++ The primitive way to create a byte-code object is with ++@code{make-byte-code}: ++ ++@defun make-byte-code &rest elements ++This function constructs and returns a byte-code function object ++with @var{elements} as its elements. ++@end defun ++ ++ You should not try to come up with the elements for a byte-code ++function yourself, because if they are inconsistent, Emacs may crash ++when you call the function. Always leave it to the byte compiler to ++create these objects; it makes the elements consistent (we hope). ++ ++ You can access the elements of a byte-code object using @code{aref}; ++you can also use @code{vconcat} to create a vector with the same ++elements. ++ ++@node Disassembly ++@section Disassembled Byte-Code ++@cindex disassembled byte-code ++ ++ People do not write byte-code; that job is left to the byte ++compiler. But we provide a disassembler to satisfy a cat-like ++curiosity. The disassembler converts the byte-compiled code into ++human-readable form. ++ ++ The byte-code interpreter is implemented as a simple stack machine. ++It pushes values onto a stack of its own, then pops them off to use them ++in calculations whose results are themselves pushed back on the stack. ++When a byte-code function returns, it pops a value off the stack and ++returns it as the value of the function. ++ ++ In addition to the stack, byte-code functions can use, bind, and set ++ordinary Lisp variables, by transferring values between variables and ++the stack. ++ ++@deffn Command disassemble object &optional buffer-or-name ++This command displays the disassembled code for @var{object}. In ++interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, ++the output goes in a buffer named @samp{*Disassemble*}. If ++@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the ++name of an existing buffer. Then the output goes there, at point, and ++point is left before the output. ++ ++The argument @var{object} can be a function name, a lambda expression ++or a byte-code object. If it is a lambda expression, @code{disassemble} ++compiles it and disassembles the resulting compiled code. ++@end deffn ++ ++ Here are two examples of using the @code{disassemble} function. We ++have added explanatory comments to help you relate the byte-code to the ++Lisp source; these do not appear in the output of @code{disassemble}. ++ ++@example ++@group ++(defun factorial (integer) ++ "Compute factorial of an integer." ++ (if (= 1 integer) 1 ++ (* integer (factorial (1- integer))))) ++ @result{} factorial ++@end group ++ ++@group ++(factorial 4) ++ @result{} 24 ++@end group ++ ++@group ++(disassemble 'factorial) ++ @print{} byte-code for factorial: ++ doc: Compute factorial of an integer. ++ args: (integer) ++@end group ++ ++@group ++0 varref integer ; @r{Get the value of @code{integer}} ++ ; @r{and push it onto the stack.} ++1 constant 1 ; @r{Push 1 onto stack.} ++@end group ++ ++@group ++2 eqlsign ; @r{Pop top two values off stack, compare} ++ ; @r{them, and push result onto stack.} ++@end group ++ ++@group ++3 goto-if-nil 1 ; @r{Pop and test top of stack;} ++ ; @r{if @code{nil}, go to 1,} ++ ; @r{else continue.} ++6 constant 1 ; @r{Push 1 onto top of stack.} ++7 return ; @r{Return the top element} ++ ; @r{of the stack.} ++@end group ++ ++@group ++8:1 varref integer ; @r{Push value of @code{integer} onto stack.} ++9 constant factorial ; @r{Push @code{factorial} onto stack.} ++10 varref integer ; @r{Push value of @code{integer} onto stack.} ++11 sub1 ; @r{Pop @code{integer}, decrement value,} ++ ; @r{push new value onto stack.} ++12 call 1 ; @r{Call function @code{factorial} using} ++ ; @r{the first (i.e., the top) element} ++ ; @r{of the stack as the argument;} ++ ; @r{push returned value onto stack.} ++@end group ++ ++@group ++13 mult ; @r{Pop top two values off stack, multiply} ++ ; @r{them, and push result onto stack.} ++14 return ; @r{Return the top element of stack.} ++@end group ++@end example ++ ++The @code{silly-loop} function is somewhat more complex: ++ ++@example ++@group ++(defun silly-loop (n) ++ "Return time before and after N iterations of a loop." ++ (let ((t1 (current-time-string))) ++ (while (> (setq n (1- n)) ++ 0)) ++ (list t1 (current-time-string)))) ++ @result{} silly-loop ++@end group ++ ++@group ++(disassemble 'silly-loop) ++ @print{} byte-code for silly-loop: ++ doc: Return time before and after N iterations of a loop. ++ args: (n) ++ ++0 constant current-time-string ; @r{Push} ++ ; @r{@code{current-time-string}} ++ ; @r{onto top of stack.} ++@end group ++ ++@group ++1 call 0 ; @r{Call @code{current-time-string}} ++ ; @r{with no argument,} ++ ; @r{pushing result onto stack.} ++@end group ++ ++@group ++2 varbind t1 ; @r{Pop stack and bind @code{t1}} ++ ; @r{to popped value.} ++@end group ++ ++@group ++3:1 varref n ; @r{Get value of @code{n} from} ++ ; @r{the environment and push} ++ ; @r{the value onto the stack.} ++4 sub1 ; @r{Subtract 1 from top of stack.} ++@end group ++ ++@group ++5 dup ; @r{Duplicate the top of the stack;} ++ ; @r{i.e., copy the top of} ++ ; @r{the stack and push the} ++ ; @r{copy onto the stack.} ++6 varset n ; @r{Pop the top of the stack,} ++ ; @r{and bind @code{n} to the value.} ++ ++ ; @r{In effect, the sequence @code{dup varset}} ++ ; @r{copies the top of the stack} ++ ; @r{into the value of @code{n}} ++ ; @r{without popping it.} ++@end group ++ ++@group ++7 constant 0 ; @r{Push 0 onto stack.} ++8 gtr ; @r{Pop top two values off stack,} ++ ; @r{test if @var{n} is greater than 0} ++ ; @r{and push result onto stack.} ++@end group ++ ++@group ++9 goto-if-not-nil 1 ; @r{Goto 1 if @code{n} > 0} ++ ; @r{(this continues the while loop)} ++ ; @r{else continue.} ++@end group ++ ++@group ++12 varref t1 ; @r{Push value of @code{t1} onto stack.} ++13 constant current-time-string ; @r{Push @code{current-time-string}} ++ ; @r{onto top of stack.} ++14 call 0 ; @r{Call @code{current-time-string} again.} ++@end group ++ ++@group ++15 unbind 1 ; @r{Unbind @code{t1} in local environment.} ++16 list2 ; @r{Pop top two elements off stack,} ++ ; @r{create a list of them,} ++ ; @r{and push list onto stack.} ++17 return ; @r{Return value of the top of stack.} ++@end group ++@end example ++ ++ ++@ignore ++ arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289 ++@end ignore +diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi +new file mode 100644 +index 0000000..41f844b +--- /dev/null ++++ b/doc/lispref/control.texi +@@ -0,0 +1,1311 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/control ++@node Control Structures, Variables, Evaluation, Top ++@chapter Control Structures ++@cindex special forms for control structures ++@cindex control structures ++ ++ A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}). ++We control the order of execution of these forms by enclosing them in ++@dfn{control structures}. Control structures are special forms which ++control when, whether, or how many times to execute the forms they ++contain. ++ ++@cindex textual order ++ The simplest order of execution is sequential execution: first form ++@var{a}, then form @var{b}, and so on. This is what happens when you ++write several forms in succession in the body of a function, or at top ++level in a file of Lisp code---the forms are executed in the order ++written. We call this @dfn{textual order}. For example, if a function ++body consists of two forms @var{a} and @var{b}, evaluation of the ++function evaluates first @var{a} and then @var{b}. The result of ++evaluating @var{b} becomes the value of the function. ++ ++ Explicit control structures make possible an order of execution other ++than sequential. ++ ++ Emacs Lisp provides several kinds of control structure, including ++other varieties of sequencing, conditionals, iteration, and (controlled) ++jumps---all discussed below. The built-in control structures are ++special forms since their subforms are not necessarily evaluated or not ++evaluated sequentially. You can use macros to define your own control ++structure constructs (@pxref{Macros}). ++ ++@menu ++* Sequencing:: Evaluation in textual order. ++* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. ++* Combining Conditions:: @code{and}, @code{or}, @code{not}. ++* Iteration:: @code{while} loops. ++* Nonlocal Exits:: Jumping out of a sequence. ++@end menu ++ ++@node Sequencing ++@section Sequencing ++ ++ Evaluating forms in the order they appear is the most common way ++control passes from one form to another. In some contexts, such as in a ++function body, this happens automatically. Elsewhere you must use a ++control structure construct to do this: @code{progn}, the simplest ++control construct of Lisp. ++ ++ A @code{progn} special form looks like this: ++ ++@example ++@group ++(progn @var{a} @var{b} @var{c} @dots{}) ++@end group ++@end example ++ ++@noindent ++and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in ++that order. These forms are called the @dfn{body} of the @code{progn} form. ++The value of the last form in the body becomes the value of the entire ++@code{progn}. @code{(progn)} returns @code{nil}. ++ ++@cindex implicit @code{progn} ++ In the early days of Lisp, @code{progn} was the only way to execute ++two or more forms in succession and use the value of the last of them. ++But programmers found they often needed to use a @code{progn} in the ++body of a function, where (at that time) only one form was allowed. So ++the body of a function was made into an ``implicit @code{progn}'': ++several forms are allowed just as in the body of an actual @code{progn}. ++Many other control structures likewise contain an implicit @code{progn}. ++As a result, @code{progn} is not used as much as it was many years ago. ++It is needed now most often inside an @code{unwind-protect}, @code{and}, ++@code{or}, or in the @var{then}-part of an @code{if}. ++ ++@defspec progn forms@dots{} ++This special form evaluates all of the @var{forms}, in textual ++order, returning the result of the final form. ++ ++@example ++@group ++(progn (print "The first form") ++ (print "The second form") ++ (print "The third form")) ++ @print{} "The first form" ++ @print{} "The second form" ++ @print{} "The third form" ++@result{} "The third form" ++@end group ++@end example ++@end defspec ++ ++ Two other control constructs likewise evaluate a series of forms but return ++a different value: ++ ++@defspec prog1 form1 forms@dots{} ++This special form evaluates @var{form1} and all of the @var{forms}, in ++textual order, returning the result of @var{form1}. ++ ++@example ++@group ++(prog1 (print "The first form") ++ (print "The second form") ++ (print "The third form")) ++ @print{} "The first form" ++ @print{} "The second form" ++ @print{} "The third form" ++@result{} "The first form" ++@end group ++@end example ++ ++Here is a way to remove the first element from a list in the variable ++@code{x}, then return the value of that former element: ++ ++@example ++(prog1 (car x) (setq x (cdr x))) ++@end example ++@end defspec ++ ++@defspec prog2 form1 form2 forms@dots{} ++This special form evaluates @var{form1}, @var{form2}, and all of the ++following @var{forms}, in textual order, returning the result of ++@var{form2}. ++ ++@example ++@group ++(prog2 (print "The first form") ++ (print "The second form") ++ (print "The third form")) ++ @print{} "The first form" ++ @print{} "The second form" ++ @print{} "The third form" ++@result{} "The second form" ++@end group ++@end example ++@end defspec ++ ++@node Conditionals ++@section Conditionals ++@cindex conditional evaluation ++ ++ Conditional control structures choose among alternatives. Emacs Lisp ++has four conditional forms: @code{if}, which is much the same as in ++other languages; @code{when} and @code{unless}, which are variants of ++@code{if}; and @code{cond}, which is a generalized case statement. ++ ++@defspec if condition then-form else-forms@dots{} ++@code{if} chooses between the @var{then-form} and the @var{else-forms} ++based on the value of @var{condition}. If the evaluated @var{condition} is ++non-@code{nil}, @var{then-form} is evaluated and the result returned. ++Otherwise, the @var{else-forms} are evaluated in textual order, and the ++value of the last one is returned. (The @var{else} part of @code{if} is ++an example of an implicit @code{progn}. @xref{Sequencing}.) ++ ++If @var{condition} has the value @code{nil}, and no @var{else-forms} are ++given, @code{if} returns @code{nil}. ++ ++@code{if} is a special form because the branch that is not selected is ++never evaluated---it is ignored. Thus, in the example below, ++@code{true} is not printed because @code{print} is never called. ++ ++@example ++@group ++(if nil ++ (print 'true) ++ 'very-false) ++@result{} very-false ++@end group ++@end example ++@end defspec ++ ++@defmac when condition then-forms@dots{} ++This is a variant of @code{if} where there are no @var{else-forms}, ++and possibly several @var{then-forms}. In particular, ++ ++@example ++(when @var{condition} @var{a} @var{b} @var{c}) ++@end example ++ ++@noindent ++is entirely equivalent to ++ ++@example ++(if @var{condition} (progn @var{a} @var{b} @var{c}) nil) ++@end example ++@end defmac ++ ++@defmac unless condition forms@dots{} ++This is a variant of @code{if} where there is no @var{then-form}: ++ ++@example ++(unless @var{condition} @var{a} @var{b} @var{c}) ++@end example ++ ++@noindent ++is entirely equivalent to ++ ++@example ++(if @var{condition} nil ++ @var{a} @var{b} @var{c}) ++@end example ++@end defmac ++ ++@defspec cond clause@dots{} ++@code{cond} chooses among an arbitrary number of alternatives. Each ++@var{clause} in the @code{cond} must be a list. The @sc{car} of this ++list is the @var{condition}; the remaining elements, if any, the ++@var{body-forms}. Thus, a clause looks like this: ++ ++@example ++(@var{condition} @var{body-forms}@dots{}) ++@end example ++ ++@code{cond} tries the clauses in textual order, by evaluating the ++@var{condition} of each clause. If the value of @var{condition} is ++non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its ++@var{body-forms}, and the value of the last of @var{body-forms} becomes ++the value of the @code{cond}. The remaining clauses are ignored. ++ ++If the value of @var{condition} is @code{nil}, the clause ``fails,'' so ++the @code{cond} moves on to the following clause, trying its ++@var{condition}. ++ ++If every @var{condition} evaluates to @code{nil}, so that every clause ++fails, @code{cond} returns @code{nil}. ++ ++A clause may also look like this: ++ ++@example ++(@var{condition}) ++@end example ++ ++@noindent ++Then, if @var{condition} is non-@code{nil} when tested, the value of ++@var{condition} becomes the value of the @code{cond} form. ++ ++The following example has four clauses, which test for the cases where ++the value of @code{x} is a number, string, buffer and symbol, ++respectively: ++ ++@example ++@group ++(cond ((numberp x) x) ++ ((stringp x) x) ++ ((bufferp x) ++ (setq temporary-hack x) ; @r{multiple body-forms} ++ (buffer-name x)) ; @r{in one clause} ++ ((symbolp x) (symbol-value x))) ++@end group ++@end example ++ ++Often we want to execute the last clause whenever none of the previous ++clauses was successful. To do this, we use @code{t} as the ++@var{condition} of the last clause, like this: @code{(t ++@var{body-forms})}. The form @code{t} evaluates to @code{t}, which is ++never @code{nil}, so this clause never fails, provided the @code{cond} ++gets to it at all. ++ ++For example, ++ ++@example ++@group ++(setq a 5) ++(cond ((eq a 'hack) 'foo) ++ (t "default")) ++@result{} "default" ++@end group ++@end example ++ ++@noindent ++This @code{cond} expression returns @code{foo} if the value of @code{a} ++is @code{hack}, and returns the string @code{"default"} otherwise. ++@end defspec ++ ++Any conditional construct can be expressed with @code{cond} or with ++@code{if}. Therefore, the choice between them is a matter of style. ++For example: ++ ++@example ++@group ++(if @var{a} @var{b} @var{c}) ++@equiv{} ++(cond (@var{a} @var{b}) (t @var{c})) ++@end group ++@end example ++ ++@node Combining Conditions ++@section Constructs for Combining Conditions ++ ++ This section describes three constructs that are often used together ++with @code{if} and @code{cond} to express complicated conditions. The ++constructs @code{and} and @code{or} can also be used individually as ++kinds of multiple conditional constructs. ++ ++@defun not condition ++This function tests for the falsehood of @var{condition}. It returns ++@code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise. ++The function @code{not} is identical to @code{null}, and we recommend ++using the name @code{null} if you are testing for an empty list. ++@end defun ++ ++@defspec and conditions@dots{} ++The @code{and} special form tests whether all the @var{conditions} are ++true. It works by evaluating the @var{conditions} one by one in the ++order written. ++ ++If any of the @var{conditions} evaluates to @code{nil}, then the result ++of the @code{and} must be @code{nil} regardless of the remaining ++@var{conditions}; so @code{and} returns @code{nil} right away, ignoring ++the remaining @var{conditions}. ++ ++If all the @var{conditions} turn out non-@code{nil}, then the value of ++the last of them becomes the value of the @code{and} form. Just ++@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate ++because all the @var{conditions} turned out non-@code{nil}. (Think ++about it; which one did not?) ++ ++Here is an example. The first condition returns the integer 1, which is ++not @code{nil}. Similarly, the second condition returns the integer 2, ++which is not @code{nil}. The third condition is @code{nil}, so the ++remaining condition is never evaluated. ++ ++@example ++@group ++(and (print 1) (print 2) nil (print 3)) ++ @print{} 1 ++ @print{} 2 ++@result{} nil ++@end group ++@end example ++ ++Here is a more realistic example of using @code{and}: ++ ++@example ++@group ++(if (and (consp foo) (eq (car foo) 'x)) ++ (message "foo is a list starting with x")) ++@end group ++@end example ++ ++@noindent ++Note that @code{(car foo)} is not executed if @code{(consp foo)} returns ++@code{nil}, thus avoiding an error. ++ ++@code{and} expressions can also be written using either @code{if} or ++@code{cond}. Here's how: ++ ++@example ++@group ++(and @var{arg1} @var{arg2} @var{arg3}) ++@equiv{} ++(if @var{arg1} (if @var{arg2} @var{arg3})) ++@equiv{} ++(cond (@var{arg1} (cond (@var{arg2} @var{arg3})))) ++@end group ++@end example ++@end defspec ++ ++@defspec or conditions@dots{} ++The @code{or} special form tests whether at least one of the ++@var{conditions} is true. It works by evaluating all the ++@var{conditions} one by one in the order written. ++ ++If any of the @var{conditions} evaluates to a non-@code{nil} value, then ++the result of the @code{or} must be non-@code{nil}; so @code{or} returns ++right away, ignoring the remaining @var{conditions}. The value it ++returns is the non-@code{nil} value of the condition just evaluated. ++ ++If all the @var{conditions} turn out @code{nil}, then the @code{or} ++expression returns @code{nil}. Just @code{(or)}, with no ++@var{conditions}, returns @code{nil}, appropriate because all the ++@var{conditions} turned out @code{nil}. (Think about it; which one ++did not?) ++ ++For example, this expression tests whether @code{x} is either ++@code{nil} or the integer zero: ++ ++@example ++(or (eq x nil) (eq x 0)) ++@end example ++ ++Like the @code{and} construct, @code{or} can be written in terms of ++@code{cond}. For example: ++ ++@example ++@group ++(or @var{arg1} @var{arg2} @var{arg3}) ++@equiv{} ++(cond (@var{arg1}) ++ (@var{arg2}) ++ (@var{arg3})) ++@end group ++@end example ++ ++You could almost write @code{or} in terms of @code{if}, but not quite: ++ ++@example ++@group ++(if @var{arg1} @var{arg1} ++ (if @var{arg2} @var{arg2} ++ @var{arg3})) ++@end group ++@end example ++ ++@noindent ++This is not completely equivalent because it can evaluate @var{arg1} or ++@var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2} ++@var{arg3})} never evaluates any argument more than once. ++@end defspec ++ ++@node Iteration ++@section Iteration ++@cindex iteration ++@cindex recursion ++ ++ Iteration means executing part of a program repetitively. For ++example, you might want to repeat some computation once for each element ++of a list, or once for each integer from 0 to @var{n}. You can do this ++in Emacs Lisp with the special form @code{while}: ++ ++@defspec while condition forms@dots{} ++@code{while} first evaluates @var{condition}. If the result is ++non-@code{nil}, it evaluates @var{forms} in textual order. Then it ++reevaluates @var{condition}, and if the result is non-@code{nil}, it ++evaluates @var{forms} again. This process repeats until @var{condition} ++evaluates to @code{nil}. ++ ++There is no limit on the number of iterations that may occur. The loop ++will continue until either @var{condition} evaluates to @code{nil} or ++until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}). ++ ++The value of a @code{while} form is always @code{nil}. ++ ++@example ++@group ++(setq num 0) ++ @result{} 0 ++@end group ++@group ++(while (< num 4) ++ (princ (format "Iteration %d." num)) ++ (setq num (1+ num))) ++ @print{} Iteration 0. ++ @print{} Iteration 1. ++ @print{} Iteration 2. ++ @print{} Iteration 3. ++ @result{} nil ++@end group ++@end example ++ ++To write a ``repeat...until'' loop, which will execute something on each ++iteration and then do the end-test, put the body followed by the ++end-test in a @code{progn} as the first argument of @code{while}, as ++shown here: ++ ++@example ++@group ++(while (progn ++ (forward-line 1) ++ (not (looking-at "^$")))) ++@end group ++@end example ++ ++@noindent ++This moves forward one line and continues moving by lines until it ++reaches an empty line. It is peculiar in that the @code{while} has no ++body, just the end test (which also does the real work of moving point). ++@end defspec ++ ++ The @code{dolist} and @code{dotimes} macros provide convenient ways to ++write two common kinds of loops. ++ ++@defmac dolist (var list [result]) body@dots{} ++This construct executes @var{body} once for each element of ++@var{list}, binding the variable @var{var} locally to hold the current ++element. Then it returns the value of evaluating @var{result}, or ++@code{nil} if @var{result} is omitted. For example, here is how you ++could use @code{dolist} to define the @code{reverse} function: ++ ++@example ++(defun reverse (list) ++ (let (value) ++ (dolist (elt list value) ++ (setq value (cons elt value))))) ++@end example ++@end defmac ++ ++@defmac dotimes (var count [result]) body@dots{} ++This construct executes @var{body} once for each integer from 0 ++(inclusive) to @var{count} (exclusive), binding the variable @var{var} ++to the integer for the current iteration. Then it returns the value ++of evaluating @var{result}, or @code{nil} if @var{result} is omitted. ++Here is an example of using @code{dotimes} to do something 100 times: ++ ++@example ++(dotimes (i 100) ++ (insert "I will not obey absurd orders\n")) ++@end example ++@end defmac ++ ++@node Nonlocal Exits ++@section Nonlocal Exits ++@cindex nonlocal exits ++ ++ A @dfn{nonlocal exit} is a transfer of control from one point in a ++program to another remote point. Nonlocal exits can occur in Emacs Lisp ++as a result of errors; you can also use them under explicit control. ++Nonlocal exits unbind all variable bindings made by the constructs being ++exited. ++ ++@menu ++* Catch and Throw:: Nonlocal exits for the program's own purposes. ++* Examples of Catch:: Showing how such nonlocal exits can be written. ++* Errors:: How errors are signaled and handled. ++* Cleanups:: Arranging to run a cleanup form if an error happens. ++@end menu ++ ++@node Catch and Throw ++@subsection Explicit Nonlocal Exits: @code{catch} and @code{throw} ++ ++ Most control constructs affect only the flow of control within the ++construct itself. The function @code{throw} is the exception to this ++rule of normal program execution: it performs a nonlocal exit on ++request. (There are other exceptions, but they are for error handling ++only.) @code{throw} is used inside a @code{catch}, and jumps back to ++that @code{catch}. For example: ++ ++@example ++@group ++(defun foo-outer () ++ (catch 'foo ++ (foo-inner))) ++ ++(defun foo-inner () ++ @dots{} ++ (if x ++ (throw 'foo t)) ++ @dots{}) ++@end group ++@end example ++ ++@noindent ++The @code{throw} form, if executed, transfers control straight back to ++the corresponding @code{catch}, which returns immediately. The code ++following the @code{throw} is not executed. The second argument of ++@code{throw} is used as the return value of the @code{catch}. ++ ++ The function @code{throw} finds the matching @code{catch} based on the ++first argument: it searches for a @code{catch} whose first argument is ++@code{eq} to the one specified in the @code{throw}. If there is more ++than one applicable @code{catch}, the innermost one takes precedence. ++Thus, in the above example, the @code{throw} specifies @code{foo}, and ++the @code{catch} in @code{foo-outer} specifies the same symbol, so that ++@code{catch} is the applicable one (assuming there is no other matching ++@code{catch} in between). ++ ++ Executing @code{throw} exits all Lisp constructs up to the matching ++@code{catch}, including function calls. When binding constructs such as ++@code{let} or function calls are exited in this way, the bindings are ++unbound, just as they are when these constructs exit normally ++(@pxref{Local Variables}). Likewise, @code{throw} restores the buffer ++and position saved by @code{save-excursion} (@pxref{Excursions}), and ++the narrowing status saved by @code{save-restriction} and the window ++selection saved by @code{save-window-excursion} (@pxref{Window ++Configurations}). It also runs any cleanups established with the ++@code{unwind-protect} special form when it exits that form ++(@pxref{Cleanups}). ++ ++ The @code{throw} need not appear lexically within the @code{catch} ++that it jumps to. It can equally well be called from another function ++called within the @code{catch}. As long as the @code{throw} takes place ++chronologically after entry to the @code{catch}, and chronologically ++before exit from it, it has access to that @code{catch}. This is why ++@code{throw} can be used in commands such as @code{exit-recursive-edit} ++that throw back to the editor command loop (@pxref{Recursive Editing}). ++ ++@cindex CL note---only @code{throw} in Emacs ++@quotation ++@b{Common Lisp note:} Most other versions of Lisp, including Common Lisp, ++have several ways of transferring control nonsequentially: @code{return}, ++@code{return-from}, and @code{go}, for example. Emacs Lisp has only ++@code{throw}. ++@end quotation ++ ++@defspec catch tag body@dots{} ++@cindex tag on run time stack ++@code{catch} establishes a return point for the @code{throw} function. ++The return point is distinguished from other such return points by ++@var{tag}, which may be any Lisp object except @code{nil}. The argument ++@var{tag} is evaluated normally before the return point is established. ++ ++With the return point in effect, @code{catch} evaluates the forms of the ++@var{body} in textual order. If the forms execute normally (without ++error or nonlocal exit) the value of the last body form is returned from ++the @code{catch}. ++ ++If a @code{throw} is executed during the execution of @var{body}, ++specifying the same value @var{tag}, the @code{catch} form exits ++immediately; the value it returns is whatever was specified as the ++second argument of @code{throw}. ++@end defspec ++ ++@defun throw tag value ++The purpose of @code{throw} is to return from a return point previously ++established with @code{catch}. The argument @var{tag} is used to choose ++among the various existing return points; it must be @code{eq} to the value ++specified in the @code{catch}. If multiple return points match @var{tag}, ++the innermost one is used. ++ ++The argument @var{value} is used as the value to return from that ++@code{catch}. ++ ++@kindex no-catch ++If no return point is in effect with tag @var{tag}, then a @code{no-catch} ++error is signaled with data @code{(@var{tag} @var{value})}. ++@end defun ++ ++@node Examples of Catch ++@subsection Examples of @code{catch} and @code{throw} ++ ++ One way to use @code{catch} and @code{throw} is to exit from a doubly ++nested loop. (In most languages, this would be done with a ``go to.'') ++Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} ++varying from 0 to 9: ++ ++@example ++@group ++(defun search-foo () ++ (catch 'loop ++ (let ((i 0)) ++ (while (< i 10) ++ (let ((j 0)) ++ (while (< j 10) ++ (if (foo i j) ++ (throw 'loop (list i j))) ++ (setq j (1+ j)))) ++ (setq i (1+ i)))))) ++@end group ++@end example ++ ++@noindent ++If @code{foo} ever returns non-@code{nil}, we stop immediately and return a ++list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the ++@code{catch} returns normally, and the value is @code{nil}, since that ++is the result of the @code{while}. ++ ++ Here are two tricky examples, slightly different, showing two ++return points at once. First, two return points with the same tag, ++@code{hack}: ++ ++@example ++@group ++(defun catch2 (tag) ++ (catch tag ++ (throw 'hack 'yes))) ++@result{} catch2 ++@end group ++ ++@group ++(catch 'hack ++ (print (catch2 'hack)) ++ 'no) ++@print{} yes ++@result{} no ++@end group ++@end example ++ ++@noindent ++Since both return points have tags that match the @code{throw}, it goes to ++the inner one, the one established in @code{catch2}. Therefore, ++@code{catch2} returns normally with value @code{yes}, and this value is ++printed. Finally the second body form in the outer @code{catch}, which is ++@code{'no}, is evaluated and returned from the outer @code{catch}. ++ ++ Now let's change the argument given to @code{catch2}: ++ ++@example ++@group ++(catch 'hack ++ (print (catch2 'quux)) ++ 'no) ++@result{} yes ++@end group ++@end example ++ ++@noindent ++We still have two return points, but this time only the outer one has ++the tag @code{hack}; the inner one has the tag @code{quux} instead. ++Therefore, @code{throw} makes the outer @code{catch} return the value ++@code{yes}. The function @code{print} is never called, and the ++body-form @code{'no} is never evaluated. ++ ++@node Errors ++@subsection Errors ++@cindex errors ++ ++ When Emacs Lisp attempts to evaluate a form that, for some reason, ++cannot be evaluated, it @dfn{signals} an @dfn{error}. ++ ++ When an error is signaled, Emacs's default reaction is to print an ++error message and terminate execution of the current command. This is ++the right thing to do in most cases, such as if you type @kbd{C-f} at ++the end of the buffer. ++ ++ In complicated programs, simple termination may not be what you want. ++For example, the program may have made temporary changes in data ++structures, or created temporary buffers that should be deleted before ++the program is finished. In such cases, you would use ++@code{unwind-protect} to establish @dfn{cleanup expressions} to be ++evaluated in case of error. (@xref{Cleanups}.) Occasionally, you may ++wish the program to continue execution despite an error in a subroutine. ++In these cases, you would use @code{condition-case} to establish ++@dfn{error handlers} to recover control in case of error. ++ ++ Resist the temptation to use error handling to transfer control from ++one part of the program to another; use @code{catch} and @code{throw} ++instead. @xref{Catch and Throw}. ++ ++@menu ++* Signaling Errors:: How to report an error. ++* Processing of Errors:: What Emacs does when you report an error. ++* Handling Errors:: How you can trap errors and continue execution. ++* Error Symbols:: How errors are classified for trapping them. ++@end menu ++ ++@node Signaling Errors ++@subsubsection How to Signal an Error ++@cindex signaling errors ++ ++ @dfn{Signaling} an error means beginning error processing. Error ++processing normally aborts all or part of the running program and ++returns to a point that is set up to handle the error ++(@pxref{Processing of Errors}). Here we describe how to signal an ++error. ++ ++ Most errors are signaled ``automatically'' within Lisp primitives ++which you call for other purposes, such as if you try to take the ++@sc{car} of an integer or move forward a character at the end of the ++buffer. You can also signal errors explicitly with the functions ++@code{error} and @code{signal}. ++ ++ Quitting, which happens when the user types @kbd{C-g}, is not ++considered an error, but it is handled almost like an error. ++@xref{Quitting}. ++ ++ Every error specifies an error message, one way or another. The ++message should state what is wrong (``File does not exist''), not how ++things ought to be (``File must exist''). The convention in Emacs ++Lisp is that error messages should start with a capital letter, but ++should not end with any sort of punctuation. ++ ++@defun error format-string &rest args ++This function signals an error with an error message constructed by ++applying @code{format} (@pxref{Formatting Strings}) to ++@var{format-string} and @var{args}. ++ ++These examples show typical uses of @code{error}: ++ ++@example ++@group ++(error "That is an error -- try something else") ++ @error{} That is an error -- try something else ++@end group ++ ++@group ++(error "You have committed %d errors" 10) ++ @error{} You have committed 10 errors ++@end group ++@end example ++ ++@code{error} works by calling @code{signal} with two arguments: the ++error symbol @code{error}, and a list containing the string returned by ++@code{format}. ++ ++@strong{Warning:} If you want to use your own string as an error message ++verbatim, don't just write @code{(error @var{string})}. If @var{string} ++contains @samp{%}, it will be interpreted as a format specifier, with ++undesirable results. Instead, use @code{(error "%s" @var{string})}. ++@end defun ++ ++@defun signal error-symbol data ++@anchor{Definition of signal} ++This function signals an error named by @var{error-symbol}. The ++argument @var{data} is a list of additional Lisp objects relevant to ++the circumstances of the error. ++ ++The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol ++bearing a property @code{error-conditions} whose value is a list of ++condition names. This is how Emacs Lisp classifies different sorts of ++errors. @xref{Error Symbols}, for a description of error symbols, ++error conditions and condition names. ++ ++If the error is not handled, the two arguments are used in printing ++the error message. Normally, this error message is provided by the ++@code{error-message} property of @var{error-symbol}. If @var{data} is ++non-@code{nil}, this is followed by a colon and a comma separated list ++of the unevaluated elements of @var{data}. For @code{error}, the ++error message is the @sc{car} of @var{data} (that must be a string). ++Subcategories of @code{file-error} are handled specially. ++ ++The number and significance of the objects in @var{data} depends on ++@var{error-symbol}. For example, with a @code{wrong-type-argument} error, ++there should be two objects in the list: a predicate that describes the type ++that was expected, and the object that failed to fit that type. ++ ++Both @var{error-symbol} and @var{data} are available to any error ++handlers that handle the error: @code{condition-case} binds a local ++variable to a list of the form @code{(@var{error-symbol} .@: ++@var{data})} (@pxref{Handling Errors}). ++ ++The function @code{signal} never returns (though in older Emacs versions ++it could sometimes return). ++ ++@smallexample ++@group ++(signal 'wrong-number-of-arguments '(x y)) ++ @error{} Wrong number of arguments: x, y ++@end group ++ ++@group ++(signal 'no-such-error '("My unknown error condition")) ++ @error{} peculiar error: "My unknown error condition" ++@end group ++@end smallexample ++@end defun ++ ++@cindex CL note---no continuable errors ++@quotation ++@b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp ++concept of continuable errors. ++@end quotation ++ ++@node Processing of Errors ++@subsubsection How Emacs Processes Errors ++ ++When an error is signaled, @code{signal} searches for an active ++@dfn{handler} for the error. A handler is a sequence of Lisp ++expressions designated to be executed if an error happens in part of the ++Lisp program. If the error has an applicable handler, the handler is ++executed, and control resumes following the handler. The handler ++executes in the environment of the @code{condition-case} that ++established it; all functions called within that @code{condition-case} ++have already been exited, and the handler cannot return to them. ++ ++If there is no applicable handler for the error, it terminates the ++current command and returns control to the editor command loop. (The ++command loop has an implicit handler for all kinds of errors.) The ++command loop's handler uses the error symbol and associated data to ++print an error message. You can use the variable ++@code{command-error-function} to control how this is done: ++ ++@defvar command-error-function ++This variable, if non-@code{nil}, specifies a function to use to ++handle errors that return control to the Emacs command loop. The ++function should take three arguments: @var{data}, a list of the same ++form that @code{condition-case} would bind to its variable; ++@var{context}, a string describing the situation in which the error ++occurred, or (more often) @code{nil}; and @var{caller}, the Lisp ++function which called the primitive that signaled the error. ++@end defvar ++ ++@cindex @code{debug-on-error} use ++An error that has no explicit handler may call the Lisp debugger. The ++debugger is enabled if the variable @code{debug-on-error} (@pxref{Error ++Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs ++in the environment of the error, so that you can examine values of ++variables precisely as they were at the time of the error. ++ ++@node Handling Errors ++@subsubsection Writing Code to Handle Errors ++@cindex error handler ++@cindex handling errors ++ ++ The usual effect of signaling an error is to terminate the command ++that is running and return immediately to the Emacs editor command loop. ++You can arrange to trap errors occurring in a part of your program by ++establishing an error handler, with the special form ++@code{condition-case}. A simple example looks like this: ++ ++@example ++@group ++(condition-case nil ++ (delete-file filename) ++ (error nil)) ++@end group ++@end example ++ ++@noindent ++This deletes the file named @var{filename}, catching any error and ++returning @code{nil} if an error occurs@footnote{ ++Actually, you should use @code{ignore-errors} in such a simple case; ++see below.}. ++ ++ The @code{condition-case} construct is often used to trap errors that ++are predictable, such as failure to open a file in a call to ++@code{insert-file-contents}. It is also used to trap errors that are ++totally unpredictable, such as when the program evaluates an expression ++read from the user. ++ ++ The second argument of @code{condition-case} is called the ++@dfn{protected form}. (In the example above, the protected form is a ++call to @code{delete-file}.) The error handlers go into effect when ++this form begins execution and are deactivated when this form returns. ++They remain in effect for all the intervening time. In particular, they ++are in effect during the execution of functions called by this form, in ++their subroutines, and so on. This is a good thing, since, strictly ++speaking, errors can be signaled only by Lisp primitives (including ++@code{signal} and @code{error}) called by the protected form, not by the ++protected form itself. ++ ++ The arguments after the protected form are handlers. Each handler ++lists one or more @dfn{condition names} (which are symbols) to specify ++which errors it will handle. The error symbol specified when an error ++is signaled also defines a list of condition names. A handler applies ++to an error if they have any condition names in common. In the example ++above, there is one handler, and it specifies one condition name, ++@code{error}, which covers all errors. ++ ++ The search for an applicable handler checks all the established handlers ++starting with the most recently established one. Thus, if two nested ++@code{condition-case} forms offer to handle the same error, the inner of ++the two gets to handle it. ++ ++ If an error is handled by some @code{condition-case} form, this ++ordinarily prevents the debugger from being run, even if ++@code{debug-on-error} says this error should invoke the debugger. ++ ++ If you want to be able to debug errors that are caught by a ++@code{condition-case}, set the variable @code{debug-on-signal} to a ++non-@code{nil} value. You can also specify that a particular handler ++should let the debugger run first, by writing @code{debug} among the ++conditions, like this: ++ ++@example ++@group ++(condition-case nil ++ (delete-file filename) ++ ((debug error) nil)) ++@end group ++@end example ++ ++@noindent ++The effect of @code{debug} here is only to prevent ++@code{condition-case} from suppressing the call to the debugger. Any ++given error will invoke the debugger only if @code{debug-on-error} and ++the other usual filtering mechanisms say it should. @xref{Error Debugging}. ++ ++ Once Emacs decides that a certain handler handles the error, it ++returns control to that handler. To do so, Emacs unbinds all variable ++bindings made by binding constructs that are being exited, and ++executes the cleanups of all @code{unwind-protect} forms that are ++being exited. Once control arrives at the handler, the body of the ++handler executes normally. ++ ++ After execution of the handler body, execution returns from the ++@code{condition-case} form. Because the protected form is exited ++completely before execution of the handler, the handler cannot resume ++execution at the point of the error, nor can it examine variable ++bindings that were made within the protected form. All it can do is ++clean up and proceed. ++ ++ Error signaling and handling have some resemblance to @code{throw} and ++@code{catch} (@pxref{Catch and Throw}), but they are entirely separate ++facilities. An error cannot be caught by a @code{catch}, and a ++@code{throw} cannot be handled by an error handler (though using ++@code{throw} when there is no suitable @code{catch} signals an error ++that can be handled). ++ ++@defspec condition-case var protected-form handlers@dots{} ++This special form establishes the error handlers @var{handlers} around ++the execution of @var{protected-form}. If @var{protected-form} executes ++without error, the value it returns becomes the value of the ++@code{condition-case} form; in this case, the @code{condition-case} has ++no effect. The @code{condition-case} form makes a difference when an ++error occurs during @var{protected-form}. ++ ++Each of the @var{handlers} is a list of the form @code{(@var{conditions} ++@var{body}@dots{})}. Here @var{conditions} is an error condition name ++to be handled, or a list of condition names (which can include @code{debug} ++to allow the debugger to run before the handler); @var{body} is one or more ++Lisp expressions to be executed when this handler handles an error. ++Here are examples of handlers: ++ ++@smallexample ++@group ++(error nil) ++ ++(arith-error (message "Division by zero")) ++ ++((arith-error file-error) ++ (message ++ "Either division by zero or failure to open a file")) ++@end group ++@end smallexample ++ ++Each error that occurs has an @dfn{error symbol} that describes what ++kind of error it is. The @code{error-conditions} property of this ++symbol is a list of condition names (@pxref{Error Symbols}). Emacs ++searches all the active @code{condition-case} forms for a handler that ++specifies one or more of these condition names; the innermost matching ++@code{condition-case} handles the error. Within this ++@code{condition-case}, the first applicable handler handles the error. ++ ++After executing the body of the handler, the @code{condition-case} ++returns normally, using the value of the last form in the handler body ++as the overall value. ++ ++@cindex error description ++The argument @var{var} is a variable. @code{condition-case} does not ++bind this variable when executing the @var{protected-form}, only when it ++handles an error. At that time, it binds @var{var} locally to an ++@dfn{error description}, which is a list giving the particulars of the ++error. The error description has the form @code{(@var{error-symbol} ++. @var{data})}. The handler can refer to this list to decide what to ++do. For example, if the error is for failure opening a file, the file ++name is the second element of @var{data}---the third element of the ++error description. ++ ++If @var{var} is @code{nil}, that means no variable is bound. Then the ++error symbol and associated data are not available to the handler. ++@end defspec ++ ++@defun error-message-string error-description ++This function returns the error message string for a given error ++descriptor. It is useful if you want to handle an error by printing the ++usual error message for that error. @xref{Definition of signal}. ++@end defun ++ ++@cindex @code{arith-error} example ++Here is an example of using @code{condition-case} to handle the error ++that results from dividing by zero. The handler displays the error ++message (but without a beep), then returns a very large number. ++ ++@smallexample ++@group ++(defun safe-divide (dividend divisor) ++ (condition-case err ++ ;; @r{Protected form.} ++ (/ dividend divisor) ++@end group ++@group ++ ;; @r{The handler.} ++ (arith-error ; @r{Condition.} ++ ;; @r{Display the usual message for this error.} ++ (message "%s" (error-message-string err)) ++ 1000000))) ++@result{} safe-divide ++@end group ++ ++@group ++(safe-divide 5 0) ++ @print{} Arithmetic error: (arith-error) ++@result{} 1000000 ++@end group ++@end smallexample ++ ++@noindent ++The handler specifies condition name @code{arith-error} so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this @code{condition-case}. Thus, ++ ++@smallexample ++@group ++(safe-divide nil 3) ++ @error{} Wrong type argument: number-or-marker-p, nil ++@end group ++@end smallexample ++ ++ Here is a @code{condition-case} that catches all kinds of errors, ++including those signaled with @code{error}: ++ ++@smallexample ++@group ++(setq baz 34) ++ @result{} 34 ++@end group ++ ++@group ++(condition-case err ++ (if (eq baz 35) ++ t ++ ;; @r{This is a call to the function @code{error}.} ++ (error "Rats! The variable %s was %s, not 35" 'baz baz)) ++ ;; @r{This is the handler; it is not a form.} ++ (error (princ (format "The error was: %s" err)) ++ 2)) ++@print{} The error was: (error "Rats! The variable baz was 34, not 35") ++@result{} 2 ++@end group ++@end smallexample ++ ++@defmac ignore-errors body@dots{} ++This construct executes @var{body}, ignoring any errors that occur ++during its execution. If the execution is without error, ++@code{ignore-errors} returns the value of the last form in @var{body}; ++otherwise, it returns @code{nil}. ++ ++Here's the example at the beginning of this subsection rewritten using ++@code{ignore-errors}: ++ ++@smallexample ++@group ++ (ignore-errors ++ (delete-file filename)) ++@end group ++@end smallexample ++@end defmac ++ ++@node Error Symbols ++@subsubsection Error Symbols and Condition Names ++@cindex error symbol ++@cindex error name ++@cindex condition name ++@cindex user-defined error ++@kindex error-conditions ++ ++ When you signal an error, you specify an @dfn{error symbol} to specify ++the kind of error you have in mind. Each error has one and only one ++error symbol to categorize it. This is the finest classification of ++errors defined by the Emacs Lisp language. ++ ++ These narrow classifications are grouped into a hierarchy of wider ++classes called @dfn{error conditions}, identified by @dfn{condition ++names}. The narrowest such classes belong to the error symbols ++themselves: each error symbol is also a condition name. There are also ++condition names for more extensive classes, up to the condition name ++@code{error} which takes in all kinds of errors (but not @code{quit}). ++Thus, each error has one or more condition names: @code{error}, the ++error symbol if that is distinct from @code{error}, and perhaps some ++intermediate classifications. ++ ++ In order for a symbol to be an error symbol, it must have an ++@code{error-conditions} property which gives a list of condition names. ++This list defines the conditions that this kind of error belongs to. ++(The error symbol itself, and the symbol @code{error}, should always be ++members of this list.) Thus, the hierarchy of condition names is ++defined by the @code{error-conditions} properties of the error symbols. ++Because quitting is not considered an error, the value of the ++@code{error-conditions} property of @code{quit} is just @code{(quit)}. ++ ++@cindex peculiar error ++ In addition to the @code{error-conditions} list, the error symbol ++should have an @code{error-message} property whose value is a string to ++be printed when that error is signaled but not handled. If the ++error symbol has no @code{error-message} property or if the ++@code{error-message} property exists, but is not a string, the error ++message @samp{peculiar error} is used. @xref{Definition of signal}. ++ ++ Here is how we define a new error symbol, @code{new-error}: ++ ++@example ++@group ++(put 'new-error ++ 'error-conditions ++ '(error my-own-errors new-error)) ++@result{} (error my-own-errors new-error) ++@end group ++@group ++(put 'new-error 'error-message "A new error") ++@result{} "A new error" ++@end group ++@end example ++ ++@noindent ++This error has three condition names: @code{new-error}, the narrowest ++classification; @code{my-own-errors}, which we imagine is a wider ++classification; and @code{error}, which is the widest of all. ++ ++ The error string should start with a capital letter but it should ++not end with a period. This is for consistency with the rest of Emacs. ++ ++ Naturally, Emacs will never signal @code{new-error} on its own; only ++an explicit call to @code{signal} (@pxref{Definition of signal}) in ++your code can do this: ++ ++@example ++@group ++(signal 'new-error '(x y)) ++ @error{} A new error: x, y ++@end group ++@end example ++ ++ This error can be handled through any of the three condition names. ++This example handles @code{new-error} and any other errors in the class ++@code{my-own-errors}: ++ ++@example ++@group ++(condition-case foo ++ (bar nil t) ++ (my-own-errors nil)) ++@end group ++@end example ++ ++ The significant way that errors are classified is by their condition ++names---the names used to match errors with handlers. An error symbol ++serves only as a convenient way to specify the intended error message ++and list of condition names. It would be cumbersome to give ++@code{signal} a list of condition names rather than one error symbol. ++ ++ By contrast, using only error symbols without condition names would ++seriously decrease the power of @code{condition-case}. Condition names ++make it possible to categorize errors at various levels of generality ++when you write an error handler. Using error symbols alone would ++eliminate all but the narrowest level of classification. ++ ++ @xref{Standard Errors}, for a list of all the standard error symbols ++and their conditions. ++ ++@node Cleanups ++@subsection Cleaning Up from Nonlocal Exits ++ ++ The @code{unwind-protect} construct is essential whenever you ++temporarily put a data structure in an inconsistent state; it permits ++you to make the data consistent again in the event of an error or ++throw. (Another more specific cleanup construct that is used only for ++changes in buffer contents is the atomic change group; @ref{Atomic ++Changes}.) ++ ++@defspec unwind-protect body-form cleanup-forms@dots{} ++@cindex cleanup forms ++@cindex protected forms ++@cindex error cleanup ++@cindex unwinding ++@code{unwind-protect} executes @var{body-form} with a guarantee that ++the @var{cleanup-forms} will be evaluated if control leaves ++@var{body-form}, no matter how that happens. @var{body-form} may ++complete normally, or execute a @code{throw} out of the ++@code{unwind-protect}, or cause an error; in all cases, the ++@var{cleanup-forms} will be evaluated. ++ ++If @var{body-form} finishes normally, @code{unwind-protect} returns the ++value of @var{body-form}, after it evaluates the @var{cleanup-forms}. ++If @var{body-form} does not finish, @code{unwind-protect} does not ++return any value in the normal sense. ++ ++Only @var{body-form} is protected by the @code{unwind-protect}. If any ++of the @var{cleanup-forms} themselves exits nonlocally (via a ++@code{throw} or an error), @code{unwind-protect} is @emph{not} ++guaranteed to evaluate the rest of them. If the failure of one of the ++@var{cleanup-forms} has the potential to cause trouble, then protect ++it with another @code{unwind-protect} around that form. ++ ++The number of currently active @code{unwind-protect} forms counts, ++together with the number of local variable bindings, against the limit ++@code{max-specpdl-size} (@pxref{Definition of max-specpdl-size,, Local ++Variables}). ++@end defspec ++ ++ For example, here we make an invisible buffer for temporary use, and ++make sure to kill it before finishing: ++ ++@smallexample ++@group ++(save-excursion ++ (let ((buffer (get-buffer-create " *temp*"))) ++ (set-buffer buffer) ++ (unwind-protect ++ @var{body-form} ++ (kill-buffer buffer)))) ++@end group ++@end smallexample ++ ++@noindent ++You might think that we could just as well write @code{(kill-buffer ++(current-buffer))} and dispense with the variable @code{buffer}. ++However, the way shown above is safer, if @var{body-form} happens to ++get an error after switching to a different buffer! (Alternatively, ++you could write another @code{save-excursion} around @var{body-form}, ++to ensure that the temporary buffer becomes current again in time to ++kill it.) ++ ++ Emacs includes a standard macro called @code{with-temp-buffer} which ++expands into more or less the code shown above (@pxref{Definition of ++with-temp-buffer,, Current Buffer}). Several of the macros defined in ++this manual use @code{unwind-protect} in this way. ++ ++@findex ftp-login ++ Here is an actual example derived from an FTP package. It creates a ++process (@pxref{Processes}) to try to establish a connection to a remote ++machine. As the function @code{ftp-login} is highly susceptible to ++numerous problems that the writer of the function cannot anticipate, it ++is protected with a form that guarantees deletion of the process in the ++event of failure. Otherwise, Emacs might fill up with useless ++subprocesses. ++ ++@smallexample ++@group ++(let ((win nil)) ++ (unwind-protect ++ (progn ++ (setq process (ftp-setup-buffer host file)) ++ (if (setq win (ftp-login process host user password)) ++ (message "Logged in") ++ (error "Ftp login failed"))) ++ (or win (and process (delete-process process))))) ++@end group ++@end smallexample ++ ++ This example has a small bug: if the user types @kbd{C-g} to ++quit, and the quit happens immediately after the function ++@code{ftp-setup-buffer} returns but before the variable @code{process} is ++set, the process will not be killed. There is no easy way to fix this bug, ++but at least it is very unlikely. ++ ++@ignore ++ arch-tag: 8abc30d4-4d3a-47f9-b908-e9e971c18c6d ++@end ignore +diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi +new file mode 100644 +index 0000000..8db58ea +--- /dev/null ++++ b/doc/lispref/customize.texi +@@ -0,0 +1,1288 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/customize ++@node Customization, Loading, Macros, Top ++@chapter Writing Customization Definitions ++ ++@cindex customization definitions ++ This chapter describes how to declare user options for customization, ++and also customization groups for classifying them. We use the term ++@dfn{customization item} to include both kinds of customization ++definitions---as well as face definitions (@pxref{Defining Faces}). ++ ++@menu ++* Common Keywords:: Common keyword arguments for all kinds of ++ customization declarations. ++* Group Definitions:: Writing customization group definitions. ++* Variable Definitions:: Declaring user options. ++* Customization Types:: Specifying the type of a user option. ++@end menu ++ ++@node Common Keywords ++@section Common Item Keywords ++ ++@cindex customization keywords ++ All kinds of customization declarations (for variables and groups, and ++for faces) accept keyword arguments for specifying various information. ++This section describes some keywords that apply to all kinds. ++ ++ All of these keywords, except @code{:tag}, can be used more than once ++in a given item. Each use of the keyword has an independent effect. ++The keyword @code{:tag} is an exception because any given item can only ++display one name. ++ ++@table @code ++@item :tag @var{label} ++@kindex tag@r{, customization keyword} ++Use @var{label}, a string, instead of the item's name, to label the ++item in customization menus and buffers. @strong{Don't use a tag ++which is substantially different from the item's real name; that would ++cause confusion.} ++ ++@kindex group@r{, customization keyword} ++@item :group @var{group} ++Put this customization item in group @var{group}. When you use ++@code{:group} in a @code{defgroup}, it makes the new group a subgroup of ++@var{group}. ++ ++If you use this keyword more than once, you can put a single item into ++more than one group. Displaying any of those groups will show this ++item. Please don't overdo this, since the result would be annoying. ++ ++@item :link @var{link-data} ++@kindex link@r{, customization keyword} ++Include an external link after the documentation string for this item. ++This is a sentence containing an active field which references some ++other documentation. ++ ++There are several alternatives you can use for @var{link-data}: ++ ++@table @code ++@item (custom-manual @var{info-node}) ++Link to an Info node; @var{info-node} is a string which specifies the ++node name, as in @code{"(emacs)Top"}. The link appears as ++@samp{[Manual]} in the customization buffer and enters the built-in ++Info reader on @var{info-node}. ++ ++@item (info-link @var{info-node}) ++Like @code{custom-manual} except that the link appears ++in the customization buffer with the Info node name. ++ ++@item (url-link @var{url}) ++Link to a web page; @var{url} is a string which specifies the ++@acronym{URL}. The link appears in the customization buffer as ++@var{url} and invokes the WWW browser specified by ++@code{browse-url-browser-function}. ++ ++@item (emacs-commentary-link @var{library}) ++Link to the commentary section of a library; @var{library} is a string ++which specifies the library name. ++ ++@item (emacs-library-link @var{library}) ++Link to an Emacs Lisp library file; @var{library} is a string which ++specifies the library name. ++ ++@item (file-link @var{file}) ++Link to a file; @var{file} is a string which specifies the name of the ++file to visit with @code{find-file} when the user invokes this link. ++ ++@item (function-link @var{function}) ++Link to the documentation of a function; @var{function} is a string ++which specifies the name of the function to describe with ++@code{describe-function} when the user invokes this link. ++ ++@item (variable-link @var{variable}) ++Link to the documentation of a variable; @var{variable} is a string ++which specifies the name of the variable to describe with ++@code{describe-variable} when the user invokes this link. ++ ++@item (custom-group-link @var{group}) ++Link to another customization group. Invoking it creates a new ++customization buffer for @var{group}. ++@end table ++ ++You can specify the text to use in the customization buffer by adding ++@code{:tag @var{name}} after the first element of the @var{link-data}; ++for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to ++the Emacs manual which appears in the buffer as @samp{foo}. ++ ++An item can have more than one external link; however, most items have ++none at all. ++ ++@item :load @var{file} ++@kindex load@r{, customization keyword} ++Load file @var{file} (a string) before displaying this customization ++item. Loading is done with @code{load-library}, and only if the file is ++not already loaded. ++ ++@item :require @var{feature} ++@kindex require@r{, customization keyword} ++Execute @code{(require '@var{feature})} when your saved customizations ++set the value of this item. @var{feature} should be a symbol. ++ ++The most common reason to use @code{:require} is when a variable enables ++a feature such as a minor mode, and just setting the variable won't have ++any effect unless the code which implements the mode is loaded. ++ ++@item :version @var{version} ++@kindex version@r{, customization keyword} ++This keyword specifies that the item was first introduced in Emacs ++version @var{version}, or that its default value was changed in that ++version. The value @var{version} must be a string. ++ ++@item :package-version '(@var{package} . @var{version}) ++@kindex package-version@r{, customization keyword} ++This keyword specifies that the item was first introduced in ++@var{package} version @var{version}, or that its meaning or default ++value was changed in that version. The value of @var{package} is a ++symbol and @var{version} is a string. ++ ++This keyword takes priority over @code{:version}. ++ ++@var{package} should be the official name of the package, such as MH-E ++or Gnus. If the package @var{package} is released as part of Emacs, ++@var{package} and @var{version} should appear in the value of ++@code{customize-package-emacs-version-alist}. ++@end table ++ ++Packages distributed as part of Emacs that use the ++@code{:package-version} keyword must also update the ++@code{customize-package-emacs-version-alist} variable. ++ ++@defvar customize-package-emacs-version-alist ++This alist provides a mapping for the versions of Emacs that are ++associated with versions of a package listed in the ++@code{:package-version} keyword. Its elements look like this: ++ ++@example ++(@var{package} (@var{pversion} . @var{eversion})@dots{}) ++@end example ++ ++For each @var{package}, which is a symbol, there are one or more ++elements that contain a package version @var{pversion} with an ++associated Emacs version @var{eversion}. These versions are strings. ++For example, the MH-E package updates this alist with the following: ++ ++@smallexample ++(add-to-list 'customize-package-emacs-version-alist ++ '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1") ++ ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1") ++ ("7.4" . "22.1") ("8.0" . "22.1"))) ++@end smallexample ++ ++The value of @var{package} needs to be unique and it needs to match ++the @var{package} value appearing in the @code{:package-version} ++keyword. Since the user might see the value in a error message, a good ++choice is the official name of the package, such as MH-E or Gnus. ++@end defvar ++ ++@node Group Definitions ++@section Defining Customization Groups ++@cindex define customization group ++@cindex customization groups, defining ++ ++ Each Emacs Lisp package should have one main customization group which ++contains all the options, faces and other groups in the package. If the ++package has a small number of options and faces, use just one group and ++put everything in it. When there are more than twelve or so options and ++faces, then you should structure them into subgroups, and put the ++subgroups under the package's main customization group. It is OK to ++put some of the options and faces in the package's main group alongside ++the subgroups. ++ ++ The package's main or only group should be a member of one or more of ++the standard customization groups. (To display the full list of them, ++use @kbd{M-x customize}.) Choose one or more of them (but not too ++many), and add your group to each of them using the @code{:group} ++keyword. ++ ++ The way to declare new customization groups is with @code{defgroup}. ++ ++@defmac defgroup group members doc [keyword value]@dots{} ++Declare @var{group} as a customization group containing @var{members}. ++Do not quote the symbol @var{group}. The argument @var{doc} specifies ++the documentation string for the group. ++ ++The argument @var{members} is a list specifying an initial set of ++customization items to be members of the group. However, most often ++@var{members} is @code{nil}, and you specify the group's members by ++using the @code{:group} keyword when defining those members. ++ ++If you want to specify group members through @var{members}, each element ++should have the form @code{(@var{name} @var{widget})}. Here @var{name} ++is a symbol, and @var{widget} is a widget type for editing that symbol. ++Useful widgets are @code{custom-variable} for a variable, ++@code{custom-face} for a face, and @code{custom-group} for a group. ++ ++When you introduce a new group into Emacs, use the @code{:version} ++keyword in the @code{defgroup}; then you need not use it for ++the individual members of the group. ++ ++In addition to the common keywords (@pxref{Common Keywords}), you can ++also use this keyword in @code{defgroup}: ++ ++@table @code ++@item :prefix @var{prefix} ++@kindex prefix@r{, @code{defgroup} keyword} ++If the name of an item in the group starts with @var{prefix}, then the ++tag for that item is constructed (by default) by omitting @var{prefix}. ++ ++One group can have any number of prefixes. ++@end table ++@end defmac ++ ++ The prefix-discarding feature is currently turned off, which means ++that @code{:prefix} currently has no effect. We did this because we ++found that discarding the specified prefixes often led to confusing ++names for options. This happened because the people who wrote the ++@code{defgroup} definitions for various groups added @code{:prefix} ++keywords whenever they make logical sense---that is, whenever the ++variables in the library have a common prefix. ++ ++ In order to obtain good results with @code{:prefix}, it would be ++necessary to check the specific effects of discarding a particular ++prefix, given the specific items in a group and their names and ++documentation. If the resulting text is not clear, then @code{:prefix} ++should not be used in that case. ++ ++ It should be possible to recheck all the customization groups, delete ++the @code{:prefix} specifications which give unclear results, and then ++turn this feature back on, if someone would like to do the work. ++ ++@node Variable Definitions ++@section Defining Customization Variables ++@cindex define customization options ++@cindex customization variables, how to define ++ ++ Use @code{defcustom} to declare user-customizable variables. ++ ++@defmac defcustom option standard doc [keyword value]@dots{} ++This macro declares @var{option} as a customizable @dfn{user option}. ++You should not quote @var{option}. ++ ++This causes the function @code{user-variable-p} to return @code{t} ++when given @var{option} as an argument. @xref{Defining Variables}. ++The argument @var{doc} specifies the documentation string for the ++variable. (Note that there is no need to start @var{doc} with a ++@samp{*}.) ++ ++The argument @var{standard} is an expression that specifies the ++standard value for @var{option}. Evaluating the @code{defcustom} form ++evaluates @var{standard}, but does not necessarily install the ++standard value. If @var{option} already has a default value, ++@code{defcustom} does not change it. If the user has saved a ++customization for @var{option}, @code{defcustom} installs the user's ++customized value as @var{option}'s default value. If neither of those ++cases applies, @code{defcustom} installs the result of evaluating ++@var{standard} as the default value. ++ ++The expression @var{standard} can be evaluated at various other times, ++too---whenever the customization facility needs to know @var{option}'s ++standard value. So be sure to use an expression which is harmless to ++evaluate at any time. We recommend avoiding backquotes in ++@var{standard}, because they are not expanded when editing the value, ++so list values will appear to have the wrong structure. ++ ++Every @code{defcustom} should specify @code{:group} at least once. ++ ++If you specify the @code{:set} keyword, to make the variable take other ++special actions when set through the customization buffer, the ++variable's documentation string should tell the user specifically how ++to do the same job in hand-written Lisp code. ++ ++When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp ++mode (@code{eval-defun}), a special feature of @code{eval-defun} ++arranges to set the variable unconditionally, without testing whether ++its value is void. (The same feature applies to @code{defvar}.) ++@xref{Defining Variables}. ++ ++If you put a @code{defcustom} in a file that is preloaded at dump time ++(@pxref{Building Emacs}), and the standard value installed for the ++variable at that time might not be correct, use ++@code{custom-reevaluate-setting}, described below, to re-evaluate the ++standard value during or after Emacs startup. ++@end defmac ++ ++ @code{defcustom} accepts the following additional keywords: ++ ++@table @code ++@item :type @var{type} ++Use @var{type} as the data type for this option. It specifies which ++values are legitimate, and how to display the value. ++@xref{Customization Types}, for more information. ++ ++@item :options @var{value-list} ++@kindex options@r{, @code{defcustom} keyword} ++Specify the list of reasonable values for use in this ++option. The user is not restricted to using only these values, but they ++are offered as convenient alternatives. ++ ++This is meaningful only for certain types, currently including ++@code{hook}, @code{plist} and @code{alist}. See the definition of the ++individual types for a description of how to use @code{:options}. ++ ++@item :set @var{setfunction} ++@kindex set@r{, @code{defcustom} keyword} ++Specify @var{setfunction} as the way to change the value of this ++option. The function @var{setfunction} should take two arguments, a ++symbol (the option name) and the new value, and should do whatever is ++necessary to update the value properly for this option (which may not ++mean simply setting the option as a Lisp variable). The default for ++@var{setfunction} is @code{set-default}. ++ ++@item :get @var{getfunction} ++@kindex get@r{, @code{defcustom} keyword} ++Specify @var{getfunction} as the way to extract the value of this ++option. The function @var{getfunction} should take one argument, a ++symbol, and should return whatever customize should use as the ++``current value'' for that symbol (which need not be the symbol's Lisp ++value). The default is @code{default-value}. ++ ++You have to really understand the workings of Custom to use ++@code{:get} correctly. It is meant for values that are treated in ++Custom as variables but are not actually stored in Lisp variables. It ++is almost surely a mistake to specify @code{getfunction} for a value ++that really is stored in a Lisp variable. ++ ++@item :initialize @var{function} ++@kindex initialize@r{, @code{defcustom} keyword} ++@var{function} should be a function used to initialize the variable ++when the @code{defcustom} is evaluated. It should take two arguments, ++the option name (a symbol) and the value. Here are some predefined ++functions meant for use in this way: ++ ++@table @code ++@item custom-initialize-set ++Use the variable's @code{:set} function to initialize the variable, but ++do not reinitialize it if it is already non-void. ++ ++@item custom-initialize-default ++Like @code{custom-initialize-set}, but use the function ++@code{set-default} to set the variable, instead of the variable's ++@code{:set} function. This is the usual choice for a variable whose ++@code{:set} function enables or disables a minor mode; with this choice, ++defining the variable will not call the minor mode function, but ++customizing the variable will do so. ++ ++@item custom-initialize-reset ++Always use the @code{:set} function to initialize the variable. If ++the variable is already non-void, reset it by calling the @code{:set} ++function using the current value (returned by the @code{:get} method). ++This is the default @code{:initialize} function. ++ ++@item custom-initialize-changed ++Use the @code{:set} function to initialize the variable, if it is ++already set or has been customized; otherwise, just use ++@code{set-default}. ++ ++@item custom-initialize-safe-set ++@itemx custom-initialize-safe-default ++These functions behave like @code{custom-initialize-set} ++(@code{custom-initialize-default}, respectively), but catch errors. ++If an error occurs during initialization, they set the variable to ++@code{nil} using @code{set-default}, and throw no error. ++ ++These two functions are only meant for options defined in pre-loaded ++files, where some variables or functions used to compute the option's ++value may not yet be defined. The option normally gets updated in ++@file{startup.el}, ignoring the previously computed value. Because of ++this typical usage, the value which these two functions compute ++normally only matters when, after startup, one unsets the option's ++value and then reevaluates the defcustom. By that time, the necessary ++variables and functions will be defined, so there will not be an error. ++@end table ++ ++@item :risky @var{value} ++@kindex risky@r{, @code{defcustom} keyword} ++Set the variable's @code{risky-local-variable} property to ++@var{value} (@pxref{File Local Variables}). ++ ++@item :safe @var{function} ++@kindex safe@r{, @code{defcustom} keyword} ++Set the variable's @code{safe-local-variable} property to ++@var{function} (@pxref{File Local Variables}). ++ ++@item :set-after @var{variables} ++@kindex set-after@r{, @code{defcustom} keyword} ++When setting variables according to saved customizations, make sure to ++set the variables @var{variables} before this one; in other words, delay ++setting this variable until after those others have been handled. Use ++@code{:set-after} if setting this variable won't work properly unless ++those other variables already have their intended values. ++@end table ++ ++ It is useful to specify the @code{:require} keyword for an option ++that ``turns on'' a certain feature. This causes Emacs to load the ++feature, if it is not already loaded, whenever the option is set. ++@xref{Common Keywords}. Here is an example, from the library ++@file{saveplace.el}: ++ ++@example ++(defcustom save-place nil ++ "Non-nil means automatically save place in each file..." ++ :type 'boolean ++ :require 'saveplace ++ :group 'save-place) ++@end example ++ ++If a customization item has a type such as @code{hook} or ++@code{alist}, which supports @code{:options}, you can add additional ++values to the list from outside the @code{defcustom} declaration by ++calling @code{custom-add-frequent-value}. For example, if you define a ++function @code{my-lisp-mode-initialization} intended to be called from ++@code{emacs-lisp-mode-hook}, you might want to add that to the list of ++reasonable values for @code{emacs-lisp-mode-hook}, but not by editing ++its definition. You can do it thus: ++ ++@example ++(custom-add-frequent-value 'emacs-lisp-mode-hook ++ 'my-lisp-mode-initialization) ++@end example ++ ++@defun custom-add-frequent-value symbol value ++For the customization option @var{symbol}, add @var{value} to the ++list of reasonable values. ++ ++The precise effect of adding a value depends on the customization type ++of @var{symbol}. ++@end defun ++ ++Internally, @code{defcustom} uses the symbol property ++@code{standard-value} to record the expression for the standard value, ++@code{saved-value} to record the value saved by the user with the ++customization buffer, and @code{customized-value} to record the value ++set by the user with the customization buffer, but not saved. ++@xref{Property Lists}. These properties are lists, the car of which ++is an expression that evaluates to the value. ++ ++@defun custom-reevaluate-setting symbol ++This function re-evaluates the standard value of @var{symbol}, which ++should be a user option declared via @code{defcustom}. (If the ++variable was customized, this function re-evaluates the saved value ++instead.) This is useful for customizable options that are defined ++before their value could be computed correctly, such as variables ++defined in packages that are loaded at dump time, but depend on the ++run-time information. For example, the value could be a file whose ++precise name depends on the hierarchy of files when Emacs runs, or a ++name of a program that needs to be searched at run time. ++ ++A good place to put calls to this function is in the function ++@code{command-line} that is run during startup (@pxref{Startup Summary}) ++or in the various hooks it calls. ++@end defun ++ ++@node Customization Types ++@section Customization Types ++ ++@cindex customization types ++ When you define a user option with @code{defcustom}, you must specify ++its @dfn{customization type}. That is a Lisp object which describes (1) ++which values are legitimate and (2) how to display the value in the ++customization buffer for editing. ++ ++@kindex type@r{, @code{defcustom} keyword} ++ You specify the customization type in @code{defcustom} with the ++@code{:type} keyword. The argument of @code{:type} is evaluated, but ++only once when the @code{defcustom} is executed, so it isn't useful ++for the value to vary. Normally we use a quoted constant. For ++example: ++ ++@example ++(defcustom diff-command "diff" ++ "The command to use to run diff." ++ :type '(string) ++ :group 'diff) ++@end example ++ ++ In general, a customization type is a list whose first element is a ++symbol, one of the customization type names defined in the following ++sections. After this symbol come a number of arguments, depending on ++the symbol. Between the type symbol and its arguments, you can ++optionally write keyword-value pairs (@pxref{Type Keywords}). ++ ++ Some type symbols do not use any arguments; those are called ++@dfn{simple types}. For a simple type, if you do not use any ++keyword-value pairs, you can omit the parentheses around the type ++symbol. For example just @code{string} as a customization type is ++equivalent to @code{(string)}. ++ ++ All customization types are implemented as widgets; see @ref{Top, , ++Introduction, widget, The Emacs Widget Library}, for details. ++ ++@menu ++* Simple Types:: Simple customization types: sexp, integer, number, ++ string, file, directory, alist. ++* Composite Types:: Build new types from other types or data. ++* Splicing into Lists:: Splice elements into list with @code{:inline}. ++* Type Keywords:: Keyword-argument pairs in a customization type. ++* Defining New Types:: Give your type a name. ++@end menu ++ ++@node Simple Types ++@subsection Simple Types ++ ++ This section describes all the simple customization types. ++ ++@table @code ++@item sexp ++The value may be any Lisp object that can be printed and read back. You ++can use @code{sexp} as a fall-back for any option, if you don't want to ++take the time to work out a more specific type to use. ++ ++@item integer ++The value must be an integer, and is represented textually ++in the customization buffer. ++ ++@item number ++The value must be a number (floating point or integer), and is ++represented textually in the customization buffer. ++ ++@item float ++The value must be a floating point number, and is represented ++textually in the customization buffer. ++ ++@item string ++The value must be a string, and the customization buffer shows just the ++contents, with no delimiting @samp{"} characters and no quoting with ++@samp{\}. ++ ++@item regexp ++Like @code{string} except that the string must be a valid regular ++expression. ++ ++@item character ++The value must be a character code. A character code is actually an ++integer, but this type shows the value by inserting the character in the ++buffer, rather than by showing the number. ++ ++@item file ++The value must be a file name, and you can do completion with ++@kbd{M-@key{TAB}}. ++ ++@item (file :must-match t) ++The value must be a file name for an existing file, and you can do ++completion with @kbd{M-@key{TAB}}. ++ ++@item directory ++The value must be a directory name, and you can do completion with ++@kbd{M-@key{TAB}}. ++ ++@item hook ++The value must be a list of functions (or a single function, but that is ++obsolete usage). This customization type is used for hook variables. ++You can use the @code{:options} keyword in a hook variable's ++@code{defcustom} to specify a list of functions recommended for use in ++the hook; see @ref{Variable Definitions}. ++ ++@item alist ++The value must be a list of cons-cells, the @sc{car} of each cell ++representing a key, and the @sc{cdr} of the same cell representing an ++associated value. The user can add and delete key/value pairs, and ++edit both the key and the value of each pair. ++ ++You can specify the key and value types like this: ++ ++@smallexample ++(alist :key-type @var{key-type} :value-type @var{value-type}) ++@end smallexample ++ ++@noindent ++where @var{key-type} and @var{value-type} are customization type ++specifications. The default key type is @code{sexp}, and the default ++value type is @code{sexp}. ++ ++The user can add any key matching the specified key type, but you can ++give some keys a preferential treatment by specifying them with the ++@code{:options} (see @ref{Variable Definitions}). The specified keys ++will always be shown in the customize buffer (together with a suitable ++value), with a checkbox to include or exclude or disable the key/value ++pair from the alist. The user will not be able to edit the keys ++specified by the @code{:options} keyword argument. ++ ++The argument to the @code{:options} keywords should be a list of ++specifications for reasonable keys in the alist. Ordinarily, they are ++simply atoms, which stand for themselves as. For example: ++ ++@smallexample ++:options '("foo" "bar" "baz") ++@end smallexample ++ ++@noindent ++specifies that there are three ``known'' keys, namely @code{"foo"}, ++@code{"bar"} and @code{"baz"}, which will always be shown first. ++ ++You may want to restrict the value type for specific keys, for ++example, the value associated with the @code{"bar"} key can only be an ++integer. You can specify this by using a list instead of an atom in ++the list. The first element will specify the key, like before, while ++the second element will specify the value type. For example: ++ ++@smallexample ++:options '("foo" ("bar" integer) "baz") ++@end smallexample ++ ++Finally, you may want to change how the key is presented. By default, ++the key is simply shown as a @code{const}, since the user cannot change ++the special keys specified with the @code{:options} keyword. However, ++you may want to use a more specialized type for presenting the key, like ++@code{function-item} if you know it is a symbol with a function binding. ++This is done by using a customization type specification instead of a ++symbol for the key. ++ ++@smallexample ++:options '("foo" ((function-item some-function) integer) ++ "baz") ++@end smallexample ++ ++Many alists use lists with two elements, instead of cons cells. For ++example, ++ ++@smallexample ++(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) ++ "Each element is a list of the form (KEY VALUE).") ++@end smallexample ++ ++@noindent ++instead of ++ ++@smallexample ++(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) ++ "Each element is a cons-cell (KEY . VALUE).") ++@end smallexample ++ ++Because of the way lists are implemented on top of cons cells, you can ++treat @code{list-alist} in the example above as a cons cell alist, where ++the value type is a list with a single element containing the real ++value. ++ ++@smallexample ++(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) ++ "Each element is a list of the form (KEY VALUE)." ++ :type '(alist :value-type (group integer))) ++@end smallexample ++ ++The @code{group} widget is used here instead of @code{list} only because ++the formatting is better suited for the purpose. ++ ++Similarly, you can have alists with more values associated with each ++key, using variations of this trick: ++ ++@smallexample ++(defcustom person-data '(("brian" 50 t) ++ ("dorith" 55 nil) ++ ("ken" 52 t)) ++ "Alist of basic info about people. ++Each element has the form (NAME AGE MALE-FLAG)." ++ :type '(alist :value-type (group integer boolean))) ++ ++(defcustom pets '(("brian") ++ ("dorith" "dog" "guppy") ++ ("ken" "cat")) ++ "Alist of people's pets. ++In an element (KEY . VALUE), KEY is the person's name, ++and the VALUE is a list of that person's pets." ++ :type '(alist :value-type (repeat string))) ++@end smallexample ++ ++@item plist ++The @code{plist} custom type is similar to the @code{alist} (see above), ++except that the information is stored as a property list, i.e. a list of ++this form: ++ ++@smallexample ++(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{}) ++@end smallexample ++ ++The default @code{:key-type} for @code{plist} is @code{symbol}, ++rather than @code{sexp}. ++ ++@item symbol ++The value must be a symbol. It appears in the customization buffer as ++the name of the symbol. ++ ++@item function ++The value must be either a lambda expression or a function name. When ++it is a function name, you can do completion with @kbd{M-@key{TAB}}. ++ ++@item variable ++The value must be a variable name, and you can do completion with ++@kbd{M-@key{TAB}}. ++ ++@item face ++The value must be a symbol which is a face name, and you can do ++completion with @kbd{M-@key{TAB}}. ++ ++@item boolean ++The value is boolean---either @code{nil} or @code{t}. Note that by ++using @code{choice} and @code{const} together (see the next section), ++you can specify that the value must be @code{nil} or @code{t}, but also ++specify the text to describe each value in a way that fits the specific ++meaning of the alternative. ++ ++@item coding-system ++The value must be a coding-system name, and you can do completion with ++@kbd{M-@key{TAB}}. ++ ++@item color ++The value must be a valid color name, and you can do completion with ++@kbd{M-@key{TAB}}. A sample is provided. ++@end table ++ ++@node Composite Types ++@subsection Composite Types ++@cindex Composite Types (customization) ++ ++ When none of the simple types is appropriate, you can use composite ++types, which build new types from other types or from specified data. ++The specified types or data are called the @dfn{arguments} of the ++composite type. The composite type normally looks like this: ++ ++@example ++(@var{constructor} @var{arguments}@dots{}) ++@end example ++ ++@noindent ++but you can also add keyword-value pairs before the arguments, like ++this: ++ ++@example ++(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{}) ++@end example ++ ++ Here is a table of constructors and how to use them to write ++composite types: ++ ++@table @code ++@item (cons @var{car-type} @var{cdr-type}) ++The value must be a cons cell, its @sc{car} must fit @var{car-type}, and ++its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string ++symbol)} is a customization type which matches values such as ++@code{("foo" . foo)}. ++ ++In the customization buffer, the @sc{car} and the @sc{cdr} are ++displayed and edited separately, each according to the type ++that you specify for it. ++ ++@item (list @var{element-types}@dots{}) ++The value must be a list with exactly as many elements as the ++@var{element-types} given; and each element must fit the ++corresponding @var{element-type}. ++ ++For example, @code{(list integer string function)} describes a list of ++three elements; the first element must be an integer, the second a ++string, and the third a function. ++ ++In the customization buffer, each element is displayed and edited ++separately, according to the type specified for it. ++ ++@item (group @var{element-types}@dots{}) ++This works like @code{list} except for the formatting ++of text in the Custom buffer. @code{list} labels each ++element value with its tag; @code{group} does not. ++ ++@item (vector @var{element-types}@dots{}) ++Like @code{list} except that the value must be a vector instead of a ++list. The elements work the same as in @code{list}. ++ ++@item (choice @var{alternative-types}@dots{}) ++The value must fit at least one of @var{alternative-types}. ++For example, @code{(choice integer string)} allows either an ++integer or a string. ++ ++In the customization buffer, the user selects an alternative ++using a menu, and can then edit the value in the usual way for that ++alternative. ++ ++Normally the strings in this menu are determined automatically from the ++choices; however, you can specify different strings for the menu by ++including the @code{:tag} keyword in the alternatives. For example, if ++an integer stands for a number of spaces, while a string is text to use ++verbatim, you might write the customization type this way, ++ ++@example ++(choice (integer :tag "Number of spaces") ++ (string :tag "Literal text")) ++@end example ++ ++@noindent ++so that the menu offers @samp{Number of spaces} and @samp{Literal text}. ++ ++In any alternative for which @code{nil} is not a valid value, other than ++a @code{const}, you should specify a valid default for that alternative ++using the @code{:value} keyword. @xref{Type Keywords}. ++ ++If some values are covered by more than one of the alternatives, ++customize will choose the first alternative that the value fits. This ++means you should always list the most specific types first, and the ++most general last. Here's an example of proper usage: ++ ++@example ++(choice (const :tag "Off" nil) ++ symbol (sexp :tag "Other")) ++@end example ++ ++@noindent ++This way, the special value @code{nil} is not treated like other ++symbols, and symbols are not treated like other Lisp expressions. ++ ++@item (radio @var{element-types}@dots{}) ++This is similar to @code{choice}, except that the choices are displayed ++using `radio buttons' rather than a menu. This has the advantage of ++displaying documentation for the choices when applicable and so is often ++a good choice for a choice between constant functions ++(@code{function-item} customization types). ++ ++@item (const @var{value}) ++The value must be @var{value}---nothing else is allowed. ++ ++The main use of @code{const} is inside of @code{choice}. For example, ++@code{(choice integer (const nil))} allows either an integer or ++@code{nil}. ++ ++@code{:tag} is often used with @code{const}, inside of @code{choice}. ++For example, ++ ++@example ++(choice (const :tag "Yes" t) ++ (const :tag "No" nil) ++ (const :tag "Ask" foo)) ++@end example ++ ++@noindent ++describes a variable for which @code{t} means yes, @code{nil} means no, ++and @code{foo} means ``ask.'' ++ ++@item (other @var{value}) ++This alternative can match any Lisp value, but if the user chooses this ++alternative, that selects the value @var{value}. ++ ++The main use of @code{other} is as the last element of @code{choice}. ++For example, ++ ++@example ++(choice (const :tag "Yes" t) ++ (const :tag "No" nil) ++ (other :tag "Ask" foo)) ++@end example ++ ++@noindent ++describes a variable for which @code{t} means yes, @code{nil} means no, ++and anything else means ``ask.'' If the user chooses @samp{Ask} from ++the menu of alternatives, that specifies the value @code{foo}; but any ++other value (not @code{t}, @code{nil} or @code{foo}) displays as ++@samp{Ask}, just like @code{foo}. ++ ++@item (function-item @var{function}) ++Like @code{const}, but used for values which are functions. This ++displays the documentation string as well as the function name. ++The documentation string is either the one you specify with ++@code{:doc}, or @var{function}'s own documentation string. ++ ++@item (variable-item @var{variable}) ++Like @code{const}, but used for values which are variable names. This ++displays the documentation string as well as the variable name. The ++documentation string is either the one you specify with @code{:doc}, or ++@var{variable}'s own documentation string. ++ ++@item (set @var{types}@dots{}) ++The value must be a list, and each element of the list must match one of ++the @var{types} specified. ++ ++This appears in the customization buffer as a checklist, so that each of ++@var{types} may have either one corresponding element or none. It is ++not possible to specify two different elements that match the same one ++of @var{types}. For example, @code{(set integer symbol)} allows one ++integer and/or one symbol in the list; it does not allow multiple ++integers or multiple symbols. As a result, it is rare to use ++nonspecific types such as @code{integer} in a @code{set}. ++ ++Most often, the @var{types} in a @code{set} are @code{const} types, as ++shown here: ++ ++@example ++(set (const :bold) (const :italic)) ++@end example ++ ++Sometimes they describe possible elements in an alist: ++ ++@example ++(set (cons :tag "Height" (const height) integer) ++ (cons :tag "Width" (const width) integer)) ++@end example ++ ++@noindent ++That lets the user specify a height value optionally ++and a width value optionally. ++ ++@item (repeat @var{element-type}) ++The value must be a list and each element of the list must fit the type ++@var{element-type}. This appears in the customization buffer as a ++list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding ++more elements or removing elements. ++ ++@item (restricted-sexp :match-alternatives @var{criteria}) ++This is the most general composite type construct. The value may be ++any Lisp object that satisfies one of @var{criteria}. @var{criteria} ++should be a list, and each element should be one of these ++possibilities: ++ ++@itemize @bullet ++@item ++A predicate---that is, a function of one argument that has no side ++effects, and returns either @code{nil} or non-@code{nil} according to ++the argument. Using a predicate in the list says that objects for which ++the predicate returns non-@code{nil} are acceptable. ++ ++@item ++A quoted constant---that is, @code{'@var{object}}. This sort of element ++in the list says that @var{object} itself is an acceptable value. ++@end itemize ++ ++For example, ++ ++@example ++(restricted-sexp :match-alternatives ++ (integerp 't 'nil)) ++@end example ++ ++@noindent ++allows integers, @code{t} and @code{nil} as legitimate values. ++ ++The customization buffer shows all legitimate values using their read ++syntax, and the user edits them textually. ++@end table ++ ++ Here is a table of the keywords you can use in keyword-value pairs ++in a composite type: ++ ++@table @code ++@item :tag @var{tag} ++Use @var{tag} as the name of this alternative, for user communication ++purposes. This is useful for a type that appears inside of a ++@code{choice}. ++ ++@item :match-alternatives @var{criteria} ++@kindex match-alternatives@r{, customization keyword} ++Use @var{criteria} to match possible values. This is used only in ++@code{restricted-sexp}. ++ ++@item :args @var{argument-list} ++@kindex args@r{, customization keyword} ++Use the elements of @var{argument-list} as the arguments of the type ++construct. For instance, @code{(const :args (foo))} is equivalent to ++@code{(const foo)}. You rarely need to write @code{:args} explicitly, ++because normally the arguments are recognized automatically as ++whatever follows the last keyword-value pair. ++@end table ++ ++@node Splicing into Lists ++@subsection Splicing into Lists ++ ++ The @code{:inline} feature lets you splice a variable number of ++elements into the middle of a list or vector. You use it in a ++@code{set}, @code{choice} or @code{repeat} type which appears among the ++element-types of a @code{list} or @code{vector}. ++ ++ Normally, each of the element-types in a @code{list} or @code{vector} ++describes one and only one element of the list or vector. Thus, if an ++element-type is a @code{repeat}, that specifies a list of unspecified ++length which appears as one element. ++ ++ But when the element-type uses @code{:inline}, the value it matches is ++merged directly into the containing sequence. For example, if it ++matches a list with three elements, those become three elements of the ++overall sequence. This is analogous to using @samp{,@@} in the backquote ++construct. ++ ++ For example, to specify a list whose first element must be @code{baz} ++and whose remaining arguments should be zero or more of @code{foo} and ++@code{bar}, use this customization type: ++ ++@example ++(list (const baz) (set :inline t (const foo) (const bar))) ++@end example ++ ++@noindent ++This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)} ++and @code{(baz foo bar)}. ++ ++ When the element-type is a @code{choice}, you use @code{:inline} not ++in the @code{choice} itself, but in (some of) the alternatives of the ++@code{choice}. For example, to match a list which must start with a ++file name, followed either by the symbol @code{t} or two strings, use ++this customization type: ++ ++@example ++(list file ++ (choice (const t) ++ (list :inline t string string))) ++@end example ++ ++@noindent ++If the user chooses the first alternative in the choice, then the ++overall list has two elements and the second element is @code{t}. If ++the user chooses the second alternative, then the overall list has three ++elements and the second and third must be strings. ++ ++@node Type Keywords ++@subsection Type Keywords ++ ++You can specify keyword-argument pairs in a customization type after the ++type name symbol. Here are the keywords you can use, and their ++meanings: ++ ++@table @code ++@item :value @var{default} ++This is used for a type that appears as an alternative inside of ++@code{choice}; it specifies the default value to use, at first, if and ++when the user selects this alternative with the menu in the ++customization buffer. ++ ++Of course, if the actual value of the option fits this alternative, it ++will appear showing the actual value, not @var{default}. ++ ++If @code{nil} is not a valid value for the alternative, then it is ++essential to specify a valid default with @code{:value}. ++ ++@item :format @var{format-string} ++@kindex format@r{, customization keyword} ++This string will be inserted in the buffer to represent the value ++corresponding to the type. The following @samp{%} escapes are available ++for use in @var{format-string}: ++ ++@table @samp ++@item %[@var{button}%] ++Display the text @var{button} marked as a button. The @code{:action} ++attribute specifies what the button will do if the user invokes it; ++its value is a function which takes two arguments---the widget which ++the button appears in, and the event. ++ ++There is no way to specify two different buttons with different ++actions. ++ ++@item %@{@var{sample}%@} ++Show @var{sample} in a special face specified by @code{:sample-face}. ++ ++@item %v ++Substitute the item's value. How the value is represented depends on ++the kind of item, and (for variables) on the customization type. ++ ++@item %d ++Substitute the item's documentation string. ++ ++@item %h ++Like @samp{%d}, but if the documentation string is more than one line, ++add an active field to control whether to show all of it or just the ++first line. ++ ++@item %t ++Substitute the tag here. You specify the tag with the @code{:tag} ++keyword. ++ ++@item %% ++Display a literal @samp{%}. ++@end table ++ ++@item :action @var{action} ++@kindex action@r{, customization keyword} ++Perform @var{action} if the user clicks on a button. ++ ++@item :button-face @var{face} ++@kindex button-face@r{, customization keyword} ++Use the face @var{face} (a face name or a list of face names) for button ++text displayed with @samp{%[@dots{}%]}. ++ ++@item :button-prefix @var{prefix} ++@itemx :button-suffix @var{suffix} ++@kindex button-prefix@r{, customization keyword} ++@kindex button-suffix@r{, customization keyword} ++These specify the text to display before and after a button. ++Each can be: ++ ++@table @asis ++@item @code{nil} ++No text is inserted. ++ ++@item a string ++The string is inserted literally. ++ ++@item a symbol ++The symbol's value is used. ++@end table ++ ++@item :tag @var{tag} ++Use @var{tag} (a string) as the tag for the value (or part of the value) ++that corresponds to this type. ++ ++@item :doc @var{doc} ++@kindex doc@r{, customization keyword} ++Use @var{doc} as the documentation string for this value (or part of the ++value) that corresponds to this type. In order for this to work, you ++must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} ++in that value. ++ ++The usual reason to specify a documentation string for a type is to ++provide more information about the meanings of alternatives inside a ++@code{:choice} type or the parts of some other composite type. ++ ++@item :help-echo @var{motion-doc} ++@kindex help-echo@r{, customization keyword} ++When you move to this item with @code{widget-forward} or ++@code{widget-backward}, it will display the string @var{motion-doc} in ++the echo area. In addition, @var{motion-doc} is used as the mouse ++@code{help-echo} string and may actually be a function or form evaluated ++to yield a help string. If it is a function, it is called with one ++argument, the widget. ++ ++@item :match @var{function} ++@kindex match@r{, customization keyword} ++Specify how to decide whether a value matches the type. The ++corresponding value, @var{function}, should be a function that accepts ++two arguments, a widget and a value; it should return non-@code{nil} if ++the value is acceptable. ++ ++@item :validate @var{function} ++Specify a validation function for input. @var{function} takes a ++widget as an argument, and should return @code{nil} if the widget's ++current value is valid for the widget. Otherwise, it should return ++the widget containing the invalid data, and set that widget's ++@code{:error} property to a string explaining the error. ++ ++@ignore ++@item :indent @var{columns} ++Indent this item by @var{columns} columns. The indentation is used for ++@samp{%n}, and automatically for group names, for checklists and radio ++buttons, and for editable lists. It affects the whole of the ++item except for the first line. ++ ++@item :offset @var{extra} ++Indent the subitems of this item @var{extra} columns more than this ++item itself. By default, subitems are indented the same as their ++parent. ++ ++@item :extra-offset @var{n} ++Add @var{n} extra spaces to this item's indentation, compared to its ++parent's indentation. ++ ++@item :notify @var{function} ++Call @var{function} each time the item or a subitem is changed. The ++function gets two or three arguments. The first argument is the item ++itself, the second argument is the item that was changed, and the ++third argument is the event leading to the change, if any. ++ ++@item :menu-tag @var{tag-string} ++Use @var{tag-string} in the menu when the widget is used as an option ++in a @code{menu-choice} widget. ++ ++@item :menu-tag-get ++A function used for finding the tag when the widget is used as an option ++in a @code{menu-choice} widget. By default, the tag used will be either the ++@code{:menu-tag} or @code{:tag} property if present, or the @code{princ} ++representation of the @code{:value} property if not. ++ ++@item :tab-order ++Specify the order in which widgets are traversed with ++@code{widget-forward} or @code{widget-backward}. This is only partially ++implemented. ++ ++@enumerate a ++@item ++Widgets with tabbing order @code{-1} are ignored. ++ ++@item ++(Unimplemented) When on a widget with tabbing order @var{n}, go to the ++next widget in the buffer with tabbing order @var{n+1} or @code{nil}, ++whichever comes first. ++ ++@item ++When on a widget with no tabbing order specified, go to the next widget ++in the buffer with a positive tabbing order, or @code{nil} ++@end enumerate ++ ++@item :parent ++The parent of a nested widget (e.g., a @code{menu-choice} item or an ++element of a @code{editable-list} widget). ++ ++@item :sibling-args ++This keyword is only used for members of a @code{radio-button-choice} or ++@code{checklist}. The value should be a list of extra keyword ++arguments, which will be used when creating the @code{radio-button} or ++@code{checkbox} associated with this item. ++@end ignore ++@end table ++ ++@node Defining New Types ++@subsection Defining New Types ++ ++In the previous sections we have described how to construct elaborate ++type specifications for @code{defcustom}. In some cases you may want ++to give such a type specification a name. The obvious case is when ++you are using the same type for many user options: rather than repeat ++the specification for each option, you can give the type specification ++a name, and use that name each @code{defcustom}. The other case is ++when a user option's value is a recursive data structure. To make it ++possible for a datatype to refer to itself, it needs to have a name. ++ ++Since custom types are implemented as widgets, the way to define a new ++customize type is to define a new widget. We are not going to describe ++the widget interface here in details, see @ref{Top, , Introduction, ++widget, The Emacs Widget Library}, for that. Instead we are going to ++demonstrate the minimal functionality needed for defining new customize ++types by a simple example. ++ ++@example ++(define-widget 'binary-tree-of-string 'lazy ++ "A binary tree made of cons-cells and strings." ++ :offset 4 ++ :tag "Node" ++ :type '(choice (string :tag "Leaf" :value "") ++ (cons :tag "Interior" ++ :value ("" . "") ++ binary-tree-of-string ++ binary-tree-of-string))) ++ ++(defcustom foo-bar "" ++ "Sample variable holding a binary tree of strings." ++ :type 'binary-tree-of-string) ++@end example ++ ++The function to define a new widget is called @code{define-widget}. The ++first argument is the symbol we want to make a new widget type. The ++second argument is a symbol representing an existing widget, the new ++widget is going to be defined in terms of difference from the existing ++widget. For the purpose of defining new customization types, the ++@code{lazy} widget is perfect, because it accepts a @code{:type} keyword ++argument with the same syntax as the keyword argument to ++@code{defcustom} with the same name. The third argument is a ++documentation string for the new widget. You will be able to see that ++string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string ++@key{RET}} command. ++ ++After these mandatory arguments follow the keyword arguments. The most ++important is @code{:type}, which describes the data type we want to match ++with this widget. Here a @code{binary-tree-of-string} is described as ++being either a string, or a cons-cell whose car and cdr are themselves ++both @code{binary-tree-of-string}. Note the reference to the widget ++type we are currently in the process of defining. The @code{:tag} ++attribute is a string to name the widget in the user interface, and the ++@code{:offset} argument is there to ensure that child nodes are ++indented four spaces relative to the parent node, making the tree ++structure apparent in the customization buffer. ++ ++The @code{defcustom} shows how the new widget can be used as an ordinary ++customization type. ++ ++The reason for the name @code{lazy} is that the other composite ++widgets convert their inferior widgets to internal form when the ++widget is instantiated in a buffer. This conversion is recursive, so ++the inferior widgets will convert @emph{their} inferior widgets. If ++the data structure is itself recursive, this conversion is an infinite ++recursion. The @code{lazy} widget prevents the recursion: it convert ++its @code{:type} argument only when needed. ++ ++@ignore ++ arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2 ++@end ignore +diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi +new file mode 100644 +index 0000000..c768bbd +--- /dev/null ++++ b/doc/lispref/debugging.texi +@@ -0,0 +1,823 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, ++@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/debugging ++@node Debugging, Read and Print, Advising Functions, Top ++@chapter Debugging Lisp Programs ++ ++ There are three ways to investigate a problem in an Emacs Lisp program, ++depending on what you are doing with the program when the problem appears. ++ ++@itemize @bullet ++@item ++If the problem occurs when you run the program, you can use a Lisp ++debugger to investigate what is happening during execution. In addition ++to the ordinary debugger, Emacs comes with a source-level debugger, ++Edebug. This chapter describes both of them. ++ ++@item ++If the problem is syntactic, so that Lisp cannot even read the program, ++you can use the Emacs facilities for editing Lisp to localize it. ++ ++@item ++If the problem occurs when trying to compile the program with the byte ++compiler, you need to know how to examine the compiler's input buffer. ++@end itemize ++ ++@menu ++* Debugger:: How the Emacs Lisp debugger is implemented. ++* Edebug:: A source-level Emacs Lisp debugger. ++* Syntax Errors:: How to find syntax errors. ++* Test Coverage:: Ensuring you have tested all branches in your code. ++* Compilation Errors:: How to find errors that show up in byte compilation. ++@end menu ++ ++ Another useful debugging tool is the dribble file. When a dribble ++file is open, Emacs copies all keyboard input characters to that file. ++Afterward, you can examine the file to find out what input was used. ++@xref{Terminal Input}. ++ ++ For debugging problems in terminal descriptions, the ++@code{open-termscript} function can be useful. @xref{Terminal Output}. ++ ++@node Debugger ++@section The Lisp Debugger ++@cindex debugger for Emacs Lisp ++@cindex Lisp debugger ++@cindex break ++ ++ The ordinary @dfn{Lisp debugger} provides the ability to suspend ++evaluation of a form. While evaluation is suspended (a state that is ++commonly known as a @dfn{break}), you may examine the run time stack, ++examine the values of local or global variables, or change those values. ++Since a break is a recursive edit, all the usual editing facilities of ++Emacs are available; you can even run programs that will enter the ++debugger recursively. @xref{Recursive Editing}. ++ ++@menu ++* Error Debugging:: Entering the debugger when an error happens. ++* Infinite Loops:: Stopping and debugging a program that doesn't exit. ++* Function Debugging:: Entering it when a certain function is called. ++* Explicit Debug:: Entering it at a certain point in the program. ++* Using Debugger:: What the debugger does; what you see while in it. ++* Debugger Commands:: Commands used while in the debugger. ++* Invoking the Debugger:: How to call the function @code{debug}. ++* Internals of Debugger:: Subroutines of the debugger, and global variables. ++@end menu ++ ++@node Error Debugging ++@subsection Entering the Debugger on an Error ++@cindex error debugging ++@cindex debugging errors ++ ++ The most important time to enter the debugger is when a Lisp error ++happens. This allows you to investigate the immediate causes of the ++error. ++ ++ However, entry to the debugger is not a normal consequence of an ++error. Many commands frequently cause Lisp errors when invoked ++inappropriately, and during ordinary editing it would be very ++inconvenient to enter the debugger each time this happens. So if you ++want errors to enter the debugger, set the variable ++@code{debug-on-error} to non-@code{nil}. (The command ++@code{toggle-debug-on-error} provides an easy way to do this.) ++ ++@defopt debug-on-error ++This variable determines whether the debugger is called when an error ++is signaled and not handled. If @code{debug-on-error} is @code{t}, ++all kinds of errors call the debugger, except those listed in ++@code{debug-ignored-errors} (see below). If it is @code{nil}, none ++call the debugger. (Note that @code{eval-expression-debug-on-error} ++affects the setting of this variable in some cases; see below.) ++ ++The value can also be a list of error conditions that should call the ++debugger. For example, if you set it to the list ++@code{(void-variable)}, then only errors about a variable that has no ++value invoke the debugger. ++ ++When this variable is non-@code{nil}, Emacs does not create an error ++handler around process filter functions and sentinels. Therefore, ++errors in these functions also invoke the debugger. @xref{Processes}. ++@end defopt ++ ++@defopt debug-ignored-errors ++This variable specifies certain kinds of errors that should not enter ++the debugger. Its value is a list of error condition symbols and/or ++regular expressions. If the error has any of those condition symbols, ++or if the error message matches any of the regular expressions, then ++that error does not enter the debugger, regardless of the value of ++@code{debug-on-error}. ++ ++The normal value of this variable lists several errors that happen often ++during editing but rarely result from bugs in Lisp programs. However, ++``rarely'' is not ``never''; if your program fails with an error that ++matches this list, you will need to change this list in order to debug ++the error. The easiest way is usually to set ++@code{debug-ignored-errors} to @code{nil}. ++@end defopt ++ ++@defopt eval-expression-debug-on-error ++If this variable has a non-@code{nil} value, then ++@code{debug-on-error} is set to @code{t} when evaluating with the ++command @code{eval-expression}. If ++@code{eval-expression-debug-on-error} is @code{nil}, then the value of ++@code{debug-on-error} is not changed. @xref{Lisp Eval,, Evaluating ++Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}. ++@end defopt ++ ++@defopt debug-on-signal ++Normally, errors that are caught by @code{condition-case} never run the ++debugger, even if @code{debug-on-error} is non-@code{nil}. In other ++words, @code{condition-case} gets a chance to handle the error before ++the debugger gets a chance. ++ ++If you set @code{debug-on-signal} to a non-@code{nil} value, then the ++debugger gets the first chance at every error; an error will invoke the ++debugger regardless of any @code{condition-case}, if it fits the ++criteria specified by the values of @code{debug-on-error} and ++@code{debug-ignored-errors}. ++ ++@strong{Warning:} This variable is strong medicine! Various parts of ++Emacs handle errors in the normal course of affairs, and you may not ++even realize that errors happen there. If you set ++@code{debug-on-signal} to a non-@code{nil} value, those errors will ++enter the debugger. ++ ++@strong{Warning:} @code{debug-on-signal} has no effect when ++@code{debug-on-error} is @code{nil}. ++@end defopt ++ ++ To debug an error that happens during loading of the init ++file, use the option @samp{--debug-init}. This binds ++@code{debug-on-error} to @code{t} while loading the init file, and ++bypasses the @code{condition-case} which normally catches errors in the ++init file. ++ ++@node Infinite Loops ++@subsection Debugging Infinite Loops ++@cindex infinite loops ++@cindex loops, infinite ++@cindex quitting from infinite loop ++@cindex stopping an infinite loop ++ ++ When a program loops infinitely and fails to return, your first ++problem is to stop the loop. On most operating systems, you can do this ++with @kbd{C-g}, which causes a @dfn{quit}. ++ ++ Ordinary quitting gives no information about why the program was ++looping. To get more information, you can set the variable ++@code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not ++considered an error, and @code{debug-on-error} has no effect on the ++handling of @kbd{C-g}. Likewise, @code{debug-on-quit} has no effect on ++errors. ++ ++ Once you have the debugger running in the middle of the infinite loop, ++you can proceed from the debugger using the stepping commands. If you ++step through the entire loop, you will probably get enough information ++to solve the problem. ++ ++@defopt debug-on-quit ++This variable determines whether the debugger is called when @code{quit} ++is signaled and not handled. If @code{debug-on-quit} is non-@code{nil}, ++then the debugger is called whenever you quit (that is, type @kbd{C-g}). ++If @code{debug-on-quit} is @code{nil}, then the debugger is not called ++when you quit. @xref{Quitting}. ++@end defopt ++ ++@node Function Debugging ++@subsection Entering the Debugger on a Function Call ++@cindex function call debugging ++@cindex debugging specific functions ++ ++ To investigate a problem that happens in the middle of a program, one ++useful technique is to enter the debugger whenever a certain function is ++called. You can do this to the function in which the problem occurs, ++and then step through the function, or you can do this to a function ++called shortly before the problem, step quickly over the call to that ++function, and then step through its caller. ++ ++@deffn Command debug-on-entry function-name ++This function requests @var{function-name} to invoke the debugger each ++time it is called. It works by inserting the form ++@code{(implement-debug-on-entry)} into the function definition as the ++first form. ++ ++Any function or macro defined as Lisp code may be set to break on ++entry, regardless of whether it is interpreted code or compiled code. ++If the function is a command, it will enter the debugger when called ++from Lisp and when called interactively (after the reading of the ++arguments). You can also set debug-on-entry for primitive functions ++(i.e., those written in C) this way, but it only takes effect when the ++primitive is called from Lisp code. Debug-on-entry is not allowed for ++special forms. ++ ++When @code{debug-on-entry} is called interactively, it prompts for ++@var{function-name} in the minibuffer. If the function is already set ++up to invoke the debugger on entry, @code{debug-on-entry} does nothing. ++@code{debug-on-entry} always returns @var{function-name}. ++ ++@strong{Warning:} if you redefine a function after using ++@code{debug-on-entry} on it, the code to enter the debugger is ++discarded by the redefinition. In effect, redefining the function ++cancels the break-on-entry feature for that function. ++ ++Here's an example to illustrate use of this function: ++ ++@example ++@group ++(defun fact (n) ++ (if (zerop n) 1 ++ (* n (fact (1- n))))) ++ @result{} fact ++@end group ++@group ++(debug-on-entry 'fact) ++ @result{} fact ++@end group ++@group ++(fact 3) ++@end group ++ ++@group ++------ Buffer: *Backtrace* ------ ++Debugger entered--entering a function: ++* fact(3) ++ eval((fact 3)) ++ eval-last-sexp-1(nil) ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++------ Buffer: *Backtrace* ------ ++@end group ++ ++@group ++(symbol-function 'fact) ++ @result{} (lambda (n) ++ (debug (quote debug)) ++ (if (zerop n) 1 (* n (fact (1- n))))) ++@end group ++@end example ++@end deffn ++ ++@deffn Command cancel-debug-on-entry &optional function-name ++This function undoes the effect of @code{debug-on-entry} on ++@var{function-name}. When called interactively, it prompts for ++@var{function-name} in the minibuffer. If @var{function-name} is ++omitted or @code{nil}, it cancels break-on-entry for all functions. ++Calling @code{cancel-debug-on-entry} does nothing to a function which is ++not currently set up to break on entry. ++@end deffn ++ ++@node Explicit Debug ++@subsection Explicit Entry to the Debugger ++ ++ You can cause the debugger to be called at a certain point in your ++program by writing the expression @code{(debug)} at that point. To do ++this, visit the source file, insert the text @samp{(debug)} at the ++proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key ++binding). @strong{Warning:} if you do this for temporary debugging ++purposes, be sure to undo this insertion before you save the file! ++ ++ The place where you insert @samp{(debug)} must be a place where an ++additional form can be evaluated and its value ignored. (If the value ++of @code{(debug)} isn't ignored, it will alter the execution of the ++program!) The most common suitable places are inside a @code{progn} or ++an implicit @code{progn} (@pxref{Sequencing}). ++ ++@node Using Debugger ++@subsection Using the Debugger ++ ++ When the debugger is entered, it displays the previously selected ++buffer in one window and a buffer named @samp{*Backtrace*} in another ++window. The backtrace buffer contains one line for each level of Lisp ++function execution currently going on. At the beginning of this buffer ++is a message describing the reason that the debugger was invoked (such ++as the error message and associated data, if it was invoked due to an ++error). ++ ++ The backtrace buffer is read-only and uses a special major mode, ++Debugger mode, in which letters are defined as debugger commands. The ++usual Emacs editing commands are available; thus, you can switch windows ++to examine the buffer that was being edited at the time of the error, ++switch buffers, visit files, or do any other sort of editing. However, ++the debugger is a recursive editing level (@pxref{Recursive Editing}) ++and it is wise to go back to the backtrace buffer and exit the debugger ++(with the @kbd{q} command) when you are finished with it. Exiting ++the debugger gets out of the recursive edit and kills the backtrace ++buffer. ++ ++@cindex current stack frame ++ The backtrace buffer shows you the functions that are executing and ++their argument values. It also allows you to specify a stack frame by ++moving point to the line describing that frame. (A stack frame is the ++place where the Lisp interpreter records information about a particular ++invocation of a function.) The frame whose line point is on is ++considered the @dfn{current frame}. Some of the debugger commands ++operate on the current frame. If a line starts with a star, that means ++that exiting that frame will call the debugger again. This is useful ++for examining the return value of a function. ++ ++ If a function name is underlined, that means the debugger knows ++where its source code is located. You can click @kbd{Mouse-2} on that ++name, or move to it and type @key{RET}, to visit the source code. ++ ++ The debugger itself must be run byte-compiled, since it makes ++assumptions about how many stack frames are used for the debugger ++itself. These assumptions are false if the debugger is running ++interpreted. ++ ++@node Debugger Commands ++@subsection Debugger Commands ++@cindex debugger command list ++ ++ The debugger buffer (in Debugger mode) provides special commands in ++addition to the usual Emacs commands. The most important use of ++debugger commands is for stepping through code, so that you can see ++how control flows. The debugger can step through the control ++structures of an interpreted function, but cannot do so in a ++byte-compiled function. If you would like to step through a ++byte-compiled function, replace it with an interpreted definition of ++the same function. (To do this, visit the source for the function and ++type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger ++to step through a primitive function. ++ ++ Here is a list of Debugger mode commands: ++ ++@table @kbd ++@item c ++Exit the debugger and continue execution. When continuing is possible, ++it resumes execution of the program as if the debugger had never been ++entered (aside from any side-effects that you caused by changing ++variable values or data structures while inside the debugger). ++ ++Continuing is possible after entry to the debugger due to function entry ++or exit, explicit invocation, or quitting. You cannot continue if the ++debugger was entered because of an error. ++ ++@item d ++Continue execution, but enter the debugger the next time any Lisp ++function is called. This allows you to step through the ++subexpressions of an expression, seeing what values the subexpressions ++compute, and what else they do. ++ ++The stack frame made for the function call which enters the debugger in ++this way will be flagged automatically so that the debugger will be ++called again when the frame is exited. You can use the @kbd{u} command ++to cancel this flag. ++ ++@item b ++Flag the current frame so that the debugger will be entered when the ++frame is exited. Frames flagged in this way are marked with stars ++in the backtrace buffer. ++ ++@item u ++Don't enter the debugger when the current frame is exited. This ++cancels a @kbd{b} command on that frame. The visible effect is to ++remove the star from the line in the backtrace buffer. ++ ++@item j ++Flag the current frame like @kbd{b}. Then continue execution like ++@kbd{c}, but temporarily disable break-on-entry for all functions that ++are set up to do so by @code{debug-on-entry}. ++ ++@item e ++Read a Lisp expression in the minibuffer, evaluate it, and print the ++value in the echo area. The debugger alters certain important ++variables, and the current buffer, as part of its operation; @kbd{e} ++temporarily restores their values from outside the debugger, so you can ++examine and change them. This makes the debugger more transparent. By ++contrast, @kbd{M-:} does nothing special in the debugger; it shows you ++the variable values within the debugger. ++ ++@item R ++Like @kbd{e}, but also save the result of evaluation in the ++buffer @samp{*Debugger-record*}. ++ ++@item q ++Terminate the program being debugged; return to top-level Emacs ++command execution. ++ ++If the debugger was entered due to a @kbd{C-g} but you really want ++to quit, and not debug, use the @kbd{q} command. ++ ++@item r ++Return a value from the debugger. The value is computed by reading an ++expression with the minibuffer and evaluating it. ++ ++The @kbd{r} command is useful when the debugger was invoked due to exit ++from a Lisp call frame (as requested with @kbd{b} or by entering the ++frame with @kbd{d}); then the value specified in the @kbd{r} command is ++used as the value of that frame. It is also useful if you call ++@code{debug} and use its return value. Otherwise, @kbd{r} has the same ++effect as @kbd{c}, and the specified return value does not matter. ++ ++You can't use @kbd{r} when the debugger was entered due to an error. ++ ++@item l ++Display a list of functions that will invoke the debugger when called. ++This is a list of functions that are set to break on entry by means of ++@code{debug-on-entry}. @strong{Warning:} if you redefine such a ++function and thus cancel the effect of @code{debug-on-entry}, it may ++erroneously show up in this list. ++@end table ++ ++@node Invoking the Debugger ++@subsection Invoking the Debugger ++ ++ Here we describe in full detail the function @code{debug} that is used ++to invoke the debugger. ++ ++@defun debug &rest debugger-args ++This function enters the debugger. It switches buffers to a buffer ++named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second ++recursive entry to the debugger, etc.), and fills it with information ++about the stack of Lisp function calls. It then enters a recursive ++edit, showing the backtrace buffer in Debugger mode. ++ ++The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit ++the recursive edit; then @code{debug} switches back to the previous ++buffer and returns to whatever called @code{debug}. This is the only ++way the function @code{debug} can return to its caller. ++ ++The use of the @var{debugger-args} is that @code{debug} displays the ++rest of its arguments at the top of the @samp{*Backtrace*} buffer, so ++that the user can see them. Except as described below, this is the ++@emph{only} way these arguments are used. ++ ++However, certain values for first argument to @code{debug} have a ++special significance. (Normally, these values are used only by the ++internals of Emacs, and not by programmers calling @code{debug}.) Here ++is a table of these special values: ++ ++@table @code ++@item lambda ++@cindex @code{lambda} in debug ++A first argument of @code{lambda} means @code{debug} was called ++because of entry to a function when @code{debug-on-next-call} was ++non-@code{nil}. The debugger displays @samp{Debugger ++entered--entering a function:} as a line of text at the top of the ++buffer. ++ ++@item debug ++@code{debug} as first argument means @code{debug} was called because ++of entry to a function that was set to debug on entry. The debugger ++displays the string @samp{Debugger entered--entering a function:}, ++just as in the @code{lambda} case. It also marks the stack frame for ++that function so that it will invoke the debugger when exited. ++ ++@item t ++When the first argument is @code{t}, this indicates a call to ++@code{debug} due to evaluation of a function call form when ++@code{debug-on-next-call} is non-@code{nil}. The debugger displays ++@samp{Debugger entered--beginning evaluation of function call form:} ++as the top line in the buffer. ++ ++@item exit ++When the first argument is @code{exit}, it indicates the exit of a ++stack frame previously marked to invoke the debugger on exit. The ++second argument given to @code{debug} in this case is the value being ++returned from the frame. The debugger displays @samp{Debugger ++entered--returning value:} in the top line of the buffer, followed by ++the value being returned. ++ ++@item error ++@cindex @code{error} in debug ++When the first argument is @code{error}, the debugger indicates that ++it is being entered because an error or @code{quit} was signaled and ++not handled, by displaying @samp{Debugger entered--Lisp error:} ++followed by the error signaled and any arguments to @code{signal}. ++For example, ++ ++@example ++@group ++(let ((debug-on-error t)) ++ (/ 1 0)) ++@end group ++ ++@group ++------ Buffer: *Backtrace* ------ ++Debugger entered--Lisp error: (arith-error) ++ /(1 0) ++... ++------ Buffer: *Backtrace* ------ ++@end group ++@end example ++ ++If an error was signaled, presumably the variable ++@code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled, ++then presumably the variable @code{debug-on-quit} is non-@code{nil}. ++ ++@item nil ++Use @code{nil} as the first of the @var{debugger-args} when you want ++to enter the debugger explicitly. The rest of the @var{debugger-args} ++are printed on the top line of the buffer. You can use this feature to ++display messages---for example, to remind yourself of the conditions ++under which @code{debug} is called. ++@end table ++@end defun ++ ++@node Internals of Debugger ++@subsection Internals of the Debugger ++ ++ This section describes functions and variables used internally by the ++debugger. ++ ++@defvar debugger ++The value of this variable is the function to call to invoke the ++debugger. Its value must be a function of any number of arguments, or, ++more typically, the name of a function. This function should invoke ++some kind of debugger. The default value of the variable is ++@code{debug}. ++ ++The first argument that Lisp hands to the function indicates why it ++was called. The convention for arguments is detailed in the description ++of @code{debug} (@pxref{Invoking the Debugger}). ++@end defvar ++ ++@deffn Command backtrace ++@cindex run time stack ++@cindex call stack ++This function prints a trace of Lisp function calls currently active. ++This is the function used by @code{debug} to fill up the ++@samp{*Backtrace*} buffer. It is written in C, since it must have access ++to the stack to determine which function calls are active. The return ++value is always @code{nil}. ++ ++In the following example, a Lisp expression calls @code{backtrace} ++explicitly. This prints the backtrace to the stream ++@code{standard-output}, which, in this case, is the buffer ++@samp{backtrace-output}. ++ ++Each line of the backtrace represents one function call. The line shows ++the values of the function's arguments if they are all known; if they ++are still being computed, the line says so. The arguments of special ++forms are elided. ++ ++@smallexample ++@group ++(with-output-to-temp-buffer "backtrace-output" ++ (let ((var 1)) ++ (save-excursion ++ (setq var (eval '(progn ++ (1+ var) ++ (list 'testing (backtrace)))))))) ++ ++ @result{} (testing nil) ++@end group ++ ++@group ++----------- Buffer: backtrace-output ------------ ++ backtrace() ++ (list ...computing arguments...) ++@end group ++ (progn ...) ++ eval((progn (1+ var) (list (quote testing) (backtrace)))) ++ (setq ...) ++ (save-excursion ...) ++ (let ...) ++ (with-output-to-temp-buffer ...) ++ eval((with-output-to-temp-buffer ...)) ++ eval-last-sexp-1(nil) ++@group ++ eval-last-sexp(nil) ++ call-interactively(eval-last-sexp) ++----------- Buffer: backtrace-output ------------ ++@end group ++@end smallexample ++@end deffn ++ ++@ignore @c Not worth mentioning ++@defopt stack-trace-on-error ++@cindex stack trace ++This variable controls whether Lisp automatically displays a ++backtrace buffer after every error that is not handled. A quit signal ++counts as an error for this variable. If it is non-@code{nil} then a ++backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every ++error. If it is @code{nil}, then a backtrace is not shown. ++ ++When a backtrace is shown, that buffer is not selected. If either ++@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then ++a backtrace is shown in one buffer, and the debugger is popped up in ++another buffer with its own backtrace. ++ ++We consider this feature to be obsolete and superseded by the debugger ++itself. ++@end defopt ++@end ignore ++ ++@defvar debug-on-next-call ++@cindex @code{eval}, and debugging ++@cindex @code{apply}, and debugging ++@cindex @code{funcall}, and debugging ++If this variable is non-@code{nil}, it says to call the debugger before ++the next @code{eval}, @code{apply} or @code{funcall}. Entering the ++debugger sets @code{debug-on-next-call} to @code{nil}. ++ ++The @kbd{d} command in the debugger works by setting this variable. ++@end defvar ++ ++@defun backtrace-debug level flag ++This function sets the debug-on-exit flag of the stack frame @var{level} ++levels down the stack, giving it the value @var{flag}. If @var{flag} is ++non-@code{nil}, this will cause the debugger to be entered when that ++frame later exits. Even a nonlocal exit through that frame will enter ++the debugger. ++ ++This function is used only by the debugger. ++@end defun ++ ++@defvar command-debug-status ++This variable records the debugging status of the current interactive ++command. Each time a command is called interactively, this variable is ++bound to @code{nil}. The debugger can set this variable to leave ++information for future debugger invocations during the same command ++invocation. ++ ++The advantage of using this variable rather than an ordinary global ++variable is that the data will never carry over to a subsequent command ++invocation. ++@end defvar ++ ++@defun backtrace-frame frame-number ++The function @code{backtrace-frame} is intended for use in Lisp ++debuggers. It returns information about what computation is happening ++in the stack frame @var{frame-number} levels down. ++ ++If that frame has not evaluated the arguments yet, or is a special ++form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. ++ ++If that frame has evaluated its arguments and called its function ++already, the return value is @code{(t @var{function} ++@var{arg-values}@dots{})}. ++ ++In the return value, @var{function} is whatever was supplied as the ++@sc{car} of the evaluated list, or a @code{lambda} expression in the ++case of a macro call. If the function has a @code{&rest} argument, that ++is represented as the tail of the list @var{arg-values}. ++ ++If @var{frame-number} is out of range, @code{backtrace-frame} returns ++@code{nil}. ++@end defun ++ ++@include edebug.texi ++ ++@node Syntax Errors ++@section Debugging Invalid Lisp Syntax ++@cindex debugging invalid Lisp syntax ++ ++ The Lisp reader reports invalid syntax, but cannot say where the real ++problem is. For example, the error ``End of file during parsing'' in ++evaluating an expression indicates an excess of open parentheses (or ++square brackets). The reader detects this imbalance at the end of the ++file, but it cannot figure out where the close parenthesis should have ++been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close ++parenthesis or missing open parenthesis, but does not say where the ++missing parenthesis belongs. How, then, to find what to change? ++ ++ If the problem is not simply an imbalance of parentheses, a useful ++technique is to try @kbd{C-M-e} at the beginning of each defun, and see ++if it goes to the place where that defun appears to end. If it does ++not, there is a problem in that defun. ++ ++@cindex unbalanced parentheses ++@cindex parenthesis mismatch, debugging ++ However, unmatched parentheses are the most common syntax errors in ++Lisp, and we can give further advice for those cases. (In addition, ++just moving point through the code with Show Paren mode enabled might ++find the mismatch.) ++ ++@menu ++* Excess Open:: How to find a spurious open paren or missing close. ++* Excess Close:: How to find a spurious close paren or missing open. ++@end menu ++ ++@node Excess Open ++@subsection Excess Open Parentheses ++ ++ The first step is to find the defun that is unbalanced. If there is ++an excess open parenthesis, the way to do this is to go to the end of ++the file and type @kbd{C-u C-M-u}. This will move you to the ++beginning of the first defun that is unbalanced. ++ ++ The next step is to determine precisely what is wrong. There is no ++way to be sure of this except by studying the program, but often the ++existing indentation is a clue to where the parentheses should have ++been. The easiest way to use this clue is to reindent with @kbd{C-M-q} ++and see what moves. @strong{But don't do this yet!} Keep reading, ++first. ++ ++ Before you do this, make sure the defun has enough close parentheses. ++Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest ++of the file until the end. So move to the end of the defun and insert a ++close parenthesis there. Don't use @kbd{C-M-e} to move there, since ++that too will fail to work until the defun is balanced. ++ ++ Now you can go to the beginning of the defun and type @kbd{C-M-q}. ++Usually all the lines from a certain point to the end of the function ++will shift to the right. There is probably a missing close parenthesis, ++or a superfluous open parenthesis, near that point. (However, don't ++assume this is true; study the code to make sure.) Once you have found ++the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old ++indentation is probably appropriate to the intended parentheses. ++ ++ After you think you have fixed the problem, use @kbd{C-M-q} again. If ++the old indentation actually fit the intended nesting of parentheses, ++and you have put back those parentheses, @kbd{C-M-q} should not change ++anything. ++ ++@node Excess Close ++@subsection Excess Close Parentheses ++ ++ To deal with an excess close parenthesis, first go to the beginning ++of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first ++unbalanced defun. ++ ++ Then find the actual matching close parenthesis by typing @kbd{C-M-f} ++at the beginning of that defun. This will leave you somewhere short of ++the place where the defun ought to end. It is possible that you will ++find a spurious close parenthesis in that vicinity. ++ ++ If you don't see a problem at that point, the next thing to do is to ++type @kbd{C-M-q} at the beginning of the defun. A range of lines will ++probably shift left; if so, the missing open parenthesis or spurious ++close parenthesis is probably near the first of those lines. (However, ++don't assume this is true; study the code to make sure.) Once you have ++found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the ++old indentation is probably appropriate to the intended parentheses. ++ ++ After you think you have fixed the problem, use @kbd{C-M-q} again. If ++the old indentation actually fits the intended nesting of parentheses, ++and you have put back those parentheses, @kbd{C-M-q} should not change ++anything. ++ ++@node Test Coverage ++@section Test Coverage ++@cindex coverage testing ++ ++@findex testcover-start ++@findex testcover-mark-all ++@findex testcover-next-mark ++ You can do coverage testing for a file of Lisp code by loading the ++@code{testcover} library and using the command @kbd{M-x ++testcover-start @key{RET} @var{file} @key{RET}} to instrument the ++code. Then test your code by calling it one or more times. Then use ++the command @kbd{M-x testcover-mark-all} to display colored highlights ++on the code to show where coverage is insufficient. The command ++@kbd{M-x testcover-next-mark} will move point forward to the next ++highlighted spot. ++ ++ Normally, a red highlight indicates the form was never completely ++evaluated; a brown highlight means it always evaluated to the same ++value (meaning there has been little testing of what is done with the ++result). However, the red highlight is skipped for forms that can't ++possibly complete their evaluation, such as @code{error}. The brown ++highlight is skipped for forms that are expected to always evaluate to ++the same value, such as @code{(setq x 14)}. ++ ++ For difficult cases, you can add do-nothing macros to your code to ++give advice to the test coverage tool. ++ ++@defmac 1value form ++Evaluate @var{form} and return its value, but inform coverage testing ++that @var{form}'s value should always be the same. ++@end defmac ++ ++@defmac noreturn form ++Evaluate @var{form}, informing coverage testing that @var{form} should ++never return. If it ever does return, you get a run-time error. ++@end defmac ++ ++ Edebug also has a coverage testing feature (@pxref{Coverage ++Testing}). These features partly duplicate each other, and it would ++be cleaner to combine them. ++ ++@node Compilation Errors ++@section Debugging Problems in Compilation ++@cindex debugging byte compilation problems ++ ++ When an error happens during byte compilation, it is normally due to ++invalid syntax in the program you are compiling. The compiler prints a ++suitable error message in the @samp{*Compile-Log*} buffer, and then ++stops. The message may state a function name in which the error was ++found, or it may not. Either way, here is how to find out where in the ++file the error occurred. ++ ++ What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}. ++(Note that the buffer name starts with a space, so it does not show ++up in @kbd{M-x list-buffers}.) This buffer contains the program being ++compiled, and point shows how far the byte compiler was able to read. ++ ++ If the error was due to invalid Lisp syntax, point shows exactly where ++the invalid syntax was @emph{detected}. The cause of the error is not ++necessarily near by! Use the techniques in the previous section to find ++the error. ++ ++ If the error was detected while compiling a form that had been read ++successfully, then point is located at the end of the form. In this ++case, this technique can't localize the error precisely, but can still ++show you which function to check. ++ ++@ignore ++ arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7 ++@end ignore +diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi +new file mode 100644 +index 0000000..14e6a79 +--- /dev/null ++++ b/doc/lispref/display.texi +@@ -0,0 +1,5880 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/display ++@node Display, System Interface, Processes, Top ++@chapter Emacs Display ++ ++ This chapter describes a number of features related to the display ++that Emacs presents to the user. ++ ++@menu ++* Refresh Screen:: Clearing the screen and redrawing everything on it. ++* Forcing Redisplay:: Forcing redisplay. ++* Truncation:: Folding or wrapping long text lines. ++* The Echo Area:: Displaying messages at the bottom of the screen. ++* Warnings:: Displaying warning messages for the user. ++* Invisible Text:: Hiding part of the buffer text. ++* Selective Display:: Hiding part of the buffer text (the old way). ++* Temporary Displays:: Displays that go away automatically. ++* Overlays:: Use overlays to highlight parts of the buffer. ++* Width:: How wide a character or string is on the screen. ++* Line Height:: Controlling the height of lines. ++* Faces:: A face defines a graphics style for text characters: ++ font, colors, etc. ++* Fringes:: Controlling window fringes. ++* Scroll Bars:: Controlling vertical scroll bars. ++* Display Property:: Enabling special display features. ++* Images:: Displaying images in Emacs buffers. ++* Buttons:: Adding clickable buttons to Emacs buffers. ++* Abstract Display:: Emacs' Widget for Object Collections. ++* Blinking:: How Emacs shows the matching open parenthesis. ++* Usual Display:: The usual conventions for displaying nonprinting chars. ++* Display Tables:: How to specify other conventions. ++* Beeping:: Audible signal to the user. ++* Window Systems:: Which window system is being used. ++@end menu ++ ++@node Refresh Screen ++@section Refreshing the Screen ++ ++ The function @code{redraw-frame} clears and redisplays the entire ++contents of a given frame (@pxref{Frames}). This is useful if the ++screen is corrupted. ++ ++@c Emacs 19 feature ++@defun redraw-frame frame ++This function clears and redisplays frame @var{frame}. ++@end defun ++ ++ Even more powerful is @code{redraw-display}: ++ ++@deffn Command redraw-display ++This function clears and redisplays all visible frames. ++@end deffn ++ ++ In Emacs, processing user input takes priority over redisplay. If ++you call these functions when input is available, they don't redisplay ++immediately, but the requested redisplay does happen ++eventually---after all the input has been processed. ++ ++ On text-only terminals, suspending and resuming Emacs normally also ++refreshes the screen. Some terminal emulators record separate ++contents for display-oriented programs such as Emacs and for ordinary ++sequential display. If you are using such a terminal, you might want ++to inhibit the redisplay on resumption. ++ ++@defopt no-redraw-on-reenter ++@cindex suspend (cf. @code{no-redraw-on-reenter}) ++@cindex resume (cf. @code{no-redraw-on-reenter}) ++This variable controls whether Emacs redraws the entire screen after it ++has been suspended and resumed. Non-@code{nil} means there is no need ++to redraw, @code{nil} means redrawing is needed. The default is @code{nil}. ++@end defopt ++ ++@node Forcing Redisplay ++@section Forcing Redisplay ++@cindex forcing redisplay ++ ++ Emacs normally tries to redisplay the screen whenever it waits for ++input. With the following function, you can request an immediate ++attempt to redisplay, in the middle of Lisp code, without actually ++waiting for input. ++ ++@defun redisplay &optional force ++This function tries immediately to redisplay, provided there are no ++pending input events. ++ ++If the optional argument @var{force} is non-@code{nil}, it does all ++pending redisplay work even if input is available, with no ++pre-emption. ++ ++The function returns @code{t} if it actually tried to redisplay, and ++@code{nil} otherwise. A value of @code{t} does not mean that ++redisplay proceeded to completion; it could have been pre-empted by ++newly arriving terminal input. ++@end defun ++ ++ @code{redisplay} with no argument tries immediately to redisplay, ++but has no effect on the usual rules for what parts of the screen to ++redisplay. By contrast, the following function adds certain windows ++to the pending redisplay work (as if their contents had completely ++changed), but doesn't immediately try to do any redisplay work. ++ ++@defun force-window-update &optional object ++This function forces some or all windows to be updated on next ++redisplay. If @var{object} is a window, it requires eventual ++redisplay of that window. If @var{object} is a buffer or buffer name, ++it requires eventual redisplay of all windows displaying that buffer. ++If @var{object} is @code{nil} (or omitted), it requires eventual ++redisplay of all windows. ++@end defun ++ ++ @code{force-window-update} does not do a redisplay immediately. ++(Emacs will do that when it waits for input.) Rather, its effect is ++to put more work on the queue to be done by redisplay whenever there ++is a chance. ++ ++ Emacs redisplay normally stops if input arrives, and does not happen ++at all if input is available before it starts. Most of the time, this ++is exactly what you want. However, you can prevent preemption by ++binding @code{redisplay-dont-pause} to a non-@code{nil} value. ++ ++@defvar redisplay-dont-pause ++If this variable is non-@code{nil}, pending input does not ++prevent or halt redisplay; redisplay occurs, and finishes, ++regardless of whether input is available. ++@end defvar ++ ++@defvar redisplay-preemption-period ++This variable specifies how many seconds Emacs waits between checks ++for new input during redisplay. (The default is 0.1 seconds.) If ++input has arrived when Emacs checks, it pre-empts redisplay and ++processes the available input before trying again to redisplay. ++ ++If this variable is @code{nil}, Emacs does not check for input during ++redisplay, and redisplay cannot be preempted by input. ++ ++This variable is only obeyed on graphical terminals. For ++text terminals, see @ref{Terminal Output}. ++@end defvar ++ ++@node Truncation ++@section Truncation ++@cindex line wrapping ++@cindex line truncation ++@cindex continuation lines ++@cindex @samp{$} in display ++@cindex @samp{\} in display ++ ++ When a line of text extends beyond the right edge of a window, Emacs ++can @dfn{continue} the line (make it ``wrap'' to the next screen ++line), or @dfn{truncate} the line (limit it to one screen line). The ++additional screen lines used to display a long text line are called ++@dfn{continuation} lines. Continuation is not the same as filling; ++continuation happens on the screen only, not in the buffer contents, ++and it breaks a line precisely at the right margin, not at a word ++boundary. @xref{Filling}. ++ ++ On a graphical display, tiny arrow images in the window fringes ++indicate truncated and continued lines (@pxref{Fringes}). On a text ++terminal, a @samp{$} in the rightmost column of the window indicates ++truncation; a @samp{\} on the rightmost column indicates a line that ++``wraps.'' (The display table can specify alternate characters to use ++for this; @pxref{Display Tables}). ++ ++@defopt truncate-lines ++If this buffer-local variable is non-@code{nil}, lines that extend ++beyond the right edge of the window are truncated; otherwise, they are ++continued. As a special exception, the variable ++@code{truncate-partial-width-windows} takes precedence in ++@dfn{partial-width} windows (i.e., windows that do not occupy the ++entire frame width). ++@end defopt ++ ++@defopt default-truncate-lines ++This variable is the default value for @code{truncate-lines}, for ++buffers that do not have buffer-local values for it. ++@end defopt ++ ++@defopt truncate-partial-width-windows ++This variable controls line truncation in @dfn{partial-width} windows. ++A partial-width window is one that does not occupy the entire frame ++width (@pxref{Splitting Windows}). If the value is @code{nil}, line ++truncation is determined by the variable @code{truncate-lines} (see ++above). If the value is an integer @var{n}, lines are truncated if ++the partial-width window has fewer than @var{n} columns, regardless of ++the value of @code{truncate-lines}; if the partial-width window has ++@var{n} or more columns, line truncation is determined by ++@code{truncate-lines}. For any other non-@code{nil} value, lines are ++truncated in every partial-width window, regardless of the value of ++@code{truncate-lines}. ++@end defopt ++ ++ When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in ++a window, that forces truncation. ++ ++@defvar wrap-prefix ++If this buffer-local variable is non-@code{nil}, it defines a ++``prefix'' that is prepended to every continuation line at ++display-time. (If lines are truncated, the wrap-prefix is never ++used.) It may be a string, an image, or a stretch-glyph; the value is ++interpreted in the same way as a @code{display} text property. ++@xref{Display Property}. ++ ++A wrap-prefix may also be specified for regions of text, using the ++@code{wrap-prefix} text or overlay property. This takes precedence ++over the @code{wrap-prefix} variable. @xref{Special Properties}. ++@end defvar ++ ++@defvar line-prefix ++If this buffer-local variable is non-@code{nil}, it defines a ++``prefix'' that is prepended to every non-continuation line at ++display-time. It may be a string, an image, or a stretch-glyph; the ++value is interpreted in the same way as a @code{display} text ++property. @xref{Display Property}. ++ ++A line-prefix may also be specified for regions of text using the ++@code{line-prefix} text or overlay property. This takes precedence ++over the @code{line-prefix} variable. @xref{Special Properties}. ++@end defvar ++ ++ If your buffer contains @emph{very} long lines, and you use ++continuation to display them, computing the continuation lines can ++make Emacs redisplay slow. The column computation and indentation ++functions also become slow. Then you might find it advisable to set ++@code{cache-long-line-scans} to @code{t}. ++ ++@defvar cache-long-line-scans ++If this variable is non-@code{nil}, various indentation and motion ++functions, and Emacs redisplay, cache the results of scanning the ++buffer, and consult the cache to avoid rescanning regions of the buffer ++unless they are modified. ++ ++Turning on the cache slows down processing of short lines somewhat. ++ ++This variable is automatically buffer-local in every buffer. ++@end defvar ++ ++@node The Echo Area ++@section The Echo Area ++@cindex error display ++@cindex echo area ++ ++ The @dfn{echo area} is used for displaying error messages ++(@pxref{Errors}), for messages made with the @code{message} primitive, ++and for echoing keystrokes. It is not the same as the minibuffer, ++despite the fact that the minibuffer appears (when active) in the same ++place on the screen as the echo area. The @cite{GNU Emacs Manual} ++specifies the rules for resolving conflicts between the echo area and ++the minibuffer for use of that screen space (@pxref{Minibuffer,, The ++Minibuffer, emacs, The GNU Emacs Manual}). ++ ++ You can write output in the echo area by using the Lisp printing ++functions with @code{t} as the stream (@pxref{Output Functions}), or ++explicitly. ++ ++@menu ++* Displaying Messages:: Explicitly displaying text in the echo area. ++* Progress:: Informing user about progress of a long operation. ++* Logging Messages:: Echo area messages are logged for the user. ++* Echo Area Customization:: Controlling the echo area. ++@end menu ++ ++@node Displaying Messages ++@subsection Displaying Messages in the Echo Area ++@cindex display message in echo area ++ ++ This section describes the functions for explicitly producing echo ++area messages. Many other Emacs features display messages there, too. ++ ++@defun message format-string &rest arguments ++This function displays a message in the echo area. The argument ++@var{format-string} is similar to a C language @code{printf} format ++string. See @code{format} in @ref{Formatting Strings}, for the details ++on the conversion specifications. @code{message} returns the ++constructed string. ++ ++In batch mode, @code{message} prints the message text on the standard ++error stream, followed by a newline. ++ ++If @var{format-string}, or strings among the @var{arguments}, have ++@code{face} text properties, these affect the way the message is displayed. ++ ++@c Emacs 19 feature ++If @var{format-string} is @code{nil} or the empty string, ++@code{message} clears the echo area; if the echo area has been ++expanded automatically, this brings it back to its normal size. ++If the minibuffer is active, this brings the minibuffer contents back ++onto the screen immediately. ++ ++@example ++@group ++(message "Minibuffer depth is %d." ++ (minibuffer-depth)) ++ @print{} Minibuffer depth is 0. ++@result{} "Minibuffer depth is 0." ++@end group ++ ++@group ++---------- Echo Area ---------- ++Minibuffer depth is 0. ++---------- Echo Area ---------- ++@end group ++@end example ++ ++To automatically display a message in the echo area or in a pop-buffer, ++depending on its size, use @code{display-message-or-buffer} (see below). ++@end defun ++ ++@defmac with-temp-message message &rest body ++This construct displays a message in the echo area temporarily, during ++the execution of @var{body}. It displays @var{message}, executes ++@var{body}, then returns the value of the last body form while restoring ++the previous echo area contents. ++@end defmac ++ ++@defun message-or-box format-string &rest arguments ++This function displays a message like @code{message}, but may display it ++in a dialog box instead of the echo area. If this function is called in ++a command that was invoked using the mouse---more precisely, if ++@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either ++@code{nil} or a list---then it uses a dialog box or pop-up menu to ++display the message. Otherwise, it uses the echo area. (This is the ++same criterion that @code{y-or-n-p} uses to make a similar decision; see ++@ref{Yes-or-No Queries}.) ++ ++You can force use of the mouse or of the echo area by binding ++@code{last-nonmenu-event} to a suitable value around the call. ++@end defun ++ ++@defun message-box format-string &rest arguments ++@anchor{message-box} ++This function displays a message like @code{message}, but uses a dialog ++box (or a pop-up menu) whenever that is possible. If it is impossible ++to use a dialog box or pop-up menu, because the terminal does not ++support them, then @code{message-box} uses the echo area, like ++@code{message}. ++@end defun ++ ++@defun display-message-or-buffer message &optional buffer-name not-this-window frame ++This function displays the message @var{message}, which may be either a ++string or a buffer. If it is shorter than the maximum height of the ++echo area, as defined by @code{max-mini-window-height}, it is displayed ++in the echo area, using @code{message}. Otherwise, ++@code{display-buffer} is used to show it in a pop-up buffer. ++ ++Returns either the string shown in the echo area, or when a pop-up ++buffer is used, the window used to display it. ++ ++If @var{message} is a string, then the optional argument ++@var{buffer-name} is the name of the buffer used to display it when a ++pop-up buffer is used, defaulting to @samp{*Message*}. In the case ++where @var{message} is a string and displayed in the echo area, it is ++not specified whether the contents are inserted into the buffer anyway. ++ ++The optional arguments @var{not-this-window} and @var{frame} are as for ++@code{display-buffer}, and only used if a buffer is displayed. ++@end defun ++ ++@defun current-message ++This function returns the message currently being displayed in the ++echo area, or @code{nil} if there is none. ++@end defun ++ ++@node Progress ++@subsection Reporting Operation Progress ++@cindex progress reporting ++ ++ When an operation can take a while to finish, you should inform the ++user about the progress it makes. This way the user can estimate ++remaining time and clearly see that Emacs is busy working, not hung. ++ ++ Functions listed in this section provide simple and efficient way of ++reporting operation progress. Here is a working example that does ++nothing useful: ++ ++@smallexample ++(let ((progress-reporter ++ (make-progress-reporter "Collecting mana for Emacs..." ++ 0 500))) ++ (dotimes (k 500) ++ (sit-for 0.01) ++ (progress-reporter-update progress-reporter k)) ++ (progress-reporter-done progress-reporter)) ++@end smallexample ++ ++@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time ++This function creates and returns a @dfn{progress reporter}---an ++object you will use as an argument for all other functions listed ++here. The idea is to precompute as much data as possible to make ++progress reporting very fast. ++ ++When this progress reporter is subsequently used, it will display ++@var{message} in the echo area, followed by progress percentage. ++@var{message} is treated as a simple string. If you need it to depend ++on a filename, for instance, use @code{format} before calling this ++function. ++ ++@var{min-value} and @var{max-value} arguments stand for starting and ++final states of your operation. For instance, if you scan a buffer, ++they should be the results of @code{point-min} and @code{point-max} ++correspondingly. It is required that @var{max-value} is greater than ++@var{min-value}. If you create progress reporter when some part of ++the operation has already been completed, then specify ++@var{current-value} argument. But normally you should omit it or set ++it to @code{nil}---it will default to @var{min-value} then. ++ ++Remaining arguments control the rate of echo area updates. Progress ++reporter will wait for at least @var{min-change} more percents of the ++operation to be completed before printing next message. ++@var{min-time} specifies the minimum time in seconds to pass between ++successive prints. It can be fractional. Depending on Emacs and ++system capabilities, progress reporter may or may not respect this ++last argument or do it with varying precision. Default value for ++@var{min-change} is 1 (one percent), for @var{min-time}---0.2 ++(seconds.) ++ ++This function calls @code{progress-reporter-update}, so the first ++message is printed immediately. ++@end defun ++ ++@defun progress-reporter-update reporter value ++This function does the main work of reporting progress of your ++operation. It displays the message of @var{reporter}, followed by ++progress percentage determined by @var{value}. If percentage is zero, ++or close enough according to the @var{min-change} and @var{min-time} ++arguments, then it is omitted from the output. ++ ++@var{reporter} must be the result of a call to ++@code{make-progress-reporter}. @var{value} specifies the current ++state of your operation and must be between @var{min-value} and ++@var{max-value} (inclusive) as passed to ++@code{make-progress-reporter}. For instance, if you scan a buffer, ++then @var{value} should be the result of a call to @code{point}. ++ ++This function respects @var{min-change} and @var{min-time} as passed ++to @code{make-progress-reporter} and so does not output new messages ++on every invocation. It is thus very fast and normally you should not ++try to reduce the number of calls to it: resulting overhead will most ++likely negate your effort. ++@end defun ++ ++@defun progress-reporter-force-update reporter value &optional new-message ++This function is similar to @code{progress-reporter-update} except ++that it prints a message in the echo area unconditionally. ++ ++The first two arguments have the same meaning as for ++@code{progress-reporter-update}. Optional @var{new-message} allows ++you to change the message of the @var{reporter}. Since this functions ++always updates the echo area, such a change will be immediately ++presented to the user. ++@end defun ++ ++@defun progress-reporter-done reporter ++This function should be called when the operation is finished. It ++prints the message of @var{reporter} followed by word ``done'' in the ++echo area. ++ ++You should always call this function and not hope for ++@code{progress-reporter-update} to print ``100%.'' Firstly, it may ++never print it, there are many good reasons for this not to happen. ++Secondly, ``done'' is more explicit. ++@end defun ++ ++@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} ++This is a convenience macro that works the same way as @code{dotimes} ++does, but also reports loop progress using the functions described ++above. It allows you to save some typing. ++ ++You can rewrite the example in the beginning of this node using ++this macro this way: ++ ++@example ++(dotimes-with-progress-reporter ++ (k 500) ++ "Collecting some mana for Emacs..." ++ (sit-for 0.01)) ++@end example ++@end defmac ++ ++@node Logging Messages ++@subsection Logging Messages in @samp{*Messages*} ++@cindex logging echo-area messages ++ ++ Almost all the messages displayed in the echo area are also recorded ++in the @samp{*Messages*} buffer so that the user can refer back to ++them. This includes all the messages that are output with ++@code{message}. ++ ++@defopt message-log-max ++This variable specifies how many lines to keep in the @samp{*Messages*} ++buffer. The value @code{t} means there is no limit on how many lines to ++keep. The value @code{nil} disables message logging entirely. Here's ++how to display a message and prevent it from being logged: ++ ++@example ++(let (message-log-max) ++ (message @dots{})) ++@end example ++@end defopt ++ ++ To make @samp{*Messages*} more convenient for the user, the logging ++facility combines successive identical messages. It also combines ++successive related messages for the sake of two cases: question ++followed by answer, and a series of progress messages. ++ ++ A ``question followed by an answer'' means two messages like the ++ones produced by @code{y-or-n-p}: the first is @samp{@var{question}}, ++and the second is @samp{@var{question}...@var{answer}}. The first ++message conveys no additional information beyond what's in the second, ++so logging the second message discards the first from the log. ++ ++ A ``series of progress messages'' means successive messages like ++those produced by @code{make-progress-reporter}. They have the form ++@samp{@var{base}...@var{how-far}}, where @var{base} is the same each ++time, while @var{how-far} varies. Logging each message in the series ++discards the previous one, provided they are consecutive. ++ ++ The functions @code{make-progress-reporter} and @code{y-or-n-p} ++don't have to do anything special to activate the message log ++combination feature. It operates whenever two consecutive messages ++are logged that share a common prefix ending in @samp{...}. ++ ++@node Echo Area Customization ++@subsection Echo Area Customization ++ ++ These variables control details of how the echo area works. ++ ++@defvar cursor-in-echo-area ++This variable controls where the cursor appears when a message is ++displayed in the echo area. If it is non-@code{nil}, then the cursor ++appears at the end of the message. Otherwise, the cursor appears at ++point---not in the echo area at all. ++ ++The value is normally @code{nil}; Lisp programs bind it to @code{t} ++for brief periods of time. ++@end defvar ++ ++@defvar echo-area-clear-hook ++This normal hook is run whenever the echo area is cleared---either by ++@code{(message nil)} or for any other reason. ++@end defvar ++ ++@defopt echo-keystrokes ++This variable determines how much time should elapse before command ++characters echo. Its value must be an integer or floating point number, ++which specifies the ++number of seconds to wait before echoing. If the user types a prefix ++key (such as @kbd{C-x}) and then delays this many seconds before ++continuing, the prefix key is echoed in the echo area. (Once echoing ++begins in a key sequence, all subsequent characters in the same key ++sequence are echoed immediately.) ++ ++If the value is zero, then command input is not echoed. ++@end defopt ++ ++@defvar message-truncate-lines ++Normally, displaying a long message resizes the echo area to display ++the entire message. But if the variable @code{message-truncate-lines} ++is non-@code{nil}, the echo area does not resize, and the message is ++truncated to fit it, as in Emacs 20 and before. ++@end defvar ++ ++ The variable @code{max-mini-window-height}, which specifies the ++maximum height for resizing minibuffer windows, also applies to the ++echo area (which is really a special use of the minibuffer window. ++@xref{Minibuffer Misc}.). ++ ++@node Warnings ++@section Reporting Warnings ++@cindex warnings ++ ++ @dfn{Warnings} are a facility for a program to inform the user of a ++possible problem, but continue running. ++ ++@menu ++* Warning Basics:: Warnings concepts and functions to report them. ++* Warning Variables:: Variables programs bind to customize their warnings. ++* Warning Options:: Variables users set to control display of warnings. ++@end menu ++ ++@node Warning Basics ++@subsection Warning Basics ++@cindex severity level ++ ++ Every warning has a textual message, which explains the problem for ++the user, and a @dfn{severity level} which is a symbol. Here are the ++possible severity levels, in order of decreasing severity, and their ++meanings: ++ ++@table @code ++@item :emergency ++A problem that will seriously impair Emacs operation soon ++if you do not attend to it promptly. ++@item :error ++A report of data or circumstances that are inherently wrong. ++@item :warning ++A report of data or circumstances that are not inherently wrong, but ++raise suspicion of a possible problem. ++@item :debug ++A report of information that may be useful if you are debugging. ++@end table ++ ++ When your program encounters invalid input data, it can either ++signal a Lisp error by calling @code{error} or @code{signal} or report ++a warning with severity @code{:error}. Signaling a Lisp error is the ++easiest thing to do, but it means the program cannot continue ++processing. If you want to take the trouble to implement a way to ++continue processing despite the bad data, then reporting a warning of ++severity @code{:error} is the right way to inform the user of the ++problem. For instance, the Emacs Lisp byte compiler can report an ++error that way and continue compiling other functions. (If the ++program signals a Lisp error and then handles it with ++@code{condition-case}, the user won't see the error message; it could ++show the message to the user by reporting it as a warning.) ++ ++@cindex warning type ++ Each warning has a @dfn{warning type} to classify it. The type is a ++list of symbols. The first symbol should be the custom group that you ++use for the program's user options. For example, byte compiler ++warnings use the warning type @code{(bytecomp)}. You can also ++subcategorize the warnings, if you wish, by using more symbols in the ++list. ++ ++@defun display-warning type message &optional level buffer-name ++This function reports a warning, using @var{message} as the message ++and @var{type} as the warning type. @var{level} should be the ++severity level, with @code{:warning} being the default. ++ ++@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer ++for logging the warning. By default, it is @samp{*Warnings*}. ++@end defun ++ ++@defun lwarn type level message &rest args ++This function reports a warning using the value of @code{(format ++@var{message} @var{args}...)} as the message. In other respects it is ++equivalent to @code{display-warning}. ++@end defun ++ ++@defun warn message &rest args ++This function reports a warning using the value of @code{(format ++@var{message} @var{args}...)} as the message, @code{(emacs)} as the ++type, and @code{:warning} as the severity level. It exists for ++compatibility only; we recommend not using it, because you should ++specify a specific warning type. ++@end defun ++ ++@node Warning Variables ++@subsection Warning Variables ++ ++ Programs can customize how their warnings appear by binding ++the variables described in this section. ++ ++@defvar warning-levels ++This list defines the meaning and severity order of the warning ++severity levels. Each element defines one severity level, ++and they are arranged in order of decreasing severity. ++ ++Each element has the form @code{(@var{level} @var{string} ++@var{function})}, where @var{level} is the severity level it defines. ++@var{string} specifies the textual description of this level. ++@var{string} should use @samp{%s} to specify where to put the warning ++type information, or it can omit the @samp{%s} so as not to include ++that information. ++ ++The optional @var{function}, if non-@code{nil}, is a function to call ++with no arguments, to get the user's attention. ++ ++Normally you should not change the value of this variable. ++@end defvar ++ ++@defvar warning-prefix-function ++If non-@code{nil}, the value is a function to generate prefix text for ++warnings. Programs can bind the variable to a suitable function. ++@code{display-warning} calls this function with the warnings buffer ++current, and the function can insert text in it. That text becomes ++the beginning of the warning message. ++ ++The function is called with two arguments, the severity level and its ++entry in @code{warning-levels}. It should return a list to use as the ++entry (this value need not be an actual member of ++@code{warning-levels}). By constructing this value, the function can ++change the severity of the warning, or specify different handling for ++a given severity level. ++ ++If the variable's value is @code{nil} then there is no function ++to call. ++@end defvar ++ ++@defvar warning-series ++Programs can bind this variable to @code{t} to say that the next ++warning should begin a series. When several warnings form a series, ++that means to leave point on the first warning of the series, rather ++than keep moving it for each warning so that it appears on the last one. ++The series ends when the local binding is unbound and ++@code{warning-series} becomes @code{nil} again. ++ ++The value can also be a symbol with a function definition. That is ++equivalent to @code{t}, except that the next warning will also call ++the function with no arguments with the warnings buffer current. The ++function can insert text which will serve as a header for the series ++of warnings. ++ ++Once a series has begun, the value is a marker which points to the ++buffer position in the warnings buffer of the start of the series. ++ ++The variable's normal value is @code{nil}, which means to handle ++each warning separately. ++@end defvar ++ ++@defvar warning-fill-prefix ++When this variable is non-@code{nil}, it specifies a fill prefix to ++use for filling each warning's text. ++@end defvar ++ ++@defvar warning-type-format ++This variable specifies the format for displaying the warning type ++in the warning message. The result of formatting the type this way ++gets included in the message under the control of the string in the ++entry in @code{warning-levels}. The default value is @code{" (%s)"}. ++If you bind it to @code{""} then the warning type won't appear at ++all. ++@end defvar ++ ++@node Warning Options ++@subsection Warning Options ++ ++ These variables are used by users to control what happens ++when a Lisp program reports a warning. ++ ++@defopt warning-minimum-level ++This user option specifies the minimum severity level that should be ++shown immediately to the user. The default is @code{:warning}, which ++means to immediately display all warnings except @code{:debug} ++warnings. ++@end defopt ++ ++@defopt warning-minimum-log-level ++This user option specifies the minimum severity level that should be ++logged in the warnings buffer. The default is @code{:warning}, which ++means to log all warnings except @code{:debug} warnings. ++@end defopt ++ ++@defopt warning-suppress-types ++This list specifies which warning types should not be displayed ++immediately for the user. Each element of the list should be a list ++of symbols. If its elements match the first elements in a warning ++type, then that warning is not displayed immediately. ++@end defopt ++ ++@defopt warning-suppress-log-types ++This list specifies which warning types should not be logged in the ++warnings buffer. Each element of the list should be a list of ++symbols. If it matches the first few elements in a warning type, then ++that warning is not logged. ++@end defopt ++ ++@node Invisible Text ++@section Invisible Text ++ ++@cindex invisible text ++You can make characters @dfn{invisible}, so that they do not appear on ++the screen, with the @code{invisible} property. This can be either a ++text property (@pxref{Text Properties}) or a property of an overlay ++(@pxref{Overlays}). Cursor motion also partly ignores these ++characters; if the command loop finds point within them, it moves ++point to the other side of them. ++ ++In the simplest case, any non-@code{nil} @code{invisible} property makes ++a character invisible. This is the default case---if you don't alter ++the default value of @code{buffer-invisibility-spec}, this is how the ++@code{invisible} property works. You should normally use @code{t} ++as the value of the @code{invisible} property if you don't plan ++to set @code{buffer-invisibility-spec} yourself. ++ ++More generally, you can use the variable @code{buffer-invisibility-spec} ++to control which values of the @code{invisible} property make text ++invisible. This permits you to classify the text into different subsets ++in advance, by giving them different @code{invisible} values, and ++subsequently make various subsets visible or invisible by changing the ++value of @code{buffer-invisibility-spec}. ++ ++Controlling visibility with @code{buffer-invisibility-spec} is ++especially useful in a program to display the list of entries in a ++database. It permits the implementation of convenient filtering ++commands to view just a part of the entries in the database. Setting ++this variable is very fast, much faster than scanning all the text in ++the buffer looking for properties to change. ++ ++@defvar buffer-invisibility-spec ++This variable specifies which kinds of @code{invisible} properties ++actually make a character invisible. Setting this variable makes it ++buffer-local. ++ ++@table @asis ++@item @code{t} ++A character is invisible if its @code{invisible} property is ++non-@code{nil}. This is the default. ++ ++@item a list ++Each element of the list specifies a criterion for invisibility; if a ++character's @code{invisible} property fits any one of these criteria, ++the character is invisible. The list can have two kinds of elements: ++ ++@table @code ++@item @var{atom} ++A character is invisible if its @code{invisible} property value ++is @var{atom} or if it is a list with @var{atom} as a member. ++ ++@item (@var{atom} . t) ++A character is invisible if its @code{invisible} property value is ++@var{atom} or if it is a list with @var{atom} as a member. Moreover, ++a sequence of such characters displays as an ellipsis. ++@end table ++@end table ++@end defvar ++ ++ Two functions are specifically provided for adding elements to ++@code{buffer-invisibility-spec} and removing elements from it. ++ ++@defun add-to-invisibility-spec element ++This function adds the element @var{element} to ++@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec} ++was @code{t}, it changes to a list, @code{(t)}, so that text whose ++@code{invisible} property is @code{t} remains invisible. ++@end defun ++ ++@defun remove-from-invisibility-spec element ++This removes the element @var{element} from ++@code{buffer-invisibility-spec}. This does nothing if @var{element} ++is not in the list. ++@end defun ++ ++ A convention for use of @code{buffer-invisibility-spec} is that a ++major mode should use the mode's own name as an element of ++@code{buffer-invisibility-spec} and as the value of the ++@code{invisible} property: ++ ++@example ++;; @r{If you want to display an ellipsis:} ++(add-to-invisibility-spec '(my-symbol . t)) ++;; @r{If you don't want ellipsis:} ++(add-to-invisibility-spec 'my-symbol) ++ ++(overlay-put (make-overlay beginning end) ++ 'invisible 'my-symbol) ++ ++;; @r{When done with the overlays:} ++(remove-from-invisibility-spec '(my-symbol . t)) ++;; @r{Or respectively:} ++(remove-from-invisibility-spec 'my-symbol) ++@end example ++ ++ You can check for invisibility using the following function: ++ ++@defun invisible-p pos-or-prop ++If @var{pos-or-prop} is a marker or number, this function returns a ++non-@code{nil} value if the text at that position is invisible. ++ ++If @var{pos-or-prop} is any other kind of Lisp object, that is taken ++to mean a possible value of the @code{invisible} text or overlay ++property. In that case, this function returns a non-@code{nil} value ++if that value would cause text to become invisible, based on the ++current value of @code{buffer-invisibility-spec}. ++@end defun ++ ++@vindex line-move-ignore-invisible ++ Ordinarily, functions that operate on text or move point do not care ++whether the text is invisible. The user-level line motion commands ++ignore invisible newlines if @code{line-move-ignore-invisible} is ++non-@code{nil} (the default), but only because they are explicitly ++programmed to do so. ++ ++ However, if a command ends with point inside or immediately before ++invisible text, the main editing loop moves point further forward or ++further backward (in the same direction that the command already moved ++it) until that condition is no longer true. Thus, if the command ++moved point back into an invisible range, Emacs moves point back to ++the beginning of that range, and then back one more character. If the ++command moved point forward into an invisible range, Emacs moves point ++forward up to the first visible character that follows the invisible ++text. ++ ++ Incremental search can make invisible overlays visible temporarily ++and/or permanently when a match includes invisible text. To enable ++this, the overlay should have a non-@code{nil} ++@code{isearch-open-invisible} property. The property value should be a ++function to be called with the overlay as an argument. This function ++should make the overlay visible permanently; it is used when the match ++overlaps the overlay on exit from the search. ++ ++ During the search, such overlays are made temporarily visible by ++temporarily modifying their invisible and intangible properties. If you ++want this to be done differently for a certain overlay, give it an ++@code{isearch-open-invisible-temporary} property which is a function. ++The function is called with two arguments: the first is the overlay, and ++the second is @code{nil} to make the overlay visible, or @code{t} to ++make it invisible again. ++ ++@node Selective Display ++@section Selective Display ++@c @cindex selective display Duplicates selective-display ++ ++ @dfn{Selective display} refers to a pair of related features for ++hiding certain lines on the screen. ++ ++ The first variant, explicit selective display, is designed for use ++in a Lisp program: it controls which lines are hidden by altering the ++text. This kind of hiding in some ways resembles the effect of the ++@code{invisible} property (@pxref{Invisible Text}), but the two ++features are different and do not work the same way. ++ ++ In the second variant, the choice of lines to hide is made ++automatically based on indentation. This variant is designed to be a ++user-level feature. ++ ++ The way you control explicit selective display is by replacing a ++newline (control-j) with a carriage return (control-m). The text that ++was formerly a line following that newline is now hidden. Strictly ++speaking, it is temporarily no longer a line at all, since only ++newlines can separate lines; it is now part of the previous line. ++ ++ Selective display does not directly affect editing commands. For ++example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly ++into hidden text. However, the replacement of newline characters with ++carriage return characters affects some editing commands. For ++example, @code{next-line} skips hidden lines, since it searches only ++for newlines. Modes that use selective display can also define ++commands that take account of the newlines, or that control which ++parts of the text are hidden. ++ ++ When you write a selectively displayed buffer into a file, all the ++control-m's are output as newlines. This means that when you next read ++in the file, it looks OK, with nothing hidden. The selective display ++effect is seen only within Emacs. ++ ++@defvar selective-display ++This buffer-local variable enables selective display. This means that ++lines, or portions of lines, may be made hidden. ++ ++@itemize @bullet ++@item ++If the value of @code{selective-display} is @code{t}, then the character ++control-m marks the start of hidden text; the control-m, and the rest ++of the line following it, are not displayed. This is explicit selective ++display. ++ ++@item ++If the value of @code{selective-display} is a positive integer, then ++lines that start with more than that many columns of indentation are not ++displayed. ++@end itemize ++ ++When some portion of a buffer is hidden, the vertical movement ++commands operate as if that portion did not exist, allowing a single ++@code{next-line} command to skip any number of hidden lines. ++However, character movement commands (such as @code{forward-char}) do ++not skip the hidden portion, and it is possible (if tricky) to insert ++or delete text in an hidden portion. ++ ++In the examples below, we show the @emph{display appearance} of the ++buffer @code{foo}, which changes with the value of ++@code{selective-display}. The @emph{contents} of the buffer do not ++change. ++ ++@example ++@group ++(setq selective-display nil) ++ @result{} nil ++ ++---------- Buffer: foo ---------- ++1 on this column ++ 2on this column ++ 3n this column ++ 3n this column ++ 2on this column ++1 on this column ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(setq selective-display 2) ++ @result{} 2 ++ ++---------- Buffer: foo ---------- ++1 on this column ++ 2on this column ++ 2on this column ++1 on this column ++---------- Buffer: foo ---------- ++@end group ++@end example ++@end defvar ++ ++@defopt selective-display-ellipses ++If this buffer-local variable is non-@code{nil}, then Emacs displays ++@samp{@dots{}} at the end of a line that is followed by hidden text. ++This example is a continuation of the previous one. ++ ++@example ++@group ++(setq selective-display-ellipses t) ++ @result{} t ++ ++---------- Buffer: foo ---------- ++1 on this column ++ 2on this column ... ++ 2on this column ++1 on this column ++---------- Buffer: foo ---------- ++@end group ++@end example ++ ++You can use a display table to substitute other text for the ellipsis ++(@samp{@dots{}}). @xref{Display Tables}. ++@end defopt ++ ++@node Temporary Displays ++@section Temporary Displays ++ ++ Temporary displays are used by Lisp programs to put output into a ++buffer and then present it to the user for perusal rather than for ++editing. Many help commands use this feature. ++ ++@defspec with-output-to-temp-buffer buffer-name forms@dots{} ++This function executes @var{forms} while arranging to insert any output ++they print into the buffer named @var{buffer-name}, which is first ++created if necessary, and put into Help mode. Finally, the buffer is ++displayed in some window, but not selected. ++ ++If the @var{forms} do not change the major mode in the output buffer, ++so that it is still Help mode at the end of their execution, then ++@code{with-output-to-temp-buffer} makes this buffer read-only at the ++end, and also scans it for function and variable names to make them ++into clickable cross-references. @xref{Docstring hyperlinks, , Tips ++for Documentation Strings}, in particular the item on hyperlinks in ++documentation strings, for more details. ++ ++The string @var{buffer-name} specifies the temporary buffer, which ++need not already exist. The argument must be a string, not a buffer. ++The buffer is erased initially (with no questions asked), and it is ++marked as unmodified after @code{with-output-to-temp-buffer} exits. ++ ++@code{with-output-to-temp-buffer} binds @code{standard-output} to the ++temporary buffer, then it evaluates the forms in @var{forms}. Output ++using the Lisp output functions within @var{forms} goes by default to ++that buffer (but screen display and messages in the echo area, although ++they are ``output'' in the general sense of the word, are not affected). ++@xref{Output Functions}. ++ ++Several hooks are available for customizing the behavior ++of this construct; they are listed below. ++ ++The value of the last form in @var{forms} is returned. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++ This is the contents of foo. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(with-output-to-temp-buffer "foo" ++ (print 20) ++ (print standard-output)) ++@result{} # ++ ++---------- Buffer: foo ---------- ++20 ++ ++# ++ ++---------- Buffer: foo ---------- ++@end group ++@end example ++@end defspec ++ ++@defopt temp-buffer-show-function ++If this variable is non-@code{nil}, @code{with-output-to-temp-buffer} ++calls it as a function to do the job of displaying a help buffer. The ++function gets one argument, which is the buffer it should display. ++ ++It is a good idea for this function to run @code{temp-buffer-show-hook} ++just as @code{with-output-to-temp-buffer} normally would, inside of ++@code{save-selected-window} and with the chosen window and buffer ++selected. ++@end defopt ++ ++@defvar temp-buffer-setup-hook ++This normal hook is run by @code{with-output-to-temp-buffer} before ++evaluating @var{body}. When the hook runs, the temporary buffer is ++current. This hook is normally set up with a function to put the ++buffer in Help mode. ++@end defvar ++ ++@defvar temp-buffer-show-hook ++This normal hook is run by @code{with-output-to-temp-buffer} after ++displaying the temporary buffer. When the hook runs, the temporary buffer ++is current, and the window it was displayed in is selected. ++@end defvar ++ ++@defun momentary-string-display string position &optional char message ++This function momentarily displays @var{string} in the current buffer at ++@var{position}. It has no effect on the undo list or on the buffer's ++modification status. ++ ++The momentary display remains until the next input event. If the next ++input event is @var{char}, @code{momentary-string-display} ignores it ++and returns. Otherwise, that event remains buffered for subsequent use ++as input. Thus, typing @var{char} will simply remove the string from ++the display, while typing (say) @kbd{C-f} will remove the string from ++the display and later (presumably) move point forward. The argument ++@var{char} is a space by default. ++ ++The return value of @code{momentary-string-display} is not meaningful. ++ ++If the string @var{string} does not contain control characters, you can ++do the same job in a more general way by creating (and then subsequently ++deleting) an overlay with a @code{before-string} property. ++@xref{Overlay Properties}. ++ ++If @var{message} is non-@code{nil}, it is displayed in the echo area ++while @var{string} is displayed in the buffer. If it is @code{nil}, a ++default message says to type @var{char} to continue. ++ ++In this example, point is initially located at the beginning of the ++second line: ++ ++@example ++@group ++---------- Buffer: foo ---------- ++This is the contents of foo. ++@point{}Second line. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(momentary-string-display ++ "**** Important Message! ****" ++ (point) ?\r ++ "Type RET when done reading") ++@result{} t ++@end group ++ ++@group ++---------- Buffer: foo ---------- ++This is the contents of foo. ++**** Important Message! ****Second line. ++---------- Buffer: foo ---------- ++ ++---------- Echo Area ---------- ++Type RET when done reading ++---------- Echo Area ---------- ++@end group ++@end example ++@end defun ++ ++@node Overlays ++@section Overlays ++@cindex overlays ++ ++You can use @dfn{overlays} to alter the appearance of a buffer's text on ++the screen, for the sake of presentation features. An overlay is an ++object that belongs to a particular buffer, and has a specified ++beginning and end. It also has properties that you can examine and set; ++these affect the display of the text within the overlay. ++ ++@cindex scalability of overlays ++The visual effect of an overlay is the same as of the corresponding ++text property (@pxref{Text Properties}). However, due to a different ++implementation, overlays generally don't scale well (many operations ++take a time that is proportional to the number of overlays in the ++buffer). If you need to affect the visual appearance of many portions ++in the buffer, we recommend using text properties. ++ ++An overlay uses markers to record its beginning and end; thus, ++editing the text of the buffer adjusts the beginning and end of each ++overlay so that it stays with the text. When you create the overlay, ++you can specify whether text inserted at the beginning should be ++inside the overlay or outside, and likewise for the end of the overlay. ++ ++@menu ++* Managing Overlays:: Creating and moving overlays. ++* Overlay Properties:: How to read and set properties. ++ What properties do to the screen display. ++* Finding Overlays:: Searching for overlays. ++@end menu ++ ++@node Managing Overlays ++@subsection Managing Overlays ++ ++ This section describes the functions to create, delete and move ++overlays, and to examine their contents. Overlay changes are not ++recorded in the buffer's undo list, since the overlays are not ++part of the buffer's contents. ++ ++@defun overlayp object ++This function returns @code{t} if @var{object} is an overlay. ++@end defun ++ ++@defun make-overlay start end &optional buffer front-advance rear-advance ++This function creates and returns an overlay that belongs to ++@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} ++and @var{end} must specify buffer positions; they may be integers or ++markers. If @var{buffer} is omitted, the overlay is created in the ++current buffer. ++ ++The arguments @var{front-advance} and @var{rear-advance} specify the ++marker insertion type for the start of the overlay and for the end of ++the overlay, respectively. @xref{Marker Insertion Types}. If they ++are both @code{nil}, the default, then the overlay extends to include ++any text inserted at the beginning, but not text inserted at the end. ++If @var{front-advance} is non-@code{nil}, text inserted at the ++beginning of the overlay is excluded from the overlay. If ++@var{rear-advance} is non-@code{nil}, text inserted at the end of the ++overlay is included in the overlay. ++@end defun ++ ++@defun overlay-start overlay ++This function returns the position at which @var{overlay} starts, ++as an integer. ++@end defun ++ ++@defun overlay-end overlay ++This function returns the position at which @var{overlay} ends, ++as an integer. ++@end defun ++ ++@defun overlay-buffer overlay ++This function returns the buffer that @var{overlay} belongs to. It ++returns @code{nil} if @var{overlay} has been deleted. ++@end defun ++ ++@defun delete-overlay overlay ++This function deletes @var{overlay}. The overlay continues to exist as ++a Lisp object, and its property list is unchanged, but it ceases to be ++attached to the buffer it belonged to, and ceases to have any effect on ++display. ++ ++A deleted overlay is not permanently disconnected. You can give it a ++position in a buffer again by calling @code{move-overlay}. ++@end defun ++ ++@defun move-overlay overlay start end &optional buffer ++This function moves @var{overlay} to @var{buffer}, and places its bounds ++at @var{start} and @var{end}. Both arguments @var{start} and @var{end} ++must specify buffer positions; they may be integers or markers. ++ ++If @var{buffer} is omitted, @var{overlay} stays in the same buffer it ++was already associated with; if @var{overlay} was deleted, it goes into ++the current buffer. ++ ++The return value is @var{overlay}. ++ ++This is the only valid way to change the endpoints of an overlay. Do ++not try modifying the markers in the overlay by hand, as that fails to ++update other vital data structures and can cause some overlays to be ++``lost.'' ++@end defun ++ ++@defun remove-overlays &optional start end name value ++This function removes all the overlays between @var{start} and ++@var{end} whose property @var{name} has the value @var{value}. It can ++move the endpoints of the overlays in the region, or split them. ++ ++If @var{name} is omitted or @code{nil}, it means to delete all overlays in ++the specified region. If @var{start} and/or @var{end} are omitted or ++@code{nil}, that means the beginning and end of the buffer respectively. ++Therefore, @code{(remove-overlays)} removes all the overlays in the ++current buffer. ++@end defun ++ ++ Here are some examples: ++ ++@example ++;; @r{Create an overlay.} ++(setq foo (make-overlay 1 10)) ++ @result{} # ++(overlay-start foo) ++ @result{} 1 ++(overlay-end foo) ++ @result{} 10 ++(overlay-buffer foo) ++ @result{} # ++;; @r{Give it a property we can check later.} ++(overlay-put foo 'happy t) ++ @result{} t ++;; @r{Verify the property is present.} ++(overlay-get foo 'happy) ++ @result{} t ++;; @r{Move the overlay.} ++(move-overlay foo 5 20) ++ @result{} # ++(overlay-start foo) ++ @result{} 5 ++(overlay-end foo) ++ @result{} 20 ++;; @r{Delete the overlay.} ++(delete-overlay foo) ++ @result{} nil ++;; @r{Verify it is deleted.} ++foo ++ @result{} # ++;; @r{A deleted overlay has no position.} ++(overlay-start foo) ++ @result{} nil ++(overlay-end foo) ++ @result{} nil ++(overlay-buffer foo) ++ @result{} nil ++;; @r{Undelete the overlay.} ++(move-overlay foo 1 20) ++ @result{} # ++;; @r{Verify the results.} ++(overlay-start foo) ++ @result{} 1 ++(overlay-end foo) ++ @result{} 20 ++(overlay-buffer foo) ++ @result{} # ++;; @r{Moving and deleting the overlay does not change its properties.} ++(overlay-get foo 'happy) ++ @result{} t ++@end example ++ ++ Emacs stores the overlays of each buffer in two lists, divided ++around an arbitrary ``center position.'' One list extends backwards ++through the buffer from that center position, and the other extends ++forwards from that center position. The center position can be anywhere ++in the buffer. ++ ++@defun overlay-recenter pos ++This function recenters the overlays of the current buffer around ++position @var{pos}. That makes overlay lookup faster for positions ++near @var{pos}, but slower for positions far away from @var{pos}. ++@end defun ++ ++ A loop that scans the buffer forwards, creating overlays, can run ++faster if you do @code{(overlay-recenter (point-max))} first. ++ ++@node Overlay Properties ++@subsection Overlay Properties ++ ++ Overlay properties are like text properties in that the properties that ++alter how a character is displayed can come from either source. But in ++most respects they are different. @xref{Text Properties}, for comparison. ++ ++ Text properties are considered a part of the text; overlays and ++their properties are specifically considered not to be part of the ++text. Thus, copying text between various buffers and strings ++preserves text properties, but does not try to preserve overlays. ++Changing a buffer's text properties marks the buffer as modified, ++while moving an overlay or changing its properties does not. Unlike ++text property changes, overlay property changes are not recorded in ++the buffer's undo list. ++ ++ Since more than one overlay can specify a property value for the ++same character, Emacs lets you specify a priority value of each ++overlay. You should not make assumptions about which overlay will ++prevail when there is a conflict and they have the same priority. ++ ++ These functions read and set the properties of an overlay: ++ ++@defun overlay-get overlay prop ++This function returns the value of property @var{prop} recorded in ++@var{overlay}, if any. If @var{overlay} does not record any value for ++that property, but it does have a @code{category} property which is a ++symbol, that symbol's @var{prop} property is used. Otherwise, the value ++is @code{nil}. ++@end defun ++ ++@defun overlay-put overlay prop value ++This function sets the value of property @var{prop} recorded in ++@var{overlay} to @var{value}. It returns @var{value}. ++@end defun ++ ++@defun overlay-properties overlay ++This returns a copy of the property list of @var{overlay}. ++@end defun ++ ++ See also the function @code{get-char-property} which checks both ++overlay properties and text properties for a given character. ++@xref{Examining Properties}. ++ ++ Many overlay properties have special meanings; here is a table ++of them: ++ ++@table @code ++@item priority ++@kindex priority @r{(overlay property)} ++This property's value (which should be a nonnegative integer number) ++determines the priority of the overlay. No priority, or @code{nil}, ++means zero. ++ ++The priority matters when two or more overlays cover the same ++character and both specify the same property; the one whose ++@code{priority} value is larger overrides the other. For the ++@code{face} property, the higher priority overlay's value does not ++completely override the other value; instead, its face attributes ++override the face attributes of the lower priority @code{face} ++property. ++ ++Currently, all overlays take priority over text properties. Please ++avoid using negative priority values, as we have not yet decided just ++what they should mean. ++ ++@item window ++@kindex window @r{(overlay property)} ++If the @code{window} property is non-@code{nil}, then the overlay ++applies only on that window. ++ ++@item category ++@kindex category @r{(overlay property)} ++If an overlay has a @code{category} property, we call it the ++@dfn{category} of the overlay. It should be a symbol. The properties ++of the symbol serve as defaults for the properties of the overlay. ++ ++@item face ++@kindex face @r{(overlay property)} ++This property controls the way text is displayed---for example, which ++font and which colors. @xref{Faces}, for more information. ++ ++In the simplest case, the value is a face name. It can also be a list; ++then each element can be any of these possibilities: ++ ++@itemize @bullet ++@item ++A face name (a symbol or string). ++ ++@item ++A property list of face attributes. This has the form (@var{keyword} ++@var{value} @dots{}), where each @var{keyword} is a face attribute ++name and @var{value} is a meaningful value for that attribute. With ++this feature, you do not need to create a face each time you want to ++specify a particular attribute for certain text. @xref{Face ++Attributes}. ++ ++@item ++A cons cell, either of the form @code{(foreground-color . @var{color-name})} or ++@code{(background-color . @var{color-name})}. These elements specify ++just the foreground color or just the background color. ++ ++@code{(foreground-color . @var{color-name})} has the same effect as ++@code{(:foreground @var{color-name})}; likewise for the background. ++@end itemize ++ ++@item mouse-face ++@kindex mouse-face @r{(overlay property)} ++This property is used instead of @code{face} when the mouse is within ++the range of the overlay. ++ ++@item display ++@kindex display @r{(overlay property)} ++This property activates various features that change the ++way text is displayed. For example, it can make text appear taller ++or shorter, higher or lower, wider or narrower, or replaced with an image. ++@xref{Display Property}. ++ ++@item help-echo ++@kindex help-echo @r{(overlay property)} ++If an overlay has a @code{help-echo} property, then when you move the ++mouse onto the text in the overlay, Emacs displays a help string in the ++echo area, or in the tooltip window. For details see @ref{Text ++help-echo}. ++ ++@item modification-hooks ++@kindex modification-hooks @r{(overlay property)} ++This property's value is a list of functions to be called if any ++character within the overlay is changed or if text is inserted strictly ++within the overlay. ++ ++The hook functions are called both before and after each change. ++If the functions save the information they receive, and compare notes ++between calls, they can determine exactly what change has been made ++in the buffer text. ++ ++When called before a change, each function receives four arguments: the ++overlay, @code{nil}, and the beginning and end of the text range to be ++modified. ++ ++When called after a change, each function receives five arguments: the ++overlay, @code{t}, the beginning and end of the text range just ++modified, and the length of the pre-change text replaced by that range. ++(For an insertion, the pre-change length is zero; for a deletion, that ++length is the number of characters deleted, and the post-change ++beginning and end are equal.) ++ ++If these functions modify the buffer, they should bind ++@code{inhibit-modification-hooks} to @code{t} around doing so, to ++avoid confusing the internal mechanism that calls these hooks. ++ ++Text properties also support the @code{modification-hooks} property, ++but the details are somewhat different (@pxref{Special Properties}). ++ ++@item insert-in-front-hooks ++@kindex insert-in-front-hooks @r{(overlay property)} ++This property's value is a list of functions to be called before and ++after inserting text right at the beginning of the overlay. The calling ++conventions are the same as for the @code{modification-hooks} functions. ++ ++@item insert-behind-hooks ++@kindex insert-behind-hooks @r{(overlay property)} ++This property's value is a list of functions to be called before and ++after inserting text right at the end of the overlay. The calling ++conventions are the same as for the @code{modification-hooks} functions. ++ ++@item invisible ++@kindex invisible @r{(overlay property)} ++The @code{invisible} property can make the text in the overlay ++invisible, which means that it does not appear on the screen. ++@xref{Invisible Text}, for details. ++ ++@item intangible ++@kindex intangible @r{(overlay property)} ++The @code{intangible} property on an overlay works just like the ++@code{intangible} text property. @xref{Special Properties}, for details. ++ ++@item isearch-open-invisible ++This property tells incremental search how to make an invisible overlay ++visible, permanently, if the final match overlaps it. @xref{Invisible ++Text}. ++ ++@item isearch-open-invisible-temporary ++This property tells incremental search how to make an invisible overlay ++visible, temporarily, during the search. @xref{Invisible Text}. ++ ++@item before-string ++@kindex before-string @r{(overlay property)} ++This property's value is a string to add to the display at the beginning ++of the overlay. The string does not appear in the buffer in any ++sense---only on the screen. ++ ++@item after-string ++@kindex after-string @r{(overlay property)} ++This property's value is a string to add to the display at the end of ++the overlay. The string does not appear in the buffer in any ++sense---only on the screen. ++ ++@item line-prefix ++This property specifies a display spec to prepend to each ++non-continuation line at display-time. @xref{Truncation}. ++ ++@itemx wrap-prefix ++This property specifies a display spec to prepend to each continuation ++line at display-time. @xref{Truncation}. ++ ++@item evaporate ++@kindex evaporate @r{(overlay property)} ++If this property is non-@code{nil}, the overlay is deleted automatically ++if it becomes empty (i.e., if its length becomes zero). If you give ++an empty overlay a non-@code{nil} @code{evaporate} property, that deletes ++it immediately. ++ ++@item local-map ++@cindex keymap of character (and overlays) ++@kindex local-map @r{(overlay property)} ++If this property is non-@code{nil}, it specifies a keymap for a portion ++of the text. The property's value replaces the buffer's local map, when ++the character after point is within the overlay. @xref{Active Keymaps}. ++ ++@item keymap ++@kindex keymap @r{(overlay property)} ++The @code{keymap} property is similar to @code{local-map} but overrides the ++buffer's local map (and the map specified by the @code{local-map} ++property) rather than replacing it. ++@end table ++ ++The @code{local-map} and @code{keymap} properties do not affect a ++string displayed by the @code{before-string}, @code{after-string}, or ++@code{display} properties. This is only relevant for mouse clicks and ++other mouse events that fall on the string, since point is never on ++the string. To bind special mouse events for the string, assign it a ++@code{local-map} or @code{keymap} text property. @xref{Special ++Properties}. ++ ++@node Finding Overlays ++@subsection Searching for Overlays ++ ++@defun overlays-at pos ++This function returns a list of all the overlays that cover the ++character at position @var{pos} in the current buffer. The list is in ++no particular order. An overlay contains position @var{pos} if it ++begins at or before @var{pos}, and ends after @var{pos}. ++ ++To illustrate usage, here is a Lisp function that returns a list of the ++overlays that specify property @var{prop} for the character at point: ++ ++@smallexample ++(defun find-overlays-specifying (prop) ++ (let ((overlays (overlays-at (point))) ++ found) ++ (while overlays ++ (let ((overlay (car overlays))) ++ (if (overlay-get overlay prop) ++ (setq found (cons overlay found)))) ++ (setq overlays (cdr overlays))) ++ found)) ++@end smallexample ++@end defun ++ ++@defun overlays-in beg end ++This function returns a list of the overlays that overlap the region ++@var{beg} through @var{end}. ``Overlap'' means that at least one ++character is contained within the overlay and also contained within the ++specified region; however, empty overlays are included in the result if ++they are located at @var{beg}, strictly between @var{beg} and @var{end}, ++or at @var{end} when @var{end} denotes the position at the end of the ++buffer. ++@end defun ++ ++@defun next-overlay-change pos ++This function returns the buffer position of the next beginning or end ++of an overlay, after @var{pos}. If there is none, it returns ++@code{(point-max)}. ++@end defun ++ ++@defun previous-overlay-change pos ++This function returns the buffer position of the previous beginning or ++end of an overlay, before @var{pos}. If there is none, it returns ++@code{(point-min)}. ++@end defun ++ ++ As an example, here's a simplified (and inefficient) version of the ++primitive function @code{next-single-char-property-change} ++(@pxref{Property Search}). It searches forward from position ++@var{pos} for the next position where the value of a given property ++@code{prop}, as obtained from either overlays or text properties, ++changes. ++ ++@smallexample ++(defun next-single-char-property-change (position prop) ++ (save-excursion ++ (goto-char position) ++ (let ((propval (get-char-property (point) prop))) ++ (while (and (not (eobp)) ++ (eq (get-char-property (point) prop) propval)) ++ (goto-char (min (next-overlay-change (point)) ++ (next-single-property-change (point) prop))))) ++ (point))) ++@end smallexample ++ ++@node Width ++@section Width ++ ++Since not all characters have the same width, these functions let you ++check the width of a character. @xref{Primitive Indent}, and ++@ref{Screen Lines}, for related functions. ++ ++@defun char-width char ++This function returns the width in columns of the character @var{char}, ++if it were displayed in the current buffer and the selected window. ++@end defun ++ ++@defun string-width string ++This function returns the width in columns of the string @var{string}, ++if it were displayed in the current buffer and the selected window. ++@end defun ++ ++@defun truncate-string-to-width string width &optional start-column padding ellipsis ++This function returns the part of @var{string} that fits within ++@var{width} columns, as a new string. ++ ++If @var{string} does not reach @var{width}, then the result ends where ++@var{string} ends. If one multi-column character in @var{string} ++extends across the column @var{width}, that character is not included in ++the result. Thus, the result can fall short of @var{width} but cannot ++go beyond it. ++ ++The optional argument @var{start-column} specifies the starting column. ++If this is non-@code{nil}, then the first @var{start-column} columns of ++the string are omitted from the value. If one multi-column character in ++@var{string} extends across the column @var{start-column}, that ++character is not included. ++ ++The optional argument @var{padding}, if non-@code{nil}, is a padding ++character added at the beginning and end of the result string, to extend ++it to exactly @var{width} columns. The padding character is used at the ++end of the result if it falls short of @var{width}. It is also used at ++the beginning of the result if one multi-column character in ++@var{string} extends across the column @var{start-column}. ++ ++If @var{ellipsis} is non-@code{nil}, it should be a string which will ++replace the end of @var{str} (including any padding) if it extends ++beyond @var{end-column}, unless the display width of @var{str} is ++equal to or less than the display width of @var{ellipsis}. If ++@var{ellipsis} is non-@code{nil} and not a string, it stands for ++@code{"..."}. ++ ++@example ++(truncate-string-to-width "\tab\t" 12 4) ++ @result{} "ab" ++(truncate-string-to-width "\tab\t" 12 4 ?\s) ++ @result{} " ab " ++@end example ++@end defun ++ ++@node Line Height ++@section Line Height ++@cindex line height ++ ++ The total height of each display line consists of the height of the ++contents of the line, plus optional additional vertical line spacing ++above or below the display line. ++ ++ The height of the line contents is the maximum height of any ++character or image on that display line, including the final newline ++if there is one. (A display line that is continued doesn't include a ++final newline.) That is the default line height, if you do nothing to ++specify a greater height. (In the most common case, this equals the ++height of the default frame font.) ++ ++ There are several ways to explicitly specify a larger line height, ++either by specifying an absolute height for the display line, or by ++specifying vertical space. However, no matter what you specify, the ++actual line height can never be less than the default. ++ ++@kindex line-height @r{(text property)} ++ A newline can have a @code{line-height} text or overlay property ++that controls the total height of the display line ending in that ++newline. ++ ++ If the property value is @code{t}, the newline character has no ++effect on the displayed height of the line---the visible contents ++alone determine the height. This is useful for tiling small images ++(or image slices) without adding blank areas between the images. ++ ++ If the property value is a list of the form @code{(@var{height} ++@var{total})}, that adds extra space @emph{below} the display line. ++First Emacs uses @var{height} as a height spec to control extra space ++@emph{above} the line; then it adds enough space @emph{below} the line ++to bring the total line height up to @var{total}. In this case, the ++other ways to specify the line spacing are ignored. ++ ++ Any other kind of property value is a height spec, which translates ++into a number---the specified line height. There are several ways to ++write a height spec; here's how each of them translates into a number: ++ ++@table @code ++@item @var{integer} ++If the height spec is a positive integer, the height value is that integer. ++@item @var{float} ++If the height spec is a float, @var{float}, the numeric height value ++is @var{float} times the frame's default line height. ++@item (@var{face} . @var{ratio}) ++If the height spec is a cons of the format shown, the numeric height ++is @var{ratio} times the height of face @var{face}. @var{ratio} can ++be any type of number, or @code{nil} which means a ratio of 1. ++If @var{face} is @code{t}, it refers to the current face. ++@item (nil . @var{ratio}) ++If the height spec is a cons of the format shown, the numeric height ++is @var{ratio} times the height of the contents of the line. ++@end table ++ ++ Thus, any valid height spec determines the height in pixels, one way ++or another. If the line contents' height is less than that, Emacs ++adds extra vertical space above the line to achieve the specified ++total height. ++ ++ If you don't specify the @code{line-height} property, the line's ++height consists of the contents' height plus the line spacing. ++There are several ways to specify the line spacing for different ++parts of Emacs text. ++ ++@vindex default-line-spacing ++ On graphical terminals, you can specify the line spacing for all ++lines in a frame, using the @code{line-spacing} frame parameter ++(@pxref{Layout Parameters}). However, if the variable ++@code{default-line-spacing} is non-@code{nil}, it overrides the ++frame's @code{line-spacing} parameter. An integer value specifies the ++number of pixels put below lines. A floating point number specifies ++the spacing relative to the frame's default line height. ++ ++@vindex line-spacing ++ You can specify the line spacing for all lines in a buffer via the ++buffer-local @code{line-spacing} variable. An integer value specifies ++the number of pixels put below lines. A floating point number ++specifies the spacing relative to the default frame line height. This ++overrides line spacings specified for the frame. ++ ++@kindex line-spacing @r{(text property)} ++ Finally, a newline can have a @code{line-spacing} text or overlay ++property that overrides the default frame line spacing and the buffer ++local @code{line-spacing} variable, for the display line ending in ++that newline. ++ ++ One way or another, these mechanisms specify a Lisp value for the ++spacing of each line. The value is a height spec, and it translates ++into a Lisp value as described above. However, in this case the ++numeric height value specifies the line spacing, rather than the line ++height. ++ ++ On text-only terminals, the line spacing cannot be altered. ++ ++@node Faces ++@section Faces ++@cindex faces ++ ++ A @dfn{face} is a collection of graphical attributes for displaying ++text: font family, foreground color, background color, optional ++underlining, and so on. Faces control how buffer text is displayed, ++and how some parts of the frame, such as the mode-line, are displayed. ++@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of ++faces Emacs normally comes with. ++ ++@cindex face id ++ For most purposes, you refer to a face in Lisp programs using its ++@dfn{face name}. This is either a string or (equivalently) a Lisp ++symbol whose name is equal to that string. ++ ++@defun facep object ++This function returns a non-@code{nil} value if @var{object} is a Lisp ++symbol or string that names a face. Otherwise, it returns @code{nil}. ++@end defun ++ ++ Each face name is meaningful for all frames, and by default it has ++the same meaning in all frames. But you can arrange to give a ++particular face name a special meaning in one frame if you wish. ++ ++@menu ++* Defining Faces:: How to define a face with @code{defface}. ++* Face Attributes:: What is in a face? ++* Attribute Functions:: Functions to examine and set face attributes. ++* Displaying Faces:: How Emacs combines the faces specified for a character. ++* Face Remapping:: Remapping faces to alternative definitions. ++* Face Functions:: How to define and examine faces. ++* Auto Faces:: Hook for automatic face assignment. ++* Font Selection:: Finding the best available font for a face. ++* Font Lookup:: Looking up the names of available fonts ++ and information about them. ++* Fontsets:: A fontset is a collection of fonts ++ that handle a range of character sets. ++* Low-Level Font:: Lisp representation for character display fonts. ++@end menu ++ ++@node Defining Faces ++@subsection Defining Faces ++ ++ The way to define a new face is with @code{defface}. This creates a ++kind of customization item (@pxref{Customization}) which the user can ++customize using the Customization buffer (@pxref{Easy Customization,,, ++emacs, The GNU Emacs Manual}). ++ ++ People are sometimes tempted to create variables whose values specify ++which faces to use (for example, Font-Lock does this). In the vast ++majority of cases, this is not necessary, and simply using faces ++directly is preferable. ++ ++@defmac defface face spec doc [keyword value]@dots{} ++This declares @var{face} as a customizable face whose default ++attributes are given by @var{spec}. You should not quote the symbol ++@var{face}, and it should not end in @samp{-face} (that would be ++redundant). The argument @var{doc} specifies the face documentation. ++The keywords you can use in @code{defface} are the same as in ++@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}). ++ ++When @code{defface} executes, it defines the face according to ++@var{spec}, then uses any customizations that were read from the ++init file (@pxref{Init File}) to override that specification. ++ ++When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs ++Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} ++overrides any customizations of the face. This way, the face reflects ++exactly what the @code{defface} says. ++ ++The purpose of @var{spec} is to specify how the face should appear on ++different kinds of terminals. It should be an alist whose elements ++have the form @code{(@var{display} @var{atts})}. Each element's ++@sc{car}, @var{display}, specifies a class of terminals. (The first ++element, if its @sc{car} is @code{default}, is special---it specifies ++defaults for the remaining elements). The element's @sc{cadr}, ++@var{atts}, is a list of face attributes and their values; it ++specifies what the face should look like on that kind of terminal. ++The possible attributes are defined in the value of ++@code{custom-face-attributes}. ++ ++The @var{display} part of an element of @var{spec} determines which ++frames the element matches. If more than one element of @var{spec} ++matches a given frame, the first element that matches is the one used ++for that frame. There are three possibilities for @var{display}: ++ ++@table @asis ++@item @code{default} ++This element of @var{spec} doesn't match any frames; instead, it ++specifies defaults that apply to all frames. This kind of element, if ++used, must be the first element of @var{spec}. Each of the following ++elements can override any or all of these defaults. ++ ++@item @code{t} ++This element of @var{spec} matches all frames. Therefore, any ++subsequent elements of @var{spec} are never used. Normally ++@code{t} is used in the last (or only) element of @var{spec}. ++ ++@item a list ++If @var{display} is a list, each element should have the form ++@code{(@var{characteristic} @var{value}@dots{})}. Here ++@var{characteristic} specifies a way of classifying frames, and the ++@var{value}s are possible classifications which @var{display} should ++apply to. Here are the possible values of @var{characteristic}: ++ ++@table @code ++@item type ++The kind of window system the frame uses---either @code{graphic} (any ++graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console), ++@code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} ++(a non-graphics-capable display). ++@xref{Window Systems, window-system}. ++ ++@item class ++What kinds of colors the frame supports---either @code{color}, ++@code{grayscale}, or @code{mono}. ++ ++@item background ++The kind of background---either @code{light} or @code{dark}. ++ ++@item min-colors ++An integer that represents the minimum number of colors the frame ++should support. This matches a frame if its ++@code{display-color-cells} value is at least the specified integer. ++ ++@item supports ++Whether or not the frame can display the face attributes given in ++@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face ++Attribute Testing}, for more information on exactly how this testing ++is done. ++@end table ++ ++If an element of @var{display} specifies more than one @var{value} for a ++given @var{characteristic}, any of those values is acceptable. If ++@var{display} has more than one element, each element should specify a ++different @var{characteristic}; then @emph{each} characteristic of the ++frame must match one of the @var{value}s specified for it in ++@var{display}. ++@end table ++@end defmac ++ ++ Here's how the standard face @code{region} is defined: ++ ++@example ++@group ++(defface region ++ '((((class color) (min-colors 88) (background dark)) ++ :background "blue3") ++@end group ++ (((class color) (min-colors 88) (background light)) ++ :background "lightgoldenrod2") ++ (((class color) (min-colors 16) (background dark)) ++ :background "blue3") ++ (((class color) (min-colors 16) (background light)) ++ :background "lightgoldenrod2") ++ (((class color) (min-colors 8)) ++ :background "blue" :foreground "white") ++ (((type tty) (class mono)) ++ :inverse-video t) ++ (t :background "gray")) ++@group ++ "Basic face for highlighting the region." ++ :group 'basic-faces) ++@end group ++@end example ++ ++ Internally, @code{defface} uses the symbol property ++@code{face-defface-spec} to record the specified face attributes. The ++attributes saved by the user with the customization buffer are ++recorded in the symbol property @code{saved-face}; the attributes ++customized by the user for the current session, but not saved, are ++recorded in the symbol property @code{customized-face}. The ++documentation string is recorded in the symbol property ++@code{face-documentation}. ++ ++@defopt frame-background-mode ++This option, if non-@code{nil}, specifies the background type to use for ++interpreting face definitions. If it is @code{dark}, then Emacs treats ++all frames as if they had a dark background, regardless of their actual ++background colors. If it is @code{light}, then Emacs treats all frames ++as if they had a light background. ++@end defopt ++ ++@node Face Attributes ++@subsection Face Attributes ++@cindex face attributes ++ ++ The effect of using a face is determined by a fixed set of @dfn{face ++attributes}. This table lists all the face attributes, their possible ++values, and their effects. You can specify more than one face for a ++given piece of text; Emacs merges the attributes of all the faces to ++determine how to display the text. @xref{Displaying Faces}. ++ ++ In addition to the values given below, each face attribute can also ++have the value @code{unspecified}. This special value means the face ++doesn't specify that attribute. In face merging, when the first face ++fails to specify a particular attribute, the next face gets a chance. ++However, the @code{default} face must specify all attributes. ++ ++ Some of these font attributes are meaningful only on certain kinds ++of displays. If your display cannot handle a certain attribute, the ++attribute is ignored. ++ ++@table @code ++@item :family ++Font family name or fontset name (a string). If you specify a font ++family name, the wild-card characters @samp{*} and @samp{?} are ++allowed. The function @code{font-family-list}, described below, ++returns a list of available family names. @xref{Fontsets}, for ++information about fontsets. ++ ++@item :foundry ++The name of the @dfn{font foundry} in which the font family specified ++by the @code{:family} attribute is located (a string). The wild-card ++characters @samp{*} and @samp{?} are allowed. ++ ++@item :width ++Relative proportionate character width, also known as the character ++set width. This should be one of the symbols @code{ultra-condensed}, ++@code{extra-condensed}, @code{condensed}, @code{semi-condensed}, ++@code{normal}, @code{semi-expanded}, @code{expanded}, ++@code{extra-expanded}, or @code{ultra-expanded}. ++ ++@item :height ++Font height---either an integer in units of 1/10 point, or a floating ++point number specifying the amount by which to scale the height of any ++underlying face, or a function that is called with one argument (the ++height of the underlying face) and returns the height of the new face. ++If the function is passed an integer argument, it must return an ++integer. ++ ++The height of the default face must be specified using an integer; ++floating point and function values are not allowed. ++ ++@item :weight ++Font weight---one of the symbols (from densest to faintest) ++@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold}, ++@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, or ++@code{ultra-light}. On text-only terminals that support ++variable-brightness text, any weight greater than normal is displayed ++as extra bright, and any weight less than normal is displayed as ++half-bright. ++ ++@item :slant ++Font slant---one of the symbols @code{italic}, @code{oblique}, ++@code{normal}, @code{reverse-italic}, or @code{reverse-oblique}. On ++text-only terminals that support variable-brightness text, slanted ++text is displayed as half-bright. ++ ++@item :foreground ++Foreground color, a string. The value can be a system-defined color ++name, or a hexadecimal color specification. @xref{Color Names}. On ++black-and-white displays, certain shades of gray are implemented by ++stipple patterns. ++ ++@item :background ++Background color, a string. The value can be a system-defined color ++name, or a hexadecimal color specification. @xref{Color Names}. ++ ++@item :underline ++Whether or not characters should be underlined, and in what color. If ++the value is @code{t}, underlining uses the foreground color of the ++face. If the value is a string, underlining uses that color. The ++value @code{nil} means do not underline. ++ ++@item :overline ++Whether or not characters should be overlined, and in what color. ++The value is used like that of @code{:underline}. ++ ++@item :strike-through ++Whether or not characters should be strike-through, and in what ++color. The value is used like that of @code{:underline}. ++ ++@item :box ++Whether or not a box should be drawn around characters, its color, the ++width of the box lines, and 3D appearance. Here are the possible ++values of the @code{:box} attribute, and what they mean: ++ ++@table @asis ++@item @code{nil} ++Don't draw a box. ++ ++@item @code{t} ++Draw a box with lines of width 1, in the foreground color. ++ ++@item @var{color} ++Draw a box with lines of width 1, in color @var{color}. ++ ++@item @code{(:line-width @var{width} :color @var{color} :style @var{style})} ++This way you can explicitly specify all aspects of the box. The value ++@var{width} specifies the width of the lines to draw; it defaults to 1. ++ ++The value @var{color} specifies the color to draw with. The default is ++the foreground color of the face for simple boxes, and the background ++color of the face for 3D boxes. ++ ++The value @var{style} specifies whether to draw a 3D box. If it is ++@code{released-button}, the box looks like a 3D button that is not being ++pressed. If it is @code{pressed-button}, the box looks like a 3D button ++that is being pressed. If it is @code{nil} or omitted, a plain 2D box ++is used. ++@end table ++ ++@item :inverse-video ++Whether or not characters should be displayed in inverse video. The ++value should be @code{t} (yes) or @code{nil} (no). ++ ++@item :stipple ++The background stipple, a bitmap. ++ ++The value can be a string; that should be the name of a file containing ++external-format X bitmap data. The file is found in the directories ++listed in the variable @code{x-bitmap-file-path}. ++ ++Alternatively, the value can specify the bitmap directly, with a list ++of the form @code{(@var{width} @var{height} @var{data})}. Here, ++@var{width} and @var{height} specify the size in pixels, and ++@var{data} is a string containing the raw bits of the bitmap, row by ++row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes ++in the string (which should be a unibyte string for best results). ++This means that each row always occupies at least one whole byte. ++ ++If the value is @code{nil}, that means use no stipple pattern. ++ ++Normally you do not need to set the stipple attribute, because it is ++used automatically to handle certain shades of gray. ++ ++@item :font ++The font used to display the face. Its value should be a font object. ++@xref{Font Selection}, for information about font objects. ++ ++When specifying this attribute using @code{set-face-attribute} ++(@pxref{Attribute Functions}), you may also supply a font spec, a font ++entity, or a string. Emacs converts such values to an appropriate ++font object, and stores that font object as the actual attribute ++value. If you specify a string, the contents of the string should be ++a font name (@pxref{Font X,, Font Specification Options, emacs, The ++GNU Emacs Manual}); if the font name is an XLFD containing wildcards, ++Emacs chooses the first font matching those wildcards. Specifying ++this attribute also changes the values of the @code{:family}, ++@code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and ++@code{:slant} attributes. ++ ++@item :inherit ++The name of a face from which to inherit attributes, or a list of face ++names. Attributes from inherited faces are merged into the face like ++an underlying face would be, with higher priority than underlying ++faces. If a list of faces is used, attributes from faces earlier in ++the list override those from later faces. ++@end table ++ ++For compatibility with Emacs 20, you can also specify values for two ++``fake'' face attributes: @code{:bold} and @code{:italic}. Their ++values must be either @code{t} or @code{nil}; a value of ++@code{unspecified} is not allowed. Setting @code{:bold} to @code{t} ++is equivalent to setting the @code{:weight} attribute to @code{bold}, ++and setting it to @code{nil} is equivalent to setting @code{:weight} ++to @code{normal}. Setting @code{:italic} to @code{t} is equivalent to ++setting the @code{:slant} attribute to @code{italic}, and setting it ++to @code{nil} is equivalent to setting @code{:slant} to @code{normal}. ++ ++@defun font-family-list &optional frame ++This function returns a list of available font family names. The ++optional argument @var{frame} specifies the frame on which the text is ++to be displayed; if it is @code{nil}, the selected frame is used. ++@end defun ++ ++@defopt underline-minimum-offset ++This variable specifies the minimum distance between the baseline and ++the underline, in pixels, when displaying underlined text. ++@end defopt ++ ++@defopt x-bitmap-file-path ++This variable specifies a list of directories for searching ++for bitmap files, for the @code{:stipple} attribute. ++@end defopt ++ ++@defun bitmap-spec-p object ++This returns @code{t} if @var{object} is a valid bitmap specification, ++suitable for use with @code{:stipple} (see above). It returns ++@code{nil} otherwise. ++@end defun ++ ++@node Attribute Functions ++@subsection Face Attribute Functions ++ ++ This section describes the functions for accessing and modifying the ++attributes of an existing face. ++ ++@defun set-face-attribute face frame &rest arguments ++This function sets one or more attributes of @var{face} for ++@var{frame}. The attributes you specify this way override whatever ++the @code{defface} says. ++ ++The extra arguments @var{arguments} specify the attributes to set, and ++the values for them. They should consist of alternating attribute names ++(such as @code{:family} or @code{:underline}) and corresponding values. ++Thus, ++ ++@example ++(set-face-attribute 'foo nil ++ :width 'extended ++ :weight 'bold ++ :underline "red") ++@end example ++ ++@noindent ++sets the attributes @code{:width}, @code{:weight} and @code{:underline} ++to the corresponding values. ++ ++If @var{frame} is @code{t}, this function sets the default attributes ++for new frames. Default attribute values specified this way override ++the @code{defface} for newly created frames. ++ ++If @var{frame} is @code{nil}, this function sets the attributes for ++all existing frames, and the default for new frames. ++@end defun ++ ++@defun face-attribute face attribute &optional frame inherit ++This returns the value of the @var{attribute} attribute of @var{face} ++on @var{frame}. If @var{frame} is @code{nil}, that means the selected ++frame (@pxref{Input Focus}). ++ ++If @var{frame} is @code{t}, this returns whatever new-frames default ++value you previously specified with @code{set-face-attribute} for the ++@var{attribute} attribute of @var{face}. If you have not specified ++one, it returns @code{nil}. ++ ++If @var{inherit} is @code{nil}, only attributes directly defined by ++@var{face} are considered, so the return value may be ++@code{unspecified}, or a relative value. If @var{inherit} is ++non-@code{nil}, @var{face}'s definition of @var{attribute} is merged ++with the faces specified by its @code{:inherit} attribute; however the ++return value may still be @code{unspecified} or relative. If ++@var{inherit} is a face or a list of faces, then the result is further ++merged with that face (or faces), until it becomes specified and ++absolute. ++ ++To ensure that the return value is always specified and absolute, use ++a value of @code{default} for @var{inherit}; this will resolve any ++unspecified or relative values by merging with the @code{default} face ++(which is always completely specified). ++ ++For example, ++ ++@example ++(face-attribute 'bold :weight) ++ @result{} bold ++@end example ++@end defun ++ ++@defun face-attribute-relative-p attribute value ++This function returns non-@code{nil} if @var{value}, when used as the ++value of the face attribute @var{attribute}, is relative. This means ++it would modify, rather than completely override, any value that comes ++from a subsequent face in the face list or that is inherited from ++another face. ++ ++@code{unspecified} is a relative value for all attributes. For ++@code{:height}, floating point and function values are also relative. ++ ++For example: ++ ++@example ++(face-attribute-relative-p :height 2.0) ++ @result{} t ++@end example ++@end defun ++ ++@defun face-all-attributes face &optional frame ++This function returns an alist of attributes of @var{face}. The ++elements of the result are name-value pairs of the form ++@w{@code{(@var{attr-name} . @var{attr-value})}}. Optional argument ++@var{frame} specifies the frame whose definition of @var{face} to ++return; if omitted or @code{nil}, the returned value describes the ++default attributes of @var{face} for newly created frames. ++@end defun ++ ++@defun merge-face-attribute attribute value1 value2 ++If @var{value1} is a relative value for the face attribute ++@var{attribute}, returns it merged with the underlying value ++@var{value2}; otherwise, if @var{value1} is an absolute value for the ++face attribute @var{attribute}, returns @var{value1} unchanged. ++@end defun ++ ++ The following functions provide compatibility with Emacs 20 and ++below. They work by calling @code{set-face-attribute}. Values of ++@code{t} and @code{nil} for their @var{frame} argument are handled ++just like @code{set-face-attribute} and @code{face-attribute}. ++ ++@defun set-face-foreground face color &optional frame ++@defunx set-face-background face color &optional frame ++These functions set the @code{:foreground} attribute (or ++@code{:background} attribute, respectively) of @var{face} to ++@var{color}. ++@end defun ++ ++@defun set-face-stipple face pattern &optional frame ++This function sets the @code{:stipple} attribute of @var{face} to ++@var{pattern}. ++@end defun ++ ++@defun set-face-font face font &optional frame ++This function sets the @code{:font} attribute of @var{face} to ++@var{font}. ++@end defun ++ ++@defun set-face-bold-p face bold-p &optional frame ++This function sets the @code{:weight} attribute of @var{face} to ++@var{normal} if @var{bold-p} is @code{nil}, and to @var{bold} ++otherwise. ++@end defun ++ ++@defun set-face-italic-p face italic-p &optional frame ++This function sets the @code{:slant} attribute of @var{face} to ++@var{normal} if @var{italic-p} is @code{nil}, and to @var{italic} ++otherwise. ++@end defun ++ ++@defun set-face-underline-p face underline &optional frame ++This function sets the @code{:underline} attribute of @var{face} to ++@var{underline}. ++@end defun ++ ++@defun set-face-inverse-video-p face inverse-video-p &optional frame ++This function sets the @code{:inverse-video} attribute of @var{face} ++to @var{inverse-video-p}. ++@end defun ++ ++@defun invert-face face &optional frame ++This function swaps the foreground and background colors of face ++@var{face}. ++@end defun ++ ++ The following functions examine the attributes of a face. If you ++don't specify @var{frame}, they refer to the selected frame; @code{t} ++refers to the default data for new frames. They return the symbol ++@code{unspecified} if the face doesn't define any value for that ++attribute. ++ ++@defun face-foreground face &optional frame inherit ++@defunx face-background face &optional frame inherit ++These functions return the foreground color (or background color, ++respectively) of face @var{face}, as a string. ++ ++If @var{inherit} is @code{nil}, only a color directly defined by the face is ++returned. If @var{inherit} is non-@code{nil}, any faces specified by its ++@code{:inherit} attribute are considered as well, and if @var{inherit} ++is a face or a list of faces, then they are also considered, until a ++specified color is found. To ensure that the return value is always ++specified, use a value of @code{default} for @var{inherit}. ++@end defun ++ ++@defun face-stipple face &optional frame inherit ++This function returns the name of the background stipple pattern of face ++@var{face}, or @code{nil} if it doesn't have one. ++ ++If @var{inherit} is @code{nil}, only a stipple directly defined by the ++face is returned. If @var{inherit} is non-@code{nil}, any faces ++specified by its @code{:inherit} attribute are considered as well, and ++if @var{inherit} is a face or a list of faces, then they are also ++considered, until a specified stipple is found. To ensure that the ++return value is always specified, use a value of @code{default} for ++@var{inherit}. ++@end defun ++ ++@defun face-font face &optional frame ++This function returns the name of the font of face @var{face}. ++@end defun ++ ++@defun face-bold-p face &optional frame ++This function returns a non-@code{nil} value if the @code{:weight} ++attribute of @var{face} is bolder than normal (i.e., one of ++@code{semi-bold}, @code{bold}, @code{extra-bold}, or ++@code{ultra-bold}). Otherwise, it returns @code{nil}. ++@end defun ++ ++@defun face-italic-p face &optional frame ++This function returns a non-@code{nil} value if the @code{:slant} ++attribute of @var{face} is @code{italic} or @code{oblique}, and ++@code{nil} otherwise. ++@end defun ++ ++@defun face-underline-p face &optional frame ++This function returns the @code{:underline} attribute of face @var{face}. ++@end defun ++ ++@defun face-inverse-video-p face &optional frame ++This function returns the @code{:inverse-video} attribute of face @var{face}. ++@end defun ++ ++@node Displaying Faces ++@subsection Displaying Faces ++ ++ Here is how Emacs determines the face to use for displaying any ++given piece of text: ++ ++@itemize @bullet ++@item ++If the text consists of a special glyph, the glyph can specify a ++particular face. @xref{Glyphs}. ++ ++@item ++If the text lies within an active region, Emacs highlights it using ++the @code{region} face. @xref{Standard Faces,,, emacs, The GNU Emacs ++Manual}. ++ ++@item ++If the text lies within an overlay with a non-@code{nil} @code{face} ++property, Emacs applies the face or face attributes specified by that ++property. If the overlay has a @code{mouse-face} property and the ++mouse is ``near enough'' to the overlay, Emacs applies the face or ++face attributes specified by the @code{mouse-face} property instead. ++@xref{Overlay Properties}. ++ ++When multiple overlays cover one character, an overlay with higher ++priority overrides those with lower priority. @xref{Overlays}. ++ ++@item ++If the text contains a @code{face} or @code{mouse-face} property, ++Emacs applies the specified faces and face attributes. @xref{Special ++Properties}. (This is how Font Lock mode faces are applied. ++@xref{Font Lock Mode}.) ++ ++@item ++If the text lies within the mode line of the selected window, Emacs ++applies the @code{mode-line} face. For the mode line of a ++non-selected window, Emacs applies the @code{mode-line-inactive} face. ++For a header line, Emacs applies the @code{header-line} face. ++ ++@item ++If any given attribute has not been specified during the preceding ++steps, Emacs applies the attribute of the @code{default} face. ++@end itemize ++ ++ If these various sources together specify more than one face for a ++particular character, Emacs merges the attributes of the various faces ++specified. For each attribute, Emacs tries using the above order ++(i.e., first the face of any special glyph; then the face for region ++highlighting, if appropriate; then faces specified by overlays, then ++faces specified by text properties, then the @code{mode-line} or ++@code{mode-line-inactive} or @code{header-line} face, if appropriate, ++and finally the @code{default} face). ++ ++@node Face Remapping ++@subsection Face Remapping ++ ++ The variable @code{face-remapping-alist} is used for buffer-local or ++global changes in the appearance of a face. For instance, it can be ++used to make the @code{default} face a variable-pitch face within a ++particular buffer. ++ ++@defvar face-remapping-alist ++An alist whose elements have the form @code{(@var{face} ++@var{remapping...})}. This causes Emacs to display text using the ++face @var{face} using @var{remapping...} instead of @var{face}'s ++ordinary definition. @var{remapping...} may be any face specification ++suitable for a @code{face} text property: either a face name, or a ++property list of attribute/value pairs. @xref{Special Properties}. ++ ++If @code{face-remapping-alist} is buffer-local, its local value takes ++effect only within that buffer. ++ ++Two points bear emphasizing: ++ ++@enumerate ++@item ++The new definition @var{remapping...} is the complete ++specification of how to display @var{face}---it entirely replaces, ++rather than augmenting or modifying, the normal definition of that ++face. ++ ++@item ++If @var{remapping...} recursively references the same face name ++@var{face}, either directly remapping entry, or via the ++@code{:inherit} attribute of some other face in @var{remapping...}, ++then that reference uses the normal definition of @var{face} in the ++selected frame, instead of the ``remapped'' definition. ++ ++For instance, if the @code{mode-line} face is remapped using this ++entry in @code{face-remapping-alist}: ++@example ++(mode-line italic mode-line) ++@end example ++@noindent ++then the new definition of the @code{mode-line} face inherits from the ++@code{italic} face, and the @emph{normal} (non-remapped) definition of ++@code{mode-line} face. ++@end enumerate ++@end defvar ++ ++ A typical use of the @code{face-remapping-alist} is to change a ++buffer's @code{default} face; for example, the following changes a ++buffer's @code{default} face to use the @code{variable-pitch} face, ++with the height doubled: ++ ++@example ++(set (make-local-variable 'face-remapping-alist) ++ '((default variable-pitch :height 2.0))) ++@end example ++ ++ The following functions implement a higher-level interface to ++@code{face-remapping-alist}, making it easier to use ++``cooperatively''. They are mainly intended for buffer-local use, and ++so all make @code{face-remapping-alist} variable buffer-local as a ++side-effect. They use entries in @code{face-remapping-alist} which ++have the general form: ++ ++@example ++ (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs}) ++@end example ++ ++Everything except @var{face} is a ``face spec'': a list of face names ++or face attribute-value pairs. All face specs are merged together, ++with earlier values taking precedence. ++ ++The @var{relative_specs_}n values are ``relative specs'', and are ++added by @code{face-remap-add-relative} (and removed by ++@code{face-remap-remove-relative}. These are intended for face ++modifications (such as increasing the size). Typical users of these ++relative specs would be minor modes. ++ ++@var{base_specs} is the lowest-priority value, and by default is just the ++face name, which causes the global definition of that face to be used. ++ ++A non-default value of @var{base_specs} may also be set using ++@code{face-remap-set-base}. Because this @emph{overwrites} the ++default base-spec value (which inherits the global face definition), ++it is up to the caller of @code{face-remap-set-base} to add such ++inheritance if it is desired. A typical use of ++@code{face-remap-set-base} would be a major mode adding a face ++remappings, e.g., of the default face. ++ ++ ++@defun face-remap-add-relative face &rest specs ++This functions adds a face remapping entry of @var{face} to @var{specs} ++in the current buffer. ++ ++It returns a ``cookie'' which can be used to later delete the remapping with ++@code{face-remap-remove-relative}. ++ ++@var{specs} can be any value suitable for the @code{face} text ++property, including a face name, a list of face names, or a ++face-attribute property list. The attributes given by @var{specs} ++will be merged with any other currently active face remappings of ++@var{face}, and with the global definition of @var{face} (by default; ++this may be changed using @code{face-remap-set-base}), with the most ++recently added relative remapping taking precedence. ++@end defun ++ ++@defun face-remap-remove-relative cookie ++This function removes a face remapping previously added by ++@code{face-remap-add-relative}. @var{cookie} should be a return value ++from that function. ++@end defun ++ ++@defun face-remap-set-base face &rest specs ++This function sets the ``base remapping'' of @var{face} in the current ++buffer to @var{specs}. If @var{specs} is empty, the default base ++remapping is restored, which inherits from the global definition of ++@var{face}; note that this is different from @var{specs} containing a ++single value @code{nil}, which has the opposite result (the global ++definition of @var{face} is ignored). ++@end defun ++ ++@defun face-remap-reset-base face ++This function sets the ``base remapping'' of @var{face} to its default ++value, which inherits from @var{face}'s global definition. ++@end defun ++ ++@node Face Functions ++@subsection Functions for Working with Faces ++ ++ Here are additional functions for creating and working with faces. ++ ++@defun make-face name ++This function defines a new face named @var{name}, initially with all ++attributes @code{nil}. It does nothing if there is already a face named ++@var{name}. ++@end defun ++ ++@defun face-list ++This function returns a list of all defined face names. ++@end defun ++ ++@defun copy-face old-face new-name &optional frame new-frame ++This function defines a face named @var{new-name} as a copy of the existing ++face named @var{old-face}. It creates the face @var{new-name} if that ++doesn't already exist. ++ ++If the optional argument @var{frame} is given, this function applies ++only to that frame. Otherwise it applies to each frame individually, ++copying attributes from @var{old-face} in each frame to @var{new-face} ++in the same frame. ++ ++If the optional argument @var{new-frame} is given, then @code{copy-face} ++copies the attributes of @var{old-face} in @var{frame} to @var{new-name} ++in @var{new-frame}. ++@end defun ++ ++@defun face-id face ++This function returns the @dfn{face number} of face @var{face}. This ++is a number that uniquely identifies a face at low levels within ++Emacs. It is seldom necessary to refer to a face by its face number. ++@end defun ++ ++@defun face-documentation face ++This function returns the documentation string of face @var{face}, or ++@code{nil} if none was specified for it. ++@end defun ++ ++@defun face-equal face1 face2 &optional frame ++This returns @code{t} if the faces @var{face1} and @var{face2} have the ++same attributes for display. ++@end defun ++ ++@defun face-differs-from-default-p face &optional frame ++This returns non-@code{nil} if the face @var{face} displays ++differently from the default face. ++@end defun ++ ++@cindex face alias ++A @dfn{face alias} provides an equivalent name for a face. You can ++define a face alias by giving the alias symbol the @code{face-alias} ++property, with a value of the target face name. The following example ++makes @code{modeline} an alias for the @code{mode-line} face. ++ ++@example ++(put 'modeline 'face-alias 'mode-line) ++@end example ++ ++@node Auto Faces ++@subsection Automatic Face Assignment ++@cindex automatic face assignment ++@cindex faces, automatic choice ++ ++ This hook is used for automatically assigning faces to text in the ++buffer. It is part of the implementation of Jit-Lock mode, used by ++Font-Lock. ++ ++@defvar fontification-functions ++This variable holds a list of functions that are called by Emacs ++redisplay as needed to assign faces automatically to text in the buffer. ++ ++The functions are called in the order listed, with one argument, a ++buffer position @var{pos}. Each function should attempt to assign faces ++to the text in the current buffer starting at @var{pos}. ++ ++Each function should record the faces they assign by setting the ++@code{face} property. It should also add a non-@code{nil} ++@code{fontified} property for all the text it has assigned faces to. ++That property tells redisplay that faces have been assigned to that text ++already. ++ ++It is probably a good idea for each function to do nothing if the ++character after @var{pos} already has a non-@code{nil} @code{fontified} ++property, but this is not required. If one function overrides the ++assignments made by a previous one, the properties as they are ++after the last function finishes are the ones that really matter. ++ ++For efficiency, we recommend writing these functions so that they ++usually assign faces to around 400 to 600 characters at each call. ++@end defvar ++ ++@node Font Selection ++@subsection Font Selection ++ ++ Before Emacs can draw a character on a particular display, it must ++select a @dfn{font} for that character@footnote{In this context, the ++term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock ++Mode}).}. Normally, Emacs automatically chooses a font based on the ++faces assigned to that character---specifically, the face attributes ++@code{:family}, @code{:weight}, @code{:slant}, and @code{:width} ++(@pxref{Face Attributes}). The choice of font also depends on the ++character to be displayed; some fonts can only display a limited set ++of characters. If no available font exactly fits the requirements, ++Emacs looks for the @dfn{closest matching font}. The variables in ++this section control how Emacs makes this selection. ++ ++@defopt face-font-family-alternatives ++If a given family is specified but does not exist, this variable ++specifies alternative font families to try. Each element should have ++this form: ++ ++@example ++(@var{family} @var{alternate-families}@dots{}) ++@end example ++ ++If @var{family} is specified but not available, Emacs will try the other ++families given in @var{alternate-families}, one by one, until it finds a ++family that does exist. ++@end defopt ++ ++@defopt face-font-selection-order ++If there is no font that exactly matches all desired face attributes ++(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}), ++this variable specifies the order in which these attributes should be ++considered when selecting the closest matching font. The value should ++be a list containing those four attribute symbols, in order of ++decreasing importance. The default is @code{(:width :height :weight ++:slant)}. ++ ++Font selection first finds the best available matches for the first ++attribute in the list; then, among the fonts which are best in that ++way, it searches for the best matches in the second attribute, and so ++on. ++ ++The attributes @code{:weight} and @code{:width} have symbolic values in ++a range centered around @code{normal}. Matches that are more extreme ++(farther from @code{normal}) are somewhat preferred to matches that are ++less extreme (closer to @code{normal}); this is designed to ensure that ++non-normal faces contrast with normal ones, whenever possible. ++ ++One example of a case where this variable makes a difference is when the ++default font has no italic equivalent. With the default ordering, the ++@code{italic} face will use a non-italic font that is similar to the ++default one. But if you put @code{:slant} before @code{:height}, the ++@code{italic} face will use an italic font, even if its height is not ++quite right. ++@end defopt ++ ++@defopt face-font-registry-alternatives ++This variable lets you specify alternative font registries to try, if a ++given registry is specified and doesn't exist. Each element should have ++this form: ++ ++@example ++(@var{registry} @var{alternate-registries}@dots{}) ++@end example ++ ++If @var{registry} is specified but not available, Emacs will try the ++other registries given in @var{alternate-registries}, one by one, ++until it finds a registry that does exist. ++@end defopt ++ ++ Emacs can make use of scalable fonts, but by default it does not use ++them. ++ ++@defopt scalable-fonts-allowed ++This variable controls which scalable fonts to use. A value of ++@code{nil}, the default, means do not use scalable fonts. @code{t} ++means to use any scalable font that seems appropriate for the text. ++ ++Otherwise, the value must be a list of regular expressions. Then a ++scalable font is enabled for use if its name matches any regular ++expression in the list. For example, ++ ++@example ++(setq scalable-fonts-allowed '("muleindian-2$")) ++@end example ++ ++@noindent ++allows the use of scalable fonts with registry @code{muleindian-2}. ++@end defopt ++ ++@defvar face-font-rescale-alist ++This variable specifies scaling for certain faces. Its value should ++be a list of elements of the form ++ ++@example ++(@var{fontname-regexp} . @var{scale-factor}) ++@end example ++ ++If @var{fontname-regexp} matches the font name that is about to be ++used, this says to choose a larger similar font according to the ++factor @var{scale-factor}. You would use this feature to normalize ++the font size if certain fonts are bigger or smaller than their ++nominal heights and widths would suggest. ++@end defvar ++ ++@node Font Lookup ++@subsection Looking Up Fonts ++ ++@defun x-list-fonts name &optional reference-face frame maximum width ++This function returns a list of available font names that match ++@var{name}. @var{name} should be a string containing a font name in ++either the Fontconfig, GTK, or XLFD format (@pxref{Font X,, Font ++Specification Options, emacs, The GNU Emacs Manual}). Within an XLFD ++string, wildcard characters may be used: the @samp{*} character ++matches any substring, and the @samp{?} character matches any single ++character. Case is ignored when matching font names. ++ ++If the optional arguments @var{reference-face} and @var{frame} are ++specified, the returned list includes only fonts that are the same ++size as @var{reference-face} (a face name) currently is on the frame ++@var{frame}. ++ ++The optional argument @var{maximum} sets a limit on how many fonts to ++return. If it is non-@code{nil}, then the return value is truncated ++after the first @var{maximum} matching fonts. Specifying a small ++value for @var{maximum} can make this function much faster, in cases ++where many fonts match the pattern. ++ ++The optional argument @var{width} specifies a desired font width. If ++it is non-@code{nil}, the function only returns those fonts whose ++characters are (on average) @var{width} times as wide as ++@var{reference-face}. ++@end defun ++ ++@defun x-family-fonts &optional family frame ++This function returns a list describing the available fonts for family ++@var{family} on @var{frame}. If @var{family} is omitted or @code{nil}, ++this list applies to all families, and therefore, it contains all ++available fonts. Otherwise, @var{family} must be a string; it may ++contain the wildcards @samp{?} and @samp{*}. ++ ++The list describes the display that @var{frame} is on; if @var{frame} is ++omitted or @code{nil}, it applies to the selected frame's display ++(@pxref{Input Focus}). ++ ++Each element in the list is a vector of the following form: ++ ++@example ++[@var{family} @var{width} @var{point-size} @var{weight} @var{slant} ++ @var{fixed-p} @var{full} @var{registry-and-encoding}] ++@end example ++ ++The first five elements correspond to face attributes; if you ++specify these attributes for a face, it will use this font. ++ ++The last three elements give additional information about the font. ++@var{fixed-p} is non-@code{nil} if the font is fixed-pitch. ++@var{full} is the full name of the font, and ++@var{registry-and-encoding} is a string giving the registry and ++encoding of the font. ++@end defun ++ ++@defvar font-list-limit ++This variable specifies maximum number of fonts to consider in font ++matching. The function @code{x-family-fonts} will not return more than ++that many fonts, and font selection will consider only that many fonts ++when searching a matching font for face attributes. The default is ++currently 100. ++@end defvar ++ ++@node Fontsets ++@subsection Fontsets ++ ++ A @dfn{fontset} is a list of fonts, each assigned to a range of ++character codes. An individual font cannot display the whole range of ++characters that Emacs supports, but a fontset can. Fontsets have names, ++just as fonts do, and you can use a fontset name in place of a font name ++when you specify the ``font'' for a frame or a face. Here is ++information about defining a fontset under Lisp program control. ++ ++@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror ++This function defines a new fontset according to the specification ++string @var{fontset-spec}. The string should have this format: ++ ++@smallexample ++@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}} ++@end smallexample ++ ++@noindent ++Whitespace characters before and after the commas are ignored. ++ ++The first part of the string, @var{fontpattern}, should have the form of ++a standard X font name, except that the last two fields should be ++@samp{fontset-@var{alias}}. ++ ++The new fontset has two names, one long and one short. The long name is ++@var{fontpattern} in its entirety. The short name is ++@samp{fontset-@var{alias}}. You can refer to the fontset by either ++name. If a fontset with the same name already exists, an error is ++signaled, unless @var{noerror} is non-@code{nil}, in which case this ++function does nothing. ++ ++If optional argument @var{style-variant-p} is non-@code{nil}, that says ++to create bold, italic and bold-italic variants of the fontset as well. ++These variant fontsets do not have a short name, only a long one, which ++is made by altering @var{fontpattern} to indicate the bold or italic ++status. ++ ++The specification string also says which fonts to use in the fontset. ++See below for the details. ++@end defun ++ ++ The construct @samp{@var{charset}:@var{font}} specifies which font to ++use (in this fontset) for one particular character set. Here, ++@var{charset} is the name of a character set, and @var{font} is the font ++to use for that character set. You can use this construct any number of ++times in the specification string. ++ ++ For the remaining character sets, those that you don't specify ++explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces ++@samp{fontset-@var{alias}} with a value that names one character set. ++For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced ++with @samp{ISO8859-1}. ++ ++ In addition, when several consecutive fields are wildcards, Emacs ++collapses them into a single wildcard. This is to prevent use of ++auto-scaled fonts. Fonts made by scaling larger fonts are not usable ++for editing, and scaling a smaller font is not useful because it is ++better to use the smaller font in its own size, which Emacs does. ++ ++ Thus if @var{fontpattern} is this, ++ ++@example ++-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 ++@end example ++ ++@noindent ++the font specification for @acronym{ASCII} characters would be this: ++ ++@example ++-*-fixed-medium-r-normal-*-24-*-ISO8859-1 ++@end example ++ ++@noindent ++and the font specification for Chinese GB2312 characters would be this: ++ ++@example ++-*-fixed-medium-r-normal-*-24-*-gb2312*-* ++@end example ++ ++ You may not have any Chinese font matching the above font ++specification. Most X distributions include only Chinese fonts that ++have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In ++such a case, @samp{Fontset-@var{n}} can be specified as below: ++ ++@smallexample ++Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ ++ chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* ++@end smallexample ++ ++@noindent ++Then, the font specifications for all but Chinese GB2312 characters have ++@samp{fixed} in the @var{family} field, and the font specification for ++Chinese GB2312 characters has a wild card @samp{*} in the @var{family} ++field. ++ ++@defun set-fontset-font name character font-spec &optional frame add ++This function modifies the existing fontset @var{name} to use the font ++matching with @var{font-spec} for the character @var{character}. ++ ++If @var{name} is @code{nil}, this function modifies the fontset of the ++selected frame or that of @var{frame} if @var{frame} is not ++@code{nil}. ++ ++If @var{name} is @code{t}, this function modifies the default ++fontset, whose short name is @samp{fontset-default}. ++ ++@var{character} may be a cons; @code{(@var{from} . @var{to})}, where ++@var{from} and @var{to} are character codepoints. In that case, use ++@var{font-spec} for all characters in the range @var{from} and @var{to} ++(inclusive). ++ ++@var{character} may be a charset. In that case, use ++@var{font-spec} for all character in the charsets. ++ ++@var{character} may be a script anme. In that case, use ++@var{font-spec} for all character in the charsets. ++ ++@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})}, ++where @var{family} is a family name of a font (possibly including a ++foundry name at the head), @var{registry} is a registry name of a font ++(possibly including an encoding name at the tail). ++ ++@var{font-spec} may be a font name string. ++ ++The optional argument @var{add}, if non-@code{nil}, specifies how to ++add @var{font-spec} to the font specifications previously set. If it ++is @code{prepend}, @var{font-spec} is prepended. If it is ++@code{append}, @var{font-spec} is appended. By default, ++@var{font-spec} overrides the previous settings. ++ ++For instance, this changes the default fontset to use a font of which ++family name is @samp{Kochi Gothic} for all characters belonging to ++the charset @code{japanese-jisx0208}. ++ ++@smallexample ++(set-fontset-font t 'japanese-jisx0208 ++ (font-spec :family "Kochi Gothic")) ++@end smallexample ++@end defun ++ ++@defun char-displayable-p char ++This function returns @code{t} if Emacs ought to be able to display ++@var{char}. More precisely, if the selected frame's fontset has a ++font to display the character set that @var{char} belongs to. ++ ++Fontsets can specify a font on a per-character basis; when the fontset ++does that, this function's value may not be accurate. ++@end defun ++ ++@node Low-Level Font ++@subsection Low-Level Font Representation ++ ++ Normally, it is not necessary to manipulate fonts directly. In case ++you need to do so, this section explains how. ++ ++ In Emacs Lisp, fonts are represented using three different Lisp ++object types: @dfn{font objects}, @dfn{font specs}, and @dfn{font ++entities}. ++ ++@defun fontp object &optional type ++Return @code{t} if @var{object} is a font object, font spec, or font ++entity. Otherwise, return @code{nil}. ++ ++The optional argument @var{type}, if non-@code{nil}, determines the ++exact type of Lisp object to check for. In that case, @var{type} ++should be one of @code{font-object}, @code{font-spec}, or ++@code{font-entity}. ++@end defun ++ ++ A font object is a Lisp object that represents a font that Emacs has ++@dfn{opened}. Font objects cannot be modified in Lisp, but they can ++be inspected. ++ ++@defun font-at position &optional window string ++Return the font object that is being used to display the character at ++position @var{position} in the window @var{window}. If @var{window} ++is @code{nil}, it defaults to the selected window. If @var{string} is ++@code{nil}, @var{position} specifies a position in the current buffer; ++otherwise, @var{string} should be a string, and @var{position} ++specifies a position in that string. ++@end defun ++ ++ A font spec is a Lisp object that contains a set of specifications ++that can be used to find a font. More than one font may match the ++specifications in a font spec. ++ ++@defun font-spec &rest arguments ++Return a new font spec using the specifications in @var{arguments}, ++which should come in @code{property}-@code{value} pairs. The possible ++specifications are as follows: ++ ++@table @code ++@item :name ++The font name (a string), in either XLFD, Fontconfig, or GTK format. ++@xref{Font X,, Font Specification Options, emacs, The GNU Emacs ++Manual}. ++ ++@item :family ++@itemx :foundry ++@itemx :weight ++@itemx :slant ++@itemx :width ++These have the same meanings as the face attributes of the same name. ++@xref{Face Attributes}. ++ ++@item :size ++The font size---either a non-negative integer that specifies the pixel ++size, or a floating point number that specifies the point size. ++ ++@item :adstyle ++Additional typographic style information for the font, such as ++@samp{sans}. The value should be a string or a symbol. ++ ++@item :registry ++The charset registry and encoding of the font, such as ++@samp{iso8859-1}. The value should be a string or a symbol. ++ ++@item :script ++The script that the font must support (a symbol). ++@end table ++@end defun ++ ++@defun font-put font-spec property value ++Set the font property @var{property} in the font-spec @var{font-spec} ++to @var{value}. ++@end defun ++ ++ A font entity is a reference to a font that need not be open. Its ++properties are intermediate between a font object and a font spec: ++like a font object, and unlike a font spec, it refers to a single, ++specific font. Unlike a font object, creating a font entity does not ++load the contents of that font into computer memory. ++ ++@defun find-font font-spec &optional frame ++This function returns a font entity that best matches the font spec ++@var{font-spec} on frame @var{frame}. If @var{frame} is @code{nil}, ++it defaults to the selected frame. ++@end defun ++ ++@defun list-fonts font-spec &optional frame num prefer ++This function returns a list of all font entities that match the font ++spec @var{font-spec}. ++ ++The optional argument @var{frame}, if non-@code{nil}, specifies the ++frame on which the fonts are to be displayed. The optional argument ++@var{num}, if non-@code{nil}, should be an integer that specifies the ++maximum length of the returned list. The optional argument ++@var{prefer}, if non-@code{nil}, should be another font spec, which is ++used to control the order of the returned list; the returned font ++entities are sorted in order of decreasing ``closeness'' to that font ++spec. ++@end defun ++ ++ If you call @code{set-face-attribute} and pass a font spec, font ++entity, or font name string as the value of the @code{:font} ++attribute, Emacs opens the best ``matching'' font that is available ++for display. It then stores the corresponding font object as the ++actual value of the @code{:font} attribute for that face. ++ ++ The following functions can be used to obtain information about a ++font. For these functions, the @var{font} argument can be a font ++object, a font entity, or a font spec. ++ ++@defun font-get font property ++This function returns the value of the font property @var{property} ++for @var{font}. ++ ++If @var{font} is a font spec and the font spec does not specify ++@var{property}, the return value is @code{nil}. If @var{font} is a ++font object or font entity, the value for the @var{:script} property ++may be a list of scripts supported by the font. ++@end defun ++ ++@defun font-face-attributes font &optional frame ++This function returns a list of face attributes corresponding to ++@var{font}. The optional argument @var{frame} specifies the frame on ++which the font is to be displayed. If it is @code{nil}, the selected ++frame is used. The return value has the form ++ ++@smallexample ++(:family @var{family} :height @var{height} :weight @var{weight} ++ :slant @var{slant} :width @var{width}) ++@end smallexample ++ ++where the values of @var{family}, @var{height}, @var{weight}, ++@var{slant}, and @var{width} are face attribute values. Some of these ++key-attribute pairs may be omitted from the list if they are not ++specified by @var{font}. ++@end defun ++ ++@defun font-xlfd-name font &optional fold-wildcards ++This function returns the XLFD (X Logical Font Descriptor), a string, ++matching @var{font}. @xref{Font X,, Font Specification Options, ++emacs, The GNU Emacs Manual}, for information about XLFDs. If the ++name is too long for an XLFD (which can contain at most 255 ++characters), the function returns @code{nil}. ++ ++If the optional argument @var{fold-wildcards} is non-@code{nil}, ++consecutive wildcards in the XLFD are folded into one. ++@end defun ++ ++@node Fringes ++@section Fringes ++@cindex fringes ++ ++ The @dfn{fringes} of a window are thin vertical strips down the ++sides that are used for displaying bitmaps that indicate truncation, ++continuation, horizontal scrolling, and the overlay arrow. ++ ++@menu ++* Fringe Size/Pos:: Specifying where to put the window fringes. ++* Fringe Indicators:: Displaying indicator icons in the window fringes. ++* Fringe Cursors:: Displaying cursors in the right fringe. ++* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. ++* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. ++* Overlay Arrow:: Display of an arrow to indicate position. ++@end menu ++ ++@node Fringe Size/Pos ++@subsection Fringe Size and Position ++ ++ The following buffer-local variables control the position and width ++of the window fringes. ++ ++@defvar fringes-outside-margins ++The fringes normally appear between the display margins and the window ++text. If the value is non-@code{nil}, they appear outside the display ++margins. @xref{Display Margins}. ++@end defvar ++ ++@defvar left-fringe-width ++This variable, if non-@code{nil}, specifies the width of the left ++fringe in pixels. A value of @code{nil} means to use the left fringe ++width from the window's frame. ++@end defvar ++ ++@defvar right-fringe-width ++This variable, if non-@code{nil}, specifies the width of the right ++fringe in pixels. A value of @code{nil} means to use the right fringe ++width from the window's frame. ++@end defvar ++ ++ The values of these variables take effect when you display the ++buffer in a window. If you change them while the buffer is visible, ++you can call @code{set-window-buffer} to display it once again in the ++same window, to make the changes take effect. ++ ++@defun set-window-fringes window left &optional right outside-margins ++This function sets the fringe widths of window @var{window}. ++If @var{window} is @code{nil}, the selected window is used. ++ ++The argument @var{left} specifies the width in pixels of the left ++fringe, and likewise @var{right} for the right fringe. A value of ++@code{nil} for either one stands for the default width. If ++@var{outside-margins} is non-@code{nil}, that specifies that fringes ++should appear outside of the display margins. ++@end defun ++ ++@defun window-fringes &optional window ++This function returns information about the fringes of a window ++@var{window}. If @var{window} is omitted or @code{nil}, the selected ++window is used. The value has the form @code{(@var{left-width} ++@var{right-width} @var{outside-margins})}. ++@end defun ++ ++ ++@node Fringe Indicators ++@subsection Fringe Indicators ++@cindex fringe indicators ++@cindex indicators, fringe ++ ++ The @dfn{fringe indicators} are tiny icons Emacs displays in the ++window fringe (on a graphic display) to indicate truncated or ++continued lines, buffer boundaries, overlay arrow, etc. ++ ++@defopt indicate-empty-lines ++@cindex fringes, and empty line indication ++When this is non-@code{nil}, Emacs displays a special glyph in the ++fringe of each empty line at the end of the buffer, on graphical ++displays. @xref{Fringes}. This variable is automatically ++buffer-local in every buffer. ++@end defopt ++ ++@defopt indicate-buffer-boundaries ++This buffer-local variable controls how the buffer boundaries and ++window scrolling are indicated in the window fringes. ++ ++Emacs can indicate the buffer boundaries---that is, the first and last ++line in the buffer---with angle icons when they appear on the screen. ++In addition, Emacs can display an up-arrow in the fringe to show ++that there is text above the screen, and a down-arrow to show ++there is text below the screen. ++ ++There are three kinds of basic values: ++ ++@table @asis ++@item @code{nil} ++Don't display any of these fringe icons. ++@item @code{left} ++Display the angle icons and arrows in the left fringe. ++@item @code{right} ++Display the angle icons and arrows in the right fringe. ++@item any non-alist ++Display the angle icons in the left fringe ++and don't display the arrows. ++@end table ++ ++Otherwise the value should be an alist that specifies which fringe ++indicators to display and where. Each element of the alist should ++have the form @code{(@var{indicator} . @var{position})}. Here, ++@var{indicator} is one of @code{top}, @code{bottom}, @code{up}, ++@code{down}, and @code{t} (which covers all the icons not yet ++specified), while @var{position} is one of @code{left}, @code{right} ++and @code{nil}. ++ ++For example, @code{((top . left) (t . right))} places the top angle ++bitmap in left fringe, and the bottom angle bitmap as well as both ++arrow bitmaps in right fringe. To show the angle bitmaps in the left ++fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}. ++@end defopt ++ ++@defvar default-indicate-buffer-boundaries ++The value of this variable is the default value for ++@code{indicate-buffer-boundaries} in buffers that do not override it. ++@end defvar ++ ++@defvar fringe-indicator-alist ++This buffer-local variable specifies the mapping from logical fringe ++indicators to the actual bitmaps displayed in the window fringes. ++ ++These symbols identify the logical fringe indicators: ++ ++@table @asis ++@item Truncation and continuation line indicators: ++@code{truncation}, @code{continuation}. ++ ++@item Buffer position indicators: ++@code{up}, @code{down}, ++@code{top}, @code{bottom}, ++@code{top-bottom}. ++ ++@item Empty line indicator: ++@code{empty-line}. ++ ++@item Overlay arrow indicator: ++@code{overlay-arrow}. ++ ++@item Unknown bitmap indicator: ++@code{unknown}. ++@end table ++ ++ The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})} ++specifies the fringe bitmaps used to display a specific logical ++fringe indicator. ++ ++Here, @var{indicator} specifies the logical indicator type, and ++@var{bitmaps} is list of symbols @code{(@var{left} @var{right} ++[@var{left1} @var{right1}])} which specifies the actual bitmap shown ++in the left or right fringe for the logical indicator. ++ ++The @var{left} and @var{right} symbols specify the bitmaps shown in ++the left and/or right fringe for the specific indicator. The ++@var{left1} or @var{right1} bitmaps are used only for the `bottom' and ++`top-bottom indicators when the last (only) line in has no final ++newline. Alternatively, @var{bitmaps} may be a single symbol which is ++used in both left and right fringes. ++ ++When @code{fringe-indicator-alist} has a buffer-local value, and there ++is no bitmap defined for a logical indicator, or the bitmap is ++@code{t}, the corresponding value from the (non-local) ++@code{default-fringe-indicator-alist} is used. ++ ++To completely hide a specific indicator, set the bitmap to @code{nil}. ++@end defvar ++ ++@defvar default-fringe-indicator-alist ++The value of this variable is the default value for ++@code{fringe-indicator-alist} in buffers that do not override it. ++@end defvar ++ ++Standard fringe bitmaps for indicators: ++@example ++left-arrow right-arrow up-arrow down-arrow ++left-curly-arrow right-curly-arrow ++left-triangle right-triangle ++top-left-angle top-right-angle ++bottom-left-angle bottom-right-angle ++left-bracket right-bracket ++filled-rectangle hollow-rectangle ++filled-square hollow-square ++vertical-bar horizontal-bar ++empty-line question-mark ++@end example ++ ++@node Fringe Cursors ++@subsection Fringe Cursors ++@cindex fringe cursors ++@cindex cursor, fringe ++ ++ When a line is exactly as wide as the window, Emacs displays the ++cursor in the right fringe instead of using two lines. Different ++bitmaps are used to represent the cursor in the fringe depending on ++the current buffer's cursor type. ++ ++@table @asis ++@item Logical cursor types: ++@code{box} , @code{hollow}, @code{bar}, ++@code{hbar}, @code{hollow-small}. ++@end table ++ ++The @code{hollow-small} type is used instead of @code{hollow} when the ++normal @code{hollow-rectangle} bitmap is too tall to fit on a specific ++display line. ++ ++@defopt overflow-newline-into-fringe ++If this is non-@code{nil}, lines exactly as wide as the window (not ++counting the final newline character) are not continued. Instead, ++when point is at the end of the line, the cursor appears in the right ++fringe. ++@end defopt ++ ++@defvar fringe-cursor-alist ++This variable specifies the mapping from logical cursor type to the ++actual fringe bitmaps displayed in the right fringe. The value is an ++alist where each element @code{(@var{cursor} . @var{bitmap})} specifies ++the fringe bitmaps used to display a specific logical cursor type in ++the fringe. Here, @var{cursor} specifies the logical cursor type and ++@var{bitmap} is a symbol specifying the fringe bitmap to be displayed ++for that logical cursor type. ++ ++When @code{fringe-cursor-alist} has a buffer-local value, and there is ++no bitmap defined for a cursor type, the corresponding value from the ++(non-local) @code{default-fringes-indicator-alist} is used. ++@end defvar ++ ++@defvar default-fringes-cursor-alist ++The value of this variable is the default value for ++@code{fringe-cursor-alist} in buffers that do not override it. ++@end defvar ++ ++Standard bitmaps for displaying the cursor in right fringe: ++@example ++filled-rectangle hollow-rectangle filled-square hollow-square ++vertical-bar horizontal-bar ++@end example ++ ++ ++@node Fringe Bitmaps ++@subsection Fringe Bitmaps ++@cindex fringe bitmaps ++@cindex bitmaps, fringe ++ ++ The @dfn{fringe bitmaps} are the actual bitmaps which represent the ++logical fringe indicators for truncated or continued lines, buffer ++boundaries, overlay arrow, etc. Fringe bitmap symbols have their own ++name space. The fringe bitmaps are shared by all frames and windows. ++You can redefine the built-in fringe bitmaps, and you can define new ++fringe bitmaps. ++ ++ The way to display a bitmap in the left or right fringes for a given ++line in a window is by specifying the @code{display} property for one ++of the characters that appears in it. Use a display specification of ++the form @code{(left-fringe @var{bitmap} [@var{face}])} or ++@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display ++Property}). Here, @var{bitmap} is a symbol identifying the bitmap you ++want, and @var{face} (which is optional) is the name of the face whose ++colors should be used for displaying the bitmap, instead of the ++default @code{fringe} face. @var{face} is automatically merged with ++the @code{fringe} face, so normally @var{face} need only specify the ++foreground color for the bitmap. ++ ++@defun fringe-bitmaps-at-pos &optional pos window ++This function returns the fringe bitmaps of the display line ++containing position @var{pos} in window @var{window}. The return ++value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left} ++is the symbol for the fringe bitmap in the left fringe (or @code{nil} ++if no bitmap), @var{right} is similar for the right fringe, and @var{ov} ++is non-@code{nil} if there is an overlay arrow in the left fringe. ++ ++The value is @code{nil} if @var{pos} is not visible in @var{window}. ++If @var{window} is @code{nil}, that stands for the selected window. ++If @var{pos} is @code{nil}, that stands for the value of point in ++@var{window}. ++@end defun ++ ++@node Customizing Bitmaps ++@subsection Customizing Fringe Bitmaps ++ ++@defun define-fringe-bitmap bitmap bits &optional height width align ++This function defines the symbol @var{bitmap} as a new fringe bitmap, ++or replaces an existing bitmap with that name. ++ ++The argument @var{bits} specifies the image to use. It should be ++either a string or a vector of integers, where each element (an ++integer) corresponds to one row of the bitmap. Each bit of an integer ++corresponds to one pixel of the bitmap, where the low bit corresponds ++to the rightmost pixel of the bitmap. ++ ++The height is normally the length of @var{bits}. However, you ++can specify a different height with non-@code{nil} @var{height}. The width ++is normally 8, but you can specify a different width with non-@code{nil} ++@var{width}. The width must be an integer between 1 and 16. ++ ++The argument @var{align} specifies the positioning of the bitmap ++relative to the range of rows where it is used; the default is to ++center the bitmap. The allowed values are @code{top}, @code{center}, ++or @code{bottom}. ++ ++The @var{align} argument may also be a list @code{(@var{align} ++@var{periodic})} where @var{align} is interpreted as described above. ++If @var{periodic} is non-@code{nil}, it specifies that the rows in ++@code{bits} should be repeated enough times to reach the specified ++height. ++@end defun ++ ++@defun destroy-fringe-bitmap bitmap ++This function destroy the fringe bitmap identified by @var{bitmap}. ++If @var{bitmap} identifies a standard fringe bitmap, it actually ++restores the standard definition of that bitmap, instead of ++eliminating it entirely. ++@end defun ++ ++@defun set-fringe-bitmap-face bitmap &optional face ++This sets the face for the fringe bitmap @var{bitmap} to @var{face}. ++If @var{face} is @code{nil}, it selects the @code{fringe} face. The ++bitmap's face controls the color to draw it in. ++ ++@var{face} is merged with the @code{fringe} face, so normally ++@var{face} should specify only the foreground color. ++@end defun ++ ++@node Overlay Arrow ++@subsection The Overlay Arrow ++@c @cindex overlay arrow Duplicates variable names ++ ++ The @dfn{overlay arrow} is useful for directing the user's attention ++to a particular line in a buffer. For example, in the modes used for ++interface to debuggers, the overlay arrow indicates the line of code ++about to be executed. This feature has nothing to do with ++@dfn{overlays} (@pxref{Overlays}). ++ ++@defvar overlay-arrow-string ++This variable holds the string to display to call attention to a ++particular line, or @code{nil} if the arrow feature is not in use. ++On a graphical display the contents of the string are ignored; instead a ++glyph is displayed in the fringe area to the left of the display area. ++@end defvar ++ ++@defvar overlay-arrow-position ++This variable holds a marker that indicates where to display the overlay ++arrow. It should point at the beginning of a line. On a non-graphical ++display the arrow text ++appears at the beginning of that line, overlaying any text that would ++otherwise appear. Since the arrow is usually short, and the line ++usually begins with indentation, normally nothing significant is ++overwritten. ++ ++The overlay-arrow string is displayed in any given buffer if the value ++of @code{overlay-arrow-position} in that buffer points into that ++buffer. Thus, it is possible to display multiple overlay arrow strings ++by creating buffer-local bindings of @code{overlay-arrow-position}. ++However, it is usually cleaner to use ++@code{overlay-arrow-variable-list} to achieve this result. ++@c !!! overlay-arrow-position: but the overlay string may remain in the display ++@c of some other buffer until an update is required. This should be fixed ++@c now. Is it? ++@end defvar ++ ++ You can do a similar job by creating an overlay with a ++@code{before-string} property. @xref{Overlay Properties}. ++ ++ You can define multiple overlay arrows via the variable ++@code{overlay-arrow-variable-list}. ++ ++@defvar overlay-arrow-variable-list ++This variable's value is a list of variables, each of which specifies ++the position of an overlay arrow. The variable ++@code{overlay-arrow-position} has its normal meaning because it is on ++this list. ++@end defvar ++ ++Each variable on this list can have properties ++@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that ++specify an overlay arrow string (for text-only terminals) or fringe ++bitmap (for graphical terminals) to display at the corresponding ++overlay arrow position. If either property is not set, the default ++@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator ++is used. ++ ++@node Scroll Bars ++@section Scroll Bars ++@cindex scroll bars ++ ++Normally the frame parameter @code{vertical-scroll-bars} controls ++whether the windows in the frame have vertical scroll bars, and ++whether they are on the left or right. The frame parameter ++@code{scroll-bar-width} specifies how wide they are (@code{nil} ++meaning the default). @xref{Layout Parameters}. ++ ++@defun frame-current-scroll-bars &optional frame ++This function reports the scroll bar type settings for frame ++@var{frame}. The value is a cons cell ++@code{(@var{vertical-type} .@: @var{horizontal-type})}, where ++@var{vertical-type} is either @code{left}, @code{right}, or @code{nil} ++(which means no scroll bar.) @var{horizontal-type} is meant to ++specify the horizontal scroll bar type, but since they are not ++implemented, it is always @code{nil}. ++@end defun ++ ++@vindex vertical-scroll-bar ++ You can enable or disable scroll bars for a particular buffer, ++by setting the variable @code{vertical-scroll-bar}. This variable ++automatically becomes buffer-local when set. The possible values are ++@code{left}, @code{right}, @code{t}, which means to use the ++frame's default, and @code{nil} for no scroll bar. ++ ++ You can also control this for individual windows. Call the function ++@code{set-window-scroll-bars} to specify what to do for a specific window: ++ ++@defun set-window-scroll-bars window width &optional vertical-type horizontal-type ++This function sets the width and type of scroll bars for window ++@var{window}. ++ ++@var{width} specifies the scroll bar width in pixels (@code{nil} means ++use the width specified for the frame). @var{vertical-type} specifies ++whether to have a vertical scroll bar and, if so, where. The possible ++values are @code{left}, @code{right} and @code{nil}, just like the ++values of the @code{vertical-scroll-bars} frame parameter. ++ ++The argument @var{horizontal-type} is meant to specify whether and ++where to have horizontal scroll bars, but since they are not ++implemented, it has no effect. If @var{window} is @code{nil}, the ++selected window is used. ++@end defun ++ ++@defun window-scroll-bars &optional window ++Report the width and type of scroll bars specified for @var{window}. ++If @var{window} is omitted or @code{nil}, the selected window is used. ++The value is a list of the form @code{(@var{width} ++@var{cols} @var{vertical-type} @var{horizontal-type})}. The value ++@var{width} is the value that was specified for the width (which may ++be @code{nil}); @var{cols} is the number of columns that the scroll ++bar actually occupies. ++ ++@var{horizontal-type} is not actually meaningful. ++@end defun ++ ++If you don't specify these values for a window with ++@code{set-window-scroll-bars}, the buffer-local variables ++@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being ++displayed control the window's vertical scroll bars. The function ++@code{set-window-buffer} examines these variables. If you change them ++in a buffer that is already visible in a window, you can make the ++window take note of the new values by calling @code{set-window-buffer} ++specifying the same buffer that is already displayed. ++ ++@defopt scroll-bar-mode ++This variable, always local in all buffers, controls whether and where ++to put scroll bars in windows displaying the buffer. The possible values ++are @code{nil} for no scroll bar, @code{left} to put a scroll bar on ++the left, and @code{right} to put a scroll bar on the right. ++@end defopt ++ ++@defun window-current-scroll-bars &optional window ++This function reports the scroll bar type for window @var{window}. ++If @var{window} is omitted or @code{nil}, the selected window is used. ++The value is a cons cell ++@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike ++@code{window-scroll-bars}, this reports the scroll bar type actually ++used, once frame defaults and @code{scroll-bar-mode} are taken into ++account. ++@end defun ++ ++@defvar scroll-bar-width ++This variable, always local in all buffers, specifies the width of the ++buffer's scroll bars, measured in pixels. A value of @code{nil} means ++to use the value specified by the frame. ++@end defvar ++ ++@node Display Property ++@section The @code{display} Property ++@cindex display specification ++@kindex display @r{(text property)} ++ ++ The @code{display} text property (or overlay property) is used to ++insert images into text, and also control other aspects of how text ++displays. The value of the @code{display} property should be a ++display specification, or a list or vector containing several display ++specifications. Display specifications in the same @code{display} ++property value generally apply in parallel to the text they cover. ++ ++ If several sources (overlays and/or a text property) specify values ++for the @code{display} property, only one of the values takes effect, ++following the rules of @code{get-char-property}. @xref{Examining ++Properties}. ++ ++ The rest of this section describes several kinds of ++display specifications and what they mean. ++ ++@menu ++* Replacing Specs:: Display specs that replace the text. ++* Specified Space:: Displaying one space with a specified width. ++* Pixel Specification:: Specifying space width or height in pixels. ++* Other Display Specs:: Displaying an image; magnifying text; moving it ++ up or down on the page; adjusting the width ++ of spaces within text. ++* Display Margins:: Displaying text or images to the side of the main text. ++@end menu ++ ++@node Replacing Specs ++@subsection Display Specs That Replace The Text ++ ++ Some kinds of @code{display} specifications specify something to ++display instead of the text that has the property. These are called ++@dfn{replacing} display specifications. Emacs does not allow the user ++to interactively move point into the middle of buffer text that is ++replaced in this way. ++ ++ If a list of display specifications includes more than one replacing ++display specification, the first overrides the rest. Replacing ++display specifications make most other display specifications ++irrelevant, since those don't apply to the replacement. ++ ++ For replacing display specifications, ``the text that has the ++property'' means all the consecutive characters that have the same ++Lisp object as their @code{display} property; these characters are ++replaced as a single unit. By contrast, characters that have similar ++but distinct Lisp objects as their @code{display} properties are ++handled separately. Here's a function that illustrates this point: ++ ++@smallexample ++(defun foo () ++ (goto-char (point-min)) ++ (dotimes (i 5) ++ (let ((string (concat "A"))) ++ (put-text-property (point) (1+ (point)) 'display string) ++ (forward-char 1) ++ (put-text-property (point) (1+ (point)) 'display string) ++ (forward-char 1)))) ++@end smallexample ++ ++@noindent ++It gives each of the first ten characters in the buffer string ++@code{"A"} as the @code{display} property, but they don't all get the ++same string. The first two characters get the same string, so they ++together are replaced with one @samp{A}. The next two characters get ++a second string, so they together are replaced with one @samp{A}. ++Likewise for each following pair of characters. Thus, the ten ++characters appear as five A's. This function would have the same ++results: ++ ++@smallexample ++(defun foo () ++ (goto-char (point-min)) ++ (dotimes (i 5) ++ (let ((string (concat "A"))) ++ (put-text-property (point) (+ 2 (point)) 'display string) ++ (put-text-property (point) (1+ (point)) 'display string) ++ (forward-char 2)))) ++@end smallexample ++ ++@noindent ++This illustrates that what matters is the property value for ++each character. If two consecutive characters have the same ++object as the @code{display} property value, it's irrelevant ++whether they got this property from a single call to ++@code{put-text-property} or from two different calls. ++ ++@node Specified Space ++@subsection Specified Spaces ++@cindex spaces, specified height or width ++@cindex variable-width spaces ++ ++ To display a space of specified width and/or height, use a display ++specification of the form @code{(space . @var{props})}, where ++@var{props} is a property list (a list of alternating properties and ++values). You can put this property on one or more consecutive ++characters; a space of the specified height and width is displayed in ++place of @emph{all} of those characters. These are the properties you ++can use in @var{props} to specify the weight of the space: ++ ++@table @code ++@item :width @var{width} ++If @var{width} is an integer or floating point number, it specifies ++that the space width should be @var{width} times the normal character ++width. @var{width} can also be a @dfn{pixel width} specification ++(@pxref{Pixel Specification}). ++ ++@item :relative-width @var{factor} ++Specifies that the width of the stretch should be computed from the ++first character in the group of consecutive characters that have the ++same @code{display} property. The space width is the width of that ++character, multiplied by @var{factor}. ++ ++@item :align-to @var{hpos} ++Specifies that the space should be wide enough to reach @var{hpos}. ++If @var{hpos} is a number, it is measured in units of the normal ++character width. @var{hpos} can also be a @dfn{pixel width} ++specification (@pxref{Pixel Specification}). ++@end table ++ ++ You should use one and only one of the above properties. You can ++also specify the height of the space, with these properties: ++ ++@table @code ++@item :height @var{height} ++Specifies the height of the space. ++If @var{height} is an integer or floating point number, it specifies ++that the space height should be @var{height} times the normal character ++height. The @var{height} may also be a @dfn{pixel height} specification ++(@pxref{Pixel Specification}). ++ ++@item :relative-height @var{factor} ++Specifies the height of the space, multiplying the ordinary height ++of the text having this display specification by @var{factor}. ++ ++@item :ascent @var{ascent} ++If the value of @var{ascent} is a non-negative number no greater than ++100, it specifies that @var{ascent} percent of the height of the space ++should be considered as the ascent of the space---that is, the part ++above the baseline. The ascent may also be specified in pixel units ++with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}). ++ ++@end table ++ ++ Don't use both @code{:height} and @code{:relative-height} together. ++ ++ The @code{:width} and @code{:align-to} properties are supported on ++non-graphic terminals, but the other space properties in this section ++are not. ++ ++@node Pixel Specification ++@subsection Pixel Specification for Spaces ++@cindex spaces, pixel specification ++ ++ The value of the @code{:width}, @code{:align-to}, @code{:height}, ++and @code{:ascent} properties can be a special kind of expression that ++is evaluated during redisplay. The result of the evaluation is used ++as an absolute number of pixels. ++ ++ The following expressions are supported: ++ ++@smallexample ++@group ++ @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form} ++ @var{num} ::= @var{integer} | @var{float} | @var{symbol} ++ @var{unit} ::= in | mm | cm | width | height ++@end group ++@group ++ @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin ++ | scroll-bar | text ++ @var{pos} ::= left | center | right ++ @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...) ++ @var{op} ::= + | - ++@end group ++@end smallexample ++ ++ The form @var{num} specifies a fraction of the default frame font ++height or width. The form @code{(@var{num})} specifies an absolute ++number of pixels. If @var{num} is a symbol, @var{symbol}, its ++buffer-local variable binding is used. ++ ++ The @code{in}, @code{mm}, and @code{cm} units specify the number of ++pixels per inch, millimeter, and centimeter, respectively. The ++@code{width} and @code{height} units correspond to the default width ++and height of the current face. An image specification @code{image} ++corresponds to the width or height of the image. ++ ++ The @code{left-fringe}, @code{right-fringe}, @code{left-margin}, ++@code{right-margin}, @code{scroll-bar}, and @code{text} elements ++specify to the width of the corresponding area of the window. ++ ++ The @code{left}, @code{center}, and @code{right} positions can be ++used with @code{:align-to} to specify a position relative to the left ++edge, center, or right edge of the text area. ++ ++ Any of the above window elements (except @code{text}) can also be ++used with @code{:align-to} to specify that the position is relative to ++the left edge of the given area. Once the base offset for a relative ++position has been set (by the first occurrence of one of these ++symbols), further occurrences of these symbols are interpreted as the ++width of the specified area. For example, to align to the center of ++the left-margin, use ++ ++@example ++:align-to (+ left-margin (0.5 . left-margin)) ++@end example ++ ++ If no specific base offset is set for alignment, it is always relative ++to the left edge of the text area. For example, @samp{:align-to 0} in a ++header-line aligns with the first text column in the text area. ++ ++ A value of the form @code{(@var{num} . @var{expr})} stands for the ++product of the values of @var{num} and @var{expr}. For example, ++@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 . ++@var{image})} specifies half the width (or height) of the specified ++image. ++ ++ The form @code{(+ @var{expr} ...)} adds up the value of the ++expressions. The form @code{(- @var{expr} ...)} negates or subtracts ++the value of the expressions. ++ ++@node Other Display Specs ++@subsection Other Display Specifications ++ ++ Here are the other sorts of display specifications that you can use ++in the @code{display} text property. ++ ++@table @code ++@item @var{string} ++Display @var{string} instead of the text that has this property. ++ ++Recursive display specifications are not supported---@var{string}'s ++@code{display} properties, if any, are not used. ++ ++@item (image . @var{image-props}) ++This kind of display specification is an image descriptor (@pxref{Images}). ++When used as a display specification, it means to display the image ++instead of the text that has the display specification. ++ ++@item (slice @var{x} @var{y} @var{width} @var{height}) ++This specification together with @code{image} specifies a @dfn{slice} ++(a partial area) of the image to display. The elements @var{y} and ++@var{x} specify the top left corner of the slice, within the image; ++@var{width} and @var{height} specify the width and height of the ++slice. Integer values are numbers of pixels. A floating point number ++in the range 0.0--1.0 stands for that fraction of the width or height ++of the entire image. ++ ++@item ((margin nil) @var{string}) ++A display specification of this form means to display @var{string} ++instead of the text that has the display specification, at the same ++position as that text. It is equivalent to using just @var{string}, ++but it is done as a special case of marginal display (@pxref{Display ++Margins}). ++ ++@item (space-width @var{factor}) ++This display specification affects all the space characters within the ++text that has the specification. It displays all of these spaces ++@var{factor} times as wide as normal. The element @var{factor} should ++be an integer or float. Characters other than spaces are not affected ++at all; in particular, this has no effect on tab characters. ++ ++@item (height @var{height}) ++This display specification makes the text taller or shorter. ++Here are the possibilities for @var{height}: ++ ++@table @asis ++@item @code{(+ @var{n})} ++This means to use a font that is @var{n} steps larger. A ``step'' is ++defined by the set of available fonts---specifically, those that match ++what was otherwise specified for this text, in all attributes except ++height. Each size for which a suitable font is available counts as ++another step. @var{n} should be an integer. ++ ++@item @code{(- @var{n})} ++This means to use a font that is @var{n} steps smaller. ++ ++@item a number, @var{factor} ++A number, @var{factor}, means to use a font that is @var{factor} times ++as tall as the default font. ++ ++@item a symbol, @var{function} ++A symbol is a function to compute the height. It is called with the ++current height as argument, and should return the new height to use. ++ ++@item anything else, @var{form} ++If the @var{height} value doesn't fit the previous possibilities, it is ++a form. Emacs evaluates it to get the new height, with the symbol ++@code{height} bound to the current specified font height. ++@end table ++ ++@item (raise @var{factor}) ++This kind of display specification raises or lowers the text ++it applies to, relative to the baseline of the line. ++ ++@var{factor} must be a number, which is interpreted as a multiple of the ++height of the affected text. If it is positive, that means to display ++the characters raised. If it is negative, that means to display them ++lower down. ++ ++If the text also has a @code{height} display specification, that does ++not affect the amount of raising or lowering, which is based on the ++faces used for the text. ++@end table ++ ++@c We put all the `@code{(when ...)}' on one line to encourage ++@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot ++@c was at eol; the info file ended up w/ two spaces rendered after it. ++ You can make any display specification conditional. To do that, ++package it in another list of the form ++@code{(when @var{condition} . @var{spec})}. ++Then the specification @var{spec} applies only when ++@var{condition} evaluates to a non-@code{nil} value. During the ++evaluation, @code{object} is bound to the string or buffer having the ++conditional @code{display} property. @code{position} and ++@code{buffer-position} are bound to the position within @code{object} ++and the buffer position where the @code{display} property was found, ++respectively. Both positions can be different when @code{object} is a ++string. ++ ++@node Display Margins ++@subsection Displaying in the Margins ++@cindex display margins ++@cindex margins, display ++ ++ A buffer can have blank areas called @dfn{display margins} on the ++left and on the right. Ordinary text never appears in these areas, ++but you can put things into the display margins using the ++@code{display} property. There is currently no way to make text or ++images in the margin mouse-sensitive. ++ ++ The way to display something in the margins is to specify it in a ++margin display specification in the @code{display} property of some ++text. This is a replacing display specification, meaning that the ++text you put it on does not get displayed; the margin display appears, ++but that text does not. ++ ++ A margin display specification looks like @code{((margin ++right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}. ++Here, @var{spec} is another display specification that says what to ++display in the margin. Typically it is a string of text to display, ++or an image descriptor. ++ ++ To display something in the margin @emph{in association with} ++certain buffer text, without altering or preventing the display of ++that text, put a @code{before-string} property on the text and put the ++margin display specification on the contents of the before-string. ++ ++ Before the display margins can display anything, you must give ++them a nonzero width. The usual way to do that is to set these ++variables: ++ ++@defvar left-margin-width ++This variable specifies the width of the left margin. ++It is buffer-local in all buffers. ++@end defvar ++ ++@defvar right-margin-width ++This variable specifies the width of the right margin. ++It is buffer-local in all buffers. ++@end defvar ++ ++ Setting these variables does not immediately affect the window. These ++variables are checked when a new buffer is displayed in the window. ++Thus, you can make changes take effect by calling ++@code{set-window-buffer}. ++ ++ You can also set the margin widths immediately. ++ ++@defun set-window-margins window left &optional right ++This function specifies the margin widths for window @var{window}. ++The argument @var{left} controls the left margin and ++@var{right} controls the right margin (default @code{0}). ++@end defun ++ ++@defun window-margins &optional window ++This function returns the left and right margins of @var{window} ++as a cons cell of the form @code{(@var{left} . @var{right})}. ++If @var{window} is @code{nil}, the selected window is used. ++@end defun ++ ++@node Images ++@section Images ++@cindex images in buffers ++ ++ To display an image in an Emacs buffer, you must first create an image ++descriptor, then use it as a display specifier in the @code{display} ++property of text that is displayed (@pxref{Display Property}). ++ ++ Emacs is usually able to display images when it is run on a ++graphical terminal. Images cannot be displayed in a text terminal, on ++certain graphical terminals that lack the support for this, or if ++Emacs is compiled without image support. You can use the function ++@code{display-images-p} to determine if images can in principle be ++displayed (@pxref{Display Feature Testing}). ++ ++@menu ++* Image Formats:: Supported image formats. ++* Image Descriptors:: How to specify an image for use in @code{:display}. ++* XBM Images:: Special features for XBM format. ++* XPM Images:: Special features for XPM format. ++* GIF Images:: Special features for GIF format. ++* TIFF Images:: Special features for TIFF format. ++* PostScript Images:: Special features for PostScript format. ++* Other Image Types:: Various other formats are supported. ++* Defining Images:: Convenient ways to define an image for later use. ++* Showing Images:: Convenient ways to display an image once it is defined. ++* Image Cache:: Internal mechanisms of image display. ++@end menu ++ ++@node Image Formats ++@subsection Image Formats ++@cindex image formats ++@cindex image types ++ ++ Emacs can display a number of different image formats; some of them ++are supported only if particular support libraries are installed on ++your machine. In some environments, Emacs can load image ++libraries on demand; if so, the variable @code{image-library-alist} ++can be used to modify the set of known names for these dynamic ++libraries (though it is not possible to add new image formats). ++ ++ The supported image formats include XBM, XPM (this requires the ++libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring ++@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the ++@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff} ++v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring ++@code{librsvg} 2.0.0). ++ ++ You specify one of these formats with an image type symbol. The image ++type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, ++@code{pbm}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. ++ ++@defvar image-types ++This variable contains a list of those image type symbols that are ++potentially supported in the current configuration. ++@emph{Potentially} here means that Emacs knows about the image types, ++not necessarily that they can be loaded (they could depend on ++unavailable dynamic libraries, for example). ++ ++To know which image types are really available, use ++@code{image-type-available-p}. ++@end defvar ++ ++@defvar image-library-alist ++This in an alist of image types vs external libraries needed to ++display them. ++ ++Each element is a list @code{(@var{image-type} @var{library}...)}, ++where the car is a supported image format from @code{image-types}, and ++the rest are strings giving alternate filenames for the corresponding ++external libraries to load. ++ ++Emacs tries to load the libraries in the order they appear on the ++list; if none is loaded, the running session of Emacs won't support ++the image type. @code{pbm} and @code{xbm} don't need to be listed; ++they're always supported. ++ ++This variable is ignored if the image libraries are statically linked ++into Emacs. ++@end defvar ++ ++@defun image-type-available-p type ++This function returns non-@code{nil} if image type @var{type} is ++available, i.e., if images of this type can be loaded and displayed in ++Emacs. @var{type} should be one of the types contained in ++@code{image-types}. ++ ++For image types whose support libraries are statically linked, this ++function always returns @code{t}; for other image types, it returns ++@code{t} if the dynamic library could be loaded, @code{nil} otherwise. ++@end defun ++ ++@node Image Descriptors ++@subsection Image Descriptors ++@cindex image descriptor ++ ++ An image description is a list of the form @code{(image . @var{props})}, ++where @var{props} is a property list containing alternating keyword ++symbols (symbols whose names start with a colon) and their values. ++You can use any Lisp object as a property, but the only properties ++that have any special meaning are certain symbols, all of them keywords. ++ ++ Every image descriptor must contain the property @code{:type ++@var{type}} to specify the format of the image. The value of @var{type} ++should be an image type symbol; for example, @code{xpm} for an image in ++XPM format. ++ ++ Here is a list of other properties that are meaningful for all image ++types: ++ ++@table @code ++@item :file @var{file} ++The @code{:file} property says to load the image from file ++@var{file}. If @var{file} is not an absolute file name, it is expanded ++in @code{data-directory}. ++ ++@item :data @var{data} ++The @code{:data} property says the actual contents of the image. ++Each image must use either @code{:data} or @code{:file}, but not both. ++For most image types, the value of the @code{:data} property should be a ++string containing the image data; we recommend using a unibyte string. ++ ++Before using @code{:data}, look for further information in the section ++below describing the specific image format. For some image types, ++@code{:data} may not be supported; for some, it allows other data types; ++for some, @code{:data} alone is not enough, so you need to use other ++image properties along with @code{:data}. ++ ++@item :margin @var{margin} ++The @code{:margin} property specifies how many pixels to add as an ++extra margin around the image. The value, @var{margin}, must be a ++non-negative number, or a pair @code{(@var{x} . @var{y})} of such ++numbers. If it is a pair, @var{x} specifies how many pixels to add ++horizontally, and @var{y} specifies how many pixels to add vertically. ++If @code{:margin} is not specified, the default is zero. ++ ++@item :ascent @var{ascent} ++The @code{:ascent} property specifies the amount of the image's ++height to use for its ascent---that is, the part above the baseline. ++The value, @var{ascent}, must be a number in the range 0 to 100, or ++the symbol @code{center}. ++ ++If @var{ascent} is a number, that percentage of the image's height is ++used for its ascent. ++ ++If @var{ascent} is @code{center}, the image is vertically centered ++around a centerline which would be the vertical centerline of text drawn ++at the position of the image, in the manner specified by the text ++properties and overlays that apply to the image. ++ ++If this property is omitted, it defaults to 50. ++ ++@item :relief @var{relief} ++The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle ++around the image. The value, @var{relief}, specifies the width of the ++shadow lines, in pixels. If @var{relief} is negative, shadows are drawn ++so that the image appears as a pressed button; otherwise, it appears as ++an unpressed button. ++ ++@item :conversion @var{algorithm} ++The @code{:conversion} property, if non-@code{nil}, specifies a ++conversion algorithm that should be applied to the image before it is ++displayed; the value, @var{algorithm}, specifies which algorithm. ++ ++@table @code ++@item laplace ++@itemx emboss ++Specifies the Laplace edge detection algorithm, which blurs out small ++differences in color while highlighting larger differences. People ++sometimes consider this useful for displaying the image for a ++``disabled'' button. ++ ++@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust}) ++Specifies a general edge-detection algorithm. @var{matrix} must be ++either a nine-element list or a nine-element vector of numbers. A pixel ++at position @math{x/y} in the transformed image is computed from ++original pixels around that position. @var{matrix} specifies, for each ++pixel in the neighborhood of @math{x/y}, a factor with which that pixel ++will influence the transformed pixel; element @math{0} specifies the ++factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for ++the pixel at @math{x/y-1} etc., as shown below: ++@iftex ++@tex ++$$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr ++ x-1/y & x/y & x+1/y \cr ++ x-1/y+1& x/y+1 & x+1/y+1 \cr}$$ ++@end tex ++@end iftex ++@ifnottex ++@display ++ (x-1/y-1 x/y-1 x+1/y-1 ++ x-1/y x/y x+1/y ++ x-1/y+1 x/y+1 x+1/y+1) ++@end display ++@end ifnottex ++ ++The resulting pixel is computed from the color intensity of the color ++resulting from summing up the RGB values of surrounding pixels, ++multiplied by the specified factors, and dividing that sum by the sum ++of the factors' absolute values. ++ ++Laplace edge-detection currently uses a matrix of ++@iftex ++@tex ++$$\pmatrix{1 & 0 & 0 \cr ++ 0& 0 & 0 \cr ++ 9 & 9 & -1 \cr}$$ ++@end tex ++@end iftex ++@ifnottex ++@display ++ (1 0 0 ++ 0 0 0 ++ 9 9 -1) ++@end display ++@end ifnottex ++ ++Emboss edge-detection uses a matrix of ++@iftex ++@tex ++$$\pmatrix{ 2 & -1 & 0 \cr ++ -1 & 0 & 1 \cr ++ 0 & 1 & -2 \cr}$$ ++@end tex ++@end iftex ++@ifnottex ++@display ++ ( 2 -1 0 ++ -1 0 1 ++ 0 1 -2) ++@end display ++@end ifnottex ++ ++@item disabled ++Specifies transforming the image so that it looks ``disabled.'' ++@end table ++ ++@item :mask @var{mask} ++If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build ++a clipping mask for the image, so that the background of a frame is ++visible behind the image. If @var{bg} is not specified, or if @var{bg} ++is @code{t}, determine the background color of the image by looking at ++the four corners of the image, assuming the most frequently occurring ++color from the corners is the background color of the image. Otherwise, ++@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})} ++specifying the color to assume for the background of the image. ++ ++If @var{mask} is @code{nil}, remove a mask from the image, if it has ++one. Images in some formats include a mask which can be removed by ++specifying @code{:mask nil}. ++ ++@item :pointer @var{shape} ++This specifies the pointer shape when the mouse pointer is over this ++image. @xref{Pointer Shape}, for available pointer shapes. ++ ++@item :map @var{map} ++This associates an image map of @dfn{hot spots} with this image. ++ ++An image map is an alist where each element has the format ++@code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified ++as either a rectangle, a circle, or a polygon. ++ ++A rectangle is a cons ++@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))} ++which specifies the pixel coordinates of the upper left and bottom right ++corners of the rectangle area. ++ ++A circle is a cons ++@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))} ++which specifies the center and the radius of the circle; @var{r} may ++be a float or integer. ++ ++A polygon is a cons ++@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])} ++where each pair in the vector describes one corner in the polygon. ++ ++When the mouse pointer lies on a hot-spot area of an image, the ++@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo} ++property, that defines a tool-tip for the hot-spot, and if it contains ++a @code{pointer} property, that defines the shape of the mouse cursor when ++it is on the hot-spot. ++@xref{Pointer Shape}, for available pointer shapes. ++ ++When you click the mouse when the mouse pointer is over a hot-spot, an ++event is composed by combining the @var{id} of the hot-spot with the ++mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's ++@var{id} is @code{area4}. ++@end table ++ ++@defun image-mask-p spec &optional frame ++This function returns @code{t} if image @var{spec} has a mask bitmap. ++@var{frame} is the frame on which the image will be displayed. ++@var{frame} @code{nil} or omitted means to use the selected frame ++(@pxref{Input Focus}). ++@end defun ++ ++@node XBM Images ++@subsection XBM Images ++@cindex XBM ++ ++ To use XBM format, specify @code{xbm} as the image type. This image ++format doesn't require an external library, so images of this type are ++always supported. ++ ++ Additional image properties supported for the @code{xbm} image type are: ++ ++@table @code ++@item :foreground @var{foreground} ++The value, @var{foreground}, should be a string specifying the image ++foreground color, or @code{nil} for the default color. This color is ++used for each pixel in the XBM that is 1. The default is the frame's ++foreground color. ++ ++@item :background @var{background} ++The value, @var{background}, should be a string specifying the image ++background color, or @code{nil} for the default color. This color is ++used for each pixel in the XBM that is 0. The default is the frame's ++background color. ++@end table ++ ++ If you specify an XBM image using data within Emacs instead of an ++external file, use the following three properties: ++ ++@table @code ++@item :data @var{data} ++The value, @var{data}, specifies the contents of the image. ++There are three formats you can use for @var{data}: ++ ++@itemize @bullet ++@item ++A vector of strings or bool-vectors, each specifying one line of the ++image. Do specify @code{:height} and @code{:width}. ++ ++@item ++A string containing the same byte sequence as an XBM file would contain. ++You must not specify @code{:height} and @code{:width} in this case, ++because omitting them is what indicates the data has the format of an ++XBM file. The file contents specify the height and width of the image. ++ ++@item ++A string or a bool-vector containing the bits of the image (plus perhaps ++some extra bits at the end that will not be used). It should contain at ++least @var{width} * @code{height} bits. In this case, you must specify ++@code{:height} and @code{:width}, both to indicate that the string ++contains just the bits rather than a whole XBM file, and to specify the ++size of the image. ++@end itemize ++ ++@item :width @var{width} ++The value, @var{width}, specifies the width of the image, in pixels. ++ ++@item :height @var{height} ++The value, @var{height}, specifies the height of the image, in pixels. ++@end table ++ ++@node XPM Images ++@subsection XPM Images ++@cindex XPM ++ ++ To use XPM format, specify @code{xpm} as the image type. The ++additional image property @code{:color-symbols} is also meaningful with ++the @code{xpm} image type: ++ ++@table @code ++@item :color-symbols @var{symbols} ++The value, @var{symbols}, should be an alist whose elements have the ++form @code{(@var{name} . @var{color})}. In each element, @var{name} is ++the name of a color as it appears in the image file, and @var{color} ++specifies the actual color to use for displaying that name. ++@end table ++ ++@node GIF Images ++@subsection GIF Images ++@cindex GIF ++ ++ For GIF images, specify image type @code{gif}. ++ ++@table @code ++@item :index @var{index} ++You can use @code{:index} to specify one image from a GIF file that ++contains more than one image. This property specifies use of image ++number @var{index} from the file. If the GIF file doesn't contain an ++image with index @var{index}, the image displays as a hollow box. ++@end table ++ ++@ignore ++This could be used to implement limited support for animated GIFs. ++For example, the following function displays a multi-image GIF file ++at point-min in the current buffer, switching between sub-images ++every 0.1 seconds. ++ ++(defun show-anim (file max) ++ "Display multi-image GIF file FILE which contains MAX subimages." ++ (display-anim (current-buffer) file 0 max t)) ++ ++(defun display-anim (buffer file idx max first-time) ++ (when (= idx max) ++ (setq idx 0)) ++ (let ((img (create-image file nil :image idx))) ++ (save-excursion ++ (set-buffer buffer) ++ (goto-char (point-min)) ++ (unless first-time (delete-char 1)) ++ (insert-image img)) ++ (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil))) ++@end ignore ++ ++@node TIFF Images ++@subsection TIFF Images ++@cindex TIFF ++ ++ For TIFF images, specify image type @code{tiff}. ++ ++@table @code ++@item :index @var{index} ++You can use @code{:index} to specify one image from a TIFF file that ++contains more than one image. This property specifies use of image ++number @var{index} from the file. If the TIFF file doesn't contain an ++image with index @var{index}, the image displays as a hollow box. ++@end table ++ ++@node PostScript Images ++@subsection PostScript Images ++@cindex postscript images ++ ++ To use PostScript for an image, specify image type @code{postscript}. ++This works only if you have Ghostscript installed. You must always use ++these three properties: ++ ++@table @code ++@item :pt-width @var{width} ++The value, @var{width}, specifies the width of the image measured in ++points (1/72 inch). @var{width} must be an integer. ++ ++@item :pt-height @var{height} ++The value, @var{height}, specifies the height of the image in points ++(1/72 inch). @var{height} must be an integer. ++ ++@item :bounding-box @var{box} ++The value, @var{box}, must be a list or vector of four integers, which ++specifying the bounding box of the PostScript image, analogous to the ++@samp{BoundingBox} comment found in PostScript files. ++ ++@example ++%%BoundingBox: 22 171 567 738 ++@end example ++@end table ++ ++@node Other Image Types ++@subsection Other Image Types ++@cindex PBM ++ ++ For PBM images, specify image type @code{pbm}. Color, gray-scale and ++monochromatic images are supported. For mono PBM images, two additional ++image properties are supported. ++ ++@table @code ++@item :foreground @var{foreground} ++The value, @var{foreground}, should be a string specifying the image ++foreground color, or @code{nil} for the default color. This color is ++used for each pixel in the PBM that is 1. The default is the frame's ++foreground color. ++ ++@item :background @var{background} ++The value, @var{background}, should be a string specifying the image ++background color, or @code{nil} for the default color. This color is ++used for each pixel in the PBM that is 0. The default is the frame's ++background color. ++@end table ++ ++ For JPEG images, specify image type @code{jpeg}. ++ ++ For TIFF images, specify image type @code{tiff}. ++ ++ For PNG images, specify image type @code{png}. ++ ++ For SVG images, specify image type @code{svg}. ++ ++@node Defining Images ++@subsection Defining Images ++ ++ The functions @code{create-image}, @code{defimage} and ++@code{find-image} provide convenient ways to create image descriptors. ++ ++@defun create-image file-or-data &optional type data-p &rest props ++This function creates and returns an image descriptor which uses the ++data in @var{file-or-data}. @var{file-or-data} can be a file name or ++a string containing the image data; @var{data-p} should be @code{nil} ++for the former case, non-@code{nil} for the latter case. ++ ++The optional argument @var{type} is a symbol specifying the image type. ++If @var{type} is omitted or @code{nil}, @code{create-image} tries to ++determine the image type from the file's first few bytes, or else ++from the file's name. ++ ++The remaining arguments, @var{props}, specify additional image ++properties---for example, ++ ++@example ++(create-image "foo.xpm" 'xpm nil :heuristic-mask t) ++@end example ++ ++The function returns @code{nil} if images of this type are not ++supported. Otherwise it returns an image descriptor. ++@end defun ++ ++@defmac defimage symbol specs &optional doc ++This macro defines @var{symbol} as an image name. The arguments ++@var{specs} is a list which specifies how to display the image. ++The third argument, @var{doc}, is an optional documentation string. ++ ++Each argument in @var{specs} has the form of a property list, and each ++one should specify at least the @code{:type} property and either the ++@code{:file} or the @code{:data} property. The value of @code{:type} ++should be a symbol specifying the image type, the value of ++@code{:file} is the file to load the image from, and the value of ++@code{:data} is a string containing the actual image data. Here is an ++example: ++ ++@example ++(defimage test-image ++ ((:type xpm :file "~/test1.xpm") ++ (:type xbm :file "~/test1.xbm"))) ++@end example ++ ++@code{defimage} tests each argument, one by one, to see if it is ++usable---that is, if the type is supported and the file exists. The ++first usable argument is used to make an image descriptor which is ++stored in @var{symbol}. ++ ++If none of the alternatives will work, then @var{symbol} is defined ++as @code{nil}. ++@end defmac ++ ++@defun find-image specs ++This function provides a convenient way to find an image satisfying one ++of a list of image specifications @var{specs}. ++ ++Each specification in @var{specs} is a property list with contents ++depending on image type. All specifications must at least contain the ++properties @code{:type @var{type}} and either @w{@code{:file @var{file}}} ++or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying ++the image type, e.g.@: @code{xbm}, @var{file} is the file to load the ++image from, and @var{data} is a string containing the actual image data. ++The first specification in the list whose @var{type} is supported, and ++@var{file} exists, is used to construct the image specification to be ++returned. If no specification is satisfied, @code{nil} is returned. ++ ++The image is looked for in @code{image-load-path}. ++@end defun ++ ++@defvar image-load-path ++This variable's value is a list of locations in which to search for ++image files. If an element is a string or a variable symbol whose ++value is a string, the string is taken to be the name of a directory ++to search. If an element is a variable symbol whose value is a list, ++that is taken to be a list of directory names to search. ++ ++The default is to search in the @file{images} subdirectory of the ++directory specified by @code{data-directory}, then the directory ++specified by @code{data-directory}, and finally in the directories in ++@code{load-path}. Subdirectories are not automatically included in ++the search, so if you put an image file in a subdirectory, you have to ++supply the subdirectory name explicitly. For example, to find the ++image @file{images/foo/bar.xpm} within @code{data-directory}, you ++should specify the image as follows: ++ ++@example ++(defimage foo-image '((:type xpm :file "foo/bar.xpm"))) ++@end example ++@end defvar ++ ++@defun image-load-path-for-library library image &optional path no-error ++This function returns a suitable search path for images used by the ++Lisp package @var{library}. ++ ++The function searches for @var{image} first using @code{image-load-path}, ++excluding @file{@code{data-directory}/images}, and then in ++@code{load-path}, followed by a path suitable for @var{library}, which ++includes @file{../../etc/images} and @file{../etc/images} relative to ++the library file itself, and finally in ++@file{@code{data-directory}/images}. ++ ++Then this function returns a list of directories which contains first ++the directory in which @var{image} was found, followed by the value of ++@code{load-path}. If @var{path} is given, it is used instead of ++@code{load-path}. ++ ++If @var{no-error} is non-@code{nil} and a suitable path can't be ++found, don't signal an error. Instead, return a list of directories as ++before, except that @code{nil} appears in place of the image directory. ++ ++Here is an example that uses a common idiom to provide compatibility ++with versions of Emacs that lack the variable @code{image-load-path}: ++ ++@example ++(defvar image-load-path) ; shush compiler ++(let* ((load-path (image-load-path-for-library ++ "mh-e" "mh-logo.xpm")) ++ (image-load-path (cons (car load-path) ++ (when (boundp 'image-load-path) ++ image-load-path)))) ++ (mh-tool-bar-folder-buttons-init)) ++@end example ++@end defun ++ ++@node Showing Images ++@subsection Showing Images ++ ++ You can use an image descriptor by setting up the @code{display} ++property yourself, but it is easier to use the functions in this ++section. ++ ++@defun insert-image image &optional string area slice ++This function inserts @var{image} in the current buffer at point. The ++value @var{image} should be an image descriptor; it could be a value ++returned by @code{create-image}, or the value of a symbol defined with ++@code{defimage}. The argument @var{string} specifies the text to put ++in the buffer to hold the image. If it is omitted or @code{nil}, ++@code{insert-image} uses @code{" "} by default. ++ ++The argument @var{area} specifies whether to put the image in a margin. ++If it is @code{left-margin}, the image appears in the left margin; ++@code{right-margin} specifies the right margin. If @var{area} is ++@code{nil} or omitted, the image is displayed at point within the ++buffer's text. ++ ++The argument @var{slice} specifies a slice of the image to insert. If ++@var{slice} is @code{nil} or omitted the whole image is inserted. ++Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width} ++@var{height})} which specifies the @var{x} and @var{y} positions and ++@var{width} and @var{height} of the image area to insert. Integer ++values are in units of pixels. A floating point number in the range ++0.0--1.0 stands for that fraction of the width or height of the entire ++image. ++ ++Internally, this function inserts @var{string} in the buffer, and gives ++it a @code{display} property which specifies @var{image}. @xref{Display ++Property}. ++@end defun ++ ++@defun insert-sliced-image image &optional string area rows cols ++This function inserts @var{image} in the current buffer at point, like ++@code{insert-image}, but splits the image into @var{rows}x@var{cols} ++equally sized slices. ++@end defun ++ ++@defun put-image image pos &optional string area ++This function puts image @var{image} in front of @var{pos} in the ++current buffer. The argument @var{pos} should be an integer or a ++marker. It specifies the buffer position where the image should appear. ++The argument @var{string} specifies the text that should hold the image ++as an alternative to the default. ++ ++The argument @var{image} must be an image descriptor, perhaps returned ++by @code{create-image} or stored by @code{defimage}. ++ ++The argument @var{area} specifies whether to put the image in a margin. ++If it is @code{left-margin}, the image appears in the left margin; ++@code{right-margin} specifies the right margin. If @var{area} is ++@code{nil} or omitted, the image is displayed at point within the ++buffer's text. ++ ++Internally, this function creates an overlay, and gives it a ++@code{before-string} property containing text that has a @code{display} ++property whose value is the image. (Whew!) ++@end defun ++ ++@defun remove-images start end &optional buffer ++This function removes images in @var{buffer} between positions ++@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil}, ++images are removed from the current buffer. ++ ++This removes only images that were put into @var{buffer} the way ++@code{put-image} does it, not images that were inserted with ++@code{insert-image} or in other ways. ++@end defun ++ ++@defun image-size spec &optional pixels frame ++This function returns the size of an image as a pair ++@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image ++specification. @var{pixels} non-@code{nil} means return sizes ++measured in pixels, otherwise return sizes measured in canonical ++character units (fractions of the width/height of the frame's default ++font). @var{frame} is the frame on which the image will be displayed. ++@var{frame} null or omitted means use the selected frame (@pxref{Input ++Focus}). ++@end defun ++ ++@defvar max-image-size ++This variable is used to define the maximum size of image that Emacs ++will load. Emacs will refuse to load (and display) any image that is ++larger than this limit. ++ ++If the value is an integer, it directly specifies the maximum ++image height and width, measured in pixels. If it is a floating ++point number, it specifies the maximum image height and width ++as a ratio to the frame height and width. If the value is ++non-numeric, there is no explicit limit on the size of images. ++ ++The purpose of this variable is to prevent unreasonably large images ++from accidentally being loaded into Emacs. It only takes effect the ++first time an image is loaded. Once an image is placed in the image ++cache, it can always be displayed, even if the value of ++@var{max-image-size} is subsequently changed (@pxref{Image Cache}). ++@end defvar ++ ++@node Image Cache ++@subsection Image Cache ++@cindex image cache ++ ++ Emacs caches images so that it can display them again more ++efficiently. When Emacs displays an image, it searches the image ++cache for an existing image specification @code{equal} to the desired ++specification. If a match is found, the image is displayed from the ++cache; otherwise, Emacs loads the image normally. ++ ++ Occasionally, you may need to tell Emacs to refresh the images ++associated with a given image specification. For example, suppose you ++display an image using a specification that contains a @code{:file} ++property. The image is automatically cached, and subsequent displays ++of that image, with the same image specification, will use the image ++cache. If the image file changes in the meantime, Emacs would be ++displaying the old version of the image. In such a situation, you can ++``refresh'' the image by calling @code{image-refresh}. ++ ++ In Emacs' current implementation, each graphical terminal possesses ++an image cache, which is shared by all the frames on that terminal ++(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame ++also refreshes it in all other frames on the same terminal. ++ ++@defun image-refresh spec &optional frame ++This function refreshes any images with image specifications ++@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is ++@code{nil}, it defaults to the selected frame. If @var{frame} is ++@code{t}, the refresh is applied to all existing frames. ++@end defun ++ ++@defun clear-image-cache &optional filter ++This function clears an image cache, removing all the images stored in ++it. If @var{filter} is omitted or @code{nil}, it clears the cache for ++the selected frame. If @var{filter} is a frame, it clears the cache ++for that frame. If @var{filter} is @code{t}, all image caches are ++cleared. Otherwise, @var{filter} is taken to be a file name, and all ++images associated with that file name are removed from all image ++caches. ++@end defun ++ ++If an image in the image cache has not been displayed for a specified ++period of time, Emacs removes it from the cache and frees the ++associated memory. ++ ++@defvar image-cache-eviction-delay ++This variable specifies the number of seconds an image can remain in the ++cache without being displayed. When an image is not displayed for this ++length of time, Emacs removes it from the image cache. ++ ++If the value is @code{nil}, Emacs does not remove images from the cache ++except when you explicitly clear it. This mode can be useful for ++debugging. ++@end defvar ++ ++@node Buttons ++@section Buttons ++@cindex buttons in buffers ++@cindex clickable buttons in buffers ++ ++ The @emph{button} package defines functions for inserting and ++manipulating clickable (with the mouse, or via keyboard commands) ++buttons in Emacs buffers, such as might be used for help hyper-links, ++etc. Emacs uses buttons for the hyper-links in help text and the like. ++ ++ A button is essentially a set of properties attached (via text ++properties or overlays) to a region of text in an Emacs buffer. These ++properties are called @dfn{button properties}. ++ ++ One of these properties (@code{action}) is a function, which will ++be called when the user invokes it using the keyboard or the mouse. ++The invoked function may then examine the button and use its other ++properties as desired. ++ ++ In some ways the Emacs button package duplicates functionality offered ++by the widget package (@pxref{Top, , Introduction, widget, The Emacs ++Widget Library}), but the button package has the advantage that it is ++much faster, much smaller, and much simpler to use (for elisp ++programmers---for users, the result is about the same). The extra ++speed and space savings are useful mainly if you need to create many ++buttons in a buffer (for instance an @code{*Apropos*} buffer uses ++buttons to make entries clickable, and may contain many thousands of ++entries). ++ ++@menu ++* Button Properties:: Button properties with special meanings. ++* Button Types:: Defining common properties for classes of buttons. ++* Making Buttons:: Adding buttons to Emacs buffers. ++* Manipulating Buttons:: Getting and setting properties of buttons. ++* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. ++@end menu ++ ++@node Button Properties ++@subsection Button Properties ++@cindex button properties ++ ++ Buttons have an associated list of properties defining their ++appearance and behavior, and other arbitrary properties may be used ++for application specific purposes. Some properties that have special ++meaning to the button package include: ++ ++@table @code ++@item action ++@kindex action @r{(button property)} ++The function to call when the user invokes the button, which is passed ++the single argument @var{button}. By default this is @code{ignore}, ++which does nothing. ++ ++@item mouse-action ++@kindex mouse-action @r{(button property)} ++This is similar to @code{action}, and when present, will be used ++instead of @code{action} for button invocations resulting from ++mouse-clicks (instead of the user hitting @key{RET}). If not ++present, mouse-clicks use @code{action} instead. ++ ++@item face ++@kindex face @r{(button property)} ++This is an Emacs face controlling how buttons of this type are ++displayed; by default this is the @code{button} face. ++ ++@item mouse-face ++@kindex mouse-face @r{(button property)} ++This is an additional face which controls appearance during ++mouse-overs (merged with the usual button face); by default this is ++the usual Emacs @code{highlight} face. ++ ++@item keymap ++@kindex keymap @r{(button property)} ++The button's keymap, defining bindings active within the button ++region. By default this is the usual button region keymap, stored ++in the variable @code{button-map}, which defines @key{RET} and ++@key{mouse-2} to invoke the button. ++ ++@item type ++@kindex type @r{(button property)} ++The button-type of the button. When creating a button, this is ++usually specified using the @code{:type} keyword argument. ++@xref{Button Types}. ++ ++@item help-echo ++@kindex help-index @r{(button property)} ++A string displayed by the Emacs tool-tip help system; by default, ++@code{"mouse-2, RET: Push this button"}. ++ ++@item follow-link ++@kindex follow-link @r{(button property)} ++The follow-link property, defining how a @key{Mouse-1} click behaves ++on this button, @xref{Clickable Text}. ++ ++@item button ++@kindex button @r{(button property)} ++All buttons have a non-@code{nil} @code{button} property, which may be useful ++in finding regions of text that comprise buttons (which is what the ++standard button functions do). ++@end table ++ ++ There are other properties defined for the regions of text in a ++button, but these are not generally interesting for typical uses. ++ ++@node Button Types ++@subsection Button Types ++@cindex button types ++ ++ Every button has a button @emph{type}, which defines default values ++for the button's properties. Button types are arranged in a ++hierarchy, with specialized types inheriting from more general types, ++so that it's easy to define special-purpose types of buttons for ++specific tasks. ++ ++@defun define-button-type name &rest properties ++Define a `button type' called @var{name} (a symbol). ++The remaining arguments ++form a sequence of @var{property value} pairs, specifying default ++property values for buttons with this type (a button's type may be set ++by giving it a @code{type} property when creating the button, using ++the @code{:type} keyword argument). ++ ++In addition, the keyword argument @code{:supertype} may be used to ++specify a button-type from which @var{name} inherits its default ++property values. Note that this inheritance happens only when ++@var{name} is defined; subsequent changes to a supertype are not ++reflected in its subtypes. ++@end defun ++ ++ Using @code{define-button-type} to define default properties for ++buttons is not necessary---buttons without any specified type use the ++built-in button-type @code{button}---but it is encouraged, since ++doing so usually makes the resulting code clearer and more efficient. ++ ++@node Making Buttons ++@subsection Making Buttons ++@cindex making buttons ++ ++ Buttons are associated with a region of text, using an overlay or ++text properties to hold button-specific information, all of which are ++initialized from the button's type (which defaults to the built-in ++button type @code{button}). Like all Emacs text, the appearance of ++the button is governed by the @code{face} property; by default (via ++the @code{face} property inherited from the @code{button} button-type) ++this is a simple underline, like a typical web-page link. ++ ++ For convenience, there are two sorts of button-creation functions, ++those that add button properties to an existing region of a buffer, ++called @code{make-...button}, and those that also insert the button ++text, called @code{insert-...button}. ++ ++ The button-creation functions all take the @code{&rest} argument ++@var{properties}, which should be a sequence of @var{property value} ++pairs, specifying properties to add to the button; see @ref{Button ++Properties}. In addition, the keyword argument @code{:type} may be ++used to specify a button-type from which to inherit other properties; ++see @ref{Button Types}. Any properties not explicitly specified ++during creation will be inherited from the button's type (if the type ++defines such a property). ++ ++ The following functions add a button using an overlay ++(@pxref{Overlays}) to hold the button properties: ++ ++@defun make-button beg end &rest properties ++This makes a button from @var{beg} to @var{end} in the ++current buffer, and returns it. ++@end defun ++ ++@defun insert-button label &rest properties ++This insert a button with the label @var{label} at point, ++and returns it. ++@end defun ++ ++ The following functions are similar, but use Emacs text properties ++(@pxref{Text Properties}) to hold the button properties, making the ++button actually part of the text instead of being a property of the ++buffer. Buttons using text properties do not create markers into the ++buffer, which is important for speed when you use extremely large ++numbers of buttons. Both functions return the position of the start ++of the new button: ++ ++@defun make-text-button beg end &rest properties ++This makes a button from @var{beg} to @var{end} in the current buffer, using ++text properties. ++@end defun ++ ++@defun insert-text-button label &rest properties ++This inserts a button with the label @var{label} at point, using text ++properties. ++@end defun ++ ++@node Manipulating Buttons ++@subsection Manipulating Buttons ++@cindex manipulating buttons ++ ++These are functions for getting and setting properties of buttons. ++Often these are used by a button's invocation function to determine ++what to do. ++ ++Where a @var{button} parameter is specified, it means an object ++referring to a specific button, either an overlay (for overlay ++buttons), or a buffer-position or marker (for text property buttons). ++Such an object is passed as the first argument to a button's ++invocation function when it is invoked. ++ ++@defun button-start button ++Return the position at which @var{button} starts. ++@end defun ++ ++@defun button-end button ++Return the position at which @var{button} ends. ++@end defun ++ ++@defun button-get button prop ++Get the property of button @var{button} named @var{prop}. ++@end defun ++ ++@defun button-put button prop val ++Set @var{button}'s @var{prop} property to @var{val}. ++@end defun ++ ++@defun button-activate button &optional use-mouse-action ++Call @var{button}'s @code{action} property (i.e., invoke it). If ++@var{use-mouse-action} is non-@code{nil}, try to invoke the button's ++@code{mouse-action} property instead of @code{action}; if the button ++has no @code{mouse-action} property, use @code{action} as normal. ++@end defun ++ ++@defun button-label button ++Return @var{button}'s text label. ++@end defun ++ ++@defun button-type button ++Return @var{button}'s button-type. ++@end defun ++ ++@defun button-has-type-p button type ++Return @code{t} if @var{button} has button-type @var{type}, or one of ++@var{type}'s subtypes. ++@end defun ++ ++@defun button-at pos ++Return the button at position @var{pos} in the current buffer, or @code{nil}. ++@end defun ++ ++@defun button-type-put type prop val ++Set the button-type @var{type}'s @var{prop} property to @var{val}. ++@end defun ++ ++@defun button-type-get type prop ++Get the property of button-type @var{type} named @var{prop}. ++@end defun ++ ++@defun button-type-subtype-p type supertype ++Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. ++@end defun ++ ++@node Button Buffer Commands ++@subsection Button Buffer Commands ++@cindex button buffer commands ++ ++These are commands and functions for locating and operating on ++buttons in an Emacs buffer. ++ ++@code{push-button} is the command that a user uses to actually `push' ++a button, and is bound by default in the button itself to @key{RET} ++and to @key{mouse-2} using a region-specific keymap. Commands ++that are useful outside the buttons itself, such as ++@code{forward-button} and @code{backward-button} are additionally ++available in the keymap stored in @code{button-buffer-map}; a mode ++which uses buttons may want to use @code{button-buffer-map} as a ++parent keymap for its keymap. ++ ++If the button has a non-@code{nil} @code{follow-link} property, and ++@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click ++will also activate the @code{push-button} command. ++@xref{Clickable Text}. ++ ++@deffn Command push-button &optional pos use-mouse-action ++Perform the action specified by a button at location @var{pos}. ++@var{pos} may be either a buffer position or a mouse-event. If ++@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a ++mouse-event (@pxref{Mouse Events}), try to invoke the button's ++@code{mouse-action} property instead of @code{action}; if the button ++has no @code{mouse-action} property, use @code{action} as normal. ++@var{pos} defaults to point, except when @code{push-button} is invoked ++interactively as the result of a mouse-event, in which case, the mouse ++event's position is used. If there's no button at @var{pos}, do ++nothing and return @code{nil}, otherwise return @code{t}. ++@end deffn ++ ++@deffn Command forward-button n &optional wrap display-message ++Move to the @var{n}th next button, or @var{n}th previous button if ++@var{n} is negative. If @var{n} is zero, move to the start of any ++button at point. If @var{wrap} is non-@code{nil}, moving past either ++end of the buffer continues from the other end. If ++@var{display-message} is non-@code{nil}, the button's help-echo string ++is displayed. Any button with a non-@code{nil} @code{skip} property ++is skipped over. Returns the button found. ++@end deffn ++ ++@deffn Command backward-button n &optional wrap display-message ++Move to the @var{n}th previous button, or @var{n}th next button if ++@var{n} is negative. If @var{n} is zero, move to the start of any ++button at point. If @var{wrap} is non-@code{nil}, moving past either ++end of the buffer continues from the other end. If ++@var{display-message} is non-@code{nil}, the button's help-echo string ++is displayed. Any button with a non-@code{nil} @code{skip} property ++is skipped over. Returns the button found. ++@end deffn ++ ++@defun next-button pos &optional count-current ++@defunx previous-button pos &optional count-current ++Return the next button after (for @code{next-button} or before (for ++@code{previous-button}) position @var{pos} in the current buffer. If ++@var{count-current} is non-@code{nil}, count any button at @var{pos} ++in the search, instead of starting at the next button. ++@end defun ++ ++@node Abstract Display ++@section Abstract Display ++@cindex ewoc ++@cindex display, abstract ++@cindex display, arbitrary objects ++@cindex model/view/controller ++@cindex view part, model/view/controller ++ ++ The Ewoc package constructs buffer text that represents a structure ++of Lisp objects, and updates the text to follow changes in that ++structure. This is like the ``view'' component in the ++``model/view/controller'' design paradigm. ++ ++ An @dfn{ewoc} is a structure that organizes information required to ++construct buffer text that represents certain Lisp data. The buffer ++text of the ewoc has three parts, in order: first, fixed @dfn{header} ++text; next, textual descriptions of a series of data elements (Lisp ++objects that you specify); and last, fixed @dfn{footer} text. ++Specifically, an ewoc contains information on: ++ ++@itemize @bullet ++@item ++The buffer which its text is generated in. ++ ++@item ++The text's start position in the buffer. ++ ++@item ++The header and footer strings. ++ ++@item ++A doubly-linked chain of @dfn{nodes}, each of which contains: ++ ++@itemize ++@item ++A @dfn{data element}, a single Lisp object. ++ ++@item ++Links to the preceding and following nodes in the chain. ++@end itemize ++ ++@item ++A @dfn{pretty-printer} function which is responsible for ++inserting the textual representation of a data ++element value into the current buffer. ++@end itemize ++ ++ Typically, you define an ewoc with @code{ewoc-create}, and then pass ++the resulting ewoc structure to other functions in the Ewoc package to ++build nodes within it, and display it in the buffer. Once it is ++displayed in the buffer, other functions determine the correspondance ++between buffer positions and nodes, move point from one node's textual ++representation to another, and so forth. @xref{Abstract Display ++Functions}. ++ ++ A node @dfn{encapsulates} a data element much the way a variable ++holds a value. Normally, encapsulation occurs as a part of adding a ++node to the ewoc. You can retrieve the data element value and place a ++new value in its place, like so: ++ ++@lisp ++(ewoc-data @var{node}) ++@result{} value ++ ++(ewoc-set-data @var{node} @var{new-value}) ++@result{} @var{new-value} ++@end lisp ++ ++@noindent ++You can also use, as the data element value, a Lisp object (list or ++vector) that is a container for the ``real'' value, or an index into ++some other structure. The example (@pxref{Abstract Display Example}) ++uses the latter approach. ++ ++ When the data changes, you will want to update the text in the ++buffer. You can update all nodes by calling @code{ewoc-refresh}, or ++just specific nodes using @code{ewoc-invalidate}, or all nodes ++satisfying a predicate using @code{ewoc-map}. Alternatively, you can ++delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter}, ++and add new nodes in their place. Deleting a node from an ewoc deletes ++its associated textual description from buffer, as well. ++ ++@menu ++* Abstract Display Functions:: Functions in the Ewoc package. ++* Abstract Display Example:: Example of using Ewoc. ++@end menu ++ ++@node Abstract Display Functions ++@subsection Abstract Display Functions ++ ++ In this subsection, @var{ewoc} and @var{node} stand for the ++structures described above (@pxref{Abstract Display}), while ++@var{data} stands for an arbitrary Lisp object used as a data element. ++ ++@defun ewoc-create pretty-printer &optional header footer nosep ++This constructs and returns a new ewoc, with no nodes (and thus no data ++elements). @var{pretty-printer} should be a function that takes one ++argument, a data element of the sort you plan to use in this ewoc, and ++inserts its textual description at point using @code{insert} (and never ++@code{insert-before-markers}, because that would interfere with the ++Ewoc package's internal mechanisms). ++ ++Normally, a newline is automatically inserted after the header, ++the footer and every node's textual description. If @var{nosep} ++is non-@code{nil}, no newline is inserted. This may be useful for ++displaying an entire ewoc on a single line, for example, or for ++making nodes ``invisible'' by arranging for @var{pretty-printer} ++to do nothing for those nodes. ++ ++An ewoc maintains its text in the buffer that is current when ++you create it, so switch to the intended buffer before calling ++@code{ewoc-create}. ++@end defun ++ ++@defun ewoc-buffer ewoc ++This returns the buffer where @var{ewoc} maintains its text. ++@end defun ++ ++@defun ewoc-get-hf ewoc ++This returns a cons cell @code{(@var{header} . @var{footer})} ++made from @var{ewoc}'s header and footer. ++@end defun ++ ++@defun ewoc-set-hf ewoc header footer ++This sets the header and footer of @var{ewoc} to the strings ++@var{header} and @var{footer}, respectively. ++@end defun ++ ++@defun ewoc-enter-first ewoc data ++@defunx ewoc-enter-last ewoc data ++These add a new node encapsulating @var{data}, putting it, respectively, ++at the beginning or end of @var{ewoc}'s chain of nodes. ++@end defun ++ ++@defun ewoc-enter-before ewoc node data ++@defunx ewoc-enter-after ewoc node data ++These add a new node encapsulating @var{data}, adding it to ++@var{ewoc} before or after @var{node}, respectively. ++@end defun ++ ++@defun ewoc-prev ewoc node ++@defunx ewoc-next ewoc node ++These return, respectively, the previous node and the next node of @var{node} ++in @var{ewoc}. ++@end defun ++ ++@defun ewoc-nth ewoc n ++This returns the node in @var{ewoc} found at zero-based index @var{n}. ++A negative @var{n} means count from the end. @code{ewoc-nth} returns ++@code{nil} if @var{n} is out of range. ++@end defun ++ ++@defun ewoc-data node ++This extracts the data encapsulated by @var{node} and returns it. ++@end defun ++ ++@defun ewoc-set-data node data ++This sets the data encapsulated by @var{node} to @var{data}. ++@end defun ++ ++@defun ewoc-locate ewoc &optional pos guess ++This determines the node in @var{ewoc} which contains point (or ++@var{pos} if specified), and returns that node. If @var{ewoc} has no ++nodes, it returns @code{nil}. If @var{pos} is before the first node, ++it returns the first node; if @var{pos} is after the last node, it returns ++the last node. The optional third arg @var{guess} ++should be a node that is likely to be near @var{pos}; this doesn't ++alter the result, but makes the function run faster. ++@end defun ++ ++@defun ewoc-location node ++This returns the start position of @var{node}. ++@end defun ++ ++@defun ewoc-goto-prev ewoc arg ++@defunx ewoc-goto-next ewoc arg ++These move point to the previous or next, respectively, @var{arg}th node ++in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at ++the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} ++moves past the last node, returning @code{nil}. Excepting this special ++case, these functions return the node moved to. ++@end defun ++ ++@defun ewoc-goto-node ewoc node ++This moves point to the start of @var{node} in @var{ewoc}. ++@end defun ++ ++@defun ewoc-refresh ewoc ++This function regenerates the text of @var{ewoc}. It works by ++deleting the text between the header and the footer, i.e., all the ++data elements' representations, and then calling the pretty-printer ++function for each node, one by one, in order. ++@end defun ++ ++@defun ewoc-invalidate ewoc &rest nodes ++This is similar to @code{ewoc-refresh}, except that only @var{nodes} in ++@var{ewoc} are updated instead of the entire set. ++@end defun ++ ++@defun ewoc-delete ewoc &rest nodes ++This deletes each node in @var{nodes} from @var{ewoc}. ++@end defun ++ ++@defun ewoc-filter ewoc predicate &rest args ++This calls @var{predicate} for each data element in @var{ewoc} and ++deletes those nodes for which @var{predicate} returns @code{nil}. ++Any @var{args} are passed to @var{predicate}. ++@end defun ++ ++@defun ewoc-collect ewoc predicate &rest args ++This calls @var{predicate} for each data element in @var{ewoc} ++and returns a list of those elements for which @var{predicate} ++returns non-@code{nil}. The elements in the list are ordered ++as in the buffer. Any @var{args} are passed to @var{predicate}. ++@end defun ++ ++@defun ewoc-map map-function ewoc &rest args ++This calls @var{map-function} for each data element in @var{ewoc} and ++updates those nodes for which @var{map-function} returns non-@code{nil}. ++Any @var{args} are passed to @var{map-function}. ++@end defun ++ ++@node Abstract Display Example ++@subsection Abstract Display Example ++ ++ Here is a simple example using functions of the ewoc package to ++implement a ``color components display,'' an area in a buffer that ++represents a vector of three integers (itself representing a 24-bit RGB ++value) in various ways. ++ ++@example ++(setq colorcomp-ewoc nil ++ colorcomp-data nil ++ colorcomp-mode-map nil ++ colorcomp-labels ["Red" "Green" "Blue"]) ++ ++(defun colorcomp-pp (data) ++ (if data ++ (let ((comp (aref colorcomp-data data))) ++ (insert (aref colorcomp-labels data) "\t: #x" ++ (format "%02X" comp) " " ++ (make-string (ash comp -2) ?#) "\n")) ++ (let ((cstr (format "#%02X%02X%02X" ++ (aref colorcomp-data 0) ++ (aref colorcomp-data 1) ++ (aref colorcomp-data 2))) ++ (samp " (sample text) ")) ++ (insert "Color\t: " ++ (propertize samp 'face `(foreground-color . ,cstr)) ++ (propertize samp 'face `(background-color . ,cstr)) ++ "\n")))) ++ ++(defun colorcomp (color) ++ "Allow fiddling with COLOR in a new buffer. ++The buffer is in Color Components mode." ++ (interactive "sColor (name or #RGB or #RRGGBB): ") ++ (when (string= "" color) ++ (setq color "green")) ++ (unless (color-values color) ++ (error "No such color: %S" color)) ++ (switch-to-buffer ++ (generate-new-buffer (format "originally: %s" color))) ++ (kill-all-local-variables) ++ (setq major-mode 'colorcomp-mode ++ mode-name "Color Components") ++ (use-local-map colorcomp-mode-map) ++ (erase-buffer) ++ (buffer-disable-undo) ++ (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8)) ++ (color-values color)))) ++ (ewoc (ewoc-create 'colorcomp-pp ++ "\nColor Components\n\n" ++ (substitute-command-keys ++ "\n\\@{colorcomp-mode-map@}")))) ++ (set (make-local-variable 'colorcomp-data) data) ++ (set (make-local-variable 'colorcomp-ewoc) ewoc) ++ (ewoc-enter-last ewoc 0) ++ (ewoc-enter-last ewoc 1) ++ (ewoc-enter-last ewoc 2) ++ (ewoc-enter-last ewoc nil))) ++@end example ++ ++@cindex controller part, model/view/controller ++ This example can be extended to be a ``color selection widget'' (in ++other words, the controller part of the ``model/view/controller'' ++design paradigm) by defining commands to modify @code{colorcomp-data} ++and to ``finish'' the selection process, and a keymap to tie it all ++together conveniently. ++ ++@smallexample ++(defun colorcomp-mod (index limit delta) ++ (let ((cur (aref colorcomp-data index))) ++ (unless (= limit cur) ++ (aset colorcomp-data index (+ cur delta))) ++ (ewoc-invalidate ++ colorcomp-ewoc ++ (ewoc-nth colorcomp-ewoc index) ++ (ewoc-nth colorcomp-ewoc -1)))) ++ ++(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1)) ++(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1)) ++(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1)) ++(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1)) ++(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1)) ++(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1)) ++ ++(defun colorcomp-copy-as-kill-and-exit () ++ "Copy the color components into the kill ring and kill the buffer. ++The string is formatted #RRGGBB (hash followed by six hex digits)." ++ (interactive) ++ (kill-new (format "#%02X%02X%02X" ++ (aref colorcomp-data 0) ++ (aref colorcomp-data 1) ++ (aref colorcomp-data 2))) ++ (kill-buffer nil)) ++ ++(setq colorcomp-mode-map ++ (let ((m (make-sparse-keymap))) ++ (suppress-keymap m) ++ (define-key m "i" 'colorcomp-R-less) ++ (define-key m "o" 'colorcomp-R-more) ++ (define-key m "k" 'colorcomp-G-less) ++ (define-key m "l" 'colorcomp-G-more) ++ (define-key m "," 'colorcomp-B-less) ++ (define-key m "." 'colorcomp-B-more) ++ (define-key m " " 'colorcomp-copy-as-kill-and-exit) ++ m)) ++@end smallexample ++ ++Note that we never modify the data in each node, which is fixed when the ++ewoc is created to be either @code{nil} or an index into the vector ++@code{colorcomp-data}, the actual color components. ++ ++@node Blinking ++@section Blinking Parentheses ++@cindex parenthesis matching ++@cindex blinking parentheses ++@cindex balancing parentheses ++ ++ This section describes the mechanism by which Emacs shows a matching ++open parenthesis when the user inserts a close parenthesis. ++ ++@defvar blink-paren-function ++The value of this variable should be a function (of no arguments) to ++be called whenever a character with close parenthesis syntax is inserted. ++The value of @code{blink-paren-function} may be @code{nil}, in which ++case nothing is done. ++@end defvar ++ ++@defopt blink-matching-paren ++If this variable is @code{nil}, then @code{blink-matching-open} does ++nothing. ++@end defopt ++ ++@defopt blink-matching-paren-distance ++This variable specifies the maximum distance to scan for a matching ++parenthesis before giving up. ++@end defopt ++ ++@defopt blink-matching-delay ++This variable specifies the number of seconds for the cursor to remain ++at the matching parenthesis. A fraction of a second often gives ++good results, but the default is 1, which works on all systems. ++@end defopt ++ ++@deffn Command blink-matching-open ++This function is the default value of @code{blink-paren-function}. It ++assumes that point follows a character with close parenthesis syntax and ++moves the cursor momentarily to the matching opening character. If that ++character is not already on the screen, it displays the character's ++context in the echo area. To avoid long delays, this function does not ++search farther than @code{blink-matching-paren-distance} characters. ++ ++Here is an example of calling this function explicitly. ++ ++@smallexample ++@group ++(defun interactive-blink-matching-open () ++@c Do not break this line! -- rms. ++@c The first line of a doc string ++@c must stand alone. ++ "Indicate momentarily the start of sexp before point." ++ (interactive) ++@end group ++@group ++ (let ((blink-matching-paren-distance ++ (buffer-size)) ++ (blink-matching-paren t)) ++ (blink-matching-open))) ++@end group ++@end smallexample ++@end deffn ++ ++@node Usual Display ++@section Usual Display Conventions ++ ++ The usual display conventions define how to display each character ++code. You can override these conventions by setting up a display table ++(@pxref{Display Tables}). Here are the usual display conventions: ++ ++@itemize @bullet ++@item ++Character codes 32 through 126 map to glyph codes 32 through 126. ++Normally this means they display as themselves. ++ ++@item ++Character code 9 is a horizontal tab. It displays as whitespace ++up to a position determined by @code{tab-width}. ++ ++@item ++Character code 10 is a newline. ++ ++@item ++All other codes in the range 0 through 31, and code 127, display in one ++of two ways according to the value of @code{ctl-arrow}. If it is ++non-@code{nil}, these codes map to sequences of two glyphs, where the ++first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can ++specify a glyph to use instead of @samp{^}.) Otherwise, these codes map ++just like the codes in the range 128 to 255. ++ ++On MS-DOS terminals, Emacs arranges by default for the character code ++127 to be mapped to the glyph code 127, which normally displays as an ++empty polygon. This glyph is used to display non-@acronym{ASCII} characters ++that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,, ++emacs, The GNU Emacs Manual}. ++ ++@item ++Character codes 128 through 255 map to sequences of four glyphs, where ++the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are ++digit characters representing the character code in octal. (A display ++table can specify a glyph to use instead of @samp{\}.) ++ ++@item ++Multibyte character codes above 256 are displayed as themselves, or as a ++question mark or empty box if the terminal cannot display that ++character. ++@end itemize ++ ++ The usual display conventions apply even when there is a display ++table, for any character whose entry in the active display table is ++@code{nil}. Thus, when you set up a display table, you need only ++specify the characters for which you want special behavior. ++ ++ These display rules apply to carriage return (character code 13), when ++it appears in the buffer. But that character may not appear in the ++buffer where you expect it, if it was eliminated as part of end-of-line ++conversion (@pxref{Coding System Basics}). ++ ++ These variables affect the way certain characters are displayed on the ++screen. Since they change the number of columns the characters occupy, ++they also affect the indentation functions. These variables also affect ++how the mode line is displayed; if you want to force redisplay of the ++mode line using the new values, call the function ++@code{force-mode-line-update} (@pxref{Mode Line Format}). ++ ++@defopt ctl-arrow ++@cindex control characters in display ++This buffer-local variable controls how control characters are ++displayed. If it is non-@code{nil}, they are displayed as a caret ++followed by the character: @samp{^A}. If it is @code{nil}, they are ++displayed as a backslash followed by three octal digits: @samp{\001}. ++@end defopt ++ ++@c Following may have overfull hbox. ++@defvar default-ctl-arrow ++The value of this variable is the default value for @code{ctl-arrow} in ++buffers that do not override it. @xref{Default Value}. ++@end defvar ++ ++@defopt tab-width ++The value of this buffer-local variable is the spacing between tab ++stops used for displaying tab characters in Emacs buffers. The value ++is in units of columns, and the default is 8. Note that this feature ++is completely independent of the user-settable tab stops used by the ++command @code{tab-to-tab-stop}. @xref{Indent Tabs}. ++@end defopt ++ ++@node Display Tables ++@section Display Tables ++ ++@cindex display table ++You can use the @dfn{display table} feature to control how all possible ++character codes display on the screen. This is useful for displaying ++European languages that have letters not in the @acronym{ASCII} character ++set. ++ ++The display table maps each character code into a sequence of ++@dfn{glyphs}, each glyph being a graphic that takes up one character ++position on the screen. You can also define how to display each glyph ++on your terminal, using the @dfn{glyph table}. ++ ++Display tables affect how the mode line is displayed; if you want to ++force redisplay of the mode line using a new display table, call ++@code{force-mode-line-update} (@pxref{Mode Line Format}). ++ ++@menu ++* Display Table Format:: What a display table consists of. ++* Active Display Table:: How Emacs selects a display table to use. ++* Glyphs:: How to define a glyph, and what glyphs mean. ++@end menu ++ ++@node Display Table Format ++@subsection Display Table Format ++ ++ A display table is actually a char-table (@pxref{Char-Tables}) with ++@code{display-table} as its subtype. ++ ++@defun make-display-table ++This creates and returns a display table. The table initially has ++@code{nil} in all elements. ++@end defun ++ ++ The ordinary elements of the display table are indexed by character ++codes; the element at index @var{c} says how to display the character ++code @var{c}. The value should be @code{nil} or a vector of the ++glyphs to be output (@pxref{Glyphs}). @code{nil} says to display the ++character @var{c} according to the usual display conventions ++(@pxref{Usual Display}). ++ ++ @strong{Warning:} if you use the display table to change the display ++of newline characters, the whole buffer will be displayed as one long ++``line.'' ++ ++ The display table also has six ``extra slots'' which serve special ++purposes. Here is a table of their meanings; @code{nil} in any slot ++means to use the default for that slot, as stated below. ++ ++@table @asis ++@item 0 ++The glyph for the end of a truncated screen line (the default for this ++is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses ++arrows in the fringes to indicate truncation, so the display table has ++no effect. ++ ++@item 1 ++The glyph for the end of a continued line (the default is @samp{\}). ++On graphical terminals, Emacs uses curved arrows in the fringes to ++indicate continuation, so the display table has no effect. ++ ++@item 2 ++The glyph for indicating a character displayed as an octal character ++code (the default is @samp{\}). ++ ++@item 3 ++The glyph for indicating a control character (the default is @samp{^}). ++ ++@item 4 ++A vector of glyphs for indicating the presence of invisible lines (the ++default is @samp{...}). @xref{Selective Display}. ++ ++@item 5 ++The glyph used to draw the border between side-by-side windows (the ++default is @samp{|}). @xref{Splitting Windows}. This takes effect only ++when there are no scroll bars; if scroll bars are supported and in use, ++a scroll bar separates the two windows. ++@end table ++ ++ For example, here is how to construct a display table that mimics the ++effect of setting @code{ctl-arrow} to a non-@code{nil} value: ++ ++@example ++(setq disptab (make-display-table)) ++(let ((i 0)) ++ (while (< i 32) ++ (or (= i ?\t) (= i ?\n) ++ (aset disptab i (vector ?^ (+ i 64)))) ++ (setq i (1+ i))) ++ (aset disptab 127 (vector ?^ ??))) ++@end example ++ ++@defun display-table-slot display-table slot ++This function returns the value of the extra slot @var{slot} of ++@var{display-table}. The argument @var{slot} may be a number from 0 to ++5 inclusive, or a slot name (symbol). Valid symbols are ++@code{truncation}, @code{wrap}, @code{escape}, @code{control}, ++@code{selective-display}, and @code{vertical-border}. ++@end defun ++ ++@defun set-display-table-slot display-table slot value ++This function stores @var{value} in the extra slot @var{slot} of ++@var{display-table}. The argument @var{slot} may be a number from 0 to ++5 inclusive, or a slot name (symbol). Valid symbols are ++@code{truncation}, @code{wrap}, @code{escape}, @code{control}, ++@code{selective-display}, and @code{vertical-border}. ++@end defun ++ ++@defun describe-display-table display-table ++This function displays a description of the display table ++@var{display-table} in a help buffer. ++@end defun ++ ++@deffn Command describe-current-display-table ++This command displays a description of the current display table in a ++help buffer. ++@end deffn ++ ++@node Active Display Table ++@subsection Active Display Table ++@cindex active display table ++ ++ Each window can specify a display table, and so can each buffer. When ++a buffer @var{b} is displayed in window @var{w}, display uses the ++display table for window @var{w} if it has one; otherwise, the display ++table for buffer @var{b} if it has one; otherwise, the standard display ++table if any. The display table chosen is called the @dfn{active} ++display table. ++ ++@defun window-display-table &optional window ++This function returns @var{window}'s display table, or @code{nil} ++if @var{window} does not have an assigned display table. The default ++for @var{window} is the selected window. ++@end defun ++ ++@defun set-window-display-table window table ++This function sets the display table of @var{window} to @var{table}. ++The argument @var{table} should be either a display table or ++@code{nil}. ++@end defun ++ ++@defvar buffer-display-table ++This variable is automatically buffer-local in all buffers; its value in ++a particular buffer specifies the display table for that buffer. If it ++is @code{nil}, that means the buffer does not have an assigned display ++table. ++@end defvar ++ ++@defvar standard-display-table ++This variable's value is the default display table, used whenever a ++window has no display table and neither does the buffer displayed in ++that window. This variable is @code{nil} by default. ++@end defvar ++ ++ If there is no display table to use for a particular window---that is, ++if the window specifies none, its buffer specifies none, and ++@code{standard-display-table} is @code{nil}---then Emacs uses the usual ++display conventions for all character codes in that window. @xref{Usual ++Display}. ++ ++A number of functions for changing the standard display table ++are defined in the library @file{disp-table}. ++ ++@node Glyphs ++@subsection Glyphs ++ ++@cindex glyph ++ A @dfn{glyph} is a generalization of a character; it stands for an ++image that takes up a single character position on the screen. Normally ++glyphs come from vectors in the display table (@pxref{Display Tables}). ++ ++ A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code ++can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A ++simple glyph code is just a way of specifying a character and a face ++to output it in. @xref{Faces}. ++ ++ The following functions are used to manipulate simple glyph codes: ++ ++@defun make-glyph-code char &optional face ++This function returns a simple glyph code representing char @var{char} ++with face @var{face}. ++@end defun ++ ++@defun glyph-char glyph ++This function returns the character of simple glyph code @var{glyph}. ++@end defun ++ ++@defun glyph-face glyph ++This function returns face of simple glyph code @var{glyph}, or ++@code{nil} if @var{glyph} has the default face (face-id 0). ++@xref{Face Functions}. ++@end defun ++ ++ On character terminals, you can set up a @dfn{glyph table} to define ++the meaning of glyph codes (represented as small integers). ++ ++@defvar glyph-table ++The value of this variable is the current glyph table. It should be ++@code{nil} or a vector whose @var{g}th element defines glyph code ++@var{g}. ++ ++If a glyph code is greater than or equal to the length of the glyph ++table, that code is automatically simple. If @code{glyph-table} is ++@code{nil} then all glyph codes are simple. ++ ++The glyph table is used only on character terminals. On graphical ++displays, all glyph codes are simple. ++@end defvar ++ ++ Here are the meaningful types of elements in the glyph table: ++ ++@table @asis ++@item @var{string} ++Send the characters in @var{string} to the terminal to output ++this glyph code. ++ ++@item @var{code} ++Define this glyph code as an alias for glyph code @var{code} created ++by @code{make-glyph-code}. You can use such an alias to define a ++small-numbered glyph code which specifies a character with a face. ++ ++@item @code{nil} ++This glyph code is simple. ++@end table ++ ++@defun create-glyph string ++This function returns a newly-allocated glyph code which is set up to ++display by sending @var{string} to the terminal. ++@end defun ++ ++@node Beeping ++@section Beeping ++@c @cindex beeping "beep" is adjacent ++@cindex bell ++ ++ This section describes how to make Emacs ring the bell (or blink the ++screen) to attract the user's attention. Be conservative about how ++often you do this; frequent bells can become irritating. Also be ++careful not to use just beeping when signaling an error is more ++appropriate. (@xref{Errors}.) ++ ++@defun ding &optional do-not-terminate ++@cindex keyboard macro termination ++This function beeps, or flashes the screen (see @code{visible-bell} below). ++It also terminates any keyboard macro currently executing unless ++@var{do-not-terminate} is non-@code{nil}. ++@end defun ++ ++@defun beep &optional do-not-terminate ++This is a synonym for @code{ding}. ++@end defun ++ ++@defopt visible-bell ++This variable determines whether Emacs should flash the screen to ++represent a bell. Non-@code{nil} means yes, @code{nil} means no. This ++is effective on graphical displays, and on text-only terminals ++provided the terminal's Termcap entry defines the visible bell ++capability (@samp{vb}). ++@end defopt ++ ++@defvar ring-bell-function ++If this is non-@code{nil}, it specifies how Emacs should ``ring the ++bell.'' Its value should be a function of no arguments. If this is ++non-@code{nil}, it takes precedence over the @code{visible-bell} ++variable. ++@end defvar ++ ++@node Window Systems ++@section Window Systems ++ ++ Emacs works with several window systems, most notably the X Window ++System. Both Emacs and X use the term ``window,'' but use it ++differently. An Emacs frame is a single window as far as X is ++concerned; the individual Emacs windows are not known to X at all. ++ ++@defvar window-system ++This frame-local variable tells Lisp programs what window system Emacs is using ++for displaying the frame. The possible values are ++ ++@table @code ++@item x ++@cindex X Window System ++Emacs is displaying the frame using X. ++@item w32 ++Emacs is displaying the frame using native MS-Windows GUI. ++@item ns ++Emacs is displaying the frame using the Nextstep interface (used on ++GNUstep and Mac OS X). ++@item pc ++Emacs is displaying the frame using MS-DOS direct screen writes. ++@item nil ++Emacs is displaying the frame on a character-based terminal. ++@end table ++@end defvar ++ ++@defvar initial-window-system ++This variable holds the value of @code{window-system} used for the ++first frame created by Emacs during startup. (When Emacs is invoked ++with the @option{--daemon} option, it does not create any initial ++frames, so @code{initial-window-system} is @code{nil}. @xref{Initial ++Options, daemon,, emacs, The GNU Emacs Manual}.) ++@end defvar ++ ++@defun window-system &optional frame ++This function returns a symbol whose name tells what window system is ++used for displaying @var{frame} (which defaults to the currently ++selected frame). The list of possible symbols it returns is the same ++one documented for the variable @code{window-system} above. ++@end defun ++ ++@defvar window-setup-hook ++This variable is a normal hook which Emacs runs after handling the ++initialization files. Emacs runs this hook after it has completed ++loading your init file, the default initialization file (if ++any), and the terminal-specific Lisp code, and running the hook ++@code{term-setup-hook}. ++ ++This hook is used for internal purposes: setting up communication with ++the window system, and creating the initial window. Users should not ++interfere with it. ++@end defvar ++ ++@ignore ++ arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6 ++@end ignore +diff --git a/doc/lispref/doclicense.texi b/doc/lispref/doclicense.texi +new file mode 100644 +index 0000000..9adddff +--- /dev/null ++++ b/doc/lispref/doclicense.texi +@@ -0,0 +1,514 @@ ++@c -*-texinfo-*- ++@c The GNU Free Documentation License. ++@node GNU Free Documentation License, GPL, Antinews, Top ++ ++@appendix 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, 2009 Free Software Foundation, Inc. ++@uref{http://fsf.org/} ++ ++Everyone is permitted to copy and distribute verbatim copies ++of this license document, but changing it is not allowed. ++@end display ++ ++@enumerate 0 ++@item ++PREAMBLE ++ ++The purpose of this License is to make a manual, textbook, or other ++functional and useful document @dfn{free} in the sense of freedom: to ++assure everyone the effective freedom to copy and redistribute it, ++with or without modifying it, either commercially or noncommercially. ++Secondarily, this License preserves for the author and publisher a way ++to get credit for their work, while not being considered responsible ++for modifications made by others. ++ ++This License is a kind of ``copyleft'', which means that derivative ++works of the document must themselves be free in the same sense. It ++complements the GNU General Public License, which is a copyleft ++license designed for free software. ++ ++We have designed this License in order to use it for manuals for free ++software, because free software needs free documentation: a free ++program should come with manuals providing the same freedoms that the ++software does. But this License is not limited to software manuals; ++it can be used for any textual work, regardless of subject matter or ++whether it is published as a printed book. We recommend this License ++principally for works whose purpose is instruction or reference. ++ ++@item ++APPLICABILITY AND DEFINITIONS ++ ++This License applies to any manual or other work, in any medium, that ++contains a notice placed by the copyright holder saying it can be ++distributed under the terms of this License. Such a notice grants a ++world-wide, royalty-free license, unlimited in duration, to use that ++work under the conditions stated herein. The ``Document'', below, ++refers to any such manual or work. Any member of the public is a ++licensee, and is addressed as ``you''. You accept the license if you ++copy, modify or distribute the work in a way requiring permission ++under copyright law. ++ ++A ``Modified Version'' of the Document means any work containing the ++Document or a portion of it, either copied verbatim, or with ++modifications and/or translated into another language. ++ ++A ``Secondary Section'' is a named appendix or a front-matter section ++of the Document that deals exclusively with the relationship of the ++publishers or authors of the Document to the Document's overall ++subject (or to related matters) and contains nothing that could fall ++directly within that overall subject. (Thus, if the Document is in ++part a textbook of mathematics, a Secondary Section may not explain ++any mathematics.) The relationship could be a matter of historical ++connection with the subject or with related matters, or of legal, ++commercial, philosophical, ethical or political position regarding ++them. ++ ++The ``Invariant Sections'' are certain Secondary Sections whose titles ++are designated, as being those of Invariant Sections, in the notice ++that says that the Document is released under this License. If a ++section does not fit the above definition of Secondary then it is not ++allowed to be designated as Invariant. The Document may contain zero ++Invariant Sections. If the Document does not identify any Invariant ++Sections then there are none. ++ ++The ``Cover Texts'' are certain short passages of text that are listed, ++as Front-Cover Texts or Back-Cover Texts, in the notice that says that ++the Document is released under this License. A Front-Cover Text may ++be at most 5 words, and a Back-Cover Text may be at most 25 words. ++ ++A ``Transparent'' copy of the Document means a machine-readable copy, ++represented in a format whose specification is available to the ++general public, that is suitable for revising the document ++straightforwardly with generic text editors or (for images composed of ++pixels) generic paint programs or (for drawings) some widely available ++drawing editor, and that is suitable for input to text formatters or ++for automatic translation to a variety of formats suitable for input ++to text formatters. A copy made in an otherwise Transparent file ++format whose markup, or absence of markup, has been arranged to thwart ++or discourage subsequent modification by readers is not Transparent. ++An image format is not Transparent if used for any substantial amount ++of text. A copy that is not ``Transparent'' is called ``Opaque''. ++ ++Examples of suitable formats for Transparent copies include plain ++@sc{ascii} without markup, Texinfo input format, La@TeX{} input ++format, @acronym{SGML} or @acronym{XML} using a publicly available ++@acronym{DTD}, and standard-conforming simple @acronym{HTML}, ++PostScript or @acronym{PDF} designed for human modification. Examples ++of transparent image formats include @acronym{PNG}, @acronym{XCF} and ++@acronym{JPG}. Opaque formats include proprietary formats that can be ++read and edited only by proprietary word processors, @acronym{SGML} or ++@acronym{XML} for which the @acronym{DTD} and/or processing tools are ++not generally available, and the machine-generated @acronym{HTML}, ++PostScript or @acronym{PDF} produced by some word processors for ++output purposes only. ++ ++The ``Title Page'' means, for a printed book, the title page itself, ++plus such following pages as are needed to hold, legibly, the material ++this License requires to appear in the title page. For works in ++formats which do not have any title page as such, ``Title Page'' means ++the text near the most prominent appearance of the work's title, ++preceding the beginning of the body of the text. ++ ++The ``publisher'' means any person or entity that distributes copies ++of the Document to the public. ++ ++A section ``Entitled XYZ'' means a named subunit of the Document whose ++title either is precisely XYZ or contains XYZ in parentheses following ++text that translates XYZ in another language. (Here XYZ stands for a ++specific section name mentioned below, such as ``Acknowledgements'', ++``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' ++of such a section when you modify the Document means that it remains a ++section ``Entitled XYZ'' according to this definition. ++ ++The Document may include Warranty Disclaimers next to the notice which ++states that this License applies to the Document. These Warranty ++Disclaimers are considered to be included by reference in this ++License, but only as regards disclaiming warranties: any other ++implication that these Warranty Disclaimers may have is void and has ++no effect on the meaning of this License. ++ ++@item ++VERBATIM COPYING ++ ++You may copy and distribute the Document in any medium, either ++commercially or noncommercially, provided that this License, the ++copyright notices, and the license notice saying this License applies ++to the Document are reproduced in all copies, and that you add no other ++conditions whatsoever to those of this License. You may not use ++technical measures to obstruct or control the reading or further ++copying of the copies you make or distribute. However, you may accept ++compensation in exchange for copies. If you distribute a large enough ++number of copies you must also follow the conditions in section 3. ++ ++You may also lend copies, under the same conditions stated above, and ++you may publicly display copies. ++ ++@item ++COPYING IN QUANTITY ++ ++If you publish printed copies (or copies in media that commonly have ++printed covers) of the Document, numbering more than 100, and the ++Document's license notice requires Cover Texts, you must enclose the ++copies in covers that carry, clearly and legibly, all these Cover ++Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on ++the back cover. Both covers must also clearly and legibly identify ++you as the publisher of these copies. The front cover must present ++the full title with all words of the title equally prominent and ++visible. You may add other material on the covers in addition. ++Copying with changes limited to the covers, as long as they preserve ++the title of the Document and satisfy these conditions, can be treated ++as verbatim copying in other respects. ++ ++If the required texts for either cover are too voluminous to fit ++legibly, you should put the first ones listed (as many as fit ++reasonably) on the actual cover, and continue the rest onto adjacent ++pages. ++ ++If you publish or distribute Opaque copies of the Document numbering ++more than 100, you must either include a machine-readable Transparent ++copy along with each Opaque copy, or state in or with each Opaque copy ++a computer-network location from which the general network-using ++public has access to download using public-standard network protocols ++a complete Transparent copy of the Document, free of added material. ++If you use the latter option, you must take reasonably prudent steps, ++when you begin distribution of Opaque copies in quantity, to ensure ++that this Transparent copy will remain thus accessible at the stated ++location until at least one year after the last time you distribute an ++Opaque copy (directly or through your agents or retailers) of that ++edition to the public. ++ ++It is requested, but not required, that you contact the authors of the ++Document well before redistributing any large number of copies, to give ++them a chance to provide you with an updated version of the Document. ++ ++@item ++MODIFICATIONS ++ ++You may copy and distribute a Modified Version of the Document under ++the conditions of sections 2 and 3 above, provided that you release ++the Modified Version under precisely this License, with the Modified ++Version filling the role of the Document, thus licensing distribution ++and modification of the Modified Version to whoever possesses a copy ++of it. In addition, you must do these things in the Modified Version: ++ ++@enumerate A ++@item ++Use in the Title Page (and on the covers, if any) a title distinct ++from that of the Document, and from those of previous versions ++(which should, if there were any, be listed in the History section ++of the Document). You may use the same title as a previous version ++if the original publisher of that version gives permission. ++ ++@item ++List on the Title Page, as authors, one or more persons or entities ++responsible for authorship of the modifications in the Modified ++Version, together with at least five of the principal authors of the ++Document (all of its principal authors, if it has fewer than five), ++unless they release you from this requirement. ++ ++@item ++State on the Title page the name of the publisher of the ++Modified Version, as the publisher. ++ ++@item ++Preserve all the copyright notices of the Document. ++ ++@item ++Add an appropriate copyright notice for your modifications ++adjacent to the other copyright notices. ++ ++@item ++Include, immediately after the copyright notices, a license notice ++giving the public permission to use the Modified Version under the ++terms of this License, in the form shown in the Addendum below. ++ ++@item ++Preserve in that license notice the full lists of Invariant Sections ++and required Cover Texts given in the Document's license notice. ++ ++@item ++Include an unaltered copy of this License. ++ ++@item ++Preserve the section Entitled ``History'', Preserve its Title, and add ++to it an item stating at least the title, year, new authors, and ++publisher of the Modified Version as given on the Title Page. If ++there is no section Entitled ``History'' in the Document, create one ++stating the title, year, authors, and publisher of the Document as ++given on its Title Page, then add an item describing the Modified ++Version as stated in the previous sentence. ++ ++@item ++Preserve the network location, if any, given in the Document for ++public access to a Transparent copy of the Document, and likewise ++the network locations given in the Document for previous versions ++it was based on. These may be placed in the ``History'' section. ++You may omit a network location for a work that was published at ++least four years before the Document itself, or if the original ++publisher of the version it refers to gives permission. ++ ++@item ++For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve ++the Title of the section, and preserve in the section all the ++substance and tone of each of the contributor acknowledgements and/or ++dedications given therein. ++ ++@item ++Preserve all the Invariant Sections of the Document, ++unaltered in their text and in their titles. Section numbers ++or the equivalent are not considered part of the section titles. ++ ++@item ++Delete any section Entitled ``Endorsements''. Such a section ++may not be included in the Modified Version. ++ ++@item ++Do not retitle any existing section to be Entitled ``Endorsements'' or ++to conflict in title with any Invariant Section. ++ ++@item ++Preserve any Warranty Disclaimers. ++@end enumerate ++ ++If the Modified Version includes new front-matter sections or ++appendices that qualify as Secondary Sections and contain no material ++copied from the Document, you may at your option designate some or all ++of these sections as invariant. To do this, add their titles to the ++list of Invariant Sections in the Modified Version's license notice. ++These titles must be distinct from any other section titles. ++ ++You may add a section Entitled ``Endorsements'', provided it contains ++nothing but endorsements of your Modified Version by various ++parties---for example, statements of peer review or that the text has ++been approved by an organization as the authoritative definition of a ++standard. ++ ++You may add a passage of up to five words as a Front-Cover Text, and a ++passage of up to 25 words as a Back-Cover Text, to the end of the list ++of Cover Texts in the Modified Version. Only one passage of ++Front-Cover Text and one of Back-Cover Text may be added by (or ++through arrangements made by) any one entity. If the Document already ++includes a cover text for the same cover, previously added by you or ++by arrangement made by the same entity you are acting on behalf of, ++you may not add another; but you may replace the old one, on explicit ++permission from the previous publisher that added the old one. ++ ++The author(s) and publisher(s) of the Document do not by this License ++give permission to use their names for publicity for or to assert or ++imply endorsement of any Modified Version. ++ ++@item ++COMBINING DOCUMENTS ++ ++You may combine the Document with other documents released under this ++License, under the terms defined in section 4 above for modified ++versions, provided that you include in the combination all of the ++Invariant Sections of all of the original documents, unmodified, and ++list them all as Invariant Sections of your combined work in its ++license notice, and that you preserve all their Warranty Disclaimers. ++ ++The combined work need only contain one copy of this License, and ++multiple identical Invariant Sections may be replaced with a single ++copy. If there are multiple Invariant Sections with the same name but ++different contents, make the title of each such section unique by ++adding at the end of it, in parentheses, the name of the original ++author or publisher of that section if known, or else a unique number. ++Make the same adjustment to the section titles in the list of ++Invariant Sections in the license notice of the combined work. ++ ++In the combination, you must combine any sections Entitled ``History'' ++in the various original documents, forming one section Entitled ++``History''; likewise combine any sections Entitled ``Acknowledgements'', ++and any sections Entitled ``Dedications''. You must delete all ++sections Entitled ``Endorsements.'' ++ ++@item ++COLLECTIONS OF DOCUMENTS ++ ++You may make a collection consisting of the Document and other documents ++released under this License, and replace the individual copies of this ++License in the various documents with a single copy that is included in ++the collection, provided that you follow the rules of this License for ++verbatim copying of each of the documents in all other respects. ++ ++You may extract a single document from such a collection, and distribute ++it individually under this License, provided you insert a copy of this ++License into the extracted document, and follow this License in all ++other respects regarding verbatim copying of that document. ++ ++@item ++AGGREGATION WITH INDEPENDENT WORKS ++ ++A compilation of the Document or its derivatives with other separate ++and independent documents or works, in or on a volume of a storage or ++distribution medium, is called an ``aggregate'' if the copyright ++resulting from the compilation is not used to limit the legal rights ++of the compilation's users beyond what the individual works permit. ++When the Document is included in an aggregate, this License does not ++apply to the other works in the aggregate which are not themselves ++derivative works of the Document. ++ ++If the Cover Text requirement of section 3 is applicable to these ++copies of the Document, then if the Document is less than one half of ++the entire aggregate, the Document's Cover Texts may be placed on ++covers that bracket the Document within the aggregate, or the ++electronic equivalent of covers if the Document is in electronic form. ++Otherwise they must appear on printed covers that bracket the whole ++aggregate. ++ ++@item ++TRANSLATION ++ ++Translation is considered a kind of modification, so you may ++distribute translations of the Document under the terms of section 4. ++Replacing Invariant Sections with translations requires special ++permission from their copyright holders, but you may include ++translations of some or all Invariant Sections in addition to the ++original versions of these Invariant Sections. You may include a ++translation of this License, and all the license notices in the ++Document, and any Warranty Disclaimers, provided that you also include ++the original English version of this License and the original versions ++of those notices and disclaimers. In case of a disagreement between ++the translation and the original version of this License or a notice ++or disclaimer, the original version will prevail. ++ ++If a section in the Document is Entitled ``Acknowledgements'', ++``Dedications'', or ``History'', the requirement (section 4) to Preserve ++its Title (section 1) will typically require changing the actual ++title. ++ ++@item ++TERMINATION ++ ++You may not copy, modify, sublicense, or distribute the Document ++except as expressly provided under this License. Any attempt ++otherwise to copy, modify, sublicense, or distribute it is void, and ++will automatically terminate your rights under this License. ++ ++However, if you cease all violation of this License, then your license ++from a particular copyright holder is reinstated (a) provisionally, ++unless and until the copyright holder explicitly and finally ++terminates your license, and (b) permanently, if the copyright holder ++fails to notify you of the violation by some reasonable means prior to ++60 days after the cessation. ++ ++Moreover, your license from a particular copyright holder is ++reinstated permanently if the copyright holder notifies you of the ++violation by some reasonable means, this is the first time you have ++received notice of violation of this License (for any work) from that ++copyright holder, and you cure the violation prior to 30 days after ++your receipt of the notice. ++ ++Termination of your rights under this section does not terminate the ++licenses of parties who have received copies or rights from you under ++this License. If your rights have been terminated and not permanently ++reinstated, receipt of a copy of some or all of the same material does ++not give you any rights to use it. ++ ++@item ++FUTURE REVISIONS OF THIS LICENSE ++ ++The Free Software Foundation may publish new, revised versions ++of the GNU Free Documentation License from time to time. Such new ++versions will be similar in spirit to the present version, but may ++differ in detail to address new problems or concerns. See ++@uref{http://www.gnu.org/copyleft/}. ++ ++Each version of the License is given a distinguishing version number. ++If the Document specifies that a particular numbered version of this ++License ``or any later version'' applies to it, you have the option of ++following the terms and conditions either of that specified version or ++of any later version that has been published (not as a draft) by the ++Free Software Foundation. If the Document does not specify a version ++number of this License, you may choose any version ever published (not ++as a draft) by the Free Software Foundation. If the Document ++specifies that a proxy can decide which future versions of this ++License can be used, that proxy's public statement of acceptance of a ++version permanently authorizes you to choose that version for the ++Document. ++ ++@item ++RELICENSING ++ ++``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any ++World Wide Web server that publishes copyrightable works and also ++provides prominent facilities for anybody to edit those works. A ++public wiki that anybody can edit is an example of such a server. A ++``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the ++site means any set of copyrightable works thus published on the MMC ++site. ++ ++``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 ++license published by Creative Commons Corporation, a not-for-profit ++corporation with a principal place of business in San Francisco, ++California, as well as future copyleft versions of that license ++published by that same organization. ++ ++``Incorporate'' means to publish or republish a Document, in whole or ++in part, as part of another Document. ++ ++An MMC is ``eligible for relicensing'' if it is licensed under this ++License, and if all works that were first published under this License ++somewhere other than this MMC, and subsequently incorporated in whole ++or in part into the MMC, (1) had no cover texts or invariant sections, ++and (2) were thus incorporated prior to November 1, 2008. ++ ++The operator of an MMC Site may republish an MMC contained in the site ++under CC-BY-SA on the same site at any time before August 1, 2009, ++provided the MMC is eligible for relicensing. ++ ++@end enumerate ++ ++@page ++@heading ADDENDUM: How to use this License for your documents ++ ++To use this License in a document you have written, include a copy of ++the License in the document and put the following copyright and ++license notices just after the title page: ++ ++@smallexample ++@group ++ Copyright (C) @var{year} @var{your name}. ++ Permission is granted to copy, distribute and/or modify this document ++ under the terms of the GNU Free Documentation License, Version 1.3 ++ or any later version published by the Free Software Foundation; ++ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover ++ Texts. A copy of the license is included in the section entitled ``GNU ++ Free Documentation License''. ++@end group ++@end smallexample ++ ++If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, ++replace the ``with@dots{}Texts.'' line with this: ++ ++@smallexample ++@group ++ with the Invariant Sections being @var{list their titles}, with ++ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts ++ being @var{list}. ++@end group ++@end smallexample ++ ++If you have Invariant Sections without Cover Texts, or some other ++combination of the three, merge those two alternatives to suit the ++situation. ++ ++If your document contains nontrivial examples of program code, we ++recommend releasing these examples in parallel under your choice of ++free software license, such as the GNU General Public License, ++to permit their use in free software. ++ ++ ++@c Local Variables: ++@c ispell-local-pdict: "ispell-dict" ++@c End: ++ ++@ignore ++ arch-tag: 9014cf6e-f3c4-401d-b8da-4fe52723984c ++@end ignore +diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi +new file mode 100644 +index 0000000..943bab4 +--- /dev/null ++++ b/doc/lispref/edebug.texi +@@ -0,0 +1,1594 @@ ++@comment -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++ ++@c This file can also be used by an independent Edebug User ++@c Manual in which case the Edebug node below should be used ++@c with the following links to the Bugs section and to the top level: ++ ++@c , Bugs and Todo List, Top, Top ++ ++@node Edebug, Syntax Errors, Debugger, Debugging ++@section Edebug ++@cindex Edebug debugging facility ++ ++ Edebug is a source-level debugger for Emacs Lisp programs, with which ++you can: ++ ++@itemize @bullet ++@item ++Step through evaluation, stopping before and after each expression. ++ ++@item ++Set conditional or unconditional breakpoints. ++ ++@item ++Stop when a specified condition is true (the global break event). ++ ++@item ++Trace slow or fast, stopping briefly at each stop point, or ++at each breakpoint. ++ ++@item ++Display expression results and evaluate expressions as if outside of ++Edebug. ++ ++@item ++Automatically re-evaluate a list of expressions and ++display their results each time Edebug updates the display. ++ ++@item ++Output trace information on function calls and returns. ++ ++@item ++Stop when an error occurs. ++ ++@item ++Display a backtrace, omitting Edebug's own frames. ++ ++@item ++Specify argument evaluation for macros and defining forms. ++ ++@item ++Obtain rudimentary coverage testing and frequency counts. ++@end itemize ++ ++The first three sections below should tell you enough about Edebug to ++start using it. ++ ++@menu ++* Using Edebug:: Introduction to use of Edebug. ++* Instrumenting:: You must instrument your code ++ in order to debug it with Edebug. ++* Modes: Edebug Execution Modes. Execution modes, stopping more or less often. ++* Jumping:: Commands to jump to a specified place. ++* Misc: Edebug Misc. Miscellaneous commands. ++* Breaks:: Setting breakpoints to make the program stop. ++* Trapping Errors:: Trapping errors with Edebug. ++* Views: Edebug Views. Views inside and outside of Edebug. ++* Eval: Edebug Eval. Evaluating expressions within Edebug. ++* Eval List:: Expressions whose values are displayed ++ each time you enter Edebug. ++* Printing in Edebug:: Customization of printing. ++* Trace Buffer:: How to produce trace output in a buffer. ++* Coverage Testing:: How to test evaluation coverage. ++* The Outside Context:: Data that Edebug saves and restores. ++* Edebug and Macros:: Specifying how to handle macro calls. ++* Options: Edebug Options. Option variables for customizing Edebug. ++@end menu ++ ++@node Using Edebug ++@subsection Using Edebug ++ ++ To debug a Lisp program with Edebug, you must first @dfn{instrument} ++the Lisp code that you want to debug. A simple way to do this is to ++first move point into the definition of a function or macro and then do ++@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See ++@ref{Instrumenting}, for alternative ways to instrument code. ++ ++ Once a function is instrumented, any call to the function activates ++Edebug. Depending on which Edebug execution mode you have selected, ++activating Edebug may stop execution and let you step through the ++function, or it may update the display and continue execution while ++checking for debugging commands. The default execution mode is step, ++which stops execution. @xref{Edebug Execution Modes}. ++ ++ Within Edebug, you normally view an Emacs buffer showing the source of ++the Lisp code you are debugging. This is referred to as the @dfn{source ++code buffer}, and it is temporarily read-only. ++ ++ An arrow in the left fringe indicates the line where the function is ++executing. Point initially shows where within the line the function is ++executing, but this ceases to be true if you move point yourself. ++ ++ If you instrument the definition of @code{fac} (shown below) and then ++execute @code{(fac 3)}, here is what you would normally see. Point is ++at the open-parenthesis before @code{if}. ++ ++@example ++(defun fac (n) ++=>@point{}(if (< 0 n) ++ (* n (fac (1- n))) ++ 1)) ++@end example ++ ++@cindex stop points ++The places within a function where Edebug can stop execution are called ++@dfn{stop points}. These occur both before and after each subexpression ++that is a list, and also after each variable reference. ++Here we use periods to show the stop points in the function ++@code{fac}: ++ ++@example ++(defun fac (n) ++ .(if .(< 0 n.). ++ .(* n. .(fac .(1- n.).).). ++ 1).) ++@end example ++ ++The special commands of Edebug are available in the source code buffer ++in addition to the commands of Emacs Lisp mode. For example, you can ++type the Edebug command @key{SPC} to execute until the next stop point. ++If you type @key{SPC} once after entry to @code{fac}, here is the ++display you will see: ++ ++@example ++(defun fac (n) ++=>(if @point{}(< 0 n) ++ (* n (fac (1- n))) ++ 1)) ++@end example ++ ++When Edebug stops execution after an expression, it displays the ++expression's value in the echo area. ++ ++Other frequently used commands are @kbd{b} to set a breakpoint at a stop ++point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to ++exit Edebug and return to the top-level command loop. Type @kbd{?} to ++display a list of all Edebug commands. ++ ++@node Instrumenting ++@subsection Instrumenting for Edebug ++ ++ In order to use Edebug to debug Lisp code, you must first ++@dfn{instrument} the code. Instrumenting code inserts additional code ++into it, to invoke Edebug at the proper places. ++ ++@kindex C-M-x ++@findex eval-defun (Edebug) ++ When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a ++prefix argument on a function definition, it instruments the ++definition before evaluating it. (This does not modify the source ++code itself.) If the variable @code{edebug-all-defs} is ++non-@code{nil}, that inverts the meaning of the prefix argument: in ++this case, @kbd{C-M-x} instruments the definition @emph{unless} it has ++a prefix argument. The default value of @code{edebug-all-defs} is ++@code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value ++of the variable @code{edebug-all-defs}. ++ ++@findex eval-region @r{(Edebug)} ++@findex eval-buffer @r{(Edebug)} ++@findex eval-current-buffer @r{(Edebug)} ++ If @code{edebug-all-defs} is non-@code{nil}, then the commands ++@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} ++also instrument any definitions they evaluate. Similarly, ++@code{edebug-all-forms} controls whether @code{eval-region} should ++instrument @emph{any} form, even non-defining forms. This doesn't apply ++to loading or evaluations in the minibuffer. The command @kbd{M-x ++edebug-all-forms} toggles this option. ++ ++@findex edebug-eval-top-level-form ++ Another command, @kbd{M-x edebug-eval-top-level-form}, is available to ++instrument any top-level form regardless of the values of ++@code{edebug-all-defs} and @code{edebug-all-forms}. ++ ++ While Edebug is active, the command @kbd{I} ++(@code{edebug-instrument-callee}) instruments the definition of the ++function or macro called by the list form after point, if is not already ++instrumented. This is possible only if Edebug knows where to find the ++source for that function; for this reason, after loading Edebug, ++@code{eval-region} records the position of every definition it ++evaluates, even if not instrumenting it. See also the @kbd{i} command ++(@pxref{Jumping}), which steps into the call after instrumenting the ++function. ++ ++ Edebug knows how to instrument all the standard special forms, ++@code{interactive} forms with an expression argument, anonymous lambda ++expressions, and other defining forms. However, Edebug cannot determine ++on its own what a user-defined macro will do with the arguments of a ++macro call, so you must provide that information using Edebug ++specifications; for details, @pxref{Edebug and Macros}. ++ ++ When Edebug is about to instrument code for the first time in a ++session, it runs the hook @code{edebug-setup-hook}, then sets it to ++@code{nil}. You can use this to load Edebug specifications ++associated with a package you are using, but only when you use Edebug. ++ ++@findex eval-expression @r{(Edebug)} ++ To remove instrumentation from a definition, simply re-evaluate its ++definition in a way that does not instrument. There are two ways of ++evaluating forms that never instrument them: from a file with ++@code{load}, and from the minibuffer with @code{eval-expression} ++(@kbd{M-:}). ++ ++ If Edebug detects a syntax error while instrumenting, it leaves point ++at the erroneous code and signals an @code{invalid-read-syntax} error. ++ ++ @xref{Edebug Eval}, for other evaluation functions available ++inside of Edebug. ++ ++@node Edebug Execution Modes ++@subsection Edebug Execution Modes ++ ++@cindex Edebug execution modes ++Edebug supports several execution modes for running the program you are ++debugging. We call these alternatives @dfn{Edebug execution modes}; do ++not confuse them with major or minor modes. The current Edebug execution mode ++determines how far Edebug continues execution before stopping---whether ++it stops at each stop point, or continues to the next breakpoint, for ++example---and how much Edebug displays the progress of the evaluation ++before it stops. ++ ++Normally, you specify the Edebug execution mode by typing a command to ++continue the program in a certain mode. Here is a table of these ++commands; all except for @kbd{S} resume execution of the program, at ++least for a certain distance. ++ ++@table @kbd ++@item S ++Stop: don't execute any more of the program, but wait for more ++Edebug commands (@code{edebug-stop}). ++ ++@item @key{SPC} ++Step: stop at the next stop point encountered (@code{edebug-step-mode}). ++ ++@item n ++Next: stop at the next stop point encountered after an expression ++(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in ++@ref{Jumping}. ++ ++@item t ++Trace: pause (normally one second) at each Edebug stop point ++(@code{edebug-trace-mode}). ++ ++@item T ++Rapid trace: update the display at each stop point, but don't actually ++pause (@code{edebug-Trace-fast-mode}). ++ ++@item g ++Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}. ++ ++@item c ++Continue: pause one second at each breakpoint, and then continue ++(@code{edebug-continue-mode}). ++ ++@item C ++Rapid continue: move point to each breakpoint, but don't pause ++(@code{edebug-Continue-fast-mode}). ++ ++@item G ++Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You ++can still stop the program by typing @kbd{S}, or any editing command. ++@end table ++ ++In general, the execution modes earlier in the above list run the ++program more slowly or stop sooner than the modes later in the list. ++ ++While executing or tracing, you can interrupt the execution by typing ++any Edebug command. Edebug stops the program at the next stop point and ++then executes the command you typed. For example, typing @kbd{t} during ++execution switches to trace mode at the next stop point. You can use ++@kbd{S} to stop execution without doing anything else. ++ ++If your function happens to read input, a character you type intending ++to interrupt execution may be read by the function instead. You can ++avoid such unintended results by paying attention to when your program ++wants input. ++ ++@cindex keyboard macros (Edebug) ++Keyboard macros containing the commands in this section do not ++completely work: exiting from Edebug, to resume the program, loses track ++of the keyboard macro. This is not easy to fix. Also, defining or ++executing a keyboard macro outside of Edebug does not affect commands ++inside Edebug. This is usually an advantage. See also the ++@code{edebug-continue-kbd-macro} option in @ref{Edebug Options}. ++ ++When you enter a new Edebug level, the initial execution mode comes ++from the value of the variable @code{edebug-initial-mode} ++(@pxref{Edebug Options}). By default, this specifies step mode. Note ++that you may reenter the same Edebug level several times if, for ++example, an instrumented function is called several times from one ++command. ++ ++@defopt edebug-sit-for-seconds ++This option specifies how many seconds to wait between execution steps ++in trace mode or continue mode. The default is 1 second. ++@end defopt ++ ++@node Jumping ++@subsection Jumping ++ ++ The commands described in this section execute until they reach a ++specified location. All except @kbd{i} make a temporary breakpoint to ++establish the place to stop, then switch to go mode. Any other ++breakpoint reached before the intended stop point will also stop ++execution. @xref{Breakpoints}, for the details on breakpoints. ++ ++ These commands may fail to work as expected in case of nonlocal exit, ++as that can bypass the temporary breakpoint where you expected the ++program to stop. ++ ++@table @kbd ++@item h ++Proceed to the stop point near where point is (@code{edebug-goto-here}). ++ ++@item f ++Run the program for one expression ++(@code{edebug-forward-sexp}). ++ ++@item o ++Run the program until the end of the containing sexp (@code{edebug-step-out}). ++ ++@item i ++Step into the function or macro called by the form after point. ++@end table ++ ++The @kbd{h} command proceeds to the stop point at or after the current ++location of point, using a temporary breakpoint. ++ ++The @kbd{f} command runs the program forward over one expression. More ++precisely, it sets a temporary breakpoint at the position that ++@code{forward-sexp} would reach, then executes in go mode so that ++the program will stop at breakpoints. ++ ++With a prefix argument @var{n}, the temporary breakpoint is placed ++@var{n} sexps beyond point. If the containing list ends before @var{n} ++more elements, then the place to stop is after the containing ++expression. ++ ++You must check that the position @code{forward-sexp} finds is a place ++that the program will really get to. In @code{cond}, for example, ++this may not be true. ++ ++For flexibility, the @kbd{f} command does @code{forward-sexp} starting ++at point, rather than at the stop point. If you want to execute one ++expression @emph{from the current stop point}, first type @kbd{w} ++(@code{edebug-where}) to move point there, and then type @kbd{f}. ++ ++The @kbd{o} command continues ``out of'' an expression. It places a ++temporary breakpoint at the end of the sexp containing point. If the ++containing sexp is a function definition itself, @kbd{o} continues until ++just before the last sexp in the definition. If that is where you are ++now, it returns from the function and then stops. In other words, this ++command does not exit the currently executing function unless you are ++positioned after the last sexp. ++ ++The @kbd{i} command steps into the function or macro called by the list ++form after point, and stops at its first stop point. Note that the form ++need not be the one about to be evaluated. But if the form is a ++function call about to be evaluated, remember to use this command before ++any of the arguments are evaluated, since otherwise it will be too late. ++ ++The @kbd{i} command instruments the function or macro it's supposed to ++step into, if it isn't instrumented already. This is convenient, but keep ++in mind that the function or macro remains instrumented unless you explicitly ++arrange to deinstrument it. ++ ++@node Edebug Misc ++@subsection Miscellaneous Edebug Commands ++ ++ Some miscellaneous Edebug commands are described here. ++ ++@table @kbd ++@item ? ++Display the help message for Edebug (@code{edebug-help}). ++ ++@item C-] ++Abort one level back to the previous command level ++(@code{abort-recursive-edit}). ++ ++@item q ++Return to the top level editor command loop (@code{top-level}). This ++exits all recursive editing levels, including all levels of Edebug ++activity. However, instrumented code protected with ++@code{unwind-protect} or @code{condition-case} forms may resume ++debugging. ++ ++@item Q ++Like @kbd{q}, but don't stop even for protected code ++(@code{edebug-top-level-nonstop}). ++ ++@item r ++Redisplay the most recently known expression result in the echo area ++(@code{edebug-previous-result}). ++ ++@item d ++Display a backtrace, excluding Edebug's own functions for clarity ++(@code{edebug-backtrace}). ++ ++You cannot use debugger commands in the backtrace buffer in Edebug as ++you would in the standard debugger. ++ ++The backtrace buffer is killed automatically when you continue ++execution. ++@end table ++ ++You can invoke commands from Edebug that activate Edebug again ++recursively. Whenever Edebug is active, you can quit to the top level ++with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can ++display a backtrace of all the pending evaluations with @kbd{d}. ++ ++@node Breaks ++@subsection Breaks ++ ++Edebug's step mode stops execution when the next stop point is reached. ++There are three other ways to stop Edebug execution once it has started: ++breakpoints, the global break condition, and source breakpoints. ++ ++@menu ++* Breakpoints:: Breakpoints at stop points. ++* Global Break Condition:: Breaking on an event. ++* Source Breakpoints:: Embedding breakpoints in source code. ++@end menu ++ ++@node Breakpoints ++@subsubsection Edebug Breakpoints ++ ++@cindex breakpoints (Edebug) ++While using Edebug, you can specify @dfn{breakpoints} in the program you ++are testing: these are places where execution should stop. You can set a ++breakpoint at any stop point, as defined in @ref{Using Edebug}. For ++setting and unsetting breakpoints, the stop point that is affected is ++the first one at or after point in the source code buffer. Here are the ++Edebug commands for breakpoints: ++ ++@table @kbd ++@item b ++Set a breakpoint at the stop point at or after point ++(@code{edebug-set-breakpoint}). If you use a prefix argument, the ++breakpoint is temporary---it turns off the first time it stops the ++program. ++ ++@item u ++Unset the breakpoint (if any) at the stop point at or after ++point (@code{edebug-unset-breakpoint}). ++ ++@item x @var{condition} @key{RET} ++Set a conditional breakpoint which stops the program only if ++evaluating @var{condition} produces a non-@code{nil} value ++(@code{edebug-set-conditional-breakpoint}). With a prefix argument, ++the breakpoint is temporary. ++ ++@item B ++Move point to the next breakpoint in the current definition ++(@code{edebug-next-breakpoint}). ++@end table ++ ++While in Edebug, you can set a breakpoint with @kbd{b} and unset one ++with @kbd{u}. First move point to the Edebug stop point of your choice, ++then type @kbd{b} or @kbd{u} to set or unset a breakpoint there. ++Unsetting a breakpoint where none has been set has no effect. ++ ++Re-evaluating or reinstrumenting a definition removes all of its ++previous breakpoints. ++ ++A @dfn{conditional breakpoint} tests a condition each time the program ++gets there. Any errors that occur as a result of evaluating the ++condition are ignored, as if the result were @code{nil}. To set a ++conditional breakpoint, use @kbd{x}, and specify the condition ++expression in the minibuffer. Setting a conditional breakpoint at a ++stop point that has a previously established conditional breakpoint puts ++the previous condition expression in the minibuffer so you can edit it. ++ ++You can make a conditional or unconditional breakpoint ++@dfn{temporary} by using a prefix argument with the command to set the ++breakpoint. When a temporary breakpoint stops the program, it is ++automatically unset. ++ ++Edebug always stops or pauses at a breakpoint, except when the Edebug ++mode is Go-nonstop. In that mode, it ignores breakpoints entirely. ++ ++To find out where your breakpoints are, use the @kbd{B} command, which ++moves point to the next breakpoint following point, within the same ++function, or to the first breakpoint if there are no following ++breakpoints. This command does not continue execution---it just moves ++point in the buffer. ++ ++@node Global Break Condition ++@subsubsection Global Break Condition ++ ++@cindex stopping on events ++@cindex global break condition ++ A @dfn{global break condition} stops execution when a specified ++condition is satisfied, no matter where that may occur. Edebug ++evaluates the global break condition at every stop point; if it ++evaluates to a non-@code{nil} value, then execution stops or pauses ++depending on the execution mode, as if a breakpoint had been hit. If ++evaluating the condition gets an error, execution does not stop. ++ ++@findex edebug-set-global-break-condition ++ The condition expression is stored in ++@code{edebug-global-break-condition}. You can specify a new expression ++using the @kbd{X} command from the source code buffer while Edebug is ++active, or using @kbd{C-x X X} from any buffer at any time, as long as ++Edebug is loaded (@code{edebug-set-global-break-condition}). ++ ++ The global break condition is the simplest way to find where in your ++code some event occurs, but it makes code run much more slowly. So you ++should reset the condition to @code{nil} when not using it. ++ ++@node Source Breakpoints ++@subsubsection Source Breakpoints ++ ++@findex edebug ++@cindex source breakpoints ++ All breakpoints in a definition are forgotten each time you ++reinstrument it. If you wish to make a breakpoint that won't be ++forgotten, you can write a @dfn{source breakpoint}, which is simply a ++call to the function @code{edebug} in your source code. You can, of ++course, make such a call conditional. For example, in the @code{fac} ++function, you can insert the first line as shown below, to stop when the ++argument reaches zero: ++ ++@example ++(defun fac (n) ++ (if (= n 0) (edebug)) ++ (if (< 0 n) ++ (* n (fac (1- n))) ++ 1)) ++@end example ++ ++ When the @code{fac} definition is instrumented and the function is ++called, the call to @code{edebug} acts as a breakpoint. Depending on ++the execution mode, Edebug stops or pauses there. ++ ++ If no instrumented code is being executed when @code{edebug} is called, ++that function calls @code{debug}. ++@c This may not be a good idea anymore. ++ ++@node Trapping Errors ++@subsection Trapping Errors ++ ++ Emacs normally displays an error message when an error is signaled and ++not handled with @code{condition-case}. While Edebug is active and ++executing instrumented code, it normally responds to all unhandled ++errors. You can customize this with the options @code{edebug-on-error} ++and @code{edebug-on-quit}; see @ref{Edebug Options}. ++ ++ When Edebug responds to an error, it shows the last stop point ++encountered before the error. This may be the location of a call to a ++function which was not instrumented, and within which the error actually ++occurred. For an unbound variable error, the last known stop point ++might be quite distant from the offending variable reference. In that ++case, you might want to display a full backtrace (@pxref{Edebug Misc}). ++ ++@c Edebug should be changed for the following: -- dan ++ If you change @code{debug-on-error} or @code{debug-on-quit} while ++Edebug is active, these changes will be forgotten when Edebug becomes ++inactive. Furthermore, during Edebug's recursive edit, these variables ++are bound to the values they had outside of Edebug. ++ ++@node Edebug Views ++@subsection Edebug Views ++ ++ These Edebug commands let you view aspects of the buffer and window ++status as they were before entry to Edebug. The outside window ++configuration is the collection of windows and contents that were in ++effect outside of Edebug. ++ ++@table @kbd ++@item v ++Switch to viewing the outside window configuration ++(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug. ++ ++@item p ++Temporarily display the outside current buffer with point at its ++outside position (@code{edebug-bounce-point}), pausing for one second ++before returning to Edebug. With a prefix argument @var{n}, pause for ++@var{n} seconds instead. ++ ++@item w ++Move point back to the current stop point in the source code buffer ++(@code{edebug-where}). ++ ++If you use this command in a different window displaying the same ++buffer, that window will be used instead to display the current ++definition in the future. ++ ++@item W ++@c Its function is not simply to forget the saved configuration -- dan ++Toggle whether Edebug saves and restores the outside window ++configuration (@code{edebug-toggle-save-windows}). ++ ++With a prefix argument, @code{W} only toggles saving and restoring of ++the selected window. To specify a window that is not displaying the ++source code buffer, you must use @kbd{C-x X W} from the global keymap. ++@end table ++ ++ You can view the outside window configuration with @kbd{v} or just ++bounce to the point in the current buffer with @kbd{p}, even if ++it is not normally displayed. ++ ++ After moving point, you may wish to jump back to the stop point. ++You can do that with @kbd{w} from a source code buffer. You can jump ++back to the stop point in the source code buffer from any buffer using ++@kbd{C-x X w}. ++ ++ Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the ++saved outside window configuration---so that even if you turn saving ++back @emph{on}, the current window configuration remains unchanged when ++you next exit Edebug (by continuing the program). However, the ++automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may ++conflict with the buffers you wish to see unless you have enough windows ++open. ++ ++@node Edebug Eval ++@subsection Evaluation ++ ++ While within Edebug, you can evaluate expressions ``as if'' Edebug ++were not running. Edebug tries to be invisible to the expression's ++evaluation and printing. Evaluation of expressions that cause side ++effects will work as expected, except for changes to data that Edebug ++explicitly saves and restores. @xref{The Outside Context}, for details ++on this process. ++ ++@table @kbd ++@item e @var{exp} @key{RET} ++Evaluate expression @var{exp} in the context outside of Edebug ++(@code{edebug-eval-expression}). That is, Edebug tries to minimize its ++interference with the evaluation. ++ ++@item M-: @var{exp} @key{RET} ++Evaluate expression @var{exp} in the context of Edebug itself ++(@code{eval-expression}). ++ ++@item C-x C-e ++Evaluate the expression before point, in the context outside of Edebug ++(@code{edebug-eval-last-sexp}). ++@end table ++ ++@cindex lexical binding (Edebug) ++ Edebug supports evaluation of expressions containing references to ++lexically bound symbols created by the following constructs in ++@file{cl.el}: @code{lexical-let}, @code{macrolet}, and ++@code{symbol-macrolet}. ++ ++@node Eval List ++@subsection Evaluation List Buffer ++ ++ You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to ++evaluate expressions interactively. You can also set up the ++@dfn{evaluation list} of expressions to be evaluated automatically each ++time Edebug updates the display. ++ ++@table @kbd ++@item E ++Switch to the evaluation list buffer @samp{*edebug*} ++(@code{edebug-visit-eval-list}). ++@end table ++ ++ In the @samp{*edebug*} buffer you can use the commands of Lisp ++Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs ++Manual}) as well as these special commands: ++ ++@table @kbd ++@item C-j ++Evaluate the expression before point, in the outside context, and insert ++the value in the buffer (@code{edebug-eval-print-last-sexp}). ++ ++@item C-x C-e ++Evaluate the expression before point, in the context outside of Edebug ++(@code{edebug-eval-last-sexp}). ++ ++@item C-c C-u ++Build a new evaluation list from the contents of the buffer ++(@code{edebug-update-eval-list}). ++ ++@item C-c C-d ++Delete the evaluation list group that point is in ++(@code{edebug-delete-eval-item}). ++ ++@item C-c C-w ++Switch back to the source code buffer at the current stop point ++(@code{edebug-where}). ++@end table ++ ++ You can evaluate expressions in the evaluation list window with ++@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*}; ++but they are evaluated in the context outside of Edebug. ++ ++ The expressions you enter interactively (and their results) are lost ++when you continue execution; but you can set up an @dfn{evaluation list} ++consisting of expressions to be evaluated each time execution stops. ++ ++@cindex evaluation list group ++ To do this, write one or more @dfn{evaluation list groups} in the ++evaluation list buffer. An evaluation list group consists of one or ++more Lisp expressions. Groups are separated by comment lines. ++ ++ The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the ++evaluation list, scanning the buffer and using the first expression of ++each group. (The idea is that the second expression of the group is the ++value previously computed and displayed.) ++ ++ Each entry to Edebug redisplays the evaluation list by inserting each ++expression in the buffer, followed by its current value. It also ++inserts comment lines so that each expression becomes its own group. ++Thus, if you type @kbd{C-c C-u} again without changing the buffer text, ++the evaluation list is effectively unchanged. ++ ++ If an error occurs during an evaluation from the evaluation list, ++the error message is displayed in a string as if it were the result. ++Therefore, expressions using variables that are not currently valid do ++not interrupt your debugging. ++ ++ Here is an example of what the evaluation list window looks like after ++several expressions have been added to it: ++ ++@smallexample ++(current-buffer) ++# ++;--------------------------------------------------------------- ++(selected-window) ++# ++;--------------------------------------------------------------- ++(point) ++196 ++;--------------------------------------------------------------- ++bad-var ++"Symbol's value as variable is void: bad-var" ++;--------------------------------------------------------------- ++(recursion-depth) ++0 ++;--------------------------------------------------------------- ++this-command ++eval-last-sexp ++;--------------------------------------------------------------- ++@end smallexample ++ ++To delete a group, move point into it and type @kbd{C-c C-d}, or simply ++delete the text for the group and update the evaluation list with ++@kbd{C-c C-u}. To add a new expression to the evaluation list, insert ++the expression at a suitable place, insert a new comment line, then type ++@kbd{C-c C-u}. You need not insert dashes in the comment line---its ++contents don't matter. ++ ++After selecting @samp{*edebug*}, you can return to the source code ++buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when ++you continue execution, and recreated next time it is needed. ++ ++@node Printing in Edebug ++@subsection Printing in Edebug ++ ++@cindex printing (Edebug) ++@cindex printing circular structures ++@pindex cust-print ++ If an expression in your program produces a value containing circular ++list structure, you may get an error when Edebug attempts to print it. ++ ++ One way to cope with circular structure is to set @code{print-length} ++or @code{print-level} to truncate the printing. Edebug does this for ++you; it binds @code{print-length} and @code{print-level} to the values ++of the variables @code{edebug-print-length} and ++@code{edebug-print-level} (so long as they have non-@code{nil} ++values). @xref{Output Variables}. ++ ++@defopt edebug-print-length ++If non-@code{nil}, Edebug binds @code{print-length} to this value while ++printing results. The default value is @code{50}. ++@end defopt ++ ++@defopt edebug-print-level ++If non-@code{nil}, Edebug binds @code{print-level} to this value while ++printing results. The default value is @code{50}. ++@end defopt ++ ++ You can also print circular structures and structures that share ++elements more informatively by binding @code{print-circle} ++to a non-@code{nil} value. ++ ++ Here is an example of code that creates a circular structure: ++ ++@example ++(setq a '(x y)) ++(setcar a a) ++@end example ++ ++@noindent ++Custom printing prints this as @samp{Result: #1=(#1# y)}. The ++@samp{#1=} notation labels the structure that follows it with the label ++@samp{1}, and the @samp{#1#} notation references the previously labeled ++structure. This notation is used for any shared elements of lists or ++vectors. ++ ++@defopt edebug-print-circle ++If non-@code{nil}, Edebug binds @code{print-circle} to this value while ++printing results. The default value is @code{t}. ++@end defopt ++ ++ Other programs can also use custom printing; see @file{cust-print.el} ++for details. ++ ++@node Trace Buffer ++@subsection Trace Buffer ++@cindex trace buffer ++ ++ Edebug can record an execution trace, storing it in a buffer named ++@samp{*edebug-trace*}. This is a log of function calls and returns, ++showing the function names and their arguments and values. To enable ++trace recording, set @code{edebug-trace} to a non-@code{nil} value. ++ ++ Making a trace buffer is not the same thing as using trace execution ++mode (@pxref{Edebug Execution Modes}). ++ ++ When trace recording is enabled, each function entry and exit adds ++lines to the trace buffer. A function entry record consists of ++@samp{::::@{}, followed by the function name and argument values. A ++function exit record consists of @samp{::::@}}, followed by the function ++name and result of the function. ++ ++ The number of @samp{:}s in an entry shows its recursion depth. You ++can use the braces in the trace buffer to find the matching beginning or ++end of function calls. ++ ++@findex edebug-print-trace-before ++@findex edebug-print-trace-after ++ You can customize trace recording for function entry and exit by ++redefining the functions @code{edebug-print-trace-before} and ++@code{edebug-print-trace-after}. ++ ++@defmac edebug-tracing string body@dots{} ++This macro requests additional trace information around the execution ++of the @var{body} forms. The argument @var{string} specifies text ++to put in the trace buffer, after the @samp{@{} or @samp{@}}. All ++the arguments are evaluated, and @code{edebug-tracing} returns the ++value of the last form in @var{body}. ++@end defmac ++ ++@defun edebug-trace format-string &rest format-args ++This function inserts text in the trace buffer. It computes the text ++with @code{(apply 'format @var{format-string} @var{format-args})}. ++It also appends a newline to separate entries. ++@end defun ++ ++ @code{edebug-tracing} and @code{edebug-trace} insert lines in the ++trace buffer whenever they are called, even if Edebug is not active. ++Adding text to the trace buffer also scrolls its window to show the last ++lines inserted. ++ ++@node Coverage Testing ++@subsection Coverage Testing ++ ++@cindex coverage testing (Edebug) ++@cindex frequency counts ++@cindex performance analysis ++ Edebug provides rudimentary coverage testing and display of execution ++frequency. ++ ++ Coverage testing works by comparing the result of each expression with ++the previous result; each form in the program is considered ``covered'' ++if it has returned two different values since you began testing coverage ++in the current Emacs session. Thus, to do coverage testing on your ++program, execute it under various conditions and note whether it behaves ++correctly; Edebug will tell you when you have tried enough different ++conditions that each form has returned two different values. ++ ++ Coverage testing makes execution slower, so it is only done if ++@code{edebug-test-coverage} is non-@code{nil}. Frequency counting is ++performed for all executions of an instrumented function, even if the ++execution mode is Go-nonstop, and regardless of whether coverage testing ++is enabled. ++ ++@kindex C-x X = ++@findex edebug-temp-display-freq-count ++ Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both ++the coverage information and the frequency counts for a definition. ++Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same ++information temporarily, only until you type another key. ++ ++@deffn Command edebug-display-freq-count ++This command displays the frequency count data for each line of the ++current definition. ++ ++It inserts frequency counts as comment lines after each line of code. ++You can undo all insertions with one @code{undo} command. The counts ++appear under the @samp{(} before an expression or the @samp{)} after ++an expression, or on the last character of a variable. To simplify ++the display, a count is not shown if it is equal to the count of an ++earlier expression on the same line. ++ ++The character @samp{=} following the count for an expression says that ++the expression has returned the same value each time it was evaluated. ++In other words, it is not yet ``covered'' for coverage testing purposes. ++ ++To clear the frequency count and coverage data for a definition, ++simply reinstrument it with @code{eval-defun}. ++@end deffn ++ ++For example, after evaluating @code{(fac 5)} with a source ++breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when ++the breakpoint is reached, the frequency data looks like this: ++ ++@example ++(defun fac (n) ++ (if (= n 0) (edebug)) ++;#6 1 = =5 ++ (if (< 0 n) ++;#5 = ++ (* n (fac (1- n))) ++;# 5 0 ++ 1)) ++;# 0 ++@end example ++ ++The comment lines show that @code{fac} was called 6 times. The ++first @code{if} statement returned 5 times with the same result each ++time; the same is true of the condition on the second @code{if}. ++The recursive call of @code{fac} did not return at all. ++ ++ ++@node The Outside Context ++@subsection The Outside Context ++ ++Edebug tries to be transparent to the program you are debugging, but it ++does not succeed completely. Edebug also tries to be transparent when ++you evaluate expressions with @kbd{e} or with the evaluation list ++buffer, by temporarily restoring the outside context. This section ++explains precisely what context Edebug restores, and how Edebug fails to ++be completely transparent. ++ ++@menu ++* Checking Whether to Stop:: When Edebug decides what to do. ++* Edebug Display Update:: When Edebug updates the display. ++* Edebug Recursive Edit:: When Edebug stops execution. ++@end menu ++ ++@node Checking Whether to Stop ++@subsubsection Checking Whether to Stop ++ ++Whenever Edebug is entered, it needs to save and restore certain data ++before even deciding whether to make trace information or stop the ++program. ++ ++@itemize @bullet ++@item ++@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both ++increased to reduce Edebug's impact on the stack. You could, however, ++still run out of stack space when using Edebug. ++ ++@item ++The state of keyboard macro execution is saved and restored. While ++Edebug is active, @code{executing-kbd-macro} is bound to @code{nil} ++unless @code{edebug-continue-kbd-macro} is non-@code{nil}. ++@end itemize ++ ++ ++@node Edebug Display Update ++@subsubsection Edebug Display Update ++ ++@c This paragraph is not filled, because LaLiberte's conversion script ++@c needs an xref to be on just one line. ++When Edebug needs to display something (e.g., in trace mode), it saves ++the current window configuration from ``outside'' Edebug ++(@pxref{Window Configurations}). When you exit Edebug (by continuing ++the program), it restores the previous window configuration. ++ ++Emacs redisplays only when it pauses. Usually, when you continue ++execution, the program re-enters Edebug at a breakpoint or after ++stepping, without pausing or reading input in between. In such cases, ++Emacs never gets a chance to redisplay the ``outside'' configuration. ++Consequently, what you see is the same window configuration as the last ++time Edebug was active, with no interruption. ++ ++Entry to Edebug for displaying something also saves and restores the ++following data (though some of them are deliberately not restored if an ++error or quit signal occurs). ++ ++@itemize @bullet ++@item ++@cindex current buffer point and mark (Edebug) ++Which buffer is current, and the positions of point and the mark in the ++current buffer, are saved and restored. ++ ++@item ++@cindex window configuration (Edebug) ++The outside window configuration is saved and restored if ++@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}). ++ ++The window configuration is not restored on error or quit, but the ++outside selected window @emph{is} reselected even on error or quit in ++case a @code{save-excursion} is active. If the value of ++@code{edebug-save-windows} is a list, only the listed windows are saved ++and restored. ++ ++The window start and horizontal scrolling of the source code buffer are ++not restored, however, so that the display remains coherent within Edebug. ++ ++@item ++The value of point in each displayed buffer is saved and restored if ++@code{edebug-save-displayed-buffer-points} is non-@code{nil}. ++ ++@item ++The variables @code{overlay-arrow-position} and ++@code{overlay-arrow-string} are saved and restored, so you can safely ++invoke Edebug from the recursive edit elsewhere in the same buffer. ++ ++@item ++@code{cursor-in-echo-area} is locally bound to @code{nil} so that ++the cursor shows up in the window. ++@end itemize ++ ++@node Edebug Recursive Edit ++@subsubsection Edebug Recursive Edit ++ ++When Edebug is entered and actually reads commands from the user, it ++saves (and later restores) these additional data: ++ ++@itemize @bullet ++@item ++The current match data. @xref{Match Data}. ++ ++@item ++The variables @code{last-command}, @code{this-command}, ++@code{last-input-event}, @code{last-command-event}, ++@code{last-event-frame}, @code{last-nonmenu-event}, and ++@code{track-mouse}. Commands used within Edebug do not affect these ++variables outside of Edebug. ++ ++Executing commands within Edebug can change the key sequence that ++would be returned by @code{this-command-keys}, and there is no way to ++reset the key sequence from Lisp. ++ ++Edebug cannot save and restore the value of ++@code{unread-command-events}. Entering Edebug while this variable has a ++nontrivial value can interfere with execution of the program you are ++debugging. ++ ++@item ++Complex commands executed while in Edebug are added to the variable ++@code{command-history}. In rare cases this can alter execution. ++ ++@item ++Within Edebug, the recursion depth appears one deeper than the recursion ++depth outside Edebug. This is not true of the automatically updated ++evaluation list window. ++ ++@item ++@code{standard-output} and @code{standard-input} are bound to @code{nil} ++by the @code{recursive-edit}, but Edebug temporarily restores them during ++evaluations. ++ ++@item ++The state of keyboard macro definition is saved and restored. While ++Edebug is active, @code{defining-kbd-macro} is bound to ++@code{edebug-continue-kbd-macro}. ++@end itemize ++ ++@node Edebug and Macros ++@subsection Edebug and Macros ++ ++To make Edebug properly instrument expressions that call macros, some ++extra care is needed. This subsection explains the details. ++ ++@menu ++* Instrumenting Macro Calls:: The basic problem. ++* Specification List:: How to specify complex patterns of evaluation. ++* Backtracking:: What Edebug does when matching fails. ++* Specification Examples:: To help understand specifications. ++@end menu ++ ++@node Instrumenting Macro Calls ++@subsubsection Instrumenting Macro Calls ++ ++ When Edebug instruments an expression that calls a Lisp macro, it needs ++additional information about the macro to do the job properly. This is ++because there is no a-priori way to tell which subexpressions of the ++macro call are forms to be evaluated. (Evaluation may occur explicitly ++in the macro body, or when the resulting expansion is evaluated, or any ++time later.) ++ ++ Therefore, you must define an Edebug specification for each macro ++that Edebug will encounter, to explain the format of calls to that ++macro. To do this, add a @code{debug} declaration to the macro ++definition. Here is a simple example that shows the specification for ++the @code{for} example macro (@pxref{Argument Evaluation}). ++ ++@smallexample ++(defmacro for (var from init to final do &rest body) ++ "Execute a simple \"for\" loop. ++For example, (for i from 1 to 10 do (print i))." ++ (declare (debug (symbolp "from" form "to" form "do" &rest form))) ++ ...) ++@end smallexample ++ ++ The Edebug specification says which parts of a call to the macro are ++forms to be evaluated. For simple macros, the specification ++often looks very similar to the formal argument list of the macro ++definition, but specifications are much more general than macro ++arguments. @xref{Defining Macros}, for more explanation of ++the @code{declare} form. ++ ++ You can also define an edebug specification for a macro separately ++from the macro definition with @code{def-edebug-spec}. Adding ++@code{debug} declarations is preferred, and more convenient, for macro ++definitions in Lisp, but @code{def-edebug-spec} makes it possible to ++define Edebug specifications for special forms implemented in C. ++ ++@deffn Macro def-edebug-spec macro specification ++Specify which expressions of a call to macro @var{macro} are forms to be ++evaluated. @var{specification} should be the edebug specification. ++Neither argument is evaluated. ++ ++The @var{macro} argument can actually be any symbol, not just a macro ++name. ++@end deffn ++ ++Here is a table of the possibilities for @var{specification} and how each ++directs processing of arguments. ++ ++@table @asis ++@item @code{t} ++All arguments are instrumented for evaluation. ++ ++@item @code{0} ++None of the arguments is instrumented. ++ ++@item a symbol ++The symbol must have an Edebug specification, which is used instead. ++This indirection is repeated until another kind of specification is ++found. This allows you to inherit the specification from another macro. ++ ++@item a list ++The elements of the list describe the types of the arguments of a ++calling form. The possible elements of a specification list are ++described in the following sections. ++@end table ++ ++If a macro has no Edebug specification, neither through a @code{debug} ++declaration nor through a @code{def-edebug-spec} call, the variable ++@code{edebug-eval-macro-args} comes into play. ++ ++@defopt edebug-eval-macro-args ++This controls the way Edebug treats macro arguments with no explicit ++Edebug specification. If it is @code{nil} (the default), none of the ++arguments is instrumented for evaluation. Otherwise, all arguments ++are instrumented. ++@end defopt ++ ++@node Specification List ++@subsubsection Specification List ++ ++@cindex Edebug specification list ++A @dfn{specification list} is required for an Edebug specification if ++some arguments of a macro call are evaluated while others are not. Some ++elements in a specification list match one or more arguments, but others ++modify the processing of all following elements. The latter, called ++@dfn{specification keywords}, are symbols beginning with @samp{&} (such ++as @code{&optional}). ++ ++A specification list may contain sublists which match arguments that are ++themselves lists, or it may contain vectors used for grouping. Sublists ++and groups thus subdivide the specification list into a hierarchy of ++levels. Specification keywords apply only to the remainder of the ++sublist or group they are contained in. ++ ++When a specification list involves alternatives or repetition, matching ++it against an actual macro call may require backtracking. For more ++details, @pxref{Backtracking}. ++ ++Edebug specifications provide the power of regular expression matching, ++plus some context-free grammar constructs: the matching of sublists with ++balanced parentheses, recursive processing of forms, and recursion via ++indirect specifications. ++ ++Here's a table of the possible elements of a specification list, with ++their meanings (see @ref{Specification Examples}, for the referenced ++examples): ++ ++@table @code ++@item sexp ++A single unevaluated Lisp object, which is not instrumented. ++@c an "expression" is not necessarily intended for evaluation. ++ ++@item form ++A single evaluated expression, which is instrumented. ++ ++@item place ++@c I can't see that this index entry is useful without any explanation. ++@c @findex edebug-unwrap ++A place to store a value, as in the Common Lisp @code{setf} construct. ++ ++@item body ++Short for @code{&rest form}. See @code{&rest} below. ++ ++@item function-form ++A function form: either a quoted function symbol, a quoted lambda ++expression, or a form (that should evaluate to a function symbol or ++lambda expression). This is useful when an argument that's a lambda ++expression might be quoted with @code{quote} rather than ++@code{function}, since it instruments the body of the lambda expression ++either way. ++ ++@item lambda-expr ++A lambda expression with no quoting. ++ ++@item &optional ++@c @kindex &optional @r{(Edebug)} ++All following elements in the specification list are optional; as soon ++as one does not match, Edebug stops matching at this level. ++ ++To make just a few elements optional followed by non-optional elements, ++use @code{[&optional @var{specs}@dots{}]}. To specify that several ++elements must all match or none, use @code{&optional ++[@var{specs}@dots{}]}. See the @code{defun} example. ++ ++@item &rest ++@c @kindex &rest @r{(Edebug)} ++All following elements in the specification list are repeated zero or ++more times. In the last repetition, however, it is not a problem if the ++expression runs out before matching all of the elements of the ++specification list. ++ ++To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}. ++To specify several elements that must all match on every repetition, use ++@code{&rest [@var{specs}@dots{}]}. ++ ++@item &or ++@c @kindex &or @r{(Edebug)} ++Each of the following elements in the specification list is an ++alternative. One of the alternatives must match, or the @code{&or} ++specification fails. ++ ++Each list element following @code{&or} is a single alternative. To ++group two or more list elements as a single alternative, enclose them in ++@code{[@dots{}]}. ++ ++@item ¬ ++@c @kindex ¬ @r{(Edebug)} ++Each of the following elements is matched as alternatives as if by using ++@code{&or}, but if any of them match, the specification fails. If none ++of them match, nothing is matched, but the @code{¬} specification ++succeeds. ++ ++@item &define ++@c @kindex &define @r{(Edebug)} ++Indicates that the specification is for a defining form. The defining ++form itself is not instrumented (that is, Edebug does not stop before and ++after the defining form), but forms inside it typically will be ++instrumented. The @code{&define} keyword should be the first element in ++a list specification. ++ ++@item nil ++This is successful when there are no more arguments to match at the ++current argument list level; otherwise it fails. See sublist ++specifications and the backquote example. ++ ++@item gate ++@cindex preventing backtracking ++No argument is matched but backtracking through the gate is disabled ++while matching the remainder of the specifications at this level. This ++is primarily used to generate more specific syntax error messages. See ++@ref{Backtracking}, for more details. Also see the @code{let} example. ++ ++@item @var{other-symbol} ++@cindex indirect specifications ++Any other symbol in a specification list may be a predicate or an ++indirect specification. ++ ++If the symbol has an Edebug specification, this @dfn{indirect ++specification} should be either a list specification that is used in ++place of the symbol, or a function that is called to process the ++arguments. The specification may be defined with @code{def-edebug-spec} ++just as for macros. See the @code{defun} example. ++ ++Otherwise, the symbol should be a predicate. The predicate is called ++with the argument and the specification fails if the predicate returns ++@code{nil}, and the argument is not instrumented. ++ ++Some suitable predicates include @code{symbolp}, @code{integerp}, ++@code{stringp}, @code{vectorp}, and @code{atom}. ++ ++@item [@var{elements}@dots{}] ++@cindex [@dots{}] (Edebug) ++A vector of elements groups the elements into a single @dfn{group ++specification}. Its meaning has nothing to do with vectors. ++ ++@item "@var{string}" ++The argument should be a symbol named @var{string}. This specification ++is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name ++of @var{symbol} is the @var{string}, but the string form is preferred. ++ ++@item (vector @var{elements}@dots{}) ++The argument should be a vector whose elements must match the ++@var{elements} in the specification. See the backquote example. ++ ++@item (@var{elements}@dots{}) ++Any other list is a @dfn{sublist specification} and the argument must be ++a list whose elements match the specification @var{elements}. ++ ++@cindex dotted lists (Edebug) ++A sublist specification may be a dotted list and the corresponding list ++argument may then be a dotted list. Alternatively, the last @sc{cdr} of a ++dotted list specification may be another sublist specification (via a ++grouping or an indirect specification, e.g., @code{(spec . [(more ++specs@dots{})])}) whose elements match the non-dotted list arguments. ++This is useful in recursive specifications such as in the backquote ++example. Also see the description of a @code{nil} specification ++above for terminating such recursion. ++ ++Note that a sublist specification written as @code{(specs . nil)} ++is equivalent to @code{(specs)}, and @code{(specs . ++(sublist-elements@dots{}))} is equivalent to @code{(specs ++sublist-elements@dots{})}. ++@end table ++ ++@c Need to document extensions with &symbol and :symbol ++ ++Here is a list of additional specifications that may appear only after ++@code{&define}. See the @code{defun} example. ++ ++@table @code ++@item name ++The argument, a symbol, is the name of the defining form. ++ ++A defining form is not required to have a name field; and it may have ++multiple name fields. ++ ++@item :name ++This construct does not actually match an argument. The element ++following @code{:name} should be a symbol; it is used as an additional ++name component for the definition. You can use this to add a unique, ++static component to the name of the definition. It may be used more ++than once. ++ ++@item arg ++The argument, a symbol, is the name of an argument of the defining form. ++However, lambda-list keywords (symbols starting with @samp{&}) ++are not allowed. ++ ++@item lambda-list ++@cindex lambda-list (Edebug) ++This matches a lambda list---the argument list of a lambda expression. ++ ++@item def-body ++The argument is the body of code in a definition. This is like ++@code{body}, described above, but a definition body must be instrumented ++with a different Edebug call that looks up information associated with ++the definition. Use @code{def-body} for the highest level list of forms ++within the definition. ++ ++@item def-form ++The argument is a single, highest-level form in a definition. This is ++like @code{def-body}, except it is used to match a single form rather than ++a list of forms. As a special case, @code{def-form} also means that ++tracing information is not output when the form is executed. See the ++@code{interactive} example. ++@end table ++ ++@node Backtracking ++@subsubsection Backtracking in Specifications ++ ++@cindex backtracking ++@cindex syntax error (Edebug) ++If a specification fails to match at some point, this does not ++necessarily mean a syntax error will be signaled; instead, ++@dfn{backtracking} will take place until all alternatives have been ++exhausted. Eventually every element of the argument list must be ++matched by some element in the specification, and every required element ++in the specification must match some argument. ++ ++When a syntax error is detected, it might not be reported until much ++later, after higher-level alternatives have been exhausted, and with the ++point positioned further from the real error. But if backtracking is ++disabled when an error occurs, it can be reported immediately. Note ++that backtracking is also reenabled automatically in several situations; ++when a new alternative is established by @code{&optional}, ++@code{&rest}, or @code{&or}, or at the start of processing a sublist, ++group, or indirect specification. The effect of enabling or disabling ++backtracking is limited to the remainder of the level currently being ++processed and lower levels. ++ ++Backtracking is disabled while matching any of the ++form specifications (that is, @code{form}, @code{body}, @code{def-form}, and ++@code{def-body}). These specifications will match any form so any error ++must be in the form itself rather than at a higher level. ++ ++Backtracking is also disabled after successfully matching a quoted ++symbol or string specification, since this usually indicates a ++recognized construct. But if you have a set of alternative constructs that ++all begin with the same symbol, you can usually work around this ++constraint by factoring the symbol out of the alternatives, e.g., ++@code{["foo" &or [first case] [second case] ...]}. ++ ++Most needs are satisfied by these two ways that backtracking is ++automatically disabled, but occasionally it is useful to explicitly ++disable backtracking by using the @code{gate} specification. This is ++useful when you know that no higher alternatives could apply. See the ++example of the @code{let} specification. ++ ++@node Specification Examples ++@subsubsection Specification Examples ++ ++It may be easier to understand Edebug specifications by studying ++the examples provided here. ++ ++A @code{let} special form has a sequence of bindings and a body. Each ++of the bindings is either a symbol or a sublist with a symbol and ++optional expression. In the specification below, notice the @code{gate} ++inside of the sublist to prevent backtracking once a sublist is found. ++ ++@c FIXME? The actual definition in edebug.el does not have a gate. ++@example ++(def-edebug-spec let ++ ((&rest ++ &or symbolp (gate symbolp &optional form)) ++ body)) ++@end example ++ ++Edebug uses the following specifications for @code{defun} and the ++associated argument list and @code{interactive} specifications. It is ++necessary to handle interactive forms specially since an expression ++argument is actually evaluated outside of the function body. (The ++specification for @code{defmacro} is very similar to that for ++@code{defun}, but allows for the @code{declare} statement.) ++ ++@smallexample ++(def-edebug-spec defun ++ (&define name lambda-list ++ [&optional stringp] ; @r{Match the doc string, if present.} ++ [&optional ("interactive" interactive)] ++ def-body)) ++ ++(def-edebug-spec lambda-list ++ (([&rest arg] ++ [&optional ["&optional" arg &rest arg]] ++ &optional ["&rest" arg] ++ ))) ++ ++(def-edebug-spec interactive ++ (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}} ++@end smallexample ++ ++The specification for backquote below illustrates how to match ++dotted lists and use @code{nil} to terminate recursion. It also ++illustrates how components of a vector may be matched. (The actual ++specification defined by Edebug is a little different, and does not ++support dotted lists because doing so causes very deep recursion that ++could fail.) ++ ++@smallexample ++(def-edebug-spec \` (backquote-form)) ; @r{Alias just for clarity.} ++ ++(def-edebug-spec backquote-form ++ (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) ++ (backquote-form . [&or nil backquote-form]) ++ (vector &rest backquote-form) ++ sexp)) ++@end smallexample ++ ++ ++@node Edebug Options ++@subsection Edebug Options ++ ++ These options affect the behavior of Edebug: ++@c Previously defopt'd: ++@c edebug-sit-for-seconds, edebug-print-length, edebug-print-level ++@c edebug-print-circle, edebug-eval-macro-args ++ ++@defopt edebug-setup-hook ++Functions to call before Edebug is used. Each time it is set to a new ++value, Edebug will call those functions once and then ++@code{edebug-setup-hook} is reset to @code{nil}. You could use this to ++load up Edebug specifications associated with a package you are using ++but only when you also use Edebug. ++@xref{Instrumenting}. ++@end defopt ++ ++@defopt edebug-all-defs ++If this is non-@code{nil}, normal evaluation of defining forms such as ++@code{defun} and @code{defmacro} instruments them for Edebug. This ++applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer}, ++and @code{eval-current-buffer}. ++ ++Use the command @kbd{M-x edebug-all-defs} to toggle the value of this ++option. @xref{Instrumenting}. ++@end defopt ++ ++@defopt edebug-all-forms ++If this is non-@code{nil}, the commands @code{eval-defun}, ++@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer} ++instrument all forms, even those that don't define anything. ++This doesn't apply to loading or evaluations in the minibuffer. ++ ++Use the command @kbd{M-x edebug-all-forms} to toggle the value of this ++option. @xref{Instrumenting}. ++@end defopt ++ ++@defopt edebug-save-windows ++If this is non-@code{nil}, Edebug saves and restores the window ++configuration. That takes some time, so if your program does not care ++what happens to the window configurations, it is better to set this ++variable to @code{nil}. ++ ++If the value is a list, only the listed windows are saved and ++restored. ++ ++You can use the @kbd{W} command in Edebug to change this variable ++interactively. @xref{Edebug Display Update}. ++@end defopt ++ ++@defopt edebug-save-displayed-buffer-points ++If this is non-@code{nil}, Edebug saves and restores point in all ++displayed buffers. ++ ++Saving and restoring point in other buffers is necessary if you are ++debugging code that changes the point of a buffer that is displayed in ++a non-selected window. If Edebug or the user then selects the window, ++point in that buffer will move to the window's value of point. ++ ++Saving and restoring point in all buffers is expensive, since it ++requires selecting each window twice, so enable this only if you need ++it. @xref{Edebug Display Update}. ++@end defopt ++ ++@defopt edebug-initial-mode ++If this variable is non-@code{nil}, it specifies the initial execution ++mode for Edebug when it is first activated. Possible values are ++@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace}, ++@code{Trace-fast}, @code{continue}, and @code{Continue-fast}. ++ ++The default value is @code{step}. ++@xref{Edebug Execution Modes}. ++@end defopt ++ ++@defopt edebug-trace ++If this is non-@code{nil}, trace each function entry and exit. ++Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one ++function entry or exit per line, indented by the recursion level. ++ ++Also see @code{edebug-tracing}, in @ref{Trace Buffer}. ++@end defopt ++ ++@defopt edebug-test-coverage ++If non-@code{nil}, Edebug tests coverage of all expressions debugged. ++@xref{Coverage Testing}. ++@end defopt ++ ++@defopt edebug-continue-kbd-macro ++If non-@code{nil}, continue defining or executing any keyboard macro ++that is executing outside of Edebug. Use this with caution since it is not ++debugged. ++@xref{Edebug Execution Modes}. ++@end defopt ++ ++@c FIXME edebug-unwrap-results ++ ++@defopt edebug-on-error ++Edebug binds @code{debug-on-error} to this value, if ++@code{debug-on-error} was previously @code{nil}. @xref{Trapping ++Errors}. ++@end defopt ++ ++@defopt edebug-on-quit ++Edebug binds @code{debug-on-quit} to this value, if ++@code{debug-on-quit} was previously @code{nil}. @xref{Trapping ++Errors}. ++@end defopt ++ ++ If you change the values of @code{edebug-on-error} or ++@code{edebug-on-quit} while Edebug is active, their values won't be used ++until the @emph{next} time Edebug is invoked via a new command. ++@c Not necessarily a deeper command level. ++@c A new command is not precisely true, but that is close enough -- dan ++ ++@defopt edebug-global-break-condition ++If non-@code{nil}, an expression to test for at every stop point. If ++the result is non-@code{nil}, then break. Errors are ignored. ++@xref{Global Break Condition}. ++@end defopt ++ ++@ignore ++ arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd ++@end ignore +diff --git a/doc/lispref/elisp-covers.texi b/doc/lispref/elisp-covers.texi +new file mode 100644 +index 0000000..e7bfa85 +--- /dev/null ++++ b/doc/lispref/elisp-covers.texi +@@ -0,0 +1,257 @@ ++\input texinfo @c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@c ++@comment %**start of header ++@setfilename covers.info ++@settitle GNU Emacs Lisp Reference Manual ++@comment %**end of header ++ ++@titlepage ++@c ================ Volume 1 ================ ++@w{ } ++@sp 2 ++@center @titlefont{The} ++@sp 1 ++@center @titlefont{GNU} ++@sp 1 ++@center @titlefont{Emacs Lisp} ++@sp 1 ++@center @titlefont{Reference} ++@sp 1 ++@center @titlefont{Manual} ++@sp 2 ++@center GNU Emacs Version 19 ++@center for Unix Users ++@center Edition 2.3, June 1994 ++@sp 2 ++@center @titlefont{Volume 1} ++@sp 2 ++@center by Bil Lewis, Dan LaLiberte, ++@center and the GNU Manual Group ++ ++@page ++@c ================ Volume 2 ================ ++@w{ } ++@sp 5 ++@center @titlefont{The} ++@sp 1 ++@center @titlefont{GNU} ++@sp 1 ++@center @titlefont{Emacs Lisp} ++@sp 1 ++@center @titlefont{Reference} ++@sp 1 ++@center @titlefont{Manual} ++@sp 2 ++@center GNU Emacs Version 19 ++@center for Unix Users ++@center Edition 2.3, June 1994 ++@sp 2 ++@center @titlefont{Volume 2} ++@sp 2 ++@center by Bil Lewis, ++@center Dan LaLiberte, and ++@center the GNU Manual Group ++ ++@page ++@c ================ Volume 1 with baseline skip 16pt ================ ++ ++@tex ++\global\baselineskip = 16pt ++@end tex ++ ++16 pts baseline skip: ++ ++@w{ } ++@sp 2 ++@center @titlefont{The} ++@sp 1 ++@center @titlefont{GNU} ++@sp 1 ++@center @titlefont{Emacs Lisp} ++@sp 1 ++@center @titlefont{Reference} ++@sp 1 ++@center @titlefont{Manual} ++@sp 2 ++@center GNU Emacs Version 19 ++@center for Unix Users ++@center Edition 2.3, June 1994 ++@sp 2 ++@center @titlefont{Volume 1} ++@sp 2 ++@center by Bil Lewis, Dan LaLiberte, ++@center and the GNU Manual Group ++ ++@page ++@c ================ Volume 1 with baseline skip 18pt ================ ++ ++@tex ++\global\baselineskip = 18pt ++@end tex ++ ++18 pts baseline skip, with 15pts between sections ++ ++@w{ } ++@sp 2 ++@center @titlefont{The} ++@sp 1 ++@center @titlefont{GNU} ++@sp 1 ++@center @titlefont{Emacs Lisp} ++@sp 1 ++@center @titlefont{Reference} ++@sp 1 ++@center @titlefont{Manual} ++@tex ++\global\baselineskip = 15pt ++@end tex ++ ++@sp 2 ++@center GNU Emacs Version 19 ++@center for Unix Users ++@center Edition 2.3, June 1994 ++@sp 2 ++@center @titlefont{Volume 1} ++@sp 2 ++@center by Bil Lewis, ++@center Dan LaLiberte, and ++@center the GNU Manual Group ++ ++@page ++@c ================ Volume 1 with more baseline skip 24 pts ================ ++ ++@tex ++\global\baselineskip = 24pt ++@end tex ++ ++24 pts baseline skip: ++ ++@w{ } ++@sp 2 ++@center @titlefont{The} ++@sp 1 ++@center @titlefont{GNU} ++@sp 1 ++@center @titlefont{Emacs Lisp} ++@sp 1 ++@center @titlefont{Reference} ++@sp 1 ++@center @titlefont{Manual} ++@sp 2 ++@center GNU Emacs Version 19 ++@center for Unix Users ++@center Edition 2.3, June 1994 ++@sp 2 ++@center @titlefont{Volume 1} ++@sp 2 ++@center by Bil Lewis, Dan LaLiberte, ++@center and the GNU Manual Group ++ ++@page ++@c ================ Volume 2 with more baseline skip 18 pts ================ ++ ++@tex ++\global\baselineskip = 18pt ++@end tex ++ ++18 pts baseline skip: ++ ++@w{ } ++@sp 5 ++@center @titlefont{The} ++@sp 1 ++@center @titlefont{GNU} ++@sp 1 ++@center @titlefont{Emacs Lisp} ++@sp 1 ++@center @titlefont{Reference} ++@sp 1 ++@center @titlefont{Manual} ++@sp 2 ++@center GNU Emacs Version 19 ++@center for Unix Users ++@center Edition 2.3, June 1994 ++@sp 2 ++@center @titlefont{Volume 2} ++@sp 2 ++@center by Bil Lewis, Dan LaLiberte, ++@center and the GNU Manual Group ++ ++@page ++@c ================ Volume 2 with more baseline skip 24 pts ================ ++ ++@tex ++\global\baselineskip = 24pt ++@end tex ++ ++24 pts baseline skip: ++ ++@w{ } ++@sp 5 ++@center @titlefont{The} ++@sp 1 ++@center @titlefont{GNU} ++@sp 1 ++@center @titlefont{Emacs Lisp} ++@sp 1 ++@center @titlefont{Reference} ++@sp 1 ++@center @titlefont{Manual} ++@sp 2 ++@center GNU Emacs Version 19 ++@center for Unix Users ++@center Edition 2.3, June 1994 ++@sp 2 ++@center @titlefont{Volume 2} ++@sp 2 ++@center by Bil Lewis, Dan LaLiberte, ++@center and the GNU Manual Group ++ ++ ++@page ++@c ================ Spine 1 ================ ++ ++@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 1}} ++@sp 4 ++@center GNU Emacs Version 19 ++@center for Unix Users ++@center Edition 2.3, June 1994 ++@sp 4 ++@center by Bil Lewis, Dan LaLiberte, ++@center and the GNU Manual Group ++ ++@sp 4 ++@author The GNU Emacs Lisp Reference Manual --- Vol. 1 ++@sp 3 ++@author FSF ++ ++@author ++ ++@page ++@c ================ Spine 2 ================ ++ ++@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 2}} ++@sp 4 ++@center GNU Emacs Version 19 ++@center for Unix Users ++@center Edition 2.3, June 1994 ++@sp 4 ++@center by Bil Lewis, Dan LaLiberte, ++@center and the GNU Manual Group ++ ++ ++@sp 4 ++@author The GNU Emacs Lisp Reference Manual --- Vol. 2 ++@sp 3 ++@author FSF ++ ++@end titlepage ++@bye ++ ++@ignore ++ arch-tag: 02d65d63-3b64-49bc-a5c0-bfd5eabb6c98 ++@end ignore +diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi +new file mode 100644 +index 0000000..5eaa5ee +--- /dev/null ++++ b/doc/lispref/elisp.texi +@@ -0,0 +1,1529 @@ ++\input texinfo @c -*-texinfo-*- ++@c %**start of header ++@setfilename elisp ++@settitle GNU Emacs Lisp Reference Manual ++@c %**end of header ++ ++@c Version of the manual and of Emacs. ++@c Please remember to update the edition number in README as well. ++@c And also the copies in vol1.texi and vol2.texi. ++@set VERSION 3.0 ++@set EMACSVER 23.1 ++@set DATE July 2009 ++ ++@c in general, keep the following line commented out, unless doing a ++@c copy of this manual that will be published. The manual should go ++@c onto the distribution in the full, 8.5 x 11" size. ++@c set smallbook ++ ++@ifset smallbook ++@smallbook ++@end ifset ++ ++@c per rms and peterb, use 10pt fonts for the main text, mostly to ++@c save on paper cost. ++@c Do this inside @tex for now, so current makeinfo does not complain. ++@tex ++@ifset smallbook ++@fonttextsize 10 ++\global\let\urlcolor=\Black % don't print links in grayscale ++\global\let\linkcolor=\Black ++@end ifset ++\global\hbadness=6666 % don't worry about not-too-underfull boxes ++@end tex ++ ++@c Combine indices. ++@synindex cp fn ++@syncodeindex vr fn ++@syncodeindex ky fn ++@syncodeindex pg fn ++@c We use the "type index" to index new functions and variables. ++@c @syncodeindex tp fn ++ ++@copying ++This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* ++corresponding to Emacs version @value{EMACSVER}. ++ ++Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, ++1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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 the ++Invariant Sections being ``GNU General Public License,'' 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 Emacs ++@direntry ++* Elisp: (elisp). The Emacs Lisp Reference Manual. ++@end direntry ++ ++@titlepage ++@title GNU Emacs Lisp Reference Manual ++@subtitle For Emacs Version @value{EMACSVER} ++@subtitle Revision @value{VERSION}, @value{DATE} ++ ++@author by Bil Lewis, Dan LaLiberte, Richard Stallman ++@author and the GNU Manual Group ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++ ++@sp 2 ++Published by the Free Software Foundation @* ++51 Franklin St, Fifth Floor @* ++Boston, MA 02110-1301 @* ++USA @* ++ISBN 1-882114-74-4 ++ ++@sp 2 ++Cover art by Etienne Suvasa. ++@end titlepage ++ ++ ++@c Print the tables of contents ++@summarycontents ++@contents ++ ++ ++@ifnottex ++@node Top, Introduction, (dir), (dir) ++@top Emacs Lisp ++ ++This Info file contains edition @value{VERSION} of the GNU Emacs Lisp ++Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. ++ ++@insertcopying ++@end ifnottex ++ ++@c Copy any updates to vol1.texi and vol2.texi. ++@menu ++* Introduction:: Introduction and conventions used. ++ ++* Lisp Data Types:: Data types of objects in Emacs Lisp. ++* Numbers:: Numbers and arithmetic functions. ++* Strings and Characters:: Strings, and functions that work on them. ++* Lists:: Lists, cons cells, and related functions. ++* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. ++ Certain functions act on any kind of sequence. ++ The description of vectors is here as well. ++* Hash Tables:: Very fast lookup-tables. ++* Symbols:: Symbols represent names, uniquely. ++ ++* Evaluation:: How Lisp expressions are evaluated. ++* Control Structures:: Conditionals, loops, nonlocal exits. ++* Variables:: Using symbols in programs to stand for values. ++* Functions:: A function is a Lisp program ++ that can be invoked from other functions. ++* Macros:: Macros are a way to extend the Lisp language. ++* Customization:: Writing customization declarations. ++ ++* Loading:: Reading files of Lisp code into Lisp. ++* Byte Compilation:: Compilation makes programs run faster. ++* Advising Functions:: Adding to the definition of a function. ++* Debugging:: Tools and tips for debugging Lisp programs. ++ ++* Read and Print:: Converting Lisp objects to text and back. ++* Minibuffers:: Using the minibuffer to read input. ++* Command Loop:: How the editor command loop works, ++ and how you can call its subroutines. ++* Keymaps:: Defining the bindings from keys to commands. ++* Modes:: Defining major and minor modes. ++* Documentation:: Writing and using documentation strings. ++ ++* Files:: Accessing files. ++* Backups and Auto-Saving:: Controlling how backups and auto-save ++ files are made. ++* Buffers:: Creating and using buffer objects. ++* Windows:: Manipulating windows and displaying buffers. ++* Frames:: Making multiple system-level windows. ++* Positions:: Buffer positions and motion functions. ++* Markers:: Markers represent positions and update ++ automatically when the text is changed. ++ ++* Text:: Examining and changing text in buffers. ++* Non-ASCII Characters:: Non-ASCII text in buffers and strings. ++* Searching and Matching:: Searching buffers for strings or regexps. ++* Syntax Tables:: The syntax table controls word and list parsing. ++* Abbrevs:: How Abbrev mode works, and its data structures. ++ ++* Processes:: Running and communicating with subprocesses. ++* Display:: Features for controlling the screen display. ++* System Interface:: Getting the user id, system type, environment ++ variables, and other such things. ++ ++Appendices ++ ++* Antinews:: Info for users downgrading to Emacs 22. ++* GNU Free Documentation License:: The license for this documentation. ++* GPL:: Conditions for copying and changing GNU Emacs. ++* Tips:: Advice and coding conventions for Emacs Lisp. ++* GNU Emacs Internals:: Building and dumping Emacs; ++ internal data structures. ++* Standard Errors:: List of all error symbols. ++* Standard Buffer-Local Variables:: ++ List of variables buffer-local in all buffers. ++* Standard Keymaps:: List of standard keymaps. ++* Standard Hooks:: List of standard hook variables. ++ ++* Index:: Index including concepts, functions, variables, ++ and other terms. ++ ++@ignore ++* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. ++@end ignore ++ ++@c Do NOT modify the following 3 lines! They must have this form to ++@c be correctly identified by `texinfo-multiple-files-update'. In ++@c particular, the detailed menu header line MUST be identical to the ++@c value of `texinfo-master-menu-header'. See texnfo-upd.el. ++@c Copy any updates to vol1.texi and vol2.texi. ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ --------------------------------- ++ ++Here are other nodes that are inferiors of those already listed, ++mentioned here so you can get to them in one step: ++ ++Introduction ++ ++* Caveats:: Flaws and a request for help. ++* Lisp History:: Emacs Lisp is descended from Maclisp. ++* Conventions:: How the manual is formatted. ++* Version Info:: Which Emacs version is running? ++* Acknowledgements:: The authors, editors, and sponsors of this manual. ++ ++Conventions ++ ++* Some Terms:: Explanation of terms we use in this manual. ++* nil and t:: How the symbols @code{nil} and @code{t} are used. ++* Evaluation Notation:: The format we use for examples of evaluation. ++* Printing Notation:: The format we use when examples print text. ++* Error Messages:: The format we use for examples of errors. ++* Buffer Text Notation:: The format we use for buffer contents in examples. ++* Format of Descriptions:: Notation for describing functions, variables, etc. ++ ++Format of Descriptions ++ ++* A Sample Function Description:: A description of an imaginary ++ function, @code{foo}. ++* A Sample Variable Description:: A description of an imaginary ++ variable, @code{electric-future-map}. ++ ++Lisp Data Types ++ ++* Printed Representation:: How Lisp objects are represented as text. ++* Comments:: Comments and their formatting conventions. ++* Programming Types:: Types found in all Lisp systems. ++* Editing Types:: Types specific to Emacs. ++* Circular Objects:: Read syntax for circular structure. ++* Type Predicates:: Tests related to types. ++* Equality Predicates:: Tests of equality between any two objects. ++ ++Programming Types ++ ++* Integer Type:: Numbers without fractional parts. ++* Floating Point Type:: Numbers with fractional parts and with a large range. ++* Character Type:: The representation of letters, numbers and ++ control characters. ++* Symbol Type:: A multi-use object that refers to a function, ++ variable, or property list, and has a unique identity. ++* Sequence Type:: Both lists and arrays are classified as sequences. ++* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). ++* Array Type:: Arrays include strings and vectors. ++* String Type:: An (efficient) array of characters. ++* Vector Type:: One-dimensional arrays. ++* Char-Table Type:: One-dimensional sparse arrays indexed by characters. ++* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. ++* Hash Table Type:: Super-fast lookup tables. ++* Function Type:: A piece of executable code you can call from elsewhere. ++* Macro Type:: A method of expanding an expression into another ++ expression, more fundamental but less pretty. ++* Primitive Function Type:: A function written in C, callable from Lisp. ++* Byte-Code Type:: A function written in Lisp, then compiled. ++* Autoload Type:: A type used for automatically loading seldom-used ++ functions. ++ ++Character Type ++ ++* Basic Char Syntax:: Syntax for regular characters. ++* General Escape Syntax:: How to specify characters by their codes. ++* Ctl-Char Syntax:: Syntax for control characters. ++* Meta-Char Syntax:: Syntax for meta-characters. ++* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. ++ ++Cons Cell and List Types ++ ++* Box Diagrams:: Drawing pictures of lists. ++* Dotted Pair Notation:: A general syntax for cons cells. ++* Association List Type:: A specially constructed list. ++ ++String Type ++ ++* Syntax for Strings:: How to specify Lisp strings. ++* Non-ASCII in Strings:: International characters in strings. ++* Nonprinting Characters:: Literal unprintable characters in strings. ++* Text Props and Strings:: Strings with text properties. ++ ++Editing Types ++ ++* Buffer Type:: The basic object of editing. ++* Marker Type:: A position in a buffer. ++* Window Type:: Buffers are displayed in windows. ++* Frame Type:: Windows subdivide frames. ++* Terminal Type:: A terminal device displays frames. ++* Window Configuration Type:: Recording the way a frame is subdivided. ++* Frame Configuration Type:: Recording the status of all frames. ++* Process Type:: A subprocess of Emacs running on the underlying OS. ++* Stream Type:: Receive or send characters. ++* Keymap Type:: What function a keystroke invokes. ++* Overlay Type:: How an overlay is represented. ++* Font Type:: Fonts for displaying text. ++ ++Numbers ++ ++* Integer Basics:: Representation and range of integers. ++* Float Basics:: Representation and range of floating point. ++* Predicates on Numbers:: Testing for numbers. ++* Comparison of Numbers:: Equality and inequality predicates. ++* Numeric Conversions:: Converting float to integer and vice versa. ++* Arithmetic Operations:: How to add, subtract, multiply and divide. ++* Rounding Operations:: Explicitly rounding floating point numbers. ++* Bitwise Operations:: Logical and, or, not, shifting. ++* Math Functions:: Trig, exponential and logarithmic functions. ++* Random Numbers:: Obtaining random integers, predictable or not. ++ ++Strings and Characters ++ ++* String Basics:: Basic properties of strings and characters. ++* Predicates for Strings:: Testing whether an object is a string or char. ++* Creating Strings:: Functions to allocate new strings. ++* Modifying Strings:: Altering the contents of an existing string. ++* Text Comparison:: Comparing characters or strings. ++* String Conversion:: Converting to and from characters and strings. ++* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. ++* Case Conversion:: Case conversion functions. ++* Case Tables:: Customizing case conversion. ++ ++Lists ++ ++* Cons Cells:: How lists are made out of cons cells. ++* List-related Predicates:: Is this object a list? Comparing two lists. ++* List Elements:: Extracting the pieces of a list. ++* Building Lists:: Creating list structure. ++* List Variables:: Modifying lists stored in variables. ++* Modifying Lists:: Storing new pieces into an existing list. ++* Sets And Lists:: A list can represent a finite mathematical set. ++* Association Lists:: A list can represent a finite relation or mapping. ++* Rings:: Managing a fixed-size ring of objects. ++ ++Modifying Existing List Structure ++ ++* Setcar:: Replacing an element in a list. ++* Setcdr:: Replacing part of the list backbone. ++ This can be used to remove or add elements. ++* Rearrangement:: Reordering the elements in a list; combining lists. ++ ++Sequences, Arrays, and Vectors ++ ++* Sequence Functions:: Functions that accept any kind of sequence. ++* Arrays:: Characteristics of arrays in Emacs Lisp. ++* Array Functions:: Functions specifically for arrays. ++* Vectors:: Special characteristics of Emacs Lisp vectors. ++* Vector Functions:: Functions specifically for vectors. ++* Char-Tables:: How to work with char-tables. ++* Bool-Vectors:: How to work with bool-vectors. ++ ++Hash Tables ++ ++* Creating Hash:: Functions to create hash tables. ++* Hash Access:: Reading and writing the hash table contents. ++* Defining Hash:: Defining new comparison methods. ++* Other Hash:: Miscellaneous. ++ ++Symbols ++ ++* Symbol Components:: Symbols have names, values, function definitions ++ and property lists. ++* Definitions:: A definition says how a symbol will be used. ++* Creating Symbols:: How symbols are kept unique. ++* Property Lists:: Each symbol has a property list ++ for recording miscellaneous information. ++ ++Property Lists ++ ++* Plists and Alists:: Comparison of the advantages of property ++ lists and association lists. ++* Symbol Plists:: Functions to access symbols' property lists. ++* Other Plists:: Accessing property lists stored elsewhere. ++ ++Evaluation ++ ++* Intro Eval:: Evaluation in the scheme of things. ++* Forms:: How various sorts of objects are evaluated. ++* Quoting:: Avoiding evaluation (to put constants in ++ the program). ++* Eval:: How to invoke the Lisp interpreter explicitly. ++ ++Kinds of Forms ++ ++* Self-Evaluating Forms:: Forms that evaluate to themselves. ++* Symbol Forms:: Symbols evaluate as variables. ++* Classifying Lists:: How to distinguish various sorts of list forms. ++* Function Indirection:: When a symbol appears as the car of a list, ++ we find the real function via the symbol. ++* Function Forms:: Forms that call functions. ++* Macro Forms:: Forms that call macros. ++* Special Forms:: "Special forms" are idiosyncratic primitives, ++ most of them extremely important. ++* Autoloading:: Functions set up to load files ++ containing their real definitions. ++ ++Control Structures ++ ++* Sequencing:: Evaluation in textual order. ++* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. ++* Combining Conditions:: @code{and}, @code{or}, @code{not}. ++* Iteration:: @code{while} loops. ++* Nonlocal Exits:: Jumping out of a sequence. ++ ++Nonlocal Exits ++ ++* Catch and Throw:: Nonlocal exits for the program's own purposes. ++* Examples of Catch:: Showing how such nonlocal exits can be written. ++* Errors:: How errors are signaled and handled. ++* Cleanups:: Arranging to run a cleanup form if an ++ error happens. ++ ++Errors ++ ++* Signaling Errors:: How to report an error. ++* Processing of Errors:: What Emacs does when you report an error. ++* Handling Errors:: How you can trap errors and continue execution. ++* Error Symbols:: How errors are classified for trapping them. ++ ++Variables ++ ++* Global Variables:: Variable values that exist permanently, everywhere. ++* Constant Variables:: Certain "variables" have values that never change. ++* Local Variables:: Variable values that exist only temporarily. ++* Void Variables:: Symbols that lack values. ++* Defining Variables:: A definition says a symbol is used as a variable. ++* Tips for Defining:: Things you should think about when you ++ define a variable. ++* Accessing Variables:: Examining values of variables whose names ++ are known only at run time. ++* Setting Variables:: Storing new values in variables. ++* Variable Scoping:: How Lisp chooses among local and global values. ++* Buffer-Local Variables:: Variable values in effect only in one buffer. ++* File Local Variables:: Handling local variable lists in files. ++* Directory Local Variables:: Local variables common to all files in a ++ directory. ++* Frame-Local Variables:: Frame-local bindings for variables. ++* Variable Aliases:: Variables that are aliases for other variables. ++* Variables with Restricted Values:: Non-constant variables whose value can ++ @emph{not} be an arbitrary Lisp object. ++ ++Scoping Rules for Variable Bindings ++ ++* Scope:: Scope means where in the program a value ++ is visible. Comparison with other languages. ++* Extent:: Extent means how long in time a value exists. ++* Impl of Scope:: Two ways to implement dynamic scoping. ++* Using Scoping:: How to use dynamic scoping carefully and ++ avoid problems. ++ ++Buffer-Local Variables ++ ++* Intro to Buffer-Local:: Introduction and concepts. ++* Creating Buffer-Local:: Creating and destroying buffer-local bindings. ++* Default Value:: The default value is seen in buffers ++ that don't have their own buffer-local values. ++ ++Functions ++ ++* What Is a Function:: Lisp functions vs. primitives; terminology. ++* Lambda Expressions:: How functions are expressed as Lisp objects. ++* Function Names:: A symbol can serve as the name of a function. ++* Defining Functions:: Lisp expressions for defining functions. ++* Calling Functions:: How to use an existing function. ++* Mapping Functions:: Applying a function to each element of a list, etc. ++* Anonymous Functions:: Lambda expressions are functions with no names. ++* Function Cells:: Accessing or setting the function definition ++ of a symbol. ++* Obsolete Functions:: Declaring functions obsolete. ++* Inline Functions:: Defining functions that the compiler ++ will open code. ++* Declaring Functions:: Telling the compiler that a function is defined. ++* Function Safety:: Determining whether a function is safe to call. ++* Related Topics:: Cross-references to specific Lisp primitives ++ that have a special bearing on how ++ functions work. ++ ++Lambda Expressions ++ ++* Lambda Components:: The parts of a lambda expression. ++* Simple Lambda:: A simple example. ++* Argument List:: Details and special features of argument lists. ++* Function Documentation:: How to put documentation in a function. ++ ++Macros ++ ++* Simple Macro:: A basic example. ++* Expansion:: How, when and why macros are expanded. ++* Compiling Macros:: How macros are expanded by the compiler. ++* Defining Macros:: How to write a macro definition. ++* Backquote:: Easier construction of list structure. ++* Problems with Macros:: Don't evaluate the macro arguments too many times. ++ Don't hide the user's variables. ++* Indenting Macros:: Specifying how to indent macro calls. ++ ++Common Problems Using Macros ++ ++* Wrong Time:: Do the work in the expansion, not in the macro. ++* Argument Evaluation:: The expansion should evaluate each macro arg once. ++* Surprising Local Vars:: Local variable bindings in the expansion ++ require special care. ++* Eval During Expansion:: Don't evaluate them; put them in the expansion. ++* Repeated Expansion:: Avoid depending on how many times expansion is done. ++ ++Writing Customization Definitions ++ ++* Common Keywords:: Common keyword arguments for all kinds of ++ customization declarations. ++* Group Definitions:: Writing customization group definitions. ++* Variable Definitions:: Declaring user options. ++* Customization Types:: Specifying the type of a user option. ++ ++Customization Types ++ ++* Simple Types:: Simple customization types: sexp, integer, number, ++ string, file, directory, alist. ++* Composite Types:: Build new types from other types or data. ++* Splicing into Lists:: Splice elements into list with @code{:inline}. ++* Type Keywords:: Keyword-argument pairs in a customization type. ++* Defining New Types:: Give your type a name. ++ ++Loading ++ ++* How Programs Do Loading:: The @code{load} function and others. ++* Load Suffixes:: Details about the suffixes that @code{load} tries. ++* Library Search:: Finding a library to load. ++* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. ++* Autoload:: Setting up a function to autoload. ++* Repeated Loading:: Precautions about loading a file twice. ++* Named Features:: Loading a library if it isn't already loaded. ++* Where Defined:: Finding which file defined a certain symbol. ++* Unloading:: How to "unload" a library that was loaded. ++* Hooks for Loading:: Providing code to be run when ++ particular libraries are loaded. ++ ++Byte Compilation ++ ++* Speed of Byte-Code:: An example of speedup from byte compilation. ++* Compilation Functions:: Byte compilation functions. ++* Docs and Compilation:: Dynamic loading of documentation strings. ++* Dynamic Loading:: Dynamic loading of individual functions. ++* Eval During Compile:: Code to be evaluated when you compile. ++* Compiler Errors:: Handling compiler error messages. ++* Byte-Code Objects:: The data type used for byte-compiled functions. ++* Disassembly:: Disassembling byte-code; how to read byte-code. ++ ++Advising Emacs Lisp Functions ++ ++* Simple Advice:: A simple example to explain the basics of advice. ++* Defining Advice:: Detailed description of @code{defadvice}. ++* Around-Advice:: Wrapping advice around a function's definition. ++* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. ++* Activation of Advice:: Advice doesn't do anything until you activate it. ++* Enabling Advice:: You can enable or disable each piece of advice. ++* Preactivation:: Preactivation is a way of speeding up the ++ loading of compiled advice. ++* Argument Access in Advice:: How advice can access the function's arguments. ++* Advising Primitives:: Accessing arguments when advising a primitive. ++* Combined Definition:: How advice is implemented. ++ ++Debugging Lisp Programs ++ ++* Debugger:: How the Emacs Lisp debugger is implemented. ++* Edebug:: A source-level Emacs Lisp debugger. ++* Syntax Errors:: How to find syntax errors. ++* Test Coverage:: Ensuring you have tested all branches in your code. ++* Compilation Errors:: How to find errors that show up in ++ byte compilation. ++ ++The Lisp Debugger ++ ++* Error Debugging:: Entering the debugger when an error happens. ++* Infinite Loops:: Stopping and debugging a program that doesn't exit. ++* Function Debugging:: Entering it when a certain function is called. ++* Explicit Debug:: Entering it at a certain point in the program. ++* Using Debugger:: What the debugger does; what you see while in it. ++* Debugger Commands:: Commands used while in the debugger. ++* Invoking the Debugger:: How to call the function @code{debug}. ++* Internals of Debugger:: Subroutines of the debugger, and global variables. ++ ++Edebug ++ ++* Using Edebug:: Introduction to use of Edebug. ++* Instrumenting:: You must instrument your code ++ in order to debug it with Edebug. ++* Edebug Execution Modes:: Execution modes, stopping more or less often. ++* Jumping:: Commands to jump to a specified place. ++* Edebug Misc:: Miscellaneous commands. ++* Breaks:: Setting breakpoints to make the program stop. ++* Trapping Errors:: Trapping errors with Edebug. ++* Edebug Views:: Views inside and outside of Edebug. ++* Edebug Eval:: Evaluating expressions within Edebug. ++* Eval List:: Expressions whose values are displayed ++ each time you enter Edebug. ++* Printing in Edebug:: Customization of printing. ++* Trace Buffer:: How to produce trace output in a buffer. ++* Coverage Testing:: How to test evaluation coverage. ++* The Outside Context:: Data that Edebug saves and restores. ++* Edebug and Macros:: Specifying how to handle macro calls. ++* Edebug Options:: Option variables for customizing Edebug. ++ ++Breaks ++ ++* Breakpoints:: Breakpoints at stop points. ++* Global Break Condition:: Breaking on an event. ++* Source Breakpoints:: Embedding breakpoints in source code. ++ ++The Outside Context ++ ++* Checking Whether to Stop::When Edebug decides what to do. ++* Edebug Display Update:: When Edebug updates the display. ++* Edebug Recursive Edit:: When Edebug stops execution. ++ ++Edebug and Macros ++ ++* Instrumenting Macro Calls::The basic problem. ++* Specification List:: How to specify complex patterns of evaluation. ++* Backtracking:: What Edebug does when matching fails. ++* Specification Examples:: To help understand specifications. ++ ++Debugging Invalid Lisp Syntax ++ ++* Excess Open:: How to find a spurious open paren or missing close. ++* Excess Close:: How to find a spurious close paren or missing open. ++ ++Reading and Printing Lisp Objects ++ ++* Streams Intro:: Overview of streams, reading and printing. ++* Input Streams:: Various data types that can be used as ++ input streams. ++* Input Functions:: Functions to read Lisp objects from text. ++* Output Streams:: Various data types that can be used as ++ output streams. ++* Output Functions:: Functions to print Lisp objects as text. ++* Output Variables:: Variables that control what the printing ++ functions do. ++ ++Minibuffers ++ ++* Intro to Minibuffers:: Basic information about minibuffers. ++* Text from Minibuffer:: How to read a straight text string. ++* Object from Minibuffer:: How to read a Lisp object or expression. ++* Minibuffer History:: Recording previous minibuffer inputs ++ so the user can reuse them. ++* Initial Input:: Specifying initial contents for the minibuffer. ++* Completion:: How to invoke and customize completion. ++* Yes-or-No Queries:: Asking a question with a simple answer. ++* Multiple Queries:: Asking a series of similar questions. ++* Reading a Password:: Reading a password from the terminal. ++* Minibuffer Commands:: Commands used as key bindings in minibuffers. ++* Minibuffer Contents:: How such commands access the minibuffer text. ++* Minibuffer Windows:: Operating on the special minibuffer windows. ++* Recursive Mini:: Whether recursive entry to minibuffer is allowed. ++* Minibuffer Misc:: Various customization hooks and variables. ++ ++Completion ++ ++* Basic Completion:: Low-level functions for completing strings. ++ (These are too low level to use the minibuffer.) ++* Minibuffer Completion:: Invoking the minibuffer with completion. ++* Completion Commands:: Minibuffer commands that do completion. ++* High-Level Completion:: Convenient special cases of completion ++ (reading buffer name, file name, etc.). ++* Reading File Names:: Using completion to read file names and ++ shell commands. ++* Completion Styles:: Specifying rules for performing completion. ++* Programmed Completion:: Writing your own completion-function. ++ ++Command Loop ++ ++* Command Overview:: How the command loop reads commands. ++* Defining Commands:: Specifying how a function should read arguments. ++* Interactive Call:: Calling a command, so that it will read arguments. ++* Distinguish Interactive:: Making a command distinguish interactive calls. ++* Command Loop Info:: Variables set by the command loop for you to examine. ++* Adjusting Point:: Adjustment of point after a command. ++* Input Events:: What input looks like when you read it. ++* Reading Input:: How to read input events from the keyboard or mouse. ++* Special Events:: Events processed immediately and individually. ++* Waiting:: Waiting for user input or elapsed time. ++* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. ++* Prefix Command Arguments:: How the commands to set prefix args work. ++* Recursive Editing:: Entering a recursive edit, ++ and why you usually shouldn't. ++* Disabling Commands:: How the command loop handles disabled commands. ++* Command History:: How the command history is set up, and how accessed. ++* Keyboard Macros:: How keyboard macros are implemented. ++ ++Defining Commands ++ ++* Using Interactive:: General rules for @code{interactive}. ++* Interactive Codes:: The standard letter-codes for reading arguments ++ in various ways. ++* Interactive Examples:: Examples of how to read interactive arguments. ++ ++Input Events ++ ++* Keyboard Events:: Ordinary characters--keys with symbols on them. ++* Function Keys:: Function keys--keys with names, not symbols. ++* Mouse Events:: Overview of mouse events. ++* Click Events:: Pushing and releasing a mouse button. ++* Drag Events:: Moving the mouse before releasing the button. ++* Button-Down Events:: A button was pushed and not yet released. ++* Repeat Events:: Double and triple click (or drag, or down). ++* Motion Events:: Just moving the mouse, not pushing a button. ++* Focus Events:: Moving the mouse between frames. ++* Misc Events:: Other events the system can generate. ++* Event Examples:: Examples of the lists for mouse events. ++* Classifying Events:: Finding the modifier keys in an event symbol. ++ Event types. ++* Accessing Mouse:: Functions to extract info from mouse events. ++* Accessing Scroll:: Functions to get info from scroll bar events. ++* Strings of Events:: Special considerations for putting ++ keyboard character events in a string. ++ ++Reading Input ++ ++* Key Sequence Input:: How to read one key sequence. ++* Reading One Event:: How to read just one event. ++* Event Mod:: How Emacs modifies events as they are read. ++* Invoking the Input Method:: How reading an event uses the input method. ++* Quoted Character Input:: Asking the user to specify a character. ++* Event Input Misc:: How to reread or throw away input events. ++ ++Keymaps ++ ++* Key Sequences:: Key sequences as Lisp objects. ++* Keymap Basics:: Basic concepts of keymaps. ++* Format of Keymaps:: What a keymap looks like as a Lisp object. ++* Creating Keymaps:: Functions to create and copy keymaps. ++* Inheritance and Keymaps:: How one keymap can inherit the bindings ++ of another keymap. ++* Prefix Keys:: Defining a key with a keymap as its definition. ++* Active Keymaps:: How Emacs searches the active keymaps ++ for a key binding. ++* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. ++* Controlling Active Maps:: Each buffer has a local keymap ++ to override the standard (global) bindings. ++ A minor mode can also override them. ++* Key Lookup:: Finding a key's binding in one keymap. ++* Functions for Key Lookup:: How to request key lookup. ++* Changing Key Bindings:: Redefining a key in a keymap. ++* Remapping Commands:: A keymap can translate one command to another. ++* Translation Keymaps:: Keymaps for translating sequences of events. ++* Key Binding Commands:: Interactive interfaces for redefining keys. ++* Scanning Keymaps:: Looking through all keymaps, for printing help. ++* Menu Keymaps:: Defining a menu as a keymap. ++ ++Menu Keymaps ++ ++* Defining Menus:: How to make a keymap that defines a menu. ++* Mouse Menus:: How users actuate the menu with the mouse. ++* Keyboard Menus:: How users actuate the menu with the keyboard. ++* Menu Example:: Making a simple menu. ++* Menu Bar:: How to customize the menu bar. ++* Tool Bar:: A tool bar is a row of images. ++* Modifying Menus:: How to add new items to a menu. ++ ++Defining Menus ++ ++* Simple Menu Items:: A simple kind of menu key binding, ++ limited in capabilities. ++* Extended Menu Items:: More powerful menu item definitions ++ let you specify keywords to enable ++ various features. ++* Menu Separators:: Drawing a horizontal line through a menu. ++* Alias Menu Items:: Using command aliases in menu items. ++ ++Major and Minor Modes ++ ++* Hooks:: How to use hooks; how to write code that provides hooks. ++* Major Modes:: Defining major modes. ++* Minor Modes:: Defining minor modes. ++* Mode Line Format:: Customizing the text that appears in the mode line. ++* Imenu:: How a mode can provide a menu ++ of definitions in the buffer. ++* Font Lock Mode:: How modes can highlight text according to syntax. ++* Desktop Save Mode:: How modes can have buffer state saved between ++ Emacs sessions. ++ ++Hooks ++ ++* Running Hooks:: How to run a hook. ++* Setting Hooks:: How to put functions on a hook, or remove them. ++ ++Major Modes ++ ++* Major Mode Basics:: ++* Major Mode Conventions:: Coding conventions for keymaps, etc. ++* Auto Major Mode:: How Emacs chooses the major mode automatically. ++* Mode Help:: Finding out how to use a mode. ++* Derived Modes:: Defining a new major mode based on another major ++ mode. ++* Generic Modes:: Defining a simple major mode that supports ++ comment syntax and Font Lock mode. ++* Mode Hooks:: Hooks run at the end of major mode functions. ++* Example Major Modes:: Text mode and Lisp modes. ++ ++Minor Modes ++ ++* Minor Mode Conventions:: Tips for writing a minor mode. ++* Keymaps and Minor Modes:: How a minor mode can have its own keymap. ++* Defining Minor Modes:: A convenient facility for defining minor modes. ++ ++Mode Line Format ++ ++* Mode Line Basics:: Basic ideas of mode line control. ++* Mode Line Data:: The data structure that controls the mode line. ++* Mode Line Top:: The top level variable, mode-line-format. ++* Mode Line Variables:: Variables used in that data structure. ++* %-Constructs:: Putting information into a mode line. ++* Properties in Mode:: Using text properties in the mode line. ++* Header Lines:: Like a mode line, but at the top. ++* Emulating Mode Line:: Formatting text as the mode line would. ++ ++Font Lock Mode ++ ++* Font Lock Basics:: Overview of customizing Font Lock. ++* Search-based Fontification:: Fontification based on regexps. ++* Customizing Keywords:: Customizing search-based fontification. ++* Other Font Lock Variables:: Additional customization facilities. ++* Levels of Font Lock:: Each mode can define alternative levels ++ so that the user can select more or less. ++* Precalculated Fontification:: How Lisp programs that produce the buffer ++ contents can also specify how to fontify it. ++* Faces for Font Lock:: Special faces specifically for Font Lock. ++* Syntactic Font Lock:: Fontification based on syntax tables. ++* Setting Syntax Properties:: Defining character syntax based on context ++ using the Font Lock mechanism. ++* Multiline Font Lock:: How to coerce Font Lock into properly ++ highlighting multiline constructs. ++ ++Multiline Font Lock Constructs ++ ++* Font Lock Multiline:: Marking multiline chunks with a text property. ++* Region to Fontify:: Controlling which region gets refontified ++ after a buffer change. ++ ++Documentation ++ ++* Documentation Basics:: Good style for doc strings. ++ Where to put them. How Emacs stores them. ++* Accessing Documentation:: How Lisp programs can access doc strings. ++* Keys in Documentation:: Substituting current key bindings. ++* Describing Characters:: Making printable descriptions of ++ non-printing characters and key sequences. ++* Help Functions:: Subroutines used by Emacs help facilities. ++ ++Files ++ ++* Visiting Files:: Reading files into Emacs buffers for editing. ++* Saving Buffers:: Writing changed buffers back into files. ++* Reading from Files:: Reading files into buffers without visiting. ++* Writing to Files:: Writing new files from parts of buffers. ++* File Locks:: Locking and unlocking files, to prevent ++ simultaneous editing by two people. ++* Information about Files:: Testing existence, accessibility, size of files. ++* Changing Files:: Renaming files, changing protection, etc. ++* File Names:: Decomposing and expanding file names. ++* Contents of Directories:: Getting a list of the files in a directory. ++* Create/Delete Dirs:: Creating and Deleting Directories. ++* Magic File Names:: Defining "magic" special handling ++ for certain file names. ++* Format Conversion:: Conversion to and from various file formats. ++ ++Visiting Files ++ ++* Visiting Functions:: The usual interface functions for visiting. ++* Subroutines of Visiting:: Lower-level subroutines that they use. ++ ++Information about Files ++ ++* Testing Accessibility:: Is a given file readable? Writable? ++* Kinds of Files:: Is it a directory? A symbolic link? ++* Truenames:: Eliminating symbolic links from a file name. ++* File Attributes:: How large is it? Any other names? Etc. ++* Locating Files:: How to find a file in standard places. ++ ++File Names ++ ++* File Name Components:: The directory part of a file name, and the rest. ++* Relative File Names:: Some file names are relative to a current directory. ++* Directory Names:: A directory's name as a directory ++ is different from its name as a file. ++* File Name Expansion:: Converting relative file names to absolute ones. ++* Unique File Names:: Generating names for temporary files. ++* File Name Completion:: Finding the completions for a given file name. ++* Standard File Names:: If your package uses a fixed file name, ++ how to handle various operating systems simply. ++ ++File Format Conversion ++ ++* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. ++* Format Conversion Round-Trip:: Using @code{format-alist}. ++* Format Conversion Piecemeal:: Specifying non-paired conversion. ++ ++Backups and Auto-Saving ++ ++* Backup Files:: How backup files are made; how their names ++ are chosen. ++* Auto-Saving:: How auto-save files are made; how their ++ names are chosen. ++* Reverting:: @code{revert-buffer}, and how to customize ++ what it does. ++ ++Backup Files ++ ++* Making Backups:: How Emacs makes backup files, and when. ++* Rename or Copy:: Two alternatives: renaming the old file ++ or copying it. ++* Numbered Backups:: Keeping multiple backups for each source file. ++* Backup Names:: How backup file names are computed; customization. ++ ++Buffers ++ ++* Buffer Basics:: What is a buffer? ++* Current Buffer:: Designating a buffer as current ++ so that primitives will access its contents. ++* Buffer Names:: Accessing and changing buffer names. ++* Buffer File Name:: The buffer file name indicates which file ++ is visited. ++* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. ++* Modification Time:: Determining whether the visited file was changed ++ ``behind Emacs's back''. ++* Read Only Buffers:: Modifying text is not allowed in a ++ read-only buffer. ++* The Buffer List:: How to look at all the existing buffers. ++* Creating Buffers:: Functions that create buffers. ++* Killing Buffers:: Buffers exist until explicitly killed. ++* Indirect Buffers:: An indirect buffer shares text with some ++ other buffer. ++* Swapping Text:: Swapping text between two buffers. ++* Buffer Gap:: The gap in the buffer. ++ ++Windows ++ ++* Basic Windows:: Basic information on using windows. ++* Splitting Windows:: Splitting one window into two windows. ++* Deleting Windows:: Deleting a window gives its space to other windows. ++* Selecting Windows:: The selected window is the one that you edit in. ++* Cyclic Window Ordering:: Moving around the existing windows. ++* Buffers and Windows:: Each window displays the contents of a buffer. ++* Displaying Buffers:: Higher-level functions for displaying a buffer ++ and choosing a window for it. ++* Choosing Window:: How to choose a window for displaying a buffer. ++* Dedicated Windows:: How to avoid displaying another buffer in ++ a specific window. ++* Window Point:: Each window has its own location of point. ++* Window Start and End:: Buffer positions indicating which text is ++ on-screen in a window. ++* Textual Scrolling:: Moving text up and down through the window. ++* Vertical Scrolling:: Moving the contents up and down on the window. ++* Horizontal Scrolling:: Moving the contents sideways on the window. ++* Size of Window:: Accessing the size of a window. ++* Resizing Windows:: Changing the size of a window. ++* Coordinates and Windows:: Converting coordinates to windows. ++* Window Tree:: The layout and sizes of all windows in a frame. ++* Window Configurations:: Saving and restoring the state of the screen. ++* Window Parameters:: Associating additional information with windows. ++* Window Hooks:: Hooks for scrolling, window size changes, ++ redisplay going past a certain point, ++ or window configuration changes. ++ ++Frames ++ ++* Creating Frames:: Creating additional frames. ++* Multiple Terminals:: Displaying on several different devices. ++* Frame Parameters:: Controlling frame size, position, font, etc. ++* Terminal Parameters:: Parameters common for all frames on terminal. ++* Frame Titles:: Automatic updating of frame titles. ++* Deleting Frames:: Frames last until explicitly deleted. ++* Finding All Frames:: How to examine all existing frames. ++* Frames and Windows:: A frame contains windows; ++ display of text always works through windows. ++* Minibuffers and Frames:: How a frame finds the minibuffer to use. ++* Input Focus:: Specifying the selected frame. ++* Visibility of Frames:: Frames may be visible or invisible, or icons. ++* Raising and Lowering:: Raising a frame makes it hide other windows; ++ lowering it makes the others hide it. ++* Frame Configurations:: Saving the state of all frames. ++* Mouse Tracking:: Getting events that say when the mouse moves. ++* Mouse Position:: Asking where the mouse is, or moving it. ++* Pop-Up Menus:: Displaying a menu for the user to select from. ++* Dialog Boxes:: Displaying a box to ask yes or no. ++* Pointer Shape:: Specifying the shape of the mouse pointer. ++* Window System Selections::Transferring text to and from other X clients. ++* Drag and Drop:: Internals of Drag-and-Drop implementation. ++* Color Names:: Getting the definitions of color names. ++* Text Terminal Colors:: Defining colors for text-only terminals. ++* Resources:: Getting resource values from the server. ++* Display Feature Testing:: Determining the features of a terminal. ++ ++Frame Parameters ++ ++* Parameter Access:: How to change a frame's parameters. ++* Initial Parameters:: Specifying frame parameters when you make a frame. ++* Window Frame Parameters:: List of frame parameters for window systems. ++* Size and Position:: Changing the size and position of a frame. ++* Geometry:: Parsing geometry specifications. ++ ++Window Frame Parameters ++ ++* Basic Parameters:: Parameters that are fundamental. ++* Position Parameters:: The position of the frame on the screen. ++* Size Parameters:: Frame's size. ++* Layout Parameters:: Size of parts of the frame, and ++ enabling or disabling some parts. ++* Buffer Parameters:: Which buffers have been or should be shown. ++* Management Parameters:: Communicating with the window manager. ++* Cursor Parameters:: Controlling the cursor appearance. ++* Font and Color Parameters:: Fonts and colors for the frame text. ++ ++Positions ++ ++* Point:: The special position where editing takes place. ++* Motion:: Changing point. ++* Excursions:: Temporary motion and buffer changes. ++* Narrowing:: Restricting editing to a portion of the buffer. ++ ++Motion ++ ++* Character Motion:: Moving in terms of characters. ++* Word Motion:: Moving in terms of words. ++* Buffer End Motion:: Moving to the beginning or end of the buffer. ++* Text Lines:: Moving in terms of lines of text. ++* Screen Lines:: Moving in terms of lines as displayed. ++* List Motion:: Moving by parsing lists and sexps. ++* Skipping Characters:: Skipping characters belonging to a certain set. ++ ++Markers ++ ++* Overview of Markers:: The components of a marker, and how it relocates. ++* Predicates on Markers:: Testing whether an object is a marker. ++* Creating Markers:: Making empty markers or markers at certain places. ++* Information from Markers::Finding the marker's buffer or character position. ++* Marker Insertion Types:: Two ways a marker can relocate when you ++ insert where it points. ++* Moving Markers:: Moving the marker to a new buffer or position. ++* The Mark:: How "the mark" is implemented with a marker. ++* The Region:: How to access "the region". ++ ++Text ++ ++* Near Point:: Examining text in the vicinity of point. ++* Buffer Contents:: Examining text in a general fashion. ++* Comparing Text:: Comparing substrings of buffers. ++* Insertion:: Adding new text to a buffer. ++* Commands for Insertion:: User-level commands to insert text. ++* Deletion:: Removing text from a buffer. ++* User-Level Deletion:: User-level commands to delete text. ++* The Kill Ring:: Where removed text sometimes is saved for ++ later use. ++* Undo:: Undoing changes to the text of a buffer. ++* Maintaining Undo:: How to enable and disable undo information. ++ How to control how much information is kept. ++* Filling:: Functions for explicit filling. ++* Margins:: How to specify margins for filling commands. ++* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix ++ from context. ++* Auto Filling:: How auto-fill mode is implemented to break lines. ++* Sorting:: Functions for sorting parts of the buffer. ++* Columns:: Computing horizontal positions, and using them. ++* Indentation:: Functions to insert or adjust indentation. ++* Case Changes:: Case conversion of parts of the buffer. ++* Text Properties:: Assigning Lisp property lists to text characters. ++* Substitution:: Replacing a given character wherever it appears. ++* Transposition:: Swapping two portions of a buffer. ++* Registers:: How registers are implemented. Accessing ++ the text or position stored in a register. ++* Base 64:: Conversion to or from base 64 encoding. ++* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". ++* Atomic Changes:: Installing several buffer changes "atomically". ++* Change Hooks:: Supplying functions to be run when text is changed. ++ ++The Kill Ring ++ ++* Kill Ring Concepts:: What text looks like in the kill ring. ++* Kill Functions:: Functions that kill text. ++* Yanking:: How yanking is done. ++* Yank Commands:: Commands that access the kill ring. ++* Low-Level Kill Ring:: Functions and variables for kill ring access. ++* Internals of Kill Ring:: Variables that hold kill ring data. ++ ++Indentation ++ ++* Primitive Indent:: Functions used to count and insert indentation. ++* Mode-Specific Indent:: Customize indentation for different modes. ++* Region Indent:: Indent all the lines in a region. ++* Relative Indent:: Indent the current line based on previous lines. ++* Indent Tabs:: Adjustable, typewriter-like tab stops. ++* Motion by Indent:: Move to first non-blank character. ++ ++Text Properties ++ ++* Examining Properties:: Looking at the properties of one character. ++* Changing Properties:: Setting the properties of a range of text. ++* Property Search:: Searching for where a property changes value. ++* Special Properties:: Particular properties with special meanings. ++* Format Properties:: Properties for representing formatting of text. ++* Sticky Properties:: How inserted text gets properties from ++ neighboring text. ++* Lazy Properties:: Computing text properties in a lazy fashion ++ only when text is examined. ++* Clickable Text:: Using text properties to make regions of text ++ do something when you click on them. ++* Fields:: The @code{field} property defines ++ fields within the buffer. ++* Not Intervals:: Why text properties do not use ++ Lisp-visible text intervals. ++ ++Non-@acronym{ASCII} Characters ++ ++* Text Representations:: How Emacs represents text. ++* Converting Representations:: Converting unibyte to multibyte and vice versa. ++* Selecting a Representation:: Treating a byte sequence as unibyte or multi. ++* Character Codes:: How unibyte and multibyte relate to ++ codes of individual characters. ++* Character Properties:: Character attributes that define their ++ behavior and handling. ++* Character Sets:: The space of possible character codes ++ is divided into various character sets. ++* Scanning Charsets:: Which character sets are used in a buffer? ++* Translation of Characters:: Translation tables are used for conversion. ++* Coding Systems:: Coding systems are conversions for saving files. ++* Input Methods:: Input methods allow users to enter various ++ non-ASCII characters without special keyboards. ++* Locales:: Interacting with the POSIX locale. ++ ++Coding Systems ++ ++* Coding System Basics:: Basic concepts. ++* Encoding and I/O:: How file I/O functions handle coding systems. ++* Lisp and Coding Systems:: Functions to operate on coding system names. ++* User-Chosen Coding Systems:: Asking the user to choose a coding system. ++* Default Coding Systems:: Controlling the default choices. ++* Specifying Coding Systems:: Requesting a particular coding system ++ for a single file operation. ++* Explicit Encoding:: Encoding or decoding text without doing I/O. ++* Terminal I/O Encoding:: Use of encoding for terminal I/O. ++* MS-DOS File Types:: How DOS "text" and "binary" files ++ relate to coding systems. ++ ++Searching and Matching ++ ++* String Search:: Search for an exact match. ++* Searching and Case:: Case-independent or case-significant searching. ++* Regular Expressions:: Describing classes of strings. ++* Regexp Search:: Searching for a match for a regexp. ++* POSIX Regexps:: Searching POSIX-style for the longest match. ++* Match Data:: Finding out which part of the text matched, ++ after a string or regexp search. ++* Search and Replace:: Commands that loop, searching and replacing. ++* Standard Regexps:: Useful regexps for finding sentences, pages,... ++ ++Regular Expressions ++ ++* Syntax of Regexps:: Rules for writing regular expressions. ++* Regexp Example:: Illustrates regular expression syntax. ++* Regexp Functions:: Functions for operating on regular expressions. ++ ++Syntax of Regular Expressions ++ ++* Regexp Special:: Special characters in regular expressions. ++* Char Classes:: Character classes used in regular expressions. ++* Regexp Backslash:: Backslash-sequences in regular expressions. ++ ++The Match Data ++ ++* Replacing Match:: Replacing a substring that was matched. ++* Simple Match Data:: Accessing single items of match data, ++ such as where a particular subexpression started. ++* Entire Match Data:: Accessing the entire match data at once, as a list. ++* Saving Match Data:: Saving and restoring the match data. ++ ++Syntax Tables ++ ++* Syntax Basics:: Basic concepts of syntax tables. ++* Syntax Descriptors:: How characters are classified. ++* Syntax Table Functions:: How to create, examine and alter syntax tables. ++* Syntax Properties:: Overriding syntax with text properties. ++* Motion and Syntax:: Moving over characters with certain syntaxes. ++* Parsing Expressions:: Parsing balanced expressions ++ using the syntax table. ++* Standard Syntax Tables:: Syntax tables used by various major modes. ++* Syntax Table Internals:: How syntax table information is stored. ++* Categories:: Another way of classifying character syntax. ++ ++Syntax Descriptors ++ ++* Syntax Class Table:: Table of syntax classes. ++* Syntax Flags:: Additional flags each character can have. ++ ++Parsing Expressions ++ ++* Motion via Parsing:: Motion functions that work by parsing. ++* Position Parse:: Determining the syntactic state of a position. ++* Parser State:: How Emacs represents a syntactic state. ++* Low-Level Parsing:: Parsing across a specified region. ++* Control Parsing:: Parameters that affect parsing. ++ ++Abbrevs and Abbrev Expansion ++ ++* Abbrev Mode:: Setting up Emacs for abbreviation. ++* Abbrev Tables:: Creating and working with abbrev tables. ++* Defining Abbrevs:: Specifying abbreviations and their expansions. ++* Abbrev Files:: Saving abbrevs in files. ++* Abbrev Expansion:: Controlling expansion; expansion subroutines. ++* Standard Abbrev Tables:: Abbrev tables used by various major modes. ++* Abbrev Properties:: How to read and set abbrev properties. ++ Which properties have which effect. ++* Abbrev Table Properties:: How to read and set abbrev table properties. ++ Which properties have which effect. ++ ++Processes ++ ++* Subprocess Creation:: Functions that start subprocesses. ++* Shell Arguments:: Quoting an argument to pass it to a shell. ++* Synchronous Processes:: Details of using synchronous subprocesses. ++* Asynchronous Processes:: Starting up an asynchronous subprocess. ++* Deleting Processes:: Eliminating an asynchronous subprocess. ++* Process Information:: Accessing run-status and other attributes. ++* Input to Processes:: Sending input to an asynchronous subprocess. ++* Signals to Processes:: Stopping, continuing or interrupting ++ an asynchronous subprocess. ++* Output from Processes:: Collecting output from an asynchronous subprocess. ++* Sentinels:: Sentinels run when process run-status changes. ++* Query Before Exit:: Whether to query if exiting will kill a process. ++* System Processes:: Accessing other processes running on your system. ++* Transaction Queues:: Transaction-based communication with subprocesses. ++* Network:: Opening network connections. ++* Network Servers:: Network servers let Emacs accept net connections. ++* Datagrams:: UDP network connections. ++* Low-Level Network:: Lower-level but more general function ++ to create connections and servers. ++* Misc Network:: Additional relevant functions for ++ network connections. ++* Serial Ports:: Communicating with serial ports. ++* Byte Packing:: Using bindat to pack and unpack binary data. ++ ++Receiving Output from Processes ++ ++* Process Buffers:: If no filter, output is put in a buffer. ++* Filter Functions:: Filter functions accept output from the process. ++* Decoding Output:: Filters can get unibyte or multibyte strings. ++* Accepting Output:: How to wait until process output arrives. ++ ++Low-Level Network Access ++ ++* Network Processes:: Using @code{make-network-process}. ++* Network Options:: Further control over network connections. ++* Network Feature Testing:: Determining which network features work on ++ the machine you are using. ++ ++Packing and Unpacking Byte Arrays ++ ++* Bindat Spec:: Describing data layout. ++* Bindat Functions:: Doing the unpacking and packing. ++* Bindat Examples:: Samples of what bindat.el can do for you! ++ ++Emacs Display ++ ++* Refresh Screen:: Clearing the screen and redrawing everything on it. ++* Forcing Redisplay:: Forcing redisplay. ++* Truncation:: Folding or wrapping long text lines. ++* The Echo Area:: Displaying messages at the bottom of the screen. ++* Warnings:: Displaying warning messages for the user. ++* Invisible Text:: Hiding part of the buffer text. ++* Selective Display:: Hiding part of the buffer text (the old way). ++* Temporary Displays:: Displays that go away automatically. ++* Overlays:: Use overlays to highlight parts of the buffer. ++* Width:: How wide a character or string is on the screen. ++* Line Height:: Controlling the height of lines. ++* Faces:: A face defines a graphics style ++ for text characters: font, colors, etc. ++* Fringes:: Controlling window fringes. ++* Scroll Bars:: Controlling vertical scroll bars. ++* Display Property:: Enabling special display features. ++* Images:: Displaying images in Emacs buffers. ++* Buttons:: Adding clickable buttons to Emacs buffers. ++* Abstract Display:: Emacs' Widget for Object Collections. ++* Blinking:: How Emacs shows the matching open parenthesis. ++* Usual Display:: The usual conventions for displaying ++ nonprinting chars. ++* Display Tables:: How to specify other conventions. ++* Beeping:: Audible signal to the user. ++* Window Systems:: Which window system is being used. ++ ++The Echo Area ++ ++* Displaying Messages:: Explicitly displaying text in the echo area. ++* Progress:: Informing user about progress of a long operation. ++* Logging Messages:: Echo area messages are logged for the user. ++* Echo Area Customization:: Controlling the echo area. ++ ++Reporting Warnings ++ ++* Warning Basics:: Warnings concepts and functions to report them. ++* Warning Variables:: Variables programs bind to customize ++ their warnings. ++* Warning Options:: Variables users set to control display of warnings. ++ ++Overlays ++ ++* Managing Overlays:: Creating and moving overlays. ++* Overlay Properties:: How to read and set properties. ++ What properties do to the screen display. ++* Finding Overlays:: Searching for overlays. ++ ++Faces ++ ++* Defining Faces:: How to define a face with @code{defface}. ++* Face Attributes:: What is in a face? ++* Attribute Functions:: Functions to examine and set face attributes. ++* Displaying Faces:: How Emacs combines the faces specified for ++ a character. ++* Face Remapping:: Remapping faces to alternative definitions. ++* Face Functions:: How to define and examine faces. ++* Auto Faces:: Hook for automatic face assignment. ++* Font Selection:: Finding the best available font for a face. ++* Font Lookup:: Looking up the names of available fonts ++ and information about them. ++* Fontsets:: A fontset is a collection of fonts ++ that handle a range of character sets. ++* Low-Level Font:: Lisp representation for character display fonts. ++ ++Fringes ++ ++* Fringe Size/Pos:: Specifying where to put the window fringes. ++* Fringe Indicators:: Displaying indicator icons in the window fringes. ++* Fringe Cursors:: Displaying cursors in the right fringe. ++* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. ++* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. ++* Overlay Arrow:: Display of an arrow to indicate position. ++ ++The @code{display} Property ++ ++* Replacing Specs:: Display specs that replace the text. ++* Specified Space:: Displaying one space with a specified width. ++* Pixel Specification:: Specifying space width or height in pixels. ++* Other Display Specs:: Displaying an image; magnifying text; moving it ++ up or down on the page; adjusting the width ++ of spaces within text. ++* Display Margins:: Displaying text or images to the side of ++ the main text. ++ ++Images ++ ++* Image Formats:: Supported image formats. ++* Image Descriptors:: How to specify an image for use in @code{:display}. ++* XBM Images:: Special features for XBM format. ++* XPM Images:: Special features for XPM format. ++* GIF Images:: Special features for GIF format. ++* TIFF Images:: Special features for TIFF format. ++* PostScript Images:: Special features for PostScript format. ++* Other Image Types:: Various other formats are supported. ++* Defining Images:: Convenient ways to define an image for later use. ++* Showing Images:: Convenient ways to display an image once ++ it is defined. ++* Image Cache:: Internal mechanisms of image display. ++ ++Buttons ++ ++* Button Properties:: Button properties with special meanings. ++* Button Types:: Defining common properties for classes of buttons. ++* Making Buttons:: Adding buttons to Emacs buffers. ++* Manipulating Buttons:: Getting and setting properties of buttons. ++* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. ++ ++Abstract Display ++ ++* Abstract Display Functions:: Functions in the Ewoc package. ++* Abstract Display Example:: Example of using Ewoc. ++ ++Display Tables ++ ++* Display Table Format:: What a display table consists of. ++* Active Display Table:: How Emacs selects a display table to use. ++* Glyphs:: How to define a glyph, and what glyphs mean. ++ ++Operating System Interface ++ ++* Starting Up:: Customizing Emacs startup processing. ++* Getting Out:: How exiting works (permanent or temporary). ++* System Environment:: Distinguish the name and kind of system. ++* User Identification:: Finding the name and user id of the user. ++* Time of Day:: Getting the current time. ++* Time Conversion:: Converting a time from numeric form to ++ calendrical data and vice versa. ++* Time Parsing:: Converting a time from numeric form to text ++ and vice versa. ++* Processor Run Time:: Getting the run time used by Emacs. ++* Time Calculations:: Adding, subtracting, comparing times, etc. ++* Timers:: Setting a timer to call a function at a ++ certain time. ++* Idle Timers:: Setting a timer to call a function when Emacs has ++ been idle for a certain length of time. ++* Terminal Input:: Accessing and recording terminal input. ++* Terminal Output:: Controlling and recording terminal output. ++* Sound Output:: Playing sounds on the computer's speaker. ++* X11 Keysyms:: Operating on key symbols for X Windows. ++* Batch Mode:: Running Emacs without terminal interaction. ++* Session Management:: Saving and restoring state with ++ X Session Management. ++ ++Starting Up Emacs ++ ++* Startup Summary:: Sequence of actions Emacs performs at startup. ++* Init File:: Details on reading the init file. ++* Terminal-Specific:: How the terminal-specific Lisp file is read. ++* Command-Line Arguments:: How command-line arguments are processed, ++ and how you can customize them. ++ ++Getting Out of Emacs ++ ++* Killing Emacs:: Exiting Emacs irreversibly. ++* Suspending Emacs:: Exiting Emacs reversibly. ++ ++Terminal Input ++ ++* Input Modes:: Options for how input is processed. ++* Recording Input:: Saving histories of recent or all input events. ++ ++Tips and Conventions ++ ++* Coding Conventions:: Conventions for clean and robust programs. ++* Key Binding Conventions:: Which keys should be bound by which programs. ++* Programming Tips:: Making Emacs code fit smoothly in Emacs. ++* Compilation Tips:: Making compiled code run fast. ++* Warning Tips:: Turning off compiler warnings. ++* Documentation Tips:: Writing readable documentation strings. ++* Comment Tips:: Conventions for writing comments. ++* Library Headers:: Standard headers for library packages. ++ ++GNU Emacs Internals ++ ++* Building Emacs:: How the dumped Emacs is made. ++* Pure Storage:: A kludge to make preloaded Lisp functions sharable. ++* Garbage Collection:: Reclaiming space for Lisp objects no longer used. ++* Memory Usage:: Info about total size of Lisp objects made so far. ++* Writing Emacs Primitives:: Writing C code for Emacs. ++* Object Internals:: Data formats of buffers, windows, processes. ++ ++Object Internals ++ ++* Buffer Internals:: Components of a buffer structure. ++* Window Internals:: Components of a window structure. ++* Process Internals:: Components of a process structure. ++@end detailmenu ++@end menu ++ ++@include intro.texi ++@include objects.texi ++@include numbers.texi ++@include strings.texi ++ ++@include lists.texi ++@include sequences.texi ++@include hash.texi ++@include symbols.texi ++@include eval.texi ++ ++@include control.texi ++@include variables.texi ++@include functions.texi ++@include macros.texi ++ ++@include customize.texi ++@include loading.texi ++@include compile.texi ++@include advice.texi ++ ++@c This includes edebug.texi. ++@include debugging.texi ++@include streams.texi ++@include minibuf.texi ++@include commands.texi ++ ++@include keymaps.texi ++@include modes.texi ++@include help.texi ++@include files.texi ++ ++@include backups.texi ++@include buffers.texi ++@include windows.texi ++@include frames.texi ++ ++@include positions.texi ++@include markers.texi ++@include text.texi ++@include nonascii.texi ++ ++@include searching.texi ++@include syntax.texi ++@include abbrevs.texi ++@include processes.texi ++ ++@include display.texi ++@include os.texi ++ ++@c MOVE to Emacs Manual: include misc-modes.texi ++ ++@c appendices ++ ++@c REMOVE this: include non-hacker.texi ++ ++@include anti.texi ++@include doclicense.texi ++@include gpl.texi ++@include tips.texi ++@include internals.texi ++@include errors.texi ++@include locals.texi ++@include maps.texi ++@include hooks.texi ++ ++@include index.texi ++ ++@ignore ++@node New Symbols, , Index, Top ++@unnumbered New Symbols Since the Previous Edition ++ ++@printindex tp ++@end ignore ++ ++@bye ++ ++ ++These words prevent "local variables" above from confusing Emacs. ++ ++@ignore ++ arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34 ++@end ignore +diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi +new file mode 100644 +index 0000000..a495258 +--- /dev/null ++++ b/doc/lispref/errors.texi +@@ -0,0 +1,209 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/errors ++@node Standard Errors, Standard Buffer-Local Variables, GNU Emacs Internals, Top ++@appendix Standard Errors ++@cindex standard errors ++ ++ Here is the complete list of the error symbols in standard Emacs, ++grouped by concept. The list includes each symbol's message (on the ++@code{error-message} property of the symbol) and a cross reference to a ++description of how the error can occur. ++ ++ Each error symbol has an @code{error-conditions} property that is a ++list of symbols. Normally this list includes the error symbol itself ++and the symbol @code{error}. Occasionally it includes additional ++symbols, which are intermediate classifications, narrower than ++@code{error} but broader than a single error symbol. For example, all ++the errors in accessing files have the condition @code{file-error}. If ++we do not say here that a certain error symbol has additional error ++conditions, that means it has none. ++ ++ As a special exception, the error symbol @code{quit} does not have the ++condition @code{error}, because quitting is not considered an error. ++ ++ @xref{Errors}, for an explanation of how errors are generated and ++handled. ++ ++@table @code ++@item @var{symbol} ++@var{string}; @var{reference}. ++ ++@item error ++@code{"error"}@* ++@xref{Errors}. ++ ++@item quit ++@code{"Quit"}@* ++@xref{Quitting}. ++ ++@item args-out-of-range ++@code{"Args out of range"}@* ++This happens when trying to access an element beyond the range of a ++sequence or buffer.@* ++@xref{Sequences Arrays Vectors}, @xref{Text}. ++ ++@item arith-error ++@code{"Arithmetic error"}@* ++@xref{Arithmetic Operations}. ++ ++@item beginning-of-buffer ++@code{"Beginning of buffer"}@* ++@xref{Character Motion}. ++ ++@item buffer-read-only ++@code{"Buffer is read-only"}@* ++@xref{Read Only Buffers}. ++ ++@item coding-system-error ++@code{"Invalid coding system"}@* ++@xref{Lisp and Coding Systems}. ++ ++@item cyclic-function-indirection ++@code{"Symbol's chain of function indirections\@* contains a loop"}@* ++@xref{Function Indirection}. ++ ++@item cyclic-variable-indirection ++@code{"Symbol's chain of variable indirections\@* contains a loop"}@* ++@xref{Variable Aliases}. ++ ++@item end-of-buffer ++@code{"End of buffer"}@* ++@xref{Character Motion}. ++ ++@item end-of-file ++@code{"End of file during parsing"}@* ++Note that this is not a subcategory of @code{file-error}, ++because it pertains to the Lisp reader, not to file I/O.@* ++@xref{Input Functions}. ++ ++@item file-already-exists ++This is a subcategory of @code{file-error}.@* ++@xref{Writing to Files}. ++ ++@item file-date-error ++This is a subcategory of @code{file-error}. It occurs when ++@code{copy-file} tries and fails to set the last-modification time of ++the output file.@* ++@xref{Changing Files}. ++ ++@item file-error ++We do not list the error-strings of this error and its subcategories, ++because the error message is normally constructed from the data items ++alone when the error condition @code{file-error} is present. Thus, ++the error-strings are not very relevant. However, these error symbols ++do have @code{error-message} properties, and if no data is provided, ++the @code{error-message} property @emph{is} used.@* ++@xref{Files}. ++ ++@item file-locked ++This is a subcategory of @code{file-error}.@* ++@xref{File Locks}. ++ ++@item file-supersession ++This is a subcategory of @code{file-error}.@* ++@xref{Modification Time}. ++ ++@item ftp-error ++This is a subcategory of @code{file-error}, which results from problems ++in accessing a remote file using ftp.@* ++@xref{Remote Files,,, emacs, The GNU Emacs Manual}. ++ ++@item invalid-function ++@code{"Invalid function"}@* ++@xref{Function Indirection}. ++ ++@item invalid-read-syntax ++@code{"Invalid read syntax"}@* ++@xref{Printed Representation}. ++ ++@item invalid-regexp ++@code{"Invalid regexp"}@* ++@xref{Regular Expressions}. ++ ++@item mark-inactive ++@code{"The mark is not active now"}@* ++@xref{The Mark}. ++ ++@item no-catch ++@code{"No catch for tag"}@* ++@xref{Catch and Throw}. ++ ++@item scan-error ++@code{"Scan error"}@* ++This happens when certain syntax-parsing functions ++find invalid syntax or mismatched parentheses.@* ++@xref{List Motion}, and @ref{Parsing Expressions}. ++ ++@item search-failed ++@code{"Search failed"}@* ++@xref{Searching and Matching}. ++ ++@item setting-constant ++@code{"Attempt to set a constant symbol"}@* ++The values of the symbols @code{nil} and @code{t}, ++and any symbols that start with @samp{:}, ++may not be changed.@* ++@xref{Constant Variables, , Variables that Never Change}. ++ ++@item text-read-only ++@code{"Text is read-only"}@* ++This is a subcategory of @code{buffer-read-only}.@* ++@xref{Special Properties}. ++ ++@item undefined-color ++@code{"Undefined color"}@* ++@xref{Color Names}. ++ ++@item void-function ++@code{"Symbol's function definition is void"}@* ++@xref{Function Cells}. ++ ++@item void-variable ++@code{"Symbol's value as variable is void"}@* ++@xref{Accessing Variables}. ++ ++@item wrong-number-of-arguments ++@code{"Wrong number of arguments"}@* ++@xref{Classifying Lists}. ++ ++@item wrong-type-argument ++@code{"Wrong type argument"}@* ++@xref{Type Predicates}. ++@end table ++ ++ These kinds of error, which are classified as special cases of ++@code{arith-error}, can occur on certain systems for invalid use of ++mathematical functions. ++ ++@table @code ++@item domain-error ++@code{"Arithmetic domain error"}@* ++@xref{Math Functions}. ++ ++@item overflow-error ++@code{"Arithmetic overflow error"}@* ++This is a subcategory of @code{domain-error}.@* ++@xref{Math Functions}. ++ ++@item range-error ++@code{"Arithmetic range error"}@* ++@xref{Math Functions}. ++ ++@item singularity-error ++@code{"Arithmetic singularity error"}@* ++This is a subcategory of @code{domain-error}.@* ++@xref{Math Functions}. ++ ++@item underflow-error ++@code{"Arithmetic underflow error"}@* ++This is a subcategory of @code{domain-error}.@* ++@xref{Math Functions}. ++@end table ++ ++@ignore ++ arch-tag: 717c6048-5d9d-4c7d-9a62-df57390b6f19 ++@end ignore +diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi +new file mode 100644 +index 0000000..7e47005 +--- /dev/null ++++ b/doc/lispref/eval.texi +@@ -0,0 +1,754 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003, ++@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/eval ++@node Evaluation, Control Structures, Symbols, Top ++@chapter Evaluation ++@cindex evaluation ++@cindex interpreter ++@cindex interpreter ++@cindex value of expression ++ ++ The @dfn{evaluation} of expressions in Emacs Lisp is performed by the ++@dfn{Lisp interpreter}---a program that receives a Lisp object as input ++and computes its @dfn{value as an expression}. How it does this depends ++on the data type of the object, according to rules described in this ++chapter. The interpreter runs automatically to evaluate portions of ++your program, but can also be called explicitly via the Lisp primitive ++function @code{eval}. ++ ++@ifnottex ++@menu ++* Intro Eval:: Evaluation in the scheme of things. ++* Forms:: How various sorts of objects are evaluated. ++* Quoting:: Avoiding evaluation (to put constants in the program). ++* Eval:: How to invoke the Lisp interpreter explicitly. ++@end menu ++ ++@node Intro Eval ++@section Introduction to Evaluation ++ ++ The Lisp interpreter, or evaluator, is the part of Emacs that ++computes the value of an expression that is given to it. When a ++function written in Lisp is called, the evaluator computes the value ++of the function by evaluating the expressions in the function body. ++Thus, running any Lisp program really means running the Lisp ++interpreter. ++@end ifnottex ++ ++@cindex form ++@cindex expression ++ A Lisp object that is intended for evaluation is called an ++@dfn{expression} or a @dfn{form}. The fact that forms are data ++objects and not merely text is one of the fundamental differences ++between Lisp-like languages and typical programming languages. Any ++object can be evaluated, but in practice only numbers, symbols, lists ++and strings are evaluated very often. ++ ++ In subsequent sections, we will describe the details of what ++evaluation means for each kind of form. ++ ++ It is very common to read a Lisp form and then evaluate the form, ++but reading and evaluation are separate activities, and either can be ++performed alone. Reading per se does not evaluate anything; it ++converts the printed representation of a Lisp object to the object ++itself. It is up to the caller of @code{read} to specify whether this ++object is a form to be evaluated, or serves some entirely different ++purpose. @xref{Input Functions}. ++ ++@cindex recursive evaluation ++ Evaluation is a recursive process, and evaluating a form often ++involves evaluating parts within that form. For instance, when you ++evaluate a @dfn{function call} form such as @code{(car x)}, Emacs ++first evaluates the argument (the subform @code{x}). After evaluating ++the argument, Emacs @dfn{executes} the function (@code{car}), and if ++the function is written in Lisp, execution works by evaluating the ++@dfn{body} of the function. (In this example, however, @code{car} is ++not a Lisp function; it is a primitive function implemented in C.) ++@xref{Functions}, for more information about functions and function ++calls. ++ ++@cindex environment ++ Evaluation takes place in a context called the @dfn{environment}, ++which consists of the current values and bindings of all Lisp ++variables (@pxref{Variables}).@footnote{This definition of ++``environment'' is specifically not intended to include all the data ++that can affect the result of a program.} Whenever a form refers to a ++variable without creating a new binding for it, the variable evaluates ++to the value given by the current environment. Evaluating a form may ++create a new environment for recursive evaluation, by binding ++variables (@pxref{Local Variables}). Such environments are temporary, ++and vanish when the evaluation of the form is complete. ++ ++@cindex side effect ++ Evaluating a form may also make changes that persist; these changes ++are called @dfn{side effects}. An example of a form that produces a ++side effect is @code{(setq foo 1)}. ++ ++ Do not confuse evaluation with command key interpretation. The ++editor command loop translates keyboard input into a command (an ++interactively callable function) using the active keymaps, and then ++uses @code{call-interactively} to execute that command. Executing the ++command usually involves evaluation, if the command is written in ++Lisp; however, this step is not considered a part of command key ++interpretation. @xref{Command Loop}. ++ ++@node Forms ++@section Kinds of Forms ++ ++ A Lisp object that is intended to be evaluated is called a @dfn{form}. ++How Emacs evaluates a form depends on its data type. Emacs has three ++different kinds of form that are evaluated differently: symbols, lists, ++and ``all other types.'' This section describes all three kinds, one by ++one, starting with the ``all other types'' which are self-evaluating ++forms. ++ ++@menu ++* Self-Evaluating Forms:: Forms that evaluate to themselves. ++* Symbol Forms:: Symbols evaluate as variables. ++* Classifying Lists:: How to distinguish various sorts of list forms. ++* Function Indirection:: When a symbol appears as the car of a list, ++ we find the real function via the symbol. ++* Function Forms:: Forms that call functions. ++* Macro Forms:: Forms that call macros. ++* Special Forms:: "Special forms" are idiosyncratic primitives, ++ most of them extremely important. ++* Autoloading:: Functions set up to load files ++ containing their real definitions. ++@end menu ++ ++@node Self-Evaluating Forms ++@subsection Self-Evaluating Forms ++@cindex vector evaluation ++@cindex literal evaluation ++@cindex self-evaluating form ++ ++ A @dfn{self-evaluating form} is any form that is not a list or ++symbol. Self-evaluating forms evaluate to themselves: the result of ++evaluation is the same object that was evaluated. Thus, the number 25 ++evaluates to 25, and the string @code{"foo"} evaluates to the string ++@code{"foo"}. Likewise, evaluating a vector does not cause evaluation ++of the elements of the vector---it returns the same vector with its ++contents unchanged. ++ ++@example ++@group ++'123 ; @r{A number, shown without evaluation.} ++ @result{} 123 ++@end group ++@group ++123 ; @r{Evaluated as usual---result is the same.} ++ @result{} 123 ++@end group ++@group ++(eval '123) ; @r{Evaluated ``by hand''---result is the same.} ++ @result{} 123 ++@end group ++@group ++(eval (eval '123)) ; @r{Evaluating twice changes nothing.} ++ @result{} 123 ++@end group ++@end example ++ ++ It is common to write numbers, characters, strings, and even vectors ++in Lisp code, taking advantage of the fact that they self-evaluate. ++However, it is quite unusual to do this for types that lack a read ++syntax, because there's no way to write them textually. It is possible ++to construct Lisp expressions containing these types by means of a Lisp ++program. Here is an example: ++ ++@example ++@group ++;; @r{Build an expression containing a buffer object.} ++(setq print-exp (list 'print (current-buffer))) ++ @result{} (print #) ++@end group ++@group ++;; @r{Evaluate it.} ++(eval print-exp) ++ @print{} # ++ @result{} # ++@end group ++@end example ++ ++@node Symbol Forms ++@subsection Symbol Forms ++@cindex symbol evaluation ++ ++ When a symbol is evaluated, it is treated as a variable. The result ++is the variable's value, if it has one. If it has none (if its value ++cell is void), an error is signaled. For more information on the use of ++variables, see @ref{Variables}. ++ ++ In the following example, we set the value of a symbol with ++@code{setq}. Then we evaluate the symbol, and get back the value that ++@code{setq} stored. ++ ++@example ++@group ++(setq a 123) ++ @result{} 123 ++@end group ++@group ++(eval 'a) ++ @result{} 123 ++@end group ++@group ++a ++ @result{} 123 ++@end group ++@end example ++ ++ The symbols @code{nil} and @code{t} are treated specially, so that the ++value of @code{nil} is always @code{nil}, and the value of @code{t} is ++always @code{t}; you cannot set or bind them to any other values. Thus, ++these two symbols act like self-evaluating forms, even though ++@code{eval} treats them like any other symbol. A symbol whose name ++starts with @samp{:} also self-evaluates in the same way; likewise, ++its value ordinarily cannot be changed. @xref{Constant Variables}. ++ ++@node Classifying Lists ++@subsection Classification of List Forms ++@cindex list form evaluation ++ ++ A form that is a nonempty list is either a function call, a macro ++call, or a special form, according to its first element. These three ++kinds of forms are evaluated in different ways, described below. The ++remaining list elements constitute the @dfn{arguments} for the function, ++macro, or special form. ++ ++ The first step in evaluating a nonempty list is to examine its first ++element. This element alone determines what kind of form the list is ++and how the rest of the list is to be processed. The first element is ++@emph{not} evaluated, as it would be in some Lisp dialects such as ++Scheme. ++ ++@node Function Indirection ++@subsection Symbol Function Indirection ++@cindex symbol function indirection ++@cindex indirection for functions ++@cindex void function ++ ++ If the first element of the list is a symbol then evaluation ++examines the symbol's function cell, and uses its contents instead of ++the original symbol. If the contents are another symbol, this ++process, called @dfn{symbol function indirection}, is repeated until ++it obtains a non-symbol. @xref{Function Names}, for more information ++about symbol function indirection. ++ ++ One possible consequence of this process is an infinite loop, in the ++event that a symbol's function cell refers to the same symbol. Or a ++symbol may have a void function cell, in which case the subroutine ++@code{symbol-function} signals a @code{void-function} error. But if ++neither of these things happens, we eventually obtain a non-symbol, ++which ought to be a function or other suitable object. ++ ++@kindex invalid-function ++ More precisely, we should now have a Lisp function (a lambda ++expression), a byte-code function, a primitive function, a Lisp macro, ++a special form, or an autoload object. Each of these types is a case ++described in one of the following sections. If the object is not one ++of these types, Emacs signals an @code{invalid-function} error. ++ ++ The following example illustrates the symbol indirection process. We ++use @code{fset} to set the function cell of a symbol and ++@code{symbol-function} to get the function cell contents ++(@pxref{Function Cells}). Specifically, we store the symbol @code{car} ++into the function cell of @code{first}, and the symbol @code{first} into ++the function cell of @code{erste}. ++ ++@smallexample ++@group ++;; @r{Build this function cell linkage:} ++;; ------------- ----- ------- ------- ++;; | # | <-- | car | <-- | first | <-- | erste | ++;; ------------- ----- ------- ------- ++@end group ++@end smallexample ++ ++@smallexample ++@group ++(symbol-function 'car) ++ @result{} # ++@end group ++@group ++(fset 'first 'car) ++ @result{} car ++@end group ++@group ++(fset 'erste 'first) ++ @result{} first ++@end group ++@group ++(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.} ++ @result{} 1 ++@end group ++@end smallexample ++ ++ By contrast, the following example calls a function without any symbol ++function indirection, because the first element is an anonymous Lisp ++function, not a symbol. ++ ++@smallexample ++@group ++((lambda (arg) (erste arg)) ++ '(1 2 3)) ++ @result{} 1 ++@end group ++@end smallexample ++ ++@noindent ++Executing the function itself evaluates its body; this does involve ++symbol function indirection when calling @code{erste}. ++ ++ The built-in function @code{indirect-function} provides an easy way to ++perform symbol function indirection explicitly. ++ ++@c Emacs 19 feature ++@defun indirect-function function &optional noerror ++@anchor{Definition of indirect-function} ++This function returns the meaning of @var{function} as a function. If ++@var{function} is a symbol, then it finds @var{function}'s function ++definition and starts over with that value. If @var{function} is not a ++symbol, then it returns @var{function} itself. ++ ++This function signals a @code{void-function} error if the final symbol ++is unbound and optional argument @var{noerror} is @code{nil} or ++omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns ++@code{nil} if the final symbol is unbound. ++ ++It signals a @code{cyclic-function-indirection} error if there is a ++loop in the chain of symbols. ++ ++Here is how you could define @code{indirect-function} in Lisp: ++ ++@smallexample ++(defun indirect-function (function) ++ (if (symbolp function) ++ (indirect-function (symbol-function function)) ++ function)) ++@end smallexample ++@end defun ++ ++@node Function Forms ++@subsection Evaluation of Function Forms ++@cindex function form evaluation ++@cindex function call ++ ++ If the first element of a list being evaluated is a Lisp function ++object, byte-code object or primitive function object, then that list is ++a @dfn{function call}. For example, here is a call to the function ++@code{+}: ++ ++@example ++(+ 1 x) ++@end example ++ ++ The first step in evaluating a function call is to evaluate the ++remaining elements of the list from left to right. The results are the ++actual argument values, one value for each list element. The next step ++is to call the function with this list of arguments, effectively using ++the function @code{apply} (@pxref{Calling Functions}). If the function ++is written in Lisp, the arguments are used to bind the argument ++variables of the function (@pxref{Lambda Expressions}); then the forms ++in the function body are evaluated in order, and the value of the last ++body form becomes the value of the function call. ++ ++@node Macro Forms ++@subsection Lisp Macro Evaluation ++@cindex macro call evaluation ++ ++ If the first element of a list being evaluated is a macro object, then ++the list is a @dfn{macro call}. When a macro call is evaluated, the ++elements of the rest of the list are @emph{not} initially evaluated. ++Instead, these elements themselves are used as the arguments of the ++macro. The macro definition computes a replacement form, called the ++@dfn{expansion} of the macro, to be evaluated in place of the original ++form. The expansion may be any sort of form: a self-evaluating ++constant, a symbol, or a list. If the expansion is itself a macro call, ++this process of expansion repeats until some other sort of form results. ++ ++ Ordinary evaluation of a macro call finishes by evaluating the ++expansion. However, the macro expansion is not necessarily evaluated ++right away, or at all, because other programs also expand macro calls, ++and they may or may not evaluate the expansions. ++ ++ Normally, the argument expressions are not evaluated as part of ++computing the macro expansion, but instead appear as part of the ++expansion, so they are computed when the expansion is evaluated. ++ ++ For example, given a macro defined as follows: ++ ++@example ++@group ++(defmacro cadr (x) ++ (list 'car (list 'cdr x))) ++@end group ++@end example ++ ++@noindent ++an expression such as @code{(cadr (assq 'handler list))} is a macro ++call, and its expansion is: ++ ++@example ++(car (cdr (assq 'handler list))) ++@end example ++ ++@noindent ++Note that the argument @code{(assq 'handler list)} appears in the ++expansion. ++ ++@xref{Macros}, for a complete description of Emacs Lisp macros. ++ ++@node Special Forms ++@subsection Special Forms ++@cindex special forms ++@cindex evaluation of special forms ++ ++ A @dfn{special form} is a primitive function specially marked so that ++its arguments are not all evaluated. Most special forms define control ++structures or perform variable bindings---things which functions cannot ++do. ++ ++ Each special form has its own rules for which arguments are evaluated ++and which are used without evaluation. Whether a particular argument is ++evaluated may depend on the results of evaluating other arguments. ++ ++ Here is a list, in alphabetical order, of all of the special forms in ++Emacs Lisp with a reference to where each is described. ++ ++@table @code ++@item and ++@pxref{Combining Conditions} ++ ++@item catch ++@pxref{Catch and Throw} ++ ++@item cond ++@pxref{Conditionals} ++ ++@item condition-case ++@pxref{Handling Errors} ++ ++@item defconst ++@pxref{Defining Variables} ++ ++@item defmacro ++@pxref{Defining Macros} ++ ++@item defun ++@pxref{Defining Functions} ++ ++@item defvar ++@pxref{Defining Variables} ++ ++@item function ++@pxref{Anonymous Functions} ++ ++@item if ++@pxref{Conditionals} ++ ++@item interactive ++@pxref{Interactive Call} ++ ++@item let ++@itemx let* ++@pxref{Local Variables} ++ ++@item or ++@pxref{Combining Conditions} ++ ++@item prog1 ++@itemx prog2 ++@itemx progn ++@pxref{Sequencing} ++ ++@item quote ++@pxref{Quoting} ++ ++@item save-current-buffer ++@pxref{Current Buffer} ++ ++@item save-excursion ++@pxref{Excursions} ++ ++@item save-restriction ++@pxref{Narrowing} ++ ++@item save-window-excursion ++@pxref{Window Configurations} ++ ++@item setq ++@pxref{Setting Variables} ++ ++@item setq-default ++@pxref{Creating Buffer-Local} ++ ++@item track-mouse ++@pxref{Mouse Tracking} ++ ++@item unwind-protect ++@pxref{Nonlocal Exits} ++ ++@item while ++@pxref{Iteration} ++ ++@item with-output-to-temp-buffer ++@pxref{Temporary Displays} ++@end table ++ ++@cindex CL note---special forms compared ++@quotation ++@b{Common Lisp note:} Here are some comparisons of special forms in ++GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and ++@code{catch} are special forms in both Emacs Lisp and Common Lisp. ++@code{defun} is a special form in Emacs Lisp, but a macro in Common ++Lisp. @code{save-excursion} is a special form in Emacs Lisp, but ++doesn't exist in Common Lisp. @code{throw} is a special form in ++Common Lisp (because it must be able to throw multiple values), but it ++is a function in Emacs Lisp (which doesn't have multiple ++values).@refill ++@end quotation ++ ++@node Autoloading ++@subsection Autoloading ++ ++ The @dfn{autoload} feature allows you to call a function or macro ++whose function definition has not yet been loaded into Emacs. It ++specifies which file contains the definition. When an autoload object ++appears as a symbol's function definition, calling that symbol as a ++function automatically loads the specified file; then it calls the real ++definition loaded from that file. @xref{Autoload}. ++ ++@node Quoting ++@section Quoting ++ ++ The special form @code{quote} returns its single argument, as written, ++without evaluating it. This provides a way to include constant symbols ++and lists, which are not self-evaluating objects, in a program. (It is ++not necessary to quote self-evaluating objects such as numbers, strings, ++and vectors.) ++ ++@defspec quote object ++This special form returns @var{object}, without evaluating it. ++@end defspec ++ ++@cindex @samp{'} for quoting ++@cindex quoting using apostrophe ++@cindex apostrophe for quoting ++Because @code{quote} is used so often in programs, Lisp provides a ++convenient read syntax for it. An apostrophe character (@samp{'}) ++followed by a Lisp object (in read syntax) expands to a list whose first ++element is @code{quote}, and whose second element is the object. Thus, ++the read syntax @code{'x} is an abbreviation for @code{(quote x)}. ++ ++Here are some examples of expressions that use @code{quote}: ++ ++@example ++@group ++(quote (+ 1 2)) ++ @result{} (+ 1 2) ++@end group ++@group ++(quote foo) ++ @result{} foo ++@end group ++@group ++'foo ++ @result{} foo ++@end group ++@group ++''foo ++ @result{} (quote foo) ++@end group ++@group ++'(quote foo) ++ @result{} (quote foo) ++@end group ++@group ++['foo] ++ @result{} [(quote foo)] ++@end group ++@end example ++ ++ Other quoting constructs include @code{function} (@pxref{Anonymous ++Functions}), which causes an anonymous lambda expression written in Lisp ++to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote ++only part of a list, while computing and substituting other parts. ++ ++@node Eval ++@section Eval ++ ++ Most often, forms are evaluated automatically, by virtue of their ++occurrence in a program being run. On rare occasions, you may need to ++write code that evaluates a form that is computed at run time, such as ++after reading a form from text being edited or getting one from a ++property list. On these occasions, use the @code{eval} function. ++ ++ The functions and variables described in this section evaluate forms, ++specify limits to the evaluation process, or record recently returned ++values. Loading a file also does evaluation (@pxref{Loading}). ++ ++ It is generally cleaner and more flexible to store a function in a ++data structure, and call it with @code{funcall} or @code{apply}, than ++to store an expression in the data structure and evaluate it. Using ++functions provides the ability to pass information to them as ++arguments. ++ ++@defun eval form ++This is the basic function evaluating an expression. It evaluates ++@var{form} in the current environment and returns the result. How the ++evaluation proceeds depends on the type of the object (@pxref{Forms}). ++ ++Since @code{eval} is a function, the argument expression that appears ++in a call to @code{eval} is evaluated twice: once as preparation before ++@code{eval} is called, and again by the @code{eval} function itself. ++Here is an example: ++ ++@example ++@group ++(setq foo 'bar) ++ @result{} bar ++@end group ++@group ++(setq bar 'baz) ++ @result{} baz ++;; @r{Here @code{eval} receives argument @code{foo}} ++(eval 'foo) ++ @result{} bar ++;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}} ++(eval foo) ++ @result{} baz ++@end group ++@end example ++ ++The number of currently active calls to @code{eval} is limited to ++@code{max-lisp-eval-depth} (see below). ++@end defun ++ ++@deffn Command eval-region start end &optional stream read-function ++@anchor{Definition of eval-region} ++This function evaluates the forms in the current buffer in the region ++defined by the positions @var{start} and @var{end}. It reads forms from ++the region and calls @code{eval} on them until the end of the region is ++reached, or until an error is signaled and not handled. ++ ++By default, @code{eval-region} does not produce any output. However, ++if @var{stream} is non-@code{nil}, any output produced by output ++functions (@pxref{Output Functions}), as well as the values that ++result from evaluating the expressions in the region are printed using ++@var{stream}. @xref{Output Streams}. ++ ++If @var{read-function} is non-@code{nil}, it should be a function, ++which is used instead of @code{read} to read expressions one by one. ++This function is called with one argument, the stream for reading ++input. You can also use the variable @code{load-read-function} ++(@pxref{Definition of load-read-function,, How Programs Do Loading}) ++to specify this function, but it is more robust to use the ++@var{read-function} argument. ++ ++@code{eval-region} does not move point. It always returns @code{nil}. ++@end deffn ++ ++@cindex evaluation of buffer contents ++@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print ++This is similar to @code{eval-region}, but the arguments provide ++different optional features. @code{eval-buffer} operates on the ++entire accessible portion of buffer @var{buffer-or-name}. ++@var{buffer-or-name} can be a buffer, a buffer name (a string), or ++@code{nil} (or omitted), which means to use the current buffer. ++@var{stream} is used as in @code{eval-region}, unless @var{stream} is ++@code{nil} and @var{print} non-@code{nil}. In that case, values that ++result from evaluating the expressions are still discarded, but the ++output of the output functions is printed in the echo area. ++@var{filename} is the file name to use for @code{load-history} ++(@pxref{Unloading}), and defaults to @code{buffer-file-name} ++(@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil}, ++@code{read} converts strings to unibyte whenever possible. ++ ++@findex eval-current-buffer ++@code{eval-current-buffer} is an alias for this command. ++@end deffn ++ ++@defopt max-lisp-eval-depth ++@anchor{Definition of max-lisp-eval-depth} ++This variable defines the maximum depth allowed in calls to @code{eval}, ++@code{apply}, and @code{funcall} before an error is signaled (with error ++message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). ++ ++This limit, with the associated error when it is exceeded, is one way ++Emacs Lisp avoids infinite recursion on an ill-defined function. If ++you increase the value of @code{max-lisp-eval-depth} too much, such ++code can cause stack overflow instead. ++@cindex Lisp nesting error ++ ++The depth limit counts internal uses of @code{eval}, @code{apply}, and ++@code{funcall}, such as for calling the functions mentioned in Lisp ++expressions, and recursive evaluation of function call arguments and ++function body forms, as well as explicit calls in Lisp code. ++ ++The default value of this variable is 400. If you set it to a value ++less than 100, Lisp will reset it to 100 if the given value is ++reached. Entry to the Lisp debugger increases the value, if there is ++little room left, to make sure the debugger itself has room to ++execute. ++ ++@code{max-specpdl-size} provides another limit on nesting. ++@xref{Definition of max-specpdl-size,, Local Variables}. ++@end defopt ++ ++@defvar values ++The value of this variable is a list of the values returned by all the ++expressions that were read, evaluated, and printed from buffers ++(including the minibuffer) by the standard Emacs commands which do ++this. (Note that this does @emph{not} include evaluation in ++@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in ++@code{lisp-interaction-mode}.) The elements are ordered most recent ++first. ++ ++@example ++@group ++(setq x 1) ++ @result{} 1 ++@end group ++@group ++(list 'A (1+ 2) auto-save-default) ++ @result{} (A 3 t) ++@end group ++@group ++values ++ @result{} ((A 3 t) 1 @dots{}) ++@end group ++@end example ++ ++This variable is useful for referring back to values of forms recently ++evaluated. It is generally a bad idea to print the value of ++@code{values} itself, since this may be very long. Instead, examine ++particular elements, like this: ++ ++@example ++@group ++;; @r{Refer to the most recent evaluation result.} ++(nth 0 values) ++ @result{} (A 3 t) ++@end group ++@group ++;; @r{That put a new element on,} ++;; @r{so all elements move back one.} ++(nth 1 values) ++ @result{} (A 3 t) ++@end group ++@group ++;; @r{This gets the element that was next-to-most-recent} ++;; @r{before this example.} ++(nth 3 values) ++ @result{} 1 ++@end group ++@end example ++@end defvar ++ ++@ignore ++ arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57 ++@end ignore +diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi +new file mode 100644 +index 0000000..ff225e0 +--- /dev/null ++++ b/doc/lispref/files.texi +@@ -0,0 +1,3142 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/files ++@node Files, Backups and Auto-Saving, Documentation, Top ++@comment node-name, next, previous, up ++@chapter Files ++ ++ In Emacs, you can find, create, view, save, and otherwise work with ++files and file directories. This chapter describes most of the ++file-related functions of Emacs Lisp, but a few others are described in ++@ref{Buffers}, and those related to backups and auto-saving are ++described in @ref{Backups and Auto-Saving}. ++ ++ Many of the file functions take one or more arguments that are file ++names. A file name is actually a string. Most of these functions ++expand file name arguments by calling @code{expand-file-name}, so that ++@file{~} is handled correctly, as are relative file names (including ++@samp{../}). These functions don't recognize environment variable ++substitutions such as @samp{$HOME}. @xref{File Name Expansion}. ++ ++ When file I/O functions signal Lisp errors, they usually use the ++condition @code{file-error} (@pxref{Handling Errors}). The error ++message is in most cases obtained from the operating system, according ++to locale @code{system-message-locale}, and decoded using coding system ++@code{locale-coding-system} (@pxref{Locales}). ++ ++@menu ++* Visiting Files:: Reading files into Emacs buffers for editing. ++* Saving Buffers:: Writing changed buffers back into files. ++* Reading from Files:: Reading files into buffers without visiting. ++* Writing to Files:: Writing new files from parts of buffers. ++* File Locks:: Locking and unlocking files, to prevent ++ simultaneous editing by two people. ++* Information about Files:: Testing existence, accessibility, size of files. ++* Changing Files:: Renaming files, changing protection, etc. ++* File Names:: Decomposing and expanding file names. ++* Contents of Directories:: Getting a list of the files in a directory. ++* Create/Delete Dirs:: Creating and Deleting Directories. ++* Magic File Names:: Defining "magic" special handling ++ for certain file names. ++* Format Conversion:: Conversion to and from various file formats. ++@end menu ++ ++@node Visiting Files ++@section Visiting Files ++@cindex finding files ++@cindex visiting files ++ ++ Visiting a file means reading a file into a buffer. Once this is ++done, we say that the buffer is @dfn{visiting} that file, and call the ++file ``the visited file'' of the buffer. ++ ++ A file and a buffer are two different things. A file is information ++recorded permanently in the computer (unless you delete it). A buffer, ++on the other hand, is information inside of Emacs that will vanish at ++the end of the editing session (or when you kill the buffer). Usually, ++a buffer contains information that you have copied from a file; then we ++say the buffer is visiting that file. The copy in the buffer is what ++you modify with editing commands. Such changes to the buffer do not ++change the file; therefore, to make the changes permanent, you must ++@dfn{save} the buffer, which means copying the altered buffer contents ++back into the file. ++ ++ In spite of the distinction between files and buffers, people often ++refer to a file when they mean a buffer and vice-versa. Indeed, we say, ++``I am editing a file,'' rather than, ``I am editing a buffer that I ++will soon save as a file of the same name.'' Humans do not usually need ++to make the distinction explicit. When dealing with a computer program, ++however, it is good to keep the distinction in mind. ++ ++@menu ++* Visiting Functions:: The usual interface functions for visiting. ++* Subroutines of Visiting:: Lower-level subroutines that they use. ++@end menu ++ ++@node Visiting Functions ++@subsection Functions for Visiting Files ++ ++ This section describes the functions normally used to visit files. ++For historical reasons, these functions have names starting with ++@samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for ++functions and variables that access the visited file name of a buffer or ++that find an existing buffer by its visited file name. ++ ++ In a Lisp program, if you want to look at the contents of a file but ++not alter it, the fastest way is to use @code{insert-file-contents} in a ++temporary buffer. Visiting the file is not necessary and takes longer. ++@xref{Reading from Files}. ++ ++@deffn Command find-file filename &optional wildcards ++This command selects a buffer visiting the file @var{filename}, ++using an existing buffer if there is one, and otherwise creating a ++new buffer and reading the file into it. It also returns that buffer. ++ ++Aside from some technical details, the body of the @code{find-file} ++function is basically equivalent to: ++ ++@smallexample ++(switch-to-buffer (find-file-noselect filename nil nil wildcards)) ++@end smallexample ++ ++@noindent ++(See @code{switch-to-buffer} in @ref{Displaying Buffers}.) ++ ++If @var{wildcards} is non-@code{nil}, which is always true in an ++interactive call, then @code{find-file} expands wildcard characters in ++@var{filename} and visits all the matching files. ++ ++When @code{find-file} is called interactively, it prompts for ++@var{filename} in the minibuffer. ++@end deffn ++ ++@defun find-file-noselect filename &optional nowarn rawfile wildcards ++This function is the guts of all the file-visiting functions. It ++returns a buffer visiting the file @var{filename}. You may make the ++buffer current or display it in a window if you wish, but this ++function does not do so. ++ ++The function returns an existing buffer if there is one; otherwise it ++creates a new buffer and reads the file into it. When ++@code{find-file-noselect} uses an existing buffer, it first verifies ++that the file has not changed since it was last visited or saved in ++that buffer. If the file has changed, this function asks the user ++whether to reread the changed file. If the user says @samp{yes}, any ++edits previously made in the buffer are lost. ++ ++Reading the file involves decoding the file's contents (@pxref{Coding ++Systems}), including end-of-line conversion, and format conversion ++(@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil}, ++then @code{find-file-noselect} expands wildcard characters in ++@var{filename} and visits all the matching files. ++ ++This function displays warning or advisory messages in various peculiar ++cases, unless the optional argument @var{nowarn} is non-@code{nil}. For ++example, if it needs to create a buffer, and there is no file named ++@var{filename}, it displays the message @samp{(New file)} in the echo ++area, and leaves the buffer empty. ++ ++The @code{find-file-noselect} function normally calls ++@code{after-find-file} after reading the file (@pxref{Subroutines of ++Visiting}). That function sets the buffer major mode, parses local ++variables, warns the user if there exists an auto-save file more recent ++than the file just visited, and finishes by running the functions in ++@code{find-file-hook}. ++ ++If the optional argument @var{rawfile} is non-@code{nil}, then ++@code{after-find-file} is not called, and the ++@code{find-file-not-found-functions} are not run in case of failure. ++What's more, a non-@code{nil} @var{rawfile} value suppresses coding ++system conversion and format conversion. ++ ++The @code{find-file-noselect} function usually returns the buffer that ++is visiting the file @var{filename}. But, if wildcards are actually ++used and expanded, it returns a list of buffers that are visiting the ++various files. ++ ++@example ++@group ++(find-file-noselect "/etc/fstab") ++ @result{} # ++@end group ++@end example ++@end defun ++ ++@deffn Command find-file-other-window filename &optional wildcards ++This command selects a buffer visiting the file @var{filename}, but ++does so in a window other than the selected window. It may use another ++existing window or split a window; see @ref{Displaying Buffers}. ++ ++When this command is called interactively, it prompts for ++@var{filename}. ++@end deffn ++ ++@deffn Command find-file-read-only filename &optional wildcards ++This command selects a buffer visiting the file @var{filename}, like ++@code{find-file}, but it marks the buffer as read-only. @xref{Read Only ++Buffers}, for related functions and variables. ++ ++When this command is called interactively, it prompts for ++@var{filename}. ++@end deffn ++ ++@deffn Command view-file filename ++This command visits @var{filename} using View mode, returning to the ++previous buffer when you exit View mode. View mode is a minor mode that ++provides commands to skim rapidly through the file, but does not let you ++modify the text. Entering View mode runs the normal hook ++@code{view-mode-hook}. @xref{Hooks}. ++ ++When @code{view-file} is called interactively, it prompts for ++@var{filename}. ++@end deffn ++ ++@defopt find-file-wildcards ++If this variable is non-@code{nil}, then the various @code{find-file} ++commands check for wildcard characters and visit all the files that ++match them (when invoked interactively or when their @var{wildcards} ++argument is non-@code{nil}). If this option is @code{nil}, then ++the @code{find-file} commands ignore their @var{wildcards} argument ++and never treat wildcard characters specially. ++@end defopt ++ ++@defopt find-file-hook ++The value of this variable is a list of functions to be called after a ++file is visited. The file's local-variables specification (if any) will ++have been processed before the hooks are run. The buffer visiting the ++file is current when the hook functions are run. ++ ++This variable is a normal hook. @xref{Hooks}. ++@end defopt ++ ++@defvar find-file-not-found-functions ++The value of this variable is a list of functions to be called when ++@code{find-file} or @code{find-file-noselect} is passed a nonexistent ++file name. @code{find-file-noselect} calls these functions as soon as ++it detects a nonexistent file. It calls them in the order of the list, ++until one of them returns non-@code{nil}. @code{buffer-file-name} is ++already set up. ++ ++This is not a normal hook because the values of the functions are ++used, and in many cases only some of the functions are called. ++@end defvar ++ ++@node Subroutines of Visiting ++@comment node-name, next, previous, up ++@subsection Subroutines of Visiting ++ ++ The @code{find-file-noselect} function uses two important subroutines ++which are sometimes useful in user Lisp code: @code{create-file-buffer} ++and @code{after-find-file}. This section explains how to use them. ++ ++@defun create-file-buffer filename ++This function creates a suitably named buffer for visiting ++@var{filename}, and returns it. It uses @var{filename} (sans directory) ++as the name if that name is free; otherwise, it appends a string such as ++@samp{<2>} to get an unused name. See also @ref{Creating Buffers}. ++ ++@strong{Please note:} @code{create-file-buffer} does @emph{not} ++associate the new buffer with a file and does not select the buffer. ++It also does not use the default major mode. ++ ++@example ++@group ++(create-file-buffer "foo") ++ @result{} # ++@end group ++@group ++(create-file-buffer "foo") ++ @result{} #> ++@end group ++@group ++(create-file-buffer "foo") ++ @result{} #> ++@end group ++@end example ++ ++This function is used by @code{find-file-noselect}. ++It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). ++@end defun ++ ++@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes ++This function sets the buffer major mode, and parses local variables ++(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} ++and by the default revert function (@pxref{Reverting}). ++ ++@cindex new file message ++@cindex file open error ++If reading the file got an error because the file does not exist, but ++its directory does exist, the caller should pass a non-@code{nil} value ++for @var{error}. In that case, @code{after-find-file} issues a warning: ++@samp{(New file)}. For more serious errors, the caller should usually not ++call @code{after-find-file}. ++ ++If @var{warn} is non-@code{nil}, then this function issues a warning ++if an auto-save file exists and is more recent than the visited file. ++ ++If @var{noauto} is non-@code{nil}, that says not to enable or disable ++Auto-Save mode. The mode remains enabled if it was enabled before. ++ ++If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that ++means this call was from @code{revert-buffer}. This has no direct ++effect, but some mode functions and hook functions check the value ++of this variable. ++ ++If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's ++major mode, don't process local variables specifications in the file, ++and don't run @code{find-file-hook}. This feature is used by ++@code{revert-buffer} in some cases. ++ ++The last thing @code{after-find-file} does is call all the functions ++in the list @code{find-file-hook}. ++@end defun ++ ++@node Saving Buffers ++@section Saving Buffers ++@cindex saving buffers ++ ++ When you edit a file in Emacs, you are actually working on a buffer ++that is visiting that file---that is, the contents of the file are ++copied into the buffer and the copy is what you edit. Changes to the ++buffer do not change the file until you @dfn{save} the buffer, which ++means copying the contents of the buffer into the file. ++ ++@deffn Command save-buffer &optional backup-option ++This function saves the contents of the current buffer in its visited ++file if the buffer has been modified since it was last visited or saved. ++Otherwise it does nothing. ++ ++@code{save-buffer} is responsible for making backup files. Normally, ++@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup ++file only if this is the first save since visiting the file. Other ++values for @var{backup-option} request the making of backup files in ++other circumstances: ++ ++@itemize @bullet ++@item ++With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the ++@code{save-buffer} function marks this version of the file to be ++backed up when the buffer is next saved. ++ ++@item ++With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the ++@code{save-buffer} function unconditionally backs up the previous ++version of the file before saving it. ++ ++@item ++With an argument of 0, unconditionally do @emph{not} make any backup file. ++@end itemize ++@end deffn ++ ++@deffn Command save-some-buffers &optional save-silently-p pred ++@anchor{Definition of save-some-buffers} ++This command saves some modified file-visiting buffers. Normally it ++asks the user about each buffer. But if @var{save-silently-p} is ++non-@code{nil}, it saves all the file-visiting buffers without querying ++the user. ++ ++The optional @var{pred} argument controls which buffers to ask about ++(or to save silently if @var{save-silently-p} is non-@code{nil}). ++If it is @code{nil}, that means to ask only about file-visiting buffers. ++If it is @code{t}, that means also offer to save certain other non-file ++buffers---those that have a non-@code{nil} buffer-local value of ++@code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says ++@samp{yes} to saving a non-file buffer is asked to specify the file ++name to use. The @code{save-buffers-kill-emacs} function passes the ++value @code{t} for @var{pred}. ++ ++If @var{pred} is neither @code{t} nor @code{nil}, then it should be ++a function of no arguments. It will be called in each buffer to decide ++whether to offer to save that buffer. If it returns a non-@code{nil} ++value in a certain buffer, that means do offer to save that buffer. ++@end deffn ++ ++@deffn Command write-file filename &optional confirm ++@anchor{Definition of write-file} ++This function writes the current buffer into file @var{filename}, makes ++the buffer visit that file, and marks it not modified. Then it renames ++the buffer based on @var{filename}, appending a string like @samp{<2>} ++if necessary to make a unique buffer name. It does most of this work by ++calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and ++@code{save-buffer}. ++ ++If @var{confirm} is non-@code{nil}, that means to ask for confirmation ++before overwriting an existing file. Interactively, confirmation is ++required, unless the user supplies a prefix argument. ++ ++If @var{filename} is an existing directory, or a symbolic link to one, ++@code{write-file} uses the name of the visited file, in directory ++@var{filename}. If the buffer is not visiting a file, it uses the ++buffer name instead. ++@end deffn ++ ++ Saving a buffer runs several hooks. It also performs format ++conversion (@pxref{Format Conversion}). ++ ++@defvar write-file-functions ++The value of this variable is a list of functions to be called before ++writing out a buffer to its visited file. If one of them returns ++non-@code{nil}, the file is considered already written and the rest of ++the functions are not called, nor is the usual code for writing the file ++executed. ++ ++If a function in @code{write-file-functions} returns non-@code{nil}, it ++is responsible for making a backup file (if that is appropriate). ++To do so, execute the following code: ++ ++@example ++(or buffer-backed-up (backup-buffer)) ++@end example ++ ++You might wish to save the file modes value returned by ++@code{backup-buffer} and use that (if non-@code{nil}) to set the mode ++bits of the file that you write. This is what @code{save-buffer} ++normally does. @xref{Making Backups,, Making Backup Files}. ++ ++The hook functions in @code{write-file-functions} are also responsible ++for encoding the data (if desired): they must choose a suitable coding ++system and end-of-line conversion (@pxref{Lisp and Coding Systems}), ++perform the encoding (@pxref{Explicit Encoding}), and set ++@code{last-coding-system-used} to the coding system that was used ++(@pxref{Encoding and I/O}). ++ ++If you set this hook locally in a buffer, it is assumed to be ++associated with the file or the way the contents of the buffer were ++obtained. Thus the variable is marked as a permanent local, so that ++changing the major mode does not alter a buffer-local value. On the ++other hand, calling @code{set-visited-file-name} will reset it. ++If this is not what you want, you might like to use ++@code{write-contents-functions} instead. ++ ++Even though this is not a normal hook, you can use @code{add-hook} and ++@code{remove-hook} to manipulate the list. @xref{Hooks}. ++@end defvar ++ ++@c Emacs 19 feature ++@defvar write-contents-functions ++This works just like @code{write-file-functions}, but it is intended ++for hooks that pertain to the buffer's contents, not to the particular ++visited file or its location. Such hooks are usually set up by major ++modes, as buffer-local bindings for this variable. This variable ++automatically becomes buffer-local whenever it is set; switching to a ++new major mode always resets this variable, but calling ++@code{set-visited-file-name} does not. ++ ++If any of the functions in this hook returns non-@code{nil}, the file ++is considered already written and the rest are not called and neither ++are the functions in @code{write-file-functions}. ++@end defvar ++ ++@defopt before-save-hook ++This normal hook runs before a buffer is saved in its visited file, ++regardless of whether that is done normally or by one of the hooks ++described above. For instance, the @file{copyright.el} program uses ++this hook to make sure the file you are saving has the current year in ++its copyright notice. ++@end defopt ++ ++@c Emacs 19 feature ++@defopt after-save-hook ++This normal hook runs after a buffer has been saved in its visited file. ++One use of this hook is in Fast Lock mode; it uses this hook to save the ++highlighting information in a cache file. ++@end defopt ++ ++@defopt file-precious-flag ++If this variable is non-@code{nil}, then @code{save-buffer} protects ++against I/O errors while saving by writing the new file to a temporary ++name instead of the name it is supposed to have, and then renaming it to ++the intended name after it is clear there are no errors. This procedure ++prevents problems such as a lack of disk space from resulting in an ++invalid file. ++ ++As a side effect, backups are necessarily made by copying. @xref{Rename ++or Copy}. Yet, at the same time, saving a precious file always breaks ++all hard links between the file you save and other file names. ++ ++Some modes give this variable a non-@code{nil} buffer-local value ++in particular buffers. ++@end defopt ++ ++@defopt require-final-newline ++This variable determines whether files may be written out that do ++@emph{not} end with a newline. If the value of the variable is ++@code{t}, then @code{save-buffer} silently adds a newline at the end of ++the file whenever the buffer being saved does not already end in one. ++If the value of the variable is non-@code{nil}, but not @code{t}, then ++@code{save-buffer} asks the user whether to add a newline each time the ++case arises. ++ ++If the value of the variable is @code{nil}, then @code{save-buffer} ++doesn't add newlines at all. @code{nil} is the default value, but a few ++major modes set it to @code{t} in particular buffers. ++@end defopt ++ ++ See also the function @code{set-visited-file-name} (@pxref{Buffer File ++Name}). ++ ++@node Reading from Files ++@comment node-name, next, previous, up ++@section Reading from Files ++@cindex reading from files ++ ++ You can copy a file from the disk and insert it into a buffer ++using the @code{insert-file-contents} function. Don't use the user-level ++command @code{insert-file} in a Lisp program, as that sets the mark. ++ ++@defun insert-file-contents filename &optional visit beg end replace ++This function inserts the contents of file @var{filename} into the ++current buffer after point. It returns a list of the absolute file name ++and the length of the data inserted. An error is signaled if ++@var{filename} is not the name of a file that can be read. ++ ++The function @code{insert-file-contents} checks the file contents ++against the defined file formats, and converts the file contents if ++appropriate and also calls the functions in ++the list @code{after-insert-file-functions}. @xref{Format Conversion}. ++Normally, one of the functions in the ++@code{after-insert-file-functions} list determines the coding system ++(@pxref{Coding Systems}) used for decoding the file's contents, ++including end-of-line conversion. However, if the file contains null ++bytes, it is by default visited without any code conversions; see ++@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to ++control this behavior. ++ ++If @var{visit} is non-@code{nil}, this function additionally marks the ++buffer as unmodified and sets up various fields in the buffer so that it ++is visiting the file @var{filename}: these include the buffer's visited ++file name and its last save file modtime. This feature is used by ++@code{find-file-noselect} and you probably should not use it yourself. ++ ++If @var{beg} and @var{end} are non-@code{nil}, they should be integers ++specifying the portion of the file to insert. In this case, @var{visit} ++must be @code{nil}. For example, ++ ++@example ++(insert-file-contents filename nil 0 500) ++@end example ++ ++@noindent ++inserts the first 500 characters of a file. ++ ++If the argument @var{replace} is non-@code{nil}, it means to replace the ++contents of the buffer (actually, just the accessible portion) with the ++contents of the file. This is better than simply deleting the buffer ++contents and inserting the whole file, because (1) it preserves some ++marker positions and (2) it puts less data in the undo list. ++ ++It is possible to read a special file (such as a FIFO or an I/O device) ++with @code{insert-file-contents}, as long as @var{replace} and ++@var{visit} are @code{nil}. ++@end defun ++ ++@defun insert-file-contents-literally filename &optional visit beg end replace ++This function works like @code{insert-file-contents} except that it does ++not do format decoding (@pxref{Format Conversion}), does not do ++character code conversion (@pxref{Coding Systems}), does not run ++@code{find-file-hook}, does not perform automatic uncompression, and so ++on. ++@end defun ++ ++If you want to pass a file name to another process so that another ++program can read the file, use the function @code{file-local-copy}; see ++@ref{Magic File Names}. ++ ++@node Writing to Files ++@comment node-name, next, previous, up ++@section Writing to Files ++@cindex writing to files ++ ++ You can write the contents of a buffer, or part of a buffer, directly ++to a file on disk using the @code{append-to-file} and ++@code{write-region} functions. Don't use these functions to write to ++files that are being visited; that could cause confusion in the ++mechanisms for visiting. ++ ++@deffn Command append-to-file start end filename ++This function appends the contents of the region delimited by ++@var{start} and @var{end} in the current buffer to the end of file ++@var{filename}. If that file does not exist, it is created. This ++function returns @code{nil}. ++ ++An error is signaled if @var{filename} specifies a nonwritable file, ++or a nonexistent file in a directory where files cannot be created. ++ ++When called from Lisp, this function is completely equivalent to: ++ ++@example ++(write-region start end filename t) ++@end example ++@end deffn ++ ++@deffn Command write-region start end filename &optional append visit lockname mustbenew ++This function writes the region delimited by @var{start} and @var{end} ++in the current buffer into the file specified by @var{filename}. ++ ++If @var{start} is @code{nil}, then the command writes the entire buffer ++contents (@emph{not} just the accessible portion) to the file and ++ignores @var{end}. ++ ++@c Emacs 19 feature ++If @var{start} is a string, then @code{write-region} writes or appends ++that string, rather than text from the buffer. @var{end} is ignored in ++this case. ++ ++If @var{append} is non-@code{nil}, then the specified text is appended ++to the existing file contents (if any). If @var{append} is an ++integer, @code{write-region} seeks to that byte offset from the start ++of the file and writes the data from there. ++ ++If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks ++for confirmation if @var{filename} names an existing file. If ++@var{mustbenew} is the symbol @code{excl}, then @code{write-region} ++does not ask for confirmation, but instead it signals an error ++@code{file-already-exists} if the file already exists. ++ ++The test for an existing file, when @var{mustbenew} is @code{excl}, uses ++a special system feature. At least for files on a local disk, there is ++no chance that some other program could create a file of the same name ++before Emacs does, without Emacs's noticing. ++ ++If @var{visit} is @code{t}, then Emacs establishes an association ++between the buffer and the file: the buffer is then visiting that file. ++It also sets the last file modification time for the current buffer to ++@var{filename}'s modtime, and marks the buffer as not modified. This ++feature is used by @code{save-buffer}, but you probably should not use ++it yourself. ++ ++@c Emacs 19 feature ++If @var{visit} is a string, it specifies the file name to visit. This ++way, you can write the data to one file (@var{filename}) while recording ++the buffer as visiting another file (@var{visit}). The argument ++@var{visit} is used in the echo area message and also for file locking; ++@var{visit} is stored in @code{buffer-file-name}. This feature is used ++to implement @code{file-precious-flag}; don't use it yourself unless you ++really know what you're doing. ++ ++The optional argument @var{lockname}, if non-@code{nil}, specifies the ++file name to use for purposes of locking and unlocking, overriding ++@var{filename} and @var{visit} for that purpose. ++ ++The function @code{write-region} converts the data which it writes to ++the appropriate file formats specified by @code{buffer-file-format} ++and also calls the functions in the list ++@code{write-region-annotate-functions}. ++@xref{Format Conversion}. ++ ++Normally, @code{write-region} displays the message @samp{Wrote ++@var{filename}} in the echo area. If @var{visit} is neither @code{t} ++nor @code{nil} nor a string, then this message is inhibited. This ++feature is useful for programs that use files for internal purposes, ++files that the user does not need to know about. ++@end deffn ++ ++@defmac with-temp-file file body@dots{} ++@anchor{Definition of with-temp-file} ++The @code{with-temp-file} macro evaluates the @var{body} forms with a ++temporary buffer as the current buffer; then, at the end, it writes the ++buffer contents into file @var{file}. It kills the temporary buffer ++when finished, restoring the buffer that was current before the ++@code{with-temp-file} form. Then it returns the value of the last form ++in @var{body}. ++ ++The current buffer is restored even in case of an abnormal exit via ++@code{throw} or error (@pxref{Nonlocal Exits}). ++ ++See also @code{with-temp-buffer} in @ref{Definition of ++with-temp-buffer,, The Current Buffer}. ++@end defmac ++ ++@node File Locks ++@section File Locks ++@cindex file locks ++@cindex lock file ++ ++ When two users edit the same file at the same time, they are likely ++to interfere with each other. Emacs tries to prevent this situation ++from arising by recording a @dfn{file lock} when a file is being ++modified. (File locks are not implemented on Microsoft systems.) ++Emacs can then detect the first attempt to modify a buffer visiting a ++file that is locked by another Emacs job, and ask the user what to do. ++The file lock is really a file, a symbolic link with a special name, ++stored in the same directory as the file you are editing. ++ ++ When you access files using NFS, there may be a small probability that ++you and another user will both lock the same file ``simultaneously.'' ++If this happens, it is possible for the two users to make changes ++simultaneously, but Emacs will still warn the user who saves second. ++Also, the detection of modification of a buffer visiting a file changed ++on disk catches some cases of simultaneous editing; see ++@ref{Modification Time}. ++ ++@defun file-locked-p filename ++This function returns @code{nil} if the file @var{filename} is not ++locked. It returns @code{t} if it is locked by this Emacs process, and ++it returns the name of the user who has locked it if it is locked by ++some other job. ++ ++@example ++@group ++(file-locked-p "foo") ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun lock-buffer &optional filename ++This function locks the file @var{filename}, if the current buffer is ++modified. The argument @var{filename} defaults to the current buffer's ++visited file. Nothing is done if the current buffer is not visiting a ++file, or is not modified, or if the system does not support locking. ++@end defun ++ ++@defun unlock-buffer ++This function unlocks the file being visited in the current buffer, ++if the buffer is modified. If the buffer is not modified, then ++the file should not be locked, so this function does nothing. It also ++does nothing if the current buffer is not visiting a file, or if the ++system does not support locking. ++@end defun ++ ++ File locking is not supported on some systems. On systems that do not ++support it, the functions @code{lock-buffer}, @code{unlock-buffer} and ++@code{file-locked-p} do nothing and return @code{nil}. ++ ++@defun ask-user-about-lock file other-user ++This function is called when the user tries to modify @var{file}, but it ++is locked by another user named @var{other-user}. The default ++definition of this function asks the user to say what to do. The value ++this function returns determines what Emacs does next: ++ ++@itemize @bullet ++@item ++A value of @code{t} says to grab the lock on the file. Then ++this user may edit the file and @var{other-user} loses the lock. ++ ++@item ++A value of @code{nil} says to ignore the lock and let this ++user edit the file anyway. ++ ++@item ++@kindex file-locked ++This function may instead signal a @code{file-locked} error, in which ++case the change that the user was about to make does not take place. ++ ++The error message for this error looks like this: ++ ++@example ++@error{} File is locked: @var{file} @var{other-user} ++@end example ++ ++@noindent ++where @code{file} is the name of the file and @var{other-user} is the ++name of the user who has locked the file. ++@end itemize ++ ++If you wish, you can replace the @code{ask-user-about-lock} function ++with your own version that makes the decision in another way. The code ++for its usual definition is in @file{userlock.el}. ++@end defun ++ ++@node Information about Files ++@section Information about Files ++@cindex file, information about ++ ++ The functions described in this section all operate on strings that ++designate file names. With a few exceptions, all the functions have ++names that begin with the word @samp{file}. These functions all ++return information about actual files or directories, so their ++arguments must all exist as actual files or directories unless ++otherwise noted. ++ ++@menu ++* Testing Accessibility:: Is a given file readable? Writable? ++* Kinds of Files:: Is it a directory? A symbolic link? ++* Truenames:: Eliminating symbolic links from a file name. ++* File Attributes:: How large is it? Any other names? Etc. ++* Locating Files:: How to find a file in standard places. ++@end menu ++ ++@node Testing Accessibility ++@comment node-name, next, previous, up ++@subsection Testing Accessibility ++@cindex accessibility of a file ++@cindex file accessibility ++ ++ These functions test for permission to access a file in specific ++ways. Unless explicitly stated otherwise, they recursively follow ++symbolic links for their file name arguments, at all levels (at the ++level of the file itself and at all levels of parent directories). ++ ++@defun file-exists-p filename ++This function returns @code{t} if a file named @var{filename} appears ++to exist. This does not mean you can necessarily read the file, only ++that you can find out its attributes. (On Unix and GNU/Linux, this is ++true if the file exists and you have execute permission on the ++containing directories, regardless of the protection of the file ++itself.) ++ ++If the file does not exist, or if fascist access control policies ++prevent you from finding the attributes of the file, this function ++returns @code{nil}. ++ ++Directories are files, so @code{file-exists-p} returns @code{t} when ++given a directory name. However, symbolic links are treated ++specially; @code{file-exists-p} returns @code{t} for a symbolic link ++name only if the target file exists. ++@end defun ++ ++@defun file-readable-p filename ++This function returns @code{t} if a file named @var{filename} exists ++and you can read it. It returns @code{nil} otherwise. ++ ++@example ++@group ++(file-readable-p "files.texi") ++ @result{} t ++@end group ++@group ++(file-exists-p "/usr/spool/mqueue") ++ @result{} t ++@end group ++@group ++(file-readable-p "/usr/spool/mqueue") ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@c Emacs 19 feature ++@defun file-executable-p filename ++This function returns @code{t} if a file named @var{filename} exists and ++you can execute it. It returns @code{nil} otherwise. On Unix and ++GNU/Linux, if the file is a directory, execute permission means you can ++check the existence and attributes of files inside the directory, and ++open those files if their modes permit. ++@end defun ++ ++@defun file-writable-p filename ++This function returns @code{t} if the file @var{filename} can be written ++or created by you, and @code{nil} otherwise. A file is writable if the ++file exists and you can write it. It is creatable if it does not exist, ++but the specified directory does exist and you can write in that ++directory. ++ ++In the third example below, @file{foo} is not writable because the ++parent directory does not exist, even though the user could create such ++a directory. ++ ++@example ++@group ++(file-writable-p "~/foo") ++ @result{} t ++@end group ++@group ++(file-writable-p "/foo") ++ @result{} nil ++@end group ++@group ++(file-writable-p "~/no-such-dir/foo") ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@c Emacs 19 feature ++@defun file-accessible-directory-p dirname ++This function returns @code{t} if you have permission to open existing ++files in the directory whose name as a file is @var{dirname}; ++otherwise (or if there is no such directory), it returns @code{nil}. ++The value of @var{dirname} may be either a directory name (such as ++@file{/foo/}) or the file name of a file which is a directory ++(such as @file{/foo}, without the final slash). ++ ++Example: after the following, ++ ++@example ++(file-accessible-directory-p "/foo") ++ @result{} nil ++@end example ++ ++@noindent ++we can deduce that any attempt to read a file in @file{/foo/} will ++give an error. ++@end defun ++ ++@defun access-file filename string ++This function opens file @var{filename} for reading, then closes it and ++returns @code{nil}. However, if the open fails, it signals an error ++using @var{string} as the error message text. ++@end defun ++ ++@defun file-ownership-preserved-p filename ++This function returns @code{t} if deleting the file @var{filename} and ++then creating it anew would keep the file's owner unchanged. It also ++returns @code{t} for nonexistent files. ++ ++If @var{filename} is a symbolic link, then, unlike the other functions ++discussed here, @code{file-ownership-preserved-p} does @emph{not} ++replace @var{filename} with its target. However, it does recursively ++follow symbolic links at all levels of parent directories. ++@end defun ++ ++@defun file-newer-than-file-p filename1 filename2 ++@cindex file age ++@cindex file modification time ++This function returns @code{t} if the file @var{filename1} is ++newer than file @var{filename2}. If @var{filename1} does not ++exist, it returns @code{nil}. If @var{filename1} does exist, but ++@var{filename2} does not, it returns @code{t}. ++ ++In the following example, assume that the file @file{aug-19} was written ++on the 19th, @file{aug-20} was written on the 20th, and the file ++@file{no-file} doesn't exist at all. ++ ++@example ++@group ++(file-newer-than-file-p "aug-19" "aug-20") ++ @result{} nil ++@end group ++@group ++(file-newer-than-file-p "aug-20" "aug-19") ++ @result{} t ++@end group ++@group ++(file-newer-than-file-p "aug-19" "no-file") ++ @result{} t ++@end group ++@group ++(file-newer-than-file-p "no-file" "aug-19") ++ @result{} nil ++@end group ++@end example ++ ++You can use @code{file-attributes} to get a file's last modification ++time as a list of two numbers. @xref{File Attributes}. ++@end defun ++ ++@node Kinds of Files ++@comment node-name, next, previous, up ++@subsection Distinguishing Kinds of Files ++ ++ This section describes how to distinguish various kinds of files, such ++as directories, symbolic links, and ordinary files. ++ ++@defun file-symlink-p filename ++@cindex file symbolic links ++If the file @var{filename} is a symbolic link, the ++@code{file-symlink-p} function returns the (non-recursive) link target ++as a string. (Determining the file name that the link points to from ++the target is nontrivial.) First, this function recursively follows ++symbolic links at all levels of parent directories. ++ ++If the file @var{filename} is not a symbolic link (or there is no such file), ++@code{file-symlink-p} returns @code{nil}. ++ ++@example ++@group ++(file-symlink-p "foo") ++ @result{} nil ++@end group ++@group ++(file-symlink-p "sym-link") ++ @result{} "foo" ++@end group ++@group ++(file-symlink-p "sym-link2") ++ @result{} "sym-link" ++@end group ++@group ++(file-symlink-p "/bin") ++ @result{} "/pub/bin" ++@end group ++@end example ++ ++@c !!! file-symlink-p: should show output of ls -l for comparison ++@end defun ++ ++The next two functions recursively follow symbolic links at ++all levels for @var{filename}. ++ ++@defun file-directory-p filename ++This function returns @code{t} if @var{filename} is the name of an ++existing directory, @code{nil} otherwise. ++ ++@example ++@group ++(file-directory-p "~rms") ++ @result{} t ++@end group ++@group ++(file-directory-p "~rms/lewis/files.texi") ++ @result{} nil ++@end group ++@group ++(file-directory-p "~rms/lewis/no-such-file") ++ @result{} nil ++@end group ++@group ++(file-directory-p "$HOME") ++ @result{} nil ++@end group ++@group ++(file-directory-p ++ (substitute-in-file-name "$HOME")) ++ @result{} t ++@end group ++@end example ++@end defun ++ ++@defun file-regular-p filename ++This function returns @code{t} if the file @var{filename} exists and is ++a regular file (not a directory, named pipe, terminal, or ++other I/O device). ++@end defun ++ ++@node Truenames ++@subsection Truenames ++@cindex truename (of file) ++ ++@c Emacs 19 features ++ The @dfn{truename} of a file is the name that you get by following ++symbolic links at all levels until none remain, then simplifying away ++@samp{.}@: and @samp{..}@: appearing as name components. This results ++in a sort of canonical name for the file. A file does not always have a ++unique truename; the number of distinct truenames a file has is equal to ++the number of hard links to the file. However, truenames are useful ++because they eliminate symbolic links as a cause of name variation. ++ ++@defun file-truename filename ++The function @code{file-truename} returns the truename of the file ++@var{filename}. The argument must be an absolute file name. ++ ++This function does not expand environment variables. Only ++@code{substitute-in-file-name} does that. @xref{Definition of ++substitute-in-file-name}. ++ ++If you may need to follow symbolic links preceding @samp{..}@: ++appearing as a name component, you should make sure to call ++@code{file-truename} without prior direct or indirect calls to ++@code{expand-file-name}, as otherwise the file name component ++immediately preceding @samp{..} will be ``simplified away'' before ++@code{file-truename} is called. To eliminate the need for a call to ++@code{expand-file-name}, @code{file-truename} handles @samp{~} in the ++same way that @code{expand-file-name} does. @xref{File Name ++Expansion,, Functions that Expand Filenames}. ++@end defun ++ ++@defun file-chase-links filename &optional limit ++This function follows symbolic links, starting with @var{filename}, ++until it finds a file name which is not the name of a symbolic link. ++Then it returns that file name. This function does @emph{not} follow ++symbolic links at the level of parent directories. ++ ++If you specify a number for @var{limit}, then after chasing through ++that many links, the function just returns what it has even if that is ++still a symbolic link. ++@end defun ++ ++ To illustrate the difference between @code{file-chase-links} and ++@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to ++the directory @file{/home/foo}, and @file{/home/foo/hello} is an ++ordinary file (or at least, not a symbolic link) or nonexistent. Then ++we would have: ++ ++@example ++(file-chase-links "/usr/foo/hello") ++ ;; @r{This does not follow the links in the parent directories.} ++ @result{} "/usr/foo/hello" ++(file-truename "/usr/foo/hello") ++ ;; @r{Assuming that @file{/home} is not a symbolic link.} ++ @result{} "/home/foo/hello" ++@end example ++ ++ @xref{Buffer File Name}, for related information. ++ ++@node File Attributes ++@comment node-name, next, previous, up ++@subsection Other Information about Files ++ ++ This section describes the functions for getting detailed information ++about a file, other than its contents. This information includes the ++mode bits that control access permission, the owner and group numbers, ++the number of names, the inode number, the size, and the times of access ++and modification. ++ ++@defun file-modes filename ++@cindex permission ++@cindex file attributes ++This function returns the mode bits of @var{filename}, as an integer. ++The mode bits are also called the file permissions, and they specify ++access control in the usual Unix fashion. If the low-order bit is 1, ++then the file is executable by all users, if the second-lowest-order bit ++is 1, then the file is writable by all users, etc. ++ ++The highest value returnable is 4095 (7777 octal), meaning that ++everyone has read, write, and execute permission, that the @acronym{SUID} bit ++is set for both others and group, and that the sticky bit is set. ++ ++If @var{filename} does not exist, @code{file-modes} returns @code{nil}. ++ ++This function recursively follows symbolic links at all levels. ++ ++@example ++@group ++(file-modes "~/junk/diffs") ++ @result{} 492 ; @r{Decimal integer.} ++@end group ++@group ++(format "%o" 492) ++ @result{} "754" ; @r{Convert to octal.} ++@end group ++ ++@group ++(set-file-modes "~/junk/diffs" 438) ++ @result{} nil ++@end group ++ ++@group ++(format "%o" 438) ++ @result{} "666" ; @r{Convert to octal.} ++@end group ++ ++@group ++% ls -l diffs ++ -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs ++@end group ++@end example ++@end defun ++ ++If the @var{filename} argument to the next two functions is a symbolic ++link, then these function do @emph{not} replace it with its target. ++However, they both recursively follow symbolic links at all levels of ++parent directories. ++ ++@defun file-nlinks filename ++This functions returns the number of names (i.e., hard links) that ++file @var{filename} has. If the file does not exist, then this function ++returns @code{nil}. Note that symbolic links have no effect on this ++function, because they are not considered to be names of the files they ++link to. ++ ++@example ++@group ++% ls -l foo* ++-rw-rw-rw- 2 rms 4 Aug 19 01:27 foo ++-rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 ++@end group ++ ++@group ++(file-nlinks "foo") ++ @result{} 2 ++@end group ++@group ++(file-nlinks "doesnt-exist") ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun file-attributes filename &optional id-format ++@anchor{Definition of file-attributes} ++This function returns a list of attributes of file @var{filename}. If ++the specified file cannot be opened, it returns @code{nil}. ++The optional parameter @var{id-format} specifies the preferred format ++of attributes @acronym{UID} and @acronym{GID} (see below)---the ++valid values are @code{'string} and @code{'integer}. The latter is ++the default, but we plan to change that, so you should specify a ++non-@code{nil} value for @var{id-format} if you use the returned ++@acronym{UID} or @acronym{GID}. ++ ++The elements of the list, in order, are: ++ ++@enumerate 0 ++@item ++@code{t} for a directory, a string for a symbolic link (the name ++linked to), or @code{nil} for a text file. ++ ++@c Wordy so as to prevent an overfull hbox. --rjc 15mar92 ++@item ++The number of names the file has. Alternate names, also known as hard ++links, can be created by using the @code{add-name-to-file} function ++(@pxref{Changing Files}). ++ ++@item ++The file's @acronym{UID}, normally as a string. However, if it does ++not correspond to a named user, the value is an integer or a floating ++point number. ++ ++@item ++The file's @acronym{GID}, likewise. ++ ++@item ++The time of last access, as a list of two integers. ++The first integer has the high-order 16 bits of time, ++the second has the low 16 bits. (This is similar to the ++value of @code{current-time}; see @ref{Time of Day}.) ++ ++@item ++The time of last modification as a list of two integers (as above). ++@cindex modification time of file ++ ++@item ++The time of last status change as a list of two integers (as above). ++ ++@item ++The size of the file in bytes. If the size is too large to fit in a ++Lisp integer, this is a floating point number. ++ ++@item ++The file's modes, as a string of ten letters or dashes, ++as in @samp{ls -l}. ++ ++@item ++@code{t} if the file's @acronym{GID} would change if file were ++deleted and recreated; @code{nil} otherwise. ++ ++@item ++The file's inode number. If possible, this is an integer. If the inode ++number is too large to be represented as an integer in Emacs Lisp, then ++the value has the form @code{(@var{high} . @var{low})}, where @var{low} ++holds the low 16 bits. ++ ++@item ++The file system number of the file system that the file is in. ++Depending on the magnitude of the value, this can be either an integer ++or a cons cell, in the same manner as the inode number. This element ++and the file's inode number together give enough information to ++distinguish any two files on the system---no two files can have the same ++values for both of these numbers. ++@end enumerate ++ ++For example, here are the file attributes for @file{files.texi}: ++ ++@example ++@group ++(file-attributes "files.texi" 'string) ++ @result{} (nil 1 "lh" "users" ++ (8489 20284) ++ (8489 20284) ++ (8489 20285) ++ 14906 "-rw-rw-rw-" ++ nil 129500 -32252) ++@end group ++@end example ++ ++@noindent ++and here is how the result is interpreted: ++ ++@table @code ++@item nil ++is neither a directory nor a symbolic link. ++ ++@item 1 ++has only one name (the name @file{files.texi} in the current default ++directory). ++ ++@item "lh" ++is owned by the user with name "lh". ++ ++@item "users" ++is in the group with name "users". ++ ++@item (8489 20284) ++was last accessed on Aug 19 00:09. ++ ++@item (8489 20284) ++was last modified on Aug 19 00:09. ++ ++@item (8489 20285) ++last had its inode changed on Aug 19 00:09. ++ ++@item 14906 ++is 14906 bytes long. (It may not contain 14906 characters, though, ++if some of the bytes belong to multibyte sequences.) ++ ++@item "-rw-rw-rw-" ++has a mode of read and write access for the owner, group, and world. ++ ++@item nil ++would retain the same @acronym{GID} if it were recreated. ++ ++@item 129500 ++has an inode number of 129500. ++@item -32252 ++is on file system number -32252. ++@end table ++@end defun ++ ++@cindex MS-DOS and file modes ++@cindex file modes and MS-DOS ++ On MS-DOS, there is no such thing as an ``executable'' file mode bit. ++So Emacs considers a file executable if its name ends in one of the ++standard executable extensions, such as @file{.com}, @file{.bat}, ++@file{.exe}, and some others. Files that begin with the Unix-standard ++@samp{#!} signature, such as shell and Perl scripts, are also considered ++as executable files. This is reflected in the values returned by ++@code{file-modes} and @code{file-attributes}. Directories are also ++reported with executable bit set, for compatibility with Unix. ++ ++@node Locating Files ++@subsection How to Locate Files in Standard Places ++@cindex locate file in path ++@cindex find file in path ++ ++ This section explains how to search for a file in a list of ++directories (a @dfn{path}). One example is when you need to look for ++a program's executable file, e.g., to find out whether a given program ++is installed on the user's system. Another example is the search for ++Lisp libraries (@pxref{Library Search}). Such searches generally need ++to try various possible file name extensions, in addition to various ++possible directories. Emacs provides a function for such a ++generalized search for a file. ++ ++@defun locate-file filename path &optional suffixes predicate ++This function searches for a file whose name is @var{filename} in a ++list of directories given by @var{path}, trying the suffixes in ++@var{suffixes}. If it finds such a file, it returns the full ++@dfn{absolute file name} of the file (@pxref{Relative File Names}); ++otherwise it returns @code{nil}. ++ ++The optional argument @var{suffixes} gives the list of file-name ++suffixes to append to @var{filename} when searching. ++@code{locate-file} tries each possible directory with each of these ++suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there ++are no suffixes, and @var{filename} is used only as-is. Typical ++values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess ++Creation, exec-suffixes}), @code{load-suffixes}, ++@code{load-file-rep-suffixes} and the return value of the function ++@code{get-load-suffixes} (@pxref{Load Suffixes}). ++ ++Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess ++Creation, exec-path}) when looking for executable programs or ++@code{load-path} (@pxref{Library Search, load-path}) when looking for ++Lisp files. If @var{filename} is absolute, @var{path} has no effect, ++but the suffixes in @var{suffixes} are still tried. ++ ++The optional argument @var{predicate}, if non-@code{nil}, specifies ++the predicate function to use for testing whether a candidate file is ++suitable. The predicate function is passed the candidate file name as ++its single argument. If @var{predicate} is @code{nil} or unspecified, ++@code{locate-file} uses @code{file-readable-p} as the default ++predicate. Useful non-default predicates include ++@code{file-executable-p}, @code{file-directory-p}, and other ++predicates described in @ref{Kinds of Files}. ++ ++For compatibility, @var{predicate} can also be one of the symbols ++@code{executable}, @code{readable}, @code{writable}, @code{exists}, or ++a list of one or more of these symbols. ++@end defun ++ ++@defun executable-find program ++This function searches for the executable file of the named ++@var{program} and returns the full absolute name of the executable, ++including its file-name extensions, if any. It returns @code{nil} if ++the file is not found. The functions searches in all the directories ++in @code{exec-path} and tries all the file-name extensions in ++@code{exec-suffixes}. ++@end defun ++ ++@node Changing Files ++@section Changing File Names and Attributes ++@c @cindex renaming files Duplicates rename-file ++@cindex copying files ++@cindex deleting files ++@cindex linking files ++@cindex setting modes of files ++ ++ The functions in this section rename, copy, delete, link, and set the ++modes of files. ++ ++ In the functions that have an argument @var{newname}, if a file by the ++name of @var{newname} already exists, the actions taken depend on the ++value of the argument @var{ok-if-already-exists}: ++ ++@itemize @bullet ++@item ++Signal a @code{file-already-exists} error if ++@var{ok-if-already-exists} is @code{nil}. ++ ++@item ++Request confirmation if @var{ok-if-already-exists} is a number. ++ ++@item ++Replace the old file without confirmation if @var{ok-if-already-exists} ++is any other value. ++@end itemize ++ ++The next four commands all recursively follow symbolic links at all ++levels of parent directories for their first argument, but, if that ++argument is itself a symbolic link, then only @code{copy-file} ++replaces it with its (recursive) target. ++ ++@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists ++@cindex file with multiple names ++@cindex file hard link ++This function gives the file named @var{oldname} the additional name ++@var{newname}. This means that @var{newname} becomes a new ``hard ++link'' to @var{oldname}. ++ ++In the first part of the following example, we list two files, ++@file{foo} and @file{foo3}. ++ ++@example ++@group ++% ls -li fo* ++81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo ++84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 ++@end group ++@end example ++ ++Now we create a hard link, by calling @code{add-name-to-file}, then list ++the files again. This shows two names for one file, @file{foo} and ++@file{foo2}. ++ ++@example ++@group ++(add-name-to-file "foo" "foo2") ++ @result{} nil ++@end group ++ ++@group ++% ls -li fo* ++81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo ++81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 ++84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 ++@end group ++@end example ++ ++Finally, we evaluate the following: ++ ++@example ++(add-name-to-file "foo" "foo3" t) ++@end example ++ ++@noindent ++and list the files again. Now there are three names ++for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old ++contents of @file{foo3} are lost. ++ ++@example ++@group ++(add-name-to-file "foo1" "foo3") ++ @result{} nil ++@end group ++ ++@group ++% ls -li fo* ++81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo ++81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 ++81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 ++@end group ++@end example ++ ++This function is meaningless on operating systems where multiple names ++for one file are not allowed. Some systems implement multiple names ++by copying the file instead. ++ ++See also @code{file-nlinks} in @ref{File Attributes}. ++@end deffn ++ ++@deffn Command rename-file filename newname &optional ok-if-already-exists ++This command renames the file @var{filename} as @var{newname}. ++ ++If @var{filename} has additional names aside from @var{filename}, it ++continues to have those names. In fact, adding the name @var{newname} ++with @code{add-name-to-file} and then deleting @var{filename} has the ++same effect as renaming, aside from momentary intermediate states. ++@end deffn ++ ++@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid ++This command copies the file @var{oldname} to @var{newname}. An ++error is signaled if @var{oldname} does not exist. If @var{newname} ++names a directory, it copies @var{oldname} into that directory, ++preserving its final name component. ++ ++If @var{time} is non-@code{nil}, then this function gives the new file ++the same last-modified time that the old one has. (This works on only ++some operating systems.) If setting the time gets an error, ++@code{copy-file} signals a @code{file-date-error} error. In an ++interactive call, a prefix argument specifies a non-@code{nil} value ++for @var{time}. ++ ++This function copies the file modes, too. ++ ++If argument @var{preserve-uid-gid} is @code{nil}, we let the operating ++system decide the user and group ownership of the new file (this is ++usually set to the user running Emacs). If @var{preserve-uid-gid} is ++non-@code{nil}, we attempt to copy the user and group ownership of the ++file. This works only on some operating systems, and only if you have ++the correct permissions to do so. ++@end deffn ++ ++@deffn Command make-symbolic-link filename newname &optional ok-if-exists ++@pindex ln ++@kindex file-already-exists ++This command makes a symbolic link to @var{filename}, named ++@var{newname}. This is like the shell command @samp{ln -s ++@var{filename} @var{newname}}. ++ ++This function is not available on systems that don't support symbolic ++links. ++@end deffn ++ ++@deffn Command delete-file filename ++@pindex rm ++This command deletes the file @var{filename}, like the shell command ++@samp{rm @var{filename}}. If the file has multiple names, it continues ++to exist under the other names. ++ ++A suitable kind of @code{file-error} error is signaled if the file does ++not exist, or is not deletable. (On Unix and GNU/Linux, a file is ++deletable if its directory is writable.) ++ ++If @var{filename} is a symbolic link, @code{delete-file} does not ++replace it with its target, but it does follow symbolic links at all ++levels of parent directories. ++ ++See also @code{delete-directory} in @ref{Create/Delete Dirs}. ++@end deffn ++ ++@deffn Command set-file-modes filename mode ++This function sets mode bits of @var{filename} to @var{mode} (which ++must be an integer when the function is called non-interactively). ++Only the low 12 bits of @var{mode} are used. ++ ++Interactively, @var{mode} is read from the minibuffer using ++@code{read-file-modes}, which accepts mode bits either as a number or ++as a character string representing the mode bits symbolically. See ++the description of @code{read-file-modes} below for the supported ++forms of symbolic notation for mode bits. ++ ++This function recursively follows symbolic links at all levels for ++@var{filename}. ++@end deffn ++ ++@c Emacs 19 feature ++@defun set-default-file-modes mode ++@cindex umask ++This function sets the default file protection for new files created by ++Emacs and its subprocesses. Every file created with Emacs initially has ++this protection, or a subset of it (@code{write-region} will not give a ++file execute permission even if the default file protection allows ++execute permission). On Unix and GNU/Linux, the default protection is ++the bitwise complement of the ``umask'' value. ++ ++The argument @var{mode} must be an integer. On most systems, only the ++low 9 bits of @var{mode} are meaningful. You can use the Lisp construct ++for octal character codes to enter @var{mode}; for example, ++ ++@example ++(set-default-file-modes ?\644) ++@end example ++ ++Saving a modified version of an existing file does not count as creating ++the file; it preserves the existing file's mode, whatever that is. So ++the default file protection has no effect. ++@end defun ++ ++@defun default-file-modes ++This function returns the current default protection value. ++@end defun ++ ++@defun read-file-modes &optional prompt base-file ++This function reads file mode bits from the minibuffer. The optional ++argument @var{prompt} specifies a non-default prompt. Second optional ++argument @var{base-file} is the name of a file on whose permissions to ++base the mode bits that this function returns, if what the user types ++specifies mode bits relative to permissions of an existing file. ++ ++If user input represents an octal number, this function returns that ++number. If it is a complete symbolic specification of mode bits, as ++in @code{"u=rwx"}, the function converts it to the equivalent numeric ++value using @code{file-modes-symbolic-to-number} and returns the ++result. If the specification is relative, as in @code{"o+g"}, then ++the permissions on which the specification is based are taken from the ++mode bits of @var{base-file}. If @var{base-file} is omitted or ++@code{nil}, the function uses @code{0} as the base mode bits. The ++complete and relative specifications can be combined, as in ++@code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The ++@sc{gnu} @code{Coreutils} Manual}, for detailed description of ++symbolic mode bits specifications. ++@end defun ++ ++@defun file-modes-symbolic-to-number modes &optional base-modes ++This subroutine converts a symbolic specification of file mode bits in ++@var{modes} into the equivalent numeric value. If the symbolic ++specification is based on an existing file, that file's mode bits are ++taken from the optional argument @var{base-modes}; if that argument is ++omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at ++all. ++@end defun ++ ++@defun set-file-times filename &optional time ++This function sets the access and modification times of @var{filename} ++to @var{time}. The return value is @code{t} if the times are successfully ++set, otherwise it is @code{nil}. @var{time} defaults to the current ++time and must be in the format returned by @code{current-time} ++(@pxref{Time of Day}). ++@end defun ++ ++@node File Names ++@section File Names ++@cindex file names ++ ++ Files are generally referred to by their names, in Emacs as elsewhere. ++File names in Emacs are represented as strings. The functions that ++operate on a file all expect a file name argument. ++ ++ In addition to operating on files themselves, Emacs Lisp programs ++often need to operate on file names; i.e., to take them apart and to use ++part of a name to construct related file names. This section describes ++how to manipulate file names. ++ ++ The functions in this section do not actually access files, so they ++can operate on file names that do not refer to an existing file or ++directory. ++ ++ On MS-DOS and MS-Windows, these functions (like the function that ++actually operate on files) accept MS-DOS or MS-Windows file-name syntax, ++where backslashes separate the components, as well as Unix syntax; but ++they always return Unix syntax. This enables Lisp programs to specify ++file names in Unix syntax and work properly on all systems without ++change. ++ ++@menu ++* File Name Components:: The directory part of a file name, and the rest. ++* Relative File Names:: Some file names are relative to a current directory. ++* Directory Names:: A directory's name as a directory ++ is different from its name as a file. ++* File Name Expansion:: Converting relative file names to absolute ones. ++* Unique File Names:: Generating names for temporary files. ++* File Name Completion:: Finding the completions for a given file name. ++* Standard File Names:: If your package uses a fixed file name, ++ how to handle various operating systems simply. ++@end menu ++ ++@node File Name Components ++@subsection File Name Components ++@cindex directory part (of file name) ++@cindex nondirectory part (of file name) ++@cindex version number (in file name) ++ ++ The operating system groups files into directories. To specify a ++file, you must specify the directory and the file's name within that ++directory. Therefore, Emacs considers a file name as having two main ++parts: the @dfn{directory name} part, and the @dfn{nondirectory} part ++(or @dfn{file name within the directory}). Either part may be empty. ++Concatenating these two parts reproduces the original file name. ++ ++ On most systems, the directory part is everything up to and including ++the last slash (backslash is also allowed in input on MS-DOS or ++MS-Windows); the nondirectory part is the rest. ++ ++ For some purposes, the nondirectory part is further subdivided into ++the name proper and the @dfn{version number}. On most systems, only ++backup files have version numbers in their names. ++ ++@defun file-name-directory filename ++This function returns the directory part of @var{filename}, as a ++directory name (@pxref{Directory Names}), or @code{nil} if ++@var{filename} does not include a directory part. ++ ++On GNU and Unix systems, a string returned by this function always ++ends in a slash. On MS-DOS it can also end in a colon. ++ ++@example ++@group ++(file-name-directory "lewis/foo") ; @r{Unix example} ++ @result{} "lewis/" ++@end group ++@group ++(file-name-directory "foo") ; @r{Unix example} ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun file-name-nondirectory filename ++This function returns the nondirectory part of @var{filename}. ++ ++@example ++@group ++(file-name-nondirectory "lewis/foo") ++ @result{} "foo" ++@end group ++@group ++(file-name-nondirectory "foo") ++ @result{} "foo" ++@end group ++@group ++(file-name-nondirectory "lewis/") ++ @result{} "" ++@end group ++@end example ++@end defun ++ ++@defun file-name-sans-versions filename &optional keep-backup-version ++This function returns @var{filename} with any file version numbers, ++backup version numbers, or trailing tildes discarded. ++ ++If @var{keep-backup-version} is non-@code{nil}, then true file version ++numbers understood as such by the file system are discarded from the ++return value, but backup version numbers are kept. ++ ++@example ++@group ++(file-name-sans-versions "~rms/foo.~1~") ++ @result{} "~rms/foo" ++@end group ++@group ++(file-name-sans-versions "~rms/foo~") ++ @result{} "~rms/foo" ++@end group ++@group ++(file-name-sans-versions "~rms/foo") ++ @result{} "~rms/foo" ++@end group ++@end example ++@end defun ++ ++@defun file-name-extension filename &optional period ++This function returns @var{filename}'s final ``extension,'' if any, ++after applying @code{file-name-sans-versions} to remove any ++version/backup part. The extension, in a file name, is the part that ++follows the last @samp{.} in the last name component (minus any ++version/backup part). ++ ++This function returns @code{nil} for extensionless file names such as ++@file{foo}. It returns @code{""} for null extensions, as in ++@file{foo.}. If the last component of a file name begins with a ++@samp{.}, that @samp{.} doesn't count as the beginning of an ++extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not ++@samp{.emacs}. ++ ++If @var{period} is non-@code{nil}, then the returned value includes ++the period that delimits the extension, and if @var{filename} has no ++extension, the value is @code{""}. ++@end defun ++ ++@defun file-name-sans-extension filename ++This function returns @var{filename} minus its extension, if any. The ++version/backup part, if present, is only removed if the file has an ++extension. For example, ++ ++@example ++(file-name-sans-extension "foo.lose.c") ++ @result{} "foo.lose" ++(file-name-sans-extension "big.hack/foo") ++ @result{} "big.hack/foo" ++(file-name-sans-extension "/my/home/.emacs") ++ @result{} "/my/home/.emacs" ++(file-name-sans-extension "/my/home/.emacs.el") ++ @result{} "/my/home/.emacs" ++(file-name-sans-extension "~/foo.el.~3~") ++ @result{} "~/foo" ++(file-name-sans-extension "~/foo.~3~") ++ @result{} "~/foo.~3~" ++@end example ++ ++Note that the @samp{.~3~} in the two last examples is the backup part, ++not an extension. ++@end defun ++ ++@ignore ++Andrew Innes says that this ++ ++@c @defvar directory-sep-char ++This variable holds the character that Emacs normally uses to separate ++file name components. The default value is @code{?/}, but on MS-Windows ++you can set it to @code{?\\}; then the functions that transform file names ++use backslashes in their output. ++ ++File names using backslashes work as input to Lisp primitives even on ++MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default ++value of @code{?/}. ++@end defvar ++@end ignore ++ ++@node Relative File Names ++@subsection Absolute and Relative File Names ++@cindex absolute file name ++@cindex relative file name ++ ++ All the directories in the file system form a tree starting at the ++root directory. A file name can specify all the directory names ++starting from the root of the tree; then it is called an @dfn{absolute} ++file name. Or it can specify the position of the file in the tree ++relative to a default directory; then it is called a @dfn{relative} file ++name. On Unix and GNU/Linux, an absolute file name starts with a slash ++or a tilde (@samp{~}), and a relative one does not. On MS-DOS and ++MS-Windows, an absolute file name starts with a slash or a backslash, or ++with a drive specification @samp{@var{x}:/}, where @var{x} is the ++@dfn{drive letter}. ++ ++@defun file-name-absolute-p filename ++This function returns @code{t} if file @var{filename} is an absolute ++file name, @code{nil} otherwise. ++ ++@example ++@group ++(file-name-absolute-p "~rms/foo") ++ @result{} t ++@end group ++@group ++(file-name-absolute-p "rms/foo") ++ @result{} nil ++@end group ++@group ++(file-name-absolute-p "/user/rms/foo") ++ @result{} t ++@end group ++@end example ++@end defun ++ ++ Given a possibly relative file name, you can convert it to an ++absolute name using @code{expand-file-name} (@pxref{File Name ++Expansion}). This function converts absolute file names to relative ++names: ++ ++@defun file-relative-name filename &optional directory ++This function tries to return a relative name that is equivalent to ++@var{filename}, assuming the result will be interpreted relative to ++@var{directory} (an absolute directory name or directory file name). ++If @var{directory} is omitted or @code{nil}, it defaults to the ++current buffer's default directory. ++ ++On some operating systems, an absolute file name begins with a device ++name. On such systems, @var{filename} has no relative equivalent based ++on @var{directory} if they start with two different device names. In ++this case, @code{file-relative-name} returns @var{filename} in absolute ++form. ++ ++@example ++(file-relative-name "/foo/bar" "/foo/") ++ @result{} "bar" ++(file-relative-name "/foo/bar" "/hack/") ++ @result{} "../foo/bar" ++@end example ++@end defun ++ ++@node Directory Names ++@comment node-name, next, previous, up ++@subsection Directory Names ++@cindex directory name ++@cindex file name of directory ++ ++ A @dfn{directory name} is the name of a directory. A directory is ++actually a kind of file, so it has a file name, which is related to ++the directory name but not identical to it. (This is not quite the ++same as the usual Unix terminology.) These two different names for ++the same entity are related by a syntactic transformation. On GNU and ++Unix systems, this is simple: a directory name ends in a slash, ++whereas the directory's name as a file lacks that slash. On MS-DOS ++the relationship is more complicated. ++ ++ The difference between a directory name and its name as a file is ++subtle but crucial. When an Emacs variable or function argument is ++described as being a directory name, a file name of a directory is not ++acceptable. When @code{file-name-directory} returns a string, that is ++always a directory name. ++ ++ The following two functions convert between directory names and file ++names. They do nothing special with environment variable substitutions ++such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}. ++ ++@defun file-name-as-directory filename ++This function returns a string representing @var{filename} in a form ++that the operating system will interpret as the name of a directory. On ++most systems, this means appending a slash to the string (if it does not ++already end in one). ++ ++@example ++@group ++(file-name-as-directory "~rms/lewis") ++ @result{} "~rms/lewis/" ++@end group ++@end example ++@end defun ++ ++@defun directory-file-name dirname ++This function returns a string representing @var{dirname} in a form that ++the operating system will interpret as the name of a file. On most ++systems, this means removing the final slash (or backslash) from the ++string. ++ ++@example ++@group ++(directory-file-name "~lewis/") ++ @result{} "~lewis" ++@end group ++@end example ++@end defun ++ ++ Given a directory name, you can combine it with a relative file name ++using @code{concat}: ++ ++@example ++(concat @var{dirname} @var{relfile}) ++@end example ++ ++@noindent ++Be sure to verify that the file name is relative before doing that. ++If you use an absolute file name, the results could be syntactically ++invalid or refer to the wrong file. ++ ++ If you want to use a directory file name in making such a ++combination, you must first convert it to a directory name using ++@code{file-name-as-directory}: ++ ++@example ++(concat (file-name-as-directory @var{dirfile}) @var{relfile}) ++@end example ++ ++@noindent ++Don't try concatenating a slash by hand, as in ++ ++@example ++;;; @r{Wrong!} ++(concat @var{dirfile} "/" @var{relfile}) ++@end example ++ ++@noindent ++because this is not portable. Always use ++@code{file-name-as-directory}. ++ ++@cindex directory name abbreviation ++ Directory name abbreviations are useful for directories that are ++normally accessed through symbolic links. Sometimes the users recognize ++primarily the link's name as ``the name'' of the directory, and find it ++annoying to see the directory's ``real'' name. If you define the link ++name as an abbreviation for the ``real'' name, Emacs shows users the ++abbreviation instead. ++ ++@defopt directory-abbrev-alist ++The variable @code{directory-abbrev-alist} contains an alist of ++abbreviations to use for file directories. Each element has the form ++@code{(@var{from} . @var{to})}, and says to replace @var{from} with ++@var{to} when it appears in a directory name. The @var{from} string is ++actually a regular expression; it should always start with @samp{^}. ++The @var{to} string should be an ordinary absolute directory name. Do ++not use @samp{~} to stand for a home directory in that string. The ++function @code{abbreviate-file-name} performs these substitutions. ++ ++You can set this variable in @file{site-init.el} to describe the ++abbreviations appropriate for your site. ++ ++Here's an example, from a system on which file system @file{/home/fsf} ++and so on are normally accessed through symbolic links named @file{/fsf} ++and so on. ++ ++@example ++(("^/home/fsf" . "/fsf") ++ ("^/home/gp" . "/gp") ++ ("^/home/gd" . "/gd")) ++@end example ++@end defopt ++ ++ To convert a directory name to its abbreviation, use this ++function: ++ ++@defun abbreviate-file-name filename ++@anchor{Definition of abbreviate-file-name} ++This function applies abbreviations from @code{directory-abbrev-alist} ++to its argument, and substitutes @samp{~} for the user's home ++directory. You can use it for directory names and for file names, ++because it recognizes abbreviations even as part of the name. ++@end defun ++ ++@node File Name Expansion ++@subsection Functions that Expand Filenames ++@cindex expansion of file names ++ ++ @dfn{Expansion} of a file name means converting a relative file name ++to an absolute one. Since this is done relative to a default directory, ++you must specify the default directory name as well as the file name to ++be expanded. Expansion also simplifies file names by eliminating ++redundancies such as @file{./} and @file{@var{name}/../}. ++ ++@defun expand-file-name filename &optional directory ++This function converts @var{filename} to an absolute file name. If ++@var{directory} is supplied, it is the default directory to start with ++if @var{filename} is relative. (The value of @var{directory} should ++itself be an absolute directory name or directory file name; it may ++start with @samp{~}.) Otherwise, the current buffer's value of ++@code{default-directory} is used. For example: ++ ++@example ++@group ++(expand-file-name "foo") ++ @result{} "/xcssun/users/rms/lewis/foo" ++@end group ++@group ++(expand-file-name "../foo") ++ @result{} "/xcssun/users/rms/foo" ++@end group ++@group ++(expand-file-name "foo" "/usr/spool/") ++ @result{} "/usr/spool/foo" ++@end group ++@group ++(expand-file-name "$HOME/foo") ++ @result{} "/xcssun/users/rms/lewis/$HOME/foo" ++@end group ++@end example ++ ++If the part of the combined file name before the first slash is ++@samp{~}, it expands to the value of the @env{HOME} environment ++variable (usually your home directory). If the part before the first ++slash is @samp{~@var{user}} and if @var{user} is a valid login name, ++it expands to @var{user}'s home directory. ++ ++Filenames containing @samp{.} or @samp{..} are simplified to their ++canonical form: ++ ++@example ++@group ++(expand-file-name "bar/../foo") ++ @result{} "/xcssun/users/rms/lewis/foo" ++@end group ++@end example ++ ++In some cases, a leading @samp{..} component can remain in the output: ++ ++@example ++@group ++(expand-file-name "../home" "/") ++ @result{} "/../home" ++@end group ++@end example ++ ++@noindent ++This is for the sake of filesystems that have the concept of a ++``superroot'' above the root directory @file{/}. On other filesystems, ++@file{/../} is interpreted exactly the same as @file{/}. ++ ++Note that @code{expand-file-name} does @emph{not} expand environment ++variables; only @code{substitute-in-file-name} does that. ++ ++Note also that @code{expand-file-name} does not follow symbolic links ++at any level. This results in a difference between the way ++@code{file-truename} and @code{expand-file-name} treat @samp{..}. ++Assuming that @samp{/tmp/bar} is a symbolic link to the directory ++@samp{/tmp/foo/bar} we get: ++ ++@example ++@group ++(file-truename "/tmp/bar/../myfile") ++ @result{} "/tmp/foo/myfile" ++@end group ++@group ++(expand-file-name "/tmp/bar/../myfile") ++ @result{} "/tmp/myfile" ++@end group ++@end example ++ ++If you may need to follow symbolic links preceding @samp{..}, you ++should make sure to call @code{file-truename} without prior direct or ++indirect calls to @code{expand-file-name}. @xref{Truenames}. ++@end defun ++ ++@defvar default-directory ++The value of this buffer-local variable is the default directory for the ++current buffer. It should be an absolute directory name; it may start ++with @samp{~}. This variable is buffer-local in every buffer. ++ ++@code{expand-file-name} uses the default directory when its second ++argument is @code{nil}. ++ ++The value is always a string ending with a slash. ++ ++@example ++@group ++default-directory ++ @result{} "/user/lewis/manual/" ++@end group ++@end example ++@end defvar ++ ++@defun substitute-in-file-name filename ++@anchor{Definition of substitute-in-file-name} ++This function replaces environment variable references in ++@var{filename} with the environment variable values. Following ++standard Unix shell syntax, @samp{$} is the prefix to substitute an ++environment variable value. If the input contains @samp{$$}, that is ++converted to @samp{$}; this gives the user a way to ``quote'' a ++@samp{$}. ++ ++The environment variable name is the series of alphanumeric characters ++(including underscores) that follow the @samp{$}. If the character following ++the @samp{$} is a @samp{@{}, then the variable name is everything up to the ++matching @samp{@}}. ++ ++Calling @code{substitute-in-file-name} on output produced by ++@code{substitute-in-file-name} tends to give incorrect results. For ++instance, use of @samp{$$} to quote a single @samp{$} won't work ++properly, and @samp{$} in an environment variable's value could lead ++to repeated substitution. Therefore, programs that call this function ++and put the output where it will be passed to this function need to ++double all @samp{$} characters to prevent subsequent incorrect ++results. ++ ++@c Wordy to avoid overfull hbox. --rjc 15mar92 ++Here we assume that the environment variable @code{HOME}, which holds ++the user's home directory name, has value @samp{/xcssun/users/rms}. ++ ++@example ++@group ++(substitute-in-file-name "$HOME/foo") ++ @result{} "/xcssun/users/rms/foo" ++@end group ++@end example ++ ++After substitution, if a @samp{~} or a @samp{/} appears immediately ++after another @samp{/}, the function discards everything before it (up ++through the immediately preceding @samp{/}). ++ ++@example ++@group ++(substitute-in-file-name "bar/~/foo") ++ @result{} "~/foo" ++@end group ++@group ++(substitute-in-file-name "/usr/local/$HOME/foo") ++ @result{} "/xcssun/users/rms/foo" ++ ;; @r{@file{/usr/local/} has been discarded.} ++@end group ++@end example ++ ++@end defun ++ ++@node Unique File Names ++@subsection Generating Unique File Names ++ ++ Some programs need to write temporary files. Here is the usual way to ++construct a name for such a file: ++ ++@example ++(make-temp-file @var{name-of-application}) ++@end example ++ ++@noindent ++The job of @code{make-temp-file} is to prevent two different users or ++two different jobs from trying to use the exact same file name. ++ ++@defun make-temp-file prefix &optional dir-flag suffix ++This function creates a temporary file and returns its name. Emacs ++creates the temporary file's name by adding to @var{prefix} some ++random characters that are different in each Emacs job. The result is ++guaranteed to be a newly created empty file. On MS-DOS, this function ++can truncate the @var{string} prefix to fit into the 8+3 file-name ++limits. If @var{prefix} is a relative file name, it is expanded ++against @code{temporary-file-directory}. ++ ++@example ++@group ++(make-temp-file "foo") ++ @result{} "/tmp/foo232J6v" ++@end group ++@end example ++ ++When @code{make-temp-file} returns, the file has been created and is ++empty. At that point, you should write the intended contents into the ++file. ++ ++If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an ++empty directory instead of an empty file. It returns the file name, ++not the directory name, of that directory. @xref{Directory Names}. ++ ++If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at ++the end of the file name. ++ ++To prevent conflicts among different libraries running in the same ++Emacs, each Lisp program that uses @code{make-temp-file} should have its ++own @var{prefix}. The number added to the end of @var{prefix} ++distinguishes between the same application running in different Emacs ++jobs. Additional added characters permit a large number of distinct ++names even in one Emacs job. ++@end defun ++ ++ The default directory for temporary files is controlled by the ++variable @code{temporary-file-directory}. This variable gives the user ++a uniform way to specify the directory for all temporary files. Some ++programs use @code{small-temporary-file-directory} instead, if that is ++non-@code{nil}. To use it, you should expand the prefix against ++the proper directory before calling @code{make-temp-file}. ++ ++ In older Emacs versions where @code{make-temp-file} does not exist, ++you should use @code{make-temp-name} instead: ++ ++@example ++(make-temp-name ++ (expand-file-name @var{name-of-application} ++ temporary-file-directory)) ++@end example ++ ++@defun make-temp-name string ++This function generates a string that can be used as a unique file ++name. The name starts with @var{string}, and has several random ++characters appended to it, which are different in each Emacs job. It ++is like @code{make-temp-file} except that it just constructs a name, ++and does not create a file. Another difference is that @var{string} ++should be an absolute file name. On MS-DOS, this function can ++truncate the @var{string} prefix to fit into the 8+3 file-name limits. ++@end defun ++ ++@defopt temporary-file-directory ++@cindex @code{TMPDIR} environment variable ++@cindex @code{TMP} environment variable ++@cindex @code{TEMP} environment variable ++This variable specifies the directory name for creating temporary files. ++Its value should be a directory name (@pxref{Directory Names}), but it ++is good for Lisp programs to cope if the value is a directory's file ++name instead. Using the value as the second argument to ++@code{expand-file-name} is a good way to achieve that. ++ ++The default value is determined in a reasonable way for your operating ++system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP} ++environment variables, with a fall-back to a system-dependent name if ++none of these variables is defined. ++ ++Even if you do not use @code{make-temp-file} to create the temporary ++file, you should still use this variable to decide which directory to ++put the file in. However, if you expect the file to be small, you ++should use @code{small-temporary-file-directory} first if that is ++non-@code{nil}. ++@end defopt ++ ++@defopt small-temporary-file-directory ++This variable specifies the directory name for ++creating certain temporary files, which are likely to be small. ++ ++If you want to write a temporary file which is likely to be small, you ++should compute the directory like this: ++ ++@example ++(make-temp-file ++ (expand-file-name @var{prefix} ++ (or small-temporary-file-directory ++ temporary-file-directory))) ++@end example ++@end defopt ++ ++@node File Name Completion ++@subsection File Name Completion ++@cindex file name completion subroutines ++@cindex completion, file name ++ ++ This section describes low-level subroutines for completing a file ++name. For higher level functions, see @ref{Reading File Names}. ++ ++@defun file-name-all-completions partial-filename directory ++This function returns a list of all possible completions for a file ++whose name starts with @var{partial-filename} in directory ++@var{directory}. The order of the completions is the order of the files ++in the directory, which is unpredictable and conveys no useful ++information. ++ ++The argument @var{partial-filename} must be a file name containing no ++directory part and no slash (or backslash on some systems). The current ++buffer's default directory is prepended to @var{directory}, if ++@var{directory} is not absolute. ++ ++In the following example, suppose that @file{~rms/lewis} is the current ++default directory, and has five files whose names begin with @samp{f}: ++@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and ++@file{file.c.~2~}.@refill ++ ++@example ++@group ++(file-name-all-completions "f" "") ++ @result{} ("foo" "file~" "file.c.~2~" ++ "file.c.~1~" "file.c") ++@end group ++ ++@group ++(file-name-all-completions "fo" "") ++ @result{} ("foo") ++@end group ++@end example ++@end defun ++ ++@defun file-name-completion filename directory &optional predicate ++This function completes the file name @var{filename} in directory ++@var{directory}. It returns the longest prefix common to all file names ++in directory @var{directory} that start with @var{filename}. If ++@var{predicate} is non-@code{nil} then it ignores possible completions ++that don't satisfy @var{predicate}, after calling that function ++with one argument, the expanded absolute file name. ++ ++If only one match exists and @var{filename} matches it exactly, the ++function returns @code{t}. The function returns @code{nil} if directory ++@var{directory} contains no name starting with @var{filename}. ++ ++In the following example, suppose that the current default directory ++has five files whose names begin with @samp{f}: @file{foo}, ++@file{file~}, @file{file.c}, @file{file.c.~1~}, and ++@file{file.c.~2~}.@refill ++ ++@example ++@group ++(file-name-completion "fi" "") ++ @result{} "file" ++@end group ++ ++@group ++(file-name-completion "file.c.~1" "") ++ @result{} "file.c.~1~" ++@end group ++ ++@group ++(file-name-completion "file.c.~1~" "") ++ @result{} t ++@end group ++ ++@group ++(file-name-completion "file.c.~3" "") ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defopt completion-ignored-extensions ++@code{file-name-completion} usually ignores file names that end in any ++string in this list. It does not ignore them when all the possible ++completions end in one of these suffixes. This variable has no effect ++on @code{file-name-all-completions}.@refill ++ ++A typical value might look like this: ++ ++@example ++@group ++completion-ignored-extensions ++ @result{} (".o" ".elc" "~" ".dvi") ++@end group ++@end example ++ ++If an element of @code{completion-ignored-extensions} ends in a slash ++@samp{/}, it signals a directory. The elements which do @emph{not} end ++in a slash will never match a directory; thus, the above value will not ++filter out a directory named @file{foo.elc}. ++@end defopt ++ ++@node Standard File Names ++@subsection Standard File Names ++ ++ Most of the file names used in Lisp programs are entered by the user. ++But occasionally a Lisp program needs to specify a standard file name ++for a particular use---typically, to hold customization information ++about each user. For example, abbrev definitions are stored (by ++default) in the file @file{~/.abbrev_defs}; the @code{completion} ++package stores completions in the file @file{~/.completions}. These are ++two of the many standard file names used by parts of Emacs for certain ++purposes. ++ ++ Various operating systems have their own conventions for valid file ++names and for which file names to use for user profile data. A Lisp ++program which reads a file using a standard file name ought to use, on ++each type of system, a file name suitable for that system. The function ++@code{convert-standard-filename} makes this easy to do. ++ ++@defun convert-standard-filename filename ++This function alters the file name @var{filename} to fit the conventions ++of the operating system in use, and returns the result as a new string. ++@end defun ++ ++ The recommended way to specify a standard file name in a Lisp program ++is to choose a name which fits the conventions of GNU and Unix systems, ++usually with a nondirectory part that starts with a period, and pass it ++to @code{convert-standard-filename} instead of using it directly. Here ++is an example from the @code{completion} package: ++ ++@example ++(defvar save-completions-file-name ++ (convert-standard-filename "~/.completions") ++ "*The file name to save completions to.") ++@end example ++ ++ On GNU and Unix systems, and on some other systems as well, ++@code{convert-standard-filename} returns its argument unchanged. On ++some other systems, it alters the name to fit the system's conventions. ++ ++ For example, on MS-DOS the alterations made by this function include ++converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the ++middle of the name to @samp{.} if there is no other @samp{.}, inserting ++a @samp{.} after eight characters if there is none, and truncating to ++three characters after the @samp{.}. (It makes other changes as well.) ++Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and ++@file{.completions} becomes @file{_complet.ion}. ++ ++@node Contents of Directories ++@section Contents of Directories ++@cindex directory-oriented functions ++@cindex file names in directory ++ ++ A directory is a kind of file that contains other files entered under ++various names. Directories are a feature of the file system. ++ ++ Emacs can list the names of the files in a directory as a Lisp list, ++or display the names in a buffer using the @code{ls} shell command. In ++the latter case, it can optionally display information about each file, ++depending on the options passed to the @code{ls} command. ++ ++@defun directory-files directory &optional full-name match-regexp nosort ++This function returns a list of the names of the files in the directory ++@var{directory}. By default, the list is in alphabetical order. ++ ++If @var{full-name} is non-@code{nil}, the function returns the files' ++absolute file names. Otherwise, it returns the names relative to ++the specified directory. ++ ++If @var{match-regexp} is non-@code{nil}, this function returns only ++those file names that contain a match for that regular expression---the ++other file names are excluded from the list. On case-insensitive ++filesystems, the regular expression matching is case-insensitive. ++ ++@c Emacs 19 feature ++If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort ++the list, so you get the file names in no particular order. Use this if ++you want the utmost possible speed and don't care what order the files ++are processed in. If the order of processing is visible to the user, ++then the user will probably be happier if you do sort the names. ++ ++@example ++@group ++(directory-files "~lewis") ++ @result{} ("#foo#" "#foo.el#" "." ".." ++ "dired-mods.el" "files.texi" ++ "files.texi.~1~") ++@end group ++@end example ++ ++An error is signaled if @var{directory} is not the name of a directory ++that can be read. ++@end defun ++ ++@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format ++This is similar to @code{directory-files} in deciding which files ++to report on and how to report their names. However, instead ++of returning a list of file names, it returns for each file a ++list @code{(@var{filename} . @var{attributes})}, where @var{attributes} ++is what @code{file-attributes} would return for that file. ++The optional argument @var{id-format} has the same meaning as the ++corresponding argument to @code{file-attributes} (@pxref{Definition ++of file-attributes}). ++@end defun ++ ++@defun file-expand-wildcards pattern &optional full ++This function expands the wildcard pattern @var{pattern}, returning ++a list of file names that match it. ++ ++If @var{pattern} is written as an absolute file name, ++the values are absolute also. ++ ++If @var{pattern} is written as a relative file name, it is interpreted ++relative to the current default directory. The file names returned are ++normally also relative to the current default directory. However, if ++@var{full} is non-@code{nil}, they are absolute. ++@end defun ++ ++@defun insert-directory file switches &optional wildcard full-directory-p ++This function inserts (in the current buffer) a directory listing for ++directory @var{file}, formatted with @code{ls} according to ++@var{switches}. It leaves point after the inserted text. ++@var{switches} may be a string of options, or a list of strings ++representing individual options. ++ ++The argument @var{file} may be either a directory name or a file ++specification including wildcard characters. If @var{wildcard} is ++non-@code{nil}, that means treat @var{file} as a file specification with ++wildcards. ++ ++If @var{full-directory-p} is non-@code{nil}, that means the directory ++listing is expected to show the full contents of a directory. You ++should specify @code{t} when @var{file} is a directory and switches do ++not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to ++describe a directory itself as a file, rather than showing its ++contents.) ++ ++On most systems, this function works by running a directory listing ++program whose name is in the variable @code{insert-directory-program}. ++If @var{wildcard} is non-@code{nil}, it also runs the shell specified by ++@code{shell-file-name}, to expand the wildcards. ++ ++MS-DOS and MS-Windows systems usually lack the standard Unix program ++@code{ls}, so this function emulates the standard Unix program @code{ls} ++with Lisp code. ++ ++As a technical detail, when @var{switches} contains the long ++@samp{--dired} option, @code{insert-directory} treats it specially, ++for the sake of dired. However, the normally equivalent short ++@samp{-D} option is just passed on to @code{insert-directory-program}, ++as any other option. ++@end defun ++ ++@defvar insert-directory-program ++This variable's value is the program to run to generate a directory listing ++for the function @code{insert-directory}. It is ignored on systems ++which generate the listing with Lisp code. ++@end defvar ++ ++@node Create/Delete Dirs ++@section Creating and Deleting Directories ++@cindex creating and deleting directories ++@c Emacs 19 features ++ ++ Most Emacs Lisp file-manipulation functions get errors when used on ++files that are directories. For example, you cannot delete a directory ++with @code{delete-file}. These special functions exist to create and ++delete directories. ++ ++@findex mkdir ++@deffn Command make-directory dirname &optional parents ++This command creates a directory named @var{dirname}. If ++@var{parents} is non-@code{nil}, as is always the case in an ++interactive call, that means to create the parent directories first, ++if they don't already exist. ++ ++@code{mkdir} is an alias for this. ++@end deffn ++ ++@deffn Command delete-directory dirname ++This command deletes the directory named @var{dirname}. The function ++@code{delete-file} does not work for files that are directories; you ++must use @code{delete-directory} for them. If the directory contains ++any files, @code{delete-directory} signals an error. ++ ++@code{delete-directory} only follows symbolic links at the level of ++parent directories. ++@end deffn ++ ++@node Magic File Names ++@section Making Certain File Names ``Magic'' ++@cindex magic file names ++ ++@c Emacs 19 feature ++ You can implement special handling for certain file names. This is ++called making those names @dfn{magic}. The principal use for this ++feature is in implementing remote file names (@pxref{Remote Files,, ++Remote Files, emacs, The GNU Emacs Manual}). ++ ++ To define a kind of magic file name, you must supply a regular ++expression to define the class of names (all those that match the ++regular expression), plus a handler that implements all the primitive ++Emacs file operations for file names that do match. ++ ++ The variable @code{file-name-handler-alist} holds a list of handlers, ++together with regular expressions that determine when to apply each ++handler. Each element has this form: ++ ++@example ++(@var{regexp} . @var{handler}) ++@end example ++ ++@noindent ++All the Emacs primitives for file access and file name transformation ++check the given file name against @code{file-name-handler-alist}. If ++the file name matches @var{regexp}, the primitives handle that file by ++calling @var{handler}. ++ ++ The first argument given to @var{handler} is the name of the ++primitive, as a symbol; the remaining arguments are the arguments that ++were passed to that primitive. (The first of these arguments is most ++often the file name itself.) For example, if you do this: ++ ++@example ++(file-exists-p @var{filename}) ++@end example ++ ++@noindent ++and @var{filename} has handler @var{handler}, then @var{handler} is ++called like this: ++ ++@example ++(funcall @var{handler} 'file-exists-p @var{filename}) ++@end example ++ ++ When a function takes two or more arguments that must be file names, ++it checks each of those names for a handler. For example, if you do ++this: ++ ++@example ++(expand-file-name @var{filename} @var{dirname}) ++@end example ++ ++@noindent ++then it checks for a handler for @var{filename} and then for a handler ++for @var{dirname}. In either case, the @var{handler} is called like ++this: ++ ++@example ++(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname}) ++@end example ++ ++@noindent ++The @var{handler} then needs to figure out whether to handle ++@var{filename} or @var{dirname}. ++ ++ If the specified file name matches more than one handler, the one ++whose match starts last in the file name gets precedence. This rule ++is chosen so that handlers for jobs such as uncompression are handled ++first, before handlers for jobs such as remote file access. ++ ++ Here are the operations that a magic file name handler gets to handle: ++ ++@ifnottex ++@noindent ++@code{access-file}, @code{add-name-to-file}, ++@code{byte-compiler-base-file-name},@* ++@code{copy-file}, @code{delete-directory}, ++@code{delete-file}, ++@code{diff-latest-backup-file}, ++@code{directory-file-name}, ++@code{directory-files}, ++@code{directory-files-and-attributes}, ++@code{dired-compress-file}, @code{dired-uncache},@* ++@code{expand-file-name}, ++@code{file-accessible-directory-p}, ++@code{file-attributes}, ++@code{file-directory-p}, ++@code{file-executable-p}, @code{file-exists-p}, ++@code{file-local-copy}, @code{file-remote-p}, ++@code{file-modes}, @code{file-name-all-completions}, ++@code{file-name-as-directory}, ++@code{file-name-completion}, ++@code{file-name-directory}, ++@code{file-name-nondirectory}, ++@code{file-name-sans-versions}, @code{file-newer-than-file-p}, ++@code{file-ownership-preserved-p}, ++@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, ++@code{file-truename}, @code{file-writable-p}, ++@code{find-backup-file-name}, ++@c Not sure why it was here: @code{find-file-noselect},@* ++@code{get-file-buffer}, ++@code{insert-directory}, ++@code{insert-file-contents},@* ++@code{load}, ++@code{make-auto-save-file-name}, ++@code{make-directory}, ++@code{make-directory-internal}, ++@code{make-symbolic-link},@* ++@code{process-file}, ++@code{rename-file}, @code{set-file-modes}, @code{set-file-times}, ++@code{set-visited-file-modtime}, @code{shell-command}, ++@code{start-file-process}, ++@code{substitute-in-file-name},@* ++@code{unhandled-file-name-directory}, ++@code{vc-registered}, ++@code{verify-visited-file-modtime},@* ++@code{write-region}. ++@end ifnottex ++@iftex ++@noindent ++@flushleft ++@code{access-file}, @code{add-name-to-file}, ++@code{byte-com@discretionary{}{}{}piler-base-file-name}, ++@code{copy-file}, @code{delete-directory}, ++@code{delete-file}, ++@code{diff-latest-backup-file}, ++@code{directory-file-name}, ++@code{directory-files}, ++@code{directory-files-and-at@discretionary{}{}{}tributes}, ++@code{dired-compress-file}, @code{dired-uncache}, ++@code{expand-file-name}, ++@code{file-accessible-direc@discretionary{}{}{}tory-p}, ++@code{file-attributes}, ++@code{file-direct@discretionary{}{}{}ory-p}, ++@code{file-executable-p}, @code{file-exists-p}, ++@code{file-local-copy}, @code{file-remote-p}, ++@code{file-modes}, @code{file-name-all-completions}, ++@code{file-name-as-directory}, ++@code{file-name-completion}, ++@code{file-name-directory}, ++@code{file-name-nondirec@discretionary{}{}{}tory}, ++@code{file-name-sans-versions}, @code{file-newer-than-file-p}, ++@code{file-ownership-pre@discretionary{}{}{}served-p}, ++@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, ++@code{file-truename}, @code{file-writable-p}, ++@code{find-backup-file-name}, ++@c Not sure why it was here: @code{find-file-noselect}, ++@code{get-file-buffer}, ++@code{insert-directory}, ++@code{insert-file-contents}, ++@code{load}, @code{make-direc@discretionary{}{}{}tory}, ++@code{make-direc@discretionary{}{}{}tory-internal}, ++@code{make-symbolic-link}, ++@code{process-file}, ++@code{rename-file}, @code{set-file-modes}, ++@code{set-visited-file-modtime}, @code{shell-command}, ++@code{start-file-process}, ++@code{substitute-in-file-name}, ++@code{unhandled-file-name-directory}, ++@code{vc-regis@discretionary{}{}{}tered}, ++@code{verify-visited-file-modtime}, ++@code{write-region}. ++@end flushleft ++@end iftex ++ ++ Handlers for @code{insert-file-contents} typically need to clear the ++buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the ++@var{visit} argument is non-@code{nil}. This also has the effect of ++unlocking the buffer if it is locked. ++ ++ The handler function must handle all of the above operations, and ++possibly others to be added in the future. It need not implement all ++these operations itself---when it has nothing special to do for a ++certain operation, it can reinvoke the primitive, to handle the ++operation ``in the usual way.'' It should always reinvoke the primitive ++for an operation it does not recognize. Here's one way to do this: ++ ++@smallexample ++(defun my-file-handler (operation &rest args) ++ ;; @r{First check for the specific operations} ++ ;; @r{that we have special handling for.} ++ (cond ((eq operation 'insert-file-contents) @dots{}) ++ ((eq operation 'write-region) @dots{}) ++ @dots{} ++ ;; @r{Handle any operation we don't know about.} ++ (t (let ((inhibit-file-name-handlers ++ (cons 'my-file-handler ++ (and (eq inhibit-file-name-operation operation) ++ inhibit-file-name-handlers))) ++ (inhibit-file-name-operation operation)) ++ (apply operation args))))) ++@end smallexample ++ ++ When a handler function decides to call the ordinary Emacs primitive for ++the operation at hand, it needs to prevent the primitive from calling ++the same handler once again, thus leading to an infinite recursion. The ++example above shows how to do this, with the variables ++@code{inhibit-file-name-handlers} and ++@code{inhibit-file-name-operation}. Be careful to use them exactly as ++shown above; the details are crucial for proper behavior in the case of ++multiple handlers, and for operations that have two file names that may ++each have handlers. ++ ++@kindex safe-magic (@r{property}) ++ Handlers that don't really do anything special for actual access to the ++file---such as the ones that implement completion of host names for ++remote file names---should have a non-@code{nil} @code{safe-magic} ++property. For instance, Emacs normally ``protects'' directory names ++it finds in @code{PATH} from becoming magic, if they look like magic ++file names, by prefixing them with @samp{/:}. But if the handler that ++would be used for them has a non-@code{nil} @code{safe-magic} ++property, the @samp{/:} is not added. ++ ++@kindex operations (@r{property}) ++ A file name handler can have an @code{operations} property to ++declare which operations it handles in a nontrivial way. If this ++property has a non-@code{nil} value, it should be a list of ++operations; then only those operations will call the handler. This ++avoids inefficiency, but its main purpose is for autoloaded handler ++functions, so that they won't be loaded except when they have real ++work to do. ++ ++ Simply deferring all operations to the usual primitives does not ++work. For instance, if the file name handler applies to ++@code{file-exists-p}, then it must handle @code{load} itself, because ++the usual @code{load} code won't work properly in that case. However, ++if the handler uses the @code{operations} property to say it doesn't ++handle @code{file-exists-p}, then it need not handle @code{load} ++nontrivially. ++ ++@defvar inhibit-file-name-handlers ++This variable holds a list of handlers whose use is presently inhibited ++for a certain operation. ++@end defvar ++ ++@defvar inhibit-file-name-operation ++The operation for which certain handlers are presently inhibited. ++@end defvar ++ ++@defun find-file-name-handler file operation ++This function returns the handler function for file name @var{file}, ++or @code{nil} if there is none. The argument @var{operation} should ++be the operation to be performed on the file---the value you will pass ++to the handler as its first argument when you call it. If ++@var{operation} equals @code{inhibit-file-name-operation}, or if it is ++not found in the @code{operations} property of the handler, this ++function returns @code{nil}. ++@end defun ++ ++@defun file-local-copy filename ++This function copies file @var{filename} to an ordinary non-magic file ++on the local machine, if it isn't on the local machine already. Magic ++file names should handle the @code{file-local-copy} operation if they ++refer to files on other machines. A magic file name that is used for ++other purposes than remote file access should not handle ++@code{file-local-copy}; then this function will treat the file as ++local. ++ ++If @var{filename} is local, whether magic or not, this function does ++nothing and returns @code{nil}. Otherwise it returns the file name ++of the local copy file. ++@end defun ++ ++@defun file-remote-p filename &optional identification connected ++This function tests whether @var{filename} is a remote file. If ++@var{filename} is local (not remote), the return value is @code{nil}. ++If @var{filename} is indeed remote, the return value is a string that ++identifies the remote system. ++ ++This identifier string can include a host name and a user name, as ++well as characters designating the method used to access the remote ++system. For example, the remote identifier string for the filename ++@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}. ++ ++If @code{file-remote-p} returns the same identifier for two different ++filenames, that means they are stored on the same file system and can ++be accessed locally with respect to each other. This means, for ++example, that it is possible to start a remote process accessing both ++files at the same time. Implementors of file handlers need to ensure ++this principle is valid. ++ ++@var{identification} specifies which part of the identifier shall be ++returned as string. @var{identification} can be the symbol ++@code{method}, @code{user} or @code{host}; any other value is handled ++like @code{nil} and means to return the complete identifier string. ++In the example above, the remote @code{user} identifier string would ++be @code{root}. ++ ++If @var{connected} is non-@code{nil}, this function returns @code{nil} ++even if @var{filename} is remote, if Emacs has no network connection ++to its host. This is useful when you want to avoid the delay of ++making connections when they don't exist. ++@end defun ++ ++@defun unhandled-file-name-directory filename ++This function returns the name of a directory that is not magic. It ++uses the directory part of @var{filename} if that is not magic. For a ++magic file name, it invokes the file name handler, which therefore ++decides what value to return. If @var{filename} is not accessible ++from a local process, then the file name handler should indicate it by ++returning @code{nil}. ++ ++This is useful for running a subprocess; every subprocess must have a ++non-magic directory to serve as its current directory, and this function ++is a good way to come up with one. ++@end defun ++ ++@node Format Conversion ++@section File Format Conversion ++ ++@cindex file format conversion ++@cindex encoding file formats ++@cindex decoding file formats ++@cindex text properties in files ++@cindex saving text properties ++ Emacs performs several steps to convert the data in a buffer (text, ++text properties, and possibly other information) to and from a ++representation suitable for storing into a file. This section describes ++the fundamental functions that perform this @dfn{format conversion}, ++namely @code{insert-file-contents} for reading a file into a buffer, ++and @code{write-region} for writing a buffer into a file. ++ ++@menu ++* Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}. ++* Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}. ++* Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion. ++@end menu ++ ++@node Format Conversion Overview ++@subsection Overview ++@noindent ++The function @code{insert-file-contents}: ++ ++@itemize ++@item initially, inserts bytes from the file into the buffer; ++@item decodes bytes to characters as appropriate; ++@item processes formats as defined by entries in @code{format-alist}; and ++@item calls functions in @code{after-insert-file-functions}. ++@end itemize ++ ++@noindent ++The function @code{write-region}: ++ ++@itemize ++@item initially, calls functions in @code{write-region-annotate-functions}; ++@item processes formats as defined by entries in @code{format-alist}; ++@item encodes characters to bytes as appropriate; and ++@item modifies the file with the bytes. ++@end itemize ++ ++ This shows the symmetry of the lowest-level operations; reading and ++writing handle things in opposite order. The rest of this section ++describes the two facilities surrounding the three variables named ++above, as well as some related functions. @ref{Coding Systems}, for ++details on character encoding and decoding. ++ ++@node Format Conversion Round-Trip ++@subsection Round-Trip Specification ++ ++ The most general of the two facilities is controlled by the variable ++@code{format-alist}, a list of @dfn{file format} specifications, which ++describe textual representations used in files for the data in an Emacs ++buffer. The descriptions for reading and writing are paired, which is ++why we call this ``round-trip'' specification ++(@pxref{Format Conversion Piecemeal}, for non-paired specification). ++ ++@defvar format-alist ++This list contains one format definition for each defined file format. ++Each format definition is a list of this form: ++ ++@example ++(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve}) ++@end example ++@end defvar ++ ++@cindex format definition ++@noindent ++Here is what the elements in a format definition mean: ++ ++@table @var ++@item name ++The name of this format. ++ ++@item doc-string ++A documentation string for the format. ++ ++@item regexp ++A regular expression which is used to recognize files represented in ++this format. ++ ++@item from-fn ++A shell command or function to decode data in this format (to convert ++file data into the usual Emacs data representation). ++ ++A shell command is represented as a string; Emacs runs the command as a ++filter to perform the conversion. ++ ++If @var{from-fn} is a function, it is called with two arguments, @var{begin} ++and @var{end}, which specify the part of the buffer it should convert. ++It should convert the text by editing it in place. Since this can ++change the length of the text, @var{from-fn} should return the modified ++end position. ++ ++One responsibility of @var{from-fn} is to make sure that the beginning ++of the file no longer matches @var{regexp}. Otherwise it is likely to ++get called again. ++ ++@item to-fn ++A shell command or function to encode data in this format---that is, to ++convert the usual Emacs data representation into this format. ++ ++If @var{to-fn} is a string, it is a shell command; Emacs runs the ++command as a filter to perform the conversion. ++ ++If @var{to-fn} is a function, it is called with three arguments: ++@var{begin} and @var{end}, which specify the part of the buffer it ++should convert, and @var{buffer}, which specifies which buffer. There ++are two ways it can do the conversion: ++ ++@itemize @bullet ++@item ++By editing the buffer in place. In this case, @var{to-fn} should ++return the end-position of the range of text, as modified. ++ ++@item ++By returning a list of annotations. This is a list of elements of the ++form @code{(@var{position} . @var{string})}, where @var{position} is an ++integer specifying the relative position in the text to be written, and ++@var{string} is the annotation to add there. The list must be sorted in ++order of position when @var{to-fn} returns it. ++ ++When @code{write-region} actually writes the text from the buffer to the ++file, it intermixes the specified annotations at the corresponding ++positions. All this takes place without modifying the buffer. ++@end itemize ++ ++@item modify ++A flag, @code{t} if the encoding function modifies the buffer, and ++@code{nil} if it works by returning a list of annotations. ++ ++@item mode-fn ++A minor-mode function to call after visiting a file converted from this ++format. The function is called with one argument, the integer 1; ++that tells a minor-mode function to enable the mode. ++ ++@item preserve ++A flag, @code{t} if @code{format-write-file} should not remove this format ++from @code{buffer-file-format}. ++@end table ++ ++The function @code{insert-file-contents} automatically recognizes file ++formats when it reads the specified file. It checks the text of the ++beginning of the file against the regular expressions of the format ++definitions, and if it finds a match, it calls the decoding function for ++that format. Then it checks all the known formats over again. ++It keeps checking them until none of them is applicable. ++ ++Visiting a file, with @code{find-file-noselect} or the commands that use ++it, performs conversion likewise (because it calls ++@code{insert-file-contents}); it also calls the mode function for each ++format that it decodes. It stores a list of the format names in the ++buffer-local variable @code{buffer-file-format}. ++ ++@defvar buffer-file-format ++This variable states the format of the visited file. More precisely, ++this is a list of the file format names that were decoded in the course ++of visiting the current buffer's file. It is always buffer-local in all ++buffers. ++@end defvar ++ ++When @code{write-region} writes data into a file, it first calls the ++encoding functions for the formats listed in @code{buffer-file-format}, ++in the order of appearance in the list. ++ ++@deffn Command format-write-file file format &optional confirm ++This command writes the current buffer contents into the file @var{file} ++in a format based on @var{format}, which is a list of format names. It ++constructs the actual format starting from @var{format}, then appending ++any elements from the value of @code{buffer-file-format} with a non-nil ++@var{preserve} flag (see above), if they are not already present in ++@var{format}. It then updates @code{buffer-file-format} with this ++format, making it the default for future saves. Except for the ++@var{format} argument, this command is similar to @code{write-file}. In ++particular, @var{confirm} has the same meaning and interactive treatment ++as the corresponding argument to @code{write-file}. @xref{Definition of ++write-file}. ++@end deffn ++ ++@deffn Command format-find-file file format ++This command finds the file @var{file}, converting it according to ++format @var{format}. It also makes @var{format} the default if the ++buffer is saved later. ++ ++The argument @var{format} is a list of format names. If @var{format} is ++@code{nil}, no conversion takes place. Interactively, typing just ++@key{RET} for @var{format} specifies @code{nil}. ++@end deffn ++ ++@deffn Command format-insert-file file format &optional beg end ++This command inserts the contents of file @var{file}, converting it ++according to format @var{format}. If @var{beg} and @var{end} are ++non-@code{nil}, they specify which part of the file to read, as in ++@code{insert-file-contents} (@pxref{Reading from Files}). ++ ++The return value is like what @code{insert-file-contents} returns: a ++list of the absolute file name and the length of the data inserted ++(after conversion). ++ ++The argument @var{format} is a list of format names. If @var{format} is ++@code{nil}, no conversion takes place. Interactively, typing just ++@key{RET} for @var{format} specifies @code{nil}. ++@end deffn ++ ++@defvar buffer-auto-save-file-format ++This variable specifies the format to use for auto-saving. Its value is ++a list of format names, just like the value of ++@code{buffer-file-format}; however, it is used instead of ++@code{buffer-file-format} for writing auto-save files. If the value ++is @code{t}, the default, auto-saving uses the same format as a ++regular save in the same buffer. This variable is always buffer-local ++in all buffers. ++@end defvar ++ ++@node Format Conversion Piecemeal ++@subsection Piecemeal Specification ++ ++ In contrast to the round-trip specification described in the previous ++subsection (@pxref{Format Conversion Round-Trip}), you can use the variables ++@code{after-insert-file-functions} and @code{write-region-annotate-functions} ++to separately control the respective reading and writing conversions. ++ ++ Conversion starts with one representation and produces another ++representation. When there is only one conversion to do, there is no ++conflict about what to start with. However, when there are multiple ++conversions involved, conflict may arise when two conversions need to ++start with the same data. ++ ++ This situation is best understood in the context of converting text ++properties during @code{write-region}. For example, the character at ++position 42 in a buffer is @samp{X} with a text property @code{foo}. If ++the conversion for @code{foo} is done by inserting into the buffer, say, ++@samp{FOO:}, then that changes the character at position 42 from ++@samp{X} to @samp{F}. The next conversion will start with the wrong ++data straight away. ++ ++ To avoid conflict, cooperative conversions do not modify the buffer, ++but instead specify @dfn{annotations}, a list of elements of the form ++@code{(@var{position} . @var{string})}, sorted in order of increasing ++@var{position}. ++ ++ If there is more than one conversion, @code{write-region} merges their ++annotations destructively into one sorted list. Later, when the text ++from the buffer is actually written to the file, it intermixes the ++specified annotations at the corresponding positions. All this takes ++place without modifying the buffer. ++ ++@c ??? What about ``overriding'' conversions like those allowed ++@c ??? for `write-region-annotate-functions', below? --ttn ++ ++ In contrast, when reading, the annotations intermixed with the text ++are handled immediately. @code{insert-file-contents} sets point to ++the beginning of some text to be converted, then calls the conversion ++functions with the length of that text. These functions should always ++return with point at the beginning of the inserted text. This ++approach makes sense for reading because annotations removed by the ++first converter can't be mistakenly processed by a later converter. ++Each conversion function should scan for the annotations it ++recognizes, remove the annotation, modify the buffer text (to set a ++text property, for example), and return the updated length of the ++text, as it stands after those changes. The value returned by one ++function becomes the argument to the next function. ++ ++@defvar write-region-annotate-functions ++A list of functions for @code{write-region} to call. Each function in ++the list is called with two arguments: the start and end of the region ++to be written. These functions should not alter the contents of the ++buffer. Instead, they should return annotations. ++ ++As a special case, a function may return with a different buffer ++current. Emacs takes this to mean that the current buffer contains ++altered text to be output. It therefore changes the @var{start} and ++@var{end} arguments of the @code{write-region} call, giving them the ++values of @code{point-min} and @code{point-max} in the new buffer, ++respectively. It also discards all previous annotations, because they ++should have been dealt with by this function. ++@end defvar ++ ++@defvar write-region-post-annotation-function ++The value of this variable, if non-@code{nil}, should be a function. ++This function is called, with no arguments, after @code{write-region} ++has completed. ++ ++If any function in @code{write-region-annotate-functions} returns with ++a different buffer current, Emacs calls ++@code{write-region-post-annotation-function} more than once. Emacs ++calls it with the last buffer that was current, and again with the ++buffer before that, and so on back to the original buffer. ++ ++Thus, a function in @code{write-region-annotate-functions} can create ++a buffer, give this variable the local value of @code{kill-buffer} in ++that buffer, set up the buffer with altered text, and make the buffer ++current. The buffer will be killed after @code{write-region} is done. ++@end defvar ++ ++@defvar after-insert-file-functions ++Each function in this list is called by @code{insert-file-contents} ++with one argument, the number of characters inserted, and with point ++at the beginning of the inserted text. Each function should leave ++point unchanged, and return the new character count describing the ++inserted text as modified by the function. ++@c ??? The docstring mentions a handler from `file-name-handler-alist' ++@c "intercepting" `insert-file-contents'. Hmmm. --ttn ++@end defvar ++ ++ We invite users to write Lisp programs to store and retrieve text ++properties in files, using these hooks, and thus to experiment with ++various data formats and find good ones. Eventually we hope users ++will produce good, general extensions we can install in Emacs. ++ ++ We suggest not trying to handle arbitrary Lisp objects as text property ++names or values---because a program that general is probably difficult ++to write, and slow. Instead, choose a set of possible data types that ++are reasonably flexible, and not too hard to encode. ++ ++@ignore ++ arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c ++@end ignore +diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi +new file mode 100644 +index 0000000..87127c9 +--- /dev/null ++++ b/doc/lispref/frames.texi +@@ -0,0 +1,2406 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/frames ++@node Frames, Positions, Windows, Top ++@chapter Frames ++@cindex frame ++ ++ A @dfn{frame} is a screen object that contains one or more Emacs ++windows (@pxref{Windows}). It is the kind of object called a ++``window'' in the terminology of graphical environments; but we can't ++call it a ``window'' here, because Emacs uses that word in a different ++way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that ++represents a frame on the screen. @xref{Frame Type}. ++ ++ A frame initially contains a single main window and/or a minibuffer ++window; you can subdivide the main window vertically or horizontally ++into smaller windows. @xref{Splitting Windows}. ++ ++@cindex terminal ++ A @dfn{terminal} is a display device capable of displaying one or ++more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp ++object that represents a terminal. @xref{Terminal Type}. ++ ++@cindex terminal frame ++@cindex window frame ++ There are two classes of terminals: text-only terminals and ++graphical terminals. Text-only terminals are non-graphics-capable ++display devices, including ``terminal emulators'' such as xterm. On ++text-only terminals, each frame occupies the entire terminal screen; ++although you can create additional frames and switch between them, ++only one frame can be shown at any given time. We refer to frames on ++text-only terminals as @dfn{terminal frames}. Graphical terminals, on ++the other hand, are graphics-capable windowing systems, such as the X ++Window System. On a graphical terminal, Emacs can display multiple ++frames simultaneously. We refer to such frames as @dfn{window ++frames}. ++ ++ On GNU and Unix systems, you can create additional frames on any ++available terminal, within a single Emacs session, regardless of ++whether Emacs was started on a text-only or graphical terminal. Emacs ++can display on both graphical and text-only terminals simultaneously. ++This comes in handy, for instance, when you connect to the same ++session from several remote locations. @xref{Multiple Terminals}. ++ ++@defun framep object ++This predicate returns a non-@code{nil} value if @var{object} is a ++frame, and @code{nil} otherwise. For a frame, the value indicates which ++kind of display the frame uses: ++ ++@table @code ++@item x ++The frame is displayed in an X window. ++@item t ++A terminal frame on a character display. ++@item w32 ++The frame is displayed on MS-Windows 9X/NT. ++@item ns ++The frame is displayed on a GNUstep or Macintosh Cocoa display. ++@item pc ++The frame is displayed on an MS-DOS terminal. ++@end table ++@end defun ++ ++@defun frame-terminal &optional frame ++This function returns the terminal object that displays @var{frame}. ++If @var{frame} is @code{nil} or unspecified, it defaults to the ++selected frame. ++@end defun ++ ++@defun terminal-live-p object ++This predicate returns a non-@code{nil} value if @var{object} is a ++terminal that is alive (i.e.@: was not deleted), and @code{nil} ++otherwise. For live terminals, the return value indicates what kind ++of frames are displayed on that terminal; the list of possible values ++is the same as for @code{framep} above. ++@end defun ++ ++@menu ++* Creating Frames:: Creating additional frames. ++* Multiple Terminals:: Displaying on several different devices. ++* Frame Parameters:: Controlling frame size, position, font, etc. ++* Terminal Parameters:: Parameters common for all frames on terminal. ++* Frame Titles:: Automatic updating of frame titles. ++* Deleting Frames:: Frames last until explicitly deleted. ++* Finding All Frames:: How to examine all existing frames. ++* Frames and Windows:: A frame contains windows; ++ display of text always works through windows. ++* Minibuffers and Frames:: How a frame finds the minibuffer to use. ++* Input Focus:: Specifying the selected frame. ++* Visibility of Frames:: Frames may be visible or invisible, or icons. ++* Raising and Lowering:: Raising a frame makes it hide other windows; ++ lowering it makes the others hide it. ++* Frame Configurations:: Saving the state of all frames. ++* Mouse Tracking:: Getting events that say when the mouse moves. ++* Mouse Position:: Asking where the mouse is, or moving it. ++* Pop-Up Menus:: Displaying a menu for the user to select from. ++* Dialog Boxes:: Displaying a box to ask yes or no. ++* Pointer Shape:: Specifying the shape of the mouse pointer. ++* Window System Selections:: Transferring text to and from other X clients. ++* Drag and Drop:: Internals of Drag-and-Drop implementation. ++* Color Names:: Getting the definitions of color names. ++* Text Terminal Colors:: Defining colors for text-only terminals. ++* Resources:: Getting resource values from the server. ++* Display Feature Testing:: Determining the features of a terminal. ++@end menu ++ ++@node Creating Frames ++@section Creating Frames ++ ++To create a new frame, call the function @code{make-frame}. ++ ++@defun make-frame &optional alist ++This function creates and returns a new frame, displaying the current ++buffer. ++ ++The @var{alist} argument is an alist that specifies frame parameters ++for the new frame. @xref{Frame Parameters}. If you specify the ++@code{terminal} parameter in @var{alist}, the new frame is created on ++that terminal. Otherwise, if you specify the @code{window-system} ++frame parameter in @var{alist}, that determines whether the frame ++should be displayed on a text-only or graphical terminal. ++@xref{Window Systems}. If neither is specified, the new frame is ++created in the same terminal as the selected frame. ++ ++Any parameters not mentioned in @var{alist} default to the values in ++the alist @code{default-frame-alist} (@pxref{Initial Parameters}); ++parameters not specified there default from the X resources or its ++equivalent on your operating system (@pxref{X Resources,, X Resources, ++emacs, The GNU Emacs Manual}). After the frame is created, Emacs ++applies any parameters listed in @code{frame-inherited-parameters} ++(see below) and not present in the argument, taking the values from ++the frame that was selected when @code{make-frame} was called. ++ ++This function itself does not make the new frame the selected frame. ++@xref{Input Focus}. The previously selected frame remains selected. ++On graphical terminals, however, the windowing system may select the ++new frame for its own reasons. ++@end defun ++ ++@defvar before-make-frame-hook ++A normal hook run by @code{make-frame} before it creates the frame. ++@end defvar ++ ++@defvar after-make-frame-functions ++An abnormal hook run by @code{make-frame} after it creates the frame. ++Each function in @code{after-make-frame-functions} receives one argument, the ++frame just created. ++@end defvar ++ ++@defvar frame-inherited-parameters ++This variable specifies the list of frame parameters that a newly ++created frame inherits from the currently selected frame. For each ++parameter (a symbol) that is an element in the list and is not present ++in the argument to @code{make-frame}, the function sets the value of ++that parameter in the created frame to its value in the selected ++frame. ++@end defvar ++ ++@node Multiple Terminals ++@section Multiple Terminals ++@cindex multiple terminals ++@cindex multi-tty ++@cindex multiple X displays ++@cindex displays, multiple ++ ++ Emacs represents each terminal, whether graphical or text-only, as a ++@dfn{terminal object} data type (@pxref{Terminal Type}). On GNU and ++Unix systems, Emacs can use multiple terminals simultaneously in each ++session. On other systems, it can only use a single terminal. Each ++terminal object has the following attributes: ++ ++@itemize @bullet ++@item ++The name of the device used by the terminal (e.g., @samp{:0.0} or ++@file{/dev/tty}). ++ ++@item ++The terminal and keyboard coding systems used on the terminal. ++@xref{Terminal I/O Encoding}. ++ ++@item ++The kind of display associated with the terminal. This is the symbol ++returned by the function @code{terminal-live-p} (i.e., @code{x}, ++@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}. ++ ++@item ++A list of terminal parameters. @xref{Terminal Parameters}. ++@end itemize ++ ++ There is no primitive for creating terminal objects. Emacs creates ++them as needed, such as when you call @code{make-frame-on-display} ++(which is described below). ++ ++@defun terminal-name &optional terminal ++This function returns the file name of the device used by ++@var{terminal}. If @var{terminal} is omitted or @code{nil}, it ++defaults to the selected frame's terminal. @var{terminal} can also be ++a frame, meaning that frame's terminal. ++@end defun ++ ++@defun terminal-list ++This function returns a list of all terminal objects currently in use. ++@end defun ++ ++@defun get-device-terminal device ++This function returns a terminal whose device name is given by ++@var{device}. If @var{device} is a string, it can be either the file ++name of a terminal device, or the name of an X display of the form ++@samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a ++frame, this function returns that frame's terminal; @code{nil} means ++the selected frame. Finally, if @var{device} is a terminal object ++that represents a live terminal, that terminal is returned. The ++function signals an error if its argument is none of the above. ++@end defun ++ ++@defun delete-terminal &optional terminal force ++This function deletes all frames on @var{terminal} and frees the ++resources used by it. It runs the abnormal hook ++@code{delete-terminal-functions}, passing @var{terminal} as the ++argument to each function. ++ ++If @var{terminal} is omitted or @code{nil}, it defaults to the ++selected frame's terminal. @var{terminal} can also be a frame, ++meaning that frame's terminal. ++ ++Normally, this function signals an error if you attempt to delete the ++sole active terminal, but if @var{force} is non-@code{nil}, you are ++allowed to do so. Emacs automatically calls this function when the ++last frame on a terminal is deleted (@pxref{Deleting Frames}). ++@end defun ++ ++@defvar delete-terminal-functions ++An abnormal hook run by @code{delete-terminal}. Each function ++receives one argument, the @var{terminal} argument passed to ++@code{delete-terminal}. Due to technical details, the functions may ++be called either just before the terminal is deleted, or just ++afterwards. ++@end defvar ++ ++@cindex terminal-local variables ++ A few Lisp variables are @dfn{terminal-local}; that is, they have a ++separate binding for each terminal. The binding in effect at any time ++is the one for the terminal that the currently selected frame belongs ++to. These variables include @code{default-minibuffer-frame}, ++@code{defining-kbd-macro}, @code{last-kbd-macro}, and ++@code{system-key-alist}. They are always terminal-local, and can ++never be buffer-local (@pxref{Buffer-Local Variables}). ++ ++ On GNU and Unix systems, each X display is a separate graphical ++terminal. When Emacs is started from within the X window system, it ++uses the X display chosen with the @code{DISPLAY} environment ++variable, or with the @samp{--display} option. @xref{Initial ++Options,,, emacs, The GNU Emacs Manual}. Emacs can connect to other X ++displays via the command @code{make-frame-on-display}. Each X display ++has its own selected frame and its own minibuffer windows; however, ++only one of those frames is ``@emph{the} selected frame'' at any given ++moment (@pxref{Input Focus}). Emacs can even connect to other ++text-only terminals, by interacting with the @command{emacsclient} ++program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}. ++ ++ A single X server can handle more than one display. Each X display ++has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}. ++The first two parts, @var{host} and @var{server}, identify the X ++server; the third part, @var{screen}, identifies a screen number on ++that X server. When you use two or more screens belonging to one ++server, Emacs knows by the similarity in their names that they share a ++single keyboard. ++ ++ On some ``multi-monitor'' setups, a single X display outputs to more ++than one monitor. Currently, there is no way for Emacs to distinguish ++between the different physical monitors. ++ ++@deffn Command make-frame-on-display display &optional parameters ++This function creates and returns a new frame on @var{display}, taking ++the other frame parameters from the alist @var{parameters}. ++@var{display} should be the name of an X display (a string). ++ ++Before creating the frame, this function ensures that Emacs is ``set ++up'' to display graphics. For instance, if Emacs has not processed X ++resources (e.g., if it was started on a text-only terminal), it does ++so at this time. In all other respects, this function behaves like ++@code{make-frame} (@pxref{Creating Frames}). ++@end deffn ++ ++@defun x-display-list ++This function returns a list that indicates which X displays Emacs has ++a connection to. The elements of the list are strings, and each one ++is a display name. ++@end defun ++ ++@defun x-open-connection display &optional xrm-string must-succeed ++This function opens a connection to the X display @var{display}, ++without creating a frame on that display. Normally, Emacs Lisp ++programs need not call this function, as @code{make-frame-on-display} ++calls it automatically. The only reason for calling it is to check ++whether communication can be established with a given X display. ++ ++The optional argument @var{xrm-string}, if not @code{nil}, is a string ++of resource names and values, in the same format used in the ++@file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The ++GNU Emacs Manual}. These values apply to all Emacs frames created on ++this display, overriding the resource values recorded in the X server. ++Here's an example of what this string might look like: ++ ++@example ++"*BorderWidth: 3\n*InternalBorder: 2\n" ++@end example ++ ++If @var{must-succeed} is non-@code{nil}, failure to open the connection ++terminates Emacs. Otherwise, it is an ordinary Lisp error. ++@end defun ++ ++@defun x-close-connection display ++This function closes the connection to display @var{display}. Before ++you can do this, you must first delete all the frames that were open ++on that display (@pxref{Deleting Frames}). ++@end defun ++ ++@node Frame Parameters ++@section Frame Parameters ++@cindex frame parameters ++ ++ A frame has many parameters that control its appearance and behavior. ++Just what parameters a frame has depends on what display mechanism it ++uses. ++ ++ Frame parameters exist mostly for the sake of window systems. A ++terminal frame has a few parameters, mostly for compatibility's sake; ++only the @code{height}, @code{width}, @code{name}, @code{title}, ++@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate} ++parameters do something special. If the terminal supports colors, the ++parameters @code{foreground-color}, @code{background-color}, ++@code{background-mode} and @code{display-type} are also meaningful. ++If the terminal supports frame transparency, the parameter ++@code{alpha} is also meaningful. ++ ++ You can use frame parameters to define frame-local bindings for ++variables. @xref{Frame-Local Variables}. ++ ++@menu ++* Parameter Access:: How to change a frame's parameters. ++* Initial Parameters:: Specifying frame parameters when you make a frame. ++* Window Frame Parameters:: List of frame parameters for window systems. ++* Size and Position:: Changing the size and position of a frame. ++* Geometry:: Parsing geometry specifications. ++@end menu ++ ++@node Parameter Access ++@subsection Access to Frame Parameters ++ ++These functions let you read and change the parameter values of a ++frame. ++ ++@defun frame-parameter frame parameter ++This function returns the value of the parameter @var{parameter} (a ++symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the ++selected frame's parameter. If @var{frame} has no setting for ++@var{parameter}, this function returns @code{nil}. ++@end defun ++ ++@defun frame-parameters &optional frame ++The function @code{frame-parameters} returns an alist listing all the ++parameters of @var{frame} and their values. If @var{frame} is ++@code{nil} or omitted, this returns the selected frame's parameters ++@end defun ++ ++@defun modify-frame-parameters frame alist ++This function alters the parameters of frame @var{frame} based on the ++elements of @var{alist}. Each element of @var{alist} has the form ++@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a ++parameter. If you don't mention a parameter in @var{alist}, its value ++doesn't change. If @var{frame} is @code{nil}, it defaults to the selected ++frame. ++ ++You can use this function to define frame-local bindings for ++variables, see @ref{Frame-Local Variables}. ++@end defun ++ ++@defun set-frame-parameter frame parm value ++This function sets the frame parameter @var{parm} to the specified ++@var{value}. If @var{frame} is @code{nil}, it defaults to the ++selected frame. ++@end defun ++ ++@defun modify-all-frames-parameters alist ++This function alters the frame parameters of all existing frames ++according to @var{alist}, then modifies @code{default-frame-alist} ++(and, if necessary, @code{initial-frame-alist}) to apply the same ++parameter values to frames that will be created henceforth. ++@end defun ++ ++@node Initial Parameters ++@subsection Initial Frame Parameters ++ ++You can specify the parameters for the initial startup frame ++by setting @code{initial-frame-alist} in your init file (@pxref{Init File}). ++ ++@defopt initial-frame-alist ++This variable's value is an alist of parameter values used when creating ++the initial window frame. You can set this variable to specify the ++appearance of the initial frame without altering subsequent frames. ++Each element has the form: ++ ++@example ++(@var{parameter} . @var{value}) ++@end example ++ ++Emacs creates the initial frame before it reads your init ++file. After reading that file, Emacs checks @code{initial-frame-alist}, ++and applies the parameter settings in the altered value to the already ++created initial frame. ++ ++If these settings affect the frame geometry and appearance, you'll see ++the frame appear with the wrong ones and then change to the specified ++ones. If that bothers you, you can specify the same geometry and ++appearance with X resources; those do take effect before the frame is ++created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. ++ ++X resource settings typically apply to all frames. If you want to ++specify some X resources solely for the sake of the initial frame, and ++you don't want them to apply to subsequent frames, here's how to achieve ++this. Specify parameters in @code{default-frame-alist} to override the ++X resources for subsequent frames; then, to prevent these from affecting ++the initial frame, specify the same parameters in ++@code{initial-frame-alist} with values that match the X resources. ++@end defopt ++ ++If these parameters specify a separate minibuffer-only frame with ++@code{(minibuffer . nil)}, and you have not created one, Emacs creates ++one for you. ++ ++@defopt minibuffer-frame-alist ++This variable's value is an alist of parameter values used when ++creating an initial minibuffer-only frame. This is the ++minibuffer-only frame that Emacs creates if @code{initial-frame-alist} ++specifies a frame with no minibuffer. ++@end defopt ++ ++@defopt default-frame-alist ++This is an alist specifying default values of frame parameters for all ++Emacs frames---the first frame, and subsequent frames. When using the X ++Window System, you can get the same results by means of X resources ++in many cases. ++ ++Setting this variable does not affect existing frames. ++@end defopt ++ ++Functions that display a buffer in a separate frame can override the ++default parameters by supplying their own parameters. @xref{Definition ++of special-display-frame-alist}. ++ ++If you use options that specify window appearance when you invoke Emacs, ++they take effect by adding elements to @code{default-frame-alist}. One ++exception is @samp{-geometry}, which adds the specified position to ++@code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command ++Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}. ++ ++@node Window Frame Parameters ++@subsection Window Frame Parameters ++ ++ Just what parameters a frame has depends on what display mechanism ++it uses. This section describes the parameters that have special ++meanings on some or all kinds of terminals. Of these, @code{name}, ++@code{title}, @code{height}, @code{width}, @code{buffer-list} and ++@code{buffer-predicate} provide meaningful information in terminal ++frames, and @code{tty-color-mode} is meaningful @emph{only} in ++terminal frames. ++ ++@menu ++* Basic Parameters:: Parameters that are fundamental. ++* Position Parameters:: The position of the frame on the screen. ++* Size Parameters:: Frame's size. ++* Layout Parameters:: Size of parts of the frame, and ++ enabling or disabling some parts. ++* Buffer Parameters:: Which buffers have been or should be shown. ++* Management Parameters:: Communicating with the window manager. ++* Cursor Parameters:: Controlling the cursor appearance. ++* Font and Color Parameters:: Fonts and colors for the frame text. ++@end menu ++ ++@node Basic Parameters ++@subsubsection Basic Parameters ++ ++ These frame parameters give the most basic information about the ++frame. @code{title} and @code{name} are meaningful on all terminals. ++ ++@table @code ++@item display ++The display on which to open this frame. It should be a string of the ++form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the ++@code{DISPLAY} environment variable. ++ ++@item display-type ++This parameter describes the range of possible colors that can be used ++in this frame. Its value is @code{color}, @code{grayscale} or ++@code{mono}. ++ ++@item title ++If a frame has a non-@code{nil} title, it appears in the window ++system's title bar at the top of the frame, and also in the mode line ++of windows in that frame if @code{mode-line-frame-identification} uses ++@samp{%F} (@pxref{%-Constructs}). This is normally the case when ++Emacs is not using a window system, and can only display one frame at ++a time. @xref{Frame Titles}. ++ ++@item name ++The name of the frame. The frame name serves as a default for the frame ++title, if the @code{title} parameter is unspecified or @code{nil}. If ++you don't specify a name, Emacs sets the frame name automatically ++(@pxref{Frame Titles}). ++ ++If you specify the frame name explicitly when you create the frame, the ++name is also used (instead of the name of the Emacs executable) when ++looking up X resources for the frame. ++@end table ++ ++@node Position Parameters ++@subsubsection Position Parameters ++ ++ Position parameters' values are normally measured in pixels, but on ++text-only terminals they count characters or lines instead. ++ ++@table @code ++@item left ++The position, in pixels, of the left (or right) edge of the frame with ++respect to the left (or right) edge of the screen. The value may be: ++ ++@table @asis ++@item an integer ++A positive integer relates the left edge of the frame to the left edge ++of the screen. A negative integer relates the right frame edge to the ++right screen edge. ++ ++@item @code{(+ @var{pos})} ++This specifies the position of the left frame edge relative to the left ++screen edge. The integer @var{pos} may be positive or negative; a ++negative value specifies a position outside the screen. ++ ++@item @code{(- @var{pos})} ++This specifies the position of the right frame edge relative to the right ++screen edge. The integer @var{pos} may be positive or negative; a ++negative value specifies a position outside the screen. ++@end table ++ ++Some window managers ignore program-specified positions. If you want to ++be sure the position you specify is not ignored, specify a ++non-@code{nil} value for the @code{user-position} parameter as well. ++ ++@item top ++The screen position of the top (or bottom) edge, in pixels, with respect ++to the top (or bottom) edge of the screen. It works just like ++@code{left}, except vertically instead of horizontally. ++ ++@item icon-left ++The screen position of the left edge @emph{of the frame's icon}, in ++pixels, counting from the left edge of the screen. This takes effect if ++and when the frame is iconified. ++ ++If you specify a value for this parameter, then you must also specify ++a value for @code{icon-top} and vice versa. The window manager may ++ignore these two parameters. ++ ++@item icon-top ++The screen position of the top edge @emph{of the frame's icon}, in ++pixels, counting from the top edge of the screen. This takes effect if ++and when the frame is iconified. ++ ++@item user-position ++When you create a frame and specify its screen position with the ++@code{left} and @code{top} parameters, use this parameter to say whether ++the specified position was user-specified (explicitly requested in some ++way by a human user) or merely program-specified (chosen by a program). ++A non-@code{nil} value says the position was user-specified. ++ ++Window managers generally heed user-specified positions, and some heed ++program-specified positions too. But many ignore program-specified ++positions, placing the window in a default fashion or letting the user ++place it with the mouse. Some window managers, including @code{twm}, ++let the user specify whether to obey program-specified positions or ++ignore them. ++ ++When you call @code{make-frame}, you should specify a non-@code{nil} ++value for this parameter if the values of the @code{left} and @code{top} ++parameters represent the user's stated preference; otherwise, use ++@code{nil}. ++@end table ++ ++@node Size Parameters ++@subsubsection Size Parameters ++ ++ Size parameters' values are normally measured in pixels, but on ++text-only terminals they count characters or lines instead. ++ ++@table @code ++@item height ++The height of the frame contents, in characters. (To get the height in ++pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) ++ ++@item width ++The width of the frame contents, in characters. (To get the width in ++pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) ++ ++@item user-size ++This does for the size parameters @code{height} and @code{width} what ++the @code{user-position} parameter (see above) does for the position ++parameters @code{top} and @code{left}. ++ ++@item fullscreen ++Specify that width, height or both shall be set to the size of the screen. ++The value @code{fullwidth} specifies that width shall be the size of the ++screen. The value @code{fullheight} specifies that height shall be the ++size of the screen. The value @code{fullboth} specifies that both the ++width and the height shall be set to the size of the screen. ++@end table ++ ++@node Layout Parameters ++@subsubsection Layout Parameters ++ ++ These frame parameters enable or disable various parts of the ++frame, or control their sizes. ++ ++@table @code ++@item border-width ++The width in pixels of the frame's border. ++ ++@item internal-border-width ++The distance in pixels between text (or fringe) and the frame's border. ++ ++@item vertical-scroll-bars ++Whether the frame has scroll bars for vertical scrolling, and which side ++of the frame they should be on. The possible values are @code{left}, ++@code{right}, and @code{nil} for no scroll bars. ++ ++@ignore ++@item horizontal-scroll-bars ++Whether the frame has scroll bars for horizontal scrolling ++(non-@code{nil} means yes). Horizontal scroll bars are not currently ++implemented. ++@end ignore ++ ++@item scroll-bar-width ++The width of vertical scroll bars, in pixels, or @code{nil} meaning to ++use the default width. ++ ++@item left-fringe ++@itemx right-fringe ++The default width of the left and right fringes of windows in this ++frame (@pxref{Fringes}). If either of these is zero, that effectively ++removes the corresponding fringe. A value of @code{nil} stands for ++the standard fringe width, which is the width needed to display the ++fringe bitmaps. ++ ++The combined fringe widths must add up to an integral number of ++columns, so the actual default fringe widths for the frame may be ++larger than the specified values. The extra width needed to reach an ++acceptable total is distributed evenly between the left and right ++fringe. However, you can force one fringe or the other to a precise ++width by specifying that width as a negative integer. If both widths are ++negative, only the left fringe gets the specified width. ++ ++@item menu-bar-lines ++The number of lines to allocate at the top of the frame for a menu ++bar. The default is 1. A value of @code{nil} means don't display a ++menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one ++menu bar line; they treat larger values as 1.) ++ ++@item tool-bar-lines ++The number of lines to use for the tool bar. A value of @code{nil} ++means don't display a tool bar. (GTK and Nextstep allow at most one ++tool bar line; they treat larger values as 1.) ++ ++@item line-spacing ++Additional space to leave below each text line, in pixels (a positive ++integer). @xref{Line Height}, for more information. ++@end table ++ ++@node Buffer Parameters ++@subsubsection Buffer Parameters ++ ++ These frame parameters, meaningful on all kinds of terminals, deal ++with which buffers have been, or should, be displayed in the frame. ++ ++@table @code ++@item minibuffer ++Whether this frame has its own minibuffer. The value @code{t} means ++yes, @code{nil} means no, @code{only} means this frame is just a ++minibuffer. If the value is a minibuffer window (in some other ++frame), the frame uses that minibuffer. ++ ++This frame parameter takes effect when the frame is created, and can ++not be changed afterwards. ++ ++@item buffer-predicate ++The buffer-predicate function for this frame. The function ++@code{other-buffer} uses this predicate (from the selected frame) to ++decide which buffers it should consider, if the predicate is not ++@code{nil}. It calls the predicate with one argument, a buffer, once for ++each buffer; if the predicate returns a non-@code{nil} value, it ++considers that buffer. ++ ++@item buffer-list ++A list of buffers that have been selected in this frame, ++ordered most-recently-selected first. ++ ++@item unsplittable ++If non-@code{nil}, this frame's window is never split automatically. ++@end table ++ ++@node Management Parameters ++@subsubsection Window Management Parameters ++@cindex window manager, and frame parameters ++ ++ These frame parameters, meaningful only on window system displays, ++interact with the window manager. ++ ++@table @code ++@item visibility ++The state of visibility of the frame. There are three possibilities: ++@code{nil} for invisible, @code{t} for visible, and @code{icon} for ++iconified. @xref{Visibility of Frames}. ++ ++@item auto-raise ++Whether selecting the frame raises it (non-@code{nil} means yes). ++ ++@item auto-lower ++Whether deselecting the frame lowers it (non-@code{nil} means yes). ++ ++@item icon-type ++The type of icon to use for this frame when it is iconified. If the ++value is a string, that specifies a file containing a bitmap to use. ++Any other non-@code{nil} value specifies the default bitmap icon (a ++picture of a gnu); @code{nil} specifies a text icon. ++ ++@item icon-name ++The name to use in the icon for this frame, when and if the icon ++appears. If this is @code{nil}, the frame's title is used. ++ ++@item window-id ++The number of the window-system window used by the frame ++to contain the actual Emacs windows. ++ ++@item outer-window-id ++The number of the outermost window-system window used for the whole frame. ++ ++@item wait-for-wm ++If non-@code{nil}, tell Xt to wait for the window manager to confirm ++geometry changes. Some window managers, including versions of Fvwm2 ++and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to ++prevent hanging with those window managers. ++ ++@ignore ++@item parent-id ++@c ??? Not yet working. ++The X window number of the window that should be the parent of this one. ++Specifying this lets you create an Emacs window inside some other ++application's window. (It is not certain this will be implemented; try ++it and see if it works.) ++@end ignore ++@end table ++ ++@node Cursor Parameters ++@subsubsection Cursor Parameters ++ ++ This frame parameter controls the way the cursor looks. ++ ++@table @code ++@item cursor-type ++How to display the cursor. Legitimate values are: ++ ++@table @code ++@item box ++Display a filled box. (This is the default.) ++@item hollow ++Display a hollow box. ++@item nil ++Don't display a cursor. ++@item bar ++Display a vertical bar between characters. ++@item (bar . @var{width}) ++Display a vertical bar @var{width} pixels wide between characters. ++@item hbar ++Display a horizontal bar. ++@item (hbar . @var{height}) ++Display a horizontal bar @var{height} pixels high. ++@end table ++@end table ++ ++@vindex cursor-type ++The buffer-local variable @code{cursor-type} overrides the value of ++the @code{cursor-type} frame parameter, but if it is @code{t}, that ++means to use the cursor specified for the frame. ++ ++@defopt blink-cursor-alist ++This variable specifies how to blink the cursor. Each element has the ++form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor ++type equals @var{on-state} (comparing using @code{equal}), the ++corresponding @var{off-state} specifies what the cursor looks like ++when it blinks ``off.'' Both @var{on-state} and @var{off-state} ++should be suitable values for the @code{cursor-type} frame parameter. ++ ++There are various defaults for how to blink each type of cursor, if ++the type is not mentioned as an @var{on-state} here. Changes in this ++variable do not take effect immediately, only when you specify the ++@code{cursor-type} frame parameter. ++@end defopt ++ ++@defopt cursor-in-non-selected-windows ++This variable controls how the cursor looks in a window that is not ++selected. It supports the same values as the @code{cursor-type} frame ++parameter; also, @code{nil} means don't display a cursor in ++nonselected windows, and @code{t} (the default) means use a standard ++modificatoin of the usual cursor type (solid box becomes hollow box, ++and bar becomes a narrower bar). ++@end defopt ++ ++@node Font and Color Parameters ++@subsubsection Font and Color Parameters ++ ++ These frame parameters control the use of fonts and colors. ++ ++@table @code ++@item font-backend ++A list of symbols, specifying the @dfn{font backends} to use for ++drawing fonts in the frame, in order of priority. On X, there are ++currently two available font backends: @code{x} (the X core font ++driver) and @code{xft} (the Xft font driver). On other systems, there ++is only one available font backend, so it does not make sense to ++modify this frame parameter. ++ ++@item background-mode ++This parameter is either @code{dark} or @code{light}, according ++to whether the background color is a light one or a dark one. ++ ++@item tty-color-mode ++@cindex standard colors for character terminals ++This parameter overrides the terminal's color support as given by the ++system's terminal capabilities database in that this parameter's value ++specifies the color mode to use in terminal frames. The value can be ++either a symbol or a number. A number specifies the number of colors ++to use (and, indirectly, what commands to issue to produce each ++color). For example, @code{(tty-color-mode . 8)} specifies use of the ++ANSI escape sequences for 8 standard text colors. A value of -1 turns ++off color support. ++ ++If the parameter's value is a symbol, it specifies a number through ++the value of @code{tty-color-mode-alist}, and the associated number is ++used instead. ++ ++@item screen-gamma ++@cindex gamma correction ++If this is a number, Emacs performs ``gamma correction'' which adjusts ++the brightness of all colors. The value should be the screen gamma of ++your display, a floating point number. ++ ++Usual PC monitors have a screen gamma of 2.2, so color values in ++Emacs, and in X windows generally, are calibrated to display properly ++on a monitor with that gamma value. If you specify 2.2 for ++@code{screen-gamma}, that means no correction is needed. Other values ++request correction, designed to make the corrected colors appear on ++your screen the way they would have appeared without correction on an ++ordinary monitor with a gamma value of 2.2. ++ ++If your monitor displays colors too light, you should specify a ++@code{screen-gamma} value smaller than 2.2. This requests correction ++that makes colors darker. A screen gamma value of 1.5 may give good ++results for LCD color displays. ++ ++@item alpha ++@cindex opacity, frame ++@cindex transparency, frame ++@vindex frame-alpha-lower-limit ++This parameter specifies the opacity of the frame, on graphical ++displays that support variable opacity. It should be an integer ++between 0 and 100, where 0 means completely transparent and 100 means ++completely opaque. It can also have a @code{nil} value, which tells ++Emacs not to set the frame opacity (leaving it to the window manager). ++ ++To prevent the frame from disappearing completely from view, the ++variable @code{frame-alpha-lower-limit} defines a lower opacity limit. ++If the value of the frame parameter is less than the value of this ++variable, Emacs uses the latter. By default, ++@code{frame-alpha-lower-limit} is 20. ++ ++The @code{alpha} frame parameter can also be a cons cell ++@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the ++opacity of the frame when it is selected, and @samp{inactive} is the ++opactity when it is not selected. ++@end table ++ ++The following frame parameters are semi-obsolete in that they are ++automatically equivalent to particular face attributes of particular ++faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}): ++ ++@table @code ++@item font ++The name of the font for displaying text in the frame. This is a ++string, either a valid font name for your system or the name of an Emacs ++fontset (@pxref{Fontsets}). It is equivalent to the @code{font} ++attribute of the @code{default} face. ++ ++@item foreground-color ++The color to use for the image of a character. It is equivalent to ++the @code{:foreground} attribute of the @code{default} face. ++ ++@item background-color ++The color to use for the background of characters. It is equivalent to ++the @code{:background} attribute of the @code{default} face. ++ ++@item mouse-color ++The color for the mouse pointer. It is equivalent to the @code{:background} ++attribute of the @code{mouse} face. ++ ++@item cursor-color ++The color for the cursor that shows point. It is equivalent to the ++@code{:background} attribute of the @code{cursor} face. ++ ++@item border-color ++The color for the border of the frame. It is equivalent to the ++@code{:background} attribute of the @code{border} face. ++ ++@item scroll-bar-foreground ++If non-@code{nil}, the color for the foreground of scroll bars. It is ++equivalent to the @code{:foreground} attribute of the ++@code{scroll-bar} face. ++ ++@item scroll-bar-background ++If non-@code{nil}, the color for the background of scroll bars. It is ++equivalent to the @code{:background} attribute of the ++@code{scroll-bar} face. ++@end table ++ ++@node Size and Position ++@subsection Frame Size And Position ++@cindex size of frame ++@cindex screen size ++@cindex frame size ++@cindex resize frame ++ ++ You can read or change the size and position of a frame using the ++frame parameters @code{left}, @code{top}, @code{height}, and ++@code{width}. Whatever geometry parameters you don't specify are chosen ++by the window manager in its usual fashion. ++ ++ Here are some special features for working with sizes and positions. ++(For the precise meaning of ``selected frame'' used by these functions, ++see @ref{Input Focus}.) ++ ++@defun set-frame-position frame left top ++This function sets the position of the top left corner of @var{frame} to ++@var{left} and @var{top}. These arguments are measured in pixels, and ++normally count from the top left corner of the screen. ++ ++Negative parameter values position the bottom edge of the window up from ++the bottom edge of the screen, or the right window edge to the left of ++the right edge of the screen. It would probably be better if the values ++were always counted from the left and top, so that negative arguments ++would position the frame partly off the top or left edge of the screen, ++but it seems inadvisable to change that now. ++@end defun ++ ++@defun frame-height &optional frame ++@defunx frame-width &optional frame ++These functions return the height and width of @var{frame}, measured in ++lines and columns. If you don't supply @var{frame}, they use the ++selected frame. ++@end defun ++ ++@defun frame-pixel-height &optional frame ++@defunx frame-pixel-width &optional frame ++These functions return the height and width of the main display area ++of @var{frame}, measured in pixels. If you don't supply @var{frame}, ++they use the selected frame. ++ ++These values include the internal borders, and windows' scroll bars ++and fringes (which belong to individual windows, not to the frame ++itself), but do not include menu bars or tool bars (except when using ++X without an X toolkit). ++@end defun ++ ++@defun frame-char-height &optional frame ++@defunx frame-char-width &optional frame ++These functions return the height and width of a character in ++@var{frame}, measured in pixels. The values depend on the choice of ++font. If you don't supply @var{frame}, these functions use the selected ++frame. ++@end defun ++ ++@defun set-frame-size frame cols rows ++This function sets the size of @var{frame}, measured in characters; ++@var{cols} and @var{rows} specify the new width and height. ++ ++To set the size based on values measured in pixels, use ++@code{frame-char-height} and @code{frame-char-width} to convert ++them to units of characters. ++@end defun ++ ++@defun set-frame-height frame lines &optional pretend ++This function resizes @var{frame} to a height of @var{lines} lines. The ++sizes of existing windows in @var{frame} are altered proportionally to ++fit. ++ ++If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines} ++lines of output in @var{frame}, but does not change its value for the ++actual height of the frame. This is only useful for a terminal frame. ++Using a smaller height than the terminal actually implements may be ++useful to reproduce behavior observed on a smaller screen, or if the ++terminal malfunctions when using its whole screen. Setting the frame ++height ``for real'' does not always work, because knowing the correct ++actual size may be necessary for correct cursor positioning on a ++terminal frame. ++@end defun ++ ++@defun set-frame-width frame width &optional pretend ++This function sets the width of @var{frame}, measured in characters. ++The argument @var{pretend} has the same meaning as in ++@code{set-frame-height}. ++@end defun ++ ++@findex set-screen-height ++@findex set-screen-width ++ The older functions @code{set-screen-height} and ++@code{set-screen-width} were used to specify the height and width of the ++screen, in Emacs versions that did not support multiple frames. They ++are semi-obsolete, but still work; they apply to the selected frame. ++ ++@node Geometry ++@subsection Geometry ++ ++ Here's how to examine the data in an X-style window geometry ++specification: ++ ++@defun x-parse-geometry geom ++@cindex geometry specification ++The function @code{x-parse-geometry} converts a standard X window ++geometry string to an alist that you can use as part of the argument to ++@code{make-frame}. ++ ++The alist describes which parameters were specified in @var{geom}, and ++gives the values specified for them. Each element looks like ++@code{(@var{parameter} . @var{value})}. The possible @var{parameter} ++values are @code{left}, @code{top}, @code{width}, and @code{height}. ++ ++For the size parameters, the value must be an integer. The position ++parameter names @code{left} and @code{top} are not totally accurate, ++because some values indicate the position of the right or bottom edges ++instead. The @var{value} possibilities for the position parameters are: ++an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})}; ++as previously described (@pxref{Position Parameters}). ++ ++Here is an example: ++ ++@example ++(x-parse-geometry "35x70+0-0") ++ @result{} ((height . 70) (width . 35) ++ (top - 0) (left . 0)) ++@end example ++@end defun ++ ++@node Terminal Parameters ++@section Terminal Parameters ++@cindex terminal parameters ++ ++ Each terminal has a list of associated parameters. These ++@dfn{terminal parameters} are mostly a convenient way of storage for ++terminal-local variables, but some terminal parameters have a special ++meaning. ++ ++ This section describes functions to read and change the parameter values ++of a terminal. They all accept as their argument either a terminal or ++a frame; the latter means use that frame's terminal. An argument of ++@code{nil} means the selected frame's terminal. ++ ++@defun terminal-parameters &optional terminal ++This function returns an alist listing all the parameters of ++@var{terminal} and their values. ++@end defun ++ ++@defun terminal-parameter terminal parameter ++This function returns the value of the parameter @var{parameter} (a ++symbol) of @var{terminal}. If @var{terminal} has no setting for ++@var{parameter}, this function returns @code{nil}. ++@end defun ++ ++@defun set-terminal-parameter terminal parameter value ++This function sets the parameter @var{parm} of @var{terminal} to the ++specified @var{value}, and returns the previous value of that ++parameter. ++@end defun ++ ++Here's a list of a few terminal parameters that have a special ++meaning: ++ ++@table @code ++@item background-mode ++The classification of the terminal's background color, either ++@code{light} or @code{dark}. ++@item normal-erase-is-backspace ++Value is either 1 or 0, depending on whether ++@code{normal-erase-is-backspace-mode} is turned on or off on this ++terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}. ++@item terminal-initted ++After the terminal is initialized, this is set to the ++terminal-specific initialization function. ++@end table ++ ++@node Frame Titles ++@section Frame Titles ++@cindex frame title ++ ++ Every frame has a @code{name} parameter; this serves as the default ++for the frame title which window systems typically display at the top of ++the frame. You can specify a name explicitly by setting the @code{name} ++frame property. ++ ++ Normally you don't specify the name explicitly, and Emacs computes the ++frame name automatically based on a template stored in the variable ++@code{frame-title-format}. Emacs recomputes the name each time the ++frame is redisplayed. ++ ++@defvar frame-title-format ++This variable specifies how to compute a name for a frame when you have ++not explicitly specified one. The variable's value is actually a mode ++line construct, just like @code{mode-line-format}, except that the ++@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line ++Data}. ++@end defvar ++ ++@defvar icon-title-format ++This variable specifies how to compute the name for an iconified frame, ++when you have not explicitly specified the frame title. This title ++appears in the icon itself. ++@end defvar ++ ++@defvar multiple-frames ++This variable is set automatically by Emacs. Its value is @code{t} when ++there are two or more frames (not counting minibuffer-only frames or ++invisible frames). The default value of @code{frame-title-format} uses ++@code{multiple-frames} so as to put the buffer name in the frame title ++only when there is more than one frame. ++ ++The value of this variable is not guaranteed to be accurate except ++while processing @code{frame-title-format} or ++@code{icon-title-format}. ++@end defvar ++ ++@node Deleting Frames ++@section Deleting Frames ++@cindex deleting frames ++ ++Frames remain potentially visible until you explicitly @dfn{delete} ++them. A deleted frame cannot appear on the screen, but continues to ++exist as a Lisp object until there are no references to it. ++ ++@deffn Command delete-frame &optional frame force ++@vindex delete-frame-functions ++This function deletes the frame @var{frame}. Unless @var{frame} is a ++tooltip, it first runs the hook @code{delete-frame-functions} (each ++function gets one argument, @var{frame}). By default, @var{frame} is ++the selected frame. ++ ++A frame cannot be deleted if its minibuffer is used by other frames. ++Normally, you cannot delete a frame if all other frames are invisible, ++but if @var{force} is non-@code{nil}, then you are allowed to do so. ++@end deffn ++ ++@defun frame-live-p frame ++The function @code{frame-live-p} returns non-@code{nil} if the frame ++@var{frame} has not been deleted. The possible non-@code{nil} return ++values are like those of @code{framep}. @xref{Frames}. ++@end defun ++ ++ Some window managers provide a command to delete a window. These work ++by sending a special message to the program that operates the window. ++When Emacs gets one of these commands, it generates a ++@code{delete-frame} event, whose normal definition is a command that ++calls the function @code{delete-frame}. @xref{Misc Events}. ++ ++@node Finding All Frames ++@section Finding All Frames ++@cindex frames, scanning all ++ ++@defun frame-list ++The function @code{frame-list} returns a list of all the live frames, ++i.e.@: those that have not been deleted. It is analogous to ++@code{buffer-list} for buffers, and includes frames on all terminals. ++The list that you get is newly created, so modifying the list doesn't ++have any effect on the internals of Emacs. ++@end defun ++ ++@defun visible-frame-list ++This function returns a list of just the currently visible frames. ++@xref{Visibility of Frames}. (Terminal frames always count as ++``visible,'' even though only the selected one is actually displayed.) ++@end defun ++ ++@defun next-frame &optional frame minibuf ++The function @code{next-frame} lets you cycle conveniently through all ++the frames on the current display from an arbitrary starting point. It ++returns the ``next'' frame after @var{frame} in the cycle. If ++@var{frame} is omitted or @code{nil}, it defaults to the selected frame ++(@pxref{Input Focus}). ++ ++The second argument, @var{minibuf}, says which frames to consider: ++ ++@table @asis ++@item @code{nil} ++Exclude minibuffer-only frames. ++@item @code{visible} ++Consider all visible frames. ++@item 0 ++Consider all visible or iconified frames. ++@item a window ++Consider only the frames using that particular window as their ++minibuffer. ++@item anything else ++Consider all frames. ++@end table ++@end defun ++ ++@defun previous-frame &optional frame minibuf ++Like @code{next-frame}, but cycles through all frames in the opposite ++direction. ++@end defun ++ ++ See also @code{next-window} and @code{previous-window}, in @ref{Cyclic ++Window Ordering}. ++ ++@node Frames and Windows ++@section Frames and Windows ++ ++ Each window is part of one and only one frame; you can get that frame ++with @code{window-frame}. ++ ++@defun window-frame window ++This function returns the frame that @var{window} is on. ++@end defun ++ ++ All the non-minibuffer windows in a frame are arranged in a cyclic ++order. The order runs from the frame's top window, which is at the ++upper left corner, down and to the right, until it reaches the window at ++the lower right corner (always the minibuffer window, if the frame has ++one), and then it moves back to the top. @xref{Cyclic Window Ordering}. ++ ++@defun frame-first-window &optional frame ++This returns the topmost, leftmost window of frame @var{frame}. ++If omitted or @code{nil}, @var{frame} defaults to the selected frame. ++@end defun ++ ++At any time, exactly one window on any frame is @dfn{selected within the ++frame}. The significance of this designation is that selecting the ++frame also selects this window. Conversely, selecting a window for ++Emacs with @code{select-window} also makes that window selected within ++its frame. @xref{Selecting Windows}. ++ ++@defun frame-selected-window &optional frame ++This function returns the window on @var{frame} that is selected ++within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to ++the selected frame. ++@end defun ++ ++@defun set-frame-selected-window frame window &optional norecord ++This sets the selected window of frame @var{frame} to @var{window}. ++If @var{frame} is @code{nil}, it operates on the selected frame. If ++@var{frame} is the selected frame, this makes @var{window} the ++selected window. This function returns @var{window}. ++ ++Optional argument @var{norecord} non-@code{nil} means to neither change ++the order of recently selected windows nor the buffer list (@pxref{The ++Buffer List}). ++@end defun ++ ++ Another function that (usually) returns one of the windows in a given ++frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}. ++ ++@node Minibuffers and Frames ++@section Minibuffers and Frames ++ ++Normally, each frame has its own minibuffer window at the bottom, which ++is used whenever that frame is selected. If the frame has a minibuffer, ++you can get it with @code{minibuffer-window} (@pxref{Definition of ++minibuffer-window}). ++ ++However, you can also create a frame with no minibuffer. Such a frame ++must use the minibuffer window of some other frame. When you create the ++frame, you can specify explicitly the minibuffer window to use (in some ++other frame). If you don't, then the minibuffer is found in the frame ++which is the value of the variable @code{default-minibuffer-frame}. Its ++value should be a frame that does have a minibuffer. ++ ++If you use a minibuffer-only frame, you might want that frame to raise ++when you enter the minibuffer. If so, set the variable ++@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}. ++ ++@defvar default-minibuffer-frame ++This variable specifies the frame to use for the minibuffer window, by ++default. It does not affect existing frames. It is always local to ++the current terminal and cannot be buffer-local. @xref{Multiple ++Terminals}. ++@end defvar ++ ++@node Input Focus ++@section Input Focus ++@cindex input focus ++@c @cindex selected frame Duplicates selected-frame ++ ++At any time, one frame in Emacs is the @dfn{selected frame}. The selected ++window always resides on the selected frame. ++ ++When Emacs displays its frames on several terminals (@pxref{Multiple ++Terminals}), each terminal has its own selected frame. But only one ++of these is ``@emph{the} selected frame'': it's the frame that belongs ++to the terminal from which the most recent input came. That is, when ++Emacs runs a command that came from a certain terminal, the selected ++frame is the one of that terminal. Since Emacs runs only a single ++command at any given time, it needs to consider only one selected ++frame at a time; this frame is what we call @dfn{the selected frame} ++in this manual. The display on which the selected frame is shown is ++the @dfn{selected frame's display}. ++ ++@defun selected-frame ++This function returns the selected frame. ++@end defun ++ ++Some window systems and window managers direct keyboard input to the ++window object that the mouse is in; others require explicit clicks or ++commands to @dfn{shift the focus} to various window objects. Either ++way, Emacs automatically keeps track of which frame has the focus. To ++explicitly switch to a different frame from a Lisp function, call ++@code{select-frame-set-input-focus}. ++ ++Lisp programs can also switch frames ``temporarily'' by calling the ++function @code{select-frame}. This does not alter the window system's ++concept of focus; rather, it escapes from the window manager's control ++until that control is somehow reasserted. ++ ++When using a text-only terminal, only one frame can be displayed at a ++time on the terminal, so after a call to @code{select-frame}, the next ++redisplay actually displays the newly selected frame. This frame ++remains selected until a subsequent call to @code{select-frame}. Each ++terminal frame has a number which appears in the mode line before the ++buffer name (@pxref{Mode Line Variables}). ++ ++@defun select-frame-set-input-focus frame ++This function selects @var{frame}, raises it (should it happen to be ++obscured by other frames) and tries to give it the X server's focus. On ++a text-only terminal, the next redisplay displays the new frame on the ++entire terminal screen. The return value of this function is not ++significant. ++@end defun ++ ++@c ??? This is not yet implemented properly. ++@defun select-frame frame &optional norecord ++This function selects frame @var{frame}, temporarily disregarding the ++focus of the X server if any. The selection of @var{frame} lasts until ++the next time the user does something to select a different frame, or ++until the next time this function is called. (If you are using a ++window system, the previously selected frame may be restored as the ++selected frame after return to the command loop, because it still may ++have the window system's input focus.) ++ ++The specified @var{frame} becomes the selected frame, as explained ++above, and the terminal that @var{frame} is on becomes the selected ++terminal. The window selected within @var{frame} becomes the selected ++window. This function returns @var{frame}, or @code{nil} if @var{frame} ++has been deleted. ++ ++Optional argument @var{norecord} non-@code{nil} means to neither change ++the order of recently selected windows nor the buffer list. @xref{The ++Buffer List}. ++ ++In general, you should never use @code{select-frame} in a way that could ++switch to a different terminal without switching back when you're done. ++@end defun ++ ++Emacs cooperates with the window system by arranging to select frames as ++the server and window manager request. It does so by generating a ++special kind of input event, called a @dfn{focus} event, when ++appropriate. The command loop handles a focus event by calling ++@code{handle-switch-frame}. @xref{Focus Events}. ++ ++@deffn Command handle-switch-frame frame ++This function handles a focus event by selecting frame @var{frame}. ++ ++Focus events normally do their job by invoking this command. ++Don't call it for any other reason. ++@end deffn ++ ++@defun redirect-frame-focus frame &optional focus-frame ++This function redirects focus from @var{frame} to @var{focus-frame}. ++This means that @var{focus-frame} will receive subsequent keystrokes and ++events intended for @var{frame}. After such an event, the value of ++@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame ++events specifying @var{frame} will instead select @var{focus-frame}. ++ ++If @var{focus-frame} is omitted or @code{nil}, that cancels any existing ++redirection for @var{frame}, which therefore once again receives its own ++events. ++ ++One use of focus redirection is for frames that don't have minibuffers. ++These frames use minibuffers on other frames. Activating a minibuffer ++on another frame redirects focus to that frame. This puts the focus on ++the minibuffer's frame, where it belongs, even though the mouse remains ++in the frame that activated the minibuffer. ++ ++Selecting a frame can also change focus redirections. Selecting frame ++@code{bar}, when @code{foo} had been selected, changes any redirections ++pointing to @code{foo} so that they point to @code{bar} instead. This ++allows focus redirection to work properly when the user switches from ++one frame to another using @code{select-window}. ++ ++This means that a frame whose focus is redirected to itself is treated ++differently from a frame whose focus is not redirected. ++@code{select-frame} affects the former but not the latter. ++ ++The redirection lasts until @code{redirect-frame-focus} is called to ++change it. ++@end defun ++ ++@defopt focus-follows-mouse ++This option is how you inform Emacs whether the window manager transfers ++focus when the user moves the mouse. Non-@code{nil} says that it does. ++When this is so, the command @code{other-frame} moves the mouse to a ++position consistent with the new selected frame. ++@end defopt ++ ++@node Visibility of Frames ++@section Visibility of Frames ++@cindex visible frame ++@cindex invisible frame ++@cindex iconified frame ++@cindex frame visibility ++ ++A window frame may be @dfn{visible}, @dfn{invisible}, or ++@dfn{iconified}. If it is visible, you can see its contents, unless ++other windows cover it. If it is iconified, the frame's contents do ++not appear on the screen, but an icon does. (Note: because of the ++way in which some window managers implement the concept of multiple ++workspaces, or desktops, all frames on other workspaces may appear to ++Emacs to be iconified.) If the frame is invisible, it doesn't show on ++the screen, not even as an icon. ++ ++Visibility is meaningless for terminal frames, since only the selected ++one is actually displayed in any case. ++ ++@deffn Command make-frame-visible &optional frame ++This function makes frame @var{frame} visible. If you omit ++@var{frame}, it makes the selected frame visible. This does not raise ++the frame, but you can do that with @code{raise-frame} if you wish ++(@pxref{Raising and Lowering}). ++@end deffn ++ ++@deffn Command make-frame-invisible &optional frame force ++This function makes frame @var{frame} invisible. If you omit ++@var{frame}, it makes the selected frame invisible. ++ ++Unless @var{force} is non-@code{nil}, this function refuses to make ++@var{frame} invisible if all other frames are invisible.. ++@end deffn ++ ++@deffn Command iconify-frame &optional frame ++This function iconifies frame @var{frame}. If you omit @var{frame}, it ++iconifies the selected frame. ++@end deffn ++ ++@defun frame-visible-p frame ++This returns the visibility status of frame @var{frame}. The value is ++@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and ++@code{icon} if it is iconified. ++ ++On a text-only terminal, all frames are considered visible, whether ++they are currently being displayed or not, and this function returns ++@code{t} for all frames. ++@end defun ++ ++ The visibility status of a frame is also available as a frame ++parameter. You can read or change it as such. @xref{Management ++Parameters}. ++ ++ The user can iconify and deiconify frames with the window manager. ++This happens below the level at which Emacs can exert any control, but ++Emacs does provide events that you can use to keep track of such ++changes. @xref{Misc Events}. ++ ++@node Raising and Lowering ++@section Raising and Lowering Frames ++ ++ Most window systems use a desktop metaphor. Part of this metaphor is ++the idea that windows are stacked in a notional third dimension ++perpendicular to the screen surface, and thus ordered from ``highest'' ++to ``lowest.'' Where two windows overlap, the one higher up covers ++the one underneath. Even a window at the bottom of the stack can be ++seen if no other window overlaps it. ++ ++@c @cindex raising a frame redundant with raise-frame ++@cindex lowering a frame ++ A window's place in this ordering is not fixed; in fact, users tend ++to change the order frequently. @dfn{Raising} a window means moving ++it ``up,'' to the top of the stack. @dfn{Lowering} a window means ++moving it to the bottom of the stack. This motion is in the notional ++third dimension only, and does not change the position of the window ++on the screen. ++ ++ With Emacs, frames constitute the windows in the metaphor sketched ++above. You can raise and lower frames using these functions: ++ ++@deffn Command raise-frame &optional frame ++This function raises frame @var{frame} (default, the selected frame). ++If @var{frame} is invisible or iconified, this makes it visible. ++@end deffn ++ ++@deffn Command lower-frame &optional frame ++This function lowers frame @var{frame} (default, the selected frame). ++@end deffn ++ ++@defopt minibuffer-auto-raise ++If this is non-@code{nil}, activation of the minibuffer raises the frame ++that the minibuffer window is in. ++@end defopt ++ ++You can also enable auto-raise (raising automatically when a frame is ++selected) or auto-lower (lowering automatically when it is deselected) ++for any frame using frame parameters. @xref{Management Parameters}. ++ ++@node Frame Configurations ++@section Frame Configurations ++@cindex frame configuration ++ ++ A @dfn{frame configuration} records the current arrangement of frames, ++all their properties, and the window configuration of each one. ++(@xref{Window Configurations}.) ++ ++@defun current-frame-configuration ++This function returns a frame configuration list that describes ++the current arrangement of frames and their contents. ++@end defun ++ ++@defun set-frame-configuration configuration &optional nodelete ++This function restores the state of frames described in ++@var{configuration}. However, this function does not restore deleted ++frames. ++ ++Ordinarily, this function deletes all existing frames not listed in ++@var{configuration}. But if @var{nodelete} is non-@code{nil}, the ++unwanted frames are iconified instead. ++@end defun ++ ++@node Mouse Tracking ++@section Mouse Tracking ++@cindex mouse tracking ++@c @cindex tracking the mouse Duplicates track-mouse ++ ++ Sometimes it is useful to @dfn{track} the mouse, which means to display ++something to indicate where the mouse is and move the indicator as the ++mouse moves. For efficient mouse tracking, you need a way to wait until ++the mouse actually moves. ++ ++ The convenient way to track the mouse is to ask for events to represent ++mouse motion. Then you can wait for motion by waiting for an event. In ++addition, you can easily handle any other sorts of events that may ++occur. That is useful, because normally you don't want to track the ++mouse forever---only until some other event, such as the release of a ++button. ++ ++@defspec track-mouse body@dots{} ++This special form executes @var{body}, with generation of mouse motion ++events enabled. Typically, @var{body} would use @code{read-event} to ++read the motion events and modify the display accordingly. @xref{Motion ++Events}, for the format of mouse motion events. ++ ++The value of @code{track-mouse} is that of the last form in @var{body}. ++You should design @var{body} to return when it sees the up-event that ++indicates the release of the button, or whatever kind of event means ++it is time to stop tracking. ++@end defspec ++ ++The usual purpose of tracking mouse motion is to indicate on the screen ++the consequences of pushing or releasing a button at the current ++position. ++ ++In many cases, you can avoid the need to track the mouse by using ++the @code{mouse-face} text property (@pxref{Special Properties}). ++That works at a much lower level and runs more smoothly than ++Lisp-level mouse tracking. ++ ++@ignore ++@c These are not implemented yet. ++ ++These functions change the screen appearance instantaneously. The ++effect is transient, only until the next ordinary Emacs redisplay. That ++is OK for mouse tracking, since it doesn't make sense for mouse tracking ++to change the text, and the body of @code{track-mouse} normally reads ++the events itself and does not do redisplay. ++ ++@defun x-contour-region window beg end ++This function draws lines to make a box around the text from @var{beg} ++to @var{end}, in window @var{window}. ++@end defun ++ ++@defun x-uncontour-region window beg end ++This function erases the lines that would make a box around the text ++from @var{beg} to @var{end}, in window @var{window}. Use it to remove ++a contour that you previously made by calling @code{x-contour-region}. ++@end defun ++ ++@defun x-draw-rectangle frame left top right bottom ++This function draws a hollow rectangle on frame @var{frame} with the ++specified edge coordinates, all measured in pixels from the inside top ++left corner. It uses the cursor color, the one used for indicating the ++location of point. ++@end defun ++ ++@defun x-erase-rectangle frame left top right bottom ++This function erases a hollow rectangle on frame @var{frame} with the ++specified edge coordinates, all measured in pixels from the inside top ++left corner. Erasure means redrawing the text and background that ++normally belong in the specified rectangle. ++@end defun ++@end ignore ++ ++@node Mouse Position ++@section Mouse Position ++@cindex mouse position ++@cindex position of mouse ++ ++ The functions @code{mouse-position} and @code{set-mouse-position} ++give access to the current position of the mouse. ++ ++@defun mouse-position ++This function returns a description of the position of the mouse. The ++value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} ++and @var{y} are integers giving the position in characters relative to ++the top left corner of the inside of @var{frame}. ++@end defun ++ ++@defvar mouse-position-function ++If non-@code{nil}, the value of this variable is a function for ++@code{mouse-position} to call. @code{mouse-position} calls this ++function just before returning, with its normal return value as the ++sole argument, and it returns whatever this function returns to it. ++ ++This abnormal hook exists for the benefit of packages like ++@file{xt-mouse.el} that need to do mouse handling at the Lisp level. ++@end defvar ++ ++@defun set-mouse-position frame x y ++This function @dfn{warps the mouse} to position @var{x}, @var{y} in ++frame @var{frame}. The arguments @var{x} and @var{y} are integers, ++giving the position in characters relative to the top left corner of the ++inside of @var{frame}. If @var{frame} is not visible, this function ++does nothing. The return value is not significant. ++@end defun ++ ++@defun mouse-pixel-position ++This function is like @code{mouse-position} except that it returns ++coordinates in units of pixels rather than units of characters. ++@end defun ++ ++@defun set-mouse-pixel-position frame x y ++This function warps the mouse like @code{set-mouse-position} except that ++@var{x} and @var{y} are in units of pixels rather than units of ++characters. These coordinates are not required to be within the frame. ++ ++If @var{frame} is not visible, this function does nothing. The return ++value is not significant. ++@end defun ++ ++@need 3000 ++ ++@node Pop-Up Menus ++@section Pop-Up Menus ++ ++ When using a window system, a Lisp program can pop up a menu so that ++the user can choose an alternative with the mouse. ++ ++@defun x-popup-menu position menu ++This function displays a pop-up menu and returns an indication of ++what selection the user makes. ++ ++The argument @var{position} specifies where on the screen to put the ++top left corner of the menu. It can be either a mouse button event ++(which says to put the menu where the user actuated the button) or a ++list of this form: ++ ++@example ++((@var{xoffset} @var{yoffset}) @var{window}) ++@end example ++ ++@noindent ++where @var{xoffset} and @var{yoffset} are coordinates, measured in ++pixels, counting from the top left corner of @var{window}. @var{window} ++may be a window or a frame. ++ ++If @var{position} is @code{t}, it means to use the current mouse ++position. If @var{position} is @code{nil}, it means to precompute the ++key binding equivalents for the keymaps specified in @var{menu}, ++without actually displaying or popping up the menu. ++ ++The argument @var{menu} says what to display in the menu. It can be a ++keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the ++return value is the list of events corresponding to the user's choice. ++(This list has more than one element if the choice occurred in a ++submenu.) Note that @code{x-popup-menu} does not actually execute the ++command bound to that sequence of events. ++ ++Alternatively, @var{menu} can have the following form: ++ ++@example ++(@var{title} @var{pane1} @var{pane2}...) ++@end example ++ ++@noindent ++where each pane is a list of form ++ ++@example ++(@var{title} @var{item1} @var{item2}...) ++@end example ++ ++Each item should normally be a cons cell @code{(@var{line} . @var{value})}, ++where @var{line} is a string, and @var{value} is the value to return if ++that @var{line} is chosen. An item can also be a string; this makes a ++non-selectable line in the menu. ++ ++If the user gets rid of the menu without making a valid choice, for ++instance by clicking the mouse away from a valid choice or by typing ++keyboard input, then this normally results in a quit and ++@code{x-popup-menu} does not return. But if @var{position} is a mouse ++button event (indicating that the user invoked the menu with the ++mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}. ++@end defun ++ ++ @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu ++if you could do the job with a prefix key defined with a menu keymap. ++If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h ++a} can see the individual items in that menu and provide help for them. ++If instead you implement the menu by defining a command that calls ++@code{x-popup-menu}, the help facilities cannot know what happens inside ++that command, so they cannot give any help for the menu's items. ++ ++ The menu bar mechanism, which lets you switch between submenus by ++moving the mouse, cannot look within the definition of a command to see ++that it calls @code{x-popup-menu}. Therefore, if you try to implement a ++submenu using @code{x-popup-menu}, it cannot work with the menu bar in ++an integrated fashion. This is why all menu bar submenus are ++implemented with menu keymaps within the parent menu, and never with ++@code{x-popup-menu}. @xref{Menu Bar}. ++ ++ If you want a menu bar submenu to have contents that vary, you should ++still use a menu keymap to implement it. To make the contents vary, add ++a hook function to @code{menu-bar-update-hook} to update the contents of ++the menu keymap as necessary. ++ ++@node Dialog Boxes ++@section Dialog Boxes ++@cindex dialog boxes ++ ++ A dialog box is a variant of a pop-up menu---it looks a little ++different, it always appears in the center of a frame, and it has just ++one level and one or more buttons. The main use of dialog boxes is ++for asking questions that the user can answer with ``yes,'' ``no,'' ++and a few other alternatives. With a single button, they can also ++force the user to acknowledge important information. The functions ++@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the ++keyboard, when called from commands invoked by mouse clicks. ++ ++@defun x-popup-dialog position contents &optional header ++This function displays a pop-up dialog box and returns an indication of ++what selection the user makes. The argument @var{contents} specifies ++the alternatives to offer; it has this format: ++ ++@example ++(@var{title} (@var{string} . @var{value})@dots{}) ++@end example ++ ++@noindent ++which looks like the list that specifies a single pane for ++@code{x-popup-menu}. ++ ++The return value is @var{value} from the chosen alternative. ++ ++As for @code{x-popup-menu}, an element of the list may be just a ++string instead of a cons cell @code{(@var{string} . @var{value})}. ++That makes a box that cannot be selected. ++ ++If @code{nil} appears in the list, it separates the left-hand items from ++the right-hand items; items that precede the @code{nil} appear on the ++left, and items that follow the @code{nil} appear on the right. If you ++don't include a @code{nil} in the list, then approximately half the ++items appear on each side. ++ ++Dialog boxes always appear in the center of a frame; the argument ++@var{position} specifies which frame. The possible values are as in ++@code{x-popup-menu}, but the precise coordinates or the individual ++window don't matter; only the frame matters. ++ ++If @var{header} is non-@code{nil}, the frame title for the box is ++@samp{Information}, otherwise it is @samp{Question}. The former is used ++for @code{message-box} (@pxref{message-box}). ++ ++In some configurations, Emacs cannot display a real dialog box; so ++instead it displays the same items in a pop-up menu in the center of the ++frame. ++ ++If the user gets rid of the dialog box without making a valid choice, ++for instance using the window manager, then this produces a quit and ++@code{x-popup-dialog} does not return. ++@end defun ++ ++@node Pointer Shape ++@section Pointer Shape ++@cindex pointer shape ++@cindex mouse pointer shape ++ ++ You can specify the mouse pointer style for particular text or ++images using the @code{pointer} text property, and for images with the ++@code{:pointer} and @code{:map} image properties. The values you can ++use in these properties are @code{text} (or @code{nil}), @code{arrow}, ++@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and ++@code{hourglass}. @code{text} stands for the usual mouse pointer ++style used over text. ++ ++ Over void parts of the window (parts that do not correspond to any ++of the buffer contents), the mouse pointer usually uses the ++@code{arrow} style, but you can specify a different style (one of ++those above) by setting @code{void-text-area-pointer}. ++ ++@defvar void-text-area-pointer ++This variable specifies the mouse pointer style for void text areas. ++These include the areas after the end of a line or below the last line ++in the buffer. The default is to use the @code{arrow} (non-text) ++pointer style. ++@end defvar ++ ++ When using X, you can specify what the @code{text} pointer style ++really looks like by setting the variable @code{x-pointer-shape}. ++ ++@defvar x-pointer-shape ++This variable specifies the pointer shape to use ordinarily in the ++Emacs frame, for the @code{text} pointer style. ++@end defvar ++ ++@defvar x-sensitive-text-pointer-shape ++This variable specifies the pointer shape to use when the mouse ++is over mouse-sensitive text. ++@end defvar ++ ++ These variables affect newly created frames. They do not normally ++affect existing frames; however, if you set the mouse color of a ++frame, that also installs the current value of those two variables. ++@xref{Font and Color Parameters}. ++ ++ The values you can use, to specify either of these pointer shapes, are ++defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos ++@key{RET} x-pointer @key{RET}} to see a list of them. ++ ++@node Window System Selections ++@section Window System Selections ++@cindex selection (for window systems) ++ ++The X server records a set of @dfn{selections} which permit transfer of ++data between application programs. The various selections are ++distinguished by @dfn{selection types}, represented in Emacs by ++symbols. X clients including Emacs can read or set the selection for ++any given type. ++ ++@deffn Command x-set-selection type data ++This function sets a ``selection'' in the X server. It takes two ++arguments: a selection type @var{type}, and the value to assign to it, ++@var{data}. If @var{data} is @code{nil}, it means to clear out the ++selection. Otherwise, @var{data} may be a string, a symbol, an integer ++(or a cons of two integers or list of two integers), an overlay, or a ++cons of two markers pointing to the same buffer. An overlay or a pair ++of markers stands for text in the overlay or between the markers. ++ ++The argument @var{data} may also be a vector of valid non-vector ++selection values. ++ ++Each possible @var{type} has its own selection value, which changes ++independently. The usual values of @var{type} are @code{PRIMARY}, ++@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case ++names, in accord with X Window System conventions. If @var{type} is ++@code{nil}, that stands for @code{PRIMARY}. ++ ++This function returns @var{data}. ++@end deffn ++ ++@defun x-get-selection &optional type data-type ++This function accesses selections set up by Emacs or by other X ++clients. It takes two optional arguments, @var{type} and ++@var{data-type}. The default for @var{type}, the selection type, is ++@code{PRIMARY}. ++ ++The @var{data-type} argument specifies the form of data conversion to ++use, to convert the raw data obtained from another X client into Lisp ++data. Meaningful values include @code{TEXT}, @code{STRING}, ++@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE}, ++@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME}, ++@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS}, ++@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and ++@code{INTEGER}. (These are symbols with upper-case names in accord ++with X conventions.) The default for @var{data-type} is ++@code{STRING}. ++@end defun ++ ++@cindex cut buffer ++The X server also has a set of eight numbered @dfn{cut buffers} which can ++store text or other data being moved between applications. Cut buffers ++are considered obsolete, but Emacs supports them for the sake of X ++clients that still use them. Cut buffers are numbered from 0 to 7. ++ ++@defun x-get-cut-buffer &optional n ++This function returns the contents of cut buffer number @var{n}. ++If omitted @var{n} defaults to 0. ++@end defun ++ ++@defun x-set-cut-buffer string &optional push ++@anchor{Definition of x-set-cut-buffer} ++This function stores @var{string} into the first cut buffer (cut buffer ++0). If @var{push} is @code{nil}, only the first cut buffer is changed. ++If @var{push} is non-@code{nil}, that says to move the values down ++through the series of cut buffers, much like the way successive kills in ++Emacs move down the kill ring. In other words, the previous value of ++the first cut buffer moves into the second cut buffer, and the second to ++the third, and so on through all eight cut buffers. ++@end defun ++ ++@defopt selection-coding-system ++This variable specifies the coding system to use when reading and ++writing selections or the clipboard. @xref{Coding ++Systems}. The default is @code{compound-text-with-extensions}, which ++converts to the text representation that X11 normally uses. ++@end defopt ++ ++@cindex clipboard support (for MS-Windows) ++When Emacs runs on MS-Windows, it does not implement X selections in ++general, but it does support the clipboard. @code{x-get-selection} ++and @code{x-set-selection} on MS-Windows support the text data type ++only; if the clipboard holds other types of data, Emacs treats the ++clipboard as empty. ++ ++@defopt x-select-enable-clipboard ++If this is non-@code{nil}, the Emacs yank functions consult the ++clipboard before the primary selection, and the kill functions store in ++the clipboard as well as the primary selection. Otherwise they do not ++access the clipboard at all. The default is @code{nil} on most systems, ++but @code{t} on MS-Windows. ++@end defopt ++ ++@node Drag and Drop ++@section Drag and Drop ++ ++@vindex x-dnd-test-function ++@vindex x-dnd-known-types ++ When a user drags something from another application over Emacs, that other ++application expects Emacs to tell it if Emacs can handle the data that is ++dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine ++what to reply. The default value is @code{x-dnd-default-test-function} ++which accepts drops if the type of the data to be dropped is present in ++@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or ++@code{x-dnd-known-types} if you want Emacs to accept or reject drops based ++on some other criteria. ++ ++@vindex x-dnd-types-alist ++ If you want to change the way Emacs handles drop of different types ++or add a new type, customize @code{x-dnd-types-alist}. This requires ++detailed knowledge of what types other applications use for drag and ++drop. ++ ++@vindex dnd-protocol-alist ++ When an URL is dropped on Emacs it may be a file, but it may also be ++another URL type (ftp, http, etc.). Emacs first checks ++@code{dnd-protocol-alist} to determine what to do with the URL. If ++there is no match there and if @code{browse-url-browser-function} is ++an alist, Emacs looks for a match there. If no match is found the ++text for the URL is inserted. If you want to alter Emacs behavior, ++you can customize these variables. ++ ++@node Color Names ++@section Color Names ++ ++@cindex color names ++@cindex specify color ++@cindex numerical RGB color specification ++ A color name is text (usually in a string) that specifies a color. ++Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc., ++are allowed; use @kbd{M-x list-colors-display} to see a list of ++defined names. You can also specify colors numerically in forms such ++as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where ++@var{r} specifies the red level, @var{g} specifies the green level, ++and @var{b} specifies the blue level. You can use either one, two, ++three, or four hex digits for @var{r}; then you must use the same ++number of hex digits for all @var{g} and @var{b} as well, making ++either 3, 6, 9 or 12 hex digits in all. (See the documentation of the ++X Window System for more details about numerical RGB specification of ++colors.) ++ ++ These functions provide a way to determine which color names are ++valid, and what they look like. In some cases, the value depends on the ++@dfn{selected frame}, as described below; see @ref{Input Focus}, for the ++meaning of the term ``selected frame.'' ++ ++ To read user input of color names with completion, use ++@code{read-color} (@pxref{High-Level Completion, read-color}). ++ ++@defun color-defined-p color &optional frame ++This function reports whether a color name is meaningful. It returns ++@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says ++which frame's display to ask about; if @var{frame} is omitted or ++@code{nil}, the selected frame is used. ++ ++Note that this does not tell you whether the display you are using ++really supports that color. When using X, you can ask for any defined ++color on any kind of display, and you will get some result---typically, ++the closest it can do. To determine whether a frame can really display ++a certain color, use @code{color-supported-p} (see below). ++ ++@findex x-color-defined-p ++This function used to be called @code{x-color-defined-p}, ++and that name is still supported as an alias. ++@end defun ++ ++@defun defined-colors &optional frame ++This function returns a list of the color names that are defined ++and supported on frame @var{frame} (default, the selected frame). ++If @var{frame} does not support colors, the value is @code{nil}. ++ ++@findex x-defined-colors ++This function used to be called @code{x-defined-colors}, ++and that name is still supported as an alias. ++@end defun ++ ++@defun color-supported-p color &optional frame background-p ++This returns @code{t} if @var{frame} can really display the color ++@var{color} (or at least something close to it). If @var{frame} is ++omitted or @code{nil}, the question applies to the selected frame. ++ ++Some terminals support a different set of colors for foreground and ++background. If @var{background-p} is non-@code{nil}, that means you are ++asking whether @var{color} can be used as a background; otherwise you ++are asking whether it can be used as a foreground. ++ ++The argument @var{color} must be a valid color name. ++@end defun ++ ++@defun color-gray-p color &optional frame ++This returns @code{t} if @var{color} is a shade of gray, as defined on ++@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the ++question applies to the selected frame. If @var{color} is not a valid ++color name, this function returns @code{nil}. ++@end defun ++ ++@defun color-values color &optional frame ++@cindex rgb value ++This function returns a value that describes what @var{color} should ++ideally look like on @var{frame}. If @var{color} is defined, the ++value is a list of three integers, which give the amount of red, the ++amount of green, and the amount of blue. Each integer ranges in ++principle from 0 to 65535, but some displays may not use the full ++range. This three-element list is called the @dfn{rgb values} of the ++color. ++ ++If @var{color} is not defined, the value is @code{nil}. ++ ++@example ++(color-values "black") ++ @result{} (0 0 0) ++(color-values "white") ++ @result{} (65280 65280 65280) ++(color-values "red") ++ @result{} (65280 0 0) ++(color-values "pink") ++ @result{} (65280 49152 51968) ++(color-values "hungry") ++ @result{} nil ++@end example ++ ++The color values are returned for @var{frame}'s display. If ++@var{frame} is omitted or @code{nil}, the information is returned for ++the selected frame's display. If the frame cannot display colors, the ++value is @code{nil}. ++ ++@findex x-color-values ++This function used to be called @code{x-color-values}, ++and that name is still supported as an alias. ++@end defun ++ ++@node Text Terminal Colors ++@section Text Terminal Colors ++@cindex colors on text-only terminals ++ ++ Text-only terminals usually support only a small number of colors, ++and the computer uses small integers to select colors on the terminal. ++This means that the computer cannot reliably tell what the selected ++color looks like; instead, you have to inform your application which ++small integers correspond to which colors. However, Emacs does know ++the standard set of colors and will try to use them automatically. ++ ++ The functions described in this section control how terminal colors ++are used by Emacs. ++ ++ Several of these functions use or return @dfn{rgb values}, described ++in @ref{Color Names}. ++ ++ These functions accept a display (either a frame or the name of a ++terminal) as an optional argument. We hope in the future to make ++Emacs support different colors on different text-only terminals; then ++this argument will specify which terminal to operate on (the default ++being the selected frame's terminal; @pxref{Input Focus}). At ++present, though, the @var{frame} argument has no effect. ++ ++@defun tty-color-define name number &optional rgb frame ++This function associates the color name @var{name} with ++color number @var{number} on the terminal. ++ ++The optional argument @var{rgb}, if specified, is an rgb value, a list ++of three numbers that specify what the color actually looks like. ++If you do not specify @var{rgb}, then this color cannot be used by ++@code{tty-color-approximate} to approximate other colors, because ++Emacs will not know what it looks like. ++@end defun ++ ++@defun tty-color-clear &optional frame ++This function clears the table of defined colors for a text-only terminal. ++@end defun ++ ++@defun tty-color-alist &optional frame ++This function returns an alist recording the known colors supported by a ++text-only terminal. ++ ++Each element has the form @code{(@var{name} @var{number} . @var{rgb})} ++or @code{(@var{name} @var{number})}. Here, @var{name} is the color ++name, @var{number} is the number used to specify it to the terminal. ++If present, @var{rgb} is a list of three color values (for red, green, ++and blue) that says what the color actually looks like. ++@end defun ++ ++@defun tty-color-approximate rgb &optional frame ++This function finds the closest color, among the known colors ++supported for @var{display}, to that described by the rgb value ++@var{rgb} (a list of color values). The return value is an element of ++@code{tty-color-alist}. ++@end defun ++ ++@defun tty-color-translate color &optional frame ++This function finds the closest color to @var{color} among the known ++colors supported for @var{display} and returns its index (an integer). ++If the name @var{color} is not defined, the value is @code{nil}. ++@end defun ++ ++@node Resources ++@section X Resources ++ ++@defun x-get-resource attribute class &optional component subclass ++The function @code{x-get-resource} retrieves a resource value from the X ++Window defaults database. ++ ++Resources are indexed by a combination of a @dfn{key} and a @dfn{class}. ++This function searches using a key of the form ++@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name ++under which Emacs was invoked), and using @samp{Emacs.@var{class}} as ++the class. ++ ++The optional arguments @var{component} and @var{subclass} add to the key ++and the class, respectively. You must specify both of them or neither. ++If you specify them, the key is ++@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is ++@samp{Emacs.@var{class}.@var{subclass}}. ++@end defun ++ ++@defvar x-resource-class ++This variable specifies the application name that @code{x-get-resource} ++should look up. The default value is @code{"Emacs"}. You can examine X ++resources for application names other than ``Emacs'' by binding this ++variable to some other string, around a call to @code{x-get-resource}. ++@end defvar ++ ++@defvar x-resource-name ++This variable specifies the instance name that @code{x-get-resource} ++should look up. The default value is the name Emacs was invoked with, ++or the value specified with the @samp{-name} or @samp{-rn} switches. ++@end defvar ++ ++To illustrate some of the above, suppose that you have the line: ++ ++@example ++xterm.vt100.background: yellow ++@end example ++ ++@noindent ++in your X resources file (whose name is usually @file{~/.Xdefaults} ++or @file{~/.Xresources}). Then: ++ ++@example ++@group ++(let ((x-resource-class "XTerm") (x-resource-name "xterm")) ++ (x-get-resource "vt100.background" "VT100.Background")) ++ @result{} "yellow" ++@end group ++@group ++(let ((x-resource-class "XTerm") (x-resource-name "xterm")) ++ (x-get-resource "background" "VT100" "vt100" "Background")) ++ @result{} "yellow" ++@end group ++@end example ++ ++ @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. ++ ++@node Display Feature Testing ++@section Display Feature Testing ++@cindex display feature testing ++ ++ The functions in this section describe the basic capabilities of a ++particular display. Lisp programs can use them to adapt their behavior ++to what the display can do. For example, a program that ordinarily uses ++a popup menu could use the minibuffer if popup menus are not supported. ++ ++ The optional argument @var{display} in these functions specifies which ++display to ask the question about. It can be a display name, a frame ++(which designates the display that frame is on), or @code{nil} (which ++refers to the selected frame's display, @pxref{Input Focus}). ++ ++ @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to ++obtain information about displays. ++ ++@defun display-popup-menus-p &optional display ++This function returns @code{t} if popup menus are supported on ++@var{display}, @code{nil} if not. Support for popup menus requires that ++the mouse be available, since the user cannot choose menu items without ++a mouse. ++@end defun ++ ++@defun display-graphic-p &optional display ++This function returns @code{t} if @var{display} is a graphic display ++capable of displaying several frames and several different fonts at ++once. This is true for displays that use a window system such as X, and ++false for text-only terminals. ++@end defun ++ ++@defun display-mouse-p &optional display ++@cindex mouse, availability ++This function returns @code{t} if @var{display} has a mouse available, ++@code{nil} if not. ++@end defun ++ ++@defun display-color-p &optional display ++@findex x-display-color-p ++This function returns @code{t} if the screen is a color screen. ++It used to be called @code{x-display-color-p}, and that name ++is still supported as an alias. ++@end defun ++ ++@defun display-grayscale-p &optional display ++This function returns @code{t} if the screen can display shades of gray. ++(All color displays can do this.) ++@end defun ++ ++@defun display-supports-face-attributes-p attributes &optional display ++@anchor{Display Face Attribute Testing} ++This function returns non-@code{nil} if all the face attributes in ++@var{attributes} are supported (@pxref{Face Attributes}). ++ ++The definition of `supported' is somewhat heuristic, but basically ++means that a face containing all the attributes in @var{attributes}, ++when merged with the default face for display, can be represented in a ++way that's ++ ++@enumerate ++@item ++different in appearance than the default face, and ++ ++@item ++`close in spirit' to what the attributes specify, if not exact. ++@end enumerate ++ ++Point (2) implies that a @code{:weight black} attribute will be ++satisfied by any display that can display bold, as will ++@code{:foreground "yellow"} as long as some yellowish color can be ++displayed, but @code{:slant italic} will @emph{not} be satisfied by ++the tty display code's automatic substitution of a `dim' face for ++italic. ++@end defun ++ ++@defun display-selections-p &optional display ++This function returns @code{t} if @var{display} supports selections. ++Windowed displays normally support selections, but they may also be ++supported in some other cases. ++@end defun ++ ++@defun display-images-p &optional display ++This function returns @code{t} if @var{display} can display images. ++Windowed displays ought in principle to handle images, but some ++systems lack the support for that. On a display that does not support ++images, Emacs cannot display a tool bar. ++@end defun ++ ++@defun display-screens &optional display ++This function returns the number of screens associated with the display. ++@end defun ++ ++@defun display-pixel-height &optional display ++This function returns the height of the screen in pixels. ++On a character terminal, it gives the height in characters. ++ ++For graphical terminals, note that on ``multi-monitor'' setups this ++refers to the pixel width for all physical monitors associated with ++@var{display}. @xref{Multiple Terminals}. ++@end defun ++ ++@defun display-pixel-width &optional display ++This function returns the width of the screen in pixels. ++On a character terminal, it gives the width in characters. ++ ++For graphical terminals, note that on ``multi-monitor'' setups this ++refers to the pixel width for all physical monitors associated with ++@var{display}. @xref{Multiple Terminals}. ++@end defun ++ ++@defun display-mm-height &optional display ++This function returns the height of the screen in millimeters, ++or @code{nil} if Emacs cannot get that information. ++@end defun ++ ++@defun display-mm-width &optional display ++This function returns the width of the screen in millimeters, ++or @code{nil} if Emacs cannot get that information. ++@end defun ++ ++@defopt display-mm-dimensions-alist ++This variable allows the user to specify the dimensions of graphical ++displays returned by @code{display-mm-height} and ++@code{display-mm-width} in case the system provides incorrect values. ++@end defopt ++ ++@defun display-backing-store &optional display ++This function returns the backing store capability of the display. ++Backing store means recording the pixels of windows (and parts of ++windows) that are not exposed, so that when exposed they can be ++displayed very quickly. ++ ++Values can be the symbols @code{always}, @code{when-mapped}, or ++@code{not-useful}. The function can also return @code{nil} ++when the question is inapplicable to a certain kind of display. ++@end defun ++ ++@defun display-save-under &optional display ++This function returns non-@code{nil} if the display supports the ++SaveUnder feature. That feature is used by pop-up windows ++to save the pixels they obscure, so that they can pop down ++quickly. ++@end defun ++ ++@defun display-planes &optional display ++This function returns the number of planes the display supports. ++This is typically the number of bits per pixel. ++For a tty display, it is log to base two of the number of colors supported. ++@end defun ++ ++@defun display-visual-class &optional display ++This function returns the visual class for the screen. The value is one ++of the symbols @code{static-gray}, @code{gray-scale}, ++@code{static-color}, @code{pseudo-color}, @code{true-color}, and ++@code{direct-color}. ++@end defun ++ ++@defun display-color-cells &optional display ++This function returns the number of color cells the screen supports. ++@end defun ++ ++ These functions obtain additional information specifically ++about X displays. ++ ++@defun x-server-version &optional display ++This function returns the list of version numbers of the X server ++running the display. The value is a list of three integers: the major ++and minor version numbers of the X protocol, and the ++distributor-specific release number of the X server software itself. ++@end defun ++ ++@defun x-server-vendor &optional display ++This function returns the ``vendor'' that provided the X server ++software (as a string). Really this means whoever distributes the X ++server. ++ ++When the developers of X labelled software distributors as ++``vendors,'' they showed their false assumption that no system could ++ever be developed and distributed noncommercially. ++@end defun ++ ++@ignore ++@defvar x-no-window-manager ++This variable's value is @code{t} if no X window manager is in use. ++@end defvar ++@end ignore ++ ++@ignore ++@item ++The functions @code{x-pixel-width} and @code{x-pixel-height} return the ++width and height of an X Window frame, measured in pixels. ++@end ignore ++ ++ ++@ignore ++ arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba ++@end ignore +diff --git a/doc/lispref/front-cover-1.texi b/doc/lispref/front-cover-1.texi +new file mode 100644 +index 0000000..5c9f435 +--- /dev/null ++++ b/doc/lispref/front-cover-1.texi +@@ -0,0 +1,56 @@ ++\input texinfo @c -*-texinfo-*- ++@comment %**start of header ++@setfilename front1.info ++@settitle GNU Emacs Lisp Reference Manual ++@smallbook ++@comment %**end of header ++ ++@titlepage ++. ++@sp 2 ++@center @titlefont{The} ++@sp 1 ++@center @titlefont{GNU} ++@sp 1 ++@center @titlefont{Emacs Lisp} ++@sp 1 ++@center @titlefont{Reference} ++@sp 1 ++@center @titlefont{Manual} ++@sp 2 ++@center GNU Emacs Version 19.29 ++@center for Unix Users ++@center Edition 2.4, June 1995 ++@sp 2 ++@center @titlefont{Volume 1} ++@sp 2 ++@center by Bil Lewis, Dan LaLiberte, ++@center and the GNU Manual Group ++@page ++. ++@sp 5 ++@center @titlefont{The} ++@sp 1 ++@center @titlefont{GNU} ++@sp 1 ++@center @titlefont{Emacs Lisp} ++@sp 1 ++@center @titlefont{Reference} ++@sp 1 ++@center @titlefont{Manual} ++@sp 2 ++@center GNU Emacs Version 19.29 ++@center for Unix Users ++@center Edition 2.4, June 1995 ++@sp 2 ++@center @titlefont{Volume 2} ++@sp 2 ++@center by Bil Lewis, Dan LaLiberte, ++@center and the GNU Manual Group ++ ++@end titlepage ++@bye ++ ++@ignore ++ arch-tag: 5182b306-c403-4e4f-ba24-e1911bc6da9d ++@end ignore +diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi +new file mode 100644 +index 0000000..36a937c +--- /dev/null ++++ b/doc/lispref/functions.texi +@@ -0,0 +1,1501 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/functions ++@node Functions, Macros, Variables, Top ++@chapter Functions ++ ++ A Lisp program is composed mainly of Lisp functions. This chapter ++explains what functions are, how they accept arguments, and how to ++define them. ++ ++@menu ++* What Is a Function:: Lisp functions vs. primitives; terminology. ++* Lambda Expressions:: How functions are expressed as Lisp objects. ++* Function Names:: A symbol can serve as the name of a function. ++* Defining Functions:: Lisp expressions for defining functions. ++* Calling Functions:: How to use an existing function. ++* Mapping Functions:: Applying a function to each element of a list, etc. ++* Anonymous Functions:: Lambda expressions are functions with no names. ++* Function Cells:: Accessing or setting the function definition ++ of a symbol. ++* Obsolete Functions:: Declaring functions obsolete. ++* Inline Functions:: Defining functions that the compiler will open code. ++* Declaring Functions:: Telling the compiler that a function is defined. ++* Function Safety:: Determining whether a function is safe to call. ++* Related Topics:: Cross-references to specific Lisp primitives ++ that have a special bearing on how functions work. ++@end menu ++ ++@node What Is a Function ++@section What Is a Function? ++ ++ In a general sense, a function is a rule for carrying on a computation ++given several values called @dfn{arguments}. The result of the ++computation is called the value of the function. The computation can ++also have side effects: lasting changes in the values of variables or ++the contents of data structures. ++ ++ Here are important terms for functions in Emacs Lisp and for other ++function-like objects. ++ ++@table @dfn ++@item function ++@cindex function ++In Emacs Lisp, a @dfn{function} is anything that can be applied to ++arguments in a Lisp program. In some cases, we use it more ++specifically to mean a function written in Lisp. Special forms and ++macros are not functions. ++ ++@item primitive ++@cindex primitive ++@cindex subr ++@cindex built-in function ++A @dfn{primitive} is a function callable from Lisp that is written in C, ++such as @code{car} or @code{append}. These functions are also called ++@dfn{built-in functions}, or @dfn{subrs}. (Special forms are also ++considered primitives.) ++ ++Usually the reason we implement a function as a primitive is either ++because it is fundamental, because it provides a low-level interface ++to operating system services, or because it needs to run fast. ++Primitives can be modified or added only by changing the C sources and ++recompiling the editor. See @ref{Writing Emacs Primitives}. ++ ++@item lambda expression ++A @dfn{lambda expression} is a function written in Lisp. ++These are described in the following section. ++@ifnottex ++@xref{Lambda Expressions}. ++@end ifnottex ++ ++@item special form ++A @dfn{special form} is a primitive that is like a function but does not ++evaluate all of its arguments in the usual way. It may evaluate only ++some of the arguments, or may evaluate them in an unusual order, or ++several times. Many special forms are described in @ref{Control ++Structures}. ++ ++@item macro ++@cindex macro ++A @dfn{macro} is a construct defined in Lisp by the programmer. It ++differs from a function in that it translates a Lisp expression that you ++write into an equivalent expression to be evaluated instead of the ++original expression. Macros enable Lisp programmers to do the sorts of ++things that special forms can do. @xref{Macros}, for how to define and ++use macros. ++ ++@item command ++@cindex command ++A @dfn{command} is an object that @code{command-execute} can invoke; it ++is a possible definition for a key sequence. Some functions are ++commands; a function written in Lisp is a command if it contains an ++interactive declaration (@pxref{Defining Commands}). Such a function ++can be called from Lisp expressions like other functions; in this case, ++the fact that the function is a command makes no difference. ++ ++Keyboard macros (strings and vectors) are commands also, even though ++they are not functions. A symbol is a command if its function ++definition is a command; such symbols can be invoked with @kbd{M-x}. ++The symbol is a function as well if the definition is a function. ++@xref{Interactive Call}. ++ ++@item keystroke command ++@cindex keystroke command ++A @dfn{keystroke command} is a command that is bound to a key sequence ++(typically one to three keystrokes). The distinction is made here ++merely to avoid confusion with the meaning of ``command'' in non-Emacs ++editors; for Lisp programs, the distinction is normally unimportant. ++ ++@item byte-code function ++A @dfn{byte-code function} is a function that has been compiled by the ++byte compiler. @xref{Byte-Code Type}. ++@end table ++ ++@defun functionp object ++This function returns @code{t} if @var{object} is any kind of ++function, i.e.@: can be passed to @code{funcall}. Note that ++@code{functionp} returns @code{nil} for special forms (@pxref{Special ++Forms}). ++@end defun ++ ++Unlike @code{functionp}, the next three functions do @emph{not} ++treat a symbol as its function definition. ++ ++@defun subrp object ++This function returns @code{t} if @var{object} is a built-in function ++(i.e., a Lisp primitive). ++ ++@example ++@group ++(subrp 'message) ; @r{@code{message} is a symbol,} ++ @result{} nil ; @r{not a subr object.} ++@end group ++@group ++(subrp (symbol-function 'message)) ++ @result{} t ++@end group ++@end example ++@end defun ++ ++@defun byte-code-function-p object ++This function returns @code{t} if @var{object} is a byte-code ++function. For example: ++ ++@example ++@group ++(byte-code-function-p (symbol-function 'next-line)) ++ @result{} t ++@end group ++@end example ++@end defun ++ ++@defun subr-arity subr ++This function provides information about the argument list of a ++primitive, @var{subr}. The returned value is a pair ++@code{(@var{min} . @var{max})}. @var{min} is the minimum number of ++args. @var{max} is the maximum number or the symbol @code{many}, for a ++function with @code{&rest} arguments, or the symbol @code{unevalled} if ++@var{subr} is a special form. ++@end defun ++ ++@node Lambda Expressions ++@section Lambda Expressions ++@cindex lambda expression ++ ++ A function written in Lisp is a list that looks like this: ++ ++@example ++(lambda (@var{arg-variables}@dots{}) ++ @r{[}@var{documentation-string}@r{]} ++ @r{[}@var{interactive-declaration}@r{]} ++ @var{body-forms}@dots{}) ++@end example ++ ++@noindent ++Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it ++actually is valid as an expression---it evaluates to itself. In some ++other Lisp dialects, a lambda expression is not a valid expression at ++all. In either case, its main use is not to be evaluated as an ++expression, but to be called as a function. ++ ++@menu ++* Lambda Components:: The parts of a lambda expression. ++* Simple Lambda:: A simple example. ++* Argument List:: Details and special features of argument lists. ++* Function Documentation:: How to put documentation in a function. ++@end menu ++ ++@node Lambda Components ++@subsection Components of a Lambda Expression ++ ++@ifnottex ++ ++ A function written in Lisp (a ``lambda expression'') is a list that ++looks like this: ++ ++@example ++(lambda (@var{arg-variables}@dots{}) ++ [@var{documentation-string}] ++ [@var{interactive-declaration}] ++ @var{body-forms}@dots{}) ++@end example ++@end ifnottex ++ ++@cindex lambda list ++ The first element of a lambda expression is always the symbol ++@code{lambda}. This indicates that the list represents a function. The ++reason functions are defined to start with @code{lambda} is so that ++other lists, intended for other uses, will not accidentally be valid as ++functions. ++ ++ The second element is a list of symbols---the argument variable names. ++This is called the @dfn{lambda list}. When a Lisp function is called, ++the argument values are matched up against the variables in the lambda ++list, which are given local bindings with the values provided. ++@xref{Local Variables}. ++ ++ The documentation string is a Lisp string object placed within the ++function definition to describe the function for the Emacs help ++facilities. @xref{Function Documentation}. ++ ++ The interactive declaration is a list of the form @code{(interactive ++@var{code-string})}. This declares how to provide arguments if the ++function is used interactively. Functions with this declaration are called ++@dfn{commands}; they can be called using @kbd{M-x} or bound to a key. ++Functions not intended to be called in this way should not have interactive ++declarations. @xref{Defining Commands}, for how to write an interactive ++declaration. ++ ++@cindex body of function ++ The rest of the elements are the @dfn{body} of the function: the Lisp ++code to do the work of the function (or, as a Lisp programmer would say, ++``a list of Lisp forms to evaluate''). The value returned by the ++function is the value returned by the last element of the body. ++ ++@node Simple Lambda ++@subsection A Simple Lambda-Expression Example ++ ++ Consider for example the following function: ++ ++@example ++(lambda (a b c) (+ a b c)) ++@end example ++ ++@noindent ++We can call this function by writing it as the @sc{car} of an ++expression, like this: ++ ++@example ++@group ++((lambda (a b c) (+ a b c)) ++ 1 2 3) ++@end group ++@end example ++ ++@noindent ++This call evaluates the body of the lambda expression with the variable ++@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3. ++Evaluation of the body adds these three numbers, producing the result 6; ++therefore, this call to the function returns the value 6. ++ ++ Note that the arguments can be the results of other function calls, as in ++this example: ++ ++@example ++@group ++((lambda (a b c) (+ a b c)) ++ 1 (* 2 3) (- 5 4)) ++@end group ++@end example ++ ++@noindent ++This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5 ++4)} from left to right. Then it applies the lambda expression to the ++argument values 1, 6 and 1 to produce the value 8. ++ ++ It is not often useful to write a lambda expression as the @sc{car} of ++a form in this way. You can get the same result, of making local ++variables and giving them values, using the special form @code{let} ++(@pxref{Local Variables}). And @code{let} is clearer and easier to use. ++In practice, lambda expressions are either stored as the function ++definitions of symbols, to produce named functions, or passed as ++arguments to other functions (@pxref{Anonymous Functions}). ++ ++ However, calls to explicit lambda expressions were very useful in the ++old days of Lisp, before the special form @code{let} was invented. At ++that time, they were the only way to bind and initialize local ++variables. ++ ++@node Argument List ++@subsection Other Features of Argument Lists ++@kindex wrong-number-of-arguments ++@cindex argument binding ++@cindex binding arguments ++@cindex argument lists, features ++ ++ Our simple sample function, @code{(lambda (a b c) (+ a b c))}, ++specifies three argument variables, so it must be called with three ++arguments: if you try to call it with only two arguments or four ++arguments, you get a @code{wrong-number-of-arguments} error. ++ ++ It is often convenient to write a function that allows certain ++arguments to be omitted. For example, the function @code{substring} ++accepts three arguments---a string, the start index and the end ++index---but the third argument defaults to the @var{length} of the ++string if you omit it. It is also convenient for certain functions to ++accept an indefinite number of arguments, as the functions @code{list} ++and @code{+} do. ++ ++@cindex optional arguments ++@cindex rest arguments ++@kindex &optional ++@kindex &rest ++ To specify optional arguments that may be omitted when a function ++is called, simply include the keyword @code{&optional} before the optional ++arguments. To specify a list of zero or more extra arguments, include the ++keyword @code{&rest} before one final argument. ++ ++ Thus, the complete syntax for an argument list is as follows: ++ ++@example ++@group ++(@var{required-vars}@dots{} ++ @r{[}&optional @var{optional-vars}@dots{}@r{]} ++ @r{[}&rest @var{rest-var}@r{]}) ++@end group ++@end example ++ ++@noindent ++The square brackets indicate that the @code{&optional} and @code{&rest} ++clauses, and the variables that follow them, are optional. ++ ++ A call to the function requires one actual argument for each of the ++@var{required-vars}. There may be actual arguments for zero or more of ++the @var{optional-vars}, and there cannot be any actual arguments beyond ++that unless the lambda list uses @code{&rest}. In that case, there may ++be any number of extra actual arguments. ++ ++ If actual arguments for the optional and rest variables are omitted, ++then they always default to @code{nil}. There is no way for the ++function to distinguish between an explicit argument of @code{nil} and ++an omitted argument. However, the body of the function is free to ++consider @code{nil} an abbreviation for some other meaningful value. ++This is what @code{substring} does; @code{nil} as the third argument to ++@code{substring} means to use the length of the string supplied. ++ ++@cindex CL note---default optional arg ++@quotation ++@b{Common Lisp note:} Common Lisp allows the function to specify what ++default value to use when an optional argument is omitted; Emacs Lisp ++always uses @code{nil}. Emacs Lisp does not support ``supplied-p'' ++variables that tell you whether an argument was explicitly passed. ++@end quotation ++ ++ For example, an argument list that looks like this: ++ ++@example ++(a b &optional c d &rest e) ++@end example ++ ++@noindent ++binds @code{a} and @code{b} to the first two actual arguments, which are ++required. If one or two more arguments are provided, @code{c} and ++@code{d} are bound to them respectively; any arguments after the first ++four are collected into a list and @code{e} is bound to that list. If ++there are only two arguments, @code{c} is @code{nil}; if two or three ++arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e} ++is @code{nil}. ++ ++ There is no way to have required arguments following optional ++ones---it would not make sense. To see why this must be so, suppose ++that @code{c} in the example were optional and @code{d} were required. ++Suppose three actual arguments are given; which variable would the ++third argument be for? Would it be used for the @var{c}, or for ++@var{d}? One can argue for both possibilities. Similarly, it makes ++no sense to have any more arguments (either required or optional) ++after a @code{&rest} argument. ++ ++ Here are some examples of argument lists and proper calls: ++ ++@smallexample ++((lambda (n) (1+ n)) ; @r{One required:} ++ 1) ; @r{requires exactly one argument.} ++ @result{} 2 ++((lambda (n &optional n1) ; @r{One required and one optional:} ++ (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.} ++ 1 2) ++ @result{} 3 ++((lambda (n &rest ns) ; @r{One required and one rest:} ++ (+ n (apply '+ ns))) ; @r{1 or more arguments.} ++ 1 2 3 4 5) ++ @result{} 15 ++@end smallexample ++ ++@node Function Documentation ++@subsection Documentation Strings of Functions ++@cindex documentation of function ++ ++ A lambda expression may optionally have a @dfn{documentation string} just ++after the lambda list. This string does not affect execution of the ++function; it is a kind of comment, but a systematized comment which ++actually appears inside the Lisp world and can be used by the Emacs help ++facilities. @xref{Documentation}, for how the @var{documentation-string} is ++accessed. ++ ++ It is a good idea to provide documentation strings for all the ++functions in your program, even those that are called only from within ++your program. Documentation strings are like comments, except that they ++are easier to access. ++ ++ The first line of the documentation string should stand on its own, ++because @code{apropos} displays just this first line. It should consist ++of one or two complete sentences that summarize the function's purpose. ++ ++ The start of the documentation string is usually indented in the ++source file, but since these spaces come before the starting ++double-quote, they are not part of the string. Some people make a ++practice of indenting any additional lines of the string so that the ++text lines up in the program source. @emph{That is a mistake.} The ++indentation of the following lines is inside the string; what looks ++nice in the source code will look ugly when displayed by the help ++commands. ++ ++ You may wonder how the documentation string could be optional, since ++there are required components of the function that follow it (the body). ++Since evaluation of a string returns that string, without any side effects, ++it has no effect if it is not the last form in the body. Thus, in ++practice, there is no confusion between the first form of the body and the ++documentation string; if the only body form is a string then it serves both ++as the return value and as the documentation. ++ ++ The last line of the documentation string can specify calling ++conventions different from the actual function arguments. Write ++text like this: ++ ++@example ++\(fn @var{arglist}) ++@end example ++ ++@noindent ++following a blank line, at the beginning of the line, with no newline ++following it inside the documentation string. (The @samp{\} is used ++to avoid confusing the Emacs motion commands.) The calling convention ++specified in this way appears in help messages in place of the one ++derived from the actual arguments of the function. ++ ++ This feature is particularly useful for macro definitions, since the ++arguments written in a macro definition often do not correspond to the ++way users think of the parts of the macro call. ++ ++@node Function Names ++@section Naming a Function ++@cindex function definition ++@cindex named function ++@cindex function name ++ ++ In most computer languages, every function has a name; the idea of a ++function without a name is nonsensical. In Lisp, a function in the ++strictest sense has no name. It is simply a list whose first element is ++@code{lambda}, a byte-code function object, or a primitive subr-object. ++ ++ However, a symbol can serve as the name of a function. This happens ++when you put the function in the symbol's @dfn{function cell} ++(@pxref{Symbol Components}). Then the symbol itself becomes a valid, ++callable function, equivalent to the list or subr-object that its ++function cell refers to. The contents of the function cell are also ++called the symbol's @dfn{function definition}. The procedure of using a ++symbol's function definition in place of the symbol is called ++@dfn{symbol function indirection}; see @ref{Function Indirection}. ++ ++ In practice, nearly all functions are given names in this way and ++referred to through their names. For example, the symbol @code{car} works ++as a function and does what it does because the primitive subr-object ++@code{#} is stored in its function cell. ++ ++ We give functions names because it is convenient to refer to them by ++their names in Lisp expressions. For primitive subr-objects such as ++@code{#}, names are the only way you can refer to them: there ++is no read syntax for such objects. For functions written in Lisp, the ++name is more convenient to use in a call than an explicit lambda ++expression. Also, a function with a name can refer to itself---it can ++be recursive. Writing the function's name in its own definition is much ++more convenient than making the function definition point to itself ++(something that is not impossible but that has various disadvantages in ++practice). ++ ++ We often identify functions with the symbols used to name them. For ++example, we often speak of ``the function @code{car},'' not ++distinguishing between the symbol @code{car} and the primitive ++subr-object that is its function definition. For most purposes, the ++distinction is not important. ++ ++ Even so, keep in mind that a function need not have a unique name. While ++a given function object @emph{usually} appears in the function cell of only ++one symbol, this is just a matter of convenience. It is easy to store ++it in several symbols using @code{fset}; then each of the symbols is ++equally well a name for the same function. ++ ++ A symbol used as a function name may also be used as a variable; these ++two uses of a symbol are independent and do not conflict. (Some Lisp ++dialects, such as Scheme, do not distinguish between a symbol's value ++and its function definition; a symbol's value as a variable is also its ++function definition.) If you have not given a symbol a function ++definition, you cannot use it as a function; whether the symbol has a ++value as a variable makes no difference to this. ++ ++@node Defining Functions ++@section Defining Functions ++@cindex defining a function ++ ++ We usually give a name to a function when it is first created. This ++is called @dfn{defining a function}, and it is done with the ++@code{defun} special form. ++ ++@defspec defun name argument-list body-forms ++@code{defun} is the usual way to define new Lisp functions. It ++defines the symbol @var{name} as a function that looks like this: ++ ++@example ++(lambda @var{argument-list} . @var{body-forms}) ++@end example ++ ++@code{defun} stores this lambda expression in the function cell of ++@var{name}. It returns the value @var{name}, but usually we ignore this ++value. ++ ++As described previously, @var{argument-list} is a list of argument ++names and may include the keywords @code{&optional} and @code{&rest} ++(@pxref{Lambda Expressions}). Also, the first two of the ++@var{body-forms} may be a documentation string and an interactive ++declaration. ++ ++There is no conflict if the same symbol @var{name} is also used as a ++variable, since the symbol's value cell is independent of the function ++cell. @xref{Symbol Components}. ++ ++Here are some examples: ++ ++@example ++@group ++(defun foo () 5) ++ @result{} foo ++@end group ++@group ++(foo) ++ @result{} 5 ++@end group ++ ++@group ++(defun bar (a &optional b &rest c) ++ (list a b c)) ++ @result{} bar ++@end group ++@group ++(bar 1 2 3 4 5) ++ @result{} (1 2 (3 4 5)) ++@end group ++@group ++(bar 1) ++ @result{} (1 nil nil) ++@end group ++@group ++(bar) ++@error{} Wrong number of arguments. ++@end group ++ ++@group ++(defun capitalize-backwards () ++ "Upcase the last letter of a word." ++ (interactive) ++ (backward-word 1) ++ (forward-word 1) ++ (backward-char 1) ++ (capitalize-word 1)) ++ @result{} capitalize-backwards ++@end group ++@end example ++ ++Be careful not to redefine existing functions unintentionally. ++@code{defun} redefines even primitive functions such as @code{car} ++without any hesitation or notification. Redefining a function already ++defined is often done deliberately, and there is no way to distinguish ++deliberate redefinition from unintentional redefinition. ++@end defspec ++ ++@cindex function aliases ++@defun defalias name definition &optional docstring ++@anchor{Definition of defalias} ++This special form defines the symbol @var{name} as a function, with ++definition @var{definition} (which can be any valid Lisp function). ++It returns @var{definition}. ++ ++If @var{docstring} is non-@code{nil}, it becomes the function ++documentation of @var{name}. Otherwise, any documentation provided by ++@var{definition} is used. ++ ++The proper place to use @code{defalias} is where a specific function ++name is being defined---especially where that name appears explicitly in ++the source file being loaded. This is because @code{defalias} records ++which file defined the function, just like @code{defun} ++(@pxref{Unloading}). ++ ++By contrast, in programs that manipulate function definitions for other ++purposes, it is better to use @code{fset}, which does not keep such ++records. @xref{Function Cells}. ++@end defun ++ ++ You cannot create a new primitive function with @code{defun} or ++@code{defalias}, but you can use them to change the function definition of ++any symbol, even one such as @code{car} or @code{x-popup-menu} whose ++normal definition is a primitive. However, this is risky: for ++instance, it is next to impossible to redefine @code{car} without ++breaking Lisp completely. Redefining an obscure function such as ++@code{x-popup-menu} is less dangerous, but it still may not work as ++you expect. If there are calls to the primitive from C code, they ++call the primitive's C definition directly, so changing the symbol's ++definition will have no effect on them. ++ ++ See also @code{defsubst}, which defines a function like @code{defun} ++and tells the Lisp compiler to open-code it. @xref{Inline Functions}. ++ ++@node Calling Functions ++@section Calling Functions ++@cindex function invocation ++@cindex calling a function ++ ++ Defining functions is only half the battle. Functions don't do ++anything until you @dfn{call} them, i.e., tell them to run. Calling a ++function is also known as @dfn{invocation}. ++ ++ The most common way of invoking a function is by evaluating a list. ++For example, evaluating the list @code{(concat "a" "b")} calls the ++function @code{concat} with arguments @code{"a"} and @code{"b"}. ++@xref{Evaluation}, for a description of evaluation. ++ ++ When you write a list as an expression in your program, you specify ++which function to call, and how many arguments to give it, in the text ++of the program. Usually that's just what you want. Occasionally you ++need to compute at run time which function to call. To do that, use ++the function @code{funcall}. When you also need to determine at run ++time how many arguments to pass, use @code{apply}. ++ ++@defun funcall function &rest arguments ++@code{funcall} calls @var{function} with @var{arguments}, and returns ++whatever @var{function} returns. ++ ++Since @code{funcall} is a function, all of its arguments, including ++@var{function}, are evaluated before @code{funcall} is called. This ++means that you can use any expression to obtain the function to be ++called. It also means that @code{funcall} does not see the ++expressions you write for the @var{arguments}, only their values. ++These values are @emph{not} evaluated a second time in the act of ++calling @var{function}; the operation of @code{funcall} is like the ++normal procedure for calling a function, once its arguments have ++already been evaluated. ++ ++The argument @var{function} must be either a Lisp function or a ++primitive function. Special forms and macros are not allowed, because ++they make sense only when given the ``unevaluated'' argument ++expressions. @code{funcall} cannot provide these because, as we saw ++above, it never knows them in the first place. ++ ++@example ++@group ++(setq f 'list) ++ @result{} list ++@end group ++@group ++(funcall f 'x 'y 'z) ++ @result{} (x y z) ++@end group ++@group ++(funcall f 'x 'y '(z)) ++ @result{} (x y (z)) ++@end group ++@group ++(funcall 'and t nil) ++@error{} Invalid function: # ++@end group ++@end example ++ ++Compare these examples with the examples of @code{apply}. ++@end defun ++ ++@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 objects, which are passed to @var{function} as separate ++arguments, rather than a single list. We say that @code{apply} ++@dfn{spreads} this list so that each individual element becomes an ++argument. ++ ++@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 ++@group ++(setq f 'list) ++ @result{} list ++@end group ++@group ++(apply f 'x 'y 'z) ++@error{} Wrong type argument: listp, z ++@end group ++@group ++(apply '+ 1 2 '(3 4)) ++ @result{} 10 ++@end group ++@group ++(apply '+ '(1 2 3 4)) ++ @result{} 10 ++@end group ++ ++@group ++(apply 'append '((a b c) nil (x y z) nil)) ++ @result{} (a b c x y z) ++@end group ++@end example ++ ++For an interesting example of using @code{apply}, see @ref{Definition ++of mapcar}. ++@end defun ++ ++@cindex partial application of functions ++@cindex currying ++ Sometimes it is useful to fix some of the function's arguments at ++certain values, and leave the rest of arguments for when the function ++is actually called. The act of fixing some of the function's ++arguments is called @dfn{partial application} of the function@footnote{ ++This is related to, but different from @dfn{currying}, which ++transforms a function that takes multiple arguments in such a way that ++it can be called as a chain of functions, each one with a single ++argument.}. ++The result is a new function that accepts the rest of ++arguments and calls the original function with all the arguments ++combined. ++ ++ Here's how to do partial application in Emacs Lisp: ++ ++@defun apply-partially func &rest args ++This function returns a new function which, when called, will call ++@var{func} with the list of arguments composed from @var{args} and ++additional arguments specified at the time of the call. If @var{func} ++accepts @var{n} arguments, then a call to @code{apply-partially} with ++@w{@code{@var{m} < @var{n}}} arguments will produce a new function of ++@w{@code{@var{n} - @var{m}}} arguments. ++ ++Here's how we could define the built-in function @code{1+}, if it ++didn't exist, using @code{apply-partially} and @code{+}, another ++built-in function: ++ ++@example ++@group ++(defalias '1+ (apply-partially '+ 1) ++ "Increment argument by one.") ++@end group ++@group ++(1+ 10) ++ @result{} 11 ++@end group ++@end example ++@end defun ++ ++@cindex functionals ++ It is common for Lisp functions to accept functions as arguments or ++find them in data structures (especially in hook variables and property ++lists) and call them using @code{funcall} or @code{apply}. Functions ++that accept function arguments are often called @dfn{functionals}. ++ ++ Sometimes, when you call a functional, it is useful to supply a no-op ++function as the argument. Here are two different kinds of no-op ++function: ++ ++@defun identity arg ++This function returns @var{arg} and has no side effects. ++@end defun ++ ++@defun ignore &rest args ++This function ignores any arguments and returns @code{nil}. ++@end defun ++ ++@node Mapping Functions ++@section Mapping Functions ++@cindex mapping functions ++ ++ A @dfn{mapping function} applies a given function (@emph{not} a ++special form or macro) to each element of a list or other collection. ++Emacs Lisp has several such functions; @code{mapcar} and ++@code{mapconcat}, which scan a list, are described here. ++@xref{Definition of mapatoms}, for the function @code{mapatoms} which ++maps over the symbols in an obarray. @xref{Definition of maphash}, ++for the function @code{maphash} which maps over key/value associations ++in a hash table. ++ ++ These mapping functions do not allow char-tables because a char-table ++is a sparse array whose nominal range of indices is very large. To map ++over a char-table in a way that deals properly with its sparse nature, ++use the function @code{map-char-table} (@pxref{Char-Tables}). ++ ++@defun mapcar function sequence ++@anchor{Definition of mapcar} ++@code{mapcar} applies @var{function} to each element of @var{sequence} ++in turn, and returns a list of the results. ++ ++The argument @var{sequence} can be any kind of sequence except a ++char-table; that is, a list, a vector, a bool-vector, or a string. The ++result is always a list. The length of the result is the same as the ++length of @var{sequence}. For example: ++ ++@smallexample ++@group ++(mapcar 'car '((a b) (c d) (e f))) ++ @result{} (a c e) ++(mapcar '1+ [1 2 3]) ++ @result{} (2 3 4) ++(mapcar 'char-to-string "abc") ++ @result{} ("a" "b" "c") ++@end group ++ ++@group ++;; @r{Call each function in @code{my-hooks}.} ++(mapcar 'funcall my-hooks) ++@end group ++ ++@group ++(defun mapcar* (function &rest args) ++ "Apply FUNCTION to successive cars of all ARGS. ++Return the list of results." ++ ;; @r{If no list is exhausted,} ++ (if (not (memq nil args)) ++ ;; @r{apply function to @sc{car}s.} ++ (cons (apply function (mapcar 'car args)) ++ (apply 'mapcar* function ++ ;; @r{Recurse for rest of elements.} ++ (mapcar 'cdr args))))) ++@end group ++ ++@group ++(mapcar* 'cons '(a b c) '(1 2 3 4)) ++ @result{} ((a . 1) (b . 2) (c . 3)) ++@end group ++@end smallexample ++@end defun ++ ++@defun mapc function sequence ++@code{mapc} is like @code{mapcar} except that @var{function} is used for ++side-effects only---the values it returns are ignored, not collected ++into a list. @code{mapc} always returns @var{sequence}. ++@end defun ++ ++@defun mapconcat function sequence separator ++@code{mapconcat} applies @var{function} to each element of ++@var{sequence}: the results, which must be strings, are concatenated. ++Between each pair of result strings, @code{mapconcat} inserts the string ++@var{separator}. Usually @var{separator} contains a space or comma or ++other suitable punctuation. ++ ++The argument @var{function} must be a function that can take one ++argument and return a string. The argument @var{sequence} can be any ++kind of sequence except a char-table; that is, a list, a vector, a ++bool-vector, or a string. ++ ++@smallexample ++@group ++(mapconcat 'symbol-name ++ '(The cat in the hat) ++ " ") ++ @result{} "The cat in the hat" ++@end group ++ ++@group ++(mapconcat (function (lambda (x) (format "%c" (1+ x)))) ++ "HAL-8000" ++ "") ++ @result{} "IBM.9111" ++@end group ++@end smallexample ++@end defun ++ ++@node Anonymous Functions ++@section Anonymous Functions ++@cindex anonymous function ++ ++ In Lisp, a function is a list that starts with @code{lambda}, a ++byte-code function compiled from such a list, or alternatively a ++primitive subr-object; names are ``extra.'' Although usually functions ++are defined with @code{defun} and given names at the same time, it is ++occasionally more concise to use an explicit lambda expression---an ++anonymous function. Such a list is valid wherever a function name is. ++ ++ Any method of creating such a list makes a valid function. Even this: ++ ++@smallexample ++@group ++(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x)))) ++@result{} (lambda (x) (+ 12 x)) ++@end group ++@end smallexample ++ ++@noindent ++This computes a list that looks like @code{(lambda (x) (+ 12 x))} and ++makes it the value (@emph{not} the function definition!) of ++@code{silly}. ++ ++ Here is how we might call this function: ++ ++@example ++@group ++(funcall silly 1) ++@result{} 13 ++@end group ++@end example ++ ++@noindent ++(It does @emph{not} work to write @code{(silly 1)}, because this function ++is not the @emph{function definition} of @code{silly}. We have not given ++@code{silly} any function definition, just a value as a variable.) ++ ++ Most of the time, anonymous functions are constants that appear in ++your program. For example, you might want to pass one as an argument to ++the function @code{mapcar}, which applies any given function to each ++element of a list. ++ ++ Here we define a function @code{change-property} which ++uses a function as its third argument: ++ ++@example ++@group ++(defun change-property (symbol prop function) ++ (let ((value (get symbol prop))) ++ (put symbol prop (funcall function value)))) ++@end group ++@end example ++ ++@noindent ++Here we define a function that uses @code{change-property}, ++passing it a function to double a number: ++ ++@example ++@group ++(defun double-property (symbol prop) ++ (change-property symbol prop '(lambda (x) (* 2 x)))) ++@end group ++@end example ++ ++@noindent ++In such cases, we usually use the special form @code{function} instead ++of simple quotation to quote the anonymous function, like this: ++ ++@example ++@group ++(defun double-property (symbol prop) ++ (change-property symbol prop ++ (function (lambda (x) (* 2 x))))) ++@end group ++@end example ++ ++Using @code{function} instead of @code{quote} makes a difference if you ++compile the function @code{double-property}. For example, if you ++compile the second definition of @code{double-property}, the anonymous ++function is compiled as well. By contrast, if you compile the first ++definition which uses ordinary @code{quote}, the argument passed to ++@code{change-property} is the precise list shown: ++ ++@example ++(lambda (x) (* x 2)) ++@end example ++ ++@noindent ++The Lisp compiler cannot assume this list is a function, even though it ++looks like one, since it does not know what @code{change-property} will ++do with the list. Perhaps it will check whether the @sc{car} of the third ++element is the symbol @code{*}! Using @code{function} tells the ++compiler it is safe to go ahead and compile the constant function. ++ ++ Nowadays it is possible to omit @code{function} entirely, like this: ++ ++@example ++@group ++(defun double-property (symbol prop) ++ (change-property symbol prop (lambda (x) (* 2 x)))) ++@end group ++@end example ++ ++@noindent ++This is because @code{lambda} itself implies @code{function}. ++ ++ We sometimes write @code{function} instead of @code{quote} when ++quoting the name of a function, but this usage is just a sort of ++comment: ++ ++@example ++(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol} ++@end example ++ ++@cindex @samp{#'} syntax ++ The read syntax @code{#'} is a short-hand for using @code{function}. ++For example, ++ ++@example ++#'(lambda (x) (* x x)) ++@end example ++ ++@noindent ++is equivalent to ++ ++@example ++(function (lambda (x) (* x x))) ++@end example ++ ++@defspec function function-object ++@cindex function quoting ++This special form returns @var{function-object} without evaluating it. ++In this, it is equivalent to @code{quote}. However, it serves as a ++note to the Emacs Lisp compiler that @var{function-object} is intended ++to be used only as a function, and therefore can safely be compiled. ++Contrast this with @code{quote}, in @ref{Quoting}. ++@end defspec ++ ++ @xref{describe-symbols example}, for a realistic example using ++@code{function} and an anonymous function. ++ ++@node Function Cells ++@section Accessing Function Cell Contents ++ ++ The @dfn{function definition} of a symbol is the object stored in the ++function cell of the symbol. The functions described here access, test, ++and set the function cell of symbols. ++ ++ See also the function @code{indirect-function}. @xref{Definition of ++indirect-function}. ++ ++@defun symbol-function symbol ++@kindex void-function ++This returns the object in the function cell of @var{symbol}. If the ++symbol's function cell is void, a @code{void-function} error is ++signaled. ++ ++This function does not check that the returned object is a legitimate ++function. ++ ++@example ++@group ++(defun bar (n) (+ n 2)) ++ @result{} bar ++@end group ++@group ++(symbol-function 'bar) ++ @result{} (lambda (n) (+ n 2)) ++@end group ++@group ++(fset 'baz 'bar) ++ @result{} bar ++@end group ++@group ++(symbol-function 'baz) ++ @result{} bar ++@end group ++@end example ++@end defun ++ ++@cindex void function cell ++ If you have never given a symbol any function definition, we say that ++that symbol's function cell is @dfn{void}. In other words, the function ++cell does not have any Lisp object in it. If you try to call such a symbol ++as a function, it signals a @code{void-function} error. ++ ++ Note that void is not the same as @code{nil} or the symbol ++@code{void}. The symbols @code{nil} and @code{void} are Lisp objects, ++and can be stored into a function cell just as any other object can be ++(and they can be valid functions if you define them in turn with ++@code{defun}). A void function cell contains no object whatsoever. ++ ++ You can test the voidness of a symbol's function definition with ++@code{fboundp}. After you have given a symbol a function definition, you ++can make it void once more using @code{fmakunbound}. ++ ++@defun fboundp symbol ++This function returns @code{t} if the symbol has an object in its ++function cell, @code{nil} otherwise. It does not check that the object ++is a legitimate function. ++@end defun ++ ++@defun fmakunbound symbol ++This function makes @var{symbol}'s function cell void, so that a ++subsequent attempt to access this cell will cause a ++@code{void-function} error. It returns @var{symbol}. (See also ++@code{makunbound}, in @ref{Void Variables}.) ++ ++@example ++@group ++(defun foo (x) x) ++ @result{} foo ++@end group ++@group ++(foo 1) ++ @result{}1 ++@end group ++@group ++(fmakunbound 'foo) ++ @result{} foo ++@end group ++@group ++(foo 1) ++@error{} Symbol's function definition is void: foo ++@end group ++@end example ++@end defun ++ ++@defun fset symbol definition ++This function stores @var{definition} in the function cell of ++@var{symbol}. The result is @var{definition}. Normally ++@var{definition} should be a function or the name of a function, but ++this is not checked. The argument @var{symbol} is an ordinary evaluated ++argument. ++ ++There are three normal uses of this function: ++ ++@itemize @bullet ++@item ++Copying one symbol's function definition to another---in other words, ++making an alternate name for a function. (If you think of this as the ++definition of the new name, you should use @code{defalias} instead of ++@code{fset}; see @ref{Definition of defalias}.) ++ ++@item ++Giving a symbol a function definition that is not a list and therefore ++cannot be made with @code{defun}. For example, you can use @code{fset} ++to give a symbol @code{s1} a function definition which is another symbol ++@code{s2}; then @code{s1} serves as an alias for whatever definition ++@code{s2} presently has. (Once again use @code{defalias} instead of ++@code{fset} if you think of this as the definition of @code{s1}.) ++ ++@item ++In constructs for defining or altering functions. If @code{defun} ++were not a primitive, it could be written in Lisp (as a macro) using ++@code{fset}. ++@end itemize ++ ++Here are examples of these uses: ++ ++@example ++@group ++;; @r{Save @code{foo}'s definition in @code{old-foo}.} ++(fset 'old-foo (symbol-function 'foo)) ++@end group ++ ++@group ++;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.} ++;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)} ++(fset 'xfirst 'car) ++ @result{} car ++@end group ++@group ++(xfirst '(1 2 3)) ++ @result{} 1 ++@end group ++@group ++(symbol-function 'xfirst) ++ @result{} car ++@end group ++@group ++(symbol-function (symbol-function 'xfirst)) ++ @result{} # ++@end group ++ ++@group ++;; @r{Define a named keyboard macro.} ++(fset 'kill-two-lines "\^u2\^k") ++ @result{} "\^u2\^k" ++@end group ++ ++@group ++;; @r{Here is a function that alters other functions.} ++(defun copy-function-definition (new old) ++ "Define NEW with the same function definition as OLD." ++ (fset new (symbol-function old))) ++@end group ++@end example ++@end defun ++ ++ @code{fset} is sometimes used to save the old definition of a ++function before redefining it. That permits the new definition to ++invoke the old definition. But it is unmodular and unclean for a Lisp ++file to redefine a function defined elsewhere. If you want to modify ++a function defined by another package, it is cleaner to use ++@code{defadvice} (@pxref{Advising Functions}). ++ ++@node Obsolete Functions ++@section Declaring Functions Obsolete ++ ++You can use @code{make-obsolete} to declare a function obsolete. This ++indicates that the function may be removed at some stage in the future. ++ ++@defun make-obsolete obsolete-name current-name &optional when ++This function makes the byte compiler warn that the function ++@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the ++warning message says to use @var{current-name} instead of ++@var{obsolete-name}. @var{current-name} does not need to be an alias for ++@var{obsolete-name}; it can be a different function with similar ++functionality. If @var{current-name} is a string, it is the warning ++message. ++ ++If provided, @var{when} should be a string indicating when the function ++was first made obsolete---for example, a date or a release number. ++@end defun ++ ++You can define a function as an alias and declare it obsolete at the ++same time using the macro @code{define-obsolete-function-alias}. ++ ++@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring ++This macro marks the function @var{obsolete-name} obsolete and also ++defines it as an alias for the function @var{current-name}. It is ++equivalent to the following: ++ ++@example ++(defalias @var{obsolete-name} @var{current-name} @var{docstring}) ++(make-obsolete @var{obsolete-name} @var{current-name} @var{when}) ++@end example ++@end defmac ++ ++@node Inline Functions ++@section Inline Functions ++@cindex inline functions ++ ++@findex defsubst ++You can define an @dfn{inline function} by using @code{defsubst} instead ++of @code{defun}. An inline function works just like an ordinary ++function except for one thing: when you compile a call to the function, ++the function's definition is open-coded into the caller. ++ ++Making a function inline makes explicit calls run faster. But it also ++has disadvantages. For one thing, it reduces flexibility; if you ++change the definition of the function, calls already inlined still use ++the old definition until you recompile them. ++ ++Another disadvantage is that making a large function inline can increase ++the size of compiled code both in files and in memory. Since the speed ++advantage of inline functions is greatest for small functions, you ++generally should not make large functions inline. ++ ++Also, inline functions do not behave well with respect to debugging, ++tracing, and advising (@pxref{Advising Functions}). Since ease of ++debugging and the flexibility of redefining functions are important ++features of Emacs, you should not make a function inline, even if it's ++small, unless its speed is really crucial, and you've timed the code ++to verify that using @code{defun} actually has performance problems. ++ ++It's possible to define a macro to expand into the same code that an ++inline function would execute. (@xref{Macros}.) But the macro would be ++limited to direct use in expressions---a macro cannot be called with ++@code{apply}, @code{mapcar} and so on. Also, it takes some work to ++convert an ordinary function into a macro. To convert it into an inline ++function is very easy; simply replace @code{defun} with @code{defsubst}. ++Since each argument of an inline function is evaluated exactly once, you ++needn't worry about how many times the body uses the arguments, as you ++do for macros. (@xref{Argument Evaluation}.) ++ ++Inline functions can be used and open-coded later on in the same file, ++following the definition, just like macros. ++ ++@node Declaring Functions ++@section Telling the Compiler that a Function is Defined ++@cindex function declaration ++@cindex declaring functions ++@findex declare-function ++ ++Byte-compiling a file often produces warnings about functions that the ++compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this ++indicates a real problem, but usually the functions in question are ++defined in other files which would be loaded if that code is run. For ++example, byte-compiling @file{fortran.el} used to warn: ++ ++@smallexample ++In end of data: ++fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known ++ to be defined. ++@end smallexample ++ ++In fact, @code{gud-find-c-expr} is only used in the function that ++Fortran mode uses for the local value of ++@code{gud-find-expr-function}, which is a callback from GUD; if it is ++called, the GUD functions will be loaded. When you know that such a ++warning does not indicate a real problem, it is good to suppress the ++warning. That makes new warnings which might mean real problems more ++visible. You do that with @code{declare-function}. ++ ++All you need to do is add a @code{declare-function} statement before the ++first use of the function in question: ++ ++@smallexample ++(declare-function gud-find-c-expr "gud.el" nil) ++@end smallexample ++ ++This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the ++@samp{.el} can be omitted). The compiler takes for granted that that file ++really defines the function, and does not check. ++ ++ The optional third argument specifies the argument list of ++@code{gud-find-c-expr}. In this case, it takes no arguments ++(@code{nil} is different from not specifying a value). In other ++cases, this might be something like @code{(file &optional overwrite)}. ++You don't have to specify the argument list, but if you do the ++byte compiler can check that the calls match the declaration. ++ ++@defmac declare-function function file &optional arglist fileonly ++Tell the byte compiler to assume that @var{function} is defined, with ++arguments @var{arglist}, and that the definition should come from the ++file @var{file}. @var{fileonly} non-@code{nil} means only check that ++@var{file} exists, not that it actually defines @var{function}. ++@end defmac ++ ++ To verify that these functions really are declared where ++@code{declare-function} says they are, use @code{check-declare-file} ++to check all @code{declare-function} calls in one source file, or use ++@code{check-declare-directory} check all the files in and under a ++certain directory. ++ ++ These commands find the file that ought to contain a function's ++definition using @code{locate-library}; if that finds no file, they ++expand the definition file name relative to the directory of the file ++that contains the @code{declare-function} call. ++ ++ You can also say that a function is defined by C code by specifying ++a file name ending in @samp{.c}. @code{check-declare-file} looks for ++these files in the C source code directory. This is useful only when ++you call a function that is defined only on certain systems. Most ++of the primitive functions of Emacs are always defined so they will ++never give you a warning. ++ ++ Sometimes a file will optionally use functions from an external package. ++If you prefix the filename in the @code{declare-function} statement with ++@samp{ext:}, then it will be checked if it is found, otherwise skipped ++without error. ++ ++ There are some function definitions that @samp{check-declare} does not ++understand (e.g. @code{defstruct} and some other macros). In such cases, ++you can pass a non-@code{nil} @var{fileonly} argument to ++@code{declare-function}, meaning to only check that the file exists, not ++that it actually defines the function. Note that to do this without ++having to specify an argument list, you should set the @var{arglist} ++argument to @code{t} (because @code{nil} means an empty argument list, as ++opposed to an unspecified one). ++ ++@node Function Safety ++@section Determining whether a Function is Safe to Call ++@cindex function safety ++@cindex safety of functions ++ ++Some major modes such as SES call functions that are stored in user ++files. (@inforef{Top, ,ses}, for more information on SES.) User ++files sometimes have poor pedigrees---you can get a spreadsheet from ++someone you've just met, or you can get one through email from someone ++you've never met. So it is risky to call a function whose source code ++is stored in a user file until you have determined that it is safe. ++ ++@defun unsafep form &optional unsafep-vars ++Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or ++returns a list that describes why it might be unsafe. The argument ++@var{unsafep-vars} is a list of symbols known to have temporary ++bindings at this point; it is mainly used for internal recursive ++calls. The current buffer is an implicit argument, which provides a ++list of buffer-local bindings. ++@end defun ++ ++Being quick and simple, @code{unsafep} does a very light analysis and ++rejects many Lisp expressions that are actually safe. There are no ++known cases where @code{unsafep} returns @code{nil} for an unsafe ++expression. However, a ``safe'' Lisp expression can return a string ++with a @code{display} property, containing an associated Lisp ++expression to be executed after the string is inserted into a buffer. ++This associated expression can be a virus. In order to be safe, you ++must delete properties from all strings calculated by user code before ++inserting them into buffers. ++ ++@ignore ++What is a safe Lisp expression? Basically, it's an expression that ++calls only built-in functions with no side effects (or only innocuous ++ones). Innocuous side effects include displaying messages and ++altering non-risky buffer-local variables (but not global variables). ++ ++@table @dfn ++@item Safe expression ++@itemize ++@item ++An atom or quoted thing. ++@item ++A call to a safe function (see below), if all its arguments are ++safe expressions. ++@item ++One of the special forms @code{and}, @code{catch}, @code{cond}, ++@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn}, ++@code{while}, and @code{unwind-protect}], if all its arguments are ++safe. ++@item ++A form that creates temporary bindings (@code{condition-case}, ++@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or ++@code{let*}), if all args are safe and the symbols to be bound are not ++explicitly risky (see @pxref{File Local Variables}). ++@item ++An assignment using @code{add-to-list}, @code{setq}, @code{push}, or ++@code{pop}, if all args are safe and the symbols to be assigned are ++not explicitly risky and they already have temporary or buffer-local ++bindings. ++@item ++One of [apply, mapc, mapcar, mapconcat] if the first argument is a ++safe explicit lambda and the other args are safe expressions. ++@end itemize ++ ++@item Safe function ++@itemize ++@item ++A lambda containing safe expressions. ++@item ++A symbol on the list @code{safe-functions}, so the user says it's safe. ++@item ++A symbol with a non-@code{nil} @code{side-effect-free} property. ++@item ++A symbol with a non-@code{nil} @code{safe-function} property. The ++value @code{t} indicates a function that is safe but has innocuous ++side effects. Other values will someday indicate functions with ++classes of side effects that are not always safe. ++@end itemize ++ ++The @code{side-effect-free} and @code{safe-function} properties are ++provided for built-in functions and for low-level functions and macros ++defined in @file{subr.el}. You can assign these properties for the ++functions you write. ++@end table ++@end ignore ++ ++@node Related Topics ++@section Other Topics Related to Functions ++ ++ Here is a table of several functions that do things related to ++function calling and function definitions. They are documented ++elsewhere, but we provide cross references here. ++ ++@table @code ++@item apply ++See @ref{Calling Functions}. ++ ++@item autoload ++See @ref{Autoload}. ++ ++@item call-interactively ++See @ref{Interactive Call}. ++ ++@item called-interactively-p ++See @ref{Distinguish Interactive}. ++ ++@item commandp ++See @ref{Interactive Call}. ++ ++@item documentation ++See @ref{Accessing Documentation}. ++ ++@item eval ++See @ref{Eval}. ++ ++@item funcall ++See @ref{Calling Functions}. ++ ++@item function ++See @ref{Anonymous Functions}. ++ ++@item ignore ++See @ref{Calling Functions}. ++ ++@item indirect-function ++See @ref{Function Indirection}. ++ ++@item interactive ++See @ref{Using Interactive}. ++ ++@item interactive-p ++See @ref{Distinguish Interactive}. ++ ++@item mapatoms ++See @ref{Creating Symbols}. ++ ++@item mapcar ++See @ref{Mapping Functions}. ++ ++@item map-char-table ++See @ref{Char-Tables}. ++ ++@item mapconcat ++See @ref{Mapping Functions}. ++ ++@item undefined ++See @ref{Functions for Key Lookup}. ++@end table ++ ++@ignore ++ arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2 ++@end ignore +diff --git a/doc/lispref/gpl.texi b/doc/lispref/gpl.texi +new file mode 100644 +index 0000000..163af46 +--- /dev/null ++++ b/doc/lispref/gpl.texi +@@ -0,0 +1,727 @@ ++@c -*-texinfo-*- ++@setfilename ../../info/gpl ++ ++@node GPL, Tips, GNU Free Documentation License, Top ++@comment node-name, next, previous, up ++@appendix GNU General Public License ++@c The GNU General Public License. ++@center Version 3, 29 June 2007 ++ ++@c This file is intended to be included within another document, ++@c hence no sectioning command or @node. ++ ++@display ++Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} ++ ++Everyone is permitted to copy and distribute verbatim copies of this ++license document, but changing it is not allowed. ++@end display ++ ++@heading Preamble ++ ++The GNU General Public License is a free, copyleft license for ++software and other kinds of works. ++ ++The licenses for most software and other practical works are designed ++to take away your freedom to share and change the works. By contrast, ++the GNU General Public License is intended to guarantee your freedom ++to share and change all versions of a program---to make sure it remains ++free software for all its users. We, the Free Software Foundation, ++use the GNU General Public License for most of our software; it ++applies also to any other work released this way by its authors. You ++can apply it to your programs, too. ++ ++When we speak of free software, we are referring to freedom, not ++price. Our General Public Licenses are designed to make sure that you ++have the freedom to distribute copies of free software (and charge for ++them 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. ++ ++To protect your rights, we need to prevent others from denying you ++these rights or asking you to surrender the rights. Therefore, you ++have certain responsibilities if you distribute copies of the ++software, or if you modify it: responsibilities to respect the freedom ++of others. ++ ++For example, if you distribute copies of such a program, whether ++gratis or for a fee, you must pass on to the recipients the same ++freedoms that you received. You must make sure that they, too, ++receive or can get the source code. And you must show them these ++terms so they know their rights. ++ ++Developers that use the GNU GPL protect your rights with two steps: ++(1) assert copyright on the software, and (2) offer you this License ++giving you legal permission to copy, distribute and/or modify it. ++ ++For the developers' and authors' protection, the GPL clearly explains ++that there is no warranty for this free software. For both users' and ++authors' sake, the GPL requires that modified versions be marked as ++changed, so that their problems will not be attributed erroneously to ++authors of previous versions. ++ ++Some devices are designed to deny users access to install or run ++modified versions of the software inside them, although the ++manufacturer can do so. This is fundamentally incompatible with the ++aim of protecting users' freedom to change the software. The ++systematic pattern of such abuse occurs in the area of products for ++individuals to use, which is precisely where it is most unacceptable. ++Therefore, we have designed this version of the GPL to prohibit the ++practice for those products. If such problems arise substantially in ++other domains, we stand ready to extend this provision to those ++domains in future versions of the GPL, as needed to protect the ++freedom of users. ++ ++Finally, every program is threatened constantly by software patents. ++States should not allow patents to restrict development and use of ++software on general-purpose computers, but in those that do, we wish ++to avoid the special danger that patents applied to a free program ++could make it effectively proprietary. To prevent this, the GPL ++assures that patents cannot be used to render the program non-free. ++ ++The precise terms and conditions for copying, distribution and ++modification follow. ++ ++@heading TERMS AND CONDITIONS ++ ++@enumerate 0 ++@item Definitions. ++ ++``This License'' refers to version 3 of the GNU General Public License. ++ ++``Copyright'' also means copyright-like laws that apply to other kinds ++of works, such as semiconductor masks. ++ ++``The Program'' refers to any copyrightable work licensed under this ++License. Each licensee is addressed as ``you''. ``Licensees'' and ++``recipients'' may be individuals or organizations. ++ ++To ``modify'' a work means to copy from or adapt all or part of the work ++in a fashion requiring copyright permission, other than the making of ++an exact copy. The resulting work is called a ``modified version'' of ++the earlier work or a work ``based on'' the earlier work. ++ ++A ``covered work'' means either the unmodified Program or a work based ++on the Program. ++ ++To ``propagate'' a work means to do anything with it that, without ++permission, would make you directly or secondarily liable for ++infringement under applicable copyright law, except executing it on a ++computer or modifying a private copy. Propagation includes copying, ++distribution (with or without modification), making available to the ++public, and in some countries other activities as well. ++ ++To ``convey'' a work means any kind of propagation that enables other ++parties to make or receive copies. Mere interaction with a user ++through a computer network, with no transfer of a copy, is not ++conveying. ++ ++An interactive user interface displays ``Appropriate Legal Notices'' to ++the extent that it includes a convenient and prominently visible ++feature that (1) displays an appropriate copyright notice, and (2) ++tells the user that there is no warranty for the work (except to the ++extent that warranties are provided), that licensees may convey the ++work under this License, and how to view a copy of this License. If ++the interface presents a list of user commands or options, such as a ++menu, a prominent item in the list meets this criterion. ++ ++@item Source Code. ++ ++The ``source code'' for a work means the preferred form of the work for ++making modifications to it. ``Object code'' means any non-source form ++of a work. ++ ++A ``Standard Interface'' means an interface that either is an official ++standard defined by a recognized standards body, or, in the case of ++interfaces specified for a particular programming language, one that ++is widely used among developers working in that language. ++ ++The ``System Libraries'' of an executable work include anything, other ++than the work as a whole, that (a) is included in the normal form of ++packaging a Major Component, but which is not part of that Major ++Component, and (b) serves only to enable use of the work with that ++Major Component, or to implement a Standard Interface for which an ++implementation is available to the public in source code form. A ++``Major Component'', in this context, means a major essential component ++(kernel, window system, and so on) of the specific operating system ++(if any) on which the executable work runs, or a compiler used to ++produce the work, or an object code interpreter used to run it. ++ ++The ``Corresponding Source'' for a work in object code form means all ++the source code needed to generate, install, and (for an executable ++work) run the object code and to modify the work, including scripts to ++control those activities. However, it does not include the work's ++System Libraries, or general-purpose tools or generally available free ++programs which are used unmodified in performing those activities but ++which are not part of the work. For example, Corresponding Source ++includes interface definition files associated with source files for ++the work, and the source code for shared libraries and dynamically ++linked subprograms that the work is specifically designed to require, ++such as by intimate data communication or control flow between those ++subprograms and other parts of the work. ++ ++The Corresponding Source need not include anything that users can ++regenerate automatically from other parts of the Corresponding Source. ++ ++The Corresponding Source for a work in source code form is that same ++work. ++ ++@item Basic Permissions. ++ ++All rights granted under this License are granted for the term of ++copyright on the Program, and are irrevocable provided the stated ++conditions are met. This License explicitly affirms your unlimited ++permission to run the unmodified Program. The output from running a ++covered work is covered by this License only if the output, given its ++content, constitutes a covered work. This License acknowledges your ++rights of fair use or other equivalent, as provided by copyright law. ++ ++You may make, run and propagate covered works that you do not convey, ++without conditions so long as your license otherwise remains in force. ++You may convey covered works to others for the sole purpose of having ++them make modifications exclusively for you, or provide you with ++facilities for running those works, provided that you comply with the ++terms of this License in conveying all material for which you do not ++control copyright. Those thus making or running the covered works for ++you must do so exclusively on your behalf, under your direction and ++control, on terms that prohibit them from making any copies of your ++copyrighted material outside their relationship with you. ++ ++Conveying under any other circumstances is permitted solely under the ++conditions stated below. Sublicensing is not allowed; section 10 ++makes it unnecessary. ++ ++@item Protecting Users' Legal Rights From Anti-Circumvention Law. ++ ++No covered work shall be deemed part of an effective technological ++measure under any applicable law fulfilling obligations under article ++11 of the WIPO copyright treaty adopted on 20 December 1996, or ++similar laws prohibiting or restricting circumvention of such ++measures. ++ ++When you convey a covered work, you waive any legal power to forbid ++circumvention of technological measures to the extent such ++circumvention is effected by exercising rights under this License with ++respect to the covered work, and you disclaim any intention to limit ++operation or modification of the work as a means of enforcing, against ++the work's users, your or third parties' legal rights to forbid ++circumvention of technological measures. ++ ++@item Conveying Verbatim Copies. ++ ++You may convey verbatim copies of the Program's source code as you ++receive it, in any medium, provided that you conspicuously and ++appropriately publish on each copy an appropriate copyright notice; ++keep intact all notices stating that this License and any ++non-permissive terms added in accord with section 7 apply to the code; ++keep intact all notices of the absence of any warranty; and give all ++recipients a copy of this License along with the Program. ++ ++You may charge any price or no price for each copy that you convey, ++and you may offer support or warranty protection for a fee. ++ ++@item Conveying Modified Source Versions. ++ ++You may convey a work based on the Program, or the modifications to ++produce it from the Program, in the form of source code under the ++terms of section 4, provided that you also meet all of these ++conditions: ++ ++@enumerate a ++@item ++The work must carry prominent notices stating that you modified it, ++and giving a relevant date. ++ ++@item ++The work must carry prominent notices stating that it is released ++under this License and any conditions added under section 7. This ++requirement modifies the requirement in section 4 to ``keep intact all ++notices''. ++ ++@item ++You must license the entire work, as a whole, under this License to ++anyone who comes into possession of a copy. This License will ++therefore apply, along with any applicable section 7 additional terms, ++to the whole of the work, and all its parts, regardless of how they ++are packaged. This License gives no permission to license the work in ++any other way, but it does not invalidate such permission if you have ++separately received it. ++ ++@item ++If the work has interactive user interfaces, each must display ++Appropriate Legal Notices; however, if the Program has interactive ++interfaces that do not display Appropriate Legal Notices, your work ++need not make them do so. ++@end enumerate ++ ++A compilation of a covered work with other separate and independent ++works, which are not by their nature extensions of the covered work, ++and which are not combined with it such as to form a larger program, ++in or on a volume of a storage or distribution medium, is called an ++``aggregate'' if the compilation and its resulting copyright are not ++used to limit the access or legal rights of the compilation's users ++beyond what the individual works permit. Inclusion of a covered work ++in an aggregate does not cause this License to apply to the other ++parts of the aggregate. ++ ++@item Conveying Non-Source Forms. ++ ++You may convey a covered work in object code form under the terms of ++sections 4 and 5, provided that you also convey the machine-readable ++Corresponding Source under the terms of this License, in one of these ++ways: ++ ++@enumerate a ++@item ++Convey the object code in, or embodied in, a physical product ++(including a physical distribution medium), accompanied by the ++Corresponding Source fixed on a durable physical medium customarily ++used for software interchange. ++ ++@item ++Convey the object code in, or embodied in, a physical product ++(including a physical distribution medium), accompanied by a written ++offer, valid for at least three years and valid for as long as you ++offer spare parts or customer support for that product model, to give ++anyone who possesses the object code either (1) a copy of the ++Corresponding Source for all the software in the product that is ++covered by this License, on a durable physical medium customarily used ++for software interchange, for a price no more than your reasonable ++cost of physically performing this conveying of source, or (2) access ++to copy the Corresponding Source from a network server at no charge. ++ ++@item ++Convey individual copies of the object code with a copy of the written ++offer to provide the Corresponding Source. This alternative is ++allowed only occasionally and noncommercially, and only if you ++received the object code with such an offer, in accord with subsection ++6b. ++ ++@item ++Convey the object code by offering access from a designated place ++(gratis or for a charge), and offer equivalent access to the ++Corresponding Source in the same way through the same place at no ++further charge. You need not require recipients to copy the ++Corresponding Source along with the object code. If the place to copy ++the object code is a network server, the Corresponding Source may be ++on a different server (operated by you or a third party) that supports ++equivalent copying facilities, provided you maintain clear directions ++next to the object code saying where to find the Corresponding Source. ++Regardless of what server hosts the Corresponding Source, you remain ++obligated to ensure that it is available for as long as needed to ++satisfy these requirements. ++ ++@item ++Convey the object code using peer-to-peer transmission, provided you ++inform other peers where the object code and Corresponding Source of ++the work are being offered to the general public at no charge under ++subsection 6d. ++ ++@end enumerate ++ ++A separable portion of the object code, whose source code is excluded ++from the Corresponding Source as a System Library, need not be ++included in conveying the object code work. ++ ++A ``User Product'' is either (1) a ``consumer product'', which means any ++tangible personal property which is normally used for personal, ++family, or household purposes, or (2) anything designed or sold for ++incorporation into a dwelling. In determining whether a product is a ++consumer product, doubtful cases shall be resolved in favor of ++coverage. For a particular product received by a particular user, ++``normally used'' refers to a typical or common use of that class of ++product, regardless of the status of the particular user or of the way ++in which the particular user actually uses, or expects or is expected ++to use, the product. A product is a consumer product regardless of ++whether the product has substantial commercial, industrial or ++non-consumer uses, unless such uses represent the only significant ++mode of use of the product. ++ ++``Installation Information'' for a User Product means any methods, ++procedures, authorization keys, or other information required to ++install and execute modified versions of a covered work in that User ++Product from a modified version of its Corresponding Source. The ++information must suffice to ensure that the continued functioning of ++the modified object code is in no case prevented or interfered with ++solely because modification has been made. ++ ++If you convey an object code work under this section in, or with, or ++specifically for use in, a User Product, and the conveying occurs as ++part of a transaction in which the right of possession and use of the ++User Product is transferred to the recipient in perpetuity or for a ++fixed term (regardless of how the transaction is characterized), the ++Corresponding Source conveyed under this section must be accompanied ++by the Installation Information. But this requirement does not apply ++if neither you nor any third party retains the ability to install ++modified object code on the User Product (for example, the work has ++been installed in ROM). ++ ++The requirement to provide Installation Information does not include a ++requirement to continue to provide support service, warranty, or ++updates for a work that has been modified or installed by the ++recipient, or for the User Product in which it has been modified or ++installed. Access to a network may be denied when the modification ++itself materially and adversely affects the operation of the network ++or violates the rules and protocols for communication across the ++network. ++ ++Corresponding Source conveyed, and Installation Information provided, ++in accord with this section must be in a format that is publicly ++documented (and with an implementation available to the public in ++source code form), and must require no special password or key for ++unpacking, reading or copying. ++ ++@item Additional Terms. ++ ++``Additional permissions'' are terms that supplement the terms of this ++License by making exceptions from one or more of its conditions. ++Additional permissions that are applicable to the entire Program shall ++be treated as though they were included in this License, to the extent ++that they are valid under applicable law. If additional permissions ++apply only to part of the Program, that part may be used separately ++under those permissions, but the entire Program remains governed by ++this License without regard to the additional permissions. ++ ++When you convey a copy of a covered work, you may at your option ++remove any additional permissions from that copy, or from any part of ++it. (Additional permissions may be written to require their own ++removal in certain cases when you modify the work.) You may place ++additional permissions on material, added by you to a covered work, ++for which you have or can give appropriate copyright permission. ++ ++Notwithstanding any other provision of this License, for material you ++add to a covered work, you may (if authorized by the copyright holders ++of that material) supplement the terms of this License with terms: ++ ++@enumerate a ++@item ++Disclaiming warranty or limiting liability differently from the terms ++of sections 15 and 16 of this License; or ++ ++@item ++Requiring preservation of specified reasonable legal notices or author ++attributions in that material or in the Appropriate Legal Notices ++displayed by works containing it; or ++ ++@item ++Prohibiting misrepresentation of the origin of that material, or ++requiring that modified versions of such material be marked in ++reasonable ways as different from the original version; or ++ ++@item ++Limiting the use for publicity purposes of names of licensors or ++authors of the material; or ++ ++@item ++Declining to grant rights under trademark law for use of some trade ++names, trademarks, or service marks; or ++ ++@item ++Requiring indemnification of licensors and authors of that material by ++anyone who conveys the material (or modified versions of it) with ++contractual assumptions of liability to the recipient, for any ++liability that these contractual assumptions directly impose on those ++licensors and authors. ++@end enumerate ++ ++All other non-permissive additional terms are considered ``further ++restrictions'' within the meaning of section 10. If the Program as you ++received it, or any part of it, contains a notice stating that it is ++governed by this License along with a term that is a further ++restriction, you may remove that term. If a license document contains ++a further restriction but permits relicensing or conveying under this ++License, you may add to a covered work material governed by the terms ++of that license document, provided that the further restriction does ++not survive such relicensing or conveying. ++ ++If you add terms to a covered work in accord with this section, you ++must place, in the relevant source files, a statement of the ++additional terms that apply to those files, or a notice indicating ++where to find the applicable terms. ++ ++Additional terms, permissive or non-permissive, may be stated in the ++form of a separately written license, or stated as exceptions; the ++above requirements apply either way. ++ ++@item Termination. ++ ++You may not propagate or modify a covered work except as expressly ++provided under this License. Any attempt otherwise to propagate or ++modify it is void, and will automatically terminate your rights under ++this License (including any patent licenses granted under the third ++paragraph of section 11). ++ ++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, you do not qualify to receive new licenses for the same ++material under section 10. ++ ++@item Acceptance Not Required for Having Copies. ++ ++You are not required to accept this License in order to receive or run ++a copy of the Program. Ancillary propagation of a covered work ++occurring solely as a consequence of using peer-to-peer transmission ++to receive a copy likewise does not require acceptance. However, ++nothing other than this License grants you permission to propagate or ++modify any covered work. These actions infringe copyright if you do ++not accept this License. Therefore, by modifying or propagating a ++covered work, you indicate your acceptance of this License to do so. ++ ++@item Automatic Licensing of Downstream Recipients. ++ ++Each time you convey a covered work, the recipient automatically ++receives a license from the original licensors, to run, modify and ++propagate that work, subject to this License. You are not responsible ++for enforcing compliance by third parties with this License. ++ ++An ``entity transaction'' is a transaction transferring control of an ++organization, or substantially all assets of one, or subdividing an ++organization, or merging organizations. If propagation of a covered ++work results from an entity transaction, each party to that ++transaction who receives a copy of the work also receives whatever ++licenses to the work the party's predecessor in interest had or could ++give under the previous paragraph, plus a right to possession of the ++Corresponding Source of the work from the predecessor in interest, if ++the predecessor has it or can get it with reasonable efforts. ++ ++You may not impose any further restrictions on the exercise of the ++rights granted or affirmed under this License. For example, you may ++not impose a license fee, royalty, or other charge for exercise of ++rights granted under this License, and you may not initiate litigation ++(including a cross-claim or counterclaim in a lawsuit) alleging that ++any patent claim is infringed by making, using, selling, offering for ++sale, or importing the Program or any portion of it. ++ ++@item Patents. ++ ++A ``contributor'' is a copyright holder who authorizes use under this ++License of the Program or a work on which the Program is based. The ++work thus licensed is called the contributor's ``contributor version''. ++ ++A contributor's ``essential patent claims'' are all patent claims owned ++or controlled by the contributor, whether already acquired or ++hereafter acquired, that would be infringed by some manner, permitted ++by this License, of making, using, or selling its contributor version, ++but do not include claims that would be infringed only as a ++consequence of further modification of the contributor version. For ++purposes of this definition, ``control'' includes the right to grant ++patent sublicenses in a manner consistent with the requirements of ++this License. ++ ++Each contributor grants you a non-exclusive, worldwide, royalty-free ++patent license under the contributor's essential patent claims, to ++make, use, sell, offer for sale, import and otherwise run, modify and ++propagate the contents of its contributor version. ++ ++In the following three paragraphs, a ``patent license'' is any express ++agreement or commitment, however denominated, not to enforce a patent ++(such as an express permission to practice a patent or covenant not to ++sue for patent infringement). To ``grant'' such a patent license to a ++party means to make such an agreement or commitment not to enforce a ++patent against the party. ++ ++If you convey a covered work, knowingly relying on a patent license, ++and the Corresponding Source of the work is not available for anyone ++to copy, free of charge and under the terms of this License, through a ++publicly available network server or other readily accessible means, ++then you must either (1) cause the Corresponding Source to be so ++available, or (2) arrange to deprive yourself of the benefit of the ++patent license for this particular work, or (3) arrange, in a manner ++consistent with the requirements of this License, to extend the patent ++license to downstream recipients. ``Knowingly relying'' means you have ++actual knowledge that, but for the patent license, your conveying the ++covered work in a country, or your recipient's use of the covered work ++in a country, would infringe one or more identifiable patents in that ++country that you have reason to believe are valid. ++ ++If, pursuant to or in connection with a single transaction or ++arrangement, you convey, or propagate by procuring conveyance of, a ++covered work, and grant a patent license to some of the parties ++receiving the covered work authorizing them to use, propagate, modify ++or convey a specific copy of the covered work, then the patent license ++you grant is automatically extended to all recipients of the covered ++work and works based on it. ++ ++A patent license is ``discriminatory'' if it does not include within the ++scope of its coverage, prohibits the exercise of, or is conditioned on ++the non-exercise of one or more of the rights that are specifically ++granted under this License. You may not convey a covered work if you ++are a party to an arrangement with a third party that is in the ++business of distributing software, under which you make payment to the ++third party based on the extent of your activity of conveying the ++work, and under which the third party grants, to any of the parties ++who would receive the covered work from you, a discriminatory patent ++license (a) in connection with copies of the covered work conveyed by ++you (or copies made from those copies), or (b) primarily for and in ++connection with specific products or compilations that contain the ++covered work, unless you entered into that arrangement, or that patent ++license was granted, prior to 28 March 2007. ++ ++Nothing in this License shall be construed as excluding or limiting ++any implied license or other defenses to infringement that may ++otherwise be available to you under applicable patent law. ++ ++@item No Surrender of Others' Freedom. ++ ++If conditions are imposed on you (whether by court order, agreement or ++otherwise) that contradict the conditions of this License, they do not ++excuse you from the conditions of this License. If you cannot convey ++a covered work so as to satisfy simultaneously your obligations under ++this License and any other pertinent obligations, then as a ++consequence you may not convey it at all. For example, if you agree ++to terms that obligate you to collect a royalty for further conveying ++from those to whom you convey the Program, the only way you could ++satisfy both those terms and this License would be to refrain entirely ++from conveying the Program. ++ ++@item Use with the GNU Affero General Public License. ++ ++Notwithstanding any other provision of this License, you have ++permission to link or combine any covered work with a work licensed ++under version 3 of the GNU Affero General Public License into a single ++combined work, and to convey the resulting work. The terms of this ++License will continue to apply to the part which is the covered work, ++but the special requirements of the GNU Affero General Public License, ++section 13, concerning interaction through a network will apply to the ++combination as such. ++ ++@item Revised Versions of this License. ++ ++The Free Software Foundation may publish revised and/or new versions ++of the GNU General Public 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. ++ ++Each version is given a distinguishing version number. If the Program ++specifies that a certain numbered version of the GNU General Public ++License ``or any later version'' applies to it, you have the option of ++following the terms and conditions either of that numbered version or ++of any later version published by the Free Software Foundation. If ++the Program does not specify a version number of the GNU General ++Public License, you may choose any version ever published by the Free ++Software Foundation. ++ ++If the Program specifies that a proxy can decide which future versions ++of the GNU General Public License can be used, that proxy's public ++statement of acceptance of a version permanently authorizes you to ++choose that version for the Program. ++ ++Later license versions may give you additional or different ++permissions. However, no additional obligations are imposed on any ++author or copyright holder as a result of your choosing to follow a ++later version. ++ ++@item Disclaimer of Warranty. ++ ++THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY ++APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT ++HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT ++WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT ++LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ++A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND ++PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE ++DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR ++CORRECTION. ++ ++@item Limitation of Liability. ++ ++IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING ++WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR ++CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, ++INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ++ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT ++NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR ++LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM ++TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER ++PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. ++ ++@item Interpretation of Sections 15 and 16. ++ ++If the disclaimer of warranty and limitation of liability provided ++above cannot be given local legal effect according to their terms, ++reviewing courts shall apply local law that most closely approximates ++an absolute waiver of all civil liability in connection with the ++Program, unless a warranty or assumption of liability accompanies a ++copy of the Program in return for a fee. ++ ++@end enumerate ++ ++@heading END OF TERMS AND CONDITIONS ++ ++@heading How to Apply These Terms to Your New Programs ++ ++If you develop a new program, and you want it to be of the greatest ++possible use to the public, the best way to achieve this is to make it ++free software which everyone can redistribute and change under these ++terms. ++ ++To do so, attach the following notices to the program. It is safest ++to attach them to the start of each source file to most effectively ++state the exclusion of warranty; and each file should have at least ++the ``copyright'' line and a pointer to where the full notice is found. ++ ++@smallexample ++@var{one line to give the program's name and a brief idea of what it does.} ++Copyright (C) @var{year} @var{name of author} ++ ++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 @url{http://www.gnu.org/licenses/}. ++@end smallexample ++ ++Also add information on how to contact you by electronic and paper mail. ++ ++If the program does terminal interaction, make it output a short ++notice like this when it starts in an interactive mode: ++ ++@smallexample ++@var{program} Copyright (C) @var{year} @var{name of author} ++This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. ++This is free software, and you are welcome to redistribute it ++under certain conditions; type @samp{show c} for details. ++@end smallexample ++ ++The hypothetical commands @samp{show w} and @samp{show c} should show ++the appropriate parts of the General Public License. Of course, your ++program's commands might be different; for a GUI interface, you would ++use an ``about box''. ++ ++You should also get your employer (if you work as a programmer) or school, ++if any, to sign a ``copyright disclaimer'' for the program, if necessary. ++For more information on this, and how to apply and follow the GNU GPL, see ++@url{http://www.gnu.org/licenses/}. ++ ++The GNU General Public License does not permit incorporating your ++program into proprietary programs. If your program is a subroutine ++library, you may consider it more useful to permit linking proprietary ++applications with the library. If this is what you want to do, use ++the GNU Lesser General Public License instead of this License. But ++first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. ++ ++@ignore ++ arch-tag: d00ac830-e120-41fb-bbc5-7ca3eeaa227f ++@end ignore +diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi +new file mode 100644 +index 0000000..dd785f8 +--- /dev/null ++++ b/doc/lispref/hash.texi +@@ -0,0 +1,337 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1999, 2001, 2002, 2003, 2004, 2005, ++@c 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/hash ++@node Hash Tables, Symbols, Sequences Arrays Vectors, Top ++@chapter Hash Tables ++@cindex hash tables ++@cindex lookup tables ++ ++ A hash table is a very fast kind of lookup table, somewhat like an ++alist (@pxref{Association Lists}) in that it maps keys to ++corresponding values. It differs from an alist in these ways: ++ ++@itemize @bullet ++@item ++Lookup in a hash table is extremely fast for large tables---in fact, the ++time required is essentially @emph{independent} of how many elements are ++stored in the table. For smaller tables (a few tens of elements) ++alists may still be faster because hash tables have a more-or-less ++constant overhead. ++ ++@item ++The correspondences in a hash table are in no particular order. ++ ++@item ++There is no way to share structure between two hash tables, ++the way two alists can share a common tail. ++@end itemize ++ ++ Emacs Lisp provides a general-purpose hash table data type, along ++with a series of functions for operating on them. Hash tables have no ++read syntax, and print in hash notation, like this: ++ ++@example ++(make-hash-table) ++ @result{} # ++@end example ++ ++@noindent ++(The term ``hash notation'' refers to the initial @samp{#} ++character---@pxref{Printed Representation}---and has nothing to do with ++the term ``hash table.'') ++ ++ Obarrays are also a kind of hash table, but they are a different type ++of object and are used only for recording interned symbols ++(@pxref{Creating Symbols}). ++ ++@menu ++* Creating Hash:: Functions to create hash tables. ++* Hash Access:: Reading and writing the hash table contents. ++* Defining Hash:: Defining new comparison methods. ++* Other Hash:: Miscellaneous. ++@end menu ++ ++@node Creating Hash ++@section Creating Hash Tables ++@cindex creating hash tables ++ ++ The principal function for creating a hash table is ++@code{make-hash-table}. ++ ++@defun make-hash-table &rest keyword-args ++This function creates a new hash table according to the specified ++arguments. The arguments should consist of alternating keywords ++(particular symbols recognized specially) and values corresponding to ++them. ++ ++Several keywords make sense in @code{make-hash-table}, but the only two ++that you really need to know about are @code{:test} and @code{:weakness}. ++ ++@table @code ++@item :test @var{test} ++This specifies the method of key lookup for this hash table. The ++default is @code{eql}; @code{eq} and @code{equal} are other ++alternatives: ++ ++@table @code ++@item eql ++Keys which are numbers are ``the same'' if they are @code{equal}, that ++is, if they are equal in value and either both are integers or both ++are floating point numbers; otherwise, two distinct objects are never ++``the same.'' ++ ++@item eq ++Any two distinct Lisp objects are ``different'' as keys. ++ ++@item equal ++Two Lisp objects are ``the same,'' as keys, if they are equal ++according to @code{equal}. ++@end table ++ ++You can use @code{define-hash-table-test} (@pxref{Defining Hash}) to ++define additional possibilities for @var{test}. ++ ++@item :weakness @var{weak} ++The weakness of a hash table specifies whether the presence of a key or ++value in the hash table preserves it from garbage collection. ++ ++The value, @var{weak}, must be one of @code{nil}, @code{key}, ++@code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t} ++which is an alias for @code{key-and-value}. If @var{weak} is @code{key} ++then the hash table does not prevent its keys from being collected as ++garbage (if they are not referenced anywhere else); if a particular key ++does get collected, the corresponding association is removed from the ++hash table. ++ ++If @var{weak} is @code{value}, then the hash table does not prevent ++values from being collected as garbage (if they are not referenced ++anywhere else); if a particular value does get collected, the ++corresponding association is removed from the hash table. ++ ++If @var{weak} is @code{key-and-value} or @code{t}, both the key and ++the value must be live in order to preserve the association. Thus, ++the hash table does not protect either keys or values from garbage ++collection; if either one is collected as garbage, that removes the ++association. ++ ++If @var{weak} is @code{key-or-value}, either the key or ++the value can preserve the association. Thus, associations are ++removed from the hash table when both their key and value would be ++collected as garbage (if not for references from weak hash tables). ++ ++The default for @var{weak} is @code{nil}, so that all keys and values ++referenced in the hash table are preserved from garbage collection. ++ ++@item :size @var{size} ++This specifies a hint for how many associations you plan to store in the ++hash table. If you know the approximate number, you can make things a ++little more efficient by specifying it this way. If you specify too ++small a size, the hash table will grow automatically when necessary, but ++doing that takes some extra time. ++ ++The default size is 65. ++ ++@item :rehash-size @var{rehash-size} ++When you add an association to a hash table and the table is ``full,'' ++it grows automatically. This value specifies how to make the hash table ++larger, at that time. ++ ++If @var{rehash-size} is an integer, it should be positive, and the hash ++table grows by adding that much to the nominal size. If ++@var{rehash-size} is a floating point number, it had better be greater ++than 1, and the hash table grows by multiplying the old size by that ++number. ++ ++The default value is 1.5. ++ ++@item :rehash-threshold @var{threshold} ++This specifies the criterion for when the hash table is ``full'' (so ++it should be made larger). The value, @var{threshold}, should be a ++positive floating point number, no greater than 1. The hash table is ++``full'' whenever the actual number of entries exceeds this fraction ++of the nominal size. The default for @var{threshold} is 0.8. ++@end table ++@end defun ++ ++@defun makehash &optional test ++This is equivalent to @code{make-hash-table}, but with a different style ++argument list. The argument @var{test} specifies the method ++of key lookup. ++ ++This function is obsolete. Use @code{make-hash-table} instead. ++@end defun ++ ++@node Hash Access ++@section Hash Table Access ++ ++ This section describes the functions for accessing and storing ++associations in a hash table. In general, any Lisp object can be used ++as a hash key, unless the comparison method imposes limits. Any Lisp ++object can also be used as the value. ++ ++@defun gethash key table &optional default ++This function looks up @var{key} in @var{table}, and returns its ++associated @var{value}---or @var{default}, if @var{key} has no ++association in @var{table}. ++@end defun ++ ++@defun puthash key value table ++This function enters an association for @var{key} in @var{table}, with ++value @var{value}. If @var{key} already has an association in ++@var{table}, @var{value} replaces the old associated value. ++@end defun ++ ++@defun remhash key table ++This function removes the association for @var{key} from @var{table}, if ++there is one. If @var{key} has no association, @code{remhash} does ++nothing. ++ ++@b{Common Lisp note:} In Common Lisp, @code{remhash} returns ++non-@code{nil} if it actually removed an association and @code{nil} ++otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}. ++@end defun ++ ++@defun clrhash table ++This function removes all the associations from hash table @var{table}, ++so that it becomes empty. This is also called @dfn{clearing} the hash ++table. ++ ++@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty ++@var{table}. In Emacs Lisp, it returns @code{nil}. ++@end defun ++ ++@defun maphash function table ++@anchor{Definition of maphash} ++This function calls @var{function} once for each of the associations in ++@var{table}. The function @var{function} should accept two ++arguments---a @var{key} listed in @var{table}, and its associated ++@var{value}. @code{maphash} returns @code{nil}. ++@end defun ++ ++@node Defining Hash ++@section Defining Hash Comparisons ++@cindex hash code ++@cindex define hash comparisons ++ ++ You can define new methods of key lookup by means of ++@code{define-hash-table-test}. In order to use this feature, you need ++to understand how hash tables work, and what a @dfn{hash code} means. ++ ++ You can think of a hash table conceptually as a large array of many ++slots, each capable of holding one association. To look up a key, ++@code{gethash} first computes an integer, the hash code, from the key. ++It reduces this integer modulo the length of the array, to produce an ++index in the array. Then it looks in that slot, and if necessary in ++other nearby slots, to see if it has found the key being sought. ++ ++ Thus, to define a new method of key lookup, you need to specify both a ++function to compute the hash code from a key, and a function to compare ++two keys directly. ++ ++@defun define-hash-table-test name test-fn hash-fn ++This function defines a new hash table test, named @var{name}. ++ ++After defining @var{name} in this way, you can use it as the @var{test} ++argument in @code{make-hash-table}. When you do that, the hash table ++will use @var{test-fn} to compare key values, and @var{hash-fn} to compute ++a ``hash code'' from a key value. ++ ++The function @var{test-fn} should accept two arguments, two keys, and ++return non-@code{nil} if they are considered ``the same.'' ++ ++The function @var{hash-fn} should accept one argument, a key, and return ++an integer that is the ``hash code'' of that key. For good results, the ++function should use the whole range of integer values for hash codes, ++including negative integers. ++ ++The specified functions are stored in the property list of @var{name} ++under the property @code{hash-table-test}; the property value's form is ++@code{(@var{test-fn} @var{hash-fn})}. ++@end defun ++ ++@defun sxhash obj ++This function returns a hash code for Lisp object @var{obj}. ++This is an integer which reflects the contents of @var{obj} ++and the other Lisp objects it points to. ++ ++If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash ++@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer. ++ ++If the two objects are not equal, the values returned by @code{sxhash} ++are usually different, but not always; once in a rare while, by luck, ++you will encounter two distinct-looking objects that give the same ++result from @code{sxhash}. ++@end defun ++ ++ This example creates a hash table whose keys are strings that are ++compared case-insensitively. ++ ++@example ++(defun case-fold-string= (a b) ++ (compare-strings a nil nil b nil nil t)) ++(defun case-fold-string-hash (a) ++ (sxhash (upcase a))) ++ ++(define-hash-table-test 'case-fold ++ 'case-fold-string= 'case-fold-string-hash) ++ ++(make-hash-table :test 'case-fold) ++@end example ++ ++ Here is how you could define a hash table test equivalent to the ++predefined test value @code{equal}. The keys can be any Lisp object, ++and equal-looking objects are considered the same key. ++ ++@example ++(define-hash-table-test 'contents-hash 'equal 'sxhash) ++ ++(make-hash-table :test 'contents-hash) ++@end example ++ ++@node Other Hash ++@section Other Hash Table Functions ++ ++ Here are some other functions for working with hash tables. ++ ++@defun hash-table-p table ++This returns non-@code{nil} if @var{table} is a hash table object. ++@end defun ++ ++@defun copy-hash-table table ++This function creates and returns a copy of @var{table}. Only the table ++itself is copied---the keys and values are shared. ++@end defun ++ ++@defun hash-table-count table ++This function returns the actual number of entries in @var{table}. ++@end defun ++ ++@defun hash-table-test table ++This returns the @var{test} value that was given when @var{table} was ++created, to specify how to hash and compare keys. See ++@code{make-hash-table} (@pxref{Creating Hash}). ++@end defun ++ ++@defun hash-table-weakness table ++This function returns the @var{weak} value that was specified for hash ++table @var{table}. ++@end defun ++ ++@defun hash-table-rehash-size table ++This returns the rehash size of @var{table}. ++@end defun ++ ++@defun hash-table-rehash-threshold table ++This returns the rehash threshold of @var{table}. ++@end defun ++ ++@defun hash-table-size table ++This returns the current nominal size of @var{table}. ++@end defun ++ ++@ignore ++ arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e ++@end ignore +diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi +new file mode 100644 +index 0000000..bb38aab +--- /dev/null ++++ b/doc/lispref/help.texi +@@ -0,0 +1,706 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/help ++@node Documentation, Files, Modes, Top ++@chapter Documentation ++@cindex documentation strings ++ ++ GNU Emacs Lisp has convenient on-line help facilities, most of which ++derive their information from the documentation strings associated with ++functions and variables. This chapter describes how to write good ++documentation strings for your Lisp programs, as well as how to write ++programs to access documentation. ++ ++ Note that the documentation strings for Emacs are not the same thing ++as the Emacs manual. Manuals have their own source files, written in ++the Texinfo language; documentation strings are specified in the ++definitions of the functions and variables they apply to. A collection ++of documentation strings is not sufficient as a manual because a good ++manual is not organized in that fashion; it is organized in terms of ++topics of discussion. ++ ++ For commands to display documentation strings, see @ref{Help, , ++Help, emacs, The GNU Emacs Manual}. For the conventions for writing ++documentation strings, see @ref{Documentation Tips}. ++ ++@menu ++* Documentation Basics:: Good style for doc strings. ++ Where to put them. How Emacs stores them. ++* Accessing Documentation:: How Lisp programs can access doc strings. ++* Keys in Documentation:: Substituting current key bindings. ++* Describing Characters:: Making printable descriptions of ++ non-printing characters and key sequences. ++* Help Functions:: Subroutines used by Emacs help facilities. ++@end menu ++ ++@node Documentation Basics ++@comment node-name, next, previous, up ++@section Documentation Basics ++@cindex documentation conventions ++@cindex writing a documentation string ++@cindex string, writing a doc string ++ ++ A documentation string is written using the Lisp syntax for strings, ++with double-quote characters surrounding the text of the string. This ++is because it really is a Lisp string object. The string serves as ++documentation when it is written in the proper place in the definition ++of a function or variable. In a function definition, the documentation ++string follows the argument list. In a variable definition, the ++documentation string follows the initial value of the variable. ++ ++ When you write a documentation string, make the first line a ++complete sentence (or two complete sentences) since some commands, ++such as @code{apropos}, show only the first line of a multi-line ++documentation string. Also, you should not indent the second line of ++a documentation string, if it has one, because that looks odd when you ++use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v} ++(@code{describe-variable}) to view the documentation string. There ++are many other conventions for doc strings; see @ref{Documentation ++Tips}. ++ ++ Documentation strings can contain several special substrings, which ++stand for key bindings to be looked up in the current keymaps when the ++documentation is displayed. This allows documentation strings to refer ++to the keys for related commands and be accurate even when a user ++rearranges the key bindings. (@xref{Keys in Documentation}.) ++ ++@vindex emacs-lisp-docstring-fill-column ++ Emacs Lisp mode fills documentation strings to the width ++specified by @code{emacs-lisp-docstring-fill-column}. ++ ++ In Emacs Lisp, a documentation string is accessible through the ++function or variable that it describes: ++ ++@itemize @bullet ++@item ++@kindex function-documentation ++The documentation for a function is usually stored in the function ++definition itself (@pxref{Lambda Expressions}). The function ++@code{documentation} knows how to extract it. You can also put ++function documentation in the @code{function-documentation} property ++of the function name. That is useful with definitions such as ++keyboard macros that can't hold a documentation string. ++ ++@item ++@kindex variable-documentation ++The documentation for a variable is stored in the variable's property ++list under the property name @code{variable-documentation}. The ++function @code{documentation-property} knows how to retrieve it. ++@end itemize ++ ++@cindex @file{DOC-@var{version}} (documentation) file ++To save space, the documentation for preloaded functions and variables ++(including primitive functions and autoloaded functions) is stored in ++the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The ++documentation strings for functions and variables loaded during the ++Emacs session from byte-compiled files are stored in those files ++(@pxref{Docs and Compilation}). ++ ++The data structure inside Emacs has an integer offset into the file, or ++a list containing a file name and an integer, in place of the ++documentation string. The functions @code{documentation} and ++@code{documentation-property} use that information to fetch the ++documentation string from the appropriate file; this is transparent to ++the user. ++ ++@c Wordy to prevent overfull hbox. --rjc 15mar92 ++ The @file{emacs/lib-src} directory contains two utilities that you can ++use to print nice-looking hardcopy for the file ++@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and ++@file{digest-doc}. ++ ++@node Accessing Documentation ++@section Access to Documentation Strings ++ ++@defun documentation-property symbol property &optional verbatim ++This function returns the documentation string that is recorded in ++@var{symbol}'s property list under property @var{property}. It ++retrieves the text from a file if the value calls for that. If the ++property value isn't @code{nil}, isn't a string, and doesn't refer to ++text in a file, then it is evaluated to obtain a string. ++ ++The last thing this function does is pass the string through ++@code{substitute-command-keys} to substitute actual key bindings, ++unless @var{verbatim} is non-@code{nil}. ++ ++@smallexample ++@group ++(documentation-property 'command-line-processed ++ 'variable-documentation) ++ @result{} "Non-nil once command line has been processed" ++@end group ++@group ++(symbol-plist 'command-line-processed) ++ @result{} (variable-documentation 188902) ++@end group ++@group ++(documentation-property 'emacs 'group-documentation) ++ @result{} "Customization of the One True Editor." ++@end group ++@end smallexample ++@end defun ++ ++@defun documentation function &optional verbatim ++This function returns the documentation string of @var{function}. ++@code{documentation} handles macros, named keyboard macros, and ++special forms, as well as ordinary functions. ++ ++If @var{function} is a symbol, this function first looks for the ++@code{function-documentation} property of that symbol; if that has a ++non-@code{nil} value, the documentation comes from that value (if the ++value is not a string, it is evaluated). If @var{function} is not a ++symbol, or if it has no @code{function-documentation} property, then ++@code{documentation} extracts the documentation string from the actual ++function definition, reading it from a file if called for. ++ ++Finally, unless @var{verbatim} is non-@code{nil}, it calls ++@code{substitute-command-keys} so as to return a value containing the ++actual (current) key bindings. ++ ++The function @code{documentation} signals a @code{void-function} error ++if @var{function} has no function definition. However, it is OK if ++the function definition has no documentation string. In that case, ++@code{documentation} returns @code{nil}. ++@end defun ++ ++@defun face-documentation face ++This function returns the documentation string of @var{face} as a ++face. ++@end defun ++ ++@c Wordy to prevent overfull hboxes. --rjc 15mar92 ++Here is an example of using the two functions, @code{documentation} and ++@code{documentation-property}, to display the documentation strings for ++several symbols in a @samp{*Help*} buffer. ++ ++@anchor{describe-symbols example} ++@smallexample ++@group ++(defun describe-symbols (pattern) ++ "Describe the Emacs Lisp symbols matching PATTERN. ++All symbols that have PATTERN in their name are described ++in the `*Help*' buffer." ++ (interactive "sDescribe symbols matching: ") ++ (let ((describe-func ++ (function ++ (lambda (s) ++@end group ++@group ++ ;; @r{Print description of symbol.} ++ (if (fboundp s) ; @r{It is a function.} ++ (princ ++ (format "%s\t%s\n%s\n\n" s ++ (if (commandp s) ++ (let ((keys (where-is-internal s))) ++ (if keys ++ (concat ++ "Keys: " ++ (mapconcat 'key-description ++ keys " ")) ++ "Keys: none")) ++ "Function") ++@end group ++@group ++ (or (documentation s) ++ "not documented")))) ++ ++ (if (boundp s) ; @r{It is a variable.} ++@end group ++@group ++ (princ ++ (format "%s\t%s\n%s\n\n" s ++ (if (user-variable-p s) ++ "Option " "Variable") ++@end group ++@group ++ (or (documentation-property ++ s 'variable-documentation) ++ "not documented"))))))) ++ sym-list) ++@end group ++ ++@group ++ ;; @r{Build a list of symbols that match pattern.} ++ (mapatoms (function ++ (lambda (sym) ++ (if (string-match pattern (symbol-name sym)) ++ (setq sym-list (cons sym sym-list)))))) ++@end group ++ ++@group ++ ;; @r{Display the data.} ++ (help-setup-xref (list 'describe-symbols pattern) (interactive-p)) ++ (with-help-window (help-buffer) ++ (mapcar describe-func (sort sym-list 'string<))))) ++@end group ++@end smallexample ++ ++ The @code{describe-symbols} function works like @code{apropos}, ++but provides more information. ++ ++@smallexample ++@group ++(describe-symbols "goal") ++ ++---------- Buffer: *Help* ---------- ++goal-column Option ++Semipermanent goal column for vertical motion, as set by @dots{} ++@end group ++@c Do not blithely break or fill these lines. ++@c That makes them incorrect. ++ ++@group ++set-goal-column Keys: C-x C-n ++Set the current horizontal position as a goal for C-n and C-p. ++@end group ++@c DO NOT put a blank line here! That is factually inaccurate! ++@group ++Those commands will move to this position in the line moved to ++rather than trying to keep the same horizontal position. ++With a non-nil argument, clears out the goal column ++so that C-n and C-p resume vertical motion. ++The goal column is stored in the variable `goal-column'. ++@end group ++ ++@group ++temporary-goal-column Variable ++Current goal column for vertical motion. ++It is the column where point was ++at the start of current run of vertical motion commands. ++When the `track-eol' feature is doing its job, the value is 9999. ++---------- Buffer: *Help* ---------- ++@end group ++@end smallexample ++ ++@defun Snarf-documentation filename ++@anchor{Definition of Snarf-documentation} ++This function is used only during Emacs initialization, just before ++the runnable Emacs is dumped. It finds the file offsets of the ++documentation strings stored in the file @var{filename}, and records ++them in the in-core function definitions and variable property lists in ++place of the actual strings. @xref{Building Emacs}. ++ ++Emacs reads the file @var{filename} from the @file{emacs/etc} directory. ++When the dumped Emacs is later executed, the same file will be looked ++for in the directory @code{doc-directory}. Usually @var{filename} is ++@code{"DOC-@var{version}"}. ++@end defun ++ ++@defvar doc-directory ++This variable holds the name of the directory which should contain the ++file @code{"DOC-@var{version}"} that contains documentation strings for ++built-in and preloaded functions and variables. ++ ++In most cases, this is the same as @code{data-directory}. They may be ++different when you run Emacs from the directory where you built it, ++without actually installing it. @xref{Definition of data-directory}. ++@end defvar ++ ++@node Keys in Documentation ++@section Substituting Key Bindings in Documentation ++@cindex documentation, keys in ++@cindex keys in documentation strings ++@cindex substituting keys in documentation ++ ++ When documentation strings refer to key sequences, they should use the ++current, actual key bindings. They can do so using certain special text ++sequences described below. Accessing documentation strings in the usual ++way substitutes current key binding information for these special ++sequences. This works by calling @code{substitute-command-keys}. You ++can also call that function yourself. ++ ++ Here is a list of the special sequences and what they mean: ++ ++@table @code ++@item \[@var{command}] ++stands for a key sequence that will invoke @var{command}, or @samp{M-x ++@var{command}} if @var{command} has no key bindings. ++ ++@item \@{@var{mapvar}@} ++stands for a summary of the keymap which is the value of the variable ++@var{mapvar}. The summary is made using @code{describe-bindings}. ++ ++@item \<@var{mapvar}> ++stands for no text itself. It is used only for a side effect: it ++specifies @var{mapvar}'s value as the keymap for any following ++@samp{\[@var{command}]} sequences in this documentation string. ++ ++@item \= ++quotes the following character and is discarded; thus, @samp{\=\[} puts ++@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the ++output. ++@end table ++ ++@strong{Please note:} Each @samp{\} must be doubled when written in a ++string in Emacs Lisp. ++ ++@defun substitute-command-keys string ++This function scans @var{string} for the above special sequences and ++replaces them by what they stand for, returning the result as a string. ++This permits display of documentation that refers accurately to the ++user's own customized key bindings. ++@end defun ++ ++ Here are examples of the special sequences: ++ ++@smallexample ++@group ++(substitute-command-keys ++ "To abort recursive edit, type: \\[abort-recursive-edit]") ++@result{} "To abort recursive edit, type: C-]" ++@end group ++ ++@group ++(substitute-command-keys ++ "The keys that are defined for the minibuffer here are: ++ \\@{minibuffer-local-must-match-map@}") ++@result{} "The keys that are defined for the minibuffer here are: ++@end group ++ ++? minibuffer-completion-help ++SPC minibuffer-complete-word ++TAB minibuffer-complete ++C-j minibuffer-complete-and-exit ++RET minibuffer-complete-and-exit ++C-g abort-recursive-edit ++" ++ ++@group ++(substitute-command-keys ++ "To abort a recursive edit from the minibuffer, type\ ++\\\\[abort-recursive-edit].") ++@result{} "To abort a recursive edit from the minibuffer, type C-g." ++@end group ++@end smallexample ++ ++ There are other special conventions for the text in documentation ++strings---for instance, you can refer to functions, variables, and ++sections of this manual. @xref{Documentation Tips}, for details. ++ ++@node Describing Characters ++@section Describing Characters for Help Messages ++@cindex describe characters and events ++ ++ These functions convert events, key sequences, or characters to ++textual descriptions. These descriptions are useful for including ++arbitrary text characters or key sequences in messages, because they ++convert non-printing and whitespace characters to sequences of printing ++characters. The description of a non-whitespace printing character is ++the character itself. ++ ++@defun key-description sequence &optional prefix ++@cindex Emacs event standard notation ++This function returns a string containing the Emacs standard notation ++for the input events in @var{sequence}. If @var{prefix} is ++non-@code{nil}, it is a sequence of input events leading up to ++@var{sequence} and is included in the return value. Both arguments ++may be strings, vectors or lists. @xref{Input Events}, for more ++information about valid events. ++ ++@smallexample ++@group ++(key-description [?\M-3 delete]) ++ @result{} "M-3 " ++@end group ++@group ++(key-description [delete] "\M-3") ++ @result{} "M-3 " ++@end group ++@end smallexample ++ ++ See also the examples for @code{single-key-description}, below. ++@end defun ++ ++@defun single-key-description event &optional no-angles ++@cindex event printing ++@cindex character printing ++@cindex control character printing ++@cindex meta character printing ++This function returns a string describing @var{event} in the standard ++Emacs notation for keyboard input. A normal printing character ++appears as itself, but a control character turns into a string ++starting with @samp{C-}, a meta character turns into a string starting ++with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC}, ++@samp{TAB}, etc. A function key symbol appears inside angle brackets ++@samp{<@dots{}>}. An event that is a list appears as the name of the ++symbol in the @sc{car} of the list, inside angle brackets. ++ ++If the optional argument @var{no-angles} is non-@code{nil}, the angle ++brackets around function keys and event symbols are omitted; this is ++for compatibility with old versions of Emacs which didn't use the ++brackets. ++ ++@smallexample ++@group ++(single-key-description ?\C-x) ++ @result{} "C-x" ++@end group ++@group ++(key-description "\C-x \M-y \n \t \r \f123") ++ @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3" ++@end group ++@group ++(single-key-description 'delete) ++ @result{} "" ++@end group ++@group ++(single-key-description 'C-mouse-1) ++ @result{} "" ++@end group ++@group ++(single-key-description 'C-mouse-1 t) ++ @result{} "C-mouse-1" ++@end group ++@end smallexample ++@end defun ++ ++@defun text-char-description character ++This function returns a string describing @var{character} in the ++standard Emacs notation for characters that appear in text---like ++@code{single-key-description}, except that control characters are ++represented with a leading caret (which is how control characters in ++Emacs buffers are usually displayed). Another difference is that ++@code{text-char-description} recognizes the 2**7 bit as the Meta ++character, whereas @code{single-key-description} uses the 2**27 bit ++for Meta. ++ ++@smallexample ++@group ++(text-char-description ?\C-c) ++ @result{} "^C" ++@end group ++@group ++(text-char-description ?\M-m) ++ @result{} "\xed" ++@end group ++@group ++(text-char-description ?\C-\M-m) ++ @result{} "\x8d" ++@end group ++@group ++(text-char-description (+ 128 ?m)) ++ @result{} "M-m" ++@end group ++@group ++(text-char-description (+ 128 ?\C-m)) ++ @result{} "M-^M" ++@end group ++@end smallexample ++@end defun ++ ++@defun read-kbd-macro string &optional need-vector ++This function is used mainly for operating on keyboard macros, but it ++can also be used as a rough inverse for @code{key-description}. You ++call it with a string containing key descriptions, separated by spaces; ++it returns a string or vector containing the corresponding events. ++(This may or may not be a single valid key sequence, depending on what ++events you use; @pxref{Key Sequences}.) If @var{need-vector} is ++non-@code{nil}, the return value is always a vector. ++@end defun ++ ++@node Help Functions ++@section Help Functions ++ ++ Emacs provides a variety of on-line help functions, all accessible to ++the user as subcommands of the prefix @kbd{C-h}. For more information ++about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here ++we describe some program-level interfaces to the same information. ++ ++@deffn Command apropos pattern &optional do-all ++This function finds all ``meaningful'' symbols whose names contain a ++match for the apropos pattern @var{pattern}. An apropos pattern is ++either a word to match, a space-separated list of words of which at ++least two must match, or a regular expression (if any special regular ++expression characters occur). A symbol is ``meaningful'' if it has a ++definition as a function, variable, or face, or has properties. ++ ++The function returns a list of elements that look like this: ++ ++@example ++(@var{symbol} @var{score} @var{fn-doc} @var{var-doc} ++ @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc}) ++@end example ++ ++Here, @var{score} is an integer measure of how important the symbol ++seems to be as a match, and the remaining elements are documentation ++strings for @var{symbol}'s various roles (or @code{nil}). ++ ++It also displays the symbols in a buffer named @samp{*Apropos*}, each ++with a one-line description taken from the beginning of its ++documentation string. ++ ++If @var{do-all} is non-@code{nil}, or if the user option ++@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also ++shows key bindings for the functions that are found; it also shows ++@emph{all} interned symbols, not just meaningful ones (and it lists ++them in the return value as well). ++@end deffn ++ ++@defvar help-map ++The value of this variable is a local keymap for characters following the ++Help key, @kbd{C-h}. ++@end defvar ++ ++@deffn {Prefix Command} help-command ++This symbol is not a function; its function definition cell holds the ++keymap known as @code{help-map}. It is defined in @file{help.el} as ++follows: ++ ++@smallexample ++@group ++(define-key global-map (char-to-string help-char) 'help-command) ++(fset 'help-command help-map) ++@end group ++@end smallexample ++@end deffn ++ ++@defopt help-char ++The value of this variable is the help character---the character that ++Emacs recognizes as meaning Help. By default, its value is 8, which ++stands for @kbd{C-h}. When Emacs reads this character, if ++@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that ++expression, and displays the result in a window if it is a string. ++ ++Usually the value of @code{help-form} is @code{nil}. Then the ++help character has no special meaning at the level of command input, and ++it becomes part of a key sequence in the normal way. The standard key ++binding of @kbd{C-h} is a prefix key for several general-purpose help ++features. ++ ++The help character is special after prefix keys, too. If it has no ++binding as a subcommand of the prefix key, it runs ++@code{describe-prefix-bindings}, which displays a list of all the ++subcommands of the prefix key. ++@end defopt ++ ++@defopt help-event-list ++The value of this variable is a list of event types that serve as ++alternative ``help characters.'' These events are handled just like the ++event specified by @code{help-char}. ++@end defopt ++ ++@defvar help-form ++If this variable is non-@code{nil}, its value is a form to evaluate ++whenever the character @code{help-char} is read. If evaluating the form ++produces a string, that string is displayed. ++ ++A command that calls @code{read-event} or @code{read-char} probably ++should bind @code{help-form} to a non-@code{nil} expression while it ++does input. (The time when you should not do this is when @kbd{C-h} has ++some other meaning.) Evaluating this expression should result in a ++string that explains what the input is for and how to enter it properly. ++ ++Entry to the minibuffer binds this variable to the value of ++@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}). ++@end defvar ++ ++@defvar prefix-help-command ++This variable holds a function to print help for a prefix key. The ++function is called when the user types a prefix key followed by the help ++character, and the help character has no binding after that prefix. The ++variable's default value is @code{describe-prefix-bindings}. ++@end defvar ++ ++@defun describe-prefix-bindings ++This function calls @code{describe-bindings} to display a list of all ++the subcommands of the prefix key of the most recent key sequence. The ++prefix described consists of all but the last event of that key ++sequence. (The last event is, presumably, the help character.) ++@end defun ++ ++ The following two functions are meant for modes that want to provide ++help without relinquishing control, such as the ``electric'' modes. ++Their names begin with @samp{Helper} to distinguish them from the ++ordinary help functions. ++ ++@deffn Command Helper-describe-bindings ++This command pops up a window displaying a help buffer containing a ++listing of all of the key bindings from both the local and global keymaps. ++It works by calling @code{describe-bindings}. ++@end deffn ++ ++@deffn Command Helper-help ++This command provides help for the current mode. It prompts the user ++in the minibuffer with the message @samp{Help (Type ? for further ++options)}, and then provides assistance in finding out what the key ++bindings are, and what the mode is intended for. It returns @code{nil}. ++ ++This can be customized by changing the map @code{Helper-help-map}. ++@end deffn ++ ++@defvar data-directory ++@anchor{Definition of data-directory} ++This variable holds the name of the directory in which Emacs finds ++certain documentation and text files that come with Emacs. ++@end defvar ++ ++@defun help-buffer ++This function returns the name of the help buffer, which is normally ++@samp{*Help*}; if such a buffer does not exist, it is first created. ++@end defun ++ ++@defmac with-help-window buffer-name body@dots{} ++This macro evaluates the @var{body} forms, inserting any output they ++produce into a buffer named @var{buffer-name} like ++@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}). ++(Usually, @var{buffer-name} should be the value returned by the ++function @code{help-buffer}.) It also puts the specified buffer into ++Help mode and displays a message telling the user how to quit and ++scroll the help window. ++@end defmac ++ ++@defun help-setup-xref item interactive-p ++This function updates the cross reference data in the @samp{*Help*} ++buffer, which is used to regenerate the help information when the user ++clicks on the @samp{Back} or @samp{Forward} buttons. Most commands ++that use the @samp{*Help*} buffer should invoke this function before ++clearing the buffer. The @var{item} argument should have the form ++@code{(@var{funtion} . @var{args})}, where @var{funtion} is a function ++to call, with argument list @var{args}, to regenerate the help buffer. ++The @var{interactive-p} argument is non-@code{nil} if the calling ++command was invoked interactively; in that case, the stack of items ++for the @samp{*Help*} buffer's @samp{Back} buttons is cleared. ++@end defun ++ ++@xref{describe-symbols example}, for an example of using ++@code{help-buffer}, @code{with-help-window}, and ++@code{help-setup-xref}. ++ ++@defmac make-help-screen fname help-line help-text help-map ++This macro defines a help command named @var{fname} that acts like a ++prefix key that shows a list of the subcommands it offers. ++ ++When invoked, @var{fname} displays @var{help-text} in a window, then ++reads and executes a key sequence according to @var{help-map}. The ++string @var{help-text} should describe the bindings available in ++@var{help-map}. ++ ++The command @var{fname} is defined to handle a few events itself, by ++scrolling the display of @var{help-text}. When @var{fname} reads one of ++those special events, it does the scrolling and then reads another ++event. When it reads an event that is not one of those few, and which ++has a binding in @var{help-map}, it executes that key's binding and ++then returns. ++ ++The argument @var{help-line} should be a single-line summary of the ++alternatives in @var{help-map}. In the current version of Emacs, this ++argument is used only if you set the option @code{three-step-help} to ++@code{t}. ++ ++This macro is used in the command @code{help-for-help} which is the ++binding of @kbd{C-h C-h}. ++@end defmac ++ ++@defopt three-step-help ++If this variable is non-@code{nil}, commands defined with ++@code{make-help-screen} display their @var{help-line} strings in the ++echo area at first, and display the longer @var{help-text} strings only ++if the user types the help character again. ++@end defopt ++ ++@ignore ++ arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815 ++@end ignore +diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi +new file mode 100644 +index 0000000..8eb5bcb +--- /dev/null ++++ b/doc/lispref/hooks.texi +@@ -0,0 +1,358 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/hooks ++@node Standard Hooks, Index, Standard Keymaps, Top ++@appendix Standard Hooks ++@cindex standard hooks ++@cindex hook variables, list of ++ ++The following is a list of hook variables that let you provide ++functions to be called from within Emacs on suitable occasions. ++ ++Most of these variables have names ending with @samp{-hook}. They are ++@dfn{normal hooks}, run by means of @code{run-hooks}. The value of such ++a hook is a list of functions; the functions are called with no ++arguments and their values are completely ignored. The recommended way ++to put a new function on such a hook is to call @code{add-hook}. ++@xref{Hooks}, for more information about using hooks. ++ ++Every major mode defines a mode hook named ++@samp{@var{modename}-mode-hook}. The major mode command runs this ++normal hook with @code{run-mode-hooks} as the very last thing it does. ++@xref{Mode Hooks}. Most minor modes have mode hooks too. Mode hooks ++are omitted in the list below. ++ ++The variables whose names end in @samp{-hooks} or @samp{-functions} are ++usually @dfn{abnormal hooks}; their values are lists of functions, but ++these functions are called in a special way (they are passed arguments, ++or their values are used). The variables whose names end in ++@samp{-function} have single functions as their values. ++ ++A special feature allows you to specify expressions to evaluate if and ++when a file is loaded (@pxref{Hooks for Loading}). That feature is ++not exactly a hook, but does a similar job. ++ ++@c We need to xref to where each hook is documented or else document ++@c it here. ++ ++@table @code ++@item abbrev-expand-functions ++@xref{Abbrev Expansion}. ++ ++@item activate-mark-hook ++@xref{The Mark}. ++ ++@item after-change-functions ++@xref{Change Hooks}. ++ ++@item after-change-major-mode-hook ++@xref{Mode Hooks}. ++ ++@item after-init-hook ++@xref{Init File}. ++ ++@item after-insert-file-functions ++@xref{Format Conversion}. ++ ++@item after-make-frame-functions ++@xref{Creating Frames}. ++ ++@item after-revert-hook ++@xref{Reverting}. ++ ++@item after-save-hook ++@xref{Saving Buffers}. ++ ++@item auto-fill-function ++@xref{Auto Filling}. ++ ++@item auto-save-hook ++@xref{Auto-Saving}. ++ ++@item before-change-functions ++@xref{Change Hooks}. ++ ++@item before-hack-local-variables-hook ++@xref{File Local Variables}. ++ ++@item before-init-hook ++@xref{Init File}. ++ ++@item before-make-frame-hook ++@xref{Creating Frames}. ++ ++@item before-revert-hook ++@xref{Reverting}. ++ ++@item before-save-hook ++@xref{Saving Buffers}. ++ ++@item blink-paren-function ++@xref{Blinking}. ++ ++@item buffer-access-fontify-functions ++@xref{Lazy Properties}. ++ ++@item calendar-load-hook ++@iftex ++@inforef{Calendar Customizing,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Calendar Customizing,,, emacs}. ++@end ifnottex ++ ++ ++@item change-major-mode-hook ++@xref{Creating Buffer-Local}. ++ ++@item command-line-functions ++@xref{Command-Line Arguments}. ++ ++@item comment-indent-function ++@xref{Options for Comments,, Options Controlling Comments, emacs, the ++GNU Emacs Manual}. ++ ++@item compilation-finish-functions ++Functions to call when a compilation process finishes. ++ ++@item custom-define-hook ++Hook called after defining each customize option. ++ ++@item deactivate-mark-hook ++@xref{The Mark}. ++ ++@item delete-frame-functions ++Functions to call when Emacs deletes a frame. @xref{Deleting Frames}. ++ ++@item delete-terminal-functions ++Functions to call when Emacs deletes a terminal. @xref{Multiple ++Terminals}. ++ ++@item desktop-after-read-hook ++Normal hook run after a successful @code{desktop-read}. May be used ++to show a buffer list. @xref{Saving Emacs Sessions,, Saving Emacs ++Sessions, emacs, the GNU Emacs Manual}. ++ ++@item desktop-no-desktop-file-hook ++Normal hook run when @code{desktop-read} can't find a desktop file. ++May be used to show a dired buffer. @xref{Saving Emacs Sessions,, ++Saving Emacs Sessions, emacs, the GNU Emacs Manual}. ++ ++@item desktop-save-hook ++Normal hook run before the desktop is saved in a desktop file. This ++is useful for truncating history lists, for example. @xref{Saving ++Emacs Sessions,, Saving Emacs Sessions, emacs, the GNU Emacs Manual}. ++ ++@item diary-display-hook ++@iftex ++@inforef{Fancy Diary Display,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Fancy Diary Display,,, emacs}. ++@end ifnottex ++ ++@item diary-hook ++List of functions called after the display of the diary. Can be used ++for appointment notification. ++ ++@item disabled-command-function ++@xref{Disabling Commands}. ++ ++@item echo-area-clear-hook ++@xref{Echo Area Customization}. ++ ++@item emacs-startup-hook ++@xref{Init File}. ++ ++@item find-file-hook ++@xref{Visiting Functions}. ++ ++@item find-file-not-found-functions ++@xref{Visiting Functions}. ++ ++@item first-change-hook ++@xref{Change Hooks}. ++ ++@item font-lock-beginning-of-syntax-function ++@xref{Syntactic Font Lock}. ++ ++@item font-lock-fontify-buffer-function ++@xref{Other Font Lock Variables}. ++ ++@item font-lock-fontify-region-function ++@xref{Other Font Lock Variables}. ++ ++@item font-lock-mark-block-function ++@xref{Other Font Lock Variables}. ++ ++@item font-lock-syntactic-face-function ++@xref{Syntactic Font Lock}. ++ ++@item font-lock-unfontify-buffer-function ++@xref{Other Font Lock Variables}. ++ ++@item hack-local-variables-hook ++@xref{File Local Variables}. ++ ++@item font-lock-unfontify-region-function ++@xref{Other Font Lock Variables}. ++ ++@item initial-calendar-window-hook ++@iftex ++@inforef{Calendar Customizing,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Calendar Customizing,,, emacs}. ++@end ifnottex ++ ++@item kbd-macro-termination-hook ++@xref{Keyboard Macros}. ++ ++@item kill-buffer-hook ++@xref{Killing Buffers}. ++ ++@item kill-buffer-query-functions ++@xref{Killing Buffers}. ++ ++@item kill-emacs-hook ++@xref{Killing Emacs}. ++ ++@item kill-emacs-query-functions ++@xref{Killing Emacs}. ++ ++@item lisp-indent-function ++ ++@item list-diary-entries-hook ++@iftex ++@inforef{Fancy Diary Display,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Fancy Diary Display,,, emacs}. ++@end ifnottex ++ ++@item mail-setup-hook ++@xref{Mail Mode Misc,, Mail Mode Miscellany, emacs, the GNU Emacs ++Manual}. ++ ++@item mark-diary-entries-hook ++@iftex ++@inforef{Fancy Diary Display,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Fancy Diary Display,,, emacs}. ++@end ifnottex ++ ++@item menu-bar-update-hook ++@xref{Menu Bar}. ++ ++@item minibuffer-setup-hook ++@xref{Minibuffer Misc}. ++ ++@item minibuffer-exit-hook ++@xref{Minibuffer Misc}. ++ ++@item mouse-position-function ++@xref{Mouse Position}. ++ ++@item nongregorian-diary-listing-hook ++@iftex ++@inforef{Non-Gregorian Diary,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Non-Gregorian Diary,,, emacs}. ++@end ifnottex ++ ++@item nongregorian-diary-marking-hook ++@iftex ++@inforef{Non-Gregorian Diary,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Non-Gregorian Diary,,, emacs}. ++@end ifnottex ++ ++@item occur-hook ++ ++@item post-command-hook ++@xref{Command Overview}. ++ ++@item pre-command-hook ++@xref{Command Overview}. ++ ++@item print-diary-entries-hook ++@iftex ++@inforef{Diary Customizing,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Diary Customizing,,, emacs}. ++@end ifnottex ++ ++@item resume-tty-functions ++@xref{Suspending Emacs}. ++ ++@item scheme-indent-function ++ ++@item suspend-hook ++@xref{Suspending Emacs}. ++ ++@item suspend-resume-hook ++@xref{Suspending Emacs}. ++ ++@item suspend-tty-functions ++@xref{Suspending Emacs}. ++ ++@item temp-buffer-setup-hook ++@xref{Temporary Displays}. ++ ++@item temp-buffer-show-function ++@xref{Temporary Displays}. ++ ++@item temp-buffer-show-hook ++@xref{Temporary Displays}. ++ ++@item term-setup-hook ++@xref{Terminal-Specific}. ++ ++@item today-visible-calendar-hook ++@iftex ++@inforef{Calendar Customizing,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Calendar Customizing,,, emacs}. ++@end ifnottex ++ ++@item today-invisible-calendar-hook ++@iftex ++@inforef{Calendar Customizing,, emacs-xtra}. ++@end iftex ++@ifnottex ++@xref{Calendar Customizing,,, emacs}. ++@end ifnottex ++ ++@item window-configuration-change-hook ++@xref{Window Hooks}. ++ ++@item window-scroll-functions ++@xref{Window Hooks}. ++ ++@item window-setup-hook ++@xref{Window Systems}. ++ ++@item window-size-change-functions ++@xref{Window Hooks}. ++ ++@item write-contents-functions ++@xref{Saving Buffers}. ++ ++@item write-file-functions ++@xref{Saving Buffers}. ++ ++@item write-region-annotate-functions ++@xref{Format Conversion}. ++@end table ++ ++@ignore ++ arch-tag: 55fd0296-d906-4551-b300-979d3846aa88 ++@end ignore +diff --git a/doc/lispref/index.texi b/doc/lispref/index.texi +new file mode 100644 +index 0000000..6cdadf9 +--- /dev/null ++++ b/doc/lispref/index.texi +@@ -0,0 +1,29 @@ ++@c -*-texinfo-*- ++@setfilename ../../info/index ++ ++@c Indexing guidelines ++ ++@c I assume that all indexes will be combined. ++@c Therefore, if a generated findex and permutations ++@c cover the ways an index user would look up the entry, ++@c then no cindex is added. ++@c Concept index (cindex) entries will also be permuted. Therefore, they ++@c have no commas and few irrelevant connectives in them. ++ ++@c I tried to include words in a cindex that give the context of the entry, ++@c particularly if there is more than one entry for the same concept. ++@c For example, "nil in keymap" ++@c Similarly for explicit findex and vindex entries, e.g. "print example". ++ ++@c Error codes are given cindex entries, e.g. "end-of-file error". ++ ++@c pindex is used for .el files and Unix programs ++ ++@node Index, , Standard Hooks, Top ++@unnumbered Index ++ ++@c Print the indices ++ ++@printindex fn ++ ++ +diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi +new file mode 100644 +index 0000000..e281498 +--- /dev/null ++++ b/doc/lispref/internals.texi +@@ -0,0 +1,1404 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2001, 2002, 2003, ++@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/internals ++@node GNU Emacs Internals, Standard Errors, Tips, Top ++@comment node-name, next, previous, up ++@appendix GNU Emacs Internals ++ ++This chapter describes how the runnable Emacs executable is dumped with ++the preloaded Lisp libraries in it, how storage is allocated, and some ++internal aspects of GNU Emacs that may be of interest to C programmers. ++ ++@menu ++* Building Emacs:: How the dumped Emacs is made. ++* Pure Storage:: A kludge to make preloaded Lisp functions sharable. ++* Garbage Collection:: Reclaiming space for Lisp objects no longer used. ++* Memory Usage:: Info about total size of Lisp objects made so far. ++* Writing Emacs Primitives:: Writing C code for Emacs. ++* Object Internals:: Data formats of buffers, windows, processes. ++@end menu ++ ++@node Building Emacs ++@appendixsec Building Emacs ++@cindex building Emacs ++@pindex temacs ++ ++ This section explains the steps involved in building the Emacs ++executable. You don't have to know this material to build and install ++Emacs, since the makefiles do all these things automatically. This ++information is pertinent to Emacs maintenance. ++ ++ Compilation of the C source files in the @file{src} directory ++produces an executable file called @file{temacs}, also called a ++@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O ++routines, but not the editing commands. ++ ++@cindex @file{loadup.el} ++ The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create ++the real runnable Emacs executable. These arguments direct ++@file{temacs} to evaluate the Lisp files specified in the file ++@file{loadup.el}. These files set up the normal Emacs editing ++environment, resulting in an Emacs that is still impure but no longer ++bare. ++ ++@cindex dumping Emacs ++ It takes a substantial time to load the standard Lisp files. Luckily, ++you don't have to do this each time you run Emacs; @file{temacs} can ++dump out an executable program called @file{emacs} that has these files ++preloaded. @file{emacs} starts more quickly because it does not need to ++load the files. This is the Emacs executable that is normally ++installed. ++ ++ To create @file{emacs}, use the command @samp{temacs -batch -l loadup ++dump}. The purpose of @samp{-batch} here is to prevent @file{temacs} ++from trying to initialize any of its data on the terminal; this ensures ++that the tables of terminal information are empty in the dumped Emacs. ++The argument @samp{dump} tells @file{loadup.el} to dump a new executable ++named @file{emacs}. ++ ++ Some operating systems don't support dumping. On those systems, you ++must start Emacs with the @samp{temacs -l loadup} command each time you ++use it. This takes a substantial time, but since you need to start ++Emacs once a day at most---or once a week if you never log out---the ++extra time is not too severe a problem. ++ ++@cindex @file{site-load.el} ++ ++ You can specify additional files to preload by writing a library named ++@file{site-load.el} that loads them. You may need to add a definition ++ ++@example ++#define SITELOAD_PURESIZE_EXTRA @var{n} ++@end example ++ ++@noindent ++to make @var{n} added bytes of pure space to hold the additional files. ++(Try adding increments of 20000 until it is big enough.) However, the ++advantage of preloading additional files decreases as machines get ++faster. On modern machines, it is usually not advisable. ++ ++ After @file{loadup.el} reads @file{site-load.el}, it finds the ++documentation strings for primitive and preloaded functions (and ++variables) in the file @file{etc/DOC} where they are stored, by ++calling @code{Snarf-documentation} (@pxref{Definition of ++Snarf-documentation,, Accessing Documentation}). ++ ++@cindex @file{site-init.el} ++@cindex preloading additional functions and variables ++ You can specify other Lisp expressions to execute just before dumping ++by putting them in a library named @file{site-init.el}. This file is ++executed after the documentation strings are found. ++ ++ If you want to preload function or variable definitions, there are ++three ways you can do this and make their documentation strings ++accessible when you subsequently run Emacs: ++ ++@itemize @bullet ++@item ++Arrange to scan these files when producing the @file{etc/DOC} file, ++and load them with @file{site-load.el}. ++ ++@item ++Load the files with @file{site-init.el}, then copy the files into the ++installation directory for Lisp files when you install Emacs. ++ ++@item ++Specify a non-@code{nil} value for ++@code{byte-compile-dynamic-docstrings} as a local variable in each of these ++files, and load them with either @file{site-load.el} or ++@file{site-init.el}. (This method has the drawback that the ++documentation strings take up space in Emacs all the time.) ++@end itemize ++ ++ It is not advisable to put anything in @file{site-load.el} or ++@file{site-init.el} that would alter any of the features that users ++expect in an ordinary unmodified Emacs. If you feel you must override ++normal features for your site, do it with @file{default.el}, so that ++users can override your changes if they wish. @xref{Startup Summary}. ++ ++ In a package that can be preloaded, it is sometimes useful to ++specify a computation to be done when Emacs subsequently starts up. ++For this, use @code{eval-at-startup}: ++ ++@defmac eval-at-startup body@dots{} ++This evaluates the @var{body} forms, either immediately if running in ++an Emacs that has already started up, or later when Emacs does start ++up. Since the value of the @var{body} forms is not necessarily ++available when the @code{eval-at-startup} form is run, that form ++always returns @code{nil}. ++@end defmac ++ ++@defun dump-emacs to-file from-file ++@cindex unexec ++This function dumps the current state of Emacs into an executable file ++@var{to-file}. It takes symbols from @var{from-file} (this is normally ++the executable file @file{temacs}). ++ ++If you want to use this function in an Emacs that was already dumped, ++you must run Emacs with @samp{-batch}. ++@end defun ++ ++@node Pure Storage ++@appendixsec Pure Storage ++@cindex pure storage ++ ++ Emacs Lisp uses two kinds of storage for user-created Lisp objects: ++@dfn{normal storage} and @dfn{pure storage}. Normal storage is where ++all the new data created during an Emacs session are kept; see the ++following section for information on normal storage. Pure storage is ++used for certain data in the preloaded standard Lisp files---data that ++should never change during actual use of Emacs. ++ ++ Pure storage is allocated only while @file{temacs} is loading the ++standard preloaded Lisp libraries. In the file @file{emacs}, it is ++marked as read-only (on operating systems that permit this), so that ++the memory space can be shared by all the Emacs jobs running on the ++machine at once. Pure storage is not expandable; a fixed amount is ++allocated when Emacs is compiled, and if that is not sufficient for ++the preloaded libraries, @file{temacs} allocates dynamic memory for ++the part that didn't fit. If that happens, you should increase the ++compilation parameter @code{PURESIZE} in the file ++@file{src/puresize.h} and rebuild Emacs, even though the resulting ++image will work: garbage collection is disabled in this situation, ++causing a memory leak. Such an overflow normally won't happen unless you ++try to preload additional libraries or add features to the standard ++ones. Emacs will display a warning about the overflow when it ++starts. ++ ++@defun purecopy object ++This function makes a copy in pure storage of @var{object}, and returns ++it. It copies a string by simply making a new string with the same ++characters, but without text properties, in pure storage. It ++recursively copies the contents of vectors and cons cells. It does ++not make copies of other objects such as symbols, but just returns ++them unchanged. It signals an error if asked to copy markers. ++ ++This function is a no-op except while Emacs is being built and dumped; ++it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but ++a few packages call it just in case you decide to preload them. ++@end defun ++ ++@defvar pure-bytes-used ++The value of this variable is the number of bytes of pure storage ++allocated so far. Typically, in a dumped Emacs, this number is very ++close to the total amount of pure storage available---if it were not, ++we would preallocate less. ++@end defvar ++ ++@defvar purify-flag ++This variable determines whether @code{defun} should make a copy of the ++function definition in pure storage. If it is non-@code{nil}, then the ++function definition is copied into pure storage. ++ ++This flag is @code{t} while loading all of the basic functions for ++building Emacs initially (allowing those functions to be sharable and ++non-collectible). Dumping Emacs as an executable always writes ++@code{nil} in this variable, regardless of the value it actually has ++before and after dumping. ++ ++You should not change this flag in a running Emacs. ++@end defvar ++ ++@node Garbage Collection ++@appendixsec Garbage Collection ++@cindex garbage collection ++ ++@cindex memory allocation ++ When a program creates a list or the user defines a new function (such ++as by loading a library), that data is placed in normal storage. If ++normal storage runs low, then Emacs asks the operating system to ++allocate more memory in blocks of 1k bytes. Each block is used for one ++type of Lisp object, so symbols, cons cells, markers, etc., are ++segregated in distinct blocks in memory. (Vectors, long strings, ++buffers and certain other editing types, which are fairly large, are ++allocated in individual blocks, one per object, while small strings are ++packed into blocks of 8k bytes.) ++ ++ It is quite common to use some storage for a while, then release it by ++(for example) killing a buffer or deleting the last pointer to an ++object. Emacs provides a @dfn{garbage collector} to reclaim this ++abandoned storage. (This name is traditional, but ``garbage recycler'' ++might be a more intuitive metaphor for this facility.) ++ ++ The garbage collector operates by finding and marking all Lisp objects ++that are still accessible to Lisp programs. To begin with, it assumes ++all the symbols, their values and associated function definitions, and ++any data presently on the stack, are accessible. Any objects that can ++be reached indirectly through other accessible objects are also ++accessible. ++ ++ When marking is finished, all objects still unmarked are garbage. No ++matter what the Lisp program or the user does, it is impossible to refer ++to them, since there is no longer a way to reach them. Their space ++might as well be reused, since no one will miss them. The second ++(``sweep'') phase of the garbage collector arranges to reuse them. ++ ++@c ??? Maybe add something describing weak hash tables here? ++ ++@cindex free list ++ The sweep phase puts unused cons cells onto a @dfn{free list} ++for future allocation; likewise for symbols and markers. It compacts ++the accessible strings so they occupy fewer 8k blocks; then it frees the ++other 8k blocks. Vectors, buffers, windows, and other large objects are ++individually allocated and freed using @code{malloc} and @code{free}. ++ ++@cindex CL note---allocate more storage ++@quotation ++@b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not ++call the garbage collector when the free list is empty. Instead, it ++simply requests the operating system to allocate more storage, and ++processing continues until @code{gc-cons-threshold} bytes have been ++used. ++ ++This means that you can make sure that the garbage collector will not ++run during a certain portion of a Lisp program by calling the garbage ++collector explicitly just before it (provided that portion of the ++program does not use so much space as to force a second garbage ++collection). ++@end quotation ++ ++@deffn Command garbage-collect ++This command runs a garbage collection, and returns information on ++the amount of space in use. (Garbage collection can also occur ++spontaneously if you use more than @code{gc-cons-threshold} bytes of ++Lisp data since the previous garbage collection.) ++ ++@code{garbage-collect} returns a list containing the following ++information: ++ ++@example ++@group ++((@var{used-conses} . @var{free-conses}) ++ (@var{used-syms} . @var{free-syms}) ++@end group ++ (@var{used-miscs} . @var{free-miscs}) ++ @var{used-string-chars} ++ @var{used-vector-slots} ++ (@var{used-floats} . @var{free-floats}) ++ (@var{used-intervals} . @var{free-intervals}) ++ (@var{used-strings} . @var{free-strings})) ++@end example ++ ++Here is an example: ++ ++@example ++@group ++(garbage-collect) ++ @result{} ((106886 . 13184) (9769 . 0) ++ (7731 . 4651) 347543 121628 ++ (31 . 94) (1273 . 168) ++ (25474 . 3569)) ++@end group ++@end example ++ ++Here is a table explaining each element: ++ ++@table @var ++@item used-conses ++The number of cons cells in use. ++ ++@item free-conses ++The number of cons cells for which space has been obtained from the ++operating system, but that are not currently being used. ++ ++@item used-syms ++The number of symbols in use. ++ ++@item free-syms ++The number of symbols for which space has been obtained from the ++operating system, but that are not currently being used. ++ ++@item used-miscs ++The number of miscellaneous objects in use. These include markers and ++overlays, plus certain objects not visible to users. ++ ++@item free-miscs ++The number of miscellaneous objects for which space has been obtained ++from the operating system, but that are not currently being used. ++ ++@item used-string-chars ++The total size of all strings, in characters. ++ ++@item used-vector-slots ++The total number of elements of existing vectors. ++ ++@item used-floats ++@c Emacs 19 feature ++The number of floats in use. ++ ++@item free-floats ++@c Emacs 19 feature ++The number of floats for which space has been obtained from the ++operating system, but that are not currently being used. ++ ++@item used-intervals ++The number of intervals in use. Intervals are an internal ++data structure used for representing text properties. ++ ++@item free-intervals ++The number of intervals for which space has been obtained ++from the operating system, but that are not currently being used. ++ ++@item used-strings ++The number of strings in use. ++ ++@item free-strings ++The number of string headers for which the space was obtained from the ++operating system, but which are currently not in use. (A string ++object consists of a header and the storage for the string text ++itself; the latter is only allocated when the string is created.) ++@end table ++ ++If there was overflow in pure space (see the previous section), ++@code{garbage-collect} returns @code{nil}, because a real garbage ++collection can not be done in this situation. ++@end deffn ++ ++@defopt garbage-collection-messages ++If this variable is non-@code{nil}, Emacs displays a message at the ++beginning and end of garbage collection. The default value is ++@code{nil}, meaning there are no such messages. ++@end defopt ++ ++@defvar post-gc-hook ++This is a normal hook that is run at the end of garbage collection. ++Garbage collection is inhibited while the hook functions run, so be ++careful writing them. ++@end defvar ++ ++@defopt gc-cons-threshold ++The value of this variable is the number of bytes of storage that must ++be allocated for Lisp objects after one garbage collection in order to ++trigger another garbage collection. A cons cell counts as eight bytes, ++a string as one byte per character plus a few bytes of overhead, and so ++on; space allocated to the contents of buffers does not count. Note ++that the subsequent garbage collection does not happen immediately when ++the threshold is exhausted, but only the next time the Lisp evaluator is ++called. ++ ++The initial threshold value is 400,000. If you specify a larger ++value, garbage collection will happen less often. This reduces the ++amount of time spent garbage collecting, but increases total memory use. ++You may want to do this when running a program that creates lots of ++Lisp data. ++ ++You can make collections more frequent by specifying a smaller value, ++down to 10,000. A value less than 10,000 will remain in effect only ++until the subsequent garbage collection, at which time ++@code{garbage-collect} will set the threshold back to 10,000. ++@end defopt ++ ++@defopt gc-cons-percentage ++The value of this variable specifies the amount of consing before a ++garbage collection occurs, as a fraction of the current heap size. ++This criterion and @code{gc-cons-threshold} apply in parallel, and ++garbage collection occurs only when both criteria are satisfied. ++ ++As the heap size increases, the time to perform a garbage collection ++increases. Thus, it can be desirable to do them less frequently in ++proportion. ++@end defopt ++ ++ The value returned by @code{garbage-collect} describes the amount of ++memory used by Lisp data, broken down by data type. By contrast, the ++function @code{memory-limit} provides information on the total amount of ++memory Emacs is currently using. ++ ++@c Emacs 19 feature ++@defun memory-limit ++This function returns the address of the last byte Emacs has allocated, ++divided by 1024. We divide the value by 1024 to make sure it fits in a ++Lisp integer. ++ ++You can use this to get a general idea of how your actions affect the ++memory usage. ++@end defun ++ ++@defvar memory-full ++This variable is @code{t} if Emacs is close to out of memory for Lisp ++objects, and @code{nil} otherwise. ++@end defvar ++ ++@defun memory-use-counts ++This returns a list of numbers that count the number of objects ++created in this Emacs session. Each of these counters increments for ++a certain kind of object. See the documentation string for details. ++@end defun ++ ++@defvar gcs-done ++This variable contains the total number of garbage collections ++done so far in this Emacs session. ++@end defvar ++ ++@defvar gc-elapsed ++This variable contains the total number of seconds of elapsed time ++during garbage collection so far in this Emacs session, as a floating ++point number. ++@end defvar ++ ++@node Memory Usage ++@section Memory Usage ++@cindex memory usage ++ ++ These functions and variables give information about the total amount ++of memory allocation that Emacs has done, broken down by data type. ++Note the difference between these and the values returned by ++@code{(garbage-collect)}; those count objects that currently exist, but ++these count the number or size of all allocations, including those for ++objects that have since been freed. ++ ++@defvar cons-cells-consed ++The total number of cons cells that have been allocated so far ++in this Emacs session. ++@end defvar ++ ++@defvar floats-consed ++The total number of floats that have been allocated so far ++in this Emacs session. ++@end defvar ++ ++@defvar vector-cells-consed ++The total number of vector cells that have been allocated so far ++in this Emacs session. ++@end defvar ++ ++@defvar symbols-consed ++The total number of symbols that have been allocated so far ++in this Emacs session. ++@end defvar ++ ++@defvar string-chars-consed ++The total number of string characters that have been allocated so far ++in this Emacs session. ++@end defvar ++ ++@defvar misc-objects-consed ++The total number of miscellaneous objects that have been allocated so ++far in this Emacs session. These include markers and overlays, plus ++certain objects not visible to users. ++@end defvar ++ ++@defvar intervals-consed ++The total number of intervals that have been allocated so far ++in this Emacs session. ++@end defvar ++ ++@defvar strings-consed ++The total number of strings that have been allocated so far in this ++Emacs session. ++@end defvar ++ ++@node Writing Emacs Primitives ++@appendixsec Writing Emacs Primitives ++@cindex primitive function internals ++@cindex writing Emacs primitives ++ ++ Lisp primitives are Lisp functions implemented in C. The details of ++interfacing the C function so that Lisp can call it are handled by a few ++C macros. The only way to really understand how to write new C code is ++to read the source, but we can explain some things here. ++ ++ An example of a special form is the definition of @code{or}, from ++@file{eval.c}. (An ordinary function would have the same general ++appearance.) ++ ++@cindex garbage collection protection ++@smallexample ++@group ++DEFUN ("or", For, Sor, 0, UNEVALLED, 0, ++ doc: /* Eval args until one of them yields non-nil, then return that ++value. The remaining args are not evalled at all. ++If all args return nil, return nil. ++@end group ++@group ++usage: (or CONDITIONS ...) */) ++ (args) ++ Lisp_Object args; ++@{ ++ register Lisp_Object val = Qnil; ++ struct gcpro gcpro1; ++@end group ++ ++@group ++ GCPRO1 (args); ++@end group ++ ++@group ++ while (CONSP (args)) ++ @{ ++ val = Feval (XCAR (args)); ++ if (!NILP (val)) ++ break; ++ args = XCDR (args); ++ @} ++@end group ++ ++@group ++ UNGCPRO; ++ return val; ++@} ++@end group ++@end smallexample ++ ++@cindex @code{DEFUN}, C macro to define Lisp primitives ++ Let's start with a precise explanation of the arguments to the ++@code{DEFUN} macro. Here is a template for them: ++ ++@example ++DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) ++@end example ++ ++@table @var ++@item lname ++This is the name of the Lisp symbol to define as the function name; in ++the example above, it is @code{or}. ++ ++@item fname ++This is the C function name for this function. This is ++the name that is used in C code for calling the function. The name is, ++by convention, @samp{F} prepended to the Lisp name, with all dashes ++(@samp{-}) in the Lisp name changed to underscores. Thus, to call this ++function from C code, call @code{For}. Remember that the arguments must ++be of type @code{Lisp_Object}; various macros and functions for creating ++values of type @code{Lisp_Object} are declared in the file ++@file{lisp.h}. ++ ++@item sname ++This is a C variable name to use for a structure that holds the data for ++the subr object that represents the function in Lisp. This structure ++conveys the Lisp symbol name to the initialization routine that will ++create the symbol and store the subr object as its definition. By ++convention, this name is always @var{fname} with @samp{F} replaced with ++@samp{S}. ++ ++@item min ++This is the minimum number of arguments that the function requires. The ++function @code{or} allows a minimum of zero arguments. ++ ++@item max ++This is the maximum number of arguments that the function accepts, if ++there is a fixed maximum. Alternatively, it can be @code{UNEVALLED}, ++indicating a special form that receives unevaluated arguments, or ++@code{MANY}, indicating an unlimited number of evaluated arguments (the ++equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are ++macros. If @var{max} is a number, it may not be less than @var{min} and ++it may not be greater than eight. ++ ++@item interactive ++This is an interactive specification, a string such as might be used as ++the argument of @code{interactive} in a Lisp function. In the case of ++@code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be ++called interactively. A value of @code{""} indicates a function that ++should receive no arguments when called interactively. If the value ++begins with a @samp{(}, the string is evaluated as a Lisp form. ++ ++@item doc ++This is the documentation string. It uses C comment syntax rather ++than C string syntax because comment syntax requires nothing special ++to include multiple lines. The @samp{doc:} identifies the comment ++that follows as the documentation string. The @samp{/*} and @samp{*/} ++delimiters that begin and end the comment are not part of the ++documentation string. ++ ++If the last line of the documentation string begins with the keyword ++@samp{usage:}, the rest of the line is treated as the argument list ++for documentation purposes. This way, you can use different argument ++names in the documentation string from the ones used in the C code. ++@samp{usage:} is required if the function has an unlimited number of ++arguments. ++ ++All the usual rules for documentation strings in Lisp code ++(@pxref{Documentation Tips}) apply to C code documentation strings ++too. ++@end table ++ ++ After the call to the @code{DEFUN} macro, you must write the argument ++name list that every C function must have, followed by ordinary C ++declarations for the arguments. For a function with a fixed maximum ++number of arguments, declare a C argument for each Lisp argument, and ++give them all type @code{Lisp_Object}. When a Lisp function has no ++upper limit on the number of arguments, its implementation in C actually ++receives exactly two arguments: the first is the number of Lisp ++arguments, and the second is the address of a block containing their ++values. They have types @code{int} and @w{@code{Lisp_Object *}}. ++ ++@cindex @code{GCPRO} and @code{UNGCPRO} ++@cindex protect C variables from garbage collection ++ Within the function @code{For} itself, note the use of the macros ++@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ++``protect'' a variable from garbage collection---to inform the garbage ++collector that it must look in that variable and regard its contents ++as an accessible object. GC protection is necessary whenever you call ++@code{Feval} or anything that can directly or indirectly call ++@code{Feval}. At such a time, any Lisp object that this function may ++refer to again must be protected somehow. ++ ++ It suffices to ensure that at least one pointer to each object is ++GC-protected; that way, the object cannot be recycled, so all pointers ++to it remain valid. Thus, a particular local variable can do without ++protection if it is certain that the object it points to will be ++preserved by some other pointer (such as another local variable which ++has a @code{GCPRO})@footnote{Formerly, strings were a special ++exception; in older Emacs versions, every local variable that might ++point to a string needed a @code{GCPRO}.}. Otherwise, the local ++variable needs a @code{GCPRO}. ++ ++ The macro @code{GCPRO1} protects just one local variable. If you ++want to protect two variables, use @code{GCPRO2} instead; repeating ++@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4}, ++@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros ++implicitly use local variables such as @code{gcpro1}; you must declare ++these explicitly, with type @code{struct gcpro}. Thus, if you use ++@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. ++Alas, we can't explain all the tricky details here. ++ ++ @code{UNGCPRO} cancels the protection of the variables that are ++protected in the current function. It is necessary to do this ++explicitly. ++ ++ Built-in functions that take a variable number of arguments actually ++accept two arguments at the C level: the number of Lisp arguments, and ++a @code{Lisp_Object *} pointer to a C vector containing those Lisp ++arguments. This C vector may be part of a Lisp vector, but it need ++not be. The responsibility for using @code{GCPRO} to protect the Lisp ++arguments from GC if necessary rests with the caller in this case, ++since the caller allocated or found the storage for them. ++ ++ You must not use C initializers for static or global variables unless ++the variables are never written once Emacs is dumped. These variables ++with initializers are allocated in an area of memory that becomes ++read-only (on certain operating systems) as a result of dumping Emacs. ++@xref{Pure Storage}. ++ ++ Do not use static variables within functions---place all static ++variables at top level in the file. This is necessary because Emacs on ++some operating systems defines the keyword @code{static} as a null ++macro. (This definition is used because those systems put all variables ++declared static in a place that becomes read-only after dumping, whether ++they have initializers or not.) ++ ++@cindex @code{defsubr}, Lisp symbol for a primitive ++ Defining the C function is not enough to make a Lisp primitive ++available; you must also create the Lisp symbol for the primitive and ++store a suitable subr object in its function cell. The code looks like ++this: ++ ++@example ++defsubr (&@var{subr-structure-name}); ++@end example ++ ++@noindent ++Here @var{subr-structure-name} is the name you used as the third ++argument to @code{DEFUN}. ++ ++ If you add a new primitive to a file that already has Lisp primitives ++defined in it, find the function (near the end of the file) named ++@code{syms_of_@var{something}}, and add the call to @code{defsubr} ++there. If the file doesn't have this function, or if you create a new ++file, add to it a @code{syms_of_@var{filename}} (e.g., ++@code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all ++of these functions are called, and add a call to ++@code{syms_of_@var{filename}} there. ++ ++@anchor{Defining Lisp variables in C} ++@vindex byte-boolean-vars ++@cindex defining Lisp variables in C ++@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL} ++ The function @code{syms_of_@var{filename}} is also the place to define ++any C variables that are to be visible as Lisp variables. ++@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible ++in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int} ++visible in Lisp with a value that is always an integer. ++@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp ++with a value that is either @code{t} or @code{nil}. Note that variables ++defined with @code{DEFVAR_BOOL} are automatically added to the list ++@code{byte-boolean-vars} used by the byte compiler. ++ ++@cindex @code{staticpro}, protection from GC ++ If you define a file-scope C variable of type @code{Lisp_Object}, ++you must protect it from garbage-collection by calling @code{staticpro} ++in @code{syms_of_@var{filename}}, like this: ++ ++@example ++staticpro (&@var{variable}); ++@end example ++ ++ Here is another example function, with more complicated arguments. ++This comes from the code in @file{window.c}, and it demonstrates the use ++of macros and functions to manipulate Lisp objects. ++ ++@smallexample ++@group ++DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, ++ Scoordinates_in_window_p, 2, 2, ++ "xSpecify coordinate pair: \nXExpression which evals to window: ", ++ "Return non-nil if COORDINATES is in WINDOW.\n\ ++COORDINATES is a cons of the form (X . Y), X and Y being distances\n\ ++... ++@end group ++@group ++If they are on the border between WINDOW and its right sibling,\n\ ++ `vertical-line' is returned.") ++ (coordinates, window) ++ register Lisp_Object coordinates, window; ++@{ ++ int x, y; ++@end group ++ ++@group ++ CHECK_LIVE_WINDOW (window, 0); ++ CHECK_CONS (coordinates, 1); ++ x = XINT (Fcar (coordinates)); ++ y = XINT (Fcdr (coordinates)); ++@end group ++ ++@group ++ switch (coordinates_in_window (XWINDOW (window), &x, &y)) ++ @{ ++ case 0: /* NOT in window at all. */ ++ return Qnil; ++@end group ++ ++@group ++ case 1: /* In text part of window. */ ++ return Fcons (make_number (x), make_number (y)); ++@end group ++ ++@group ++ case 2: /* In mode line of window. */ ++ return Qmode_line; ++@end group ++ ++@group ++ case 3: /* On right border of window. */ ++ return Qvertical_line; ++@end group ++ ++@group ++ default: ++ abort (); ++ @} ++@} ++@end group ++@end smallexample ++ ++ Note that C code cannot call functions by name unless they are defined ++in C. The way to call a function written in Lisp is to use ++@code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since ++the Lisp function @code{funcall} accepts an unlimited number of ++arguments, in C it takes two: the number of Lisp-level arguments, and a ++one-dimensional array containing their values. The first Lisp-level ++argument is the Lisp function to call, and the rest are the arguments to ++pass to it. Since @code{Ffuncall} can call the evaluator, you must ++protect pointers from garbage collection around the call to ++@code{Ffuncall}. ++ ++ The C functions @code{call0}, @code{call1}, @code{call2}, and so on, ++provide handy ways to call a Lisp function conveniently with a fixed ++number of arguments. They work by calling @code{Ffuncall}. ++ ++ @file{eval.c} is a very good file to look through for examples; ++@file{lisp.h} contains the definitions for some important macros and ++functions. ++ ++ If you define a function which is side-effect free, update the code ++in @file{byte-opt.el} which binds @code{side-effect-free-fns} and ++@code{side-effect-and-error-free-fns} so that the compiler optimizer ++knows about it. ++ ++@node Object Internals ++@appendixsec Object Internals ++@cindex object internals ++ ++ GNU Emacs Lisp manipulates many different types of data. The actual ++data are stored in a heap and the only access that programs have to it ++is through pointers. Each pointer is 32 bits wide on 32-bit machines, ++and 64 bits wide on 64-bit machines; three of these bits are used for ++the tag that identifies the object's type, and the remainder are used ++to address the object. ++ ++ Because Lisp objects are represented as tagged pointers, it is always ++possible to determine the Lisp data type of any object. The C data type ++@code{Lisp_Object} can hold any Lisp object of any data type. Ordinary ++variables have type @code{Lisp_Object}, which means they can hold any ++type of Lisp value; you can determine the actual data type only at run ++time. The same is true for function arguments; if you want a function ++to accept only a certain type of argument, you must check the type ++explicitly using a suitable predicate (@pxref{Type Predicates}). ++@cindex type checking internals ++ ++@menu ++* Buffer Internals:: Components of a buffer structure. ++* Window Internals:: Components of a window structure. ++* Process Internals:: Components of a process structure. ++@end menu ++ ++@node Buffer Internals ++@appendixsubsec Buffer Internals ++@cindex internals, of buffer ++@cindex buffer internals ++ ++ Two structures are used to represent buffers in C. The ++@code{buffer_text} structure contains fields describing the text of a ++buffer; the @code{buffer} structure holds other fields. In the case ++of indirect buffers, two or more @code{buffer} structures reference ++the same @code{buffer_text} structure. ++ ++Here are some of the fields in @code{struct buffer_text}: ++ ++@table @code ++@item beg ++The address of the buffer contents. ++ ++@item gpt ++@itemx gpt_byte ++The character and byte positions of the buffer gap. @xref{Buffer ++Gap}. ++ ++@item z ++@itemx z_byte ++The character and byte positions of the end of the buffer text. ++ ++@item gap_size ++The size of buffer's gap. @xref{Buffer Gap}. ++ ++@item modiff ++@itemx save_modiff ++@itemx chars_modiff ++@itemx overlay_modiff ++These fields count the number of buffer-modification events performed ++in this buffer. @code{modiff} is incremented after each ++buffer-modification event, and is never otherwise changed; ++@code{save_modiff} contains the value of @code{modiff} the last time ++the buffer was visited or saved; @code{chars_modiff} counts only ++modifications to the characters in the buffer, ignoring all other ++kinds of changes; and @code{overlay_modiff} counts only modifications ++to the overlays. ++ ++@item beg_unchanged ++@itemx end_unchanged ++The number of characters at the start and end of the text that are ++known to be unchanged since the last complete redisplay. ++ ++@item unchanged_modified ++@itemx overlay_unchanged_modified ++The values of @code{modiff} and @code{overlay_modiff}, respectively, ++after the last compelete redisplay. If their current values match ++@code{modiff} or @code{overlay_modiff}, that means ++@code{beg_unchanged} and @code{end_unchanged} contain no useful ++information. ++ ++@item markers ++The markers that refer to this buffer. This is actually a single ++marker, and successive elements in its marker @code{chain} are the other ++markers referring to this buffer text. ++ ++@item intervals ++The interval tree which records the text properties of this buffer. ++@end table ++ ++Some of the fields of @code{struct buffer} are: ++ ++@table @code ++@item next ++Points to the next buffer, in the chain of all buffers (including ++killed buffers). This chain is used only for garbage collection, in ++order to collect killed buffers properly. Note that vectors, and most ++kinds of objects allocated as vectors, are all on one chain, but ++buffers are on a separate chain of their own. ++ ++@item own_text ++A @code{struct buffer_text} structure that ordinarily holds the buffer ++contents. In indirect buffers, this field is not used. ++ ++@item text ++A pointer to the @code{buffer_text} structure for this buffer. In an ++ordinary buffer, this is the @code{own_text} field above. In an ++indirect buffer, this is the @code{own_text} field of the base buffer. ++ ++@item pt ++@itemx pt_byte ++The character and byte positions of point in a buffer. ++ ++@item begv ++@itemx begv_byte ++The character and byte positions of the beginning of the accessible ++range of text in the buffer. ++ ++@item zv ++@itemx zv_byte ++The character and byte positions of the end of the accessible range of ++text in the buffer. ++ ++@item base_buffer ++In an indirect buffer, this points to the base buffer. In an ordinary ++buffer, it is null. ++ ++@item local_flags ++This field contains flags indicating that certain variables are local ++in this buffer. Such variables are declared in the C code using ++@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored ++in fields in the buffer structure itself. (Some of these fields are ++described in this table.) ++ ++@item modtime ++The modification time of the visited file. It is set when the file is ++written or read. Before writing the buffer into a file, this field is ++compared to the modification time of the file to see if the file has ++changed on disk. @xref{Buffer Modification}. ++ ++@item auto_save_modified ++The time when the buffer was last auto-saved. ++ ++@item last_window_start ++The @code{window-start} position in the buffer as of the last time the ++buffer was displayed in a window. ++ ++@item clip_changed ++This flag indicates that narrowing has changed in the buffer. ++@xref{Narrowing}. ++ ++@item prevent_redisplay_optimizations_p ++This flag indicates that redisplay optimizations should not be used to ++display this buffer. ++ ++@item overlay_center ++This field holds the current overlay center position. @xref{Managing ++Overlays}. ++ ++@item overlays_before ++@itemx overlays_after ++These fields hold, respectively, a list of overlays that end at or ++before the current overlay center, and a list of overlays that end ++after the current overlay center. @xref{Managing Overlays}. ++@code{overlays_before} is sorted in order of decreasing end position, ++and @code{overlays_after} is sorted in order of increasing beginning ++position. ++ ++@item name ++A Lisp string that names the buffer. It is guaranteed to be unique. ++@xref{Buffer Names}. ++ ++@item save_length ++The length of the file this buffer is visiting, when last read or ++saved. This and other fields concerned with saving are not kept in ++the @code{buffer_text} structure because indirect buffers are never ++saved. ++ ++@item directory ++The directory for expanding relative file names. This is the value of ++the buffer-local variable @code{default-directory} (@pxref{File Name Expansion}). ++ ++@item filename ++The name of the file visited in this buffer, or @code{nil}. This is ++the value of the buffer-local variable @code{buffer-file-name} ++(@pxref{Buffer File Name}). ++ ++@item undo_list ++@itemx backed_up ++@itemx auto_save_file_name ++@itemx read_only ++@itemx file_format ++@itemx file_truename ++@itemx invisibility_spec ++@itemx display_count ++@itemx display_time ++These fields store the values of Lisp variables that are automatically ++buffer-local (@pxref{Buffer-Local Variables}), whose corresponding ++variable names have the additional prefix @code{buffer-} and have ++underscores replaced with dashes. For instance, @code{undo_list} ++stores the value of @code{buffer-undo-list}. @xref{Standard ++Buffer-Local Variables}. ++ ++@item mark ++The mark for the buffer. The mark is a marker, hence it is also ++included on the list @code{markers}. @xref{The Mark}. ++ ++@item local_var_alist ++The association list describing the buffer-local variable bindings of ++this buffer, not including the built-in buffer-local bindings that ++have special slots in the buffer object. (Those slots are omitted ++from this table.) @xref{Buffer-Local Variables}. ++ ++@item major_mode ++Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}. ++ ++@item mode_name ++Pretty name of the major mode, e.g., @code{"Lisp"}. ++ ++@item keymap ++@itemx abbrev_table ++@itemx syntax_table ++@itemx category_table ++@itemx display_table ++These fields store the buffer's local keymap (@pxref{Keymaps}), abbrev ++table (@pxref{Abbrev Tables}), syntax table (@pxref{Syntax Tables}), ++category table (@pxref{Categories}), and display table (@pxref{Display ++Tables}). ++ ++@item downcase_table ++@itemx upcase_table ++@itemx case_canon_table ++These fields store the conversion tables for converting text to lower ++case, upper case, and for canonicalizing text for case-fold search. ++@xref{Case Tables}. ++ ++@item minor_modes ++An alist of the minor modes of this buffer. ++ ++@item pt_marker ++@itemx begv_marker ++@itemx zv_marker ++These fields are only used in an indirect buffer, or in a buffer that ++is the base of an indirect buffer. Each holds a marker that records ++@code{pt}, @code{begv}, and @code{zv} respectively, for this buffer ++when the buffer is not current. ++ ++@item mode_line_format ++@itemx header_line_format ++@itemx case_fold_search ++@itemx tab_width ++@itemx fill_column ++@itemx left_margin ++@itemx auto_fill_function ++@itemx truncate_lines ++@itemx word_wrap ++@itemx ctl_arrow ++@itemx selective_display ++@itemx selective_display_ellipses ++@itemx overwrite_mode ++@itemx abbrev_mode ++@itemx display_table ++@itemx mark_active ++@itemx enable_multibyte_characters ++@itemx buffer_file_coding_system ++@itemx auto_save_file_format ++@itemx cache_long_line_scans ++@itemx point_before_scroll ++@itemx left_fringe_width ++@itemx right_fringe_width ++@itemx fringes_outside_margins ++@itemx scroll_bar_width ++@itemx indicate_empty_lines ++@itemx indicate_buffer_boundaries ++@itemx fringe_indicator_alist ++@itemx fringe_cursor_alist ++@itemx scroll_up_aggressively ++@itemx scroll_down_aggressively ++@itemx cursor_type ++@itemx cursor_in_non_selected_windows ++These fields store the values of Lisp variables that are automatically ++buffer-local (@pxref{Buffer-Local Variables}), whose corresponding ++variable names have underscores replaced with dashes. For instance, ++@code{mode_line_format} stores the value of @code{mode-line-format}. ++@xref{Standard Buffer-Local Variables}. ++ ++@item last_selected_window ++This is the last window that was selected with this buffer in it, or @code{nil} ++if that window no longer displays this buffer. ++@end table ++ ++@node Window Internals ++@appendixsubsec Window Internals ++@cindex internals, of window ++@cindex window internals ++ ++ Windows have the following accessible fields: ++ ++@table @code ++@item frame ++The frame that this window is on. ++ ++@item mini_p ++Non-@code{nil} if this window is a minibuffer window. ++ ++@item parent ++Internally, Emacs arranges windows in a tree; each group of siblings has ++a parent window whose area includes all the siblings. This field points ++to a window's parent. ++ ++Parent windows do not display buffers, and play little role in display ++except to shape their child windows. Emacs Lisp programs usually have ++no access to the parent windows; they operate on the windows at the ++leaves of the tree, which actually display buffers. ++ ++@item hchild ++@itemx vchild ++These fields contain the window's leftmost child and its topmost child ++respectively. @code{hchild} is used if the window is subdivided ++horizontally by child windows, and @code{vchild} if it is subdivided ++vertically. ++ ++@item next ++@itemx prev ++The next sibling and previous sibling of this window. @code{next} is ++@code{nil} if the window is the rightmost or bottommost in its group; ++@code{prev} is @code{nil} if it is the leftmost or topmost in its ++group. ++ ++@item left_col ++The left-hand edge of the window, measured in columns, relative to the ++leftmost column in the frame (column 0). ++ ++@item top_line ++The top edge of the window, measured in lines, relative to the topmost ++line in the frame (line 0). ++ ++@item total_cols ++@itemx total_lines ++The width and height of the window, measured in columns and lines ++respectively. The width includes the scroll bar and fringes, and/or ++the separator line on the right of the window (if any). ++ ++@item buffer ++The buffer that the window is displaying. ++ ++@item start ++A marker pointing to the position in the buffer that is the first ++character displayed in the window. ++ ++@item pointm ++@cindex window point internals ++This is the value of point in the current buffer when this window is ++selected; when it is not selected, it retains its previous value. ++ ++@item force_start ++If this flag is non-@code{nil}, it says that the window has been ++scrolled explicitly by the Lisp program. This affects what the next ++redisplay does if point is off the screen: instead of scrolling the ++window to show the text around point, it moves point to a location that ++is on the screen. ++ ++@item frozen_window_start_p ++This field is set temporarily to 1 to indicate to redisplay that ++@code{start} of this window should not be changed, even if point ++gets invisible. ++ ++@item start_at_line_beg ++Non-@code{nil} means current value of @code{start} was the beginning of a line ++when it was chosen. ++ ++@item use_time ++This is the last time that the window was selected. The function ++@code{get-lru-window} uses this field. ++ ++@item sequence_number ++A unique number assigned to this window when it was created. ++ ++@item last_modified ++The @code{modiff} field of the window's buffer, as of the last time ++a redisplay completed in this window. ++ ++@item last_overlay_modified ++The @code{overlay_modiff} field of the window's buffer, as of the last ++time a redisplay completed in this window. ++ ++@item last_point ++The buffer's value of point, as of the last time a redisplay completed ++in this window. ++ ++@item last_had_star ++A non-@code{nil} value means the window's buffer was ``modified'' when the ++window was last updated. ++ ++@item vertical_scroll_bar ++This window's vertical scroll bar. ++ ++@item left_margin_width ++@itemx right_margin_width ++The widths of the left and right margins in this window. A value of ++@code{nil} means to use the buffer's value of @code{left-margin-width} ++or @code{right-margin-width}. ++ ++@item window_end_pos ++This is computed as @code{z} minus the buffer position of the last glyph ++in the current matrix of the window. The value is only valid if ++@code{window_end_valid} is not @code{nil}. ++ ++@item window_end_bytepos ++The byte position corresponding to @code{window_end_pos}. ++ ++@item window_end_vpos ++The window-relative vertical position of the line containing ++@code{window_end_pos}. ++ ++@item window_end_valid ++This field is set to a non-@code{nil} value if @code{window_end_pos} is truly ++valid. This is @code{nil} if nontrivial redisplay is preempted since in that ++case the display that @code{window_end_pos} was computed for did not get ++onto the screen. ++ ++@item cursor ++A structure describing where the cursor is in this window. ++ ++@item last_cursor ++The value of @code{cursor} as of the last redisplay that finished. ++ ++@item phys_cursor ++A structure describing where the cursor of this window physically is. ++ ++@item phys_cursor_type ++The type of cursor that was last displayed on this window. ++ ++@item phys_cursor_on_p ++This field is non-zero if the cursor is physically on. ++ ++@item cursor_off_p ++Non-zero means the cursor in this window is logically on. ++ ++@item last_cursor_off_p ++This field contains the value of @code{cursor_off_p} as of the time of ++the last redisplay. ++ ++@item must_be_updated_p ++This is set to 1 during redisplay when this window must be updated. ++ ++@item hscroll ++This is the number of columns that the display in the window is scrolled ++horizontally to the left. Normally, this is 0. ++ ++@item vscroll ++Vertical scroll amount, in pixels. Normally, this is 0. ++ ++@item dedicated ++Non-@code{nil} if this window is dedicated to its buffer. ++ ++@item display_table ++The window's display table, or @code{nil} if none is specified for it. ++ ++@item update_mode_line ++Non-@code{nil} means this window's mode line needs to be updated. ++ ++@item base_line_number ++The line number of a certain position in the buffer, or @code{nil}. ++This is used for displaying the line number of point in the mode line. ++ ++@item base_line_pos ++The position in the buffer for which the line number is known, or ++@code{nil} meaning none is known. ++ ++@item region_showing ++If the region (or part of it) is highlighted in this window, this field ++holds the mark position that made one end of that region. Otherwise, ++this field is @code{nil}. ++ ++@item column_number_displayed ++The column number currently displayed in this window's mode line, or @code{nil} ++if column numbers are not being displayed. ++ ++@item current_matrix ++A glyph matrix describing the current display of this window. ++ ++@item desired_matrix ++A glyph matrix describing the desired display of this window. ++@end table ++ ++@node Process Internals ++@appendixsubsec Process Internals ++@cindex internals, of process ++@cindex process internals ++ ++ The fields of a process are: ++ ++@table @code ++@item name ++A string, the name of the process. ++ ++@item command ++A list containing the command arguments that were used to start this ++process. For a network or serial process, it is @code{nil} if the ++process is running or @code{t} if the process is stopped. ++ ++@item filter ++A function used to accept output from the process instead of a buffer, ++or @code{nil}. ++ ++@item sentinel ++A function called whenever the process receives a signal, or @code{nil}. ++ ++@item buffer ++The associated buffer of the process. ++ ++@item pid ++An integer, the operating system's process @acronym{ID}. ++ ++@item childp ++A flag, non-@code{nil} if this is really a child process. ++It is @code{nil} for a network or serial connection. ++ ++@item mark ++A marker indicating the position of the end of the last output from this ++process inserted into the buffer. This is often but not always the end ++of the buffer. ++ ++@item kill_without_query ++If this is non-zero, killing Emacs while this process is still running ++does not ask for confirmation about killing the process. ++ ++@item raw_status_low ++@itemx raw_status_high ++These two fields record 16 bits each of the process status returned by ++the @code{wait} system call. ++ ++@item status ++The process status, as @code{process-status} should return it. ++ ++@item tick ++@itemx update_tick ++If these two fields are not equal, a change in the status of the process ++needs to be reported, either by running the sentinel or by inserting a ++message in the process buffer. ++ ++@item pty_flag ++Non-@code{nil} if communication with the subprocess uses a @acronym{PTY}; ++@code{nil} if it uses a pipe. ++ ++@item infd ++The file descriptor for input from the process. ++ ++@item outfd ++The file descriptor for output to the process. ++ ++@item subtty ++The file descriptor for the terminal that the subprocess is using. (On ++some systems, there is no need to record this, so the value is ++@code{nil}.) ++ ++@item tty_name ++The name of the terminal that the subprocess is using, ++or @code{nil} if it is using pipes. ++ ++@item decode_coding_system ++Coding-system for decoding the input from this process. ++ ++@item decoding_buf ++A working buffer for decoding. ++ ++@item decoding_carryover ++Size of carryover in decoding. ++ ++@item encode_coding_system ++Coding-system for encoding the output to this process. ++ ++@item encoding_buf ++A working buffer for encoding. ++ ++@item encoding_carryover ++Size of carryover in encoding. ++ ++@item inherit_coding_system_flag ++Flag to set @code{coding-system} of the process buffer from the ++coding system used to decode process output. ++ ++@item type ++Symbol indicating the type of process: @code{real}, @code{network}, ++@code{serial} ++ ++@end table ++ ++@ignore ++ arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e ++@end ignore +diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi +new file mode 100644 +index 0000000..86ec6eb +--- /dev/null ++++ b/doc/lispref/intro.texi +@@ -0,0 +1,552 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/intro ++ ++@node Introduction, Lisp Data Types, Top, Top ++@comment node-name, next, previous, up ++@chapter Introduction ++ ++ Most of the GNU Emacs text editor is written in the programming ++language called Emacs Lisp. You can write new code in Emacs Lisp and ++install it as an extension to the editor. However, Emacs Lisp is more ++than a mere ``extension language''; it is a full computer programming ++language in its own right. You can use it as you would any other ++programming language. ++ ++ Because Emacs Lisp is designed for use in an editor, it has special ++features for scanning and parsing text as well as features for handling ++files, buffers, displays, subprocesses, and so on. Emacs Lisp is ++closely integrated with the editing facilities; thus, editing commands ++are functions that can also conveniently be called from Lisp programs, ++and parameters for customization are ordinary Lisp variables. ++ ++ This manual attempts to be a full description of Emacs Lisp. For a ++beginner's introduction to Emacs Lisp, see @cite{An Introduction to ++Emacs Lisp Programming}, by Bob Chassell, also published by the Free ++Software Foundation. This manual presumes considerable familiarity with ++the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this ++basic information. ++ ++ Generally speaking, the earlier chapters describe features of Emacs ++Lisp that have counterparts in many programming languages, and later ++chapters describe features that are peculiar to Emacs Lisp or relate ++specifically to editing. ++ ++ This is edition @value{VERSION} of the GNU Emacs Lisp Reference ++Manual, corresponding to Emacs version @value{EMACSVER}. ++ ++@menu ++* Caveats:: Flaws and a request for help. ++* Lisp History:: Emacs Lisp is descended from Maclisp. ++* Conventions:: How the manual is formatted. ++* Version Info:: Which Emacs version is running? ++* Acknowledgements:: The authors, editors, and sponsors of this manual. ++@end menu ++ ++@node Caveats ++@section Caveats ++@cindex bugs in this manual ++ ++ This manual has gone through numerous drafts. It is nearly complete ++but not flawless. There are a few topics that are not covered, either ++because we consider them secondary (such as most of the individual ++modes) or because they are yet to be written. Because we are not able ++to deal with them completely, we have left out several parts ++intentionally. ++ ++ The manual should be fully correct in what it does cover, and it is ++therefore open to criticism on anything it says---from specific examples ++and descriptive text, to the ordering of chapters and sections. If ++something is confusing, or you find that you have to look at the sources ++or experiment to learn something not covered in the manual, then perhaps ++the manual should be fixed. Please let us know. ++ ++@iftex ++ As you use this manual, we ask that you mark pages with corrections so ++you can later look them up and send them to us. If you think of a simple, ++real-life example for a function or group of functions, please make an ++effort to write it up and send it in. Please reference any comments to ++the chapter name, section name, and function name, as appropriate, since ++page numbers and chapter and section numbers will change and we may have ++trouble finding the text you are talking about. Also state the number ++of the edition you are criticizing. ++@end iftex ++@ifnottex ++ ++As you use this manual, we ask that you send corrections as soon as you ++find them. If you think of a simple, real life example for a function ++or group of functions, please make an effort to write it up and send it ++in. Please reference any comments to the node name and function or ++variable name, as appropriate. Also state the number of the edition ++you are criticizing. ++@end ifnottex ++ ++@cindex bugs ++@cindex suggestions ++Please send comments and corrections using @kbd{M-x report-emacs-bug}. ++ ++@node Lisp History ++@section Lisp History ++@cindex Lisp history ++ ++ Lisp (LISt Processing language) was first developed in the late 1950s ++at the Massachusetts Institute of Technology for research in artificial ++intelligence. The great power of the Lisp language makes it ideal ++for other purposes as well, such as writing editing commands. ++ ++@cindex Maclisp ++@cindex Common Lisp ++ Dozens of Lisp implementations have been built over the years, each ++with its own idiosyncrasies. Many of them were inspired by Maclisp, ++which was written in the 1960s at MIT's Project MAC. Eventually the ++implementors of the descendants of Maclisp came together and developed a ++standard for Lisp systems, called Common Lisp. In the meantime, Gerry ++Sussman and Guy Steele at MIT developed a simplified but very powerful ++dialect of Lisp, called Scheme. ++ ++ GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common ++Lisp. If you know Common Lisp, you will notice many similarities. ++However, many features of Common Lisp have been omitted or ++simplified in order to reduce the memory requirements of GNU Emacs. ++Sometimes the simplifications are so drastic that a Common Lisp user ++might be very confused. We will occasionally point out how GNU Emacs ++Lisp differs from Common Lisp. If you don't know Common Lisp, don't ++worry about it; this manual is self-contained. ++ ++@pindex cl ++ A certain amount of Common Lisp emulation is available via the ++@file{cl} library. @inforef{Top, Overview, cl}. ++ ++ Emacs Lisp is not at all influenced by Scheme; but the GNU project has ++an implementation of Scheme, called Guile. We use Guile in all new GNU ++software that calls for extensibility. ++ ++@node Conventions ++@section Conventions ++ ++This section explains the notational conventions that are used in this ++manual. You may want to skip this section and refer back to it later. ++ ++@menu ++* Some Terms:: Explanation of terms we use in this manual. ++* nil and t:: How the symbols @code{nil} and @code{t} are used. ++* Evaluation Notation:: The format we use for examples of evaluation. ++* Printing Notation:: The format we use when examples print text. ++* Error Messages:: The format we use for examples of errors. ++* Buffer Text Notation:: The format we use for buffer contents in examples. ++* Format of Descriptions:: Notation for describing functions, variables, etc. ++@end menu ++ ++@node Some Terms ++@subsection Some Terms ++ ++ Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp ++printer'' refer to those routines in Lisp that convert textual ++representations of Lisp objects into actual Lisp objects, and vice ++versa. @xref{Printed Representation}, for more details. You, the ++person reading this manual, are thought of as ``the programmer'' and are ++addressed as ``you.'' ``The user'' is the person who uses Lisp ++programs, including those you write. ++ ++@cindex typographic conventions ++ Examples of Lisp code are formatted like this: @code{(list 1 2 3)}. ++Names that represent metasyntactic variables, or arguments to a function ++being described, are formatted like this: @var{first-number}. ++ ++@node nil and t ++@subsection @code{nil} and @code{t} ++@cindex truth value ++@cindex boolean ++ ++@cindex @code{nil} ++@cindex false ++ In Lisp, the symbol @code{nil} has three separate meanings: it ++is a symbol with the name @samp{nil}; it is the logical truth value ++@var{false}; and it is the empty list---the list of zero elements. ++When used as a variable, @code{nil} always has the value @code{nil}. ++ ++ As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are ++identical: they stand for the same object, the symbol @code{nil}. The ++different ways of writing the symbol are intended entirely for human ++readers. After the Lisp reader has read either @samp{()} or @samp{nil}, ++there is no way to determine which representation was actually written ++by the programmer. ++ ++ In this manual, we write @code{()} when we wish to emphasize that it ++means the empty list, and we write @code{nil} when we wish to emphasize ++that it means the truth value @var{false}. That is a good convention to use ++in Lisp programs also. ++ ++@example ++(cons 'foo ()) ; @r{Emphasize the empty list} ++(setq foo-flag nil) ; @r{Emphasize the truth value @var{false}} ++@end example ++ ++@cindex @code{t} ++@cindex true ++ In contexts where a truth value is expected, any non-@code{nil} value ++is considered to be @var{true}. However, @code{t} is the preferred way ++to represent the truth value @var{true}. When you need to choose a ++value which represents @var{true}, and there is no other basis for ++choosing, use @code{t}. The symbol @code{t} always has the value ++@code{t}. ++ ++ In Emacs Lisp, @code{nil} and @code{t} are special symbols that always ++evaluate to themselves. This is so that you do not need to quote them ++to use them as constants in a program. An attempt to change their ++values results in a @code{setting-constant} error. @xref{Constant ++Variables}. ++ ++@defun booleanp object ++Return non-@code{nil} if @var{object} is one of the two canonical ++boolean values: @code{t} or @code{nil}. ++@end defun ++ ++@node Evaluation Notation ++@subsection Evaluation Notation ++@cindex evaluation notation ++@cindex documentation notation ++@cindex notation ++ ++ A Lisp expression that you can evaluate is called a @dfn{form}. ++Evaluating a form always produces a result, which is a Lisp object. In ++the examples in this manual, this is indicated with @samp{@result{}}: ++ ++@example ++(car '(1 2)) ++ @result{} 1 ++@end example ++ ++@noindent ++You can read this as ``@code{(car '(1 2))} evaluates to 1.'' ++ ++ When a form is a macro call, it expands into a new form for Lisp to ++evaluate. We show the result of the expansion with ++@samp{@expansion{}}. We may or may not show the result of the ++evaluation of the expanded form. ++ ++@example ++(third '(a b c)) ++ @expansion{} (car (cdr (cdr '(a b c)))) ++ @result{} c ++@end example ++ ++ Sometimes to help describe one form we show another form that ++produces identical results. The exact equivalence of two forms is ++indicated with @samp{@equiv{}}. ++ ++@example ++(make-sparse-keymap) @equiv{} (list 'keymap) ++@end example ++ ++@node Printing Notation ++@subsection Printing Notation ++@cindex printing notation ++ ++ Many of the examples in this manual print text when they are ++evaluated. If you execute example code in a Lisp Interaction buffer ++(such as the buffer @samp{*scratch*}), the printed text is inserted into ++the buffer. If you execute the example by other means (such as by ++evaluating the function @code{eval-region}), the printed text is ++displayed in the echo area. ++ ++ Examples in this manual indicate printed text with @samp{@print{}}, ++irrespective of where that text goes. The value returned by ++evaluating the form (here @code{bar}) follows on a separate line with ++@samp{@result{}}. ++ ++@example ++@group ++(progn (prin1 'foo) (princ "\n") (prin1 'bar)) ++ @print{} foo ++ @print{} bar ++ @result{} bar ++@end group ++@end example ++ ++@node Error Messages ++@subsection Error Messages ++@cindex error message notation ++ ++ Some examples signal errors. This normally displays an error message ++in the echo area. We show the error message on a line starting with ++@samp{@error{}}. Note that @samp{@error{}} itself does not appear in ++the echo area. ++ ++@example ++(+ 23 'x) ++@error{} Wrong type argument: number-or-marker-p, x ++@end example ++ ++@node Buffer Text Notation ++@subsection Buffer Text Notation ++@cindex buffer text notation ++ ++ Some examples describe modifications to the contents of a buffer, by ++showing the ``before'' and ``after'' versions of the text. These ++examples show the contents of the buffer in question between two lines ++of dashes containing the buffer name. In addition, @samp{@point{}} ++indicates the location of point. (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 currently located.) ++ ++@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 ++ ++@node Format of Descriptions ++@subsection Format of Descriptions ++@cindex description format ++ ++ Functions, variables, macros, commands, user options, and special ++forms are described in this manual in a uniform format. The first ++line of a description contains the name of the item followed by its ++arguments, if any. ++@ifnottex ++The category---function, variable, or whatever---appears at the ++beginning of the line. ++@end ifnottex ++@iftex ++The category---function, variable, or whatever---is printed next to the ++right margin. ++@end iftex ++The description follows on succeeding lines, sometimes with examples. ++ ++@menu ++* A Sample Function Description:: A description of an imaginary ++ function, @code{foo}. ++* A Sample Variable Description:: A description of an imaginary ++ variable, ++ @code{electric-future-map}. ++@end menu ++ ++@node A Sample Function Description ++@subsubsection A Sample Function Description ++@cindex function descriptions ++@cindex command descriptions ++@cindex macro descriptions ++@cindex special form descriptions ++ ++ In a function description, the name of the function being described ++appears first. It is followed on the same line by a list of argument ++names. These names are also used in the body of the description, to ++stand for the values of the arguments. ++ ++ The appearance of the keyword @code{&optional} in the argument list ++indicates that the subsequent arguments may be omitted (omitted ++arguments default to @code{nil}). Do not write @code{&optional} when ++you call the function. ++ ++ The keyword @code{&rest} (which must be followed by a single ++argument name) indicates that any number of arguments can follow. The ++single argument name following @code{&rest} will receive, as its ++value, a list of all the remaining arguments passed to the function. ++Do not write @code{&rest} when you call the function. ++ ++ Here is a description of an imaginary function @code{foo}: ++ ++@defun foo integer1 &optional integer2 &rest integers ++The function @code{foo} subtracts @var{integer1} from @var{integer2}, ++then adds all the rest of the arguments to the result. If @var{integer2} ++is not supplied, then the number 19 is used by default. ++ ++@example ++(foo 1 5 3 9) ++ @result{} 16 ++(foo 5) ++ @result{} 14 ++@end example ++ ++@need 1500 ++More generally, ++ ++@example ++(foo @var{w} @var{x} @var{y}@dots{}) ++@equiv{} ++(+ (- @var{x} @var{w}) @var{y}@dots{}) ++@end example ++@end defun ++ ++ Any argument whose name contains the name of a type (e.g., ++@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that ++type. A plural of a type (such as @var{buffers}) often means a list of ++objects of that type. Arguments named @var{object} may be of any type. ++(@xref{Lisp Data Types}, for a list of Emacs object types.) Arguments ++with other sorts of names (e.g., @var{new-file}) are discussed ++specifically in the description of the function. In some sections, ++features common to the arguments of several functions are described at ++the beginning. ++ ++ @xref{Lambda Expressions}, for a more complete description of optional ++and rest arguments. ++ ++ Command, macro, and special form descriptions have the same format, ++but the word `Function' is replaced by `Command', `Macro', or `Special ++Form', respectively. Commands are simply functions that may be called ++interactively; macros process their arguments differently from functions ++(the arguments are not evaluated), but are presented the same way. ++ ++ Special form descriptions use a more complex notation to specify ++optional and repeated arguments because they can break the argument ++list down into separate arguments in more complicated ways. ++@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is ++optional and @samp{@var{repeated-args}@dots{}} stands for zero or more ++arguments. Parentheses are used when several arguments are grouped into ++additional levels of list structure. Here is an example: ++ ++@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} ++This imaginary special form implements a loop that executes the ++@var{body} forms and then increments the variable @var{var} on each ++iteration. On the first iteration, the variable has the value ++@var{from}; on subsequent iterations, it is incremented by one (or by ++@var{inc} if that is given). The loop exits before executing @var{body} ++if @var{var} equals @var{to}. Here is an example: ++ ++@example ++(count-loop (i 0 10) ++ (prin1 i) (princ " ") ++ (prin1 (aref vector i)) ++ (terpri)) ++@end example ++ ++If @var{from} and @var{to} are omitted, @var{var} is bound to ++@code{nil} before the loop begins, and the loop exits if @var{var} is ++non-@code{nil} at the beginning of an iteration. Here is an example: ++ ++@example ++(count-loop (done) ++ (if (pending) ++ (fixit) ++ (setq done t))) ++@end example ++ ++In this special form, 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. ++@end defspec ++ ++@node A Sample Variable Description ++@subsubsection A Sample Variable Description ++@cindex variable descriptions ++@cindex option descriptions ++ ++ A @dfn{variable} is a name that can hold a value. Although nearly ++all variables can be set by the user, certain variables exist ++specifically so that users can change them; these are called @dfn{user ++options}. Ordinary variables and user options are described using a ++format like that for functions except that there are no arguments. ++ ++ Here is a description of the imaginary @code{electric-future-map} ++variable.@refill ++ ++@defvar electric-future-map ++The value of this variable is a full keymap used by Electric Command ++Future mode. The functions in this map allow you to edit commands you ++have not yet thought about executing. ++@end defvar ++ ++ User option descriptions have the same format, but `Variable' is ++replaced by `User Option'. ++ ++@node Version Info ++@section Version Information ++ ++ These facilities provide information about which version of Emacs is ++in use. ++ ++@deffn Command emacs-version &optional here ++This function returns a string describing the version of Emacs that is ++running. It is useful to include this string in bug reports. ++ ++@smallexample ++@group ++(emacs-version) ++ @result{} "GNU Emacs 23.1 (i686-pc-linux-gnu, GTK+ Version 2.14.4) ++ of 2009-06-01 on cyd.mit.edu" ++@end group ++@end smallexample ++ ++If @var{here} is non-@code{nil}, it inserts the text in the buffer ++before point, and returns @code{nil}. When this function is called ++interactively, it prints the same information in the echo area, but ++giving a prefix argument makes @var{here} non-@code{nil}. ++@end deffn ++ ++@defvar emacs-build-time ++The value of this variable indicates the time at which Emacs was built ++at the local site. It is a list of three integers, like the value ++of @code{current-time} (@pxref{Time of Day}). ++ ++@example ++@group ++emacs-build-time ++ @result{} (18846 52016 156039) ++@end group ++@end example ++@end defvar ++ ++@defvar emacs-version ++The value of this variable is the version of Emacs being run. It is a ++string such as @code{"23.1.1"}. The last number in this string is not ++really part of the Emacs release version number; it is incremented ++each time you build Emacs in any given directory. A value with four ++numeric components, such as @code{"22.0.91.1"}, indicates an ++unreleased test version. ++@end defvar ++ ++ The following two variables have existed since Emacs version 19.23: ++ ++@defvar emacs-major-version ++The major version number of Emacs, as an integer. For Emacs version ++23.1, the value is 23. ++@end defvar ++ ++@defvar emacs-minor-version ++The minor version number of Emacs, as an integer. For Emacs version ++23.1, the value is 1. ++@end defvar ++ ++@node Acknowledgements ++@section Acknowledgements ++ ++ This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, ++Richard@tie{}M. Stallman and Chris Welty, the volunteers of the GNU ++manual group, in an effort extending over several years. ++Robert@tie{}J. Chassell helped to review and edit the manual, with the ++support of the Defense Advanced Research Projects Agency, ARPA Order ++6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic, ++Inc. Additional sections were written by Miles Bader, Lars Brinkhoff, ++Chong Yidong, Kenichi Handa, Lute Kamstra, Juri Linkov, Glenn Morris, ++Thien-Thi Nguyen, Dan Nicolaescu, Martin Rudalics, Kim F. Storm, Luc ++Teirlinck, and Eli Zaretskii. ++ ++ Corrections were supplied by Drew Adams, Juanma Barranquero, Karl ++Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David Boyes, Alan ++Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch, David ++A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf Fassel, ++Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, Jesper ++Harder, George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak ++Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, ++K. Richard Magill, Brian Marick, Roland McGrath, Stefan Monnier, Skip ++Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potorti, ++Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Jason Rumney, ++Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill ++Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding, ++Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn. ++ ++@ignore ++ arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa ++@end ignore +diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi +new file mode 100644 +index 0000000..4afe5e5 +--- /dev/null ++++ b/doc/lispref/keymaps.texi +@@ -0,0 +1,2810 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/keymaps ++@node Keymaps, Modes, Command Loop, Top ++@chapter Keymaps ++@cindex keymap ++ ++ The command bindings of input events are recorded in data structures ++called @dfn{keymaps}. Each entry in a keymap associates (or ++@dfn{binds}) an individual event type, either to another keymap or to ++a command. When an event type is bound to a keymap, that keymap is ++used to look up the next input event; this continues until a command ++is found. The whole process is called @dfn{key lookup}. ++ ++@menu ++* Key Sequences:: Key sequences as Lisp objects. ++* Keymap Basics:: Basic concepts of keymaps. ++* Format of Keymaps:: What a keymap looks like as a Lisp object. ++* Creating Keymaps:: Functions to create and copy keymaps. ++* Inheritance and Keymaps:: How one keymap can inherit the bindings ++ of another keymap. ++* Prefix Keys:: Defining a key with a keymap as its definition. ++* Active Keymaps:: How Emacs searches the active keymaps ++ for a key binding. ++* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. ++* Controlling Active Maps:: Each buffer has a local keymap ++ to override the standard (global) bindings. ++ A minor mode can also override them. ++* Key Lookup:: Finding a key's binding in one keymap. ++* Functions for Key Lookup:: How to request key lookup. ++* Changing Key Bindings:: Redefining a key in a keymap. ++* Remapping Commands:: A keymap can translate one command to another. ++* Translation Keymaps:: Keymaps for translating sequences of events. ++* Key Binding Commands:: Interactive interfaces for redefining keys. ++* Scanning Keymaps:: Looking through all keymaps, for printing help. ++* Menu Keymaps:: Defining a menu as a keymap. ++@end menu ++ ++@node Key Sequences ++@section Key Sequences ++@cindex key ++@cindex keystroke ++@cindex key sequence ++ ++ A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one ++or more input events that form a unit. Input events include ++characters, function keys, and mouse actions (@pxref{Input Events}). ++The Emacs Lisp representation for a key sequence is a string or ++vector. Unless otherwise stated, any Emacs Lisp function that accepts ++a key sequence as an argument can handle both representations. ++ ++ In the string representation, alphanumeric characters ordinarily ++stand for themselves; for example, @code{"a"} represents @kbd{a} ++and @code{"2"} represents @kbd{2}. Control character events are ++prefixed by the substring @code{"\C-"}, and meta characters by ++@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}. ++In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events ++are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and ++@code{"\d"} respectively. The string representation of a complete key ++sequence is the concatenation of the string representations of the ++constituent events; thus, @code{"\C-xl"} represents the key sequence ++@kbd{C-x l}. ++ ++ Key sequences containing function keys, mouse button events, or ++non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be ++represented as strings; they have to be represented as vectors. ++ ++ In the vector representation, each element of the vector represents ++an input event, in its Lisp form. @xref{Input Events}. For example, ++the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}. ++ ++ For examples of key sequences written in string and vector ++representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}. ++ ++@defmac kbd keyseq-text ++This macro converts the text @var{keyseq-text} (a string constant) ++into a key sequence (a string or vector constant). The contents of ++@var{keyseq-text} should describe the key sequence using almost the same ++syntax used in this manual. More precisely, it uses the same syntax ++that Edit Macro mode uses for editing keyboard macros (@pxref{Edit ++Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround ++function key names with @samp{<@dots{}>}. ++ ++@example ++(kbd "C-x") @result{} "\C-x" ++(kbd "C-x C-f") @result{} "\C-x\C-f" ++(kbd "C-x 4 C-f") @result{} "\C-x4\C-f" ++(kbd "X") @result{} "X" ++(kbd "RET") @result{} "\^M" ++(kbd "C-c SPC") @result{} "\C-c@ " ++(kbd " SPC") @result{} [f1 32] ++(kbd "C-M-") @result{} [C-M-down] ++@end example ++ ++This macro is not meant for use with arguments that vary---only ++with string constants. ++@end defmac ++ ++@node Keymap Basics ++@section Keymap Basics ++@cindex key binding ++@cindex binding of a key ++@cindex complete key ++@cindex undefined key ++ ++ A keymap is a Lisp data structure that specifies @dfn{key bindings} ++for various key sequences. ++ ++ A single keymap directly specifies definitions for individual ++events. When a key sequence consists of a single event, its binding ++in a keymap is the keymap's definition for that event. The binding of ++a longer key sequence is found by an iterative process: first find the ++definition of the first event (which must itself be a keymap); then ++find the second event's definition in that keymap, and so on until all ++the events in the key sequence have been processed. ++ ++ If the binding of a key sequence is a keymap, we call the key sequence ++a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because ++no more events can be added to it). If the binding is @code{nil}, ++we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c}, ++@kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are ++@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete ++keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more ++details. ++ ++ The rule for finding the binding of a key sequence assumes that the ++intermediate bindings (found for the events before the last) are all ++keymaps; if this is not so, the sequence of events does not form a ++unit---it is not really one key sequence. In other words, removing one ++or more events from the end of any valid key sequence must always yield ++a prefix key. For example, @kbd{C-f C-n} is not a key sequence; ++@kbd{C-f} is not a prefix key, so a longer sequence starting with ++@kbd{C-f} cannot be a key sequence. ++ ++ The set of possible multi-event key sequences depends on the bindings ++for prefix keys; therefore, it can be different for different keymaps, ++and can change when bindings are changed. However, a one-event sequence ++is always a key sequence, because it does not depend on any prefix keys ++for its well-formedness. ++ ++ At any time, several primary keymaps are @dfn{active}---that is, in ++use for finding key bindings. These are the @dfn{global map}, which is ++shared by all buffers; the @dfn{local keymap}, which is usually ++associated with a specific major mode; and zero or more @dfn{minor mode ++keymaps}, which belong to currently enabled minor modes. (Not all minor ++modes have keymaps.) The local keymap bindings shadow (i.e., take ++precedence over) the corresponding global bindings. The minor mode ++keymaps shadow both local and global keymaps. @xref{Active Keymaps}, ++for details. ++ ++@node Format of Keymaps ++@section Format of Keymaps ++@cindex format of keymaps ++@cindex keymap format ++@cindex full keymap ++@cindex sparse keymap ++ ++ Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The ++remaining elements of the list define the key bindings of the keymap. ++A symbol whose function definition is a keymap is also a keymap. Use ++the function @code{keymapp} (see below) to test whether an object is a ++keymap. ++ ++ Several kinds of elements may appear in a keymap, after the symbol ++@code{keymap} that begins it: ++ ++@table @code ++@item (@var{type} .@: @var{binding}) ++This specifies one binding, for events of type @var{type}. Each ++ordinary binding applies to events of a particular @dfn{event type}, ++which is always a character or a symbol. @xref{Classifying Events}. ++In this kind of binding, @var{binding} is a command. ++ ++@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding}) ++This specifies a binding which is also a simple menu item that ++displays as @var{item-name} in the menu. @var{cache}, if present, ++caches certain information for display in the menu. @xref{Simple Menu ++Items}. ++ ++@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding}) ++This is a simple menu item with help string @var{help-string}. ++ ++@item (@var{type} menu-item .@: @var{details}) ++This specifies a binding which is also an extended menu item. This ++allows use of other features. @xref{Extended Menu Items}. ++ ++@item (t .@: @var{binding}) ++@cindex default key binding ++This specifies a @dfn{default key binding}; any event not bound by other ++elements of the keymap is given @var{binding} as its binding. Default ++bindings allow a keymap to bind all possible event types without having ++to enumerate all of them. A keymap that has a default binding ++completely masks any lower-precedence keymap, except for events ++explicitly bound to @code{nil} (see below). ++ ++@item @var{char-table} ++If an element of a keymap is a char-table, it counts as holding ++bindings for all character events with no modifier bits ++(@pxref{modifier bits}): element @var{n} is the binding for the ++character with code @var{n}. This is a compact way to record lots of ++bindings. A keymap with such a char-table is called a @dfn{full ++keymap}. Other keymaps are called @dfn{sparse keymaps}. ++ ++@item @var{string} ++@cindex keymap prompt string ++@cindex overall prompt string ++@cindex prompt string of keymap ++Aside from elements that specify bindings for keys, a keymap can also ++have a string as an element. This is called the @dfn{overall prompt ++string} and makes it possible to use the keymap as a menu. ++@xref{Defining Menus}. ++@end table ++ ++When the binding is @code{nil}, it doesn't constitute a definition ++but it does take precedence over a default binding or a binding in the ++parent keymap. On the other hand, a binding of @code{nil} does ++@emph{not} override lower-precedence keymaps; thus, if the local map ++gives a binding of @code{nil}, Emacs uses the binding from the ++global map. ++ ++@cindex meta characters lookup ++ Keymaps do not directly record bindings for the meta characters. ++Instead, meta characters are regarded for purposes of key lookup as ++sequences of two characters, the first of which is @key{ESC} (or ++whatever is currently the value of @code{meta-prefix-char}). Thus, the ++key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its ++global binding is found at the slot for @kbd{a} in @code{esc-map} ++(@pxref{Prefix Keys}). ++ ++ This conversion applies only to characters, not to function keys or ++other input events; thus, @kbd{M-@key{end}} has nothing to do with ++@kbd{@key{ESC} @key{end}}. ++ ++ Here as an example is the local keymap for Lisp mode, a sparse ++keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c ++C-l}, @kbd{M-C-q}, and @kbd{M-C-x}. ++ ++@example ++@group ++lisp-mode-map ++@result{} ++@end group ++@group ++(keymap ++ (3 keymap ++ ;; @kbd{C-c C-z} ++ (26 . run-lisp)) ++@end group ++@group ++ (27 keymap ++ ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}} ++ (24 . lisp-send-defun) ++ keymap ++ ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} ++ (17 . indent-sexp)) ++@end group ++@group ++ ;; @r{This part is inherited from @code{lisp-mode-shared-map}.} ++ keymap ++ ;; @key{DEL} ++ (127 . backward-delete-char-untabify) ++@end group ++@group ++ (27 keymap ++ ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} ++ (17 . indent-sexp)) ++ (9 . lisp-indent-line)) ++@end group ++@end example ++ ++@defun keymapp object ++This function returns @code{t} if @var{object} is a keymap, @code{nil} ++otherwise. More precisely, this function tests for a list whose ++@sc{car} is @code{keymap}, or for a symbol whose function definition ++satisfies @code{keymapp}. ++ ++@example ++@group ++(keymapp '(keymap)) ++ @result{} t ++@end group ++@group ++(fset 'foo '(keymap)) ++(keymapp 'foo) ++ @result{} t ++@end group ++@group ++(keymapp (current-global-map)) ++ @result{} t ++@end group ++@end example ++@end defun ++ ++@node Creating Keymaps ++@section Creating Keymaps ++@cindex creating keymaps ++ ++ Here we describe the functions for creating keymaps. ++ ++@defun make-sparse-keymap &optional prompt ++This function creates and returns a new sparse keymap with no entries. ++(A sparse keymap is the kind of keymap you usually want.) The new ++keymap does not contain a char-table, unlike @code{make-keymap}, and ++does not bind any events. ++ ++@example ++@group ++(make-sparse-keymap) ++ @result{} (keymap) ++@end group ++@end example ++ ++If you specify @var{prompt}, that becomes the overall prompt string ++for the keymap. You should specify this only for menu keymaps ++(@pxref{Defining Menus}). A keymap with an overall prompt string will ++always present a mouse menu or a keyboard menu if it is active for ++looking up the next input event. Don't specify an overall prompt string ++for the main map of a major or minor mode, because that would cause ++the command loop to present a keyboard menu every time. ++@end defun ++ ++@defun make-keymap &optional prompt ++This function creates and returns a new full keymap. That keymap ++contains a char-table (@pxref{Char-Tables}) with slots for all ++characters without modifiers. The new keymap initially binds all ++these characters to @code{nil}, and does not bind any other kind of ++event. The argument @var{prompt} specifies a ++prompt string, as in @code{make-sparse-keymap}. ++ ++@example ++@group ++(make-keymap) ++ @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap]) ++@end group ++@end example ++ ++A full keymap is more efficient than a sparse keymap when it holds ++lots of bindings; for just a few, the sparse keymap is better. ++@end defun ++ ++@defun copy-keymap keymap ++This function returns a copy of @var{keymap}. Any keymaps that ++appear directly as bindings in @var{keymap} are also copied recursively, ++and so on to any number of levels. However, recursive copying does not ++take place when the definition of a character is a symbol whose function ++definition is a keymap; the same symbol appears in the new copy. ++@c Emacs 19 feature ++ ++@example ++@group ++(setq map (copy-keymap (current-local-map))) ++@result{} (keymap ++@end group ++@group ++ ;; @r{(This implements meta characters.)} ++ (27 keymap ++ (83 . center-paragraph) ++ (115 . center-line)) ++ (9 . tab-to-tab-stop)) ++@end group ++ ++@group ++(eq map (current-local-map)) ++ @result{} nil ++@end group ++@group ++(equal map (current-local-map)) ++ @result{} t ++@end group ++@end example ++@end defun ++ ++@node Inheritance and Keymaps ++@section Inheritance and Keymaps ++@cindex keymap inheritance ++@cindex inheriting a keymap's bindings ++ ++ A keymap can inherit the bindings of another keymap, which we call the ++@dfn{parent keymap}. Such a keymap looks like this: ++ ++@example ++(keymap @var{elements}@dots{} . @var{parent-keymap}) ++@end example ++ ++@noindent ++The effect is that this keymap inherits all the bindings of ++@var{parent-keymap}, whatever they may be at the time a key is looked up, ++but can add to them or override them with @var{elements}. ++ ++If you change the bindings in @var{parent-keymap} using ++@code{define-key} or other key-binding functions, these changed ++bindings are visible in the inheriting keymap, unless shadowed by the ++bindings made by @var{elements}. The converse is not true: if you use ++@code{define-key} to change bindings in the inheriting keymap, these ++changes are recorded in @var{elements}, but have no effect on ++@var{parent-keymap}. ++ ++The proper way to construct a keymap with a parent is to use ++@code{set-keymap-parent}; if you have code that directly constructs a ++keymap with a parent, please convert the program to use ++@code{set-keymap-parent} instead. ++ ++@defun keymap-parent keymap ++This returns the parent keymap of @var{keymap}. If @var{keymap} ++has no parent, @code{keymap-parent} returns @code{nil}. ++@end defun ++ ++@defun set-keymap-parent keymap parent ++This sets the parent keymap of @var{keymap} to @var{parent}, and returns ++@var{parent}. If @var{parent} is @code{nil}, this function gives ++@var{keymap} no parent at all. ++ ++If @var{keymap} has submaps (bindings for prefix keys), they too receive ++new parent keymaps that reflect what @var{parent} specifies for those ++prefix keys. ++@end defun ++ ++ Here is an example showing how to make a keymap that inherits ++from @code{text-mode-map}: ++ ++@example ++(let ((map (make-sparse-keymap))) ++ (set-keymap-parent map text-mode-map) ++ map) ++@end example ++ ++ A non-sparse keymap can have a parent too, but this is not very ++useful. A non-sparse keymap always specifies something as the binding ++for every numeric character code without modifier bits, even if it is ++@code{nil}, so these character's bindings are never inherited from ++the parent keymap. ++ ++@node Prefix Keys ++@section Prefix Keys ++@cindex prefix key ++ ++ A @dfn{prefix key} is a key sequence whose binding is a keymap. The ++keymap defines what to do with key sequences that extend the prefix key. ++For example, @kbd{C-x} is a prefix key, and it uses a keymap that is ++also stored in the variable @code{ctl-x-map}. This keymap defines ++bindings for key sequences starting with @kbd{C-x}. ++ ++ Some of the standard Emacs prefix keys use keymaps that are ++also found in Lisp variables: ++ ++@itemize @bullet ++@item ++@vindex esc-map ++@findex ESC-prefix ++@code{esc-map} is the global keymap for the @key{ESC} prefix key. Thus, ++the global definitions of all meta characters are actually found here. ++This map is also the function definition of @code{ESC-prefix}. ++ ++@item ++@cindex @kbd{C-h} ++@code{help-map} is the global keymap for the @kbd{C-h} prefix key. ++ ++@item ++@cindex @kbd{C-c} ++@vindex mode-specific-map ++@code{mode-specific-map} is the global keymap for the prefix key ++@kbd{C-c}. This map is actually global, not mode-specific, but its name ++provides useful information about @kbd{C-c} in the output of @kbd{C-h b} ++(@code{display-bindings}), since the main use of this prefix key is for ++mode-specific bindings. ++ ++@item ++@cindex @kbd{C-x} ++@vindex ctl-x-map ++@findex Control-X-prefix ++@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key. ++This map is found via the function cell of the symbol ++@code{Control-X-prefix}. ++ ++@item ++@cindex @kbd{C-x @key{RET}} ++@vindex mule-keymap ++@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}} ++prefix key. ++ ++@item ++@cindex @kbd{C-x 4} ++@vindex ctl-x-4-map ++@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix ++key. ++ ++@item ++@cindex @kbd{C-x 5} ++@vindex ctl-x-5-map ++@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix ++key. ++ ++@item ++@cindex @kbd{C-x 6} ++@vindex 2C-mode-map ++@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix ++key. ++ ++@item ++@cindex @kbd{C-x v} ++@vindex vc-prefix-map ++@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix ++key. ++ ++@item ++@cindex @kbd{M-g} ++@vindex goto-map ++@code{goto-map} is the global keymap used for the @kbd{M-g} prefix ++key. ++ ++@item ++@cindex @kbd{M-s} ++@vindex search-map ++@code{search-map} is the global keymap used for the @kbd{M-s} prefix ++key. ++ ++@item ++@cindex @kbd{M-o} ++@vindex facemenu-keymap ++@code{facemenu-keymap} is the global keymap used for the @kbd{M-o} ++prefix key. ++ ++@item ++The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x ++@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have ++no special names. ++@end itemize ++ ++ The keymap binding of a prefix key is used for looking up the event ++that follows the prefix key. (It may instead be a symbol whose function ++definition is a keymap. The effect is the same, but the symbol serves ++as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the ++symbol @code{Control-X-prefix}, whose function cell holds the keymap ++for @kbd{C-x} commands. (The same keymap is also the value of ++@code{ctl-x-map}.) ++ ++ Prefix key definitions can appear in any active keymap. The ++definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix ++keys appear in the global map, so these prefix keys are always ++available. Major and minor modes can redefine a key as a prefix by ++putting a prefix key definition for it in the local map or the minor ++mode's map. @xref{Active Keymaps}. ++ ++ If a key is defined as a prefix in more than one active map, then its ++various definitions are in effect merged: the commands defined in the ++minor mode keymaps come first, followed by those in the local map's ++prefix definition, and then by those from the global map. ++ ++ In the following example, we make @kbd{C-p} a prefix key in the local ++keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then ++the binding for @kbd{C-p C-f} is the function @code{find-file}, just ++like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any ++active keymap. ++ ++@example ++@group ++(use-local-map (make-sparse-keymap)) ++ @result{} nil ++@end group ++@group ++(local-set-key "\C-p" ctl-x-map) ++ @result{} nil ++@end group ++@group ++(key-binding "\C-p\C-f") ++ @result{} find-file ++@end group ++ ++@group ++(key-binding "\C-p6") ++ @result{} nil ++@end group ++@end example ++ ++@defun define-prefix-command symbol &optional mapvar prompt ++@cindex prefix command ++@anchor{Definition of define-prefix-command} ++This function prepares @var{symbol} for use as a prefix key's binding: ++it creates a sparse keymap and stores it as @var{symbol}'s function ++definition. Subsequently binding a key sequence to @var{symbol} will ++make that key sequence into a prefix key. The return value is @code{symbol}. ++ ++This function also sets @var{symbol} as a variable, with the keymap as ++its value. But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar} ++as a variable instead. ++ ++If @var{prompt} is non-@code{nil}, that becomes the overall prompt ++string for the keymap. The prompt string should be given for menu keymaps ++(@pxref{Defining Menus}). ++@end defun ++ ++@node Active Keymaps ++@section Active Keymaps ++@cindex active keymap ++@cindex global keymap ++@cindex local keymap ++ ++ Emacs normally contains many keymaps; at any given time, just a few ++of them are @dfn{active}, meaning that they participate in the ++interpretation of user input. All the active keymaps are used ++together to determine what command to execute when a key is entered. ++ ++ Normally the active keymaps are the @code{keymap} property keymap, ++the keymaps of any enabled minor modes, the current buffer's local ++keymap, and the global keymap, in that order. Emacs searches for each ++input key sequence in all these keymaps. @xref{Searching Keymaps}, ++for more details of this procedure. ++ ++ When the key sequence starts with a mouse event (optionally preceded ++by a symbolic prefix), the active keymaps are determined based on the ++position in that event. If the event happened on a string embedded ++with a @code{display}, @code{before-string}, or @code{after-string} ++property (@pxref{Special Properties}), the non-@code{nil} map ++properties of the string override those of the buffer (if the ++underlying buffer text contains map properties in its text properties ++or overlays, they are ignored). ++ ++ The @dfn{global keymap} holds the bindings of keys that are defined ++regardless of the current buffer, such as @kbd{C-f}. The variable ++@code{global-map} holds this keymap, which is always active. ++ ++ Each buffer may have another keymap, its @dfn{local keymap}, which ++may contain new or overriding definitions for keys. The current ++buffer's local keymap is always active except when ++@code{overriding-local-map} overrides it. The @code{local-map} text ++or overlay property can specify an alternative local keymap for certain ++parts of the buffer; see @ref{Special Properties}. ++ ++ Each minor mode can have a keymap; if it does, the keymap is active ++when the minor mode is enabled. Modes for emulation can specify ++additional active keymaps through the variable ++@code{emulation-mode-map-alists}. ++ ++ The highest precedence normal keymap comes from the @code{keymap} ++text or overlay property. If that is non-@code{nil}, it is the first ++keymap to be processed, in normal circumstances. ++ ++ However, there are also special ways for programs to substitute ++other keymaps for some of those. The variable ++@code{overriding-local-map}, if non-@code{nil}, specifies a keymap ++that replaces all the usual active keymaps except the global keymap. ++Another way to do this is with @code{overriding-terminal-local-map}; ++it operates on a per-terminal basis. These variables are documented ++below. ++ ++@cindex major mode keymap ++ Since every buffer that uses the same major mode normally uses the ++same local keymap, you can think of the keymap as local to the mode. A ++change to the local keymap of a buffer (using @code{local-set-key}, for ++example) is seen also in the other buffers that share that keymap. ++ ++ The local keymaps that are used for Lisp mode and some other major ++modes exist even if they have not yet been used. These local keymaps are ++the values of variables such as @code{lisp-mode-map}. For most major ++modes, which are less frequently used, the local keymap is constructed ++only when the mode is used for the first time in a session. ++ ++ The minibuffer has local keymaps, too; they contain various completion ++and exit commands. @xref{Intro to Minibuffers}. ++ ++ Emacs has other keymaps that are used in a different way---translating ++events within @code{read-key-sequence}. @xref{Translation Keymaps}. ++ ++ @xref{Standard Keymaps}, for a list of standard keymaps. ++ ++@defun current-active-maps &optional olp position ++This returns the list of active keymaps that would be used by the ++command loop in the current circumstances to look up a key sequence. ++Normally it ignores @code{overriding-local-map} and ++@code{overriding-terminal-local-map}, but if @var{olp} is non-@code{nil} ++then it pays attention to them. @var{position} can optionally be either ++an event position as returned by @code{event-start} or a buffer ++position, and may change the keymaps as described for ++@code{key-binding}. ++@end defun ++ ++@defun key-binding key &optional accept-defaults no-remap position ++This function returns the binding for @var{key} according to the ++current active keymaps. The result is @code{nil} if @var{key} is ++undefined in the keymaps. ++ ++The argument @var{accept-defaults} controls checking for default ++bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}). ++ ++When commands are remapped (@pxref{Remapping Commands}), ++@code{key-binding} normally processes command remappings so as to ++returns the remapped command that will actually be executed. However, ++if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores ++remappings and returns the binding directly specified for @var{key}. ++ ++If @var{key} starts with a mouse event (perhaps following a prefix ++event), the maps to be consulted are determined based on the event's ++position. Otherwise, they are determined based on the value of point. ++However, you can override either of them by specifying @var{position}. ++If @var{position} is non-@code{nil}, it should be either a buffer ++position or an event position like the value of @code{event-start}. ++Then the maps consulted are determined based on @var{position}. ++ ++An error is signaled if @var{key} is not a string or a vector. ++ ++@example ++@group ++(key-binding "\C-x\C-f") ++ @result{} find-file ++@end group ++@end example ++@end defun ++ ++@node Searching Keymaps ++@section Searching the Active Keymaps ++@cindex searching active keymaps for keys ++ ++ After translation of event subsequences (@pxref{Translation ++Keymaps}) Emacs looks for them in the active keymaps. Here is a ++pseudo-Lisp description of the order and conditions for searching ++them: ++ ++@lisp ++(or (if overriding-terminal-local-map ++ (@var{find-in} overriding-terminal-local-map) ++ (if overriding-local-map ++ (@var{find-in} overriding-local-map) ++ (or (@var{find-in} (get-char-property (point) 'keymap)) ++ (@var{find-in-any} emulation-mode-map-alists) ++ (@var{find-in-any} minor-mode-overriding-map-alist) ++ (@var{find-in-any} minor-mode-map-alist) ++ (if (get-text-property (point) 'local-map) ++ (@var{find-in} (get-char-property (point) 'local-map)) ++ (@var{find-in} (current-local-map)))))) ++ (@var{find-in} (current-global-map))) ++@end lisp ++ ++@noindent ++The @var{find-in} and @var{find-in-any} are pseudo functions that ++search in one keymap and in an alist of keymaps, respectively. ++(Searching a single keymap for a binding is called @dfn{key lookup}; ++see @ref{Key Lookup}.) If the key sequence starts with a mouse event, ++or a symbolic prefix event followed by a mouse event, that event's ++position is used instead of point and the current buffer. Mouse ++events on an embedded string use non-@code{nil} text properties from ++that string instead of the buffer. ++ ++@enumerate ++@item ++The function finally found may be remapped ++(@pxref{Remapping Commands}). ++ ++@item ++Characters that are bound to @code{self-insert-command} are translated ++according to @code{translation-table-for-input} before insertion. ++ ++@item ++@code{current-active-maps} returns a list of the ++currently active keymaps at point. ++ ++@item ++When a match is found (@pxref{Key Lookup}), if the binding in the ++keymap is a function, the search is over. However if the keymap entry ++is a symbol with a value or a string, Emacs replaces the input key ++sequences with the variable's value or the string, and restarts the ++search of the active keymaps. ++@end enumerate ++ ++@node Controlling Active Maps ++@section Controlling the Active Keymaps ++ ++@defvar global-map ++This variable contains the default global keymap that maps Emacs ++keyboard input to commands. The global keymap is normally this ++keymap. The default global keymap is a full keymap that binds ++@code{self-insert-command} to all of the printing characters. ++ ++It is normal practice to change the bindings in the global keymap, but you ++should not assign this variable any value other than the keymap it starts ++out with. ++@end defvar ++ ++@defun current-global-map ++This function returns the current global keymap. This is the same as ++the value of @code{global-map} unless you change one or the other. ++The return value is a reference, not a copy; if you use ++@code{define-key} or other functions on it you will alter global ++bindings. ++ ++@example ++@group ++(current-global-map) ++@result{} (keymap [set-mark-command beginning-of-line @dots{} ++ delete-backward-char]) ++@end group ++@end example ++@end defun ++ ++@defun current-local-map ++This function returns the current buffer's local keymap, or @code{nil} ++if it has none. In the following example, the keymap for the ++@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap ++in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse ++keymap. ++ ++@example ++@group ++(current-local-map) ++@result{} (keymap ++ (10 . eval-print-last-sexp) ++ (9 . lisp-indent-line) ++ (127 . backward-delete-char-untabify) ++@end group ++@group ++ (27 keymap ++ (24 . eval-defun) ++ (17 . indent-sexp))) ++@end group ++@end example ++@end defun ++ ++@code{current-local-map} returns a reference to the local keymap, not ++a copy of it; if you use @code{define-key} or other functions on it ++you will alter local bindings. ++ ++@defun current-minor-mode-maps ++This function returns a list of the keymaps of currently enabled minor modes. ++@end defun ++ ++@defun use-global-map keymap ++This function makes @var{keymap} the new current global keymap. It ++returns @code{nil}. ++ ++It is very unusual to change the global keymap. ++@end defun ++ ++@defun use-local-map keymap ++This function makes @var{keymap} the new local keymap of the current ++buffer. If @var{keymap} is @code{nil}, then the buffer has no local ++keymap. @code{use-local-map} returns @code{nil}. Most major mode ++commands use this function. ++@end defun ++ ++@c Emacs 19 feature ++@defvar minor-mode-map-alist ++@anchor{Definition of minor-mode-map-alist} ++This variable is an alist describing keymaps that may or may not be ++active according to the values of certain variables. Its elements look ++like this: ++ ++@example ++(@var{variable} . @var{keymap}) ++@end example ++ ++The keymap @var{keymap} is active whenever @var{variable} has a ++non-@code{nil} value. Typically @var{variable} is the variable that ++enables or disables a minor mode. @xref{Keymaps and Minor Modes}. ++ ++Note that elements of @code{minor-mode-map-alist} do not have the same ++structure as elements of @code{minor-mode-alist}. The map must be the ++@sc{cdr} of the element; a list with the map as the second element will ++not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose ++function definition is a keymap. ++ ++When more than one minor mode keymap is active, the earlier one in ++@code{minor-mode-map-alist} takes priority. But you should design ++minor modes so that they don't interfere with each other. If you do ++this properly, the order will not matter. ++ ++See @ref{Keymaps and Minor Modes}, for more information about minor ++modes. See also @code{minor-mode-key-binding} (@pxref{Functions for Key ++Lookup}). ++@end defvar ++ ++@defvar minor-mode-overriding-map-alist ++This variable allows major modes to override the key bindings for ++particular minor modes. The elements of this alist look like the ++elements of @code{minor-mode-map-alist}: @code{(@var{variable} ++. @var{keymap})}. ++ ++If a variable appears as an element of ++@code{minor-mode-overriding-map-alist}, the map specified by that ++element totally replaces any map specified for the same variable in ++@code{minor-mode-map-alist}. ++ ++@code{minor-mode-overriding-map-alist} is automatically buffer-local in ++all buffers. ++@end defvar ++ ++@defvar overriding-local-map ++If non-@code{nil}, this variable holds a keymap to use instead of the ++buffer's local keymap, any text property or overlay keymaps, and any ++minor mode keymaps. This keymap, if specified, overrides all other ++maps that would have been active, except for the current global map. ++@end defvar ++ ++@defvar overriding-terminal-local-map ++If non-@code{nil}, this variable holds a keymap to use instead of ++@code{overriding-local-map}, the buffer's local keymap, text property ++or overlay keymaps, and all the minor mode keymaps. ++ ++This variable is always local to the current terminal and cannot be ++buffer-local. @xref{Multiple Terminals}. It is used to implement ++incremental search mode. ++@end defvar ++ ++@defvar overriding-local-map-menu-flag ++If this variable is non-@code{nil}, the value of ++@code{overriding-local-map} or @code{overriding-terminal-local-map} can ++affect the display of the menu bar. The default value is @code{nil}, so ++those map variables have no effect on the menu bar. ++ ++Note that these two map variables do affect the execution of key ++sequences entered using the menu bar, even if they do not affect the ++menu bar display. So if a menu bar key sequence comes in, you should ++clear the variables before looking up and executing that key sequence. ++Modes that use the variables would typically do this anyway; normally ++they respond to events that they do not handle by ``unreading'' them and ++exiting. ++@end defvar ++ ++@defvar special-event-map ++This variable holds a keymap for special events. If an event type has a ++binding in this keymap, then it is special, and the binding for the ++event is run directly by @code{read-event}. @xref{Special Events}. ++@end defvar ++ ++@defvar emulation-mode-map-alists ++This variable holds a list of keymap alists to use for emulations ++modes. It is intended for modes or packages using multiple minor-mode ++keymaps. Each element is a keymap alist which has the same format and ++meaning as @code{minor-mode-map-alist}, or a symbol with a variable ++binding which is such an alist. The ``active'' keymaps in each alist ++are used before @code{minor-mode-map-alist} and ++@code{minor-mode-overriding-map-alist}. ++@end defvar ++ ++@node Key Lookup ++@section Key Lookup ++@cindex key lookup ++@cindex keymap entry ++ ++ @dfn{Key lookup} is the process of finding the binding of a key ++sequence from a given keymap. The execution or use of the binding is ++not part of key lookup. ++ ++ Key lookup uses just the event type of each event in the key sequence; ++the rest of the event is ignored. In fact, a key sequence used for key ++lookup may designate a mouse event with just its types (a symbol) ++instead of the entire event (a list). @xref{Input Events}. Such ++a ``key sequence'' is insufficient for @code{command-execute} to run, ++but it is sufficient for looking up or rebinding a key. ++ ++ When the key sequence consists of multiple events, key lookup ++processes the events sequentially: the binding of the first event is ++found, and must be a keymap; then the second event's binding is found in ++that keymap, and so on until all the events in the key sequence are used ++up. (The binding thus found for the last event may or may not be a ++keymap.) Thus, the process of key lookup is defined in terms of a ++simpler process for looking up a single event in a keymap. How that is ++done depends on the type of object associated with the event in that ++keymap. ++ ++ Let's use the term @dfn{keymap entry} to describe the value found by ++looking up an event type in a keymap. (This doesn't include the item ++string and other extra elements in a keymap element for a menu item, because ++@code{lookup-key} and other key lookup functions don't include them in ++the returned value.) While any Lisp object may be stored in a keymap ++as a keymap entry, not all make sense for key lookup. Here is a table ++of the meaningful types of keymap entries: ++ ++@table @asis ++@item @code{nil} ++@cindex @code{nil} in keymap ++@code{nil} means that the events used so far in the lookup form an ++undefined key. When a keymap fails to mention an event type at all, and ++has no default binding, that is equivalent to a binding of @code{nil} ++for that event type. ++ ++@item @var{command} ++@cindex command in keymap ++The events used so far in the lookup form a complete key, ++and @var{command} is its binding. @xref{What Is a Function}. ++ ++@item @var{array} ++@cindex string in keymap ++The array (either a string or a vector) is a keyboard macro. The events ++used so far in the lookup form a complete key, and the array is its ++binding. See @ref{Keyboard Macros}, for more information. ++ ++@item @var{keymap} ++@cindex keymap in keymap ++The events used so far in the lookup form a prefix key. The next ++event of the key sequence is looked up in @var{keymap}. ++ ++@item @var{list} ++@cindex list in keymap ++The meaning of a list depends on what it contains: ++ ++@itemize @bullet ++@item ++If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list ++is a keymap, and is treated as a keymap (see above). ++ ++@item ++@cindex @code{lambda} in keymap ++If the @sc{car} of @var{list} is @code{lambda}, then the list is a ++lambda expression. This is presumed to be a function, and is treated ++as such (see above). In order to execute properly as a key binding, ++this function must be a command---it must have an @code{interactive} ++specification. @xref{Defining Commands}. ++ ++@item ++If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event ++type, then this is an @dfn{indirect entry}: ++ ++@example ++(@var{othermap} . @var{othertype}) ++@end example ++ ++When key lookup encounters an indirect entry, it looks up instead the ++binding of @var{othertype} in @var{othermap} and uses that. ++ ++This feature permits you to define one key as an alias for another key. ++For example, an entry whose @sc{car} is the keymap called @code{esc-map} ++and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global ++binding of @kbd{Meta-@key{SPC}}, whatever that may be.'' ++@end itemize ++ ++@item @var{symbol} ++@cindex symbol in keymap ++The function definition of @var{symbol} is used in place of ++@var{symbol}. If that too is a symbol, then this process is repeated, ++any number of times. Ultimately this should lead to an object that is ++a keymap, a command, or a keyboard macro. A list is allowed if it is a ++keymap or a command, but indirect entries are not understood when found ++via symbols. ++ ++Note that keymaps and keyboard macros (strings and vectors) are not ++valid functions, so a symbol with a keymap, string, or vector as its ++function definition is invalid as a function. It is, however, valid as ++a key binding. If the definition is a keyboard macro, then the symbol ++is also valid as an argument to @code{command-execute} ++(@pxref{Interactive Call}). ++ ++@cindex @code{undefined} in keymap ++The symbol @code{undefined} is worth special mention: it means to treat ++the key as undefined. Strictly speaking, the key is defined, and its ++binding is the command @code{undefined}; but that command does the same ++thing that is done automatically for an undefined key: it rings the bell ++(by calling @code{ding}) but does not signal an error. ++ ++@cindex preventing prefix key ++@code{undefined} is used in local keymaps to override a global key ++binding and make the key ``undefined'' locally. A local binding of ++@code{nil} would fail to do this because it would not override the ++global binding. ++ ++@item @var{anything else} ++If any other type of object is found, the events used so far in the ++lookup form a complete key, and the object is its binding, but the ++binding is not executable as a command. ++@end table ++ ++ In short, a keymap entry may be a keymap, a command, a keyboard macro, ++a symbol that leads to one of them, or an indirection or @code{nil}. ++Here is an example of a sparse keymap with two characters bound to ++commands and one bound to another keymap. This map is the normal value ++of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB}, ++127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for ++@kbd{C-x}. ++ ++@example ++@group ++(keymap (9 . lisp-indent-line) ++ (127 . backward-delete-char-untabify) ++ (27 keymap (17 . indent-sexp) (24 . eval-defun))) ++@end group ++@end example ++ ++@node Functions for Key Lookup ++@section Functions for Key Lookup ++ ++ Here are the functions and variables pertaining to key lookup. ++ ++@defun lookup-key keymap key &optional accept-defaults ++This function returns the definition of @var{key} in @var{keymap}. All ++the other functions described in this chapter that look up keys use ++@code{lookup-key}. Here are examples: ++ ++@example ++@group ++(lookup-key (current-global-map) "\C-x\C-f") ++ @result{} find-file ++@end group ++@group ++(lookup-key (current-global-map) (kbd "C-x C-f")) ++ @result{} find-file ++@end group ++@group ++(lookup-key (current-global-map) "\C-x\C-f12345") ++ @result{} 2 ++@end group ++@end example ++ ++If the string or vector @var{key} is not a valid key sequence according ++to the prefix keys specified in @var{keymap}, it must be ``too long'' ++and have extra events at the end that do not fit into a single key ++sequence. Then the value is a number, the number of events at the front ++of @var{key} that compose a complete key. ++ ++@c Emacs 19 feature ++If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} ++considers default bindings as well as bindings for the specific events ++in @var{key}. Otherwise, @code{lookup-key} reports only bindings for ++the specific sequence @var{key}, ignoring default bindings except when ++you explicitly ask about them. (To do this, supply @code{t} as an ++element of @var{key}; see @ref{Format of Keymaps}.) ++ ++If @var{key} contains a meta character (not a function key), that ++character is implicitly replaced by a two-character sequence: the value ++of @code{meta-prefix-char}, followed by the corresponding non-meta ++character. Thus, the first example below is handled by conversion into ++the second example. ++ ++@example ++@group ++(lookup-key (current-global-map) "\M-f") ++ @result{} forward-word ++@end group ++@group ++(lookup-key (current-global-map) "\ef") ++ @result{} forward-word ++@end group ++@end example ++ ++Unlike @code{read-key-sequence}, this function does not modify the ++specified events in ways that discard information (@pxref{Key Sequence ++Input}). In particular, it does not convert letters to lower case and ++it does not change drag events to clicks. ++@end defun ++ ++@deffn Command undefined ++Used in keymaps to undefine keys. It calls @code{ding}, but does ++not cause an error. ++@end deffn ++ ++@defun local-key-binding key &optional accept-defaults ++This function returns the binding for @var{key} in the current ++local keymap, or @code{nil} if it is undefined there. ++ ++@c Emacs 19 feature ++The argument @var{accept-defaults} controls checking for default bindings, ++as in @code{lookup-key} (above). ++@end defun ++ ++@defun global-key-binding key &optional accept-defaults ++This function returns the binding for command @var{key} in the ++current global keymap, or @code{nil} if it is undefined there. ++ ++@c Emacs 19 feature ++The argument @var{accept-defaults} controls checking for default bindings, ++as in @code{lookup-key} (above). ++@end defun ++ ++@c Emacs 19 feature ++@defun minor-mode-key-binding key &optional accept-defaults ++This function returns a list of all the active minor mode bindings of ++@var{key}. More precisely, it returns an alist of pairs ++@code{(@var{modename} . @var{binding})}, where @var{modename} is the ++variable that enables the minor mode, and @var{binding} is @var{key}'s ++binding in that mode. If @var{key} has no minor-mode bindings, the ++value is @code{nil}. ++ ++If the first binding found is not a prefix definition (a keymap or a ++symbol defined as a keymap), all subsequent bindings from other minor ++modes are omitted, since they would be completely shadowed. Similarly, ++the list omits non-prefix bindings that follow prefix bindings. ++ ++The argument @var{accept-defaults} controls checking for default ++bindings, as in @code{lookup-key} (above). ++@end defun ++ ++@defopt meta-prefix-char ++@cindex @key{ESC} ++This variable is the meta-prefix character code. It is used for ++translating a meta character to a two-character sequence so it can be ++looked up in a keymap. For useful results, the value should be a ++prefix event (@pxref{Prefix Keys}). The default value is 27, which is ++the @acronym{ASCII} code for @key{ESC}. ++ ++As long as the value of @code{meta-prefix-char} remains 27, key lookup ++translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined ++as the @code{backward-word} command. However, if you were to set ++@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will ++translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the ++@code{switch-to-buffer} command. (Don't actually do this!) Here is an ++illustration of what would happen: ++ ++@smallexample ++@group ++meta-prefix-char ; @r{The default value.} ++ @result{} 27 ++@end group ++@group ++(key-binding "\M-b") ++ @result{} backward-word ++@end group ++@group ++?\C-x ; @r{The print representation} ++ @result{} 24 ; @r{of a character.} ++@end group ++@group ++(setq meta-prefix-char 24) ++ @result{} 24 ++@end group ++@group ++(key-binding "\M-b") ++ @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is} ++ ; @r{like typing @kbd{C-x b}.} ++ ++(setq meta-prefix-char 27) ; @r{Avoid confusion!} ++ @result{} 27 ; @r{Restore the default value!} ++@end group ++@end smallexample ++ ++This translation of one event into two happens only for characters, not ++for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function ++key, is not converted into @kbd{@key{ESC} @key{F1}}. ++@end defopt ++ ++@node Changing Key Bindings ++@section Changing Key Bindings ++@cindex changing key bindings ++@cindex rebinding ++ ++ The way to rebind a key is to change its entry in a keymap. If you ++change a binding in the global keymap, the change is effective in all ++buffers (though it has no direct effect in buffers that shadow the ++global binding with a local one). If you change the current buffer's ++local map, that usually affects all buffers using the same major mode. ++The @code{global-set-key} and @code{local-set-key} functions are ++convenient interfaces for these operations (@pxref{Key Binding ++Commands}). You can also use @code{define-key}, a more general ++function; then you must specify explicitly the map to change. ++ ++ When choosing the key sequences for Lisp programs to rebind, please ++follow the Emacs conventions for use of various keys (@pxref{Key ++Binding Conventions}). ++ ++@cindex meta character key constants ++@cindex control character key constants ++ In writing the key sequence to rebind, it is good to use the special ++escape sequences for control and meta characters (@pxref{String Type}). ++The syntax @samp{\C-} means that the following character is a control ++character and @samp{\M-} means that the following character is a meta ++character. Thus, the string @code{"\M-x"} is read as containing a ++single @kbd{M-x}, @code{"\C-f"} is read as containing a single ++@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as ++containing a single @kbd{C-M-x}. You can also use this escape syntax in ++vectors, as well as others that aren't allowed in strings; one example ++is @samp{[?\C-\H-x home]}. @xref{Character Type}. ++ ++ The key definition and lookup functions accept an alternate syntax for ++event types in a key sequence that is a vector: you can use a list ++containing modifier names plus one base event (a character or function ++key name). For example, @code{(control ?a)} is equivalent to ++@code{?\C-a} and @code{(hyper control left)} is equivalent to ++@code{C-H-left}. One advantage of such lists is that the precise ++numeric codes for the modifier bits don't appear in compiled files. ++ ++ The functions below signal an error if @var{keymap} is not a keymap, ++or if @var{key} is not a string or vector representing a key sequence. ++You can use event types (symbols) as shorthand for events that are ++lists. The @code{kbd} macro (@pxref{Key Sequences}) is a convenient ++way to specify the key sequence. ++ ++@defun define-key keymap key binding ++This function sets the binding for @var{key} in @var{keymap}. (If ++@var{key} is more than one event long, the change is actually made ++in another keymap reached from @var{keymap}.) The argument ++@var{binding} can be any Lisp object, but only certain types are ++meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) ++The value returned by @code{define-key} is @var{binding}. ++ ++If @var{key} is @code{[t]}, this sets the default binding in ++@var{keymap}. When an event has no binding of its own, the Emacs ++command loop uses the keymap's default binding, if there is one. ++ ++@cindex invalid prefix key error ++@cindex key sequence error ++Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap) ++or undefined; otherwise an error is signaled. If some prefix of ++@var{key} is undefined, then @code{define-key} defines it as a prefix ++key so that the rest of @var{key} can be defined as specified. ++ ++If there was previously no binding for @var{key} in @var{keymap}, the ++new binding is added at the beginning of @var{keymap}. The order of ++bindings in a keymap makes no difference for keyboard input, but it ++does matter for menu keymaps (@pxref{Menu Keymaps}). ++@end defun ++ ++ This example creates a sparse keymap and makes a number of ++bindings in it: ++ ++@smallexample ++@group ++(setq map (make-sparse-keymap)) ++ @result{} (keymap) ++@end group ++@group ++(define-key map "\C-f" 'forward-char) ++ @result{} forward-char ++@end group ++@group ++map ++ @result{} (keymap (6 . forward-char)) ++@end group ++ ++@group ++;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} ++(define-key map (kbd "C-x f") 'forward-word) ++ @result{} forward-word ++@end group ++@group ++map ++@result{} (keymap ++ (24 keymap ; @kbd{C-x} ++ (102 . forward-word)) ; @kbd{f} ++ (6 . forward-char)) ; @kbd{C-f} ++@end group ++ ++@group ++;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} ++(define-key map (kbd "C-p") ctl-x-map) ++;; @code{ctl-x-map} ++@result{} [nil @dots{} find-file @dots{} backward-kill-sentence] ++@end group ++ ++@group ++;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} ++(define-key map (kbd "C-p C-f") 'foo) ++@result{} 'foo ++@end group ++@group ++map ++@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.} ++ (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence]) ++ (24 keymap ++ (102 . forward-word)) ++ (6 . forward-char)) ++@end group ++@end smallexample ++ ++@noindent ++Note that storing a new binding for @kbd{C-p C-f} actually works by ++changing an entry in @code{ctl-x-map}, and this has the effect of ++changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the ++default global map. ++ ++ The function @code{substitute-key-definition} scans a keymap for ++keys that have a certain binding and rebinds them with a different ++binding. Another feature which is cleaner and can often produce the ++same results to remap one command into another (@pxref{Remapping ++Commands}). ++ ++@defun substitute-key-definition olddef newdef keymap &optional oldmap ++@cindex replace bindings ++This function replaces @var{olddef} with @var{newdef} for any keys in ++@var{keymap} that were bound to @var{olddef}. In other words, ++@var{olddef} is replaced with @var{newdef} wherever it appears. The ++function returns @code{nil}. ++ ++For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with ++standard bindings: ++ ++@smallexample ++@group ++(substitute-key-definition ++ 'find-file 'find-file-read-only (current-global-map)) ++@end group ++@end smallexample ++ ++@c Emacs 19 feature ++If @var{oldmap} is non-@code{nil}, that changes the behavior of ++@code{substitute-key-definition}: the bindings in @var{oldmap} determine ++which keys to rebind. The rebindings still happen in @var{keymap}, not ++in @var{oldmap}. Thus, you can change one map under the control of the ++bindings in another. For example, ++ ++@smallexample ++(substitute-key-definition ++ 'delete-backward-char 'my-funny-delete ++ my-map global-map) ++@end smallexample ++ ++@noindent ++puts the special deletion command in @code{my-map} for whichever keys ++are globally bound to the standard deletion command. ++ ++Here is an example showing a keymap before and after substitution: ++ ++@smallexample ++@group ++(setq map '(keymap ++ (?1 . olddef-1) ++ (?2 . olddef-2) ++ (?3 . olddef-1))) ++@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1)) ++@end group ++ ++@group ++(substitute-key-definition 'olddef-1 'newdef map) ++@result{} nil ++@end group ++@group ++map ++@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef)) ++@end group ++@end smallexample ++@end defun ++ ++@defun suppress-keymap keymap &optional nodigits ++@cindex @code{self-insert-command} override ++This function changes the contents of the full keymap @var{keymap} by ++remapping @code{self-insert-command} to the command @code{undefined} ++(@pxref{Remapping Commands}). This has the effect of undefining all ++printing characters, thus making ordinary insertion of text impossible. ++@code{suppress-keymap} returns @code{nil}. ++ ++If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines ++digits to run @code{digit-argument}, and @kbd{-} to run ++@code{negative-argument}. Otherwise it makes them undefined like the ++rest of the printing characters. ++ ++@cindex yank suppression ++@cindex @code{quoted-insert} suppression ++The @code{suppress-keymap} function does not make it impossible to ++modify a buffer, as it does not suppress commands such as @code{yank} ++and @code{quoted-insert}. To prevent any modification of a buffer, make ++it read-only (@pxref{Read Only Buffers}). ++ ++Since this function modifies @var{keymap}, you would normally use it ++on a newly created keymap. Operating on an existing keymap ++that is used for some other purpose is likely to cause trouble; for ++example, suppressing @code{global-map} would make it impossible to use ++most of Emacs. ++ ++Most often, @code{suppress-keymap} is used to initialize local ++keymaps of modes such as Rmail and Dired where insertion of text is not ++desirable and the buffer is read-only. Here is an example taken from ++the file @file{emacs/lisp/dired.el}, showing how the local keymap for ++Dired mode is set up: ++ ++@smallexample ++@group ++(setq dired-mode-map (make-keymap)) ++(suppress-keymap dired-mode-map) ++(define-key dired-mode-map "r" 'dired-rename-file) ++(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted) ++(define-key dired-mode-map "d" 'dired-flag-file-deleted) ++(define-key dired-mode-map "v" 'dired-view-file) ++(define-key dired-mode-map "e" 'dired-find-file) ++(define-key dired-mode-map "f" 'dired-find-file) ++@dots{} ++@end group ++@end smallexample ++@end defun ++ ++@node Remapping Commands ++@section Remapping Commands ++@cindex remapping commands ++ ++ A special kind of key binding, using a special ``key sequence'' ++which includes a command name, has the effect of @dfn{remapping} that ++command into another. Here's how it works. You make a key binding ++for a key sequence that starts with the dummy event @code{remap}, ++followed by the command name you want to remap. Specify the remapped ++definition as the definition in this binding. The remapped definition ++is usually a command name, but it can be any valid definition for ++a key binding. ++ ++ Here's an example. Suppose that My mode uses special commands ++@code{my-kill-line} and @code{my-kill-word}, which should be invoked ++instead of @code{kill-line} and @code{kill-word}. It can establish ++this by making these two command-remapping bindings in its keymap: ++ ++@smallexample ++(define-key my-mode-map [remap kill-line] 'my-kill-line) ++(define-key my-mode-map [remap kill-word] 'my-kill-word) ++@end smallexample ++ ++Whenever @code{my-mode-map} is an active keymap, if the user types ++@kbd{C-k}, Emacs will find the standard global binding of ++@code{kill-line} (assuming nobody has changed it). But ++@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line}, ++so instead of running @code{kill-line}, Emacs runs ++@code{my-kill-line}. ++ ++Remapping only works through a single level. In other words, ++ ++@smallexample ++(define-key my-mode-map [remap kill-line] 'my-kill-line) ++(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line) ++@end smallexample ++ ++@noindent ++does not have the effect of remapping @code{kill-line} into ++@code{my-other-kill-line}. If an ordinary key binding specifies ++@code{kill-line}, this keymap will remap it to @code{my-kill-line}; ++if an ordinary binding specifies @code{my-kill-line}, this keymap will ++remap it to @code{my-other-kill-line}. ++ ++@defun command-remapping command &optional position keymaps ++This function returns the remapping for @var{command} (a symbol), ++given the current active keymaps. If @var{command} is not remapped ++(which is the usual situation), or not a symbol, the function returns ++@code{nil}. @code{position} can optionally specify a buffer position ++or an event position to determine the keymaps to use, as in ++@code{key-binding}. ++ ++If the optional argument @code{keymaps} is non-@code{nil}, it ++specifies a list of keymaps to search in. This argument is ignored if ++@code{position} is non-@code{nil}. ++@end defun ++ ++@node Translation Keymaps ++@section Keymaps for Translating Sequences of Events ++@cindex keymaps for translating events ++ ++ This section describes keymaps that are used during reading a key ++sequence, to translate certain event sequences into others. ++@code{read-key-sequence} checks every subsequence of the key sequence ++being read, as it is read, against @code{input-decode-map}, then ++@code{local-function-key-map}, and then against @code{key-translation-map}. ++ ++@defvar input-decode-map ++This variable holds a keymap that describes the character sequences sent ++by function keys on an ordinary character terminal. This keymap has the ++same structure as other keymaps, but is used differently: it specifies ++translations to make while reading key sequences, rather than bindings ++for key sequences. ++ ++If @code{input-decode-map} ``binds'' a key sequence @var{k} to a vector ++@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a ++key sequence, it is replaced with the events in @var{v}. ++ ++For example, VT100 terminals send @kbd{@key{ESC} O P} when the ++keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate ++that sequence of events into the single event @code{pf1}. We accomplish ++this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in ++@code{input-decode-map}, when using a VT100. ++ ++Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c ++@key{ESC} O P}; later the function @code{read-key-sequence} translates ++this back into @kbd{C-c @key{PF1}}, which it returns as the vector ++@code{[?\C-c pf1]}. ++ ++The value of @code{input-decode-map} is usually set up automatically ++according to the terminal's Terminfo or Termcap entry, but sometimes ++those need help from terminal-specific Lisp files. Emacs comes with ++terminal-specific files for many common terminals; their main purpose is ++to make entries in @code{input-decode-map} beyond those that can be ++deduced from Termcap and Terminfo. @xref{Terminal-Specific}. ++@end defvar ++ ++@defvar local-function-key-map ++This variable holds a keymap similar to @code{input-decode-map} except ++that it describes key sequences which should be translated to ++alternative interpretations that are usually preferred. It applies ++after @code{input-decode-map} and before @code{key-translation-map}. ++ ++Entries in @code{local-function-key-map} are ignored if they conflict ++with bindings made in the minor mode, local, or global keymaps. I.e. ++the remapping only applies if the original key sequence would ++otherwise not have any binding. ++ ++@code{local-function-key-map} inherits from @code{function-key-map}, ++but the latter should not be used directly. ++@end defvar ++ ++@defvar key-translation-map ++This variable is another keymap used just like @code{input-decode-map} ++to translate input events into other events. It differs from ++@code{input-decode-map} in that it goes to work after ++@code{local-function-key-map} is finished rather than before; it ++receives the results of translation by @code{local-function-key-map}. ++ ++Just like @code{input-decode-map}, but unlike ++@code{local-function-key-map}, this keymap is applied regardless of ++whether the input key-sequence has a normal binding. Note however ++that actual key bindings can have an effect on ++@code{key-translation-map}, even though they are overridden by it. ++Indeed, actual key bindings override @code{local-function-key-map} and ++thus may alter the key sequence that @code{key-translation-map} ++receives. Clearly, it is better to avoid this type of situation. ++ ++The intent of @code{key-translation-map} is for users to map one ++character set to another, including ordinary characters normally bound ++to @code{self-insert-command}. ++@end defvar ++ ++@cindex key translation function ++You can use @code{input-decode-map}, @code{local-function-key-map}, or ++@code{key-translation-map} for more than simple aliases, by using a ++function, instead of a key sequence, as the ``translation'' of a key. ++Then this function is called to compute the translation of that key. ++ ++The key translation function receives one argument, which is the prompt ++that was specified in @code{read-key-sequence}---or @code{nil} if the ++key sequence is being read by the editor command loop. In most cases ++you can ignore the prompt value. ++ ++If the function reads input itself, it can have the effect of altering ++the event that follows. For example, here's how to define @kbd{C-c h} ++to turn the character that follows into a Hyper character: ++ ++@example ++@group ++(defun hyperify (prompt) ++ (let ((e (read-event))) ++ (vector (if (numberp e) ++ (logior (lsh 1 24) e) ++ (if (memq 'hyper (event-modifiers e)) ++ e ++ (add-event-modifier "H-" e)))))) ++ ++(defun add-event-modifier (string e) ++ (let ((symbol (if (symbolp e) e (car e)))) ++ (setq symbol (intern (concat string ++ (symbol-name symbol)))) ++@end group ++@group ++ (if (symbolp e) ++ symbol ++ (cons symbol (cdr e))))) ++ ++(define-key local-function-key-map "\C-ch" 'hyperify) ++@end group ++@end example ++ ++ If you have enabled keyboard character set decoding using ++@code{set-keyboard-coding-system}, decoding is done after the ++translations listed above. @xref{Terminal I/O Encoding}. However, in ++future Emacs versions, character set decoding may be done at an ++earlier stage. ++ ++@node Key Binding Commands ++@section Commands for Binding Keys ++ ++ This section describes some convenient interactive interfaces for ++changing key bindings. They work by calling @code{define-key}. ++ ++ People often use @code{global-set-key} in their init files ++(@pxref{Init File}) for simple customization. For example, ++ ++@smallexample ++(global-set-key (kbd "C-x C-\\") 'next-line) ++@end smallexample ++ ++@noindent ++or ++ ++@smallexample ++(global-set-key [?\C-x ?\C-\\] 'next-line) ++@end smallexample ++ ++@noindent ++or ++ ++@smallexample ++(global-set-key [(control ?x) (control ?\\)] 'next-line) ++@end smallexample ++ ++@noindent ++redefines @kbd{C-x C-\} to move down a line. ++ ++@smallexample ++(global-set-key [M-mouse-1] 'mouse-set-point) ++@end smallexample ++ ++@noindent ++redefines the first (leftmost) mouse button, entered with the Meta key, to ++set point where you click. ++ ++@cindex non-@acronym{ASCII} text in keybindings ++ Be careful when using non-@acronym{ASCII} text characters in Lisp ++specifications of keys to bind. If these are read as multibyte text, as ++they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you ++must type the keys as multibyte too. For instance, if you use this: ++ ++@smallexample ++(global-set-key "@"o" 'my-function) ; bind o-umlaut ++@end smallexample ++ ++@noindent ++or ++ ++@smallexample ++(global-set-key ?@"o 'my-function) ; bind o-umlaut ++@end smallexample ++ ++@noindent ++and your language environment is multibyte Latin-1, these commands ++actually bind the multibyte character with code 2294, not the unibyte ++Latin-1 character with code 246 (@kbd{M-v}). In order to use this ++binding, you need to enter the multibyte Latin-1 character as keyboard ++input. One way to do this is by using an appropriate input method ++(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}). ++ ++ If you want to use a unibyte character in the key binding, you can ++construct the key sequence string using @code{multibyte-char-to-unibyte} ++or @code{string-make-unibyte} (@pxref{Converting Representations}). ++ ++@deffn Command global-set-key key binding ++This function sets the binding of @var{key} in the current global map ++to @var{binding}. ++ ++@smallexample ++@group ++(global-set-key @var{key} @var{binding}) ++@equiv{} ++(define-key (current-global-map) @var{key} @var{binding}) ++@end group ++@end smallexample ++@end deffn ++ ++@deffn Command global-unset-key key ++@cindex unbinding keys ++This function removes the binding of @var{key} from the current ++global map. ++ ++One use of this function is in preparation for defining a longer key ++that uses @var{key} as a prefix---which would not be allowed if ++@var{key} has a non-prefix binding. For example: ++ ++@smallexample ++@group ++(global-unset-key "\C-l") ++ @result{} nil ++@end group ++@group ++(global-set-key "\C-l\C-l" 'redraw-display) ++ @result{} nil ++@end group ++@end smallexample ++ ++This function is implemented simply using @code{define-key}: ++ ++@smallexample ++@group ++(global-unset-key @var{key}) ++@equiv{} ++(define-key (current-global-map) @var{key} nil) ++@end group ++@end smallexample ++@end deffn ++ ++@deffn Command local-set-key key binding ++This function sets the binding of @var{key} in the current local ++keymap to @var{binding}. ++ ++@smallexample ++@group ++(local-set-key @var{key} @var{binding}) ++@equiv{} ++(define-key (current-local-map) @var{key} @var{binding}) ++@end group ++@end smallexample ++@end deffn ++ ++@deffn Command local-unset-key key ++This function removes the binding of @var{key} from the current ++local map. ++ ++@smallexample ++@group ++(local-unset-key @var{key}) ++@equiv{} ++(define-key (current-local-map) @var{key} nil) ++@end group ++@end smallexample ++@end deffn ++ ++@node Scanning Keymaps ++@section Scanning Keymaps ++ ++ This section describes functions used to scan all the current keymaps ++for the sake of printing help information. ++ ++@defun accessible-keymaps keymap &optional prefix ++This function returns a list of all the keymaps that can be reached (via ++zero or more prefix keys) from @var{keymap}. The value is an ++association list with elements of the form @code{(@var{key} .@: ++@var{map})}, where @var{key} is a prefix key whose definition in ++@var{keymap} is @var{map}. ++ ++The elements of the alist are ordered so that the @var{key} increases ++in length. The first element is always @code{([] .@: @var{keymap})}, ++because the specified keymap is accessible from itself with a prefix of ++no events. ++ ++If @var{prefix} is given, it should be a prefix key sequence; then ++@code{accessible-keymaps} includes only the submaps whose prefixes start ++with @var{prefix}. These elements look just as they do in the value of ++@code{(accessible-keymaps)}; the only difference is that some elements ++are omitted. ++ ++In the example below, the returned alist indicates that the key ++@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose ++definition is the sparse keymap @code{(keymap (83 .@: center-paragraph) ++(115 .@: foo))}. ++ ++@smallexample ++@group ++(accessible-keymaps (current-local-map)) ++@result{}(([] keymap ++ (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.} ++ (83 . center-paragraph) ++ (115 . center-line)) ++ (9 . tab-to-tab-stop)) ++@end group ++ ++@group ++ ("^[" keymap ++ (83 . center-paragraph) ++ (115 . foo))) ++@end group ++@end smallexample ++ ++In the following example, @kbd{C-h} is a prefix key that uses a sparse ++keymap starting with @code{(keymap (118 . describe-variable)@dots{})}. ++Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of ++the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of ++several dummy events used as prefixes for mouse actions in special parts ++of a window. ++ ++@smallexample ++@group ++(accessible-keymaps (current-global-map)) ++@result{} (([] keymap [set-mark-command beginning-of-line @dots{} ++ delete-backward-char]) ++@end group ++@group ++ ("^H" keymap (118 . describe-variable) @dots{} ++ (8 . help-for-help)) ++@end group ++@group ++ ("^X" keymap [x-flush-mouse-queue @dots{} ++ backward-kill-sentence]) ++@end group ++@group ++ ("^[" keymap [mark-sexp backward-sexp @dots{} ++ backward-kill-word]) ++@end group ++ ("^X4" keymap (15 . display-buffer) @dots{}) ++@group ++ ([mode-line] keymap ++ (S-mouse-2 . mouse-split-window-horizontally) @dots{})) ++@end group ++@end smallexample ++ ++@noindent ++These are not all the keymaps you would see in actuality. ++@end defun ++ ++@defun map-keymap function keymap ++The function @code{map-keymap} calls @var{function} once ++for each binding in @var{keymap}. It passes two arguments, ++the event type and the value of the binding. If @var{keymap} ++has a parent, the parent's bindings are included as well. ++This works recursively: if the parent has itself a parent, then the ++grandparent's bindings are also included and so on. ++ ++This function is the cleanest way to examine all the bindings ++in a keymap. ++@end defun ++ ++@defun where-is-internal command &optional keymap firstonly noindirect no-remap ++This function is a subroutine used by the @code{where-is} command ++(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list ++of all key sequences (of any length) that are bound to @var{command} in a ++set of keymaps. ++ ++The argument @var{command} can be any object; it is compared with all ++keymap entries using @code{eq}. ++ ++If @var{keymap} is @code{nil}, then the maps used are the current active ++keymaps, disregarding @code{overriding-local-map} (that is, pretending ++its value is @code{nil}). If @var{keymap} is a keymap, then the ++maps searched are @var{keymap} and the global keymap. If @var{keymap} ++is a list of keymaps, only those keymaps are searched. ++ ++Usually it's best to use @code{overriding-local-map} as the expression ++for @var{keymap}. Then @code{where-is-internal} searches precisely the ++keymaps that are active. To search only the global map, pass ++@code{(keymap)} (an empty keymap) as @var{keymap}. ++ ++If @var{firstonly} is @code{non-ascii}, then the value is a single ++vector representing the first key sequence found, rather than a list of ++all possible key sequences. If @var{firstonly} is @code{t}, then the ++value is the first key sequence, except that key sequences consisting ++entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} ++characters) are preferred to all other key sequences and that the ++return value can never be a menu binding. ++ ++If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't ++follow indirect keymap bindings. This makes it possible to search for ++an indirect definition itself. ++ ++When command remapping is in effect (@pxref{Remapping Commands}), ++@code{where-is-internal} figures out when a command will be run due to ++remapping and reports keys accordingly. It also returns @code{nil} if ++@var{command} won't really be run because it has been remapped to some ++other command. However, if @var{no-remap} is non-@code{nil}. ++@code{where-is-internal} ignores remappings. ++ ++@smallexample ++@group ++(where-is-internal 'describe-function) ++ @result{} ([8 102] [f1 102] [help 102] ++ [menu-bar help-menu describe describe-function]) ++@end group ++@end smallexample ++@end defun ++ ++@deffn Command describe-bindings &optional prefix buffer-or-name ++This function creates a listing of all current key bindings, and ++displays it in a buffer named @samp{*Help*}. The text is grouped by ++modes---minor modes first, then the major mode, then global bindings. ++ ++If @var{prefix} is non-@code{nil}, it should be a prefix key; then the ++listing includes only keys that start with @var{prefix}. ++ ++The listing describes meta characters as @key{ESC} followed by the ++corresponding non-meta character. ++ ++When several characters with consecutive @acronym{ASCII} codes have the ++same definition, they are shown together, as ++@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to ++know the @acronym{ASCII} codes to understand which characters this means. ++For example, in the default global map, the characters @samp{@key{SPC} ++..@: ~} are described by a single line. @key{SPC} is @acronym{ASCII} 32, ++@kbd{~} is @acronym{ASCII} 126, and the characters between them include all ++the normal printing characters, (e.g., letters, digits, punctuation, ++etc.@:); all these characters are bound to @code{self-insert-command}. ++ ++If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a ++buffer name. Then @code{describe-bindings} lists that buffer's bindings, ++instead of the current buffer's. ++@end deffn ++ ++@node Menu Keymaps ++@section Menu Keymaps ++@cindex menu keymaps ++ ++A keymap can operate as a menu as well as defining bindings for ++keyboard keys and mouse buttons. Menus are usually actuated with the ++mouse, but they can function with the keyboard also. If a menu keymap ++is active for the next input event, that activates the keyboard menu ++feature. ++ ++@menu ++* Defining Menus:: How to make a keymap that defines a menu. ++* Mouse Menus:: How users actuate the menu with the mouse. ++* Keyboard Menus:: How users actuate the menu with the keyboard. ++* Menu Example:: Making a simple menu. ++* Menu Bar:: How to customize the menu bar. ++* Tool Bar:: A tool bar is a row of images. ++* Modifying Menus:: How to add new items to a menu. ++@end menu ++ ++@node Defining Menus ++@subsection Defining Menus ++@cindex defining menus ++@cindex menu prompt string ++@cindex prompt string (of menu) ++ ++A keymap acts as a menu if it has an @dfn{overall prompt string}, ++which is a string that appears as an element of the keymap. ++(@xref{Format of Keymaps}.) The string should describe the purpose of ++the menu's commands. Emacs displays the overall prompt string as the ++menu title in some cases, depending on the toolkit (if any) used for ++displaying menus.@footnote{It is required for menus which do not use a ++toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the ++overall prompt string. ++ ++The easiest way to construct a keymap with a prompt string is to ++specify the string as an argument when you call @code{make-keymap}, ++@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or ++@code{define-prefix-command} (@pxref{Definition of ++define-prefix-command}). If you do not want the keymap to operate as ++a menu, don't specify a prompt string for it. ++ ++@defun keymap-prompt keymap ++This function returns the overall prompt string of @var{keymap}, ++or @code{nil} if it has none. ++@end defun ++ ++The menu's items are the bindings in the keymap. Each binding ++associates an event type to a definition, but the event types have no ++significance for the menu appearance. (Usually we use pseudo-events, ++symbols that the keyboard cannot generate, as the event types for menu ++item bindings.) The menu is generated entirely from the bindings that ++correspond in the keymap to these events. ++ ++The order of items in the menu is the same as the order of bindings in ++the keymap. Since @code{define-key} puts new bindings at the front, you ++should define the menu items starting at the bottom of the menu and ++moving to the top, if you care about the order. When you add an item to ++an existing menu, you can specify its position in the menu using ++@code{define-key-after} (@pxref{Modifying Menus}). ++ ++@menu ++* Simple Menu Items:: A simple kind of menu key binding, ++ limited in capabilities. ++* Extended Menu Items:: More powerful menu item definitions ++ let you specify keywords to enable ++ various features. ++* Menu Separators:: Drawing a horizontal line through a menu. ++* Alias Menu Items:: Using command aliases in menu items. ++@end menu ++ ++@node Simple Menu Items ++@subsubsection Simple Menu Items ++ ++ The simpler (and original) way to define a menu item is to bind some ++event type (it doesn't matter what event type) to a binding like this: ++ ++@example ++(@var{item-string} . @var{real-binding}) ++@end example ++ ++@noindent ++The @sc{car}, @var{item-string}, is the string to be displayed in the ++menu. It should be short---preferably one to three words. It should ++describe the action of the command it corresponds to. Note that it is ++not generally possible to display non-@acronym{ASCII} text in menus. It will ++work for keyboard menus and will work to a large extent when Emacs is ++built with the Gtk+ toolkit.@footnote{In this case, the text is first ++encoded using the @code{utf-8} coding system and then rendered by the ++toolkit as it sees fit.} ++ ++ You can also supply a second string, called the help string, as follows: ++ ++@example ++(@var{item-string} @var{help} . @var{real-binding}) ++@end example ++ ++@noindent ++@var{help} specifies a ``help-echo'' string to display while the mouse ++is on that item in the same way as @code{help-echo} text properties ++(@pxref{Help display}). ++ ++ As far as @code{define-key} is concerned, @var{item-string} and ++@var{help-string} are part of the event's binding. However, ++@code{lookup-key} returns just @var{real-binding}, and only ++@var{real-binding} is used for executing the key. ++ ++ If @var{real-binding} is @code{nil}, then @var{item-string} appears in ++the menu but cannot be selected. ++ ++ If @var{real-binding} is a symbol and has a non-@code{nil} ++@code{menu-enable} property, that property is an expression that ++controls whether the menu item is enabled. Every time the keymap is ++used to display a menu, Emacs evaluates the expression, and it enables ++the menu item only if the expression's value is non-@code{nil}. When a ++menu item is disabled, it is displayed in a ``fuzzy'' fashion, and ++cannot be selected. ++ ++ The menu bar does not recalculate which items are enabled every time you ++look at a menu. This is because the X toolkit requires the whole tree ++of menus in advance. To force recalculation of the menu bar, call ++@code{force-mode-line-update} (@pxref{Mode Line Format}). ++ ++ You've probably noticed that menu items show the equivalent keyboard key ++sequence (if any) to invoke the same command. To save time on ++recalculation, menu display caches this information in a sublist in the ++binding, like this: ++ ++@c This line is not too long--rms. ++@example ++(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding}) ++@end example ++ ++@noindent ++Don't put these sublists in the menu item yourself; menu display ++calculates them automatically. Don't mention keyboard equivalents in ++the item strings themselves, since that is redundant. ++ ++@node Extended Menu Items ++@subsubsection Extended Menu Items ++@kindex menu-item ++ ++ An extended-format menu item is a more flexible and also cleaner ++alternative to the simple format. You define an event type with a ++binding that's a list starting with the symbol @code{menu-item}. ++For a non-selectable string, the binding looks like this: ++ ++@example ++(menu-item @var{item-name}) ++@end example ++ ++@noindent ++A string starting with two or more dashes specifies a separator line; ++see @ref{Menu Separators}. ++ ++ To define a real menu item which can be selected, the extended format ++binding looks like this: ++ ++@example ++(menu-item @var{item-name} @var{real-binding} ++ . @var{item-property-list}) ++@end example ++ ++@noindent ++Here, @var{item-name} is an expression which evaluates to the menu item ++string. Thus, the string need not be a constant. The third element, ++@var{real-binding}, is the command to execute. The tail of the list, ++@var{item-property-list}, has the form of a property list which contains ++other information. ++ ++ When an equivalent keyboard key binding is cached, the extended menu ++item binding looks like this: ++ ++@example ++(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data}) ++ . @var{item-property-list}) ++@end example ++ ++ Here is a table of the properties that are supported: ++ ++@table @code ++@item :enable @var{form} ++The result of evaluating @var{form} determines whether the item is ++enabled (non-@code{nil} means yes). If the item is not enabled, ++you can't really click on it. ++ ++@item :visible @var{form} ++The result of evaluating @var{form} determines whether the item should ++actually appear in the menu (non-@code{nil} means yes). If the item ++does not appear, then the menu is displayed as if this item were ++not defined at all. ++ ++@item :help @var{help} ++The value of this property, @var{help}, specifies a ``help-echo'' string ++to display while the mouse is on that item. This is displayed in the ++same way as @code{help-echo} text properties (@pxref{Help display}). ++Note that this must be a constant string, unlike the @code{help-echo} ++property for text and overlays. ++ ++@item :button (@var{type} . @var{selected}) ++This property provides a way to define radio buttons and toggle buttons. ++The @sc{car}, @var{type}, says which: it should be @code{:toggle} or ++@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the ++result of evaluating it says whether this button is currently selected. ++ ++A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off'' ++according to the value of @var{selected}. The command itself should ++toggle @var{selected}, setting it to @code{t} if it is @code{nil}, ++and to @code{nil} if it is @code{t}. Here is how the menu item ++to toggle the @code{debug-on-error} flag is defined: ++ ++@example ++(menu-item "Debug on Error" toggle-debug-on-error ++ :button (:toggle ++ . (and (boundp 'debug-on-error) ++ debug-on-error))) ++@end example ++ ++@noindent ++This works because @code{toggle-debug-on-error} is defined as a command ++which toggles the variable @code{debug-on-error}. ++ ++@dfn{Radio buttons} are a group of menu items, in which at any time one ++and only one is ``selected.'' There should be a variable whose value ++says which one is selected at any time. The @var{selected} form for ++each radio button in the group should check whether the variable has the ++right value for selecting that button. Clicking on the button should ++set the variable so that the button you clicked on becomes selected. ++ ++@item :key-sequence @var{key-sequence} ++This property specifies which key sequence is likely to be bound to the ++same command invoked by this menu item. If you specify the right key ++sequence, that makes preparing the menu for display run much faster. ++ ++If you specify the wrong key sequence, it has no effect; before Emacs ++displays @var{key-sequence} in the menu, it verifies that ++@var{key-sequence} is really equivalent to this menu item. ++ ++@item :key-sequence nil ++This property indicates that there is normally no key binding which is ++equivalent to this menu item. Using this property saves time in ++preparing the menu for display, because Emacs does not need to search ++the keymaps for a keyboard equivalent for this menu item. ++ ++However, if the user has rebound this item's definition to a key ++sequence, Emacs ignores the @code{:keys} property and finds the keyboard ++equivalent anyway. ++ ++@item :keys @var{string} ++This property specifies that @var{string} is the string to display ++as the keyboard equivalent for this menu item. You can use ++the @samp{\\[...]} documentation construct in @var{string}. ++ ++@item :filter @var{filter-fn} ++This property provides a way to compute the menu item dynamically. ++The property value @var{filter-fn} should be a function of one argument; ++when it is called, its argument will be @var{real-binding}. The ++function should return the binding to use instead. ++ ++Emacs can call this function at any time that it does redisplay or ++operates on menu data structures, so you should write it so it can ++safely be called at any time. ++@end table ++ ++@node Menu Separators ++@subsubsection Menu Separators ++@cindex menu separators ++ ++ A menu separator is a kind of menu item that doesn't display any ++text---instead, it divides the menu into subparts with a horizontal line. ++A separator looks like this in the menu keymap: ++ ++@example ++(menu-item @var{separator-type}) ++@end example ++ ++@noindent ++where @var{separator-type} is a string starting with two or more dashes. ++ ++ In the simplest case, @var{separator-type} consists of only dashes. ++That specifies the default kind of separator. (For compatibility, ++@code{""} and @code{-} also count as separators.) ++ ++ Certain other values of @var{separator-type} specify a different ++style of separator. Here is a table of them: ++ ++@table @code ++@item "--no-line" ++@itemx "--space" ++An extra vertical space, with no actual line. ++ ++@item "--single-line" ++A single line in the menu's foreground color. ++ ++@item "--double-line" ++A double line in the menu's foreground color. ++ ++@item "--single-dashed-line" ++A single dashed line in the menu's foreground color. ++ ++@item "--double-dashed-line" ++A double dashed line in the menu's foreground color. ++ ++@item "--shadow-etched-in" ++A single line with a 3D sunken appearance. This is the default, ++used separators consisting of dashes only. ++ ++@item "--shadow-etched-out" ++A single line with a 3D raised appearance. ++ ++@item "--shadow-etched-in-dash" ++A single dashed line with a 3D sunken appearance. ++ ++@item "--shadow-etched-out-dash" ++A single dashed line with a 3D raised appearance. ++ ++@item "--shadow-double-etched-in" ++Two lines with a 3D sunken appearance. ++ ++@item "--shadow-double-etched-out" ++Two lines with a 3D raised appearance. ++ ++@item "--shadow-double-etched-in-dash" ++Two dashed lines with a 3D sunken appearance. ++ ++@item "--shadow-double-etched-out-dash" ++Two dashed lines with a 3D raised appearance. ++@end table ++ ++ You can also give these names in another style, adding a colon after ++the double-dash and replacing each single dash with capitalization of ++the following word. Thus, @code{"--:singleLine"}, is equivalent to ++@code{"--single-line"}. ++ ++ Some systems and display toolkits don't really handle all of these ++separator types. If you use a type that isn't supported, the menu ++displays a similar kind of separator that is supported. ++ ++@node Alias Menu Items ++@subsubsection Alias Menu Items ++ ++ Sometimes it is useful to make menu items that use the ``same'' ++command but with different enable conditions. The best way to do this ++in Emacs now is with extended menu items; before that feature existed, ++it could be done by defining alias commands and using them in menu ++items. Here's an example that makes two aliases for ++@code{toggle-read-only} and gives them different enable conditions: ++ ++@example ++(defalias 'make-read-only 'toggle-read-only) ++(put 'make-read-only 'menu-enable '(not buffer-read-only)) ++(defalias 'make-writable 'toggle-read-only) ++(put 'make-writable 'menu-enable 'buffer-read-only) ++@end example ++ ++When using aliases in menus, often it is useful to display the ++equivalent key bindings for the ``real'' command name, not the aliases ++(which typically don't have any key bindings except for the menu ++itself). To request this, give the alias symbol a non-@code{nil} ++@code{menu-alias} property. Thus, ++ ++@example ++(put 'make-read-only 'menu-alias t) ++(put 'make-writable 'menu-alias t) ++@end example ++ ++@noindent ++causes menu items for @code{make-read-only} and @code{make-writable} to ++show the keyboard bindings for @code{toggle-read-only}. ++ ++@node Mouse Menus ++@subsection Menus and the Mouse ++ ++ The usual way to make a menu keymap produce a menu is to make it the ++definition of a prefix key. (A Lisp program can explicitly pop up a ++menu and receive the user's choice---see @ref{Pop-Up Menus}.) ++ ++ If the prefix key ends with a mouse event, Emacs handles the menu keymap ++by popping up a visible menu, so that the user can select a choice with ++the mouse. When the user clicks on a menu item, the event generated is ++whatever character or symbol has the binding that brought about that ++menu item. (A menu item may generate a series of events if the menu has ++multiple levels or comes from the menu bar.) ++ ++ It's often best to use a button-down event to trigger the menu. Then ++the user can select a menu item by releasing the button. ++ ++ A single keymap can appear as multiple menu panes, if you explicitly ++arrange for this. The way to do this is to make a keymap for each pane, ++then create a binding for each of those maps in the main keymap of the ++menu. Give each of these bindings an item string that starts with ++@samp{@@}. The rest of the item string becomes the name of the pane. ++See the file @file{lisp/mouse.el} for an example of this. Any ordinary ++bindings with @samp{@@}-less item strings are grouped into one pane, ++which appears along with the other panes explicitly created for the ++submaps. ++ ++ X toolkit menus don't have panes; instead, they can have submenus. ++Every nested keymap becomes a submenu, whether the item string starts ++with @samp{@@} or not. In a toolkit version of Emacs, the only thing ++special about @samp{@@} at the beginning of an item string is that the ++@samp{@@} doesn't appear in the menu item. ++ ++ Multiple keymaps that define the same menu prefix key produce ++separate panes or separate submenus. ++ ++@node Keyboard Menus ++@subsection Menus and the Keyboard ++ ++ When a prefix key ending with a keyboard event (a character or ++function key) has a definition that is a menu keymap, the keymap ++operates as a keyboard menu; the user specifies the next event by ++choosing a menu item with the keyboard. ++ ++ Emacs displays the keyboard menu with the map's overall prompt ++string, followed by the alternatives (the item strings of the map's ++bindings), in the echo area. If the bindings don't all fit at once, ++the user can type @key{SPC} to see the next line of alternatives. ++Successive uses of @key{SPC} eventually get to the end of the menu and ++then cycle around to the beginning. (The variable ++@code{menu-prompt-more-char} specifies which character is used for ++this; @key{SPC} is the default.) ++ ++ When the user has found the desired alternative from the menu, he or ++she should type the corresponding character---the one whose binding is ++that alternative. ++ ++@ignore ++In a menu intended for keyboard use, each menu item must clearly ++indicate what character to type. The best convention to use is to make ++the character the first letter of the item string---that is something ++users will understand without being told. We plan to change this; by ++the time you read this manual, keyboard menus may explicitly name the ++key for each alternative. ++@end ignore ++ ++ This way of using menus in an Emacs-like editor was inspired by the ++Hierarkey system. ++ ++@defvar menu-prompt-more-char ++This variable specifies the character to use to ask to see ++the next line of a menu. Its initial value is 32, the code ++for @key{SPC}. ++@end defvar ++ ++@node Menu Example ++@subsection Menu Example ++@cindex menu definition example ++ ++ Here is a complete example of defining a menu keymap. It is the ++definition of the @samp{Replace} submenu in the @samp{Edit} menu in ++the menu bar, and it uses the extended menu item format ++(@pxref{Extended Menu Items}). First we create the keymap, and give ++it a name: ++ ++@smallexample ++(defvar menu-bar-replace-menu (make-sparse-keymap "Replace")) ++@end smallexample ++ ++@noindent ++Next we define the menu items: ++ ++@smallexample ++(define-key menu-bar-replace-menu [tags-repl-continue] ++ '(menu-item "Continue Replace" tags-loop-continue ++ :help "Continue last tags replace operation")) ++(define-key menu-bar-replace-menu [tags-repl] ++ '(menu-item "Replace in tagged files" tags-query-replace ++ :help "Interactively replace a regexp in all tagged files")) ++(define-key menu-bar-replace-menu [separator-replace-tags] ++ '(menu-item "--")) ++;; @r{@dots{}} ++@end smallexample ++ ++@noindent ++Note the symbols which the bindings are ``made for''; these appear ++inside square brackets, in the key sequence being defined. In some ++cases, this symbol is the same as the command name; sometimes it is ++different. These symbols are treated as ``function keys,'' but they are ++not real function keys on the keyboard. They do not affect the ++functioning of the menu itself, but they are ``echoed'' in the echo area ++when the user selects from the menu, and they appear in the output of ++@code{where-is} and @code{apropos}. ++ ++ The menu in this example is intended for use with the mouse. If a ++menu is intended for use with the keyboard, that is, if it is bound to ++a key sequence ending with a keyboard event, then the menu items ++should be bound to characters or ``real'' function keys, that can be ++typed with the keyboard. ++ ++ The binding whose definition is @code{("--")} is a separator line. ++Like a real menu item, the separator has a key symbol, in this case ++@code{separator-replace-tags}. If one menu has two separators, they ++must have two different key symbols. ++ ++ Here is how we make this menu appear as an item in the parent menu: ++ ++@example ++(define-key menu-bar-edit-menu [replace] ++ (list 'menu-item "Replace" menu-bar-replace-menu)) ++@end example ++ ++@noindent ++Note that this incorporates the submenu keymap, which is the value of ++the variable @code{menu-bar-replace-menu}, rather than the symbol ++@code{menu-bar-replace-menu} itself. Using that symbol in the parent ++menu item would be meaningless because @code{menu-bar-replace-menu} is ++not a command. ++ ++ If you wanted to attach the same replace menu to a mouse click, you ++can do it this way: ++ ++@example ++(define-key global-map [C-S-down-mouse-1] ++ menu-bar-replace-menu) ++@end example ++ ++@node Menu Bar ++@subsection The Menu Bar ++@cindex menu bar ++ ++ Most window systems allow each frame to have a @dfn{menu bar}---a ++permanently displayed menu stretching horizontally across the top of the ++frame. The items of the menu bar are the subcommands of the fake ++``function key'' @code{menu-bar}, as defined in the active keymaps. ++ ++ To add an item to the menu bar, invent a fake ``function key'' of your ++own (let's call it @var{key}), and make a binding for the key sequence ++@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap, ++so that pressing a button on the menu bar item leads to another menu. ++ ++ When more than one active keymap defines the same fake function key ++for the menu bar, the item appears just once. If the user clicks on ++that menu bar item, it brings up a single, combined menu containing ++all the subcommands of that item---the global subcommands, the local ++subcommands, and the minor mode subcommands. ++ ++ The variable @code{overriding-local-map} is normally ignored when ++determining the menu bar contents. That is, the menu bar is computed ++from the keymaps that would be active if @code{overriding-local-map} ++were @code{nil}. @xref{Active Keymaps}. ++ ++ In order for a frame to display a menu bar, its @code{menu-bar-lines} ++parameter must be greater than zero. Emacs uses just one line for the ++menu bar itself; if you specify more than one line, the other lines ++serve to separate the menu bar from the windows in the frame. We ++recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout ++Parameters}. ++ ++ Here's an example of setting up a menu bar item: ++ ++@example ++@group ++(modify-frame-parameters (selected-frame) ++ '((menu-bar-lines . 2))) ++@end group ++ ++@group ++;; @r{Make a menu keymap (with a prompt string)} ++;; @r{and make it the menu bar item's definition.} ++(define-key global-map [menu-bar words] ++ (cons "Words" (make-sparse-keymap "Words"))) ++@end group ++ ++@group ++;; @r{Define specific subcommands in this menu.} ++(define-key global-map ++ [menu-bar words forward] ++ '("Forward word" . forward-word)) ++@end group ++@group ++(define-key global-map ++ [menu-bar words backward] ++ '("Backward word" . backward-word)) ++@end group ++@end example ++ ++ A local keymap can cancel a menu bar item made by the global keymap by ++rebinding the same fake function key with @code{undefined} as the ++binding. For example, this is how Dired suppresses the @samp{Edit} menu ++bar item: ++ ++@example ++(define-key dired-mode-map [menu-bar edit] 'undefined) ++@end example ++ ++@noindent ++@code{edit} is the fake function key used by the global map for the ++@samp{Edit} menu bar item. The main reason to suppress a global ++menu bar item is to regain space for mode-specific items. ++ ++@defvar menu-bar-final-items ++Normally the menu bar shows global items followed by items defined by the ++local maps. ++ ++This variable holds a list of fake function keys for items to display at ++the end of the menu bar rather than in normal sequence. The default ++value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears ++at the end of the menu bar, following local menu items. ++@end defvar ++ ++@defvar menu-bar-update-hook ++This normal hook is run by redisplay to update the menu bar contents, ++before redisplaying the menu bar. You can use it to update submenus ++whose contents should vary. Since this hook is run frequently, we ++advise you to ensure that the functions it calls do not take much time ++in the usual case. ++@end defvar ++ ++@node Tool Bar ++@subsection Tool bars ++@cindex tool bar ++ ++ A @dfn{tool bar} is a row of icons at the top of a frame, that execute ++commands when you click on them---in effect, a kind of graphical menu ++bar. ++ ++ The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar}) ++controls how many lines' worth of height to reserve for the tool bar. A ++zero value suppresses the tool bar. If the value is nonzero, and ++@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and ++contracts automatically as needed to hold the specified contents. ++ ++ If the value of @code{auto-resize-tool-bars} is @code{grow-only}, ++the tool bar expands automatically, but does not contract automatically. ++To contract the tool bar, the user has to redraw the frame by entering ++@kbd{C-l}. ++ ++ The tool bar contents are controlled by a menu keymap attached to a ++fake ``function key'' called @code{tool-bar} (much like the way the menu ++bar is controlled). So you define a tool bar item using ++@code{define-key}, like this: ++ ++@example ++(define-key global-map [tool-bar @var{key}] @var{item}) ++@end example ++ ++@noindent ++where @var{key} is a fake ``function key'' to distinguish this item from ++other items, and @var{item} is a menu item key binding (@pxref{Extended ++Menu Items}), which says how to display this item and how it behaves. ++ ++ The usual menu keymap item properties, @code{:visible}, ++@code{:enable}, @code{:button}, and @code{:filter}, are useful in ++tool bar bindings and have their normal meanings. The @var{real-binding} ++in the item must be a command, not a keymap; in other words, it does not ++work to define a tool bar icon as a prefix key. ++ ++ The @code{:help} property specifies a ``help-echo'' string to display ++while the mouse is on that item. This is displayed in the same way as ++@code{help-echo} text properties (@pxref{Help display}). ++ ++ In addition, you should use the @code{:image} property; ++this is how you specify the image to display in the tool bar: ++ ++@table @code ++@item :image @var{image} ++@var{images} is either a single image specification or a vector of four ++image specifications. If you use a vector of four, ++one of them is used, depending on circumstances: ++ ++@table @asis ++@item item 0 ++Used when the item is enabled and selected. ++@item item 1 ++Used when the item is enabled and deselected. ++@item item 2 ++Used when the item is disabled and selected. ++@item item 3 ++Used when the item is disabled and deselected. ++@end table ++@end table ++ ++If @var{image} is a single image specification, Emacs draws the tool bar ++button in disabled state by applying an edge-detection algorithm to the ++image. ++ ++The @code{:rtl} property specifies an alternative image to use for ++right-to-left languages. Only the Gtk+ version of Emacs supports this ++at present. ++ ++The default tool bar is defined so that items specific to editing do not ++appear for major modes whose command symbol has a @code{mode-class} ++property of @code{special} (@pxref{Major Mode Conventions}). Major ++modes may add items to the global bar by binding @code{[tool-bar ++@var{foo}]} in their local map. It makes sense for some major modes to ++replace the default tool bar items completely, since not many can be ++accommodated conveniently, and the default bindings make this easy by ++using an indirection through @code{tool-bar-map}. ++ ++@defvar tool-bar-map ++By default, the global map binds @code{[tool-bar]} as follows: ++@example ++(global-set-key [tool-bar] ++ '(menu-item "tool bar" ignore ++ :filter (lambda (ignore) tool-bar-map))) ++@end example ++@noindent ++Thus the tool bar map is derived dynamically from the value of variable ++@code{tool-bar-map} and you should normally adjust the default (global) ++tool bar by changing that map. Major modes may replace the global bar ++completely by making @code{tool-bar-map} buffer-local and set to a ++keymap containing only the desired items. Info mode provides an ++example. ++@end defvar ++ ++There are two convenience functions for defining tool bar items, as ++follows. ++ ++@defun tool-bar-add-item icon def key &rest props ++This function adds an item to the tool bar by modifying ++@code{tool-bar-map}. The image to use is defined by @var{icon}, which ++is the base name of an XPM, XBM or PBM image file to be located by ++@code{find-image}. Given a value @samp{"exit"}, say, @file{exit.xpm}, ++@file{exit.pbm} and @file{exit.xbm} would be searched for in that order ++on a color display. On a monochrome display, the search order is ++@samp{.pbm}, @samp{.xbm} and @samp{.xpm}. The binding to use is the ++command @var{def}, and @var{key} is the fake function key symbol in the ++prefix keymap. The remaining arguments @var{props} are additional ++property list elements to add to the menu item specification. ++ ++To define items in some local map, bind @code{tool-bar-map} with ++@code{let} around calls of this function: ++@example ++(defvar foo-tool-bar-map ++ (let ((tool-bar-map (make-sparse-keymap))) ++ (tool-bar-add-item @dots{}) ++ @dots{} ++ tool-bar-map)) ++@end example ++@end defun ++ ++@defun tool-bar-add-item-from-menu command icon &optional map &rest props ++This function is a convenience for defining tool bar items which are ++consistent with existing menu bar bindings. The binding of ++@var{command} is looked up in the menu bar in @var{map} (default ++@code{global-map}) and modified to add an image specification for ++@var{icon}, which is found in the same way as by ++@code{tool-bar-add-item}. The resulting binding is then placed in ++@code{tool-bar-map}, so use this function only for global tool bar ++items. ++ ++@var{map} must contain an appropriate keymap bound to ++@code{[menu-bar]}. The remaining arguments @var{props} are additional ++property list elements to add to the menu item specification. ++@end defun ++ ++@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props ++This function is used for making non-global tool bar items. Use it ++like @code{tool-bar-add-item-from-menu} except that @var{in-map} ++specifies the local map to make the definition in. The argument ++@var{from-map} is like the @var{map} argument of ++@code{tool-bar-add-item-from-menu}. ++@end defun ++ ++@defvar auto-resize-tool-bars ++If this variable is non-@code{nil}, the tool bar automatically resizes to ++show all defined tool bar items---but not larger than a quarter of the ++frame's height. ++ ++If the value is @code{grow-only}, the tool bar expands automatically, ++but does not contract automatically. To contract the tool bar, the ++user has to redraw the frame by entering @kbd{C-l}. ++ ++If Emacs is built with GTK or Nextstep, the tool bar can only show one ++line, so this variable has no effect. ++@end defvar ++ ++@defvar auto-raise-tool-bar-buttons ++If this variable is non-@code{nil}, tool bar items display ++in raised form when the mouse moves over them. ++@end defvar ++ ++@defvar tool-bar-button-margin ++This variable specifies an extra margin to add around tool bar items. ++The value is an integer, a number of pixels. The default is 4. ++@end defvar ++ ++@defvar tool-bar-button-relief ++This variable specifies the shadow width for tool bar items. ++The value is an integer, a number of pixels. The default is 1. ++@end defvar ++ ++@defvar tool-bar-border ++This variable specifies the height of the border drawn below the tool ++bar area. An integer value specifies height as a number of pixels. ++If the value is one of @code{internal-border-width} (the default) or ++@code{border-width}, the tool bar border height corresponds to the ++corresponding frame parameter. ++@end defvar ++ ++ You can define a special meaning for clicking on a tool bar item with ++the shift, control, meta, etc., modifiers. You do this by setting up ++additional items that relate to the original item through the fake ++function keys. Specifically, the additional items should use the ++modified versions of the same fake function key used to name the ++original item. ++ ++ Thus, if the original item was defined this way, ++ ++@example ++(define-key global-map [tool-bar shell] ++ '(menu-item "Shell" shell ++ :image (image :type xpm :file "shell.xpm"))) ++@end example ++ ++@noindent ++then here is how you can define clicking on the same tool bar image with ++the shift modifier: ++ ++@example ++(define-key global-map [tool-bar S-shell] 'some-command) ++@end example ++ ++@xref{Function Keys}, for more information about how to add modifiers to ++function keys. ++ ++@node Modifying Menus ++@subsection Modifying Menus ++ ++ When you insert a new item in an existing menu, you probably want to ++put it in a particular place among the menu's existing items. If you ++use @code{define-key} to add the item, it normally goes at the front of ++the menu. To put it elsewhere in the menu, use @code{define-key-after}: ++ ++@defun define-key-after map key binding &optional after ++Define a binding in @var{map} for @var{key}, with value @var{binding}, ++just like @code{define-key}, but position the binding in @var{map} after ++the binding for the event @var{after}. The argument @var{key} should be ++of length one---a vector or string with just one element. But ++@var{after} should be a single event type---a symbol or a character, not ++a sequence. The new binding goes after the binding for @var{after}. If ++@var{after} is @code{t} or is omitted, then the new binding goes last, at ++the end of the keymap. However, new bindings are added before any ++inherited keymap. ++ ++Here is an example: ++ ++@example ++(define-key-after my-menu [drink] ++ '("Drink" . drink-command) 'eat) ++@end example ++ ++@noindent ++makes a binding for the fake function key @key{DRINK} and puts it ++right after the binding for @key{EAT}. ++ ++Here is how to insert an item called @samp{Work} in the @samp{Signals} ++menu of Shell mode, after the item @code{break}: ++ ++@example ++(define-key-after ++ (lookup-key shell-mode-map [menu-bar signals]) ++ [work] '("Work" . work-command) 'break) ++@end example ++@end defun ++ ++@ignore ++ arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794 ++@end ignore +diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi +new file mode 100644 +index 0000000..64854e9 +--- /dev/null ++++ b/doc/lispref/lay-flat.texi +@@ -0,0 +1,48 @@ ++\input texinfo @c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@c ++@comment %**start of header ++@setfilename inner-covers.info ++@settitle Inner Covers ++@smallbook ++@comment %**end of header ++ ++@headings off ++ ++@w{ } ++@sp 4 ++@tex ++\center {\secfonts \rm Lay-Flat Binding} ++@end tex ++@sp 2 ++ ++We have bound this manual using a new @dfn{lay-flat} binding ++technology. This type of binding allows you to open a soft cover book ++so that it ``lays flat'' on a table without creasing the binding. ++ ++In order to make the book lay flat properly, you need to ``crack'' the ++binding. To do this, divide the book into two sections and bend it so ++that the front and back covers meet. Do not worry; the pages are ++sewn and glued to the binding, and will not fall out easily. ++The outer cardboard binding itself is designed so that it will not ++break or crease as an ordinary paperback binding will. Bend the book ++several times in this manner, dividing it in a different place each ++time and pressing the pages flat and open. With use, the binding will ++become flexible and the pages will lay flat without needing to be ++pushed or held down. ++ ++@page ++ ++ ++@tex ++\center {\secfonts \rm Notes} ++@end tex ++ ++@bye ++ ++@ignore ++ arch-tag: 9e03a1c7-6f62-4346-85d9-ed5b79386e07 ++@end ignore +diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi +new file mode 100644 +index 0000000..d38cdc1 +--- /dev/null ++++ b/doc/lispref/lists.texi +@@ -0,0 +1,1894 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/lists ++@node Lists, Sequences Arrays Vectors, Strings and Characters, Top ++@chapter Lists ++@cindex lists ++@cindex element (of list) ++ ++ A @dfn{list} represents a sequence of zero or more elements (which may ++be any Lisp objects). The important difference between lists and ++vectors is that two or more lists can share part of their structure; in ++addition, you can insert or delete elements in a list without copying ++the whole list. ++ ++@menu ++* Cons Cells:: How lists are made out of cons cells. ++* List-related Predicates:: Is this object a list? Comparing two lists. ++* List Elements:: Extracting the pieces of a list. ++* Building Lists:: Creating list structure. ++* List Variables:: Modifying lists stored in variables. ++* Modifying Lists:: Storing new pieces into an existing list. ++* Sets And Lists:: A list can represent a finite mathematical set. ++* Association Lists:: A list can represent a finite relation or mapping. ++* Rings:: Managing a fixed-size ring of objects. ++@end menu ++ ++@node Cons Cells ++@section Lists and Cons Cells ++@cindex lists and cons cells ++ ++ Lists in Lisp are not a primitive data type; they are built up from ++@dfn{cons cells}. A cons cell is a data object that represents an ++ordered pair. That is, it has two slots, and each slot @dfn{holds}, or ++@dfn{refers to}, some Lisp object. One slot is known as the @sc{car}, ++and the other is known as the @sc{cdr}. (These names are traditional; ++see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.'' ++ ++ We say that ``the @sc{car} of this cons cell is'' whatever object ++its @sc{car} slot currently holds, and likewise for the @sc{cdr}. ++ ++ A list is a series of cons cells ``chained together,'' so that each ++cell refers to the next one. There is one cons cell for each element of ++the list. By convention, the @sc{car}s of the cons cells hold the ++elements of the list, and the @sc{cdr}s are used to chain the list: the ++@sc{cdr} slot of each cons cell refers to the following cons cell. The ++@sc{cdr} of the last cons cell is @code{nil}. This asymmetry between ++the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the ++level of cons cells, the @sc{car} and @sc{cdr} slots have the same ++characteristics. ++ ++@cindex true list ++ Since @code{nil} is the conventional value to put in the @sc{cdr} of ++the last cons cell in the list, we call that case a @dfn{true list}. ++ ++ In Lisp, we consider the symbol @code{nil} a list as well as a ++symbol; it is the list with no elements. For convenience, the symbol ++@code{nil} is considered to have @code{nil} as its @sc{cdr} (and also ++as its @sc{car}). Therefore, the @sc{cdr} of a true list is always a ++true list. ++ ++@cindex dotted list ++@cindex circular list ++ If the @sc{cdr} of a list's last cons cell is some other value, ++neither @code{nil} nor another cons cell, we call the structure a ++@dfn{dotted list}, since its printed representation would use ++@samp{.}. There is one other possibility: some cons cell's @sc{cdr} ++could point to one of the previous cons cells in the list. We call ++that structure a @dfn{circular list}. ++ ++ For some purposes, it does not matter whether a list is true, ++circular or dotted. If the program doesn't look far enough down the ++list to see the @sc{cdr} of the final cons cell, it won't care. ++However, some functions that operate on lists demand true lists and ++signal errors if given a dotted list. Most functions that try to find ++the end of a list enter infinite loops if given a circular list. ++ ++@cindex list structure ++ Because most cons cells are used as part of lists, the phrase ++@dfn{list structure} has come to mean any structure made out of cons ++cells. ++ ++ The @sc{cdr} of any nonempty true list @var{l} is a list containing all the ++elements of @var{l} except the first. ++ ++ @xref{Cons Cell Type}, for the read and print syntax of cons cells and ++lists, and for ``box and arrow'' illustrations of lists. ++ ++@node List-related Predicates ++@section Predicates on Lists ++ ++ The following predicates test whether a Lisp object is an atom, ++whether it is a cons cell or is a list, or whether it is the ++distinguished object @code{nil}. (Many of these predicates can be ++defined in terms of the others, but they are used so often that it is ++worth having all of them.) ++ ++@defun consp object ++This function returns @code{t} if @var{object} is a cons cell, @code{nil} ++otherwise. @code{nil} is not a cons cell, although it @emph{is} a list. ++@end defun ++ ++@defun atom object ++This function returns @code{t} if @var{object} is an atom, @code{nil} ++otherwise. All objects except cons cells are atoms. The symbol ++@code{nil} is an atom and is also a list; it is the only Lisp object ++that is both. ++ ++@example ++(atom @var{object}) @equiv{} (not (consp @var{object})) ++@end example ++@end defun ++ ++@defun listp object ++This function returns @code{t} if @var{object} is a cons cell or ++@code{nil}. Otherwise, it returns @code{nil}. ++ ++@example ++@group ++(listp '(1)) ++ @result{} t ++@end group ++@group ++(listp '()) ++ @result{} t ++@end group ++@end example ++@end defun ++ ++@defun nlistp object ++This function is the opposite of @code{listp}: it returns @code{t} if ++@var{object} is not a list. Otherwise, it returns @code{nil}. ++ ++@example ++(listp @var{object}) @equiv{} (not (nlistp @var{object})) ++@end example ++@end defun ++ ++@defun null object ++This function returns @code{t} if @var{object} is @code{nil}, and ++returns @code{nil} otherwise. This function is identical to @code{not}, ++but as a matter of clarity we use @code{null} when @var{object} is ++considered a list and @code{not} when it is considered a truth value ++(see @code{not} in @ref{Combining Conditions}). ++ ++@example ++@group ++(null '(1)) ++ @result{} nil ++@end group ++@group ++(null '()) ++ @result{} t ++@end group ++@end example ++@end defun ++ ++ ++@node List Elements ++@section Accessing Elements of Lists ++@cindex list elements ++ ++@defun car cons-cell ++This function returns the value referred to by the first slot of the ++cons cell @var{cons-cell}. In other words, it returns the @sc{car} of ++@var{cons-cell}. ++ ++As a special case, if @var{cons-cell} is @code{nil}, this function ++returns @code{nil}. Therefore, any list is a valid argument. An ++error is signaled if the argument is not a cons cell or @code{nil}. ++ ++@example ++@group ++(car '(a b c)) ++ @result{} a ++@end group ++@group ++(car '()) ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun cdr cons-cell ++This function returns the value referred to by the second slot of the ++cons cell @var{cons-cell}. In other words, it returns the @sc{cdr} of ++@var{cons-cell}. ++ ++As a special case, if @var{cons-cell} is @code{nil}, this function ++returns @code{nil}; therefore, any list is a valid argument. An error ++is signaled if the argument is not a cons cell or @code{nil}. ++ ++@example ++@group ++(cdr '(a b c)) ++ @result{} (b c) ++@end group ++@group ++(cdr '()) ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun car-safe object ++This function lets you take the @sc{car} of a cons cell while avoiding ++errors for other data types. It returns the @sc{car} of @var{object} if ++@var{object} is a cons cell, @code{nil} otherwise. This is in contrast ++to @code{car}, which signals an error if @var{object} is not a list. ++ ++@example ++@group ++(car-safe @var{object}) ++@equiv{} ++(let ((x @var{object})) ++ (if (consp x) ++ (car x) ++ nil)) ++@end group ++@end example ++@end defun ++ ++@defun cdr-safe object ++This function lets you take the @sc{cdr} of a cons cell while ++avoiding errors for other data types. It returns the @sc{cdr} of ++@var{object} if @var{object} is a cons cell, @code{nil} otherwise. ++This is in contrast to @code{cdr}, which signals an error if ++@var{object} is not a list. ++ ++@example ++@group ++(cdr-safe @var{object}) ++@equiv{} ++(let ((x @var{object})) ++ (if (consp x) ++ (cdr x) ++ nil)) ++@end group ++@end example ++@end defun ++ ++@defmac pop listname ++This macro is a way of examining the @sc{car} of a list, ++and taking it off the list, all at once. ++ ++It operates on the list which is stored in the symbol @var{listname}. ++It removes this element from the list by setting @var{listname} ++to the @sc{cdr} of its old value---but it also returns the @sc{car} ++of that list, which is the element being removed. ++ ++@example ++x ++ @result{} (a b c) ++(pop x) ++ @result{} a ++x ++ @result{} (b c) ++@end example ++@end defmac ++ ++@defun nth n list ++@anchor{Definition of nth} ++This function returns the @var{n}th element of @var{list}. Elements ++are numbered starting with zero, so the @sc{car} of @var{list} is ++element number zero. If the length of @var{list} is @var{n} or less, ++the value is @code{nil}. ++ ++If @var{n} is negative, @code{nth} returns the first element of ++@var{list}. ++ ++@example ++@group ++(nth 2 '(1 2 3 4)) ++ @result{} 3 ++@end group ++@group ++(nth 10 '(1 2 3 4)) ++ @result{} nil ++@end group ++@group ++(nth -3 '(1 2 3 4)) ++ @result{} 1 ++ ++(nth n x) @equiv{} (car (nthcdr n x)) ++@end group ++@end example ++ ++The function @code{elt} is similar, but applies to any kind of sequence. ++For historical reasons, it takes its arguments in the opposite order. ++@xref{Sequence Functions}. ++@end defun ++ ++@defun nthcdr n list ++This function returns the @var{n}th @sc{cdr} of @var{list}. In other ++words, it skips past the first @var{n} links of @var{list} and returns ++what follows. ++ ++If @var{n} is zero or negative, @code{nthcdr} returns all of ++@var{list}. If the length of @var{list} is @var{n} or less, ++@code{nthcdr} returns @code{nil}. ++ ++@example ++@group ++(nthcdr 1 '(1 2 3 4)) ++ @result{} (2 3 4) ++@end group ++@group ++(nthcdr 10 '(1 2 3 4)) ++ @result{} nil ++@end group ++@group ++(nthcdr -3 '(1 2 3 4)) ++ @result{} (1 2 3 4) ++@end group ++@end example ++@end defun ++ ++@defun last list &optional n ++This function returns the last link of @var{list}. The @code{car} of ++this link is the list's last element. If @var{list} is null, ++@code{nil} is returned. If @var{n} is non-@code{nil}, the ++@var{n}th-to-last link is returned instead, or the whole of @var{list} ++if @var{n} is bigger than @var{list}'s length. ++@end defun ++ ++@defun safe-length list ++@anchor{Definition of safe-length} ++This function returns the length of @var{list}, with no risk of either ++an error or an infinite loop. It generally returns the number of ++distinct cons cells in the list. However, for circular lists, ++the value is just an upper bound; it is often too large. ++ ++If @var{list} is not @code{nil} or a cons cell, @code{safe-length} ++returns 0. ++@end defun ++ ++ The most common way to compute the length of a list, when you are not ++worried that it may be circular, is with @code{length}. @xref{Sequence ++Functions}. ++ ++@defun caar cons-cell ++This is the same as @code{(car (car @var{cons-cell}))}. ++@end defun ++ ++@defun cadr cons-cell ++This is the same as @code{(car (cdr @var{cons-cell}))} ++or @code{(nth 1 @var{cons-cell})}. ++@end defun ++ ++@defun cdar cons-cell ++This is the same as @code{(cdr (car @var{cons-cell}))}. ++@end defun ++ ++@defun cddr cons-cell ++This is the same as @code{(cdr (cdr @var{cons-cell}))} ++or @code{(nthcdr 2 @var{cons-cell})}. ++@end defun ++ ++@defun butlast x &optional n ++This function returns the list @var{x} with the last element, ++or the last @var{n} elements, removed. If @var{n} is greater ++than zero it makes a copy of the list so as not to damage the ++original list. In general, @code{(append (butlast @var{x} @var{n}) ++(last @var{x} @var{n}))} will return a list equal to @var{x}. ++@end defun ++ ++@defun nbutlast x &optional n ++This is a version of @code{butlast} that works by destructively ++modifying the @code{cdr} of the appropriate element, rather than ++making a copy of the list. ++@end defun ++ ++@node Building Lists ++@comment node-name, next, previous, up ++@section Building Cons Cells and Lists ++@cindex cons cells ++@cindex building lists ++ ++ Many functions build lists, as lists reside at the very heart of Lisp. ++@code{cons} is the fundamental list-building function; however, it is ++interesting to note that @code{list} is used more times in the source ++code for Emacs than @code{cons}. ++ ++@defun cons object1 object2 ++This function is the most basic function for building new list ++structure. It creates a new cons cell, making @var{object1} the ++@sc{car}, and @var{object2} the @sc{cdr}. It then returns the new ++cons cell. The arguments @var{object1} and @var{object2} may be any ++Lisp objects, but most often @var{object2} is a list. ++ ++@example ++@group ++(cons 1 '(2)) ++ @result{} (1 2) ++@end group ++@group ++(cons 1 '()) ++ @result{} (1) ++@end group ++@group ++(cons 1 2) ++ @result{} (1 . 2) ++@end group ++@end example ++ ++@cindex consing ++@code{cons} is often used to add a single element to the front of a ++list. This is called @dfn{consing the element onto the list}. ++@footnote{There is no strictly equivalent way to add an element to ++the end of a list. You can use @code{(append @var{listname} (list ++@var{newelt}))}, which creates a whole new list by copying @var{listname} ++and adding @var{newelt} to its end. Or you can use @code{(nconc ++@var{listname} (list @var{newelt}))}, which modifies @var{listname} ++by following all the @sc{cdr}s and then replacing the terminating ++@code{nil}. Compare this to adding an element to the beginning of a ++list with @code{cons}, which neither copies nor modifies the list.} ++For example: ++ ++@example ++(setq list (cons newelt list)) ++@end example ++ ++Note that there is no conflict between the variable named @code{list} ++used in this example and the function named @code{list} described below; ++any symbol can serve both purposes. ++@end defun ++ ++@defun list &rest objects ++This function creates a list with @var{objects} as its elements. The ++resulting list is always @code{nil}-terminated. If no @var{objects} ++are given, the empty list is returned. ++ ++@example ++@group ++(list 1 2 3 4 5) ++ @result{} (1 2 3 4 5) ++@end group ++@group ++(list 1 2 '(3 4 5) 'foo) ++ @result{} (1 2 (3 4 5) foo) ++@end group ++@group ++(list) ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun make-list length object ++This function creates a list of @var{length} elements, in which each ++element is @var{object}. Compare @code{make-list} with ++@code{make-string} (@pxref{Creating Strings}). ++ ++@example ++@group ++(make-list 3 'pigs) ++ @result{} (pigs pigs pigs) ++@end group ++@group ++(make-list 0 'pigs) ++ @result{} nil ++@end group ++@group ++(setq l (make-list 3 '(a b)) ++ @result{} ((a b) (a b) (a b)) ++(eq (car l) (cadr l)) ++ @result{} t ++@end group ++@end example ++@end defun ++ ++@defun append &rest sequences ++@cindex copying lists ++This function returns a list containing all the elements of ++@var{sequences}. The @var{sequences} may be lists, vectors, ++bool-vectors, or strings, but the last one should usually be a list. ++All arguments except the last one are copied, so none of the arguments ++is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join ++lists with no copying.) ++ ++More generally, the final argument to @code{append} may be any Lisp ++object. The final argument is not copied or converted; it becomes the ++@sc{cdr} of the last cons cell in the new list. If the final argument ++is itself a list, then its elements become in effect elements of the ++result list. If the final element is not a list, the result is a ++dotted list since its final @sc{cdr} is not @code{nil} as required ++in a true list. ++@end defun ++ ++ Here is an example of using @code{append}: ++ ++@example ++@group ++(setq trees '(pine oak)) ++ @result{} (pine oak) ++(setq more-trees (append '(maple birch) trees)) ++ @result{} (maple birch pine oak) ++@end group ++ ++@group ++trees ++ @result{} (pine oak) ++more-trees ++ @result{} (maple birch pine oak) ++@end group ++@group ++(eq trees (cdr (cdr more-trees))) ++ @result{} t ++@end group ++@end example ++ ++ You can see how @code{append} works by looking at a box diagram. The ++variable @code{trees} is set to the list @code{(pine oak)} and then the ++variable @code{more-trees} is set to the list @code{(maple birch pine ++oak)}. However, the variable @code{trees} continues to refer to the ++original list: ++ ++@smallexample ++@group ++more-trees trees ++| | ++| --- --- --- --- -> --- --- --- --- ++ --> | | |--> | | |--> | | |--> | | |--> nil ++ --- --- --- --- --- --- --- --- ++ | | | | ++ | | | | ++ --> maple -->birch --> pine --> oak ++@end group ++@end smallexample ++ ++ An empty sequence contributes nothing to the value returned by ++@code{append}. As a consequence of this, a final @code{nil} argument ++forces a copy of the previous argument: ++ ++@example ++@group ++trees ++ @result{} (pine oak) ++@end group ++@group ++(setq wood (append trees nil)) ++ @result{} (pine oak) ++@end group ++@group ++wood ++ @result{} (pine oak) ++@end group ++@group ++(eq wood trees) ++ @result{} nil ++@end group ++@end example ++ ++@noindent ++This once was the usual way to copy a list, before the function ++@code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}. ++ ++ Here we show the use of vectors and strings as arguments to @code{append}: ++ ++@example ++@group ++(append [a b] "cd" nil) ++ @result{} (a b 99 100) ++@end group ++@end example ++ ++ With the help of @code{apply} (@pxref{Calling Functions}), we can append ++all the lists in a list of lists: ++ ++@example ++@group ++(apply 'append '((a b c) nil (x y z) nil)) ++ @result{} (a b c x y z) ++@end group ++@end example ++ ++ If no @var{sequences} are given, @code{nil} is returned: ++ ++@example ++@group ++(append) ++ @result{} nil ++@end group ++@end example ++ ++ Here are some examples where the final argument is not a list: ++ ++@example ++(append '(x y) 'z) ++ @result{} (x y . z) ++(append '(x y) [z]) ++ @result{} (x y . [z]) ++@end example ++ ++@noindent ++The second example shows that when the final argument is a sequence but ++not a list, the sequence's elements do not become elements of the ++resulting list. Instead, the sequence becomes the final @sc{cdr}, like ++any other non-list final argument. ++ ++@defun reverse list ++This function creates a new list whose elements are the elements of ++@var{list}, but in reverse order. The original argument @var{list} is ++@emph{not} altered. ++ ++@example ++@group ++(setq x '(1 2 3 4)) ++ @result{} (1 2 3 4) ++@end group ++@group ++(reverse x) ++ @result{} (4 3 2 1) ++x ++ @result{} (1 2 3 4) ++@end group ++@end example ++@end defun ++ ++@defun copy-tree tree &optional vecp ++This function returns a copy of the tree @code{tree}. If @var{tree} is a ++cons cell, this makes a new cons cell with the same @sc{car} and ++@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the ++same way. ++ ++Normally, when @var{tree} is anything other than a cons cell, ++@code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is ++non-@code{nil}, it copies vectors too (and operates recursively on ++their elements). ++@end defun ++ ++@defun number-sequence from &optional to separation ++This returns a list of numbers starting with @var{from} and ++incrementing by @var{separation}, and ending at or just before ++@var{to}. @var{separation} can be positive or negative and defaults ++to 1. If @var{to} is @code{nil} or numerically equal to @var{from}, ++the value is the one-element list @code{(@var{from})}. If @var{to} is ++less than @var{from} with a positive @var{separation}, or greater than ++@var{from} with a negative @var{separation}, the value is @code{nil} ++because those arguments specify an empty sequence. ++ ++If @var{separation} is 0 and @var{to} is neither @code{nil} nor ++numerically equal to @var{from}, @code{number-sequence} signals an ++error, since those arguments specify an infinite sequence. ++ ++All arguments can be integers or floating point numbers. However, ++floating point arguments can be tricky, because floating point ++arithmetic is inexact. For instance, depending on the machine, it may ++quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns ++the one element list @code{(0.4)}, whereas ++@code{(number-sequence 0.4 0.8 0.2)} returns a list with three ++elements. The @var{n}th element of the list is computed by the exact ++formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if ++one wants to make sure that @var{to} is included in the list, one can ++pass an expression of this exact type for @var{to}. Alternatively, ++one can replace @var{to} with a slightly larger value (or a slightly ++more negative value if @var{separation} is negative). ++ ++Some examples: ++ ++@example ++(number-sequence 4 9) ++ @result{} (4 5 6 7 8 9) ++(number-sequence 9 4 -1) ++ @result{} (9 8 7 6 5 4) ++(number-sequence 9 4 -2) ++ @result{} (9 7 5) ++(number-sequence 8) ++ @result{} (8) ++(number-sequence 8 5) ++ @result{} nil ++(number-sequence 5 8 -1) ++ @result{} nil ++(number-sequence 1.5 6 2) ++ @result{} (1.5 3.5 5.5) ++@end example ++@end defun ++ ++@node List Variables ++@section Modifying List Variables ++ ++ These functions, and one macro, provide convenient ways ++to modify a list which is stored in a variable. ++ ++@defmac push newelt listname ++This macro provides an alternative way to write ++@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. ++ ++@example ++(setq l '(a b)) ++ @result{} (a b) ++(push 'c l) ++ @result{} (c a b) ++l ++ @result{} (c a b) ++@end example ++@end defmac ++ ++ Two functions modify lists that are the values of variables. ++ ++@defun add-to-list symbol element &optional append compare-fn ++This function sets the variable @var{symbol} by consing @var{element} ++onto the old value, if @var{element} is not already a member of that ++value. It returns the resulting list, whether updated or not. The ++value of @var{symbol} had better be a list already before the call. ++@code{add-to-list} uses @var{compare-fn} to compare @var{element} ++against existing list members; if @var{compare-fn} is @code{nil}, it ++uses @code{equal}. ++ ++Normally, if @var{element} is added, it is added to the front of ++@var{symbol}, but if the optional argument @var{append} is ++non-@code{nil}, it is added at the end. ++ ++The argument @var{symbol} is not implicitly quoted; @code{add-to-list} ++is an ordinary function, like @code{set} and unlike @code{setq}. Quote ++the argument yourself if that is what you want. ++@end defun ++ ++Here's a scenario showing how to use @code{add-to-list}: ++ ++@example ++(setq foo '(a b)) ++ @result{} (a b) ++ ++(add-to-list 'foo 'c) ;; @r{Add @code{c}.} ++ @result{} (c a b) ++ ++(add-to-list 'foo 'b) ;; @r{No effect.} ++ @result{} (c a b) ++ ++foo ;; @r{@code{foo} was changed.} ++ @result{} (c a b) ++@end example ++ ++ An equivalent expression for @code{(add-to-list '@var{var} ++@var{value})} is this: ++ ++@example ++(or (member @var{value} @var{var}) ++ (setq @var{var} (cons @var{value} @var{var}))) ++@end example ++ ++@defun add-to-ordered-list symbol element &optional order ++This function sets the variable @var{symbol} by inserting ++@var{element} into the old value, which must be a list, at the ++position specified by @var{order}. If @var{element} is already a ++member of the list, its position in the list is adjusted according ++to @var{order}. Membership is tested using @code{eq}. ++This function returns the resulting list, whether updated or not. ++ ++The @var{order} is typically a number (integer or float), and the ++elements of the list are sorted in non-decreasing numerical order. ++ ++@var{order} may also be omitted or @code{nil}. Then the numeric order ++of @var{element} stays unchanged if it already has one; otherwise, ++@var{element} has no numeric order. Elements without a numeric list ++order are placed at the end of the list, in no particular order. ++ ++Any other value for @var{order} removes the numeric order of @var{element} ++if it already has one; otherwise, it is equivalent to @code{nil}. ++ ++The argument @var{symbol} is not implicitly quoted; ++@code{add-to-ordered-list} is an ordinary function, like @code{set} ++and unlike @code{setq}. Quote the argument yourself if that is what ++you want. ++ ++The ordering information is stored in a hash table on @var{symbol}'s ++@code{list-order} property. ++@end defun ++ ++Here's a scenario showing how to use @code{add-to-ordered-list}: ++ ++@example ++(setq foo '()) ++ @result{} nil ++ ++(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.} ++ @result{} (a) ++ ++(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.} ++ @result{} (a c) ++ ++(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.} ++ @result{} (a b c) ++ ++(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.} ++ @result{} (a c b) ++ ++(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} ++ @result{} (a c b d) ++ ++(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. ++ @result{} (a c b e d) ++ ++foo ;; @r{@code{foo} was changed.} ++ @result{} (a c b e d) ++@end example ++ ++@node Modifying Lists ++@section Modifying Existing List Structure ++@cindex destructive list operations ++ ++ You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the ++primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' ++operations because they change existing list structure. ++ ++@cindex CL note---@code{rplaca} vs @code{setcar} ++@quotation ++@findex rplaca ++@findex rplacd ++@b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and ++@code{rplacd} to alter list structure; they change structure the same ++way as @code{setcar} and @code{setcdr}, but the Common Lisp functions ++return the cons cell while @code{setcar} and @code{setcdr} return the ++new @sc{car} or @sc{cdr}. ++@end quotation ++ ++@menu ++* Setcar:: Replacing an element in a list. ++* Setcdr:: Replacing part of the list backbone. ++ This can be used to remove or add elements. ++* Rearrangement:: Reordering the elements in a list; combining lists. ++@end menu ++ ++@node Setcar ++@subsection Altering List Elements with @code{setcar} ++ ++ Changing the @sc{car} of a cons cell is done with @code{setcar}. When ++used on a list, @code{setcar} replaces one element of a list with a ++different element. ++ ++@defun setcar cons object ++This function stores @var{object} as the new @sc{car} of @var{cons}, ++replacing its previous @sc{car}. In other words, it changes the ++@sc{car} slot of @var{cons} to refer to @var{object}. It returns the ++value @var{object}. For example: ++ ++@example ++@group ++(setq x '(1 2)) ++ @result{} (1 2) ++@end group ++@group ++(setcar x 4) ++ @result{} 4 ++@end group ++@group ++x ++ @result{} (4 2) ++@end group ++@end example ++@end defun ++ ++ When a cons cell is part of the shared structure of several lists, ++storing a new @sc{car} into the cons changes one element of each of ++these lists. Here is an example: ++ ++@example ++@group ++;; @r{Create two lists that are partly shared.} ++(setq x1 '(a b c)) ++ @result{} (a b c) ++(setq x2 (cons 'z (cdr x1))) ++ @result{} (z b c) ++@end group ++ ++@group ++;; @r{Replace the @sc{car} of a shared link.} ++(setcar (cdr x1) 'foo) ++ @result{} foo ++x1 ; @r{Both lists are changed.} ++ @result{} (a foo c) ++x2 ++ @result{} (z foo c) ++@end group ++ ++@group ++;; @r{Replace the @sc{car} of a link that is not shared.} ++(setcar x1 'baz) ++ @result{} baz ++x1 ; @r{Only one list is changed.} ++ @result{} (baz foo c) ++x2 ++ @result{} (z foo c) ++@end group ++@end example ++ ++ Here is a graphical depiction of the shared structure of the two lists ++in the variables @code{x1} and @code{x2}, showing why replacing @code{b} ++changes them both: ++ ++@example ++@group ++ --- --- --- --- --- --- ++x1---> | | |----> | | |--> | | |--> nil ++ --- --- --- --- --- --- ++ | --> | | ++ | | | | ++ --> a | --> b --> c ++ | ++ --- --- | ++x2--> | | |-- ++ --- --- ++ | ++ | ++ --> z ++@end group ++@end example ++ ++ Here is an alternative form of box diagram, showing the same relationship: ++ ++@example ++@group ++x1: ++ -------------- -------------- -------------- ++| car | cdr | | car | cdr | | car | cdr | ++| a | o------->| b | o------->| c | nil | ++| | | -->| | | | | | ++ -------------- | -------------- -------------- ++ | ++x2: | ++ -------------- | ++| car | cdr | | ++| z | o---- ++| | | ++ -------------- ++@end group ++@end example ++ ++@node Setcdr ++@subsection Altering the CDR of a List ++ ++ The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: ++ ++@defun setcdr cons object ++This function stores @var{object} as the new @sc{cdr} of @var{cons}, ++replacing its previous @sc{cdr}. In other words, it changes the ++@sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the ++value @var{object}. ++@end defun ++ ++ Here is an example of replacing the @sc{cdr} of a list with a ++different list. All but the first element of the list are removed in ++favor of a different sequence of elements. The first element is ++unchanged, because it resides in the @sc{car} of the list, and is not ++reached via the @sc{cdr}. ++ ++@example ++@group ++(setq x '(1 2 3)) ++ @result{} (1 2 3) ++@end group ++@group ++(setcdr x '(4)) ++ @result{} (4) ++@end group ++@group ++x ++ @result{} (1 4) ++@end group ++@end example ++ ++ You can delete elements from the middle of a list by altering the ++@sc{cdr}s of the cons cells in the list. For example, here we delete ++the second element, @code{b}, from the list @code{(a b c)}, by changing ++the @sc{cdr} of the first cons cell: ++ ++@example ++@group ++(setq x1 '(a b c)) ++ @result{} (a b c) ++(setcdr x1 (cdr (cdr x1))) ++ @result{} (c) ++x1 ++ @result{} (a c) ++@end group ++@end example ++ ++ Here is the result in box notation: ++ ++@smallexample ++@group ++ -------------------- ++ | | ++ -------------- | -------------- | -------------- ++| car | cdr | | | car | cdr | -->| car | cdr | ++| a | o----- | b | o-------->| c | nil | ++| | | | | | | | | ++ -------------- -------------- -------------- ++@end group ++@end smallexample ++ ++@noindent ++The second cons cell, which previously held the element @code{b}, still ++exists and its @sc{car} is still @code{b}, but it no longer forms part ++of this list. ++ ++ It is equally easy to insert a new element by changing @sc{cdr}s: ++ ++@example ++@group ++(setq x1 '(a b c)) ++ @result{} (a b c) ++(setcdr x1 (cons 'd (cdr x1))) ++ @result{} (d b c) ++x1 ++ @result{} (a d b c) ++@end group ++@end example ++ ++ Here is this result in box notation: ++ ++@smallexample ++@group ++ -------------- ------------- ------------- ++| car | cdr | | car | cdr | | car | cdr | ++| a | o | -->| b | o------->| c | nil | ++| | | | | | | | | | | ++ --------- | -- | ------------- ------------- ++ | | ++ ----- -------- ++ | | ++ | --------------- | ++ | | car | cdr | | ++ -->| d | o------ ++ | | | ++ --------------- ++@end group ++@end smallexample ++ ++@node Rearrangement ++@subsection Functions that Rearrange Lists ++@cindex rearrangement of lists ++@cindex modification of lists ++ ++ Here are some functions that rearrange lists ``destructively'' by ++modifying the @sc{cdr}s of their component cons cells. We call these ++functions ``destructive'' because they chew up the original lists passed ++to them as arguments, relinking their cons cells to form a new list that ++is the returned value. ++ ++@ifnottex ++ See @code{delq}, in @ref{Sets And Lists}, for another function ++that modifies cons cells. ++@end ifnottex ++@iftex ++ The function @code{delq} in the following section is another example ++of destructive list manipulation. ++@end iftex ++ ++@defun nconc &rest lists ++@cindex concatenating lists ++@cindex joining lists ++This function returns a list containing all the elements of @var{lists}. ++Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are ++@emph{not} copied. Instead, the last @sc{cdr} of each of the ++@var{lists} is changed to refer to the following list. The last of the ++@var{lists} is not altered. For example: ++ ++@example ++@group ++(setq x '(1 2 3)) ++ @result{} (1 2 3) ++@end group ++@group ++(nconc x '(4 5)) ++ @result{} (1 2 3 4 5) ++@end group ++@group ++x ++ @result{} (1 2 3 4 5) ++@end group ++@end example ++ ++ Since the last argument of @code{nconc} is not itself modified, it is ++reasonable to use a constant list, such as @code{'(4 5)}, as in the ++above example. For the same reason, the last argument need not be a ++list: ++ ++@example ++@group ++(setq x '(1 2 3)) ++ @result{} (1 2 3) ++@end group ++@group ++(nconc x 'z) ++ @result{} (1 2 3 . z) ++@end group ++@group ++x ++ @result{} (1 2 3 . z) ++@end group ++@end example ++ ++However, the other arguments (all but the last) must be lists. ++ ++A common pitfall is to use a quoted constant list as a non-last ++argument to @code{nconc}. If you do this, your program will change ++each time you run it! Here is what happens: ++ ++@smallexample ++@group ++(defun add-foo (x) ; @r{We want this function to add} ++ (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.} ++@end group ++ ++@group ++(symbol-function 'add-foo) ++ @result{} (lambda (x) (nconc (quote (foo)) x)) ++@end group ++ ++@group ++(setq xx (add-foo '(1 2))) ; @r{It seems to work.} ++ @result{} (foo 1 2) ++@end group ++@group ++(setq xy (add-foo '(3 4))) ; @r{What happened?} ++ @result{} (foo 1 2 3 4) ++@end group ++@group ++(eq xx xy) ++ @result{} t ++@end group ++ ++@group ++(symbol-function 'add-foo) ++ @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) ++@end group ++@end smallexample ++@end defun ++ ++@defun nreverse list ++@cindex reversing a list ++ This function reverses the order of the elements of @var{list}. ++Unlike @code{reverse}, @code{nreverse} alters its argument by reversing ++the @sc{cdr}s in the cons cells forming the list. The cons cell that ++used to be the last one in @var{list} becomes the first cons cell of the ++value. ++ ++ For example: ++ ++@example ++@group ++(setq x '(a b c)) ++ @result{} (a b c) ++@end group ++@group ++x ++ @result{} (a b c) ++(nreverse x) ++ @result{} (c b a) ++@end group ++@group ++;; @r{The cons cell that was first is now last.} ++x ++ @result{} (a) ++@end group ++@end example ++ ++ To avoid confusion, we usually store the result of @code{nreverse} ++back in the same variable which held the original list: ++ ++@example ++(setq x (nreverse x)) ++@end example ++ ++ Here is the @code{nreverse} of our favorite example, @code{(a b c)}, ++presented graphically: ++ ++@smallexample ++@group ++@r{Original list head:} @r{Reversed list:} ++ ------------- ------------- ------------ ++| car | cdr | | car | cdr | | car | cdr | ++| a | nil |<-- | b | o |<-- | c | o | ++| | | | | | | | | | | | | ++ ------------- | --------- | - | -------- | - ++ | | | | ++ ------------- ------------ ++@end group ++@end smallexample ++@end defun ++ ++@defun sort list predicate ++@cindex stable sort ++@cindex sorting lists ++This function sorts @var{list} stably, though destructively, and ++returns the sorted list. It compares elements using @var{predicate}. A ++stable sort is one in which elements with equal sort keys maintain their ++relative order before and after the sort. Stability is important when ++successive sorts are used to order elements according to different ++criteria. ++ ++The argument @var{predicate} must be a function that accepts two ++arguments. It is called with two elements of @var{list}. To get an ++increasing order sort, the @var{predicate} should return non-@code{nil} if the ++first element is ``less than'' the second, or @code{nil} if not. ++ ++The comparison function @var{predicate} must give reliable results for ++any given pair of arguments, at least within a single call to ++@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is ++less than @var{b}, @var{b} must not be less than @var{a}. It must be ++@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} ++is less than @var{c}, then @var{a} must be less than @var{c}. If you ++use a comparison function which does not meet these requirements, the ++result of @code{sort} is unpredictable. ++ ++The destructive aspect of @code{sort} is that it rearranges the cons ++cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort ++function would create new cons cells to store the elements in their ++sorted order. If you wish to make a sorted copy without destroying the ++original, copy it first with @code{copy-sequence} and then sort. ++ ++Sorting does not change the @sc{car}s of the cons cells in @var{list}; ++the cons cell that originally contained the element @code{a} in ++@var{list} still has @code{a} in its @sc{car} after sorting, but it now ++appears in a different position in the list due to the change of ++@sc{cdr}s. For example: ++ ++@example ++@group ++(setq nums '(1 3 2 6 5 4 0)) ++ @result{} (1 3 2 6 5 4 0) ++@end group ++@group ++(sort nums '<) ++ @result{} (0 1 2 3 4 5 6) ++@end group ++@group ++nums ++ @result{} (1 2 3 4 5 6) ++@end group ++@end example ++ ++@noindent ++@strong{Warning}: Note that the list in @code{nums} no longer contains ++0; this is the same cons cell that it was before, but it is no longer ++the first one in the list. Don't assume a variable that formerly held ++the argument now holds the entire sorted list! Instead, save the result ++of @code{sort} and use that. Most often we store the result back into ++the variable that held the original list: ++ ++@example ++(setq nums (sort nums '<)) ++@end example ++ ++@xref{Sorting}, for more functions that perform sorting. ++See @code{documentation} in @ref{Accessing Documentation}, for a ++useful example of @code{sort}. ++@end defun ++ ++@node Sets And Lists ++@section Using Lists as Sets ++@cindex lists as sets ++@cindex sets ++ ++ A list can represent an unordered mathematical set---simply consider a ++value an element of a set if it appears in the list, and ignore the ++order of the list. To form the union of two sets, use @code{append} (as ++long as you don't mind having duplicate elements). You can remove ++@code{equal} duplicates using @code{delete-dups}. Other useful ++functions for sets include @code{memq} and @code{delq}, and their ++@code{equal} versions, @code{member} and @code{delete}. ++ ++@cindex CL note---lack @code{union}, @code{intersection} ++@quotation ++@b{Common Lisp note:} Common Lisp has functions @code{union} (which ++avoids duplicate elements) and @code{intersection} for set operations, ++but GNU Emacs Lisp does not have them. You can write them in Lisp if ++you wish. ++@end quotation ++ ++@defun memq object list ++@cindex membership in a list ++This function tests to see whether @var{object} is a member of ++@var{list}. If it is, @code{memq} returns a list starting with the ++first occurrence of @var{object}. Otherwise, it returns @code{nil}. ++The letter @samp{q} in @code{memq} says that it uses @code{eq} to ++compare @var{object} against the elements of the list. For example: ++ ++@example ++@group ++(memq 'b '(a b c b a)) ++ @result{} (b c b a) ++@end group ++@group ++(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun delq object list ++@cindex deleting list elements ++This function destructively removes all elements @code{eq} to ++@var{object} from @var{list}. The letter @samp{q} in @code{delq} says ++that it uses @code{eq} to compare @var{object} against the elements of ++the list, like @code{memq} and @code{remq}. ++@end defun ++ ++When @code{delq} deletes elements from the front of the list, it does so ++simply by advancing down the list and returning a sublist that starts ++after those elements: ++ ++@example ++@group ++(delq 'a '(a b c)) @equiv{} (cdr '(a b c)) ++@end group ++@end example ++ ++When an element to be deleted appears in the middle of the list, ++removing it involves changing the @sc{cdr}s (@pxref{Setcdr}). ++ ++@example ++@group ++(setq sample-list '(a b c (4))) ++ @result{} (a b c (4)) ++@end group ++@group ++(delq 'a sample-list) ++ @result{} (b c (4)) ++@end group ++@group ++sample-list ++ @result{} (a b c (4)) ++@end group ++@group ++(delq 'c sample-list) ++ @result{} (a b (4)) ++@end group ++@group ++sample-list ++ @result{} (a b (4)) ++@end group ++@end example ++ ++Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to ++splice out the third element, but @code{(delq 'a sample-list)} does not ++splice anything---it just returns a shorter list. Don't assume that a ++variable which formerly held the argument @var{list} now has fewer ++elements, or that it still holds the original list! Instead, save the ++result of @code{delq} and use that. Most often we store the result back ++into the variable that held the original list: ++ ++@example ++(setq flowers (delq 'rose flowers)) ++@end example ++ ++In the following example, the @code{(4)} that @code{delq} attempts to match ++and the @code{(4)} in the @code{sample-list} are not @code{eq}: ++ ++@example ++@group ++(delq '(4) sample-list) ++ @result{} (a c (4)) ++@end group ++ ++If you want to delete elements that are @code{equal} to a given value, ++use @code{delete} (see below). ++@end example ++ ++@defun remq object list ++This function returns a copy of @var{list}, with all elements removed ++which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq} ++says that it uses @code{eq} to compare @var{object} against the elements ++of @code{list}. ++ ++@example ++@group ++(setq sample-list '(a b c a b c)) ++ @result{} (a b c a b c) ++@end group ++@group ++(remq 'a sample-list) ++ @result{} (b c b c) ++@end group ++@group ++sample-list ++ @result{} (a b c a b c) ++@end group ++@end example ++@end defun ++ ++@defun memql object list ++The function @code{memql} tests to see whether @var{object} is a member ++of @var{list}, comparing members with @var{object} using @code{eql}, ++so floating point elements are compared by value. ++If @var{object} is a member, @code{memql} returns a list starting with ++its first occurrence in @var{list}. Otherwise, it returns @code{nil}. ++ ++Compare this with @code{memq}: ++ ++@example ++@group ++(memql 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are @code{eql}.} ++ @result{} (1.2 1.3) ++@end group ++@group ++(memq 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are not @code{eq}.} ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++The following three functions are like @code{memq}, @code{delq} and ++@code{remq}, but use @code{equal} rather than @code{eq} to compare ++elements. @xref{Equality Predicates}. ++ ++@defun member object list ++The function @code{member} tests to see whether @var{object} is a member ++of @var{list}, comparing members with @var{object} using @code{equal}. ++If @var{object} is a member, @code{member} returns a list starting with ++its first occurrence in @var{list}. Otherwise, it returns @code{nil}. ++ ++Compare this with @code{memq}: ++ ++@example ++@group ++(member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.} ++ @result{} ((2)) ++@end group ++@group ++(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} ++ @result{} nil ++@end group ++@group ++;; @r{Two strings with the same contents are @code{equal}.} ++(member "foo" '("foo" "bar")) ++ @result{} ("foo" "bar") ++@end group ++@end example ++@end defun ++ ++@defun delete object sequence ++If @code{sequence} is a list, this function destructively removes all ++elements @code{equal} to @var{object} from @var{sequence}. For lists, ++@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it ++uses @code{equal} to compare elements with @var{object}, like ++@code{member}; when it finds an element that matches, it cuts the ++element out just as @code{delq} would. ++ ++If @code{sequence} is a vector or string, @code{delete} returns a copy ++of @code{sequence} with all elements @code{equal} to @code{object} ++removed. ++ ++For example: ++ ++@example ++@group ++(setq l '((2) (1) (2))) ++(delete '(2) l) ++ @result{} ((1)) ++l ++ @result{} ((2) (1)) ++;; @r{If you want to change @code{l} reliably,} ++;; @r{write @code{(setq l (delete elt l))}.} ++@end group ++@group ++(setq l '((2) (1) (2))) ++(delete '(1) l) ++ @result{} ((2) (2)) ++l ++ @result{} ((2) (2)) ++;; @r{In this case, it makes no difference whether you set @code{l},} ++;; @r{but you should do so for the sake of the other case.} ++@end group ++@group ++(delete '(2) [(2) (1) (2)]) ++ @result{} [(1)] ++@end group ++@end example ++@end defun ++ ++@defun remove object sequence ++This function is the non-destructive counterpart of @code{delete}. It ++returns a copy of @code{sequence}, a list, vector, or string, with ++elements @code{equal} to @code{object} removed. For example: ++ ++@example ++@group ++(remove '(2) '((2) (1) (2))) ++ @result{} ((1)) ++@end group ++@group ++(remove '(2) [(2) (1) (2)]) ++ @result{} [(1)] ++@end group ++@end example ++@end defun ++ ++@quotation ++@b{Common Lisp note:} The functions @code{member}, @code{delete} and ++@code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common ++Lisp. The Common Lisp versions do not use @code{equal} to compare ++elements. ++@end quotation ++ ++@defun member-ignore-case object list ++This function is like @code{member}, except that @var{object} should ++be a string and that it ignores differences in letter-case and text ++representation: upper-case and lower-case letters are treated as ++equal, and unibyte strings are converted to multibyte prior to ++comparison. ++@end defun ++ ++@defun delete-dups list ++This function destructively removes all @code{equal} duplicates from ++@var{list}, stores the result in @var{list} and returns it. Of ++several @code{equal} occurrences of an element in @var{list}, ++@code{delete-dups} keeps the first one. ++@end defun ++ ++ See also the function @code{add-to-list}, in @ref{List Variables}, ++for a way to add an element to a list stored in a variable and used as a ++set. ++ ++@node Association Lists ++@section Association Lists ++@cindex association list ++@cindex alist ++ ++ An @dfn{association list}, or @dfn{alist} for short, records a mapping ++from keys to values. It is a list of cons cells called ++@dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the ++@sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key'' ++is not related to the term ``key sequence''; it means a value used to ++look up an item in a table. In this case, the table is the alist, and ++the alist associations are the items.} ++ ++ Here is an example of an alist. The key @code{pine} is associated with ++the value @code{cones}; the key @code{oak} is associated with ++@code{acorns}; and the key @code{maple} is associated with @code{seeds}. ++ ++@example ++@group ++((pine . cones) ++ (oak . acorns) ++ (maple . seeds)) ++@end group ++@end example ++ ++ Both the values and the keys in an alist may be any Lisp objects. ++For example, in the following alist, the symbol @code{a} is ++associated with the number @code{1}, and the string @code{"b"} is ++associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of ++the alist element: ++ ++@example ++((a . 1) ("b" 2 3)) ++@end example ++ ++ Sometimes it is better to design an alist to store the associated ++value in the @sc{car} of the @sc{cdr} of the element. Here is an ++example of such an alist: ++ ++@example ++((rose red) (lily white) (buttercup yellow)) ++@end example ++ ++@noindent ++Here we regard @code{red} as the value associated with @code{rose}. One ++advantage of this kind of alist is that you can store other related ++information---even a list of other items---in the @sc{cdr} of the ++@sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see ++below) to find the element containing a given value. When neither of ++these considerations is important, the choice is a matter of taste, as ++long as you are consistent about it for any given alist. ++ ++ The same alist shown above could be regarded as having the ++associated value in the @sc{cdr} of the element; the value associated ++with @code{rose} would be the list @code{(red)}. ++ ++ Association lists are often used to record information that you might ++otherwise keep on a stack, since new associations may be added easily to ++the front of the list. When searching an association list for an ++association with a given key, the first one found is returned, if there ++is more than one. ++ ++ In Emacs Lisp, it is @emph{not} an error if an element of an ++association list is not a cons cell. The alist search functions simply ++ignore such elements. Many other versions of Lisp signal errors in such ++cases. ++ ++ Note that property lists are similar to association lists in several ++respects. A property list behaves like an association list in which ++each key can occur only once. @xref{Property Lists}, for a comparison ++of property lists and association lists. ++ ++@defun assoc key alist ++This function returns the first association for @var{key} in ++@var{alist}, comparing @var{key} against the alist elements using ++@code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no ++association in @var{alist} has a @sc{car} @code{equal} to @var{key}. ++For example: ++ ++@smallexample ++(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) ++ @result{} ((pine . cones) (oak . acorns) (maple . seeds)) ++(assoc 'oak trees) ++ @result{} (oak . acorns) ++(cdr (assoc 'oak trees)) ++ @result{} acorns ++(assoc 'birch trees) ++ @result{} nil ++@end smallexample ++ ++Here is another example, in which the keys and values are not symbols: ++ ++@smallexample ++(setq needles-per-cluster ++ '((2 "Austrian Pine" "Red Pine") ++ (3 "Pitch Pine") ++ (5 "White Pine"))) ++ ++(cdr (assoc 3 needles-per-cluster)) ++ @result{} ("Pitch Pine") ++(cdr (assoc 2 needles-per-cluster)) ++ @result{} ("Austrian Pine" "Red Pine") ++@end smallexample ++@end defun ++ ++ The function @code{assoc-string} is much like @code{assoc} except ++that it ignores certain differences between strings. @xref{Text ++Comparison}. ++ ++@defun rassoc value alist ++This function returns the first association with value @var{value} in ++@var{alist}. It returns @code{nil} if no association in @var{alist} has ++a @sc{cdr} @code{equal} to @var{value}. ++ ++@code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of ++each @var{alist} association instead of the @sc{car}. You can think of ++this as ``reverse @code{assoc},'' finding the key for a given value. ++@end defun ++ ++@defun assq key alist ++This function is like @code{assoc} in that it returns the first ++association for @var{key} in @var{alist}, but it makes the comparison ++using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil} ++if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}. ++This function is used more often than @code{assoc}, since @code{eq} is ++faster than @code{equal} and most alists use symbols as keys. ++@xref{Equality Predicates}. ++ ++@smallexample ++(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) ++ @result{} ((pine . cones) (oak . acorns) (maple . seeds)) ++(assq 'pine trees) ++ @result{} (pine . cones) ++@end smallexample ++ ++On the other hand, @code{assq} is not usually useful in alists where the ++keys may not be symbols: ++ ++@smallexample ++(setq leaves ++ '(("simple leaves" . oak) ++ ("compound leaves" . horsechestnut))) ++ ++(assq "simple leaves" leaves) ++ @result{} nil ++(assoc "simple leaves" leaves) ++ @result{} ("simple leaves" . oak) ++@end smallexample ++@end defun ++ ++@defun rassq value alist ++This function returns the first association with value @var{value} in ++@var{alist}. It returns @code{nil} if no association in @var{alist} has ++a @sc{cdr} @code{eq} to @var{value}. ++ ++@code{rassq} is like @code{assq} except that it compares the @sc{cdr} of ++each @var{alist} association instead of the @sc{car}. You can think of ++this as ``reverse @code{assq},'' finding the key for a given value. ++ ++For example: ++ ++@smallexample ++(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) ++ ++(rassq 'acorns trees) ++ @result{} (oak . acorns) ++(rassq 'spores trees) ++ @result{} nil ++@end smallexample ++ ++@code{rassq} cannot search for a value stored in the @sc{car} ++of the @sc{cdr} of an element: ++ ++@smallexample ++(setq colors '((rose red) (lily white) (buttercup yellow))) ++ ++(rassq 'white colors) ++ @result{} nil ++@end smallexample ++ ++In this case, the @sc{cdr} of the association @code{(lily white)} is not ++the symbol @code{white}, but rather the list @code{(white)}. This ++becomes clearer if the association is written in dotted pair notation: ++ ++@smallexample ++(lily white) @equiv{} (lily . (white)) ++@end smallexample ++@end defun ++ ++@defun assoc-default key alist &optional test default ++This function searches @var{alist} for a match for @var{key}. For each ++element of @var{alist}, it compares the element (if it is an atom) or ++the element's @sc{car} (if it is a cons) against @var{key}, by calling ++@var{test} with two arguments: the element or its @sc{car}, and ++@var{key}. The arguments are passed in that order so that you can get ++useful results using @code{string-match} with an alist that contains ++regular expressions (@pxref{Regexp Search}). If @var{test} is omitted ++or @code{nil}, @code{equal} is used for comparison. ++ ++If an alist element matches @var{key} by this criterion, ++then @code{assoc-default} returns a value based on this element. ++If the element is a cons, then the value is the element's @sc{cdr}. ++Otherwise, the return value is @var{default}. ++ ++If no alist element matches @var{key}, @code{assoc-default} returns ++@code{nil}. ++@end defun ++ ++@defun copy-alist alist ++@cindex copying alists ++This function returns a two-level deep copy of @var{alist}: it creates a ++new copy of each association, so that you can alter the associations of ++the new alist without changing the old one. ++ ++@smallexample ++@group ++(setq needles-per-cluster ++ '((2 . ("Austrian Pine" "Red Pine")) ++ (3 . ("Pitch Pine")) ++@end group ++ (5 . ("White Pine")))) ++@result{} ++((2 "Austrian Pine" "Red Pine") ++ (3 "Pitch Pine") ++ (5 "White Pine")) ++ ++(setq copy (copy-alist needles-per-cluster)) ++@result{} ++((2 "Austrian Pine" "Red Pine") ++ (3 "Pitch Pine") ++ (5 "White Pine")) ++ ++(eq needles-per-cluster copy) ++ @result{} nil ++(equal needles-per-cluster copy) ++ @result{} t ++(eq (car needles-per-cluster) (car copy)) ++ @result{} nil ++(cdr (car (cdr needles-per-cluster))) ++ @result{} ("Pitch Pine") ++@group ++(eq (cdr (car (cdr needles-per-cluster))) ++ (cdr (car (cdr copy)))) ++ @result{} t ++@end group ++@end smallexample ++ ++ This example shows how @code{copy-alist} makes it possible to change ++the associations of one copy without affecting the other: ++ ++@smallexample ++@group ++(setcdr (assq 3 copy) '("Martian Vacuum Pine")) ++(cdr (assq 3 needles-per-cluster)) ++ @result{} ("Pitch Pine") ++@end group ++@end smallexample ++@end defun ++ ++@defun assq-delete-all key alist ++This function deletes from @var{alist} all the elements whose @sc{car} ++is @code{eq} to @var{key}, much as if you used @code{delq} to delete ++each such element one by one. It returns the shortened alist, and ++often modifies the original list structure of @var{alist}. For ++correct results, use the return value of @code{assq-delete-all} rather ++than looking at the saved value of @var{alist}. ++ ++@example ++(setq alist '((foo 1) (bar 2) (foo 3) (lose 4))) ++ @result{} ((foo 1) (bar 2) (foo 3) (lose 4)) ++(assq-delete-all 'foo alist) ++ @result{} ((bar 2) (lose 4)) ++alist ++ @result{} ((foo 1) (bar 2) (lose 4)) ++@end example ++@end defun ++ ++@defun rassq-delete-all value alist ++This function deletes from @var{alist} all the elements whose @sc{cdr} ++is @code{eq} to @var{value}. It returns the shortened alist, and ++often modifies the original list structure of @var{alist}. ++@code{rassq-delete-all} is like @code{assq-delete-all} except that it ++compares the @sc{cdr} of each @var{alist} association instead of the ++@sc{car}. ++@end defun ++ ++@node Rings ++@section Managing a Fixed-Size Ring of Objects ++ ++@cindex ring data structure ++ This section describes functions for operating on rings. A ++@dfn{ring} is a fixed-size data structure that supports insertion, ++deletion, rotation, and modulo-indexed reference and traversal. ++ ++@defun make-ring size ++This returns a new ring capable of holding @var{size} objects. ++@var{size} should be an integer. ++@end defun ++ ++@defun ring-p object ++This returns @code{t} if @var{object} is a ring, @code{nil} otherwise. ++@end defun ++ ++@defun ring-size ring ++This returns the maximum capacity of the @var{ring}. ++@end defun ++ ++@defun ring-length ring ++This returns the number of objects that @var{ring} currently contains. ++The value will never exceed that returned by @code{ring-size}. ++@end defun ++ ++@defun ring-elements ring ++This returns a list of the objects in @var{ring}, in order, newest first. ++@end defun ++ ++@defun ring-copy ring ++This returns a new ring which is a copy of @var{ring}. ++The new ring contains the same (@code{eq}) objects as @var{ring}. ++@end defun ++ ++@defun ring-empty-p ring ++This returns @code{t} if @var{ring} is empty, @code{nil} otherwise. ++@end defun ++ ++ The newest element in the ring always has index 0. Higher indices ++correspond to older elements. Indices are computed modulo the ring ++length. Index @minus{}1 corresponds to the oldest element, @minus{}2 ++to the next-oldest, and so forth. ++ ++@defun ring-ref ring index ++This returns the object in @var{ring} found at index @var{index}. ++@var{index} may be negative or greater than the ring length. If ++@var{ring} is empty, @code{ring-ref} signals an error. ++@end defun ++ ++@defun ring-insert ring object ++This inserts @var{object} into @var{ring}, making it the newest ++element, and returns @var{object}. ++ ++If the ring is full, insertion removes the oldest element to ++make room for the new element. ++@end defun ++ ++@defun ring-remove ring &optional index ++Remove an object from @var{ring}, and return that object. The ++argument @var{index} specifies which item to remove; if it is ++@code{nil}, that means to remove the oldest item. If @var{ring} is ++empty, @code{ring-remove} signals an error. ++@end defun ++ ++@defun ring-insert-at-beginning ring object ++This inserts @var{object} into @var{ring}, treating it as the oldest ++element. The return value is not significant. ++ ++If the ring is full, this function removes the newest element to make ++room for the inserted element. ++@end defun ++ ++@cindex fifo data structure ++ If you are careful not to exceed the ring size, you can ++use the ring as a first-in-first-out queue. For example: ++ ++@lisp ++(let ((fifo (make-ring 5))) ++ (mapc (lambda (obj) (ring-insert fifo obj)) ++ '(0 one "two")) ++ (list (ring-remove fifo) t ++ (ring-remove fifo) t ++ (ring-remove fifo))) ++ @result{} (0 t one t "two") ++@end lisp ++ ++@ignore ++ arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4 ++@end ignore +diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi +new file mode 100644 +index 0000000..403a740 +--- /dev/null ++++ b/doc/lispref/loading.texi +@@ -0,0 +1,988 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/loading ++@node Loading, Byte Compilation, Customization, Top ++@chapter Loading ++@cindex loading ++@cindex library ++@cindex Lisp library ++ ++ Loading a file of Lisp code means bringing its contents into the Lisp ++environment in the form of Lisp objects. Emacs finds and opens the ++file, reads the text, evaluates each form, and then closes the file. ++ ++ The load functions evaluate all the expressions in a file just ++as the @code{eval-buffer} function evaluates all the ++expressions in a buffer. The difference is that the load functions ++read and evaluate the text in the file as found on disk, not the text ++in an Emacs buffer. ++ ++@cindex top-level form ++ The loaded file must contain Lisp expressions, either as source code ++or as byte-compiled code. Each form in the file is called a ++@dfn{top-level form}. There is no special format for the forms in a ++loadable file; any form in a file may equally well be typed directly ++into a buffer and evaluated there. (Indeed, most code is tested this ++way.) Most often, the forms are function definitions and variable ++definitions. ++ ++ A file containing Lisp code is often called a @dfn{library}. Thus, ++the ``Rmail library'' is a file containing code for Rmail mode. ++Similarly, a ``Lisp library directory'' is a directory of files ++containing Lisp code. ++ ++@menu ++* How Programs Do Loading:: The @code{load} function and others. ++* Load Suffixes:: Details about the suffixes that @code{load} tries. ++* Library Search:: Finding a library to load. ++* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. ++* Autoload:: Setting up a function to autoload. ++* Repeated Loading:: Precautions about loading a file twice. ++* Named Features:: Loading a library if it isn't already loaded. ++* Where Defined:: Finding which file defined a certain symbol. ++* Unloading:: How to "unload" a library that was loaded. ++* Hooks for Loading:: Providing code to be run when ++ particular libraries are loaded. ++@end menu ++ ++@node How Programs Do Loading ++@section How Programs Do Loading ++ ++ Emacs Lisp has several interfaces for loading. For example, ++@code{autoload} creates a placeholder object for a function defined in a ++file; trying to call the autoloading function loads the file to get the ++function's real definition (@pxref{Autoload}). @code{require} loads a ++file if it isn't already loaded (@pxref{Named Features}). Ultimately, ++all these facilities call the @code{load} function to do the work. ++ ++@defun load filename &optional missing-ok nomessage nosuffix must-suffix ++This function finds and opens a file of Lisp code, evaluates all the ++forms in it, and closes the file. ++ ++To find the file, @code{load} first looks for a file named ++@file{@var{filename}.elc}, that is, for a file whose name is ++@var{filename} with the extension @samp{.elc} appended. If such a ++file exists, it is loaded. If there is no file by that name, then ++@code{load} looks for a file named @file{@var{filename}.el}. If that ++file exists, it is loaded. Finally, if neither of those names is ++found, @code{load} looks for a file named @var{filename} with nothing ++appended, and loads it if it exists. (The @code{load} function is not ++clever about looking at @var{filename}. In the perverse case of a ++file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will ++indeed find it.) ++ ++If Auto Compression mode is enabled, as it is by default, then if ++@code{load} can not find a file, it searches for a compressed version ++of the file before trying other file names. It decompresses and loads ++it if it exists. It looks for compressed versions by appending each ++of the suffixes in @code{jka-compr-load-suffixes} to the file name. ++The value of this variable must be a list of strings. Its standard ++value is @code{(".gz")}. ++ ++If the optional argument @var{nosuffix} is non-@code{nil}, then ++@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In ++this case, you must specify the precise file name you want, except ++that, if Auto Compression mode is enabled, @code{load} will still use ++@code{jka-compr-load-suffixes} to find compressed versions. By ++specifying the precise file name and using @code{t} for ++@var{nosuffix}, you can prevent perverse file names such as ++@file{foo.el.el} from being tried. ++ ++If the optional argument @var{must-suffix} is non-@code{nil}, then ++@code{load} insists that the file name used must end in either ++@samp{.el} or @samp{.elc} (possibly extended with a compression ++suffix), unless it contains an explicit directory name. ++ ++If @var{filename} is a relative file name, such as @file{foo} or ++@file{baz/foo.bar}, @code{load} searches for the file using the variable ++@code{load-path}. It appends @var{filename} to each of the directories ++listed in @code{load-path}, and loads the first file it finds whose name ++matches. The current default directory is tried only if it is specified ++in @code{load-path}, where @code{nil} stands for the default directory. ++@code{load} tries all three possible suffixes in the first directory in ++@code{load-path}, then all three suffixes in the second directory, and ++so on. @xref{Library Search}. ++ ++If you get a warning that @file{foo.elc} is older than @file{foo.el}, it ++means you should consider recompiling @file{foo.el}. @xref{Byte ++Compilation}. ++ ++When loading a source file (not compiled), @code{load} performs ++character set translation just as Emacs would do when visiting the file. ++@xref{Coding Systems}. ++ ++Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear ++in the echo area during loading unless @var{nomessage} is ++non-@code{nil}. ++ ++@cindex load errors ++Any unhandled errors while loading a file terminate loading. If the ++load was done for the sake of @code{autoload}, any function definitions ++made during the loading are undone. ++ ++@kindex file-error ++If @code{load} can't find the file to load, then normally it signals the ++error @code{file-error} (with @samp{Cannot open load file ++@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then ++@code{load} just returns @code{nil}. ++ ++You can use the variable @code{load-read-function} to specify a function ++for @code{load} to use instead of @code{read} for reading expressions. ++See below. ++ ++@code{load} returns @code{t} if the file loads successfully. ++@end defun ++ ++@deffn Command load-file filename ++This command loads the file @var{filename}. If @var{filename} is a ++relative file name, then the current default directory is assumed. ++This command does not use @code{load-path}, and does not append ++suffixes. However, it does look for compressed versions (if Auto ++Compression Mode is enabled). Use this command if you wish to specify ++precisely the file name to load. ++@end deffn ++ ++@deffn Command load-library library ++This command loads the library named @var{library}. It is equivalent to ++@code{load}, except in how it reads its argument interactively. ++@end deffn ++ ++@defvar load-in-progress ++This variable is non-@code{nil} if Emacs is in the process of loading a ++file, and it is @code{nil} otherwise. ++@end defvar ++ ++@defvar load-read-function ++@anchor{Definition of load-read-function} ++@c do not allow page break at anchor; work around Texinfo deficiency. ++This variable specifies an alternate expression-reading function for ++@code{load} and @code{eval-region} to use instead of @code{read}. ++The function should accept one argument, just as @code{read} does. ++ ++Normally, the variable's value is @code{nil}, which means those ++functions should use @code{read}. ++ ++Instead of using this variable, it is cleaner to use another, newer ++feature: to pass the function as the @var{read-function} argument to ++@code{eval-region}. @xref{Definition of eval-region,, Eval}. ++@end defvar ++ ++ For information about how @code{load} is used in building Emacs, see ++@ref{Building Emacs}. ++ ++@node Load Suffixes ++@section Load Suffixes ++We now describe some technical details about the exact suffixes that ++@code{load} tries. ++ ++@defvar load-suffixes ++This is a list of suffixes indicating (compiled or source) Emacs Lisp ++files. It should not include the empty string. @code{load} uses ++these suffixes in order when it appends Lisp suffixes to the specified ++file name. The standard value is @code{(".elc" ".el")} which produces ++the behavior described in the previous section. ++@end defvar ++ ++@defvar load-file-rep-suffixes ++This is a list of suffixes that indicate representations of the same ++file. This list should normally start with the empty string. ++When @code{load} searches for a file it appends the suffixes in this ++list, in order, to the file name, before searching for another file. ++ ++Enabling Auto Compression mode appends the suffixes in ++@code{jka-compr-load-suffixes} to this list and disabling Auto ++Compression mode removes them again. The standard value of ++@code{load-file-rep-suffixes} if Auto Compression mode is disabled is ++@code{("")}. Given that the standard value of ++@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value ++of @code{load-file-rep-suffixes} if Auto Compression mode is enabled ++is @code{("" ".gz")}. ++@end defvar ++ ++@defun get-load-suffixes ++This function returns the list of all suffixes that @code{load} should ++try, in order, when its @var{must-suffix} argument is non-@code{nil}. ++This takes both @code{load-suffixes} and @code{load-file-rep-suffixes} ++into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes} ++and @code{load-file-rep-suffixes} all have their standard values, this ++function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto ++Compression mode is enabled and @code{(".elc" ".el")} if Auto ++Compression mode is disabled. ++@end defun ++ ++To summarize, @code{load} normally first tries the suffixes in the ++value of @code{(get-load-suffixes)} and then those in ++@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil}, ++it skips the former group, and if @var{must-suffix} is non-@code{nil}, ++it skips the latter group. ++ ++@node Library Search ++@section Library Search ++@cindex library search ++@cindex find library ++ ++ When Emacs loads a Lisp library, it searches for the library ++in a list of directories specified by the variable @code{load-path}. ++ ++@defopt load-path ++@cindex @code{EMACSLOADPATH} environment variable ++The value of this variable is a list of directories to search when ++loading files with @code{load}. Each element is a string (which must be ++a directory name) or @code{nil} (which stands for the current working ++directory). ++@end defopt ++ ++ The value of @code{load-path} is initialized from the environment ++variable @code{EMACSLOADPATH}, if that exists; otherwise its default ++value is specified in @file{emacs/src/epaths.h} when Emacs is built. ++Then the list is expanded by adding subdirectories of the directories ++in the list. ++ ++ The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH}; ++@samp{:} (or @samp{;}, according to the operating system) separates ++directory names, and @samp{.} is used for the current default directory. ++Here is an example of how to set your @code{EMACSLOADPATH} variable from ++a @code{csh} @file{.login} file: ++ ++@smallexample ++setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp ++@end smallexample ++ ++ Here is how to set it using @code{sh}: ++ ++@smallexample ++export EMACSLOADPATH ++EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp ++@end smallexample ++ ++ Here is an example of code you can place in your init file (@pxref{Init ++File}) to add several directories to the front of your default ++@code{load-path}: ++ ++@smallexample ++@group ++(setq load-path ++ (append (list nil "/user/bil/emacs" ++ "/usr/local/lisplib" ++ "~/emacs") ++ load-path)) ++@end group ++@end smallexample ++ ++@c Wordy to rid us of an overfull hbox. --rjc 15mar92 ++@noindent ++In this example, the path searches the current working directory first, ++followed then by the @file{/user/bil/emacs} directory, the ++@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory, ++which are then followed by the standard directories for Lisp code. ++ ++ Dumping Emacs uses a special value of @code{load-path}. If the value of ++@code{load-path} at the end of dumping is unchanged (that is, still the ++same special value), the dumped Emacs switches to the ordinary ++@code{load-path} value when it starts up, as described above. But if ++@code{load-path} has any other value at the end of dumping, that value ++is used for execution of the dumped Emacs also. ++ ++ Therefore, if you want to change @code{load-path} temporarily for ++loading a few libraries in @file{site-init.el} or @file{site-load.el}, ++you should bind @code{load-path} locally with @code{let} around the ++calls to @code{load}. ++ ++ The default value of @code{load-path}, when running an Emacs which has ++been installed on the system, includes two special directories (and ++their subdirectories as well): ++ ++@smallexample ++"/usr/local/share/emacs/@var{version}/site-lisp" ++@end smallexample ++ ++@noindent ++and ++ ++@smallexample ++"/usr/local/share/emacs/site-lisp" ++@end smallexample ++ ++@noindent ++The first one is for locally installed packages for a particular Emacs ++version; the second is for locally installed packages meant for use with ++all installed Emacs versions. ++ ++ There are several reasons why a Lisp package that works well in one ++Emacs version can cause trouble in another. Sometimes packages need ++updating for incompatible changes in Emacs; sometimes they depend on ++undocumented internal Emacs data that can change without notice; ++sometimes a newer Emacs version incorporates a version of the package, ++and should be used only with that version. ++ ++ Emacs finds these directories' subdirectories and adds them to ++@code{load-path} when it starts up. Both immediate subdirectories and ++subdirectories multiple levels down are added to @code{load-path}. ++ ++ Not all subdirectories are included, though. Subdirectories whose ++names do not start with a letter or digit are excluded. Subdirectories ++named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which ++contains a file named @file{.nosearch} is excluded. You can use these ++methods to prevent certain subdirectories of the @file{site-lisp} ++directories from being searched. ++ ++ If you run Emacs from the directory where it was built---that is, an ++executable that has not been formally installed---then @code{load-path} ++normally contains two additional directories. These are the @code{lisp} ++and @code{site-lisp} subdirectories of the main build directory. (Both ++are represented as absolute file names.) ++ ++@deffn Command locate-library library &optional nosuffix path interactive-call ++This command finds the precise file name for library @var{library}. It ++searches for the library in the same way @code{load} does, and the ++argument @var{nosuffix} has the same meaning as in @code{load}: don't ++add suffixes @samp{.elc} or @samp{.el} to the specified name ++@var{library}. ++ ++If the @var{path} is non-@code{nil}, that list of directories is used ++instead of @code{load-path}. ++ ++When @code{locate-library} is called from a program, it returns the file ++name as a string. When the user runs @code{locate-library} ++interactively, the argument @var{interactive-call} is @code{t}, and this ++tells @code{locate-library} to display the file name in the echo area. ++@end deffn ++ ++@node Loading Non-ASCII ++@section Loading Non-@acronym{ASCII} Characters ++ ++ When Emacs Lisp programs contain string constants with non-@acronym{ASCII} ++characters, these can be represented within Emacs either as unibyte ++strings or as multibyte strings (@pxref{Text Representations}). Which ++representation is used depends on how the file is read into Emacs. If ++it is read with decoding into multibyte representation, the text of the ++Lisp program will be multibyte text, and its string constants will be ++multibyte strings. If a file containing Latin-1 characters (for ++example) is read without decoding, the text of the program will be ++unibyte text, and its string constants will be unibyte strings. ++@xref{Coding Systems}. ++ ++ To make the results more predictable, Emacs always performs decoding ++into the multibyte representation when loading Lisp files, even if it ++was started with the @samp{--unibyte} option. This means that string ++constants with non-@acronym{ASCII} characters translate into multibyte ++strings. The only exception is when a particular file specifies no ++decoding. ++ ++ The reason Emacs is designed this way is so that Lisp programs give ++predictable results, regardless of how Emacs was started. In addition, ++this enables programs that depend on using multibyte text to work even ++in a unibyte Emacs. Of course, such programs should be designed to ++notice whether the user prefers unibyte or multibyte text, by checking ++@code{default-enable-multibyte-characters}, and convert representations ++appropriately. ++ ++ In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are ++multibyte strings should not be noticeable, since inserting them in ++unibyte buffers converts them to unibyte automatically. However, if ++this does make a difference, you can force a particular Lisp file to be ++interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a ++comment on the file's first line. With that designator, the file will ++unconditionally be interpreted as unibyte, even in an ordinary ++multibyte Emacs session. This can matter when making keybindings to ++non-@acronym{ASCII} characters written as @code{?v@var{literal}}. ++ ++@node Autoload ++@section Autoload ++@cindex autoload ++ ++ The @dfn{autoload} facility allows you to make a function or macro ++known in Lisp, but put off loading the file that defines it. The first ++call to the function automatically reads the proper file to install the ++real definition and other associated code, then runs the real definition ++as if it had been loaded all along. ++ ++ There are two ways to set up an autoloaded function: by calling ++@code{autoload}, and by writing a special ``magic'' comment in the ++source before the real definition. @code{autoload} is the low-level ++primitive for autoloading; any Lisp program can call @code{autoload} at ++any time. Magic comments are the most convenient way to make a function ++autoload, for packages installed along with Emacs. These comments do ++nothing on their own, but they serve as a guide for the command ++@code{update-file-autoloads}, which constructs calls to @code{autoload} ++and arranges to execute them when Emacs is built. ++ ++@defun autoload function filename &optional docstring interactive type ++This function defines the function (or macro) named @var{function} so as ++to load automatically from @var{filename}. The string @var{filename} ++specifies the file to load to get the real definition of @var{function}. ++ ++If @var{filename} does not contain either a directory name, or the ++suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding ++one of these suffixes, and it will not load from a file whose name is ++just @var{filename} with no added suffix. (The variable ++@code{load-suffixes} specifies the exact required suffixes.) ++ ++The argument @var{docstring} is the documentation string for the ++function. Specifying the documentation string in the call to ++@code{autoload} makes it possible to look at the documentation without ++loading the function's real definition. Normally, this should be ++identical to the documentation string in the function definition ++itself. If it isn't, the function definition's documentation string ++takes effect when it is loaded. ++ ++If @var{interactive} is non-@code{nil}, that says @var{function} can be ++called interactively. This lets completion in @kbd{M-x} work without ++loading @var{function}'s real definition. The complete interactive ++specification is not given here; it's not needed unless the user ++actually calls @var{function}, and when that happens, it's time to load ++the real definition. ++ ++You can autoload macros and keymaps as well as ordinary functions. ++Specify @var{type} as @code{macro} if @var{function} is really a macro. ++Specify @var{type} as @code{keymap} if @var{function} is really a ++keymap. Various parts of Emacs need to know this information without ++loading the real definition. ++ ++An autoloaded keymap loads automatically during key lookup when a prefix ++key's binding is the symbol @var{function}. Autoloading does not occur ++for other kinds of access to the keymap. In particular, it does not ++happen when a Lisp program gets the keymap from the value of a variable ++and calls @code{define-key}; not even if the variable name is the same ++symbol @var{function}. ++ ++@cindex function cell in autoload ++If @var{function} already has a non-void function definition that is not ++an autoload object, @code{autoload} does nothing and returns @code{nil}. ++If the function cell of @var{function} is void, or is already an autoload ++object, then it is defined as an autoload object like this: ++ ++@example ++(autoload @var{filename} @var{docstring} @var{interactive} @var{type}) ++@end example ++ ++For example, ++ ++@example ++@group ++(symbol-function 'run-prolog) ++ @result{} (autoload "prolog" 169681 t nil) ++@end group ++@end example ++ ++@noindent ++In this case, @code{"prolog"} is the name of the file to load, 169681 ++refers to the documentation string in the ++@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}), ++@code{t} means the function is interactive, and @code{nil} that it is ++not a macro or a keymap. ++@end defun ++ ++@cindex autoload errors ++ The autoloaded file usually contains other definitions and may require ++or provide one or more features. If the file is not completely loaded ++(due to an error in the evaluation of its contents), any function ++definitions or @code{provide} calls that occurred during the load are ++undone. This is to ensure that the next attempt to call any function ++autoloading from this file will try again to load the file. If not for ++this, then some of the functions in the file might be defined by the ++aborted load, but fail to work properly for the lack of certain ++subroutines not loaded successfully because they come later in the file. ++ ++ If the autoloaded file fails to define the desired Lisp function or ++macro, then an error is signaled with data @code{"Autoloading failed to ++define function @var{function-name}"}. ++ ++@findex update-file-autoloads ++@findex update-directory-autoloads ++@cindex magic autoload comment ++@cindex autoload cookie ++@anchor{autoload cookie} ++ A magic autoload comment (often called an @dfn{autoload cookie}) ++consists of @samp{;;;###autoload}, on a line by itself, ++just before the real definition of the function in its ++autoloadable source file. The command @kbd{M-x update-file-autoloads} ++writes a corresponding @code{autoload} call into @file{loaddefs.el}. ++(The string that serves as the autoload cookie and the name of the ++file generated by @code{update-file-autoloads} can be changed from the ++above defaults, see below.) ++Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. ++@kbd{M-x update-directory-autoloads} is even more powerful; it updates ++autoloads for all files in the current directory. ++ ++ The same magic comment can copy any kind of form into ++@file{loaddefs.el}. If the form following the magic comment is not a ++function-defining form or a @code{defcustom} form, it is copied ++verbatim. ``Function-defining forms'' include @code{define-skeleton}, ++@code{define-derived-mode}, @code{define-generic-mode} and ++@code{define-minor-mode} as well as @code{defun} and ++@code{defmacro}. To save space, a @code{defcustom} form is converted to ++a @code{defvar} in @file{loaddefs.el}, with some additional information ++if it uses @code{:require}. ++ ++ You can also use a magic comment to execute a form at build time ++@emph{without} executing it when the file itself is loaded. To do this, ++write the form @emph{on the same line} as the magic comment. Since it ++is in a comment, it does nothing when you load the source file; but ++@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where ++it is executed while building Emacs. ++ ++ The following example shows how @code{doctor} is prepared for ++autoloading with a magic comment: ++ ++@smallexample ++;;;###autoload ++(defun doctor () ++ "Switch to *doctor* buffer and start giving psychotherapy." ++ (interactive) ++ (switch-to-buffer "*doctor*") ++ (doctor-mode)) ++@end smallexample ++ ++@noindent ++Here's what that produces in @file{loaddefs.el}: ++ ++@smallexample ++(autoload (quote doctor) "doctor" "\ ++Switch to *doctor* buffer and start giving psychotherapy. ++ ++\(fn)" t nil) ++@end smallexample ++ ++@noindent ++@cindex @code{fn} in function's documentation string ++The backslash and newline immediately following the double-quote are a ++convention used only in the preloaded uncompiled Lisp files such as ++@file{loaddefs.el}; they tell @code{make-docfile} to put the ++documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. ++See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)} ++in the usage part of the documentation string is replaced with the ++function's name when the various help functions (@pxref{Help ++Functions}) display it. ++ ++ If you write a function definition with an unusual macro that is not ++one of the known and recognized function definition methods, use of an ++ordinary magic autoload comment would copy the whole definition into ++@code{loaddefs.el}. That is not desirable. You can put the desired ++@code{autoload} call into @code{loaddefs.el} instead by writing this: ++ ++@smallexample ++;;;###autoload (autoload 'foo "myfile") ++(mydefunmacro foo ++ ...) ++@end smallexample ++ ++ You can use a non-default string as the autoload cookie and have the ++corresponding autoload calls written into a file whose name is ++different from the default @file{loaddefs.el}. Emacs provides two ++variables to control this: ++ ++@defvar generate-autoload-cookie ++The value of this variable should be a string whose syntax is a Lisp ++comment. @kbd{M-x update-file-autoloads} copies the Lisp form that ++follows the cookie into the autoload file it generates. The default ++value of this variable is @code{";;;###autoload"}. ++@end defvar ++ ++@defvar generated-autoload-file ++The value of this variable names an Emacs Lisp file where the autoload ++calls should go. The default value is @file{loaddefs.el}, but you can ++override that, e.g., in the ``Local Variables'' section of a ++@file{.el} file (@pxref{File Local Variables}). The autoload file is ++assumed to contain a trailer starting with a formfeed character. ++@end defvar ++ ++@node Repeated Loading ++@section Repeated Loading ++@cindex repeated loading ++ ++ You can load a given file more than once in an Emacs session. For ++example, after you have rewritten and reinstalled a function definition ++by editing it in a buffer, you may wish to return to the original ++version; you can do this by reloading the file it came from. ++ ++ When you load or reload files, bear in mind that the @code{load} and ++@code{load-library} functions automatically load a byte-compiled file ++rather than a non-compiled file of similar name. If you rewrite a file ++that you intend to save and reinstall, you need to byte-compile the new ++version; otherwise Emacs will load the older, byte-compiled file instead ++of your newer, non-compiled file! If that happens, the message ++displayed when loading the file includes, @samp{(compiled; note, source is ++newer)}, to remind you to recompile it. ++ ++ When writing the forms in a Lisp library file, keep in mind that the ++file might be loaded more than once. For example, think about whether ++each variable should be reinitialized when you reload the library; ++@code{defvar} does not change the value if the variable is already ++initialized. (@xref{Defining Variables}.) ++ ++ The simplest way to add an element to an alist is like this: ++ ++@example ++(push '(leif-mode " Leif") minor-mode-alist) ++@end example ++ ++@noindent ++But this would add multiple elements if the library is reloaded. To ++avoid the problem, use @code{add-to-list} (@pxref{List Variables}): ++ ++@example ++(add-to-list 'minor-mode-alist '(leif-mode " Leif")) ++@end example ++ ++ Occasionally you will want to test explicitly whether a library has ++already been loaded. If the library uses @code{provide} to provide a ++named feature, you can use @code{featurep} earlier in the file to test ++whether the @code{provide} call has been executed before (@pxref{Named ++Features}). Alternatively, you could use something like this: ++ ++@example ++(defvar foo-was-loaded nil) ++ ++(unless foo-was-loaded ++ @var{execute-first-time-only} ++ (setq foo-was-loaded t)) ++@end example ++ ++@noindent ++ ++@node Named Features ++@section Features ++@cindex features ++@cindex requiring features ++@cindex providing features ++ ++ @code{provide} and @code{require} are an alternative to ++@code{autoload} for loading files automatically. They work in terms of ++named @dfn{features}. Autoloading is triggered by calling a specific ++function, but a feature is loaded the first time another program asks ++for it by name. ++ ++ A feature name is a symbol that stands for a collection of functions, ++variables, etc. The file that defines them should @dfn{provide} the ++feature. Another program that uses them may ensure they are defined by ++@dfn{requiring} the feature. This loads the file of definitions if it ++hasn't been loaded already. ++ ++@cindex load error with require ++ To require the presence of a feature, call @code{require} with the ++feature name as argument. @code{require} looks in the global variable ++@code{features} to see whether the desired feature has been provided ++already. If not, it loads the feature from the appropriate file. This ++file should call @code{provide} at the top level to add the feature to ++@code{features}; if it fails to do so, @code{require} signals an error. ++ ++ For example, in @file{emacs/lisp/prolog.el}, ++the definition for @code{run-prolog} includes the following code: ++ ++@smallexample ++(defun run-prolog () ++ "Run an inferior Prolog process, with I/O via buffer *prolog*." ++ (interactive) ++ (require 'comint) ++ (switch-to-buffer (make-comint "prolog" prolog-program-name)) ++ (inferior-prolog-mode)) ++@end smallexample ++ ++@noindent ++The expression @code{(require 'comint)} loads the file @file{comint.el} ++if it has not yet been loaded. This ensures that @code{make-comint} is ++defined. Features are normally named after the files that provide them, ++so that @code{require} need not be given the file name. ++ ++The @file{comint.el} file contains the following top-level expression: ++ ++@smallexample ++(provide 'comint) ++@end smallexample ++ ++@noindent ++This adds @code{comint} to the global @code{features} list, so that ++@code{(require 'comint)} will henceforth know that nothing needs to be ++done. ++ ++@cindex byte-compiling @code{require} ++ When @code{require} is used at top level in a file, it takes effect ++when you byte-compile that file (@pxref{Byte Compilation}) as well as ++when you load it. This is in case the required package contains macros ++that the byte compiler must know about. It also avoids byte compiler ++warnings for functions and variables defined in the file loaded with ++@code{require}. ++ ++ Although top-level calls to @code{require} are evaluated during ++byte compilation, @code{provide} calls are not. Therefore, you can ++ensure that a file of definitions is loaded before it is byte-compiled ++by including a @code{provide} followed by a @code{require} for the same ++feature, as in the following example. ++ ++@smallexample ++@group ++(provide 'my-feature) ; @r{Ignored by byte compiler,} ++ ; @r{evaluated by @code{load}.} ++(require 'my-feature) ; @r{Evaluated by byte compiler.} ++@end group ++@end smallexample ++ ++@noindent ++The compiler ignores the @code{provide}, then processes the ++@code{require} by loading the file in question. Loading the file does ++execute the @code{provide} call, so the subsequent @code{require} call ++does nothing when the file is loaded. ++ ++@defun provide feature &optional subfeatures ++This function announces that @var{feature} is now loaded, or being ++loaded, into the current Emacs session. This means that the facilities ++associated with @var{feature} are or will be available for other Lisp ++programs. ++ ++The direct effect of calling @code{provide} is if not already in ++@var{features} then to add @var{feature} to the front of that list and ++call any @code{eval-after-load} code waiting for it (@pxref{Hooks for ++Loading}). The argument @var{feature} must be a symbol. ++@code{provide} returns @var{feature}. ++ ++If provided, @var{subfeatures} should be a list of symbols indicating ++a set of specific subfeatures provided by this version of ++@var{feature}. You can test the presence of a subfeature using ++@code{featurep}. The idea of subfeatures is that you use them when a ++package (which is one @var{feature}) is complex enough to make it ++useful to give names to various parts or functionalities of the ++package, which might or might not be loaded, or might or might not be ++present in a given version. @xref{Network Feature Testing}, for ++an example. ++ ++@smallexample ++features ++ @result{} (bar bish) ++ ++(provide 'foo) ++ @result{} foo ++features ++ @result{} (foo bar bish) ++@end smallexample ++ ++When a file is loaded to satisfy an autoload, and it stops due to an ++error in the evaluation of its contents, any function definitions or ++@code{provide} calls that occurred during the load are undone. ++@xref{Autoload}. ++@end defun ++ ++@defun require feature &optional filename noerror ++This function checks whether @var{feature} is present in the current ++Emacs session (using @code{(featurep @var{feature})}; see below). The ++argument @var{feature} must be a symbol. ++ ++If the feature is not present, then @code{require} loads @var{filename} ++with @code{load}. If @var{filename} is not supplied, then the name of ++the symbol @var{feature} is used as the base file name to load. ++However, in this case, @code{require} insists on finding @var{feature} ++with an added @samp{.el} or @samp{.elc} suffix (possibly extended with ++a compression suffix); a file whose name is just @var{feature} won't ++be used. (The variable @code{load-suffixes} specifies the exact ++required Lisp suffixes.) ++ ++If @var{noerror} is non-@code{nil}, that suppresses errors from actual ++loading of the file. In that case, @code{require} returns @code{nil} ++if loading the file fails. Normally, @code{require} returns ++@var{feature}. ++ ++If loading the file succeeds but does not provide @var{feature}, ++@code{require} signals an error, @samp{Required feature @var{feature} ++was not provided}. ++@end defun ++ ++@defun featurep feature &optional subfeature ++This function returns @code{t} if @var{feature} has been provided in ++the current Emacs session (i.e.@:, if @var{feature} is a member of ++@code{features}.) If @var{subfeature} is non-@code{nil}, then the ++function returns @code{t} only if that subfeature is provided as well ++(i.e.@: if @var{subfeature} is a member of the @code{subfeature} ++property of the @var{feature} symbol.) ++@end defun ++ ++@defvar features ++The value of this variable is a list of symbols that are the features ++loaded in the current Emacs session. Each symbol was put in this list ++with a call to @code{provide}. The order of the elements in the ++@code{features} list is not significant. ++@end defvar ++ ++@node Where Defined ++@section Which File Defined a Certain Symbol ++ ++@defun symbol-file symbol &optional type ++This function returns the name of the file that defined @var{symbol}. ++If @var{type} is @code{nil}, then any kind of definition is acceptable. ++If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that ++specifies function definition, variable definition, or face definition ++only. ++ ++The value is normally an absolute file name. It can also be @code{nil}, ++if the definition is not associated with any file. If @var{symbol} ++specifies an autoloaded function, the value can be a relative file name ++without extension. ++@end defun ++ ++ The basis for @code{symbol-file} is the data in the variable ++@code{load-history}. ++ ++@defvar load-history ++This variable's value is an alist connecting library file names with the ++names of functions and variables they define, the features they provide, ++and the features they require. ++ ++Each element is a list and describes one library. The @sc{car} of the ++list is the absolute file name of the library, as a string. The rest ++of the list elements have these forms: ++ ++@table @code ++@item @var{var} ++The symbol @var{var} was defined as a variable. ++@item (defun . @var{fun}) ++The function @var{fun} was defined. ++@item (t . @var{fun}) ++The function @var{fun} was previously an autoload before this library ++redefined it as a function. The following element is always ++@code{(defun . @var{fun})}, which represents defining @var{fun} as a ++function. ++@item (autoload . @var{fun}) ++The function @var{fun} was defined as an autoload. ++@item (defface . @var{face}) ++The face @var{face} was defined. ++@item (require . @var{feature}) ++The feature @var{feature} was required. ++@item (provide . @var{feature}) ++The feature @var{feature} was provided. ++@end table ++ ++The value of @code{load-history} may have one element whose @sc{car} is ++@code{nil}. This element describes definitions made with ++@code{eval-buffer} on a buffer that is not visiting a file. ++@end defvar ++ ++ The command @code{eval-region} updates @code{load-history}, but does so ++by adding the symbols defined to the element for the file being visited, ++rather than replacing that element. @xref{Eval}. ++ ++@node Unloading ++@section Unloading ++@cindex unloading packages ++ ++@c Emacs 19 feature ++ You can discard the functions and variables loaded by a library to ++reclaim memory for other Lisp objects. To do this, use the function ++@code{unload-feature}: ++ ++@deffn Command unload-feature feature &optional force ++This command unloads the library that provided feature @var{feature}. ++It undefines all functions, macros, and variables defined in that ++library with @code{defun}, @code{defalias}, @code{defsubst}, ++@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}. ++It then restores any autoloads formerly associated with those symbols. ++(Loading saves these in the @code{autoload} property of the symbol.) ++ ++Before restoring the previous definitions, @code{unload-feature} runs ++@code{remove-hook} to remove functions in the library from certain ++hooks. These hooks include variables whose names end in @samp{hook} ++or @samp{-hooks}, plus those listed in ++@code{unload-feature-special-hooks}, as well as ++@code{auto-mode-alist}. This is to prevent Emacs from ceasing to ++function because important hooks refer to functions that are no longer ++defined. ++ ++Standard unloading activities also undoes ELP profiling of functions ++in that library, unprovides any features provided by the library, and ++cancels timers held in variables defined by the library. ++ ++@vindex @var{feature}-unload-function ++If these measures are not sufficient to prevent malfunction, a library ++can define an explicit unloader named @code{@var{feature}-unload-function}. ++If that symbol is defined as a function, @code{unload-feature} calls ++it with no arguments before doing anything else. It can do whatever ++is appropriate to unload the library. If it returns @code{nil}, ++@code{unload-feature} proceeds to take the normal unload actions. ++Otherwise it considers the job to be done. ++ ++Ordinarily, @code{unload-feature} refuses to unload a library on which ++other loaded libraries depend. (A library @var{a} depends on library ++@var{b} if @var{a} contains a @code{require} for @var{b}.) If the ++optional argument @var{force} is non-@code{nil}, dependencies are ++ignored and you can unload any library. ++@end deffn ++ ++ The @code{unload-feature} function is written in Lisp; its actions are ++based on the variable @code{load-history}. ++ ++@defvar unload-feature-special-hooks ++This variable holds a list of hooks to be scanned before unloading a ++library, to remove functions defined in the library. ++@end defvar ++ ++@node Hooks for Loading ++@section Hooks for Loading ++@cindex loading hooks ++@cindex hooks for loading ++ ++You can ask for code to be executed if and when a particular library is ++loaded, by calling @code{eval-after-load}. ++ ++@defun eval-after-load library form ++This function arranges to evaluate @var{form} at the end of loading ++the file @var{library}, each time @var{library} is loaded. If ++@var{library} is already loaded, it evaluates @var{form} right away. ++Don't forget to quote @var{form}! ++ ++You don't need to give a directory or extension in the file name ++@var{library}---normally you just give a bare file name, like this: ++ ++@example ++(eval-after-load "edebug" '(def-edebug-spec c-point t)) ++@end example ++ ++To restrict which files can trigger the evaluation, include a ++directory or an extension or both in @var{library}. Only a file whose ++absolute true name (i.e., the name with all symbolic links chased out) ++matches all the given name components will match. In the following ++example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory ++@code{..../foo/bar} will trigger the evaluation, but not ++@file{my_inst.el}: ++ ++@example ++(eval-after-load "foo/bar/my_inst.elc" @dots{}) ++@end example ++ ++@var{library} can also be a feature (i.e.@: a symbol), in which case ++@var{form} is evaluated when @code{(provide @var{library})} is called. ++ ++An error in @var{form} does not undo the load, but does prevent ++execution of the rest of @var{form}. ++@end defun ++ ++In general, well-designed Lisp programs should not use this feature. ++The clean and modular ways to interact with a Lisp library are (1) ++examine and set the library's variables (those which are meant for ++outside use), and (2) call the library's functions. If you wish to ++do (1), you can do it immediately---there is no need to wait for when ++the library is loaded. To do (2), you must load the library (preferably ++with @code{require}). ++ ++But it is OK to use @code{eval-after-load} in your personal ++customizations if you don't feel they must meet the design standards for ++programs meant for wider use. ++ ++@defvar after-load-alist ++This variable, an alist built by @code{eval-after-load}, holds the ++expressions to evaluate when particular libraries are loaded. Each ++element looks like this: ++ ++@example ++(@var{regexp-or-feature} @var{forms}@dots{}) ++@end example ++ ++The key @var{regexp-or-feature} is either a regular expression or a ++symbol, and the value is a list of forms. The forms are evaluated when ++the key matches the absolute true name of the file being ++@code{load}ed or the symbol being @code{provide}d. ++@end defvar ++ ++@ignore ++ arch-tag: df731f89-0900-4389-a436-9105241b6f7a ++@end ignore +diff --git a/doc/lispref/locals.texi b/doc/lispref/locals.texi +new file mode 100644 +index 0000000..fcd6277 +--- /dev/null ++++ b/doc/lispref/locals.texi +@@ -0,0 +1,228 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/locals ++@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top ++@appendix Buffer-Local Variables ++@c The title "Standard Buffer-Local Variables" is too long for ++@c smallbook. --rjc 30mar92 ++@cindex buffer-local variables, general-purpose ++@cindex standard buffer-local variables ++ ++ The table below lists the general-purpose Emacs variables that ++automatically become buffer-local in each buffer. Most become ++buffer-local only when set; a few of them are always local in every ++buffer. Many Lisp packages define such variables for their internal ++use, but we don't try to list them all here. ++ ++ Every buffer-specific minor mode defines a buffer-local variable ++named @samp{@var{modename}-mode}. @xref{Minor Mode Conventions}. ++Minor mode variables will not be listed here. ++ ++@table @code ++@item auto-fill-function ++@xref{Auto Filling}. ++ ++@item buffer-auto-save-file-format ++@xref{Format Conversion}. ++ ++@item buffer-auto-save-file-name ++@xref{Auto-Saving}. ++ ++@item buffer-backed-up ++@xref{Making Backups}. ++ ++@item buffer-display-count ++@xref{Buffers and Windows}. ++ ++@item buffer-display-table ++@xref{Active Display Table}. ++ ++@item buffer-display-time ++@xref{Buffers and Windows}. ++ ++@item buffer-file-coding-system ++@xref{Encoding and I/O}. ++ ++@item buffer-file-format ++@xref{Format Conversion}. ++ ++@item buffer-file-name ++@xref{Buffer File Name}. ++ ++@item buffer-file-number ++@xref{Buffer File Name}. ++ ++@item buffer-file-truename ++@xref{Buffer File Name}. ++ ++@item buffer-file-type ++@xref{MS-DOS File Types}. ++ ++@item buffer-invisibility-spec ++@xref{Invisible Text}. ++ ++@item buffer-offer-save ++@xref{Killing Buffers}. ++ ++@item buffer-save-without-query ++@xref{Killing Buffers}. ++ ++@item buffer-read-only ++@xref{Read Only Buffers}. ++ ++@item buffer-saved-size ++@xref{Auto-Saving}. ++ ++@item buffer-undo-list ++@xref{Undo}. ++ ++@item cache-long-line-scans ++@xref{Truncation}. ++ ++@item case-fold-search ++@xref{Searching and Case}. ++ ++@item ctl-arrow ++@xref{Usual Display}. ++ ++@item cursor-in-non-selected-windows ++@xref{Basic Windows}. ++ ++@item cursor-type ++@xref{Cursor Parameters}. ++ ++@item comment-column ++@xref{Comments,,, emacs, The GNU Emacs Manual}. ++ ++@item default-directory ++@xref{File Name Expansion}. ++ ++@item defun-prompt-regexp ++@xref{List Motion}. ++ ++@item desktop-save-buffer ++@xref{Desktop Save Mode}. ++ ++@ignore ++@item direction-reversed ++Does not work yet. ++@end ignore ++ ++@item enable-multibyte-characters ++@ref{Text Representations}. ++ ++@item fill-column ++@xref{Margins}. ++ ++@item fill-prefix ++@xref{Margins}. ++ ++@item font-lock-defaults ++@xref{Font Lock Basics}. ++ ++@item fringe-cursor-alist ++@xref{Fringe Cursors}. ++ ++@item fringe-indicator-alist ++@xref{Fringe Indicators}. ++ ++@item fringes-outside-margins ++@xref{Fringes}. ++ ++@item goal-column ++@xref{Moving Point,,, emacs, The GNU Emacs Manual}. ++ ++@item header-line-format ++@xref{Header Lines}. ++ ++@item indicate-buffer-boundaries ++@xref{Usual Display}. ++ ++@item indicate-empty-lines ++@xref{Usual Display}. ++ ++@item left-fringe-width ++@xref{Fringe Size/Pos}. ++ ++@item left-margin ++@xref{Margins}. ++ ++@item left-margin-width ++@xref{Display Margins}. ++ ++@item line-spacing ++@xref{Line Height}. ++ ++@item local-abbrev-table ++@xref{Standard Abbrev Tables}. ++ ++@item major-mode ++@xref{Mode Help}. ++ ++@item mark-active ++@xref{The Mark}. ++ ++@item mark-ring ++@xref{The Mark}. ++ ++@item mode-line-buffer-identification ++@xref{Mode Line Variables}. ++ ++@item mode-line-format ++@xref{Mode Line Data}. ++ ++@item mode-line-modified ++@xref{Mode Line Variables}. ++ ++@item mode-line-process ++@xref{Mode Line Variables}. ++ ++@item mode-name ++@xref{Mode Line Variables}. ++ ++@item point-before-scroll ++Used for communication between mouse commands and scroll-bar commands. ++ ++@item right-fringe-width ++@xref{Fringe Size/Pos}. ++ ++@item right-margin-width ++@xref{Display Margins}. ++ ++@item save-buffer-coding-system ++@xref{Encoding and I/O}. ++ ++@item scroll-bar-width ++@xref{Scroll Bars}. ++ ++@item scroll-down-aggressively ++@itemx scroll-up-aggressively ++@xref{Textual Scrolling}. ++ ++@item selective-display ++@itemx selective-display-ellipses ++@xref{Selective Display}. ++ ++@item tab-width ++@xref{Usual Display}. ++ ++@item truncate-lines ++@xref{Truncation}. ++ ++@item vertical-scroll-bar ++@xref{Scroll Bars}. ++ ++@item window-size-fixed ++@xref{Resizing Windows}. ++ ++@item write-contents-functions ++@xref{Saving Buffers}. ++@end table ++ ++ ++@ignore ++ arch-tag: 6baae835-b667-4447-91e2-9829ae1cf543 ++@end ignore +diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi +new file mode 100644 +index 0000000..935dc65 +--- /dev/null ++++ b/doc/lispref/macros.texi +@@ -0,0 +1,738 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/macros ++@node Macros, Customization, Functions, Top ++@chapter Macros ++@cindex macros ++ ++ @dfn{Macros} enable you to define new control constructs and other ++language features. A macro is defined much like a function, but instead ++of telling how to compute a value, it tells how to compute another Lisp ++expression which will in turn compute the value. We call this ++expression the @dfn{expansion} of the macro. ++ ++ Macros can do this because they operate on the unevaluated expressions ++for the arguments, not on the argument values as functions do. They can ++therefore construct an expansion containing these argument expressions ++or parts of them. ++ ++ If you are using a macro to do something an ordinary function could ++do, just for the sake of speed, consider using an inline function ++instead. @xref{Inline Functions}. ++ ++@menu ++* Simple Macro:: A basic example. ++* Expansion:: How, when and why macros are expanded. ++* Compiling Macros:: How macros are expanded by the compiler. ++* Defining Macros:: How to write a macro definition. ++* Backquote:: Easier construction of list structure. ++* Problems with Macros:: Don't evaluate the macro arguments too many times. ++ Don't hide the user's variables. ++* Indenting Macros:: Specifying how to indent macro calls. ++@end menu ++ ++@node Simple Macro ++@section A Simple Example of a Macro ++ ++ Suppose we would like to define a Lisp construct to increment a ++variable value, much like the @code{++} operator in C. We would like to ++write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}. ++Here's a macro definition that does the job: ++ ++@findex inc ++@example ++@group ++(defmacro inc (var) ++ (list 'setq var (list '1+ var))) ++@end group ++@end example ++ ++ When this is called with @code{(inc x)}, the argument @var{var} is the ++symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would ++be in a function. The body of the macro uses this to construct the ++expansion, which is @code{(setq x (1+ x))}. Once the macro definition ++returns this expansion, Lisp proceeds to evaluate it, thus incrementing ++@code{x}. ++ ++@node Expansion ++@section Expansion of a Macro Call ++@cindex expansion of macros ++@cindex macro call ++ ++ A macro call looks just like a function call in that it is a list which ++starts with the name of the macro. The rest of the elements of the list ++are the arguments of the macro. ++ ++ Evaluation of the macro call begins like evaluation of a function call ++except for one crucial difference: the macro arguments are the actual ++expressions appearing in the macro call. They are not evaluated before ++they are given to the macro definition. By contrast, the arguments of a ++function are results of evaluating the elements of the function call ++list. ++ ++ Having obtained the arguments, Lisp invokes the macro definition just ++as a function is invoked. The argument variables of the macro are bound ++to the argument values from the macro call, or to a list of them in the ++case of a @code{&rest} argument. And the macro body executes and ++returns its value just as a function body does. ++ ++ The second crucial difference between macros and functions is that the ++value returned by the macro body is not the value of the macro call. ++Instead, it is an alternate expression for computing that value, also ++known as the @dfn{expansion} of the macro. The Lisp interpreter ++proceeds to evaluate the expansion as soon as it comes back from the ++macro. ++ ++ Since the expansion is evaluated in the normal manner, it may contain ++calls to other macros. It may even be a call to the same macro, though ++this is unusual. ++ ++ You can see the expansion of a given macro call by calling ++@code{macroexpand}. ++ ++@defun macroexpand form &optional environment ++@cindex macro expansion ++This function expands @var{form}, if it is a macro call. If the result ++is another macro call, it is expanded in turn, until something which is ++not a macro call results. That is the value returned by ++@code{macroexpand}. If @var{form} is not a macro call to begin with, it ++is returned as given. ++ ++Note that @code{macroexpand} does not look at the subexpressions of ++@var{form} (although some macro definitions may do so). Even if they ++are macro calls themselves, @code{macroexpand} does not expand them. ++ ++The function @code{macroexpand} does not expand calls to inline functions. ++Normally there is no need for that, since a call to an inline function is ++no harder to understand than a call to an ordinary function. ++ ++If @var{environment} is provided, it specifies an alist of macro ++definitions that shadow the currently defined macros. Byte compilation ++uses this feature. ++ ++@smallexample ++@group ++(defmacro inc (var) ++ (list 'setq var (list '1+ var))) ++ @result{} inc ++@end group ++ ++@group ++(macroexpand '(inc r)) ++ @result{} (setq r (1+ r)) ++@end group ++ ++@group ++(defmacro inc2 (var1 var2) ++ (list 'progn (list 'inc var1) (list 'inc var2))) ++ @result{} inc2 ++@end group ++ ++@group ++(macroexpand '(inc2 r s)) ++ @result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.} ++@end group ++@end smallexample ++@end defun ++ ++ ++@defun macroexpand-all form &optional environment ++@code{macroexpand-all} expands macros like @code{macroexpand}, but ++will look for and expand all macros in @var{form}, not just at the ++top-level. If no macros are expanded, the return value is @code{eq} ++to @var{form}. ++ ++Repeating the example used for @code{macroexpand} above with ++@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does} ++expand the embedded calls to @code{inc}: ++ ++@smallexample ++(macroexpand-all '(inc2 r s)) ++ @result{} (progn (setq r (1+ r)) (setq s (1+ s))) ++@end smallexample ++ ++@end defun ++ ++@node Compiling Macros ++@section Macros and Byte Compilation ++@cindex byte-compiling macros ++ ++ You might ask why we take the trouble to compute an expansion for a ++macro and then evaluate the expansion. Why not have the macro body ++produce the desired results directly? The reason has to do with ++compilation. ++ ++ When a macro call appears in a Lisp program being compiled, the Lisp ++compiler calls the macro definition just as the interpreter would, and ++receives an expansion. But instead of evaluating this expansion, it ++compiles the expansion as if it had appeared directly in the program. ++As a result, the compiled code produces the value and side effects ++intended for the macro, but executes at full compiled speed. This would ++not work if the macro body computed the value and side effects ++itself---they would be computed at compile time, which is not useful. ++ ++ In order for compilation of macro calls to work, the macros must ++already be defined in Lisp when the calls to them are compiled. The ++compiler has a special feature to help you do this: if a file being ++compiled contains a @code{defmacro} form, the macro is defined ++temporarily for the rest of the compilation of that file. ++ ++ Byte-compiling a file also executes any @code{require} calls at ++top-level in the file, so you can ensure that necessary macro ++definitions are available during compilation by requiring the files ++that define them (@pxref{Named Features}). To avoid loading the macro ++definition files when someone @emph{runs} the compiled program, write ++@code{eval-when-compile} around the @code{require} calls (@pxref{Eval ++During Compile}). ++ ++@node Defining Macros ++@section Defining Macros ++ ++ A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should ++be a function; expansion of the macro works by applying the function ++(with @code{apply}) to the list of unevaluated argument-expressions ++from the macro call. ++ ++ It is possible to use an anonymous Lisp macro just like an anonymous ++function, but this is never done, because it does not make sense to pass ++an anonymous macro to functionals such as @code{mapcar}. In practice, ++all Lisp macros have names, and they are usually defined with the ++special form @code{defmacro}. ++ ++@defspec defmacro name argument-list body-forms@dots{} ++@code{defmacro} defines the symbol @var{name} as a macro that looks ++like this: ++ ++@example ++(macro lambda @var{argument-list} . @var{body-forms}) ++@end example ++ ++(Note that the @sc{cdr} of this list is a function---a lambda expression.) ++This macro object is stored in the function cell of @var{name}. The ++value returned by evaluating the @code{defmacro} form is @var{name}, but ++usually we ignore this value. ++ ++The shape and meaning of @var{argument-list} is the same as in a ++function, and the keywords @code{&rest} and @code{&optional} may be used ++(@pxref{Argument List}). Macros may have a documentation string, but ++any @code{interactive} declaration is ignored since macros cannot be ++called interactively. ++@end defspec ++ ++ The body of the macro definition can include a @code{declare} form, ++which can specify how @key{TAB} should indent macro calls, and how to ++step through them for Edebug. ++ ++@defmac declare @var{specs}@dots{} ++@anchor{Definition of declare} ++A @code{declare} form is used in a macro definition to specify various ++additional information about it. Two kinds of specification are ++currently supported: ++ ++@table @code ++@item (debug @var{edebug-form-spec}) ++Specify how to step through macro calls for Edebug. ++@xref{Instrumenting Macro Calls}. ++ ++@item (indent @var{indent-spec}) ++Specify how to indent calls to this macro. @xref{Indenting Macros}, ++for more details. ++@end table ++ ++A @code{declare} form only has its special effect in the body of a ++@code{defmacro} form if it immediately follows the documentation ++string, if present, or the argument list otherwise. (Strictly ++speaking, @emph{several} @code{declare} forms can follow the ++documentation string or argument list, but since a @code{declare} form ++can have several @var{specs}, they can always be combined into a ++single form.) When used at other places in a @code{defmacro} form, or ++outside a @code{defmacro} form, @code{declare} just returns @code{nil} ++without evaluating any @var{specs}. ++@end defmac ++ ++ No macro absolutely needs a @code{declare} form, because that form ++has no effect on how the macro expands, on what the macro means in the ++program. It only affects secondary features: indentation and Edebug. ++ ++@node Backquote ++@section Backquote ++@cindex backquote (list substitution) ++@cindex ` (list substitution) ++@findex ` ++ ++ Macros often need to construct large list structures from a mixture of ++constants and nonconstant parts. To make this easier, use the @samp{`} ++syntax (usually called @dfn{backquote}). ++ ++ Backquote allows you to quote a list, but selectively evaluate ++elements of that list. In the simplest case, it is identical to the ++special form @code{quote} (@pxref{Quoting}). For example, these ++two forms yield identical results: ++ ++@example ++@group ++`(a list of (+ 2 3) elements) ++ @result{} (a list of (+ 2 3) elements) ++@end group ++@group ++'(a list of (+ 2 3) elements) ++ @result{} (a list of (+ 2 3) elements) ++@end group ++@end example ++ ++@findex , @r{(with backquote)} ++The special marker @samp{,} inside of the argument to backquote ++indicates a value that isn't constant. Backquote evaluates the ++argument of @samp{,} and puts the value in the list structure: ++ ++@example ++@group ++(list 'a 'list 'of (+ 2 3) 'elements) ++ @result{} (a list of 5 elements) ++@end group ++@group ++`(a list of ,(+ 2 3) elements) ++ @result{} (a list of 5 elements) ++@end group ++@end example ++ ++ Substitution with @samp{,} is allowed at deeper levels of the list ++structure also. For example: ++ ++@example ++@group ++(defmacro t-becomes-nil (variable) ++ `(if (eq ,variable t) ++ (setq ,variable nil))) ++@end group ++ ++@group ++(t-becomes-nil foo) ++ @equiv{} (if (eq foo t) (setq foo nil)) ++@end group ++@end example ++ ++@findex ,@@ @r{(with backquote)} ++@cindex splicing (with backquote) ++ You can also @dfn{splice} an evaluated value into the resulting list, ++using the special marker @samp{,@@}. The elements of the spliced list ++become elements at the same level as the other elements of the resulting ++list. The equivalent code without using @samp{`} is often unreadable. ++Here are some examples: ++ ++@example ++@group ++(setq some-list '(2 3)) ++ @result{} (2 3) ++@end group ++@group ++(cons 1 (append some-list '(4) some-list)) ++ @result{} (1 2 3 4 2 3) ++@end group ++@group ++`(1 ,@@some-list 4 ,@@some-list) ++ @result{} (1 2 3 4 2 3) ++@end group ++ ++@group ++(setq list '(hack foo bar)) ++ @result{} (hack foo bar) ++@end group ++@group ++(cons 'use ++ (cons 'the ++ (cons 'words (append (cdr list) '(as elements))))) ++ @result{} (use the words foo bar as elements) ++@end group ++@group ++`(use the words ,@@(cdr list) as elements) ++ @result{} (use the words foo bar as elements) ++@end group ++@end example ++ ++@node Problems with Macros ++@section Common Problems Using Macros ++ ++ The basic facts of macro expansion have counterintuitive consequences. ++This section describes some important consequences that can lead to ++trouble, and rules to follow to avoid trouble. ++ ++@menu ++* Wrong Time:: Do the work in the expansion, not in the macro. ++* Argument Evaluation:: The expansion should evaluate each macro arg once. ++* Surprising Local Vars:: Local variable bindings in the expansion ++ require special care. ++* Eval During Expansion:: Don't evaluate them; put them in the expansion. ++* Repeated Expansion:: Avoid depending on how many times expansion is done. ++@end menu ++ ++@node Wrong Time ++@subsection Wrong Time ++ ++ The most common problem in writing macros is doing some of the ++real work prematurely---while expanding the macro, rather than in the ++expansion itself. For instance, one real package had this macro ++definition: ++ ++@example ++(defmacro my-set-buffer-multibyte (arg) ++ (if (fboundp 'set-buffer-multibyte) ++ (set-buffer-multibyte arg))) ++@end example ++ ++With this erroneous macro definition, the program worked fine when ++interpreted but failed when compiled. This macro definition called ++@code{set-buffer-multibyte} during compilation, which was wrong, and ++then did nothing when the compiled package was run. The definition ++that the programmer really wanted was this: ++ ++@example ++(defmacro my-set-buffer-multibyte (arg) ++ (if (fboundp 'set-buffer-multibyte) ++ `(set-buffer-multibyte ,arg))) ++@end example ++ ++@noindent ++This macro expands, if appropriate, into a call to ++@code{set-buffer-multibyte} that will be executed when the compiled ++program is actually run. ++ ++@node Argument Evaluation ++@subsection Evaluating Macro Arguments Repeatedly ++ ++ When defining a macro you must pay attention to the number of times ++the arguments will be evaluated when the expansion is executed. The ++following macro (used to facilitate iteration) illustrates the problem. ++This macro allows us to write a simple ``for'' loop such as one might ++find in Pascal. ++ ++@findex for ++@smallexample ++@group ++(defmacro for (var from init to final do &rest body) ++ "Execute a simple \"for\" loop. ++For example, (for i from 1 to 10 do (print i))." ++ (list 'let (list (list var init)) ++ (cons 'while (cons (list '<= var final) ++ (append body (list (list 'inc var))))))) ++@end group ++@result{} for ++ ++@group ++(for i from 1 to 3 do ++ (setq square (* i i)) ++ (princ (format "\n%d %d" i square))) ++@expansion{} ++@end group ++@group ++(let ((i 1)) ++ (while (<= i 3) ++ (setq square (* i i)) ++ (princ (format "\n%d %d" i square)) ++ (inc i))) ++@end group ++@group ++ ++ @print{}1 1 ++ @print{}2 4 ++ @print{}3 9 ++@result{} nil ++@end group ++@end smallexample ++ ++@noindent ++The arguments @code{from}, @code{to}, and @code{do} in this macro are ++``syntactic sugar''; they are entirely ignored. The idea is that you ++will write noise words (such as @code{from}, @code{to}, and @code{do}) ++in those positions in the macro call. ++ ++Here's an equivalent definition simplified through use of backquote: ++ ++@smallexample ++@group ++(defmacro for (var from init to final do &rest body) ++ "Execute a simple \"for\" loop. ++For example, (for i from 1 to 10 do (print i))." ++ `(let ((,var ,init)) ++ (while (<= ,var ,final) ++ ,@@body ++ (inc ,var)))) ++@end group ++@end smallexample ++ ++Both forms of this definition (with backquote and without) suffer from ++the defect that @var{final} is evaluated on every iteration. If ++@var{final} is a constant, this is not a problem. If it is a more ++complex form, say @code{(long-complex-calculation x)}, this can slow ++down the execution significantly. If @var{final} has side effects, ++executing it more than once is probably incorrect. ++ ++@cindex macro argument evaluation ++A well-designed macro definition takes steps to avoid this problem by ++producing an expansion that evaluates the argument expressions exactly ++once unless repeated evaluation is part of the intended purpose of the ++macro. Here is a correct expansion for the @code{for} macro: ++ ++@smallexample ++@group ++(let ((i 1) ++ (max 3)) ++ (while (<= i max) ++ (setq square (* i i)) ++ (princ (format "%d %d" i square)) ++ (inc i))) ++@end group ++@end smallexample ++ ++Here is a macro definition that creates this expansion: ++ ++@smallexample ++@group ++(defmacro for (var from init to final do &rest body) ++ "Execute a simple for loop: (for i from 1 to 10 do (print i))." ++ `(let ((,var ,init) ++ (max ,final)) ++ (while (<= ,var max) ++ ,@@body ++ (inc ,var)))) ++@end group ++@end smallexample ++ ++ Unfortunately, this fix introduces another problem, ++described in the following section. ++ ++@node Surprising Local Vars ++@subsection Local Variables in Macro Expansions ++ ++@ifnottex ++ In the previous section, the definition of @code{for} was fixed as ++follows to make the expansion evaluate the macro arguments the proper ++number of times: ++ ++@smallexample ++@group ++(defmacro for (var from init to final do &rest body) ++ "Execute a simple for loop: (for i from 1 to 10 do (print i))." ++@end group ++@group ++ `(let ((,var ,init) ++ (max ,final)) ++ (while (<= ,var max) ++ ,@@body ++ (inc ,var)))) ++@end group ++@end smallexample ++@end ifnottex ++ ++ The new definition of @code{for} has a new problem: it introduces a ++local variable named @code{max} which the user does not expect. This ++causes trouble in examples such as the following: ++ ++@smallexample ++@group ++(let ((max 0)) ++ (for x from 0 to 10 do ++ (let ((this (frob x))) ++ (if (< max this) ++ (setq max this))))) ++@end group ++@end smallexample ++ ++@noindent ++The references to @code{max} inside the body of the @code{for}, which ++are supposed to refer to the user's binding of @code{max}, really access ++the binding made by @code{for}. ++ ++The way to correct this is to use an uninterned symbol instead of ++@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be ++bound and referred to just like any other symbol, but since it is ++created by @code{for}, we know that it cannot already appear in the ++user's program. Since it is not interned, there is no way the user can ++put it into the program later. It will never appear anywhere except ++where put by @code{for}. Here is a definition of @code{for} that works ++this way: ++ ++@smallexample ++@group ++(defmacro for (var from init to final do &rest body) ++ "Execute a simple for loop: (for i from 1 to 10 do (print i))." ++ (let ((tempvar (make-symbol "max"))) ++ `(let ((,var ,init) ++ (,tempvar ,final)) ++ (while (<= ,var ,tempvar) ++ ,@@body ++ (inc ,var))))) ++@end group ++@end smallexample ++ ++@noindent ++This creates an uninterned symbol named @code{max} and puts it in the ++expansion instead of the usual interned symbol @code{max} that appears ++in expressions ordinarily. ++ ++@node Eval During Expansion ++@subsection Evaluating Macro Arguments in Expansion ++ ++ Another problem can happen if the macro definition itself ++evaluates any of the macro argument expressions, such as by calling ++@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the ++user's variables, you may have trouble if the user happens to use a ++variable with the same name as one of the macro arguments. Inside the ++macro body, the macro argument binding is the most local binding of this ++variable, so any references inside the form being evaluated do refer to ++it. Here is an example: ++ ++@example ++@group ++(defmacro foo (a) ++ (list 'setq (eval a) t)) ++ @result{} foo ++@end group ++@group ++(setq x 'b) ++(foo x) @expansion{} (setq b t) ++ @result{} t ; @r{and @code{b} has been set.} ++;; @r{but} ++(setq a 'c) ++(foo a) @expansion{} (setq a t) ++ @result{} t ; @r{but this set @code{a}, not @code{c}.} ++ ++@end group ++@end example ++ ++ It makes a difference whether the user's variable is named @code{a} or ++@code{x}, because @code{a} conflicts with the macro argument variable ++@code{a}. ++ ++ Another problem with calling @code{eval} in a macro definition is that ++it probably won't do what you intend in a compiled program. The ++byte compiler runs macro definitions while compiling the program, when ++the program's own computations (which you might have wished to access ++with @code{eval}) don't occur and its local variable bindings don't ++exist. ++ ++ To avoid these problems, @strong{don't evaluate an argument expression ++while computing the macro expansion}. Instead, substitute the ++expression into the macro expansion, so that its value will be computed ++as part of executing the expansion. This is how the other examples in ++this chapter work. ++ ++@node Repeated Expansion ++@subsection How Many Times is the Macro Expanded? ++ ++ Occasionally problems result from the fact that a macro call is ++expanded each time it is evaluated in an interpreted function, but is ++expanded only once (during compilation) for a compiled function. If the ++macro definition has side effects, they will work differently depending ++on how many times the macro is expanded. ++ ++ Therefore, you should avoid side effects in computation of the ++macro expansion, unless you really know what you are doing. ++ ++ One special kind of side effect can't be avoided: constructing Lisp ++objects. Almost all macro expansions include constructed lists; that is ++the whole point of most macros. This is usually safe; there is just one ++case where you must be careful: when the object you construct is part of a ++quoted constant in the macro expansion. ++ ++ If the macro is expanded just once, in compilation, then the object is ++constructed just once, during compilation. But in interpreted ++execution, the macro is expanded each time the macro call runs, and this ++means a new object is constructed each time. ++ ++ In most clean Lisp code, this difference won't matter. It can matter ++only if you perform side-effects on the objects constructed by the macro ++definition. Thus, to avoid trouble, @strong{avoid side effects on ++objects constructed by macro definitions}. Here is an example of how ++such side effects can get you into trouble: ++ ++@lisp ++@group ++(defmacro empty-object () ++ (list 'quote (cons nil nil))) ++@end group ++ ++@group ++(defun initialize (condition) ++ (let ((object (empty-object))) ++ (if condition ++ (setcar object condition)) ++ object)) ++@end group ++@end lisp ++ ++@noindent ++If @code{initialize} is interpreted, a new list @code{(nil)} is ++constructed each time @code{initialize} is called. Thus, no side effect ++survives between calls. If @code{initialize} is compiled, then the ++macro @code{empty-object} is expanded during compilation, producing a ++single ``constant'' @code{(nil)} that is reused and altered each time ++@code{initialize} is called. ++ ++One way to avoid pathological cases like this is to think of ++@code{empty-object} as a funny kind of constant, not as a memory ++allocation construct. You wouldn't use @code{setcar} on a constant such ++as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)} ++either. ++ ++@node Indenting Macros ++@section Indenting Macros ++ ++ You can use the @code{declare} form in the macro definition to ++specify how to @key{TAB} should indent indent calls to the macro. You ++write it like this: ++ ++@example ++(declare (indent @var{indent-spec})) ++@end example ++ ++@noindent ++Here are the possibilities for @var{indent-spec}: ++ ++@table @asis ++@item @code{nil} ++This is the same as no property---use the standard indentation pattern. ++@item @code{defun} ++Handle this function like a @samp{def} construct: treat the second ++line as the start of a @dfn{body}. ++@item an integer, @var{number} ++The first @var{number} arguments of the function are ++@dfn{distinguished} arguments; the rest are considered the body ++of the expression. A line in the expression is indented according to ++whether the first argument on it is distinguished or not. If the ++argument is part of the body, the line is indented @code{lisp-body-indent} ++more columns than the open-parenthesis starting the containing ++expression. If the argument is distinguished and is either the first ++or second argument, it is indented @emph{twice} that many extra columns. ++If the argument is distinguished and not the first or second argument, ++the line uses the standard pattern. ++@item a symbol, @var{symbol} ++@var{symbol} should be a function name; that function is called to ++calculate the indentation of a line within this expression. The ++function receives two arguments: ++@table @asis ++@item @var{state} ++The value returned by @code{parse-partial-sexp} (a Lisp primitive for ++indentation and nesting computation) when it parses up to the ++beginning of this line. ++@item @var{pos} ++The position at which the line being indented begins. ++@end table ++@noindent ++It should return either a number, which is the number of columns of ++indentation for that line, or a list whose car is such a number. The ++difference between returning a number and returning a list is that a ++number says that all following lines at the same nesting level should ++be indented just like this one; a list says that following lines might ++call for different indentations. This makes a difference when the ++indentation is being computed by @kbd{C-M-q}; if the value is a ++number, @kbd{C-M-q} need not recalculate indentation for the following ++lines until the end of the list. ++@end table ++ ++@ignore ++ arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b ++@end ignore +diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in +new file mode 100644 +index 0000000..1ba8e1e +--- /dev/null ++++ b/doc/lispref/makefile.w32-in +@@ -0,0 +1,125 @@ ++# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual. ++ ++# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++# Free Software Foundation, Inc. ++ ++# This file is part of GNU Emacs. ++ ++# GNU Emacs 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. ++ ++# GNU Emacs 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 GNU Emacs. If not, see . ++ ++ ++# Standard configure variables. ++srcdir = . ++ ++infodir = $(srcdir)/../../info ++usermanualdir = $(srcdir)/../emacs ++ ++# Redefine `TEX' if `tex' does not invoke plain TeX. For example: ++# TEX=platex ++TEX=tex ++INSTALL_INFO = install-info ++MAKEINFO = makeinfo --force ++ ++# The environment variable and its value to add $(srcdir) to the path ++# searched for TeX input files. ++texinputdir = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" /C ++ ++# The name of the manual: ++VERSION=2.9 ++## FIXME can this be set by configure, as per Makefile.in? ++manual = elisp-manual-23-$(VERSION) ++ ++# List of all the texinfo files in the manual: ++ ++srcs = \ ++ $(srcdir)/abbrevs.texi \ ++ $(srcdir)/advice.texi \ ++ $(srcdir)/anti.texi \ ++ $(srcdir)/back.texi \ ++ $(srcdir)/backups.texi \ ++ $(srcdir)/buffers.texi \ ++ $(srcdir)/commands.texi \ ++ $(srcdir)/compile.texi \ ++ $(srcdir)/control.texi \ ++ $(srcdir)/customize.texi \ ++ $(srcdir)/debugging.texi \ ++ $(srcdir)/display.texi \ ++ $(srcdir)/edebug.texi \ ++ $(srcdir)/elisp.texi \ ++ $(srcdir)/errors.texi \ ++ $(srcdir)/eval.texi \ ++ $(srcdir)/files.texi \ ++ $(srcdir)/frames.texi \ ++ $(srcdir)/functions.texi \ ++ $(srcdir)/hash.texi \ ++ $(srcdir)/help.texi \ ++ $(srcdir)/hooks.texi \ ++ $(srcdir)/internals.texi \ ++ $(srcdir)/intro.texi \ ++ $(srcdir)/keymaps.texi \ ++ $(srcdir)/lists.texi \ ++ $(srcdir)/loading.texi \ ++ $(srcdir)/locals.texi \ ++ $(srcdir)/macros.texi \ ++ $(srcdir)/maps.texi \ ++ $(srcdir)/markers.texi \ ++ $(srcdir)/minibuf.texi \ ++ $(srcdir)/modes.texi \ ++ $(srcdir)/nonascii.texi \ ++ $(srcdir)/numbers.texi \ ++ $(srcdir)/objects.texi \ ++ $(srcdir)/os.texi \ ++ $(srcdir)/positions.texi \ ++ $(srcdir)/processes.texi \ ++ $(srcdir)/searching.texi \ ++ $(srcdir)/sequences.texi \ ++ $(srcdir)/streams.texi \ ++ $(srcdir)/strings.texi \ ++ $(srcdir)/symbols.texi \ ++ $(srcdir)/syntax.texi \ ++ $(srcdir)/text.texi \ ++ $(srcdir)/tips.texi \ ++ $(srcdir)/variables.texi \ ++ $(srcdir)/windows.texi \ ++ $(srcdir)/index.texi \ ++ $(srcdir)/gpl.texi \ ++ $(srcdir)/doclicense.texi ++ ++ ++.PHONY: clean ++ ++# The info file is named `elisp'. ++ ++info: $(infodir)/elisp ++ ++$(infodir)/dir: ++ $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp ++ ++$(infodir)/elisp: $(srcs) ++ $(MAKEINFO) -I. -I$(srcdir) -o $(infodir)/elisp $(srcdir)/elisp.texi ++ ++elisp.dvi: $(srcs) ++ $(texinputdir) $(TEX) -I $(usermanualdir) $(srcdir)/elisp.texi ++ ++clean: ++ - $(DEL) *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ ++ *.vr *.vrs *.pg *.pgs *.ky *.kys ++ - $(DEL) make.out core ++ - $(DEL) $(infodir)/elisp* ++ ++distclean: clean ++ - $(DEL) makefile ++ ++maintainer-clean: distclean ++ - $(DEL) elisp elisp-? elisp-?? elisp.dvi elisp.oaux +diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi +new file mode 100644 +index 0000000..88ab85a +--- /dev/null ++++ b/doc/lispref/maps.texi +@@ -0,0 +1,244 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/maps ++@node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top ++@appendix Standard Keymaps ++@cindex standard keymaps ++ ++The following symbols are used as the names for various keymaps. ++Some of these exist when Emacs is first started, others are ++loaded only when their respective mode is used. This is not ++an exhaustive list. ++ ++Several keymaps are used in the minibuffer. @xref{Completion Commands}. ++ ++Almost all of these maps are used as local maps. Indeed, of the modes ++that presently exist, only Vip mode and Terminal mode ever change the ++global keymap. ++ ++@table @code ++@item apropos-mode-map ++@vindex apropos-mode-map ++A sparse keymap for @code{apropos} buffers. ++ ++@item Buffer-menu-mode-map ++@vindex Buffer-menu-mode-map ++A full keymap used by Buffer Menu mode. ++ ++@item c-mode-map ++@vindex c-mode-map ++A sparse keymap used by C mode. ++ ++@item command-history-map ++@vindex command-history-map ++A full keymap used by Command History mode. ++ ++@item ctl-x-4-map ++A sparse keymap for subcommands of the prefix @kbd{C-x 4}. ++ ++@item ctl-x-5-map ++A sparse keymap for subcommands of the prefix @kbd{C-x 5}. ++ ++@item ctl-x-map ++A full keymap for @kbd{C-x} commands. ++ ++@item custom-mode-map ++A full keymap for Custom mode. ++ ++@item debugger-mode-map ++@vindex debugger-mode-map ++A full keymap used by Debugger mode. ++ ++@item dired-mode-map ++@vindex dired-mode-map ++A full keymap for @code{dired-mode} buffers. ++ ++@item edit-abbrevs-map ++@vindex edit-abbrevs-map ++A sparse keymap used in @code{edit-abbrevs}. ++ ++@item edit-tab-stops-map ++@vindex edit-tab-stops-map ++A sparse keymap used in @code{edit-tab-stops}. ++ ++@item electric-buffer-menu-mode-map ++@vindex electric-buffer-menu-mode-map ++A full keymap used by Electric Buffer Menu mode. ++ ++@item electric-history-map ++@vindex electric-history-map ++A full keymap used by Electric Command History mode. ++ ++@item emacs-lisp-mode-map ++@vindex emacs-lisp-mode-map ++A sparse keymap used by Emacs Lisp mode. ++ ++@item esc-map ++A full keymap for @kbd{ESC} (or @kbd{Meta}) commands. ++ ++@item facemenu-menu ++@vindex facemenu-menu ++The sparse keymap that displays the Text Properties menu. ++ ++@item facemenu-background-menu ++@vindex facemenu-background-menu ++The sparse keymap that displays the Background Color submenu of the Text ++Properties menu. ++ ++@item facemenu-face-menu ++@vindex facemenu-face-menu ++The sparse keymap that displays the Face submenu of the Text Properties menu. ++ ++@item facemenu-foreground-menu ++@vindex facemenu-foreground-menu ++The sparse keymap that displays the Foreground Color submenu of the Text ++Properties menu. ++ ++@item facemenu-indentation-menu ++@vindex facemenu-indentation-menu ++The sparse keymap that displays the Indentation submenu of the Text ++Properties menu. ++ ++@item facemenu-justification-menu ++@vindex facemenu-justification-menu ++The sparse keymap that displays the Justification submenu of the Text ++Properties menu. ++ ++@item facemenu-special-menu ++@vindex facemenu-special-menu ++The sparse keymap that displays the Special Props submenu of the Text ++Properties menu. ++ ++@item local-function-key-map ++The keymap for translating key sequences to preferred alternatives.@* ++If there are none, then it contains an empty sparse keymap. ++@xref{Translation Keymaps}. ++ ++@item fundamental-mode-map ++@vindex fundamental-mode-map ++The sparse keymap for Fundamental mode.@* ++It is empty and should not be changed. ++ ++@item global-map ++The full keymap containing default global key bindings.@* ++Modes should not modify the Global map. ++ ++@item grep-mode-map ++@vindex grep-mode-map ++The keymap for @code{grep-mode} buffers. ++ ++@item help-map ++The sparse keymap for the keys that follow the help character @kbd{C-h}. ++ ++@item help-mode-map ++@vindex help-mode-map ++The sparse keymap for Help mode. ++ ++@item Helper-help-map ++@vindex Helper-help-map ++A full keymap used by the help utility package.@* ++It has the same keymap in its value cell and in its function ++cell. ++ ++@item Info-edit-map ++@vindex Info-edit-map ++A sparse keymap used by the @kbd{e} command of Info. ++ ++@item Info-mode-map ++@vindex Info-mode-map ++A sparse keymap containing Info commands. ++ ++@item input-decode-map ++The keymap for translating keypad and function keys.@* ++If there are none, then it contains an empty sparse keymap. ++@xref{Translation Keymaps}. ++ ++@item isearch-mode-map ++@vindex isearch-mode-map ++A keymap that defines the characters you can type within incremental ++search. ++ ++@item key-translation-map ++A keymap for translating keys. This one overrides ordinary key ++bindings, unlike @code{local- function-key-map}. @xref{Translation ++Keymaps}. ++ ++@item kmacro-map ++@vindex kmacro-map ++A sparse keymap for keys that follows the @kbd{C-x C-k} prefix ++search. ++ ++@item lisp-interaction-mode-map ++@vindex lisp-interaction-mode-map ++A sparse keymap used by Lisp Interaction mode. ++ ++@item lisp-mode-map ++@vindex lisp-mode-map ++A sparse keymap used by Lisp mode. ++ ++@item menu-bar-edit-menu ++@vindex menu-bar-edit-menu ++The keymap which displays the Edit menu in the menu bar. ++ ++@item menu-bar-files-menu ++@vindex menu-bar-files-menu ++The keymap which displays the Files menu in the menu bar. ++ ++@item menu-bar-help-menu ++@vindex menu-bar-help-menu ++The keymap which displays the Help menu in the menu bar. ++ ++@item menu-bar-mule-menu ++@vindex menu-bar-mule-menu ++The keymap which displays the Mule menu in the menu bar. ++ ++@item menu-bar-search-menu ++@vindex menu-bar-search-menu ++The keymap which displays the Search menu in the menu bar. ++ ++@item menu-bar-tools-menu ++@vindex menu-bar-tools-menu ++The keymap which displays the Tools menu in the menu bar. ++ ++@item mode-specific-map ++The keymap for characters following @kbd{C-c}. Note, this is in the ++global map. This map is not actually mode specific: its name was chosen ++to be informative for the user in @kbd{C-h b} (@code{display-bindings}), ++where it describes the main use of the @kbd{C-c} prefix key. ++ ++@item multi-query-replace-map ++A sparse keymap that extends @code{query-replace-map} for multi-buffer ++replacements. @xref{Search and Replace, query-replace-map}. ++ ++@item occur-mode-map ++@vindex occur-mode-map ++A sparse keymap used by Occur mode. ++ ++@item query-replace-map ++A sparse keymap used for responses in @code{query-replace} and related ++commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions ++that use this map do not support prefix keys; they look up one event at a ++time. ++ ++@item search-map ++A sparse keymap that provides global bindings for search-related ++commands. ++ ++@item text-mode-map ++@vindex text-mode-map ++A sparse keymap used by Text mode. ++ ++@item tool-bar-map ++The keymap defining the contents of the tool bar. ++ ++@item view-mode-map ++@vindex view-mode-map ++A full keymap used by View mode. ++@end table ++ ++@ignore ++ arch-tag: b741253c-7e23-4a02-b3fa-cffd9e4d72b9 ++@end ignore +diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi +new file mode 100644 +index 0000000..78dbbef +--- /dev/null ++++ b/doc/lispref/markers.texi +@@ -0,0 +1,679 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/markers ++@node Markers, Text, Positions, Top ++@chapter Markers ++@cindex markers ++ ++ A @dfn{marker} is a Lisp object used to specify a position in a buffer ++relative to the surrounding text. A marker changes its offset from the ++beginning of the buffer automatically whenever text is inserted or ++deleted, so that it stays with the two characters on either side of it. ++ ++@menu ++* Overview of Markers:: The components of a marker, and how it relocates. ++* Predicates on Markers:: Testing whether an object is a marker. ++* Creating Markers:: Making empty markers or markers at certain places. ++* Information from Markers:: Finding the marker's buffer or character position. ++* Marker Insertion Types:: Two ways a marker can relocate when you ++ insert where it points. ++* Moving Markers:: Moving the marker to a new buffer or position. ++* The Mark:: How "the mark" is implemented with a marker. ++* The Region:: How to access "the region". ++@end menu ++ ++@node Overview of Markers ++@section Overview of Markers ++ ++ A marker specifies a buffer and a position in that buffer. The ++marker can be used to represent a position in the functions that ++require one, just as an integer could be used. In that case, the ++marker's buffer is normally ignored. Of course, a marker used in this ++way usually points to a position in the buffer that the function ++operates on, but that is entirely the programmer's responsibility. ++@xref{Positions}, for a complete description of positions. ++ ++ A marker has three attributes: the marker position, the marker ++buffer, and the insertion type. The marker position is an integer ++that is equivalent (at a given time) to the marker as a position in ++that buffer. But the marker's position value can change often during ++the life of the marker. Insertion and deletion of text in the buffer ++relocate the marker. The idea is that a marker positioned between two ++characters remains between those two characters despite insertion and ++deletion elsewhere in the buffer. Relocation changes the integer ++equivalent of the marker. ++ ++@cindex marker relocation ++ Deleting text around a marker's position leaves the marker between the ++characters immediately before and after the deleted text. Inserting ++text at the position of a marker normally leaves the marker either in ++front of or after the new text, depending on the marker's @dfn{insertion ++type} (@pxref{Marker Insertion Types})---unless the insertion is done ++with @code{insert-before-markers} (@pxref{Insertion}). ++ ++@cindex marker garbage collection ++ Insertion and deletion in a buffer must check all the markers and ++relocate them if necessary. This slows processing in a buffer with a ++large number of markers. For this reason, it is a good idea to make a ++marker point nowhere if you are sure you don't need it any more. ++Unreferenced markers are garbage collected eventually, but until then ++will continue to use time if they do point somewhere. ++ ++@cindex markers as numbers ++ Because it is common to perform arithmetic operations on a marker ++position, most of the arithmetic operations (including @code{+} and ++@code{-}) accept markers as arguments. In such cases, the marker ++stands for its current position. ++ ++Here are examples of creating markers, setting markers, and moving point ++to markers: ++ ++@example ++@group ++;; @r{Make a new marker that initially does not point anywhere:} ++(setq m1 (make-marker)) ++ @result{} # ++@end group ++ ++@group ++;; @r{Set @code{m1} to point between the 99th and 100th characters} ++;; @r{in the current buffer:} ++(set-marker m1 100) ++ @result{} # ++@end group ++ ++@group ++;; @r{Now insert one character at the beginning of the buffer:} ++(goto-char (point-min)) ++ @result{} 1 ++(insert "Q") ++ @result{} nil ++@end group ++ ++@group ++;; @r{@code{m1} is updated appropriately.} ++m1 ++ @result{} # ++@end group ++ ++@group ++;; @r{Two markers that point to the same position} ++;; @r{are not @code{eq}, but they are @code{equal}.} ++(setq m2 (copy-marker m1)) ++ @result{} # ++(eq m1 m2) ++ @result{} nil ++(equal m1 m2) ++ @result{} t ++@end group ++ ++@group ++;; @r{When you are finished using a marker, make it point nowhere.} ++(set-marker m1 nil) ++ @result{} # ++@end group ++@end example ++ ++@node Predicates on Markers ++@section Predicates on Markers ++ ++ You can test an object to see whether it is a marker, or whether it is ++either an integer or a marker. The latter test is useful in connection ++with the arithmetic functions that work with both markers and integers. ++ ++@defun markerp object ++This function returns @code{t} if @var{object} is a marker, @code{nil} ++otherwise. Note that integers are not markers, even though many ++functions will accept either a marker or an integer. ++@end defun ++ ++@defun integer-or-marker-p object ++This function returns @code{t} if @var{object} is an integer or a marker, ++@code{nil} otherwise. ++@end defun ++ ++@defun number-or-marker-p object ++This function returns @code{t} if @var{object} is a number (either ++integer or floating point) or a marker, @code{nil} otherwise. ++@end defun ++ ++@node Creating Markers ++@section Functions that Create Markers ++ ++ When you create a new marker, you can make it point nowhere, or point ++to the present position of point, or to the beginning or end of the ++accessible portion of the buffer, or to the same place as another given ++marker. ++ ++The next four functions all return markers with insertion type ++@code{nil}. @xref{Marker Insertion Types}. ++ ++@defun make-marker ++This function returns a newly created marker that does not point ++anywhere. ++ ++@example ++@group ++(make-marker) ++ @result{} # ++@end group ++@end example ++@end defun ++ ++@defun point-marker ++This function returns a new marker that points to the present position ++of point in the current buffer. @xref{Point}. For an example, see ++@code{copy-marker}, below. ++@end defun ++ ++@defun point-min-marker ++This function returns a new marker that points to the beginning of the ++accessible portion of the buffer. This will be the beginning of the ++buffer unless narrowing is in effect. @xref{Narrowing}. ++@end defun ++ ++@defun point-max-marker ++This function returns a new marker that points to the end of the ++accessible portion of the buffer. This will be the end of the buffer ++unless narrowing is in effect. @xref{Narrowing}. ++ ++Here are examples of this function and @code{point-min-marker}, shown in ++a buffer containing a version of the source file for the text of this ++chapter. ++ ++@example ++@group ++(point-min-marker) ++ @result{} # ++(point-max-marker) ++ @result{} # ++@end group ++ ++@group ++(narrow-to-region 100 200) ++ @result{} nil ++@end group ++@group ++(point-min-marker) ++ @result{} # ++@end group ++@group ++(point-max-marker) ++ @result{} # ++@end group ++@end example ++@end defun ++ ++@defun copy-marker marker-or-integer &optional insertion-type ++If passed a marker as its argument, @code{copy-marker} returns a ++new marker that points to the same place and the same buffer as does ++@var{marker-or-integer}. If passed an integer as its argument, ++@code{copy-marker} returns a new marker that points to position ++@var{marker-or-integer} in the current buffer. ++ ++The new marker's insertion type is specified by the argument ++@var{insertion-type}. @xref{Marker Insertion Types}. ++ ++If passed an integer argument less than 1, @code{copy-marker} returns a ++new marker that points to the beginning of the current buffer. If ++passed an integer argument greater than the length of the buffer, ++@code{copy-marker} returns a new marker that points to the end of the ++buffer. ++ ++@example ++@group ++(copy-marker 0) ++ @result{} # ++@end group ++ ++@group ++(copy-marker 20000) ++ @result{} # ++@end group ++@end example ++ ++An error is signaled if @var{marker} is neither a marker nor an ++integer. ++@end defun ++ ++ Two distinct markers are considered @code{equal} (even though not ++@code{eq}) to each other if they have the same position and buffer, or ++if they both point nowhere. ++ ++@example ++@group ++(setq p (point-marker)) ++ @result{} # ++@end group ++ ++@group ++(setq q (copy-marker p)) ++ @result{} # ++@end group ++ ++@group ++(eq p q) ++ @result{} nil ++@end group ++ ++@group ++(equal p q) ++ @result{} t ++@end group ++@end example ++ ++@node Information from Markers ++@section Information from Markers ++ ++ This section describes the functions for accessing the components of a ++marker object. ++ ++@defun marker-position marker ++This function returns the position that @var{marker} points to, or ++@code{nil} if it points nowhere. ++@end defun ++ ++@defun marker-buffer marker ++This function returns the buffer that @var{marker} points into, or ++@code{nil} if it points nowhere. ++ ++@example ++@group ++(setq m (make-marker)) ++ @result{} # ++@end group ++@group ++(marker-position m) ++ @result{} nil ++@end group ++@group ++(marker-buffer m) ++ @result{} nil ++@end group ++ ++@group ++(set-marker m 3770 (current-buffer)) ++ @result{} # ++@end group ++@group ++(marker-buffer m) ++ @result{} # ++@end group ++@group ++(marker-position m) ++ @result{} 3770 ++@end group ++@end example ++@end defun ++ ++@defun buffer-has-markers-at position ++This function returns @code{t} if one or more markers ++point at position @var{position} in the current buffer. ++@end defun ++ ++@node Marker Insertion Types ++@section Marker Insertion Types ++ ++@cindex insertion type of a marker ++ When you insert text directly at the place where a marker points, ++there are two possible ways to relocate that marker: it can point before ++the inserted text, or point after it. You can specify which one a given ++marker should do by setting its @dfn{insertion type}. Note that use of ++@code{insert-before-markers} ignores markers' insertion types, always ++relocating a marker to point after the inserted text. ++ ++@defun set-marker-insertion-type marker type ++This function sets the insertion type of marker @var{marker} to ++@var{type}. If @var{type} is @code{t}, @var{marker} will advance when ++text is inserted at its position. If @var{type} is @code{nil}, ++@var{marker} does not advance when text is inserted there. ++@end defun ++ ++@defun marker-insertion-type marker ++This function reports the current insertion type of @var{marker}. ++@end defun ++ ++Most functions that create markers, without an argument allowing to ++specify the insertion type, create them with insertion type ++@code{nil}. Also, the mark has, by default, insertion type ++@code{nil}. ++ ++@node Moving Markers ++@section Moving Marker Positions ++ ++ This section describes how to change the position of an existing ++marker. When you do this, be sure you know whether the marker is used ++outside of your program, and, if so, what effects will result from ++moving it---otherwise, confusing things may happen in other parts of ++Emacs. ++ ++@defun set-marker marker position &optional buffer ++This function moves @var{marker} to @var{position} ++in @var{buffer}. If @var{buffer} is not provided, it defaults to ++the current buffer. ++ ++If @var{position} is less than 1, @code{set-marker} moves @var{marker} ++to the beginning of the buffer. If @var{position} is greater than the ++size of the buffer, @code{set-marker} moves marker to the end of the ++buffer. If @var{position} is @code{nil} or a marker that points ++nowhere, then @var{marker} is set to point nowhere. ++ ++The value returned is @var{marker}. ++ ++@example ++@group ++(setq m (point-marker)) ++ @result{} # ++@end group ++@group ++(set-marker m 55) ++ @result{} # ++@end group ++@group ++(setq b (get-buffer "foo")) ++ @result{} # ++@end group ++@group ++(set-marker m 0 b) ++ @result{} # ++@end group ++@end example ++@end defun ++ ++@defun move-marker marker position &optional buffer ++This is another name for @code{set-marker}. ++@end defun ++ ++@node The Mark ++@section The Mark ++@cindex mark, the ++@cindex mark ring ++ ++ Each buffer has a special marker, which is designated @dfn{the ++mark}. When a buffer is newly created, this marker exists but does ++not point anywhere; this means that the mark ``doesn't exist'' in that ++buffer yet. Subsequent commands can set the mark. ++ ++ The mark specifies a position to bound a range of text for many ++commands, such as @code{kill-region} and @code{indent-rigidly}. These ++commands typically act on the text between point and the mark, which ++is called the @dfn{region}. If you are writing a command that ++operates on the region, don't examine the mark directly; instead, use ++@code{interactive} with the @samp{r} specification. This provides the ++values of point and the mark as arguments to the command in an ++interactive call, but permits other Lisp programs to specify arguments ++explicitly. @xref{Interactive Codes}. ++ ++ Some commands set the mark as a side-effect. Commands should do ++this only if it has a potential use to the user, and never for their ++own internal purposes. For example, the @code{replace-regexp} command ++sets the mark to the value of point before doing any replacements, ++because this enables the user to move back there conveniently after ++the replace is finished. ++ ++ Once the mark ``exists'' in a buffer, it normally never ceases to ++exist. However, it may become @dfn{inactive}, if Transient Mark mode ++is enabled. The buffer-local variable @code{mark-active}, if ++non-@code{nil}, means that the mark is active. A command can call the ++function @code{deactivate-mark} to deactivate the mark directly, or it ++can request deactivation of the mark upon return to the editor command ++loop by setting the variable @code{deactivate-mark} to a ++non-@code{nil} value. ++ ++ If Transient Mode is enabled, certain editing commands that normally ++apply to text near point, apply instead to the region when the mark is ++active. This is the main motivation for using Transient Mark mode. ++(Another is that this enables highlighting of the region when the mark ++is active. @xref{Display}.) ++ ++ In addition to the mark, each buffer has a @dfn{mark ring} which is a ++list of markers containing previous values of the mark. When editing ++commands change the mark, they should normally save the old value of the ++mark on the mark ring. The variable @code{mark-ring-max} specifies the ++maximum number of entries in the mark ring; once the list becomes this ++long, adding a new element deletes the last element. ++ ++ There is also a separate global mark ring, but that is used only in a ++few particular user-level commands, and is not relevant to Lisp ++programming. So we do not describe it here. ++ ++@defun mark &optional force ++@cindex current buffer mark ++This function returns the current buffer's mark position as an integer, ++or @code{nil} if no mark has ever been set in this buffer. ++ ++If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is ++@code{nil}, @code{mark} signals an error if the mark is inactive. ++However, if @var{force} is non-@code{nil}, then @code{mark} disregards ++inactivity of the mark, and returns the mark position (or @code{nil}) ++anyway. ++@end defun ++ ++@defun mark-marker ++This function returns the marker that represents the current buffer's ++mark. It is not a copy, it is the marker used internally. Therefore, ++changing this marker's position will directly affect the buffer's ++mark. Don't do that unless that is the effect you want. ++ ++@example ++@group ++(setq m (mark-marker)) ++ @result{} # ++@end group ++@group ++(set-marker m 100) ++ @result{} # ++@end group ++@group ++(mark-marker) ++ @result{} # ++@end group ++@end example ++ ++Like any marker, this marker can be set to point at any buffer you ++like. If you make it point at any buffer other than the one of which ++it is the mark, it will yield perfectly consistent, but rather odd, ++results. We recommend that you not do it! ++@end defun ++ ++@defun set-mark position ++This function sets the mark to @var{position}, and activates the mark. ++The old value of the mark is @emph{not} pushed onto the mark ring. ++ ++@strong{Please note:} Use this function only if you want the user to ++see that the mark has moved, and you want the previous mark position to ++be lost. Normally, when a new mark is set, the old one should go on the ++@code{mark-ring}. For this reason, most applications should use ++@code{push-mark} and @code{pop-mark}, not @code{set-mark}. ++ ++Novice Emacs Lisp programmers often try to use the mark for the wrong ++purposes. The mark saves a location for the user's convenience. An ++editing command should not alter the mark unless altering the mark is ++part of the user-level functionality of the command. (And, in that ++case, this effect should be documented.) To remember a location for ++internal use in the Lisp program, store it in a Lisp variable. For ++example: ++ ++@example ++@group ++(let ((beg (point))) ++ (forward-line 1) ++ (delete-region beg (point))). ++@end group ++@end example ++@end defun ++ ++@defun push-mark &optional position nomsg activate ++This function sets the current buffer's mark to @var{position}, and ++pushes a copy of the previous mark onto @code{mark-ring}. If ++@var{position} is @code{nil}, then the value of point is used. ++@code{push-mark} returns @code{nil}. ++ ++The function @code{push-mark} normally @emph{does not} activate the ++mark. To do that, specify @code{t} for the argument @var{activate}. ++ ++A @samp{Mark set} message is displayed unless @var{nomsg} is ++non-@code{nil}. ++@end defun ++ ++@defun pop-mark ++This function pops off the top element of @code{mark-ring} and makes ++that mark become the buffer's actual mark. This does not move point in ++the buffer, and it does nothing if @code{mark-ring} is empty. It ++deactivates the mark. ++ ++The return value is not meaningful. ++@end defun ++ ++@defopt transient-mark-mode ++This variable, if non-@code{nil}, enables Transient Mark mode. In ++Transient Mark mode, every buffer-modifying primitive sets ++@code{deactivate-mark}. As a consequence, most commands that modify ++the buffer also deactivate the mark. ++ ++When Transient Mark mode is enabled and the mark is active, many ++commands that normally apply to the text near point instead apply to ++the region. Such commands should use the function @code{use-region-p} ++to test whether they should operate on the region. @xref{The Region}. ++ ++Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, ++non-@code{t} values to enable Transient Mark mode temporarily. If the ++value is @code{lambda}, Transient Mark mode is automatically turned ++off after any action, such as buffer modification, that would normally ++deactivate the mark. If the value is @w{@code{(only . @var{oldval})}}, ++then @code{transient-mark-mode} is set to the value @var{oldval} after ++any subsequent command that moves point and is not shift-translated ++(@pxref{Key Sequence Input, shift-translation}), or after any other ++action that would normally deactivate the mark. ++@end defopt ++ ++@defopt mark-even-if-inactive ++If this is non-@code{nil}, Lisp programs and the Emacs user can use the ++mark even when it is inactive. This option affects the behavior of ++Transient Mark mode. When the option is non-@code{nil}, deactivation of ++the mark turns off region highlighting, but commands that use the mark ++behave as if the mark were still active. ++@end defopt ++ ++@defvar deactivate-mark ++If an editor command sets this variable non-@code{nil}, then the editor ++command loop deactivates the mark after the command returns (if ++Transient Mark mode is enabled). All the primitives that change the ++buffer set @code{deactivate-mark}, to deactivate the mark when the ++command is finished. ++ ++To write Lisp code that modifies the buffer without causing ++deactivation of the mark at the end of the command, bind ++@code{deactivate-mark} to @code{nil} around the code that does the ++modification. For example: ++ ++@example ++(let (deactivate-mark) ++ (insert " ")) ++@end example ++@end defvar ++ ++@defun deactivate-mark ++This function deactivates the mark, if Transient Mark mode is enabled. ++Otherwise it does nothing. ++@end defun ++ ++@defvar mark-active ++The mark is active when this variable is non-@code{nil}. This ++variable is always buffer-local in each buffer. Do @emph{not} use the ++value of this variable to decide whether a command that normally ++operates on text near point should operate on the region instead. Use ++the function @code{use-region-p} for that (@pxref{The Region}). ++@end defvar ++ ++@defvar activate-mark-hook ++@defvarx deactivate-mark-hook ++These normal hooks are run, respectively, when the mark becomes active ++and when it becomes inactive. The hook @code{activate-mark-hook} is ++also run at the end of a command if the mark is active and it is ++possible that the region may have changed. ++@end defvar ++ ++@defun handle-shift-selection ++This function implements the ``shift-selection'' behavior of ++point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs ++Manual}. It is called automatically by the Emacs command loop ++whenever a command with a @samp{^} character in its @code{interactive} ++spec is invoked, before the command itself is executed ++(@pxref{Interactive Codes, ^}). ++ ++If @code{shift-select-mode} is non-@code{nil} and the current command ++was invoked via shift translation (@pxref{Key Sequence Input, ++shift-translation}), this function sets the mark and temporarily ++activates the region, unless the region was already temporarily ++activated in this way. Otherwise, if the region has been activated ++temporarily, it deactivates the mark and restores the variable ++@code{transient-mark-mode} to its earlier value. ++@end defun ++ ++@defvar mark-ring ++The value of this buffer-local variable is the list of saved former ++marks of the current buffer, most recent first. ++ ++@example ++@group ++mark-ring ++@result{} (# ++ # ++ @dots{}) ++@end group ++@end example ++@end defvar ++ ++@defopt mark-ring-max ++The value of this variable is the maximum size of @code{mark-ring}. If ++more marks than this are pushed onto the @code{mark-ring}, ++@code{push-mark} discards an old mark when it adds a new one. ++@end defopt ++ ++@node The Region ++@section The Region ++@cindex region (between point and mark) ++ ++ The text between point and the mark is known as @dfn{the region}. ++Various functions operate on text delimited by point and the mark, but ++only those functions specifically related to the region itself are ++described here. ++ ++The next two functions signal an error if the mark does not point ++anywhere. If Transient Mark mode is enabled and ++@code{mark-even-if-inactive} is @code{nil}, they also signal an error ++if the mark is inactive. ++ ++@defun region-beginning ++This function returns the position of the beginning of the region (as ++an integer). This is the position of either point or the mark, ++whichever is smaller. ++@end defun ++ ++@defun region-end ++This function returns the position of the end of the region (as an ++integer). This is the position of either point or the mark, whichever is ++larger. ++@end defun ++ ++ Few programs need to use the @code{region-beginning} and ++@code{region-end} functions. A command designed to operate on a region ++should normally use @code{interactive} with the @samp{r} specification ++to find the beginning and end of the region. This lets other Lisp ++programs specify the bounds explicitly as arguments. (@xref{Interactive ++Codes}.) ++ ++@defun use-region-p ++This function returns @code{t} if Transient Mark mode is enabled, the ++mark is active, and there's a valid region in the buffer. Commands ++that operate on the region (instead of on text near point) when ++there's an active mark should use this to test whether to do that. ++@end defun ++ ++@ignore ++ arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299 ++@end ignore +diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi +new file mode 100644 +index 0000000..c28ab70 +--- /dev/null ++++ b/doc/lispref/minibuf.texi +@@ -0,0 +1,2140 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/minibuf ++@node Minibuffers, Command Loop, Read and Print, Top ++@chapter Minibuffers ++@cindex arguments, reading ++@cindex complex arguments ++@cindex minibuffer ++ ++ A @dfn{minibuffer} is a special buffer that Emacs commands use to ++read arguments more complicated than the single numeric prefix ++argument. These arguments include file names, buffer names, and ++command names (as in @kbd{M-x}). The minibuffer is displayed on the ++bottom line of the frame, in the same place as the echo area ++(@pxref{The Echo Area}), but only while it is in use for reading an ++argument. ++ ++@menu ++* Intro to Minibuffers:: Basic information about minibuffers. ++* Text from Minibuffer:: How to read a straight text string. ++* Object from Minibuffer:: How to read a Lisp object or expression. ++* Minibuffer History:: Recording previous minibuffer inputs ++ so the user can reuse them. ++* Initial Input:: Specifying initial contents for the minibuffer. ++* Completion:: How to invoke and customize completion. ++* Yes-or-No Queries:: Asking a question with a simple answer. ++* Multiple Queries:: Asking a series of similar questions. ++* Reading a Password:: Reading a password from the terminal. ++* Minibuffer Commands:: Commands used as key bindings in minibuffers. ++* Minibuffer Contents:: How such commands access the minibuffer text. ++* Minibuffer Windows:: Operating on the special minibuffer windows. ++* Recursive Mini:: Whether recursive entry to minibuffer is allowed. ++* Minibuffer Misc:: Various customization hooks and variables. ++@end menu ++ ++@node Intro to Minibuffers ++@section Introduction to Minibuffers ++ ++ In most ways, a minibuffer is a normal Emacs buffer. Most operations ++@emph{within} a buffer, such as editing commands, work normally in a ++minibuffer. However, many operations for managing buffers do not apply ++to minibuffers. The name of a minibuffer always has the form @w{@samp{ ++*Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are ++displayed only in special windows used only for minibuffers; these ++windows always appear at the bottom of a frame. (Sometimes frames have ++no minibuffer window, and sometimes a special kind of frame contains ++nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) ++ ++ The text in the minibuffer always starts with the @dfn{prompt string}, ++the text that was specified by the program that is using the minibuffer ++to tell the user what sort of input to type. This text is marked ++read-only so you won't accidentally delete or change it. It is also ++marked as a field (@pxref{Fields}), so that certain motion functions, ++including @code{beginning-of-line}, @code{forward-word}, ++@code{forward-sentence}, and @code{forward-paragraph}, stop at the ++boundary between the prompt and the actual text. ++ ++ The minibuffer's window is normally a single line; it grows ++automatically if the contents require more space. You can explicitly ++resize it temporarily with the window sizing commands; it reverts to ++its normal size when the minibuffer is exited. You can resize it ++permanently by using the window sizing commands in the frame's other ++window, when the minibuffer is not active. If the frame contains just ++a minibuffer, you can change the minibuffer's size by changing the ++frame's size. ++ ++ Use of the minibuffer reads input events, and that alters the values ++of variables such as @code{this-command} and @code{last-command} ++(@pxref{Command Loop Info}). Your program should bind them around the ++code that uses the minibuffer, if you do not want that to change them. ++ ++ Under some circumstances, a command can use a minibuffer even if ++there is an active minibuffer; such minibuffers are called a ++@dfn{recursive minibuffer}. The first minibuffer is named ++@w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by ++incrementing the number at the end of the name. (The names begin with ++a space so that they won't show up in normal buffer lists.) Of ++several recursive minibuffers, the innermost (or most recently ++entered) is the active minibuffer. We usually call this ``the'' ++minibuffer. You can permit or forbid recursive minibuffers by setting ++the variable @code{enable-recursive-minibuffers}, or by putting ++properties of that name on command symbols (@xref{Recursive Mini}.) ++ ++ Like other buffers, a minibuffer uses a local keymap ++(@pxref{Keymaps}) to specify special key bindings. The function that ++invokes the minibuffer also sets up its local map according to the job ++to be done. @xref{Text from Minibuffer}, for the non-completion ++minibuffer local maps. @xref{Completion Commands}, for the minibuffer ++local maps for completion. ++ ++ When Emacs is running in batch mode, any request to read from the ++minibuffer actually reads a line from the standard input descriptor that ++was supplied when Emacs was started. ++ ++@node Text from Minibuffer ++@section Reading Text Strings with the Minibuffer ++ ++ The most basic primitive for minibuffer input is ++@code{read-from-minibuffer}, which can be used to read either a string ++or a Lisp object in textual form. The function @code{read-regexp} is ++used for reading regular expressions (@pxref{Regular Expressions}), ++which are a special kind of string. There are also specialized ++functions for reading commands, variables, file names, etc.@: ++(@pxref{Completion}). ++ ++ In most cases, you should not call minibuffer input functions in the ++middle of a Lisp function. Instead, do all minibuffer input as part of ++reading the arguments for a command, in the @code{interactive} ++specification. @xref{Defining Commands}. ++ ++@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method ++This function is the most general way to get input from the ++minibuffer. By default, it accepts arbitrary text and returns it as a ++string; however, if @var{read} is non-@code{nil}, then it uses ++@code{read} to convert the text into a Lisp object (@pxref{Input ++Functions}). ++ ++The first thing this function does is to activate a minibuffer and ++display it with @var{prompt-string} as the prompt. This value must be a ++string. Then the user can edit text in the minibuffer. ++ ++When the user types a command to exit the minibuffer, ++@code{read-from-minibuffer} constructs the return value from the text in ++the minibuffer. Normally it returns a string containing that text. ++However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer} ++reads the text and returns the resulting Lisp object, unevaluated. ++(@xref{Input Functions}, for information about reading.) ++ ++The argument @var{default} specifies default values to make available ++through the history commands. It should be a string, a list of ++strings, or @code{nil}. The string or strings become the minibuffer's ++``future history,'' available to the user with @kbd{M-n}. ++ ++If @var{read} is non-@code{nil}, then @var{default} is also used ++as the input to @code{read}, if the user enters empty input. ++If @var{default} is a list of strings, the first string is used as the input. ++If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error. ++However, in the usual case (where @var{read} is @code{nil}), ++@code{read-from-minibuffer} ignores @var{default} when the user enters ++empty input and returns an empty string, @code{""}. In this respect, ++it differs from all the other minibuffer input functions in this chapter. ++ ++If @var{keymap} is non-@code{nil}, that keymap is the local keymap to ++use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the ++value of @code{minibuffer-local-map} is used as the keymap. Specifying ++a keymap is the most important way to customize the minibuffer for ++various applications such as completion. ++ ++The argument @var{hist} specifies which history list variable to use ++for saving the input and for history commands used in the minibuffer. ++It defaults to @code{minibuffer-history}. @xref{Minibuffer History}. ++ ++If the variable @code{minibuffer-allow-text-properties} is ++non-@code{nil}, then the string which is returned includes whatever text ++properties were present in the minibuffer. Otherwise all the text ++properties are stripped when the value is returned. ++ ++If the argument @var{inherit-input-method} is non-@code{nil}, then the ++minibuffer inherits the current input method (@pxref{Input Methods}) and ++the setting of @code{enable-multibyte-characters} (@pxref{Text ++Representations}) from whichever buffer was current before entering the ++minibuffer. ++ ++Use of @var{initial-contents} is mostly deprecated; we recommend using ++a non-@code{nil} value only in conjunction with specifying a cons cell ++for @var{hist}. @xref{Initial Input}. ++@end defun ++ ++@defun read-string prompt &optional initial history default inherit-input-method ++This function reads a string from the minibuffer and returns it. The ++arguments @var{prompt}, @var{initial}, @var{history} and ++@var{inherit-input-method} are used as in @code{read-from-minibuffer}. ++The keymap used is @code{minibuffer-local-map}. ++ ++The optional argument @var{default} is used as in ++@code{read-from-minibuffer}, except that, if non-@code{nil}, it also ++specifies a default value to return if the user enters null input. As ++in @code{read-from-minibuffer} it should be a string, a list of ++strings, or @code{nil} which is equivalent to an empty string. When ++@var{default} is a string, that string is the default value. When it ++is a list of strings, the first string is the default value. (All ++these strings are available to the user in the ``future minibuffer ++history.'') ++ ++This function works by calling the ++@code{read-from-minibuffer} function: ++ ++@smallexample ++@group ++(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit}) ++@equiv{} ++(let ((value ++ (read-from-minibuffer @var{prompt} @var{initial} nil nil ++ @var{history} @var{default} @var{inherit}))) ++ (if (and (equal value "") @var{default}) ++ (if (consp @var{default}) (car @var{default}) @var{default}) ++ value)) ++@end group ++@end smallexample ++@end defun ++ ++@defun read-regexp prompt &optional default-value ++This function reads a regular expression as a string from the ++minibuffer and returns it. The argument @var{prompt} is used as in ++@code{read-from-minibuffer}. The keymap used is ++@code{minibuffer-local-map}, and @code{regexp-history} is used as the ++history list (@pxref{Minibuffer History, regexp-history}). ++ ++The optional argument @var{default-value} specifies a default value to ++return if the user enters null input; it should be a string, or ++@code{nil} which is equivalent to an empty string. ++ ++In addition, @code{read-regexp} collects a few useful candidates for ++input and passes them to @code{read-from-minibuffer}, to make them ++available to the user as the ``future minibuffer history list'' ++(@pxref{Minibuffer History, future list,, emacs, The GNU Emacs ++Manual}). These candidates are: ++ ++@itemize @minus ++@item ++The word or symbol at point. ++@item ++The last regexp used in an incremental search. ++@item ++The last string used in an incremental search. ++@item ++The last string or pattern used in query-replace commands. ++@end itemize ++ ++This function works by calling the @code{read-from-minibuffer} ++function, after computing the list of defaults as described above. ++@end defun ++ ++@defvar minibuffer-allow-text-properties ++If this variable is @code{nil}, then @code{read-from-minibuffer} strips ++all text properties from the minibuffer input before returning it. ++This variable also affects @code{read-string}. However, ++@code{read-no-blanks-input} (see below), as well as ++@code{read-minibuffer} and related functions (@pxref{Object from ++Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all ++functions that do minibuffer input with completion, discard text ++properties unconditionally, regardless of the value of this variable. ++@end defvar ++ ++@defvar minibuffer-local-map ++This ++@anchor{Definition of minibuffer-local-map} ++@c avoid page break at anchor; work around Texinfo deficiency ++is the default local keymap for reading from the minibuffer. By ++default, it makes the following bindings: ++ ++@table @asis ++@item @kbd{C-j} ++@code{exit-minibuffer} ++ ++@item @key{RET} ++@code{exit-minibuffer} ++ ++@item @kbd{C-g} ++@code{abort-recursive-edit} ++ ++@item @kbd{M-n} ++@itemx @key{DOWN} ++@code{next-history-element} ++ ++@item @kbd{M-p} ++@itemx @key{UP} ++@code{previous-history-element} ++ ++@item @kbd{M-s} ++@code{next-matching-history-element} ++ ++@item @kbd{M-r} ++@code{previous-matching-history-element} ++@end table ++@end defvar ++ ++@c In version 18, initial is required ++@c Emacs 19 feature ++@defun read-no-blanks-input prompt &optional initial inherit-input-method ++This function reads a string from the minibuffer, but does not allow ++whitespace characters as part of the input: instead, those characters ++terminate the input. The arguments @var{prompt}, @var{initial}, and ++@var{inherit-input-method} are used as in @code{read-from-minibuffer}. ++ ++This is a simplified interface to the @code{read-from-minibuffer} ++function, and passes the value of the @code{minibuffer-local-ns-map} ++keymap as the @var{keymap} argument for that function. Since the keymap ++@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is} ++possible to put a space into the string, by quoting it. ++ ++This function discards text properties, regardless of the value of ++@code{minibuffer-allow-text-properties}. ++ ++@smallexample ++@group ++(read-no-blanks-input @var{prompt} @var{initial}) ++@equiv{} ++(let (minibuffer-allow-text-properties) ++ (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)) ++@end group ++@end smallexample ++@end defun ++ ++@defvar minibuffer-local-ns-map ++This built-in variable is the keymap used as the minibuffer local keymap ++in the function @code{read-no-blanks-input}. By default, it makes the ++following bindings, in addition to those of @code{minibuffer-local-map}: ++ ++@table @asis ++@item @key{SPC} ++@cindex @key{SPC} in minibuffer ++@code{exit-minibuffer} ++ ++@item @key{TAB} ++@cindex @key{TAB} in minibuffer ++@code{exit-minibuffer} ++ ++@item @kbd{?} ++@cindex @kbd{?} in minibuffer ++@code{self-insert-and-exit} ++@end table ++@end defvar ++ ++@node Object from Minibuffer ++@section Reading Lisp Objects with the Minibuffer ++ ++ This section describes functions for reading Lisp objects with the ++minibuffer. ++ ++@defun read-minibuffer prompt &optional initial ++This function reads a Lisp object using the minibuffer, and returns it ++without evaluating it. The arguments @var{prompt} and @var{initial} are ++used as in @code{read-from-minibuffer}. ++ ++This is a simplified interface to the ++@code{read-from-minibuffer} function: ++ ++@smallexample ++@group ++(read-minibuffer @var{prompt} @var{initial}) ++@equiv{} ++(let (minibuffer-allow-text-properties) ++ (read-from-minibuffer @var{prompt} @var{initial} nil t)) ++@end group ++@end smallexample ++ ++Here is an example in which we supply the string @code{"(testing)"} as ++initial input: ++ ++@smallexample ++@group ++(read-minibuffer ++ "Enter an expression: " (format "%s" '(testing))) ++ ++;; @r{Here is how the minibuffer is displayed:} ++@end group ++ ++@group ++---------- Buffer: Minibuffer ---------- ++Enter an expression: (testing)@point{} ++---------- Buffer: Minibuffer ---------- ++@end group ++@end smallexample ++ ++@noindent ++The user can type @key{RET} immediately to use the initial input as a ++default, or can edit the input. ++@end defun ++ ++@defun eval-minibuffer prompt &optional initial ++This function reads a Lisp expression using the minibuffer, evaluates ++it, then returns the result. The arguments @var{prompt} and ++@var{initial} are used as in @code{read-from-minibuffer}. ++ ++This function simply evaluates the result of a call to ++@code{read-minibuffer}: ++ ++@smallexample ++@group ++(eval-minibuffer @var{prompt} @var{initial}) ++@equiv{} ++(eval (read-minibuffer @var{prompt} @var{initial})) ++@end group ++@end smallexample ++@end defun ++ ++@defun edit-and-eval-command prompt form ++This function reads a Lisp expression in the minibuffer, and then ++evaluates it. The difference between this command and ++@code{eval-minibuffer} is that here the initial @var{form} is not ++optional and it is treated as a Lisp object to be converted to printed ++representation rather than as a string of text. It is printed with ++@code{prin1}, so if it is a string, double-quote characters (@samp{"}) ++appear in the initial text. @xref{Output Functions}. ++ ++The first thing @code{edit-and-eval-command} does is to activate the ++minibuffer with @var{prompt} as the prompt. Then it inserts the printed ++representation of @var{form} in the minibuffer, and lets the user edit it. ++When the user exits the minibuffer, the edited text is read with ++@code{read} and then evaluated. The resulting value becomes the value ++of @code{edit-and-eval-command}. ++ ++In the following example, we offer the user an expression with initial ++text which is a valid form already: ++ ++@smallexample ++@group ++(edit-and-eval-command "Please edit: " '(forward-word 1)) ++ ++;; @r{After evaluation of the preceding expression,} ++;; @r{the following appears in the minibuffer:} ++@end group ++ ++@group ++---------- Buffer: Minibuffer ---------- ++Please edit: (forward-word 1)@point{} ++---------- Buffer: Minibuffer ---------- ++@end group ++@end smallexample ++ ++@noindent ++Typing @key{RET} right away would exit the minibuffer and evaluate the ++expression, thus moving point forward one word. ++@code{edit-and-eval-command} returns @code{nil} in this example. ++@end defun ++ ++@node Minibuffer History ++@section Minibuffer History ++@cindex minibuffer history ++@cindex history list ++ ++ A @dfn{minibuffer history list} records previous minibuffer inputs so ++the user can reuse them conveniently. A history list is actually a ++symbol, not a list; it is a variable whose value is a list of strings ++(previous inputs), most recent first. ++ ++ There are many separate history lists, used for different kinds of ++inputs. It's the Lisp programmer's job to specify the right history ++list for each use of the minibuffer. ++ ++ You specify the history list with the optional @var{hist} argument ++to either @code{read-from-minibuffer} or @code{completing-read}. Here ++are the possible values for it: ++ ++@table @asis ++@item @var{variable} ++Use @var{variable} (a symbol) as the history list. ++ ++@item (@var{variable} . @var{startpos}) ++Use @var{variable} (a symbol) as the history list, and assume that the ++initial history position is @var{startpos} (a nonnegative integer). ++ ++Specifying 0 for @var{startpos} is equivalent to just specifying the ++symbol @var{variable}. @code{previous-history-element} will display ++the most recent element of the history list in the minibuffer. If you ++specify a positive @var{startpos}, the minibuffer history functions ++behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the ++history element currently shown in the minibuffer. ++ ++For consistency, you should also specify that element of the history ++as the initial minibuffer contents, using the @var{initial} argument ++to the minibuffer input function (@pxref{Initial Input}). ++@end table ++ ++ If you don't specify @var{hist}, then the default history list ++@code{minibuffer-history} is used. For other standard history lists, ++see below. You can also create your own history list variable; just ++initialize it to @code{nil} before the first use. ++ ++ Both @code{read-from-minibuffer} and @code{completing-read} add new ++elements to the history list automatically, and provide commands to ++allow the user to reuse items on the list. The only thing your program ++needs to do to use a history list is to initialize it and to pass its ++name to the input functions when you wish. But it is safe to modify the ++list by hand when the minibuffer input functions are not using it. ++ ++ Emacs functions that add a new element to a history list can also ++delete old elements if the list gets too long. The variable ++@code{history-length} specifies the maximum length for most history ++lists. To specify a different maximum length for a particular history ++list, put the length in the @code{history-length} property of the ++history list symbol. The variable @code{history-delete-duplicates} ++specifies whether to delete duplicates in history. ++ ++@defun add-to-history history-var newelt &optional maxelt keep-all ++This function adds a new element @var{newelt}, if it isn't the empty ++string, to the history list stored in the variable @var{history-var}, ++and returns the updated history list. It limits the list length to ++the value of @var{maxelt} (if non-@code{nil}) or @code{history-length} ++(described below). The possible values of @var{maxelt} have the same ++meaning as the values of @code{history-length}. ++ ++Normally, @code{add-to-history} removes duplicate members from the ++history list if @code{history-delete-duplicates} is non-@code{nil}. ++However, if @var{keep-all} is non-@code{nil}, that says not to remove ++duplicates, and to add @var{newelt} to the list even if it is empty. ++@end defun ++ ++@defvar history-add-new-input ++If the value of this variable is @code{nil}, standard functions that ++read from the minibuffer don't add new elements to the history list. ++This lets Lisp programs explicitly manage input history by using ++@code{add-to-history}. By default, @code{history-add-new-input} is ++set to a non-@code{nil} value. ++@end defvar ++ ++@defopt history-length ++The value of this variable specifies the maximum length for all ++history lists that don't specify their own maximum lengths. If the ++value is @code{t}, that means there no maximum (don't delete old ++elements). The value of @code{history-length} property of the history ++list variable's symbol, if set, overrides this variable for that ++particular history list. ++@end defopt ++ ++@defopt history-delete-duplicates ++If the value of this variable is @code{t}, that means when adding a ++new history element, all previous identical elements are deleted. ++@end defopt ++ ++ Here are some of the standard minibuffer history list variables: ++ ++@defvar minibuffer-history ++The default history list for minibuffer history input. ++@end defvar ++ ++@defvar query-replace-history ++A history list for arguments to @code{query-replace} (and similar ++arguments to other commands). ++@end defvar ++ ++@defvar file-name-history ++A history list for file-name arguments. ++@end defvar ++ ++@defvar buffer-name-history ++A history list for buffer-name arguments. ++@end defvar ++ ++@defvar regexp-history ++A history list for regular expression arguments. ++@end defvar ++ ++@defvar extended-command-history ++A history list for arguments that are names of extended commands. ++@end defvar ++ ++@defvar shell-command-history ++A history list for arguments that are shell commands. ++@end defvar ++ ++@defvar read-expression-history ++A history list for arguments that are Lisp expressions to evaluate. ++@end defvar ++ ++@node Initial Input ++@section Initial Input ++ ++Several of the functions for minibuffer input have an argument called ++@var{initial} or @var{initial-contents}. This is a mostly-deprecated ++feature for specifying that the minibuffer should start out with ++certain text, instead of empty as usual. ++ ++If @var{initial} is a string, the minibuffer starts out containing the ++text of the string, with point at the end, when the user starts to ++edit the text. If the user simply types @key{RET} to exit the ++minibuffer, it will use the initial input string to determine the ++value to return. ++ ++@strong{We discourage use of a non-@code{nil} value for ++@var{initial}}, because initial input is an intrusive interface. ++History lists and default values provide a much more convenient method ++to offer useful default inputs to the user. ++ ++There is just one situation where you should specify a string for an ++@var{initial} argument. This is when you specify a cons cell for the ++@var{hist} or @var{history} argument. @xref{Minibuffer History}. ++ ++@var{initial} can also be a cons cell of the form @code{(@var{string} ++. @var{position})}. This means to insert @var{string} in the ++minibuffer but put point at @var{position} within the string's text. ++ ++As a historical accident, @var{position} was implemented ++inconsistently in different functions. In @code{completing-read}, ++@var{position}'s value is interpreted as origin-zero; that is, a value ++of 0 means the beginning of the string, 1 means after the first ++character, etc. In @code{read-minibuffer}, and the other ++non-completion minibuffer input functions that support this argument, ++1 means the beginning of the string 2 means after the first character, ++etc. ++ ++Use of a cons cell as the value for @var{initial} arguments is ++deprecated in user code. ++ ++@node Completion ++@section Completion ++@cindex completion ++ ++ @dfn{Completion} is a feature that fills in the rest of a name ++starting from an abbreviation for it. Completion works by comparing the ++user's input against a list of valid names and determining how much of ++the name is determined uniquely by what the user has typed. For ++example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then ++type the first few letters of the name of the buffer to which you wish ++to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs ++extends the name as far as it can. ++ ++ Standard Emacs commands offer completion for names of symbols, files, ++buffers, and processes; with the functions in this section, you can ++implement completion for other kinds of names. ++ ++ The @code{try-completion} function is the basic primitive for ++completion: it returns the longest determined completion of a given ++initial string, with a given set of strings to match against. ++ ++ The function @code{completing-read} provides a higher-level interface ++for completion. A call to @code{completing-read} specifies how to ++determine the list of valid names. The function then activates the ++minibuffer with a local keymap that binds a few keys to commands useful ++for completion. Other functions provide convenient simple interfaces ++for reading certain kinds of names with completion. ++ ++@menu ++* Basic Completion:: Low-level functions for completing strings. ++ (These are too low level to use the minibuffer.) ++* Minibuffer Completion:: Invoking the minibuffer with completion. ++* Completion Commands:: Minibuffer commands that do completion. ++* High-Level Completion:: Convenient special cases of completion ++ (reading buffer name, file name, etc.). ++* Reading File Names:: Using completion to read file names and ++ shell commands. ++* Completion Styles:: Specifying rules for performing completion. ++* Programmed Completion:: Writing your own completion-function. ++@end menu ++ ++@node Basic Completion ++@subsection Basic Completion Functions ++ ++ The completion functions @code{try-completion}, ++@code{all-completions} and @code{test-completion} have nothing in ++themselves to do with minibuffers. We describe them in this chapter ++so as to keep them near the higher-level completion features that do ++use the minibuffer. ++ ++ If you store a completion alist in a variable, you should mark the ++variable as ``risky'' with a non-@code{nil} ++@code{risky-local-variable} property. ++ ++@defun try-completion string collection &optional predicate ++This function returns the longest common substring of all possible ++completions of @var{string} in @var{collection}. The value of ++@var{collection} must be a list of strings or symbols, an alist, an ++obarray, a hash table, or a function that implements a virtual set of ++strings (see below). ++ ++Completion compares @var{string} against each of the permissible ++completions specified by @var{collection}; if the beginning of the ++permissible completion equals @var{string}, it matches. If no permissible ++completions match, @code{try-completion} returns @code{nil}. If only ++one permissible completion matches, and the match is exact, then ++@code{try-completion} returns @code{t}. Otherwise, the value is the ++longest initial sequence common to all the permissible completions that ++match. ++ ++If @var{collection} is an alist (@pxref{Association Lists}), the ++permissible completions are the elements of the alist that are either ++strings, symbols, or conses whose @sc{car} is a string or symbol. ++Symbols are converted to strings using @code{symbol-name}. Other ++elements of the alist are ignored. (Remember that in Emacs Lisp, the ++elements of alists do not @emph{have} to be conses.) In particular, a ++list of strings or symbols is allowed, even though we usually do not ++think of such lists as alists. ++ ++@cindex obarray in completion ++If @var{collection} is an obarray (@pxref{Creating Symbols}), the names ++of all symbols in the obarray form the set of permissible completions. The ++global variable @code{obarray} holds an obarray containing the names of ++all interned Lisp symbols. ++ ++Note that the only valid way to make a new obarray is to create it ++empty and then add symbols to it one by one using @code{intern}. ++Also, you cannot intern a given symbol in more than one obarray. ++ ++If @var{collection} is a hash table, then the keys that are strings ++are the possible completions. Other keys are ignored. ++ ++You can also use a symbol that is a function as @var{collection}. Then ++the function is solely responsible for performing completion; ++@code{try-completion} returns whatever this function returns. The ++function is called with three arguments: @var{string}, @var{predicate} ++and @code{nil}. (The reason for the third argument is so that the same ++function can be used in @code{all-completions} and do the appropriate ++thing in either case.) @xref{Programmed Completion}. ++ ++If the argument @var{predicate} is non-@code{nil}, then it must be a ++function of one argument, unless @var{collection} is a hash table, in ++which case it should be a function of two arguments. It is used to ++test each possible match, and the match is accepted only if ++@var{predicate} returns non-@code{nil}. The argument given to ++@var{predicate} is either a string or a cons cell (the @sc{car} of ++which is a string) from the alist, or a symbol (@emph{not} a symbol ++name) from the obarray. If @var{collection} is a hash table, ++@var{predicate} is called with two arguments, the string key and the ++associated value. ++ ++In addition, to be acceptable, a completion must also match all the ++regular expressions in @code{completion-regexp-list}. (Unless ++@var{collection} is a function, in which case that function has to ++handle @code{completion-regexp-list} itself.) ++ ++In the first of the following examples, the string @samp{foo} is ++matched by three of the alist @sc{car}s. All of the matches begin with ++the characters @samp{fooba}, so that is the result. In the second ++example, there is only one possible match, and it is exact, so the value ++is @code{t}. ++ ++@smallexample ++@group ++(try-completion ++ "foo" ++ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) ++ @result{} "fooba" ++@end group ++ ++@group ++(try-completion "foo" '(("barfoo" 2) ("foo" 3))) ++ @result{} t ++@end group ++@end smallexample ++ ++In the following example, numerous symbols begin with the characters ++@samp{forw}, and all of them begin with the word @samp{forward}. In ++most of the symbols, this is followed with a @samp{-}, but not in all, ++so no more than @samp{forward} can be completed. ++ ++@smallexample ++@group ++(try-completion "forw" obarray) ++ @result{} "forward" ++@end group ++@end smallexample ++ ++Finally, in the following example, only two of the three possible ++matches pass the predicate @code{test} (the string @samp{foobaz} is ++too short). Both of those begin with the string @samp{foobar}. ++ ++@smallexample ++@group ++(defun test (s) ++ (> (length (car s)) 6)) ++ @result{} test ++@end group ++@group ++(try-completion ++ "foo" ++ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) ++ 'test) ++ @result{} "foobar" ++@end group ++@end smallexample ++@end defun ++ ++@defun all-completions string collection &optional predicate nospace ++This function returns a list of all possible completions of ++@var{string}. The arguments to this function (aside from ++@var{nospace}) are the same as those of @code{try-completion}. Also, ++this function uses @code{completion-regexp-list} in the same way that ++@code{try-completion} does. The optional argument @var{nospace} only ++matters if @var{string} is the empty string. In that case, if ++@var{nospace} is non-@code{nil}, completions that start with a space ++are ignored. ++ ++If @var{collection} is a function, it is called with three arguments: ++@var{string}, @var{predicate} and @code{t}; then @code{all-completions} ++returns whatever the function returns. @xref{Programmed Completion}. ++ ++Here is an example, using the function @code{test} shown in the ++example for @code{try-completion}: ++ ++@smallexample ++@group ++(defun test (s) ++ (> (length (car s)) 6)) ++ @result{} test ++@end group ++ ++@group ++(all-completions ++ "foo" ++ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) ++ 'test) ++ @result{} ("foobar1" "foobar2") ++@end group ++@end smallexample ++@end defun ++ ++@defun test-completion string collection &optional predicate ++@anchor{Definition of test-completion} ++This function returns non-@code{nil} if @var{string} is a valid ++completion possibility specified by @var{collection} and ++@var{predicate}. The arguments are the same as in ++@code{try-completion}. For instance, if @var{collection} is a list of ++strings, this is true if @var{string} appears in the list and ++@var{predicate} is satisfied. ++ ++This function uses @code{completion-regexp-list} in the same ++way that @code{try-completion} does. ++ ++If @var{predicate} is non-@code{nil} and if @var{collection} contains ++several strings that are equal to each other, as determined by ++@code{compare-strings} according to @code{completion-ignore-case}, ++then @var{predicate} should accept either all or none of them. ++Otherwise, the return value of @code{test-completion} is essentially ++unpredictable. ++ ++If @var{collection} is a function, it is called with three arguments, ++the values @var{string}, @var{predicate} and @code{lambda}; whatever ++it returns, @code{test-completion} returns in turn. ++@end defun ++ ++@defvar completion-ignore-case ++If the value of this variable is non-@code{nil}, Emacs does not ++consider case significant in completion. Note, however, that this ++variable is overridden by @code{read-file-name-completion-ignore-case} ++within @code{read-file-name} (@pxref{Reading File Names}), and by ++@code{read-buffer-completion-ignore-case} within @code{read-buffer} ++(@pxref{High-Level Completion}). ++@end defvar ++ ++@defvar completion-regexp-list ++This is a list of regular expressions. The completion functions only ++consider a completion acceptable if it matches all regular expressions ++in this list, with @code{case-fold-search} (@pxref{Searching and Case}) ++bound to the value of @code{completion-ignore-case}. ++@end defvar ++ ++@defmac lazy-completion-table var fun ++This macro provides a way to initialize the variable @var{var} as a ++collection for completion in a lazy way, not computing its actual ++contents until they are first needed. You use this macro to produce a ++value that you store in @var{var}. The actual computation of the ++proper value is done the first time you do completion using @var{var}. ++It is done by calling @var{fun} with no arguments. The ++value @var{fun} returns becomes the permanent value of @var{var}. ++ ++Here is an example of use: ++ ++@smallexample ++(defvar foo (lazy-completion-table foo make-my-alist)) ++@end smallexample ++@end defmac ++ ++@node Minibuffer Completion ++@subsection Completion and the Minibuffer ++@cindex minibuffer completion ++@cindex reading from minibuffer with completion ++ ++ This section describes the basic interface for reading from the ++minibuffer with completion. ++ ++@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method ++This function reads a string in the minibuffer, assisting the user by ++providing completion. It activates the minibuffer with prompt ++@var{prompt}, which must be a string. ++ ++The actual completion is done by passing @var{collection} and ++@var{predicate} to the function @code{try-completion}. This happens ++in certain commands bound in the local keymaps used for completion. ++Some of these commands also call @code{test-completion}. Thus, if ++@var{predicate} is non-@code{nil}, it should be compatible with ++@var{collection} and @code{completion-ignore-case}. @xref{Definition ++of test-completion}. ++ ++The value of the optional argument @var{require-match} determines how ++the user may exit the minibuffer: ++ ++@itemize @bullet ++@item ++If @code{nil}, the usual minibuffer exit commands work regardless of ++the input in the minibuffer. ++ ++@item ++If @code{t}, the usual minibuffer exit commands won't exit unless the ++input completes to an element of @var{collection}. ++ ++@item ++If @code{confirm}, the user can exit with any input, but is asked for ++confirmation if the input is not an element of @var{collection}. ++ ++@item ++If @code{confirm-after-completion}, the user can exit with any input, ++but is asked for confirmation if the preceding command was a ++completion command (i.e., one of the commands in ++@code{minibuffer-confirm-exit-commands}) and the resulting input is ++not an element of @var{collection}. @xref{Completion Commands}. ++ ++@item ++Any other value of @var{require-match} behaves like @code{t}, except ++that the exit commands won't exit if it performs completion. ++@end itemize ++ ++However, empty input is always permitted, regardless of the value of ++@var{require-match}; in that case, @code{completing-read} returns the ++first element of @var{default}, if it is a list; @code{""}, if ++@var{default} is @code{nil}; or @var{default}. The string or strings ++in @var{default} are also available to the user through the history ++commands. ++ ++The function @code{completing-read} uses ++@code{minibuffer-local-completion-map} as the keymap if ++@var{require-match} is @code{nil}, and uses ++@code{minibuffer-local-must-match-map} if @var{require-match} is ++non-@code{nil}. @xref{Completion Commands}. ++ ++The argument @var{hist} specifies which history list variable to use for ++saving the input and for minibuffer history commands. It defaults to ++@code{minibuffer-history}. @xref{Minibuffer History}. ++ ++The argument @var{initial} is mostly deprecated; we recommend using a ++non-@code{nil} value only in conjunction with specifying a cons cell ++for @var{hist}. @xref{Initial Input}. For default input, use ++@var{default} instead. ++ ++If the argument @var{inherit-input-method} is non-@code{nil}, then the ++minibuffer inherits the current input method (@pxref{Input ++Methods}) and the setting of @code{enable-multibyte-characters} ++(@pxref{Text Representations}) from whichever buffer was current before ++entering the minibuffer. ++ ++If the built-in variable @code{completion-ignore-case} is ++non-@code{nil}, completion ignores case when comparing the input ++against the possible matches. @xref{Basic Completion}. In this mode ++of operation, @var{predicate} must also ignore case, or you will get ++surprising results. ++ ++Here's an example of using @code{completing-read}: ++ ++@smallexample ++@group ++(completing-read ++ "Complete a foo: " ++ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) ++ nil t "fo") ++@end group ++ ++@group ++;; @r{After evaluation of the preceding expression,} ++;; @r{the following appears in the minibuffer:} ++ ++---------- Buffer: Minibuffer ---------- ++Complete a foo: fo@point{} ++---------- Buffer: Minibuffer ---------- ++@end group ++@end smallexample ++ ++@noindent ++If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}}, ++@code{completing-read} returns @code{barfoo}. ++ ++The @code{completing-read} function binds variables to pass ++information to the commands that actually do completion. ++They are described in the following section. ++@end defun ++ ++@node Completion Commands ++@subsection Minibuffer Commands that Do Completion ++ ++ This section describes the keymaps, commands and user options used ++in the minibuffer to do completion. ++ ++@defvar minibuffer-completion-table ++The value of this variable is the collection used for completion in ++the minibuffer. This is the global variable that contains what ++@code{completing-read} passes to @code{try-completion}. It is used by ++minibuffer completion commands such as @code{minibuffer-complete-word}. ++@end defvar ++ ++@defvar minibuffer-completion-predicate ++This variable's value is the predicate that @code{completing-read} ++passes to @code{try-completion}. The variable is also used by the other ++minibuffer completion functions. ++@end defvar ++ ++@defvar minibuffer-completion-confirm ++This variable determines whether Emacs asks for confirmation before ++exiting the minibuffer; @code{completing-read} binds this variable, ++and the function @code{minibuffer-complete-and-exit} checks the value ++before exiting. If the value is @code{nil}, confirmation is not ++required. If the value is @code{confirm}, the user may exit with an ++input that is not a valid completion alternative, but Emacs asks for ++confirmation. If the value is @code{confirm-after-completion}, the ++user may exit with an input that is not a valid completion ++alternative, but Emacs asks for confirmation if the user submitted the ++input right after any of the completion commands in ++@code{minibuffer-confirm-exit-commands}. ++@end defvar ++ ++@defvar minibuffer-confirm-exit-commands ++This variable holds a list of commands that cause Emacs to ask for ++confirmation before exiting the minibuffer, if the @var{require-match} ++argument to @code{completing-read} is @code{confirm-after-completion}. ++The confirmation is requested if the user attempts to exit the ++minibuffer immediately after calling any command in this list. ++@end defvar ++ ++@deffn Command minibuffer-complete-word ++This function completes the minibuffer contents by at most a single ++word. Even if the minibuffer contents have only one completion, ++@code{minibuffer-complete-word} does not add any characters beyond the ++first character that is not a word constituent. @xref{Syntax Tables}. ++@end deffn ++ ++@deffn Command minibuffer-complete ++This function completes the minibuffer contents as far as possible. ++@end deffn ++ ++@deffn Command minibuffer-complete-and-exit ++This function completes the minibuffer contents, and exits if ++confirmation is not required, i.e., if ++@code{minibuffer-completion-confirm} is @code{nil}. If confirmation ++@emph{is} required, it is given by repeating this command ++immediately---the command is programmed to work without confirmation ++when run twice in succession. ++@end deffn ++ ++@deffn Command minibuffer-completion-help ++This function creates a list of the possible completions of the ++current minibuffer contents. It works by calling @code{all-completions} ++using the value of the variable @code{minibuffer-completion-table} as ++the @var{collection} argument, and the value of ++@code{minibuffer-completion-predicate} as the @var{predicate} argument. ++The list of completions is displayed as text in a buffer named ++@samp{*Completions*}. ++@end deffn ++ ++@defun display-completion-list completions &optional common-substring ++This function displays @var{completions} to the stream in ++@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more ++information about streams.) The argument @var{completions} is normally ++a list of completions just returned by @code{all-completions}, but it ++does not have to be. Each element may be a symbol or a string, either ++of which is simply printed. It can also be a list of two strings, ++which is printed as if the strings were concatenated. The first of ++the two strings is the actual completion, the second string serves as ++annotation. ++ ++The argument @var{common-substring} is the prefix that is common to ++all the completions. With normal Emacs completion, it is usually the ++same as the string that was completed. @code{display-completion-list} ++uses this to highlight text in the completion list for better visual ++feedback. This is not needed in the minibuffer; for minibuffer ++completion, you can pass @code{nil}. ++ ++This function is called by @code{minibuffer-completion-help}. The ++most common way to use it is together with ++@code{with-output-to-temp-buffer}, like this: ++ ++@example ++(with-output-to-temp-buffer "*Completions*" ++ (display-completion-list ++ (all-completions (buffer-string) my-alist) ++ (buffer-string))) ++@end example ++@end defun ++ ++@defopt completion-auto-help ++If this variable is non-@code{nil}, the completion commands ++automatically display a list of possible completions whenever nothing ++can be completed because the next character is not uniquely determined. ++@end defopt ++ ++@defvar minibuffer-local-completion-map ++@code{completing-read} uses this value as the local keymap when an ++exact match of one of the completions is not required. By default, this ++keymap makes the following bindings: ++ ++@table @asis ++@item @kbd{?} ++@code{minibuffer-completion-help} ++ ++@item @key{SPC} ++@code{minibuffer-complete-word} ++ ++@item @key{TAB} ++@code{minibuffer-complete} ++@end table ++ ++@noindent ++with other characters bound as in @code{minibuffer-local-map} ++(@pxref{Definition of minibuffer-local-map}). ++@end defvar ++ ++@defvar minibuffer-local-must-match-map ++@code{completing-read} uses this value as the local keymap when an ++exact match of one of the completions is required. Therefore, no keys ++are bound to @code{exit-minibuffer}, the command that exits the ++minibuffer unconditionally. By default, this keymap makes the following ++bindings: ++ ++@table @asis ++@item @kbd{?} ++@code{minibuffer-completion-help} ++ ++@item @key{SPC} ++@code{minibuffer-complete-word} ++ ++@item @key{TAB} ++@code{minibuffer-complete} ++ ++@item @kbd{C-j} ++@code{minibuffer-complete-and-exit} ++ ++@item @key{RET} ++@code{minibuffer-complete-and-exit} ++@end table ++ ++@noindent ++with other characters bound as in @code{minibuffer-local-map}. ++@end defvar ++ ++@defvar minibuffer-local-filename-completion-map ++This is like @code{minibuffer-local-completion-map} ++except that it does not bind @key{SPC}. This keymap is used by the ++function @code{read-file-name}. ++@end defvar ++ ++@defvar minibuffer-local-filename-must-match-map ++This is like @code{minibuffer-local-must-match-map} ++except that it does not bind @key{SPC}. This keymap is used by the ++function @code{read-file-name}. ++@end defvar ++ ++@node High-Level Completion ++@subsection High-Level Completion Functions ++ ++ This section describes the higher-level convenient functions for ++reading certain sorts of names with completion. ++ ++ In most cases, you should not call these functions in the middle of a ++Lisp function. When possible, do all minibuffer input as part of ++reading the arguments for a command, in the @code{interactive} ++specification. @xref{Defining Commands}. ++ ++@defun read-buffer prompt &optional default require-match ++This function reads the name of a buffer and returns it as a string. ++The argument @var{default} is the default name to use, the value to ++return if the user exits with an empty minibuffer. If non-@code{nil}, ++it should be a string, a list of strings, or a buffer. If it is ++a list, the default value is the first element of this list. It is ++mentioned in the prompt, but is not inserted in the minibuffer as ++initial input. ++ ++The argument @var{prompt} should be a string ending with a colon and a ++space. If @var{default} is non-@code{nil}, the function inserts it in ++@var{prompt} before the colon to follow the convention for reading from ++the minibuffer with a default value (@pxref{Programming Tips}). ++ ++The optional argument @var{require-match} has the same meaning as in ++@code{completing-read}. @xref{Minibuffer Completion}. ++ ++In the following example, the user enters @samp{minibuffer.t}, and ++then types @key{RET}. The argument @var{require-match} is @code{t}, ++and the only buffer name starting with the given input is ++@samp{minibuffer.texi}, so that name is the value. ++ ++@example ++(read-buffer "Buffer name: " "foo" t) ++@group ++;; @r{After evaluation of the preceding expression,} ++;; @r{the following prompt appears,} ++;; @r{with an empty minibuffer:} ++@end group ++ ++@group ++---------- Buffer: Minibuffer ---------- ++Buffer name (default foo): @point{} ++---------- Buffer: Minibuffer ---------- ++@end group ++ ++@group ++;; @r{The user types @kbd{minibuffer.t @key{RET}}.} ++ @result{} "minibuffer.texi" ++@end group ++@end example ++@end defun ++ ++@defopt read-buffer-function ++This variable specifies how to read buffer names. For example, if you ++set this variable to @code{iswitchb-read-buffer}, all Emacs commands ++that call @code{read-buffer} to read a buffer name will actually use the ++@code{iswitchb} package to read it. ++@end defopt ++ ++@defopt read-buffer-completion-ignore-case ++If this variable is non-@code{nil}, @code{read-buffer} ignores case ++when performing completion. ++@end defopt ++ ++@defun read-command prompt &optional default ++This function reads the name of a command and returns it as a Lisp ++symbol. The argument @var{prompt} is used as in ++@code{read-from-minibuffer}. Recall that a command is anything for ++which @code{commandp} returns @code{t}, and a command name is a symbol ++for which @code{commandp} returns @code{t}. @xref{Interactive Call}. ++ ++The argument @var{default} specifies what to return if the user enters ++null input. It can be a symbol, a string or a list of strings. If it ++is a string, @code{read-command} interns it before returning it. ++If it is a list, @code{read-command} returns the first element of this list. ++If @var{default} is @code{nil}, that means no default has been ++specified; then if the user enters null input, the return value is ++@code{(intern "")}, that is, a symbol whose name is an empty string. ++ ++@example ++(read-command "Command name? ") ++ ++@group ++;; @r{After evaluation of the preceding expression,} ++;; @r{the following prompt appears with an empty minibuffer:} ++@end group ++ ++@group ++---------- Buffer: Minibuffer ---------- ++Command name? ++---------- Buffer: Minibuffer ---------- ++@end group ++@end example ++ ++@noindent ++If the user types @kbd{forward-c @key{RET}}, then this function returns ++@code{forward-char}. ++ ++The @code{read-command} function is a simplified interface to ++@code{completing-read}. It uses the variable @code{obarray} so as to ++complete in the set of extant Lisp symbols, and it uses the ++@code{commandp} predicate so as to accept only command names: ++ ++@cindex @code{commandp} example ++@example ++@group ++(read-command @var{prompt}) ++@equiv{} ++(intern (completing-read @var{prompt} obarray ++ 'commandp t nil)) ++@end group ++@end example ++@end defun ++ ++@defun read-variable prompt &optional default ++@anchor{Definition of read-variable} ++This function reads the name of a user variable and returns it as a ++symbol. ++ ++The argument @var{default} specifies the default value to return if ++the user enters null input. It can be a symbol, a string, or a list ++of strings. If it is a string, @code{read-variable} interns it to ++make the default value. If it is a list, @code{read-variable} interns ++the first element. If @var{default} is @code{nil}, that means no ++default has been specified; then if the user enters null input, the ++return value is @code{(intern "")}. ++ ++@example ++@group ++(read-variable "Variable name? ") ++ ++;; @r{After evaluation of the preceding expression,} ++;; @r{the following prompt appears,} ++;; @r{with an empty minibuffer:} ++@end group ++ ++@group ++---------- Buffer: Minibuffer ---------- ++Variable name? @point{} ++---------- Buffer: Minibuffer ---------- ++@end group ++@end example ++ ++@noindent ++If the user then types @kbd{fill-p @key{RET}}, @code{read-variable} ++returns @code{fill-prefix}. ++ ++In general, @code{read-variable} is similar to @code{read-command}, ++but uses the predicate @code{user-variable-p} instead of ++@code{commandp}: ++ ++@cindex @code{user-variable-p} example ++@example ++@group ++(read-variable @var{prompt}) ++@equiv{} ++(intern ++ (completing-read @var{prompt} obarray ++ 'user-variable-p t nil)) ++@end group ++@end example ++@end defun ++ ++@deffn Command read-color &optional prompt convert allow-empty display ++This function reads a string that is a color specification, either the ++color's name or an RGB hex value such as @code{#RRRGGGBBB}. It ++prompts with @var{prompt} (default: @code{"Color (name or #R+G+B+):"}) ++and provides completion for color names, but not for hex RGB values. ++In addition to names of standard colors, completion candidates include ++the foreground and background colors at point. ++ ++Valid RGB values are described in @ref{Color Names}. ++ ++The function's return value is the color name typed by the user in the ++minibuffer. However, when called interactively or if the optional ++argument @var{convert} is non-@code{nil}, it converts the name into ++the color's RGB value and returns that value as a string. If an ++invalid color name was specified, this function signals an error, ++except that empty color names are allowed when @code{allow-empty} is ++non-@code{nil} and the user enters null input. ++ ++Interactively, or when @var{display} is non-@code{nil}, the return ++value is also displayed in the echo area. ++@end deffn ++ ++ See also the functions @code{read-coding-system} and ++@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}, ++and @code{read-input-method-name}, in @ref{Input Methods}. ++ ++@node Reading File Names ++@subsection Reading File Names ++@cindex read file names ++@cindex prompt for file name ++ ++ The high-level completion functions @code{read-file-name}, ++@code{read-directory-name}, and @code{read-shell-command} are designed ++to read file names, directory names, and shell commands respectively. ++They provide special features, including automatic insertion of the ++default directory. ++ ++@defun read-file-name prompt &optional directory default require-match initial predicate ++This function reads a file name in the minibuffer, prompting with ++@var{prompt} and providing completion. ++ ++The optional argument @var{require-match} has the same meaning as in ++@code{completing-read}. @xref{Minibuffer Completion}. ++ ++@code{read-file-name} uses ++@code{minibuffer-local-filename-completion-map} as the keymap if ++@var{require-match} is @code{nil}, and uses ++@code{minibuffer-local-filename-must-match-map} if @var{require-match} ++is non-@code{nil}. @xref{Completion Commands}. ++ ++The argument @var{directory} specifies the directory to use for ++completion of relative file names. It should be an absolute directory ++name. If @code{insert-default-directory} is non-@code{nil}, ++@var{directory} is also inserted in the minibuffer as initial input. ++It defaults to the current buffer's value of @code{default-directory}. ++ ++@c Emacs 19 feature ++If you specify @var{initial}, that is an initial file name to insert ++in the buffer (after @var{directory}, if that is inserted). In this ++case, point goes at the beginning of @var{initial}. The default for ++@var{initial} is @code{nil}---don't insert any file name. To see what ++@var{initial} does, try the command @kbd{C-x C-v}. @strong{Please ++note:} we recommend using @var{default} rather than @var{initial} in ++most cases. ++ ++If @var{default} is non-@code{nil}, then the function returns ++@var{default} if the user exits the minibuffer with the same non-empty ++contents that @code{read-file-name} inserted initially. The initial ++minibuffer contents are always non-empty if ++@code{insert-default-directory} is non-@code{nil}, as it is by ++default. @var{default} is not checked for validity, regardless of the ++value of @var{require-match}. However, if @var{require-match} is ++non-@code{nil}, the initial minibuffer contents should be a valid file ++(or directory) name. Otherwise @code{read-file-name} attempts ++completion if the user exits without any editing, and does not return ++@var{default}. @var{default} is also available through the history ++commands. ++ ++If @var{default} is @code{nil}, @code{read-file-name} tries to find a ++substitute default to use in its place, which it treats in exactly the ++same way as if it had been specified explicitly. If @var{default} is ++@code{nil}, but @var{initial} is non-@code{nil}, then the default is ++the absolute file name obtained from @var{directory} and ++@var{initial}. If both @var{default} and @var{initial} are @code{nil} ++and the buffer is visiting a file, @code{read-file-name} uses the ++absolute file name of that file as default. If the buffer is not ++visiting a file, then there is no default. In that case, if the user ++types @key{RET} without any editing, @code{read-file-name} simply ++returns the pre-inserted contents of the minibuffer. ++ ++If the user types @key{RET} in an empty minibuffer, this function ++returns an empty string, regardless of the value of ++@var{require-match}. This is, for instance, how the user can make the ++current buffer visit no file using @code{M-x set-visited-file-name}. ++ ++If @var{predicate} is non-@code{nil}, it specifies a function of one ++argument that decides which file names are acceptable completion ++possibilities. A file name is an acceptable value if @var{predicate} ++returns non-@code{nil} for it. ++ ++@code{read-file-name} does not automatically expand file names. You ++must call @code{expand-file-name} yourself if an absolute file name is ++required. ++ ++Here is an example: ++ ++@example ++@group ++(read-file-name "The file is ") ++ ++;; @r{After evaluation of the preceding expression,} ++;; @r{the following appears in the minibuffer:} ++@end group ++ ++@group ++---------- Buffer: Minibuffer ---------- ++The file is /gp/gnu/elisp/@point{} ++---------- Buffer: Minibuffer ---------- ++@end group ++@end example ++ ++@noindent ++Typing @kbd{manual @key{TAB}} results in the following: ++ ++@example ++@group ++---------- Buffer: Minibuffer ---------- ++The file is /gp/gnu/elisp/manual.texi@point{} ++---------- Buffer: Minibuffer ---------- ++@end group ++@end example ++ ++@c Wordy to avoid overfull hbox in smallbook mode. ++@noindent ++If the user types @key{RET}, @code{read-file-name} returns the file name ++as the string @code{"/gp/gnu/elisp/manual.texi"}. ++@end defun ++ ++@defvar read-file-name-function ++If non-@code{nil}, this should be a function that accepts the same ++arguments as @code{read-file-name}. When @code{read-file-name} is ++called, it calls this function with the supplied arguments instead of ++doing its usual work. ++@end defvar ++ ++@defopt read-file-name-completion-ignore-case ++If this variable is non-@code{nil}, @code{read-file-name} ignores case ++when performing completion. ++@end defopt ++ ++@defun read-directory-name prompt &optional directory default require-match initial ++This function is like @code{read-file-name} but allows only directory ++names as completion possibilities. ++ ++If @var{default} is @code{nil} and @var{initial} is non-@code{nil}, ++@code{read-directory-name} constructs a substitute default by ++combining @var{directory} (or the current buffer's default directory ++if @var{directory} is @code{nil}) and @var{initial}. If both ++@var{default} and @var{initial} are @code{nil}, this function uses ++@var{directory} as substitute default, or the current buffer's default ++directory if @var{directory} is @code{nil}. ++@end defun ++ ++@defopt insert-default-directory ++This variable is used by @code{read-file-name}, and thus, indirectly, ++by most commands reading file names. (This includes all commands that ++use the code letters @samp{f} or @samp{F} in their interactive form. ++@xref{Interactive Codes,, Code Characters for interactive}.) Its ++value controls whether @code{read-file-name} starts by placing the ++name of the default directory in the minibuffer, plus the initial file ++name if any. If the value of this variable is @code{nil}, then ++@code{read-file-name} does not place any initial input in the ++minibuffer (unless you specify initial input with the @var{initial} ++argument). In that case, the default directory is still used for ++completion of relative file names, but is not displayed. ++ ++If this variable is @code{nil} and the initial minibuffer contents are ++empty, the user may have to explicitly fetch the next history element ++to access a default value. If the variable is non-@code{nil}, the ++initial minibuffer contents are always non-empty and the user can ++always request a default value by immediately typing @key{RET} in an ++unedited minibuffer. (See above.) ++ ++For example: ++ ++@example ++@group ++;; @r{Here the minibuffer starts out with the default directory.} ++(let ((insert-default-directory t)) ++ (read-file-name "The file is ")) ++@end group ++ ++@group ++---------- Buffer: Minibuffer ---------- ++The file is ~lewis/manual/@point{} ++---------- Buffer: Minibuffer ---------- ++@end group ++ ++@group ++;; @r{Here the minibuffer is empty and only the prompt} ++;; @r{appears on its line.} ++(let ((insert-default-directory nil)) ++ (read-file-name "The file is ")) ++@end group ++ ++@group ++---------- Buffer: Minibuffer ---------- ++The file is @point{} ++---------- Buffer: Minibuffer ---------- ++@end group ++@end example ++@end defopt ++ ++@defun read-shell-command prompt &optional initial-contents hist &rest args ++This function reads a shell command from the minibuffer, prompting ++with @var{prompt} and providing intelligent completion. It completes ++the first word of the command using candidates that are appropriate ++for command names, and the rest of the command words as file names. ++ ++This function uses @code{minibuffer-local-shell-command-map} as the ++keymap for minibuffer input. The @var{hist} argument specifies the ++history list to use; if is omitted or @code{nil}, it defaults to ++@code{shell-command-history} (@pxref{Minibuffer History, ++shell-command-history}). The optional argument @var{initial-contents} ++specifies the initial content of the minibuffer (@pxref{Initial ++Input}). The rest of @var{args}, if present, are used as the ++@var{default} and @var{inherit-input-method} arguments in ++@code{read-from-minibuffer} (@pxref{Text from Minibuffer}). ++@end defun ++ ++@defvar minibuffer-local-shell-command-map ++This keymap is used by @code{read-shell-command} for completing ++command and file names that are part of a shell command. ++@end defvar ++ ++@node Completion Styles ++@subsection Completion Styles ++@cindex completion styles ++ ++ A @dfn{completion style} is a set of rules for generating ++completions. The user option @code{completion-styles} stores a list ++of completion styles, which are represented by symbols. ++ ++@defopt completion-styles ++This is a list of completion style symbols to use for performing ++completion. Each completion style in this list must be defined in ++@code{completion-styles-alist}. ++@end defopt ++ ++@defvar completion-styles-alist ++This variable stores a list of available completion styles. Each ++element in the list must have the form @samp{(@var{name} ++@var{try-completion} @var{all-completions})}. Here, @var{name} is the ++name of the completion style (a symbol), which may be used in ++@code{completion-styles-alist} to refer to this style. ++ ++@var{try-completion} is the function that does the completion, and ++@var{all-completions} is the function that lists the completions. ++These functions should accept four arguments: @var{string}, ++@var{collection}, @var{predicate}, and @var{point}. The @var{string}, ++@var{collection}, and @var{predicate} arguments have the same meanings ++as in @code{try-completion} (@pxref{Basic Completion}), and the ++@var{point} argument is the position of point within @var{string}. ++Each function should return a non-@code{nil} value if it performed its ++job, and @code{nil} if it did not (e.g., if there is no way to ++complete @var{string} according to the completion style). ++ ++When the user calls a completion command, such as ++@code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks ++for the first style listed in @code{completion-styles} and calls its ++@var{try-completion} function. If this function returns @code{nil}, ++Emacs moves to the next completion style listed in ++@code{completion-styles} and calls its @var{try-completion} function, ++and so on until one of the @var{try-completion} functions successfully ++performs completion and returns a non-@code{nil} value. A similar ++procedure is used for listing completions, via the ++@var{all-completions} functions. ++@end defvar ++ ++ By default, @code{completion-styles-alist} contains four pre-defined ++completion styles: @code{basic}, a basic completion style; ++@code{partial-completion}, which does partial completion (completing ++each word in the input separately); @code{emacs22}, which performs ++completion according to the rules used in Emacs 22; and ++@code{emacs21}, which performs completion according to the rules used ++in Emacs 21. ++ ++@node Programmed Completion ++@subsection Programmed Completion ++@cindex programmed completion ++ ++ Sometimes it is not possible to create an alist or an obarray ++containing all the intended possible completions. In such a case, you ++can supply your own function to compute the completion of a given string. ++This is called @dfn{programmed completion}. ++ ++ To use this feature, pass a symbol with a function definition as the ++@var{collection} argument to @code{completing-read}. The function ++@code{completing-read} arranges to pass your completion function along ++to @code{try-completion} and @code{all-completions}, which will then let ++your function do all the work. ++ ++ The completion function should accept three arguments: ++ ++@itemize @bullet ++@item ++The string to be completed. ++ ++@item ++The predicate function to filter possible matches, or @code{nil} if ++none. Your function should call the predicate for each possible match, ++and ignore the possible match if the predicate returns @code{nil}. ++ ++@item ++A flag specifying the type of operation. ++@end itemize ++ ++ There are three flag values for three operations: ++ ++@itemize @bullet ++@item ++@code{nil} specifies @code{try-completion}. The completion function ++should return the completion of the specified string, or @code{t} if the ++string is a unique and exact match already, or @code{nil} if the string ++matches no possibility. ++ ++If the string is an exact match for one possibility, but also matches ++other longer possibilities, the function should return the string, not ++@code{t}. ++ ++@item ++@code{t} specifies @code{all-completions}. The completion function ++should return a list of all possible completions of the specified ++string. ++ ++@item ++@code{lambda} specifies @code{test-completion}. The completion ++function should return @code{t} if the specified string is an exact ++match for some possibility; @code{nil} otherwise. ++@end itemize ++ ++ It would be consistent and clean for completion functions to allow ++lambda expressions (lists that are functions) as well as function ++symbols as @var{collection}, but this is impossible. Lists as ++completion tables already have other meanings, and it would be ++unreliable to treat one differently just because it is also a possible ++function. So you must arrange for any function you wish to use for ++completion to be encapsulated in a symbol. ++ ++ Emacs uses programmed completion when completing file names. ++@xref{File Name Completion}. ++ ++@defun completion-table-dynamic function ++This function is a convenient way to write a function that can act as ++programmed completion function. The argument @var{function} should be ++a function that takes one argument, a string, and returns an alist of ++possible completions of it. You can think of ++@code{completion-table-dynamic} as a transducer between that interface ++and the interface for programmed completion functions. ++@end defun ++ ++@node Yes-or-No Queries ++@section Yes-or-No Queries ++@cindex asking the user questions ++@cindex querying the user ++@cindex yes-or-no questions ++ ++ This section describes functions used to ask the user a yes-or-no ++question. The function @code{y-or-n-p} can be answered with a single ++character; it is useful for questions where an inadvertent wrong answer ++will not have serious consequences. @code{yes-or-no-p} is suitable for ++more momentous questions, since it requires three or four characters to ++answer. ++ ++ If either of these functions is called in a command that was invoked ++using the mouse---more precisely, if @code{last-nonmenu-event} ++(@pxref{Command Loop Info}) is either @code{nil} or a list---then it ++uses a dialog box or pop-up menu to ask the question. Otherwise, it ++uses keyboard input. You can force use of the mouse or use of keyboard ++input by binding @code{last-nonmenu-event} to a suitable value around ++the call. ++ ++ Strictly speaking, @code{yes-or-no-p} uses the minibuffer and ++@code{y-or-n-p} does not; but it seems best to describe them together. ++ ++@defun y-or-n-p prompt ++This function asks the user a question, expecting input in the echo ++area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the ++user types @kbd{n}. This function also accepts @key{SPC} to mean yes ++and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit,'' like ++@kbd{C-g}, because the question might look like a minibuffer and for ++that reason the user might try to use @kbd{C-]} to get out. The answer ++is a single character, with no @key{RET} needed to terminate it. Upper ++and lower case are equivalent. ++ ++``Asking the question'' means printing @var{prompt} in the echo area, ++followed by the string @w{@samp{(y or n) }}. If the input is not one of ++the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}}, ++@kbd{@key{DEL}}, or something that quits), the function responds ++@samp{Please answer y or n.}, and repeats the request. ++ ++This function does not actually use the minibuffer, since it does not ++allow editing of the answer. It actually uses the echo area (@pxref{The ++Echo Area}), which uses the same screen space as the minibuffer. The ++cursor moves to the echo area while the question is being asked. ++ ++The answers and their meanings, even @samp{y} and @samp{n}, are not ++hardwired. The keymap @code{query-replace-map} specifies them. ++@xref{Search and Replace}. ++ ++In the following example, the user first types @kbd{q}, which is ++invalid. At the next prompt the user types @kbd{y}. ++ ++@smallexample ++@group ++(y-or-n-p "Do you need a lift? ") ++ ++;; @r{After evaluation of the preceding expression,} ++;; @r{the following prompt appears in the echo area:} ++@end group ++ ++@group ++---------- Echo area ---------- ++Do you need a lift? (y or n) ++---------- Echo area ---------- ++@end group ++ ++;; @r{If the user then types @kbd{q}, the following appears:} ++ ++@group ++---------- Echo area ---------- ++Please answer y or n. Do you need a lift? (y or n) ++---------- Echo area ---------- ++@end group ++ ++;; @r{When the user types a valid answer,} ++;; @r{it is displayed after the question:} ++ ++@group ++---------- Echo area ---------- ++Do you need a lift? (y or n) y ++---------- Echo area ---------- ++@end group ++@end smallexample ++ ++@noindent ++We show successive lines of echo area messages, but only one actually ++appears on the screen at a time. ++@end defun ++ ++@defun y-or-n-p-with-timeout prompt seconds default-value ++Like @code{y-or-n-p}, except that if the user fails to answer within ++@var{seconds} seconds, this function stops waiting and returns ++@var{default-value}. It works by setting up a timer; see @ref{Timers}. ++The argument @var{seconds} may be an integer or a floating point number. ++@end defun ++ ++@defun yes-or-no-p prompt ++This function asks the user a question, expecting input in the ++minibuffer. It returns @code{t} if the user enters @samp{yes}, ++@code{nil} if the user types @samp{no}. The user must type @key{RET} to ++finalize the response. Upper and lower case are equivalent. ++ ++@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area, ++followed by @w{@samp{(yes or no) }}. The user must type one of the ++expected responses; otherwise, the function responds @samp{Please answer ++yes or no.}, waits about two seconds and repeats the request. ++ ++@code{yes-or-no-p} requires more work from the user than ++@code{y-or-n-p} and is appropriate for more crucial decisions. ++ ++Here is an example: ++ ++@smallexample ++@group ++(yes-or-no-p "Do you really want to remove everything? ") ++ ++;; @r{After evaluation of the preceding expression,} ++;; @r{the following prompt appears,} ++;; @r{with an empty minibuffer:} ++@end group ++ ++@group ++---------- Buffer: minibuffer ---------- ++Do you really want to remove everything? (yes or no) ++---------- Buffer: minibuffer ---------- ++@end group ++@end smallexample ++ ++@noindent ++If the user first types @kbd{y @key{RET}}, which is invalid because this ++function demands the entire word @samp{yes}, it responds by displaying ++these prompts, with a brief pause between them: ++ ++@smallexample ++@group ++---------- Buffer: minibuffer ---------- ++Please answer yes or no. ++Do you really want to remove everything? (yes or no) ++---------- Buffer: minibuffer ---------- ++@end group ++@end smallexample ++@end defun ++ ++@node Multiple Queries ++@section Asking Multiple Y-or-N Questions ++ ++ When you have a series of similar questions to ask, such as ``Do you ++want to save this buffer'' for each buffer in turn, you should use ++@code{map-y-or-n-p} to ask the collection of questions, rather than ++asking each question individually. This gives the user certain ++convenient facilities such as the ability to answer the whole series at ++once. ++ ++@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area ++This function asks the user a series of questions, reading a ++single-character answer in the echo area for each one. ++ ++The value of @var{list} specifies the objects to ask questions about. ++It should be either a list of objects or a generator function. If it is ++a function, it should expect no arguments, and should return either the ++next object to ask about, or @code{nil} meaning stop asking questions. ++ ++The argument @var{prompter} specifies how to ask each question. If ++@var{prompter} is a string, the question text is computed like this: ++ ++@example ++(format @var{prompter} @var{object}) ++@end example ++ ++@noindent ++where @var{object} is the next object to ask about (as obtained from ++@var{list}). ++ ++If not a string, @var{prompter} should be a function of one argument ++(the next object to ask about) and should return the question text. If ++the value is a string, that is the question to ask the user. The ++function can also return @code{t} meaning do act on this object (and ++don't ask the user), or @code{nil} meaning ignore this object (and don't ++ask the user). ++ ++The argument @var{actor} says how to act on the answers that the user ++gives. It should be a function of one argument, and it is called with ++each object that the user says yes for. Its argument is always an ++object obtained from @var{list}. ++ ++If the argument @var{help} is given, it should be a list of this form: ++ ++@example ++(@var{singular} @var{plural} @var{action}) ++@end example ++ ++@noindent ++where @var{singular} is a string containing a singular noun that ++describes the objects conceptually being acted on, @var{plural} is the ++corresponding plural noun, and @var{action} is a transitive verb ++describing what @var{actor} does. ++ ++If you don't specify @var{help}, the default is @code{("object" ++"objects" "act on")}. ++ ++Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or ++@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip ++that object; @kbd{!} to act on all following objects; @key{ESC} or ++@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on ++the current object and then exit; or @kbd{C-h} to get help. These are ++the same answers that @code{query-replace} accepts. The keymap ++@code{query-replace-map} defines their meaning for @code{map-y-or-n-p} ++as well as for @code{query-replace}; see @ref{Search and Replace}. ++ ++You can use @var{action-alist} to specify additional possible answers ++and what they mean. It is an alist of elements of the form ++@code{(@var{char} @var{function} @var{help})}, each of which defines one ++additional answer. In this element, @var{char} is a character (the ++answer); @var{function} is a function of one argument (an object from ++@var{list}); @var{help} is a string. ++ ++When the user responds with @var{char}, @code{map-y-or-n-p} calls ++@var{function}. If it returns non-@code{nil}, the object is considered ++``acted upon,'' and @code{map-y-or-n-p} advances to the next object in ++@var{list}. If it returns @code{nil}, the prompt is repeated for the ++same object. ++ ++Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while ++prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it ++does not do that. ++ ++If @code{map-y-or-n-p} is called in a command that was invoked using the ++mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command ++Loop Info}) is either @code{nil} or a list---then it uses a dialog box ++or pop-up menu to ask the question. In this case, it does not use ++keyboard input or the echo area. You can force use of the mouse or use ++of keyboard input by binding @code{last-nonmenu-event} to a suitable ++value around the call. ++ ++The return value of @code{map-y-or-n-p} is the number of objects acted on. ++@end defun ++ ++@node Reading a Password ++@section Reading a Password ++@cindex passwords, reading ++ ++ To read a password to pass to another program, you can use the ++function @code{read-passwd}. ++ ++@defun read-passwd prompt &optional confirm default ++This function reads a password, prompting with @var{prompt}. It does ++not echo the password as the user types it; instead, it echoes @samp{.} ++for each character in the password. ++ ++The optional argument @var{confirm}, if non-@code{nil}, says to read the ++password twice and insist it must be the same both times. If it isn't ++the same, the user has to type it over and over until the last two ++times match. ++ ++The optional argument @var{default} specifies the default password to ++return if the user enters empty input. If @var{default} is @code{nil}, ++then @code{read-passwd} returns the null string in that case. ++@end defun ++ ++@node Minibuffer Commands ++@section Minibuffer Commands ++ ++ This section describes some commands meant for use in the ++minibuffer. ++ ++@deffn Command exit-minibuffer ++This command exits the active minibuffer. It is normally bound to ++keys in minibuffer local keymaps. ++@end deffn ++ ++@deffn Command self-insert-and-exit ++This command exits the active minibuffer after inserting the last ++character typed on the keyboard (found in @code{last-command-event}; ++@pxref{Command Loop Info}). ++@end deffn ++ ++@deffn Command previous-history-element n ++This command replaces the minibuffer contents with the value of the ++@var{n}th previous (older) history element. ++@end deffn ++ ++@deffn Command next-history-element n ++This command replaces the minibuffer contents with the value of the ++@var{n}th more recent history element. ++@end deffn ++ ++@deffn Command previous-matching-history-element pattern n ++This command replaces the minibuffer contents with the value of the ++@var{n}th previous (older) history element that matches @var{pattern} (a ++regular expression). ++@end deffn ++ ++@deffn Command next-matching-history-element pattern n ++This command replaces the minibuffer contents with the value of the ++@var{n}th next (newer) history element that matches @var{pattern} (a ++regular expression). ++@end deffn ++ ++@node Minibuffer Windows ++@section Minibuffer Windows ++@cindex minibuffer windows ++ ++ These functions access and select minibuffer windows ++and test whether they are active. ++ ++@defun active-minibuffer-window ++This function returns the currently active minibuffer window, or ++@code{nil} if none is currently active. ++@end defun ++ ++@defun minibuffer-window &optional frame ++@anchor{Definition of minibuffer-window} ++This function returns the minibuffer window used for frame @var{frame}. ++If @var{frame} is @code{nil}, that stands for the current frame. Note ++that the minibuffer window used by a frame need not be part of that ++frame---a frame that has no minibuffer of its own necessarily uses some ++other frame's minibuffer window. ++@end defun ++ ++@defun set-minibuffer-window window ++This function specifies @var{window} as the minibuffer window to use. ++This affects where the minibuffer is displayed if you put text in it ++without invoking the usual minibuffer commands. It has no effect on ++the usual minibuffer input functions because they all start by ++choosing the minibuffer window according to the current frame. ++@end defun ++ ++@c Emacs 19 feature ++@defun window-minibuffer-p &optional window ++This function returns non-@code{nil} if @var{window} is a minibuffer ++window. ++@var{window} defaults to the selected window. ++@end defun ++ ++It is not correct to determine whether a given window is a minibuffer by ++comparing it with the result of @code{(minibuffer-window)}, because ++there can be more than one minibuffer window if there is more than one ++frame. ++ ++@defun minibuffer-window-active-p window ++This function returns non-@code{nil} if @var{window}, assumed to be ++a minibuffer window, is currently active. ++@end defun ++ ++@node Minibuffer Contents ++@section Minibuffer Contents ++ ++ These functions access the minibuffer prompt and contents. ++ ++@defun minibuffer-prompt ++This function returns the prompt string of the currently active ++minibuffer. If no minibuffer is active, it returns @code{nil}. ++@end defun ++ ++@defun minibuffer-prompt-end ++This function returns the current ++position of the end of the minibuffer prompt, if a minibuffer is ++current. Otherwise, it returns the minimum valid buffer position. ++@end defun ++ ++@defun minibuffer-prompt-width ++This function returns the current display-width of the minibuffer ++prompt, if a minibuffer is current. Otherwise, it returns zero. ++@end defun ++ ++@defun minibuffer-contents ++This function returns the editable ++contents of the minibuffer (that is, everything except the prompt) as ++a string, if a minibuffer is current. Otherwise, it returns the ++entire contents of the current buffer. ++@end defun ++ ++@defun minibuffer-contents-no-properties ++This is like @code{minibuffer-contents}, except that it does not copy text ++properties, just the characters themselves. @xref{Text Properties}. ++@end defun ++ ++@defun minibuffer-completion-contents ++This is like @code{minibuffer-contents}, except that it returns only ++the contents before point. That is the part that completion commands ++operate on. @xref{Minibuffer Completion}. ++@end defun ++ ++@defun delete-minibuffer-contents ++This function erases the editable contents of the minibuffer (that is, ++everything except the prompt), if a minibuffer is current. Otherwise, ++it erases the entire current buffer. ++@end defun ++ ++@node Recursive Mini ++@section Recursive Minibuffers ++@cindex recursive minibuffers ++ ++ These functions and variables deal with recursive minibuffers ++(@pxref{Recursive Editing}): ++ ++@defun minibuffer-depth ++This function returns the current depth of activations of the ++minibuffer, a nonnegative integer. If no minibuffers are active, it ++returns zero. ++@end defun ++ ++@defopt enable-recursive-minibuffers ++If this variable is non-@code{nil}, you can invoke commands (such as ++@code{find-file}) that use minibuffers even while the minibuffer window ++is active. Such invocation produces a recursive editing level for a new ++minibuffer. The outer-level minibuffer is invisible while you are ++editing the inner one. ++ ++If this variable is @code{nil}, you cannot invoke minibuffer ++commands when the minibuffer window is active, not even if you switch to ++another window to do it. ++@end defopt ++ ++@c Emacs 19 feature ++If a command name has a property @code{enable-recursive-minibuffers} ++that is non-@code{nil}, then the command can use the minibuffer to read ++arguments even if it is invoked from the minibuffer. A command can ++also achieve this by binding @code{enable-recursive-minibuffers} ++to @code{t} in the interactive declaration (@pxref{Using Interactive}). ++The minibuffer command @code{next-matching-history-element} (normally ++@kbd{M-s} in the minibuffer) does the latter. ++ ++@node Minibuffer Misc ++@section Minibuffer Miscellany ++ ++@defun minibufferp &optional buffer-or-name ++This function returns non-@code{nil} if @var{buffer-or-name} is a ++minibuffer. If @var{buffer-or-name} is omitted, it tests the current ++buffer. ++@end defun ++ ++@defvar minibuffer-setup-hook ++This is a normal hook that is run whenever the minibuffer is entered. ++@xref{Hooks}. ++@end defvar ++ ++@defvar minibuffer-exit-hook ++This is a normal hook that is run whenever the minibuffer is exited. ++@xref{Hooks}. ++@end defvar ++ ++@defvar minibuffer-help-form ++@anchor{Definition of minibuffer-help-form} ++The current value of this variable is used to rebind @code{help-form} ++locally inside the minibuffer (@pxref{Help Functions}). ++@end defvar ++ ++@defvar minibuffer-scroll-window ++@anchor{Definition of minibuffer-scroll-window} ++If the value of this variable is non-@code{nil}, it should be a window ++object. When the function @code{scroll-other-window} is called in the ++minibuffer, it scrolls this window. ++@end defvar ++ ++@defun minibuffer-selected-window ++This function returns the window which was selected when the ++minibuffer was entered. If selected window is not a minibuffer ++window, it returns @code{nil}. ++@end defun ++ ++@defopt max-mini-window-height ++This variable specifies the maximum height for resizing minibuffer ++windows. If a float, it specifies a fraction of the height of the ++frame. If an integer, it specifies a number of lines. ++@end defopt ++ ++@defun minibuffer-message string &rest args ++This function displays @var{string} temporarily at the end of the ++minibuffer text, for two seconds, or until the next input event ++arrives, whichever comes first. If @var{args} is non-@code{nil}, the ++actual message is obtained by passing @var{string} and @var{args} ++through @code{format}. @xref{Formatting Strings}. ++@end defun ++ ++@ignore ++ arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218 ++@end ignore +diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi +new file mode 100644 +index 0000000..8313ef7 +--- /dev/null ++++ b/doc/lispref/modes.texi +@@ -0,0 +1,3287 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/modes ++@node Modes, Documentation, Keymaps, Top ++@chapter Major and Minor Modes ++@cindex mode ++ ++ A @dfn{mode} is a set of definitions that customize Emacs and can be ++turned on and off while you edit. There are two varieties of modes: ++@dfn{major modes}, which are mutually exclusive and used for editing ++particular kinds of text, and @dfn{minor modes}, which provide features ++that users can enable individually. ++ ++ This chapter describes how to write both major and minor modes, how to ++indicate them in the mode line, and how they run hooks supplied by the ++user. For related topics such as keymaps and syntax tables, see ++@ref{Keymaps}, and @ref{Syntax Tables}. ++ ++@menu ++* Hooks:: How to use hooks; how to write code that provides hooks. ++* Major Modes:: Defining major modes. ++* Minor Modes:: Defining minor modes. ++* Mode Line Format:: Customizing the text that appears in the mode line. ++* Imenu:: How a mode can provide a menu ++ of definitions in the buffer. ++* Font Lock Mode:: How modes can highlight text according to syntax. ++* Desktop Save Mode:: How modes can have buffer state saved between ++ Emacs sessions. ++@end menu ++ ++@node Hooks ++@section Hooks ++@cindex hooks ++ ++ A @dfn{hook} is a variable where you can store a function or functions ++to be called on a particular occasion by an existing program. Emacs ++provides hooks for the sake of customization. Most often, hooks are set ++up in the init file (@pxref{Init File}), but Lisp programs can set them also. ++@xref{Standard Hooks}, for a list of standard hook variables. ++ ++@cindex normal hook ++ Most of the hooks in Emacs are @dfn{normal hooks}. These variables ++contain lists of functions to be called with no arguments. By ++convention, whenever the hook name ends in @samp{-hook}, that tells ++you it is normal. We try to make all hooks normal, as much as ++possible, so that you can use them in a uniform way. ++ ++ Every major mode function is supposed to run a normal hook called ++the @dfn{mode hook} as the one of the last steps of initialization. ++This makes it easy for a user to customize the behavior of the mode, ++by overriding the buffer-local variable assignments already made by ++the mode. Most minor mode functions also run a mode hook at the end. ++But hooks are used in other contexts too. For example, the hook ++@code{suspend-hook} runs just before Emacs suspends itself ++(@pxref{Suspending Emacs}). ++ ++ The recommended way to add a hook function to a normal hook is by ++calling @code{add-hook} (see below). The hook functions may be any of ++the valid kinds of functions that @code{funcall} accepts (@pxref{What ++Is a Function}). Most normal hook variables are initially void; ++@code{add-hook} knows how to deal with this. You can add hooks either ++globally or buffer-locally with @code{add-hook}. ++ ++@cindex abnormal hook ++ If the hook variable's name does not end with @samp{-hook}, that ++indicates it is probably an @dfn{abnormal hook}. That means the hook ++functions are called with arguments, or their return values are used ++in some way. The hook's documentation says how the functions are ++called. You can use @code{add-hook} to add a function to an abnormal ++hook, but you must write the function to follow the hook's calling ++convention. ++ ++ By convention, abnormal hook names end in @samp{-functions} or ++@samp{-hooks}. If the variable's name ends in @samp{-function}, then ++its value is just a single function, not a list of functions. ++ ++@menu ++* Running Hooks:: How to run a hook. ++* Setting Hooks:: How to put functions on a hook, or remove them. ++@end menu ++ ++@node Running Hooks ++@subsection Running Hooks ++ ++ At the appropriate times, Emacs uses the @code{run-hooks} function ++and the other functions below to run particular hooks. ++ ++@defun run-hooks &rest hookvars ++This function takes one or more normal hook variable names as ++arguments, and runs each hook in turn. Each argument should be a ++symbol that is a normal hook variable. These arguments are processed ++in the order specified. ++ ++If a hook variable has a non-@code{nil} value, that value should be a ++list of functions. @code{run-hooks} calls all the functions, one by ++one, with no arguments. ++ ++The hook variable's value can also be a single function---either a ++lambda expression or a symbol with a function definition---which ++@code{run-hooks} calls. But this usage is obsolete. ++@end defun ++ ++@defun run-hook-with-args hook &rest args ++This function is the way to run an abnormal hook and always call all ++of the hook functions. It calls each of the hook functions one by ++one, passing each of them the arguments @var{args}. ++@end defun ++ ++@defun run-hook-with-args-until-failure hook &rest args ++This function is the way to run an abnormal hook until one of the hook ++functions fails. It calls each of the hook functions, passing each of ++them the arguments @var{args}, until some hook function returns ++@code{nil}. It then stops and returns @code{nil}. If none of the ++hook functions return @code{nil}, it returns a non-@code{nil} value. ++@end defun ++ ++@defun run-hook-with-args-until-success hook &rest args ++This function is the way to run an abnormal hook until a hook function ++succeeds. It calls each of the hook functions, passing each of them ++the arguments @var{args}, until some hook function returns ++non-@code{nil}. Then it stops, and returns whatever was returned by ++the last hook function that was called. If all hook functions return ++@code{nil}, it returns @code{nil} as well. ++@end defun ++ ++@node Setting Hooks ++@subsection Setting Hooks ++ ++ Here's an example that uses a mode hook to turn on Auto Fill mode when ++in Lisp Interaction mode: ++ ++@example ++(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) ++@end example ++ ++@defun add-hook hook function &optional append local ++This function is the handy way to add function @var{function} to hook ++variable @var{hook}. You can use it for abnormal hooks as well as for ++normal hooks. @var{function} can be any Lisp function that can accept ++the proper number of arguments for @var{hook}. For example, ++ ++@example ++(add-hook 'text-mode-hook 'my-text-hook-function) ++@end example ++ ++@noindent ++adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. ++ ++If @var{function} is already present in @var{hook} (comparing using ++@code{equal}), then @code{add-hook} does not add it a second time. ++ ++If @var{function} has a non-@code{nil} property ++@code{permanent-local-hook}, then @code{kill-all-local-variables} (or ++changing major modes) won't delete it from the hook variable's local ++value. ++ ++It is best to design your hook functions so that the order in which ++they are executed does not matter. Any dependence on the order is ++asking for trouble. However, the order is predictable: normally, ++@var{function} goes at the front of the hook list, so it will be ++executed first (barring another @code{add-hook} call). If the ++optional argument @var{append} is non-@code{nil}, the new hook ++function goes at the end of the hook list and will be executed last. ++ ++@code{add-hook} can handle the cases where @var{hook} is void or its ++value is a single function; it sets or changes the value to a list of ++functions. ++ ++If @var{local} is non-@code{nil}, that says to add @var{function} to ++the buffer-local hook list instead of to the global hook list. If ++needed, this makes the hook buffer-local and adds @code{t} to the ++buffer-local value. The latter acts as a flag to run the hook ++functions in the default value as well as in the local value. ++@end defun ++ ++@defun remove-hook hook function &optional local ++This function removes @var{function} from the hook variable ++@var{hook}. It compares @var{function} with elements of @var{hook} ++using @code{equal}, so it works for both symbols and lambda ++expressions. ++ ++If @var{local} is non-@code{nil}, that says to remove @var{function} ++from the buffer-local hook list instead of from the global hook list. ++@end defun ++ ++@node Major Modes ++@section Major Modes ++@cindex major mode ++ ++ Major modes specialize Emacs for editing particular kinds of text. ++Each buffer has only one major mode at a time. For each major mode ++there is a function to switch to that mode in the current buffer; its ++name should end in @samp{-mode}. These functions work by setting ++buffer-local variable bindings and other data associated with the ++buffer, such as a local keymap. The effect lasts until you switch ++to another major mode in the same buffer. ++ ++@menu ++* Major Mode Basics:: ++* Major Mode Conventions:: Coding conventions for keymaps, etc. ++* Auto Major Mode:: How Emacs chooses the major mode automatically. ++* Mode Help:: Finding out how to use a mode. ++* Derived Modes:: Defining a new major mode based on another major ++ mode. ++* Generic Modes:: Defining a simple major mode that supports ++ comment syntax and Font Lock mode. ++* Mode Hooks:: Hooks run at the end of major mode functions. ++* Example Major Modes:: Text mode and Lisp modes. ++@end menu ++ ++@node Major Mode Basics ++@subsection Major Mode Basics ++@cindex Fundamental mode ++ ++ The least specialized major mode is called @dfn{Fundamental mode}. ++This mode has no mode-specific definitions or variable settings, so each ++Emacs command behaves in its default manner, and each option is in its ++default state. All other major modes redefine various keys and options. ++For example, Lisp Interaction mode provides special key bindings for ++@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB} ++(@code{lisp-indent-line}), and other keys. ++ ++ When you need to write several editing commands to help you perform a ++specialized editing task, creating a new major mode is usually a good ++idea. In practice, writing a major mode is easy (in contrast to ++writing a minor mode, which is often difficult). ++ ++ If the new mode is similar to an old one, it is often unwise to ++modify the old one to serve two purposes, since it may become harder ++to use and maintain. Instead, copy and rename an existing major mode ++definition and alter the copy---or use the @code{define-derived-mode} ++macro to define a @dfn{derived mode} (@pxref{Derived Modes}). For ++example, Rmail Edit mode is a major mode that is very similar to Text ++mode except that it provides two additional commands. Its definition ++is distinct from that of Text mode, but uses that of Text mode. ++ ++ Even if the new mode is not an obvious derivative of any other mode, ++it is convenient to use @code{define-derived-mode} with a @code{nil} ++parent argument, since it automatically enforces the most important ++coding conventions for you. ++ ++ For a very simple programming language major mode that handles ++comments and fontification, you can use @code{define-generic-mode}. ++@xref{Generic Modes}. ++ ++ Rmail Edit mode offers an example of changing the major mode ++temporarily for a buffer, so it can be edited in a different way (with ++ordinary Emacs commands rather than Rmail commands). In such cases, the ++temporary major mode usually provides a command to switch back to the ++buffer's usual mode (Rmail mode, in this case). You might be tempted to ++present the temporary redefinitions inside a recursive edit and restore ++the usual ones when the user exits; but this is a bad idea because it ++constrains the user's options when it is done in more than one buffer: ++recursive edits must be exited most-recently-entered first. Using an ++alternative major mode avoids this limitation. @xref{Recursive ++Editing}. ++ ++ The standard GNU Emacs Lisp library directory tree contains the code ++for several major modes, in files such as @file{text-mode.el}, ++@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and ++@file{rmail.el}. They are found in various subdirectories of the ++@file{lisp} directory. You can study these libraries to see how modes ++are written. Text mode is perhaps the simplest major mode aside from ++Fundamental mode. Rmail mode is a complicated and specialized mode. ++ ++@node Major Mode Conventions ++@subsection Major Mode Conventions ++@cindex major mode conventions ++@cindex conventions for writing major modes ++ ++ The code for existing major modes follows various coding conventions, ++including conventions for local keymap and syntax table initialization, ++global names, and hooks. Please follow these conventions when you ++define a new major mode. (Fundamental mode is an exception to many ++of these conventions, because its definition is to present the global ++state of Emacs.) ++ ++ This list of conventions is only partial, because each major mode ++should aim for consistency in general with other Emacs major modes. ++This makes Emacs as a whole more coherent. It is impossible to list ++here all the possible points where this issue might come up; if the ++Emacs developers point out an area where your major mode deviates from ++the usual conventions, please make it compatible. ++ ++@itemize @bullet ++@item ++Define a command whose name ends in @samp{-mode}, with no arguments, ++that switches to the new mode in the current buffer. This command ++should set up the keymap, syntax table, and buffer-local variables in an ++existing buffer, without changing the buffer's contents. ++ ++@item ++Write a documentation string for this command that describes the ++special commands available in this mode. @kbd{C-h m} ++(@code{describe-mode}) in your mode will display this string. ++ ++The documentation string may include the special documentation ++substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and ++@samp{\<@var{keymap}>}, which enable the documentation to adapt ++automatically to the user's own key bindings. @xref{Keys in ++Documentation}. ++ ++@item ++The major mode command should start by calling ++@code{kill-all-local-variables}. This runs the normal hook ++@code{change-major-mode-hook}, then gets rid of the buffer-local ++variables of the major mode previously in effect. @xref{Creating ++Buffer-Local}. ++ ++@item ++The major mode command should set the variable @code{major-mode} to the ++major mode command symbol. This is how @code{describe-mode} discovers ++which documentation to print. ++ ++@item ++The major mode command should set the variable @code{mode-name} to the ++``pretty'' name of the mode, usually a string (but see @ref{Mode Line ++Data}, for other possible forms). The name of the mode appears ++in the mode line. ++ ++@item ++@cindex functions in modes ++Since all global names are in the same name space, all the global ++variables, constants, and functions that are part of the mode should ++have names that start with the major mode name (or with an abbreviation ++of it if the name is long). @xref{Coding Conventions}. ++ ++@item ++In a major mode for editing some kind of structured text, such as a ++programming language, indentation of text according to structure is ++probably useful. So the mode should set @code{indent-line-function} ++to a suitable function, and probably customize other variables ++for indentation. ++ ++@item ++@cindex keymaps in modes ++The major mode should usually have its own keymap, which is used as the ++local keymap in all buffers in that mode. The major mode command should ++call @code{use-local-map} to install this local map. @xref{Active ++Keymaps}, for more information. ++ ++This keymap should be stored permanently in a global variable named ++@code{@var{modename}-mode-map}. Normally the library that defines the ++mode sets this variable. ++ ++@xref{Tips for Defining}, for advice about how to write the code to set ++up the mode's keymap variable. ++ ++@item ++The key sequences bound in a major mode keymap should usually start with ++@kbd{C-c}, followed by a control character, a digit, or @kbd{@{}, ++@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation ++characters are reserved for minor modes, and ordinary letters are ++reserved for users. ++ ++A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and ++@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally ++be some kind of ``moving forward and backward,'' but this does not ++necessarily mean cursor motion. ++ ++It is legitimate for a major mode to rebind a standard key sequence if ++it provides a command that does ``the same job'' in a way better ++suited to the text this mode is used for. For example, a major mode ++for editing a programming language might redefine @kbd{C-M-a} to ++``move to the beginning of a function'' in a way that works better for ++that language. ++ ++It is also legitimate for a major mode to rebind a standard key ++sequence whose standard meaning is rarely useful in that mode. For ++instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is ++rarely of any use in the minibuffer. Major modes such as Dired or ++Rmail that do not allow self-insertion of text can reasonably redefine ++letters and other printing characters as special commands. ++ ++@item ++Major modes for editing text should not define @key{RET} to do ++anything other than insert a newline. However, it is ok for ++specialized modes for text that users don't directly edit, such as ++Dired and Info modes, to redefine @key{RET} to do something entirely ++different. ++ ++@item ++Major modes should not alter options that are primarily a matter of user ++preference, such as whether Auto-Fill mode is enabled. Leave this to ++each user to decide. However, a major mode should customize other ++variables so that Auto-Fill mode will work usefully @emph{if} the user ++decides to use it. ++ ++@item ++@cindex syntax tables in modes ++The mode may have its own syntax table or may share one with other ++related modes. If it has its own syntax table, it should store this in ++a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax ++Tables}. ++ ++@item ++If the mode handles a language that has a syntax for comments, it should ++set the variables that define the comment syntax. @xref{Options for ++Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}. ++ ++@item ++@cindex abbrev tables in modes ++The mode may have its own abbrev table or may share one with other ++related modes. If it has its own abbrev table, it should store this ++in a variable named @code{@var{modename}-mode-abbrev-table}. If the ++major mode command defines any abbrevs itself, it should pass @code{t} ++for the @var{system-flag} argument to @code{define-abbrev}. ++@xref{Defining Abbrevs}. ++ ++@item ++The mode should specify how to do highlighting for Font Lock mode, by ++setting up a buffer-local value for the variable ++@code{font-lock-defaults} (@pxref{Font Lock Mode}). ++ ++@item ++The mode should specify how Imenu should find the definitions or ++sections of a buffer, by setting up a buffer-local value for the ++variable @code{imenu-generic-expression}, for the two variables ++@code{imenu-prev-index-position-function} and ++@code{imenu-extract-index-name-function}, or for the variable ++@code{imenu-create-index-function} (@pxref{Imenu}). ++ ++@item ++The mode can specify a local value for ++@code{eldoc-documentation-function} to tell ElDoc mode how to handle ++this mode. ++ ++@item ++Use @code{defvar} or @code{defcustom} to set mode-related variables, so ++that they are not reinitialized if they already have a value. (Such ++reinitialization could discard customizations made by the user.) ++ ++@item ++@cindex buffer-local variables in modes ++To make a buffer-local binding for an Emacs customization variable, use ++@code{make-local-variable} in the major mode command, not ++@code{make-variable-buffer-local}. The latter function would make the ++variable local to every buffer in which it is subsequently set, which ++would affect buffers that do not use this mode. It is undesirable for a ++mode to have such global effects. @xref{Buffer-Local Variables}. ++ ++With rare exceptions, the only reasonable way to use ++@code{make-variable-buffer-local} in a Lisp package is for a variable ++which is used only within that package. Using it on a variable used by ++other packages would interfere with them. ++ ++@item ++@cindex mode hook ++@cindex major mode hook ++Each major mode should have a normal @dfn{mode hook} named ++@code{@var{modename}-mode-hook}. The very last thing the major mode command ++should do is to call @code{run-mode-hooks}. This runs the mode hook, ++and then runs the normal hook @code{after-change-major-mode-hook}. ++@xref{Mode Hooks}. ++ ++@item ++The major mode command may start by calling some other major mode ++command (called the @dfn{parent mode}) and then alter some of its ++settings. A mode that does this is called a @dfn{derived mode}. The ++recommended way to define one is to use the @code{define-derived-mode} ++macro, but this is not required. Such a mode should call the parent ++mode command inside a @code{delay-mode-hooks} form. (Using ++@code{define-derived-mode} does this automatically.) @xref{Derived ++Modes}, and @ref{Mode Hooks}. ++ ++@item ++If something special should be done if the user switches a buffer from ++this mode to any other major mode, this mode can set up a buffer-local ++value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}). ++ ++@item ++If this mode is appropriate only for specially-prepared text, then the ++major mode command symbol should have a property named @code{mode-class} ++with value @code{special}, put on as follows: ++ ++@kindex mode-class @r{(property)} ++@cindex @code{special} ++@example ++(put 'funny-mode 'mode-class 'special) ++@end example ++ ++@noindent ++This tells Emacs that new buffers created while the current buffer is ++in Funny mode should not inherit Funny mode, in case ++@code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail, ++and Buffer List use this feature. ++ ++The @code{define-derived-mode} macro automatically marks the derived ++mode as special if the parent mode is special. The special mode ++@code{special-mode} provides a convenient parent for other special ++modes to inherit from; it sets @code{buffer-read-only} to @code{t}, ++and does nothing else. ++ ++@item ++If you want to make the new mode the default for files with certain ++recognizable names, add an element to @code{auto-mode-alist} to select ++the mode for those file names (@pxref{Auto Major Mode}). If you ++define the mode command to autoload, you should add this element in ++the same file that calls @code{autoload}. If you use an autoload ++cookie for the mode command, you can also use an autoload cookie for ++the form that adds the element (@pxref{autoload cookie}). If you do ++not autoload the mode command, it is sufficient to add the element in ++the file that contains the mode definition. ++ ++@item ++In the comments that document the file, you should provide a sample ++@code{autoload} form and an example of how to add to ++@code{auto-mode-alist}, that users can include in their init files ++(@pxref{Init File}). ++ ++@item ++@cindex mode loading ++The top-level forms in the file defining the mode should be written so ++that they may be evaluated more than once without adverse consequences. ++Even if you never load the file more than once, someone else will. ++@end itemize ++ ++@node Auto Major Mode ++@subsection How Emacs Chooses a Major Mode ++@cindex major mode, automatic selection ++ ++ Based on information in the file name or in the file itself, Emacs ++automatically selects a major mode for the new buffer when a file is ++visited. It also processes local variables specified in the file text. ++ ++@deffn Command fundamental-mode ++ Fundamental mode is a major mode that is not specialized for anything ++in particular. Other major modes are defined in effect by comparison ++with this one---their definitions say what to change, starting from ++Fundamental mode. The @code{fundamental-mode} function does @emph{not} ++run any mode hooks; you're not supposed to customize it. (If you want Emacs ++to behave differently in Fundamental mode, change the @emph{global} ++state of Emacs.) ++@end deffn ++ ++@deffn Command normal-mode &optional find-file ++This function establishes the proper major mode and buffer-local variable ++bindings for the current buffer. First it calls @code{set-auto-mode} ++(see below), then it runs @code{hack-local-variables} to parse, and ++bind or evaluate as appropriate, the file's local variables ++(@pxref{File Local Variables}). ++ ++If the @var{find-file} argument to @code{normal-mode} is non-@code{nil}, ++@code{normal-mode} assumes that the @code{find-file} function is calling ++it. In this case, it may process local variables in the @samp{-*-} ++line or at the end of the file. The variable ++@code{enable-local-variables} controls whether to do so. @xref{File ++Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, ++for the syntax of the local variables section of a file. ++ ++If you run @code{normal-mode} interactively, the argument ++@var{find-file} is normally @code{nil}. In this case, ++@code{normal-mode} unconditionally processes any file local variables. ++ ++If @code{normal-mode} processes the local variables list and this list ++specifies a major mode, that mode overrides any mode chosen by ++@code{set-auto-mode}. If neither @code{set-auto-mode} nor ++@code{hack-local-variables} specify a major mode, the buffer stays in ++the major mode determined by @code{default-major-mode} (see below). ++ ++@cindex file mode specification error ++@code{normal-mode} uses @code{condition-case} around the call to the ++major mode function, so errors are caught and reported as a @samp{File ++mode specification error}, followed by the original error message. ++@end deffn ++ ++@defun set-auto-mode &optional keep-mode-if-same ++@cindex visited file mode ++ This function selects the major mode that is appropriate for the ++current buffer. It bases its decision (in order of precedence) on ++the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using ++@code{interpreter-mode-alist}), on the text at the beginning of the ++buffer (using @code{magic-mode-alist}), and finally on the visited ++file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How ++Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this ++function does not look for the @samp{mode:} local variable near the ++end of a file; the @code{hack-local-variables} function does that. ++If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode} ++does not check the @w{@samp{-*-}} line for a mode tag either. ++ ++If @var{keep-mode-if-same} is non-@code{nil}, this function does not ++call the mode command if the buffer is already in the proper major ++mode. For instance, @code{set-visited-file-name} sets this to ++@code{t} to avoid killing buffer local variables that the user may ++have set. ++@end defun ++ ++@defopt default-major-mode ++This variable holds the default major mode for new buffers. The ++standard value is @code{fundamental-mode}. ++ ++If the value of @code{default-major-mode} is @code{nil}, Emacs uses ++the (previously) current buffer's major mode as the default major mode ++of a new buffer. However, if that major mode symbol has a @code{mode-class} ++property with value @code{special}, then it is not used for new buffers; ++Fundamental mode is used instead. The modes that have this property are ++those such as Dired and Rmail that are useful only with text that has ++been specially prepared. ++@end defopt ++ ++@defun set-buffer-major-mode buffer ++This function sets the major mode of @var{buffer} to the value of ++@code{default-major-mode}; if that variable is @code{nil}, it uses the ++current buffer's major mode (if that is suitable). As an exception, ++if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to ++@code{initial-major-mode}. ++ ++The low-level primitives for creating buffers do not use this function, ++but medium-level commands such as @code{switch-to-buffer} and ++@code{find-file-noselect} use it whenever they create buffers. ++@end defun ++ ++@defopt initial-major-mode ++@cindex @samp{*scratch*} ++The value of this variable determines the major mode of the initial ++@samp{*scratch*} buffer. The value should be a symbol that is a major ++mode command. The default value is @code{lisp-interaction-mode}. ++@end defopt ++ ++@defvar interpreter-mode-alist ++This variable specifies major modes to use for scripts that specify a ++command interpreter in a @samp{#!} line. Its value is an alist with ++elements of the form @code{(@var{interpreter} . @var{mode})}; for ++example, @code{("perl" . perl-mode)} is one element present by ++default. The element says to use mode @var{mode} if the file ++specifies an interpreter which matches @var{interpreter}. ++@end defvar ++ ++@defvar magic-mode-alist ++This variable's value is an alist with elements of the form ++@code{(@var{regexp} . @var{function})}, where @var{regexp} is a ++regular expression and @var{function} is a function or @code{nil}. ++After visiting a file, @code{set-auto-mode} calls @var{function} if ++the text at the beginning of the buffer matches @var{regexp} and ++@var{function} is non-@code{nil}; if @var{function} is @code{nil}, ++@code{auto-mode-alist} gets to decide the mode. ++@end defvar ++ ++@defvar magic-fallback-mode-alist ++This works like @code{magic-mode-alist}, except that it is handled ++only if @code{auto-mode-alist} does not specify a mode for this file. ++@end defvar ++ ++@defvar auto-mode-alist ++This variable contains an association list of file name patterns ++(regular expressions) and corresponding major mode commands. Usually, ++the file name patterns test for suffixes, such as @samp{.el} and ++@samp{.c}, but this need not be the case. An ordinary element of the ++alist looks like @code{(@var{regexp} . @var{mode-function})}. ++ ++For example, ++ ++@smallexample ++@group ++(("\\`/tmp/fol/" . text-mode) ++ ("\\.texinfo\\'" . texinfo-mode) ++ ("\\.texi\\'" . texinfo-mode) ++@end group ++@group ++ ("\\.el\\'" . emacs-lisp-mode) ++ ("\\.c\\'" . c-mode) ++ ("\\.h\\'" . c-mode) ++ @dots{}) ++@end group ++@end smallexample ++ ++When you visit a file whose expanded file name (@pxref{File Name ++Expansion}), with version numbers and backup suffixes removed using ++@code{file-name-sans-versions} (@pxref{File Name Components}), matches ++a @var{regexp}, @code{set-auto-mode} calls the corresponding ++@var{mode-function}. This feature enables Emacs to select the proper ++major mode for most files. ++ ++If an element of @code{auto-mode-alist} has the form @code{(@var{regexp} ++@var{function} t)}, then after calling @var{function}, Emacs searches ++@code{auto-mode-alist} again for a match against the portion of the file ++name that did not match before. This feature is useful for ++uncompression packages: an entry of the form @code{("\\.gz\\'" ++@var{function} t)} can uncompress the file and then put the uncompressed ++file in the proper mode according to the name sans @samp{.gz}. ++ ++Here is an example of how to prepend several pattern pairs to ++@code{auto-mode-alist}. (You might use this sort of expression in your ++init file.) ++ ++@smallexample ++@group ++(setq auto-mode-alist ++ (append ++ ;; @r{File name (within directory) starts with a dot.} ++ '(("/\\.[^/]*\\'" . fundamental-mode) ++ ;; @r{File name has no dot.} ++ ("/[^\\./]*\\'" . fundamental-mode) ++ ;; @r{File name ends in @samp{.C}.} ++ ("\\.C\\'" . c++-mode)) ++ auto-mode-alist)) ++@end group ++@end smallexample ++@end defvar ++ ++@node Mode Help ++@subsection Getting Help about a Major Mode ++@cindex mode help ++@cindex help for major mode ++@cindex documentation for major mode ++ ++ The @code{describe-mode} function is used to provide information ++about major modes. It is normally called with @kbd{C-h m}. The ++@code{describe-mode} function uses the value of @code{major-mode}, ++which is why every major mode function needs to set the ++@code{major-mode} variable. ++ ++@deffn Command describe-mode ++This function displays the documentation of the current major mode. ++ ++The @code{describe-mode} function calls the @code{documentation} ++function using the value of @code{major-mode} as an argument. Thus, it ++displays the documentation string of the major mode function. ++(@xref{Accessing Documentation}.) ++@end deffn ++ ++@defvar major-mode ++This buffer-local variable holds the symbol for the current buffer's ++major mode. This symbol should have a function definition that is the ++command to switch to that major mode. The @code{describe-mode} ++function uses the documentation string of the function as the ++documentation of the major mode. ++@end defvar ++ ++@node Derived Modes ++@subsection Defining Derived Modes ++@cindex derived mode ++ ++ It's often useful to define a new major mode in terms of an existing ++one. An easy way to do this is to use @code{define-derived-mode}. ++ ++@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{} ++This macro defines @var{variant} as a major mode command, using ++@var{name} as the string form of the mode name. @var{variant} and ++@var{parent} should be unquoted symbols. ++ ++The new command @var{variant} is defined to call the function ++@var{parent}, then override certain aspects of that parent mode: ++ ++@itemize @bullet ++@item ++The new mode has its own sparse keymap, named ++@code{@var{variant}-map}. @code{define-derived-mode} ++makes the parent mode's keymap the parent of the new map, unless ++@code{@var{variant}-map} is already set and already has a parent. ++ ++@item ++The new mode has its own syntax table, kept in the variable ++@code{@var{variant}-syntax-table}, unless you override this using the ++@code{:syntax-table} keyword (see below). @code{define-derived-mode} ++makes the parent mode's syntax-table the parent of ++@code{@var{variant}-syntax-table}, unless the latter is already set ++and already has a parent different from the standard syntax table. ++ ++@item ++The new mode has its own abbrev table, kept in the variable ++@code{@var{variant}-abbrev-table}, unless you override this using the ++@code{:abbrev-table} keyword (see below). ++ ++@item ++The new mode has its own mode hook, @code{@var{variant}-hook}. It ++runs this hook, after running the hooks of its ancestor modes, with ++@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. ++@end itemize ++ ++In addition, you can specify how to override other aspects of ++@var{parent} with @var{body}. The command @var{variant} ++evaluates the forms in @var{body} after setting up all its usual ++overrides, just before running the mode hooks. ++ ++If @var{parent} has a non-@code{nil} @code{mode-class} symbol ++property, then @code{define-derived-mode} sets the @code{mode-class} ++property of @var{variant} to the same value. This ensures, for ++example, that if @var{parent} is a special mode, then @var{variant} is ++also a special mode (@pxref{Major Mode Conventions}). ++ ++You can also specify @code{nil} for @var{parent}. This gives the new ++mode no parent. Then @code{define-derived-mode} behaves as described ++above, but, of course, omits all actions connected with @var{parent}. ++ ++The argument @var{docstring} specifies the documentation string for ++the new mode. @code{define-derived-mode} adds some general ++information about the mode's hook, followed by the mode's keymap, at ++the end of this docstring. If you omit @var{docstring}, ++@code{define-derived-mode} generates a documentation string. ++ ++The @var{keyword-args} are pairs of keywords and values. The values ++are evaluated. The following keywords are currently supported: ++ ++@table @code ++@item :syntax-table ++You can use this to explicitly specify a syntax table for the new ++mode. If you specify a @code{nil} value, the new mode uses the same ++syntax table as @var{parent}, or the standard syntax table if ++@var{parent} is @code{nil}. (Note that this does @emph{not} follow ++the convention used for non-keyword arguments that a @code{nil} value ++is equivalent with not specifying the argument.) ++ ++@item :abbrev-table ++You can use this to explicitly specify an abbrev table for the new ++mode. If you specify a @code{nil} value, the new mode uses the same ++abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} ++if @var{parent} is @code{nil}. (Again, a @code{nil} value is ++@emph{not} equivalent to not specifying this keyword.) ++ ++@item :group ++If this is specified, the value should be the customization group for ++this mode. (Not all major modes have one.) Only the (still ++experimental and unadvertised) command @code{customize-mode} currently ++uses this. @code{define-derived-mode} does @emph{not} automatically ++define the specified customization group. ++@end table ++ ++Here is a hypothetical example: ++ ++@example ++(define-derived-mode hypertext-mode ++ text-mode "Hypertext" ++ "Major mode for hypertext. ++\\@{hypertext-mode-map@}" ++ (setq case-fold-search nil)) ++ ++(define-key hypertext-mode-map ++ [down-mouse-3] 'do-hyper-link) ++@end example ++ ++Do not write an @code{interactive} spec in the definition; ++@code{define-derived-mode} does that automatically. ++@end defmac ++ ++@node Generic Modes ++@subsection Generic Modes ++@cindex generic mode ++ ++ @dfn{Generic modes} are simple major modes with basic support for ++comment syntax and Font Lock mode. To define a generic mode, use the ++macro @code{define-generic-mode}. See the file @file{generic-x.el} ++for some examples of the use of @code{define-generic-mode}. ++ ++@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring ++This macro defines a generic mode command named @var{mode} (a symbol, ++not quoted). The optional argument @var{docstring} is the ++documentation for the mode command. If you do not supply it, ++@code{define-generic-mode} generates one by default. ++ ++The argument @var{comment-list} is a list in which each element is ++either a character, a string of one or two characters, or a cons cell. ++A character or a string is set up in the mode's syntax table as a ++``comment starter.'' If the entry is a cons cell, the @sc{car} is set ++up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.'' ++(Use @code{nil} for the latter if you want comments to end at the end ++of the line.) Note that the syntax table mechanism has limitations ++about what comment starters and enders are actually possible. ++@xref{Syntax Tables}. ++ ++The argument @var{keyword-list} is a list of keywords to highlight ++with @code{font-lock-keyword-face}. Each keyword should be a string. ++Meanwhile, @var{font-lock-list} is a list of additional expressions to ++highlight. Each element of this list should have the same form as an ++element of @code{font-lock-keywords}. @xref{Search-based ++Fontification}. ++ ++The argument @var{auto-mode-list} is a list of regular expressions to ++add to the variable @code{auto-mode-alist}. They are added by the execution ++of the @code{define-generic-mode} form, not by expanding the macro call. ++ ++Finally, @var{function-list} is a list of functions for the mode ++command to call for additional setup. It calls these functions just ++before it runs the mode hook variable @code{@var{mode}-hook}. ++@end defmac ++ ++@node Mode Hooks ++@subsection Mode Hooks ++ ++ Every major mode function should finish by running its mode hook and ++the mode-independent normal hook @code{after-change-major-mode-hook}. ++It does this by calling @code{run-mode-hooks}. If the major mode is a ++derived mode, that is if it calls another major mode (the parent mode) ++in its body, it should do this inside @code{delay-mode-hooks} so that ++the parent won't run these hooks itself. Instead, the derived mode's ++call to @code{run-mode-hooks} runs the parent's mode hook too. ++@xref{Major Mode Conventions}. ++ ++ Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. ++When user-implemented major modes have not been updated to use it, ++they won't entirely follow these conventions: they may run the ++parent's mode hook too early, or fail to run ++@code{after-change-major-mode-hook}. If you encounter such a major ++mode, please correct it to follow these conventions. ++ ++ When you defined a major mode using @code{define-derived-mode}, it ++automatically makes sure these conventions are followed. If you ++define a major mode ``by hand,'' not using @code{define-derived-mode}, ++use the following functions to handle these conventions automatically. ++ ++@defun run-mode-hooks &rest hookvars ++Major modes should run their mode hook using this function. It is ++similar to @code{run-hooks} (@pxref{Hooks}), but it also runs ++@code{after-change-major-mode-hook}. ++ ++When this function is called during the execution of a ++@code{delay-mode-hooks} form, it does not run the hooks immediately. ++Instead, it arranges for the next call to @code{run-mode-hooks} to run ++them. ++@end defun ++ ++@defmac delay-mode-hooks body@dots{} ++When one major mode command calls another, it should do so inside of ++@code{delay-mode-hooks}. ++ ++This macro executes @var{body}, but tells all @code{run-mode-hooks} ++calls during the execution of @var{body} to delay running their hooks. ++The hooks will actually run during the next call to ++@code{run-mode-hooks} after the end of the @code{delay-mode-hooks} ++construct. ++@end defmac ++ ++@defvar after-change-major-mode-hook ++This is a normal hook run by @code{run-mode-hooks}. It is run at the ++very end of every properly-written major mode function. ++@end defvar ++ ++@node Example Major Modes ++@subsection Major Mode Examples ++ ++ Text mode is perhaps the simplest mode besides Fundamental mode. ++Here are excerpts from @file{text-mode.el} that illustrate many of ++the conventions listed above: ++ ++@smallexample ++@group ++;; @r{Create the syntax table for this mode.} ++(defvar text-mode-syntax-table ++ (let ((st (make-syntax-table))) ++ (modify-syntax-entry ?\" ". " st) ++ (modify-syntax-entry ?\\ ". " st) ++ ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. ++ (modify-syntax-entry ?' "w p" st) ++ st) ++ "Syntax table used while in `text-mode'.") ++@end group ++ ++;; @r{Create the keymap for this mode.} ++@group ++(defvar text-mode-map ++ (let ((map (make-sparse-keymap))) ++ (define-key map "\e\t" 'ispell-complete-word) ++ (define-key map "\es" 'center-line) ++ (define-key map "\eS" 'center-paragraph) ++ map) ++ "Keymap for `text-mode'. ++Many other modes, such as Mail mode, Outline mode ++and Indented Text mode, inherit all the commands ++defined in this map.") ++@end group ++@end smallexample ++ ++ Here is how the actual mode command is defined now: ++ ++@smallexample ++@group ++(define-derived-mode text-mode nil "Text" ++ "Major mode for editing text written for humans to read. ++In this mode, paragraphs are delimited only by blank or white lines. ++You can thus get the full benefit of adaptive filling ++ (see the variable `adaptive-fill-mode'). ++\\@{text-mode-map@} ++Turning on Text mode runs the normal hook `text-mode-hook'." ++@end group ++@group ++ (make-local-variable 'text-mode-variant) ++ (setq text-mode-variant t) ++ ;; @r{These two lines are a feature added recently.} ++ (set (make-local-variable 'require-final-newline) ++ mode-require-final-newline) ++ (set (make-local-variable 'indent-line-function) 'indent-relative)) ++@end group ++@end smallexample ++ ++@noindent ++(The last line is redundant nowadays, since @code{indent-relative} is ++the default value, and we'll delete it in a future version.) ++ ++ Here is how it was defined formerly, before ++@code{define-derived-mode} existed: ++ ++@smallexample ++@group ++;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} ++(defvar text-mode-abbrev-table nil ++ "Abbrev table used while in text mode.") ++(define-abbrev-table 'text-mode-abbrev-table ()) ++@end group ++ ++@group ++(defun text-mode () ++ "Major mode for editing text intended for humans to read... ++ Special commands: \\@{text-mode-map@} ++@end group ++@group ++Turning on text-mode runs the hook `text-mode-hook'." ++ (interactive) ++ (kill-all-local-variables) ++ (use-local-map text-mode-map) ++@end group ++@group ++ (setq local-abbrev-table text-mode-abbrev-table) ++ (set-syntax-table text-mode-syntax-table) ++@end group ++@group ++ ;; @r{These four lines are absent from the current version} ++ ;; @r{not because this is done some other way, but rather} ++ ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} ++ (make-local-variable 'paragraph-start) ++ (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter)) ++ (make-local-variable 'paragraph-separate) ++ (setq paragraph-separate paragraph-start) ++ (make-local-variable 'indent-line-function) ++ (setq indent-line-function 'indent-relative-maybe) ++@end group ++@group ++ (setq mode-name "Text") ++ (setq major-mode 'text-mode) ++ (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} ++ ; @r{customize the mode with a hook.} ++@end group ++@end smallexample ++ ++@cindex @file{lisp-mode.el} ++ The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp ++Interaction mode) have more features than Text mode and the code is ++correspondingly more complicated. Here are excerpts from ++@file{lisp-mode.el} that illustrate how these modes are written. ++ ++@cindex syntax table example ++@smallexample ++@group ++;; @r{Create mode-specific table variables.} ++(defvar lisp-mode-syntax-table nil "") ++(defvar lisp-mode-abbrev-table nil "") ++@end group ++ ++@group ++(defvar emacs-lisp-mode-syntax-table ++ (let ((table (make-syntax-table))) ++ (let ((i 0)) ++@end group ++ ++@group ++ ;; @r{Set syntax of chars up to @samp{0} to say they are} ++ ;; @r{part of symbol names but not words.} ++ ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)} ++ (while (< i ?0) ++ (modify-syntax-entry i "_ " table) ++ (setq i (1+ i))) ++ ;; @r{@dots{} similar code follows for other character ranges.} ++@end group ++@group ++ ;; @r{Then set the syntax codes for characters that are special in Lisp.} ++ (modify-syntax-entry ? " " table) ++ (modify-syntax-entry ?\t " " table) ++ (modify-syntax-entry ?\f " " table) ++ (modify-syntax-entry ?\n "> " table) ++@end group ++@group ++ ;; @r{Give CR the same syntax as newline, for selective-display.} ++ (modify-syntax-entry ?\^m "> " table) ++ (modify-syntax-entry ?\; "< " table) ++ (modify-syntax-entry ?` "' " table) ++ (modify-syntax-entry ?' "' " table) ++ (modify-syntax-entry ?, "' " table) ++@end group ++@group ++ ;; @r{@dots{}likewise for many other characters@dots{}} ++ (modify-syntax-entry ?\( "() " table) ++ (modify-syntax-entry ?\) ")( " table) ++ (modify-syntax-entry ?\[ "(] " table) ++ (modify-syntax-entry ?\] ")[ " table)) ++ table)) ++@end group ++@group ++;; @r{Create an abbrev table for lisp-mode.} ++(define-abbrev-table 'lisp-mode-abbrev-table ()) ++@end group ++@end smallexample ++ ++ The three modes for Lisp share much of their code. For instance, ++each calls the following function to set various variables: ++ ++@smallexample ++@group ++(defun lisp-mode-variables (lisp-syntax) ++ (when lisp-syntax ++ (set-syntax-table lisp-mode-syntax-table)) ++ (setq local-abbrev-table lisp-mode-abbrev-table) ++ @dots{} ++@end group ++@end smallexample ++ ++ In Lisp and most programming languages, we want the paragraph ++commands to treat only blank lines as paragraph separators. And the ++modes should understand the Lisp conventions for comments. The rest of ++@code{lisp-mode-variables} sets this up: ++ ++@smallexample ++@group ++ (make-local-variable 'paragraph-start) ++ (setq paragraph-start (concat page-delimiter "\\|$" )) ++ (make-local-variable 'paragraph-separate) ++ (setq paragraph-separate paragraph-start) ++ @dots{} ++@end group ++@group ++ (make-local-variable 'comment-indent-function) ++ (setq comment-indent-function 'lisp-comment-indent)) ++ @dots{} ++@end group ++@end smallexample ++ ++ Each of the different Lisp modes has a slightly different keymap. For ++example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other ++Lisp modes do not. However, all Lisp modes have some commands in ++common. The following code sets up the common commands: ++ ++@smallexample ++@group ++(defvar shared-lisp-mode-map () ++ "Keymap for commands shared by all sorts of Lisp modes.") ++ ++;; @r{Putting this @code{if} after the @code{defvar} is an older style.} ++(if shared-lisp-mode-map ++ () ++ (setq shared-lisp-mode-map (make-sparse-keymap)) ++ (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp) ++ (define-key shared-lisp-mode-map "\177" ++ 'backward-delete-char-untabify)) ++@end group ++@end smallexample ++ ++@noindent ++And here is the code to set up the keymap for Lisp mode: ++ ++@smallexample ++@group ++(defvar lisp-mode-map () ++ "Keymap for ordinary Lisp mode...") ++ ++(if lisp-mode-map ++ () ++ (setq lisp-mode-map (make-sparse-keymap)) ++ (set-keymap-parent lisp-mode-map shared-lisp-mode-map) ++ (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun) ++ (define-key lisp-mode-map "\C-c\C-z" 'run-lisp)) ++@end group ++@end smallexample ++ ++ Finally, here is the complete major mode function definition for ++Lisp mode. ++ ++@smallexample ++@group ++(defun lisp-mode () ++ "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. ++Commands: ++Delete converts tabs to spaces as it moves back. ++Blank lines separate paragraphs. Semicolons start comments. ++\\@{lisp-mode-map@} ++Note that `run-lisp' may be used either to start an inferior Lisp job ++or to switch back to an existing one. ++@end group ++ ++@group ++Entry to this mode calls the value of `lisp-mode-hook' ++if that value is non-nil." ++ (interactive) ++ (kill-all-local-variables) ++@end group ++@group ++ (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.} ++ (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}} ++ ; @r{finds out what to describe.} ++ (setq mode-name "Lisp") ; @r{This goes into the mode line.} ++ (lisp-mode-variables t) ; @r{This defines various variables.} ++ (make-local-variable 'comment-start-skip) ++ (setq comment-start-skip ++ "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") ++ (make-local-variable 'font-lock-keywords-case-fold-search) ++ (setq font-lock-keywords-case-fold-search t) ++@end group ++@group ++ (setq imenu-case-fold-search t) ++ (set-syntax-table lisp-mode-syntax-table) ++ (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} ++ ; @r{hook to customize the mode.} ++@end group ++@end smallexample ++ ++@node Minor Modes ++@section Minor Modes ++@cindex minor mode ++ ++ A @dfn{minor mode} provides features that users may enable or disable ++independently of the choice of major mode. Minor modes can be enabled ++individually or in combination. Minor modes would be better named ++``generally available, optional feature modes,'' except that such a name ++would be unwieldy. ++ ++ A minor mode is not usually meant as a variation of a single major mode. ++Usually they are general and can apply to many major modes. For ++example, Auto Fill mode works with any major mode that permits text ++insertion. To be general, a minor mode must be effectively independent ++of the things major modes do. ++ ++ A minor mode is often much more difficult to implement than a major ++mode. One reason is that you should be able to activate and deactivate ++minor modes in any order. A minor mode should be able to have its ++desired effect regardless of the major mode and regardless of the other ++minor modes in effect. ++ ++ Often the biggest problem in implementing a minor mode is finding a ++way to insert the necessary hook into the rest of Emacs. Minor mode ++keymaps make this easier than it used to be. ++ ++@defvar minor-mode-list ++The value of this variable is a list of all minor mode commands. ++@end defvar ++ ++@menu ++* Minor Mode Conventions:: Tips for writing a minor mode. ++* Keymaps and Minor Modes:: How a minor mode can have its own keymap. ++* Defining Minor Modes:: A convenient facility for defining minor modes. ++@end menu ++ ++@node Minor Mode Conventions ++@subsection Conventions for Writing Minor Modes ++@cindex minor mode conventions ++@cindex conventions for writing minor modes ++ ++ There are conventions for writing minor modes just as there are for ++major modes. Several of the major mode conventions apply to minor ++modes as well: those regarding the name of the mode initialization ++function, the names of global symbols, the use of a hook at the end of ++the initialization function, and the use of keymaps and other tables. ++ ++ In addition, there are several conventions that are specific to ++minor modes. (The easiest way to follow all the conventions is to use ++the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.) ++ ++@itemize @bullet ++@item ++@cindex mode variable ++Make a variable whose name ends in @samp{-mode} to control the minor ++mode. We call this the @dfn{mode variable}. The minor mode command ++should set this variable (@code{nil} to disable; anything else to ++enable). ++ ++If possible, implement the mode so that setting the variable ++automatically enables or disables the mode. Then the minor mode command ++does not need to do anything except set the variable. ++ ++This variable is used in conjunction with the @code{minor-mode-alist} to ++display the minor mode name in the mode line. It can also enable ++or disable a minor mode keymap. Individual commands or hooks can also ++check the variable's value. ++ ++If you want the minor mode to be enabled separately in each buffer, ++make the variable buffer-local. ++ ++@item ++Define a command whose name is the same as the mode variable. ++Its job is to enable and disable the mode by setting the variable. ++ ++The command should accept one optional argument. If the argument is ++@code{nil}, it should toggle the mode (turn it on if it is off, and ++off if it is on). It should turn the mode on if the argument is a ++positive integer, the symbol @code{t}, or a list whose @sc{car} is one ++of those. It should turn the mode off if the argument is a negative ++integer or zero, the symbol @code{-}, or a list whose @sc{car} is a ++negative integer or zero. The meaning of other arguments is not ++specified. ++ ++Here is an example taken from the definition of @code{transient-mark-mode}. ++It shows the use of @code{transient-mark-mode} as a variable that enables or ++disables the mode's behavior, and also shows the proper way to toggle, ++enable or disable the minor mode based on the raw prefix argument value. ++ ++@smallexample ++@group ++(setq transient-mark-mode ++ (if (null arg) (not transient-mark-mode) ++ (> (prefix-numeric-value arg) 0))) ++@end group ++@end smallexample ++ ++@item ++Add an element to @code{minor-mode-alist} for each minor mode ++(@pxref{Definition of minor-mode-alist}), if you want to indicate the ++minor mode in the mode line. This element should be a list of the ++following form: ++ ++@smallexample ++(@var{mode-variable} @var{string}) ++@end smallexample ++ ++Here @var{mode-variable} is the variable that controls enabling of the ++minor mode, and @var{string} is a short string, starting with a space, ++to represent the mode in the mode line. These strings must be short so ++that there is room for several of them at once. ++ ++When you add an element to @code{minor-mode-alist}, use @code{assq} to ++check for an existing element, to avoid duplication. For example: ++ ++@smallexample ++@group ++(unless (assq 'leif-mode minor-mode-alist) ++ (setq minor-mode-alist ++ (cons '(leif-mode " Leif") minor-mode-alist))) ++@end group ++@end smallexample ++ ++@noindent ++or like this, using @code{add-to-list} (@pxref{List Variables}): ++ ++@smallexample ++@group ++(add-to-list 'minor-mode-alist '(leif-mode " Leif")) ++@end group ++@end smallexample ++@end itemize ++ ++ Global minor modes distributed with Emacs should if possible support ++enabling and disabling via Custom (@pxref{Customization}). To do this, ++the first step is to define the mode variable with @code{defcustom}, and ++specify @code{:type boolean}. ++ ++ If just setting the variable is not sufficient to enable the mode, you ++should also specify a @code{:set} method which enables the mode by ++invoking the mode command. Note in the variable's documentation string that ++setting the variable other than via Custom may not take effect. ++ ++ Also mark the definition with an autoload cookie (@pxref{autoload cookie}), ++and specify a @code{:require} so that customizing the variable will load ++the library that defines the mode. This will copy suitable definitions ++into @file{loaddefs.el} so that users can use @code{customize-option} to ++enable the mode. For example: ++ ++@smallexample ++@group ++ ++;;;###autoload ++(defcustom msb-mode nil ++ "Toggle msb-mode. ++Setting this variable directly does not take effect; ++use either \\[customize] or the function `msb-mode'." ++ :set 'custom-set-minor-mode ++ :initialize 'custom-initialize-default ++ :version "20.4" ++ :type 'boolean ++ :group 'msb ++ :require 'msb) ++@end group ++@end smallexample ++ ++@node Keymaps and Minor Modes ++@subsection Keymaps and Minor Modes ++ ++ Each minor mode can have its own keymap, which is active when the mode ++is enabled. To set up a keymap for a minor mode, add an element to the ++alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}. ++ ++@cindex @code{self-insert-command}, minor modes ++ One use of minor mode keymaps is to modify the behavior of certain ++self-inserting characters so that they do something else as well as ++self-insert. In general, this is the only way to do that, since the ++facilities for customizing @code{self-insert-command} are limited to ++special cases (designed for abbrevs and Auto Fill mode). (Do not try ++substituting your own definition of @code{self-insert-command} for the ++standard one. The editor command loop handles this function specially.) ++ ++The key sequences bound in a minor mode should consist of @kbd{C-c} ++followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other ++punctuation characters are reserved for major modes.) ++ ++@node Defining Minor Modes ++@subsection Defining Minor Modes ++ ++ The macro @code{define-minor-mode} offers a convenient way of ++implementing a mode in one self-contained definition. ++ ++@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} ++This macro defines a new minor mode whose name is @var{mode} (a ++symbol). It defines a command named @var{mode} to toggle the minor ++mode, with @var{doc} as its documentation string. It also defines a ++variable named @var{mode}, which is set to @code{t} or @code{nil} by ++enabling or disabling the mode. The variable is initialized to ++@var{init-value}. Except in unusual circumstances (see below), this ++value must be @code{nil}. ++ ++The string @var{lighter} says what to display in the mode line ++when the mode is enabled; if it is @code{nil}, the mode is not displayed ++in the mode line. ++ ++The optional argument @var{keymap} specifies the keymap for the minor mode. ++It can be a variable name, whose value is the keymap, or it can be an alist ++specifying bindings in this form: ++ ++@example ++(@var{key-sequence} . @var{definition}) ++@end example ++ ++The above three arguments @var{init-value}, @var{lighter}, and ++@var{keymap} can be (partially) omitted when @var{keyword-args} are ++used. The @var{keyword-args} consist of keywords followed by ++corresponding values. A few keywords have special meanings: ++ ++@table @code ++@item :group @var{group} ++Custom group name to use in all generated @code{defcustom} forms. ++Defaults to @var{mode} without the possible trailing @samp{-mode}. ++@strong{Warning:} don't use this default group name unless you have ++written a @code{defgroup} to define that group properly. @xref{Group ++Definitions}. ++ ++@item :global @var{global} ++If non-@code{nil}, this specifies that the minor mode should be global ++rather than buffer-local. It defaults to @code{nil}. ++ ++One of the effects of making a minor mode global is that the ++@var{mode} variable becomes a customization variable. Toggling it ++through the Custom interface turns the mode on and off, and its value ++can be saved for future Emacs sessions (@pxref{Saving ++Customizations,,, emacs, The GNU Emacs Manual}. For the saved ++variable to work, you should ensure that the @code{define-minor-mode} ++form is evaluated each time Emacs starts; for packages that are not ++part of Emacs, the easiest way to do this is to specify a ++@code{:require} keyword. ++ ++@item :init-value @var{init-value} ++This is equivalent to specifying @var{init-value} positionally. ++ ++@item :lighter @var{lighter} ++This is equivalent to specifying @var{lighter} positionally. ++ ++@item :keymap @var{keymap} ++This is equivalent to specifying @var{keymap} positionally. ++@end table ++ ++Any other keyword arguments are passed directly to the ++@code{defcustom} generated for the variable @var{mode}. ++ ++The command named @var{mode} first performs the standard actions such ++as setting the variable named @var{mode} and then executes the ++@var{body} forms, if any. It finishes by running the mode hook ++variable @code{@var{mode}-hook}. ++@end defmac ++ ++ The initial value must be @code{nil} except in cases where (1) the ++mode is preloaded in Emacs, or (2) it is painless for loading to ++enable the mode even though the user did not request it. For ++instance, if the mode has no effect unless something else is enabled, ++and will always be loaded by that time, enabling it by default is ++harmless. But these are unusual circumstances. Normally, the ++initial value must be @code{nil}. ++ ++@findex easy-mmode-define-minor-mode ++ The name @code{easy-mmode-define-minor-mode} is an alias ++for this macro. ++ ++ Here is an example of using @code{define-minor-mode}: ++ ++@smallexample ++(define-minor-mode hungry-mode ++ "Toggle Hungry mode. ++With no argument, this command toggles the mode. ++Non-null prefix argument turns on the mode. ++Null prefix argument turns off the mode. ++ ++When Hungry mode is enabled, the control delete key ++gobbles all preceding whitespace except the last. ++See the command \\[hungry-electric-delete]." ++ ;; The initial value. ++ nil ++ ;; The indicator for the mode line. ++ " Hungry" ++ ;; The minor mode bindings. ++ '(("\C-\^?" . hungry-electric-delete)) ++ :group 'hunger) ++@end smallexample ++ ++@noindent ++This defines a minor mode named ``Hungry mode,'' a command named ++@code{hungry-mode} to toggle it, a variable named @code{hungry-mode} ++which indicates whether the mode is enabled, and a variable named ++@code{hungry-mode-map} which holds the keymap that is active when the ++mode is enabled. It initializes the keymap with a key binding for ++@kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into ++custom group @code{hunger}. There are no @var{body} forms---many ++minor modes don't need any. ++ ++ Here's an equivalent way to write it: ++ ++@smallexample ++(define-minor-mode hungry-mode ++ "Toggle Hungry mode. ++With no argument, this command toggles the mode. ++Non-null prefix argument turns on the mode. ++Null prefix argument turns off the mode. ++ ++When Hungry mode is enabled, the control delete key ++gobbles all preceding whitespace except the last. ++See the command \\[hungry-electric-delete]." ++ ;; The initial value. ++ :init-value nil ++ ;; The indicator for the mode line. ++ :lighter " Hungry" ++ ;; The minor mode bindings. ++ :keymap ++ '(("\C-\^?" . hungry-electric-delete) ++ ("\C-\M-\^?" ++ . (lambda () ++ (interactive) ++ (hungry-electric-delete t)))) ++ :group 'hunger) ++@end smallexample ++ ++@defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{} ++This defines a global toggle named @var{global-mode} whose meaning is ++to enable or disable the buffer-local minor mode @var{mode} in all ++buffers. To turn on the minor mode in a buffer, it uses the function ++@var{turn-on}; to turn off the minor mode, it calls @code{mode} with ++@minus{}1 as argument. ++ ++Globally enabling the mode also affects buffers subsequently created ++by visiting files, and buffers that use a major mode other than ++Fundamental mode; but it does not detect the creation of a new buffer ++in Fundamental mode. ++ ++This defines the customization option @var{global-mode} (@pxref{Customization}), ++which can be toggled in the Custom interface to turn the minor mode on ++and off. As with @code{define-minor-mode}, you should ensure that the ++@code{define-globalized-minor-mode} form is evaluated each time Emacs ++starts, for example by providing a @code{:require} keyword. ++ ++Use @code{:group @var{group}} in @var{keyword-args} to specify the ++custom group for the mode variable of the global minor mode. ++@end defmac ++ ++@node Mode Line Format ++@section Mode-Line Format ++@cindex mode line ++ ++ Each Emacs window (aside from minibuffer windows) typically has a mode ++line at the bottom, which displays status information about the buffer ++displayed in the window. The mode line contains information about the ++buffer, such as its name, associated file, depth of recursive editing, ++and major and minor modes. A window can also have a @dfn{header ++line}, which is much like the mode line but appears at the top of the ++window. ++ ++ This section describes how to control the contents of the mode line ++and header line. We include it in this chapter because much of the ++information displayed in the mode line relates to the enabled major and ++minor modes. ++ ++@menu ++* Base: Mode Line Basics. Basic ideas of mode line control. ++* Data: Mode Line Data. The data structure that controls the mode line. ++* Top: Mode Line Top. The top level variable, mode-line-format. ++* Mode Line Variables:: Variables used in that data structure. ++* %-Constructs:: Putting information into a mode line. ++* Properties in Mode:: Using text properties in the mode line. ++* Header Lines:: Like a mode line, but at the top. ++* Emulating Mode Line:: Formatting text as the mode line would. ++@end menu ++ ++@node Mode Line Basics ++@subsection Mode Line Basics ++ ++ @code{mode-line-format} is a buffer-local variable that holds a ++@dfn{mode line construct}, a kind of template, which controls what is ++displayed on the mode line of the current buffer. The value of ++@code{header-line-format} specifies the buffer's header line in the ++same way. All windows for the same buffer use the same ++@code{mode-line-format} and @code{header-line-format}. ++ ++ For efficiency, Emacs does not continuously recompute the mode ++line and header line of a window. It does so when circumstances ++appear to call for it---for instance, if you change the window ++configuration, switch buffers, narrow or widen the buffer, scroll, or ++change the buffer's modification status. If you modify any of the ++variables referenced by @code{mode-line-format} (@pxref{Mode Line ++Variables}), or any other variables and data structures that affect ++how text is displayed (@pxref{Display}), you may want to force an ++update of the mode line so as to display the new information or ++display it in the new way. ++ ++@defun force-mode-line-update &optional all ++Force redisplay of the current buffer's mode line and header line. ++The next redisplay will update the mode line and header line based on ++the latest values of all relevant variables. With optional ++non-@code{nil} @var{all}, force redisplay of all mode lines and header ++lines. ++ ++This function also forces recomputation of the menu bar menus ++and the frame title. ++@end defun ++ ++ The selected window's mode line is usually displayed in a different ++color using the face @code{mode-line}. Other windows' mode lines ++appear in the face @code{mode-line-inactive} instead. @xref{Faces}. ++ ++@node Mode Line Data ++@subsection The Data Structure of the Mode Line ++@cindex mode-line construct ++ ++ The mode-line contents are controlled by a data structure called a ++@dfn{mode-line construct}, made up of lists, strings, symbols, and ++numbers kept in buffer-local variables. Each data type has a specific ++meaning for the mode-line appearance, as described below. The same ++data structure is used for constructing frame titles (@pxref{Frame ++Titles}) and header lines (@pxref{Header Lines}). ++ ++ A mode-line construct may be as simple as a fixed string of text, ++but it usually specifies how to combine fixed strings with variables' ++values to construct the text. Many of these variables are themselves ++defined to have mode-line constructs as their values. ++ ++ Here are the meanings of various data types as mode-line constructs: ++ ++@table @code ++@cindex percent symbol in mode line ++@item @var{string} ++A string as a mode-line construct appears verbatim except for ++@dfn{@code{%}-constructs} in it. These stand for substitution of ++other data; see @ref{%-Constructs}. ++ ++If parts of the string have @code{face} properties, they control ++display of the text just as they would text in the buffer. Any ++characters which have no @code{face} properties are displayed, by ++default, in the face @code{mode-line} or @code{mode-line-inactive} ++(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The ++@code{help-echo} and @code{local-map} properties in @var{string} have ++special meanings. @xref{Properties in Mode}. ++ ++@item @var{symbol} ++A symbol as a mode-line construct stands for its value. The value of ++@var{symbol} is used as a mode-line construct, in place of @var{symbol}. ++However, the symbols @code{t} and @code{nil} are ignored, as is any ++symbol whose value is void. ++ ++There is one exception: if the value of @var{symbol} is a string, it is ++displayed verbatim: the @code{%}-constructs are not recognized. ++ ++Unless @var{symbol} is marked as ``risky'' (i.e., it has a ++non-@code{nil} @code{risky-local-variable} property), all text ++properties specified in @var{symbol}'s value are ignored. This ++includes the text properties of strings in @var{symbol}'s value, as ++well as all @code{:eval} and @code{:propertize} forms in it. (The ++reason for this is security: non-risky variables could be set ++automatically from file variables without prompting the user.) ++ ++@item (@var{string} @var{rest}@dots{}) ++@itemx (@var{list} @var{rest}@dots{}) ++A list whose first element is a string or list means to process all the ++elements recursively and concatenate the results. This is the most ++common form of mode-line construct. ++ ++@item (:eval @var{form}) ++A list whose first element is the symbol @code{:eval} says to evaluate ++@var{form}, and use the result as a string to display. Make sure this ++evaluation cannot load any files, as doing so could cause infinite ++recursion. ++ ++@item (:propertize @var{elt} @var{props}@dots{}) ++A list whose first element is the symbol @code{:propertize} says to ++process the mode-line construct @var{elt} recursively, then add the text ++properties specified by @var{props} to the result. The argument ++@var{props} should consist of zero or more pairs @var{text-property} ++@var{value}. (This feature is new as of Emacs 22.1.) ++ ++@item (@var{symbol} @var{then} @var{else}) ++A list whose first element is a symbol that is not a keyword specifies ++a conditional. Its meaning depends on the value of @var{symbol}. If ++@var{symbol} has a non-@code{nil} value, the second element, ++@var{then}, is processed recursively as a mode-line element. ++Otherwise, the third element, @var{else}, is processed recursively. ++You may omit @var{else}; then the mode-line element displays nothing ++if the value of @var{symbol} is @code{nil} or void. ++ ++@item (@var{width} @var{rest}@dots{}) ++A list whose first element is an integer specifies truncation or ++padding of the results of @var{rest}. The remaining elements ++@var{rest} are processed recursively as mode-line constructs and ++concatenated together. When @var{width} is positive, the result is ++space filled on the right if its width is less than @var{width}. When ++@var{width} is negative, the result is truncated on the right to ++@minus{}@var{width} columns if its width exceeds @minus{}@var{width}. ++ ++For example, the usual way to show what percentage of a buffer is above ++the top of the window is to use a list like this: @code{(-3 "%p")}. ++@end table ++ ++@node Mode Line Top ++@subsection The Top Level of Mode Line Control ++ ++ The variable in overall control of the mode line is ++@code{mode-line-format}. ++ ++@defopt mode-line-format ++The value of this variable is a mode-line construct that controls the ++contents of the mode-line. It is always buffer-local in all buffers. ++ ++If you set this variable to @code{nil} in a buffer, that buffer does ++not have a mode line. (A window that is just one line tall never ++displays a mode line.) ++@end defopt ++ ++ The default value of @code{mode-line-format} is designed to use the ++values of other variables such as @code{mode-line-position} and ++@code{mode-line-modes} (which in turn incorporates the values of the ++variables @code{mode-name} and @code{minor-mode-alist}). Very few ++modes need to alter @code{mode-line-format} itself. For most ++purposes, it is sufficient to alter some of the variables that ++@code{mode-line-format} either directly or indirectly refers to. ++ ++ If you do alter @code{mode-line-format} itself, the new value should ++use the same variables that appear in the default value (@pxref{Mode ++Line Variables}), rather than duplicating their contents or displaying ++the information in another fashion. This way, customizations made by ++the user or by Lisp programs (such as @code{display-time} and major ++modes) via changes to those variables remain effective. ++ ++ Here is an example of a @code{mode-line-format} that might be ++useful for @code{shell-mode}, since it contains the host name and default ++directory. ++ ++@example ++@group ++(setq mode-line-format ++ (list "-" ++ 'mode-line-mule-info ++ 'mode-line-modified ++ 'mode-line-frame-identification ++ "%b--" ++@end group ++@group ++ ;; @r{Note that this is evaluated while making the list.} ++ ;; @r{It makes a mode-line construct which is just a string.} ++ (getenv "HOST") ++@end group ++ ":" ++ 'default-directory ++ " " ++ 'global-mode-string ++ " %[(" ++ '(:eval (mode-line-mode-name)) ++ 'mode-line-process ++ 'minor-mode-alist ++ "%n" ++ ")%]--" ++@group ++ '(which-func-mode ("" which-func-format "--")) ++ '(line-number-mode "L%l--") ++ '(column-number-mode "C%c--") ++ '(-3 "%p") ++ "-%-")) ++@end group ++@end example ++ ++@noindent ++(The variables @code{line-number-mode}, @code{column-number-mode} ++and @code{which-func-mode} enable particular minor modes; as usual, ++these variable names are also the minor mode command names.) ++ ++@node Mode Line Variables ++@subsection Variables Used in the Mode Line ++ ++ This section describes variables incorporated by the standard value ++of @code{mode-line-format} into the text of the mode line. There is ++nothing inherently special about these variables; any other variables ++could have the same effects on the mode line if ++@code{mode-line-format}'s value were changed to use them. However, ++various parts of Emacs set these variables on the understanding that ++they will control parts of the mode line; therefore, practically ++speaking, it is essential for the mode line to use them. ++ ++@defvar mode-line-mule-info ++This variable holds the value of the mode-line construct that displays ++information about the language environment, buffer coding system, and ++current input method. @xref{Non-ASCII Characters}. ++@end defvar ++ ++@defvar mode-line-modified ++This variable holds the value of the mode-line construct that displays ++whether the current buffer is modified. Its default value displays ++@samp{**} if the buffer is modified, @samp{--} if the buffer is not ++modified, @samp{%%} if the buffer is read only, and @samp{%*} if the ++buffer is read only and modified. ++ ++Changing this variable does not force an update of the mode line. ++@end defvar ++ ++@defvar mode-line-frame-identification ++This variable identifies the current frame. Its default value ++displays @code{" "} if you are using a window system which can show ++multiple frames, or @code{"-%F "} on an ordinary terminal which shows ++only one frame at a time. ++@end defvar ++ ++@defvar mode-line-buffer-identification ++This variable identifies the buffer being displayed in the window. ++Its default value displays the buffer name, padded with spaces to at ++least 12 columns. ++@end defvar ++ ++@defopt mode-line-position ++This variable indicates the position in the buffer. Its default value ++displays the buffer percentage and, optionally, the buffer size, the ++line number and the column number. ++@end defopt ++ ++@defvar vc-mode ++The variable @code{vc-mode}, buffer-local in each buffer, records ++whether the buffer's visited file is maintained with version control, ++and, if so, which kind. Its value is a string that appears in the mode ++line, or @code{nil} for no version control. ++@end defvar ++ ++@defopt mode-line-modes ++This variable displays the buffer's major and minor modes. Its ++default value also displays the recursive editing level, information ++on the process status, and whether narrowing is in effect. ++@end defopt ++ ++ The following three variables are used in @code{mode-line-modes}: ++ ++@defvar mode-name ++This buffer-local variable holds the ``pretty'' name of the current ++buffer's major mode. Each major mode should set this variable so that ++the mode name will appear in the mode line. The value does not have ++to be a string, but can use any of the data types valid in a mode-line ++construct (@pxref{Mode Line Data}). To compute the string that will ++identify the mode name in the mode line, use @code{format-mode-line} ++(@pxref{Emulating Mode Line}). ++@end defvar ++ ++@defvar mode-line-process ++This buffer-local variable contains the mode-line information on process ++status in modes used for communicating with subprocesses. It is ++displayed immediately following the major mode name, with no intervening ++space. For example, its value in the @samp{*shell*} buffer is ++@code{(":%s")}, which allows the shell to display its status along ++with the major mode as: @samp{(Shell:run)}. Normally this variable ++is @code{nil}. ++@end defvar ++ ++@defvar minor-mode-alist ++@anchor{Definition of minor-mode-alist} ++This variable holds an association list whose elements specify how the ++mode line should indicate that a minor mode is active. Each element of ++the @code{minor-mode-alist} should be a two-element list: ++ ++@example ++(@var{minor-mode-variable} @var{mode-line-string}) ++@end example ++ ++More generally, @var{mode-line-string} can be any mode-line spec. It ++appears in the mode line when the value of @var{minor-mode-variable} ++is non-@code{nil}, and not otherwise. These strings should begin with ++spaces so that they don't run together. Conventionally, the ++@var{minor-mode-variable} for a specific mode is set to a ++non-@code{nil} value when that minor mode is activated. ++ ++@code{minor-mode-alist} itself is not buffer-local. Each variable ++mentioned in the alist should be buffer-local if its minor mode can be ++enabled separately in each buffer. ++@end defvar ++ ++@defvar global-mode-string ++This variable holds a mode-line spec that, by default, appears in the ++mode line just after the @code{which-func-mode} minor mode if set, ++else after @code{mode-line-modes}. The command @code{display-time} ++sets @code{global-mode-string} to refer to the variable ++@code{display-time-string}, which holds a string containing the time ++and load information. ++ ++The @samp{%M} construct substitutes the value of ++@code{global-mode-string}, but that is obsolete, since the variable is ++included in the mode line from @code{mode-line-format}. ++@end defvar ++ ++ The variable @code{default-mode-line-format} is where ++@code{mode-line-format} usually gets its value: ++ ++@defvar default-mode-line-format ++This variable holds the default @code{mode-line-format} for buffers ++that do not override it. This is the same as @code{(default-value ++'mode-line-format)}. ++ ++Here is a simplified version of the default value of ++@code{default-mode-line-format}. The real default value also ++specifies addition of text properties. ++ ++@example ++@group ++("-" ++ mode-line-mule-info ++ mode-line-modified ++ mode-line-frame-identification ++ mode-line-buffer-identification ++@end group ++ " " ++ mode-line-position ++ (vc-mode vc-mode) ++ " " ++@group ++ mode-line-modes ++ (which-func-mode ("" which-func-format "--")) ++ (global-mode-string ("--" global-mode-string)) ++ "-%-") ++@end group ++@end example ++@end defvar ++ ++@node %-Constructs ++@subsection @code{%}-Constructs in the Mode Line ++ ++ Strings used as mode-line constructs can use certain ++@code{%}-constructs to substitute various kinds of data. Here is a ++list of the defined @code{%}-constructs, and what they mean. In any ++construct except @samp{%%}, you can add a decimal integer after the ++@samp{%} to specify a minimum field width. If the width is less, the ++field is padded with spaces to the right. ++ ++@table @code ++@item %b ++The current buffer name, obtained with the @code{buffer-name} function. ++@xref{Buffer Names}. ++ ++@item %c ++The current column number of point. ++ ++@item %e ++When Emacs is nearly out of memory for Lisp objects, a brief message ++saying so. Otherwise, this is empty. ++ ++@item %f ++The visited file name, obtained with the @code{buffer-file-name} ++function. @xref{Buffer File Name}. ++ ++@item %F ++The title (only on a window system) or the name of the selected frame. ++@xref{Basic Parameters}. ++ ++@item %i ++The size of the accessible part of the current buffer; basically ++@code{(- (point-max) (point-min))}. ++ ++@item %I ++Like @samp{%i}, but the size is printed in a more readable way by using ++@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to ++abbreviate. ++ ++@item %l ++The current line number of point, counting within the accessible portion ++of the buffer. ++ ++@item %n ++@samp{Narrow} when narrowing is in effect; nothing otherwise (see ++@code{narrow-to-region} in @ref{Narrowing}). ++ ++@item %p ++The percentage of the buffer text above the @strong{top} of window, or ++@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default ++mode-line specification truncates this to three characters. ++ ++@item %P ++The percentage of the buffer text that is above the @strong{bottom} of ++the window (which includes the text visible in the window, as well as ++the text above the top), plus @samp{Top} if the top of the buffer is ++visible on screen; or @samp{Bottom} or @samp{All}. ++ ++@item %s ++The status of the subprocess belonging to the current buffer, obtained with ++@code{process-status}. @xref{Process Information}. ++ ++@item %t ++Whether the visited file is a text file or a binary file. This is a ++meaningful distinction only on certain operating systems (@pxref{MS-DOS ++File Types}). ++ ++@item %z ++The mnemonics of keyboard, terminal, and buffer coding systems. ++ ++@item %Z ++Like @samp{%z}, but including the end-of-line format. ++ ++@item %* ++@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* ++@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* ++@samp{-} otherwise. @xref{Buffer Modification}. ++ ++@item %+ ++@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* ++@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* ++@samp{-} otherwise. This differs from @samp{%*} only for a modified ++read-only buffer. @xref{Buffer Modification}. ++ ++@item %& ++@samp{*} if the buffer is modified, and @samp{-} otherwise. ++ ++@item %[ ++An indication of the depth of recursive editing levels (not counting ++minibuffer levels): one @samp{[} for each editing level. ++@xref{Recursive Editing}. ++ ++@item %] ++One @samp{]} for each recursive editing level (not counting minibuffer ++levels). ++ ++@item %- ++Dashes sufficient to fill the remainder of the mode line. ++ ++@item %% ++The character @samp{%}---this is how to include a literal @samp{%} in a ++string in which @code{%}-constructs are allowed. ++@end table ++ ++The following two @code{%}-constructs are still supported, but they are ++obsolete, since you can get the same results with the variables ++@code{mode-name} and @code{global-mode-string}. ++ ++@table @code ++@item %m ++The value of @code{mode-name}. ++ ++@item %M ++The value of @code{global-mode-string}. ++@end table ++ ++@node Properties in Mode ++@subsection Properties in the Mode Line ++@cindex text properties in the mode line ++ ++ Certain text properties are meaningful in the ++mode line. The @code{face} property affects the appearance of text; the ++@code{help-echo} property associates help strings with the text, and ++@code{local-map} can make the text mouse-sensitive. ++ ++ There are four ways to specify text properties for text in the mode ++line: ++ ++@enumerate ++@item ++Put a string with a text property directly into the mode-line data ++structure. ++ ++@item ++Put a text property on a mode-line %-construct such as @samp{%12b}; then ++the expansion of the %-construct will have that same text property. ++ ++@item ++Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to ++give @var{elt} a text property specified by @var{props}. ++ ++@item ++Use a list containing @code{:eval @var{form}} in the mode-line data ++structure, and make @var{form} evaluate to a string that has a text ++property. ++@end enumerate ++ ++ You can use the @code{local-map} property to specify a keymap. This ++keymap only takes real effect for mouse clicks; binding character keys ++and function keys to it has no effect, since it is impossible to move ++point into the mode line. ++ ++ When the mode line refers to a variable which does not have a ++non-@code{nil} @code{risky-local-variable} property, any text ++properties given or specified within that variable's values are ++ignored. This is because such properties could otherwise specify ++functions to be called, and those functions could come from file ++local variables. ++ ++@node Header Lines ++@subsection Window Header Lines ++@cindex header line (of a window) ++@cindex window header line ++ ++ A window can have a @dfn{header line} at the ++top, just as it can have a mode line at the bottom. The header line ++feature works just like the mode-line feature, except that it's ++controlled by different variables. ++ ++@defvar header-line-format ++This variable, local in every buffer, specifies how to display the ++header line, for windows displaying the buffer. The format of the value ++is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). ++@end defvar ++ ++@defvar default-header-line-format ++This variable holds the default @code{header-line-format} for buffers ++that do not override it. This is the same as @code{(default-value ++'header-line-format)}. ++ ++It is normally @code{nil}, so that ordinary buffers have no header line. ++@end defvar ++ ++ A window that is just one line tall never displays a header line. A ++window that is two lines tall cannot display both a mode line and a ++header line at once; if it has a mode line, then it does not display a ++header line. ++ ++@node Emulating Mode Line ++@subsection Emulating Mode-Line Formatting ++ ++ You can use the function @code{format-mode-line} to compute ++the text that would appear in a mode line or header line ++based on a certain mode-line specification. ++ ++@defun format-mode-line format &optional face window buffer ++This function formats a line of text according to @var{format} as if ++it were generating the mode line for @var{window}, but instead of ++displaying the text in the mode line or the header line, it returns ++the text as a string. The argument @var{window} defaults to the ++selected window. If @var{buffer} is non-@code{nil}, all the ++information used is taken from @var{buffer}; by default, it comes from ++@var{window}'s buffer. ++ ++The value string normally has text properties that correspond to the ++faces, keymaps, etc., that the mode line would have. And any character ++for which no @code{face} property is specified gets a default ++value which is usually @var{face}. (If @var{face} is @code{t}, ++that stands for either @code{mode-line} if @var{window} is selected, ++otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or ++omitted, that stands for no face property.) ++ ++However, if @var{face} is an integer, the value has no text properties. ++ ++For example, @code{(format-mode-line header-line-format)} returns the ++text that would appear in the selected window's header line (@code{""} ++if it has no header line). @code{(format-mode-line header-line-format ++'header-line)} returns the same text, with each character ++carrying the face that it will have in the header line itself. ++@end defun ++ ++@node Imenu ++@section Imenu ++ ++@cindex Imenu ++ @dfn{Imenu} is a feature that lets users select a definition or ++section in the buffer, from a menu which lists all of them, to go ++directly to that location in the buffer. Imenu works by constructing ++a buffer index which lists the names and buffer positions of the ++definitions, or other named portions of the buffer; then the user can ++choose one of them and move point to it. Major modes can add a menu ++bar item to use Imenu using @code{imenu-add-to-menubar}. ++ ++@defun imenu-add-to-menubar name ++This function defines a local menu bar item named @var{name} ++to run Imenu. ++@end defun ++ ++ The user-level commands for using Imenu are described in the Emacs ++Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section ++explains how to customize Imenu's method of finding definitions or ++buffer portions for a particular major mode. ++ ++ The usual and simplest way is to set the variable ++@code{imenu-generic-expression}: ++ ++@defvar imenu-generic-expression ++This variable, if non-@code{nil}, is a list that specifies regular ++expressions for finding definitions for Imenu. Simple elements of ++@code{imenu-generic-expression} look like this: ++ ++@example ++(@var{menu-title} @var{regexp} @var{index}) ++@end example ++ ++Here, if @var{menu-title} is non-@code{nil}, it says that the matches ++for this element should go in a submenu of the buffer index; ++@var{menu-title} itself specifies the name for the submenu. If ++@var{menu-title} is @code{nil}, the matches for this element go directly ++in the top level of the buffer index. ++ ++The second item in the list, @var{regexp}, is a regular expression ++(@pxref{Regular Expressions}); anything in the buffer that it matches ++is considered a definition, something to mention in the buffer index. ++The third item, @var{index}, is a non-negative integer that indicates ++which subexpression in @var{regexp} matches the definition's name. ++ ++An element can also look like this: ++ ++@example ++(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{}) ++@end example ++ ++Each match for this element creates an index item, and when the index ++item is selected by the user, it calls @var{function} with arguments ++consisting of the item name, the buffer position, and @var{arguments}. ++ ++For Emacs Lisp mode, @code{imenu-generic-expression} could look like ++this: ++ ++@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+] ++@example ++@group ++((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\ ++\\s-+\\([-A-Za-z0-9+]+\\)" 2) ++@end group ++@group ++ ("*Vars*" "^\\s-*(def\\(var\\|const\\)\ ++\\s-+\\([-A-Za-z0-9+]+\\)" 2) ++@end group ++@group ++ ("*Types*" ++ "^\\s-*\ ++(def\\(type\\|struct\\|class\\|ine-condition\\)\ ++\\s-+\\([-A-Za-z0-9+]+\\)" 2)) ++@end group ++@end example ++ ++Setting this variable makes it buffer-local in the current buffer. ++@end defvar ++ ++@defvar imenu-case-fold-search ++This variable controls whether matching against the regular ++expressions in the value of @code{imenu-generic-expression} is ++case-sensitive: @code{t}, the default, means matching should ignore ++case. ++ ++Setting this variable makes it buffer-local in the current buffer. ++@end defvar ++ ++@defvar imenu-syntax-alist ++This variable is an alist of syntax table modifiers to use while ++processing @code{imenu-generic-expression}, to override the syntax table ++of the current buffer. Each element should have this form: ++ ++@example ++(@var{characters} . @var{syntax-description}) ++@end example ++ ++The @sc{car}, @var{characters}, can be either a character or a string. ++The element says to give that character or characters the syntax ++specified by @var{syntax-description}, which is passed to ++@code{modify-syntax-entry} (@pxref{Syntax Table Functions}). ++ ++This feature is typically used to give word syntax to characters which ++normally have symbol syntax, and thus to simplify ++@code{imenu-generic-expression} and speed up matching. ++For example, Fortran mode uses it this way: ++ ++@example ++(setq imenu-syntax-alist '(("_$" . "w"))) ++@end example ++ ++The @code{imenu-generic-expression} regular expressions can then use ++@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this ++technique may be inconvenient when the mode needs to limit the initial ++character of a name to a smaller set of characters than are allowed in ++the rest of a name. ++ ++Setting this variable makes it buffer-local in the current buffer. ++@end defvar ++ ++ Another way to customize Imenu for a major mode is to set the ++variables @code{imenu-prev-index-position-function} and ++@code{imenu-extract-index-name-function}: ++ ++@defvar imenu-prev-index-position-function ++If this variable is non-@code{nil}, its value should be a function that ++finds the next ``definition'' to put in the buffer index, scanning ++backward in the buffer from point. It should return @code{nil} if it ++doesn't find another ``definition'' before point. Otherwise it should ++leave point at the place it finds a ``definition'' and return any ++non-@code{nil} value. ++ ++Setting this variable makes it buffer-local in the current buffer. ++@end defvar ++ ++@defvar imenu-extract-index-name-function ++If this variable is non-@code{nil}, its value should be a function to ++return the name for a definition, assuming point is in that definition ++as the @code{imenu-prev-index-position-function} function would leave ++it. ++ ++Setting this variable makes it buffer-local in the current buffer. ++@end defvar ++ ++ The last way to customize Imenu for a major mode is to set the ++variable @code{imenu-create-index-function}: ++ ++@defvar imenu-create-index-function ++This variable specifies the function to use for creating a buffer ++index. The function should take no arguments, and return an index ++alist for the current buffer. It is called within ++@code{save-excursion}, so where it leaves point makes no difference. ++ ++The index alist can have three types of elements. Simple elements ++look like this: ++ ++@example ++(@var{index-name} . @var{index-position}) ++@end example ++ ++Selecting a simple element has the effect of moving to position ++@var{index-position} in the buffer. Special elements look like this: ++ ++@example ++(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{}) ++@end example ++ ++Selecting a special element performs: ++ ++@example ++(funcall @var{function} ++ @var{index-name} @var{index-position} @var{arguments}@dots{}) ++@end example ++ ++A nested sub-alist element looks like this: ++ ++@example ++(@var{menu-title} @var{sub-alist}) ++@end example ++ ++It creates the submenu @var{menu-title} specified by @var{sub-alist}. ++ ++The default value of @code{imenu-create-index-function} is ++@code{imenu-default-create-index-function}. This function calls the ++value of @code{imenu-prev-index-position-function} and the value of ++@code{imenu-extract-index-name-function} to produce the index alist. ++However, if either of these two variables is @code{nil}, the default ++function uses @code{imenu-generic-expression} instead. ++ ++Setting this variable makes it buffer-local in the current buffer. ++@end defvar ++ ++@node Font Lock Mode ++@section Font Lock Mode ++@cindex Font Lock mode ++ ++ @dfn{Font Lock mode} is a feature that automatically attaches ++@code{face} properties to certain parts of the buffer based on their ++syntactic role. How it parses the buffer depends on the major mode; ++most major modes define syntactic criteria for which faces to use in ++which contexts. This section explains how to customize Font Lock for a ++particular major mode. ++ ++ Font Lock mode finds text to highlight in two ways: through ++syntactic parsing based on the syntax table, and through searching ++(usually for regular expressions). Syntactic fontification happens ++first; it finds comments and string constants and highlights them. ++Search-based fontification happens second. ++ ++@menu ++* Font Lock Basics:: Overview of customizing Font Lock. ++* Search-based Fontification:: Fontification based on regexps. ++* Customizing Keywords:: Customizing search-based fontification. ++* Other Font Lock Variables:: Additional customization facilities. ++* Levels of Font Lock:: Each mode can define alternative levels ++ so that the user can select more or less. ++* Precalculated Fontification:: How Lisp programs that produce the buffer ++ contents can also specify how to fontify it. ++* Faces for Font Lock:: Special faces specifically for Font Lock. ++* Syntactic Font Lock:: Fontification based on syntax tables. ++* Setting Syntax Properties:: Defining character syntax based on context ++ using the Font Lock mechanism. ++* Multiline Font Lock:: How to coerce Font Lock into properly ++ highlighting multiline constructs. ++@end menu ++ ++@node Font Lock Basics ++@subsection Font Lock Basics ++ ++ There are several variables that control how Font Lock mode highlights ++text. But major modes should not set any of these variables directly. ++Instead, they should set @code{font-lock-defaults} as a buffer-local ++variable. The value assigned to this variable is used, if and when Font ++Lock mode is enabled, to set all the other variables. ++ ++@defvar font-lock-defaults ++This variable is set by major modes, as a buffer-local variable, to ++specify how to fontify text in that mode. It automatically becomes ++buffer-local when you set it. If its value is @code{nil}, Font-Lock ++mode does no highlighting, and you can use the @samp{Faces} menu ++(under @samp{Edit} and then @samp{Text Properties} in the menu bar) to ++assign faces explicitly to text in the buffer. ++ ++If non-@code{nil}, the value should look like this: ++ ++@example ++(@var{keywords} [@var{keywords-only} [@var{case-fold} ++ [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]]) ++@end example ++ ++The first element, @var{keywords}, indirectly specifies the value of ++@code{font-lock-keywords} which directs search-based fontification. ++It can be a symbol, a variable or a function whose value is the list ++to use for @code{font-lock-keywords}. It can also be a list of ++several such symbols, one for each possible level of fontification. ++The first symbol specifies the @samp{mode default} level of ++fontification, the next symbol level 1 fontification, the next level 2, ++and so on. The @samp{mode default} level is normally the same as level ++1. It is used when @code{font-lock-maximum-decoration} has a @code{nil} ++value. @xref{Levels of Font Lock}. ++ ++The second element, @var{keywords-only}, specifies the value of the ++variable @code{font-lock-keywords-only}. If this is omitted or ++@code{nil}, syntactic fontification (of strings and comments) is also ++performed. If this is non-@code{nil}, such fontification is not ++performed. @xref{Syntactic Font Lock}. ++ ++The third element, @var{case-fold}, specifies the value of ++@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil}, ++Font Lock mode ignores case when searching as directed by ++@code{font-lock-keywords}. ++ ++If the fourth element, @var{syntax-alist}, is non-@code{nil}, it ++should be a list of cons cells of the form @code{(@var{char-or-string} ++. @var{string})}. These are used to set up a syntax table for ++syntactic fontification (@pxref{Syntax Table Functions}). The ++resulting syntax table is stored in @code{font-lock-syntax-table}. ++ ++The fifth element, @var{syntax-begin}, specifies the value of ++@code{font-lock-beginning-of-syntax-function}. We recommend setting ++this variable to @code{nil} and using @code{syntax-begin-function} ++instead. ++ ++All the remaining elements (if any) are collectively called ++@var{other-vars}. Each of these elements should have the form ++@code{(@var{variable} . @var{value})}---which means, make ++@var{variable} buffer-local and then set it to @var{value}. You can ++use these @var{other-vars} to set other variables that affect ++fontification, aside from those you can control with the first five ++elements. @xref{Other Font Lock Variables}. ++@end defvar ++ ++ If your mode fontifies text explicitly by adding ++@code{font-lock-face} properties, it can specify @code{(nil t)} for ++@code{font-lock-defaults} to turn off all automatic fontification. ++However, this is not required; it is possible to fontify some things ++using @code{font-lock-face} properties and set up automatic ++fontification for other parts of the text. ++ ++@node Search-based Fontification ++@subsection Search-based Fontification ++ ++ The most important variable for customizing Font Lock mode is ++@code{font-lock-keywords}. It specifies the search criteria for ++search-based fontification. You should specify the value of this ++variable with @var{keywords} in @code{font-lock-defaults}. ++ ++@defvar font-lock-keywords ++This variable's value is a list of the keywords to highlight. Be ++careful when composing regular expressions for this list; a poorly ++written pattern can dramatically slow things down! ++@end defvar ++ ++ Each element of @code{font-lock-keywords} specifies how to find ++certain cases of text, and how to highlight those cases. Font Lock mode ++processes the elements of @code{font-lock-keywords} one by one, and for ++each element, it finds and handles all matches. Ordinarily, once ++part of the text has been fontified already, this cannot be overridden ++by a subsequent match in the same text; but you can specify different ++behavior using the @var{override} element of a @var{subexp-highlighter}. ++ ++ Each element of @code{font-lock-keywords} should have one of these ++forms: ++ ++@table @code ++@item @var{regexp} ++Highlight all matches for @var{regexp} using ++@code{font-lock-keyword-face}. For example, ++ ++@example ++;; @r{Highlight occurrences of the word @samp{foo}} ++;; @r{using @code{font-lock-keyword-face}.} ++"\\" ++@end example ++ ++The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful ++for calculating optimal regular expressions to match a number of ++different keywords. ++ ++@item @var{function} ++Find text by calling @var{function}, and highlight the matches ++it finds using @code{font-lock-keyword-face}. ++ ++When @var{function} is called, it receives one argument, the limit of ++the search; it should begin searching at point, and not search beyond the ++limit. It should return non-@code{nil} if it succeeds, and set the ++match data to describe the match that was found. Returning @code{nil} ++indicates failure of the search. ++ ++Fontification will call @var{function} repeatedly with the same limit, ++and with point where the previous invocation left it, until ++@var{function} fails. On failure, @var{function} need not reset point ++in any particular way. ++ ++@item (@var{matcher} . @var{subexp}) ++In this kind of element, @var{matcher} is either a regular ++expression or a function, as described above. The @sc{cdr}, ++@var{subexp}, specifies which subexpression of @var{matcher} should be ++highlighted (instead of the entire text that @var{matcher} matched). ++ ++@example ++;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},} ++;; @r{using @code{font-lock-keyword-face}.} ++("fu\\(bar\\)" . 1) ++@end example ++ ++If you use @code{regexp-opt} to produce the regular expression ++@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp ++Functions}) to calculate the value for @var{subexp}. ++ ++@item (@var{matcher} . @var{facespec}) ++In this kind of element, @var{facespec} is an expression whose value ++specifies the face to use for highlighting. In the simplest case, ++@var{facespec} is a Lisp variable (a symbol) whose value is a face ++name. ++ ++@example ++;; @r{Highlight occurrences of @samp{fubar},} ++;; @r{using the face which is the value of @code{fubar-face}.} ++("fubar" . fubar-face) ++@end example ++ ++However, @var{facespec} can also evaluate to a list of this form: ++ ++@example ++(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) ++@end example ++ ++@noindent ++to specify the face @var{face} and various additional text properties ++to put on the text that matches. If you do this, be sure to add the ++other text property names that you set in this way to the value of ++@code{font-lock-extra-managed-props} so that the properties will also ++be cleared out when they are no longer appropriate. Alternatively, ++you can set the variable @code{font-lock-unfontify-region-function} to ++a function that clears these properties. @xref{Other Font Lock ++Variables}. ++ ++@item (@var{matcher} . @var{subexp-highlighter}) ++In this kind of element, @var{subexp-highlighter} is a list ++which specifies how to highlight matches found by @var{matcher}. ++It has the form: ++ ++@example ++(@var{subexp} @var{facespec} [@var{override} [@var{laxmatch}]]) ++@end example ++ ++The @sc{car}, @var{subexp}, is an integer specifying which subexpression ++of the match to fontify (0 means the entire matching text). The second ++subelement, @var{facespec}, is an expression whose value specifies the ++face, as described above. ++ ++The last two values in @var{subexp-highlighter}, @var{override} and ++@var{laxmatch}, are optional flags. If @var{override} is @code{t}, ++this element can override existing fontification made by previous ++elements of @code{font-lock-keywords}. If it is @code{keep}, then ++each character is fontified if it has not been fontified already by ++some other element. If it is @code{prepend}, the face specified by ++@var{facespec} is added to the beginning of the @code{font-lock-face} ++property. If it is @code{append}, the face is added to the end of the ++@code{font-lock-face} property. ++ ++If @var{laxmatch} is non-@code{nil}, it means there should be no error ++if there is no subexpression numbered @var{subexp} in @var{matcher}. ++Obviously, fontification of the subexpression numbered @var{subexp} will ++not occur. However, fontification of other subexpressions (and other ++regexps) will continue. If @var{laxmatch} is @code{nil}, and the ++specified subexpression is missing, then an error is signaled which ++terminates search-based fontification. ++ ++Here are some examples of elements of this kind, and what they do: ++ ++@smallexample ++;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using} ++;; @r{@code{foo-bar-face}, even if they have already been highlighted.} ++;; @r{@code{foo-bar-face} should be a variable whose value is a face.} ++("foo\\|bar" 0 foo-bar-face t) ++ ++;; @r{Highlight the first subexpression within each occurrence} ++;; @r{that the function @code{fubar-match} finds,} ++;; @r{using the face which is the value of @code{fubar-face}.} ++(fubar-match 1 fubar-face) ++@end smallexample ++ ++@item (@var{matcher} . @var{anchored-highlighter}) ++In this kind of element, @var{anchored-highlighter} specifies how to ++highlight text that follows a match found by @var{matcher}. So a ++match found by @var{matcher} acts as the anchor for further searches ++specified by @var{anchored-highlighter}. @var{anchored-highlighter} ++is a list of the following form: ++ ++@example ++(@var{anchored-matcher} @var{pre-form} @var{post-form} ++ @var{subexp-highlighters}@dots{}) ++@end example ++ ++Here, @var{anchored-matcher}, like @var{matcher}, is either a regular ++expression or a function. After a match of @var{matcher} is found, ++point is at the end of the match. Now, Font Lock evaluates the form ++@var{pre-form}. Then it searches for matches of ++@var{anchored-matcher} and uses @var{subexp-highlighters} to highlight ++these. A @var{subexp-highlighter} is as described above. Finally, ++Font Lock evaluates @var{post-form}. ++ ++The forms @var{pre-form} and @var{post-form} can be used to initialize ++before, and cleanup after, @var{anchored-matcher} is used. Typically, ++@var{pre-form} is used to move point to some position relative to the ++match of @var{matcher}, before starting with @var{anchored-matcher}. ++@var{post-form} might be used to move back, before resuming with ++@var{matcher}. ++ ++After Font Lock evaluates @var{pre-form}, it does not search for ++@var{anchored-matcher} beyond the end of the line. However, if ++@var{pre-form} returns a buffer position that is greater than the ++position of point after @var{pre-form} is evaluated, then the position ++returned by @var{pre-form} is used as the limit of the search instead. ++It is generally a bad idea to return a position greater than the end ++of the line; in other words, the @var{anchored-matcher} search should ++not span lines. ++ ++For example, ++ ++@smallexample ++;; @r{Highlight occurrences of the word @samp{item} following} ++;; @r{an occurrence of the word @samp{anchor} (on the same line)} ++;; @r{in the value of @code{item-face}.} ++("\\" "\\" nil nil (0 item-face)) ++@end smallexample ++ ++Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore ++searching for @samp{item} starts at the end of the match of ++@samp{anchor}, and searching for subsequent instances of @samp{anchor} ++resumes from where searching for @samp{item} concluded. ++ ++@item (@var{matcher} @var{highlighters}@dots{}) ++This sort of element specifies several @var{highlighter} lists for a ++single @var{matcher}. A @var{highlighter} list can be of the type ++@var{subexp-highlighter} or @var{anchored-highlighter} as described ++above. ++ ++For example, ++ ++@smallexample ++;; @r{Highlight occurrences of the word @samp{anchor} in the value} ++;; @r{of @code{anchor-face}, and subsequent occurrences of the word} ++;; @r{@samp{item} (on the same line) in the value of @code{item-face}.} ++("\\" (0 anchor-face) ++ ("\\" nil nil (0 item-face))) ++@end smallexample ++ ++@item (eval . @var{form}) ++Here @var{form} is an expression to be evaluated the first time ++this value of @code{font-lock-keywords} is used in a buffer. ++Its value should have one of the forms described in this table. ++@end table ++ ++@strong{Warning:} Do not design an element of @code{font-lock-keywords} ++to match text which spans lines; this does not work reliably. ++For details, see @xref{Multiline Font Lock}. ++ ++You can use @var{case-fold} in @code{font-lock-defaults} to specify ++the value of @code{font-lock-keywords-case-fold-search} which says ++whether search-based fontification should be case-insensitive. ++ ++@defvar font-lock-keywords-case-fold-search ++Non-@code{nil} means that regular expression matching for the sake of ++@code{font-lock-keywords} should be case-insensitive. ++@end defvar ++ ++@node Customizing Keywords ++@subsection Customizing Search-Based Fontification ++ ++ You can use @code{font-lock-add-keywords} to add additional ++search-based fontification rules to a major mode, and ++@code{font-lock-remove-keywords} to remove rules. ++ ++@defun font-lock-add-keywords mode keywords &optional how ++This function adds highlighting @var{keywords}, for the current buffer ++or for major mode @var{mode}. The argument @var{keywords} should be a ++list with the same format as the variable @code{font-lock-keywords}. ++ ++If @var{mode} is a symbol which is a major mode command name, such as ++@code{c-mode}, the effect is that enabling Font Lock mode in ++@var{mode} will add @var{keywords} to @code{font-lock-keywords}. ++Calling with a non-@code{nil} value of @var{mode} is correct only in ++your @file{~/.emacs} file. ++ ++If @var{mode} is @code{nil}, this function adds @var{keywords} to ++@code{font-lock-keywords} in the current buffer. This way of calling ++@code{font-lock-add-keywords} is usually used in mode hook functions. ++ ++By default, @var{keywords} are added at the beginning of ++@code{font-lock-keywords}. If the optional argument @var{how} is ++@code{set}, they are used to replace the value of ++@code{font-lock-keywords}. If @var{how} is any other non-@code{nil} ++value, they are added at the end of @code{font-lock-keywords}. ++ ++Some modes provide specialized support you can use in additional ++highlighting patterns. See the variables ++@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, ++and @code{java-font-lock-extra-types}, for example. ++ ++@strong{Warning:} major mode functions must not call ++@code{font-lock-add-keywords} under any circumstances, either directly ++or indirectly, except through their mode hooks. (Doing so would lead ++to incorrect behavior for some minor modes.) They should set up their ++rules for search-based fontification by setting ++@code{font-lock-keywords}. ++@end defun ++ ++@defun font-lock-remove-keywords mode keywords ++This function removes @var{keywords} from @code{font-lock-keywords} ++for the current buffer or for major mode @var{mode}. As in ++@code{font-lock-add-keywords}, @var{mode} should be a major mode ++command name or @code{nil}. All the caveats and requirements for ++@code{font-lock-add-keywords} apply here too. ++@end defun ++ ++ For example, this code ++ ++@smallexample ++(font-lock-add-keywords 'c-mode ++ '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) ++ ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) ++@end smallexample ++ ++@noindent ++adds two fontification patterns for C mode: one to fontify the word ++@samp{FIXME}, even in comments, and another to fontify the words ++@samp{and}, @samp{or} and @samp{not} as keywords. ++ ++@noindent ++That example affects only C mode proper. To add the same patterns to ++C mode @emph{and} all modes derived from it, do this instead: ++ ++@smallexample ++(add-hook 'c-mode-hook ++ (lambda () ++ (font-lock-add-keywords nil ++ '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) ++ ("\\<\\(and\\|or\\|not\\)\\>" . ++ font-lock-keyword-face))))) ++@end smallexample ++ ++@node Other Font Lock Variables ++@subsection Other Font Lock Variables ++ ++ This section describes additional variables that a major mode can ++set by means of @var{other-vars} in @code{font-lock-defaults} ++(@pxref{Font Lock Basics}). ++ ++@defvar font-lock-mark-block-function ++If this variable is non-@code{nil}, it should be a function that is ++called with no arguments, to choose an enclosing range of text for ++refontification for the command @kbd{M-o M-o} ++(@code{font-lock-fontify-block}). ++ ++The function should report its choice by placing the region around it. ++A good choice is a range of text large enough to give proper results, ++but not too large so that refontification becomes slow. Typical values ++are @code{mark-defun} for programming modes or @code{mark-paragraph} for ++textual modes. ++@end defvar ++ ++@defvar font-lock-extra-managed-props ++This variable specifies additional properties (other than ++@code{font-lock-face}) that are being managed by Font Lock mode. It ++is used by @code{font-lock-default-unfontify-region}, which normally ++only manages the @code{font-lock-face} property. If you want Font ++Lock to manage other properties as well, you must specify them in a ++@var{facespec} in @code{font-lock-keywords} as well as add them to ++this list. @xref{Search-based Fontification}. ++@end defvar ++ ++@defvar font-lock-fontify-buffer-function ++Function to use for fontifying the buffer. The default value is ++@code{font-lock-default-fontify-buffer}. ++@end defvar ++ ++@defvar font-lock-unfontify-buffer-function ++Function to use for unfontifying the buffer. This is used when ++turning off Font Lock mode. The default value is ++@code{font-lock-default-unfontify-buffer}. ++@end defvar ++ ++@defvar font-lock-fontify-region-function ++Function to use for fontifying a region. It should take two ++arguments, the beginning and end of the region, and an optional third ++argument @var{verbose}. If @var{verbose} is non-@code{nil}, the ++function should print status messages. The default value is ++@code{font-lock-default-fontify-region}. ++@end defvar ++ ++@defvar font-lock-unfontify-region-function ++Function to use for unfontifying a region. It should take two ++arguments, the beginning and end of the region. The default value is ++@code{font-lock-default-unfontify-region}. ++@end defvar ++ ++@defun jit-lock-register function &optional contextual ++This function tells Font Lock mode to run the Lisp function ++@var{function} any time it has to fontify or refontify part of the ++current buffer. It calls @var{function} before calling the default ++fontification functions, and gives it two arguments, @var{start} and ++@var{end}, which specify the region to be fontified or refontified. ++ ++The optional argument @var{contextual}, if non-@code{nil}, forces Font ++Lock mode to always refontify a syntactically relevant part of the ++buffer, and not just the modified lines. This argument can usually be ++omitted. ++@end defun ++ ++@defun jit-lock-unregister function ++If @var{function} was previously registered as a fontification ++function using @code{jit-lock-register}, this function unregisters it. ++@end defun ++ ++@node Levels of Font Lock ++@subsection Levels of Font Lock ++ ++ Many major modes offer three different levels of fontification. You ++can define multiple levels by using a list of symbols for @var{keywords} ++in @code{font-lock-defaults}. Each symbol specifies one level of ++fontification; it is up to the user to choose one of these levels, ++normally by setting @code{font-lock-maximum-decoration} (@pxref{Font ++Lock,,, emacs, the GNU Emacs Manual}). The chosen level's symbol ++value is used to initialize @code{font-lock-keywords}. ++ ++ Here are the conventions for how to define the levels of ++fontification: ++ ++@itemize @bullet ++@item ++Level 1: highlight function declarations, file directives (such as include or ++import directives), strings and comments. The idea is speed, so only ++the most important and top-level components are fontified. ++ ++@item ++Level 2: in addition to level 1, highlight all language keywords, ++including type names that act like keywords, as well as named constant ++values. The idea is that all keywords (either syntactic or semantic) ++should be fontified appropriately. ++ ++@item ++Level 3: in addition to level 2, highlight the symbols being defined in ++function and variable declarations, and all builtin function names, ++wherever they appear. ++@end itemize ++ ++@node Precalculated Fontification ++@subsection Precalculated Fontification ++ ++ Some major modes such as @code{list-buffers} and @code{occur} ++construct the buffer text programmatically. The easiest way for them ++to support Font Lock mode is to specify the faces of text when they ++insert the text in the buffer. ++ ++ The way to do this is to specify the faces in the text with the ++special text property @code{font-lock-face} (@pxref{Special ++Properties}). When Font Lock mode is enabled, this property controls ++the display, just like the @code{face} property. When Font Lock mode ++is disabled, @code{font-lock-face} has no effect on the display. ++ ++ It is ok for a mode to use @code{font-lock-face} for some text and ++also use the normal Font Lock machinery. But if the mode does not use ++the normal Font Lock machinery, it should not set the variable ++@code{font-lock-defaults}. ++ ++@node Faces for Font Lock ++@subsection Faces for Font Lock ++@cindex faces for font lock ++@cindex font lock faces ++ ++ You can make Font Lock mode use any face, but several faces are ++defined specifically for Font Lock mode. Each of these symbols is both ++a face name, and a variable whose default value is the symbol itself. ++Thus, the default value of @code{font-lock-comment-face} is ++@code{font-lock-comment-face}. This means you can write ++@code{font-lock-comment-face} in a context such as ++@code{font-lock-keywords} where a face-name-valued expression is used. ++ ++@table @code ++@item font-lock-comment-face ++@vindex font-lock-comment-face ++Used (typically) for comments. ++ ++@item font-lock-comment-delimiter-face ++@vindex font-lock-comment-delimiter-face ++Used (typically) for comments delimiters. ++ ++@item font-lock-doc-face ++@vindex font-lock-doc-face ++Used (typically) for documentation strings in the code. ++ ++@item font-lock-string-face ++@vindex font-lock-string-face ++Used (typically) for string constants. ++ ++@item font-lock-keyword-face ++@vindex font-lock-keyword-face ++Used (typically) for keywords---names that have special syntactic ++significance, like @code{for} and @code{if} in C. ++ ++@item font-lock-builtin-face ++@vindex font-lock-builtin-face ++Used (typically) for built-in function names. ++ ++@item font-lock-function-name-face ++@vindex font-lock-function-name-face ++Used (typically) for the name of a function being defined or declared, ++in a function definition or declaration. ++ ++@item font-lock-variable-name-face ++@vindex font-lock-variable-name-face ++Used (typically) for the name of a variable being defined or declared, ++in a variable definition or declaration. ++ ++@item font-lock-type-face ++@vindex font-lock-type-face ++Used (typically) for names of user-defined data types, ++where they are defined and where they are used. ++ ++@item font-lock-constant-face ++@vindex font-lock-constant-face ++Used (typically) for constant names. ++ ++@item font-lock-preprocessor-face ++@vindex font-lock-preprocessor-face ++Used (typically) for preprocessor commands. ++ ++@item font-lock-negation-char-face ++@vindex font-lock-negation-char-face ++Used (typically) for easily-overlooked negation characters. ++ ++@item font-lock-warning-face ++@vindex font-lock-warning-face ++Used (typically) for constructs that are peculiar, or that greatly ++change the meaning of other text. For example, this is used for ++@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error} ++directives in C. ++@end table ++ ++@node Syntactic Font Lock ++@subsection Syntactic Font Lock ++@cindex syntactic font lock ++ ++Syntactic fontification uses the syntax table to find comments and ++string constants (@pxref{Syntax Tables}). It highlights them using ++@code{font-lock-comment-face} and @code{font-lock-string-face} ++(@pxref{Faces for Font Lock}), or whatever ++@code{font-lock-syntactic-face-function} chooses. There are several ++variables that affect syntactic fontification; you should set them by ++means of @code{font-lock-defaults} (@pxref{Font Lock Basics}). ++ ++@defvar font-lock-keywords-only ++Non-@code{nil} means Font Lock should not do syntactic fontification; ++it should only fontify based on @code{font-lock-keywords}. The normal ++way for a mode to set this variable to @code{t} is with ++@var{keywords-only} in @code{font-lock-defaults}. ++@end defvar ++ ++@defvar font-lock-syntax-table ++This variable holds the syntax table to use for fontification of ++comments and strings. Specify it using @var{syntax-alist} in ++@code{font-lock-defaults}. If this is @code{nil}, fontification uses ++the buffer's syntax table. ++@end defvar ++ ++@defvar font-lock-beginning-of-syntax-function ++If this variable is non-@code{nil}, it should be a function to move ++point back to a position that is syntactically at ``top level'' and ++outside of strings or comments. Font Lock uses this when necessary ++to get the right results for syntactic fontification. ++ ++This function is called with no arguments. It should leave point at ++the beginning of any enclosing syntactic block. Typical values are ++@code{beginning-of-line} (used when the start of the line is known to ++be outside a syntactic block), or @code{beginning-of-defun} for ++programming modes, or @code{backward-paragraph} for textual modes. ++ ++If the value is @code{nil}, Font Lock uses ++@code{syntax-begin-function} to move back outside of any comment, ++string, or sexp. This variable is semi-obsolete; we recommend setting ++@code{syntax-begin-function} instead. ++ ++Specify this variable using @var{syntax-begin} in ++@code{font-lock-defaults}. ++@end defvar ++ ++@defvar font-lock-syntactic-face-function ++A function to determine which face to use for a given syntactic ++element (a string or a comment). The function is called with one ++argument, the parse state at point returned by ++@code{parse-partial-sexp}, and should return a face. The default ++value returns @code{font-lock-comment-face} for comments and ++@code{font-lock-string-face} for strings. ++ ++This can be used to highlighting different kinds of strings or ++comments differently. It is also sometimes abused together with ++@code{font-lock-syntactic-keywords} to highlight constructs that span ++multiple lines, but this is too esoteric to document here. ++ ++Specify this variable using @var{other-vars} in ++@code{font-lock-defaults}. ++@end defvar ++ ++@node Setting Syntax Properties ++@subsection Setting Syntax Properties ++ ++ Font Lock mode can be used to update @code{syntax-table} properties ++automatically (@pxref{Syntax Properties}). This is useful in ++languages for which a single syntax table by itself is not sufficient. ++ ++@defvar font-lock-syntactic-keywords ++This variable enables and controls updating @code{syntax-table} ++properties by Font Lock. Its value should be a list of elements of ++this form: ++ ++@example ++(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch}) ++@end example ++ ++The parts of this element have the same meanings as in the corresponding ++sort of element of @code{font-lock-keywords}, ++ ++@example ++(@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch}) ++@end example ++ ++However, instead of specifying the value @var{facespec} to use for the ++@code{face} property, it specifies the value @var{syntax} to use for ++the @code{syntax-table} property. Here, @var{syntax} can be a string ++(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell ++(as returned by @code{string-to-syntax}), or an expression whose value ++is one of those two types. @var{override} cannot be @code{prepend} or ++@code{append}. ++ ++For example, an element of the form: ++ ++@example ++("\\$\\(#\\)" 1 ".") ++@end example ++ ++highlights syntactically a hash character when following a dollar ++character, with a SYNTAX of @code{"."} (meaning punctuation syntax). ++Assuming that the buffer syntax table specifies hash characters to ++have comment start syntax, the element will only highlight hash ++characters that do not follow dollar characters as comments ++syntactically. ++ ++An element of the form: ++ ++@example ++ ("\\('\\).\\('\\)" ++ (1 "\"") ++ (2 "\"")) ++@end example ++ ++highlights syntactically both single quotes which surround a single ++character, with a SYNTAX of @code{"\""} (meaning string quote syntax). ++Assuming that the buffer syntax table does not specify single quotes ++to have quote syntax, the element will only highlight single quotes of ++the form @samp{'@var{c}'} as strings syntactically. Other forms, such ++as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as ++strings. ++ ++Major modes normally set this variable with @var{other-vars} in ++@code{font-lock-defaults}. ++@end defvar ++ ++@node Multiline Font Lock ++@subsection Multiline Font Lock Constructs ++@cindex multiline font lock ++ ++ Normally, elements of @code{font-lock-keywords} should not match ++across multiple lines; that doesn't work reliably, because Font Lock ++usually scans just part of the buffer, and it can miss a multi-line ++construct that crosses the line boundary where the scan starts. (The ++scan normally starts at the beginning of a line.) ++ ++ Making elements that match multiline constructs work properly has ++two aspects: correct @emph{identification} and correct ++@emph{rehighlighting}. The first means that Font Lock finds all ++multiline constructs. The second means that Font Lock will correctly ++rehighlight all the relevant text when a multiline construct is ++changed---for example, if some of the text that was previously part of ++a multiline construct ceases to be part of it. The two aspects are ++closely related, and often getting one of them to work will appear to ++make the other also work. However, for reliable results you must ++attend explicitly to both aspects. ++ ++ There are three ways to ensure correct identification of multiline ++constructs: ++ ++@itemize ++@item ++Add a function to @code{font-lock-extend-region-functions} that does ++the @emph{identification} and extends the scan so that the scanned ++text never starts or ends in the middle of a multiline construct. ++@item ++Use the @code{font-lock-fontify-region-function} hook similarly to ++extend the scan so that the scanned text never starts or ends in the ++middle of a multiline construct. ++@item ++Somehow identify the multiline construct right when it gets inserted ++into the buffer (or at any point after that but before font-lock ++tries to highlight it), and mark it with a @code{font-lock-multiline} ++which will instruct font-lock not to start or end the scan in the ++middle of the construct. ++@end itemize ++ ++ There are three ways to do rehighlighting of multiline constructs: ++ ++@itemize ++@item ++Place a @code{font-lock-multiline} property on the construct. This ++will rehighlight the whole construct if any part of it is changed. In ++some cases you can do this automatically by setting the ++@code{font-lock-multiline} variable, which see. ++@item ++Make sure @code{jit-lock-contextually} is set and rely on it doing its ++job. This will only rehighlight the part of the construct that ++follows the actual change, and will do it after a short delay. ++This only works if the highlighting of the various parts of your ++multiline construct never depends on text in subsequent lines. ++Since @code{jit-lock-contextually} is activated by default, this can ++be an attractive solution. ++@item ++Place a @code{jit-lock-defer-multiline} property on the construct. ++This works only if @code{jit-lock-contextually} is used, and with the ++same delay before rehighlighting, but like @code{font-lock-multiline}, ++it also handles the case where highlighting depends on ++subsequent lines. ++@end itemize ++ ++@menu ++* Font Lock Multiline:: Marking multiline chunks with a text property. ++* Region to Fontify:: Controlling which region gets refontified ++ after a buffer change. ++@end menu ++ ++@node Font Lock Multiline ++@subsubsection Font Lock Multiline ++ ++ One way to ensure reliable rehighlighting of multiline Font Lock ++constructs is to put on them the text property @code{font-lock-multiline}. ++It should be present and non-@code{nil} for text that is part of a ++multiline construct. ++ ++ When Font Lock is about to highlight a range of text, it first ++extends the boundaries of the range as necessary so that they do not ++fall within text marked with the @code{font-lock-multiline} property. ++Then it removes any @code{font-lock-multiline} properties from the ++range, and highlights it. The highlighting specification (mostly ++@code{font-lock-keywords}) must reinstall this property each time, ++whenever it is appropriate. ++ ++ @strong{Warning:} don't use the @code{font-lock-multiline} property ++on large ranges of text, because that will make rehighlighting slow. ++ ++@defvar font-lock-multiline ++If the @code{font-lock-multiline} variable is set to @code{t}, Font ++Lock will try to add the @code{font-lock-multiline} property ++automatically on multiline constructs. This is not a universal ++solution, however, since it slows down Font Lock somewhat. It can ++miss some multiline constructs, or make the property larger or smaller ++than necessary. ++ ++For elements whose @var{matcher} is a function, the function should ++ensure that submatch 0 covers the whole relevant multiline construct, ++even if only a small subpart will be highlighted. It is often just as ++easy to add the @code{font-lock-multiline} property by hand. ++@end defvar ++ ++ The @code{font-lock-multiline} property is meant to ensure proper ++refontification; it does not automatically identify new multiline ++constructs. Identifying the requires that Font-Lock operate on large ++enough chunks at a time. This will happen by accident on many cases, ++which may give the impression that multiline constructs magically work. ++If you set the @code{font-lock-multiline} variable non-@code{nil}, ++this impression will be even stronger, since the highlighting of those ++constructs which are found will be properly updated from then on. ++But that does not work reliably. ++ ++ To find multiline constructs reliably, you must either manually ++place the @code{font-lock-multiline} property on the text before ++Font-Lock looks at it, or use ++@code{font-lock-fontify-region-function}. ++ ++@node Region to Fontify ++@subsubsection Region to Fontify after a Buffer Change ++ ++ When a buffer is changed, the region that Font Lock refontifies is ++by default the smallest sequence of whole lines that spans the change. ++While this works well most of the time, sometimes it doesn't---for ++example, when a change alters the syntactic meaning of text on an ++earlier line. ++ ++ You can enlarge (or even reduce) the region to fontify by setting ++one the following variables: ++ ++@defvar font-lock-extend-after-change-region-function ++This buffer-local variable is either @code{nil} or a function for ++Font-Lock to call to determine the region to scan and fontify. ++ ++The function is given three parameters, the standard @var{beg}, ++@var{end}, and @var{old-len} from after-change-functions ++(@pxref{Change Hooks}). It should return either a cons of the ++beginning and end buffer positions (in that order) of the region to ++fontify, or @code{nil} (which means choose the region in the standard ++way). This function needs to preserve point, the match-data, and the ++current restriction. The region it returns may start or end in the ++middle of a line. ++ ++Since this function is called after every buffer change, it should be ++reasonably fast. ++@end defvar ++ ++@node Desktop Save Mode ++@section Desktop Save Mode ++@cindex desktop save mode ++ ++@dfn{Desktop Save Mode} is a feature to save the state of Emacs from ++one session to another. The user-level commands for using Desktop ++Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs ++Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit ++a file, don't have to do anything to use this feature. ++ ++For buffers not visiting a file to have their state saved, the major ++mode must bind the buffer local variable @code{desktop-save-buffer} to ++a non-@code{nil} value. ++ ++@defvar desktop-save-buffer ++If this buffer-local variable is non-@code{nil}, the buffer will have ++its state saved in the desktop file at desktop save. If the value is ++a function, it is called at desktop save with argument ++@var{desktop-dirname}, and its value is saved in the desktop file along ++with the state of the buffer for which it was called. When file names ++are returned as part of the auxiliary information, they should be ++formatted using the call ++ ++@example ++(desktop-file-name @var{file-name} @var{desktop-dirname}) ++@end example ++ ++@end defvar ++ ++For buffers not visiting a file to be restored, the major mode must ++define a function to do the job, and that function must be listed in ++the alist @code{desktop-buffer-mode-handlers}. ++ ++@defvar desktop-buffer-mode-handlers ++Alist with elements ++ ++@example ++(@var{major-mode} . @var{restore-buffer-function}) ++@end example ++ ++The function @var{restore-buffer-function} will be called with ++argument list ++ ++@example ++(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc}) ++@end example ++ ++and it should return the restored buffer. ++Here @var{desktop-buffer-misc} is the value returned by the function ++optionally bound to @code{desktop-save-buffer}. ++@end defvar ++ ++@ignore ++ arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e ++@end ignore +diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi +new file mode 100644 +index 0000000..870c028 +--- /dev/null ++++ b/doc/lispref/nonascii.texi +@@ -0,0 +1,1924 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, ++@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/characters ++@node Non-ASCII Characters, Searching and Matching, Text, Top ++@chapter Non-@acronym{ASCII} Characters ++@cindex multibyte characters ++@cindex characters, multi-byte ++@cindex non-@acronym{ASCII} characters ++ ++ This chapter covers the special issues relating to characters and ++how they are stored in strings and buffers. ++ ++@menu ++* Text Representations:: How Emacs represents text. ++* Converting Representations:: Converting unibyte to multibyte and vice versa. ++* Selecting a Representation:: Treating a byte sequence as unibyte or multi. ++* Character Codes:: How unibyte and multibyte relate to ++ codes of individual characters. ++* Character Properties:: Character attributes that define their ++ behavior and handling. ++* Character Sets:: The space of possible character codes ++ is divided into various character sets. ++* Scanning Charsets:: Which character sets are used in a buffer? ++* Translation of Characters:: Translation tables are used for conversion. ++* Coding Systems:: Coding systems are conversions for saving files. ++* Input Methods:: Input methods allow users to enter various ++ non-ASCII characters without special keyboards. ++* Locales:: Interacting with the POSIX locale. ++@end menu ++ ++@node Text Representations ++@section Text Representations ++@cindex text representation ++ ++ Emacs buffers and strings support a large repertoire of characters ++from many different scripts, allowing users to type and display text ++in most any known written language. ++ ++@cindex character codepoint ++@cindex codespace ++@cindex Unicode ++ To support this multitude of characters and scripts, Emacs closely ++follows the @dfn{Unicode Standard}. The Unicode Standard assigns a ++unique number, called a @dfn{codepoint}, to each and every character. ++The range of codepoints defined by Unicode, or the Unicode ++@dfn{codespace}, is @code{0..10FFFF} (in hex), inclusive. Emacs ++extends this range with codepoints in the range @code{110000..3FFFFF}, ++which it uses for representing characters that are not unified with ++Unicode and raw 8-bit bytes that cannot be interpreted as characters ++(the latter occupy the range @code{3FFF80..3FFFFF}). Thus, a ++character codepoint in Emacs is a 22-bit integer number. ++ ++@cindex internal representation of characters ++@cindex characters, representation in buffers and strings ++@cindex multibyte text ++ To conserve memory, Emacs does not hold fixed-length 22-bit numbers ++that are codepoints of text characters within buffers and strings. ++Rather, Emacs uses a variable-length internal representation of ++characters, that stores each character as a sequence of 1 to 5 8-bit ++bytes, depending on the magnitude of its codepoint@footnote{ ++This internal representation is based on one of the encodings defined ++by the Unicode Standard, called @dfn{UTF-8}, for representing any ++Unicode codepoint, but Emacs extends UTF-8 to represent the additional ++codepoints it uses for raw 8-bit bytes and characters not unified with ++Unicode.}. For example, any @acronym{ASCII} character takes up only 1 ++byte, a Latin-1 character takes up 2 bytes, etc. We call this ++representation of text @dfn{multibyte}. ++ ++ Outside Emacs, characters can be represented in many different ++encodings, such as ISO-8859-1, GB-2312, Big-5, etc. Emacs converts ++between these external encodings and its internal representation, as ++appropriate, when it reads text into a buffer or a string, or when it ++writes text to a disk file or passes it to some other process. ++ ++ Occasionally, Emacs needs to hold and manipulate encoded text or ++binary non-text data in its buffers or strings. For example, when ++Emacs visits a file, it first reads the file's text verbatim into a ++buffer, and only then converts it to the internal representation. ++Before the conversion, the buffer holds encoded text. ++ ++@cindex unibyte text ++ Encoded text is not really text, as far as Emacs is concerned, but ++rather a sequence of raw 8-bit bytes. We call buffers and strings ++that hold encoded text @dfn{unibyte} buffers and strings, because ++Emacs treats them as a sequence of individual bytes. Usually, Emacs ++displays unibyte buffers and strings as octal codes such as ++@code{\237}. We recommend that you never use unibyte buffers and ++strings except for manipulating encoded text or binary non-text data. ++ ++ In a buffer, the buffer-local value of the variable ++@code{enable-multibyte-characters} specifies the representation used. ++The representation for a string is determined and recorded in the string ++when the string is constructed. ++ ++@defopt enable-multibyte-characters ++This variable specifies the current buffer's text representation. ++If it is non-@code{nil}, the buffer contains multibyte text; otherwise, ++it contains unibyte encoded text or binary non-text data. ++ ++You cannot set this variable directly; instead, use the function ++@code{set-buffer-multibyte} to change a buffer's representation. ++@end defopt ++ ++@defvar default-enable-multibyte-characters ++This variable's value is entirely equivalent to @code{(default-value ++'enable-multibyte-characters)}, and setting this variable changes that ++default value. Setting the local binding of ++@code{enable-multibyte-characters} in a specific buffer is not allowed, ++but changing the default value is supported, and it is a reasonable ++thing to do, because it has no effect on existing buffers. ++ ++The @samp{--unibyte} command line option does its job by setting the ++default value to @code{nil} early in startup. ++@end defvar ++ ++@defun position-bytes position ++Buffer positions are measured in character units. This function ++returns the byte-position corresponding to buffer position ++@var{position} in the current buffer. This is 1 at the start of the ++buffer, and counts upward in bytes. If @var{position} is out of ++range, the value is @code{nil}. ++@end defun ++ ++@defun byte-to-position byte-position ++Return the buffer position, in character units, corresponding to given ++@var{byte-position} in the current buffer. If @var{byte-position} is ++out of range, the value is @code{nil}. In a multibyte buffer, an ++arbitrary value of @var{byte-position} can be not at character ++boundary, but inside a multibyte sequence representing a single ++character; in this case, this function returns the buffer position of ++the character whose multibyte sequence includes @var{byte-position}. ++In other words, the value does not change for all byte positions that ++belong to the same character. ++@end defun ++ ++@defun multibyte-string-p string ++Return @code{t} if @var{string} is a multibyte string, @code{nil} ++otherwise. ++@end defun ++ ++@defun string-bytes string ++@cindex string, number of bytes ++This function returns the number of bytes in @var{string}. ++If @var{string} is a multibyte string, this can be greater than ++@code{(length @var{string})}. ++@end defun ++ ++@defun unibyte-string &rest bytes ++This function concatenates all its argument @var{bytes} and makes the ++result a unibyte string. ++@end defun ++ ++@node Converting Representations ++@section Converting Text Representations ++ ++ Emacs can convert unibyte text to multibyte; it can also convert ++multibyte text to unibyte, provided that the multibyte text contains ++only @acronym{ASCII} and 8-bit raw bytes. In general, these ++conversions happen when inserting text into a buffer, or when putting ++text from several strings together in one string. You can also ++explicitly convert a string's contents to either representation. ++ ++ Emacs chooses the representation for a string based on the text from ++which it is constructed. The general rule is to convert unibyte text ++to multibyte text when combining it with other multibyte text, because ++the multibyte representation is more general and can hold whatever ++characters the unibyte text has. ++ ++ When inserting text into a buffer, Emacs converts the text to the ++buffer's representation, as specified by ++@code{enable-multibyte-characters} in that buffer. In particular, when ++you insert multibyte text into a unibyte buffer, Emacs converts the text ++to unibyte, even though this conversion cannot in general preserve all ++the characters that might be in the multibyte text. The other natural ++alternative, to convert the buffer contents to multibyte, is not ++acceptable because the buffer's representation is a choice made by the ++user that cannot be overridden automatically. ++ ++ Converting unibyte text to multibyte text leaves @acronym{ASCII} ++characters unchanged, and converts bytes with codes 128 through 159 to ++the multibyte representation of raw eight-bit bytes. ++ ++ Converting multibyte text to unibyte converts all @acronym{ASCII} ++and eight-bit characters to their single-byte form, but loses ++information for non-@acronym{ASCII} characters by discarding all but ++the low 8 bits of each character's codepoint. Converting unibyte text ++to multibyte and back to unibyte reproduces the original unibyte text. ++ ++The next two functions either return the argument @var{string}, or a ++newly created string with no text properties. ++ ++@defun string-to-multibyte string ++This function returns a multibyte string containing the same sequence ++of characters as @var{string}. If @var{string} is a multibyte string, ++it is returned unchanged. The function assumes that @var{string} ++includes only @acronym{ASCII} characters and raw 8-bit bytes; the ++latter are converted to their multibyte representation corresponding ++to the codepoints in the @code{3FFF80..3FFFFF} area (@pxref{Text ++Representations, codepoints}). ++@end defun ++ ++@defun string-to-unibyte string ++This function returns a unibyte string containing the same sequence of ++characters as @var{string}. It signals an error if @var{string} ++contains a non-@acronym{ASCII} character. If @var{string} is a ++unibyte string, it is returned unchanged. Use this function for ++@var{string} arguments that contain only @acronym{ASCII} and eight-bit ++characters. ++@end defun ++ ++@defun multibyte-char-to-unibyte char ++This converts the multibyte character @var{char} to a unibyte ++character, and returns that character. If @var{char} is neither ++@acronym{ASCII} nor eight-bit, the function returns -1. ++@end defun ++ ++@defun unibyte-char-to-multibyte char ++This convert the unibyte character @var{char} to a multibyte ++character, assuming @var{char} is either @acronym{ASCII} or raw 8-bit ++byte. ++@end defun ++ ++@node Selecting a Representation ++@section Selecting a Representation ++ ++ Sometimes it is useful to examine an existing buffer or string as ++multibyte when it was unibyte, or vice versa. ++ ++@defun set-buffer-multibyte multibyte ++Set the representation type of the current buffer. If @var{multibyte} ++is non-@code{nil}, the buffer becomes multibyte. If @var{multibyte} ++is @code{nil}, the buffer becomes unibyte. ++ ++This function leaves the buffer contents unchanged when viewed as a ++sequence of bytes. As a consequence, it can change the contents ++viewed as characters; for instance, a sequence of three bytes which is ++treated as one character in multibyte representation will count as ++three characters in unibyte representation. Eight-bit characters ++representing raw bytes are an exception. They are represented by one ++byte in a unibyte buffer, but when the buffer is set to multibyte, ++they are converted to two-byte sequences, and vice versa. ++ ++This function sets @code{enable-multibyte-characters} to record which ++representation is in use. It also adjusts various data in the buffer ++(including overlays, text properties and markers) so that they cover the ++same text as they did before. ++ ++You cannot use @code{set-buffer-multibyte} on an indirect buffer, ++because indirect buffers always inherit the representation of the ++base buffer. ++@end defun ++ ++@defun string-as-unibyte string ++If @var{string} is already a unibyte string, this function returns ++@var{string} itself. Otherwise, it returns a new string with the same ++bytes as @var{string}, but treating each byte as a separate character ++(so that the value may have more characters than @var{string}); as an ++exception, each eight-bit character representing a raw byte is ++converted into a single byte. The newly-created string contains no ++text properties. ++@end defun ++ ++@defun string-as-multibyte string ++If @var{string} is a multibyte string, this function returns ++@var{string} itself. Otherwise, it returns a new string with the same ++bytes as @var{string}, but treating each multibyte sequence as one ++character. This means that the value may have fewer characters than ++@var{string} has. If a byte sequence in @var{string} is invalid as a ++multibyte representation of a single character, each byte in the ++sequence is treated as a raw 8-bit byte. The newly-created string ++contains no text properties. ++@end defun ++ ++@node Character Codes ++@section Character Codes ++@cindex character codes ++ ++ The unibyte and multibyte text representations use different ++character codes. The valid character codes for unibyte representation ++range from 0 to 255---the values that can fit in one byte. The valid ++character codes for multibyte representation range from 0 to 4194303 ++(#x3FFFFF). In this code space, values 0 through 127 are for ++@acronym{ASCII} charcters, and values 129 through 4194175 (#x3FFF7F) ++are for non-@acronym{ASCII} characters. Values 0 through 1114111 ++(#10FFFF) correspond to Unicode characters of the same codepoint; ++values 1114112 (#110000) through 4194175 (#x3FFF7F) represent ++characters that are not unified with Unicode; and values 4194176 ++(#x3FFF80) through 4194303 (#x3FFFFF) represent eight-bit raw bytes. ++ ++@defun characterp charcode ++This returns @code{t} if @var{charcode} is a valid character, and ++@code{nil} otherwise. ++ ++@example ++@group ++(characterp 65) ++ @result{} t ++@end group ++@group ++(characterp 4194303) ++ @result{} t ++@end group ++@group ++(characterp 4194304) ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@cindex maximum value of character codepoint ++@cindex codepoint, largest value ++@defun max-char ++This function returns the largest value that a valid character ++codepoint can have. ++ ++@example ++@group ++(characterp (max-char)) ++ @result{} t ++@end group ++@group ++(characterp (1+ (max-char))) ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun get-byte &optional pos string ++This function returns the byte at character position @var{pos} in the ++current buffer. If the current buffer is unibyte, this is literally ++the byte at that position. If the buffer is multibyte, byte values of ++@acronym{ASCII} characters are the same as character codepoints, ++whereas eight-bit raw bytes are converted to their 8-bit codes. The ++function signals an error if the character at @var{pos} is ++non-@acronym{ASCII}. ++ ++The optional argument @var{string} means to get a byte value from that ++string instead of the current buffer. ++@end defun ++ ++@node Character Properties ++@section Character Properties ++@cindex character properties ++A @dfn{character property} is a named attribute of a character that ++specifies how the character behaves and how it should be handled ++during text processing and display. Thus, character properties are an ++important part of specifying the character's semantics. ++ ++ On the whole, Emacs follows the Unicode Standard in its implementation ++of character properties. In particular, Emacs supports the ++@uref{http://www.unicode.org/reports/tr23/, Unicode Character Property ++Model}, and the Emacs character property database is derived from the ++Unicode Character Database (@acronym{UCD}). See the ++@uref{http://www.unicode.org/versions/Unicode5.0.0/ch04.pdf, Character ++Properties chapter of the Unicode Standard}, for a detailed ++description of Unicode character properties and their meaning. This ++section assumes you are already familiar with that chapter of the ++Unicode Standard, and want to apply that knowledge to Emacs Lisp ++programs. ++ ++ In Emacs, each property has a name, which is a symbol, and a set of ++possible values, whose types depend on the property; if a character ++does not have a certain property, the value is @code{nil}. As a ++general rule, the names of character properties in Emacs are produced ++from the corresponding Unicode properties by downcasing them and ++replacing each @samp{_} character with a dash @samp{-}. For example, ++@code{Canonical_Combining_Class} becomes ++@code{canonical-combining-class}. However, sometimes we shorten the ++names to make their use easier. ++ ++ Here is the full list of value types for all the character ++properties that Emacs knows about: ++ ++@table @code ++@item name ++This property corresponds to the Unicode @code{Name} property. The ++value is a string consisting of upper-case Latin letters A to Z, ++digits, spaces, and hyphen @samp{-} characters. ++ ++@item general-category ++This property corresponds to the Unicode @code{General_Category} ++property. The value is a symbol whose name is a 2-letter abbreviation ++of the character's classification. ++ ++@item canonical-combining-class ++Corresponds to the Unicode @code{Canonical_Combining_Class} property. ++The value is an integer number. ++ ++@item bidi-class ++Corresponds to the Unicode @code{Bidi_Class} property. The value is a ++symbol whose name is the Unicode @dfn{directional type} of the ++character. ++ ++@item decomposition ++Corresponds to the Unicode @code{Decomposition_Type} and ++@code{Decomposition_Value} properties. The value is a list, whose ++first element may be a symbol representing a compatibility formatting ++tag, such as @code{small}@footnote{ ++Note that the Unicode spec writes these tag names inside ++@samp{<..>} brackets. The tag names in Emacs do not include the ++brackets; e.g., Unicode specifies @samp{} where Emacs uses ++@samp{small}. ++}; the other elements are characters that give the compatibility ++decomposition sequence of this character. ++ ++@item decimal-digit-value ++Corresponds to the Unicode @code{Numeric_Value} property for ++characters whose @code{Numeric_Type} is @samp{Digit}. The value is an ++integer number. ++ ++@item digit ++Corresponds to the Unicode @code{Numeric_Value} property for ++characters whose @code{Numeric_Type} is @samp{Decimal}. The value is ++an integer number. Examples of such characters include compatibility ++subscript and superscript digits, for which the value is the ++corresponding number. ++ ++@item numeric-value ++Corresponds to the Unicode @code{Numeric_Value} property for ++characters whose @code{Numeric_Type} is @samp{Numeric}. The value of ++this property is an integer or a floating-point number. Examples of ++characters that have this property include fractions, subscripts, ++superscripts, Roman numerals, currency numerators, and encircled ++numbers. For example, the value of this property for the character ++@code{U+2155} (@sc{vulgar fraction one fifth}) is @code{0.2}. ++ ++@item mirrored ++Corresponds to the Unicode @code{Bidi_Mirrored} property. The value ++of this property is a symbol, either @code{Y} or @code{N}. ++ ++@item old-name ++Corresponds to the Unicode @code{Unicode_1_Name} property. The value ++is a string. ++ ++@item iso-10646-comment ++Corresponds to the Unicode @code{ISO_Comment} property. The value is ++a string. ++ ++@item uppercase ++Corresponds to the Unicode @code{Simple_Uppercase_Mapping} property. ++The value of this property is a single character. ++ ++@item lowercase ++Corresponds to the Unicode @code{Simple_Lowercase_Mapping} property. ++The value of this property is a single character. ++ ++@item titlecase ++Corresponds to the Unicode @code{Simple_Titlecase_Mapping} property. ++@dfn{Title case} is a special form of a character used when the first ++character of a word needs to be capitalized. The value of this ++property is a single character. ++@end table ++ ++@defun get-char-code-property char propname ++This function returns the value of @var{char}'s @var{propname} property. ++ ++@example ++@group ++(get-char-code-property ? 'general-category) ++ @result{} Zs ++@end group ++@group ++(get-char-code-property ?1 'general-category) ++ @result{} Nd ++@end group ++@group ++(get-char-code-property ?\u2084 'digit-value) ; subscript 4 ++ @result{} 4 ++@end group ++@group ++(get-char-code-property ?\u2155 'numeric-value) ; one fifth ++ @result{} 1/5 ++@end group ++@group ++(get-char-code-property ?\u2163 'numeric-value) ; Roman IV ++ @result{} \4 ++@end group ++@end example ++@end defun ++ ++@defun char-code-property-description prop value ++This function returns the description string of property @var{prop}'s ++@var{value}, or @code{nil} if @var{value} has no description. ++ ++@example ++@group ++(char-code-property-description 'general-category 'Zs) ++ @result{} "Separator, Space" ++@end group ++@group ++(char-code-property-description 'general-category 'Nd) ++ @result{} "Number, Decimal Digit" ++@end group ++@group ++(char-code-property-description 'numeric-value '1/5) ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun put-char-code-property char propname value ++This function stores @var{value} as the value of the property ++@var{propname} for the character @var{char}. ++@end defun ++ ++@defvar char-script-table ++The value of this variable is a char-table (@pxref{Char-Tables}) that ++specifies, for each character, a symbol whose name is the script to ++which the character belongs, according to the Unicode Standard ++classification of the Unicode code space into script-specific blocks. ++This char-table has a single extra slot whose value is the list of all ++script symbols. ++@end defvar ++ ++@defvar char-width-table ++The value of this variable is a char-table that specifies the width of ++each character in columns that it will occupy on the screen. ++@end defvar ++ ++@defvar printable-chars ++The value of this variable is a char-table that specifies, for each ++character, whether it is printable or not. That is, if evaluating ++@code{(aref printable-chars char)} results in @code{t}, the character ++is printable, and if it results in @code{nil}, it is not. ++@end defvar ++ ++@node Character Sets ++@section Character Sets ++@cindex character sets ++ ++@cindex charset ++@cindex coded character set ++An Emacs @dfn{character set}, or @dfn{charset}, is a set of characters ++in which each character is assigned a numeric code point. (The ++Unicode Standard calls this a @dfn{coded character set}.) Each Emacs ++charset has a name which is a symbol. A single character can belong ++to any number of different character sets, but it will generally have ++a different code point in each charset. Examples of character sets ++include @code{ascii}, @code{iso-8859-1}, @code{greek-iso8859-7}, and ++@code{windows-1255}. The code point assigned to a character in a ++charset is usually different from its code point used in Emacs buffers ++and strings. ++ ++@cindex @code{emacs}, a charset ++@cindex @code{unicode}, a charset ++@cindex @code{eight-bit}, a charset ++ Emacs defines several special character sets. The character set ++@code{unicode} includes all the characters whose Emacs code points are ++in the range @code{0..10FFFF}. The character set @code{emacs} ++includes all @acronym{ASCII} and non-@acronym{ASCII} characters. ++Finally, the @code{eight-bit} charset includes the 8-bit raw bytes; ++Emacs uses it to represent raw bytes encountered in text. ++ ++@defun charsetp object ++Returns @code{t} if @var{object} is a symbol that names a character set, ++@code{nil} otherwise. ++@end defun ++ ++@defvar charset-list ++The value is a list of all defined character set names. ++@end defvar ++ ++@defun charset-priority-list &optional highestp ++This functions returns a list of all defined character sets ordered by ++their priority. If @var{highestp} is non-@code{nil}, the function ++returns a single character set of the highest priority. ++@end defun ++ ++@defun set-charset-priority &rest charsets ++This function makes @var{charsets} the highest priority character sets. ++@end defun ++ ++@defun char-charset character &optional restriction ++This function returns the name of the character set of highest ++priority that @var{character} belongs to. @acronym{ASCII} characters ++are an exception: for them, this function always returns @code{ascii}. ++ ++If @var{restriction} is non-@code{nil}, it should be a list of ++charsets to search. Alternatively, it can be a coding system, in ++which case the returned charset must be supported by that coding ++system (@pxref{Coding Systems}). ++@end defun ++ ++@defun charset-plist charset ++This function returns the property list of the character set ++@var{charset}. Although @var{charset} is a symbol, this is not the ++same as the property list of that symbol. Charset properties include ++important information about the charset, such as its documentation ++string, short name, etc. ++@end defun ++ ++@defun put-charset-property charset propname value ++This function sets the @var{propname} property of @var{charset} to the ++given @var{value}. ++@end defun ++ ++@defun get-charset-property charset propname ++This function returns the value of @var{charset}s property ++@var{propname}. ++@end defun ++ ++@deffn Command list-charset-chars charset ++This command displays a list of characters in the character set ++@var{charset}. ++@end deffn ++ ++ Emacs can convert between its internal representation of a character ++and the character's codepoint in a specific charset. The following ++two functions support these conversions. ++ ++@c FIXME: decode-char and encode-char accept and ignore an additional ++@c argument @var{restriction}. When that argument actually makes a ++@c difference, it should be documented here. ++@defun decode-char charset code-point ++This function decodes a character that is assigned a @var{code-point} ++in @var{charset}, to the corresponding Emacs character, and returns ++it. If @var{charset} doesn't contain a character of that code point, ++the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp ++integer (@pxref{Integer Basics, most-positive-fixnum}), it can be ++specified as a cons cell @code{(@var{high} . @var{low})}, where ++@var{low} are the lower 16 bits of the value and @var{high} are the ++high 16 bits. ++@end defun ++ ++@defun encode-char char charset ++This function returns the code point assigned to the character ++@var{char} in @var{charset}. If the result does not fit in a Lisp ++integer, it is returned as a cons cell @code{(@var{high} . @var{low})} ++that fits the second argument of @code{decode-char} above. If ++@var{charset} doesn't have a codepoint for @var{char}, the value is ++@code{nil}. ++@end defun ++ ++ The following function comes in handy for applying a certain ++function to all or part of the characters in a charset: ++ ++@defun map-charset-chars function charset &optional arg from to ++Call @var{function} for characters in @var{charset}. @var{function} ++is called with two arguments. The first one is a cons cell ++@code{(@var{from} . @var{to})}, where @var{from} and @var{to} ++indicate a range of characters contained in charset. The second ++argument is the optional argument @var{arg}. ++ ++By default, the range of codepoints passed to @var{function} includes ++all the characters in @var{charset}, but optional arguments ++@var{from-code} and @var{to-code} limit that to the range of ++characters between these two codepoints of @var{charset}. If either ++of them is @code{nil}, it defaults to the first or last codepoint of ++@var{charset}, respectively. ++@end defun ++ ++@node Scanning Charsets ++@section Scanning for Character Sets ++ ++ Sometimes it is useful to find out which character set a particular ++character belongs to. One use for this is in determining which coding ++systems (@pxref{Coding Systems}) are capable of representing all of ++the text in question; another is to determine the font(s) for ++displaying that text. ++ ++@defun charset-after &optional pos ++This function returns the charset of highest priority containing the ++character at position @var{pos} in the current buffer. If @var{pos} ++is omitted or @code{nil}, it defaults to the current value of point. ++If @var{pos} is out of range, the value is @code{nil}. ++@end defun ++ ++@defun find-charset-region beg end &optional translation ++This function returns a list of the character sets of highest priority ++that contain characters in the current buffer between positions ++@var{beg} and @var{end}. ++ ++The optional argument @var{translation} specifies a translation table ++to use for scanning the text (@pxref{Translation of Characters}). If ++it is non-@code{nil}, then each character in the region is translated ++through this table, and the value returned describes the translated ++characters instead of the characters actually in the buffer. ++@end defun ++ ++@defun find-charset-string string &optional translation ++This function returns a list of character sets of highest priority ++that contain characters in @var{string}. It is just like ++@code{find-charset-region}, except that it applies to the contents of ++@var{string} instead of part of the current buffer. ++@end defun ++ ++@node Translation of Characters ++@section Translation of Characters ++@cindex character translation tables ++@cindex translation tables ++ ++ A @dfn{translation table} is a char-table (@pxref{Char-Tables}) that ++specifies a mapping of characters into characters. These tables are ++used in encoding and decoding, and for other purposes. Some coding ++systems specify their own particular translation tables; there are ++also default translation tables which apply to all other coding ++systems. ++ ++ A translation table has two extra slots. The first is either ++@code{nil} or a translation table that performs the reverse ++translation; the second is the maximum number of characters to look up ++for translating sequences of characters (see the description of ++@code{make-translation-table-from-alist} below). ++ ++@defun make-translation-table &rest translations ++This function returns a translation table based on the argument ++@var{translations}. Each element of @var{translations} should be a ++list of elements of the form @code{(@var{from} . @var{to})}; this says ++to translate the character @var{from} into @var{to}. ++ ++The arguments and the forms in each argument are processed in order, ++and if a previous form already translates @var{to} to some other ++character, say @var{to-alt}, @var{from} is also translated to ++@var{to-alt}. ++@end defun ++ ++ During decoding, the translation table's translations are applied to ++the characters that result from ordinary decoding. If a coding system ++has the property @code{:decode-translation-table}, that specifies the ++translation table to use, or a list of translation tables to apply in ++sequence. (This is a property of the coding system, as returned by ++@code{coding-system-get}, not a property of the symbol that is the ++coding system's name. @xref{Coding System Basics,, Basic Concepts of ++Coding Systems}.) Finally, if ++@code{standard-translation-table-for-decode} is non-@code{nil}, the ++resulting characters are translated by that table. ++ ++ During encoding, the translation table's translations are applied to ++the characters in the buffer, and the result of translation is ++actually encoded. If a coding system has property ++@code{:encode-translation-table}, that specifies the translation table ++to use, or a list of translation tables to apply in sequence. In ++addition, if the variable @code{standard-translation-table-for-encode} ++is non-@code{nil}, it specifies the translation table to use for ++translating the result. ++ ++@defvar standard-translation-table-for-decode ++This is the default translation table for decoding. If a coding ++systems specifies its own translation tables, the table that is the ++value of this variable, if non-@code{nil}, is applied after them. ++@end defvar ++ ++@defvar standard-translation-table-for-encode ++This is the default translation table for encoding. If a coding ++systems specifies its own translation tables, the table that is the ++value of this variable, if non-@code{nil}, is applied after them. ++@end defvar ++ ++@defvar translation-table-for-input ++Self-inserting characters are translated through this translation ++table before they are inserted. Search commands also translate their ++input through this table, so they can compare more reliably with ++what's in the buffer. ++ ++This variable automatically becomes buffer-local when set. ++@end defvar ++ ++@defun make-translation-table-from-vector vec ++This function returns a translation table made from @var{vec} that is ++an array of 256 elements to map byte values 0 through 255 to ++characters. Elements may be @code{nil} for untranslated bytes. The ++returned table has a translation table for reverse mapping in the ++first extra slot, and the value @code{1} in the second extra slot. ++ ++This function provides an easy way to make a private coding system ++that maps each byte to a specific character. You can specify the ++returned table and the reverse translation table using the properties ++@code{:decode-translation-table} and @code{:encode-translation-table} ++respectively in the @var{props} argument to ++@code{define-coding-system}. ++@end defun ++ ++@defun make-translation-table-from-alist alist ++This function is similar to @code{make-translation-table} but returns ++a complex translation table rather than a simple one-to-one mapping. ++Each element of @var{alist} is of the form @code{(@var{from} ++. @var{to})}, where @var{from} and @var{to} are either characters or ++vectors specifying a sequence of characters. If @var{from} is a ++character, that character is translated to @var{to} (i.e.@: to a ++character or a character sequence). If @var{from} is a vector of ++characters, that sequence is translated to @var{to}. The returned ++table has a translation table for reverse mapping in the first extra ++slot, and the maximum length of all the @var{from} character sequences ++in the second extra slot. ++@end defun ++ ++@node Coding Systems ++@section Coding Systems ++ ++@cindex coding system ++ When Emacs reads or writes a file, and when Emacs sends text to a ++subprocess or receives text from a subprocess, it normally performs ++character code conversion and end-of-line conversion as specified ++by a particular @dfn{coding system}. ++ ++ How to define a coding system is an arcane matter, and is not ++documented here. ++ ++@menu ++* Coding System Basics:: Basic concepts. ++* Encoding and I/O:: How file I/O functions handle coding systems. ++* Lisp and Coding Systems:: Functions to operate on coding system names. ++* User-Chosen Coding Systems:: Asking the user to choose a coding system. ++* Default Coding Systems:: Controlling the default choices. ++* Specifying Coding Systems:: Requesting a particular coding system ++ for a single file operation. ++* Explicit Encoding:: Encoding or decoding text without doing I/O. ++* Terminal I/O Encoding:: Use of encoding for terminal I/O. ++* MS-DOS File Types:: How DOS "text" and "binary" files ++ relate to coding systems. ++@end menu ++ ++@node Coding System Basics ++@subsection Basic Concepts of Coding Systems ++ ++@cindex character code conversion ++ @dfn{Character code conversion} involves conversion between the ++internal representation of characters used inside Emacs and some other ++encoding. Emacs supports many different encodings, in that it can ++convert to and from them. For example, it can convert text to or from ++encodings such as Latin 1, Latin 2, Latin 3, Latin 4, Latin 5, and ++several variants of ISO 2022. In some cases, Emacs supports several ++alternative encodings for the same characters; for example, there are ++three coding systems for the Cyrillic (Russian) alphabet: ISO, ++Alternativnyj, and KOI8. ++ ++ Every coding system specifies a particular set of character code ++conversions, but the coding system @code{undecided} is special: it ++leaves the choice unspecified, to be chosen heuristically for each ++file, based on the file's data. ++ ++ In general, a coding system doesn't guarantee roundtrip identity: ++decoding a byte sequence using coding system, then encoding the ++resulting text in the same coding system, can produce a different byte ++sequence. But some coding systems do guarantee that the byte sequence ++will be the same as what you originally decoded. Here are a few ++examples: ++ ++@quotation ++iso-8859-1, utf-8, big5, shift_jis, euc-jp ++@end quotation ++ ++ Encoding buffer text and then decoding the result can also fail to ++reproduce the original text. For instance, if you encode a character ++with a coding system which does not support that character, the result ++is unpredictable, and thus decoding it using the same coding system ++may produce a different text. Currently, Emacs can't report errors ++that result from encoding unsupported characters. ++ ++@cindex EOL conversion ++@cindex end-of-line conversion ++@cindex line end conversion ++ @dfn{End of line conversion} handles three different conventions ++used on various systems for representing end of line in files. The ++Unix convention, used on GNU and Unix systems, is to use the linefeed ++character (also called newline). The DOS convention, used on ++MS-Windows and MS-DOS systems, is to use a carriage-return and a ++linefeed at the end of a line. The Mac convention is to use just ++carriage-return. ++ ++@cindex base coding system ++@cindex variant coding system ++ @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line ++conversion unspecified, to be chosen based on the data. @dfn{Variant ++coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and ++@code{latin-1-mac} specify the end-of-line conversion explicitly as ++well. Most base coding systems have three corresponding variants whose ++names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}. ++ ++@vindex raw-text@r{ coding system} ++ The coding system @code{raw-text} is special in that it prevents ++character code conversion, and causes the buffer visited with this ++coding system to be a unibyte buffer. For historical reasons, you can ++save both unibyte and multibyte text with this coding system. When ++you use @code{raw-text} to encode multibyte text, it does perform one ++character code conversion: it converts eight-bit characters to their ++single-byte external representation. @code{raw-text} does not specify ++the end-of-line conversion, allowing that to be determined as usual by ++the data, and has the usual three variants which specify the ++end-of-line conversion. ++ ++@vindex no-conversion@r{ coding system} ++@vindex binary@r{ coding system} ++ @code{no-conversion} (and its alias @code{binary}) is equivalent to ++@code{raw-text-unix}: it specifies no conversion of either character ++codes or end-of-line. ++ ++@vindex emacs-internal@r{ coding system} ++@vindex utf-8-emacs@r{ coding system} ++ The coding system @code{utf-8-emacs} specifies that the data is ++represented in the internal Emacs encoding (@pxref{Text ++Representations}). This is like @code{raw-text} in that no code ++conversion happens, but different in that the result is multibyte ++data. The name @code{emacs-internal} is an alias for ++@code{utf-8-emacs}. ++ ++@defun coding-system-get coding-system property ++This function returns the specified property of the coding system ++@var{coding-system}. Most coding system properties exist for internal ++purposes, but one that you might find useful is @code{:mime-charset}. ++That property's value is the name used in MIME for the character coding ++which this coding system can read and write. Examples: ++ ++@example ++(coding-system-get 'iso-latin-1 :mime-charset) ++ @result{} iso-8859-1 ++(coding-system-get 'iso-2022-cn :mime-charset) ++ @result{} iso-2022-cn ++(coding-system-get 'cyrillic-koi8 :mime-charset) ++ @result{} koi8-r ++@end example ++ ++The value of the @code{:mime-charset} property is also defined ++as an alias for the coding system. ++@end defun ++ ++@defun coding-system-aliases coding-system ++This function returns the list of aliases of @var{coding-system}. ++@end defun ++ ++@node Encoding and I/O ++@subsection Encoding and I/O ++ ++ The principal purpose of coding systems is for use in reading and ++writing files. The function @code{insert-file-contents} uses a coding ++system to decode the file data, and @code{write-region} uses one to ++encode the buffer contents. ++ ++ You can specify the coding system to use either explicitly ++(@pxref{Specifying Coding Systems}), or implicitly using a default ++mechanism (@pxref{Default Coding Systems}). But these methods may not ++completely specify what to do. For example, they may choose a coding ++system such as @code{undefined} which leaves the character code ++conversion to be determined from the data. In these cases, the I/O ++operation finishes the job of choosing a coding system. Very often ++you will want to find out afterwards which coding system was chosen. ++ ++@defvar buffer-file-coding-system ++This buffer-local variable records the coding system used for saving the ++buffer and for writing part of the buffer with @code{write-region}. If ++the text to be written cannot be safely encoded using the coding system ++specified by this variable, these operations select an alternative ++encoding by calling the function @code{select-safe-coding-system} ++(@pxref{User-Chosen Coding Systems}). If selecting a different encoding ++requires to ask the user to specify a coding system, ++@code{buffer-file-coding-system} is updated to the newly selected coding ++system. ++ ++@code{buffer-file-coding-system} does @emph{not} affect sending text ++to a subprocess. ++@end defvar ++ ++@defvar save-buffer-coding-system ++This variable specifies the coding system for saving the buffer (by ++overriding @code{buffer-file-coding-system}). Note that it is not used ++for @code{write-region}. ++ ++When a command to save the buffer starts out to use ++@code{buffer-file-coding-system} (or @code{save-buffer-coding-system}), ++and that coding system cannot handle ++the actual text in the buffer, the command asks the user to choose ++another coding system (by calling @code{select-safe-coding-system}). ++After that happens, the command also updates ++@code{buffer-file-coding-system} to represent the coding system that ++the user specified. ++@end defvar ++ ++@defvar last-coding-system-used ++I/O operations for files and subprocesses set this variable to the ++coding system name that was used. The explicit encoding and decoding ++functions (@pxref{Explicit Encoding}) set it too. ++ ++@strong{Warning:} Since receiving subprocess output sets this variable, ++it can change whenever Emacs waits; therefore, you should copy the ++value shortly after the function call that stores the value you are ++interested in. ++@end defvar ++ ++ The variable @code{selection-coding-system} specifies how to encode ++selections for the window system. @xref{Window System Selections}. ++ ++@defvar file-name-coding-system ++The variable @code{file-name-coding-system} specifies the coding ++system to use for encoding file names. Emacs encodes file names using ++that coding system for all file operations. If ++@code{file-name-coding-system} is @code{nil}, Emacs uses a default ++coding system determined by the selected language environment. In the ++default language environment, any non-@acronym{ASCII} characters in ++file names are not encoded specially; they appear in the file system ++using the internal Emacs representation. ++@end defvar ++ ++ @strong{Warning:} if you change @code{file-name-coding-system} (or ++the language environment) in the middle of an Emacs session, problems ++can result if you have already visited files whose names were encoded ++using the earlier coding system and are handled differently under the ++new coding system. If you try to save one of these buffers under the ++visited file name, saving may use the wrong file name, or it may get ++an error. If such a problem happens, use @kbd{C-x C-w} to specify a ++new file name for that buffer. ++ ++@node Lisp and Coding Systems ++@subsection Coding Systems in Lisp ++ ++ Here are the Lisp facilities for working with coding systems: ++ ++@cindex list all coding systems ++@defun coding-system-list &optional base-only ++This function returns a list of all coding system names (symbols). If ++@var{base-only} is non-@code{nil}, the value includes only the ++base coding systems. Otherwise, it includes alias and variant coding ++systems as well. ++@end defun ++ ++@defun coding-system-p object ++This function returns @code{t} if @var{object} is a coding system ++name or @code{nil}. ++@end defun ++ ++@cindex validity of coding system ++@cindex coding system, validity check ++@defun check-coding-system coding-system ++This function checks the validity of @var{coding-system}. If that is ++valid, it returns @var{coding-system}. If @var{coding-system} is ++@code{nil}, the function return @code{nil}. For any other values, it ++signals an error whose @code{error-symbol} is @code{coding-system-error} ++(@pxref{Signaling Errors, signal}). ++@end defun ++ ++@cindex eol type of coding system ++@defun coding-system-eol-type coding-system ++This function returns the type of end-of-line (a.k.a.@: @dfn{eol}) ++conversion used by @var{coding-system}. If @var{coding-system} ++specifies a certain eol conversion, the return value is an integer 0, ++1, or 2, standing for @code{unix}, @code{dos}, and @code{mac}, ++respectively. If @var{coding-system} doesn't specify eol conversion ++explicitly, the return value is a vector of coding systems, each one ++with one of the possible eol conversion types, like this: ++ ++@lisp ++(coding-system-eol-type 'latin-1) ++ @result{} [latin-1-unix latin-1-dos latin-1-mac] ++@end lisp ++ ++@noindent ++If this function returns a vector, Emacs will decide, as part of the ++text encoding or decoding process, what eol conversion to use. For ++decoding, the end-of-line format of the text is auto-detected, and the ++eol conversion is set to match it (e.g., DOS-style CRLF format will ++imply @code{dos} eol conversion). For encoding, the eol conversion is ++taken from the appropriate default coding system (e.g., ++@code{default-buffer-file-coding-system} for ++@code{buffer-file-coding-system}), or from the default eol conversion ++appropriate for the underlying platform. ++@end defun ++ ++@cindex eol conversion of coding system ++@defun coding-system-change-eol-conversion coding-system eol-type ++This function returns a coding system which is like @var{coding-system} ++except for its eol conversion, which is specified by @code{eol-type}. ++@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or ++@code{nil}. If it is @code{nil}, the returned coding system determines ++the end-of-line conversion from the data. ++ ++@var{eol-type} may also be 0, 1 or 2, standing for @code{unix}, ++@code{dos} and @code{mac}, respectively. ++@end defun ++ ++@cindex text conversion of coding system ++@defun coding-system-change-text-conversion eol-coding text-coding ++This function returns a coding system which uses the end-of-line ++conversion of @var{eol-coding}, and the text conversion of ++@var{text-coding}. If @var{text-coding} is @code{nil}, it returns ++@code{undecided}, or one of its variants according to @var{eol-coding}. ++@end defun ++ ++@cindex safely encode region ++@cindex coding systems for encoding region ++@defun find-coding-systems-region from to ++This function returns a list of coding systems that could be used to ++encode a text between @var{from} and @var{to}. All coding systems in ++the list can safely encode any multibyte characters in that portion of ++the text. ++ ++If the text contains no multibyte characters, the function returns the ++list @code{(undecided)}. ++@end defun ++ ++@cindex safely encode a string ++@cindex coding systems for encoding a string ++@defun find-coding-systems-string string ++This function returns a list of coding systems that could be used to ++encode the text of @var{string}. All coding systems in the list can ++safely encode any multibyte characters in @var{string}. If the text ++contains no multibyte characters, this returns the list ++@code{(undecided)}. ++@end defun ++ ++@cindex charset, coding systems to encode ++@cindex safely encode characters in a charset ++@defun find-coding-systems-for-charsets charsets ++This function returns a list of coding systems that could be used to ++encode all the character sets in the list @var{charsets}. ++@end defun ++ ++@defun check-coding-systems-region start end coding-system-list ++This function checks whether coding systems in the list ++@code{coding-system-list} can encode all the characters in the region ++between @var{start} and @var{end}. If all of the coding systems in ++the list can encode the specified text, the function returns ++@code{nil}. If some coding systems cannot encode some of the ++characters, the value is an alist, each element of which has the form ++@code{(@var{coding-system1} @var{pos1} @var{pos2} @dots{})}, meaning ++that @var{coding-system1} cannot encode characters at buffer positions ++@var{pos1}, @var{pos2}, @enddots{}. ++ ++@var{start} may be a string, in which case @var{end} is ignored and ++the returned value references string indices instead of buffer ++positions. ++@end defun ++ ++@defun detect-coding-region start end &optional highest ++This function chooses a plausible coding system for decoding the text ++from @var{start} to @var{end}. This text should be a byte sequence, ++i.e.@: unibyte text or multibyte text with only @acronym{ASCII} and ++eight-bit characters (@pxref{Explicit Encoding}). ++ ++Normally this function returns a list of coding systems that could ++handle decoding the text that was scanned. They are listed in order of ++decreasing priority. But if @var{highest} is non-@code{nil}, then the ++return value is just one coding system, the one that is highest in ++priority. ++ ++If the region contains only @acronym{ASCII} characters except for such ++ISO-2022 control characters ISO-2022 as @code{ESC}, the value is ++@code{undecided} or @code{(undecided)}, or a variant specifying ++end-of-line conversion, if that can be deduced from the text. ++ ++If the region contains null bytes, the value is @code{no-conversion}, ++even if the region contains text encoded in some coding system. ++@end defun ++ ++@defun detect-coding-string string &optional highest ++This function is like @code{detect-coding-region} except that it ++operates on the contents of @var{string} instead of bytes in the buffer. ++@end defun ++ ++@cindex null bytes, and decoding text ++@defvar inhibit-null-byte-detection ++If this variable has a non-@code{nil} value, null bytes are ignored ++when detecting the encoding of a region or a string. This allows to ++correctly detect the encoding of text that contains null bytes, such ++as Info files with Index nodes. ++@end defvar ++ ++@defvar inhibit-iso-escape-detection ++If this variable has a non-@code{nil} value, ISO-2022 escape sequences ++are ignored when detecting the encoding of a region or a string. The ++result is that no text is ever detected as encoded in some ISO-2022 ++encoding, and all escape sequences become visible in a buffer. ++@strong{Warning:} @emph{Use this variable with extreme caution, ++because many files in the Emacs distribution use ISO-2022 encoding.} ++@end defvar ++ ++@cindex charsets supported by a coding system ++@defun coding-system-charset-list coding-system ++This function returns the list of character sets (@pxref{Character ++Sets}) supported by @var{coding-system}. Some coding systems that ++support too many character sets to list them all yield special values: ++@itemize @bullet ++@item ++If @var{coding-system} supports all the ISO-2022 charsets, the value ++is @code{iso-2022}. ++@item ++If @var{coding-system} supports all Emacs characters, the value is ++@code{(emacs)}. ++@item ++If @var{coding-system} supports all emacs-mule characters, the value ++is @code{emacs-mule}. ++@item ++If @var{coding-system} supports all Unicode characters, the value is ++@code{(unicode)}. ++@end itemize ++@end defun ++ ++ @xref{Coding systems for a subprocess,, Process Information}, in ++particular the description of the functions ++@code{process-coding-system} and @code{set-process-coding-system}, for ++how to examine or set the coding systems used for I/O to a subprocess. ++ ++@node User-Chosen Coding Systems ++@subsection User-Chosen Coding Systems ++ ++@cindex select safe coding system ++@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file ++This function selects a coding system for encoding specified text, ++asking the user to choose if necessary. Normally the specified text ++is the text in the current buffer between @var{from} and @var{to}. If ++@var{from} is a string, the string specifies the text to encode, and ++@var{to} is ignored. ++ ++If the specified text includes raw bytes (@pxref{Text ++Representations}), @code{select-safe-coding-system} suggests ++@code{raw-text} for its encoding. ++ ++If @var{default-coding-system} is non-@code{nil}, that is the first ++coding system to try; if that can handle the text, ++@code{select-safe-coding-system} returns that coding system. It can ++also be a list of coding systems; then the function tries each of them ++one by one. After trying all of them, it next tries the current ++buffer's value of @code{buffer-file-coding-system} (if it is not ++@code{undecided}), then the value of ++@code{default-buffer-file-coding-system} and finally the user's most ++preferred coding system, which the user can set using the command ++@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing ++Coding Systems, emacs, The GNU Emacs Manual}). ++ ++If one of those coding systems can safely encode all the specified ++text, @code{select-safe-coding-system} chooses it and returns it. ++Otherwise, it asks the user to choose from a list of coding systems ++which can encode all the text, and returns the user's choice. ++ ++@var{default-coding-system} can also be a list whose first element is ++t and whose other elements are coding systems. Then, if no coding ++system in the list can handle the text, @code{select-safe-coding-system} ++queries the user immediately, without trying any of the three ++alternatives described above. ++ ++The optional argument @var{accept-default-p}, if non-@code{nil}, ++should be a function to determine whether a coding system selected ++without user interaction is acceptable. @code{select-safe-coding-system} ++calls this function with one argument, the base coding system of the ++selected coding system. If @var{accept-default-p} returns @code{nil}, ++@code{select-safe-coding-system} rejects the silently selected coding ++system, and asks the user to select a coding system from a list of ++possible candidates. ++ ++@vindex select-safe-coding-system-accept-default-p ++If the variable @code{select-safe-coding-system-accept-default-p} is ++non-@code{nil}, its value overrides the value of ++@var{accept-default-p}. ++ ++As a final step, before returning the chosen coding system, ++@code{select-safe-coding-system} checks whether that coding system is ++consistent with what would be selected if the contents of the region ++were read from a file. (If not, this could lead to data corruption in ++a file subsequently re-visited and edited.) Normally, ++@code{select-safe-coding-system} uses @code{buffer-file-name} as the ++file for this purpose, but if @var{file} is non-@code{nil}, it uses ++that file instead (this can be relevant for @code{write-region} and ++similar functions). If it detects an apparent inconsistency, ++@code{select-safe-coding-system} queries the user before selecting the ++coding system. ++@end defun ++ ++ Here are two functions you can use to let the user specify a coding ++system, with completion. @xref{Completion}. ++ ++@defun read-coding-system prompt &optional default ++This function reads a coding system using the minibuffer, prompting with ++string @var{prompt}, and returns the coding system name as a symbol. If ++the user enters null input, @var{default} specifies which coding system ++to return. It should be a symbol or a string. ++@end defun ++ ++@defun read-non-nil-coding-system prompt ++This function reads a coding system using the minibuffer, prompting with ++string @var{prompt}, and returns the coding system name as a symbol. If ++the user tries to enter null input, it asks the user to try again. ++@xref{Coding Systems}. ++@end defun ++ ++@node Default Coding Systems ++@subsection Default Coding Systems ++@cindex default coding system ++@cindex coding system, automatically determined ++ ++ This section describes variables that specify the default coding ++system for certain files or when running certain subprograms, and the ++function that I/O operations use to access them. ++ ++ The idea of these variables is that you set them once and for all to the ++defaults you want, and then do not change them again. To specify a ++particular coding system for a particular operation in a Lisp program, ++don't change these variables; instead, override them using ++@code{coding-system-for-read} and @code{coding-system-for-write} ++(@pxref{Specifying Coding Systems}). ++ ++@cindex file contents, and default coding system ++@defopt auto-coding-regexp-alist ++This variable is an alist of text patterns and corresponding coding ++systems. Each element has the form @code{(@var{regexp} ++. @var{coding-system})}; a file whose first few kilobytes match ++@var{regexp} is decoded with @var{coding-system} when its contents are ++read into a buffer. The settings in this alist take priority over ++@code{coding:} tags in the files and the contents of ++@code{file-coding-system-alist} (see below). The default value is set ++so that Emacs automatically recognizes mail files in Babyl format and ++reads them with no code conversions. ++@end defopt ++ ++@cindex file name, and default coding system ++@defopt file-coding-system-alist ++This variable is an alist that specifies the coding systems to use for ++reading and writing particular files. Each element has the form ++@code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular ++expression that matches certain file names. The element applies to file ++names that match @var{pattern}. ++ ++The @sc{cdr} of the element, @var{coding}, should be either a coding ++system, a cons cell containing two coding systems, or a function name (a ++symbol with a function definition). If @var{coding} is a coding system, ++that coding system is used for both reading the file and writing it. If ++@var{coding} is a cons cell containing two coding systems, its @sc{car} ++specifies the coding system for decoding, and its @sc{cdr} specifies the ++coding system for encoding. ++ ++If @var{coding} is a function name, the function should take one ++argument, a list of all arguments passed to ++@code{find-operation-coding-system}. It must return a coding system ++or a cons cell containing two coding systems. This value has the same ++meaning as described above. ++ ++If @var{coding} (or what returned by the above function) is ++@code{undecided}, the normal code-detection is performed. ++@end defopt ++ ++@defopt auto-coding-alist ++This variable is an alist that specifies the coding systems to use for ++reading and writing particular files. Its form is like that of ++@code{file-coding-system-alist}, but, unlike the latter, this variable ++takes priority over any @code{coding:} tags in the file. ++@end defopt ++ ++@cindex program name, and default coding system ++@defvar process-coding-system-alist ++This variable is an alist specifying which coding systems to use for a ++subprocess, depending on which program is running in the subprocess. It ++works like @code{file-coding-system-alist}, except that @var{pattern} is ++matched against the program name used to start the subprocess. The coding ++system or systems specified in this alist are used to initialize the ++coding systems used for I/O to the subprocess, but you can specify ++other coding systems later using @code{set-process-coding-system}. ++@end defvar ++ ++ @strong{Warning:} Coding systems such as @code{undecided}, which ++determine the coding system from the data, do not work entirely reliably ++with asynchronous subprocess output. This is because Emacs handles ++asynchronous subprocess output in batches, as it arrives. If the coding ++system leaves the character code conversion unspecified, or leaves the ++end-of-line conversion unspecified, Emacs must try to detect the proper ++conversion from one batch at a time, and this does not always work. ++ ++ Therefore, with an asynchronous subprocess, if at all possible, use a ++coding system which determines both the character code conversion and ++the end of line conversion---that is, one like @code{latin-1-unix}, ++rather than @code{undecided} or @code{latin-1}. ++ ++@cindex port number, and default coding system ++@cindex network service name, and default coding system ++@defvar network-coding-system-alist ++This variable is an alist that specifies the coding system to use for ++network streams. It works much like @code{file-coding-system-alist}, ++with the difference that the @var{pattern} in an element may be either a ++port number or a regular expression. If it is a regular expression, it ++is matched against the network service name used to open the network ++stream. ++@end defvar ++ ++@defvar default-process-coding-system ++This variable specifies the coding systems to use for subprocess (and ++network stream) input and output, when nothing else specifies what to ++do. ++ ++The value should be a cons cell of the form @code{(@var{input-coding} ++. @var{output-coding})}. Here @var{input-coding} applies to input from ++the subprocess, and @var{output-coding} applies to output to it. ++@end defvar ++ ++@cindex default coding system, functions to determine ++@defopt auto-coding-functions ++This variable holds a list of functions that try to determine a ++coding system for a file based on its undecoded contents. ++ ++Each function in this list should be written to look at text in the ++current buffer, but should not modify it in any way. The buffer will ++contain undecoded text of parts of the file. Each function should ++take one argument, @var{size}, which tells it how many characters to ++look at, starting from point. If the function succeeds in determining ++a coding system for the file, it should return that coding system. ++Otherwise, it should return @code{nil}. ++ ++If a file has a @samp{coding:} tag, that takes precedence, so these ++functions won't be called. ++@end defopt ++ ++@defun find-auto-coding filename size ++This function tries to determine a suitable coding system for ++@var{filename}. It examines the buffer visiting the named file, using ++the variables documented above in sequence, until it finds a match for ++one of the rules specified by these variables. It then returns a cons ++cell of the form @code{(@var{coding} . @var{source})}, where ++@var{coding} is the coding system to use and @var{source} is a symbol, ++one of @code{auto-coding-alist}, @code{auto-coding-regexp-alist}, ++@code{:coding}, or @code{auto-coding-functions}, indicating which one ++supplied the matching rule. The value @code{:coding} means the coding ++system was specified by the @code{coding:} tag in the file ++(@pxref{Specify Coding,, coding tag, emacs, The GNU Emacs Manual}). ++The order of looking for a matching rule is @code{auto-coding-alist} ++first, then @code{auto-coding-regexp-alist}, then the @code{coding:} ++tag, and lastly @code{auto-coding-functions}. If no matching rule was ++found, the function returns @code{nil}. ++ ++The second argument @var{size} is the size of text, in characters, ++following point. The function examines text only within @var{size} ++characters after point. Normally, the buffer should be positioned at ++the beginning when this function is called, because one of the places ++for the @code{coding:} tag is the first one or two lines of the file; ++in that case, @var{size} should be the size of the buffer. ++@end defun ++ ++@defun set-auto-coding filename size ++This function returns a suitable coding system for file ++@var{filename}. It uses @code{find-auto-coding} to find the coding ++system. If no coding system could be determined, the function returns ++@code{nil}. The meaning of the argument @var{size} is like in ++@code{find-auto-coding}. ++@end defun ++ ++@defun find-operation-coding-system operation &rest arguments ++This function returns the coding system to use (by default) for ++performing @var{operation} with @var{arguments}. The value has this ++form: ++ ++@example ++(@var{decoding-system} . @var{encoding-system}) ++@end example ++ ++The first element, @var{decoding-system}, is the coding system to use ++for decoding (in case @var{operation} does decoding), and ++@var{encoding-system} is the coding system for encoding (in case ++@var{operation} does encoding). ++ ++The argument @var{operation} is a symbol, one of @code{write-region}, ++@code{start-process}, @code{call-process}, @code{call-process-region}, ++@code{insert-file-contents}, or @code{open-network-stream}. These are ++the names of the Emacs I/O primitives that can do character code and ++eol conversion. ++ ++The remaining arguments should be the same arguments that might be given ++to the corresponding I/O primitive. Depending on the primitive, one ++of those arguments is selected as the @dfn{target}. For example, if ++@var{operation} does file I/O, whichever argument specifies the file ++name is the target. For subprocess primitives, the process name is the ++target. For @code{open-network-stream}, the target is the service name ++or port number. ++ ++Depending on @var{operation}, this function looks up the target in ++@code{file-coding-system-alist}, @code{process-coding-system-alist}, ++or @code{network-coding-system-alist}. If the target is found in the ++alist, @code{find-operation-coding-system} returns its association in ++the alist; otherwise it returns @code{nil}. ++ ++If @var{operation} is @code{insert-file-contents}, the argument ++corresponding to the target may be a cons cell of the form ++@code{(@var{filename} . @var{buffer})}). In that case, @var{filename} ++is a file name to look up in @code{file-coding-system-alist}, and ++@var{buffer} is a buffer that contains the file's contents (not yet ++decoded). If @code{file-coding-system-alist} specifies a function to ++call for this file, and that function needs to examine the file's ++contents (as it usually does), it should examine the contents of ++@var{buffer} instead of reading the file. ++@end defun ++ ++@node Specifying Coding Systems ++@subsection Specifying a Coding System for One Operation ++ ++ You can specify the coding system for a specific operation by binding ++the variables @code{coding-system-for-read} and/or ++@code{coding-system-for-write}. ++ ++@defvar coding-system-for-read ++If this variable is non-@code{nil}, it specifies the coding system to ++use for reading a file, or for input from a synchronous subprocess. ++ ++It also applies to any asynchronous subprocess or network stream, but in ++a different way: the value of @code{coding-system-for-read} when you ++start the subprocess or open the network stream specifies the input ++decoding method for that subprocess or network stream. It remains in ++use for that subprocess or network stream unless and until overridden. ++ ++The right way to use this variable is to bind it with @code{let} for a ++specific I/O operation. Its global value is normally @code{nil}, and ++you should not globally set it to any other value. Here is an example ++of the right way to use the variable: ++ ++@example ++;; @r{Read the file with no character code conversion.} ++;; @r{Assume @acronym{crlf} represents end-of-line.} ++(let ((coding-system-for-read 'emacs-mule-dos)) ++ (insert-file-contents filename)) ++@end example ++ ++When its value is non-@code{nil}, this variable takes precedence over ++all other methods of specifying a coding system to use for input, ++including @code{file-coding-system-alist}, ++@code{process-coding-system-alist} and ++@code{network-coding-system-alist}. ++@end defvar ++ ++@defvar coding-system-for-write ++This works much like @code{coding-system-for-read}, except that it ++applies to output rather than input. It affects writing to files, ++as well as sending output to subprocesses and net connections. ++ ++When a single operation does both input and output, as do ++@code{call-process-region} and @code{start-process}, both ++@code{coding-system-for-read} and @code{coding-system-for-write} ++affect it. ++@end defvar ++ ++@defopt inhibit-eol-conversion ++When this variable is non-@code{nil}, no end-of-line conversion is done, ++no matter which coding system is specified. This applies to all the ++Emacs I/O and subprocess primitives, and to the explicit encoding and ++decoding functions (@pxref{Explicit Encoding}). ++@end defopt ++ ++@cindex priority order of coding systems ++@cindex coding systems, priority ++ Sometimes, you need to prefer several coding systems for some ++operation, rather than fix a single one. Emacs lets you specify a ++priority order for using coding systems. This ordering affects the ++sorting of lists of coding sysems returned by functions such as ++@code{find-coding-systems-region} (@pxref{Lisp and Coding Systems}). ++ ++@defun coding-system-priority-list &optional highestp ++This function returns the list of coding systems in the order of their ++current priorities. Optional argument @var{highestp}, if ++non-@code{nil}, means return only the highest priority coding system. ++@end defun ++ ++@defun set-coding-system-priority &rest coding-systems ++This function puts @var{coding-systems} at the beginning of the ++priority list for coding systems, thus making their priority higher ++than all the rest. ++@end defun ++ ++@defmac with-coding-priority coding-systems &rest body@dots{} ++This macro execute @var{body}, like @code{progn} does ++(@pxref{Sequencing, progn}), with @var{coding-systems} at the front of ++the priority list for coding systems. @var{coding-systems} should be ++a list of coding systems to prefer during execution of @var{body}. ++@end defmac ++ ++@node Explicit Encoding ++@subsection Explicit Encoding and Decoding ++@cindex encoding in coding systems ++@cindex decoding in coding systems ++ ++ All the operations that transfer text in and out of Emacs have the ++ability to use a coding system to encode or decode the text. ++You can also explicitly encode and decode text using the functions ++in this section. ++ ++ The result of encoding, and the input to decoding, are not ordinary ++text. They logically consist of a series of byte values; that is, a ++series of @acronym{ASCII} and eight-bit characters. In unibyte ++buffers and strings, these characters have codes in the range 0 ++through 255. In a multibyte buffer or string, eight-bit characters ++have character codes higher than 255 (@pxref{Text Representations}), ++but Emacs transparently converts them to their single-byte values when ++you encode or decode such text. ++ ++ The usual way to read a file into a buffer as a sequence of bytes, so ++you can decode the contents explicitly, is with ++@code{insert-file-contents-literally} (@pxref{Reading from Files}); ++alternatively, specify a non-@code{nil} @var{rawfile} argument when ++visiting a file with @code{find-file-noselect}. These methods result in ++a unibyte buffer. ++ ++ The usual way to use the byte sequence that results from explicitly ++encoding text is to copy it to a file or process---for example, to write ++it with @code{write-region} (@pxref{Writing to Files}), and suppress ++encoding by binding @code{coding-system-for-write} to ++@code{no-conversion}. ++ ++ Here are the functions to perform explicit encoding or decoding. The ++encoding functions produce sequences of bytes; the decoding functions ++are meant to operate on sequences of bytes. All of these functions ++discard text properties. They also set @code{last-coding-system-used} ++to the precise coding system they used. ++ ++@deffn Command encode-coding-region start end coding-system &optional destination ++This command encodes the text from @var{start} to @var{end} according ++to coding system @var{coding-system}. Normally, the encoded text ++replaces the original text in the buffer, but the optional argument ++@var{destination} can change that. If @var{destination} is a buffer, ++the encoded text is inserted in that buffer after point (point does ++not move); if it is @code{t}, the command returns the encoded text as ++a unibyte string without inserting it. ++ ++If encoded text is inserted in some buffer, this command returns the ++length of the encoded text. ++ ++The result of encoding is logically a sequence of bytes, but the ++buffer remains multibyte if it was multibyte before, and any 8-bit ++bytes are converted to their multibyte representation (@pxref{Text ++Representations}). ++ ++@cindex @code{undecided} coding-system, when encoding ++Do @emph{not} use @code{undecided} for @var{coding-system} when ++encoding text, since that may lead to unexpected results. Instead, ++use @code{select-safe-coding-system} (@pxref{User-Chosen Coding ++Systems, select-safe-coding-system}) to suggest a suitable encoding, ++if there's no obvious pertinent value for @var{coding-system}. ++@end deffn ++ ++@defun encode-coding-string string coding-system &optional nocopy buffer ++This function encodes the text in @var{string} according to coding ++system @var{coding-system}. It returns a new string containing the ++encoded text, except when @var{nocopy} is non-@code{nil}, in which ++case the function may return @var{string} itself if the encoding ++operation is trivial. The result of encoding is a unibyte string. ++@end defun ++ ++@deffn Command decode-coding-region start end coding-system &optional destination ++This command decodes the text from @var{start} to @var{end} according ++to coding system @var{coding-system}. To make explicit decoding ++useful, the text before decoding ought to be a sequence of byte ++values, but both multibyte and unibyte buffers are acceptable (in the ++multibyte case, the raw byte values should be represented as eight-bit ++characters). Normally, the decoded text replaces the original text in ++the buffer, but the optional argument @var{destination} can change ++that. If @var{destination} is a buffer, the decoded text is inserted ++in that buffer after point (point does not move); if it is @code{t}, ++the command returns the decoded text as a multibyte string without ++inserting it. ++ ++If decoded text is inserted in some buffer, this command returns the ++length of the decoded text. ++ ++This command puts a @code{charset} text property on the decoded text. ++The value of the property states the character set used to decode the ++original text. ++@end deffn ++ ++@defun decode-coding-string string coding-system &optional nocopy buffer ++This function decodes the text in @var{string} according to ++@var{coding-system}. It returns a new string containing the decoded ++text, except when @var{nocopy} is non-@code{nil}, in which case the ++function may return @var{string} itself if the decoding operation is ++trivial. To make explicit decoding useful, the contents of ++@var{string} ought to be a unibyte string with a sequence of byte ++values, but a multibyte string is also acceptable (assuming it ++contains 8-bit bytes in their multibyte form). ++ ++If optional argument @var{buffer} specifies a buffer, the decoded text ++is inserted in that buffer after point (point does not move). In this ++case, the return value is the length of the decoded text. ++ ++@cindex @code{charset}, text property ++This function puts a @code{charset} text property on the decoded text. ++The value of the property states the character set used to decode the ++original text: ++ ++@example ++@group ++(decode-coding-string "Gr\374ss Gott" 'latin-1) ++ @result{} #("Gr@"uss Gott" 0 9 (charset iso-8859-1)) ++@end group ++@end example ++@end defun ++ ++@defun decode-coding-inserted-region from to filename &optional visit beg end replace ++This function decodes the text from @var{from} to @var{to} as if ++it were being read from file @var{filename} using @code{insert-file-contents} ++using the rest of the arguments provided. ++ ++The normal way to use this function is after reading text from a file ++without decoding, if you decide you would rather have decoded it. ++Instead of deleting the text and reading it again, this time with ++decoding, you can call this function. ++@end defun ++ ++@node Terminal I/O Encoding ++@subsection Terminal I/O Encoding ++ ++ Emacs can decode keyboard input using a coding system, and encode ++terminal output. This is useful for terminals that transmit or ++display text using a particular encoding such as Latin-1. Emacs does ++not set @code{last-coding-system-used} for encoding or decoding of ++terminal I/O. ++ ++@defun keyboard-coding-system &optional terminal ++This function returns the coding system that is in use for decoding ++keyboard input from @var{terminal}---or @code{nil} if no coding system ++is to be used for that terminal. If @var{terminal} is omitted or ++@code{nil}, it means the selected frame's terminal. @xref{Multiple ++Terminals}. ++@end defun ++ ++@deffn Command set-keyboard-coding-system coding-system &optional terminal ++This command specifies @var{coding-system} as the coding system to use ++for decoding keyboard input from @var{terminal}. If ++@var{coding-system} is @code{nil}, that means do not decode keyboard ++input. If @var{terminal} is a frame, it means that frame's terminal; ++if it is @code{nil}, that means the currently selected frame's ++terminal. @xref{Multiple Terminals}. ++@end deffn ++ ++@defun terminal-coding-system &optional terminal ++This function returns the coding system that is in use for encoding ++terminal output from @var{terminal}---or @code{nil} if the output is ++not encoded. If @var{terminal} is a frame, it means that frame's ++terminal; if it is @code{nil}, that means the currently selected ++frame's terminal. ++@end defun ++ ++@deffn Command set-terminal-coding-system coding-system &optional terminal ++This command specifies @var{coding-system} as the coding system to use ++for encoding terminal output from @var{terminal}. If ++@var{coding-system} is @code{nil}, terminal output is not encoded. If ++@var{terminal} is a frame, it means that frame's terminal; if it is ++@code{nil}, that means the currently selected frame's terminal. ++@end deffn ++ ++@node MS-DOS File Types ++@subsection MS-DOS File Types ++@cindex DOS file types ++@cindex MS-DOS file types ++@cindex Windows file types ++@cindex file types on MS-DOS and Windows ++@cindex text files and binary files ++@cindex binary files and text files ++ ++ On MS-DOS and Microsoft Windows, Emacs guesses the appropriate ++end-of-line conversion for a file by looking at the file's name. This ++feature classifies files as @dfn{text files} and @dfn{binary files}. By ++``binary file'' we mean a file of literal byte values that are not ++necessarily meant to be characters; Emacs does no end-of-line conversion ++and no character code conversion for them. On the other hand, the bytes ++in a text file are intended to represent characters; when you create a ++new file whose name implies that it is a text file, Emacs uses DOS ++end-of-line conversion. ++ ++@defvar buffer-file-type ++This variable, automatically buffer-local in each buffer, records the ++file type of the buffer's visited file. When a buffer does not specify ++a coding system with @code{buffer-file-coding-system}, this variable is ++used to determine which coding system to use when writing the contents ++of the buffer. It should be @code{nil} for text, @code{t} for binary. ++If it is @code{t}, the coding system is @code{no-conversion}. ++Otherwise, @code{undecided-dos} is used. ++ ++Normally this variable is set by visiting a file; it is set to ++@code{nil} if the file was visited without any actual conversion. ++@end defvar ++ ++@defopt file-name-buffer-file-type-alist ++This variable holds an alist for recognizing text and binary files. ++Each element has the form (@var{regexp} . @var{type}), where ++@var{regexp} is matched against the file name, and @var{type} may be ++@code{nil} for text, @code{t} for binary, or a function to call to ++compute which. If it is a function, then it is called with a single ++argument (the file name) and should return @code{t} or @code{nil}. ++ ++When running on MS-DOS or MS-Windows, Emacs checks this alist to decide ++which coding system to use when reading a file. For a text file, ++@code{undecided-dos} is used. For a binary file, @code{no-conversion} ++is used. ++ ++If no element in this alist matches a given file name, then ++@code{default-buffer-file-type} says how to treat the file. ++@end defopt ++ ++@defopt default-buffer-file-type ++This variable says how to handle files for which ++@code{file-name-buffer-file-type-alist} says nothing about the type. ++ ++If this variable is non-@code{nil}, then these files are treated as ++binary: the coding system @code{no-conversion} is used. Otherwise, ++nothing special is done for them---the coding system is deduced solely ++from the file contents, in the usual Emacs fashion. ++@end defopt ++ ++@node Input Methods ++@section Input Methods ++@cindex input methods ++ ++ @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII} ++characters from the keyboard. Unlike coding systems, which translate ++non-@acronym{ASCII} characters to and from encodings meant to be read by ++programs, input methods provide human-friendly commands. (@xref{Input ++Methods,,, emacs, The GNU Emacs Manual}, for information on how users ++use input methods to enter text.) How to define input methods is not ++yet documented in this manual, but here we describe how to use them. ++ ++ Each input method has a name, which is currently a string; ++in the future, symbols may also be usable as input method names. ++ ++@defvar current-input-method ++This variable holds the name of the input method now active in the ++current buffer. (It automatically becomes local in each buffer when set ++in any fashion.) It is @code{nil} if no input method is active in the ++buffer now. ++@end defvar ++ ++@defopt default-input-method ++This variable holds the default input method for commands that choose an ++input method. Unlike @code{current-input-method}, this variable is ++normally global. ++@end defopt ++ ++@deffn Command set-input-method input-method ++This command activates input method @var{input-method} for the current ++buffer. It also sets @code{default-input-method} to @var{input-method}. ++If @var{input-method} is @code{nil}, this command deactivates any input ++method for the current buffer. ++@end deffn ++ ++@defun read-input-method-name prompt &optional default inhibit-null ++This function reads an input method name with the minibuffer, prompting ++with @var{prompt}. If @var{default} is non-@code{nil}, that is returned ++by default, if the user enters empty input. However, if ++@var{inhibit-null} is non-@code{nil}, empty input signals an error. ++ ++The returned value is a string. ++@end defun ++ ++@defvar input-method-alist ++This variable defines all the supported input methods. ++Each element defines one input method, and should have the form: ++ ++@example ++(@var{input-method} @var{language-env} @var{activate-func} ++ @var{title} @var{description} @var{args}...) ++@end example ++ ++Here @var{input-method} is the input method name, a string; ++@var{language-env} is another string, the name of the language ++environment this input method is recommended for. (That serves only for ++documentation purposes.) ++ ++@var{activate-func} is a function to call to activate this method. The ++@var{args}, if any, are passed as arguments to @var{activate-func}. All ++told, the arguments to @var{activate-func} are @var{input-method} and ++the @var{args}. ++ ++@var{title} is a string to display in the mode line while this method is ++active. @var{description} is a string describing this method and what ++it is good for. ++@end defvar ++ ++ The fundamental interface to input methods is through the ++variable @code{input-method-function}. @xref{Reading One Event}, ++and @ref{Invoking the Input Method}. ++ ++@node Locales ++@section Locales ++@cindex locale ++ ++ POSIX defines a concept of ``locales'' which control which language ++to use in language-related features. These Emacs variables control ++how Emacs interacts with these features. ++ ++@defvar locale-coding-system ++@cindex keyboard input decoding on X ++This variable specifies the coding system to use for decoding system ++error messages and---on X Window system only---keyboard input, for ++encoding the format argument to @code{format-time-string}, and for ++decoding the return value of @code{format-time-string}. ++@end defvar ++ ++@defvar system-messages-locale ++This variable specifies the locale to use for generating system error ++messages. Changing the locale can cause messages to come out in a ++different language or in a different orthography. If the variable is ++@code{nil}, the locale is specified by environment variables in the ++usual POSIX fashion. ++@end defvar ++ ++@defvar system-time-locale ++This variable specifies the locale to use for formatting time values. ++Changing the locale can cause messages to appear according to the ++conventions of a different language. If the variable is @code{nil}, the ++locale is specified by environment variables in the usual POSIX fashion. ++@end defvar ++ ++@defun locale-info item ++This function returns locale data @var{item} for the current POSIX ++locale, if available. @var{item} should be one of these symbols: ++ ++@table @code ++@item codeset ++Return the character set as a string (locale item @code{CODESET}). ++ ++@item days ++Return a 7-element vector of day names (locale items ++@code{DAY_1} through @code{DAY_7}); ++ ++@item months ++Return a 12-element vector of month names (locale items @code{MON_1} ++through @code{MON_12}). ++ ++@item paper ++Return a list @code{(@var{width} @var{height})} for the default paper ++size measured in millimeters (locale items @code{PAPER_WIDTH} and ++@code{PAPER_HEIGHT}). ++@end table ++ ++If the system can't provide the requested information, or if ++@var{item} is not one of those symbols, the value is @code{nil}. All ++strings in the return value are decoded using ++@code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual}, ++for more information about locales and locale items. ++@end defun ++ ++@ignore ++ arch-tag: be705bf8-941b-4c35-84fc-ad7d20ddb7cb ++@end ignore +diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi +new file mode 100644 +index 0000000..bb67f8a +--- /dev/null ++++ b/doc/lispref/numbers.texi +@@ -0,0 +1,1214 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/numbers ++@node Numbers, Strings and Characters, Lisp Data Types, Top ++@chapter Numbers ++@cindex integers ++@cindex numbers ++ ++ GNU Emacs supports two numeric data types: @dfn{integers} and ++@dfn{floating point numbers}. Integers are whole numbers such as ++@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point ++numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or ++2.71828. They can also be expressed in exponential notation: 1.5e2 ++equals 150; in this example, @samp{e2} stands for ten to the second ++power, and that is multiplied by 1.5. Floating point values are not ++exact; they have a fixed, limited amount of precision. ++ ++@menu ++* Integer Basics:: Representation and range of integers. ++* Float Basics:: Representation and range of floating point. ++* Predicates on Numbers:: Testing for numbers. ++* Comparison of Numbers:: Equality and inequality predicates. ++* Numeric Conversions:: Converting float to integer and vice versa. ++* Arithmetic Operations:: How to add, subtract, multiply and divide. ++* Rounding Operations:: Explicitly rounding floating point numbers. ++* Bitwise Operations:: Logical and, or, not, shifting. ++* Math Functions:: Trig, exponential and logarithmic functions. ++* Random Numbers:: Obtaining random integers, predictable or not. ++@end menu ++ ++@node Integer Basics ++@comment node-name, next, previous, up ++@section Integer Basics ++ ++ The range of values for an integer depends on the machine. The ++minimum range is @minus{}268435456 to 268435455 (29 bits; i.e., ++@ifnottex ++-2**28 ++@end ifnottex ++@tex ++@math{-2^{28}} ++@end tex ++to ++@ifnottex ++2**28 - 1), ++@end ifnottex ++@tex ++@math{2^{28}-1}), ++@end tex ++but some machines may provide a wider range. Many examples in this ++chapter assume an integer has 29 bits. ++@cindex overflow ++ ++ The Lisp reader reads an integer as a sequence of digits with optional ++initial sign and optional final period. ++ ++@example ++ 1 ; @r{The integer 1.} ++ 1. ; @r{The integer 1.} +++1 ; @r{Also the integer 1.} ++-1 ; @r{The integer @minus{}1.} ++ 536870913 ; @r{Also the integer 1, due to overflow.} ++ 0 ; @r{The integer 0.} ++-0 ; @r{The integer 0.} ++@end example ++ ++@cindex integers in specific radix ++@cindex radix for reading an integer ++@cindex base for reading an integer ++@cindex hex numbers ++@cindex octal numbers ++@cindex reading numbers in hex, octal, and binary ++ The syntax for integers in bases other than 10 uses @samp{#} ++followed by a letter that specifies the radix: @samp{b} for binary, ++@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to ++specify radix @var{radix}. Case is not significant for the letter ++that specifies the radix. Thus, @samp{#b@var{integer}} reads ++@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads ++@var{integer} in radix @var{radix}. Allowed values of @var{radix} run ++from 2 to 36. For example: ++ ++@example ++#b101100 @result{} 44 ++#o54 @result{} 44 ++#x2c @result{} 44 ++#24r1k @result{} 44 ++@end example ++ ++ To understand how various functions work on integers, especially the ++bitwise operators (@pxref{Bitwise Operations}), it is often helpful to ++view the numbers in their binary form. ++ ++ In 29-bit binary, the decimal integer 5 looks like this: ++ ++@example ++0 0000 0000 0000 0000 0000 0000 0101 ++@end example ++ ++@noindent ++(We have inserted spaces between groups of 4 bits, and two spaces ++between groups of 8 bits, to make the binary integer easier to read.) ++ ++ The integer @minus{}1 looks like this: ++ ++@example ++1 1111 1111 1111 1111 1111 1111 1111 ++@end example ++ ++@noindent ++@cindex two's complement ++@minus{}1 is represented as 29 ones. (This is called @dfn{two's ++complement} notation.) ++ ++ The negative integer, @minus{}5, is creating by subtracting 4 from ++@minus{}1. In binary, the decimal integer 4 is 100. Consequently, ++@minus{}5 looks like this: ++ ++@example ++1 1111 1111 1111 1111 1111 1111 1011 ++@end example ++ ++ In this implementation, the largest 29-bit binary integer value is ++268,435,455 in decimal. In binary, it looks like this: ++ ++@example ++0 1111 1111 1111 1111 1111 1111 1111 ++@end example ++ ++ Since the arithmetic functions do not check whether integers go ++outside their range, when you add 1 to 268,435,455, the value is the ++negative integer @minus{}268,435,456: ++ ++@example ++(+ 1 268435455) ++ @result{} -268435456 ++ @result{} 1 0000 0000 0000 0000 0000 0000 0000 ++@end example ++ ++ Many of the functions described in this chapter accept markers for ++arguments in place of numbers. (@xref{Markers}.) Since the actual ++arguments to such functions may be either numbers or markers, we often ++give these arguments the name @var{number-or-marker}. When the argument ++value is a marker, its position value is used and its buffer is ignored. ++ ++@defvar most-positive-fixnum ++The value of this variable is the largest integer that Emacs Lisp ++can handle. ++@end defvar ++ ++@defvar most-negative-fixnum ++The value of this variable is the smallest integer that Emacs Lisp can ++handle. It is negative. ++@end defvar ++ ++ @xref{Character Codes, max-char}, for the maximum value of a valid ++character codepoint. ++ ++@node Float Basics ++@section Floating Point Basics ++ ++ Floating point numbers are useful for representing numbers that are ++not integral. The precise range of floating point numbers is ++machine-specific; it is the same as the range of the C data type ++@code{double} on the machine you are using. ++ ++ The read-syntax for floating point numbers requires either a decimal ++point (with at least one digit following), an exponent, or both. For ++example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and ++@samp{.15e4} are five ways of writing a floating point number whose ++value is 1500. They are all equivalent. You can also use a minus sign ++to write negative floating point numbers, as in @samp{-1.0}. ++ ++@cindex @acronym{IEEE} floating point ++@cindex positive infinity ++@cindex negative infinity ++@cindex infinity ++@cindex NaN ++ Most modern computers support the @acronym{IEEE} floating point standard, ++which provides for positive infinity and negative infinity as floating point ++values. It also provides for a class of values called NaN or ++``not-a-number''; numerical functions return such values in cases where ++there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a ++NaN. For practical purposes, there's no significant difference between ++different NaN values in Emacs Lisp, and there's no rule for precisely ++which NaN value should be used in a particular case, so Emacs Lisp ++doesn't try to distinguish them (but it does report the sign, if you ++print it). Here are the read syntaxes for these special floating ++point values: ++ ++@table @asis ++@item positive infinity ++@samp{1.0e+INF} ++@item negative infinity ++@samp{-1.0e+INF} ++@item Not-a-number ++@samp{0.0e+NaN} or @samp{-0.0e+NaN}. ++@end table ++ ++ To test whether a floating point value is a NaN, compare it with ++itself using @code{=}. That returns @code{nil} for a NaN, and ++@code{t} for any other floating point value. ++ ++ The value @code{-0.0} is distinguishable from ordinary zero in ++@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and ++@code{=} consider them equal values. ++ ++ You can use @code{logb} to extract the binary exponent of a floating ++point number (or estimate the logarithm of an integer): ++ ++@defun logb number ++This function returns the binary exponent of @var{number}. More ++precisely, the value is the logarithm of @var{number} base 2, rounded ++down to an integer. ++ ++@example ++(logb 10) ++ @result{} 3 ++(logb 10.0e20) ++ @result{} 69 ++@end example ++@end defun ++ ++@node Predicates on Numbers ++@section Type Predicates for Numbers ++@cindex predicates for numbers ++ ++ The functions in this section test for numbers, or for a specific ++type of number. The functions @code{integerp} and @code{floatp} can ++take any type of Lisp object as argument (they would not be of much ++use otherwise), but the @code{zerop} predicate requires a number as ++its argument. See also @code{integer-or-marker-p} and ++@code{number-or-marker-p}, in @ref{Predicates on Markers}. ++ ++@defun floatp object ++This predicate tests whether its argument is a floating point ++number and returns @code{t} if so, @code{nil} otherwise. ++ ++@code{floatp} does not exist in Emacs versions 18 and earlier. ++@end defun ++ ++@defun integerp object ++This predicate tests whether its argument is an integer, and returns ++@code{t} if so, @code{nil} otherwise. ++@end defun ++ ++@defun numberp object ++This predicate tests whether its argument is a number (either integer or ++floating point), and returns @code{t} if so, @code{nil} otherwise. ++@end defun ++ ++@defun wholenump object ++@cindex natural numbers ++The @code{wholenump} predicate (whose name comes from the phrase ++``whole-number-p'') tests to see whether its argument is a nonnegative ++integer, and returns @code{t} if so, @code{nil} otherwise. 0 is ++considered non-negative. ++ ++@findex natnump ++@code{natnump} is an obsolete synonym for @code{wholenump}. ++@end defun ++ ++@defun zerop number ++This predicate tests whether its argument is zero, and returns @code{t} ++if so, @code{nil} otherwise. The argument must be a number. ++ ++@code{(zerop x)} is equivalent to @code{(= x 0)}. ++@end defun ++ ++@node Comparison of Numbers ++@section Comparison of Numbers ++@cindex number comparison ++@cindex comparing numbers ++ ++ To test numbers for numerical equality, you should normally use ++@code{=}, not @code{eq}. There can be many distinct floating point ++number objects with the same numeric value. If you use @code{eq} to ++compare them, then you test whether two values are the same ++@emph{object}. By contrast, @code{=} compares only the numeric values ++of the objects. ++ ++ At present, each integer value has a unique Lisp object in Emacs Lisp. ++Therefore, @code{eq} is equivalent to @code{=} where integers are ++concerned. It is sometimes convenient to use @code{eq} for comparing an ++unknown value with an integer, because @code{eq} does not report an ++error if the unknown value is not a number---it accepts arguments of any ++type. By contrast, @code{=} signals an error if the arguments are not ++numbers or markers. However, it is a good idea to use @code{=} if you ++can, even for comparing integers, just in case we change the ++representation of integers in a future Emacs version. ++ ++ Sometimes it is useful to compare numbers with @code{equal}; it ++treats two numbers as equal if they have the same data type (both ++integers, or both floating point) and the same value. By contrast, ++@code{=} can treat an integer and a floating point number as equal. ++@xref{Equality Predicates}. ++ ++ There is another wrinkle: because floating point arithmetic is not ++exact, it is often a bad idea to check for equality of two floating ++point values. Usually it is better to test for approximate equality. ++Here's a function to do this: ++ ++@example ++(defvar fuzz-factor 1.0e-6) ++(defun approx-equal (x y) ++ (or (and (= x 0) (= y 0)) ++ (< (/ (abs (- x y)) ++ (max (abs x) (abs y))) ++ fuzz-factor))) ++@end example ++ ++@cindex CL note---integers vrs @code{eq} ++@quotation ++@b{Common Lisp note:} Comparing numbers in Common Lisp always requires ++@code{=} because Common Lisp implements multi-word integers, and two ++distinct integer objects can have the same numeric value. Emacs Lisp ++can have just one integer object for any given value because it has a ++limited range of integer values. ++@end quotation ++ ++@defun = number-or-marker1 number-or-marker2 ++This function tests whether its arguments are numerically equal, and ++returns @code{t} if so, @code{nil} otherwise. ++@end defun ++ ++@defun eql value1 value2 ++This function acts like @code{eq} except when both arguments are ++numbers. It compares numbers by type and numeric value, so that ++@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and ++@code{(eql 1 1)} both return @code{t}. ++@end defun ++ ++@defun /= number-or-marker1 number-or-marker2 ++This function tests whether its arguments are numerically equal, and ++returns @code{t} if they are not, and @code{nil} if they are. ++@end defun ++ ++@defun < number-or-marker1 number-or-marker2 ++This function tests whether its first argument is strictly less than ++its second argument. It returns @code{t} if so, @code{nil} otherwise. ++@end defun ++ ++@defun <= number-or-marker1 number-or-marker2 ++This function tests whether its first argument is less than or equal ++to its second argument. It returns @code{t} if so, @code{nil} ++otherwise. ++@end defun ++ ++@defun > number-or-marker1 number-or-marker2 ++This function tests whether its first argument is strictly greater ++than its second argument. It returns @code{t} if so, @code{nil} ++otherwise. ++@end defun ++ ++@defun >= number-or-marker1 number-or-marker2 ++This function tests whether its first argument is greater than or ++equal to its second argument. It returns @code{t} if so, @code{nil} ++otherwise. ++@end defun ++ ++@defun max number-or-marker &rest numbers-or-markers ++This function returns the largest of its arguments. ++If any of the arguments is floating-point, the value is returned ++as floating point, even if it was given as an integer. ++ ++@example ++(max 20) ++ @result{} 20 ++(max 1 2.5) ++ @result{} 2.5 ++(max 1 3 2.5) ++ @result{} 3.0 ++@end example ++@end defun ++ ++@defun min number-or-marker &rest numbers-or-markers ++This function returns the smallest of its arguments. ++If any of the arguments is floating-point, the value is returned ++as floating point, even if it was given as an integer. ++ ++@example ++(min -4 1) ++ @result{} -4 ++@end example ++@end defun ++ ++@defun abs number ++This function returns the absolute value of @var{number}. ++@end defun ++ ++@node Numeric Conversions ++@section Numeric Conversions ++@cindex rounding in conversions ++@cindex number conversions ++@cindex converting numbers ++ ++To convert an integer to floating point, use the function @code{float}. ++ ++@defun float number ++This returns @var{number} converted to floating point. ++If @var{number} is already a floating point number, @code{float} returns ++it unchanged. ++@end defun ++ ++There are four functions to convert floating point numbers to integers; ++they differ in how they round. All accept an argument @var{number} ++and an optional argument @var{divisor}. Both arguments may be ++integers or floating point numbers. @var{divisor} may also be ++@code{nil}. If @var{divisor} is @code{nil} or omitted, these ++functions convert @var{number} to an integer, or return it unchanged ++if it already is an integer. If @var{divisor} is non-@code{nil}, they ++divide @var{number} by @var{divisor} and convert the result to an ++integer. An @code{arith-error} results if @var{divisor} is 0. ++ ++@defun truncate number &optional divisor ++This returns @var{number}, converted to an integer by rounding towards ++zero. ++ ++@example ++(truncate 1.2) ++ @result{} 1 ++(truncate 1.7) ++ @result{} 1 ++(truncate -1.2) ++ @result{} -1 ++(truncate -1.7) ++ @result{} -1 ++@end example ++@end defun ++ ++@defun floor number &optional divisor ++This returns @var{number}, converted to an integer by rounding downward ++(towards negative infinity). ++ ++If @var{divisor} is specified, this uses the kind of division ++operation that corresponds to @code{mod}, rounding downward. ++ ++@example ++(floor 1.2) ++ @result{} 1 ++(floor 1.7) ++ @result{} 1 ++(floor -1.2) ++ @result{} -2 ++(floor -1.7) ++ @result{} -2 ++(floor 5.99 3) ++ @result{} 1 ++@end example ++@end defun ++ ++@defun ceiling number &optional divisor ++This returns @var{number}, converted to an integer by rounding upward ++(towards positive infinity). ++ ++@example ++(ceiling 1.2) ++ @result{} 2 ++(ceiling 1.7) ++ @result{} 2 ++(ceiling -1.2) ++ @result{} -1 ++(ceiling -1.7) ++ @result{} -1 ++@end example ++@end defun ++ ++@defun round number &optional divisor ++This returns @var{number}, converted to an integer by rounding towards the ++nearest integer. Rounding a value equidistant between two integers ++may choose the integer closer to zero, or it may prefer an even integer, ++depending on your machine. ++ ++@example ++(round 1.2) ++ @result{} 1 ++(round 1.7) ++ @result{} 2 ++(round -1.2) ++ @result{} -1 ++(round -1.7) ++ @result{} -2 ++@end example ++@end defun ++ ++@node Arithmetic Operations ++@section Arithmetic Operations ++@cindex arithmetic operations ++ ++ Emacs Lisp provides the traditional four arithmetic operations: ++addition, subtraction, multiplication, and division. Remainder and modulus ++functions supplement the division functions. The functions to ++add or subtract 1 are provided because they are traditional in Lisp and ++commonly used. ++ ++ All of these functions except @code{%} return a floating point value ++if any argument is floating. ++ ++ It is important to note that in Emacs Lisp, arithmetic functions ++do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to ++@minus{}268435456, depending on your hardware. ++ ++@defun 1+ number-or-marker ++This function returns @var{number-or-marker} plus 1. ++For example, ++ ++@example ++(setq foo 4) ++ @result{} 4 ++(1+ foo) ++ @result{} 5 ++@end example ++ ++This function is not analogous to the C operator @code{++}---it does not ++increment a variable. It just computes a sum. Thus, if we continue, ++ ++@example ++foo ++ @result{} 4 ++@end example ++ ++If you want to increment the variable, you must use @code{setq}, ++like this: ++ ++@example ++(setq foo (1+ foo)) ++ @result{} 5 ++@end example ++@end defun ++ ++@defun 1- number-or-marker ++This function returns @var{number-or-marker} minus 1. ++@end defun ++ ++@defun + &rest numbers-or-markers ++This function adds its arguments together. When given no arguments, ++@code{+} returns 0. ++ ++@example ++(+) ++ @result{} 0 ++(+ 1) ++ @result{} 1 ++(+ 1 2 3 4) ++ @result{} 10 ++@end example ++@end defun ++ ++@defun - &optional number-or-marker &rest more-numbers-or-markers ++The @code{-} function serves two purposes: negation and subtraction. ++When @code{-} has a single argument, the value is the negative of the ++argument. When there are multiple arguments, @code{-} subtracts each of ++the @var{more-numbers-or-markers} from @var{number-or-marker}, ++cumulatively. If there are no arguments, the result is 0. ++ ++@example ++(- 10 1 2 3 4) ++ @result{} 0 ++(- 10) ++ @result{} -10 ++(-) ++ @result{} 0 ++@end example ++@end defun ++ ++@defun * &rest numbers-or-markers ++This function multiplies its arguments together, and returns the ++product. When given no arguments, @code{*} returns 1. ++ ++@example ++(*) ++ @result{} 1 ++(* 1) ++ @result{} 1 ++(* 1 2 3 4) ++ @result{} 24 ++@end example ++@end defun ++ ++@defun / dividend divisor &rest divisors ++This function divides @var{dividend} by @var{divisor} and returns the ++quotient. If there are additional arguments @var{divisors}, then it ++divides @var{dividend} by each divisor in turn. Each argument may be a ++number or a marker. ++ ++If all the arguments are integers, then the result is an integer too. ++This means the result has to be rounded. On most machines, the result ++is rounded towards zero after each division, but some machines may round ++differently with negative arguments. This is because the Lisp function ++@code{/} is implemented using the C division operator, which also ++permits machine-dependent rounding. As a practical matter, all known ++machines round in the standard fashion. ++ ++@cindex @code{arith-error} in division ++If you divide an integer by 0, an @code{arith-error} error is signaled. ++(@xref{Errors}.) Floating point division by zero returns either ++infinity or a NaN if your machine supports @acronym{IEEE} floating point; ++otherwise, it signals an @code{arith-error} error. ++ ++@example ++@group ++(/ 6 2) ++ @result{} 3 ++@end group ++(/ 5 2) ++ @result{} 2 ++(/ 5.0 2) ++ @result{} 2.5 ++(/ 5 2.0) ++ @result{} 2.5 ++(/ 5.0 2.0) ++ @result{} 2.5 ++(/ 25 3 2) ++ @result{} 4 ++@group ++(/ -17 6) ++ @result{} -2 @r{(could in theory be @minus{}3 on some machines)} ++@end group ++@end example ++@end defun ++ ++@defun % dividend divisor ++@cindex remainder ++This function returns the integer remainder after division of @var{dividend} ++by @var{divisor}. The arguments must be integers or markers. ++ ++For negative arguments, the remainder is in principle machine-dependent ++since the quotient is; but in practice, all known machines behave alike. ++ ++An @code{arith-error} results if @var{divisor} is 0. ++ ++@example ++(% 9 4) ++ @result{} 1 ++(% -9 4) ++ @result{} -1 ++(% 9 -4) ++ @result{} 1 ++(% -9 -4) ++ @result{} -1 ++@end example ++ ++For any two integers @var{dividend} and @var{divisor}, ++ ++@example ++@group ++(+ (% @var{dividend} @var{divisor}) ++ (* (/ @var{dividend} @var{divisor}) @var{divisor})) ++@end group ++@end example ++ ++@noindent ++always equals @var{dividend}. ++@end defun ++ ++@defun mod dividend divisor ++@cindex modulus ++This function returns the value of @var{dividend} modulo @var{divisor}; ++in other words, the remainder after division of @var{dividend} ++by @var{divisor}, but with the same sign as @var{divisor}. ++The arguments must be numbers or markers. ++ ++Unlike @code{%}, @code{mod} returns a well-defined result for negative ++arguments. It also permits floating point arguments; it rounds the ++quotient downward (towards minus infinity) to an integer, and uses that ++quotient to compute the remainder. ++ ++An @code{arith-error} results if @var{divisor} is 0. ++ ++@example ++@group ++(mod 9 4) ++ @result{} 1 ++@end group ++@group ++(mod -9 4) ++ @result{} 3 ++@end group ++@group ++(mod 9 -4) ++ @result{} -3 ++@end group ++@group ++(mod -9 -4) ++ @result{} -1 ++@end group ++@group ++(mod 5.5 2.5) ++ @result{} .5 ++@end group ++@end example ++ ++For any two numbers @var{dividend} and @var{divisor}, ++ ++@example ++@group ++(+ (mod @var{dividend} @var{divisor}) ++ (* (floor @var{dividend} @var{divisor}) @var{divisor})) ++@end group ++@end example ++ ++@noindent ++always equals @var{dividend}, subject to rounding error if either ++argument is floating point. For @code{floor}, see @ref{Numeric ++Conversions}. ++@end defun ++ ++@node Rounding Operations ++@section Rounding Operations ++@cindex rounding without conversion ++ ++The functions @code{ffloor}, @code{fceiling}, @code{fround}, and ++@code{ftruncate} take a floating point argument and return a floating ++point result whose value is a nearby integer. @code{ffloor} returns the ++nearest integer below; @code{fceiling}, the nearest integer above; ++@code{ftruncate}, the nearest integer in the direction towards zero; ++@code{fround}, the nearest integer. ++ ++@defun ffloor float ++This function rounds @var{float} to the next lower integral value, and ++returns that value as a floating point number. ++@end defun ++ ++@defun fceiling float ++This function rounds @var{float} to the next higher integral value, and ++returns that value as a floating point number. ++@end defun ++ ++@defun ftruncate float ++This function rounds @var{float} towards zero to an integral value, and ++returns that value as a floating point number. ++@end defun ++ ++@defun fround float ++This function rounds @var{float} to the nearest integral value, ++and returns that value as a floating point number. ++@end defun ++ ++@node Bitwise Operations ++@section Bitwise Operations on Integers ++@cindex bitwise arithmetic ++@cindex logical arithmetic ++ ++ In a computer, an integer is represented as a binary number, a ++sequence of @dfn{bits} (digits which are either zero or one). A bitwise ++operation acts on the individual bits of such a sequence. For example, ++@dfn{shifting} moves the whole sequence left or right one or more places, ++reproducing the same pattern ``moved over.'' ++ ++ The bitwise operations in Emacs Lisp apply only to integers. ++ ++@defun lsh integer1 count ++@cindex logical shift ++@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the ++bits in @var{integer1} to the left @var{count} places, or to the right ++if @var{count} is negative, bringing zeros into the vacated bits. If ++@var{count} is negative, @code{lsh} shifts zeros into the leftmost ++(most-significant) bit, producing a positive result even if ++@var{integer1} is negative. Contrast this with @code{ash}, below. ++ ++Here are two examples of @code{lsh}, shifting a pattern of bits one ++place to the left. We show only the low-order eight bits of the binary ++pattern; the rest are all zero. ++ ++@example ++@group ++(lsh 5 1) ++ @result{} 10 ++;; @r{Decimal 5 becomes decimal 10.} ++00000101 @result{} 00001010 ++ ++(lsh 7 1) ++ @result{} 14 ++;; @r{Decimal 7 becomes decimal 14.} ++00000111 @result{} 00001110 ++@end group ++@end example ++ ++@noindent ++As the examples illustrate, shifting the pattern of bits one place to ++the left produces a number that is twice the value of the previous ++number. ++ ++Shifting a pattern of bits two places to the left produces results ++like this (with 8-bit binary numbers): ++ ++@example ++@group ++(lsh 3 2) ++ @result{} 12 ++;; @r{Decimal 3 becomes decimal 12.} ++00000011 @result{} 00001100 ++@end group ++@end example ++ ++On the other hand, shifting one place to the right looks like this: ++ ++@example ++@group ++(lsh 6 -1) ++ @result{} 3 ++;; @r{Decimal 6 becomes decimal 3.} ++00000110 @result{} 00000011 ++@end group ++ ++@group ++(lsh 5 -1) ++ @result{} 2 ++;; @r{Decimal 5 becomes decimal 2.} ++00000101 @result{} 00000010 ++@end group ++@end example ++ ++@noindent ++As the example illustrates, shifting one place to the right divides the ++value of a positive integer by two, rounding downward. ++ ++The function @code{lsh}, like all Emacs Lisp arithmetic functions, does ++not check for overflow, so shifting left can discard significant bits ++and change the sign of the number. For example, left shifting ++268,435,455 produces @minus{}2 on a 29-bit machine: ++ ++@example ++(lsh 268435455 1) ; @r{left shift} ++ @result{} -2 ++@end example ++ ++In binary, in the 29-bit implementation, the argument looks like this: ++ ++@example ++@group ++;; @r{Decimal 268,435,455} ++0 1111 1111 1111 1111 1111 1111 1111 ++@end group ++@end example ++ ++@noindent ++which becomes the following when left shifted: ++ ++@example ++@group ++;; @r{Decimal @minus{}2} ++1 1111 1111 1111 1111 1111 1111 1110 ++@end group ++@end example ++@end defun ++ ++@defun ash integer1 count ++@cindex arithmetic shift ++@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} ++to the left @var{count} places, or to the right if @var{count} ++is negative. ++ ++@code{ash} gives the same results as @code{lsh} except when ++@var{integer1} and @var{count} are both negative. In that case, ++@code{ash} puts ones in the empty bit positions on the left, while ++@code{lsh} puts zeros in those bit positions. ++ ++Thus, with @code{ash}, shifting the pattern of bits one place to the right ++looks like this: ++ ++@example ++@group ++(ash -6 -1) @result{} -3 ++;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} ++1 1111 1111 1111 1111 1111 1111 1010 ++ @result{} ++1 1111 1111 1111 1111 1111 1111 1101 ++@end group ++@end example ++ ++In contrast, shifting the pattern of bits one place to the right with ++@code{lsh} looks like this: ++ ++@example ++@group ++(lsh -6 -1) @result{} 268435453 ++;; @r{Decimal @minus{}6 becomes decimal 268,435,453.} ++1 1111 1111 1111 1111 1111 1111 1010 ++ @result{} ++0 1111 1111 1111 1111 1111 1111 1101 ++@end group ++@end example ++ ++Here are other examples: ++ ++@c !!! Check if lined up in smallbook format! XDVI shows problem ++@c with smallbook but not with regular book! --rjc 16mar92 ++@smallexample ++@group ++ ; @r{ 29-bit binary values} ++ ++(lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} ++ @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100} ++@end group ++@group ++(ash 5 2) ++ @result{} 20 ++(lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} ++ @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100} ++(ash -5 2) ++ @result{} -20 ++@end group ++@group ++(lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} ++ @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001} ++@end group ++@group ++(ash 5 -2) ++ @result{} 1 ++@end group ++@group ++(lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} ++ @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110} ++@end group ++@group ++(ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} ++ @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110} ++@end group ++@end smallexample ++@end defun ++ ++@defun logand &rest ints-or-markers ++This function returns the ``logical and'' of the arguments: the ++@var{n}th bit is set in the result if, and only if, the @var{n}th bit is ++set in all the arguments. (``Set'' means that the value of the bit is 1 ++rather than 0.) ++ ++For example, using 4-bit binary numbers, the ``logical and'' of 13 and ++12 is 12: 1101 combined with 1100 produces 1100. ++In both the binary numbers, the leftmost two bits are set (i.e., they ++are 1's), so the leftmost two bits of the returned value are set. ++However, for the rightmost two bits, each is zero in at least one of ++the arguments, so the rightmost two bits of the returned value are 0's. ++ ++@noindent ++Therefore, ++ ++@example ++@group ++(logand 13 12) ++ @result{} 12 ++@end group ++@end example ++ ++If @code{logand} is not passed any argument, it returns a value of ++@minus{}1. This number is an identity element for @code{logand} ++because its binary representation consists entirely of ones. If ++@code{logand} is passed just one argument, it returns that argument. ++ ++@smallexample ++@group ++ ; @r{ 29-bit binary values} ++ ++(logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} ++ ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} ++ @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} ++@end group ++ ++@group ++(logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} ++ ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} ++ ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} ++ @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} ++@end group ++ ++@group ++(logand) ++ @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111} ++@end group ++@end smallexample ++@end defun ++ ++@defun logior &rest ints-or-markers ++This function returns the ``inclusive or'' of its arguments: the @var{n}th bit ++is set in the result if, and only if, the @var{n}th bit is set in at least ++one of the arguments. If there are no arguments, the result is zero, ++which is an identity element for this operation. If @code{logior} is ++passed just one argument, it returns that argument. ++ ++@smallexample ++@group ++ ; @r{ 29-bit binary values} ++ ++(logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} ++ ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} ++ @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} ++@end group ++ ++@group ++(logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} ++ ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} ++ ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} ++ @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111} ++@end group ++@end smallexample ++@end defun ++ ++@defun logxor &rest ints-or-markers ++This function returns the ``exclusive or'' of its arguments: the ++@var{n}th bit is set in the result if, and only if, the @var{n}th bit is ++set in an odd number of the arguments. If there are no arguments, the ++result is 0, which is an identity element for this operation. If ++@code{logxor} is passed just one argument, it returns that argument. ++ ++@smallexample ++@group ++ ; @r{ 29-bit binary values} ++ ++(logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} ++ ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} ++ @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001} ++@end group ++ ++@group ++(logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} ++ ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} ++ ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} ++ @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} ++@end group ++@end smallexample ++@end defun ++ ++@defun lognot integer ++This function returns the logical complement of its argument: the @var{n}th ++bit is one in the result if, and only if, the @var{n}th bit is zero in ++@var{integer}, and vice-versa. ++ ++@example ++(lognot 5) ++ @result{} -6 ++;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} ++;; @r{becomes} ++;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010} ++@end example ++@end defun ++ ++@node Math Functions ++@section Standard Mathematical Functions ++@cindex transcendental functions ++@cindex mathematical functions ++@cindex floating-point functions ++ ++ These mathematical functions allow integers as well as floating point ++numbers as arguments. ++ ++@defun sin arg ++@defunx cos arg ++@defunx tan arg ++These are the ordinary trigonometric functions, with argument measured ++in radians. ++@end defun ++ ++@defun asin arg ++The value of @code{(asin @var{arg})} is a number between ++@ifnottex ++@minus{}pi/2 ++@end ifnottex ++@tex ++@math{-\pi/2} ++@end tex ++and ++@ifnottex ++pi/2 ++@end ifnottex ++@tex ++@math{\pi/2} ++@end tex ++(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of ++range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. ++@end defun ++ ++@defun acos arg ++The value of @code{(acos @var{arg})} is a number between 0 and ++@ifnottex ++pi ++@end ifnottex ++@tex ++@math{\pi} ++@end tex ++(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out ++of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. ++@end defun ++ ++@defun atan y &optional x ++The value of @code{(atan @var{y})} is a number between ++@ifnottex ++@minus{}pi/2 ++@end ifnottex ++@tex ++@math{-\pi/2} ++@end tex ++and ++@ifnottex ++pi/2 ++@end ifnottex ++@tex ++@math{\pi/2} ++@end tex ++(exclusive) whose tangent is @var{y}. If the optional second ++argument @var{x} is given, the value of @code{(atan y x)} is the ++angle in radians between the vector @code{[@var{x}, @var{y}]} and the ++@code{X} axis. ++@end defun ++ ++@defun exp arg ++This is the exponential function; it returns ++@tex ++@math{e} ++@end tex ++@ifnottex ++@i{e} ++@end ifnottex ++to the power @var{arg}. ++@tex ++@math{e} ++@end tex ++@ifnottex ++@i{e} ++@end ifnottex ++is a fundamental mathematical constant also called the base of natural ++logarithms. ++@end defun ++ ++@defun log arg &optional base ++This function returns the logarithm of @var{arg}, with base @var{base}. ++If you don't specify @var{base}, the base ++@tex ++@math{e} ++@end tex ++@ifnottex ++@i{e} ++@end ifnottex ++is used. If @var{arg} is negative, it signals a @code{domain-error} ++error. ++@end defun ++ ++@ignore ++@defun expm1 arg ++This function returns @code{(1- (exp @var{arg}))}, but it is more ++accurate than that when @var{arg} is negative and @code{(exp @var{arg})} ++is close to 1. ++@end defun ++ ++@defun log1p arg ++This function returns @code{(log (1+ @var{arg}))}, but it is more ++accurate than that when @var{arg} is so small that adding 1 to it would ++lose accuracy. ++@end defun ++@end ignore ++ ++@defun log10 arg ++This function returns the logarithm of @var{arg}, with base 10. If ++@var{arg} is negative, it signals a @code{domain-error} error. ++@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least ++approximately. ++@end defun ++ ++@defun expt x y ++This function returns @var{x} raised to power @var{y}. If both ++arguments are integers and @var{y} is positive, the result is an ++integer; in this case, overflow causes truncation, so watch out. ++@end defun ++ ++@defun sqrt arg ++This returns the square root of @var{arg}. If @var{arg} is negative, ++it signals a @code{domain-error} error. ++@end defun ++ ++@node Random Numbers ++@section Random Numbers ++@cindex random numbers ++ ++A deterministic computer program cannot generate true random numbers. ++For most purposes, @dfn{pseudo-random numbers} suffice. A series of ++pseudo-random numbers is generated in a deterministic fashion. The ++numbers are not truly random, but they have certain properties that ++mimic a random series. For example, all possible values occur equally ++often in a pseudo-random series. ++ ++In Emacs, pseudo-random numbers are generated from a ``seed'' number. ++Starting from any given seed, the @code{random} function always ++generates the same sequence of numbers. Emacs always starts with the ++same seed value, so the sequence of values of @code{random} is actually ++the same in each Emacs run! For example, in one operating system, the ++first call to @code{(random)} after you start Emacs always returns ++@minus{}1457731, and the second one always returns @minus{}7692030. This ++repeatability is helpful for debugging. ++ ++If you want random numbers that don't always come out the same, execute ++@code{(random t)}. This chooses a new seed based on the current time of ++day and on Emacs's process @acronym{ID} number. ++ ++@defun random &optional limit ++This function returns a pseudo-random integer. Repeated calls return a ++series of pseudo-random integers. ++ ++If @var{limit} is a positive integer, the value is chosen to be ++nonnegative and less than @var{limit}. ++ ++If @var{limit} is @code{t}, it means to choose a new seed based on the ++current time of day and on Emacs's process @acronym{ID} number. ++@c "Emacs'" is incorrect usage! ++ ++On some machines, any integer representable in Lisp may be the result ++of @code{random}. On other machines, the result can never be larger ++than a certain maximum or less than a certain (negative) minimum. ++@end defun ++ ++@ignore ++ arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e ++@end ignore +diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi +new file mode 100644 +index 0000000..2145b9b +--- /dev/null ++++ b/doc/lispref/objects.texi +@@ -0,0 +1,2101 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/objects ++@node Lisp Data Types, Numbers, Introduction, Top ++@chapter Lisp Data Types ++@cindex object ++@cindex Lisp object ++@cindex type ++@cindex data type ++ ++ A Lisp @dfn{object} is a piece of data used and manipulated by Lisp ++programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of ++possible objects. ++ ++ Every object belongs to at least one type. Objects of the same type ++have similar structures and may usually be used in the same contexts. ++Types can overlap, and objects can belong to two or more types. ++Consequently, we can ask whether an object belongs to a particular type, ++but not for ``the'' type of an object. ++ ++@cindex primitive type ++ A few fundamental object types are built into Emacs. These, from ++which all other types are constructed, are called @dfn{primitive types}. ++Each object belongs to one and only one primitive type. These types ++include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol}, ++@dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and ++@dfn{byte-code function}, plus several special types, such as ++@dfn{buffer}, that are related to editing. (@xref{Editing Types}.) ++ ++ Each primitive type has a corresponding Lisp function that checks ++whether an object is a member of that type. ++ ++ Lisp is unlike many other languages in that its objects are ++@dfn{self-typing}: the primitive type of each object is implicit in ++the object itself. For example, if an object is a vector, nothing can ++treat it as a number; Lisp knows it is a vector, not a number. ++ ++ In most languages, the programmer must declare the data type of each ++variable, and the type is known by the compiler but not represented in ++the data. Such type declarations do not exist in Emacs Lisp. A Lisp ++variable can have any type of value, and it remembers whatever value ++you store in it, type and all. (Actually, a small number of Emacs ++Lisp variables can only take on values of a certain type. ++@xref{Variables with Restricted Values}.) ++ ++ This chapter describes the purpose, printed representation, and read ++syntax of each of the standard types in GNU Emacs Lisp. Details on how ++to use these types can be found in later chapters. ++ ++@menu ++* Printed Representation:: How Lisp objects are represented as text. ++* Comments:: Comments and their formatting conventions. ++* Programming Types:: Types found in all Lisp systems. ++* Editing Types:: Types specific to Emacs. ++* Circular Objects:: Read syntax for circular structure. ++* Type Predicates:: Tests related to types. ++* Equality Predicates:: Tests of equality between any two objects. ++@end menu ++ ++@node Printed Representation ++@comment node-name, next, previous, up ++@section Printed Representation and Read Syntax ++@cindex printed representation ++@cindex read syntax ++ ++ The @dfn{printed representation} of an object is the format of the ++output generated by the Lisp printer (the function @code{prin1}) for ++that object. Every data type has a unique printed representation. ++The @dfn{read syntax} of an object is the format of the input accepted ++by the Lisp reader (the function @code{read}) for that object. This ++is not necessarily unique; many kinds of object have more than one ++syntax. @xref{Read and Print}. ++ ++@cindex hash notation ++ In most cases, an object's printed representation is also a read ++syntax for the object. However, some types have no read syntax, since ++it does not make sense to enter objects of these types as constants in ++a Lisp program. These objects are printed in @dfn{hash notation}, ++which consists of the characters @samp{#<}, a descriptive string ++(typically the type name followed by the name of the object), and a ++closing @samp{>}. For example: ++ ++@example ++(current-buffer) ++ @result{} # ++@end example ++ ++@noindent ++Hash notation cannot be read at all, so the Lisp reader signals the ++error @code{invalid-read-syntax} whenever it encounters @samp{#<}. ++@kindex invalid-read-syntax ++ ++ In other languages, an expression is text; it has no other form. In ++Lisp, an expression is primarily a Lisp object and only secondarily the ++text that is the object's read syntax. Often there is no need to ++emphasize this distinction, but you must keep it in the back of your ++mind, or you will occasionally be very confused. ++ ++ When you evaluate an expression interactively, the Lisp interpreter ++first reads the textual representation of it, producing a Lisp object, ++and then evaluates that object (@pxref{Evaluation}). However, ++evaluation and reading are separate activities. Reading returns the ++Lisp object represented by the text that is read; the object may or may ++not be evaluated later. @xref{Input Functions}, for a description of ++@code{read}, the basic function for reading objects. ++ ++@node Comments ++@comment node-name, next, previous, up ++@section Comments ++@cindex comments ++@cindex @samp{;} in comment ++ ++ A @dfn{comment} is text that is written in a program only for the sake ++of humans that read the program, and that has no effect on the meaning ++of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it ++is not within a string or character constant. The comment continues to ++the end of line. The Lisp reader discards comments; they do not become ++part of the Lisp objects which represent the program within the Lisp ++system. ++ ++ The @samp{#@@@var{count}} construct, which skips the next @var{count} ++characters, is useful for program-generated comments containing binary ++data. The Emacs Lisp byte compiler uses this in its output files ++(@pxref{Byte Compilation}). It isn't meant for source files, however. ++ ++ @xref{Comment Tips}, for conventions for formatting comments. ++ ++@node Programming Types ++@section Programming Types ++@cindex programming types ++ ++ There are two general categories of types in Emacs Lisp: those having ++to do with Lisp programming, and those having to do with editing. The ++former exist in many Lisp implementations, in one form or another. The ++latter are unique to Emacs Lisp. ++ ++@menu ++* Integer Type:: Numbers without fractional parts. ++* Floating Point Type:: Numbers with fractional parts and with a large range. ++* Character Type:: The representation of letters, numbers and ++ control characters. ++* Symbol Type:: A multi-use object that refers to a function, ++ variable, or property list, and has a unique identity. ++* Sequence Type:: Both lists and arrays are classified as sequences. ++* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). ++* Array Type:: Arrays include strings and vectors. ++* String Type:: An (efficient) array of characters. ++* Vector Type:: One-dimensional arrays. ++* Char-Table Type:: One-dimensional sparse arrays indexed by characters. ++* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. ++* Hash Table Type:: Super-fast lookup tables. ++* Function Type:: A piece of executable code you can call from elsewhere. ++* Macro Type:: A method of expanding an expression into another ++ expression, more fundamental but less pretty. ++* Primitive Function Type:: A function written in C, callable from Lisp. ++* Byte-Code Type:: A function written in Lisp, then compiled. ++* Autoload Type:: A type used for automatically loading seldom-used ++ functions. ++@end menu ++ ++@node Integer Type ++@subsection Integer Type ++ ++ The range of values for integers in Emacs Lisp is @minus{}268435456 to ++268435455 (29 bits; i.e., ++@ifnottex ++-2**28 ++@end ifnottex ++@tex ++@math{-2^{28}} ++@end tex ++to ++@ifnottex ++2**28 - 1) ++@end ifnottex ++@tex ++@math{2^{28}-1}) ++@end tex ++on most machines. (Some machines may provide a wider range.) It is ++important to note that the Emacs Lisp arithmetic functions do not check ++for overflow. Thus @code{(1+ 268435455)} is @minus{}268435456 on most ++machines. ++ ++ The read syntax for integers is a sequence of (base ten) digits with an ++optional sign at the beginning and an optional period at the end. The ++printed representation produced by the Lisp interpreter never has a ++leading @samp{+} or a final @samp{.}. ++ ++@example ++@group ++-1 ; @r{The integer -1.} ++1 ; @r{The integer 1.} ++1. ; @r{Also the integer 1.} +++1 ; @r{Also the integer 1.} ++536870913 ; @r{Also the integer 1 on a 29-bit implementation.} ++@end group ++@end example ++ ++ @xref{Numbers}, for more information. ++ ++@node Floating Point Type ++@subsection Floating Point Type ++ ++ Floating point numbers are the computer equivalent of scientific ++notation; you can think of a floating point number as a fraction ++together with a power of ten. The precise number of significant ++figures and the range of possible exponents is machine-specific; Emacs ++uses the C data type @code{double} to store the value, and internally ++this records a power of 2 rather than a power of 10. ++ ++ The printed representation for floating point numbers requires either ++a decimal point (with at least one digit following), an exponent, or ++both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, ++@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point ++number whose value is 1500. They are all equivalent. ++ ++ @xref{Numbers}, for more information. ++ ++@node Character Type ++@subsection Character Type ++@cindex @acronym{ASCII} character codes ++ ++ A @dfn{character} in Emacs Lisp is nothing more than an integer. In ++other words, characters are represented by their character codes. For ++example, the character @kbd{A} is represented as the @w{integer 65}. ++ ++ Individual characters are used occasionally in programs, but it is ++more common to work with @emph{strings}, which are sequences composed ++of characters. @xref{String Type}. ++ ++ Characters in strings and buffers are currently limited to the range ++of 0 to 4194303---twenty two bits (@pxref{Character Codes}). Codes 0 ++through 127 are @acronym{ASCII} codes; the rest are ++non-@acronym{ASCII} (@pxref{Non-ASCII Characters}). Characters that ++represent keyboard input have a much wider range, to encode modifier ++keys such as Control, Meta and Shift. ++ ++ There are special functions for producing a human-readable textual ++description of a character for the sake of messages. @xref{Describing ++Characters}. ++ ++@menu ++* Basic Char Syntax:: Syntax for regular characters. ++* General Escape Syntax:: How to specify characters by their codes. ++* Ctl-Char Syntax:: Syntax for control characters. ++* Meta-Char Syntax:: Syntax for meta-characters. ++* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. ++@end menu ++ ++@node Basic Char Syntax ++@subsubsection Basic Char Syntax ++@cindex read syntax for characters ++@cindex printed representation for characters ++@cindex syntax for characters ++@cindex @samp{?} in character constant ++@cindex question mark in character constant ++ ++ Since characters are really integers, the printed representation of ++a character is a decimal number. This is also a possible read syntax ++for a character, but writing characters that way in Lisp programs is ++not clear programming. You should @emph{always} use the special read ++syntax formats that Emacs Lisp provides for characters. These syntax ++formats start with a question mark. ++ ++ The usual read syntax for alphanumeric characters is a question mark ++followed by the character; thus, @samp{?A} for the character ++@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the ++character @kbd{a}. ++ ++ For example: ++ ++@example ++?Q @result{} 81 ?q @result{} 113 ++@end example ++ ++ You can use the same syntax for punctuation characters, but it is ++often a good idea to add a @samp{\} so that the Emacs commands for ++editing Lisp code don't get confused. For example, @samp{?\(} is the ++way to write the open-paren character. If the character is @samp{\}, ++you @emph{must} use a second @samp{\} to quote it: @samp{?\\}. ++ ++@cindex whitespace ++@cindex bell character ++@cindex @samp{\a} ++@cindex backspace ++@cindex @samp{\b} ++@cindex tab (ASCII character) ++@cindex @samp{\t} ++@cindex vertical tab ++@cindex @samp{\v} ++@cindex formfeed ++@cindex @samp{\f} ++@cindex newline ++@cindex @samp{\n} ++@cindex return (ASCII character) ++@cindex @samp{\r} ++@cindex escape (ASCII character) ++@cindex @samp{\e} ++@cindex space (ASCII character) ++@cindex @samp{\s} ++ You can express the characters control-g, backspace, tab, newline, ++vertical tab, formfeed, space, return, del, and escape as @samp{?\a}, ++@samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, ++@samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively. ++(@samp{?\s} followed by a dash has a different meaning---it applies ++the ``super'' modifier to the following character.) Thus, ++ ++@example ++?\a @result{} 7 ; @r{control-g, @kbd{C-g}} ++?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}} ++?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}} ++?\n @result{} 10 ; @r{newline, @kbd{C-j}} ++?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}} ++?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}} ++?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}} ++?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}} ++?\s @result{} 32 ; @r{space character, @key{SPC}} ++?\\ @result{} 92 ; @r{backslash character, @kbd{\}} ++?\d @result{} 127 ; @r{delete character, @key{DEL}} ++@end example ++ ++@cindex escape sequence ++ These sequences which start with backslash are also known as ++@dfn{escape sequences}, because backslash plays the role of an ++``escape character''; this terminology has nothing to do with the ++character @key{ESC}. @samp{\s} is meant for use in character ++constants; in string constants, just write the space. ++ ++ A backslash is allowed, and harmless, preceding any character without ++a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}. ++There is no reason to add a backslash before most characters. However, ++you should add a backslash before any of the characters ++@samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing ++Lisp code. You can also add a backslash before whitespace characters such as ++space, tab, newline and formfeed. However, it is cleaner to use one of ++the easily readable escape sequences, such as @samp{\t} or @samp{\s}, ++instead of an actual whitespace character such as a tab or a space. ++(If you do write backslash followed by a space, you should write ++an extra space after the character constant to separate it from the ++following text.) ++ ++@node General Escape Syntax ++@subsubsection General Escape Syntax ++ ++ In addition to the specific escape sequences for special important ++control characters, Emacs provides several types of escape syntax that ++you can use to specify non-ASCII text characters. ++ ++@cindex unicode character escape ++ You can specify characters by their Unicode values. ++@code{?\u@var{nnnn}} represents a character that maps to the Unicode ++code point @samp{U+@var{nnnn}} (by convention, Unicode code points are ++given in hexadecimal). There is a slightly different syntax for ++specifying characters with code points higher than ++@code{U+@var{ffff}}: @code{\U00@var{nnnnnn}} represents the character ++whose code point is @samp{U+@var{nnnnnn}}. The Unicode Standard only ++defines code points up to @samp{U+@var{10ffff}}, so if you specify a ++code point higher than that, Emacs signals an error. ++ ++ This peculiar and inconvenient syntax was adopted for compatibility ++with other programming languages. Unlike some other languages, Emacs ++Lisp supports this syntax only in character literals and strings. ++ ++@cindex @samp{\} in character constant ++@cindex backslash in character constant ++@cindex octal character code ++ The most general read syntax for a character represents the ++character code in either octal or hex. To use octal, write a question ++mark followed by a backslash and the octal character code (up to three ++octal digits); thus, @samp{?\101} for the character @kbd{A}, ++@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the ++character @kbd{C-b}. Although this syntax can represent any ++@acronym{ASCII} character, it is preferred only when the precise octal ++value is more important than the @acronym{ASCII} representation. ++ ++@example ++@group ++?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10 ++?\101 @result{} 65 ?A @result{} 65 ++@end group ++@end example ++ ++ To use hex, write a question mark followed by a backslash, @samp{x}, ++and the hexadecimal character code. You can use any number of hex ++digits, so you can represent any character code in this way. ++Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the ++character @kbd{C-a}, and @code{?\x8e0} for the Latin-1 character ++@iftex ++@samp{@`a}. ++@end iftex ++@ifnottex ++@samp{a} with grave accent. ++@end ifnottex ++ ++@node Ctl-Char Syntax ++@subsubsection Control-Character Syntax ++ ++@cindex control characters ++ Control characters can be represented using yet another read syntax. ++This consists of a question mark followed by a backslash, caret, and the ++corresponding non-control character, in either upper or lower case. For ++example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the ++character @kbd{C-i}, the character whose value is 9. ++ ++ Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is ++equivalent to @samp{?\^I} and to @samp{?\^i}: ++ ++@example ++?\^I @result{} 9 ?\C-I @result{} 9 ++@end example ++ ++ In strings and buffers, the only control characters allowed are those ++that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn ++any character into a control character with @samp{C-}. The character ++codes for these non-@acronym{ASCII} control characters include the ++@tex ++@math{2^{26}} ++@end tex ++@ifnottex ++2**26 ++@end ifnottex ++bit as well as the code for the corresponding non-control ++character. Ordinary terminals have no way of generating non-@acronym{ASCII} ++control characters, but you can generate them straightforwardly using X ++and other window systems. ++ ++ For historical reasons, Emacs treats the @key{DEL} character as ++the control equivalent of @kbd{?}: ++ ++@example ++?\^? @result{} 127 ?\C-? @result{} 127 ++@end example ++ ++@noindent ++As a result, it is currently not possible to represent the character ++@kbd{Control-?}, which is a meaningful input character under X, using ++@samp{\C-}. It is not easy to change this, as various Lisp files refer ++to @key{DEL} in this way. ++ ++ For representing control characters to be found in files or strings, ++we recommend the @samp{^} syntax; for control characters in keyboard ++input, we prefer the @samp{C-} syntax. Which one you use does not ++affect the meaning of the program, but may guide the understanding of ++people who read it. ++ ++@node Meta-Char Syntax ++@subsubsection Meta-Character Syntax ++ ++@cindex meta characters ++ A @dfn{meta character} is a character typed with the @key{META} ++modifier key. The integer that represents such a character has the ++@tex ++@math{2^{27}} ++@end tex ++@ifnottex ++2**27 ++@end ifnottex ++bit set. We use high bits for this and other modifiers to make ++possible a wide range of basic character codes. ++ ++ In a string, the ++@tex ++@math{2^{7}} ++@end tex ++@ifnottex ++2**7 ++@end ifnottex ++bit attached to an @acronym{ASCII} character indicates a meta ++character; thus, the meta characters that can fit in a string have ++codes in the range from 128 to 255, and are the meta versions of the ++ordinary @acronym{ASCII} characters. (In Emacs versions 18 and older, ++this convention was used for characters outside of strings as well.) ++ ++ The read syntax for meta characters uses @samp{\M-}. For example, ++@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with ++octal character codes (see below), with @samp{\C-}, or with any other ++syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A}, ++or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as ++@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}. ++ ++@node Other Char Bits ++@subsubsection Other Character Modifier Bits ++ ++ The case of a graphic character is indicated by its character code; ++for example, @acronym{ASCII} distinguishes between the characters @samp{a} ++and @samp{A}. But @acronym{ASCII} has no way to represent whether a control ++character is upper case or lower case. Emacs uses the ++@tex ++@math{2^{25}} ++@end tex ++@ifnottex ++2**25 ++@end ifnottex ++bit to indicate that the shift key was used in typing a control ++character. This distinction is possible only when you use X terminals ++or other special terminals; ordinary terminals do not report the ++distinction to the computer in any way. The Lisp syntax for ++the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O} ++represents the shifted-control-o character. ++ ++@cindex hyper characters ++@cindex super characters ++@cindex alt characters ++ The X Window System defines three other ++@anchor{modifier bits}modifier bits that can be set ++in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes ++for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is ++significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents ++@kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-} ++represents the space character.) ++@tex ++Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}} ++for super and @math{2^{24}} for hyper. ++@end tex ++@ifnottex ++Numerically, the ++bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper. ++@end ifnottex ++ ++@node Symbol Type ++@subsection Symbol Type ++ ++ A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The ++symbol name serves as the printed representation of the symbol. In ++ordinary Lisp use, with one single obarray (@pxref{Creating Symbols}), ++a symbol's name is unique---no two symbols have the same name. ++ ++ A symbol can serve as a variable, as a function name, or to hold a ++property list. Or it may serve only to be distinct from all other Lisp ++objects, so that its presence in a data structure may be recognized ++reliably. In a given context, usually only one of these uses is ++intended. But you can use one symbol in all of these ways, ++independently. ++ ++ A symbol whose name starts with a colon (@samp{:}) is called a ++@dfn{keyword symbol}. These symbols automatically act as constants, and ++are normally used only by comparing an unknown symbol with a few ++specific alternatives. ++ ++@cindex @samp{\} in symbols ++@cindex backslash in symbols ++ A symbol name can contain any characters whatever. Most symbol names ++are written with letters, digits, and the punctuation characters ++@samp{-+=*/}. Such names require no special punctuation; the characters ++of the name suffice as long as the name does not look like a number. ++(If it does, write a @samp{\} at the beginning of the name to force ++interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are ++less often used but also require no special punctuation. Any other ++characters may be included in a symbol's name by escaping them with a ++backslash. In contrast to its use in strings, however, a backslash in ++the name of a symbol simply quotes the single character that follows the ++backslash. For example, in a string, @samp{\t} represents a tab ++character; in the name of a symbol, however, @samp{\t} merely quotes the ++letter @samp{t}. To have a symbol with a tab character in its name, you ++must actually use a tab (preceded with a backslash). But it's rare to ++do such a thing. ++ ++@cindex CL note---case of letters ++@quotation ++@b{Common Lisp note:} In Common Lisp, lower case letters are always ++``folded'' to upper case, unless they are explicitly escaped. In Emacs ++Lisp, upper case and lower case letters are distinct. ++@end quotation ++ ++ Here are several examples of symbol names. Note that the @samp{+} in ++the fifth example is escaped to prevent it from being read as a number. ++This is not necessary in the fourth example because the rest of the name ++makes it invalid as a number. ++ ++@example ++@group ++foo ; @r{A symbol named @samp{foo}.} ++FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} ++char-to-string ; @r{A symbol named @samp{char-to-string}.} ++@end group ++@group ++1+ ; @r{A symbol named @samp{1+}} ++ ; @r{(not @samp{+1}, which is an integer).} ++@end group ++@group ++\+1 ; @r{A symbol named @samp{+1}} ++ ; @r{(not a very readable name).} ++@end group ++@group ++\(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).} ++@c the @'s in this next line use up three characters, hence the ++@c apparent misalignment of the comment. +++-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.} ++ ; @r{These characters need not be escaped.} ++@end group ++@end example ++ ++@ifinfo ++@c This uses ``colon'' instead of a literal `:' because Info cannot ++@c cope with a `:' in a menu ++@cindex @samp{#@var{colon}} read syntax ++@end ifinfo ++@ifnotinfo ++@cindex @samp{#:} read syntax ++@end ifnotinfo ++ Normally the Lisp reader interns all symbols (@pxref{Creating ++Symbols}). To prevent interning, you can write @samp{#:} before the ++name of the symbol. ++ ++@node Sequence Type ++@subsection Sequence Types ++ ++ A @dfn{sequence} is a Lisp object that represents an ordered set of ++elements. There are two kinds of sequence in Emacs Lisp, lists and ++arrays. Thus, an object of type list or of type array is also ++considered a sequence. ++ ++ Arrays are further subdivided into strings, vectors, char-tables and ++bool-vectors. Vectors can hold elements of any type, but string ++elements must be characters, and bool-vector elements must be @code{t} ++or @code{nil}. Char-tables are like vectors except that they are ++indexed by any valid character code. The characters in a string can ++have text properties like characters in a buffer (@pxref{Text ++Properties}), but vectors do not support text properties, even when ++their elements happen to be characters. ++ ++ Lists, strings and the other array types are different, but they have ++important similarities. For example, all have a length @var{l}, and all ++have elements which can be indexed from zero to @var{l} minus one. ++Several functions, called sequence functions, accept any kind of ++sequence. For example, the function @code{elt} can be used to extract ++an element of a sequence, given its index. @xref{Sequences Arrays ++Vectors}. ++ ++ It is generally impossible to read the same sequence twice, since ++sequences are always created anew upon reading. If you read the read ++syntax for a sequence twice, you get two sequences with equal contents. ++There is one exception: the empty list @code{()} always stands for the ++same object, @code{nil}. ++ ++@node Cons Cell Type ++@subsection Cons Cell and List Types ++@cindex address field of register ++@cindex decrement field of register ++@cindex pointers ++ ++ A @dfn{cons cell} is an object that consists of two slots, called the ++@sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or ++@dfn{refer to} any Lisp object. We also say that ``the @sc{car} of ++this cons cell is'' whatever object its @sc{car} slot currently holds, ++and likewise for the @sc{cdr}. ++ ++@quotation ++A note to C programmers: in Lisp, we do not distinguish between ++``holding'' a value and ``pointing to'' the value, because pointers in ++Lisp are implicit. ++@end quotation ++ ++ A @dfn{list} is a series of cons cells, linked together so that the ++@sc{cdr} slot of each cons cell holds either the next cons cell or the ++empty list. The empty list is actually the symbol @code{nil}. ++@xref{Lists}, for functions that work on lists. Because most cons ++cells are used as part of lists, the phrase @dfn{list structure} has ++come to refer to any structure made out of cons cells. ++ ++@cindex atoms ++ Because cons cells are so central to Lisp, we also have a word for ++``an object which is not a cons cell.'' These objects are called ++@dfn{atoms}. ++ ++@cindex parenthesis ++@cindex @samp{(@dots{})} in lists ++ The read syntax and printed representation for lists are identical, and ++consist of a left parenthesis, an arbitrary number of elements, and a ++right parenthesis. Here are examples of lists: ++ ++@example ++(A 2 "A") ; @r{A list of three elements.} ++() ; @r{A list of no elements (the empty list).} ++nil ; @r{A list of no elements (the empty list).} ++("A ()") ; @r{A list of one element: the string @code{"A ()"}.} ++(A ()) ; @r{A list of two elements: @code{A} and the empty list.} ++(A nil) ; @r{Equivalent to the previous.} ++((A B C)) ; @r{A list of one element} ++ ; @r{(which is a list of three elements).} ++@end example ++ ++ Upon reading, each object inside the parentheses becomes an element ++of the list. That is, a cons cell is made for each element. The ++@sc{car} slot of the cons cell holds the element, and its @sc{cdr} ++slot refers to the next cons cell of the list, which holds the next ++element in the list. The @sc{cdr} slot of the last cons cell is set to ++hold @code{nil}. ++ ++ The names @sc{car} and @sc{cdr} derive from the history of Lisp. The ++original Lisp implementation ran on an @w{IBM 704} computer which ++divided words into two parts, called the ``address'' part and the ++``decrement''; @sc{car} was an instruction to extract the contents of ++the address part of a register, and @sc{cdr} an instruction to extract ++the contents of the decrement. By contrast, ``cons cells'' are named ++for the function @code{cons} that creates them, which in turn was named ++for its purpose, the construction of cells. ++ ++@menu ++* Box Diagrams:: Drawing pictures of lists. ++* Dotted Pair Notation:: A general syntax for cons cells. ++* Association List Type:: A specially constructed list. ++@end menu ++ ++@node Box Diagrams ++@subsubsection Drawing Lists as Box Diagrams ++@cindex box diagrams, for lists ++@cindex diagrams, boxed, for lists ++ ++ A list can be illustrated by a diagram in which the cons cells are ++shown as pairs of boxes, like dominoes. (The Lisp reader cannot read ++such an illustration; unlike the textual notation, which can be ++understood by both humans and computers, the box illustrations can be ++understood only by humans.) This picture represents the three-element ++list @code{(rose violet buttercup)}: ++ ++@example ++@group ++ --- --- --- --- --- --- ++ | | |--> | | |--> | | |--> nil ++ --- --- --- --- --- --- ++ | | | ++ | | | ++ --> rose --> violet --> buttercup ++@end group ++@end example ++ ++ In this diagram, each box represents a slot that can hold or refer to ++any Lisp object. Each pair of boxes represents a cons cell. Each arrow ++represents a reference to a Lisp object, either an atom or another cons ++cell. ++ ++ In this example, the first box, which holds the @sc{car} of the first ++cons cell, refers to or ``holds'' @code{rose} (a symbol). The second ++box, holding the @sc{cdr} of the first cons cell, refers to the next ++pair of boxes, the second cons cell. The @sc{car} of the second cons ++cell is @code{violet}, and its @sc{cdr} is the third cons cell. The ++@sc{cdr} of the third (and last) cons cell is @code{nil}. ++ ++ Here is another diagram of the same list, @code{(rose violet ++buttercup)}, sketched in a different manner: ++ ++@smallexample ++@group ++ --------------- ---------------- ------------------- ++| car | cdr | | car | cdr | | car | cdr | ++| rose | o-------->| violet | o-------->| buttercup | nil | ++| | | | | | | | | ++ --------------- ---------------- ------------------- ++@end group ++@end smallexample ++ ++@cindex @code{nil} as a list ++@cindex empty list ++ A list with no elements in it is the @dfn{empty list}; it is identical ++to the symbol @code{nil}. In other words, @code{nil} is both a symbol ++and a list. ++ ++ Here is the list @code{(A ())}, or equivalently @code{(A nil)}, ++depicted with boxes and arrows: ++ ++@example ++@group ++ --- --- --- --- ++ | | |--> | | |--> nil ++ --- --- --- --- ++ | | ++ | | ++ --> A --> nil ++@end group ++@end example ++ ++ Here is a more complex illustration, showing the three-element list, ++@code{((pine needles) oak maple)}, the first element of which is a ++two-element list: ++ ++@example ++@group ++ --- --- --- --- --- --- ++ | | |--> | | |--> | | |--> nil ++ --- --- --- --- --- --- ++ | | | ++ | | | ++ | --> oak --> maple ++ | ++ | --- --- --- --- ++ --> | | |--> | | |--> nil ++ --- --- --- --- ++ | | ++ | | ++ --> pine --> needles ++@end group ++@end example ++ ++ The same list represented in the second box notation looks like this: ++ ++@example ++@group ++ -------------- -------------- -------------- ++| car | cdr | | car | cdr | | car | cdr | ++| o | o------->| oak | o------->| maple | nil | ++| | | | | | | | | | ++ -- | --------- -------------- -------------- ++ | ++ | ++ | -------------- ---------------- ++ | | car | cdr | | car | cdr | ++ ------>| pine | o------->| needles | nil | ++ | | | | | | ++ -------------- ---------------- ++@end group ++@end example ++ ++@node Dotted Pair Notation ++@subsubsection Dotted Pair Notation ++@cindex dotted pair notation ++@cindex @samp{.} in lists ++ ++ @dfn{Dotted pair notation} is a general syntax for cons cells that ++represents the @sc{car} and @sc{cdr} explicitly. In this syntax, ++@code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is ++the object @var{a} and whose @sc{cdr} is the object @var{b}. Dotted ++pair notation is more general than list syntax because the @sc{cdr} ++does not have to be a list. However, it is more cumbersome in cases ++where list syntax would work. In dotted pair notation, the list ++@samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For ++@code{nil}-terminated lists, you can use either notation, but list ++notation is usually clearer and more convenient. When printing a ++list, the dotted pair notation is only used if the @sc{cdr} of a cons ++cell is not a list. ++ ++ Here's an example using boxes to illustrate dotted pair notation. ++This example shows the pair @code{(rose . violet)}: ++ ++@example ++@group ++ --- --- ++ | | |--> violet ++ --- --- ++ | ++ | ++ --> rose ++@end group ++@end example ++ ++ You can combine dotted pair notation with list notation to represent ++conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}. ++You write a dot after the last element of the list, followed by the ++@sc{cdr} of the final cons cell. For example, @code{(rose violet ++. buttercup)} is equivalent to @code{(rose . (violet . buttercup))}. ++The object looks like this: ++ ++@example ++@group ++ --- --- --- --- ++ | | |--> | | |--> buttercup ++ --- --- --- --- ++ | | ++ | | ++ --> rose --> violet ++@end group ++@end example ++ ++ The syntax @code{(rose .@: violet .@: buttercup)} is invalid because ++there is nothing that it could mean. If anything, it would say to put ++@code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already ++used for @code{violet}. ++ ++ The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}, ++and looks like this: ++ ++@example ++@group ++ --- --- --- --- ++ | | |--> | | |--> nil ++ --- --- --- --- ++ | | ++ | | ++ --> rose --> violet ++@end group ++@end example ++ ++ Similarly, the three-element list @code{(rose violet buttercup)} ++is equivalent to @code{(rose . (violet . (buttercup)))}. ++@ifnottex ++It looks like this: ++ ++@example ++@group ++ --- --- --- --- --- --- ++ | | |--> | | |--> | | |--> nil ++ --- --- --- --- --- --- ++ | | | ++ | | | ++ --> rose --> violet --> buttercup ++@end group ++@end example ++@end ifnottex ++ ++@node Association List Type ++@comment node-name, next, previous, up ++@subsubsection Association List Type ++ ++ An @dfn{association list} or @dfn{alist} is a specially-constructed ++list whose elements are cons cells. In each element, the @sc{car} is ++considered a @dfn{key}, and the @sc{cdr} is considered an ++@dfn{associated value}. (In some cases, the associated value is stored ++in the @sc{car} of the @sc{cdr}.) Association lists are often used as ++stacks, since it is easy to add or remove associations at the front of ++the list. ++ ++ For example, ++ ++@example ++(setq alist-of-colors ++ '((rose . red) (lily . white) (buttercup . yellow))) ++@end example ++ ++@noindent ++sets the variable @code{alist-of-colors} to an alist of three elements. In the ++first element, @code{rose} is the key and @code{red} is the value. ++ ++ @xref{Association Lists}, for a further explanation of alists and for ++functions that work on alists. @xref{Hash Tables}, for another kind of ++lookup table, which is much faster for handling a large number of keys. ++ ++@node Array Type ++@subsection Array Type ++ ++ An @dfn{array} is composed of an arbitrary number of slots for ++holding or referring to other Lisp objects, arranged in a contiguous block of ++memory. Accessing any element of an array takes approximately the same ++amount of time. In contrast, accessing an element of a list requires ++time proportional to the position of the element in the list. (Elements ++at the end of a list take longer to access than elements at the ++beginning of a list.) ++ ++ Emacs defines four types of array: strings, vectors, bool-vectors, and ++char-tables. ++ ++ A string is an array of characters and a vector is an array of ++arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}. ++These kinds of array may have any length up to the largest integer. ++Char-tables are sparse arrays indexed by any valid character code; they ++can hold arbitrary objects. ++ ++ The first element of an array has index zero, the second element has ++index 1, and so on. This is called @dfn{zero-origin} indexing. For ++example, an array of four elements has indices 0, 1, 2, @w{and 3}. The ++largest possible index value is one less than the length of the array. ++Once an array is created, its length is fixed. ++ ++ All Emacs Lisp arrays are one-dimensional. (Most other programming ++languages support multidimensional arrays, but they are not essential; ++you can get the same effect with nested one-dimensional arrays.) Each ++type of array has its own read syntax; see the following sections for ++details. ++ ++ The array type is a subset of the sequence type, and contains the ++string type, the vector type, the bool-vector type, and the char-table ++type. ++ ++@node String Type ++@subsection String Type ++ ++ A @dfn{string} is an array of characters. Strings are used for many ++purposes in Emacs, as can be expected in a text editor; for example, as ++the names of Lisp symbols, as messages for the user, and to represent ++text extracted from buffers. Strings in Lisp are constants: evaluation ++of a string returns the same string. ++ ++ @xref{Strings and Characters}, for functions that operate on strings. ++ ++@menu ++* Syntax for Strings:: How to specify Lisp strings. ++* Non-ASCII in Strings:: International characters in strings. ++* Nonprinting Characters:: Literal unprintable characters in strings. ++* Text Props and Strings:: Strings with text properties. ++@end menu ++ ++@node Syntax for Strings ++@subsubsection Syntax for Strings ++ ++@cindex @samp{"} in strings ++@cindex double-quote in strings ++@cindex @samp{\} in strings ++@cindex backslash in strings ++ The read syntax for a string is a double-quote, an arbitrary number ++of characters, and another double-quote, @code{"like this"}. To ++include a double-quote in a string, precede it with a backslash; thus, ++@code{"\""} is a string containing just a single double-quote ++character. Likewise, you can include a backslash by preceding it with ++another backslash, like this: @code{"this \\ is a single embedded ++backslash"}. ++ ++@cindex newline in strings ++ The newline character is not special in the read syntax for strings; ++if you write a new line between the double-quotes, it becomes a ++character in the string. But an escaped newline---one that is preceded ++by @samp{\}---does not become part of the string; i.e., the Lisp reader ++ignores an escaped newline while reading a string. An escaped space ++@w{@samp{\ }} is likewise ignored. ++ ++@example ++"It is useful to include newlines ++in documentation strings, ++but the newline is \ ++ignored if escaped." ++ @result{} "It is useful to include newlines ++in documentation strings, ++but the newline is ignored if escaped." ++@end example ++ ++@node Non-ASCII in Strings ++@subsubsection Non-@acronym{ASCII} Characters in Strings ++ ++ You can include a non-@acronym{ASCII} international character in a string ++constant by writing it literally. There are two text representations ++for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte ++and multibyte. If the string constant is read from a multibyte source, ++such as a multibyte buffer or string, or a file that would be visited as ++multibyte, then the character is read as a multibyte character, and that ++makes the string multibyte. If the string constant is read from a ++unibyte source, then the character is read as unibyte and that makes the ++string unibyte. ++ ++ You can also represent a multibyte non-@acronym{ASCII} character with its ++character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many ++digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all ++greater than 256.) Any character which is not a valid hex digit ++terminates this construct. If the next character in the string could be ++interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to ++terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents ++one character, @samp{a} with grave accent. @w{@samp{\ }} in a string ++constant is just like backslash-newline; it does not contribute any ++character to the string, but it does terminate the preceding hex escape. ++ ++ You can represent a unibyte non-@acronym{ASCII} character with its ++character code, which must be in the range from 128 (0200 octal) to ++255 (0377 octal). If you write all such character codes in octal and ++the string contains no other characters forcing it to be multibyte, ++this produces a unibyte string. However, using any hex escape in a ++string (even for an @acronym{ASCII} character) forces the string to be ++multibyte. ++ ++ You can also specify characters in a string by their numeric values ++in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}). ++ ++ @xref{Text Representations}, for more information about the two ++text representations. ++ ++@node Nonprinting Characters ++@subsubsection Nonprinting Characters in Strings ++ ++ You can use the same backslash escape-sequences in a string constant ++as in character literals (but do not use the question mark that begins a ++character constant). For example, you can write a string containing the ++nonprinting characters tab and @kbd{C-a}, with commas and spaces between ++them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a ++description of the read syntax for characters. ++ ++ However, not all of the characters you can write with backslash ++escape-sequences are valid in strings. The only control characters that ++a string can hold are the @acronym{ASCII} control characters. Strings do not ++distinguish case in @acronym{ASCII} control characters. ++ ++ Properly speaking, strings cannot hold meta characters; but when a ++string is to be used as a key sequence, there is a special convention ++that provides a way to represent meta versions of @acronym{ASCII} ++characters in a string. If you use the @samp{\M-} syntax to indicate ++a meta character in a string constant, this sets the ++@tex ++@math{2^{7}} ++@end tex ++@ifnottex ++2**7 ++@end ifnottex ++bit of the character in the string. If the string is used in ++@code{define-key} or @code{lookup-key}, this numeric code is translated ++into the equivalent meta character. @xref{Character Type}. ++ ++ Strings cannot hold characters that have the hyper, super, or alt ++modifiers. ++ ++@node Text Props and Strings ++@subsubsection Text Properties in Strings ++ ++@cindex @samp{#(} read syntax ++@cindex text properties, read syntax ++ A string can hold properties for the characters it contains, in ++addition to the characters themselves. This enables programs that copy ++text between strings and buffers to copy the text's properties with no ++special effort. @xref{Text Properties}, for an explanation of what text ++properties mean. Strings with text properties use a special read and ++print syntax: ++ ++@example ++#("@var{characters}" @var{property-data}...) ++@end example ++ ++@noindent ++where @var{property-data} consists of zero or more elements, in groups ++of three as follows: ++ ++@example ++@var{beg} @var{end} @var{plist} ++@end example ++ ++@noindent ++The elements @var{beg} and @var{end} are integers, and together specify ++a range of indices in the string; @var{plist} is the property list for ++that range. For example, ++ ++@example ++#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic)) ++@end example ++ ++@noindent ++represents a string whose textual contents are @samp{foo bar}, in which ++the first three characters have a @code{face} property with value ++@code{bold}, and the last three have a @code{face} property with value ++@code{italic}. (The fourth character has no text properties, so its ++property list is @code{nil}. It is not actually necessary to mention ++ranges with @code{nil} as the property list, since any characters not ++mentioned in any range will default to having no properties.) ++ ++@node Vector Type ++@subsection Vector Type ++ ++ A @dfn{vector} is a one-dimensional array of elements of any type. It ++takes a constant amount of time to access any element of a vector. (In ++a list, the access time of an element is proportional to the distance of ++the element from the beginning of the list.) ++ ++ The printed representation of a vector consists of a left square ++bracket, the elements, and a right square bracket. This is also the ++read syntax. Like numbers and strings, vectors are considered constants ++for evaluation. ++ ++@example ++[1 "two" (three)] ; @r{A vector of three elements.} ++ @result{} [1 "two" (three)] ++@end example ++ ++ @xref{Vectors}, for functions that work with vectors. ++ ++@node Char-Table Type ++@subsection Char-Table Type ++ ++ A @dfn{char-table} is a one-dimensional array of elements of any type, ++indexed by character codes. Char-tables have certain extra features to ++make them more useful for many jobs that involve assigning information ++to character codes---for example, a char-table can have a parent to ++inherit from, a default value, and a small number of extra slots to use for ++special purposes. A char-table can also specify a single value for ++a whole character set. ++ ++ The printed representation of a char-table is like a vector ++except that there is an extra @samp{#^} at the beginning. ++ ++ @xref{Char-Tables}, for special functions to operate on char-tables. ++Uses of char-tables include: ++ ++@itemize @bullet ++@item ++Case tables (@pxref{Case Tables}). ++ ++@item ++Character category tables (@pxref{Categories}). ++ ++@item ++Display tables (@pxref{Display Tables}). ++ ++@item ++Syntax tables (@pxref{Syntax Tables}). ++@end itemize ++ ++@node Bool-Vector Type ++@subsection Bool-Vector Type ++ ++ A @dfn{bool-vector} is a one-dimensional array of elements that ++must be @code{t} or @code{nil}. ++ ++ The printed representation of a bool-vector is like a string, except ++that it begins with @samp{#&} followed by the length. The string ++constant that follows actually specifies the contents of the bool-vector ++as a bitmap---each ``character'' in the string contains 8 bits, which ++specify the next 8 elements of the bool-vector (1 stands for @code{t}, ++and 0 for @code{nil}). The least significant bits of the character ++correspond to the lowest indices in the bool-vector. ++ ++@example ++(make-bool-vector 3 t) ++ @result{} #&3"^G" ++(make-bool-vector 3 nil) ++ @result{} #&3"^@@" ++@end example ++ ++@noindent ++These results make sense, because the binary code for @samp{C-g} is ++111 and @samp{C-@@} is the character with code 0. ++ ++ If the length is not a multiple of 8, the printed representation ++shows extra elements, but these extras really make no difference. For ++instance, in the next example, the two bool-vectors are equal, because ++only the first 3 bits are used: ++ ++@example ++(equal #&3"\377" #&3"\007") ++ @result{} t ++@end example ++ ++@node Hash Table Type ++@subsection Hash Table Type ++ ++ A hash table is a very fast kind of lookup table, somewhat like an ++alist in that it maps keys to corresponding values, but much faster. ++Hash tables have no read syntax, and print using hash notation. ++@xref{Hash Tables}, for functions that operate on hash tables. ++ ++@example ++(make-hash-table) ++ @result{} # ++@end example ++ ++@node Function Type ++@subsection Function Type ++ ++ Lisp functions are executable code, just like functions in other ++programming languages. In Lisp, unlike most languages, functions are ++also Lisp objects. A non-compiled function in Lisp is a lambda ++expression: that is, a list whose first element is the symbol ++@code{lambda} (@pxref{Lambda Expressions}). ++ ++ In most programming languages, it is impossible to have a function ++without a name. In Lisp, a function has no intrinsic name. A lambda ++expression can be called as a function even though it has no name; to ++emphasize this, we also call it an @dfn{anonymous function} ++(@pxref{Anonymous Functions}). A named function in Lisp is just a ++symbol with a valid function in its function cell (@pxref{Defining ++Functions}). ++ ++ Most of the time, functions are called when their names are written in ++Lisp expressions in Lisp programs. However, you can construct or obtain ++a function object at run time and then call it with the primitive ++functions @code{funcall} and @code{apply}. @xref{Calling Functions}. ++ ++@node Macro Type ++@subsection Macro Type ++ ++ A @dfn{Lisp macro} is a user-defined construct that extends the Lisp ++language. It is represented as an object much like a function, but with ++different argument-passing semantics. A Lisp macro has the form of a ++list whose first element is the symbol @code{macro} and whose @sc{cdr} ++is a Lisp function object, including the @code{lambda} symbol. ++ ++ Lisp macro objects are usually defined with the built-in ++@code{defmacro} function, but any list that begins with @code{macro} is ++a macro as far as Emacs is concerned. @xref{Macros}, for an explanation ++of how to write a macro. ++ ++ @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard ++Macros}) are entirely different things. When we use the word ``macro'' ++without qualification, we mean a Lisp macro, not a keyboard macro. ++ ++@node Primitive Function Type ++@subsection Primitive Function Type ++@cindex primitive function ++ ++ A @dfn{primitive function} is a function callable from Lisp but ++written in the C programming language. Primitive functions are also ++called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is ++derived from ``subroutine.'') Most primitive functions evaluate all ++their arguments when they are called. A primitive function that does ++not evaluate all its arguments is called a @dfn{special form} ++(@pxref{Special Forms}).@refill ++ ++ It does not matter to the caller of a function whether the function is ++primitive. However, this does matter if you try to redefine a primitive ++with a function written in Lisp. The reason is that the primitive ++function may be called directly from C code. Calls to the redefined ++function from Lisp will use the new definition, but calls from C code ++may still use the built-in definition. Therefore, @strong{we discourage ++redefinition of primitive functions}. ++ ++ The term @dfn{function} refers to all Emacs functions, whether written ++in Lisp or C. @xref{Function Type}, for information about the ++functions written in Lisp. ++ ++ Primitive functions have no read syntax and print in hash notation ++with the name of the subroutine. ++ ++@example ++@group ++(symbol-function 'car) ; @r{Access the function cell} ++ ; @r{of the symbol.} ++ @result{} # ++(subrp (symbol-function 'car)) ; @r{Is this a primitive function?} ++ @result{} t ; @r{Yes.} ++@end group ++@end example ++ ++@node Byte-Code Type ++@subsection Byte-Code Function Type ++ ++The byte compiler produces @dfn{byte-code function objects}. ++Internally, a byte-code function object is much like a vector; however, ++the evaluator handles this data type specially when it appears as a ++function to be called. @xref{Byte Compilation}, for information about ++the byte compiler. ++ ++The printed representation and read syntax for a byte-code function ++object is like that for a vector, with an additional @samp{#} before the ++opening @samp{[}. ++ ++@node Autoload Type ++@subsection Autoload Type ++ ++ An @dfn{autoload object} is a list whose first element is the symbol ++@code{autoload}. It is stored as the function definition of a symbol, ++where it serves as a placeholder for the real definition. The autoload ++object says that the real definition is found in a file of Lisp code ++that should be loaded when necessary. It contains the name of the file, ++plus some other information about the real definition. ++ ++ After the file has been loaded, the symbol should have a new function ++definition that is not an autoload object. The new definition is then ++called as if it had been there to begin with. From the user's point of ++view, the function call works as expected, using the function definition ++in the loaded file. ++ ++ An autoload object is usually created with the function ++@code{autoload}, which stores the object in the function cell of a ++symbol. @xref{Autoload}, for more details. ++ ++@node Editing Types ++@section Editing Types ++@cindex editing types ++ ++ The types in the previous section are used for general programming ++purposes, and most of them are common to most Lisp dialects. Emacs Lisp ++provides several additional data types for purposes connected with ++editing. ++ ++@menu ++* Buffer Type:: The basic object of editing. ++* Marker Type:: A position in a buffer. ++* Window Type:: Buffers are displayed in windows. ++* Frame Type:: Windows subdivide frames. ++* Terminal Type:: A terminal device displays frames. ++* Window Configuration Type:: Recording the way a frame is subdivided. ++* Frame Configuration Type:: Recording the status of all frames. ++* Process Type:: A subprocess of Emacs running on the underlying OS. ++* Stream Type:: Receive or send characters. ++* Keymap Type:: What function a keystroke invokes. ++* Overlay Type:: How an overlay is represented. ++* Font Type:: Fonts for displaying text. ++@end menu ++ ++@node Buffer Type ++@subsection Buffer Type ++ ++ A @dfn{buffer} is an object that holds text that can be edited ++(@pxref{Buffers}). Most buffers hold the contents of a disk file ++(@pxref{Files}) so they can be edited, but some are used for other ++purposes. Most buffers are also meant to be seen by the user, and ++therefore displayed, at some time, in a window (@pxref{Windows}). But ++a buffer need not be displayed in any window. Each buffer has a ++designated position called @dfn{point} (@pxref{Positions}); most ++editing commands act on the contents of the current buffer in the ++neighborhood of point. At any time, one buffer is the @dfn{current ++buffer}. ++ ++ The contents of a buffer are much like a string, but buffers are not ++used like strings in Emacs Lisp, and the available operations are ++different. For example, you can insert text efficiently into an ++existing buffer, altering the buffer's contents, whereas ``inserting'' ++text into a string requires concatenating substrings, and the result ++is an entirely new string object. ++ ++ Many of the standard Emacs functions manipulate or test the ++characters in the current buffer; a whole chapter in this manual is ++devoted to describing these functions (@pxref{Text}). ++ ++ Several other data structures are associated with each buffer: ++ ++@itemize @bullet ++@item ++a local syntax table (@pxref{Syntax Tables}); ++ ++@item ++a local keymap (@pxref{Keymaps}); and, ++ ++@item ++a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}). ++ ++@item ++overlays (@pxref{Overlays}). ++ ++@item ++text properties for the text in the buffer (@pxref{Text Properties}). ++@end itemize ++ ++@noindent ++The local keymap and variable list contain entries that individually ++override global bindings or values. These are used to customize the ++behavior of programs in different buffers, without actually changing the ++programs. ++ ++ A buffer may be @dfn{indirect}, which means it shares the text ++of another buffer, but presents it differently. @xref{Indirect Buffers}. ++ ++ Buffers have no read syntax. They print in hash notation, showing the ++buffer name. ++ ++@example ++@group ++(current-buffer) ++ @result{} # ++@end group ++@end example ++ ++@node Marker Type ++@subsection Marker Type ++ ++ A @dfn{marker} denotes a position in a specific buffer. Markers ++therefore have two components: one for the buffer, and one for the ++position. Changes in the buffer's text automatically relocate the ++position value as necessary to ensure that the marker always points ++between the same two characters in the buffer. ++ ++ Markers have no read syntax. They print in hash notation, giving the ++current character position and the name of the buffer. ++ ++@example ++@group ++(point-marker) ++ @result{} # ++@end group ++@end example ++ ++@xref{Markers}, for information on how to test, create, copy, and move ++markers. ++ ++@node Window Type ++@subsection Window Type ++ ++ A @dfn{window} describes the portion of the terminal screen that Emacs ++uses to display a buffer. Every window has one associated buffer, whose ++contents appear in the window. By contrast, a given buffer may appear ++in one window, no window, or several windows. ++ ++ Though many windows may exist simultaneously, at any time one window ++is designated the @dfn{selected window}. This is the window where the ++cursor is (usually) displayed when Emacs is ready for a command. The ++selected window usually displays the current buffer, but this is not ++necessarily the case. ++ ++ Windows are grouped on the screen into frames; each window belongs to ++one and only one frame. @xref{Frame Type}. ++ ++ Windows have no read syntax. They print in hash notation, giving the ++window number and the name of the buffer being displayed. The window ++numbers exist to identify windows uniquely, since the buffer displayed ++in any given window can change frequently. ++ ++@example ++@group ++(selected-window) ++ @result{} # ++@end group ++@end example ++ ++ @xref{Windows}, for a description of the functions that work on windows. ++ ++@node Frame Type ++@subsection Frame Type ++ ++ A @dfn{frame} is a screen area that contains one or more Emacs ++windows; we also use the term ``frame'' to refer to the Lisp object ++that Emacs uses to refer to the screen area. ++ ++ Frames have no read syntax. They print in hash notation, giving the ++frame's title, plus its address in core (useful to identify the frame ++uniquely). ++ ++@example ++@group ++(selected-frame) ++ @result{} # ++@end group ++@end example ++ ++ @xref{Frames}, for a description of the functions that work on frames. ++ ++@node Terminal Type ++@subsection Terminal Type ++@cindex terminal type ++ ++ A @dfn{terminal} is a device capable of displaying one or more ++Emacs frames (@pxref{Frame Type}). ++ ++ Terminals have no read syntax. They print in hash notation giving ++the terminal's ordinal number and its TTY device file name. ++ ++@example ++@group ++(get-device-terminal nil) ++ @result{} # ++@end group ++@end example ++ ++@c FIXME: add an xref to where terminal-related primitives are described. ++ ++@node Window Configuration Type ++@subsection Window Configuration Type ++@cindex window layout in a frame ++ ++ A @dfn{window configuration} stores information about the positions, ++sizes, and contents of the windows in a frame, so you can recreate the ++same arrangement of windows later. ++ ++ Window configurations do not have a read syntax; their print syntax ++looks like @samp{#}. @xref{Window ++Configurations}, for a description of several functions related to ++window configurations. ++ ++@node Frame Configuration Type ++@subsection Frame Configuration Type ++@cindex screen layout ++@cindex window layout, all frames ++ ++ A @dfn{frame configuration} stores information about the positions, ++sizes, and contents of the windows in all frames. It is not a ++primitive type---it is actually a list whose @sc{car} is ++@code{frame-configuration} and whose @sc{cdr} is an alist. Each alist ++element describes one frame, which appears as the @sc{car} of that ++element. ++ ++ @xref{Frame Configurations}, for a description of several functions ++related to frame configurations. ++ ++@node Process Type ++@subsection Process Type ++ ++ The word @dfn{process} usually means a running program. Emacs itself ++runs in a process of this sort. However, in Emacs Lisp, a process is a ++Lisp object that designates a subprocess created by the Emacs process. ++Programs such as shells, GDB, ftp, and compilers, running in ++subprocesses of Emacs, extend the capabilities of Emacs. ++ ++ An Emacs subprocess takes textual input from Emacs and returns textual ++output to Emacs for further manipulation. Emacs can also send signals ++to the subprocess. ++ ++ Process objects have no read syntax. They print in hash notation, ++giving the name of the process: ++ ++@example ++@group ++(process-list) ++ @result{} (#) ++@end group ++@end example ++ ++@xref{Processes}, for information about functions that create, delete, ++return information about, send input or signals to, and receive output ++from processes. ++ ++@node Stream Type ++@subsection Stream Type ++ ++ A @dfn{stream} is an object that can be used as a source or sink for ++characters---either to supply characters for input or to accept them as ++output. Many different types can be used this way: markers, buffers, ++strings, and functions. Most often, input streams (character sources) ++obtain characters from the keyboard, a buffer, or a file, and output ++streams (character sinks) send characters to a buffer, such as a ++@file{*Help*} buffer, or to the echo area. ++ ++ The object @code{nil}, in addition to its other meanings, may be used ++as a stream. It stands for the value of the variable ++@code{standard-input} or @code{standard-output}. Also, the object ++@code{t} as a stream specifies input using the minibuffer ++(@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo ++Area}). ++ ++ Streams have no special printed representation or read syntax, and ++print as whatever primitive type they are. ++ ++ @xref{Read and Print}, for a description of functions ++related to streams, including parsing and printing functions. ++ ++@node Keymap Type ++@subsection Keymap Type ++ ++ A @dfn{keymap} maps keys typed by the user to commands. This mapping ++controls how the user's command input is executed. A keymap is actually ++a list whose @sc{car} is the symbol @code{keymap}. ++ ++ @xref{Keymaps}, for information about creating keymaps, handling prefix ++keys, local as well as global keymaps, and changing key bindings. ++ ++@node Overlay Type ++@subsection Overlay Type ++ ++ An @dfn{overlay} specifies properties that apply to a part of a ++buffer. Each overlay applies to a specified range of the buffer, and ++contains a property list (a list whose elements are alternating property ++names and values). Overlay properties are used to present parts of the ++buffer temporarily in a different display style. Overlays have no read ++syntax, and print in hash notation, giving the buffer name and range of ++positions. ++ ++ @xref{Overlays}, for how to create and use overlays. ++ ++@node Font Type ++@subsection Font Type ++ ++ A @dfn{font} specifies how to display text on a graphical terminal. ++There are actually three separate font types---@dfn{font objects}, ++@dfn{font specs}, and @dfn{font entities}---each of which has slightly ++different properties. None of them have a read syntax; their print ++syntax looks like @samp{#}, @samp{#}, and ++@samp{#} respectively. @xref{Low-Level Font}, for a ++description of these Lisp objects. ++ ++@node Circular Objects ++@section Read Syntax for Circular Objects ++@cindex circular structure, read syntax ++@cindex shared structure, read syntax ++@cindex @samp{#@var{n}=} read syntax ++@cindex @samp{#@var{n}#} read syntax ++ ++ To represent shared or circular structures within a complex of Lisp ++objects, you can use the reader constructs @samp{#@var{n}=} and ++@samp{#@var{n}#}. ++ ++ Use @code{#@var{n}=} before an object to label it for later reference; ++subsequently, you can use @code{#@var{n}#} to refer the same object in ++another place. Here, @var{n} is some integer. For example, here is how ++to make a list in which the first element recurs as the third element: ++ ++@example ++(#1=(a) b #1#) ++@end example ++ ++@noindent ++This differs from ordinary syntax such as this ++ ++@example ++((a) b (a)) ++@end example ++ ++@noindent ++which would result in a list whose first and third elements ++look alike but are not the same Lisp object. This shows the difference: ++ ++@example ++(prog1 nil ++ (setq x '(#1=(a) b #1#))) ++(eq (nth 0 x) (nth 2 x)) ++ @result{} t ++(setq x '((a) b (a))) ++(eq (nth 0 x) (nth 2 x)) ++ @result{} nil ++@end example ++ ++ You can also use the same syntax to make a circular structure, which ++appears as an ``element'' within itself. Here is an example: ++ ++@example ++#1=(a #1#) ++@end example ++ ++@noindent ++This makes a list whose second element is the list itself. ++Here's how you can see that it really works: ++ ++@example ++(prog1 nil ++ (setq x '#1=(a #1#))) ++(eq x (cadr x)) ++ @result{} t ++@end example ++ ++ The Lisp printer can produce this syntax to record circular and shared ++structure in a Lisp object, if you bind the variable @code{print-circle} ++to a non-@code{nil} value. @xref{Output Variables}. ++ ++@node Type Predicates ++@section Type Predicates ++@cindex type checking ++@kindex wrong-type-argument ++ ++ The Emacs Lisp interpreter itself does not perform type checking on ++the actual arguments passed to functions when they are called. It could ++not do so, since function arguments in Lisp do not have declared data ++types, as they do in other programming languages. It is therefore up to ++the individual function to test whether each actual argument belongs to ++a type that the function can use. ++ ++ All built-in functions do check the types of their actual arguments ++when appropriate, and signal a @code{wrong-type-argument} error if an ++argument is of the wrong type. For example, here is what happens if you ++pass an argument to @code{+} that it cannot handle: ++ ++@example ++@group ++(+ 2 'a) ++ @error{} Wrong type argument: number-or-marker-p, a ++@end group ++@end example ++ ++@cindex type predicates ++@cindex testing types ++ If you want your program to handle different types differently, you ++must do explicit type checking. The most common way to check the type ++of an object is to call a @dfn{type predicate} function. Emacs has a ++type predicate for each type, as well as some predicates for ++combinations of types. ++ ++ A type predicate function takes one argument; it returns @code{t} if ++the argument belongs to the appropriate type, and @code{nil} otherwise. ++Following a general Lisp convention for predicate functions, most type ++predicates' names end with @samp{p}. ++ ++ Here is an example which uses the predicates @code{listp} to check for ++a list and @code{symbolp} to check for a symbol. ++ ++@example ++(defun add-on (x) ++ (cond ((symbolp x) ++ ;; If X is a symbol, put it on LIST. ++ (setq list (cons x list))) ++ ((listp x) ++ ;; If X is a list, add its elements to LIST. ++ (setq list (append x list))) ++ (t ++ ;; We handle only symbols and lists. ++ (error "Invalid argument %s in add-on" x)))) ++@end example ++ ++ Here is a table of predefined type predicates, in alphabetical order, ++with references to further information. ++ ++@table @code ++@item atom ++@xref{List-related Predicates, atom}. ++ ++@item arrayp ++@xref{Array Functions, arrayp}. ++ ++@item bool-vector-p ++@xref{Bool-Vectors, bool-vector-p}. ++ ++@item bufferp ++@xref{Buffer Basics, bufferp}. ++ ++@item byte-code-function-p ++@xref{Byte-Code Type, byte-code-function-p}. ++ ++@item case-table-p ++@xref{Case Tables, case-table-p}. ++ ++@item char-or-string-p ++@xref{Predicates for Strings, char-or-string-p}. ++ ++@item char-table-p ++@xref{Char-Tables, char-table-p}. ++ ++@item commandp ++@xref{Interactive Call, commandp}. ++ ++@item consp ++@xref{List-related Predicates, consp}. ++ ++@item display-table-p ++@xref{Display Tables, display-table-p}. ++ ++@item floatp ++@xref{Predicates on Numbers, floatp}. ++ ++@item fontp ++@xref{Low-Level Font}. ++ ++@item frame-configuration-p ++@xref{Frame Configurations, frame-configuration-p}. ++ ++@item frame-live-p ++@xref{Deleting Frames, frame-live-p}. ++ ++@item framep ++@xref{Frames, framep}. ++ ++@item functionp ++@xref{Functions, functionp}. ++ ++@item hash-table-p ++@xref{Other Hash, hash-table-p}. ++ ++@item integer-or-marker-p ++@xref{Predicates on Markers, integer-or-marker-p}. ++ ++@item integerp ++@xref{Predicates on Numbers, integerp}. ++ ++@item keymapp ++@xref{Creating Keymaps, keymapp}. ++ ++@item keywordp ++@xref{Constant Variables}. ++ ++@item listp ++@xref{List-related Predicates, listp}. ++ ++@item markerp ++@xref{Predicates on Markers, markerp}. ++ ++@item wholenump ++@xref{Predicates on Numbers, wholenump}. ++ ++@item nlistp ++@xref{List-related Predicates, nlistp}. ++ ++@item numberp ++@xref{Predicates on Numbers, numberp}. ++ ++@item number-or-marker-p ++@xref{Predicates on Markers, number-or-marker-p}. ++ ++@item overlayp ++@xref{Overlays, overlayp}. ++ ++@item processp ++@xref{Processes, processp}. ++ ++@item sequencep ++@xref{Sequence Functions, sequencep}. ++ ++@item stringp ++@xref{Predicates for Strings, stringp}. ++ ++@item subrp ++@xref{Function Cells, subrp}. ++ ++@item symbolp ++@xref{Symbols, symbolp}. ++ ++@item syntax-table-p ++@xref{Syntax Tables, syntax-table-p}. ++ ++@item user-variable-p ++@xref{Defining Variables, user-variable-p}. ++ ++@item vectorp ++@xref{Vectors, vectorp}. ++ ++@item window-configuration-p ++@xref{Window Configurations, window-configuration-p}. ++ ++@item window-live-p ++@xref{Deleting Windows, window-live-p}. ++ ++@item windowp ++@xref{Basic Windows, windowp}. ++ ++@item booleanp ++@xref{nil and t, booleanp}. ++ ++@item string-or-null-p ++@xref{Predicates for Strings, string-or-null-p}. ++@end table ++ ++ The most general way to check the type of an object is to call the ++function @code{type-of}. Recall that each object belongs to one and ++only one primitive type; @code{type-of} tells you which one (@pxref{Lisp ++Data Types}). But @code{type-of} knows nothing about non-primitive ++types. In most cases, it is more convenient to use type predicates than ++@code{type-of}. ++ ++@defun type-of object ++This function returns a symbol naming the primitive type of ++@var{object}. The value is one of the symbols @code{bool-vector}, ++@code{buffer}, @code{char-table}, @code{compiled-function}, ++@code{cons}, @code{float}, @code{font-entity}, @code{font-object}, ++@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer}, ++@code{marker}, @code{overlay}, @code{process}, @code{string}, ++@code{subr}, @code{symbol}, @code{vector}, @code{window}, or ++@code{window-configuration}. ++ ++@example ++(type-of 1) ++ @result{} integer ++@group ++(type-of 'nil) ++ @result{} symbol ++(type-of '()) ; @r{@code{()} is @code{nil}.} ++ @result{} symbol ++(type-of '(x)) ++ @result{} cons ++@end group ++@end example ++@end defun ++ ++@node Equality Predicates ++@section Equality Predicates ++@cindex equality ++ ++ Here we describe functions that test for equality between any two ++objects. Other functions test equality of contents between objects of specific ++types, e.g., strings. For these predicates, see the appropriate chapter ++describing the data type. ++ ++@defun eq object1 object2 ++This function returns @code{t} if @var{object1} and @var{object2} are ++the same object, @code{nil} otherwise. ++ ++@code{eq} returns @code{t} if @var{object1} and @var{object2} are ++integers with the same value. Also, since symbol names are normally ++unique, if the arguments are symbols with the same name, they are ++@code{eq}. For other types (e.g., lists, vectors, strings), two ++arguments with the same contents or elements are not necessarily ++@code{eq} to each other: they are @code{eq} only if they are the same ++object, meaning that a change in the contents of one will be reflected ++by the same change in the contents of the other. ++ ++@example ++@group ++(eq 'foo 'foo) ++ @result{} t ++@end group ++ ++@group ++(eq 456 456) ++ @result{} t ++@end group ++ ++@group ++(eq "asdf" "asdf") ++ @result{} nil ++@end group ++ ++@group ++(eq "" "") ++ @result{} t ++;; @r{This exception occurs because Emacs Lisp} ++;; @r{makes just one multibyte empty string, to save space.} ++@end group ++ ++@group ++(eq '(1 (2 (3))) '(1 (2 (3)))) ++ @result{} nil ++@end group ++ ++@group ++(setq foo '(1 (2 (3)))) ++ @result{} (1 (2 (3))) ++(eq foo foo) ++ @result{} t ++(eq foo '(1 (2 (3)))) ++ @result{} nil ++@end group ++ ++@group ++(eq [(1 2) 3] [(1 2) 3]) ++ @result{} nil ++@end group ++ ++@group ++(eq (point-marker) (point-marker)) ++ @result{} nil ++@end group ++@end example ++ ++The @code{make-symbol} function returns an uninterned symbol, distinct ++from the symbol that is used if you write the name in a Lisp expression. ++Distinct symbols with the same name are not @code{eq}. @xref{Creating ++Symbols}. ++ ++@example ++@group ++(eq (make-symbol "foo") 'foo) ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun equal object1 object2 ++This function returns @code{t} if @var{object1} and @var{object2} have ++equal components, @code{nil} otherwise. Whereas @code{eq} tests if its ++arguments are the same object, @code{equal} looks inside nonidentical ++arguments to see if their elements or contents are the same. So, if two ++objects are @code{eq}, they are @code{equal}, but the converse is not ++always true. ++ ++@example ++@group ++(equal 'foo 'foo) ++ @result{} t ++@end group ++ ++@group ++(equal 456 456) ++ @result{} t ++@end group ++ ++@group ++(equal "asdf" "asdf") ++ @result{} t ++@end group ++@group ++(eq "asdf" "asdf") ++ @result{} nil ++@end group ++ ++@group ++(equal '(1 (2 (3))) '(1 (2 (3)))) ++ @result{} t ++@end group ++@group ++(eq '(1 (2 (3))) '(1 (2 (3)))) ++ @result{} nil ++@end group ++ ++@group ++(equal [(1 2) 3] [(1 2) 3]) ++ @result{} t ++@end group ++@group ++(eq [(1 2) 3] [(1 2) 3]) ++ @result{} nil ++@end group ++ ++@group ++(equal (point-marker) (point-marker)) ++ @result{} t ++@end group ++ ++@group ++(eq (point-marker) (point-marker)) ++ @result{} nil ++@end group ++@end example ++ ++Comparison of strings is case-sensitive, but does not take account of ++text properties---it compares only the characters in the strings. Use ++@code{equal-including-properties} to also compare text properties. For ++technical reasons, a unibyte string and a multibyte string are ++@code{equal} if and only if they contain the same sequence of ++character codes and all these codes are either in the range 0 through ++127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). ++(@pxref{Text Representations}). ++ ++@example ++@group ++(equal "asdf" "ASDF") ++ @result{} nil ++@end group ++@end example ++ ++However, two distinct buffers are never considered @code{equal}, even if ++their textual contents are the same. ++@end defun ++ ++ The test for equality is implemented recursively; for example, given ++two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})} ++returns @code{t} if and only if both the expressions below return ++@code{t}: ++ ++@example ++(equal (car @var{x}) (car @var{y})) ++(equal (cdr @var{x}) (cdr @var{y})) ++@end example ++ ++Because of this recursive method, circular lists may therefore cause ++infinite recursion (leading to an error). ++ ++@defun equal-including-properties object1 object2 ++This function behaves like @code{equal} in all cases but also requires ++that for two strings to be equal, they have the same text properties. ++ ++@example ++@group ++(equal "asdf" (propertize "asdf" '(asdf t))) ++ @result{} t ++@end group ++@group ++(equal-including-properties "asdf" ++ (propertize "asdf" '(asdf t))) ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@ignore ++ arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096 ++@end ignore +diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi +new file mode 100644 +index 0000000..c535307 +--- /dev/null ++++ b/doc/lispref/os.texi +@@ -0,0 +1,2190 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/os ++@node System Interface, Antinews, Display, Top ++@chapter Operating System Interface ++ ++ This chapter is about starting and getting out of Emacs, access to ++values in the operating system environment, and terminal input, output, ++and flow control. ++ ++ @xref{Building Emacs}, for related information. @xref{Display}, for ++additional operating system status information pertaining to the ++terminal and the screen. ++ ++@menu ++* Starting Up:: Customizing Emacs startup processing. ++* Getting Out:: How exiting works (permanent or temporary). ++* System Environment:: Distinguish the name and kind of system. ++* User Identification:: Finding the name and user id of the user. ++* Time of Day:: Getting the current time. ++* Time Conversion:: Converting a time from numeric form to ++ calendrical data and vice versa. ++* Time Parsing:: Converting a time from numeric form to text ++ and vice versa. ++* Processor Run Time:: Getting the run time used by Emacs. ++* Time Calculations:: Adding, subtracting, comparing times, etc. ++* Timers:: Setting a timer to call a function at a certain time. ++* Idle Timers:: Setting a timer to call a function when Emacs has ++ been idle for a certain length of time. ++* Terminal Input:: Accessing and recording terminal input. ++* Terminal Output:: Controlling and recording terminal output. ++* Sound Output:: Playing sounds on the computer's speaker. ++* X11 Keysyms:: Operating on key symbols for X Windows. ++* Batch Mode:: Running Emacs without terminal interaction. ++* Session Management:: Saving and restoring state with X Session Management. ++@end menu ++ ++@node Starting Up ++@section Starting Up Emacs ++ ++ This section describes what Emacs does when it is started, and how you ++can customize these actions. ++ ++@menu ++* Startup Summary:: Sequence of actions Emacs performs at startup. ++* Init File:: Details on reading the init file. ++* Terminal-Specific:: How the terminal-specific Lisp file is read. ++* Command-Line Arguments:: How command-line arguments are processed, ++ and how you can customize them. ++@end menu ++ ++@node Startup Summary ++@subsection Summary: Sequence of Actions at Startup ++@cindex initialization of Emacs ++@cindex startup of Emacs ++@cindex @file{startup.el} ++ ++ When Emacs is started up, it performs the following operations ++(which are defined in @file{startup.el}): ++ ++@enumerate ++@item ++It adds subdirectories to @code{load-path}, by running the file named ++@file{subdirs.el} in each directory in the list. Normally, this file ++adds the directory's subdirectories to the list, and those are scanned ++in their turn. The files @file{subdirs.el} are normally generated ++automatically when Emacs is installed. ++ ++@vindex before-init-time ++@item ++It sets the variable @code{before-init-time} to the value of ++@code{current-time} (@pxref{Time of Day}). It also sets ++@code{after-init-time} to @code{nil}, which signals to Lisp programs ++that Emacs is being initialized. ++ ++@vindex initial-window-system@r{, and startup} ++@vindex window-system-initialization-alist ++@item ++It loads the initialization library for the window system specified by ++the variable @code{initial-window-system} (@pxref{Window Systems, ++initial-window-system}). This library's name is ++@file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the ++value of @code{initial-window-system}. From that library, it calls ++the appropriate initialization function. The initialization function ++for each supported window system is specified by ++@code{window-system-initialization-alist}. ++ ++@item ++It sets the language environment and the terminal coding system, ++if requested by environment variables such as @code{LANG}. ++ ++@item ++It processes the initial options. (Some of them are handled ++even earlier than this.) ++ ++@item ++It runs the normal hook @code{before-init-hook}. ++ ++@item ++It initializes the window frame and faces, if appropriate, and turns ++on the menu bar and tool bar, if the initial frame needs them. ++ ++@item ++It loads the library @file{site-start}, if it exists. This is not ++done if the options @samp{-Q} or @samp{--no-site-file} were specified. ++@cindex @file{site-start.el} ++ ++@item ++It loads your init file (@pxref{Init File}). This is not done if the ++options @samp{-q}, @samp{-Q}, or @samp{--batch} were specified. If ++the @samp{-u} option was specified, Emacs looks for the init file in ++that user's home directory instead. ++ ++@item ++It loads the library @file{default}, if it exists. This is not done ++if @code{inhibit-default-init} is non-@code{nil}, nor if the options ++@samp{-q}, @samp{-Q}, or @samp{--batch} were specified. ++@cindex @file{default.el} ++ ++@item ++It loads your abbrevs from the file specified by ++@code{abbrev-file-name}, if that file exists and can be read ++(@pxref{Abbrev Files, abbrev-file-name}). This is not done if the ++option @samp{--batch} was specified. ++ ++@vindex after-init-time ++@item ++It sets the variable @code{after-init-time} to the value of ++@code{current-time}. This variable was set to @code{nil} earlier; ++setting it to the current time signals that the initialization phase ++is over, and, together with @code{before-init-time}, provides the ++measurement of how long it took. ++ ++@item ++It runs the normal hook @code{after-init-hook}. ++ ++@item ++If the buffer @samp{*scratch*} exists and is still in Fundamental mode ++(as it should be by default), it sets its major mode according to ++@code{initial-major-mode}. ++ ++@item ++If started on a text-only terminal, it loads the terminal-specific ++Lisp library, which is specified by the variable ++@code{term-file-prefix} (@pxref{Terminal-Specific}). This is not done ++in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}. ++ ++@item ++It displays the initial echo area message, unless you have suppressed ++that with @code{inhibit-startup-echo-area-message}. ++ ++@item ++It processes the action arguments from the command line. ++ ++@item ++It now exits if the option @code{--batch} was specified. ++ ++@item ++If @code{initial-buffer-choice} is a string, it visits the file with ++that name. Furthermore, if the @samp{*scratch*} buffer exists and is ++empty, it inserts @code{initial-scratch-message} into that buffer. ++ ++@item ++It runs @code{emacs-startup-hook} and then @code{term-setup-hook}. ++ ++@item ++It calls @code{frame-notice-user-settings}, which modifies the ++parameters of the selected frame according to whatever the init files ++specify. ++ ++@item ++It runs @code{window-setup-hook}. @xref{Window Systems}. ++ ++@item ++If the option @code{--daemon} was specified, it calls ++@code{server-start} and detaches from the controlling terminal. ++@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. ++ ++@item ++It displays the @dfn{startup screen}, which is a special buffer that ++contains information about copyleft and basic Emacs usage. This is ++not done if @code{initial-buffer-choice} or ++@code{inhibit-startup-screen} are @code{nil}, nor if the ++@samp{--no-splash} or @samp{-Q} command-line options were specified. ++ ++@item ++If started by the X session manager, it calls ++@code{emacs-session-restore} passing it as argument the ID of the ++previous session. @xref{Session Management}. ++@end enumerate ++ ++@defopt inhibit-startup-screen ++This variable, if non-@code{nil}, inhibits the startup screen. In ++that case, Emacs typically displays the @samp{*scratch*} buffer; but ++see @code{initial-buffer-choice}, below. ++ ++Do not set this variable in the init file of a new user, or in a way ++that affects more than one user, as that would prevent new users from ++receiving information about copyleft and basic Emacs usage. ++ ++@code{inhibit-startup-message} and @code{inhibit-splash-screen} are ++aliases for this variable. ++@end defopt ++ ++@defopt initial-buffer-choice ++This variable, if non-@code{nil}, determines a file or buffer for ++Emacs to display after starting up, instead of the startup screen. If ++its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. If ++its value is a string, that specifies the name of a file for Emacs to ++visit. ++@end defopt ++ ++@defopt inhibit-startup-echo-area-message ++This variable controls the display of the startup echo area message. ++You can suppress the startup echo area message by adding text with this ++form to your init file: ++ ++@example ++(setq inhibit-startup-echo-area-message ++ "@var{your-login-name}") ++@end example ++ ++Emacs explicitly checks for an expression as shown above in your init ++file; your login name must appear in the expression as a Lisp string ++constant. Other methods of setting ++@code{inhibit-startup-echo-area-message} to the same value do not ++inhibit the startup message. This way, you can easily inhibit the ++message for yourself if you wish, but thoughtless copying of your init ++file will not inhibit the message for someone else. ++@end defopt ++ ++@defopt initial-scratch-message ++This variable, if non-@code{nil}, should be a string, which is ++inserted into the @samp{*scratch*} buffer when Emacs starts up. If it ++is @code{nil}, the @samp{*scratch*} buffer is empty. ++@end defopt ++ ++@node Init File ++@subsection The Init File, @file{.emacs} ++@cindex init file ++@cindex @file{.emacs} ++ ++ When you start Emacs, it normally attempts to load your @dfn{init ++file}. This is either a file named @file{.emacs} or @file{.emacs.el} ++in your home directory, or a file named @file{init.el} in a ++subdirectory named @file{.emacs.d} in your home directory. Whichever ++place you use, you can also compile the file (@pxref{Byte ++Compilation}); then the actual file loaded will be @file{.emacs.elc} ++or @file{init.elc}. ++ ++ The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u} ++control whether and where to find the init file; @samp{-q} (and the ++stronger @samp{-Q}) says not to load an init file, while @samp{-u ++@var{user}} says to load @var{user}'s init file instead of yours. ++@xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither ++option is specified, Emacs uses the @code{LOGNAME} environment ++variable, or the @code{USER} (most systems) or @code{USERNAME} (MS ++systems) variable, to find your home directory and thus your init ++file; this way, even if you have su'd, Emacs still loads your own init ++file. If those environment variables are absent, though, Emacs uses ++your user-id to find your home directory. ++ ++@cindex default init file ++ A site may have a @dfn{default init file}, which is the library ++named @file{default.el}. Emacs finds the @file{default.el} file ++through the standard search path for libraries (@pxref{How Programs Do ++Loading}). The Emacs distribution does not come with this file; sites ++may provide one for local customizations. If the default init file ++exists, it is loaded whenever you start Emacs, except in batch mode or ++if @samp{-q} (or @samp{-Q}) is specified. But your own personal init ++file, if any, is loaded first; if it sets @code{inhibit-default-init} ++to a non-@code{nil} value, then Emacs does not subsequently load the ++@file{default.el} file. ++ ++ Another file for site-customization is @file{site-start.el}. Emacs ++loads this @emph{before} the user's init file. You can inhibit the ++loading of this file with the option @samp{--no-site-file}. ++ ++@defopt site-run-file ++This variable specifies the site-customization file to load before the ++user's init file. Its normal value is @code{"site-start"}. The only ++way you can change it with real effect is to do so before dumping ++Emacs. ++@end defopt ++ ++ @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for ++examples of how to make various commonly desired customizations in your ++@file{.emacs} file. ++ ++@defopt inhibit-default-init ++This variable prevents Emacs from loading the default initialization ++library file for your session of Emacs. If its value is non-@code{nil}, ++then the default library is not loaded. The default value is ++@code{nil}. ++@end defopt ++ ++@defvar before-init-hook ++This normal hook is run, once, just before loading all the init files ++(the user's init file, @file{default.el}, and/or @file{site-start.el}). ++(The only way to change it with real effect is before dumping Emacs.) ++@end defvar ++ ++@defvar after-init-hook ++This normal hook is run, once, just after loading all the init files ++(the user's init file, @file{default.el}, and/or @file{site-start.el}), ++before loading the terminal-specific library and processing the ++command-line action arguments. ++@end defvar ++ ++@defvar emacs-startup-hook ++This normal hook is run, once, just after handling the command line ++arguments, just before @code{term-setup-hook}. ++@end defvar ++ ++@defvar user-init-file ++This variable holds the absolute file name of the user's init file. If the ++actual init file loaded is a compiled file, such as @file{.emacs.elc}, ++the value refers to the corresponding source file. ++@end defvar ++ ++@defvar user-emacs-directory ++This variable holds the name of the @file{.emacs.d} directory. It is ++ordinarily @file{~/.emacs.d}, but differs on some platforms. ++@end defvar ++ ++@node Terminal-Specific ++@subsection Terminal-Specific Initialization ++@cindex terminal-specific initialization ++ ++ Each terminal type can have its own Lisp library that Emacs loads when ++run on that type of terminal. The library's name is constructed by ++concatenating the value of the variable @code{term-file-prefix} and the ++terminal type (specified by the environment variable @code{TERM}). ++Normally, @code{term-file-prefix} has the value ++@code{"term/"}; changing this is not recommended. Emacs finds the file ++in the normal manner, by searching the @code{load-path} directories, and ++trying the @samp{.elc} and @samp{.el} suffixes. ++ ++@cindex Termcap ++ The usual function of a terminal-specific library is to enable ++special keys to send sequences that Emacs can recognize. It may also ++need to set or add to @code{input-decode-map} if the Termcap or ++Terminfo entry does not specify all the terminal's function keys. ++@xref{Terminal Input}. ++ ++ When the name of the terminal type contains a hyphen, and no library ++is found whose name is identical to the terminal's name, Emacs strips ++from the terminal's name the last hyphen and everything that follows ++it, and tries again. This process is repeated until Emacs finds a ++matching library or until there are no more hyphens in the name (the ++latter means the terminal doesn't have any library specific to it). ++Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30} ++libraries, Emacs will try the same library @file{term/aaa.el} for ++terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the ++library can evaluate @code{(getenv "TERM")} to find the full name of ++the terminal type.@refill ++ ++ Your init file can prevent the loading of the ++terminal-specific library by setting the variable ++@code{term-file-prefix} to @code{nil}. This feature is useful when ++experimenting with your own peculiar customizations. ++ ++ You can also arrange to override some of the actions of the ++terminal-specific library by setting the variable ++@code{term-setup-hook}. This is a normal hook which Emacs runs using ++@code{run-hooks} at the end of Emacs initialization, after loading both ++your init file and any terminal-specific libraries. You can ++use this variable to define initializations for terminals that do not ++have their own libraries. @xref{Hooks}. ++ ++@defvar term-file-prefix ++@cindex @code{TERM} environment variable ++If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads ++a terminal-specific initialization file as follows: ++ ++@example ++(load (concat term-file-prefix (getenv "TERM"))) ++@end example ++ ++@noindent ++You may set the @code{term-file-prefix} variable to @code{nil} in your ++init file if you do not wish to load the ++terminal-initialization file. To do this, put the following in ++your init file: @code{(setq term-file-prefix nil)}. ++ ++On MS-DOS, if the environment variable @code{TERM} is not set, Emacs ++uses @samp{internal} as the terminal type. ++@end defvar ++ ++@defvar term-setup-hook ++This variable is a normal hook that Emacs runs after loading your ++init file, the default initialization file (if any) and the ++terminal-specific Lisp file. ++ ++You can use @code{term-setup-hook} to override the definitions made by a ++terminal-specific file. ++@end defvar ++ ++ See @code{window-setup-hook} in @ref{Window Systems}, for a related ++feature. ++ ++@node Command-Line Arguments ++@subsection Command-Line Arguments ++@cindex command-line arguments ++ ++ You can use command-line arguments to request various actions when you ++start Emacs. Since you do not need to start Emacs more than once per ++day, and will often leave your Emacs session running longer than that, ++command-line arguments are hardly ever used. As a practical matter, it ++is best to avoid making the habit of using them, since this habit would ++encourage you to kill and restart Emacs unnecessarily often. These ++options exist for two reasons: to be compatible with other editors (for ++invocation by other programs) and to enable shell scripts to run ++specific Lisp programs. ++ ++ This section describes how Emacs processes command-line arguments, ++and how you can customize them. ++ ++@ignore ++ (Note that some other editors require you to start afresh each time ++you want to edit a file. With this kind of editor, you will probably ++specify the file as a command-line argument. The recommended way to ++use GNU Emacs is to start it only once, just after you log in, and do ++all your editing in the same Emacs process. Each time you want to edit ++a different file, you visit it with the existing Emacs, which eventually ++comes to have many files in it ready for editing. Usually you do not ++kill the Emacs until you are about to log out.) ++@end ignore ++ ++@defun command-line ++This function parses the command line that Emacs was called with, ++processes it, loads the user's init file and displays the ++startup messages. ++@end defun ++ ++@defvar command-line-processed ++The value of this variable is @code{t} once the command line has been ++processed. ++ ++If you redump Emacs by calling @code{dump-emacs}, you may wish to set ++this variable to @code{nil} first in order to cause the new dumped Emacs ++to process its new command-line arguments. ++@end defvar ++ ++@defvar command-switch-alist ++@cindex switches on command line ++@cindex options on command line ++@cindex command-line options ++The value of this variable is an alist of user-defined command-line ++options and associated handler functions. This variable exists so you ++can add elements to it. ++ ++A @dfn{command-line option} is an argument on the command line, which ++has the form: ++ ++@example ++-@var{option} ++@end example ++ ++The elements of the @code{command-switch-alist} look like this: ++ ++@example ++(@var{option} . @var{handler-function}) ++@end example ++ ++The @sc{car}, @var{option}, is a string, the name of a command-line ++option (not including the initial hyphen). The @var{handler-function} ++is called to handle @var{option}, and receives the option name as its ++sole argument. ++ ++In some cases, the option is followed in the command line by an ++argument. In these cases, the @var{handler-function} can find all the ++remaining command-line arguments in the variable ++@code{command-line-args-left}. (The entire list of command-line ++arguments is in @code{command-line-args}.) ++ ++The command-line arguments are parsed by the @code{command-line-1} ++function in the @file{startup.el} file. See also @ref{Emacs ++Invocation, , Command Line Arguments for Emacs Invocation, emacs, The ++GNU Emacs Manual}. ++@end defvar ++ ++@defvar command-line-args ++The value of this variable is the list of command-line arguments passed ++to Emacs. ++@end defvar ++ ++@defvar command-line-args-left ++The value of this variable is the list of command-line arguments that ++have not yet been processed. @code{argv} is an alias for this. ++@end defvar ++ ++@defvar command-line-functions ++This variable's value is a list of functions for handling an ++unrecognized command-line argument. Each time the next argument to be ++processed has no special meaning, the functions in this list are called, ++in order of appearance, until one of them returns a non-@code{nil} ++value. ++ ++These functions are called with no arguments. They can access the ++command-line argument under consideration through the variable ++@code{argi}, which is bound temporarily at this point. The remaining ++arguments (not including the current one) are in the variable ++@code{command-line-args-left}. ++ ++When a function recognizes and processes the argument in @code{argi}, it ++should return a non-@code{nil} value to say it has dealt with that ++argument. If it has also dealt with some of the following arguments, it ++can indicate that by deleting them from @code{command-line-args-left}. ++ ++If all of these functions return @code{nil}, then the argument is used ++as a file name to visit. ++@end defvar ++ ++@node Getting Out ++@section Getting Out of Emacs ++@cindex exiting Emacs ++ ++ There are two ways to get out of Emacs: you can kill the Emacs job, ++which exits permanently, or you can suspend it, which permits you to ++reenter the Emacs process later. As a practical matter, you seldom kill ++Emacs---only when you are about to log out. Suspending is much more ++common. ++ ++@menu ++* Killing Emacs:: Exiting Emacs irreversibly. ++* Suspending Emacs:: Exiting Emacs reversibly. ++@end menu ++ ++@node Killing Emacs ++@comment node-name, next, previous, up ++@subsection Killing Emacs ++@cindex killing Emacs ++ ++ Killing Emacs means ending the execution of the Emacs process. The ++parent process normally resumes control. The low-level primitive for ++killing Emacs is @code{kill-emacs}. ++ ++@deffn Command kill-emacs &optional exit-data ++This command exits the Emacs process and kills it. ++ ++If @var{exit-data} is an integer, then it is used as the exit status ++of the Emacs process. (This is useful primarily in batch operation; see ++@ref{Batch Mode}.) ++ ++If @var{exit-data} is a string, its contents are stuffed into the ++terminal input buffer so that the shell (or whatever program next reads ++input) can read them. ++@end deffn ++ ++ All the information in the Emacs process, aside from files that have ++been saved, is lost when the Emacs process is killed. Because killing ++Emacs inadvertently can lose a lot of work, Emacs queries for ++confirmation before actually terminating if you have buffers that need ++saving or subprocesses that are running. This is done in the function ++@code{save-buffers-kill-emacs}, the higher level function from which ++@code{kill-emacs} is usually called. ++ ++@defvar kill-emacs-query-functions ++After asking the standard questions, @code{save-buffers-kill-emacs} ++calls the functions in the list @code{kill-emacs-query-functions}, in ++order of appearance, with no arguments. These functions can ask for ++additional confirmation from the user. If any of them returns ++@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and ++does not run the remaining functions in this hook. Calling ++@code{kill-emacs} directly does not run this hook. ++@end defvar ++ ++@defvar kill-emacs-hook ++This variable is a normal hook; once @code{save-buffers-kill-emacs} is ++finished with all file saving and confirmation, it calls ++@code{kill-emacs} which runs the functions in this hook. ++@code{kill-emacs} does not run this hook in batch mode. ++ ++@code{kill-emacs} may be invoked directly (that is not via ++@code{save-buffers-kill-emacs}) if the terminal is disconnected, or in ++similar situations where interaction with the user is not possible. ++Thus, if your hook needs to interact with the user, put it on ++@code{kill-emacs-query-functions}; if it needs to run regardless of ++how Emacs is killed, put it on @code{kill-emacs-hook}. ++@end defvar ++ ++@node Suspending Emacs ++@subsection Suspending Emacs ++@cindex suspending Emacs ++ ++ On text-only terminals, it is possible to @dfn{suspend Emacs}, which ++means stopping Emacs temporarily and returning control to its superior ++process, which is usually the shell. This allows you to resume ++editing later in the same Emacs process, with the same buffers, the ++same kill ring, the same undo history, and so on. To resume Emacs, ++use the appropriate command in the parent shell---most likely ++@code{fg}. ++ ++@cindex controlling terminal ++ Suspending works only on a terminal device from which the Emacs ++session was started. We call that device the @dfn{controlling ++terminal} of the session. Suspending is not allowed if the ++controlling terminal is a graphical terminal. ++ ++ Some operating systems do not support suspension of jobs; on these ++systems, ``suspension'' actually creates a new shell temporarily as a ++subprocess of Emacs. Then you would exit the shell to return to Emacs. ++ ++@deffn Command suspend-emacs &optional string ++This function stops Emacs and returns control to the superior process. ++If and when the superior process resumes Emacs, @code{suspend-emacs} ++returns @code{nil} to its caller in Lisp. ++ ++This function works only on the controlling terminal of the Emacs ++session; to relinquish control of other tty devices, use ++@code{suspend-tty} (see below). If the Emacs session uses more than ++one terminal, you must delete the frames on all the other terminals ++before suspending Emacs, or this function signals an error. ++@xref{Multiple Terminals}. ++ ++If @var{string} is non-@code{nil}, its characters are sent to Emacs's ++superior shell, to be read as terminal input. The characters in ++@var{string} are not echoed by the superior shell; only the results ++appear. ++ ++Before suspending, @code{suspend-emacs} runs the normal hook ++@code{suspend-hook}. After the user resumes Emacs, ++@code{suspend-emacs} runs the normal hook @code{suspend-resume-hook}. ++@xref{Hooks}. ++ ++The next redisplay after resumption will redraw the entire screen, ++unless the variable @code{no-redraw-on-reenter} is non-@code{nil}. ++@xref{Refresh Screen}. ++ ++In the following example, note that @samp{pwd} is not echoed after ++Emacs is suspended. But it is read and executed by the shell. ++ ++@smallexample ++@group ++(suspend-emacs) ++ @result{} nil ++@end group ++ ++@group ++(add-hook 'suspend-hook ++ (function (lambda () ++ (or (y-or-n-p ++ "Really suspend? ") ++ (error "Suspend canceled"))))) ++ @result{} (lambda nil ++ (or (y-or-n-p "Really suspend? ") ++ (error "Suspend canceled"))) ++@end group ++@group ++(add-hook 'suspend-resume-hook ++ (function (lambda () (message "Resumed!")))) ++ @result{} (lambda nil (message "Resumed!")) ++@end group ++@group ++(suspend-emacs "pwd") ++ @result{} nil ++@end group ++@group ++---------- Buffer: Minibuffer ---------- ++Really suspend? @kbd{y} ++---------- Buffer: Minibuffer ---------- ++@end group ++ ++@group ++---------- Parent Shell ---------- ++lewis@@slug[23] % /user/lewis/manual ++lewis@@slug[24] % fg ++@end group ++ ++@group ++---------- Echo Area ---------- ++Resumed! ++@end group ++@end smallexample ++@end deffn ++ ++@defvar suspend-hook ++This variable is a normal hook that Emacs runs before suspending. ++@end defvar ++ ++@defvar suspend-resume-hook ++This variable is a normal hook that Emacs runs on resuming ++after a suspension. ++@end defvar ++ ++@defun suspend-tty &optional tty ++If @var{tty} specifies a terminal device used by Emacs, this function ++relinquishes the device and restores it to its prior state. Frames ++that used the device continue to exist, but are not updated and Emacs ++doesn't read input from them. @var{tty} can be a terminal object, a ++frame (meaning the terminal for that frame), or @code{nil} (meaning ++the terminal for the selected frame). @xref{Multiple Terminals}. ++ ++If @var{tty} is already suspended, this function does nothing. ++ ++This function runs the hook @code{suspend-tty-functions}, passing the ++terminal object as an argument to each function. ++@end defun ++ ++@defun resume-tty &optional tty ++This function resumes the previously suspended terminal device ++@var{tty}; @var{tty} can be a terminal object, a frame (meaning the ++terminal for that frame), or @code{nil} (meaning the terminal for the ++selected frame). ++ ++This function reopens the terminal device, re-initializes it, and ++redraws its with that terminal's selected frame. It then runs the ++hook @code{resume-tty-functions}, passing the terminal object as an ++argument to each function. ++ ++If the same device is already used by another Emacs terminal, this ++function signals an error. ++@end defun ++ ++@defun controlling-tty-p &optional terminal ++This function returns non-@code{nil} if @var{terminal} is the ++controlling terminal of the Emacs session; @code{terminal} can be a ++terminal object, a frame (meaning the terminal for that frame), or ++@code{nil} (meaning the terminal for the selected frame). ++@end defun ++ ++@deffn Command suspend-frame ++This command @dfn{suspends} a frame. For GUI frames, it calls ++@code{iconify-frame} (@pxref{Visibility of Frames}); for text-only ++frames, it calls either @code{suspend-emacs} or @code{suspend-tty}, ++depending on whether the frame is displayed on the controlling ++terminal device or not. ++@end deffn ++ ++@node System Environment ++@section Operating System Environment ++@cindex operating system environment ++ ++ Emacs provides access to variables in the operating system environment ++through various functions. These variables include the name of the ++system, the user's @acronym{UID}, and so on. ++ ++@defvar system-configuration ++This variable holds the standard GNU configuration name for the ++hardware/software configuration of your system, as a string. The ++convenient way to test parts of this string is with ++@code{string-match}. ++@end defvar ++ ++@cindex system type and name ++@defvar system-type ++The value of this variable is a symbol indicating the type of operating ++system Emacs is operating on. Here is a table of the possible values: ++ ++@table @code ++@item aix ++IBM's AIX. ++ ++@item berkeley-unix ++Berkeley BSD and its variants. ++ ++@item cygwin ++Cygwin, a Posix layer on top of MS-Windows. ++ ++@item darwin ++Darwin (Mac OS X). ++ ++@item gnu ++The GNU system (using the GNU kernel, which consists of the HURD and Mach). ++ ++@item gnu/linux ++A GNU/Linux system---that is, a variant GNU system, using the Linux ++kernel. (These systems are the ones people often call ``Linux,'' but ++actually Linux is just the kernel, not the whole system.) ++ ++@item gnu/kfreebsd ++A GNU (glibc-based) system with a FreeBSD kernel. ++ ++@item hpux ++Hewlett-Packard HPUX operating system. ++ ++@item irix ++Silicon Graphics Irix system. ++ ++@item lynxos 3.0.1 ++LynxOS-3.0.1. ++ ++@item ms-dos ++Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for ++MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on ++MS-Windows. ++ ++@item usg-unix-v ++AT&T Unix System V. ++ ++@item windows-nt ++Microsoft Windows NT and later. The same executable supports Windows ++9X, but the value of @code{system-type} is @code{windows-nt} in either ++case. ++ ++@end table ++ ++We do not wish to add new symbols to make finer distinctions unless it ++is absolutely necessary! In fact, we hope to eliminate some of these ++alternatives in the future. We recommend using ++@code{system-configuration} to distinguish between different operating ++systems. ++@end defvar ++ ++@defun system-name ++This function returns the name of the machine you are running on. ++@example ++(system-name) ++ @result{} "www.gnu.org" ++@end example ++@end defun ++ ++ The symbol @code{system-name} is a variable as well as a function. In ++fact, the function returns whatever value the variable ++@code{system-name} currently holds. Thus, you can set the variable ++@code{system-name} in case Emacs is confused about the name of your ++system. The variable is also useful for constructing frame titles ++(@pxref{Frame Titles}). ++ ++@defopt mail-host-address ++If this variable is non-@code{nil}, it is used instead of ++@code{system-name} for purposes of generating email addresses. For ++example, it is used when constructing the default value of ++@code{user-mail-address}. @xref{User Identification}. (Since this is ++done when Emacs starts up, the value actually used is the one saved when ++Emacs was dumped. @xref{Building Emacs}.) ++@end defopt ++ ++@deffn Command getenv var &optional frame ++@cindex environment variable access ++This function returns the value of the environment variable @var{var}, ++as a string. @var{var} should be a string. If @var{var} is undefined ++in the environment, @code{getenv} returns @code{nil}. If returns ++@samp{""} if @var{var} is set but null. Within Emacs, the environment ++variable values are kept in the Lisp variable @code{process-environment}. ++ ++@example ++@group ++(getenv "USER") ++ @result{} "lewis" ++@end group ++ ++@group ++lewis@@slug[10] % printenv ++PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin ++USER=lewis ++@end group ++@group ++TERM=ibmapa16 ++SHELL=/bin/csh ++HOME=/user/lewis ++@end group ++@end example ++@end deffn ++ ++@c Emacs 19 feature ++@deffn Command setenv variable &optional value ++This command sets the value of the environment variable named ++@var{variable} to @var{value}. @var{variable} should be a string. ++Internally, Emacs Lisp can handle any string. However, normally ++@var{variable} should be a valid shell identifier, that is, a sequence ++of letters, digits and underscores, starting with a letter or ++underscore. Otherwise, errors may occur if subprocesses of Emacs try ++to access the value of @var{variable}. If @var{value} is omitted or ++@code{nil}, @code{setenv} removes @var{variable} from the environment. ++Otherwise, @var{value} should be a string. ++ ++@code{setenv} works by modifying @code{process-environment}; binding ++that variable with @code{let} is also reasonable practice. ++ ++@code{setenv} returns the new value of @var{variable}, or @code{nil} ++if it removed @var{variable} from the environment. ++@end deffn ++ ++@defvar process-environment ++This variable is a list of strings, each describing one environment ++variable. The functions @code{getenv} and @code{setenv} work by means ++of this variable. ++ ++@smallexample ++@group ++process-environment ++@result{} ("l=/usr/stanford/lib/gnuemacs/lisp" ++ "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" ++ "USER=lewis" ++@end group ++@group ++ "TERM=ibmapa16" ++ "SHELL=/bin/csh" ++ "HOME=/user/lewis") ++@end group ++@end smallexample ++ ++If @code{process-environment} contains ``duplicate'' elements that ++specify the same environment variable, the first of these elements ++specifies the variable, and the other ``duplicates'' are ignored. ++@end defvar ++ ++@defvar initial-environment ++This variable holds the list of environment variables Emacs inherited ++from its parent process. It is computed during startup, see ++@ref{Startup Summary}. ++@end defvar ++ ++@defvar path-separator ++This variable holds a string which says which character separates ++directories in a search path (as found in an environment variable). Its ++value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS ++and MS-Windows. ++@end defvar ++ ++@defun parse-colon-path path ++This function takes a search path string such as would be the value of ++the @code{PATH} environment variable, and splits it at the separators, ++returning a list of directory names. @code{nil} in this list stands for ++``use the current directory.'' Although the function's name says ++``colon,'' it actually uses the value of @code{path-separator}. ++ ++@example ++(parse-colon-path ":/foo:/bar") ++ @result{} (nil "/foo/" "/bar/") ++@end example ++@end defun ++ ++@defvar invocation-name ++This variable holds the program name under which Emacs was invoked. The ++value is a string, and does not include a directory name. ++@end defvar ++ ++@defvar invocation-directory ++This variable holds the directory from which the Emacs executable was ++invoked, or perhaps @code{nil} if that directory cannot be determined. ++@end defvar ++ ++@defvar installation-directory ++If non-@code{nil}, this is a directory within which to look for the ++@file{lib-src} and @file{etc} subdirectories. This is non-@code{nil} ++when Emacs can't find those directories in their standard installed ++locations, but can find them in a directory related somehow to the one ++containing the Emacs executable. ++@end defvar ++ ++@defun load-average &optional use-float ++This function returns the current 1-minute, 5-minute, and 15-minute load ++averages, in a list. ++ ++By default, the values are integers that are 100 times the system load ++averages, which indicate the average number of processes trying to run. ++If @var{use-float} is non-@code{nil}, then they are returned ++as floating point numbers and without multiplying by 100. ++ ++If it is impossible to obtain the load average, this function signals ++an error. On some platforms, access to load averages requires ++installing Emacs as setuid or setgid so that it can read kernel ++information, and that usually isn't advisable. ++ ++If the 1-minute load average is available, but the 5- or 15-minute ++averages are not, this function returns a shortened list containing ++the available averages. ++ ++@example ++@group ++(load-average) ++ @result{} (169 48 36) ++@end group ++@group ++(load-average t) ++ @result{} (1.69 0.48 0.36) ++@end group ++ ++@group ++lewis@@rocky[5] % uptime ++ 11:55am up 1 day, 19:37, 3 users, ++ load average: 1.69, 0.48, 0.36 ++@end group ++@end example ++@end defun ++ ++@defun emacs-pid ++This function returns the process @acronym{ID} of the Emacs process, ++as an integer. ++@end defun ++ ++@defvar tty-erase-char ++This variable holds the erase character that was selected ++in the system's terminal driver, before Emacs was started. ++The value is @code{nil} if Emacs is running under a window system. ++@end defvar ++ ++@node User Identification ++@section User Identification ++@cindex user identification ++ ++@defvar init-file-user ++This variable says which user's init files should be used by ++Emacs---or @code{nil} if none. @code{""} stands for the user who ++originally logged in. The value reflects command-line options such as ++@samp{-q} or @samp{-u @var{user}}. ++ ++Lisp packages that load files of customizations, or any other sort of ++user profile, should obey this variable in deciding where to find it. ++They should load the profile of the user name found in this variable. ++If @code{init-file-user} is @code{nil}, meaning that the @samp{-q} ++option was used, then Lisp packages should not load any customization ++files or user profile. ++@end defvar ++ ++@defopt user-mail-address ++This holds the nominal email address of the user who is using Emacs. ++Emacs normally sets this variable to a default value after reading your ++init files, but not if you have already set it. So you can set the ++variable to some other value in your init file if you do not ++want to use the default value. ++@end defopt ++ ++@defun user-login-name &optional uid ++If you don't specify @var{uid}, this function returns the name under ++which the user is logged in. If the environment variable @code{LOGNAME} ++is set, that value is used. Otherwise, if the environment variable ++@code{USER} is set, that value is used. Otherwise, the value is based ++on the effective @acronym{UID}, not the real @acronym{UID}. ++ ++If you specify @var{uid}, the value is the user name that corresponds ++to @var{uid} (which should be an integer), or @code{nil} if there is ++no such user. ++ ++@example ++@group ++(user-login-name) ++ @result{} "lewis" ++@end group ++@end example ++@end defun ++ ++@defun user-real-login-name ++This function returns the user name corresponding to Emacs's real ++@acronym{UID}. This ignores the effective @acronym{UID} and ignores the ++environment variables @code{LOGNAME} and @code{USER}. ++@end defun ++ ++@defun user-full-name &optional uid ++This function returns the full name of the logged-in user---or the value ++of the environment variable @code{NAME}, if that is set. ++ ++@c "Bil" is the correct spelling. ++@example ++@group ++(user-full-name) ++ @result{} "Bil Lewis" ++@end group ++@end example ++ ++If the Emacs job's user-id does not correspond to any known user (and ++provided @code{NAME} is not set), the value is @code{"unknown"}. ++ ++If @var{uid} is non-@code{nil}, then it should be a number (a user-id) ++or a string (a login name). Then @code{user-full-name} returns the full ++name corresponding to that user-id or login name. If you specify a ++user-id or login name that isn't defined, it returns @code{nil}. ++@end defun ++ ++@vindex user-full-name ++@vindex user-real-login-name ++@vindex user-login-name ++ The symbols @code{user-login-name}, @code{user-real-login-name} and ++@code{user-full-name} are variables as well as functions. The functions ++return the same values that the variables hold. These variables allow ++you to ``fake out'' Emacs by telling the functions what to return. The ++variables are also useful for constructing frame titles (@pxref{Frame ++Titles}). ++ ++@defun user-real-uid ++This function returns the real @acronym{UID} of the user. ++The value may be a floating point number. ++ ++@example ++@group ++(user-real-uid) ++ @result{} 19 ++@end group ++@end example ++@end defun ++ ++@defun user-uid ++This function returns the effective @acronym{UID} of the user. ++The value may be a floating point number. ++@end defun ++ ++@node Time of Day ++@section Time of Day ++ ++ This section explains how to determine the current time and the time ++zone. ++ ++@defun current-time-string &optional time-value ++This function returns the current time and date as a human-readable ++string. The format of the string is unvarying; the number of characters ++used for each part is always the same, so you can reliably use ++@code{substring} to extract pieces of it. It is wise to count the ++characters from the beginning of the string rather than from the end, as ++additional information may some day be added at the end. ++ ++@c Emacs 19 feature ++The argument @var{time-value}, if given, specifies a time to format ++instead of the current time. The argument should be a list whose first ++two elements are integers. Thus, you can use times obtained from ++@code{current-time} (see below) and from @code{file-attributes} ++(@pxref{Definition of file-attributes}). @var{time-value} can also be ++a cons of two integers, but this is considered obsolete. ++ ++@example ++@group ++(current-time-string) ++ @result{} "Wed Oct 14 22:21:05 1987" ++@end group ++@end example ++@end defun ++ ++@c Emacs 19 feature ++@defun current-time ++This function returns the system's time value as a list of three ++integers: @code{(@var{high} @var{low} @var{microsec})}. The integers ++@var{high} and @var{low} combine to give the number of seconds since ++0:00 January 1, 1970 UTC (Coordinated Universal Time), which is ++@ifnottex ++@var{high} * 2**16 + @var{low}. ++@end ifnottex ++@tex ++$high*2^{16}+low$. ++@end tex ++ ++The third element, @var{microsec}, gives the microseconds since the ++start of the current second (or 0 for systems that return time with ++the resolution of only one second). ++ ++The first two elements can be compared with file time values such as you ++get with the function @code{file-attributes}. ++@xref{Definition of file-attributes}. ++@end defun ++ ++@c Emacs 19 feature ++@defun current-time-zone &optional time-value ++This function returns a list describing the time zone that the user is ++in. ++ ++The value has the form @code{(@var{offset} @var{name})}. Here ++@var{offset} is an integer giving the number of seconds ahead of UTC ++(east of Greenwich). A negative value means west of Greenwich. The ++second element, @var{name}, is a string giving the name of the time ++zone. Both elements change when daylight saving time begins or ends; ++if the user has specified a time zone that does not use a seasonal time ++adjustment, then the value is constant through time. ++ ++If the operating system doesn't supply all the information necessary to ++compute the value, the unknown elements of the list are @code{nil}. ++ ++The argument @var{time-value}, if given, specifies a time to analyze ++instead of the current time. The argument should have the same form ++as for @code{current-time-string} (see above). Thus, you can use ++times obtained from @code{current-time} (see above) and from ++@code{file-attributes}. @xref{Definition of file-attributes}. ++@end defun ++ ++@defun set-time-zone-rule tz ++This function specifies the local time zone according to @var{tz}. If ++@var{tz} is @code{nil}, that means to use an implementation-defined ++default time zone. If @var{tz} is @code{t}, that means to use ++Universal Time. Otherwise, @var{tz} should be a string specifying a ++time zone rule. ++@end defun ++ ++@defun float-time &optional time-value ++This function returns the current time as a floating-point number of ++seconds since the epoch. The argument @var{time-value}, if given, ++specifies a time to convert instead of the current time. The argument ++should have the same form as for @code{current-time-string} (see ++above). Thus, it accepts the output of @code{current-time} and ++@code{file-attributes}. ++ ++@emph{Warning}: Since the result is floating point, it may not be ++exact. Do not use this function if precise time stamps are required. ++@end defun ++ ++@node Time Conversion ++@section Time Conversion ++ ++ These functions convert time values (lists of two or three integers) ++to calendrical information and vice versa. You can get time values ++from the functions @code{current-time} (@pxref{Time of Day}) and ++@code{file-attributes} (@pxref{Definition of file-attributes}). ++ ++ Many operating systems are limited to time values that contain 32 bits ++of information; these systems typically handle only the times from ++1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some ++operating systems have larger time values, and can represent times far ++in the past or future. ++ ++ Time conversion functions always use the Gregorian calendar, even ++for dates before the Gregorian calendar was introduced. Year numbers ++count the number of years since the year 1 B.C., and do not skip zero ++as traditional Gregorian years do; for example, the year number ++@minus{}37 represents the Gregorian year 38 B.C@. ++ ++@defun decode-time &optional time ++This function converts a time value into calendrical information. If ++you don't specify @var{time}, it decodes the current time. The return ++value is a list of nine elements, as follows: ++ ++@example ++(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) ++@end example ++ ++Here is what the elements mean: ++ ++@table @var ++@item seconds ++The number of seconds past the minute, as an integer between 0 and 59. ++On some operating systems, this is 60 for leap seconds. ++@item minutes ++The number of minutes past the hour, as an integer between 0 and 59. ++@item hour ++The hour of the day, as an integer between 0 and 23. ++@item day ++The day of the month, as an integer between 1 and 31. ++@item month ++The month of the year, as an integer between 1 and 12. ++@item year ++The year, an integer typically greater than 1900. ++@item dow ++The day of week, as an integer between 0 and 6, where 0 stands for ++Sunday. ++@item dst ++@code{t} if daylight saving time is effect, otherwise @code{nil}. ++@item zone ++An integer indicating the time zone, as the number of seconds east of ++Greenwich. ++@end table ++ ++@strong{Common Lisp Note:} Common Lisp has different meanings for ++@var{dow} and @var{zone}. ++@end defun ++ ++@defun encode-time seconds minutes hour day month year &optional zone ++This function is the inverse of @code{decode-time}. It converts seven ++items of calendrical data into a time value. For the meanings of the ++arguments, see the table above under @code{decode-time}. ++ ++Year numbers less than 100 are not treated specially. If you want them ++to stand for years above 1900, or years above 2000, you must alter them ++yourself before you call @code{encode-time}. ++ ++The optional argument @var{zone} defaults to the current time zone and ++its daylight saving time rules. If specified, it can be either a list ++(as you would get from @code{current-time-zone}), a string as in the ++@code{TZ} environment variable, @code{t} for Universal Time, or an ++integer (as you would get from @code{decode-time}). The specified ++zone is used without any further alteration for daylight saving time. ++ ++If you pass more than seven arguments to @code{encode-time}, the first ++six are used as @var{seconds} through @var{year}, the last argument is ++used as @var{zone}, and the arguments in between are ignored. This ++feature makes it possible to use the elements of a list returned by ++@code{decode-time} as the arguments to @code{encode-time}, like this: ++ ++@example ++(apply 'encode-time (decode-time @dots{})) ++@end example ++ ++You can perform simple date arithmetic by using out-of-range values for ++the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} ++arguments; for example, day 0 means the day preceding the given month. ++ ++The operating system puts limits on the range of possible time values; ++if you try to encode a time that is out of range, an error results. ++For instance, years before 1970 do not work on some systems; ++on others, years as early as 1901 do work. ++@end defun ++ ++@node Time Parsing ++@section Parsing and Formatting Times ++ ++ These functions convert time values (lists of two or three integers) ++to text in a string, and vice versa. ++ ++@defun date-to-time string ++This function parses the time-string @var{string} and returns the ++corresponding time value. ++@end defun ++ ++@defun format-time-string format-string &optional time universal ++This function converts @var{time} (or the current time, if @var{time} is ++omitted) to a string according to @var{format-string}. The argument ++@var{format-string} may contain @samp{%}-sequences which say to ++substitute parts of the time. Here is a table of what the ++@samp{%}-sequences mean: ++ ++@table @samp ++@item %a ++This stands for the abbreviated name of the day of week. ++@item %A ++This stands for the full name of the day of week. ++@item %b ++This stands for the abbreviated name of the month. ++@item %B ++This stands for the full name of the month. ++@item %c ++This is a synonym for @samp{%x %X}. ++@item %C ++This has a locale-specific meaning. In the default locale (named C), it ++is equivalent to @samp{%A, %B %e, %Y}. ++@item %d ++This stands for the day of month, zero-padded. ++@item %D ++This is a synonym for @samp{%m/%d/%y}. ++@item %e ++This stands for the day of month, blank-padded. ++@item %h ++This is a synonym for @samp{%b}. ++@item %H ++This stands for the hour (00-23). ++@item %I ++This stands for the hour (01-12). ++@item %j ++This stands for the day of the year (001-366). ++@item %k ++This stands for the hour (0-23), blank padded. ++@item %l ++This stands for the hour (1-12), blank padded. ++@item %m ++This stands for the month (01-12). ++@item %M ++This stands for the minute (00-59). ++@item %n ++This stands for a newline. ++@item %p ++This stands for @samp{AM} or @samp{PM}, as appropriate. ++@item %r ++This is a synonym for @samp{%I:%M:%S %p}. ++@item %R ++This is a synonym for @samp{%H:%M}. ++@item %S ++This stands for the seconds (00-59). ++@item %t ++This stands for a tab character. ++@item %T ++This is a synonym for @samp{%H:%M:%S}. ++@item %U ++This stands for the week of the year (01-52), assuming that weeks ++start on Sunday. ++@item %w ++This stands for the numeric day of week (0-6). Sunday is day 0. ++@item %W ++This stands for the week of the year (01-52), assuming that weeks ++start on Monday. ++@item %x ++This has a locale-specific meaning. In the default locale (named ++@samp{C}), it is equivalent to @samp{%D}. ++@item %X ++This has a locale-specific meaning. In the default locale (named ++@samp{C}), it is equivalent to @samp{%T}. ++@item %y ++This stands for the year without century (00-99). ++@item %Y ++This stands for the year with century. ++@item %Z ++This stands for the time zone abbreviation (e.g., @samp{EST}). ++@item %z ++This stands for the time zone numerical offset (e.g., @samp{-0500}). ++@end table ++ ++You can also specify the field width and type of padding for any of ++these @samp{%}-sequences. This works as in @code{printf}: you write ++the field width as digits in the middle of a @samp{%}-sequences. If you ++start the field width with @samp{0}, it means to pad with zeros. If you ++start the field width with @samp{_}, it means to pad with spaces. ++ ++For example, @samp{%S} specifies the number of seconds since the minute; ++@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to ++pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros, ++because that is how @samp{%S} normally pads to two positions. ++ ++The characters @samp{E} and @samp{O} act as modifiers when used between ++@samp{%} and one of the letters in the table above. @samp{E} specifies ++using the current locale's ``alternative'' version of the date and time. ++In a Japanese locale, for example, @code{%Ex} might yield a date format ++based on the Japanese Emperors' reigns. @samp{E} is allowed in ++@samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and ++@samp{%EY}. ++ ++@samp{O} means to use the current locale's ``alternative'' ++representation of numbers, instead of the ordinary decimal digits. This ++is allowed with most letters, all the ones that output numbers. ++ ++If @var{universal} is non-@code{nil}, that means to describe the time as ++Universal Time; @code{nil} means describe it using what Emacs believes ++is the local time zone (see @code{current-time-zone}). ++ ++This function uses the C library function @code{strftime} ++(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference ++Manual}) to do most of the work. In order to communicate with that ++function, it first encodes its argument using the coding system ++specified by @code{locale-coding-system} (@pxref{Locales}); after ++@code{strftime} returns the resulting string, ++@code{format-time-string} decodes the string using that same coding ++system. ++@end defun ++ ++@defun seconds-to-time seconds ++This function converts @var{seconds}, a floating point number of ++seconds since the epoch, to a time value and returns that. To perform ++the inverse conversion, use @code{float-time}. ++@end defun ++ ++@defun format-seconds format-string seconds ++This function converts its argument @var{seconds} into a string of ++years, days, hours, etc., according to @var{format-string}. The ++argument @var{format-string} may contain @samp{%}-sequences which ++control the conversion. Here is a table of what the ++@samp{%}-sequences mean: ++ ++@table @samp ++@item %y ++@itemx %Y ++The integer number of 365-day years. ++@item %d ++@itemx %D ++The integer number of days. ++@item %h ++@itemx %H ++The integer number of hours. ++@item %m ++@itemx %M ++The integer number of minutes. ++@item %s ++@itemx %S ++The integer number of seconds. ++@item %z ++Non-printing control flag. When it is used, other specifiers must be ++given in the order of decreasing size, i.e.@: years before days, hours ++before minutes, etc. Nothing will be produced in the result string to ++the left of @samp{%z} until the first non-zero conversion is ++encountered. For example, the default format used by ++@code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime}) ++@w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds ++will always be produced, but years, days, hours, and minutes will only ++be shown if they are non-zero. ++@item %% ++Produces a literal @samp{%}. ++@end table ++ ++Upper-case format sequences produce the units in addition to the ++numbers, lower-case formats produce only the numbers. ++ ++You can also specify the field width by following the @samp{%} with a ++number; shorter numbers will be padded with blanks. An optional ++period before the width requests zero-padding instead. For example, ++@code{"%.3Y"} might produce @code{"004 years"}. ++ ++@emph{Warning:} This function works only with values of @var{seconds} ++that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics, ++most-positive-fixnum}). ++@end defun ++ ++@node Processor Run Time ++@section Processor Run time ++@cindex processor run time ++@cindex Emacs process run time ++ ++ Emacs provides several functions and primitives that return time, ++both elapsed and processor time, used by the Emacs process. ++ ++@deffn Command emacs-uptime &optional format ++This function returns a string representing the Emacs ++@dfn{uptime}---the elapsed wall-clock time this instance of Emacs is ++running. The string is formatted by @code{format-seconds} according ++to the optional argument @var{format}. For the available format ++descriptors, see @ref{Time Parsing, format-seconds}. If @var{format} ++is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M, ++%z%S"}. ++ ++When called interactively, it prints the uptime in the echo area. ++@end deffn ++ ++@defun get-internal-run-time ++This function returns the processor run time used by Emacs as a list ++of three integers: @code{(@var{high} @var{low} @var{microsec})}. The ++integers @var{high} and @var{low} combine to give the number of ++seconds, which is ++@ifnottex ++@var{high} * 2**16 + @var{low}. ++@end ifnottex ++@tex ++$high*2^{16}+low$. ++@end tex ++ ++The third element, @var{microsec}, gives the microseconds (or 0 for ++systems that return time with the resolution of only one second). ++ ++Note that the time returned by this function excludes the time Emacs ++was not using the processor, and if the Emacs process has several ++threads, the returned value is the sum of the processor times used up ++by all Emacs threads. ++ ++If the system doesn't provide a way to determine the processor run ++time, @code{get-internal-run-time} returns the same time as ++@code{current-time}. ++@end defun ++ ++@deffn Command emacs-init-time ++This function returns the duration of the Emacs initialization ++(@pxref{Startup Summary}) in seconds, as a string. When called ++interactively, it prints the duration in the echo area. ++@end deffn ++ ++@node Time Calculations ++@section Time Calculations ++ ++ These functions perform calendrical computations using time values ++(the kind of list that @code{current-time} returns). ++ ++@defun time-less-p t1 t2 ++This returns @code{t} if time value @var{t1} is less than time value ++@var{t2}. ++@end defun ++ ++@defun time-subtract t1 t2 ++This returns the time difference @var{t1} @minus{} @var{t2} between ++two time values, in the same format as a time value. ++@end defun ++ ++@defun time-add t1 t2 ++This returns the sum of two time values, one of which ought to ++represent a time difference rather than a point in time. ++Here is how to add a number of seconds to a time value: ++ ++@example ++(time-add @var{time} (seconds-to-time @var{seconds})) ++@end example ++@end defun ++ ++@defun time-to-days time ++This function returns the number of days between the beginning of year ++1 and @var{time}. ++@end defun ++ ++@defun time-to-day-in-year time ++This returns the day number within the year corresponding to @var{time}. ++@end defun ++ ++@defun date-leap-year-p year ++This function returns @code{t} if @var{year} is a leap year. ++@end defun ++ ++@node Timers ++@section Timers for Delayed Execution ++@cindex timer ++ ++ You can set up a @dfn{timer} to call a function at a specified ++future time or after a certain length of idleness. ++ ++ Emacs cannot run timers at any arbitrary point in a Lisp program; it ++can run them only when Emacs could accept output from a subprocess: ++namely, while waiting or inside certain primitive functions such as ++@code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a ++timer's execution may be delayed if Emacs is busy. However, the time of ++execution is very precise if Emacs is idle. ++ ++ Emacs binds @code{inhibit-quit} to @code{t} before calling the timer ++function, because quitting out of many timer functions can leave ++things in an inconsistent state. This is normally unproblematical ++because most timer functions don't do a lot of work. Indeed, for a ++timer to call a function that takes substantial time to run is likely ++to be annoying. If a timer function needs to allow quitting, it ++should use @code{with-local-quit} (@pxref{Quitting}). For example, if ++a timer function calls @code{accept-process-output} to receive output ++from an external process, that call should be wrapped inside ++@code{with-local-quit}, to ensure that @kbd{C-g} works if the external ++process hangs. ++ ++ It is usually a bad idea for timer functions to alter buffer ++contents. When they do, they usually should call @code{undo-boundary} ++both before and after changing the buffer, to separate the timer's ++changes from user commands' changes and prevent a single undo entry ++from growing to be quite large. ++ ++ Timer functions should also avoid calling functions that cause Emacs ++to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to ++unpredictable effects, since other timers (or even the same timer) can ++run while waiting. If a timer function needs to perform an action ++after a certain time has elapsed, it can do this by scheduling a new ++timer. ++ ++ If a timer function calls functions that can change the match data, ++it should save and restore the match data. @xref{Saving Match Data}. ++ ++@deffn Command run-at-time time repeat function &rest args ++This sets up a timer that calls the function @var{function} with ++arguments @var{args} at time @var{time}. If @var{repeat} is a number ++(integer or floating point), the timer is scheduled to run again every ++@var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil}, ++the timer runs only once. ++ ++@var{time} may specify an absolute or a relative time. ++ ++Absolute times may be specified using a string with a limited variety ++of formats, and are taken to be times @emph{today}, even if already in ++the past. The recognized forms are @samp{@var{xxxx}}, ++@samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time), ++and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm}, ++@samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am}, ++@samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or ++@samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon ++to separate the hour and minute parts. ++ ++To specify a relative time as a string, use numbers followed by units. ++For example: ++ ++@table @samp ++@item 1 min ++denotes 1 minute from now. ++@item 1 min 5 sec ++denotes 65 seconds from now. ++@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year ++denotes exactly 103 months, 123 days, and 10862 seconds from now. ++@end table ++ ++For relative time values, Emacs considers a month to be exactly thirty ++days, and a year to be exactly 365.25 days. ++ ++Not all convenient formats are strings. If @var{time} is a number ++(integer or floating point), that specifies a relative time measured in ++seconds. The result of @code{encode-time} can also be used to specify ++an absolute value for @var{time}. ++ ++In most cases, @var{repeat} has no effect on when @emph{first} call ++takes place---@var{time} alone specifies that. There is one exception: ++if @var{time} is @code{t}, then the timer runs whenever the time is a ++multiple of @var{repeat} seconds after the epoch. This is useful for ++functions like @code{display-time}. ++ ++The function @code{run-at-time} returns a timer value that identifies ++the particular scheduled future action. You can use this value to call ++@code{cancel-timer} (see below). ++@end deffn ++ ++ A repeating timer nominally ought to run every @var{repeat} seconds, ++but remember that any invocation of a timer can be late. Lateness of ++one repetition has no effect on the scheduled time of the next ++repetition. For instance, if Emacs is busy computing for long enough ++to cover three scheduled repetitions of the timer, and then starts to ++wait, it will immediately call the timer function three times in ++immediate succession (presuming no other timers trigger before or ++between them). If you want a timer to run again no less than @var{n} ++seconds after the last invocation, don't use the @var{repeat} argument. ++Instead, the timer function should explicitly reschedule the timer. ++ ++@defvar timer-max-repeats ++This variable's value specifies the maximum number of times to repeat ++calling a timer function in a row, when many previously scheduled ++calls were unavoidably delayed. ++@end defvar ++ ++@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{} ++Execute @var{body}, but give up after @var{seconds} seconds. If ++@var{body} finishes before the time is up, @code{with-timeout} returns ++the value of the last form in @var{body}. If, however, the execution of ++@var{body} is cut short by the timeout, then @code{with-timeout} ++executes all the @var{timeout-forms} and returns the value of the last ++of them. ++ ++This macro works by setting a timer to run after @var{seconds} seconds. If ++@var{body} finishes before that time, it cancels the timer. If the ++timer actually runs, it terminates execution of @var{body}, then ++executes @var{timeout-forms}. ++ ++Since timers can run within a Lisp program only when the program calls a ++primitive that can wait, @code{with-timeout} cannot stop executing ++@var{body} while it is in the midst of a computation---only when it ++calls one of those primitives. So use @code{with-timeout} only with a ++@var{body} that waits for input, not one that does a long computation. ++@end defmac ++ ++ The function @code{y-or-n-p-with-timeout} provides a simple way to use ++a timer to avoid waiting too long for an answer. @xref{Yes-or-No ++Queries}. ++ ++@defun cancel-timer timer ++This cancels the requested action for @var{timer}, which should be a ++timer---usually, one previously returned by @code{run-at-time} or ++@code{run-with-idle-timer}. This cancels the effect of that call to ++one of these functions; the arrival of the specified time will not ++cause anything special to happen. ++@end defun ++ ++@node Idle Timers ++@section Idle Timers ++ ++ Here is how to set up a timer that runs when Emacs is idle for a ++certain length of time. Aside from how to set them up, idle timers ++work just like ordinary timers. ++ ++@deffn Command run-with-idle-timer secs repeat function &rest args ++Set up a timer which runs when Emacs has been idle for @var{secs} ++seconds. The value of @var{secs} may be an integer or a floating point ++number; a value of the type returned by @code{current-idle-time} ++is also allowed. ++ ++If @var{repeat} is @code{nil}, the timer runs just once, the first time ++Emacs remains idle for a long enough time. More often @var{repeat} is ++non-@code{nil}, which means to run the timer @emph{each time} Emacs ++remains idle for @var{secs} seconds. ++ ++The function @code{run-with-idle-timer} returns a timer value which you ++can use in calling @code{cancel-timer} (@pxref{Timers}). ++@end deffn ++ ++@cindex idleness ++ Emacs becomes ``idle'' when it starts waiting for user input, and it ++remains idle until the user provides some input. If a timer is set for ++five seconds of idleness, it runs approximately five seconds after Emacs ++first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer ++will not run again as long as Emacs remains idle, because the duration ++of idleness will continue to increase and will not go down to five ++seconds again. ++ ++ Emacs can do various things while idle: garbage collect, autosave or ++handle data from a subprocess. But these interludes during idleness do ++not interfere with idle timers, because they do not reset the clock of ++idleness to zero. An idle timer set for 600 seconds will run when ten ++minutes have elapsed since the last user command was finished, even if ++subprocess output has been accepted thousands of times within those ten ++minutes, and even if there have been garbage collections and autosaves. ++ ++ When the user supplies input, Emacs becomes non-idle while executing the ++input. Then it becomes idle again, and all the idle timers that are ++set up to repeat will subsequently run another time, one by one. ++ ++@c Emacs 19 feature ++@defun current-idle-time ++If Emacs is idle, this function returns the length of time Emacs has ++been idle, as a list of three integers: @code{(@var{high} @var{low} ++@var{microsec})}. The integers @var{high} and @var{low} combine to ++give the number of seconds of idleness, which is ++@ifnottex ++@var{high} * 2**16 + @var{low}. ++@end ifnottex ++@tex ++$high*2^{16}+low$. ++@end tex ++ ++The third element, @var{microsec}, gives the microseconds since the ++start of the current second (or 0 for systems that return time with ++the resolution of only one second). ++ ++When Emacs is not idle, @code{current-idle-time} returns @code{nil}. ++This is a convenient way to test whether Emacs is idle. ++ ++The main use of this function is when an idle timer function wants to ++``take a break'' for a while. It can set up another idle timer to ++call the same function again, after a few seconds more idleness. ++Here's an example: ++ ++@smallexample ++(defvar resume-timer nil ++ "Timer that `timer-function' used to reschedule itself, or nil.") ++ ++(defun timer-function () ++ ;; @r{If the user types a command while @code{resume-timer}} ++ ;; @r{is active, the next time this function is called from} ++ ;; @r{its main idle timer, deactivate @code{resume-timer}.} ++ (when resume-timer ++ (cancel-timer resume-timer)) ++ ...@var{do the work for a while}... ++ (when @var{taking-a-break} ++ (setq resume-timer ++ (run-with-idle-timer ++ ;; Compute an idle time @var{break-length} ++ ;; more than the current value. ++ (time-add (current-idle-time) ++ (seconds-to-time @var{break-length})) ++ nil ++ 'timer-function)))) ++@end smallexample ++@end defun ++ ++ Some idle timer functions in user Lisp packages have a loop that ++does a certain amount of processing each time around, and exits when ++@code{(input-pending-p)} is non-@code{nil}. That approach seems very ++natural but has two problems: ++ ++@itemize ++@item ++It blocks out all process output (since Emacs accepts process output ++only while waiting). ++ ++@item ++It blocks out any idle timers that ought to run during that time. ++@end itemize ++ ++@noindent ++To avoid these problems, don't use that technique. Instead, write ++such idle timers to reschedule themselves after a brief pause, using ++the method in the @code{timer-function} example above. ++ ++@node Terminal Input ++@section Terminal Input ++@cindex terminal input ++ ++ This section describes functions and variables for recording or ++manipulating terminal input. See @ref{Display}, for related ++functions. ++ ++@menu ++* Input Modes:: Options for how input is processed. ++* Recording Input:: Saving histories of recent or all input events. ++@end menu ++ ++@node Input Modes ++@subsection Input Modes ++@cindex input modes ++@cindex terminal input modes ++ ++@defun set-input-mode interrupt flow meta &optional quit-char ++This function sets the mode for reading keyboard input. If ++@var{interrupt} is non-null, then Emacs uses input interrupts. If it is ++@code{nil}, then it uses @sc{cbreak} mode. The default setting is ++system-dependent. Some systems always use @sc{cbreak} mode regardless ++of what is specified. ++ ++When Emacs communicates directly with X, it ignores this argument and ++uses interrupts if that is the way it knows how to communicate. ++ ++If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} ++(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This ++has no effect except in @sc{cbreak} mode. ++ ++@c Emacs 19 feature ++The argument @var{meta} controls support for input character codes ++above 127. If @var{meta} is @code{t}, Emacs converts characters with ++the 8th bit set into Meta characters. If @var{meta} is @code{nil}, ++Emacs disregards the 8th bit; this is necessary when the terminal uses ++it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, ++Emacs uses all 8 bits of input unchanged. This is good for terminals ++that use 8-bit character sets. ++ ++@c Emacs 19 feature ++If @var{quit-char} is non-@code{nil}, it specifies the character to ++use for quitting. Normally this character is @kbd{C-g}. ++@xref{Quitting}. ++@end defun ++ ++The @code{current-input-mode} function returns the input mode settings ++Emacs is currently using. ++ ++@c Emacs 19 feature ++@defun current-input-mode ++This function returns the current mode for reading keyboard input. It ++returns a list, corresponding to the arguments of @code{set-input-mode}, ++of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in ++which: ++@table @var ++@item interrupt ++is non-@code{nil} when Emacs is using interrupt-driven input. If ++@code{nil}, Emacs is using @sc{cbreak} mode. ++@item flow ++is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) ++flow control for output to the terminal. This value is meaningful only ++when @var{interrupt} is @code{nil}. ++@item meta ++is @code{t} if Emacs treats the eighth bit of input characters as ++the meta bit; @code{nil} means Emacs clears the eighth bit of every ++input character; any other value means Emacs uses all eight bits as the ++basic character code. ++@item quit ++is the character Emacs currently uses for quitting, usually @kbd{C-g}. ++@end table ++@end defun ++ ++@node Recording Input ++@subsection Recording Input ++@cindex recording input ++ ++@defun recent-keys ++This function returns a vector containing the last 300 input events from ++the keyboard or mouse. All input events are included, whether or not ++they were used as parts of key sequences. Thus, you always get the last ++100 input events, not counting events generated by keyboard macros. ++(These are excluded because they are less interesting for debugging; it ++should be enough to see the events that invoked the macros.) ++ ++A call to @code{clear-this-command-keys} (@pxref{Command Loop Info}) ++causes this function to return an empty vector immediately afterward. ++@end defun ++ ++@deffn Command open-dribble-file filename ++@cindex dribble file ++This function opens a @dfn{dribble file} named @var{filename}. When a ++dribble file is open, each input event from the keyboard or mouse (but ++not those from keyboard macros) is written in that file. A ++non-character event is expressed using its printed representation ++surrounded by @samp{<@dots{}>}. ++ ++You close the dribble file by calling this function with an argument ++of @code{nil}. ++ ++This function is normally used to record the input necessary to ++trigger an Emacs bug, for the sake of a bug report. ++ ++@example ++@group ++(open-dribble-file "~/dribble") ++ @result{} nil ++@end group ++@end example ++@end deffn ++ ++ See also the @code{open-termscript} function (@pxref{Terminal Output}). ++ ++@node Terminal Output ++@section Terminal Output ++@cindex terminal output ++ ++ The terminal output functions send output to a text terminal, or keep ++track of output sent to the terminal. The variable @code{baud-rate} ++tells you what Emacs thinks is the output speed of the terminal. ++ ++@defopt baud-rate ++This variable's value is the output speed of the terminal, as far as ++Emacs knows. Setting this variable does not change the speed of actual ++data transmission, but the value is used for calculations such as ++padding. ++ ++ It also affects decisions about whether to scroll part of the ++screen or repaint on text terminals. @xref{Forcing Redisplay}, ++for the corresponding functionality on graphical terminals. ++ ++The value is measured in baud. ++@end defopt ++ ++ If you are running across a network, and different parts of the ++network work at different baud rates, the value returned by Emacs may be ++different from the value used by your local terminal. Some network ++protocols communicate the local terminal speed to the remote machine, so ++that Emacs and other programs can get the proper value, but others do ++not. If Emacs has the wrong value, it makes decisions that are less ++than optimal. To fix the problem, set @code{baud-rate}. ++ ++@defun send-string-to-terminal string &optional terminal ++This function sends @var{string} to @var{terminal} without alteration. ++Control characters in @var{string} have terminal-dependent effects. ++This function operates only on text terminals. @var{terminal} may be ++a terminal object, a frame, or @code{nil} for the selected frame's ++terminal. ++ ++One use of this function is to define function keys on terminals that ++have downloadable function key definitions. For example, this is how (on ++certain terminals) to define function key 4 to move forward four ++characters (by transmitting the characters @kbd{C-u C-f} to the ++computer): ++ ++@example ++@group ++(send-string-to-terminal "\eF4\^U\^F") ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@deffn Command open-termscript filename ++@cindex termscript file ++This function is used to open a @dfn{termscript file} that will record ++all the characters sent by Emacs to the terminal. It returns ++@code{nil}. Termscript files are useful for investigating problems ++where Emacs garbles the screen, problems that are due to incorrect ++Termcap entries or to undesirable settings of terminal options more ++often than to actual Emacs bugs. Once you are certain which characters ++were actually output, you can determine reliably whether they correspond ++to the Termcap specifications in use. ++ ++You close the termscript file by calling this function with an ++argument of @code{nil}. ++ ++See also @code{open-dribble-file} in @ref{Recording Input}. ++ ++@example ++@group ++(open-termscript "../junk/termscript") ++ @result{} nil ++@end group ++@end example ++@end deffn ++ ++@node Sound Output ++@section Sound Output ++@cindex sound ++ ++ To play sound using Emacs, use the function @code{play-sound}. Only ++certain systems are supported; if you call @code{play-sound} on a system ++which cannot really do the job, it gives an error. Emacs version 20 and ++earlier did not support sound at all. ++ ++ The sound must be stored as a file in RIFF-WAVE format (@samp{.wav}) ++or Sun Audio format (@samp{.au}). ++ ++@defun play-sound sound ++This function plays a specified sound. The argument, @var{sound}, has ++the form @code{(sound @var{properties}...)}, where the @var{properties} ++consist of alternating keywords (particular symbols recognized ++specially) and values corresponding to them. ++ ++Here is a table of the keywords that are currently meaningful in ++@var{sound}, and their meanings: ++ ++@table @code ++@item :file @var{file} ++This specifies the file containing the sound to play. ++If the file name is not absolute, it is expanded against ++the directory @code{data-directory}. ++ ++@item :data @var{data} ++This specifies the sound to play without need to refer to a file. The ++value, @var{data}, should be a string containing the same bytes as a ++sound file. We recommend using a unibyte string. ++ ++@item :volume @var{volume} ++This specifies how loud to play the sound. It should be a number in the ++range of 0 to 1. The default is to use whatever volume has been ++specified before. ++ ++@item :device @var{device} ++This specifies the system device on which to play the sound, as a ++string. The default device is system-dependent. ++@end table ++ ++Before actually playing the sound, @code{play-sound} ++calls the functions in the list @code{play-sound-functions}. ++Each function is called with one argument, @var{sound}. ++@end defun ++ ++@defun play-sound-file file &optional volume device ++This function is an alternative interface to playing a sound @var{file} ++specifying an optional @var{volume} and @var{device}. ++@end defun ++ ++@defvar play-sound-functions ++A list of functions to be called before playing a sound. Each function ++is called with one argument, a property list that describes the sound. ++@end defvar ++ ++@node X11 Keysyms ++@section Operating on X11 Keysyms ++@cindex X11 keysyms ++ ++To define system-specific X11 keysyms, set the variable ++@code{system-key-alist}. ++ ++@defvar system-key-alist ++This variable's value should be an alist with one element for each ++system-specific keysym. Each element has the form @code{(@var{code} ++. @var{symbol})}, where @var{code} is the numeric keysym code (not ++including the ``vendor specific'' bit, ++@ifnottex ++-2**28), ++@end ifnottex ++@tex ++$-2^{28}$), ++@end tex ++and @var{symbol} is the name for the function key. ++ ++For example @code{(168 . mute-acute)} defines a system-specific key (used ++by HP X servers) whose numeric code is ++@ifnottex ++-2**28 ++@end ifnottex ++@tex ++$-2^{28}$ ++@end tex +++ 168. ++ ++It is not crucial to exclude from the alist the keysyms of other X ++servers; those do no harm, as long as they don't conflict with the ones ++used by the X server actually in use. ++ ++The variable is always local to the current terminal, and cannot be ++buffer-local. @xref{Multiple Terminals}. ++@end defvar ++ ++You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables: ++ ++@defvar x-alt-keysym ++@defvarx x-meta-keysym ++@defvarx x-hyper-keysym ++@defvarx x-super-keysym ++The name of the keysym that should stand for the Alt modifier ++(respectively, for Meta, Hyper, and Super). For example, here is ++how to swap the Meta and Alt modifiers within Emacs: ++@lisp ++(setq x-alt-keysym 'meta) ++(setq x-meta-keysym 'alt) ++@end lisp ++@end defvar ++ ++@node Batch Mode ++@section Batch Mode ++@cindex batch mode ++ ++ The command-line option @samp{-batch} causes Emacs to run ++noninteractively. In this mode, Emacs does not read commands from the ++terminal, it does not alter the terminal modes, and it does not expect ++to be outputting to an erasable screen. The idea is that you specify ++Lisp programs to run; when they are finished, Emacs should exit. The ++way to specify the programs to run is with @samp{-l @var{file}}, which ++loads the library named @var{file}, or @samp{-f @var{function}}, which ++calls @var{function} with no arguments, or @samp{--eval @var{form}}. ++ ++ Any Lisp program output that would normally go to the echo area, ++either using @code{message}, or using @code{prin1}, etc., with @code{t} ++as the stream, goes instead to Emacs's standard error descriptor when ++in batch mode. Similarly, input that would normally come from the ++minibuffer is read from the standard input descriptor. ++Thus, Emacs behaves much like a noninteractive ++application program. (The echo area output that Emacs itself normally ++generates, such as command echoing, is suppressed entirely.) ++ ++@defvar noninteractive ++This variable is non-@code{nil} when Emacs is running in batch mode. ++@end defvar ++ ++@node Session Management ++@section Session Management ++@cindex session manager ++ ++Emacs supports the X Session Management Protocol, which is used to ++suspend and restart applications. In the X Window System, a program ++called the @dfn{session manager} is responsible for keeping track of ++the applications that are running. When the X server shuts down, the ++session manager asks applications to save their state, and delays the ++actual shutdown until they respond. An application can also cancel ++the shutdown. ++ ++When the session manager restarts a suspended session, it directs ++these applications to individually reload their saved state. It does ++this by specifying a special command-line argument that says what ++saved session to restore. For Emacs, this argument is @samp{--smid ++@var{session}}. ++ ++@defvar emacs-save-session-functions ++Emacs supports saving state via a hook called ++@code{emacs-save-session-functions}. Emacs runs this hook when the ++session manager tells it that the window system is shutting down. The ++functions are called with no arguments, and with the current buffer ++set to a temporary buffer. Each function can use @code{insert} to add ++Lisp code to this buffer. At the end, Emacs saves the buffer in a ++file, called the @dfn{session file}. ++ ++@findex emacs-session-restore ++Subsequently, when the session manager restarts Emacs, it loads the ++session file automatically (@pxref{Loading}). This is performed by a ++function named @code{emacs-session-restore}, which is called during ++startup. @xref{Startup Summary}. ++ ++If a function in @code{emacs-save-session-functions} returns ++non-@code{nil}, Emacs tells the session manager to cancel the ++shutdown. ++@end defvar ++ ++Here is an example that just inserts some text into @samp{*scratch*} when ++Emacs is restarted by the session manager. ++ ++@example ++@group ++(add-hook 'emacs-save-session-functions 'save-yourself-test) ++@end group ++ ++@group ++(defun save-yourself-test () ++ (insert "(save-excursion ++ (switch-to-buffer \"*scratch*\") ++ (insert \"I am restored\"))") ++ nil) ++@end group ++@end example ++ ++@ignore ++ arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7 ++@end ignore +diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi +new file mode 100644 +index 0000000..d3c13a3 +--- /dev/null ++++ b/doc/lispref/positions.texi +@@ -0,0 +1,1016 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/positions ++@node Positions, Markers, Frames, Top ++@chapter Positions ++@cindex position (in buffer) ++ ++ A @dfn{position} is the index of a character in the text of a buffer. ++More precisely, a position identifies the place between two characters ++(or before the first character, or after the last character), so we can ++speak of the character before or after a given position. However, we ++often speak of the character ``at'' a position, meaning the character ++after that position. ++ ++ Positions are usually represented as integers starting from 1, but ++can also be represented as @dfn{markers}---special objects that ++relocate automatically when text is inserted or deleted so they stay ++with the surrounding characters. Functions that expect an argument to ++be a position (an integer), but accept a marker as a substitute, ++normally ignore which buffer the marker points into; they convert the ++marker to an integer, and use that integer, exactly as if you had ++passed the integer as the argument, even if the marker points to the ++``wrong'' buffer. A marker that points nowhere cannot convert to an ++integer; using it instead of an integer causes an error. ++@xref{Markers}. ++ ++ See also the ``field'' feature (@pxref{Fields}), which provides ++functions that are used by many cursor-motion commands. ++ ++@menu ++* Point:: The special position where editing takes place. ++* Motion:: Changing point. ++* Excursions:: Temporary motion and buffer changes. ++* Narrowing:: Restricting editing to a portion of the buffer. ++@end menu ++ ++@node Point ++@section Point ++@cindex point ++ ++ @dfn{Point} is a special buffer position used by many editing ++commands, including the self-inserting typed characters and text ++insertion functions. Other commands move point through the text ++to allow editing and insertion at different places. ++ ++ Like other positions, point designates a place between two characters ++(or before the first character, or after the last character), rather ++than a particular character. Usually terminals display the cursor over ++the character that immediately follows point; point is actually before ++the character on which the cursor sits. ++ ++@cindex point with narrowing ++ The value of point is a number no less than 1, and no greater than the ++buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then ++point is constrained to fall within the accessible portion of the buffer ++(possibly at one end of it). ++ ++ Each buffer has its own value of point, which is independent of the ++value of point in other buffers. Each window also has a value of point, ++which is independent of the value of point in other windows on the same ++buffer. This is why point can have different values in various windows ++that display the same buffer. When a buffer appears in only one window, ++the buffer's point and the window's point normally have the same value, ++so the distinction is rarely important. @xref{Window Point}, for more ++details. ++ ++@defun point ++@cindex current buffer position ++This function returns the value of point in the current buffer, ++as an integer. ++ ++@need 700 ++@example ++@group ++(point) ++ @result{} 175 ++@end group ++@end example ++@end defun ++ ++@defun point-min ++This function returns the minimum accessible value of point in the ++current buffer. This is normally 1, but if narrowing is in effect, it ++is the position of the start of the region that you narrowed to. ++(@xref{Narrowing}.) ++@end defun ++ ++@defun point-max ++This function returns the maximum accessible value of point in the ++current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is ++in effect, in which case it is the position of the end of the region ++that you narrowed to. (@xref{Narrowing}.) ++@end defun ++ ++@defun buffer-end flag ++This function returns @code{(point-max)} if @var{flag} is greater than ++0, @code{(point-min)} otherwise. The argument @var{flag} must be a ++number. ++@end defun ++ ++@defun buffer-size &optional buffer ++This function returns the total number of characters in the current ++buffer. In the absence of any narrowing (@pxref{Narrowing}), ++@code{point-max} returns a value one larger than this. ++ ++If you specify a buffer, @var{buffer}, then the value is the ++size of @var{buffer}. ++ ++@example ++@group ++(buffer-size) ++ @result{} 35 ++@end group ++@group ++(point-max) ++ @result{} 36 ++@end group ++@end example ++@end defun ++ ++@node Motion ++@section Motion ++@cindex motion by chars, words, lines, lists ++ ++ Motion functions change the value of point, either relative to the ++current value of point, relative to the beginning or end of the buffer, ++or relative to the edges of the selected window. @xref{Point}. ++ ++@menu ++* Character Motion:: Moving in terms of characters. ++* Word Motion:: Moving in terms of words. ++* Buffer End Motion:: Moving to the beginning or end of the buffer. ++* Text Lines:: Moving in terms of lines of text. ++* Screen Lines:: Moving in terms of lines as displayed. ++* List Motion:: Moving by parsing lists and sexps. ++* Skipping Characters:: Skipping characters belonging to a certain set. ++@end menu ++ ++@node Character Motion ++@subsection Motion by Characters ++ ++ These functions move point based on a count of characters. ++@code{goto-char} is the fundamental primitive; the other functions use ++that. ++ ++@deffn Command goto-char position ++This function sets point in the current buffer to the value ++@var{position}. If @var{position} is less than 1, it moves point to the ++beginning of the buffer. If @var{position} is greater than the length ++of the buffer, it moves point to the end. ++ ++If narrowing is in effect, @var{position} still counts from the ++beginning of the buffer, but point cannot go outside the accessible ++portion. If @var{position} is out of range, @code{goto-char} moves ++point to the beginning or the end of the accessible portion. ++ ++When this function is called interactively, @var{position} is the ++numeric prefix argument, if provided; otherwise it is read from the ++minibuffer. ++ ++@code{goto-char} returns @var{position}. ++@end deffn ++ ++@deffn Command forward-char &optional count ++@c @kindex beginning-of-buffer ++@c @kindex end-of-buffer ++This function moves point @var{count} characters forward, towards the ++end of the buffer (or backward, towards the beginning of the buffer, if ++@var{count} is negative). If @var{count} is @code{nil}, the default ++is 1. ++ ++If this attempts to move past the beginning or end of the buffer (or ++the limits of the accessible portion, when narrowing is in effect), it ++signals an error with error symbol @code{beginning-of-buffer} or ++@code{end-of-buffer}. ++ ++In an interactive call, @var{count} is the numeric prefix argument. ++@end deffn ++ ++@deffn Command backward-char &optional count ++This is just like @code{forward-char} except that it moves ++in the opposite direction. ++@end deffn ++ ++@node Word Motion ++@subsection Motion by Words ++ ++ These functions for parsing words use the syntax table to decide ++whether a given character is part of a word. @xref{Syntax Tables}. ++ ++@deffn Command forward-word &optional count ++This function moves point forward @var{count} words (or backward if ++@var{count} is negative). If @var{count} is @code{nil}, it moves ++forward one word. ++ ++``Moving one word'' means moving until point crosses a ++word-constituent character and then encounters a word-separator ++character. However, this function cannot move point past the boundary ++of the accessible portion of the buffer, or across a field boundary ++(@pxref{Fields}). The most common case of a field boundary is the end ++of the prompt in the minibuffer. ++ ++If it is possible to move @var{count} words, without being stopped ++prematurely by the buffer boundary or a field boundary, the value is ++@code{t}. Otherwise, the return value is @code{nil} and point stops at ++the buffer boundary or field boundary. ++ ++If @code{inhibit-field-text-motion} is non-@code{nil}, ++this function ignores field boundaries. ++ ++In an interactive call, @var{count} is specified by the numeric prefix ++argument. If @var{count} is omitted or @code{nil}, it defaults to 1. ++@end deffn ++ ++@deffn Command backward-word &optional count ++This function is just like @code{forward-word}, except that it moves ++backward until encountering the front of a word, rather than forward. ++@end deffn ++ ++@defopt words-include-escapes ++@c Emacs 19 feature ++This variable affects the behavior of @code{forward-word} and everything ++that uses it. If it is non-@code{nil}, then characters in the ++``escape'' and ``character quote'' syntax classes count as part of ++words. Otherwise, they do not. ++@end defopt ++ ++@defvar inhibit-field-text-motion ++If this variable is non-@code{nil}, certain motion functions including ++@code{forward-word}, @code{forward-sentence}, and ++@code{forward-paragraph} ignore field boundaries. ++@end defvar ++ ++@node Buffer End Motion ++@subsection Motion to an End of the Buffer ++@cindex move to beginning or end of buffer ++ ++ To move point to the beginning of the buffer, write: ++ ++@example ++@group ++(goto-char (point-min)) ++@end group ++@end example ++ ++@noindent ++Likewise, to move to the end of the buffer, use: ++ ++@example ++@group ++(goto-char (point-max)) ++@end group ++@end example ++ ++ Here are two commands that users use to do these things. They are ++documented here to warn you not to use them in Lisp programs, because ++they set the mark and display messages in the echo area. ++ ++@deffn Command beginning-of-buffer &optional n ++This function moves point to the beginning of the buffer (or the limits ++of the accessible portion, when narrowing is in effect), setting the ++mark at the previous position (except in Transient Mark mode, if ++the mark is already active, it does not set the mark.) ++ ++If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the ++way from the beginning of the accessible portion of the buffer. In an ++interactive call, @var{n} is the numeric prefix argument, if provided; ++otherwise @var{n} defaults to @code{nil}. ++ ++@strong{Warning:} Don't use this function in Lisp programs! ++@end deffn ++ ++@deffn Command end-of-buffer &optional n ++This function moves point to the end of the buffer (or the limits of ++the accessible portion, when narrowing is in effect), setting the mark ++at the previous position (except in Transient Mark mode when the mark ++is already active). If @var{n} is non-@code{nil}, then it puts point ++@var{n} tenths of the way from the end of the accessible portion of ++the buffer. ++ ++In an interactive call, @var{n} is the numeric prefix argument, ++if provided; otherwise @var{n} defaults to @code{nil}. ++ ++@strong{Warning:} Don't use this function in Lisp programs! ++@end deffn ++ ++@node Text Lines ++@subsection Motion by Text Lines ++@cindex lines ++ ++ Text lines are portions of the buffer delimited by newline characters, ++which are regarded as part of the previous line. The first text line ++begins at the beginning of the buffer, and the last text line ends at ++the end of the buffer whether or not the last character is a newline. ++The division of the buffer into text lines is not affected by the width ++of the window, by line continuation in display, or by how tabs and ++control characters are displayed. ++ ++@deffn Command goto-line line &optional buffer ++This function moves point to the front of the @var{line}th line, ++counting from line 1 at beginning of the buffer, and leaves mark at the ++previous position. If @var{line} is less than 1, it moves point to the ++beginning of the buffer. If @var{line} is greater than the number of ++lines in the buffer, it moves point to the end of the buffer---that is, ++the @emph{end of the last line} of the buffer. ++ ++If narrowing is in effect, then @var{line} still counts from the ++beginning of the buffer, but point cannot go outside the accessible ++portion. So @code{goto-line} moves point to the beginning or end of the ++accessible portion, if the line number specifies an inaccessible ++position. ++ ++The return value of @code{goto-line} is the difference between ++@var{line} and the line number of the line to which point actually was ++able to move (in the full buffer, before taking account of narrowing). ++Thus, the value is positive if the scan encounters the real end of the ++buffer before finding the specified line. The value is zero if scan ++encounters the end of the accessible portion, but not the real end of ++the buffer. ++ ++If you provide the optional argument @var{buffer}, @code{goto-line} uses ++@var{buffer} instead of the current buffer and displays it in another ++window, if it was not already visible. ++@end deffn ++ ++@deffn Command beginning-of-line &optional count ++This function moves point to the beginning of the current line. With an ++argument @var{count} not @code{nil} or 1, it moves forward ++@var{count}@minus{}1 lines and then to the beginning of the line. ++ ++This function does not move point across a field boundary ++(@pxref{Fields}) unless doing so would move beyond there to a ++different line; therefore, if @var{count} is @code{nil} or 1, and ++point starts at a field boundary, point does not move. To ignore ++field boundaries, either bind @code{inhibit-field-text-motion} to ++@code{t}, or use the @code{forward-line} function instead. For ++instance, @code{(forward-line 0)} does the same thing as ++@code{(beginning-of-line)}, except that it ignores field boundaries. ++ ++If this function reaches the end of the buffer (or of the accessible ++portion, if narrowing is in effect), it positions point there. No error ++is signaled. ++@end deffn ++ ++@defun line-beginning-position &optional count ++Return the position that @code{(beginning-of-line @var{count})} ++would move to. ++@end defun ++ ++@deffn Command end-of-line &optional count ++This function moves point to the end of the current line. With an ++argument @var{count} not @code{nil} or 1, it moves forward ++@var{count}@minus{}1 lines and then to the end of the line. ++ ++This function does not move point across a field boundary ++(@pxref{Fields}) unless doing so would move beyond there to a ++different line; therefore, if @var{count} is @code{nil} or 1, and ++point starts at a field boundary, point does not move. To ignore ++field boundaries, bind @code{inhibit-field-text-motion} to @code{t}. ++ ++If this function reaches the end of the buffer (or of the accessible ++portion, if narrowing is in effect), it positions point there. No error ++is signaled. ++@end deffn ++ ++@defun line-end-position &optional count ++Return the position that @code{(end-of-line @var{count})} ++would move to. ++@end defun ++ ++@deffn Command forward-line &optional count ++@cindex beginning of line ++This function moves point forward @var{count} lines, to the beginning of ++the line. If @var{count} is negative, it moves point ++@minus{}@var{count} lines backward, to the beginning of a line. If ++@var{count} is zero, it moves point to the beginning of the current ++line. If @var{count} is @code{nil}, that means 1. ++ ++If @code{forward-line} encounters the beginning or end of the buffer (or ++of the accessible portion) before finding that many lines, it sets point ++there. No error is signaled. ++ ++@code{forward-line} returns the difference between @var{count} and the ++number of lines actually moved. If you attempt to move down five lines ++from the beginning of a buffer that has only three lines, point stops at ++the end of the last line, and the value will be 2. ++ ++In an interactive call, @var{count} is the numeric prefix argument. ++@end deffn ++ ++@defun count-lines start end ++@cindex lines in region ++@anchor{Definition of count-lines} ++This function returns the number of lines between the positions ++@var{start} and @var{end} in the current buffer. If @var{start} and ++@var{end} are equal, then it returns 0. Otherwise it returns at least ++1, even if @var{start} and @var{end} are on the same line. This is ++because the text between them, considered in isolation, must contain at ++least one line unless it is empty. ++ ++Here is an example of using @code{count-lines}: ++ ++@example ++@group ++(defun current-line () ++ "Return the vertical position of point@dots{}" ++ (+ (count-lines (window-start) (point)) ++ (if (= (current-column) 0) 1 0))) ++@end group ++@end example ++@end defun ++ ++@defun line-number-at-pos &optional pos ++@cindex line number ++This function returns the line number in the current buffer ++corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil} ++or omitted, the current buffer position is used. ++@end defun ++ ++@ignore ++@c ================ ++The @code{previous-line} and @code{next-line} commands are functions ++that should not be used in programs. They are for users and are ++mentioned here only for completeness. ++ ++@deffn Command previous-line count ++@cindex goal column ++This function moves point up @var{count} lines (down if @var{count} ++is negative). In moving, it attempts to keep point in the ``goal column'' ++(normally the same column that it was at the beginning of the move). ++ ++If there is no character in the target line exactly under the current ++column, point is positioned after the character in that line which ++spans this column, or at the end of the line if it is not long enough. ++ ++If it attempts to move beyond the top or bottom of the buffer (or clipped ++region), then point is positioned in the goal column in the top or ++bottom line. No error is signaled. ++ ++In an interactive call, @var{count} will be the numeric ++prefix argument. ++ ++The command @code{set-goal-column} can be used to create a semipermanent ++goal column to which this command always moves. Then it does not try to ++move vertically. ++ ++If you are thinking of using this in a Lisp program, consider using ++@code{forward-line} with a negative argument instead. It is usually easier ++to use and more reliable (no dependence on goal column, etc.). ++@end deffn ++ ++@deffn Command next-line count ++This function moves point down @var{count} lines (up if @var{count} ++is negative). In moving, it attempts to keep point in the ``goal column'' ++(normally the same column that it was at the beginning of the move). ++ ++If there is no character in the target line exactly under the current ++column, point is positioned after the character in that line which ++spans this column, or at the end of the line if it is not long enough. ++ ++If it attempts to move beyond the top or bottom of the buffer (or clipped ++region), then point is positioned in the goal column in the top or ++bottom line. No error is signaled. ++ ++In the case where the @var{count} is 1, and point is on the last ++line of the buffer (or clipped region), a new empty line is inserted at the ++end of the buffer (or clipped region) and point moved there. ++ ++In an interactive call, @var{count} will be the numeric ++prefix argument. ++ ++The command @code{set-goal-column} can be used to create a semipermanent ++goal column to which this command always moves. Then it does not try to ++move vertically. ++ ++If you are thinking of using this in a Lisp program, consider using ++@code{forward-line} instead. It is usually easier ++to use and more reliable (no dependence on goal column, etc.). ++@end deffn ++ ++@c ================ ++@end ignore ++ ++ Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}. ++These functions do not move point, but test whether it is already at the ++beginning or end of a line. ++ ++@node Screen Lines ++@subsection Motion by Screen Lines ++ ++ The line functions in the previous section count text lines, delimited ++only by newline characters. By contrast, these functions count screen ++lines, which are defined by the way the text appears on the screen. A ++text line is a single screen line if it is short enough to fit the width ++of the selected window, but otherwise it may occupy several screen ++lines. ++ ++ In some cases, text lines are truncated on the screen rather than ++continued onto additional screen lines. In these cases, ++@code{vertical-motion} moves point much like @code{forward-line}. ++@xref{Truncation}. ++ ++ Because the width of a given string depends on the flags that control ++the appearance of certain characters, @code{vertical-motion} behaves ++differently, for a given piece of text, depending on the buffer it is ++in, and even on the selected window (because the width, the truncation ++flag, and display table may vary between windows). @xref{Usual ++Display}. ++ ++ These functions scan text to determine where screen lines break, and ++thus take time proportional to the distance scanned. If you intend to ++use them heavily, Emacs provides caches which may improve the ++performance of your code. @xref{Truncation, cache-long-line-scans}. ++ ++@defun vertical-motion count &optional window ++This function moves point to the start of the screen line @var{count} ++screen lines down from the screen line containing point. If @var{count} ++is negative, it moves up instead. ++ ++The @var{count} argument can be a cons cell, @code{(@var{cols} ++. @var{lines})}, instead of an integer. Then the function moves by ++@var{lines} screen lines, and puts point @var{cols} columns from the ++start of that screen line. ++ ++The return value is the number of screen lines over which point was ++moved. The value may be less in absolute value than @var{count} if ++the beginning or end of the buffer was reached. ++ ++The window @var{window} is used for obtaining parameters such as the ++width, the horizontal scrolling, and the display table. But ++@code{vertical-motion} always operates on the current buffer, even if ++@var{window} currently displays some other buffer. ++@end defun ++ ++@defun count-screen-lines &optional beg end count-final-newline window ++This function returns the number of screen lines in the text from ++@var{beg} to @var{end}. The number of screen lines may be different ++from the number of actual lines, due to line continuation, the display ++table, etc. If @var{beg} and @var{end} are @code{nil} or omitted, ++they default to the beginning and end of the accessible portion of the ++buffer. ++ ++If the region ends with a newline, that is ignored unless the optional ++third argument @var{count-final-newline} is non-@code{nil}. ++ ++The optional fourth argument @var{window} specifies the window for ++obtaining parameters such as width, horizontal scrolling, and so on. ++The default is to use the selected window's parameters. ++ ++Like @code{vertical-motion}, @code{count-screen-lines} always uses the ++current buffer, regardless of which buffer is displayed in ++@var{window}. This makes possible to use @code{count-screen-lines} in ++any buffer, whether or not it is currently displayed in some window. ++@end defun ++ ++@deffn Command move-to-window-line count ++This function moves point with respect to the text currently displayed ++in the selected window. It moves point to the beginning of the screen ++line @var{count} screen lines from the top of the window. If ++@var{count} is negative, that specifies a position ++@w{@minus{}@var{count}} lines from the bottom (or the last line of the ++buffer, if the buffer ends above the specified screen position). ++ ++If @var{count} is @code{nil}, then point moves to the beginning of the ++line in the middle of the window. If the absolute value of @var{count} ++is greater than the size of the window, then point moves to the place ++that would appear on that screen line if the window were tall enough. ++This will probably cause the next redisplay to scroll to bring that ++location onto the screen. ++ ++In an interactive call, @var{count} is the numeric prefix argument. ++ ++The value returned is the window line number point has moved to, with ++the top line in the window numbered 0. ++@end deffn ++ ++@defun compute-motion from frompos to topos width offsets window ++This function scans the current buffer, calculating screen positions. ++It scans the buffer forward from position @var{from}, assuming that is ++at screen coordinates @var{frompos}, to position @var{to} or coordinates ++@var{topos}, whichever comes first. It returns the ending buffer ++position and screen coordinates. ++ ++The coordinate arguments @var{frompos} and @var{topos} are cons cells of ++the form @code{(@var{hpos} . @var{vpos})}. ++ ++The argument @var{width} is the number of columns available to display ++text; this affects handling of continuation lines. @code{nil} means ++the actual number of usable text columns in the window, which is ++equivalent to the value returned by @code{(window-width window)}. ++ ++The argument @var{offsets} is either @code{nil} or a cons cell of the ++form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is ++the number of columns not being displayed at the left margin; most ++callers get this by calling @code{window-hscroll}. Meanwhile, ++@var{tab-offset} is the offset between column numbers on the screen and ++column numbers in the buffer. This can be nonzero in a continuation ++line, when the previous screen lines' widths do not add up to a multiple ++of @code{tab-width}. It is always zero in a non-continuation line. ++ ++The window @var{window} serves only to specify which display table to ++use. @code{compute-motion} always operates on the current buffer, ++regardless of what buffer is displayed in @var{window}. ++ ++The return value is a list of five elements: ++ ++@example ++(@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin}) ++@end example ++ ++@noindent ++Here @var{pos} is the buffer position where the scan stopped, @var{vpos} ++is the vertical screen position, and @var{hpos} is the horizontal screen ++position. ++ ++The result @var{prevhpos} is the horizontal position one character back ++from @var{pos}. The result @var{contin} is @code{t} if the last line ++was continued after (or within) the previous character. ++ ++For example, to find the buffer position of column @var{col} of screen line ++@var{line} of a certain window, pass the window's display start location ++as @var{from} and the window's upper-left coordinates as @var{frompos}. ++Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to ++the end of the accessible portion of the buffer, and pass @var{line} and ++@var{col} as @var{topos}. Here's a function that does this: ++ ++@example ++(defun coordinates-of-position (col line) ++ (car (compute-motion (window-start) ++ '(0 . 0) ++ (point-max) ++ (cons col line) ++ (window-width) ++ (cons (window-hscroll) 0) ++ (selected-window)))) ++@end example ++ ++When you use @code{compute-motion} for the minibuffer, you need to use ++@code{minibuffer-prompt-width} to get the horizontal position of the ++beginning of the first screen line. @xref{Minibuffer Contents}. ++@end defun ++ ++@node List Motion ++@comment node-name, next, previous, up ++@subsection Moving over Balanced Expressions ++@cindex sexp motion ++@cindex Lisp expression motion ++@cindex list motion ++@cindex balanced parenthesis motion ++ ++ Here are several functions concerned with balanced-parenthesis ++expressions (also called @dfn{sexps} in connection with moving across ++them in Emacs). The syntax table controls how these functions interpret ++various characters; see @ref{Syntax Tables}. @xref{Parsing ++Expressions}, for lower-level primitives for scanning sexps or parts of ++sexps. For user-level commands, see @ref{Parentheses,, Commands for ++Editing with Parentheses, emacs, The GNU Emacs Manual}. ++ ++@deffn Command forward-list &optional arg ++This function moves forward across @var{arg} (default 1) balanced groups of ++parentheses. (Other syntactic entities such as words or paired string ++quotes are ignored.) ++@end deffn ++ ++@deffn Command backward-list &optional arg ++This function moves backward across @var{arg} (default 1) balanced groups of ++parentheses. (Other syntactic entities such as words or paired string ++quotes are ignored.) ++@end deffn ++ ++@deffn Command up-list &optional arg ++This function moves forward out of @var{arg} (default 1) levels of parentheses. ++A negative argument means move backward but still to a less deep spot. ++@end deffn ++ ++@deffn Command down-list &optional arg ++This function moves forward into @var{arg} (default 1) levels of ++parentheses. A negative argument means move backward but still go ++deeper in parentheses (@minus{}@var{arg} levels). ++@end deffn ++ ++@deffn Command forward-sexp &optional arg ++This function moves forward across @var{arg} (default 1) balanced expressions. ++Balanced expressions include both those delimited by parentheses and ++other kinds, such as words and string constants. ++@xref{Parsing Expressions}. For example, ++ ++@example ++@group ++---------- Buffer: foo ---------- ++(concat@point{} "foo " (car x) y z) ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(forward-sexp 3) ++ @result{} nil ++ ++---------- Buffer: foo ---------- ++(concat "foo " (car x) y@point{} z) ++---------- Buffer: foo ---------- ++@end group ++@end example ++@end deffn ++ ++@deffn Command backward-sexp &optional arg ++This function moves backward across @var{arg} (default 1) balanced expressions. ++@end deffn ++ ++@deffn Command beginning-of-defun &optional arg ++This function moves back to the @var{arg}th beginning of a defun. If ++@var{arg} is negative, this actually moves forward, but it still moves ++to the beginning of a defun, not to the end of one. @var{arg} defaults ++to 1. ++@end deffn ++ ++@deffn Command end-of-defun &optional arg ++This function moves forward to the @var{arg}th end of a defun. If ++@var{arg} is negative, this actually moves backward, but it still moves ++to the end of a defun, not to the beginning of one. @var{arg} defaults ++to 1. ++@end deffn ++ ++@defopt defun-prompt-regexp ++If non-@code{nil}, this buffer-local variable holds a regular ++expression that specifies what text can appear before the ++open-parenthesis that starts a defun. That is to say, a defun begins ++on a line that starts with a match for this regular expression, ++followed by a character with open-parenthesis syntax. ++@end defopt ++ ++@defopt open-paren-in-column-0-is-defun-start ++If this variable's value is non-@code{nil}, an open parenthesis in ++column 0 is considered to be the start of a defun. If it is ++@code{nil}, an open parenthesis in column 0 has no special meaning. ++The default is @code{t}. ++@end defopt ++ ++@defvar beginning-of-defun-function ++If non-@code{nil}, this variable holds a function for finding the ++beginning of a defun. The function @code{beginning-of-defun} ++calls this function instead of using its normal method, passing it its ++optional argument. If the argument is non-@code{nil}, the function ++should move back by that many functions, like ++@code{beginning-of-defun} does. ++@end defvar ++ ++@defvar end-of-defun-function ++If non-@code{nil}, this variable holds a function for finding the end of ++a defun. The function @code{end-of-defun} calls this function instead ++of using its normal method. ++@end defvar ++ ++@node Skipping Characters ++@comment node-name, next, previous, up ++@subsection Skipping Characters ++@cindex skipping characters ++ ++ The following two functions move point over a specified set of ++characters. For example, they are often used to skip whitespace. For ++related functions, see @ref{Motion and Syntax}. ++ ++These functions convert the set string to multibyte if the buffer is ++multibyte, and they convert it to unibyte if the buffer is unibyte, as ++the search functions do (@pxref{Searching and Matching}). ++ ++@defun skip-chars-forward character-set &optional limit ++This function moves point in the current buffer forward, skipping over a ++given set of characters. It examines the character following point, ++then advances point if the character matches @var{character-set}. This ++continues until it reaches a character that does not match. The ++function returns the number of characters moved over. ++ ++The argument @var{character-set} is a string, like the inside of a ++@samp{[@dots{}]} in a regular expression except that @samp{]} does not ++terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. ++Thus, @code{"a-zA-Z"} skips over all letters, stopping before the ++first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before ++the first letter. See @xref{Regular Expressions}. Character classes ++can also be used, e.g. @code{"[:alnum:]"}. See @pxref{Char Classes}. ++ ++If @var{limit} is supplied (it must be a number or a marker), it ++specifies the maximum position in the buffer that point can be skipped ++to. Point will stop at or before @var{limit}. ++ ++In the following example, point is initially located directly before the ++@samp{T}. After the form is evaluated, point is located at the end of ++that line (between the @samp{t} of @samp{hat} and the newline). The ++function skips all letters and spaces, but not newlines. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++I read "@point{}The cat in the hat ++comes back" twice. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(skip-chars-forward "a-zA-Z ") ++ @result{} 18 ++ ++---------- Buffer: foo ---------- ++I read "The cat in the hat@point{} ++comes back" twice. ++---------- Buffer: foo ---------- ++@end group ++@end example ++@end defun ++ ++@defun skip-chars-backward character-set &optional limit ++This function moves point backward, skipping characters that match ++@var{character-set}, until @var{limit}. It is just like ++@code{skip-chars-forward} except for the direction of motion. ++ ++The return value indicates the distance traveled. It is an integer that ++is zero or less. ++@end defun ++ ++@node Excursions ++@section Excursions ++@cindex excursion ++ ++ It is often useful to move point ``temporarily'' within a localized ++portion of the program, or to switch buffers temporarily. This is ++called an @dfn{excursion}, and it is done with the @code{save-excursion} ++special form. This construct initially remembers the identity of the ++current buffer, and its values of point and the mark, and restores them ++after the completion of the excursion. ++ ++ The forms for saving and restoring the configuration of windows are ++described elsewhere (see @ref{Window Configurations}, and @pxref{Frame ++Configurations}). ++ ++@defspec save-excursion body@dots{} ++@cindex mark excursion ++@cindex point excursion ++The @code{save-excursion} special form saves the identity of the current ++buffer and the values of point and the mark in it, evaluates ++@var{body}, and finally restores the buffer and its saved values of ++point and the mark. All three saved values are restored even in case of ++an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). ++ ++The @code{save-excursion} special form is the standard way to switch ++buffers or move point within one part of a program and avoid affecting ++the rest of the program. It is used more than 4000 times in the Lisp ++sources of Emacs. ++ ++@code{save-excursion} does not save the values of point and the mark for ++other buffers, so changes in other buffers remain in effect after ++@code{save-excursion} exits. ++ ++@cindex window excursions ++Likewise, @code{save-excursion} does not restore window-buffer ++correspondences altered by functions such as @code{switch-to-buffer}. ++One way to restore these correspondences, and the selected window, is to ++use @code{save-window-excursion} inside @code{save-excursion} ++(@pxref{Window Configurations}). ++ ++The value returned by @code{save-excursion} is the result of the last ++form in @var{body}, or @code{nil} if no body forms were given. ++ ++@example ++@group ++(save-excursion @var{forms}) ++@equiv{} ++(let ((old-buf (current-buffer)) ++ (old-pnt (point-marker)) ++@end group ++ (old-mark (copy-marker (mark-marker)))) ++ (unwind-protect ++ (progn @var{forms}) ++ (set-buffer old-buf) ++@group ++ (goto-char old-pnt) ++ (set-marker (mark-marker) old-mark))) ++@end group ++@end example ++@end defspec ++ ++ @strong{Warning:} Ordinary insertion of text adjacent to the saved ++point value relocates the saved value, just as it relocates all markers. ++More precisely, the saved value is a marker with insertion type ++@code{nil}. @xref{Marker Insertion Types}. Therefore, when the saved ++point value is restored, it normally comes before the inserted text. ++ ++ Although @code{save-excursion} saves the location of the mark, it does ++not prevent functions which modify the buffer from setting ++@code{deactivate-mark}, and thus causing the deactivation of the mark ++after the command finishes. @xref{The Mark}. ++ ++@node Narrowing ++@section Narrowing ++@cindex narrowing ++@cindex restriction (in a buffer) ++@cindex accessible portion (of a buffer) ++ ++ @dfn{Narrowing} means limiting the text addressable by Emacs editing ++commands to a limited range of characters in a buffer. The text that ++remains addressable is called the @dfn{accessible portion} of the ++buffer. ++ ++ Narrowing is specified with two buffer positions which become the ++beginning and end of the accessible portion. For most editing commands ++and most Emacs primitives, these positions replace the values of the ++beginning and end of the buffer. While narrowing is in effect, no text ++outside the accessible portion is displayed, and point cannot move ++outside the accessible portion. ++ ++ Values such as positions or line numbers, which usually count from the ++beginning of the buffer, do so despite narrowing, but the functions ++which use them refuse to operate on text that is inaccessible. ++ ++ The commands for saving buffers are unaffected by narrowing; they save ++the entire buffer regardless of any narrowing. ++ ++ If you need to display in a single buffer several very different ++types of text, consider using an alternative facility described in ++@ref{Swapping Text}. ++ ++@deffn Command narrow-to-region start end ++This function sets the accessible portion of the current buffer to start ++at @var{start} and end at @var{end}. Both arguments should be character ++positions. ++ ++In an interactive call, @var{start} and @var{end} are set to the bounds ++of the current region (point and the mark, with the smallest first). ++@end deffn ++ ++@deffn Command narrow-to-page &optional move-count ++This function sets the accessible portion of the current buffer to ++include just the current page. An optional first argument ++@var{move-count} non-@code{nil} means to move forward or backward by ++@var{move-count} pages and then narrow to one page. The variable ++@code{page-delimiter} specifies where pages start and end ++(@pxref{Standard Regexps}). ++ ++In an interactive call, @var{move-count} is set to the numeric prefix ++argument. ++@end deffn ++ ++@deffn Command widen ++@cindex widening ++This function cancels any narrowing in the current buffer, so that the ++entire contents are accessible. This is called @dfn{widening}. ++It is equivalent to the following expression: ++ ++@example ++(narrow-to-region 1 (1+ (buffer-size))) ++@end example ++@end deffn ++ ++@defspec save-restriction body@dots{} ++This special form saves the current bounds of the accessible portion, ++evaluates the @var{body} forms, and finally restores the saved bounds, ++thus restoring the same state of narrowing (or absence thereof) formerly ++in effect. The state of narrowing is restored even in the event of an ++abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). ++Therefore, this construct is a clean way to narrow a buffer temporarily. ++ ++The value returned by @code{save-restriction} is that returned by the ++last form in @var{body}, or @code{nil} if no body forms were given. ++ ++@c Wordy to avoid overfull hbox. --rjc 16mar92 ++@strong{Caution:} it is easy to make a mistake when using the ++@code{save-restriction} construct. Read the entire description here ++before you try it. ++ ++If @var{body} changes the current buffer, @code{save-restriction} still ++restores the restrictions on the original buffer (the buffer whose ++restrictions it saved from), but it does not restore the identity of the ++current buffer. ++ ++@code{save-restriction} does @emph{not} restore point and the mark; use ++@code{save-excursion} for that. If you use both @code{save-restriction} ++and @code{save-excursion} together, @code{save-excursion} should come ++first (on the outside). Otherwise, the old point value would be ++restored with temporary narrowing still in effect. If the old point ++value were outside the limits of the temporary narrowing, this would ++fail to restore it accurately. ++ ++Here is a simple example of correct use of @code{save-restriction}: ++ ++@example ++@group ++---------- Buffer: foo ---------- ++This is the contents of foo ++This is the contents of foo ++This is the contents of foo@point{} ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(save-excursion ++ (save-restriction ++ (goto-char 1) ++ (forward-line 2) ++ (narrow-to-region 1 (point)) ++ (goto-char (point-min)) ++ (replace-string "foo" "bar"))) ++ ++---------- Buffer: foo ---------- ++This is the contents of bar ++This is the contents of bar ++This is the contents of foo@point{} ++---------- Buffer: foo ---------- ++@end group ++@end example ++@end defspec ++ ++@ignore ++ arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87 ++@end ignore +diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi +new file mode 100644 +index 0000000..b80b49f +--- /dev/null ++++ b/doc/lispref/processes.texi +@@ -0,0 +1,3003 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/processes ++@node Processes, Display, Abbrevs, Top ++@chapter Processes ++@cindex child process ++@cindex parent process ++@cindex subprocess ++@cindex process ++ ++ In the terminology of operating systems, a @dfn{process} is a space in ++which a program can execute. Emacs runs in a process. Emacs Lisp ++programs can invoke other programs in processes of their own. These are ++called @dfn{subprocesses} or @dfn{child processes} of the Emacs process, ++which is their @dfn{parent process}. ++ ++ A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous}, ++depending on how it is created. When you create a synchronous ++subprocess, the Lisp program waits for the subprocess to terminate ++before continuing execution. When you create an asynchronous ++subprocess, it can run in parallel with the Lisp program. This kind of ++subprocess is represented within Emacs by a Lisp object which is also ++called a ``process.'' Lisp programs can use this object to communicate ++with the subprocess or to control it. For example, you can send ++signals, obtain status information, receive output from the process, or ++send input to it. ++ ++@defun processp object ++This function returns @code{t} if @var{object} represents an Emacs ++subprocess, @code{nil} otherwise. ++@end defun ++ ++ In addition to subprocesses of the current Emacs session, you can ++also access other processes running on your machine. @xref{System ++Processes}. ++ ++@menu ++* Subprocess Creation:: Functions that start subprocesses. ++* Shell Arguments:: Quoting an argument to pass it to a shell. ++* Synchronous Processes:: Details of using synchronous subprocesses. ++* Asynchronous Processes:: Starting up an asynchronous subprocess. ++* Deleting Processes:: Eliminating an asynchronous subprocess. ++* Process Information:: Accessing run-status and other attributes. ++* Input to Processes:: Sending input to an asynchronous subprocess. ++* Signals to Processes:: Stopping, continuing or interrupting ++ an asynchronous subprocess. ++* Output from Processes:: Collecting output from an asynchronous subprocess. ++* Sentinels:: Sentinels run when process run-status changes. ++* Query Before Exit:: Whether to query if exiting will kill a process. ++* System Processes:: Accessing other processes running on your system. ++* Transaction Queues:: Transaction-based communication with subprocesses. ++* Network:: Opening network connections. ++* Network Servers:: Network servers let Emacs accept net connections. ++* Datagrams:: UDP network connections. ++* Low-Level Network:: Lower-level but more general function ++ to create connections and servers. ++* Misc Network:: Additional relevant functions for network connections. ++* Serial Ports:: Communicating with serial ports. ++* Byte Packing:: Using bindat to pack and unpack binary data. ++@end menu ++ ++@node Subprocess Creation ++@section Functions that Create Subprocesses ++ ++ There are three primitives that create a new subprocess in which to run ++a program. One of them, @code{start-process}, creates an asynchronous ++process and returns a process object (@pxref{Asynchronous Processes}). ++The other two, @code{call-process} and @code{call-process-region}, ++create a synchronous process and do not return a process object ++(@pxref{Synchronous Processes}). ++ ++ Synchronous and asynchronous processes are explained in the following ++sections. Since the three functions are all called in a similar ++fashion, their common arguments are described here. ++ ++@cindex execute program ++@cindex @code{PATH} environment variable ++@cindex @code{HOME} environment variable ++ In all cases, the function's @var{program} argument specifies the ++program to be run. An error is signaled if the file is not found or ++cannot be executed. If the file name is relative, the variable ++@code{exec-path} contains a list of directories to search. Emacs ++initializes @code{exec-path} when it starts up, based on the value of ++the environment variable @code{PATH}. The standard file name ++constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as ++usual in @code{exec-path}, but environment variable substitutions ++(@samp{$HOME}, etc.) are not recognized; use ++@code{substitute-in-file-name} to perform them (@pxref{File Name ++Expansion}). @code{nil} in this list refers to ++@code{default-directory}. ++ ++ Executing a program can also try adding suffixes to the specified ++name: ++ ++@defvar exec-suffixes ++This variable is a list of suffixes (strings) to try adding to the ++specified program file name. The list should include @code{""} if you ++want the name to be tried exactly as specified. The default value is ++system-dependent. ++@end defvar ++ ++ @strong{Please note:} The argument @var{program} contains only the ++name of the program; it may not contain any command-line arguments. You ++must use @var{args} to provide those. ++ ++ Each of the subprocess-creating functions has a @var{buffer-or-name} ++argument which specifies where the standard output from the program will ++go. It should be a buffer or a buffer name; if it is a buffer name, ++that will create the buffer if it does not already exist. It can also ++be @code{nil}, which says to discard the output unless a filter function ++handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) ++Normally, you should avoid having multiple processes send output to the ++same buffer because their output would be intermixed randomly. ++ ++@cindex program arguments ++ All three of the subprocess-creating functions have a @code{&rest} ++argument, @var{args}. The @var{args} must all be strings, and they are ++supplied to @var{program} as separate command line arguments. Wildcard ++characters and other shell constructs have no special meanings in these ++strings, since the strings are passed directly to the specified program. ++ ++ The subprocess gets its current directory from the value of ++@code{default-directory} (@pxref{File Name Expansion}). ++ ++@cindex environment variables, subprocesses ++ The subprocess inherits its environment from Emacs, but you can ++specify overrides for it with @code{process-environment}. @xref{System ++Environment}. ++ ++@defvar exec-directory ++@pindex movemail ++The value of this variable is a string, the name of a directory that ++contains programs that come with GNU Emacs, programs intended for Emacs ++to invoke. The program @code{movemail} is an example of such a program; ++Rmail uses it to fetch new mail from an inbox. ++@end defvar ++ ++@defopt exec-path ++The value of this variable is a list of directories to search for ++programs to run in subprocesses. Each element is either the name of a ++directory (i.e., a string), or @code{nil}, which stands for the default ++directory (which is the value of @code{default-directory}). ++@cindex program directories ++ ++The value of @code{exec-path} is used by @code{call-process} and ++@code{start-process} when the @var{program} argument is not an absolute ++file name. ++@end defopt ++ ++@node Shell Arguments ++@section Shell Arguments ++@cindex arguments for shell commands ++@cindex shell command arguments ++ ++ Lisp programs sometimes need to run a shell and give it a command ++that contains file names that were specified by the user. These ++programs ought to be able to support any valid file name. But the shell ++gives special treatment to certain characters, and if these characters ++occur in the file name, they will confuse the shell. To handle these ++characters, use the function @code{shell-quote-argument}: ++ ++@defun shell-quote-argument argument ++This function returns a string which represents, in shell syntax, ++an argument whose actual contents are @var{argument}. It should ++work reliably to concatenate the return value into a shell command ++and then pass it to a shell for execution. ++ ++Precisely what this function does depends on your operating system. The ++function is designed to work with the syntax of your system's standard ++shell; if you use an unusual shell, you will need to redefine this ++function. ++ ++@example ++;; @r{This example shows the behavior on GNU and Unix systems.} ++(shell-quote-argument "foo > bar") ++ @result{} "foo\\ \\>\\ bar" ++ ++;; @r{This example shows the behavior on MS-DOS and MS-Windows.} ++(shell-quote-argument "foo > bar") ++ @result{} "\"foo > bar\"" ++@end example ++ ++Here's an example of using @code{shell-quote-argument} to construct ++a shell command: ++ ++@example ++(concat "diff -c " ++ (shell-quote-argument oldfile) ++ " " ++ (shell-quote-argument newfile)) ++@end example ++@end defun ++ ++@cindex quoting and unquoting shell command line ++ The following two functions are useful for creating shell commands ++from individual argument strings, and taking shell command lines apart ++into individual arguments. ++ ++@defun split-string-and-unquote string &optional separators ++This function splits @var{string} into substrings at matches for the ++regular expression @var{separators}, like @code{split-string} does ++(@pxref{Creating Strings}); in addition, it removes quoting from the ++substrings. It then makes a list of the substrings and returns it. ++ ++If @var{separators} is omitted or @code{nil}, it defaults to ++@code{"\\s-+"}, which is a regular expression that matches one or more ++characters with whitespace syntax (@pxref{Syntax Class Table}). ++ ++This function performs two types of quoting: enclosing a whole string ++in double quotes @code{"@dots{}"}, and quoting individual characters ++with a backslash escape @samp{\}. The latter is also used in Lisp ++strings, so this function can handle those as well. ++@end defun ++ ++@defun combine-and-quote-strings list-of-strings &optional separator ++This function concatenates @var{list-of-strings} into a single string, ++quoting each string as necessary. It also sticks the @var{separator} ++string between each pair of strings; if @var{separator} is omitted or ++@code{nil}, it defaults to @code{" "}. The return value is the ++resulting string. ++ ++The strings in @var{list-of-strings} that need quoting are those that ++include @var{separator} as their substring. Quoting a string encloses ++it in double quotes @code{"@dots{}"}. In the simplest case, if you ++are consing a shell command from the individual command-line ++arguments, every argument that includes embedded blanks will be ++quoted. ++@end defun ++ ++@node Synchronous Processes ++@section Creating a Synchronous Process ++@cindex synchronous subprocess ++ ++ After a @dfn{synchronous process} is created, Emacs waits for the ++process to terminate before continuing. Starting Dired on GNU or ++Unix@footnote{On other systems, Emacs uses a Lisp emulation of ++@code{ls}; see @ref{Contents of Directories}.} is an example of this: it ++runs @code{ls} in a synchronous process, then modifies the output ++slightly. Because the process is synchronous, the entire directory ++listing arrives in the buffer before Emacs tries to do anything with it. ++ ++ While Emacs waits for the synchronous subprocess to terminate, the ++user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill ++the subprocess with a @code{SIGINT} signal; but it waits until the ++subprocess actually terminates before quitting. If during that time the ++user types another @kbd{C-g}, that kills the subprocess instantly with ++@code{SIGKILL} and quits immediately (except on MS-DOS, where killing ++other processes doesn't work). @xref{Quitting}. ++ ++ The synchronous subprocess functions return an indication of how the ++process terminated. ++ ++ The output from a synchronous subprocess is generally decoded using a ++coding system, much like text read from a file. The input sent to a ++subprocess by @code{call-process-region} is encoded using a coding ++system, much like text written into a file. @xref{Coding Systems}. ++ ++@defun call-process program &optional infile destination display &rest args ++This function calls @var{program} in a separate process and waits for ++it to finish. ++ ++The standard input for the process comes from file @var{infile} if ++@var{infile} is not @code{nil}, and from the null device otherwise. ++The argument @var{destination} says where to put the process output. ++Here are the possibilities: ++ ++@table @asis ++@item a buffer ++Insert the output in that buffer, before point. This includes both the ++standard output stream and the standard error stream of the process. ++ ++@item a string ++Insert the output in a buffer with that name, before point. ++ ++@item @code{t} ++Insert the output in the current buffer, before point. ++ ++@item @code{nil} ++Discard the output. ++ ++@item 0 ++Discard the output, and return @code{nil} immediately without waiting ++for the subprocess to finish. ++ ++In this case, the process is not truly synchronous, since it can run in ++parallel with Emacs; but you can think of it as synchronous in that ++Emacs is essentially finished with the subprocess as soon as this ++function returns. ++ ++MS-DOS doesn't support asynchronous subprocesses, so this option doesn't ++work there. ++ ++@item @code{(@var{real-destination} @var{error-destination})} ++Keep the standard output stream separate from the standard error stream; ++deal with the ordinary output as specified by @var{real-destination}, ++and dispose of the error output according to @var{error-destination}. ++If @var{error-destination} is @code{nil}, that means to discard the ++error output, @code{t} means mix it with the ordinary output, and a ++string specifies a file name to redirect error output into. ++ ++You can't directly specify a buffer to put the error output in; that is ++too difficult to implement. But you can achieve this result by sending ++the error output to a temporary file and then inserting the file into a ++buffer. ++@end table ++ ++If @var{display} is non-@code{nil}, then @code{call-process} redisplays ++the buffer as output is inserted. (However, if the coding system chosen ++for decoding output is @code{undecided}, meaning deduce the encoding ++from the actual data, then redisplay sometimes cannot continue once ++non-@acronym{ASCII} characters are encountered. There are fundamental ++reasons why it is hard to fix this; see @ref{Output from Processes}.) ++ ++Otherwise the function @code{call-process} does no redisplay, and the ++results become visible on the screen only when Emacs redisplays that ++buffer in the normal course of events. ++ ++The remaining arguments, @var{args}, are strings that specify command ++line arguments for the program. ++ ++The value returned by @code{call-process} (unless you told it not to ++wait) indicates the reason for process termination. A number gives the ++exit status of the subprocess; 0 means success, and any other value ++means failure. If the process terminated with a signal, ++@code{call-process} returns a string describing the signal. ++ ++In the examples below, the buffer @samp{foo} is current. ++ ++@smallexample ++@group ++(call-process "pwd" nil t) ++ @result{} 0 ++ ++---------- Buffer: foo ---------- ++/usr/user/lewis/manual ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(call-process "grep" nil "bar" nil "lewis" "/etc/passwd") ++ @result{} 0 ++ ++---------- Buffer: bar ---------- ++lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh ++ ++---------- Buffer: bar ---------- ++@end group ++@end smallexample ++ ++Here is a good example of the use of @code{call-process}, which used to ++be found in the definition of @code{insert-directory}: ++ ++@smallexample ++@group ++(call-process insert-directory-program nil t nil @var{switches} ++ (if full-directory-p ++ (concat (file-name-as-directory file) ".") ++ file)) ++@end group ++@end smallexample ++@end defun ++ ++@defun process-file program &optional infile buffer display &rest args ++This function processes files synchronously in a separate process. It ++is similar to @code{call-process} but may invoke a file handler based ++on the value of the variable @code{default-directory}. The current ++working directory of the subprocess is @code{default-directory}. ++ ++The arguments are handled in almost the same way as for ++@code{call-process}, with the following differences: ++ ++Some file handlers may not support all combinations and forms of the ++arguments @var{infile}, @var{buffer}, and @var{display}. For example, ++some file handlers might behave as if @var{display} were @code{nil}, ++regardless of the value actually passed. As another example, some ++file handlers might not support separating standard output and error ++output by way of the @var{buffer} argument. ++ ++If a file handler is invoked, it determines the program to run based ++on the first argument @var{program}. For instance, consider that a ++handler for remote files is invoked. Then the path that is used for ++searching the program might be different than @code{exec-path}. ++ ++The second argument @var{infile} may invoke a file handler. The file ++handler could be different from the handler chosen for the ++@code{process-file} function itself. (For example, ++@code{default-directory} could be on a remote host, whereas ++@var{infile} is on another remote host. Or @code{default-directory} ++could be non-special, whereas @var{infile} is on a remote host.) ++ ++If @var{buffer} is a list of the form @code{(@var{real-destination} ++@var{error-destination})}, and @var{error-destination} names a file, ++then the same remarks as for @var{infile} apply. ++ ++The remaining arguments (@var{args}) will be passed to the process ++verbatim. Emacs is not involved in processing file names that are ++present in @var{args}. To avoid confusion, it may be best to avoid ++absolute file names in @var{args}, but rather to specify all file ++names as relative to @code{default-directory}. The function ++@code{file-relative-name} is useful for constructing such relative ++file names. ++@end defun ++ ++@defun call-process-region start end program &optional delete destination display &rest args ++This function sends the text from @var{start} to @var{end} as ++standard input to a process running @var{program}. It deletes the text ++sent if @var{delete} is non-@code{nil}; this is useful when ++@var{destination} is @code{t}, to insert the output in the current ++buffer in place of the input. ++ ++The arguments @var{destination} and @var{display} control what to do ++with the output from the subprocess, and whether to update the display ++as it comes in. For details, see the description of ++@code{call-process}, above. If @var{destination} is the integer 0, ++@code{call-process-region} discards the output and returns @code{nil} ++immediately, without waiting for the subprocess to finish (this only ++works if asynchronous subprocesses are supported). ++ ++The remaining arguments, @var{args}, are strings that specify command ++line arguments for the program. ++ ++The return value of @code{call-process-region} is just like that of ++@code{call-process}: @code{nil} if you told it to return without ++waiting; otherwise, a number or string which indicates how the ++subprocess terminated. ++ ++In the following example, we use @code{call-process-region} to run the ++@code{cat} utility, with standard input being the first five characters ++in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its ++standard input into its standard output. Since the argument ++@var{destination} is @code{t}, this output is inserted in the current ++buffer. ++ ++@smallexample ++@group ++---------- Buffer: foo ---------- ++input@point{} ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(call-process-region 1 6 "cat" nil t) ++ @result{} 0 ++ ++---------- Buffer: foo ---------- ++inputinput@point{} ++---------- Buffer: foo ---------- ++@end group ++@end smallexample ++ ++ The @code{shell-command-on-region} command uses ++@code{call-process-region} like this: ++ ++@smallexample ++@group ++(call-process-region ++ start end ++ shell-file-name ; @r{Name of program.} ++ nil ; @r{Do not delete region.} ++ buffer ; @r{Send output to @code{buffer}.} ++ nil ; @r{No redisplay during output.} ++ "-c" command) ; @r{Arguments for the shell.} ++@end group ++@end smallexample ++@end defun ++ ++@defun call-process-shell-command command &optional infile destination display &rest args ++This function executes the shell command @var{command} synchronously ++in a separate process. The final arguments @var{args} are additional ++arguments to add at the end of @var{command}. The other arguments ++are handled as in @code{call-process}. ++@end defun ++ ++@defun process-file-shell-command command &optional infile destination display &rest args ++This function is like @code{call-process-shell-command}, but uses ++@code{process-file} internally. Depending on @code{default-directory}, ++@var{command} can be executed also on remote hosts. ++@end defun ++ ++@defun shell-command-to-string command ++This function executes @var{command} (a string) as a shell command, ++then returns the command's output as a string. ++@end defun ++ ++@defun process-lines program &rest args ++This function runs @var{program} in a separate process, waits for it ++to finish, and returns its output as a list of strings. Each string ++in the list holds a single line of text output by the program; the ++end-of-line characters are stripped from each line. The arguments ++beyond @var{program}, @var{args}, are strings that specify ++command-line arguments with which to run the program. ++ ++If @var{program} exits with a non-zero exit status, this function ++signals an error. ++ ++This function works by calling @code{call-process}, so program output ++is decoded in the same way as for @code{call-process}. ++@end defun ++ ++@node Asynchronous Processes ++@section Creating an Asynchronous Process ++@cindex asynchronous subprocess ++ ++ After an @dfn{asynchronous process} is created, Emacs and the subprocess ++both continue running immediately. The process thereafter runs ++in parallel with Emacs, and the two can communicate with each other ++using the functions described in the following sections. However, ++communication is only partially asynchronous: Emacs sends data to the ++process only when certain functions are called, and Emacs accepts data ++from the process only when Emacs is waiting for input or for a time ++delay. ++ ++ Here we describe how to create an asynchronous process. ++ ++@defun start-process name buffer-or-name program &rest args ++This function creates a new asynchronous subprocess and starts the ++program @var{program} running in it. It returns a process object that ++stands for the new subprocess in Lisp. The argument @var{name} ++specifies the name for the process object; if a process with this name ++already exists, then @var{name} is modified (by appending @samp{<1>}, ++etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to ++associate with the process. ++ ++The remaining arguments, @var{args}, are strings that specify command ++line arguments for the program. ++ ++In the example below, the first process is started and runs (rather, ++sleeps) for 100 seconds. Meanwhile, the second process is started, and ++given the name @samp{my-process<1>} for the sake of uniqueness. It ++inserts the directory listing at the end of the buffer @samp{foo}, ++before the first process finishes. Then it finishes, and a message to ++that effect is inserted in the buffer. Much later, the first process ++finishes, and another message is inserted in the buffer for it. ++ ++@smallexample ++@group ++(start-process "my-process" "foo" "sleep" "100") ++ @result{} # ++@end group ++ ++@group ++(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") ++ @result{} #> ++ ++---------- Buffer: foo ---------- ++total 2 ++lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs ++-rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon ++ ++Process my-process<1> finished ++ ++Process my-process finished ++---------- Buffer: foo ---------- ++@end group ++@end smallexample ++@end defun ++ ++@defun start-file-process name buffer-or-name program &rest args ++Like @code{start-process}, this function starts a new asynchronous ++subprocess running @var{program} in it, and returns its process ++object---when @code{default-directory} is not a magic file name. ++ ++If @code{default-directory} is magic, the function invokes its file ++handler instead. This handler ought to run @var{program}, perhaps on ++the local host, perhaps on a remote host that corresponds to ++@code{default-directory}. In the latter case, the local part of ++@code{default-directory} becomes the working directory of the process. ++ ++This function does not try to invoke file name handlers for ++@var{program} or for the @var{program-args}. ++ ++Depending on the implementation of the file handler, it might not be ++possible to apply @code{process-filter} or @code{process-sentinel} to ++the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}). ++ ++Some file handlers may not support @code{start-file-process} (for ++example @code{ange-ftp-hook-function}). In such cases, the function ++does nothing and returns @code{nil}. ++@end defun ++ ++@defun start-process-shell-command name buffer-or-name command &rest command-args ++This function is like @code{start-process} except that it uses a shell ++to execute the specified command. The argument @var{command} is a shell ++command name, and @var{command-args} are the arguments for the shell ++command. The variable @code{shell-file-name} specifies which shell to ++use. ++ ++The point of running a program through the shell, rather than directly ++with @code{start-process}, is so that you can employ shell features such ++as wildcards in the arguments. It follows that if you include an ++arbitrary user-specified arguments in the command, you should quote it ++with @code{shell-quote-argument} first, so that any special shell ++characters do @emph{not} have their special shell meanings. @xref{Shell ++Arguments}. ++@end defun ++ ++@defun start-file-process-shell-command name buffer-or-name command &rest command-args ++This function is like @code{start-process-shell-command}, but uses ++@code{start-file-process} internally. By this, @var{command} can be ++executed also on remote hosts, depending on @code{default-directory}. ++@end defun ++ ++@defvar process-connection-type ++@cindex pipes ++@cindex @acronym{PTY}s ++This variable controls the type of device used to communicate with ++asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are ++used, when available. Otherwise, pipes are used. ++ ++@acronym{PTY}s are usually preferable for processes visible to the user, as ++in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z}, ++etc.) to work between the process and its children, whereas pipes do ++not. For subprocesses used for internal purposes by programs, it is ++often better to use a pipe, because they are more efficient. In ++addition, the total number of @acronym{PTY}s is limited on many systems and ++it is good not to waste them. ++ ++The value of @code{process-connection-type} takes effect when ++@code{start-process} is called. So you can specify how to communicate ++with one subprocess by binding the variable around the call to ++@code{start-process}. ++ ++@smallexample ++@group ++(let ((process-connection-type nil)) ; @r{Use a pipe.} ++ (start-process @dots{})) ++@end group ++@end smallexample ++ ++To determine whether a given subprocess actually got a pipe or a ++@acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process ++Information}). ++@end defvar ++ ++@node Deleting Processes ++@section Deleting Processes ++@cindex deleting processes ++ ++ @dfn{Deleting a process} disconnects Emacs immediately from the ++subprocess. Processes are deleted automatically after they terminate, ++but not necessarily right away. You can delete a process explicitly ++at any time. If you delete a terminated process explicitly before it ++is deleted automatically, no harm results. Deleting a running ++process sends a signal to terminate it (and its child processes if ++any), and calls the process sentinel if it has one. @xref{Sentinels}. ++ ++ When a process is deleted, the process object itself continues to ++exist as long as other Lisp objects point to it. All the Lisp ++primitives that work on process objects accept deleted processes, but ++those that do I/O or send signals will report an error. The process ++mark continues to point to the same place as before, usually into a ++buffer where output from the process was being inserted. ++ ++@defopt delete-exited-processes ++This variable controls automatic deletion of processes that have ++terminated (due to calling @code{exit} or to a signal). If it is ++@code{nil}, then they continue to exist until the user runs ++@code{list-processes}. Otherwise, they are deleted immediately after ++they exit. ++@end defopt ++ ++@defun delete-process process ++This function deletes a process, killing it with a @code{SIGKILL} ++signal. The argument may be a process, the name of a process, a ++buffer, or the name of a buffer. (A buffer or buffer-name stands for ++the process that @code{get-buffer-process} returns.) Calling ++@code{delete-process} on a running process terminates it, updates the ++process status, and runs the sentinel (if any) immediately. If the ++process has already terminated, calling @code{delete-process} has no ++effect on its status, or on the running of its sentinel (which will ++happen sooner or later). ++ ++@smallexample ++@group ++(delete-process "*shell*") ++ @result{} nil ++@end group ++@end smallexample ++@end defun ++ ++@node Process Information ++@section Process Information ++ ++ Several functions return information about processes. ++@code{list-processes} is provided for interactive use. ++ ++@deffn Command list-processes &optional query-only ++This command displays a listing of all living processes. In addition, ++it finally deletes any process whose status was @samp{Exited} or ++@samp{Signaled}. It returns @code{nil}. ++ ++If @var{query-only} is non-@code{nil} then it lists only processes ++whose query flag is non-@code{nil}. @xref{Query Before Exit}. ++@end deffn ++ ++@defun process-list ++This function returns a list of all processes that have not been deleted. ++ ++@smallexample ++@group ++(process-list) ++ @result{} (# #) ++@end group ++@end smallexample ++@end defun ++ ++@defun get-process name ++This function returns the process named @var{name}, or @code{nil} if ++there is none. An error is signaled if @var{name} is not a string. ++ ++@smallexample ++@group ++(get-process "shell") ++ @result{} # ++@end group ++@end smallexample ++@end defun ++ ++@defun process-command process ++This function returns the command that was executed to start ++@var{process}. This is a list of strings, the first string being the ++program executed and the rest of the strings being the arguments that ++were given to the program. ++ ++@smallexample ++@group ++(process-command (get-process "shell")) ++ @result{} ("/bin/csh" "-i") ++@end group ++@end smallexample ++@end defun ++ ++@defun process-contact process &optional key ++ ++This function returns information about how a network or serial ++process was set up. For a network process, when @var{key} is ++@code{nil}, it returns @code{(@var{hostname} @var{service})} which ++specifies what you connected to. For a serial process, when @var{key} ++is @code{nil}, it returns @code{(@var{port} @var{speed})}. For an ++ordinary child process, this function always returns @code{t}. ++ ++If @var{key} is @code{t}, the value is the complete status information ++for the connection, server, or serial port; that is, the list of ++keywords and values specified in @code{make-network-process} or ++@code{make-serial-process}, except that some of the values represent ++the current status instead of what you specified. ++ ++For a network process: ++ ++@table @code ++@item :buffer ++The associated value is the process buffer. ++@item :filter ++The associated value is the process filter function. ++@item :sentinel ++The associated value is the process sentinel function. ++@item :remote ++In a connection, the address in internal format of the remote peer. ++@item :local ++The local address, in internal format. ++@item :service ++In a server, if you specified @code{t} for @var{service}, ++this value is the actual port number. ++@end table ++ ++@code{:local} and @code{:remote} are included even if they were not ++specified explicitly in @code{make-network-process}. ++ ++For a serial process, see @code{make-serial-process} and ++@code{serial-process-configure} for a list of keys. ++ ++If @var{key} is a keyword, the function returns the value corresponding ++to that keyword. ++@end defun ++ ++@defun process-id process ++This function returns the @acronym{PID} of @var{process}. This is an ++integer that distinguishes the process @var{process} from all other ++processes running on the same computer at the current time. The ++@acronym{PID} of a process is chosen by the operating system kernel when the ++process is started and remains constant as long as the process exists. ++@end defun ++ ++@defun process-name process ++This function returns the name of @var{process}. ++@end defun ++ ++@defun process-status process-name ++This function returns the status of @var{process-name} as a symbol. ++The argument @var{process-name} must be a process, a buffer, or a ++process name (a string). ++ ++The possible values for an actual subprocess are: ++ ++@table @code ++@item run ++for a process that is running. ++@item stop ++for a process that is stopped but continuable. ++@item exit ++for a process that has exited. ++@item signal ++for a process that has received a fatal signal. ++@item open ++for a network connection that is open. ++@item closed ++for a network connection that is closed. Once a connection ++is closed, you cannot reopen it, though you might be able to open ++a new connection to the same place. ++@item connect ++for a non-blocking connection that is waiting to complete. ++@item failed ++for a non-blocking connection that has failed to complete. ++@item listen ++for a network server that is listening. ++@item nil ++if @var{process-name} is not the name of an existing process. ++@end table ++ ++@smallexample ++@group ++(process-status (get-buffer "*shell*")) ++ @result{} run ++@end group ++@group ++x ++ @result{} #> ++(process-status x) ++ @result{} exit ++@end group ++@end smallexample ++ ++For a network connection, @code{process-status} returns one of the symbols ++@code{open} or @code{closed}. The latter means that the other side ++closed the connection, or Emacs did @code{delete-process}. ++@end defun ++ ++@defun process-type process ++This function returns the symbol @code{network} for a network ++connection or server, @code{serial} for a serial port connection, or ++@code{real} for a real subprocess. ++@end defun ++ ++@defun process-exit-status process ++This function returns the exit status of @var{process} or the signal ++number that killed it. (Use the result of @code{process-status} to ++determine which of those it is.) If @var{process} has not yet ++terminated, the value is 0. ++@end defun ++ ++@defun process-tty-name process ++This function returns the terminal name that @var{process} is using for ++its communication with Emacs---or @code{nil} if it is using pipes ++instead of a terminal (see @code{process-connection-type} in ++@ref{Asynchronous Processes}). ++@end defun ++ ++@defun process-coding-system process ++@anchor{Coding systems for a subprocess} ++This function returns a cons cell describing the coding systems in use ++for decoding output from @var{process} and for encoding input to ++@var{process} (@pxref{Coding Systems}). The value has this form: ++ ++@example ++(@var{coding-system-for-decoding} . @var{coding-system-for-encoding}) ++@end example ++@end defun ++ ++@defun set-process-coding-system process &optional decoding-system encoding-system ++This function specifies the coding systems to use for subsequent output ++from and input to @var{process}. It will use @var{decoding-system} to ++decode subprocess output, and @var{encoding-system} to encode subprocess ++input. ++@end defun ++ ++ Every process also has a property list that you can use to store ++miscellaneous values associated with the process. ++ ++@defun process-get process propname ++This function returns the value of the @var{propname} property ++of @var{process}. ++@end defun ++ ++@defun process-put process propname value ++This function sets the value of the @var{propname} property ++of @var{process} to @var{value}. ++@end defun ++ ++@defun process-plist process ++This function returns the process plist of @var{process}. ++@end defun ++ ++@defun set-process-plist process plist ++This function sets the process plist of @var{process} to @var{plist}. ++@end defun ++ ++@node Input to Processes ++@section Sending Input to Processes ++@cindex process input ++ ++ Asynchronous subprocesses receive input when it is sent to them by ++Emacs, which is done with the functions in this section. You must ++specify the process to send input to, and the input data to send. The ++data appears on the ``standard input'' of the subprocess. ++ ++ Some operating systems have limited space for buffered input in a ++@acronym{PTY}. On these systems, Emacs sends an @acronym{EOF} ++periodically amidst the other characters, to force them through. For ++most programs, these @acronym{EOF}s do no harm. ++ ++ Subprocess input is normally encoded using a coding system before the ++subprocess receives it, much like text written into a file. You can use ++@code{set-process-coding-system} to specify which coding system to use ++(@pxref{Process Information}). Otherwise, the coding system comes from ++@code{coding-system-for-write}, if that is non-@code{nil}; or else from ++the defaulting mechanism (@pxref{Default Coding Systems}). ++ ++ Sometimes the system is unable to accept input for that process, ++because the input buffer is full. When this happens, the send functions ++wait a short while, accepting output from subprocesses, and then try ++again. This gives the subprocess a chance to read more of its pending ++input and make space in the buffer. It also allows filters, sentinels ++and timers to run---so take account of that in writing your code. ++ ++ In these functions, the @var{process} argument can be a process or ++the name of a process, or a buffer or buffer name (which stands ++for a process via @code{get-buffer-process}). @code{nil} means ++the current buffer's process. ++ ++@defun process-send-string process string ++This function sends @var{process} the contents of @var{string} as ++standard input. If it is @code{nil}, the current buffer's process is used. ++ ++ The function returns @code{nil}. ++ ++@smallexample ++@group ++(process-send-string "shell<1>" "ls\n") ++ @result{} nil ++@end group ++ ++ ++@group ++---------- Buffer: *shell* ---------- ++... ++introduction.texi syntax-tables.texi~ ++introduction.texi~ text.texi ++introduction.txt text.texi~ ++... ++---------- Buffer: *shell* ---------- ++@end group ++@end smallexample ++@end defun ++ ++@defun process-send-region process start end ++This function sends the text in the region defined by @var{start} and ++@var{end} as standard input to @var{process}. ++ ++An error is signaled unless both @var{start} and @var{end} are ++integers or markers that indicate positions in the current buffer. (It ++is unimportant which number is larger.) ++@end defun ++ ++@defun process-send-eof &optional process ++This function makes @var{process} see an end-of-file in its ++input. The @acronym{EOF} comes after any text already sent to it. ++ ++The function returns @var{process}. ++ ++@smallexample ++@group ++(process-send-eof "shell") ++ @result{} "shell" ++@end group ++@end smallexample ++@end defun ++ ++@defun process-running-child-p &optional process ++This function will tell you whether a @var{process} has given control of ++its terminal to its own child process. The value is @code{t} if this is ++true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain ++that this is not so. ++@end defun ++ ++@node Signals to Processes ++@section Sending Signals to Processes ++@cindex process signals ++@cindex sending signals ++@cindex signals ++ ++ @dfn{Sending a signal} to a subprocess is a way of interrupting its ++activities. There are several different signals, each with its own ++meaning. The set of signals and their names is defined by the operating ++system. For example, the signal @code{SIGINT} means that the user has ++typed @kbd{C-c}, or that some analogous thing has happened. ++ ++ Each signal has a standard effect on the subprocess. Most signals ++kill the subprocess, but some stop or resume execution instead. Most ++signals can optionally be handled by programs; if the program handles ++the signal, then we can say nothing in general about its effects. ++ ++ You can send signals explicitly by calling the functions in this ++section. Emacs also sends signals automatically at certain times: ++killing a buffer sends a @code{SIGHUP} signal to all its associated ++processes; killing Emacs sends a @code{SIGHUP} signal to all remaining ++processes. (@code{SIGHUP} is a signal that usually indicates that the ++user hung up the phone.) ++ ++ Each of the signal-sending functions takes two optional arguments: ++@var{process} and @var{current-group}. ++ ++ The argument @var{process} must be either a process, a process ++name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name ++stands for a process through @code{get-buffer-process}. @code{nil} ++stands for the process associated with the current buffer. An error ++is signaled if @var{process} does not identify a process. ++ ++ The argument @var{current-group} is a flag that makes a difference ++when you are running a job-control shell as an Emacs subprocess. If it ++is non-@code{nil}, then the signal is sent to the current process-group ++of the terminal that Emacs uses to communicate with the subprocess. If ++the process is a job-control shell, this means the shell's current ++subjob. If it is @code{nil}, the signal is sent to the process group of ++the immediate subprocess of Emacs. If the subprocess is a job-control ++shell, this is the shell itself. ++ ++ The flag @var{current-group} has no effect when a pipe is used to ++communicate with the subprocess, because the operating system does not ++support the distinction in the case of pipes. For the same reason, ++job-control shells won't work when a pipe is used. See ++@code{process-connection-type} in @ref{Asynchronous Processes}. ++ ++@defun interrupt-process &optional process current-group ++This function interrupts the process @var{process} by sending the ++signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt ++character'' (normally @kbd{C-c} on some systems, and @code{DEL} on ++others) sends this signal. When the argument @var{current-group} is ++non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' ++on the terminal by which Emacs talks to the subprocess. ++@end defun ++ ++@defun kill-process &optional process current-group ++This function kills the process @var{process} by sending the ++signal @code{SIGKILL}. This signal kills the subprocess immediately, ++and cannot be handled by the subprocess. ++@end defun ++ ++@defun quit-process &optional process current-group ++This function sends the signal @code{SIGQUIT} to the process ++@var{process}. This signal is the one sent by the ``quit ++character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside ++Emacs. ++@end defun ++ ++@defun stop-process &optional process current-group ++This function stops the process @var{process} by sending the ++signal @code{SIGTSTP}. Use @code{continue-process} to resume its ++execution. ++ ++Outside of Emacs, on systems with job control, the ``stop character'' ++(usually @kbd{C-z}) normally sends this signal. When ++@var{current-group} is non-@code{nil}, you can think of this function as ++``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the ++subprocess. ++@end defun ++ ++@defun continue-process &optional process current-group ++This function resumes execution of the process @var{process} by sending ++it the signal @code{SIGCONT}. This presumes that @var{process} was ++stopped previously. ++@end defun ++ ++@defun signal-process process signal ++This function sends a signal to process @var{process}. The argument ++@var{signal} specifies which signal to send; it should be an integer. ++ ++The @var{process} argument can be a system process @acronym{ID}; that ++allows you to send signals to processes that are not children of ++Emacs. @xref{System Processes}. ++@end defun ++ ++@node Output from Processes ++@section Receiving Output from Processes ++@cindex process output ++@cindex output from processes ++ ++ There are two ways to receive the output that a subprocess writes to ++its standard output stream. The output can be inserted in a buffer, ++which is called the associated buffer of the process, or a function ++called the @dfn{filter function} can be called to act on the output. If ++the process has no buffer and no filter function, its output is ++discarded. ++ ++ When a subprocess terminates, Emacs reads any pending output, ++then stops reading output from that subprocess. Therefore, if the ++subprocess has children that are still live and still producing ++output, Emacs won't receive that output. ++ ++ Output from a subprocess can arrive only while Emacs is waiting: when ++reading terminal input, in @code{sit-for} and @code{sleep-for} ++(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting ++Output}). This minimizes the problem of timing errors that usually ++plague parallel programming. For example, you can safely create a ++process and only then specify its buffer or filter function; no output ++can arrive before you finish, if the code in between does not call any ++primitive that waits. ++ ++@defvar process-adaptive-read-buffering ++On some systems, when Emacs reads the output from a subprocess, the ++output data is read in very small blocks, potentially resulting in ++very poor performance. This behavior can be remedied to some extent ++by setting the variable @var{process-adaptive-read-buffering} to a ++non-@code{nil} value (the default), as it will automatically delay reading ++from such processes, thus allowing them to produce more output before ++Emacs tries to read it. ++@end defvar ++ ++ It is impossible to separate the standard output and standard error ++streams of the subprocess, because Emacs normally spawns the subprocess ++inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If ++you want to keep the output to those streams separate, you should ++redirect one of them to a file---for example, by using an appropriate ++shell command. ++ ++@menu ++* Process Buffers:: If no filter, output is put in a buffer. ++* Filter Functions:: Filter functions accept output from the process. ++* Decoding Output:: Filters can get unibyte or multibyte strings. ++* Accepting Output:: How to wait until process output arrives. ++@end menu ++ ++@node Process Buffers ++@subsection Process Buffers ++ ++ A process can (and usually does) have an @dfn{associated buffer}, ++which is an ordinary Emacs buffer that is used for two purposes: storing ++the output from the process, and deciding when to kill the process. You ++can also use the buffer to identify a process to operate on, since in ++normal practice only one process is associated with any given buffer. ++Many applications of processes also use the buffer for editing input to ++be sent to the process, but this is not built into Emacs Lisp. ++ ++ Unless the process has a filter function (@pxref{Filter Functions}), ++its output is inserted in the associated buffer. The position to insert ++the output is determined by the @code{process-mark}, which is then ++updated to point to the end of the text just inserted. Usually, but not ++always, the @code{process-mark} is at the end of the buffer. ++ ++@defun process-buffer process ++This function returns the associated buffer of the process ++@var{process}. ++ ++@smallexample ++@group ++(process-buffer (get-process "shell")) ++ @result{} # ++@end group ++@end smallexample ++@end defun ++ ++@defun process-mark process ++This function returns the process marker for @var{process}, which is the ++marker that says where to insert output from the process. ++ ++If @var{process} does not have a buffer, @code{process-mark} returns a ++marker that points nowhere. ++ ++Insertion of process output in a buffer uses this marker to decide where ++to insert, and updates it to point after the inserted text. That is why ++successive batches of output are inserted consecutively. ++ ++Filter functions normally should use this marker in the same fashion ++as is done by direct insertion of output in the buffer. A good ++example of a filter function that uses @code{process-mark} is found at ++the end of the following section. ++ ++When the user is expected to enter input in the process buffer for ++transmission to the process, the process marker separates the new input ++from previous output. ++@end defun ++ ++@defun set-process-buffer process buffer ++This function sets the buffer associated with @var{process} to ++@var{buffer}. If @var{buffer} is @code{nil}, the process becomes ++associated with no buffer. ++@end defun ++ ++@defun get-buffer-process buffer-or-name ++This function returns a nondeleted process associated with the buffer ++specified by @var{buffer-or-name}. If there are several processes ++associated with it, this function chooses one (currently, the one most ++recently created, but don't count on that). Deletion of a process ++(see @code{delete-process}) makes it ineligible for this function to ++return. ++ ++It is usually a bad idea to have more than one process associated with ++the same buffer. ++ ++@smallexample ++@group ++(get-buffer-process "*shell*") ++ @result{} # ++@end group ++@end smallexample ++ ++Killing the process's buffer deletes the process, which kills the ++subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). ++@end defun ++ ++@node Filter Functions ++@subsection Process Filter Functions ++@cindex filter function ++@cindex process filter ++ ++ A process @dfn{filter function} is a function that receives the ++standard output from the associated process. If a process has a filter, ++then @emph{all} output from that process is passed to the filter. The ++process buffer is used directly for output from the process only when ++there is no filter. ++ ++ The filter function can only be called when Emacs is waiting for ++something, because process output arrives only at such times. Emacs ++waits when reading terminal input, in @code{sit-for} and ++@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output} ++(@pxref{Accepting Output}). ++ ++ A filter function must accept two arguments: the associated process ++and a string, which is output just received from it. The function is ++then free to do whatever it chooses with the output. ++ ++ Quitting is normally inhibited within a filter function---otherwise, ++the effect of typing @kbd{C-g} at command level or to quit a user ++command would be unpredictable. If you want to permit quitting inside ++a filter function, bind @code{inhibit-quit} to @code{nil}. In most ++cases, the right way to do this is with the macro ++@code{with-local-quit}. @xref{Quitting}. ++ ++ If an error happens during execution of a filter function, it is ++caught automatically, so that it doesn't stop the execution of whatever ++program was running when the filter function was started. However, if ++@code{debug-on-error} is non-@code{nil}, the error-catching is turned ++off. This makes it possible to use the Lisp debugger to debug the ++filter function. @xref{Debugger}. ++ ++ Many filter functions sometimes or always insert the text in the ++process's buffer, mimicking the actions of Emacs when there is no ++filter. Such filter functions need to use @code{set-buffer} in order to ++be sure to insert in that buffer. To avoid setting the current buffer ++semipermanently, these filter functions must save and restore the ++current buffer. They should also update the process marker, and in some ++cases update the value of point. Here is how to do these things: ++ ++@smallexample ++@group ++(defun ordinary-insertion-filter (proc string) ++ (with-current-buffer (process-buffer proc) ++ (let ((moving (= (point) (process-mark proc)))) ++@end group ++@group ++ (save-excursion ++ ;; @r{Insert the text, advancing the process marker.} ++ (goto-char (process-mark proc)) ++ (insert string) ++ (set-marker (process-mark proc) (point))) ++ (if moving (goto-char (process-mark proc)))))) ++@end group ++@end smallexample ++ ++@noindent ++The reason to use @code{with-current-buffer}, rather than using ++@code{save-excursion} to save and restore the current buffer, is so as ++to preserve the change in point made by the second call to ++@code{goto-char}. ++ ++ To make the filter force the process buffer to be visible whenever new ++text arrives, insert the following line just before the ++@code{with-current-buffer} construct: ++ ++@smallexample ++(display-buffer (process-buffer proc)) ++@end smallexample ++ ++ To force point to the end of the new output, no matter where it was ++previously, eliminate the variable @code{moving} and call ++@code{goto-char} unconditionally. ++ ++ In earlier Emacs versions, every filter function that did regular ++expression searching or matching had to explicitly save and restore the ++match data. Now Emacs does this automatically for filter functions; ++they never need to do it explicitly. @xref{Match Data}. ++ ++ A filter function that writes the output into the buffer of the ++process should check whether the buffer is still alive. If it tries to ++insert into a dead buffer, it will get an error. The expression ++@code{(buffer-name (process-buffer @var{process}))} returns @code{nil} ++if the buffer is dead. ++ ++ The output to the function may come in chunks of any size. A program ++that produces the same output twice in a row may send it as one batch of ++200 characters one time, and five batches of 40 characters the next. If ++the filter looks for certain text strings in the subprocess output, make ++sure to handle the case where one of these strings is split across two ++or more batches of output; one way to do this is to insert the ++received text into a temporary buffer, which can then be searched. ++ ++@defun set-process-filter process filter ++This function gives @var{process} the filter function @var{filter}. If ++@var{filter} is @code{nil}, it gives the process no filter. ++@end defun ++ ++@defun process-filter process ++This function returns the filter function of @var{process}, or @code{nil} ++if it has none. ++@end defun ++ ++ Here is an example of use of a filter function: ++ ++@smallexample ++@group ++(defun keep-output (process output) ++ (setq kept (cons output kept))) ++ @result{} keep-output ++@end group ++@group ++(setq kept nil) ++ @result{} nil ++@end group ++@group ++(set-process-filter (get-process "shell") 'keep-output) ++ @result{} keep-output ++@end group ++@group ++(process-send-string "shell" "ls ~/other\n") ++ @result{} nil ++kept ++ @result{} ("lewis@@slug[8] % " ++@end group ++@group ++"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ ++address.txt backup.psf kolstad.psf ++backup.bib~ david.mss resume-Dec-86.mss~ ++backup.err david.psf resume-Dec.psf ++backup.mss dland syllabus.mss ++" ++"#backups.mss# backup.mss~ kolstad.mss ++") ++@end group ++@end smallexample ++ ++@ignore @c The code in this example doesn't show the right way to do things. ++Here is another, more realistic example, which demonstrates how to use ++the process mark to do insertion in the same fashion as is done when ++there is no filter function: ++ ++@smallexample ++@group ++;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} ++;; @r{and make sure that buffer is shown in some window.} ++(defun my-process-filter (proc str) ++ (let ((cur (selected-window)) ++ (pop-up-windows t)) ++ (pop-to-buffer my-shell-buffer) ++@end group ++@group ++ (goto-char (point-max)) ++ (insert str) ++ (set-marker (process-mark proc) (point-max)) ++ (select-window cur))) ++@end group ++@end smallexample ++@end ignore ++ ++@node Decoding Output ++@subsection Decoding Process Output ++@cindex decode process output ++ ++ When Emacs writes process output directly into a multibyte buffer, ++it decodes the output according to the process output coding system. ++If the coding system is @code{raw-text} or @code{no-conversion}, Emacs ++converts the unibyte output to multibyte using ++@code{string-to-multibyte}, and inserts the resulting multibyte text. ++ ++ You can use @code{set-process-coding-system} to specify which coding ++system to use (@pxref{Process Information}). Otherwise, the coding ++system comes from @code{coding-system-for-read}, if that is ++non-@code{nil}; or else from the defaulting mechanism (@pxref{Default ++Coding Systems}). If the text output by a process contains null ++bytes, Emacs by default uses @code{no-conversion} for it; see ++@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to ++control this behavior. ++ ++ @strong{Warning:} Coding systems such as @code{undecided} which ++determine the coding system from the data do not work entirely ++reliably with asynchronous subprocess output. This is because Emacs ++has to process asynchronous subprocess output in batches, as it ++arrives. Emacs must try to detect the proper coding system from one ++batch at a time, and this does not always work. Therefore, if at all ++possible, specify a coding system that determines both the character ++code conversion and the end of line conversion---that is, one like ++@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}. ++ ++@c Let's keep the index entries that were there for ++@c set-process-filter-multibyte and process-filter-multibyte-p, ++@cindex filter multibyte flag, of process ++@cindex process filter multibyte flag ++ When Emacs calls a process filter function, it provides the process ++output as a multibyte string or as a unibyte string according to the ++process's filter coding system. Emacs ++decodes the output according to the process output coding system, ++which usually produces a multibyte string, except for coding systems ++such as @code{binary} and @code{raw-text} ++ ++@node Accepting Output ++@subsection Accepting Output from Processes ++@cindex accept input from processes ++ ++ Output from asynchronous subprocesses normally arrives only while ++Emacs is waiting for some sort of external event, such as elapsed time ++or terminal input. Occasionally it is useful in a Lisp program to ++explicitly permit output to arrive at a specific point, or even to wait ++until output arrives from a process. ++ ++@defun accept-process-output &optional process seconds millisec just-this-one ++This function allows Emacs to read pending output from processes. The ++output is inserted in the associated buffers or given to their filter ++functions. If @var{process} is non-@code{nil} then this function does ++not return until some output has been received from @var{process}. ++ ++@c Emacs 19 feature ++The arguments @var{seconds} and @var{millisec} let you specify timeout ++periods. The former specifies a period measured in seconds and the ++latter specifies one measured in milliseconds. The two time periods ++thus specified are added together, and @code{accept-process-output} ++returns after that much time, whether or not there has been any ++subprocess output. ++ ++The argument @var{millisec} is semi-obsolete nowadays because ++@var{seconds} can be a floating point number to specify waiting a ++fractional number of seconds. If @var{seconds} is 0, the function ++accepts whatever output is pending but does not wait. ++ ++@c Emacs 22.1 feature ++If @var{process} is a process, and the argument @var{just-this-one} is ++non-@code{nil}, only output from that process is handled, suspending output ++from other processes until some output has been received from that ++process or the timeout expires. If @var{just-this-one} is an integer, ++also inhibit running timers. This feature is generally not ++recommended, but may be necessary for specific applications, such as ++speech synthesis. ++ ++The function @code{accept-process-output} returns non-@code{nil} if it ++did get some output, or @code{nil} if the timeout expired before output ++arrived. ++@end defun ++ ++@node Sentinels ++@section Sentinels: Detecting Process Status Changes ++@cindex process sentinel ++@cindex sentinel (of process) ++ ++ A @dfn{process sentinel} is a function that is called whenever the ++associated process changes status for any reason, including signals ++(whether sent by Emacs or caused by the process's own actions) that ++terminate, stop, or continue the process. The process sentinel is ++also called if the process exits. The sentinel receives two ++arguments: the process for which the event occurred, and a string ++describing the type of event. ++ ++ The string describing the event looks like one of the following: ++ ++@itemize @bullet ++@item ++@code{"finished\n"}. ++ ++@item ++@code{"exited abnormally with code @var{exitcode}\n"}. ++ ++@item ++@code{"@var{name-of-signal}\n"}. ++ ++@item ++@code{"@var{name-of-signal} (core dumped)\n"}. ++@end itemize ++ ++ A sentinel runs only while Emacs is waiting (e.g., for terminal ++input, or for time to elapse, or for process output). This avoids the ++timing errors that could result from running them at random places in ++the middle of other Lisp programs. A program can wait, so that ++sentinels will run, by calling @code{sit-for} or @code{sleep-for} ++(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting ++Output}). Emacs also allows sentinels to run when the command loop is ++reading input. @code{delete-process} calls the sentinel when it ++terminates a running process. ++ ++ Emacs does not keep a queue of multiple reasons to call the sentinel ++of one process; it records just the current status and the fact that ++there has been a change. Therefore two changes in status, coming in ++quick succession, can call the sentinel just once. However, process ++termination will always run the sentinel exactly once. This is ++because the process status can't change again after termination. ++ ++ Emacs explicitly checks for output from the process before running ++the process sentinel. Once the sentinel runs due to process ++termination, no further output can arrive from the process. ++ ++ A sentinel that writes the output into the buffer of the process ++should check whether the buffer is still alive. If it tries to insert ++into a dead buffer, it will get an error. If the buffer is dead, ++@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. ++ ++ Quitting is normally inhibited within a sentinel---otherwise, the ++effect of typing @kbd{C-g} at command level or to quit a user command ++would be unpredictable. If you want to permit quitting inside a ++sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the ++right way to do this is with the macro @code{with-local-quit}. ++@xref{Quitting}. ++ ++ If an error happens during execution of a sentinel, it is caught ++automatically, so that it doesn't stop the execution of whatever ++programs was running when the sentinel was started. However, if ++@code{debug-on-error} is non-@code{nil}, the error-catching is turned ++off. This makes it possible to use the Lisp debugger to debug the ++sentinel. @xref{Debugger}. ++ ++ While a sentinel is running, the process sentinel is temporarily ++set to @code{nil} so that the sentinel won't run recursively. ++For this reason it is not possible for a sentinel to specify ++a new sentinel. ++ ++ In earlier Emacs versions, every sentinel that did regular expression ++searching or matching had to explicitly save and restore the match data. ++Now Emacs does this automatically for sentinels; they never need to do ++it explicitly. @xref{Match Data}. ++ ++@defun set-process-sentinel process sentinel ++This function associates @var{sentinel} with @var{process}. If ++@var{sentinel} is @code{nil}, then the process will have no sentinel. ++The default behavior when there is no sentinel is to insert a message in ++the process's buffer when the process status changes. ++ ++Changes in process sentinel take effect immediately---if the sentinel ++is slated to be run but has not been called yet, and you specify a new ++sentinel, the eventual call to the sentinel will use the new one. ++ ++@smallexample ++@group ++(defun msg-me (process event) ++ (princ ++ (format "Process: %s had the event `%s'" process event))) ++(set-process-sentinel (get-process "shell") 'msg-me) ++ @result{} msg-me ++@end group ++@group ++(kill-process (get-process "shell")) ++ @print{} Process: # had the event `killed' ++ @result{} # ++@end group ++@end smallexample ++@end defun ++ ++@defun process-sentinel process ++This function returns the sentinel of @var{process}, or @code{nil} if it ++has none. ++@end defun ++ ++@defun waiting-for-user-input-p ++While a sentinel or filter function is running, this function returns ++non-@code{nil} if Emacs was waiting for keyboard input from the user at ++the time the sentinel or filter function was called, @code{nil} if it ++was not. ++@end defun ++ ++@node Query Before Exit ++@section Querying Before Exit ++ ++ When Emacs exits, it terminates all its subprocesses by sending them ++the @code{SIGHUP} signal. Because subprocesses may be doing ++valuable work, Emacs normally asks the user to confirm that it is ok ++to terminate them. Each process has a query flag which, if ++non-@code{nil}, says that Emacs should ask for confirmation before ++exiting and thus killing that process. The default for the query flag ++is @code{t}, meaning @emph{do} query. ++ ++@defun process-query-on-exit-flag process ++This returns the query flag of @var{process}. ++@end defun ++ ++@defun set-process-query-on-exit-flag process flag ++This function sets the query flag of @var{process} to @var{flag}. It ++returns @var{flag}. ++ ++@smallexample ++@group ++;; @r{Don't query about the shell process} ++(set-process-query-on-exit-flag (get-process "shell") nil) ++ @result{} t ++@end group ++@end smallexample ++@end defun ++ ++@defun process-kill-without-query process &optional do-query ++This function clears the query flag of @var{process}, so that ++Emacs will not query the user on account of that process. ++ ++Actually, the function does more than that: it returns the old value of ++the process's query flag, and sets the query flag to @var{do-query}. ++Please don't use this function to do those things any more---please ++use the newer, cleaner functions @code{process-query-on-exit-flag} and ++@code{set-process-query-on-exit-flag} in all but the simplest cases. ++The only way you should use @code{process-kill-without-query} nowadays ++is like this: ++ ++@smallexample ++@group ++;; @r{Don't query about the shell process} ++(process-kill-without-query (get-process "shell")) ++@end group ++@end smallexample ++@end defun ++ ++@node System Processes ++@section Accessing Other Processes ++@cindex system processes ++ ++ In addition to accessing and manipulating processes that are ++subprocesses of the current Emacs session, Emacs Lisp programs can ++also access other processes running on the same machine. We call ++these @dfn{system processes}, to distinguish between them and Emacs ++subprocesses. ++ ++ Emacs provides several primitives for accessing system processes. ++Not all platforms support these primitives; on those which don't, ++these primitives return @code{nil}. ++ ++@defun list-system-processes ++This function returns a list of all the processes running on the ++system. Each process is identified by its @acronym{PID}, a numerical ++process ID that is assigned by the OS and distinguishes the process ++from all the other processes running on the same machine at the same ++time. ++@end defun ++ ++@defun process-attributes pid ++This function returns an alist of attributes for the process specified ++by its process ID @var{pid}. Each association in the alist is of the ++form @code{(@var{key} . @var{value})}, where @var{key} designates the ++attribute and @var{value} is the value of that attribute. The various ++attribute @var{key}'s that this function can return are listed below. ++Not all platforms support all of these attributes; if an attribute is ++not supported, its association will not appear in the returned alist. ++Values that are numbers can be either integer or floating-point, ++depending on the magnitude of the value. ++ ++@table @code ++@item euid ++The effective user ID of the user who invoked the process. The ++corresponding @var{value} is a number. If the process was invoked by ++the same user who runs the current Emacs session, the value is ++identical to what @code{user-uid} returns (@pxref{User ++Identification}). ++ ++@item user ++User name corresponding to the process's effective user ID, a string. ++ ++@item egid ++The group ID of the effective user ID, a number. ++ ++@item group ++Group name corresponding to the effective user's group ID, a string. ++ ++@item comm ++The name of the command that runs in the process. This is a string ++that usually specifies the name of the executable file of the process, ++without the leading directories. However, some special system ++processes can report strings that do not correspond to an executable ++file of a program. ++ ++@item state ++The state code of the process. This is a short string that encodes ++the scheduling state of the process. Here's a list of the most ++frequently seen codes: ++ ++@table @code ++@item "D" ++uninterruptible sleep (usually I/O) ++@item "R" ++running ++@item "S" ++interruptible sleep (waiting for some event) ++@item "T" ++stopped, e.g., by a job control signal ++@item "Z" ++``zombie'': a process that terminated, but was not reaped by its parent ++@end table ++ ++@noindent ++For the full list of the possible states, see the manual page of the ++@command{ps} command. ++ ++@item ppid ++The process ID of the parent process, a number. ++ ++@item pgrp ++The process group ID of the process, a number. ++ ++@item sess ++The session ID of the process. This is a number that is the process ++ID of the process's @dfn{session leader}. ++ ++@item ttname ++A string that is the name of the process's controlling terminal. On ++Unix and GNU systems, this is normally the file name of the ++corresponding terminal device, such as @file{/dev/pts65}. ++ ++@item tpgid ++The numerical process group ID of the foreground process group that ++uses the process's terminal. ++ ++@item minflt ++The number of minor page faults caused by the process since its ++beginning. (Minor page faults are those that don't involve reading ++from disk.) ++ ++@item majflt ++The number of major page faults caused by the process since its ++beginning. (Major page faults require a disk to be read, and are thus ++more expensive than minor page faults.) ++ ++@item cminflt ++@itemx cmajflt ++Like @code{minflt} and @code{majflt}, but include the number of page ++faults for all the child processes of the given process. ++ ++@item utime ++Time spent by the process in the user context, for running the ++application's code. The corresponding @var{value} is in the ++@w{@code{(@var{high} @var{low} @var{microsec})}} format, the same ++format used by functions @code{current-time} (@pxref{Time of Day, ++current-time}) and @code{file-attributes} (@pxref{File Attributes}). ++ ++@item stime ++Time spent by the process in the system (kernel) context, for ++processing system calls. The corresponding @var{value} is in the same ++format as for @code{utime}. ++ ++@item time ++The sum of @code{utime} and @code{stime}. The corresponding ++@var{value} is in the same format as for @code{utime}. ++ ++@item cutime ++@itemx cstime ++@itemx ctime ++Like @code{utime}, @code{stime}, and @code{time}, but include the ++times of all the child processes of the given process. ++ ++@item pri ++The numerical priority of the process. ++ ++@item nice ++The @dfn{nice value} of the process, a number. (Processes with smaller ++nice values get scheduled more favorably.) ++ ++@item thcount ++The number of threads in the process. ++ ++@item start ++The time the process was started, in the @w{@code{(@var{high} ++@var{low} @var{microsec})}} format used by @code{current-time} and ++@code{file-attributes}. ++ ++@item etime ++The time elapsed since the process started, in the @w{@code{(@var{high} ++@var{low} @var{microsec})}} format. ++ ++@item vsize ++The virtual memory size of the process, measured in kilobytes. ++ ++@item rss ++The size of the process's @dfn{resident set}, the number of kilobytes ++occupied by the process in the machine's physical memory. ++ ++@item pcpu ++The percentage of the CPU time used by the process since it started. ++The corresponding @var{value} is a floating-point number between 0 and ++100. ++ ++@item pmem ++The percentage of the total physical memory installed on the machine ++used by the process's resident set. The value is a floating-point ++number between 0 and 100. ++ ++@item args ++The command-line with which the process was invoked. This is a string ++in which individual command-line arguments are separated by blanks; ++whitespace characters that are embedded in the arguments are quoted as ++appropriate for the system's shell: escaped by backslash characters on ++GNU and Unix, and enclosed in double quote characters on Windows. ++Thus, this command-line string can be directly used in primitives such ++as @code{shell-command}. ++@end table ++ ++@end defun ++ ++ ++@node Transaction Queues ++@section Transaction Queues ++@cindex transaction queue ++ ++You can use a @dfn{transaction queue} to communicate with a subprocess ++using transactions. First use @code{tq-create} to create a transaction ++queue communicating with a specified process. Then you can call ++@code{tq-enqueue} to send a transaction. ++ ++@defun tq-create process ++This function creates and returns a transaction queue communicating with ++@var{process}. The argument @var{process} should be a subprocess ++capable of sending and receiving streams of bytes. It may be a child ++process, or it may be a TCP connection to a server, possibly on another ++machine. ++@end defun ++ ++@defun tq-enqueue queue question regexp closure fn &optional delay-question ++This function sends a transaction to queue @var{queue}. Specifying the ++queue has the effect of specifying the subprocess to talk to. ++ ++The argument @var{question} is the outgoing message that starts the ++transaction. The argument @var{fn} is the function to call when the ++corresponding answer comes back; it is called with two arguments: ++@var{closure}, and the answer received. ++ ++The argument @var{regexp} is a regular expression that should match ++text at the end of the entire answer, but nothing before; that's how ++@code{tq-enqueue} determines where the answer ends. ++ ++If the argument @var{delay-question} is non-@code{nil}, delay sending ++this question until the process has finished replying to any previous ++questions. This produces more reliable results with some processes. ++ ++The return value of @code{tq-enqueue} itself is not meaningful. ++@end defun ++ ++@defun tq-close queue ++Shut down transaction queue @var{queue}, waiting for all pending transactions ++to complete, and then terminate the connection or child process. ++@end defun ++ ++Transaction queues are implemented by means of a filter function. ++@xref{Filter Functions}. ++ ++@node Network ++@section Network Connections ++@cindex network connection ++@cindex TCP ++@cindex UDP ++ ++ Emacs Lisp programs can open stream (TCP) and datagram (UDP) network ++connections to other processes on the same machine or other machines. ++A network connection is handled by Lisp much like a subprocess, and is ++represented by a process object. However, the process you are ++communicating with is not a child of the Emacs process, so it has no ++process @acronym{ID}, and you can't kill it or send it signals. All you ++can do is send and receive data. @code{delete-process} closes the ++connection, but does not kill the program at the other end; that ++program must decide what to do about closure of the connection. ++ ++ Lisp programs can listen for connections by creating network ++servers. A network server is also represented by a kind of process ++object, but unlike a network connection, the network server never ++transfers data itself. When it receives a connection request, it ++creates a new network connection to represent the connection just ++made. (The network connection inherits certain information, including ++the process plist, from the server.) The network server then goes ++back to listening for more connection requests. ++ ++ Network connections and servers are created by calling ++@code{make-network-process} with an argument list consisting of ++keyword/argument pairs, for example @code{:server t} to create a ++server process, or @code{:type 'datagram} to create a datagram ++connection. @xref{Low-Level Network}, for details. You can also use ++the @code{open-network-stream} function described below. ++ ++ To distinguish the different types of processes, the ++@code{process-type} function returns the symbol @code{network} for a ++network connection or server, @code{serial} for a serial port ++connection, or @code{real} for a real subprocess. ++ ++ The @code{process-status} function returns @code{open}, ++@code{closed}, @code{connect}, and @code{failed} for network ++connections. For a network server, the status is always ++@code{listen}. None of those values is possible for a real ++subprocess. @xref{Process Information}. ++ ++ You can stop and resume operation of a network process by calling ++@code{stop-process} and @code{continue-process}. For a server ++process, being stopped means not accepting new connections. (Up to 5 ++connection requests will be queued for when you resume the server; you ++can increase this limit, unless it is imposed by the operating ++system.) For a network stream connection, being stopped means not ++processing input (any arriving input waits until you resume the ++connection). For a datagram connection, some number of packets may be ++queued but input may be lost. You can use the function ++@code{process-command} to determine whether a network connection or ++server is stopped; a non-@code{nil} value means yes. ++ ++@defun open-network-stream name buffer-or-name host service ++This function opens a TCP connection, and returns a process object ++that represents the connection. ++ ++The @var{name} argument specifies the name for the process object. It ++is modified as necessary to make it unique. ++ ++The @var{buffer-or-name} argument is the buffer to associate with the ++connection. Output from the connection is inserted in the buffer, ++unless you specify a filter function to handle the output. If ++@var{buffer-or-name} is @code{nil}, it means that the connection is not ++associated with any buffer. ++ ++The arguments @var{host} and @var{service} specify where to connect to; ++@var{host} is the host name (a string), and @var{service} is the name of ++a defined network service (a string) or a port number (an integer). ++@end defun ++ ++@node Network Servers ++@section Network Servers ++@cindex network servers ++ ++ You create a server by calling @code{make-network-process} with ++@code{:server t}. The server will listen for connection requests from ++clients. When it accepts a client connection request, that creates a ++new network connection, itself a process object, with the following ++parameters: ++ ++@itemize @bullet ++@item ++The connection's process name is constructed by concatenating the ++server process' @var{name} with a client identification string. The ++client identification string for an IPv4 connection looks like ++@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a ++unique number in brackets, as in @samp{<@var{nnn}>}. The number ++is unique for each connection in the Emacs session. ++ ++@item ++If the server's filter is non-@code{nil}, the connection process does ++not get a separate process buffer; otherwise, Emacs creates a new ++buffer for the purpose. The buffer name is the server's buffer name ++or process name, concatenated with the client identification string. ++ ++The server's process buffer value is never used directly by Emacs, but ++it is passed to the log function, which can log connections by ++inserting text there. ++ ++@item ++The communication type and the process filter and sentinel are ++inherited from those of the server. The server never directly ++uses its filter and sentinel; their sole purpose is to initialize ++connections made to the server. ++ ++@item ++The connection's process contact info is set according to the client's ++addressing information (typically an IP address and a port number). ++This information is associated with the @code{process-contact} ++keywords @code{:host}, @code{:service}, @code{:remote}. ++ ++@item ++The connection's local address is set up according to the port ++number used for the connection. ++ ++@item ++The client process' plist is initialized from the server's plist. ++@end itemize ++ ++@node Datagrams ++@section Datagrams ++@cindex datagrams ++ ++ A datagram connection communicates with individual packets rather ++than streams of data. Each call to @code{process-send} sends one ++datagram packet (@pxref{Input to Processes}), and each datagram ++received results in one call to the filter function. ++ ++ The datagram connection doesn't have to talk with the same remote ++peer all the time. It has a @dfn{remote peer address} which specifies ++where to send datagrams to. Each time an incoming datagram is passed ++to the filter function, the peer address is set to the address that ++datagram came from; that way, if the filter function sends a datagram, ++it will go back to that place. You can specify the remote peer ++address when you create the datagram connection using the ++@code{:remote} keyword. You can change it later on by calling ++@code{set-process-datagram-address}. ++ ++@defun process-datagram-address process ++If @var{process} is a datagram connection or server, this function ++returns its remote peer address. ++@end defun ++ ++@defun set-process-datagram-address process address ++If @var{process} is a datagram connection or server, this function ++sets its remote peer address to @var{address}. ++@end defun ++ ++@node Low-Level Network ++@section Low-Level Network Access ++ ++ You can also create network connections by operating at a lower ++level than that of @code{open-network-stream}, using ++@code{make-network-process}. ++ ++@menu ++* Proc: Network Processes. Using @code{make-network-process}. ++* Options: Network Options. Further control over network connections. ++* Features: Network Feature Testing. ++ Determining which network features work on ++ the machine you are using. ++@end menu ++ ++@node Network Processes ++@subsection @code{make-network-process} ++ ++ The basic function for creating network connections and network ++servers is @code{make-network-process}. It can do either of those ++jobs, depending on the arguments you give it. ++ ++@defun make-network-process &rest args ++This function creates a network connection or server and returns the ++process object that represents it. The arguments @var{args} are a ++list of keyword/argument pairs. Omitting a keyword is always ++equivalent to specifying it with value @code{nil}, except for ++@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here ++are the meaningful keywords: ++ ++@table @asis ++@item :name @var{name} ++Use the string @var{name} as the process name. It is modified if ++necessary to make it unique. ++ ++@item :type @var{type} ++Specify the communication type. A value of @code{nil} specifies a ++stream connection (the default); @code{datagram} specifies a datagram ++connection. Both connections and servers can be of either type. ++ ++@item :server @var{server-flag} ++If @var{server-flag} is non-@code{nil}, create a server. Otherwise, ++create a connection. For a stream type server, @var{server-flag} may ++be an integer which then specifies the length of the queue of pending ++connections to the server. The default queue length is 5. ++ ++@item :host @var{host} ++Specify the host to connect to. @var{host} should be a host name or ++Internet address, as a string, or the symbol @code{local} to specify ++the local host. If you specify @var{host} for a server, it must ++specify a valid address for the local host, and only clients ++connecting to that address will be accepted. ++ ++@item :service @var{service} ++@var{service} specifies a port number to connect to, or, for a server, ++the port number to listen on. It should be a service name that ++translates to a port number, or an integer specifying the port number ++directly. For a server, it can also be @code{t}, which means to let ++the system select an unused port number. ++ ++@item :family @var{family} ++@var{family} specifies the address (and protocol) family for ++communication. @code{nil} means determine the proper address family ++automatically for the given @var{host} and @var{service}. ++@code{local} specifies a Unix socket, in which case @var{host} is ++ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6 ++respectively. ++ ++@item :local @var{local-address} ++For a server process, @var{local-address} is the address to listen on. ++It overrides @var{family}, @var{host} and @var{service}, and you ++may as well not specify them. ++ ++@item :remote @var{remote-address} ++For a connection, @var{remote-address} is the address to connect to. ++It overrides @var{family}, @var{host} and @var{service}, and you ++may as well not specify them. ++ ++For a datagram server, @var{remote-address} specifies the initial ++setting of the remote datagram address. ++ ++The format of @var{local-address} or @var{remote-address} depends on ++the address family: ++ ++@itemize - ++@item ++An IPv4 address is represented as a five-element vector of four 8-bit ++integers and one 16-bit integer ++@code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to ++numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number ++@var{p}. ++ ++@item ++An IPv6 address is represented as a nine-element vector of 16-bit ++integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f} ++@var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address ++@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and ++port number @var{p}. ++ ++@item ++A local address is represented as a string which specifies the address ++in the local address space. ++ ++@item ++An ``unsupported family'' address is represented by a cons ++@code{(@var{f} . @var{av})}, where @var{f} is the family number and ++@var{av} is a vector specifying the socket address using one element ++per address data byte. Do not rely on this format in portable code, ++as it may depend on implementation defined constants, data sizes, and ++data structure alignment. ++@end itemize ++ ++@item :nowait @var{bool} ++If @var{bool} is non-@code{nil} for a stream connection, return ++without waiting for the connection to complete. When the connection ++succeeds or fails, Emacs will call the sentinel function, with a ++second argument matching @code{"open"} (if successful) or ++@code{"failed"}. The default is to block, so that ++@code{make-network-process} does not return until the connection ++has succeeded or failed. ++ ++@item :stop @var{stopped} ++Start the network connection or server in the `stopped' state if ++@var{stopped} is non-@code{nil}. ++ ++@item :buffer @var{buffer} ++Use @var{buffer} as the process buffer. ++ ++@item :coding @var{coding} ++Use @var{coding} as the coding system for this process. To specify ++different coding systems for decoding data from the connection and for ++encoding data sent to it, specify @code{(@var{decoding} . ++@var{encoding})} for @var{coding}. ++ ++If you don't specify this keyword at all, the default ++is to determine the coding systems from the data. ++ ++@item :noquery @var{query-flag} ++Initialize the process query flag to @var{query-flag}. ++@xref{Query Before Exit}. ++ ++@item :filter @var{filter} ++Initialize the process filter to @var{filter}. ++ ++@item :filter-multibyte @var{bool} ++If @var{bool} is non-@code{nil}, strings given to the process filter ++are multibyte, otherwise they are unibyte. If you don't specify this ++keyword at all, the default is that the strings are multibyte if ++@code{default-enable-multibyte-characters} is non-@code{nil}. ++ ++@item :sentinel @var{sentinel} ++Initialize the process sentinel to @var{sentinel}. ++ ++@item :log @var{log} ++Initialize the log function of a server process to @var{log}. The log ++function is called each time the server accepts a network connection ++from a client. The arguments passed to the log function are ++@var{server}, @var{connection}, and @var{message}, where @var{server} ++is the server process, @var{connection} is the new process for the ++connection, and @var{message} is a string describing what has ++happened. ++ ++@item :plist @var{plist} ++Initialize the process plist to @var{plist}. ++@end table ++ ++The original argument list, modified with the actual connection ++information, is available via the @code{process-contact} function. ++@end defun ++ ++@node Network Options ++@subsection Network Options ++ ++ The following network options can be specified when you create a ++network process. Except for @code{:reuseaddr}, you can also set or ++modify these options later, using @code{set-network-process-option}. ++ ++ For a server process, the options specified with ++@code{make-network-process} are not inherited by the client ++connections, so you will need to set the necessary options for each ++child connection as it is created. ++ ++@table @asis ++@item :bindtodevice @var{device-name} ++If @var{device-name} is a non-empty string identifying a network ++interface name (see @code{network-interface-list}), only handle ++packets received on that interface. If @var{device-name} is @code{nil} ++(the default), handle packets received on any interface. ++ ++Using this option may require special privileges on some systems. ++ ++@item :broadcast @var{broadcast-flag} ++If @var{broadcast-flag} is non-@code{nil} for a datagram process, the ++process will receive datagram packet sent to a broadcast address, and ++be able to send packets to a broadcast address. Ignored for a stream ++connection. ++ ++@item :dontroute @var{dontroute-flag} ++If @var{dontroute-flag} is non-@code{nil}, the process can only send ++to hosts on the same network as the local host. ++ ++@item :keepalive @var{keepalive-flag} ++If @var{keepalive-flag} is non-@code{nil} for a stream connection, ++enable exchange of low-level keep-alive messages. ++ ++@item :linger @var{linger-arg} ++If @var{linger-arg} is non-@code{nil}, wait for successful ++transmission of all queued packets on the connection before it is ++deleted (see @code{delete-process}). If @var{linger-arg} is an ++integer, it specifies the maximum time in seconds to wait for queued ++packets to be sent before closing the connection. Default is ++@code{nil} which means to discard unsent queued packets when the ++process is deleted. ++ ++@item :oobinline @var{oobinline-flag} ++If @var{oobinline-flag} is non-@code{nil} for a stream connection, ++receive out-of-band data in the normal data stream. Otherwise, ignore ++out-of-band data. ++ ++@item :priority @var{priority} ++Set the priority for packets sent on this connection to the integer ++@var{priority}. The interpretation of this number is protocol ++specific, such as setting the TOS (type of service) field on IP ++packets sent on this connection. It may also have system dependent ++effects, such as selecting a specific output queue on the network ++interface. ++ ++@item :reuseaddr @var{reuseaddr-flag} ++If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream ++server process, allow this server to reuse a specific port number (see ++@code{:service}) unless another process on this host is already ++listening on that port. If @var{reuseaddr-flag} is @code{nil}, there ++may be a period of time after the last use of that port (by any ++process on the host), where it is not possible to make a new server on ++that port. ++@end table ++ ++@defun set-network-process-option process option value &optional no-error ++This function sets or modifies a network option for network process ++@var{process}. See @code{make-network-process} for details of options ++@var{option} and their corresponding values @var{value}. If ++@var{no-error} is non-@code{nil}, this function returns @code{nil} ++instead of signaling an error if @var{option} is not a supported ++option. If the function successfully completes, it returns @code{t}. ++ ++The current setting of an option is available via the ++@code{process-contact} function. ++@end defun ++ ++@node Network Feature Testing ++@subsection Testing Availability of Network Features ++ ++ To test for the availability of a given network feature, use ++@code{featurep} like this: ++ ++@example ++(featurep 'make-network-process '(@var{keyword} @var{value})) ++@end example ++ ++@noindent ++The result of the first form is @code{t} if it works to specify ++@var{keyword} with value @var{value} in @code{make-network-process}. ++The result of the second form is @code{t} if @var{keyword} is ++supported by @code{make-network-process}. Here are some of the ++@var{keyword}---@var{value} pairs you can test in ++this way. ++ ++@table @code ++@item (:nowait t) ++Non-@code{nil} if non-blocking connect is supported. ++@item (:type datagram) ++Non-@code{nil} if datagrams are supported. ++@item (:family local) ++Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported. ++@item (:family ipv6) ++Non-@code{nil} if IPv6 is supported. ++@item (:service t) ++Non-@code{nil} if the system can select the port for a server. ++@end table ++ ++ To test for the availability of a given network option, use ++@code{featurep} like this: ++ ++@example ++(featurep 'make-network-process '@var{keyword}) ++@end example ++ ++@noindent ++Here are some of the options you can test in this way. ++ ++@table @code ++@item :bindtodevice ++@itemx :broadcast ++@itemx :dontroute ++@itemx :keepalive ++@itemx :linger ++@itemx :oobinline ++@itemx :priority ++@itemx :reuseaddr ++That particular network option is supported by ++@code{make-network-process} and @code{set-network-process-option}. ++@end table ++ ++@node Misc Network ++@section Misc Network Facilities ++ ++ These additional functions are useful for creating and operating ++on network connections. Note that they are supported only on some ++systems. ++ ++@defun network-interface-list ++This function returns a list describing the network interfaces ++of the machine you are using. The value is an alist whose ++elements have the form @code{(@var{name} . @var{address})}. ++@var{address} has the same form as the @var{local-address} ++and @var{remote-address} arguments to @code{make-network-process}. ++@end defun ++ ++@defun network-interface-info ifname ++This function returns information about the network interface named ++@var{ifname}. The value is a list of the form ++@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}. ++ ++@table @var ++@item addr ++The Internet protocol address. ++@item bcast ++The broadcast address. ++@item netmask ++The network mask. ++@item hwaddr ++The layer 2 address (Ethernet MAC address, for instance). ++@item flags ++The current flags of the interface. ++@end table ++@end defun ++ ++@defun format-network-address address &optional omit-port ++This function converts the Lisp representation of a network address to ++a string. ++ ++A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} ++represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port ++number @var{p}. @code{format-network-address} converts that to the ++string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}. ++ ++A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e} ++@var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along ++with a port number. @code{format-network-address} converts that to ++the string ++@code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}. ++ ++If the vector does not include the port number, @var{p}, or if ++@var{omit-port} is non-@code{nil}, the result does not include the ++@code{:@var{p}} suffix. ++@end defun ++ ++@node Serial Ports ++@section Communicating with Serial Ports ++@cindex @file{/dev/tty} ++@cindex @file{COM1} ++@cindex serial connections ++ ++ Emacs can communicate with serial ports. For interactive use, ++@kbd{M-x serial-term} opens a terminal window. In a Lisp program, ++@code{make-serial-process} creates a process object. ++ ++ The serial port can be configured at run-time, without having to ++close and re-open it. The function @code{serial-process-configure} ++lets you change the speed, bytesize, and other parameters. In a ++terminal window created by @code{serial-term}, you can click on the ++mode line for configuration. ++ ++ A serial connection is represented by a process object which can be ++used similar to a subprocess or network process. You can send and ++receive data and configure the serial port. A serial process object ++has no process ID, you can't send signals to it, and the status codes ++are different from other types of processes. ++@code{delete-process} on the process object or @code{kill-buffer} on ++the process buffer close the connection, but this does not affect the ++device connected to the serial port. ++ ++ The function @code{process-type} returns the symbol @code{serial} ++for a process object representing a serial port connection. ++ ++ Serial ports are available on GNU/Linux, Unix, and Windows systems. ++ ++@deffn Command serial-term port speed ++Start a terminal-emulator for a serial port in a new buffer. ++@var{port} is the name of the serial port to which to connect. For ++example, this could be @file{/dev/ttyS0} on Unix. On Windows, this ++could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in ++Lisp strings). ++ ++@var{speed} is the speed of the serial port in bits per second. 9600 ++is a common value. The buffer is in Term mode; see @ref{Term Mode,,, ++emacs, The GNU Emacs Manual}, for the commands to use in that buffer. ++You can change the speed and the configuration in the mode line menu. ++@end deffn ++ ++@defun make-serial-process &rest args ++This function creates a process and a buffer. Arguments are specified ++as keyword/argument pairs. Here's the list of the meaningful keywords: ++ ++@table @code ++@item :port @var{port}@r{ (mandatory)} ++This is the name of the serial port. On Unix and GNU systems, this is ++a file name such as @file{/dev/ttyS0}. On Windows, this could be ++@file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9} ++(double the backslashes in Lisp strings). ++ ++@item :speed @var{speed}@r{ (mandatory)} ++The speed of the serial port in bits per second. This function calls ++@code{serial-process-configure} to handle the speed. ++ ++@item :name @var{name} ++The name of the process. If @var{name} is not given, @var{port} will ++serve as the process name as well. ++ ++@item :buffer @var{buffer} ++The buffer to associate with the process. The value could be either a ++buffer or a string that names a buffer. Process output goes at the ++end of that buffer, unless you specify an output stream or filter ++function to handle the output. If @var{buffer} is not given, the ++process buffer's name is taken from the value of the @code{:name} ++keyword. ++ ++@item :coding @var{coding} ++If @var{coding} is a symbol, it specifies the coding system used for ++both reading and writing for this process. If @var{coding} is a cons ++@code{(decoding . encoding)}, @var{decoding} is used for reading, and ++@var{encoding} is used for writing. If not specified, the default is ++to determine the coding systems from data itself. ++ ++@item :noquery @var{query-flag} ++Initialize the process query flag to @var{query-flag}. @xref{Query ++Before Exit}. The flags defaults to @code{nil} if unspecified. ++ ++@item :stop @var{bool} ++Start process in the @code{stopped} state if @var{bool} is ++non-@code{nil}. In the stopped state, a serial process does not ++accept incoming data, but you can send outgoing data. The stopped ++state is cleared by @code{continue-process} and set by ++@code{stop-process}. ++ ++@item :filter @var{filter} ++Install @var{filter} as the process filter. ++ ++@item :sentinel @var{sentinel} ++Install @var{sentinel} as the process sentinel. ++ ++@item :plist @var{plist} ++Install @var{plist} as the initial plist of the process. ++ ++@item :speed ++@itemx :bytesize ++@itemx :parity ++@itemx :stopbits ++@itemx :flowcontrol ++These arguments are handled by @code{serial-process-configure}, which ++is called by @code{make-serial-process}. ++@end table ++ ++The original argument list, possibly modified by later configuration, ++is available via the function @code{process-contact}. ++ ++Examples: ++ ++@example ++(make-serial-process :port "/dev/ttyS0" :speed 9600) ++ ++(make-serial-process :port "COM1" :speed 115200 :stopbits 2) ++ ++(make-serial-process :port "\\\\.\\COM13" :speed 1200 ++ :bytesize 7 :parity 'odd) ++ ++(make-serial-process :port "/dev/tty.BlueConsole-SPP-1" ++ :speed nil) ++@end example ++@end defun ++ ++@defun serial-process-configure &rest args ++@cindex baud, in serial connections ++@cindex bytesize, in serial connections ++@cindex parity, in serial connections ++@cindex stopbits, in serial connections ++@cindex flowcontrol, in serial connections ++ ++This functions configures a serial port connection. Arguments are ++specified as keyword/argument pairs. Attributes that are not given ++are re-initialized from the process's current configuration (available ++via the function @code{process-contact}) or set to reasonable default ++values. The following arguments are defined: ++ ++@table @code ++@item :process @var{process} ++@itemx :name @var{name} ++@itemx :buffer @var{buffer} ++@itemx :port @var{port} ++Any of these arguments can be given to identify the process that is to ++be configured. If none of these arguments is given, the current ++buffer's process is used. ++ ++@item :speed @var{speed} ++The speed of the serial port in bits per second, a.k.a.@: @dfn{baud ++rate}. The value can be any number, but most serial ports work only ++at a few defined values between 1200 and 115200, with 9600 being the ++most common value. If @var{speed} is @code{nil}, the function ignores ++all other arguments and does not configure the port. This may be ++useful for special serial ports such as Bluetooth-to-serial converters ++which can only be configured through AT commands sent through the ++connection. The value of @code{nil} for @var{speed} is valid only for ++connections that were already opened by a previous call to ++@code{make-serial-process} or @code{serial-term}. ++ ++@item :bytesize @var{bytesize} ++The number of bits per byte, which can be 7 or 8. If @var{bytesize} ++is not given or @code{nil}, it defaults to 8. ++ ++@item :parity @var{parity} ++The value can be @code{nil} (don't use parity), the symbol ++@code{odd} (use odd parity), or the symbol @code{even} (use even ++parity). If @var{parity} is not given, it defaults to no parity. ++ ++@item :stopbits @var{stopbits} ++The number of stopbits used to terminate a transmission ++of each byte. @var{stopbits} can be 1 or 2. If @var{stopbits} is not ++given or @code{nil}, it defaults to 1. ++ ++@item :flowcontrol @var{flowcontrol} ++The type of flow control to use for this connection, which is either ++@code{nil} (don't use flow control), the symbol @code{hw} (use RTS/CTS ++hardware flow control), or the symbol @code{sw} (use XON/XOFF software ++flow control). If @var{flowcontrol} is not given, it defaults to no ++flow control. ++@end table ++ ++@code{serial-process-configure} is called by @code{make-serial-process} for the ++initial configuration of the serial port. ++ ++Examples: ++ ++@example ++(serial-process-configure :process "/dev/ttyS0" :speed 1200) ++ ++(serial-process-configure :buffer "COM1" :stopbits 1 ++ :parity 'odd :flowcontrol 'hw) ++ ++(serial-process-configure :port "\\\\.\\COM13" :bytesize 7) ++@end example ++@end defun ++ ++@node Byte Packing ++@section Packing and Unpacking Byte Arrays ++@cindex byte packing and unpacking ++ ++ This section describes how to pack and unpack arrays of bytes, ++usually for binary network protocols. These functions convert byte arrays ++to alists, and vice versa. The byte array can be represented as a ++unibyte string or as a vector of integers, while the alist associates ++symbols either with fixed-size objects or with recursive sub-alists. ++ ++@cindex serializing ++@cindex deserializing ++@cindex packing ++@cindex unpacking ++ Conversion from byte arrays to nested alists is also known as ++@dfn{deserializing} or @dfn{unpacking}, while going in the opposite ++direction is also known as @dfn{serializing} or @dfn{packing}. ++ ++@menu ++* Bindat Spec:: Describing data layout. ++* Bindat Functions:: Doing the unpacking and packing. ++* Bindat Examples:: Samples of what bindat.el can do for you! ++@end menu ++ ++@node Bindat Spec ++@subsection Describing Data Layout ++ ++ To control unpacking and packing, you write a @dfn{data layout ++specification}, a special nested list describing named and typed ++@dfn{fields}. This specification controls length of each field to be ++processed, and how to pack or unpack it. We normally keep bindat specs ++in variables whose names end in @samp{-bindat-spec}; that kind of name ++is automatically recognized as ``risky.'' ++ ++@cindex endianness ++@cindex big endian ++@cindex little endian ++@cindex network byte ordering ++ A field's @dfn{type} describes the size (in bytes) of the object ++that the field represents and, in the case of multibyte fields, how ++the bytes are ordered within the field. The two possible orderings ++are ``big endian'' (also known as ``network byte ordering'') and ++``little endian.'' For instance, the number @code{#x23cd} (decimal ++9165) in big endian would be the two bytes @code{#x23} @code{#xcd}; ++and in little endian, @code{#xcd} @code{#x23}. Here are the possible ++type values: ++ ++@table @code ++@item u8 ++@itemx byte ++Unsigned byte, with length 1. ++ ++@item u16 ++@itemx word ++@itemx short ++Unsigned integer in network byte order, with length 2. ++ ++@item u24 ++Unsigned integer in network byte order, with length 3. ++ ++@item u32 ++@itemx dword ++@itemx long ++Unsigned integer in network byte order, with length 4. ++Note: These values may be limited by Emacs' integer implementation limits. ++ ++@item u16r ++@itemx u24r ++@itemx u32r ++Unsigned integer in little endian order, with length 2, 3 and 4, respectively. ++ ++@item str @var{len} ++String of length @var{len}. ++ ++@item strz @var{len} ++Zero-terminated string, in a fixed-size field with length @var{len}. ++ ++@item vec @var{len} [@var{type}] ++Vector of @var{len} elements of type @var{type}, or bytes if not ++@var{type} is specified. ++The @var{type} is any of the simple types above, or another vector ++specified as a list @code{(vec @var{len} [@var{type}])}. ++ ++@item ip ++Four-byte vector representing an Internet address. For example: ++@code{[127 0 0 1]} for localhost. ++ ++@item bits @var{len} ++List of set bits in @var{len} bytes. The bytes are taken in big ++endian order and the bits are numbered starting with @code{8 * ++@var{len} @minus{} 1} and ending with zero. For example: @code{bits ++2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and ++@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}. ++ ++@item (eval @var{form}) ++@var{form} is a Lisp expression evaluated at the moment the field is ++unpacked or packed. The result of the evaluation should be one of the ++above-listed type specifications. ++@end table ++ ++For a fixed-size field, the length @var{len} is given as an integer ++specifying the number of bytes in the field. ++ ++When the length of a field is not fixed, it typically depends on the ++value of a preceding field. In this case, the length @var{len} can be ++given either as a list @code{(@var{name} ...)} identifying a ++@dfn{field name} in the format specified for @code{bindat-get-field} ++below, or by an expression @code{(eval @var{form})} where @var{form} ++should evaluate to an integer, specifying the field length. ++ ++A field specification generally has the form @code{([@var{name}] ++@var{handler})}. The square braces indicate that @var{name} is ++optional. (Don't use names that are symbols meaningful as type ++specifications (above) or handler specifications (below), since that ++would be ambiguous.) @var{name} can be a symbol or the expression ++@code{(eval @var{form})}, in which case @var{form} should evaluate to ++a symbol. ++ ++@var{handler} describes how to unpack or pack the field and can be one ++of the following: ++ ++@table @code ++@item @var{type} ++Unpack/pack this field according to the type specification @var{type}. ++ ++@item eval @var{form} ++Evaluate @var{form}, a Lisp expression, for side-effect only. If the ++field name is specified, the value is bound to that field name. ++ ++@item fill @var{len} ++Skip @var{len} bytes. In packing, this leaves them unchanged, ++which normally means they remain zero. In unpacking, this means ++they are ignored. ++ ++@item align @var{len} ++Skip to the next multiple of @var{len} bytes. ++ ++@item struct @var{spec-name} ++Process @var{spec-name} as a sub-specification. This describes a ++structure nested within another structure. ++ ++@item union @var{form} (@var{tag} @var{spec})@dots{} ++@c ??? I don't see how one would actually use this. ++@c ??? what kind of expression would be useful for @var{form}? ++Evaluate @var{form}, a Lisp expression, find the first @var{tag} ++that matches it, and process its associated data layout specification ++@var{spec}. Matching can occur in one of three ways: ++ ++@itemize ++@item ++If a @var{tag} has the form @code{(eval @var{expr})}, evaluate ++@var{expr} with the variable @code{tag} dynamically bound to the value ++of @var{form}. A non-@code{nil} result indicates a match. ++ ++@item ++@var{tag} matches if it is @code{equal} to the value of @var{form}. ++ ++@item ++@var{tag} matches unconditionally if it is @code{t}. ++@end itemize ++ ++@item repeat @var{count} @var{field-specs}@dots{} ++Process the @var{field-specs} recursively, in order, then repeat ++starting from the first one, processing all the specs @var{count} ++times overall. The @var{count} is given using the same formats as a ++field length---if an @code{eval} form is used, it is evaluated just once. ++For correct operation, each spec in @var{field-specs} must include a name. ++@end table ++ ++For the @code{(eval @var{form})} forms used in a bindat specification, ++the @var{form} can access and update these dynamically bound variables ++during evaluation: ++ ++@table @code ++@item last ++Value of the last field processed. ++ ++@item bindat-raw ++The data as a byte array. ++ ++@item bindat-idx ++Current index (within @code{bindat-raw}) for unpacking or packing. ++ ++@item struct ++The alist containing the structured data that have been unpacked so ++far, or the entire structure being packed. You can use ++@code{bindat-get-field} to access specific fields of this structure. ++ ++@item count ++@itemx index ++Inside a @code{repeat} block, these contain the maximum number of ++repetitions (as specified by the @var{count} parameter), and the ++current repetition number (counting from 0). Setting @code{count} to ++zero will terminate the inner-most repeat block after the current ++repetition has completed. ++@end table ++ ++@node Bindat Functions ++@subsection Functions to Unpack and Pack Bytes ++ ++ In the following documentation, @var{spec} refers to a data layout ++specification, @code{bindat-raw} to a byte array, and @var{struct} to an ++alist representing unpacked field data. ++ ++@defun bindat-unpack spec bindat-raw &optional bindat-idx ++This function unpacks data from the unibyte string or byte ++array @code{bindat-raw} ++according to @var{spec}. Normally this starts unpacking at the ++beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it ++specifies a zero-based starting position to use instead. ++ ++The value is an alist or nested alist in which each element describes ++one unpacked field. ++@end defun ++ ++@defun bindat-get-field struct &rest name ++This function selects a field's data from the nested alist ++@var{struct}. Usually @var{struct} was returned by ++@code{bindat-unpack}. If @var{name} corresponds to just one argument, ++that means to extract a top-level field value. Multiple @var{name} ++arguments specify repeated lookup of sub-structures. An integer name ++acts as an array index. ++ ++For example, if @var{name} is @code{(a b 2 c)}, that means to find ++field @code{c} in the third element of subfield @code{b} of field ++@code{a}. (This corresponds to @code{struct.a.b[2].c} in C.) ++@end defun ++ ++ Although packing and unpacking operations change the organization of ++data (in memory), they preserve the data's @dfn{total length}, which is ++the sum of all the fields' lengths, in bytes. This value is not ++generally inherent in either the specification or alist alone; instead, ++both pieces of information contribute to its calculation. Likewise, the ++length of a string or array being unpacked may be longer than the data's ++total length as described by the specification. ++ ++@defun bindat-length spec struct ++This function returns the total length of the data in @var{struct}, ++according to @var{spec}. ++@end defun ++ ++@defun bindat-pack spec struct &optional bindat-raw bindat-idx ++This function returns a byte array packed according to @var{spec} from ++the data in the alist @var{struct}. Normally it creates and fills a ++new byte array starting at the beginning. However, if @var{bindat-raw} ++is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to ++pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting ++offset for packing into @code{bindat-raw}. ++ ++When pre-allocating, you should make sure @code{(length @var{bindat-raw})} ++meets or exceeds the total length to avoid an out-of-range error. ++@end defun ++ ++@defun bindat-ip-to-string ip ++Convert the Internet address vector @var{ip} to a string in the usual ++dotted notation. ++ ++@example ++(bindat-ip-to-string [127 0 0 1]) ++ @result{} "127.0.0.1" ++@end example ++@end defun ++ ++@node Bindat Examples ++@subsection Examples of Byte Unpacking and Packing ++ ++ Here is a complete example of byte unpacking and packing: ++ ++@lisp ++(defvar fcookie-index-spec ++ '((:version u32) ++ (:count u32) ++ (:longest u32) ++ (:shortest u32) ++ (:flags u32) ++ (:delim u8) ++ (:ignored fill 3) ++ (:offset repeat (:count) ++ (:foo u32))) ++ "Description of a fortune cookie index file's contents.") ++ ++(defun fcookie (cookies &optional index) ++ "Display a random fortune cookie from file COOKIES. ++Optional second arg INDEX specifies the associated index ++filename, which is by default constructed by appending ++\".dat\" to COOKIES. Display cookie text in possibly ++new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME ++is COOKIES without the directory part." ++ (interactive "fCookies file: ") ++ (let* ((info (with-temp-buffer ++ (insert-file-contents-literally ++ (or index (concat cookies ".dat"))) ++ (bindat-unpack fcookie-index-spec ++ (buffer-string)))) ++ (sel (random (bindat-get-field info :count))) ++ (beg (cdar (bindat-get-field info :offset sel))) ++ (end (or (cdar (bindat-get-field info ++ :offset (1+ sel))) ++ (nth 7 (file-attributes cookies))))) ++ (switch-to-buffer ++ (get-buffer-create ++ (format "*Fortune Cookie: %s*" ++ (file-name-nondirectory cookies)))) ++ (erase-buffer) ++ (insert-file-contents-literally ++ cookies nil beg (- end 3)))) ++ ++(defun fcookie-create-index (cookies &optional index delim) ++ "Scan file COOKIES, and write out its index file. ++Optional second arg INDEX specifies the index filename, ++which is by default constructed by appending \".dat\" to ++COOKIES. Optional third arg DELIM specifies the unibyte ++character which, when found on a line of its own in ++COOKIES, indicates the border between entries." ++ (interactive "fCookies file: ") ++ (setq delim (or delim ?%)) ++ (let ((delim-line (format "\n%c\n" delim)) ++ (count 0) ++ (max 0) ++ min p q len offsets) ++ (unless (= 3 (string-bytes delim-line)) ++ (error "Delimiter cannot be represented in one byte")) ++ (with-temp-buffer ++ (insert-file-contents-literally cookies) ++ (while (and (setq p (point)) ++ (search-forward delim-line (point-max) t) ++ (setq len (- (point) 3 p))) ++ (setq count (1+ count) ++ max (max max len) ++ min (min (or min max) len) ++ offsets (cons (1- p) offsets)))) ++ (with-temp-buffer ++ (set-buffer-multibyte nil) ++ (insert ++ (bindat-pack ++ fcookie-index-spec ++ `((:version . 2) ++ (:count . ,count) ++ (:longest . ,max) ++ (:shortest . ,min) ++ (:flags . 0) ++ (:delim . ,delim) ++ (:offset . ,(mapcar (lambda (o) ++ (list (cons :foo o))) ++ (nreverse offsets)))))) ++ (let ((coding-system-for-write 'raw-text-unix)) ++ (write-file (or index (concat cookies ".dat"))))))) ++@end lisp ++ ++Following is an example of defining and unpacking a complex structure. ++Consider the following C structures: ++ ++@example ++struct header @{ ++ unsigned long dest_ip; ++ unsigned long src_ip; ++ unsigned short dest_port; ++ unsigned short src_port; ++@}; ++ ++struct data @{ ++ unsigned char type; ++ unsigned char opcode; ++ unsigned short length; /* In network byte order */ ++ unsigned char id[8]; /* null-terminated string */ ++ unsigned char data[/* (length + 3) & ~3 */]; ++@}; ++ ++struct packet @{ ++ struct header header; ++ unsigned long counters[2]; /* In little endian order */ ++ unsigned char items; ++ unsigned char filler[3]; ++ struct data item[/* items */]; ++ ++@}; ++@end example ++ ++The corresponding data layout specification: ++ ++@lisp ++(setq header-spec ++ '((dest-ip ip) ++ (src-ip ip) ++ (dest-port u16) ++ (src-port u16))) ++ ++(setq data-spec ++ '((type u8) ++ (opcode u8) ++ (length u16) ;; network byte order ++ (id strz 8) ++ (data vec (length)) ++ (align 4))) ++ ++(setq packet-spec ++ '((header struct header-spec) ++ (counters vec 2 u32r) ;; little endian order ++ (items u8) ++ (fill 3) ++ (item repeat (items) ++ (struct data-spec)))) ++@end lisp ++ ++A binary data representation: ++ ++@lisp ++(setq binary-data ++ [ 192 168 1 100 192 168 1 101 01 28 21 32 ++ 160 134 1 0 5 1 0 0 2 0 0 0 ++ 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 ++ 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) ++@end lisp ++ ++The corresponding decoded structure: ++ ++@lisp ++(setq decoded (bindat-unpack packet-spec binary-data)) ++ @result{} ++((header ++ (dest-ip . [192 168 1 100]) ++ (src-ip . [192 168 1 101]) ++ (dest-port . 284) ++ (src-port . 5408)) ++ (counters . [100000 261]) ++ (items . 2) ++ (item ((data . [1 2 3 4 5]) ++ (id . "ABCDEF") ++ (length . 5) ++ (opcode . 3) ++ (type . 2)) ++ ((data . [6 7 8 9 10 11 12]) ++ (id . "BCDEFG") ++ (length . 7) ++ (opcode . 4) ++ (type . 1)))) ++@end lisp ++ ++Fetching data from this structure: ++ ++@lisp ++(bindat-get-field decoded 'item 1 'id) ++ @result{} "BCDEFG" ++@end lisp ++ ++@ignore ++ arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a ++@end ignore +diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi +new file mode 100644 +index 0000000..2b89a89 +--- /dev/null ++++ b/doc/lispref/searching.texi +@@ -0,0 +1,1842 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/searching ++@node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top ++@chapter Searching and Matching ++@cindex searching ++ ++ GNU Emacs provides two ways to search through a buffer for specified ++text: exact string searches and regular expression searches. After a ++regular expression search, you can examine the @dfn{match data} to ++determine which text matched the whole regular expression or various ++portions of it. ++ ++@menu ++* String Search:: Search for an exact match. ++* Searching and Case:: Case-independent or case-significant searching. ++* Regular Expressions:: Describing classes of strings. ++* Regexp Search:: Searching for a match for a regexp. ++* POSIX Regexps:: Searching POSIX-style for the longest match. ++* Match Data:: Finding out which part of the text matched, ++ after a string or regexp search. ++* Search and Replace:: Commands that loop, searching and replacing. ++* Standard Regexps:: Useful regexps for finding sentences, pages,... ++@end menu ++ ++ The @samp{skip-chars@dots{}} functions also perform a kind of searching. ++@xref{Skipping Characters}. To search for changes in character ++properties, see @ref{Property Search}. ++ ++@node String Search ++@section Searching for Strings ++@cindex string search ++ ++ These are the primitive functions for searching through the text in a ++buffer. They are meant for use in programs, but you may call them ++interactively. If you do so, they prompt for the search string; the ++arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat} ++is 1. ++ ++ These search functions convert the search string to multibyte if the ++buffer is multibyte; they convert the search string to unibyte if the ++buffer is unibyte. @xref{Text Representations}. ++ ++@deffn Command search-forward string &optional limit noerror repeat ++This function searches forward from point for an exact match for ++@var{string}. If successful, it sets point to the end of the occurrence ++found, and returns the new value of point. If no match is found, the ++value and side effects depend on @var{noerror} (see below). ++@c Emacs 19 feature ++ ++In the following example, point is initially at the beginning of the ++line. Then @code{(search-forward "fox")} moves point after the last ++letter of @samp{fox}: ++ ++@example ++@group ++---------- Buffer: foo ---------- ++@point{}The quick brown fox jumped over the lazy dog. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(search-forward "fox") ++ @result{} 20 ++ ++---------- Buffer: foo ---------- ++The quick brown fox@point{} jumped over the lazy dog. ++---------- Buffer: foo ---------- ++@end group ++@end example ++ ++The argument @var{limit} specifies the upper bound to the search. (It ++must be a position in the current buffer.) No match extending after ++that position is accepted. If @var{limit} is omitted or @code{nil}, it ++defaults to the end of the accessible portion of the buffer. ++ ++@kindex search-failed ++What happens when the search fails depends on the value of ++@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed} ++error is signaled. If @var{noerror} is @code{t}, @code{search-forward} ++returns @code{nil} and does nothing. If @var{noerror} is neither ++@code{nil} nor @code{t}, then @code{search-forward} moves point to the ++upper bound and returns @code{nil}. (It would be more consistent now to ++return the new position of point in that case, but some existing ++programs may depend on a value of @code{nil}.) ++ ++The argument @var{noerror} only affects valid searches which fail to ++find a match. Invalid arguments cause errors regardless of ++@var{noerror}. ++ ++If @var{repeat} is supplied (it must be a positive number), then the ++search is repeated that many times (each time starting at the end of the ++previous time's match). If these successive searches succeed, the ++function succeeds, moving point and returning its new value. Otherwise ++the search fails, with results depending on the value of ++@var{noerror}, as described above. ++@end deffn ++ ++@deffn Command search-backward string &optional limit noerror repeat ++This function searches backward from point for @var{string}. It is ++just like @code{search-forward} except that it searches backwards and ++leaves point at the beginning of the match. ++@end deffn ++ ++@deffn Command word-search-forward string &optional limit noerror repeat ++This function searches forward from point for a ``word'' match for ++@var{string}. If it finds a match, it sets point to the end of the ++match found, and returns the new value of point. ++ ++Word matching regards @var{string} as a sequence of words, disregarding ++punctuation that separates them. It searches the buffer for the same ++sequence of words. Each word must be distinct in the buffer (searching ++for the word @samp{ball} does not match the word @samp{balls}), but the ++details of punctuation and spacing are ignored (searching for @samp{ball ++boy} does match @samp{ball. Boy!}). ++ ++In this example, point is initially at the beginning of the buffer; the ++search leaves it between the @samp{y} and the @samp{!}. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++@point{}He said "Please! Find ++the ball boy!" ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(word-search-forward "Please find the ball, boy.") ++ @result{} 35 ++ ++---------- Buffer: foo ---------- ++He said "Please! Find ++the ball boy@point{}!" ++---------- Buffer: foo ---------- ++@end group ++@end example ++ ++If @var{limit} is non-@code{nil}, it must be a position in the current ++buffer; it specifies the upper bound to the search. The match found ++must not extend after that position. ++ ++If @var{noerror} is @code{nil}, then @code{word-search-forward} signals ++an error if the search fails. If @var{noerror} is @code{t}, then it ++returns @code{nil} instead of signaling an error. If @var{noerror} is ++neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the ++end of the accessible portion of the buffer) and returns @code{nil}. ++ ++If @var{repeat} is non-@code{nil}, then the search is repeated that many ++times. Point is positioned at the end of the last match. ++@end deffn ++ ++@deffn Command word-search-forward-lax string &optional limit noerror repeat ++This command is identical to @code{word-search-forward}, except that ++the end of @code{string} need not match a word boundary unless it ends ++in whitespace. For instance, searching for @samp{ball boy} matches ++@samp{ball boyee}, but does not match @samp{aball boy}. ++@end deffn ++ ++@deffn Command word-search-backward string &optional limit noerror repeat ++This function searches backward from point for a word match to ++@var{string}. This function is just like @code{word-search-forward} ++except that it searches backward and normally leaves point at the ++beginning of the match. ++@end deffn ++ ++@deffn Command word-search-backward-lax string &optional limit noerror repeat ++This command is identical to @code{word-search-backward}, except that ++the end of @code{string} need not match a word boundary unless it ends ++in whitespace. ++@end deffn ++ ++@node Searching and Case ++@section Searching and Case ++@cindex searching and case ++ ++ By default, searches in Emacs ignore the case of the text they are ++searching through; if you specify searching for @samp{FOO}, then ++@samp{Foo} or @samp{foo} is also considered a match. This applies to ++regular expressions, too; thus, @samp{[aB]} would match @samp{a} or ++@samp{A} or @samp{b} or @samp{B}. ++ ++ If you do not want this feature, set the variable ++@code{case-fold-search} to @code{nil}. Then all letters must match ++exactly, including case. This is a buffer-local variable; altering the ++variable affects only the current buffer. (@xref{Intro to ++Buffer-Local}.) Alternatively, you may change the value of ++@code{default-case-fold-search}, which is the default value of ++@code{case-fold-search} for buffers that do not override it. ++ ++ Note that the user-level incremental search feature handles case ++distinctions differently. When the search string contains only lower ++case letters, the search ignores case, but when the search string ++contains one or more upper case letters, the search becomes ++case-sensitive. But this has nothing to do with the searching ++functions used in Lisp code. ++ ++@defopt case-fold-search ++This buffer-local variable determines whether searches should ignore ++case. If the variable is @code{nil} they do not ignore case; otherwise ++they do ignore case. ++@end defopt ++ ++@defvar default-case-fold-search ++The value of this variable is the default value for ++@code{case-fold-search} in buffers that do not override it. This is the ++same as @code{(default-value 'case-fold-search)}. ++@end defvar ++ ++@defopt case-replace ++This variable determines whether the higher level replacement ++functions should preserve case. If the variable is @code{nil}, that ++means to use the replacement text verbatim. A non-@code{nil} value ++means to convert the case of the replacement text according to the ++text being replaced. ++ ++This variable is used by passing it as an argument to the function ++@code{replace-match}. @xref{Replacing Match}. ++@end defopt ++ ++@node Regular Expressions ++@section Regular Expressions ++@cindex regular expression ++@cindex regexp ++ ++ A @dfn{regular expression}, or @dfn{regexp} for short, is a pattern that ++denotes a (possibly infinite) set of strings. Searching for matches for ++a regexp is a very powerful operation. This section explains how to write ++regexps; the following section says how to search for them. ++ ++@findex re-builder ++@cindex regular expressions, developing ++ For convenient interactive development of regular expressions, you ++can use the @kbd{M-x re-builder} command. It provides a convenient ++interface for creating regular expressions, by giving immediate visual ++feedback in a separate buffer. As you edit the regexp, all its ++matches in the target buffer are highlighted. Each parenthesized ++sub-expression of the regexp is shown in a distinct face, which makes ++it easier to verify even very complex regexps. ++ ++@menu ++* Syntax of Regexps:: Rules for writing regular expressions. ++* Regexp Example:: Illustrates regular expression syntax. ++* Regexp Functions:: Functions for operating on regular expressions. ++@end menu ++ ++@node Syntax of Regexps ++@subsection Syntax of Regular Expressions ++ ++ Regular expressions have a syntax in which a few characters are ++special constructs and the rest are @dfn{ordinary}. An ordinary ++character is a simple regular expression that matches that character ++and nothing else. The special characters are @samp{.}, @samp{*}, ++@samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new ++special characters will be defined in the future. The character ++@samp{]} is special if it ends a character alternative (see later). ++The character @samp{-} is special inside a character alternative. A ++@samp{[:} and balancing @samp{:]} enclose a character class inside a ++character alternative. Any other character appearing in a regular ++expression is ordinary, unless a @samp{\} precedes it. ++ ++ For example, @samp{f} is not a special character, so it is ordinary, and ++therefore @samp{f} is a regular expression that matches the string ++@samp{f} and no other string. (It does @emph{not} match the string ++@samp{fg}, but it does match a @emph{part} of that string.) Likewise, ++@samp{o} is a regular expression that matches only @samp{o}.@refill ++ ++ Any two regular expressions @var{a} and @var{b} can be concatenated. The ++result is a regular expression that matches a string if @var{a} matches ++some amount of the beginning of that string and @var{b} matches the rest of ++the string.@refill ++ ++ As a simple example, we can concatenate the regular expressions @samp{f} ++and @samp{o} to get the regular expression @samp{fo}, which matches only ++the string @samp{fo}. Still trivial. To do something more powerful, you ++need to use one of the special regular expression constructs. ++ ++@menu ++* Regexp Special:: Special characters in regular expressions. ++* Char Classes:: Character classes used in regular expressions. ++* Regexp Backslash:: Backslash-sequences in regular expressions. ++@end menu ++ ++@node Regexp Special ++@subsubsection Special Characters in Regular Expressions ++ ++ Here is a list of the characters that are special in a regular ++expression. ++ ++@need 800 ++@table @asis ++@item @samp{.}@: @r{(Period)} ++@cindex @samp{.} in regexp ++is a special character that matches any single character except a newline. ++Using concatenation, we can make regular expressions like @samp{a.b}, which ++matches any three-character string that begins with @samp{a} and ends with ++@samp{b}.@refill ++ ++@item @samp{*} ++@cindex @samp{*} in regexp ++is not a construct by itself; it is a postfix operator that means to ++match the preceding regular expression repetitively as many times as ++possible. Thus, @samp{o*} matches any number of @samp{o}s (including no ++@samp{o}s). ++ ++@samp{*} always applies to the @emph{smallest} possible preceding ++expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating ++@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. ++ ++The matcher processes a @samp{*} construct by matching, immediately, as ++many repetitions as can be found. Then it continues with the rest of ++the pattern. If that fails, backtracking occurs, discarding some of the ++matches of the @samp{*}-modified construct in the hope that that will ++make it possible to match the rest of the pattern. For example, in ++matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} ++first tries to match all three @samp{a}s; but the rest of the pattern is ++@samp{ar} and there is only @samp{r} left to match, so this try fails. ++The next alternative is for @samp{a*} to match only two @samp{a}s. With ++this choice, the rest of the regexp matches successfully. ++ ++@strong{Warning:} Nested repetition operators can run for an ++indefinitely long time, if they lead to ambiguous matching. For ++example, trying to match the regular expression @samp{\(x+y*\)*a} ++against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could ++take hours before it ultimately fails. Emacs must try each way of ++grouping the @samp{x}s before concluding that none of them can work. ++Even worse, @samp{\(x*\)*} can match the null string in infinitely ++many ways, so it causes an infinite loop. To avoid these problems, ++check nested repetitions carefully, to make sure that they do not ++cause combinatorial explosions in backtracking. ++ ++@item @samp{+} ++@cindex @samp{+} in regexp ++is a postfix operator, similar to @samp{*} except that it must match ++the preceding expression at least once. So, for example, @samp{ca+r} ++matches the strings @samp{car} and @samp{caaaar} but not the string ++@samp{cr}, whereas @samp{ca*r} matches all three strings. ++ ++@item @samp{?} ++@cindex @samp{?} in regexp ++is a postfix operator, similar to @samp{*} except that it must match the ++preceding expression either once or not at all. For example, ++@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. ++ ++@item @samp{*?}, @samp{+?}, @samp{??} ++@cindex non-greedy repetition characters in regexp ++These are ``non-greedy'' variants of the operators @samp{*}, @samp{+} ++and @samp{?}. Where those operators match the largest possible ++substring (consistent with matching the entire containing expression), ++the non-greedy variants match the smallest possible substring ++(consistent with matching the entire containing expression). ++ ++For example, the regular expression @samp{c[ad]*a} when applied to the ++string @samp{cdaaada} matches the whole string; but the regular ++expression @samp{c[ad]*?a}, applied to that same string, matches just ++@samp{cda}. (The smallest possible match here for @samp{[ad]*?} that ++permits the whole expression to match is @samp{d}.) ++ ++@item @samp{[ @dots{} ]} ++@cindex character alternative (in regexp) ++@cindex @samp{[} in regexp ++@cindex @samp{]} in regexp ++is a @dfn{character alternative}, which begins with @samp{[} and is ++terminated by @samp{]}. In the simplest case, the characters between ++the two brackets are what this character alternative can match. ++ ++Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and ++@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s ++(including the empty string), from which it follows that @samp{c[ad]*r} ++matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. ++ ++You can also include character ranges in a character alternative, by ++writing the starting and ending characters with a @samp{-} between them. ++Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter. ++Ranges may be intermixed freely with individual characters, as in ++@samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter ++or @samp{$}, @samp{%} or period. ++ ++Note that the usual regexp special characters are not special inside a ++character alternative. A completely different set of characters is ++special inside character alternatives: @samp{]}, @samp{-} and @samp{^}. ++ ++To include a @samp{]} in a character alternative, you must make it the ++first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. ++To include a @samp{-}, write @samp{-} as the first or last character of ++the character alternative, or put it after a range. Thus, @samp{[]-]} ++matches both @samp{]} and @samp{-}. ++ ++To include @samp{^} in a character alternative, put it anywhere but at ++the beginning. ++ ++The beginning and end of a range of multibyte characters must be in ++the same character set (@pxref{Character Sets}). Thus, ++@code{"[\x8e0-\x97c]"} is invalid because character 0x8e0 (@samp{a} ++with grave accent) is in the Emacs character set for Latin-1 but the ++character 0x97c (@samp{u} with diaeresis) is in the Emacs character ++set for Latin-2. (We use Lisp string syntax to write that example, ++and a few others in the next few paragraphs, in order to include hex ++escape sequences in them.) ++ ++If a range starts with a unibyte character @var{c} and ends with a ++multibyte character @var{c2}, the range is divided into two parts: one ++is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where ++@var{c1} is the first character of the charset to which @var{c2} ++belongs. ++ ++You cannot always match all non-@acronym{ASCII} characters with the regular ++expression @code{"[\200-\377]"}. This works when searching a unibyte ++buffer or string (@pxref{Text Representations}), but not in a multibyte ++buffer or string, because many non-@acronym{ASCII} characters have codes ++above octal 0377. However, the regular expression @code{"[^\000-\177]"} ++does match all non-@acronym{ASCII} characters (see below regarding @samp{^}), ++in both multibyte and unibyte representations, because only the ++@acronym{ASCII} characters are excluded. ++ ++A character alternative can also specify named ++character classes (@pxref{Char Classes}). This is a POSIX feature whose ++syntax is @samp{[:@var{class}:]}. Using a character class is equivalent ++to mentioning each of the characters in that class; but the latter is ++not feasible in practice, since some classes include thousands of ++different characters. ++ ++@item @samp{[^ @dots{} ]} ++@cindex @samp{^} in regexp ++@samp{[^} begins a @dfn{complemented character alternative}. This ++matches any character except the ones specified. Thus, ++@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and ++digits. ++ ++@samp{^} is not special in a character alternative unless it is the first ++character. The character following the @samp{^} is treated as if it ++were first (in other words, @samp{-} and @samp{]} are not special there). ++ ++A complemented character alternative can match a newline, unless newline is ++mentioned as one of the characters not to match. This is in contrast to ++the handling of regexps in programs such as @code{grep}. ++ ++@item @samp{^} ++@cindex beginning of line in regexp ++When matching a buffer, @samp{^} matches the empty string, but only at the ++beginning of a line in the text being matched (or the beginning of the ++accessible portion of the buffer). Otherwise it fails to match ++anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the ++beginning of a line. ++ ++When matching a string instead of a buffer, @samp{^} matches at the ++beginning of the string or after a newline character. ++ ++For historical compatibility reasons, @samp{^} can be used only at the ++beginning of the regular expression, or after @samp{\(}, @samp{\(?:} ++or @samp{\|}. ++ ++@item @samp{$} ++@cindex @samp{$} in regexp ++@cindex end of line in regexp ++is similar to @samp{^} but matches only at the end of a line (or the ++end of the accessible portion of the buffer). Thus, @samp{x+$} ++matches a string of one @samp{x} or more at the end of a line. ++ ++When matching a string instead of a buffer, @samp{$} matches at the end ++of the string or before a newline character. ++ ++For historical compatibility reasons, @samp{$} can be used only at the ++end of the regular expression, or before @samp{\)} or @samp{\|}. ++ ++@item @samp{\} ++@cindex @samp{\} in regexp ++has two functions: it quotes the special characters (including ++@samp{\}), and it introduces additional special constructs. ++ ++Because @samp{\} quotes special characters, @samp{\$} is a regular ++expression that matches only @samp{$}, and @samp{\[} is a regular ++expression that matches only @samp{[}, and so on. ++ ++Note that @samp{\} also has special meaning in the read syntax of Lisp ++strings (@pxref{String Type}), and must be quoted with @samp{\}. For ++example, the regular expression that matches the @samp{\} character is ++@samp{\\}. To write a Lisp string that contains the characters ++@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another ++@samp{\}. Therefore, the read syntax for a regular expression matching ++@samp{\} is @code{"\\\\"}.@refill ++@end table ++ ++@strong{Please note:} For historical compatibility, special characters ++are treated as ordinary ones if they are in contexts where their special ++meanings make no sense. For example, @samp{*foo} treats @samp{*} as ++ordinary since there is no preceding expression on which the @samp{*} ++can act. It is poor practice to depend on this behavior; quote the ++special character anyway, regardless of where it appears.@refill ++ ++As a @samp{\} is not special inside a character alternative, it can ++never remove the special meaning of @samp{-} or @samp{]}. So you ++should not quote these characters when they have no special meaning ++either. This would not clarify anything, since backslashes can ++legitimately precede these characters where they @emph{have} special ++meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), ++which matches any single character except a backslash. ++ ++In practice, most @samp{]} that occur in regular expressions close a ++character alternative and hence are special. However, occasionally a ++regular expression may try to match a complex pattern of literal ++@samp{[} and @samp{]}. In such situations, it sometimes may be ++necessary to carefully parse the regexp from the start to determine ++which square brackets enclose a character alternative. For example, ++@samp{[^][]]} consists of the complemented character alternative ++@samp{[^][]} (which matches any single character that is not a square ++bracket), followed by a literal @samp{]}. ++ ++The exact rules are that at the beginning of a regexp, @samp{[} is ++special and @samp{]} not. This lasts until the first unquoted ++@samp{[}, after which we are in a character alternative; @samp{[} is ++no longer special (except when it starts a character class) but @samp{]} ++is special, unless it immediately follows the special @samp{[} or that ++@samp{[} followed by a @samp{^}. This lasts until the next special ++@samp{]} that does not end a character class. This ends the character ++alternative and restores the ordinary syntax of regular expressions; ++an unquoted @samp{[} is special again and a @samp{]} not. ++ ++@node Char Classes ++@subsubsection Character Classes ++@cindex character classes in regexp ++ ++ Here is a table of the classes you can use in a character alternative, ++and what they mean: ++ ++@table @samp ++@item [:ascii:] ++This matches any @acronym{ASCII} character (codes 0--127). ++@item [:alnum:] ++This matches any letter or digit. (At present, for multibyte ++characters, it matches anything that has word syntax.) ++@item [:alpha:] ++This matches any letter. (At present, for multibyte characters, it ++matches anything that has word syntax.) ++@item [:blank:] ++This matches space and tab only. ++@item [:cntrl:] ++This matches any @acronym{ASCII} control character. ++@item [:digit:] ++This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]} ++matches any digit, as well as @samp{+} and @samp{-}. ++@item [:graph:] ++This matches graphic characters---everything except @acronym{ASCII} control ++characters, space, and the delete character. ++@item [:lower:] ++This matches any lower-case letter, as determined by ++the current case table (@pxref{Case Tables}). ++@item [:multibyte:] ++This matches any multibyte character (@pxref{Text Representations}). ++@item [:nonascii:] ++This matches any non-@acronym{ASCII} character. ++@item [:print:] ++This matches printing characters---everything except @acronym{ASCII} control ++characters and the delete character. ++@item [:punct:] ++This matches any punctuation character. (At present, for multibyte ++characters, it matches anything that has non-word syntax.) ++@item [:space:] ++This matches any character that has whitespace syntax ++(@pxref{Syntax Class Table}). ++@item [:unibyte:] ++This matches any unibyte character (@pxref{Text Representations}). ++@item [:upper:] ++This matches any upper-case letter, as determined by ++the current case table (@pxref{Case Tables}). ++@item [:word:] ++This matches any character that has word syntax (@pxref{Syntax Class ++Table}). ++@item [:xdigit:] ++This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a} ++through @samp{f} and @samp{A} through @samp{F}. ++@end table ++ ++@node Regexp Backslash ++@subsubsection Backslash Constructs in Regular Expressions ++ ++ For the most part, @samp{\} followed by any character matches only ++that character. However, there are several exceptions: certain ++two-character sequences starting with @samp{\} that have special ++meanings. (The character after the @samp{\} in such a sequence is ++always ordinary when used on its own.) Here is a table of the special ++@samp{\} constructs. ++ ++@table @samp ++@item \| ++@cindex @samp{|} in regexp ++@cindex regexp alternative ++specifies an alternative. ++Two regular expressions @var{a} and @var{b} with @samp{\|} in ++between form an expression that matches anything that either @var{a} or ++@var{b} matches.@refill ++ ++Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} ++but no other string.@refill ++ ++@samp{\|} applies to the largest possible surrounding expressions. Only a ++surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of ++@samp{\|}.@refill ++ ++If you need full backtracking capability to handle multiple uses of ++@samp{\|}, use the POSIX regular expression functions (@pxref{POSIX ++Regexps}). ++ ++@item \@{@var{m}\@} ++is a postfix operator that repeats the previous pattern exactly @var{m} ++times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx} ++and nothing else. @samp{c[ad]\@{3\@}r} matches string such as ++@samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on. ++ ++@item \@{@var{m},@var{n}\@} ++is a more general postfix operator that specifies repetition with a ++minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m} ++is omitted, the minimum is 0; if @var{n} is omitted, there is no ++maximum. ++ ++For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car}, ++@samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and ++nothing else.@* ++@samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}. @* ++@samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}. @* ++@samp{\@{1,\@}} is equivalent to @samp{+}. ++ ++@item \( @dots{} \) ++@cindex @samp{(} in regexp ++@cindex @samp{)} in regexp ++@cindex regexp grouping ++is a grouping construct that serves three purposes: ++ ++@enumerate ++@item ++To enclose a set of @samp{\|} alternatives for other operations. Thus, ++the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox} ++or @samp{barx}. ++ ++@item ++To enclose a complicated expression for the postfix operators @samp{*}, ++@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches ++@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any ++number (zero or more) of @samp{na} strings. ++ ++@item ++To record a matched substring for future reference with ++@samp{\@var{digit}} (see below). ++@end enumerate ++ ++This last application is not a consequence of the idea of a ++parenthetical grouping; it is a separate feature that was assigned as a ++second meaning to the same @samp{\( @dots{} \)} construct because, in ++practice, there was usually no conflict between the two meanings. But ++occasionally there is a conflict, and that led to the introduction of ++shy groups. ++ ++@item \(?: @dots{} \) ++@cindex shy groups ++@cindex non-capturing group ++@cindex unnumbered group ++@cindex @samp{(?:} in regexp ++is the @dfn{shy group} construct. A shy group serves the first two ++purposes of an ordinary group (controlling the nesting of other ++operators), but it does not get a number, so you cannot refer back to ++its value with @samp{\@var{digit}}. Shy groups are particularly ++useful for mechanically-constructed regular expressions, because they ++can be added automatically without altering the numbering of ordinary, ++non-shy groups. ++ ++Shy groups are also called @dfn{non-capturing} or @dfn{unnumbered ++groups}. ++ ++@item \(?@var{num}: @dots{} \) ++is the @dfn{explicitly numbered group} construct. Normal groups get ++their number implicitly, based on their position, which can be ++inconvenient. This construct allows you to force a particular group ++number. There is no particular restriction on the numbering, ++e.g.@: you can have several groups with the same number in which case ++the last one to match (i.e.@: the rightmost match) will win. ++Implicitly numbered groups always get the smallest integer larger than ++the one of any previous group. ++ ++@item \@var{digit} ++matches the same text that matched the @var{digit}th occurrence of a ++grouping (@samp{\( @dots{} \)}) construct. ++ ++In other words, after the end of a group, the matcher remembers the ++beginning and end of the text matched by that group. Later on in the ++regular expression you can use @samp{\} followed by @var{digit} to ++match that same text, whatever it may have been. ++ ++The strings matching the first nine grouping constructs appearing in ++the entire regular expression passed to a search or matching function ++are assigned numbers 1 through 9 in the order that the open ++parentheses appear in the regular expression. So you can use ++@samp{\1} through @samp{\9} to refer to the text matched by the ++corresponding grouping constructs. ++ ++For example, @samp{\(.*\)\1} matches any newline-free string that is ++composed of two identical halves. The @samp{\(.*\)} matches the first ++half, which may be anything, but the @samp{\1} that follows must match ++the same exact text. ++ ++If a @samp{\( @dots{} \)} construct matches more than once (which can ++happen, for instance, if it is followed by @samp{*}), only the last ++match is recorded. ++ ++If a particular grouping construct in the regular expression was never ++matched---for instance, if it appears inside of an alternative that ++wasn't used, or inside of a repetition that repeated zero times---then ++the corresponding @samp{\@var{digit}} construct never matches ++anything. To use an artificial example, @samp{\(foo\(b*\)\|lose\)\2} ++cannot match @samp{lose}: the second alternative inside the larger ++group matches it, but then @samp{\2} is undefined and can't match ++anything. But it can match @samp{foobb}, because the first ++alternative matches @samp{foob} and @samp{\2} matches @samp{b}. ++ ++@item \w ++@cindex @samp{\w} in regexp ++matches any word-constituent character. The editor syntax table ++determines which characters these are. @xref{Syntax Tables}. ++ ++@item \W ++@cindex @samp{\W} in regexp ++matches any character that is not a word constituent. ++ ++@item \s@var{code} ++@cindex @samp{\s} in regexp ++matches any character whose syntax is @var{code}. Here @var{code} is a ++character that represents a syntax code: thus, @samp{w} for word ++constituent, @samp{-} for whitespace, @samp{(} for open parenthesis, ++etc. To represent whitespace syntax, use either @samp{-} or a space ++character. @xref{Syntax Class Table}, for a list of syntax codes and ++the characters that stand for them. ++ ++@item \S@var{code} ++@cindex @samp{\S} in regexp ++matches any character whose syntax is not @var{code}. ++ ++@item \c@var{c} ++matches any character whose category is @var{c}. Here @var{c} is a ++character that represents a category: thus, @samp{c} for Chinese ++characters or @samp{g} for Greek characters in the standard category ++table. ++ ++@item \C@var{c} ++matches any character whose category is not @var{c}. ++@end table ++ ++ The following regular expression constructs match the empty string---that is, ++they don't use up any characters---but whether they match depends on the ++context. For all, the beginning and end of the accessible portion of ++the buffer are treated as if they were the actual beginning and end of ++the buffer. ++ ++@table @samp ++@item \` ++@cindex @samp{\`} in regexp ++matches the empty string, but only at the beginning ++of the buffer or string being matched against. ++ ++@item \' ++@cindex @samp{\'} in regexp ++matches the empty string, but only at the end of ++the buffer or string being matched against. ++ ++@item \= ++@cindex @samp{\=} in regexp ++matches the empty string, but only at point. ++(This construct is not defined when matching against a string.) ++ ++@item \b ++@cindex @samp{\b} in regexp ++matches the empty string, but only at the beginning or ++end of a word. Thus, @samp{\bfoo\b} matches any occurrence of ++@samp{foo} as a separate word. @samp{\bballs?\b} matches ++@samp{ball} or @samp{balls} as a separate word.@refill ++ ++@samp{\b} matches at the beginning or end of the buffer (or string) ++regardless of what text appears next to it. ++ ++@item \B ++@cindex @samp{\B} in regexp ++matches the empty string, but @emph{not} at the beginning or ++end of a word, nor at the beginning or end of the buffer (or string). ++ ++@item \< ++@cindex @samp{\<} in regexp ++matches the empty string, but only at the beginning of a word. ++@samp{\<} matches at the beginning of the buffer (or string) only if a ++word-constituent character follows. ++ ++@item \> ++@cindex @samp{\>} in regexp ++matches the empty string, but only at the end of a word. @samp{\>} ++matches at the end of the buffer (or string) only if the contents end ++with a word-constituent character. ++ ++@item \_< ++@cindex @samp{\_<} in regexp ++matches the empty string, but only at the beginning of a symbol. A ++symbol is a sequence of one or more word or symbol constituent ++characters. @samp{\_<} matches at the beginning of the buffer (or ++string) only if a symbol-constituent character follows. ++ ++@item \_> ++@cindex @samp{\_>} in regexp ++matches the empty string, but only at the end of a symbol. @samp{\_>} ++matches at the end of the buffer (or string) only if the contents end ++with a symbol-constituent character. ++@end table ++ ++@kindex invalid-regexp ++ Not every string is a valid regular expression. For example, a string ++that ends inside a character alternative without terminating @samp{]} ++is invalid, and so is a string that ends with a single @samp{\}. If ++an invalid regular expression is passed to any of the search functions, ++an @code{invalid-regexp} error is signaled. ++ ++@node Regexp Example ++@comment node-name, next, previous, up ++@subsection Complex Regexp Example ++ ++ Here is a complicated regexp which was formerly used by Emacs to ++recognize the end of a sentence together with any whitespace that ++follows. (Nowadays Emacs uses a similar but more complex default ++regexp constructed by the function @code{sentence-end}. ++@xref{Standard Regexps}.) ++ ++ First, we show the regexp as a string in Lisp syntax to distinguish ++spaces from tab characters. The string constant begins and ends with a ++double-quote. @samp{\"} stands for a double-quote as part of the ++string, @samp{\\} for a backslash as part of the string, @samp{\t} for a ++tab and @samp{\n} for a newline. ++ ++@example ++"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*" ++@end example ++ ++@noindent ++In contrast, if you evaluate this string, you will see the following: ++ ++@example ++@group ++"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*" ++ @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[ ++]*" ++@end group ++@end example ++ ++@noindent ++In this output, tab and newline appear as themselves. ++ ++ This regular expression contains four parts in succession and can be ++deciphered as follows: ++ ++@table @code ++@item [.?!] ++The first part of the pattern is a character alternative that matches ++any one of three characters: period, question mark, and exclamation ++mark. The match must begin with one of these three characters. (This ++is one point where the new default regexp used by Emacs differs from ++the old. The new value also allows some non-@acronym{ASCII} ++characters that end a sentence without any following whitespace.) ++ ++@item []\"')@}]* ++The second part of the pattern matches any closing braces and quotation ++marks, zero or more of them, that may follow the period, question mark ++or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in ++a string. The @samp{*} at the end indicates that the immediately ++preceding regular expression (a character alternative, in this case) may be ++repeated zero or more times. ++ ++@item \\($\\|@ $\\|\t\\|@ @ \\) ++The third part of the pattern matches the whitespace that follows the ++end of a sentence: the end of a line (optionally with a space), or a ++tab, or two spaces. The double backslashes mark the parentheses and ++vertical bars as regular expression syntax; the parentheses delimit a ++group and the vertical bars separate alternatives. The dollar sign is ++used to match the end of a line. ++ ++@item [ \t\n]* ++Finally, the last part of the pattern matches any additional whitespace ++beyond the minimum needed to end a sentence. ++@end table ++ ++@node Regexp Functions ++@subsection Regular Expression Functions ++ ++ These functions operate on regular expressions. ++ ++@defun regexp-quote string ++This function returns a regular expression whose only exact match is ++@var{string}. Using this regular expression in @code{looking-at} will ++succeed only if the next characters in the buffer are @var{string}; ++using it in a search function will succeed if the text being searched ++contains @var{string}. ++ ++This allows you to request an exact string match or search when calling ++a function that wants a regular expression. ++ ++@example ++@group ++(regexp-quote "^The cat$") ++ @result{} "\\^The cat\\$" ++@end group ++@end example ++ ++One use of @code{regexp-quote} is to combine an exact string match with ++context described as a regular expression. For example, this searches ++for the string that is the value of @var{string}, surrounded by ++whitespace: ++ ++@example ++@group ++(re-search-forward ++ (concat "\\s-" (regexp-quote string) "\\s-")) ++@end group ++@end example ++@end defun ++ ++@defun regexp-opt strings &optional paren ++This function returns an efficient regular expression that will match ++any of the strings in the list @var{strings}. This is useful when you ++need to make matching or searching as fast as possible---for example, ++for Font Lock mode. ++ ++If the optional argument @var{paren} is non-@code{nil}, then the ++returned regular expression is always enclosed by at least one ++parentheses-grouping construct. If @var{paren} is @code{words}, then ++that construct is additionally surrounded by @samp{\<} and @samp{\>}. ++ ++This simplified definition of @code{regexp-opt} produces a ++regular expression which is equivalent to the actual value ++(but not as efficient): ++ ++@example ++(defun regexp-opt (strings paren) ++ (let ((open-paren (if paren "\\(" "")) ++ (close-paren (if paren "\\)" ""))) ++ (concat open-paren ++ (mapconcat 'regexp-quote strings "\\|") ++ close-paren))) ++@end example ++@end defun ++ ++@defun regexp-opt-depth regexp ++This function returns the total number of grouping constructs ++(parenthesized expressions) in @var{regexp}. This does not include ++shy groups (@pxref{Regexp Backslash}). ++@end defun ++ ++@node Regexp Search ++@section Regular Expression Searching ++@cindex regular expression searching ++@cindex regexp searching ++@cindex searching for regexp ++ ++ In GNU Emacs, you can search for the next match for a regular ++expression either incrementally or not. For incremental search ++commands, see @ref{Regexp Search, , Regular Expression Search, emacs, ++The GNU Emacs Manual}. Here we describe only the search functions ++useful in programs. The principal one is @code{re-search-forward}. ++ ++ These search functions convert the regular expression to multibyte if ++the buffer is multibyte; they convert the regular expression to unibyte ++if the buffer is unibyte. @xref{Text Representations}. ++ ++@deffn Command re-search-forward regexp &optional limit noerror repeat ++This function searches forward in the current buffer for a string of ++text that is matched by the regular expression @var{regexp}. The ++function skips over any amount of text that is not matched by ++@var{regexp}, and leaves point at the end of the first match found. ++It returns the new value of point. ++ ++If @var{limit} is non-@code{nil}, it must be a position in the current ++buffer. It specifies the upper bound to the search. No match ++extending after that position is accepted. ++ ++If @var{repeat} is supplied, it must be a positive number; the search ++is repeated that many times; each repetition starts at the end of the ++previous match. If all these successive searches succeed, the search ++succeeds, moving point and returning its new value. Otherwise the ++search fails. What @code{re-search-forward} does when the search ++fails depends on the value of @var{noerror}: ++ ++@table @asis ++@item @code{nil} ++Signal a @code{search-failed} error. ++@item @code{t} ++Do nothing and return @code{nil}. ++@item anything else ++Move point to @var{limit} (or the end of the accessible portion of the ++buffer) and return @code{nil}. ++@end table ++ ++In the following example, point is initially before the @samp{T}. ++Evaluating the search call moves point to the end of that line (between ++the @samp{t} of @samp{hat} and the newline). ++ ++@example ++@group ++---------- Buffer: foo ---------- ++I read "@point{}The cat in the hat ++comes back" twice. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(re-search-forward "[a-z]+" nil t 5) ++ @result{} 27 ++ ++---------- Buffer: foo ---------- ++I read "The cat in the hat@point{} ++comes back" twice. ++---------- Buffer: foo ---------- ++@end group ++@end example ++@end deffn ++ ++@deffn Command re-search-backward regexp &optional limit noerror repeat ++This function searches backward in the current buffer for a string of ++text that is matched by the regular expression @var{regexp}, leaving ++point at the beginning of the first text found. ++ ++This function is analogous to @code{re-search-forward}, but they are not ++simple mirror images. @code{re-search-forward} finds the match whose ++beginning is as close as possible to the starting point. If ++@code{re-search-backward} were a perfect mirror image, it would find the ++match whose end is as close as possible. However, in fact it finds the ++match whose beginning is as close as possible (and yet ends before the ++starting point). The reason for this is that matching a regular ++expression at a given spot always works from beginning to end, and ++starts at a specified beginning position. ++ ++A true mirror-image of @code{re-search-forward} would require a special ++feature for matching regular expressions from end to beginning. It's ++not worth the trouble of implementing that. ++@end deffn ++ ++@defun string-match regexp string &optional start ++This function returns the index of the start of the first match for ++the regular expression @var{regexp} in @var{string}, or @code{nil} if ++there is no match. If @var{start} is non-@code{nil}, the search starts ++at that index in @var{string}. ++ ++For example, ++ ++@example ++@group ++(string-match ++ "quick" "The quick brown fox jumped quickly.") ++ @result{} 4 ++@end group ++@group ++(string-match ++ "quick" "The quick brown fox jumped quickly." 8) ++ @result{} 27 ++@end group ++@end example ++ ++@noindent ++The index of the first character of the ++string is 0, the index of the second character is 1, and so on. ++ ++After this function returns, the index of the first character beyond ++the match is available as @code{(match-end 0)}. @xref{Match Data}. ++ ++@example ++@group ++(string-match ++ "quick" "The quick brown fox jumped quickly." 8) ++ @result{} 27 ++@end group ++ ++@group ++(match-end 0) ++ @result{} 32 ++@end group ++@end example ++@end defun ++ ++@defun string-match-p regexp string &optional start ++This predicate function does what @code{string-match} does, but it ++avoids modifying the match data. ++@end defun ++ ++@defun looking-at regexp ++This function determines whether the text in the current buffer directly ++following point matches the regular expression @var{regexp}. ``Directly ++following'' means precisely that: the search is ``anchored'' and it can ++succeed only starting with the first character following point. The ++result is @code{t} if so, @code{nil} otherwise. ++ ++This function does not move point, but it updates the match data, which ++you can access using @code{match-beginning} and @code{match-end}. ++@xref{Match Data}. If you need to test for a match without modifying ++the match data, use @code{looking-at-p}, described below. ++ ++In this example, point is located directly before the @samp{T}. If it ++were anywhere else, the result would be @code{nil}. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++I read "@point{}The cat in the hat ++comes back" twice. ++---------- Buffer: foo ---------- ++ ++(looking-at "The cat in the hat$") ++ @result{} t ++@end group ++@end example ++@end defun ++ ++@defun looking-back regexp &optional limit greedy ++This function returns @code{t} if @var{regexp} matches text before ++point, ending at point, and @code{nil} otherwise. ++ ++Because regular expression matching works only going forward, this is ++implemented by searching backwards from point for a match that ends at ++point. That can be quite slow if it has to search a long distance. ++You can bound the time required by specifying @var{limit}, which says ++not to search before @var{limit}. In this case, the match that is ++found must begin at or after @var{limit}. ++ ++If @var{greedy} is non-@code{nil}, this function extends the match ++backwards as far as possible, stopping when a single additional ++previous character cannot be part of a match for regexp. When the ++match is extended, its starting position is allowed to occur before ++@var{limit}. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++I read "@point{}The cat in the hat ++comes back" twice. ++---------- Buffer: foo ---------- ++ ++(looking-back "read \"" 3) ++ @result{} t ++(looking-back "read \"" 4) ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun looking-at-p regexp ++This predicate function works like @code{looking-at}, but without ++updating the match data. ++@end defun ++ ++@defvar search-spaces-regexp ++If this variable is non-@code{nil}, it should be a regular expression ++that says how to search for whitespace. In that case, any group of ++spaces in a regular expression being searched for stands for use of ++this regular expression. However, spaces inside of constructs such as ++@samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by ++@code{search-spaces-regexp}. ++ ++Since this variable affects all regular expression search and match ++constructs, you should bind it temporarily for as small as possible ++a part of the code. ++@end defvar ++ ++@node POSIX Regexps ++@section POSIX Regular Expression Searching ++ ++ The usual regular expression functions do backtracking when necessary ++to handle the @samp{\|} and repetition constructs, but they continue ++this only until they find @emph{some} match. Then they succeed and ++report the first match found. ++ ++ This section describes alternative search functions which perform the ++full backtracking specified by the POSIX standard for regular expression ++matching. They continue backtracking until they have tried all ++possibilities and found all matches, so they can report the longest ++match, as required by POSIX. This is much slower, so use these ++functions only when you really need the longest match. ++ ++ The POSIX search and match functions do not properly support the ++non-greedy repetition operators (@pxref{Regexp Special, non-greedy}). ++This is because POSIX backtracking conflicts with the semantics of ++non-greedy repetition. ++ ++@deffn Command posix-search-forward regexp &optional limit noerror repeat ++This is like @code{re-search-forward} except that it performs the full ++backtracking specified by the POSIX standard for regular expression ++matching. ++@end deffn ++ ++@deffn Command posix-search-backward regexp &optional limit noerror repeat ++This is like @code{re-search-backward} except that it performs the full ++backtracking specified by the POSIX standard for regular expression ++matching. ++@end deffn ++ ++@defun posix-looking-at regexp ++This is like @code{looking-at} except that it performs the full ++backtracking specified by the POSIX standard for regular expression ++matching. ++@end defun ++ ++@defun posix-string-match regexp string &optional start ++This is like @code{string-match} except that it performs the full ++backtracking specified by the POSIX standard for regular expression ++matching. ++@end defun ++ ++@node Match Data ++@section The Match Data ++@cindex match data ++ ++ Emacs keeps track of the start and end positions of the segments of ++text found during a search; this is called the @dfn{match data}. ++Thanks to the match data, you can search for a complex pattern, such ++as a date in a mail message, and then extract parts of the match under ++control of the pattern. ++ ++ Because the match data normally describe the most recent search only, ++you must be careful not to do another search inadvertently between the ++search you wish to refer back to and the use of the match data. If you ++can't avoid another intervening search, you must save and restore the ++match data around it, to prevent it from being overwritten. ++ ++@menu ++* Replacing Match:: Replacing a substring that was matched. ++* Simple Match Data:: Accessing single items of match data, ++ such as where a particular subexpression started. ++* Entire Match Data:: Accessing the entire match data at once, as a list. ++* Saving Match Data:: Saving and restoring the match data. ++@end menu ++ ++@node Replacing Match ++@subsection Replacing the Text that Matched ++@cindex replace matched text ++ ++ This function replaces all or part of the text matched by the last ++search. It works by means of the match data. ++ ++@cindex case in replacements ++@defun replace-match replacement &optional fixedcase literal string subexp ++This function replaces the text in the buffer (or in @var{string}) that ++was matched by the last search. It replaces that text with ++@var{replacement}. ++ ++If you did the last search in a buffer, you should specify @code{nil} ++for @var{string} and make sure that the current buffer when you call ++@code{replace-match} is the one in which you did the searching or ++matching. Then @code{replace-match} does the replacement by editing ++the buffer; it leaves point at the end of the replacement text, and ++returns @code{t}. ++ ++If you did the search in a string, pass the same string as @var{string}. ++Then @code{replace-match} does the replacement by constructing and ++returning a new string. ++ ++If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses ++the replacement text without case conversion; otherwise, it converts ++the replacement text depending upon the capitalization of the text to ++be replaced. If the original text is all upper case, this converts ++the replacement text to upper case. If all words of the original text ++are capitalized, this capitalizes all the words of the replacement ++text. If all the words are one-letter and they are all upper case, ++they are treated as capitalized words rather than all-upper-case ++words. ++ ++If @var{literal} is non-@code{nil}, then @var{replacement} is inserted ++exactly as it is, the only alterations being case changes as needed. ++If it is @code{nil} (the default), then the character @samp{\} is treated ++specially. If a @samp{\} appears in @var{replacement}, then it must be ++part of one of the following sequences: ++ ++@table @asis ++@item @samp{\&} ++@cindex @samp{&} in replacement ++@samp{\&} stands for the entire text being replaced. ++ ++@item @samp{\@var{n}} ++@cindex @samp{\@var{n}} in replacement ++@samp{\@var{n}}, where @var{n} is a digit, stands for the text that ++matched the @var{n}th subexpression in the original regexp. ++Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}. ++If the @var{n}th subexpression never matched, an empty string is substituted. ++ ++@item @samp{\\} ++@cindex @samp{\} in replacement ++@samp{\\} stands for a single @samp{\} in the replacement text. ++@end table ++ ++These substitutions occur after case conversion, if any, ++so the strings they substitute are never case-converted. ++ ++If @var{subexp} is non-@code{nil}, that says to replace just ++subexpression number @var{subexp} of the regexp that was matched, not ++the entire match. For example, after matching @samp{foo \(ba*r\)}, ++calling @code{replace-match} with 1 as @var{subexp} means to replace ++just the text that matched @samp{\(ba*r\)}. ++@end defun ++ ++@defun match-substitute-replacement replacement &optional fixedcase literal string subexp ++This function returns the text that would be inserted into the buffer ++by @code{replace-match}, but without modifying the buffer. It is ++useful if you want to present the user with actual replacement result, ++with constructs like @samp{\@var{n}} or @samp{\&} substituted with ++matched groups. Arguments @var{replacement} and optional ++@var{fixedcase}, @var{literal}, @var{string} and @var{subexp} have the ++same meaning as for @code{replace-match}. ++@end defun ++ ++@node Simple Match Data ++@subsection Simple Match Data Access ++ ++ This section explains how to use the match data to find out what was ++matched by the last search or match operation, if it succeeded. ++ ++ You can ask about the entire matching text, or about a particular ++parenthetical subexpression of a regular expression. The @var{count} ++argument in the functions below specifies which. If @var{count} is ++zero, you are asking about the entire match. If @var{count} is ++positive, it specifies which subexpression you want. ++ ++ Recall that the subexpressions of a regular expression are those ++expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The ++@var{count}th subexpression is found by counting occurrences of ++@samp{\(} from the beginning of the whole regular expression. The first ++subexpression is numbered 1, the second 2, and so on. Only regular ++expressions can have subexpressions---after a simple string search, the ++only information available is about the entire match. ++ ++ Every successful search sets the match data. Therefore, you should ++query the match data immediately after searching, before calling any ++other function that might perform another search. Alternatively, you ++may save and restore the match data (@pxref{Saving Match Data}) around ++the call to functions that could perform another search. ++ ++ A search which fails may or may not alter the match data. In the ++past, a failing search did not do this, but we may change it in the ++future. So don't try to rely on the value of the match data after ++a failing search. ++ ++@defun match-string count &optional in-string ++This function returns, as a string, the text matched in the last search ++or match operation. It returns the entire text if @var{count} is zero, ++or just the portion corresponding to the @var{count}th parenthetical ++subexpression, if @var{count} is positive. ++ ++If the last such operation was done against a string with ++@code{string-match}, then you should pass the same string as the ++argument @var{in-string}. After a buffer search or match, ++you should omit @var{in-string} or pass @code{nil} for it; but you ++should make sure that the current buffer when you call ++@code{match-string} is the one in which you did the searching or ++matching. ++ ++The value is @code{nil} if @var{count} is out of range, or for a ++subexpression inside a @samp{\|} alternative that wasn't used or a ++repetition that repeated zero times. ++@end defun ++ ++@defun match-string-no-properties count &optional in-string ++This function is like @code{match-string} except that the result ++has no text properties. ++@end defun ++ ++@defun match-beginning count ++This function returns the position of the start of text matched by the ++last regular expression searched for, or a subexpression of it. ++ ++If @var{count} is zero, then the value is the position of the start of ++the entire match. Otherwise, @var{count} specifies a subexpression in ++the regular expression, and the value of the function is the starting ++position of the match for that subexpression. ++ ++The value is @code{nil} for a subexpression inside a @samp{\|} ++alternative that wasn't used or a repetition that repeated zero times. ++@end defun ++ ++@defun match-end count ++This function is like @code{match-beginning} except that it returns the ++position of the end of the match, rather than the position of the ++beginning. ++@end defun ++ ++ Here is an example of using the match data, with a comment showing the ++positions within the text: ++ ++@example ++@group ++(string-match "\\(qu\\)\\(ick\\)" ++ "The quick fox jumped quickly.") ++ ;0123456789 ++ @result{} 4 ++@end group ++ ++@group ++(match-string 0 "The quick fox jumped quickly.") ++ @result{} "quick" ++(match-string 1 "The quick fox jumped quickly.") ++ @result{} "qu" ++(match-string 2 "The quick fox jumped quickly.") ++ @result{} "ick" ++@end group ++ ++@group ++(match-beginning 1) ; @r{The beginning of the match} ++ @result{} 4 ; @r{with @samp{qu} is at index 4.} ++@end group ++ ++@group ++(match-beginning 2) ; @r{The beginning of the match} ++ @result{} 6 ; @r{with @samp{ick} is at index 6.} ++@end group ++ ++@group ++(match-end 1) ; @r{The end of the match} ++ @result{} 6 ; @r{with @samp{qu} is at index 6.} ++ ++(match-end 2) ; @r{The end of the match} ++ @result{} 9 ; @r{with @samp{ick} is at index 9.} ++@end group ++@end example ++ ++ Here is another example. Point is initially located at the beginning ++of the line. Searching moves point to between the space and the word ++@samp{in}. The beginning of the entire match is at the 9th character of ++the buffer (@samp{T}), and the beginning of the match for the first ++subexpression is at the 13th character (@samp{c}). ++ ++@example ++@group ++(list ++ (re-search-forward "The \\(cat \\)") ++ (match-beginning 0) ++ (match-beginning 1)) ++ @result{} (17 9 13) ++@end group ++ ++@group ++---------- Buffer: foo ---------- ++I read "The cat @point{}in the hat comes back" twice. ++ ^ ^ ++ 9 13 ++---------- Buffer: foo ---------- ++@end group ++@end example ++ ++@noindent ++(In this case, the index returned is a buffer position; the first ++character of the buffer counts as 1.) ++ ++@node Entire Match Data ++@subsection Accessing the Entire Match Data ++ ++ The functions @code{match-data} and @code{set-match-data} read or ++write the entire match data, all at once. ++ ++@defun match-data &optional integers reuse reseat ++This function returns a list of positions (markers or integers) that ++record all the information on what text the last search matched. ++Element zero is the position of the beginning of the match for the ++whole expression; element one is the position of the end of the match ++for the expression. The next two elements are the positions of the ++beginning and end of the match for the first subexpression, and so on. ++In general, element ++@ifnottex ++number 2@var{n} ++@end ifnottex ++@tex ++number {\mathsurround=0pt $2n$} ++@end tex ++corresponds to @code{(match-beginning @var{n})}; and ++element ++@ifnottex ++number 2@var{n} + 1 ++@end ifnottex ++@tex ++number {\mathsurround=0pt $2n+1$} ++@end tex ++corresponds to @code{(match-end @var{n})}. ++ ++Normally all the elements are markers or @code{nil}, but if ++@var{integers} is non-@code{nil}, that means to use integers instead ++of markers. (In that case, the buffer itself is appended as an ++additional element at the end of the list, to facilitate complete ++restoration of the match data.) If the last match was done on a ++string with @code{string-match}, then integers are always used, ++since markers can't point into a string. ++ ++If @var{reuse} is non-@code{nil}, it should be a list. In that case, ++@code{match-data} stores the match data in @var{reuse}. That is, ++@var{reuse} is destructively modified. @var{reuse} does not need to ++have the right length. If it is not long enough to contain the match ++data, it is extended. If it is too long, the length of @var{reuse} ++stays the same, but the elements that were not used are set to ++@code{nil}. The purpose of this feature is to reduce the need for ++garbage collection. ++ ++If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list ++are reseated to point to nowhere. ++ ++As always, there must be no possibility of intervening searches between ++the call to a search function and the call to @code{match-data} that is ++intended to access the match data for that search. ++ ++@example ++@group ++(match-data) ++ @result{} (# ++ # ++ # ++ #) ++@end group ++@end example ++@end defun ++ ++@defun set-match-data match-list &optional reseat ++This function sets the match data from the elements of @var{match-list}, ++which should be a list that was the value of a previous call to ++@code{match-data}. (More precisely, anything that has the same format ++will work.) ++ ++If @var{match-list} refers to a buffer that doesn't exist, you don't get ++an error; that sets the match data in a meaningless but harmless way. ++ ++If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list ++are reseated to point to nowhere. ++ ++@findex store-match-data ++@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}. ++@end defun ++ ++@node Saving Match Data ++@subsection Saving and Restoring the Match Data ++ ++ When you call a function that may do a search, you may need to save ++and restore the match data around that call, if you want to preserve the ++match data from an earlier search for later use. Here is an example ++that shows the problem that arises if you fail to save the match data: ++ ++@example ++@group ++(re-search-forward "The \\(cat \\)") ++ @result{} 48 ++(foo) ; @r{Perhaps @code{foo} does} ++ ; @r{more searching.} ++(match-end 0) ++ @result{} 61 ; @r{Unexpected result---not 48!} ++@end group ++@end example ++ ++ You can save and restore the match data with @code{save-match-data}: ++ ++@defmac save-match-data body@dots{} ++This macro executes @var{body}, saving and restoring the match ++data around it. The return value is the value of the last form in ++@var{body}. ++@end defmac ++ ++ You could use @code{set-match-data} together with @code{match-data} to ++imitate the effect of the special form @code{save-match-data}. Here is ++how: ++ ++@example ++@group ++(let ((data (match-data))) ++ (unwind-protect ++ @dots{} ; @r{Ok to change the original match data.} ++ (set-match-data data))) ++@end group ++@end example ++ ++ Emacs automatically saves and restores the match data when it runs ++process filter functions (@pxref{Filter Functions}) and process ++sentinels (@pxref{Sentinels}). ++ ++@ignore ++ Here is a function which restores the match data provided the buffer ++associated with it still exists. ++ ++@smallexample ++@group ++(defun restore-match-data (data) ++@c It is incorrect to split the first line of a doc string. ++@c If there's a problem here, it should be solved in some other way. ++ "Restore the match data DATA unless the buffer is missing." ++ (catch 'foo ++ (let ((d data)) ++@end group ++ (while d ++ (and (car d) ++ (null (marker-buffer (car d))) ++@group ++ ;; @file{match-data} @r{buffer is deleted.} ++ (throw 'foo nil)) ++ (setq d (cdr d))) ++ (set-match-data data)))) ++@end group ++@end smallexample ++@end ignore ++ ++@node Search and Replace ++@section Search and Replace ++@cindex replacement after search ++@cindex searching and replacing ++ ++ If you want to find all matches for a regexp in part of the buffer, ++and replace them, the best way is to write an explicit loop using ++@code{re-search-forward} and @code{replace-match}, like this: ++ ++@example ++(while (re-search-forward "foo[ \t]+bar" nil t) ++ (replace-match "foobar")) ++@end example ++ ++@noindent ++@xref{Replacing Match,, Replacing the Text that Matched}, for a ++description of @code{replace-match}. ++ ++ However, replacing matches in a string is more complex, especially ++if you want to do it efficiently. So Emacs provides a function to do ++this. ++ ++@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start ++This function copies @var{string} and searches it for matches for ++@var{regexp}, and replaces them with @var{rep}. It returns the ++modified copy. If @var{start} is non-@code{nil}, the search for ++matches starts at that index in @var{string}, so matches starting ++before that index are not changed. ++ ++This function uses @code{replace-match} to do the replacement, and it ++passes the optional arguments @var{fixedcase}, @var{literal} and ++@var{subexp} along to @code{replace-match}. ++ ++Instead of a string, @var{rep} can be a function. In that case, ++@code{replace-regexp-in-string} calls @var{rep} for each match, ++passing the text of the match as its sole argument. It collects the ++value @var{rep} returns and passes that to @code{replace-match} as the ++replacement string. The match-data at this point are the result ++of matching @var{regexp} against a substring of @var{string}. ++@end defun ++ ++ If you want to write a command along the lines of @code{query-replace}, ++you can use @code{perform-replace} to do the work. ++ ++@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end ++This function is the guts of @code{query-replace} and related ++commands. It searches for occurrences of @var{from-string} in the ++text between positions @var{start} and @var{end} and replaces some or ++all of them. If @var{start} is @code{nil} (or omitted), point is used ++instead, and the end of the buffer's accessible portion is used for ++@var{end}. ++ ++If @var{query-flag} is @code{nil}, it replaces all ++occurrences; otherwise, it asks the user what to do about each one. ++ ++If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is ++considered a regular expression; otherwise, it must match literally. If ++@var{delimited-flag} is non-@code{nil}, then only replacements ++surrounded by word boundaries are considered. ++ ++The argument @var{replacements} specifies what to replace occurrences ++with. If it is a string, that string is used. It can also be a list of ++strings, to be used in cyclic order. ++ ++If @var{replacements} is a cons cell, @w{@code{(@var{function} ++. @var{data})}}, this means to call @var{function} after each match to ++get the replacement text. This function is called with two arguments: ++@var{data}, and the number of replacements already made. ++ ++If @var{repeat-count} is non-@code{nil}, it should be an integer. Then ++it specifies how many times to use each of the strings in the ++@var{replacements} list before advancing cyclically to the next one. ++ ++If @var{from-string} contains upper-case letters, then ++@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and ++it uses the @code{replacements} without altering the case of them. ++ ++Normally, the keymap @code{query-replace-map} defines the possible ++user responses for queries. The argument @var{map}, if ++non-@code{nil}, specifies a keymap to use instead of ++@code{query-replace-map}. ++ ++This function uses one of two functions to search for the next ++occurrence of @var{from-string}. These functions are specified by the ++values of two variables: @code{replace-re-search-function} and ++@code{replace-search-function}. The former is called when the ++argument @var{regexp-flag} is non-@code{nil}, the latter when it is ++@code{nil}. ++@end defun ++ ++@defvar query-replace-map ++This variable holds a special keymap that defines the valid user ++responses for @code{perform-replace} and the commands that use it, as ++well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual ++in two ways: ++ ++@itemize @bullet ++@item ++The ``key bindings'' are not commands, just symbols that are meaningful ++to the functions that use this map. ++ ++@item ++Prefix keys are not supported; each key binding must be for a ++single-event key sequence. This is because the functions don't use ++@code{read-key-sequence} to get the input; instead, they read a single ++event and look it up ``by hand.'' ++@end itemize ++@end defvar ++ ++Here are the meaningful ``bindings'' for @code{query-replace-map}. ++Several of them are meaningful only for @code{query-replace} and ++friends. ++ ++@table @code ++@item act ++Do take the action being considered---in other words, ``yes.'' ++ ++@item skip ++Do not take action for this question---in other words, ``no.'' ++ ++@item exit ++Answer this question ``no,'' and give up on the entire series of ++questions, assuming that the answers will be ``no.'' ++ ++@item act-and-exit ++Answer this question ``yes,'' and give up on the entire series of ++questions, assuming that subsequent answers will be ``no.'' ++ ++@item act-and-show ++Answer this question ``yes,'' but show the results---don't advance yet ++to the next question. ++ ++@item automatic ++Answer this question and all subsequent questions in the series with ++``yes,'' without further user interaction. ++ ++@item backup ++Move back to the previous place that a question was asked about. ++ ++@item edit ++Enter a recursive edit to deal with this question---instead of any ++other action that would normally be taken. ++ ++@item delete-and-edit ++Delete the text being considered, then enter a recursive edit to replace ++it. ++ ++@item recenter ++Redisplay and center the window, then ask the same question again. ++ ++@item quit ++Perform a quit right away. Only @code{y-or-n-p} and related functions ++use this answer. ++ ++@item help ++Display some help, then ask again. ++@end table ++ ++@defvar multi-query-replace-map ++This variable holds a keymap that extends @code{query-replace-map} by ++providing additional keybindings that are useful in multi-buffer ++replacements. ++@end defvar ++ ++@defvar replace-search-function ++This variable specifies a function that @code{perform-replace} calls ++to search for the next string to replace. Its default value is ++@code{search-forward}. Any other value should name a function of 3 ++arguments: the first 3 arguments of @code{search-forward} ++(@pxref{String Search}). ++@end defvar ++ ++@defvar replace-re-search-function ++This variable specifies a function that @code{perform-replace} calls ++to search for the next regexp to replace. Its default value is ++@code{re-search-forward}. Any other value should name a function of 3 ++arguments: the first 3 arguments of @code{re-search-forward} ++(@pxref{Regexp Search}). ++@end defvar ++ ++@node Standard Regexps ++@section Standard Regular Expressions Used in Editing ++@cindex regexps used standardly in editing ++@cindex standard regexps used in editing ++ ++ This section describes some variables that hold regular expressions ++used for certain purposes in editing: ++ ++@defopt page-delimiter ++This is the regular expression describing line-beginnings that separate ++pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or ++@code{"^\C-l"}); this matches a line that starts with a formfeed ++character. ++@end defopt ++ ++ The following two regular expressions should @emph{not} assume the ++match always starts at the beginning of a line; they should not use ++@samp{^} to anchor the match. Most often, the paragraph commands do ++check for a match only at the beginning of a line, which means that ++@samp{^} would be superfluous. When there is a nonzero left margin, ++they accept matches that start after the left margin. In that case, a ++@samp{^} would be incorrect. However, a @samp{^} is harmless in modes ++where a left margin is never used. ++ ++@defopt paragraph-separate ++This is the regular expression for recognizing the beginning of a line ++that separates paragraphs. (If you change this, you may have to ++change @code{paragraph-start} also.) The default value is ++@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of ++spaces, tabs, and form feeds (after its left margin). ++@end defopt ++ ++@defopt paragraph-start ++This is the regular expression for recognizing the beginning of a line ++that starts @emph{or} separates paragraphs. The default value is ++@w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only ++whitespace or starting with a form feed (after its left margin). ++@end defopt ++ ++@defopt sentence-end ++If non-@code{nil}, the value should be a regular expression describing ++the end of a sentence, including the whitespace following the ++sentence. (All paragraph boundaries also end sentences, regardless.) ++ ++If the value is @code{nil}, the default, then the function ++@code{sentence-end} has to construct the regexp. That is why you ++should always call the function @code{sentence-end} to obtain the ++regexp to be used to recognize the end of a sentence. ++@end defopt ++ ++@defun sentence-end ++This function returns the value of the variable @code{sentence-end}, ++if non-@code{nil}. Otherwise it returns a default value based on the ++values of the variables @code{sentence-end-double-space} ++(@pxref{Definition of sentence-end-double-space}), ++@code{sentence-end-without-period} and ++@code{sentence-end-without-space}. ++@end defun ++ ++@ignore ++ arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f ++@end ignore +diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi +new file mode 100644 +index 0000000..0827ff0 +--- /dev/null ++++ b/doc/lispref/sequences.texi +@@ -0,0 +1,734 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/sequences ++@node Sequences Arrays Vectors, Hash Tables, Lists, Top ++@chapter Sequences, Arrays, and Vectors ++@cindex sequence ++ ++ Recall that the @dfn{sequence} type is the union of two other Lisp ++types: lists and arrays. In other words, any list is a sequence, and ++any array is a sequence. The common property that all sequences have is ++that each is an ordered collection of elements. ++ ++ An @dfn{array} is a fixed-length object with a slot for each of its ++elements. All the elements are accessible in constant time. The four ++types of arrays are strings, vectors, char-tables and bool-vectors. ++ ++ A list is a sequence of elements, but it is not a single primitive ++object; it is made of cons cells, one cell per element. Finding the ++@var{n}th element requires looking through @var{n} cons cells, so ++elements farther from the beginning of the list take longer to access. ++But it is possible to add elements to the list, or remove elements. ++ ++ The following diagram shows the relationship between these types: ++ ++@example ++@group ++ _____________________________________________ ++ | | ++ | Sequence | ++ | ______ ________________________________ | ++ | | | | | | ++ | | List | | Array | | ++ | | | | ________ ________ | | ++ | |______| | | | | | | | ++ | | | Vector | | String | | | ++ | | |________| |________| | | ++ | | ____________ _____________ | | ++ | | | | | | | | ++ | | | Char-table | | Bool-vector | | | ++ | | |____________| |_____________| | | ++ | |________________________________| | ++ |_____________________________________________| ++@end group ++@end example ++ ++@menu ++* Sequence Functions:: Functions that accept any kind of sequence. ++* Arrays:: Characteristics of arrays in Emacs Lisp. ++* Array Functions:: Functions specifically for arrays. ++* Vectors:: Special characteristics of Emacs Lisp vectors. ++* Vector Functions:: Functions specifically for vectors. ++* Char-Tables:: How to work with char-tables. ++* Bool-Vectors:: How to work with bool-vectors. ++@end menu ++ ++@node Sequence Functions ++@section Sequences ++ ++ In Emacs Lisp, a @dfn{sequence} is either a list or an array. The ++common property of all sequences is that they are ordered collections of ++elements. This section describes functions that accept any kind of ++sequence. ++ ++@defun sequencep object ++Returns @code{t} if @var{object} is a list, vector, string, ++bool-vector, or char-table, @code{nil} otherwise. ++@end defun ++ ++@defun length sequence ++@cindex string length ++@cindex list length ++@cindex vector length ++@cindex sequence length ++@cindex char-table length ++This function returns the number of elements in @var{sequence}. If ++@var{sequence} is a dotted list, a @code{wrong-type-argument} error is ++signaled. Circular lists may cause an infinite loop. For a ++char-table, the value returned is always one more than the maximum ++Emacs character code. ++ ++@xref{Definition of safe-length}, for the related function @code{safe-length}. ++ ++@example ++@group ++(length '(1 2 3)) ++ @result{} 3 ++@end group ++@group ++(length ()) ++ @result{} 0 ++@end group ++@group ++(length "foobar") ++ @result{} 6 ++@end group ++@group ++(length [1 2 3]) ++ @result{} 3 ++@end group ++@group ++(length (make-bool-vector 5 nil)) ++ @result{} 5 ++@end group ++@end example ++@end defun ++ ++@noindent ++See also @code{string-bytes}, in @ref{Text Representations}. ++ ++@defun elt sequence index ++@cindex elements of sequences ++This function returns the element of @var{sequence} indexed by ++@var{index}. Legitimate values of @var{index} are integers ranging ++from 0 up to one less than the length of @var{sequence}. If ++@var{sequence} is a list, out-of-range values behave as for ++@code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values ++trigger an @code{args-out-of-range} error. ++ ++@example ++@group ++(elt [1 2 3 4] 2) ++ @result{} 3 ++@end group ++@group ++(elt '(1 2 3 4) 2) ++ @result{} 3 ++@end group ++@group ++;; @r{We use @code{string} to show clearly which character @code{elt} returns.} ++(string (elt "1234" 2)) ++ @result{} "3" ++@end group ++@group ++(elt [1 2 3 4] 4) ++ @error{} Args out of range: [1 2 3 4], 4 ++@end group ++@group ++(elt [1 2 3 4] -1) ++ @error{} Args out of range: [1 2 3 4], -1 ++@end group ++@end example ++ ++This function generalizes @code{aref} (@pxref{Array Functions}) and ++@code{nth} (@pxref{Definition of nth}). ++@end defun ++ ++@defun copy-sequence sequence ++@cindex copying sequences ++Returns a copy of @var{sequence}. The copy is the same type of object ++as the original sequence, and it has the same elements in the same order. ++ ++Storing a new element into the copy does not affect the original ++@var{sequence}, and vice versa. However, the elements of the new ++sequence are not copies; they are identical (@code{eq}) to the elements ++of the original. Therefore, changes made within these elements, as ++found via the copied sequence, are also visible in the original ++sequence. ++ ++If the sequence is a string with text properties, the property list in ++the copy is itself a copy, not shared with the original's property ++list. However, the actual values of the properties are shared. ++@xref{Text Properties}. ++ ++This function does not work for dotted lists. Trying to copy a ++circular list may cause an infinite loop. ++ ++See also @code{append} in @ref{Building Lists}, @code{concat} in ++@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions}, ++for other ways to copy sequences. ++ ++@example ++@group ++(setq bar '(1 2)) ++ @result{} (1 2) ++@end group ++@group ++(setq x (vector 'foo bar)) ++ @result{} [foo (1 2)] ++@end group ++@group ++(setq y (copy-sequence x)) ++ @result{} [foo (1 2)] ++@end group ++ ++@group ++(eq x y) ++ @result{} nil ++@end group ++@group ++(equal x y) ++ @result{} t ++@end group ++@group ++(eq (elt x 1) (elt y 1)) ++ @result{} t ++@end group ++ ++@group ++;; @r{Replacing an element of one sequence.} ++(aset x 0 'quux) ++x @result{} [quux (1 2)] ++y @result{} [foo (1 2)] ++@end group ++ ++@group ++;; @r{Modifying the inside of a shared element.} ++(setcar (aref x 1) 69) ++x @result{} [quux (69 2)] ++y @result{} [foo (69 2)] ++@end group ++@end example ++@end defun ++ ++@node Arrays ++@section Arrays ++@cindex array ++ ++ An @dfn{array} object has slots that hold a number of other Lisp ++objects, called the elements of the array. Any element of an array ++may be accessed in constant time. In contrast, the time to access an ++element of a list is proportional to the position of that element in ++the list. ++ ++ Emacs defines four types of array, all one-dimensional: ++@dfn{strings} (@pxref{String Type}), @dfn{vectors} (@pxref{Vector ++Type}), @dfn{bool-vectors} (@pxref{Bool-Vector Type}), and ++@dfn{char-tables} (@pxref{Char-Table Type}). Vectors and char-tables ++can hold elements of any type, but strings can only hold characters, ++and bool-vectors can only hold @code{t} and @code{nil}. ++ ++ All four kinds of array share these characteristics: ++ ++@itemize @bullet ++@item ++The first element of an array has index zero, the second element has ++index 1, and so on. This is called @dfn{zero-origin} indexing. For ++example, an array of four elements has indices 0, 1, 2, @w{and 3}. ++ ++@item ++The length of the array is fixed once you create it; you cannot ++change the length of an existing array. ++ ++@item ++For purposes of evaluation, the array is a constant---in other words, ++it evaluates to itself. ++ ++@item ++The elements of an array may be referenced or changed with the functions ++@code{aref} and @code{aset}, respectively (@pxref{Array Functions}). ++@end itemize ++ ++ When you create an array, other than a char-table, you must specify ++its length. You cannot specify the length of a char-table, because that ++is determined by the range of character codes. ++ ++ In principle, if you want an array of text characters, you could use ++either a string or a vector. In practice, we always choose strings for ++such applications, for four reasons: ++ ++@itemize @bullet ++@item ++They occupy one-fourth the space of a vector of the same elements. ++ ++@item ++Strings are printed in a way that shows the contents more clearly ++as text. ++ ++@item ++Strings can hold text properties. @xref{Text Properties}. ++ ++@item ++Many of the specialized editing and I/O facilities of Emacs accept only ++strings. For example, you cannot insert a vector of characters into a ++buffer the way you can insert a string. @xref{Strings and Characters}. ++@end itemize ++ ++ By contrast, for an array of keyboard input characters (such as a key ++sequence), a vector may be necessary, because many keyboard input ++characters are outside the range that will fit in a string. @xref{Key ++Sequence Input}. ++ ++@node Array Functions ++@section Functions that Operate on Arrays ++ ++ In this section, we describe the functions that accept all types of ++arrays. ++ ++@defun arrayp object ++This function returns @code{t} if @var{object} is an array (i.e., a ++vector, a string, a bool-vector or a char-table). ++ ++@example ++@group ++(arrayp [a]) ++ @result{} t ++(arrayp "asdf") ++ @result{} t ++(arrayp (syntax-table)) ;; @r{A char-table.} ++ @result{} t ++@end group ++@end example ++@end defun ++ ++@defun aref array index ++@cindex array elements ++This function returns the @var{index}th element of @var{array}. The ++first element is at index zero. ++ ++@example ++@group ++(setq primes [2 3 5 7 11 13]) ++ @result{} [2 3 5 7 11 13] ++(aref primes 4) ++ @result{} 11 ++@end group ++@group ++(aref "abcdefg" 1) ++ @result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.} ++@end group ++@end example ++ ++See also the function @code{elt}, in @ref{Sequence Functions}. ++@end defun ++ ++@defun aset array index object ++This function sets the @var{index}th element of @var{array} to be ++@var{object}. It returns @var{object}. ++ ++@example ++@group ++(setq w [foo bar baz]) ++ @result{} [foo bar baz] ++(aset w 0 'fu) ++ @result{} fu ++w ++ @result{} [fu bar baz] ++@end group ++ ++@group ++(setq x "asdfasfd") ++ @result{} "asdfasfd" ++(aset x 3 ?Z) ++ @result{} 90 ++x ++ @result{} "asdZasfd" ++@end group ++@end example ++ ++If @var{array} is a string and @var{object} is not a character, a ++@code{wrong-type-argument} error results. The function converts a ++unibyte string to multibyte if necessary to insert a character. ++@end defun ++ ++@defun fillarray array object ++This function fills the array @var{array} with @var{object}, so that ++each element of @var{array} is @var{object}. It returns @var{array}. ++ ++@example ++@group ++(setq a [a b c d e f g]) ++ @result{} [a b c d e f g] ++(fillarray a 0) ++ @result{} [0 0 0 0 0 0 0] ++a ++ @result{} [0 0 0 0 0 0 0] ++@end group ++@group ++(setq s "When in the course") ++ @result{} "When in the course" ++(fillarray s ?-) ++ @result{} "------------------" ++@end group ++@end example ++ ++If @var{array} is a string and @var{object} is not a character, a ++@code{wrong-type-argument} error results. ++@end defun ++ ++The general sequence functions @code{copy-sequence} and @code{length} ++are often useful for objects known to be arrays. @xref{Sequence Functions}. ++ ++@node Vectors ++@section Vectors ++@cindex vector (type) ++ ++ A @dfn{vector} is a general-purpose array whose elements can be any ++Lisp objects. (By contrast, the elements of a string can only be ++characters. @xref{Strings and Characters}.) Vectors are used in ++Emacs for many purposes: as key sequences (@pxref{Key Sequences}), as ++symbol-lookup tables (@pxref{Creating Symbols}), as part of the ++representation of a byte-compiled function (@pxref{Byte Compilation}), ++and more. ++ ++ In Emacs Lisp, the indices of the elements of a vector start from zero ++and count up from there. ++ ++ Vectors are printed with square brackets surrounding the elements. ++Thus, a vector whose elements are the symbols @code{a}, @code{b} and ++@code{a} is printed as @code{[a b a]}. You can write vectors in the ++same way in Lisp input. ++ ++ A vector, like a string or a number, is considered a constant for ++evaluation: the result of evaluating it is the same vector. This does ++not evaluate or even examine the elements of the vector. ++@xref{Self-Evaluating Forms}. ++ ++ Here are examples illustrating these principles: ++ ++@example ++@group ++(setq avector [1 two '(three) "four" [five]]) ++ @result{} [1 two (quote (three)) "four" [five]] ++(eval avector) ++ @result{} [1 two (quote (three)) "four" [five]] ++(eq avector (eval avector)) ++ @result{} t ++@end group ++@end example ++ ++@node Vector Functions ++@section Functions for Vectors ++ ++ Here are some functions that relate to vectors: ++ ++@defun vectorp object ++This function returns @code{t} if @var{object} is a vector. ++ ++@example ++@group ++(vectorp [a]) ++ @result{} t ++(vectorp "asdf") ++ @result{} nil ++@end group ++@end example ++@end defun ++ ++@defun vector &rest objects ++This function creates and returns a vector whose elements are the ++arguments, @var{objects}. ++ ++@example ++@group ++(vector 'foo 23 [bar baz] "rats") ++ @result{} [foo 23 [bar baz] "rats"] ++(vector) ++ @result{} [] ++@end group ++@end example ++@end defun ++ ++@defun make-vector length object ++This function returns a new vector consisting of @var{length} elements, ++each initialized to @var{object}. ++ ++@example ++@group ++(setq sleepy (make-vector 9 'Z)) ++ @result{} [Z Z Z Z Z Z Z Z Z] ++@end group ++@end example ++@end defun ++ ++@defun vconcat &rest sequences ++@cindex copying vectors ++This function returns a new vector containing all the elements of ++@var{sequences}. The arguments @var{sequences} may be true lists, ++vectors, strings or bool-vectors. If no @var{sequences} are given, an ++empty vector is returned. ++ ++The value is a newly constructed vector that is not @code{eq} to any ++existing vector. ++ ++@example ++@group ++(setq a (vconcat '(A B C) '(D E F))) ++ @result{} [A B C D E F] ++(eq a (vconcat a)) ++ @result{} nil ++@end group ++@group ++(vconcat) ++ @result{} [] ++(vconcat [A B C] "aa" '(foo (6 7))) ++ @result{} [A B C 97 97 foo (6 7)] ++@end group ++@end example ++ ++The @code{vconcat} function also allows byte-code function objects as ++arguments. This is a special feature to make it easy to access the entire ++contents of a byte-code function object. @xref{Byte-Code Objects}. ++ ++For other concatenation functions, see @code{mapconcat} in @ref{Mapping ++Functions}, @code{concat} in @ref{Creating Strings}, and @code{append} ++in @ref{Building Lists}. ++@end defun ++ ++ The @code{append} function also provides a way to convert a vector into a ++list with the same elements: ++ ++@example ++@group ++(setq avector [1 two (quote (three)) "four" [five]]) ++ @result{} [1 two (quote (three)) "four" [five]] ++(append avector nil) ++ @result{} (1 two (quote (three)) "four" [five]) ++@end group ++@end example ++ ++@node Char-Tables ++@section Char-Tables ++@cindex char-tables ++@cindex extra slots of char-table ++ ++ A char-table is much like a vector, except that it is indexed by ++character codes. Any valid character code, without modifiers, can be ++used as an index in a char-table. You can access a char-table's ++elements with @code{aref} and @code{aset}, as with any array. In ++addition, a char-table can have @dfn{extra slots} to hold additional ++data not associated with particular character codes. Like vectors, ++char-tables are constants when evaluated, and can hold elements of any ++type. ++ ++@cindex subtype of char-table ++ Each char-table has a @dfn{subtype}, a symbol, which serves two ++purposes: ++ ++@itemize @bullet ++@item ++The subtype provides an easy way to tell what the char-table is for. ++For instance, display tables are char-tables with @code{display-table} ++as the subtype, and syntax tables are char-tables with ++@code{syntax-table} as the subtype. The subtype can be queried using ++the function @code{char-table-subtype}, described below. ++ ++@item ++The subtype controls the number of @dfn{extra slots} in the ++char-table. This number is specified by the subtype's ++@code{char-table-extra-slots} symbol property, which should be an ++integer between 0 and 10. If the subtype has no such symbol property, ++the char-table has no extra slots. @xref{Property Lists}, for ++information about symbol properties. ++@end itemize ++ ++@cindex parent of char-table ++ A char-table can have a @dfn{parent}, which is another char-table. If ++it does, then whenever the char-table specifies @code{nil} for a ++particular character @var{c}, it inherits the value specified in the ++parent. In other words, @code{(aref @var{char-table} @var{c})} returns ++the value from the parent of @var{char-table} if @var{char-table} itself ++specifies @code{nil}. ++ ++@cindex default value of char-table ++ A char-table can also have a @dfn{default value}. If so, then ++@code{(aref @var{char-table} @var{c})} returns the default value ++whenever the char-table does not specify any other non-@code{nil} value. ++ ++@defun make-char-table subtype &optional init ++Return a newly-created char-table, with subtype @var{subtype} (a ++symbol). Each element is initialized to @var{init}, which defaults to ++@code{nil}. You cannot alter the subtype of a char-table after the ++char-table is created. ++ ++There is no argument to specify the length of the char-table, because ++all char-tables have room for any valid character code as an index. ++ ++If @var{subtype} has the @code{char-table-extra-slots} symbol ++property, that specifies the number of extra slots in the char-table. ++This should be an integer between 0 and 10; otherwise, ++@code{make-char-table} raises an error. If @var{subtype} has no ++@code{char-table-extra-slots} symbol property (@pxref{Property ++Lists}), the char-table has no extra slots. ++@end defun ++ ++@defun char-table-p object ++This function returns @code{t} if @var{object} is a char-table, and ++@code{nil} otherwise. ++@end defun ++ ++@defun char-table-subtype char-table ++This function returns the subtype symbol of @var{char-table}. ++@end defun ++ ++There is no special function to access default values in a char-table. ++To do that, use @code{char-table-range} (see below). ++ ++@defun char-table-parent char-table ++This function returns the parent of @var{char-table}. The parent is ++always either @code{nil} or another char-table. ++@end defun ++ ++@defun set-char-table-parent char-table new-parent ++This function sets the parent of @var{char-table} to @var{new-parent}. ++@end defun ++ ++@defun char-table-extra-slot char-table n ++This function returns the contents of extra slot @var{n} of ++@var{char-table}. The number of extra slots in a char-table is ++determined by its subtype. ++@end defun ++ ++@defun set-char-table-extra-slot char-table n value ++This function stores @var{value} in extra slot @var{n} of ++@var{char-table}. ++@end defun ++ ++ A char-table can specify an element value for a single character code; ++it can also specify a value for an entire character set. ++ ++@defun char-table-range char-table range ++This returns the value specified in @var{char-table} for a range of ++characters @var{range}. Here are the possibilities for @var{range}: ++ ++@table @asis ++@item @code{nil} ++Refers to the default value. ++ ++@item @var{char} ++Refers to the element for character @var{char} ++(supposing @var{char} is a valid character code). ++ ++@item @code{(@var{from} . @var{to})} ++A cons cell refers to all the characters in the inclusive range ++@samp{[@var{from}..@var{to}]}. ++@end table ++@end defun ++ ++@defun set-char-table-range char-table range value ++This function sets the value in @var{char-table} for a range of ++characters @var{range}. Here are the possibilities for @var{range}: ++ ++@table @asis ++@item @code{nil} ++Refers to the default value. ++ ++@item @code{t} ++Refers to the whole range of character codes. ++ ++@item @var{char} ++Refers to the element for character @var{char} ++(supposing @var{char} is a valid character code). ++ ++@item @code{(@var{from} . @var{to})} ++A cons cell refers to all the characters in the inclusive range ++@samp{[@var{from}..@var{to}]}. ++@end table ++@end defun ++ ++@defun map-char-table function char-table ++This function calls its argument @var{function} for each element of ++@var{char-table} that has a non-@code{nil} value. The call to ++@var{function} is with two arguments, a key and a value. The key ++is a possible @var{range} argument for @code{char-table-range}---either ++a valid character or a cons cell @code{(@var{from} . @var{to})}, ++specifying a range of characters that share the same value. The value is ++what @code{(char-table-range @var{char-table} @var{key})} returns. ++ ++Overall, the key-value pairs passed to @var{function} describe all the ++values stored in @var{char-table}. ++ ++The return value is always @code{nil}; to make calls to ++@code{map-char-table} useful, @var{function} should have side effects. ++For example, here is how to examine the elements of the syntax table: ++ ++@example ++(let (accumulator) ++ (map-char-table ++ #'(lambda (key value) ++ (setq accumulator ++ (cons (list ++ (if (consp key) ++ (list (car key) (cdr key)) ++ key) ++ value) ++ accumulator))) ++ (syntax-table)) ++ accumulator) ++@result{} ++(((2597602 4194303) (2)) ((2597523 2597601) (3)) ++ ... (65379 (5 . 65378)) (65378 (4 . 65379)) (65377 (1)) ++ ... (12 (0)) (11 (3)) (10 (12)) (9 (0)) ((0 8) (3))) ++@end example ++@end defun ++ ++@node Bool-Vectors ++@section Bool-vectors ++@cindex Bool-vectors ++ ++ A bool-vector is much like a vector, except that it stores only the ++values @code{t} and @code{nil}. If you try to store any non-@code{nil} ++value into an element of the bool-vector, the effect is to store ++@code{t} there. As with all arrays, bool-vector indices start from 0, ++and the length cannot be changed once the bool-vector is created. ++Bool-vectors are constants when evaluated. ++ ++ There are two special functions for working with bool-vectors; aside ++from that, you manipulate them with same functions used for other kinds ++of arrays. ++ ++@defun make-bool-vector length initial ++Return a new bool-vector of @var{length} elements, ++each one initialized to @var{initial}. ++@end defun ++ ++@defun bool-vector-p object ++This returns @code{t} if @var{object} is a bool-vector, ++and @code{nil} otherwise. ++@end defun ++ ++ Here is an example of creating, examining, and updating a ++bool-vector. Note that the printed form represents up to 8 boolean ++values as a single character. ++ ++@example ++(setq bv (make-bool-vector 5 t)) ++ @result{} #&5"^_" ++(aref bv 1) ++ @result{} t ++(aset bv 3 nil) ++ @result{} nil ++bv ++ @result{} #&5"^W" ++@end example ++ ++@noindent ++These results make sense because the binary codes for control-_ and ++control-W are 11111 and 10111, respectively. ++ ++@ignore ++ arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386 ++@end ignore +diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile +new file mode 100644 +index 0000000..b373d00 +--- /dev/null ++++ b/doc/lispref/spellfile +@@ -0,0 +1,738 @@ ++ARPA ++Abbrev ++Acknowledgements ++Alan ++Arnold ++Autoloading ++BAppend ++Backquote ++Beeping ++Beverly ++Boyes ++Brian ++CL ++CSWKg ++Carl ++Carroll ++Chris ++Cleanups ++DEC ++DStandard ++Dan ++Dired's ++Disassembly ++Duff ++EMAC ++EMACSLOADPATH ++Eckelkamp ++Edward ++Eirik ++Emacses ++Eric ++Erlebacher ++Fcar ++Fcdr ++Fcons ++Fcoordinates ++Feval ++Frazzle ++Frederick ++Fri ++Gardiner ++Gentlemen ++HAL ++HATTED ++HS ++HU ++Hanchrow ++Hartzell ++Hess ++Hewlett ++IBM ++ISBN ++Impl ++Interning ++Ithought ++J's ++Jacobson ++Jak ++Joe ++Jones ++Jr ++Jul ++Keymaps ++Kimmo ++Kirman ++Knighten ++Korz ++Krawitz ++LTsHm ++LaLiberte ++LaTeX ++Lammens ++Local' ++MAC ++MONIES ++MSS ++Maclisp ++Magill ++Marick ++Matthew ++Minibuf ++Misc ++Miscellany ++Mocklisp ++Montanaro ++Myers ++NFS ++Nathan ++Nope ++OS ++OSITIONS ++Oct ++Ovwrt ++PURESIZE ++Packard ++Qlistp ++Qnil ++RMAIL ++Raul ++Resizing ++Robbins ++Rockwell ++SCO ++SIGCONT ++SIGHUP ++SIGINT ++SIGKILL ++SIGQUIT ++SIGTSTP ++SLOAD ++Scoordinates ++Set' ++Setcar ++Setcdr ++Shinichirou ++Snarf ++Sor ++SourceFile ++Stops' ++Subprocess ++Sugou ++Sunview ++Suominen ++T's ++TCP ++ThXs ++Tharp ++Thu ++Trost ++UCB ++UNEVALLED ++UNGCPRO ++UniPlus ++UniSoft's ++VMS ++Vip ++Void' ++Warren ++Welty ++Wethought ++Wilding ++Worley ++Wright ++XDVI ++XFASTINT ++XINT ++XWINDOW ++Xs ++Yo ++Zuhn ++aB ++aa ++aaa ++abbrevname ++abbrevs ++abc ++abcdefg ++abcxyz ++abd ++above' ++abracadabra ++address' ++after' ++alist ++alists ++anchored' ++and' ++ar ++aref ++arg'th ++argdecl ++arith ++arrayp ++arrow' ++asa ++asdZasfd ++asdf ++asdfasfd ++aset ++assoc ++assq ++at' ++aug ++autoload ++automatic' ++automatically' ++avector ++bBuffer ++bFrobnicate ++ba ++back' ++bananana ++barfoo ++barx ++bballs ++before' ++beforep ++bfoo ++bil ++binding's ++bish ++bobp ++bolp ++bottommost ++boundp ++brief' ++buf ++buffer' ++bufferp ++buttercup ++ca ++caaaar ++caaar ++caddaar ++cadr ++callable ++cbreak ++ce ++cell' ++cells' ++cf ++chaprm ++character' ++childp ++chistory ++ck ++column' ++commandp ++concat ++cond ++conses ++consing ++consp ++constant' ++contains' ++continuable ++convert' ++copyleft ++correct' ++counterintuitive ++cr ++creatable ++customie ++deactivate ++deactivated ++deassigns ++decrement' ++deffnx ++definition' ++defmacro ++defsubr ++deletable ++deletion' ++delq ++depiction ++descendents ++deselecting ++destructive' ++destructively' ++diffs ++ding ++directory' ++dired ++dirname ++disassembler ++dland ++docfile ++docstring ++doesnt ++dont ++down' ++downcasing ++downloadable ++dribble ++dup ++ef ++efg ++electric' ++elided ++elt ++enablement ++endkeyfun ++endrecfun ++environment' ++eobp ++eof ++eol ++eolp ++eq ++eqlsign ++erminal ++erste ++etags ++eval ++evalled ++evals ++evaluate' ++excess' ++exec ++exitcode ++expression' ++extendible ++extra' ++fails' ++fascist ++fboundp ++featurep ++ff ++fg ++fi ++file' ++filespec ++filesystems ++fillarray ++firstchar ++firstonly ++fixedcase ++fixit ++fixup ++floatp ++fmakunbound ++fns ++fo ++fol ++folded' ++following' ++fooba ++foobaz ++foox ++for' ++formfeed ++forms' ++forw ++forwa ++found' ++frob ++from' ++front' ++fset ++fstab ++ftp ++fu ++funtions ++garbles ++gc ++gcpro ++gd ++getenv ++getprv ++gid ++gnuemacs ++gp ++grep ++gtr ++halves' ++hand' ++hashes' ++hd ++hexadecimal ++hf ++hfil ++hookvar ++horsechestnut ++hostname ++hpux ++hscroll ++ibmapa ++ick ++id ++idiom ++ii ++indrm ++inode ++input' ++inputinput ++inserting' ++integerp ++intermixed ++ints ++inturned ++irreversibly ++jum ++keymapp ++kill' ++killed' ++killp ++kludge ++kolstad ++language' ++lastchar ++lcl ++ledit ++leif ++lessp ++level' ++lewis ++library' ++link' ++lisplib ++listexp ++loadable ++loadst ++loadup ++logand ++logior ++lognot ++logxor ++long' ++loop's ++lru ++lrwxrwxrwx ++ls ++lsh ++m's ++macroexpand ++makunbound ++malloc ++mapatoms ++mapconcat ++mapvar ++mark' ++marker's ++markerp ++mathsurround ++medit ++memq ++mh ++mim ++mini ++minibuffer's ++minibuffers ++misalignment ++misnamed ++mode's ++modename ++modes' ++mods ++modtime ++mqueue ++msg ++multicharacter ++myfile ++nCount ++nXExpression ++na ++name's ++natnump ++nb ++nbBuffer ++nconc ++newdef ++newelt ++newname ++nextrecfun ++nfsusr ++ninett ++nlines ++nlinks ++nlistp ++noconfirm ++nodigits ++noerror ++noforce ++nomessage ++nominees ++nomsg ++nonblank ++nonconstant ++nondestructive ++nondirectory ++nonidentical ++noninteractive ++noninteractively ++nonletter ++nonletters ++nonlocally ++nonoverlapping ++nonprinting ++nonselected ++nonsequentially ++nonvoid ++nonwarranty ++nonwritable ++noop ++noprint ++norecord ++normal' ++noselect ++nosuffix ++nots ++noundo ++nr ++nreverse ++ns ++nsRename ++nth ++nthcdr ++num ++number' ++numberp ++nums ++obarray ++obarrays ++object' ++oldbuf ++olddef ++oldname ++oo ++oops ++op ++or' ++otl ++out' ++over' ++overful ++overfullrule ++overstrike ++overstriking ++overstruck ++p' ++paren ++part' ++passwd ++pe ++ped ++perverse ++pid ++plist ++pnt ++pointer' ++pointm ++pos ++preallocate ++predicale ++preload ++prepend ++prepended ++prepends ++pretty' ++prin ++princ ++print' ++printenv ++printer' ++proc ++process' ++processp ++programmer' ++prolog ++protect' ++ps ++psf ++psychotherapy ++pty ++purecopy ++qu ++quux ++rassq ++reader' ++readin ++rebind ++rec ++rechecking ++recursively' ++recycler' ++redo ++redrawing ++redraws ++redump ++reenabled ++reexposed ++reg ++region' ++reindent ++reindents ++reinitialization ++reinitialize ++reinitialized ++reinstall ++reinstalled ++resize ++resized ++resizes ++reversibly ++reworded ++rhetorical ++right' ++ring' ++risky ++rmailedit ++rms ++rplaca ++rplacd ++rtu ++runnable ++rw ++rwxrwxrwx ++sDescribe ++sans ++se ++searching' ++section' ++seed' ++sequence' ++sequencep ++setp ++setplist ++setprv ++settable ++setuid ++sexp ++sexps ++shape' ++shell's ++sideline ++special' ++specpdl ++st ++stanford ++startkeyfun ++str ++stringp ++stty ++subcategories ++subcommands ++subexp ++subform ++subforms ++subjob ++submap ++subprocesses ++subr ++subr' ++subroutine' ++subrp ++subrs ++subwindows ++sugar' ++suid ++supersession ++suspension' ++symbolp ++symlink ++syms ++syntatic ++tabname ++temacs ++temporarily' ++tempvar ++tenths ++termcap ++termcaps ++terminfo ++termscript ++termtype ++terpri ++text' ++textrm ++textsl ++texttt ++than' ++the' ++tildes ++time's ++to' ++towars ++transportable ++txt ++types' ++uid ++unbind ++unbinding ++unbinds ++unchanged' ++unclutters ++undefine ++undefines ++underfull ++undo's ++undodata ++unevaluated' ++unexec ++unexpand ++unhesitatingly ++uninterned ++unisoft ++unpaired ++unread ++unreadable ++unreading ++unsaved ++untyped ++ununderline ++up' ++uptime ++usecount ++used' ++user' ++userlock ++usg ++val ++varbind ++varname ++varref ++vars ++varset ++vb ++vconcat ++vectorp ++vfil ++vi ++vn ++voidness ++vrs ++vt ++window' ++windowing ++windowp ++wrapped' ++xSpecify ++xcoord ++xcssun ++xemacs ++xenix ++xf ++xfirst ++xoff ++xon ++xx ++xxxxx ++xxxxxxxxx ++xy ++xyz ++ycoord ++yes' ++zA ++zap ++zerop +diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi +new file mode 100644 +index 0000000..1e7d533 +--- /dev/null ++++ b/doc/lispref/streams.texi +@@ -0,0 +1,843 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/streams ++@node Read and Print, Minibuffers, Debugging, Top ++@comment node-name, next, previous, up ++@chapter Reading and Printing Lisp Objects ++ ++ @dfn{Printing} and @dfn{reading} are the operations of converting Lisp ++objects to textual form and vice versa. They use the printed ++representations and read syntax described in @ref{Lisp Data Types}. ++ ++ This chapter describes the Lisp functions for reading and printing. ++It also describes @dfn{streams}, which specify where to get the text (if ++reading) or where to put it (if printing). ++ ++@menu ++* Streams Intro:: Overview of streams, reading and printing. ++* Input Streams:: Various data types that can be used as input streams. ++* Input Functions:: Functions to read Lisp objects from text. ++* Output Streams:: Various data types that can be used as output streams. ++* Output Functions:: Functions to print Lisp objects as text. ++* Output Variables:: Variables that control what the printing functions do. ++@end menu ++ ++@node Streams Intro ++@section Introduction to Reading and Printing ++@cindex Lisp reader ++@cindex printing ++@cindex reading ++ ++ @dfn{Reading} a Lisp object means parsing a Lisp expression in textual ++form and producing a corresponding Lisp object. This is how Lisp ++programs get into Lisp from files of Lisp code. We call the text the ++@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)} ++is the read syntax for a cons cell whose @sc{car} is @code{a} and whose ++@sc{cdr} is the number 5. ++ ++ @dfn{Printing} a Lisp object means producing text that represents that ++object---converting the object to its @dfn{printed representation} ++(@pxref{Printed Representation}). Printing the cons cell described ++above produces the text @samp{(a .@: 5)}. ++ ++ Reading and printing are more or less inverse operations: printing the ++object that results from reading a given piece of text often produces ++the same text, and reading the text that results from printing an object ++usually produces a similar-looking object. For example, printing the ++symbol @code{foo} produces the text @samp{foo}, and reading that text ++returns the symbol @code{foo}. Printing a list whose elements are ++@code{a} and @code{b} produces the text @samp{(a b)}, and reading that ++text produces a list (but not the same list) with elements @code{a} ++and @code{b}. ++ ++ However, these two operations are not precisely inverse to each other. ++There are three kinds of exceptions: ++ ++@itemize @bullet ++@item ++Printing can produce text that cannot be read. For example, buffers, ++windows, frames, subprocesses and markers print as text that starts ++with @samp{#}; if you try to read this text, you get an error. There is ++no way to read those data types. ++ ++@item ++One object can have multiple textual representations. For example, ++@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and ++@samp{(a .@: (b))} represent the same list. Reading will accept any of ++the alternatives, but printing must choose one of them. ++ ++@item ++Comments can appear at certain points in the middle of an object's ++read sequence without affecting the result of reading it. ++@end itemize ++ ++@node Input Streams ++@section Input Streams ++@cindex stream (for reading) ++@cindex input stream ++ ++ Most of the Lisp functions for reading text take an @dfn{input stream} ++as an argument. The input stream specifies where or how to get the ++characters of the text to be read. Here are the possible types of input ++stream: ++ ++@table @asis ++@item @var{buffer} ++@cindex buffer input stream ++The input characters are read from @var{buffer}, starting with the ++character directly after point. Point advances as characters are read. ++ ++@item @var{marker} ++@cindex marker input stream ++The input characters are read from the buffer that @var{marker} is in, ++starting with the character directly after the marker. The marker ++position advances as characters are read. The value of point in the ++buffer has no effect when the stream is a marker. ++ ++@item @var{string} ++@cindex string input stream ++The input characters are taken from @var{string}, starting at the first ++character in the string and using as many characters as required. ++ ++@item @var{function} ++@cindex function input stream ++The input characters are generated by @var{function}, which must support ++two kinds of calls: ++ ++@itemize @bullet ++@item ++When it is called with no arguments, it should return the next character. ++ ++@item ++When it is called with one argument (always a character), @var{function} ++should save the argument and arrange to return it on the next call. ++This is called @dfn{unreading} the character; it happens when the Lisp ++reader reads one character too many and wants to ``put it back where it ++came from.'' In this case, it makes no difference what value ++@var{function} returns. ++@end itemize ++ ++@item @code{t} ++@cindex @code{t} input stream ++@code{t} used as a stream means that the input is read from the ++minibuffer. In fact, the minibuffer is invoked once and the text ++given by the user is made into a string that is then used as the ++input stream. If Emacs is running in batch mode, standard input is used ++instead of the minibuffer. For example, ++@example ++(message "%s" (read t)) ++@end example ++will read a Lisp expression from standard input and print the result ++to standard output. ++ ++@item @code{nil} ++@cindex @code{nil} input stream ++@code{nil} supplied as an input stream means to use the value of ++@code{standard-input} instead; that value is the @dfn{default input ++stream}, and must be a non-@code{nil} input stream. ++ ++@item @var{symbol} ++A symbol as input stream is equivalent to the symbol's function ++definition (if any). ++@end table ++ ++ Here is an example of reading from a stream that is a buffer, showing ++where point is located before and after: ++ ++@example ++@group ++---------- Buffer: foo ---------- ++This@point{} is the contents of foo. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(read (get-buffer "foo")) ++ @result{} is ++@end group ++@group ++(read (get-buffer "foo")) ++ @result{} the ++@end group ++ ++@group ++---------- Buffer: foo ---------- ++This is the@point{} contents of foo. ++---------- Buffer: foo ---------- ++@end group ++@end example ++ ++@noindent ++Note that the first read skips a space. Reading skips any amount of ++whitespace preceding the significant text. ++ ++ Here is an example of reading from a stream that is a marker, ++initially positioned at the beginning of the buffer shown. The value ++read is the symbol @code{This}. ++ ++@example ++@group ++ ++---------- Buffer: foo ---------- ++This is the contents of foo. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(setq m (set-marker (make-marker) 1 (get-buffer "foo"))) ++ @result{} # ++@end group ++@group ++(read m) ++ @result{} This ++@end group ++@group ++m ++ @result{} # ;; @r{Before the first space.} ++@end group ++@end example ++ ++ Here we read from the contents of a string: ++ ++@example ++@group ++(read "(When in) the course") ++ @result{} (When in) ++@end group ++@end example ++ ++ The following example reads from the minibuffer. The ++prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt ++used when you read from the stream @code{t}.) The user's input is shown ++following the prompt. ++ ++@example ++@group ++(read t) ++ @result{} 23 ++---------- Buffer: Minibuffer ---------- ++Lisp expression: @kbd{23 @key{RET}} ++---------- Buffer: Minibuffer ---------- ++@end group ++@end example ++ ++ Finally, here is an example of a stream that is a function, named ++@code{useless-stream}. Before we use the stream, we initialize the ++variable @code{useless-list} to a list of characters. Then each call to ++the function @code{useless-stream} obtains the next character in the list ++or unreads a character by adding it to the front of the list. ++ ++@example ++@group ++(setq useless-list (append "XY()" nil)) ++ @result{} (88 89 40 41) ++@end group ++ ++@group ++(defun useless-stream (&optional unread) ++ (if unread ++ (setq useless-list (cons unread useless-list)) ++ (prog1 (car useless-list) ++ (setq useless-list (cdr useless-list))))) ++ @result{} useless-stream ++@end group ++@end example ++ ++@noindent ++Now we read using the stream thus constructed: ++ ++@example ++@group ++(read 'useless-stream) ++ @result{} XY ++@end group ++ ++@group ++useless-list ++ @result{} (40 41) ++@end group ++@end example ++ ++@noindent ++Note that the open and close parentheses remain in the list. The Lisp ++reader encountered the open parenthesis, decided that it ended the ++input, and unread it. Another attempt to read from the stream at this ++point would read @samp{()} and return @code{nil}. ++ ++@defun get-file-char ++This function is used internally as an input stream to read from the ++input file opened by the function @code{load}. Don't use this function ++yourself. ++@end defun ++ ++@node Input Functions ++@section Input Functions ++ ++ This section describes the Lisp functions and variables that pertain ++to reading. ++ ++ In the functions below, @var{stream} stands for an input stream (see ++the previous section). If @var{stream} is @code{nil} or omitted, it ++defaults to the value of @code{standard-input}. ++ ++@kindex end-of-file ++ An @code{end-of-file} error is signaled if reading encounters an ++unterminated list, vector, or string. ++ ++@defun read &optional stream ++This function reads one textual Lisp expression from @var{stream}, ++returning it as a Lisp object. This is the basic Lisp input function. ++@end defun ++ ++@defun read-from-string string &optional start end ++@cindex string to object ++This function reads the first textual Lisp expression from the text in ++@var{string}. It returns a cons cell whose @sc{car} is that expression, ++and whose @sc{cdr} is an integer giving the position of the next ++remaining character in the string (i.e., the first one not read). ++ ++If @var{start} is supplied, then reading begins at index @var{start} in ++the string (where the first character is at index 0). If you specify ++@var{end}, then reading is forced to stop just before that index, as if ++the rest of the string were not there. ++ ++For example: ++ ++@example ++@group ++(read-from-string "(setq x 55) (setq y 5)") ++ @result{} ((setq x 55) . 11) ++@end group ++@group ++(read-from-string "\"A short string\"") ++ @result{} ("A short string" . 16) ++@end group ++ ++@group ++;; @r{Read starting at the first character.} ++(read-from-string "(list 112)" 0) ++ @result{} ((list 112) . 10) ++@end group ++@group ++;; @r{Read starting at the second character.} ++(read-from-string "(list 112)" 1) ++ @result{} (list . 5) ++@end group ++@group ++;; @r{Read starting at the seventh character,} ++;; @r{and stopping at the ninth.} ++(read-from-string "(list 112)" 6 8) ++ @result{} (11 . 8) ++@end group ++@end example ++@end defun ++ ++@defvar standard-input ++This variable holds the default input stream---the stream that ++@code{read} uses when the @var{stream} argument is @code{nil}. ++The default is @code{t}, meaning use the minibuffer. ++@end defvar ++ ++@defvar read-circle ++If non-@code{nil}, this variable enables the reading of circular and ++shared structures. @xref{Circular Objects}. Its default value is ++@code{t}. ++@end defvar ++ ++@node Output Streams ++@section Output Streams ++@cindex stream (for printing) ++@cindex output stream ++ ++ An output stream specifies what to do with the characters produced ++by printing. Most print functions accept an output stream as an ++optional argument. Here are the possible types of output stream: ++ ++@table @asis ++@item @var{buffer} ++@cindex buffer output stream ++The output characters are inserted into @var{buffer} at point. ++Point advances as characters are inserted. ++ ++@item @var{marker} ++@cindex marker output stream ++The output characters are inserted into the buffer that @var{marker} ++points into, at the marker position. The marker position advances as ++characters are inserted. The value of point in the buffer has no effect ++on printing when the stream is a marker, and this kind of printing ++does not move point (except that if the marker points at or before the ++position of point, point advances with the surrounding text, as ++usual). ++ ++@item @var{function} ++@cindex function output stream ++The output characters are passed to @var{function}, which is responsible ++for storing them away. It is called with a single character as ++argument, as many times as there are characters to be output, and ++is responsible for storing the characters wherever you want to put them. ++ ++@item @code{t} ++@cindex @code{t} output stream ++The output characters are displayed in the echo area. ++ ++@item @code{nil} ++@cindex @code{nil} output stream ++@code{nil} specified as an output stream means to use the value of ++@code{standard-output} instead; that value is the @dfn{default output ++stream}, and must not be @code{nil}. ++ ++@item @var{symbol} ++A symbol as output stream is equivalent to the symbol's function ++definition (if any). ++@end table ++ ++ Many of the valid output streams are also valid as input streams. The ++difference between input and output streams is therefore more a matter ++of how you use a Lisp object, than of different types of object. ++ ++ Here is an example of a buffer used as an output stream. Point is ++initially located as shown immediately before the @samp{h} in ++@samp{the}. At the end, point is located directly before that same ++@samp{h}. ++ ++@cindex print example ++@example ++@group ++---------- Buffer: foo ---------- ++This is t@point{}he contents of foo. ++---------- Buffer: foo ---------- ++@end group ++ ++(print "This is the output" (get-buffer "foo")) ++ @result{} "This is the output" ++ ++@group ++---------- Buffer: foo ---------- ++This is t ++"This is the output" ++@point{}he contents of foo. ++---------- Buffer: foo ---------- ++@end group ++@end example ++ ++ Now we show a use of a marker as an output stream. Initially, the ++marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in ++the word @samp{the}. At the end, the marker has advanced over the ++inserted text so that it remains positioned before the same @samp{h}. ++Note that the location of point, shown in the usual fashion, has no ++effect. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++This is the @point{}output ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(setq m (copy-marker 10)) ++ @result{} # ++@end group ++ ++@group ++(print "More output for foo." m) ++ @result{} "More output for foo." ++@end group ++ ++@group ++---------- Buffer: foo ---------- ++This is t ++"More output for foo." ++he @point{}output ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++m ++ @result{} # ++@end group ++@end example ++ ++ The following example shows output to the echo area: ++ ++@example ++@group ++(print "Echo Area output" t) ++ @result{} "Echo Area output" ++---------- Echo Area ---------- ++"Echo Area output" ++---------- Echo Area ---------- ++@end group ++@end example ++ ++ Finally, we show the use of a function as an output stream. The ++function @code{eat-output} takes each character that it is given and ++conses it onto the front of the list @code{last-output} (@pxref{Building ++Lists}). At the end, the list contains all the characters output, but ++in reverse order. ++ ++@example ++@group ++(setq last-output nil) ++ @result{} nil ++@end group ++ ++@group ++(defun eat-output (c) ++ (setq last-output (cons c last-output))) ++ @result{} eat-output ++@end group ++ ++@group ++(print "This is the output" 'eat-output) ++ @result{} "This is the output" ++@end group ++ ++@group ++last-output ++ @result{} (10 34 116 117 112 116 117 111 32 101 104 ++ 116 32 115 105 32 115 105 104 84 34 10) ++@end group ++@end example ++ ++@noindent ++Now we can put the output in the proper order by reversing the list: ++ ++@example ++@group ++(concat (nreverse last-output)) ++ @result{} " ++\"This is the output\" ++" ++@end group ++@end example ++ ++@noindent ++Calling @code{concat} converts the list to a string so you can see its ++contents more clearly. ++ ++@node Output Functions ++@section Output Functions ++ ++ This section describes the Lisp functions for printing Lisp ++objects---converting objects into their printed representation. ++ ++@cindex @samp{"} in printing ++@cindex @samp{\} in printing ++@cindex quoting characters in printing ++@cindex escape characters in printing ++ Some of the Emacs printing functions add quoting characters to the ++output when necessary so that it can be read properly. The quoting ++characters used are @samp{"} and @samp{\}; they distinguish strings from ++symbols, and prevent punctuation characters in strings and symbols from ++being taken as delimiters when reading. @xref{Printed Representation}, ++for full details. You specify quoting or no quoting by the choice of ++printing function. ++ ++ If the text is to be read back into Lisp, then you should print with ++quoting characters to avoid ambiguity. Likewise, if the purpose is to ++describe a Lisp object clearly for a Lisp programmer. However, if the ++purpose of the output is to look nice for humans, then it is usually ++better to print without quoting. ++ ++ Lisp objects can refer to themselves. Printing a self-referential ++object in the normal way would require an infinite amount of text, and ++the attempt could cause infinite recursion. Emacs detects such ++recursion and prints @samp{#@var{level}} instead of recursively printing ++an object already being printed. For example, here @samp{#0} indicates ++a recursive reference to the object at level 0 of the current print ++operation: ++ ++@example ++(setq foo (list nil)) ++ @result{} (nil) ++(setcar foo foo) ++ @result{} (#0) ++@end example ++ ++ In the functions below, @var{stream} stands for an output stream. ++(See the previous section for a description of output streams.) If ++@var{stream} is @code{nil} or omitted, it defaults to the value of ++@code{standard-output}. ++ ++@defun print object &optional stream ++@cindex Lisp printer ++The @code{print} function is a convenient way of printing. It outputs ++the printed representation of @var{object} to @var{stream}, printing in ++addition one newline before @var{object} and another after it. Quoting ++characters are used. @code{print} returns @var{object}. For example: ++ ++@example ++@group ++(progn (print 'The\ cat\ in) ++ (print "the hat") ++ (print " came back")) ++ @print{} ++ @print{} The\ cat\ in ++ @print{} ++ @print{} "the hat" ++ @print{} ++ @print{} " came back" ++ @result{} " came back" ++@end group ++@end example ++@end defun ++ ++@defun prin1 object &optional stream ++This function outputs the printed representation of @var{object} to ++@var{stream}. It does not print newlines to separate output as ++@code{print} does, but it does use quoting characters just like ++@code{print}. It returns @var{object}. ++ ++@example ++@group ++(progn (prin1 'The\ cat\ in) ++ (prin1 "the hat") ++ (prin1 " came back")) ++ @print{} The\ cat\ in"the hat"" came back" ++ @result{} " came back" ++@end group ++@end example ++@end defun ++ ++@defun princ object &optional stream ++This function outputs the printed representation of @var{object} to ++@var{stream}. It returns @var{object}. ++ ++This function is intended to produce output that is readable by people, ++not by @code{read}, so it doesn't insert quoting characters and doesn't ++put double-quotes around the contents of strings. It does not add any ++spacing between calls. ++ ++@example ++@group ++(progn ++ (princ 'The\ cat) ++ (princ " in the \"hat\"")) ++ @print{} The cat in the "hat" ++ @result{} " in the \"hat\"" ++@end group ++@end example ++@end defun ++ ++@defun terpri &optional stream ++@cindex newline in print ++This function outputs a newline to @var{stream}. The name stands ++for ``terminate print.'' ++@end defun ++ ++@defun write-char character &optional stream ++This function outputs @var{character} to @var{stream}. It returns ++@var{character}. ++@end defun ++ ++@defun prin1-to-string object &optional noescape ++@cindex object to string ++This function returns a string containing the text that @code{prin1} ++would have printed for the same argument. ++ ++@example ++@group ++(prin1-to-string 'foo) ++ @result{} "foo" ++@end group ++@group ++(prin1-to-string (mark-marker)) ++ @result{} "#" ++@end group ++@end example ++ ++If @var{noescape} is non-@code{nil}, that inhibits use of quoting ++characters in the output. (This argument is supported in Emacs versions ++19 and later.) ++ ++@example ++@group ++(prin1-to-string "foo") ++ @result{} "\"foo\"" ++@end group ++@group ++(prin1-to-string "foo" t) ++ @result{} "foo" ++@end group ++@end example ++ ++See @code{format}, in @ref{Formatting Strings}, for other ways to obtain ++the printed representation of a Lisp object as a string. ++@end defun ++ ++@defmac with-output-to-string body@dots{} ++This macro executes the @var{body} forms with @code{standard-output} set ++up to feed output into a string. Then it returns that string. ++ ++For example, if the current buffer name is @samp{foo}, ++ ++@example ++(with-output-to-string ++ (princ "The buffer is ") ++ (princ (buffer-name))) ++@end example ++ ++@noindent ++returns @code{"The buffer is foo"}. ++@end defmac ++ ++@node Output Variables ++@section Variables Affecting Output ++@cindex output-controlling variables ++ ++@defvar standard-output ++The value of this variable is the default output stream---the stream ++that print functions use when the @var{stream} argument is @code{nil}. ++The default is @code{t}, meaning display in the echo area. ++@end defvar ++ ++@defvar print-quoted ++If this is non-@code{nil}, that means to print quoted forms using ++abbreviated reader syntax. @code{(quote foo)} prints as @code{'foo}, ++@code{(function foo)} as @code{#'foo}, and backquoted forms print ++using modern backquote syntax. ++@end defvar ++ ++@defvar print-escape-newlines ++@cindex @samp{\n} in print ++@cindex escape characters ++If this variable is non-@code{nil}, then newline characters in strings ++are printed as @samp{\n} and formfeeds are printed as @samp{\f}. ++Normally these characters are printed as actual newlines and formfeeds. ++ ++This variable affects the print functions @code{prin1} and @code{print} ++that print with quoting. It does not affect @code{princ}. Here is an ++example using @code{prin1}: ++ ++@example ++@group ++(prin1 "a\nb") ++ @print{} "a ++ @print{} b" ++ @result{} "a ++b" ++@end group ++ ++@group ++(let ((print-escape-newlines t)) ++ (prin1 "a\nb")) ++ @print{} "a\nb" ++ @result{} "a ++b" ++@end group ++@end example ++ ++@noindent ++In the second expression, the local binding of ++@code{print-escape-newlines} is in effect during the call to ++@code{prin1}, but not during the printing of the result. ++@end defvar ++ ++@defvar print-escape-nonascii ++If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII} ++characters in strings are unconditionally printed as backslash sequences ++by the print functions @code{prin1} and @code{print} that print with ++quoting. ++ ++Those functions also use backslash sequences for unibyte non-@acronym{ASCII} ++characters, regardless of the value of this variable, when the output ++stream is a multibyte buffer or a marker pointing into one. ++@end defvar ++ ++@defvar print-escape-multibyte ++If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII} ++characters in strings are unconditionally printed as backslash sequences ++by the print functions @code{prin1} and @code{print} that print with ++quoting. ++ ++Those functions also use backslash sequences for multibyte ++non-@acronym{ASCII} characters, regardless of the value of this variable, ++when the output stream is a unibyte buffer or a marker pointing into ++one. ++@end defvar ++ ++@defvar print-length ++@cindex printing limits ++The value of this variable is the maximum number of elements to print in ++any list, vector or bool-vector. If an object being printed has more ++than this many elements, it is abbreviated with an ellipsis. ++ ++If the value is @code{nil} (the default), then there is no limit. ++ ++@example ++@group ++(setq print-length 2) ++ @result{} 2 ++@end group ++@group ++(print '(1 2 3 4 5)) ++ @print{} (1 2 ...) ++ @result{} (1 2 ...) ++@end group ++@end example ++@end defvar ++ ++@defvar print-level ++The value of this variable is the maximum depth of nesting of ++parentheses and brackets when printed. Any list or vector at a depth ++exceeding this limit is abbreviated with an ellipsis. A value of ++@code{nil} (which is the default) means no limit. ++@end defvar ++ ++@defopt eval-expression-print-length ++@defoptx eval-expression-print-level ++These are the values for @code{print-length} and @code{print-level} ++used by @code{eval-expression}, and thus, indirectly, by many ++interactive evaluation commands (@pxref{Lisp Eval,, Evaluating ++Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}). ++@end defopt ++ ++ These variables are used for detecting and reporting circular ++and shared structure: ++ ++@defvar print-circle ++If non-@code{nil}, this variable enables detection of circular and ++shared structure in printing. @xref{Circular Objects}. ++@end defvar ++ ++@defvar print-gensym ++If non-@code{nil}, this variable enables detection of uninterned symbols ++(@pxref{Creating Symbols}) in printing. When this is enabled, ++uninterned symbols print with the prefix @samp{#:}, which tells the Lisp ++reader to produce an uninterned symbol. ++@end defvar ++ ++@defvar print-continuous-numbering ++If non-@code{nil}, that means number continuously across print calls. ++This affects the numbers printed for @samp{#@var{n}=} labels and ++@samp{#@var{m}#} references. ++ ++Don't set this variable with @code{setq}; you should only bind it ++temporarily to @code{t} with @code{let}. When you do that, you should ++also bind @code{print-number-table} to @code{nil}. ++@end defvar ++ ++@defvar print-number-table ++This variable holds a vector used internally by printing to implement ++the @code{print-circle} feature. You should not use it except ++to bind it to @code{nil} when you bind @code{print-continuous-numbering}. ++@end defvar ++ ++@defvar float-output-format ++This variable specifies how to print floating point numbers. Its ++default value is @code{nil}, meaning use the shortest output ++that represents the number without losing information. ++ ++To control output format more precisely, you can put a string in this ++variable. The string should hold a @samp{%}-specification to be used ++in the C function @code{sprintf}. For further restrictions on what ++you can use, see the variable's documentation string. ++@end defvar ++ ++@ignore ++ arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434 ++@end ignore +diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi +new file mode 100644 +index 0000000..5dd5e80 +--- /dev/null ++++ b/doc/lispref/strings.texi +@@ -0,0 +1,1160 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/strings ++@node Strings and Characters, Lists, Numbers, Top ++@comment node-name, next, previous, up ++@chapter Strings and Characters ++@cindex strings ++@cindex character arrays ++@cindex characters ++@cindex bytes ++ ++ A string in Emacs Lisp is an array that contains an ordered sequence ++of characters. Strings are used as names of symbols, buffers, and ++files; to send messages to users; to hold text being copied between ++buffers; and for many other purposes. Because strings are so important, ++Emacs Lisp has many functions expressly for manipulating them. Emacs ++Lisp programs use strings more often than individual characters. ++ ++ @xref{Strings of Events}, for special considerations for strings of ++keyboard character events. ++ ++@menu ++* Basics: String Basics. Basic properties of strings and characters. ++* Predicates for Strings:: Testing whether an object is a string or char. ++* Creating Strings:: Functions to allocate new strings. ++* Modifying Strings:: Altering the contents of an existing string. ++* Text Comparison:: Comparing characters or strings. ++* String Conversion:: Converting to and from characters and strings. ++* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. ++* Case Conversion:: Case conversion functions. ++* Case Tables:: Customizing case conversion. ++@end menu ++ ++@node String Basics ++@section String and Character Basics ++ ++ Characters are represented in Emacs Lisp as integers; ++whether an integer is a character or not is determined only by how it is ++used. Thus, strings really contain integers. @xref{Character Codes}, ++for details about character representation in Emacs. ++ ++ The length of a string (like any array) is fixed, and cannot be ++altered once the string exists. Strings in Lisp are @emph{not} ++terminated by a distinguished character code. (By contrast, strings in ++C are terminated by a character with @acronym{ASCII} code 0.) ++ ++ Since strings are arrays, and therefore sequences as well, you can ++operate on them with the general array and sequence functions. ++(@xref{Sequences Arrays Vectors}.) For example, you can access or ++change individual characters in a string using the functions @code{aref} ++and @code{aset} (@pxref{Array Functions}). ++ ++ There are two text representations for non-@acronym{ASCII} characters in ++Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text ++Representations}). For most Lisp programming, you don't need to be ++concerned with these two representations. ++ ++ Sometimes key sequences are represented as unibyte strings. When a ++unibyte string is a key sequence, string elements in the range 128 to ++255 represent meta characters (which are large integers) rather than ++character codes in the range 128 to 255. Strings cannot hold ++characters that have the hyper, super or alt modifiers; they can hold ++@acronym{ASCII} control characters, but no other control characters. ++They do not distinguish case in @acronym{ASCII} control characters. ++If you want to store such characters in a sequence, such as a key ++sequence, you must use a vector instead of a string. @xref{Character ++Type}, for more information about keyboard input characters. ++ ++ Strings are useful for holding regular expressions. You can also ++match regular expressions against strings with @code{string-match} ++(@pxref{Regexp Search}). The functions @code{match-string} ++(@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing ++Match}) are useful for decomposing and modifying strings after ++matching regular expressions against them. ++ ++ Like a buffer, a string can contain text properties for the characters ++in it, as well as the characters themselves. @xref{Text Properties}. ++All the Lisp primitives that copy text from strings to buffers or other ++strings also copy the properties of the characters being copied. ++ ++ @xref{Text}, for information about functions that display strings or ++copy them into buffers. @xref{Character Type}, and @ref{String Type}, ++for information about the syntax of characters and strings. ++@xref{Non-ASCII Characters}, for functions to convert between text ++representations and to encode and decode character codes. ++ ++@node Predicates for Strings ++@section The Predicates for Strings ++ ++For more information about general sequence and array predicates, ++see @ref{Sequences Arrays Vectors}, and @ref{Arrays}. ++ ++@defun stringp object ++This function returns @code{t} if @var{object} is a string, @code{nil} ++otherwise. ++@end defun ++ ++@defun string-or-null-p object ++This function returns @code{t} if @var{object} is a string or ++@code{nil}. It returns @code{nil} otherwise. ++@end defun ++ ++@defun char-or-string-p object ++This function returns @code{t} if @var{object} is a string or a ++character (i.e., an integer), @code{nil} otherwise. ++@end defun ++ ++@node Creating Strings ++@section Creating Strings ++ ++ The following functions create strings, either from scratch, or by ++putting strings together, or by taking them apart. ++ ++@defun make-string count character ++This function returns a string made up of @var{count} repetitions of ++@var{character}. If @var{count} is negative, an error is signaled. ++ ++@example ++(make-string 5 ?x) ++ @result{} "xxxxx" ++(make-string 0 ?x) ++ @result{} "" ++@end example ++ ++ Other functions to compare with this one include @code{char-to-string} ++(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and ++@code{make-list} (@pxref{Building Lists}). ++@end defun ++ ++@defun string &rest characters ++This returns a string containing the characters @var{characters}. ++ ++@example ++(string ?a ?b ?c) ++ @result{} "abc" ++@end example ++@end defun ++ ++@defun substring string start &optional end ++This function returns a new string which consists of those characters ++from @var{string} in the range from (and including) the character at the ++index @var{start} up to (but excluding) the character at the index ++@var{end}. The first character is at index zero. ++ ++@example ++@group ++(substring "abcdefg" 0 3) ++ @result{} "abc" ++@end group ++@end example ++ ++@noindent ++In the above example, the index for @samp{a} is 0, the index for ++@samp{b} is 1, and the index for @samp{c} is 2. The index 3---which ++is the the fourth character in the string---marks the character ++position up to which the substring is copied. Thus, @samp{abc} is ++copied from the string @code{"abcdefg"}. ++ ++A negative number counts from the end of the string, so that @minus{}1 ++signifies the index of the last character of the string. For example: ++ ++@example ++@group ++(substring "abcdefg" -3 -1) ++ @result{} "ef" ++@end group ++@end example ++ ++@noindent ++In this example, the index for @samp{e} is @minus{}3, the index for ++@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1. ++Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded. ++ ++When @code{nil} is used for @var{end}, it stands for the length of the ++string. Thus, ++ ++@example ++@group ++(substring "abcdefg" -3 nil) ++ @result{} "efg" ++@end group ++@end example ++ ++Omitting the argument @var{end} is equivalent to specifying @code{nil}. ++It follows that @code{(substring @var{string} 0)} returns a copy of all ++of @var{string}. ++ ++@example ++@group ++(substring "abcdefg" 0) ++ @result{} "abcdefg" ++@end group ++@end example ++ ++@noindent ++But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence ++Functions}). ++ ++If the characters copied from @var{string} have text properties, the ++properties are copied into the new string also. @xref{Text Properties}. ++ ++@code{substring} also accepts a vector for the first argument. ++For example: ++ ++@example ++(substring [a b (c) "d"] 1 3) ++ @result{} [b (c)] ++@end example ++ ++A @code{wrong-type-argument} error is signaled if @var{start} is not ++an integer or if @var{end} is neither an integer nor @code{nil}. An ++@code{args-out-of-range} error is signaled if @var{start} indicates a ++character following @var{end}, or if either integer is out of range ++for @var{string}. ++ ++Contrast this function with @code{buffer-substring} (@pxref{Buffer ++Contents}), which returns a string containing a portion of the text in ++the current buffer. The beginning of a string is at index 0, but the ++beginning of a buffer is at index 1. ++@end defun ++ ++@defun substring-no-properties string &optional start end ++This works like @code{substring} but discards all text properties from ++the value. Also, @var{start} may be omitted or @code{nil}, which is ++equivalent to 0. Thus, @w{@code{(substring-no-properties ++@var{string})}} returns a copy of @var{string}, with all text ++properties removed. ++@end defun ++ ++@defun concat &rest sequences ++@cindex copying strings ++@cindex concatenating strings ++This function returns a new string consisting of the characters in the ++arguments passed to it (along with their text properties, if any). The ++arguments may be strings, lists of numbers, or vectors of numbers; they ++are not themselves changed. If @code{concat} receives no arguments, it ++returns an empty string. ++ ++@example ++(concat "abc" "-def") ++ @result{} "abc-def" ++(concat "abc" (list 120 121) [122]) ++ @result{} "abcxyz" ++;; @r{@code{nil} is an empty sequence.} ++(concat "abc" nil "-def") ++ @result{} "abc-def" ++(concat "The " "quick brown " "fox.") ++ @result{} "The quick brown fox." ++(concat) ++ @result{} "" ++@end example ++ ++@noindent ++This function always constructs a new string that is not @code{eq} to ++any existing string, except when the result is the empty string (to ++save space, Emacs makes only one empty multibyte string). ++ ++For information about other concatenation functions, see the ++description of @code{mapconcat} in @ref{Mapping Functions}, ++@code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building ++Lists}. For concatenating individual command-line arguments into a ++string to be used as a shell command, see @ref{Shell Arguments, ++combine-and-quote-strings}. ++@end defun ++ ++@defun split-string string &optional separators omit-nulls ++This function splits @var{string} into substrings based on the regular ++expression @var{separators} (@pxref{Regular Expressions}). Each match ++for @var{separators} defines a splitting point; the substrings between ++splitting points are made into a list, which is returned. ++ ++If @var{omit-nulls} is @code{nil} (or omitted), the result contains ++null strings whenever there are two consecutive matches for ++@var{separators}, or a match is adjacent to the beginning or end of ++@var{string}. If @var{omit-nulls} is @code{t}, these null strings are ++omitted from the result. ++ ++If @var{separators} is @code{nil} (or omitted), the default is the ++value of @code{split-string-default-separators}. ++ ++As a special case, when @var{separators} is @code{nil} (or omitted), ++null strings are always omitted from the result. Thus: ++ ++@example ++(split-string " two words ") ++ @result{} ("two" "words") ++@end example ++ ++The result is not @code{("" "two" "words" "")}, which would rarely be ++useful. If you need such a result, use an explicit value for ++@var{separators}: ++ ++@example ++(split-string " two words " ++ split-string-default-separators) ++ @result{} ("" "two" "words" "") ++@end example ++ ++More examples: ++ ++@example ++(split-string "Soup is good food" "o") ++ @result{} ("S" "up is g" "" "d f" "" "d") ++(split-string "Soup is good food" "o" t) ++ @result{} ("S" "up is g" "d f" "d") ++(split-string "Soup is good food" "o+") ++ @result{} ("S" "up is g" "d f" "d") ++@end example ++ ++Empty matches do count, except that @code{split-string} will not look ++for a final empty match when it already reached the end of the string ++using a non-empty match or when @var{string} is empty: ++ ++@example ++(split-string "aooob" "o*") ++ @result{} ("" "a" "" "b" "") ++(split-string "ooaboo" "o*") ++ @result{} ("" "" "a" "b" "") ++(split-string "" "") ++ @result{} ("") ++@end example ++ ++However, when @var{separators} can match the empty string, ++@var{omit-nulls} is usually @code{t}, so that the subtleties in the ++three previous examples are rarely relevant: ++ ++@example ++(split-string "Soup is good food" "o*" t) ++ @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d") ++(split-string "Nice doggy!" "" t) ++ @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!") ++(split-string "" "" t) ++ @result{} nil ++@end example ++ ++Somewhat odd, but predictable, behavior can occur for certain ++``non-greedy'' values of @var{separators} that can prefer empty ++matches over non-empty matches. Again, such values rarely occur in ++practice: ++ ++@example ++(split-string "ooo" "o*" t) ++ @result{} nil ++(split-string "ooo" "\\|o+" t) ++ @result{} ("o" "o" "o") ++@end example ++ ++If you need to split a string that is a shell command, where ++individual arguments could be quoted, see @ref{Shell Arguments, ++split-string-and-unquote}. ++@end defun ++ ++@defvar split-string-default-separators ++The default value of @var{separators} for @code{split-string}. Its ++usual value is @w{@code{"[ \f\t\n\r\v]+"}}. ++@end defvar ++ ++@node Modifying Strings ++@section Modifying Strings ++ ++ The most basic way to alter the contents of an existing string is with ++@code{aset} (@pxref{Array Functions}). @code{(aset @var{string} ++@var{idx} @var{char})} stores @var{char} into @var{string} at index ++@var{idx}. Each character occupies one or more bytes, and if @var{char} ++needs a different number of bytes from the character already present at ++that index, @code{aset} signals an error. ++ ++ A more powerful function is @code{store-substring}: ++ ++@defun store-substring string idx obj ++This function alters part of the contents of the string @var{string}, by ++storing @var{obj} starting at index @var{idx}. The argument @var{obj} ++may be either a character or a (smaller) string. ++ ++Since it is impossible to change the length of an existing string, it is ++an error if @var{obj} doesn't fit within @var{string}'s actual length, ++or if any new character requires a different number of bytes from the ++character currently present at that point in @var{string}. ++@end defun ++ ++ To clear out a string that contained a password, use ++@code{clear-string}: ++ ++@defun clear-string string ++This makes @var{string} a unibyte string and clears its contents to ++zeros. It may also change @var{string}'s length. ++@end defun ++ ++@need 2000 ++@node Text Comparison ++@section Comparison of Characters and Strings ++@cindex string equality ++ ++@defun char-equal character1 character2 ++This function returns @code{t} if the arguments represent the same ++character, @code{nil} otherwise. This function ignores differences ++in case if @code{case-fold-search} is non-@code{nil}. ++ ++@example ++(char-equal ?x ?x) ++ @result{} t ++(let ((case-fold-search nil)) ++ (char-equal ?x ?X)) ++ @result{} nil ++@end example ++@end defun ++ ++@defun string= string1 string2 ++This function returns @code{t} if the characters of the two strings ++match exactly. Symbols are also allowed as arguments, in which case ++their print names are used. ++Case is always significant, regardless of @code{case-fold-search}. ++ ++@example ++(string= "abc" "abc") ++ @result{} t ++(string= "abc" "ABC") ++ @result{} nil ++(string= "ab" "ABC") ++ @result{} nil ++@end example ++ ++The function @code{string=} ignores the text properties of the two ++strings. When @code{equal} (@pxref{Equality Predicates}) compares two ++strings, it uses @code{string=}. ++ ++For technical reasons, a unibyte and a multibyte string are ++@code{equal} if and only if they contain the same sequence of ++character codes and all these codes are either in the range 0 through ++127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). ++However, when a unibyte string is converted to a multibyte string, all ++characters with codes in the range 160 through 255 are converted to ++characters with higher codes, whereas @acronym{ASCII} characters ++remain unchanged. Thus, a unibyte string and its conversion to ++multibyte are only @code{equal} if the string is all @acronym{ASCII}. ++Character codes 160 through 255 are not entirely proper in multibyte ++text, even though they can occur. As a consequence, the situation ++where a unibyte and a multibyte string are @code{equal} without both ++being all @acronym{ASCII} is a technical oddity that very few Emacs ++Lisp programmers ever get confronted with. @xref{Text ++Representations}. ++@end defun ++ ++@defun string-equal string1 string2 ++@code{string-equal} is another name for @code{string=}. ++@end defun ++ ++@cindex lexical comparison ++@defun string< string1 string2 ++@c (findex string< causes problems for permuted index!!) ++This function compares two strings a character at a time. It ++scans both the strings at the same time to find the first pair of corresponding ++characters that do not match. If the lesser character of these two is ++the character from @var{string1}, then @var{string1} is less, and this ++function returns @code{t}. If the lesser character is the one from ++@var{string2}, then @var{string1} is greater, and this function returns ++@code{nil}. If the two strings match entirely, the value is @code{nil}. ++ ++Pairs of characters are compared according to their character codes. ++Keep in mind that lower case letters have higher numeric values in the ++@acronym{ASCII} character set than their upper case counterparts; digits and ++many punctuation characters have a lower numeric value than upper case ++letters. An @acronym{ASCII} character is less than any non-@acronym{ASCII} ++character; a unibyte non-@acronym{ASCII} character is always less than any ++multibyte non-@acronym{ASCII} character (@pxref{Text Representations}). ++ ++@example ++@group ++(string< "abc" "abd") ++ @result{} t ++(string< "abd" "abc") ++ @result{} nil ++(string< "123" "abc") ++ @result{} t ++@end group ++@end example ++ ++When the strings have different lengths, and they match up to the ++length of @var{string1}, then the result is @code{t}. If they match up ++to the length of @var{string2}, the result is @code{nil}. A string of ++no characters is less than any other string. ++ ++@example ++@group ++(string< "" "abc") ++ @result{} t ++(string< "ab" "abc") ++ @result{} t ++(string< "abc" "") ++ @result{} nil ++(string< "abc" "ab") ++ @result{} nil ++(string< "" "") ++ @result{} nil ++@end group ++@end example ++ ++Symbols are also allowed as arguments, in which case their print names ++are used. ++@end defun ++ ++@defun string-lessp string1 string2 ++@code{string-lessp} is another name for @code{string<}. ++@end defun ++ ++@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case ++This function compares the specified part of @var{string1} with the ++specified part of @var{string2}. The specified part of @var{string1} ++runs from index @var{start1} up to index @var{end1} (@code{nil} means ++the end of the string). The specified part of @var{string2} runs from ++index @var{start2} up to index @var{end2} (@code{nil} means the end of ++the string). ++ ++The strings are both converted to multibyte for the comparison ++(@pxref{Text Representations}) so that a unibyte string and its ++conversion to multibyte are always regarded as equal. If ++@var{ignore-case} is non-@code{nil}, then case is ignored, so that ++upper case letters can be equal to lower case letters. ++ ++If the specified portions of the two strings match, the value is ++@code{t}. Otherwise, the value is an integer which indicates how many ++leading characters agree, and which string is less. Its absolute value ++is one plus the number of characters that agree at the beginning of the ++two strings. The sign is negative if @var{string1} (or its specified ++portion) is less. ++@end defun ++ ++@defun assoc-string key alist &optional case-fold ++This function works like @code{assoc}, except that @var{key} must be a ++string or symbol, and comparison is done using @code{compare-strings}. ++Symbols are converted to strings before testing. ++If @var{case-fold} is non-@code{nil}, it ignores case differences. ++Unlike @code{assoc}, this function can also match elements of the alist ++that are strings or symbols rather than conses. In particular, @var{alist} can ++be a list of strings or symbols rather than an actual alist. ++@xref{Association Lists}. ++@end defun ++ ++ See also the function @code{compare-buffer-substrings} in ++@ref{Comparing Text}, for a way to compare text in buffers. The ++function @code{string-match}, which matches a regular expression ++against a string, can be used for a kind of string comparison; see ++@ref{Regexp Search}. ++ ++@node String Conversion ++@comment node-name, next, previous, up ++@section Conversion of Characters and Strings ++@cindex conversion of strings ++ ++ This section describes functions for converting between characters, ++strings and integers. @code{format} (@pxref{Formatting Strings}) and ++@code{prin1-to-string} (@pxref{Output Functions}) can also convert ++Lisp objects into strings. @code{read-from-string} (@pxref{Input ++Functions}) can ``convert'' a string representation of a Lisp object ++into an object. The functions @code{string-make-multibyte} and ++@code{string-make-unibyte} convert the text representation of a string ++(@pxref{Converting Representations}). ++ ++ @xref{Documentation}, for functions that produce textual descriptions ++of text characters and general input events ++(@code{single-key-description} and @code{text-char-description}). These ++are used primarily for making help messages. ++ ++@defun char-to-string character ++@cindex character to string ++This function returns a new string containing one character, ++@var{character}. This function is semi-obsolete because the function ++@code{string} is more general. @xref{Creating Strings}. ++@end defun ++ ++@defun string-to-char string ++@cindex string to character ++ This function returns the first character in @var{string}. If the ++string is empty, the function returns 0. The value is also 0 when the ++first character of @var{string} is the null character, @acronym{ASCII} code ++0. ++ ++@example ++(string-to-char "ABC") ++ @result{} 65 ++ ++(string-to-char "xyz") ++ @result{} 120 ++(string-to-char "") ++ @result{} 0 ++@group ++(string-to-char "\000") ++ @result{} 0 ++@end group ++@end example ++ ++This function may be eliminated in the future if it does not seem useful ++enough to retain. ++@end defun ++ ++@defun number-to-string number ++@cindex integer to string ++@cindex integer to decimal ++This function returns a string consisting of the printed base-ten ++representation of @var{number}, which may be an integer or a floating ++point number. The returned value starts with a minus sign if the argument is ++negative. ++ ++@example ++(number-to-string 256) ++ @result{} "256" ++@group ++(number-to-string -23) ++ @result{} "-23" ++@end group ++(number-to-string -23.5) ++ @result{} "-23.5" ++@end example ++ ++@cindex int-to-string ++@code{int-to-string} is a semi-obsolete alias for this function. ++ ++See also the function @code{format} in @ref{Formatting Strings}. ++@end defun ++ ++@defun string-to-number string &optional base ++@cindex string to number ++This function returns the numeric value of the characters in ++@var{string}. If @var{base} is non-@code{nil}, it must be an integer ++between 2 and 16 (inclusive), and integers are converted in that base. ++If @var{base} is @code{nil}, then base ten is used. Floating point ++conversion only works in base ten; we have not implemented other ++radices for floating point numbers, because that would be much more ++work and does not seem useful. If @var{string} looks like an integer ++but its value is too large to fit into a Lisp integer, ++@code{string-to-number} returns a floating point result. ++ ++The parsing skips spaces and tabs at the beginning of @var{string}, ++then reads as much of @var{string} as it can interpret as a number in ++the given base. (On some systems it ignores other whitespace at the ++beginning, not just spaces and tabs.) If the first character after ++the ignored whitespace is neither a digit in the given base, nor a ++plus or minus sign, nor the leading dot of a floating point number, ++this function returns 0. ++ ++@example ++(string-to-number "256") ++ @result{} 256 ++(string-to-number "25 is a perfect square.") ++ @result{} 25 ++(string-to-number "X256") ++ @result{} 0 ++(string-to-number "-4.5") ++ @result{} -4.5 ++(string-to-number "1e5") ++ @result{} 100000.0 ++@end example ++ ++@findex string-to-int ++@code{string-to-int} is an obsolete alias for this function. ++@end defun ++ ++ Here are some other functions that can convert to or from a string: ++ ++@table @code ++@item concat ++@code{concat} can convert a vector or a list into a string. ++@xref{Creating Strings}. ++ ++@item vconcat ++@code{vconcat} can convert a string into a vector. @xref{Vector ++Functions}. ++ ++@item append ++@code{append} can convert a string into a list. @xref{Building Lists}. ++@end table ++ ++@node Formatting Strings ++@comment node-name, next, previous, up ++@section Formatting Strings ++@cindex formatting strings ++@cindex strings, formatting them ++ ++ @dfn{Formatting} means constructing a string by substituting ++computed values at various places in a constant string. This constant ++string controls how the other values are printed, as well as where ++they appear; it is called a @dfn{format string}. ++ ++ Formatting is often useful for computing messages to be displayed. In ++fact, the functions @code{message} and @code{error} provide the same ++formatting feature described here; they differ from @code{format} only ++in how they use the result of formatting. ++ ++@defun format string &rest objects ++This function returns a new string that is made by copying ++@var{string} and then replacing any format specification ++in the copy with encodings of the corresponding @var{objects}. The ++arguments @var{objects} are the computed values to be formatted. ++ ++The characters in @var{string}, other than the format specifications, ++are copied directly into the output, including their text properties, ++if any. ++@end defun ++ ++@cindex @samp{%} in format ++@cindex format specification ++ A format specification is a sequence of characters beginning with a ++@samp{%}. Thus, if there is a @samp{%d} in @var{string}, the ++@code{format} function replaces it with the printed representation of ++one of the values to be formatted (one of the arguments @var{objects}). ++For example: ++ ++@example ++@group ++(format "The value of fill-column is %d." fill-column) ++ @result{} "The value of fill-column is 72." ++@end group ++@end example ++ ++ Since @code{format} interprets @samp{%} characters as format ++specifications, you should @emph{never} pass an arbitrary string as ++the first argument. This is particularly true when the string is ++generated by some Lisp code. Unless the string is @emph{known} to ++never include any @samp{%} characters, pass @code{"%s"}, described ++below, as the first argument, and the string as the second, like this: ++ ++@example ++ (format "%s" @var{arbitrary-string}) ++@end example ++ ++ If @var{string} contains more than one format specification, the ++format specifications correspond to successive values from ++@var{objects}. Thus, the first format specification in @var{string} ++uses the first such value, the second format specification uses the ++second such value, and so on. Any extra format specifications (those ++for which there are no corresponding values) cause an error. Any ++extra values to be formatted are ignored. ++ ++ Certain format specifications require values of particular types. If ++you supply a value that doesn't fit the requirements, an error is ++signaled. ++ ++ Here is a table of valid format specifications: ++ ++@table @samp ++@item %s ++Replace the specification with the printed representation of the object, ++made without quoting (that is, using @code{princ}, not ++@code{prin1}---@pxref{Output Functions}). Thus, strings are represented ++by their contents alone, with no @samp{"} characters, and symbols appear ++without @samp{\} characters. ++ ++If the object is a string, its text properties are ++copied into the output. The text properties of the @samp{%s} itself ++are also copied, but those of the object take priority. ++ ++@item %S ++Replace the specification with the printed representation of the object, ++made with quoting (that is, using @code{prin1}---@pxref{Output ++Functions}). Thus, strings are enclosed in @samp{"} characters, and ++@samp{\} characters appear where necessary before special characters. ++ ++@item %o ++@cindex integer to octal ++Replace the specification with the base-eight representation of an ++integer. ++ ++@item %d ++Replace the specification with the base-ten representation of an ++integer. ++ ++@item %x ++@itemx %X ++@cindex integer to hexadecimal ++Replace the specification with the base-sixteen representation of an ++integer. @samp{%x} uses lower case and @samp{%X} uses upper case. ++ ++@item %c ++Replace the specification with the character which is the value given. ++ ++@item %e ++Replace the specification with the exponential notation for a floating ++point number. ++ ++@item %f ++Replace the specification with the decimal-point notation for a floating ++point number. ++ ++@item %g ++Replace the specification with notation for a floating point number, ++using either exponential notation or decimal-point notation, whichever ++is shorter. ++ ++@item %% ++Replace the specification with a single @samp{%}. This format ++specification is unusual in that it does not use a value. For example, ++@code{(format "%% %d" 30)} returns @code{"% 30"}. ++@end table ++ ++ Any other format character results in an @samp{Invalid format ++operation} error. ++ ++ Here are several examples: ++ ++@example ++@group ++(format "The name of this buffer is %s." (buffer-name)) ++ @result{} "The name of this buffer is strings.texi." ++ ++(format "The buffer object prints as %s." (current-buffer)) ++ @result{} "The buffer object prints as strings.texi." ++ ++(format "The octal value of %d is %o, ++ and the hex value is %x." 18 18 18) ++ @result{} "The octal value of 18 is 22, ++ and the hex value is 12." ++@end group ++@end example ++ ++@cindex field width ++@cindex padding ++ A specification can have a @dfn{width}, which is a decimal number ++between the @samp{%} and the specification character. If the printed ++representation of the object contains fewer characters than this ++width, @code{format} extends it with padding. The width specifier is ++ignored for the @samp{%%} specification. Any padding introduced by ++the width specifier normally consists of spaces inserted on the left: ++ ++@example ++(format "%5d is padded on the left with spaces" 123) ++ @result{} " 123 is padded on the left with spaces" ++@end example ++ ++@noindent ++If the width is too small, @code{format} does not truncate the ++object's printed representation. Thus, you can use a width to specify ++a minimum spacing between columns with no risk of losing information. ++In the following three examples, @samp{%7s} specifies a minimum width ++of 7. In the first case, the string inserted in place of @samp{%7s} ++has only 3 letters, and needs 4 blank spaces as padding. In the ++second case, the string @code{"specification"} is 13 letters wide but ++is not truncated. ++ ++@example ++@group ++(format "The word `%7s' actually has %d letters in it." ++ "foo" (length "foo")) ++ @result{} "The word ` foo' actually has 3 letters in it." ++(format "The word `%7s' actually has %d letters in it." ++ "specification" (length "specification")) ++ @result{} "The word `specification' actually has 13 letters in it." ++@end group ++@end example ++ ++@cindex flags in format specifications ++ Immediately after the @samp{%} and before the optional width ++specifier, you can also put certain @dfn{flag characters}. ++ ++ The flag @samp{+} inserts a plus sign before a positive number, so ++that it always has a sign. A space character as flag inserts a space ++before a positive number. (Otherwise, positive numbers start with the ++first digit.) These flags are useful for ensuring that positive ++numbers and negative numbers use the same number of columns. They are ++ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if ++both flags are used, @samp{+} takes precedence. ++ ++ The flag @samp{#} specifies an ``alternate form'' which depends on ++the format in use. For @samp{%o}, it ensures that the result begins ++with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result ++with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g}, ++the @samp{#} flag means include a decimal point even if the precision ++is zero. ++ ++ The flag @samp{-} causes the padding inserted by the width ++specifier, if any, to be inserted on the right rather than the left. ++The flag @samp{0} ensures that the padding consists of @samp{0} ++characters instead of spaces, inserted on the left. These flags are ++ignored for specification characters for which they do not make sense: ++@samp{%s}, @samp{%S} and @samp{%c} accept the @samp{0} flag, but still ++pad with @emph{spaces} on the left. If both @samp{-} and @samp{0} are ++present and valid, @samp{-} takes precedence. ++ ++@example ++@group ++(format "%06d is padded on the left with zeros" 123) ++ @result{} "000123 is padded on the left with zeros" ++ ++(format "%-6d is padded on the right" 123) ++ @result{} "123 is padded on the right" ++ ++(format "The word `%-7s' actually has %d letters in it." ++ "foo" (length "foo")) ++ @result{} "The word `foo ' actually has 3 letters in it." ++@end group ++@end example ++ ++@cindex precision in format specifications ++ All the specification characters allow an optional @dfn{precision} ++before the character (after the width, if present). The precision is ++a decimal-point @samp{.} followed by a digit-string. For the ++floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the ++precision specifies how many decimal places to show; if zero, the ++decimal-point itself is also omitted. For @samp{%s} and @samp{%S}, ++the precision truncates the string to the given width, so @samp{%.3s} ++shows only the first three characters of the representation for ++@var{object}. Precision has no effect for other specification ++characters. ++ ++@node Case Conversion ++@comment node-name, next, previous, up ++@section Case Conversion in Lisp ++@cindex upper case ++@cindex lower case ++@cindex character case ++@cindex case conversion in Lisp ++ ++ The character case functions change the case of single characters or ++of the contents of strings. The functions normally convert only ++alphabetic characters (the letters @samp{A} through @samp{Z} and ++@samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other ++characters are not altered. You can specify a different case ++conversion mapping by specifying a case table (@pxref{Case Tables}). ++ ++ These functions do not modify the strings that are passed to them as ++arguments. ++ ++ The examples below use the characters @samp{X} and @samp{x} which have ++@acronym{ASCII} codes 88 and 120 respectively. ++ ++@defun downcase string-or-char ++This function converts @var{string-or-char}, which should be either a ++character or a string, to lower case. ++ ++When @var{string-or-char} is a string, this function returns a new ++string in which each letter in the argument that is upper case is ++converted to lower case. When @var{string-or-char} is a character, ++this function returns the corresponding lower case character (an ++integer); if the original character is lower case, or is not a letter, ++the return value is equal to the original character. ++ ++@example ++(downcase "The cat in the hat") ++ @result{} "the cat in the hat" ++ ++(downcase ?X) ++ @result{} 120 ++@end example ++@end defun ++ ++@defun upcase string-or-char ++This function converts @var{string-or-char}, which should be either a ++character or a string, to upper case. ++ ++When @var{string-or-char} is a string, this function returns a new ++string in which each letter in the argument that is lower case is ++converted to upper case. When @var{string-or-char} is a character, ++this function returns the corresponding upper case character (an an ++integer); if the original character is upper case, or is not a letter, ++the return value is equal to the original character. ++ ++@example ++(upcase "The cat in the hat") ++ @result{} "THE CAT IN THE HAT" ++ ++(upcase ?x) ++ @result{} 88 ++@end example ++@end defun ++ ++@defun capitalize string-or-char ++@cindex capitalization ++This function capitalizes strings or characters. If ++@var{string-or-char} is a string, the function returns a new string ++whose contents are a copy of @var{string-or-char} in which each word ++has been capitalized. This means that the first character of each ++word is converted to upper case, and the rest are converted to lower ++case. ++ ++The definition of a word is any sequence of consecutive characters that ++are assigned to the word constituent syntax class in the current syntax ++table (@pxref{Syntax Class Table}). ++ ++When @var{string-or-char} is a character, this function does the same ++thing as @code{upcase}. ++ ++@example ++@group ++(capitalize "The cat in the hat") ++ @result{} "The Cat In The Hat" ++@end group ++ ++@group ++(capitalize "THE 77TH-HATTED CAT") ++ @result{} "The 77th-Hatted Cat" ++@end group ++ ++@group ++(capitalize ?x) ++ @result{} 88 ++@end group ++@end example ++@end defun ++ ++@defun upcase-initials string-or-char ++If @var{string-or-char} is a string, this function capitalizes the ++initials of the words in @var{string-or-char}, without altering any ++letters other than the initials. It returns a new string whose ++contents are a copy of @var{string-or-char}, in which each word has ++had its initial letter converted to upper case. ++ ++The definition of a word is any sequence of consecutive characters that ++are assigned to the word constituent syntax class in the current syntax ++table (@pxref{Syntax Class Table}). ++ ++When the argument to @code{upcase-initials} is a character, ++@code{upcase-initials} has the same result as @code{upcase}. ++ ++@example ++@group ++(upcase-initials "The CAT in the hAt") ++ @result{} "The CAT In The HAt" ++@end group ++@end example ++@end defun ++ ++ @xref{Text Comparison}, for functions that compare strings; some of ++them ignore case differences, or can optionally ignore case differences. ++ ++@node Case Tables ++@section The Case Table ++ ++ You can customize case conversion by installing a special @dfn{case ++table}. A case table specifies the mapping between upper case and lower ++case letters. It affects both the case conversion functions for Lisp ++objects (see the previous section) and those that apply to text in the ++buffer (@pxref{Case Changes}). Each buffer has a case table; there is ++also a standard case table which is used to initialize the case table ++of new buffers. ++ ++ A case table is a char-table (@pxref{Char-Tables}) whose subtype is ++@code{case-table}. This char-table maps each character into the ++corresponding lower case character. It has three extra slots, which ++hold related tables: ++ ++@table @var ++@item upcase ++The upcase table maps each character into the corresponding upper ++case character. ++@item canonicalize ++The canonicalize table maps all of a set of case-related characters ++into a particular member of that set. ++@item equivalences ++The equivalences table maps each one of a set of case-related characters ++into the next character in that set. ++@end table ++ ++ In simple cases, all you need to specify is the mapping to lower-case; ++the three related tables will be calculated automatically from that one. ++ ++ For some languages, upper and lower case letters are not in one-to-one ++correspondence. There may be two different lower case letters with the ++same upper case equivalent. In these cases, you need to specify the ++maps for both lower case and upper case. ++ ++ The extra table @var{canonicalize} maps each character to a canonical ++equivalent; any two characters that are related by case-conversion have ++the same canonical equivalent character. For example, since @samp{a} ++and @samp{A} are related by case-conversion, they should have the same ++canonical equivalent character (which should be either @samp{a} for both ++of them, or @samp{A} for both of them). ++ ++ The extra table @var{equivalences} is a map that cyclically permutes ++each equivalence class (of characters with the same canonical ++equivalent). (For ordinary @acronym{ASCII}, this would map @samp{a} into ++@samp{A} and @samp{A} into @samp{a}, and likewise for each set of ++equivalent characters.) ++ ++ When constructing a case table, you can provide @code{nil} for ++@var{canonicalize}; then Emacs fills in this slot from the lower case ++and upper case mappings. You can also provide @code{nil} for ++@var{equivalences}; then Emacs fills in this slot from ++@var{canonicalize}. In a case table that is actually in use, those ++components are non-@code{nil}. Do not try to specify ++@var{equivalences} without also specifying @var{canonicalize}. ++ ++ Here are the functions for working with case tables: ++ ++@defun case-table-p object ++This predicate returns non-@code{nil} if @var{object} is a valid case ++table. ++@end defun ++ ++@defun set-standard-case-table table ++This function makes @var{table} the standard case table, so that it will ++be used in any buffers created subsequently. ++@end defun ++ ++@defun standard-case-table ++This returns the standard case table. ++@end defun ++ ++@defun current-case-table ++This function returns the current buffer's case table. ++@end defun ++ ++@defun set-case-table table ++This sets the current buffer's case table to @var{table}. ++@end defun ++ ++@defmac with-case-table table body@dots{} ++The @code{with-case-table} macro saves the current case table, makes ++@var{table} the current case table, evaluates the @var{body} forms, ++and finally restores the case table. The return value is the value of ++the last form in @var{body}. The case table is restored even in case ++of an abnormal exit via @code{throw} or error (@pxref{Nonlocal ++Exits}). ++@end defmac ++ ++ Some language environments modify the case conversions of ++@acronym{ASCII} characters; for example, in the Turkish language ++environment, the @acronym{ASCII} character @samp{I} is downcased into ++a Turkish ``dotless i''. This can interfere with code that requires ++ordinary ASCII case conversion, such as implementations of ++@acronym{ASCII}-based network protocols. In that case, use the ++@code{with-case-table} macro with the variable @var{ascii-case-table}, ++which stores the unmodified case table for the @acronym{ASCII} ++character set. ++ ++@defvar ascii-case-table ++The case table for the @acronym{ASCII} character set. This should not be ++modified by any language environment settings. ++@end defvar ++ ++ The following three functions are convenient subroutines for packages ++that define non-@acronym{ASCII} character sets. They modify the specified ++case table @var{case-table}; they also modify the standard syntax table. ++@xref{Syntax Tables}. Normally you would use these functions to change ++the standard case table. ++ ++@defun set-case-syntax-pair uc lc case-table ++This function specifies a pair of corresponding letters, one upper case ++and one lower case. ++@end defun ++ ++@defun set-case-syntax-delims l r case-table ++This function makes characters @var{l} and @var{r} a matching pair of ++case-invariant delimiters. ++@end defun ++ ++@defun set-case-syntax char syntax case-table ++This function makes @var{char} case-invariant, with syntax ++@var{syntax}. ++@end defun ++ ++@deffn Command describe-buffer-case-table ++This command displays a description of the contents of the current ++buffer's case table. ++@end deffn ++ ++@ignore ++ arch-tag: 700b8e95-7aa5-4b52-9eb3-8f2e1ea152b4 ++@end ignore +diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi +new file mode 100644 +index 0000000..d5d5bb0 +--- /dev/null ++++ b/doc/lispref/symbols.texi +@@ -0,0 +1,596 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/symbols ++@node Symbols, Evaluation, Hash Tables, Top ++@chapter Symbols ++@cindex symbol ++ ++ A @dfn{symbol} is an object with a unique name. This chapter ++describes symbols, their components, their property lists, and how they ++are created and interned. Separate chapters describe the use of symbols ++as variables and as function names; see @ref{Variables}, and ++@ref{Functions}. For the precise read syntax for symbols, see ++@ref{Symbol Type}. ++ ++ You can test whether an arbitrary Lisp object is a symbol ++with @code{symbolp}: ++ ++@defun symbolp object ++This function returns @code{t} if @var{object} is a symbol, @code{nil} ++otherwise. ++@end defun ++ ++@menu ++* Symbol Components:: Symbols have names, values, function definitions ++ and property lists. ++* Definitions:: A definition says how a symbol will be used. ++* Creating Symbols:: How symbols are kept unique. ++* Property Lists:: Each symbol has a property list ++ for recording miscellaneous information. ++@end menu ++ ++@node Symbol Components, Definitions, Symbols, Symbols ++@section Symbol Components ++@cindex symbol components ++ ++ Each symbol has four components (or ``cells''), each of which ++references another object: ++ ++@table @asis ++@item Print name ++@cindex print name cell ++The @dfn{print name cell} holds a string that names the symbol for ++reading and printing. See @code{symbol-name} in @ref{Creating Symbols}. ++ ++@item Value ++@cindex value cell ++The @dfn{value cell} holds the current value of the symbol as a ++variable. When a symbol is used as a form, the value of the form is the ++contents of the symbol's value cell. See @code{symbol-value} in ++@ref{Accessing Variables}. ++ ++@item Function ++@cindex function cell ++The @dfn{function cell} holds the function definition of the symbol. ++When a symbol is used as a function, its function definition is used in ++its place. This cell is also used to make a symbol stand for a keymap ++or a keyboard macro, for editor command execution. Because each symbol ++has separate value and function cells, variables names and function names do ++not conflict. See @code{symbol-function} in @ref{Function Cells}. ++ ++@item Property list ++@cindex property list cell ++The @dfn{property list cell} holds the property list of the symbol. See ++@code{symbol-plist} in @ref{Property Lists}. ++@end table ++ ++ The print name cell always holds a string, and cannot be changed. The ++other three cells can be set individually to any specified Lisp object. ++ ++ The print name cell holds the string that is the name of the symbol. ++Since symbols are represented textually by their names, it is important ++not to have two symbols with the same name. The Lisp reader ensures ++this: every time it reads a symbol, it looks for an existing symbol with ++the specified name before it creates a new one. (In GNU Emacs Lisp, ++this lookup uses a hashing algorithm and an obarray; see @ref{Creating ++Symbols}.) ++ ++ The value cell holds the symbol's value as a variable ++(@pxref{Variables}). That is what you get if you evaluate the symbol as ++a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate ++value. Certain symbols have values that cannot be changed; these ++include @code{nil} and @code{t}, and any symbol whose name starts with ++@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}. ++ ++ We often refer to ``the function @code{foo}'' when we really mean ++the function stored in the function cell of the symbol @code{foo}. We ++make the distinction explicit only when necessary. In normal ++usage, the function cell usually contains a function ++(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the ++Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard ++macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and ++autoload objects (@pxref{Autoloading}) are also sometimes stored in ++the function cells of symbols. ++ ++ The property list cell normally should hold a correctly formatted ++property list (@pxref{Property Lists}), as a number of functions expect ++to see a property list there. ++ ++ The function cell or the value cell may be @dfn{void}, which means ++that the cell does not reference any object. (This is not the same ++thing as holding the symbol @code{void}, nor the same as holding the ++symbol @code{nil}.) Examining a function or value cell that is void ++results in an error, such as @samp{Symbol's value as variable is void}. ++ ++ The four functions @code{symbol-name}, @code{symbol-value}, ++@code{symbol-plist}, and @code{symbol-function} return the contents of ++the four cells of a symbol. Here as an example we show the contents of ++the four cells of the symbol @code{buffer-file-name}: ++ ++@example ++(symbol-name 'buffer-file-name) ++ @result{} "buffer-file-name" ++(symbol-value 'buffer-file-name) ++ @result{} "/gnu/elisp/symbols.texi" ++(symbol-function 'buffer-file-name) ++ @result{} # ++(symbol-plist 'buffer-file-name) ++ @result{} (variable-documentation 29529) ++@end example ++ ++@noindent ++Because this symbol is the variable which holds the name of the file ++being visited in the current buffer, the value cell contents we see are ++the name of the source file of this chapter of the Emacs Lisp Manual. ++The property list cell contains the list @code{(variable-documentation ++29529)} which tells the documentation functions where to find the ++documentation string for the variable @code{buffer-file-name} in the ++@file{DOC-@var{version}} file. (29529 is the offset from the beginning ++of the @file{DOC-@var{version}} file to where that documentation string ++begins---see @ref{Documentation Basics}.) The function cell contains ++the function for returning the name of the file. ++@code{buffer-file-name} names a primitive function, which has no read ++syntax and prints in hash notation (@pxref{Primitive Function Type}). A ++symbol naming a function written in Lisp would have a lambda expression ++(or a byte-code object) in this cell. ++ ++@node Definitions, Creating Symbols, Symbol Components, Symbols ++@section Defining Symbols ++@cindex definitions of symbols ++ ++ A @dfn{definition} in Lisp is a special form that announces your ++intention to use a certain symbol in a particular way. In Emacs Lisp, ++you can define a symbol as a variable, or define it as a function (or ++macro), or both independently. ++ ++ A definition construct typically specifies a value or meaning for the ++symbol for one kind of use, plus documentation for its meaning when used ++in this way. Thus, when you define a symbol as a variable, you can ++supply an initial value for the variable, plus documentation for the ++variable. ++ ++ @code{defvar} and @code{defconst} are special forms that define a ++symbol as a global variable. They are documented in detail in ++@ref{Defining Variables}. For defining user option variables that can ++be customized, use @code{defcustom} (@pxref{Customization}). ++ ++ @code{defun} defines a symbol as a function, creating a lambda ++expression and storing it in the function cell of the symbol. This ++lambda expression thus becomes the function definition of the symbol. ++(The term ``function definition,'' meaning the contents of the function ++cell, is derived from the idea that @code{defun} gives the symbol its ++definition as a function.) @code{defsubst} and @code{defalias} are two ++other ways of defining a function. @xref{Functions}. ++ ++ @code{defmacro} defines a symbol as a macro. It creates a macro ++object and stores it in the function cell of the symbol. Note that a ++given symbol can be a macro or a function, but not both at once, because ++both macro and function definitions are kept in the function cell, and ++that cell can hold only one Lisp object at any given time. ++@xref{Macros}. ++ ++ In Emacs Lisp, a definition is not required in order to use a symbol ++as a variable or function. Thus, you can make a symbol a global ++variable with @code{setq}, whether you define it first or not. The real ++purpose of definitions is to guide programmers and programming tools. ++They inform programmers who read the code that certain symbols are ++@emph{intended} to be used as variables, or as functions. In addition, ++utilities such as @file{etags} and @file{make-docfile} recognize ++definitions, and add appropriate information to tag tables and the ++@file{DOC-@var{version}} file. @xref{Accessing Documentation}. ++ ++@node Creating Symbols, Property Lists, Definitions, Symbols ++@section Creating and Interning Symbols ++@cindex reading symbols ++ ++ To understand how symbols are created in GNU Emacs Lisp, you must know ++how Lisp reads them. Lisp must ensure that it finds the same symbol ++every time it reads the same set of characters. Failure to do so would ++cause complete confusion. ++ ++@cindex symbol name hashing ++@cindex hashing ++@cindex obarray ++@cindex bucket (in obarray) ++ When the Lisp reader encounters a symbol, it reads all the characters ++of the name. Then it ``hashes'' those characters to find an index in a ++table called an @dfn{obarray}. Hashing is an efficient method of ++looking something up. For example, instead of searching a telephone ++book cover to cover when looking up Jan Jones, you start with the J's ++and go from there. That is a simple version of hashing. Each element ++of the obarray is a @dfn{bucket} which holds all the symbols with a ++given hash code; to look for a given name, it is sufficient to look ++through all the symbols in the bucket for that name's hash code. (The ++same idea is used for general Emacs hash tables, but they are a ++different data type; see @ref{Hash Tables}.) ++ ++@cindex interning ++ If a symbol with the desired name is found, the reader uses that ++symbol. If the obarray does not contain a symbol with that name, the ++reader makes a new symbol and adds it to the obarray. Finding or adding ++a symbol with a certain name is called @dfn{interning} it, and the ++symbol is then called an @dfn{interned symbol}. ++ ++ Interning ensures that each obarray has just one symbol with any ++particular name. Other like-named symbols may exist, but not in the ++same obarray. Thus, the reader gets the same symbols for the same ++names, as long as you keep reading with the same obarray. ++ ++ Interning usually happens automatically in the reader, but sometimes ++other programs need to do it. For example, after the @kbd{M-x} command ++obtains the command name as a string using the minibuffer, it then ++interns the string, to get the interned symbol with that name. ++ ++@cindex symbol equality ++@cindex uninterned symbol ++ No obarray contains all symbols; in fact, some symbols are not in any ++obarray. They are called @dfn{uninterned symbols}. An uninterned ++symbol has the same four cells as other symbols; however, the only way ++to gain access to it is by finding it in some other object or as the ++value of a variable. ++ ++ Creating an uninterned symbol is useful in generating Lisp code, ++because an uninterned symbol used as a variable in the code you generate ++cannot clash with any variables used in other Lisp programs. ++ ++ In Emacs Lisp, an obarray is actually a vector. Each element of the ++vector is a bucket; its value is either an interned symbol whose name ++hashes to that bucket, or 0 if the bucket is empty. Each interned ++symbol has an internal link (invisible to the user) to the next symbol ++in the bucket. Because these links are invisible, there is no way to ++find all the symbols in an obarray except using @code{mapatoms} (below). ++The order of symbols in a bucket is not significant. ++ ++ In an empty obarray, every element is 0, so you can create an obarray ++with @code{(make-vector @var{length} 0)}. @strong{This is the only ++valid way to create an obarray.} Prime numbers as lengths tend ++to result in good hashing; lengths one less than a power of two are also ++good. ++ ++ @strong{Do not try to put symbols in an obarray yourself.} This does ++not work---only @code{intern} can enter a symbol in an obarray properly. ++ ++@cindex CL note---symbol in obarrays ++@quotation ++@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in ++several obarrays. ++@end quotation ++ ++ Most of the functions below take a name and sometimes an obarray as ++arguments. A @code{wrong-type-argument} error is signaled if the name ++is not a string, or if the obarray is not a vector. ++ ++@defun symbol-name symbol ++This function returns the string that is @var{symbol}'s name. For example: ++ ++@example ++@group ++(symbol-name 'foo) ++ @result{} "foo" ++@end group ++@end example ++ ++@strong{Warning:} Changing the string by substituting characters does ++change the name of the symbol, but fails to update the obarray, so don't ++do it! ++@end defun ++ ++@defun make-symbol name ++This function returns a newly-allocated, uninterned symbol whose name is ++@var{name} (which must be a string). Its value and function definition ++are void, and its property list is @code{nil}. In the example below, ++the value of @code{sym} is not @code{eq} to @code{foo} because it is a ++distinct uninterned symbol whose name is also @samp{foo}. ++ ++@example ++(setq sym (make-symbol "foo")) ++ @result{} foo ++(eq sym 'foo) ++ @result{} nil ++@end example ++@end defun ++ ++@defun intern name &optional obarray ++This function returns the interned symbol whose name is @var{name}. If ++there is no such symbol in the obarray @var{obarray}, @code{intern} ++creates a new one, adds it to the obarray, and returns it. If ++@var{obarray} is omitted, the value of the global variable ++@code{obarray} is used. ++ ++@example ++(setq sym (intern "foo")) ++ @result{} foo ++(eq sym 'foo) ++ @result{} t ++ ++(setq sym1 (intern "foo" other-obarray)) ++ @result{} foo ++(eq sym1 'foo) ++ @result{} nil ++@end example ++@end defun ++ ++@cindex CL note---interning existing symbol ++@quotation ++@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol ++in an obarray. In Emacs Lisp, you cannot do this, because the argument ++to @code{intern} must be a string, not a symbol. ++@end quotation ++ ++@defun intern-soft name &optional obarray ++This function returns the symbol in @var{obarray} whose name is ++@var{name}, or @code{nil} if @var{obarray} has no symbol with that name. ++Therefore, you can use @code{intern-soft} to test whether a symbol with ++a given name is already interned. If @var{obarray} is omitted, the ++value of the global variable @code{obarray} is used. ++ ++The argument @var{name} may also be a symbol; in that case, ++the function returns @var{name} if @var{name} is interned ++in the specified obarray, and otherwise @code{nil}. ++ ++@smallexample ++(intern-soft "frazzle") ; @r{No such symbol exists.} ++ @result{} nil ++(make-symbol "frazzle") ; @r{Create an uninterned one.} ++ @result{} frazzle ++@group ++(intern-soft "frazzle") ; @r{That one cannot be found.} ++ @result{} nil ++@end group ++@group ++(setq sym (intern "frazzle")) ; @r{Create an interned one.} ++ @result{} frazzle ++@end group ++@group ++(intern-soft "frazzle") ; @r{That one can be found!} ++ @result{} frazzle ++@end group ++@group ++(eq sym 'frazzle) ; @r{And it is the same one.} ++ @result{} t ++@end group ++@end smallexample ++@end defun ++ ++@defvar obarray ++This variable is the standard obarray for use by @code{intern} and ++@code{read}. ++@end defvar ++ ++@defun mapatoms function &optional obarray ++@anchor{Definition of mapatoms} ++This function calls @var{function} once with each symbol in the obarray ++@var{obarray}. Then it returns @code{nil}. If @var{obarray} is ++omitted, it defaults to the value of @code{obarray}, the standard ++obarray for ordinary symbols. ++ ++@smallexample ++(setq count 0) ++ @result{} 0 ++(defun count-syms (s) ++ (setq count (1+ count))) ++ @result{} count-syms ++(mapatoms 'count-syms) ++ @result{} nil ++count ++ @result{} 1871 ++@end smallexample ++ ++See @code{documentation} in @ref{Accessing Documentation}, for another ++example using @code{mapatoms}. ++@end defun ++ ++@defun unintern symbol &optional obarray ++This function deletes @var{symbol} from the obarray @var{obarray}. If ++@code{symbol} is not actually in the obarray, @code{unintern} does ++nothing. If @var{obarray} is @code{nil}, the current obarray is used. ++ ++If you provide a string instead of a symbol as @var{symbol}, it stands ++for a symbol name. Then @code{unintern} deletes the symbol (if any) in ++the obarray which has that name. If there is no such symbol, ++@code{unintern} does nothing. ++ ++If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise ++it returns @code{nil}. ++@end defun ++ ++@node Property Lists,, Creating Symbols, Symbols ++@section Property Lists ++@cindex property list ++@cindex plist ++ ++ A @dfn{property list} (@dfn{plist} for short) is a list of paired ++elements. Each of the pairs associates a property name (usually a ++symbol) with a property or value. ++ ++ Every symbol has a cell that stores a property list (@pxref{Symbol ++Components}). This property list is used to record information about ++the symbol, such as its variable documentation and the name of the ++file where it was defined. ++ ++ Property lists can also be used in other contexts. For instance, ++you can assign property lists to character positions in a string or ++buffer. @xref{Text Properties}. ++ ++ The property names and values in a property list can be any Lisp ++objects, but the names are usually symbols. Property list functions ++compare the property names using @code{eq}. Here is an example of a ++property list, found on the symbol @code{progn} when the compiler is ++loaded: ++ ++@example ++(lisp-indent-function 0 byte-compile byte-compile-progn) ++@end example ++ ++@noindent ++Here @code{lisp-indent-function} and @code{byte-compile} are property ++names, and the other two elements are the corresponding values. ++ ++@menu ++* Plists and Alists:: Comparison of the advantages of property ++ lists and association lists. ++* Symbol Plists:: Functions to access symbols' property lists. ++* Other Plists:: Accessing property lists stored elsewhere. ++@end menu ++ ++@node Plists and Alists ++@subsection Property Lists and Association Lists ++@cindex plist vs. alist ++@cindex alist vs. plist ++ ++@cindex property lists vs association lists ++ Association lists (@pxref{Association Lists}) are very similar to ++property lists. In contrast to association lists, the order of the ++pairs in the property list is not significant since the property names ++must be distinct. ++ ++ Property lists are better than association lists for attaching ++information to various Lisp function names or variables. If your ++program keeps all of its associations in one association list, it will ++typically need to search that entire list each time it checks for an ++association. This could be slow. By contrast, if you keep the same ++information in the property lists of the function names or variables ++themselves, each search will scan only the length of one property list, ++which is usually short. This is why the documentation for a variable is ++recorded in a property named @code{variable-documentation}. The byte ++compiler likewise uses properties to record those functions needing ++special treatment. ++ ++ However, association lists have their own advantages. Depending on ++your application, it may be faster to add an association to the front of ++an association list than to update a property. All properties for a ++symbol are stored in the same property list, so there is a possibility ++of a conflict between different uses of a property name. (For this ++reason, it is a good idea to choose property names that are probably ++unique, such as by beginning the property name with the program's usual ++name-prefix for variables and functions.) An association list may be ++used like a stack where associations are pushed on the front of the list ++and later discarded; this is not possible with a property list. ++ ++@node Symbol Plists ++@subsection Property List Functions for Symbols ++ ++@defun symbol-plist symbol ++This function returns the property list of @var{symbol}. ++@end defun ++ ++@defun setplist symbol plist ++This function sets @var{symbol}'s property list to @var{plist}. ++Normally, @var{plist} should be a well-formed property list, but this is ++not enforced. The return value is @var{plist}. ++ ++@smallexample ++(setplist 'foo '(a 1 b (2 3) c nil)) ++ @result{} (a 1 b (2 3) c nil) ++(symbol-plist 'foo) ++ @result{} (a 1 b (2 3) c nil) ++@end smallexample ++ ++For symbols in special obarrays, which are not used for ordinary ++purposes, it may make sense to use the property list cell in a ++nonstandard fashion; in fact, the abbrev mechanism does so ++(@pxref{Abbrevs}). ++@end defun ++ ++@defun get symbol property ++This function finds the value of the property named @var{property} in ++@var{symbol}'s property list. If there is no such property, @code{nil} ++is returned. Thus, there is no distinction between a value of ++@code{nil} and the absence of the property. ++ ++The name @var{property} is compared with the existing property names ++using @code{eq}, so any object is a legitimate property. ++ ++See @code{put} for an example. ++@end defun ++ ++@defun put symbol property value ++This function puts @var{value} onto @var{symbol}'s property list under ++the property name @var{property}, replacing any previous property value. ++The @code{put} function returns @var{value}. ++ ++@smallexample ++(put 'fly 'verb 'transitive) ++ @result{}'transitive ++(put 'fly 'noun '(a buzzing little bug)) ++ @result{} (a buzzing little bug) ++(get 'fly 'verb) ++ @result{} transitive ++(symbol-plist 'fly) ++ @result{} (verb transitive noun (a buzzing little bug)) ++@end smallexample ++@end defun ++ ++@node Other Plists ++@subsection Property Lists Outside Symbols ++ ++ These functions are useful for manipulating property lists ++that are stored in places other than symbols: ++ ++@defun plist-get plist property ++This returns the value of the @var{property} property stored in the ++property list @var{plist}. It accepts a malformed @var{plist} ++argument. If @var{property} is not found in the @var{plist}, it ++returns @code{nil}. For example, ++ ++@example ++(plist-get '(foo 4) 'foo) ++ @result{} 4 ++(plist-get '(foo 4 bad) 'foo) ++ @result{} 4 ++(plist-get '(foo 4 bad) 'bad) ++ @result{} @code{nil} ++(plist-get '(foo 4 bad) 'bar) ++ @result{} nil ++@end example ++@end defun ++ ++@defun plist-put plist property value ++This stores @var{value} as the value of the @var{property} property in ++the property list @var{plist}. It may modify @var{plist} destructively, ++or it may construct a new list structure without altering the old. The ++function returns the modified property list, so you can store that back ++in the place where you got @var{plist}. For example, ++ ++@example ++(setq my-plist '(bar t foo 4)) ++ @result{} (bar t foo 4) ++(setq my-plist (plist-put my-plist 'foo 69)) ++ @result{} (bar t foo 69) ++(setq my-plist (plist-put my-plist 'quux '(a))) ++ @result{} (bar t foo 69 quux (a)) ++@end example ++@end defun ++ ++ You could define @code{put} in terms of @code{plist-put} as follows: ++ ++@example ++(defun put (symbol prop value) ++ (setplist symbol ++ (plist-put (symbol-plist symbol) prop value))) ++@end example ++ ++@defun lax-plist-get plist property ++Like @code{plist-get} except that it compares properties ++using @code{equal} instead of @code{eq}. ++@end defun ++ ++@defun lax-plist-put plist property value ++Like @code{plist-put} except that it compares properties ++using @code{equal} instead of @code{eq}. ++@end defun ++ ++@defun plist-member plist property ++This returns non-@code{nil} if @var{plist} contains the given ++@var{property}. Unlike @code{plist-get}, this allows you to distinguish ++between a missing property and a property with the value @code{nil}. ++The value is actually the tail of @var{plist} whose @code{car} is ++@var{property}. ++@end defun ++ ++@ignore ++ arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce ++@end ignore +diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi +new file mode 100644 +index 0000000..5b7be7c +--- /dev/null ++++ b/doc/lispref/syntax.texi +@@ -0,0 +1,1196 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/syntax ++@node Syntax Tables, Abbrevs, Searching and Matching, Top ++@chapter Syntax Tables ++@cindex parsing buffer text ++@cindex syntax table ++@cindex text parsing ++ ++ A @dfn{syntax table} specifies the syntactic textual function of each ++character. This information is used by the @dfn{parsing functions}, the ++complex movement commands, and others to determine where words, symbols, ++and other syntactic constructs begin and end. The current syntax table ++controls the meaning of the word motion functions (@pxref{Word Motion}) ++and the list motion functions (@pxref{List Motion}), as well as the ++functions in this chapter. ++ ++@menu ++* Basics: Syntax Basics. Basic concepts of syntax tables. ++* Desc: Syntax Descriptors. How characters are classified. ++* Syntax Table Functions:: How to create, examine and alter syntax tables. ++* Syntax Properties:: Overriding syntax with text properties. ++* Motion and Syntax:: Moving over characters with certain syntaxes. ++* Parsing Expressions:: Parsing balanced expressions ++ using the syntax table. ++* Standard Syntax Tables:: Syntax tables used by various major modes. ++* Syntax Table Internals:: How syntax table information is stored. ++* Categories:: Another way of classifying character syntax. ++@end menu ++ ++@node Syntax Basics ++@section Syntax Table Concepts ++ ++@ifnottex ++ A @dfn{syntax table} provides Emacs with the information that ++determines the syntactic use of each character in a buffer. This ++information is used by the parsing commands, the complex movement ++commands, and others to determine where words, symbols, and other ++syntactic constructs begin and end. The current syntax table controls ++the meaning of the word motion functions (@pxref{Word Motion}) and the ++list motion functions (@pxref{List Motion}) as well as the functions in ++this chapter. ++@end ifnottex ++ ++ A syntax table is a char-table (@pxref{Char-Tables}). The element at ++index @var{c} describes the character with code @var{c}. The element's ++value should be a list that encodes the syntax of the character in ++question. ++ ++ Syntax tables are used only for moving across text, not for the Emacs ++Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp ++expressions, and these rules cannot be changed. (Some Lisp systems ++provide ways to redefine the read syntax, but we decided to leave this ++feature out of Emacs Lisp for simplicity.) ++ ++ Each buffer has its own major mode, and each major mode has its own ++idea of the syntactic class of various characters. For example, in Lisp ++mode, the character @samp{;} begins a comment, but in C mode, it ++terminates a statement. To support these variations, Emacs makes the ++choice of syntax table local to each buffer. Typically, each major ++mode has its own syntax table and installs that table in each buffer ++that uses that mode. Changing this table alters the syntax in all ++those buffers as well as in any buffers subsequently put in that mode. ++Occasionally several similar modes share one syntax table. ++@xref{Example Major Modes}, for an example of how to set up a syntax ++table. ++ ++A syntax table can inherit the data for some characters from the ++standard syntax table, while specifying other characters itself. The ++``inherit'' syntax class means ``inherit this character's syntax from ++the standard syntax table.'' Just changing the standard syntax for a ++character affects all syntax tables that inherit from it. ++ ++@defun syntax-table-p object ++This function returns @code{t} if @var{object} is a syntax table. ++@end defun ++ ++@node Syntax Descriptors ++@section Syntax Descriptors ++@cindex syntax class ++ ++ This section describes the syntax classes and flags that denote the ++syntax of a character, and how they are represented as a @dfn{syntax ++descriptor}, which is a Lisp string that you pass to ++@code{modify-syntax-entry} to specify the syntax you want. ++ ++ The syntax table specifies a syntax class for each character. There ++is no necessary relationship between the class of a character in one ++syntax table and its class in any other table. ++ ++ Each class is designated by a mnemonic character, which serves as the ++name of the class when you need to specify a class. Usually the ++designator character is one that is often assigned that class; however, ++its meaning as a designator is unvarying and independent of what syntax ++that character currently has. Thus, @samp{\} as a designator character ++always gives ``escape character'' syntax, regardless of what syntax ++@samp{\} currently has. ++ ++@cindex syntax descriptor ++ A syntax descriptor is a Lisp string that specifies a syntax class, a ++matching character (used only for the parenthesis classes) and flags. ++The first character is the designator for a syntax class. The second ++character is the character to match; if it is unused, put a space there. ++Then come the characters for any desired flags. If no matching ++character or flags are needed, one character is sufficient. ++ ++ For example, the syntax descriptor for the character @samp{*} in C ++mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot ++unused, second character of a comment-starter, first character of a ++comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e., ++punctuation, matching character slot unused, first character of a ++comment-starter, second character of a comment-ender). ++ ++@menu ++* Syntax Class Table:: Table of syntax classes. ++* Syntax Flags:: Additional flags each character can have. ++@end menu ++ ++@node Syntax Class Table ++@subsection Table of Syntax Classes ++ ++ Here is a table of syntax classes, the characters that stand for them, ++their meanings, and examples of their use. ++ ++@deffn {Syntax class} @w{whitespace character} ++@dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-}) ++separate symbols and words from each other. Typically, whitespace ++characters have no other syntactic significance, and multiple whitespace ++characters are syntactically equivalent to a single one. Space, tab, ++newline and formfeed are classified as whitespace in almost all major ++modes. ++@end deffn ++ ++@deffn {Syntax class} @w{word constituent} ++@dfn{Word constituents} (designated by @samp{w}) are parts of words in ++human languages, and are typically used in variable and command names ++in programs. All upper- and lower-case letters, and the digits, are ++typically word constituents. ++@end deffn ++ ++@deffn {Syntax class} @w{symbol constituent} ++@dfn{Symbol constituents} (designated by @samp{_}) are the extra ++characters that are used in variable and command names along with word ++constituents. For example, the symbol constituents class is used in ++Lisp mode to indicate that certain characters may be part of symbol ++names even though they are not part of English words. These characters ++are @samp{$&*+-_<>}. In standard C, the only non-word-constituent ++character that is valid in symbols is underscore (@samp{_}). ++@end deffn ++ ++@deffn {Syntax class} @w{punctuation character} ++@dfn{Punctuation characters} (designated by @samp{.}) are those ++characters that are used as punctuation in English, or are used in some ++way in a programming language to separate symbols from one another. ++Some programming language modes, such as Emacs Lisp mode, have no ++characters in this class since the few characters that are not symbol or ++word constituents all have other uses. Other programming language modes, ++such as C mode, use punctuation syntax for operators. ++@end deffn ++ ++@deffn {Syntax class} @w{open parenthesis character} ++@deffnx {Syntax class} @w{close parenthesis character} ++@cindex parenthesis syntax ++Open and close @dfn{parenthesis characters} are characters used in ++dissimilar pairs to surround sentences or expressions. Such a grouping ++is begun with an open parenthesis character and terminated with a close. ++Each open parenthesis character matches a particular close parenthesis ++character, and vice versa. Normally, Emacs indicates momentarily the ++matching open parenthesis when you insert a close parenthesis. ++@xref{Blinking}. ++ ++The class of open parentheses is designated by @samp{(}, and that of ++close parentheses by @samp{)}. ++ ++In English text, and in C code, the parenthesis pairs are @samp{()}, ++@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists and ++vectors (@samp{()} and @samp{[]}) are classified as parenthesis ++characters. ++@end deffn ++ ++@deffn {Syntax class} @w{string quote} ++@dfn{String quote characters} (designated by @samp{"}) are used in ++many languages, including Lisp and C, to delimit string constants. The ++same string quote character appears at the beginning and the end of a ++string. Such quoted strings do not nest. ++ ++The parsing facilities of Emacs consider a string as a single token. ++The usual syntactic meanings of the characters in the string are ++suppressed. ++ ++The Lisp modes have two string quote characters: double-quote (@samp{"}) ++and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it ++is used in Common Lisp. C also has two string quote characters: ++double-quote for strings, and single-quote (@samp{'}) for character ++constants. ++ ++English text has no string quote characters because English is not a ++programming language. Although quotation marks are used in English, ++we do not want them to turn off the usual syntactic properties of ++other characters in the quotation. ++@end deffn ++ ++@deffn {Syntax class} @w{escape-syntax character} ++An @dfn{escape character} (designated by @samp{\}) starts an escape ++sequence such as is used in C string and character constants. The ++character @samp{\} belongs to this class in both C and Lisp. (In C, it ++is used thus only inside strings, but it turns out to cause no trouble ++to treat it this way throughout C code.) ++ ++Characters in this class count as part of words if ++@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. ++@end deffn ++ ++@deffn {Syntax class} @w{character quote} ++A @dfn{character quote character} (designated by @samp{/}) quotes the ++following character so that it loses its normal syntactic meaning. This ++differs from an escape character in that only the character immediately ++following is ever affected. ++ ++Characters in this class count as part of words if ++@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. ++ ++This class is used for backslash in @TeX{} mode. ++@end deffn ++ ++@deffn {Syntax class} @w{paired delimiter} ++@dfn{Paired delimiter characters} (designated by @samp{$}) are like ++string quote characters except that the syntactic properties of the ++characters between the delimiters are not suppressed. Only @TeX{} mode ++uses a paired delimiter presently---the @samp{$} that both enters and ++leaves math mode. ++@end deffn ++ ++@deffn {Syntax class} @w{expression prefix} ++An @dfn{expression prefix operator} (designated by @samp{'}) is used for ++syntactic operators that are considered as part of an expression if they ++appear next to one. In Lisp modes, these characters include the ++apostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used in ++macros), and @samp{#} (used in the read syntax for certain data types). ++@end deffn ++ ++@deffn {Syntax class} @w{comment starter} ++@deffnx {Syntax class} @w{comment ender} ++@cindex comment syntax ++The @dfn{comment starter} and @dfn{comment ender} characters are used in ++various languages to delimit comments. These classes are designated ++by @samp{<} and @samp{>}, respectively. ++ ++English text has no comment characters. In Lisp, the semicolon ++(@samp{;}) starts a comment and a newline or formfeed ends one. ++@end deffn ++ ++@deffn {Syntax class} @w{inherit standard syntax} ++This syntax class does not specify a particular syntax. It says to look ++in the standard syntax table to find the syntax of this character. The ++designator for this syntax class is @samp{@@}. ++@end deffn ++ ++@deffn {Syntax class} @w{generic comment delimiter} ++A @dfn{generic comment delimiter} (designated by @samp{!}) starts ++or ends a special kind of comment. @emph{Any} generic comment delimiter ++matches @emph{any} generic comment delimiter, but they cannot match ++a comment starter or comment ender; generic comment delimiters can only ++match each other. ++ ++This syntax class is primarily meant for use with the ++@code{syntax-table} text property (@pxref{Syntax Properties}). You can ++mark any range of characters as forming a comment, by giving the first ++and last characters of the range @code{syntax-table} properties ++identifying them as generic comment delimiters. ++@end deffn ++ ++@deffn {Syntax class} @w{generic string delimiter} ++A @dfn{generic string delimiter} (designated by @samp{|}) starts or ends ++a string. This class differs from the string quote class in that @emph{any} ++generic string delimiter can match any other generic string delimiter; but ++they do not match ordinary string quote characters. ++ ++This syntax class is primarily meant for use with the ++@code{syntax-table} text property (@pxref{Syntax Properties}). You can ++mark any range of characters as forming a string constant, by giving the ++first and last characters of the range @code{syntax-table} properties ++identifying them as generic string delimiters. ++@end deffn ++ ++@node Syntax Flags ++@subsection Syntax Flags ++@cindex syntax flags ++ ++ In addition to the classes, entries for characters in a syntax table ++can specify flags. There are seven possible flags, represented by the ++characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{n}, ++and @samp{p}. ++ ++ All the flags except @samp{n} and @samp{p} are used to describe ++multi-character comment delimiters. The digit flags indicate that a ++character can @emph{also} be part of a comment sequence, in addition to ++the syntactic properties associated with its character class. The flags ++are independent of the class and each other for the sake of characters ++such as @samp{*} in C mode, which is a punctuation character, @emph{and} ++the second character of a start-of-comment sequence (@samp{/*}), ++@emph{and} the first character of an end-of-comment sequence ++(@samp{*/}). ++ ++ Here is a table of the possible flags for a character @var{c}, ++and what they mean: ++ ++@itemize @bullet ++@item ++@samp{1} means @var{c} is the start of a two-character comment-start ++sequence. ++ ++@item ++@samp{2} means @var{c} is the second character of such a sequence. ++ ++@item ++@samp{3} means @var{c} is the start of a two-character comment-end ++sequence. ++ ++@item ++@samp{4} means @var{c} is the second character of such a sequence. ++ ++@item ++@c Emacs 19 feature ++@samp{b} means that @var{c} as a comment delimiter belongs to the ++alternative ``b'' comment style. ++ ++Emacs supports two comment styles simultaneously in any one syntax ++table. This is for the sake of C++. Each style of comment syntax has ++its own comment-start sequence and its own comment-end sequence. Each ++comment must stick to one style or the other; thus, if it starts with ++the comment-start sequence of style ``b,'' it must also end with the ++comment-end sequence of style ``b.'' ++ ++The two comment-start sequences must begin with the same character; only ++the second character may differ. Mark the second character of the ++``b''-style comment-start sequence with the @samp{b} flag. ++ ++A comment-end sequence (one or two characters) applies to the ``b'' ++style if its first character has the @samp{b} flag set; otherwise, it ++applies to the ``a'' style. ++ ++The appropriate comment syntax settings for C++ are as follows: ++ ++@table @asis ++@item @samp{/} ++@samp{124b} ++@item @samp{*} ++@samp{23} ++@item newline ++@samp{>b} ++@end table ++ ++This defines four comment-delimiting sequences: ++ ++@table @asis ++@item @samp{/*} ++This is a comment-start sequence for ``a'' style because the ++second character, @samp{*}, does not have the @samp{b} flag. ++ ++@item @samp{//} ++This is a comment-start sequence for ``b'' style because the second ++character, @samp{/}, does have the @samp{b} flag. ++ ++@item @samp{*/} ++This is a comment-end sequence for ``a'' style because the first ++character, @samp{*}, does not have the @samp{b} flag. ++ ++@item newline ++This is a comment-end sequence for ``b'' style, because the newline ++character has the @samp{b} flag. ++@end table ++ ++@item ++@samp{n} on a comment delimiter character specifies ++that this kind of comment can be nested. For a two-character ++comment delimiter, @samp{n} on either character makes it ++nestable. ++ ++@item ++@c Emacs 19 feature ++@samp{p} identifies an additional ``prefix character'' for Lisp syntax. ++These characters are treated as whitespace when they appear between ++expressions. When they appear within an expression, they are handled ++according to their usual syntax classes. ++ ++The function @code{backward-prefix-chars} moves back over these ++characters, as well as over characters whose primary syntax class is ++prefix (@samp{'}). @xref{Motion and Syntax}. ++@end itemize ++ ++@node Syntax Table Functions ++@section Syntax Table Functions ++ ++ In this section we describe functions for creating, accessing and ++altering syntax tables. ++ ++@defun make-syntax-table &optional table ++This function creates a new syntax table, with all values initialized ++to @code{nil}. If @var{table} is non-@code{nil}, it becomes the ++parent of the new syntax table, otherwise the standard syntax table is ++the parent. Like all char-tables, a syntax table inherits from its ++parent. Thus the original syntax of all characters in the returned ++syntax table is determined by the parent. @xref{Char-Tables}. ++ ++Most major mode syntax tables are created in this way. ++@end defun ++ ++@defun copy-syntax-table &optional table ++This function constructs a copy of @var{table} and returns it. If ++@var{table} is not supplied (or is @code{nil}), it returns a copy of the ++standard syntax table. Otherwise, an error is signaled if @var{table} is ++not a syntax table. ++@end defun ++ ++@deffn Command modify-syntax-entry char syntax-descriptor &optional table ++This function sets the syntax entry for @var{char} according to ++@var{syntax-descriptor}. @var{char} can be a character, or a cons ++cell of the form @code{(@var{min} . @var{max})}; in the latter case, ++the function sets the syntax entries for all characters in the range ++between @var{min} and @var{max}, inclusive. ++ ++The syntax is changed only for @var{table}, which defaults to the ++current buffer's syntax table, and not in any other syntax table. The ++argument @var{syntax-descriptor} specifies the desired syntax; this is ++a string beginning with a class designator character, and optionally ++containing a matching character and flags as well. @xref{Syntax ++Descriptors}. ++ ++This function always returns @code{nil}. The old syntax information in ++the table for this character is discarded. ++ ++An error is signaled if the first character of the syntax descriptor is not ++one of the seventeen syntax class designator characters. An error is also ++signaled if @var{char} is not a character. ++ ++@example ++@group ++@exdent @r{Examples:} ++ ++;; @r{Put the space character in class whitespace.} ++(modify-syntax-entry ?\s " ") ++ @result{} nil ++@end group ++ ++@group ++;; @r{Make @samp{$} an open parenthesis character,} ++;; @r{with @samp{^} as its matching close.} ++(modify-syntax-entry ?$ "(^") ++ @result{} nil ++@end group ++ ++@group ++;; @r{Make @samp{^} a close parenthesis character,} ++;; @r{with @samp{$} as its matching open.} ++(modify-syntax-entry ?^ ")$") ++ @result{} nil ++@end group ++ ++@group ++;; @r{Make @samp{/} a punctuation character,} ++;; @r{the first character of a start-comment sequence,} ++;; @r{and the second character of an end-comment sequence.} ++;; @r{This is used in C mode.} ++(modify-syntax-entry ?/ ". 14") ++ @result{} nil ++@end group ++@end example ++@end deffn ++ ++@defun char-syntax character ++This function returns the syntax class of @var{character}, represented ++by its mnemonic designator character. This returns @emph{only} the ++class, not any matching parenthesis or flags. ++ ++An error is signaled if @var{char} is not a character. ++ ++The following examples apply to C mode. The first example shows that ++the syntax class of space is whitespace (represented by a space). The ++second example shows that the syntax of @samp{/} is punctuation. This ++does not show the fact that it is also part of comment-start and -end ++sequences. The third example shows that open parenthesis is in the class ++of open parentheses. This does not show the fact that it has a matching ++character, @samp{)}. ++ ++@example ++@group ++(string (char-syntax ?\s)) ++ @result{} " " ++@end group ++ ++@group ++(string (char-syntax ?/)) ++ @result{} "." ++@end group ++ ++@group ++(string (char-syntax ?\()) ++ @result{} "(" ++@end group ++@end example ++ ++We use @code{string} to make it easier to see the character returned by ++@code{char-syntax}. ++@end defun ++ ++@defun set-syntax-table table ++This function makes @var{table} the syntax table for the current buffer. ++It returns @var{table}. ++@end defun ++ ++@defun syntax-table ++This function returns the current syntax table, which is the table for ++the current buffer. ++@end defun ++ ++@defmac with-syntax-table @var{table} @var{body}@dots{} ++This macro executes @var{body} using @var{table} as the current syntax ++table. It returns the value of the last form in @var{body}, after ++restoring the old current syntax table. ++ ++Since each buffer has its own current syntax table, we should make that ++more precise: @code{with-syntax-table} temporarily alters the current ++syntax table of whichever buffer is current at the time the macro ++execution starts. Other buffers are not affected. ++@end defmac ++ ++@node Syntax Properties ++@section Syntax Properties ++@kindex syntax-table @r{(text property)} ++ ++When the syntax table is not flexible enough to specify the syntax of ++a language, you can use @code{syntax-table} text properties to ++override the syntax table for specific character occurrences in the ++buffer. @xref{Text Properties}. You can use Font Lock mode to set ++@code{syntax-table} text properties. @xref{Setting Syntax ++Properties}. ++ ++The valid values of @code{syntax-table} text property are: ++ ++@table @asis ++@item @var{syntax-table} ++If the property value is a syntax table, that table is used instead of ++the current buffer's syntax table to determine the syntax for this ++occurrence of the character. ++ ++@item @code{(@var{syntax-code} . @var{matching-char})} ++A cons cell of this format specifies the syntax for this ++occurrence of the character. (@pxref{Syntax Table Internals}) ++ ++@item @code{nil} ++If the property is @code{nil}, the character's syntax is determined from ++the current syntax table in the usual way. ++@end table ++ ++@defvar parse-sexp-lookup-properties ++If this is non-@code{nil}, the syntax scanning functions pay attention ++to syntax text properties. Otherwise they use only the current syntax ++table. ++@end defvar ++ ++@node Motion and Syntax ++@section Motion and Syntax ++ ++ This section describes functions for moving across characters that ++have certain syntax classes. ++ ++@defun skip-syntax-forward syntaxes &optional limit ++This function moves point forward across characters having syntax ++classes mentioned in @var{syntaxes} (a string of syntax class ++characters). It stops when it encounters the end of the buffer, or ++position @var{limit} (if specified), or a character it is not supposed ++to skip. ++ ++If @var{syntaxes} starts with @samp{^}, then the function skips ++characters whose syntax is @emph{not} in @var{syntaxes}. ++ ++The return value is the distance traveled, which is a nonnegative ++integer. ++@end defun ++ ++@defun skip-syntax-backward syntaxes &optional limit ++This function moves point backward across characters whose syntax ++classes are mentioned in @var{syntaxes}. It stops when it encounters ++the beginning of the buffer, or position @var{limit} (if specified), or ++a character it is not supposed to skip. ++ ++If @var{syntaxes} starts with @samp{^}, then the function skips ++characters whose syntax is @emph{not} in @var{syntaxes}. ++ ++The return value indicates the distance traveled. It is an integer that ++is zero or less. ++@end defun ++ ++@defun backward-prefix-chars ++This function moves point backward over any number of characters with ++expression prefix syntax. This includes both characters in the ++expression prefix syntax class, and characters with the @samp{p} flag. ++@end defun ++ ++@node Parsing Expressions ++@section Parsing Expressions ++ ++ This section describes functions for parsing and scanning balanced ++expressions, also known as @dfn{sexps}. Basically, a sexp is either a ++balanced parenthetical grouping, a string, or a symbol name (a ++sequence of characters whose syntax is either word constituent or ++symbol constituent). However, characters whose syntax is expression ++prefix are treated as part of the sexp if they appear next to it. ++ ++ The syntax table controls the interpretation of characters, so these ++functions can be used for Lisp expressions when in Lisp mode and for C ++expressions when in C mode. @xref{List Motion}, for convenient ++higher-level functions for moving over balanced expressions. ++ ++ A character's syntax controls how it changes the state of the ++parser, rather than describing the state itself. For example, a ++string delimiter character toggles the parser state between ++``in-string'' and ``in-code,'' but the syntax of characters does not ++directly say whether they are inside a string. For example (note that ++15 is the syntax code for generic string delimiters), ++ ++@example ++(put-text-property 1 9 'syntax-table '(15 . nil)) ++@end example ++ ++@noindent ++does not tell Emacs that the first eight chars of the current buffer ++are a string, but rather that they are all string delimiters. As a ++result, Emacs treats them as four consecutive empty string constants. ++ ++@menu ++* Motion via Parsing:: Motion functions that work by parsing. ++* Position Parse:: Determining the syntactic state of a position. ++* Parser State:: How Emacs represents a syntactic state. ++* Low-Level Parsing:: Parsing across a specified region. ++* Control Parsing:: Parameters that affect parsing. ++@end menu ++ ++@node Motion via Parsing ++@subsection Motion Commands Based on Parsing ++ ++ This section describes simple point-motion functions that operate ++based on parsing expressions. ++ ++@defun scan-lists from count depth ++This function scans forward @var{count} balanced parenthetical groupings ++from position @var{from}. It returns the position where the scan stops. ++If @var{count} is negative, the scan moves backwards. ++ ++If @var{depth} is nonzero, parenthesis depth counting begins from that ++value. The only candidates for stopping are places where the depth in ++parentheses becomes zero; @code{scan-lists} counts @var{count} such ++places and then stops. Thus, a positive value for @var{depth} means go ++out @var{depth} levels of parenthesis. ++ ++Scanning ignores comments if @code{parse-sexp-ignore-comments} is ++non-@code{nil}. ++ ++If the scan reaches the beginning or end of the buffer (or its ++accessible portion), and the depth is not zero, an error is signaled. ++If the depth is zero but the count is not used up, @code{nil} is ++returned. ++@end defun ++ ++@defun scan-sexps from count ++This function scans forward @var{count} sexps from position @var{from}. ++It returns the position where the scan stops. If @var{count} is ++negative, the scan moves backwards. ++ ++Scanning ignores comments if @code{parse-sexp-ignore-comments} is ++non-@code{nil}. ++ ++If the scan reaches the beginning or end of (the accessible part of) the ++buffer while in the middle of a parenthetical grouping, an error is ++signaled. If it reaches the beginning or end between groupings but ++before count is used up, @code{nil} is returned. ++@end defun ++ ++@defun forward-comment count ++This function moves point forward across @var{count} complete comments ++ (that is, including the starting delimiter and the terminating ++delimiter if any), plus any whitespace encountered on the way. It ++moves backward if @var{count} is negative. If it encounters anything ++other than a comment or whitespace, it stops, leaving point at the ++place where it stopped. This includes (for instance) finding the end ++of a comment when moving forward and expecting the beginning of one. ++The function also stops immediately after moving over the specified ++number of complete comments. If @var{count} comments are found as ++expected, with nothing except whitespace between them, it returns ++@code{t}; otherwise it returns @code{nil}. ++ ++This function cannot tell whether the ``comments'' it traverses are ++embedded within a string. If they look like comments, it treats them ++as comments. ++@end defun ++ ++To move forward over all comments and whitespace following point, use ++@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a good ++argument to use, because the number of comments in the buffer cannot ++exceed that many. ++ ++@node Position Parse ++@subsection Finding the Parse State for a Position ++ ++ For syntactic analysis, such as in indentation, often the useful ++thing is to compute the syntactic state corresponding to a given buffer ++position. This function does that conveniently. ++ ++@defun syntax-ppss &optional pos ++This function returns the parser state (see next section) that the ++parser would reach at position @var{pos} starting from the beginning ++of the buffer. This is equivalent to @code{(parse-partial-sexp ++(point-min) @var{pos})}, except that @code{syntax-ppss} uses a cache ++to speed up the computation. Due to this optimization, the 2nd value ++(previous complete subexpression) and 6th value (minimum parenthesis ++depth) of the returned parser state are not meaningful. ++@end defun ++ ++ @code{syntax-ppss} automatically hooks itself to ++@code{before-change-functions} to keep its cache consistent. But ++updating can fail if @code{syntax-ppss} is called while ++@code{before-change-functions} is temporarily let-bound, or if the ++buffer is modified without obeying the hook, such as when using ++@code{inhibit-modification-hooks}. For this reason, it is sometimes ++necessary to flush the cache manually. ++ ++@defun syntax-ppss-flush-cache beg &rest ignored-args ++This function flushes the cache used by @code{syntax-ppss}, starting ++at position @var{beg}. The remaining arguments, @var{ignored-args}, ++are ignored; this function accepts them so that it can be directly ++used on hooks such as @code{before-change-functions} (@pxref{Change ++Hooks}). ++@end defun ++ ++ Major modes can make @code{syntax-ppss} run faster by specifying ++where it needs to start parsing. ++ ++@defvar syntax-begin-function ++If this is non-@code{nil}, it should be a function that moves to an ++earlier buffer position where the parser state is equivalent to ++@code{nil}---in other words, a position outside of any comment, ++string, or parenthesis. @code{syntax-ppss} uses it to further ++optimize its computations, when the cache gives no help. ++@end defvar ++ ++@node Parser State ++@subsection Parser State ++@cindex parser state ++ ++ A @dfn{parser state} is a list of ten elements describing the final ++state of parsing text syntactically as part of an expression. The ++parsing functions in the following sections return a parser state as ++the value, and in some cases accept one as an argument also, so that ++you can resume parsing after it stops. Here are the meanings of the ++elements of the parser state: ++ ++@enumerate 0 ++@item ++The depth in parentheses, counting from 0. @strong{Warning:} this can ++be negative if there are more close parens than open parens between ++the start of the defun and point. ++ ++@item ++@cindex innermost containing parentheses ++The character position of the start of the innermost parenthetical ++grouping containing the stopping point; @code{nil} if none. ++ ++@item ++@cindex previous complete subexpression ++The character position of the start of the last complete subexpression ++terminated; @code{nil} if none. ++ ++@item ++@cindex inside string ++Non-@code{nil} if inside a string. More precisely, this is the ++character that will terminate the string, or @code{t} if a generic ++string delimiter character should terminate it. ++ ++@item ++@cindex inside comment ++@code{t} if inside a comment (of either style), ++or the comment nesting level if inside a kind of comment ++that can be nested. ++ ++@item ++@cindex quote character ++@code{t} if point is just after a quote character. ++ ++@item ++The minimum parenthesis depth encountered during this scan. ++ ++@item ++What kind of comment is active: @code{nil} for a comment of style ++``a'' or when not inside a comment, @code{t} for a comment of style ++``b,'' and @code{syntax-table} for a comment that should be ended by a ++generic comment delimiter character. ++ ++@item ++The string or comment start position. While inside a comment, this is ++the position where the comment began; while inside a string, this is the ++position where the string began. When outside of strings and comments, ++this element is @code{nil}. ++ ++@item ++Internal data for continuing the parsing. The meaning of this ++data is subject to change; it is used if you pass this list ++as the @var{state} argument to another call. ++@end enumerate ++ ++ Elements 1, 2, and 6 are ignored in a state which you pass as an ++argument to continue parsing, and elements 8 and 9 are used only in ++trivial cases. Those elements serve primarily to convey information ++to the Lisp program which does the parsing. ++ ++ One additional piece of useful information is available from a ++parser state using this function: ++ ++@defun syntax-ppss-toplevel-pos state ++This function extracts, from parser state @var{state}, the last ++position scanned in the parse which was at top level in grammatical ++structure. ``At top level'' means outside of any parentheses, ++comments, or strings. ++ ++The value is @code{nil} if @var{state} represents a parse which has ++arrived at a top level position. ++@end defun ++ ++ We have provided this access function rather than document how the ++data is represented in the state, because we plan to change the ++representation in the future. ++ ++@node Low-Level Parsing ++@subsection Low-Level Parsing ++ ++ The most basic way to use the expression parser is to tell it ++to start at a given position with a certain state, and parse up to ++a specified end position. ++ ++@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment ++This function parses a sexp in the current buffer starting at ++@var{start}, not scanning past @var{limit}. It stops at position ++@var{limit} or when certain criteria described below are met, and sets ++point to the location where parsing stops. It returns a parser state ++describing the status of the parse at the point where it stops. ++ ++@cindex parenthesis depth ++If the third argument @var{target-depth} is non-@code{nil}, parsing ++stops if the depth in parentheses becomes equal to @var{target-depth}. ++The depth starts at 0, or at whatever is given in @var{state}. ++ ++If the fourth argument @var{stop-before} is non-@code{nil}, parsing ++stops when it comes to any character that starts a sexp. If ++@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the ++start of a comment. If @var{stop-comment} is the symbol ++@code{syntax-table}, parsing stops after the start of a comment or a ++string, or the end of a comment or a string, whichever comes first. ++ ++If @var{state} is @code{nil}, @var{start} is assumed to be at the top ++level of parenthesis structure, such as the beginning of a function ++definition. Alternatively, you might wish to resume parsing in the ++middle of the structure. To do this, you must provide a @var{state} ++argument that describes the initial status of parsing. The value ++returned by a previous call to @code{parse-partial-sexp} will do ++nicely. ++@end defun ++ ++@node Control Parsing ++@subsection Parameters to Control Parsing ++ ++@defvar multibyte-syntax-as-symbol ++If this variable is non-@code{nil}, @code{scan-sexps} treats all ++non-@acronym{ASCII} characters as symbol constituents regardless ++of what the syntax table says about them. (However, text properties ++can still override the syntax.) ++@end defvar ++ ++@defopt parse-sexp-ignore-comments ++@cindex skipping comments ++If the value is non-@code{nil}, then comments are treated as ++whitespace by the functions in this section and by @code{forward-sexp}, ++@code{scan-lists} and @code{scan-sexps}. ++@end defopt ++ ++@vindex parse-sexp-lookup-properties ++The behavior of @code{parse-partial-sexp} is also affected by ++@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}). ++ ++You can use @code{forward-comment} to move forward or backward over ++one comment or several comments. ++ ++@node Standard Syntax Tables ++@section Some Standard Syntax Tables ++ ++ Most of the major modes in Emacs have their own syntax tables. Here ++are several of them: ++ ++@defun standard-syntax-table ++This function returns the standard syntax table, which is the syntax ++table used in Fundamental mode. ++@end defun ++ ++@defvar text-mode-syntax-table ++The value of this variable is the syntax table used in Text mode. ++@end defvar ++ ++@defvar c-mode-syntax-table ++The value of this variable is the syntax table for C-mode buffers. ++@end defvar ++ ++@defvar emacs-lisp-mode-syntax-table ++The value of this variable is the syntax table used in Emacs Lisp mode ++by editing commands. (It has no effect on the Lisp @code{read} ++function.) ++@end defvar ++ ++@node Syntax Table Internals ++@section Syntax Table Internals ++@cindex syntax table internals ++ ++ Lisp programs don't usually work with the elements directly; the ++Lisp-level syntax table functions usually work with syntax descriptors ++(@pxref{Syntax Descriptors}). Nonetheless, here we document the ++internal format. This format is used mostly when manipulating ++syntax properties. ++ ++ Each element of a syntax table is a cons cell of the form ++@code{(@var{syntax-code} . @var{matching-char})}. The @sc{car}, ++@var{syntax-code}, is an integer that encodes the syntax class, and any ++flags. The @sc{cdr}, @var{matching-char}, is non-@code{nil} if ++a character to match was specified. ++ ++ This table gives the value of @var{syntax-code} which corresponds ++to each syntactic type. ++ ++@multitable @columnfractions .05 .3 .3 .31 ++@item ++@tab ++@i{Integer} @i{Class} ++@tab ++@i{Integer} @i{Class} ++@tab ++@i{Integer} @i{Class} ++@item ++@tab ++0 @ @ whitespace ++@tab ++5 @ @ close parenthesis ++@tab ++10 @ @ character quote ++@item ++@tab ++1 @ @ punctuation ++@tab ++6 @ @ expression prefix ++@tab ++11 @ @ comment-start ++@item ++@tab ++2 @ @ word ++@tab ++7 @ @ string quote ++@tab ++12 @ @ comment-end ++@item ++@tab ++3 @ @ symbol ++@tab ++8 @ @ paired delimiter ++@tab ++13 @ @ inherit ++@item ++@tab ++4 @ @ open parenthesis ++@tab ++9 @ @ escape ++@tab ++14 @ @ generic comment ++@item ++@tab ++15 @ generic string ++@end multitable ++ ++ For example, the usual syntax value for @samp{(} is @code{(4 . 41)}. ++(41 is the character code for @samp{)}.) ++ ++ The flags are encoded in higher order bits, starting 16 bits from the ++least significant bit. This table gives the power of two which ++corresponds to each syntax flag. ++ ++@multitable @columnfractions .05 .3 .3 .3 ++@item ++@tab ++@i{Prefix} @i{Flag} ++@tab ++@i{Prefix} @i{Flag} ++@tab ++@i{Prefix} @i{Flag} ++@item ++@tab ++@samp{1} @ @ @code{(lsh 1 16)} ++@tab ++@samp{4} @ @ @code{(lsh 1 19)} ++@tab ++@samp{b} @ @ @code{(lsh 1 21)} ++@item ++@tab ++@samp{2} @ @ @code{(lsh 1 17)} ++@tab ++@samp{p} @ @ @code{(lsh 1 20)} ++@tab ++@samp{n} @ @ @code{(lsh 1 22)} ++@item ++@tab ++@samp{3} @ @ @code{(lsh 1 18)} ++@end multitable ++ ++@defun string-to-syntax @var{desc} ++This function returns the internal form corresponding to the syntax ++descriptor @var{desc}, a cons cell @code{(@var{syntax-code} ++. @var{matching-char})}. ++@end defun ++ ++@defun syntax-after pos ++This function returns the syntax code of the character in the buffer ++after position @var{pos}, taking account of syntax properties as well ++as the syntax table. If @var{pos} is outside the buffer's accessible ++portion (@pxref{Narrowing, accessible portion}), this function returns ++@code{nil}. ++@end defun ++ ++@defun syntax-class syntax ++This function returns the syntax class of the syntax code ++@var{syntax}. (It masks off the high 16 bits that hold the flags ++encoded in the syntax descriptor.) If @var{syntax} is @code{nil}, it ++returns @code{nil}; this is so evaluating the expression ++ ++@example ++(syntax-class (syntax-after pos)) ++@end example ++ ++@noindent ++where @code{pos} is outside the buffer's accessible portion, will ++yield @code{nil} without throwing errors or producing wrong syntax ++class codes. ++@end defun ++ ++@node Categories ++@section Categories ++@cindex categories of characters ++@cindex character categories ++ ++ @dfn{Categories} provide an alternate way of classifying characters ++syntactically. You can define several categories as needed, then ++independently assign each character to one or more categories. Unlike ++syntax classes, categories are not mutually exclusive; it is normal for ++one character to belong to several categories. ++ ++@cindex category table ++ Each buffer has a @dfn{category table} which records which categories ++are defined and also which characters belong to each category. Each ++category table defines its own categories, but normally these are ++initialized by copying from the standard categories table, so that the ++standard categories are available in all modes. ++ ++ Each category has a name, which is an @acronym{ASCII} printing character in ++the range @w{@samp{ }} to @samp{~}. You specify the name of a category ++when you define it with @code{define-category}. ++ ++ The category table is actually a char-table (@pxref{Char-Tables}). ++The element of the category table at index @var{c} is a @dfn{category ++set}---a bool-vector---that indicates which categories character @var{c} ++belongs to. In this category set, if the element at index @var{cat} is ++@code{t}, that means category @var{cat} is a member of the set, and that ++character @var{c} belongs to category @var{cat}. ++ ++For the next three functions, the optional argument @var{table} ++defaults to the current buffer's category table. ++ ++@defun define-category char docstring &optional table ++This function defines a new category, with name @var{char} and ++documentation @var{docstring}, for the category table @var{table}. ++@end defun ++ ++@defun category-docstring category &optional table ++This function returns the documentation string of category @var{category} ++in category table @var{table}. ++ ++@example ++(category-docstring ?a) ++ @result{} "ASCII" ++(category-docstring ?l) ++ @result{} "Latin" ++@end example ++@end defun ++ ++@defun get-unused-category &optional table ++This function returns a category name (a character) which is not ++currently defined in @var{table}. If all possible categories are in use ++in @var{table}, it returns @code{nil}. ++@end defun ++ ++@defun category-table ++This function returns the current buffer's category table. ++@end defun ++ ++@defun category-table-p object ++This function returns @code{t} if @var{object} is a category table, ++otherwise @code{nil}. ++@end defun ++ ++@defun standard-category-table ++This function returns the standard category table. ++@end defun ++ ++@defun copy-category-table &optional table ++This function constructs a copy of @var{table} and returns it. If ++@var{table} is not supplied (or is @code{nil}), it returns a copy of the ++standard category table. Otherwise, an error is signaled if @var{table} ++is not a category table. ++@end defun ++ ++@defun set-category-table table ++This function makes @var{table} the category table for the current ++buffer. It returns @var{table}. ++@end defun ++ ++@defun make-category-table ++This creates and returns an empty category table. In an empty category ++table, no categories have been allocated, and no characters belong to ++any categories. ++@end defun ++ ++@defun make-category-set categories ++This function returns a new category set---a bool-vector---whose initial ++contents are the categories listed in the string @var{categories}. The ++elements of @var{categories} should be category names; the new category ++set has @code{t} for each of those categories, and @code{nil} for all ++other categories. ++ ++@example ++(make-category-set "al") ++ @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" ++@end example ++@end defun ++ ++@defun char-category-set char ++This function returns the category set for character @var{char} in the ++current buffer's category table. This is the bool-vector which ++records which categories the character @var{char} belongs to. The ++function @code{char-category-set} does not allocate storage, because ++it returns the same bool-vector that exists in the category table. ++ ++@example ++(char-category-set ?a) ++ @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" ++@end example ++@end defun ++ ++@defun category-set-mnemonics category-set ++This function converts the category set @var{category-set} into a string ++containing the characters that designate the categories that are members ++of the set. ++ ++@example ++(category-set-mnemonics (char-category-set ?a)) ++ @result{} "al" ++@end example ++@end defun ++ ++@defun modify-category-entry char category &optional table reset ++This function modifies the category set of @var{char} in category ++table @var{table} (which defaults to the current buffer's category ++table). @var{char} can be a character, or a cons cell of the form ++@code{(@var{min} . @var{max})}; in the latter case, the function ++modifies the category sets of all characters in the range between ++@var{min} and @var{max}, inclusive. ++ ++Normally, it modifies a category set by adding @var{category} to it. ++But if @var{reset} is non-@code{nil}, then it deletes @var{category} ++instead. ++@end defun ++ ++@deffn Command describe-categories &optional buffer-or-name ++This function describes the category specifications in the current ++category table. It inserts the descriptions in a buffer, and then ++displays that buffer. If @var{buffer-or-name} is non-@code{nil}, it ++describes the category table of that buffer instead. ++@end deffn ++ ++@ignore ++ arch-tag: 4d914e96-0283-445c-9233-75d33662908c ++@end ignore +diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi +new file mode 100644 +index 0000000..5c2a3ce +--- /dev/null ++++ b/doc/lispref/text.texi +@@ -0,0 +1,4276 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/text ++@node Text, Non-ASCII Characters, Markers, Top ++@chapter Text ++@cindex text ++ ++ This chapter describes the functions that deal with the text in a ++buffer. Most examine, insert, or delete text in the current buffer, ++often operating at point or on text adjacent to point. Many are ++interactive. All the functions that change the text provide for undoing ++the changes (@pxref{Undo}). ++ ++ Many text-related functions operate on a region of text defined by two ++buffer positions passed in arguments named @var{start} and @var{end}. ++These arguments should be either markers (@pxref{Markers}) or numeric ++character positions (@pxref{Positions}). The order of these arguments ++does not matter; it is all right for @var{start} to be the end of the ++region and @var{end} the beginning. For example, @code{(delete-region 1 ++10)} and @code{(delete-region 10 1)} are equivalent. An ++@code{args-out-of-range} error is signaled if either @var{start} or ++@var{end} is outside the accessible portion of the buffer. In an ++interactive call, point and the mark are used for these arguments. ++ ++@cindex buffer contents ++ Throughout this chapter, ``text'' refers to the characters in the ++buffer, together with their properties (when relevant). Keep in mind ++that point is always between two characters, and the cursor appears on ++the character after point. ++ ++@menu ++* Near Point:: Examining text in the vicinity of point. ++* Buffer Contents:: Examining text in a general fashion. ++* Comparing Text:: Comparing substrings of buffers. ++* Insertion:: Adding new text to a buffer. ++* Commands for Insertion:: User-level commands to insert text. ++* Deletion:: Removing text from a buffer. ++* User-Level Deletion:: User-level commands to delete text. ++* The Kill Ring:: Where removed text sometimes is saved for later use. ++* Undo:: Undoing changes to the text of a buffer. ++* Maintaining Undo:: How to enable and disable undo information. ++ How to control how much information is kept. ++* Filling:: Functions for explicit filling. ++* Margins:: How to specify margins for filling commands. ++* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context. ++* Auto Filling:: How auto-fill mode is implemented to break lines. ++* Sorting:: Functions for sorting parts of the buffer. ++* Columns:: Computing horizontal positions, and using them. ++* Indentation:: Functions to insert or adjust indentation. ++* Case Changes:: Case conversion of parts of the buffer. ++* Text Properties:: Assigning Lisp property lists to text characters. ++* Substitution:: Replacing a given character wherever it appears. ++* Transposition:: Swapping two portions of a buffer. ++* Registers:: How registers are implemented. Accessing the text or ++ position stored in a register. ++* Base 64:: Conversion to or from base 64 encoding. ++* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". ++* Atomic Changes:: Installing several buffer changes "atomically". ++* Change Hooks:: Supplying functions to be run when text is changed. ++@end menu ++ ++@node Near Point ++@section Examining Text Near Point ++@cindex text near point ++ ++ Many functions are provided to look at the characters around point. ++Several simple functions are described here. See also @code{looking-at} ++in @ref{Regexp Search}. ++ ++In the following four functions, ``beginning'' or ``end'' of buffer ++refers to the beginning or end of the accessible portion. ++ ++@defun char-after &optional position ++This function returns the character in the current buffer at (i.e., ++immediately after) position @var{position}. If @var{position} is out of ++range for this purpose, either before the beginning of the buffer, or at ++or beyond the end, then the value is @code{nil}. The default for ++@var{position} is point. ++ ++In the following example, assume that the first character in the ++buffer is @samp{@@}: ++ ++@example ++@group ++(char-to-string (char-after 1)) ++ @result{} "@@" ++@end group ++@end example ++@end defun ++ ++@defun char-before &optional position ++This function returns the character in the current buffer immediately ++before position @var{position}. If @var{position} is out of range for ++this purpose, either at or before the beginning of the buffer, or beyond ++the end, then the value is @code{nil}. The default for ++@var{position} is point. ++@end defun ++ ++@defun following-char ++This function returns the character following point in the current ++buffer. This is similar to @code{(char-after (point))}. However, if ++point is at the end of the buffer, then @code{following-char} returns 0. ++ ++Remember that point is always between characters, and the cursor ++normally appears over the character following point. Therefore, the ++character returned by @code{following-char} is the character the ++cursor is over. ++ ++In this example, point is between the @samp{a} and the @samp{c}. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++Gentlemen may cry ``Pea@point{}ce! Peace!,'' ++but there is no peace. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(char-to-string (preceding-char)) ++ @result{} "a" ++(char-to-string (following-char)) ++ @result{} "c" ++@end group ++@end example ++@end defun ++ ++@defun preceding-char ++This function returns the character preceding point in the current ++buffer. See above, under @code{following-char}, for an example. If ++point is at the beginning of the buffer, @code{preceding-char} returns ++0. ++@end defun ++ ++@defun bobp ++This function returns @code{t} if point is at the beginning of the ++buffer. If narrowing is in effect, this means the beginning of the ++accessible portion of the text. See also @code{point-min} in ++@ref{Point}. ++@end defun ++ ++@defun eobp ++This function returns @code{t} if point is at the end of the buffer. ++If narrowing is in effect, this means the end of accessible portion of ++the text. See also @code{point-max} in @xref{Point}. ++@end defun ++ ++@defun bolp ++This function returns @code{t} if point is at the beginning of a line. ++@xref{Text Lines}. The beginning of the buffer (or of its accessible ++portion) always counts as the beginning of a line. ++@end defun ++ ++@defun eolp ++This function returns @code{t} if point is at the end of a line. The ++end of the buffer (or of its accessible portion) is always considered ++the end of a line. ++@end defun ++ ++@node Buffer Contents ++@section Examining Buffer Contents ++ ++ This section describes functions that allow a Lisp program to ++convert any portion of the text in the buffer into a string. ++ ++@defun buffer-substring start end ++This function returns a string containing a copy of the text of the ++region defined by positions @var{start} and @var{end} in the current ++buffer. If the arguments are not positions in the accessible portion of ++the buffer, @code{buffer-substring} signals an @code{args-out-of-range} ++error. ++ ++It is not necessary for @var{start} to be less than @var{end}; the ++arguments can be given in either order. But most often the smaller ++argument is written first. ++ ++Here's an example which assumes Font-Lock mode is not enabled: ++ ++@example ++@group ++---------- Buffer: foo ---------- ++This is the contents of buffer foo ++ ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(buffer-substring 1 10) ++ @result{} "This is t" ++@end group ++@group ++(buffer-substring (point-max) 10) ++ @result{} "he contents of buffer foo\n" ++@end group ++@end example ++ ++If the text being copied has any text properties, these are copied into ++the string along with the characters they belong to. @xref{Text ++Properties}. However, overlays (@pxref{Overlays}) in the buffer and ++their properties are ignored, not copied. ++ ++For example, if Font-Lock mode is enabled, you might get results like ++these: ++ ++@example ++@group ++(buffer-substring 1 10) ++ @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t)) ++@end group ++@end example ++@end defun ++ ++@defun buffer-substring-no-properties start end ++This is like @code{buffer-substring}, except that it does not copy text ++properties, just the characters themselves. @xref{Text Properties}. ++@end defun ++ ++@defun filter-buffer-substring start end &optional delete noprops ++This function passes the buffer text between @var{start} and @var{end} ++through the filter functions specified by the variable ++@code{buffer-substring-filters}, and returns the value from the last ++filter function. If @code{buffer-substring-filters} is @code{nil}, ++the value is the unaltered text from the buffer, what ++@code{buffer-substring} would return. ++ ++If @var{delete} is non-@code{nil}, this function deletes the text ++between @var{start} and @var{end} after copying it, like ++@code{delete-and-extract-region}. ++ ++If @var{noprops} is non-@code{nil}, the final string returned does not ++include text properties, while the string passed through the filters ++still includes text properties from the buffer text. ++ ++Lisp code should use this function instead of @code{buffer-substring}, ++@code{buffer-substring-no-properties}, ++or @code{delete-and-extract-region} when copying into user-accessible ++data structures such as the kill-ring, X clipboard, and registers. ++Major and minor modes can add functions to ++@code{buffer-substring-filters} to alter such text as it is copied out ++of the buffer. ++@end defun ++ ++@defvar buffer-substring-filters ++This variable should be a list of functions that accept a single ++argument, a string, and return a string. ++@code{filter-buffer-substring} passes the buffer substring to the ++first function in this list, and the return value of each function is ++passed to the next function. The return value of the last function is ++used as the return value of @code{filter-buffer-substring}. ++ ++As a special convention, point is set to the start of the buffer text ++being operated on (i.e., the @var{start} argument for ++@code{filter-buffer-substring}) before these functions are called. ++ ++If this variable is @code{nil}, no filtering is performed. ++@end defvar ++ ++@defun buffer-string ++This function returns the contents of the entire accessible portion of ++the current buffer as a string. It is equivalent to ++ ++@example ++(buffer-substring (point-min) (point-max)) ++@end example ++ ++@example ++@group ++---------- Buffer: foo ---------- ++This is the contents of buffer foo ++ ++---------- Buffer: foo ---------- ++ ++(buffer-string) ++ @result{} "This is the contents of buffer foo\n" ++@end group ++@end example ++@end defun ++ ++@defun current-word &optional strict really-word ++This function returns the symbol (or word) at or near point, as a string. ++The return value includes no text properties. ++ ++If the optional argument @var{really-word} is non-@code{nil}, it finds a ++word; otherwise, it finds a symbol (which includes both word ++characters and symbol constituent characters). ++ ++If the optional argument @var{strict} is non-@code{nil}, then point ++must be in or next to the symbol or word---if no symbol or word is ++there, the function returns @code{nil}. Otherwise, a nearby symbol or ++word on the same line is acceptable. ++@end defun ++ ++@defun thing-at-point thing ++Return the @var{thing} around or next to point, as a string. ++ ++The argument @var{thing} is a symbol which specifies a kind of syntactic ++entity. Possibilities include @code{symbol}, @code{list}, @code{sexp}, ++@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence}, ++@code{whitespace}, @code{line}, @code{page}, and others. ++ ++@example ++---------- Buffer: foo ---------- ++Gentlemen may cry ``Pea@point{}ce! Peace!,'' ++but there is no peace. ++---------- Buffer: foo ---------- ++ ++(thing-at-point 'word) ++ @result{} "Peace" ++(thing-at-point 'line) ++ @result{} "Gentlemen may cry ``Peace! Peace!,''\n" ++(thing-at-point 'whitespace) ++ @result{} nil ++@end example ++@end defun ++ ++@node Comparing Text ++@section Comparing Text ++@cindex comparing buffer text ++ ++ This function lets you compare portions of the text in a buffer, without ++copying them into strings first. ++ ++@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 ++This function lets you compare two substrings of the same buffer or two ++different buffers. The first three arguments specify one substring, ++giving a buffer (or a buffer name) and two positions within the ++buffer. The last three arguments specify the other substring in the ++same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or ++both to stand for the current buffer. ++ ++The value is negative if the first substring is less, positive if the ++first is greater, and zero if they are equal. The absolute value of ++the result is one plus the index of the first differing characters ++within the substrings. ++ ++This function ignores case when comparing characters ++if @code{case-fold-search} is non-@code{nil}. It always ignores ++text properties. ++ ++Suppose the current buffer contains the text @samp{foobarbar ++haha!rara!}; then in this example the two substrings are @samp{rbar } ++and @samp{rara!}. The value is 2 because the first substring is greater ++at the second character. ++ ++@example ++(compare-buffer-substrings nil 6 11 nil 16 21) ++ @result{} 2 ++@end example ++@end defun ++ ++@node Insertion ++@section Inserting Text ++@cindex insertion of text ++@cindex text insertion ++ ++@cindex insertion before point ++@cindex before point, insertion ++ @dfn{Insertion} means adding new text to a buffer. The inserted text ++goes at point---between the character before point and the character ++after point. Some insertion functions leave point before the inserted ++text, while other functions leave it after. We call the former ++insertion @dfn{after point} and the latter insertion @dfn{before point}. ++ ++ Insertion relocates markers that point at positions after the ++insertion point, so that they stay with the surrounding text ++(@pxref{Markers}). When a marker points at the place of insertion, ++insertion may or may not relocate the marker, depending on the marker's ++insertion type (@pxref{Marker Insertion Types}). Certain special ++functions such as @code{insert-before-markers} relocate all such markers ++to point after the inserted text, regardless of the markers' insertion ++type. ++ ++ Insertion functions signal an error if the current buffer is ++read-only or if they insert within read-only text. ++ ++ These functions copy text characters from strings and buffers along ++with their properties. The inserted characters have exactly the same ++properties as the characters they were copied from. By contrast, ++characters specified as separate arguments, not part of a string or ++buffer, inherit their text properties from the neighboring text. ++ ++ The insertion functions convert text from unibyte to multibyte in ++order to insert in a multibyte buffer, and vice versa---if the text ++comes from a string or from a buffer. However, they do not convert ++unibyte character codes 128 through 255 to multibyte characters, not ++even if the current buffer is a multibyte buffer. @xref{Converting ++Representations}. ++ ++@defun insert &rest args ++This function inserts the strings and/or characters @var{args} into the ++current buffer, at point, moving point forward. In other words, it ++inserts the text before point. An error is signaled unless all ++@var{args} are either strings or characters. The value is @code{nil}. ++@end defun ++ ++@defun insert-before-markers &rest args ++This function inserts the strings and/or characters @var{args} into the ++current buffer, at point, moving point forward. An error is signaled ++unless all @var{args} are either strings or characters. The value is ++@code{nil}. ++ ++This function is unlike the other insertion functions in that it ++relocates markers initially pointing at the insertion point, to point ++after the inserted text. If an overlay begins at the insertion point, ++the inserted text falls outside the overlay; if a nonempty overlay ++ends at the insertion point, the inserted text falls inside that ++overlay. ++@end defun ++ ++@defun insert-char character count &optional inherit ++This function inserts @var{count} instances of @var{character} into the ++current buffer before point. The argument @var{count} should be an ++integer, and @var{character} must be a character. The value is @code{nil}. ++ ++This function does not convert unibyte character codes 128 through 255 ++to multibyte characters, not even if the current buffer is a multibyte ++buffer. @xref{Converting Representations}. ++ ++If @var{inherit} is non-@code{nil}, then the inserted characters inherit ++sticky text properties from the two characters before and after the ++insertion point. @xref{Sticky Properties}. ++@end defun ++ ++@defun insert-buffer-substring from-buffer-or-name &optional start end ++This function inserts a portion of buffer @var{from-buffer-or-name} ++(which must already exist) into the current buffer before point. The ++text inserted is the region between @var{start} and @var{end}. (These ++arguments default to the beginning and end of the accessible portion of ++that buffer.) This function returns @code{nil}. ++ ++In this example, the form is executed with buffer @samp{bar} as the ++current buffer. We assume that buffer @samp{bar} is initially empty. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++We hold these truths to be self-evident, that all ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(insert-buffer-substring "foo" 1 20) ++ @result{} nil ++ ++---------- Buffer: bar ---------- ++We hold these truth@point{} ++---------- Buffer: bar ---------- ++@end group ++@end example ++@end defun ++ ++@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end ++This is like @code{insert-buffer-substring} except that it does not ++copy any text properties. ++@end defun ++ ++ @xref{Sticky Properties}, for other insertion functions that inherit ++text properties from the nearby text in addition to inserting it. ++Whitespace inserted by indentation functions also inherits text ++properties. ++ ++@node Commands for Insertion ++@section User-Level Insertion Commands ++ ++ This section describes higher-level commands for inserting text, ++commands intended primarily for the user but useful also in Lisp ++programs. ++ ++@deffn Command insert-buffer from-buffer-or-name ++This command inserts the entire accessible contents of ++@var{from-buffer-or-name} (which must exist) into the current buffer ++after point. It leaves the mark after the inserted text. The value ++is @code{nil}. ++@end deffn ++ ++@deffn Command self-insert-command count ++@cindex character insertion ++@cindex self-insertion ++This command inserts the last character typed; it does so @var{count} ++times, before point, and returns @code{nil}. Most printing characters ++are bound to this command. In routine use, @code{self-insert-command} ++is the most frequently called function in Emacs, but programs rarely use ++it except to install it on a keymap. ++ ++In an interactive call, @var{count} is the numeric prefix argument. ++ ++Self-insertion translates the input character through ++@code{translation-table-for-input}. @xref{Translation of Characters}. ++ ++This command calls @code{auto-fill-function} whenever that is ++non-@code{nil} and the character inserted is in the table ++@code{auto-fill-chars} (@pxref{Auto Filling}). ++ ++@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 ++This command performs abbrev expansion if Abbrev mode is enabled and ++the inserted character does not have word-constituent ++syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also ++responsible for calling @code{blink-paren-function} when the inserted ++character has close parenthesis syntax (@pxref{Blinking}). ++ ++Do not try substituting your own definition of ++@code{self-insert-command} for the standard one. The editor command ++loop handles this function specially. ++@end deffn ++ ++@deffn Command newline &optional number-of-newlines ++This command inserts newlines into the current buffer before point. ++If @var{number-of-newlines} is supplied, that many newline characters ++are inserted. ++ ++@cindex newline and Auto Fill mode ++This function calls @code{auto-fill-function} if the current column ++number is greater than the value of @code{fill-column} and ++@var{number-of-newlines} is @code{nil}. Typically what ++@code{auto-fill-function} does is insert a newline; thus, the overall ++result in this case is to insert two newlines at different places: one ++at point, and another earlier in the line. @code{newline} does not ++auto-fill if @var{number-of-newlines} is non-@code{nil}. ++ ++This command indents to the left margin if that is not zero. ++@xref{Margins}. ++ ++The value returned is @code{nil}. In an interactive call, @var{count} ++is the numeric prefix argument. ++@end deffn ++ ++@defvar overwrite-mode ++This variable controls whether overwrite mode is in effect. The value ++should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, ++or @code{nil}. @code{overwrite-mode-textual} specifies textual ++overwrite mode (treats newlines and tabs specially), and ++@code{overwrite-mode-binary} specifies binary overwrite mode (treats ++newlines and tabs like any other characters). ++@end defvar ++ ++@node Deletion ++@section Deleting Text ++@cindex text deletion ++ ++@cindex deleting text vs killing ++ Deletion means removing part of the text in a buffer, without saving ++it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be ++yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). ++Some deletion functions do save text in the kill ring in some special ++cases. ++ ++ All of the deletion functions operate on the current buffer. ++ ++@deffn Command erase-buffer ++This function deletes the entire text of the current buffer ++(@emph{not} just the accessible portion), leaving it ++empty. If the buffer is read-only, it signals a @code{buffer-read-only} ++error; if some of the text in it is read-only, it signals a ++@code{text-read-only} error. Otherwise, it deletes the text without ++asking for any confirmation. It returns @code{nil}. ++ ++Normally, deleting a large amount of text from a buffer inhibits further ++auto-saving of that buffer ``because it has shrunk.'' However, ++@code{erase-buffer} does not do this, the idea being that the future ++text is not really related to the former text, and its size should not ++be compared with that of the former text. ++@end deffn ++ ++@deffn Command delete-region start end ++This command deletes the text between positions @var{start} and ++@var{end} in the current buffer, and returns @code{nil}. If point was ++inside the deleted region, its value afterward is @var{start}. ++Otherwise, point relocates with the surrounding text, as markers do. ++@end deffn ++ ++@defun delete-and-extract-region start end ++This function deletes the text between positions @var{start} and ++@var{end} in the current buffer, and returns a string containing the ++text just deleted. ++ ++If point was inside the deleted region, its value afterward is ++@var{start}. Otherwise, point relocates with the surrounding text, as ++markers do. ++@end defun ++ ++@deffn Command delete-char count &optional killp ++This command deletes @var{count} characters directly after point, or ++before point if @var{count} is negative. If @var{killp} is ++non-@code{nil}, then it saves the deleted characters in the kill ring. ++ ++In an interactive call, @var{count} is the numeric prefix argument, and ++@var{killp} is the unprocessed prefix argument. Therefore, if a prefix ++argument is supplied, the text is saved in the kill ring. If no prefix ++argument is supplied, then one character is deleted, but not saved in ++the kill ring. ++ ++The value returned is always @code{nil}. ++@end deffn ++ ++@deffn Command delete-backward-char count &optional killp ++@cindex deleting previous char ++This command deletes @var{count} characters directly before point, or ++after point if @var{count} is negative. If @var{killp} is ++non-@code{nil}, then it saves the deleted characters in the kill ring. ++ ++In an interactive call, @var{count} is the numeric prefix argument, and ++@var{killp} is the unprocessed prefix argument. Therefore, if a prefix ++argument is supplied, the text is saved in the kill ring. If no prefix ++argument is supplied, then one character is deleted, but not saved in ++the kill ring. ++ ++The value returned is always @code{nil}. ++@end deffn ++ ++@deffn Command backward-delete-char-untabify count &optional killp ++@cindex tab deletion ++This command deletes @var{count} characters backward, changing tabs ++into spaces. When the next character to be deleted is a tab, it is ++first replaced with the proper number of spaces to preserve alignment ++and then one of those spaces is deleted instead of the tab. If ++@var{killp} is non-@code{nil}, then the command saves the deleted ++characters in the kill ring. ++ ++Conversion of tabs to spaces happens only if @var{count} is positive. ++If it is negative, exactly @minus{}@var{count} characters after point ++are deleted. ++ ++In an interactive call, @var{count} is the numeric prefix argument, and ++@var{killp} is the unprocessed prefix argument. Therefore, if a prefix ++argument is supplied, the text is saved in the kill ring. If no prefix ++argument is supplied, then one character is deleted, but not saved in ++the kill ring. ++ ++The value returned is always @code{nil}. ++@end deffn ++ ++@defopt backward-delete-char-untabify-method ++This option specifies how @code{backward-delete-char-untabify} should ++deal with whitespace. Possible values include @code{untabify}, the ++default, meaning convert a tab to many spaces and delete one; ++@code{hungry}, meaning delete all tabs and spaces before point with ++one command; @code{all} meaning delete all tabs, spaces and newlines ++before point, and @code{nil}, meaning do nothing special for ++whitespace characters. ++@end defopt ++ ++@node User-Level Deletion ++@section User-Level Deletion Commands ++ ++ This section describes higher-level commands for deleting text, ++commands intended primarily for the user but useful also in Lisp ++programs. ++ ++@deffn Command delete-horizontal-space &optional backward-only ++@cindex deleting whitespace ++This function deletes all spaces and tabs around point. It returns ++@code{nil}. ++ ++If @var{backward-only} is non-@code{nil}, the function deletes ++spaces and tabs before point, but not after point. ++ ++In the following examples, we call @code{delete-horizontal-space} four ++times, once on each line, with point between the second and third ++characters on the line each time. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++I @point{}thought ++I @point{} thought ++We@point{} thought ++Yo@point{}u thought ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(delete-horizontal-space) ; @r{Four times.} ++ @result{} nil ++ ++---------- Buffer: foo ---------- ++Ithought ++Ithought ++Wethought ++You thought ++---------- Buffer: foo ---------- ++@end group ++@end example ++@end deffn ++ ++@deffn Command delete-indentation &optional join-following-p ++This function joins the line point is on to the previous line, deleting ++any whitespace at the join and in some cases replacing it with one ++space. If @var{join-following-p} is non-@code{nil}, ++@code{delete-indentation} joins this line to the following line ++instead. The function returns @code{nil}. ++ ++If there is a fill prefix, and the second of the lines being joined ++starts with the prefix, then @code{delete-indentation} deletes the ++fill prefix before joining the lines. @xref{Margins}. ++ ++In the example below, point is located on the line starting ++@samp{events}, and it makes no difference if there are trailing spaces ++in the preceding line. ++ ++@smallexample ++@group ++---------- Buffer: foo ---------- ++When in the course of human ++@point{} events, it becomes necessary ++---------- Buffer: foo ---------- ++@end group ++ ++(delete-indentation) ++ @result{} nil ++ ++@group ++---------- Buffer: foo ---------- ++When in the course of human@point{} events, it becomes necessary ++---------- Buffer: foo ---------- ++@end group ++@end smallexample ++ ++After the lines are joined, the function @code{fixup-whitespace} is ++responsible for deciding whether to leave a space at the junction. ++@end deffn ++ ++@deffn Command fixup-whitespace ++This function replaces all the horizontal whitespace surrounding point ++with either one space or no space, according to the context. It ++returns @code{nil}. ++ ++At the beginning or end of a line, the appropriate amount of space is ++none. Before a character with close parenthesis syntax, or after a ++character with open parenthesis or expression-prefix syntax, no space is ++also appropriate. Otherwise, one space is appropriate. @xref{Syntax ++Class Table}. ++ ++In the example below, @code{fixup-whitespace} is called the first time ++with point before the word @samp{spaces} in the first line. For the ++second invocation, point is directly after the @samp{(}. ++ ++@smallexample ++@group ++---------- Buffer: foo ---------- ++This has too many @point{}spaces ++This has too many spaces at the start of (@point{} this list) ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(fixup-whitespace) ++ @result{} nil ++(fixup-whitespace) ++ @result{} nil ++@end group ++ ++@group ++---------- Buffer: foo ---------- ++This has too many spaces ++This has too many spaces at the start of (this list) ++---------- Buffer: foo ---------- ++@end group ++@end smallexample ++@end deffn ++ ++@deffn Command just-one-space &optional n ++@comment !!SourceFile simple.el ++This command replaces any spaces and tabs around point with a single ++space, or @var{n} spaces if @var{n} is specified. It returns ++@code{nil}. ++@end deffn ++ ++@deffn Command delete-blank-lines ++This function deletes blank lines surrounding point. If point is on a ++blank line with one or more blank lines before or after it, then all but ++one of them are deleted. If point is on an isolated blank line, then it ++is deleted. If point is on a nonblank line, the command deletes all ++blank lines immediately following it. ++ ++A blank line is defined as a line containing only tabs and spaces. ++ ++@code{delete-blank-lines} returns @code{nil}. ++@end deffn ++ ++@node The Kill Ring ++@section The Kill Ring ++@cindex kill ring ++ ++ @dfn{Kill functions} delete text like the deletion functions, but save ++it so that the user can reinsert it by @dfn{yanking}. Most of these ++functions have @samp{kill-} in their name. By contrast, the functions ++whose names start with @samp{delete-} normally do not save text for ++yanking (though they can still be undone); these are ``deletion'' ++functions. ++ ++ Most of the kill commands are primarily for interactive use, and are ++not described here. What we do describe are the functions provided for ++use in writing such commands. You can use these functions to write ++commands for killing text. When you need to delete text for internal ++purposes within a Lisp function, you should normally use deletion ++functions, so as not to disturb the kill ring contents. ++@xref{Deletion}. ++ ++ Killed text is saved for later yanking in the @dfn{kill ring}. This ++is a list that holds a number of recent kills, not just the last text ++kill. We call this a ``ring'' because yanking treats it as having ++elements in a cyclic order. The list is kept in the variable ++@code{kill-ring}, and can be operated on with the usual functions for ++lists; there are also specialized functions, described in this section, ++that treat it as a ring. ++ ++ Some people think this use of the word ``kill'' is unfortunate, since ++it refers to operations that specifically @emph{do not} destroy the ++entities ``killed.'' This is in sharp contrast to ordinary life, in ++which death is permanent and ``killed'' entities do not come back to ++life. Therefore, other metaphors have been proposed. For example, the ++term ``cut ring'' makes sense to people who, in pre-computer days, used ++scissors and paste to cut up and rearrange manuscripts. However, it ++would be difficult to change the terminology now. ++ ++@menu ++* Kill Ring Concepts:: What text looks like in the kill ring. ++* Kill Functions:: Functions that kill text. ++* Yanking:: How yanking is done. ++* Yank Commands:: Commands that access the kill ring. ++* Low-Level Kill Ring:: Functions and variables for kill ring access. ++* Internals of Kill Ring:: Variables that hold kill ring data. ++@end menu ++ ++@node Kill Ring Concepts ++@comment node-name, next, previous, up ++@subsection Kill Ring Concepts ++ ++ The kill ring records killed text as strings in a list, most recent ++first. A short kill ring, for example, might look like this: ++ ++@example ++("some text" "a different piece of text" "even older text") ++@end example ++ ++@noindent ++When the list reaches @code{kill-ring-max} entries in length, adding a ++new entry automatically deletes the last entry. ++ ++ When kill commands are interwoven with other commands, each kill ++command makes a new entry in the kill ring. Multiple kill commands in ++succession build up a single kill ring entry, which would be yanked as a ++unit; the second and subsequent consecutive kill commands add text to ++the entry made by the first one. ++ ++ For yanking, one entry in the kill ring is designated the ``front'' of ++the ring. Some yank commands ``rotate'' the ring by designating a ++different element as the ``front.'' But this virtual rotation doesn't ++change the list itself---the most recent entry always comes first in the ++list. ++ ++@node Kill Functions ++@comment node-name, next, previous, up ++@subsection Functions for Killing ++ ++ @code{kill-region} is the usual subroutine for killing text. Any ++command that calls this function is a ``kill command'' (and should ++probably have @samp{kill} in its name). @code{kill-region} puts the ++newly killed text in a new element at the beginning of the kill ring or ++adds it to the most recent element. It determines automatically (using ++@code{last-command}) whether the previous command was a kill command, ++and if so appends the killed text to the most recent entry. ++ ++@deffn Command kill-region start end &optional yank-handler ++This function kills the text in the region defined by @var{start} and ++@var{end}. The text is deleted but saved in the kill ring, along with ++its text properties. The value is always @code{nil}. ++ ++In an interactive call, @var{start} and @var{end} are point and ++the mark. ++ ++@c Emacs 19 feature ++If the buffer or text is read-only, @code{kill-region} modifies the kill ++ring just the same, then signals an error without modifying the buffer. ++This is convenient because it lets the user use a series of kill ++commands to copy text from a read-only buffer into the kill ring. ++ ++If @var{yank-handler} is non-@code{nil}, this puts that value onto ++the string of killed text, as a @code{yank-handler} text property. ++@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any ++@code{yank-handler} properties present on the killed text are copied ++onto the kill ring, like other text properties. ++@end deffn ++ ++@defopt kill-read-only-ok ++If this option is non-@code{nil}, @code{kill-region} does not signal an ++error if the buffer or text is read-only. Instead, it simply returns, ++updating the kill ring but not changing the buffer. ++@end defopt ++ ++@deffn Command copy-region-as-kill start end ++This command saves the region defined by @var{start} and @var{end} on ++the kill ring (including text properties), but does not delete the text ++from the buffer. It returns @code{nil}. ++ ++The command does not set @code{this-command} to @code{kill-region}, so a ++subsequent kill command does not append to the same kill ring entry. ++ ++Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to ++support Emacs 18. For newer Emacs versions, it is better to use ++@code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill ++Ring}. ++@end deffn ++ ++@node Yanking ++@subsection Yanking ++ ++ Yanking means inserting text from the kill ring, but it does ++not insert the text blindly. Yank commands and some other commands ++use @code{insert-for-yank} to perform special processing on the ++text that they copy into the buffer. ++ ++@defun insert-for-yank string ++This function normally works like @code{insert} except that it doesn't ++insert the text properties in the @code{yank-excluded-properties} ++list. However, if any part of @var{string} has a non-@code{nil} ++@code{yank-handler} text property, that property can do various ++special processing on that part of the text being inserted. ++@end defun ++ ++@defun insert-buffer-substring-as-yank buf &optional start end ++This function resembles @code{insert-buffer-substring} except that it ++doesn't insert the text properties in the ++@code{yank-excluded-properties} list. ++@end defun ++ ++ You can put a @code{yank-handler} text property on all or part of ++the text to control how it will be inserted if it is yanked. The ++@code{insert-for-yank} function looks for that property. The property ++value must be a list of one to four elements, with the following ++format (where elements after the first may be omitted): ++ ++@example ++(@var{function} @var{param} @var{noexclude} @var{undo}) ++@end example ++ ++ Here is what the elements do: ++ ++@table @var ++@item function ++When @var{function} is present and non-@code{nil}, it is called instead of ++@code{insert} to insert the string. @var{function} takes one ++argument---the string to insert. ++ ++@item param ++If @var{param} is present and non-@code{nil}, it replaces @var{string} ++(or the part of @var{string} being processed) as the object passed to ++@var{function} (or @code{insert}); for example, if @var{function} is ++@code{yank-rectangle}, @var{param} should be a list of strings to ++insert as a rectangle. ++ ++@item noexclude ++If @var{noexclude} is present and non-@code{nil}, the normal removal of the ++yank-excluded-properties is not performed; instead @var{function} is ++responsible for removing those properties. This may be necessary ++if @var{function} adjusts point before or after inserting the object. ++ ++@item undo ++If @var{undo} is present and non-@code{nil}, it is a function that will be ++called by @code{yank-pop} to undo the insertion of the current object. ++It is called with two arguments, the start and end of the current ++region. @var{function} can set @code{yank-undo-function} to override ++the @var{undo} value. ++@end table ++ ++@node Yank Commands ++@comment node-name, next, previous, up ++@subsection Functions for Yanking ++ ++ This section describes higher-level commands for yanking, which are ++intended primarily for the user but useful also in Lisp programs. ++Both @code{yank} and @code{yank-pop} honor the ++@code{yank-excluded-properties} variable and @code{yank-handler} text ++property (@pxref{Yanking}). ++ ++@deffn Command yank &optional arg ++@cindex inserting killed text ++This command inserts before point the text at the front of the kill ++ring. It sets the mark at the beginning of that text, using ++@code{push-mark} (@pxref{The Mark}), and puts point at the end. ++ ++If @var{arg} is a non-@code{nil} list (which occurs interactively when ++the user types @kbd{C-u} with no digits), then @code{yank} inserts the ++text as described above, but puts point before the yanked text and ++sets the mark after it. ++ ++If @var{arg} is a number, then @code{yank} inserts the @var{arg}th ++most recently killed text---the @var{arg}th element of the kill ring ++list, counted cyclically from the front, which is considered the ++first element for this purpose. ++ ++@code{yank} does not alter the contents of the kill ring, unless it ++used text provided by another program, in which case it pushes that text ++onto the kill ring. However if @var{arg} is an integer different from ++one, it rotates the kill ring to place the yanked string at the front. ++ ++@code{yank} returns @code{nil}. ++@end deffn ++ ++@deffn Command yank-pop &optional arg ++This command replaces the just-yanked entry from the kill ring with a ++different entry from the kill ring. ++ ++This is allowed only immediately after a @code{yank} or another ++@code{yank-pop}. At such a time, the region contains text that was just ++inserted by yanking. @code{yank-pop} deletes that text and inserts in ++its place a different piece of killed text. It does not add the deleted ++text to the kill ring, since it is already in the kill ring somewhere. ++It does however rotate the kill ring to place the newly yanked string at ++the front. ++ ++If @var{arg} is @code{nil}, then the replacement text is the previous ++element of the kill ring. If @var{arg} is numeric, the replacement is ++the @var{arg}th previous kill. If @var{arg} is negative, a more recent ++kill is the replacement. ++ ++The sequence of kills in the kill ring wraps around, so that after the ++oldest one comes the newest one, and before the newest one goes the ++oldest. ++ ++The return value is always @code{nil}. ++@end deffn ++ ++@defvar yank-undo-function ++If this variable is non-@code{nil}, the function @code{yank-pop} uses ++its value instead of @code{delete-region} to delete the text ++inserted by the previous @code{yank} or ++@code{yank-pop} command. The value must be a function of two ++arguments, the start and end of the current region. ++ ++The function @code{insert-for-yank} automatically sets this variable ++according to the @var{undo} element of the @code{yank-handler} ++text property, if there is one. ++@end defvar ++ ++@node Low-Level Kill Ring ++@subsection Low-Level Kill Ring ++ ++ These functions and variables provide access to the kill ring at a ++lower level, but still convenient for use in Lisp programs, because they ++take care of interaction with window system selections ++(@pxref{Window System Selections}). ++ ++@defun current-kill n &optional do-not-move ++The function @code{current-kill} rotates the yanking pointer, which ++designates the ``front'' of the kill ring, by @var{n} places (from newer ++kills to older ones), and returns the text at that place in the ring. ++ ++If the optional second argument @var{do-not-move} is non-@code{nil}, ++then @code{current-kill} doesn't alter the yanking pointer; it just ++returns the @var{n}th kill, counting from the current yanking pointer. ++ ++If @var{n} is zero, indicating a request for the latest kill, ++@code{current-kill} calls the value of ++@code{interprogram-paste-function} (documented below) before ++consulting the kill ring. If that value is a function and calling it ++returns a string or a list of several string, @code{current-kill} ++pushes the strings onto the kill ring and returns the first string. ++It also sets the yanking pointer to point to the kill-ring entry of ++the first string returned by @code{interprogram-paste-function}, ++regardless of the value of @var{do-not-move}. Otherwise, ++@code{current-kill} does not treat a zero value for @var{n} specially: ++it returns the entry pointed at by the yanking pointer and does not ++move the yanking pointer. ++@end defun ++ ++@defun kill-new string &optional replace yank-handler ++This function pushes the text @var{string} onto the kill ring and ++makes the yanking pointer point to it. It discards the oldest entry ++if appropriate. It also invokes the value of ++@code{interprogram-cut-function} (see below). ++ ++If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the ++first element of the kill ring with @var{string}, rather than pushing ++@var{string} onto the kill ring. ++ ++If @var{yank-handler} is non-@code{nil}, this puts that value onto ++the string of killed text, as a @code{yank-handler} property. ++@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then ++@code{kill-new} copies any @code{yank-handler} properties present on ++@var{string} onto the kill ring, as it does with other text properties. ++@end defun ++ ++@defun kill-append string before-p &optional yank-handler ++This function appends the text @var{string} to the first entry in the ++kill ring and makes the yanking pointer point to the combined entry. ++Normally @var{string} goes at the end of the entry, but if ++@var{before-p} is non-@code{nil}, it goes at the beginning. This ++function also invokes the value of @code{interprogram-cut-function} ++(see below). This handles @var{yank-handler} just like ++@code{kill-new}, except that if @var{yank-handler} is different from ++the @code{yank-handler} property of the first entry of the kill ring, ++@code{kill-append} pushes the concatenated string onto the kill ring, ++instead of replacing the original first entry with it. ++@end defun ++ ++@defvar interprogram-paste-function ++This variable provides a way of transferring killed text from other ++programs, when you are using a window system. Its value should be ++@code{nil} or a function of no arguments. ++ ++If the value is a function, @code{current-kill} calls it to get the ++``most recent kill.'' If the function returns a non-@code{nil} value, ++then that value is used as the ``most recent kill.'' If it returns ++@code{nil}, then the front of the kill ring is used. ++ ++To facilitate support for window systems that support multiple ++selections, this function may also return a list of strings. In that ++case, the first string is used as the ``most recent kill'', and all ++the other strings are pushed onto the kill ring, for easy access by ++@code{yank-pop}. ++ ++The normal use of this function is to get the window system's primary ++selection as the most recent kill, even if the selection belongs to ++another application. @xref{Window System Selections}. However, if ++the selection was provided by the current Emacs session, this function ++should return @code{nil}. (If it is hard to tell whether Emacs or ++some other program provided the selection, it should be good enough to ++use @code{string=} to compare it with the last text Emacs provided.) ++@end defvar ++ ++@defvar interprogram-cut-function ++This variable provides a way of communicating killed text to other ++programs, when you are using a window system. Its value should be ++@code{nil} or a function of one required and one optional argument. ++ ++If the value is a function, @code{kill-new} and @code{kill-append} call ++it with the new first element of the kill ring as the first argument. ++The second, optional, argument has the same meaning as the @var{push} ++argument to @code{x-set-cut-buffer} (@pxref{Definition of ++x-set-cut-buffer}) and only affects the second and later cut buffers. ++ ++The normal use of this function is to set the window system's primary ++selection (and first cut buffer) from the newly killed text. ++@xref{Window System Selections}. ++@end defvar ++ ++@node Internals of Kill Ring ++@comment node-name, next, previous, up ++@subsection Internals of the Kill Ring ++ ++ The variable @code{kill-ring} holds the kill ring contents, in the ++form of a list of strings. The most recent kill is always at the front ++of the list. ++ ++ The @code{kill-ring-yank-pointer} variable points to a link in the ++kill ring list, whose @sc{car} is the text to yank next. We say it ++identifies the ``front'' of the ring. Moving ++@code{kill-ring-yank-pointer} to a different link is called ++@dfn{rotating the kill ring}. We call the kill ring a ``ring'' because ++the functions that move the yank pointer wrap around from the end of the ++list to the beginning, or vice-versa. Rotation of the kill ring is ++virtual; it does not change the value of @code{kill-ring}. ++ ++ Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp ++variables whose values are normally lists. The word ``pointer'' in the ++name of the @code{kill-ring-yank-pointer} indicates that the variable's ++purpose is to identify one element of the list for use by the next yank ++command. ++ ++ The value of @code{kill-ring-yank-pointer} is always @code{eq} to one ++of the links in the kill ring list. The element it identifies is the ++@sc{car} of that link. Kill commands, which change the kill ring, also ++set this variable to the value of @code{kill-ring}. The effect is to ++rotate the ring so that the newly killed text is at the front. ++ ++ Here is a diagram that shows the variable @code{kill-ring-yank-pointer} ++pointing to the second entry in the kill ring @code{("some text" "a ++different piece of text" "yet older text")}. ++ ++@example ++@group ++kill-ring ---- kill-ring-yank-pointer ++ | | ++ | v ++ | --- --- --- --- --- --- ++ --> | | |------> | | |--> | | |--> nil ++ --- --- --- --- --- --- ++ | | | ++ | | | ++ | | -->"yet older text" ++ | | ++ | --> "a different piece of text" ++ | ++ --> "some text" ++@end group ++@end example ++ ++@noindent ++This state of affairs might occur after @kbd{C-y} (@code{yank}) ++immediately followed by @kbd{M-y} (@code{yank-pop}). ++ ++@defvar kill-ring ++This variable holds the list of killed text sequences, most recently ++killed first. ++@end defvar ++ ++@defvar kill-ring-yank-pointer ++This variable's value indicates which element of the kill ring is at the ++``front'' of the ring for yanking. More precisely, the value is a tail ++of the value of @code{kill-ring}, and its @sc{car} is the kill string ++that @kbd{C-y} should yank. ++@end defvar ++ ++@defopt kill-ring-max ++The value of this variable is the maximum length to which the kill ++ring can grow, before elements are thrown away at the end. The default ++value for @code{kill-ring-max} is 60. ++@end defopt ++ ++@node Undo ++@comment node-name, next, previous, up ++@section Undo ++@cindex redo ++ ++ Most buffers have an @dfn{undo list}, which records all changes made ++to the buffer's text so that they can be undone. (The buffers that ++don't have one are usually special-purpose buffers for which Emacs ++assumes that undoing is not useful. In particular, any buffer whose ++name begins with a space has its undo recording off by default; ++see @ref{Buffer Names}.) All the primitives that modify the ++text in the buffer automatically add elements to the front of the undo ++list, which is in the variable @code{buffer-undo-list}. ++ ++@defvar buffer-undo-list ++This buffer-local variable's value is the undo list of the current ++buffer. A value of @code{t} disables the recording of undo information. ++@end defvar ++ ++Here are the kinds of elements an undo list can have: ++ ++@table @code ++@item @var{position} ++This kind of element records a previous value of point; undoing this ++element moves point to @var{position}. Ordinary cursor motion does not ++make any sort of undo record, but deletion operations use these entries ++to record where point was before the command. ++ ++@item (@var{beg} . @var{end}) ++This kind of element indicates how to delete text that was inserted. ++Upon insertion, the text occupied the range @var{beg}--@var{end} in the ++buffer. ++ ++@item (@var{text} . @var{position}) ++This kind of element indicates how to reinsert text that was deleted. ++The deleted text itself is the string @var{text}. The place to ++reinsert it is @code{(abs @var{position})}. If @var{position} is ++positive, point was at the beginning of the deleted text, otherwise it ++was at the end. ++ ++@item (t @var{high} . @var{low}) ++This kind of element indicates that an unmodified buffer became ++modified. The elements @var{high} and @var{low} are two integers, each ++recording 16 bits of the visited file's modification time as of when it ++was previously visited or saved. @code{primitive-undo} uses those ++values to determine whether to mark the buffer as unmodified once again; ++it does so only if the file's modification time matches those numbers. ++ ++@item (nil @var{property} @var{value} @var{beg} . @var{end}) ++This kind of element records a change in a text property. ++Here's how you might undo the change: ++ ++@example ++(put-text-property @var{beg} @var{end} @var{property} @var{value}) ++@end example ++ ++@item (@var{marker} . @var{adjustment}) ++This kind of element records the fact that the marker @var{marker} was ++relocated due to deletion of surrounding text, and that it moved ++@var{adjustment} character positions. Undoing this element moves ++@var{marker} @minus{} @var{adjustment} characters. ++ ++@item (apply @var{funname} . @var{args}) ++This is an extensible undo item, which is undone by calling ++@var{funname} with arguments @var{args}. ++ ++@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args}) ++This is an extensible undo item, which records a change limited to the ++range @var{beg} to @var{end}, which increased the size of the buffer ++by @var{delta}. It is undone by calling @var{funname} with arguments ++@var{args}. ++ ++This kind of element enables undo limited to a region to determine ++whether the element pertains to that region. ++ ++@item nil ++This element is a boundary. The elements between two boundaries are ++called a @dfn{change group}; normally, each change group corresponds to ++one keyboard command, and undo commands normally undo an entire group as ++a unit. ++@end table ++ ++@defun undo-boundary ++This function places a boundary element in the undo list. The undo ++command stops at such a boundary, and successive undo commands undo ++to earlier and earlier boundaries. This function returns @code{nil}. ++ ++The editor command loop automatically creates an undo boundary before ++each key sequence is executed. Thus, each undo normally undoes the ++effects of one command. Self-inserting input characters are an ++exception. The command loop makes a boundary for the first such ++character; the next 19 consecutive self-inserting input characters do ++not make boundaries, and then the 20th does, and so on as long as ++self-inserting characters continue. ++ ++All buffer modifications add a boundary whenever the previous undoable ++change was made in some other buffer. This is to ensure that ++each command makes a boundary in each buffer where it makes changes. ++ ++Calling this function explicitly is useful for splitting the effects of ++a command into more than one unit. For example, @code{query-replace} ++calls @code{undo-boundary} after each replacement, so that the user can ++undo individual replacements one by one. ++@end defun ++ ++@defvar undo-in-progress ++This variable is normally @code{nil}, but the undo commands bind it to ++@code{t}. This is so that various kinds of change hooks can tell when ++they're being called for the sake of undoing. ++@end defvar ++ ++@defun primitive-undo count list ++This is the basic function for undoing elements of an undo list. ++It undoes the first @var{count} elements of @var{list}, returning ++the rest of @var{list}. ++ ++@code{primitive-undo} adds elements to the buffer's undo list when it ++changes the buffer. Undo commands avoid confusion by saving the undo ++list value at the beginning of a sequence of undo operations. Then the ++undo operations use and update the saved value. The new elements added ++by undoing are not part of this saved value, so they don't interfere with ++continuing to undo. ++ ++This function does not bind @code{undo-in-progress}. ++@end defun ++ ++@node Maintaining Undo ++@section Maintaining Undo Lists ++ ++ This section describes how to enable and disable undo information for ++a given buffer. It also explains how the undo list is truncated ++automatically so it doesn't get too big. ++ ++ Recording of undo information in a newly created buffer is normally ++enabled to start with; but if the buffer name starts with a space, the ++undo recording is initially disabled. You can explicitly enable or ++disable undo recording with the following two functions, or by setting ++@code{buffer-undo-list} yourself. ++ ++@deffn Command buffer-enable-undo &optional buffer-or-name ++This command enables recording undo information for buffer ++@var{buffer-or-name}, so that subsequent changes can be undone. If no ++argument is supplied, then the current buffer is used. This function ++does nothing if undo recording is already enabled in the buffer. It ++returns @code{nil}. ++ ++In an interactive call, @var{buffer-or-name} is the current buffer. ++You cannot specify any other buffer. ++@end deffn ++ ++@deffn Command buffer-disable-undo &optional buffer-or-name ++@cindex disabling undo ++This function discards the undo list of @var{buffer-or-name}, and disables ++further recording of undo information. As a result, it is no longer ++possible to undo either previous changes or any subsequent changes. If ++the undo list of @var{buffer-or-name} is already disabled, this function ++has no effect. ++ ++This function returns @code{nil}. ++@end deffn ++ ++ As editing continues, undo lists get longer and longer. To prevent ++them from using up all available memory space, garbage collection trims ++them back to size limits you can set. (For this purpose, the ``size'' ++of an undo list measures the cons cells that make up the list, plus the ++strings of deleted text.) Three variables control the range of acceptable ++sizes: @code{undo-limit}, @code{undo-strong-limit} and ++@code{undo-outer-limit}. In these variables, size is counted as the ++number of bytes occupied, which includes both saved text and other ++data. ++ ++@defopt undo-limit ++This is the soft limit for the acceptable size of an undo list. The ++change group at which this size is exceeded is the last one kept. ++@end defopt ++ ++@defopt undo-strong-limit ++This is the upper limit for the acceptable size of an undo list. The ++change group at which this size is exceeded is discarded itself (along ++with all older change groups). There is one exception: the very latest ++change group is only discarded if it exceeds @code{undo-outer-limit}. ++@end defopt ++ ++@defopt undo-outer-limit ++If at garbage collection time the undo info for the current command ++exceeds this limit, Emacs discards the info and displays a warning. ++This is a last ditch limit to prevent memory overflow. ++@end defopt ++ ++@defopt undo-ask-before-discard ++If this variable is non-@code{nil}, when the undo info exceeds ++@code{undo-outer-limit}, Emacs asks in the echo area whether to ++discard the info. The default value is @code{nil}, which means to ++discard it automatically. ++ ++This option is mainly intended for debugging. Garbage collection is ++inhibited while the question is asked, which means that Emacs might ++leak memory if the user waits too long before answering the question. ++@end defopt ++ ++@node Filling ++@comment node-name, next, previous, up ++@section Filling ++@cindex filling text ++ ++ @dfn{Filling} means adjusting the lengths of lines (by moving the line ++breaks) so that they are nearly (but no greater than) a specified ++maximum width. Additionally, lines can be @dfn{justified}, which means ++inserting spaces to make the left and/or right margins line up ++precisely. The width is controlled by the variable @code{fill-column}. ++For ease of reading, lines should be no longer than 70 or so columns. ++ ++ You can use Auto Fill mode (@pxref{Auto Filling}) to fill text ++automatically as you insert it, but changes to existing text may leave ++it improperly filled. Then you must fill the text explicitly. ++ ++ Most of the commands in this section return values that are not ++meaningful. All the functions that do filling take note of the current ++left margin, current right margin, and current justification style ++(@pxref{Margins}). If the current justification style is ++@code{none}, the filling functions don't actually do anything. ++ ++ Several of the filling functions have an argument @var{justify}. ++If it is non-@code{nil}, that requests some kind of justification. It ++can be @code{left}, @code{right}, @code{full}, or @code{center}, to ++request a specific style of justification. If it is @code{t}, that ++means to use the current justification style for this part of the text ++(see @code{current-justification}, below). Any other value is treated ++as @code{full}. ++ ++ When you call the filling functions interactively, using a prefix ++argument implies the value @code{full} for @var{justify}. ++ ++@deffn Command fill-paragraph &optional justify region ++This command fills the paragraph at or after point. If ++@var{justify} is non-@code{nil}, each line is justified as well. ++It uses the ordinary paragraph motion commands to find paragraph ++boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}. ++ ++When @var{region} is non-@code{nil}, then if Transient Mark mode is ++enabled and the mark is active, this command calls @code{fill-region} ++to fill all the paragraphs in the region, instead of filling only the ++current paragraph. When this command is called interactively, ++@var{region} is @code{t}. ++@end deffn ++ ++@deffn Command fill-region start end &optional justify nosqueeze to-eop ++This command fills each of the paragraphs in the region from @var{start} ++to @var{end}. It justifies as well if @var{justify} is ++non-@code{nil}. ++ ++If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace ++other than line breaks untouched. If @var{to-eop} is non-@code{nil}, ++that means to keep filling to the end of the paragraph---or the next hard ++newline, if @code{use-hard-newlines} is enabled (see below). ++ ++The variable @code{paragraph-separate} controls how to distinguish ++paragraphs. @xref{Standard Regexps}. ++@end deffn ++ ++@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp ++This command fills each paragraph in the region according to its ++individual fill prefix. Thus, if the lines of a paragraph were indented ++with spaces, the filled paragraph will remain indented in the same ++fashion. ++ ++The first two arguments, @var{start} and @var{end}, are the beginning ++and end of the region to be filled. The third and fourth arguments, ++@var{justify} and @var{citation-regexp}, are optional. If ++@var{justify} is non-@code{nil}, the paragraphs are justified as ++well as filled. If @var{citation-regexp} is non-@code{nil}, it means the ++function is operating on a mail message and therefore should not fill ++the header lines. If @var{citation-regexp} is a string, it is used as ++a regular expression; if it matches the beginning of a line, that line ++is treated as a citation marker. ++ ++Ordinarily, @code{fill-individual-paragraphs} regards each change in ++indentation as starting a new paragraph. If ++@code{fill-individual-varying-indent} is non-@code{nil}, then only ++separator lines separate paragraphs. That mode can handle indented ++paragraphs with additional indentation on the first line. ++@end deffn ++ ++@defopt fill-individual-varying-indent ++This variable alters the action of @code{fill-individual-paragraphs} as ++described above. ++@end defopt ++ ++@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after ++This command considers a region of text as a single paragraph and fills ++it. If the region was made up of many paragraphs, the blank lines ++between paragraphs are removed. This function justifies as well as ++filling when @var{justify} is non-@code{nil}. ++ ++If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace ++other than line breaks untouched. If @var{squeeze-after} is ++non-@code{nil}, it specifies a position in the region, and means don't ++canonicalize spaces before that position. ++ ++In Adaptive Fill mode, this command calls @code{fill-context-prefix} to ++choose a fill prefix by default. @xref{Adaptive Fill}. ++@end deffn ++ ++@deffn Command justify-current-line &optional how eop nosqueeze ++This command inserts spaces between the words of the current line so ++that the line ends exactly at @code{fill-column}. It returns ++@code{nil}. ++ ++The argument @var{how}, if non-@code{nil} specifies explicitly the style ++of justification. It can be @code{left}, @code{right}, @code{full}, ++@code{center}, or @code{none}. If it is @code{t}, that means to do ++follow specified justification style (see @code{current-justification}, ++below). @code{nil} means to do full justification. ++ ++If @var{eop} is non-@code{nil}, that means do only left-justification ++if @code{current-justification} specifies full justification. This is ++used for the last line of a paragraph; even if the paragraph as a ++whole is fully justified, the last line should not be. ++ ++If @var{nosqueeze} is non-@code{nil}, that means do not change interior ++whitespace. ++@end deffn ++ ++@defopt default-justification ++This variable's value specifies the style of justification to use for ++text that doesn't specify a style with a text property. The possible ++values are @code{left}, @code{right}, @code{full}, @code{center}, or ++@code{none}. The default value is @code{left}. ++@end defopt ++ ++@defun current-justification ++This function returns the proper justification style to use for filling ++the text around point. ++ ++This returns the value of the @code{justification} text property at ++point, or the variable @var{default-justification} if there is no such ++text property. However, it returns @code{nil} rather than @code{none} ++to mean ``don't justify''. ++@end defun ++ ++@defopt sentence-end-double-space ++@anchor{Definition of sentence-end-double-space} ++If this variable is non-@code{nil}, a period followed by just one space ++does not count as the end of a sentence, and the filling functions ++avoid breaking the line at such a place. ++@end defopt ++ ++@defopt sentence-end-without-period ++If this variable is non-@code{nil}, a sentence can end without a ++period. This is used for languages like Thai, where sentences end ++with a double space but without a period. ++@end defopt ++ ++@defopt sentence-end-without-space ++If this variable is non-@code{nil}, it should be a string of ++characters that can end a sentence without following spaces. ++@end defopt ++ ++@defvar fill-paragraph-function ++This variable provides a way to override the filling of paragraphs. ++If its value is non-@code{nil}, @code{fill-paragraph} calls this ++function to do the work. If the function returns a non-@code{nil} ++value, @code{fill-paragraph} assumes the job is done, and immediately ++returns that value. ++ ++The usual use of this feature is to fill comments in programming ++language modes. If the function needs to fill a paragraph in the usual ++way, it can do so as follows: ++ ++@example ++(let ((fill-paragraph-function nil)) ++ (fill-paragraph arg)) ++@end example ++@end defvar ++ ++@defvar fill-forward-paragraph-function ++This variable provides a way to override how the filling functions, ++such as @code{fill-region} and @code{fill-paragraph}, move forward to ++the next paragraph. Its value should be a function, which is called ++with a single argument @var{n}, the number of paragraphs to move, and ++should return the difference between @var{n} and the number of ++paragraphs actually moved. The default value of this variable is ++@code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs ++Manual}. ++@end defvar ++ ++@defvar use-hard-newlines ++If this variable is non-@code{nil}, the filling functions do not delete ++newlines that have the @code{hard} text property. These ``hard ++newlines'' act as paragraph separators. ++@end defvar ++ ++@node Margins ++@section Margins for Filling ++ ++@defopt fill-prefix ++This buffer-local variable, if non-@code{nil}, specifies a string of ++text that appears at the beginning of normal text lines and should be ++disregarded when filling them. Any line that fails to start with the ++fill prefix is considered the start of a paragraph; so is any line ++that starts with the fill prefix followed by additional whitespace. ++Lines that start with the fill prefix but no additional whitespace are ++ordinary text lines that can be filled together. The resulting filled ++lines also start with the fill prefix. ++ ++The fill prefix follows the left margin whitespace, if any. ++@end defopt ++ ++@defopt fill-column ++This buffer-local variable specifies the maximum width of filled lines. ++Its value should be an integer, which is a number of columns. All the ++filling, justification, and centering commands are affected by this ++variable, including Auto Fill mode (@pxref{Auto Filling}). ++ ++As a practical matter, if you are writing text for other people to ++read, you should set @code{fill-column} to no more than 70. Otherwise ++the line will be too long for people to read comfortably, and this can ++make the text seem clumsy. ++@end defopt ++ ++@defvar default-fill-column ++The value of this variable is the default value for @code{fill-column} in ++buffers that do not override it. This is the same as ++@code{(default-value 'fill-column)}. ++ ++The default value for @code{default-fill-column} is 70. ++@end defvar ++ ++@deffn Command set-left-margin from to margin ++This sets the @code{left-margin} property on the text from @var{from} to ++@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this ++command also refills the region to fit the new margin. ++@end deffn ++ ++@deffn Command set-right-margin from to margin ++This sets the @code{right-margin} property on the text from @var{from} ++to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, ++this command also refills the region to fit the new margin. ++@end deffn ++ ++@defun current-left-margin ++This function returns the proper left margin value to use for filling ++the text around point. The value is the sum of the @code{left-margin} ++property of the character at the start of the current line (or zero if ++none), and the value of the variable @code{left-margin}. ++@end defun ++ ++@defun current-fill-column ++This function returns the proper fill column value to use for filling ++the text around point. The value is the value of the @code{fill-column} ++variable, minus the value of the @code{right-margin} property of the ++character after point. ++@end defun ++ ++@deffn Command move-to-left-margin &optional n force ++This function moves point to the left margin of the current line. The ++column moved to is determined by calling the function ++@code{current-left-margin}. If the argument @var{n} is non-@code{nil}, ++@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first. ++ ++If @var{force} is non-@code{nil}, that says to fix the line's ++indentation if that doesn't match the left margin value. ++@end deffn ++ ++@defun delete-to-left-margin &optional from to ++This function removes left margin indentation from the text between ++@var{from} and @var{to}. The amount of indentation to delete is ++determined by calling @code{current-left-margin}. In no case does this ++function delete non-whitespace. If @var{from} and @var{to} are omitted, ++they default to the whole buffer. ++@end defun ++ ++@defun indent-to-left-margin ++This function adjusts the indentation at the beginning of the current ++line to the value specified by the variable @code{left-margin}. (That ++may involve either inserting or deleting whitespace.) This function ++is value of @code{indent-line-function} in Paragraph-Indent Text mode. ++@end defun ++ ++@defopt left-margin ++This variable specifies the base left margin column. In Fundamental ++mode, @kbd{C-j} indents to this column. This variable automatically ++becomes buffer-local when set in any fashion. ++@end defopt ++ ++@defopt fill-nobreak-predicate ++This variable gives major modes a way to specify not to break a line ++at certain places. Its value should be a list of functions. Whenever ++filling considers breaking the line at a certain place in the buffer, ++it calls each of these functions with no arguments and with point ++located at that place. If any of the functions returns ++non-@code{nil}, then the line won't be broken there. ++@end defopt ++ ++@node Adaptive Fill ++@section Adaptive Fill Mode ++@c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent. ++ ++ When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill ++prefix automatically from the text in each paragraph being filled ++rather than using a predetermined value. During filling, this fill ++prefix gets inserted at the start of the second and subsequent lines ++of the paragraph as described in @ref{Filling}, and in @ref{Auto ++Filling}. ++ ++@defopt adaptive-fill-mode ++Adaptive Fill mode is enabled when this variable is non-@code{nil}. ++It is @code{t} by default. ++@end defopt ++ ++@defun fill-context-prefix from to ++This function implements the heart of Adaptive Fill mode; it chooses a ++fill prefix based on the text between @var{from} and @var{to}, ++typically the start and end of a paragraph. It does this by looking ++at the first two lines of the paragraph, based on the variables ++described below. ++@c The optional argument first-line-regexp is not documented ++@c because it exists for internal purposes and might be eliminated ++@c in the future. ++ ++Usually, this function returns the fill prefix, a string. However, ++before doing this, the function makes a final check (not specially ++mentioned in the following) that a line starting with this prefix ++wouldn't look like the start of a paragraph. Should this happen, the ++function signals the anomaly by returning @code{nil} instead. ++ ++In detail, @code{fill-context-prefix} does this: ++ ++@enumerate ++@item ++It takes a candidate for the fill prefix from the first line---it ++tries first the function in @code{adaptive-fill-function} (if any), ++then the regular expression @code{adaptive-fill-regexp} (see below). ++The first non-@code{nil} result of these, or the empty string if ++they're both @code{nil}, becomes the first line's candidate. ++@item ++If the paragraph has as yet only one line, the function tests the ++validity of the prefix candidate just found. The function then ++returns the candidate if it's valid, or a string of spaces otherwise. ++(see the description of @code{adaptive-fill-first-line-regexp} below). ++@item ++When the paragraph already has two lines, the function next looks for ++a prefix candidate on the second line, in just the same way it did for ++the first line. If it doesn't find one, it returns @code{nil}. ++@item ++The function now compares the two candidate prefixes heuristically: if ++the non-whitespace characters in the line 2 candidate occur in the ++same order in the line 1 candidate, the function returns the line 2 ++candidate. Otherwise, it returns the largest initial substring which ++is common to both candidates (which might be the empty string). ++@end enumerate ++@end defun ++ ++@defopt adaptive-fill-regexp ++Adaptive Fill mode matches this regular expression against the text ++starting after the left margin whitespace (if any) on a line; the ++characters it matches are that line's candidate for the fill prefix. ++ ++The default value matches whitespace with certain punctuation ++characters intermingled. ++@end defopt ++ ++@defopt adaptive-fill-first-line-regexp ++Used only in one-line paragraphs, this regular expression acts as an ++additional check of the validity of the one available candidate fill ++prefix: the candidate must match this regular expression, or match ++@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} ++replaces the candidate with a string of spaces ``of the same width'' ++as it. ++ ++The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which ++matches only a string of whitespace. The effect of this default is to ++force the fill prefixes found in one-line paragraphs always to be pure ++whitespace. ++@end defopt ++ ++@defopt adaptive-fill-function ++You can specify more complex ways of choosing a fill prefix ++automatically by setting this variable to a function. The function is ++called with point after the left margin (if any) of a line, and it ++must preserve point. It should return either ``that line's'' fill ++prefix or @code{nil}, meaning it has failed to determine a prefix. ++@end defopt ++ ++@node Auto Filling ++@comment node-name, next, previous, up ++@section Auto Filling ++@cindex filling, automatic ++@cindex Auto Fill mode ++ ++ Auto Fill mode is a minor mode that fills lines automatically as text ++is inserted. This section describes the hook used by Auto Fill mode. ++For a description of functions that you can call explicitly to fill and ++justify existing text, see @ref{Filling}. ++ ++ Auto Fill mode also enables the functions that change the margins and ++justification style to refill portions of the text. @xref{Margins}. ++ ++@defvar auto-fill-function ++The value of this buffer-local variable should be a function (of no ++arguments) to be called after self-inserting a character from the table ++@code{auto-fill-chars}. It may be @code{nil}, in which case nothing ++special is done in that case. ++ ++The value of @code{auto-fill-function} is @code{do-auto-fill} when ++Auto-Fill mode is enabled. That is a function whose sole purpose is to ++implement the usual strategy for breaking a line. ++ ++@quotation ++In older Emacs versions, this variable was named @code{auto-fill-hook}, ++but since it is not called with the standard convention for hooks, it ++was renamed to @code{auto-fill-function} in version 19. ++@end quotation ++@end defvar ++ ++@defvar normal-auto-fill-function ++This variable specifies the function to use for ++@code{auto-fill-function}, if and when Auto Fill is turned on. Major ++modes can set buffer-local values for this variable to alter how Auto ++Fill works. ++@end defvar ++ ++@defvar auto-fill-chars ++A char table of characters which invoke @code{auto-fill-function} when ++self-inserted---space and newline in most language environments. They ++have an entry @code{t} in the table. ++@end defvar ++ ++@node Sorting ++@section Sorting Text ++@cindex sorting text ++ ++ The sorting functions described in this section all rearrange text in ++a buffer. This is in contrast to the function @code{sort}, which ++rearranges the order of the elements of a list (@pxref{Rearrangement}). ++The values returned by these functions are not meaningful. ++ ++@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate ++This function is the general text-sorting routine that subdivides a ++buffer into records and then sorts them. Most of the commands in this ++section use this function. ++ ++To understand how @code{sort-subr} works, consider the whole accessible ++portion of the buffer as being divided into disjoint pieces called ++@dfn{sort records}. The records may or may not be contiguous, but they ++must not overlap. A portion of each sort record (perhaps all of it) is ++designated as the sort key. Sorting rearranges the records in order by ++their sort keys. ++ ++Usually, the records are rearranged in order of ascending sort key. ++If the first argument to the @code{sort-subr} function, @var{reverse}, ++is non-@code{nil}, the sort records are rearranged in order of ++descending sort key. ++ ++The next four arguments to @code{sort-subr} are functions that are ++called to move point across a sort record. They are called many times ++from within @code{sort-subr}. ++ ++@enumerate ++@item ++@var{nextrecfun} is called with point at the end of a record. This ++function moves point to the start of the next record. The first record ++is assumed to start at the position of point when @code{sort-subr} is ++called. Therefore, you should usually move point to the beginning of ++the buffer before calling @code{sort-subr}. ++ ++This function can indicate there are no more sort records by leaving ++point at the end of the buffer. ++ ++@item ++@var{endrecfun} is called with point within a record. It moves point to ++the end of the record. ++ ++@item ++@var{startkeyfun} is called to move point from the start of a record to ++the start of the sort key. This argument is optional; if it is omitted, ++the whole record is the sort key. If supplied, the function should ++either return a non-@code{nil} value to be used as the sort key, or ++return @code{nil} to indicate that the sort key is in the buffer ++starting at point. In the latter case, @var{endkeyfun} is called to ++find the end of the sort key. ++ ++@item ++@var{endkeyfun} is called to move point from the start of the sort key ++to the end of the sort key. This argument is optional. If ++@var{startkeyfun} returns @code{nil} and this argument is omitted (or ++@code{nil}), then the sort key extends to the end of the record. There ++is no need for @var{endkeyfun} if @var{startkeyfun} returns a ++non-@code{nil} value. ++@end enumerate ++ ++The argument @var{predicate} is the function to use to compare keys. ++If keys are numbers, it defaults to @code{<}; otherwise it defaults to ++@code{string<}. ++ ++As an example of @code{sort-subr}, here is the complete function ++definition for @code{sort-lines}: ++ ++@example ++@group ++;; @r{Note that the first two lines of doc string} ++;; @r{are effectively one line when viewed by a user.} ++(defun sort-lines (reverse beg end) ++ "Sort lines in region alphabetically;\ ++ argument means descending order. ++Called from a program, there are three arguments: ++@end group ++@group ++REVERSE (non-nil means reverse order),\ ++ BEG and END (region to sort). ++The variable `sort-fold-case' determines\ ++ whether alphabetic case affects ++the sort order." ++@end group ++@group ++ (interactive "P\nr") ++ (save-excursion ++ (save-restriction ++ (narrow-to-region beg end) ++ (goto-char (point-min)) ++ (let ((inhibit-field-text-motion t)) ++ (sort-subr reverse 'forward-line 'end-of-line))))) ++@end group ++@end example ++ ++Here @code{forward-line} moves point to the start of the next record, ++and @code{end-of-line} moves point to the end of record. We do not pass ++the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire ++record is used as the sort key. ++ ++The @code{sort-paragraphs} function is very much the same, except that ++its @code{sort-subr} call looks like this: ++ ++@example ++@group ++(sort-subr reverse ++ (function ++ (lambda () ++ (while (and (not (eobp)) ++ (looking-at paragraph-separate)) ++ (forward-line 1)))) ++ 'forward-paragraph) ++@end group ++@end example ++ ++Markers pointing into any sort records are left with no useful ++position after @code{sort-subr} returns. ++@end defun ++ ++@defopt sort-fold-case ++If this variable is non-@code{nil}, @code{sort-subr} and the other ++buffer sorting functions ignore case when comparing strings. ++@end defopt ++ ++@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end ++This command sorts the region between @var{start} and @var{end} ++alphabetically as specified by @var{record-regexp} and @var{key-regexp}. ++If @var{reverse} is a negative integer, then sorting is in reverse ++order. ++ ++Alphabetical sorting means that two sort keys are compared by ++comparing the first characters of each, the second characters of each, ++and so on. If a mismatch is found, it means that the sort keys are ++unequal; the sort key whose character is less at the point of first ++mismatch is the lesser sort key. The individual characters are compared ++according to their numerical character codes in the Emacs character set. ++ ++The value of the @var{record-regexp} argument specifies how to divide ++the buffer into sort records. At the end of each record, a search is ++done for this regular expression, and the text that matches it is taken ++as the next record. For example, the regular expression @samp{^.+$}, ++which matches lines with at least one character besides a newline, would ++make each such line into a sort record. @xref{Regular Expressions}, for ++a description of the syntax and meaning of regular expressions. ++ ++The value of the @var{key-regexp} argument specifies what part of each ++record is the sort key. The @var{key-regexp} could match the whole ++record, or only a part. In the latter case, the rest of the record has ++no effect on the sorted order of records, but it is carried along when ++the record moves to its new position. ++ ++The @var{key-regexp} argument can refer to the text matched by a ++subexpression of @var{record-regexp}, or it can be a regular expression ++on its own. ++ ++If @var{key-regexp} is: ++ ++@table @asis ++@item @samp{\@var{digit}} ++then the text matched by the @var{digit}th @samp{\(...\)} parenthesis ++grouping in @var{record-regexp} is the sort key. ++ ++@item @samp{\&} ++then the whole record is the sort key. ++ ++@item a regular expression ++then @code{sort-regexp-fields} searches for a match for the regular ++expression within the record. If such a match is found, it is the sort ++key. If there is no match for @var{key-regexp} within a record then ++that record is ignored, which means its position in the buffer is not ++changed. (The other records may move around it.) ++@end table ++ ++For example, if you plan to sort all the lines in the region by the ++first word on each line starting with the letter @samp{f}, you should ++set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to ++@samp{\}. The resulting expression looks like this: ++ ++@example ++@group ++(sort-regexp-fields nil "^.*$" "\\" ++ (region-beginning) ++ (region-end)) ++@end group ++@end example ++ ++If you call @code{sort-regexp-fields} interactively, it prompts for ++@var{record-regexp} and @var{key-regexp} in the minibuffer. ++@end deffn ++ ++@deffn Command sort-lines reverse start end ++This command alphabetically sorts lines in the region between ++@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort ++is in reverse order. ++@end deffn ++ ++@deffn Command sort-paragraphs reverse start end ++This command alphabetically sorts paragraphs in the region between ++@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort ++is in reverse order. ++@end deffn ++ ++@deffn Command sort-pages reverse start end ++This command alphabetically sorts pages in the region between ++@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort ++is in reverse order. ++@end deffn ++ ++@deffn Command sort-fields field start end ++This command sorts lines in the region between @var{start} and ++@var{end}, comparing them alphabetically by the @var{field}th field ++of each line. Fields are separated by whitespace and numbered starting ++from 1. If @var{field} is negative, sorting is by the ++@w{@minus{}@var{field}th} field from the end of the line. This command ++is useful for sorting tables. ++@end deffn ++ ++@deffn Command sort-numeric-fields field start end ++This command sorts lines in the region between @var{start} and ++@var{end}, comparing them numerically by the @var{field}th field of ++each line. Fields are separated by whitespace and numbered starting ++from 1. The specified field must contain a number in each line of the ++region. Numbers starting with 0 are treated as octal, and numbers ++starting with @samp{0x} are treated as hexadecimal. ++ ++If @var{field} is negative, sorting is by the ++@w{@minus{}@var{field}th} field from the end of the line. This ++command is useful for sorting tables. ++@end deffn ++ ++@defopt sort-numeric-base ++This variable specifies the default radix for ++@code{sort-numeric-fields} to parse numbers. ++@end defopt ++ ++@deffn Command sort-columns reverse &optional beg end ++This command sorts the lines in the region between @var{beg} and ++@var{end}, comparing them alphabetically by a certain range of ++columns. The column positions of @var{beg} and @var{end} bound the ++range of columns to sort on. ++ ++If @var{reverse} is non-@code{nil}, the sort is in reverse order. ++ ++One unusual thing about this command is that the entire line ++containing position @var{beg}, and the entire line containing position ++@var{end}, are included in the region sorted. ++ ++Note that @code{sort-columns} rejects text that contains tabs, because ++tabs could be split across the specified columns. Use @kbd{M-x ++untabify} to convert tabs to spaces before sorting. ++ ++When possible, this command actually works by calling the @code{sort} ++utility program. ++@end deffn ++ ++@node Columns ++@comment node-name, next, previous, up ++@section Counting Columns ++@cindex columns ++@cindex counting columns ++@cindex horizontal position ++ ++ The column functions convert between a character position (counting ++characters from the beginning of the buffer) and a column position ++(counting screen characters from the beginning of a line). ++ ++ These functions count each character according to the number of ++columns it occupies on the screen. This means control characters count ++as occupying 2 or 4 columns, depending upon the value of ++@code{ctl-arrow}, and tabs count as occupying a number of columns that ++depends on the value of @code{tab-width} and on the column where the tab ++begins. @xref{Usual Display}. ++ ++ Column number computations ignore the width of the window and the ++amount of horizontal scrolling. Consequently, a column value can be ++arbitrarily high. The first (or leftmost) column is numbered 0. They ++also ignore overlays and text properties, aside from invisibility. ++ ++@defun current-column ++This function returns the horizontal position of point, measured in ++columns, counting from 0 at the left margin. The column position is the ++sum of the widths of all the displayed representations of the characters ++between the start of the current line and point. ++ ++For an example of using @code{current-column}, see the description of ++@code{count-lines} in @ref{Text Lines}. ++@end defun ++ ++@deffn Command move-to-column column &optional force ++This function moves point to @var{column} in the current line. The ++calculation of @var{column} takes into account the widths of the ++displayed representations of the characters between the start of the ++line and point. ++ ++When called interactively, @var{column} is the value of prefix numeric ++argument. If @var{column} is not an integer, an error is signaled. ++ ++If column @var{column} is beyond the end of the line, point moves to ++the end of the line. If @var{column} is negative, point moves to the ++beginning of the line. ++ ++If it is impossible to move to column @var{column} because that is in ++the middle of a multicolumn character such as a tab, point moves to the ++end of that character. However, if @var{force} is non-@code{nil}, and ++@var{column} is in the middle of a tab, then @code{move-to-column} ++converts the tab into spaces so that it can move precisely to column ++@var{column}. Other multicolumn characters can cause anomalies despite ++@var{force}, since there is no way to split them. ++ ++The argument @var{force} also has an effect if the line isn't long ++enough to reach column @var{column}; if it is @code{t}, that means to ++add whitespace at the end of the line to reach that column. ++ ++The return value is the column number actually moved to. ++@end deffn ++ ++@node Indentation ++@section Indentation ++@cindex indentation ++ ++ The indentation functions are used to examine, move to, and change ++whitespace that is at the beginning of a line. Some of the functions ++can also change whitespace elsewhere on a line. Columns and indentation ++count from zero at the left margin. ++ ++@menu ++* Primitive Indent:: Functions used to count and insert indentation. ++* Mode-Specific Indent:: Customize indentation for different modes. ++* Region Indent:: Indent all the lines in a region. ++* Relative Indent:: Indent the current line based on previous lines. ++* Indent Tabs:: Adjustable, typewriter-like tab stops. ++* Motion by Indent:: Move to first non-blank character. ++@end menu ++ ++@node Primitive Indent ++@subsection Indentation Primitives ++ ++ This section describes the primitive functions used to count and ++insert indentation. The functions in the following sections use these ++primitives. @xref{Width}, for related functions. ++ ++@defun current-indentation ++@comment !!Type Primitive Function ++@comment !!SourceFile indent.c ++This function returns the indentation of the current line, which is ++the horizontal position of the first nonblank character. If the ++contents are entirely blank, then this is the horizontal position of the ++end of the line. ++@end defun ++ ++@deffn Command indent-to column &optional minimum ++@comment !!Type Primitive Function ++@comment !!SourceFile indent.c ++This function indents from point with tabs and spaces until @var{column} ++is reached. If @var{minimum} is specified and non-@code{nil}, then at ++least that many spaces are inserted even if this requires going beyond ++@var{column}. Otherwise the function does nothing if point is already ++beyond @var{column}. The value is the column at which the inserted ++indentation ends. ++ ++The inserted whitespace characters inherit text properties from the ++surrounding text (usually, from the preceding text only). @xref{Sticky ++Properties}. ++@end deffn ++ ++@defopt indent-tabs-mode ++@comment !!SourceFile indent.c ++If this variable is non-@code{nil}, indentation functions can insert ++tabs as well as spaces. Otherwise, they insert only spaces. Setting ++this variable automatically makes it buffer-local in the current buffer. ++@end defopt ++ ++@node Mode-Specific Indent ++@subsection Indentation Controlled by Major Mode ++ ++ An important function of each major mode is to customize the @key{TAB} ++key to indent properly for the language being edited. This section ++describes the mechanism of the @key{TAB} key and how to control it. ++The functions in this section return unpredictable values. ++ ++@defvar indent-line-function ++This variable's value is the function to be used by @key{TAB} (and ++various commands) to indent the current line. The command ++@code{indent-according-to-mode} does no more than call this function. ++ ++In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C ++mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}. ++The default value is @code{indent-relative}. ++@end defvar ++ ++@deffn Command indent-according-to-mode ++This command calls the function in @code{indent-line-function} to ++indent the current line in a way appropriate for the current major mode. ++@end deffn ++ ++@deffn Command indent-for-tab-command &optional rigid ++This command calls the function in @code{indent-line-function} to ++indent the current line; however, if that function is ++@code{indent-to-left-margin}, @code{insert-tab} is called instead. ++(That is a trivial command that inserts a tab character.) If ++@var{rigid} is non-@code{nil}, this function also rigidly indents the ++entire balanced expression that starts at the beginning of the current ++line, to reflect change in indentation of the current line. ++@end deffn ++ ++@deffn Command newline-and-indent ++This function inserts a newline, then indents the new line (the one ++following the newline just inserted) according to the major mode. ++ ++It does indentation by calling the current @code{indent-line-function}. ++In programming language modes, this is the same thing @key{TAB} does, ++but in some text modes, where @key{TAB} inserts a tab, ++@code{newline-and-indent} indents to the column specified by ++@code{left-margin}. ++@end deffn ++ ++@deffn Command reindent-then-newline-and-indent ++@comment !!SourceFile simple.el ++This command reindents the current line, inserts a newline at point, ++and then indents the new line (the one following the newline just ++inserted). ++ ++This command does indentation on both lines according to the current ++major mode, by calling the current value of @code{indent-line-function}. ++In programming language modes, this is the same thing @key{TAB} does, ++but in some text modes, where @key{TAB} inserts a tab, ++@code{reindent-then-newline-and-indent} indents to the column specified ++by @code{left-margin}. ++@end deffn ++ ++@node Region Indent ++@subsection Indenting an Entire Region ++ ++ This section describes commands that indent all the lines in the ++region. They return unpredictable values. ++ ++@deffn Command indent-region start end &optional to-column ++This command indents each nonblank line starting between @var{start} ++(inclusive) and @var{end} (exclusive). If @var{to-column} is ++@code{nil}, @code{indent-region} indents each nonblank line by calling ++the current mode's indentation function, the value of ++@code{indent-line-function}. ++ ++If @var{to-column} is non-@code{nil}, it should be an integer ++specifying the number of columns of indentation; then this function ++gives each line exactly that much indentation, by either adding or ++deleting whitespace. ++ ++If there is a fill prefix, @code{indent-region} indents each line ++by making it start with the fill prefix. ++@end deffn ++ ++@defvar indent-region-function ++The value of this variable is a function that can be used by ++@code{indent-region} as a short cut. It should take two arguments, the ++start and end of the region. You should design the function so ++that it will produce the same results as indenting the lines of the ++region one by one, but presumably faster. ++ ++If the value is @code{nil}, there is no short cut, and ++@code{indent-region} actually works line by line. ++ ++A short-cut function is useful in modes such as C mode and Lisp mode, ++where the @code{indent-line-function} must scan from the beginning of ++the function definition: applying it to each line would be quadratic in ++time. The short cut can update the scan information as it moves through ++the lines indenting them; this takes linear time. In a mode where ++indenting a line individually is fast, there is no need for a short cut. ++ ++@code{indent-region} with a non-@code{nil} argument @var{to-column} has ++a different meaning and does not use this variable. ++@end defvar ++ ++@deffn Command indent-rigidly start end count ++This command indents all lines starting between @var{start} ++(inclusive) and @var{end} (exclusive) sideways by @var{count} columns. ++This ``preserves the shape'' of the affected region, moving it as a ++rigid unit. Consequently, this command is useful not only for indenting ++regions of unindented text, but also for indenting regions of formatted ++code. ++ ++For example, if @var{count} is 3, this command adds 3 columns of ++indentation to each of the lines beginning in the region specified. ++ ++In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses ++@code{indent-rigidly} to indent the text copied from the message being ++replied to. ++@end deffn ++ ++@deffn Command indent-code-rigidly start end columns &optional nochange-regexp ++This is like @code{indent-rigidly}, except that it doesn't alter lines ++that start within strings or comments. ++ ++In addition, it doesn't alter a line if @var{nochange-regexp} matches at ++the beginning of the line (if @var{nochange-regexp} is non-@code{nil}). ++@end deffn ++ ++@node Relative Indent ++@subsection Indentation Relative to Previous Lines ++ ++ This section describes two commands that indent the current line ++based on the contents of previous lines. ++ ++@deffn Command indent-relative &optional unindented-ok ++This command inserts whitespace at point, extending to the same ++column as the next @dfn{indent point} of the previous nonblank line. An ++indent point is a non-whitespace character following whitespace. The ++next indent point is the first one at a column greater than the current ++column of point. For example, if point is underneath and to the left of ++the first non-blank character of a line of text, it moves to that column ++by inserting whitespace. ++ ++If the previous nonblank line has no next indent point (i.e., none at a ++great enough column position), @code{indent-relative} either does ++nothing (if @var{unindented-ok} is non-@code{nil}) or calls ++@code{tab-to-tab-stop}. Thus, if point is underneath and to the right ++of the last column of a short line of text, this command ordinarily ++moves point to the next tab stop by inserting whitespace. ++ ++The return value of @code{indent-relative} is unpredictable. ++ ++In the following example, point is at the beginning of the second ++line: ++ ++@example ++@group ++ This line is indented twelve spaces. ++@point{}The quick brown fox jumped. ++@end group ++@end example ++ ++@noindent ++Evaluation of the expression @code{(indent-relative nil)} produces the ++following: ++ ++@example ++@group ++ This line is indented twelve spaces. ++ @point{}The quick brown fox jumped. ++@end group ++@end example ++ ++ In this next example, point is between the @samp{m} and @samp{p} of ++@samp{jumped}: ++ ++@example ++@group ++ This line is indented twelve spaces. ++The quick brown fox jum@point{}ped. ++@end group ++@end example ++ ++@noindent ++Evaluation of the expression @code{(indent-relative nil)} produces the ++following: ++ ++@example ++@group ++ This line is indented twelve spaces. ++The quick brown fox jum @point{}ped. ++@end group ++@end example ++@end deffn ++ ++@deffn Command indent-relative-maybe ++@comment !!SourceFile indent.el ++This command indents the current line like the previous nonblank line, ++by calling @code{indent-relative} with @code{t} as the ++@var{unindented-ok} argument. The return value is unpredictable. ++ ++If the previous nonblank line has no indent points beyond the current ++column, this command does nothing. ++@end deffn ++ ++@node Indent Tabs ++@comment node-name, next, previous, up ++@subsection Adjustable ``Tab Stops'' ++@cindex tabs stops for indentation ++ ++ This section explains the mechanism for user-specified ``tab stops'' ++and the mechanisms that use and set them. The name ``tab stops'' is ++used because the feature is similar to that of the tab stops on a ++typewriter. The feature works by inserting an appropriate number of ++spaces and tab characters to reach the next tab stop column; it does not ++affect the display of tab characters in the buffer (@pxref{Usual ++Display}). Note that the @key{TAB} character as input uses this tab ++stop feature only in a few major modes, such as Text mode. ++@xref{Tab Stops,,, emacs, The GNU Emacs Manual}. ++ ++@deffn Command tab-to-tab-stop ++This command inserts spaces or tabs before point, up to the next tab ++stop column defined by @code{tab-stop-list}. It searches the list for ++an element greater than the current column number, and uses that element ++as the column to indent to. It does nothing if no such element is ++found. ++@end deffn ++ ++@defopt tab-stop-list ++This variable is the list of tab stop columns used by ++@code{tab-to-tab-stops}. The elements should be integers in increasing ++order. The tab stop columns need not be evenly spaced. ++ ++Use @kbd{M-x edit-tab-stops} to edit the location of tab stops ++interactively. ++@end defopt ++ ++@node Motion by Indent ++@subsection Indentation-Based Motion Commands ++ ++ These commands, primarily for interactive use, act based on the ++indentation in the text. ++ ++@deffn Command back-to-indentation ++@comment !!SourceFile simple.el ++This command moves point to the first non-whitespace character in the ++current line (which is the line in which point is located). It returns ++@code{nil}. ++@end deffn ++ ++@deffn Command backward-to-indentation &optional arg ++@comment !!SourceFile simple.el ++This command moves point backward @var{arg} lines and then to the ++first nonblank character on that line. It returns @code{nil}. ++If @var{arg} is omitted or @code{nil}, it defaults to 1. ++@end deffn ++ ++@deffn Command forward-to-indentation &optional arg ++@comment !!SourceFile simple.el ++This command moves point forward @var{arg} lines and then to the first ++nonblank character on that line. It returns @code{nil}. ++If @var{arg} is omitted or @code{nil}, it defaults to 1. ++@end deffn ++ ++@node Case Changes ++@comment node-name, next, previous, up ++@section Case Changes ++@cindex case conversion in buffers ++ ++ The case change commands described here work on text in the current ++buffer. @xref{Case Conversion}, for case conversion functions that work ++on strings and characters. @xref{Case Tables}, for how to customize ++which characters are upper or lower case and how to convert them. ++ ++@deffn Command capitalize-region start end ++This function capitalizes all words in the region defined by ++@var{start} and @var{end}. To capitalize means to convert each word's ++first character to upper case and convert the rest of each word to lower ++case. The function returns @code{nil}. ++ ++If one end of the region is in the middle of a word, the part of the ++word within the region is treated as an entire word. ++ ++When @code{capitalize-region} is called interactively, @var{start} and ++@var{end} are point and the mark, with the smallest first. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++This is the contents of the 5th foo. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(capitalize-region 1 44) ++@result{} nil ++ ++---------- Buffer: foo ---------- ++This Is The Contents Of The 5th Foo. ++---------- Buffer: foo ---------- ++@end group ++@end example ++@end deffn ++ ++@deffn Command downcase-region start end ++This function converts all of the letters in the region defined by ++@var{start} and @var{end} to lower case. The function returns ++@code{nil}. ++ ++When @code{downcase-region} is called interactively, @var{start} and ++@var{end} are point and the mark, with the smallest first. ++@end deffn ++ ++@deffn Command upcase-region start end ++This function converts all of the letters in the region defined by ++@var{start} and @var{end} to upper case. The function returns ++@code{nil}. ++ ++When @code{upcase-region} is called interactively, @var{start} and ++@var{end} are point and the mark, with the smallest first. ++@end deffn ++ ++@deffn Command capitalize-word count ++This function capitalizes @var{count} words after point, moving point ++over as it does. To capitalize means to convert each word's first ++character to upper case and convert the rest of each word to lower case. ++If @var{count} is negative, the function capitalizes the ++@minus{}@var{count} previous words but does not move point. The value ++is @code{nil}. ++ ++If point is in the middle of a word, the part of the word before point ++is ignored when moving forward. The rest is treated as an entire word. ++ ++When @code{capitalize-word} is called interactively, @var{count} is ++set to the numeric prefix argument. ++@end deffn ++ ++@deffn Command downcase-word count ++This function converts the @var{count} words after point to all lower ++case, moving point over as it does. If @var{count} is negative, it ++converts the @minus{}@var{count} previous words but does not move point. ++The value is @code{nil}. ++ ++When @code{downcase-word} is called interactively, @var{count} is set ++to the numeric prefix argument. ++@end deffn ++ ++@deffn Command upcase-word count ++This function converts the @var{count} words after point to all upper ++case, moving point over as it does. If @var{count} is negative, it ++converts the @minus{}@var{count} previous words but does not move point. ++The value is @code{nil}. ++ ++When @code{upcase-word} is called interactively, @var{count} is set to ++the numeric prefix argument. ++@end deffn ++ ++@node Text Properties ++@section Text Properties ++@cindex text properties ++@cindex attributes of text ++@cindex properties of text ++ ++ Each character position in a buffer or a string can have a @dfn{text ++property list}, much like the property list of a symbol (@pxref{Property ++Lists}). The properties belong to a particular character at a ++particular place, such as, the letter @samp{T} at the beginning of this ++sentence or the first @samp{o} in @samp{foo}---if the same character ++occurs in two different places, the two occurrences in general have ++different properties. ++ ++ Each property has a name and a value. Both of these can be any Lisp ++object, but the name is normally a symbol. Typically each property ++name symbol is used for a particular purpose; for instance, the text ++property @code{face} specifies the faces for displaying the character ++(@pxref{Special Properties}). The usual way to access the property ++list is to specify a name and ask what value corresponds to it. ++ ++ If a character has a @code{category} property, we call it the ++@dfn{property category} of the character. It should be a symbol. The ++properties of the symbol serve as defaults for the properties of the ++character. ++ ++ Copying text between strings and buffers preserves the properties ++along with the characters; this includes such diverse functions as ++@code{substring}, @code{insert}, and @code{buffer-substring}. ++ ++@menu ++* Examining Properties:: Looking at the properties of one character. ++* Changing Properties:: Setting the properties of a range of text. ++* Property Search:: Searching for where a property changes value. ++* Special Properties:: Particular properties with special meanings. ++* Format Properties:: Properties for representing formatting of text. ++* Sticky Properties:: How inserted text gets properties from ++ neighboring text. ++* Lazy Properties:: Computing text properties in a lazy fashion ++ only when text is examined. ++* Clickable Text:: Using text properties to make regions of text ++ do something when you click on them. ++* Fields:: The @code{field} property defines ++ fields within the buffer. ++* Not Intervals:: Why text properties do not use ++ Lisp-visible text intervals. ++@end menu ++ ++@node Examining Properties ++@subsection Examining Text Properties ++ ++ The simplest way to examine text properties is to ask for the value of ++a particular property of a particular character. For that, use ++@code{get-text-property}. Use @code{text-properties-at} to get the ++entire property list of a character. @xref{Property Search}, for ++functions to examine the properties of a number of characters at once. ++ ++ These functions handle both strings and buffers. Keep in mind that ++positions in a string start from 0, whereas positions in a buffer start ++from 1. ++ ++@defun get-text-property pos prop &optional object ++This function returns the value of the @var{prop} property of the ++character after position @var{pos} in @var{object} (a buffer or ++string). The argument @var{object} is optional and defaults to the ++current buffer. ++ ++If there is no @var{prop} property strictly speaking, but the character ++has a property category that is a symbol, then @code{get-text-property} returns ++the @var{prop} property of that symbol. ++@end defun ++ ++@defun get-char-property position prop &optional object ++This function is like @code{get-text-property}, except that it checks ++overlays first and then text properties. @xref{Overlays}. ++ ++The argument @var{object} may be a string, a buffer, or a window. If ++it is a window, then the buffer displayed in that window is used for ++text properties and overlays, but only the overlays active for that ++window are considered. If @var{object} is a buffer, then overlays in ++that buffer are considered first, in order of decreasing priority, ++followed by the text properties. If @var{object} is a string, only ++text properties are considered, since strings never have overlays. ++@end defun ++ ++@defun get-char-property-and-overlay position prop &optional object ++This is like @code{get-char-property}, but gives extra information ++about the overlay that the property value comes from. ++ ++Its value is a cons cell whose @sc{car} is the property value, the ++same value @code{get-char-property} would return with the same ++arguments. Its @sc{cdr} is the overlay in which the property was ++found, or @code{nil}, if it was found as a text property or not found ++at all. ++ ++If @var{position} is at the end of @var{object}, both the @sc{car} and ++the @sc{cdr} of the value are @code{nil}. ++@end defun ++ ++@defvar char-property-alias-alist ++This variable holds an alist which maps property names to a list of ++alternative property names. If a character does not specify a direct ++value for a property, the alternative property names are consulted in ++order; the first non-@code{nil} value is used. This variable takes ++precedence over @code{default-text-properties}, and @code{category} ++properties take precedence over this variable. ++@end defvar ++ ++@defun text-properties-at position &optional object ++This function returns the entire property list of the character at ++@var{position} in the string or buffer @var{object}. If @var{object} is ++@code{nil}, it defaults to the current buffer. ++@end defun ++ ++@defvar default-text-properties ++This variable holds a property list giving default values for text ++properties. Whenever a character does not specify a value for a ++property, neither directly, through a category symbol, or through ++@code{char-property-alias-alist}, the value stored in this list is ++used instead. Here is an example: ++ ++@example ++(setq default-text-properties '(foo 69) ++ char-property-alias-alist nil) ++;; @r{Make sure character 1 has no properties of its own.} ++(set-text-properties 1 2 nil) ++;; @r{What we get, when we ask, is the default value.} ++(get-text-property 1 'foo) ++ @result{} 69 ++@end example ++@end defvar ++ ++@node Changing Properties ++@subsection Changing Text Properties ++ ++ The primitives for changing properties apply to a specified range of ++text in a buffer or string. The function @code{set-text-properties} ++(see end of section) sets the entire property list of the text in that ++range; more often, it is useful to add, change, or delete just certain ++properties specified by name. ++ ++ Since text properties are considered part of the contents of the ++buffer (or string), and can affect how a buffer looks on the screen, ++any change in buffer text properties marks the buffer as modified. ++Buffer text property changes are undoable also (@pxref{Undo}). ++Positions in a string start from 0, whereas positions in a buffer ++start from 1. ++ ++@defun put-text-property start end prop value &optional object ++This function sets the @var{prop} property to @var{value} for the text ++between @var{start} and @var{end} in the string or buffer @var{object}. ++If @var{object} is @code{nil}, it defaults to the current buffer. ++@end defun ++ ++@defun add-text-properties start end props &optional object ++This function adds or overrides text properties for the text between ++@var{start} and @var{end} in the string or buffer @var{object}. If ++@var{object} is @code{nil}, it defaults to the current buffer. ++ ++The argument @var{props} specifies which properties to add. It should ++have the form of a property list (@pxref{Property Lists}): a list whose ++elements include the property names followed alternately by the ++corresponding values. ++ ++The return value is @code{t} if the function actually changed some ++property's value; @code{nil} otherwise (if @var{props} is @code{nil} or ++its values agree with those in the text). ++ ++For example, here is how to set the @code{comment} and @code{face} ++properties of a range of text: ++ ++@example ++(add-text-properties @var{start} @var{end} ++ '(comment t face highlight)) ++@end example ++@end defun ++ ++@defun remove-text-properties start end props &optional object ++This function deletes specified text properties from the text between ++@var{start} and @var{end} in the string or buffer @var{object}. If ++@var{object} is @code{nil}, it defaults to the current buffer. ++ ++The argument @var{props} specifies which properties to delete. It ++should have the form of a property list (@pxref{Property Lists}): a list ++whose elements are property names alternating with corresponding values. ++But only the names matter---the values that accompany them are ignored. ++For example, here's how to remove the @code{face} property. ++ ++@example ++(remove-text-properties @var{start} @var{end} '(face nil)) ++@end example ++ ++The return value is @code{t} if the function actually changed some ++property's value; @code{nil} otherwise (if @var{props} is @code{nil} or ++if no character in the specified text had any of those properties). ++ ++To remove all text properties from certain text, use ++@code{set-text-properties} and specify @code{nil} for the new property ++list. ++@end defun ++ ++@defun remove-list-of-text-properties start end list-of-properties &optional object ++Like @code{remove-text-properties} except that ++@var{list-of-properties} is a list of property names only, not an ++alternating list of property names and values. ++@end defun ++ ++@defun set-text-properties start end props &optional object ++This function completely replaces the text property list for the text ++between @var{start} and @var{end} in the string or buffer @var{object}. ++If @var{object} is @code{nil}, it defaults to the current buffer. ++ ++The argument @var{props} is the new property list. It should be a list ++whose elements are property names alternating with corresponding values. ++ ++After @code{set-text-properties} returns, all the characters in the ++specified range have identical properties. ++ ++If @var{props} is @code{nil}, the effect is to get rid of all properties ++from the specified range of text. Here's an example: ++ ++@example ++(set-text-properties @var{start} @var{end} nil) ++@end example ++ ++Do not rely on the return value of this function. ++@end defun ++ ++ The easiest way to make a string with text properties ++is with @code{propertize}: ++ ++@defun propertize string &rest properties ++This function returns a copy of @var{string} which has the text ++properties @var{properties}. These properties apply to all the ++characters in the string that is returned. Here is an example that ++constructs a string with a @code{face} property and a @code{mouse-face} ++property: ++ ++@smallexample ++(propertize "foo" 'face 'italic ++ 'mouse-face 'bold-italic) ++ @result{} #("foo" 0 3 (mouse-face bold-italic face italic)) ++@end smallexample ++ ++To put different properties on various parts of a string, you can ++construct each part with @code{propertize} and then combine them with ++@code{concat}: ++ ++@smallexample ++(concat ++ (propertize "foo" 'face 'italic ++ 'mouse-face 'bold-italic) ++ " and " ++ (propertize "bar" 'face 'italic ++ 'mouse-face 'bold-italic)) ++ @result{} #("foo and bar" ++ 0 3 (face italic mouse-face bold-italic) ++ 3 8 nil ++ 8 11 (face italic mouse-face bold-italic)) ++@end smallexample ++@end defun ++ ++ See also the function @code{buffer-substring-no-properties} ++(@pxref{Buffer Contents}) which copies text from the buffer ++but does not copy its properties. ++ ++@node Property Search ++@subsection Text Property Search Functions ++ ++ In typical use of text properties, most of the time several or many ++consecutive characters have the same value for a property. Rather than ++writing your programs to examine characters one by one, it is much ++faster to process chunks of text that have the same property value. ++ ++ Here are functions you can use to do this. They use @code{eq} for ++comparing property values. In all cases, @var{object} defaults to the ++current buffer. ++ ++ For high performance, it's very important to use the @var{limit} ++argument to these functions, especially the ones that search for a ++single property---otherwise, they may spend a long time scanning to the ++end of the buffer, if the property you are interested in does not change. ++ ++ These functions do not move point; instead, they return a position (or ++@code{nil}). Remember that a position is always between two characters; ++the position returned by these functions is between two characters with ++different properties. ++ ++@defun next-property-change pos &optional object limit ++The function scans the text forward from position @var{pos} in the ++string or buffer @var{object} till it finds a change in some text ++property, then returns the position of the change. In other words, it ++returns the position of the first character beyond @var{pos} whose ++properties are not identical to those of the character just after ++@var{pos}. ++ ++If @var{limit} is non-@code{nil}, then the scan ends at position ++@var{limit}. If there is no property change before that point, ++@code{next-property-change} returns @var{limit}. ++ ++The value is @code{nil} if the properties remain unchanged all the way ++to the end of @var{object} and @var{limit} is @code{nil}. If the value ++is non-@code{nil}, it is a position greater than or equal to @var{pos}. ++The value equals @var{pos} only when @var{limit} equals @var{pos}. ++ ++Here is an example of how to scan the buffer by chunks of text within ++which all properties are constant: ++ ++@smallexample ++(while (not (eobp)) ++ (let ((plist (text-properties-at (point))) ++ (next-change ++ (or (next-property-change (point) (current-buffer)) ++ (point-max)))) ++ @r{Process text from point to @var{next-change}@dots{}} ++ (goto-char next-change))) ++@end smallexample ++@end defun ++ ++@defun previous-property-change pos &optional object limit ++This is like @code{next-property-change}, but scans back from @var{pos} ++instead of forward. If the value is non-@code{nil}, it is a position ++less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} ++equals @var{pos}. ++@end defun ++ ++@defun next-single-property-change pos prop &optional object limit ++The function scans text for a change in the @var{prop} property, then ++returns the position of the change. The scan goes forward from ++position @var{pos} in the string or buffer @var{object}. In other ++words, this function returns the position of the first character ++beyond @var{pos} whose @var{prop} property differs from that of the ++character just after @var{pos}. ++ ++If @var{limit} is non-@code{nil}, then the scan ends at position ++@var{limit}. If there is no property change before that point, ++@code{next-single-property-change} returns @var{limit}. ++ ++The value is @code{nil} if the property remains unchanged all the way to ++the end of @var{object} and @var{limit} is @code{nil}. If the value is ++non-@code{nil}, it is a position greater than or equal to @var{pos}; it ++equals @var{pos} only if @var{limit} equals @var{pos}. ++@end defun ++ ++@defun previous-single-property-change pos prop &optional object limit ++This is like @code{next-single-property-change}, but scans back from ++@var{pos} instead of forward. If the value is non-@code{nil}, it is a ++position less than or equal to @var{pos}; it equals @var{pos} only if ++@var{limit} equals @var{pos}. ++@end defun ++ ++@defun next-char-property-change pos &optional limit ++This is like @code{next-property-change} except that it considers ++overlay properties as well as text properties, and if no change is ++found before the end of the buffer, it returns the maximum buffer ++position rather than @code{nil} (in this sense, it resembles the ++corresponding overlay function @code{next-overlay-change}, rather than ++@code{next-property-change}). There is no @var{object} operand ++because this function operates only on the current buffer. It returns ++the next address at which either kind of property changes. ++@end defun ++ ++@defun previous-char-property-change pos &optional limit ++This is like @code{next-char-property-change}, but scans back from ++@var{pos} instead of forward, and returns the minimum buffer ++position if no change is found. ++@end defun ++ ++@defun next-single-char-property-change pos prop &optional object limit ++This is like @code{next-single-property-change} except that it ++considers overlay properties as well as text properties, and if no ++change is found before the end of the @var{object}, it returns the ++maximum valid position in @var{object} rather than @code{nil}. Unlike ++@code{next-char-property-change}, this function @emph{does} have an ++@var{object} operand; if @var{object} is not a buffer, only ++text-properties are considered. ++@end defun ++ ++@defun previous-single-char-property-change pos prop &optional object limit ++This is like @code{next-single-char-property-change}, but scans back ++from @var{pos} instead of forward, and returns the minimum valid ++position in @var{object} if no change is found. ++@end defun ++ ++@defun text-property-any start end prop value &optional object ++This function returns non-@code{nil} if at least one character between ++@var{start} and @var{end} has a property @var{prop} whose value is ++@var{value}. More precisely, it returns the position of the first such ++character. Otherwise, it returns @code{nil}. ++ ++The optional fifth argument, @var{object}, specifies the string or ++buffer to scan. Positions are relative to @var{object}. The default ++for @var{object} is the current buffer. ++@end defun ++ ++@defun text-property-not-all start end prop value &optional object ++This function returns non-@code{nil} if at least one character between ++@var{start} and @var{end} does not have a property @var{prop} with value ++@var{value}. More precisely, it returns the position of the first such ++character. Otherwise, it returns @code{nil}. ++ ++The optional fifth argument, @var{object}, specifies the string or ++buffer to scan. Positions are relative to @var{object}. The default ++for @var{object} is the current buffer. ++@end defun ++ ++@node Special Properties ++@subsection Properties with Special Meanings ++ ++ Here is a table of text property names that have special built-in ++meanings. The following sections list a few additional special property ++names that control filling and property inheritance. All other names ++have no standard meaning, and you can use them as you like. ++ ++ Note: the properties @code{composition}, @code{display}, ++@code{invisible} and @code{intangible} can also cause point to move to ++an acceptable place, after each Emacs command. @xref{Adjusting ++Point}. ++ ++@table @code ++@cindex property category of text character ++@kindex category @r{(text property)} ++@item category ++If a character has a @code{category} property, we call it the ++@dfn{property category} of the character. It should be a symbol. The ++properties of this symbol serve as defaults for the properties of the ++character. ++ ++@item face ++@cindex face codes of text ++@kindex face @r{(text property)} ++You can use the property @code{face} to control the font and color of ++text. @xref{Faces}, for more information. ++ ++In the simplest case, the value is a face name. It can also be a list; ++then each element can be any of these possibilities; ++ ++@itemize @bullet ++@item ++A face name (a symbol or string). ++ ++@item ++A property list of face attributes. This has the ++form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a ++face attribute name and @var{value} is a meaningful value for that ++attribute. With this feature, you do not need to create a face each ++time you want to specify a particular attribute for certain text. ++@xref{Face Attributes}. ++ ++@item ++A cons cell with the form @code{(foreground-color . @var{color-name})} ++or @code{(background-color . @var{color-name})}. These are old, ++deprecated equivalents for @code{(:foreground @var{color-name})} and ++@code{(:background @var{color-name})}. Please convert code that uses ++them. ++@end itemize ++ ++It works to use the latter two forms directly as the value ++of the @code{face} property. ++ ++Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by ++dynamically updating the @code{face} property of characters based on ++the context. ++ ++@item font-lock-face ++@kindex font-lock-face @r{(text property)} ++The @code{font-lock-face} property is equivalent to the @code{face} ++property when Font Lock mode is enabled. When Font Lock mode is disabled, ++@code{font-lock-face} has no effect. ++ ++The @code{font-lock-mode} property is useful for special modes that ++implement their own highlighting. @xref{Precalculated Fontification}. ++ ++@item mouse-face ++@kindex mouse-face @r{(text property)} ++The property @code{mouse-face} is used instead of @code{face} when the ++mouse is on or near the character. For this purpose, ``near'' means ++that all text between the character and where the mouse is have the same ++@code{mouse-face} property value. ++ ++@item fontified ++@kindex fontified @r{(text property)} ++This property says whether the text is ready for display. If ++@code{nil}, Emacs's redisplay routine calls the functions in ++@code{fontification-functions} (@pxref{Auto Faces}) to prepare this ++part of the buffer before it is displayed. It is used internally by ++the ``just in time'' font locking code. ++ ++@item display ++This property activates various features that change the ++way text is displayed. For example, it can make text appear taller ++or shorter, higher or lower, wider or narrow, or replaced with an image. ++@xref{Display Property}. ++ ++@item help-echo ++@kindex help-echo @r{(text property)} ++@cindex tooltip ++@anchor{Text help-echo} ++If text has a string as its @code{help-echo} property, then when you ++move the mouse onto that text, Emacs displays that string in the echo ++area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs ++Manual}). ++ ++If the value of the @code{help-echo} property is a function, that ++function is called with three arguments, @var{window}, @var{object} and ++@var{pos} and should return a help string or @code{nil} for ++none. The first argument, @var{window} is the window in which ++the help was found. The second, @var{object}, is the buffer, overlay or ++string which had the @code{help-echo} property. The @var{pos} ++argument is as follows: ++ ++@itemize @bullet{} ++@item ++If @var{object} is a buffer, @var{pos} is the position in the buffer. ++@item ++If @var{object} is an overlay, that overlay has a @code{help-echo} ++property, and @var{pos} is the position in the overlay's buffer. ++@item ++If @var{object} is a string (an overlay string or a string displayed ++with the @code{display} property), @var{pos} is the position in that ++string. ++@end itemize ++ ++If the value of the @code{help-echo} property is neither a function nor ++a string, it is evaluated to obtain a help string. ++ ++You can alter the way help text is displayed by setting the variable ++@code{show-help-function} (@pxref{Help display}). ++ ++This feature is used in the mode line and for other active text. ++ ++@item keymap ++@cindex keymap of character ++@kindex keymap @r{(text property)} ++The @code{keymap} property specifies an additional keymap for ++commands. When this keymap applies, it is used for key lookup before ++the minor mode keymaps and before the buffer's local map. ++@xref{Active Keymaps}. If the property value is a symbol, the ++symbol's function definition is used as the keymap. ++ ++The property's value for the character before point applies if it is ++non-@code{nil} and rear-sticky, and the property's value for the ++character after point applies if it is non-@code{nil} and ++front-sticky. (For mouse clicks, the position of the click is used ++instead of the position of point.) ++ ++@item local-map ++@kindex local-map @r{(text property)} ++This property works like @code{keymap} except that it specifies a ++keymap to use @emph{instead of} the buffer's local map. For most ++purposes (perhaps all purposes), it is better to use the @code{keymap} ++property. ++ ++@item syntax-table ++The @code{syntax-table} property overrides what the syntax table says ++about this particular character. @xref{Syntax Properties}. ++ ++@item read-only ++@cindex read-only character ++@kindex read-only @r{(text property)} ++If a character has the property @code{read-only}, then modifying that ++character is not allowed. Any command that would do so gets an error, ++@code{text-read-only}. If the property value is a string, that string ++is used as the error message. ++ ++Insertion next to a read-only character is an error if inserting ++ordinary text there would inherit the @code{read-only} property due to ++stickiness. Thus, you can control permission to insert next to ++read-only text by controlling the stickiness. @xref{Sticky Properties}. ++ ++Since changing properties counts as modifying the buffer, it is not ++possible to remove a @code{read-only} property unless you know the ++special trick: bind @code{inhibit-read-only} to a non-@code{nil} value ++and then remove the property. @xref{Read Only Buffers}. ++ ++@item invisible ++@kindex invisible @r{(text property)} ++A non-@code{nil} @code{invisible} property can make a character invisible ++on the screen. @xref{Invisible Text}, for details. ++ ++@item intangible ++@kindex intangible @r{(text property)} ++If a group of consecutive characters have equal and non-@code{nil} ++@code{intangible} properties, then you cannot place point between them. ++If you try to move point forward into the group, point actually moves to ++the end of the group. If you try to move point backward into the group, ++point actually moves to the start of the group. ++ ++If consecutive characters have unequal non-@code{nil} ++@code{intangible} properties, they belong to separate groups; each ++group is separately treated as described above. ++ ++When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, ++the @code{intangible} property is ignored. ++ ++@item field ++@kindex field @r{(text property)} ++Consecutive characters with the same @code{field} property constitute a ++@dfn{field}. Some motion functions including @code{forward-word} and ++@code{beginning-of-line} stop moving at a field boundary. ++@xref{Fields}. ++ ++@item cursor ++@kindex cursor @r{(text property)} ++Normally, the cursor is displayed at the end of any overlay and text ++property strings present at the current window position. You can ++place the cursor on any desired character of these strings by giving ++that character a non-@code{nil} @var{cursor} text property. ++ ++@item pointer ++@kindex pointer @r{(text property)} ++This specifies a specific pointer shape when the mouse pointer is over ++this text or image. @xref{Pointer Shape}, for possible pointer ++shapes. ++ ++@item line-spacing ++@kindex line-spacing @r{(text property)} ++A newline can have a @code{line-spacing} text or overlay property that ++controls the height of the display line ending with that newline. The ++property value overrides the default frame line spacing and the buffer ++local @code{line-spacing} variable. @xref{Line Height}. ++ ++@item line-height ++@kindex line-height @r{(text property)} ++A newline can have a @code{line-height} text or overlay property that ++controls the total height of the display line ending in that newline. ++@xref{Line Height}. ++ ++@item wrap-prefix ++If text has a @code{wrap-prefix} property, the prefix it defines will ++be added at display-time to the beginning of every continuation line ++due to text wrapping (so if lines are truncated, the wrap-prefix is ++never used). It may be a string, an image, or a stretch-glyph such as ++used by the @code{display} text-property. @xref{Display Property}. ++ ++A wrap-prefix may also be specified for an entire buffer using the ++@code{wrap-prefix} buffer-local variable (however, a ++@code{wrap-prefix} text-property takes precedence over the value of ++the @code{wrap-prefix} variable). @xref{Truncation}. ++ ++@item line-prefix ++If text has a @code{line-prefix} property, the prefix it defines will ++be added at display-time to the beginning of every non-continuation ++line. It may be a string, an image, or a stretch-glyph such as used ++by the @code{display} text-property. @xref{Display Property}. ++ ++A line-prefix may also be specified for an entire buffer using the ++@code{line-prefix} buffer-local variable (however, a ++@code{line-prefix} text-property takes precedence over the value of ++the @code{line-prefix} variable). @xref{Truncation}. ++ ++@item modification-hooks ++@cindex change hooks for a character ++@cindex hooks for changing a character ++@kindex modification-hooks @r{(text property)} ++If a character has the property @code{modification-hooks}, then its ++value should be a list of functions; modifying that character calls all ++of those functions. Each function receives two arguments: the beginning ++and end of the part of the buffer being modified. Note that if a ++particular modification hook function appears on several characters ++being modified by a single primitive, you can't predict how many times ++the function will be called. ++ ++If these functions modify the buffer, they should bind ++@code{inhibit-modification-hooks} to @code{t} around doing so, to ++avoid confusing the internal mechanism that calls these hooks. ++ ++Overlays also support the @code{modification-hooks} property, but the ++details are somewhat different (@pxref{Overlay Properties}). ++ ++@item insert-in-front-hooks ++@itemx insert-behind-hooks ++@kindex insert-in-front-hooks @r{(text property)} ++@kindex insert-behind-hooks @r{(text property)} ++The operation of inserting text in a buffer also calls the functions ++listed in the @code{insert-in-front-hooks} property of the following ++character and in the @code{insert-behind-hooks} property of the ++preceding character. These functions receive two arguments, the ++beginning and end of the inserted text. The functions are called ++@emph{after} the actual insertion takes place. ++ ++See also @ref{Change Hooks}, for other hooks that are called ++when you change text in a buffer. ++ ++@item point-entered ++@itemx point-left ++@cindex hooks for motion of point ++@kindex point-entered @r{(text property)} ++@kindex point-left @r{(text property)} ++The special properties @code{point-entered} and @code{point-left} ++record hook functions that report motion of point. Each time point ++moves, Emacs compares these two property values: ++ ++@itemize @bullet ++@item ++the @code{point-left} property of the character after the old location, ++and ++@item ++the @code{point-entered} property of the character after the new ++location. ++@end itemize ++ ++@noindent ++If these two values differ, each of them is called (if not @code{nil}) ++with two arguments: the old value of point, and the new one. ++ ++The same comparison is made for the characters before the old and new ++locations. The result may be to execute two @code{point-left} functions ++(which may be the same function) and/or two @code{point-entered} ++functions (which may be the same function). In any case, all the ++@code{point-left} functions are called first, followed by all the ++@code{point-entered} functions. ++ ++It is possible with @code{char-after} to examine characters at various ++buffer positions without moving point to those positions. Only an ++actual change in the value of point runs these hook functions. ++ ++@defvar inhibit-point-motion-hooks ++When this variable is non-@code{nil}, @code{point-left} and ++@code{point-entered} hooks are not run, and the @code{intangible} ++property has no effect. Do not set this variable globally; bind it with ++@code{let}. ++@end defvar ++ ++@defvar show-help-function ++@anchor{Help display} If this variable is non-@code{nil}, it specifies a ++function called to display help strings. These may be @code{help-echo} ++properties, menu help strings (@pxref{Simple Menu Items}, ++@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool ++Bar}). The specified function is called with one argument, the help ++string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs ++Manual}) provides an example. ++@end defvar ++ ++@item composition ++@kindex composition @r{(text property)} ++This text property is used to display a sequence of characters as a ++single glyph composed from components. But the value of the property ++itself is completely internal to Emacs and should not be manipulated ++directly by, for instance, @code{put-text-property}. ++ ++@end table ++ ++@node Format Properties ++@subsection Formatted Text Properties ++ ++ These text properties affect the behavior of the fill commands. They ++are used for representing formatted text. @xref{Filling}, and ++@ref{Margins}. ++ ++@table @code ++@item hard ++If a newline character has this property, it is a ``hard'' newline. ++The fill commands do not alter hard newlines and do not move words ++across them. However, this property takes effect only if the ++@code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft ++Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. ++ ++@item right-margin ++This property specifies an extra right margin for filling this part of the ++text. ++ ++@item left-margin ++This property specifies an extra left margin for filling this part of the ++text. ++ ++@item justification ++This property specifies the style of justification for filling this part ++of the text. ++@end table ++ ++@node Sticky Properties ++@subsection Stickiness of Text Properties ++@cindex sticky text properties ++@cindex inheritance of text properties ++ ++ Self-inserting characters normally take on the same properties as the ++preceding character. This is called @dfn{inheritance} of properties. ++ ++ In a Lisp program, you can do insertion with inheritance or without, ++depending on your choice of insertion primitive. The ordinary text ++insertion functions such as @code{insert} do not inherit any properties. ++They insert text with precisely the properties of the string being ++inserted, and no others. This is correct for programs that copy text ++from one context to another---for example, into or out of the kill ring. ++To insert with inheritance, use the special primitives described in this ++section. Self-inserting characters inherit properties because they work ++using these primitives. ++ ++ When you do insertion with inheritance, @emph{which} properties are ++inherited, and from where, depends on which properties are @dfn{sticky}. ++Insertion after a character inherits those of its properties that are ++@dfn{rear-sticky}. Insertion before a character inherits those of its ++properties that are @dfn{front-sticky}. When both sides offer different ++sticky values for the same property, the previous character's value ++takes precedence. ++ ++ By default, a text property is rear-sticky but not front-sticky; thus, ++the default is to inherit all the properties of the preceding character, ++and nothing from the following character. ++ ++ You can control the stickiness of various text properties with two ++specific text properties, @code{front-sticky} and @code{rear-nonsticky}, ++and with the variable @code{text-property-default-nonsticky}. You can ++use the variable to specify a different default for a given property. ++You can use those two text properties to make any specific properties ++sticky or nonsticky in any particular part of the text. ++ ++ If a character's @code{front-sticky} property is @code{t}, then all ++its properties are front-sticky. If the @code{front-sticky} property is ++a list, then the sticky properties of the character are those whose ++names are in the list. For example, if a character has a ++@code{front-sticky} property whose value is @code{(face read-only)}, ++then insertion before the character can inherit its @code{face} property ++and its @code{read-only} property, but no others. ++ ++ The @code{rear-nonsticky} property works the opposite way. Most ++properties are rear-sticky by default, so the @code{rear-nonsticky} ++property says which properties are @emph{not} rear-sticky. If a ++character's @code{rear-nonsticky} property is @code{t}, then none of its ++properties are rear-sticky. If the @code{rear-nonsticky} property is a ++list, properties are rear-sticky @emph{unless} their names are in the ++list. ++ ++@defvar text-property-default-nonsticky ++This variable holds an alist which defines the default rear-stickiness ++of various text properties. Each element has the form ++@code{(@var{property} . @var{nonstickiness})}, and it defines the ++stickiness of a particular text property, @var{property}. ++ ++If @var{nonstickiness} is non-@code{nil}, this means that the property ++@var{property} is rear-nonsticky by default. Since all properties are ++front-nonsticky by default, this makes @var{property} nonsticky in both ++directions by default. ++ ++The text properties @code{front-sticky} and @code{rear-nonsticky}, when ++used, take precedence over the default @var{nonstickiness} specified in ++@code{text-property-default-nonsticky}. ++@end defvar ++ ++ Here are the functions that insert text with inheritance of properties: ++ ++@defun insert-and-inherit &rest strings ++Insert the strings @var{strings}, just like the function @code{insert}, ++but inherit any sticky properties from the adjoining text. ++@end defun ++ ++@defun insert-before-markers-and-inherit &rest strings ++Insert the strings @var{strings}, just like the function ++@code{insert-before-markers}, but inherit any sticky properties from the ++adjoining text. ++@end defun ++ ++ @xref{Insertion}, for the ordinary insertion functions which do not ++inherit. ++ ++@node Lazy Properties ++@subsection Lazy Computation of Text Properties ++ ++ Instead of computing text properties for all the text in the buffer, ++you can arrange to compute the text properties for parts of the text ++when and if something depends on them. ++ ++ The primitive that extracts text from the buffer along with its ++properties is @code{buffer-substring}. Before examining the properties, ++this function runs the abnormal hook @code{buffer-access-fontify-functions}. ++ ++@defvar buffer-access-fontify-functions ++This variable holds a list of functions for computing text properties. ++Before @code{buffer-substring} copies the text and text properties for a ++portion of the buffer, it calls all the functions in this list. Each of ++the functions receives two arguments that specify the range of the ++buffer being accessed. (The buffer itself is always the current ++buffer.) ++@end defvar ++ ++ The function @code{buffer-substring-no-properties} does not call these ++functions, since it ignores text properties anyway. ++ ++ In order to prevent the hook functions from being called more than ++once for the same part of the buffer, you can use the variable ++@code{buffer-access-fontified-property}. ++ ++@defvar buffer-access-fontified-property ++If this variable's value is non-@code{nil}, it is a symbol which is used ++as a text property name. A non-@code{nil} value for that text property ++means, ``the other text properties for this character have already been ++computed.'' ++ ++If all the characters in the range specified for @code{buffer-substring} ++have a non-@code{nil} value for this property, @code{buffer-substring} ++does not call the @code{buffer-access-fontify-functions} functions. It ++assumes these characters already have the right text properties, and ++just copies the properties they already have. ++ ++The normal way to use this feature is that the ++@code{buffer-access-fontify-functions} functions add this property, as ++well as others, to the characters they operate on. That way, they avoid ++being called over and over for the same text. ++@end defvar ++ ++@node Clickable Text ++@subsection Defining Clickable Text ++@cindex clickable text ++@cindex follow links ++@cindex mouse-1 ++ ++ @dfn{Clickable text} is text that can be clicked, with either the ++mouse or via a keyboard command, to produce some result. Many major ++modes use clickable text to implement textual hyper-links, or ++@dfn{links} for short. ++ ++ The easiest way to insert and manipulate links is to use the ++@code{button} package. @xref{Buttons}. In this section, we will ++explain how to manually set up clickable text in a buffer, using text ++properties. For simplicity, we will refer to the clickable text as a ++@dfn{link}. ++ ++ Implementing a link involves three separate steps: (1) indicating ++clickability when the mouse moves over the link; (2) making @kbd{RET} ++or @kbd{Mouse-2} on that link do something; and (3) setting up a ++@code{follow-link} condition so that the link obeys ++@code{mouse-1-click-follows-link}. ++ ++ To indicate clickability, add the @code{mouse-face} text property to ++the text of the link; then Emacs will highlight the link when the ++mouse moves over it. In addition, you should define a tooltip or echo ++area message, using the @code{help-echo} text property. @xref{Special ++Properties}. For instance, here is how Dired indicates that file ++names are clickable: ++ ++@smallexample ++ (if (dired-move-to-filename) ++ (add-text-properties ++ (point) ++ (save-excursion ++ (dired-move-to-end-of-filename) ++ (point)) ++ '(mouse-face highlight ++ help-echo "mouse-2: visit this file in other window"))) ++@end smallexample ++ ++ To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to ++commands that perform the desired action. Each command should check ++to see whether it was called on a link, and act accordingly. For ++instance, Dired's major mode keymap binds @kbd{Mouse-2} to the ++following command: ++ ++@smallexample ++(defun dired-mouse-find-file-other-window (event) ++ "In Dired, visit the file or directory name you click on." ++ (interactive "e") ++ (let (window pos file) ++ (save-excursion ++ (setq window (posn-window (event-end event)) ++ pos (posn-point (event-end event))) ++ (if (not (windowp window)) ++ (error "No file chosen")) ++ (set-buffer (window-buffer window)) ++ (goto-char pos) ++ (setq file (dired-get-file-for-visit))) ++ (if (file-directory-p file) ++ (or (and (cdr dired-subdir-alist) ++ (dired-goto-subdir file)) ++ (progn ++ (select-window window) ++ (dired-other-window file))) ++ (select-window window) ++ (find-file-other-window (file-name-sans-versions file t))))) ++@end smallexample ++ ++@noindent ++This command uses the functions @code{posn-window} and ++@code{posn-point} to determine where the click occurred, and ++@code{dired-get-file-for-visit} to determine which file to visit. ++ ++ Instead of binding the mouse command in a major mode keymap, you can ++bind it within the link text, using the @code{keymap} text property ++(@pxref{Special Properties}). For instance: ++ ++@example ++(let ((map (make-sparse-keymap))) ++ (define-key map [mouse-2] 'operate-this-button) ++ (put-text-property link-start link-end 'keymap map)) ++@end example ++ ++@noindent ++With this method, you can easily define different commands for ++different links. Furthermore, the global definition of @key{RET} and ++@kbd{Mouse-2} remain available for the rest of the text in the buffer. ++ ++@vindex mouse-1-click-follows-link ++ The basic Emacs command for clicking on links is @kbd{Mouse-2}. ++However, for compatibility with other graphical applications, Emacs ++also recognizes @kbd{Mouse-1} clicks on links, provided the user ++clicks on the link quickly without moving the mouse. This behavior is ++controlled by the user option @code{mouse-1-click-follows-link}. ++@xref{Mouse References,,, emacs, The GNU Emacs Manual}. ++ ++ To set up the link so that it obeys ++@code{mouse-1-click-follows-link}, you must either (1) apply a ++@code{follow-link} text or overlay property to the link text, or (2) ++bind the @code{follow-link} event to a keymap (which can be a major ++mode keymap or a local keymap specified via the @code{keymap} text ++property). The value of the @code{follow-link} property, or the ++binding for the @code{follow-link} event, acts as a ``condition'' for ++the link action. This condition tells Emacs two things: the ++circumstances under which a @kbd{Mouse-1} click should be regarded as ++occurring ``inside'' the link, and how to compute an ``action code'' ++that says what to translate the @kbd{Mouse-1} click into. The link ++action condition can be one of the following: ++ ++@table @asis ++@item @code{mouse-face} ++If the condition is the symbol @code{mouse-face}, a position is inside ++a link if there is a non-@code{nil} @code{mouse-face} property at that ++position. The action code is always @code{t}. ++ ++For example, here is how Info mode handles @key{Mouse-1}: ++ ++@smallexample ++(define-key Info-mode-map [follow-link] 'mouse-face) ++@end smallexample ++ ++@item a function ++If the condition is a function, @var{func}, then a position @var{pos} ++is inside a link if @code{(@var{func} @var{pos})} evaluates to ++non-@code{nil}. The value returned by @var{func} serves as the action ++code. ++ ++For example, here is how pcvs enables @kbd{Mouse-1} to follow links on ++file names only: ++ ++@smallexample ++(define-key map [follow-link] ++ (lambda (pos) ++ (eq (get-char-property pos 'face) 'cvs-filename-face))) ++@end smallexample ++ ++@item anything else ++If the condition value is anything else, then the position is inside a ++link and the condition itself is the action code. Clearly, you should ++specify this kind of condition only when applying the condition via a ++text or property overlay on the link text (so that it does not apply ++to the entire buffer). ++@end table ++ ++@noindent ++The action code tells @kbd{Mouse-1} how to follow the link: ++ ++@table @asis ++@item a string or vector ++If the action code is a string or vector, the @kbd{Mouse-1} event is ++translated into the first element of the string or vector; i.e., the ++action of the @kbd{Mouse-1} click is the local or global binding of ++that character or symbol. Thus, if the action code is @code{"foo"}, ++@kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, ++@kbd{Mouse-1} translates into @key{foo}. ++ ++@item anything else ++For any other non-@code{nil} action code, the @kbd{Mouse-1} event is ++translated into a @kbd{Mouse-2} event at the same position. ++@end table ++ ++ To define @kbd{Mouse-1} to activate a button defined with ++@code{define-button-type}, give the button a @code{follow-link} ++property. The property value should be a link action condition, as ++described above. @xref{Buttons}. For example, here is how Help mode ++handles @kbd{Mouse-1}: ++ ++@smallexample ++(define-button-type 'help-xref ++ 'follow-link t ++ 'action #'help-button-action) ++@end smallexample ++ ++ To define @kbd{Mouse-1} on a widget defined with ++@code{define-widget}, give the widget a @code{:follow-link} property. ++The property value should be a link action condition, as described ++above. For example, here is how the @code{link} widget specifies that ++a @key{Mouse-1} click shall be translated to @key{RET}: ++ ++@smallexample ++(define-widget 'link 'item ++ "An embedded link." ++ :button-prefix 'widget-link-prefix ++ :button-suffix 'widget-link-suffix ++ :follow-link "\C-m" ++ :help-echo "Follow the link." ++ :format "%[%t%]") ++@end smallexample ++ ++@defun mouse-on-link-p pos ++This function returns non-@code{nil} if position @var{pos} in the ++current buffer is on a link. @var{pos} can also be a mouse event ++location, as returned by @code{event-start} (@pxref{Accessing Mouse}). ++@end defun ++ ++@node Fields ++@subsection Defining and Using Fields ++@cindex fields ++ ++ A field is a range of consecutive characters in the buffer that are ++identified by having the same value (comparing with @code{eq}) of the ++@code{field} property (either a text-property or an overlay property). ++This section describes special functions that are available for ++operating on fields. ++ ++ You specify a field with a buffer position, @var{pos}. We think of ++each field as containing a range of buffer positions, so the position ++you specify stands for the field containing that position. ++ ++ When the characters before and after @var{pos} are part of the same ++field, there is no doubt which field contains @var{pos}: the one those ++characters both belong to. When @var{pos} is at a boundary between ++fields, which field it belongs to depends on the stickiness of the ++@code{field} properties of the two surrounding characters (@pxref{Sticky ++Properties}). The field whose property would be inherited by text ++inserted at @var{pos} is the field that contains @var{pos}. ++ ++ There is an anomalous case where newly inserted text at @var{pos} ++would not inherit the @code{field} property from either side. This ++happens if the previous character's @code{field} property is not ++rear-sticky, and the following character's @code{field} property is not ++front-sticky. In this case, @var{pos} belongs to neither the preceding ++field nor the following field; the field functions treat it as belonging ++to an empty field whose beginning and end are both at @var{pos}. ++ ++ In all of these functions, if @var{pos} is omitted or @code{nil}, the ++value of point is used by default. If narrowing is in effect, then ++@var{pos} should fall within the accessible portion. @xref{Narrowing}. ++ ++@defun field-beginning &optional pos escape-from-edge limit ++This function returns the beginning of the field specified by @var{pos}. ++ ++If @var{pos} is at the beginning of its field, and ++@var{escape-from-edge} is non-@code{nil}, then the return value is ++always the beginning of the preceding field that @emph{ends} at @var{pos}, ++regardless of the stickiness of the @code{field} properties around ++@var{pos}. ++ ++If @var{limit} is non-@code{nil}, it is a buffer position; if the ++beginning of the field is before @var{limit}, then @var{limit} will be ++returned instead. ++@end defun ++ ++@defun field-end &optional pos escape-from-edge limit ++This function returns the end of the field specified by @var{pos}. ++ ++If @var{pos} is at the end of its field, and @var{escape-from-edge} is ++non-@code{nil}, then the return value is always the end of the following ++field that @emph{begins} at @var{pos}, regardless of the stickiness of ++the @code{field} properties around @var{pos}. ++ ++If @var{limit} is non-@code{nil}, it is a buffer position; if the end ++of the field is after @var{limit}, then @var{limit} will be returned ++instead. ++@end defun ++ ++@defun field-string &optional pos ++This function returns the contents of the field specified by @var{pos}, ++as a string. ++@end defun ++ ++@defun field-string-no-properties &optional pos ++This function returns the contents of the field specified by @var{pos}, ++as a string, discarding text properties. ++@end defun ++ ++@defun delete-field &optional pos ++This function deletes the text of the field specified by @var{pos}. ++@end defun ++ ++@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property ++This function ``constrains'' @var{new-pos} to the field that ++@var{old-pos} belongs to---in other words, it returns the position ++closest to @var{new-pos} that is in the same field as @var{old-pos}. ++ ++If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses ++the value of point instead, and moves point to the resulting position ++as well as returning it. ++ ++If @var{old-pos} is at the boundary of two fields, then the acceptable ++final positions depend on the argument @var{escape-from-edge}. If ++@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in ++the field whose @code{field} property equals what new characters ++inserted at @var{old-pos} would inherit. (This depends on the ++stickiness of the @code{field} property for the characters before and ++after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil}, ++@var{new-pos} can be anywhere in the two adjacent fields. ++Additionally, if two fields are separated by another field with the ++special value @code{boundary}, then any point within this special ++field is also considered to be ``on the boundary.'' ++ ++Commands like @kbd{C-a} with no argumemt, that normally move backward ++to a specific kind of location and stay there once there, probably ++should specify @code{nil} for @var{escape-from-edge}. Other motion ++commands that check fields should probably pass @code{t}. ++ ++If the optional argument @var{only-in-line} is non-@code{nil}, and ++constraining @var{new-pos} in the usual way would move it to a different ++line, @var{new-pos} is returned unconstrained. This used in commands ++that move by line, such as @code{next-line} and ++@code{beginning-of-line}, so that they respect field boundaries only in ++the case where they can still move to the right line. ++ ++If the optional argument @var{inhibit-capture-property} is ++non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that ++name, then any field boundaries are ignored. ++ ++You can cause @code{constrain-to-field} to ignore all field boundaries ++(and so never constrain anything) by binding the variable ++@code{inhibit-field-text-motion} to a non-@code{nil} value. ++@end defun ++ ++@node Not Intervals ++@subsection Why Text Properties are not Intervals ++@cindex intervals ++ ++ Some editors that support adding attributes to text in the buffer do ++so by letting the user specify ``intervals'' within the text, and adding ++the properties to the intervals. Those editors permit the user or the ++programmer to determine where individual intervals start and end. We ++deliberately provided a different sort of interface in Emacs Lisp to ++avoid certain paradoxical behavior associated with text modification. ++ ++ If the actual subdivision into intervals is meaningful, that means you ++can distinguish between a buffer that is just one interval with a ++certain property, and a buffer containing the same text subdivided into ++two intervals, both of which have that property. ++ ++ Suppose you take the buffer with just one interval and kill part of ++the text. The text remaining in the buffer is one interval, and the ++copy in the kill ring (and the undo list) becomes a separate interval. ++Then if you yank back the killed text, you get two intervals with the ++same properties. Thus, editing does not preserve the distinction ++between one interval and two. ++ ++ Suppose we ``fix'' this problem by coalescing the two intervals when ++the text is inserted. That works fine if the buffer originally was a ++single interval. But suppose instead that we have two adjacent ++intervals with the same properties, and we kill the text of one interval ++and yank it back. The same interval-coalescence feature that rescues ++the other case causes trouble in this one: after yanking, we have just ++one interval. One again, editing does not preserve the distinction ++between one interval and two. ++ ++ Insertion of text at the border between intervals also raises ++questions that have no satisfactory answer. ++ ++ However, it is easy to arrange for editing to behave consistently for ++questions of the form, ``What are the properties of this character?'' ++So we have decided these are the only questions that make sense; we have ++not implemented asking questions about where intervals start or end. ++ ++ In practice, you can usually use the text property search functions in ++place of explicit interval boundaries. You can think of them as finding ++the boundaries of intervals, assuming that intervals are always ++coalesced whenever possible. @xref{Property Search}. ++ ++ Emacs also provides explicit intervals as a presentation feature; see ++@ref{Overlays}. ++ ++@node Substitution ++@section Substituting for a Character Code ++ ++ The following functions replace characters within a specified region ++based on their character codes. ++ ++@defun subst-char-in-region start end old-char new-char &optional noundo ++@cindex replace characters ++This function replaces all occurrences of the character @var{old-char} ++with the character @var{new-char} in the region of the current buffer ++defined by @var{start} and @var{end}. ++ ++@cindex undo avoidance ++If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does ++not record the change for undo and does not mark the buffer as modified. ++This was useful for controlling the old selective display feature ++(@pxref{Selective Display}). ++ ++@code{subst-char-in-region} does not move point and returns ++@code{nil}. ++ ++@example ++@group ++---------- Buffer: foo ---------- ++This is the contents of the buffer before. ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(subst-char-in-region 1 20 ?i ?X) ++ @result{} nil ++ ++---------- Buffer: foo ---------- ++ThXs Xs the contents of the buffer before. ++---------- Buffer: foo ---------- ++@end group ++@end example ++@end defun ++ ++@deffn Command translate-region start end table ++This function applies a translation table to the characters in the ++buffer between positions @var{start} and @var{end}. ++ ++The translation table @var{table} is a string or a char-table; ++@code{(aref @var{table} @var{ochar})} gives the translated character ++corresponding to @var{ochar}. If @var{table} is a string, any ++characters with codes larger than the length of @var{table} are not ++altered by the translation. ++ ++The return value of @code{translate-region} is the number of ++characters that were actually changed by the translation. This does ++not count characters that were mapped into themselves in the ++translation table. ++@end deffn ++ ++@node Registers ++@section Registers ++@cindex registers ++ ++ A register is a sort of variable used in Emacs editing that can hold a ++variety of different kinds of values. Each register is named by a ++single character. All @acronym{ASCII} characters and their meta variants ++(but with the exception of @kbd{C-g}) can be used to name registers. ++Thus, there are 255 possible registers. A register is designated in ++Emacs Lisp by the character that is its name. ++ ++@defvar register-alist ++This variable is an alist of elements of the form @code{(@var{name} . ++@var{contents})}. Normally, there is one element for each Emacs ++register that has been used. ++ ++The object @var{name} is a character (an integer) identifying the ++register. ++@end defvar ++ ++ The @var{contents} of a register can have several possible types: ++ ++@table @asis ++@item a number ++A number stands for itself. If @code{insert-register} finds a number ++in the register, it converts the number to decimal. ++ ++@item a marker ++A marker represents a buffer position to jump to. ++ ++@item a string ++A string is text saved in the register. ++ ++@item a rectangle ++A rectangle is represented by a list of strings. ++ ++@item @code{(@var{window-configuration} @var{position})} ++This represents a window configuration to restore in one frame, and a ++position to jump to in the current buffer. ++ ++@item @code{(@var{frame-configuration} @var{position})} ++This represents a frame configuration to restore, and a position ++to jump to in the current buffer. ++ ++@item (file @var{filename}) ++This represents a file to visit; jumping to this value visits file ++@var{filename}. ++ ++@item (file-query @var{filename} @var{position}) ++This represents a file to visit and a position in it; jumping to this ++value visits file @var{filename} and goes to buffer position ++@var{position}. Restoring this type of position asks the user for ++confirmation first. ++@end table ++ ++ The functions in this section return unpredictable values unless ++otherwise stated. ++ ++@defun get-register reg ++This function returns the contents of the register ++@var{reg}, or @code{nil} if it has no contents. ++@end defun ++ ++@defun set-register reg value ++This function sets the contents of register @var{reg} to @var{value}. ++A register can be set to any value, but the other register functions ++expect only certain data types. The return value is @var{value}. ++@end defun ++ ++@deffn Command view-register reg ++This command displays what is contained in register @var{reg}. ++@end deffn ++ ++@deffn Command insert-register reg &optional beforep ++This command inserts contents of register @var{reg} into the current ++buffer. ++ ++Normally, this command puts point before the inserted text, and the ++mark after it. However, if the optional second argument @var{beforep} ++is non-@code{nil}, it puts the mark before and point after. ++You can pass a non-@code{nil} second argument @var{beforep} to this ++function interactively by supplying any prefix argument. ++ ++If the register contains a rectangle, then the rectangle is inserted ++with its upper left corner at point. This means that text is inserted ++in the current line and underneath it on successive lines. ++ ++If the register contains something other than saved text (a string) or ++a rectangle (a list), currently useless things happen. This may be ++changed in the future. ++@end deffn ++ ++@node Transposition ++@section Transposition of Text ++ ++ This subroutine is used by the transposition commands. ++ ++@defun transpose-regions start1 end1 start2 end2 &optional leave-markers ++This function exchanges two nonoverlapping portions of the buffer. ++Arguments @var{start1} and @var{end1} specify the bounds of one portion ++and arguments @var{start2} and @var{end2} specify the bounds of the ++other portion. ++ ++Normally, @code{transpose-regions} relocates markers with the transposed ++text; a marker previously positioned within one of the two transposed ++portions moves along with that portion, thus remaining between the same ++two characters in their new position. However, if @var{leave-markers} ++is non-@code{nil}, @code{transpose-regions} does not do this---it leaves ++all markers unrelocated. ++@end defun ++ ++@node Base 64 ++@section Base 64 Encoding ++@cindex base 64 encoding ++ ++ Base 64 code is used in email to encode a sequence of 8-bit bytes as ++a longer sequence of @acronym{ASCII} graphic characters. It is defined in ++Internet RFC@footnote{ ++An RFC, an acronym for @dfn{Request for Comments}, is a numbered ++Internet informational document describing a standard. RFCs are ++usually written by technical experts acting on their own initiative, ++and are traditionally written in a pragmatic, experience-driven ++manner. ++}2045. This section describes the functions for ++converting to and from this code. ++ ++@deffn Command base64-encode-region beg end &optional no-line-break ++This function converts the region from @var{beg} to @var{end} into base ++64 code. It returns the length of the encoded text. An error is ++signaled if a character in the region is multibyte, i.e.@: in a ++multibyte buffer the region must contain only characters from the ++charsets @code{ascii}, @code{eight-bit-control} and ++@code{eight-bit-graphic}. ++ ++Normally, this function inserts newline characters into the encoded ++text, to avoid overlong lines. However, if the optional argument ++@var{no-line-break} is non-@code{nil}, these newlines are not added, so ++the output is just one long line. ++@end deffn ++ ++@deffn Command base64-encode-string string &optional no-line-break ++This function converts the string @var{string} into base 64 code. It ++returns a string containing the encoded text. As for ++@code{base64-encode-region}, an error is signaled if a character in the ++string is multibyte. ++ ++Normally, this function inserts newline characters into the encoded ++text, to avoid overlong lines. However, if the optional argument ++@var{no-line-break} is non-@code{nil}, these newlines are not added, so ++the result string is just one long line. ++@end deffn ++ ++@defun base64-decode-region beg end ++This function converts the region from @var{beg} to @var{end} from base ++64 code into the corresponding decoded text. It returns the length of ++the decoded text. ++ ++The decoding functions ignore newline characters in the encoded text. ++@end defun ++ ++@defun base64-decode-string string ++This function converts the string @var{string} from base 64 code into ++the corresponding decoded text. It returns a unibyte string containing the ++decoded text. ++ ++The decoding functions ignore newline characters in the encoded text. ++@end defun ++ ++@node MD5 Checksum ++@section MD5 Checksum ++@cindex MD5 checksum ++@cindex message digest computation ++ ++ MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit ++``fingerprints'' of a document or program. They are used to verify ++that you have an exact and unaltered copy of the data. The algorithm ++to calculate the MD5 message digest is defined in Internet ++RFC@footnote{ ++For an explanation of what is an RFC, see the footnote in @ref{Base ++64}. ++}1321. This section describes the Emacs facilities for computing ++message digests. ++ ++@defun md5 object &optional start end coding-system noerror ++This function returns the MD5 message digest of @var{object}, which ++should be a buffer or a string. ++ ++The two optional arguments @var{start} and @var{end} are character ++positions specifying the portion of @var{object} to compute the ++message digest for. If they are @code{nil} or omitted, the digest is ++computed for the whole of @var{object}. ++ ++The function @code{md5} does not compute the message digest directly ++from the internal Emacs representation of the text (@pxref{Text ++Representations}). Instead, it encodes the text using a coding ++system, and computes the message digest from the encoded text. The ++optional fourth argument @var{coding-system} specifies which coding ++system to use for encoding the text. It should be the same coding ++system that you used to read the text, or that you used or will use ++when saving or sending the text. @xref{Coding Systems}, for more ++information about coding systems. ++ ++If @var{coding-system} is @code{nil} or omitted, the default depends ++on @var{object}. If @var{object} is a buffer, the default for ++@var{coding-system} is whatever coding system would be chosen by ++default for writing this text into a file. If @var{object} is a ++string, the user's most preferred coding system (@pxref{Recognize ++Coding, prefer-coding-system, the description of ++@code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used. ++ ++Normally, @code{md5} signals an error if the text can't be encoded ++using the specified or chosen coding system. However, if ++@var{noerror} is non-@code{nil}, it silently uses @code{raw-text} ++coding instead. ++@end defun ++ ++@node Atomic Changes ++@section Atomic Change Groups ++@cindex atomic changes ++ ++ In data base terminology, an @dfn{atomic} change is an indivisible ++change---it can succeed entirely or it can fail entirely, but it ++cannot partly succeed. A Lisp program can make a series of changes to ++one or several buffers as an @dfn{atomic change group}, meaning that ++either the entire series of changes will be installed in their buffers ++or, in case of an error, none of them will be. ++ ++ To do this for one buffer, the one already current, simply write a ++call to @code{atomic-change-group} around the code that makes the ++changes, like this: ++ ++@example ++(atomic-change-group ++ (insert foo) ++ (delete-region x y)) ++@end example ++ ++@noindent ++If an error (or other nonlocal exit) occurs inside the body of ++@code{atomic-change-group}, it unmakes all the changes in that buffer ++that were during the execution of the body. This kind of change group ++has no effect on any other buffers---any such changes remain. ++ ++ If you need something more sophisticated, such as to make changes in ++various buffers constitute one atomic group, you must directly call ++lower-level functions that @code{atomic-change-group} uses. ++ ++@defun prepare-change-group &optional buffer ++This function sets up a change group for buffer @var{buffer}, which ++defaults to the current buffer. It returns a ``handle'' that ++represents the change group. You must use this handle to activate the ++change group and subsequently to finish it. ++@end defun ++ ++ To use the change group, you must @dfn{activate} it. You must do ++this before making any changes in the text of @var{buffer}. ++ ++@defun activate-change-group handle ++This function activates the change group that @var{handle} designates. ++@end defun ++ ++ After you activate the change group, any changes you make in that ++buffer become part of it. Once you have made all the desired changes ++in the buffer, you must @dfn{finish} the change group. There are two ++ways to do this: you can either accept (and finalize) all the changes, ++or cancel them all. ++ ++@defun accept-change-group handle ++This function accepts all the changes in the change group specified by ++@var{handle}, making them final. ++@end defun ++ ++@defun cancel-change-group handle ++This function cancels and undoes all the changes in the change group ++specified by @var{handle}. ++@end defun ++ ++ Your code should use @code{unwind-protect} to make sure the group is ++always finished. The call to @code{activate-change-group} should be ++inside the @code{unwind-protect}, in case the user types @kbd{C-g} ++just after it runs. (This is one reason why ++@code{prepare-change-group} and @code{activate-change-group} are ++separate functions, because normally you would call ++@code{prepare-change-group} before the start of that ++@code{unwind-protect}.) Once you finish the group, don't use the ++handle again---in particular, don't try to finish the same group ++twice. ++ ++ To make a multibuffer change group, call @code{prepare-change-group} ++once for each buffer you want to cover, then use @code{nconc} to ++combine the returned values, like this: ++ ++@example ++(nconc (prepare-change-group buffer-1) ++ (prepare-change-group buffer-2)) ++@end example ++ ++You can then activate the multibuffer change group with a single call ++to @code{activate-change-group}, and finish it with a single call to ++@code{accept-change-group} or @code{cancel-change-group}. ++ ++ Nested use of several change groups for the same buffer works as you ++would expect. Non-nested use of change groups for the same buffer ++will get Emacs confused, so don't let it happen; the first change ++group you start for any given buffer should be the last one finished. ++ ++@node Change Hooks ++@section Change Hooks ++@cindex change hooks ++@cindex hooks for text changes ++ ++ These hook variables let you arrange to take notice of all changes in ++all buffers (or in a particular buffer, if you make them buffer-local). ++See also @ref{Special Properties}, for how to detect changes to specific ++parts of the text. ++ ++ The functions you use in these hooks should save and restore the match ++data if they do anything that uses regular expressions; otherwise, they ++will interfere in bizarre ways with the editing operations that call ++them. ++ ++@defvar before-change-functions ++This variable holds a list of functions to call before any buffer ++modification. Each function gets two arguments, the beginning and end ++of the region that is about to change, represented as integers. The ++buffer that is about to change is always the current buffer. ++@end defvar ++ ++@defvar after-change-functions ++This variable holds a list of functions to call after any buffer ++modification. Each function receives three arguments: the beginning and ++end of the region just changed, and the length of the text that existed ++before the change. All three arguments are integers. The buffer that's ++about to change is always the current buffer. ++ ++The length of the old text is the difference between the buffer positions ++before and after that text as it was before the change. As for the ++changed text, its length is simply the difference between the first two ++arguments. ++@end defvar ++ ++ Output of messages into the @samp{*Messages*} buffer does not ++call these functions. ++ ++@defmac combine-after-change-calls body@dots{} ++The macro executes @var{body} normally, but arranges to call the ++after-change functions just once for a series of several changes---if ++that seems safe. ++ ++If a program makes several text changes in the same area of the buffer, ++using the macro @code{combine-after-change-calls} around that part of ++the program can make it run considerably faster when after-change hooks ++are in use. When the after-change hooks are ultimately called, the ++arguments specify a portion of the buffer including all of the changes ++made within the @code{combine-after-change-calls} body. ++ ++@strong{Warning:} You must not alter the values of ++@code{after-change-functions} within ++the body of a @code{combine-after-change-calls} form. ++ ++@strong{Warning:} if the changes you combine occur in widely scattered ++parts of the buffer, this will still work, but it is not advisable, ++because it may lead to inefficient behavior for some change hook ++functions. ++@end defmac ++ ++@defvar first-change-hook ++This variable is a normal hook that is run whenever a buffer is changed ++that was previously in the unmodified state. ++@end defvar ++ ++@defvar inhibit-modification-hooks ++If this variable is non-@code{nil}, all of the change hooks are ++disabled; none of them run. This affects all the hook variables ++described above in this section, as well as the hooks attached to ++certain special text properties (@pxref{Special Properties}) and overlay ++properties (@pxref{Overlay Properties}). ++ ++Also, this variable is bound to non-@code{nil} while running those ++same hook variables, so that by default modifying the buffer from ++a modification hook does not cause other modification hooks to be run. ++If you do want modification hooks to be run in a particular piece of ++code that is itself run from a modification hook, then rebind locally ++@code{inhibit-modification-hooks} to @code{nil}. ++@end defvar ++ ++@ignore ++ arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b ++@end ignore +diff --git a/doc/lispref/tindex.pl b/doc/lispref/tindex.pl +new file mode 100755 +index 0000000..b9cff85 +--- /dev/null ++++ b/doc/lispref/tindex.pl +@@ -0,0 +1,126 @@ ++#! /usr/bin/perl ++ ++# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, ++# 2008, 2009 Free Software Foundation, Inc. ++ ++# This file is part of GNU Emacs. ++ ++# GNU Emacs 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. ++ ++# GNU Emacs 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 GNU Emacs. If not, see . ++ ++ ++require 5; ++use Getopt::Long; ++ ++my $USAGE = < \$help, 'version' => \$version, ++ 'old=s' => \$old); ++if ($version) { ++ print "0.1\n"; ++ exit 0; ++} elsif (!$rc || !$old || @ARGV) { ++ print $USAGE; ++ exit 1; ++} elsif ($help) { ++ print $USAGE; ++ exit 0; ++} ++ ++# Fill the hash %tindex with associations VAR -> COUNT where ++# the keys VAR are identifiers mentioned in @tindex lines in the older ++# files to process and COUNT is the number of times they are seen in ++# the files. ++ ++my %tindex; ++my %removed; ++my @old_files = glob "$old/*.texi"; ++my @new_files = glob "*.texi"; ++fatal ("No Texinfo files found in `$old'") unless @old_files; ++fatal ("No Texinfo files found in current directory") unless @new_files; ++ ++print "Scanning old files for \@tindex lines\n"; ++foreach $file (@old_files) { ++ open (IN, "<$file") or fatal "Cannot open $file: $!"; ++ while () { ++ ++$tindex{$1} if /^\s*\@tindex\s+(\S+)/; ++ } ++ close IN; ++} ++ ++# Process current files and remove those @tindex lines which we ++# know were already present in the files scanned above. ++ ++print "Removing old \@tindex lines\n"; ++foreach $file (@new_files) { ++ my $modified = 0; ++ my $contents = ""; ++ ++ open (IN, "< $file") or fatal "Cannot open $file.orig for reading: $!"; ++ while () { ++ if (/^\s*\@tindex\s+(\S+)/ && $tindex{$1}) { ++ ++$removed{$1}; ++ $modified = 1; ++ } else { ++ $contents = $contents . $_; ++ } ++ } ++ ++ close IN; ++ ++ if ($modified) { ++ print " $file\n"; ++ system ("cp $file $file.orig") == 0 or fatal "Cannot backup $file: $!"; ++ open (OUT, ">$file") or fatal "Cannot open $file for writing: $!"; ++ print OUT $contents; ++ close OUT; ++ } ++} ++ ++# Print a list of identifiers removed. ++ ++print "Removed \@tindex commands for:\n"; ++my $key; ++foreach $key (keys %removed) { ++ print " $key\n"; ++} ++ ++# arch-tag: f8460df6-6bef-4c98-8555-e2c63a88b0fa +diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi +new file mode 100644 +index 0000000..fcf91d8 +--- /dev/null ++++ b/doc/lispref/tips.texi +@@ -0,0 +1,1095 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2001, 2002, ++@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/tips ++@node Tips, GNU Emacs Internals, GPL, Top ++@appendix Tips and Conventions ++@cindex tips for writing Lisp ++@cindex standards of coding style ++@cindex coding standards ++ ++ This chapter describes no additional features of Emacs Lisp. Instead ++it gives advice on making effective use of the features described in the ++previous chapters, and describes conventions Emacs Lisp programmers ++should follow. ++ ++ You can automatically check some of the conventions described below by ++running the command @kbd{M-x checkdoc RET} when visiting a Lisp file. ++It cannot check all of the conventions, and not all the warnings it ++gives necessarily correspond to problems, but it is worth examining them ++all. ++ ++@menu ++* Coding Conventions:: Conventions for clean and robust programs. ++* Key Binding Conventions:: Which keys should be bound by which programs. ++* Programming Tips:: Making Emacs code fit smoothly in Emacs. ++* Compilation Tips:: Making compiled code run fast. ++* Warning Tips:: Turning off compiler warnings. ++* Documentation Tips:: Writing readable documentation strings. ++* Comment Tips:: Conventions for writing comments. ++* Library Headers:: Standard headers for library packages. ++@end menu ++ ++@node Coding Conventions ++@section Emacs Lisp Coding Conventions ++ ++@cindex coding conventions in Emacs Lisp ++ Here are conventions that you should follow when writing Emacs Lisp ++code intended for widespread use: ++ ++@itemize @bullet ++@item ++Simply loading a package should not change Emacs's editing behavior. ++Include a command or commands to enable and disable the feature, ++or to invoke it. ++ ++This convention is mandatory for any file that includes custom ++definitions. If fixing such a file to follow this convention requires ++an incompatible change, go ahead and make the incompatible change; ++don't postpone it. ++ ++@item ++You should choose a short word to distinguish your program from other ++Lisp programs. The names of all global variables, constants, and ++functions in your program should begin with that chosen prefix. ++Separate the prefix from the rest of the name with a hyphen, @samp{-}. ++This practice helps avoid name conflicts, since all global variables ++in Emacs Lisp share the same name space, and all functions share ++another name space@footnote{The benefits of a Common Lisp-style ++package system are considered not to outweigh the costs.} ++ ++Occasionally, for a command name intended for users to use, it is more ++convenient if some words come before the package's name prefix. And ++constructs that define functions, variables, etc., work better if they ++start with @samp{defun} or @samp{defvar}, so put the name prefix later ++on in the name. ++ ++This recommendation applies even to names for traditional Lisp ++primitives that are not primitives in Emacs Lisp---such as ++@code{copy-list}. Believe it or not, there is more than one plausible ++way to define @code{copy-list}. Play it safe; append your name prefix ++to produce a name like @code{foo-copy-list} or @code{mylib-copy-list} ++instead. ++ ++If you write a function that you think ought to be added to Emacs under ++a certain name, such as @code{twiddle-files}, don't call it by that name ++in your program. Call it @code{mylib-twiddle-files} in your program, ++and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add ++it to Emacs. If and when we do, we can change the name easily enough. ++ ++If one prefix is insufficient, your package can use two or three ++alternative common prefixes, so long as they make sense. ++ ++@item ++Put a call to @code{provide} at the end of each separate Lisp file. ++@xref{Named Features}. ++ ++@item ++If a file requires certain other Lisp programs to be loaded ++beforehand, then the comments at the beginning of the file should say ++so. Also, use @code{require} to make sure they are loaded. ++x@xref{Named Features}. ++ ++@item ++If a file @var{foo} uses a macro defined in another file @var{bar}, ++but does not use any functions or variables defined in @var{bar}, then ++@var{foo} should contain the following expression: ++ ++@example ++(eval-when-compile (require '@var{bar})) ++@end example ++ ++@noindent ++This tells Emacs to load @var{bar} just before byte-compiling ++@var{foo}, so that the macro definition is available during ++compilation. Using @code{eval-when-compile} avoids loading @var{bar} ++when the compiled version of @var{foo} is @emph{used}. It should be ++called before the first use of the macro in the file. @xref{Compiling ++Macros}. ++ ++@item ++Please don't require the @code{cl} package of Common Lisp extensions at ++run time. Use of this package is optional, and it is not part of the ++standard Emacs namespace. If your package loads @code{cl} at run time, ++that could cause name clashes for users who don't use that package. ++ ++However, there is no problem with using the @code{cl} package at ++compile time, with @code{(eval-when-compile (require 'cl))}. That's ++sufficient for using the macros in the @code{cl} package, because the ++compiler expands them before generating the byte-code. ++ ++@item ++When defining a major mode, please follow the major mode ++conventions. @xref{Major Mode Conventions}. ++ ++@item ++When defining a minor mode, please follow the minor mode ++conventions. @xref{Minor Mode Conventions}. ++ ++@item ++If the purpose of a function is to tell you whether a certain ++condition is true or false, give the function a name that ends in ++@samp{p} (which stands for ``predicate''). If the name is one word, ++add just @samp{p}; if the name is multiple words, add @samp{-p}. ++Examples are @code{framep} and @code{frame-live-p}. ++ ++@item ++If the purpose of a variable is to store a single function, give it a ++name that ends in @samp{-function}. If the purpose of a variable is ++to store a list of functions (i.e., the variable is a hook), please ++follow the naming conventions for hooks. @xref{Hooks}. ++ ++@item ++@cindex unloading packages, preparing for ++If loading the file adds functions to hooks, define a function ++@code{@var{feature}-unload-hook}, where @var{feature} is the name of ++the feature the package provides, and make it undo any such changes. ++Using @code{unload-feature} to unload the file will run this function. ++@xref{Unloading}. ++ ++@item ++It is a bad idea to define aliases for the Emacs primitives. Normally ++you should use the standard names instead. The case where an alias ++may be useful is where it facilitates backwards compatibility or ++portability. ++ ++@item ++If a package needs to define an alias or a new function for ++compatibility with some other version of Emacs, name it with the package ++prefix, not with the raw name with which it occurs in the other version. ++Here is an example from Gnus, which provides many examples of such ++compatibility issues. ++ ++@example ++(defalias 'gnus-point-at-bol ++ (if (fboundp 'point-at-bol) ++ 'point-at-bol ++ 'line-beginning-position)) ++@end example ++ ++@item ++Redefining or advising an Emacs primitive is a bad idea. It may do ++the right thing for a particular program, but there is no telling what ++other programs might break as a result. ++ ++@item ++It is likewise a bad idea for one Lisp package to advise a function in ++another Lisp package (@pxref{Advising Functions}). ++ ++@item ++Avoid using @code{eval-after-load} in libraries and packages ++(@pxref{Hooks for Loading}). This feature is meant for personal ++customizations; using it in a Lisp program is unclean, because it ++modifies the behavior of another Lisp file in a way that's not visible ++in that file. This is an obstacle for debugging, much like advising a ++function in the other package. ++ ++@item ++If a file does replace any of the standard functions or library ++programs of Emacs, prominent comments at the beginning of the file ++should say which functions are replaced, and how the behavior of the ++replacements differs from that of the originals. ++ ++@item ++Constructs that define a function or variable should be macros, ++not functions, and their names should start with @samp{def}. ++ ++@item ++A macro that defines a function or variable should have a name that ++starts with @samp{define-}. The macro should receive the name to be ++defined as the first argument. That will help various tools find the ++definition automatically. Avoid constructing the names in the macro ++itself, since that would confuse these tools. ++ ++@item ++Please keep the names of your Emacs Lisp source files to 13 characters ++or less. This way, if the files are compiled, the compiled files' names ++will be 14 characters or less, which is short enough to fit on all kinds ++of Unix systems. ++ ++@item ++In some other systems there is a convention of choosing variable names ++that begin and end with @samp{*}. We don't use that convention in Emacs ++Lisp, so please don't use it in your programs. (Emacs uses such names ++only for special-purpose buffers.) The users will find Emacs more ++coherent if all libraries use the same conventions. ++ ++@item ++If your program contains non-ASCII characters in string or character ++constants, you should make sure Emacs always decodes these characters ++the same way, regardless of the user's settings. The easiest way to ++do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding ++System Basics}), and specify that coding in the @samp{-*-} line or the ++local variables list. @xref{File variables, , Local Variables in ++Files, emacs, The GNU Emacs Manual}. ++ ++@example ++;; XXX.el -*- coding: utf-8-emacs; -*- ++@end example ++ ++@item ++Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the ++default indentation parameters. ++ ++@item ++Don't make a habit of putting close-parentheses on lines by ++themselves; Lisp programmers find this disconcerting. ++ ++@item ++Please put a copyright notice and copying permission notice on the ++file if you distribute copies. Use a notice like this one: ++ ++@smallexample ++;; Copyright (C) @var{year} @var{name} ++ ++;; 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 . ++@end smallexample ++ ++If you have signed papers to assign the copyright to the Foundation, ++then use @samp{Free Software Foundation, Inc.} as @var{name}. ++Otherwise, use your name. @xref{Library Headers}. ++@end itemize ++ ++@node Key Binding Conventions ++@section Key Binding Conventions ++@cindex key binding, conventions for ++ ++@itemize @bullet ++@item ++@cindex mouse-2 ++@cindex references, following ++Many special major modes, like Dired, Info, Compilation, and Occur, ++are designed to handle read-only text that contains @dfn{hyper-links}. ++Such a major mode should redefine @kbd{mouse-2} and @key{RET} to ++follow the links. It should also set up a @code{follow-link} ++condition, so that the link obeys @code{mouse-1-click-follows-link}. ++@xref{Clickable Text}. @xref{Buttons}, for an easy method of ++implementing such clickable links. ++ ++@item ++@cindex reserved keys ++@cindex keys, reserved ++Don't define @kbd{C-c @var{letter}} as a key in Lisp programs. ++Sequences consisting of @kbd{C-c} and a letter (either upper or lower ++case) are reserved for users; they are the @strong{only} sequences ++reserved for users, so do not block them. ++ ++Changing all the Emacs major modes to respect this convention was a ++lot of work; abandoning this convention would make that work go to ++waste, and inconvenience users. Please comply with it. ++ ++@item ++Function keys @key{F5} through @key{F9} without modifier keys are ++also reserved for users to define. ++ ++@item ++Sequences consisting of @kbd{C-c} followed by a control character or a ++digit are reserved for major modes. ++ ++@item ++Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}}, ++@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes. ++ ++@item ++Sequences consisting of @kbd{C-c} followed by any other punctuation ++character are allocated for minor modes. Using them in a major mode is ++not absolutely prohibited, but if you do that, the major mode binding ++may be shadowed from time to time by minor modes. ++ ++@item ++Don't bind @kbd{C-h} following any prefix character (including ++@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically ++available as a help character for listing the subcommands of the ++prefix character. ++ ++@item ++Don't bind a key sequence ending in @key{ESC} except following another ++@key{ESC}. (That is, it is OK to bind a sequence ending in ++@kbd{@key{ESC} @key{ESC}}.) ++ ++The reason for this rule is that a non-prefix binding for @key{ESC} in ++any context prevents recognition of escape sequences as function keys in ++that context. ++ ++@item ++Anything which acts like a temporary mode or state which the user can ++enter and leave should define @kbd{@key{ESC} @key{ESC}} or ++@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape. ++ ++For a state which accepts ordinary Emacs commands, or more generally any ++kind of state in which @key{ESC} followed by a function key or arrow key ++is potentially meaningful, then you must not define @kbd{@key{ESC} ++@key{ESC}}, since that would preclude recognizing an escape sequence ++after @key{ESC}. In these states, you should define @kbd{@key{ESC} ++@key{ESC} @key{ESC}} as the way to escape. Otherwise, define ++@kbd{@key{ESC} @key{ESC}} instead. ++@end itemize ++ ++@node Programming Tips ++@section Emacs Programming Tips ++@cindex programming conventions ++ ++ Following these conventions will make your program fit better ++into Emacs when it runs. ++ ++@itemize @bullet ++@item ++Don't use @code{next-line} or @code{previous-line} in programs; nearly ++always, @code{forward-line} is more convenient as well as more ++predictable and robust. @xref{Text Lines}. ++ ++@item ++Don't call functions that set the mark, unless setting the mark is one ++of the intended features of your program. The mark is a user-level ++feature, so it is incorrect to change the mark except to supply a value ++for the user's benefit. @xref{The Mark}. ++ ++In particular, don't use any of these functions: ++ ++@itemize @bullet ++@item ++@code{beginning-of-buffer}, @code{end-of-buffer} ++@item ++@code{replace-string}, @code{replace-regexp} ++@item ++@code{insert-file}, @code{insert-buffer} ++@end itemize ++ ++If you just want to move point, or replace a certain string, or insert ++a file or buffer's contents, without any of the other features ++intended for interactive users, you can replace these functions with ++one or two lines of simple Lisp code. ++ ++@item ++Use lists rather than vectors, except when there is a particular reason ++to use a vector. Lisp has more facilities for manipulating lists than ++for vectors, and working with lists is usually more convenient. ++ ++Vectors are advantageous for tables that are substantial in size and are ++accessed in random order (not searched front to back), provided there is ++no need to insert or delete elements (only lists allow that). ++ ++@item ++The recommended way to show a message in the echo area is with ++the @code{message} function, not @code{princ}. @xref{The Echo Area}. ++ ++@item ++When you encounter an error condition, call the function @code{error} ++(or @code{signal}). The function @code{error} does not return. ++@xref{Signaling Errors}. ++ ++Don't use @code{message}, @code{throw}, @code{sleep-for}, or ++@code{beep} to report errors. ++ ++@item ++An error message should start with a capital letter but should not end ++with a period. ++ ++@item ++A question asked in the minibuffer with @code{y-or-n-p} or ++@code{yes-or-no-p} should start with a capital letter and end with ++@samp{? }. ++ ++@item ++When you mention a default value in a minibuffer prompt, ++put it and the word @samp{default} inside parentheses. ++It should look like this: ++ ++@example ++Enter the answer (default 42): ++@end example ++ ++@item ++In @code{interactive}, if you use a Lisp expression to produce a list ++of arguments, don't try to provide the ``correct'' default values for ++region or position arguments. Instead, provide @code{nil} for those ++arguments if they were not specified, and have the function body ++compute the default value when the argument is @code{nil}. For ++instance, write this: ++ ++@example ++(defun foo (pos) ++ (interactive ++ (list (if @var{specified} @var{specified-pos}))) ++ (unless pos (setq pos @var{default-pos})) ++ ...) ++@end example ++ ++@noindent ++rather than this: ++ ++@example ++(defun foo (pos) ++ (interactive ++ (list (if @var{specified} @var{specified-pos} ++ @var{default-pos}))) ++ ...) ++@end example ++ ++@noindent ++This is so that repetition of the command will recompute ++these defaults based on the current circumstances. ++ ++You do not need to take such precautions when you use interactive ++specs @samp{d}, @samp{m} and @samp{r}, because they make special ++arrangements to recompute the argument values on repetition of the ++command. ++ ++@item ++Many commands that take a long time to execute display a message that ++says something like @samp{Operating...} when they start, and change it ++to @samp{Operating...done} when they finish. Please keep the style of ++these messages uniform: @emph{no} space around the ellipsis, and ++@emph{no} period after @samp{done}. @xref{Progress}, for an easy way ++to generate such messages. ++ ++@item ++Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} ++command does: use a new local keymap that contains one command defined ++to switch back to the old local keymap. Or do what the ++@code{edit-options} command does: switch to another buffer and let the ++user switch back at will. @xref{Recursive Editing}. ++@end itemize ++ ++@node Compilation Tips ++@section Tips for Making Compiled Code Fast ++@cindex execution speed ++@cindex speedups ++ ++ Here are ways of improving the execution speed of byte-compiled ++Lisp programs. ++ ++@itemize @bullet ++@item ++@cindex profiling ++@cindex timing programs ++@cindex @file{elp.el} ++Profile your program with the @file{elp} library. See the file ++@file{elp.el} for instructions. ++ ++@item ++@cindex @file{benchmark.el} ++@cindex benchmarking ++Check the speed of individual Emacs Lisp forms using the ++@file{benchmark} library. See the functions @code{benchmark-run} and ++@code{benchmark-run-compiled} in @file{benchmark.el}. ++ ++@item ++Use iteration rather than recursion whenever possible. ++Function calls are slow in Emacs Lisp even when a compiled function ++is calling another compiled function. ++ ++@item ++Using the primitive list-searching functions @code{memq}, @code{member}, ++@code{assq}, or @code{assoc} is even faster than explicit iteration. It ++can be worth rearranging a data structure so that one of these primitive ++search functions can be used. ++ ++@item ++Certain built-in functions are handled specially in byte-compiled code, ++avoiding the need for an ordinary function call. It is a good idea to ++use these functions rather than alternatives. To see whether a function ++is handled specially by the compiler, examine its @code{byte-compile} ++property. If the property is non-@code{nil}, then the function is ++handled specially. ++ ++For example, the following input will show you that @code{aref} is ++compiled specially (@pxref{Array Functions}): ++ ++@example ++@group ++(get 'aref 'byte-compile) ++ @result{} byte-compile-two-args ++@end group ++@end example ++ ++@item ++If calling a small function accounts for a substantial part of your ++program's running time, make the function inline. This eliminates ++the function call overhead. Since making a function inline reduces ++the flexibility of changing the program, don't do it unless it gives ++a noticeable speedup in something slow enough that users care about ++the speed. @xref{Inline Functions}. ++@end itemize ++ ++@node Warning Tips ++@section Tips for Avoiding Compiler Warnings ++@cindex byte compiler warnings, how to avoid ++ ++@itemize @bullet ++@item ++Try to avoid compiler warnings about undefined free variables, by adding ++dummy @code{defvar} definitions for these variables, like this: ++ ++@example ++(defvar foo) ++@end example ++ ++Such a definition has no effect except to tell the compiler ++not to warn about uses of the variable @code{foo} in this file. ++ ++@item ++If you use many functions and variables from a certain file, you can ++add a @code{require} for that package to avoid compilation warnings ++for them. For instance, ++ ++@example ++(eval-when-compile ++ (require 'foo)) ++@end example ++ ++@item ++If you bind a variable in one function, and use it or set it in ++another function, the compiler warns about the latter function unless ++the variable has a definition. But adding a definition would be ++unclean if the variable has a short name, since Lisp packages should ++not define short variable names. The right thing to do is to rename ++this variable to start with the name prefix used for the other ++functions and variables in your package. ++ ++@item ++The last resort for avoiding a warning, when you want to do something ++that usually is a mistake but it's not a mistake in this one case, ++is to put a call to @code{with-no-warnings} around it. ++@end itemize ++ ++@node Documentation Tips ++@section Tips for Documentation Strings ++@cindex documentation strings, conventions and tips ++ ++@findex checkdoc-minor-mode ++ Here are some tips and conventions for the writing of documentation ++strings. You can check many of these conventions by running the command ++@kbd{M-x checkdoc-minor-mode}. ++ ++@itemize @bullet ++@item ++Every command, function, or variable intended for users to know about ++should have a documentation string. ++ ++@item ++An internal variable or subroutine of a Lisp program might as well have ++a documentation string. In earlier Emacs versions, you could save space ++by using a comment instead of a documentation string, but that is no ++longer the case---documentation strings now take up very little space in ++a running Emacs. ++ ++@item ++Format the documentation string so that it fits in an Emacs window on an ++80-column screen. It is a good idea for most lines to be no wider than ++60 characters. The first line should not be wider than 67 characters ++or it will look bad in the output of @code{apropos}. ++ ++You can fill the text if that looks good. However, rather than blindly ++filling the entire documentation string, you can often make it much more ++readable by choosing certain line breaks with care. Use blank lines ++between topics if the documentation string is long. ++ ++@item ++The first line of the documentation string should consist of one or two ++complete sentences that stand on their own as a summary. @kbd{M-x ++apropos} displays just the first line, and if that line's contents don't ++stand on their own, the result looks bad. In particular, start the ++first line with a capital letter and end with a period. ++ ++For a function, the first line should briefly answer the question, ++``What does this function do?'' For a variable, the first line should ++briefly answer the question, ``What does this value mean?'' ++ ++Don't limit the documentation string to one line; use as many lines as ++you need to explain the details of how to use the function or ++variable. Please use complete sentences for the rest of the text too. ++ ++@item ++When the user tries to use a disabled command, Emacs displays just the ++first paragraph of its documentation string---everything through the ++first blank line. If you wish, you can choose which information to ++include before the first blank line so as to make this display useful. ++ ++@item ++The first line should mention all the important arguments of the ++function, and should mention them in the order that they are written ++in a function call. If the function has many arguments, then it is ++not feasible to mention them all in the first line; in that case, the ++first line should mention the first few arguments, including the most ++important arguments. ++ ++@item ++When a function's documentation string mentions the value of an argument ++of the function, use the argument name in capital letters as if it were ++a name for that value. Thus, the documentation string of the function ++@code{eval} refers to its second argument as @samp{FORM}, because the ++actual argument name is @code{form}: ++ ++@example ++Evaluate FORM and return its value. ++@end example ++ ++Also write metasyntactic variables in capital letters, such as when you ++show the decomposition of a list or vector into subunits, some of which ++may vary. @samp{KEY} and @samp{VALUE} in the following example ++illustrate this practice: ++ ++@example ++The argument TABLE should be an alist whose elements ++have the form (KEY . VALUE). Here, KEY is ... ++@end example ++ ++@item ++Never change the case of a Lisp symbol when you mention it in a doc ++string. If the symbol's name is @code{foo}, write ``foo,'' not ++``Foo'' (which is a different symbol). ++ ++This might appear to contradict the policy of writing function ++argument values, but there is no real contradiction; the argument ++@emph{value} is not the same thing as the @emph{symbol} which the ++function uses to hold the value. ++ ++If this puts a lower-case letter at the beginning of a sentence ++and that annoys you, rewrite the sentence so that the symbol ++is not at the start of it. ++ ++@item ++Do not start or end a documentation string with whitespace. ++ ++@item ++@strong{Do not} indent subsequent lines of a documentation string so ++that the text is lined up in the source code with the text of the first ++line. This looks nice in the source code, but looks bizarre when users ++view the documentation. Remember that the indentation before the ++starting double-quote is not part of the string! ++ ++@anchor{Docstring hyperlinks} ++@item ++@iftex ++When a documentation string refers to a Lisp symbol, write it as it ++would be printed (which usually means in lower case), with single-quotes ++around it. For example: @samp{`lambda'}. There are two exceptions: ++write @code{t} and @code{nil} without single-quotes. ++@end iftex ++@ifnottex ++When a documentation string refers to a Lisp symbol, write it as it ++would be printed (which usually means in lower case), with single-quotes ++around it. For example: @samp{lambda}. There are two exceptions: write ++t and nil without single-quotes. (In this manual, we use a different ++convention, with single-quotes for all symbols.) ++@end ifnottex ++ ++@cindex hyperlinks in documentation strings ++Help mode automatically creates a hyperlink when a documentation string ++uses a symbol name inside single quotes, if the symbol has either a ++function or a variable definition. You do not need to do anything ++special to make use of this feature. However, when a symbol has both a ++function definition and a variable definition, and you want to refer to ++just one of them, you can specify which one by writing one of the words ++@samp{variable}, @samp{option}, @samp{function}, or @samp{command}, ++immediately before the symbol name. (Case makes no difference in ++recognizing these indicator words.) For example, if you write ++ ++@example ++This function sets the variable `buffer-file-name'. ++@end example ++ ++@noindent ++then the hyperlink will refer only to the variable documentation of ++@code{buffer-file-name}, and not to its function documentation. ++ ++If a symbol has a function definition and/or a variable definition, but ++those are irrelevant to the use of the symbol that you are documenting, ++you can write the words @samp{symbol} or @samp{program} before the ++symbol name to prevent making any hyperlink. For example, ++ ++@example ++If the argument KIND-OF-RESULT is the symbol `list', ++this function returns a list of all the objects ++that satisfy the criterion. ++@end example ++ ++@noindent ++does not make a hyperlink to the documentation, irrelevant here, of the ++function @code{list}. ++ ++Normally, no hyperlink is made for a variable without variable ++documentation. You can force a hyperlink for such variables by ++preceding them with one of the words @samp{variable} or ++@samp{option}. ++ ++Hyperlinks for faces are only made if the face name is preceded or ++followed by the word @samp{face}. In that case, only the face ++documentation will be shown, even if the symbol is also defined as a ++variable or as a function. ++ ++To make a hyperlink to Info documentation, write the name of the Info ++node (or anchor) in single quotes, preceded by @samp{info node}, ++@samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info ++file name defaults to @samp{emacs}. For example, ++ ++@smallexample ++See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. ++@end smallexample ++ ++Finally, to create a hyperlink to URLs, write the URL in single ++quotes, preceded by @samp{URL}. For example, ++ ++@smallexample ++The home page for the GNU project has more information (see URL ++`http://www.gnu.org/'). ++@end smallexample ++ ++@item ++Don't write key sequences directly in documentation strings. Instead, ++use the @samp{\\[@dots{}]} construct to stand for them. For example, ++instead of writing @samp{C-f}, write the construct ++@samp{\\[forward-char]}. When Emacs displays the documentation string, ++it substitutes whatever key is currently bound to @code{forward-char}. ++(This is normally @samp{C-f}, but it may be some other character if the ++user has moved key bindings.) @xref{Keys in Documentation}. ++ ++@item ++In documentation strings for a major mode, you will want to refer to the ++key bindings of that mode's local map, rather than global ones. ++Therefore, use the construct @samp{\\<@dots{}>} once in the ++documentation string to specify which key map to use. Do this before ++the first use of @samp{\\[@dots{}]}. The text inside the ++@samp{\\<@dots{}>} should be the name of the variable containing the ++local keymap for the major mode. ++ ++It is not practical to use @samp{\\[@dots{}]} very many times, because ++display of the documentation string will become slow. So use this to ++describe the most important commands in your major mode, and then use ++@samp{\\@{@dots{}@}} to display the rest of the mode's keymap. ++ ++@item ++For consistency, phrase the verb in the first sentence of a function's ++documentation string as an imperative---for instance, use ``Return the ++cons of A and B.'' in preference to ``Returns the cons of A and B@.'' ++Usually it looks good to do likewise for the rest of the first ++paragraph. Subsequent paragraphs usually look better if each sentence ++is indicative and has a proper subject. ++ ++@item ++The documentation string for a function that is a yes-or-no predicate ++should start with words such as ``Return t if,'' to indicate ++explicitly what constitutes ``truth.'' The word ``return'' avoids ++starting the sentence with lower-case ``t,'' which could be somewhat ++distracting. ++ ++@item ++If a line in a documentation string begins with an open-parenthesis, ++write a backslash before the open-parenthesis, like this: ++ ++@example ++The argument FOO can be either a number ++\(a buffer position) or a string (a file name). ++@end example ++ ++This prevents the open-parenthesis from being treated as the start of a ++defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). ++ ++@item ++Write documentation strings in the active voice, not the passive, and in ++the present tense, not the future. For instance, use ``Return a list ++containing A and B.'' instead of ``A list containing A and B will be ++returned.'' ++ ++@item ++Avoid using the word ``cause'' (or its equivalents) unnecessarily. ++Instead of, ``Cause Emacs to display text in boldface,'' write just ++``Display text in boldface.'' ++ ++@item ++Avoid using ``iff'' (a mathematics term meaning ``if and only if''), ++since many people are unfamiliar with it and mistake it for a typo. In ++most cases, the meaning is clear with just ``if''. Otherwise, try to ++find an alternate phrasing that conveys the meaning. ++ ++@item ++When a command is meaningful only in a certain mode or situation, ++do mention that in the documentation string. For example, ++the documentation of @code{dired-find-file} is: ++ ++@example ++In Dired, visit the file or directory named on this line. ++@end example ++ ++@item ++When you define a variable that users ought to set interactively, you ++normally should use @code{defcustom}. However, if for some reason you ++use @code{defvar} instead, start the doc string with a @samp{*}. ++@xref{Defining Variables}. ++ ++@item ++The documentation string for a variable that is a yes-or-no flag should ++start with words such as ``Non-nil means,'' to make it clear that ++all non-@code{nil} values are equivalent and indicate explicitly what ++@code{nil} and non-@code{nil} mean. ++@end itemize ++ ++@node Comment Tips ++@section Tips on Writing Comments ++@cindex comments, Lisp convention for ++ ++ We recommend these conventions for where to put comments and how to ++indent them: ++ ++@table @samp ++@item ; ++Comments that start with a single semicolon, @samp{;}, should all be ++aligned to the same column on the right of the source code. Such ++comments usually explain how the code on the same line does its job. In ++Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment}) ++command automatically inserts such a @samp{;} in the right place, or ++aligns such a comment if it is already present. ++ ++This and following examples are taken from the Emacs sources. ++ ++@smallexample ++@group ++(setq base-version-list ; there was a base ++ (assoc (substring fn 0 start-vn) ; version to which ++ file-version-assoc-list)) ; this looks like ++ ; a subversion ++@end group ++@end smallexample ++ ++@item ;; ++Comments that start with two semicolons, @samp{;;}, should be aligned to ++the same level of indentation as the code. Such comments usually ++describe the purpose of the following lines or the state of the program ++at that point. For example: ++ ++@smallexample ++@group ++(prog1 (setq auto-fill-function ++ @dots{} ++ @dots{} ++ ;; update mode line ++ (force-mode-line-update))) ++@end group ++@end smallexample ++ ++We also normally use two semicolons for comments outside functions. ++ ++@smallexample ++@group ++;; This Lisp code is run in Emacs ++;; when it is to operate as a server ++;; for other processes. ++@end group ++@end smallexample ++ ++Every function that has no documentation string (presumably one that is ++used only internally within the package it belongs to), should instead ++have a two-semicolon comment right before the function, explaining what ++the function does and how to call it properly. Explain precisely what ++each argument means and how the function interprets its possible values. ++ ++@item ;;; ++Comments that start with three semicolons, @samp{;;;}, should start at ++the left margin. These are used, occasionally, for comments within ++functions that should start at the margin. We also use them sometimes ++for comments that are between functions---whether to use two or three ++semicolons depends on whether the comment should be considered a ++``heading'' by Outline minor mode. By default, comments starting with ++at least three semicolons (followed by a single space and a ++non-whitespace character) are considered headings, comments starting ++with two or less are not. ++ ++Another use for triple-semicolon comments is for commenting out lines ++within a function. We use three semicolons for this precisely so that ++they remain at the left margin. By default, Outline minor mode does ++not consider a comment to be a heading (even if it starts with at ++least three semicolons) if the semicolons are followed by at least two ++spaces. Thus, if you add an introductory comment to the commented out ++code, make sure to indent it by at least two spaces after the three ++semicolons. ++ ++@smallexample ++(defun foo (a) ++;;; This is no longer necessary. ++;;; (force-mode-line-update) ++ (message "Finished with %s" a)) ++@end smallexample ++ ++When commenting out entire functions, use two semicolons. ++ ++@item ;;;; ++Comments that start with four semicolons, @samp{;;;;}, should be aligned ++to the left margin and are used for headings of major sections of a ++program. For example: ++ ++@smallexample ++;;;; The kill ring ++@end smallexample ++@end table ++ ++@noindent ++The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;} ++(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}), ++automatically indent comments according to these conventions, ++depending on the number of semicolons. @xref{Comments,, ++Manipulating Comments, emacs, The GNU Emacs Manual}. ++ ++@node Library Headers ++@section Conventional Headers for Emacs Libraries ++@cindex header comments ++@cindex library header comments ++ ++ Emacs has conventions for using special comments in Lisp libraries ++to divide them into sections and give information such as who wrote ++them. This section explains these conventions. ++ ++ We'll start with an example, a package that is included in the Emacs ++distribution. ++ ++ Parts of this example reflect its status as part of Emacs; for ++example, the copyright notice lists the Free Software Foundation as the ++copyright holder, and the copying permission says the file is part of ++Emacs. When you write a package and post it, the copyright holder would ++be you (unless your employer claims to own it instead), and you should ++get the suggested copying permission from the end of the GNU General ++Public License itself. Don't say your file is part of Emacs ++if we haven't installed it in Emacs yet! ++ ++ With that warning out of the way, on to the example: ++ ++@smallexample ++@group ++;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers ++ ++;; Copyright (C) 1992 Free Software Foundation, Inc. ++@end group ++ ++;; Author: Eric S. Raymond ++;; Maintainer: Eric S. Raymond ++;; Created: 14 Jul 1992 ++;; Version: 1.2 ++@group ++;; Keywords: docs ++ ++;; This file is part of GNU Emacs. ++@dots{} ++;; along with GNU Emacs. If not, see . ++@end group ++@end smallexample ++ ++ The very first line should have this format: ++ ++@example ++;;; @var{filename} --- @var{description} ++@end example ++ ++@noindent ++The description should be complete in one line. If the file ++needs a @samp{-*-} specification, put it after @var{description}. ++ ++ After the copyright notice come several @dfn{header comment} lines, ++each beginning with @samp{;; @var{header-name}:}. Here is a table of ++the conventional possibilities for @var{header-name}: ++ ++@table @samp ++@item Author ++This line states the name and net address of at least the principal ++author of the library. ++ ++If there are multiple authors, you can list them on continuation lines ++led by @code{;;} and a tab character, like this: ++ ++@smallexample ++@group ++;; Author: Ashwin Ram ++;; Dave Sill ++;; Dave Brennan ++;; Eric Raymond ++@end group ++@end smallexample ++ ++@item Maintainer ++This line should contain a single name/address as in the Author line, or ++an address only, or the string @samp{FSF}. If there is no maintainer ++line, the person(s) in the Author field are presumed to be the ++maintainers. The example above is mildly bogus because the maintainer ++line is redundant. ++ ++The idea behind the @samp{Author} and @samp{Maintainer} lines is to make ++possible a Lisp function to ``send mail to the maintainer'' without ++having to mine the name out by hand. ++ ++Be sure to surround the network address with @samp{<@dots{}>} if ++you include the person's full name as well as the network address. ++ ++@item Created ++This optional line gives the original creation date of the ++file. For historical interest only. ++ ++@item Version ++If you wish to record version numbers for the individual Lisp program, put ++them in this line. ++ ++@item Adapted-By ++In this header line, place the name of the person who adapted the ++library for installation (to make it fit the style conventions, for ++example). ++ ++@item Keywords ++This line lists keywords for the @code{finder-by-keyword} help command. ++Please use that command to see a list of the meaningful keywords. ++ ++This field is important; it's how people will find your package when ++they're looking for things by topic area. To separate the keywords, you ++can use spaces, commas, or both. ++@end table ++ ++ Just about every Lisp library ought to have the @samp{Author} and ++@samp{Keywords} header comment lines. Use the others if they are ++appropriate. You can also put in header lines with other header ++names---they have no standard meanings, so they can't do any harm. ++ ++ We use additional stylized comments to subdivide the contents of the ++library file. These should be separated by blank lines from anything ++else. Here is a table of them: ++ ++@table @samp ++@item ;;; Commentary: ++This begins introductory comments that explain how the library works. ++It should come right after the copying permissions, terminated by a ++@samp{Change Log}, @samp{History} or @samp{Code} comment line. This ++text is used by the Finder package, so it should make sense in that ++context. ++ ++@item ;;; Documentation: ++This was used in some files in place of @samp{;;; Commentary:}, ++but it is deprecated. ++ ++@item ;;; Change Log: ++This begins change log information stored in the library file (if you ++store the change history there). For Lisp files distributed with Emacs, ++the change history is kept in the file @file{ChangeLog} and not in the ++source file at all; these files generally do not have a @samp{;;; Change ++Log:} line. @samp{History} is an alternative to @samp{Change Log}. ++ ++@item ;;; Code: ++This begins the actual code of the program. ++ ++@item ;;; @var{filename} ends here ++This is the @dfn{footer line}; it appears at the very end of the file. ++Its purpose is to enable people to detect truncated versions of the file ++from the lack of a footer line. ++@end table ++ ++@ignore ++ arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e ++@end ignore +diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt +new file mode 100644 +index 0000000..0d80abd +--- /dev/null ++++ b/doc/lispref/two-volume-cross-refs.txt +@@ -0,0 +1,320 @@ ++Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++ Free Software Foundation, Inc. ++ See end for copying conditions. ++ ++Two Volume Cross References ++=========================== ++ ++12 June 2007 (karl) ++ ++For lispref 2.9 (for Emacs 22, June 2007), I created a very ugly ++Makefile, in the file two-volume.make, to encapsulate all the steps ++below, without manual intervention. In theory, simply running "make -f ++two-volume.make" should create a vol1.pdf and vol2.pdf with all the ++niceties worked out. ++ ++One issue not explicitly discussed below is getting page numbers right. ++It's not enough to go through the whole process. You have to go through ++the whole process twice -- otherwise, some index entries and/or toc ++entries will be off by one. See two-volume.make for a few more comments. ++ ++For future editions, it should suffice to update the usual things in ++vol[12].texi (as well as elisp.texi). That was my hope, anyway. ++ ++ ++18 March 1992 (bob) ++ ++This enables you to create manuals in *two* volumes, with tables of ++contents, cross references, and indices in each volume referring to ++*both* volumes. ++ ++The procedure is tedious. However, the resulting two volumes are ++conveniently organized. Each has an index of the whole two volumes. ++Each volume starts with page 1. (I don't like multi-volume works ++where each volume starts with a higher page number since I find it ++harder to go to the right place in the volume.) ++ ++References to the same volume are just the page number; references to ++the other volume are a volumne number (in Roman numerals) preceding ++the page number. ++ ++For example, in Volume I: ++ ++ list length ......... 90 ++ list motion ......II:117 ++ ++and in Volume II: ++ ++ list length ....... I:90 ++ list motion .........117 ++ ++All other references and the table of contents work the same way. I ++find this *very* helpful. ++ ++ ++In brief: you run tex on a .texi file with ++ ++ a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file ++ b. redone .aux file ++ c. redone .fns file ++ ++ ++Here are the steps in detail: ++ ++% tex vol1.texi ++% texindex vol1.?? ++% tex vol1.texi ++ ++% tex vol2.texi ++% texindex vol2.?? ++% tex vol2.texi ++ ++### Create .aux files with volume numbers for other volume. ++ ++% cp vol1.aux elisp1-aux ++% cp vol2.aux elisp2-aux ++ ++% cp vol1.aux elisp1-aux-vol-added ++% cp vol2.aux elisp2-aux-vol-added ++ ++on elisp1-aux-vol-number-added ++(volume-aux-markup 1) see defun for volume-aux-markup below. ++to create elisp1-aux-vol-added ++ ++on elisp2-aux-vol-number-added ++(volume-aux-markup 2) ++to create elisp2-aux-vol-added ++ ++insert elisp2-aux-vol-added into vol1.aux (append) ++insert elisp1-aux-vol-added into vol2.aux (prepend) ++ ++(so you dont have to do it again) ++% cp vol1.aux elisp1-aux-ready ++% cp vol2.aux elisp2-aux-ready ++ ++ ++### Create .fn files with volume numbers for other volume. ++ ++% cp vol1.fn elisp1-fn ++% cp vol2.fn elisp2-fn ++ ++% cp vol1.fn elisp1-fn-vol-number-added ++% cp vol2.fn elisp2-fn-vol-number-added ++ ++on elisp1-fn-vol-number-added ++(volume-index-markup "I") ++to create elisp1-fn-vol-number-added ++ ++on elisp2-fn-vol-number-added ++(volume-index-markup "II") ++to create elisp2-fn-vol-number-added ++ ++insert elisp2-fn-vol-number-added into vol1.fn: do following `cat' ++insert elisp1-fn-vol-number-added into vol2.fn: do following `cat' ++ ++% cat elisp2-fn-vol-number-added >> vol1.fn ++% cat elisp1-fn-vol-number-added >> vol2.fn ++ ++Be sure to handle special case entries by hand. ++Be sure that .fn file has no blank lines. ++ ++% texindex vol1.fn ++% texindex vol2.fn ++ ++(so you dont have to do it again) ++% cp vol1.fns elisp1-fns-2vol-ready ++% cp vol2.fns elisp2-fns-2vol-ready ++ ++### Create merged .toc file with volume number headings. ++ ++append vol2.toc to vol1.toc with following `cat' ++ ++% cat vol1.toc vol2.toc > elisp-toc-2vol.toc ++ ++and edit in Volume titles ++ ++\unnumbchapentry {Volume 1}{} ++\unnumbchapentry {}{} ++ ++\unnumbchapentry {Index}{295} ++\unnumbchapentry {}{} ++\unnumbchapentry {Volume 2}{} ++\unnumbchapentry {}{} ++ ++If you want to put in volume numbers for TOC, then do this: ++Create volume specific .toc files with volume numbers in them. ++ ++% cp elisp-toc-2vol.toc elisp1-toc.toc ++% cp elisp-toc-2vol.toc elisp2-toc.toc ++ ++Use keyboard macro to put I: in first half of elisp1-toc.toc and ++II: in first half of elisp2-toc.toc ++ ++Copy the tocs to something you can remember more easily ++ ++% cp elisp2-toc.toc elisp1-toc-ready.toc ++% cp elisp1-toc.toc elisp2-toc-ready.toc ++ ++Then, edit vol1.texi to input elisp1-toc-ready.toc ++and vol2.texi to input elisp2-toc-ready.toc ++ ++ ++### Now format the two volumes: ++ ++% cp elisp1-aux-2vol-ready vol1.aux ++% cp elisp2-aux-2vol-ready vol2.aux ++ ++% tex vol1.texi ++% tex vol2.texi ++ ++ ++ ++For every additional run: ++ ++### recopy aux files so the correct ones are read: ++% cp elisp1-aux-2vol-ready vol1.aux ++% cp elisp2-aux-2vol-ready vol2.aux ++ ++Do not run texindex. Then proper sorted index will stay. ++ else do: % cp elisp2-fns-2vol-ready vol2.fns ++ ++Do not change the .texi files; they will call the elisp-toc-2vol.toc file. ++ ++% tex vol1.texi ++% tex vol2.texi ++ ++================================================================ ++ ++ ++(defun volume-aux-markup (arg) ++ "Append `vol. NUMBER' to page number. ++Apply to aux file that you save. ++Then insert marked file into other volume's .aux file." ++ (interactive "sType volume number, 1 or 2: " ) ++ (goto-char (point-min)) ++ (while (search-forward "-pg" nil t) ++ (end-of-line 1) ++ (delete-backward-char 1 nil) ++ (insert ", vol.'tie" arg "}"))) ++ ++(defun volume-index-markup (arg) ++ "Prepend `NUMBER:' to page number. Use Roman Numeral. ++Apply only to unsorted index file, ++Then insert marked file into other volume's unsorted index file. ++Then run texindex on that file and save." ++ (interactive ++ "sType volume number, roman number I or II: " ) ++ (goto-char (point-min)) ++ (while (search-forward "\\entry" nil t) ++ (search-forward "}{" (save-excursion (end-of-line) (point)) nil) ++ (insert arg ":"))) ++ ++ ++================================================================ ++ ++ ++The steps: ++ ++1. Run TeX, texindex and TeX on file1. ++2. Run TeX, texindex and TeX on file2. ++ ++3. Copy both .aux files into specially named files ++ ++4. In the case of the elisp ref manual, ++ ++ copy the *unsorted* function index files into specially named files ++ (no other index used in elisp ref manual) ++ ++ ++5. For aux files: ++ ++ Run a function on the specially named .aux files to label each ++ entry according to volume. Save these files. ++ ++ i.e., convert ++ 'xrdef {Special-pg}{7} to 'xrdef {Special-pg}{7, vol.'tie1} ++ ++5a.Insert each specially named .aux file into the regular .aux file of ++ the other volume. ++ ++6. For index files: ++ ++ Run a function on the specially named unsorted index files to label ++ each entry according to volume. Save these files. ++ ++6b.Insert each specially named marked unsorted index file into the ++ regular unsorted file of the other volume. Run texindex on this ++ ++7. Insert the other volumes .toc file into the .toc, edit, and rename to ++ elisp-toc-2vol.toc ++ ++7a. insert special @contents and @summarycontents defs into .texi files. ++ ++8. Run TeX on each .texi file. ++ ++================ ++ ++ ++ ++Here is the discursive commentary: ++ ++I've been running some small test files, called test1.texi and ++test2.texi. As far as I can see, if we run tex on the two test files, ++tex creates a .aux for each that includes the names of all the nodes ++in that file. The node names are used for cross references. ++ ++If you insert the .aux file for the second test file, test2.aux, into ++the .aux file for the first test file, test1.aux, then when you next ++run TeX on the first test file, test1.texi, the second volume cross ++references are inserted. ++ ++You can edit the text of the cross reference in test2.aux to include ++the volume number. ++ ++For example, you can take the following two lines from test1.texi and ++insert them into test2.texi: ++ ++ 'xrdef {Special-pg}{7} ++ 'xrdef {Special-snt}{Section'tie1.6} ++ ++You can re-edit this to show that the page is in volume 1: ++ ++ 'xrdef {Special-pg}{7, vol.'tie1} ++ 'xrdef {Special-snt}{Section'tie1.6} ++ ++(The 'tie is a TeX special command to keep the number tied on one ++line to the previous word. I don't know if it works after a period in ++the "vol." but figure it is worth trying. {The ' is the @ of .aux files.} ++Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the ++definition for 'tie is the following: ++ ++ \def\tie{\penalty 10000\ } % Save plain tex definition of ~. ++ ++) ++ ++After running tex on the test2.texi file with the augmented test2.aux ++file, you can see the following in the resulting DVI file: ++ ++ See Section 1.6 [Special], page 7, vol. 1 ++ ++Note that TeX rewrites the .aux file each time TeX is run, so after ++running Tex using an .aux file augmented with the .aux file from the ++other volume, the new .aux file will *lack* the other volumes cross ++references. Save your augmented .aux file in some other name for ++another run! ++ ++ ++COPYING CONDITIONS ++ ++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 file. If not, see . +diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make +new file mode 100644 +index 0000000..ca13397 +--- /dev/null ++++ b/doc/lispref/two-volume.make +@@ -0,0 +1,224 @@ ++# Copyright (C) 2007, 2008, 2009 Free Software Foundation, Inc. ++# See end for copying conditions. ++ ++# although it would be nice to use tex rather than pdftex to avoid ++# colors, spurious warnings about names being referenced but not ++# existing, etc., dvips | ps2pdf doesn't preserve the page size. ++# Instead of creating a special dvips config file, put up with the warnings. ++texinfodir=../misc ++ ++tex = TEXINPUTS=".:$(texinfodir):${TEXINPUTS}" pdftex -interaction=nonstopmode ++ ++all: vol1.pdf vol2.pdf ++ ++# vol1.texi and vol2.texi specially define \tocreadfilename so we can ++# use our premade .toc's. ++# ++vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready ++ @echo -e "\f Final TeX run for volume 1..." ++ cp elisp1med-toc-ready elisp1-toc-ready.toc ++ cp elisp1med-fns-ready vol1.fns ++ cp elisp1med-aux-ready vol1.aux ++ $(tex) vol1.texi ++# ++vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready ++ @echo "Final TeX run for volume 2..." ++ cp elisp2med-toc-ready elisp2-toc-ready.toc ++ cp elisp2med-fns-ready vol2.fns ++ cp elisp2med-aux-ready vol2.aux ++ $(tex) vol2.texi ++ ++# intermediate toc files. ++# ++# vol1 toc: volume 1, page break, volume 2 (with II: prepended). ++elisp1med-toc-ready: elisp1med-init elisp2med-init ++ echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ ++ cat elisp1med-toc >>$@ ++ echo '@page' >>$@ ++ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ ++ sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@ ++# ++# vol2 toc: volume 1 (with I: prepended), page break, volume 2. ++elisp2med-toc-ready: elisp1med-init elisp2med-init ++ echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ ++ sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@ ++ echo '@page' >>$@ ++ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ ++ cat elisp2med-toc >>$@ ++ ++ ++# intermediate aux files. ++# ++# append vol2's fixed aux to normal vol1. ++elisp1med-aux-ready: elisp2med-aux-vol-added ++ cat elisp1med-aux $< >$@ ++# ++# prepend vol1's fixed aux to vol2. ++elisp2med-aux-ready: elisp1med-aux-vol-added ++ cat $< elisp2med-aux >$@ ++ ++# on -pg entries, append volume number after page number. ++elisp1med-aux-vol-added: elisp1med-init ++ sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1med-aux >$@ ++# ++elisp2med-aux-vol-added: elisp2med-init ++ sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@ ++ ++# intermediate index (fns) file. ++# ++elisp1med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added ++ cat elisp2med-fn-vol-added >>vol1.fn ++ texindex vol1.fn ++ cp vol1.fns $@ ++# ++elisp2med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added ++ cat elisp1med-fn-vol-added >>vol2.fn ++ texindex vol2.fn ++ cp vol2.fns $@ ++ ++# Insert volume number (I: or II:) into index file. ++elisp1med-fn-vol-added: elisp1med-init ++ cp vol1.fn elisp1med-fn ++ sed 's/}{/}{I:/' elisp1med-fn >$@ ++# ++elisp2med-fn-vol-added: elisp2med-init ++ cp vol2.fn elisp2med-fn ++ sed 's/}{/}{II:/' elisp2med-fn >$@ ++ ++# ----------------------------------------------------------------------------- ++# everything above is essentially a duplicate of everything below. sorry. ++# ----------------------------------------------------------------------------- ++ ++# intermediate TeX runs. ++# ++# this generates what would be the final versions -- except the page ++# numbers aren't right. The process of adding the I: and II: changes ++# the page breaks, so a few index entries, at least are wrong. (In ++# 2007, x-meta-keysym in vol.II ended up on page 374 when the index had ++# it on page 375 from the initial run.) ++# ++# So, we start all over again, from these fns/aux/toc files. ++# ++elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready $(texinfodir)/texinfo.tex ++ @echo -e "\f Intermediate TeX run for volume 1..." ++ cp elisp1init-toc-ready elisp1-toc-ready.toc ++ cp elisp1-fns-ready vol1.fns ++ cp elisp1-aux-ready vol1.aux ++ $(tex) vol1.texi ++ texindex vol1.?? ++ mv vol1.aux elisp1med-aux ++ mv vol1.toc elisp1med-toc ++# ++elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready $(texinfodir)/texinfo.tex ++ @echo "Final TeX run for volume 2..." ++ cp elisp2init-toc-ready elisp2-toc-ready.toc ++ cp elisp2-fns-ready vol2.fns ++ cp elisp2-aux-ready vol2.aux ++ $(tex) vol2.texi ++ texindex vol2.?? ++ mv vol2.aux elisp2med-aux ++ mv vol2.toc elisp2med-toc ++ ++ ++# initial toc files. ++# ++# vol1 toc: volume 1, page break, volume 2 (with II: prepended). ++elisp1init-toc-ready: elisp1-init elisp2-init ++ echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ ++ cat elisp1-toc >>$@ ++ echo '@page' >>$@ ++ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ ++ sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@ ++# ++# vol2 toc: volume 1 (with I: prepended), page break, volume 2. ++elisp2init-toc-ready: elisp1-init elisp2-init ++ echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ ++ sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@ ++ echo '@page' >>$@ ++ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ ++ cat elisp2-toc >>$@ ++ ++ ++# initial aux files. ++# ++# append vol2's fixed aux to normal vol1. The initial runs saved ++# elisp1-aux and elisp2-aux. ++elisp1-aux-ready: elisp2-aux-vol-added ++ cat elisp1-aux $< >$@ ++# ++# prepend vol1's fixed aux to vol2. ++elisp2-aux-ready: elisp1-aux-vol-added ++ cat $< elisp2-aux >$@ ++ ++# on -pg entries, append volume number after page number. ++elisp1-aux-vol-added: elisp1-init ++ sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1-aux >$@ ++# ++elisp2-aux-vol-added: elisp2-init ++ sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@ ++ ++# initial index (fns) file. ++# ++# Append other volume's index entries to this one's. ++# Index entries in this volume will then take precedence. ++elisp1-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added ++ cat elisp2-fn-vol-added >>vol1.fn ++ texindex vol1.fn ++ cp vol1.fns $@ ++# ++elisp2-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added ++ cat elisp1-fn-vol-added >>vol2.fn ++ texindex vol2.fn ++ cp vol2.fns $@ ++ ++# Insert volume number (I: or II:) into index file. ++elisp1-fn-vol-added: elisp1-init ++ cp vol1.fn elisp1-fn ++ sed 's/}{/}{I:/' elisp1-fn >$@ ++# ++elisp2-fn-vol-added: elisp2-init ++ cp vol2.fn elisp2-fn ++ sed 's/}{/}{II:/' elisp2-fn >$@ ++ ++ ++# initial TeX runs. ++# ++# We use the .fn, .aux, and .toc files created here in subsequent ++# processing. The page numbers generated here will not be correct yet, ++# but we run texindex and TeX a second time just to get them closer. ++# Otherwise it might take even longer for them to converge. ++# ++elisp1-init: vol1.texi ++ @echo -e "\f Initial TeX run for volume 1..." ++ rm -f vol1.aux vol1.toc ++ $(tex) $< ++ texindex vol1.?? ++ mv vol1.aux elisp1-aux ++ mv vol1.toc elisp1-toc ++ touch $@ ++# ++elisp2-init: vol2.texi ++ @echo "Initial TeX run for volume 2..." ++ rm -f vol2.aux vol2.toc ++ $(tex) $< ++ texindex vol2.?? ++ mv vol2.aux elisp2-aux ++ mv vol2.toc elisp2-toc ++ touch $@ ++ ++# COPYING CONDITIONS ++# ++# 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 file. If not, see . ++ ++# arch-tag: 5c258a2e-d4a9-4d0e-b279-fb3a6faa27eb +diff --git a/doc/lispref/two.el b/doc/lispref/two.el +new file mode 100644 +index 0000000..124e518 +--- /dev/null ++++ b/doc/lispref/two.el +@@ -0,0 +1,80 @@ ++;; Auxiliary functions for preparing a two volume manual. ++ ++;; Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++;; Free Software Foundation, Inc. ++ ++;; --rjc 30mar92 ++ ++;; 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 file. If not, see . ++ ++ ++(defun volume-aux-markup (arg) ++ "Append `vol. NUMBER' to page number. ++Apply to aux file that you save. ++Then insert marked file into other volume's .aux file." ++ (interactive "sType volume number, 1 or 2: " ) ++ (goto-char (point-min)) ++ (while (search-forward "-pg" nil t) ++ (end-of-line 1) ++ (delete-backward-char 1 nil) ++ (insert ", vol.'tie" arg "}"))) ++ ++(defun volume-index-markup (arg) ++ "Prepend `NUMBER:' to page number. Use Roman Numeral. ++Apply only to unsorted index file, ++Then insert marked file into other volume's unsorted index file. ++Then run texindex on that file and save." ++ (interactive ++ "sType volume number, roman number I or II: " ) ++ (goto-char (point-min)) ++ (while (search-forward "\\entry" nil t) ++ (search-forward "}{" (save-excursion (end-of-line) (point)) nil) ++ (insert arg ":"))) ++ ++(defun volume-numbers-toc-markup (arg) ++ (interactive ++ "sType volume number, roman number I or II: " ) ++ (goto-char (point-min)) ++ (while (search-forward "chapentry" nil t) ++ (end-of-line) ++ (search-backward "{" nil t) ++ (forward-char 1) ++ (insert arg ":"))) ++ ++(defun volume-header-toc-markup () ++ "Insert Volume I and Volume II text into .toc file. ++NOTE: this auxilary function is file specific. ++This is for the *Elisp Ref Manual*" ++ (interactive) ++ (goto-char (point-min)) ++ (insert "\\unnumbchapentry {Volume 1}{}\n\\unnumbchapentry {}{}\n") ++ (search-forward "\\unnumbchapentry {Index}") ++ (forward-line 1) ++ (insert ++ "\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {Volume 2}{}\n\\unnumbchapentry {}{}\n")) ++ ++ ++;;; In batch mode, you cannot call functions with args; hence this kludge: ++ ++(defun volume-aux-markup-1 () (volume-aux-markup "1")) ++(defun volume-aux-markup-2 () (volume-aux-markup "2")) ++ ++(defun volume-index-markup-I () (volume-index-markup "I")) ++(defun volume-index-markup-II () (volume-index-markup "II")) ++ ++(defun volume-numbers-toc-markup-I () (volume-numbers-toc-markup "I")) ++(defun volume-numbers-toc-markup-II () (volume-numbers-toc-markup "II")) ++ ++;; arch-tag: 848955fe-e9cf-45e7-a2f1-570ef156d6a5 ++;;; two.el ends here +diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi +new file mode 100644 +index 0000000..89fb19b +--- /dev/null ++++ b/doc/lispref/variables.texi +@@ -0,0 +1,1927 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, ++@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/variables ++@node Variables, Functions, Control Structures, Top ++@chapter Variables ++@cindex variable ++ ++ A @dfn{variable} is a name used in a program to stand for a value. ++Nearly all programming languages have variables of some sort. In the ++text of a Lisp program, variables are written using the syntax for ++symbols. ++ ++ In Lisp, unlike most programming languages, programs are represented ++primarily as Lisp objects and only secondarily as text. The Lisp ++objects used for variables are symbols: the symbol name is the ++variable name, and the variable's value is stored in the value cell of ++the symbol. The use of a symbol as a variable is independent of its ++use as a function name. @xref{Symbol Components}. ++ ++ The textual form of a Lisp program is given by the read syntax of ++the Lisp objects that constitute the program. Hence, a variable in a ++textual Lisp program is written using the read syntax for the symbol ++representing the variable. ++ ++@menu ++* Global Variables:: Variable values that exist permanently, everywhere. ++* Constant Variables:: Certain "variables" have values that never change. ++* Local Variables:: Variable values that exist only temporarily. ++* Void Variables:: Symbols that lack values. ++* Defining Variables:: A definition says a symbol is used as a variable. ++* Tips for Defining:: Things you should think about when you ++ define a variable. ++* Accessing Variables:: Examining values of variables whose names ++ are known only at run time. ++* Setting Variables:: Storing new values in variables. ++* Variable Scoping:: How Lisp chooses among local and global values. ++* Buffer-Local Variables:: Variable values in effect only in one buffer. ++* File Local Variables:: Handling local variable lists in files. ++* Directory Local Variables:: Local variables common to all files in a directory. ++* Frame-Local Variables:: Frame-local bindings for variables. ++* Variable Aliases:: Variables that are aliases for other variables. ++* Variables with Restricted Values:: Non-constant variables whose value can ++ @emph{not} be an arbitrary Lisp object. ++@end menu ++ ++@node Global Variables ++@section Global Variables ++@cindex global variable ++ ++ The simplest way to use a variable is @dfn{globally}. This means that ++the variable has just one value at a time, and this value is in effect ++(at least for the moment) throughout the Lisp system. The value remains ++in effect until you specify a new one. When a new value replaces the ++old one, no trace of the old value remains in the variable. ++ ++ You specify a value for a symbol with @code{setq}. For example, ++ ++@example ++(setq x '(a b)) ++@end example ++ ++@noindent ++gives the variable @code{x} the value @code{(a b)}. Note that ++@code{setq} is a special form (@pxref{Special Forms}); it does not ++evaluate its first argument, the name of the variable, but it does ++evaluate the second argument, the new value. ++ ++ Once the variable has a value, you can refer to it by using the ++symbol itself as an expression. Thus, ++ ++@example ++@group ++x @result{} (a b) ++@end group ++@end example ++ ++@noindent ++assuming the @code{setq} form shown above has already been executed. ++ ++ If you do set the same variable again, the new value replaces the old ++one: ++ ++@example ++@group ++x ++ @result{} (a b) ++@end group ++@group ++(setq x 4) ++ @result{} 4 ++@end group ++@group ++x ++ @result{} 4 ++@end group ++@end example ++ ++@node Constant Variables ++@section Variables that Never Change ++@kindex setting-constant ++@cindex keyword symbol ++@cindex variable with constant value ++@cindex constant variables ++@cindex symbol that evaluates to itself ++@cindex symbol with constant value ++ ++ In Emacs Lisp, certain symbols normally evaluate to themselves. These ++include @code{nil} and @code{t}, as well as any symbol whose name starts ++with @samp{:} (these are called @dfn{keywords}). These symbols cannot ++be rebound, nor can their values be changed. Any attempt to set or bind ++@code{nil} or @code{t} signals a @code{setting-constant} error. The ++same is true for a keyword (a symbol whose name starts with @samp{:}), ++if it is interned in the standard obarray, except that setting such a ++symbol to itself is not an error. ++ ++@example ++@group ++nil @equiv{} 'nil ++ @result{} nil ++@end group ++@group ++(setq nil 500) ++@error{} Attempt to set constant symbol: nil ++@end group ++@end example ++ ++@defun keywordp object ++function returns @code{t} if @var{object} is a symbol whose name ++starts with @samp{:}, interned in the standard obarray, and returns ++@code{nil} otherwise. ++@end defun ++ ++@node Local Variables ++@section Local Variables ++@cindex binding local variables ++@cindex local variables ++@cindex local binding ++@cindex global binding ++ ++ Global variables have values that last until explicitly superseded ++with new values. Sometimes it is useful to create variable values that ++exist temporarily---only until a certain part of the program finishes. ++These values are called @dfn{local}, and the variables so used are ++called @dfn{local variables}. ++ ++ For example, when a function is called, its argument variables receive ++new local values that last until the function exits. The @code{let} ++special form explicitly establishes new local values for specified ++variables; these last until exit from the @code{let} form. ++ ++@cindex shadowing of variables ++ Establishing a local value saves away the variable's previous value ++(or lack of one). We say that the previous value is @dfn{shadowed} ++and @dfn{not visible}. Both global and local values may be shadowed ++(@pxref{Scope}). After the life span of the local value is over, the ++previous value (or lack of one) is restored. ++ ++ If you set a variable (such as with @code{setq}) while it is local, ++this replaces the local value; it does not alter the global value, or ++previous local values, that are shadowed. To model this behavior, we ++speak of a @dfn{local binding} of the variable as well as a local value. ++ ++ The local binding is a conceptual place that holds a local value. ++Entering a function, or a special form such as @code{let}, creates the ++local binding; exiting the function or the @code{let} removes the ++local binding. While the local binding lasts, the variable's value is ++stored within it. Using @code{setq} or @code{set} while there is a ++local binding stores a different value into the local binding; it does ++not create a new binding. ++ ++ We also speak of the @dfn{global binding}, which is where ++(conceptually) the global value is kept. ++ ++@cindex current binding ++ A variable can have more than one local binding at a time (for ++example, if there are nested @code{let} forms that bind it). In such a ++case, the most recently created local binding that still exists is the ++@dfn{current binding} of the variable. (This rule is called ++@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no ++local bindings, the variable's global binding is its current binding. ++We sometimes call the current binding the @dfn{most-local existing ++binding}, for emphasis. Ordinary evaluation of a symbol always returns ++the value of its current binding. ++ ++ The special forms @code{let} and @code{let*} exist to create ++local bindings. ++ ++@defspec let (bindings@dots{}) forms@dots{} ++This special form binds variables according to @var{bindings} and then ++evaluates all of the @var{forms} in textual order. The @code{let}-form ++returns the value of the last form in @var{forms}. ++ ++Each of the @var{bindings} is either @w{(i) a} symbol, in which case ++that symbol is bound to @code{nil}; or @w{(ii) a} list of the form ++@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is ++bound to the result of evaluating @var{value-form}. If @var{value-form} ++is omitted, @code{nil} is used. ++ ++All of the @var{value-form}s in @var{bindings} are evaluated in the ++order they appear and @emph{before} binding any of the symbols to them. ++Here is an example of this: @code{z} is bound to the old value of ++@code{y}, which is 2, not the new value of @code{y}, which is 1. ++ ++@example ++@group ++(setq y 2) ++ @result{} 2 ++@end group ++@group ++(let ((y 1) ++ (z y)) ++ (list y z)) ++ @result{} (1 2) ++@end group ++@end example ++@end defspec ++ ++@defspec let* (bindings@dots{}) forms@dots{} ++This special form is like @code{let}, but it binds each variable right ++after computing its local value, before computing the local value for ++the next variable. Therefore, an expression in @var{bindings} can ++reasonably refer to the preceding symbols bound in this @code{let*} ++form. Compare the following example with the example above for ++@code{let}. ++ ++@example ++@group ++(setq y 2) ++ @result{} 2 ++@end group ++@group ++(let* ((y 1) ++ (z y)) ; @r{Use the just-established value of @code{y}.} ++ (list y z)) ++ @result{} (1 1) ++@end group ++@end example ++@end defspec ++ ++ Here is a complete list of the other facilities that create local ++bindings: ++ ++@itemize @bullet ++@item ++Function calls (@pxref{Functions}). ++ ++@item ++Macro calls (@pxref{Macros}). ++ ++@item ++@code{condition-case} (@pxref{Errors}). ++@end itemize ++ ++ Variables can also have buffer-local bindings (@pxref{Buffer-Local ++Variables}); a few variables have terminal-local bindings ++(@pxref{Multiple Terminals}). These kinds of bindings work somewhat ++like ordinary local bindings, but they are localized depending on ++``where'' you are in Emacs, rather than localized in time. ++ ++@defopt max-specpdl-size ++@anchor{Definition of max-specpdl-size} ++@cindex variable limit error ++@cindex evaluation error ++@cindex infinite recursion ++This variable defines the limit on the total number of local variable ++bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,, ++Cleaning Up from Nonlocal Exits}) that are allowed before Emacs ++signals an error (with data @code{"Variable binding depth exceeds ++max-specpdl-size"}). ++ ++This limit, with the associated error when it is exceeded, is one way ++that Lisp avoids infinite recursion on an ill-defined function. ++@code{max-lisp-eval-depth} provides another limit on depth of nesting. ++@xref{Definition of max-lisp-eval-depth,, Eval}. ++ ++The default value is 1000. Entry to the Lisp debugger increases the ++value, if there is little room left, to make sure the debugger itself ++has room to execute. ++@end defopt ++ ++@node Void Variables ++@section When a Variable is ``Void'' ++@kindex void-variable ++@cindex void variable ++ ++ If you have never given a symbol any value as a global variable, we ++say that that symbol's global value is @dfn{void}. In other words, the ++symbol's value cell does not have any Lisp object in it. If you try to ++evaluate the symbol, you get a @code{void-variable} error rather than ++a value. ++ ++ Note that a value of @code{nil} is not the same as void. The symbol ++@code{nil} is a Lisp object and can be the value of a variable just as any ++other object can be; but it is @emph{a value}. A void variable does not ++have any value. ++ ++ After you have given a variable a value, you can make it void once more ++using @code{makunbound}. ++ ++@defun makunbound symbol ++This function makes the current variable binding of @var{symbol} void. ++Subsequent attempts to use this symbol's value as a variable will signal ++the error @code{void-variable}, unless and until you set it again. ++ ++@code{makunbound} returns @var{symbol}. ++ ++@example ++@group ++(makunbound 'x) ; @r{Make the global value of @code{x} void.} ++ @result{} x ++@end group ++@group ++x ++@error{} Symbol's value as variable is void: x ++@end group ++@end example ++ ++If @var{symbol} is locally bound, @code{makunbound} affects the most ++local existing binding. This is the only way a symbol can have a void ++local binding, since all the constructs that create local bindings ++create them with values. In this case, the voidness lasts at most as ++long as the binding does; when the binding is removed due to exit from ++the construct that made it, the previous local or global binding is ++reexposed as usual, and the variable is no longer void unless the newly ++reexposed binding was void all along. ++ ++@smallexample ++@group ++(setq x 1) ; @r{Put a value in the global binding.} ++ @result{} 1 ++(let ((x 2)) ; @r{Locally bind it.} ++ (makunbound 'x) ; @r{Void the local binding.} ++ x) ++@error{} Symbol's value as variable is void: x ++@end group ++@group ++x ; @r{The global binding is unchanged.} ++ @result{} 1 ++ ++(let ((x 2)) ; @r{Locally bind it.} ++ (let ((x 3)) ; @r{And again.} ++ (makunbound 'x) ; @r{Void the innermost-local binding.} ++ x)) ; @r{And refer: it's void.} ++@error{} Symbol's value as variable is void: x ++@end group ++ ++@group ++(let ((x 2)) ++ (let ((x 3)) ++ (makunbound 'x)) ; @r{Void inner binding, then remove it.} ++ x) ; @r{Now outer @code{let} binding is visible.} ++ @result{} 2 ++@end group ++@end smallexample ++@end defun ++ ++ A variable that has been made void with @code{makunbound} is ++indistinguishable from one that has never received a value and has ++always been void. ++ ++ You can use the function @code{boundp} to test whether a variable is ++currently void. ++ ++@defun boundp variable ++@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void; ++more precisely, if its current binding is not void. It returns ++@code{nil} otherwise. ++ ++@smallexample ++@group ++(boundp 'abracadabra) ; @r{Starts out void.} ++ @result{} nil ++@end group ++@group ++(let ((abracadabra 5)) ; @r{Locally bind it.} ++ (boundp 'abracadabra)) ++ @result{} t ++@end group ++@group ++(boundp 'abracadabra) ; @r{Still globally void.} ++ @result{} nil ++@end group ++@group ++(setq abracadabra 5) ; @r{Make it globally nonvoid.} ++ @result{} 5 ++@end group ++@group ++(boundp 'abracadabra) ++ @result{} t ++@end group ++@end smallexample ++@end defun ++ ++@node Defining Variables ++@section Defining Global Variables ++@cindex variable definition ++ ++ You may announce your intention to use a symbol as a global variable ++with a @dfn{variable definition}: a special form, either @code{defconst} ++or @code{defvar}. ++ ++ In Emacs Lisp, definitions serve three purposes. First, they inform ++people who read the code that certain symbols are @emph{intended} to be ++used a certain way (as variables). Second, they inform the Lisp system ++of these things, supplying a value and documentation. Third, they ++provide information to utilities such as @code{etags} and ++@code{make-docfile}, which create data bases of the functions and ++variables in a program. ++ ++ The difference between @code{defconst} and @code{defvar} is primarily ++a matter of intent, serving to inform human readers of whether the value ++should ever change. Emacs Lisp does not restrict the ways in which a ++variable can be used based on @code{defconst} or @code{defvar} ++declarations. However, it does make a difference for initialization: ++@code{defconst} unconditionally initializes the variable, while ++@code{defvar} initializes it only if it is void. ++ ++@ignore ++ One would expect user option variables to be defined with ++@code{defconst}, since programs do not change them. Unfortunately, this ++has bad results if the definition is in a library that is not preloaded: ++@code{defconst} would override any prior value when the library is ++loaded. Users would like to be able to set user options in their init ++files, and override the default values given in the definitions. For ++this reason, user options must be defined with @code{defvar}. ++@end ignore ++ ++@defspec defvar symbol [value [doc-string]] ++This special form defines @var{symbol} as a variable and can also ++initialize and document it. The definition informs a person reading ++your code that @var{symbol} is used as a variable that might be set or ++changed. Note that @var{symbol} is not evaluated; the symbol to be ++defined must appear explicitly in the @code{defvar}. ++ ++If @var{symbol} is void and @var{value} is specified, @code{defvar} ++evaluates it and sets @var{symbol} to the result. But if @var{symbol} ++already has a value (i.e., it is not void), @var{value} is not even ++evaluated, and @var{symbol}'s value remains unchanged. If @var{value} ++is omitted, the value of @var{symbol} is not changed in any case. ++ ++If @var{symbol} has a buffer-local binding in the current buffer, ++@code{defvar} operates on the default value, which is buffer-independent, ++not the current (buffer-local) binding. It sets the default value if ++the default value is void. @xref{Buffer-Local Variables}. ++ ++When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in ++Emacs Lisp mode (@code{eval-defun}), a special feature of ++@code{eval-defun} arranges to set the variable unconditionally, without ++testing whether its value is void. ++ ++If the @var{doc-string} argument appears, it specifies the documentation ++for the variable. (This opportunity to specify documentation is one of ++the main benefits of defining the variable.) The documentation is ++stored in the symbol's @code{variable-documentation} property. The ++Emacs help functions (@pxref{Documentation}) look for this property. ++ ++If the documentation string begins with the character @samp{*}, Emacs ++allows users to set it interactively using the @code{set-variable} ++command. However, you should nearly always use @code{defcustom} ++instead of @code{defvar} to define such variables, so that users can ++use @kbd{M-x customize} and related commands to set them. In that ++case, it is not necessary to begin the documentation string with ++@samp{*}. @xref{Customization}. ++ ++Here are some examples. This form defines @code{foo} but does not ++initialize it: ++ ++@example ++@group ++(defvar foo) ++ @result{} foo ++@end group ++@end example ++ ++This example initializes the value of @code{bar} to @code{23}, and gives ++it a documentation string: ++ ++@example ++@group ++(defvar bar 23 ++ "The normal weight of a bar.") ++ @result{} bar ++@end group ++@end example ++ ++The following form changes the documentation string for @code{bar}, ++making it a user option, but does not change the value, since @code{bar} ++already has a value. (The addition @code{(1+ nil)} would get an error ++if it were evaluated, but since it is not evaluated, there is no error.) ++ ++@example ++@group ++(defvar bar (1+ nil) ++ "*The normal weight of a bar.") ++ @result{} bar ++@end group ++@group ++bar ++ @result{} 23 ++@end group ++@end example ++ ++Here is an equivalent expression for the @code{defvar} special form: ++ ++@example ++@group ++(defvar @var{symbol} @var{value} @var{doc-string}) ++@equiv{} ++(progn ++ (if (not (boundp '@var{symbol})) ++ (setq @var{symbol} @var{value})) ++ (if '@var{doc-string} ++ (put '@var{symbol} 'variable-documentation '@var{doc-string})) ++ '@var{symbol}) ++@end group ++@end example ++ ++The @code{defvar} form returns @var{symbol}, but it is normally used ++at top level in a file where its value does not matter. ++@end defspec ++ ++@defspec defconst symbol value [doc-string] ++This special form defines @var{symbol} as a value and initializes it. ++It informs a person reading your code that @var{symbol} has a standard ++global value, established here, that should not be changed by the user ++or by other programs. Note that @var{symbol} is not evaluated; the ++symbol to be defined must appear explicitly in the @code{defconst}. ++ ++@code{defconst} always evaluates @var{value}, and sets the value of ++@var{symbol} to the result. If @var{symbol} does have a buffer-local ++binding in the current buffer, @code{defconst} sets the default value, ++not the buffer-local value. (But you should not be making ++buffer-local bindings for a symbol that is defined with ++@code{defconst}.) ++ ++Here, @code{pi} is a constant that presumably ought not to be changed ++by anyone (attempts by the Indiana State Legislature notwithstanding). ++As the second form illustrates, however, this is only advisory. ++ ++@example ++@group ++(defconst pi 3.1415 "Pi to five places.") ++ @result{} pi ++@end group ++@group ++(setq pi 3) ++ @result{} pi ++@end group ++@group ++pi ++ @result{} 3 ++@end group ++@end example ++@end defspec ++ ++@defun user-variable-p variable ++@cindex user option ++This function returns @code{t} if @var{variable} is a user option---a ++variable intended to be set by the user for customization---and ++@code{nil} otherwise. (Variables other than user options exist for the ++internal purposes of Lisp programs, and users need not know about them.) ++ ++User option variables are distinguished from other variables either ++though being declared using @code{defcustom}@footnote{They may also be ++declared equivalently in @file{cus-start.el}.} or by the first character ++of their @code{variable-documentation} property. If the property exists ++and is a string, and its first character is @samp{*}, then the variable ++is a user option. Aliases of user options are also user options. ++@end defun ++ ++@kindex variable-interactive ++ If a user option variable has a @code{variable-interactive} property, ++the @code{set-variable} command uses that value to control reading the ++new value for the variable. The property's value is used as if it were ++specified in @code{interactive} (@pxref{Using Interactive}). However, ++this feature is largely obsoleted by @code{defcustom} ++(@pxref{Customization}). ++ ++ @strong{Warning:} If the @code{defconst} and @code{defvar} special ++forms are used while the variable has a local binding (made with ++@code{let}, or a function argument), they set the local-binding's ++value; the top-level binding is not changed. This is not what you ++usually want. To prevent it, use these special forms at top level in ++a file, where normally no local binding is in effect, and make sure to ++load the file before making a local binding for the variable. ++ ++@node Tips for Defining ++@section Tips for Defining Variables Robustly ++ ++ When you define a variable whose value is a function, or a list of ++functions, use a name that ends in @samp{-function} or ++@samp{-functions}, respectively. ++ ++ There are several other variable name conventions; ++here is a complete list: ++ ++@table @samp ++@item @dots{}-hook ++The variable is a normal hook (@pxref{Hooks}). ++ ++@item @dots{}-function ++The value is a function. ++ ++@item @dots{}-functions ++The value is a list of functions. ++ ++@item @dots{}-form ++The value is a form (an expression). ++ ++@item @dots{}-forms ++The value is a list of forms (expressions). ++ ++@item @dots{}-predicate ++The value is a predicate---a function of one argument that returns ++non-@code{nil} for ``good'' arguments and @code{nil} for ``bad'' ++arguments. ++ ++@item @dots{}-flag ++The value is significant only as to whether it is @code{nil} or not. ++Since such variables often end up acquiring more values over time, ++this convention is not strongly recommended. ++ ++@item @dots{}-program ++The value is a program name. ++ ++@item @dots{}-command ++The value is a whole shell command. ++ ++@item @dots{}-switches ++The value specifies options for a command. ++@end table ++ ++ When you define a variable, always consider whether you should mark ++it as ``safe'' or ``risky''; see @ref{File Local Variables}. ++ ++ When defining and initializing a variable that holds a complicated ++value (such as a keymap with bindings in it), it's best to put the ++entire computation of the value into the @code{defvar}, like this: ++ ++@example ++(defvar my-mode-map ++ (let ((map (make-sparse-keymap))) ++ (define-key map "\C-c\C-a" 'my-command) ++ @dots{} ++ map) ++ @var{docstring}) ++@end example ++ ++@noindent ++This method has several benefits. First, if the user quits while ++loading the file, the variable is either still uninitialized or ++initialized properly, never in-between. If it is still uninitialized, ++reloading the file will initialize it properly. Second, reloading the ++file once the variable is initialized will not alter it; that is ++important if the user has run hooks to alter part of the contents (such ++as, to rebind keys). Third, evaluating the @code{defvar} form with ++@kbd{C-M-x} @emph{will} reinitialize the map completely. ++ ++ Putting so much code in the @code{defvar} form has one disadvantage: ++it puts the documentation string far away from the line which names the ++variable. Here's a safe way to avoid that: ++ ++@example ++(defvar my-mode-map nil ++ @var{docstring}) ++(unless my-mode-map ++ (let ((map (make-sparse-keymap))) ++ (define-key map "\C-c\C-a" 'my-command) ++ @dots{} ++ (setq my-mode-map map))) ++@end example ++ ++@noindent ++This has all the same advantages as putting the initialization inside ++the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on ++each form, if you do want to reinitialize the variable. ++ ++ But be careful not to write the code like this: ++ ++@example ++(defvar my-mode-map nil ++ @var{docstring}) ++(unless my-mode-map ++ (setq my-mode-map (make-sparse-keymap)) ++ (define-key my-mode-map "\C-c\C-a" 'my-command) ++ @dots{}) ++@end example ++ ++@noindent ++This code sets the variable, then alters it, but it does so in more than ++one step. If the user quits just after the @code{setq}, that leaves the ++variable neither correctly initialized nor void nor @code{nil}. Once ++that happens, reloading the file will not initialize the variable; it ++will remain incomplete. ++ ++@node Accessing Variables ++@section Accessing Variable Values ++ ++ The usual way to reference a variable is to write the symbol which ++names it (@pxref{Symbol Forms}). This requires you to specify the ++variable name when you write the program. Usually that is exactly what ++you want to do. Occasionally you need to choose at run time which ++variable to reference; then you can use @code{symbol-value}. ++ ++@defun symbol-value symbol ++This function returns the value of @var{symbol}. This is the value in ++the innermost local binding of the symbol, or its global value if it ++has no local bindings. ++ ++@example ++@group ++(setq abracadabra 5) ++ @result{} 5 ++@end group ++@group ++(setq foo 9) ++ @result{} 9 ++@end group ++ ++@group ++;; @r{Here the symbol @code{abracadabra}} ++;; @r{is the symbol whose value is examined.} ++(let ((abracadabra 'foo)) ++ (symbol-value 'abracadabra)) ++ @result{} foo ++@end group ++ ++@group ++;; @r{Here, the value of @code{abracadabra},} ++;; @r{which is @code{foo},} ++;; @r{is the symbol whose value is examined.} ++(let ((abracadabra 'foo)) ++ (symbol-value abracadabra)) ++ @result{} 9 ++@end group ++ ++@group ++(symbol-value 'abracadabra) ++ @result{} 5 ++@end group ++@end example ++ ++A @code{void-variable} error is signaled if the current binding of ++@var{symbol} is void. ++@end defun ++ ++@node Setting Variables ++@section How to Alter a Variable Value ++ ++ The usual way to change the value of a variable is with the special ++form @code{setq}. When you need to compute the choice of variable at ++run time, use the function @code{set}. ++ ++@defspec setq [symbol form]@dots{} ++This special form is the most common method of changing a variable's ++value. Each @var{symbol} is given a new value, which is the result of ++evaluating the corresponding @var{form}. The most-local existing ++binding of the symbol is changed. ++ ++@code{setq} does not evaluate @var{symbol}; it sets the symbol that you ++write. We say that this argument is @dfn{automatically quoted}. The ++@samp{q} in @code{setq} stands for ``quoted.'' ++ ++The value of the @code{setq} form is the value of the last @var{form}. ++ ++@example ++@group ++(setq x (1+ 2)) ++ @result{} 3 ++@end group ++x ; @r{@code{x} now has a global value.} ++ @result{} 3 ++@group ++(let ((x 5)) ++ (setq x 6) ; @r{The local binding of @code{x} is set.} ++ x) ++ @result{} 6 ++@end group ++x ; @r{The global value is unchanged.} ++ @result{} 3 ++@end example ++ ++Note that the first @var{form} is evaluated, then the first ++@var{symbol} is set, then the second @var{form} is evaluated, then the ++second @var{symbol} is set, and so on: ++ ++@example ++@group ++(setq x 10 ; @r{Notice that @code{x} is set before} ++ y (1+ x)) ; @r{the value of @code{y} is computed.} ++ @result{} 11 ++@end group ++@end example ++@end defspec ++ ++@defun set symbol value ++This function sets @var{symbol}'s value to @var{value}, then returns ++@var{value}. Since @code{set} is a function, the expression written for ++@var{symbol} is evaluated to obtain the symbol to set. ++ ++The most-local existing binding of the variable is the binding that is ++set; shadowed bindings are not affected. ++ ++@example ++@group ++(set one 1) ++@error{} Symbol's value as variable is void: one ++@end group ++@group ++(set 'one 1) ++ @result{} 1 ++@end group ++@group ++(set 'two 'one) ++ @result{} one ++@end group ++@group ++(set two 2) ; @r{@code{two} evaluates to symbol @code{one}.} ++ @result{} 2 ++@end group ++@group ++one ; @r{So it is @code{one} that was set.} ++ @result{} 2 ++(let ((one 1)) ; @r{This binding of @code{one} is set,} ++ (set 'one 3) ; @r{not the global value.} ++ one) ++ @result{} 3 ++@end group ++@group ++one ++ @result{} 2 ++@end group ++@end example ++ ++If @var{symbol} is not actually a symbol, a @code{wrong-type-argument} ++error is signaled. ++ ++@example ++(set '(x y) 'z) ++@error{} Wrong type argument: symbolp, (x y) ++@end example ++ ++Logically speaking, @code{set} is a more fundamental primitive than ++@code{setq}. Any use of @code{setq} can be trivially rewritten to use ++@code{set}; @code{setq} could even be defined as a macro, given the ++availability of @code{set}. However, @code{set} itself is rarely used; ++beginners hardly need to know about it. It is useful only for choosing ++at run time which variable to set. For example, the command ++@code{set-variable}, which reads a variable name from the user and then ++sets the variable, needs to use @code{set}. ++ ++@cindex CL note---@code{set} local ++@quotation ++@b{Common Lisp note:} In Common Lisp, @code{set} always changes the ++symbol's ``special'' or dynamic value, ignoring any lexical bindings. ++In Emacs Lisp, all variables and all bindings are dynamic, so @code{set} ++always affects the most local existing binding. ++@end quotation ++@end defun ++ ++@node Variable Scoping ++@section Scoping Rules for Variable Bindings ++ ++ A given symbol @code{foo} can have several local variable bindings, ++established at different places in the Lisp program, as well as a global ++binding. The most recently established binding takes precedence over ++the others. ++ ++@cindex scope ++@cindex extent ++@cindex dynamic scoping ++@cindex lexical scoping ++ Local bindings in Emacs Lisp have @dfn{indefinite scope} and ++@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in ++the source code the binding can be accessed. ``Indefinite scope'' means ++that any part of the program can potentially access the variable ++binding. @dfn{Extent} refers to @emph{when}, as the program is ++executing, the binding exists. ``Dynamic extent'' means that the binding ++lasts as long as the activation of the construct that established it. ++ ++ The combination of dynamic extent and indefinite scope is called ++@dfn{dynamic scoping}. By contrast, most programming languages use ++@dfn{lexical scoping}, in which references to a local variable must be ++located textually within the function or block that binds the variable. ++ ++@cindex CL note---special variables ++@quotation ++@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are ++dynamically scoped, like all variables in Emacs Lisp. ++@end quotation ++ ++@menu ++* Scope:: Scope means where in the program a value is visible. ++ Comparison with other languages. ++* Extent:: Extent means how long in time a value exists. ++* Impl of Scope:: Two ways to implement dynamic scoping. ++* Using Scoping:: How to use dynamic scoping carefully and avoid problems. ++@end menu ++ ++@node Scope ++@subsection Scope ++ ++ Emacs Lisp uses @dfn{indefinite scope} for local variable bindings. ++This means that any function anywhere in the program text might access a ++given binding of a variable. Consider the following function ++definitions: ++ ++@example ++@group ++(defun binder (x) ; @r{@code{x} is bound in @code{binder}.} ++ (foo 5)) ; @r{@code{foo} is some other function.} ++@end group ++ ++@group ++(defun user () ; @r{@code{x} is used ``free'' in @code{user}.} ++ (list x)) ++@end group ++@end example ++ ++ In a lexically scoped language, the binding of @code{x} in ++@code{binder} would never be accessible in @code{user}, because ++@code{user} is not textually contained within the function ++@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user} ++may or may not refer to the binding of @code{x} established in ++@code{binder}, depending on the circumstances: ++ ++@itemize @bullet ++@item ++If we call @code{user} directly without calling @code{binder} at all, ++then whatever binding of @code{x} is found, it cannot come from ++@code{binder}. ++ ++@item ++If we define @code{foo} as follows and then call @code{binder}, then the ++binding made in @code{binder} will be seen in @code{user}: ++ ++@example ++@group ++(defun foo (lose) ++ (user)) ++@end group ++@end example ++ ++@item ++However, if we define @code{foo} as follows and then call @code{binder}, ++then the binding made in @code{binder} @emph{will not} be seen in ++@code{user}: ++ ++@example ++(defun foo (x) ++ (user)) ++@end example ++ ++@noindent ++Here, when @code{foo} is called by @code{binder}, it binds @code{x}. ++(The binding in @code{foo} is said to @dfn{shadow} the one made in ++@code{binder}.) Therefore, @code{user} will access the @code{x} bound ++by @code{foo} instead of the one bound by @code{binder}. ++@end itemize ++ ++Emacs Lisp uses dynamic scoping because simple implementations of ++lexical scoping are slow. In addition, every Lisp system needs to offer ++dynamic scoping at least as an option; if lexical scoping is the norm, ++there must be a way to specify dynamic scoping instead for a particular ++variable. It might not be a bad thing for Emacs to offer both, but ++implementing it with dynamic scoping only was much easier. ++ ++@node Extent ++@subsection Extent ++ ++ @dfn{Extent} refers to the time during program execution that a ++variable name is valid. In Emacs Lisp, a variable is valid only while ++the form that bound it is executing. This is called @dfn{dynamic ++extent}. ``Local'' or ``automatic'' variables in most languages, ++including C and Pascal, have dynamic extent. ++ ++ One alternative to dynamic extent is @dfn{indefinite extent}. This ++means that a variable binding can live on past the exit from the form ++that made the binding. Common Lisp and Scheme, for example, support ++this, but Emacs Lisp does not. ++ ++ To illustrate this, the function below, @code{make-add}, returns a ++function that purports to add @var{n} to its own argument @var{m}. This ++would work in Common Lisp, but it does not do the job in Emacs Lisp, ++because after the call to @code{make-add} exits, the variable @code{n} ++is no longer bound to the actual argument 2. ++ ++@example ++(defun make-add (n) ++ (function (lambda (m) (+ n m)))) ; @r{Return a function.} ++ @result{} make-add ++(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}} ++ ; @r{with @code{(make-add 2)}.} ++ @result{} (lambda (m) (+ n m)) ++(add2 4) ; @r{Try to add 2 to 4.} ++@error{} Symbol's value as variable is void: n ++@end example ++ ++@cindex closures not available ++ Some Lisp dialects have ``closures,'' objects that are like functions ++but record additional variable bindings. Emacs Lisp does not have ++closures. ++ ++@node Impl of Scope ++@subsection Implementation of Dynamic Scoping ++@cindex deep binding ++ ++ A simple sample implementation (which is not how Emacs Lisp actually ++works) may help you understand dynamic binding. This technique is ++called @dfn{deep binding} and was used in early Lisp systems. ++ ++ Suppose there is a stack of bindings, which are variable-value pairs. ++At entry to a function or to a @code{let} form, we can push bindings ++onto the stack for the arguments or local variables created there. We ++can pop those bindings from the stack at exit from the binding ++construct. ++ ++ We can find the value of a variable by searching the stack from top to ++bottom for a binding for that variable; the value from that binding is ++the value of the variable. To set the variable, we search for the ++current binding, then store the new value into that binding. ++ ++ As you can see, a function's bindings remain in effect as long as it ++continues execution, even during its calls to other functions. That is ++why we say the extent of the binding is dynamic. And any other function ++can refer to the bindings, if it uses the same variables while the ++bindings are in effect. That is why we say the scope is indefinite. ++ ++@cindex shallow binding ++ The actual implementation of variable scoping in GNU Emacs Lisp uses a ++technique called @dfn{shallow binding}. Each variable has a standard ++place in which its current value is always found---the value cell of the ++symbol. ++ ++ In shallow binding, setting the variable works by storing a value in ++the value cell. Creating a new binding works by pushing the old value ++(belonging to a previous binding) onto a stack, and storing the new ++local value in the value cell. Eliminating a binding works by popping ++the old value off the stack, into the value cell. ++ ++ We use shallow binding because it has the same results as deep ++binding, but runs faster, since there is never a need to search for a ++binding. ++ ++@node Using Scoping ++@subsection Proper Use of Dynamic Scoping ++ ++ Binding a variable in one function and using it in another is a ++powerful technique, but if used without restraint, it can make programs ++hard to understand. There are two clean ways to use this technique: ++ ++@itemize @bullet ++@item ++Use or bind the variable only in a few related functions, written close ++together in one file. Such a variable is used for communication within ++one program. ++ ++You should write comments to inform other programmers that they can see ++all uses of the variable before them, and to advise them not to add uses ++elsewhere. ++ ++@item ++Give the variable a well-defined, documented meaning, and make all ++appropriate functions refer to it (but not bind it or set it) wherever ++that meaning is relevant. For example, the variable ++@code{case-fold-search} is defined as ``non-@code{nil} means ignore case ++when searching''; various search and replace functions refer to it ++directly or through their subroutines, but do not bind or set it. ++ ++Then you can bind the variable in other programs, knowing reliably what ++the effect will be. ++@end itemize ++ ++ In either case, you should define the variable with @code{defvar}. ++This helps other people understand your program by telling them to look ++for inter-function usage. It also avoids a warning from the byte ++compiler. Choose the variable's name to avoid name conflicts---don't ++use short names like @code{x}. ++ ++@node Buffer-Local Variables ++@section Buffer-Local Variables ++@cindex variable, buffer-local ++@cindex buffer-local variables ++ ++ Global and local variable bindings are found in most programming ++languages in one form or another. Emacs, however, also supports ++additional, unusual kinds of variable binding, such as ++@dfn{buffer-local} bindings, which apply only in one buffer. Having ++different values for a variable in different buffers is an important ++customization method. (Variables can also have bindings that are ++local to each terminal, or to each frame. @xref{Multiple Terminals}, ++and @xref{Frame-Local Variables}.) ++ ++@menu ++* Intro to Buffer-Local:: Introduction and concepts. ++* Creating Buffer-Local:: Creating and destroying buffer-local bindings. ++* Default Value:: The default value is seen in buffers ++ that don't have their own buffer-local values. ++@end menu ++ ++@node Intro to Buffer-Local ++@subsection Introduction to Buffer-Local Variables ++ ++ A buffer-local variable has a buffer-local binding associated with a ++particular buffer. The binding is in effect when that buffer is ++current; otherwise, it is not in effect. If you set the variable while ++a buffer-local binding is in effect, the new value goes in that binding, ++so its other bindings are unchanged. This means that the change is ++visible only in the buffer where you made it. ++ ++ The variable's ordinary binding, which is not associated with any ++specific buffer, is called the @dfn{default binding}. In most cases, ++this is the global binding. ++ ++ A variable can have buffer-local bindings in some buffers but not in ++other buffers. The default binding is shared by all the buffers that ++don't have their own bindings for the variable. (This includes all ++newly-created buffers.) If you set the variable in a buffer that does ++not have a buffer-local binding for it, this sets the default binding, ++so the new value is visible in all the buffers that see the default ++binding. ++ ++ The most common use of buffer-local bindings is for major modes to change ++variables that control the behavior of commands. For example, C mode and ++Lisp mode both set the variable @code{paragraph-start} to specify that only ++blank lines separate paragraphs. They do this by making the variable ++buffer-local in the buffer that is being put into C mode or Lisp mode, and ++then setting it to the new value for that mode. @xref{Major Modes}. ++ ++ The usual way to make a buffer-local binding is with ++@code{make-local-variable}, which is what major mode commands typically ++use. This affects just the current buffer; all other buffers (including ++those yet to be created) will continue to share the default value unless ++they are explicitly given their own buffer-local bindings. ++ ++@cindex automatically buffer-local ++ A more powerful operation is to mark the variable as ++@dfn{automatically buffer-local} by calling ++@code{make-variable-buffer-local}. You can think of this as making the ++variable local in all buffers, even those yet to be created. More ++precisely, the effect is that setting the variable automatically makes ++the variable local to the current buffer if it is not already so. All ++buffers start out by sharing the default value of the variable as usual, ++but setting the variable creates a buffer-local binding for the current ++buffer. The new value is stored in the buffer-local binding, leaving ++the default binding untouched. This means that the default value cannot ++be changed with @code{setq} in any buffer; the only way to change it is ++with @code{setq-default}. ++ ++ @strong{Warning:} When a variable has buffer-local ++bindings in one or more buffers, @code{let} rebinds the binding that's ++currently in effect. For instance, if the current buffer has a ++buffer-local value, @code{let} temporarily rebinds that. If no ++buffer-local bindings are in effect, @code{let} rebinds ++the default value. If inside the @code{let} you then change to a ++different current buffer in which a different binding is in effect, ++you won't see the @code{let} binding any more. And if you exit the ++@code{let} while still in the other buffer, you won't see the ++unbinding occur (though it will occur properly). Here is an example ++to illustrate: ++ ++@example ++@group ++(setq foo 'g) ++(set-buffer "a") ++(make-local-variable 'foo) ++@end group ++(setq foo 'a) ++(let ((foo 'temp)) ++ ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}} ++ (set-buffer "b") ++ ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}} ++ @var{body}@dots{}) ++@group ++foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},} ++ ; @r{but we don't see that in buffer @samp{b}} ++@end group ++@group ++(set-buffer "a") ; @r{verify the local value was restored} ++foo @result{} 'a ++@end group ++@end example ++ ++ Note that references to @code{foo} in @var{body} access the ++buffer-local binding of buffer @samp{b}. ++ ++ When a file specifies local variable values, these become buffer-local ++values when you visit the file. @xref{File Variables,,, emacs, The ++GNU Emacs Manual}. ++ ++ A buffer-local variable cannot be made frame-local ++(@pxref{Frame-Local Variables}) or terminal-local (@pxref{Multiple ++Terminals}). ++ ++@node Creating Buffer-Local ++@subsection Creating and Deleting Buffer-Local Bindings ++ ++@deffn Command make-local-variable variable ++This function creates a buffer-local binding in the current buffer for ++@var{variable} (a symbol). Other buffers are not affected. The value ++returned is @var{variable}. ++ ++The buffer-local value of @var{variable} starts out as the same value ++@var{variable} previously had. If @var{variable} was void, it remains ++void. ++ ++@example ++@group ++;; @r{In buffer @samp{b1}:} ++(setq foo 5) ; @r{Affects all buffers.} ++ @result{} 5 ++@end group ++@group ++(make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.} ++ @result{} foo ++@end group ++@group ++foo ; @r{That did not change} ++ @result{} 5 ; @r{the value.} ++@end group ++@group ++(setq foo 6) ; @r{Change the value} ++ @result{} 6 ; @r{in @samp{b1}.} ++@end group ++@group ++foo ++ @result{} 6 ++@end group ++ ++@group ++;; @r{In buffer @samp{b2}, the value hasn't changed.} ++(save-excursion ++ (set-buffer "b2") ++ foo) ++ @result{} 5 ++@end group ++@end example ++ ++Making a variable buffer-local within a @code{let}-binding for that ++variable does not work reliably, unless the buffer in which you do this ++is not current either on entry to or exit from the @code{let}. This is ++because @code{let} does not distinguish between different kinds of ++bindings; it knows only which variable the binding was made for. ++ ++If the variable is terminal-local (@pxref{Multiple Terminals}), or ++frame-local (@pxref{Frame-Local Variables}), this function signals an ++error. Such variables cannot have buffer-local bindings as well. ++ ++@strong{Warning:} do not use @code{make-local-variable} for a hook ++variable. The hook variables are automatically made buffer-local as ++needed if you use the @var{local} argument to @code{add-hook} or ++@code{remove-hook}. ++@end deffn ++ ++@deffn Command make-variable-buffer-local variable ++This function marks @var{variable} (a symbol) automatically ++buffer-local, so that any subsequent attempt to set it will make it ++local to the current buffer at the time. ++ ++A peculiar wrinkle of this feature is that binding the variable (with ++@code{let} or other binding constructs) does not create a buffer-local ++binding for it. Only setting the variable (with @code{set} or ++@code{setq}), while the variable does not have a @code{let}-style ++binding that was made in the current buffer, does so. ++ ++If @var{variable} does not have a default value, then calling this ++command will give it a default value of @code{nil}. If @var{variable} ++already has a default value, that value remains unchanged. ++Subsequently calling @code{makunbound} on @var{variable} will result ++in a void buffer-local value and leave the default value unaffected. ++ ++The value returned is @var{variable}. ++ ++@strong{Warning:} Don't assume that you should use ++@code{make-variable-buffer-local} for user-option variables, simply ++because users @emph{might} want to customize them differently in ++different buffers. Users can make any variable local, when they wish ++to. It is better to leave the choice to them. ++ ++The time to use @code{make-variable-buffer-local} is when it is crucial ++that no two buffers ever share the same binding. For example, when a ++variable is used for internal purposes in a Lisp program which depends ++on having separate values in separate buffers, then using ++@code{make-variable-buffer-local} can be the best solution. ++@end deffn ++ ++@defun local-variable-p variable &optional buffer ++This returns @code{t} if @var{variable} is buffer-local in buffer ++@var{buffer} (which defaults to the current buffer); otherwise, ++@code{nil}. ++@end defun ++ ++@defun local-variable-if-set-p variable &optional buffer ++This returns @code{t} if @var{variable} will become buffer-local in ++buffer @var{buffer} (which defaults to the current buffer) if it is ++set there. ++@end defun ++ ++@defun buffer-local-value variable buffer ++This function returns the buffer-local binding of @var{variable} (a ++symbol) in buffer @var{buffer}. If @var{variable} does not have a ++buffer-local binding in buffer @var{buffer}, it returns the default ++value (@pxref{Default Value}) of @var{variable} instead. ++@end defun ++ ++@defun buffer-local-variables &optional buffer ++This function returns a list describing the buffer-local variables in ++buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is ++used.) It returns an association list (@pxref{Association Lists}) in ++which each element contains one buffer-local variable and its value. ++However, when a variable's buffer-local binding in @var{buffer} is void, ++then the variable appears directly in the resulting list. ++ ++@example ++@group ++(make-local-variable 'foobar) ++(makunbound 'foobar) ++(make-local-variable 'bind-me) ++(setq bind-me 69) ++@end group ++(setq lcl (buffer-local-variables)) ++ ;; @r{First, built-in variables local in all buffers:} ++@result{} ((mark-active . nil) ++ (buffer-undo-list . nil) ++ (mode-name . "Fundamental") ++ @dots{} ++@group ++ ;; @r{Next, non-built-in buffer-local variables.} ++ ;; @r{This one is buffer-local and void:} ++ foobar ++ ;; @r{This one is buffer-local and nonvoid:} ++ (bind-me . 69)) ++@end group ++@end example ++ ++Note that storing new values into the @sc{cdr}s of cons cells in this ++list does @emph{not} change the buffer-local values of the variables. ++@end defun ++ ++@deffn Command kill-local-variable variable ++This function deletes the buffer-local binding (if any) for ++@var{variable} (a symbol) in the current buffer. As a result, the ++default binding of @var{variable} becomes visible in this buffer. This ++typically results in a change in the value of @var{variable}, since the ++default value is usually different from the buffer-local value just ++eliminated. ++ ++If you kill the buffer-local binding of a variable that automatically ++becomes buffer-local when set, this makes the default value visible in ++the current buffer. However, if you set the variable again, that will ++once again create a buffer-local binding for it. ++ ++@code{kill-local-variable} returns @var{variable}. ++ ++This function is a command because it is sometimes useful to kill one ++buffer-local variable interactively, just as it is useful to create ++buffer-local variables interactively. ++@end deffn ++ ++@defun kill-all-local-variables ++This function eliminates all the buffer-local variable bindings of the ++current buffer except for variables marked as ``permanent'' and local ++hook functions that have a non-@code{nil} @code{permanent-local-hook} ++property (@pxref{Setting Hooks}). As a result, the buffer will see ++the default values of most variables. ++ ++This function also resets certain other information pertaining to the ++buffer: it sets the local keymap to @code{nil}, the syntax table to the ++value of @code{(standard-syntax-table)}, the case table to ++@code{(standard-case-table)}, and the abbrev table to the value of ++@code{fundamental-mode-abbrev-table}. ++ ++The very first thing this function does is run the normal hook ++@code{change-major-mode-hook} (see below). ++ ++Every major mode command begins by calling this function, which has the ++effect of switching to Fundamental mode and erasing most of the effects ++of the previous major mode. To ensure that this does its job, the ++variables that major modes set should not be marked permanent. ++ ++@code{kill-all-local-variables} returns @code{nil}. ++@end defun ++ ++@defvar change-major-mode-hook ++The function @code{kill-all-local-variables} runs this normal hook ++before it does anything else. This gives major modes a way to arrange ++for something special to be done if the user switches to a different ++major mode. It is also useful for buffer-specific minor modes ++that should be forgotten if the user changes the major mode. ++ ++For best results, make this variable buffer-local, so that it will ++disappear after doing its job and will not interfere with the ++subsequent major mode. @xref{Hooks}. ++@end defvar ++ ++@c Emacs 19 feature ++@cindex permanent local variable ++A buffer-local variable is @dfn{permanent} if the variable name (a ++symbol) has a @code{permanent-local} property that is non-@code{nil}. ++Permanent locals are appropriate for data pertaining to where the file ++came from or how to save it, rather than with how to edit the contents. ++ ++@node Default Value ++@subsection The Default Value of a Buffer-Local Variable ++@cindex default value ++ ++ The global value of a variable with buffer-local bindings is also ++called the @dfn{default} value, because it is the value that is in ++effect whenever neither the current buffer nor the selected frame has ++its own binding for the variable. ++ ++ The functions @code{default-value} and @code{setq-default} access and ++change a variable's default value regardless of whether the current ++buffer has a buffer-local binding. For example, you could use ++@code{setq-default} to change the default setting of ++@code{paragraph-start} for most buffers; and this would work even when ++you are in a C or Lisp mode buffer that has a buffer-local value for ++this variable. ++ ++@c Emacs 19 feature ++ The special forms @code{defvar} and @code{defconst} also set the ++default value (if they set the variable at all), rather than any ++buffer-local value. ++ ++@defun default-value symbol ++This function returns @var{symbol}'s default value. This is the value ++that is seen in buffers and frames that do not have their own values for ++this variable. If @var{symbol} is not buffer-local, this is equivalent ++to @code{symbol-value} (@pxref{Accessing Variables}). ++@end defun ++ ++@c Emacs 19 feature ++@defun default-boundp symbol ++The function @code{default-boundp} tells you whether @var{symbol}'s ++default value is nonvoid. If @code{(default-boundp 'foo)} returns ++@code{nil}, then @code{(default-value 'foo)} would get an error. ++ ++@code{default-boundp} is to @code{default-value} as @code{boundp} is to ++@code{symbol-value}. ++@end defun ++ ++@defspec setq-default [symbol form]@dots{} ++This special form gives each @var{symbol} a new default value, which is ++the result of evaluating the corresponding @var{form}. It does not ++evaluate @var{symbol}, but does evaluate @var{form}. The value of the ++@code{setq-default} form is the value of the last @var{form}. ++ ++If a @var{symbol} is not buffer-local for the current buffer, and is not ++marked automatically buffer-local, @code{setq-default} has the same ++effect as @code{setq}. If @var{symbol} is buffer-local for the current ++buffer, then this changes the value that other buffers will see (as long ++as they don't have a buffer-local value), but not the value that the ++current buffer sees. ++ ++@example ++@group ++;; @r{In buffer @samp{foo}:} ++(make-local-variable 'buffer-local) ++ @result{} buffer-local ++@end group ++@group ++(setq buffer-local 'value-in-foo) ++ @result{} value-in-foo ++@end group ++@group ++(setq-default buffer-local 'new-default) ++ @result{} new-default ++@end group ++@group ++buffer-local ++ @result{} value-in-foo ++@end group ++@group ++(default-value 'buffer-local) ++ @result{} new-default ++@end group ++ ++@group ++;; @r{In (the new) buffer @samp{bar}:} ++buffer-local ++ @result{} new-default ++@end group ++@group ++(default-value 'buffer-local) ++ @result{} new-default ++@end group ++@group ++(setq buffer-local 'another-default) ++ @result{} another-default ++@end group ++@group ++(default-value 'buffer-local) ++ @result{} another-default ++@end group ++ ++@group ++;; @r{Back in buffer @samp{foo}:} ++buffer-local ++ @result{} value-in-foo ++(default-value 'buffer-local) ++ @result{} another-default ++@end group ++@end example ++@end defspec ++ ++@defun set-default symbol value ++This function is like @code{setq-default}, except that @var{symbol} is ++an ordinary evaluated argument. ++ ++@example ++@group ++(set-default (car '(a b c)) 23) ++ @result{} 23 ++@end group ++@group ++(default-value 'a) ++ @result{} 23 ++@end group ++@end example ++@end defun ++ ++@node File Local Variables ++@section File Local Variables ++@cindex file local variables ++ ++ A file can specify local variable values; Emacs uses these to create ++buffer-local bindings for those variables in the buffer visiting that ++file. @xref{File variables, , Local Variables in Files, emacs, The ++GNU Emacs Manual}, for basic information about file-local variables. ++This section describes the functions and variables that affect how ++file-local variables are processed. ++ ++ If a file-local variable could specify an arbitrary function or Lisp ++expression that would be called later, visiting a file could take over ++your Emacs. Emacs protects against this by automatically setting only ++those file-local variables whose specified values are known to be ++safe. Other file-local variables are set only if the user agrees. ++ ++ For additional safety, @code{read-circle} is temporarily bound to ++@code{nil} when Emacs reads file-local variables (@pxref{Input ++Functions}). This prevents the Lisp reader from recognizing circular ++and shared Lisp structures (@pxref{Circular Objects}). ++ ++@defopt enable-local-variables ++This variable controls whether to process file-local variables. ++The possible values are: ++ ++@table @asis ++@item @code{t} (the default) ++Set the safe variables, and query (once) about any unsafe variables. ++@item @code{:safe} ++Set only the safe variables and do not query. ++@item @code{:all} ++Set all the variables and do not query. ++@item @code{nil} ++Don't set any variables. ++@item anything else ++Query (once) about all the variables. ++@end table ++@end defopt ++ ++@defun hack-local-variables &optional mode-only ++This function parses, and binds or evaluates as appropriate, any local ++variables specified by the contents of the current buffer. The variable ++@code{enable-local-variables} has its effect here. However, this ++function does not look for the @samp{mode:} local variable in the ++@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking ++@code{enable-local-variables} into account (@pxref{Auto Major Mode}). ++ ++This function works by walking the alist stored in ++@code{file-local-variables-alist} and applying each local variable in ++turn. It calls @code{before-hack-local-variables-hook} and ++@code{hack-local-variables-hook} before and after applying the ++variables, respectively. ++ ++If the optional argument @var{mode-only} is non-@code{nil}, then all ++this function does is return @code{t} if the @w{@samp{-*-}} line or ++the local variables list specifies a mode and @code{nil} otherwise. ++It does not set the mode nor any other file-local variable. ++@end defun ++ ++@defvar file-local-variables-alist ++This buffer-local variable holds the alist of file-local variable ++settings. Each element of the alist is of the form ++@w{@code{(@var{var} . @var{value})}}, where @var{var} is a symbol of ++the local variable and @var{value} is its value. When Emacs visits a ++file, it first collects all the file-local variables into this alist, ++and then the @code{hack-local-variables} function applies them one by ++one. ++@end defvar ++ ++@defvar before-hack-local-variables-hook ++Emacs calls this hook immediately before applying file-local variables ++stored in @code{file-local-variables-alist}. ++@end defvar ++ ++@defvar hack-local-variables-hook ++Emacs calls this hook immediately after it finishes applying ++file-local variables stored in @code{file-local-variables-alist}. ++@end defvar ++ ++@cindex safe local variable ++ You can specify safe values for a variable with a ++@code{safe-local-variable} property. The property has to be a ++function of one argument; any value is safe if the function returns ++non-@code{nil} given that value. Many commonly-encountered file ++variables have @code{safe-local-variable} properties; these include ++@code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}. ++For boolean-valued variables that are safe, use @code{booleanp} as the ++property value. Lambda expressions should be quoted so that ++@code{describe-variable} can display the predicate. ++ ++@defopt safe-local-variable-values ++This variable provides another way to mark some variable values as ++safe. It is a list of cons cells @code{(@var{var} . @var{val})}, ++where @var{var} is a variable name and @var{val} is a value which is ++safe for that variable. ++ ++When Emacs asks the user whether or not to obey a set of file-local ++variable specifications, the user can choose to mark them as safe. ++Doing so adds those variable/value pairs to ++@code{safe-local-variable-values}, and saves it to the user's custom ++file. ++@end defopt ++ ++@defun safe-local-variable-p sym val ++This function returns non-@code{nil} if it is safe to give @var{sym} ++the value @var{val}, based on the above criteria. ++@end defun ++ ++@c @cindex risky local variable Duplicates risky-local-variable ++ Some variables are considered @dfn{risky}. A variable whose name ++ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function}, ++@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form}, ++@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist}, ++@samp{-program}, or @samp{-predicate} is considered risky. The ++variables @samp{font-lock-keywords}, @samp{font-lock-keywords} ++followed by a digit, and @samp{font-lock-syntactic-keywords} are also ++considered risky. Finally, any variable whose name has a ++non-@code{nil} @code{risky-local-variable} property is considered ++risky. ++ ++@defun risky-local-variable-p sym ++This function returns non-@code{nil} if @var{sym} is a risky variable, ++based on the above criteria. ++@end defun ++ ++ If a variable is risky, it will not be entered automatically into ++@code{safe-local-variable-values} as described above. Therefore, ++Emacs will always query before setting a risky variable, unless the ++user explicitly allows the setting by customizing ++@code{safe-local-variable-values} directly. ++ ++@defvar ignored-local-variables ++This variable holds a list of variables that should not be given local ++values by files. Any value specified for one of these variables is ++completely ignored. ++@end defvar ++ ++ The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs ++normally asks for confirmation before handling it. ++ ++@defopt enable-local-eval ++This variable controls processing of @samp{Eval:} in @samp{-*-} lines ++or local variables ++lists in files being visited. A value of @code{t} means process them ++unconditionally; @code{nil} means ignore them; anything else means ask ++the user what to do for each file. The default value is @code{maybe}. ++@end defopt ++ ++@defopt safe-local-eval-forms ++This variable holds a list of expressions that are safe to ++evaluate when found in the @samp{Eval:} ``variable'' in a file ++local variables list. ++@end defopt ++ ++ If the expression is a function call and the function has a ++@code{safe-local-eval-function} property, the property value ++determines whether the expression is safe to evaluate. The property ++value can be a predicate to call to test the expression, a list of ++such predicates (it's safe if any predicate succeeds), or @code{t} ++(always safe provided the arguments are constant). ++ ++ Text properties are also potential loopholes, since their values ++could include functions to call. So Emacs discards all text ++properties from string values specified for file-local variables. ++ ++@node Directory Local Variables ++@section Directory Local Variables ++@cindex directory local variables ++ ++ A directory can specify local variable values common to all files in ++that directory; Emacs uses these to create buffer-local bindings for ++those variables in buffers visiting any file in that directory. This ++is useful when the files in the directory belong to some @dfn{project} ++and therefore share the same local variables. ++ ++ There are two different methods for specifying directory local ++variables: by putting them in a special file, or by defining a ++@dfn{project class} for that directory. ++ ++@defvr Constant dir-locals-file ++This constant is the name of the file where Emacs expects to find the ++directory-local variables. The name of the file is ++@file{.dir-locals.el}@footnote{ ++The MS-DOS version of Emacs uses @file{_dir-locals.el} instead, due to ++limitations of the DOS filesystems. ++}. A file by that name in a directory causes Emacs to apply its ++settings to any file in that directory or any of its subdirectories. ++If some of the subdirectories have their own @file{.dir-locals.el} ++files, Emacs uses the settings from the deepest file it finds starting ++from the file's directory and moving up the directory tree. The file ++specifies local variables as a specially formatted list; see ++@ref{Directory Variables, , Per-directory Local Variables, emacs, The ++GNU Emacs Manual}, for more details. ++@end defvr ++ ++@defun hack-dir-local-variables ++This function reads the @code{.dir-locals.el} file and stores the ++directory-local variables in @code{file-local-variables-alist} that is ++local to the buffer visiting any file in the directory, without ++applying them. It also stores the directory-local settings in ++@code{dir-locals-class-alist}, where it defines a special class for ++the directory in which @file{.dir-locals.el} file was found. This ++function works by calling @code{dir-locals-set-class-variables} and ++@code{dir-locals-set-directory-class}, described below. ++@end defun ++ ++@defun dir-locals-set-class-variables class variables ++This function defines a set of variable settings for the named ++@var{class}, which is a symbol. You can later assign the class to one ++or more directories, and Emacs will apply those variable settings to ++all files in those directories. The list in @var{variables} can be of ++one of the two forms: @code{(@var{major-mode} . @var{alist})} or ++@code{(@var{directory} . @var{list})}. With the first form, if the ++file's buffer turns on a mode that is derived from @var{major-mode}, ++then the all the variables in the associated @var{alist} are applied; ++@var{alist} should be of the form @code{(@var{name} . @var{value})}. ++A special value @code{nil} for @var{major-mode} means the settings are ++applicable to any mode. ++ ++With the second form of @var{variables}, if @var{directory} is the ++initial substring of the file's directory, then @var{list} is applied ++recursively by following the above rules; @var{list} should be of one ++of the two forms accepted by this function in @var{variables}. ++@end defun ++ ++@defun dir-locals-set-directory-class directory class ++This function assigns @var{class} to all the files in @code{directory} ++and its subdirectories. Thereafter, all the variable settings ++specified for @var{class} will be applied to any visited file in ++@var{directory} and its children. @var{class} must have been already ++defined by @code{dir-locals-set-class-variables} ++@end defun ++ ++@defvar dir-locals-class-alist ++This alist holds the class symbols and the associated variable ++settings. It is updated by @code{dir-locals-set-class-variables}. ++@end defvar ++ ++@defvar dir-locals-directory-cache ++This alist holds directory names, their assigned class names, and ++modification times of the associated directory local variables file. ++It is updated by @code{dir-locals-set-directory-class}. ++@end defvar ++ ++@node Frame-Local Variables ++@section Frame-Local Values for Variables ++@cindex frame-local variables ++ ++ In addition to buffer-local variable bindings (@pxref{Buffer-Local ++Variables}), Emacs supports @dfn{frame-local} bindings. A frame-local ++binding for a variable is in effect in a frame for which it was ++defined. ++ ++ In practice, frame-local variables have not proven very useful. ++Ordinary frame parameters are generally used instead (@pxref{Frame ++Parameters}). The function @code{make-variable-frame-local}, which ++was used to define frame-local variables, has been deprecated since ++Emacs 22.2. However, you can still define a frame-specific binding ++for a variable @var{var} in frame @var{frame}, by setting the ++@var{var} frame parameter for that frame: ++ ++@lisp ++ (modify-frame-parameters @var{frame} '((@var{var} . @var{value}))) ++@end lisp ++ ++@noindent ++This causes the variable @var{var} to be bound to the specified ++@var{value} in the named @var{frame}. To check the frame-specific ++values of such variables, use @code{frame-parameter}. @xref{Parameter ++Access}. ++ ++ Note that you cannot have a frame-local binding for a variable that ++has a buffer-local binding. ++ ++@node Variable Aliases ++@section Variable Aliases ++@cindex variable aliases ++ ++ It is sometimes useful to make two variables synonyms, so that both ++variables always have the same value, and changing either one also ++changes the other. Whenever you change the name of a ++variable---either because you realize its old name was not well ++chosen, or because its meaning has partly changed---it can be useful ++to keep the old name as an @emph{alias} of the new one for ++compatibility. You can do this with @code{defvaralias}. ++ ++@defun defvaralias new-alias base-variable &optional docstring ++This function defines the symbol @var{new-alias} as a variable alias ++for symbol @var{base-variable}. This means that retrieving the value ++of @var{new-alias} returns the value of @var{base-variable}, and ++changing the value of @var{new-alias} changes the value of ++@var{base-variable}. The two aliased variable names always share the ++same value and the same bindings. ++ ++If the @var{docstring} argument is non-@code{nil}, it specifies the ++documentation for @var{new-alias}; otherwise, the alias gets the same ++documentation as @var{base-variable} has, if any, unless ++@var{base-variable} is itself an alias, in which case @var{new-alias} gets ++the documentation of the variable at the end of the chain of aliases. ++ ++This function returns @var{base-variable}. ++@end defun ++ ++ Variable aliases are convenient for replacing an old name for a ++variable with a new name. @code{make-obsolete-variable} declares that ++the old name is obsolete and therefore that it may be removed at some ++stage in the future. ++ ++@defun make-obsolete-variable obsolete-name current-name &optional when ++This function makes the byte compiler warn that the variable ++@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, it is ++the variable's new name; then the warning message says to use ++@var{current-name} instead of @var{obsolete-name}. If @var{current-name} ++is a string, this is the message and there is no replacement variable. ++ ++If provided, @var{when} should be a string indicating when the ++variable was first made obsolete---for example, a date or a release ++number. ++@end defun ++ ++ You can make two variables synonyms and declare one obsolete at the ++same time using the macro @code{define-obsolete-variable-alias}. ++ ++@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring ++This macro marks the variable @var{obsolete-name} as obsolete and also ++makes it an alias for the variable @var{current-name}. It is ++equivalent to the following: ++ ++@example ++(defvaralias @var{obsolete-name} @var{current-name} @var{docstring}) ++(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when}) ++@end example ++@end defmac ++ ++@defun indirect-variable variable ++This function returns the variable at the end of the chain of aliases ++of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is ++not defined as an alias, the function returns @var{variable}. ++ ++This function signals a @code{cyclic-variable-indirection} error if ++there is a loop in the chain of symbols. ++@end defun ++ ++@example ++(defvaralias 'foo 'bar) ++(indirect-variable 'foo) ++ @result{} bar ++(indirect-variable 'bar) ++ @result{} bar ++(setq bar 2) ++bar ++ @result{} 2 ++@group ++foo ++ @result{} 2 ++@end group ++(setq foo 0) ++bar ++ @result{} 0 ++foo ++ @result{} 0 ++@end example ++ ++@node Variables with Restricted Values ++@section Variables with Restricted Values ++ ++ Ordinary Lisp variables can be assigned any value that is a valid ++Lisp object. However, certain Lisp variables are not defined in Lisp, ++but in C. Most of these variables are defined in the C code using ++@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on ++any value. However, some variables are defined using ++@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp ++variables in C,, Writing Emacs Primitives}, in particular the ++description of functions of the type @code{syms_of_@var{filename}}, ++for a brief discussion of the C implementation. ++ ++ Variables of type @code{DEFVAR_BOOL} can only take on the values ++@code{nil} or @code{t}. Attempting to assign them any other value ++will set them to @code{t}: ++ ++@example ++(let ((display-hourglass 5)) ++ display-hourglass) ++ @result{} t ++@end example ++ ++@defvar byte-boolean-vars ++This variable holds a list of all variables of type @code{DEFVAR_BOOL}. ++@end defvar ++ ++ Variables of type @code{DEFVAR_INT} can only take on integer values. ++Attempting to assign them any other value will result in an error: ++ ++@example ++(setq window-min-height 5.0) ++@error{} Wrong type argument: integerp, 5.0 ++@end example ++ ++@ignore ++ arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e ++@end ignore +diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi +new file mode 100644 +index 0000000..4aa5783 +--- /dev/null ++++ b/doc/lispref/vol1.texi +@@ -0,0 +1,1548 @@ ++\input texinfo @c -*-texinfo-*- ++@c This file is used for printing the GNU Emacs Lisp Reference Manual ++@c in two volumes. It is a modified version of elisp.texi. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c %**start of header ++@setfilename elisp ++@settitle GNU Emacs Lisp Reference Manual: Volume 1 ++@c %**end of header ++ ++@c See two-volume-cross-refs.txt. ++@tex ++\message{Formatting for two volume edition...Volume 1...} ++% ++% Read special toc file, set up in two-volume.make. ++\gdef\tocreadfilename{elisp1-toc-ready.toc} ++% ++% Don't make outlines, they're not needed and \readdatafile can't pay ++% attention to the special definition above. ++\global\let\pdfmakeoutlines=\relax ++% ++% Start volume 1 chapter numbering at 1; this must be listed as chapno0. ++\global\chapno=0 ++@end tex ++ ++@c Version of the manual and of Emacs. ++@c Please remember to update the edition number in README as well. ++@set VERSION 3.0 ++@set EMACSVER 23.1 ++@set DATE July 2009 ++ ++@dircategory Emacs ++@direntry ++* Elisp: (elisp). The Emacs Lisp Reference Manual. ++@end direntry ++ ++@c in general, keep the following line commented out, unless doing a ++@c copy of this manual that will be published. the manual should go ++@c onto the distribution in the full, 8.5 x 11" size. ++@set smallbook ++ ++@ifset smallbook ++@smallbook ++@end ifset ++ ++@c per rms and peterb, use 10pt fonts for the main text, mostly to ++@c save on paper cost. ++@c Do this inside @tex for now, so current makeinfo does not complain. ++@tex ++@ifset smallbook ++@fonttextsize 10 ++\global\let\urlcolor=\Black % don't print links in grayscale ++\global\let\linkcolor=\Black ++@end ifset ++\global\hbadness=6666 % don't worry about not-too-underfull boxes ++@end tex ++ ++@c Combine indices. ++@synindex cp fn ++@syncodeindex vr fn ++@syncodeindex ky fn ++@syncodeindex pg fn ++@c We use the "type index" to index new functions and variables. ++@c @syncodeindex tp fn ++ ++@copying ++This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* ++corresponding to Emacs version @value{EMACSVER}. ++ ++Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, ++1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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 the ++Invariant Sections being ``GNU General Public License,'' 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 ++ ++@titlepage ++@title GNU Emacs Lisp Reference Manual ++@subtitle Volume 1 ++@subtitle For Emacs Version @value{EMACSVER} ++@subtitle Revision @value{VERSION}, @value{DATE} ++ ++@author by Bil Lewis, Dan LaLiberte, Richard Stallman ++@author and the GNU Manual Group ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++ ++@sp 2 ++ ++Published by the Free Software Foundation @* ++51 Franklin St, Fifth Floor @* ++Boston, MA 02110-1301 @* ++USA @* ++ISBN 1-882114-74-4 ++ ++@sp 2 ++Cover art by Etienne Suvasa. ++@end titlepage ++ ++ ++@c Print the tables of contents ++@summarycontents ++@contents ++ ++ ++@ifnottex ++@node Top, Introduction, (dir), (dir) ++@top Emacs Lisp ++ ++This Info file contains edition @value{VERSION} of the GNU Emacs Lisp ++Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. ++@end ifnottex ++ ++@menu ++* Introduction:: Introduction and conventions used. ++ ++* Lisp Data Types:: Data types of objects in Emacs Lisp. ++* Numbers:: Numbers and arithmetic functions. ++* Strings and Characters:: Strings, and functions that work on them. ++* Lists:: Lists, cons cells, and related functions. ++* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. ++ Certain functions act on any kind of sequence. ++ The description of vectors is here as well. ++* Hash Tables:: Very fast lookup-tables. ++* Symbols:: Symbols represent names, uniquely. ++ ++* Evaluation:: How Lisp expressions are evaluated. ++* Control Structures:: Conditionals, loops, nonlocal exits. ++* Variables:: Using symbols in programs to stand for values. ++* Functions:: A function is a Lisp program ++ that can be invoked from other functions. ++* Macros:: Macros are a way to extend the Lisp language. ++* Customization:: Writing customization declarations. ++ ++* Loading:: Reading files of Lisp code into Lisp. ++* Byte Compilation:: Compilation makes programs run faster. ++* Advising Functions:: Adding to the definition of a function. ++* Debugging:: Tools and tips for debugging Lisp programs. ++ ++* Read and Print:: Converting Lisp objects to text and back. ++* Minibuffers:: Using the minibuffer to read input. ++* Command Loop:: How the editor command loop works, ++ and how you can call its subroutines. ++* Keymaps:: Defining the bindings from keys to commands. ++* Modes:: Defining major and minor modes. ++* Documentation:: Writing and using documentation strings. ++ ++* Files:: Accessing files. ++* Backups and Auto-Saving:: Controlling how backups and auto-save ++ files are made. ++* Buffers:: Creating and using buffer objects. ++* Windows:: Manipulating windows and displaying buffers. ++* Frames:: Making multiple system-level windows. ++* Positions:: Buffer positions and motion functions. ++* Markers:: Markers represent positions and update ++ automatically when the text is changed. ++ ++* Text:: Examining and changing text in buffers. ++* Non-ASCII Characters:: Non-ASCII text in buffers and strings. ++* Searching and Matching:: Searching buffers for strings or regexps. ++* Syntax Tables:: The syntax table controls word and list parsing. ++* Abbrevs:: How Abbrev mode works, and its data structures. ++ ++* Processes:: Running and communicating with subprocesses. ++* Display:: Features for controlling the screen display. ++* System Interface:: Getting the user id, system type, environment ++ variables, and other such things. ++ ++Appendices ++ ++* Antinews:: Info for users downgrading to Emacs 22. ++* GNU Free Documentation License:: The license for this documentation. ++* GPL:: Conditions for copying and changing GNU Emacs. ++* Tips:: Advice and coding conventions for Emacs Lisp. ++* GNU Emacs Internals:: Building and dumping Emacs; ++ internal data structures. ++* Standard Errors:: List of all error symbols. ++* Standard Buffer-Local Variables:: ++ List of variables buffer-local in all buffers. ++* Standard Keymaps:: List of standard keymaps. ++* Standard Hooks:: List of standard hook variables. ++ ++* Index:: Index including concepts, functions, variables, ++ and other terms. ++ ++@ignore ++* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. ++@end ignore ++ ++@c Do NOT modify the following 3 lines! They must have this form to ++@c be correctly identified by `texinfo-multiple-files-update'. In ++@c particular, the detailed menu header line MUST be identical to the ++@c value of `texinfo-master-menu-header'. See texnfo-upd.el. ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ --------------------------------- ++ ++Here are other nodes that are inferiors of those already listed, ++mentioned here so you can get to them in one step: ++ ++Introduction ++ ++* Caveats:: Flaws and a request for help. ++* Lisp History:: Emacs Lisp is descended from Maclisp. ++* Conventions:: How the manual is formatted. ++* Version Info:: Which Emacs version is running? ++* Acknowledgements:: The authors, editors, and sponsors of this manual. ++ ++Conventions ++ ++* Some Terms:: Explanation of terms we use in this manual. ++* nil and t:: How the symbols @code{nil} and @code{t} are used. ++* Evaluation Notation:: The format we use for examples of evaluation. ++* Printing Notation:: The format we use when examples print text. ++* Error Messages:: The format we use for examples of errors. ++* Buffer Text Notation:: The format we use for buffer contents in examples. ++* Format of Descriptions:: Notation for describing functions, variables, etc. ++ ++Format of Descriptions ++ ++* A Sample Function Description:: A description of an imaginary ++ function, @code{foo}. ++* A Sample Variable Description:: A description of an imaginary ++ variable, @code{electric-future-map}. ++ ++Lisp Data Types ++ ++* Printed Representation:: How Lisp objects are represented as text. ++* Comments:: Comments and their formatting conventions. ++* Programming Types:: Types found in all Lisp systems. ++* Editing Types:: Types specific to Emacs. ++* Circular Objects:: Read syntax for circular structure. ++* Type Predicates:: Tests related to types. ++* Equality Predicates:: Tests of equality between any two objects. ++ ++Programming Types ++ ++* Integer Type:: Numbers without fractional parts. ++* Floating Point Type:: Numbers with fractional parts and with a large range. ++* Character Type:: The representation of letters, numbers and ++ control characters. ++* Symbol Type:: A multi-use object that refers to a function, ++ variable, or property list, and has a unique identity. ++* Sequence Type:: Both lists and arrays are classified as sequences. ++* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). ++* Array Type:: Arrays include strings and vectors. ++* String Type:: An (efficient) array of characters. ++* Vector Type:: One-dimensional arrays. ++* Char-Table Type:: One-dimensional sparse arrays indexed by characters. ++* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. ++* Hash Table Type:: Super-fast lookup tables. ++* Function Type:: A piece of executable code you can call from elsewhere. ++* Macro Type:: A method of expanding an expression into another ++ expression, more fundamental but less pretty. ++* Primitive Function Type:: A function written in C, callable from Lisp. ++* Byte-Code Type:: A function written in Lisp, then compiled. ++* Autoload Type:: A type used for automatically loading seldom-used ++ functions. ++ ++Character Type ++ ++* Basic Char Syntax:: Syntax for regular characters. ++* General Escape Syntax:: How to specify characters by their codes. ++* Ctl-Char Syntax:: Syntax for control characters. ++* Meta-Char Syntax:: Syntax for meta-characters. ++* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. ++ ++Cons Cell and List Types ++ ++* Box Diagrams:: Drawing pictures of lists. ++* Dotted Pair Notation:: A general syntax for cons cells. ++* Association List Type:: A specially constructed list. ++ ++String Type ++ ++* Syntax for Strings:: How to specify Lisp strings. ++* Non-ASCII in Strings:: International characters in strings. ++* Nonprinting Characters:: Literal unprintable characters in strings. ++* Text Props and Strings:: Strings with text properties. ++ ++Editing Types ++ ++* Buffer Type:: The basic object of editing. ++* Marker Type:: A position in a buffer. ++* Window Type:: Buffers are displayed in windows. ++* Frame Type:: Windows subdivide frames. ++* Terminal Type:: A terminal device displays frames. ++* Window Configuration Type:: Recording the way a frame is subdivided. ++* Frame Configuration Type:: Recording the status of all frames. ++* Process Type:: A subprocess of Emacs running on the underlying OS. ++* Stream Type:: Receive or send characters. ++* Keymap Type:: What function a keystroke invokes. ++* Overlay Type:: How an overlay is represented. ++* Font Type:: Fonts for displaying text. ++ ++Numbers ++ ++* Integer Basics:: Representation and range of integers. ++* Float Basics:: Representation and range of floating point. ++* Predicates on Numbers:: Testing for numbers. ++* Comparison of Numbers:: Equality and inequality predicates. ++* Numeric Conversions:: Converting float to integer and vice versa. ++* Arithmetic Operations:: How to add, subtract, multiply and divide. ++* Rounding Operations:: Explicitly rounding floating point numbers. ++* Bitwise Operations:: Logical and, or, not, shifting. ++* Math Functions:: Trig, exponential and logarithmic functions. ++* Random Numbers:: Obtaining random integers, predictable or not. ++ ++Strings and Characters ++ ++* String Basics:: Basic properties of strings and characters. ++* Predicates for Strings:: Testing whether an object is a string or char. ++* Creating Strings:: Functions to allocate new strings. ++* Modifying Strings:: Altering the contents of an existing string. ++* Text Comparison:: Comparing characters or strings. ++* String Conversion:: Converting to and from characters and strings. ++* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. ++* Case Conversion:: Case conversion functions. ++* Case Tables:: Customizing case conversion. ++ ++Lists ++ ++* Cons Cells:: How lists are made out of cons cells. ++* List-related Predicates:: Is this object a list? Comparing two lists. ++* List Elements:: Extracting the pieces of a list. ++* Building Lists:: Creating list structure. ++* List Variables:: Modifying lists stored in variables. ++* Modifying Lists:: Storing new pieces into an existing list. ++* Sets And Lists:: A list can represent a finite mathematical set. ++* Association Lists:: A list can represent a finite relation or mapping. ++* Rings:: Managing a fixed-size ring of objects. ++ ++Modifying Existing List Structure ++ ++* Setcar:: Replacing an element in a list. ++* Setcdr:: Replacing part of the list backbone. ++ This can be used to remove or add elements. ++* Rearrangement:: Reordering the elements in a list; combining lists. ++ ++Sequences, Arrays, and Vectors ++ ++* Sequence Functions:: Functions that accept any kind of sequence. ++* Arrays:: Characteristics of arrays in Emacs Lisp. ++* Array Functions:: Functions specifically for arrays. ++* Vectors:: Special characteristics of Emacs Lisp vectors. ++* Vector Functions:: Functions specifically for vectors. ++* Char-Tables:: How to work with char-tables. ++* Bool-Vectors:: How to work with bool-vectors. ++ ++Hash Tables ++ ++* Creating Hash:: Functions to create hash tables. ++* Hash Access:: Reading and writing the hash table contents. ++* Defining Hash:: Defining new comparison methods. ++* Other Hash:: Miscellaneous. ++ ++Symbols ++ ++* Symbol Components:: Symbols have names, values, function definitions ++ and property lists. ++* Definitions:: A definition says how a symbol will be used. ++* Creating Symbols:: How symbols are kept unique. ++* Property Lists:: Each symbol has a property list ++ for recording miscellaneous information. ++ ++Property Lists ++ ++* Plists and Alists:: Comparison of the advantages of property ++ lists and association lists. ++* Symbol Plists:: Functions to access symbols' property lists. ++* Other Plists:: Accessing property lists stored elsewhere. ++ ++Evaluation ++ ++* Intro Eval:: Evaluation in the scheme of things. ++* Forms:: How various sorts of objects are evaluated. ++* Quoting:: Avoiding evaluation (to put constants in ++ the program). ++* Eval:: How to invoke the Lisp interpreter explicitly. ++ ++Kinds of Forms ++ ++* Self-Evaluating Forms:: Forms that evaluate to themselves. ++* Symbol Forms:: Symbols evaluate as variables. ++* Classifying Lists:: How to distinguish various sorts of list forms. ++* Function Indirection:: When a symbol appears as the car of a list, ++ we find the real function via the symbol. ++* Function Forms:: Forms that call functions. ++* Macro Forms:: Forms that call macros. ++* Special Forms:: "Special forms" are idiosyncratic primitives, ++ most of them extremely important. ++* Autoloading:: Functions set up to load files ++ containing their real definitions. ++ ++Control Structures ++ ++* Sequencing:: Evaluation in textual order. ++* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. ++* Combining Conditions:: @code{and}, @code{or}, @code{not}. ++* Iteration:: @code{while} loops. ++* Nonlocal Exits:: Jumping out of a sequence. ++ ++Nonlocal Exits ++ ++* Catch and Throw:: Nonlocal exits for the program's own purposes. ++* Examples of Catch:: Showing how such nonlocal exits can be written. ++* Errors:: How errors are signaled and handled. ++* Cleanups:: Arranging to run a cleanup form if an ++ error happens. ++ ++Errors ++ ++* Signaling Errors:: How to report an error. ++* Processing of Errors:: What Emacs does when you report an error. ++* Handling Errors:: How you can trap errors and continue execution. ++* Error Symbols:: How errors are classified for trapping them. ++ ++Variables ++ ++* Global Variables:: Variable values that exist permanently, everywhere. ++* Constant Variables:: Certain "variables" have values that never change. ++* Local Variables:: Variable values that exist only temporarily. ++* Void Variables:: Symbols that lack values. ++* Defining Variables:: A definition says a symbol is used as a variable. ++* Tips for Defining:: Things you should think about when you ++ define a variable. ++* Accessing Variables:: Examining values of variables whose names ++ are known only at run time. ++* Setting Variables:: Storing new values in variables. ++* Variable Scoping:: How Lisp chooses among local and global values. ++* Buffer-Local Variables:: Variable values in effect only in one buffer. ++* File Local Variables:: Handling local variable lists in files. ++* Directory Local Variables:: Local variables common to all files in a ++ directory. ++* Frame-Local Variables:: Frame-local bindings for variables. ++* Variable Aliases:: Variables that are aliases for other variables. ++* Variables with Restricted Values:: Non-constant variables whose value can ++ @emph{not} be an arbitrary Lisp object. ++ ++Scoping Rules for Variable Bindings ++ ++* Scope:: Scope means where in the program a value ++ is visible. Comparison with other languages. ++* Extent:: Extent means how long in time a value exists. ++* Impl of Scope:: Two ways to implement dynamic scoping. ++* Using Scoping:: How to use dynamic scoping carefully and ++ avoid problems. ++ ++Buffer-Local Variables ++ ++* Intro to Buffer-Local:: Introduction and concepts. ++* Creating Buffer-Local:: Creating and destroying buffer-local bindings. ++* Default Value:: The default value is seen in buffers ++ that don't have their own buffer-local values. ++ ++Functions ++ ++* What Is a Function:: Lisp functions vs. primitives; terminology. ++* Lambda Expressions:: How functions are expressed as Lisp objects. ++* Function Names:: A symbol can serve as the name of a function. ++* Defining Functions:: Lisp expressions for defining functions. ++* Calling Functions:: How to use an existing function. ++* Mapping Functions:: Applying a function to each element of a list, etc. ++* Anonymous Functions:: Lambda expressions are functions with no names. ++* Function Cells:: Accessing or setting the function definition ++ of a symbol. ++* Obsolete Functions:: Declaring functions obsolete. ++* Inline Functions:: Defining functions that the compiler ++ will open code. ++* Declaring Functions:: Telling the compiler that a function is defined. ++* Function Safety:: Determining whether a function is safe to call. ++* Related Topics:: Cross-references to specific Lisp primitives ++ that have a special bearing on how ++ functions work. ++ ++Lambda Expressions ++ ++* Lambda Components:: The parts of a lambda expression. ++* Simple Lambda:: A simple example. ++* Argument List:: Details and special features of argument lists. ++* Function Documentation:: How to put documentation in a function. ++ ++Macros ++ ++* Simple Macro:: A basic example. ++* Expansion:: How, when and why macros are expanded. ++* Compiling Macros:: How macros are expanded by the compiler. ++* Defining Macros:: How to write a macro definition. ++* Backquote:: Easier construction of list structure. ++* Problems with Macros:: Don't evaluate the macro arguments too many times. ++ Don't hide the user's variables. ++* Indenting Macros:: Specifying how to indent macro calls. ++ ++Common Problems Using Macros ++ ++* Wrong Time:: Do the work in the expansion, not in the macro. ++* Argument Evaluation:: The expansion should evaluate each macro arg once. ++* Surprising Local Vars:: Local variable bindings in the expansion ++ require special care. ++* Eval During Expansion:: Don't evaluate them; put them in the expansion. ++* Repeated Expansion:: Avoid depending on how many times expansion is done. ++ ++Writing Customization Definitions ++ ++* Common Keywords:: Common keyword arguments for all kinds of ++ customization declarations. ++* Group Definitions:: Writing customization group definitions. ++* Variable Definitions:: Declaring user options. ++* Customization Types:: Specifying the type of a user option. ++ ++Customization Types ++ ++* Simple Types:: Simple customization types: sexp, integer, number, ++ string, file, directory, alist. ++* Composite Types:: Build new types from other types or data. ++* Splicing into Lists:: Splice elements into list with @code{:inline}. ++* Type Keywords:: Keyword-argument pairs in a customization type. ++* Defining New Types:: Give your type a name. ++ ++Loading ++ ++* How Programs Do Loading:: The @code{load} function and others. ++* Load Suffixes:: Details about the suffixes that @code{load} tries. ++* Library Search:: Finding a library to load. ++* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. ++* Autoload:: Setting up a function to autoload. ++* Repeated Loading:: Precautions about loading a file twice. ++* Named Features:: Loading a library if it isn't already loaded. ++* Where Defined:: Finding which file defined a certain symbol. ++* Unloading:: How to "unload" a library that was loaded. ++* Hooks for Loading:: Providing code to be run when ++ particular libraries are loaded. ++ ++Byte Compilation ++ ++* Speed of Byte-Code:: An example of speedup from byte compilation. ++* Compilation Functions:: Byte compilation functions. ++* Docs and Compilation:: Dynamic loading of documentation strings. ++* Dynamic Loading:: Dynamic loading of individual functions. ++* Eval During Compile:: Code to be evaluated when you compile. ++* Compiler Errors:: Handling compiler error messages. ++* Byte-Code Objects:: The data type used for byte-compiled functions. ++* Disassembly:: Disassembling byte-code; how to read byte-code. ++ ++Advising Emacs Lisp Functions ++ ++* Simple Advice:: A simple example to explain the basics of advice. ++* Defining Advice:: Detailed description of @code{defadvice}. ++* Around-Advice:: Wrapping advice around a function's definition. ++* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. ++* Activation of Advice:: Advice doesn't do anything until you activate it. ++* Enabling Advice:: You can enable or disable each piece of advice. ++* Preactivation:: Preactivation is a way of speeding up the ++ loading of compiled advice. ++* Argument Access in Advice:: How advice can access the function's arguments. ++* Advising Primitives:: Accessing arguments when advising a primitive. ++* Combined Definition:: How advice is implemented. ++ ++Debugging Lisp Programs ++ ++* Debugger:: How the Emacs Lisp debugger is implemented. ++* Edebug:: A source-level Emacs Lisp debugger. ++* Syntax Errors:: How to find syntax errors. ++* Test Coverage:: Ensuring you have tested all branches in your code. ++* Compilation Errors:: How to find errors that show up in ++ byte compilation. ++ ++The Lisp Debugger ++ ++* Error Debugging:: Entering the debugger when an error happens. ++* Infinite Loops:: Stopping and debugging a program that doesn't exit. ++* Function Debugging:: Entering it when a certain function is called. ++* Explicit Debug:: Entering it at a certain point in the program. ++* Using Debugger:: What the debugger does; what you see while in it. ++* Debugger Commands:: Commands used while in the debugger. ++* Invoking the Debugger:: How to call the function @code{debug}. ++* Internals of Debugger:: Subroutines of the debugger, and global variables. ++ ++Edebug ++ ++* Using Edebug:: Introduction to use of Edebug. ++* Instrumenting:: You must instrument your code ++ in order to debug it with Edebug. ++* Edebug Execution Modes:: Execution modes, stopping more or less often. ++* Jumping:: Commands to jump to a specified place. ++* Edebug Misc:: Miscellaneous commands. ++* Breaks:: Setting breakpoints to make the program stop. ++* Trapping Errors:: Trapping errors with Edebug. ++* Edebug Views:: Views inside and outside of Edebug. ++* Edebug Eval:: Evaluating expressions within Edebug. ++* Eval List:: Expressions whose values are displayed ++ each time you enter Edebug. ++* Printing in Edebug:: Customization of printing. ++* Trace Buffer:: How to produce trace output in a buffer. ++* Coverage Testing:: How to test evaluation coverage. ++* The Outside Context:: Data that Edebug saves and restores. ++* Edebug and Macros:: Specifying how to handle macro calls. ++* Edebug Options:: Option variables for customizing Edebug. ++ ++Breaks ++ ++* Breakpoints:: Breakpoints at stop points. ++* Global Break Condition:: Breaking on an event. ++* Source Breakpoints:: Embedding breakpoints in source code. ++ ++The Outside Context ++ ++* Checking Whether to Stop::When Edebug decides what to do. ++* Edebug Display Update:: When Edebug updates the display. ++* Edebug Recursive Edit:: When Edebug stops execution. ++ ++Edebug and Macros ++ ++* Instrumenting Macro Calls::The basic problem. ++* Specification List:: How to specify complex patterns of evaluation. ++* Backtracking:: What Edebug does when matching fails. ++* Specification Examples:: To help understand specifications. ++ ++Debugging Invalid Lisp Syntax ++ ++* Excess Open:: How to find a spurious open paren or missing close. ++* Excess Close:: How to find a spurious close paren or missing open. ++ ++Reading and Printing Lisp Objects ++ ++* Streams Intro:: Overview of streams, reading and printing. ++* Input Streams:: Various data types that can be used as ++ input streams. ++* Input Functions:: Functions to read Lisp objects from text. ++* Output Streams:: Various data types that can be used as ++ output streams. ++* Output Functions:: Functions to print Lisp objects as text. ++* Output Variables:: Variables that control what the printing ++ functions do. ++ ++Minibuffers ++ ++* Intro to Minibuffers:: Basic information about minibuffers. ++* Text from Minibuffer:: How to read a straight text string. ++* Object from Minibuffer:: How to read a Lisp object or expression. ++* Minibuffer History:: Recording previous minibuffer inputs ++ so the user can reuse them. ++* Initial Input:: Specifying initial contents for the minibuffer. ++* Completion:: How to invoke and customize completion. ++* Yes-or-No Queries:: Asking a question with a simple answer. ++* Multiple Queries:: Asking a series of similar questions. ++* Reading a Password:: Reading a password from the terminal. ++* Minibuffer Commands:: Commands used as key bindings in minibuffers. ++* Minibuffer Contents:: How such commands access the minibuffer text. ++* Minibuffer Windows:: Operating on the special minibuffer windows. ++* Recursive Mini:: Whether recursive entry to minibuffer is allowed. ++* Minibuffer Misc:: Various customization hooks and variables. ++ ++Completion ++ ++* Basic Completion:: Low-level functions for completing strings. ++ (These are too low level to use the minibuffer.) ++* Minibuffer Completion:: Invoking the minibuffer with completion. ++* Completion Commands:: Minibuffer commands that do completion. ++* High-Level Completion:: Convenient special cases of completion ++ (reading buffer name, file name, etc.). ++* Reading File Names:: Using completion to read file names and ++ shell commands. ++* Completion Styles:: Specifying rules for performing completion. ++* Programmed Completion:: Writing your own completion-function. ++ ++Command Loop ++ ++* Command Overview:: How the command loop reads commands. ++* Defining Commands:: Specifying how a function should read arguments. ++* Interactive Call:: Calling a command, so that it will read arguments. ++* Distinguish Interactive:: Making a command distinguish interactive calls. ++* Command Loop Info:: Variables set by the command loop for you to examine. ++* Adjusting Point:: Adjustment of point after a command. ++* Input Events:: What input looks like when you read it. ++* Reading Input:: How to read input events from the keyboard or mouse. ++* Special Events:: Events processed immediately and individually. ++* Waiting:: Waiting for user input or elapsed time. ++* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. ++* Prefix Command Arguments:: How the commands to set prefix args work. ++* Recursive Editing:: Entering a recursive edit, ++ and why you usually shouldn't. ++* Disabling Commands:: How the command loop handles disabled commands. ++* Command History:: How the command history is set up, and how accessed. ++* Keyboard Macros:: How keyboard macros are implemented. ++ ++Defining Commands ++ ++* Using Interactive:: General rules for @code{interactive}. ++* Interactive Codes:: The standard letter-codes for reading arguments ++ in various ways. ++* Interactive Examples:: Examples of how to read interactive arguments. ++ ++Input Events ++ ++* Keyboard Events:: Ordinary characters--keys with symbols on them. ++* Function Keys:: Function keys--keys with names, not symbols. ++* Mouse Events:: Overview of mouse events. ++* Click Events:: Pushing and releasing a mouse button. ++* Drag Events:: Moving the mouse before releasing the button. ++* Button-Down Events:: A button was pushed and not yet released. ++* Repeat Events:: Double and triple click (or drag, or down). ++* Motion Events:: Just moving the mouse, not pushing a button. ++* Focus Events:: Moving the mouse between frames. ++* Misc Events:: Other events the system can generate. ++* Event Examples:: Examples of the lists for mouse events. ++* Classifying Events:: Finding the modifier keys in an event symbol. ++ Event types. ++* Accessing Mouse:: Functions to extract info from mouse events. ++* Accessing Scroll:: Functions to get info from scroll bar events. ++* Strings of Events:: Special considerations for putting ++ keyboard character events in a string. ++ ++Reading Input ++ ++* Key Sequence Input:: How to read one key sequence. ++* Reading One Event:: How to read just one event. ++* Event Mod:: How Emacs modifies events as they are read. ++* Invoking the Input Method:: How reading an event uses the input method. ++* Quoted Character Input:: Asking the user to specify a character. ++* Event Input Misc:: How to reread or throw away input events. ++ ++Keymaps ++ ++* Key Sequences:: Key sequences as Lisp objects. ++* Keymap Basics:: Basic concepts of keymaps. ++* Format of Keymaps:: What a keymap looks like as a Lisp object. ++* Creating Keymaps:: Functions to create and copy keymaps. ++* Inheritance and Keymaps:: How one keymap can inherit the bindings ++ of another keymap. ++* Prefix Keys:: Defining a key with a keymap as its definition. ++* Active Keymaps:: How Emacs searches the active keymaps ++ for a key binding. ++* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. ++* Controlling Active Maps:: Each buffer has a local keymap ++ to override the standard (global) bindings. ++ A minor mode can also override them. ++* Key Lookup:: Finding a key's binding in one keymap. ++* Functions for Key Lookup:: How to request key lookup. ++* Changing Key Bindings:: Redefining a key in a keymap. ++* Remapping Commands:: A keymap can translate one command to another. ++* Translation Keymaps:: Keymaps for translating sequences of events. ++* Key Binding Commands:: Interactive interfaces for redefining keys. ++* Scanning Keymaps:: Looking through all keymaps, for printing help. ++* Menu Keymaps:: Defining a menu as a keymap. ++ ++Menu Keymaps ++ ++* Defining Menus:: How to make a keymap that defines a menu. ++* Mouse Menus:: How users actuate the menu with the mouse. ++* Keyboard Menus:: How users actuate the menu with the keyboard. ++* Menu Example:: Making a simple menu. ++* Menu Bar:: How to customize the menu bar. ++* Tool Bar:: A tool bar is a row of images. ++* Modifying Menus:: How to add new items to a menu. ++ ++Defining Menus ++ ++* Simple Menu Items:: A simple kind of menu key binding, ++ limited in capabilities. ++* Extended Menu Items:: More powerful menu item definitions ++ let you specify keywords to enable ++ various features. ++* Menu Separators:: Drawing a horizontal line through a menu. ++* Alias Menu Items:: Using command aliases in menu items. ++ ++Major and Minor Modes ++ ++* Hooks:: How to use hooks; how to write code that provides hooks. ++* Major Modes:: Defining major modes. ++* Minor Modes:: Defining minor modes. ++* Mode Line Format:: Customizing the text that appears in the mode line. ++* Imenu:: How a mode can provide a menu ++ of definitions in the buffer. ++* Font Lock Mode:: How modes can highlight text according to syntax. ++* Desktop Save Mode:: How modes can have buffer state saved between ++ Emacs sessions. ++ ++Hooks ++ ++* Running Hooks:: How to run a hook. ++* Setting Hooks:: How to put functions on a hook, or remove them. ++ ++Major Modes ++ ++* Major Mode Basics:: ++* Major Mode Conventions:: Coding conventions for keymaps, etc. ++* Auto Major Mode:: How Emacs chooses the major mode automatically. ++* Mode Help:: Finding out how to use a mode. ++* Derived Modes:: Defining a new major mode based on another major ++ mode. ++* Generic Modes:: Defining a simple major mode that supports ++ comment syntax and Font Lock mode. ++* Mode Hooks:: Hooks run at the end of major mode functions. ++* Example Major Modes:: Text mode and Lisp modes. ++ ++Minor Modes ++ ++* Minor Mode Conventions:: Tips for writing a minor mode. ++* Keymaps and Minor Modes:: How a minor mode can have its own keymap. ++* Defining Minor Modes:: A convenient facility for defining minor modes. ++ ++Mode Line Format ++ ++* Mode Line Basics:: Basic ideas of mode line control. ++* Mode Line Data:: The data structure that controls the mode line. ++* Mode Line Top:: The top level variable, mode-line-format. ++* Mode Line Variables:: Variables used in that data structure. ++* %-Constructs:: Putting information into a mode line. ++* Properties in Mode:: Using text properties in the mode line. ++* Header Lines:: Like a mode line, but at the top. ++* Emulating Mode Line:: Formatting text as the mode line would. ++ ++Font Lock Mode ++ ++* Font Lock Basics:: Overview of customizing Font Lock. ++* Search-based Fontification:: Fontification based on regexps. ++* Customizing Keywords:: Customizing search-based fontification. ++* Other Font Lock Variables:: Additional customization facilities. ++* Levels of Font Lock:: Each mode can define alternative levels ++ so that the user can select more or less. ++* Precalculated Fontification:: How Lisp programs that produce the buffer ++ contents can also specify how to fontify it. ++* Faces for Font Lock:: Special faces specifically for Font Lock. ++* Syntactic Font Lock:: Fontification based on syntax tables. ++* Setting Syntax Properties:: Defining character syntax based on context ++ using the Font Lock mechanism. ++* Multiline Font Lock:: How to coerce Font Lock into properly ++ highlighting multiline constructs. ++ ++Multiline Font Lock Constructs ++ ++* Font Lock Multiline:: Marking multiline chunks with a text property. ++* Region to Fontify:: Controlling which region gets refontified ++ after a buffer change. ++ ++Documentation ++ ++* Documentation Basics:: Good style for doc strings. ++ Where to put them. How Emacs stores them. ++* Accessing Documentation:: How Lisp programs can access doc strings. ++* Keys in Documentation:: Substituting current key bindings. ++* Describing Characters:: Making printable descriptions of ++ non-printing characters and key sequences. ++* Help Functions:: Subroutines used by Emacs help facilities. ++ ++Files ++ ++* Visiting Files:: Reading files into Emacs buffers for editing. ++* Saving Buffers:: Writing changed buffers back into files. ++* Reading from Files:: Reading files into buffers without visiting. ++* Writing to Files:: Writing new files from parts of buffers. ++* File Locks:: Locking and unlocking files, to prevent ++ simultaneous editing by two people. ++* Information about Files:: Testing existence, accessibility, size of files. ++* Changing Files:: Renaming files, changing protection, etc. ++* File Names:: Decomposing and expanding file names. ++* Contents of Directories:: Getting a list of the files in a directory. ++* Create/Delete Dirs:: Creating and Deleting Directories. ++* Magic File Names:: Defining "magic" special handling ++ for certain file names. ++* Format Conversion:: Conversion to and from various file formats. ++ ++Visiting Files ++ ++* Visiting Functions:: The usual interface functions for visiting. ++* Subroutines of Visiting:: Lower-level subroutines that they use. ++ ++Information about Files ++ ++* Testing Accessibility:: Is a given file readable? Writable? ++* Kinds of Files:: Is it a directory? A symbolic link? ++* Truenames:: Eliminating symbolic links from a file name. ++* File Attributes:: How large is it? Any other names? Etc. ++* Locating Files:: How to find a file in standard places. ++ ++File Names ++ ++* File Name Components:: The directory part of a file name, and the rest. ++* Relative File Names:: Some file names are relative to a current directory. ++* Directory Names:: A directory's name as a directory ++ is different from its name as a file. ++* File Name Expansion:: Converting relative file names to absolute ones. ++* Unique File Names:: Generating names for temporary files. ++* File Name Completion:: Finding the completions for a given file name. ++* Standard File Names:: If your package uses a fixed file name, ++ how to handle various operating systems simply. ++ ++File Format Conversion ++ ++* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. ++* Format Conversion Round-Trip:: Using @code{format-alist}. ++* Format Conversion Piecemeal:: Specifying non-paired conversion. ++ ++Backups and Auto-Saving ++ ++* Backup Files:: How backup files are made; how their names ++ are chosen. ++* Auto-Saving:: How auto-save files are made; how their ++ names are chosen. ++* Reverting:: @code{revert-buffer}, and how to customize ++ what it does. ++ ++Backup Files ++ ++* Making Backups:: How Emacs makes backup files, and when. ++* Rename or Copy:: Two alternatives: renaming the old file ++ or copying it. ++* Numbered Backups:: Keeping multiple backups for each source file. ++* Backup Names:: How backup file names are computed; customization. ++ ++Buffers ++ ++* Buffer Basics:: What is a buffer? ++* Current Buffer:: Designating a buffer as current ++ so that primitives will access its contents. ++* Buffer Names:: Accessing and changing buffer names. ++* Buffer File Name:: The buffer file name indicates which file ++ is visited. ++* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. ++* Modification Time:: Determining whether the visited file was changed ++ ``behind Emacs's back''. ++* Read Only Buffers:: Modifying text is not allowed in a ++ read-only buffer. ++* The Buffer List:: How to look at all the existing buffers. ++* Creating Buffers:: Functions that create buffers. ++* Killing Buffers:: Buffers exist until explicitly killed. ++* Indirect Buffers:: An indirect buffer shares text with some ++ other buffer. ++* Swapping Text:: Swapping text between two buffers. ++* Buffer Gap:: The gap in the buffer. ++ ++Windows ++ ++* Basic Windows:: Basic information on using windows. ++* Splitting Windows:: Splitting one window into two windows. ++* Deleting Windows:: Deleting a window gives its space to other windows. ++* Selecting Windows:: The selected window is the one that you edit in. ++* Cyclic Window Ordering:: Moving around the existing windows. ++* Buffers and Windows:: Each window displays the contents of a buffer. ++* Displaying Buffers:: Higher-level functions for displaying a buffer ++ and choosing a window for it. ++* Choosing Window:: How to choose a window for displaying a buffer. ++* Dedicated Windows:: How to avoid displaying another buffer in ++ a specific window. ++* Window Point:: Each window has its own location of point. ++* Window Start and End:: Buffer positions indicating which text is ++ on-screen in a window. ++* Textual Scrolling:: Moving text up and down through the window. ++* Vertical Scrolling:: Moving the contents up and down on the window. ++* Horizontal Scrolling:: Moving the contents sideways on the window. ++* Size of Window:: Accessing the size of a window. ++* Resizing Windows:: Changing the size of a window. ++* Coordinates and Windows:: Converting coordinates to windows. ++* Window Tree:: The layout and sizes of all windows in a frame. ++* Window Configurations:: Saving and restoring the state of the screen. ++* Window Parameters:: Associating additional information with windows. ++* Window Hooks:: Hooks for scrolling, window size changes, ++ redisplay going past a certain point, ++ or window configuration changes. ++ ++Frames ++ ++* Creating Frames:: Creating additional frames. ++* Multiple Terminals:: Displaying on several different devices. ++* Frame Parameters:: Controlling frame size, position, font, etc. ++* Terminal Parameters:: Parameters common for all frames on terminal. ++* Frame Titles:: Automatic updating of frame titles. ++* Deleting Frames:: Frames last until explicitly deleted. ++* Finding All Frames:: How to examine all existing frames. ++* Frames and Windows:: A frame contains windows; ++ display of text always works through windows. ++* Minibuffers and Frames:: How a frame finds the minibuffer to use. ++* Input Focus:: Specifying the selected frame. ++* Visibility of Frames:: Frames may be visible or invisible, or icons. ++* Raising and Lowering:: Raising a frame makes it hide other windows; ++ lowering it makes the others hide it. ++* Frame Configurations:: Saving the state of all frames. ++* Mouse Tracking:: Getting events that say when the mouse moves. ++* Mouse Position:: Asking where the mouse is, or moving it. ++* Pop-Up Menus:: Displaying a menu for the user to select from. ++* Dialog Boxes:: Displaying a box to ask yes or no. ++* Pointer Shape:: Specifying the shape of the mouse pointer. ++* Window System Selections::Transferring text to and from other X clients. ++* Drag and Drop:: Internals of Drag-and-Drop implementation. ++* Color Names:: Getting the definitions of color names. ++* Text Terminal Colors:: Defining colors for text-only terminals. ++* Resources:: Getting resource values from the server. ++* Display Feature Testing:: Determining the features of a terminal. ++ ++Frame Parameters ++ ++* Parameter Access:: How to change a frame's parameters. ++* Initial Parameters:: Specifying frame parameters when you make a frame. ++* Window Frame Parameters:: List of frame parameters for window systems. ++* Size and Position:: Changing the size and position of a frame. ++* Geometry:: Parsing geometry specifications. ++ ++Window Frame Parameters ++ ++* Basic Parameters:: Parameters that are fundamental. ++* Position Parameters:: The position of the frame on the screen. ++* Size Parameters:: Frame's size. ++* Layout Parameters:: Size of parts of the frame, and ++ enabling or disabling some parts. ++* Buffer Parameters:: Which buffers have been or should be shown. ++* Management Parameters:: Communicating with the window manager. ++* Cursor Parameters:: Controlling the cursor appearance. ++* Font and Color Parameters:: Fonts and colors for the frame text. ++ ++Positions ++ ++* Point:: The special position where editing takes place. ++* Motion:: Changing point. ++* Excursions:: Temporary motion and buffer changes. ++* Narrowing:: Restricting editing to a portion of the buffer. ++ ++Motion ++ ++* Character Motion:: Moving in terms of characters. ++* Word Motion:: Moving in terms of words. ++* Buffer End Motion:: Moving to the beginning or end of the buffer. ++* Text Lines:: Moving in terms of lines of text. ++* Screen Lines:: Moving in terms of lines as displayed. ++* List Motion:: Moving by parsing lists and sexps. ++* Skipping Characters:: Skipping characters belonging to a certain set. ++ ++Markers ++ ++* Overview of Markers:: The components of a marker, and how it relocates. ++* Predicates on Markers:: Testing whether an object is a marker. ++* Creating Markers:: Making empty markers or markers at certain places. ++* Information from Markers::Finding the marker's buffer or character position. ++* Marker Insertion Types:: Two ways a marker can relocate when you ++ insert where it points. ++* Moving Markers:: Moving the marker to a new buffer or position. ++* The Mark:: How "the mark" is implemented with a marker. ++* The Region:: How to access "the region". ++ ++Text ++ ++* Near Point:: Examining text in the vicinity of point. ++* Buffer Contents:: Examining text in a general fashion. ++* Comparing Text:: Comparing substrings of buffers. ++* Insertion:: Adding new text to a buffer. ++* Commands for Insertion:: User-level commands to insert text. ++* Deletion:: Removing text from a buffer. ++* User-Level Deletion:: User-level commands to delete text. ++* The Kill Ring:: Where removed text sometimes is saved for ++ later use. ++* Undo:: Undoing changes to the text of a buffer. ++* Maintaining Undo:: How to enable and disable undo information. ++ How to control how much information is kept. ++* Filling:: Functions for explicit filling. ++* Margins:: How to specify margins for filling commands. ++* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix ++ from context. ++* Auto Filling:: How auto-fill mode is implemented to break lines. ++* Sorting:: Functions for sorting parts of the buffer. ++* Columns:: Computing horizontal positions, and using them. ++* Indentation:: Functions to insert or adjust indentation. ++* Case Changes:: Case conversion of parts of the buffer. ++* Text Properties:: Assigning Lisp property lists to text characters. ++* Substitution:: Replacing a given character wherever it appears. ++* Transposition:: Swapping two portions of a buffer. ++* Registers:: How registers are implemented. Accessing ++ the text or position stored in a register. ++* Base 64:: Conversion to or from base 64 encoding. ++* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". ++* Atomic Changes:: Installing several buffer changes "atomically". ++* Change Hooks:: Supplying functions to be run when text is changed. ++ ++The Kill Ring ++ ++* Kill Ring Concepts:: What text looks like in the kill ring. ++* Kill Functions:: Functions that kill text. ++* Yanking:: How yanking is done. ++* Yank Commands:: Commands that access the kill ring. ++* Low-Level Kill Ring:: Functions and variables for kill ring access. ++* Internals of Kill Ring:: Variables that hold kill ring data. ++ ++Indentation ++ ++* Primitive Indent:: Functions used to count and insert indentation. ++* Mode-Specific Indent:: Customize indentation for different modes. ++* Region Indent:: Indent all the lines in a region. ++* Relative Indent:: Indent the current line based on previous lines. ++* Indent Tabs:: Adjustable, typewriter-like tab stops. ++* Motion by Indent:: Move to first non-blank character. ++ ++Text Properties ++ ++* Examining Properties:: Looking at the properties of one character. ++* Changing Properties:: Setting the properties of a range of text. ++* Property Search:: Searching for where a property changes value. ++* Special Properties:: Particular properties with special meanings. ++* Format Properties:: Properties for representing formatting of text. ++* Sticky Properties:: How inserted text gets properties from ++ neighboring text. ++* Lazy Properties:: Computing text properties in a lazy fashion ++ only when text is examined. ++* Clickable Text:: Using text properties to make regions of text ++ do something when you click on them. ++* Fields:: The @code{field} property defines ++ fields within the buffer. ++* Not Intervals:: Why text properties do not use ++ Lisp-visible text intervals. ++ ++Non-@acronym{ASCII} Characters ++ ++* Text Representations:: How Emacs represents text. ++* Converting Representations:: Converting unibyte to multibyte and vice versa. ++* Selecting a Representation:: Treating a byte sequence as unibyte or multi. ++* Character Codes:: How unibyte and multibyte relate to ++ codes of individual characters. ++* Character Properties:: Character attributes that define their ++ behavior and handling. ++* Character Sets:: The space of possible character codes ++ is divided into various character sets. ++* Scanning Charsets:: Which character sets are used in a buffer? ++* Translation of Characters:: Translation tables are used for conversion. ++* Coding Systems:: Coding systems are conversions for saving files. ++* Input Methods:: Input methods allow users to enter various ++ non-ASCII characters without special keyboards. ++* Locales:: Interacting with the POSIX locale. ++ ++Coding Systems ++ ++* Coding System Basics:: Basic concepts. ++* Encoding and I/O:: How file I/O functions handle coding systems. ++* Lisp and Coding Systems:: Functions to operate on coding system names. ++* User-Chosen Coding Systems:: Asking the user to choose a coding system. ++* Default Coding Systems:: Controlling the default choices. ++* Specifying Coding Systems:: Requesting a particular coding system ++ for a single file operation. ++* Explicit Encoding:: Encoding or decoding text without doing I/O. ++* Terminal I/O Encoding:: Use of encoding for terminal I/O. ++* MS-DOS File Types:: How DOS "text" and "binary" files ++ relate to coding systems. ++ ++Searching and Matching ++ ++* String Search:: Search for an exact match. ++* Searching and Case:: Case-independent or case-significant searching. ++* Regular Expressions:: Describing classes of strings. ++* Regexp Search:: Searching for a match for a regexp. ++* POSIX Regexps:: Searching POSIX-style for the longest match. ++* Match Data:: Finding out which part of the text matched, ++ after a string or regexp search. ++* Search and Replace:: Commands that loop, searching and replacing. ++* Standard Regexps:: Useful regexps for finding sentences, pages,... ++ ++Regular Expressions ++ ++* Syntax of Regexps:: Rules for writing regular expressions. ++* Regexp Example:: Illustrates regular expression syntax. ++* Regexp Functions:: Functions for operating on regular expressions. ++ ++Syntax of Regular Expressions ++ ++* Regexp Special:: Special characters in regular expressions. ++* Char Classes:: Character classes used in regular expressions. ++* Regexp Backslash:: Backslash-sequences in regular expressions. ++ ++The Match Data ++ ++* Replacing Match:: Replacing a substring that was matched. ++* Simple Match Data:: Accessing single items of match data, ++ such as where a particular subexpression started. ++* Entire Match Data:: Accessing the entire match data at once, as a list. ++* Saving Match Data:: Saving and restoring the match data. ++ ++Syntax Tables ++ ++* Syntax Basics:: Basic concepts of syntax tables. ++* Syntax Descriptors:: How characters are classified. ++* Syntax Table Functions:: How to create, examine and alter syntax tables. ++* Syntax Properties:: Overriding syntax with text properties. ++* Motion and Syntax:: Moving over characters with certain syntaxes. ++* Parsing Expressions:: Parsing balanced expressions ++ using the syntax table. ++* Standard Syntax Tables:: Syntax tables used by various major modes. ++* Syntax Table Internals:: How syntax table information is stored. ++* Categories:: Another way of classifying character syntax. ++ ++Syntax Descriptors ++ ++* Syntax Class Table:: Table of syntax classes. ++* Syntax Flags:: Additional flags each character can have. ++ ++Parsing Expressions ++ ++* Motion via Parsing:: Motion functions that work by parsing. ++* Position Parse:: Determining the syntactic state of a position. ++* Parser State:: How Emacs represents a syntactic state. ++* Low-Level Parsing:: Parsing across a specified region. ++* Control Parsing:: Parameters that affect parsing. ++ ++Abbrevs and Abbrev Expansion ++ ++* Abbrev Mode:: Setting up Emacs for abbreviation. ++* Abbrev Tables:: Creating and working with abbrev tables. ++* Defining Abbrevs:: Specifying abbreviations and their expansions. ++* Abbrev Files:: Saving abbrevs in files. ++* Abbrev Expansion:: Controlling expansion; expansion subroutines. ++* Standard Abbrev Tables:: Abbrev tables used by various major modes. ++* Abbrev Properties:: How to read and set abbrev properties. ++ Which properties have which effect. ++* Abbrev Table Properties:: How to read and set abbrev table properties. ++ Which properties have which effect. ++ ++Processes ++ ++* Subprocess Creation:: Functions that start subprocesses. ++* Shell Arguments:: Quoting an argument to pass it to a shell. ++* Synchronous Processes:: Details of using synchronous subprocesses. ++* Asynchronous Processes:: Starting up an asynchronous subprocess. ++* Deleting Processes:: Eliminating an asynchronous subprocess. ++* Process Information:: Accessing run-status and other attributes. ++* Input to Processes:: Sending input to an asynchronous subprocess. ++* Signals to Processes:: Stopping, continuing or interrupting ++ an asynchronous subprocess. ++* Output from Processes:: Collecting output from an asynchronous subprocess. ++* Sentinels:: Sentinels run when process run-status changes. ++* Query Before Exit:: Whether to query if exiting will kill a process. ++* System Processes:: Accessing other processes running on your system. ++* Transaction Queues:: Transaction-based communication with subprocesses. ++* Network:: Opening network connections. ++* Network Servers:: Network servers let Emacs accept net connections. ++* Datagrams:: UDP network connections. ++* Low-Level Network:: Lower-level but more general function ++ to create connections and servers. ++* Misc Network:: Additional relevant functions for ++ network connections. ++* Serial Ports:: Communicating with serial ports. ++* Byte Packing:: Using bindat to pack and unpack binary data. ++ ++Receiving Output from Processes ++ ++* Process Buffers:: If no filter, output is put in a buffer. ++* Filter Functions:: Filter functions accept output from the process. ++* Decoding Output:: Filters can get unibyte or multibyte strings. ++* Accepting Output:: How to wait until process output arrives. ++ ++Low-Level Network Access ++ ++* Network Processes:: Using @code{make-network-process}. ++* Network Options:: Further control over network connections. ++* Network Feature Testing:: Determining which network features work on ++ the machine you are using. ++ ++Packing and Unpacking Byte Arrays ++ ++* Bindat Spec:: Describing data layout. ++* Bindat Functions:: Doing the unpacking and packing. ++* Bindat Examples:: Samples of what bindat.el can do for you! ++ ++Emacs Display ++ ++* Refresh Screen:: Clearing the screen and redrawing everything on it. ++* Forcing Redisplay:: Forcing redisplay. ++* Truncation:: Folding or wrapping long text lines. ++* The Echo Area:: Displaying messages at the bottom of the screen. ++* Warnings:: Displaying warning messages for the user. ++* Invisible Text:: Hiding part of the buffer text. ++* Selective Display:: Hiding part of the buffer text (the old way). ++* Temporary Displays:: Displays that go away automatically. ++* Overlays:: Use overlays to highlight parts of the buffer. ++* Width:: How wide a character or string is on the screen. ++* Line Height:: Controlling the height of lines. ++* Faces:: A face defines a graphics style ++ for text characters: font, colors, etc. ++* Fringes:: Controlling window fringes. ++* Scroll Bars:: Controlling vertical scroll bars. ++* Display Property:: Enabling special display features. ++* Images:: Displaying images in Emacs buffers. ++* Buttons:: Adding clickable buttons to Emacs buffers. ++* Abstract Display:: Emacs' Widget for Object Collections. ++* Blinking:: How Emacs shows the matching open parenthesis. ++* Usual Display:: The usual conventions for displaying ++ nonprinting chars. ++* Display Tables:: How to specify other conventions. ++* Beeping:: Audible signal to the user. ++* Window Systems:: Which window system is being used. ++ ++The Echo Area ++ ++* Displaying Messages:: Explicitly displaying text in the echo area. ++* Progress:: Informing user about progress of a long operation. ++* Logging Messages:: Echo area messages are logged for the user. ++* Echo Area Customization:: Controlling the echo area. ++ ++Reporting Warnings ++ ++* Warning Basics:: Warnings concepts and functions to report them. ++* Warning Variables:: Variables programs bind to customize ++ their warnings. ++* Warning Options:: Variables users set to control display of warnings. ++ ++Overlays ++ ++* Managing Overlays:: Creating and moving overlays. ++* Overlay Properties:: How to read and set properties. ++ What properties do to the screen display. ++* Finding Overlays:: Searching for overlays. ++ ++Faces ++ ++* Defining Faces:: How to define a face with @code{defface}. ++* Face Attributes:: What is in a face? ++* Attribute Functions:: Functions to examine and set face attributes. ++* Displaying Faces:: How Emacs combines the faces specified for ++ a character. ++* Face Remapping:: Remapping faces to alternative definitions. ++* Face Functions:: How to define and examine faces. ++* Auto Faces:: Hook for automatic face assignment. ++* Font Selection:: Finding the best available font for a face. ++* Font Lookup:: Looking up the names of available fonts ++ and information about them. ++* Fontsets:: A fontset is a collection of fonts ++ that handle a range of character sets. ++* Low-Level Font:: Lisp representation for character display fonts. ++ ++Fringes ++ ++* Fringe Size/Pos:: Specifying where to put the window fringes. ++* Fringe Indicators:: Displaying indicator icons in the window fringes. ++* Fringe Cursors:: Displaying cursors in the right fringe. ++* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. ++* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. ++* Overlay Arrow:: Display of an arrow to indicate position. ++ ++The @code{display} Property ++ ++* Replacing Specs:: Display specs that replace the text. ++* Specified Space:: Displaying one space with a specified width. ++* Pixel Specification:: Specifying space width or height in pixels. ++* Other Display Specs:: Displaying an image; magnifying text; moving it ++ up or down on the page; adjusting the width ++ of spaces within text. ++* Display Margins:: Displaying text or images to the side of ++ the main text. ++ ++Images ++ ++* Image Formats:: Supported image formats. ++* Image Descriptors:: How to specify an image for use in @code{:display}. ++* XBM Images:: Special features for XBM format. ++* XPM Images:: Special features for XPM format. ++* GIF Images:: Special features for GIF format. ++* TIFF Images:: Special features for TIFF format. ++* PostScript Images:: Special features for PostScript format. ++* Other Image Types:: Various other formats are supported. ++* Defining Images:: Convenient ways to define an image for later use. ++* Showing Images:: Convenient ways to display an image once ++ it is defined. ++* Image Cache:: Internal mechanisms of image display. ++ ++Buttons ++ ++* Button Properties:: Button properties with special meanings. ++* Button Types:: Defining common properties for classes of buttons. ++* Making Buttons:: Adding buttons to Emacs buffers. ++* Manipulating Buttons:: Getting and setting properties of buttons. ++* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. ++ ++Abstract Display ++ ++* Abstract Display Functions:: Functions in the Ewoc package. ++* Abstract Display Example:: Example of using Ewoc. ++ ++Display Tables ++ ++* Display Table Format:: What a display table consists of. ++* Active Display Table:: How Emacs selects a display table to use. ++* Glyphs:: How to define a glyph, and what glyphs mean. ++ ++Operating System Interface ++ ++* Starting Up:: Customizing Emacs startup processing. ++* Getting Out:: How exiting works (permanent or temporary). ++* System Environment:: Distinguish the name and kind of system. ++* User Identification:: Finding the name and user id of the user. ++* Time of Day:: Getting the current time. ++* Time Conversion:: Converting a time from numeric form to ++ calendrical data and vice versa. ++* Time Parsing:: Converting a time from numeric form to text ++ and vice versa. ++* Processor Run Time:: Getting the run time used by Emacs. ++* Time Calculations:: Adding, subtracting, comparing times, etc. ++* Timers:: Setting a timer to call a function at a ++ certain time. ++* Idle Timers:: Setting a timer to call a function when Emacs has ++ been idle for a certain length of time. ++* Terminal Input:: Accessing and recording terminal input. ++* Terminal Output:: Controlling and recording terminal output. ++* Sound Output:: Playing sounds on the computer's speaker. ++* X11 Keysyms:: Operating on key symbols for X Windows. ++* Batch Mode:: Running Emacs without terminal interaction. ++* Session Management:: Saving and restoring state with ++ X Session Management. ++ ++Starting Up Emacs ++ ++* Startup Summary:: Sequence of actions Emacs performs at startup. ++* Init File:: Details on reading the init file. ++* Terminal-Specific:: How the terminal-specific Lisp file is read. ++* Command-Line Arguments:: How command-line arguments are processed, ++ and how you can customize them. ++ ++Getting Out of Emacs ++ ++* Killing Emacs:: Exiting Emacs irreversibly. ++* Suspending Emacs:: Exiting Emacs reversibly. ++ ++Terminal Input ++ ++* Input Modes:: Options for how input is processed. ++* Recording Input:: Saving histories of recent or all input events. ++ ++Tips and Conventions ++ ++* Coding Conventions:: Conventions for clean and robust programs. ++* Key Binding Conventions:: Which keys should be bound by which programs. ++* Programming Tips:: Making Emacs code fit smoothly in Emacs. ++* Compilation Tips:: Making compiled code run fast. ++* Warning Tips:: Turning off compiler warnings. ++* Documentation Tips:: Writing readable documentation strings. ++* Comment Tips:: Conventions for writing comments. ++* Library Headers:: Standard headers for library packages. ++ ++GNU Emacs Internals ++ ++* Building Emacs:: How the dumped Emacs is made. ++* Pure Storage:: A kludge to make preloaded Lisp functions sharable. ++* Garbage Collection:: Reclaiming space for Lisp objects no longer used. ++* Memory Usage:: Info about total size of Lisp objects made so far. ++* Writing Emacs Primitives:: Writing C code for Emacs. ++* Object Internals:: Data formats of buffers, windows, processes. ++ ++Object Internals ++ ++* Buffer Internals:: Components of a buffer structure. ++* Window Internals:: Components of a window structure. ++* Process Internals:: Components of a process structure. ++@end detailmenu ++@end menu ++ ++@include intro.texi ++@include objects.texi ++@include numbers.texi ++@include strings.texi ++ ++@include lists.texi ++@include sequences.texi ++@include hash.texi ++@include symbols.texi ++@include eval.texi ++ ++@include control.texi ++@include variables.texi ++@include functions.texi ++@include macros.texi ++ ++@include customize.texi ++@include loading.texi ++@include compile.texi ++@include advice.texi ++ ++@c This includes edebug.texi. ++@include debugging.texi ++@include streams.texi ++@include minibuf.texi ++@include commands.texi ++ ++@include keymaps.texi ++@include modes.texi ++@include help.texi ++@include files.texi ++ ++@include backups.texi ++ ++@c ================ Beginning of Volume 2 ================ ++@c include buffers.texi ++@c include windows.texi ++@c include frames.texi ++ ++@c include positions.texi ++@c include markers.texi ++@c include text.texi ++@c include nonascii.texi ++ ++@c include searching.texi ++@c include syntax.texi ++@c include abbrevs.texi ++@c include processes.texi ++ ++@c include display.texi ++@c include os.texi ++ ++@c MOVE to Emacs Manual: include misc-modes.texi ++ ++@c appendices ++ ++@c REMOVE this: include non-hacker.texi ++ ++@c include anti.texi ++@c include doclicense.texi ++@c include gpl.texi ++@c include tips.texi ++@c include internals.texi ++@c include errors.texi ++@c include locals.texi ++@c include maps.texi ++@c include hooks.texi ++ ++@include index.texi ++ ++@ignore ++@node New Symbols, , Index, Top ++@unnumbered New Symbols Since the Previous Edition ++ ++@printindex tp ++@end ignore ++ ++@bye ++ ++ ++These words prevent "local variables" above from confusing Emacs. ++ ++@ignore ++ arch-tag: 9594760d-8801-4d1b-aeb9-f3b3166b5be2 ++@end ignore +diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi +new file mode 100644 +index 0000000..e4ea5c7 +--- /dev/null ++++ b/doc/lispref/vol2.texi +@@ -0,0 +1,1547 @@ ++\input texinfo @c -*-texinfo-*- ++@c This file is used for printing the GNU Emacs Lisp Reference Manual ++@c in two volumes. It is a modified version of elisp.texi. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c %**start of header ++@setfilename elisp ++@settitle GNU Emacs Lisp Reference Manual: Volume 2 ++@c %**end of header ++ ++@c See two-volume-cross-refs.txt. ++@tex ++\message{Formatting for two volume edition...Volume 2...} ++% ++% Read special toc file, set up in two-volume.make. ++\gdef\tocreadfilename{elisp2-toc-ready.toc} ++% ++% Don't make outlines, they're not needed and \readdatafile can't pay ++% attention to the special definition above. ++\global\let\pdfmakeoutlines=\relax ++% ++% Start volume 2 chapter numbering at 27; this must be listed as chapno26 ++\global\chapno=26 ++@end tex ++ ++@c Version of the manual and of Emacs. ++@c Please remember to update the edition number in README as well. ++@set VERSION 3.0 ++@set EMACSVER 23.1 ++@set DATE July 2009 ++ ++@dircategory Emacs ++@direntry ++* Elisp: (elisp). The Emacs Lisp Reference Manual. ++@end direntry ++ ++@c in general, keep the following line commented out, unless doing a ++@c copy of this manual that will be published. the manual should go ++@c onto the distribution in the full, 8.5 x 11" size. ++@set smallbook ++ ++@ifset smallbook ++@smallbook ++@end ifset ++ ++@c per rms and peterb, use 10pt fonts for the main text, mostly to ++@c save on paper cost. ++@c Do this inside @tex for now, so current makeinfo does not complain. ++@tex ++@ifset smallbook ++@fonttextsize 10 ++\global\let\urlcolor=\Black % don't print links in grayscale ++\global\let\linkcolor=\Black ++@end ifset ++\global\hbadness=6666 % don't worry about not-too-underfull boxes ++@end tex ++ ++@c Combine indices. ++@synindex cp fn ++@syncodeindex vr fn ++@syncodeindex ky fn ++@syncodeindex pg fn ++@c We use the "type index" to index new functions and variables. ++@c @syncodeindex tp fn ++ ++@copying ++This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* ++corresponding to Emacs version @value{EMACSVER}. ++ ++Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, ++1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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 the ++Invariant Sections being ``GNU General Public License,'' 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 ++ ++@titlepage ++@title GNU Emacs Lisp Reference Manual ++@subtitle Volume 2 ++@subtitle For Emacs Version @value{EMACSVER} ++@subtitle Revision @value{VERSION}, @value{DATE} ++ ++@author by Bil Lewis, Dan LaLiberte, Richard Stallman ++@author and the GNU Manual Group ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++ ++@sp 2 ++Published by the Free Software Foundation @* ++51 Franklin St, Fifth Floor @* ++Boston, MA 02110-1301 @* ++USA @* ++ISBN 1-882114-74-4 ++ ++@sp 2 ++Cover art by Etienne Suvasa. ++@end titlepage ++ ++ ++@c Print the tables of contents ++@summarycontents ++@contents ++ ++ ++@ifnottex ++@node Top, Introduction, (dir), (dir) ++@top Emacs Lisp ++ ++This Info file contains edition @value{VERSION} of the GNU Emacs Lisp ++Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. ++@end ifnottex ++ ++@menu ++* Introduction:: Introduction and conventions used. ++ ++* Lisp Data Types:: Data types of objects in Emacs Lisp. ++* Numbers:: Numbers and arithmetic functions. ++* Strings and Characters:: Strings, and functions that work on them. ++* Lists:: Lists, cons cells, and related functions. ++* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. ++ Certain functions act on any kind of sequence. ++ The description of vectors is here as well. ++* Hash Tables:: Very fast lookup-tables. ++* Symbols:: Symbols represent names, uniquely. ++ ++* Evaluation:: How Lisp expressions are evaluated. ++* Control Structures:: Conditionals, loops, nonlocal exits. ++* Variables:: Using symbols in programs to stand for values. ++* Functions:: A function is a Lisp program ++ that can be invoked from other functions. ++* Macros:: Macros are a way to extend the Lisp language. ++* Customization:: Writing customization declarations. ++ ++* Loading:: Reading files of Lisp code into Lisp. ++* Byte Compilation:: Compilation makes programs run faster. ++* Advising Functions:: Adding to the definition of a function. ++* Debugging:: Tools and tips for debugging Lisp programs. ++ ++* Read and Print:: Converting Lisp objects to text and back. ++* Minibuffers:: Using the minibuffer to read input. ++* Command Loop:: How the editor command loop works, ++ and how you can call its subroutines. ++* Keymaps:: Defining the bindings from keys to commands. ++* Modes:: Defining major and minor modes. ++* Documentation:: Writing and using documentation strings. ++ ++* Files:: Accessing files. ++* Backups and Auto-Saving:: Controlling how backups and auto-save ++ files are made. ++* Buffers:: Creating and using buffer objects. ++* Windows:: Manipulating windows and displaying buffers. ++* Frames:: Making multiple system-level windows. ++* Positions:: Buffer positions and motion functions. ++* Markers:: Markers represent positions and update ++ automatically when the text is changed. ++ ++* Text:: Examining and changing text in buffers. ++* Non-ASCII Characters:: Non-ASCII text in buffers and strings. ++* Searching and Matching:: Searching buffers for strings or regexps. ++* Syntax Tables:: The syntax table controls word and list parsing. ++* Abbrevs:: How Abbrev mode works, and its data structures. ++ ++* Processes:: Running and communicating with subprocesses. ++* Display:: Features for controlling the screen display. ++* System Interface:: Getting the user id, system type, environment ++ variables, and other such things. ++ ++Appendices ++ ++* Antinews:: Info for users downgrading to Emacs 22. ++* GNU Free Documentation License:: The license for this documentation. ++* GPL:: Conditions for copying and changing GNU Emacs. ++* Tips:: Advice and coding conventions for Emacs Lisp. ++* GNU Emacs Internals:: Building and dumping Emacs; ++ internal data structures. ++* Standard Errors:: List of all error symbols. ++* Standard Buffer-Local Variables:: ++ List of variables buffer-local in all buffers. ++* Standard Keymaps:: List of standard keymaps. ++* Standard Hooks:: List of standard hook variables. ++ ++* Index:: Index including concepts, functions, variables, ++ and other terms. ++ ++@ignore ++* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. ++@end ignore ++ ++@c Do NOT modify the following 3 lines! They must have this form to ++@c be correctly identified by `texinfo-multiple-files-update'. In ++@c particular, the detailed menu header line MUST be identical to the ++@c value of `texinfo-master-menu-header'. See texnfo-upd.el. ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ --------------------------------- ++ ++Here are other nodes that are inferiors of those already listed, ++mentioned here so you can get to them in one step: ++ ++Introduction ++ ++* Caveats:: Flaws and a request for help. ++* Lisp History:: Emacs Lisp is descended from Maclisp. ++* Conventions:: How the manual is formatted. ++* Version Info:: Which Emacs version is running? ++* Acknowledgements:: The authors, editors, and sponsors of this manual. ++ ++Conventions ++ ++* Some Terms:: Explanation of terms we use in this manual. ++* nil and t:: How the symbols @code{nil} and @code{t} are used. ++* Evaluation Notation:: The format we use for examples of evaluation. ++* Printing Notation:: The format we use when examples print text. ++* Error Messages:: The format we use for examples of errors. ++* Buffer Text Notation:: The format we use for buffer contents in examples. ++* Format of Descriptions:: Notation for describing functions, variables, etc. ++ ++Format of Descriptions ++ ++* A Sample Function Description:: A description of an imaginary ++ function, @code{foo}. ++* A Sample Variable Description:: A description of an imaginary ++ variable, @code{electric-future-map}. ++ ++Lisp Data Types ++ ++* Printed Representation:: How Lisp objects are represented as text. ++* Comments:: Comments and their formatting conventions. ++* Programming Types:: Types found in all Lisp systems. ++* Editing Types:: Types specific to Emacs. ++* Circular Objects:: Read syntax for circular structure. ++* Type Predicates:: Tests related to types. ++* Equality Predicates:: Tests of equality between any two objects. ++ ++Programming Types ++ ++* Integer Type:: Numbers without fractional parts. ++* Floating Point Type:: Numbers with fractional parts and with a large range. ++* Character Type:: The representation of letters, numbers and ++ control characters. ++* Symbol Type:: A multi-use object that refers to a function, ++ variable, or property list, and has a unique identity. ++* Sequence Type:: Both lists and arrays are classified as sequences. ++* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). ++* Array Type:: Arrays include strings and vectors. ++* String Type:: An (efficient) array of characters. ++* Vector Type:: One-dimensional arrays. ++* Char-Table Type:: One-dimensional sparse arrays indexed by characters. ++* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. ++* Hash Table Type:: Super-fast lookup tables. ++* Function Type:: A piece of executable code you can call from elsewhere. ++* Macro Type:: A method of expanding an expression into another ++ expression, more fundamental but less pretty. ++* Primitive Function Type:: A function written in C, callable from Lisp. ++* Byte-Code Type:: A function written in Lisp, then compiled. ++* Autoload Type:: A type used for automatically loading seldom-used ++ functions. ++ ++Character Type ++ ++* Basic Char Syntax:: Syntax for regular characters. ++* General Escape Syntax:: How to specify characters by their codes. ++* Ctl-Char Syntax:: Syntax for control characters. ++* Meta-Char Syntax:: Syntax for meta-characters. ++* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. ++ ++Cons Cell and List Types ++ ++* Box Diagrams:: Drawing pictures of lists. ++* Dotted Pair Notation:: A general syntax for cons cells. ++* Association List Type:: A specially constructed list. ++ ++String Type ++ ++* Syntax for Strings:: How to specify Lisp strings. ++* Non-ASCII in Strings:: International characters in strings. ++* Nonprinting Characters:: Literal unprintable characters in strings. ++* Text Props and Strings:: Strings with text properties. ++ ++Editing Types ++ ++* Buffer Type:: The basic object of editing. ++* Marker Type:: A position in a buffer. ++* Window Type:: Buffers are displayed in windows. ++* Frame Type:: Windows subdivide frames. ++* Terminal Type:: A terminal device displays frames. ++* Window Configuration Type:: Recording the way a frame is subdivided. ++* Frame Configuration Type:: Recording the status of all frames. ++* Process Type:: A subprocess of Emacs running on the underlying OS. ++* Stream Type:: Receive or send characters. ++* Keymap Type:: What function a keystroke invokes. ++* Overlay Type:: How an overlay is represented. ++* Font Type:: Fonts for displaying text. ++ ++Numbers ++ ++* Integer Basics:: Representation and range of integers. ++* Float Basics:: Representation and range of floating point. ++* Predicates on Numbers:: Testing for numbers. ++* Comparison of Numbers:: Equality and inequality predicates. ++* Numeric Conversions:: Converting float to integer and vice versa. ++* Arithmetic Operations:: How to add, subtract, multiply and divide. ++* Rounding Operations:: Explicitly rounding floating point numbers. ++* Bitwise Operations:: Logical and, or, not, shifting. ++* Math Functions:: Trig, exponential and logarithmic functions. ++* Random Numbers:: Obtaining random integers, predictable or not. ++ ++Strings and Characters ++ ++* String Basics:: Basic properties of strings and characters. ++* Predicates for Strings:: Testing whether an object is a string or char. ++* Creating Strings:: Functions to allocate new strings. ++* Modifying Strings:: Altering the contents of an existing string. ++* Text Comparison:: Comparing characters or strings. ++* String Conversion:: Converting to and from characters and strings. ++* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. ++* Case Conversion:: Case conversion functions. ++* Case Tables:: Customizing case conversion. ++ ++Lists ++ ++* Cons Cells:: How lists are made out of cons cells. ++* List-related Predicates:: Is this object a list? Comparing two lists. ++* List Elements:: Extracting the pieces of a list. ++* Building Lists:: Creating list structure. ++* List Variables:: Modifying lists stored in variables. ++* Modifying Lists:: Storing new pieces into an existing list. ++* Sets And Lists:: A list can represent a finite mathematical set. ++* Association Lists:: A list can represent a finite relation or mapping. ++* Rings:: Managing a fixed-size ring of objects. ++ ++Modifying Existing List Structure ++ ++* Setcar:: Replacing an element in a list. ++* Setcdr:: Replacing part of the list backbone. ++ This can be used to remove or add elements. ++* Rearrangement:: Reordering the elements in a list; combining lists. ++ ++Sequences, Arrays, and Vectors ++ ++* Sequence Functions:: Functions that accept any kind of sequence. ++* Arrays:: Characteristics of arrays in Emacs Lisp. ++* Array Functions:: Functions specifically for arrays. ++* Vectors:: Special characteristics of Emacs Lisp vectors. ++* Vector Functions:: Functions specifically for vectors. ++* Char-Tables:: How to work with char-tables. ++* Bool-Vectors:: How to work with bool-vectors. ++ ++Hash Tables ++ ++* Creating Hash:: Functions to create hash tables. ++* Hash Access:: Reading and writing the hash table contents. ++* Defining Hash:: Defining new comparison methods. ++* Other Hash:: Miscellaneous. ++ ++Symbols ++ ++* Symbol Components:: Symbols have names, values, function definitions ++ and property lists. ++* Definitions:: A definition says how a symbol will be used. ++* Creating Symbols:: How symbols are kept unique. ++* Property Lists:: Each symbol has a property list ++ for recording miscellaneous information. ++ ++Property Lists ++ ++* Plists and Alists:: Comparison of the advantages of property ++ lists and association lists. ++* Symbol Plists:: Functions to access symbols' property lists. ++* Other Plists:: Accessing property lists stored elsewhere. ++ ++Evaluation ++ ++* Intro Eval:: Evaluation in the scheme of things. ++* Forms:: How various sorts of objects are evaluated. ++* Quoting:: Avoiding evaluation (to put constants in ++ the program). ++* Eval:: How to invoke the Lisp interpreter explicitly. ++ ++Kinds of Forms ++ ++* Self-Evaluating Forms:: Forms that evaluate to themselves. ++* Symbol Forms:: Symbols evaluate as variables. ++* Classifying Lists:: How to distinguish various sorts of list forms. ++* Function Indirection:: When a symbol appears as the car of a list, ++ we find the real function via the symbol. ++* Function Forms:: Forms that call functions. ++* Macro Forms:: Forms that call macros. ++* Special Forms:: "Special forms" are idiosyncratic primitives, ++ most of them extremely important. ++* Autoloading:: Functions set up to load files ++ containing their real definitions. ++ ++Control Structures ++ ++* Sequencing:: Evaluation in textual order. ++* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. ++* Combining Conditions:: @code{and}, @code{or}, @code{not}. ++* Iteration:: @code{while} loops. ++* Nonlocal Exits:: Jumping out of a sequence. ++ ++Nonlocal Exits ++ ++* Catch and Throw:: Nonlocal exits for the program's own purposes. ++* Examples of Catch:: Showing how such nonlocal exits can be written. ++* Errors:: How errors are signaled and handled. ++* Cleanups:: Arranging to run a cleanup form if an ++ error happens. ++ ++Errors ++ ++* Signaling Errors:: How to report an error. ++* Processing of Errors:: What Emacs does when you report an error. ++* Handling Errors:: How you can trap errors and continue execution. ++* Error Symbols:: How errors are classified for trapping them. ++ ++Variables ++ ++* Global Variables:: Variable values that exist permanently, everywhere. ++* Constant Variables:: Certain "variables" have values that never change. ++* Local Variables:: Variable values that exist only temporarily. ++* Void Variables:: Symbols that lack values. ++* Defining Variables:: A definition says a symbol is used as a variable. ++* Tips for Defining:: Things you should think about when you ++ define a variable. ++* Accessing Variables:: Examining values of variables whose names ++ are known only at run time. ++* Setting Variables:: Storing new values in variables. ++* Variable Scoping:: How Lisp chooses among local and global values. ++* Buffer-Local Variables:: Variable values in effect only in one buffer. ++* File Local Variables:: Handling local variable lists in files. ++* Directory Local Variables:: Local variables common to all files in a ++ directory. ++* Frame-Local Variables:: Frame-local bindings for variables. ++* Variable Aliases:: Variables that are aliases for other variables. ++* Variables with Restricted Values:: Non-constant variables whose value can ++ @emph{not} be an arbitrary Lisp object. ++ ++Scoping Rules for Variable Bindings ++ ++* Scope:: Scope means where in the program a value ++ is visible. Comparison with other languages. ++* Extent:: Extent means how long in time a value exists. ++* Impl of Scope:: Two ways to implement dynamic scoping. ++* Using Scoping:: How to use dynamic scoping carefully and ++ avoid problems. ++ ++Buffer-Local Variables ++ ++* Intro to Buffer-Local:: Introduction and concepts. ++* Creating Buffer-Local:: Creating and destroying buffer-local bindings. ++* Default Value:: The default value is seen in buffers ++ that don't have their own buffer-local values. ++ ++Functions ++ ++* What Is a Function:: Lisp functions vs. primitives; terminology. ++* Lambda Expressions:: How functions are expressed as Lisp objects. ++* Function Names:: A symbol can serve as the name of a function. ++* Defining Functions:: Lisp expressions for defining functions. ++* Calling Functions:: How to use an existing function. ++* Mapping Functions:: Applying a function to each element of a list, etc. ++* Anonymous Functions:: Lambda expressions are functions with no names. ++* Function Cells:: Accessing or setting the function definition ++ of a symbol. ++* Obsolete Functions:: Declaring functions obsolete. ++* Inline Functions:: Defining functions that the compiler ++ will open code. ++* Declaring Functions:: Telling the compiler that a function is defined. ++* Function Safety:: Determining whether a function is safe to call. ++* Related Topics:: Cross-references to specific Lisp primitives ++ that have a special bearing on how ++ functions work. ++ ++Lambda Expressions ++ ++* Lambda Components:: The parts of a lambda expression. ++* Simple Lambda:: A simple example. ++* Argument List:: Details and special features of argument lists. ++* Function Documentation:: How to put documentation in a function. ++ ++Macros ++ ++* Simple Macro:: A basic example. ++* Expansion:: How, when and why macros are expanded. ++* Compiling Macros:: How macros are expanded by the compiler. ++* Defining Macros:: How to write a macro definition. ++* Backquote:: Easier construction of list structure. ++* Problems with Macros:: Don't evaluate the macro arguments too many times. ++ Don't hide the user's variables. ++* Indenting Macros:: Specifying how to indent macro calls. ++ ++Common Problems Using Macros ++ ++* Wrong Time:: Do the work in the expansion, not in the macro. ++* Argument Evaluation:: The expansion should evaluate each macro arg once. ++* Surprising Local Vars:: Local variable bindings in the expansion ++ require special care. ++* Eval During Expansion:: Don't evaluate them; put them in the expansion. ++* Repeated Expansion:: Avoid depending on how many times expansion is done. ++ ++Writing Customization Definitions ++ ++* Common Keywords:: Common keyword arguments for all kinds of ++ customization declarations. ++* Group Definitions:: Writing customization group definitions. ++* Variable Definitions:: Declaring user options. ++* Customization Types:: Specifying the type of a user option. ++ ++Customization Types ++ ++* Simple Types:: Simple customization types: sexp, integer, number, ++ string, file, directory, alist. ++* Composite Types:: Build new types from other types or data. ++* Splicing into Lists:: Splice elements into list with @code{:inline}. ++* Type Keywords:: Keyword-argument pairs in a customization type. ++* Defining New Types:: Give your type a name. ++ ++Loading ++ ++* How Programs Do Loading:: The @code{load} function and others. ++* Load Suffixes:: Details about the suffixes that @code{load} tries. ++* Library Search:: Finding a library to load. ++* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. ++* Autoload:: Setting up a function to autoload. ++* Repeated Loading:: Precautions about loading a file twice. ++* Named Features:: Loading a library if it isn't already loaded. ++* Where Defined:: Finding which file defined a certain symbol. ++* Unloading:: How to "unload" a library that was loaded. ++* Hooks for Loading:: Providing code to be run when ++ particular libraries are loaded. ++ ++Byte Compilation ++ ++* Speed of Byte-Code:: An example of speedup from byte compilation. ++* Compilation Functions:: Byte compilation functions. ++* Docs and Compilation:: Dynamic loading of documentation strings. ++* Dynamic Loading:: Dynamic loading of individual functions. ++* Eval During Compile:: Code to be evaluated when you compile. ++* Compiler Errors:: Handling compiler error messages. ++* Byte-Code Objects:: The data type used for byte-compiled functions. ++* Disassembly:: Disassembling byte-code; how to read byte-code. ++ ++Advising Emacs Lisp Functions ++ ++* Simple Advice:: A simple example to explain the basics of advice. ++* Defining Advice:: Detailed description of @code{defadvice}. ++* Around-Advice:: Wrapping advice around a function's definition. ++* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. ++* Activation of Advice:: Advice doesn't do anything until you activate it. ++* Enabling Advice:: You can enable or disable each piece of advice. ++* Preactivation:: Preactivation is a way of speeding up the ++ loading of compiled advice. ++* Argument Access in Advice:: How advice can access the function's arguments. ++* Advising Primitives:: Accessing arguments when advising a primitive. ++* Combined Definition:: How advice is implemented. ++ ++Debugging Lisp Programs ++ ++* Debugger:: How the Emacs Lisp debugger is implemented. ++* Edebug:: A source-level Emacs Lisp debugger. ++* Syntax Errors:: How to find syntax errors. ++* Test Coverage:: Ensuring you have tested all branches in your code. ++* Compilation Errors:: How to find errors that show up in ++ byte compilation. ++ ++The Lisp Debugger ++ ++* Error Debugging:: Entering the debugger when an error happens. ++* Infinite Loops:: Stopping and debugging a program that doesn't exit. ++* Function Debugging:: Entering it when a certain function is called. ++* Explicit Debug:: Entering it at a certain point in the program. ++* Using Debugger:: What the debugger does; what you see while in it. ++* Debugger Commands:: Commands used while in the debugger. ++* Invoking the Debugger:: How to call the function @code{debug}. ++* Internals of Debugger:: Subroutines of the debugger, and global variables. ++ ++Edebug ++ ++* Using Edebug:: Introduction to use of Edebug. ++* Instrumenting:: You must instrument your code ++ in order to debug it with Edebug. ++* Edebug Execution Modes:: Execution modes, stopping more or less often. ++* Jumping:: Commands to jump to a specified place. ++* Edebug Misc:: Miscellaneous commands. ++* Breaks:: Setting breakpoints to make the program stop. ++* Trapping Errors:: Trapping errors with Edebug. ++* Edebug Views:: Views inside and outside of Edebug. ++* Edebug Eval:: Evaluating expressions within Edebug. ++* Eval List:: Expressions whose values are displayed ++ each time you enter Edebug. ++* Printing in Edebug:: Customization of printing. ++* Trace Buffer:: How to produce trace output in a buffer. ++* Coverage Testing:: How to test evaluation coverage. ++* The Outside Context:: Data that Edebug saves and restores. ++* Edebug and Macros:: Specifying how to handle macro calls. ++* Edebug Options:: Option variables for customizing Edebug. ++ ++Breaks ++ ++* Breakpoints:: Breakpoints at stop points. ++* Global Break Condition:: Breaking on an event. ++* Source Breakpoints:: Embedding breakpoints in source code. ++ ++The Outside Context ++ ++* Checking Whether to Stop::When Edebug decides what to do. ++* Edebug Display Update:: When Edebug updates the display. ++* Edebug Recursive Edit:: When Edebug stops execution. ++ ++Edebug and Macros ++ ++* Instrumenting Macro Calls::The basic problem. ++* Specification List:: How to specify complex patterns of evaluation. ++* Backtracking:: What Edebug does when matching fails. ++* Specification Examples:: To help understand specifications. ++ ++Debugging Invalid Lisp Syntax ++ ++* Excess Open:: How to find a spurious open paren or missing close. ++* Excess Close:: How to find a spurious close paren or missing open. ++ ++Reading and Printing Lisp Objects ++ ++* Streams Intro:: Overview of streams, reading and printing. ++* Input Streams:: Various data types that can be used as ++ input streams. ++* Input Functions:: Functions to read Lisp objects from text. ++* Output Streams:: Various data types that can be used as ++ output streams. ++* Output Functions:: Functions to print Lisp objects as text. ++* Output Variables:: Variables that control what the printing ++ functions do. ++ ++Minibuffers ++ ++* Intro to Minibuffers:: Basic information about minibuffers. ++* Text from Minibuffer:: How to read a straight text string. ++* Object from Minibuffer:: How to read a Lisp object or expression. ++* Minibuffer History:: Recording previous minibuffer inputs ++ so the user can reuse them. ++* Initial Input:: Specifying initial contents for the minibuffer. ++* Completion:: How to invoke and customize completion. ++* Yes-or-No Queries:: Asking a question with a simple answer. ++* Multiple Queries:: Asking a series of similar questions. ++* Reading a Password:: Reading a password from the terminal. ++* Minibuffer Commands:: Commands used as key bindings in minibuffers. ++* Minibuffer Contents:: How such commands access the minibuffer text. ++* Minibuffer Windows:: Operating on the special minibuffer windows. ++* Recursive Mini:: Whether recursive entry to minibuffer is allowed. ++* Minibuffer Misc:: Various customization hooks and variables. ++ ++Completion ++ ++* Basic Completion:: Low-level functions for completing strings. ++ (These are too low level to use the minibuffer.) ++* Minibuffer Completion:: Invoking the minibuffer with completion. ++* Completion Commands:: Minibuffer commands that do completion. ++* High-Level Completion:: Convenient special cases of completion ++ (reading buffer name, file name, etc.). ++* Reading File Names:: Using completion to read file names and ++ shell commands. ++* Completion Styles:: Specifying rules for performing completion. ++* Programmed Completion:: Writing your own completion-function. ++ ++Command Loop ++ ++* Command Overview:: How the command loop reads commands. ++* Defining Commands:: Specifying how a function should read arguments. ++* Interactive Call:: Calling a command, so that it will read arguments. ++* Distinguish Interactive:: Making a command distinguish interactive calls. ++* Command Loop Info:: Variables set by the command loop for you to examine. ++* Adjusting Point:: Adjustment of point after a command. ++* Input Events:: What input looks like when you read it. ++* Reading Input:: How to read input events from the keyboard or mouse. ++* Special Events:: Events processed immediately and individually. ++* Waiting:: Waiting for user input or elapsed time. ++* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. ++* Prefix Command Arguments:: How the commands to set prefix args work. ++* Recursive Editing:: Entering a recursive edit, ++ and why you usually shouldn't. ++* Disabling Commands:: How the command loop handles disabled commands. ++* Command History:: How the command history is set up, and how accessed. ++* Keyboard Macros:: How keyboard macros are implemented. ++ ++Defining Commands ++ ++* Using Interactive:: General rules for @code{interactive}. ++* Interactive Codes:: The standard letter-codes for reading arguments ++ in various ways. ++* Interactive Examples:: Examples of how to read interactive arguments. ++ ++Input Events ++ ++* Keyboard Events:: Ordinary characters--keys with symbols on them. ++* Function Keys:: Function keys--keys with names, not symbols. ++* Mouse Events:: Overview of mouse events. ++* Click Events:: Pushing and releasing a mouse button. ++* Drag Events:: Moving the mouse before releasing the button. ++* Button-Down Events:: A button was pushed and not yet released. ++* Repeat Events:: Double and triple click (or drag, or down). ++* Motion Events:: Just moving the mouse, not pushing a button. ++* Focus Events:: Moving the mouse between frames. ++* Misc Events:: Other events the system can generate. ++* Event Examples:: Examples of the lists for mouse events. ++* Classifying Events:: Finding the modifier keys in an event symbol. ++ Event types. ++* Accessing Mouse:: Functions to extract info from mouse events. ++* Accessing Scroll:: Functions to get info from scroll bar events. ++* Strings of Events:: Special considerations for putting ++ keyboard character events in a string. ++ ++Reading Input ++ ++* Key Sequence Input:: How to read one key sequence. ++* Reading One Event:: How to read just one event. ++* Event Mod:: How Emacs modifies events as they are read. ++* Invoking the Input Method:: How reading an event uses the input method. ++* Quoted Character Input:: Asking the user to specify a character. ++* Event Input Misc:: How to reread or throw away input events. ++ ++Keymaps ++ ++* Key Sequences:: Key sequences as Lisp objects. ++* Keymap Basics:: Basic concepts of keymaps. ++* Format of Keymaps:: What a keymap looks like as a Lisp object. ++* Creating Keymaps:: Functions to create and copy keymaps. ++* Inheritance and Keymaps:: How one keymap can inherit the bindings ++ of another keymap. ++* Prefix Keys:: Defining a key with a keymap as its definition. ++* Active Keymaps:: How Emacs searches the active keymaps ++ for a key binding. ++* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. ++* Controlling Active Maps:: Each buffer has a local keymap ++ to override the standard (global) bindings. ++ A minor mode can also override them. ++* Key Lookup:: Finding a key's binding in one keymap. ++* Functions for Key Lookup:: How to request key lookup. ++* Changing Key Bindings:: Redefining a key in a keymap. ++* Remapping Commands:: A keymap can translate one command to another. ++* Translation Keymaps:: Keymaps for translating sequences of events. ++* Key Binding Commands:: Interactive interfaces for redefining keys. ++* Scanning Keymaps:: Looking through all keymaps, for printing help. ++* Menu Keymaps:: Defining a menu as a keymap. ++ ++Menu Keymaps ++ ++* Defining Menus:: How to make a keymap that defines a menu. ++* Mouse Menus:: How users actuate the menu with the mouse. ++* Keyboard Menus:: How users actuate the menu with the keyboard. ++* Menu Example:: Making a simple menu. ++* Menu Bar:: How to customize the menu bar. ++* Tool Bar:: A tool bar is a row of images. ++* Modifying Menus:: How to add new items to a menu. ++ ++Defining Menus ++ ++* Simple Menu Items:: A simple kind of menu key binding, ++ limited in capabilities. ++* Extended Menu Items:: More powerful menu item definitions ++ let you specify keywords to enable ++ various features. ++* Menu Separators:: Drawing a horizontal line through a menu. ++* Alias Menu Items:: Using command aliases in menu items. ++ ++Major and Minor Modes ++ ++* Hooks:: How to use hooks; how to write code that provides hooks. ++* Major Modes:: Defining major modes. ++* Minor Modes:: Defining minor modes. ++* Mode Line Format:: Customizing the text that appears in the mode line. ++* Imenu:: How a mode can provide a menu ++ of definitions in the buffer. ++* Font Lock Mode:: How modes can highlight text according to syntax. ++* Desktop Save Mode:: How modes can have buffer state saved between ++ Emacs sessions. ++ ++Hooks ++ ++* Running Hooks:: How to run a hook. ++* Setting Hooks:: How to put functions on a hook, or remove them. ++ ++Major Modes ++ ++* Major Mode Basics:: ++* Major Mode Conventions:: Coding conventions for keymaps, etc. ++* Auto Major Mode:: How Emacs chooses the major mode automatically. ++* Mode Help:: Finding out how to use a mode. ++* Derived Modes:: Defining a new major mode based on another major ++ mode. ++* Generic Modes:: Defining a simple major mode that supports ++ comment syntax and Font Lock mode. ++* Mode Hooks:: Hooks run at the end of major mode functions. ++* Example Major Modes:: Text mode and Lisp modes. ++ ++Minor Modes ++ ++* Minor Mode Conventions:: Tips for writing a minor mode. ++* Keymaps and Minor Modes:: How a minor mode can have its own keymap. ++* Defining Minor Modes:: A convenient facility for defining minor modes. ++ ++Mode Line Format ++ ++* Mode Line Basics:: Basic ideas of mode line control. ++* Mode Line Data:: The data structure that controls the mode line. ++* Mode Line Top:: The top level variable, mode-line-format. ++* Mode Line Variables:: Variables used in that data structure. ++* %-Constructs:: Putting information into a mode line. ++* Properties in Mode:: Using text properties in the mode line. ++* Header Lines:: Like a mode line, but at the top. ++* Emulating Mode Line:: Formatting text as the mode line would. ++ ++Font Lock Mode ++ ++* Font Lock Basics:: Overview of customizing Font Lock. ++* Search-based Fontification:: Fontification based on regexps. ++* Customizing Keywords:: Customizing search-based fontification. ++* Other Font Lock Variables:: Additional customization facilities. ++* Levels of Font Lock:: Each mode can define alternative levels ++ so that the user can select more or less. ++* Precalculated Fontification:: How Lisp programs that produce the buffer ++ contents can also specify how to fontify it. ++* Faces for Font Lock:: Special faces specifically for Font Lock. ++* Syntactic Font Lock:: Fontification based on syntax tables. ++* Setting Syntax Properties:: Defining character syntax based on context ++ using the Font Lock mechanism. ++* Multiline Font Lock:: How to coerce Font Lock into properly ++ highlighting multiline constructs. ++ ++Multiline Font Lock Constructs ++ ++* Font Lock Multiline:: Marking multiline chunks with a text property. ++* Region to Fontify:: Controlling which region gets refontified ++ after a buffer change. ++ ++Documentation ++ ++* Documentation Basics:: Good style for doc strings. ++ Where to put them. How Emacs stores them. ++* Accessing Documentation:: How Lisp programs can access doc strings. ++* Keys in Documentation:: Substituting current key bindings. ++* Describing Characters:: Making printable descriptions of ++ non-printing characters and key sequences. ++* Help Functions:: Subroutines used by Emacs help facilities. ++ ++Files ++ ++* Visiting Files:: Reading files into Emacs buffers for editing. ++* Saving Buffers:: Writing changed buffers back into files. ++* Reading from Files:: Reading files into buffers without visiting. ++* Writing to Files:: Writing new files from parts of buffers. ++* File Locks:: Locking and unlocking files, to prevent ++ simultaneous editing by two people. ++* Information about Files:: Testing existence, accessibility, size of files. ++* Changing Files:: Renaming files, changing protection, etc. ++* File Names:: Decomposing and expanding file names. ++* Contents of Directories:: Getting a list of the files in a directory. ++* Create/Delete Dirs:: Creating and Deleting Directories. ++* Magic File Names:: Defining "magic" special handling ++ for certain file names. ++* Format Conversion:: Conversion to and from various file formats. ++ ++Visiting Files ++ ++* Visiting Functions:: The usual interface functions for visiting. ++* Subroutines of Visiting:: Lower-level subroutines that they use. ++ ++Information about Files ++ ++* Testing Accessibility:: Is a given file readable? Writable? ++* Kinds of Files:: Is it a directory? A symbolic link? ++* Truenames:: Eliminating symbolic links from a file name. ++* File Attributes:: How large is it? Any other names? Etc. ++* Locating Files:: How to find a file in standard places. ++ ++File Names ++ ++* File Name Components:: The directory part of a file name, and the rest. ++* Relative File Names:: Some file names are relative to a current directory. ++* Directory Names:: A directory's name as a directory ++ is different from its name as a file. ++* File Name Expansion:: Converting relative file names to absolute ones. ++* Unique File Names:: Generating names for temporary files. ++* File Name Completion:: Finding the completions for a given file name. ++* Standard File Names:: If your package uses a fixed file name, ++ how to handle various operating systems simply. ++ ++File Format Conversion ++ ++* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. ++* Format Conversion Round-Trip:: Using @code{format-alist}. ++* Format Conversion Piecemeal:: Specifying non-paired conversion. ++ ++Backups and Auto-Saving ++ ++* Backup Files:: How backup files are made; how their names ++ are chosen. ++* Auto-Saving:: How auto-save files are made; how their ++ names are chosen. ++* Reverting:: @code{revert-buffer}, and how to customize ++ what it does. ++ ++Backup Files ++ ++* Making Backups:: How Emacs makes backup files, and when. ++* Rename or Copy:: Two alternatives: renaming the old file ++ or copying it. ++* Numbered Backups:: Keeping multiple backups for each source file. ++* Backup Names:: How backup file names are computed; customization. ++ ++Buffers ++ ++* Buffer Basics:: What is a buffer? ++* Current Buffer:: Designating a buffer as current ++ so that primitives will access its contents. ++* Buffer Names:: Accessing and changing buffer names. ++* Buffer File Name:: The buffer file name indicates which file ++ is visited. ++* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. ++* Modification Time:: Determining whether the visited file was changed ++ ``behind Emacs's back''. ++* Read Only Buffers:: Modifying text is not allowed in a ++ read-only buffer. ++* The Buffer List:: How to look at all the existing buffers. ++* Creating Buffers:: Functions that create buffers. ++* Killing Buffers:: Buffers exist until explicitly killed. ++* Indirect Buffers:: An indirect buffer shares text with some ++ other buffer. ++* Swapping Text:: Swapping text between two buffers. ++* Buffer Gap:: The gap in the buffer. ++ ++Windows ++ ++* Basic Windows:: Basic information on using windows. ++* Splitting Windows:: Splitting one window into two windows. ++* Deleting Windows:: Deleting a window gives its space to other windows. ++* Selecting Windows:: The selected window is the one that you edit in. ++* Cyclic Window Ordering:: Moving around the existing windows. ++* Buffers and Windows:: Each window displays the contents of a buffer. ++* Displaying Buffers:: Higher-level functions for displaying a buffer ++ and choosing a window for it. ++* Choosing Window:: How to choose a window for displaying a buffer. ++* Dedicated Windows:: How to avoid displaying another buffer in ++ a specific window. ++* Window Point:: Each window has its own location of point. ++* Window Start and End:: Buffer positions indicating which text is ++ on-screen in a window. ++* Textual Scrolling:: Moving text up and down through the window. ++* Vertical Scrolling:: Moving the contents up and down on the window. ++* Horizontal Scrolling:: Moving the contents sideways on the window. ++* Size of Window:: Accessing the size of a window. ++* Resizing Windows:: Changing the size of a window. ++* Coordinates and Windows:: Converting coordinates to windows. ++* Window Tree:: The layout and sizes of all windows in a frame. ++* Window Configurations:: Saving and restoring the state of the screen. ++* Window Parameters:: Associating additional information with windows. ++* Window Hooks:: Hooks for scrolling, window size changes, ++ redisplay going past a certain point, ++ or window configuration changes. ++ ++Frames ++ ++* Creating Frames:: Creating additional frames. ++* Multiple Terminals:: Displaying on several different devices. ++* Frame Parameters:: Controlling frame size, position, font, etc. ++* Terminal Parameters:: Parameters common for all frames on terminal. ++* Frame Titles:: Automatic updating of frame titles. ++* Deleting Frames:: Frames last until explicitly deleted. ++* Finding All Frames:: How to examine all existing frames. ++* Frames and Windows:: A frame contains windows; ++ display of text always works through windows. ++* Minibuffers and Frames:: How a frame finds the minibuffer to use. ++* Input Focus:: Specifying the selected frame. ++* Visibility of Frames:: Frames may be visible or invisible, or icons. ++* Raising and Lowering:: Raising a frame makes it hide other windows; ++ lowering it makes the others hide it. ++* Frame Configurations:: Saving the state of all frames. ++* Mouse Tracking:: Getting events that say when the mouse moves. ++* Mouse Position:: Asking where the mouse is, or moving it. ++* Pop-Up Menus:: Displaying a menu for the user to select from. ++* Dialog Boxes:: Displaying a box to ask yes or no. ++* Pointer Shape:: Specifying the shape of the mouse pointer. ++* Window System Selections::Transferring text to and from other X clients. ++* Drag and Drop:: Internals of Drag-and-Drop implementation. ++* Color Names:: Getting the definitions of color names. ++* Text Terminal Colors:: Defining colors for text-only terminals. ++* Resources:: Getting resource values from the server. ++* Display Feature Testing:: Determining the features of a terminal. ++ ++Frame Parameters ++ ++* Parameter Access:: How to change a frame's parameters. ++* Initial Parameters:: Specifying frame parameters when you make a frame. ++* Window Frame Parameters:: List of frame parameters for window systems. ++* Size and Position:: Changing the size and position of a frame. ++* Geometry:: Parsing geometry specifications. ++ ++Window Frame Parameters ++ ++* Basic Parameters:: Parameters that are fundamental. ++* Position Parameters:: The position of the frame on the screen. ++* Size Parameters:: Frame's size. ++* Layout Parameters:: Size of parts of the frame, and ++ enabling or disabling some parts. ++* Buffer Parameters:: Which buffers have been or should be shown. ++* Management Parameters:: Communicating with the window manager. ++* Cursor Parameters:: Controlling the cursor appearance. ++* Font and Color Parameters:: Fonts and colors for the frame text. ++ ++Positions ++ ++* Point:: The special position where editing takes place. ++* Motion:: Changing point. ++* Excursions:: Temporary motion and buffer changes. ++* Narrowing:: Restricting editing to a portion of the buffer. ++ ++Motion ++ ++* Character Motion:: Moving in terms of characters. ++* Word Motion:: Moving in terms of words. ++* Buffer End Motion:: Moving to the beginning or end of the buffer. ++* Text Lines:: Moving in terms of lines of text. ++* Screen Lines:: Moving in terms of lines as displayed. ++* List Motion:: Moving by parsing lists and sexps. ++* Skipping Characters:: Skipping characters belonging to a certain set. ++ ++Markers ++ ++* Overview of Markers:: The components of a marker, and how it relocates. ++* Predicates on Markers:: Testing whether an object is a marker. ++* Creating Markers:: Making empty markers or markers at certain places. ++* Information from Markers::Finding the marker's buffer or character position. ++* Marker Insertion Types:: Two ways a marker can relocate when you ++ insert where it points. ++* Moving Markers:: Moving the marker to a new buffer or position. ++* The Mark:: How "the mark" is implemented with a marker. ++* The Region:: How to access "the region". ++ ++Text ++ ++* Near Point:: Examining text in the vicinity of point. ++* Buffer Contents:: Examining text in a general fashion. ++* Comparing Text:: Comparing substrings of buffers. ++* Insertion:: Adding new text to a buffer. ++* Commands for Insertion:: User-level commands to insert text. ++* Deletion:: Removing text from a buffer. ++* User-Level Deletion:: User-level commands to delete text. ++* The Kill Ring:: Where removed text sometimes is saved for ++ later use. ++* Undo:: Undoing changes to the text of a buffer. ++* Maintaining Undo:: How to enable and disable undo information. ++ How to control how much information is kept. ++* Filling:: Functions for explicit filling. ++* Margins:: How to specify margins for filling commands. ++* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix ++ from context. ++* Auto Filling:: How auto-fill mode is implemented to break lines. ++* Sorting:: Functions for sorting parts of the buffer. ++* Columns:: Computing horizontal positions, and using them. ++* Indentation:: Functions to insert or adjust indentation. ++* Case Changes:: Case conversion of parts of the buffer. ++* Text Properties:: Assigning Lisp property lists to text characters. ++* Substitution:: Replacing a given character wherever it appears. ++* Transposition:: Swapping two portions of a buffer. ++* Registers:: How registers are implemented. Accessing ++ the text or position stored in a register. ++* Base 64:: Conversion to or from base 64 encoding. ++* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". ++* Atomic Changes:: Installing several buffer changes "atomically". ++* Change Hooks:: Supplying functions to be run when text is changed. ++ ++The Kill Ring ++ ++* Kill Ring Concepts:: What text looks like in the kill ring. ++* Kill Functions:: Functions that kill text. ++* Yanking:: How yanking is done. ++* Yank Commands:: Commands that access the kill ring. ++* Low-Level Kill Ring:: Functions and variables for kill ring access. ++* Internals of Kill Ring:: Variables that hold kill ring data. ++ ++Indentation ++ ++* Primitive Indent:: Functions used to count and insert indentation. ++* Mode-Specific Indent:: Customize indentation for different modes. ++* Region Indent:: Indent all the lines in a region. ++* Relative Indent:: Indent the current line based on previous lines. ++* Indent Tabs:: Adjustable, typewriter-like tab stops. ++* Motion by Indent:: Move to first non-blank character. ++ ++Text Properties ++ ++* Examining Properties:: Looking at the properties of one character. ++* Changing Properties:: Setting the properties of a range of text. ++* Property Search:: Searching for where a property changes value. ++* Special Properties:: Particular properties with special meanings. ++* Format Properties:: Properties for representing formatting of text. ++* Sticky Properties:: How inserted text gets properties from ++ neighboring text. ++* Lazy Properties:: Computing text properties in a lazy fashion ++ only when text is examined. ++* Clickable Text:: Using text properties to make regions of text ++ do something when you click on them. ++* Fields:: The @code{field} property defines ++ fields within the buffer. ++* Not Intervals:: Why text properties do not use ++ Lisp-visible text intervals. ++ ++Non-@acronym{ASCII} Characters ++ ++* Text Representations:: How Emacs represents text. ++* Converting Representations:: Converting unibyte to multibyte and vice versa. ++* Selecting a Representation:: Treating a byte sequence as unibyte or multi. ++* Character Codes:: How unibyte and multibyte relate to ++ codes of individual characters. ++* Character Properties:: Character attributes that define their ++ behavior and handling. ++* Character Sets:: The space of possible character codes ++ is divided into various character sets. ++* Scanning Charsets:: Which character sets are used in a buffer? ++* Translation of Characters:: Translation tables are used for conversion. ++* Coding Systems:: Coding systems are conversions for saving files. ++* Input Methods:: Input methods allow users to enter various ++ non-ASCII characters without special keyboards. ++* Locales:: Interacting with the POSIX locale. ++ ++Coding Systems ++ ++* Coding System Basics:: Basic concepts. ++* Encoding and I/O:: How file I/O functions handle coding systems. ++* Lisp and Coding Systems:: Functions to operate on coding system names. ++* User-Chosen Coding Systems:: Asking the user to choose a coding system. ++* Default Coding Systems:: Controlling the default choices. ++* Specifying Coding Systems:: Requesting a particular coding system ++ for a single file operation. ++* Explicit Encoding:: Encoding or decoding text without doing I/O. ++* Terminal I/O Encoding:: Use of encoding for terminal I/O. ++* MS-DOS File Types:: How DOS "text" and "binary" files ++ relate to coding systems. ++ ++Searching and Matching ++ ++* String Search:: Search for an exact match. ++* Searching and Case:: Case-independent or case-significant searching. ++* Regular Expressions:: Describing classes of strings. ++* Regexp Search:: Searching for a match for a regexp. ++* POSIX Regexps:: Searching POSIX-style for the longest match. ++* Match Data:: Finding out which part of the text matched, ++ after a string or regexp search. ++* Search and Replace:: Commands that loop, searching and replacing. ++* Standard Regexps:: Useful regexps for finding sentences, pages,... ++ ++Regular Expressions ++ ++* Syntax of Regexps:: Rules for writing regular expressions. ++* Regexp Example:: Illustrates regular expression syntax. ++* Regexp Functions:: Functions for operating on regular expressions. ++ ++Syntax of Regular Expressions ++ ++* Regexp Special:: Special characters in regular expressions. ++* Char Classes:: Character classes used in regular expressions. ++* Regexp Backslash:: Backslash-sequences in regular expressions. ++ ++The Match Data ++ ++* Replacing Match:: Replacing a substring that was matched. ++* Simple Match Data:: Accessing single items of match data, ++ such as where a particular subexpression started. ++* Entire Match Data:: Accessing the entire match data at once, as a list. ++* Saving Match Data:: Saving and restoring the match data. ++ ++Syntax Tables ++ ++* Syntax Basics:: Basic concepts of syntax tables. ++* Syntax Descriptors:: How characters are classified. ++* Syntax Table Functions:: How to create, examine and alter syntax tables. ++* Syntax Properties:: Overriding syntax with text properties. ++* Motion and Syntax:: Moving over characters with certain syntaxes. ++* Parsing Expressions:: Parsing balanced expressions ++ using the syntax table. ++* Standard Syntax Tables:: Syntax tables used by various major modes. ++* Syntax Table Internals:: How syntax table information is stored. ++* Categories:: Another way of classifying character syntax. ++ ++Syntax Descriptors ++ ++* Syntax Class Table:: Table of syntax classes. ++* Syntax Flags:: Additional flags each character can have. ++ ++Parsing Expressions ++ ++* Motion via Parsing:: Motion functions that work by parsing. ++* Position Parse:: Determining the syntactic state of a position. ++* Parser State:: How Emacs represents a syntactic state. ++* Low-Level Parsing:: Parsing across a specified region. ++* Control Parsing:: Parameters that affect parsing. ++ ++Abbrevs and Abbrev Expansion ++ ++* Abbrev Mode:: Setting up Emacs for abbreviation. ++* Abbrev Tables:: Creating and working with abbrev tables. ++* Defining Abbrevs:: Specifying abbreviations and their expansions. ++* Abbrev Files:: Saving abbrevs in files. ++* Abbrev Expansion:: Controlling expansion; expansion subroutines. ++* Standard Abbrev Tables:: Abbrev tables used by various major modes. ++* Abbrev Properties:: How to read and set abbrev properties. ++ Which properties have which effect. ++* Abbrev Table Properties:: How to read and set abbrev table properties. ++ Which properties have which effect. ++ ++Processes ++ ++* Subprocess Creation:: Functions that start subprocesses. ++* Shell Arguments:: Quoting an argument to pass it to a shell. ++* Synchronous Processes:: Details of using synchronous subprocesses. ++* Asynchronous Processes:: Starting up an asynchronous subprocess. ++* Deleting Processes:: Eliminating an asynchronous subprocess. ++* Process Information:: Accessing run-status and other attributes. ++* Input to Processes:: Sending input to an asynchronous subprocess. ++* Signals to Processes:: Stopping, continuing or interrupting ++ an asynchronous subprocess. ++* Output from Processes:: Collecting output from an asynchronous subprocess. ++* Sentinels:: Sentinels run when process run-status changes. ++* Query Before Exit:: Whether to query if exiting will kill a process. ++* System Processes:: Accessing other processes running on your system. ++* Transaction Queues:: Transaction-based communication with subprocesses. ++* Network:: Opening network connections. ++* Network Servers:: Network servers let Emacs accept net connections. ++* Datagrams:: UDP network connections. ++* Low-Level Network:: Lower-level but more general function ++ to create connections and servers. ++* Misc Network:: Additional relevant functions for ++ network connections. ++* Serial Ports:: Communicating with serial ports. ++* Byte Packing:: Using bindat to pack and unpack binary data. ++ ++Receiving Output from Processes ++ ++* Process Buffers:: If no filter, output is put in a buffer. ++* Filter Functions:: Filter functions accept output from the process. ++* Decoding Output:: Filters can get unibyte or multibyte strings. ++* Accepting Output:: How to wait until process output arrives. ++ ++Low-Level Network Access ++ ++* Network Processes:: Using @code{make-network-process}. ++* Network Options:: Further control over network connections. ++* Network Feature Testing:: Determining which network features work on ++ the machine you are using. ++ ++Packing and Unpacking Byte Arrays ++ ++* Bindat Spec:: Describing data layout. ++* Bindat Functions:: Doing the unpacking and packing. ++* Bindat Examples:: Samples of what bindat.el can do for you! ++ ++Emacs Display ++ ++* Refresh Screen:: Clearing the screen and redrawing everything on it. ++* Forcing Redisplay:: Forcing redisplay. ++* Truncation:: Folding or wrapping long text lines. ++* The Echo Area:: Displaying messages at the bottom of the screen. ++* Warnings:: Displaying warning messages for the user. ++* Invisible Text:: Hiding part of the buffer text. ++* Selective Display:: Hiding part of the buffer text (the old way). ++* Temporary Displays:: Displays that go away automatically. ++* Overlays:: Use overlays to highlight parts of the buffer. ++* Width:: How wide a character or string is on the screen. ++* Line Height:: Controlling the height of lines. ++* Faces:: A face defines a graphics style ++ for text characters: font, colors, etc. ++* Fringes:: Controlling window fringes. ++* Scroll Bars:: Controlling vertical scroll bars. ++* Display Property:: Enabling special display features. ++* Images:: Displaying images in Emacs buffers. ++* Buttons:: Adding clickable buttons to Emacs buffers. ++* Abstract Display:: Emacs' Widget for Object Collections. ++* Blinking:: How Emacs shows the matching open parenthesis. ++* Usual Display:: The usual conventions for displaying ++ nonprinting chars. ++* Display Tables:: How to specify other conventions. ++* Beeping:: Audible signal to the user. ++* Window Systems:: Which window system is being used. ++ ++The Echo Area ++ ++* Displaying Messages:: Explicitly displaying text in the echo area. ++* Progress:: Informing user about progress of a long operation. ++* Logging Messages:: Echo area messages are logged for the user. ++* Echo Area Customization:: Controlling the echo area. ++ ++Reporting Warnings ++ ++* Warning Basics:: Warnings concepts and functions to report them. ++* Warning Variables:: Variables programs bind to customize ++ their warnings. ++* Warning Options:: Variables users set to control display of warnings. ++ ++Overlays ++ ++* Managing Overlays:: Creating and moving overlays. ++* Overlay Properties:: How to read and set properties. ++ What properties do to the screen display. ++* Finding Overlays:: Searching for overlays. ++ ++Faces ++ ++* Defining Faces:: How to define a face with @code{defface}. ++* Face Attributes:: What is in a face? ++* Attribute Functions:: Functions to examine and set face attributes. ++* Displaying Faces:: How Emacs combines the faces specified for ++ a character. ++* Face Remapping:: Remapping faces to alternative definitions. ++* Face Functions:: How to define and examine faces. ++* Auto Faces:: Hook for automatic face assignment. ++* Font Selection:: Finding the best available font for a face. ++* Font Lookup:: Looking up the names of available fonts ++ and information about them. ++* Fontsets:: A fontset is a collection of fonts ++ that handle a range of character sets. ++* Low-Level Font:: Lisp representation for character display fonts. ++ ++Fringes ++ ++* Fringe Size/Pos:: Specifying where to put the window fringes. ++* Fringe Indicators:: Displaying indicator icons in the window fringes. ++* Fringe Cursors:: Displaying cursors in the right fringe. ++* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. ++* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. ++* Overlay Arrow:: Display of an arrow to indicate position. ++ ++The @code{display} Property ++ ++* Replacing Specs:: Display specs that replace the text. ++* Specified Space:: Displaying one space with a specified width. ++* Pixel Specification:: Specifying space width or height in pixels. ++* Other Display Specs:: Displaying an image; magnifying text; moving it ++ up or down on the page; adjusting the width ++ of spaces within text. ++* Display Margins:: Displaying text or images to the side of ++ the main text. ++ ++Images ++ ++* Image Formats:: Supported image formats. ++* Image Descriptors:: How to specify an image for use in @code{:display}. ++* XBM Images:: Special features for XBM format. ++* XPM Images:: Special features for XPM format. ++* GIF Images:: Special features for GIF format. ++* TIFF Images:: Special features for TIFF format. ++* PostScript Images:: Special features for PostScript format. ++* Other Image Types:: Various other formats are supported. ++* Defining Images:: Convenient ways to define an image for later use. ++* Showing Images:: Convenient ways to display an image once ++ it is defined. ++* Image Cache:: Internal mechanisms of image display. ++ ++Buttons ++ ++* Button Properties:: Button properties with special meanings. ++* Button Types:: Defining common properties for classes of buttons. ++* Making Buttons:: Adding buttons to Emacs buffers. ++* Manipulating Buttons:: Getting and setting properties of buttons. ++* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. ++ ++Abstract Display ++ ++* Abstract Display Functions:: Functions in the Ewoc package. ++* Abstract Display Example:: Example of using Ewoc. ++ ++Display Tables ++ ++* Display Table Format:: What a display table consists of. ++* Active Display Table:: How Emacs selects a display table to use. ++* Glyphs:: How to define a glyph, and what glyphs mean. ++ ++Operating System Interface ++ ++* Starting Up:: Customizing Emacs startup processing. ++* Getting Out:: How exiting works (permanent or temporary). ++* System Environment:: Distinguish the name and kind of system. ++* User Identification:: Finding the name and user id of the user. ++* Time of Day:: Getting the current time. ++* Time Conversion:: Converting a time from numeric form to ++ calendrical data and vice versa. ++* Time Parsing:: Converting a time from numeric form to text ++ and vice versa. ++* Processor Run Time:: Getting the run time used by Emacs. ++* Time Calculations:: Adding, subtracting, comparing times, etc. ++* Timers:: Setting a timer to call a function at a ++ certain time. ++* Idle Timers:: Setting a timer to call a function when Emacs has ++ been idle for a certain length of time. ++* Terminal Input:: Accessing and recording terminal input. ++* Terminal Output:: Controlling and recording terminal output. ++* Sound Output:: Playing sounds on the computer's speaker. ++* X11 Keysyms:: Operating on key symbols for X Windows. ++* Batch Mode:: Running Emacs without terminal interaction. ++* Session Management:: Saving and restoring state with ++ X Session Management. ++ ++Starting Up Emacs ++ ++* Startup Summary:: Sequence of actions Emacs performs at startup. ++* Init File:: Details on reading the init file. ++* Terminal-Specific:: How the terminal-specific Lisp file is read. ++* Command-Line Arguments:: How command-line arguments are processed, ++ and how you can customize them. ++ ++Getting Out of Emacs ++ ++* Killing Emacs:: Exiting Emacs irreversibly. ++* Suspending Emacs:: Exiting Emacs reversibly. ++ ++Terminal Input ++ ++* Input Modes:: Options for how input is processed. ++* Recording Input:: Saving histories of recent or all input events. ++ ++Tips and Conventions ++ ++* Coding Conventions:: Conventions for clean and robust programs. ++* Key Binding Conventions:: Which keys should be bound by which programs. ++* Programming Tips:: Making Emacs code fit smoothly in Emacs. ++* Compilation Tips:: Making compiled code run fast. ++* Warning Tips:: Turning off compiler warnings. ++* Documentation Tips:: Writing readable documentation strings. ++* Comment Tips:: Conventions for writing comments. ++* Library Headers:: Standard headers for library packages. ++ ++GNU Emacs Internals ++ ++* Building Emacs:: How the dumped Emacs is made. ++* Pure Storage:: A kludge to make preloaded Lisp functions sharable. ++* Garbage Collection:: Reclaiming space for Lisp objects no longer used. ++* Memory Usage:: Info about total size of Lisp objects made so far. ++* Writing Emacs Primitives:: Writing C code for Emacs. ++* Object Internals:: Data formats of buffers, windows, processes. ++ ++Object Internals ++ ++* Buffer Internals:: Components of a buffer structure. ++* Window Internals:: Components of a window structure. ++* Process Internals:: Components of a process structure. ++@end detailmenu ++@end menu ++ ++@c include intro.texi ++@c include objects.texi ++@c include numbers.texi ++@c include strings.texi ++ ++@c include lists.texi ++@c include sequences.texi ++@c include hash.texi ++@c include symbols.texi ++@c include eval.texi ++ ++@c include control.texi ++@c include variables.texi ++@c include functions.texi ++@c include macros.texi ++ ++@c include customize.texi ++@c include loading.texi ++@c include compile.texi ++@c include advice.texi ++ ++@c This includes edebug.texi. ++@c include debugging.texi ++@c include streams.texi ++@c include minibuf.texi ++@c include commands.texi ++ ++@c include keymaps.texi ++@c include modes.texi ++@c include help.texi ++@c include files.texi ++ ++@c include backups.texi ++ ++@c ================ Beginning of Volume 2 ================ ++@include buffers.texi ++@include windows.texi ++@include frames.texi ++ ++@include positions.texi ++@include markers.texi ++@include text.texi ++@include nonascii.texi ++ ++@include searching.texi ++@include syntax.texi ++@include abbrevs.texi ++@include processes.texi ++ ++@include display.texi ++@include os.texi ++ ++@c MOVE to Emacs Manual: include misc-modes.texi ++ ++@c appendices ++ ++@c REMOVE this: include non-hacker.texi ++ ++@include anti.texi ++@include doclicense.texi ++@include gpl.texi ++@include tips.texi ++@include internals.texi ++@include errors.texi ++@include locals.texi ++@include maps.texi ++@include hooks.texi ++ ++@include index.texi ++ ++@ignore ++@node New Symbols, , Index, Top ++@unnumbered New Symbols Since the Previous Edition ++ ++@printindex tp ++@end ignore ++ ++@bye ++ ++ ++These words prevent "local variables" above from confusing Emacs. ++ ++@ignore ++ arch-tag: dfdbecf8-fec2-49c1-8427-3e8ac8b0b849 ++@end ignore +diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi +new file mode 100644 +index 0000000..539ed6e +--- /dev/null ++++ b/doc/lispref/windows.texi +@@ -0,0 +1,2603 @@ ++@c -*-texinfo-*- ++@c This is part of the GNU Emacs Lisp Reference Manual. ++@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, ++@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++@c See the file elisp.texi for copying conditions. ++@setfilename ../../info/windows ++@node Windows, Frames, Buffers, Top ++@chapter Windows ++ ++ This chapter describes most of the functions and variables related to ++Emacs windows. @xref{Frames and Windows}, for how windows relate to ++frames. @xref{Display}, for information on how text is displayed in ++windows. ++ ++@menu ++* Basic Windows:: Basic information on using windows. ++* Splitting Windows:: Splitting one window into two windows. ++* Deleting Windows:: Deleting a window gives its space to other windows. ++* Selecting Windows:: The selected window is the one that you edit in. ++* Cyclic Window Ordering:: Moving around the existing windows. ++* Buffers and Windows:: Each window displays the contents of a buffer. ++* Displaying Buffers:: Higher-level functions for displaying a buffer ++ and choosing a window for it. ++* Choosing Window:: How to choose a window for displaying a buffer. ++* Dedicated Windows:: How to avoid displaying another buffer in ++ a specific window. ++* Window Point:: Each window has its own location of point. ++* Window Start and End:: Buffer positions indicating which text is ++ on-screen in a window. ++* Textual Scrolling:: Moving text up and down through the window. ++* Vertical Scrolling:: Moving the contents up and down on the window. ++* Horizontal Scrolling:: Moving the contents sideways on the window. ++* Size of Window:: Accessing the size of a window. ++* Resizing Windows:: Changing the size of a window. ++* Coordinates and Windows:: Converting coordinates to windows. ++* Window Tree:: The layout and sizes of all windows in a frame. ++* Window Configurations:: Saving and restoring the state of the screen. ++* Window Parameters:: Associating additional information with windows. ++* Window Hooks:: Hooks for scrolling, window size changes, ++ redisplay going past a certain point, ++ or window configuration changes. ++@end menu ++ ++@node Basic Windows ++@section Basic Concepts of Emacs Windows ++@cindex window ++@cindex selected window ++ ++ A @dfn{window} in Emacs is the physical area of the screen in which a ++buffer is displayed. The term is also used to refer to a Lisp object that ++represents that screen area in Emacs Lisp. It should be ++clear from the context which is meant. ++ ++ Emacs groups windows into frames; see @ref{Frames}. A frame ++represents an area of screen available for Emacs to use. Each frame ++always contains at least one window, but you can subdivide it ++vertically or horizontally into multiple, nonoverlapping Emacs ++windows. ++ ++ In each frame, at any time, one and only one window is designated as ++@dfn{selected within the frame}. The frame's cursor appears in that ++window, but the other windows have ``non-selected'' cursors, normally ++less visible. (@xref{Cursor Parameters}, for customizing this.) At ++any time, one frame is the selected frame; and the window selected ++within that frame is @dfn{the selected window}. The selected window's ++buffer is usually the current buffer (except when @code{set-buffer} has ++been used); see @ref{Current Buffer}. ++ ++ For practical purposes, a window exists only while it is displayed in ++a frame. Once removed from the frame, the window is effectively deleted ++and should not be used, @emph{even though there may still be references ++to it} from other Lisp objects; see @ref{Deleting Windows}. Restoring a ++saved window configuration is the only way for a window no longer on the ++screen to come back to life; see @ref{Window Configurations}. ++ ++@cindex multiple windows ++ Users create multiple windows so they can look at several buffers at ++once. Lisp libraries use multiple windows for a variety of reasons, but ++most often to display related information. In Rmail, for example, you ++can move through a summary buffer in one window while the other window ++shows messages one at a time as they are reached. ++ ++ The meaning of ``window'' in Emacs is similar to what it means in the ++context of general-purpose window systems such as X, but not identical. ++The X Window System places X windows on the screen; Emacs uses one or ++more X windows as frames, and subdivides them into ++Emacs windows. When you use Emacs on a character-only terminal, Emacs ++treats the whole terminal screen as one frame. ++ ++@cindex terminal screen ++@cindex screen of terminal ++@cindex tiled windows ++ Most window systems support arbitrarily located overlapping windows. ++In contrast, Emacs windows are @dfn{tiled}; they never overlap, and ++together they fill the whole screen or frame. Because of the way in ++which Emacs creates new windows (@pxref{Splitting Windows}) and resizes ++them (@pxref{Resizing Windows}), not all conceivable tilings of windows ++on an Emacs frame are actually possible. ++ ++@defun windowp object ++This function returns @code{t} if @var{object} is a window. ++@end defun ++ ++@node Splitting Windows ++@section Splitting Windows ++@cindex splitting windows ++@cindex window splitting ++ ++The functions described below are the primitives used to split a window ++into two windows. They do not accept a buffer as an argument. Rather, ++the two ``halves'' of the split window initially display the same buffer ++previously visible in the window that was split. ++ ++@deffn Command split-window &optional window size horizontal ++This function splits a new window out of @var{window}'s screen area. It ++returns the new window. The default for @var{window} is the selected ++window. When you split the selected window, it remains selected. ++ ++If @var{horizontal} is non-@code{nil}, then @var{window} splits into two ++side by side windows. The original window keeps the leftmost @var{size} ++columns, and gives the rest of the columns to the new window. ++Otherwise, @var{window} splits into windows one above the other, the ++original window keeps the upper @var{size} lines and gives the rest of ++the lines to the new window. The original window @var{window} is ++therefore the left-hand or upper of the two, and the new window is the ++right-hand or lower. ++ ++If @var{size} is omitted or @code{nil}, then @var{window} is divided ++evenly into two parts. (If there is an odd line, it is allocated to ++the new window.) When @code{split-window} is called interactively, ++all its arguments are @code{nil}. ++ ++If splitting would result in making a window that is smaller than ++@code{window-min-height} or @code{window-min-width} (@pxref{Resizing ++Windows}), @code{split-window} signals an error and does not split the ++window at all. ++ ++The following example starts with one window on a screen that is 50 ++lines high by 80 columns wide; then it splits the window. ++ ++@smallexample ++@group ++(setq w (selected-window)) ++ @result{} # ++(window-edges) ; @r{Edges in order:} ++ @result{} (0 0 80 50) ; @r{left--top--right--bottom} ++@end group ++ ++@group ++;; @r{Returns window created} ++(setq w2 (split-window w 15)) ++ @result{} # ++@end group ++@group ++(window-edges w2) ++ @result{} (0 15 80 50) ; @r{Bottom window;} ++ ; @r{top is line 15} ++@end group ++@group ++(window-edges w) ++ @result{} (0 0 80 15) ; @r{Top window} ++@end group ++@end smallexample ++ ++The screen looks like this: ++ ++@smallexample ++@group ++ __________ ++ | | line 0 ++ | w | ++ |__________| ++ | | line 15 ++ | w2 | ++ |__________| ++ line 50 ++ column 0 column 80 ++@end group ++@end smallexample ++ ++Next, split the top window horizontally: ++ ++@smallexample ++@group ++(setq w3 (split-window w 35 t)) ++ @result{} # ++@end group ++@group ++(window-edges w3) ++ @result{} (35 0 80 15) ; @r{Left edge at column 35} ++@end group ++@group ++(window-edges w) ++ @result{} (0 0 35 15) ; @r{Right edge at column 35} ++@end group ++@group ++(window-edges w2) ++ @result{} (0 15 80 50) ; @r{Bottom window unchanged} ++@end group ++@end smallexample ++ ++@need 3000 ++Now the screen looks like this: ++ ++@smallexample ++@group ++ column 35 ++ __________ ++ | | | line 0 ++ | w | w3 | ++ |___|______| ++ | | line 15 ++ | w2 | ++ |__________| ++ line 50 ++ column 0 column 80 ++@end group ++@end smallexample ++ ++Normally, Emacs indicates the border between two side-by-side windows ++with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The ++display table can specify alternative border characters; see @ref{Display ++Tables}. ++@end deffn ++ ++@deffn Command split-window-vertically &optional size ++This function splits the selected window into two windows, one above the ++other, leaving the upper of the two windows selected, with @var{size} ++lines. (If @var{size} is negative, then the lower of the two windows ++gets @minus{}@var{size} lines and the upper window gets the rest, but ++the upper window is still the one selected.) However, if ++@code{split-window-keep-point} (see below) is @code{nil}, then either ++window can be selected. ++ ++In other respects, this function is similar to @code{split-window}. ++In particular, the upper window is the original one and the return ++value is the new, lower window. ++@end deffn ++ ++@defopt split-window-keep-point ++If this variable is non-@code{nil} (the default), then ++@code{split-window-vertically} behaves as described above. ++ ++If it is @code{nil}, then @code{split-window-vertically} adjusts point ++in each of the two windows to avoid scrolling. (This is useful on ++slow terminals.) It selects whichever window contains the screen line ++that point was previously on. ++ ++This variable affects the behavior of @code{split-window-vertically} ++only. It has no effect on the other functions described here. ++@end defopt ++ ++@deffn Command split-window-horizontally &optional size ++This function splits the selected window into two windows ++side-by-side, leaving the selected window on the left with @var{size} ++columns. If @var{size} is negative, the rightmost window gets ++@minus{}@var{size} columns, but the leftmost window still remains ++selected. ++ ++This function is basically an interface to @code{split-window}. ++You could define a simplified version of the function like this: ++ ++@smallexample ++@group ++(defun split-window-horizontally (&optional arg) ++ "Split selected window into two windows, side by side..." ++ (interactive "P") ++@end group ++@group ++ (let ((size (and arg (prefix-numeric-value arg)))) ++ (and size (< size 0) ++ (setq size (+ (window-width) size))) ++ (split-window nil size t))) ++@end group ++@end smallexample ++@end deffn ++ ++@defun one-window-p &optional no-mini all-frames ++This function returns non-@code{nil} if there is only one window. The ++argument @var{no-mini}, if non-@code{nil}, means don't count the ++minibuffer even if it is active; otherwise, the minibuffer window is ++counted when it is active. ++ ++The argument @var{all-frames} specifies which frames to consider. Here ++are the possible values and their meanings: ++ ++@table @asis ++@item @code{nil} ++Count the windows in the selected frame, plus the minibuffer used ++by that frame even if it lies in some other frame. ++ ++@item @code{t} ++Count all windows in all existing frames. ++ ++@item @code{visible} ++Count all windows in all visible frames. ++ ++@item 0 ++Count all windows in all visible or iconified frames. ++ ++@item anything else ++Count precisely the windows in the selected frame, and no others. ++@end table ++@end defun ++ ++@node Deleting Windows ++@section Deleting Windows ++@cindex deleting windows ++ ++A window remains visible on its frame unless you @dfn{delete} it by ++calling certain functions that delete windows. A deleted window cannot ++appear on the screen, but continues to exist as a Lisp object until ++there are no references to it. There is no way to cancel the deletion ++of a window aside from restoring a saved window configuration ++(@pxref{Window Configurations}). Restoring a window configuration also ++deletes any windows that aren't part of that configuration. ++ ++ When you delete a window, the space it took up is given to one of ++its sibling windows adjacent to it. ++ ++@c Emacs 19 feature ++@defun window-live-p window ++This function returns @code{nil} if @var{window} is deleted, and ++@code{t} otherwise. ++ ++@strong{Warning:} Erroneous information or fatal errors may result from ++using a deleted window as if it were live. ++@end defun ++ ++@deffn Command delete-window &optional window ++This function removes @var{window} from display and returns @code{nil}. ++The default for @var{window} is the selected window. An error is ++signaled if @var{window} is the only window on its frame. ++@end deffn ++ ++@deffn Command delete-other-windows &optional window ++This function makes @var{window} the only window on its frame, by ++deleting the other windows in that frame. The default for @var{window} ++is the selected window. The return value is @code{nil}. ++@end deffn ++ ++@deffn Command delete-windows-on &optional buffer-or-name frame ++This function deletes all windows showing @var{buffer-or-name}. If ++there are no windows showing @var{buffer-or-name}, it does nothing. The ++optional argument @var{buffer-or-name} may be a buffer or the name of an ++existing buffer and defaults to the current buffer. ++ ++@code{delete-windows-on} operates frame by frame. If a frame has ++several windows showing different buffers, then those showing ++@var{buffer-or-name} are removed, and the others expand to fill the ++space. If all windows in some frame are showing @var{buffer-or-name} ++(including the case where there is only one window), then the frame ++winds up with a single window showing another buffer chosen with ++@code{other-buffer} (@pxref{The Buffer List}). If, however, the window ++showing @var{buffer-or-name} is dedicated to its buffer ++(@pxref{Dedicated Windows}), and there are other frames left, that ++window's frame is deleted. ++ ++The optional argument @var{frame} specifies which frames to operate on. ++This function does not use it in quite the same way as the other ++functions which scan all windows; specifically, the values @code{t} and ++@code{nil} have the opposite of their meanings in other functions. Here ++are the full details: ++ ++@itemize @bullet ++@item ++If it is @code{nil}, operate on all frames. ++@item ++If it is @code{t}, operate on the selected frame. ++@item ++If it is @code{visible}, operate on all visible frames. ++@item ++If it is 0, operate on all visible or iconified frames. ++@item ++If it is a frame, operate on that frame. ++@end itemize ++ ++This function always returns @code{nil}. ++@end deffn ++ ++@node Selecting Windows ++@section Selecting Windows ++@cindex selecting a window ++ ++ When a window is selected, the buffer in the window becomes the current ++buffer, and the cursor will appear in it. ++ ++@defun selected-window ++This function returns the selected window. This is the window in ++which the cursor appears and to which many commands apply. ++@end defun ++ ++@defun select-window window &optional norecord ++This function makes @var{window} the selected window. The cursor then ++appears in @var{window} (after redisplay). Unless @var{window} was ++already selected, @code{select-window} makes @var{window}'s buffer the ++current buffer. The return value is @var{window}. ++ ++Normally, @var{window}'s selected buffer is moved to the front of the ++buffer list (@pxref{The Buffer List}) and @var{window} becomes the most ++recently selected window. But if @var{norecord} is non-@code{nil}, the ++buffer list remains unchanged and @var{window} does not become the most ++recently selected one. ++ ++ ++@example ++@group ++(setq w (next-window)) ++(select-window w) ++ @result{} # ++@end group ++@end example ++@end defun ++ ++@defmac save-selected-window forms@dots{} ++This macro records the selected frame, as well as the selected window ++of each frame, executes @var{forms} in sequence, then restores the ++earlier selected frame and windows. It also saves and restores the ++current buffer. It returns the value of the last form in @var{forms}. ++ ++This macro does not save or restore anything about the sizes, ++arrangement or contents of windows; therefore, if @var{forms} change ++them, the change persists. If the previously selected window of some ++frame is no longer live at the time of exit from @var{forms}, that ++frame's selected window is left alone. If the previously selected ++window is no longer live, then whatever window is selected at the end of ++@var{forms} remains selected. The current buffer is restored if and ++only if it is still live when exiting @var{forms}. ++ ++This macro changes neither the ordering of recently selected windows nor ++the buffer list. ++@end defmac ++ ++@defmac with-selected-window window forms@dots{} ++This macro selects @var{window}, executes @var{forms} in sequence, then ++restores the previously selected window and current buffer. The ordering ++of recently selected windows and the buffer list remain unchanged unless ++you deliberately change them within @var{forms}, for example, by calling ++@code{select-window} with argument @var{norecord} @code{nil}. ++@end defmac ++ ++@cindex finding windows ++ The following functions choose one of the windows on the screen, ++offering various criteria for the choice. ++ ++@defun get-lru-window &optional frame dedicated ++This function returns the window least recently ``used'' (that is, ++selected) among a set of candidate windows. If any full-width windows ++are present, it only considers these. ++ ++The selected window is returned if it is the only candidate. A ++minibuffer window is never a candidate. A dedicated window ++(@pxref{Dedicated Windows}) is never a candidate unless the optional ++argument @var{dedicated} is non-@code{nil}. ++ ++The optional argument @var{frame} specifies which windows are ++considered. ++ ++@itemize @bullet ++@item ++If it is @code{nil}, consider windows on the selected frame. ++@item ++If it is @code{t}, consider windows on all frames. ++@item ++If it is @code{visible}, consider windows on all visible frames. ++@item ++If it is 0, consider windows on all visible or iconified frames. ++@item ++If it is a frame, consider windows on that frame. ++@end itemize ++@end defun ++ ++@defun get-largest-window &optional frame dedicated ++This function returns the window with the largest area (height times ++width). If there are no side-by-side windows, then this is the window ++with the most lines. A minibuffer window is never a candidate. A ++dedicated window (@pxref{Dedicated Windows}) is never a candidate unless ++the optional argument @var{dedicated} is non-@code{nil}. ++ ++If there are two candidate windows of the same size, this function ++prefers the one that comes first in the cyclic ordering of windows, ++starting from the selected window (@pxref{Cyclic Window Ordering}). ++ ++The optional argument @var{frame} specifies which set of windows to ++consider, see @code{get-lru-window} above. ++@end defun ++ ++@cindex window that satisfies a predicate ++@cindex conditional selection of windows ++@defun get-window-with-predicate predicate &optional minibuf all-frames default ++This function returns a window satisfying @var{predicate}. It cycles ++through all visible windows using @code{walk-windows} (@pxref{Cyclic ++Window Ordering}), calling @var{predicate} on each one of them with that ++window as its argument. The function returns the first window for which ++@var{predicate} returns a non-@code{nil} value; if that never happens, ++it returns @var{default} (which defaults to @code{nil}). ++ ++The optional arguments @var{minibuf} and @var{all-frames} specify the ++set of windows to include in the scan. See the description of ++@code{next-window} in @ref{Cyclic Window Ordering}, for details. ++@end defun ++ ++@node Cyclic Window Ordering ++@comment node-name, next, previous, up ++@section Cyclic Ordering of Windows ++@cindex cyclic ordering of windows ++@cindex ordering of windows, cyclic ++@cindex window ordering, cyclic ++ ++ When you use the command @kbd{C-x o} (@code{other-window}) to select ++some other window, it moves through the windows on the screen in a ++specific order. For any given configuration of windows, this order ++never varies. It is called the @dfn{cyclic ordering of windows}. ++ ++ For a particular frame, this ordering generally goes from top to ++bottom, and from left to right. But it may go down first or go right ++first, depending on the order in which windows were split. ++ ++ If the first split was vertical (into windows one above each other), ++and then the subwindows were split horizontally, then the ordering is ++left to right in the top of the frame, and then left to right in the ++next lower part of the frame, and so on. If the first split was ++horizontal, the ordering is top to bottom in the left part, and so on. ++In general, within each set of siblings at any level in the window tree ++(@pxref{Window Tree}), the order is left to right, or top to bottom. ++ ++@deffn next-window &optional window minibuf all-frames ++@cindex minibuffer window, and @code{next-window} ++This function returns the window following @var{window} in the cyclic ++ordering of windows. This is the window @kbd{C-x o} selects if typed ++when @var{window} is selected. The default for @var{window} is the ++selected window. ++ ++The value of the optional argument @var{minibuf} specifies whether the ++minibuffer is included in the window order. Normally, when ++@var{minibuf} is @code{nil}, the minibuffer is included only if it is ++currently ``active''; this matches the behavior of @kbd{C-x o}. (The ++minibuffer window is active while the minibuffer is in use; see ++@ref{Minibuffers}.) ++ ++If @var{minibuf} is @code{t}, the cyclic ordering includes the ++minibuffer window even if it is not active. If @var{minibuf} is neither ++@code{t} nor @code{nil}, the minibuffer window is not included even if ++it is active. ++ ++The optional argument @var{all-frames} specifies which frames to ++consider. Here are the possible values and their meanings: ++ ++@table @asis ++@item @code{nil} ++Consider all the windows in @var{window}'s frame, plus the minibuffer ++used by that frame even if it lies in some other frame. If the ++minibuffer counts (as determined by @var{minibuf}), then all windows on ++all frames that share that minibuffer count too. ++ ++@item @code{t} ++Consider all windows in all existing frames. ++ ++@item @code{visible} ++Consider all windows in all visible frames. (To get useful results, you ++must ensure @var{window} is in a visible frame.) ++ ++@item 0 ++Consider all windows in all visible or iconified frames. ++ ++@item a frame ++Consider all windows on that frame. ++ ++@item anything else ++Consider precisely the windows in @var{window}'s frame, and no others. ++@end table ++ ++This example assumes there are two windows, both displaying the ++buffer @samp{windows.texi}: ++ ++@example ++@group ++(selected-window) ++ @result{} # ++@end group ++@group ++(next-window (selected-window)) ++ @result{} # ++@end group ++@group ++(next-window (next-window (selected-window))) ++ @result{} # ++@end group ++@end example ++@end deffn ++ ++@deffn previous-window &optional window minibuf all-frames ++This function returns the window preceding @var{window} in the cyclic ++ordering of windows. The other arguments specify which windows to ++include in the cycle, as in @code{next-window}. ++@end deffn ++ ++@deffn Command other-window count &optional all-frames ++This function selects another window in the cyclic ordering of windows. ++@var{count} specifies the number of windows to skip in the ordering, ++starting with the selected window, before making the selection. If ++@var{count} is a positive number, it skips @var{count} windows forwards. ++@var{count} negative means skip @minus{}@var{count} windows backwards. ++If @var{count} is zero, it does not skip any window, thus re-selecting ++the selected window. In an interactive call, @var{count} is the numeric ++prefix argument. ++ ++The optional argument @var{all-frames} has the same meaning as in ++@code{next-window}, but the @var{minibuf} argument of @code{next-window} ++is always effectively @code{nil}. This function returns @code{nil}. ++@end deffn ++ ++@c Emacs 19 feature ++@defun walk-windows proc &optional minibuf all-frames ++This function cycles through all windows. It calls the function ++@code{proc} once for each window, with the window as its sole ++argument. ++ ++The optional arguments @var{minibuf} and @var{all-frames} specify the ++set of windows to include in the walk. See @code{next-window}, above, ++for details. ++@end defun ++ ++@defun window-list &optional frame minibuf window ++This function returns a list of all windows on @var{frame}, starting ++with @var{window}. The default for @var{frame} is the selected frame; ++the default for @var{window} is the selected window. ++ ++The value of @var{minibuf} specifies if the minibuffer window shall be ++included in the result list. If @var{minibuf} is @code{t}, the result ++always includes the minibuffer window. If @var{minibuf} is @code{nil} ++or omitted, that includes the minibuffer window if it is active. If ++@var{minibuf} is neither @code{nil} nor @code{t}, the result never ++includes the minibuffer window. ++@end defun ++ ++@node Buffers and Windows ++@section Buffers and Windows ++@cindex examining windows ++@cindex windows, controlling precisely ++@cindex buffers, controlled in windows ++ ++ This section describes low-level functions to examine windows or to ++display buffers in windows in a precisely controlled fashion. ++@iftex ++See the following section for ++@end iftex ++@ifnottex ++@xref{Displaying Buffers}, for ++@end ifnottex ++related functions that find a window to use and specify a buffer for it. ++The functions described there are easier to use, but they employ ++heuristics in choosing or creating a window; use the functions described ++here when you need complete control. ++ ++@defun set-window-buffer window buffer-or-name &optional keep-margins ++This function makes @var{window} display @var{buffer-or-name} as its ++contents. It returns @code{nil}. The default for @var{window} is the ++selected window. The argument @var{buffer-or-name} must specify a ++buffer or the name of an existing buffer. ++ ++@code{set-window-buffer} is the fundamental primitive for changing which ++buffer is displayed in a window, and all ways of doing that call this ++function. ++ ++@example ++@group ++(set-window-buffer (selected-window) "foo") ++ @result{} nil ++@end group ++@end example ++ ++Normally, displaying @var{buffer-or-name} in @var{window} resets the ++window's position, display margins, fringe widths, and scroll bar ++settings based on the local variables of that buffer. ++However, if @var{keep-margins} is non-@code{nil}, display margins and ++fringe widths of @var{window} remain unchanged. @xref{Fringes}. ++ ++@code{set-window-buffer} signals an error when @var{window} is ++@dfn{strongly} dedicated to its buffer (@pxref{Dedicated Windows}) and ++does not already display @var{buffer-or-name}. ++ ++Note that this function runs @code{window-scroll-functions} before ++running @code{window-configuration-change-hook}. ++@end defun ++ ++@defvar buffer-display-count ++This buffer-local variable records the number of times a buffer has been ++displayed in a window. It is incremented each time ++@code{set-window-buffer} is called for the buffer. ++@end defvar ++ ++@defun window-buffer &optional window ++This function returns the buffer that @var{window} is displaying. The ++default for @var{window} is the selected window. ++ ++@example ++@group ++(window-buffer) ++ @result{} # ++@end group ++@end example ++@end defun ++ ++@defun get-buffer-window &optional buffer-or-name all-frames ++This function returns a window currently displaying ++@var{buffer-or-name}, or @code{nil} if there is none. If there are ++several such windows, then the function returns the first one in the ++cyclic ordering of windows, starting from the selected window. ++@xref{Cyclic Window Ordering}. ++ ++The argument @var{BUFFER-OR-NAME} may be a buffer or a buffer name and ++defaults to the current buffer. The optional argument @var{all-frames} ++specifies which windows to consider: ++ ++@itemize @bullet ++@item ++@code{nil} means consider windows on the selected frame. ++@item ++@code{t} means consider windows on all existing frames. ++@item ++@code{visible} means consider windows on all visible frames. ++@item ++0 means consider windows on all visible or iconified frames. ++@item ++A frame means consider windows on that frame only. ++@end itemize ++ ++Observe that the behavior of @code{get-buffer-window} may differ from ++that of @code{next-window} (@pxref{Cyclic Window Ordering}) when ++@var{all-frames} equals @code{nil} or any value not listed here. ++Perhaps we will change @code{get-buffer-window} in the future to make it ++compatible with the other functions. ++@end defun ++ ++@defun get-buffer-window-list &optional buffer-or-name minibuf all-frames ++This function returns a list of all windows currently displaying ++@var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer ++or the name of an existing buffer and defaults to the current buffer. ++ ++The two remaining arguments work like the same-named arguments of ++@code{next-window}; they are @emph{not} like the optional arguments of ++@code{get-buffer-window}. ++@end defun ++ ++@defvar buffer-display-time ++This variable records the time at which a buffer was last made visible ++in a window. It is always local in each buffer; each time ++@code{set-window-buffer} is called, it sets this variable to ++@code{(current-time)} in the specified buffer (@pxref{Time of Day}). ++When a buffer is first created, @code{buffer-display-time} starts out ++with the value @code{nil}. ++@end defvar ++ ++@node Displaying Buffers ++@section Displaying Buffers in Windows ++@cindex switching to a buffer ++@cindex displaying a buffer ++ ++ In this section we describe convenient functions that choose a window ++automatically and use it to display a specified buffer. These functions ++can also split an existing window in certain circumstances. We also ++describe variables that parameterize the heuristics used for choosing a ++window. ++@iftex ++See the preceding section for ++@end iftex ++@ifnottex ++@xref{Buffers and Windows}, for ++@end ifnottex ++low-level primitives that give you more precise control. All of these ++functions work by calling @code{set-window-buffer}. ++ ++ Do not use the functions in this section in order to make a buffer ++current so that a Lisp program can access or modify it; they are too ++drastic for that purpose, since they change the display of buffers in ++windows, which would be gratuitous and surprise the user. Instead, use ++@code{set-buffer} and @code{save-current-buffer} (@pxref{Current ++Buffer}), which designate buffers as current for programmed access ++without affecting the display of buffers in windows. ++ ++@deffn Command switch-to-buffer buffer-or-name &optional norecord ++This function makes @var{buffer-or-name} the current buffer, and also ++displays the buffer in the selected window. This means that a human can ++see the buffer and subsequent keyboard commands will apply to it. ++Contrast this with @code{set-buffer}, which makes @var{buffer-or-name} ++the current buffer but does not display it in the selected window; ++see @ref{Current Buffer}. ++ ++If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a ++buffer using @code{other-buffer}. If @var{buffer-or-name} is a string ++that does not identify an existing buffer, then a new buffer by that ++name is created. The major mode for the new buffer is set according to ++the variable @code{default-major-mode}; see @ref{Auto Major Mode}. ++ ++When the selected window is the minibuffer window or is strongly ++dedicated to its buffer (@pxref{Dedicated Windows}), this function calls ++@code{pop-to-buffer} (see below) to display the buffer in some other ++window. ++ ++Normally the specified buffer is put at the front of the buffer list ++(both the selected frame's buffer list and the frame-independent buffer ++list). This affects the operation of @code{other-buffer}. However, if ++@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer ++List}. ++ ++The @code{switch-to-buffer} function is often used interactively, as ++the binding of @kbd{C-x b}. It is also used frequently in programs. It ++returns the buffer that it switched to. ++@end deffn ++ ++The next two functions are similar to @code{switch-to-buffer}, except ++for the described features. ++ ++@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord ++This function makes the buffer specified by @var{buffer-or-name} current ++and displays it in a window not currently selected, using the function ++@code{pop-to-buffer} (see below). ++ ++The currently selected window is absolutely never used to do the job. ++If the selected window already displays @var{buffer-or-name}, then it ++continues to do so, but another window is nonetheless found to display ++it in as well. ++ ++This function updates the buffer list just like @code{switch-to-buffer} ++unless @var{norecord} is non-@code{nil}. ++@end deffn ++ ++@deffn pop-to-buffer buffer-or-name &optional other-window norecord ++This command makes @var{buffer-or-name} the current buffer and switches ++to it in some window, preferably not the window previously selected. ++The ``popped-to'' window becomes the selected window. Its frame is ++given the X server's focus, if possible; see @ref{Input Focus}. The ++return value is the buffer that was switched to. ++ ++If @var{buffer-or-name} is @code{nil}, that means to choose some other ++buffer, but you don't specify which. If @var{buffer-or-name} is a ++string that does not name an existing buffer, a buffer by that name is ++created. The major mode for the new buffer is set according to the ++variable @code{default-major-mode}. @xref{Auto Major Mode}. ++ ++If either of the variables @code{display-buffer-reuse-frames} or ++@code{pop-up-frames} is non-@code{nil}, @code{pop-to-buffer} looks for a ++window in any visible frame already displaying the buffer; if there is ++one, it selects and returns that window. If no such window exists and ++@code{pop-up-frames} is non-@code{nil}, it creates a new frame and ++displays the buffer in it. Otherwise, @code{pop-to-buffer} operates ++entirely within the selected frame. (If the selected frame has just a ++minibuffer, @code{pop-to-buffer} operates within the most recently ++selected frame that was not just a minibuffer.) ++ ++If the variable @code{pop-up-windows} is non-@code{nil}, windows may be ++split to create a new window that is different from the original window. ++For details, see @ref{Choosing Window}. ++ ++If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or ++creates another window even if @var{buffer-or-name} is already visible ++in the selected window. Thus @var{buffer-or-name} could end up ++displayed in two windows. On the other hand, if @var{buffer-or-name} is ++already displayed in the selected window and @var{other-window} is ++@code{nil}, then the selected window is considered sufficient for ++displaying @var{buffer-or-name}, so that nothing needs to be done. ++ ++All the variables that affect @code{display-buffer} affect ++@code{pop-to-buffer} as well. @xref{Choosing Window}. ++ ++This function updates the buffer list just like @code{switch-to-buffer} ++unless @var{norecord} is non-@code{nil}. ++@end deffn ++ ++@deffn Command replace-buffer-in-windows &optional buffer-or-name ++This function replaces @var{buffer-or-name} in all windows displaying ++it with some other buffer. It uses @code{other-buffer} to choose the ++other buffer. In the usual applications of this function, you ++don't care which other buffer is used; you just want to make sure that ++@var{buffer-or-name} is no longer displayed. ++ ++The argument @var{buffer-or-name} may be a buffer or the name of an ++existing buffer and defaults to the current buffer. ++ ++If a window displaying @var{buffer-or-name} is dedicated ++(@pxref{Dedicated Windows}), and is not the only window on its frame, ++that window is deleted. If that window is the only window on its frame ++and there are other frames left, the window's frame is deleted too. If ++there are no other frames left, some other buffer is displayed in that ++window. ++ ++This function returns @code{nil}. ++@end deffn ++ ++@node Choosing Window ++@section Choosing a Window for Display ++ ++ This section describes the basic facility that chooses a window to ++display a buffer in---@code{display-buffer}. Higher-level functions and ++commands, like @code{switch-to-buffer} and @code{pop-to-buffer}, use this ++subroutine. Here we describe how to use @code{display-buffer} and how ++to customize it. ++ ++@deffn Command display-buffer buffer-or-name &optional not-this-window frame ++This command makes @var{buffer-or-name} appear in some window, but it ++does not select that window and does not make the buffer specified by ++@var{buffer-or-name} current. The identity of the selected window is ++unaltered by this function. The argument @var{buffer-or-name} must be a ++buffer or the name of an existing buffer. ++ ++@var{not-this-window} non-@code{nil} means to display the specified ++buffer in a window other than the selected one, even if it is already ++displayed in the selected window. This can cause the buffer to appear ++in two windows at once. Otherwise, if @var{buffer-or-name} is already ++being displayed in any window, that is good enough, so this function ++does nothing. ++ ++@code{display-buffer} returns the window chosen to display ++@var{buffer-or-name}. ++ ++If the optional argument @var{frame} is non-@code{nil}, it specifies ++which frames to check when deciding whether the buffer is already ++displayed. If the buffer is already displayed in some window on one of ++these frames, @code{display-buffer} simply returns that window. Here ++are the possible values of @var{frame}: ++ ++@itemize @bullet ++@item ++@code{nil} means consider windows on the selected frame. ++(Actually, the last non-minibuffer frame.) ++@item ++@code{t} means consider windows on all frames. ++@item ++@code{visible} means consider windows on all visible frames. ++@item ++0 means consider windows on all visible or iconified frames. ++@item ++A frame means consider windows on that frame only. ++@end itemize ++ ++Precisely how @code{display-buffer} finds or creates a window depends on ++the variables described below. ++@end deffn ++ ++@defopt display-buffer-reuse-frames ++If this variable is non-@code{nil}, @code{display-buffer} searches ++visible and iconified frames for a window displaying ++@var{buffer-or-name}. If there is such a window, @code{display-buffer} ++makes that window's frame visible and raises it if necessary, and ++returns the window. If there is no such window or ++@code{display-buffer-reuse-frames} is @code{nil}, the behavior of ++@code{display-buffer} is determined by the variables described next. ++@end defopt ++ ++@defopt pop-up-windows ++This variable specifies whether @code{display-buffer} is allowed to ++split (@pxref{Splitting Windows}) an existing window. If this variable ++is non-@code{nil}, @code{display-buffer} tries to split the largest or ++least recently used window on the selected frame. (If the selected ++frame is a minibuffer-only frame, @code{display-buffer} tries to split a ++window on another frame instead.) If this variable is @code{nil} or the ++variable @code{pop-up-frames} (see below) is non-@code{nil}, ++@code{display-buffer} does not split any window. ++@end defopt ++ ++@defopt split-window-preferred-function ++This variable must specify a function with one argument, which is a ++window. The @code{display-buffer} routines will call this function with ++one or more candidate windows when they look for a window to split. The ++function is expected to split that window and return the new window. If ++the function returns @code{nil}, this means that the argument window ++cannot (or shall not) be split. ++ ++The default value of @code{split-window-preferred-function} is the ++function @code{split-window-sensibly} described below. If you ++customize this option, bear in mind that the @code{display-buffer} ++routines may call your function up to two times when trying to split a ++window. The argument of the first call is the largest window on the ++chosen frame (as returned by @code{get-largest-window}). If that call ++fails to return a live window, your function is called a second time ++with the least recently used window on that frame (as returned by ++@code{get-lru-window}). ++ ++The function specified by this option may try to split any other window ++instead of the argument window. Note that the window selected at the ++time @code{display-buffer} was invoked is still selected when your ++function is called. Hence, you can split the selected window (instead ++of the largest or least recently used one) by simply ignoring the window ++argument in the body of your function. You can even choose to not split ++any window as long as the return value of your function specifies a live ++window or @code{nil}, but you are not encouraged to do so ++unconditionally. If you want @code{display-buffer} to never split any ++windows, set @code{pop-up-windows} to @code{nil}. ++@end defopt ++ ++@defun split-window-sensibly window ++This function takes a window as argument and tries to split that window ++in a suitable way. The two variables described next are useful for ++tuning the behavior of this function. ++@end defun ++ ++@defopt split-height-threshold ++This variable specifies whether @code{split-window-sensibly} may split ++windows vertically. If it is an integer, @code{split-window-sensibly} ++tries to vertically split a window only if it has at least this many ++lines. If the window has less lines, splitting fails, or the value of ++this variable is @code{nil}, @code{split-window-sensibly} will try to ++split the window horizontally, subject to restrictions of ++@code{split-width-threshold} (see below). If splitting horizontally ++fails too and the window is the only window on its frame, ++@code{split-window-sensibly} will try to split the window vertically ++disregarding the value of @code{split-height-threshold}. If this fails ++as well, @code{split-window-sensibly} returns @code{nil}. ++ ++@code{split-window-sensibly} does not split vertically a window whose ++height is fixed (@pxref{Resizing Windows}). Also, it vertically splits ++a window only if the space taken up by that window can accommodate two ++windows one above the other that are both at least ++@code{window-min-height} lines tall. Moreover, if the window that shall ++be split has a mode line, @code{split-window-sensibly} does not split ++the window unless the new window can accomodate a mode line too. ++@end defopt ++ ++@defopt split-width-threshold ++This variable specifies whether @code{split-window-sensibly} may split ++windows horizontally. If it is an integer, @code{split-window-sensibly} ++tries to horizontally split a window only if it has at least this many ++columns. If it is @code{nil}, @code{split-window-sensibly} will not ++split the window horizontally. (It still might split the window ++vertically, though, see above.) ++ ++@code{split-window-sensibly} does not split horizontally a window if ++that window's width is fixed (@pxref{Resizing Windows}). Also, it ++horizontally splits a window only if the space that window takes up can ++accommodate two windows side by side that are both at least ++@code{window-min-width} columns wide. ++@end defopt ++ ++@defopt even-window-heights ++This variable specifies whether @code{display-buffer} should even out ++window heights if the buffer gets displayed in an existing window, above ++or beneath another window. If @code{even-window-heights} is ++non-@code{nil}, the default, window heights will be evened out. If ++either of the involved window has fixed height (@pxref{Resizing ++Windows}) or @code{even-window-heights} is @code{nil}, the original ++window heights will be left alone. ++@end defopt ++ ++@c Emacs 19 feature ++@defopt pop-up-frames ++This variable specifies whether @code{display-buffer} should make new ++frames. If it is non-@code{nil}, @code{display-buffer} looks for a ++window already displaying @var{buffer-or-name} on any visible or ++iconified frame. If it finds such a window, it makes that window's ++frame visible and raises it if necessary, and returns the window. ++Otherwise it makes a new frame, unless the variable's value is ++@code{graphic-only} and the selected frame is not on a graphic display. ++@xref{Frames}, for more information. ++ ++Note that the value of @code{pop-up-windows} does not matter if ++@code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is ++@code{nil}, then @code{display-buffer} either splits a window or reuses ++one. ++@end defopt ++ ++@c Emacs 19 feature ++@defopt pop-up-frame-function ++This variable specifies how to make a new frame if @code{pop-up-frames} ++is non-@code{nil}. ++ ++The value of this variable must be a function of no arguments. When ++@code{display-buffer} makes a new frame, it does so by calling that ++function, which should return a frame. The default value of this ++variable is a function that creates a frame using the parameters ++specified by @code{pop-up-frame-alist} described next. ++@end defopt ++ ++@defopt pop-up-frame-alist ++This variable holds an alist specifying frame parameters used by the ++default value of @code{pop-up-frame-function} for making new frames. ++@xref{Frame Parameters}, for more information about frame parameters. ++@end defopt ++ ++@defopt special-display-buffer-names ++A list of buffer names identifying buffers that should be displayed ++specially. If the name of @var{buffer-or-name} is in this list, ++@code{display-buffer} handles the buffer specially. By default, special ++display means to give the buffer a dedicated frame. ++ ++If an element is a list, instead of a string, then the @sc{car} of that ++list is the buffer name, and the rest of that list says how to create ++the frame. There are two possibilities for the rest of that list (its ++@sc{cdr}): It can be an alist, specifying frame parameters, or it can ++contain a function and arguments to give to it. (The function's first ++argument is always the buffer to be displayed; the arguments from the ++list come after that.) ++ ++For example: ++ ++@example ++(("myfile" (minibuffer) (menu-bar-lines . 0))) ++@end example ++ ++@noindent ++specifies to display a buffer named @samp{myfile} in a dedicated frame ++with specified @code{minibuffer} and @code{menu-bar-lines} parameters. ++ ++The list of frame parameters can also use the phony frame parameters ++@code{same-frame} and @code{same-window}. If the specified frame ++parameters include @code{(same-window . @var{value})} and @var{value} ++is non-@code{nil}, that means to display the buffer in the current ++selected window. Otherwise, if they include @code{(same-frame . ++@var{value})} and @var{value} is non-@code{nil}, that means to display ++the buffer in a new window in the currently selected frame. ++@end defopt ++ ++@defopt special-display-regexps ++A list of regular expressions specifying buffers that should be ++displayed specially. If the buffer's name matches any of the regular ++expressions in this list, @code{display-buffer} handles the buffer ++specially. By default, special display means to give the buffer a ++dedicated frame. ++ ++If an element is a list, instead of a string, then the @sc{car} of the ++list is the regular expression, and the rest of the list says how to ++create the frame. See @code{special-display-buffer-names} above. ++@end defopt ++ ++@defun special-display-p buffer-name ++This function returns non-@code{nil} if displaying a buffer ++named @var{buffer-name} with @code{display-buffer} would ++create a special frame. The value is @code{t} if it would ++use the default frame parameters, or else the specified list ++of frame parameters. ++@end defun ++ ++@defopt special-display-function ++This variable holds the function to call to display a buffer specially. ++It receives the buffer as an argument, and should return the window in ++which it is displayed. The default value of this variable is ++@code{special-display-popup-frame}, see below. ++@end defopt ++ ++@defun special-display-popup-frame buffer &optional args ++This function tries to make @var{buffer} visible in a frame of its own. ++If @var{buffer} is already displayed in some window, it makes that ++window's frame visible and raises it. Otherwise, it creates a frame ++that is dedicated to @var{buffer}. The return value is the window used ++to display @var{buffer}. ++ ++If @var{args} is an alist, it specifies frame parameters for the new ++frame. If @var{args} is a list whose @sc{car} is a symbol, then ++@code{(car @var{args})} is called as a function to actually create and ++set up the frame; it is called with @var{buffer} as first argument, and ++@code{(cdr @var{args})} as additional arguments. ++ ++This function always uses an existing window displaying @var{buffer}, ++whether or not it is in a frame of its own; but if you set up the above ++variables in your init file, before @var{buffer} was created, then ++presumably the window was previously made by this function. ++@end defun ++ ++@defopt special-display-frame-alist ++@anchor{Definition of special-display-frame-alist} ++This variable holds frame parameters for ++@code{special-display-popup-frame} to use when it creates a frame. ++@end defopt ++ ++@defopt same-window-buffer-names ++A list of buffer names for buffers that should be displayed in the ++selected window. If the buffer's name is in this list, ++@code{display-buffer} handles the buffer by switching to it in the ++selected window. ++@end defopt ++ ++@defopt same-window-regexps ++A list of regular expressions that specify buffers that should be ++displayed in the selected window. If the buffer's name matches any of ++the regular expressions in this list, @code{display-buffer} handles the ++buffer by switching to it in the selected window. ++@end defopt ++ ++@defun same-window-p buffer-name ++This function returns @code{t} if displaying a buffer ++named @var{buffer-name} with @code{display-buffer} would ++put it in the selected window. ++@end defun ++ ++@c Emacs 19 feature ++@defopt display-buffer-function ++This variable is the most flexible way to customize the behavior of ++@code{display-buffer}. If it is non-@code{nil}, it should be a function ++that @code{display-buffer} calls to do the work. The function should ++accept two arguments, the first two arguments that @code{display-buffer} ++received. It should choose or create a window, display the specified ++buffer in it, and then return the window. ++ ++This variable takes precedence over all the other options described ++above. ++@end defopt ++ ++If all options described above fail to produce a suitable window, ++@code{display-buffer} tries to reuse an existing window. As a last ++resort, it will try to display @var{buffer-or-name} on a separate frame. ++In that case, the value of @code{pop-up-frames} is disregarded. ++ ++@node Dedicated Windows ++@section Dedicated Windows ++@cindex dedicated window ++ ++Functions for displaying a buffer can be told to not use specific ++windows by marking these windows as @dfn{dedicated} to their buffers. ++@code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated ++window for displaying another buffer in it. @code{get-lru-window} and ++@code{get-largest-window} (@pxref{Selecting Windows}) do not consider ++dedicated windows as candidates when their @var{dedicated} argument is ++non-@code{nil}. The behavior of @code{set-window-buffer} ++(@pxref{Buffers and Windows}) with respect to dedicated windows is ++slightly different, see below. ++ ++When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to delete ++a dedicated window and that window is the only window on its frame, it ++deletes the window's frame too, provided there are other frames left. ++@code{replace-buffer-in-windows} (@pxref{Displaying Buffers}) tries to ++delete all dedicated windows showing its buffer argument. When such a ++window is the only window on its frame, that frame is deleted, provided ++there are other frames left. If there are no more frames left, some ++other buffer is displayed in the window, and the window is marked as ++non-dedicated. ++ ++When you kill a buffer (@pxref{Killing Buffers}) displayed in a ++dedicated window, any such window usually gets deleted too, since ++@code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning ++up windows. Burying a buffer (@pxref{The Buffer List}) deletes the ++selected window if it is dedicated to that buffer. If, however, that ++window is the only window on its frame, @code{bury-buffer} displays ++another buffer in it and iconifies the frame. ++ ++@defun window-dedicated-p &optional window ++This function returns non-@code{nil} if @var{window} is dedicated to its ++buffer and @code{nil} otherwise. More precisely, the return value is ++the value assigned by the last call of @code{set-window-dedicated-p} for ++@var{window} or @code{nil} if that function was never called with ++@var{window} as its argument. The default for @var{window} is the ++selected window. ++@end defun ++ ++@defun set-window-dedicated-p window flag ++This function marks @var{window} as dedicated to its buffer if ++@var{flag} is non-@code{nil}, and non-dedicated otherwise. ++ ++As a special case, if @var{flag} is @code{t}, @var{window} becomes ++@dfn{strongly} dedicated to its buffer. @code{set-window-buffer} ++signals an error when the window it acts upon is strongly dedicated to ++its buffer and does not already display the buffer it is asked to ++display. Other functions do not treat @code{t} differently from any ++non-@code{nil} value. ++@end defun ++ ++@node Window Point ++@section Windows and Point ++@cindex window position ++@cindex window point ++@cindex position in window ++@cindex point in window ++ ++ Each window has its own value of point (@pxref{Point}), independent of ++the value of point in other windows displaying the same buffer. This ++makes it useful to have multiple windows showing one buffer. ++ ++@itemize @bullet ++@item ++The window point is established when a window is first created; it is ++initialized from the buffer's point, or from the window point of another ++window opened on the buffer if such a window exists. ++ ++@item ++Selecting a window sets the value of point in its buffer from the ++window's value of point. Conversely, deselecting a window sets the ++window's value of point from that of the buffer. Thus, when you switch ++between windows that display a given buffer, the point value for the ++selected window is in effect in the buffer, while the point values for ++the other windows are stored in those windows. ++ ++@item ++As long as the selected window displays the current buffer, the window's ++point and the buffer's point always move together; they remain equal. ++@end itemize ++ ++@cindex cursor ++ As far as the user is concerned, point is where the cursor is, and ++when the user switches to another buffer, the cursor jumps to the ++position of point in that buffer. ++ ++@defun window-point &optional window ++This function returns the current position of point in @var{window}. ++For a nonselected window, this is the value point would have (in that ++window's buffer) if that window were selected. The default for ++@var{window} is the selected window. ++ ++When @var{window} is the selected window and its buffer is also the ++current buffer, the value returned is the same as point in that buffer. ++Strictly speaking, it would be more correct to return the ``top-level'' ++value of point, outside of any @code{save-excursion} forms. But that ++value is hard to find. ++@end defun ++ ++@defun set-window-point window position ++This function positions point in @var{window} at position ++@var{position} in @var{window}'s buffer. It returns @var{position}. ++ ++If @var{window} is selected, and its buffer is current, ++this simply does @code{goto-char}. ++@end defun ++ ++@defvar window-point-insertion-type ++This variable specifies the marker insertion type (@pxref{Marker ++Insertion Types}) of @code{window-point}. The default is @code{nil}, ++so @code{window-point} will stay behind text inserted there. ++@end defvar ++ ++@node Window Start and End ++@section The Window Start and End Positions ++@cindex window start position ++ ++ Each window maintains a marker used to keep track of a buffer position ++that specifies where in the buffer display should start. This position ++is called the @dfn{display-start} position of the window (or just the ++@dfn{start}). The character after this position is the one that appears ++at the upper left corner of the window. It is usually, but not ++inevitably, at the beginning of a text line. ++ ++ After switching windows or buffers, and in some other cases, if the ++window start is in the middle of a line, Emacs adjusts the window ++start to the start of a line. This prevents certain operations from ++leaving the window start at a meaningless point within a line. This ++feature may interfere with testing some Lisp code by executing it ++using the commands of Lisp mode, because they trigger this ++readjustment. To test such code, put it into a command and bind the ++command to a key. ++ ++@defun window-start &optional window ++@cindex window top line ++This function returns the display-start position of window ++@var{window}. If @var{window} is @code{nil}, the selected window is ++used. For example, ++ ++@example ++@group ++(window-start) ++ @result{} 7058 ++@end group ++@end example ++ ++When you create a window, or display a different buffer in it, the ++display-start position is set to a display-start position recently used ++for the same buffer, or to @code{point-min} if the buffer doesn't have ++any. ++ ++Redisplay updates the window-start position (if you have not specified ++it explicitly since the previous redisplay)---to make sure point appears ++on the screen. Nothing except redisplay automatically changes the ++window-start position; if you move point, do not expect the window-start ++position to change in response until after the next redisplay. ++ ++For a realistic example of using @code{window-start}, see the ++description of @code{count-lines}. @xref{Definition of count-lines}. ++@end defun ++ ++@cindex window end position ++@defun window-end &optional window update ++This function returns the position where display of its buffer ends in ++@var{window}. The default for @var{window} is the selected window. ++ ++Simply changing the buffer text or moving point does not update the ++value that @code{window-end} returns. The value is updated only when ++Emacs redisplays and redisplay completes without being preempted. ++ ++If the last redisplay of @var{window} was preempted, and did not finish, ++Emacs does not know the position of the end of display in that window. ++In that case, this function returns @code{nil}. ++ ++If @var{update} is non-@code{nil}, @code{window-end} always returns an ++up-to-date value for where display ends, based on the current ++@code{window-start} value. If a previously saved value of that position ++is still valid, @code{window-end} returns that value; otherwise it ++computes the correct value by scanning the buffer text. ++ ++Even if @var{update} is non-@code{nil}, @code{window-end} does not ++attempt to scroll the display if point has moved off the screen, the ++way real redisplay would do. It does not alter the ++@code{window-start} value. In effect, it reports where the displayed ++text will end if scrolling is not required. ++@end defun ++ ++@defun set-window-start window position &optional noforce ++This function sets the display-start position of @var{window} to ++@var{position} in @var{window}'s buffer. It returns @var{position}. ++ ++The display routines insist that the position of point be visible when a ++buffer is displayed. Normally, they change the display-start position ++(that is, scroll the window) whenever necessary to make point visible. ++However, if you specify the start position with this function using ++@code{nil} for @var{noforce}, it means you want display to start at ++@var{position} even if that would put the location of point off the ++screen. If this does place point off screen, the display routines move ++point to the left margin on the middle line in the window. ++ ++For example, if point @w{is 1} and you set the start of the window ++@w{to 37}, the start of the next line, point will be ``above'' the top ++of the window. The display routines will automatically move point if ++it is still 1 when redisplay occurs. Here is an example: ++ ++@example ++@group ++;; @r{Here is what @samp{foo} looks like before executing} ++;; @r{the @code{set-window-start} expression.} ++@end group ++ ++@group ++---------- Buffer: foo ---------- ++@point{}This is the contents of buffer foo. ++2 ++3 ++4 ++5 ++6 ++---------- Buffer: foo ---------- ++@end group ++ ++@group ++(set-window-start ++ (selected-window) ++ (save-excursion ++ (goto-char 1) ++ (forward-line 1) ++ (point))) ++@result{} 37 ++@end group ++ ++@group ++;; @r{Here is what @samp{foo} looks like after executing} ++;; @r{the @code{set-window-start} expression.} ++---------- Buffer: foo ---------- ++2 ++3 ++@point{}4 ++5 ++6 ++---------- Buffer: foo ---------- ++@end group ++@end example ++ ++If @var{noforce} is non-@code{nil}, and @var{position} would place point ++off screen at the next redisplay, then redisplay computes a new window-start ++position that works well with point, and thus @var{position} is not used. ++@end defun ++ ++@defun pos-visible-in-window-p &optional position window partially ++This function returns non-@code{nil} if @var{position} is within the ++range of text currently visible on the screen in @var{window}. It ++returns @code{nil} if @var{position} is scrolled vertically out of view. ++Locations that are partially obscured are not considered visible unless ++@var{partially} is non-@code{nil}. The argument @var{position} defaults ++to the current position of point in @var{window}; @var{window}, to the ++selected window. If @var{position} is @code{t}, that means to check the ++last visible position in @var{window}. ++ ++The @code{pos-visible-in-window-p} function considers only vertical ++scrolling. If @var{position} is out of view only because @var{window} ++has been scrolled horizontally, @code{pos-visible-in-window-p} returns ++non-@code{nil} anyway. @xref{Horizontal Scrolling}. ++ ++If @var{position} is visible, @code{pos-visible-in-window-p} returns ++@code{t} if @var{partially} is @code{nil}; if @var{partially} is ++non-@code{nil}, and the character following @var{position} is fully ++visible, it returns a list of the form @code{(@var{x} @var{y})}, where ++@var{x} and @var{y} are the pixel coordinates relative to the top left ++corner of the window; otherwise it returns an extended list of the form ++@code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})}, ++where @var{rtop} and @var{rbot} specify the number of off-window pixels ++at the top and bottom of the row at @var{position}, @var{rowh} specifies ++the visible height of that row, and @var{vpos} specifies the vertical ++position (zero-based row number) of that row. ++ ++Here is an example: ++ ++@example ++@group ++;; @r{If point is off the screen now, recenter it now.} ++(or (pos-visible-in-window-p ++ (point) (selected-window)) ++ (recenter 0)) ++@end group ++@end example ++@end defun ++ ++@defun window-line-height &optional line window ++This function returns the height of text line @var{line} in ++@var{window}. If @var{line} is one of @code{header-line} or ++@code{mode-line}, @code{window-line-height} returns information about ++the corresponding line of the window. Otherwise, @var{line} is a text ++line number starting from 0. A negative number counts from the end of ++the window. The default for @var{line} is the current line in ++@var{window}; the default for @var{window} is the selected window. ++ ++If the display is not up to date, @code{window-line-height} returns ++@code{nil}. In that case, @code{pos-visible-in-window-p} may be used ++to obtain related information. ++ ++If there is no line corresponding to the specified @var{line}, ++@code{window-line-height} returns @code{nil}. Otherwise, it returns ++a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, ++where @var{height} is the height in pixels of the visible part of the ++line, @var{vpos} and @var{ypos} are the vertical position in lines and ++pixels of the line relative to the top of the first text line, and ++@var{offbot} is the number of off-window pixels at the bottom of the ++text line. If there are off-window pixels at the top of the (first) ++text line, @var{ypos} is negative. ++@end defun ++ ++@node Textual Scrolling ++@section Textual Scrolling ++@cindex textual scrolling ++@cindex scrolling textually ++ ++ @dfn{Textual scrolling} means moving the text up or down through a ++window. It works by changing the value of the window's display-start ++location. It may also change the value of @code{window-point} to keep ++point on the screen. ++ ++ Textual scrolling was formerly called ``vertical scrolling,'' but we ++changed its name to distinguish it from the new vertical fractional ++scrolling feature (@pxref{Vertical Scrolling}). ++ ++ In the commands @code{scroll-up} and @code{scroll-down}, the directions ++``up'' and ``down'' refer to the motion of the text in the buffer at which ++you are looking through the window. Imagine that the text is ++written on a long roll of paper and that the scrolling commands move the ++paper up and down. Thus, if you are looking at text in the middle of a ++buffer and repeatedly call @code{scroll-down}, you will eventually see ++the beginning of the buffer. ++ ++ Some people have urged that the opposite convention be used: they ++imagine that the window moves over text that remains in place. Then ++``down'' commands would take you to the end of the buffer. This view is ++more consistent with the actual relationship between windows and the ++text in the buffer, but it is less like what the user sees. The ++position of a window on the terminal does not move, and short scrolling ++commands clearly move the text up or down on the screen. We have chosen ++names that fit the user's point of view. ++ ++ The textual scrolling functions (aside from ++@code{scroll-other-window}) have unpredictable results if the current ++buffer is different from the buffer that is displayed in the selected ++window. @xref{Current Buffer}. ++ ++ If the window contains a row which is taller than the height of the ++window (for example in the presence of a large image), the scroll ++functions will adjust the window's vertical scroll position to scroll ++the partially visible row. To disable this feature, Lisp code may bind ++the variable @code{auto-window-vscroll} to @code{nil} (@pxref{Vertical ++Scrolling}). ++ ++@deffn Command scroll-up &optional count ++This function scrolls the text in the selected window upward ++@var{count} lines. If @var{count} is negative, scrolling is actually ++downward. ++ ++If @var{count} is @code{nil} (or omitted), then the length of scroll ++is @code{next-screen-context-lines} lines less than the usable height of ++the window (not counting its mode line). ++ ++@code{scroll-up} returns @code{nil}, unless it gets an error ++because it can't scroll any further. ++@end deffn ++ ++@deffn Command scroll-down &optional count ++This function scrolls the text in the selected window downward ++@var{count} lines. If @var{count} is negative, scrolling is actually ++upward. ++ ++If @var{count} is omitted or @code{nil}, then the length of the scroll ++is @code{next-screen-context-lines} lines less than the usable height of ++the window (not counting its mode line). ++ ++@code{scroll-down} returns @code{nil}, unless it gets an error because ++it can't scroll any further. ++@end deffn ++ ++@deffn Command scroll-other-window &optional count ++This function scrolls the text in another window upward @var{count} ++lines. Negative values of @var{count}, or @code{nil}, are handled ++as in @code{scroll-up}. ++ ++You can specify which buffer to scroll by setting the variable ++@code{other-window-scroll-buffer} to a buffer. If that buffer isn't ++already displayed, @code{scroll-other-window} displays it in some ++window. ++ ++When the selected window is the minibuffer, the next window is normally ++the one at the top left corner. You can specify a different window to ++scroll, when the minibuffer is selected, by setting the variable ++@code{minibuffer-scroll-window}. This variable has no effect when any ++other window is selected. When it is non-@code{nil} and the ++minibuffer is selected, it takes precedence over ++@code{other-window-scroll-buffer}. @xref{Definition of ++minibuffer-scroll-window}. ++ ++When the minibuffer is active, it is the next window if the selected ++window is the one at the bottom right corner. In this case, ++@code{scroll-other-window} attempts to scroll the minibuffer. If the ++minibuffer contains just one line, it has nowhere to scroll to, so the ++line reappears after the echo area momentarily displays the message ++@samp{Beginning of buffer}. ++@end deffn ++ ++@c Emacs 19 feature ++@defvar other-window-scroll-buffer ++If this variable is non-@code{nil}, it tells @code{scroll-other-window} ++which buffer's window to scroll. ++@end defvar ++ ++@defopt scroll-margin ++This option specifies the size of the scroll margin---a minimum number ++of lines between point and the top or bottom of a window. Whenever ++point gets within this many lines of the top or bottom of the window, ++redisplay scrolls the text automatically (if possible) to move point ++out of the margin, closer to the center of the window. ++@end defopt ++ ++@defopt scroll-conservatively ++This variable controls how scrolling is done automatically when point ++moves off the screen (or into the scroll margin). If the value is a ++positive integer @var{n}, then redisplay scrolls the text up to ++@var{n} lines in either direction, if that will bring point back into ++proper view. This behavior is called @dfn{conservative scrolling}. ++Otherwise, scrolling happens in the usual way, under the control of ++other variables such as @code{scroll-up-aggressively} and ++@code{scroll-down-aggressively}. ++ ++The default value is zero, which means that conservative scrolling ++never happens. ++@end defopt ++ ++@defopt scroll-down-aggressively ++The value of this variable should be either @code{nil} or a fraction ++@var{f} between 0 and 1. If it is a fraction, that specifies where on ++the screen to put point when scrolling down. More precisely, when a ++window scrolls down because point is above the window start, the new ++start position is chosen to put point @var{f} part of the window ++height from the top. The larger @var{f}, the more aggressive the ++scrolling. ++ ++A value of @code{nil} is equivalent to .5, since its effect is to center ++point. This variable automatically becomes buffer-local when set in any ++fashion. ++@end defopt ++ ++@defopt scroll-up-aggressively ++Likewise, for scrolling up. The value, @var{f}, specifies how far ++point should be placed from the bottom of the window; thus, as with ++@code{scroll-up-aggressively}, a larger value scrolls more aggressively. ++@end defopt ++ ++@defopt scroll-step ++This variable is an older variant of @code{scroll-conservatively}. The ++difference is that it if its value is @var{n}, that permits scrolling ++only by precisely @var{n} lines, not a smaller number. This feature ++does not work with @code{scroll-margin}. The default value is zero. ++@end defopt ++ ++@defopt scroll-preserve-screen-position ++If this option is @code{t}, scrolling which would move the current ++point position out of the window chooses the new position of point ++so that the vertical position of the cursor is unchanged, if possible. ++ ++If it is non-@code{nil} and not @code{t}, then the scrolling functions ++always preserve the vertical position of point, if possible. ++@end defopt ++ ++@defopt next-screen-context-lines ++The value of this variable is the number of lines of continuity to ++retain when scrolling by full screens. For example, @code{scroll-up} ++with an argument of @code{nil} scrolls so that this many lines at the ++bottom of the window appear instead at the top. The default value is ++@code{2}. ++@end defopt ++ ++@deffn Command recenter &optional count ++@cindex centering point ++This function scrolls the text in the selected window so that point is ++displayed at a specified vertical position within the window. It does ++not ``move point'' with respect to the text. ++ ++If @var{count} is a nonnegative number, that puts the line containing ++point @var{count} lines down from the top of the window. If ++@var{count} is a negative number, then it counts upward from the ++bottom of the window, so that @minus{}1 stands for the last usable ++line in the window. If @var{count} is a non-@code{nil} list, then it ++stands for the line in the middle of the window. ++ ++If @var{count} is @code{nil}, @code{recenter} puts the line containing ++point in the middle of the window, then clears and redisplays the entire ++selected frame. ++ ++When @code{recenter} is called interactively, @var{count} is the raw ++prefix argument. Thus, typing @kbd{C-u} as the prefix sets the ++@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets ++@var{count} to 4, which positions the current line four lines from the ++top. ++ ++With an argument of zero, @code{recenter} positions the current line at ++the top of the window. This action is so handy that some people make a ++separate key binding to do this. For example, ++ ++@example ++@group ++(defun line-to-top-of-window () ++ "Scroll current line to top of window. ++Replaces three keystroke sequence C-u 0 C-l." ++ (interactive) ++ (recenter 0)) ++ ++(global-set-key [kp-multiply] 'line-to-top-of-window) ++@end group ++@end example ++@end deffn ++ ++@node Vertical Scrolling ++@section Vertical Fractional Scrolling ++@cindex vertical fractional scrolling ++@cindex vertical scroll position ++ ++ @dfn{Vertical fractional scrolling} means shifting text in a window ++up or down by a specified multiple or fraction of a line. Each window ++has a @dfn{vertical scroll position}, which is a number, never less than ++zero. It specifies how far to raise the contents of the window. ++Raising the window contents generally makes all or part of some lines ++disappear off the top, and all or part of some other lines appear at the ++bottom. The usual value is zero. ++ ++ The vertical scroll position is measured in units of the normal line ++height, which is the height of the default font. Thus, if the value is ++.5, that means the window contents are scrolled up half the normal line ++height. If it is 3.3, that means the window contents are scrolled up ++somewhat over three times the normal line height. ++ ++ What fraction of a line the vertical scrolling covers, or how many ++lines, depends on what the lines contain. A value of .5 could scroll a ++line whose height is very short off the screen, while a value of 3.3 ++could scroll just part of the way through a tall line or an image. ++ ++@defun window-vscroll &optional window pixels-p ++This function returns the current vertical scroll position of ++@var{window}. The default for @var{window} is the selected window. ++If @var{pixels-p} is non-@code{nil}, the return value is measured in ++pixels, rather than in units of the normal line height. ++ ++@example ++@group ++(window-vscroll) ++ @result{} 0 ++@end group ++@end example ++@end defun ++ ++@defun set-window-vscroll window lines &optional pixels-p ++This function sets @var{window}'s vertical scroll position to ++@var{lines}. If @var{window} is @code{nil}, the selected window is ++used. The argument @var{lines} should be zero or positive; if not, it ++is taken as zero. ++ ++ ++The actual vertical scroll position must always correspond ++to an integral number of pixels, so the value you specify ++is rounded accordingly. ++ ++The return value is the result of this rounding. ++ ++@example ++@group ++(set-window-vscroll (selected-window) 1.2) ++ @result{} 1.13 ++@end group ++@end example ++ ++If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of ++pixels. In this case, the return value is @var{lines}. ++@end defun ++ ++@defvar auto-window-vscroll ++If this variable is non-@code{nil}, the line-move, scroll-up, and ++scroll-down functions will automatically modify the vertical scroll ++position to scroll through display rows that are taller than the height ++of the window, for example in the presence of large images. ++@end defvar ++ ++@node Horizontal Scrolling ++@section Horizontal Scrolling ++@cindex horizontal scrolling ++ ++ @dfn{Horizontal scrolling} means shifting the image in the window left ++or right by a specified multiple of the normal character width. Each ++window has a @dfn{horizontal scroll position}, which is a number, never ++less than zero. It specifies how far to shift the contents left. ++Shifting the window contents left generally makes all or part of some ++characters disappear off the left, and all or part of some other ++characters appear at the right. The usual value is zero. ++ ++ The horizontal scroll position is measured in units of the normal ++character width, which is the width of space in the default font. Thus, ++if the value is 5, that means the window contents are scrolled left by 5 ++times the normal character width. How many characters actually ++disappear off to the left depends on their width, and could vary from ++line to line. ++ ++ Because we read from side to side in the ``inner loop,'' and from top ++to bottom in the ``outer loop,'' the effect of horizontal scrolling is ++not like that of textual or vertical scrolling. Textual scrolling ++involves selection of a portion of text to display, and vertical ++scrolling moves the window contents contiguously; but horizontal ++scrolling causes part of @emph{each line} to go off screen. ++ ++ Usually, no horizontal scrolling is in effect; then the leftmost ++column is at the left edge of the window. In this state, scrolling to ++the right is meaningless, since there is no data to the left of the edge ++to be revealed by it; so this is not allowed. Scrolling to the left is ++allowed; it scrolls the first columns of text off the edge of the window ++and can reveal additional columns on the right that were truncated ++before. Once a window has a nonzero amount of leftward horizontal ++scrolling, you can scroll it back to the right, but only so far as to ++reduce the net horizontal scroll to zero. There is no limit to how far ++left you can scroll, but eventually all the text will disappear off the ++left edge. ++ ++@vindex auto-hscroll-mode ++ If @code{auto-hscroll-mode} is set, redisplay automatically alters ++the horizontal scrolling of a window as necessary to ensure that point ++is always visible. However, you can still set the horizontal ++scrolling value explicitly. The value you specify serves as a lower ++bound for automatic scrolling, i.e. automatic scrolling will not ++scroll a window to a column less than the specified one. ++ ++@deffn Command scroll-left &optional count set-minimum ++This function scrolls the selected window @var{count} columns to the ++left (or to the right if @var{count} is negative). The default ++for @var{count} is the window width, minus 2. ++ ++The return value is the total amount of leftward horizontal scrolling in ++effect after the change---just like the value returned by ++@code{window-hscroll} (below). ++ ++Once you scroll a window as far right as it can go, back to its normal ++position where the total leftward scrolling is zero, attempts to scroll ++any farther right have no effect. ++ ++If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes ++the lower bound for automatic scrolling; that is, automatic scrolling ++will not scroll a window to a column less than the value returned by ++this function. Interactive calls pass non-@code{nil} for ++@var{set-minimum}. ++@end deffn ++ ++@deffn Command scroll-right &optional count set-minimum ++This function scrolls the selected window @var{count} columns to the ++right (or to the left if @var{count} is negative). The default ++for @var{count} is the window width, minus 2. Aside from the direction ++of scrolling, this works just like @code{scroll-left}. ++@end deffn ++ ++@defun window-hscroll &optional window ++This function returns the total leftward horizontal scrolling of ++@var{window}---the number of columns by which the text in @var{window} ++is scrolled left past the left margin. The default for ++@var{window} is the selected window. ++ ++The return value is never negative. It is zero when no horizontal ++scrolling has been done in @var{window} (which is usually the case). ++ ++ ++@example ++@group ++(window-hscroll) ++ @result{} 0 ++@end group ++@group ++(scroll-left 5) ++ @result{} 5 ++@end group ++@group ++(window-hscroll) ++ @result{} 5 ++@end group ++@end example ++@end defun ++ ++@defun set-window-hscroll window columns ++This function sets horizontal scrolling of @var{window}. The value of ++@var{columns} specifies the amount of scrolling, in terms of columns ++from the left margin. The argument @var{columns} should be zero or ++positive; if not, it is taken as zero. Fractional values of ++@var{columns} are not supported at present. ++ ++Note that @code{set-window-hscroll} may appear not to work if you test ++it by evaluating a call with @kbd{M-:} in a simple way. What happens ++is that the function sets the horizontal scroll value and returns, but ++then redisplay adjusts the horizontal scrolling to make point visible, ++and this overrides what the function did. You can observe the ++function's effect if you call it while point is sufficiently far from ++the left margin that it will remain visible. ++ ++The value returned is @var{columns}. ++ ++@example ++@group ++(set-window-hscroll (selected-window) 10) ++ @result{} 10 ++@end group ++@end example ++@end defun ++ ++ Here is how you can determine whether a given position @var{position} ++is off the screen due to horizontal scrolling: ++ ++@example ++@group ++(defun hscroll-on-screen (window position) ++ (save-excursion ++ (goto-char position) ++ (and ++ (>= (- (current-column) (window-hscroll window)) 0) ++ (< (- (current-column) (window-hscroll window)) ++ (window-width window))))) ++@end group ++@end example ++ ++@node Size of Window ++@section The Size of a Window ++@cindex window size ++@cindex size of window ++ ++ An Emacs window is rectangular, and its size information consists of ++the height (the number of lines) and the width (the number of character ++positions in each line). The mode line is included in the height. But ++the width does not count the scroll bar or the column of @samp{|} ++characters that separates side-by-side windows. ++ ++ The following three functions return size information about a window: ++ ++@defun window-height &optional window ++This function returns the number of lines in @var{window}, including its ++mode line and header line, if any. If @var{window} fills its entire ++frame except for the echo area, this is typically one less than the ++value of @code{frame-height} on that frame. The default for ++@var{window} is the selected window. ++ ++@example ++@group ++(window-height) ++ @result{} 23 ++@end group ++@group ++(split-window-vertically) ++ @result{} # ++@end group ++@group ++(window-height) ++ @result{} 11 ++@end group ++@end example ++@end defun ++ ++@defun window-body-height &optional window ++Like @code{window-height} but the value does not include the ++mode line (if any) or the header line (if any). ++@end defun ++ ++@defun window-width &optional window ++This function returns the number of columns in @var{window}. The ++default for @var{window} is the selected window. ++ ++The return value does not include the window's scroll bar or the column ++of @samp{|} characters that separates side-by-side windows. Moreover, ++the return value does not include the space used for displaying fringes ++and margins. Hence you cannot, in general, compare the return values of ++@code{window-width} and @code{frame-width} for equality to determine ++whether a window is a wide as the containing frame. Use the function ++@code{window-full-width-p}, see below, instead. ++ ++@example ++@group ++(window-width) ++ @result{} 80 ++@end group ++@end example ++@end defun ++ ++@defun window-full-width-p &optional window ++This function returns non-@code{nil} if @var{window} is as wide as the ++frame that contains it; otherwise @code{nil}. The default for ++@var{window} is the selected window. ++@end defun ++ ++@defun window-edges &optional window ++This function returns a list of the edge coordinates of @var{window}. ++The default for @var{window} is the selected window. ++ ++The order of the list is @code{(@var{left} @var{top} @var{right} ++@var{bottom})}, all elements relative to 0, 0 at the top left corner of ++the frame. The element @var{right} of the value is one more than the ++rightmost column used by @var{window}, and @var{bottom} is one more than ++the bottommost row used by @var{window} and its mode-line. ++ ++The edges include the space used by the window's scroll bar, display ++margins, fringes, header line, and mode line, if it has them. Also, ++if the window has a neighbor on the right, its right edge value ++includes the width of the separator line between the window and that ++neighbor. Since the width of the window does not include this ++separator, the width does not usually equal the difference between the ++right and left edges. ++@end defun ++ ++@defun window-inside-edges &optional window ++This is similar to @code{window-edges}, but the edge values ++it returns include only the text area of the window. They ++do not include the header line, mode line, scroll bar or ++vertical separator, fringes, or display margins. ++@end defun ++ ++Here are the results obtained on a typical 24-line terminal with just ++one window, with menu bar enabled: ++ ++@example ++@group ++(window-edges (selected-window)) ++ @result{} (0 1 80 23) ++@end group ++@group ++(window-inside-edges (selected-window)) ++ @result{} (0 1 80 22) ++@end group ++@end example ++ ++@noindent ++The bottom edge is at line 23 because the last line is the echo area. ++The bottom inside edge is at line 22, which is the window's mode line. ++ ++If @var{window} is at the upper left corner of its frame, and there is ++no menu bar, then @var{bottom} returned by @code{window-edges} is the ++same as the value of @code{(window-height)}, @var{right} is almost the ++same as the value of @code{(window-width)}, and @var{top} and ++@var{left} are zero. For example, the edges of the following window ++are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8 ++columns, the last column of the window (column 7) holds a border ++rather than text. The last row (row 4) holds the mode line, shown ++here with @samp{xxxxxxxxx}. ++ ++@example ++@group ++ 0 ++ _______ ++ 0 | | ++ | | ++ | | ++ | | ++ xxxxxxxxx 4 ++ ++ 7 ++@end group ++@end example ++ ++In the following example, let's suppose that the frame is 7 ++columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} ++and the edges of the right window are @w{@samp{4 0 7 3}}. ++The inside edges of the left window are @w{@samp{0 0 3 2}}, ++and the inside edges of the right window are @w{@samp{4 0 7 2}}, ++ ++@example ++@group ++ ___ ___ ++ | | | ++ | | | ++ xxxxxxxxx ++ ++ 0 34 7 ++@end group ++@end example ++ ++@defun window-pixel-edges &optional window ++This function is like @code{window-edges} except that, on a graphical ++display, the edge values are measured in pixels instead of in ++character lines and columns. ++@end defun ++ ++@defun window-inside-pixel-edges &optional window ++This function is like @code{window-inside-edges} except that, on a ++graphical display, the edge values are measured in pixels instead of ++in character lines and columns. ++@end defun ++ ++@node Resizing Windows ++@section Changing the Size of a Window ++@cindex window resizing ++@cindex resize window ++@cindex changing window size ++@cindex window size, changing ++ ++ The window size functions fall into two classes: high-level commands ++that change the size of windows and low-level functions that access ++window size. Emacs does not permit overlapping windows or gaps between ++windows, so resizing a window always affects at least one other window. ++ ++@deffn Command enlarge-window size &optional horizontal ++This function makes the selected window @var{size} lines taller by ++stealing lines from windows above or below. In a first round, it takes ++lines from one window at a time until that window is ++@code{window-min-height} lines tall, then takes from another. If, at ++the end of the first round, the selected window is still not tall ++enough, @code{enlarge-window} starts a second round, where it deletes ++windows above or below the selected one. ++ ++If @var{horizontal} is non-@code{nil}, this function makes the window ++@var{size} columns wider, stealing columns instead of lines. If a ++window from which columns are stolen shrinks below ++@code{window-min-width} columns, that window disappears. ++ ++If the requested size would exceed that of the window's frame, then the ++function makes the window occupy the entire height (or width) of the ++frame. ++ ++If there are various other windows from which lines or columns can be ++stolen, and some of them specify fixed size (using ++@code{window-size-fixed}, see below), they are left untouched while ++other windows are ``robbed.'' If it would be necessary to alter the ++size of a fixed-size window, @code{enlarge-window} gets an error ++instead. ++ ++If @var{size} is negative, this function shrinks the selected window by ++@minus{}@var{size} lines or columns. If that makes the window smaller ++than the minimum size (@code{window-min-height} and ++@code{window-min-width}), then @code{enlarge-window} deletes the window. ++ ++@code{enlarge-window} returns @code{nil}. ++@end deffn ++ ++@deffn Command enlarge-window-horizontally columns ++This function makes the selected window @var{columns} wider. ++It could be defined as follows: ++ ++@example ++@group ++(defun enlarge-window-horizontally (columns) ++ (interactive "p") ++ (enlarge-window columns t)) ++@end group ++@end example ++@end deffn ++ ++@deffn Command shrink-window size &optional horizontal ++This function is like @code{enlarge-window} but negates the argument ++@var{size}, making the selected window smaller by giving lines (or ++columns) to the other windows. If the window shrinks below ++@code{window-min-height} or @code{window-min-width}, then it disappears. ++ ++If @var{size} is negative, the window is enlarged by @minus{}@var{size} ++lines or columns. ++@end deffn ++ ++@deffn Command shrink-window-horizontally columns ++This function makes the selected window @var{columns} narrower. ++It could be defined as follows: ++ ++@example ++@group ++(defun shrink-window-horizontally (columns) ++ (interactive "p") ++ (shrink-window columns t)) ++@end group ++@end example ++@end deffn ++ ++@defun adjust-window-trailing-edge window delta horizontal ++This function makes the selected window @var{delta} lines taller or ++@var{delta} columns wider, by moving the bottom or right edge. This ++function does not delete other windows; if it cannot make the ++requested size adjustment, it signals an error. On success, this ++function returns @code{nil}. ++@end defun ++ ++@deffn Command fit-window-to-buffer &optional window max-height min-height ++This command makes @var{window} the right height to display its ++contents exactly. The default for @var{window} is the selected window. ++ ++The optional argument @var{max-height} specifies the maximum height the ++window is allowed to be; @code{nil} means use the maximum permissible ++height of a window on @var{window}'s frame. The optional argument ++@var{min-height} specifies the minimum height for the window; @code{nil} ++means use @code{window-min-height}. All these height values include the ++mode line and/or header line. ++ ++This function can delete windows when their height shrinks below ++@var{min-height}. It returns non-@code{nil} if it orderly resized ++@var{window}, and @code{nil} otherwise. ++@end deffn ++ ++@deffn Command shrink-window-if-larger-than-buffer &optional window ++This command shrinks @var{window} vertically to be as small as possible ++while still showing the full contents of its buffer---but not less than ++@code{window-min-height} lines. The default for @var{window} is ++the selected window. ++ ++However, this command does nothing if the window is already too small to ++display the whole text of the buffer, or if part of the contents are ++currently scrolled off screen, or if the window is not the full width of ++its frame, or if the window is the only window in its frame. ++ ++This command returns non-@code{nil} if it actually shrank the window ++and @code{nil} otherwise. ++@end deffn ++ ++@cindex fixed-size window ++@defvar window-size-fixed ++If this variable is non-@code{nil}, in a given buffer, then the size of ++any window displaying that buffer remains fixed unless you either ++explicitly change it or Emacs has no other choice. ++ ++If the value is @code{height}, then only the window's height is fixed; ++if the value is @code{width}, then only the window's width is fixed. ++Any other non-@code{nil} value fixes both the width and the height. ++ ++This variable automatically becomes buffer-local when set. ++ ++Explicit size-change functions such as @code{enlarge-window} ++get an error if they would have to change a window size which is fixed. ++Therefore, when you want to change the size of such a window, ++you should bind @code{window-size-fixed} to @code{nil}, like this: ++ ++@example ++(let ((window-size-fixed nil)) ++ (enlarge-window 10)) ++@end example ++ ++Deleting an adjacent window or changing the frame size may change the ++size of a fixed-size window, if there is no other alternative. ++@end defvar ++ ++@cindex minimum window size ++ The following two variables constrain the window-structure-changing ++functions to a minimum height and width. ++ ++@defopt window-min-height ++The value of this variable specifies how short a window may become ++before it is automatically deleted. Making a window smaller than ++@code{window-min-height} automatically deletes it, and no window may be ++created shorter than this. The value is measured in line units. When ++the window wants a mode line and/or a header line, they are counted as ++one line each. The default value is @code{4}. A value less than ++@code{1} is ignored. ++@end defopt ++ ++@defopt window-min-width ++The value of this variable specifies how narrow a window may become ++before it is automatically deleted. Making a window smaller than ++@code{window-min-width} automatically deletes it, and no window may be ++created narrower than this. The value is measured in characters and ++includes any fringes or the scroll bar. The default value is @code{10}. ++A value less than @code{2} is ignored. ++@end defopt ++ ++@cindex balancing window sizes ++Emacs provides two functions to balance windows, that is, to even out ++the sizes of windows on the same frame. The minibuffer window and ++fixed-size windows are not resized by these functions. ++ ++@deffn Command balance-windows &optional window-or-frame ++This function balances windows in a way that gives more space to ++full-width and/or full-height windows. If @var{window-or-frame} ++specifies a frame, it balances all windows on that frame. If ++@var{window-or-frame} specifies a window, it balances this window and ++its ``siblings'' only. Think of a sibling as the other (original or ++new) window with respect to the present one, involved in the process of ++splitting; see @ref{Splitting Windows}. Since a sibling may have been ++split again, a window can have more than one sibling. ++@end deffn ++ ++@deffn Command balance-windows-area ++This function attempts to give all windows on the selected frame ++approximately the same share of the screen area. This means that ++full-width or full-height windows are not given more space than other ++windows. ++@end deffn ++ ++@node Coordinates and Windows ++@section Coordinates and Windows ++ ++This section describes how to relate screen coordinates to windows. ++ ++@defun window-at x y &optional frame ++This function returns the window containing the specified cursor ++position in the frame @var{frame}. The coordinates @var{x} and @var{y} ++are measured in characters and count from the top left corner of the ++frame. If they are out of range, @code{window-at} returns @code{nil}. ++ ++If you omit @var{frame}, the selected frame is used. ++@end defun ++ ++@defun coordinates-in-window-p coordinates window ++This function checks whether a particular frame position falls within ++the window @var{window}. ++ ++The argument @var{coordinates} is a cons cell of the form @code{(@var{x} ++. @var{y})}. The coordinates @var{x} and @var{y} are measured in ++characters, and count from the top left corner of the screen or frame. ++ ++The value returned by @code{coordinates-in-window-p} is non-@code{nil} ++if the coordinates are inside @var{window}. The value also indicates ++what part of the window the position is in, as follows: ++ ++@table @code ++@item (@var{relx} . @var{rely}) ++The coordinates are inside @var{window}. The numbers @var{relx} and ++@var{rely} are the equivalent window-relative coordinates for the ++specified position, counting from 0 at the top left corner of the ++window. ++ ++@item mode-line ++The coordinates are in the mode line of @var{window}. ++ ++@item header-line ++The coordinates are in the header line of @var{window}. ++ ++@item vertical-line ++The coordinates are in the vertical line between @var{window} and its ++neighbor to the right. This value occurs only if the window doesn't ++have a scroll bar; positions in a scroll bar are considered outside the ++window for these purposes. ++ ++@item left-fringe ++@itemx right-fringe ++The coordinates are in the left or right fringe of the window. ++ ++@item left-margin ++@itemx right-margin ++The coordinates are in the left or right margin of the window. ++ ++@item nil ++The coordinates are not in any part of @var{window}. ++@end table ++ ++The function @code{coordinates-in-window-p} does not require a frame as ++argument because it always uses the frame that @var{window} is on. ++@end defun ++ ++@node Window Tree ++@section The Window Tree ++@cindex window tree ++ ++ A @dfn{window tree} specifies the layout, size, and relationship ++between all windows in one frame. ++ ++@defun window-tree &optional frame ++This function returns the window tree for frame @var{frame}. ++If @var{frame} is omitted, the selected frame is used. ++ ++The return value is a list of the form @code{(@var{root} @var{mini})}, ++where @var{root} represents the window tree of the frame's ++root window, and @var{mini} is the frame's minibuffer window. ++ ++If the root window is not split, @var{root} is the root window itself. ++Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} ++@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split, ++and @code{t} for a vertical split, @var{edges} gives the combined size and ++position of the subwindows in the split, and the rest of the elements ++are the subwindows in the split. Each of the subwindows may again be ++a window or a list representing a window split, and so on. The ++@var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})} ++similar to the value returned by @code{window-edges}. ++@end defun ++ ++@node Window Configurations ++@section Window Configurations ++@cindex window configurations ++@cindex saving window information ++ ++ A @dfn{window configuration} records the entire layout of one ++frame---all windows, their sizes, which buffers they contain, how those ++buffers are scrolled, and their values of point and the mark; also their ++fringes, margins, and scroll bar settings. It also includes the value ++of @code{minibuffer-scroll-window}. As a special exception, the window ++configuration does not record the value of point in the selected window ++for the current buffer. Also, the window configuration does not record ++the values of window parameters; see @ref{Window Parameters}. ++ ++ You can bring back an entire frame layout by restoring a previously ++saved window configuration. If you want to record the layout of all ++frames instead of just one, use a frame configuration instead of a ++window configuration; see @ref{Frame Configurations}. ++ ++@defun current-window-configuration &optional frame ++This function returns a new object representing @var{frame}'s current ++window configuration. The default for @var{frame} is the selected ++frame. ++@end defun ++ ++@defun set-window-configuration configuration ++This function restores the configuration of windows and buffers as ++specified by @var{configuration}, for the frame that @var{configuration} ++was created for. ++ ++The argument @var{configuration} must be a value that was previously ++returned by @code{current-window-configuration}. The configuration is ++restored in the frame from which @var{configuration} was made, whether ++that frame is selected or not. This always counts as a window size ++change and triggers execution of the @code{window-size-change-functions} ++(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't ++know how to tell whether the new configuration actually differs from the ++old one. ++ ++If the frame which @var{configuration} was saved from is dead, all this ++function does is restore the three variables @code{window-min-height}, ++@code{window-min-width} and @code{minibuffer-scroll-window}. In this ++case, the function returns @code{nil}. Otherwise, it returns @code{t}. ++ ++Here is a way of using this function to get the same effect ++as @code{save-window-excursion}: ++ ++@example ++@group ++(let ((config (current-window-configuration))) ++ (unwind-protect ++ (progn (split-window-vertically nil) ++ @dots{}) ++ (set-window-configuration config))) ++@end group ++@end example ++@end defun ++ ++@defspec save-window-excursion forms@dots{} ++This special form records the window configuration, executes @var{forms} ++in sequence, then restores the earlier window configuration. The window ++configuration includes, for each window, the value of point and the ++portion of the buffer that is visible. It also includes the choice of ++selected window. However, it does not include the value of point in ++the current buffer; use @code{save-excursion} also, if you wish to ++preserve that. ++ ++Don't use this construct when @code{save-selected-window} is sufficient. ++ ++Exit from @code{save-window-excursion} always triggers execution of ++@code{window-size-change-functions}. (It doesn't know how to tell ++whether the restored configuration actually differs from the one in ++effect at the end of the @var{forms}.) ++ ++The return value is the value of the final form in @var{forms}. ++For example: ++ ++@example ++@group ++(split-window) ++ @result{} # ++@end group ++@group ++(setq w (selected-window)) ++ @result{} # ++@end group ++@group ++(save-window-excursion ++ (delete-other-windows w) ++ (switch-to-buffer "foo") ++ 'do-something) ++ @result{} do-something ++ ;; @r{The screen is now split again.} ++@end group ++@end example ++@end defspec ++ ++@defun window-configuration-p object ++This function returns @code{t} if @var{object} is a window configuration. ++@end defun ++ ++@defun compare-window-configurations config1 config2 ++This function compares two window configurations as regards the ++structure of windows, but ignores the values of point and mark and the ++saved scrolling positions---it can return @code{t} even if those ++aspects differ. ++ ++The function @code{equal} can also compare two window configurations; it ++regards configurations as unequal if they differ in any respect, even a ++saved point or mark. ++@end defun ++ ++@defun window-configuration-frame config ++This function returns the frame for which the window configuration ++@var{config} was made. ++@end defun ++ ++ Other primitives to look inside of window configurations would make ++sense, but are not implemented because we did not need them. See the ++file @file{winner.el} for some more operations on windows ++configurations. ++ ++@node Window Parameters ++@section Window Parameters ++@cindex window parameters ++ ++This sections describes how window parameters can be used to associate ++additional information with windows. ++ ++@defun window-parameter window parameter ++This function returns @var{window}'s value for @var{parameter}. The ++default for @var{window} is the selected window. If @var{window} ++has no setting for @var{parameter}, this function returns @code{nil}. ++@end defun ++ ++@defun window-parameters &optional window ++This function returns all parameters of @var{window} and their values. ++The default for @var{window} is the selected window. The return value ++is an association list of elements of the form @code{(@var{parameter} ++. @var{value})}. ++@end defun ++ ++@defun set-window-parameter window parameter value ++This function sets @var{window}'s value of @var{parameter} to ++@var{value} and returns @var{value}. The default for @var{window} ++is the selected window. ++@end defun ++ ++Currently, window parameters are not saved in window configurations and ++consequently not restored by @code{set-window-configuration}. Hence, ++any change of a parameter introduced via @code{set-window-parameter} can ++be undone only by invoking @code{set-window-parameter} for the same ++parameter again. Since @code{save-window-excursion} relies on window ++configurations (@pxref{Window Configurations}), window parameters are ++not saved and restored by that special form, either. ++ ++@node Window Hooks ++@section Hooks for Window Scrolling and Changes ++@cindex hooks for window operations ++ ++This section describes how a Lisp program can take action whenever a ++window displays a different part of its buffer or a different buffer. ++There are three actions that can change this: scrolling the window, ++switching buffers in the window, and changing the size of the window. ++The first two actions run @code{window-scroll-functions}; the last runs ++@code{window-size-change-functions}. ++ ++@defvar window-scroll-functions ++This variable holds a list of functions that Emacs should call before ++redisplaying a window with scrolling. Displaying a different buffer in ++the window also runs these functions. ++ ++This variable is not a normal hook, because each function is called with ++two arguments: the window, and its new display-start position. ++ ++These functions must be careful in using @code{window-end} ++(@pxref{Window Start and End}); if you need an up-to-date value, you ++must use the @var{update} argument to ensure you get it. ++ ++@strong{Warning:} don't use this feature to alter the way the window ++is scrolled. It's not designed for that, and such use probably won't ++work. ++@end defvar ++ ++@defvar window-size-change-functions ++This variable holds a list of functions to be called if the size of any ++window changes for any reason. The functions are called just once per ++redisplay, and just once for each frame on which size changes have ++occurred. ++ ++Each function receives the frame as its sole argument. There is no ++direct way to find out which windows on that frame have changed size, or ++precisely how. However, if a size-change function records, at each ++call, the existing windows and their sizes, it can also compare the ++present sizes and the previous sizes. ++ ++Creating or deleting windows counts as a size change, and therefore ++causes these functions to be called. Changing the frame size also ++counts, because it changes the sizes of the existing windows. ++ ++It is not a good idea to use @code{save-window-excursion} (@pxref{Window ++Configurations}) in these functions, because that always counts as a ++size change, and it would cause these functions to be called over and ++over. In most cases, @code{save-selected-window} (@pxref{Selecting ++Windows}) is what you need here. ++@end defvar ++ ++@defvar window-configuration-change-hook ++A normal hook that is run every time you change the window configuration ++of an existing frame. This includes splitting or deleting windows, ++changing the sizes of windows, or displaying a different buffer in a ++window. ++ ++The buffer-local part of this hook is run once per each window on the ++affected frame, with the relevant window selected and its buffer ++current. The global part is run once for the modified frame, with that ++frame selected. ++@end defvar ++ ++ In addition, you can use @code{jit-lock-register} to register a Font ++Lock fontification function, which will be called whenever parts of a ++buffer are (re)fontified because a window was scrolled or its size ++changed. @xref{Other Font Lock Variables}. ++ ++@ignore ++ arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3 ++@end ignore +diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi +new file mode 100644 +index 0000000..8a2f102 +--- /dev/null ++++ b/doc/misc/ada-mode.texi +@@ -0,0 +1,1530 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/ada-mode ++@settitle Ada Mode ++ ++@copying ++Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code. ++@end direntry ++ ++@titlepage ++@sp 10 ++@title{Ada Mode} ++@sp 2 ++@subtitle An Emacs major mode for programming in Ada ++@subtitle Ada Mode Version 4.00 ++@sp 2 ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top, Overview, (dir), (dir) ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview:: ++* Installation:: Installing Ada mode on your system ++* Customization:: Setting up Ada mode to your taste ++* Compiling Executing:: Working with your application within Emacs ++* Project files:: Describing the organization of your project ++* Compiling Examples:: A small tutorial ++* Moving Through Ada Code:: Moving easily through Ada sources ++* Identifier completion:: Finishing words automatically ++* Automatic Smart Indentation:: Indenting your code automatically as you type ++* Formatting Parameter Lists:: Formatting subprograms' parameter lists ++ automatically ++* Automatic Casing:: Adjusting the case of words automatically ++* Statement Templates:: Inserting code templates ++* Comment Handling:: Reformatting comments easily ++* GNU Free Documentation License:: The license for this documentation. ++* Index:: ++@end menu ++ ++ ++@node Overview, Installation, Top, Top ++@chapter Overview ++ ++The Emacs mode for programming in Ada helps the user in understanding ++existing code and facilitates writing new code. ++ ++When the Gnu Ada compiler GNAT is used, the cross-reference ++information output by the compiler is used to provide powerful code ++navigation (jump to definition, find all uses, etc). ++ ++When you open a file with a file extension of @file{.ads} or ++@file{.adb}, Emacs will automatically load and activate Ada mode. ++ ++Ada mode works without any customization, if you are using the GNAT ++compiler (@url{https://libre2.adacore.com/}) and the GNAT default ++naming convention. ++ ++You must customize a few things if you are using a different compiler ++or file naming convention; @xref{Other compiler}, @xref{Non-standard ++file names}. ++ ++In addition, you may want to customize the indentation, ++capitalization, and other things; @xref{Other customization}. ++ ++Finally, for large Ada projects, you will want to set up an Emacs ++Ada mode project file for each project; @xref{Project files}. Note ++that these are different from the GNAT project files used by gnatmake ++and other GNAT commands. ++ ++See the Emacs info manual, section 'Running Debuggers Under Emacs', ++for general information on debugging. ++ ++@node Installation, Customization, Overview, Top ++@chapter Installation ++ ++Ada mode is part of the standard Emacs distribution; if you use that, ++no files need to be installed. ++ ++Ada mode is also available as a separate distribution, from the Emacs ++Ada mode website ++@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The ++separate distribution may be more recent. ++ ++For installing the separate distribution, see the @file{README} file ++in the distribution. ++ ++To see what version of Ada mode you have installed, do @kbd{M-x ++ada-mode-version}. ++ ++The following files are provided with the Ada mode distribution: ++ ++@itemize @bullet ++ ++@item ++@file{ada-mode.el}: The main file for Ada mode, providing indentation, ++formatting of parameter lists, moving through code, comment handling ++and automatic casing. ++ ++@item ++@file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs ++widgets. ++ ++@item ++@file{ada-stmt.el}: Ada statement templates. ++ ++@item ++@file{ada-xref.el}: GNAT cross-references, completion of identifiers, ++and compilation. Also provides project files (which are not ++GNAT-specific). ++ ++@end itemize ++ ++@node Customization, Compiling Executing, Installation, Top ++@chapter Customizing Ada mode ++ ++Here we assume you are familiar with setting variables in Emacs, ++either thru 'customize' or in elisp (in your @file{.emacs} file). For ++a basic introduction to customize, elisp, and Emacs in general, see ++the tutorial in ++@iftex ++@cite{The GNU Emacs Manual}. ++@end iftex ++@ifhtml ++@cite{The GNU Emacs Manual}. ++@end ifhtml ++@ifinfo ++@ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}. ++@end ifinfo ++ ++These global Emacs settings are strongly recommended (put them in your ++.emacs): ++ ++@example ++(global-font-lock-mode t) ++(transient-mark-mode t) ++@end example ++ ++@samp{(global-font-lock-mode t)} turns on syntax ++highlighting for all buffers (it is off by default because it may be ++too slow for some machines). ++ ++@samp{(transient-mark-mode t)} highlights selected text. ++ ++See the Emacs help for each of these variables for more information. ++ ++@menu ++* Non-standard file names:: ++* Other compiler:: ++* Other customization:: ++@end menu ++ ++@node Non-standard file names, Other compiler, Customization, Customization ++@section Non-standard file names ++ ++By default, Ada mode is configured to use the GNAT file naming ++convention, where file names are a simple modification of the Ada ++names, and the extension for specs and bodies are ++@samp{.ads} and @samp{.adb}, respectively. ++ ++Ada mode uses the file extentions to allow moving from a package body ++to the corresponding spec and back. ++ ++Ada mode supports a list of alternative file extensions for specs and bodies. ++ ++For instance, if your spec and bodies files are called ++@file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you ++can add the following to your @file{.emacs} file: ++ ++@example ++(ada-add-extensions "_s.ada" "_b.ada") ++@end example ++ ++You can define additional extensions: ++ ++@example ++(ada-add-extensions ".ads" "_b.ada") ++(ada-add-extensions ".ads" ".body") ++@end example ++ ++This means that whenever Ada mode looks for the body for a file ++whose extension is @file{.ads}, it will take the first available file ++that ends with either @file{.adb}, @file{_b.ada} or ++@file{.body}. ++ ++Simililarly, if Ada mode is looking for a spec, it will look for ++@file{.ads} or @file{_s.ada}. ++ ++If the filename is not derived from the Ada name following the GNAT ++convention, things are a little more complicated. You then need to ++rewrite the function @code{ada-make-filename-from-adaname}. Doing that ++is beyond the scope of this manual; see the current definitions in ++@file{ada-mode.el} and @file{ada-xref.el} for examples. ++ ++@node Other compiler, Other customization, Non-standard file names, Customization ++@section Other compiler ++ ++By default, Ada mode is configured to use the Gnu Ada compiler GNAT. ++ ++To use a different Ada compiler, you must specify the command lines ++used to run that compiler, either in lisp variables or in Emacs ++Ada mode project files. See @ref{Project file variables} for the list ++of project variables, and the corresponding lisp variables. ++ ++@node Other customization, , Other compiler, Customization ++@section Other customization ++ ++All user-settable Ada mode variables can be set via the menu ++@samp{Ada | Customize}. Click on the @samp{Help} button there for help ++on using customize. ++ ++To modify a specific variable, you can directly call the function ++@code{customize-variable}; just type @kbd{M-x customize-variable ++@key{RET} @var{variable-name} @key{RET}}). ++ ++Alternately, you can specify variable settings in the Emacs ++configuration file, @file{.emacs}. This file is coded in Emacs lisp, ++and the syntax to set a variable is the following: ++@example ++(setq variable-name value) ++@end example ++ ++@node Compiling Executing, Project files, Customization, Top ++@chapter Compiling Executing ++ ++Ada projects can be compiled, linked, and executed using commands on ++the Ada menu. All of these commands can be customized via a project ++file (@pxref{Project files}), but the defaults are sufficient for using ++the GNAT compiler for simple projects (single files, or several files ++in a single directory). ++ ++Even when no project file is used, the GUI project editor (menu ++@samp{Ada | Project | Edit}) shows the settings of the various project ++file variables referenced here. ++ ++@menu ++* Compile commands:: ++* Compiler errors:: ++@end menu ++ ++@node Compile commands, Compiler errors, Compiling Executing, Compiling Executing ++@section Compile commands ++ ++Here are the commands for building and using an Ada project, as ++listed in the Ada menu. ++ ++In multi-file projects, there must be one file that is the main ++program. That is given by the @code{main} project file variable; ++it defaults to the current file if not yet set, but is also set by the ++``set main and build'' command. ++ ++@table @code ++ ++@item Check file ++Compiles the current file in syntax check mode, by running ++@code{check_cmd} defined in the current project file. This typically ++runs faster than full compile mode, speeding up finding and fixing ++compilation errors. ++ ++This sets @code{main} only if it has not been set yet. ++ ++@item Compile file ++Compiles the current file, by running @code{comp_cmd} from the current ++project file. ++ ++This does not set @code{main}. ++ ++@item Set main and Build ++Sets @code{main} to the current file, then executes the Build ++command. ++ ++@item Show main ++Display @code{main} in the message buffer. ++ ++@item Build ++Compiles all obsolete units of the current @code{main}, and links ++@code{main}, by running @code{make_cmd} from the current project. ++ ++This sets @code{main} only if it has not been set yet. ++ ++@item Run ++Executes the main program in a shell, displayed in a separate Emacs ++buffer. This runs @code{run_cmd} from the current project. The ++execution buffer allows for interactive input/output. ++ ++To modify the run command, in particular to provide or change the ++command line arguments, type @kbd{C-u} before invoking the command. ++ ++This command is not available for a cross-compilation toolchain. ++ ++@end table ++It is important when using these commands to understand how ++@code{main} is used and changed. ++ ++Build runs 'gnatmake' on the main unit. During a typical edit/compile ++session, this is the only command you need to invoke, which is why it ++is bound to @kbd{C-c C-c}. It will compile all files needed by the ++main unit, and display compilation errors in any of them. ++ ++Note that Build can be invoked from any Ada buffer; typically you will ++be fixing errors in files other than the main, but you don't have to ++switch back to the main to invoke the compiler again. ++ ++Novices and students typically work on single-file Ada projects. In ++this case, @kbd{C-c C-m} will normally be the only command needed; it ++will build the current file, rather than the last-built main. ++ ++There are three ways to change @code{main}: ++ ++@enumerate ++@item ++Invoke @samp{Ada | Set main and Build}, which sets @code{main} to ++the current file. ++ ++@item ++Invoke @samp{Ada | Project | Edit}, edit @code{main} and ++@code{main}, and click @samp{[save]} ++ ++@item ++Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} ++ ++@end enumerate ++ ++@node Compiler errors, , Compile commands, Compiling Executing ++@section Compiler errors ++ ++The @code{Check file}, @code{Compile file}, and @code{Build} commands ++all place compilation errors in a separate buffer named ++@code{*compilation*}. ++ ++Each line in this buffer will become active: you can simply click on ++it with the middle button of the mouse, or move point to it and press ++@key{RET}. Emacs will then display the relevant source file and put ++point on the line and column where the error was found. ++ ++You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs ++will jump to the first error. If you press that key again, it will ++move you to the second error, and so on. ++ ++Some error messages might also include references to other files. These ++references are also clickable in the same way, or put point after the ++line number and press @key{RET}. ++ ++@node Project files, Compiling Examples, Compiling Executing, Top ++@chapter Project files ++ ++An Emacs Ada mode project file specifies what directories hold sources ++for your project, and allows you to customize the compilation commands ++and other things on a per-project basis. ++ ++Note that Ada mode project files @samp{*.adp} are different than GNAT ++compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a ++GNAT project file to specify the project directories. If no ++other customization is needed, a GNAT project file can be used without ++an Emacs Ada mode project file. ++ ++@menu ++* Project File Overview:: ++* GUI Editor:: ++* Project file variables:: ++@end menu ++ ++@node Project File Overview, GUI Editor, Project files, Project files ++@section Project File Overview ++ ++Project files have a simple syntax; they may be edited directly. Each ++line specifies a project variable name and its value, separated by ``='': ++@example ++src_dir=/Projects/my_project/src_1 ++src_dir=/Projects/my_project/src_2 ++@end example ++ ++Some variables (like @code{src_dir}) are lists; multiple occurances ++are concatenated. ++ ++There must be no space between the variable name and ``='', and no ++trailing spaces. ++ ++Alternately, a GUI editor for project files is available (@pxref{GUI ++Editor}). It uses Emacs widgets, similar to Emacs customize. ++ ++The GUI editor also provides a convenient way to view current project ++settings, if they have been modified using menu commands rather than ++by editing the project file. ++ ++After the first Ada mode build command is invoked, there is always a ++current project file, given by the lisp variable ++@code{ada-prj-default-project-file}. Currently, the only way to show ++the current project file is to invoke the GUI editor. ++ ++To find the project file the first time, Ada mode uses the following ++search algorithm: ++ ++@itemize @bullet ++@item ++If @code{ada-prj-default-project-file} is set, use that. ++ ++@item ++Otherwise, search for a file in the current directory with ++the same base name as the Ada file, but extension given by ++@code{ada-prj-file-extension} (default @code{".adp"}). ++ ++@item ++If not found, search for @file{*.adp} in the current directory; if ++several are found, prompt the user to select one. ++ ++@item ++If none are found, use @file{default.adp} in the current directory (even ++if it does not exist). ++ ++@end itemize ++ ++This algorithm always sets @code{ada-prj-default-project-file}, even ++when the file does not actually exist. ++ ++To change the project file before or after the first one is found, ++invoke @samp{Ada | Project | Load ...}. ++ ++Or, in lisp, evaluate @code{(ada-set-default-project-file "/path/file.adp")}. ++This sets @code{ada-prj-default-project-file}, and reads the project file. ++ ++You can also specify a GNAT project file to @samp{Ada | Project | Load ++...} or @code{ada-set-default-project-file}. Emacs Ada mode checks the ++file extension; if it is @code{.gpr}, the file is treated as a GNAT ++project file. Any other extension is treated as an Emacs Ada mode ++project file. ++ ++@node GUI Editor, Project file variables, Project File Overview, Project files ++@section GUI Editor ++ ++The project file editor is invoked with the menu @samp{Ada | Projects ++| Edit}. ++ ++Once in the buffer for editing the project file, you can save your ++modification using the @samp{[save]} button at the bottom of the ++buffer, or the @kbd{C-x C-s} binding. To cancel your modifications, ++kill the buffer or click on the @samp{[cancel]} button. ++ ++@node Project file variables, , GUI Editor, Project files ++@section Project file variables ++ ++The following variables can be defined in a project file; some can ++also be defined in lisp variables. ++ ++To set a project variable that is a list, specify each element of the ++list on a separate line in the project file. ++ ++Any project variable can be referenced in other project variables, ++using a shell-like notation. For instance, if the variable ++@code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the ++@code{comp_opt} variable will be substituted when @code{comp_cmd} is ++used. ++ ++In addition, process environment variables can be referenced using the ++same syntax, or the normal @code{$var} syntax. ++ ++Most project variables have defaults that can be changed by setting ++lisp variables; the table below identifies the lisp variable for each ++project variable. Lisp variables corresponding to project variables ++that are lists are lisp lists. ++ ++In general, project variables are evaluated when referenced in ++Emacs Ada mode commands. Relative file paths are expanded to ++absolute relative to @code{$@{build_dir@}}. ++ ++Here is the list of variables. In the default values, the current ++directory @code{"."} is the project file directory. ++ ++@table @asis ++@c defined in ada-default-prj-properties; alphabetical order ++ ++@item @code{ada_project_path_sep} [default: @code{":" or ";"}] ++Path separator for @code{ADA_PROJECT_PATH}. It defaults to the correct ++value for a native implementation of GNAT for the current operating ++system. The user must override this when using Windows native GNAT ++with Cygwin Emacs, and perhaps in other cases. ++ ++Lisp variable: @code{ada-prj-ada-project-path-sep}. ++ ++@item @code{ada_project_path} [default: @code{""}] ++A list of directories to search for GNAT project files. ++ ++If set, the @code{ADA_PROJECT_PATH} process environment variable is ++set to this value in the Emacs process when the Emacs Ada mode project ++is selected via menu @samp{Ada | Project | Load}. ++ ++For @code{ada_project_path}, relative file paths are expanded to ++absolute when the Emacs Ada project file is read, rather than when the ++project file is selected. ++ ++For example if the project file is in the directory ++@file{/home/myproject}, the environment variable @code{GDS_ROOT} is ++set to @code{/home/shared}, and the project file contains: ++@example ++ada_project_path_sep=: ++ada_project_path=$GDS_ROOT/makerules ++ada_project_path=../opentoken ++@end example ++the environment variable @code{ADA_PROJECT_PATH} will be set to ++@code{"/home/shared/makerules:/home/opentoken/"}. ++ ++The default value is not the current value of this environment ++variable, because that will typically have been set by another ++project, and will therefore be incorrect for this project. ++ ++If you have the environment variable set correctly for all of your ++projects, you do not need to set this project variable. ++ ++@item @code{bind_opt} [default: @code{""}] ++Holds user binder options; used in the default build commands. ++ ++Lisp variable: @code{ada-prj-default-bind-opt}. ++ ++@item @code{build_dir} [default: @code{"."}] ++The compile commands will be issued in this directory. ++ ++@item @code{casing} [default: @code{("~/.emacs_case_exceptions")} ++List of files containing casing exceptions. See the help on ++@code{ada-case-exception-file} for more info. ++@c FIXME: section on case exceptions ++ ++Lisp variable: @code{ada-case-exception-file}. ++ ++@item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] ++Command used to syntax check a single file. ++The name of the file is substituted for @code{full_current}. ++ ++Lisp variable: @code{ada-prj-default-check-cmd} ++ ++@item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] ++Command used to compile a single file. ++The name of the file is substituted for @code{full_current}. ++ ++Lisp variable: @code{ada-prj-default-comp-cmd}. ++ ++@item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}] ++Holds user compiler options; used in the default compile commands. The ++default value tells gnatmake to generate library files for ++cross-referencing even when there are errors. ++ ++If source code for the project is in multiple directories, the ++appropriate compiler options must be added here. @ref{Set source ++search path} for examples of this. Alternately, GNAT project files may ++be used; @ref{Use GNAT project file}. ++ ++Lisp variable: @code{ada-prj-default-comp-opt}. ++ ++@item @code{cross_prefix} [default: @code{""}] ++Name of target machine in a cross-compilation environment. Used in ++default compile and build commands. ++ ++@item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}] ++Command used to debug the application ++ ++Lisp variable: @code{ada-prj-default-debugger}. ++ ++@item @code{debug_post_cmd} [default: @code{""}] ++Command executed after @code{debug_cmd}. ++ ++@item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}] ++Command executed before @code{debug_cmd}. ++ ++@item @code{gnatfind_opt} [default: @code{"-rf"}] ++Holds user gnatfind options; used in the default find commands. ++ ++Lisp variable: @code{ada-prj-gnatfind-switches}. ++ ++@item @code{gnatmake_opt} [default: @code{"-g"}] ++Holds user gnatmake options; used in the default build commands. ++ ++Lisp variable: @code{ada-prj-default-gnatmake-opt}. ++ ++@item @code{gpr_file} [default: @code{""}] ++Specify GNAT project file. ++ ++If set, the source and object directories specified in the GNAT ++project file are appended to @code{src_dir} and @code{obj_dir}. This ++allows specifying Ada source directories with a GNAT project file, and ++other source directories with the Emacs project file. ++ ++In addition, @code{-P@{gpr_file@}} is added to the project variable ++@code{gnatmake_opt} whenever it is referenced. With the default ++project variables, this passes the project file to all gnatmake ++commands. ++ ++Lisp variable: @code{ada-prj-default-gpr-file}. ++ ++@c FIXME: add gnatstub-opts ++ ++@item @code{link_opt} [default: @code{""}] ++Holds user linker options; used in the default build commands. ++ ++Lisp variable: @code{ada-prj-default-link-opt}. ++ ++@item @code{main} [default: current file] ++Specifies the name of the executable file for the project; used in the ++default build commands. ++ ++@item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}] ++Command used to build the application. ++ ++Lisp variable: @code{ada-prj-default-make-cmd}. ++ ++@item @code{obj_dir} [default: @code{"."}] ++A list of directories to search for library files. Ada mode searches ++this list for the @samp{.ali} files generated by GNAT that contain ++cross-reference information. ++ ++The compiler commands must place the @samp{.ali} files in one of these ++directories; the default commands do that. ++ ++@item @code{remote_machine} [default: @code{""}] ++Name of the machine to log into before issuing the compile and build ++commands. If this variable is empty, the command will be run on the ++local machine. ++ ++@item @code{run_cmd} [default: @code{"./$@{main@}"}] ++Command used to run the application. ++ ++@item @code{src_dir} [default: @code{"."}] ++A list of directories to search for source files, both for compile ++commands and source navigation. ++ ++@end table ++ ++@node Compiling Examples, Moving Through Ada Code, Project files, Top ++@chapter Compiling Examples ++ ++We present several small projects, and walk thru the process of ++compiling, linking, and running them. ++ ++The first example illustrates more Ada mode features than the others; ++you should work thru that example before doing the others. ++ ++All of these examples assume you are using GNAT. ++ ++The source for these examples is available on the Emacs Ada mode ++website mentioned in @xref{Installation}. ++ ++@menu ++* No project files:: Just menus ++* Set compiler options:: A basic Ada mode project file ++* Set source search path:: Source in multiple directories ++* Use GNAT project file:: ++* Use multiple GNAT project files:: ++@end menu ++ ++@node No project files, Set compiler options, Compiling Examples, Compiling Examples ++@section No project files ++This example uses no project files. ++ ++First, create a directory @file{Example_1}, containing: ++ ++@file{hello.adb}: ++ ++@example ++with Ada.Text_IO; ++procedure Hello ++is begin ++ Put_Line("Hello from hello.adb"); ++end Hello; ++@end example ++ ++Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate ++compiler error handling. ++ ++@file{hello_2.adb}: ++ ++@example ++with Hello_Pkg; ++procedure Hello_2 ++is begin ++ Hello_Pkg.Say_Hello; ++end Hello_2; ++@end example ++ ++This file has no errors. ++ ++@file{hello_pkg.ads}: ++ ++@example ++package Hello_Pkg is ++ procedure Say_Hello; ++end Hello_Pkg; ++@end example ++ ++This file has no errors. ++ ++@file{hello_pkg.adb}: ++ ++@example ++with Ada.Text_IO; ++package Hello_Pkg is ++ procedure Say_Hello ++ is begin ++ Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); ++ end Say_Hello; ++end Hello_Pkg; ++@end example ++ ++Yes, this is missing the keyword @code{body}; another compiler error ++example. ++ ++In buffer @file{hello.adb}, invoke @samp{Ada | Check file}. You should ++get a @code{*compilation*} buffer containing something like (the ++directory paths will be different): ++ ++@example ++cd c:/Examples/Example_1/ ++gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ ++gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb ++hello.adb:4:04: "Put_Line" is not visible ++hello.adb:4:04: non-visible declaration at a-textio.ads:264 ++hello.adb:4:04: non-visible declaration at a-textio.ads:260 ++gnatmake: "c:/Examples/Example_1/hello.adb" compilation error ++@end example ++ ++If you have enabled font-lock, the lines with actual errors (starting ++with @file{hello.adb}) are highlighted, with the file name in red. ++ ++Now type @kbd{C-x `} (on a PC keyboard, @key{`} is next to @key{1}). ++Or you can click the middle mouse button on the first error line. The ++compilation buffer scrolls to put the first error on the top line, and ++point is put at the place of the error in the @file{hello.adb} buffer. ++ ++To fix the error, change the line to be ++ ++@example ++ Ada.Text_IO.Put_Line ("hello from hello.adb"); ++@end example ++ ++Now invoke @samp{Ada | Show main}; this displays @samp{Ada mode main: hello}. ++ ++Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build}. You are ++prompted to save the file (if you haven't already). Then the ++compilation buffer is displayed again, containing: ++ ++@example ++cd c:/Examples/Example_1/ ++gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs ++gcc -c -g -gnatq -gnatQ hello.adb ++gnatbind -x hello.ali ++gnatlink hello.ali -o hello.exe -g ++@end example ++ ++The compilation has succeeded without errors; @file{hello.exe} now ++exists in the same directory as @file{hello.adb}. ++ ++Now invoke @samp{Ada | Run}. A @file{*run*} buffer is displayed, ++containing ++ ++@example ++Hello from hello.adb ++ ++Process run finished ++@end example ++ ++That completes the first part of this example. ++ ++Now we will compile a multi-file project. Open the file ++@file{hello_2.adb}, and invoke @samp{Ada | Set main and Build}. This ++finds an error in @file{hello_pkg.adb}: ++ ++@example ++cd c:/Examples/Example_1/ ++gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs ++gcc -c -g -gnatq -gnatQ hello_pkg.adb ++hello_pkg.adb:2:08: keyword "body" expected here [see file name] ++gnatmake: "hello_pkg.adb" compilation error ++@end example ++ ++This demonstrates that gnatmake finds the files needed by the main ++program. However, it cannot find files in a different directory, ++unless you use an Emacs Ada mode project file to specify the other directories; ++@xref{Set source search path}, or a GNAT project file; @ref{Use GNAT ++project file}. ++ ++Invoke @samp{Ada | Show main}; this displays @file{Ada mode main: hello_2}. ++ ++Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}: ++ ++@example ++package body Hello_Pkg is ++@end example ++ ++Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build}. ++gnatmake successfully builds @file{hello_2}. This demonstrates that ++Emacs has remembered the main file, in the project variable ++@code{main}, and used it for the Build command. ++ ++Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Run}. ++The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}. ++ ++One final point. If you switch back to buffer @file{hello.adb}, and ++invoke @samp{Ada | Run}, @file{hello_2.exe} will be run. That is ++because @code{main} is still set to @code{hello_2}, as you can ++see when you invoke @samp{Ada | Project | Edit}. ++ ++There are three ways to change @code{main}: ++ ++@enumerate ++@item ++Invoke @samp{Ada | Set main and Build}, which sets @code{main} to ++the current file. ++ ++@item ++Invoke @samp{Ada | Project | Edit}, edit @code{main}, and click @samp{[save]} ++ ++@item ++Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} ++ ++@end enumerate ++ ++@node Set compiler options, Set source search path, No project files, Compiling Examples ++@section Set compiler options ++ ++This example illustrates using an Emacs Ada mode project file to set a ++compiler option. ++ ++If you have files from @file{Example_1} open in Emacs, you should ++close them so you don't get confused. Use menu @samp{File | Close ++(current buffer)}. ++ ++In directory @file{Example_2}, create these files: ++ ++@file{hello.adb}: ++ ++@example ++with Ada.Text_IO; ++procedure Hello ++is begin ++ Put_Line("Hello from hello.adb"); ++end Hello; ++@end example ++ ++This is the same as @file{hello.adb} from @file{Example_1}. It has two ++errors; missing ``use Ada.Text_IO;'', and no space between ++@code{Put_Line} and its argument list. ++ ++@file{hello.adp}: ++ ++@example ++comp_opt=-gnatyt ++@end example ++ ++This tells the GNAT compiler to check for token spacing; in ++particular, there must be a space preceding a parenthesis. ++ ++In buffer @file{hello.adb}, invoke @samp{Ada | Project | Load...}, and ++select @file{Example_2/hello.adp}. ++ ++Then, again in buffer @file{hello.adb}, invoke @samp{Ada | Set main and ++Build}. You should get a @code{*compilation*} buffer containing ++something like (the directory paths will be different): ++ ++@example ++cd c:/Examples/Example_2/ ++gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs ++gcc -c -g -gnatyt hello.adb ++hello.adb:4:04: "Put_Line" is not visible ++hello.adb:4:04: non-visible declaration at a-textio.ads:264 ++hello.adb:4:04: non-visible declaration at a-textio.ads:260 ++hello.adb:4:12: (style) space required ++gnatmake: "hello.adb" compilation error ++@end example ++ ++Compare this to the compiler output in @ref{No project files}; the ++gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by ++@code{-cargs -gnaty}, and an additional error is reported in ++@file{hello.adb} on line 4. This shows that @file{hello.adp} is being ++used to set the compiler options. ++ ++Fixing the error, linking and running the code proceed as in @ref{No ++project files}. ++ ++@node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples ++@section Set source search path ++ ++In this example, we show how to deal with files in more than one ++directory. We start with the same code as in @ref{No project files}; ++create those files (with the errors present) ++ ++Create the directory @file{Example_3}, containing: ++ ++@file{hello_pkg.ads}: ++ ++@example ++package Hello_Pkg is ++ procedure Say_Hello; ++end Hello_Pkg; ++@end example ++ ++@file{hello_pkg.adb}: ++ ++@example ++with Ada.Text_IO; ++package Hello_Pkg is ++ procedure Say_Hello ++ is begin ++ Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); ++ end Say_Hello; ++end Hello_Pkg; ++@end example ++ ++These are the same files from example 1; @file{hello_pkg.adb} has an ++error on line 2. ++ ++In addition, create a directory @file{Example_3/Other}, containing these files: ++ ++@file{Other/hello_3.adb}: ++ ++@example ++with Hello_Pkg; ++with Ada.Text_IO; use Ada.Text_IO; ++procedure Hello_3 ++is begin ++ Hello_Pkg.Say_Hello; ++ Put_Line ("From hello_3"); ++end Hello_3; ++@end example ++ ++There are no errors in this file. ++ ++@file{Other/other.adp}: ++ ++@example ++src_dir=.. ++comp_opt=-I.. ++@end example ++ ++Note that there must be no trailing spaces. ++ ++In buffer @file{hello_3.adb}, invoke @samp{Ada | Project | Load...}, and ++select @file{Example_3/Other/other.adp}. ++ ++Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and ++Build}. You should get a @code{*compilation*} buffer containing ++something like (the directory paths will be different): ++ ++@example ++cd c:/Examples/Example_3/Other/ ++gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs ++gcc -c -g -I.. hello_3.adb ++gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb ++hello_pkg.adb:2:08: keyword "body" expected here [see file name] ++gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error ++@end example ++ ++Compare the @code{-cargs} option to the compiler output in @ref{Set ++compiler options}; this shows that @file{other.adp} is being used to ++set the compiler options. ++ ++Move to the error with @kbd{C-x `}. Ada mode searches the list of ++directories given by @code{src_dir} for the file mentioned in the ++compiler error message. ++ ++Fixing the error, linking and running the code proceed as in @ref{No ++project files}. ++ ++@node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples ++@section Use GNAT project file ++ ++In this example, we show how to use a GNAT project file, with no Ada ++mode project file. ++ ++Create the directory @file{Example_4}, containing: ++ ++@file{hello_pkg.ads}: ++ ++@example ++package Hello_Pkg is ++ procedure Say_Hello; ++end Hello_Pkg; ++@end example ++ ++@file{hello_pkg.adb}: ++ ++@example ++with Ada.Text_IO; ++package Hello_Pkg is ++ procedure Say_Hello ++ is begin ++ Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); ++ end Say_Hello; ++end Hello_Pkg; ++@end example ++ ++These are the same files from example 1; @file{hello_pkg.adb} has an ++error on line 2. ++ ++In addition, create a directory @file{Example_4/Gnat_Project}, ++containing these files: ++ ++@file{Gnat_Project/hello_4.adb}: ++ ++@example ++with Hello_Pkg; ++with Ada.Text_IO; use Ada.Text_IO; ++procedure Hello_4 ++is begin ++ Hello_Pkg.Say_Hello; ++ Put_Line ("From hello_4"); ++end Hello_4; ++@end example ++ ++There are no errors in this file. ++ ++@file{Gnat_Project/hello_4.gpr}: ++ ++@example ++Project Hello_4 is ++ for Source_Dirs use (".", ".."); ++end Hello_4; ++@end example ++ ++In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and ++select @file{Example_4/Gnat_Project/hello_4.gpr}. ++ ++Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and ++Build}. You should get a @code{*compilation*} buffer containing ++something like (the directory paths will be different): ++ ++@example ++cd c:/Examples/Example_4/Gnat_Project/ ++gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs ++gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb ++gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb ++hello_pkg.adb:2:08: keyword "body" expected here [see file name] ++gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error ++@end example ++ ++Compare the @code{gcc} options to the compiler output in @ref{Set ++compiler options}; this shows that @file{hello_4.gpr} is being used to ++set the compiler options. ++ ++Fixing the error, linking and running the code proceed as in @ref{No ++project files}. ++ ++@node Use multiple GNAT project files, , Use GNAT project file, Compiling Examples ++@section Use multiple GNAT project files ++ ++In this example, we show how to use multiple GNAT project files, ++specifying the GNAT project search path in an Ada mode project file. ++ ++Create the directory @file{Example_4} as specified in @ref{Use GNAT ++project file}. ++ ++Create the directory @file{Example_5}, containing: ++ ++@file{hello_5.adb}: ++ ++@example ++with Hello_Pkg; ++with Ada.Text_IO; use Ada.Text_IO; ++procedure Hello_5 ++is begin ++ Hello_Pkg.Say_Hello; ++ Put_Line ("From hello_5"); ++end Hello_5; ++@end example ++ ++There are no errors in this file. ++ ++@file{hello_5.adp}: ++ ++@example ++ada_project_path=../Example_4/Gnat_Project ++gpr_file=hello_5.gpr ++@end example ++ ++@file{hello_5.gpr}: ++ ++@example ++with "hello_4"; ++Project Hello_5 is ++ for Source_Dirs use ("."); ++ package Compiler is ++ for Default_Switches ("Ada") use ("-g", "-gnatyt"); ++ end Compiler; ++end Hello_5; ++@end example ++ ++In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Load...}, and ++select @file{Example_5/hello_5.adp}. ++ ++Then, again in @file{hello_5.adb}, invoke @samp{Ada | Set main and ++Build}. You should get a @code{*compilation*} buffer containing ++something like (the directory paths will be different): ++ ++@example ++cd c:/Examples/Example_5/ ++gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs -largs ++gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb ++gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb ++hello_pkg.adb:2:08: keyword "body" expected here [see file name] ++gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error ++@end example ++ ++Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown, ++demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being ++used to set the compilation search path. ++ ++@node Moving Through Ada Code, Identifier completion, Compiling Examples, Top ++@chapter Moving Through Ada Code ++ ++There are several easy to use commands to navigate through Ada code. All ++these functions are available through the Ada menu, and you can also ++use the following key bindings or the command names. Some of these ++menu entries are available only if the GNAT compiler is used, since ++the implementation relies on the GNAT cross-referencing information. ++ ++@table @kbd ++@item M-C-e ++@findex ada-next-procedure ++Move to the next function/procedure/task, which ever comes next ++(@code{ada-next-procedure}). ++@item M-C-a ++@findex ada-previous-procedure ++Move to previous function/procedure/task ++(@code{ada-previous-procedure}). ++@item M-x ada-next-package ++@findex ada-next-package ++Move to next package. ++@item M-x ada-previous-package ++@findex ada-previous-package ++Move to previous package. ++@item C-c C-a ++@findex ada-move-to-start ++Move to matching start of @code{end} (@code{ada-move-to-start}). If ++point is at the end of a subprogram, this command jumps to the ++corresponding @code{begin} if the user option ++@code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to ++the subprogram declaration. ++@item C-c C-e ++@findex ada-move-to-end ++Move point to end of current block (@code{ada-move-to-end}). ++@item C-c o ++Switch between corresponding spec and body file ++(@code{ff-find-other-file}). If point is in a subprogram, position ++point on the corresponding declaration or body in the other file. ++@item C-c c-d ++@findex ada-goto-declaration ++Move from any reference to its declaration, for from a declaration to ++its body (for procedures, tasks, private and incomplete types). ++@item C-c C-r ++@findex ada-find-references ++Runs the @file{gnatfind} command to search for all references to the ++identifier surrounding point (@code{ada-find-references}). Use ++@kbd{C-x `} (@code{next-error}) to visit each reference (as for ++compilation errors). ++@end table ++ ++If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs ++will try to run GNAT for you whenever cross-reference information is ++needed, and is older than the current source file. ++ ++@node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top ++@chapter Identifier completion ++ ++Emacs and Ada mode provide two general ways for the completion of ++identifiers. This is an easy way to type faster: you just have to type ++the first few letters of an identifiers, and then loop through all the ++possible completions. ++ ++The first method is general for Emacs. It works by parsing all open ++files for possible completions. ++ ++For instance, if the words @samp{my_identifier}, @samp{my_subprogram} ++are the only words starting with @samp{my} in any of the opened files, ++then you will have this scenario: ++ ++@example ++You type: my@kbd{M-/} ++Emacs inserts: @samp{my_identifier} ++If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with ++@samp{my_subprogram}. ++Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}. ++@end example ++ ++This is a very fast way to do completion, and the casing of words will ++also be respected. ++ ++The second method (@kbd{C-@key{TAB}}) is specific to Ada mode and the GNAT ++compiler. Emacs will search the cross-information for possible ++completions. ++ ++The main advantage is that this completion is more accurate: only ++existing identifier will be suggested. ++ ++On the other hand, this completion is a little bit slower and requires ++that you have compiled your file at least once since you created that ++identifier. ++ ++@table @kbd ++@item C-@key{TAB} ++@findex ada-complete-identifier ++Complete current identifier using cross-reference information. ++@item M-/ ++Complete identifier using buffer information (not Ada-specific). ++@end table ++ ++@node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top ++@chapter Automatic Smart Indentation ++ ++Ada mode comes with a full set of rules for automatic indentation. You ++can also configure the indentation, via the following variables: ++ ++@table @asis ++@item @code{ada-broken-indent} (default value: 2) ++Number of columns to indent the continuation of a broken line. ++ ++@item @code{ada-indent} (default value: 3) ++Number of columns for default indentation. ++ ++@item @code{ada-indent-record-rel-type} (default value: 3) ++Indentation for @code{record} relative to @code{type} or @code{use}. ++ ++@item @code{ada-indent-return} (default value: 0) ++Indentation for @code{return} relative to @code{function} (if ++@code{ada-indent-return} is greater than 0), or the open parenthesis ++(if @code{ada-indent-return} is negative or 0). Note that in the second ++case, when there is no open parenthesis, the indentation is done ++relative to @code{function} with the value of @code{ada-broken-indent}. ++ ++@item @code{ada-label-indent} (default value: -4) ++Number of columns to indent a label. ++ ++@item @code{ada-stmt-end-indent} (default value: 0) ++Number of columns to indent a statement @code{end} keyword on a separate line. ++ ++@item @code{ada-when-indent} (default value: 3) ++Indentation for @code{when} relative to @code{exception} or @code{case}. ++ ++@item @code{ada-indent-is-separate} (default value: t) ++Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line. ++ ++@item @code{ada-indent-to-open-paren} (default value: t) ++Non-@code{nil} means indent according to the innermost open parenthesis. ++ ++@item @code{ada-indent-after-return} (default value: t) ++Non-@code{nil} means that the current line will also be re-indented ++before inserting a newline, when you press @key{RET}. ++@end table ++ ++Most of the time, the indentation will be automatic, i.e when you ++press @key{RET}, the cursor will move to the correct column on the ++next line. ++ ++You can also indent single lines, or the current region, with @key{TAB}. ++ ++Another mode of indentation exists that helps you to set up your ++indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do ++the following: ++ ++@itemize @bullet ++@item ++Reindent the current line, as @key{TAB} would do. ++@item ++Temporarily move the cursor to a reference line, i.e., the line that ++was used to calculate the current indentation. ++@item ++Display in the message window the name of the variable that provided ++the offset for the indentation. ++@end itemize ++ ++The exact indentation of the current line is the same as the one for the ++reference line, plus an offset given by the variable. ++ ++@table @kbd ++@item @key{TAB} ++Indent the current line or the current region. ++@item C-M-\ ++Indent lines in the current region. ++@item C-c @key{TAB} ++Indent the current line and display the name of the variable used for ++indentation. ++@end table ++ ++@node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top ++@chapter Formatting Parameter Lists ++ ++@table @kbd ++@item C-c C-f ++@findex ada-format-paramlist ++Format the parameter list (@code{ada-format-paramlist}). ++@end table ++ ++This aligns the declarations on the colon (@samp{:}) separating ++argument names and argument types, and aligns the @code{in}, ++@code{out} and @code{in out} keywords. ++ ++@node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top ++@chapter Automatic Casing ++ ++Casing of identifiers, attributes and keywords is automatically ++performed while typing when the variable @code{ada-auto-case} is set. ++Every time you press a word separator, the previous word is ++automatically cased. ++ ++You can customize the automatic casing differently for keywords, ++attributes and identifiers. The relevant variables are the following: ++@code{ada-case-keyword}, @code{ada-case-attribute} and ++@code{ada-case-identifier}. ++ ++All these variables can have one of the following values: ++ ++@table @code ++@item downcase-word ++The word will be lowercase. For instance @code{My_vARIable} is ++converted to @code{my_variable}. ++ ++@item upcase-word ++The word will be uppercase. For instance @code{My_vARIable} is ++converted to @code{MY_VARIABLE}. ++ ++@item ada-capitalize-word ++The first letter and each letter following an underscore (@samp{_}) ++are uppercase, others are lowercase. For instance @code{My_vARIable} ++is converted to @code{My_Variable}. ++ ++@item ada-loose-case-word ++Characters after an underscore @samp{_} character are uppercase, ++others are not modified. For instance @code{My_vARIable} is converted ++to @code{My_VARIable}. ++@end table ++ ++Ada mode allows you to define exceptions to these rules, in a file ++specified by the variable @code{ada-case-exception-file} ++(default @file{~/.emacs_case_exceptions}). Each line in this file ++specifies the casing of one word or word fragment. Comments may be ++included, separated from the word by a space. ++ ++If the word starts with an asterisk (@key{*}), it defines the casing ++af a word fragemnt (or ``substring''); part of a word between two ++underscores or word boundary. ++ ++For example: ++ ++@example ++DOD Department of Defense ++*IO ++GNAT The GNAT compiler from Ada Core Technologies ++@end example ++ ++The word fragment @code{*IO} applies to any word containing ``_io''; ++@code{Text_IO}, @code{Hardware_IO}, etc. ++ ++@findex ada-create-case-exception ++There are two ways to add new items to this file: you can simply edit ++it as you would edit any text file. Or you can position point on the ++word you want to add, and select menu @samp{Ada | Edit | Create Case ++Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}). ++The word will automatically be added to the current list of exceptions ++and to the file. ++ ++To define a word fragment case exception, select the word fragment, ++then select menu @samp{Ada | Edit | Create Case Exception Substring}. ++ ++It is sometimes useful to have multiple exception files around (for ++instance, one could be the standard Ada acronyms, the second some ++company specific exceptions, and the last one some project specific ++exceptions). If you set up the variable @code{ada-case-exception-file} ++as a list of files, each of them will be parsed and used in your emacs ++session. However, when you save a new exception through the menu, as ++described above, the new exception will be added to the first file in ++the list. ++ ++@table @kbd ++@item C-c C-b ++@findex ada-adjust-case-buffer ++Adjust case in the whole buffer (@code{ada-adjust-case-buffer}). ++@item C-c C-y ++Create a new entry in the exception dictionary, with the word under ++the cursor (@code{ada-create-case-exception}) ++@item C-c C-t ++@findex ada-case-read-exceptions ++Rereads the exception dictionary from the file ++@code{ada-case-exception-file} (@code{ada-case-read-exceptions}). ++@end table ++ ++@node Statement Templates, Comment Handling, Automatic Casing, Top ++@chapter Statement Templates ++ ++Templates are defined for most Ada statements, using the Emacs ++``skeleton'' package. They can be inserted in the buffer using the ++following commands: ++ ++@table @kbd ++@item C-c t b ++@findex ada-exception-block ++exception Block (@code{ada-exception-block}). ++@item C-c t c ++@findex ada-case ++case (@code{ada-case}). ++@item C-c t d ++@findex ada-declare-block ++declare Block (@code{ada-declare-block}). ++@item C-c t e ++@findex ada-else ++else (@code{ada-else}). ++@item C-c t f ++@findex ada-for-loop ++for Loop (@code{ada-for-loop}). ++@item C-c t h ++@findex ada-header ++Header (@code{ada-header}). ++@item C-c t i ++@findex ada-if ++if (@code{ada-if}). ++@item C-c t k ++@findex ada-package-body ++package Body (@code{ada-package-body}). ++@item C-c t l ++@findex ada-loop ++loop (@code{ada-loop}). ++@item C-c p ++@findex ada-subprogram-body ++subprogram body (@code{ada-subprogram-body}). ++@item C-c t t ++@findex ada-task-body ++task Body (@code{ada-task-body}). ++@item C-c t w ++@findex ada-while ++while Loop (@code{ada-while}). ++@item C-c t u ++@findex ada-use ++use (@code{ada-use}). ++@item C-c t x ++@findex ada-exit ++exit (@code{ada-exit}). ++@item C-c t C-a ++@findex ada-array ++array (@code{ada-array}). ++@item C-c t C-e ++@findex ada-elsif ++elsif (@code{ada-elsif}). ++@item C-c t C-f ++@findex ada-function-spec ++function Spec (@code{ada-function-spec}). ++@item C-c t C-k ++@findex ada-package-spec ++package Spec (@code{ada-package-spec}). ++@item C-c t C-p ++@findex ada-procedure-spec ++procedure Spec (@code{ada-package-spec}. ++@item C-c t C-r ++@findex ada-record ++record (@code{ada-record}). ++@item C-c t C-s ++@findex ada-subtype ++subtype (@code{ada-subtype}). ++@item C-c t C-t ++@findex ada-task-spec ++task Spec (@code{ada-task-spec}). ++@item C-c t C-u ++@findex ada-with ++with (@code{ada-with}). ++@item C-c t C-v ++@findex ada-private ++private (@code{ada-private}). ++@item C-c t C-w ++@findex ada-when ++when (@code{ada-when}). ++@item C-c t C-x ++@findex ada-exception ++exception (@code{ada-exception}). ++@item C-c t C-y ++@findex ada-type ++type (@code{ada-type}). ++@end table ++ ++@node Comment Handling, GNU Free Documentation License, Statement Templates, Top ++@chapter Comment Handling ++ ++By default, comment lines get indented like Ada code. There are a few ++additional functions to handle comments: ++ ++@table @kbd ++@item M-; ++Start a comment in default column. ++@item M-j ++Continue comment on next line. ++@item C-c ; ++Comment the selected region (add -- at the beginning of lines). ++@item C-c : ++Uncomment the selected region ++@item M-q ++autofill the current comment. ++@end table ++ ++@node GNU Free Documentation License, Index, Comment Handling, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index, , GNU Free Documentation License, Top ++@unnumbered Index ++ ++@printindex fn ++ ++@bye ++ ++@ignore ++ arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e ++@end ignore +diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi +new file mode 100644 +index 0000000..e4eaedb +--- /dev/null ++++ b/doc/misc/auth.texi +@@ -0,0 +1,197 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/auth ++@settitle Emacs auth-source Library @value{VERSION} ++ ++@set VERSION 0.1 ++ ++@copying ++This file describes the Emacs auth-source library. ++ ++Copyright @copyright{} 2008, 2009 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 Emacs 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.'' ++ ++This document is part of a collection distributed under the GNU Free ++Documentation License. If you want to distribute this document ++separately from the collection, you can do so by adding a copy of the ++license to the document, as described in section 6 of the license. ++@end quotation ++@end copying ++ ++@dircategory Emacs ++@direntry ++* Auth-source: (auth). The Emacs auth-source library. ++@end direntry ++ ++@titlepage ++@title Emacs auth-source Library ++@author by Ted Zlatanov ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top ++@top Emacs auth-source ++This manual describes the Emacs auth-source library. ++ ++It is a way for multiple applications to share a single configuration ++(in Emacs and in files) for user convenience. ++ ++@insertcopying ++ ++@menu ++* Overview:: Overview of the auth-source library. ++* Help for users:: ++* Help for developers:: ++* Index:: ++* Function Index:: ++* Variable Index:: ++@end menu ++@end ifnottex ++ ++@node Overview ++@chapter Overview ++ ++To be done. ++ ++@node Help for users ++@chapter Help for users ++ ++If you have problems with the port, turn up @code{gnus-verbose} and ++see what port the library is checking. Ditto for any other ++problems, your first step is to see what's being checked. ++ ++Setup: ++ ++@lisp ++(require 'auth-source) ++(customize-variable 'auth-sources) ;; optional, do it once ++@end lisp ++ ++@defvar auth-sources ++ ++The @var{auth-sources} variable tells the auth-source library where ++your netrc files live for a particular host and protocol. While you ++can get fancy, the default and simplest configuration is: ++ ++@lisp ++(setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) ++@end lisp ++ ++By adding multiple entries to that list with a particular host or ++protocol, you can have specific netrc files for that host or protocol. ++ ++@end defvar ++ ++ ++``Netrc'' files are a de facto standard. They look like this: ++@example ++machine mymachine login myloginname password mypassword port myport ++@end example ++ ++The port is optional. If it's missing, auth-source will assume any ++port is OK. Actually the port is a protocol name or a port number so ++you can have separate entries for port 143 and for protocol ``imap'' ++if you fancy that. ++ ++If you don't customize @var{auth-sources}, you'll have to live with ++the defaults: any host and any port are looked up in the netrc ++file @code{~/.authinfo.gpg}. This is an encrypted file if and only if ++you set up EPA, which is strongly recommended. ++ ++@lisp ++(require 'epa-file) ++(epa-file-enable) ++(setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important ++@end lisp ++ ++For url-auth authentication (HTTP/HTTPS), you need to put this in your ++netrc file: ++ ++@example ++machine yourmachine.com:80 port http login testuser password testpass ++@end example ++ ++This will match any realm and authentication method (basic or ++digest). If you want finer controls, explore the url-auth source ++code and variables. ++ ++For Tramp authentication, use: ++ ++@example ++machine yourmachine.com port scp login testuser password testpass ++@end example ++ ++Note that the port denotes the Tramp connection method. When you ++don't use a port entry, you match any Tramp method, as explained ++earlier. ++ ++@node Help for developers ++@chapter Help for developers ++ ++The auth-source library only has one function for external use. ++ ++@defun auth-source-user-or-password mode host port ++ ++Retrieve appropriate authentication tokens, determined by @var{mode}, ++for host @var{host} and @var{port}. If @code{gnus-verbose} is 9 or ++higher, debugging messages will be printed. ++ ++If @var{mode} is a list of strings, the function will return a list of ++strings or @code{nil} objects. If it's a string, the function will ++return a string or a @code{nil} object. Currently only the modes ++``login'' and ``password'' are recognized but more may be added in the ++future. ++ ++@var{host} is a string containing the host name. ++ ++@var{port} contains the protocol name (e.g. ``imap'') or ++a port number. It must be a string, corresponding to the port in the ++users' netrc files. ++ ++@example ++;; IMAP example ++(setq auth (auth-source-user-or-password ++ '("login" "password") ++ "anyhostnamehere" ++ "imap")) ++(nth 0 auth) ; the login name ++(nth 1 auth) ; the password ++@end example ++ ++@end defun ++ ++@node Index ++@chapter Index ++@printindex cp ++ ++@node Function Index ++@chapter Function Index ++@printindex fn ++ ++@node Variable Index ++@chapter Variable Index ++@printindex vr ++ ++@bye ++ ++@c End: ++ ++@ignore ++ arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 ++@end ignore +diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi +new file mode 100644 +index 0000000..0ca6b81 +--- /dev/null ++++ b/doc/misc/autotype.texi +@@ -0,0 +1,670 @@ ++\input texinfo ++@c This is an annex of the Emacs manual. ++@c Author: Daniel.Pfeiffer@Informatik.START.dbp.de, fax (+49 69) 7588-2389 ++@setfilename ../../info/autotype ++@c @node Autotypist, Picture, Abbrevs, Top ++@c @chapter Features for Automatic Typing ++@settitle Features for Automatic Typing ++@c @cindex text ++@c @cindex selfinserting text ++@c @cindex autotypist ++ ++@copying ++Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* Autotype: (autotype). Convenient features for text that you enter frequently ++ in Emacs. ++@end direntry ++ ++@titlepage ++@sp 10 ++ ++@center @titlefont{Autotyping} ++@sp 2 ++@center @subtitlefont{Convenient features for text that you enter ++frequently in Emacs} ++@sp 2 ++@center Daniel Pfeiffer ++@center additions by Dave Love ++ ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top ++@top Autotyping ++ ++ Under certain circumstances you will find yourself typing similar things ++over and over again. This is especially true of form letters and programming ++language constructs. Project-specific header comments, flow-control ++constructs or magic numbers are essentially the same every time. Emacs has ++various features for doing tedious and repetitive typing chores for you ++in addition to the Abbrev features (@pxref{(emacs)Abbrevs}). ++ ++ One solution is using skeletons, flexible rules that say what to ++insert, and how to do it. Various programming language modes offer some ++ready-to-use skeletons, and you can adapt them to suit your needs or ++taste, or define new ones. ++ ++ Another feature is automatic insertion of what you want into empty files, ++depending on the file-name or the mode as appropriate. You can have a file or ++a skeleton inserted, or you can call a function. Then there is the ++possibility to have Un*x interpreter scripts automatically take on a magic ++number and be executable as soon as they are saved. Or you can have a ++copyright notice's year updated, if necessary, every time you save a ++file. Similarly for time stamps in the file. ++ ++ URLs can be inserted based on a word at point. Flexible templates can ++be defined for inserting and navigating between text more generally. A ++sort of meta-expansion facility can be used to try a set of alternative ++completions and expansions of text at point. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Using Skeletons:: How to insert a skeleton into your text. ++* Wrapping Skeletons:: Putting existing text within a skeleton. ++* Skeletons as Abbrevs:: An alternative for issuing skeleton commands. ++* Skeleton Language:: Making skeleton commands insert what you want. ++* Inserting Pairs:: Typing one character and getting another ++ after point. ++* Autoinserting:: Filling up empty files as soon as you visit them. ++* Copyrights:: Inserting and updating copyrights. ++* Executables:: Turning interpreter scripts into executables. ++* Timestamps:: Updating dates and times in modified files. ++* QuickURL:: Inserting URLs based on text at point. ++* Tempo:: Flexible template insertion. ++* Hippie Expand:: Expansion of text trying various methods. ++ ++* GNU Free Documentation License:: The license for this documentation. ++* Concept Index:: ++* Command Index:: ++* Variable Index:: ++@end menu ++ ++ ++@node Using Skeletons ++@chapter Using Skeletons ++@cindex skeletons ++@cindex using skeletons ++ ++ When you want Emacs to insert a form letter or a typical construct of the ++programming language you are using, skeletons are a means of accomplishing ++this. Normally skeletons each have a command of their own, that, when called, ++will insert the skeleton. These commands can be issued in the usual ways ++(@pxref{(emacs)Commands}). Modes that offer various skeletons will often ++bind these to key-sequences on the @kbd{C-c} prefix, as well as having ++an @cite{Insert} menu and maybe even predefined abbrevs for them ++(@pxref{Skeletons as Abbrevs}). ++ ++ The simplest kind of skeleton will simply insert some text indented ++according to the major mode and leave the cursor at a likely place in the ++middle. Interactive skeletons may prompt you for a string that will be part ++of the inserted text. ++ ++ Skeletons may ask for input several times. They even have a looping ++mechanism in which you will be asked for input as long as you are willing to ++furnish it. An example would be multiple ``else if'' conditions. You can ++recognize this situation by a prompt ending in @key{RET}, @kbd{C-g} ++or @kbd{C-h}. This ++means that entering an empty string will simply assume that you are finished. ++Typing quit on the other hand terminates the loop but also the rest of the ++skeleton, e.g. an ``else'' clause is skipped. Only a syntactically necessary ++termination still gets inserted. ++ ++ ++ ++@node Wrapping Skeletons ++@chapter Wrapping Skeletons Around Existing Text ++@cindex wrapping skeletons ++ ++ Often you will find yourself with some code that for whatever reason ++suddenly becomes conditional. Or you have written a bit of text and want to ++put it in the middle of a form letter. Skeletons provide a means for ++accomplishing this, and can even, in the case of programming languages, ++reindent the wrapped code for you. ++ ++ Skeleton commands take an optional numeric prefix argument ++(@pxref{(emacs)Arguments}). This is interpreted in two different ways depending ++on whether the prefix is positive, i.e. forwards oriented or negative, ++i.e. backwards oriented. ++ ++ A positive prefix means to wrap the skeleton around that many ++following words. This is accomplished by putting the words there where ++the point is normally left after that skeleton is inserted (@pxref{Using ++Skeletons}). The point (@pxref{(emacs)Point}) is left at the next ++interesting spot in the skeleton instead. ++ ++ A negative prefix means to do something similar with that many precedingly ++marked interregions (@pxref{(emacs)Mark}). In the simplest case, if you type ++@kbd{M--} just before issuing the skeleton command, that will wrap the ++skeleton around the current region, just like a positive argument would have ++wrapped it around a number of words. ++ ++ Smaller negative arguments will wrap that many interregions into successive ++interesting spots within the skeleton, again leaving the point at the next one. ++We speak about interregions rather than regions here, because we treat them in ++the order they appear in the buffer, which coincides with successive regions ++only if they were marked in order. ++ ++ That is, if you marked in alphabetical order the points A B C [] (where [] ++represents the point) and call a skeleton command with @kbd{M-- 3}, you will ++wrap the text from A to B into the first interesting spot of the skeleton, the ++text from B to C into the next one, the text from C to the point into the ++third one, and leave the point in the fourth one. If there are less marks in ++the buffer, or if the skeleton defines less interesting points, the surplus is ++ignored. ++ ++ If, on the other hand, you marked in alphabetical order the points [] A C B, ++and call a skeleton command with @kbd{M-- 3}, you will wrap the text from ++point to A, then the text from A to C and finally the text from C to B. This ++is done because the regions overlap and Emacs would be helplessly lost if it ++tried to follow the order in which you marked these points. ++ ++ ++ ++@node Skeletons as Abbrevs ++@chapter Skeletons as Abbrev Expansions ++@cindex skeletons as abbrevs ++ ++ Rather than use a key binding for every skeleton command, you can also ++define an abbreviation (@pxref{(emacs)Defining Abbrevs}) that will expand ++(@pxref{(emacs)Expanding Abbrevs}) into the skeleton. ++ ++ Say you want @samp{ifst} to be an abbreviation for the C language if ++statement. You will tell Emacs that @samp{ifst} expands to the empty string ++and then calls the skeleton command. In Emacs Lisp you can say something like ++@code{(define-abbrev c-mode-abbrev-table "ifst" "" 'c-if)}. Or you can edit ++the output from @kbd{M-x list-abbrevs} to make it look like this: ++ ++@example ++(c-mode-abbrev-table) ++"if" 0 "" c-if ++@end example ++ ++@noindent ++(Some blank lines of no semantic significance, and other abbrev tables, ++have been omitted.) ++ ++ ++ ++@node Skeleton Language ++@chapter Skeleton Language ++@cindex skeleton language ++ ++@findex skeleton-insert ++ Skeletons are an shorthand extension to the Lisp language, where various ++atoms directly perform either actions on the current buffer or rudimentary ++flow control mechanisms. Skeletons are interpreted by the function ++@code{skeleton-insert}. ++ ++ A skeleton is a list starting with an interactor, which is usually a ++prompt-string, or @code{nil} when not needed, but can also be a Lisp ++expression for complex read functions or for returning some calculated value. ++The rest of the list are any number of elements as described in the following ++table: ++ ++@table @asis ++@item @code{"@var{string}"}, @code{?@var{c}}, @code{?\@var{c}} ++@vindex skeleton-transformation ++Insert string or character. Literal strings and characters are passed through ++@code{skeleton-transformation} when that is non-@code{nil}. ++@item @code{?\n} ++@c ??? something seems very wrong here. ++Insert a newline and align under current line. Use newline character ++@code{?\n} to prevent alignment. ++@item @code{_} ++Interesting point. When wrapping skeletons around successive regions, they are ++put at these places. Point is left at first @code{_} where nothing is wrapped. ++@item @code{>} ++Indent line according to major mode. When following element is @code{_}, and ++there is a interregion that will be wrapped here, indent that interregion. ++@item @code{&} ++Logical and. Iff preceding element moved point, i.e. usually inserted ++something, do following element. ++@item @code{|} ++Logical xor. Iff preceding element didn't move point, i.e. usually inserted ++nothing, do following element. ++@item @code{-@var{number}} ++Delete preceding number characters. Depends on value of ++@code{skeleton-untabify}. ++@item @code{()} or @code{nil} ++Ignored. ++@item @var{lisp-expression} ++Evaluated, and the return value is again interpreted as a skeleton element. ++@item @code{str} ++A special variable that, when evaluated the first time, usually prompts ++for input according to the skeleton's interactor. It is then set to the ++return value resulting from the interactor. Each subskeleton has its local ++copy of this variable. ++@item @code{v1}, @code{v2} ++Skeleton-local user variables. ++@item @code{'@var{expression}} ++Evaluate following Lisp expression for its side-effect, but prevent it from ++being interpreted as a skeleton element. ++@item @var{skeleton} ++Subskeletons are inserted recursively, not once, but as often as the user ++enters something at the subskeletons interactor. Thus there must be a ++@code{str} in the subskeleton. They can also be used non-interactively, when ++prompt is a lisp-expression that returns successive list-elements. ++@item @code{resume:} ++Ignored. Execution resumes here if the user quits during skeleton ++interpretation. ++@item @code{quit} ++A constant which is non-@code{nil} when the @code{resume:} section was entered ++because the user quit. ++@end table ++ ++@findex skeleton-further-elements ++ Some modes also use other skeleton elements they themselves defined. For ++example in shell script mode's skeletons you will find @code{<} which does a ++rigid indentation backwards, or in CC mode's skeletons you find the ++self-inserting elements @code{@{} and @code{@}}. These are defined by the ++buffer-local variable @code{skeleton-further-elements} which is a list of ++variables bound while interpreting a skeleton. ++ ++@findex define-skeleton ++ The macro @code{define-skeleton} defines a command for interpreting a ++skeleton. The first argument is the command name, the second is a ++documentation string, and the rest is an interactor and any number of skeleton ++elements together forming a skeleton. This skeleton is assigned to a variable ++of the same name as the command and can thus be overridden from your ++@file{~/.emacs} file (@pxref{(emacs)Init File}). ++ ++ ++ ++@node Inserting Pairs ++@chapter Inserting Matching Pairs of Characters ++@cindex inserting pairs ++@cindex pairs ++ ++ Various characters usually appear in pairs. When, for example, you insert ++an open parenthesis, no matter whether you are programming or writing prose, ++you will surely enter a closing one later. By entering both at the same time ++and leaving the cursor inbetween, Emacs can guarantee you that such ++parentheses are always balanced. And if you have a non-qwerty keyboard, where ++typing some of the stranger programming language symbols makes you bend your ++fingers backwards, this can be quite relieving too. ++ ++@findex skeleton-pair-insert-maybe ++@vindex skeleton-pair ++ This is done by binding the first key (@pxref{(emacs)Rebinding}) of ++the pair to @code{skeleton-pair-insert-maybe} instead of ++@code{self-insert-command}. The ``maybe'' comes from the fact that ++this at-first surprising behavior is initially turned off. To enable ++it, you must set @code{skeleton-pair} to some non-@code{nil} value. ++And even then, a positive argument (@pxref{(emacs)Arguments}) will ++make this key behave like a self-inserting key ++(@pxref{(emacs)Inserting Text}). ++ ++@vindex skeleton-pair-on-word ++ While this breaks with the stated intention of always balancing pairs, it ++turns out that one often doesn't want pairing to occur, when the following ++character is part of a word. If you want pairing to occur even then, set ++@code{skeleton-pair-on-word} to some non-@code{nil} value. ++ ++@vindex skeleton-pair-alist ++ Pairing is possible for all visible characters. By default the ++parenthesis @samp{(}, the square bracket @samp{[}, the brace ++@samp{@{}, the pointed bracket @samp{<} and the backquote @samp{`} all ++pair with the symmetrical character. All other characters pair ++themselves. This behavior can be modified by the variable ++@code{skeleton-pair-alist}. This is in fact an alist of skeletons ++(@pxref{Skeleton Language}), with the first part of each sublist ++matching the typed character. This is the position of the interactor, ++but since pairs don't need the @code{str} element, this is ignored. ++ ++ Some modes have bound the command @code{skeleton-pair-insert-maybe} ++to relevant keys. These modes also configure the pairs as ++appropriate. For example, when typing english prose, you'd expect the ++backquote (@samp{`}) to pair with the quote (@samp{'}), while in Shell ++script mode it must pair to itself. They can also inhibit pairing in ++certain contexts. For example an escaped character stands for itself. ++ ++ ++ ++@node Autoinserting ++@chapter Autoinserting Text in Empty Files ++@cindex autoinserting ++ ++@findex auto-insert ++ @kbd{M-x auto-insert} will put some predefined text at the beginning of ++the buffer. The main application for this function, as its name suggests, ++is to have it be called automatically every time an empty, and only an ++empty file is visited. This is accomplished by putting @code{(add-hook ++'find-file-hook 'auto-insert)} into your @file{~/.emacs} file ++(@pxref{(emacs)Init File}). ++ ++@vindex auto-insert-alist ++ What gets inserted, if anything, is determined by the variable ++@code{auto-insert-alist}. The @sc{car}s of this list are each either ++a mode name, making an element applicable when a buffer is in that ++mode. Or they can be a string, which is a regexp matched against the ++buffer's file name. In that way different kinds of files that have ++the same mode in Emacs can be distinguished. The @sc{car}s may also ++be cons cells consisting of mode name or regexp as above and an ++additional descriptive string. ++ ++ When a matching element is found, the @sc{cdr} says what to do. It may ++be a string, which is a file name, whose contents are to be inserted, if ++that file is found in the directory @code{auto-insert-directory} or under a ++absolute file name. Or it can be a skeleton (@pxref{Skeleton Language}) to ++be inserted. ++ ++ It can also be a function, which allows doing various things. The function ++can simply insert some text, indeed, it can be skeleton command (@pxref{Using ++Skeletons}). It can be a lambda function which will for example conditionally ++call another function. Or it can even reset the mode for the buffer. If you ++want to perform several such actions in order, you use a vector, i.e. several ++of the above elements between square brackets (@samp{[@r{@dots{}}]}). ++ ++ By default C and C++ headers insert a definition of a symbol derived from ++the filename to prevent multiple inclusions. C and C++ sources insert an ++include of the header. Makefiles insert the file makefile.inc if it exists. ++ ++ TeX and bibTeX mode files insert the file tex-insert.tex if it exists, while ++LaTeX mode files insert a typical @code{\documentclass} frame. Html ++files insert a skeleton with the usual frame. ++ ++ Ada mode files call the Ada header skeleton command. Emacs lisp ++source files insert the usual header, with a copyright of your ++environment variable @env{$ORGANIZATION} or else the FSF, and prompt ++for valid keywords describing the contents. Files in a @file{bin} ++directory for which Emacs could determine no specialized mode ++(@pxref{(emacs)Choosing Modes}) are set to Shell script mode. ++ ++@findex define-auto-insert ++ In Lisp (@pxref{(emacs)Init File}) you can use the function ++@code{define-auto-insert} to add to or modify ++@code{auto-insert-alist}. See its documentation with @kbd{C-h f ++define-auto-insert}. ++ ++@vindex auto-insert ++ The variable @code{auto-insert} says what to do when @code{auto-insert} is ++called non-interactively, e.g. when a newly found file is empty (see above): ++@table @asis ++@item @code{nil} ++Do nothing. ++@item @code{t} ++Insert something if possible, i.e. there is a matching entry in ++@code{auto-insert-alist}. ++@item other ++Insert something if possible, but mark as unmodified. ++@end table ++ ++@vindex auto-insert-query ++ The variable @code{auto-insert-query} controls whether to ask about ++inserting something. When this is @code{nil}, inserting is only done with ++@kbd{M-x auto-insert}. When this is @code{function}, you are queried ++whenever @code{auto-insert} is called as a function, such as when Emacs ++visits an empty file and you have set the above-mentioned hook. Otherwise ++you are alway queried. ++ ++@vindex auto-insert-prompt ++ When querying, the variable @code{auto-insert-prompt}'s value is used as a ++prompt for a y-or-n-type question. If this includes a @samp{%s} construct, ++that is replaced by what caused the insertion rule to be chosen. This is ++either a descriptive text, the mode-name of the buffer or the regular ++expression that matched the filename. ++ ++ ++ ++@node Copyrights ++@chapter Inserting and Updating Copyrights ++@cindex copyrights ++ ++@findex copyright ++ @kbd{M-x copyright} is a skeleton inserting command, that adds a copyright ++notice at the point. The ``by'' part is taken from your environment variable ++@env{$ORGANIZATION} or if that isn't set you are prompted for it. If the ++buffer has a comment syntax (@pxref{(emacs)Comments}), this is inserted as a comment. ++ ++@findex copyright-update ++@vindex copyright-limit ++@vindex copyright-current-year ++ @kbd{M-x copyright-update} looks for a copyright notice in the first ++@code{copyright-limit} characters of the buffer and updates it when necessary. ++The current year (variable @code{copyright-current-year}) is added to the ++existing ones, in the same format as the preceding year, i.e. 1994, '94 or 94. ++If a dash-separated year list up to last year is found, that is extended to ++current year, else the year is added separated by a comma. Or it replaces ++them when this is called with a prefix argument. If a header referring to a ++wrong version of the GNU General Public License (@pxref{(emacs)Copying}) is found, ++that is updated too. ++ ++ An interesting application for this function is to have it be called ++automatically every time a file is saved. This is accomplished by ++putting @code{(add-hook 'before-save-hook 'copyright-update)} into ++your @file{~/.emacs} file (@pxref{(emacs)Init File}). Alternative, ++you can do @kbd{M-x customize-variable @key{RET} before-save-hook ++@key{RET}}. @code{copyright-update} is conveniently listed as an ++option in the customization buffer. ++ ++@vindex copyright-query ++ The variable @code{copyright-query} controls whether to update the ++copyright or whether to ask about it. When this is @code{nil} updating is ++only done with @kbd{M-x copyright-update}. When this is @code{function} ++you are queried whenever @code{copyright-update} is called as a function, ++such as in the @code{before-save-hook} feature mentioned above. Otherwise ++you are always queried. ++ ++ ++ ++@node Executables ++@chapter Making Interpreter Scripts Executable ++@cindex executables ++ ++@vindex executable-prefix ++@vindex executable-chmod ++ Various interpreter modes such as Shell script mode or AWK mode will ++automatically insert or update the buffer's magic number, a special ++comment on the first line that makes the @code{exec} systemcall know ++how to execute the script. To this end the script is automatically ++made executable upon saving, with @code{executable-chmod} as argument ++to the system @code{chmod} command. The magic number is prefixed by ++the value of @code{executable-prefix}. ++ ++@vindex executable-magicless-file-regexp ++ Any file whose name matches @code{executable-magicless-file-regexp} is not ++furnished with a magic number, nor is it made executable. This is mainly ++intended for resource files, which are only meant to be read in. ++ ++@vindex executable-insert ++ The variable @code{executable-insert} says what to do when ++@code{executable-set-magic} is called non-interactively, e.g. when file has no ++or the wrong magic number: ++@table @asis ++@item @code{nil} ++Do nothing. ++@item @code{t} ++Insert or update magic number. ++@item other ++Insert or update magic number, but mark as unmodified. ++@end table ++ ++@findex executable-set-magic ++@vindex executable-query ++ The variable @code{executable-query} controls whether to ask about ++inserting or updating the magic number. When this is @code{nil} updating ++is only done with @kbd{M-x executable-set-magic}. When this is ++@code{function} you are queried whenever @code{executable-set-magic} is ++called as a function, such as when Emacs puts a buffer in Shell script ++mode. Otherwise you are alway queried. ++ ++@findex executable-self-display ++ @kbd{M-x executable-self-display} adds a magic number to the buffer, which ++will turn it into a self displaying text file, when called as a Un*x command. ++The ``interpreter'' used is @code{executable-self-display} with argument ++@samp{+2}. ++ ++@node Timestamps ++@chapter Maintaining Timestamps in Modified Files ++@cindex timestamps ++ ++@findex time-stamp ++@vindex before-save-hook ++The @code{time-stamp} command can be used to update automatically a ++template in a file with a new time stamp every time you save the file. ++Customize the hook @code{before-save-hook} to add the function ++@code{time-stamp} to arrange this. It you use Custom to do this, ++then @code{time-stamp} is conveniently listed as an option in the ++customization buffer. ++ ++@vindex time-stamp-active ++@vindex time-stamp-format ++@vindex time-stamp-start ++The time stamp is updated only if the customizable variable ++@code{time-stamp-active} is on, which it is by default; the command ++@code{time-stamp-toggle-active} can be used to toggle it. The format of ++the time stamp is set by the customizable variable ++@code{time-stamp-format}. ++ ++@vindex time-stamp-line-limit ++@vindex time-stamp-end ++@vindex time-stamp-count ++@vindex time-stamp-inserts-lines ++The variables @code{time-stamp-line-limit}, @code{time-stamp-start}, ++@code{time-stamp-end}, @code{time-stamp-count}, and ++@code{time-stamp-inserts-lines} control finding the template. Do not ++change these in your init file or you will be incompatible with other ++people's files. If you must change them, do so only in the local ++variables section of the file itself. ++ ++Normally the template must appear in the first 8 lines of a file and ++look like one of the following: ++ ++@example ++Time-stamp: <> ++Time-stamp: " " ++@end example ++ ++The time stamp is written between the brackets or quotes: ++ ++@example ++Time-stamp: <1998-02-18 10:20:51 gildea> ++@end example ++ ++@node QuickURL ++@chapter QuickURL: Inserting URLs Based on Text at Point ++ ++@vindex quickurl-url-file ++@findex quickurl ++@cindex URLs ++@kbd{M-x quickurl} can be used to insert a URL into a buffer based on ++the text at point. The URLs are stored in an external file defined by ++the variable @code{quickurl-url-file} as a list of either cons cells of ++the form @code{(@var{key} . @var{URL})} or ++lists of the form @code{(@var{key} @var{URL} @var{comment})}. These ++specify that @kbd{M-x quickurl} should insert @var{URL} if the word ++@var{key} is at point, for example: ++ ++@example ++(("FSF" "http://www.fsf.org/" "The Free Software Foundation") ++ ("emacs" . "http://www.emacs.org/") ++ ("hagbard" "http://www.hagbard.demon.co.uk" "Hagbard's World")) ++@end example ++ ++@findex quickurl-add-url ++@findex quickurl-list ++@kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL} ++pair. @kbd{M-x quickurl-list} provides interactive editing of the URL ++list. ++ ++@node Tempo ++@chapter Tempo: Flexible Template Insertion ++ ++@cindex templates ++The Tempo package provides a simple way to define powerful templates, or ++macros, if you wish. It is mainly intended for, but not limited to, ++programmers to be used for creating shortcuts for editing ++certain kinds of documents. ++ ++@findex tempo-backward-mark ++@findex tempo-forward-mark ++A template is defined as a list of items to be inserted in the current ++buffer at point. Some can be simple strings, while others can control ++formatting or define special points of interest in the inserted text. ++@kbd{M-x tempo-backward-mark} and @kbd{M-x tempo-forward-mark} can be ++used to jump between such points. ++ ++More flexible templates can be created by including Lisp symbols, which ++will be evaluated as variables, or lists, which will be evaluated ++as Lisp expressions. Automatic completion of specified tags to expanded ++templates can be provided. ++ ++@findex tempo-define-template ++See the documentation for @code{tempo-define-template} for the different ++items that can be used to define a tempo template with a command for ++inserting it. ++ ++See the commentary in @file{tempo.el} for more information on using the ++Tempo package. ++ ++@node Hippie Expand ++@chapter `Hippie' Expansion ++ ++@findex hippie-expand ++@kindex M-/ ++@vindex hippie-expand-try-functions-list ++@kbd{M-x hippie-expand} is a single command providing a variety of ++completions and expansions. Called repeatedly, it tries all possible ++completions in succession. ++ ++Which ones to try, and in which order, is determined by the contents of ++the customizable option @code{hippie-expand-try-functions-list}. Much ++customization of the expansion behavior can be made by changing the ++order of, removing, or inserting new functions in this list. Given a ++positive numeric argument, @kbd{M-x hippie-expand} jumps directly that ++number of functions forward in this list. Given some other argument (a ++negative argument or just @kbd{C-u}) it undoes the tried completion. ++ ++See the commentary in @file{hippie-exp.el} for more information on the ++possibilities. ++ ++Typically you would bind @code{hippie-expand} to @kbd{M-/} with ++@code{dabbrev-expand}, the standard binding of @kbd{M-/}, providing one ++of the expansion possibilities. ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Concept Index ++@unnumbered Concept Index ++@printindex cp ++ ++@node Command Index ++@unnumbered Command Index ++@printindex fn ++ ++@node Variable Index ++@unnumbered Variable Index ++@printindex vr ++ ++@bye ++ ++@ignore ++ arch-tag: 54001b27-5ef8-4a9d-a199-905d650fafba ++@end ignore +diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi +new file mode 100644 +index 0000000..0475ee2 +--- /dev/null ++++ b/doc/misc/calc.texi +@@ -0,0 +1,36383 @@ ++\input texinfo @c -*-texinfo-*- ++@comment %**start of header (This is for running Texinfo on a region.) ++@c smallbook ++@setfilename ../../info/calc ++@c [title] ++@settitle GNU Emacs Calc Manual ++@setchapternewpage odd ++@comment %**end of header (This is for running Texinfo on a region.) ++ ++@c The following macros are used for conditional output for single lines. ++@c @texline foo ++@c `foo' will appear only in TeX output ++@c @infoline foo ++@c `foo' will appear only in non-TeX output ++ ++@c @expr{expr} will typeset an expression; ++@c $x$ in TeX, @samp{x} otherwise. ++ ++@iftex ++@macro texline ++@end macro ++@alias infoline=comment ++@alias expr=math ++@alias tfn=code ++@alias mathit=expr ++@alias summarykey=key ++@macro cpi{} ++@math{@pi{}} ++@end macro ++@macro cpiover{den} ++@math{@pi/\den\} ++@end macro ++@end iftex ++ ++@ifnottex ++@alias texline=comment ++@macro infoline{stuff} ++\stuff\ ++@end macro ++@alias expr=samp ++@alias tfn=t ++@alias mathit=i ++@macro summarykey{ky} ++\ky\ ++@end macro ++@macro cpi{} ++@expr{pi} ++@end macro ++@macro cpiover{den} ++@expr{pi/\den\} ++@end macro ++@end ifnottex ++ ++ ++@tex ++% Suggested by Karl Berry ++\gdef\!{\mskip-\thinmuskip} ++@end tex ++ ++@c Fix some other things specifically for this manual. ++@iftex ++@finalout ++@mathcode`@:=`@: @c Make Calc fractions come out right in math mode ++@tex ++\gdef\coloneq{\mathrel{\mathord:\mathord=}} ++ ++\gdef\beforedisplay{\vskip-10pt} ++\gdef\afterdisplay{\vskip-5pt} ++\gdef\beforedisplayh{\vskip-25pt} ++\gdef\afterdisplayh{\vskip-10pt} ++@end tex ++@newdimen@kyvpos @kyvpos=0pt ++@newdimen@kyhpos @kyhpos=0pt ++@newcount@calcclubpenalty @calcclubpenalty=1000 ++@ignore ++@newcount@calcpageno ++@newtoks@calcoldeverypar @calcoldeverypar=@everypar ++@everypar={@calceverypar@the@calcoldeverypar} ++@ifx@turnoffactive@undefinedzzz@def@turnoffactive{}@fi ++@ifx@ninett@undefinedzzz@font@ninett=cmtt9@fi ++@catcode`@\=0 \catcode`\@=11 ++\r@ggedbottomtrue ++\catcode`\@=0 @catcode`@\=@active ++@end ignore ++@end iftex ++ ++@copying ++@ifinfo ++This file documents Calc, the GNU Emacs calculator. ++@end ifinfo ++@ifnotinfo ++This file documents Calc, the GNU Emacs calculator, included with GNU Emacs 23.1. ++@end ifnotinfo ++ ++Copyright @copyright{} 1990, 1991, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 the ++Invariant Sections being just ``GNU GENERAL PUBLIC LICENSE'', 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 Emacs ++@direntry ++* Calc: (calc). Advanced desk calculator and mathematical tool. ++@end direntry ++ ++@titlepage ++@sp 6 ++@center @titlefont{Calc Manual} ++@sp 4 ++@center GNU Emacs Calc ++@c [volume] ++@sp 5 ++@center Dave Gillespie ++@center daveg@@synaptics.com ++@page ++ ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++ ++@summarycontents ++ ++@c [end] ++ ++@contents ++ ++@c [begin] ++@ifnottex ++@node Top, Getting Started, (dir), (dir) ++@chapter The GNU Emacs Calculator ++ ++@noindent ++@dfn{Calc} is an advanced desk calculator and mathematical tool ++written by Dave Gillespie that runs as part of the GNU Emacs environment. ++ ++This manual, also written (mostly) by Dave Gillespie, is divided into ++three major parts: ``Getting Started,'' the ``Calc Tutorial,'' and the ++``Calc Reference.'' The Tutorial introduces all the major aspects of ++Calculator use in an easy, hands-on way. The remainder of the manual is ++a complete reference to the features of the Calculator. ++@end ifnottex ++ ++@ifinfo ++For help in the Emacs Info system (which you are using to read this ++file), type @kbd{?}. (You can also type @kbd{h} to run through a ++longer Info tutorial.) ++@end ifinfo ++ ++@insertcopying ++ ++@menu ++* Getting Started:: General description and overview. ++@ifinfo ++* Interactive Tutorial:: ++@end ifinfo ++* Tutorial:: A step-by-step introduction for beginners. ++ ++* Introduction:: Introduction to the Calc reference manual. ++* Data Types:: Types of objects manipulated by Calc. ++* Stack and Trail:: Manipulating the stack and trail buffers. ++* Mode Settings:: Adjusting display format and other modes. ++* Arithmetic:: Basic arithmetic functions. ++* Scientific Functions:: Transcendentals and other scientific functions. ++* Matrix Functions:: Operations on vectors and matrices. ++* Algebra:: Manipulating expressions algebraically. ++* Units:: Operations on numbers with units. ++* Store and Recall:: Storing and recalling variables. ++* Graphics:: Commands for making graphs of data. ++* Kill and Yank:: Moving data into and out of Calc. ++* Keypad Mode:: Operating Calc from a keypad. ++* Embedded Mode:: Working with formulas embedded in a file. ++* Programming:: Calc as a programmable calculator. ++ ++* Copying:: How you can copy and share Calc. ++* GNU Free Documentation License:: The license for this documentation. ++* Customizing Calc:: Customizing Calc. ++* Reporting Bugs:: How to report bugs and make suggestions. ++ ++* Summary:: Summary of Calc commands and functions. ++ ++* Key Index:: The standard Calc key sequences. ++* Command Index:: The interactive Calc commands. ++* Function Index:: Functions (in algebraic formulas). ++* Concept Index:: General concepts. ++* Variable Index:: Variables used by Calc (both user and internal). ++* Lisp Function Index:: Internal Lisp math functions. ++@end menu ++ ++@ifinfo ++@node Getting Started, Interactive Tutorial, Top, Top ++@end ifinfo ++@ifnotinfo ++@node Getting Started, Tutorial, Top, Top ++@end ifnotinfo ++@chapter Getting Started ++@noindent ++This chapter provides a general overview of Calc, the GNU Emacs ++Calculator: What it is, how to start it and how to exit from it, ++and what are the various ways that it can be used. ++ ++@menu ++* What is Calc:: ++* About This Manual:: ++* Notations Used in This Manual:: ++* Demonstration of Calc:: ++* Using Calc:: ++* History and Acknowledgements:: ++@end menu ++ ++@node What is Calc, About This Manual, Getting Started, Getting Started ++@section What is Calc? ++ ++@noindent ++@dfn{Calc} is an advanced calculator and mathematical tool that runs as ++part of the GNU Emacs environment. Very roughly based on the HP-28/48 ++series of calculators, its many features include: ++ ++@itemize @bullet ++@item ++Choice of algebraic or RPN (stack-based) entry of calculations. ++ ++@item ++Arbitrary precision integers and floating-point numbers. ++ ++@item ++Arithmetic on rational numbers, complex numbers (rectangular and polar), ++error forms with standard deviations, open and closed intervals, vectors ++and matrices, dates and times, infinities, sets, quantities with units, ++and algebraic formulas. ++ ++@item ++Mathematical operations such as logarithms and trigonometric functions. ++ ++@item ++Programmer's features (bitwise operations, non-decimal numbers). ++ ++@item ++Financial functions such as future value and internal rate of return. ++ ++@item ++Number theoretical features such as prime factorization and arithmetic ++modulo @var{m} for any @var{m}. ++ ++@item ++Algebraic manipulation features, including symbolic calculus. ++ ++@item ++Moving data to and from regular editing buffers. ++ ++@item ++Embedded mode for manipulating Calc formulas and data directly ++inside any editing buffer. ++ ++@item ++Graphics using GNUPLOT, a versatile (and free) plotting program. ++ ++@item ++Easy programming using keyboard macros, algebraic formulas, ++algebraic rewrite rules, or extended Emacs Lisp. ++@end itemize ++ ++Calc tries to include a little something for everyone; as a result it is ++large and might be intimidating to the first-time user. If you plan to ++use Calc only as a traditional desk calculator, all you really need to ++read is the ``Getting Started'' chapter of this manual and possibly the ++first few sections of the tutorial. As you become more comfortable with ++the program you can learn its additional features. Calc does not ++have the scope and depth of a fully-functional symbolic math package, ++but Calc has the advantages of convenience, portability, and freedom. ++ ++@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started ++@section About This Manual ++ ++@noindent ++This document serves as a complete description of the GNU Emacs ++Calculator. It works both as an introduction for novices and as ++a reference for experienced users. While it helps to have some ++experience with GNU Emacs in order to get the most out of Calc, ++this manual ought to be readable even if you don't know or use Emacs ++regularly. ++ ++This manual is divided into three major parts:@: the ``Getting ++Started'' chapter you are reading now, the Calc tutorial, and the Calc ++reference manual. ++@c [when-split] ++@c This manual has been printed in two volumes, the @dfn{Tutorial} and the ++@c @dfn{Reference}. Both volumes include a copy of the ``Getting Started'' ++@c chapter. ++ ++If you are in a hurry to use Calc, there is a brief ``demonstration'' ++below which illustrates the major features of Calc in just a couple of ++pages. If you don't have time to go through the full tutorial, this ++will show you everything you need to know to begin. ++@xref{Demonstration of Calc}. ++ ++The tutorial chapter walks you through the various parts of Calc ++with lots of hands-on examples and explanations. If you are new ++to Calc and you have some time, try going through at least the ++beginning of the tutorial. The tutorial includes about 70 exercises ++with answers. These exercises give you some guided practice with ++Calc, as well as pointing out some interesting and unusual ways ++to use its features. ++ ++The reference section discusses Calc in complete depth. You can read ++the reference from start to finish if you want to learn every aspect ++of Calc. Or, you can look in the table of contents or the Concept ++Index to find the parts of the manual that discuss the things you ++need to know. ++ ++@c @cindex Marginal notes ++Every Calc keyboard command is listed in the Calc Summary, and also ++in the Key Index. Algebraic functions, @kbd{M-x} commands, and ++variables also have their own indices. ++@c @texline Each ++@c @infoline In the printed manual, each ++@c paragraph that is referenced in the Key or Function Index is marked ++@c in the margin with its index entry. ++ ++@c [fix-ref Help Commands] ++You can access this manual on-line at any time within Calc by pressing ++the @kbd{h i} key sequence. Outside of the Calc window, you can press ++@kbd{C-x * i} to read the manual on-line. From within Calc the command ++@kbd{h t} will jump directly to the Tutorial; from outside of Calc the ++command @kbd{C-x * t} will jump to the Tutorial and start Calc if ++necessary. Pressing @kbd{h s} or @kbd{C-x * s} will take you directly ++to the Calc Summary. Within Calc, you can also go to the part of the ++manual describing any Calc key, function, or variable using ++@w{@kbd{h k}}, @kbd{h f}, or @kbd{h v}, respectively. @xref{Help Commands}. ++ ++@ifnottex ++The Calc manual can be printed, but because the manual is so large, you ++should only make a printed copy if you really need it. To print the ++manual, you will need the @TeX{} typesetting program (this is a free ++program by Donald Knuth at Stanford University) as well as the ++@file{texindex} program and @file{texinfo.tex} file, both of which can ++be obtained from the FSF as part of the @code{texinfo} package. ++To print the Calc manual in one huge tome, you will need the ++source code to this manual, @file{calc.texi}, available as part of the ++Emacs source. Once you have this file, type @kbd{texi2dvi calc.texi}. ++Alternatively, change to the @file{man} subdirectory of the Emacs ++source distribution, and type @kbd{make calc.dvi}. (Don't worry if you ++get some ``overfull box'' warnings while @TeX{} runs.) ++The result will be a device-independent output file called ++@file{calc.dvi}, which you must print in whatever way is right ++for your system. On many systems, the command is ++ ++@example ++lpr -d calc.dvi ++@end example ++ ++@noindent ++or ++ ++@example ++dvips calc.dvi ++@end example ++@end ifnottex ++@c Printed copies of this manual are also available from the Free Software ++@c Foundation. ++ ++@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started ++@section Notations Used in This Manual ++ ++@noindent ++This section describes the various notations that are used ++throughout the Calc manual. ++ ++In keystroke sequences, uppercase letters mean you must hold down ++the shift key while typing the letter. Keys pressed with Control ++held down are shown as @kbd{C-x}. Keys pressed with Meta held down ++are shown as @kbd{M-x}. Other notations are @key{RET} for the ++Return key, @key{SPC} for the space bar, @key{TAB} for the Tab key, ++@key{DEL} for the Delete key, and @key{LFD} for the Line-Feed key. ++The @key{DEL} key is called Backspace on some keyboards, it is ++whatever key you would use to correct a simple typing error when ++regularly using Emacs. ++ ++(If you don't have the @key{LFD} or @key{TAB} keys on your keyboard, ++the @kbd{C-j} and @kbd{C-i} keys are equivalent to them, respectively. ++If you don't have a Meta key, look for Alt or Extend Char. You can ++also press @key{ESC} or @kbd{C-[} first to get the same effect, so ++that @kbd{M-x}, @kbd{@key{ESC} x}, and @kbd{C-[ x} are all equivalent.) ++ ++Sometimes the @key{RET} key is not shown when it is ``obvious'' ++that you must press @key{RET} to proceed. For example, the @key{RET} ++is usually omitted in key sequences like @kbd{M-x calc-keypad @key{RET}}. ++ ++Commands are generally shown like this: @kbd{p} (@code{calc-precision}) ++or @kbd{C-x * k} (@code{calc-keypad}). This means that the command is ++normally used by pressing the @kbd{p} key or @kbd{C-x * k} key sequence, ++but it also has the full-name equivalent shown, e.g., @kbd{M-x calc-precision}. ++ ++Commands that correspond to functions in algebraic notation ++are written: @kbd{C} (@code{calc-cos}) [@code{cos}]. This means ++the @kbd{C} key is equivalent to @kbd{M-x calc-cos}, and that ++the corresponding function in an algebraic-style formula would ++be @samp{cos(@var{x})}. ++ ++A few commands don't have key equivalents: @code{calc-sincos} ++[@code{sincos}]. ++ ++@node Demonstration of Calc, Using Calc, Notations Used in This Manual, Getting Started ++@section A Demonstration of Calc ++ ++@noindent ++@cindex Demonstration of Calc ++This section will show some typical small problems being solved with ++Calc. The focus is more on demonstration than explanation, but ++everything you see here will be covered more thoroughly in the ++Tutorial. ++ ++To begin, start Emacs if necessary (usually the command @code{emacs} ++does this), and type @kbd{C-x * c} to start the ++Calculator. (You can also use @kbd{M-x calc} if this doesn't work. ++@xref{Starting Calc}, for various ways of starting the Calculator.) ++ ++Be sure to type all the sample input exactly, especially noting the ++difference between lower-case and upper-case letters. Remember, ++@key{RET}, @key{TAB}, @key{DEL}, and @key{SPC} are the Return, Tab, ++Delete, and Space keys. ++ ++@strong{RPN calculation.} In RPN, you type the input number(s) first, ++then the command to operate on the numbers. ++ ++@noindent ++Type @kbd{2 @key{RET} 3 + Q} to compute ++@texline @math{\sqrt{2+3} = 2.2360679775}. ++@infoline the square root of 2+3, which is 2.2360679775. ++ ++@noindent ++Type @kbd{P 2 ^} to compute ++@texline @math{\pi^2 = 9.86960440109}. ++@infoline the value of `pi' squared, 9.86960440109. ++ ++@noindent ++Type @key{TAB} to exchange the order of these two results. ++ ++@noindent ++Type @kbd{- I H S} to subtract these results and compute the Inverse ++Hyperbolic sine of the difference, 2.72996136574. ++ ++@noindent ++Type @key{DEL} to erase this result. ++ ++@strong{Algebraic calculation.} You can also enter calculations using ++conventional ``algebraic'' notation. To enter an algebraic formula, ++use the apostrophe key. ++ ++@noindent ++Type @kbd{' sqrt(2+3) @key{RET}} to compute ++@texline @math{\sqrt{2+3}}. ++@infoline the square root of 2+3. ++ ++@noindent ++Type @kbd{' pi^2 @key{RET}} to enter ++@texline @math{\pi^2}. ++@infoline `pi' squared. ++To evaluate this symbolic formula as a number, type @kbd{=}. ++ ++@noindent ++Type @kbd{' arcsinh($ - $$) @key{RET}} to subtract the second-most-recent ++result from the most-recent and compute the Inverse Hyperbolic sine. ++ ++@strong{Keypad mode.} If you are using the X window system, press ++@w{@kbd{C-x * k}} to get Keypad mode. (If you don't use X, skip to ++the next section.) ++ ++@noindent ++Click on the @key{2}, @key{ENTER}, @key{3}, @key{+}, and @key{SQRT} ++``buttons'' using your left mouse button. ++ ++@noindent ++Click on @key{PI}, @key{2}, and @tfn{y^x}. ++ ++@noindent ++Click on @key{INV}, then @key{ENTER} to swap the two results. ++ ++@noindent ++Click on @key{-}, @key{INV}, @key{HYP}, and @key{SIN}. ++ ++@noindent ++Click on @key{<-} to erase the result, then click @key{OFF} to turn ++the Keypad Calculator off. ++ ++@strong{Grabbing data.} Type @kbd{C-x * x} if necessary to exit Calc. ++Now select the following numbers as an Emacs region: ``Mark'' the ++front of the list by typing @kbd{C-@key{SPC}} or @kbd{C-@@} there, ++then move to the other end of the list. (Either get this list from ++the on-line copy of this manual, accessed by @w{@kbd{C-x * i}}, or just ++type these numbers into a scratch file.) Now type @kbd{C-x * g} to ++``grab'' these numbers into Calc. ++ ++@example ++@group ++1.23 1.97 ++1.6 2 ++1.19 1.08 ++@end group ++@end example ++ ++@noindent ++The result @samp{[1.23, 1.97, 1.6, 2, 1.19, 1.08]} is a Calc ``vector.'' ++Type @w{@kbd{V R +}} to compute the sum of these numbers. ++ ++@noindent ++Type @kbd{U} to Undo this command, then type @kbd{V R *} to compute ++the product of the numbers. ++ ++@noindent ++You can also grab data as a rectangular matrix. Place the cursor on ++the upper-leftmost @samp{1} and set the mark, then move to just after ++the lower-right @samp{8} and press @kbd{C-x * r}. ++ ++@noindent ++Type @kbd{v t} to transpose this ++@texline @math{3\times2} ++@infoline 3x2 ++matrix into a ++@texline @math{2\times3} ++@infoline 2x3 ++matrix. Type @w{@kbd{v u}} to unpack the rows into two separate ++vectors. Now type @w{@kbd{V R + @key{TAB} V R +}} to compute the sums ++of the two original columns. (There is also a special ++grab-and-sum-columns command, @kbd{C-x * :}.) ++ ++@strong{Units conversion.} Units are entered algebraically. ++Type @w{@kbd{' 43 mi/hr @key{RET}}} to enter the quantity 43 miles-per-hour. ++Type @w{@kbd{u c km/hr @key{RET}}}. Type @w{@kbd{u c m/s @key{RET}}}. ++ ++@strong{Date arithmetic.} Type @kbd{t N} to get the current date and ++time. Type @kbd{90 +} to find the date 90 days from now. Type ++@kbd{' <25 dec 87> @key{RET}} to enter a date, then @kbd{- 7 /} to see how ++many weeks have passed since then. ++ ++@strong{Algebra.} Algebraic entries can also include formulas ++or equations involving variables. Type @kbd{@w{' [x + y} = a, x y = 1] @key{RET}} ++to enter a pair of equations involving three variables. ++(Note the leading apostrophe in this example; also, note that the space ++in @samp{x y} is required.) Type @w{@kbd{a S x,y @key{RET}}} to solve ++these equations for the variables @expr{x} and @expr{y}. ++ ++@noindent ++Type @kbd{d B} to view the solutions in more readable notation. ++Type @w{@kbd{d C}} to view them in C language notation, @kbd{d T} ++to view them in the notation for the @TeX{} typesetting system, ++and @kbd{d L} to view them in the notation for the La@TeX{} typesetting ++system. Type @kbd{d N} to return to normal notation. ++ ++@noindent ++Type @kbd{7.5}, then @kbd{s l a @key{RET}} to let @expr{a = 7.5} in these formulas. ++(That's the letter @kbd{l}, not the numeral @kbd{1}.) ++ ++@ifnotinfo ++@strong{Help functions.} You can read about any command in the on-line ++manual. Type @kbd{C-x * c} to return to Calc after each of these ++commands: @kbd{h k t N} to read about the @kbd{t N} command, ++@kbd{h f sqrt @key{RET}} to read about the @code{sqrt} function, and ++@kbd{h s} to read the Calc summary. ++@end ifnotinfo ++@ifinfo ++@strong{Help functions.} You can read about any command in the on-line ++manual. Remember to type the letter @kbd{l}, then @kbd{C-x * c}, to ++return here after each of these commands: @w{@kbd{h k t N}} to read ++about the @w{@kbd{t N}} command, @kbd{h f sqrt @key{RET}} to read about the ++@code{sqrt} function, and @kbd{h s} to read the Calc summary. ++@end ifinfo ++ ++Press @key{DEL} repeatedly to remove any leftover results from the stack. ++To exit from Calc, press @kbd{q} or @kbd{C-x * c} again. ++ ++@node Using Calc, History and Acknowledgements, Demonstration of Calc, Getting Started ++@section Using Calc ++ ++@noindent ++Calc has several user interfaces that are specialized for ++different kinds of tasks. As well as Calc's standard interface, ++there are Quick mode, Keypad mode, and Embedded mode. ++ ++@menu ++* Starting Calc:: ++* The Standard Interface:: ++* Quick Mode Overview:: ++* Keypad Mode Overview:: ++* Standalone Operation:: ++* Embedded Mode Overview:: ++* Other C-x * Commands:: ++@end menu ++ ++@node Starting Calc, The Standard Interface, Using Calc, Using Calc ++@subsection Starting Calc ++ ++@noindent ++On most systems, you can type @kbd{C-x *} to start the Calculator. ++The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch}, ++which can be rebound if convenient (@pxref{Customizing Calc}). ++ ++When you press @kbd{C-x *}, Emacs waits for you to press a second key to ++complete the command. In this case, you will follow @kbd{C-x *} with a ++letter (upper- or lower-case, it doesn't matter for @kbd{C-x *}) that says ++which Calc interface you want to use. ++ ++To get Calc's standard interface, type @kbd{C-x * c}. To get ++Keypad mode, type @kbd{C-x * k}. Type @kbd{C-x * ?} to get a brief ++list of the available options, and type a second @kbd{?} to get ++a complete list. ++ ++To ease typing, @kbd{C-x * *} also works to start Calc. It starts the ++same interface (either @kbd{C-x * c} or @w{@kbd{C-x * k}}) that you last ++used, selecting the @kbd{C-x * c} interface by default. ++ ++If @kbd{C-x *} doesn't work for you, you can always type explicit ++commands like @kbd{M-x calc} (for the standard user interface) or ++@w{@kbd{M-x calc-keypad}} (for Keypad mode). First type @kbd{M-x} ++(that's Meta with the letter @kbd{x}), then, at the prompt, ++type the full command (like @kbd{calc-keypad}) and press Return. ++ ++The same commands (like @kbd{C-x * c} or @kbd{C-x * *}) that start ++the Calculator also turn it off if it is already on. ++ ++@node The Standard Interface, Quick Mode Overview, Starting Calc, Using Calc ++@subsection The Standard Calc Interface ++ ++@noindent ++@cindex Standard user interface ++Calc's standard interface acts like a traditional RPN calculator, ++operated by the normal Emacs keyboard. When you type @kbd{C-x * c} ++to start the Calculator, the Emacs screen splits into two windows ++with the file you were editing on top and Calc on the bottom. ++ ++@smallexample ++@group ++ ++... ++--**-Emacs: myfile (Fundamental)----All---------------------- ++--- Emacs Calculator Mode --- |Emacs Calculator Trail ++2: 17.3 | 17.3 ++1: -5 | 3 ++ . | 2 ++ | 4 ++ | * 8 ++ | ->-5 ++ | ++--%*-Calc: 12 Deg (Calculator)----All----- --%*- *Calc Trail* ++@end group ++@end smallexample ++ ++In this figure, the mode-line for @file{myfile} has moved up and the ++``Calculator'' window has appeared below it. As you can see, Calc ++actually makes two windows side-by-side. The lefthand one is ++called the @dfn{stack window} and the righthand one is called the ++@dfn{trail window.} The stack holds the numbers involved in the ++calculation you are currently performing. The trail holds a complete ++record of all calculations you have done. In a desk calculator with ++a printer, the trail corresponds to the paper tape that records what ++you do. ++ ++In this case, the trail shows that four numbers (17.3, 3, 2, and 4) ++were first entered into the Calculator, then the 2 and 4 were ++multiplied to get 8, then the 3 and 8 were subtracted to get @mathit{-5}. ++(The @samp{>} symbol shows that this was the most recent calculation.) ++The net result is the two numbers 17.3 and @mathit{-5} sitting on the stack. ++ ++Most Calculator commands deal explicitly with the stack only, but ++there is a set of commands that allow you to search back through ++the trail and retrieve any previous result. ++ ++Calc commands use the digits, letters, and punctuation keys. ++Shifted (i.e., upper-case) letters are different from lowercase ++letters. Some letters are @dfn{prefix} keys that begin two-letter ++commands. For example, @kbd{e} means ``enter exponent'' and shifted ++@kbd{E} means @expr{e^x}. With the @kbd{d} (``display modes'') prefix ++the letter ``e'' takes on very different meanings: @kbd{d e} means ++``engineering notation'' and @kbd{d E} means ``@dfn{eqn} language mode.'' ++ ++There is nothing stopping you from switching out of the Calc ++window and back into your editing window, say by using the Emacs ++@w{@kbd{C-x o}} (@code{other-window}) command. When the cursor is ++inside a regular window, Emacs acts just like normal. When the ++cursor is in the Calc stack or trail windows, keys are interpreted ++as Calc commands. ++ ++When you quit by pressing @kbd{C-x * c} a second time, the Calculator ++windows go away but the actual Stack and Trail are not gone, just ++hidden. When you press @kbd{C-x * c} once again you will get the ++same stack and trail contents you had when you last used the ++Calculator. ++ ++The Calculator does not remember its state between Emacs sessions. ++Thus if you quit Emacs and start it again, @kbd{C-x * c} will give you ++a fresh stack and trail. There is a command (@kbd{m m}) that lets ++you save your favorite mode settings between sessions, though. ++One of the things it saves is which user interface (standard or ++Keypad) you last used; otherwise, a freshly started Emacs will ++always treat @kbd{C-x * *} the same as @kbd{C-x * c}. ++ ++The @kbd{q} key is another equivalent way to turn the Calculator off. ++ ++If you type @kbd{C-x * b} first and then @kbd{C-x * c}, you get a ++full-screen version of Calc (@code{full-calc}) in which the stack and ++trail windows are still side-by-side but are now as tall as the whole ++Emacs screen. When you press @kbd{q} or @kbd{C-x * c} again to quit, ++the file you were editing before reappears. The @kbd{C-x * b} key ++switches back and forth between ``big'' full-screen mode and the ++normal partial-screen mode. ++ ++Finally, @kbd{C-x * o} (@code{calc-other-window}) is like @kbd{C-x * c} ++except that the Calc window is not selected. The buffer you were ++editing before remains selected instead. If you are in a Calc window, ++then @kbd{C-x * o} will switch you out of it, being careful not to ++switch you to the Calc Trail window. So @kbd{C-x * o} is a handy ++way to switch out of Calc momentarily to edit your file; you can then ++type @kbd{C-x * c} to switch back into Calc when you are done. ++ ++@node Quick Mode Overview, Keypad Mode Overview, The Standard Interface, Using Calc ++@subsection Quick Mode (Overview) ++ ++@noindent ++@dfn{Quick mode} is a quick way to use Calc when you don't need the ++full complexity of the stack and trail. To use it, type @kbd{C-x * q} ++(@code{quick-calc}) in any regular editing buffer. ++ ++Quick mode is very simple: It prompts you to type any formula in ++standard algebraic notation (like @samp{4 - 2/3}) and then displays ++the result at the bottom of the Emacs screen (@mathit{3.33333333333} ++in this case). You are then back in the same editing buffer you ++were in before, ready to continue editing or to type @kbd{C-x * q} ++again to do another quick calculation. The result of the calculation ++will also be in the Emacs ``kill ring'' so that a @kbd{C-y} command ++at this point will yank the result into your editing buffer. ++ ++Calc mode settings affect Quick mode, too, though you will have to ++go into regular Calc (with @kbd{C-x * c}) to change the mode settings. ++ ++@c [fix-ref Quick Calculator mode] ++@xref{Quick Calculator}, for further information. ++ ++@node Keypad Mode Overview, Standalone Operation, Quick Mode Overview, Using Calc ++@subsection Keypad Mode (Overview) ++ ++@noindent ++@dfn{Keypad mode} is a mouse-based interface to the Calculator. ++It is designed for use with terminals that support a mouse. If you ++don't have a mouse, you will have to operate Keypad mode with your ++arrow keys (which is probably more trouble than it's worth). ++ ++Type @kbd{C-x * k} to turn Keypad mode on or off. Once again you ++get two new windows, this time on the righthand side of the screen ++instead of at the bottom. The upper window is the familiar Calc ++Stack; the lower window is a picture of a typical calculator keypad. ++ ++@tex ++\dimen0=\pagetotal% ++\advance \dimen0 by 24\baselineskip% ++\ifdim \dimen0>\pagegoal \vfill\eject \fi% ++\medskip ++@end tex ++@smallexample ++@group ++|--- Emacs Calculator Mode --- ++|2: 17.3 ++|1: -5 ++| . ++|--%*-Calc: 12 Deg (Calcul ++|----+----+--Calc---+----+----1 ++|FLR |CEIL|RND |TRNC|CLN2|FLT | ++|----+----+----+----+----+----| ++| LN |EXP | |ABS |IDIV|MOD | ++|----+----+----+----+----+----| ++|SIN |COS |TAN |SQRT|y^x |1/x | ++|----+----+----+----+----+----| ++| ENTER |+/- |EEX |UNDO| <- | ++|-----+---+-+--+--+-+---++----| ++| INV | 7 | 8 | 9 | / | ++|-----+-----+-----+-----+-----| ++| HYP | 4 | 5 | 6 | * | ++|-----+-----+-----+-----+-----| ++|EXEC | 1 | 2 | 3 | - | ++|-----+-----+-----+-----+-----| ++| OFF | 0 | . | PI | + | ++|-----+-----+-----+-----+-----+ ++@end group ++@end smallexample ++ ++Keypad mode is much easier for beginners to learn, because there ++is no need to memorize lots of obscure key sequences. But not all ++commands in regular Calc are available on the Keypad. You can ++always switch the cursor into the Calc stack window to use ++standard Calc commands if you need. Serious Calc users, though, ++often find they prefer the standard interface over Keypad mode. ++ ++To operate the Calculator, just click on the ``buttons'' of the ++keypad using your left mouse button. To enter the two numbers ++shown here you would click @w{@kbd{1 7 .@: 3 ENTER 5 +/- ENTER}}; to ++add them together you would then click @kbd{+} (to get 12.3 on ++the stack). ++ ++If you click the right mouse button, the top three rows of the ++keypad change to show other sets of commands, such as advanced ++math functions, vector operations, and operations on binary ++numbers. ++ ++Because Keypad mode doesn't use the regular keyboard, Calc leaves ++the cursor in your original editing buffer. You can type in ++this buffer in the usual way while also clicking on the Calculator ++keypad. One advantage of Keypad mode is that you don't need an ++explicit command to switch between editing and calculating. ++ ++If you press @kbd{C-x * b} first, you get a full-screen Keypad mode ++(@code{full-calc-keypad}) with three windows: The keypad in the lower ++left, the stack in the lower right, and the trail on top. ++ ++@c [fix-ref Keypad Mode] ++@xref{Keypad Mode}, for further information. ++ ++@node Standalone Operation, Embedded Mode Overview, Keypad Mode Overview, Using Calc ++@subsection Standalone Operation ++ ++@noindent ++@cindex Standalone Operation ++If you are not in Emacs at the moment but you wish to use Calc, ++you must start Emacs first. If all you want is to run Calc, you ++can give the commands: ++ ++@example ++emacs -f full-calc ++@end example ++ ++@noindent ++or ++ ++@example ++emacs -f full-calc-keypad ++@end example ++ ++@noindent ++which run a full-screen Calculator (as if by @kbd{C-x * b C-x * c}) or ++a full-screen X-based Calculator (as if by @kbd{C-x * b C-x * k}). ++In standalone operation, quitting the Calculator (by pressing ++@kbd{q} or clicking on the keypad @key{EXIT} button) quits Emacs ++itself. ++ ++@node Embedded Mode Overview, Other C-x * Commands, Standalone Operation, Using Calc ++@subsection Embedded Mode (Overview) ++ ++@noindent ++@dfn{Embedded mode} is a way to use Calc directly from inside an ++editing buffer. Suppose you have a formula written as part of a ++document like this: ++ ++@smallexample ++@group ++The derivative of ++ ++ ln(ln(x)) ++ ++is ++@end group ++@end smallexample ++ ++@noindent ++and you wish to have Calc compute and format the derivative for ++you and store this derivative in the buffer automatically. To ++do this with Embedded mode, first copy the formula down to where ++you want the result to be, leaving a blank line before and after the ++formula: ++ ++@smallexample ++@group ++The derivative of ++ ++ ln(ln(x)) ++ ++is ++ ++ ln(ln(x)) ++@end group ++@end smallexample ++ ++Now, move the cursor onto this new formula and press @kbd{C-x * e}. ++Calc will read the formula (using the surrounding blank lines to tell ++how much text to read), then push this formula (invisibly) onto the Calc ++stack. The cursor will stay on the formula in the editing buffer, but ++the line with the formula will now appear as it would on the Calc stack ++(in this case, it will be left-aligned) and the buffer's mode line will ++change to look like the Calc mode line (with mode indicators like ++@samp{12 Deg} and so on). Even though you are still in your editing ++buffer, the keyboard now acts like the Calc keyboard, and any new result ++you get is copied from the stack back into the buffer. To take the ++derivative, you would type @kbd{a d x @key{RET}}. ++ ++@smallexample ++@group ++The derivative of ++ ++ ln(ln(x)) ++ ++is ++ ++1 / ln(x) x ++@end group ++@end smallexample ++ ++(Note that by default, Calc gives division lower precedence than multiplication, ++so that @samp{1 / ln(x) x} is equivalent to @samp{1 / (ln(x) x)}.) ++ ++To make this look nicer, you might want to press @kbd{d =} to center ++the formula, and even @kbd{d B} to use Big display mode. ++ ++@smallexample ++@group ++The derivative of ++ ++ ln(ln(x)) ++ ++is ++% [calc-mode: justify: center] ++% [calc-mode: language: big] ++ ++ 1 ++ ------- ++ ln(x) x ++@end group ++@end smallexample ++ ++Calc has added annotations to the file to help it remember the modes ++that were used for this formula. They are formatted like comments ++in the @TeX{} typesetting language, just in case you are using @TeX{} or ++La@TeX{}. (In this example @TeX{} is not being used, so you might want ++to move these comments up to the top of the file or otherwise put them ++out of the way.) ++ ++As an extra flourish, we can add an equation number using a ++righthand label: Type @kbd{d @} (1) @key{RET}}. ++ ++@smallexample ++@group ++% [calc-mode: justify: center] ++% [calc-mode: language: big] ++% [calc-mode: right-label: " (1)"] ++ ++ 1 ++ ------- (1) ++ ln(x) x ++@end group ++@end smallexample ++ ++To leave Embedded mode, type @kbd{C-x * e} again. The mode line ++and keyboard will revert to the way they were before. ++ ++The related command @kbd{C-x * w} operates on a single word, which ++generally means a single number, inside text. It searches for an ++expression which ``looks'' like a number containing the point. ++Here's an example of its use: ++ ++@smallexample ++A slope of one-third corresponds to an angle of 1 degrees. ++@end smallexample ++ ++Place the cursor on the @samp{1}, then type @kbd{C-x * w} to enable ++Embedded mode on that number. Now type @kbd{3 /} (to get one-third), ++and @kbd{I T} (the Inverse Tangent converts a slope into an angle), ++then @w{@kbd{C-x * w}} again to exit Embedded mode. ++ ++@smallexample ++A slope of one-third corresponds to an angle of 18.4349488229 degrees. ++@end smallexample ++ ++@c [fix-ref Embedded Mode] ++@xref{Embedded Mode}, for full details. ++ ++@node Other C-x * Commands, , Embedded Mode Overview, Using Calc ++@subsection Other @kbd{C-x *} Commands ++ ++@noindent ++Two more Calc-related commands are @kbd{C-x * g} and @kbd{C-x * r}, ++which ``grab'' data from a selected region of a buffer into the ++Calculator. The region is defined in the usual Emacs way, by ++a ``mark'' placed at one end of the region, and the Emacs ++cursor or ``point'' placed at the other. ++ ++The @kbd{C-x * g} command reads the region in the usual left-to-right, ++top-to-bottom order. The result is packaged into a Calc vector ++of numbers and placed on the stack. Calc (in its standard ++user interface) is then started. Type @kbd{v u} if you want ++to unpack this vector into separate numbers on the stack. Also, ++@kbd{C-u C-x * g} interprets the region as a single number or ++formula. ++ ++The @kbd{C-x * r} command reads a rectangle, with the point and ++mark defining opposite corners of the rectangle. The result ++is a matrix of numbers on the Calculator stack. ++ ++Complementary to these is @kbd{C-x * y}, which ``yanks'' the ++value at the top of the Calc stack back into an editing buffer. ++If you type @w{@kbd{C-x * y}} while in such a buffer, the value is ++yanked at the current position. If you type @kbd{C-x * y} while ++in the Calc buffer, Calc makes an educated guess as to which ++editing buffer you want to use. The Calc window does not have ++to be visible in order to use this command, as long as there ++is something on the Calc stack. ++ ++Here, for reference, is the complete list of @kbd{C-x *} commands. ++The shift, control, and meta keys are ignored for the keystroke ++following @kbd{C-x *}. ++ ++@noindent ++Commands for turning Calc on and off: ++ ++@table @kbd ++@item * ++Turn Calc on or off, employing the same user interface as last time. ++ ++@item =, +, -, /, \, &, # ++Alternatives for @kbd{*}. ++ ++@item C ++Turn Calc on or off using its standard bottom-of-the-screen ++interface. If Calc is already turned on but the cursor is not ++in the Calc window, move the cursor into the window. ++ ++@item O ++Same as @kbd{C}, but don't select the new Calc window. If ++Calc is already turned on and the cursor is in the Calc window, ++move it out of that window. ++ ++@item B ++Control whether @kbd{C-x * c} and @kbd{C-x * k} use the full screen. ++ ++@item Q ++Use Quick mode for a single short calculation. ++ ++@item K ++Turn Calc Keypad mode on or off. ++ ++@item E ++Turn Calc Embedded mode on or off at the current formula. ++ ++@item J ++Turn Calc Embedded mode on or off, select the interesting part. ++ ++@item W ++Turn Calc Embedded mode on or off at the current word (number). ++ ++@item Z ++Turn Calc on in a user-defined way, as defined by a @kbd{Z I} command. ++ ++@item X ++Quit Calc; turn off standard, Keypad, or Embedded mode if on. ++(This is like @kbd{q} or @key{OFF} inside of Calc.) ++@end table ++@iftex ++@sp 2 ++@end iftex ++ ++@noindent ++Commands for moving data into and out of the Calculator: ++ ++@table @kbd ++@item G ++Grab the region into the Calculator as a vector. ++ ++@item R ++Grab the rectangular region into the Calculator as a matrix. ++ ++@item : ++Grab the rectangular region and compute the sums of its columns. ++ ++@item _ ++Grab the rectangular region and compute the sums of its rows. ++ ++@item Y ++Yank a value from the Calculator into the current editing buffer. ++@end table ++@iftex ++@sp 2 ++@end iftex ++ ++@noindent ++Commands for use with Embedded mode: ++ ++@table @kbd ++@item A ++``Activate'' the current buffer. Locate all formulas that ++contain @samp{:=} or @samp{=>} symbols and record their locations ++so that they can be updated automatically as variables are changed. ++ ++@item D ++Duplicate the current formula immediately below and select ++the duplicate. ++ ++@item F ++Insert a new formula at the current point. ++ ++@item N ++Move the cursor to the next active formula in the buffer. ++ ++@item P ++Move the cursor to the previous active formula in the buffer. ++ ++@item U ++Update (i.e., as if by the @kbd{=} key) the formula at the current point. ++ ++@item ` ++Edit (as if by @code{calc-edit}) the formula at the current point. ++@end table ++@iftex ++@sp 2 ++@end iftex ++ ++@noindent ++Miscellaneous commands: ++ ++@table @kbd ++@item I ++Run the Emacs Info system to read the Calc manual. ++(This is the same as @kbd{h i} inside of Calc.) ++ ++@item T ++Run the Emacs Info system to read the Calc Tutorial. ++ ++@item S ++Run the Emacs Info system to read the Calc Summary. ++ ++@item L ++Load Calc entirely into memory. (Normally the various parts ++are loaded only as they are needed.) ++ ++@item M ++Read a region of written keystroke names (like @kbd{C-n a b c @key{RET}}) ++and record them as the current keyboard macro. ++ ++@item 0 ++(This is the ``zero'' digit key.) Reset the Calculator to ++its initial state: Empty stack, and initial mode settings. ++@end table ++ ++@node History and Acknowledgements, , Using Calc, Getting Started ++@section History and Acknowledgements ++ ++@noindent ++Calc was originally started as a two-week project to occupy a lull ++in the author's schedule. Basically, a friend asked if I remembered ++the value of ++@texline @math{2^{32}}. ++@infoline @expr{2^32}. ++I didn't offhand, but I said, ``that's easy, just call up an ++@code{xcalc}.'' @code{Xcalc} duly reported that the answer to our ++question was @samp{4.294967e+09}---with no way to see the full ten ++digits even though we knew they were there in the program's memory! I ++was so annoyed, I vowed to write a calculator of my own, once and for ++all. ++ ++I chose Emacs Lisp, a) because I had always been curious about it ++and b) because, being only a text editor extension language after ++all, Emacs Lisp would surely reach its limits long before the project ++got too far out of hand. ++ ++To make a long story short, Emacs Lisp turned out to be a distressingly ++solid implementation of Lisp, and the humble task of calculating ++turned out to be more open-ended than one might have expected. ++ ++Emacs Lisp didn't have built-in floating point math (now it does), so ++this had to be simulated in software. In fact, Emacs integers would ++only comfortably fit six decimal digits or so---not enough for a decent ++calculator. So I had to write my own high-precision integer code as ++well, and once I had this I figured that arbitrary-size integers were ++just as easy as large integers. Arbitrary floating-point precision was ++the logical next step. Also, since the large integer arithmetic was ++there anyway it seemed only fair to give the user direct access to it, ++which in turn made it practical to support fractions as well as floats. ++All these features inspired me to look around for other data types that ++might be worth having. ++ ++Around this time, my friend Rick Koshi showed me his nifty new HP-28 ++calculator. It allowed the user to manipulate formulas as well as ++numerical quantities, and it could also operate on matrices. I ++decided that these would be good for Calc to have, too. And once ++things had gone this far, I figured I might as well take a look at ++serious algebra systems for further ideas. Since these systems did ++far more than I could ever hope to implement, I decided to focus on ++rewrite rules and other programming features so that users could ++implement what they needed for themselves. ++ ++Rick complained that matrices were hard to read, so I put in code to ++format them in a 2D style. Once these routines were in place, Big mode ++was obligatory. Gee, what other language modes would be useful? ++ ++Scott Hemphill and Allen Knutson, two friends with a strong mathematical ++bent, contributed ideas and algorithms for a number of Calc features ++including modulo forms, primality testing, and float-to-fraction conversion. ++ ++Units were added at the eager insistence of Mass Sivilotti. Later, ++Ulrich Mueller at CERN and Przemek Klosowski at NIST provided invaluable ++expert assistance with the units table. As far as I can remember, the ++idea of using algebraic formulas and variables to represent units dates ++back to an ancient article in Byte magazine about muMath, an early ++algebra system for microcomputers. ++ ++Many people have contributed to Calc by reporting bugs and suggesting ++features, large and small. A few deserve special mention: Tim Peters, ++who helped develop the ideas that led to the selection commands, rewrite ++rules, and many other algebra features; ++@texline Fran\c{c}ois ++@infoline Francois ++Pinard, who contributed an early prototype of the Calc Summary appendix ++as well as providing valuable suggestions in many other areas of Calc; ++Carl Witty, whose eagle eyes discovered many typographical and factual ++errors in the Calc manual; Tim Kay, who drove the development of ++Embedded mode; Ove Ewerlid, who made many suggestions relating to the ++algebra commands and contributed some code for polynomial operations; ++Randal Schwartz, who suggested the @code{calc-eval} function; Juha ++Sarlin, who first worked out how to split Calc into quickly-loading ++parts; Bob Weiner, who helped immensely with the Lucid Emacs port; and ++Robert J. Chassell, who suggested the Calc Tutorial and exercises as ++well as many other things. ++ ++@cindex Bibliography ++@cindex Knuth, Art of Computer Programming ++@cindex Numerical Recipes ++@c Should these be expanded into more complete references? ++Among the books used in the development of Calc were Knuth's @emph{Art ++of Computer Programming} (especially volume II, @emph{Seminumerical ++Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky, ++and Vetterling; Bevington's @emph{Data Reduction and Error Analysis ++for the Physical Sciences}; @emph{Concrete Mathematics} by Graham, ++Knuth, and Patashnik; Steele's @emph{Common Lisp, the Language}; the ++@emph{CRC Standard Math Tables} (William H. Beyer, ed.); and ++Abramowitz and Stegun's venerable @emph{Handbook of Mathematical ++Functions}. Also, of course, Calc could not have been written without ++the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil Lewis and ++Dan LaLiberte. ++ ++Final thanks go to Richard Stallman, without whose fine implementations ++of the Emacs editor, language, and environment, Calc would have been ++finished in two weeks. ++ ++@c [tutorial] ++ ++@ifinfo ++@c This node is accessed by the `C-x * t' command. ++@node Interactive Tutorial, Tutorial, Getting Started, Top ++@chapter Tutorial ++ ++@noindent ++Some brief instructions on using the Emacs Info system for this tutorial: ++ ++Press the space bar and Delete keys to go forward and backward in a ++section by screenfuls (or use the regular Emacs scrolling commands ++for this). ++ ++Press @kbd{n} or @kbd{p} to go to the Next or Previous section. ++If the section has a @dfn{menu}, press a digit key like @kbd{1} ++or @kbd{2} to go to a sub-section from the menu. Press @kbd{u} to ++go back up from a sub-section to the menu it is part of. ++ ++Exercises in the tutorial all have cross-references to the ++appropriate page of the ``answers'' section. Press @kbd{f}, then ++the exercise number, to see the answer to an exercise. After ++you have followed a cross-reference, you can press the letter ++@kbd{l} to return to where you were before. ++ ++You can press @kbd{?} at any time for a brief summary of Info commands. ++ ++Press the number @kbd{1} now to enter the first section of the Tutorial. ++ ++@menu ++* Tutorial:: ++@end menu ++ ++@node Tutorial, Introduction, Interactive Tutorial, Top ++@end ifinfo ++@ifnotinfo ++@node Tutorial, Introduction, Getting Started, Top ++@end ifnotinfo ++@chapter Tutorial ++ ++@noindent ++This chapter explains how to use Calc and its many features, in ++a step-by-step, tutorial way. You are encouraged to run Calc and ++work along with the examples as you read (@pxref{Starting Calc}). ++If you are already familiar with advanced calculators, you may wish ++@c [not-split] ++to skip on to the rest of this manual. ++@c [when-split] ++@c to skip on to volume II of this manual, the @dfn{Calc Reference}. ++ ++@c [fix-ref Embedded Mode] ++This tutorial describes the standard user interface of Calc only. ++The Quick mode and Keypad mode interfaces are fairly ++self-explanatory. @xref{Embedded Mode}, for a description of ++the Embedded mode interface. ++ ++The easiest way to read this tutorial on-line is to have two windows on ++your Emacs screen, one with Calc and one with the Info system. Press ++@kbd{C-x * t} to set this up; the on-line tutorial will be opened in the ++current window and Calc will be started in another window. From the ++Info window, the command @kbd{C-x * c} can be used to switch to the Calc ++window and @kbd{C-x * o} can be used to switch back to the Info window. ++(If you have a printed copy of the manual you can use that instead; in ++that case you only need to press @kbd{C-x * c} to start Calc.) ++ ++This tutorial is designed to be done in sequence. But the rest of this ++manual does not assume you have gone through the tutorial. The tutorial ++does not cover everything in the Calculator, but it touches on most ++general areas. ++ ++@ifnottex ++You may wish to print out a copy of the Calc Summary and keep notes on ++it as you learn Calc. @xref{About This Manual}, to see how to make a ++printed summary. @xref{Summary}. ++@end ifnottex ++@iftex ++The Calc Summary at the end of the reference manual includes some blank ++space for your own use. You may wish to keep notes there as you learn ++Calc. ++@end iftex ++ ++@menu ++* Basic Tutorial:: ++* Arithmetic Tutorial:: ++* Vector/Matrix Tutorial:: ++* Types Tutorial:: ++* Algebra Tutorial:: ++* Programming Tutorial:: ++ ++* Answers to Exercises:: ++@end menu ++ ++@node Basic Tutorial, Arithmetic Tutorial, Tutorial, Tutorial ++@section Basic Tutorial ++ ++@noindent ++In this section, we learn how RPN and algebraic-style calculations ++work, how to undo and redo an operation done by mistake, and how ++to control various modes of the Calculator. ++ ++@menu ++* RPN Tutorial:: Basic operations with the stack. ++* Algebraic Tutorial:: Algebraic entry; variables. ++* Undo Tutorial:: If you make a mistake: Undo and the trail. ++* Modes Tutorial:: Common mode-setting commands. ++@end menu ++ ++@node RPN Tutorial, Algebraic Tutorial, Basic Tutorial, Basic Tutorial ++@subsection RPN Calculations and the Stack ++ ++@cindex RPN notation ++@ifnottex ++@noindent ++Calc normally uses RPN notation. You may be familiar with the RPN ++system from Hewlett-Packard calculators, FORTH, or PostScript. ++(Reverse Polish Notation, RPN, is named after the Polish mathematician ++Jan Lukasiewicz.) ++@end ifnottex ++@tex ++\noindent ++Calc normally uses RPN notation. You may be familiar with the RPN ++system from Hewlett-Packard calculators, FORTH, or PostScript. ++(Reverse Polish Notation, RPN, is named after the Polish mathematician ++Jan \L ukasiewicz.) ++@end tex ++ ++The central component of an RPN calculator is the @dfn{stack}. A ++calculator stack is like a stack of dishes. New dishes (numbers) are ++added at the top of the stack, and numbers are normally only removed ++from the top of the stack. ++ ++@cindex Operators ++@cindex Operands ++In an operation like @expr{2+3}, the 2 and 3 are called the @dfn{operands} ++and the @expr{+} is the @dfn{operator}. In an RPN calculator you always ++enter the operands first, then the operator. Each time you type a ++number, Calc adds or @dfn{pushes} it onto the top of the Stack. ++When you press an operator key like @kbd{+}, Calc @dfn{pops} the appropriate ++number of operands from the stack and pushes back the result. ++ ++Thus we could add the numbers 2 and 3 in an RPN calculator by typing: ++@kbd{2 @key{RET} 3 @key{RET} +}. (The @key{RET} key, Return, corresponds to ++the @key{ENTER} key on traditional RPN calculators.) Try this now if ++you wish; type @kbd{C-x * c} to switch into the Calc window (you can type ++@kbd{C-x * c} again or @kbd{C-x * o} to switch back to the Tutorial window). ++The first four keystrokes ``push'' the numbers 2 and 3 onto the stack. ++The @kbd{+} key ``pops'' the top two numbers from the stack, adds them, ++and pushes the result (5) back onto the stack. Here's how the stack ++will look at various points throughout the calculation: ++ ++@smallexample ++@group ++ . 1: 2 2: 2 1: 5 . ++ . 1: 3 . ++ . ++ ++ C-x * c 2 @key{RET} 3 @key{RET} + @key{DEL} ++@end group ++@end smallexample ++ ++The @samp{.} symbol is a marker that represents the top of the stack. ++Note that the ``top'' of the stack is really shown at the bottom of ++the Stack window. This may seem backwards, but it turns out to be ++less distracting in regular use. ++ ++@cindex Stack levels ++@cindex Levels of stack ++The numbers @samp{1:} and @samp{2:} on the left are @dfn{stack level ++numbers}. Old RPN calculators always had four stack levels called ++@expr{x}, @expr{y}, @expr{z}, and @expr{t}. Calc's stack can grow ++as large as you like, so it uses numbers instead of letters. Some ++stack-manipulation commands accept a numeric argument that says ++which stack level to work on. Normal commands like @kbd{+} always ++work on the top few levels of the stack. ++ ++@c [fix-ref Truncating the Stack] ++The Stack buffer is just an Emacs buffer, and you can move around in ++it using the regular Emacs motion commands. But no matter where the ++cursor is, even if you have scrolled the @samp{.} marker out of ++view, most Calc commands always move the cursor back down to level 1 ++before doing anything. It is possible to move the @samp{.} marker ++upwards through the stack, temporarily ``hiding'' some numbers from ++commands like @kbd{+}. This is called @dfn{stack truncation} and ++we will not cover it in this tutorial; @pxref{Truncating the Stack}, ++if you are interested. ++ ++You don't really need the second @key{RET} in @kbd{2 @key{RET} 3 ++@key{RET} +}. That's because if you type any operator name or ++other non-numeric key when you are entering a number, the Calculator ++automatically enters that number and then does the requested command. ++Thus @kbd{2 @key{RET} 3 +} will work just as well. ++ ++Examples in this tutorial will often omit @key{RET} even when the ++stack displays shown would only happen if you did press @key{RET}: ++ ++@smallexample ++@group ++1: 2 2: 2 1: 5 ++ . 1: 3 . ++ . ++ ++ 2 @key{RET} 3 + ++@end group ++@end smallexample ++ ++@noindent ++Here, after pressing @kbd{3} the stack would really show @samp{1: 2} ++with @samp{Calc:@: 3} in the minibuffer. In these situations, you can ++press the optional @key{RET} to see the stack as the figure shows. ++ ++(@bullet{}) @strong{Exercise 1.} (This tutorial will include exercises ++at various points. Try them if you wish. Answers to all the exercises ++are located at the end of the Tutorial chapter. Each exercise will ++include a cross-reference to its particular answer. If you are ++reading with the Emacs Info system, press @kbd{f} and the ++exercise number to go to the answer, then the letter @kbd{l} to ++return to where you were.) ++ ++@noindent ++Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2 ++@key{RET} 3 @key{RET} 4 + * -} compute? (@samp{*} is the symbol for ++multiplication.) Figure it out by hand, then try it with Calc to see ++if you're right. @xref{RPN Answer 1, 1}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 2.} Compute ++@texline @math{(2\times4) + (7\times9.4) + {5\over4}} ++@infoline @expr{2*4 + 7*9.5 + 5/4} ++using the stack. @xref{RPN Answer 2, 2}. (@bullet{}) ++ ++The @key{DEL} key is called Backspace on some keyboards. It is ++whatever key you would use to correct a simple typing error when ++regularly using Emacs. The @key{DEL} key pops and throws away the ++top value on the stack. (You can still get that value back from ++the Trail if you should need it later on.) There are many places ++in this tutorial where we assume you have used @key{DEL} to erase the ++results of the previous example at the beginning of a new example. ++In the few places where it is really important to use @key{DEL} to ++clear away old results, the text will remind you to do so. ++ ++(It won't hurt to let things accumulate on the stack, except that ++whenever you give a display-mode-changing command Calc will have to ++spend a long time reformatting such a large stack.) ++ ++Since the @kbd{-} key is also an operator (it subtracts the top two ++stack elements), how does one enter a negative number? Calc uses ++the @kbd{_} (underscore) key to act like the minus sign in a number. ++So, typing @kbd{-5 @key{RET}} won't work because the @kbd{-} key ++will try to do a subtraction, but @kbd{_5 @key{RET}} works just fine. ++ ++You can also press @kbd{n}, which means ``change sign.'' It changes ++the number at the top of the stack (or the number being entered) ++from positive to negative or vice-versa: @kbd{5 n @key{RET}}. ++ ++@cindex Duplicating a stack entry ++If you press @key{RET} when you're not entering a number, the effect ++is to duplicate the top number on the stack. Consider this calculation: ++ ++@smallexample ++@group ++1: 3 2: 3 1: 9 2: 9 1: 81 ++ . 1: 3 . 1: 9 . ++ . . ++ ++ 3 @key{RET} @key{RET} * @key{RET} * ++@end group ++@end smallexample ++ ++@noindent ++(Of course, an easier way to do this would be @kbd{3 @key{RET} 4 ^}, ++to raise 3 to the fourth power.) ++ ++The space-bar key (denoted @key{SPC} here) performs the same function ++as @key{RET}; you could replace all three occurrences of @key{RET} in ++the above example with @key{SPC} and the effect would be the same. ++ ++@cindex Exchanging stack entries ++Another stack manipulation key is @key{TAB}. This exchanges the top ++two stack entries. Suppose you have computed @kbd{2 @key{RET} 3 +} ++to get 5, and then you realize what you really wanted to compute ++was @expr{20 / (2+3)}. ++ ++@smallexample ++@group ++1: 5 2: 5 2: 20 1: 4 ++ . 1: 20 1: 5 . ++ . . ++ ++ 2 @key{RET} 3 + 20 @key{TAB} / ++@end group ++@end smallexample ++ ++@noindent ++Planning ahead, the calculation would have gone like this: ++ ++@smallexample ++@group ++1: 20 2: 20 3: 20 2: 20 1: 4 ++ . 1: 2 2: 2 1: 5 . ++ . 1: 3 . ++ . ++ ++ 20 @key{RET} 2 @key{RET} 3 + / ++@end group ++@end smallexample ++ ++A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type ++@key{TAB}). It rotates the top three elements of the stack upward, ++bringing the object in level 3 to the top. ++ ++@smallexample ++@group ++1: 10 2: 10 3: 10 3: 20 3: 30 ++ . 1: 20 2: 20 2: 30 2: 10 ++ . 1: 30 1: 10 1: 20 ++ . . . ++ ++ 10 @key{RET} 20 @key{RET} 30 @key{RET} M-@key{TAB} M-@key{TAB} ++@end group ++@end smallexample ++ ++(@bullet{}) @strong{Exercise 3.} Suppose the numbers 10, 20, and 30 are ++on the stack. Figure out how to add one to the number in level 2 ++without affecting the rest of the stack. Also figure out how to add ++one to the number in level 3. @xref{RPN Answer 3, 3}. (@bullet{}) ++ ++Operations like @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, and @kbd{^} pop two ++arguments from the stack and push a result. Operations like @kbd{n} and ++@kbd{Q} (square root) pop a single number and push the result. You can ++think of them as simply operating on the top element of the stack. ++ ++@smallexample ++@group ++1: 3 1: 9 2: 9 1: 25 1: 5 ++ . . 1: 16 . . ++ . ++ ++ 3 @key{RET} @key{RET} * 4 @key{RET} @key{RET} * + Q ++@end group ++@end smallexample ++ ++@noindent ++(Note that capital @kbd{Q} means to hold down the Shift key while ++typing @kbd{q}. Remember, plain unshifted @kbd{q} is the Quit command.) ++ ++@cindex Pythagorean Theorem ++Here we've used the Pythagorean Theorem to determine the hypotenuse of a ++right triangle. Calc actually has a built-in command for that called ++@kbd{f h}, but let's suppose we can't remember the necessary keystrokes. ++We can still enter it by its full name using @kbd{M-x} notation: ++ ++@smallexample ++@group ++1: 3 2: 3 1: 5 ++ . 1: 4 . ++ . ++ ++ 3 @key{RET} 4 @key{RET} M-x calc-hypot ++@end group ++@end smallexample ++ ++All Calculator commands begin with the word @samp{calc-}. Since it ++gets tiring to type this, Calc provides an @kbd{x} key which is just ++like the regular Emacs @kbd{M-x} key except that it types the @samp{calc-} ++prefix for you: ++ ++@smallexample ++@group ++1: 3 2: 3 1: 5 ++ . 1: 4 . ++ . ++ ++ 3 @key{RET} 4 @key{RET} x hypot ++@end group ++@end smallexample ++ ++What happens if you take the square root of a negative number? ++ ++@smallexample ++@group ++1: 4 1: -4 1: (0, 2) ++ . . . ++ ++ 4 @key{RET} n Q ++@end group ++@end smallexample ++ ++@noindent ++The notation @expr{(a, b)} represents a complex number. ++Complex numbers are more traditionally written @expr{a + b i}; ++Calc can display in this format, too, but for now we'll stick to the ++@expr{(a, b)} notation. ++ ++If you don't know how complex numbers work, you can safely ignore this ++feature. Complex numbers only arise from operations that would be ++errors in a calculator that didn't have complex numbers. (For example, ++taking the square root or logarithm of a negative number produces a ++complex result.) ++ ++Complex numbers are entered in the notation shown. The @kbd{(} and ++@kbd{,} and @kbd{)} keys manipulate ``incomplete complex numbers.'' ++ ++@smallexample ++@group ++1: ( ... 2: ( ... 1: (2, ... 1: (2, ... 1: (2, 3) ++ . 1: 2 . 3 . ++ . . ++ ++ ( 2 , 3 ) ++@end group ++@end smallexample ++ ++You can perform calculations while entering parts of incomplete objects. ++However, an incomplete object cannot actually participate in a calculation: ++ ++@smallexample ++@group ++1: ( ... 2: ( ... 3: ( ... 1: ( ... 1: ( ... ++ . 1: 2 2: 2 5 5 ++ . 1: 3 . . ++ . ++ (error) ++ ( 2 @key{RET} 3 + + ++@end group ++@end smallexample ++ ++@noindent ++Adding 5 to an incomplete object makes no sense, so the last command ++produces an error message and leaves the stack the same. ++ ++Incomplete objects can't participate in arithmetic, but they can be ++moved around by the regular stack commands. ++ ++@smallexample ++@group ++2: 2 3: 2 3: 3 1: ( ... 1: (2, 3) ++1: 3 2: 3 2: ( ... 2 . ++ . 1: ( ... 1: 2 3 ++ . . . ++ ++2 @key{RET} 3 @key{RET} ( M-@key{TAB} M-@key{TAB} ) ++@end group ++@end smallexample ++ ++@noindent ++Note that the @kbd{,} (comma) key did not have to be used here. ++When you press @kbd{)} all the stack entries between the incomplete ++entry and the top are collected, so there's never really a reason ++to use the comma. It's up to you. ++ ++(@bullet{}) @strong{Exercise 4.} To enter the complex number @expr{(2, 3)}, ++your friend Joe typed @kbd{( 2 , @key{SPC} 3 )}. What happened? ++(Joe thought of a clever way to correct his mistake in only two ++keystrokes, but it didn't quite work. Try it to find out why.) ++@xref{RPN Answer 4, 4}. (@bullet{}) ++ ++Vectors are entered the same way as complex numbers, but with square ++brackets in place of parentheses. We'll meet vectors again later in ++the tutorial. ++ ++Any Emacs command can be given a @dfn{numeric prefix argument} by ++typing a series of @key{META}-digits beforehand. If @key{META} is ++awkward for you, you can instead type @kbd{C-u} followed by the ++necessary digits. Numeric prefix arguments can be negative, as in ++@kbd{M-- M-3 M-5} or @w{@kbd{C-u - 3 5}}. Calc commands use numeric ++prefix arguments in a variety of ways. For example, a numeric prefix ++on the @kbd{+} operator adds any number of stack entries at once: ++ ++@smallexample ++@group ++1: 10 2: 10 3: 10 3: 10 1: 60 ++ . 1: 20 2: 20 2: 20 . ++ . 1: 30 1: 30 ++ . . ++ ++ 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u 3 + ++@end group ++@end smallexample ++ ++For stack manipulation commands like @key{RET}, a positive numeric ++prefix argument operates on the top @var{n} stack entries at once. A ++negative argument operates on the entry in level @var{n} only. An ++argument of zero operates on the entire stack. In this example, we copy ++the second-to-top element of the stack: ++ ++@smallexample ++@group ++1: 10 2: 10 3: 10 3: 10 4: 10 ++ . 1: 20 2: 20 2: 20 3: 20 ++ . 1: 30 1: 30 2: 30 ++ . . 1: 20 ++ . ++ ++ 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u -2 @key{RET} ++@end group ++@end smallexample ++ ++@cindex Clearing the stack ++@cindex Emptying the stack ++Another common idiom is @kbd{M-0 @key{DEL}}, which clears the stack. ++(The @kbd{M-0} numeric prefix tells @key{DEL} to operate on the ++entire stack.) ++ ++@node Algebraic Tutorial, Undo Tutorial, RPN Tutorial, Basic Tutorial ++@subsection Algebraic-Style Calculations ++ ++@noindent ++If you are not used to RPN notation, you may prefer to operate the ++Calculator in Algebraic mode, which is closer to the way ++non-RPN calculators work. In Algebraic mode, you enter formulas ++in traditional @expr{2+3} notation. ++ ++@strong{Notice:} Calc gives @samp{/} lower precedence than @samp{*}, so ++that @samp{a/b*c} is interpreted as @samp{a/(b*c)}; this is not ++standard across all computer languages. See below for details. ++ ++You don't really need any special ``mode'' to enter algebraic formulas. ++You can enter a formula at any time by pressing the apostrophe (@kbd{'}) ++key. Answer the prompt with the desired formula, then press @key{RET}. ++The formula is evaluated and the result is pushed onto the RPN stack. ++If you don't want to think in RPN at all, you can enter your whole ++computation as a formula, read the result from the stack, then press ++@key{DEL} to delete it from the stack. ++ ++Try pressing the apostrophe key, then @kbd{2+3+4}, then @key{RET}. ++The result should be the number 9. ++ ++Algebraic formulas use the operators @samp{+}, @samp{-}, @samp{*}, ++@samp{/}, and @samp{^}. You can use parentheses to make the order ++of evaluation clear. In the absence of parentheses, @samp{^} is ++evaluated first, then @samp{*}, then @samp{/}, then finally ++@samp{+} and @samp{-}. For example, the expression ++ ++@example ++2 + 3*4*5 / 6*7^8 - 9 ++@end example ++ ++@noindent ++is equivalent to ++ ++@example ++2 + ((3*4*5) / (6*(7^8)) - 9 ++@end example ++ ++@noindent ++or, in large mathematical notation, ++ ++@ifnottex ++@example ++@group ++ 3 * 4 * 5 ++2 + --------- - 9 ++ 8 ++ 6 * 7 ++@end group ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$ ++\afterdisplay ++@end tex ++ ++@noindent ++The result of this expression will be the number @mathit{-6.99999826533}. ++ ++Calc's order of evaluation is the same as for most computer languages, ++except that @samp{*} binds more strongly than @samp{/}, as the above ++example shows. As in normal mathematical notation, the @samp{*} symbol ++can often be omitted: @samp{2 a} is the same as @samp{2*a}. ++ ++Operators at the same level are evaluated from left to right, except ++that @samp{^} is evaluated from right to left. Thus, @samp{2-3-4} is ++equivalent to @samp{(2-3)-4} or @mathit{-5}, whereas @samp{2^3^4} is equivalent ++to @samp{2^(3^4)} (a very large integer; try it!). ++ ++If you tire of typing the apostrophe all the time, there is ++Algebraic mode, where Calc automatically senses ++when you are about to type an algebraic expression. To enter this ++mode, press the two letters @w{@kbd{m a}}. (An @samp{Alg} indicator ++should appear in the Calc window's mode line.) ++ ++Press @kbd{m a}, then @kbd{2+3+4} with no apostrophe, then @key{RET}. ++ ++In Algebraic mode, when you press any key that would normally begin ++entering a number (such as a digit, a decimal point, or the @kbd{_} ++key), or if you press @kbd{(} or @kbd{[}, Calc automatically begins ++an algebraic entry. ++ ++Functions which do not have operator symbols like @samp{+} and @samp{*} ++must be entered in formulas using function-call notation. For example, ++the function name corresponding to the square-root key @kbd{Q} is ++@code{sqrt}. To compute a square root in a formula, you would use ++the notation @samp{sqrt(@var{x})}. ++ ++Press the apostrophe, then type @kbd{sqrt(5*2) - 3}. The result should ++be @expr{0.16227766017}. ++ ++Note that if the formula begins with a function name, you need to use ++the apostrophe even if you are in Algebraic mode. If you type @kbd{arcsin} ++out of the blue, the @kbd{a r} will be taken as an Algebraic Rewrite ++command, and the @kbd{csin} will be taken as the name of the rewrite ++rule to use! ++ ++Some people prefer to enter complex numbers and vectors in algebraic ++form because they find RPN entry with incomplete objects to be too ++distracting, even though they otherwise use Calc as an RPN calculator. ++ ++Still in Algebraic mode, type: ++ ++@smallexample ++@group ++1: (2, 3) 2: (2, 3) 1: (8, -1) 2: (8, -1) 1: (9, -1) ++ . 1: (1, -2) . 1: 1 . ++ . . ++ ++ (2,3) @key{RET} (1,-2) @key{RET} * 1 @key{RET} + ++@end group ++@end smallexample ++ ++Algebraic mode allows us to enter complex numbers without pressing ++an apostrophe first, but it also means we need to press @key{RET} ++after every entry, even for a simple number like @expr{1}. ++ ++(You can type @kbd{C-u m a} to enable a special Incomplete Algebraic ++mode in which the @kbd{(} and @kbd{[} keys use algebraic entry even ++though regular numeric keys still use RPN numeric entry. There is also ++Total Algebraic mode, started by typing @kbd{m t}, in which all ++normal keys begin algebraic entry. You must then use the @key{META} key ++to type Calc commands: @kbd{M-m t} to get back out of Total Algebraic ++mode, @kbd{M-q} to quit, etc.) ++ ++If you're still in Algebraic mode, press @kbd{m a} again to turn it off. ++ ++Actual non-RPN calculators use a mixture of algebraic and RPN styles. ++In general, operators of two numbers (like @kbd{+} and @kbd{*}) ++use algebraic form, but operators of one number (like @kbd{n} and @kbd{Q}) ++use RPN form. Also, a non-RPN calculator allows you to see the ++intermediate results of a calculation as you go along. You can ++accomplish this in Calc by performing your calculation as a series ++of algebraic entries, using the @kbd{$} sign to tie them together. ++In an algebraic formula, @kbd{$} represents the number on the top ++of the stack. Here, we perform the calculation ++@texline @math{\sqrt{2\times4+1}}, ++@infoline @expr{sqrt(2*4+1)}, ++which on a traditional calculator would be done by pressing ++@kbd{2 * 4 + 1 =} and then the square-root key. ++ ++@smallexample ++@group ++1: 8 1: 9 1: 3 ++ . . . ++ ++ ' 2*4 @key{RET} $+1 @key{RET} Q ++@end group ++@end smallexample ++ ++@noindent ++Notice that we didn't need to press an apostrophe for the @kbd{$+1}, ++because the dollar sign always begins an algebraic entry. ++ ++(@bullet{}) @strong{Exercise 1.} How could you get the same effect as ++pressing @kbd{Q} but using an algebraic entry instead? How about ++if the @kbd{Q} key on your keyboard were broken? ++@xref{Algebraic Answer 1, 1}. (@bullet{}) ++ ++The notations @kbd{$$}, @kbd{$$$}, and so on stand for higher stack ++entries. For example, @kbd{' $$+$ @key{RET}} is just like typing @kbd{+}. ++ ++Algebraic formulas can include @dfn{variables}. To store in a ++variable, press @kbd{s s}, then type the variable name, then press ++@key{RET}. (There are actually two flavors of store command: ++@kbd{s s} stores a number in a variable but also leaves the number ++on the stack, while @w{@kbd{s t}} removes a number from the stack and ++stores it in the variable.) A variable name should consist of one ++or more letters or digits, beginning with a letter. ++ ++@smallexample ++@group ++1: 17 . 1: a + a^2 1: 306 ++ . . . ++ ++ 17 s t a @key{RET} ' a+a^2 @key{RET} = ++@end group ++@end smallexample ++ ++@noindent ++The @kbd{=} key @dfn{evaluates} a formula by replacing all its ++variables by the values that were stored in them. ++ ++For RPN calculations, you can recall a variable's value on the ++stack either by entering its name as a formula and pressing @kbd{=}, ++or by using the @kbd{s r} command. ++ ++@smallexample ++@group ++1: 17 2: 17 3: 17 2: 17 1: 306 ++ . 1: 17 2: 17 1: 289 . ++ . 1: 2 . ++ . ++ ++ s r a @key{RET} ' a @key{RET} = 2 ^ + ++@end group ++@end smallexample ++ ++If you press a single digit for a variable name (as in @kbd{s t 3}, you ++get one of ten @dfn{quick variables} @code{q0} through @code{q9}. ++They are ``quick'' simply because you don't have to type the letter ++@code{q} or the @key{RET} after their names. In fact, you can type ++simply @kbd{s 3} as a shorthand for @kbd{s s 3}, and likewise for ++@kbd{t 3} and @w{@kbd{r 3}}. ++ ++Any variables in an algebraic formula for which you have not stored ++values are left alone, even when you evaluate the formula. ++ ++@smallexample ++@group ++1: 2 a + 2 b 1: 34 + 2 b ++ . . ++ ++ ' 2a+2b @key{RET} = ++@end group ++@end smallexample ++ ++Calls to function names which are undefined in Calc are also left ++alone, as are calls for which the value is undefined. ++ ++@smallexample ++@group ++1: 2 + log10(0) + log10(x) + log10(5, 6) + foo(3) ++ . ++ ++ ' log10(100) + log10(0) + log10(x) + log10(5,6) + foo(3) @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++In this example, the first call to @code{log10} works, but the other ++calls are not evaluated. In the second call, the logarithm is ++undefined for that value of the argument; in the third, the argument ++is symbolic, and in the fourth, there are too many arguments. In the ++fifth case, there is no function called @code{foo}. You will see a ++``Wrong number of arguments'' message referring to @samp{log10(5,6)}. ++Press the @kbd{w} (``why'') key to see any other messages that may ++have arisen from the last calculation. In this case you will get ++``logarithm of zero,'' then ``number expected: @code{x}''. Calc ++automatically displays the first message only if the message is ++sufficiently important; for example, Calc considers ``wrong number ++of arguments'' and ``logarithm of zero'' to be important enough to ++report automatically, while a message like ``number expected: @code{x}'' ++will only show up if you explicitly press the @kbd{w} key. ++ ++(@bullet{}) @strong{Exercise 2.} Joe entered the formula @samp{2 x y}, ++stored 5 in @code{x}, pressed @kbd{=}, and got the expected result, ++@samp{10 y}. He then tried the same for the formula @samp{2 x (1+y)}, ++expecting @samp{10 (1+y)}, but it didn't work. Why not? ++@xref{Algebraic Answer 2, 2}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 3.} What result would you expect ++@kbd{1 @key{RET} 0 /} to give? What if you then type @kbd{0 *}? ++@xref{Algebraic Answer 3, 3}. (@bullet{}) ++ ++One interesting way to work with variables is to use the ++@dfn{evaluates-to} (@samp{=>}) operator. It works like this: ++Enter a formula algebraically in the usual way, but follow ++the formula with an @samp{=>} symbol. (There is also an @kbd{s =} ++command which builds an @samp{=>} formula using the stack.) On ++the stack, you will see two copies of the formula with an @samp{=>} ++between them. The lefthand formula is exactly like you typed it; ++the righthand formula has been evaluated as if by typing @kbd{=}. ++ ++@smallexample ++@group ++2: 2 + 3 => 5 2: 2 + 3 => 5 ++1: 2 a + 2 b => 34 + 2 b 1: 2 a + 2 b => 20 + 2 b ++ . . ++ ++' 2+3 => @key{RET} ' 2a+2b @key{RET} s = 10 s t a @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++Notice that the instant we stored a new value in @code{a}, all ++@samp{=>} operators already on the stack that referred to @expr{a} ++were updated to use the new value. With @samp{=>}, you can push a ++set of formulas on the stack, then change the variables experimentally ++to see the effects on the formulas' values. ++ ++You can also ``unstore'' a variable when you are through with it: ++ ++@smallexample ++@group ++2: 2 + 5 => 5 ++1: 2 a + 2 b => 2 a + 2 b ++ . ++ ++ s u a @key{RET} ++@end group ++@end smallexample ++ ++We will encounter formulas involving variables and functions again ++when we discuss the algebra and calculus features of the Calculator. ++ ++@node Undo Tutorial, Modes Tutorial, Algebraic Tutorial, Basic Tutorial ++@subsection Undo and Redo ++ ++@noindent ++If you make a mistake, you can usually correct it by pressing shift-@kbd{U}, ++the ``undo'' command. First, clear the stack (@kbd{M-0 @key{DEL}}) and exit ++and restart Calc (@kbd{C-x * * C-x * *}) to make sure things start off ++with a clean slate. Now: ++ ++@smallexample ++@group ++1: 2 2: 2 1: 8 2: 2 1: 6 ++ . 1: 3 . 1: 3 . ++ . . ++ ++ 2 @key{RET} 3 ^ U * ++@end group ++@end smallexample ++ ++You can undo any number of times. Calc keeps a complete record of ++all you have done since you last opened the Calc window. After the ++above example, you could type: ++ ++@smallexample ++@group ++1: 6 2: 2 1: 2 . . ++ . 1: 3 . ++ . ++ (error) ++ U U U U ++@end group ++@end smallexample ++ ++You can also type @kbd{D} to ``redo'' a command that you have undone ++mistakenly. ++ ++@smallexample ++@group ++ . 1: 2 2: 2 1: 6 1: 6 ++ . 1: 3 . . ++ . ++ (error) ++ D D D D ++@end group ++@end smallexample ++ ++@noindent ++It was not possible to redo past the @expr{6}, since that was placed there ++by something other than an undo command. ++ ++@cindex Time travel ++You can think of undo and redo as a sort of ``time machine.'' Press ++@kbd{U} to go backward in time, @kbd{D} to go forward. If you go ++backward and do something (like @kbd{*}) then, as any science fiction ++reader knows, you have changed your future and you cannot go forward ++again. Thus, the inability to redo past the @expr{6} even though there ++was an earlier undo command. ++ ++You can always recall an earlier result using the Trail. We've ignored ++the trail so far, but it has been faithfully recording everything we ++did since we loaded the Calculator. If the Trail is not displayed, ++press @kbd{t d} now to turn it on. ++ ++Let's try grabbing an earlier result. The @expr{8} we computed was ++undone by a @kbd{U} command, and was lost even to Redo when we pressed ++@kbd{*}, but it's still there in the trail. There should be a little ++@samp{>} arrow (the @dfn{trail pointer}) resting on the last trail ++entry. If there isn't, press @kbd{t ]} to reset the trail pointer. ++Now, press @w{@kbd{t p}} to move the arrow onto the line containing ++@expr{8}, and press @w{@kbd{t y}} to ``yank'' that number back onto the ++stack. ++ ++If you press @kbd{t ]} again, you will see that even our Yank command ++went into the trail. ++ ++Let's go further back in time. Earlier in the tutorial we computed ++a huge integer using the formula @samp{2^3^4}. We don't remember ++what it was, but the first digits were ``241''. Press @kbd{t r} ++(which stands for trail-search-reverse), then type @kbd{241}. ++The trail cursor will jump back to the next previous occurrence of ++the string ``241'' in the trail. This is just a regular Emacs ++incremental search; you can now press @kbd{C-s} or @kbd{C-r} to ++continue the search forwards or backwards as you like. ++ ++To finish the search, press @key{RET}. This halts the incremental ++search and leaves the trail pointer at the thing we found. Now we ++can type @kbd{t y} to yank that number onto the stack. If we hadn't ++remembered the ``241'', we could simply have searched for @kbd{2^3^4}, ++then pressed @kbd{@key{RET} t n} to halt and then move to the next item. ++ ++You may have noticed that all the trail-related commands begin with ++the letter @kbd{t}. (The store-and-recall commands, on the other hand, ++all began with @kbd{s}.) Calc has so many commands that there aren't ++enough keys for all of them, so various commands are grouped into ++two-letter sequences where the first letter is called the @dfn{prefix} ++key. If you type a prefix key by accident, you can press @kbd{C-g} ++to cancel it. (In fact, you can press @kbd{C-g} to cancel almost ++anything in Emacs.) To get help on a prefix key, press that key ++followed by @kbd{?}. Some prefixes have several lines of help, ++so you need to press @kbd{?} repeatedly to see them all. ++You can also type @kbd{h h} to see all the help at once. ++ ++Try pressing @kbd{t ?} now. You will see a line of the form, ++ ++@smallexample ++trail/time: Display; Fwd, Back; Next, Prev, Here, [, ]; Yank: [MORE] t- ++@end smallexample ++ ++@noindent ++The word ``trail'' indicates that the @kbd{t} prefix key contains ++trail-related commands. Each entry on the line shows one command, ++with a single capital letter showing which letter you press to get ++that command. We have used @kbd{t n}, @kbd{t p}, @kbd{t ]}, and ++@kbd{t y} so far. The @samp{[MORE]} means you can press @kbd{?} ++again to see more @kbd{t}-prefix commands. Notice that the commands ++are roughly divided (by semicolons) into related groups. ++ ++When you are in the help display for a prefix key, the prefix is ++still active. If you press another key, like @kbd{y} for example, ++it will be interpreted as a @kbd{t y} command. If all you wanted ++was to look at the help messages, press @kbd{C-g} afterwards to cancel ++the prefix. ++ ++One more way to correct an error is by editing the stack entries. ++The actual Stack buffer is marked read-only and must not be edited ++directly, but you can press @kbd{`} (the backquote or accent grave) ++to edit a stack entry. ++ ++Try entering @samp{3.141439} now. If this is supposed to represent ++@cpi{}, it's got several errors. Press @kbd{`} to edit this number. ++Now use the normal Emacs cursor motion and editing keys to change ++the second 4 to a 5, and to transpose the 3 and the 9. When you ++press @key{RET}, the number on the stack will be replaced by your ++new number. This works for formulas, vectors, and all other types ++of values you can put on the stack. The @kbd{`} key also works ++during entry of a number or algebraic formula. ++ ++@node Modes Tutorial, , Undo Tutorial, Basic Tutorial ++@subsection Mode-Setting Commands ++ ++@noindent ++Calc has many types of @dfn{modes} that affect the way it interprets ++your commands or the way it displays data. We have already seen one ++mode, namely Algebraic mode. There are many others, too; we'll ++try some of the most common ones here. ++ ++Perhaps the most fundamental mode in Calc is the current @dfn{precision}. ++Notice the @samp{12} on the Calc window's mode line: ++ ++@smallexample ++--%*-Calc: 12 Deg (Calculator)----All------ ++@end smallexample ++ ++@noindent ++Most of the symbols there are Emacs things you don't need to worry ++about, but the @samp{12} and the @samp{Deg} are mode indicators. ++The @samp{12} means that calculations should always be carried to ++12 significant figures. That is why, when we type @kbd{1 @key{RET} 7 /}, ++we get @expr{0.142857142857} with exactly 12 digits, not counting ++leading and trailing zeros. ++ ++You can set the precision to anything you like by pressing @kbd{p}, ++then entering a suitable number. Try pressing @kbd{p 30 @key{RET}}, ++then doing @kbd{1 @key{RET} 7 /} again: ++ ++@smallexample ++@group ++1: 0.142857142857 ++2: 0.142857142857142857142857142857 ++ . ++@end group ++@end smallexample ++ ++Although the precision can be set arbitrarily high, Calc always ++has to have @emph{some} value for the current precision. After ++all, the true value @expr{1/7} is an infinitely repeating decimal; ++Calc has to stop somewhere. ++ ++Of course, calculations are slower the more digits you request. ++Press @w{@kbd{p 12}} now to set the precision back down to the default. ++ ++Calculations always use the current precision. For example, even ++though we have a 30-digit value for @expr{1/7} on the stack, if ++we use it in a calculation in 12-digit mode it will be rounded ++down to 12 digits before it is used. Try it; press @key{RET} to ++duplicate the number, then @w{@kbd{1 +}}. Notice that the @key{RET} ++key didn't round the number, because it doesn't do any calculation. ++But the instant we pressed @kbd{+}, the number was rounded down. ++ ++@smallexample ++@group ++1: 0.142857142857 ++2: 0.142857142857142857142857142857 ++3: 1.14285714286 ++ . ++@end group ++@end smallexample ++ ++@noindent ++In fact, since we added a digit on the left, we had to lose one ++digit on the right from even the 12-digit value of @expr{1/7}. ++ ++How did we get more than 12 digits when we computed @samp{2^3^4}? The ++answer is that Calc makes a distinction between @dfn{integers} and ++@dfn{floating-point} numbers, or @dfn{floats}. An integer is a number ++that does not contain a decimal point. There is no such thing as an ++``infinitely repeating fraction integer,'' so Calc doesn't have to limit ++itself. If you asked for @samp{2^10000} (don't try this!), you would ++have to wait a long time but you would eventually get an exact answer. ++If you ask for @samp{2.^10000}, you will quickly get an answer which is ++correct only to 12 places. The decimal point tells Calc that it should ++use floating-point arithmetic to get the answer, not exact integer ++arithmetic. ++ ++You can use the @kbd{F} (@code{calc-floor}) command to convert a ++floating-point value to an integer, and @kbd{c f} (@code{calc-float}) ++to convert an integer to floating-point form. ++ ++Let's try entering that last calculation: ++ ++@smallexample ++@group ++1: 2. 2: 2. 1: 1.99506311689e3010 ++ . 1: 10000 . ++ . ++ ++ 2.0 @key{RET} 10000 @key{RET} ^ ++@end group ++@end smallexample ++ ++@noindent ++@cindex Scientific notation, entry of ++Notice the letter @samp{e} in there. It represents ``times ten to the ++power of,'' and is used by Calc automatically whenever writing the ++number out fully would introduce more extra zeros than you probably ++want to see. You can enter numbers in this notation, too. ++ ++@smallexample ++@group ++1: 2. 2: 2. 1: 1.99506311678e3010 ++ . 1: 10000. . ++ . ++ ++ 2.0 @key{RET} 1e4 @key{RET} ^ ++@end group ++@end smallexample ++ ++@cindex Round-off errors ++@noindent ++Hey, the answer is different! Look closely at the middle columns ++of the two examples. In the first, the stack contained the ++exact integer @expr{10000}, but in the second it contained ++a floating-point value with a decimal point. When you raise a ++number to an integer power, Calc uses repeated squaring and ++multiplication to get the answer. When you use a floating-point ++power, Calc uses logarithms and exponentials. As you can see, ++a slight error crept in during one of these methods. Which ++one should we trust? Let's raise the precision a bit and find ++out: ++ ++@smallexample ++@group ++ . 1: 2. 2: 2. 1: 1.995063116880828e3010 ++ . 1: 10000. . ++ . ++ ++ p 16 @key{RET} 2. @key{RET} 1e4 ^ p 12 @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++@cindex Guard digits ++Presumably, it doesn't matter whether we do this higher-precision ++calculation using an integer or floating-point power, since we ++have added enough ``guard digits'' to trust the first 12 digits ++no matter what. And the verdict is@dots{} Integer powers were more ++accurate; in fact, the result was only off by one unit in the ++last place. ++ ++@cindex Guard digits ++Calc does many of its internal calculations to a slightly higher ++precision, but it doesn't always bump the precision up enough. ++In each case, Calc added about two digits of precision during ++its calculation and then rounded back down to 12 digits ++afterward. In one case, it was enough; in the other, it ++wasn't. If you really need @var{x} digits of precision, it ++never hurts to do the calculation with a few extra guard digits. ++ ++What if we want guard digits but don't want to look at them? ++We can set the @dfn{float format}. Calc supports four major ++formats for floating-point numbers, called @dfn{normal}, ++@dfn{fixed-point}, @dfn{scientific notation}, and @dfn{engineering ++notation}. You get them by pressing @w{@kbd{d n}}, @kbd{d f}, ++@kbd{d s}, and @kbd{d e}, respectively. In each case, you can ++supply a numeric prefix argument which says how many digits ++should be displayed. As an example, let's put a few numbers ++onto the stack and try some different display modes. First, ++use @kbd{M-0 @key{DEL}} to clear the stack, then enter the four ++numbers shown here: ++ ++@smallexample ++@group ++4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 ++3: 12345. 3: 12300. 3: 1.2345e4 3: 1.23e4 3: 12345.000 ++2: 123.45 2: 123. 2: 1.2345e2 2: 1.23e2 2: 123.450 ++1: 12.345 1: 12.3 1: 1.2345e1 1: 1.23e1 1: 12.345 ++ . . . . . ++ ++ d n M-3 d n d s M-3 d s M-3 d f ++@end group ++@end smallexample ++ ++@noindent ++Notice that when we typed @kbd{M-3 d n}, the numbers were rounded down ++to three significant digits, but then when we typed @kbd{d s} all ++five significant figures reappeared. The float format does not ++affect how numbers are stored, it only affects how they are ++displayed. Only the current precision governs the actual rounding ++of numbers in the Calculator's memory. ++ ++Engineering notation, not shown here, is like scientific notation ++except the exponent (the power-of-ten part) is always adjusted to be ++a multiple of three (as in ``kilo,'' ``micro,'' etc.). As a result ++there will be one, two, or three digits before the decimal point. ++ ++Whenever you change a display-related mode, Calc redraws everything ++in the stack. This may be slow if there are many things on the stack, ++so Calc allows you to type shift-@kbd{H} before any mode command to ++prevent it from updating the stack. Anything Calc displays after the ++mode-changing command will appear in the new format. ++ ++@smallexample ++@group ++4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 ++3: 12345.000 3: 12345.000 3: 12345.000 3: 1.2345e4 3: 12345. ++2: 123.450 2: 123.450 2: 1.2345e1 2: 1.2345e1 2: 123.45 ++1: 12.345 1: 1.2345e1 1: 1.2345e2 1: 1.2345e2 1: 12.345 ++ . . . . . ++ ++ H d s @key{DEL} U @key{TAB} d @key{SPC} d n ++@end group ++@end smallexample ++ ++@noindent ++Here the @kbd{H d s} command changes to scientific notation but without ++updating the screen. Deleting the top stack entry and undoing it back ++causes it to show up in the new format; swapping the top two stack ++entries reformats both entries. The @kbd{d @key{SPC}} command refreshes the ++whole stack. The @kbd{d n} command changes back to the normal float ++format; since it doesn't have an @kbd{H} prefix, it also updates all ++the stack entries to be in @kbd{d n} format. ++ ++Notice that the integer @expr{12345} was not affected by any ++of the float formats. Integers are integers, and are always ++displayed exactly. ++ ++@cindex Large numbers, readability ++Large integers have their own problems. Let's look back at ++the result of @kbd{2^3^4}. ++ ++@example ++2417851639229258349412352 ++@end example ++ ++@noindent ++Quick---how many digits does this have? Try typing @kbd{d g}: ++ ++@example ++2,417,851,639,229,258,349,412,352 ++@end example ++ ++@noindent ++Now how many digits does this have? It's much easier to tell! ++We can actually group digits into clumps of any size. Some ++people prefer @kbd{M-5 d g}: ++ ++@example ++24178,51639,22925,83494,12352 ++@end example ++ ++Let's see what happens to floating-point numbers when they are grouped. ++First, type @kbd{p 25 @key{RET}} to make sure we have enough precision ++to get ourselves into trouble. Now, type @kbd{1e13 /}: ++ ++@example ++24,17851,63922.9258349412352 ++@end example ++ ++@noindent ++The integer part is grouped but the fractional part isn't. Now try ++@kbd{M-- M-5 d g} (that's meta-minus-sign, meta-five): ++ ++@example ++24,17851,63922.92583,49412,352 ++@end example ++ ++If you find it hard to tell the decimal point from the commas, try ++changing the grouping character to a space with @kbd{d , @key{SPC}}: ++ ++@example ++24 17851 63922.92583 49412 352 ++@end example ++ ++Type @kbd{d , ,} to restore the normal grouping character, then ++@kbd{d g} again to turn grouping off. Also, press @kbd{p 12} to ++restore the default precision. ++ ++Press @kbd{U} enough times to get the original big integer back. ++(Notice that @kbd{U} does not undo each mode-setting command; if ++you want to undo a mode-setting command, you have to do it yourself.) ++Now, type @kbd{d r 16 @key{RET}}: ++ ++@example ++16#200000000000000000000 ++@end example ++ ++@noindent ++The number is now displayed in @dfn{hexadecimal}, or ``base-16'' form. ++Suddenly it looks pretty simple; this should be no surprise, since we ++got this number by computing a power of two, and 16 is a power of 2. ++In fact, we can use @w{@kbd{d r 2 @key{RET}}} to see it in actual binary ++form: ++ ++@example ++2#1000000000000000000000000000000000000000000000000000000 @dots{} ++@end example ++ ++@noindent ++We don't have enough space here to show all the zeros! They won't ++fit on a typical screen, either, so you will have to use horizontal ++scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the ++stack window left and right by half its width. Another way to view ++something large is to press @kbd{`} (back-quote) to edit the top of ++stack in a separate window. (Press @kbd{C-c C-c} when you are done.) ++ ++You can enter non-decimal numbers using the @kbd{#} symbol, too. ++Let's see what the hexadecimal number @samp{5FE} looks like in ++binary. Type @kbd{16#5FE} (the letters can be typed in upper or ++lower case; they will always appear in upper case). It will also ++help to turn grouping on with @kbd{d g}: ++ ++@example ++2#101,1111,1110 ++@end example ++ ++Notice that @kbd{d g} groups by fours by default if the display radix ++is binary or hexadecimal, but by threes if it is decimal, octal, or any ++other radix. ++ ++Now let's see that number in decimal; type @kbd{d r 10}: ++ ++@example ++1,534 ++@end example ++ ++Numbers are not @emph{stored} with any particular radix attached. They're ++just numbers; they can be entered in any radix, and are always displayed ++in whatever radix you've chosen with @kbd{d r}. The current radix applies ++to integers, fractions, and floats. ++ ++@cindex Roundoff errors, in non-decimal numbers ++(@bullet{}) @strong{Exercise 1.} Your friend Joe tried to enter one-third ++as @samp{3#0.1} in @kbd{d r 3} mode with a precision of 12. He got ++@samp{3#0.0222222...} (with 25 2's) in the display. When he multiplied ++that by three, he got @samp{3#0.222222...} instead of the expected ++@samp{3#1}. Next, Joe entered @samp{3#0.2} and, to his great relief, ++saw @samp{3#0.2} on the screen. But when he typed @kbd{2 /}, he got ++@samp{3#0.10000001} (some zeros omitted). What's going on here? ++@xref{Modes Answer 1, 1}. (@bullet{}) ++ ++@cindex Scientific notation, in non-decimal numbers ++(@bullet{}) @strong{Exercise 2.} Scientific notation works in non-decimal ++modes in the natural way (the exponent is a power of the radix instead of ++a power of ten, although the exponent itself is always written in decimal). ++Thus @samp{8#1.23e3 = 8#1230.0}. Suppose we have the hexadecimal number ++@samp{f.e8f} times 16 to the 15th power: We write @samp{16#f.e8fe15}. ++What is wrong with this picture? What could we write instead that would ++work better? @xref{Modes Answer 2, 2}. (@bullet{}) ++ ++The @kbd{m} prefix key has another set of modes, relating to the way ++Calc interprets your inputs and does computations. Whereas @kbd{d}-prefix ++modes generally affect the way things look, @kbd{m}-prefix modes affect ++the way they are actually computed. ++ ++The most popular @kbd{m}-prefix mode is the @dfn{angular mode}. Notice ++the @samp{Deg} indicator in the mode line. This means that if you use ++a command that interprets a number as an angle, it will assume the ++angle is measured in degrees. For example, ++ ++@smallexample ++@group ++1: 45 1: 0.707106781187 1: 0.500000000001 1: 0.5 ++ . . . . ++ ++ 45 S 2 ^ c 1 ++@end group ++@end smallexample ++ ++@noindent ++The shift-@kbd{S} command computes the sine of an angle. The sine ++of 45 degrees is ++@texline @math{\sqrt{2}/2}; ++@infoline @expr{sqrt(2)/2}; ++squaring this yields @expr{2/4 = 0.5}. However, there has been a slight ++roundoff error because the representation of ++@texline @math{\sqrt{2}/2} ++@infoline @expr{sqrt(2)/2} ++wasn't exact. The @kbd{c 1} command is a handy way to clean up numbers ++in this case; it temporarily reduces the precision by one digit while it ++re-rounds the number on the top of the stack. ++ ++@cindex Roundoff errors, examples ++(@bullet{}) @strong{Exercise 3.} Your friend Joe computed the sine ++of 45 degrees as shown above, then, hoping to avoid an inexact ++result, he increased the precision to 16 digits before squaring. ++What happened? @xref{Modes Answer 3, 3}. (@bullet{}) ++ ++To do this calculation in radians, we would type @kbd{m r} first. ++(The indicator changes to @samp{Rad}.) 45 degrees corresponds to ++@cpiover{4} radians. To get @cpi{}, press the @kbd{P} key. (Once ++again, this is a shifted capital @kbd{P}. Remember, unshifted ++@kbd{p} sets the precision.) ++ ++@smallexample ++@group ++1: 3.14159265359 1: 0.785398163398 1: 0.707106781187 ++ . . . ++ ++ P 4 / m r S ++@end group ++@end smallexample ++ ++Likewise, inverse trigonometric functions generate results in ++either radians or degrees, depending on the current angular mode. ++ ++@smallexample ++@group ++1: 0.707106781187 1: 0.785398163398 1: 45. ++ . . . ++ ++ .5 Q m r I S m d U I S ++@end group ++@end smallexample ++ ++@noindent ++Here we compute the Inverse Sine of ++@texline @math{\sqrt{0.5}}, ++@infoline @expr{sqrt(0.5)}, ++first in radians, then in degrees. ++ ++Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees ++and vice-versa. ++ ++@smallexample ++@group ++1: 45 1: 0.785398163397 1: 45. ++ . . . ++ ++ 45 c r c d ++@end group ++@end smallexample ++ ++Another interesting mode is @dfn{Fraction mode}. Normally, ++dividing two integers produces a floating-point result if the ++quotient can't be expressed as an exact integer. Fraction mode ++causes integer division to produce a fraction, i.e., a rational ++number, instead. ++ ++@smallexample ++@group ++2: 12 1: 1.33333333333 1: 4:3 ++1: 9 . . ++ . ++ ++ 12 @key{RET} 9 / m f U / m f ++@end group ++@end smallexample ++ ++@noindent ++In the first case, we get an approximate floating-point result. ++In the second case, we get an exact fractional result (four-thirds). ++ ++You can enter a fraction at any time using @kbd{:} notation. ++(Calc uses @kbd{:} instead of @kbd{/} as the fraction separator ++because @kbd{/} is already used to divide the top two stack ++elements.) Calculations involving fractions will always ++produce exact fractional results; Fraction mode only says ++what to do when dividing two integers. ++ ++@cindex Fractions vs. floats ++@cindex Floats vs. fractions ++(@bullet{}) @strong{Exercise 4.} If fractional arithmetic is exact, ++why would you ever use floating-point numbers instead? ++@xref{Modes Answer 4, 4}. (@bullet{}) ++ ++Typing @kbd{m f} doesn't change any existing values in the stack. ++In the above example, we had to Undo the division and do it over ++again when we changed to Fraction mode. But if you use the ++evaluates-to operator you can get commands like @kbd{m f} to ++recompute for you. ++ ++@smallexample ++@group ++1: 12 / 9 => 1.33333333333 1: 12 / 9 => 1.333 1: 12 / 9 => 4:3 ++ . . . ++ ++ ' 12/9 => @key{RET} p 4 @key{RET} m f ++@end group ++@end smallexample ++ ++@noindent ++In this example, the righthand side of the @samp{=>} operator ++on the stack is recomputed when we change the precision, then ++again when we change to Fraction mode. All @samp{=>} expressions ++on the stack are recomputed every time you change any mode that ++might affect their values. ++ ++@node Arithmetic Tutorial, Vector/Matrix Tutorial, Basic Tutorial, Tutorial ++@section Arithmetic Tutorial ++ ++@noindent ++In this section, we explore the arithmetic and scientific functions ++available in the Calculator. ++ ++The standard arithmetic commands are @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, ++and @kbd{^}. Each normally takes two numbers from the top of the stack ++and pushes back a result. The @kbd{n} and @kbd{&} keys perform ++change-sign and reciprocal operations, respectively. ++ ++@smallexample ++@group ++1: 5 1: 0.2 1: 5. 1: -5. 1: 5. ++ . . . . . ++ ++ 5 & & n n ++@end group ++@end smallexample ++ ++@cindex Binary operators ++You can apply a ``binary operator'' like @kbd{+} across any number of ++stack entries by giving it a numeric prefix. You can also apply it ++pairwise to several stack elements along with the top one if you use ++a negative prefix. ++ ++@smallexample ++@group ++3: 2 1: 9 3: 2 4: 2 3: 12 ++2: 3 . 2: 3 3: 3 2: 13 ++1: 4 1: 4 2: 4 1: 14 ++ . . 1: 10 . ++ . ++ ++2 @key{RET} 3 @key{RET} 4 M-3 + U 10 M-- M-3 + ++@end group ++@end smallexample ++ ++@cindex Unary operators ++You can apply a ``unary operator'' like @kbd{&} to the top @var{n} ++stack entries with a numeric prefix, too. ++ ++@smallexample ++@group ++3: 2 3: 0.5 3: 0.5 ++2: 3 2: 0.333333333333 2: 3. ++1: 4 1: 0.25 1: 4. ++ . . . ++ ++2 @key{RET} 3 @key{RET} 4 M-3 & M-2 & ++@end group ++@end smallexample ++ ++Notice that the results here are left in floating-point form. ++We can convert them back to integers by pressing @kbd{F}, the ++``floor'' function. This function rounds down to the next lower ++integer. There is also @kbd{R}, which rounds to the nearest ++integer. ++ ++@smallexample ++@group ++7: 2. 7: 2 7: 2 ++6: 2.4 6: 2 6: 2 ++5: 2.5 5: 2 5: 3 ++4: 2.6 4: 2 4: 3 ++3: -2. 3: -2 3: -2 ++2: -2.4 2: -3 2: -2 ++1: -2.6 1: -3 1: -3 ++ . . . ++ ++ M-7 F U M-7 R ++@end group ++@end smallexample ++ ++Since dividing-and-flooring (i.e., ``integer quotient'') is such a ++common operation, Calc provides a special command for that purpose, the ++backslash @kbd{\}. Another common arithmetic operator is @kbd{%}, which ++computes the remainder that would arise from a @kbd{\} operation, i.e., ++the ``modulo'' of two numbers. For example, ++ ++@smallexample ++@group ++2: 1234 1: 12 2: 1234 1: 34 ++1: 100 . 1: 100 . ++ . . ++ ++1234 @key{RET} 100 \ U % ++@end group ++@end smallexample ++ ++These commands actually work for any real numbers, not just integers. ++ ++@smallexample ++@group ++2: 3.1415 1: 3 2: 3.1415 1: 0.1415 ++1: 1 . 1: 1 . ++ . . ++ ++3.1415 @key{RET} 1 \ U % ++@end group ++@end smallexample ++ ++(@bullet{}) @strong{Exercise 1.} The @kbd{\} command would appear to be a ++frill, since you could always do the same thing with @kbd{/ F}. Think ++of a situation where this is not true---@kbd{/ F} would be inadequate. ++Now think of a way you could get around the problem if Calc didn't ++provide a @kbd{\} command. @xref{Arithmetic Answer 1, 1}. (@bullet{}) ++ ++We've already seen the @kbd{Q} (square root) and @kbd{S} (sine) ++commands. Other commands along those lines are @kbd{C} (cosine), ++@kbd{T} (tangent), @kbd{E} (@expr{e^x}) and @kbd{L} (natural ++logarithm). These can be modified by the @kbd{I} (inverse) and ++@kbd{H} (hyperbolic) prefix keys. ++ ++Let's compute the sine and cosine of an angle, and verify the ++identity ++@texline @math{\sin^2x + \cos^2x = 1}. ++@infoline @expr{sin(x)^2 + cos(x)^2 = 1}. ++We'll arbitrarily pick @mathit{-64} degrees as a good value for @expr{x}. ++With the angular mode set to degrees (type @w{@kbd{m d}}), do: ++ ++@smallexample ++@group ++2: -64 2: -64 2: -0.89879 2: -0.89879 1: 1. ++1: -64 1: -0.89879 1: -64 1: 0.43837 . ++ . . . . ++ ++ 64 n @key{RET} @key{RET} S @key{TAB} C f h ++@end group ++@end smallexample ++ ++@noindent ++(For brevity, we're showing only five digits of the results here. ++You can of course do these calculations to any precision you like.) ++ ++Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum ++of squares, command. ++ ++Another identity is ++@texline @math{\displaystyle\tan x = {\sin x \over \cos x}}. ++@infoline @expr{tan(x) = sin(x) / cos(x)}. ++@smallexample ++@group ++ ++2: -0.89879 1: -2.0503 1: -64. ++1: 0.43837 . . ++ . ++ ++ U / I T ++@end group ++@end smallexample ++ ++A physical interpretation of this calculation is that if you move ++@expr{0.89879} units downward and @expr{0.43837} units to the right, ++your direction of motion is @mathit{-64} degrees from horizontal. Suppose ++we move in the opposite direction, up and to the left: ++ ++@smallexample ++@group ++2: -0.89879 2: 0.89879 1: -2.0503 1: -64. ++1: 0.43837 1: -0.43837 . . ++ . . ++ ++ U U M-2 n / I T ++@end group ++@end smallexample ++ ++@noindent ++How can the angle be the same? The answer is that the @kbd{/} operation ++loses information about the signs of its inputs. Because the quotient ++is negative, we know exactly one of the inputs was negative, but we ++can't tell which one. There is an @kbd{f T} [@code{arctan2}] function which ++computes the inverse tangent of the quotient of a pair of numbers. ++Since you feed it the two original numbers, it has enough information ++to give you a full 360-degree answer. ++ ++@smallexample ++@group ++2: 0.89879 1: 116. 3: 116. 2: 116. 1: 180. ++1: -0.43837 . 2: -0.89879 1: -64. . ++ . 1: 0.43837 . ++ . ++ ++ U U f T M-@key{RET} M-2 n f T - ++@end group ++@end smallexample ++ ++@noindent ++The resulting angles differ by 180 degrees; in other words, they ++point in opposite directions, just as we would expect. ++ ++The @key{META}-@key{RET} we used in the third step is the ++``last-arguments'' command. It is sort of like Undo, except that it ++restores the arguments of the last command to the stack without removing ++the command's result. It is useful in situations like this one, ++where we need to do several operations on the same inputs. We could ++have accomplished the same thing by using @kbd{M-2 @key{RET}} to duplicate ++the top two stack elements right after the @kbd{U U}, then a pair of ++@kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates. ++ ++A similar identity is supposed to hold for hyperbolic sines and cosines, ++except that it is the @emph{difference} ++@texline @math{\cosh^2x - \sinh^2x} ++@infoline @expr{cosh(x)^2 - sinh(x)^2} ++that always equals one. Let's try to verify this identity. ++ ++@smallexample ++@group ++2: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54 ++1: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 ++ . . . . . ++ ++ 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^ ++@end group ++@end smallexample ++ ++@noindent ++@cindex Roundoff errors, examples ++Something's obviously wrong, because when we subtract these numbers ++the answer will clearly be zero! But if you think about it, if these ++numbers @emph{did} differ by one, it would be in the 55th decimal ++place. The difference we seek has been lost entirely to roundoff ++error. ++ ++We could verify this hypothesis by doing the actual calculation with, ++say, 60 decimal places of precision. This will be slow, but not ++enormously so. Try it if you wish; sure enough, the answer is ++0.99999, reasonably close to 1. ++ ++Of course, a more reasonable way to verify the identity is to use ++a more reasonable value for @expr{x}! ++ ++@cindex Common logarithm ++Some Calculator commands use the Hyperbolic prefix for other purposes. ++The logarithm and exponential functions, for example, work to the base ++@expr{e} normally but use base-10 instead if you use the Hyperbolic ++prefix. ++ ++@smallexample ++@group ++1: 1000 1: 6.9077 1: 1000 1: 3 ++ . . . . ++ ++ 1000 L U H L ++@end group ++@end smallexample ++ ++@noindent ++First, we mistakenly compute a natural logarithm. Then we undo ++and compute a common logarithm instead. ++ ++The @kbd{B} key computes a general base-@var{b} logarithm for any ++value of @var{b}. ++ ++@smallexample ++@group ++2: 1000 1: 3 1: 1000. 2: 1000. 1: 6.9077 ++1: 10 . . 1: 2.71828 . ++ . . ++ ++ 1000 @key{RET} 10 B H E H P B ++@end group ++@end smallexample ++ ++@noindent ++Here we first use @kbd{B} to compute the base-10 logarithm, then use ++the ``hyperbolic'' exponential as a cheap hack to recover the number ++1000, then use @kbd{B} again to compute the natural logarithm. Note ++that @kbd{P} with the hyperbolic prefix pushes the constant @expr{e} ++onto the stack. ++ ++You may have noticed that both times we took the base-10 logarithm ++of 1000, we got an exact integer result. Calc always tries to give ++an exact rational result for calculations involving rational numbers ++where possible. But when we used @kbd{H E}, the result was a ++floating-point number for no apparent reason. In fact, if we had ++computed @kbd{10 @key{RET} 3 ^} we @emph{would} have gotten an ++exact integer 1000. But the @kbd{H E} command is rigged to generate ++a floating-point result all of the time so that @kbd{1000 H E} will ++not waste time computing a thousand-digit integer when all you ++probably wanted was @samp{1e1000}. ++ ++(@bullet{}) @strong{Exercise 2.} Find a pair of integer inputs to ++the @kbd{B} command for which Calc could find an exact rational ++result but doesn't. @xref{Arithmetic Answer 2, 2}. (@bullet{}) ++ ++The Calculator also has a set of functions relating to combinatorics ++and statistics. You may be familiar with the @dfn{factorial} function, ++which computes the product of all the integers up to a given number. ++ ++@smallexample ++@group ++1: 100 1: 93326215443... 1: 100. 1: 9.3326e157 ++ . . . . ++ ++ 100 ! U c f ! ++@end group ++@end smallexample ++ ++@noindent ++Recall, the @kbd{c f} command converts the integer or fraction at the ++top of the stack to floating-point format. If you take the factorial ++of a floating-point number, you get a floating-point result ++accurate to the current precision. But if you give @kbd{!} an ++exact integer, you get an exact integer result (158 digits long ++in this case). ++ ++If you take the factorial of a non-integer, Calc uses a generalized ++factorial function defined in terms of Euler's Gamma function ++@texline @math{\Gamma(n)} ++@infoline @expr{gamma(n)} ++(which is itself available as the @kbd{f g} command). ++ ++@smallexample ++@group ++3: 4. 3: 24. 1: 5.5 1: 52.342777847 ++2: 4.5 2: 52.3427777847 . . ++1: 5. 1: 120. ++ . . ++ ++ M-3 ! M-0 @key{DEL} 5.5 f g ++@end group ++@end smallexample ++ ++@noindent ++Here we verify the identity ++@texline @math{n! = \Gamma(n+1)}. ++@infoline @expr{@var{n}!@: = gamma(@var{n}+1)}. ++ ++The binomial coefficient @var{n}-choose-@var{m} ++@texline or @math{\displaystyle {n \choose m}} ++is defined by ++@texline @math{\displaystyle {n! \over m! \, (n-m)!}} ++@infoline @expr{n!@: / m!@: (n-m)!} ++for all reals @expr{n} and @expr{m}. The intermediate results in this ++formula can become quite large even if the final result is small; the ++@kbd{k c} command computes a binomial coefficient in a way that avoids ++large intermediate values. ++ ++The @kbd{k} prefix key defines several common functions out of ++combinatorics and number theory. Here we compute the binomial ++coefficient 30-choose-20, then determine its prime factorization. ++ ++@smallexample ++@group ++2: 30 1: 30045015 1: [3, 3, 5, 7, 11, 13, 23, 29] ++1: 20 . . ++ . ++ ++ 30 @key{RET} 20 k c k f ++@end group ++@end smallexample ++ ++@noindent ++You can verify these prime factors by using @kbd{V R *} to multiply ++together the elements of this vector. The result is the original ++number, 30045015. ++ ++@cindex Hash tables ++Suppose a program you are writing needs a hash table with at least ++10000 entries. It's best to use a prime number as the actual size ++of a hash table. Calc can compute the next prime number after 10000: ++ ++@smallexample ++@group ++1: 10000 1: 10007 1: 9973 ++ . . . ++ ++ 10000 k n I k n ++@end group ++@end smallexample ++ ++@noindent ++Just for kicks we've also computed the next prime @emph{less} than ++10000. ++ ++@c [fix-ref Financial Functions] ++@xref{Financial Functions}, for a description of the Calculator ++commands that deal with business and financial calculations (functions ++like @code{pv}, @code{rate}, and @code{sln}). ++ ++@c [fix-ref Binary Number Functions] ++@xref{Binary Functions}, to read about the commands for operating ++on binary numbers (like @code{and}, @code{xor}, and @code{lsh}). ++ ++@node Vector/Matrix Tutorial, Types Tutorial, Arithmetic Tutorial, Tutorial ++@section Vector/Matrix Tutorial ++ ++@noindent ++A @dfn{vector} is a list of numbers or other Calc data objects. ++Calc provides a large set of commands that operate on vectors. Some ++are familiar operations from vector analysis. Others simply treat ++a vector as a list of objects. ++ ++@menu ++* Vector Analysis Tutorial:: ++* Matrix Tutorial:: ++* List Tutorial:: ++@end menu ++ ++@node Vector Analysis Tutorial, Matrix Tutorial, Vector/Matrix Tutorial, Vector/Matrix Tutorial ++@subsection Vector Analysis ++ ++@noindent ++If you add two vectors, the result is a vector of the sums of the ++elements, taken pairwise. ++ ++@smallexample ++@group ++1: [1, 2, 3] 2: [1, 2, 3] 1: [8, 8, 3] ++ . 1: [7, 6, 0] . ++ . ++ ++ [1,2,3] s 1 [7 6 0] s 2 + ++@end group ++@end smallexample ++ ++@noindent ++Note that we can separate the vector elements with either commas or ++spaces. This is true whether we are using incomplete vectors or ++algebraic entry. The @kbd{s 1} and @kbd{s 2} commands save these ++vectors so we can easily reuse them later. ++ ++If you multiply two vectors, the result is the sum of the products ++of the elements taken pairwise. This is called the @dfn{dot product} ++of the vectors. ++ ++@smallexample ++@group ++2: [1, 2, 3] 1: 19 ++1: [7, 6, 0] . ++ . ++ ++ r 1 r 2 * ++@end group ++@end smallexample ++ ++@cindex Dot product ++The dot product of two vectors is equal to the product of their ++lengths times the cosine of the angle between them. (Here the vector ++is interpreted as a line from the origin @expr{(0,0,0)} to the ++specified point in three-dimensional space.) The @kbd{A} ++(absolute value) command can be used to compute the length of a ++vector. ++ ++@smallexample ++@group ++3: 19 3: 19 1: 0.550782 1: 56.579 ++2: [1, 2, 3] 2: 3.741657 . . ++1: [7, 6, 0] 1: 9.219544 ++ . . ++ ++ M-@key{RET} M-2 A * / I C ++@end group ++@end smallexample ++ ++@noindent ++First we recall the arguments to the dot product command, then ++we compute the absolute values of the top two stack entries to ++obtain the lengths of the vectors, then we divide the dot product ++by the product of the lengths to get the cosine of the angle. ++The inverse cosine finds that the angle between the vectors ++is about 56 degrees. ++ ++@cindex Cross product ++@cindex Perpendicular vectors ++The @dfn{cross product} of two vectors is a vector whose length ++is the product of the lengths of the inputs times the sine of the ++angle between them, and whose direction is perpendicular to both ++input vectors. Unlike the dot product, the cross product is ++defined only for three-dimensional vectors. Let's double-check ++our computation of the angle using the cross product. ++ ++@smallexample ++@group ++2: [1, 2, 3] 3: [-18, 21, -8] 1: [-0.52, 0.61, -0.23] 1: 56.579 ++1: [7, 6, 0] 2: [1, 2, 3] . . ++ . 1: [7, 6, 0] ++ . ++ ++ r 1 r 2 V C s 3 M-@key{RET} M-2 A * / A I S ++@end group ++@end smallexample ++ ++@noindent ++First we recall the original vectors and compute their cross product, ++which we also store for later reference. Now we divide the vector ++by the product of the lengths of the original vectors. The length of ++this vector should be the sine of the angle; sure enough, it is! ++ ++@c [fix-ref General Mode Commands] ++Vector-related commands generally begin with the @kbd{v} prefix key. ++Some are uppercase letters and some are lowercase. To make it easier ++to type these commands, the shift-@kbd{V} prefix key acts the same as ++the @kbd{v} key. (@xref{General Mode Commands}, for a way to make all ++prefix keys have this property.) ++ ++If we take the dot product of two perpendicular vectors we expect ++to get zero, since the cosine of 90 degrees is zero. Let's check ++that the cross product is indeed perpendicular to both inputs: ++ ++@smallexample ++@group ++2: [1, 2, 3] 1: 0 2: [7, 6, 0] 1: 0 ++1: [-18, 21, -8] . 1: [-18, 21, -8] . ++ . . ++ ++ r 1 r 3 * @key{DEL} r 2 r 3 * ++@end group ++@end smallexample ++ ++@cindex Normalizing a vector ++@cindex Unit vectors ++(@bullet{}) @strong{Exercise 1.} Given a vector on the top of the ++stack, what keystrokes would you use to @dfn{normalize} the ++vector, i.e., to reduce its length to one without changing its ++direction? @xref{Vector Answer 1, 1}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 2.} Suppose a certain particle can be ++at any of several positions along a ruler. You have a list of ++those positions in the form of a vector, and another list of the ++probabilities for the particle to be at the corresponding positions. ++Find the average position of the particle. ++@xref{Vector Answer 2, 2}. (@bullet{}) ++ ++@node Matrix Tutorial, List Tutorial, Vector Analysis Tutorial, Vector/Matrix Tutorial ++@subsection Matrices ++ ++@noindent ++A @dfn{matrix} is just a vector of vectors, all the same length. ++This means you can enter a matrix using nested brackets. You can ++also use the semicolon character to enter a matrix. We'll show ++both methods here: ++ ++@smallexample ++@group ++1: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] ++ [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] ++ . . ++ ++ [[1 2 3] [4 5 6]] ' [1 2 3; 4 5 6] @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++We'll be using this matrix again, so type @kbd{s 4} to save it now. ++ ++Note that semicolons work with incomplete vectors, but they work ++better in algebraic entry. That's why we use the apostrophe in ++the second example. ++ ++When two matrices are multiplied, the lefthand matrix must have ++the same number of columns as the righthand matrix has rows. ++Row @expr{i}, column @expr{j} of the result is effectively the ++dot product of row @expr{i} of the left matrix by column @expr{j} ++of the right matrix. ++ ++If we try to duplicate this matrix and multiply it by itself, ++the dimensions are wrong and the multiplication cannot take place: ++ ++@smallexample ++@group ++1: [ [ 1, 2, 3 ] * [ [ 1, 2, 3 ] ++ [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] ++ . ++ ++ @key{RET} * ++@end group ++@end smallexample ++ ++@noindent ++Though rather hard to read, this is a formula which shows the product ++of two matrices. The @samp{*} function, having invalid arguments, has ++been left in symbolic form. ++ ++We can multiply the matrices if we @dfn{transpose} one of them first. ++ ++@smallexample ++@group ++2: [ [ 1, 2, 3 ] 1: [ [ 14, 32 ] 1: [ [ 17, 22, 27 ] ++ [ 4, 5, 6 ] ] [ 32, 77 ] ] [ 22, 29, 36 ] ++1: [ [ 1, 4 ] . [ 27, 36, 45 ] ] ++ [ 2, 5 ] . ++ [ 3, 6 ] ] ++ . ++ ++ U v t * U @key{TAB} * ++@end group ++@end smallexample ++ ++Matrix multiplication is not commutative; indeed, switching the ++order of the operands can even change the dimensions of the result ++matrix, as happened here! ++ ++If you multiply a plain vector by a matrix, it is treated as a ++single row or column depending on which side of the matrix it is ++on. The result is a plain vector which should also be interpreted ++as a row or column as appropriate. ++ ++@smallexample ++@group ++2: [ [ 1, 2, 3 ] 1: [14, 32] ++ [ 4, 5, 6 ] ] . ++1: [1, 2, 3] ++ . ++ ++ r 4 r 1 * ++@end group ++@end smallexample ++ ++Multiplying in the other order wouldn't work because the number of ++rows in the matrix is different from the number of elements in the ++vector. ++ ++(@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows ++of the above ++@texline @math{2\times3} ++@infoline 2x3 ++matrix to get @expr{[6, 15]}. Now use @samp{*} to sum along the columns ++to get @expr{[5, 7, 9]}. ++@xref{Matrix Answer 1, 1}. (@bullet{}) ++ ++@cindex Identity matrix ++An @dfn{identity matrix} is a square matrix with ones along the ++diagonal and zeros elsewhere. It has the property that multiplication ++by an identity matrix, on the left or on the right, always produces ++the original matrix. ++ ++@smallexample ++@group ++1: [ [ 1, 2, 3 ] 2: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] ++ [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] ++ . 1: [ [ 1, 0, 0 ] . ++ [ 0, 1, 0 ] ++ [ 0, 0, 1 ] ] ++ . ++ ++ r 4 v i 3 @key{RET} * ++@end group ++@end smallexample ++ ++If a matrix is square, it is often possible to find its @dfn{inverse}, ++that is, a matrix which, when multiplied by the original matrix, yields ++an identity matrix. The @kbd{&} (reciprocal) key also computes the ++inverse of a matrix. ++ ++@smallexample ++@group ++1: [ [ 1, 2, 3 ] 1: [ [ -2.4, 1.2, -0.2 ] ++ [ 4, 5, 6 ] [ 2.8, -1.4, 0.4 ] ++ [ 7, 6, 0 ] ] [ -0.73333, 0.53333, -0.2 ] ] ++ . . ++ ++ r 4 r 2 | s 5 & ++@end group ++@end smallexample ++ ++@noindent ++The vertical bar @kbd{|} @dfn{concatenates} numbers, vectors, and ++matrices together. Here we have used it to add a new row onto ++our matrix to make it square. ++ ++We can multiply these two matrices in either order to get an identity. ++ ++@smallexample ++@group ++1: [ [ 1., 0., 0. ] 1: [ [ 1., 0., 0. ] ++ [ 0., 1., 0. ] [ 0., 1., 0. ] ++ [ 0., 0., 1. ] ] [ 0., 0., 1. ] ] ++ . . ++ ++ M-@key{RET} * U @key{TAB} * ++@end group ++@end smallexample ++ ++@cindex Systems of linear equations ++@cindex Linear equations, systems of ++Matrix inverses are related to systems of linear equations in algebra. ++Suppose we had the following set of equations: ++ ++@ifnottex ++@group ++@example ++ a + 2b + 3c = 6 ++ 4a + 5b + 6c = 2 ++ 7a + 6b = 3 ++@end example ++@end group ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplayh ++$$ \openup1\jot \tabskip=0pt plus1fil ++\halign to\displaywidth{\tabskip=0pt ++ $\hfil#$&$\hfil{}#{}$& ++ $\hfil#$&$\hfil{}#{}$& ++ $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr ++ a&+&2b&+&3c&=6 \cr ++ 4a&+&5b&+&6c&=2 \cr ++ 7a&+&6b& & &=3 \cr} ++$$ ++\afterdisplayh ++@end tex ++ ++@noindent ++This can be cast into the matrix equation, ++ ++@ifnottex ++@group ++@example ++ [ [ 1, 2, 3 ] [ [ a ] [ [ 6 ] ++ [ 4, 5, 6 ] * [ b ] = [ 2 ] ++ [ 7, 6, 0 ] ] [ c ] ] [ 3 ] ] ++@end example ++@end group ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 } ++ \times ++ \pmatrix{ a \cr b \cr c } = \pmatrix{ 6 \cr 2 \cr 3 } ++$$ ++\afterdisplay ++@end tex ++ ++We can solve this system of equations by multiplying both sides by the ++inverse of the matrix. Calc can do this all in one step: ++ ++@smallexample ++@group ++2: [6, 2, 3] 1: [-12.6, 15.2, -3.93333] ++1: [ [ 1, 2, 3 ] . ++ [ 4, 5, 6 ] ++ [ 7, 6, 0 ] ] ++ . ++ ++ [6,2,3] r 5 / ++@end group ++@end smallexample ++ ++@noindent ++The result is the @expr{[a, b, c]} vector that solves the equations. ++(Dividing by a square matrix is equivalent to multiplying by its ++inverse.) ++ ++Let's verify this solution: ++ ++@smallexample ++@group ++2: [ [ 1, 2, 3 ] 1: [6., 2., 3.] ++ [ 4, 5, 6 ] . ++ [ 7, 6, 0 ] ] ++1: [-12.6, 15.2, -3.93333] ++ . ++ ++ r 5 @key{TAB} * ++@end group ++@end smallexample ++ ++@noindent ++Note that we had to be careful about the order in which we multiplied ++the matrix and vector. If we multiplied in the other order, Calc would ++assume the vector was a row vector in order to make the dimensions ++come out right, and the answer would be incorrect. If you ++don't feel safe letting Calc take either interpretation of your ++vectors, use explicit ++@texline @math{N\times1} ++@infoline Nx1 ++or ++@texline @math{1\times N} ++@infoline 1xN ++matrices instead. In this case, you would enter the original column ++vector as @samp{[[6], [2], [3]]} or @samp{[6; 2; 3]}. ++ ++(@bullet{}) @strong{Exercise 2.} Algebraic entry allows you to make ++vectors and matrices that include variables. Solve the following ++system of equations to get expressions for @expr{x} and @expr{y} ++in terms of @expr{a} and @expr{b}. ++ ++@ifnottex ++@group ++@example ++ x + a y = 6 ++ x + b y = 10 ++@end example ++@end group ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ \eqalign{ x &+ a y = 6 \cr ++ x &+ b y = 10} ++$$ ++\afterdisplay ++@end tex ++ ++@noindent ++@xref{Matrix Answer 2, 2}. (@bullet{}) ++ ++@cindex Least-squares for over-determined systems ++@cindex Over-determined systems of equations ++(@bullet{}) @strong{Exercise 3.} A system of equations is ``over-determined'' ++if it has more equations than variables. It is often the case that ++there are no values for the variables that will satisfy all the ++equations at once, but it is still useful to find a set of values ++which ``nearly'' satisfy all the equations. In terms of matrix equations, ++you can't solve @expr{A X = B} directly because the matrix @expr{A} ++is not square for an over-determined system. Matrix inversion works ++only for square matrices. One common trick is to multiply both sides ++on the left by the transpose of @expr{A}: ++@ifnottex ++@samp{trn(A)*A*X = trn(A)*B}. ++@end ifnottex ++@tex ++\turnoffactive ++$A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}. ++@end tex ++Now ++@texline @math{A^T A} ++@infoline @expr{trn(A)*A} ++is a square matrix so a solution is possible. It turns out that the ++@expr{X} vector you compute in this way will be a ``least-squares'' ++solution, which can be regarded as the ``closest'' solution to the set ++of equations. Use Calc to solve the following over-determined ++system: ++ ++@ifnottex ++@group ++@example ++ a + 2b + 3c = 6 ++ 4a + 5b + 6c = 2 ++ 7a + 6b = 3 ++ 2a + 4b + 6c = 11 ++@end example ++@end group ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplayh ++$$ \openup1\jot \tabskip=0pt plus1fil ++\halign to\displaywidth{\tabskip=0pt ++ $\hfil#$&$\hfil{}#{}$& ++ $\hfil#$&$\hfil{}#{}$& ++ $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr ++ a&+&2b&+&3c&=6 \cr ++ 4a&+&5b&+&6c&=2 \cr ++ 7a&+&6b& & &=3 \cr ++ 2a&+&4b&+&6c&=11 \cr} ++$$ ++\afterdisplayh ++@end tex ++ ++@noindent ++@xref{Matrix Answer 3, 3}. (@bullet{}) ++ ++@node List Tutorial, , Matrix Tutorial, Vector/Matrix Tutorial ++@subsection Vectors as Lists ++ ++@noindent ++@cindex Lists ++Although Calc has a number of features for manipulating vectors and ++matrices as mathematical objects, you can also treat vectors as ++simple lists of values. For example, we saw that the @kbd{k f} ++command returns a vector which is a list of the prime factors of a ++number. ++ ++You can pack and unpack stack entries into vectors: ++ ++@smallexample ++@group ++3: 10 1: [10, 20, 30] 3: 10 ++2: 20 . 2: 20 ++1: 30 1: 30 ++ . . ++ ++ M-3 v p v u ++@end group ++@end smallexample ++ ++You can also build vectors out of consecutive integers, or out ++of many copies of a given value: ++ ++@smallexample ++@group ++1: [1, 2, 3, 4] 2: [1, 2, 3, 4] 2: [1, 2, 3, 4] ++ . 1: 17 1: [17, 17, 17, 17] ++ . . ++ ++ v x 4 @key{RET} 17 v b 4 @key{RET} ++@end group ++@end smallexample ++ ++You can apply an operator to every element of a vector using the ++@dfn{map} command. ++ ++@smallexample ++@group ++1: [17, 34, 51, 68] 1: [289, 1156, 2601, 4624] 1: [17, 34, 51, 68] ++ . . . ++ ++ V M * 2 V M ^ V M Q ++@end group ++@end smallexample ++ ++@noindent ++In the first step, we multiply the vector of integers by the vector ++of 17's elementwise. In the second step, we raise each element to ++the power two. (The general rule is that both operands must be ++vectors of the same length, or else one must be a vector and the ++other a plain number.) In the final step, we take the square root ++of each element. ++ ++(@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two ++from ++@texline @math{2^{-4}} ++@infoline @expr{2^-4} ++to @expr{2^4}. @xref{List Answer 1, 1}. (@bullet{}) ++ ++You can also @dfn{reduce} a binary operator across a vector. ++For example, reducing @samp{*} computes the product of all the ++elements in the vector: ++ ++@smallexample ++@group ++1: 123123 1: [3, 7, 11, 13, 41] 1: 123123 ++ . . . ++ ++ 123123 k f V R * ++@end group ++@end smallexample ++ ++@noindent ++In this example, we decompose 123123 into its prime factors, then ++multiply those factors together again to yield the original number. ++ ++We could compute a dot product ``by hand'' using mapping and ++reduction: ++ ++@smallexample ++@group ++2: [1, 2, 3] 1: [7, 12, 0] 1: 19 ++1: [7, 6, 0] . . ++ . ++ ++ r 1 r 2 V M * V R + ++@end group ++@end smallexample ++ ++@noindent ++Recalling two vectors from the previous section, we compute the ++sum of pairwise products of the elements to get the same answer ++for the dot product as before. ++ ++A slight variant of vector reduction is the @dfn{accumulate} operation, ++@kbd{V U}. This produces a vector of the intermediate results from ++a corresponding reduction. Here we compute a table of factorials: ++ ++@smallexample ++@group ++1: [1, 2, 3, 4, 5, 6] 1: [1, 2, 6, 24, 120, 720] ++ . . ++ ++ v x 6 @key{RET} V U * ++@end group ++@end smallexample ++ ++Calc allows vectors to grow as large as you like, although it gets ++rather slow if vectors have more than about a hundred elements. ++Actually, most of the time is spent formatting these large vectors ++for display, not calculating on them. Try the following experiment ++(if your computer is very fast you may need to substitute a larger ++vector size). ++ ++@smallexample ++@group ++1: [1, 2, 3, 4, ... 1: [2, 3, 4, 5, ... ++ . . ++ ++ v x 500 @key{RET} 1 V M + ++@end group ++@end smallexample ++ ++Now press @kbd{v .} (the letter @kbd{v}, then a period) and try the ++experiment again. In @kbd{v .} mode, long vectors are displayed ++``abbreviated'' like this: ++ ++@smallexample ++@group ++1: [1, 2, 3, ..., 500] 1: [2, 3, 4, ..., 501] ++ . . ++ ++ v x 500 @key{RET} 1 V M + ++@end group ++@end smallexample ++ ++@noindent ++(where now the @samp{...} is actually part of the Calc display). ++You will find both operations are now much faster. But notice that ++even in @w{@kbd{v .}} mode, the full vectors are still shown in the Trail. ++Type @w{@kbd{t .}} to cause the trail to abbreviate as well, and try the ++experiment one more time. Operations on long vectors are now quite ++fast! (But of course if you use @kbd{t .} you will lose the ability ++to get old vectors back using the @kbd{t y} command.) ++ ++An easy way to view a full vector when @kbd{v .} mode is active is ++to press @kbd{`} (back-quote) to edit the vector; editing always works ++with the full, unabbreviated value. ++ ++@cindex Least-squares for fitting a straight line ++@cindex Fitting data to a line ++@cindex Line, fitting data to ++@cindex Data, extracting from buffers ++@cindex Columns of data, extracting ++As a larger example, let's try to fit a straight line to some data, ++using the method of least squares. (Calc has a built-in command for ++least-squares curve fitting, but we'll do it by hand here just to ++practice working with vectors.) Suppose we have the following list ++of values in a file we have loaded into Emacs: ++ ++@smallexample ++ x y ++ --- --- ++ 1.34 0.234 ++ 1.41 0.298 ++ 1.49 0.402 ++ 1.56 0.412 ++ 1.64 0.466 ++ 1.73 0.473 ++ 1.82 0.601 ++ 1.91 0.519 ++ 2.01 0.603 ++ 2.11 0.637 ++ 2.22 0.645 ++ 2.33 0.705 ++ 2.45 0.917 ++ 2.58 1.009 ++ 2.71 0.971 ++ 2.85 1.062 ++ 3.00 1.148 ++ 3.15 1.157 ++ 3.32 1.354 ++@end smallexample ++ ++@noindent ++If you are reading this tutorial in printed form, you will find it ++easiest to press @kbd{C-x * i} to enter the on-line Info version of ++the manual and find this table there. (Press @kbd{g}, then type ++@kbd{List Tutorial}, to jump straight to this section.) ++ ++Position the cursor at the upper-left corner of this table, just ++to the left of the @expr{1.34}. Press @kbd{C-@@} to set the mark. ++(On your system this may be @kbd{C-2}, @kbd{C-@key{SPC}}, or @kbd{NUL}.) ++Now position the cursor to the lower-right, just after the @expr{1.354}. ++You have now defined this region as an Emacs ``rectangle.'' Still ++in the Info buffer, type @kbd{C-x * r}. This command ++(@code{calc-grab-rectangle}) will pop you back into the Calculator, with ++the contents of the rectangle you specified in the form of a matrix. ++ ++@smallexample ++@group ++1: [ [ 1.34, 0.234 ] ++ [ 1.41, 0.298 ] ++ @dots{} ++@end group ++@end smallexample ++ ++@noindent ++(You may wish to use @kbd{v .} mode to abbreviate the display of this ++large matrix.) ++ ++We want to treat this as a pair of lists. The first step is to ++transpose this matrix into a pair of rows. Remember, a matrix is ++just a vector of vectors. So we can unpack the matrix into a pair ++of row vectors on the stack. ++ ++@smallexample ++@group ++1: [ [ 1.34, 1.41, 1.49, ... ] 2: [1.34, 1.41, 1.49, ... ] ++ [ 0.234, 0.298, 0.402, ... ] ] 1: [0.234, 0.298, 0.402, ... ] ++ . . ++ ++ v t v u ++@end group ++@end smallexample ++ ++@noindent ++Let's store these in quick variables 1 and 2, respectively. ++ ++@smallexample ++@group ++1: [1.34, 1.41, 1.49, ... ] . ++ . ++ ++ t 2 t 1 ++@end group ++@end smallexample ++ ++@noindent ++(Recall that @kbd{t 2} is a variant of @kbd{s 2} that removes the ++stored value from the stack.) ++ ++In a least squares fit, the slope @expr{m} is given by the formula ++ ++@ifnottex ++@example ++m = (N sum(x y) - sum(x) sum(y)) / (N sum(x^2) - sum(x)^2) ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ m = {N \sum x y - \sum x \sum y \over ++ N \sum x^2 - \left( \sum x \right)^2} $$ ++\afterdisplay ++@end tex ++ ++@noindent ++where ++@texline @math{\sum x} ++@infoline @expr{sum(x)} ++represents the sum of all the values of @expr{x}. While there is an ++actual @code{sum} function in Calc, it's easier to sum a vector using a ++simple reduction. First, let's compute the four different sums that ++this formula uses. ++ ++@smallexample ++@group ++1: 41.63 1: 98.0003 ++ . . ++ ++ r 1 V R + t 3 r 1 2 V M ^ V R + t 4 ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: 13.613 1: 33.36554 ++ . . ++ ++ r 2 V R + t 5 r 1 r 2 V M * V R + t 6 ++@end group ++@end smallexample ++ ++@ifnottex ++@noindent ++These are @samp{sum(x)}, @samp{sum(x^2)}, @samp{sum(y)}, and @samp{sum(x y)}, ++respectively. (We could have used @kbd{*} to compute @samp{sum(x^2)} and ++@samp{sum(x y)}.) ++@end ifnottex ++@tex ++\turnoffactive ++These are $\sum x$, $\sum x^2$, $\sum y$, and $\sum x y$, ++respectively. (We could have used \kbd{*} to compute $\sum x^2$ and ++$\sum x y$.) ++@end tex ++ ++Finally, we also need @expr{N}, the number of data points. This is just ++the length of either of our lists. ++ ++@smallexample ++@group ++1: 19 ++ . ++ ++ r 1 v l t 7 ++@end group ++@end smallexample ++ ++@noindent ++(That's @kbd{v} followed by a lower-case @kbd{l}.) ++ ++Now we grind through the formula: ++ ++@smallexample ++@group ++1: 633.94526 2: 633.94526 1: 67.23607 ++ . 1: 566.70919 . ++ . ++ ++ r 7 r 6 * r 3 r 5 * - ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++2: 67.23607 3: 67.23607 2: 67.23607 1: 0.52141679 ++1: 1862.0057 2: 1862.0057 1: 128.9488 . ++ . 1: 1733.0569 . ++ . ++ ++ r 7 r 4 * r 3 2 ^ - / t 8 ++@end group ++@end smallexample ++ ++That gives us the slope @expr{m}. The y-intercept @expr{b} can now ++be found with the simple formula, ++ ++@ifnottex ++@example ++b = (sum(y) - m sum(x)) / N ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ b = {\sum y - m \sum x \over N} $$ ++\afterdisplay ++\vskip10pt ++@end tex ++ ++@smallexample ++@group ++1: 13.613 2: 13.613 1: -8.09358 1: -0.425978 ++ . 1: 21.70658 . . ++ . ++ ++ r 5 r 8 r 3 * - r 7 / t 9 ++@end group ++@end smallexample ++ ++Let's ``plot'' this straight line approximation, ++@texline @math{y \approx m x + b}, ++@infoline @expr{m x + b}, ++and compare it with the original data. ++ ++@smallexample ++@group ++1: [0.699, 0.735, ... ] 1: [0.273, 0.309, ... ] ++ . . ++ ++ r 1 r 8 * r 9 + s 0 ++@end group ++@end smallexample ++ ++@noindent ++Notice that multiplying a vector by a constant, and adding a constant ++to a vector, can be done without mapping commands since these are ++common operations from vector algebra. As far as Calc is concerned, ++we've just been doing geometry in 19-dimensional space! ++ ++We can subtract this vector from our original @expr{y} vector to get ++a feel for the error of our fit. Let's find the maximum error: ++ ++@smallexample ++@group ++1: [0.0387, 0.0112, ... ] 1: [0.0387, 0.0112, ... ] 1: 0.0897 ++ . . . ++ ++ r 2 - V M A V R X ++@end group ++@end smallexample ++ ++@noindent ++First we compute a vector of differences, then we take the absolute ++values of these differences, then we reduce the @code{max} function ++across the vector. (The @code{max} function is on the two-key sequence ++@kbd{f x}; because it is so common to use @code{max} in a vector ++operation, the letters @kbd{X} and @kbd{N} are also accepted for ++@code{max} and @code{min} in this context. In general, you answer ++the @kbd{V M} or @kbd{V R} prompt with the actual key sequence that ++invokes the function you want. You could have typed @kbd{V R f x} or ++even @kbd{V R x max @key{RET}} if you had preferred.) ++ ++If your system has the GNUPLOT program, you can see graphs of your ++data and your straight line to see how well they match. (If you have ++GNUPLOT 3.0 or higher, the following instructions will work regardless ++of the kind of display you have. Some GNUPLOT 2.0, non-X-windows systems ++may require additional steps to view the graphs.) ++ ++Let's start by plotting the original data. Recall the ``@var{x}'' and ``@var{y}'' ++vectors onto the stack and press @kbd{g f}. This ``fast'' graphing ++command does everything you need to do for simple, straightforward ++plotting of data. ++ ++@smallexample ++@group ++2: [1.34, 1.41, 1.49, ... ] ++1: [0.234, 0.298, 0.402, ... ] ++ . ++ ++ r 1 r 2 g f ++@end group ++@end smallexample ++ ++If all goes well, you will shortly get a new window containing a graph ++of the data. (If not, contact your GNUPLOT or Calc installer to find ++out what went wrong.) In the X window system, this will be a separate ++graphics window. For other kinds of displays, the default is to ++display the graph in Emacs itself using rough character graphics. ++Press @kbd{q} when you are done viewing the character graphics. ++ ++Next, let's add the line we got from our least-squares fit. ++@ifinfo ++(If you are reading this tutorial on-line while running Calc, typing ++@kbd{g a} may cause the tutorial to disappear from its window and be ++replaced by a buffer named @samp{*Gnuplot Commands*}. The tutorial ++will reappear when you terminate GNUPLOT by typing @kbd{g q}.) ++@end ifinfo ++ ++@smallexample ++@group ++2: [1.34, 1.41, 1.49, ... ] ++1: [0.273, 0.309, 0.351, ... ] ++ . ++ ++ @key{DEL} r 0 g a g p ++@end group ++@end smallexample ++ ++It's not very useful to get symbols to mark the data points on this ++second curve; you can type @kbd{g S g p} to remove them. Type @kbd{g q} ++when you are done to remove the X graphics window and terminate GNUPLOT. ++ ++(@bullet{}) @strong{Exercise 2.} An earlier exercise showed how to do ++least squares fitting to a general system of equations. Our 19 data ++points are really 19 equations of the form @expr{y_i = m x_i + b} for ++different pairs of @expr{(x_i,y_i)}. Use the matrix-transpose method ++to solve for @expr{m} and @expr{b}, duplicating the above result. ++@xref{List Answer 2, 2}. (@bullet{}) ++ ++@cindex Geometric mean ++(@bullet{}) @strong{Exercise 3.} If the input data do not form a ++rectangle, you can use @w{@kbd{C-x * g}} (@code{calc-grab-region}) ++to grab the data the way Emacs normally works with regions---it reads ++left-to-right, top-to-bottom, treating line breaks the same as spaces. ++Use this command to find the geometric mean of the following numbers. ++(The geometric mean is the @var{n}th root of the product of @var{n} numbers.) ++ ++@example ++2.3 6 22 15.1 7 ++ 15 14 7.5 ++ 2.5 ++@end example ++ ++@noindent ++The @kbd{C-x * g} command accepts numbers separated by spaces or commas, ++with or without surrounding vector brackets. ++@xref{List Answer 3, 3}. (@bullet{}) ++ ++@ifnottex ++As another example, a theorem about binomial coefficients tells ++us that the alternating sum of binomial coefficients ++@var{n}-choose-0 minus @var{n}-choose-1 plus @var{n}-choose-2, and so ++on up to @var{n}-choose-@var{n}, ++always comes out to zero. Let's verify this ++for @expr{n=6}. ++@end ifnottex ++@tex ++As another example, a theorem about binomial coefficients tells ++us that the alternating sum of binomial coefficients ++${n \choose 0} - {n \choose 1} + {n \choose 2} - \cdots \pm {n \choose n}$ ++always comes out to zero. Let's verify this ++for \cite{n=6}. ++@end tex ++ ++@smallexample ++@group ++1: [1, 2, 3, 4, 5, 6, 7] 1: [0, 1, 2, 3, 4, 5, 6] ++ . . ++ ++ v x 7 @key{RET} 1 - ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [1, -6, 15, -20, 15, -6, 1] 1: 0 ++ . . ++ ++ V M ' (-1)^$ choose(6,$) @key{RET} V R + ++@end group ++@end smallexample ++ ++The @kbd{V M '} command prompts you to enter any algebraic expression ++to define the function to map over the vector. The symbol @samp{$} ++inside this expression represents the argument to the function. ++The Calculator applies this formula to each element of the vector, ++substituting each element's value for the @samp{$} sign(s) in turn. ++ ++To define a two-argument function, use @samp{$$} for the first ++argument and @samp{$} for the second: @kbd{V M ' $$-$ @key{RET}} is ++equivalent to @kbd{V M -}. This is analogous to regular algebraic ++entry, where @samp{$$} would refer to the next-to-top stack entry ++and @samp{$} would refer to the top stack entry, and @kbd{' $$-$ @key{RET}} ++would act exactly like @kbd{-}. ++ ++Notice that the @kbd{V M '} command has recorded two things in the ++trail: The result, as usual, and also a funny-looking thing marked ++@samp{oper} that represents the operator function you typed in. ++The function is enclosed in @samp{< >} brackets, and the argument is ++denoted by a @samp{#} sign. If there were several arguments, they ++would be shown as @samp{#1}, @samp{#2}, and so on. (For example, ++@kbd{V M ' $$-$} will put the function @samp{<#1 - #2>} on the ++trail.) This object is a ``nameless function''; you can use nameless ++@w{@samp{< >}} notation to answer the @kbd{V M '} prompt if you like. ++Nameless function notation has the interesting, occasionally useful ++property that a nameless function is not actually evaluated until ++it is used. For example, @kbd{V M ' $+random(2.0)} evaluates ++@samp{random(2.0)} once and adds that random number to all elements ++of the vector, but @kbd{V M ' <#+random(2.0)>} evaluates the ++@samp{random(2.0)} separately for each vector element. ++ ++Another group of operators that are often useful with @kbd{V M} are ++the relational operators: @kbd{a =}, for example, compares two numbers ++and gives the result 1 if they are equal, or 0 if not. Similarly, ++@w{@kbd{a <}} checks for one number being less than another. ++ ++Other useful vector operations include @kbd{v v}, to reverse a ++vector end-for-end; @kbd{V S}, to sort the elements of a vector ++into increasing order; and @kbd{v r} and @w{@kbd{v c}}, to extract ++one row or column of a matrix, or (in both cases) to extract one ++element of a plain vector. With a negative argument, @kbd{v r} ++and @kbd{v c} instead delete one row, column, or vector element. ++ ++@cindex Divisor functions ++(@bullet{}) @strong{Exercise 4.} The @expr{k}th @dfn{divisor function} ++@tex ++$\sigma_k(n)$ ++@end tex ++is the sum of the @expr{k}th powers of all the divisors of an ++integer @expr{n}. Figure out a method for computing the divisor ++function for reasonably small values of @expr{n}. As a test, ++the 0th and 1st divisor functions of 30 are 8 and 72, respectively. ++@xref{List Answer 4, 4}. (@bullet{}) ++ ++@cindex Square-free numbers ++@cindex Duplicate values in a list ++(@bullet{}) @strong{Exercise 5.} The @kbd{k f} command produces a ++list of prime factors for a number. Sometimes it is important to ++know that a number is @dfn{square-free}, i.e., that no prime occurs ++more than once in its list of prime factors. Find a sequence of ++keystrokes to tell if a number is square-free; your method should ++leave 1 on the stack if it is, or 0 if it isn't. ++@xref{List Answer 5, 5}. (@bullet{}) ++ ++@cindex Triangular lists ++(@bullet{}) @strong{Exercise 6.} Build a list of lists that looks ++like the following diagram. (You may wish to use the @kbd{v /} ++command to enable multi-line display of vectors.) ++ ++@smallexample ++@group ++1: [ [1], ++ [1, 2], ++ [1, 2, 3], ++ [1, 2, 3, 4], ++ [1, 2, 3, 4, 5], ++ [1, 2, 3, 4, 5, 6] ] ++@end group ++@end smallexample ++ ++@noindent ++@xref{List Answer 6, 6}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 7.} Build the following list of lists. ++ ++@smallexample ++@group ++1: [ [0], ++ [1, 2], ++ [3, 4, 5], ++ [6, 7, 8, 9], ++ [10, 11, 12, 13, 14], ++ [15, 16, 17, 18, 19, 20] ] ++@end group ++@end smallexample ++ ++@noindent ++@xref{List Answer 7, 7}. (@bullet{}) ++ ++@cindex Maximizing a function over a list of values ++@c [fix-ref Numerical Solutions] ++(@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's ++@texline @math{J_1(x)} ++@infoline @expr{J1} ++function @samp{besJ(1,x)} for @expr{x} from 0 to 5 in steps of 0.25. ++Find the value of @expr{x} (from among the above set of values) for ++which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method, ++i.e., just reading along the list by hand to find the largest value ++is not allowed! (There is an @kbd{a X} command which does this kind ++of thing automatically; @pxref{Numerical Solutions}.) ++@xref{List Answer 8, 8}. (@bullet{}) ++ ++@cindex Digits, vectors of ++(@bullet{}) @strong{Exercise 9.} You are given an integer in the range ++@texline @math{0 \le N < 10^m} ++@infoline @expr{0 <= N < 10^m} ++for @expr{m=12} (i.e., an integer of less than ++twelve digits). Convert this integer into a vector of @expr{m} ++digits, each in the range from 0 to 9. In vector-of-digits notation, ++add one to this integer to produce a vector of @expr{m+1} digits ++(since there could be a carry out of the most significant digit). ++Convert this vector back into a regular integer. A good integer ++to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 10.} Your friend Joe tried to use ++@kbd{V R a =} to test if all numbers in a list were equal. What ++happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 11.} The area of a circle of radius one ++is @cpi{}. The area of the ++@texline @math{2\times2} ++@infoline 2x2 ++square that encloses that circle is 4. So if we throw @var{n} darts at ++random points in the square, about @cpiover{4} of them will land inside ++the circle. This gives us an entertaining way to estimate the value of ++@cpi{}. The @w{@kbd{k r}} ++command picks a random number between zero and the value on the stack. ++We could get a random floating-point number between @mathit{-1} and 1 by typing ++@w{@kbd{2.0 k r 1 -}}. Build a vector of 100 random @expr{(x,y)} points in ++this square, then use vector mapping and reduction to count how many ++points lie inside the unit circle. Hint: Use the @kbd{v b} command. ++@xref{List Answer 11, 11}. (@bullet{}) ++ ++@cindex Matchstick problem ++(@bullet{}) @strong{Exercise 12.} The @dfn{matchstick problem} provides ++another way to calculate @cpi{}. Say you have an infinite field ++of vertical lines with a spacing of one inch. Toss a one-inch matchstick ++onto the field. The probability that the matchstick will land crossing ++a line turns out to be ++@texline @math{2/\pi}. ++@infoline @expr{2/pi}. ++Toss 100 matchsticks to estimate @cpi{}. (If you want still more fun, ++the probability that the GCD (@w{@kbd{k g}}) of two large integers is ++one turns out to be ++@texline @math{6/\pi^2}. ++@infoline @expr{6/pi^2}. ++That provides yet another way to estimate @cpi{}.) ++@xref{List Answer 12, 12}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 13.} An algebraic entry of a string in ++double-quote marks, @samp{"hello"}, creates a vector of the numerical ++(ASCII) codes of the characters (here, @expr{[104, 101, 108, 108, 111]}). ++Sometimes it is convenient to compute a @dfn{hash code} of a string, ++which is just an integer that represents the value of that string. ++Two equal strings have the same hash code; two different strings ++@dfn{probably} have different hash codes. (For example, Calc has ++over 400 function names, but Emacs can quickly find the definition for ++any given name because it has sorted the functions into ``buckets'' by ++their hash codes. Sometimes a few names will hash into the same bucket, ++but it is easier to search among a few names than among all the names.) ++One popular hash function is computed as follows: First set @expr{h = 0}. ++Then, for each character from the string in turn, set @expr{h = 3h + c_i} ++where @expr{c_i} is the character's ASCII code. If we have 511 buckets, ++we then take the hash code modulo 511 to get the bucket number. Develop a ++simple command or commands for converting string vectors into hash codes. ++The hash code for @samp{"Testing, 1, 2, 3"} is 1960915098, which modulo ++511 is 121. @xref{List Answer 13, 13}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 14.} The @kbd{H V R} and @kbd{H V U} ++commands do nested function evaluations. @kbd{H V U} takes a starting ++value and a number of steps @var{n} from the stack; it then applies the ++function you give to the starting value 0, 1, 2, up to @var{n} times ++and returns a vector of the results. Use this command to create a ++``random walk'' of 50 steps. Start with the two-dimensional point ++@expr{(0,0)}; then take one step a random distance between @mathit{-1} and 1 ++in both @expr{x} and @expr{y}; then take another step, and so on. Use the ++@kbd{g f} command to display this random walk. Now modify your random ++walk to walk a unit distance, but in a random direction, at each step. ++(Hint: The @code{sincos} function returns a vector of the cosine and ++sine of an angle.) @xref{List Answer 14, 14}. (@bullet{}) ++ ++@node Types Tutorial, Algebra Tutorial, Vector/Matrix Tutorial, Tutorial ++@section Types Tutorial ++ ++@noindent ++Calc understands a variety of data types as well as simple numbers. ++In this section, we'll experiment with each of these types in turn. ++ ++The numbers we've been using so far have mainly been either @dfn{integers} ++or @dfn{floats}. We saw that floats are usually a good approximation to ++the mathematical concept of real numbers, but they are only approximations ++and are susceptible to roundoff error. Calc also supports @dfn{fractions}, ++which can exactly represent any rational number. ++ ++@smallexample ++@group ++1: 3628800 2: 3628800 1: 518400:7 1: 518414:7 1: 7:518414 ++ . 1: 49 . . . ++ . ++ ++ 10 ! 49 @key{RET} : 2 + & ++@end group ++@end smallexample ++ ++@noindent ++The @kbd{:} command divides two integers to get a fraction; @kbd{/} ++would normally divide integers to get a floating-point result. ++Notice we had to type @key{RET} between the @kbd{49} and the @kbd{:} ++since the @kbd{:} would otherwise be interpreted as part of a ++fraction beginning with 49. ++ ++You can convert between floating-point and fractional format using ++@kbd{c f} and @kbd{c F}: ++ ++@smallexample ++@group ++1: 1.35027217629e-5 1: 7:518414 ++ . . ++ ++ c f c F ++@end group ++@end smallexample ++ ++The @kbd{c F} command replaces a floating-point number with the ++``simplest'' fraction whose floating-point representation is the ++same, to within the current precision. ++ ++@smallexample ++@group ++1: 3.14159265359 1: 1146408:364913 1: 3.1416 1: 355:113 ++ . . . . ++ ++ P c F @key{DEL} p 5 @key{RET} P c F ++@end group ++@end smallexample ++ ++(@bullet{}) @strong{Exercise 1.} A calculation has produced the ++result 1.26508260337. You suspect it is the square root of the ++product of @cpi{} and some rational number. Is it? (Be sure ++to allow for roundoff error!) @xref{Types Answer 1, 1}. (@bullet{}) ++ ++@dfn{Complex numbers} can be stored in both rectangular and polar form. ++ ++@smallexample ++@group ++1: -9 1: (0, 3) 1: (3; 90.) 1: (6; 90.) 1: (2.4495; 45.) ++ . . . . . ++ ++ 9 n Q c p 2 * Q ++@end group ++@end smallexample ++ ++@noindent ++The square root of @mathit{-9} is by default rendered in rectangular form ++(@w{@expr{0 + 3i}}), but we can convert it to polar form (3 with a ++phase angle of 90 degrees). All the usual arithmetic and scientific ++operations are defined on both types of complex numbers. ++ ++Another generalized kind of number is @dfn{infinity}. Infinity ++isn't really a number, but it can sometimes be treated like one. ++Calc uses the symbol @code{inf} to represent positive infinity, ++i.e., a value greater than any real number. Naturally, you can ++also write @samp{-inf} for minus infinity, a value less than any ++real number. The word @code{inf} can only be input using ++algebraic entry. ++ ++@smallexample ++@group ++2: inf 2: -inf 2: -inf 2: -inf 1: nan ++1: -17 1: -inf 1: -inf 1: inf . ++ . . . . ++ ++' inf @key{RET} 17 n * @key{RET} 72 + A + ++@end group ++@end smallexample ++ ++@noindent ++Since infinity is infinitely large, multiplying it by any finite ++number (like @mathit{-17}) has no effect, except that since @mathit{-17} ++is negative, it changes a plus infinity to a minus infinity. ++(``A huge positive number, multiplied by @mathit{-17}, yields a huge ++negative number.'') Adding any finite number to infinity also ++leaves it unchanged. Taking an absolute value gives us plus ++infinity again. Finally, we add this plus infinity to the minus ++infinity we had earlier. If you work it out, you might expect ++the answer to be @mathit{-72} for this. But the 72 has been completely ++lost next to the infinities; by the time we compute @w{@samp{inf - inf}} ++the finite difference between them, if any, is undetectable. ++So we say the result is @dfn{indeterminate}, which Calc writes ++with the symbol @code{nan} (for Not A Number). ++ ++Dividing by zero is normally treated as an error, but you can get ++Calc to write an answer in terms of infinity by pressing @kbd{m i} ++to turn on Infinite mode. ++ ++@smallexample ++@group ++3: nan 2: nan 2: nan 2: nan 1: nan ++2: 1 1: 1 / 0 1: uinf 1: uinf . ++1: 0 . . . ++ . ++ ++ 1 @key{RET} 0 / m i U / 17 n * + ++@end group ++@end smallexample ++ ++@noindent ++Dividing by zero normally is left unevaluated, but after @kbd{m i} ++it instead gives an infinite result. The answer is actually ++@code{uinf}, ``undirected infinity.'' If you look at a graph of ++@expr{1 / x} around @w{@expr{x = 0}}, you'll see that it goes toward ++plus infinity as you approach zero from above, but toward minus ++infinity as you approach from below. Since we said only @expr{1 / 0}, ++Calc knows that the answer is infinite but not in which direction. ++That's what @code{uinf} means. Notice that multiplying @code{uinf} ++by a negative number still leaves plain @code{uinf}; there's no ++point in saying @samp{-uinf} because the sign of @code{uinf} is ++unknown anyway. Finally, we add @code{uinf} to our @code{nan}, ++yielding @code{nan} again. It's easy to see that, because ++@code{nan} means ``totally unknown'' while @code{uinf} means ++``unknown sign but known to be infinite,'' the more mysterious ++@code{nan} wins out when it is combined with @code{uinf}, or, for ++that matter, with anything else. ++ ++(@bullet{}) @strong{Exercise 2.} Predict what Calc will answer ++for each of these formulas: @samp{inf / inf}, @samp{exp(inf)}, ++@samp{exp(-inf)}, @samp{sqrt(-inf)}, @samp{sqrt(uinf)}, ++@samp{abs(uinf)}, @samp{ln(0)}. ++@xref{Types Answer 2, 2}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 3.} We saw that @samp{inf - inf = nan}, ++which stands for an unknown value. Can @code{nan} stand for ++a complex number? Can it stand for infinity? ++@xref{Types Answer 3, 3}. (@bullet{}) ++ ++@dfn{HMS forms} represent a value in terms of hours, minutes, and ++seconds. ++ ++@smallexample ++@group ++1: 2@@ 30' 0" 1: 3@@ 30' 0" 2: 3@@ 30' 0" 1: 2. ++ . . 1: 1@@ 45' 0." . ++ . ++ ++ 2@@ 30' @key{RET} 1 + @key{RET} 2 / / ++@end group ++@end smallexample ++ ++HMS forms can also be used to hold angles in degrees, minutes, and ++seconds. ++ ++@smallexample ++@group ++1: 0.5 1: 26.56505 1: 26@@ 33' 54.18" 1: 0.44721 ++ . . . . ++ ++ 0.5 I T c h S ++@end group ++@end smallexample ++ ++@noindent ++First we convert the inverse tangent of 0.5 to degrees-minutes-seconds ++form, then we take the sine of that angle. Note that the trigonometric ++functions will accept HMS forms directly as input. ++ ++@cindex Beatles ++(@bullet{}) @strong{Exercise 4.} The Beatles' @emph{Abbey Road} is ++47 minutes and 26 seconds long, and contains 17 songs. What is the ++average length of a song on @emph{Abbey Road}? If the Extended Disco ++Version of @emph{Abbey Road} added 20 seconds to the length of each ++song, how long would the album be? @xref{Types Answer 4, 4}. (@bullet{}) ++ ++A @dfn{date form} represents a date, or a date and time. Dates must ++be entered using algebraic entry. Date forms are surrounded by ++@samp{< >} symbols; most standard formats for dates are recognized. ++ ++@smallexample ++@group ++2: 1: 2.25 ++1: <6:00pm Thu Jan 10, 1991> . ++ . ++ ++' <13 Jan 1991>, <1/10/91, 6pm> @key{RET} - ++@end group ++@end smallexample ++ ++@noindent ++In this example, we enter two dates, then subtract to find the ++number of days between them. It is also possible to add an ++HMS form or a number (of days) to a date form to get another ++date form. ++ ++@smallexample ++@group ++1: <4:45:59pm Mon Jan 14, 1991> 1: <2:50:59am Thu Jan 17, 1991> ++ . . ++ ++ t N 2 + 10@@ 5' + ++@end group ++@end smallexample ++ ++@c [fix-ref Date Arithmetic] ++@noindent ++The @kbd{t N} (``now'') command pushes the current date and time on the ++stack; then we add two days, ten hours and five minutes to the date and ++time. Other date-and-time related commands include @kbd{t J}, which ++does Julian day conversions, @kbd{t W}, which finds the beginning of ++the week in which a date form lies, and @kbd{t I}, which increments a ++date by one or several months. @xref{Date Arithmetic}, for more. ++ ++(@bullet{}) @strong{Exercise 5.} How many days until the next ++Friday the 13th? @xref{Types Answer 5, 5}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 6.} How many leap years will there be ++between now and the year 10001 A.D.? @xref{Types Answer 6, 6}. (@bullet{}) ++ ++@cindex Slope and angle of a line ++@cindex Angle and slope of a line ++An @dfn{error form} represents a mean value with an attached standard ++deviation, or error estimate. Suppose our measurements indicate that ++a certain telephone pole is about 30 meters away, with an estimated ++error of 1 meter, and 8 meters tall, with an estimated error of 0.2 ++meters. What is the slope of a line from here to the top of the ++pole, and what is the equivalent angle in degrees? ++ ++@smallexample ++@group ++1: 8 +/- 0.2 2: 8 +/- 0.2 1: 0.266 +/- 0.011 1: 14.93 +/- 0.594 ++ . 1: 30 +/- 1 . . ++ . ++ ++ 8 p .2 @key{RET} 30 p 1 / I T ++@end group ++@end smallexample ++ ++@noindent ++This means that the angle is about 15 degrees, and, assuming our ++original error estimates were valid standard deviations, there is about ++a 60% chance that the result is correct within 0.59 degrees. ++ ++@cindex Torus, volume of ++(@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is ++@texline @math{2 \pi^2 R r^2} ++@infoline @w{@expr{2 pi^2 R r^2}} ++where @expr{R} is the radius of the circle that ++defines the center of the tube and @expr{r} is the radius of the tube ++itself. Suppose @expr{R} is 20 cm and @expr{r} is 4 cm, each known to ++within 5 percent. What is the volume and the relative uncertainty of ++the volume? @xref{Types Answer 7, 7}. (@bullet{}) ++ ++An @dfn{interval form} represents a range of values. While an ++error form is best for making statistical estimates, intervals give ++you exact bounds on an answer. Suppose we additionally know that ++our telephone pole is definitely between 28 and 31 meters away, ++and that it is between 7.7 and 8.1 meters tall. ++ ++@smallexample ++@group ++1: [7.7 .. 8.1] 2: [7.7 .. 8.1] 1: [0.24 .. 0.28] 1: [13.9 .. 16.1] ++ . 1: [28 .. 31] . . ++ . ++ ++ [ 7.7 .. 8.1 ] [ 28 .. 31 ] / I T ++@end group ++@end smallexample ++ ++@noindent ++If our bounds were correct, then the angle to the top of the pole ++is sure to lie in the range shown. ++ ++The square brackets around these intervals indicate that the endpoints ++themselves are allowable values. In other words, the distance to the ++telephone pole is between 28 and 31, @emph{inclusive}. You can also ++make an interval that is exclusive of its endpoints by writing ++parentheses instead of square brackets. You can even make an interval ++which is inclusive (``closed'') on one end and exclusive (``open'') on ++the other. ++ ++@smallexample ++@group ++1: [1 .. 10) 1: (0.1 .. 1] 2: (0.1 .. 1] 1: (0.2 .. 3) ++ . . 1: [2 .. 3) . ++ . ++ ++ [ 1 .. 10 ) & [ 2 .. 3 ) * ++@end group ++@end smallexample ++ ++@noindent ++The Calculator automatically keeps track of which end values should ++be open and which should be closed. You can also make infinite or ++semi-infinite intervals by using @samp{-inf} or @samp{inf} for one ++or both endpoints. ++ ++(@bullet{}) @strong{Exercise 8.} What answer would you expect from ++@samp{@w{1 /} @w{(0 .. 10)}}? What about @samp{@w{1 /} @w{(-10 .. 0)}}? What ++about @samp{@w{1 /} @w{[0 .. 10]}} (where the interval actually includes ++zero)? What about @samp{@w{1 /} @w{(-10 .. 10)}}? ++@xref{Types Answer 8, 8}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 9.} Two easy ways of squaring a number ++are @kbd{@key{RET} *} and @w{@kbd{2 ^}}. Normally these produce the same ++answer. Would you expect this still to hold true for interval forms? ++If not, which of these will result in a larger interval? ++@xref{Types Answer 9, 9}. (@bullet{}) ++ ++A @dfn{modulo form} is used for performing arithmetic modulo @var{m}. ++For example, arithmetic involving time is generally done modulo 12 ++or 24 hours. ++ ++@smallexample ++@group ++1: 17 mod 24 1: 3 mod 24 1: 21 mod 24 1: 9 mod 24 ++ . . . . ++ ++ 17 M 24 @key{RET} 10 + n 5 / ++@end group ++@end smallexample ++ ++@noindent ++In this last step, Calc has divided by 5 modulo 24; i.e., it has found a ++new number which, when multiplied by 5 modulo 24, produces the original ++number, 21. If @var{m} is prime and the divisor is not a multiple of ++@var{m}, it is always possible to find such a number. For non-prime ++@var{m} like 24, it is only sometimes possible. ++ ++@smallexample ++@group ++1: 10 mod 24 1: 16 mod 24 1: 1000000... 1: 16 ++ . . . . ++ ++ 10 M 24 @key{RET} 100 ^ 10 @key{RET} 100 ^ 24 % ++@end group ++@end smallexample ++ ++@noindent ++These two calculations get the same answer, but the first one is ++much more efficient because it avoids the huge intermediate value ++that arises in the second one. ++ ++@cindex Fermat, primality test of ++(@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat ++says that ++@texline @w{@math{x^{n-1} \bmod n = 1}} ++@infoline @expr{x^(n-1) mod n = 1} ++if @expr{n} is a prime number and @expr{x} is an integer less than ++@expr{n}. If @expr{n} is @emph{not} a prime number, this will ++@emph{not} be true for most values of @expr{x}. Thus we can test ++informally if a number is prime by trying this formula for several ++values of @expr{x}. Use this test to tell whether the following numbers ++are prime: 811749613, 15485863. @xref{Types Answer 10, 10}. (@bullet{}) ++ ++It is possible to use HMS forms as parts of error forms, intervals, ++modulo forms, or as the phase part of a polar complex number. ++For example, the @code{calc-time} command pushes the current time ++of day on the stack as an HMS/modulo form. ++ ++@smallexample ++@group ++1: 17@@ 34' 45" mod 24@@ 0' 0" 1: 6@@ 22' 15" mod 24@@ 0' 0" ++ . . ++ ++ x time @key{RET} n ++@end group ++@end smallexample ++ ++@noindent ++This calculation tells me it is six hours and 22 minutes until midnight. ++ ++(@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year ++is about ++@texline @math{\pi \times 10^7} ++@infoline @w{@expr{pi * 10^7}} ++seconds. What time will it be that many seconds from right now? ++@xref{Types Answer 11, 11}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 12.} You are preparing to order packaging ++for the CD release of the Extended Disco Version of @emph{Abbey Road}. ++You are told that the songs will actually be anywhere from 20 to 60 ++seconds longer than the originals. One CD can hold about 75 minutes ++of music. Should you order single or double packages? ++@xref{Types Answer 12, 12}. (@bullet{}) ++ ++Another kind of data the Calculator can manipulate is numbers with ++@dfn{units}. This isn't strictly a new data type; it's simply an ++application of algebraic expressions, where we use variables with ++suggestive names like @samp{cm} and @samp{in} to represent units ++like centimeters and inches. ++ ++@smallexample ++@group ++1: 2 in 1: 5.08 cm 1: 0.027778 fath 1: 0.0508 m ++ . . . . ++ ++ ' 2in @key{RET} u c cm @key{RET} u c fath @key{RET} u b ++@end group ++@end smallexample ++ ++@noindent ++We enter the quantity ``2 inches'' (actually an algebraic expression ++which means two times the variable @samp{in}), then we convert it ++first to centimeters, then to fathoms, then finally to ``base'' units, ++which in this case means meters. ++ ++@smallexample ++@group ++1: 9 acre 1: 3 sqrt(acre) 1: 190.84 m 1: 190.84 m + 30 cm ++ . . . . ++ ++ ' 9 acre @key{RET} Q u s ' $+30 cm @key{RET} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: 191.14 m 1: 36536.3046 m^2 1: 365363046 cm^2 ++ . . . ++ ++ u s 2 ^ u c cgs ++@end group ++@end smallexample ++ ++@noindent ++Since units expressions are really just formulas, taking the square ++root of @samp{acre} is undefined. After all, @code{acre} might be an ++algebraic variable that you will someday assign a value. We use the ++``units-simplify'' command to simplify the expression with variables ++being interpreted as unit names. ++ ++In the final step, we have converted not to a particular unit, but to a ++units system. The ``cgs'' system uses centimeters instead of meters ++as its standard unit of length. ++ ++There is a wide variety of units defined in the Calculator. ++ ++@smallexample ++@group ++1: 55 mph 1: 88.5139 kph 1: 88.5139 km / hr 1: 8.201407e-8 c ++ . . . . ++ ++ ' 55 mph @key{RET} u c kph @key{RET} u c km/hr @key{RET} u c c @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++We express a speed first in miles per hour, then in kilometers per ++hour, then again using a slightly more explicit notation, then ++finally in terms of fractions of the speed of light. ++ ++Temperature conversions are a bit more tricky. There are two ways to ++interpret ``20 degrees Fahrenheit''---it could mean an actual ++temperature, or it could mean a change in temperature. For normal ++units there is no difference, but temperature units have an offset ++as well as a scale factor and so there must be two explicit commands ++for them. ++ ++@smallexample ++@group ++1: 20 degF 1: 11.1111 degC 1: -20:3 degC 1: -6.666 degC ++ . . . . ++ ++ ' 20 degF @key{RET} u c degC @key{RET} U u t degC @key{RET} c f ++@end group ++@end smallexample ++ ++@noindent ++First we convert a change of 20 degrees Fahrenheit into an equivalent ++change in degrees Celsius (or Centigrade). Then, we convert the ++absolute temperature 20 degrees Fahrenheit into Celsius. Since ++this comes out as an exact fraction, we then convert to floating-point ++for easier comparison with the other result. ++ ++For simple unit conversions, you can put a plain number on the stack. ++Then @kbd{u c} and @kbd{u t} will prompt for both old and new units. ++When you use this method, you're responsible for remembering which ++numbers are in which units: ++ ++@smallexample ++@group ++1: 55 1: 88.5139 1: 8.201407e-8 ++ . . . ++ ++ 55 u c mph @key{RET} kph @key{RET} u c km/hr @key{RET} c @key{RET} ++@end group ++@end smallexample ++ ++To see a complete list of built-in units, type @kbd{u v}. Press ++@w{@kbd{C-x * c}} again to re-enter the Calculator when you're done looking ++at the units table. ++ ++(@bullet{}) @strong{Exercise 13.} How many seconds are there really ++in a year? @xref{Types Answer 13, 13}. (@bullet{}) ++ ++@cindex Speed of light ++(@bullet{}) @strong{Exercise 14.} Supercomputer designs are limited by ++the speed of light (and of electricity, which is nearly as fast). ++Suppose a computer has a 4.1 ns (nanosecond) clock cycle, and its ++cabinet is one meter across. Is speed of light going to be a ++significant factor in its design? @xref{Types Answer 14, 14}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 15.} Sam the Slug normally travels about ++five yards in an hour. He has obtained a supply of Power Pills; each ++Power Pill he eats doubles his speed. How many Power Pills can he ++swallow and still travel legally on most US highways? ++@xref{Types Answer 15, 15}. (@bullet{}) ++ ++@node Algebra Tutorial, Programming Tutorial, Types Tutorial, Tutorial ++@section Algebra and Calculus Tutorial ++ ++@noindent ++This section shows how to use Calc's algebra facilities to solve ++equations, do simple calculus problems, and manipulate algebraic ++formulas. ++ ++@menu ++* Basic Algebra Tutorial:: ++* Rewrites Tutorial:: ++@end menu ++ ++@node Basic Algebra Tutorial, Rewrites Tutorial, Algebra Tutorial, Algebra Tutorial ++@subsection Basic Algebra ++ ++@noindent ++If you enter a formula in Algebraic mode that refers to variables, ++the formula itself is pushed onto the stack. You can manipulate ++formulas as regular data objects. ++ ++@smallexample ++@group ++1: 2 x^2 - 6 1: 6 - 2 x^2 1: (6 - 2 x^2) (3 x^2 + y) ++ . . . ++ ++ ' 2x^2-6 @key{RET} n ' 3x^2+y @key{RET} * ++@end group ++@end smallexample ++ ++(@bullet{}) @strong{Exercise 1.} Do @kbd{' x @key{RET} Q 2 ^} and ++@kbd{' x @key{RET} 2 ^ Q} both wind up with the same result (@samp{x})? ++Why or why not? @xref{Algebra Answer 1, 1}. (@bullet{}) ++ ++There are also commands for doing common algebraic operations on ++formulas. Continuing with the formula from the last example, ++ ++@smallexample ++@group ++1: 18 x^2 + 6 y - 6 x^4 - 2 x^2 y 1: (18 - 2 y) x^2 - 6 x^4 + 6 y ++ . . ++ ++ a x a c x @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++First we ``expand'' using the distributive law, then we ``collect'' ++terms involving like powers of @expr{x}. ++ ++Let's find the value of this expression when @expr{x} is 2 and @expr{y} ++is one-half. ++ ++@smallexample ++@group ++1: 17 x^2 - 6 x^4 + 3 1: -25 ++ . . ++ ++ 1:2 s l y @key{RET} 2 s l x @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++The @kbd{s l} command means ``let''; it takes a number from the top of ++the stack and temporarily assigns it as the value of the variable ++you specify. It then evaluates (as if by the @kbd{=} key) the ++next expression on the stack. After this command, the variable goes ++back to its original value, if any. ++ ++(An earlier exercise in this tutorial involved storing a value in the ++variable @code{x}; if this value is still there, you will have to ++unstore it with @kbd{s u x @key{RET}} before the above example will work ++properly.) ++ ++@cindex Maximum of a function using Calculus ++Let's find the maximum value of our original expression when @expr{y} ++is one-half and @expr{x} ranges over all possible values. We can ++do this by taking the derivative with respect to @expr{x} and examining ++values of @expr{x} for which the derivative is zero. If the second ++derivative of the function at that value of @expr{x} is negative, ++the function has a local maximum there. ++ ++@smallexample ++@group ++1: 17 x^2 - 6 x^4 + 3 1: 34 x - 24 x^3 ++ . . ++ ++ U @key{DEL} s 1 a d x @key{RET} s 2 ++@end group ++@end smallexample ++ ++@noindent ++Well, the derivative is clearly zero when @expr{x} is zero. To find ++the other root(s), let's divide through by @expr{x} and then solve: ++ ++@smallexample ++@group ++1: (34 x - 24 x^3) / x 1: 34 x / x - 24 x^3 / x 1: 34 - 24 x^2 ++ . . . ++ ++ ' x @key{RET} / a x a s ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: 34 - 24 x^2 = 0 1: x = 1.19023 ++ . . ++ ++ 0 a = s 3 a S x @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++Notice the use of @kbd{a s} to ``simplify'' the formula. When the ++default algebraic simplifications don't do enough, you can use ++@kbd{a s} to tell Calc to spend more time on the job. ++ ++Now we compute the second derivative and plug in our values of @expr{x}: ++ ++@smallexample ++@group ++1: 1.19023 2: 1.19023 2: 1.19023 ++ . 1: 34 x - 24 x^3 1: 34 - 72 x^2 ++ . . ++ ++ a . r 2 a d x @key{RET} s 4 ++@end group ++@end smallexample ++ ++@noindent ++(The @kbd{a .} command extracts just the righthand side of an equation. ++Another method would have been to use @kbd{v u} to unpack the equation ++@w{@samp{x = 1.19}} to @samp{x} and @samp{1.19}, then use @kbd{M-- M-2 @key{DEL}} ++to delete the @samp{x}.) ++ ++@smallexample ++@group ++2: 34 - 72 x^2 1: -68. 2: 34 - 72 x^2 1: 34 ++1: 1.19023 . 1: 0 . ++ . . ++ ++ @key{TAB} s l x @key{RET} U @key{DEL} 0 s l x @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++The first of these second derivatives is negative, so we know the function ++has a maximum value at @expr{x = 1.19023}. (The function also has a ++local @emph{minimum} at @expr{x = 0}.) ++ ++When we solved for @expr{x}, we got only one value even though ++@expr{34 - 24 x^2 = 0} is a quadratic equation that ought to have ++two solutions. The reason is that @w{@kbd{a S}} normally returns a ++single ``principal'' solution. If it needs to come up with an ++arbitrary sign (as occurs in the quadratic formula) it picks @expr{+}. ++If it needs an arbitrary integer, it picks zero. We can get a full ++solution by pressing @kbd{H} (the Hyperbolic flag) before @kbd{a S}. ++ ++@smallexample ++@group ++1: 34 - 24 x^2 = 0 1: x = 1.19023 s1 1: x = -1.19023 ++ . . . ++ ++ r 3 H a S x @key{RET} s 5 1 n s l s1 @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++Calc has invented the variable @samp{s1} to represent an unknown sign; ++it is supposed to be either @mathit{+1} or @mathit{-1}. Here we have used ++the ``let'' command to evaluate the expression when the sign is negative. ++If we plugged this into our second derivative we would get the same, ++negative, answer, so @expr{x = -1.19023} is also a maximum. ++ ++To find the actual maximum value, we must plug our two values of @expr{x} ++into the original formula. ++ ++@smallexample ++@group ++2: 17 x^2 - 6 x^4 + 3 1: 24.08333 s1^2 - 12.04166 s1^4 + 3 ++1: x = 1.19023 s1 . ++ . ++ ++ r 1 r 5 s l @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++(Here we see another way to use @kbd{s l}; if its input is an equation ++with a variable on the lefthand side, then @kbd{s l} treats the equation ++like an assignment to that variable if you don't give a variable name.) ++ ++It's clear that this will have the same value for either sign of ++@code{s1}, but let's work it out anyway, just for the exercise: ++ ++@smallexample ++@group ++2: [-1, 1] 1: [15.04166, 15.04166] ++1: 24.08333 s1^2 ... . ++ . ++ ++ [ 1 n , 1 ] @key{TAB} V M $ @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++Here we have used a vector mapping operation to evaluate the function ++at several values of @samp{s1} at once. @kbd{V M $} is like @kbd{V M '} ++except that it takes the formula from the top of the stack. The ++formula is interpreted as a function to apply across the vector at the ++next-to-top stack level. Since a formula on the stack can't contain ++@samp{$} signs, Calc assumes the variables in the formula stand for ++different arguments. It prompts you for an @dfn{argument list}, giving ++the list of all variables in the formula in alphabetical order as the ++default list. In this case the default is @samp{(s1)}, which is just ++what we want so we simply press @key{RET} at the prompt. ++ ++If there had been several different values, we could have used ++@w{@kbd{V R X}} to find the global maximum. ++ ++Calc has a built-in @kbd{a P} command that solves an equation using ++@w{@kbd{H a S}} and returns a vector of all the solutions. It simply ++automates the job we just did by hand. Applied to our original ++cubic polynomial, it would produce the vector of solutions ++@expr{[1.19023, -1.19023, 0]}. (There is also an @kbd{a X} command ++which finds a local maximum of a function. It uses a numerical search ++method rather than examining the derivatives, and thus requires you ++to provide some kind of initial guess to show it where to look.) ++ ++(@bullet{}) @strong{Exercise 2.} Given a vector of the roots of a ++polynomial (such as the output of an @kbd{a P} command), what ++sequence of commands would you use to reconstruct the original ++polynomial? (The answer will be unique to within a constant ++multiple; choose the solution where the leading coefficient is one.) ++@xref{Algebra Answer 2, 2}. (@bullet{}) ++ ++The @kbd{m s} command enables Symbolic mode, in which formulas ++like @samp{sqrt(5)} that can't be evaluated exactly are left in ++symbolic form rather than giving a floating-point approximate answer. ++Fraction mode (@kbd{m f}) is also useful when doing algebra. ++ ++@smallexample ++@group ++2: 34 x - 24 x^3 2: 34 x - 24 x^3 ++1: 34 x - 24 x^3 1: [sqrt(51) / 6, sqrt(51) / -6, 0] ++ . . ++ ++ r 2 @key{RET} m s m f a P x @key{RET} ++@end group ++@end smallexample ++ ++One more mode that makes reading formulas easier is Big mode. ++ ++@smallexample ++@group ++ 3 ++2: 34 x - 24 x ++ ++ ____ ____ ++ V 51 V 51 ++1: [-----, -----, 0] ++ 6 -6 ++ ++ . ++ ++ d B ++@end group ++@end smallexample ++ ++Here things like powers, square roots, and quotients and fractions ++are displayed in a two-dimensional pictorial form. Calc has other ++language modes as well, such as C mode, FORTRAN mode, @TeX{} mode ++and La@TeX{} mode. ++ ++@smallexample ++@group ++2: 34*x - 24*pow(x, 3) 2: 34*x - 24*x**3 ++1: @{sqrt(51) / 6, sqrt(51) / -6, 0@} 1: /sqrt(51) / 6, sqrt(51) / -6, 0/ ++ . . ++ ++ d C d F ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++3: 34 x - 24 x^3 ++2: [@{\sqrt@{51@} \over 6@}, @{\sqrt@{51@} \over -6@}, 0] ++1: @{2 \over 3@} \sqrt@{5@} ++ . ++ ++ d T ' 2 \sqrt@{5@} \over 3 @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++As you can see, language modes affect both entry and display of ++formulas. They affect such things as the names used for built-in ++functions, the set of arithmetic operators and their precedences, ++and notations for vectors and matrices. ++ ++Notice that @samp{sqrt(51)} may cause problems with older ++implementations of C and FORTRAN, which would require something more ++like @samp{sqrt(51.0)}. It is always wise to check over the formulas ++produced by the various language modes to make sure they are fully ++correct. ++ ++Type @kbd{m s}, @kbd{m f}, and @kbd{d N} to reset these modes. (You ++may prefer to remain in Big mode, but all the examples in the tutorial ++are shown in normal mode.) ++ ++@cindex Area under a curve ++What is the area under the portion of this curve from @expr{x = 1} to @expr{2}? ++This is simply the integral of the function: ++ ++@smallexample ++@group ++1: 17 x^2 - 6 x^4 + 3 1: 5.6666 x^3 - 1.2 x^5 + 3 x ++ . . ++ ++ r 1 a i x ++@end group ++@end smallexample ++ ++@noindent ++We want to evaluate this at our two values for @expr{x} and subtract. ++One way to do it is again with vector mapping and reduction: ++ ++@smallexample ++@group ++2: [2, 1] 1: [12.93333, 7.46666] 1: 5.46666 ++1: 5.6666 x^3 ... . . ++ ++ [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - ++@end group ++@end smallexample ++ ++(@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @expr{y} ++of ++@texline @math{x \sin \pi x} ++@infoline @w{@expr{x sin(pi x)}} ++(where the sine is calculated in radians). Find the values of the ++integral for integers @expr{y} from 1 to 5. @xref{Algebra Answer 3, ++3}. (@bullet{}) ++ ++Calc's integrator can do many simple integrals symbolically, but many ++others are beyond its capabilities. Suppose we wish to find the area ++under the curve ++@texline @math{\sin x \ln x} ++@infoline @expr{sin(x) ln(x)} ++over the same range of @expr{x}. If you entered this formula and typed ++@kbd{a i x @key{RET}} (don't bother to try this), Calc would work for a ++long time but would be unable to find a solution. In fact, there is no ++closed-form solution to this integral. Now what do we do? ++ ++@cindex Integration, numerical ++@cindex Numerical integration ++One approach would be to do the integral numerically. It is not hard ++to do this by hand using vector mapping and reduction. It is rather ++slow, though, since the sine and logarithm functions take a long time. ++We can save some time by reducing the working precision. ++ ++@smallexample ++@group ++3: 10 1: [1, 1.1, 1.2, ... , 1.8, 1.9] ++2: 1 . ++1: 0.1 ++ . ++ ++ 10 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x ++@end group ++@end smallexample ++ ++@noindent ++(Note that we have used the extended version of @kbd{v x}; we could ++also have used plain @kbd{v x} as follows: @kbd{v x 10 @key{RET} 9 + .1 *}.) ++ ++@smallexample ++@group ++2: [1, 1.1, ... ] 1: [0., 0.084941, 0.16993, ... ] ++1: sin(x) ln(x) . ++ . ++ ++ ' sin(x) ln(x) @key{RET} s 1 m r p 5 @key{RET} V M $ @key{RET} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: 3.4195 0.34195 ++ . . ++ ++ V R + 0.1 * ++@end group ++@end smallexample ++ ++@noindent ++(If you got wildly different results, did you remember to switch ++to Radians mode?) ++ ++Here we have divided the curve into ten segments of equal width; ++approximating these segments as rectangular boxes (i.e., assuming ++the curve is nearly flat at that resolution), we compute the areas ++of the boxes (height times width), then sum the areas. (It is ++faster to sum first, then multiply by the width, since the width ++is the same for every box.) ++ ++The true value of this integral turns out to be about 0.374, so ++we're not doing too well. Let's try another approach. ++ ++@smallexample ++@group ++1: sin(x) ln(x) 1: 0.84147 x - 0.84147 + 0.11957 (x - 1)^2 - ... ++ . . ++ ++ r 1 a t x=1 @key{RET} 4 @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++Here we have computed the Taylor series expansion of the function ++about the point @expr{x=1}. We can now integrate this polynomial ++approximation, since polynomials are easy to integrate. ++ ++@smallexample ++@group ++1: 0.42074 x^2 + ... 1: [-0.0446, -0.42073] 1: 0.3761 ++ . . . ++ ++ a i x @key{RET} [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - ++@end group ++@end smallexample ++ ++@noindent ++Better! By increasing the precision and/or asking for more terms ++in the Taylor series, we can get a result as accurate as we like. ++(Taylor series converge better away from singularities in the ++function such as the one at @code{ln(0)}, so it would also help to ++expand the series about the points @expr{x=2} or @expr{x=1.5} instead ++of @expr{x=1}.) ++ ++@cindex Simpson's rule ++@cindex Integration by Simpson's rule ++(@bullet{}) @strong{Exercise 4.} Our first method approximated the ++curve by stairsteps of width 0.1; the total area was then the sum ++of the areas of the rectangles under these stairsteps. Our second ++method approximated the function by a polynomial, which turned out ++to be a better approximation than stairsteps. A third method is ++@dfn{Simpson's rule}, which is like the stairstep method except ++that the steps are not required to be flat. Simpson's rule boils ++down to the formula, ++ ++@ifnottex ++@example ++(h/3) * (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + ... ++ + 2 f(a+(n-2)*h) + 4 f(a+(n-1)*h) + f(a+n*h)) ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ \displaylines{ ++ \qquad {h \over 3} (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + \cdots ++ \hfill \cr \hfill {} + 2 f(a+(n-2)h) + 4 f(a+(n-1)h) + f(a+n h)) \qquad ++} $$ ++\afterdisplay ++@end tex ++ ++@noindent ++where @expr{n} (which must be even) is the number of slices and @expr{h} ++is the width of each slice. These are 10 and 0.1 in our example. ++For reference, here is the corresponding formula for the stairstep ++method: ++ ++@ifnottex ++@example ++h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ... ++ + f(a+(n-2)*h) + f(a+(n-1)*h)) ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots ++ + f(a+(n-2)h) + f(a+(n-1)h)) $$ ++\afterdisplay ++@end tex ++ ++Compute the integral from 1 to 2 of ++@texline @math{\sin x \ln x} ++@infoline @expr{sin(x) ln(x)} ++using Simpson's rule with 10 slices. ++@xref{Algebra Answer 4, 4}. (@bullet{}) ++ ++Calc has a built-in @kbd{a I} command for doing numerical integration. ++It uses @dfn{Romberg's method}, which is a more sophisticated cousin ++of Simpson's rule. In particular, it knows how to keep refining the ++result until the current precision is satisfied. ++ ++@c [fix-ref Selecting Sub-Formulas] ++Aside from the commands we've seen so far, Calc also provides a ++large set of commands for operating on parts of formulas. You ++indicate the desired sub-formula by placing the cursor on any part ++of the formula before giving a @dfn{selection} command. Selections won't ++be covered in the tutorial; @pxref{Selecting Subformulas}, for ++details and examples. ++ ++@c hard exercise: simplify (2^(n r) - 2^(r*(n - 1))) / (2^r - 1) 2^(n - 1) ++@c to 2^((n-1)*(r-1)). ++ ++@node Rewrites Tutorial, , Basic Algebra Tutorial, Algebra Tutorial ++@subsection Rewrite Rules ++ ++@noindent ++No matter how many built-in commands Calc provided for doing algebra, ++there would always be something you wanted to do that Calc didn't have ++in its repertoire. So Calc also provides a @dfn{rewrite rule} system ++that you can use to define your own algebraic manipulations. ++ ++Suppose we want to simplify this trigonometric formula: ++ ++@smallexample ++@group ++1: 1 / cos(x) - sin(x) tan(x) ++ . ++ ++ ' 1/cos(x) - sin(x) tan(x) @key{RET} s 1 ++@end group ++@end smallexample ++ ++@noindent ++If we were simplifying this by hand, we'd probably replace the ++@samp{tan} with a @samp{sin/cos} first, then combine over a common ++denominator. There is no Calc command to do the former; the @kbd{a n} ++algebra command will do the latter but we'll do both with rewrite ++rules just for practice. ++ ++Rewrite rules are written with the @samp{:=} symbol. ++ ++@smallexample ++@group ++1: 1 / cos(x) - sin(x)^2 / cos(x) ++ . ++ ++ a r tan(a) := sin(a)/cos(a) @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++(The ``assignment operator'' @samp{:=} has several uses in Calc. All ++by itself the formula @samp{tan(a) := sin(a)/cos(a)} doesn't do anything, ++but when it is given to the @kbd{a r} command, that command interprets ++it as a rewrite rule.) ++ ++The lefthand side, @samp{tan(a)}, is called the @dfn{pattern} of the ++rewrite rule. Calc searches the formula on the stack for parts that ++match the pattern. Variables in a rewrite pattern are called ++@dfn{meta-variables}, and when matching the pattern each meta-variable ++can match any sub-formula. Here, the meta-variable @samp{a} matched ++the actual variable @samp{x}. ++ ++When the pattern part of a rewrite rule matches a part of the formula, ++that part is replaced by the righthand side with all the meta-variables ++substituted with the things they matched. So the result is ++@samp{sin(x) / cos(x)}. Calc's normal algebraic simplifications then ++mix this in with the rest of the original formula. ++ ++To merge over a common denominator, we can use another simple rule: ++ ++@smallexample ++@group ++1: (1 - sin(x)^2) / cos(x) ++ . ++ ++ a r a/x + b/x := (a+b)/x @key{RET} ++@end group ++@end smallexample ++ ++This rule points out several interesting features of rewrite patterns. ++First, if a meta-variable appears several times in a pattern, it must ++match the same thing everywhere. This rule detects common denominators ++because the same meta-variable @samp{x} is used in both of the ++denominators. ++ ++Second, meta-variable names are independent from variables in the ++target formula. Notice that the meta-variable @samp{x} here matches ++the subformula @samp{cos(x)}; Calc never confuses the two meanings of ++@samp{x}. ++ ++And third, rewrite patterns know a little bit about the algebraic ++properties of formulas. The pattern called for a sum of two quotients; ++Calc was able to match a difference of two quotients by matching ++@samp{a = 1}, @samp{b = -sin(x)^2}, and @samp{x = cos(x)}. ++ ++@c [fix-ref Algebraic Properties of Rewrite Rules] ++We could just as easily have written @samp{a/x - b/x := (a-b)/x} for ++the rule. It would have worked just the same in all cases. (If we ++really wanted the rule to apply only to @samp{+} or only to @samp{-}, ++we could have used the @code{plain} symbol. @xref{Algebraic Properties ++of Rewrite Rules}, for some examples of this.) ++ ++One more rewrite will complete the job. We want to use the identity ++@samp{sin(x)^2 + cos(x)^2 = 1}, but of course we must first rearrange ++the identity in a way that matches our formula. The obvious rule ++would be @samp{@w{1 - sin(x)^2} := cos(x)^2}, but a little thought shows ++that the rule @samp{sin(x)^2 := 1 - cos(x)^2} will also work. The ++latter rule has a more general pattern so it will work in many other ++situations, too. ++ ++@smallexample ++@group ++1: (1 + cos(x)^2 - 1) / cos(x) 1: cos(x) ++ . . ++ ++ a r sin(x)^2 := 1 - cos(x)^2 @key{RET} a s ++@end group ++@end smallexample ++ ++You may ask, what's the point of using the most general rule if you ++have to type it in every time anyway? The answer is that Calc allows ++you to store a rewrite rule in a variable, then give the variable ++name in the @kbd{a r} command. In fact, this is the preferred way to ++use rewrites. For one, if you need a rule once you'll most likely ++need it again later. Also, if the rule doesn't work quite right you ++can simply Undo, edit the variable, and run the rule again without ++having to retype it. ++ ++@smallexample ++@group ++' tan(x) := sin(x)/cos(x) @key{RET} s t tsc @key{RET} ++' a/x + b/x := (a+b)/x @key{RET} s t merge @key{RET} ++' sin(x)^2 := 1 - cos(x)^2 @key{RET} s t sinsqr @key{RET} ++ ++1: 1 / cos(x) - sin(x) tan(x) 1: cos(x) ++ . . ++ ++ r 1 a r tsc @key{RET} a r merge @key{RET} a r sinsqr @key{RET} a s ++@end group ++@end smallexample ++ ++To edit a variable, type @kbd{s e} and the variable name, use regular ++Emacs editing commands as necessary, then type @kbd{C-c C-c} to store ++the edited value back into the variable. ++You can also use @w{@kbd{s e}} to create a new variable if you wish. ++ ++Notice that the first time you use each rule, Calc puts up a ``compiling'' ++message briefly. The pattern matcher converts rules into a special ++optimized pattern-matching language rather than using them directly. ++This allows @kbd{a r} to apply even rather complicated rules very ++efficiently. If the rule is stored in a variable, Calc compiles it ++only once and stores the compiled form along with the variable. That's ++another good reason to store your rules in variables rather than ++entering them on the fly. ++ ++(@bullet{}) @strong{Exercise 1.} Type @kbd{m s} to get Symbolic ++mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}. ++Using a rewrite rule, simplify this formula by multiplying the top and ++bottom by the conjugate @w{@samp{1 - sqrt(2)}}. The result will have ++to be expanded by the distributive law; do this with another ++rewrite. @xref{Rewrites Answer 1, 1}. (@bullet{}) ++ ++The @kbd{a r} command can also accept a vector of rewrite rules, or ++a variable containing a vector of rules. ++ ++@smallexample ++@group ++1: [tsc, merge, sinsqr] 1: [tan(x) := sin(x) / cos(x), ... ] ++ . . ++ ++ ' [tsc,merge,sinsqr] @key{RET} = ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: 1 / cos(x) - sin(x) tan(x) 1: cos(x) ++ . . ++ ++ s t trig @key{RET} r 1 a r trig @key{RET} a s ++@end group ++@end smallexample ++ ++@c [fix-ref Nested Formulas with Rewrite Rules] ++Calc tries all the rules you give against all parts of the formula, ++repeating until no further change is possible. (The exact order in ++which things are tried is rather complex, but for simple rules like ++the ones we've used here the order doesn't really matter. ++@xref{Nested Formulas with Rewrite Rules}.) ++ ++Calc actually repeats only up to 100 times, just in case your rule set ++has gotten into an infinite loop. You can give a numeric prefix argument ++to @kbd{a r} to specify any limit. In particular, @kbd{M-1 a r} does ++only one rewrite at a time. ++ ++@smallexample ++@group ++1: 1 / cos(x) - sin(x)^2 / cos(x) 1: (1 - sin(x)^2) / cos(x) ++ . . ++ ++ r 1 M-1 a r trig @key{RET} M-1 a r trig @key{RET} ++@end group ++@end smallexample ++ ++You can type @kbd{M-0 a r} if you want no limit at all on the number ++of rewrites that occur. ++ ++Rewrite rules can also be @dfn{conditional}. Simply follow the rule ++with a @samp{::} symbol and the desired condition. For example, ++ ++@smallexample ++@group ++1: exp(2 pi i) + exp(3 pi i) + exp(4 pi i) ++ . ++ ++ ' exp(2 pi i) + exp(3 pi i) + exp(4 pi i) @key{RET} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: 1 + exp(3 pi i) + 1 ++ . ++ ++ a r exp(k pi i) := 1 :: k % 2 = 0 @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++(Recall, @samp{k % 2} is the remainder from dividing @samp{k} by 2, ++which will be zero only when @samp{k} is an even integer.) ++ ++An interesting point is that the variables @samp{pi} and @samp{i} ++were matched literally rather than acting as meta-variables. ++This is because they are special-constant variables. The special ++constants @samp{e}, @samp{phi}, and so on also match literally. ++A common error with rewrite ++rules is to write, say, @samp{f(a,b,c,d,e) := g(a+b+c+d+e)}, expecting ++to match any @samp{f} with five arguments but in fact matching ++only when the fifth argument is literally @samp{e}! ++ ++@cindex Fibonacci numbers ++@ignore ++@starindex ++@end ignore ++@tindex fib ++Rewrite rules provide an interesting way to define your own functions. ++Suppose we want to define @samp{fib(n)} to produce the @var{n}th ++Fibonacci number. The first two Fibonacci numbers are each 1; ++later numbers are formed by summing the two preceding numbers in ++the sequence. This is easy to express in a set of three rules: ++ ++@smallexample ++@group ++' [fib(1) := 1, fib(2) := 1, fib(n) := fib(n-1) + fib(n-2)] @key{RET} s t fib ++ ++1: fib(7) 1: 13 ++ . . ++ ++ ' fib(7) @key{RET} a r fib @key{RET} ++@end group ++@end smallexample ++ ++One thing that is guaranteed about the order that rewrites are tried ++is that, for any given subformula, earlier rules in the rule set will ++be tried for that subformula before later ones. So even though the ++first and third rules both match @samp{fib(1)}, we know the first will ++be used preferentially. ++ ++This rule set has one dangerous bug: Suppose we apply it to the ++formula @samp{fib(x)}? (Don't actually try this.) The third rule ++will match @samp{fib(x)} and replace it with @w{@samp{fib(x-1) + fib(x-2)}}. ++Each of these will then be replaced to get @samp{fib(x-2) + 2 fib(x-3) + ++fib(x-4)}, and so on, expanding forever. What we really want is to apply ++the third rule only when @samp{n} is an integer greater than two. Type ++@w{@kbd{s e fib @key{RET}}}, then edit the third rule to: ++ ++@smallexample ++fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 ++@end smallexample ++ ++@noindent ++Now: ++ ++@smallexample ++@group ++1: fib(6) + fib(x) + fib(0) 1: 8 + fib(x) + fib(0) ++ . . ++ ++ ' fib(6)+fib(x)+fib(0) @key{RET} a r fib @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++We've created a new function, @code{fib}, and a new command, ++@w{@kbd{a r fib @key{RET}}}, which means ``evaluate all @code{fib} calls in ++this formula.'' To make things easier still, we can tell Calc to ++apply these rules automatically by storing them in the special ++variable @code{EvalRules}. ++ ++@smallexample ++@group ++1: [fib(1) := ...] . 1: [8, 13] ++ . . ++ ++ s r fib @key{RET} s t EvalRules @key{RET} ' [fib(6), fib(7)] @key{RET} ++@end group ++@end smallexample ++ ++It turns out that this rule set has the problem that it does far ++more work than it needs to when @samp{n} is large. Consider the ++first few steps of the computation of @samp{fib(6)}: ++ ++@smallexample ++@group ++fib(6) = ++fib(5) + fib(4) = ++fib(4) + fib(3) + fib(3) + fib(2) = ++fib(3) + fib(2) + fib(2) + fib(1) + fib(2) + fib(1) + 1 = ... ++@end group ++@end smallexample ++ ++@noindent ++Note that @samp{fib(3)} appears three times here. Unless Calc's ++algebraic simplifier notices the multiple @samp{fib(3)}s and combines ++them (and, as it happens, it doesn't), this rule set does lots of ++needless recomputation. To cure the problem, type @code{s e EvalRules} ++to edit the rules (or just @kbd{s E}, a shorthand command for editing ++@code{EvalRules}) and add another condition: ++ ++@smallexample ++fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 :: remember ++@end smallexample ++ ++@noindent ++If a @samp{:: remember} condition appears anywhere in a rule, then if ++that rule succeeds Calc will add another rule that describes that match ++to the front of the rule set. (Remembering works in any rule set, but ++for technical reasons it is most effective in @code{EvalRules}.) For ++example, if the rule rewrites @samp{fib(7)} to something that evaluates ++to 13, then the rule @samp{fib(7) := 13} will be added to the rule set. ++ ++Type @kbd{' fib(8) @key{RET}} to compute the eighth Fibonacci number, then ++type @kbd{s E} again to see what has happened to the rule set. ++ ++With the @code{remember} feature, our rule set can now compute ++@samp{fib(@var{n})} in just @var{n} steps. In the process it builds ++up a table of all Fibonacci numbers up to @var{n}. After we have ++computed the result for a particular @var{n}, we can get it back ++(and the results for all smaller @var{n}) later in just one step. ++ ++All Calc operations will run somewhat slower whenever @code{EvalRules} ++contains any rules. You should type @kbd{s u EvalRules @key{RET}} now to ++un-store the variable. ++ ++(@bullet{}) @strong{Exercise 2.} Sometimes it is possible to reformulate ++a problem to reduce the amount of recursion necessary to solve it. ++Create a rule that, in about @var{n} simple steps and without recourse ++to the @code{remember} option, replaces @samp{fib(@var{n}, 1, 1)} with ++@samp{fib(1, @var{x}, @var{y})} where @var{x} and @var{y} are the ++@var{n}th and @var{n+1}st Fibonacci numbers, respectively. This rule is ++rather clunky to use, so add a couple more rules to make the ``user ++interface'' the same as for our first version: enter @samp{fib(@var{n})}, ++get back a plain number. @xref{Rewrites Answer 2, 2}. (@bullet{}) ++ ++There are many more things that rewrites can do. For example, there ++are @samp{&&&} and @samp{|||} pattern operators that create ``and'' ++and ``or'' combinations of rules. As one really simple example, we ++could combine our first two Fibonacci rules thusly: ++ ++@example ++[fib(1 ||| 2) := 1, fib(n) := ... ] ++@end example ++ ++@noindent ++That means ``@code{fib} of something matching either 1 or 2 rewrites ++to 1.'' ++ ++You can also make meta-variables optional by enclosing them in @code{opt}. ++For example, the pattern @samp{a + b x} matches @samp{2 + 3 x} but not ++@samp{2 + x} or @samp{3 x} or @samp{x}. The pattern @samp{opt(a) + opt(b) x} ++matches all of these forms, filling in a default of zero for @samp{a} ++and one for @samp{b}. ++ ++(@bullet{}) @strong{Exercise 3.} Your friend Joe had @samp{2 + 3 x} ++on the stack and tried to use the rule ++@samp{opt(a) + opt(b) x := f(a, b, x)}. What happened? ++@xref{Rewrites Answer 3, 3}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 4.} Starting with a positive integer @expr{a}, ++divide @expr{a} by two if it is even, otherwise compute @expr{3 a + 1}. ++Now repeat this step over and over. A famous unproved conjecture ++is that for any starting @expr{a}, the sequence always eventually ++reaches 1. Given the formula @samp{seq(@var{a}, 0)}, write a set of ++rules that convert this into @samp{seq(1, @var{n})} where @var{n} ++is the number of steps it took the sequence to reach the value 1. ++Now enhance the rules to accept @samp{seq(@var{a})} as a starting ++configuration, and to stop with just the number @var{n} by itself. ++Now make the result be a vector of values in the sequence, from @var{a} ++to 1. (The formula @samp{@var{x}|@var{y}} appends the vectors @var{x} ++and @var{y}.) For example, rewriting @samp{seq(6)} should yield the ++vector @expr{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. ++@xref{Rewrites Answer 4, 4}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 5.} Define, using rewrite rules, a function ++@samp{nterms(@var{x})} that returns the number of terms in the sum ++@var{x}, or 1 if @var{x} is not a sum. (A @dfn{sum} for our purposes ++is one or more non-sum terms separated by @samp{+} or @samp{-} signs, ++so that @expr{2 - 3 (x + y) + x y} is a sum of three terms.) ++@xref{Rewrites Answer 5, 5}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 6.} A Taylor series for a function is an ++infinite series that exactly equals the value of that function at ++values of @expr{x} near zero. ++ ++@ifnottex ++@example ++cos(x) = 1 - x^2 / 2! + x^4 / 4! - x^6 / 6! + ... ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ \cos x = 1 - {x^2 \over 2!} + {x^4 \over 4!} - {x^6 \over 6!} + \cdots $$ ++\afterdisplay ++@end tex ++ ++The @kbd{a t} command produces a @dfn{truncated Taylor series} which ++is obtained by dropping all the terms higher than, say, @expr{x^2}. ++Calc represents the truncated Taylor series as a polynomial in @expr{x}. ++Mathematicians often write a truncated series using a ``big-O'' notation ++that records what was the lowest term that was truncated. ++ ++@ifnottex ++@example ++cos(x) = 1 - x^2 / 2! + O(x^3) ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ \cos x = 1 - {x^2 \over 2!} + O(x^3) $$ ++\afterdisplay ++@end tex ++ ++@noindent ++The meaning of @expr{O(x^3)} is ``a quantity which is negligibly small ++if @expr{x^3} is considered negligibly small as @expr{x} goes to zero.'' ++ ++The exercise is to create rewrite rules that simplify sums and products of ++power series represented as @samp{@var{polynomial} + O(@var{var}^@var{n})}. ++For example, given @samp{1 - x^2 / 2 + O(x^3)} and @samp{x - x^3 / 6 + O(x^4)} ++on the stack, we want to be able to type @kbd{*} and get the result ++@samp{x - 2:3 x^3 + O(x^4)}. Don't worry if the terms of the sum are ++rearranged or if @kbd{a s} needs to be typed after rewriting. (This one ++is rather tricky; the solution at the end of this chapter uses 6 rewrite ++rules. Hint: The @samp{constant(x)} condition tests whether @samp{x} is ++a number.) @xref{Rewrites Answer 6, 6}. (@bullet{}) ++ ++Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}. ++What happens? (Be sure to remove this rule afterward, or you might get ++a nasty surprise when you use Calc to balance your checkbook!) ++ ++@xref{Rewrite Rules}, for the whole story on rewrite rules. ++ ++@node Programming Tutorial, Answers to Exercises, Algebra Tutorial, Tutorial ++@section Programming Tutorial ++ ++@noindent ++The Calculator is written entirely in Emacs Lisp, a highly extensible ++language. If you know Lisp, you can program the Calculator to do ++anything you like. Rewrite rules also work as a powerful programming ++system. But Lisp and rewrite rules take a while to master, and often ++all you want to do is define a new function or repeat a command a few ++times. Calc has features that allow you to do these things easily. ++ ++One very limited form of programming is defining your own functions. ++Calc's @kbd{Z F} command allows you to define a function name and ++key sequence to correspond to any formula. Programming commands use ++the shift-@kbd{Z} prefix; the user commands they create use the lower ++case @kbd{z} prefix. ++ ++@smallexample ++@group ++1: 1 + x + x^2 / 2 + x^3 / 6 1: 1 + x + x^2 / 2 + x^3 / 6 ++ . . ++ ++ ' 1 + x + x^2/2! + x^3/3! @key{RET} Z F e myexp @key{RET} @key{RET} @key{RET} y ++@end group ++@end smallexample ++ ++This polynomial is a Taylor series approximation to @samp{exp(x)}. ++The @kbd{Z F} command asks a number of questions. The above answers ++say that the key sequence for our function should be @kbd{z e}; the ++@kbd{M-x} equivalent should be @code{calc-myexp}; the name of the ++function in algebraic formulas should also be @code{myexp}; the ++default argument list @samp{(x)} is acceptable; and finally @kbd{y} ++answers the question ``leave it in symbolic form for non-constant ++arguments?'' ++ ++@smallexample ++@group ++1: 1.3495 2: 1.3495 3: 1.3495 ++ . 1: 1.34986 2: 1.34986 ++ . 1: myexp(a + 1) ++ . ++ ++ .3 z e .3 E ' a+1 @key{RET} z e ++@end group ++@end smallexample ++ ++@noindent ++First we call our new @code{exp} approximation with 0.3 as an ++argument, and compare it with the true @code{exp} function. Then ++we note that, as requested, if we try to give @kbd{z e} an ++argument that isn't a plain number, it leaves the @code{myexp} ++function call in symbolic form. If we had answered @kbd{n} to the ++final question, @samp{myexp(a + 1)} would have evaluated by plugging ++in @samp{a + 1} for @samp{x} in the defining formula. ++ ++@cindex Sine integral Si(x) ++@ignore ++@starindex ++@end ignore ++@tindex Si ++(@bullet{}) @strong{Exercise 1.} The ``sine integral'' function ++@texline @math{{\rm Si}(x)} ++@infoline @expr{Si(x)} ++is defined as the integral of @samp{sin(t)/t} for ++@expr{t = 0} to @expr{x} in radians. (It was invented because this ++integral has no solution in terms of basic functions; if you give it ++to Calc's @kbd{a i} command, it will ponder it for a long time and then ++give up.) We can use the numerical integration command, however, ++which in algebraic notation is written like @samp{ninteg(f(t), t, 0, x)} ++with any integrand @samp{f(t)}. Define a @kbd{z s} command and ++@code{Si} function that implement this. You will need to edit the ++default argument list a bit. As a test, @samp{Si(1)} should return ++0.946083. (If you don't get this answer, you might want to check that ++Calc is in Radians mode. Also, @code{ninteg} will run a lot faster if ++you reduce the precision to, say, six digits beforehand.) ++@xref{Programming Answer 1, 1}. (@bullet{}) ++ ++The simplest way to do real ``programming'' of Emacs is to define a ++@dfn{keyboard macro}. A keyboard macro is simply a sequence of ++keystrokes which Emacs has stored away and can play back on demand. ++For example, if you find yourself typing @kbd{H a S x @key{RET}} often, ++you may wish to program a keyboard macro to type this for you. ++ ++@smallexample ++@group ++1: y = sqrt(x) 1: x = y^2 ++ . . ++ ++ ' y=sqrt(x) @key{RET} C-x ( H a S x @key{RET} C-x ) ++ ++1: y = cos(x) 1: x = s1 arccos(y) + 2 pi n1 ++ . . ++ ++ ' y=cos(x) @key{RET} X ++@end group ++@end smallexample ++ ++@noindent ++When you type @kbd{C-x (}, Emacs begins recording. But it is also ++still ready to execute your keystrokes, so you're really ``training'' ++Emacs by walking it through the procedure once. When you type ++@w{@kbd{C-x )}}, the macro is recorded. You can now type @kbd{X} to ++re-execute the same keystrokes. ++ ++You can give a name to your macro by typing @kbd{Z K}. ++ ++@smallexample ++@group ++1: . 1: y = x^4 1: x = s2 sqrt(s1 sqrt(y)) ++ . . ++ ++ Z K x @key{RET} ' y=x^4 @key{RET} z x ++@end group ++@end smallexample ++ ++@noindent ++Notice that we use shift-@kbd{Z} to define the command, and lower-case ++@kbd{z} to call it up. ++ ++Keyboard macros can call other macros. ++ ++@smallexample ++@group ++1: abs(x) 1: x = s1 y 1: 2 / x 1: x = 2 / y ++ . . . . ++ ++ ' abs(x) @key{RET} C-x ( ' y @key{RET} a = z x C-x ) ' 2/x @key{RET} X ++@end group ++@end smallexample ++ ++(@bullet{}) @strong{Exercise 2.} Define a keyboard macro to negate ++the item in level 3 of the stack, without disturbing the rest of ++the stack. @xref{Programming Answer 2, 2}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 3.} Define keyboard macros to compute ++the following functions: ++ ++@enumerate ++@item ++Compute ++@texline @math{\displaystyle{\sin x \over x}}, ++@infoline @expr{sin(x) / x}, ++where @expr{x} is the number on the top of the stack. ++ ++@item ++Compute the base-@expr{b} logarithm, just like the @kbd{B} key except ++the arguments are taken in the opposite order. ++ ++@item ++Produce a vector of integers from 1 to the integer on the top of ++the stack. ++@end enumerate ++@noindent ++@xref{Programming Answer 3, 3}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 4.} Define a keyboard macro to compute ++the average (mean) value of a list of numbers. ++@xref{Programming Answer 4, 4}. (@bullet{}) ++ ++In many programs, some of the steps must execute several times. ++Calc has @dfn{looping} commands that allow this. Loops are useful ++inside keyboard macros, but actually work at any time. ++ ++@smallexample ++@group ++1: x^6 2: x^6 1: 360 x^2 ++ . 1: 4 . ++ . ++ ++ ' x^6 @key{RET} 4 Z < a d x @key{RET} Z > ++@end group ++@end smallexample ++ ++@noindent ++Here we have computed the fourth derivative of @expr{x^6} by ++enclosing a derivative command in a ``repeat loop'' structure. ++This structure pops a repeat count from the stack, then ++executes the body of the loop that many times. ++ ++If you make a mistake while entering the body of the loop, ++type @w{@kbd{Z C-g}} to cancel the loop command. ++ ++@cindex Fibonacci numbers ++Here's another example: ++ ++@smallexample ++@group ++3: 1 2: 10946 ++2: 1 1: 17711 ++1: 20 . ++ . ++ ++1 @key{RET} @key{RET} 20 Z < @key{TAB} C-j + Z > ++@end group ++@end smallexample ++ ++@noindent ++The numbers in levels 2 and 1 should be the 21st and 22nd Fibonacci ++numbers, respectively. (To see what's going on, try a few repetitions ++of the loop body by hand; @kbd{C-j}, also on the Line-Feed or @key{LFD} ++key if you have one, makes a copy of the number in level 2.) ++ ++@cindex Golden ratio ++@cindex Phi, golden ratio ++A fascinating property of the Fibonacci numbers is that the @expr{n}th ++Fibonacci number can be found directly by computing ++@texline @math{\phi^n / \sqrt{5}} ++@infoline @expr{phi^n / sqrt(5)} ++and then rounding to the nearest integer, where ++@texline @math{\phi} (``phi''), ++@infoline @expr{phi}, ++the ``golden ratio,'' is ++@texline @math{(1 + \sqrt{5}) / 2}. ++@infoline @expr{(1 + sqrt(5)) / 2}. ++(For convenience, this constant is available from the @code{phi} ++variable, or the @kbd{I H P} command.) ++ ++@smallexample ++@group ++1: 1.61803 1: 24476.0000409 1: 10945.9999817 1: 10946 ++ . . . . ++ ++ I H P 21 ^ 5 Q / R ++@end group ++@end smallexample ++ ++@cindex Continued fractions ++(@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction} ++representation of ++@texline @math{\phi} ++@infoline @expr{phi} ++is ++@texline @math{1 + 1/(1 + 1/(1 + 1/( \ldots )))}. ++@infoline @expr{1 + 1/(1 + 1/(1 + 1/( ...@: )))}. ++We can compute an approximate value by carrying this however far ++and then replacing the innermost ++@texline @math{1/( \ldots )} ++@infoline @expr{1/( ...@: )} ++by 1. Approximate ++@texline @math{\phi} ++@infoline @expr{phi} ++using a twenty-term continued fraction. ++@xref{Programming Answer 5, 5}. (@bullet{}) ++ ++(@bullet{}) @strong{Exercise 6.} Linear recurrences like the one for ++Fibonacci numbers can be expressed in terms of matrices. Given a ++vector @w{@expr{[a, b]}} determine a matrix which, when multiplied by this ++vector, produces the vector @expr{[b, c]}, where @expr{a}, @expr{b} and ++@expr{c} are three successive Fibonacci numbers. Now write a program ++that, given an integer @expr{n}, computes the @expr{n}th Fibonacci number ++using matrix arithmetic. @xref{Programming Answer 6, 6}. (@bullet{}) ++ ++@cindex Harmonic numbers ++A more sophisticated kind of loop is the @dfn{for} loop. Suppose ++we wish to compute the 20th ``harmonic'' number, which is equal to ++the sum of the reciprocals of the integers from 1 to 20. ++ ++@smallexample ++@group ++3: 0 1: 3.597739 ++2: 1 . ++1: 20 ++ . ++ ++0 @key{RET} 1 @key{RET} 20 Z ( & + 1 Z ) ++@end group ++@end smallexample ++ ++@noindent ++The ``for'' loop pops two numbers, the lower and upper limits, then ++repeats the body of the loop as an internal counter increases from ++the lower limit to the upper one. Just before executing the loop ++body, it pushes the current loop counter. When the loop body ++finishes, it pops the ``step,'' i.e., the amount by which to ++increment the loop counter. As you can see, our loop always ++uses a step of one. ++ ++This harmonic number function uses the stack to hold the running ++total as well as for the various loop housekeeping functions. If ++you find this disorienting, you can sum in a variable instead: ++ ++@smallexample ++@group ++1: 0 2: 1 . 1: 3.597739 ++ . 1: 20 . ++ . ++ ++ 0 t 7 1 @key{RET} 20 Z ( & s + 7 1 Z ) r 7 ++@end group ++@end smallexample ++ ++@noindent ++The @kbd{s +} command adds the top-of-stack into the value in a ++variable (and removes that value from the stack). ++ ++It's worth noting that many jobs that call for a ``for'' loop can ++also be done more easily by Calc's high-level operations. Two ++other ways to compute harmonic numbers are to use vector mapping ++and reduction (@kbd{v x 20}, then @w{@kbd{V M &}}, then @kbd{V R +}), ++or to use the summation command @kbd{a +}. Both of these are ++probably easier than using loops. However, there are some ++situations where loops really are the way to go: ++ ++(@bullet{}) @strong{Exercise 7.} Use a ``for'' loop to find the first ++harmonic number which is greater than 4.0. ++@xref{Programming Answer 7, 7}. (@bullet{}) ++ ++Of course, if we're going to be using variables in our programs, ++we have to worry about the programs clobbering values that the ++caller was keeping in those same variables. This is easy to ++fix, though: ++ ++@smallexample ++@group ++ . 1: 0.6667 1: 0.6667 3: 0.6667 ++ . . 2: 3.597739 ++ 1: 0.6667 ++ . ++ ++ Z ` p 4 @key{RET} 2 @key{RET} 3 / s 7 s s a @key{RET} Z ' r 7 s r a @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++When we type @kbd{Z `} (that's a back-quote character), Calc saves ++its mode settings and the contents of the ten ``quick variables'' ++for later reference. When we type @kbd{Z '} (that's an apostrophe ++now), Calc restores those saved values. Thus the @kbd{p 4} and ++@kbd{s 7} commands have no effect outside this sequence. Wrapping ++this around the body of a keyboard macro ensures that it doesn't ++interfere with what the user of the macro was doing. Notice that ++the contents of the stack, and the values of named variables, ++survive past the @kbd{Z '} command. ++ ++@cindex Bernoulli numbers, approximate ++The @dfn{Bernoulli numbers} are a sequence with the interesting ++property that all of the odd Bernoulli numbers are zero, and the ++even ones, while difficult to compute, can be roughly approximated ++by the formula ++@texline @math{\displaystyle{2 n! \over (2 \pi)^n}}. ++@infoline @expr{2 n!@: / (2 pi)^n}. ++Let's write a keyboard macro to compute (approximate) Bernoulli numbers. ++(Calc has a command, @kbd{k b}, to compute exact Bernoulli numbers, but ++this command is very slow for large @expr{n} since the higher Bernoulli ++numbers are very large fractions.) ++ ++@smallexample ++@group ++1: 10 1: 0.0756823 ++ . . ++ ++ 10 C-x ( @key{RET} 2 % Z [ @key{DEL} 0 Z : ' 2 $! / (2 pi)^$ @key{RET} = Z ] C-x ) ++@end group ++@end smallexample ++ ++@noindent ++You can read @kbd{Z [} as ``then,'' @kbd{Z :} as ``else,'' and ++@kbd{Z ]} as ``end-if.'' There is no need for an explicit ``if'' ++command. For the purposes of @w{@kbd{Z [}}, the condition is ``true'' ++if the value it pops from the stack is a nonzero number, or ``false'' ++if it pops zero or something that is not a number (like a formula). ++Here we take our integer argument modulo 2; this will be nonzero ++if we're asking for an odd Bernoulli number. ++ ++The actual tenth Bernoulli number is @expr{5/66}. ++ ++@smallexample ++@group ++3: 0.0756823 1: 0 1: 0.25305 1: 0 1: 1.16659 ++2: 5:66 . . . . ++1: 0.0757575 ++ . ++ ++10 k b @key{RET} c f M-0 @key{DEL} 11 X @key{DEL} 12 X @key{DEL} 13 X @key{DEL} 14 X ++@end group ++@end smallexample ++ ++Just to exercise loops a bit more, let's compute a table of even ++Bernoulli numbers. ++ ++@smallexample ++@group ++3: [] 1: [0.10132, 0.03079, 0.02340, 0.033197, ...] ++2: 2 . ++1: 30 ++ . ++ ++ [ ] 2 @key{RET} 30 Z ( X | 2 Z ) ++@end group ++@end smallexample ++ ++@noindent ++The vertical-bar @kbd{|} is the vector-concatenation command. When ++we execute it, the list we are building will be in stack level 2 ++(initially this is an empty list), and the next Bernoulli number ++will be in level 1. The effect is to append the Bernoulli number ++onto the end of the list. (To create a table of exact fractional ++Bernoulli numbers, just replace @kbd{X} with @kbd{k b} in the above ++sequence of keystrokes.) ++ ++With loops and conditionals, you can program essentially anything ++in Calc. One other command that makes looping easier is @kbd{Z /}, ++which takes a condition from the stack and breaks out of the enclosing ++loop if the condition is true (non-zero). You can use this to make ++``while'' and ``until'' style loops. ++ ++If you make a mistake when entering a keyboard macro, you can edit ++it using @kbd{Z E}. First, you must attach it to a key with @kbd{Z K}. ++One technique is to enter a throwaway dummy definition for the macro, ++then enter the real one in the edit command. ++ ++@smallexample ++@group ++1: 3 1: 3 Calc Macro Edit Mode. ++ . . Original keys: 1 2 + ++ ++ 1 ;; calc digits ++ RET ;; calc-enter ++ 2 ;; calc digits ++ + ;; calc-plus ++ ++C-x ( 1 @key{RET} 2 + C-x ) Z K h @key{RET} Z E h ++@end group ++@end smallexample ++ ++@noindent ++A keyboard macro is stored as a pure keystroke sequence. The ++@file{edmacro} package (invoked by @kbd{Z E}) scans along the ++macro and tries to decode it back into human-readable steps. ++Descriptions of the keystrokes are given as comments, which begin with ++@samp{;;}, and which are ignored when the edited macro is saved. ++Spaces and line breaks are also ignored when the edited macro is saved. ++To enter a space into the macro, type @code{SPC}. All the special ++characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL}, ++and @code{NUL} must be written in all uppercase, as must the prefixes ++@code{C-} and @code{M-}. ++ ++Let's edit in a new definition, for computing harmonic numbers. ++First, erase the four lines of the old definition. Then, type ++in the new definition (or use Emacs @kbd{M-w} and @kbd{C-y} commands ++to copy it from this page of the Info file; you can of course skip ++typing the comments, which begin with @samp{;;}). ++ ++@smallexample ++Z` ;; calc-kbd-push (Save local values) ++0 ;; calc digits (Push a zero onto the stack) ++st ;; calc-store-into (Store it in the following variable) ++1 ;; calc quick variable (Quick variable q1) ++1 ;; calc digits (Initial value for the loop) ++TAB ;; calc-roll-down (Swap initial and final) ++Z( ;; calc-kbd-for (Begin the "for" loop) ++& ;; calc-inv (Take the reciprocal) ++s+ ;; calc-store-plus (Add to the following variable) ++1 ;; calc quick variable (Quick variable q1) ++1 ;; calc digits (The loop step is 1) ++Z) ;; calc-kbd-end-for (End the "for" loop) ++sr ;; calc-recall (Recall the final accumulated value) ++1 ;; calc quick variable (Quick variable q1) ++Z' ;; calc-kbd-pop (Restore values) ++@end smallexample ++ ++@noindent ++Press @kbd{C-c C-c} to finish editing and return to the Calculator. ++ ++@smallexample ++@group ++1: 20 1: 3.597739 ++ . . ++ ++ 20 z h ++@end group ++@end smallexample ++ ++The @file{edmacro} package defines a handy @code{read-kbd-macro} command ++which reads the current region of the current buffer as a sequence of ++keystroke names, and defines that sequence on the @kbd{X} ++(and @kbd{C-x e}) key. Because this is so useful, Calc puts this ++command on the @kbd{C-x * m} key. Try reading in this macro in the ++following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at ++one end of the text below, then type @kbd{C-x * m} at the other. ++ ++@example ++@group ++Z ` 0 t 1 ++ 1 TAB ++ Z ( & s + 1 1 Z ) ++ r 1 ++Z ' ++@end group ++@end example ++ ++(@bullet{}) @strong{Exercise 8.} A general algorithm for solving ++equations numerically is @dfn{Newton's Method}. Given the equation ++@expr{f(x) = 0} for any function @expr{f}, and an initial guess ++@expr{x_0} which is reasonably close to the desired solution, apply ++this formula over and over: ++ ++@ifnottex ++@example ++new_x = x - f(x)/f'(x) ++@end example ++@end ifnottex ++@tex ++\beforedisplay ++$$ x_{\rm new} = x - {f(x) \over f'(x)} $$ ++\afterdisplay ++@end tex ++ ++@noindent ++where @expr{f'(x)} is the derivative of @expr{f}. The @expr{x} ++values will quickly converge to a solution, i.e., eventually ++@texline @math{x_{\rm new}} ++@infoline @expr{new_x} ++and @expr{x} will be equal to within the limits ++of the current precision. Write a program which takes a formula ++involving the variable @expr{x}, and an initial guess @expr{x_0}, ++on the stack, and produces a value of @expr{x} for which the formula ++is zero. Use it to find a solution of ++@texline @math{\sin(\cos x) = 0.5} ++@infoline @expr{sin(cos(x)) = 0.5} ++near @expr{x = 4.5}. (Use angles measured in radians.) Note that ++the built-in @w{@kbd{a R}} (@code{calc-find-root}) command uses Newton's ++method when it is able. @xref{Programming Answer 8, 8}. (@bullet{}) ++ ++@cindex Digamma function ++@cindex Gamma constant, Euler's ++@cindex Euler's gamma constant ++(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function ++@texline @math{\psi(z) (``psi'')} ++@infoline @expr{psi(z)} ++is defined as the derivative of ++@texline @math{\ln \Gamma(z)}. ++@infoline @expr{ln(gamma(z))}. ++For large values of @expr{z}, it can be approximated by the infinite sum ++ ++@ifnottex ++@example ++psi(z) ~= ln(z) - 1/2z - sum(bern(2 n) / 2 n z^(2 n), n, 1, inf) ++@end example ++@end ifnottex ++@tex ++\beforedisplay ++$$ \psi(z) \approx \ln z - {1\over2z} - ++ \sum_{n=1}^\infty {\code{bern}(2 n) \over 2 n z^{2n}} ++$$ ++\afterdisplay ++@end tex ++ ++@noindent ++where ++@texline @math{\sum} ++@infoline @expr{sum} ++represents the sum over @expr{n} from 1 to infinity ++(or to some limit high enough to give the desired accuracy), and ++the @code{bern} function produces (exact) Bernoulli numbers. ++While this sum is not guaranteed to converge, in practice it is safe. ++An interesting mathematical constant is Euler's gamma, which is equal ++to about 0.5772. One way to compute it is by the formula, ++@texline @math{\gamma = -\psi(1)}. ++@infoline @expr{gamma = -psi(1)}. ++Unfortunately, 1 isn't a large enough argument ++for the above formula to work (5 is a much safer value for @expr{z}). ++Fortunately, we can compute ++@texline @math{\psi(1)} ++@infoline @expr{psi(1)} ++from ++@texline @math{\psi(5)} ++@infoline @expr{psi(5)} ++using the recurrence ++@texline @math{\psi(z+1) = \psi(z) + {1 \over z}}. ++@infoline @expr{psi(z+1) = psi(z) + 1/z}. ++Your task: Develop a program to compute ++@texline @math{\psi(z)}; ++@infoline @expr{psi(z)}; ++it should ``pump up'' @expr{z} ++if necessary to be greater than 5, then use the above summation ++formula. Use looping commands to compute the sum. Use your function ++to compute ++@texline @math{\gamma} ++@infoline @expr{gamma} ++to twelve decimal places. (Calc has a built-in command ++for Euler's constant, @kbd{I P}, which you can use to check your answer.) ++@xref{Programming Answer 9, 9}. (@bullet{}) ++ ++@cindex Polynomial, list of coefficients ++(@bullet{}) @strong{Exercise 10.} Given a polynomial in @expr{x} and ++a number @expr{m} on the stack, where the polynomial is of degree ++@expr{m} or less (i.e., does not have any terms higher than @expr{x^m}), ++write a program to convert the polynomial into a list-of-coefficients ++notation. For example, @expr{5 x^4 + (x + 1)^2} with @expr{m = 6} ++should produce the list @expr{[1, 2, 1, 0, 5, 0, 0]}. Also develop ++a way to convert from this form back to the standard algebraic form. ++@xref{Programming Answer 10, 10}. (@bullet{}) ++ ++@cindex Recursion ++(@bullet{}) @strong{Exercise 11.} The @dfn{Stirling numbers of the ++first kind} are defined by the recurrences, ++ ++@ifnottex ++@example ++s(n,n) = 1 for n >= 0, ++s(n,0) = 0 for n > 0, ++s(n+1,m) = s(n,m-1) - n s(n,m) for n >= m >= 1. ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ \eqalign{ s(n,n) &= 1 \qquad \hbox{for } n \ge 0, \cr ++ s(n,0) &= 0 \qquad \hbox{for } n > 0, \cr ++ s(n+1,m) &= s(n,m-1) - n \, s(n,m) \qquad ++ \hbox{for } n \ge m \ge 1.} ++$$ ++\afterdisplay ++\vskip5pt ++(These numbers are also sometimes written $\displaystyle{n \brack m}$.) ++@end tex ++ ++This can be implemented using a @dfn{recursive} program in Calc; the ++program must invoke itself in order to calculate the two righthand ++terms in the general formula. Since it always invokes itself with ++``simpler'' arguments, it's easy to see that it must eventually finish ++the computation. Recursion is a little difficult with Emacs keyboard ++macros since the macro is executed before its definition is complete. ++So here's the recommended strategy: Create a ``dummy macro'' and assign ++it to a key with, e.g., @kbd{Z K s}. Now enter the true definition, ++using the @kbd{z s} command to call itself recursively, then assign it ++to the same key with @kbd{Z K s}. Now the @kbd{z s} command will run ++the complete recursive program. (Another way is to use @w{@kbd{Z E}} ++or @kbd{C-x * m} (@code{read-kbd-macro}) to read the whole macro at once, ++thus avoiding the ``training'' phase.) The task: Write a program ++that computes Stirling numbers of the first kind, given @expr{n} and ++@expr{m} on the stack. Test it with @emph{small} inputs like ++@expr{s(4,2)}. (There is a built-in command for Stirling numbers, ++@kbd{k s}, which you can use to check your answers.) ++@xref{Programming Answer 11, 11}. (@bullet{}) ++ ++The programming commands we've seen in this part of the tutorial ++are low-level, general-purpose operations. Often you will find ++that a higher-level function, such as vector mapping or rewrite ++rules, will do the job much more easily than a detailed, step-by-step ++program can: ++ ++(@bullet{}) @strong{Exercise 12.} Write another program for ++computing Stirling numbers of the first kind, this time using ++rewrite rules. Once again, @expr{n} and @expr{m} should be taken ++from the stack. @xref{Programming Answer 12, 12}. (@bullet{}) ++ ++@example ++ ++@end example ++This ends the tutorial section of the Calc manual. Now you know enough ++about Calc to use it effectively for many kinds of calculations. But ++Calc has many features that were not even touched upon in this tutorial. ++@c [not-split] ++The rest of this manual tells the whole story. ++@c [when-split] ++@c Volume II of this manual, the @dfn{Calc Reference}, tells the whole story. ++ ++@page ++@node Answers to Exercises, , Programming Tutorial, Tutorial ++@section Answers to Exercises ++ ++@noindent ++This section includes answers to all the exercises in the Calc tutorial. ++ ++@menu ++* RPN Answer 1:: 1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * - ++* RPN Answer 2:: 2*4 + 7*9.5 + 5/4 ++* RPN Answer 3:: Operating on levels 2 and 3 ++* RPN Answer 4:: Joe's complex problems ++* Algebraic Answer 1:: Simulating Q command ++* Algebraic Answer 2:: Joe's algebraic woes ++* Algebraic Answer 3:: 1 / 0 ++* Modes Answer 1:: 3#0.1 = 3#0.0222222? ++* Modes Answer 2:: 16#f.e8fe15 ++* Modes Answer 3:: Joe's rounding bug ++* Modes Answer 4:: Why floating point? ++* Arithmetic Answer 1:: Why the \ command? ++* Arithmetic Answer 2:: Tripping up the B command ++* Vector Answer 1:: Normalizing a vector ++* Vector Answer 2:: Average position ++* Matrix Answer 1:: Row and column sums ++* Matrix Answer 2:: Symbolic system of equations ++* Matrix Answer 3:: Over-determined system ++* List Answer 1:: Powers of two ++* List Answer 2:: Least-squares fit with matrices ++* List Answer 3:: Geometric mean ++* List Answer 4:: Divisor function ++* List Answer 5:: Duplicate factors ++* List Answer 6:: Triangular list ++* List Answer 7:: Another triangular list ++* List Answer 8:: Maximum of Bessel function ++* List Answer 9:: Integers the hard way ++* List Answer 10:: All elements equal ++* List Answer 11:: Estimating pi with darts ++* List Answer 12:: Estimating pi with matchsticks ++* List Answer 13:: Hash codes ++* List Answer 14:: Random walk ++* Types Answer 1:: Square root of pi times rational ++* Types Answer 2:: Infinities ++* Types Answer 3:: What can "nan" be? ++* Types Answer 4:: Abbey Road ++* Types Answer 5:: Friday the 13th ++* Types Answer 6:: Leap years ++* Types Answer 7:: Erroneous donut ++* Types Answer 8:: Dividing intervals ++* Types Answer 9:: Squaring intervals ++* Types Answer 10:: Fermat's primality test ++* Types Answer 11:: pi * 10^7 seconds ++* Types Answer 12:: Abbey Road on CD ++* Types Answer 13:: Not quite pi * 10^7 seconds ++* Types Answer 14:: Supercomputers and c ++* Types Answer 15:: Sam the Slug ++* Algebra Answer 1:: Squares and square roots ++* Algebra Answer 2:: Building polynomial from roots ++* Algebra Answer 3:: Integral of x sin(pi x) ++* Algebra Answer 4:: Simpson's rule ++* Rewrites Answer 1:: Multiplying by conjugate ++* Rewrites Answer 2:: Alternative fib rule ++* Rewrites Answer 3:: Rewriting opt(a) + opt(b) x ++* Rewrites Answer 4:: Sequence of integers ++* Rewrites Answer 5:: Number of terms in sum ++* Rewrites Answer 6:: Truncated Taylor series ++* Programming Answer 1:: Fresnel's C(x) ++* Programming Answer 2:: Negate third stack element ++* Programming Answer 3:: Compute sin(x) / x, etc. ++* Programming Answer 4:: Average value of a list ++* Programming Answer 5:: Continued fraction phi ++* Programming Answer 6:: Matrix Fibonacci numbers ++* Programming Answer 7:: Harmonic number greater than 4 ++* Programming Answer 8:: Newton's method ++* Programming Answer 9:: Digamma function ++* Programming Answer 10:: Unpacking a polynomial ++* Programming Answer 11:: Recursive Stirling numbers ++* Programming Answer 12:: Stirling numbers with rewrites ++@end menu ++ ++@c The following kludgery prevents the individual answers from ++@c being entered on the table of contents. ++@tex ++\global\let\oldwrite=\write ++\gdef\skipwrite#1#2{\let\write=\oldwrite} ++\global\let\oldchapternofonts=\chapternofonts ++\gdef\chapternofonts{\let\write=\skipwrite\oldchapternofonts} ++@end tex ++ ++@node RPN Answer 1, RPN Answer 2, Answers to Exercises, Answers to Exercises ++@subsection RPN Tutorial Exercise 1 ++ ++@noindent ++@kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -} ++ ++The result is ++@texline @math{1 - (2 \times (3 + 4)) = -13}. ++@infoline @expr{1 - (2 * (3 + 4)) = -13}. ++ ++@node RPN Answer 2, RPN Answer 3, RPN Answer 1, Answers to Exercises ++@subsection RPN Tutorial Exercise 2 ++ ++@noindent ++@texline @math{2\times4 + 7\times9.5 + {5\over4} = 75.75} ++@infoline @expr{2*4 + 7*9.5 + 5/4 = 75.75} ++ ++After computing the intermediate term ++@texline @math{2\times4 = 8}, ++@infoline @expr{2*4 = 8}, ++you can leave that result on the stack while you compute the second ++term. With both of these results waiting on the stack you can then ++compute the final term, then press @kbd{+ +} to add everything up. ++ ++@smallexample ++@group ++2: 2 1: 8 3: 8 2: 8 ++1: 4 . 2: 7 1: 66.5 ++ . 1: 9.5 . ++ . ++ ++ 2 @key{RET} 4 * 7 @key{RET} 9.5 * ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++4: 8 3: 8 2: 8 1: 75.75 ++3: 66.5 2: 66.5 1: 67.75 . ++2: 5 1: 1.25 . ++1: 4 . ++ . ++ ++ 5 @key{RET} 4 / + + ++@end group ++@end smallexample ++ ++Alternatively, you could add the first two terms before going on ++with the third term. ++ ++@smallexample ++@group ++2: 8 1: 74.5 3: 74.5 2: 74.5 1: 75.75 ++1: 66.5 . 2: 5 1: 1.25 . ++ . 1: 4 . ++ . ++ ++ ... + 5 @key{RET} 4 / + ++@end group ++@end smallexample ++ ++On an old-style RPN calculator this second method would have the ++advantage of using only three stack levels. But since Calc's stack ++can grow arbitrarily large this isn't really an issue. Which method ++you choose is purely a matter of taste. ++ ++@node RPN Answer 3, RPN Answer 4, RPN Answer 2, Answers to Exercises ++@subsection RPN Tutorial Exercise 3 ++ ++@noindent ++The @key{TAB} key provides a way to operate on the number in level 2. ++ ++@smallexample ++@group ++3: 10 3: 10 4: 10 3: 10 3: 10 ++2: 20 2: 30 3: 30 2: 30 2: 21 ++1: 30 1: 20 2: 20 1: 21 1: 30 ++ . . 1: 1 . . ++ . ++ ++ @key{TAB} 1 + @key{TAB} ++@end group ++@end smallexample ++ ++Similarly, @kbd{M-@key{TAB}} gives you access to the number in level 3. ++ ++@smallexample ++@group ++3: 10 3: 21 3: 21 3: 30 3: 11 ++2: 21 2: 30 2: 30 2: 11 2: 21 ++1: 30 1: 10 1: 11 1: 21 1: 30 ++ . . . . . ++ ++ M-@key{TAB} 1 + M-@key{TAB} M-@key{TAB} ++@end group ++@end smallexample ++ ++@node RPN Answer 4, Algebraic Answer 1, RPN Answer 3, Answers to Exercises ++@subsection RPN Tutorial Exercise 4 ++ ++@noindent ++Either @kbd{( 2 , 3 )} or @kbd{( 2 @key{SPC} 3 )} would have worked, ++but using both the comma and the space at once yields: ++ ++@smallexample ++@group ++1: ( ... 2: ( ... 1: (2, ... 2: (2, ... 2: (2, ... ++ . 1: 2 . 1: (2, ... 1: (2, 3) ++ . . . ++ ++ ( 2 , @key{SPC} 3 ) ++@end group ++@end smallexample ++ ++Joe probably tried to type @kbd{@key{TAB} @key{DEL}} to swap the ++extra incomplete object to the top of the stack and delete it. ++But a feature of Calc is that @key{DEL} on an incomplete object ++deletes just one component out of that object, so he had to press ++@key{DEL} twice to finish the job. ++ ++@smallexample ++@group ++2: (2, ... 2: (2, 3) 2: (2, 3) 1: (2, 3) ++1: (2, 3) 1: (2, ... 1: ( ... . ++ . . . ++ ++ @key{TAB} @key{DEL} @key{DEL} ++@end group ++@end smallexample ++ ++(As it turns out, deleting the second-to-top stack entry happens often ++enough that Calc provides a special key, @kbd{M-@key{DEL}}, to do just that. ++@kbd{M-@key{DEL}} is just like @kbd{@key{TAB} @key{DEL}}, except that it doesn't exhibit ++the ``feature'' that tripped poor Joe.) ++ ++@node Algebraic Answer 1, Algebraic Answer 2, RPN Answer 4, Answers to Exercises ++@subsection Algebraic Entry Tutorial Exercise 1 ++ ++@noindent ++Type @kbd{' sqrt($) @key{RET}}. ++ ++If the @kbd{Q} key is broken, you could use @kbd{' $^0.5 @key{RET}}. ++Or, RPN style, @kbd{0.5 ^}. ++ ++(Actually, @samp{$^1:2}, using the fraction one-half as the power, is ++a closer equivalent, since @samp{9^0.5} yields @expr{3.0} whereas ++@samp{sqrt(9)} and @samp{9^1:2} yield the exact integer @expr{3}.) ++ ++@node Algebraic Answer 2, Algebraic Answer 3, Algebraic Answer 1, Answers to Exercises ++@subsection Algebraic Entry Tutorial Exercise 2 ++ ++@noindent ++In the formula @samp{2 x (1+y)}, @samp{x} was interpreted as a function ++name with @samp{1+y} as its argument. Assigning a value to a variable ++has no relation to a function by the same name. Joe needed to use an ++explicit @samp{*} symbol here: @samp{2 x*(1+y)}. ++ ++@node Algebraic Answer 3, Modes Answer 1, Algebraic Answer 2, Answers to Exercises ++@subsection Algebraic Entry Tutorial Exercise 3 ++ ++@noindent ++The result from @kbd{1 @key{RET} 0 /} will be the formula @expr{1 / 0}. ++The ``function'' @samp{/} cannot be evaluated when its second argument ++is zero, so it is left in symbolic form. When you now type @kbd{0 *}, ++the result will be zero because Calc uses the general rule that ``zero ++times anything is zero.'' ++ ++@c [fix-ref Infinities] ++The @kbd{m i} command enables an @dfn{Infinite mode} in which @expr{1 / 0} ++results in a special symbol that represents ``infinity.'' If you ++multiply infinity by zero, Calc uses another special new symbol to ++show that the answer is ``indeterminate.'' @xref{Infinities}, for ++further discussion of infinite and indeterminate values. ++ ++@node Modes Answer 1, Modes Answer 2, Algebraic Answer 3, Answers to Exercises ++@subsection Modes Tutorial Exercise 1 ++ ++@noindent ++Calc always stores its numbers in decimal, so even though one-third has ++an exact base-3 representation (@samp{3#0.1}), it is still stored as ++0.3333333 (chopped off after 12 or however many decimal digits) inside ++the calculator's memory. When this inexact number is converted back ++to base 3 for display, it may still be slightly inexact. When we ++multiply this number by 3, we get 0.999999, also an inexact value. ++ ++When Calc displays a number in base 3, it has to decide how many digits ++to show. If the current precision is 12 (decimal) digits, that corresponds ++to @samp{12 / log10(3) = 25.15} base-3 digits. Because 25.15 is not an ++exact integer, Calc shows only 25 digits, with the result that stored ++numbers carry a little bit of extra information that may not show up on ++the screen. When Joe entered @samp{3#0.2}, the stored number 0.666666 ++happened to round to a pleasing value when it lost that last 0.15 of a ++digit, but it was still inexact in Calc's memory. When he divided by 2, ++he still got the dreaded inexact value 0.333333. (Actually, he divided ++0.666667 by 2 to get 0.333334, which is why he got something a little ++higher than @code{3#0.1} instead of a little lower.) ++ ++If Joe didn't want to be bothered with all this, he could have typed ++@kbd{M-24 d n} to display with one less digit than the default. (If ++you give @kbd{d n} a negative argument, it uses default-minus-that, ++so @kbd{M-- d n} would be an easier way to get the same effect.) Those ++inexact results would still be lurking there, but they would now be ++rounded to nice, natural-looking values for display purposes. (Remember, ++@samp{0.022222} in base 3 is like @samp{0.099999} in base 10; rounding ++off one digit will round the number up to @samp{0.1}.) Depending on the ++nature of your work, this hiding of the inexactness may be a benefit or ++a danger. With the @kbd{d n} command, Calc gives you the choice. ++ ++Incidentally, another consequence of all this is that if you type ++@kbd{M-30 d n} to display more digits than are ``really there,'' ++you'll see garbage digits at the end of the number. (In decimal ++display mode, with decimally-stored numbers, these garbage digits are ++always zero so they vanish and you don't notice them.) Because Calc ++rounds off that 0.15 digit, there is the danger that two numbers could ++be slightly different internally but still look the same. If you feel ++uneasy about this, set the @kbd{d n} precision to be a little higher ++than normal; you'll get ugly garbage digits, but you'll always be able ++to tell two distinct numbers apart. ++ ++An interesting side note is that most computers store their ++floating-point numbers in binary, and convert to decimal for display. ++Thus everyday programs have the same problem: Decimal 0.1 cannot be ++represented exactly in binary (try it: @kbd{0.1 d 2}), so @samp{0.1 * 10} ++comes out as an inexact approximation to 1 on some machines (though ++they generally arrange to hide it from you by rounding off one digit as ++we did above). Because Calc works in decimal instead of binary, you can ++be sure that numbers that look exact @emph{are} exact as long as you stay ++in decimal display mode. ++ ++It's not hard to show that any number that can be represented exactly ++in binary, octal, or hexadecimal is also exact in decimal, so the kinds ++of problems we saw in this exercise are likely to be severe only when ++you use a relatively unusual radix like 3. ++ ++@node Modes Answer 2, Modes Answer 3, Modes Answer 1, Answers to Exercises ++@subsection Modes Tutorial Exercise 2 ++ ++If the radix is 15 or higher, we can't use the letter @samp{e} to mark ++the exponent because @samp{e} is interpreted as a digit. When Calc ++needs to display scientific notation in a high radix, it writes ++@samp{16#F.E8F*16.^15}. You can enter a number like this as an ++algebraic entry. Also, pressing @kbd{e} without any digits before it ++normally types @kbd{1e}, but in a high radix it types @kbd{16.^} and ++puts you in algebraic entry: @kbd{16#f.e8f @key{RET} e 15 @key{RET} *} is another ++way to enter this number. ++ ++The reason Calc puts a decimal point in the @samp{16.^} is to prevent ++huge integers from being generated if the exponent is large (consider ++@samp{16#1.23*16^1000}, where we compute @samp{16^1000} as a giant ++exact integer and then throw away most of the digits when we multiply ++it by the floating-point @samp{16#1.23}). While this wouldn't normally ++matter for display purposes, it could give you a nasty surprise if you ++copied that number into a file and later moved it back into Calc. ++ ++@node Modes Answer 3, Modes Answer 4, Modes Answer 2, Answers to Exercises ++@subsection Modes Tutorial Exercise 3 ++ ++@noindent ++The answer he got was @expr{0.5000000000006399}. ++ ++The problem is not that the square operation is inexact, but that the ++sine of 45 that was already on the stack was accurate to only 12 places. ++Arbitrary-precision calculations still only give answers as good as ++their inputs. ++ ++The real problem is that there is no 12-digit number which, when ++squared, comes out to 0.5 exactly. The @kbd{f [} and @kbd{f ]} ++commands decrease or increase a number by one unit in the last ++place (according to the current precision). They are useful for ++determining facts like this. ++ ++@smallexample ++@group ++1: 0.707106781187 1: 0.500000000001 ++ . . ++ ++ 45 S 2 ^ ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: 0.707106781187 1: 0.707106781186 1: 0.499999999999 ++ . . . ++ ++ U @key{DEL} f [ 2 ^ ++@end group ++@end smallexample ++ ++A high-precision calculation must be carried out in high precision ++all the way. The only number in the original problem which was known ++exactly was the quantity 45 degrees, so the precision must be raised ++before anything is done after the number 45 has been entered in order ++for the higher precision to be meaningful. ++ ++@node Modes Answer 4, Arithmetic Answer 1, Modes Answer 3, Answers to Exercises ++@subsection Modes Tutorial Exercise 4 ++ ++@noindent ++Many calculations involve real-world quantities, like the width and ++height of a piece of wood or the volume of a jar. Such quantities ++can't be measured exactly anyway, and if the data that is input to ++a calculation is inexact, doing exact arithmetic on it is a waste ++of time. ++ ++Fractions become unwieldy after too many calculations have been ++done with them. For example, the sum of the reciprocals of the ++integers from 1 to 10 is 7381:2520. The sum from 1 to 30 is ++9304682830147:2329089562800. After a point it will take a long ++time to add even one more term to this sum, but a floating-point ++calculation of the sum will not have this problem. ++ ++Also, rational numbers cannot express the results of all calculations. ++There is no fractional form for the square root of two, so if you type ++@w{@kbd{2 Q}}, Calc has no choice but to give you a floating-point answer. ++ ++@node Arithmetic Answer 1, Arithmetic Answer 2, Modes Answer 4, Answers to Exercises ++@subsection Arithmetic Tutorial Exercise 1 ++ ++@noindent ++Dividing two integers that are larger than the current precision may ++give a floating-point result that is inaccurate even when rounded ++down to an integer. Consider @expr{123456789 / 2} when the current ++precision is 6 digits. The true answer is @expr{61728394.5}, but ++with a precision of 6 this will be rounded to ++@texline @math{12345700.0/2.0 = 61728500.0}. ++@infoline @expr{12345700.@: / 2.@: = 61728500.}. ++The result, when converted to an integer, will be off by 106. ++ ++Here are two solutions: Raise the precision enough that the ++floating-point round-off error is strictly to the right of the ++decimal point. Or, convert to Fraction mode so that @expr{123456789 / 2} ++produces the exact fraction @expr{123456789:2}, which can be rounded ++down by the @kbd{F} command without ever switching to floating-point ++format. ++ ++@node Arithmetic Answer 2, Vector Answer 1, Arithmetic Answer 1, Answers to Exercises ++@subsection Arithmetic Tutorial Exercise 2 ++ ++@noindent ++@kbd{27 @key{RET} 9 B} could give the exact result @expr{3:2}, but it ++does a floating-point calculation instead and produces @expr{1.5}. ++ ++Calc will find an exact result for a logarithm if the result is an integer ++or (when in Fraction mode) the reciprocal of an integer. But there is ++no efficient way to search the space of all possible rational numbers ++for an exact answer, so Calc doesn't try. ++ ++@node Vector Answer 1, Vector Answer 2, Arithmetic Answer 2, Answers to Exercises ++@subsection Vector Tutorial Exercise 1 ++ ++@noindent ++Duplicate the vector, compute its length, then divide the vector ++by its length: @kbd{@key{RET} A /}. ++ ++@smallexample ++@group ++1: [1, 2, 3] 2: [1, 2, 3] 1: [0.27, 0.53, 0.80] 1: 1. ++ . 1: 3.74165738677 . . ++ . ++ ++ r 1 @key{RET} A / A ++@end group ++@end smallexample ++ ++The final @kbd{A} command shows that the normalized vector does ++indeed have unit length. ++ ++@node Vector Answer 2, Matrix Answer 1, Vector Answer 1, Answers to Exercises ++@subsection Vector Tutorial Exercise 2 ++ ++@noindent ++The average position is equal to the sum of the products of the ++positions times their corresponding probabilities. This is the ++definition of the dot product operation. So all you need to do ++is to put the two vectors on the stack and press @kbd{*}. ++ ++@node Matrix Answer 1, Matrix Answer 2, Vector Answer 2, Answers to Exercises ++@subsection Matrix Tutorial Exercise 1 ++ ++@noindent ++The trick is to multiply by a vector of ones. Use @kbd{r 4 [1 1 1] *} to ++get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum. ++ ++@node Matrix Answer 2, Matrix Answer 3, Matrix Answer 1, Answers to Exercises ++@subsection Matrix Tutorial Exercise 2 ++ ++@ifnottex ++@example ++@group ++ x + a y = 6 ++ x + b y = 10 ++@end group ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ \eqalign{ x &+ a y = 6 \cr ++ x &+ b y = 10} ++$$ ++\afterdisplay ++@end tex ++ ++Just enter the righthand side vector, then divide by the lefthand side ++matrix as usual. ++ ++@smallexample ++@group ++1: [6, 10] 2: [6, 10] 1: [6 - 4 a / (b - a), 4 / (b - a) ] ++ . 1: [ [ 1, a ] . ++ [ 1, b ] ] ++ . ++ ++' [6 10] @key{RET} ' [1 a; 1 b] @key{RET} / ++@end group ++@end smallexample ++ ++This can be made more readable using @kbd{d B} to enable Big display ++mode: ++ ++@smallexample ++@group ++ 4 a 4 ++1: [6 - -----, -----] ++ b - a b - a ++@end group ++@end smallexample ++ ++Type @kbd{d N} to return to Normal display mode afterwards. ++ ++@node Matrix Answer 3, List Answer 1, Matrix Answer 2, Answers to Exercises ++@subsection Matrix Tutorial Exercise 3 ++ ++@noindent ++To solve ++@texline @math{A^T A \, X = A^T B}, ++@infoline @expr{trn(A) * A * X = trn(A) * B}, ++first we compute ++@texline @math{A' = A^T A} ++@infoline @expr{A2 = trn(A) * A} ++and ++@texline @math{B' = A^T B}; ++@infoline @expr{B2 = trn(A) * B}; ++now, we have a system ++@texline @math{A' X = B'} ++@infoline @expr{A2 * X = B2} ++which we can solve using Calc's @samp{/} command. ++ ++@ifnottex ++@example ++@group ++ a + 2b + 3c = 6 ++ 4a + 5b + 6c = 2 ++ 7a + 6b = 3 ++ 2a + 4b + 6c = 11 ++@end group ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplayh ++$$ \openup1\jot \tabskip=0pt plus1fil ++\halign to\displaywidth{\tabskip=0pt ++ $\hfil#$&$\hfil{}#{}$& ++ $\hfil#$&$\hfil{}#{}$& ++ $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr ++ a&+&2b&+&3c&=6 \cr ++ 4a&+&5b&+&6c&=2 \cr ++ 7a&+&6b& & &=3 \cr ++ 2a&+&4b&+&6c&=11 \cr} ++$$ ++\afterdisplayh ++@end tex ++ ++The first step is to enter the coefficient matrix. We'll store it in ++quick variable number 7 for later reference. Next, we compute the ++@texline @math{B'} ++@infoline @expr{B2} ++vector. ++ ++@smallexample ++@group ++1: [ [ 1, 2, 3 ] 2: [ [ 1, 4, 7, 2 ] 1: [57, 84, 96] ++ [ 4, 5, 6 ] [ 2, 5, 6, 4 ] . ++ [ 7, 6, 0 ] [ 3, 6, 0, 6 ] ] ++ [ 2, 4, 6 ] ] 1: [6, 2, 3, 11] ++ . . ++ ++' [1 2 3; 4 5 6; 7 6 0; 2 4 6] @key{RET} s 7 v t [6 2 3 11] * ++@end group ++@end smallexample ++ ++@noindent ++Now we compute the matrix ++@texline @math{A'} ++@infoline @expr{A2} ++and divide. ++ ++@smallexample ++@group ++2: [57, 84, 96] 1: [-11.64, 14.08, -3.64] ++1: [ [ 70, 72, 39 ] . ++ [ 72, 81, 60 ] ++ [ 39, 60, 81 ] ] ++ . ++ ++ r 7 v t r 7 * / ++@end group ++@end smallexample ++ ++@noindent ++(The actual computed answer will be slightly inexact due to ++round-off error.) ++ ++Notice that the answers are similar to those for the ++@texline @math{3\times3} ++@infoline 3x3 ++system solved in the text. That's because the fourth equation that was ++added to the system is almost identical to the first one multiplied ++by two. (If it were identical, we would have gotten the exact same ++answer since the ++@texline @math{4\times3} ++@infoline 4x3 ++system would be equivalent to the original ++@texline @math{3\times3} ++@infoline 3x3 ++system.) ++ ++Since the first and fourth equations aren't quite equivalent, they ++can't both be satisfied at once. Let's plug our answers back into ++the original system of equations to see how well they match. ++ ++@smallexample ++@group ++2: [-11.64, 14.08, -3.64] 1: [5.6, 2., 3., 11.2] ++1: [ [ 1, 2, 3 ] . ++ [ 4, 5, 6 ] ++ [ 7, 6, 0 ] ++ [ 2, 4, 6 ] ] ++ . ++ ++ r 7 @key{TAB} * ++@end group ++@end smallexample ++ ++@noindent ++This is reasonably close to our original @expr{B} vector, ++@expr{[6, 2, 3, 11]}. ++ ++@node List Answer 1, List Answer 2, Matrix Answer 3, Answers to Exercises ++@subsection List Tutorial Exercise 1 ++ ++@noindent ++We can use @kbd{v x} to build a vector of integers. This needs to be ++adjusted to get the range of integers we desire. Mapping @samp{-} ++across the vector will accomplish this, although it turns out the ++plain @samp{-} key will work just as well. ++ ++@smallexample ++@group ++2: 2 2: 2 ++1: [1, 2, 3, 4, 5, 6, 7, 8, 9] 1: [-4, -3, -2, -1, 0, 1, 2, 3, 4] ++ . . ++ ++ 2 v x 9 @key{RET} 5 V M - or 5 - ++@end group ++@end smallexample ++ ++@noindent ++Now we use @kbd{V M ^} to map the exponentiation operator across the ++vector. ++ ++@smallexample ++@group ++1: [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16] ++ . ++ ++ V M ^ ++@end group ++@end smallexample ++ ++@node List Answer 2, List Answer 3, List Answer 1, Answers to Exercises ++@subsection List Tutorial Exercise 2 ++ ++@noindent ++Given @expr{x} and @expr{y} vectors in quick variables 1 and 2 as before, ++the first job is to form the matrix that describes the problem. ++ ++@ifnottex ++@example ++ m*x + b*1 = y ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ m \times x + b \times 1 = y $$ ++\afterdisplay ++@end tex ++ ++Thus we want a ++@texline @math{19\times2} ++@infoline 19x2 ++matrix with our @expr{x} vector as one column and ++ones as the other column. So, first we build the column of ones, then ++we combine the two columns to form our @expr{A} matrix. ++ ++@smallexample ++@group ++2: [1.34, 1.41, 1.49, ... ] 1: [ [ 1.34, 1 ] ++1: [1, 1, 1, ...] [ 1.41, 1 ] ++ . [ 1.49, 1 ] ++ @dots{} ++ ++ r 1 1 v b 19 @key{RET} M-2 v p v t s 3 ++@end group ++@end smallexample ++ ++@noindent ++Now we compute ++@texline @math{A^T y} ++@infoline @expr{trn(A) * y} ++and ++@texline @math{A^T A} ++@infoline @expr{trn(A) * A} ++and divide. ++ ++@smallexample ++@group ++1: [33.36554, 13.613] 2: [33.36554, 13.613] ++ . 1: [ [ 98.0003, 41.63 ] ++ [ 41.63, 19 ] ] ++ . ++ ++ v t r 2 * r 3 v t r 3 * ++@end group ++@end smallexample ++ ++@noindent ++(Hey, those numbers look familiar!) ++ ++@smallexample ++@group ++1: [0.52141679, -0.425978] ++ . ++ ++ / ++@end group ++@end smallexample ++ ++Since we were solving equations of the form ++@texline @math{m \times x + b \times 1 = y}, ++@infoline @expr{m*x + b*1 = y}, ++these numbers should be @expr{m} and @expr{b}, respectively. Sure ++enough, they agree exactly with the result computed using @kbd{V M} and ++@kbd{V R}! ++ ++The moral of this story: @kbd{V M} and @kbd{V R} will probably solve ++your problem, but there is often an easier way using the higher-level ++arithmetic functions! ++ ++@c [fix-ref Curve Fitting] ++In fact, there is a built-in @kbd{a F} command that does least-squares ++fits. @xref{Curve Fitting}. ++ ++@node List Answer 3, List Answer 4, List Answer 2, Answers to Exercises ++@subsection List Tutorial Exercise 3 ++ ++@noindent ++Move to one end of the list and press @kbd{C-@@} (or @kbd{C-@key{SPC}} or ++whatever) to set the mark, then move to the other end of the list ++and type @w{@kbd{C-x * g}}. ++ ++@smallexample ++@group ++1: [2.3, 6, 22, 15.1, 7, 15, 14, 7.5, 2.5] ++ . ++@end group ++@end smallexample ++ ++To make things interesting, let's assume we don't know at a glance ++how many numbers are in this list. Then we could type: ++ ++@smallexample ++@group ++2: [2.3, 6, 22, ... ] 2: [2.3, 6, 22, ... ] ++1: [2.3, 6, 22, ... ] 1: 126356422.5 ++ . . ++ ++ @key{RET} V R * ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++2: 126356422.5 2: 126356422.5 1: 7.94652913734 ++1: [2.3, 6, 22, ... ] 1: 9 . ++ . . ++ ++ @key{TAB} v l I ^ ++@end group ++@end smallexample ++ ++@noindent ++(The @kbd{I ^} command computes the @var{n}th root of a number. ++You could also type @kbd{& ^} to take the reciprocal of 9 and ++then raise the number to that power.) ++ ++@node List Answer 4, List Answer 5, List Answer 3, Answers to Exercises ++@subsection List Tutorial Exercise 4 ++ ++@noindent ++A number @expr{j} is a divisor of @expr{n} if ++@texline @math{n \mathbin{\hbox{\code{\%}}} j = 0}. ++@infoline @samp{n % j = 0}. ++The first step is to get a vector that identifies the divisors. ++ ++@smallexample ++@group ++2: 30 2: [0, 0, 0, 2, ...] 1: [1, 1, 1, 0, ...] ++1: [1, 2, 3, 4, ...] 1: 0 . ++ . . ++ ++ 30 @key{RET} v x 30 @key{RET} s 1 V M % 0 V M a = s 2 ++@end group ++@end smallexample ++ ++@noindent ++This vector has 1's marking divisors of 30 and 0's marking non-divisors. ++ ++The zeroth divisor function is just the total number of divisors. ++The first divisor function is the sum of the divisors. ++ ++@smallexample ++@group ++1: 8 3: 8 2: 8 2: 8 ++ 2: [1, 2, 3, 4, ...] 1: [1, 2, 3, 0, ...] 1: 72 ++ 1: [1, 1, 1, 0, ...] . . ++ . ++ ++ V R + r 1 r 2 V M * V R + ++@end group ++@end smallexample ++ ++@noindent ++Once again, the last two steps just compute a dot product for which ++a simple @kbd{*} would have worked equally well. ++ ++@node List Answer 5, List Answer 6, List Answer 4, Answers to Exercises ++@subsection List Tutorial Exercise 5 ++ ++@noindent ++The obvious first step is to obtain the list of factors with @kbd{k f}. ++This list will always be in sorted order, so if there are duplicates ++they will be right next to each other. A suitable method is to compare ++the list with a copy of itself shifted over by one. ++ ++@smallexample ++@group ++1: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19, 0] ++ . 1: [3, 7, 7, 7, 19, 0] 1: [0, 3, 7, 7, 7, 19] ++ . . ++ ++ 19551 k f @key{RET} 0 | @key{TAB} 0 @key{TAB} | ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [0, 0, 1, 1, 0, 0] 1: 2 1: 0 ++ . . . ++ ++ V M a = V R + 0 a = ++@end group ++@end smallexample ++ ++@noindent ++Note that we have to arrange for both vectors to have the same length ++so that the mapping operation works; no prime factor will ever be ++zero, so adding zeros on the left and right is safe. From then on ++the job is pretty straightforward. ++ ++Incidentally, Calc provides the ++@texline @dfn{M@"obius} @math{\mu} ++@infoline @dfn{Moebius mu} ++function which is zero if and only if its argument is square-free. It ++would be a much more convenient way to do the above test in practice. ++ ++@node List Answer 6, List Answer 7, List Answer 5, Answers to Exercises ++@subsection List Tutorial Exercise 6 ++ ++@noindent ++First use @kbd{v x 6 @key{RET}} to get a list of integers, then @kbd{V M v x} ++to get a list of lists of integers! ++ ++@node List Answer 7, List Answer 8, List Answer 6, Answers to Exercises ++@subsection List Tutorial Exercise 7 ++ ++@noindent ++Here's one solution. First, compute the triangular list from the previous ++exercise and type @kbd{1 -} to subtract one from all the elements. ++ ++@smallexample ++@group ++1: [ [0], ++ [0, 1], ++ [0, 1, 2], ++ @dots{} ++ ++ 1 - ++@end group ++@end smallexample ++ ++The numbers down the lefthand edge of the list we desire are called ++the ``triangular numbers'' (now you know why!). The @expr{n}th ++triangular number is the sum of the integers from 1 to @expr{n}, and ++can be computed directly by the formula ++@texline @math{n (n+1) \over 2}. ++@infoline @expr{n * (n+1) / 2}. ++ ++@smallexample ++@group ++2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] ++1: [0, 1, 2, 3, 4, 5] 1: [0, 1, 3, 6, 10, 15] ++ . . ++ ++ v x 6 @key{RET} 1 - V M ' $ ($+1)/2 @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++Adding this list to the above list of lists produces the desired ++result: ++ ++@smallexample ++@group ++1: [ [0], ++ [1, 2], ++ [3, 4, 5], ++ [6, 7, 8, 9], ++ [10, 11, 12, 13, 14], ++ [15, 16, 17, 18, 19, 20] ] ++ . ++ ++ V M + ++@end group ++@end smallexample ++ ++If we did not know the formula for triangular numbers, we could have ++computed them using a @kbd{V U +} command. We could also have ++gotten them the hard way by mapping a reduction across the original ++triangular list. ++ ++@smallexample ++@group ++2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] ++1: [ [0], [0, 1], ... ] 1: [0, 1, 3, 6, 10, 15] ++ . . ++ ++ @key{RET} V M V R + ++@end group ++@end smallexample ++ ++@noindent ++(This means ``map a @kbd{V R +} command across the vector,'' and ++since each element of the main vector is itself a small vector, ++@kbd{V R +} computes the sum of its elements.) ++ ++@node List Answer 8, List Answer 9, List Answer 7, Answers to Exercises ++@subsection List Tutorial Exercise 8 ++ ++@noindent ++The first step is to build a list of values of @expr{x}. ++ ++@smallexample ++@group ++1: [1, 2, 3, ..., 21] 1: [0, 1, 2, ..., 20] 1: [0, 0.25, 0.5, ..., 5] ++ . . . ++ ++ v x 21 @key{RET} 1 - 4 / s 1 ++@end group ++@end smallexample ++ ++Next, we compute the Bessel function values. ++ ++@smallexample ++@group ++1: [0., 0.124, 0.242, ..., -0.328] ++ . ++ ++ V M ' besJ(1,$) @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++(Another way to do this would be @kbd{1 @key{TAB} V M f j}.) ++ ++A way to isolate the maximum value is to compute the maximum using ++@kbd{V R X}, then compare all the Bessel values with that maximum. ++ ++@smallexample ++@group ++2: [0., 0.124, 0.242, ... ] 1: [0, 0, 0, ... ] 2: [0, 0, 0, ... ] ++1: 0.5801562 . 1: 1 ++ . . ++ ++ @key{RET} V R X V M a = @key{RET} V R + @key{DEL} ++@end group ++@end smallexample ++ ++@noindent ++It's a good idea to verify, as in the last step above, that only ++one value is equal to the maximum. (After all, a plot of ++@texline @math{\sin x} ++@infoline @expr{sin(x)} ++might have many points all equal to the maximum value, 1.) ++ ++The vector we have now has a single 1 in the position that indicates ++the maximum value of @expr{x}. Now it is a simple matter to convert ++this back into the corresponding value itself. ++ ++@smallexample ++@group ++2: [0, 0, 0, ... ] 1: [0, 0., 0., ... ] 1: 1.75 ++1: [0, 0.25, 0.5, ... ] . . ++ . ++ ++ r 1 V M * V R + ++@end group ++@end smallexample ++ ++If @kbd{a =} had produced more than one @expr{1} value, this method ++would have given the sum of all maximum @expr{x} values; not very ++useful! In this case we could have used @kbd{v m} (@code{calc-mask-vector}) ++instead. This command deletes all elements of a ``data'' vector that ++correspond to zeros in a ``mask'' vector, leaving us with, in this ++example, a vector of maximum @expr{x} values. ++ ++The built-in @kbd{a X} command maximizes a function using more ++efficient methods. Just for illustration, let's use @kbd{a X} ++to maximize @samp{besJ(1,x)} over this same interval. ++ ++@smallexample ++@group ++2: besJ(1, x) 1: [1.84115, 0.581865] ++1: [0 .. 5] . ++ . ++ ++' besJ(1,x), [0..5] @key{RET} a X x @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++The output from @kbd{a X} is a vector containing the value of @expr{x} ++that maximizes the function, and the function's value at that maximum. ++As you can see, our simple search got quite close to the right answer. ++ ++@node List Answer 9, List Answer 10, List Answer 8, Answers to Exercises ++@subsection List Tutorial Exercise 9 ++ ++@noindent ++Step one is to convert our integer into vector notation. ++ ++@smallexample ++@group ++1: 25129925999 3: 25129925999 ++ . 2: 10 ++ 1: [11, 10, 9, ..., 1, 0] ++ . ++ ++ 25129925999 @key{RET} 10 @key{RET} 12 @key{RET} v x 12 @key{RET} - ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: 25129925999 1: [0, 2, 25, 251, 2512, ... ] ++2: [100000000000, ... ] . ++ . ++ ++ V M ^ s 1 V M \ ++@end group ++@end smallexample ++ ++@noindent ++(Recall, the @kbd{\} command computes an integer quotient.) ++ ++@smallexample ++@group ++1: [0, 2, 5, 1, 2, 9, 9, 2, 5, 9, 9, 9] ++ . ++ ++ 10 V M % s 2 ++@end group ++@end smallexample ++ ++Next we must increment this number. This involves adding one to ++the last digit, plus handling carries. There is a carry to the ++left out of a digit if that digit is a nine and all the digits to ++the right of it are nines. ++ ++@smallexample ++@group ++1: [0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1] 1: [1, 1, 1, 0, 0, 1, ... ] ++ . . ++ ++ 9 V M a = v v ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [1, 1, 1, 0, 0, 0, ... ] 1: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1] ++ . . ++ ++ V U * v v 1 | ++@end group ++@end smallexample ++ ++@noindent ++Accumulating @kbd{*} across a vector of ones and zeros will preserve ++only the initial run of ones. These are the carries into all digits ++except the rightmost digit. Concatenating a one on the right takes ++care of aligning the carries properly, and also adding one to the ++rightmost digit. ++ ++@smallexample ++@group ++2: [0, 0, 0, 0, ... ] 1: [0, 0, 2, 5, 1, 2, 9, 9, 2, 6, 0, 0, 0] ++1: [0, 0, 2, 5, ... ] . ++ . ++ ++ 0 r 2 | V M + 10 V M % ++@end group ++@end smallexample ++ ++@noindent ++Here we have concatenated 0 to the @emph{left} of the original number; ++this takes care of shifting the carries by one with respect to the ++digits that generated them. ++ ++Finally, we must convert this list back into an integer. ++ ++@smallexample ++@group ++3: [0, 0, 2, 5, ... ] 2: [0, 0, 2, 5, ... ] ++2: 1000000000000 1: [1000000000000, 100000000000, ... ] ++1: [100000000000, ... ] . ++ . ++ ++ 10 @key{RET} 12 ^ r 1 | ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [0, 0, 20000000000, 5000000000, ... ] 1: 25129926000 ++ . . ++ ++ V M * V R + ++@end group ++@end smallexample ++ ++@noindent ++Another way to do this final step would be to reduce the formula ++@w{@samp{10 $$ + $}} across the vector of digits. ++ ++@smallexample ++@group ++1: [0, 0, 2, 5, ... ] 1: 25129926000 ++ . . ++ ++ V R ' 10 $$ + $ @key{RET} ++@end group ++@end smallexample ++ ++@node List Answer 10, List Answer 11, List Answer 9, Answers to Exercises ++@subsection List Tutorial Exercise 10 ++ ++@noindent ++For the list @expr{[a, b, c, d]}, the result is @expr{((a = b) = c) = d}, ++which will compare @expr{a} and @expr{b} to produce a 1 or 0, which is ++then compared with @expr{c} to produce another 1 or 0, which is then ++compared with @expr{d}. This is not at all what Joe wanted. ++ ++Here's a more correct method: ++ ++@smallexample ++@group ++1: [7, 7, 7, 8, 7] 2: [7, 7, 7, 8, 7] ++ . 1: 7 ++ . ++ ++ ' [7,7,7,8,7] @key{RET} @key{RET} v r 1 @key{RET} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [1, 1, 1, 0, 1] 1: 0 ++ . . ++ ++ V M a = V R * ++@end group ++@end smallexample ++ ++@node List Answer 11, List Answer 12, List Answer 10, Answers to Exercises ++@subsection List Tutorial Exercise 11 ++ ++@noindent ++The circle of unit radius consists of those points @expr{(x,y)} for which ++@expr{x^2 + y^2 < 1}. We start by generating a vector of @expr{x^2} ++and a vector of @expr{y^2}. ++ ++We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} ++commands. ++ ++@smallexample ++@group ++2: [2., 2., ..., 2.] 2: [2., 2., ..., 2.] ++1: [2., 2., ..., 2.] 1: [1.16, 1.98, ..., 0.81] ++ . . ++ ++ v . t . 2. v b 100 @key{RET} @key{RET} V M k r ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++2: [2., 2., ..., 2.] 1: [0.026, 0.96, ..., 0.036] ++1: [0.026, 0.96, ..., 0.036] 2: [0.53, 0.81, ..., 0.094] ++ . . ++ ++ 1 - 2 V M ^ @key{TAB} V M k r 1 - 2 V M ^ ++@end group ++@end smallexample ++ ++Now we sum the @expr{x^2} and @expr{y^2} values, compare with 1 to ++get a vector of 1/0 truth values, then sum the truth values. ++ ++@smallexample ++@group ++1: [0.56, 1.78, ..., 0.13] 1: [1, 0, ..., 1] 1: 84 ++ . . . ++ ++ + 1 V M a < V R + ++@end group ++@end smallexample ++ ++@noindent ++The ratio @expr{84/100} should approximate the ratio @cpiover{4}. ++ ++@smallexample ++@group ++1: 0.84 1: 3.36 2: 3.36 1: 1.0695 ++ . . 1: 3.14159 . ++ ++ 100 / 4 * P / ++@end group ++@end smallexample ++ ++@noindent ++Our estimate, 3.36, is off by about 7%. We could get a better estimate ++by taking more points (say, 1000), but it's clear that this method is ++not very efficient! ++ ++(Naturally, since this example uses random numbers your own answer ++will be slightly different from the one shown here!) ++ ++If you typed @kbd{v .} and @kbd{t .} before, type them again to ++return to full-sized display of vectors. ++ ++@node List Answer 12, List Answer 13, List Answer 11, Answers to Exercises ++@subsection List Tutorial Exercise 12 ++ ++@noindent ++This problem can be made a lot easier by taking advantage of some ++symmetries. First of all, after some thought it's clear that the ++@expr{y} axis can be ignored altogether. Just pick a random @expr{x} ++component for one end of the match, pick a random direction ++@texline @math{\theta}, ++@infoline @expr{theta}, ++and see if @expr{x} and ++@texline @math{x + \cos \theta} ++@infoline @expr{x + cos(theta)} ++(which is the @expr{x} coordinate of the other endpoint) cross a line. ++The lines are at integer coordinates, so this happens when the two ++numbers surround an integer. ++ ++Since the two endpoints are equivalent, we may as well choose the leftmost ++of the two endpoints as @expr{x}. Then @expr{theta} is an angle pointing ++to the right, in the range -90 to 90 degrees. (We could use radians, but ++it would feel like cheating to refer to @cpiover{2} radians while trying ++to estimate @cpi{}!) ++ ++In fact, since the field of lines is infinite we can choose the ++coordinates 0 and 1 for the lines on either side of the leftmost ++endpoint. The rightmost endpoint will be between 0 and 1 if the ++match does not cross a line, or between 1 and 2 if it does. So: ++Pick random @expr{x} and ++@texline @math{\theta}, ++@infoline @expr{theta}, ++compute ++@texline @math{x + \cos \theta}, ++@infoline @expr{x + cos(theta)}, ++and count how many of the results are greater than one. Simple! ++ ++We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} ++commands. ++ ++@smallexample ++@group ++1: [0.52, 0.71, ..., 0.72] 2: [0.52, 0.71, ..., 0.72] ++ . 1: [78.4, 64.5, ..., -42.9] ++ . ++ ++v . t . 1. v b 100 @key{RET} V M k r 180. v b 100 @key{RET} V M k r 90 - ++@end group ++@end smallexample ++ ++@noindent ++(The next step may be slow, depending on the speed of your computer.) ++ ++@smallexample ++@group ++2: [0.52, 0.71, ..., 0.72] 1: [0.72, 1.14, ..., 1.45] ++1: [0.20, 0.43, ..., 0.73] . ++ . ++ ++ m d V M C + ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [0, 1, ..., 1] 1: 0.64 1: 3.125 ++ . . . ++ ++ 1 V M a > V R + 100 / 2 @key{TAB} / ++@end group ++@end smallexample ++ ++Let's try the third method, too. We'll use random integers up to ++one million. The @kbd{k r} command with an integer argument picks ++a random integer. ++ ++@smallexample ++@group ++2: [1000000, 1000000, ..., 1000000] 2: [78489, 527587, ..., 814975] ++1: [1000000, 1000000, ..., 1000000] 1: [324014, 358783, ..., 955450] ++ . . ++ ++ 1000000 v b 100 @key{RET} @key{RET} V M k r @key{TAB} V M k r ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [1, 1, ..., 25] 1: [1, 1, ..., 0] 1: 0.56 ++ . . . ++ ++ V M k g 1 V M a = V R + 100 / ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: 10.714 1: 3.273 ++ . . ++ ++ 6 @key{TAB} / Q ++@end group ++@end smallexample ++ ++For a proof of this property of the GCD function, see section 4.5.2, ++exercise 10, of Knuth's @emph{Art of Computer Programming}, volume II. ++ ++If you typed @kbd{v .} and @kbd{t .} before, type them again to ++return to full-sized display of vectors. ++ ++@node List Answer 13, List Answer 14, List Answer 12, Answers to Exercises ++@subsection List Tutorial Exercise 13 ++ ++@noindent ++First, we put the string on the stack as a vector of ASCII codes. ++ ++@smallexample ++@group ++1: [84, 101, 115, ..., 51] ++ . ++ ++ "Testing, 1, 2, 3 @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++Note that the @kbd{"} key, like @kbd{$}, initiates algebraic entry so ++there was no need to type an apostrophe. Also, Calc didn't mind that ++we omitted the closing @kbd{"}. (The same goes for all closing delimiters ++like @kbd{)} and @kbd{]} at the end of a formula. ++ ++We'll show two different approaches here. In the first, we note that ++if the input vector is @expr{[a, b, c, d]}, then the hash code is ++@expr{3 (3 (3a + b) + c) + d = 27a + 9b + 3c + d}. In other words, ++it's a sum of descending powers of three times the ASCII codes. ++ ++@smallexample ++@group ++2: [84, 101, 115, ..., 51] 2: [84, 101, 115, ..., 51] ++1: 16 1: [15, 14, 13, ..., 0] ++ . . ++ ++ @key{RET} v l v x 16 @key{RET} - ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++2: [84, 101, 115, ..., 51] 1: 1960915098 1: 121 ++1: [14348907, ..., 1] . . ++ . ++ ++ 3 @key{TAB} V M ^ * 511 % ++@end group ++@end smallexample ++ ++@noindent ++Once again, @kbd{*} elegantly summarizes most of the computation. ++But there's an even more elegant approach: Reduce the formula ++@kbd{3 $$ + $} across the vector. Recall that this represents a ++function of two arguments that computes its first argument times three ++plus its second argument. ++ ++@smallexample ++@group ++1: [84, 101, 115, ..., 51] 1: 1960915098 ++ . . ++ ++ "Testing, 1, 2, 3 @key{RET} V R ' 3$$+$ @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++If you did the decimal arithmetic exercise, this will be familiar. ++Basically, we're turning a base-3 vector of digits into an integer, ++except that our ``digits'' are much larger than real digits. ++ ++Instead of typing @kbd{511 %} again to reduce the result, we can be ++cleverer still and notice that rather than computing a huge integer ++and taking the modulo at the end, we can take the modulo at each step ++without affecting the result. While this means there are more ++arithmetic operations, the numbers we operate on remain small so ++the operations are faster. ++ ++@smallexample ++@group ++1: [84, 101, 115, ..., 51] 1: 121 ++ . . ++ ++ "Testing, 1, 2, 3 @key{RET} V R ' (3$$+$)%511 @key{RET} ++@end group ++@end smallexample ++ ++Why does this work? Think about a two-step computation: ++@w{@expr{3 (3a + b) + c}}. Taking a result modulo 511 basically means ++subtracting off enough 511's to put the result in the desired range. ++So the result when we take the modulo after every step is, ++ ++@ifnottex ++@example ++3 (3 a + b - 511 m) + c - 511 n ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ 3 (3 a + b - 511 m) + c - 511 n $$ ++\afterdisplay ++@end tex ++ ++@noindent ++for some suitable integers @expr{m} and @expr{n}. Expanding out by ++the distributive law yields ++ ++@ifnottex ++@example ++9 a + 3 b + c - 511*3 m - 511 n ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ 9 a + 3 b + c - 511\times3 m - 511 n $$ ++\afterdisplay ++@end tex ++ ++@noindent ++The @expr{m} term in the latter formula is redundant because any ++contribution it makes could just as easily be made by the @expr{n} ++term. So we can take it out to get an equivalent formula with ++@expr{n' = 3m + n}, ++ ++@ifnottex ++@example ++9 a + 3 b + c - 511 n' ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ 9 a + 3 b + c - 511 n' $$ ++\afterdisplay ++@end tex ++ ++@noindent ++which is just the formula for taking the modulo only at the end of ++the calculation. Therefore the two methods are essentially the same. ++ ++Later in the tutorial we will encounter @dfn{modulo forms}, which ++basically automate the idea of reducing every intermediate result ++modulo some value @var{m}. ++ ++@node List Answer 14, Types Answer 1, List Answer 13, Answers to Exercises ++@subsection List Tutorial Exercise 14 ++ ++We want to use @kbd{H V U} to nest a function which adds a random ++step to an @expr{(x,y)} coordinate. The function is a bit long, but ++otherwise the problem is quite straightforward. ++ ++@smallexample ++@group ++2: [0, 0] 1: [ [ 0, 0 ] ++1: 50 [ 0.4288, -0.1695 ] ++ . [ -0.4787, -0.9027 ] ++ ... ++ ++ [0,0] 50 H V U ' <# + [random(2.0)-1, random(2.0)-1]> @key{RET} ++@end group ++@end smallexample ++ ++Just as the text recommended, we used @samp{< >} nameless function ++notation to keep the two @code{random} calls from being evaluated ++before nesting even begins. ++ ++We now have a vector of @expr{[x, y]} sub-vectors, which by Calc's ++rules acts like a matrix. We can transpose this matrix and unpack ++to get a pair of vectors, @expr{x} and @expr{y}, suitable for graphing. ++ ++@smallexample ++@group ++2: [ 0, 0.4288, -0.4787, ... ] ++1: [ 0, -0.1696, -0.9027, ... ] ++ . ++ ++ v t v u g f ++@end group ++@end smallexample ++ ++Incidentally, because the @expr{x} and @expr{y} are completely ++independent in this case, we could have done two separate commands ++to create our @expr{x} and @expr{y} vectors of numbers directly. ++ ++To make a random walk of unit steps, we note that @code{sincos} of ++a random direction exactly gives us an @expr{[x, y]} step of unit ++length; in fact, the new nesting function is even briefer, though ++we might want to lower the precision a bit for it. ++ ++@smallexample ++@group ++2: [0, 0] 1: [ [ 0, 0 ] ++1: 50 [ 0.1318, 0.9912 ] ++ . [ -0.5965, 0.3061 ] ++ ... ++ ++ [0,0] 50 m d p 6 @key{RET} H V U ' <# + sincos(random(360.0))> @key{RET} ++@end group ++@end smallexample ++ ++Another @kbd{v t v u g f} sequence will graph this new random walk. ++ ++An interesting twist on these random walk functions would be to use ++complex numbers instead of 2-vectors to represent points on the plane. ++In the first example, we'd use something like @samp{random + random*(0,1)}, ++and in the second we could use polar complex numbers with random phase ++angles. (This exercise was first suggested in this form by Randal ++Schwartz.) ++ ++@node Types Answer 1, Types Answer 2, List Answer 14, Answers to Exercises ++@subsection Types Tutorial Exercise 1 ++ ++@noindent ++If the number is the square root of @cpi{} times a rational number, ++then its square, divided by @cpi{}, should be a rational number. ++ ++@smallexample ++@group ++1: 1.26508260337 1: 0.509433962268 1: 2486645810:4881193627 ++ . . . ++ ++ 2 ^ P / c F ++@end group ++@end smallexample ++ ++@noindent ++Technically speaking this is a rational number, but not one that is ++likely to have arisen in the original problem. More likely, it just ++happens to be the fraction which most closely represents some ++irrational number to within 12 digits. ++ ++But perhaps our result was not quite exact. Let's reduce the ++precision slightly and try again: ++ ++@smallexample ++@group ++1: 0.509433962268 1: 27:53 ++ . . ++ ++ U p 10 @key{RET} c F ++@end group ++@end smallexample ++ ++@noindent ++Aha! It's unlikely that an irrational number would equal a fraction ++this simple to within ten digits, so our original number was probably ++@texline @math{\sqrt{27 \pi / 53}}. ++@infoline @expr{sqrt(27 pi / 53)}. ++ ++Notice that we didn't need to re-round the number when we reduced the ++precision. Remember, arithmetic operations always round their inputs ++to the current precision before they begin. ++ ++@node Types Answer 2, Types Answer 3, Types Answer 1, Answers to Exercises ++@subsection Types Tutorial Exercise 2 ++ ++@noindent ++@samp{inf / inf = nan}. Perhaps @samp{1} is the ``obvious'' answer. ++But if @w{@samp{17 inf = inf}}, then @samp{17 inf / inf = inf / inf = 17}, too. ++ ++@samp{exp(inf) = inf}. It's tempting to say that the exponential ++of infinity must be ``bigger'' than ``regular'' infinity, but as ++far as Calc is concerned all infinities are as just as big. ++In other words, as @expr{x} goes to infinity, @expr{e^x} also goes ++to infinity, but the fact the @expr{e^x} grows much faster than ++@expr{x} is not relevant here. ++ ++@samp{exp(-inf) = 0}. Here we have a finite answer even though ++the input is infinite. ++ ++@samp{sqrt(-inf) = (0, 1) inf}. Remember that @expr{(0, 1)} ++represents the imaginary number @expr{i}. Here's a derivation: ++@samp{sqrt(-inf) = @w{sqrt((-1) * inf)} = sqrt(-1) * sqrt(inf)}. ++The first part is, by definition, @expr{i}; the second is @code{inf} ++because, once again, all infinities are the same size. ++ ++@samp{sqrt(uinf) = uinf}. In fact, we do know something about the ++direction because @code{sqrt} is defined to return a value in the ++right half of the complex plane. But Calc has no notation for this, ++so it settles for the conservative answer @code{uinf}. ++ ++@samp{abs(uinf) = inf}. No matter which direction @expr{x} points, ++@samp{abs(x)} always points along the positive real axis. ++ ++@samp{ln(0) = -inf}. Here we have an infinite answer to a finite ++input. As in the @expr{1 / 0} case, Calc will only use infinities ++here if you have turned on Infinite mode. Otherwise, it will ++treat @samp{ln(0)} as an error. ++ ++@node Types Answer 3, Types Answer 4, Types Answer 2, Answers to Exercises ++@subsection Types Tutorial Exercise 3 ++ ++@noindent ++We can make @samp{inf - inf} be any real number we like, say, ++@expr{a}, just by claiming that we added @expr{a} to the first ++infinity but not to the second. This is just as true for complex ++values of @expr{a}, so @code{nan} can stand for a complex number. ++(And, similarly, @code{uinf} can stand for an infinity that points ++in any direction in the complex plane, such as @samp{(0, 1) inf}). ++ ++In fact, we can multiply the first @code{inf} by two. Surely ++@w{@samp{2 inf - inf = inf}}, but also @samp{2 inf - inf = inf - inf = nan}. ++So @code{nan} can even stand for infinity. Obviously it's just ++as easy to make it stand for minus infinity as for plus infinity. ++ ++The moral of this story is that ``infinity'' is a slippery fish ++indeed, and Calc tries to handle it by having a very simple model ++for infinities (only the direction counts, not the ``size''); but ++Calc is careful to write @code{nan} any time this simple model is ++unable to tell what the true answer is. ++ ++@node Types Answer 4, Types Answer 5, Types Answer 3, Answers to Exercises ++@subsection Types Tutorial Exercise 4 ++ ++@smallexample ++@group ++2: 0@@ 47' 26" 1: 0@@ 2' 47.411765" ++1: 17 . ++ . ++ ++ 0@@ 47' 26" @key{RET} 17 / ++@end group ++@end smallexample ++ ++@noindent ++The average song length is two minutes and 47.4 seconds. ++ ++@smallexample ++@group ++2: 0@@ 2' 47.411765" 1: 0@@ 3' 7.411765" 1: 0@@ 53' 6.000005" ++1: 0@@ 0' 20" . . ++ . ++ ++ 20" + 17 * ++@end group ++@end smallexample ++ ++@noindent ++The album would be 53 minutes and 6 seconds long. ++ ++@node Types Answer 5, Types Answer 6, Types Answer 4, Answers to Exercises ++@subsection Types Tutorial Exercise 5 ++ ++@noindent ++Let's suppose it's January 14, 1991. The easiest thing to do is ++to keep trying 13ths of months until Calc reports a Friday. ++We can do this by manually entering dates, or by using @kbd{t I}: ++ ++@smallexample ++@group ++1: 1: 1: ++ . . . ++ ++ ' <2/13> @key{RET} @key{DEL} ' <3/13> @key{RET} t I ++@end group ++@end smallexample ++ ++@noindent ++(Calc assumes the current year if you don't say otherwise.) ++ ++This is getting tedious---we can keep advancing the date by typing ++@kbd{t I} over and over again, but let's automate the job by using ++vector mapping. The @kbd{t I} command actually takes a second ++``how-many-months'' argument, which defaults to one. This ++argument is exactly what we want to map over: ++ ++@smallexample ++@group ++2: 1: [, , ++1: [1, 2, 3, 4, 5, 6] , , ++ . , ] ++ . ++ ++ v x 6 @key{RET} V M t I ++@end group ++@end smallexample ++ ++@noindent ++Et voil@`a, September 13, 1991 is a Friday. ++ ++@smallexample ++@group ++1: 242 ++ . ++ ++' - @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++And the answer to our original question: 242 days to go. ++ ++@node Types Answer 6, Types Answer 7, Types Answer 5, Answers to Exercises ++@subsection Types Tutorial Exercise 6 ++ ++@noindent ++The full rule for leap years is that they occur in every year divisible ++by four, except that they don't occur in years divisible by 100, except ++that they @emph{do} in years divisible by 400. We could work out the ++answer by carefully counting the years divisible by four and the ++exceptions, but there is a much simpler way that works even if we ++don't know the leap year rule. ++ ++Let's assume the present year is 1991. Years have 365 days, except ++that leap years (whenever they occur) have 366 days. So let's count ++the number of days between now and then, and compare that to the ++number of years times 365. The number of extra days we find must be ++equal to the number of leap years there were. ++ ++@smallexample ++@group ++1: 2: 1: 2925593 ++ . 1: . ++ . ++ ++ ' @key{RET} ' @key{RET} - ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++3: 2925593 2: 2925593 2: 2925593 1: 1943 ++2: 10001 1: 8010 1: 2923650 . ++1: 1991 . . ++ . ++ ++ 10001 @key{RET} 1991 - 365 * - ++@end group ++@end smallexample ++ ++@c [fix-ref Date Forms] ++@noindent ++There will be 1943 leap years before the year 10001. (Assuming, ++of course, that the algorithm for computing leap years remains ++unchanged for that long. @xref{Date Forms}, for some interesting ++background information in that regard.) ++ ++@node Types Answer 7, Types Answer 8, Types Answer 6, Answers to Exercises ++@subsection Types Tutorial Exercise 7 ++ ++@noindent ++The relative errors must be converted to absolute errors so that ++@samp{+/-} notation may be used. ++ ++@smallexample ++@group ++1: 1. 2: 1. ++ . 1: 0.2 ++ . ++ ++ 20 @key{RET} .05 * 4 @key{RET} .05 * ++@end group ++@end smallexample ++ ++Now we simply chug through the formula. ++ ++@smallexample ++@group ++1: 19.7392088022 1: 394.78 +/- 19.739 1: 6316.5 +/- 706.21 ++ . . . ++ ++ 2 P 2 ^ * 20 p 1 * 4 p .2 @key{RET} 2 ^ * ++@end group ++@end smallexample ++ ++It turns out the @kbd{v u} command will unpack an error form as ++well as a vector. This saves us some retyping of numbers. ++ ++@smallexample ++@group ++3: 6316.5 +/- 706.21 2: 6316.5 +/- 706.21 ++2: 6316.5 1: 0.1118 ++1: 706.21 . ++ . ++ ++ @key{RET} v u @key{TAB} / ++@end group ++@end smallexample ++ ++@noindent ++Thus the volume is 6316 cubic centimeters, within about 11 percent. ++ ++@node Types Answer 8, Types Answer 9, Types Answer 7, Answers to Exercises ++@subsection Types Tutorial Exercise 8 ++ ++@noindent ++The first answer is pretty simple: @samp{1 / (0 .. 10) = (0.1 .. inf)}. ++Since a number in the interval @samp{(0 .. 10)} can get arbitrarily ++close to zero, its reciprocal can get arbitrarily large, so the answer ++is an interval that effectively means, ``any number greater than 0.1'' ++but with no upper bound. ++ ++The second answer, similarly, is @samp{1 / (-10 .. 0) = (-inf .. -0.1)}. ++ ++Calc normally treats division by zero as an error, so that the formula ++@w{@samp{1 / 0}} is left unsimplified. Our third problem, ++@w{@samp{1 / [0 .. 10]}}, also (potentially) divides by zero because zero ++is now a member of the interval. So Calc leaves this one unevaluated, too. ++ ++If you turn on Infinite mode by pressing @kbd{m i}, you will ++instead get the answer @samp{[0.1 .. inf]}, which includes infinity ++as a possible value. ++ ++The fourth calculation, @samp{1 / (-10 .. 10)}, has the same problem. ++Zero is buried inside the interval, but it's still a possible value. ++It's not hard to see that the actual result of @samp{1 / (-10 .. 10)} ++will be either greater than @mathit{0.1}, or less than @mathit{-0.1}. Thus ++the interval goes from minus infinity to plus infinity, with a ``hole'' ++in it from @mathit{-0.1} to @mathit{0.1}. Calc doesn't have any way to ++represent this, so it just reports @samp{[-inf .. inf]} as the answer. ++It may be disappointing to hear ``the answer lies somewhere between ++minus infinity and plus infinity, inclusive,'' but that's the best ++that interval arithmetic can do in this case. ++ ++@node Types Answer 9, Types Answer 10, Types Answer 8, Answers to Exercises ++@subsection Types Tutorial Exercise 9 ++ ++@smallexample ++@group ++1: [-3 .. 3] 2: [-3 .. 3] 2: [0 .. 9] ++ . 1: [0 .. 9] 1: [-9 .. 9] ++ . . ++ ++ [ 3 n .. 3 ] @key{RET} 2 ^ @key{TAB} @key{RET} * ++@end group ++@end smallexample ++ ++@noindent ++In the first case the result says, ``if a number is between @mathit{-3} and ++3, its square is between 0 and 9.'' The second case says, ``the product ++of two numbers each between @mathit{-3} and 3 is between @mathit{-9} and 9.'' ++ ++An interval form is not a number; it is a symbol that can stand for ++many different numbers. Two identical-looking interval forms can stand ++for different numbers. ++ ++The same issue arises when you try to square an error form. ++ ++@node Types Answer 10, Types Answer 11, Types Answer 9, Answers to Exercises ++@subsection Types Tutorial Exercise 10 ++ ++@noindent ++Testing the first number, we might arbitrarily choose 17 for @expr{x}. ++ ++@smallexample ++@group ++1: 17 mod 811749613 2: 17 mod 811749613 1: 533694123 mod 811749613 ++ . 811749612 . ++ . ++ ++ 17 M 811749613 @key{RET} 811749612 ^ ++@end group ++@end smallexample ++ ++@noindent ++Since 533694123 is (considerably) different from 1, the number 811749613 ++must not be prime. ++ ++It's awkward to type the number in twice as we did above. There are ++various ways to avoid this, and algebraic entry is one. In fact, using ++a vector mapping operation we can perform several tests at once. Let's ++use this method to test the second number. ++ ++@smallexample ++@group ++2: [17, 42, 100000] 1: [1 mod 15485863, 1 mod ... ] ++1: 15485863 . ++ . ++ ++ [17 42 100000] 15485863 @key{RET} V M ' ($$ mod $)^($-1) @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++The result is three ones (modulo @expr{n}), so it's very probable that ++15485863 is prime. (In fact, this number is the millionth prime.) ++ ++Note that the functions @samp{($$^($-1)) mod $} or @samp{$$^($-1) % $} ++would have been hopelessly inefficient, since they would have calculated ++the power using full integer arithmetic. ++ ++Calc has a @kbd{k p} command that does primality testing. For small ++numbers it does an exact test; for large numbers it uses a variant ++of the Fermat test we used here. You can use @kbd{k p} repeatedly ++to prove that a large integer is prime with any desired probability. ++ ++@node Types Answer 11, Types Answer 12, Types Answer 10, Answers to Exercises ++@subsection Types Tutorial Exercise 11 ++ ++@noindent ++There are several ways to insert a calculated number into an HMS form. ++One way to convert a number of seconds to an HMS form is simply to ++multiply the number by an HMS form representing one second: ++ ++@smallexample ++@group ++1: 31415926.5359 2: 31415926.5359 1: 8726@@ 38' 46.5359" ++ . 1: 0@@ 0' 1" . ++ . ++ ++ P 1e7 * 0@@ 0' 1" * ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++2: 8726@@ 38' 46.5359" 1: 6@@ 6' 2.5359" mod 24@@ 0' 0" ++1: 15@@ 27' 16" mod 24@@ 0' 0" . ++ . ++ ++ x time @key{RET} + ++@end group ++@end smallexample ++ ++@noindent ++It will be just after six in the morning. ++ ++The algebraic @code{hms} function can also be used to build an ++HMS form: ++ ++@smallexample ++@group ++1: hms(0, 0, 10000000. pi) 1: 8726@@ 38' 46.5359" ++ . . ++ ++ ' hms(0, 0, 1e7 pi) @key{RET} = ++@end group ++@end smallexample ++ ++@noindent ++The @kbd{=} key is necessary to evaluate the symbol @samp{pi} to ++the actual number 3.14159... ++ ++@node Types Answer 12, Types Answer 13, Types Answer 11, Answers to Exercises ++@subsection Types Tutorial Exercise 12 ++ ++@noindent ++As we recall, there are 17 songs of about 2 minutes and 47 seconds ++each. ++ ++@smallexample ++@group ++2: 0@@ 2' 47" 1: [0@@ 3' 7" .. 0@@ 3' 47"] ++1: [0@@ 0' 20" .. 0@@ 1' 0"] . ++ . ++ ++ [ 0@@ 20" .. 0@@ 1' ] + ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [0@@ 52' 59." .. 1@@ 4' 19."] ++ . ++ ++ 17 * ++@end group ++@end smallexample ++ ++@noindent ++No matter how long it is, the album will fit nicely on one CD. ++ ++@node Types Answer 13, Types Answer 14, Types Answer 12, Answers to Exercises ++@subsection Types Tutorial Exercise 13 ++ ++@noindent ++Type @kbd{' 1 yr @key{RET} u c s @key{RET}}. The answer is 31557600 seconds. ++ ++@node Types Answer 14, Types Answer 15, Types Answer 13, Answers to Exercises ++@subsection Types Tutorial Exercise 14 ++ ++@noindent ++How long will it take for a signal to get from one end of the computer ++to the other? ++ ++@smallexample ++@group ++1: m / c 1: 3.3356 ns ++ . . ++ ++ ' 1 m / c @key{RET} u c ns @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++(Recall, @samp{c} is a ``unit'' corresponding to the speed of light.) ++ ++@smallexample ++@group ++1: 3.3356 ns 1: 0.81356 ns / ns 1: 0.81356 ++2: 4.1 ns . . ++ . ++ ++ ' 4.1 ns @key{RET} / u s ++@end group ++@end smallexample ++ ++@noindent ++Thus a signal could take up to 81 percent of a clock cycle just to ++go from one place to another inside the computer, assuming the signal ++could actually attain the full speed of light. Pretty tight! ++ ++@node Types Answer 15, Algebra Answer 1, Types Answer 14, Answers to Exercises ++@subsection Types Tutorial Exercise 15 ++ ++@noindent ++The speed limit is 55 miles per hour on most highways. We want to ++find the ratio of Sam's speed to the US speed limit. ++ ++@smallexample ++@group ++1: 55 mph 2: 55 mph 3: 11 hr mph / yd ++ . 1: 5 yd / hr . ++ . ++ ++ ' 55 mph @key{RET} ' 5 yd/hr @key{RET} / ++@end group ++@end smallexample ++ ++The @kbd{u s} command cancels out these units to get a plain ++number. Now we take the logarithm base two to find the final ++answer, assuming that each successive pill doubles his speed. ++ ++@smallexample ++@group ++1: 19360. 2: 19360. 1: 14.24 ++ . 1: 2 . ++ . ++ ++ u s 2 B ++@end group ++@end smallexample ++ ++@noindent ++Thus Sam can take up to 14 pills without a worry. ++ ++@node Algebra Answer 1, Algebra Answer 2, Types Answer 15, Answers to Exercises ++@subsection Algebra Tutorial Exercise 1 ++ ++@noindent ++@c [fix-ref Declarations] ++The result @samp{sqrt(x)^2} is simplified back to @expr{x} by the ++Calculator, but @samp{sqrt(x^2)} is not. (Consider what happens ++if @w{@expr{x = -4}}.) If @expr{x} is real, this formula could be ++simplified to @samp{abs(x)}, but for general complex arguments even ++that is not safe. (@xref{Declarations}, for a way to tell Calc ++that @expr{x} is known to be real.) ++ ++@node Algebra Answer 2, Algebra Answer 3, Algebra Answer 1, Answers to Exercises ++@subsection Algebra Tutorial Exercise 2 ++ ++@noindent ++Suppose our roots are @expr{[a, b, c]}. We want a polynomial which ++is zero when @expr{x} is any of these values. The trivial polynomial ++@expr{x-a} is zero when @expr{x=a}, so the product @expr{(x-a)(x-b)(x-c)} ++will do the job. We can use @kbd{a c x} to write this in a more ++familiar form. ++ ++@smallexample ++@group ++1: 34 x - 24 x^3 1: [1.19023, -1.19023, 0] ++ . . ++ ++ r 2 a P x @key{RET} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [x - 1.19023, x + 1.19023, x] 1: (x - 1.19023) (x + 1.19023) x ++ . . ++ ++ V M ' x-$ @key{RET} V R * ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: x^3 - 1.41666 x 1: 34 x - 24 x^3 ++ . . ++ ++ a c x @key{RET} 24 n * a x ++@end group ++@end smallexample ++ ++@noindent ++Sure enough, our answer (multiplied by a suitable constant) is the ++same as the original polynomial. ++ ++@node Algebra Answer 3, Algebra Answer 4, Algebra Answer 2, Answers to Exercises ++@subsection Algebra Tutorial Exercise 3 ++ ++@smallexample ++@group ++1: x sin(pi x) 1: (sin(pi x) - pi x cos(pi x)) / pi^2 ++ . . ++ ++ ' x sin(pi x) @key{RET} m r a i x @key{RET} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [y, 1] ++2: (sin(pi x) - pi x cos(pi x)) / pi^2 ++ . ++ ++ ' [y,1] @key{RET} @key{TAB} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [(sin(pi y) - pi y cos(pi y)) / pi^2, (sin(pi) - pi cos(pi)) / pi^2] ++ . ++ ++ V M $ @key{RET} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: (sin(pi y) - pi y cos(pi y)) / pi^2 + (pi cos(pi) - sin(pi)) / pi^2 ++ . ++ ++ V R - ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: (sin(3.14159 y) - 3.14159 y cos(3.14159 y)) / 9.8696 - 0.3183 ++ . ++ ++ = ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [0., -0.95493, 0.63662, -1.5915, 1.2732] ++ . ++ ++ v x 5 @key{RET} @key{TAB} V M $ @key{RET} ++@end group ++@end smallexample ++ ++@node Algebra Answer 4, Rewrites Answer 1, Algebra Answer 3, Answers to Exercises ++@subsection Algebra Tutorial Exercise 4 ++ ++@noindent ++The hard part is that @kbd{V R +} is no longer sufficient to add up all ++the contributions from the slices, since the slices have varying ++coefficients. So first we must come up with a vector of these ++coefficients. Here's one way: ++ ++@smallexample ++@group ++2: -1 2: 3 1: [4, 2, ..., 4] ++1: [1, 2, ..., 9] 1: [-1, 1, ..., -1] . ++ . . ++ ++ 1 n v x 9 @key{RET} V M ^ 3 @key{TAB} - ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: [4, 2, ..., 4, 1] 1: [1, 4, 2, ..., 4, 1] ++ . . ++ ++ 1 | 1 @key{TAB} | ++@end group ++@end smallexample ++ ++@noindent ++Now we compute the function values. Note that for this method we need ++eleven values, including both endpoints of the desired interval. ++ ++@smallexample ++@group ++2: [1, 4, 2, ..., 4, 1] ++1: [1, 1.1, 1.2, ... , 1.8, 1.9, 2.] ++ . ++ ++ 11 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++2: [1, 4, 2, ..., 4, 1] ++1: [0., 0.084941, 0.16993, ... ] ++ . ++ ++ ' sin(x) ln(x) @key{RET} m r p 5 @key{RET} V M $ @key{RET} ++@end group ++@end smallexample ++ ++@noindent ++Once again this calls for @kbd{V M * V R +}; a simple @kbd{*} does the ++same thing. ++ ++@smallexample ++@group ++1: 11.22 1: 1.122 1: 0.374 ++ . . . ++ ++ * .1 * 3 / ++@end group ++@end smallexample ++ ++@noindent ++Wow! That's even better than the result from the Taylor series method. ++ ++@node Rewrites Answer 1, Rewrites Answer 2, Algebra Answer 4, Answers to Exercises ++@subsection Rewrites Tutorial Exercise 1 ++ ++@noindent ++We'll use Big mode to make the formulas more readable. ++ ++@smallexample ++@group ++ ___ ++ 2 + V 2 ++1: (2 + sqrt(2)) / (1 + sqrt(2)) 1: -------- ++ . ___ ++ 1 + V 2 ++ ++ . ++ ++ ' (2+sqrt(2)) / (1+sqrt(2)) @key{RET} d B ++@end group ++@end smallexample ++ ++@noindent ++Multiplying by the conjugate helps because @expr{(a+b) (a-b) = a^2 - b^2}. ++ ++@smallexample ++@group ++ ___ ___ ++1: (2 + V 2 ) (V 2 - 1) ++ . ++ ++ a r a/(b+c) := a*(b-c) / (b^2-c^2) @key{RET} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++ ___ ___ ++1: 2 + V 2 - 2 1: V 2 ++ . . ++ ++ a r a*(b+c) := a*b + a*c a s ++@end group ++@end smallexample ++ ++@noindent ++(We could have used @kbd{a x} instead of a rewrite rule for the ++second step.) ++ ++The multiply-by-conjugate rule turns out to be useful in many ++different circumstances, such as when the denominator involves ++sines and cosines or the imaginary constant @code{i}. ++ ++@node Rewrites Answer 2, Rewrites Answer 3, Rewrites Answer 1, Answers to Exercises ++@subsection Rewrites Tutorial Exercise 2 ++ ++@noindent ++Here is the rule set: ++ ++@smallexample ++@group ++[ fib(n) := fib(n, 1, 1) :: integer(n) :: n >= 1, ++ fib(1, x, y) := x, ++ fib(n, x, y) := fib(n-1, y, x+y) ] ++@end group ++@end smallexample ++ ++@noindent ++The first rule turns a one-argument @code{fib} that people like to write ++into a three-argument @code{fib} that makes computation easier. The ++second rule converts back from three-argument form once the computation ++is done. The third rule does the computation itself. It basically ++says that if @expr{x} and @expr{y} are two consecutive Fibonacci numbers, ++then @expr{y} and @expr{x+y} are the next (overlapping) pair of Fibonacci ++numbers. ++ ++Notice that because the number @expr{n} was ``validated'' by the ++conditions on the first rule, there is no need to put conditions on ++the other rules because the rule set would never get that far unless ++the input were valid. That further speeds computation, since no ++extra conditions need to be checked at every step. ++ ++Actually, a user with a nasty sense of humor could enter a bad ++three-argument @code{fib} call directly, say, @samp{fib(0, 1, 1)}, ++which would get the rules into an infinite loop. One thing that would ++help keep this from happening by accident would be to use something like ++@samp{ZzFib} instead of @code{fib} as the name of the three-argument ++function. ++ ++@node Rewrites Answer 3, Rewrites Answer 4, Rewrites Answer 2, Answers to Exercises ++@subsection Rewrites Tutorial Exercise 3 ++ ++@noindent ++He got an infinite loop. First, Calc did as expected and rewrote ++@w{@samp{2 + 3 x}} to @samp{f(2, 3, x)}. Then it looked for ways to ++apply the rule again, and found that @samp{f(2, 3, x)} looks like ++@samp{a + b x} with @w{@samp{a = 0}} and @samp{b = 1}, so it rewrote to ++@samp{f(0, 1, f(2, 3, x))}. It then wrapped another @samp{f(0, 1, ...)} ++around that, and so on, ad infinitum. Joe should have used @kbd{M-1 a r} ++to make sure the rule applied only once. ++ ++(Actually, even the first step didn't work as he expected. What Calc ++really gives for @kbd{M-1 a r} in this situation is @samp{f(3 x, 1, 2)}, ++treating 2 as the ``variable,'' and @samp{3 x} as a constant being added ++to it. While this may seem odd, it's just as valid a solution as the ++``obvious'' one. One way to fix this would be to add the condition ++@samp{:: variable(x)} to the rule, to make sure the thing that matches ++@samp{x} is indeed a variable, or to change @samp{x} to @samp{quote(x)} ++on the lefthand side, so that the rule matches the actual variable ++@samp{x} rather than letting @samp{x} stand for something else.) ++ ++@node Rewrites Answer 4, Rewrites Answer 5, Rewrites Answer 3, Answers to Exercises ++@subsection Rewrites Tutorial Exercise 4 ++ ++@noindent ++@ignore ++@starindex ++@end ignore ++@tindex seq ++Here is a suitable set of rules to solve the first part of the problem: ++ ++@smallexample ++@group ++[ seq(n, c) := seq(n/2, c+1) :: n%2 = 0, ++ seq(n, c) := seq(3n+1, c+1) :: n%2 = 1 :: n > 1 ] ++@end group ++@end smallexample ++ ++Given the initial formula @samp{seq(6, 0)}, application of these ++rules produces the following sequence of formulas: ++ ++@example ++seq( 3, 1) ++seq(10, 2) ++seq( 5, 3) ++seq(16, 4) ++seq( 8, 5) ++seq( 4, 6) ++seq( 2, 7) ++seq( 1, 8) ++@end example ++ ++@noindent ++whereupon neither of the rules match, and rewriting stops. ++ ++We can pretty this up a bit with a couple more rules: ++ ++@smallexample ++@group ++[ seq(n) := seq(n, 0), ++ seq(1, c) := c, ++ ... ] ++@end group ++@end smallexample ++ ++@noindent ++Now, given @samp{seq(6)} as the starting configuration, we get 8 ++as the result. ++ ++The change to return a vector is quite simple: ++ ++@smallexample ++@group ++[ seq(n) := seq(n, []) :: integer(n) :: n > 0, ++ seq(1, v) := v | 1, ++ seq(n, v) := seq(n/2, v | n) :: n%2 = 0, ++ seq(n, v) := seq(3n+1, v | n) :: n%2 = 1 ] ++@end group ++@end smallexample ++ ++@noindent ++Given @samp{seq(6)}, the result is @samp{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. ++ ++Notice that the @expr{n > 1} guard is no longer necessary on the last ++rule since the @expr{n = 1} case is now detected by another rule. ++But a guard has been added to the initial rule to make sure the ++initial value is suitable before the computation begins. ++ ++While still a good idea, this guard is not as vitally important as it ++was for the @code{fib} function, since calling, say, @samp{seq(x, [])} ++will not get into an infinite loop. Calc will not be able to prove ++the symbol @samp{x} is either even or odd, so none of the rules will ++apply and the rewrites will stop right away. ++ ++@node Rewrites Answer 5, Rewrites Answer 6, Rewrites Answer 4, Answers to Exercises ++@subsection Rewrites Tutorial Exercise 5 ++ ++@noindent ++@ignore ++@starindex ++@end ignore ++@tindex nterms ++If @expr{x} is the sum @expr{a + b}, then `@tfn{nterms(}@var{x}@tfn{)}' must ++be `@tfn{nterms(}@var{a}@tfn{)}' plus `@tfn{nterms(}@var{b}@tfn{)}'. If @expr{x} ++is not a sum, then `@tfn{nterms(}@var{x}@tfn{)}' = 1. ++ ++@smallexample ++@group ++[ nterms(a + b) := nterms(a) + nterms(b), ++ nterms(x) := 1 ] ++@end group ++@end smallexample ++ ++@noindent ++Here we have taken advantage of the fact that earlier rules always ++match before later rules; @samp{nterms(x)} will only be tried if we ++already know that @samp{x} is not a sum. ++ ++@node Rewrites Answer 6, Programming Answer 1, Rewrites Answer 5, Answers to Exercises ++@subsection Rewrites Tutorial Exercise 6 ++ ++@noindent ++Here is a rule set that will do the job: ++ ++@smallexample ++@group ++[ a*(b + c) := a*b + a*c, ++ opt(a) O(x^n) + opt(b) O(x^m) := O(x^n) :: n <= m ++ :: constant(a) :: constant(b), ++ opt(a) O(x^n) + opt(b) x^m := O(x^n) :: n <= m ++ :: constant(a) :: constant(b), ++ a O(x^n) := O(x^n) :: constant(a), ++ x^opt(m) O(x^n) := O(x^(n+m)), ++ O(x^n) O(x^m) := O(x^(n+m)) ] ++@end group ++@end smallexample ++ ++If we really want the @kbd{+} and @kbd{*} keys to operate naturally ++on power series, we should put these rules in @code{EvalRules}. For ++testing purposes, it is better to put them in a different variable, ++say, @code{O}, first. ++ ++The first rule just expands products of sums so that the rest of the ++rules can assume they have an expanded-out polynomial to work with. ++Note that this rule does not mention @samp{O} at all, so it will ++apply to any product-of-sum it encounters---this rule may surprise ++you if you put it into @code{EvalRules}! ++ ++In the second rule, the sum of two O's is changed to the smaller O. ++The optional constant coefficients are there mostly so that ++@samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled ++as well as @samp{O(x^2) + O(x^3)}. ++ ++The third rule absorbs higher powers of @samp{x} into O's. ++ ++The fourth rule says that a constant times a negligible quantity ++is still negligible. (This rule will also match @samp{O(x^3) / 4}, ++with @samp{a = 1/4}.) ++ ++The fifth rule rewrites, for example, @samp{x^2 O(x^3)} to @samp{O(x^5)}. ++(It is easy to see that if one of these forms is negligible, the other ++is, too.) Notice the @samp{x^opt(m)} to pick up terms like ++@w{@samp{x O(x^3)}}. Optional powers will match @samp{x} as @samp{x^1} ++but not 1 as @samp{x^0}. This turns out to be exactly what we want here. ++ ++The sixth rule is the corresponding rule for products of two O's. ++ ++Another way to solve this problem would be to create a new ``data type'' ++that represents truncated power series. We might represent these as ++function calls @samp{series(@var{coefs}, @var{x})} where @var{coefs} is ++a vector of coefficients for @expr{x^0}, @expr{x^1}, @expr{x^2}, and so ++on. Rules would exist for sums and products of such @code{series} ++objects, and as an optional convenience could also know how to combine a ++@code{series} object with a normal polynomial. (With this, and with a ++rule that rewrites @samp{O(x^n)} to the equivalent @code{series} form, ++you could still enter power series in exactly the same notation as ++before.) Operations on such objects would probably be more efficient, ++although the objects would be a bit harder to read. ++ ++@c [fix-ref Compositions] ++Some other symbolic math programs provide a power series data type ++similar to this. Mathematica, for example, has an object that looks ++like @samp{PowerSeries[@var{x}, @var{x0}, @var{coefs}, @var{nmin}, ++@var{nmax}, @var{den}]}, where @var{x0} is the point about which the ++power series is taken (we've been assuming this was always zero), ++and @var{nmin}, @var{nmax}, and @var{den} allow pseudo-power-series ++with fractional or negative powers. Also, the @code{PowerSeries} ++objects have a special display format that makes them look like ++@samp{2 x^2 + O(x^4)} when they are printed out. (@xref{Compositions}, ++for a way to do this in Calc, although for something as involved as ++this it would probably be better to write the formatting routine ++in Lisp.) ++ ++@node Programming Answer 1, Programming Answer 2, Rewrites Answer 6, Answers to Exercises ++@subsection Programming Tutorial Exercise 1 ++ ++@noindent ++Just enter the formula @samp{ninteg(sin(t)/t, t, 0, x)}, type ++@kbd{Z F}, and answer the questions. Since this formula contains two ++variables, the default argument list will be @samp{(t x)}. We want to ++change this to @samp{(x)} since @expr{t} is really a dummy variable ++to be used within @code{ninteg}. ++ ++The exact keystrokes are @kbd{Z F s Si @key{RET} @key{RET} C-b C-b @key{DEL} @key{DEL} @key{RET} y}. ++(The @kbd{C-b C-b @key{DEL} @key{DEL}} are what fix the argument list.) ++ ++@node Programming Answer 2, Programming Answer 3, Programming Answer 1, Answers to Exercises ++@subsection Programming Tutorial Exercise 2 ++ ++@noindent ++One way is to move the number to the top of the stack, operate on ++it, then move it back: @kbd{C-x ( M-@key{TAB} n M-@key{TAB} M-@key{TAB} C-x )}. ++ ++Another way is to negate the top three stack entries, then negate ++again the top two stack entries: @kbd{C-x ( M-3 n M-2 n C-x )}. ++ ++Finally, it turns out that a negative prefix argument causes a ++command like @kbd{n} to operate on the specified stack entry only, ++which is just what we want: @kbd{C-x ( M-- 3 n C-x )}. ++ ++Just for kicks, let's also do it algebraically: ++@w{@kbd{C-x ( ' -$$$, $$, $ @key{RET} C-x )}}. ++ ++@node Programming Answer 3, Programming Answer 4, Programming Answer 2, Answers to Exercises ++@subsection Programming Tutorial Exercise 3 ++ ++@noindent ++Each of these functions can be computed using the stack, or using ++algebraic entry, whichever way you prefer: ++ ++@noindent ++Computing ++@texline @math{\displaystyle{\sin x \over x}}: ++@infoline @expr{sin(x) / x}: ++ ++Using the stack: @kbd{C-x ( @key{RET} S @key{TAB} / C-x )}. ++ ++Using algebraic entry: @kbd{C-x ( ' sin($)/$ @key{RET} C-x )}. ++ ++@noindent ++Computing the logarithm: ++ ++Using the stack: @kbd{C-x ( @key{TAB} B C-x )} ++ ++Using algebraic entry: @kbd{C-x ( ' log($,$$) @key{RET} C-x )}. ++ ++@noindent ++Computing the vector of integers: ++ ++Using the stack: @kbd{C-x ( 1 @key{RET} 1 C-u v x C-x )}. (Recall that ++@kbd{C-u v x} takes the vector size, starting value, and increment ++from the stack.) ++ ++Alternatively: @kbd{C-x ( ~ v x C-x )}. (The @kbd{~} key pops a ++number from the stack and uses it as the prefix argument for the ++next command.) ++ ++Using algebraic entry: @kbd{C-x ( ' index($) @key{RET} C-x )}. ++ ++@node Programming Answer 4, Programming Answer 5, Programming Answer 3, Answers to Exercises ++@subsection Programming Tutorial Exercise 4 ++ ++@noindent ++Here's one way: @kbd{C-x ( @key{RET} V R + @key{TAB} v l / C-x )}. ++ ++@node Programming Answer 5, Programming Answer 6, Programming Answer 4, Answers to Exercises ++@subsection Programming Tutorial Exercise 5 ++ ++@smallexample ++@group ++2: 1 1: 1.61803398502 2: 1.61803398502 ++1: 20 . 1: 1.61803398875 ++ . . ++ ++ 1 @key{RET} 20 Z < & 1 + Z > I H P ++@end group ++@end smallexample ++ ++@noindent ++This answer is quite accurate. ++ ++@node Programming Answer 6, Programming Answer 7, Programming Answer 5, Answers to Exercises ++@subsection Programming Tutorial Exercise 6 ++ ++@noindent ++Here is the matrix: ++ ++@example ++[ [ 0, 1 ] * [a, b] = [b, a + b] ++ [ 1, 1 ] ] ++@end example ++ ++@noindent ++Thus @samp{[0, 1; 1, 1]^n * [1, 1]} computes Fibonacci numbers @expr{n+1} ++and @expr{n+2}. Here's one program that does the job: ++ ++@example ++C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] @key{RET} v u @key{DEL} C-x ) ++@end example ++ ++@noindent ++This program is quite efficient because Calc knows how to raise a ++matrix (or other value) to the power @expr{n} in only ++@texline @math{\log_2 n} ++@infoline @expr{log(n,2)} ++steps. For example, this program can compute the 1000th Fibonacci ++number (a 209-digit integer!) in about 10 steps; even though the ++@kbd{Z < ... Z >} solution had much simpler steps, it would have ++required so many steps that it would not have been practical. ++ ++@node Programming Answer 7, Programming Answer 8, Programming Answer 6, Answers to Exercises ++@subsection Programming Tutorial Exercise 7 ++ ++@noindent ++The trick here is to compute the harmonic numbers differently, so that ++the loop counter itself accumulates the sum of reciprocals. We use ++a separate variable to hold the integer counter. ++ ++@smallexample ++@group ++1: 1 2: 1 1: . ++ . 1: 4 ++ . ++ ++ 1 t 1 1 @key{RET} 4 Z ( t 2 r 1 1 + s 1 & Z ) ++@end group ++@end smallexample ++ ++@noindent ++The body of the loop goes as follows: First save the harmonic sum ++so far in variable 2. Then delete it from the stack; the for loop ++itself will take care of remembering it for us. Next, recall the ++count from variable 1, add one to it, and feed its reciprocal to ++the for loop to use as the step value. The for loop will increase ++the ``loop counter'' by that amount and keep going until the ++loop counter exceeds 4. ++ ++@smallexample ++@group ++2: 31 3: 31 ++1: 3.99498713092 2: 3.99498713092 ++ . 1: 4.02724519544 ++ . ++ ++ r 1 r 2 @key{RET} 31 & + ++@end group ++@end smallexample ++ ++Thus we find that the 30th harmonic number is 3.99, and the 31st ++harmonic number is 4.02. ++ ++@node Programming Answer 8, Programming Answer 9, Programming Answer 7, Answers to Exercises ++@subsection Programming Tutorial Exercise 8 ++ ++@noindent ++The first step is to compute the derivative @expr{f'(x)} and thus ++the formula ++@texline @math{\displaystyle{x - {f(x) \over f'(x)}}}. ++@infoline @expr{x - f(x)/f'(x)}. ++ ++(Because this definition is long, it will be repeated in concise form ++below. You can use @w{@kbd{C-x * m}} to load it from there. While you are ++entering a @kbd{Z ` Z '} body in a macro, Calc simply collects ++keystrokes without executing them. In the following diagrams we'll ++pretend Calc actually executed the keystrokes as you typed them, ++just for purposes of illustration.) ++ ++@smallexample ++@group ++2: sin(cos(x)) - 0.5 3: 4.5 ++1: 4.5 2: sin(cos(x)) - 0.5 ++ . 1: -(sin(x) cos(cos(x))) ++ . ++ ++' sin(cos(x))-0.5 @key{RET} 4.5 m r C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++2: 4.5 ++1: x + (sin(cos(x)) - 0.5) / sin(x) cos(cos(x)) ++ . ++ ++ / ' x @key{RET} @key{TAB} - t 1 ++@end group ++@end smallexample ++ ++Now, we enter the loop. We'll use a repeat loop with a 20-repetition ++limit just in case the method fails to converge for some reason. ++(Normally, the @w{@kbd{Z /}} command will stop the loop before all 20 ++repetitions are done.) ++ ++@smallexample ++@group ++1: 4.5 3: 4.5 2: 4.5 ++ . 2: x + (sin(cos(x)) ... 1: 5.24196456928 ++ 1: 4.5 . ++ . ++ ++ 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} ++@end group ++@end smallexample ++ ++This is the new guess for @expr{x}. Now we compare it with the ++old one to see if we've converged. ++ ++@smallexample ++@group ++3: 5.24196 2: 5.24196 1: 5.24196 1: 5.26345856348 ++2: 5.24196 1: 0 . . ++1: 4.5 . ++ . ++ ++ @key{RET} M-@key{TAB} a = Z / Z > Z ' C-x ) ++@end group ++@end smallexample ++ ++The loop converges in just a few steps to this value. To check ++the result, we can simply substitute it back into the equation. ++ ++@smallexample ++@group ++2: 5.26345856348 ++1: 0.499999999997 ++ . ++ ++ @key{RET} ' sin(cos($)) @key{RET} ++@end group ++@end smallexample ++ ++Let's test the new definition again: ++ ++@smallexample ++@group ++2: x^2 - 9 1: 3. ++1: 1 . ++ . ++ ++ ' x^2-9 @key{RET} 1 X ++@end group ++@end smallexample ++ ++Once again, here's the full Newton's Method definition: ++ ++@example ++@group ++C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} / ' x @key{RET} @key{TAB} - t 1 ++ 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} ++ @key{RET} M-@key{TAB} a = Z / ++ Z > ++ Z ' ++C-x ) ++@end group ++@end example ++ ++@c [fix-ref Nesting and Fixed Points] ++It turns out that Calc has a built-in command for applying a formula ++repeatedly until it converges to a number. @xref{Nesting and Fixed Points}, ++to see how to use it. ++ ++@c [fix-ref Root Finding] ++Also, of course, @kbd{a R} is a built-in command that uses Newton's ++method (among others) to look for numerical solutions to any equation. ++@xref{Root Finding}. ++ ++@node Programming Answer 9, Programming Answer 10, Programming Answer 8, Answers to Exercises ++@subsection Programming Tutorial Exercise 9 ++ ++@noindent ++The first step is to adjust @expr{z} to be greater than 5. A simple ++``for'' loop will do the job here. If @expr{z} is less than 5, we ++reduce the problem using ++@texline @math{\psi(z) = \psi(z+1) - 1/z}. ++@infoline @expr{psi(z) = psi(z+1) - 1/z}. We go ++on to compute ++@texline @math{\psi(z+1)}, ++@infoline @expr{psi(z+1)}, ++and remember to add back a factor of @expr{-1/z} when we're done. This ++step is repeated until @expr{z > 5}. ++ ++(Because this definition is long, it will be repeated in concise form ++below. You can use @w{@kbd{C-x * m}} to load it from there. While you are ++entering a @kbd{Z ` Z '} body in a macro, Calc simply collects ++keystrokes without executing them. In the following diagrams we'll ++pretend Calc actually executed the keystrokes as you typed them, ++just for purposes of illustration.) ++ ++@smallexample ++@group ++1: 1. 1: 1. ++ . . ++ ++ 1.0 @key{RET} C-x ( Z ` s 1 0 t 2 ++@end group ++@end smallexample ++ ++Here, variable 1 holds @expr{z} and variable 2 holds the adjustment ++factor. If @expr{z < 5}, we use a loop to increase it. ++ ++(By the way, we started with @samp{1.0} instead of the integer 1 because ++otherwise the calculation below will try to do exact fractional arithmetic, ++and will never converge because fractions compare equal only if they ++are exactly equal, not just equal to within the current precision.) ++ ++@smallexample ++@group ++3: 1. 2: 1. 1: 6. ++2: 1. 1: 1 . ++1: 5 . ++ . ++ ++ @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] ++@end group ++@end smallexample ++ ++Now we compute the initial part of the sum: ++@texline @math{\ln z - {1 \over 2z}} ++@infoline @expr{ln(z) - 1/2z} ++minus the adjustment factor. ++ ++@smallexample ++@group ++2: 1.79175946923 2: 1.7084261359 1: -0.57490719743 ++1: 0.0833333333333 1: 2.28333333333 . ++ . . ++ ++ L r 1 2 * & - r 2 - ++@end group ++@end smallexample ++ ++Now we evaluate the series. We'll use another ``for'' loop counting ++up the value of @expr{2 n}. (Calc does have a summation command, ++@kbd{a +}, but we'll use loops just to get more practice with them.) ++ ++@smallexample ++@group ++3: -0.5749 3: -0.5749 4: -0.5749 2: -0.5749 ++2: 2 2: 1:6 3: 1:6 1: 2.3148e-3 ++1: 40 1: 2 2: 2 . ++ . . 1: 36. ++ . ++ ++ 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++3: -0.5749 3: -0.5772 2: -0.5772 1: -0.577215664892 ++2: -0.5749 2: -0.5772 1: 0 . ++1: 2.3148e-3 1: -0.5749 . ++ . . ++ ++ @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / 2 Z ) Z ' C-x ) ++@end group ++@end smallexample ++ ++This is the value of ++@texline @math{-\gamma}, ++@infoline @expr{- gamma}, ++with a slight bit of roundoff error. To get a full 12 digits, let's use ++a higher precision: ++ ++@smallexample ++@group ++2: -0.577215664892 2: -0.577215664892 ++1: 1. 1: -0.577215664901532 ++ ++ 1. @key{RET} p 16 @key{RET} X ++@end group ++@end smallexample ++ ++Here's the complete sequence of keystrokes: ++ ++@example ++@group ++C-x ( Z ` s 1 0 t 2 ++ @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] ++ L r 1 2 * & - r 2 - ++ 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / ++ @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / ++ 2 Z ) ++ Z ' ++C-x ) ++@end group ++@end example ++ ++@node Programming Answer 10, Programming Answer 11, Programming Answer 9, Answers to Exercises ++@subsection Programming Tutorial Exercise 10 ++ ++@noindent ++Taking the derivative of a term of the form @expr{x^n} will produce ++a term like ++@texline @math{n x^{n-1}}. ++@infoline @expr{n x^(n-1)}. ++Taking the derivative of a constant ++produces zero. From this it is easy to see that the @expr{n}th ++derivative of a polynomial, evaluated at @expr{x = 0}, will equal the ++coefficient on the @expr{x^n} term times @expr{n!}. ++ ++(Because this definition is long, it will be repeated in concise form ++below. You can use @w{@kbd{C-x * m}} to load it from there. While you are ++entering a @kbd{Z ` Z '} body in a macro, Calc simply collects ++keystrokes without executing them. In the following diagrams we'll ++pretend Calc actually executed the keystrokes as you typed them, ++just for purposes of illustration.) ++ ++@smallexample ++@group ++2: 5 x^4 + (x + 1)^2 3: 5 x^4 + (x + 1)^2 ++1: 6 2: 0 ++ . 1: 6 ++ . ++ ++ ' 5 x^4 + (x+1)^2 @key{RET} 6 C-x ( Z ` [ ] t 1 0 @key{TAB} ++@end group ++@end smallexample ++ ++@noindent ++Variable 1 will accumulate the vector of coefficients. ++ ++@smallexample ++@group ++2: 0 3: 0 2: 5 x^4 + ... ++1: 5 x^4 + ... 2: 5 x^4 + ... 1: 1 ++ . 1: 1 . ++ . ++ ++ Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 ++@end group ++@end smallexample ++ ++@noindent ++Note that @kbd{s | 1} appends the top-of-stack value to the vector ++in a variable; it is completely analogous to @kbd{s + 1}. We could ++have written instead, @kbd{r 1 @key{TAB} | t 1}. ++ ++@smallexample ++@group ++1: 20 x^3 + 2 x + 2 1: 0 1: [1, 2, 1, 0, 5, 0, 0] ++ . . . ++ ++ a d x @key{RET} 1 Z ) @key{DEL} r 1 Z ' C-x ) ++@end group ++@end smallexample ++ ++To convert back, a simple method is just to map the coefficients ++against a table of powers of @expr{x}. ++ ++@smallexample ++@group ++2: [1, 2, 1, 0, 5, 0, 0] 2: [1, 2, 1, 0, 5, 0, 0] ++1: 6 1: [0, 1, 2, 3, 4, 5, 6] ++ . . ++ ++ 6 @key{RET} 1 + 0 @key{RET} 1 C-u v x ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++2: [1, 2, 1, 0, 5, 0, 0] 2: 1 + 2 x + x^2 + 5 x^4 ++1: [1, x, x^2, x^3, ... ] . ++ . ++ ++ ' x @key{RET} @key{TAB} V M ^ * ++@end group ++@end smallexample ++ ++Once again, here are the whole polynomial to/from vector programs: ++ ++@example ++@group ++C-x ( Z ` [ ] t 1 0 @key{TAB} ++ Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 ++ a d x @key{RET} ++ 1 Z ) r 1 ++ Z ' ++C-x ) ++ ++C-x ( 1 + 0 @key{RET} 1 C-u v x ' x @key{RET} @key{TAB} V M ^ * C-x ) ++@end group ++@end example ++ ++@node Programming Answer 11, Programming Answer 12, Programming Answer 10, Answers to Exercises ++@subsection Programming Tutorial Exercise 11 ++ ++@noindent ++First we define a dummy program to go on the @kbd{z s} key. The true ++@w{@kbd{z s}} key is supposed to take two numbers from the stack and ++return one number, so @key{DEL} as a dummy definition will make ++sure the stack comes out right. ++ ++@smallexample ++@group ++2: 4 1: 4 2: 4 ++1: 2 . 1: 2 ++ . . ++ ++ 4 @key{RET} 2 C-x ( @key{DEL} C-x ) Z K s @key{RET} 2 ++@end group ++@end smallexample ++ ++The last step replaces the 2 that was eaten during the creation ++of the dummy @kbd{z s} command. Now we move on to the real ++definition. The recurrence needs to be rewritten slightly, ++to the form @expr{s(n,m) = s(n-1,m-1) - (n-1) s(n-1,m)}. ++ ++(Because this definition is long, it will be repeated in concise form ++below. You can use @kbd{C-x * m} to load it from there.) ++ ++@smallexample ++@group ++2: 4 4: 4 3: 4 2: 4 ++1: 2 3: 2 2: 2 1: 2 ++ . 2: 4 1: 0 . ++ 1: 2 . ++ . ++ ++ C-x ( M-2 @key{RET} a = Z [ @key{DEL} @key{DEL} 1 Z : ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++4: 4 2: 4 2: 3 4: 3 4: 3 3: 3 ++3: 2 1: 2 1: 2 3: 2 3: 2 2: 2 ++2: 2 . . 2: 3 2: 3 1: 3 ++1: 0 1: 2 1: 1 . ++ . . . ++ ++ @key{RET} 0 a = Z [ @key{DEL} @key{DEL} 0 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s ++@end group ++@end smallexample ++ ++@noindent ++(Note that the value 3 that our dummy @kbd{z s} produces is not correct; ++it is merely a placeholder that will do just as well for now.) ++ ++@smallexample ++@group ++3: 3 4: 3 3: 3 2: 3 1: -6 ++2: 3 3: 3 2: 3 1: 9 . ++1: 2 2: 3 1: 3 . ++ . 1: 2 . ++ . ++ ++ M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - ++ ++@end group ++@end smallexample ++@noindent ++@smallexample ++@group ++1: -6 2: 4 1: 11 2: 11 ++ . 1: 2 . 1: 11 ++ . . ++ ++ Z ] Z ] C-x ) Z K s @key{RET} @key{DEL} 4 @key{RET} 2 z s M-@key{RET} k s ++@end group ++@end smallexample ++ ++Even though the result that we got during the definition was highly ++bogus, once the definition is complete the @kbd{z s} command gets ++the right answers. ++ ++Here's the full program once again: ++ ++@example ++@group ++C-x ( M-2 @key{RET} a = ++ Z [ @key{DEL} @key{DEL} 1 ++ Z : @key{RET} 0 a = ++ Z [ @key{DEL} @key{DEL} 0 ++ Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s ++ M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - ++ Z ] ++ Z ] ++C-x ) ++@end group ++@end example ++ ++You can read this definition using @kbd{C-x * m} (@code{read-kbd-macro}) ++followed by @kbd{Z K s}, without having to make a dummy definition ++first, because @code{read-kbd-macro} doesn't need to execute the ++definition as it reads it in. For this reason, @code{C-x * m} is often ++the easiest way to create recursive programs in Calc. ++ ++@node Programming Answer 12, , Programming Answer 11, Answers to Exercises ++@subsection Programming Tutorial Exercise 12 ++ ++@noindent ++This turns out to be a much easier way to solve the problem. Let's ++denote Stirling numbers as calls of the function @samp{s}. ++ ++First, we store the rewrite rules corresponding to the definition of ++Stirling numbers in a convenient variable: ++ ++@smallexample ++s e StirlingRules @key{RET} ++[ s(n,n) := 1 :: n >= 0, ++ s(n,0) := 0 :: n > 0, ++ s(n,m) := s(n-1,m-1) - (n-1) s(n-1,m) :: n >= m :: m >= 1 ] ++C-c C-c ++@end smallexample ++ ++Now, it's just a matter of applying the rules: ++ ++@smallexample ++@group ++2: 4 1: s(4, 2) 1: 11 ++1: 2 . . ++ . ++ ++ 4 @key{RET} 2 C-x ( ' s($$,$) @key{RET} a r StirlingRules @key{RET} C-x ) ++@end group ++@end smallexample ++ ++As in the case of the @code{fib} rules, it would be useful to put these ++rules in @code{EvalRules} and to add a @samp{:: remember} condition to ++the last rule. ++ ++@c This ends the table-of-contents kludge from above: ++@tex ++\global\let\chapternofonts=\oldchapternofonts ++@end tex ++ ++@c [reference] ++ ++@node Introduction, Data Types, Tutorial, Top ++@chapter Introduction ++ ++@noindent ++This chapter is the beginning of the Calc reference manual. ++It covers basic concepts such as the stack, algebraic and ++numeric entry, undo, numeric prefix arguments, etc. ++ ++@c [when-split] ++@c (Chapter 2, the Tutorial, has been printed in a separate volume.) ++ ++@menu ++* Basic Commands:: ++* Help Commands:: ++* Stack Basics:: ++* Numeric Entry:: ++* Algebraic Entry:: ++* Quick Calculator:: ++* Prefix Arguments:: ++* Undo:: ++* Error Messages:: ++* Multiple Calculators:: ++* Troubleshooting Commands:: ++@end menu ++ ++@node Basic Commands, Help Commands, Introduction, Introduction ++@section Basic Commands ++ ++@noindent ++@pindex calc ++@pindex calc-mode ++@cindex Starting the Calculator ++@cindex Running the Calculator ++To start the Calculator in its standard interface, type @kbd{M-x calc}. ++By default this creates a pair of small windows, @samp{*Calculator*} ++and @samp{*Calc Trail*}. The former displays the contents of the ++Calculator stack and is manipulated exclusively through Calc commands. ++It is possible (though not usually necessary) to create several Calc ++mode buffers each of which has an independent stack, undo list, and ++mode settings. There is exactly one Calc Trail buffer; it records a ++list of the results of all calculations that have been done. The ++Calc Trail buffer uses a variant of Calc mode, so Calculator commands ++still work when the trail buffer's window is selected. It is possible ++to turn the trail window off, but the @samp{*Calc Trail*} buffer itself ++still exists and is updated silently. @xref{Trail Commands}. ++ ++@kindex C-x * c ++@kindex C-x * * ++@ignore ++@mindex @null ++@end ignore ++In most installations, the @kbd{C-x * c} key sequence is a more ++convenient way to start the Calculator. Also, @kbd{C-x * *} ++is a synonym for @kbd{C-x * c} unless you last used Calc ++in its Keypad mode. ++ ++@kindex x ++@kindex M-x ++@pindex calc-execute-extended-command ++Most Calc commands use one or two keystrokes. Lower- and upper-case ++letters are distinct. Commands may also be entered in full @kbd{M-x} form; ++for some commands this is the only form. As a convenience, the @kbd{x} ++key (@code{calc-execute-extended-command}) ++is like @kbd{M-x} except that it enters the initial string @samp{calc-} ++for you. For example, the following key sequences are equivalent: ++@kbd{S}, @kbd{M-x calc-sin @key{RET}}, @kbd{x sin @key{RET}}. ++ ++Although Calc is designed to be used from the keyboard, some of ++Calc's more common commands are available from a menu. In the menu, the ++arguments to the functions are given by referring to their stack level ++numbers. ++ ++@cindex Extensions module ++@cindex @file{calc-ext} module ++The Calculator exists in many parts. When you type @kbd{C-x * c}, the ++Emacs ``auto-load'' mechanism will bring in only the first part, which ++contains the basic arithmetic functions. The other parts will be ++auto-loaded the first time you use the more advanced commands like trig ++functions or matrix operations. This is done to improve the response time ++of the Calculator in the common case when all you need to do is a ++little arithmetic. If for some reason the Calculator fails to load an ++extension module automatically, you can force it to load all the ++extensions by using the @kbd{C-x * L} (@code{calc-load-everything}) ++command. @xref{Mode Settings}. ++ ++If you type @kbd{M-x calc} or @kbd{C-x * c} with any numeric prefix argument, ++the Calculator is loaded if necessary, but it is not actually started. ++If the argument is positive, the @file{calc-ext} extensions are also ++loaded if necessary. User-written Lisp code that wishes to make use ++of Calc's arithmetic routines can use @samp{(calc 0)} or @samp{(calc 1)} ++to auto-load the Calculator. ++ ++@kindex C-x * b ++@pindex full-calc ++If you type @kbd{C-x * b}, then next time you use @kbd{C-x * c} you ++will get a Calculator that uses the full height of the Emacs screen. ++When full-screen mode is on, @kbd{C-x * c} runs the @code{full-calc} ++command instead of @code{calc}. From the Unix shell you can type ++@samp{emacs -f full-calc} to start a new Emacs specifically for use ++as a calculator. When Calc is started from the Emacs command line ++like this, Calc's normal ``quit'' commands actually quit Emacs itself. ++ ++@kindex C-x * o ++@pindex calc-other-window ++The @kbd{C-x * o} command is like @kbd{C-x * c} except that the Calc ++window is not actually selected. If you are already in the Calc ++window, @kbd{C-x * o} switches you out of it. (The regular Emacs ++@kbd{C-x o} command would also work for this, but it has a ++tendency to drop you into the Calc Trail window instead, which ++@kbd{C-x * o} takes care not to do.) ++ ++@ignore ++@mindex C-x * q ++@end ignore ++For one quick calculation, you can type @kbd{C-x * q} (@code{quick-calc}) ++which prompts you for a formula (like @samp{2+3/4}). The result is ++displayed at the bottom of the Emacs screen without ever creating ++any special Calculator windows. @xref{Quick Calculator}. ++ ++@ignore ++@mindex C-x * k ++@end ignore ++Finally, if you are using the X window system you may want to try ++@kbd{C-x * k} (@code{calc-keypad}) which runs Calc with a ++``calculator keypad'' picture as well as a stack display. Click on ++the keys with the mouse to operate the calculator. @xref{Keypad Mode}. ++ ++@kindex q ++@pindex calc-quit ++@cindex Quitting the Calculator ++@cindex Exiting the Calculator ++The @kbd{q} key (@code{calc-quit}) exits Calc mode and closes the ++Calculator's window(s). It does not delete the Calculator buffers. ++If you type @kbd{M-x calc} again, the Calculator will reappear with the ++contents of the stack intact. Typing @kbd{C-x * c} or @kbd{C-x * *} ++again from inside the Calculator buffer is equivalent to executing ++@code{calc-quit}; you can think of @kbd{C-x * *} as toggling the ++Calculator on and off. ++ ++@kindex C-x * x ++The @kbd{C-x * x} command also turns the Calculator off, no matter which ++user interface (standard, Keypad, or Embedded) is currently active. ++It also cancels @code{calc-edit} mode if used from there. ++ ++@kindex d @key{SPC} ++@pindex calc-refresh ++@cindex Refreshing a garbled display ++@cindex Garbled displays, refreshing ++The @kbd{d @key{SPC}} key sequence (@code{calc-refresh}) redraws the contents ++of the Calculator buffer from memory. Use this if the contents of the ++buffer have been damaged somehow. ++ ++@ignore ++@mindex o ++@end ignore ++The @kbd{o} key (@code{calc-realign}) moves the cursor back to its ++``home'' position at the bottom of the Calculator buffer. ++ ++@kindex < ++@kindex > ++@pindex calc-scroll-left ++@pindex calc-scroll-right ++@cindex Horizontal scrolling ++@cindex Scrolling ++@cindex Wide text, scrolling ++The @kbd{<} and @kbd{>} keys are bound to @code{calc-scroll-left} and ++@code{calc-scroll-right}. These are just like the normal horizontal ++scrolling commands except that they scroll one half-screen at a time by ++default. (Calc formats its output to fit within the bounds of the ++window whenever it can.) ++ ++@kindex @{ ++@kindex @} ++@pindex calc-scroll-down ++@pindex calc-scroll-up ++@cindex Vertical scrolling ++The @kbd{@{} and @kbd{@}} keys are bound to @code{calc-scroll-down} ++and @code{calc-scroll-up}. They scroll up or down by one-half the ++height of the Calc window. ++ ++@kindex C-x * 0 ++@pindex calc-reset ++The @kbd{C-x * 0} command (@code{calc-reset}; that's @kbd{C-x *} followed ++by a zero) resets the Calculator to its initial state. This clears ++the stack, resets all the modes to their initial values (the values ++that were saved with @kbd{m m} (@code{calc-save-modes})), clears the ++caches (@pxref{Caches}), and so on. (It does @emph{not} erase the ++values of any variables.) With an argument of 0, Calc will be reset to ++its default state; namely, the modes will be given their default values. ++With a positive prefix argument, @kbd{C-x * 0} preserves the contents of ++the stack but resets everything else to its initial state; with a ++negative prefix argument, @kbd{C-x * 0} preserves the contents of the ++stack but resets everything else to its default state. ++ ++@node Help Commands, Stack Basics, Basic Commands, Introduction ++@section Help Commands ++ ++@noindent ++@cindex Help commands ++@kindex ? ++@pindex calc-help ++The @kbd{?} key (@code{calc-help}) displays a series of brief help messages. ++Some keys (such as @kbd{b} and @kbd{d}) are prefix keys, like Emacs' ++@key{ESC} and @kbd{C-x} prefixes. You can type ++@kbd{?} after a prefix to see a list of commands beginning with that ++prefix. (If the message includes @samp{[MORE]}, press @kbd{?} again ++to see additional commands for that prefix.) ++ ++@kindex h h ++@pindex calc-full-help ++The @kbd{h h} (@code{calc-full-help}) command displays all the @kbd{?} ++responses at once. When printed, this makes a nice, compact (three pages) ++summary of Calc keystrokes. ++ ++In general, the @kbd{h} key prefix introduces various commands that ++provide help within Calc. Many of the @kbd{h} key functions are ++Calc-specific analogues to the @kbd{C-h} functions for Emacs help. ++ ++@kindex h i ++@kindex C-x * i ++@kindex i ++@pindex calc-info ++The @kbd{h i} (@code{calc-info}) command runs the Emacs Info system ++to read this manual on-line. This is basically the same as typing ++@kbd{C-h i} (the regular way to run the Info system), then, if Info ++is not already in the Calc manual, selecting the beginning of the ++manual. The @kbd{C-x * i} command is another way to read the Calc ++manual; it is different from @kbd{h i} in that it works any time, ++not just inside Calc. The plain @kbd{i} key is also equivalent to ++@kbd{h i}, though this key is obsolete and may be replaced with a ++different command in a future version of Calc. ++ ++@kindex h t ++@kindex C-x * t ++@pindex calc-tutorial ++The @kbd{h t} (@code{calc-tutorial}) command runs the Info system on ++the Tutorial section of the Calc manual. It is like @kbd{h i}, ++except that it selects the starting node of the tutorial rather ++than the beginning of the whole manual. (It actually selects the ++node ``Interactive Tutorial'' which tells a few things about ++using the Info system before going on to the actual tutorial.) ++The @kbd{C-x * t} key is equivalent to @kbd{h t} (but it works at ++all times). ++ ++@kindex h s ++@kindex C-x * s ++@pindex calc-info-summary ++The @kbd{h s} (@code{calc-info-summary}) command runs the Info system ++on the Summary node of the Calc manual. @xref{Summary}. The @kbd{C-x * s} ++key is equivalent to @kbd{h s}. ++ ++@kindex h k ++@pindex calc-describe-key ++The @kbd{h k} (@code{calc-describe-key}) command looks up a key ++sequence in the Calc manual. For example, @kbd{h k H a S} looks ++up the documentation on the @kbd{H a S} (@code{calc-solve-for}) ++command. This works by looking up the textual description of ++the key(s) in the Key Index of the manual, then jumping to the ++node indicated by the index. ++ ++Most Calc commands do not have traditional Emacs documentation ++strings, since the @kbd{h k} command is both more convenient and ++more instructive. This means the regular Emacs @kbd{C-h k} ++(@code{describe-key}) command will not be useful for Calc keystrokes. ++ ++@kindex h c ++@pindex calc-describe-key-briefly ++The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a ++key sequence and displays a brief one-line description of it at ++the bottom of the screen. It looks for the key sequence in the ++Summary node of the Calc manual; if it doesn't find the sequence ++there, it acts just like its regular Emacs counterpart @kbd{C-h c} ++(@code{describe-key-briefly}). For example, @kbd{h c H a S} ++gives the description: ++ ++@smallexample ++H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes) ++@end smallexample ++ ++@noindent ++which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for} ++takes a value @expr{a} from the stack, prompts for a value @expr{v}, ++then applies the algebraic function @code{fsolve} to these values. ++The @samp{?=notes} message means you can now type @kbd{?} to see ++additional notes from the summary that apply to this command. ++ ++@kindex h f ++@pindex calc-describe-function ++The @kbd{h f} (@code{calc-describe-function}) command looks up an ++algebraic function or a command name in the Calc manual. Enter an ++algebraic function name to look up that function in the Function ++Index or enter a command name beginning with @samp{calc-} to look it ++up in the Command Index. This command will also look up operator ++symbols that can appear in algebraic formulas, like @samp{%} and ++@samp{=>}. ++ ++@kindex h v ++@pindex calc-describe-variable ++The @kbd{h v} (@code{calc-describe-variable}) command looks up a ++variable in the Calc manual. Enter a variable name like @code{pi} or ++@code{PlotRejects}. ++ ++@kindex h b ++@pindex describe-bindings ++The @kbd{h b} (@code{calc-describe-bindings}) command is just like ++@kbd{C-h b}, except that only local (Calc-related) key bindings are ++listed. ++ ++@kindex h n ++The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays ++the ``news'' or change history of Calc. This is kept in the file ++@file{README}, which Calc looks for in the same directory as the Calc ++source files. ++ ++@kindex h C-c ++@kindex h C-d ++@kindex h C-w ++The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying, ++distribution, and warranty information about Calc. These work by ++pulling up the appropriate parts of the ``Copying'' or ``Reporting ++Bugs'' sections of the manual. ++ ++@node Stack Basics, Numeric Entry, Help Commands, Introduction ++@section Stack Basics ++ ++@noindent ++@cindex Stack basics ++@c [fix-tut RPN Calculations and the Stack] ++Calc uses RPN notation. If you are not familiar with RPN, @pxref{RPN ++Tutorial}. ++ ++To add the numbers 1 and 2 in Calc you would type the keys: ++@kbd{1 @key{RET} 2 +}. ++(@key{RET} corresponds to the @key{ENTER} key on most calculators.) ++The first three keystrokes ``push'' the numbers 1 and 2 onto the stack. The ++@kbd{+} key always ``pops'' the top two numbers from the stack, adds them, ++and pushes the result (3) back onto the stack. This number is ready for ++further calculations: @kbd{5 -} pushes 5 onto the stack, then pops the ++3 and 5, subtracts them, and pushes the result (@mathit{-2}). ++ ++Note that the ``top'' of the stack actually appears at the @emph{bottom} ++of the buffer. A line containing a single @samp{.} character signifies ++the end of the buffer; Calculator commands operate on the number(s) ++directly above this line. The @kbd{d t} (@code{calc-truncate-stack}) ++command allows you to move the @samp{.} marker up and down in the stack; ++@pxref{Truncating the Stack}. ++ ++@kindex d l ++@pindex calc-line-numbering ++Stack elements are numbered consecutively, with number 1 being the top of ++the stack. These line numbers are ordinarily displayed on the lefthand side ++of the window. The @kbd{d l} (@code{calc-line-numbering}) command controls ++whether these numbers appear. (Line numbers may be turned off since they ++slow the Calculator down a bit and also clutter the display.) ++ ++@kindex o ++@pindex calc-realign ++The unshifted letter @kbd{o} (@code{calc-realign}) command repositions ++the cursor to its top-of-stack ``home'' position. It also undoes any ++horizontal scrolling in the window. If you give it a numeric prefix ++argument, it instead moves the cursor to the specified stack element. ++ ++The @key{RET} (or equivalent @key{SPC}) key is only required to separate ++two consecutive numbers. ++(After all, if you typed @kbd{1 2} by themselves the Calculator ++would enter the number 12.) If you press @key{RET} or @key{SPC} @emph{not} ++right after typing a number, the key duplicates the number on the top of ++the stack. @kbd{@key{RET} *} is thus a handy way to square a number. ++ ++The @key{DEL} key pops and throws away the top number on the stack. ++The @key{TAB} key swaps the top two objects on the stack. ++@xref{Stack and Trail}, for descriptions of these and other stack-related ++commands. ++ ++@node Numeric Entry, Algebraic Entry, Stack Basics, Introduction ++@section Numeric Entry ++ ++@noindent ++@kindex 0-9 ++@kindex . ++@kindex e ++@cindex Numeric entry ++@cindex Entering numbers ++Pressing a digit or other numeric key begins numeric entry using the ++minibuffer. The number is pushed on the stack when you press the @key{RET} ++or @key{SPC} keys. If you press any other non-numeric key, the number is ++pushed onto the stack and the appropriate operation is performed. If ++you press a numeric key which is not valid, the key is ignored. ++ ++@cindex Minus signs ++@cindex Negative numbers, entering ++@kindex _ ++There are three different concepts corresponding to the word ``minus,'' ++typified by @expr{a-b} (subtraction), @expr{-x} ++(change-sign), and @expr{-5} (negative number). Calc uses three ++different keys for these operations, respectively: ++@kbd{-}, @kbd{n}, and @kbd{_} (the underscore). The @kbd{-} key subtracts ++the two numbers on the top of the stack. The @kbd{n} key changes the sign ++of the number on the top of the stack or the number currently being entered. ++The @kbd{_} key begins entry of a negative number or changes the sign of ++the number currently being entered. The following sequences all enter the ++number @mathit{-5} onto the stack: @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}}, ++@kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}. ++ ++Some other keys are active during numeric entry, such as @kbd{#} for ++non-decimal numbers, @kbd{:} for fractions, and @kbd{@@} for HMS forms. ++These notations are described later in this manual with the corresponding ++data types. @xref{Data Types}. ++ ++During numeric entry, the only editing key available is @key{DEL}. ++ ++@node Algebraic Entry, Quick Calculator, Numeric Entry, Introduction ++@section Algebraic Entry ++ ++@noindent ++@kindex ' ++@pindex calc-algebraic-entry ++@cindex Algebraic notation ++@cindex Formulas, entering ++The @kbd{'} (@code{calc-algebraic-entry}) command can be used to enter ++calculations in algebraic form. This is accomplished by typing the ++apostrophe key, ', followed by the expression in standard format: ++ ++@example ++' 2+3*4 @key{RET}. ++@end example ++ ++@noindent ++This will compute ++@texline @math{2+(3\times4) = 14} ++@infoline @expr{2+(3*4) = 14} ++and push it on the stack. If you wish you can ++ignore the RPN aspect of Calc altogether and simply enter algebraic ++expressions in this way. You may want to use @key{DEL} every so often to ++clear previous results off the stack. ++ ++You can press the apostrophe key during normal numeric entry to switch ++the half-entered number into Algebraic entry mode. One reason to do ++this would be to fix a typo, as the full Emacs cursor motion and editing ++keys are available during algebraic entry but not during numeric entry. ++ ++In the same vein, during either numeric or algebraic entry you can ++press @kbd{`} (backquote) to switch to @code{calc-edit} mode, where ++you complete your half-finished entry in a separate buffer. ++@xref{Editing Stack Entries}. ++ ++@kindex m a ++@pindex calc-algebraic-mode ++@cindex Algebraic Mode ++If you prefer algebraic entry, you can use the command @kbd{m a} ++(@code{calc-algebraic-mode}) to set Algebraic mode. In this mode, ++digits and other keys that would normally start numeric entry instead ++start full algebraic entry; as long as your formula begins with a digit ++you can omit the apostrophe. Open parentheses and square brackets also ++begin algebraic entry. You can still do RPN calculations in this mode, ++but you will have to press @key{RET} to terminate every number: ++@kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same ++thing as @kbd{2*3+4 @key{RET}}. ++ ++@cindex Incomplete Algebraic Mode ++If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a} ++command, it enables Incomplete Algebraic mode; this is like regular ++Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys ++only. Numeric keys still begin a numeric entry in this mode. ++ ++@kindex m t ++@pindex calc-total-algebraic-mode ++@cindex Total Algebraic Mode ++The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even ++stronger algebraic-entry mode, in which @emph{all} regular letter and ++punctuation keys begin algebraic entry. Use this if you prefer typing ++@w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of ++@kbd{a f}, and so on. To type regular Calc commands when you are in ++Total Algebraic mode, hold down the @key{META} key. Thus @kbd{M-q} ++is the command to quit Calc, @kbd{M-p} sets the precision, and ++@kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns Total Algebraic ++mode back off again. Meta keys also terminate algebraic entry, so ++that @kbd{2+3 M-S} is equivalent to @kbd{2+3 @key{RET} M-S}. The symbol ++@samp{Alg*} will appear in the mode line whenever you are in this mode. ++ ++Pressing @kbd{'} (the apostrophe) a second time re-enters the previous ++algebraic formula. You can then use the normal Emacs editing keys to ++modify this formula to your liking before pressing @key{RET}. ++ ++@kindex $ ++@cindex Formulas, referring to stack ++Within a formula entered from the keyboard, the symbol @kbd{$} ++represents the number on the top of the stack. If an entered formula ++contains any @kbd{$} characters, the Calculator replaces the top of ++stack with that formula rather than simply pushing the formula onto the ++stack. Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2 ++@key{RET}} replaces it with 6. Note that the @kbd{$} key always ++initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the ++first character in the new formula. ++ ++Higher stack elements can be accessed from an entered formula with the ++symbols @kbd{$$}, @kbd{$$$}, and so on. The number of stack elements ++removed (to be replaced by the entered values) equals the number of dollar ++signs in the longest such symbol in the formula. For example, @samp{$$+$$$} ++adds the second and third stack elements, replacing the top three elements ++with the answer. (All information about the top stack element is thus lost ++since no single @samp{$} appears in this formula.) ++ ++A slightly different way to refer to stack elements is with a dollar ++sign followed by a number: @samp{$1}, @samp{$2}, and so on are much ++like @samp{$}, @samp{$$}, etc., except that stack entries referred ++to numerically are not replaced by the algebraic entry. That is, while ++@samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5 ++on the stack and pushes an additional 6. ++ ++If a sequence of formulas are entered separated by commas, each formula ++is pushed onto the stack in turn. For example, @samp{1,2,3} pushes ++those three numbers onto the stack (leaving the 3 at the top), and ++@samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6. Also, ++@samp{$,$$} exchanges the top two elements of the stack, just like the ++@key{TAB} key. ++ ++You can finish an algebraic entry with @kbd{M-=} or @kbd{M-@key{RET}} instead ++of @key{RET}. This uses @kbd{=} to evaluate the variables in each ++formula that goes onto the stack. (Thus @kbd{' pi @key{RET}} pushes ++the variable @samp{pi}, but @kbd{' pi M-@key{RET}} pushes 3.1415.) ++ ++If you finish your algebraic entry by pressing @key{LFD} (or @kbd{C-j}) ++instead of @key{RET}, Calc disables the default simplifications ++(as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry ++is being pushed on the stack. Thus @kbd{' 1+2 @key{RET}} pushes 3 ++on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @expr{1+2}; ++you might then press @kbd{=} when it is time to evaluate this formula. ++ ++@node Quick Calculator, Prefix Arguments, Algebraic Entry, Introduction ++@section ``Quick Calculator'' Mode ++ ++@noindent ++@kindex C-x * q ++@pindex quick-calc ++@cindex Quick Calculator ++There is another way to invoke the Calculator if all you need to do ++is make one or two quick calculations. Type @kbd{C-x * q} (or ++@kbd{M-x quick-calc}), then type any formula as an algebraic entry. ++The Calculator will compute the result and display it in the echo ++area, without ever actually putting up a Calc window. ++ ++You can use the @kbd{$} character in a Quick Calculator formula to ++refer to the previous Quick Calculator result. Older results are ++not retained; the Quick Calculator has no effect on the full ++Calculator's stack or trail. If you compute a result and then ++forget what it was, just run @code{C-x * q} again and enter ++@samp{$} as the formula. ++ ++If this is the first time you have used the Calculator in this Emacs ++session, the @kbd{C-x * q} command will create the @code{*Calculator*} ++buffer and perform all the usual initializations; it simply will ++refrain from putting that buffer up in a new window. The Quick ++Calculator refers to the @code{*Calculator*} buffer for all mode ++settings. Thus, for example, to set the precision that the Quick ++Calculator uses, simply run the full Calculator momentarily and use ++the regular @kbd{p} command. ++ ++If you use @code{C-x * q} from inside the Calculator buffer, the ++effect is the same as pressing the apostrophe key (algebraic entry). ++ ++The result of a Quick calculation is placed in the Emacs ``kill ring'' ++as well as being displayed. A subsequent @kbd{C-y} command will ++yank the result into the editing buffer. You can also use this ++to yank the result into the next @kbd{C-x * q} input line as a more ++explicit alternative to @kbd{$} notation, or to yank the result ++into the Calculator stack after typing @kbd{C-x * c}. ++ ++If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead ++of @key{RET}, the result is inserted immediately into the current ++buffer rather than going into the kill ring. ++ ++Quick Calculator results are actually evaluated as if by the @kbd{=} ++key (which replaces variable names by their stored values, if any). ++If the formula you enter is an assignment to a variable using the ++@samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1}, ++then the result of the evaluation is stored in that Calc variable. ++@xref{Store and Recall}. ++ ++If the result is an integer and the current display radix is decimal, ++the number will also be displayed in hex, octal and binary formats. If ++the integer is in the range from 1 to 126, it will also be displayed as ++an ASCII character. ++ ++For example, the quoted character @samp{"x"} produces the vector ++result @samp{[120]} (because 120 is the ASCII code of the lower-case ++`x'; @pxref{Strings}). Since this is a vector, not an integer, it ++is displayed only according to the current mode settings. But ++running Quick Calc again and entering @samp{120} will produce the ++result @samp{120 (16#78, 8#170, x)} which shows the number in its ++decimal, hexadecimal, octal, and ASCII forms. ++ ++Please note that the Quick Calculator is not any faster at loading ++or computing the answer than the full Calculator; the name ``quick'' ++merely refers to the fact that it's much less hassle to use for ++small calculations. ++ ++@node Prefix Arguments, Undo, Quick Calculator, Introduction ++@section Numeric Prefix Arguments ++ ++@noindent ++Many Calculator commands use numeric prefix arguments. Some, such as ++@kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of ++the prefix argument or use a default if you don't use a prefix. ++Others (like @kbd{d f} (@code{calc-fix-notation})) require an argument ++and prompt for a number if you don't give one as a prefix. ++ ++As a rule, stack-manipulation commands accept a numeric prefix argument ++which is interpreted as an index into the stack. A positive argument ++operates on the top @var{n} stack entries; a negative argument operates ++on the @var{n}th stack entry in isolation; and a zero argument operates ++on the entire stack. ++ ++Most commands that perform computations (such as the arithmetic and ++scientific functions) accept a numeric prefix argument that allows the ++operation to be applied across many stack elements. For unary operations ++(that is, functions of one argument like absolute value or complex ++conjugate), a positive prefix argument applies that function to the top ++@var{n} stack entries simultaneously, and a negative argument applies it ++to the @var{n}th stack entry only. For binary operations (functions of ++two arguments like addition, GCD, and vector concatenation), a positive ++prefix argument ``reduces'' the function across the top @var{n} ++stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries; ++@pxref{Reducing and Mapping}), and a negative argument maps the next-to-top ++@var{n} stack elements with the top stack element as a second argument ++(for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements). ++This feature is not available for operations which use the numeric prefix ++argument for some other purpose. ++ ++Numeric prefixes are specified the same way as always in Emacs: Press ++a sequence of @key{META}-digits, or press @key{ESC} followed by digits, ++or press @kbd{C-u} followed by digits. Some commands treat plain ++@kbd{C-u} (without any actual digits) specially. ++ ++@kindex ~ ++@pindex calc-num-prefix ++You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the ++top of the stack and enter it as the numeric prefix for the next command. ++For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate ++(silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2 ++to the fourth power and set the precision to that value. ++ ++Conversely, if you have typed a numeric prefix argument the @kbd{~} key ++pushes it onto the stack in the form of an integer. ++ ++@node Undo, Error Messages, Prefix Arguments, Introduction ++@section Undoing Mistakes ++ ++@noindent ++@kindex U ++@kindex C-_ ++@pindex calc-undo ++@cindex Mistakes, undoing ++@cindex Undoing mistakes ++@cindex Errors, undoing ++The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation. ++If that operation added or dropped objects from the stack, those objects ++are removed or restored. If it was a ``store'' operation, you are ++queried whether or not to restore the variable to its original value. ++The @kbd{U} key may be pressed any number of times to undo successively ++farther back in time; with a numeric prefix argument it undoes a ++specified number of operations. The undo history is cleared only by the ++@kbd{q} (@code{calc-quit}) command. (Recall that @kbd{C-x * c} is ++synonymous with @code{calc-quit} while inside the Calculator; this ++also clears the undo history.) ++ ++Currently the mode-setting commands (like @code{calc-precision}) are not ++undoable. You can undo past a point where you changed a mode, but you ++will need to reset the mode yourself. ++ ++@kindex D ++@pindex calc-redo ++@cindex Redoing after an Undo ++The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was ++mistakenly undone. Pressing @kbd{U} with a negative prefix argument is ++equivalent to executing @code{calc-redo}. You can redo any number of ++times, up to the number of recent consecutive undo commands. Redo ++information is cleared whenever you give any command that adds new undo ++information, i.e., if you undo, then enter a number on the stack or make ++any other change, then it will be too late to redo. ++ ++@kindex M-@key{RET} ++@pindex calc-last-args ++@cindex Last-arguments feature ++@cindex Arguments, restoring ++The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that ++it restores the arguments of the most recent command onto the stack; ++however, it does not remove the result of that command. Given a numeric ++prefix argument, this command applies to the @expr{n}th most recent ++command which removed items from the stack; it pushes those items back ++onto the stack. ++ ++The @kbd{K} (@code{calc-keep-args}) command provides a related function ++to @kbd{M-@key{RET}}. @xref{Stack and Trail}. ++ ++It is also possible to recall previous results or inputs using the trail. ++@xref{Trail Commands}. ++ ++The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}. ++ ++@node Error Messages, Multiple Calculators, Undo, Introduction ++@section Error Messages ++ ++@noindent ++@kindex w ++@pindex calc-why ++@cindex Errors, messages ++@cindex Why did an error occur? ++Many situations that would produce an error message in other calculators ++simply create unsimplified formulas in the Emacs Calculator. For example, ++@kbd{1 @key{RET} 0 /} pushes the formula @expr{1 / 0}; @w{@kbd{0 L}} pushes ++the formula @samp{ln(0)}. Floating-point overflow and underflow are also ++reasons for this to happen. ++ ++When a function call must be left in symbolic form, Calc usually ++produces a message explaining why. Messages that are probably ++surprising or indicative of user errors are displayed automatically. ++Other messages are simply kept in Calc's memory and are displayed only ++if you type @kbd{w} (@code{calc-why}). You can also press @kbd{w} if ++the same computation results in several messages. (The first message ++will end with @samp{[w=more]} in this case.) ++ ++@kindex d w ++@pindex calc-auto-why ++The @kbd{d w} (@code{calc-auto-why}) command controls when error messages ++are displayed automatically. (Calc effectively presses @kbd{w} for you ++after your computation finishes.) By default, this occurs only for ++``important'' messages. The other possible modes are to report ++@emph{all} messages automatically, or to report none automatically (so ++that you must always press @kbd{w} yourself to see the messages). ++ ++@node Multiple Calculators, Troubleshooting Commands, Error Messages, Introduction ++@section Multiple Calculators ++ ++@noindent ++@pindex another-calc ++It is possible to have any number of Calc mode buffers at once. ++Usually this is done by executing @kbd{M-x another-calc}, which ++is similar to @kbd{C-x * c} except that if a @samp{*Calculator*} ++buffer already exists, a new, independent one with a name of the ++form @samp{*Calculator*<@var{n}>} is created. You can also use the ++command @code{calc-mode} to put any buffer into Calculator mode, but ++this would ordinarily never be done. ++ ++The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer; ++it only closes its window. Use @kbd{M-x kill-buffer} to destroy a ++Calculator buffer. ++ ++Each Calculator buffer keeps its own stack, undo list, and mode settings ++such as precision, angular mode, and display formats. In Emacs terms, ++variables such as @code{calc-stack} are buffer-local variables. The ++global default values of these variables are used only when a new ++Calculator buffer is created. The @code{calc-quit} command saves ++the stack and mode settings of the buffer being quit as the new defaults. ++ ++There is only one trail buffer, @samp{*Calc Trail*}, used by all ++Calculator buffers. ++ ++@node Troubleshooting Commands, , Multiple Calculators, Introduction ++@section Troubleshooting Commands ++ ++@noindent ++This section describes commands you can use in case a computation ++incorrectly fails or gives the wrong answer. ++ ++@xref{Reporting Bugs}, if you find a problem that appears to be due ++to a bug or deficiency in Calc. ++ ++@menu ++* Autoloading Problems:: ++* Recursion Depth:: ++* Caches:: ++* Debugging Calc:: ++@end menu ++ ++@node Autoloading Problems, Recursion Depth, Troubleshooting Commands, Troubleshooting Commands ++@subsection Autoloading Problems ++ ++@noindent ++The Calc program is split into many component files; components are ++loaded automatically as you use various commands that require them. ++Occasionally Calc may lose track of when a certain component is ++necessary; typically this means you will type a command and it won't ++work because some function you've never heard of was undefined. ++ ++@kindex C-x * L ++@pindex calc-load-everything ++If this happens, the easiest workaround is to type @kbd{C-x * L} ++(@code{calc-load-everything}) to force all the parts of Calc to be ++loaded right away. This will cause Emacs to take up a lot more ++memory than it would otherwise, but it's guaranteed to fix the problem. ++ ++@node Recursion Depth, Caches, Autoloading Problems, Troubleshooting Commands ++@subsection Recursion Depth ++ ++@noindent ++@kindex M ++@kindex I M ++@pindex calc-more-recursion-depth ++@pindex calc-less-recursion-depth ++@cindex Recursion depth ++@cindex ``Computation got stuck'' message ++@cindex @code{max-lisp-eval-depth} ++@cindex @code{max-specpdl-size} ++Calc uses recursion in many of its calculations. Emacs Lisp keeps a ++variable @code{max-lisp-eval-depth} which limits the amount of recursion ++possible in an attempt to recover from program bugs. If a calculation ++ever halts incorrectly with the message ``Computation got stuck or ++ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth}) ++to increase this limit. (Of course, this will not help if the ++calculation really did get stuck due to some problem inside Calc.) ++ ++The limit is always increased (multiplied) by a factor of two. There ++is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which ++decreases this limit by a factor of two, down to a minimum value of 200. ++The default value is 1000. ++ ++These commands also double or halve @code{max-specpdl-size}, another ++internal Lisp recursion limit. The minimum value for this limit is 600. ++ ++@node Caches, Debugging Calc, Recursion Depth, Troubleshooting Commands ++@subsection Caches ++ ++@noindent ++@cindex Caches ++@cindex Flushing caches ++Calc saves certain values after they have been computed once. For ++example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the ++constant @cpi{} to about 20 decimal places; if the current precision ++is greater than this, it will recompute @cpi{} using a series ++approximation. This value will not need to be recomputed ever again ++unless you raise the precision still further. Many operations such as ++logarithms and sines make use of similarly cached values such as ++@cpiover{4} and ++@texline @math{\ln 2}. ++@infoline @expr{ln(2)}. ++The visible effect of caching is that ++high-precision computations may seem to do extra work the first time. ++Other things cached include powers of two (for the binary arithmetic ++functions), matrix inverses and determinants, symbolic integrals, and ++data points computed by the graphing commands. ++ ++@pindex calc-flush-caches ++If you suspect a Calculator cache has become corrupt, you can use the ++@code{calc-flush-caches} command to reset all caches to the empty state. ++(This should only be necessary in the event of bugs in the Calculator.) ++The @kbd{C-x * 0} (with the zero key) command also resets caches along ++with all other aspects of the Calculator's state. ++ ++@node Debugging Calc, , Caches, Troubleshooting Commands ++@subsection Debugging Calc ++ ++@noindent ++A few commands exist to help in the debugging of Calc commands. ++@xref{Programming}, to see the various ways that you can write ++your own Calc commands. ++ ++@kindex Z T ++@pindex calc-timing ++The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode ++in which the timing of slow commands is reported in the Trail. ++Any Calc command that takes two seconds or longer writes a line ++to the Trail showing how many seconds it took. This value is ++accurate only to within one second. ++ ++All steps of executing a command are included; in particular, time ++taken to format the result for display in the stack and trail is ++counted. Some prompts also count time taken waiting for them to ++be answered, while others do not; this depends on the exact ++implementation of the command. For best results, if you are timing ++a sequence that includes prompts or multiple commands, define a ++keyboard macro to run the whole sequence at once. Calc's @kbd{X} ++command (@pxref{Keyboard Macros}) will then report the time taken ++to execute the whole macro. ++ ++Another advantage of the @kbd{X} command is that while it is ++executing, the stack and trail are not updated from step to step. ++So if you expect the output of your test sequence to leave a result ++that may take a long time to format and you don't wish to count ++this formatting time, end your sequence with a @key{DEL} keystroke ++to clear the result from the stack. When you run the sequence with ++@kbd{X}, Calc will never bother to format the large result. ++ ++Another thing @kbd{Z T} does is to increase the Emacs variable ++@code{gc-cons-threshold} to a much higher value (two million; the ++usual default in Calc is 250,000) for the duration of each command. ++This generally prevents garbage collection during the timing of ++the command, though it may cause your Emacs process to grow ++abnormally large. (Garbage collection time is a major unpredictable ++factor in the timing of Emacs operations.) ++ ++Another command that is useful when debugging your own Lisp ++extensions to Calc is @kbd{M-x calc-pass-errors}, which disables ++the error handler that changes the ``@code{max-lisp-eval-depth} ++exceeded'' message to the much more friendly ``Computation got ++stuck or ran too long.'' This handler interferes with the Emacs ++Lisp debugger's @code{debug-on-error} mode. Errors are reported ++in the handler itself rather than at the true location of the ++error. After you have executed @code{calc-pass-errors}, Lisp ++errors will be reported correctly but the user-friendly message ++will be lost. ++ ++@node Data Types, Stack and Trail, Introduction, Top ++@chapter Data Types ++ ++@noindent ++This chapter discusses the various types of objects that can be placed ++on the Calculator stack, how they are displayed, and how they are ++entered. (@xref{Data Type Formats}, for information on how these data ++types are represented as underlying Lisp objects.) ++ ++Integers, fractions, and floats are various ways of describing real ++numbers. HMS forms also for many purposes act as real numbers. These ++types can be combined to form complex numbers, modulo forms, error forms, ++or interval forms. (But these last four types cannot be combined ++arbitrarily:@: error forms may not contain modulo forms, for example.) ++Finally, all these types of numbers may be combined into vectors, ++matrices, or algebraic formulas. ++ ++@menu ++* Integers:: The most basic data type. ++* Fractions:: This and above are called @dfn{rationals}. ++* Floats:: This and above are called @dfn{reals}. ++* Complex Numbers:: This and above are called @dfn{numbers}. ++* Infinities:: ++* Vectors and Matrices:: ++* Strings:: ++* HMS Forms:: ++* Date Forms:: ++* Modulo Forms:: ++* Error Forms:: ++* Interval Forms:: ++* Incomplete Objects:: ++* Variables:: ++* Formulas:: ++@end menu ++ ++@node Integers, Fractions, Data Types, Data Types ++@section Integers ++ ++@noindent ++@cindex Integers ++The Calculator stores integers to arbitrary precision. Addition, ++subtraction, and multiplication of integers always yields an exact ++integer result. (If the result of a division or exponentiation of ++integers is not an integer, it is expressed in fractional or ++floating-point form according to the current Fraction mode. ++@xref{Fraction Mode}.) ++ ++A decimal integer is represented as an optional sign followed by a ++sequence of digits. Grouping (@pxref{Grouping Digits}) can be used to ++insert a comma at every third digit for display purposes, but you ++must not type commas during the entry of numbers. ++ ++@kindex # ++A non-decimal integer is represented as an optional sign, a radix ++between 2 and 36, a @samp{#} symbol, and one or more digits. For radix 11 ++and above, the letters A through Z (upper- or lower-case) count as ++digits and do not terminate numeric entry mode. @xref{Radix Modes}, for how ++to set the default radix for display of integers. Numbers of any radix ++may be entered at any time. If you press @kbd{#} at the beginning of a ++number, the current display radix is used. ++ ++@node Fractions, Floats, Integers, Data Types ++@section Fractions ++ ++@noindent ++@cindex Fractions ++A @dfn{fraction} is a ratio of two integers. Fractions are traditionally ++written ``2/3'' but Calc uses the notation @samp{2:3}. (The @kbd{/} key ++performs RPN division; the following two sequences push the number ++@samp{2:3} on the stack: @kbd{2 :@: 3 @key{RET}}, or @kbd{2 @key{RET} 3 /} ++assuming Fraction mode has been enabled.) ++When the Calculator produces a fractional result it always reduces it to ++simplest form, which may in fact be an integer. ++ ++Fractions may also be entered in a three-part form, where @samp{2:3:4} ++represents two-and-three-quarters. @xref{Fraction Formats}, for fraction ++display formats. ++ ++Non-decimal fractions are entered and displayed as ++@samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part ++form). The numerator and denominator always use the same radix. ++ ++@node Floats, Complex Numbers, Fractions, Data Types ++@section Floats ++ ++@noindent ++@cindex Floating-point numbers ++A floating-point number or @dfn{float} is a number stored in scientific ++notation. The number of significant digits in the fractional part is ++governed by the current floating precision (@pxref{Precision}). The ++range of acceptable values is from ++@texline @math{10^{-3999999}} ++@infoline @expr{10^-3999999} ++(inclusive) to ++@texline @math{10^{4000000}} ++@infoline @expr{10^4000000} ++(exclusive), plus the corresponding negative values and zero. ++ ++Calculations that would exceed the allowable range of values (such ++as @samp{exp(exp(20))}) are left in symbolic form by Calc. The ++messages ``floating-point overflow'' or ``floating-point underflow'' ++indicate that during the calculation a number would have been produced ++that was too large or too close to zero, respectively, to be represented ++by Calc. This does not necessarily mean the final result would have ++overflowed, just that an overflow occurred while computing the result. ++(In fact, it could report an underflow even though the final result ++would have overflowed!) ++ ++If a rational number and a float are mixed in a calculation, the result ++will in general be expressed as a float. Commands that require an integer ++value (such as @kbd{k g} [@code{gcd}]) will also accept integer-valued ++floats, i.e., floating-point numbers with nothing after the decimal point. ++ ++Floats are identified by the presence of a decimal point and/or an ++exponent. In general a float consists of an optional sign, digits ++including an optional decimal point, and an optional exponent consisting ++of an @samp{e}, an optional sign, and up to seven exponent digits. ++For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power, ++or 0.235. ++ ++Floating-point numbers are normally displayed in decimal notation with ++all significant figures shown. Exceedingly large or small numbers are ++displayed in scientific notation. Various other display options are ++available. @xref{Float Formats}. ++ ++@cindex Accuracy of calculations ++Floating-point numbers are stored in decimal, not binary. The result ++of each operation is rounded to the nearest value representable in the ++number of significant digits specified by the current precision, ++rounding away from zero in the case of a tie. Thus (in the default ++display mode) what you see is exactly what you get. Some operations such ++as square roots and transcendental functions are performed with several ++digits of extra precision and then rounded down, in an effort to make the ++final result accurate to the full requested precision. However, ++accuracy is not rigorously guaranteed. If you suspect the validity of a ++result, try doing the same calculation in a higher precision. The ++Calculator's arithmetic is not intended to be IEEE-conformant in any ++way. ++ ++While floats are always @emph{stored} in decimal, they can be entered ++and displayed in any radix just like integers and fractions. Since a ++float that is entered in a radix other that 10 will be converted to ++decimal, the number that Calc stores may not be exactly the number that ++was entered, it will be the closest decimal approximation given the ++current precison. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}} ++is a floating-point number whose digits are in the specified radix. ++Note that the @samp{.} is more aptly referred to as a ``radix point'' ++than as a decimal point in this case. The number @samp{8#123.4567} is ++defined as @samp{8#1234567 * 8^-4}. If the radix is 14 or less, you can ++use @samp{e} notation to write a non-decimal number in scientific ++notation. The exponent is written in decimal, and is considered to be a ++power of the radix: @samp{8#1234567e-4}. If the radix is 15 or above, ++the letter @samp{e} is a digit, so scientific notation must be written ++out, e.g., @samp{16#123.4567*16^2}. The first two exercises of the ++Modes Tutorial explore some of the properties of non-decimal floats. ++ ++@node Complex Numbers, Infinities, Floats, Data Types ++@section Complex Numbers ++ ++@noindent ++@cindex Complex numbers ++There are two supported formats for complex numbers: rectangular and ++polar. The default format is rectangular, displayed in the form ++@samp{(@var{real},@var{imag})} where @var{real} is the real part and ++@var{imag} is the imaginary part, each of which may be any real number. ++Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i} ++notation; @pxref{Complex Formats}. ++ ++Polar complex numbers are displayed in the form ++@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}' ++@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}' ++where @var{r} is the nonnegative magnitude and ++@texline @math{\theta} ++@infoline @var{theta} ++is the argument or phase angle. The range of ++@texline @math{\theta} ++@infoline @var{theta} ++depends on the current angular mode (@pxref{Angular Modes}); it is ++generally between @mathit{-180} and @mathit{+180} degrees or the equivalent range ++in radians. ++ ++Complex numbers are entered in stages using incomplete objects. ++@xref{Incomplete Objects}. ++ ++Operations on rectangular complex numbers yield rectangular complex ++results, and similarly for polar complex numbers. Where the two types ++are mixed, or where new complex numbers arise (as for the square root of ++a negative real), the current @dfn{Polar mode} is used to determine the ++type. @xref{Polar Mode}. ++ ++A complex result in which the imaginary part is zero (or the phase angle ++is 0 or 180 degrees or @cpi{} radians) is automatically converted to a real ++number. ++ ++@node Infinities, Vectors and Matrices, Complex Numbers, Data Types ++@section Infinities ++ ++@noindent ++@cindex Infinity ++@cindex @code{inf} variable ++@cindex @code{uinf} variable ++@cindex @code{nan} variable ++@vindex inf ++@vindex uinf ++@vindex nan ++The word @code{inf} represents the mathematical concept of @dfn{infinity}. ++Calc actually has three slightly different infinity-like values: ++@code{inf}, @code{uinf}, and @code{nan}. These are just regular ++variable names (@pxref{Variables}); you should avoid using these ++names for your own variables because Calc gives them special ++treatment. Infinities, like all variable names, are normally ++entered using algebraic entry. ++ ++Mathematically speaking, it is not rigorously correct to treat ++``infinity'' as if it were a number, but mathematicians often do ++so informally. When they say that @samp{1 / inf = 0}, what they ++really mean is that @expr{1 / x}, as @expr{x} becomes larger and ++larger, becomes arbitrarily close to zero. So you can imagine ++that if @expr{x} got ``all the way to infinity,'' then @expr{1 / x} ++would go all the way to zero. Similarly, when they say that ++@samp{exp(inf) = inf}, they mean that ++@texline @math{e^x} ++@infoline @expr{exp(x)} ++grows without bound as @expr{x} grows. The symbol @samp{-inf} likewise ++stands for an infinitely negative real value; for example, we say that ++@samp{exp(-inf) = 0}. You can have an infinity pointing in any ++direction on the complex plane: @samp{sqrt(-inf) = i inf}. ++ ++The same concept of limits can be used to define @expr{1 / 0}. We ++really want the value that @expr{1 / x} approaches as @expr{x} ++approaches zero. But if all we have is @expr{1 / 0}, we can't ++tell which direction @expr{x} was coming from. If @expr{x} was ++positive and decreasing toward zero, then we should say that ++@samp{1 / 0 = inf}. But if @expr{x} was negative and increasing ++toward zero, the answer is @samp{1 / 0 = -inf}. In fact, @expr{x} ++could be an imaginary number, giving the answer @samp{i inf} or ++@samp{-i inf}. Calc uses the special symbol @samp{uinf} to mean ++@dfn{undirected infinity}, i.e., a value which is infinitely ++large but with an unknown sign (or direction on the complex plane). ++ ++Calc actually has three modes that say how infinities are handled. ++Normally, infinities never arise from calculations that didn't ++already have them. Thus, @expr{1 / 0} is treated simply as an ++error and left unevaluated. The @kbd{m i} (@code{calc-infinite-mode}) ++command (@pxref{Infinite Mode}) enables a mode in which ++@expr{1 / 0} evaluates to @code{uinf} instead. There is also ++an alternative type of infinite mode which says to treat zeros ++as if they were positive, so that @samp{1 / 0 = inf}. While this ++is less mathematically correct, it may be the answer you want in ++some cases. ++ ++Since all infinities are ``as large'' as all others, Calc simplifies, ++e.g., @samp{5 inf} to @samp{inf}. Another example is ++@samp{5 - inf = -inf}, where the @samp{-inf} is so large that ++adding a finite number like five to it does not affect it. ++Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes ++that variables like @code{a} always stand for finite quantities. ++Just to show that infinities really are all the same size, ++note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's ++notation. ++ ++It's not so easy to define certain formulas like @samp{0 * inf} and ++@samp{inf / inf}. Depending on where these zeros and infinities ++came from, the answer could be literally anything. The latter ++formula could be the limit of @expr{x / x} (giving a result of one), ++or @expr{2 x / x} (giving two), or @expr{x^2 / x} (giving @code{inf}), ++or @expr{x / x^2} (giving zero). Calc uses the symbol @code{nan} ++to represent such an @dfn{indeterminate} value. (The name ``nan'' ++comes from analogy with the ``NAN'' concept of IEEE standard ++arithmetic; it stands for ``Not A Number.'' This is somewhat of a ++misnomer, since @code{nan} @emph{does} stand for some number or ++infinity, it's just that @emph{which} number it stands for ++cannot be determined.) In Calc's notation, @samp{0 * inf = nan} ++and @samp{inf / inf = nan}. A few other common indeterminate ++expressions are @samp{inf - inf} and @samp{inf ^ 0}. Also, ++@samp{0 / 0 = nan} if you have turned on Infinite mode ++(as described above). ++ ++Infinities are especially useful as parts of @dfn{intervals}. ++@xref{Interval Forms}. ++ ++@node Vectors and Matrices, Strings, Infinities, Data Types ++@section Vectors and Matrices ++ ++@noindent ++@cindex Vectors ++@cindex Plain vectors ++@cindex Matrices ++The @dfn{vector} data type is flexible and general. A vector is simply a ++list of zero or more data objects. When these objects are numbers, the ++whole is a vector in the mathematical sense. When these objects are ++themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}. ++A vector which is not a matrix is referred to here as a @dfn{plain vector}. ++ ++A vector is displayed as a list of values separated by commas and enclosed ++in square brackets: @samp{[1, 2, 3]}. Thus the following is a 2 row by ++3 column matrix: @samp{[[1, 2, 3], [4, 5, 6]]}. Vectors, like complex ++numbers, are entered as incomplete objects. @xref{Incomplete Objects}. ++During algebraic entry, vectors are entered all at once in the usual ++brackets-and-commas form. Matrices may be entered algebraically as nested ++vectors, or using the shortcut notation @w{@samp{[1, 2, 3; 4, 5, 6]}}, ++with rows separated by semicolons. The commas may usually be omitted ++when entering vectors: @samp{[1 2 3]}. Curly braces may be used in ++place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in ++this case. ++ ++Traditional vector and matrix arithmetic is also supported; ++@pxref{Basic Arithmetic} and @pxref{Matrix Functions}. ++Many other operations are applied to vectors element-wise. For example, ++the complex conjugate of a vector is a vector of the complex conjugates ++of its elements. ++ ++@ignore ++@starindex ++@end ignore ++@tindex vec ++Algebraic functions for building vectors include @samp{vec(a, b, c)} ++to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an ++@texline @math{n\times m} ++@infoline @var{n}x@var{m} ++matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers ++from 1 to @samp{n}. ++ ++@node Strings, HMS Forms, Vectors and Matrices, Data Types ++@section Strings ++ ++@noindent ++@kindex " ++@cindex Strings ++@cindex Character strings ++Character strings are not a special data type in the Calculator. ++Rather, a string is represented simply as a vector all of whose ++elements are integers in the range 0 to 255 (ASCII codes). You can ++enter a string at any time by pressing the @kbd{"} key. Quotation ++marks and backslashes are written @samp{\"} and @samp{\\}, respectively, ++inside strings. Other notations introduced by backslashes are: ++ ++@example ++@group ++\a 7 \^@@ 0 ++\b 8 \^a-z 1-26 ++\e 27 \^[ 27 ++\f 12 \^\\ 28 ++\n 10 \^] 29 ++\r 13 \^^ 30 ++\t 9 \^_ 31 ++ \^? 127 ++@end group ++@end example ++ ++@noindent ++Finally, a backslash followed by three octal digits produces any ++character from its ASCII code. ++ ++@kindex d " ++@pindex calc-display-strings ++Strings are normally displayed in vector-of-integers form. The ++@w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in ++which any vectors of small integers are displayed as quoted strings ++instead. ++ ++The backslash notations shown above are also used for displaying ++strings. Characters 128 and above are not translated by Calc; unless ++you have an Emacs modified for 8-bit fonts, these will show up in ++backslash-octal-digits notation. For characters below 32, and ++for character 127, Calc uses the backslash-letter combination if ++there is one, or otherwise uses a @samp{\^} sequence. ++ ++The only Calc feature that uses strings is @dfn{compositions}; ++@pxref{Compositions}. Strings also provide a convenient ++way to do conversions between ASCII characters and integers. ++ ++@ignore ++@starindex ++@end ignore ++@tindex string ++There is a @code{string} function which provides a different display ++format for strings. Basically, @samp{string(@var{s})}, where @var{s} ++is a vector of integers in the proper range, is displayed as the ++corresponding string of characters with no surrounding quotation ++marks or other modifications. Thus @samp{string("ABC")} (or ++@samp{string([65 66 67])}) will look like @samp{ABC} on the stack. ++This happens regardless of whether @w{@kbd{d "}} has been used. The ++only way to turn it off is to use @kbd{d U} (unformatted language ++mode) which will display @samp{string("ABC")} instead. ++ ++Control characters are displayed somewhat differently by @code{string}. ++Characters below 32, and character 127, are shown using @samp{^} notation ++(same as shown above, but without the backslash). The quote and ++backslash characters are left alone, as are characters 128 and above. ++ ++@ignore ++@starindex ++@end ignore ++@tindex bstring ++The @code{bstring} function is just like @code{string} except that ++the resulting string is breakable across multiple lines if it doesn't ++fit all on one line. Potential break points occur at every space ++character in the string. ++ ++@node HMS Forms, Date Forms, Strings, Data Types ++@section HMS Forms ++ ++@noindent ++@cindex Hours-minutes-seconds forms ++@cindex Degrees-minutes-seconds forms ++@dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular ++argument, the interpretation is Degrees-Minutes-Seconds. All functions ++that operate on angles accept HMS forms. These are interpreted as ++degrees regardless of the current angular mode. It is also possible to ++use HMS as the angular mode so that calculated angles are expressed in ++degrees, minutes, and seconds. ++ ++@kindex @@ ++@ignore ++@mindex @null ++@end ignore ++@kindex ' (HMS forms) ++@ignore ++@mindex @null ++@end ignore ++@kindex " (HMS forms) ++@ignore ++@mindex @null ++@end ignore ++@kindex h (HMS forms) ++@ignore ++@mindex @null ++@end ignore ++@kindex o (HMS forms) ++@ignore ++@mindex @null ++@end ignore ++@kindex m (HMS forms) ++@ignore ++@mindex @null ++@end ignore ++@kindex s (HMS forms) ++The default format for HMS values is ++@samp{@var{hours}@@ @var{mins}' @var{secs}"}. During entry, the letters ++@samp{h} (for ``hours'') or ++@samp{o} (approximating the ``degrees'' symbol) are accepted as well as ++@samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is ++accepted in place of @samp{"}. ++The @var{hours} value is an integer (or integer-valued float). ++The @var{mins} value is an integer or integer-valued float between 0 and 59. ++The @var{secs} value is a real number between 0 (inclusive) and 60 ++(exclusive). A positive HMS form is interpreted as @var{hours} + ++@var{mins}/60 + @var{secs}/3600. A negative HMS form is interpreted ++as @mathit{- @var{hours}} @mathit{-} @var{mins}/60 @mathit{-} @var{secs}/3600. ++Display format for HMS forms is quite flexible. @xref{HMS Formats}. ++ ++HMS forms can be added and subtracted. When they are added to numbers, ++the numbers are interpreted according to the current angular mode. HMS ++forms can also be multiplied and divided by real numbers. Dividing ++two HMS forms produces a real-valued ratio of the two angles. ++ ++@pindex calc-time ++@cindex Time of day ++Just for kicks, @kbd{M-x calc-time} pushes the current time of day on ++the stack as an HMS form. ++ ++@node Date Forms, Modulo Forms, HMS Forms, Data Types ++@section Date Forms ++ ++@noindent ++@cindex Date forms ++A @dfn{date form} represents a date and possibly an associated time. ++Simple date arithmetic is supported: Adding a number to a date ++produces a new date shifted by that many days; adding an HMS form to ++a date shifts it by that many hours. Subtracting two date forms ++computes the number of days between them (represented as a simple ++number). Many other operations, such as multiplying two date forms, ++are nonsensical and are not allowed by Calc. ++ ++Date forms are entered and displayed enclosed in @samp{< >} brackets. ++The default format is, e.g., @samp{} for dates, ++or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times. ++Input is flexible; date forms can be entered in any of the usual ++notations for dates and times. @xref{Date Formats}. ++ ++Date forms are stored internally as numbers, specifically the number ++of days since midnight on the morning of January 1 of the year 1 AD. ++If the internal number is an integer, the form represents a date only; ++if the internal number is a fraction or float, the form represents ++a date and time. For example, @samp{<6:00am Wed Jan 9, 1991>} ++is represented by the number 726842.25. The standard precision of ++12 decimal digits is enough to ensure that a (reasonable) date and ++time can be stored without roundoff error. ++ ++If the current precision is greater than 12, date forms will keep ++additional digits in the seconds position. For example, if the ++precision is 15, the seconds will keep three digits after the ++decimal point. Decreasing the precision below 12 may cause the ++time part of a date form to become inaccurate. This can also happen ++if astronomically high years are used, though this will not be an ++issue in everyday (or even everymillennium) use. Note that date ++forms without times are stored as exact integers, so roundoff is ++never an issue for them. ++ ++You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u} ++(@code{calc-unpack}) commands to get at the numerical representation ++of a date form. @xref{Packing and Unpacking}. ++ ++Date forms can go arbitrarily far into the future or past. Negative ++year numbers represent years BC. Calc uses a combination of the ++Gregorian and Julian calendars, following the history of Great ++Britain and the British colonies. This is the same calendar that ++is used by the @code{cal} program in most Unix implementations. ++ ++@cindex Julian calendar ++@cindex Gregorian calendar ++Some historical background: The Julian calendar was created by ++Julius Caesar in the year 46 BC as an attempt to fix the gradual ++drift caused by the lack of leap years in the calendar used ++until that time. The Julian calendar introduced an extra day in ++all years divisible by four. After some initial confusion, the ++calendar was adopted around the year we call 8 AD. Some centuries ++later it became apparent that the Julian year of 365.25 days was ++itself not quite right. In 1582 Pope Gregory XIII introduced the ++Gregorian calendar, which added the new rule that years divisible ++by 100, but not by 400, were not to be considered leap years ++despite being divisible by four. Many countries delayed adoption ++of the Gregorian calendar because of religious differences; ++in Britain it was put off until the year 1752, by which time ++the Julian calendar had fallen eleven days behind the true ++seasons. So the switch to the Gregorian calendar in early ++September 1752 introduced a discontinuity: The day after ++Sep 2, 1752 is Sep 14, 1752. Calc follows this convention. ++To take another example, Russia waited until 1918 before ++adopting the new calendar, and thus needed to remove thirteen ++days (between Feb 1, 1918 and Feb 14, 1918). This means that ++Calc's reckoning will be inconsistent with Russian history between ++1752 and 1918, and similarly for various other countries. ++ ++Today's timekeepers introduce an occasional ``leap second'' as ++well, but Calc does not take these minor effects into account. ++(If it did, it would have to report a non-integer number of days ++between, say, @samp{<12:00am Mon Jan 1, 1900>} and ++@samp{<12:00am Sat Jan 1, 2000>}.) ++ ++Calc uses the Julian calendar for all dates before the year 1752, ++including dates BC when the Julian calendar technically had not ++yet been invented. Thus the claim that day number @mathit{-10000} is ++called ``August 16, 28 BC'' should be taken with a grain of salt. ++ ++Please note that there is no ``year 0''; the day before ++@samp{} is @samp{}. These are ++days 0 and @mathit{-1} respectively in Calc's internal numbering scheme. ++ ++@cindex Julian day counting ++Another day counting system in common use is, confusingly, also called ++``Julian.'' The Julian day number is the numbers of days since ++12:00 noon (GMT) on Jan 1, 4713 BC, which in Calc's scheme (in GMT) ++is @mathit{-1721423.5} (recall that Calc starts at midnight instead ++of noon). Thus to convert a Calc date code obtained by unpacking a ++date form into a Julian day number, simply add 1721423.5 after ++compensating for the time zone difference. The built-in @kbd{t J} ++command performs this conversion for you. ++ ++The Julian day number is based on the Julian cycle, which was invented ++in 1583 by Joseph Justus Scaliger. Scaliger named it the Julian cycle ++since it is involves the Julian calendar, but some have suggested that ++Scaliger named it in honor of his father, Julius Caesar Scaliger. The ++Julian cycle is based it on three other cycles: the indiction cycle, ++the Metonic cycle, and the solar cycle. The indiction cycle is a 15 ++year cycle originally used by the Romans for tax purposes but later ++used to date medieval documents. The Metonic cycle is a 19 year ++cycle; 19 years is close to being a common multiple of a solar year ++and a lunar month, and so every 19 years the phases of the moon will ++occur on the same days of the year. The solar cycle is a 28 year ++cycle; the Julian calendar repeats itself every 28 years. The ++smallest time period which contains multiples of all three cycles is ++the least common multiple of 15 years, 19 years and 28 years, which ++(since they're pairwise relatively prime) is ++@texline @math{15\times 19\times 28 = 7980} years. ++@infoline 15*19*28 = 7980 years. ++This is the length of a Julian cycle. Working backwards, the previous ++year in which all three cycles began was 4713 BC, and so Scalinger ++chose that year as the beginning of a Julian cycle. Since at the time ++there were no historical records from before 4713 BC, using this year ++as a starting point had the advantage of avoiding negative year ++numbers. In 1849, the astronomer John Herschel (son of William ++Herschel) suggested using the number of days since the beginning of ++the Julian cycle as an astronomical dating system; this idea was taken ++up by other astronomers. (At the time, noon was the start of the ++astronomical day. Herschel originally suggested counting the days ++since Jan 1, 4713 BC at noon Alexandria time; this was later amended to ++noon GMT.) Julian day numbering is largely used in astronomy. ++ ++@cindex Unix time format ++The Unix operating system measures time as an integer number of ++seconds since midnight, Jan 1, 1970. To convert a Calc date ++value into a Unix time stamp, first subtract 719164 (the code ++for @samp{}), then multiply by 86400 (the number of ++seconds in a day) and press @kbd{R} to round to the nearest ++integer. If you have a date form, you can simply subtract the ++day @samp{} instead of unpacking and subtracting ++719164. Likewise, divide by 86400 and add @samp{} ++to convert from Unix time to a Calc date form. (Note that ++Unix normally maintains the time in the GMT time zone; you may ++need to subtract five hours to get New York time, or eight hours ++for California time. The same is usually true of Julian day ++counts.) The built-in @kbd{t U} command performs these ++conversions. ++ ++@node Modulo Forms, Error Forms, Date Forms, Data Types ++@section Modulo Forms ++ ++@noindent ++@cindex Modulo forms ++A @dfn{modulo form} is a real number which is taken modulo (i.e., within ++an integer multiple of) some value @var{M}. Arithmetic modulo @var{M} ++often arises in number theory. Modulo forms are written ++`@var{a} @tfn{mod} @var{M}', ++where @var{a} and @var{M} are real numbers or HMS forms, and ++@texline @math{0 \le a < M}. ++@infoline @expr{0 <= a < @var{M}}. ++In many applications @expr{a} and @expr{M} will be ++integers but this is not required. ++ ++@ignore ++@mindex M ++@end ignore ++@kindex M (modulo forms) ++@ignore ++@mindex mod ++@end ignore ++@tindex mod (operator) ++To create a modulo form during numeric entry, press the shift-@kbd{M} ++key to enter the word @samp{mod}. As a special convenience, pressing ++shift-@kbd{M} a second time automatically enters the value of @expr{M} ++that was most recently used before. During algebraic entry, either ++type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}). ++Once again, pressing this a second time enters the current modulo. ++ ++Modulo forms are not to be confused with the modulo operator @samp{%}. ++The expression @samp{27 % 10} means to compute 27 modulo 10 to produce ++the result 7. Further computations treat this 7 as just a regular integer. ++The expression @samp{27 mod 10} produces the result @samp{7 mod 10}; ++further computations with this value are again reduced modulo 10 so that ++the result always lies in the desired range. ++ ++When two modulo forms with identical @expr{M}'s are added or multiplied, ++the Calculator simply adds or multiplies the values, then reduces modulo ++@expr{M}. If one argument is a modulo form and the other a plain number, ++the plain number is treated like a compatible modulo form. It is also ++possible to raise modulo forms to powers; the result is the value raised ++to the power, then reduced modulo @expr{M}. (When all values involved ++are integers, this calculation is done much more efficiently than ++actually computing the power and then reducing.) ++ ++@cindex Modulo division ++Two modulo forms `@var{a} @tfn{mod} @var{M}' and `@var{b} @tfn{mod} @var{M}' ++can be divided if @expr{a}, @expr{b}, and @expr{M} are all ++integers. The result is the modulo form which, when multiplied by ++`@var{b} @tfn{mod} @var{M}', produces `@var{a} @tfn{mod} @var{M}'. If ++there is no solution to this equation (which can happen only when ++@expr{M} is non-prime), or if any of the arguments are non-integers, the ++division is left in symbolic form. Other operations, such as square ++roots, are not yet supported for modulo forms. (Note that, although ++@w{`@tfn{(}@var{a} @tfn{mod} @var{M}@tfn{)^.5}'} will compute a ``modulo square root'' ++in the sense of reducing ++@texline @math{\sqrt a} ++@infoline @expr{sqrt(a)} ++modulo @expr{M}, this is not a useful definition from the ++number-theoretical point of view.) ++ ++It is possible to mix HMS forms and modulo forms. For example, an ++HMS form modulo 24 could be used to manipulate clock times; an HMS ++form modulo 360 would be suitable for angles. Making the modulo @expr{M} ++also be an HMS form eliminates troubles that would arise if the angular ++mode were inadvertently set to Radians, in which case ++@w{@samp{2@@ 0' 0" mod 24}} would be interpreted as two degrees modulo ++24 radians! ++ ++Modulo forms cannot have variables or formulas for components. If you ++enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus ++to each of the coefficients: @samp{(1 mod 5) x + (2 mod 5)}. ++ ++You can use @kbd{v p} and @kbd{%} to modify modulo forms. ++@xref{Packing and Unpacking}. @xref{Basic Arithmetic}. ++ ++@ignore ++@starindex ++@end ignore ++@tindex makemod ++The algebraic function @samp{makemod(a, m)} builds the modulo form ++@w{@samp{a mod m}}. ++ ++@node Error Forms, Interval Forms, Modulo Forms, Data Types ++@section Error Forms ++ ++@noindent ++@cindex Error forms ++@cindex Standard deviations ++An @dfn{error form} is a number with an associated standard ++deviation, as in @samp{2.3 +/- 0.12}. The notation ++@texline `@var{x} @tfn{+/-} @math{\sigma}' ++@infoline `@var{x} @tfn{+/-} sigma' ++stands for an uncertain value which follows ++a normal or Gaussian distribution of mean @expr{x} and standard ++deviation or ``error'' ++@texline @math{\sigma}. ++@infoline @expr{sigma}. ++Both the mean and the error can be either numbers or ++formulas. Generally these are real numbers but the mean may also be ++complex. If the error is negative or complex, it is changed to its ++absolute value. An error form with zero error is converted to a ++regular number by the Calculator. ++ ++All arithmetic and transcendental functions accept error forms as input. ++Operations on the mean-value part work just like operations on regular ++numbers. The error part for any function @expr{f(x)} (such as ++@texline @math{\sin x} ++@infoline @expr{sin(x)}) ++is defined by the error of @expr{x} times the derivative of @expr{f} ++evaluated at the mean value of @expr{x}. For a two-argument function ++@expr{f(x,y)} (such as addition) the error is the square root of the sum ++of the squares of the errors due to @expr{x} and @expr{y}. ++@tex ++$$ \eqalign{ ++ f(x \hbox{\code{ +/- }} \sigma) ++ &= f(x) \hbox{\code{ +/- }} \sigma \left| {df(x) \over dx} \right| \cr ++ f(x \hbox{\code{ +/- }} \sigma_x, y \hbox{\code{ +/- }} \sigma_y) ++ &= f(x,y) \hbox{\code{ +/- }} ++ \sqrt{\left(\sigma_x \left| {\partial f(x,y) \over \partial x} ++ \right| \right)^2 ++ +\left(\sigma_y \left| {\partial f(x,y) \over \partial y} ++ \right| \right)^2 } \cr ++} $$ ++@end tex ++Note that this ++definition assumes the errors in @expr{x} and @expr{y} are uncorrelated. ++A side effect of this definition is that @samp{(2 +/- 1) * (2 +/- 1)} ++is not the same as @samp{(2 +/- 1)^2}; the former represents the product ++of two independent values which happen to have the same probability ++distributions, and the latter is the product of one random value with itself. ++The former will produce an answer with less error, since on the average ++the two independent errors can be expected to cancel out. ++ ++Consult a good text on error analysis for a discussion of the proper use ++of standard deviations. Actual errors often are neither Gaussian-distributed ++nor uncorrelated, and the above formulas are valid only when errors ++are small. As an example, the error arising from ++@texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}' ++@infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}' ++is ++@texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. ++@infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. ++When @expr{x} is close to zero, ++@texline @math{\cos x} ++@infoline @expr{cos(x)} ++is close to one so the error in the sine is close to ++@texline @math{\sigma}; ++@infoline @expr{sigma}; ++this makes sense, since ++@texline @math{\sin x} ++@infoline @expr{sin(x)} ++is approximately @expr{x} near zero, so a given error in @expr{x} will ++produce about the same error in the sine. Likewise, near 90 degrees ++@texline @math{\cos x} ++@infoline @expr{cos(x)} ++is nearly zero and so the computed error is ++small: The sine curve is nearly flat in that region, so an error in @expr{x} ++has relatively little effect on the value of ++@texline @math{\sin x}. ++@infoline @expr{sin(x)}. ++However, consider @samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so ++Calc will report zero error! We get an obviously wrong result because ++we have violated the small-error approximation underlying the error ++analysis. If the error in @expr{x} had been small, the error in ++@texline @math{\sin x} ++@infoline @expr{sin(x)} ++would indeed have been negligible. ++ ++@ignore ++@mindex p ++@end ignore ++@kindex p (error forms) ++@tindex +/- ++To enter an error form during regular numeric entry, use the @kbd{p} ++(``plus-or-minus'') key to type the @samp{+/-} symbol. (If you try actually ++typing @samp{+/-} the @kbd{+} key will be interpreted as the Calculator's ++@kbd{+} command!) Within an algebraic formula, you can press @kbd{M-+} to ++type the @samp{+/-} symbol, or type it out by hand. ++ ++Error forms and complex numbers can be mixed; the formulas shown above ++are used for complex numbers, too; note that if the error part evaluates ++to a complex number its absolute value (or the square root of the sum of ++the squares of the absolute values of the two error contributions) is ++used. Mathematically, this corresponds to a radially symmetric Gaussian ++distribution of numbers on the complex plane. However, note that Calc ++considers an error form with real components to represent a real number, ++not a complex distribution around a real mean. ++ ++Error forms may also be composed of HMS forms. For best results, both ++the mean and the error should be HMS forms if either one is. ++ ++@ignore ++@starindex ++@end ignore ++@tindex sdev ++The algebraic function @samp{sdev(a, b)} builds the error form @samp{a +/- b}. ++ ++@node Interval Forms, Incomplete Objects, Error Forms, Data Types ++@section Interval Forms ++ ++@noindent ++@cindex Interval forms ++An @dfn{interval} is a subset of consecutive real numbers. For example, ++the interval @samp{[2 ..@: 4]} represents all the numbers from 2 to 4, ++inclusive. If you multiply it by the interval @samp{[0.5 ..@: 2]} you ++obtain @samp{[1 ..@: 8]}. This calculation represents the fact that if ++you multiply some number in the range @samp{[2 ..@: 4]} by some other ++number in the range @samp{[0.5 ..@: 2]}, your result will lie in the range ++from 1 to 8. Interval arithmetic is used to get a worst-case estimate ++of the possible range of values a computation will produce, given the ++set of possible values of the input. ++ ++@ifnottex ++Calc supports several varieties of intervals, including @dfn{closed} ++intervals of the type shown above, @dfn{open} intervals such as ++@samp{(2 ..@: 4)}, which represents the range of numbers from 2 to 4 ++@emph{exclusive}, and @dfn{semi-open} intervals in which one end ++uses a round parenthesis and the other a square bracket. In mathematical ++terms, ++@samp{[2 ..@: 4]} means @expr{2 <= x <= 4}, whereas ++@samp{[2 ..@: 4)} represents @expr{2 <= x < 4}, ++@samp{(2 ..@: 4]} represents @expr{2 < x <= 4}, and ++@samp{(2 ..@: 4)} represents @expr{2 < x < 4}. ++@end ifnottex ++@tex ++Calc supports several varieties of intervals, including \dfn{closed} ++intervals of the type shown above, \dfn{open} intervals such as ++\samp{(2 ..\: 4)}, which represents the range of numbers from 2 to 4 ++\emph{exclusive}, and \dfn{semi-open} intervals in which one end ++uses a round parenthesis and the other a square bracket. In mathematical ++terms, ++$$ \eqalign{ ++ [2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 \le x \le 4 \cr ++ [2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 \le x < 4 \cr ++ (2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 < x \le 4 \cr ++ (2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 < x < 4 \cr ++} $$ ++@end tex ++ ++The lower and upper limits of an interval must be either real numbers ++(or HMS or date forms), or symbolic expressions which are assumed to be ++real-valued, or @samp{-inf} and @samp{inf}. In general the lower limit ++must be less than the upper limit. A closed interval containing only ++one value, @samp{[3 ..@: 3]}, is converted to a plain number (3) ++automatically. An interval containing no values at all (such as ++@samp{[3 ..@: 2]} or @samp{[2 ..@: 2)}) can be represented but is not ++guaranteed to behave well when used in arithmetic. Note that the ++interval @samp{[3 .. inf)} represents all real numbers greater than ++or equal to 3, and @samp{(-inf .. inf)} represents all real numbers. ++In fact, @samp{[-inf .. inf]} represents all real numbers including ++the real infinities. ++ ++Intervals are entered in the notation shown here, either as algebraic ++formulas, or using incomplete forms. (@xref{Incomplete Objects}.) ++In algebraic formulas, multiple periods in a row are collected from ++left to right, so that @samp{1...1e2} is interpreted as @samp{1.0 ..@: 1e2} ++rather than @samp{1 ..@: 0.1e2}. Add spaces or zeros if you want to ++get the other interpretation. If you omit the lower or upper limit, ++a default of @samp{-inf} or @samp{inf} (respectively) is furnished. ++ ++Infinite mode also affects operations on intervals ++(@pxref{Infinities}). Calc will always introduce an open infinity, ++as in @samp{1 / (0 .. 2] = [0.5 .. inf)}. But closed infinities, ++@w{@samp{1 / [0 .. 2] = [0.5 .. inf]}}, arise only in Infinite mode; ++otherwise they are left unevaluated. Note that the ``direction'' of ++a zero is not an issue in this case since the zero is always assumed ++to be continuous with the rest of the interval. For intervals that ++contain zero inside them Calc is forced to give the result, ++@samp{1 / (-2 .. 2) = [-inf .. inf]}. ++ ++While it may seem that intervals and error forms are similar, they are ++based on entirely different concepts of inexact quantities. An error ++form ++@texline `@var{x} @tfn{+/-} @math{\sigma}' ++@infoline `@var{x} @tfn{+/-} @var{sigma}' ++means a variable is random, and its value could ++be anything but is ``probably'' within one ++@texline @math{\sigma} ++@infoline @var{sigma} ++of the mean value @expr{x}. An interval ++`@tfn{[}@var{a} @tfn{..@:} @var{b}@tfn{]}' means a ++variable's value is unknown, but guaranteed to lie in the specified ++range. Error forms are statistical or ``average case'' approximations; ++interval arithmetic tends to produce ``worst case'' bounds on an ++answer. ++ ++Intervals may not contain complex numbers, but they may contain ++HMS forms or date forms. ++ ++@xref{Set Operations}, for commands that interpret interval forms ++as subsets of the set of real numbers. ++ ++@ignore ++@starindex ++@end ignore ++@tindex intv ++The algebraic function @samp{intv(n, a, b)} builds an interval form ++from @samp{a} to @samp{b}; @samp{n} is an integer code which must ++be 0 for @samp{(..)}, 1 for @samp{(..]}, 2 for @samp{[..)}, or ++3 for @samp{[..]}. ++ ++Please note that in fully rigorous interval arithmetic, care would be ++taken to make sure that the computation of the lower bound rounds toward ++minus infinity, while upper bound computations round toward plus ++infinity. Calc's arithmetic always uses a round-to-nearest mode, ++which means that roundoff errors could creep into an interval ++calculation to produce intervals slightly smaller than they ought to ++be. For example, entering @samp{[1..2]} and pressing @kbd{Q 2 ^} ++should yield the interval @samp{[1..2]} again, but in fact it yields the ++(slightly too small) interval @samp{[1..1.9999999]} due to roundoff ++error. ++ ++@node Incomplete Objects, Variables, Interval Forms, Data Types ++@section Incomplete Objects ++ ++@noindent ++@ignore ++@mindex [ ] ++@end ignore ++@kindex [ ++@ignore ++@mindex ( ) ++@end ignore ++@kindex ( ++@kindex , ++@ignore ++@mindex @null ++@end ignore ++@kindex ] ++@ignore ++@mindex @null ++@end ignore ++@kindex ) ++@cindex Incomplete vectors ++@cindex Incomplete complex numbers ++@cindex Incomplete interval forms ++When @kbd{(} or @kbd{[} is typed to begin entering a complex number or ++vector, respectively, the effect is to push an @dfn{incomplete} complex ++number or vector onto the stack. The @kbd{,} key adds the value(s) at ++the top of the stack onto the current incomplete object. The @kbd{)} ++and @kbd{]} keys ``close'' the incomplete object after adding any values ++on the top of the stack in front of the incomplete object. ++ ++As a result, the sequence of keystrokes @kbd{[ 2 , 3 @key{RET} 2 * , 9 ]} ++pushes the vector @samp{[2, 6, 9]} onto the stack. Likewise, @kbd{( 1 , 2 Q )} ++pushes the complex number @samp{(1, 1.414)} (approximately). ++ ++If several values lie on the stack in front of the incomplete object, ++all are collected and appended to the object. Thus the @kbd{,} key ++is redundant: @kbd{[ 2 @key{RET} 3 @key{RET} 2 * 9 ]}. Some people ++prefer the equivalent @key{SPC} key to @key{RET}. ++ ++As a special case, typing @kbd{,} immediately after @kbd{(}, @kbd{[}, or ++@kbd{,} adds a zero or duplicates the preceding value in the list being ++formed. Typing @key{DEL} during incomplete entry removes the last item ++from the list. ++ ++@kindex ; ++The @kbd{;} key is used in the same way as @kbd{,} to create polar complex ++numbers: @kbd{( 1 ; 2 )}. When entering a vector, @kbd{;} is useful for ++creating a matrix. In particular, @kbd{[ [ 1 , 2 ; 3 , 4 ; 5 , 6 ] ]} is ++equivalent to @kbd{[ [ 1 , 2 ] , [ 3 , 4 ] , [ 5 , 6 ] ]}. ++ ++@kindex .. ++@pindex calc-dots ++Incomplete entry is also used to enter intervals. For example, ++@kbd{[ 2 ..@: 4 )} enters a semi-open interval. Note that when you type ++the first period, it will be interpreted as a decimal point, but when ++you type a second period immediately afterward, it is re-interpreted as ++part of the interval symbol. Typing @kbd{..} corresponds to executing ++the @code{calc-dots} command. ++ ++If you find incomplete entry distracting, you may wish to enter vectors ++and complex numbers as algebraic formulas by pressing the apostrophe key. ++ ++@node Variables, Formulas, Incomplete Objects, Data Types ++@section Variables ++ ++@noindent ++@cindex Variables, in formulas ++A @dfn{variable} is somewhere between a storage register on a conventional ++calculator, and a variable in a programming language. (In fact, a Calc ++variable is really just an Emacs Lisp variable that contains a Calc number ++or formula.) A variable's name is normally composed of letters and digits. ++Calc also allows apostrophes and @code{#} signs in variable names. ++(The Calc variable @code{foo} corresponds to the Emacs Lisp variable ++@code{var-foo}, but unless you access the variable from within Emacs ++Lisp, you don't need to worry about it. Variable names in algebraic ++formulas implicitly have @samp{var-} prefixed to their names. The ++@samp{#} character in variable names used in algebraic formulas ++corresponds to a dash @samp{-} in the Lisp variable name. If the name ++contains any dashes, the prefix @samp{var-} is @emph{not} automatically ++added. Thus the two formulas @samp{foo + 1} and @samp{var#foo + 1} both ++refer to the same variable.) ++ ++In a command that takes a variable name, you can either type the full ++name of a variable, or type a single digit to use one of the special ++convenience variables @code{q0} through @code{q9}. For example, ++@kbd{3 s s 2} stores the number 3 in variable @code{q2}, and ++@w{@kbd{3 s s foo @key{RET}}} stores that number in variable ++@code{foo}. ++ ++To push a variable itself (as opposed to the variable's value) on the ++stack, enter its name as an algebraic expression using the apostrophe ++(@key{'}) key. ++ ++@kindex = ++@pindex calc-evaluate ++@cindex Evaluation of variables in a formula ++@cindex Variables, evaluation ++@cindex Formulas, evaluation ++The @kbd{=} (@code{calc-evaluate}) key ``evaluates'' a formula by ++replacing all variables in the formula which have been given values by a ++@code{calc-store} or @code{calc-let} command by their stored values. ++Other variables are left alone. Thus a variable that has not been ++stored acts like an abstract variable in algebra; a variable that has ++been stored acts more like a register in a traditional calculator. ++With a positive numeric prefix argument, @kbd{=} evaluates the top ++@var{n} stack entries; with a negative argument, @kbd{=} evaluates ++the @var{n}th stack entry. ++ ++@cindex @code{e} variable ++@cindex @code{pi} variable ++@cindex @code{i} variable ++@cindex @code{phi} variable ++@cindex @code{gamma} variable ++@vindex e ++@vindex pi ++@vindex i ++@vindex phi ++@vindex gamma ++A few variables are called @dfn{special constants}. Their names are ++@samp{e}, @samp{pi}, @samp{i}, @samp{phi}, and @samp{gamma}. ++(@xref{Scientific Functions}.) When they are evaluated with @kbd{=}, ++their values are calculated if necessary according to the current precision ++or complex polar mode. If you wish to use these symbols for other purposes, ++simply undefine or redefine them using @code{calc-store}. ++ ++The variables @samp{inf}, @samp{uinf}, and @samp{nan} stand for ++infinite or indeterminate values. It's best not to use them as ++regular variables, since Calc uses special algebraic rules when ++it manipulates them. Calc displays a warning message if you store ++a value into any of these special variables. ++ ++@xref{Store and Recall}, for a discussion of commands dealing with variables. ++ ++@node Formulas, , Variables, Data Types ++@section Formulas ++ ++@noindent ++@cindex Formulas ++@cindex Expressions ++@cindex Operators in formulas ++@cindex Precedence of operators ++When you press the apostrophe key you may enter any expression or formula ++in algebraic form. (Calc uses the terms ``expression'' and ``formula'' ++interchangeably.) An expression is built up of numbers, variable names, ++and function calls, combined with various arithmetic operators. ++Parentheses may ++be used to indicate grouping. Spaces are ignored within formulas, except ++that spaces are not permitted within variable names or numbers. ++Arithmetic operators, in order from highest to lowest precedence, and ++with their equivalent function names, are: ++ ++@samp{_} [@code{subscr}] (subscripts); ++ ++postfix @samp{%} [@code{percent}] (as in @samp{25% = 0.25}); ++ ++prefix @samp{!} [@code{lnot}] (logical ``not,'' as in @samp{!x}); ++ ++@samp{+/-} [@code{sdev}] (the standard deviation symbol) and ++@samp{mod} [@code{makemod}] (the symbol for modulo forms); ++ ++postfix @samp{!} [@code{fact}] (factorial, as in @samp{n!}) ++and postfix @samp{!!} [@code{dfact}] (double factorial); ++ ++@samp{^} [@code{pow}] (raised-to-the-power-of); ++ ++prefix @samp{+} and @samp{-} [@code{neg}] (as in @samp{-x}); ++ ++@samp{*} [@code{mul}]; ++ ++@samp{/} [@code{div}], @samp{%} [@code{mod}] (modulo), and ++@samp{\} [@code{idiv}] (integer division); ++ ++infix @samp{+} [@code{add}] and @samp{-} [@code{sub}] (as in @samp{x-y}); ++ ++@samp{|} [@code{vconcat}] (vector concatenation); ++ ++relations @samp{=} [@code{eq}], @samp{!=} [@code{neq}], @samp{<} [@code{lt}], ++@samp{>} [@code{gt}], @samp{<=} [@code{leq}], and @samp{>=} [@code{geq}]; ++ ++@samp{&&} [@code{land}] (logical ``and''); ++ ++@samp{||} [@code{lor}] (logical ``or''); ++ ++the C-style ``if'' operator @samp{a?b:c} [@code{if}]; ++ ++@samp{!!!} [@code{pnot}] (rewrite pattern ``not''); ++ ++@samp{&&&} [@code{pand}] (rewrite pattern ``and''); ++ ++@samp{|||} [@code{por}] (rewrite pattern ``or''); ++ ++@samp{:=} [@code{assign}] (for assignments and rewrite rules); ++ ++@samp{::} [@code{condition}] (rewrite pattern condition); ++ ++@samp{=>} [@code{evalto}]. ++ ++Note that, unlike in usual computer notation, multiplication binds more ++strongly than division: @samp{a*b/c*d} is equivalent to ++@texline @math{a b \over c d}. ++@infoline @expr{(a*b)/(c*d)}. ++ ++@cindex Multiplication, implicit ++@cindex Implicit multiplication ++The multiplication sign @samp{*} may be omitted in many cases. In particular, ++if the righthand side is a number, variable name, or parenthesized ++expression, the @samp{*} may be omitted. Implicit multiplication has the ++same precedence as the explicit @samp{*} operator. The one exception to ++the rule is that a variable name followed by a parenthesized expression, ++as in @samp{f(x)}, ++is interpreted as a function call, not an implicit @samp{*}. In many ++cases you must use a space if you omit the @samp{*}: @samp{2a} is the ++same as @samp{2*a}, and @samp{a b} is the same as @samp{a*b}, but @samp{ab} ++is a variable called @code{ab}, @emph{not} the product of @samp{a} and ++@samp{b}! Also note that @samp{f (x)} is still a function call. ++ ++@cindex Implicit comma in vectors ++The rules are slightly different for vectors written with square brackets. ++In vectors, the space character is interpreted (like the comma) as a ++separator of elements of the vector. Thus @w{@samp{[ 2a b+c d ]}} is ++equivalent to @samp{[2*a, b+c, d]}, whereas @samp{2a b+c d} is equivalent ++to @samp{2*a*b + c*d}. ++Note that spaces around the brackets, and around explicit commas, are ++ignored. To force spaces to be interpreted as multiplication you can ++enclose a formula in parentheses as in @samp{[(a b) 2(c d)]}, which is ++interpreted as @samp{[a*b, 2*c*d]}. An implicit comma is also inserted ++between @samp{][}, as in the matrix @samp{[[1 2][3 4]]}. ++ ++Vectors that contain commas (not embedded within nested parentheses or ++brackets) do not treat spaces specially: @samp{[a b, 2 c d]} is a vector ++of two elements. Also, if it would be an error to treat spaces as ++separators, but not otherwise, then Calc will ignore spaces: ++@w{@samp{[a - b]}} is a vector of one element, but @w{@samp{[a -b]}} is ++a vector of two elements. Finally, vectors entered with curly braces ++instead of square brackets do not give spaces any special treatment. ++When Calc displays a vector that does not contain any commas, it will ++insert parentheses if necessary to make the meaning clear: ++@w{@samp{[(a b)]}}. ++ ++The expression @samp{5%-2} is ambiguous; is this five-percent minus two, ++or five modulo minus-two? Calc always interprets the leftmost symbol as ++an infix operator preferentially (modulo, in this case), so you would ++need to write @samp{(5%)-2} to get the former interpretation. ++ ++@cindex Function call notation ++A function call is, e.g., @samp{sin(1+x)}. (The Calc algebraic function ++@code{foo} corresponds to the Emacs Lisp function @code{calcFunc-foo}, ++but unless you access the function from within Emacs Lisp, you don't ++need to worry about it.) Most mathematical Calculator commands like ++@code{calc-sin} have function equivalents like @code{sin}. ++If no Lisp function is defined for a function called by a formula, the ++call is left as it is during algebraic manipulation: @samp{f(x+y)} is ++left alone. Beware that many innocent-looking short names like @code{in} ++and @code{re} have predefined meanings which could surprise you; however, ++single letters or single letters followed by digits are always safe to ++use for your own function names. @xref{Function Index}. ++ ++In the documentation for particular commands, the notation @kbd{H S} ++(@code{calc-sinh}) [@code{sinh}] means that the key sequence @kbd{H S}, the ++command @kbd{M-x calc-sinh}, and the algebraic function @code{sinh(x)} all ++represent the same operation. ++ ++Commands that interpret (``parse'') text as algebraic formulas include ++algebraic entry (@kbd{'}), editing commands like @kbd{`} which parse ++the contents of the editing buffer when you finish, the @kbd{C-x * g} ++and @w{@kbd{C-x * r}} commands, the @kbd{C-y} command, the X window system ++``paste'' mouse operation, and Embedded mode. All of these operations ++use the same rules for parsing formulas; in particular, language modes ++(@pxref{Language Modes}) affect them all in the same way. ++ ++When you read a large amount of text into the Calculator (say a vector ++which represents a big set of rewrite rules; @pxref{Rewrite Rules}), ++you may wish to include comments in the text. Calc's formula parser ++ignores the symbol @samp{%%} and anything following it on a line: ++ ++@example ++[ a + b, %% the sum of "a" and "b" ++ c + d, ++ %% last line is coming up: ++ e + f ] ++@end example ++ ++@noindent ++This is parsed exactly the same as @samp{[ a + b, c + d, e + f ]}. ++ ++@xref{Syntax Tables}, for a way to create your own operators and other ++input notations. @xref{Compositions}, for a way to create new display ++formats. ++ ++@xref{Algebra}, for commands for manipulating formulas symbolically. ++ ++@node Stack and Trail, Mode Settings, Data Types, Top ++@chapter Stack and Trail Commands ++ ++@noindent ++This chapter describes the Calc commands for manipulating objects on the ++stack and in the trail buffer. (These commands operate on objects of any ++type, such as numbers, vectors, formulas, and incomplete objects.) ++ ++@menu ++* Stack Manipulation:: ++* Editing Stack Entries:: ++* Trail Commands:: ++* Keep Arguments:: ++@end menu ++ ++@node Stack Manipulation, Editing Stack Entries, Stack and Trail, Stack and Trail ++@section Stack Manipulation Commands ++ ++@noindent ++@kindex @key{RET} ++@kindex @key{SPC} ++@pindex calc-enter ++@cindex Duplicating stack entries ++To duplicate the top object on the stack, press @key{RET} or @key{SPC} ++(two equivalent keys for the @code{calc-enter} command). ++Given a positive numeric prefix argument, these commands duplicate ++several elements at the top of the stack. ++Given a negative argument, ++these commands duplicate the specified element of the stack. ++Given an argument of zero, they duplicate the entire stack. ++For example, with @samp{10 20 30} on the stack, ++@key{RET} creates @samp{10 20 30 30}, ++@kbd{C-u 2 @key{RET}} creates @samp{10 20 30 20 30}, ++@kbd{C-u - 2 @key{RET}} creates @samp{10 20 30 20}, and ++@kbd{C-u 0 @key{RET}} creates @samp{10 20 30 10 20 30}. ++ ++@kindex @key{LFD} ++@pindex calc-over ++The @key{LFD} (@code{calc-over}) command (on a key marked Line-Feed if you ++have it, else on @kbd{C-j}) is like @code{calc-enter} ++except that the sign of the numeric prefix argument is interpreted ++oppositely. Also, with no prefix argument the default argument is 2. ++Thus with @samp{10 20 30} on the stack, @key{LFD} and @kbd{C-u 2 @key{LFD}} ++are both equivalent to @kbd{C-u - 2 @key{RET}}, producing ++@samp{10 20 30 20}. ++ ++@kindex @key{DEL} ++@kindex C-d ++@pindex calc-pop ++@cindex Removing stack entries ++@cindex Deleting stack entries ++To remove the top element from the stack, press @key{DEL} (@code{calc-pop}). ++The @kbd{C-d} key is a synonym for @key{DEL}. ++(If the top element is an incomplete object with at least one element, the ++last element is removed from it.) Given a positive numeric prefix argument, ++several elements are removed. Given a negative argument, the specified ++element of the stack is deleted. Given an argument of zero, the entire ++stack is emptied. ++For example, with @samp{10 20 30} on the stack, ++@key{DEL} leaves @samp{10 20}, ++@kbd{C-u 2 @key{DEL}} leaves @samp{10}, ++@kbd{C-u - 2 @key{DEL}} leaves @samp{10 30}, and ++@kbd{C-u 0 @key{DEL}} leaves an empty stack. ++ ++@kindex M-@key{DEL} ++@pindex calc-pop-above ++The @kbd{M-@key{DEL}} (@code{calc-pop-above}) command is to @key{DEL} what ++@key{LFD} is to @key{RET}: It interprets the sign of the numeric ++prefix argument in the opposite way, and the default argument is 2. ++Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element, ++leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes ++the third stack element. ++ ++@kindex @key{TAB} ++@pindex calc-roll-down ++To exchange the top two elements of the stack, press @key{TAB} ++(@code{calc-roll-down}). Given a positive numeric prefix argument, the ++specified number of elements at the top of the stack are rotated downward. ++Given a negative argument, the entire stack is rotated downward the specified ++number of times. Given an argument of zero, the entire stack is reversed ++top-for-bottom. ++For example, with @samp{10 20 30 40 50} on the stack, ++@key{TAB} creates @samp{10 20 30 50 40}, ++@kbd{C-u 3 @key{TAB}} creates @samp{10 20 50 30 40}, ++@kbd{C-u - 2 @key{TAB}} creates @samp{40 50 10 20 30}, and ++@kbd{C-u 0 @key{TAB}} creates @samp{50 40 30 20 10}. ++ ++@kindex M-@key{TAB} ++@pindex calc-roll-up ++The command @kbd{M-@key{TAB}} (@code{calc-roll-up}) is analogous to @key{TAB} ++except that it rotates upward instead of downward. Also, the default ++with no prefix argument is to rotate the top 3 elements. ++For example, with @samp{10 20 30 40 50} on the stack, ++@kbd{M-@key{TAB}} creates @samp{10 20 40 50 30}, ++@kbd{C-u 4 M-@key{TAB}} creates @samp{10 30 40 50 20}, ++@kbd{C-u - 2 M-@key{TAB}} creates @samp{30 40 50 10 20}, and ++@kbd{C-u 0 M-@key{TAB}} creates @samp{50 40 30 20 10}. ++ ++A good way to view the operation of @key{TAB} and @kbd{M-@key{TAB}} is in ++terms of moving a particular element to a new position in the stack. ++With a positive argument @var{n}, @key{TAB} moves the top stack ++element down to level @var{n}, making room for it by pulling all the ++intervening stack elements toward the top. @kbd{M-@key{TAB}} moves the ++element at level @var{n} up to the top. (Compare with @key{LFD}, ++which copies instead of moving the element in level @var{n}.) ++ ++With a negative argument @mathit{-@var{n}}, @key{TAB} rotates the stack ++to move the object in level @var{n} to the deepest place in the ++stack, and the object in level @mathit{@var{n}+1} to the top. @kbd{M-@key{TAB}} ++rotates the deepest stack element to be in level @mathit{n}, also ++putting the top stack element in level @mathit{@var{n}+1}. ++ ++@xref{Selecting Subformulas}, for a way to apply these commands to ++any portion of a vector or formula on the stack. ++ ++@node Editing Stack Entries, Trail Commands, Stack Manipulation, Stack and Trail ++@section Editing Stack Entries ++ ++@noindent ++@kindex ` ++@pindex calc-edit ++@pindex calc-edit-finish ++@cindex Editing the stack with Emacs ++The @kbd{`} (@code{calc-edit}) command creates a temporary buffer ++(@samp{*Calc Edit*}) for editing the top-of-stack value using regular ++Emacs commands. Note that @kbd{`} is a backquote, not a quote. With a ++numeric prefix argument, it edits the specified number of stack entries ++at once. (An argument of zero edits the entire stack; a negative ++argument edits one specific stack entry.) ++ ++When you are done editing, press @kbd{C-c C-c} to finish and return ++to Calc. The @key{RET} and @key{LFD} keys also work to finish most ++sorts of editing, though in some cases Calc leaves @key{RET} with its ++usual meaning (``insert a newline'') if it's a situation where you ++might want to insert new lines into the editing buffer. ++ ++When you finish editing, the Calculator parses the lines of text in ++the @samp{*Calc Edit*} buffer as numbers or formulas, replaces the ++original stack elements in the original buffer with these new values, ++then kills the @samp{*Calc Edit*} buffer. The original Calculator buffer ++continues to exist during editing, but for best results you should be ++careful not to change it until you have finished the edit. You can ++also cancel the edit by killing the buffer with @kbd{C-x k}. ++ ++The formula is normally reevaluated as it is put onto the stack. ++For example, editing @samp{a + 2} to @samp{3 + 2} and pressing ++@kbd{C-c C-c} will push 5 on the stack. If you use @key{LFD} to ++finish, Calc will put the result on the stack without evaluating it. ++ ++If you give a prefix argument to @kbd{C-c C-c}, ++Calc will not kill the @samp{*Calc Edit*} buffer. You can switch ++back to that buffer and continue editing if you wish. However, you ++should understand that if you initiated the edit with @kbd{`}, the ++@kbd{C-c C-c} operation will be programmed to replace the top of the ++stack with the new edited value, and it will do this even if you have ++rearranged the stack in the meanwhile. This is not so much of a problem ++with other editing commands, though, such as @kbd{s e} ++(@code{calc-edit-variable}; @pxref{Operations on Variables}). ++ ++If the @code{calc-edit} command involves more than one stack entry, ++each line of the @samp{*Calc Edit*} buffer is interpreted as a ++separate formula. Otherwise, the entire buffer is interpreted as ++one formula, with line breaks ignored. (You can use @kbd{C-o} or ++@kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.) ++ ++The @kbd{`} key also works during numeric or algebraic entry. The ++text entered so far is moved to the @code{*Calc Edit*} buffer for ++more extensive editing than is convenient in the minibuffer. ++ ++@node Trail Commands, Keep Arguments, Editing Stack Entries, Stack and Trail ++@section Trail Commands ++ ++@noindent ++@cindex Trail buffer ++The commands for manipulating the Calc Trail buffer are two-key sequences ++beginning with the @kbd{t} prefix. ++ ++@kindex t d ++@pindex calc-trail-display ++The @kbd{t d} (@code{calc-trail-display}) command turns display of the ++trail on and off. Normally the trail display is toggled on if it was off, ++off if it was on. With a numeric prefix of zero, this command always ++turns the trail off; with a prefix of one, it always turns the trail on. ++The other trail-manipulation commands described here automatically turn ++the trail on. Note that when the trail is off values are still recorded ++there; they are simply not displayed. To set Emacs to turn the trail ++off by default, type @kbd{t d} and then save the mode settings with ++@kbd{m m} (@code{calc-save-modes}). ++ ++@kindex t i ++@pindex calc-trail-in ++@kindex t o ++@pindex calc-trail-out ++The @kbd{t i} (@code{calc-trail-in}) and @kbd{t o} ++(@code{calc-trail-out}) commands switch the cursor into and out of the ++Calc Trail window. In practice they are rarely used, since the commands ++shown below are a more convenient way to move around in the ++trail, and they work ``by remote control'' when the cursor is still ++in the Calculator window. ++ ++@cindex Trail pointer ++There is a @dfn{trail pointer} which selects some entry of the trail at ++any given time. The trail pointer looks like a @samp{>} symbol right ++before the selected number. The following commands operate on the ++trail pointer in various ways. ++ ++@kindex t y ++@pindex calc-trail-yank ++@cindex Retrieving previous results ++The @kbd{t y} (@code{calc-trail-yank}) command reads the selected value in ++the trail and pushes it onto the Calculator stack. It allows you to ++re-use any previously computed value without retyping. With a numeric ++prefix argument @var{n}, it yanks the value @var{n} lines above the current ++trail pointer. ++ ++@kindex t < ++@pindex calc-trail-scroll-left ++@kindex t > ++@pindex calc-trail-scroll-right ++The @kbd{t <} (@code{calc-trail-scroll-left}) and @kbd{t >} ++(@code{calc-trail-scroll-right}) commands horizontally scroll the trail ++window left or right by one half of its width. ++ ++@kindex t n ++@pindex calc-trail-next ++@kindex t p ++@pindex calc-trail-previous ++@kindex t f ++@pindex calc-trail-forward ++@kindex t b ++@pindex calc-trail-backward ++The @kbd{t n} (@code{calc-trail-next}) and @kbd{t p} ++(@code{calc-trail-previous)} commands move the trail pointer down or up ++one line. The @kbd{t f} (@code{calc-trail-forward}) and @kbd{t b} ++(@code{calc-trail-backward}) commands move the trail pointer down or up ++one screenful at a time. All of these commands accept numeric prefix ++arguments to move several lines or screenfuls at a time. ++ ++@kindex t [ ++@pindex calc-trail-first ++@kindex t ] ++@pindex calc-trail-last ++@kindex t h ++@pindex calc-trail-here ++The @kbd{t [} (@code{calc-trail-first}) and @kbd{t ]} ++(@code{calc-trail-last}) commands move the trail pointer to the first or ++last line of the trail. The @kbd{t h} (@code{calc-trail-here}) command ++moves the trail pointer to the cursor position; unlike the other trail ++commands, @kbd{t h} works only when Calc Trail is the selected window. ++ ++@kindex t s ++@pindex calc-trail-isearch-forward ++@kindex t r ++@pindex calc-trail-isearch-backward ++@ifnottex ++The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} ++(@code{calc-trail-isearch-backward}) commands perform an incremental ++search forward or backward through the trail. You can press @key{RET} ++to terminate the search; the trail pointer moves to the current line. ++If you cancel the search with @kbd{C-g}, the trail pointer stays where ++it was when the search began. ++@end ifnottex ++@tex ++The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} ++(@code{calc-trail-isearch-backward}) com\-mands perform an incremental ++search forward or backward through the trail. You can press @key{RET} ++to terminate the search; the trail pointer moves to the current line. ++If you cancel the search with @kbd{C-g}, the trail pointer stays where ++it was when the search began. ++@end tex ++ ++@kindex t m ++@pindex calc-trail-marker ++The @kbd{t m} (@code{calc-trail-marker}) command allows you to enter a ++line of text of your own choosing into the trail. The text is inserted ++after the line containing the trail pointer; this usually means it is ++added to the end of the trail. Trail markers are useful mainly as the ++targets for later incremental searches in the trail. ++ ++@kindex t k ++@pindex calc-trail-kill ++The @kbd{t k} (@code{calc-trail-kill}) command removes the selected line ++from the trail. The line is saved in the Emacs kill ring suitable for ++yanking into another buffer, but it is not easy to yank the text back ++into the trail buffer. With a numeric prefix argument, this command ++kills the @var{n} lines below or above the selected one. ++ ++The @kbd{t .} (@code{calc-full-trail-vectors}) command is described ++elsewhere; @pxref{Vector and Matrix Formats}. ++ ++@node Keep Arguments, , Trail Commands, Stack and Trail ++@section Keep Arguments ++ ++@noindent ++@kindex K ++@pindex calc-keep-args ++The @kbd{K} (@code{calc-keep-args}) command acts like a prefix for ++the following command. It prevents that command from removing its ++arguments from the stack. For example, after @kbd{2 @key{RET} 3 +}, ++the stack contains the sole number 5, but after @kbd{2 @key{RET} 3 K +}, ++the stack contains the arguments and the result: @samp{2 3 5}. ++ ++With the exception of keyboard macros, this works for all commands that ++take arguments off the stack. (To avoid potentially unpleasant behavior, ++a @kbd{K} prefix before a keyboard macro will be ignored. A @kbd{K} ++prefix called @emph{within} the keyboard macro will still take effect.) ++As another example, @kbd{K a s} simplifies a formula, pushing the ++simplified version of the formula onto the stack after the original ++formula (rather than replacing the original formula). Note that you ++could get the same effect by typing @kbd{@key{RET} a s}, copying the ++formula and then simplifying the copy. One difference is that for a very ++large formula the time taken to format the intermediate copy in ++@kbd{@key{RET} a s} could be noticeable; @kbd{K a s} would avoid this ++extra work. ++ ++Even stack manipulation commands are affected. @key{TAB} works by ++popping two values and pushing them back in the opposite order, ++so @kbd{2 @key{RET} 3 K @key{TAB}} produces @samp{2 3 3 2}. ++ ++A few Calc commands provide other ways of doing the same thing. ++For example, @kbd{' sin($)} replaces the number on the stack with ++its sine using algebraic entry; to push the sine and keep the ++original argument you could use either @kbd{' sin($1)} or ++@kbd{K ' sin($)}. @xref{Algebraic Entry}. Also, the @kbd{s s} ++command is effectively the same as @kbd{K s t}. @xref{Storing Variables}. ++ ++If you execute a command and then decide you really wanted to keep ++the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}). ++This command pushes the last arguments that were popped by any command ++onto the stack. Note that the order of things on the stack will be ++different than with @kbd{K}: @kbd{2 @key{RET} 3 + M-@key{RET}} leaves ++@samp{5 2 3} on the stack instead of @samp{2 3 5}. @xref{Undo}. ++ ++@node Mode Settings, Arithmetic, Stack and Trail, Top ++@chapter Mode Settings ++ ++@noindent ++This chapter describes commands that set modes in the Calculator. ++They do not affect the contents of the stack, although they may change ++the @emph{appearance} or @emph{interpretation} of the stack's contents. ++ ++@menu ++* General Mode Commands:: ++* Precision:: ++* Inverse and Hyperbolic:: ++* Calculation Modes:: ++* Simplification Modes:: ++* Declarations:: ++* Display Modes:: ++* Language Modes:: ++* Modes Variable:: ++* Calc Mode Line:: ++@end menu ++ ++@node General Mode Commands, Precision, Mode Settings, Mode Settings ++@section General Mode Commands ++ ++@noindent ++@kindex m m ++@pindex calc-save-modes ++@cindex Continuous memory ++@cindex Saving mode settings ++@cindex Permanent mode settings ++@cindex Calc init file, mode settings ++You can save all of the current mode settings in your Calc init file ++(the file given by the variable @code{calc-settings-file}, typically ++@file{~/.calc.el}) with the @kbd{m m} (@code{calc-save-modes}) command. ++This will cause Emacs to reestablish these modes each time it starts up. ++The modes saved in the file include everything controlled by the @kbd{m} ++and @kbd{d} prefix keys, the current precision and binary word size, ++whether or not the trail is displayed, the current height of the Calc ++window, and more. The current interface (used when you type @kbd{C-x * *}) ++is also saved. If there were already saved mode settings in the ++file, they are replaced. Otherwise, the new mode information is ++appended to the end of the file. ++ ++@kindex m R ++@pindex calc-mode-record-mode ++The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to ++record all the mode settings (as if by pressing @kbd{m m}) every ++time a mode setting changes. If the modes are saved this way, then this ++``automatic mode recording'' mode is also saved. ++Type @kbd{m R} again to disable this method of recording the mode ++settings. To turn it off permanently, the @kbd{m m} command will also be ++necessary. (If Embedded mode is enabled, other options for recording ++the modes are available; @pxref{Mode Settings in Embedded Mode}.) ++ ++@kindex m F ++@pindex calc-settings-file-name ++The @kbd{m F} (@code{calc-settings-file-name}) command allows you to ++choose a different file than the current value of @code{calc-settings-file} ++for @kbd{m m}, @kbd{Z P}, and similar commands to save permanent information. ++You are prompted for a file name. All Calc modes are then reset to ++their default values, then settings from the file you named are loaded ++if this file exists, and this file becomes the one that Calc will ++use in the future for commands like @kbd{m m}. The default settings ++file name is @file{~/.calc.el}. You can see the current file name by ++giving a blank response to the @kbd{m F} prompt. See also the ++discussion of the @code{calc-settings-file} variable; @pxref{Customizing Calc}. ++ ++If the file name you give is your user init file (typically ++@file{~/.emacs}), @kbd{m F} will not automatically load the new file. This ++is because your user init file may contain other things you don't want ++to reread. You can give ++a numeric prefix argument of 1 to @kbd{m F} to force it to read the ++file no matter what. Conversely, an argument of @mathit{-1} tells ++@kbd{m F} @emph{not} to read the new file. An argument of 2 or @mathit{-2} ++tells @kbd{m F} not to reset the modes to their defaults beforehand, ++which is useful if you intend your new file to have a variant of the ++modes present in the file you were using before. ++ ++@kindex m x ++@pindex calc-always-load-extensions ++The @kbd{m x} (@code{calc-always-load-extensions}) command enables a mode ++in which the first use of Calc loads the entire program, including all ++extensions modules. Otherwise, the extensions modules will not be loaded ++until the various advanced Calc features are used. Since this mode only ++has effect when Calc is first loaded, @kbd{m x} is usually followed by ++@kbd{m m} to make the mode-setting permanent. To load all of Calc just ++once, rather than always in the future, you can press @kbd{C-x * L}. ++ ++@kindex m S ++@pindex calc-shift-prefix ++The @kbd{m S} (@code{calc-shift-prefix}) command enables a mode in which ++all of Calc's letter prefix keys may be typed shifted as well as unshifted. ++If you are typing, say, @kbd{a S} (@code{calc-solve-for}) quite often ++you might find it easier to turn this mode on so that you can type ++@kbd{A S} instead. When this mode is enabled, the commands that used to ++be on those single shifted letters (e.g., @kbd{A} (@code{calc-abs})) can ++now be invoked by pressing the shifted letter twice: @kbd{A A}. Note ++that the @kbd{v} prefix key always works both shifted and unshifted, and ++the @kbd{z} and @kbd{Z} prefix keys are always distinct. Also, the @kbd{h} ++prefix is not affected by this mode. Press @kbd{m S} again to disable ++shifted-prefix mode. ++ ++@node Precision, Inverse and Hyperbolic, General Mode Commands, Mode Settings ++@section Precision ++ ++@noindent ++@kindex p ++@pindex calc-precision ++@cindex Precision of calculations ++The @kbd{p} (@code{calc-precision}) command controls the precision to ++which floating-point calculations are carried. The precision must be ++at least 3 digits and may be arbitrarily high, within the limits of ++memory and time. This affects only floats: Integer and rational ++calculations are always carried out with as many digits as necessary. ++ ++The @kbd{p} key prompts for the current precision. If you wish you ++can instead give the precision as a numeric prefix argument. ++ ++Many internal calculations are carried to one or two digits higher ++precision than normal. Results are rounded down afterward to the ++current precision. Unless a special display mode has been selected, ++floats are always displayed with their full stored precision, i.e., ++what you see is what you get. Reducing the current precision does not ++round values already on the stack, but those values will be rounded ++down before being used in any calculation. The @kbd{c 0} through ++@kbd{c 9} commands (@pxref{Conversions}) can be used to round an ++existing value to a new precision. ++ ++@cindex Accuracy of calculations ++It is important to distinguish the concepts of @dfn{precision} and ++@dfn{accuracy}. In the normal usage of these words, the number ++123.4567 has a precision of 7 digits but an accuracy of 4 digits. ++The precision is the total number of digits not counting leading ++or trailing zeros (regardless of the position of the decimal point). ++The accuracy is simply the number of digits after the decimal point ++(again not counting trailing zeros). In Calc you control the precision, ++not the accuracy of computations. If you were to set the accuracy ++instead, then calculations like @samp{exp(100)} would generate many ++more digits than you would typically need, while @samp{exp(-100)} would ++probably round to zero! In Calc, both these computations give you ++exactly 12 (or the requested number of) significant digits. ++ ++The only Calc features that deal with accuracy instead of precision ++are fixed-point display mode for floats (@kbd{d f}; @pxref{Float Formats}), ++and the rounding functions like @code{floor} and @code{round} ++(@pxref{Integer Truncation}). Also, @kbd{c 0} through @kbd{c 9} ++deal with both precision and accuracy depending on the magnitudes ++of the numbers involved. ++ ++If you need to work with a particular fixed accuracy (say, dollars and ++cents with two digits after the decimal point), one solution is to work ++with integers and an ``implied'' decimal point. For example, $8.99 ++divided by 6 would be entered @kbd{899 @key{RET} 6 /}, yielding 149.833 ++(actually $1.49833 with our implied decimal point); pressing @kbd{R} ++would round this to 150 cents, i.e., $1.50. ++ ++@xref{Floats}, for still more on floating-point precision and related ++issues. ++ ++@node Inverse and Hyperbolic, Calculation Modes, Precision, Mode Settings ++@section Inverse and Hyperbolic Flags ++ ++@noindent ++@kindex I ++@pindex calc-inverse ++There is no single-key equivalent to the @code{calc-arcsin} function. ++Instead, you must first press @kbd{I} (@code{calc-inverse}) to set ++the @dfn{Inverse Flag}, then press @kbd{S} (@code{calc-sin}). ++The @kbd{I} key actually toggles the Inverse Flag. When this flag ++is set, the word @samp{Inv} appears in the mode line. ++ ++@kindex H ++@pindex calc-hyperbolic ++Likewise, the @kbd{H} key (@code{calc-hyperbolic}) sets or clears the ++Hyperbolic Flag, which transforms @code{calc-sin} into @code{calc-sinh}. ++If both of these flags are set at once, the effect will be ++@code{calc-arcsinh}. (The Hyperbolic flag is also used by some ++non-trigonometric commands; for example @kbd{H L} computes a base-10, ++instead of base-@mathit{e}, logarithm.) ++ ++Command names like @code{calc-arcsin} are provided for completeness, and ++may be executed with @kbd{x} or @kbd{M-x}. Their effect is simply to ++toggle the Inverse and/or Hyperbolic flags and then execute the ++corresponding base command (@code{calc-sin} in this case). ++ ++The Inverse and Hyperbolic flags apply only to the next Calculator ++command, after which they are automatically cleared. (They are also ++cleared if the next keystroke is not a Calc command.) Digits you ++type after @kbd{I} or @kbd{H} (or @kbd{K}) are treated as prefix ++arguments for the next command, not as numeric entries. The same ++is true of @kbd{C-u}, but not of the minus sign (@kbd{K -} means to ++subtract and keep arguments). ++ ++The third Calc prefix flag, @kbd{K} (keep-arguments), is discussed ++elsewhere. @xref{Keep Arguments}. ++ ++@node Calculation Modes, Simplification Modes, Inverse and Hyperbolic, Mode Settings ++@section Calculation Modes ++ ++@noindent ++The commands in this section are two-key sequences beginning with ++the @kbd{m} prefix. (That's the letter @kbd{m}, not the @key{META} key.) ++The @samp{m a} (@code{calc-algebraic-mode}) command is described elsewhere ++(@pxref{Algebraic Entry}). ++ ++@menu ++* Angular Modes:: ++* Polar Mode:: ++* Fraction Mode:: ++* Infinite Mode:: ++* Symbolic Mode:: ++* Matrix Mode:: ++* Automatic Recomputation:: ++* Working Message:: ++@end menu ++ ++@node Angular Modes, Polar Mode, Calculation Modes, Calculation Modes ++@subsection Angular Modes ++ ++@noindent ++@cindex Angular mode ++The Calculator supports three notations for angles: radians, degrees, ++and degrees-minutes-seconds. When a number is presented to a function ++like @code{sin} that requires an angle, the current angular mode is ++used to interpret the number as either radians or degrees. If an HMS ++form is presented to @code{sin}, it is always interpreted as ++degrees-minutes-seconds. ++ ++Functions that compute angles produce a number in radians, a number in ++degrees, or an HMS form depending on the current angular mode. If the ++result is a complex number and the current mode is HMS, the number is ++instead expressed in degrees. (Complex-number calculations would ++normally be done in Radians mode, though. Complex numbers are converted ++to degrees by calculating the complex result in radians and then ++multiplying by 180 over @cpi{}.) ++ ++@kindex m r ++@pindex calc-radians-mode ++@kindex m d ++@pindex calc-degrees-mode ++@kindex m h ++@pindex calc-hms-mode ++The @kbd{m r} (@code{calc-radians-mode}), @kbd{m d} (@code{calc-degrees-mode}), ++and @kbd{m h} (@code{calc-hms-mode}) commands control the angular mode. ++The current angular mode is displayed on the Emacs mode line. ++The default angular mode is Degrees. ++ ++@node Polar Mode, Fraction Mode, Angular Modes, Calculation Modes ++@subsection Polar Mode ++ ++@noindent ++@cindex Polar mode ++The Calculator normally ``prefers'' rectangular complex numbers in the ++sense that rectangular form is used when the proper form can not be ++decided from the input. This might happen by multiplying a rectangular ++number by a polar one, by taking the square root of a negative real ++number, or by entering @kbd{( 2 @key{SPC} 3 )}. ++ ++@kindex m p ++@pindex calc-polar-mode ++The @kbd{m p} (@code{calc-polar-mode}) command toggles complex-number ++preference between rectangular and polar forms. In Polar mode, all ++of the above example situations would produce polar complex numbers. ++ ++@node Fraction Mode, Infinite Mode, Polar Mode, Calculation Modes ++@subsection Fraction Mode ++ ++@noindent ++@cindex Fraction mode ++@cindex Division of integers ++Division of two integers normally yields a floating-point number if the ++result cannot be expressed as an integer. In some cases you would ++rather get an exact fractional answer. One way to accomplish this is ++to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which ++divides the two integers on the top of the stack to produce a fraction: ++@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though ++@kbd{6 @key{RET} 4 /} produces @expr{1.5}. ++ ++@kindex m f ++@pindex calc-frac-mode ++To set the Calculator to produce fractional results for normal integer ++divisions, use the @kbd{m f} (@code{calc-frac-mode}) command. ++For example, @expr{8/4} produces @expr{2} in either mode, ++but @expr{6/4} produces @expr{3:2} in Fraction mode, @expr{1.5} in ++Float mode. ++ ++At any time you can use @kbd{c f} (@code{calc-float}) to convert a ++fraction to a float, or @kbd{c F} (@code{calc-fraction}) to convert a ++float to a fraction. @xref{Conversions}. ++ ++@node Infinite Mode, Symbolic Mode, Fraction Mode, Calculation Modes ++@subsection Infinite Mode ++ ++@noindent ++@cindex Infinite mode ++The Calculator normally treats results like @expr{1 / 0} as errors; ++formulas like this are left in unsimplified form. But Calc can be ++put into a mode where such calculations instead produce ``infinite'' ++results. ++ ++@kindex m i ++@pindex calc-infinite-mode ++The @kbd{m i} (@code{calc-infinite-mode}) command turns this mode ++on and off. When the mode is off, infinities do not arise except ++in calculations that already had infinities as inputs. (One exception ++is that infinite open intervals like @samp{[0 .. inf)} can be ++generated; however, intervals closed at infinity (@samp{[0 .. inf]}) ++will not be generated when Infinite mode is off.) ++ ++With Infinite mode turned on, @samp{1 / 0} will generate @code{uinf}, ++an undirected infinity. @xref{Infinities}, for a discussion of the ++difference between @code{inf} and @code{uinf}. Also, @expr{0 / 0} ++evaluates to @code{nan}, the ``indeterminate'' symbol. Various other ++functions can also return infinities in this mode; for example, ++@samp{ln(0) = -inf}, and @samp{gamma(-7) = uinf}. Once again, ++note that @samp{exp(inf) = inf} regardless of Infinite mode because ++this calculation has infinity as an input. ++ ++@cindex Positive Infinite mode ++The @kbd{m i} command with a numeric prefix argument of zero, ++i.e., @kbd{C-u 0 m i}, turns on a Positive Infinite mode in ++which zero is treated as positive instead of being directionless. ++Thus, @samp{1 / 0 = inf} and @samp{-1 / 0 = -inf} in this mode. ++Note that zero never actually has a sign in Calc; there are no ++separate representations for @mathit{+0} and @mathit{-0}. Positive ++Infinite mode merely changes the interpretation given to the ++single symbol, @samp{0}. One consequence of this is that, while ++you might expect @samp{1 / -0 = -inf}, actually @samp{1 / -0} ++is equivalent to @samp{1 / 0}, which is equal to positive @code{inf}. ++ ++@node Symbolic Mode, Matrix Mode, Infinite Mode, Calculation Modes ++@subsection Symbolic Mode ++ ++@noindent ++@cindex Symbolic mode ++@cindex Inexact results ++Calculations are normally performed numerically wherever possible. ++For example, the @code{calc-sqrt} command, or @code{sqrt} function in an ++algebraic expression, produces a numeric answer if the argument is a ++number or a symbolic expression if the argument is an expression: ++@kbd{2 Q} pushes 1.4142 but @kbd{@key{'} x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}. ++ ++@kindex m s ++@pindex calc-symbolic-mode ++In @dfn{Symbolic mode}, controlled by the @kbd{m s} (@code{calc-symbolic-mode}) ++command, functions which would produce inexact, irrational results are ++left in symbolic form. Thus @kbd{16 Q} pushes 4, but @kbd{2 Q} pushes ++@samp{sqrt(2)}. ++ ++@kindex N ++@pindex calc-eval-num ++The shift-@kbd{N} (@code{calc-eval-num}) command evaluates numerically ++the expression at the top of the stack, by temporarily disabling ++@code{calc-symbolic-mode} and executing @kbd{=} (@code{calc-evaluate}). ++Given a numeric prefix argument, it also ++sets the floating-point precision to the specified value for the duration ++of the command. ++ ++To evaluate a formula numerically without expanding the variables it ++contains, you can use the key sequence @kbd{m s a v m s} (this uses ++@code{calc-alg-evaluate}, which resimplifies but doesn't evaluate ++variables.) ++ ++@node Matrix Mode, Automatic Recomputation, Symbolic Mode, Calculation Modes ++@subsection Matrix and Scalar Modes ++ ++@noindent ++@cindex Matrix mode ++@cindex Scalar mode ++Calc sometimes makes assumptions during algebraic manipulation that ++are awkward or incorrect when vectors and matrices are involved. ++Calc has two modes, @dfn{Matrix mode} and @dfn{Scalar mode}, which ++modify its behavior around vectors in useful ways. ++ ++@kindex m v ++@pindex calc-matrix-mode ++Press @kbd{m v} (@code{calc-matrix-mode}) once to enter Matrix mode. ++In this mode, all objects are assumed to be matrices unless provably ++otherwise. One major effect is that Calc will no longer consider ++multiplication to be commutative. (Recall that in matrix arithmetic, ++@samp{A*B} is not the same as @samp{B*A}.) This assumption affects ++rewrite rules and algebraic simplification. Another effect of this ++mode is that calculations that would normally produce constants like ++0 and 1 (e.g., @expr{a - a} and @expr{a / a}, respectively) will now ++produce function calls that represent ``generic'' zero or identity ++matrices: @samp{idn(0)}, @samp{idn(1)}. The @code{idn} function ++@samp{idn(@var{a},@var{n})} returns @var{a} times an @var{n}x@var{n} ++identity matrix; if @var{n} is omitted, it doesn't know what ++dimension to use and so the @code{idn} call remains in symbolic ++form. However, if this generic identity matrix is later combined ++with a matrix whose size is known, it will be converted into ++a true identity matrix of the appropriate size. On the other hand, ++if it is combined with a scalar (as in @samp{idn(1) + 2}), Calc ++will assume it really was a scalar after all and produce, e.g., 3. ++ ++Press @kbd{m v} a second time to get Scalar mode. Here, objects are ++assumed @emph{not} to be vectors or matrices unless provably so. ++For example, normally adding a variable to a vector, as in ++@samp{[x, y, z] + a}, will leave the sum in symbolic form because ++as far as Calc knows, @samp{a} could represent either a number or ++another 3-vector. In Scalar mode, @samp{a} is assumed to be a ++non-vector, and the addition is evaluated to @samp{[x+a, y+a, z+a]}. ++ ++Press @kbd{m v} a third time to return to the normal mode of operation. ++ ++If you press @kbd{m v} with a numeric prefix argument @var{n}, you ++get a special ``dimensioned'' Matrix mode in which matrices of ++unknown size are assumed to be @var{n}x@var{n} square matrices. ++Then, the function call @samp{idn(1)} will expand into an actual ++matrix rather than representing a ``generic'' matrix. Simply typing ++@kbd{C-u m v} will get you a square Matrix mode, in which matrices of ++unknown size are assumed to be square matrices of unspecified size. ++ ++@cindex Declaring scalar variables ++Of course these modes are approximations to the true state of ++affairs, which is probably that some quantities will be matrices ++and others will be scalars. One solution is to ``declare'' ++certain variables or functions to be scalar-valued. ++@xref{Declarations}, to see how to make declarations in Calc. ++ ++There is nothing stopping you from declaring a variable to be ++scalar and then storing a matrix in it; however, if you do, the ++results you get from Calc may not be valid. Suppose you let Calc ++get the result @samp{[x+a, y+a, z+a]} shown above, and then stored ++@samp{[1, 2, 3]} in @samp{a}. The result would not be the same as ++for @samp{[x, y, z] + [1, 2, 3]}, but that's because you have broken ++your earlier promise to Calc that @samp{a} would be scalar. ++ ++Another way to mix scalars and matrices is to use selections ++(@pxref{Selecting Subformulas}). Use Matrix mode when operating on ++your formula normally; then, to apply Scalar mode to a certain part ++of the formula without affecting the rest just select that part, ++change into Scalar mode and press @kbd{=} to resimplify the part ++under this mode, then change back to Matrix mode before deselecting. ++ ++@node Automatic Recomputation, Working Message, Matrix Mode, Calculation Modes ++@subsection Automatic Recomputation ++ ++@noindent ++The @dfn{evaluates-to} operator, @samp{=>}, has the special ++property that any @samp{=>} formulas on the stack are recomputed ++whenever variable values or mode settings that might affect them ++are changed. @xref{Evaluates-To Operator}. ++ ++@kindex m C ++@pindex calc-auto-recompute ++The @kbd{m C} (@code{calc-auto-recompute}) command turns this ++automatic recomputation on and off. If you turn it off, Calc will ++not update @samp{=>} operators on the stack (nor those in the ++attached Embedded mode buffer, if there is one). They will not ++be updated unless you explicitly do so by pressing @kbd{=} or until ++you press @kbd{m C} to turn recomputation back on. (While automatic ++recomputation is off, you can think of @kbd{m C m C} as a command ++to update all @samp{=>} operators while leaving recomputation off.) ++ ++To update @samp{=>} operators in an Embedded buffer while ++automatic recomputation is off, use @w{@kbd{C-x * u}}. ++@xref{Embedded Mode}. ++ ++@node Working Message, , Automatic Recomputation, Calculation Modes ++@subsection Working Messages ++ ++@noindent ++@cindex Performance ++@cindex Working messages ++Since the Calculator is written entirely in Emacs Lisp, which is not ++designed for heavy numerical work, many operations are quite slow. ++The Calculator normally displays the message @samp{Working...} in the ++echo area during any command that may be slow. In addition, iterative ++operations such as square roots and trigonometric functions display the ++intermediate result at each step. Both of these types of messages can ++be disabled if you find them distracting. ++ ++@kindex m w ++@pindex calc-working ++Type @kbd{m w} (@code{calc-working}) with a numeric prefix of 0 to ++disable all ``working'' messages. Use a numeric prefix of 1 to enable ++only the plain @samp{Working...} message. Use a numeric prefix of 2 to ++see intermediate results as well. With no numeric prefix this displays ++the current mode. ++ ++While it may seem that the ``working'' messages will slow Calc down ++considerably, experiments have shown that their impact is actually ++quite small. But if your terminal is slow you may find that it helps ++to turn the messages off. ++ ++@node Simplification Modes, Declarations, Calculation Modes, Mode Settings ++@section Simplification Modes ++ ++@noindent ++The current @dfn{simplification mode} controls how numbers and formulas ++are ``normalized'' when being taken from or pushed onto the stack. ++Some normalizations are unavoidable, such as rounding floating-point ++results to the current precision, and reducing fractions to simplest ++form. Others, such as simplifying a formula like @expr{a+a} (or @expr{2+3}), ++are done by default but can be turned off when necessary. ++ ++When you press a key like @kbd{+} when @expr{2} and @expr{3} are on the ++stack, Calc pops these numbers, normalizes them, creates the formula ++@expr{2+3}, normalizes it, and pushes the result. Of course the standard ++rules for normalizing @expr{2+3} will produce the result @expr{5}. ++ ++Simplification mode commands consist of the lower-case @kbd{m} prefix key ++followed by a shifted letter. ++ ++@kindex m O ++@pindex calc-no-simplify-mode ++The @kbd{m O} (@code{calc-no-simplify-mode}) command turns off all optional ++simplifications. These would leave a formula like @expr{2+3} alone. In ++fact, nothing except simple numbers are ever affected by normalization ++in this mode. ++ ++@kindex m N ++@pindex calc-num-simplify-mode ++The @kbd{m N} (@code{calc-num-simplify-mode}) command turns off simplification ++of any formulas except those for which all arguments are constants. For ++example, @expr{1+2} is simplified to @expr{3}, and @expr{a+(2-2)} is ++simplified to @expr{a+0} but no further, since one argument of the sum ++is not a constant. Unfortunately, @expr{(a+2)-2} is @emph{not} simplified ++because the top-level @samp{-} operator's arguments are not both ++constant numbers (one of them is the formula @expr{a+2}). ++A constant is a number or other numeric object (such as a constant ++error form or modulo form), or a vector all of whose ++elements are constant. ++ ++@kindex m D ++@pindex calc-default-simplify-mode ++The @kbd{m D} (@code{calc-default-simplify-mode}) command restores the ++default simplifications for all formulas. This includes many easy and ++fast algebraic simplifications such as @expr{a+0} to @expr{a}, and ++@expr{a + 2 a} to @expr{3 a}, as well as evaluating functions like ++@expr{@tfn{deriv}(x^2, x)} to @expr{2 x}. ++ ++@kindex m B ++@pindex calc-bin-simplify-mode ++The @kbd{m B} (@code{calc-bin-simplify-mode}) mode applies the default ++simplifications to a result and then, if the result is an integer, ++uses the @kbd{b c} (@code{calc-clip}) command to clip the integer according ++to the current binary word size. @xref{Binary Functions}. Real numbers ++are rounded to the nearest integer and then clipped; other kinds of ++results (after the default simplifications) are left alone. ++ ++@kindex m A ++@pindex calc-alg-simplify-mode ++The @kbd{m A} (@code{calc-alg-simplify-mode}) mode does algebraic ++simplification; it applies all the default simplifications, and also ++the more powerful (and slower) simplifications made by @kbd{a s} ++(@code{calc-simplify}). @xref{Algebraic Simplifications}. ++ ++@kindex m E ++@pindex calc-ext-simplify-mode ++The @kbd{m E} (@code{calc-ext-simplify-mode}) mode does ``extended'' ++algebraic simplification, as by the @kbd{a e} (@code{calc-simplify-extended}) ++command. @xref{Unsafe Simplifications}. ++ ++@kindex m U ++@pindex calc-units-simplify-mode ++The @kbd{m U} (@code{calc-units-simplify-mode}) mode does units ++simplification; it applies the command @kbd{u s} ++(@code{calc-simplify-units}), which in turn ++is a superset of @kbd{a s}. In this mode, variable names which ++are identifiable as unit names (like @samp{mm} for ``millimeters'') ++are simplified with their unit definitions in mind. ++ ++A common technique is to set the simplification mode down to the lowest ++amount of simplification you will allow to be applied automatically, then ++use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to ++perform higher types of simplifications on demand. @xref{Algebraic ++Definitions}, for another sample use of No-Simplification mode. ++ ++@node Declarations, Display Modes, Simplification Modes, Mode Settings ++@section Declarations ++ ++@noindent ++A @dfn{declaration} is a statement you make that promises you will ++use a certain variable or function in a restricted way. This may ++give Calc the freedom to do things that it couldn't do if it had to ++take the fully general situation into account. ++ ++@menu ++* Declaration Basics:: ++* Kinds of Declarations:: ++* Functions for Declarations:: ++@end menu ++ ++@node Declaration Basics, Kinds of Declarations, Declarations, Declarations ++@subsection Declaration Basics ++ ++@noindent ++@kindex s d ++@pindex calc-declare-variable ++The @kbd{s d} (@code{calc-declare-variable}) command is the easiest ++way to make a declaration for a variable. This command prompts for ++the variable name, then prompts for the declaration. The default ++at the declaration prompt is the previous declaration, if any. ++You can edit this declaration, or press @kbd{C-k} to erase it and ++type a new declaration. (Or, erase it and press @key{RET} to clear ++the declaration, effectively ``undeclaring'' the variable.) ++ ++A declaration is in general a vector of @dfn{type symbols} and ++@dfn{range} values. If there is only one type symbol or range value, ++you can write it directly rather than enclosing it in a vector. ++For example, @kbd{s d foo @key{RET} real @key{RET}} declares @code{foo} to ++be a real number, and @kbd{s d bar @key{RET} [int, const, [1..6]] @key{RET}} ++declares @code{bar} to be a constant integer between 1 and 6. ++(Actually, you can omit the outermost brackets and Calc will ++provide them for you: @kbd{s d bar @key{RET} int, const, [1..6] @key{RET}}.) ++ ++@cindex @code{Decls} variable ++@vindex Decls ++Declarations in Calc are kept in a special variable called @code{Decls}. ++This variable encodes the set of all outstanding declarations in ++the form of a matrix. Each row has two elements: A variable or ++vector of variables declared by that row, and the declaration ++specifier as described above. You can use the @kbd{s D} command to ++edit this variable if you wish to see all the declarations at once. ++@xref{Operations on Variables}, for a description of this command ++and the @kbd{s p} command that allows you to save your declarations ++permanently if you wish. ++ ++Items being declared can also be function calls. The arguments in ++the call are ignored; the effect is to say that this function returns ++values of the declared type for any valid arguments. The @kbd{s d} ++command declares only variables, so if you wish to make a function ++declaration you will have to edit the @code{Decls} matrix yourself. ++ ++For example, the declaration matrix ++ ++@smallexample ++@group ++[ [ foo, real ] ++ [ [j, k, n], int ] ++ [ f(1,2,3), [0 .. inf) ] ] ++@end group ++@end smallexample ++ ++@noindent ++declares that @code{foo} represents a real number, @code{j}, @code{k} ++and @code{n} represent integers, and the function @code{f} always ++returns a real number in the interval shown. ++ ++@vindex All ++If there is a declaration for the variable @code{All}, then that ++declaration applies to all variables that are not otherwise declared. ++It does not apply to function names. For example, using the row ++@samp{[All, real]} says that all your variables are real unless they ++are explicitly declared without @code{real} in some other row. ++The @kbd{s d} command declares @code{All} if you give a blank ++response to the variable-name prompt. ++ ++@node Kinds of Declarations, Functions for Declarations, Declaration Basics, Declarations ++@subsection Kinds of Declarations ++ ++@noindent ++The type-specifier part of a declaration (that is, the second prompt ++in the @kbd{s d} command) can be a type symbol, an interval, or a ++vector consisting of zero or more type symbols followed by zero or ++more intervals or numbers that represent the set of possible values ++for the variable. ++ ++@smallexample ++@group ++[ [ a, [1, 2, 3, 4, 5] ] ++ [ b, [1 .. 5] ] ++ [ c, [int, 1 .. 5] ] ] ++@end group ++@end smallexample ++ ++Here @code{a} is declared to contain one of the five integers shown; ++@code{b} is any number in the interval from 1 to 5 (any real number ++since we haven't specified), and @code{c} is any integer in that ++interval. Thus the declarations for @code{a} and @code{c} are ++nearly equivalent (see below). ++ ++The type-specifier can be the empty vector @samp{[]} to say that ++nothing is known about a given variable's value. This is the same ++as not declaring the variable at all except that it overrides any ++@code{All} declaration which would otherwise apply. ++ ++The initial value of @code{Decls} is the empty vector @samp{[]}. ++If @code{Decls} has no stored value or if the value stored in it ++is not valid, it is ignored and there are no declarations as far ++as Calc is concerned. (The @kbd{s d} command will replace such a ++malformed value with a fresh empty matrix, @samp{[]}, before recording ++the new declaration.) Unrecognized type symbols are ignored. ++ ++The following type symbols describe what sorts of numbers will be ++stored in a variable: ++ ++@table @code ++@item int ++Integers. ++@item numint ++Numerical integers. (Integers or integer-valued floats.) ++@item frac ++Fractions. (Rational numbers which are not integers.) ++@item rat ++Rational numbers. (Either integers or fractions.) ++@item float ++Floating-point numbers. ++@item real ++Real numbers. (Integers, fractions, or floats. Actually, ++intervals and error forms with real components also count as ++reals here.) ++@item pos ++Positive real numbers. (Strictly greater than zero.) ++@item nonneg ++Nonnegative real numbers. (Greater than or equal to zero.) ++@item number ++Numbers. (Real or complex.) ++@end table ++ ++Calc uses this information to determine when certain simplifications ++of formulas are safe. For example, @samp{(x^y)^z} cannot be ++simplified to @samp{x^(y z)} in general; for example, ++@samp{((-3)^2)^1:2} is 3, but @samp{(-3)^(2*1:2) = (-3)^1} is @mathit{-3}. ++However, this simplification @emph{is} safe if @code{z} is known ++to be an integer, or if @code{x} is known to be a nonnegative ++real number. If you have given declarations that allow Calc to ++deduce either of these facts, Calc will perform this simplification ++of the formula. ++ ++Calc can apply a certain amount of logic when using declarations. ++For example, @samp{(x^y)^(2n+1)} will be simplified if @code{n} ++has been declared @code{int}; Calc knows that an integer times an ++integer, plus an integer, must always be an integer. (In fact, ++Calc would simplify @samp{(-x)^(2n+1)} to @samp{-(x^(2n+1))} since ++it is able to determine that @samp{2n+1} must be an odd integer.) ++ ++Similarly, @samp{(abs(x)^y)^z} will be simplified to @samp{abs(x)^(y z)} ++because Calc knows that the @code{abs} function always returns a ++nonnegative real. If you had a @code{myabs} function that also had ++this property, you could get Calc to recognize it by adding the row ++@samp{[myabs(), nonneg]} to the @code{Decls} matrix. ++ ++One instance of this simplification is @samp{sqrt(x^2)} (since the ++@code{sqrt} function is effectively a one-half power). Normally ++Calc leaves this formula alone. After the command ++@kbd{s d x @key{RET} real @key{RET}}, however, it can simplify the formula to ++@samp{abs(x)}. And after @kbd{s d x @key{RET} nonneg @key{RET}}, Calc can ++simplify this formula all the way to @samp{x}. ++ ++If there are any intervals or real numbers in the type specifier, ++they comprise the set of possible values that the variable or ++function being declared can have. In particular, the type symbol ++@code{real} is effectively the same as the range @samp{[-inf .. inf]} ++(note that infinity is included in the range of possible values); ++@code{pos} is the same as @samp{(0 .. inf]}, and @code{nonneg} is ++the same as @samp{[0 .. inf]}. Saying @samp{[real, [-5 .. 5]]} is ++redundant because the fact that the variable is real can be ++deduced just from the interval, but @samp{[int, [-5 .. 5]]} and ++@samp{[rat, [-5 .. 5]]} are useful combinations. ++ ++Note that the vector of intervals or numbers is in the same format ++used by Calc's set-manipulation commands. @xref{Set Operations}. ++ ++The type specifier @samp{[1, 2, 3]} is equivalent to ++@samp{[numint, 1, 2, 3]}, @emph{not} to @samp{[int, 1, 2, 3]}. ++In other words, the range of possible values means only that ++the variable's value must be numerically equal to a number in ++that range, but not that it must be equal in type as well. ++Calc's set operations act the same way; @samp{in(2, [1., 2., 3.])} ++and @samp{in(1.5, [1:2, 3:2, 5:2])} both report ``true.'' ++ ++If you use a conflicting combination of type specifiers, the ++results are unpredictable. An example is @samp{[pos, [0 .. 5]]}, ++where the interval does not lie in the range described by the ++type symbol. ++ ++``Real'' declarations mostly affect simplifications involving powers ++like the one described above. Another case where they are used ++is in the @kbd{a P} command which returns a list of all roots of a ++polynomial; if the variable has been declared real, only the real ++roots (if any) will be included in the list. ++ ++``Integer'' declarations are used for simplifications which are valid ++only when certain values are integers (such as @samp{(x^y)^z} ++shown above). ++ ++Another command that makes use of declarations is @kbd{a s}, when ++simplifying equations and inequalities. It will cancel @code{x} ++from both sides of @samp{a x = b x} only if it is sure @code{x} ++is non-zero, say, because it has a @code{pos} declaration. ++To declare specifically that @code{x} is real and non-zero, ++use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the ++current notation to say that @code{x} is nonzero but not necessarily ++real.) The @kbd{a e} command does ``unsafe'' simplifications, ++including cancelling @samp{x} from the equation when @samp{x} is ++not known to be nonzero. ++ ++Another set of type symbols distinguish between scalars and vectors. ++ ++@table @code ++@item scalar ++The value is not a vector. ++@item vector ++The value is a vector. ++@item matrix ++The value is a matrix (a rectangular vector of vectors). ++@item sqmatrix ++The value is a square matrix. ++@end table ++ ++These type symbols can be combined with the other type symbols ++described above; @samp{[int, matrix]} describes an object which ++is a matrix of integers. ++ ++Scalar/vector declarations are used to determine whether certain ++algebraic operations are safe. For example, @samp{[a, b, c] + x} ++is normally not simplified to @samp{[a + x, b + x, c + x]}, but ++it will be if @code{x} has been declared @code{scalar}. On the ++other hand, multiplication is usually assumed to be commutative, ++but the terms in @samp{x y} will never be exchanged if both @code{x} ++and @code{y} are known to be vectors or matrices. (Calc currently ++never distinguishes between @code{vector} and @code{matrix} ++declarations.) ++ ++@xref{Matrix Mode}, for a discussion of Matrix mode and ++Scalar mode, which are similar to declaring @samp{[All, matrix]} ++or @samp{[All, scalar]} but much more convenient. ++ ++One more type symbol that is recognized is used with the @kbd{H a d} ++command for taking total derivatives of a formula. @xref{Calculus}. ++ ++@table @code ++@item const ++The value is a constant with respect to other variables. ++@end table ++ ++Calc does not check the declarations for a variable when you store ++a value in it. However, storing @mathit{-3.5} in a variable that has ++been declared @code{pos}, @code{int}, or @code{matrix} may have ++unexpected effects; Calc may evaluate @samp{sqrt(x^2)} to @expr{3.5} ++if it substitutes the value first, or to @expr{-3.5} if @code{x} ++was declared @code{pos} and the formula @samp{sqrt(x^2)} is ++simplified to @samp{x} before the value is substituted. Before ++using a variable for a new purpose, it is best to use @kbd{s d} ++or @kbd{s D} to check to make sure you don't still have an old ++declaration for the variable that will conflict with its new meaning. ++ ++@node Functions for Declarations, , Kinds of Declarations, Declarations ++@subsection Functions for Declarations ++ ++@noindent ++Calc has a set of functions for accessing the current declarations ++in a convenient manner. These functions return 1 if the argument ++can be shown to have the specified property, or 0 if the argument ++can be shown @emph{not} to have that property; otherwise they are ++left unevaluated. These functions are suitable for use with rewrite ++rules (@pxref{Conditional Rewrite Rules}) or programming constructs ++(@pxref{Conditionals in Macros}). They can be entered only using ++algebraic notation. @xref{Logical Operations}, for functions ++that perform other tests not related to declarations. ++ ++For example, @samp{dint(17)} returns 1 because 17 is an integer, as ++do @samp{dint(n)} and @samp{dint(2 n - 3)} if @code{n} has been declared ++@code{int}, but @samp{dint(2.5)} and @samp{dint(n + 0.5)} return 0. ++Calc consults knowledge of its own built-in functions as well as your ++own declarations: @samp{dint(floor(x))} returns 1. ++ ++@ignore ++@starindex ++@end ignore ++@tindex dint ++@ignore ++@starindex ++@end ignore ++@tindex dnumint ++@ignore ++@starindex ++@end ignore ++@tindex dnatnum ++The @code{dint} function checks if its argument is an integer. ++The @code{dnatnum} function checks if its argument is a natural ++number, i.e., a nonnegative integer. The @code{dnumint} function ++checks if its argument is numerically an integer, i.e., either an ++integer or an integer-valued float. Note that these and the other ++data type functions also accept vectors or matrices composed of ++suitable elements, and that real infinities @samp{inf} and @samp{-inf} ++are considered to be integers for the purposes of these functions. ++ ++@ignore ++@starindex ++@end ignore ++@tindex drat ++The @code{drat} function checks if its argument is rational, i.e., ++an integer or fraction. Infinities count as rational, but intervals ++and error forms do not. ++ ++@ignore ++@starindex ++@end ignore ++@tindex dreal ++The @code{dreal} function checks if its argument is real. This ++includes integers, fractions, floats, real error forms, and intervals. ++ ++@ignore ++@starindex ++@end ignore ++@tindex dimag ++The @code{dimag} function checks if its argument is imaginary, ++i.e., is mathematically equal to a real number times @expr{i}. ++ ++@ignore ++@starindex ++@end ignore ++@tindex dpos ++@ignore ++@starindex ++@end ignore ++@tindex dneg ++@ignore ++@starindex ++@end ignore ++@tindex dnonneg ++The @code{dpos} function checks for positive (but nonzero) reals. ++The @code{dneg} function checks for negative reals. The @code{dnonneg} ++function checks for nonnegative reals, i.e., reals greater than or ++equal to zero. Note that the @kbd{a s} command can simplify an ++expression like @expr{x > 0} to 1 or 0 using @code{dpos}, and that ++@kbd{a s} is effectively applied to all conditions in rewrite rules, ++so the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg} ++are rarely necessary. ++ ++@ignore ++@starindex ++@end ignore ++@tindex dnonzero ++The @code{dnonzero} function checks that its argument is nonzero. ++This includes all nonzero real or complex numbers, all intervals that ++do not include zero, all nonzero modulo forms, vectors all of whose ++elements are nonzero, and variables or formulas whose values can be ++deduced to be nonzero. It does not include error forms, since they ++represent values which could be anything including zero. (This is ++also the set of objects considered ``true'' in conditional contexts.) ++ ++@ignore ++@starindex ++@end ignore ++@tindex deven ++@ignore ++@starindex ++@end ignore ++@tindex dodd ++The @code{deven} function returns 1 if its argument is known to be ++an even integer (or integer-valued float); it returns 0 if its argument ++is known not to be even (because it is known to be odd or a non-integer). ++The @kbd{a s} command uses this to simplify a test of the form ++@samp{x % 2 = 0}. There is also an analogous @code{dodd} function. ++ ++@ignore ++@starindex ++@end ignore ++@tindex drange ++The @code{drange} function returns a set (an interval or a vector ++of intervals and/or numbers; @pxref{Set Operations}) that describes ++the set of possible values of its argument. If the argument is ++a variable or a function with a declaration, the range is copied ++from the declaration. Otherwise, the possible signs of the ++expression are determined using a method similar to @code{dpos}, ++etc., and a suitable set like @samp{[0 .. inf]} is returned. If ++the expression is not provably real, the @code{drange} function ++remains unevaluated. ++ ++@ignore ++@starindex ++@end ignore ++@tindex dscalar ++The @code{dscalar} function returns 1 if its argument is provably ++scalar, or 0 if its argument is provably non-scalar. It is left ++unevaluated if this cannot be determined. (If Matrix mode or Scalar ++mode is in effect, this function returns 1 or 0, respectively, ++if it has no other information.) When Calc interprets a condition ++(say, in a rewrite rule) it considers an unevaluated formula to be ++``false.'' Thus, @samp{dscalar(a)} is ``true'' only if @code{a} is ++provably scalar, and @samp{!dscalar(a)} is ``true'' only if @code{a} ++is provably non-scalar; both are ``false'' if there is insufficient ++information to tell. ++ ++@node Display Modes, Language Modes, Declarations, Mode Settings ++@section Display Modes ++ ++@noindent ++The commands in this section are two-key sequences beginning with the ++@kbd{d} prefix. The @kbd{d l} (@code{calc-line-numbering}) and @kbd{d b} ++(@code{calc-line-breaking}) commands are described elsewhere; ++@pxref{Stack Basics} and @pxref{Normal Language Modes}, respectively. ++Display formats for vectors and matrices are also covered elsewhere; ++@pxref{Vector and Matrix Formats}. ++ ++One thing all display modes have in common is their treatment of the ++@kbd{H} prefix. This prefix causes any mode command that would normally ++refresh the stack to leave the stack display alone. The word ``Dirty'' ++will appear in the mode line when Calc thinks the stack display may not ++reflect the latest mode settings. ++ ++@kindex d @key{RET} ++@pindex calc-refresh-top ++The @kbd{d @key{RET}} (@code{calc-refresh-top}) command reformats the ++top stack entry according to all the current modes. Positive prefix ++arguments reformat the top @var{n} entries; negative prefix arguments ++reformat the specified entry, and a prefix of zero is equivalent to ++@kbd{d @key{SPC}} (@code{calc-refresh}), which reformats the entire stack. ++For example, @kbd{H d s M-2 d @key{RET}} changes to scientific notation ++but reformats only the top two stack entries in the new mode. ++ ++The @kbd{I} prefix has another effect on the display modes. The mode ++is set only temporarily; the top stack entry is reformatted according ++to that mode, then the original mode setting is restored. In other ++words, @kbd{I d s} is equivalent to @kbd{H d s d @key{RET} H d (@var{old mode})}. ++ ++@menu ++* Radix Modes:: ++* Grouping Digits:: ++* Float Formats:: ++* Complex Formats:: ++* Fraction Formats:: ++* HMS Formats:: ++* Date Formats:: ++* Truncating the Stack:: ++* Justification:: ++* Labels:: ++@end menu ++ ++@node Radix Modes, Grouping Digits, Display Modes, Display Modes ++@subsection Radix Modes ++ ++@noindent ++@cindex Radix display ++@cindex Non-decimal numbers ++@cindex Decimal and non-decimal numbers ++Calc normally displays numbers in decimal (@dfn{base-10} or @dfn{radix-10}) ++notation. Calc can actually display in any radix from two (binary) to 36. ++When the radix is above 10, the letters @code{A} to @code{Z} are used as ++digits. When entering such a number, letter keys are interpreted as ++potential digits rather than terminating numeric entry mode. ++ ++@kindex d 2 ++@kindex d 8 ++@kindex d 6 ++@kindex d 0 ++@cindex Hexadecimal integers ++@cindex Octal integers ++The key sequences @kbd{d 2}, @kbd{d 8}, @kbd{d 6}, and @kbd{d 0} select ++binary, octal, hexadecimal, and decimal as the current display radix, ++respectively. Numbers can always be entered in any radix, though the ++current radix is used as a default if you press @kbd{#} without any initial ++digits. A number entered without a @kbd{#} is @emph{always} interpreted ++as decimal. ++ ++@kindex d r ++@pindex calc-radix ++To set the radix generally, use @kbd{d r} (@code{calc-radix}) and enter ++an integer from 2 to 36. You can specify the radix as a numeric prefix ++argument; otherwise you will be prompted for it. ++ ++@kindex d z ++@pindex calc-leading-zeros ++@cindex Leading zeros ++Integers normally are displayed with however many digits are necessary to ++represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros}) ++command causes integers to be padded out with leading zeros according to the ++current binary word size. (@xref{Binary Functions}, for a discussion of ++word size.) If the absolute value of the word size is @expr{w}, all integers ++are displayed with at least enough digits to represent ++@texline @math{2^w-1} ++@infoline @expr{(2^w)-1} ++in the current radix. (Larger integers will still be displayed in their ++entirety.) ++ ++@node Grouping Digits, Float Formats, Radix Modes, Display Modes ++@subsection Grouping Digits ++ ++@noindent ++@kindex d g ++@pindex calc-group-digits ++@cindex Grouping digits ++@cindex Digit grouping ++Long numbers can be hard to read if they have too many digits. For ++example, the factorial of 30 is 33 digits long! Press @kbd{d g} ++(@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits ++are displayed in clumps of 3 or 4 (depending on the current radix) ++separated by commas. ++ ++The @kbd{d g} command toggles grouping on and off. ++With a numeric prefix of 0, this command displays the current state of ++the grouping flag; with an argument of minus one it disables grouping; ++with a positive argument @expr{N} it enables grouping on every @expr{N} ++digits. For floating-point numbers, grouping normally occurs only ++before the decimal point. A negative prefix argument @expr{-N} enables ++grouping every @expr{N} digits both before and after the decimal point. ++ ++@kindex d , ++@pindex calc-group-char ++The @kbd{d ,} (@code{calc-group-char}) command allows you to choose any ++character as the grouping separator. The default is the comma character. ++If you find it difficult to read vectors of large integers grouped with ++commas, you may wish to use spaces or some other character instead. ++This command takes the next character you type, whatever it is, and ++uses it as the digit separator. As a special case, @kbd{d , \} selects ++@samp{\,} (@TeX{}'s thin-space symbol) as the digit separator. ++ ++Please note that grouped numbers will not generally be parsed correctly ++if re-read in textual form, say by the use of @kbd{C-x * y} and @kbd{C-x * g}. ++(@xref{Kill and Yank}, for details on these commands.) One exception is ++the @samp{\,} separator, which doesn't interfere with parsing because it ++is ignored by @TeX{} language mode. ++ ++@node Float Formats, Complex Formats, Grouping Digits, Display Modes ++@subsection Float Formats ++ ++@noindent ++Floating-point quantities are normally displayed in standard decimal ++form, with scientific notation used if the exponent is especially high ++or low. All significant digits are normally displayed. The commands ++in this section allow you to choose among several alternative display ++formats for floats. ++ ++@kindex d n ++@pindex calc-normal-notation ++The @kbd{d n} (@code{calc-normal-notation}) command selects the normal ++display format. All significant figures in a number are displayed. ++With a positive numeric prefix, numbers are rounded if necessary to ++that number of significant digits. With a negative numerix prefix, ++the specified number of significant digits less than the current ++precision is used. (Thus @kbd{C-u -2 d n} displays 10 digits if the ++current precision is 12.) ++ ++@kindex d f ++@pindex calc-fix-notation ++The @kbd{d f} (@code{calc-fix-notation}) command selects fixed-point ++notation. The numeric argument is the number of digits after the ++decimal point, zero or more. This format will relax into scientific ++notation if a nonzero number would otherwise have been rounded all the ++way to zero. Specifying a negative number of digits is the same as ++for a positive number, except that small nonzero numbers will be rounded ++to zero rather than switching to scientific notation. ++ ++@kindex d s ++@pindex calc-sci-notation ++@cindex Scientific notation, display of ++The @kbd{d s} (@code{calc-sci-notation}) command selects scientific ++notation. A positive argument sets the number of significant figures ++displayed, of which one will be before and the rest after the decimal ++point. A negative argument works the same as for @kbd{d n} format. ++The default is to display all significant digits. ++ ++@kindex d e ++@pindex calc-eng-notation ++@cindex Engineering notation, display of ++The @kbd{d e} (@code{calc-eng-notation}) command selects engineering ++notation. This is similar to scientific notation except that the ++exponent is rounded down to a multiple of three, with from one to three ++digits before the decimal point. An optional numeric prefix sets the ++number of significant digits to display, as for @kbd{d s}. ++ ++It is important to distinguish between the current @emph{precision} and ++the current @emph{display format}. After the commands @kbd{C-u 10 p} ++and @kbd{C-u 6 d n} the Calculator computes all results to ten ++significant figures but displays only six. (In fact, intermediate ++calculations are often carried to one or two more significant figures, ++but values placed on the stack will be rounded down to ten figures.) ++Numbers are never actually rounded to the display precision for storage, ++except by commands like @kbd{C-k} and @kbd{C-x * y} which operate on the ++actual displayed text in the Calculator buffer. ++ ++@kindex d . ++@pindex calc-point-char ++The @kbd{d .} (@code{calc-point-char}) command selects the character used ++as a decimal point. Normally this is a period; users in some countries ++may wish to change this to a comma. Note that this is only a display ++style; on entry, periods must always be used to denote floating-point ++numbers, and commas to separate elements in a list. ++ ++@node Complex Formats, Fraction Formats, Float Formats, Display Modes ++@subsection Complex Formats ++ ++@noindent ++@kindex d c ++@pindex calc-complex-notation ++There are three supported notations for complex numbers in rectangular ++form. The default is as a pair of real numbers enclosed in parentheses ++and separated by a comma: @samp{(a,b)}. The @kbd{d c} ++(@code{calc-complex-notation}) command selects this style. ++ ++@kindex d i ++@pindex calc-i-notation ++@kindex d j ++@pindex calc-j-notation ++The other notations are @kbd{d i} (@code{calc-i-notation}), in which ++numbers are displayed in @samp{a+bi} form, and @kbd{d j} ++(@code{calc-j-notation}) which displays the form @samp{a+bj} preferred ++in some disciplines. ++ ++@cindex @code{i} variable ++@vindex i ++Complex numbers are normally entered in @samp{(a,b)} format. ++If you enter @samp{2+3i} as an algebraic formula, it will be stored as ++the formula @samp{2 + 3 * i}. However, if you use @kbd{=} to evaluate ++this formula and you have not changed the variable @samp{i}, the @samp{i} ++will be interpreted as @samp{(0,1)} and the formula will be simplified ++to @samp{(2,3)}. Other commands (like @code{calc-sin}) will @emph{not} ++interpret the formula @samp{2 + 3 * i} as a complex number. ++@xref{Variables}, under ``special constants.'' ++ ++@node Fraction Formats, HMS Formats, Complex Formats, Display Modes ++@subsection Fraction Formats ++ ++@noindent ++@kindex d o ++@pindex calc-over-notation ++Display of fractional numbers is controlled by the @kbd{d o} ++(@code{calc-over-notation}) command. By default, a number like ++eight thirds is displayed in the form @samp{8:3}. The @kbd{d o} command ++prompts for a one- or two-character format. If you give one character, ++that character is used as the fraction separator. Common separators are ++@samp{:} and @samp{/}. (During input of numbers, the @kbd{:} key must be ++used regardless of the display format; in particular, the @kbd{/} is used ++for RPN-style division, @emph{not} for entering fractions.) ++ ++If you give two characters, fractions use ``integer-plus-fractional-part'' ++notation. For example, the format @samp{+/} would display eight thirds ++as @samp{2+2/3}. If two colons are present in a number being entered, ++the number is interpreted in this form (so that the entries @kbd{2:2:3} ++and @kbd{8:3} are equivalent). ++ ++It is also possible to follow the one- or two-character format with ++a number. For example: @samp{:10} or @samp{+/3}. In this case, ++Calc adjusts all fractions that are displayed to have the specified ++denominator, if possible. Otherwise it adjusts the denominator to ++be a multiple of the specified value. For example, in @samp{:6} mode ++the fraction @expr{1:6} will be unaffected, but @expr{2:3} will be ++displayed as @expr{4:6}, @expr{1:2} will be displayed as @expr{3:6}, ++and @expr{1:8} will be displayed as @expr{3:24}. Integers are also ++affected by this mode: 3 is displayed as @expr{18:6}. Note that the ++format @samp{:1} writes fractions the same as @samp{:}, but it writes ++integers as @expr{n:1}. ++ ++The fraction format does not affect the way fractions or integers are ++stored, only the way they appear on the screen. The fraction format ++never affects floats. ++ ++@node HMS Formats, Date Formats, Fraction Formats, Display Modes ++@subsection HMS Formats ++ ++@noindent ++@kindex d h ++@pindex calc-hms-notation ++The @kbd{d h} (@code{calc-hms-notation}) command controls the display of ++HMS (hours-minutes-seconds) forms. It prompts for a string which ++consists basically of an ``hours'' marker, optional punctuation, a ++``minutes'' marker, more optional punctuation, and a ``seconds'' marker. ++Punctuation is zero or more spaces, commas, or semicolons. The hours ++marker is one or more non-punctuation characters. The minutes and ++seconds markers must be single non-punctuation characters. ++ ++The default HMS format is @samp{@@ ' "}, producing HMS values of the form ++@samp{23@@ 30' 15.75"}. The format @samp{deg, ms} would display this same ++value as @samp{23deg, 30m15.75s}. During numeric entry, the @kbd{h} or @kbd{o} ++keys are recognized as synonyms for @kbd{@@} regardless of display format. ++The @kbd{m} and @kbd{s} keys are recognized as synonyms for @kbd{'} and ++@kbd{"}, respectively, but only if an @kbd{@@} (or @kbd{h} or @kbd{o}) has ++already been typed; otherwise, they have their usual meanings ++(@kbd{m-} prefix and @kbd{s-} prefix). Thus, @kbd{5 "}, @kbd{0 @@ 5 "}, and ++@kbd{0 h 5 s} are some of the ways to enter the quantity ``five seconds.'' ++The @kbd{'} key is recognized as ``minutes'' only if @kbd{@@} (or @kbd{h} or ++@kbd{o}) has already been pressed; otherwise it means to switch to algebraic ++entry. ++ ++@node Date Formats, Truncating the Stack, HMS Formats, Display Modes ++@subsection Date Formats ++ ++@noindent ++@kindex d d ++@pindex calc-date-notation ++The @kbd{d d} (@code{calc-date-notation}) command controls the display ++of date forms (@pxref{Date Forms}). It prompts for a string which ++contains letters that represent the various parts of a date and time. ++To show which parts should be omitted when the form represents a pure ++date with no time, parts of the string can be enclosed in @samp{< >} ++marks. If you don't include @samp{< >} markers in the format, Calc ++guesses at which parts, if any, should be omitted when formatting ++pure dates. ++ ++The default format is: @samp{Www Mmm D, YYYY}. ++An example string in this format is @samp{3:32pm Wed Jan 9, 1991}. ++If you enter a blank format string, this default format is ++reestablished. ++ ++Calc uses @samp{< >} notation for nameless functions as well as for ++dates. @xref{Specifying Operators}. To avoid confusion with nameless ++functions, your date formats should avoid using the @samp{#} character. ++ ++@menu ++* Date Formatting Codes:: ++* Free-Form Dates:: ++* Standard Date Formats:: ++@end menu ++ ++@node Date Formatting Codes, Free-Form Dates, Date Formats, Date Formats ++@subsubsection Date Formatting Codes ++ ++@noindent ++When displaying a date, the current date format is used. All ++characters except for letters and @samp{<} and @samp{>} are ++copied literally when dates are formatted. The portion between ++@samp{< >} markers is omitted for pure dates, or included for ++date/time forms. Letters are interpreted according to the table ++below. ++ ++When dates are read in during algebraic entry, Calc first tries to ++match the input string to the current format either with or without ++the time part. The punctuation characters (including spaces) must ++match exactly; letter fields must correspond to suitable text in ++the input. If this doesn't work, Calc checks if the input is a ++simple number; if so, the number is interpreted as a number of days ++since Jan 1, 1 AD. Otherwise, Calc tries a much more relaxed and ++flexible algorithm which is described in the next section. ++ ++Weekday names are ignored during reading. ++ ++Two-digit year numbers are interpreted as lying in the range ++from 1941 to 2039. Years outside that range are always ++entered and displayed in full. Year numbers with a leading ++@samp{+} sign are always interpreted exactly, allowing the ++entry and display of the years 1 through 99 AD. ++ ++Here is a complete list of the formatting codes for dates: ++ ++@table @asis ++@item Y ++Year: ``91'' for 1991, ``7'' for 2007, ``+23'' for 23 AD. ++@item YY ++Year: ``91'' for 1991, ``07'' for 2007, ``+23'' for 23 AD. ++@item BY ++Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD. ++@item YYY ++Year: ``1991'' for 1991, ``23'' for 23 AD. ++@item YYYY ++Year: ``1991'' for 1991, ``+23'' for 23 AD. ++@item aa ++Year: ``ad'' or blank. ++@item AA ++Year: ``AD'' or blank. ++@item aaa ++Year: ``ad '' or blank. (Note trailing space.) ++@item AAA ++Year: ``AD '' or blank. ++@item aaaa ++Year: ``a.d.'' or blank. ++@item AAAA ++Year: ``A.D.'' or blank. ++@item bb ++Year: ``bc'' or blank. ++@item BB ++Year: ``BC'' or blank. ++@item bbb ++Year: `` bc'' or blank. (Note leading space.) ++@item BBB ++Year: `` BC'' or blank. ++@item bbbb ++Year: ``b.c.'' or blank. ++@item BBBB ++Year: ``B.C.'' or blank. ++@item M ++Month: ``8'' for August. ++@item MM ++Month: ``08'' for August. ++@item BM ++Month: `` 8'' for August. ++@item MMM ++Month: ``AUG'' for August. ++@item Mmm ++Month: ``Aug'' for August. ++@item mmm ++Month: ``aug'' for August. ++@item MMMM ++Month: ``AUGUST'' for August. ++@item Mmmm ++Month: ``August'' for August. ++@item D ++Day: ``7'' for 7th day of month. ++@item DD ++Day: ``07'' for 7th day of month. ++@item BD ++Day: `` 7'' for 7th day of month. ++@item W ++Weekday: ``0'' for Sunday, ``6'' for Saturday. ++@item WWW ++Weekday: ``SUN'' for Sunday. ++@item Www ++Weekday: ``Sun'' for Sunday. ++@item www ++Weekday: ``sun'' for Sunday. ++@item WWWW ++Weekday: ``SUNDAY'' for Sunday. ++@item Wwww ++Weekday: ``Sunday'' for Sunday. ++@item d ++Day of year: ``34'' for Feb. 3. ++@item ddd ++Day of year: ``034'' for Feb. 3. ++@item bdd ++Day of year: `` 34'' for Feb. 3. ++@item h ++Hour: ``5'' for 5 AM; ``17'' for 5 PM. ++@item hh ++Hour: ``05'' for 5 AM; ``17'' for 5 PM. ++@item bh ++Hour: `` 5'' for 5 AM; ``17'' for 5 PM. ++@item H ++Hour: ``5'' for 5 AM and 5 PM. ++@item HH ++Hour: ``05'' for 5 AM and 5 PM. ++@item BH ++Hour: `` 5'' for 5 AM and 5 PM. ++@item p ++AM/PM: ``a'' or ``p''. ++@item P ++AM/PM: ``A'' or ``P''. ++@item pp ++AM/PM: ``am'' or ``pm''. ++@item PP ++AM/PM: ``AM'' or ``PM''. ++@item pppp ++AM/PM: ``a.m.'' or ``p.m.''. ++@item PPPP ++AM/PM: ``A.M.'' or ``P.M.''. ++@item m ++Minutes: ``7'' for 7. ++@item mm ++Minutes: ``07'' for 7. ++@item bm ++Minutes: `` 7'' for 7. ++@item s ++Seconds: ``7'' for 7; ``7.23'' for 7.23. ++@item ss ++Seconds: ``07'' for 7; ``07.23'' for 7.23. ++@item bs ++Seconds: `` 7'' for 7; `` 7.23'' for 7.23. ++@item SS ++Optional seconds: ``07'' for 7; blank for 0. ++@item BS ++Optional seconds: `` 7'' for 7; blank for 0. ++@item N ++Numeric date/time: ``726842.25'' for 6:00am Wed Jan 9, 1991. ++@item n ++Numeric date: ``726842'' for any time on Wed Jan 9, 1991. ++@item J ++Julian date/time: ``2448265.75'' for 6:00am Wed Jan 9, 1991. ++@item j ++Julian date: ``2448266'' for any time on Wed Jan 9, 1991. ++@item U ++Unix time: ``663400800'' for 6:00am Wed Jan 9, 1991. ++@item X ++Brackets suppression. An ``X'' at the front of the format ++causes the surrounding @w{@samp{< >}} delimiters to be omitted ++when formatting dates. Note that the brackets are still ++required for algebraic entry. ++@end table ++ ++If ``SS'' or ``BS'' (optional seconds) is preceded by a colon, the ++colon is also omitted if the seconds part is zero. ++ ++If ``bb,'' ``bbb'' or ``bbbb'' or their upper-case equivalents ++appear in the format, then negative year numbers are displayed ++without a minus sign. Note that ``aa'' and ``bb'' are mutually ++exclusive. Some typical usages would be @samp{YYYY AABB}; ++@samp{AAAYYYYBBB}; @samp{YYYYBBB}. ++ ++The formats ``YY,'' ``YYYY,'' ``MM,'' ``DD,'' ``ddd,'' ``hh,'' ``HH,'' ++``mm,'' ``ss,'' and ``SS'' actually match any number of digits during ++reading unless several of these codes are strung together with no ++punctuation in between, in which case the input must have exactly as ++many digits as there are letters in the format. ++ ++The ``j,'' ``J,'' and ``U'' formats do not make any time zone ++adjustment. They effectively use @samp{julian(x,0)} and ++@samp{unixtime(x,0)} to make the conversion; @pxref{Date Arithmetic}. ++ ++@node Free-Form Dates, Standard Date Formats, Date Formatting Codes, Date Formats ++@subsubsection Free-Form Dates ++ ++@noindent ++When reading a date form during algebraic entry, Calc falls back ++on the algorithm described here if the input does not exactly ++match the current date format. This algorithm generally ++``does the right thing'' and you don't have to worry about it, ++but it is described here in full detail for the curious. ++ ++Calc does not distinguish between upper- and lower-case letters ++while interpreting dates. ++ ++First, the time portion, if present, is located somewhere in the ++text and then removed. The remaining text is then interpreted as ++the date. ++ ++A time is of the form @samp{hh:mm:ss}, possibly with the seconds ++part omitted and possibly with an AM/PM indicator added to indicate ++12-hour time. If the AM/PM is present, the minutes may also be ++omitted. The AM/PM part may be any of the words @samp{am}, ++@samp{pm}, @samp{noon}, or @samp{midnight}; each of these may be ++abbreviated to one letter, and the alternate forms @samp{a.m.}, ++@samp{p.m.}, and @samp{mid} are also understood. Obviously ++@samp{noon} and @samp{midnight} are allowed only on 12:00:00. ++The words @samp{noon}, @samp{mid}, and @samp{midnight} are also ++recognized with no number attached. ++ ++If there is no AM/PM indicator, the time is interpreted in 24-hour ++format. ++ ++To read the date portion, all words and numbers are isolated ++from the string; other characters are ignored. All words must ++be either month names or day-of-week names (the latter of which ++are ignored). Names can be written in full or as three-letter ++abbreviations. ++ ++Large numbers, or numbers with @samp{+} or @samp{-} signs, ++are interpreted as years. If one of the other numbers is ++greater than 12, then that must be the day and the remaining ++number in the input is therefore the month. Otherwise, Calc ++assumes the month, day and year are in the same order that they ++appear in the current date format. If the year is omitted, the ++current year is taken from the system clock. ++ ++If there are too many or too few numbers, or any unrecognizable ++words, then the input is rejected. ++ ++If there are any large numbers (of five digits or more) other than ++the year, they are ignored on the assumption that they are something ++like Julian dates that were included along with the traditional ++date components when the date was formatted. ++ ++One of the words @samp{ad}, @samp{a.d.}, @samp{bc}, or @samp{b.c.} ++may optionally be used; the latter two are equivalent to a ++minus sign on the year value. ++ ++If you always enter a four-digit year, and use a name instead ++of a number for the month, there is no danger of ambiguity. ++ ++@node Standard Date Formats, , Free-Form Dates, Date Formats ++@subsubsection Standard Date Formats ++ ++@noindent ++There are actually ten standard date formats, numbered 0 through 9. ++Entering a blank line at the @kbd{d d} command's prompt gives ++you format number 1, Calc's usual format. You can enter any digit ++to select the other formats. ++ ++To create your own standard date formats, give a numeric prefix ++argument from 0 to 9 to the @w{@kbd{d d}} command. The format you ++enter will be recorded as the new standard format of that ++number, as well as becoming the new current date format. ++You can save your formats permanently with the @w{@kbd{m m}} ++command (@pxref{Mode Settings}). ++ ++@table @asis ++@item 0 ++@samp{N} (Numerical format) ++@item 1 ++@samp{Www Mmm D, YYYY} (American format) ++@item 2 ++@samp{D Mmm YYYY<, h:mm:SS>} (European format) ++@item 3 ++@samp{Www Mmm BD< hh:mm:ss> YYYY} (Unix written date format) ++@item 4 ++@samp{M/D/Y< H:mm:SSpp>} (American slashed format) ++@item 5 ++@samp{D.M.Y< h:mm:SS>} (European dotted format) ++@item 6 ++@samp{M-D-Y< H:mm:SSpp>} (American dashed format) ++@item 7 ++@samp{D-M-Y< h:mm:SS>} (European dashed format) ++@item 8 ++@samp{j<, h:mm:ss>} (Julian day plus time) ++@item 9 ++@samp{YYddd< hh:mm:ss>} (Year-day format) ++@end table ++ ++@node Truncating the Stack, Justification, Date Formats, Display Modes ++@subsection Truncating the Stack ++ ++@noindent ++@kindex d t ++@pindex calc-truncate-stack ++@cindex Truncating the stack ++@cindex Narrowing the stack ++The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@: ++line that marks the top-of-stack up or down in the Calculator buffer. ++The number right above that line is considered to the be at the top of ++the stack. Any numbers below that line are ``hidden'' from all stack ++operations (although still visible to the user). This is similar to the ++Emacs ``narrowing'' feature, except that the values below the @samp{.} ++are @emph{visible}, just temporarily frozen. This feature allows you to ++keep several independent calculations running at once in different parts ++of the stack, or to apply a certain command to an element buried deep in ++the stack. ++ ++Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor ++is on. Thus, this line and all those below it become hidden. To un-hide ++these lines, move down to the end of the buffer and press @w{@kbd{d t}}. ++With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the ++bottom @expr{n} values in the buffer. With a negative argument, it hides ++all but the top @expr{n} values. With an argument of zero, it hides zero ++values, i.e., moves the @samp{.} all the way down to the bottom. ++ ++@kindex d [ ++@pindex calc-truncate-up ++@kindex d ] ++@pindex calc-truncate-down ++The @kbd{d [} (@code{calc-truncate-up}) and @kbd{d ]} ++(@code{calc-truncate-down}) commands move the @samp{.} up or down one ++line at a time (or several lines with a prefix argument). ++ ++@node Justification, Labels, Truncating the Stack, Display Modes ++@subsection Justification ++ ++@noindent ++@kindex d < ++@pindex calc-left-justify ++@kindex d = ++@pindex calc-center-justify ++@kindex d > ++@pindex calc-right-justify ++Values on the stack are normally left-justified in the window. You can ++control this arrangement by typing @kbd{d <} (@code{calc-left-justify}), ++@kbd{d >} (@code{calc-right-justify}), or @kbd{d =} ++(@code{calc-center-justify}). For example, in Right-Justification mode, ++stack entries are displayed flush-right against the right edge of the ++window. ++ ++If you change the width of the Calculator window you may have to type ++@kbd{d @key{SPC}} (@code{calc-refresh}) to re-align right-justified or centered ++text. ++ ++Right-justification is especially useful together with fixed-point ++notation (see @code{d f}; @code{calc-fix-notation}). With these modes ++together, the decimal points on numbers will always line up. ++ ++With a numeric prefix argument, the justification commands give you ++a little extra control over the display. The argument specifies the ++horizontal ``origin'' of a display line. It is also possible to ++specify a maximum line width using the @kbd{d b} command (@pxref{Normal ++Language Modes}). For reference, the precise rules for formatting and ++breaking lines are given below. Notice that the interaction between ++origin and line width is slightly different in each justification ++mode. ++ ++In Left-Justified mode, the line is indented by a number of spaces ++given by the origin (default zero). If the result is longer than the ++maximum line width, if given, or too wide to fit in the Calc window ++otherwise, then it is broken into lines which will fit; each broken ++line is indented to the origin. ++ ++In Right-Justified mode, lines are shifted right so that the rightmost ++character is just before the origin, or just before the current ++window width if no origin was specified. If the line is too long ++for this, then it is broken; the current line width is used, if ++specified, or else the origin is used as a width if that is ++specified, or else the line is broken to fit in the window. ++ ++In Centering mode, the origin is the column number of the center of ++each stack entry. If a line width is specified, lines will not be ++allowed to go past that width; Calc will either indent less or ++break the lines if necessary. If no origin is specified, half the ++line width or Calc window width is used. ++ ++Note that, in each case, if line numbering is enabled the display ++is indented an additional four spaces to make room for the line ++number. The width of the line number is taken into account when ++positioning according to the current Calc window width, but not ++when positioning by explicit origins and widths. In the latter ++case, the display is formatted as specified, and then uniformly ++shifted over four spaces to fit the line numbers. ++ ++@node Labels, , Justification, Display Modes ++@subsection Labels ++ ++@noindent ++@kindex d @{ ++@pindex calc-left-label ++The @kbd{d @{} (@code{calc-left-label}) command prompts for a string, ++then displays that string to the left of every stack entry. If the ++entries are left-justified (@pxref{Justification}), then they will ++appear immediately after the label (unless you specified an origin ++greater than the length of the label). If the entries are centered ++or right-justified, the label appears on the far left and does not ++affect the horizontal position of the stack entry. ++ ++Give a blank string (with @kbd{d @{ @key{RET}}) to turn the label off. ++ ++@kindex d @} ++@pindex calc-right-label ++The @kbd{d @}} (@code{calc-right-label}) command similarly adds a ++label on the righthand side. It does not affect positioning of ++the stack entries unless they are right-justified. Also, if both ++a line width and an origin are given in Right-Justified mode, the ++stack entry is justified to the origin and the righthand label is ++justified to the line width. ++ ++One application of labels would be to add equation numbers to ++formulas you are manipulating in Calc and then copying into a ++document (possibly using Embedded mode). The equations would ++typically be centered, and the equation numbers would be on the ++left or right as you prefer. ++ ++@node Language Modes, Modes Variable, Display Modes, Mode Settings ++@section Language Modes ++ ++@noindent ++The commands in this section change Calc to use a different notation for ++entry and display of formulas, corresponding to the conventions of some ++other common language such as Pascal or La@TeX{}. Objects displayed on the ++stack or yanked from the Calculator to an editing buffer will be formatted ++in the current language; objects entered in algebraic entry or yanked from ++another buffer will be interpreted according to the current language. ++ ++The current language has no effect on things written to or read from the ++trail buffer, nor does it affect numeric entry. Only algebraic entry is ++affected. You can make even algebraic entry ignore the current language ++and use the standard notation by giving a numeric prefix, e.g., @kbd{C-u '}. ++ ++For example, suppose the formula @samp{2*a[1] + atan(a[2])} occurs in a C ++program; elsewhere in the program you need the derivatives of this formula ++with respect to @samp{a[1]} and @samp{a[2]}. First, type @kbd{d C} ++to switch to C notation. Now use @code{C-u C-x * g} to grab the formula ++into the Calculator, @kbd{a d a[1] @key{RET}} to differentiate with respect ++to the first variable, and @kbd{C-x * y} to yank the formula for the derivative ++back into your C program. Press @kbd{U} to undo the differentiation and ++repeat with @kbd{a d a[2] @key{RET}} for the other derivative. ++ ++Without being switched into C mode first, Calc would have misinterpreted ++the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that ++@code{atan} was equivalent to Calc's built-in @code{arctan} function, ++and would have written the formula back with notations (like implicit ++multiplication) which would not have been valid for a C program. ++ ++As another example, suppose you are maintaining a C program and a La@TeX{} ++document, each of which needs a copy of the same formula. You can grab the ++formula from the program in C mode, switch to La@TeX{} mode, and yank the ++formula into the document in La@TeX{} math-mode format. ++ ++Language modes are selected by typing the letter @kbd{d} followed by a ++shifted letter key. ++ ++@menu ++* Normal Language Modes:: ++* C FORTRAN Pascal:: ++* TeX and LaTeX Language Modes:: ++* Eqn Language Mode:: ++* Yacas Language Mode:: ++* Maxima Language Mode:: ++* Giac Language Mode:: ++* Mathematica Language Mode:: ++* Maple Language Mode:: ++* Compositions:: ++* Syntax Tables:: ++@end menu ++ ++@node Normal Language Modes, C FORTRAN Pascal, Language Modes, Language Modes ++@subsection Normal Language Modes ++ ++@noindent ++@kindex d N ++@pindex calc-normal-language ++The @kbd{d N} (@code{calc-normal-language}) command selects the usual ++notation for Calc formulas, as described in the rest of this manual. ++Matrices are displayed in a multi-line tabular format, but all other ++objects are written in linear form, as they would be typed from the ++keyboard. ++ ++@kindex d O ++@pindex calc-flat-language ++@cindex Matrix display ++The @kbd{d O} (@code{calc-flat-language}) command selects a language ++identical with the normal one, except that matrices are written in ++one-line form along with everything else. In some applications this ++form may be more suitable for yanking data into other buffers. ++ ++@kindex d b ++@pindex calc-line-breaking ++@cindex Line breaking ++@cindex Breaking up long lines ++Even in one-line mode, long formulas or vectors will still be split ++across multiple lines if they exceed the width of the Calculator window. ++The @kbd{d b} (@code{calc-line-breaking}) command turns this line-breaking ++feature on and off. (It works independently of the current language.) ++If you give a numeric prefix argument of five or greater to the @kbd{d b} ++command, that argument will specify the line width used when breaking ++long lines. ++ ++@kindex d B ++@pindex calc-big-language ++The @kbd{d B} (@code{calc-big-language}) command selects a language ++which uses textual approximations to various mathematical notations, ++such as powers, quotients, and square roots: ++ ++@example ++ ____________ ++ | a + 1 2 ++ | ----- + c ++\| b ++@end example ++ ++@noindent ++in place of @samp{sqrt((a+1)/b + c^2)}. ++ ++Subscripts like @samp{a_i} are displayed as actual subscripts in Big ++mode. Double subscripts, @samp{a_i_j} (@samp{subscr(subscr(a, i), j)}) ++are displayed as @samp{a} with subscripts separated by commas: ++@samp{i, j}. They must still be entered in the usual underscore ++notation. ++ ++One slight ambiguity of Big notation is that ++ ++@example ++ 3 ++- - ++ 4 ++@end example ++ ++@noindent ++can represent either the negative rational number @expr{-3:4}, or the ++actual expression @samp{-(3/4)}; but the latter formula would normally ++never be displayed because it would immediately be evaluated to ++@expr{-3:4} or @expr{-0.75}, so this ambiguity is not a problem in ++typical use. ++ ++Non-decimal numbers are displayed with subscripts. Thus there is no ++way to tell the difference between @samp{16#C2} and @samp{C2_16}, ++though generally you will know which interpretation is correct. ++Logarithms @samp{log(x,b)} and @samp{log10(x)} also use subscripts ++in Big mode. ++ ++In Big mode, stack entries often take up several lines. To aid ++readability, stack entries are separated by a blank line in this mode. ++You may find it useful to expand the Calc window's height using ++@kbd{C-x ^} (@code{enlarge-window}) or to make the Calc window the only ++one on the screen with @kbd{C-x 1} (@code{delete-other-windows}). ++ ++Long lines are currently not rearranged to fit the window width in ++Big mode, so you may need to use the @kbd{<} and @kbd{>} keys ++to scroll across a wide formula. For really big formulas, you may ++even need to use @kbd{@{} and @kbd{@}} to scroll up and down. ++ ++@kindex d U ++@pindex calc-unformatted-language ++The @kbd{d U} (@code{calc-unformatted-language}) command altogether disables ++the use of operator notation in formulas. In this mode, the formula ++shown above would be displayed: ++ ++@example ++sqrt(add(div(add(a, 1), b), pow(c, 2))) ++@end example ++ ++These four modes differ only in display format, not in the format ++expected for algebraic entry. The standard Calc operators work in ++all four modes, and unformatted notation works in any language mode ++(except that Mathematica mode expects square brackets instead of ++parentheses). ++ ++@node C FORTRAN Pascal, TeX and LaTeX Language Modes, Normal Language Modes, Language Modes ++@subsection C, FORTRAN, and Pascal Modes ++ ++@noindent ++@kindex d C ++@pindex calc-c-language ++@cindex C language ++The @kbd{d C} (@code{calc-c-language}) command selects the conventions ++of the C language for display and entry of formulas. This differs from ++the normal language mode in a variety of (mostly minor) ways. In ++particular, C language operators and operator precedences are used in ++place of Calc's usual ones. For example, @samp{a^b} means @samp{xor(a,b)} ++in C mode; a value raised to a power is written as a function call, ++@samp{pow(a,b)}. ++ ++In C mode, vectors and matrices use curly braces instead of brackets. ++Octal and hexadecimal values are written with leading @samp{0} or @samp{0x} ++rather than using the @samp{#} symbol. Array subscripting is ++translated into @code{subscr} calls, so that @samp{a[i]} in C ++mode is the same as @samp{a_i} in Normal mode. Assignments ++turn into the @code{assign} function, which Calc normally displays ++using the @samp{:=} symbol. ++ ++The variables @code{pi} and @code{e} would be displayed @samp{pi} ++and @samp{e} in Normal mode, but in C mode they are displayed as ++@samp{M_PI} and @samp{M_E}, corresponding to the names of constants ++typically provided in the @file{} header. Functions whose ++names are different in C are translated automatically for entry and ++display purposes. For example, entering @samp{asin(x)} will push the ++formula @samp{arcsin(x)} onto the stack; this formula will be displayed ++as @samp{asin(x)} as long as C mode is in effect. ++ ++@kindex d P ++@pindex calc-pascal-language ++@cindex Pascal language ++The @kbd{d P} (@code{calc-pascal-language}) command selects Pascal ++conventions. Like C mode, Pascal mode interprets array brackets and uses ++a different table of operators. Hexadecimal numbers are entered and ++displayed with a preceding dollar sign. (Thus the regular meaning of ++@kbd{$2} during algebraic entry does not work in Pascal mode, though ++@kbd{$} (and @kbd{$$}, etc.) not followed by digits works the same as ++always.) No special provisions are made for other non-decimal numbers, ++vectors, and so on, since there is no universally accepted standard way ++of handling these in Pascal. ++ ++@kindex d F ++@pindex calc-fortran-language ++@cindex FORTRAN language ++The @kbd{d F} (@code{calc-fortran-language}) command selects FORTRAN ++conventions. Various function names are transformed into FORTRAN ++equivalents. Vectors are written as @samp{/1, 2, 3/}, and may be ++entered this way or using square brackets. Since FORTRAN uses round ++parentheses for both function calls and array subscripts, Calc displays ++both in the same way; @samp{a(i)} is interpreted as a function call ++upon reading, and subscripts must be entered as @samp{subscr(a, i)}. ++If the variable @code{a} has been declared to have type ++@code{vector} or @code{matrix}, however, then @samp{a(i)} will be ++parsed as a subscript. (@xref{Declarations}.) Usually it doesn't ++matter, though; if you enter the subscript expression @samp{a(i)} and ++Calc interprets it as a function call, you'll never know the difference ++unless you switch to another language mode or replace @code{a} with an ++actual vector (or unless @code{a} happens to be the name of a built-in ++function!). ++ ++Underscores are allowed in variable and function names in all of these ++language modes. The underscore here is equivalent to the @samp{#} in ++Normal mode, or to hyphens in the underlying Emacs Lisp variable names. ++ ++FORTRAN and Pascal modes normally do not adjust the case of letters in ++formulas. Most built-in Calc names use lower-case letters. If you use a ++positive numeric prefix argument with @kbd{d P} or @kbd{d F}, these ++modes will use upper-case letters exclusively for display, and will ++convert to lower-case on input. With a negative prefix, these modes ++convert to lower-case for display and input. ++ ++@node TeX and LaTeX Language Modes, Eqn Language Mode, C FORTRAN Pascal, Language Modes ++@subsection @TeX{} and La@TeX{} Language Modes ++ ++@noindent ++@kindex d T ++@pindex calc-tex-language ++@cindex TeX language ++@kindex d L ++@pindex calc-latex-language ++@cindex LaTeX language ++The @kbd{d T} (@code{calc-tex-language}) command selects the conventions ++of ``math mode'' in Donald Knuth's @TeX{} typesetting language, ++and the @kbd{d L} (@code{calc-latex-language}) command selects the ++conventions of ``math mode'' in La@TeX{}, a typesetting language that ++uses @TeX{} as its formatting engine. Calc's La@TeX{} language mode can ++read any formula that the @TeX{} language mode can, although La@TeX{} ++mode may display it differently. ++ ++Formulas are entered and displayed in the appropriate notation; ++@texline @math{\sin(a/b)} ++@infoline @expr{sin(a/b)} ++will appear as @samp{\sin\left( @{a \over b@} \right)} in @TeX{} mode and ++@samp{\sin\left(\frac@{a@}@{b@}\right)} in La@TeX{} mode. ++Math formulas are often enclosed by @samp{$ $} signs in @TeX{} and ++La@TeX{}; these should be omitted when interfacing with Calc. To Calc, ++the @samp{$} sign has the same meaning it always does in algebraic ++formulas (a reference to an existing entry on the stack). ++ ++Complex numbers are displayed as in @samp{3 + 4i}. Fractions and ++quotients are written using @code{\over} in @TeX{} mode (as in ++@code{@{a \over b@}}) and @code{\frac} in La@TeX{} mode (as in ++@code{\frac@{a@}@{b@}}); binomial coefficients are written with ++@code{\choose} in @TeX{} mode (as in @code{@{a \choose b@}}) and ++@code{\binom} in La@TeX{} mode (as in @code{\binom@{a@}@{b@}}). ++Interval forms are written with @code{\ldots}, and error forms are ++written with @code{\pm}. Absolute values are written as in ++@samp{|x + 1|}, and the floor and ceiling functions are written with ++@code{\lfloor}, @code{\rfloor}, etc. The words @code{\left} and ++@code{\right} are ignored when reading formulas in @TeX{} and La@TeX{} ++modes. Both @code{inf} and @code{uinf} are written as @code{\infty}; ++when read, @code{\infty} always translates to @code{inf}. ++ ++Function calls are written the usual way, with the function name followed ++by the arguments in parentheses. However, functions for which @TeX{} ++and La@TeX{} have special names (like @code{\sin}) will use curly braces ++instead of parentheses for very simple arguments. During input, curly ++braces and parentheses work equally well for grouping, but when the ++document is formatted the curly braces will be invisible. Thus the ++printed result is ++@texline @math{\sin{2 x}} ++@infoline @expr{sin 2x} ++but ++@texline @math{\sin(2 + x)}. ++@infoline @expr{sin(2 + x)}. ++ ++Function and variable names not treated specially by @TeX{} and La@TeX{} ++are simply written out as-is, which will cause them to come out in ++italic letters in the printed document. If you invoke @kbd{d T} or ++@kbd{d L} with a positive numeric prefix argument, names of more than ++one character will instead be enclosed in a protective commands that ++will prevent them from being typeset in the math italics; they will be ++written @samp{\hbox@{@var{name}@}} in @TeX{} mode and ++@samp{\text@{@var{name}@}} in La@TeX{} mode. The ++@samp{\hbox@{ @}} and @samp{\text@{ @}} notations are ignored during ++reading. If you use a negative prefix argument, such function names are ++written @samp{\@var{name}}, and function names that begin with @code{\} during ++reading have the @code{\} removed. (Note that in this mode, long ++variable names are still written with @code{\hbox} or @code{\text}. ++However, you can always make an actual variable name like @code{\bar} in ++any @TeX{} mode.) ++ ++During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced ++by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and ++@code{\bmatrix}. In La@TeX{} mode this also applies to ++@samp{\begin@{matrix@} ... \end@{matrix@}}, ++@samp{\begin@{bmatrix@} ... \end@{bmatrix@}}, ++@samp{\begin@{pmatrix@} ... \end@{pmatrix@}}, as well as ++@samp{\begin@{smallmatrix@} ... \end@{smallmatrix@}}. ++The symbol @samp{&} is interpreted as a comma, ++and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons. ++During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}} ++format in @TeX{} mode and in ++@samp{\begin@{pmatrix@} a & b \\ c & d \end@{pmatrix@}} format in ++La@TeX{} mode; you may need to edit this afterwards to change to your ++preferred matrix form. If you invoke @kbd{d T} or @kbd{d L} with an ++argument of 2 or -2, then matrices will be displayed in two-dimensional ++form, such as ++ ++@example ++\begin@{pmatrix@} ++a & b \\ ++c & d ++\end@{pmatrix@} ++@end example ++ ++@noindent ++This may be convenient for isolated matrices, but could lead to ++expressions being displayed like ++ ++@example ++\begin@{pmatrix@} \times x ++a & b \\ ++c & d ++\end@{pmatrix@} ++@end example ++ ++@noindent ++While this wouldn't bother Calc, it is incorrect La@TeX{}. ++(Similarly for @TeX{}.) ++ ++Accents like @code{\tilde} and @code{\bar} translate into function ++calls internally (@samp{tilde(x)}, @samp{bar(x)}). The @code{\underline} ++sequence is treated as an accent. The @code{\vec} accent corresponds ++to the function name @code{Vec}, because @code{vec} is the name of ++a built-in Calc function. The following table shows the accents ++in Calc, @TeX{}, La@TeX{} and @dfn{eqn} (described in the next section): ++ ++@ignore ++@iftex ++@begingroup ++@let@calcindexershow=@calcindexernoshow @c Suppress marginal notes ++@let@calcindexersh=@calcindexernoshow ++@end iftex ++@starindex ++@end ignore ++@tindex acute ++@ignore ++@starindex ++@end ignore ++@tindex Acute ++@ignore ++@starindex ++@end ignore ++@tindex bar ++@ignore ++@starindex ++@end ignore ++@tindex Bar ++@ignore ++@starindex ++@end ignore ++@tindex breve ++@ignore ++@starindex ++@end ignore ++@tindex Breve ++@ignore ++@starindex ++@end ignore ++@tindex check ++@ignore ++@starindex ++@end ignore ++@tindex Check ++@ignore ++@starindex ++@end ignore ++@tindex dddot ++@ignore ++@starindex ++@end ignore ++@tindex ddddot ++@ignore ++@starindex ++@end ignore ++@tindex dot ++@ignore ++@starindex ++@end ignore ++@tindex Dot ++@ignore ++@starindex ++@end ignore ++@tindex dotdot ++@ignore ++@starindex ++@end ignore ++@tindex DotDot ++@ignore ++@starindex ++@end ignore ++@tindex dyad ++@ignore ++@starindex ++@end ignore ++@tindex grave ++@ignore ++@starindex ++@end ignore ++@tindex Grave ++@ignore ++@starindex ++@end ignore ++@tindex hat ++@ignore ++@starindex ++@end ignore ++@tindex Hat ++@ignore ++@starindex ++@end ignore ++@tindex Prime ++@ignore ++@starindex ++@end ignore ++@tindex tilde ++@ignore ++@starindex ++@end ignore ++@tindex Tilde ++@ignore ++@starindex ++@end ignore ++@tindex under ++@ignore ++@starindex ++@end ignore ++@tindex Vec ++@ignore ++@starindex ++@end ignore ++@tindex VEC ++@ignore ++@iftex ++@endgroup ++@end iftex ++@end ignore ++@example ++Calc TeX LaTeX eqn ++---- --- ----- --- ++acute \acute \acute ++Acute \Acute ++bar \bar \bar bar ++Bar \Bar ++breve \breve \breve ++Breve \Breve ++check \check \check ++Check \Check ++dddot \dddot ++ddddot \ddddot ++dot \dot \dot dot ++Dot \Dot ++dotdot \ddot \ddot dotdot ++DotDot \Ddot ++dyad dyad ++grave \grave \grave ++Grave \Grave ++hat \hat \hat hat ++Hat \Hat ++Prime prime ++tilde \tilde \tilde tilde ++Tilde \Tilde ++under \underline \underline under ++Vec \vec \vec vec ++VEC \Vec ++@end example ++ ++The @samp{=>} (evaluates-to) operator appears as a @code{\to} symbol: ++@samp{@{@var{a} \to @var{b}@}}. @TeX{} defines @code{\to} as an ++alias for @code{\rightarrow}. However, if the @samp{=>} is the ++top-level expression being formatted, a slightly different notation ++is used: @samp{\evalto @var{a} \to @var{b}}. The @code{\evalto} ++word is ignored by Calc's input routines, and is undefined in @TeX{}. ++You will typically want to include one of the following definitions ++at the top of a @TeX{} file that uses @code{\evalto}: ++ ++@example ++\def\evalto@{@} ++\def\evalto#1\to@{@} ++@end example ++ ++The first definition formats evaluates-to operators in the usual ++way. The second causes only the @var{b} part to appear in the ++printed document; the @var{a} part and the arrow are hidden. ++Another definition you may wish to use is @samp{\let\to=\Rightarrow} ++which causes @code{\to} to appear more like Calc's @samp{=>} symbol. ++@xref{Evaluates-To Operator}, for a discussion of @code{evalto}. ++ ++The complete set of @TeX{} control sequences that are ignored during ++reading is: ++ ++@example ++\hbox \mbox \text \left \right ++\, \> \: \; \! \quad \qquad \hfil \hfill ++\displaystyle \textstyle \dsize \tsize ++\scriptstyle \scriptscriptstyle \ssize \ssize ++\rm \bf \it \sl \roman \bold \italic \slanted ++\cal \mit \Cal \Bbb \frak \goth ++\evalto ++@end example ++ ++Note that, because these symbols are ignored, reading a @TeX{} or ++La@TeX{} formula into Calc and writing it back out may lose spacing and ++font information. ++ ++Also, the ``discretionary multiplication sign'' @samp{\*} is read ++the same as @samp{*}. ++ ++@ifnottex ++The @TeX{} version of this manual includes some printed examples at the ++end of this section. ++@end ifnottex ++@iftex ++Here are some examples of how various Calc formulas are formatted in @TeX{}: ++ ++@example ++@group ++sin(a^2 / b_i) ++\sin\left( {a^2 \over b_i} \right) ++@end group ++@end example ++@tex ++$$ \sin\left( a^2 \over b_i \right) $$ ++@end tex ++@sp 1 ++ ++@example ++@group ++[(3, 4), 3:4, 3 +/- 4, [3 .. inf)] ++[3 + 4i, @{3 \over 4@}, 3 \pm 4, [3 \ldots \infty)] ++@end group ++@end example ++@tex ++\turnoffactive ++$$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$ ++@end tex ++@sp 1 ++ ++@example ++@group ++[abs(a), abs(a / b), floor(a), ceil(a / b)] ++[|a|, \left| a \over b \right|, ++ \lfloor a \rfloor, \left\lceil a \over b \right\rceil] ++@end group ++@end example ++@tex ++$$ [|a|, \left| a \over b \right|, ++ \lfloor a \rfloor, \left\lceil a \over b \right\rceil] $$ ++@end tex ++@sp 1 ++ ++@example ++@group ++[sin(a), sin(2 a), sin(2 + a), sin(a / b)] ++[\sin@{a@}, \sin@{2 a@}, \sin(2 + a), ++ \sin\left( @{a \over b@} \right)] ++@end group ++@end example ++@tex ++\turnoffactive ++$$ [\sin{a}, \sin{2 a}, \sin(2 + a), \sin\left( {a \over b} \right)] $$ ++@end tex ++@sp 2 ++ ++First with plain @kbd{d T}, then with @kbd{C-u d T}, then finally with ++@kbd{C-u - d T} (using the example definition ++@samp{\def\foo#1@{\tilde F(#1)@}}: ++ ++@example ++@group ++[f(a), foo(bar), sin(pi)] ++[f(a), foo(bar), \sin{\pi}] ++[f(a), \hbox@{foo@}(\hbox@{bar@}), \sin@{\pi@}] ++[f(a), \foo@{\hbox@{bar@}@}, \sin@{\pi@}] ++@end group ++@end example ++@tex ++$$ [f(a), foo(bar), \sin{\pi}] $$ ++$$ [f(a), \hbox{foo}(\hbox{bar}), \sin{\pi}] $$ ++$$ [f(a), \tilde F(\hbox{bar}), \sin{\pi}] $$ ++@end tex ++@sp 2 ++ ++First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}: ++ ++@example ++@group ++2 + 3 => 5 ++\evalto 2 + 3 \to 5 ++@end group ++@end example ++@tex ++\turnoffactive ++$$ 2 + 3 \to 5 $$ ++$$ 5 $$ ++@end tex ++@sp 2 ++ ++First with standard @code{\to}, then with @samp{\let\to\Rightarrow}: ++ ++@example ++@group ++[2 + 3 => 5, a / 2 => (b + c) / 2] ++[@{2 + 3 \to 5@}, @{@{a \over 2@} \to @{b + c \over 2@}@}] ++@end group ++@end example ++@tex ++\turnoffactive ++$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$ ++{\let\to\Rightarrow ++$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$} ++@end tex ++@sp 2 ++ ++Matrices normally, then changing @code{\matrix} to @code{\pmatrix}: ++ ++@example ++@group ++[ [ a / b, 0 ], [ 0, 2^(x + 1) ] ] ++\matrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} ++\pmatrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} ++@end group ++@end example ++@tex ++\turnoffactive ++$$ \matrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ ++$$ \pmatrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ ++@end tex ++@sp 2 ++@end iftex ++ ++@node Eqn Language Mode, Yacas Language Mode, TeX and LaTeX Language Modes, Language Modes ++@subsection Eqn Language Mode ++ ++@noindent ++@kindex d E ++@pindex calc-eqn-language ++@dfn{Eqn} is another popular formatter for math formulas. It is ++designed for use with the TROFF text formatter, and comes standard ++with many versions of Unix. The @kbd{d E} (@code{calc-eqn-language}) ++command selects @dfn{eqn} notation. ++ ++The @dfn{eqn} language's main idiosyncrasy is that whitespace plays ++a significant part in the parsing of the language. For example, ++@samp{sqrt x+1 + y} treats @samp{x+1} as the argument of the ++@code{sqrt} operator. @dfn{Eqn} also understands more conventional ++grouping using curly braces: @samp{sqrt@{x+1@} + y}. Braces are ++required only when the argument contains spaces. ++ ++In Calc's @dfn{eqn} mode, however, curly braces are required to ++delimit arguments of operators like @code{sqrt}. The first of the ++above examples would treat only the @samp{x} as the argument of ++@code{sqrt}, and in fact @samp{sin x+1} would be interpreted as ++@samp{sin * x + 1}, because @code{sin} is not a special operator ++in the @dfn{eqn} language. If you always surround the argument ++with curly braces, Calc will never misunderstand. ++ ++Calc also understands parentheses as grouping characters. Another ++peculiarity of @dfn{eqn}'s syntax makes it advisable to separate ++words with spaces from any surrounding characters that aren't curly ++braces, so Calc writes @samp{sin ( x + y )} in @dfn{eqn} mode. ++(The spaces around @code{sin} are important to make @dfn{eqn} ++recognize that @code{sin} should be typeset in a roman font, and ++the spaces around @code{x} and @code{y} are a good idea just in ++case the @dfn{eqn} document has defined special meanings for these ++names, too.) ++ ++Powers and subscripts are written with the @code{sub} and @code{sup} ++operators, respectively. Note that the caret symbol @samp{^} is ++treated the same as a space in @dfn{eqn} mode, as is the @samp{~} ++symbol (these are used to introduce spaces of various widths into ++the typeset output of @dfn{eqn}). ++ ++As in La@TeX{} mode, Calc's formatter omits parentheses around the ++arguments of functions like @code{ln} and @code{sin} if they are ++``simple-looking''; in this case Calc surrounds the argument with ++braces, separated by a @samp{~} from the function name: @samp{sin~@{x@}}. ++ ++Font change codes (like @samp{roman @var{x}}) and positioning codes ++(like @samp{~} and @samp{down @var{n} @var{x}}) are ignored by the ++@dfn{eqn} reader. Also ignored are the words @code{left}, @code{right}, ++@code{mark}, and @code{lineup}. Quotation marks in @dfn{eqn} mode input ++are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to ++@samp{sqrt @{1+x@}}; this is only an approximation to the true meaning ++of quotes in @dfn{eqn}, but it is good enough for most uses. ++ ++Accent codes (@samp{@var{x} dot}) are handled by treating them as ++function calls (@samp{dot(@var{x})}) internally. ++@xref{TeX and LaTeX Language Modes}, for a table of these accent ++functions. The @code{prime} accent is treated specially if it occurs on ++a variable or function name: @samp{f prime prime @w{( x prime )}} is ++stored internally as @samp{f'@w{'}(x')}. For example, taking the ++derivative of @samp{f(2 x)} with @kbd{a d x} will produce @samp{2 f'(2 ++x)}, which @dfn{eqn} mode will display as @samp{2 f prime ( 2 x )}. ++ ++Assignments are written with the @samp{<-} (left-arrow) symbol, ++and @code{evalto} operators are written with @samp{->} or ++@samp{evalto ... ->} (@pxref{TeX and LaTeX Language Modes}, for a discussion ++of this). The regular Calc symbols @samp{:=} and @samp{=>} are also ++recognized for these operators during reading. ++ ++Vectors in @dfn{eqn} mode use regular Calc square brackets, but ++matrices are formatted as @samp{matrix @{ ccol @{ a above b @} ... @}}. ++The words @code{lcol} and @code{rcol} are recognized as synonyms ++for @code{ccol} during input, and are generated instead of @code{ccol} ++if the matrix justification mode so specifies. ++ ++@node Yacas Language Mode, Maxima Language Mode, Eqn Language Mode, Language Modes ++@subsection Yacas Language Mode ++ ++@noindent ++@kindex d Y ++@pindex calc-yacas-language ++@cindex Yacas language ++The @kbd{d Y} (@code{calc-yacas-language}) command selects the ++conventions of Yacas, a free computer algebra system. While the ++operators and functions in Yacas are similar to those of Calc, the names ++of built-in functions in Yacas are capitalized. The Calc formula ++@samp{sin(2 x)}, for example, is entered and displayed @samp{Sin(2 x)} ++in Yacas mode, and `@samp{arcsin(x^2)} is @samp{ArcSin(x^2)} in Yacas ++mode. Complex numbers are written are written @samp{3 + 4 I}. ++The standard special constants are written @code{Pi}, @code{E}, ++@code{I}, @code{GoldenRatio} and @code{Gamma}. @code{Infinity} ++represents both @code{inf} and @code{uinf}, and @code{Undefined} ++represents @code{nan}. ++ ++Certain operators on functions, such as @code{D} for differentiation ++and @code{Integrate} for integration, take a prefix form in Yacas. For ++example, the derivative of @w{@samp{e^x sin(x)}} can be computed with ++@w{@samp{D(x) Exp(x)*Sin(x)}}. ++ ++Other notable differences between Yacas and standard Calc expressions ++are that vectors and matrices use curly braces in Yacas, and subscripts ++use square brackets. If, for example, @samp{A} represents the list ++@samp{@{a,2,c,4@}}, then @samp{A[3]} would equal @samp{c}. ++ ++ ++@node Maxima Language Mode, Giac Language Mode, Yacas Language Mode, Language Modes ++@subsection Maxima Language Mode ++ ++@noindent ++@kindex d X ++@pindex calc-maxima-language ++@cindex Maxima language ++The @kbd{d X} (@code{calc-maxima-language}) command selects the ++conventions of Maxima, another free computer algebra system. The ++function names in Maxima are similar, but not always identical, to Calc. ++For example, instead of @samp{arcsin(x)}, Maxima will use ++@samp{asin(x)}. Complex numbers are written @samp{3 + 4 %i}. The ++standard special constants are written @code{%pi}, @code{%e}, ++@code{%i}, @code{%phi} and @code{%gamma}. In Maxima, @code{inf} means ++the same as in Calc, but @code{infinity} represents Calc's @code{uinf}. ++ ++Underscores as well as percent signs are allowed in function and ++variable names in Maxima mode. The underscore again is equivalent to ++the @samp{#} in Normal mode, and the percent sign is equivalent to ++@samp{o'o}. ++ ++Maxima uses square brackets for lists and vectors, and matrices are ++written as calls to the function @code{matrix}, given the row vectors of ++the matrix as arguments. Square brackets are also used as subscripts. ++ ++@node Giac Language Mode, Mathematica Language Mode, Maxima Language Mode, Language Modes ++@subsection Giac Language Mode ++ ++@noindent ++@kindex d A ++@pindex calc-giac-language ++@cindex Giac language ++The @kbd{d A} (@code{calc-giac-language}) command selects the ++conventions of Giac, another free computer algebra system. The function ++names in Giac are similar to Maxima. Complex numbers are written ++@samp{3 + 4 i}. The standard special constants in Giac are the same as ++in Calc, except that @code{infinity} represents both Calc's @code{inf} ++and @code{uinf}. ++ ++Underscores are allowed in function and variable names in Giac mode. ++Brackets are used for subscripts. In Giac, indexing of lists begins at ++0, instead of 1 as in Calc. So if @samp{A} represents the list ++@samp{[a,2,c,4]}, then @samp{A[2]} would equal @samp{c}. In general, ++@samp{A[n]} in Giac mode corresponds to @samp{A_(n+1)} in Normal mode. ++ ++The Giac interval notation @samp{2 .. 3} has no surrounding brackets; ++Calc reads @samp{2 .. 3} as the closed interval @samp{[2 .. 3]} and ++writes any kind of interval as @samp{2 .. 3}. This means you cannot see ++the difference between an open and a closed interval while in Giac mode. ++ ++@node Mathematica Language Mode, Maple Language Mode, Giac Language Mode, Language Modes ++@subsection Mathematica Language Mode ++ ++@noindent ++@kindex d M ++@pindex calc-mathematica-language ++@cindex Mathematica language ++The @kbd{d M} (@code{calc-mathematica-language}) command selects the ++conventions of Mathematica. Notable differences in Mathematica mode ++are that the names of built-in functions are capitalized, and function ++calls use square brackets instead of parentheses. Thus the Calc ++formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in ++Mathematica mode. ++ ++Vectors and matrices use curly braces in Mathematica. Complex numbers ++are written @samp{3 + 4 I}. The standard special constants in Calc are ++written @code{Pi}, @code{E}, @code{I}, @code{GoldenRatio}, @code{EulerGamma}, ++@code{Infinity}, @code{ComplexInfinity}, and @code{Indeterminate} in ++Mathematica mode. ++Non-decimal numbers are written, e.g., @samp{16^^7fff}. Floating-point ++numbers in scientific notation are written @samp{1.23*10.^3}. ++Subscripts use double square brackets: @samp{a[[i]]}. ++ ++@node Maple Language Mode, Compositions, Mathematica Language Mode, Language Modes ++@subsection Maple Language Mode ++ ++@noindent ++@kindex d W ++@pindex calc-maple-language ++@cindex Maple language ++The @kbd{d W} (@code{calc-maple-language}) command selects the ++conventions of Maple. ++ ++Maple's language is much like C. Underscores are allowed in symbol ++names; square brackets are used for subscripts; explicit @samp{*}s for ++multiplications are required. Use either @samp{^} or @samp{**} to ++denote powers. ++ ++Maple uses square brackets for lists and curly braces for sets. Calc ++interprets both notations as vectors, and displays vectors with square ++brackets. This means Maple sets will be converted to lists when they ++pass through Calc. As a special case, matrices are written as calls ++to the function @code{matrix}, given a list of lists as the argument, ++and can be read in this form or with all-capitals @code{MATRIX}. ++ ++The Maple interval notation @samp{2 .. 3} is like Giac's interval ++notation, and is handled the same by Calc. ++ ++Maple writes complex numbers as @samp{3 + 4*I}. Its special constants ++are @code{Pi}, @code{E}, @code{I}, and @code{infinity} (all three of ++@code{inf}, @code{uinf}, and @code{nan} display as @code{infinity}). ++Floating-point numbers are written @samp{1.23*10.^3}. ++ ++Among things not currently handled by Calc's Maple mode are the ++various quote symbols, procedures and functional operators, and ++inert (@samp{&}) operators. ++ ++@node Compositions, Syntax Tables, Maple Language Mode, Language Modes ++@subsection Compositions ++ ++@noindent ++@cindex Compositions ++There are several @dfn{composition functions} which allow you to get ++displays in a variety of formats similar to those in Big language ++mode. Most of these functions do not evaluate to anything; they are ++placeholders which are left in symbolic form by Calc's evaluator but ++are recognized by Calc's display formatting routines. ++ ++Two of these, @code{string} and @code{bstring}, are described elsewhere. ++@xref{Strings}. For example, @samp{string("ABC")} is displayed as ++@samp{ABC}. When viewed on the stack it will be indistinguishable from ++the variable @code{ABC}, but internally it will be stored as ++@samp{string([65, 66, 67])} and can still be manipulated this way; for ++example, the selection and vector commands @kbd{j 1 v v j u} would ++select the vector portion of this object and reverse the elements, then ++deselect to reveal a string whose characters had been reversed. ++ ++The composition functions do the same thing in all language modes ++(although their components will of course be formatted in the current ++language mode). The one exception is Unformatted mode (@kbd{d U}), ++which does not give the composition functions any special treatment. ++The functions are discussed here because of their relationship to ++the language modes. ++ ++@menu ++* Composition Basics:: ++* Horizontal Compositions:: ++* Vertical Compositions:: ++* Other Compositions:: ++* Information about Compositions:: ++* User-Defined Compositions:: ++@end menu ++ ++@node Composition Basics, Horizontal Compositions, Compositions, Compositions ++@subsubsection Composition Basics ++ ++@noindent ++Compositions are generally formed by stacking formulas together ++horizontally or vertically in various ways. Those formulas are ++themselves compositions. @TeX{} users will find this analogous ++to @TeX{}'s ``boxes.'' Each multi-line composition has a ++@dfn{baseline}; horizontal compositions use the baselines to ++decide how formulas should be positioned relative to one another. ++For example, in the Big mode formula ++ ++@example ++@group ++ 2 ++ a + b ++17 + ------ ++ c ++@end group ++@end example ++ ++@noindent ++the second term of the sum is four lines tall and has line three as ++its baseline. Thus when the term is combined with 17, line three ++is placed on the same level as the baseline of 17. ++ ++@tex ++\bigskip ++@end tex ++ ++Another important composition concept is @dfn{precedence}. This is ++an integer that represents the binding strength of various operators. ++For example, @samp{*} has higher precedence (195) than @samp{+} (180), ++which means that @samp{(a * b) + c} will be formatted without the ++parentheses, but @samp{a * (b + c)} will keep the parentheses. ++ ++The operator table used by normal and Big language modes has the ++following precedences: ++ ++@example ++_ 1200 @r{(subscripts)} ++% 1100 @r{(as in n}%@r{)} ++! 1000 @r{(as in }!@r{n)} ++mod 400 +++/- 300 ++!! 210 @r{(as in n}!!@r{)} ++! 210 @r{(as in n}!@r{)} ++^ 200 ++- 197 @r{(as in }-@r{n)} ++* 195 @r{(or implicit multiplication)} ++/ % \ 190 +++ - 180 @r{(as in a}+@r{b)} ++| 170 ++< = 160 @r{(and other relations)} ++&& 110 ++|| 100 ++? : 90 ++!!! 85 ++&&& 80 ++||| 75 ++:= 50 ++:: 45 ++=> 40 ++@end example ++ ++The general rule is that if an operator with precedence @expr{n} ++occurs as an argument to an operator with precedence @expr{m}, then ++the argument is enclosed in parentheses if @expr{n < m}. Top-level ++expressions and expressions which are function arguments, vector ++components, etc., are formatted with precedence zero (so that they ++normally never get additional parentheses). ++ ++For binary left-associative operators like @samp{+}, the righthand ++argument is actually formatted with one-higher precedence than shown ++in the table. This makes sure @samp{(a + b) + c} omits the parentheses, ++but the unnatural form @samp{a + (b + c)} keeps its parentheses. ++Right-associative operators like @samp{^} format the lefthand argument ++with one-higher precedence. ++ ++@ignore ++@starindex ++@end ignore ++@tindex cprec ++The @code{cprec} function formats an expression with an arbitrary ++precedence. For example, @samp{cprec(abc, 185)} will combine into ++sums and products as follows: @samp{7 + abc}, @samp{7 (abc)} (because ++this @code{cprec} form has higher precedence than addition, but lower ++precedence than multiplication). ++ ++@tex ++\bigskip ++@end tex ++ ++A final composition issue is @dfn{line breaking}. Calc uses two ++different strategies for ``flat'' and ``non-flat'' compositions. ++A non-flat composition is anything that appears on multiple lines ++(not counting line breaking). Examples would be matrices and Big ++mode powers and quotients. Non-flat compositions are displayed ++exactly as specified. If they come out wider than the current ++window, you must use horizontal scrolling (@kbd{<} and @kbd{>}) to ++view them. ++ ++Flat compositions, on the other hand, will be broken across several ++lines if they are too wide to fit the window. Certain points in a ++composition are noted internally as @dfn{break points}. Calc's ++general strategy is to fill each line as much as possible, then to ++move down to the next line starting at the first break point that ++didn't fit. However, the line breaker understands the hierarchical ++structure of formulas. It will not break an ``inner'' formula if ++it can use an earlier break point from an ``outer'' formula instead. ++For example, a vector of sums might be formatted as: ++ ++@example ++@group ++[ a + b + c, d + e + f, ++ g + h + i, j + k + l, m ] ++@end group ++@end example ++ ++@noindent ++If the @samp{m} can fit, then so, it seems, could the @samp{g}. ++But Calc prefers to break at the comma since the comma is part ++of a ``more outer'' formula. Calc would break at a plus sign ++only if it had to, say, if the very first sum in the vector had ++itself been too large to fit. ++ ++Of the composition functions described below, only @code{choriz} ++generates break points. The @code{bstring} function (@pxref{Strings}) ++also generates breakable items: A break point is added after every ++space (or group of spaces) except for spaces at the very beginning or ++end of the string. ++ ++Composition functions themselves count as levels in the formula ++hierarchy, so a @code{choriz} that is a component of a larger ++@code{choriz} will be less likely to be broken. As a special case, ++if a @code{bstring} occurs as a component of a @code{choriz} or ++@code{choriz}-like object (such as a vector or a list of arguments ++in a function call), then the break points in that @code{bstring} ++will be on the same level as the break points of the surrounding ++object. ++ ++@node Horizontal Compositions, Vertical Compositions, Composition Basics, Compositions ++@subsubsection Horizontal Compositions ++ ++@noindent ++@ignore ++@starindex ++@end ignore ++@tindex choriz ++The @code{choriz} function takes a vector of objects and composes ++them horizontally. For example, @samp{choriz([17, a b/c, d])} formats ++as @w{@samp{17a b / cd}} in Normal language mode, or as ++ ++@example ++@group ++ a b ++17---d ++ c ++@end group ++@end example ++ ++@noindent ++in Big language mode. This is actually one case of the general ++function @samp{choriz(@var{vec}, @var{sep}, @var{prec})}, where ++either or both of @var{sep} and @var{prec} may be omitted. ++@var{Prec} gives the @dfn{precedence} to use when formatting ++each of the components of @var{vec}. The default precedence is ++the precedence from the surrounding environment. ++ ++@var{Sep} is a string (i.e., a vector of character codes as might ++be entered with @code{" "} notation) which should separate components ++of the composition. Also, if @var{sep} is given, the line breaker ++will allow lines to be broken after each occurrence of @var{sep}. ++If @var{sep} is omitted, the composition will not be breakable ++(unless any of its component compositions are breakable). ++ ++For example, @samp{2 choriz([a, b c, d = e], " + ", 180)} is ++formatted as @samp{2 a + b c + (d = e)}. To get the @code{choriz} ++to have precedence 180 ``outwards'' as well as ``inwards,'' ++enclose it in a @code{cprec} form: @samp{2 cprec(choriz(...), 180)} ++formats as @samp{2 (a + b c + (d = e))}. ++ ++The baseline of a horizontal composition is the same as the ++baselines of the component compositions, which are all aligned. ++ ++@node Vertical Compositions, Other Compositions, Horizontal Compositions, Compositions ++@subsubsection Vertical Compositions ++ ++@noindent ++@ignore ++@starindex ++@end ignore ++@tindex cvert ++The @code{cvert} function makes a vertical composition. Each ++component of the vector is centered in a column. The baseline of ++the result is by default the top line of the resulting composition. ++For example, @samp{f(cvert([a, bb, ccc]), cvert([a^2 + 1, b^2]))} ++formats in Big mode as ++ ++@example ++@group ++f( a , 2 ) ++ bb a + 1 ++ ccc 2 ++ b ++@end group ++@end example ++ ++@ignore ++@starindex ++@end ignore ++@tindex cbase ++There are several special composition functions that work only as ++components of a vertical composition. The @code{cbase} function ++controls the baseline of the vertical composition; the baseline ++will be the same as the baseline of whatever component is enclosed ++in @code{cbase}. Thus @samp{f(cvert([a, cbase(bb), ccc]), ++cvert([a^2 + 1, cbase(b^2)]))} displays as ++ ++@example ++@group ++ 2 ++ a + 1 ++ a 2 ++f(bb , b ) ++ ccc ++@end group ++@end example ++ ++@ignore ++@starindex ++@end ignore ++@tindex ctbase ++@ignore ++@starindex ++@end ignore ++@tindex cbbase ++There are also @code{ctbase} and @code{cbbase} functions which ++make the baseline of the vertical composition equal to the top ++or bottom line (rather than the baseline) of that component. ++Thus @samp{cvert([cbase(a / b)]) + cvert([ctbase(a / b)]) + ++cvert([cbbase(a / b)])} gives ++ ++@example ++@group ++ a ++a - ++- + a + b ++b - ++ b ++@end group ++@end example ++ ++There should be only one @code{cbase}, @code{ctbase}, or @code{cbbase} ++function in a given vertical composition. These functions can also ++be written with no arguments: @samp{ctbase()} is a zero-height object ++which means the baseline is the top line of the following item, and ++@samp{cbbase()} means the baseline is the bottom line of the preceding ++item. ++ ++@ignore ++@starindex ++@end ignore ++@tindex crule ++The @code{crule} function builds a ``rule,'' or horizontal line, ++across a vertical composition. By itself @samp{crule()} uses @samp{-} ++characters to build the rule. You can specify any other character, ++e.g., @samp{crule("=")}. The argument must be a character code or ++vector of exactly one character code. It is repeated to match the ++width of the widest item in the stack. For example, a quotient ++with a thick line is @samp{cvert([a + 1, cbase(crule("=")), b^2])}: ++ ++@example ++@group ++a + 1 ++===== ++ 2 ++ b ++@end group ++@end example ++ ++@ignore ++@starindex ++@end ignore ++@tindex clvert ++@ignore ++@starindex ++@end ignore ++@tindex crvert ++Finally, the functions @code{clvert} and @code{crvert} act exactly ++like @code{cvert} except that the items are left- or right-justified ++in the stack. Thus @samp{clvert([a, bb, ccc]) + crvert([a, bb, ccc])} ++gives: ++ ++@example ++@group ++a + a ++bb bb ++ccc ccc ++@end group ++@end example ++ ++Like @code{choriz}, the vertical compositions accept a second argument ++which gives the precedence to use when formatting the components. ++Vertical compositions do not support separator strings. ++ ++@node Other Compositions, Information about Compositions, Vertical Compositions, Compositions ++@subsubsection Other Compositions ++ ++@noindent ++@ignore ++@starindex ++@end ignore ++@tindex csup ++The @code{csup} function builds a superscripted expression. For ++example, @samp{csup(a, b)} looks the same as @samp{a^b} does in Big ++language mode. This is essentially a horizontal composition of ++@samp{a} and @samp{b}, where @samp{b} is shifted up so that its ++bottom line is one above the baseline. ++ ++@ignore ++@starindex ++@end ignore ++@tindex csub ++Likewise, the @code{csub} function builds a subscripted expression. ++This shifts @samp{b} down so that its top line is one below the ++bottom line of @samp{a} (note that this is not quite analogous to ++@code{csup}). Other arrangements can be obtained by using ++@code{choriz} and @code{cvert} directly. ++ ++@ignore ++@starindex ++@end ignore ++@tindex cflat ++The @code{cflat} function formats its argument in ``flat'' mode, ++as obtained by @samp{d O}, if the current language mode is normal ++or Big. It has no effect in other language modes. For example, ++@samp{a^(b/c)} is formatted by Big mode like @samp{csup(a, cflat(b/c))} ++to improve its readability. ++ ++@ignore ++@starindex ++@end ignore ++@tindex cspace ++The @code{cspace} function creates horizontal space. For example, ++@samp{cspace(4)} is effectively the same as @samp{string(" ")}. ++A second string (i.e., vector of characters) argument is repeated ++instead of the space character. For example, @samp{cspace(4, "ab")} ++looks like @samp{abababab}. If the second argument is not a string, ++it is formatted in the normal way and then several copies of that ++are composed together: @samp{cspace(4, a^2)} yields ++ ++@example ++@group ++ 2 2 2 2 ++a a a a ++@end group ++@end example ++ ++@noindent ++If the number argument is zero, this is a zero-width object. ++ ++@ignore ++@starindex ++@end ignore ++@tindex cvspace ++The @code{cvspace} function creates vertical space, or a vertical ++stack of copies of a certain string or formatted object. The ++baseline is the center line of the resulting stack. A numerical ++argument of zero will produce an object which contributes zero ++height if used in a vertical composition. ++ ++@ignore ++@starindex ++@end ignore ++@tindex ctspace ++@ignore ++@starindex ++@end ignore ++@tindex cbspace ++There are also @code{ctspace} and @code{cbspace} functions which ++create vertical space with the baseline the same as the baseline ++of the top or bottom copy, respectively, of the second argument. ++Thus @samp{cvspace(2, a/b) + ctspace(2, a/b) + cbspace(2, a/b)} ++displays as: ++ ++@example ++@group ++ a ++ - ++a b ++- a a ++b + - + - ++a b b ++- a ++b - ++ b ++@end group ++@end example ++ ++@node Information about Compositions, User-Defined Compositions, Other Compositions, Compositions ++@subsubsection Information about Compositions ++ ++@noindent ++The functions in this section are actual functions; they compose their ++arguments according to the current language and other display modes, ++then return a certain measurement of the composition as an integer. ++ ++@ignore ++@starindex ++@end ignore ++@tindex cwidth ++The @code{cwidth} function measures the width, in characters, of a ++composition. For example, @samp{cwidth(a + b)} is 5, and ++@samp{cwidth(a / b)} is 5 in Normal mode, 1 in Big mode, and 11 in ++@TeX{} mode (for @samp{@{a \over b@}}). The argument may involve ++the composition functions described in this section. ++ ++@ignore ++@starindex ++@end ignore ++@tindex cheight ++The @code{cheight} function measures the height of a composition. ++This is the total number of lines in the argument's printed form. ++ ++@ignore ++@starindex ++@end ignore ++@tindex cascent ++@ignore ++@starindex ++@end ignore ++@tindex cdescent ++The functions @code{cascent} and @code{cdescent} measure the amount ++of the height that is above (and including) the baseline, or below ++the baseline, respectively. Thus @samp{cascent(@var{x}) + cdescent(@var{x})} ++always equals @samp{cheight(@var{x})}. For a one-line formula like ++@samp{a + b}, @code{cascent} returns 1 and @code{cdescent} returns 0. ++For @samp{a / b} in Big mode, @code{cascent} returns 2 and @code{cdescent} ++returns 1. The only formula for which @code{cascent} will return zero ++is @samp{cvspace(0)} or equivalents. ++ ++@node User-Defined Compositions, , Information about Compositions, Compositions ++@subsubsection User-Defined Compositions ++ ++@noindent ++@kindex Z C ++@pindex calc-user-define-composition ++The @kbd{Z C} (@code{calc-user-define-composition}) command lets you ++define the display format for any algebraic function. You provide a ++formula containing a certain number of argument variables on the stack. ++Any time Calc formats a call to the specified function in the current ++language mode and with that number of arguments, Calc effectively ++replaces the function call with that formula with the arguments ++replaced. ++ ++Calc builds the default argument list by sorting all the variable names ++that appear in the formula into alphabetical order. You can edit this ++argument list before pressing @key{RET} if you wish. Any variables in ++the formula that do not appear in the argument list will be displayed ++literally; any arguments that do not appear in the formula will not ++affect the display at all. ++ ++You can define formats for built-in functions, for functions you have ++defined with @kbd{Z F} (@pxref{Algebraic Definitions}), or for functions ++which have no definitions but are being used as purely syntactic objects. ++You can define different formats for each language mode, and for each ++number of arguments, using a succession of @kbd{Z C} commands. When ++Calc formats a function call, it first searches for a format defined ++for the current language mode (and number of arguments); if there is ++none, it uses the format defined for the Normal language mode. If ++neither format exists, Calc uses its built-in standard format for that ++function (usually just @samp{@var{func}(@var{args})}). ++ ++If you execute @kbd{Z C} with the number 0 on the stack instead of a ++formula, any defined formats for the function in the current language ++mode will be removed. The function will revert to its standard format. ++ ++For example, the default format for the binomial coefficient function ++@samp{choose(n, m)} in the Big language mode is ++ ++@example ++@group ++ n ++( ) ++ m ++@end group ++@end example ++ ++@noindent ++You might prefer the notation, ++ ++@example ++@group ++ C ++n m ++@end group ++@end example ++ ++@noindent ++To define this notation, first make sure you are in Big mode, ++then put the formula ++ ++@smallexample ++choriz([cvert([cvspace(1), n]), C, cvert([cvspace(1), m])]) ++@end smallexample ++ ++@noindent ++on the stack and type @kbd{Z C}. Answer the first prompt with ++@code{choose}. The second prompt will be the default argument list ++of @samp{(C m n)}. Edit this list to be @samp{(n m)} and press ++@key{RET}. Now, try it out: For example, turn simplification ++off with @kbd{m O} and enter @samp{choose(a,b) + choose(7,3)} ++as an algebraic entry. ++ ++@example ++@group ++ C + C ++a b 7 3 ++@end group ++@end example ++ ++As another example, let's define the usual notation for Stirling ++numbers of the first kind, @samp{stir1(n, m)}. This is just like ++the regular format for binomial coefficients but with square brackets ++instead of parentheses. ++ ++@smallexample ++choriz([string("["), cvert([n, cbase(cvspace(1)), m]), string("]")]) ++@end smallexample ++ ++Now type @kbd{Z C stir1 @key{RET}}, edit the argument list to ++@samp{(n m)}, and type @key{RET}. ++ ++The formula provided to @kbd{Z C} usually will involve composition ++functions, but it doesn't have to. Putting the formula @samp{a + b + c} ++onto the stack and typing @kbd{Z C foo @key{RET} @key{RET}} would define ++the function @samp{foo(x,y,z)} to display like @samp{x + y + z}. ++This ``sum'' will act exactly like a real sum for all formatting ++purposes (it will be parenthesized the same, and so on). However ++it will be computationally unrelated to a sum. For example, the ++formula @samp{2 * foo(1, 2, 3)} will display as @samp{2 (1 + 2 + 3)}. ++Operator precedences have caused the ``sum'' to be written in ++parentheses, but the arguments have not actually been summed. ++(Generally a display format like this would be undesirable, since ++it can easily be confused with a real sum.) ++ ++The special function @code{eval} can be used inside a @kbd{Z C} ++composition formula to cause all or part of the formula to be ++evaluated at display time. For example, if the formula is ++@samp{a + eval(b + c)}, then @samp{foo(1, 2, 3)} will be displayed ++as @samp{1 + 5}. Evaluation will use the default simplifications, ++regardless of the current simplification mode. There are also ++@code{evalsimp} and @code{evalextsimp} which simplify as if by ++@kbd{a s} and @kbd{a e} (respectively). Note that these ``functions'' ++operate only in the context of composition formulas (and also in ++rewrite rules, where they serve a similar purpose; @pxref{Rewrite ++Rules}). On the stack, a call to @code{eval} will be left in ++symbolic form. ++ ++It is not a good idea to use @code{eval} except as a last resort. ++It can cause the display of formulas to be extremely slow. For ++example, while @samp{eval(a + b)} might seem quite fast and simple, ++there are several situations where it could be slow. For example, ++@samp{a} and/or @samp{b} could be polar complex numbers, in which ++case doing the sum requires trigonometry. Or, @samp{a} could be ++the factorial @samp{fact(100)} which is unevaluated because you ++have typed @kbd{m O}; @code{eval} will evaluate it anyway to ++produce a large, unwieldy integer. ++ ++You can save your display formats permanently using the @kbd{Z P} ++command (@pxref{Creating User Keys}). ++ ++@node Syntax Tables, , Compositions, Language Modes ++@subsection Syntax Tables ++ ++@noindent ++@cindex Syntax tables ++@cindex Parsing formulas, customized ++Syntax tables do for input what compositions do for output: They ++allow you to teach custom notations to Calc's formula parser. ++Calc keeps a separate syntax table for each language mode. ++ ++(Note that the Calc ``syntax tables'' discussed here are completely ++unrelated to the syntax tables described in the Emacs manual.) ++ ++@kindex Z S ++@pindex calc-edit-user-syntax ++The @kbd{Z S} (@code{calc-edit-user-syntax}) command edits the ++syntax table for the current language mode. If you want your ++syntax to work in any language, define it in the Normal language ++mode. Type @kbd{C-c C-c} to finish editing the syntax table, or ++@kbd{C-x k} to cancel the edit. The @kbd{m m} command saves all ++the syntax tables along with the other mode settings; ++@pxref{General Mode Commands}. ++ ++@menu ++* Syntax Table Basics:: ++* Precedence in Syntax Tables:: ++* Advanced Syntax Patterns:: ++* Conditional Syntax Rules:: ++@end menu ++ ++@node Syntax Table Basics, Precedence in Syntax Tables, Syntax Tables, Syntax Tables ++@subsubsection Syntax Table Basics ++ ++@noindent ++@dfn{Parsing} is the process of converting a raw string of characters, ++such as you would type in during algebraic entry, into a Calc formula. ++Calc's parser works in two stages. First, the input is broken down ++into @dfn{tokens}, such as words, numbers, and punctuation symbols ++like @samp{+}, @samp{:=}, and @samp{+/-}. Space between tokens is ++ignored (except when it serves to separate adjacent words). Next, ++the parser matches this string of tokens against various built-in ++syntactic patterns, such as ``an expression followed by @samp{+} ++followed by another expression'' or ``a name followed by @samp{(}, ++zero or more expressions separated by commas, and @samp{)}.'' ++ ++A @dfn{syntax table} is a list of user-defined @dfn{syntax rules}, ++which allow you to specify new patterns to define your own ++favorite input notations. Calc's parser always checks the syntax ++table for the current language mode, then the table for the Normal ++language mode, before it uses its built-in rules to parse an ++algebraic formula you have entered. Each syntax rule should go on ++its own line; it consists of a @dfn{pattern}, a @samp{:=} symbol, ++and a Calc formula with an optional @dfn{condition}. (Syntax rules ++resemble algebraic rewrite rules, but the notation for patterns is ++completely different.) ++ ++A syntax pattern is a list of tokens, separated by spaces. ++Except for a few special symbols, tokens in syntax patterns are ++matched literally, from left to right. For example, the rule, ++ ++@example ++foo ( ) := 2+3 ++@end example ++ ++@noindent ++would cause Calc to parse the formula @samp{4+foo()*5} as if it ++were @samp{4+(2+3)*5}. Notice that the parentheses were written ++as two separate tokens in the rule. As a result, the rule works ++for both @samp{foo()} and @w{@samp{foo ( )}}. If we had written ++the rule as @samp{foo () := 2+3}, then Calc would treat @samp{()} ++as a single, indivisible token, so that @w{@samp{foo( )}} would ++not be recognized by the rule. (It would be parsed as a regular ++zero-argument function call instead.) In fact, this rule would ++also make trouble for the rest of Calc's parser: An unrelated ++formula like @samp{bar()} would now be tokenized into @samp{bar ()} ++instead of @samp{bar ( )}, so that the standard parser for function ++calls would no longer recognize it! ++ ++While it is possible to make a token with a mixture of letters ++and punctuation symbols, this is not recommended. It is better to ++break it into several tokens, as we did with @samp{foo()} above. ++ ++The symbol @samp{#} in a syntax pattern matches any Calc expression. ++On the righthand side, the things that matched the @samp{#}s can ++be referred to as @samp{#1}, @samp{#2}, and so on (where @samp{#1} ++matches the leftmost @samp{#} in the pattern). For example, these ++rules match a user-defined function, prefix operator, infix operator, ++and postfix operator, respectively: ++ ++@example ++foo ( # ) := myfunc(#1) ++foo # := myprefix(#1) ++# foo # := myinfix(#1,#2) ++# foo := mypostfix(#1) ++@end example ++ ++Thus @samp{foo(3)} will parse as @samp{myfunc(3)}, and @samp{2+3 foo} ++will parse as @samp{mypostfix(2+3)}. ++ ++It is important to write the first two rules in the order shown, ++because Calc tries rules in order from first to last. If the ++pattern @samp{foo #} came first, it would match anything that could ++match the @samp{foo ( # )} rule, since an expression in parentheses ++is itself a valid expression. Thus the @w{@samp{foo ( # )}} rule would ++never get to match anything. Likewise, the last two rules must be ++written in the order shown or else @samp{3 foo 4} will be parsed as ++@samp{mypostfix(3) * 4}. (Of course, the best way to avoid these ++ambiguities is not to use the same symbol in more than one way at ++the same time! In case you're not convinced, try the following ++exercise: How will the above rules parse the input @samp{foo(3,4)}, ++if at all? Work it out for yourself, then try it in Calc and see.) ++ ++Calc is quite flexible about what sorts of patterns are allowed. ++The only rule is that every pattern must begin with a literal ++token (like @samp{foo} in the first two patterns above), or with ++a @samp{#} followed by a literal token (as in the last two ++patterns). After that, any mixture is allowed, although putting ++two @samp{#}s in a row will not be very useful since two ++expressions with nothing between them will be parsed as one ++expression that uses implicit multiplication. ++ ++As a more practical example, Maple uses the notation ++@samp{sum(a(i), i=1..10)} for sums, which Calc's Maple mode doesn't ++recognize at present. To handle this syntax, we simply add the ++rule, ++ ++@example ++sum ( # , # = # .. # ) := sum(#1,#2,#3,#4) ++@end example ++ ++@noindent ++to the Maple mode syntax table. As another example, C mode can't ++read assignment operators like @samp{++} and @samp{*=}. We can ++define these operators quite easily: ++ ++@example ++# *= # := muleq(#1,#2) ++# ++ := postinc(#1) ++++ # := preinc(#1) ++@end example ++ ++@noindent ++To complete the job, we would use corresponding composition functions ++and @kbd{Z C} to cause these functions to display in their respective ++Maple and C notations. (Note that the C example ignores issues of ++operator precedence, which are discussed in the next section.) ++ ++You can enclose any token in quotes to prevent its usual ++interpretation in syntax patterns: ++ ++@example ++# ":=" # := becomes(#1,#2) ++@end example ++ ++Quotes also allow you to include spaces in a token, although once ++again it is generally better to use two tokens than one token with ++an embedded space. To include an actual quotation mark in a quoted ++token, precede it with a backslash. (This also works to include ++backslashes in tokens.) ++ ++@example ++# "bad token" # "/\"\\" # := silly(#1,#2,#3) ++@end example ++ ++@noindent ++This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}. ++ ++The token @kbd{#} has a predefined meaning in Calc's formula parser; ++it is not valid to use @samp{"#"} in a syntax rule. However, longer ++tokens that include the @samp{#} character are allowed. Also, while ++@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in ++the syntax table will prevent those characters from working in their ++usual ways (referring to stack entries and quoting strings, ++respectively). ++ ++Finally, the notation @samp{%%} anywhere in a syntax table causes ++the rest of the line to be ignored as a comment. ++ ++@node Precedence in Syntax Tables, Advanced Syntax Patterns, Syntax Table Basics, Syntax Tables ++@subsubsection Precedence ++ ++@noindent ++Different operators are generally assigned different @dfn{precedences}. ++By default, an operator defined by a rule like ++ ++@example ++# foo # := foo(#1,#2) ++@end example ++ ++@noindent ++will have an extremely low precedence, so that @samp{2*3+4 foo 5 == 6} ++will be parsed as @samp{(2*3+4) foo (5 == 6)}. To change the ++precedence of an operator, use the notation @samp{#/@var{p}} in ++place of @samp{#}, where @var{p} is an integer precedence level. ++For example, 185 lies between the precedences for @samp{+} and ++@samp{*}, so if we change this rule to ++ ++@example ++#/185 foo #/186 := foo(#1,#2) ++@end example ++ ++@noindent ++then @samp{2+3 foo 4*5} will be parsed as @samp{2+(3 foo (4*5))}. ++Also, because we've given the righthand expression slightly higher ++precedence, our new operator will be left-associative: ++@samp{1 foo 2 foo 3} will be parsed as @samp{(1 foo 2) foo 3}. ++By raising the precedence of the lefthand expression instead, we ++can create a right-associative operator. ++ ++@xref{Composition Basics}, for a table of precedences of the ++standard Calc operators. For the precedences of operators in other ++language modes, look in the Calc source file @file{calc-lang.el}. ++ ++@node Advanced Syntax Patterns, Conditional Syntax Rules, Precedence in Syntax Tables, Syntax Tables ++@subsubsection Advanced Syntax Patterns ++ ++@noindent ++To match a function with a variable number of arguments, you could ++write ++ ++@example ++foo ( # ) := myfunc(#1) ++foo ( # , # ) := myfunc(#1,#2) ++foo ( # , # , # ) := myfunc(#1,#2,#3) ++@end example ++ ++@noindent ++but this isn't very elegant. To match variable numbers of items, ++Calc uses some notations inspired regular expressions and the ++``extended BNF'' style used by some language designers. ++ ++@example ++foo ( @{ # @}*, ) := apply(myfunc,#1) ++@end example ++ ++The token @samp{@{} introduces a repeated or optional portion. ++One of the three tokens @samp{@}*}, @samp{@}+}, or @samp{@}?} ++ends the portion. These will match zero or more, one or more, ++or zero or one copies of the enclosed pattern, respectively. ++In addition, @samp{@}*} and @samp{@}+} can be followed by a ++separator token (with no space in between, as shown above). ++Thus @samp{@{ # @}*,} matches nothing, or one expression, or ++several expressions separated by commas. ++ ++A complete @samp{@{ ... @}} item matches as a vector of the ++items that matched inside it. For example, the above rule will ++match @samp{foo(1,2,3)} to get @samp{apply(myfunc,[1,2,3])}. ++The Calc @code{apply} function takes a function name and a vector ++of arguments and builds a call to the function with those ++arguments, so the net result is the formula @samp{myfunc(1,2,3)}. ++ ++If the body of a @samp{@{ ... @}} contains several @samp{#}s ++(or nested @samp{@{ ... @}} constructs), then the items will be ++strung together into the resulting vector. If the body ++does not contain anything but literal tokens, the result will ++always be an empty vector. ++ ++@example ++foo ( @{ # , # @}+, ) := bar(#1) ++foo ( @{ @{ # @}*, @}*; ) := matrix(#1) ++@end example ++ ++@noindent ++will parse @samp{foo(1, 2, 3, 4)} as @samp{bar([1, 2, 3, 4])}, and ++@samp{foo(1, 2; 3, 4)} as @samp{matrix([[1, 2], [3, 4]])}. Also, after ++some thought it's easy to see how this pair of rules will parse ++@samp{foo(1, 2, 3)} as @samp{matrix([[1, 2, 3]])}, since the first ++rule will only match an even number of arguments. The rule ++ ++@example ++foo ( # @{ , # , # @}? ) := bar(#1,#2) ++@end example ++ ++@noindent ++will parse @samp{foo(2,3,4)} as @samp{bar(2,[3,4])}, and ++@samp{foo(2)} as @samp{bar(2,[])}. ++ ++The notation @samp{@{ ... @}?.} (note the trailing period) works ++just the same as regular @samp{@{ ... @}?}, except that it does not ++count as an argument; the following two rules are equivalent: ++ ++@example ++foo ( # , @{ also @}? # ) := bar(#1,#3) ++foo ( # , @{ also @}?. # ) := bar(#1,#2) ++@end example ++ ++@noindent ++Note that in the first case the optional text counts as @samp{#2}, ++which will always be an empty vector, but in the second case no ++empty vector is produced. ++ ++Another variant is @samp{@{ ... @}?$}, which means the body is ++optional only at the end of the input formula. All built-in syntax ++rules in Calc use this for closing delimiters, so that during ++algebraic entry you can type @kbd{[sqrt(2), sqrt(3 @key{RET}}, omitting ++the closing parenthesis and bracket. Calc does this automatically ++for trailing @samp{)}, @samp{]}, and @samp{>} tokens in syntax ++rules, but you can use @samp{@{ ... @}?$} explicitly to get ++this effect with any token (such as @samp{"@}"} or @samp{end}). ++Like @samp{@{ ... @}?.}, this notation does not count as an ++argument. Conversely, you can use quotes, as in @samp{")"}, to ++prevent a closing-delimiter token from being automatically treated ++as optional. ++ ++Calc's parser does not have full backtracking, which means some ++patterns will not work as you might expect: ++ ++@example ++foo ( @{ # , @}? # , # ) := bar(#1,#2,#3) ++@end example ++ ++@noindent ++Here we are trying to make the first argument optional, so that ++@samp{foo(2,3)} parses as @samp{bar([],2,3)}. Unfortunately, Calc ++first tries to match @samp{2,} against the optional part of the ++pattern, finds a match, and so goes ahead to match the rest of the ++pattern. Later on it will fail to match the second comma, but it ++doesn't know how to go back and try the other alternative at that ++point. One way to get around this would be to use two rules: ++ ++@example ++foo ( # , # , # ) := bar([#1],#2,#3) ++foo ( # , # ) := bar([],#1,#2) ++@end example ++ ++More precisely, when Calc wants to match an optional or repeated ++part of a pattern, it scans forward attempting to match that part. ++If it reaches the end of the optional part without failing, it ++``finalizes'' its choice and proceeds. If it fails, though, it ++backs up and tries the other alternative. Thus Calc has ``partial'' ++backtracking. A fully backtracking parser would go on to make sure ++the rest of the pattern matched before finalizing the choice. ++ ++@node Conditional Syntax Rules, , Advanced Syntax Patterns, Syntax Tables ++@subsubsection Conditional Syntax Rules ++ ++@noindent ++It is possible to attach a @dfn{condition} to a syntax rule. For ++example, the rules ++ ++@example ++foo ( # ) := ifoo(#1) :: integer(#1) ++foo ( # ) := gfoo(#1) ++@end example ++ ++@noindent ++will parse @samp{foo(3)} as @samp{ifoo(3)}, but will parse ++@samp{foo(3.5)} and @samp{foo(x)} as calls to @code{gfoo}. Any ++number of conditions may be attached; all must be true for the ++rule to succeed. A condition is ``true'' if it evaluates to a ++nonzero number. @xref{Logical Operations}, for a list of Calc ++functions like @code{integer} that perform logical tests. ++ ++The exact sequence of events is as follows: When Calc tries a ++rule, it first matches the pattern as usual. It then substitutes ++@samp{#1}, @samp{#2}, etc., in the conditions, if any. Next, the ++conditions are simplified and evaluated in order from left to right, ++as if by the @w{@kbd{a s}} algebra command (@pxref{Simplifying Formulas}). ++Each result is true if it is a nonzero number, or an expression ++that can be proven to be nonzero (@pxref{Declarations}). If the ++results of all conditions are true, the expression (such as ++@samp{ifoo(#1)}) has its @samp{#}s substituted, and that is the ++result of the parse. If the result of any condition is false, Calc ++goes on to try the next rule in the syntax table. ++ ++Syntax rules also support @code{let} conditions, which operate in ++exactly the same way as they do in algebraic rewrite rules. ++@xref{Other Features of Rewrite Rules}, for details. A @code{let} ++condition is always true, but as a side effect it defines a ++variable which can be used in later conditions, and also in the ++expression after the @samp{:=} sign: ++ ++@example ++foo ( # ) := hifoo(x) :: let(x := #1 + 0.5) :: dnumint(x) ++@end example ++ ++@noindent ++The @code{dnumint} function tests if a value is numerically an ++integer, i.e., either a true integer or an integer-valued float. ++This rule will parse @code{foo} with a half-integer argument, ++like @samp{foo(3.5)}, to a call like @samp{hifoo(4.)}. ++ ++The lefthand side of a syntax rule @code{let} must be a simple ++variable, not the arbitrary pattern that is allowed in rewrite ++rules. ++ ++The @code{matches} function is also treated specially in syntax ++rule conditions (again, in the same way as in rewrite rules). ++@xref{Matching Commands}. If the matching pattern contains ++meta-variables, then those meta-variables may be used in later ++conditions and in the result expression. The arguments to ++@code{matches} are not evaluated in this situation. ++ ++@example ++sum ( # , # ) := sum(#1,a,b,c) :: matches(#2, a=[b..c]) ++@end example ++ ++@noindent ++This is another way to implement the Maple mode @code{sum} notation. ++In this approach, we allow @samp{#2} to equal the whole expression ++@samp{i=1..10}. Then, we use @code{matches} to break it apart into ++its components. If the expression turns out not to match the pattern, ++the syntax rule will fail. Note that @kbd{Z S} always uses Calc's ++Normal language mode for editing expressions in syntax rules, so we ++must use regular Calc notation for the interval @samp{[b..c]} that ++will correspond to the Maple mode interval @samp{1..10}. ++ ++@node Modes Variable, Calc Mode Line, Language Modes, Mode Settings ++@section The @code{Modes} Variable ++ ++@noindent ++@kindex m g ++@pindex calc-get-modes ++The @kbd{m g} (@code{calc-get-modes}) command pushes onto the stack ++a vector of numbers that describes the various mode settings that ++are in effect. With a numeric prefix argument, it pushes only the ++@var{n}th mode, i.e., the @var{n}th element of this vector. Keyboard ++macros can use the @kbd{m g} command to modify their behavior based ++on the current mode settings. ++ ++@cindex @code{Modes} variable ++@vindex Modes ++The modes vector is also available in the special variable ++@code{Modes}. In other words, @kbd{m g} is like @kbd{s r Modes @key{RET}}. ++It will not work to store into this variable; in fact, if you do, ++@code{Modes} will cease to track the current modes. (The @kbd{m g} ++command will continue to work, however.) ++ ++In general, each number in this vector is suitable as a numeric ++prefix argument to the associated mode-setting command. (Recall ++that the @kbd{~} key takes a number from the stack and gives it as ++a numeric prefix to the next command.) ++ ++The elements of the modes vector are as follows: ++ ++@enumerate ++@item ++Current precision. Default is 12; associated command is @kbd{p}. ++ ++@item ++Binary word size. Default is 32; associated command is @kbd{b w}. ++ ++@item ++Stack size (not counting the value about to be pushed by @kbd{m g}). ++This is zero if @kbd{m g} is executed with an empty stack. ++ ++@item ++Number radix. Default is 10; command is @kbd{d r}. ++ ++@item ++Floating-point format. This is the number of digits, plus the ++constant 0 for normal notation, 10000 for scientific notation, ++20000 for engineering notation, or 30000 for fixed-point notation. ++These codes are acceptable as prefix arguments to the @kbd{d n} ++command, but note that this may lose information: For example, ++@kbd{d s} and @kbd{C-u 12 d s} have similar (but not quite ++identical) effects if the current precision is 12, but they both ++produce a code of 10012, which will be treated by @kbd{d n} as ++@kbd{C-u 12 d s}. If the precision then changes, the float format ++will still be frozen at 12 significant figures. ++ ++@item ++Angular mode. Default is 1 (degrees). Other values are 2 (radians) ++and 3 (HMS). The @kbd{m d} command accepts these prefixes. ++ ++@item ++Symbolic mode. Value is 0 or 1; default is 0. Command is @kbd{m s}. ++ ++@item ++Fraction mode. Value is 0 or 1; default is 0. Command is @kbd{m f}. ++ ++@item ++Polar mode. Value is 0 (rectangular) or 1 (polar); default is 0. ++Command is @kbd{m p}. ++ ++@item ++Matrix/Scalar mode. Default value is @mathit{-1}. Value is 0 for Scalar ++mode, @mathit{-2} for Matrix mode, @mathit{-3} for square Matrix mode, ++or @var{N} for ++@texline @math{N\times N} ++@infoline @var{N}x@var{N} ++Matrix mode. Command is @kbd{m v}. ++ ++@item ++Simplification mode. Default is 1. Value is @mathit{-1} for off (@kbd{m O}), ++0 for @kbd{m N}, 2 for @kbd{m B}, 3 for @kbd{m A}, 4 for @kbd{m E}, ++or 5 for @w{@kbd{m U}}. The @kbd{m D} command accepts these prefixes. ++ ++@item ++Infinite mode. Default is @mathit{-1} (off). Value is 1 if the mode is on, ++or 0 if the mode is on with positive zeros. Command is @kbd{m i}. ++@end enumerate ++ ++For example, the sequence @kbd{M-1 m g @key{RET} 2 + ~ p} increases the ++precision by two, leaving a copy of the old precision on the stack. ++Later, @kbd{~ p} will restore the original precision using that ++stack value. (This sequence might be especially useful inside a ++keyboard macro.) ++ ++As another example, @kbd{M-3 m g 1 - ~ @key{DEL}} deletes all but the ++oldest (bottommost) stack entry. ++ ++Yet another example: The HP-48 ``round'' command rounds a number ++to the current displayed precision. You could roughly emulate this ++in Calc with the sequence @kbd{M-5 m g 10000 % ~ c c}. (This ++would not work for fixed-point mode, but it wouldn't be hard to ++do a full emulation with the help of the @kbd{Z [} and @kbd{Z ]} ++programming commands. @xref{Conditionals in Macros}.) ++ ++@node Calc Mode Line, , Modes Variable, Mode Settings ++@section The Calc Mode Line ++ ++@noindent ++@cindex Mode line indicators ++This section is a summary of all symbols that can appear on the ++Calc mode line, the highlighted bar that appears under the Calc ++stack window (or under an editing window in Embedded mode). ++ ++The basic mode line format is: ++ ++@example ++--%*-Calc: 12 Deg @var{other modes} (Calculator) ++@end example ++ ++The @samp{%*} indicates that the buffer is ``read-only''; it shows that ++regular Emacs commands are not allowed to edit the stack buffer ++as if it were text. ++ ++The word @samp{Calc:} changes to @samp{CalcEmbed:} if Embedded mode ++is enabled. The words after this describe the various Calc modes ++that are in effect. ++ ++The first mode is always the current precision, an integer. ++The second mode is always the angular mode, either @code{Deg}, ++@code{Rad}, or @code{Hms}. ++ ++Here is a complete list of the remaining symbols that can appear ++on the mode line: ++ ++@table @code ++@item Alg ++Algebraic mode (@kbd{m a}; @pxref{Algebraic Entry}). ++ ++@item Alg[( ++Incomplete algebraic mode (@kbd{C-u m a}). ++ ++@item Alg* ++Total algebraic mode (@kbd{m t}). ++ ++@item Symb ++Symbolic mode (@kbd{m s}; @pxref{Symbolic Mode}). ++ ++@item Matrix ++Matrix mode (@kbd{m v}; @pxref{Matrix Mode}). ++ ++@item Matrix@var{n} ++Dimensioned Matrix mode (@kbd{C-u @var{n} m v}; @pxref{Matrix Mode}). ++ ++@item SqMatrix ++Square Matrix mode (@kbd{C-u m v}; @pxref{Matrix Mode}). ++ ++@item Scalar ++Scalar mode (@kbd{m v}; @pxref{Matrix Mode}). ++ ++@item Polar ++Polar complex mode (@kbd{m p}; @pxref{Polar Mode}). ++ ++@item Frac ++Fraction mode (@kbd{m f}; @pxref{Fraction Mode}). ++ ++@item Inf ++Infinite mode (@kbd{m i}; @pxref{Infinite Mode}). ++ ++@item +Inf ++Positive Infinite mode (@kbd{C-u 0 m i}). ++ ++@item NoSimp ++Default simplifications off (@kbd{m O}; @pxref{Simplification Modes}). ++ ++@item NumSimp ++Default simplifications for numeric arguments only (@kbd{m N}). ++ ++@item BinSimp@var{w} ++Binary-integer simplification mode; word size @var{w} (@kbd{m B}, @kbd{b w}). ++ ++@item AlgSimp ++Algebraic simplification mode (@kbd{m A}). ++ ++@item ExtSimp ++Extended algebraic simplification mode (@kbd{m E}). ++ ++@item UnitSimp ++Units simplification mode (@kbd{m U}). ++ ++@item Bin ++Current radix is 2 (@kbd{d 2}; @pxref{Radix Modes}). ++ ++@item Oct ++Current radix is 8 (@kbd{d 8}). ++ ++@item Hex ++Current radix is 16 (@kbd{d 6}). ++ ++@item Radix@var{n} ++Current radix is @var{n} (@kbd{d r}). ++ ++@item Zero ++Leading zeros (@kbd{d z}; @pxref{Radix Modes}). ++ ++@item Big ++Big language mode (@kbd{d B}; @pxref{Normal Language Modes}). ++ ++@item Flat ++One-line normal language mode (@kbd{d O}). ++ ++@item Unform ++Unformatted language mode (@kbd{d U}). ++ ++@item C ++C language mode (@kbd{d C}; @pxref{C FORTRAN Pascal}). ++ ++@item Pascal ++Pascal language mode (@kbd{d P}). ++ ++@item Fortran ++FORTRAN language mode (@kbd{d F}). ++ ++@item TeX ++@TeX{} language mode (@kbd{d T}; @pxref{TeX and LaTeX Language Modes}). ++ ++@item LaTeX ++La@TeX{} language mode (@kbd{d L}; @pxref{TeX and LaTeX Language Modes}). ++ ++@item Eqn ++@dfn{Eqn} language mode (@kbd{d E}; @pxref{Eqn Language Mode}). ++ ++@item Math ++Mathematica language mode (@kbd{d M}; @pxref{Mathematica Language Mode}). ++ ++@item Maple ++Maple language mode (@kbd{d W}; @pxref{Maple Language Mode}). ++ ++@item Norm@var{n} ++Normal float mode with @var{n} digits (@kbd{d n}; @pxref{Float Formats}). ++ ++@item Fix@var{n} ++Fixed point mode with @var{n} digits after the point (@kbd{d f}). ++ ++@item Sci ++Scientific notation mode (@kbd{d s}). ++ ++@item Sci@var{n} ++Scientific notation with @var{n} digits (@kbd{d s}). ++ ++@item Eng ++Engineering notation mode (@kbd{d e}). ++ ++@item Eng@var{n} ++Engineering notation with @var{n} digits (@kbd{d e}). ++ ++@item Left@var{n} ++Left-justified display indented by @var{n} (@kbd{d <}; @pxref{Justification}). ++ ++@item Right ++Right-justified display (@kbd{d >}). ++ ++@item Right@var{n} ++Right-justified display with width @var{n} (@kbd{d >}). ++ ++@item Center ++Centered display (@kbd{d =}). ++ ++@item Center@var{n} ++Centered display with center column @var{n} (@kbd{d =}). ++ ++@item Wid@var{n} ++Line breaking with width @var{n} (@kbd{d b}; @pxref{Normal Language Modes}). ++ ++@item Wide ++No line breaking (@kbd{d b}). ++ ++@item Break ++Selections show deep structure (@kbd{j b}; @pxref{Making Selections}). ++ ++@item Save ++Record modes in @file{~/.calc.el} (@kbd{m R}; @pxref{General Mode Commands}). ++ ++@item Local ++Record modes in Embedded buffer (@kbd{m R}). ++ ++@item LocEdit ++Record modes as editing-only in Embedded buffer (@kbd{m R}). ++ ++@item LocPerm ++Record modes as permanent-only in Embedded buffer (@kbd{m R}). ++ ++@item Global ++Record modes as global in Embedded buffer (@kbd{m R}). ++ ++@item Manual ++Automatic recomputation turned off (@kbd{m C}; @pxref{Automatic ++Recomputation}). ++ ++@item Graph ++GNUPLOT process is alive in background (@pxref{Graphics}). ++ ++@item Sel ++Top-of-stack has a selection (Embedded only; @pxref{Making Selections}). ++ ++@item Dirty ++The stack display may not be up-to-date (@pxref{Display Modes}). ++ ++@item Inv ++``Inverse'' prefix was pressed (@kbd{I}; @pxref{Inverse and Hyperbolic}). ++ ++@item Hyp ++``Hyperbolic'' prefix was pressed (@kbd{H}). ++ ++@item Keep ++``Keep-arguments'' prefix was pressed (@kbd{K}). ++ ++@item Narrow ++Stack is truncated (@kbd{d t}; @pxref{Truncating the Stack}). ++@end table ++ ++In addition, the symbols @code{Active} and @code{~Active} can appear ++as minor modes on an Embedded buffer's mode line. @xref{Embedded Mode}. ++ ++@node Arithmetic, Scientific Functions, Mode Settings, Top ++@chapter Arithmetic Functions ++ ++@noindent ++This chapter describes the Calc commands for doing simple calculations ++on numbers, such as addition, absolute value, and square roots. These ++commands work by removing the top one or two values from the stack, ++performing the desired operation, and pushing the result back onto the ++stack. If the operation cannot be performed, the result pushed is a ++formula instead of a number, such as @samp{2/0} (because division by zero ++is invalid) or @samp{sqrt(x)} (because the argument @samp{x} is a formula). ++ ++Most of the commands described here can be invoked by a single keystroke. ++Some of the more obscure ones are two-letter sequences beginning with ++the @kbd{f} (``functions'') prefix key. ++ ++@xref{Prefix Arguments}, for a discussion of the effect of numeric ++prefix arguments on commands in this chapter which do not otherwise ++interpret a prefix argument. ++ ++@menu ++* Basic Arithmetic:: ++* Integer Truncation:: ++* Complex Number Functions:: ++* Conversions:: ++* Date Arithmetic:: ++* Financial Functions:: ++* Binary Functions:: ++@end menu ++ ++@node Basic Arithmetic, Integer Truncation, Arithmetic, Arithmetic ++@section Basic Arithmetic ++ ++@noindent ++@kindex + ++@pindex calc-plus ++@ignore ++@mindex @null ++@end ignore ++@tindex + ++The @kbd{+} (@code{calc-plus}) command adds two numbers. The numbers may ++be any of the standard Calc data types. The resulting sum is pushed back ++onto the stack. ++ ++If both arguments of @kbd{+} are vectors or matrices (of matching dimensions), ++the result is a vector or matrix sum. If one argument is a vector and the ++other a scalar (i.e., a non-vector), the scalar is added to each of the ++elements of the vector to form a new vector. If the scalar is not a ++number, the operation is left in symbolic form: Suppose you added @samp{x} ++to the vector @samp{[1,2]}. You may want the result @samp{[1+x,2+x]}, or ++you may plan to substitute a 2-vector for @samp{x} in the future. Since ++the Calculator can't tell which interpretation you want, it makes the ++safest assumption. @xref{Reducing and Mapping}, for a way to add @samp{x} ++to every element of a vector. ++ ++If either argument of @kbd{+} is a complex number, the result will in general ++be complex. If one argument is in rectangular form and the other polar, ++the current Polar mode determines the form of the result. If Symbolic ++mode is enabled, the sum may be left as a formula if the necessary ++conversions for polar addition are non-trivial. ++ ++If both arguments of @kbd{+} are HMS forms, the forms are added according to ++the usual conventions of hours-minutes-seconds notation. If one argument ++is an HMS form and the other is a number, that number is converted from ++degrees or radians (depending on the current Angular mode) to HMS format ++and then the two HMS forms are added. ++ ++If one argument of @kbd{+} is a date form, the other can be either a ++real number, which advances the date by a certain number of days, or ++an HMS form, which advances the date by a certain amount of time. ++Subtracting two date forms yields the number of days between them. ++Adding two date forms is meaningless, but Calc interprets it as the ++subtraction of one date form and the negative of the other. (The ++negative of a date form can be understood by remembering that dates ++are stored as the number of days before or after Jan 1, 1 AD.) ++ ++If both arguments of @kbd{+} are error forms, the result is an error form ++with an appropriately computed standard deviation. If one argument is an ++error form and the other is a number, the number is taken to have zero error. ++Error forms may have symbolic formulas as their mean and/or error parts; ++adding these will produce a symbolic error form result. However, adding an ++error form to a plain symbolic formula (as in @samp{(a +/- b) + c}) will not ++work, for the same reasons just mentioned for vectors. Instead you must ++write @samp{(a +/- b) + (c +/- 0)}. ++ ++If both arguments of @kbd{+} are modulo forms with equal values of @expr{M}, ++or if one argument is a modulo form and the other a plain number, the ++result is a modulo form which represents the sum, modulo @expr{M}, of ++the two values. ++ ++If both arguments of @kbd{+} are intervals, the result is an interval ++which describes all possible sums of the possible input values. If ++one argument is a plain number, it is treated as the interval ++@w{@samp{[x ..@: x]}}. ++ ++If one argument of @kbd{+} is an infinity and the other is not, the ++result is that same infinity. If both arguments are infinite and in ++the same direction, the result is the same infinity, but if they are ++infinite in different directions the result is @code{nan}. ++ ++@kindex - ++@pindex calc-minus ++@ignore ++@mindex @null ++@end ignore ++@tindex - ++The @kbd{-} (@code{calc-minus}) command subtracts two values. The top ++number on the stack is subtracted from the one behind it, so that the ++computation @kbd{5 @key{RET} 2 -} produces 3, not @mathit{-3}. All options ++available for @kbd{+} are available for @kbd{-} as well. ++ ++@kindex * ++@pindex calc-times ++@ignore ++@mindex @null ++@end ignore ++@tindex * ++The @kbd{*} (@code{calc-times}) command multiplies two numbers. If one ++argument is a vector and the other a scalar, the scalar is multiplied by ++the elements of the vector to produce a new vector. If both arguments ++are vectors, the interpretation depends on the dimensions of the ++vectors: If both arguments are matrices, a matrix multiplication is ++done. If one argument is a matrix and the other a plain vector, the ++vector is interpreted as a row vector or column vector, whichever is ++dimensionally correct. If both arguments are plain vectors, the result ++is a single scalar number which is the dot product of the two vectors. ++ ++If one argument of @kbd{*} is an HMS form and the other a number, the ++HMS form is multiplied by that amount. It is an error to multiply two ++HMS forms together, or to attempt any multiplication involving date ++forms. Error forms, modulo forms, and intervals can be multiplied; ++see the comments for addition of those forms. When two error forms ++or intervals are multiplied they are considered to be statistically ++independent; thus, @samp{[-2 ..@: 3] * [-2 ..@: 3]} is @samp{[-6 ..@: 9]}, ++whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}. ++ ++@kindex / ++@pindex calc-divide ++@ignore ++@mindex @null ++@end ignore ++@tindex / ++The @kbd{/} (@code{calc-divide}) command divides two numbers. ++ ++When combining multiplication and division in an algebraic formula, it ++is good style to use parentheses to distinguish between possible ++interpretations; the expression @samp{a/b*c} should be written ++@samp{(a/b)*c} or @samp{a/(b*c)}, as appropriate. Without the ++parentheses, Calc will interpret @samp{a/b*c} as @samp{a/(b*c)}, since ++in algebraic entry Calc gives division a lower precedence than ++multiplication. (This is not standard across all computer languages, and ++Calc may change the precedence depending on the language mode being used. ++@xref{Language Modes}.) This default ordering can be changed by setting ++the customizable variable @code{calc-multiplication-has-precedence} to ++@code{nil} (@pxref{Customizing Calc}); this will give multiplication and ++division equal precedences. Note that Calc's default choice of ++precedence allows @samp{a b / c d} to be used as a shortcut for ++@smallexample ++@group ++a b ++---. ++c d ++@end group ++@end smallexample ++ ++When dividing a scalar @expr{B} by a square matrix @expr{A}, the ++computation performed is @expr{B} times the inverse of @expr{A}. This ++also occurs if @expr{B} is itself a vector or matrix, in which case the ++effect is to solve the set of linear equations represented by @expr{B}. ++If @expr{B} is a matrix with the same number of rows as @expr{A}, or a ++plain vector (which is interpreted here as a column vector), then the ++equation @expr{A X = B} is solved for the vector or matrix @expr{X}. ++Otherwise, if @expr{B} is a non-square matrix with the same number of ++@emph{columns} as @expr{A}, the equation @expr{X A = B} is solved. If ++you wish a vector @expr{B} to be interpreted as a row vector to be ++solved as @expr{X A = B}, make it into a one-row matrix with @kbd{C-u 1 ++v p} first. To force a left-handed solution with a square matrix ++@expr{B}, transpose @expr{A} and @expr{B} before dividing, then ++transpose the result. ++ ++HMS forms can be divided by real numbers or by other HMS forms. Error ++forms can be divided in any combination of ways. Modulo forms where both ++values and the modulo are integers can be divided to get an integer modulo ++form result. Intervals can be divided; dividing by an interval that ++encompasses zero or has zero as a limit will result in an infinite ++interval. ++ ++@kindex ^ ++@pindex calc-power ++@ignore ++@mindex @null ++@end ignore ++@tindex ^ ++The @kbd{^} (@code{calc-power}) command raises a number to a power. If ++the power is an integer, an exact result is computed using repeated ++multiplications. For non-integer powers, Calc uses Newton's method or ++logarithms and exponentials. Square matrices can be raised to integer ++powers. If either argument is an error (or interval or modulo) form, ++the result is also an error (or interval or modulo) form. ++ ++@kindex I ^ ++@tindex nroot ++If you press the @kbd{I} (inverse) key first, the @kbd{I ^} command ++computes an Nth root: @kbd{125 @key{RET} 3 I ^} computes the number 5. ++(This is entirely equivalent to @kbd{125 @key{RET} 1:3 ^}.) ++ ++@kindex \ ++@pindex calc-idiv ++@tindex idiv ++@ignore ++@mindex @null ++@end ignore ++@tindex \ ++The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack ++to produce an integer result. It is equivalent to dividing with ++@key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit ++more convenient and efficient. Also, since it is an all-integer ++operation when the arguments are integers, it avoids problems that ++@kbd{/ F} would have with floating-point roundoff. ++ ++@kindex % ++@pindex calc-mod ++@ignore ++@mindex @null ++@end ignore ++@tindex % ++The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'') ++operation. Mathematically, @samp{a%b = a - (a\b)*b}, and is defined ++for all real numbers @expr{a} and @expr{b} (except @expr{b=0}). For ++positive @expr{b}, the result will always be between 0 (inclusive) and ++@expr{b} (exclusive). Modulo does not work for HMS forms and error forms. ++If @expr{a} is a modulo form, its modulo is changed to @expr{b}, which ++must be positive real number. ++ ++@kindex : ++@pindex calc-fdiv ++@tindex fdiv ++The @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command ++divides the two integers on the top of the stack to produce a fractional ++result. This is a convenient shorthand for enabling Fraction mode (with ++@kbd{m f}) temporarily and using @samp{/}. Note that during numeric entry ++the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6 ++you would have to type @kbd{8 @key{RET} 6 @key{RET} :}. (Of course, in ++this case, it would be much easier simply to enter the fraction directly ++as @kbd{8:6 @key{RET}}!) ++ ++@kindex n ++@pindex calc-change-sign ++The @kbd{n} (@code{calc-change-sign}) command negates the number on the top ++of the stack. It works on numbers, vectors and matrices, HMS forms, date ++forms, error forms, intervals, and modulo forms. ++ ++@kindex A ++@pindex calc-abs ++@tindex abs ++The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute ++value of a number. The result of @code{abs} is always a nonnegative ++real number: With a complex argument, it computes the complex magnitude. ++With a vector or matrix argument, it computes the Frobenius norm, i.e., ++the square root of the sum of the squares of the absolute values of the ++elements. The absolute value of an error form is defined by replacing ++the mean part with its absolute value and leaving the error part the same. ++The absolute value of a modulo form is undefined. The absolute value of ++an interval is defined in the obvious way. ++ ++@kindex f A ++@pindex calc-abssqr ++@tindex abssqr ++The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the ++absolute value squared of a number, vector or matrix, or error form. ++ ++@kindex f s ++@pindex calc-sign ++@tindex sign ++The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its ++argument is positive, @mathit{-1} if its argument is negative, or 0 if its ++argument is zero. In algebraic form, you can also write @samp{sign(a,x)} ++which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or ++zero depending on the sign of @samp{a}. ++ ++@kindex & ++@pindex calc-inv ++@tindex inv ++@cindex Reciprocal ++The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the ++reciprocal of a number, i.e., @expr{1 / x}. Operating on a square ++matrix, it computes the inverse of that matrix. ++ ++@kindex Q ++@pindex calc-sqrt ++@tindex sqrt ++The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square ++root of a number. For a negative real argument, the result will be a ++complex number whose form is determined by the current Polar mode. ++ ++@kindex f h ++@pindex calc-hypot ++@tindex hypot ++The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square ++root of the sum of the squares of two numbers. That is, @samp{hypot(a,b)} ++is the length of the hypotenuse of a right triangle with sides @expr{a} ++and @expr{b}. If the arguments are complex numbers, their squared ++magnitudes are used. ++ ++@kindex f Q ++@pindex calc-isqrt ++@tindex isqrt ++The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the ++integer square root of an integer. This is the true square root of the ++number, rounded down to an integer. For example, @samp{isqrt(10)} ++produces 3. Note that, like @kbd{\} [@code{idiv}], this uses exact ++integer arithmetic throughout to avoid roundoff problems. If the input ++is a floating-point number or other non-integer value, this is exactly ++the same as @samp{floor(sqrt(x))}. ++ ++@kindex f n ++@kindex f x ++@pindex calc-min ++@tindex min ++@pindex calc-max ++@tindex max ++The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max}) ++[@code{max}] commands take the minimum or maximum of two real numbers, ++respectively. These commands also work on HMS forms, date forms, ++intervals, and infinities. (In algebraic expressions, these functions ++take any number of arguments and return the maximum or minimum among ++all the arguments.) ++ ++@kindex f M ++@kindex f X ++@pindex calc-mant-part ++@tindex mant ++@pindex calc-xpon-part ++@tindex xpon ++The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts ++the ``mantissa'' part @expr{m} of its floating-point argument; @kbd{f X} ++(@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part ++@expr{e}. The original number is equal to ++@texline @math{m \times 10^e}, ++@infoline @expr{m * 10^e}, ++where @expr{m} is in the interval @samp{[1.0 ..@: 10.0)} except that ++@expr{m=e=0} if the original number is zero. For integers ++and fractions, @code{mant} returns the number unchanged and @code{xpon} ++returns zero. The @kbd{v u} (@code{calc-unpack}) command can also be ++used to ``unpack'' a floating-point number; this produces an integer ++mantissa and exponent, with the constraint that the mantissa is not ++a multiple of ten (again except for the @expr{m=e=0} case). ++ ++@kindex f S ++@pindex calc-scale-float ++@tindex scf ++The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number ++by a given power of ten. Thus, @samp{scf(mant(x), xpon(x)) = x} for any ++real @samp{x}. The second argument must be an integer, but the first ++may actually be any numeric value. For example, @samp{scf(5,-2) = 0.05} ++or @samp{1:20} depending on the current Fraction mode. ++ ++@kindex f [ ++@kindex f ] ++@pindex calc-decrement ++@pindex calc-increment ++@tindex decr ++@tindex incr ++The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]} ++(@code{calc-increment}) [@code{incr}] functions decrease or increase ++a number by one unit. For integers, the effect is obvious. For ++floating-point numbers, the change is by one unit in the last place. ++For example, incrementing @samp{12.3456} when the current precision ++is 6 digits yields @samp{12.3457}. If the current precision had been ++8 digits, the result would have been @samp{12.345601}. Incrementing ++@samp{0.0} produces ++@texline @math{10^{-p}}, ++@infoline @expr{10^-p}, ++where @expr{p} is the current ++precision. These operations are defined only on integers and floats. ++With numeric prefix arguments, they change the number by @expr{n} units. ++ ++Note that incrementing followed by decrementing, or vice-versa, will ++almost but not quite always cancel out. Suppose the precision is ++6 digits and the number @samp{9.99999} is on the stack. Incrementing ++will produce @samp{10.0000}; decrementing will produce @samp{9.9999}. ++One digit has been dropped. This is an unavoidable consequence of the ++way floating-point numbers work. ++ ++Incrementing a date/time form adjusts it by a certain number of seconds. ++Incrementing a pure date form adjusts it by a certain number of days. ++ ++@node Integer Truncation, Complex Number Functions, Basic Arithmetic, Arithmetic ++@section Integer Truncation ++ ++@noindent ++There are four commands for truncating a real number to an integer, ++differing mainly in their treatment of negative numbers. All of these ++commands have the property that if the argument is an integer, the result ++is the same integer. An integer-valued floating-point argument is converted ++to integer form. ++ ++If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be ++expressed as an integer-valued floating-point number. ++ ++@cindex Integer part of a number ++@kindex F ++@pindex calc-floor ++@tindex floor ++@tindex ffloor ++@ignore ++@mindex @null ++@end ignore ++@kindex H F ++The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command ++truncates a real number to the next lower integer, i.e., toward minus ++infinity. Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces ++@mathit{-4}. ++ ++@kindex I F ++@pindex calc-ceiling ++@tindex ceil ++@tindex fceil ++@ignore ++@mindex @null ++@end ignore ++@kindex H I F ++The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}] ++command truncates toward positive infinity. Thus @kbd{3.6 I F} produces ++4, and @kbd{_3.6 I F} produces @mathit{-3}. ++ ++@kindex R ++@pindex calc-round ++@tindex round ++@tindex fround ++@ignore ++@mindex @null ++@end ignore ++@kindex H R ++The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command ++rounds to the nearest integer. When the fractional part is .5 exactly, ++this command rounds away from zero. (All other rounding in the ++Calculator uses this convention as well.) Thus @kbd{3.5 R} produces 4 ++but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @mathit{-4}. ++ ++@kindex I R ++@pindex calc-trunc ++@tindex trunc ++@tindex ftrunc ++@ignore ++@mindex @null ++@end ignore ++@kindex H I R ++The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}] ++command truncates toward zero. In other words, it ``chops off'' ++everything after the decimal point. Thus @kbd{3.6 I R} produces 3 and ++@kbd{_3.6 I R} produces @mathit{-3}. ++ ++These functions may not be applied meaningfully to error forms, but they ++do work for intervals. As a convenience, applying @code{floor} to a ++modulo form floors the value part of the form. Applied to a vector, ++these functions operate on all elements of the vector one by one. ++Applied to a date form, they operate on the internal numerical ++representation of dates, converting a date/time form into a pure date. ++ ++@ignore ++@starindex ++@end ignore ++@tindex rounde ++@ignore ++@starindex ++@end ignore ++@tindex roundu ++@ignore ++@starindex ++@end ignore ++@tindex frounde ++@ignore ++@starindex ++@end ignore ++@tindex froundu ++There are two more rounding functions which can only be entered in ++algebraic notation. The @code{roundu} function is like @code{round} ++except that it rounds up, toward plus infinity, when the fractional ++part is .5. This distinction matters only for negative arguments. ++Also, @code{rounde} rounds to an even number in the case of a tie, ++rounding up or down as necessary. For example, @samp{rounde(3.5)} and ++@samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6. ++The advantage of round-to-even is that the net error due to rounding ++after a long calculation tends to cancel out to zero. An important ++subtle point here is that the number being fed to @code{rounde} will ++already have been rounded to the current precision before @code{rounde} ++begins. For example, @samp{rounde(2.500001)} with a current precision ++of 6 will incorrectly, or at least surprisingly, yield 2 because the ++argument will first have been rounded down to @expr{2.5} (which ++@code{rounde} sees as an exact tie between 2 and 3). ++ ++Each of these functions, when written in algebraic formulas, allows ++a second argument which specifies the number of digits after the ++decimal point to keep. For example, @samp{round(123.4567, 2)} will ++produce the answer 123.46, and @samp{round(123.4567, -1)} will ++produce 120 (i.e., the cutoff is one digit to the @emph{left} of ++the decimal point). A second argument of zero is equivalent to ++no second argument at all. ++ ++@cindex Fractional part of a number ++To compute the fractional part of a number (i.e., the amount which, when ++added to `@tfn{floor(}@var{n}@tfn{)}', will produce @var{n}) just take @var{n} ++modulo 1 using the @code{%} command. ++ ++Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm), ++and @kbd{f Q} (integer square root) commands, which are analogous to ++@kbd{/}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer ++arguments and return the result rounded down to an integer. ++ ++@node Complex Number Functions, Conversions, Integer Truncation, Arithmetic ++@section Complex Number Functions ++ ++@noindent ++@kindex J ++@pindex calc-conj ++@tindex conj ++The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the ++complex conjugate of a number. For complex number @expr{a+bi}, the ++complex conjugate is @expr{a-bi}. If the argument is a real number, ++this command leaves it the same. If the argument is a vector or matrix, ++this command replaces each element by its complex conjugate. ++ ++@kindex G ++@pindex calc-argument ++@tindex arg ++The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the ++``argument'' or polar angle of a complex number. For a number in polar ++notation, this is simply the second component of the pair ++@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'. ++@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'. ++The result is expressed according to the current angular mode and will ++be in the range @mathit{-180} degrees (exclusive) to @mathit{+180} degrees ++(inclusive), or the equivalent range in radians. ++ ++@pindex calc-imaginary ++The @code{calc-imaginary} command multiplies the number on the ++top of the stack by the imaginary number @expr{i = (0,1)}. This ++command is not normally bound to a key in Calc, but it is available ++on the @key{IMAG} button in Keypad mode. ++ ++@kindex f r ++@pindex calc-re ++@tindex re ++The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number ++by its real part. This command has no effect on real numbers. (As an ++added convenience, @code{re} applied to a modulo form extracts ++the value part.) ++ ++@kindex f i ++@pindex calc-im ++@tindex im ++The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number ++by its imaginary part; real numbers are converted to zero. With a vector ++or matrix argument, these functions operate element-wise. ++ ++@ignore ++@mindex v p ++@end ignore ++@kindex v p (complex) ++@pindex calc-pack ++The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on ++the stack into a composite object such as a complex number. With ++a prefix argument of @mathit{-1}, it produces a rectangular complex number; ++with an argument of @mathit{-2}, it produces a polar complex number. ++(Also, @pxref{Building Vectors}.) ++ ++@ignore ++@mindex v u ++@end ignore ++@kindex v u (complex) ++@pindex calc-unpack ++The @kbd{v u} (@code{calc-unpack}) command takes the complex number ++(or other composite object) on the top of the stack and unpacks it ++into its separate components. ++ ++@node Conversions, Date Arithmetic, Complex Number Functions, Arithmetic ++@section Conversions ++ ++@noindent ++The commands described in this section convert numbers from one form ++to another; they are two-key sequences beginning with the letter @kbd{c}. ++ ++@kindex c f ++@pindex calc-float ++@tindex pfloat ++The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the ++number on the top of the stack to floating-point form. For example, ++@expr{23} is converted to @expr{23.0}, @expr{3:2} is converted to ++@expr{1.5}, and @expr{2.3} is left the same. If the value is a composite ++object such as a complex number or vector, each of the components is ++converted to floating-point. If the value is a formula, all numbers ++in the formula are converted to floating-point. Note that depending ++on the current floating-point precision, conversion to floating-point ++format may lose information. ++ ++As a special exception, integers which appear as powers or subscripts ++are not floated by @kbd{c f}. If you really want to float a power, ++you can use a @kbd{j s} command to select the power followed by @kbd{c f}. ++Because @kbd{c f} cannot examine the formula outside of the selection, ++it does not notice that the thing being floated is a power. ++@xref{Selecting Subformulas}. ++ ++The normal @kbd{c f} command is ``pervasive'' in the sense that it ++applies to all numbers throughout the formula. The @code{pfloat} ++algebraic function never stays around in a formula; @samp{pfloat(a + 1)} ++changes to @samp{a + 1.0} as soon as it is evaluated. ++ ++@kindex H c f ++@tindex float ++With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates ++only on the number or vector of numbers at the top level of its ++argument. Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)} ++is left unevaluated because its argument is not a number. ++ ++You should use @kbd{H c f} if you wish to guarantee that the final ++value, once all the variables have been assigned, is a float; you ++would use @kbd{c f} if you wish to do the conversion on the numbers ++that appear right now. ++ ++@kindex c F ++@pindex calc-fraction ++@tindex pfrac ++The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a ++floating-point number into a fractional approximation. By default, it ++produces a fraction whose decimal representation is the same as the ++input number, to within the current precision. You can also give a ++numeric prefix argument to specify a tolerance, either directly, or, ++if the prefix argument is zero, by using the number on top of the stack ++as the tolerance. If the tolerance is a positive integer, the fraction ++is correct to within that many significant figures. If the tolerance is ++a non-positive integer, it specifies how many digits fewer than the current ++precision to use. If the tolerance is a floating-point number, the ++fraction is correct to within that absolute amount. ++ ++@kindex H c F ++@tindex frac ++The @code{pfrac} function is pervasive, like @code{pfloat}. ++There is also a non-pervasive version, @kbd{H c F} [@code{frac}], ++which is analogous to @kbd{H c f} discussed above. ++ ++@kindex c d ++@pindex calc-to-degrees ++@tindex deg ++The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a ++number into degrees form. The value on the top of the stack may be an ++HMS form (interpreted as degrees-minutes-seconds), or a real number which ++will be interpreted in radians regardless of the current angular mode. ++ ++@kindex c r ++@pindex calc-to-radians ++@tindex rad ++The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an ++HMS form or angle in degrees into an angle in radians. ++ ++@kindex c h ++@pindex calc-to-hms ++@tindex hms ++The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real ++number, interpreted according to the current angular mode, to an HMS ++form describing the same angle. In algebraic notation, the @code{hms} ++function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}. ++(The three-argument version is independent of the current angular mode.) ++ ++@pindex calc-from-hms ++The @code{calc-from-hms} command converts the HMS form on the top of the ++stack into a real number according to the current angular mode. ++ ++@kindex c p ++@kindex I c p ++@pindex calc-polar ++@tindex polar ++@tindex rect ++The @kbd{c p} (@code{calc-polar}) command converts the complex number on ++the top of the stack from polar to rectangular form, or from rectangular ++to polar form, whichever is appropriate. Real numbers are left the same. ++This command is equivalent to the @code{rect} or @code{polar} ++functions in algebraic formulas, depending on the direction of ++conversion. (It uses @code{polar}, except that if the argument is ++already a polar complex number, it uses @code{rect} instead. The ++@kbd{I c p} command always uses @code{rect}.) ++ ++@kindex c c ++@pindex calc-clean ++@tindex pclean ++The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the ++number on the top of the stack. Floating point numbers are re-rounded ++according to the current precision. Polar numbers whose angular ++components have strayed from the @mathit{-180} to @mathit{+180} degree range ++are normalized. (Note that results will be undesirable if the current ++angular mode is different from the one under which the number was ++produced!) Integers and fractions are generally unaffected by this ++operation. Vectors and formulas are cleaned by cleaning each component ++number (i.e., pervasively). ++ ++If the simplification mode is set below the default level, it is raised ++to the default level for the purposes of this command. Thus, @kbd{c c} ++applies the default simplifications even if their automatic application ++is disabled. @xref{Simplification Modes}. ++ ++@cindex Roundoff errors, correcting ++A numeric prefix argument to @kbd{c c} sets the floating-point precision ++to that value for the duration of the command. A positive prefix (of at ++least 3) sets the precision to the specified value; a negative or zero ++prefix decreases the precision by the specified amount. ++ ++@kindex c 0-9 ++@pindex calc-clean-num ++The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent ++to @kbd{c c} with the corresponding negative prefix argument. If roundoff ++errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one ++decimal place often conveniently does the trick. ++ ++The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0} ++through @kbd{c 9} commands, also ``clip'' very small floating-point ++numbers to zero. If the exponent is less than or equal to the negative ++of the specified precision, the number is changed to 0.0. For example, ++if the current precision is 12, then @kbd{c 2} changes the vector ++@samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0, 0]}. ++Numbers this small generally arise from roundoff noise. ++ ++If the numbers you are using really are legitimately this small, ++you should avoid using the @kbd{c 0} through @kbd{c 9} commands. ++(The plain @kbd{c c} command rounds to the current precision but ++does not clip small numbers.) ++ ++One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with ++a prefix argument, is that integer-valued floats are converted to ++plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]} ++produces @samp{[1, 1.5, 2, 2.5, 3]}. This is not done for huge ++numbers (@samp{1e100} is technically an integer-valued float, but ++you wouldn't want it automatically converted to a 100-digit integer). ++ ++@kindex H c 0-9 ++@kindex H c c ++@tindex clean ++With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9} ++operate non-pervasively [@code{clean}]. ++ ++@node Date Arithmetic, Financial Functions, Conversions, Arithmetic ++@section Date Arithmetic ++ ++@noindent ++@cindex Date arithmetic, additional functions ++The commands described in this section perform various conversions ++and calculations involving date forms (@pxref{Date Forms}). They ++use the @kbd{t} (for time/date) prefix key followed by shifted ++letters. ++ ++The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-} ++commands. In particular, adding a number to a date form advances the ++date form by a certain number of days; adding an HMS form to a date ++form advances the date by a certain amount of time; and subtracting two ++date forms produces a difference measured in days. The commands ++described here provide additional, more specialized operations on dates. ++ ++Many of these commands accept a numeric prefix argument; if you give ++plain @kbd{C-u} as the prefix, these commands will instead take the ++additional argument from the top of the stack. ++ ++@menu ++* Date Conversions:: ++* Date Functions:: ++* Time Zones:: ++* Business Days:: ++@end menu ++ ++@node Date Conversions, Date Functions, Date Arithmetic, Date Arithmetic ++@subsection Date Conversions ++ ++@noindent ++@kindex t D ++@pindex calc-date ++@tindex date ++The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a ++date form into a number, measured in days since Jan 1, 1 AD. The ++result will be an integer if @var{date} is a pure date form, or a ++fraction or float if @var{date} is a date/time form. Or, if its ++argument is a number, it converts this number into a date form. ++ ++With a numeric prefix argument, @kbd{t D} takes that many objects ++(up to six) from the top of the stack and interprets them in one ++of the following ways: ++ ++The @samp{date(@var{year}, @var{month}, @var{day})} function ++builds a pure date form out of the specified year, month, and ++day, which must all be integers. @var{Year} is a year number, ++such as 1991 (@emph{not} the same as 91!). @var{Month} must be ++an integer in the range 1 to 12; @var{day} must be in the range ++1 to 31. If the specified month has fewer than 31 days and ++@var{day} is too large, the equivalent day in the following ++month will be used. ++ ++The @samp{date(@var{month}, @var{day})} function builds a ++pure date form using the current year, as determined by the ++real-time clock. ++ ++The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})} ++function builds a date/time form using an @var{hms} form. ++ ++The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour}, ++@var{minute}, @var{second})} function builds a date/time form. ++@var{hour} should be an integer in the range 0 to 23; ++@var{minute} should be an integer in the range 0 to 59; ++@var{second} should be any real number in the range @samp{[0 .. 60)}. ++The last two arguments default to zero if omitted. ++ ++@kindex t J ++@pindex calc-julian ++@tindex julian ++@cindex Julian day counts, conversions ++The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts ++a date form into a Julian day count, which is the number of days ++since noon (GMT) on Jan 1, 4713 BC. A pure date is converted to an ++integer Julian count representing noon of that day. A date/time form ++is converted to an exact floating-point Julian count, adjusted to ++interpret the date form in the current time zone but the Julian ++day count in Greenwich Mean Time. A numeric prefix argument allows ++you to specify the time zone; @pxref{Time Zones}. Use a prefix of ++zero to suppress the time zone adjustment. Note that pure date forms ++are never time-zone adjusted. ++ ++This command can also do the opposite conversion, from a Julian day ++count (either an integer day, or a floating-point day and time in ++the GMT zone), into a pure date form or a date/time form in the ++current or specified time zone. ++ ++@kindex t U ++@pindex calc-unix-time ++@tindex unixtime ++@cindex Unix time format, conversions ++The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command ++converts a date form into a Unix time value, which is the number of ++seconds since midnight on Jan 1, 1970, or vice-versa. The numeric result ++will be an integer if the current precision is 12 or less; for higher ++precisions, the result may be a float with (@var{precision}@minus{}12) ++digits after the decimal. Just as for @kbd{t J}, the numeric time ++is interpreted in the GMT time zone and the date form is interpreted ++in the current or specified zone. Some systems use Unix-like ++numbering but with the local time zone; give a prefix of zero to ++suppress the adjustment if so. ++ ++@kindex t C ++@pindex calc-convert-time-zones ++@tindex tzconv ++@cindex Time Zones, converting between ++The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}] ++command converts a date form from one time zone to another. You ++are prompted for each time zone name in turn; you can answer with ++any suitable Calc time zone expression (@pxref{Time Zones}). ++If you answer either prompt with a blank line, the local time ++zone is used for that prompt. You can also answer the first ++prompt with @kbd{$} to take the two time zone names from the ++stack (and the date to be converted from the third stack level). ++ ++@node Date Functions, Business Days, Date Conversions, Date Arithmetic ++@subsection Date Functions ++ ++@noindent ++@kindex t N ++@pindex calc-now ++@tindex now ++The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the ++current date and time on the stack as a date form. The time is ++reported in terms of the specified time zone; with no numeric prefix ++argument, @kbd{t N} reports for the current time zone. ++ ++@kindex t P ++@pindex calc-date-part ++The @kbd{t P} (@code{calc-date-part}) command extracts one part ++of a date form. The prefix argument specifies the part; with no ++argument, this command prompts for a part code from 1 to 9. ++The various part codes are described in the following paragraphs. ++ ++@tindex year ++The @kbd{M-1 t P} [@code{year}] function extracts the year number ++from a date form as an integer, e.g., 1991. This and the ++following functions will also accept a real number for an ++argument, which is interpreted as a standard Calc day number. ++Note that this function will never return zero, since the year ++1 BC immediately precedes the year 1 AD. ++ ++@tindex month ++The @kbd{M-2 t P} [@code{month}] function extracts the month number ++from a date form as an integer in the range 1 to 12. ++ ++@tindex day ++The @kbd{M-3 t P} [@code{day}] function extracts the day number ++from a date form as an integer in the range 1 to 31. ++ ++@tindex hour ++The @kbd{M-4 t P} [@code{hour}] function extracts the hour from ++a date form as an integer in the range 0 (midnight) to 23. Note ++that 24-hour time is always used. This returns zero for a pure ++date form. This function (and the following two) also accept ++HMS forms as input. ++ ++@tindex minute ++The @kbd{M-5 t P} [@code{minute}] function extracts the minute ++from a date form as an integer in the range 0 to 59. ++ ++@tindex second ++The @kbd{M-6 t P} [@code{second}] function extracts the second ++from a date form. If the current precision is 12 or less, ++the result is an integer in the range 0 to 59. For higher ++precisions, the result may instead be a floating-point number. ++ ++@tindex weekday ++The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday ++number from a date form as an integer in the range 0 (Sunday) ++to 6 (Saturday). ++ ++@tindex yearday ++The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year ++number from a date form as an integer in the range 1 (January 1) ++to 366 (December 31 of a leap year). ++ ++@tindex time ++The @kbd{M-9 t P} [@code{time}] function extracts the time portion ++of a date form as an HMS form. This returns @samp{0@@ 0' 0"} ++for a pure date form. ++ ++@kindex t M ++@pindex calc-new-month ++@tindex newmonth ++The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command ++computes a new date form that represents the first day of the month ++specified by the input date. The result is always a pure date ++form; only the year and month numbers of the input are retained. ++With a numeric prefix argument @var{n} in the range from 1 to 31, ++@kbd{t M} computes the @var{n}th day of the month. (If @var{n} ++is greater than the actual number of days in the month, or if ++@var{n} is zero, the last day of the month is used.) ++ ++@kindex t Y ++@pindex calc-new-year ++@tindex newyear ++The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command ++computes a new pure date form that represents the first day of ++the year specified by the input. The month, day, and time ++of the input date form are lost. With a numeric prefix argument ++@var{n} in the range from 1 to 366, @kbd{t Y} computes the ++@var{n}th day of the year (366 is treated as 365 in non-leap ++years). A prefix argument of 0 computes the last day of the ++year (December 31). A negative prefix argument from @mathit{-1} to ++@mathit{-12} computes the first day of the @var{n}th month of the year. ++ ++@kindex t W ++@pindex calc-new-week ++@tindex newweek ++The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command ++computes a new pure date form that represents the Sunday on or before ++the input date. With a numeric prefix argument, it can be made to ++use any day of the week as the starting day; the argument must be in ++the range from 0 (Sunday) to 6 (Saturday). This function always ++subtracts between 0 and 6 days from the input date. ++ ++Here's an example use of @code{newweek}: Find the date of the next ++Wednesday after a given date. Using @kbd{M-3 t W} or @samp{newweek(d, 3)} ++will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)} ++will give you the following Wednesday. A further look at the definition ++of @code{newweek} shows that if the input date is itself a Wednesday, ++this formula will return the Wednesday one week in the future. An ++exercise for the reader is to modify this formula to yield the same day ++if the input is already a Wednesday. Another interesting exercise is ++to preserve the time-of-day portion of the input (@code{newweek} resets ++the time to midnight; hint:@: how can @code{newweek} be defined in terms ++of the @code{weekday} function?). ++ ++@ignore ++@starindex ++@end ignore ++@tindex pwday ++The @samp{pwday(@var{date})} function (not on any key) computes the ++day-of-month number of the Sunday on or before @var{date}. With ++two arguments, @samp{pwday(@var{date}, @var{day})} computes the day ++number of the Sunday on or before day number @var{day} of the month ++specified by @var{date}. The @var{day} must be in the range from ++7 to 31; if the day number is greater than the actual number of days ++in the month, the true number of days is used instead. Thus ++@samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and ++@samp{pwday(@var{date}, 31)} finds the last Sunday of the month. ++With a third @var{weekday} argument, @code{pwday} can be made to look ++for any day of the week instead of Sunday. ++ ++@kindex t I ++@pindex calc-inc-month ++@tindex incmonth ++The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command ++increases a date form by one month, or by an arbitrary number of ++months specified by a numeric prefix argument. The time portion, ++if any, of the date form stays the same. The day also stays the ++same, except that if the new month has fewer days the day ++number may be reduced to lie in the valid range. For example, ++@samp{incmonth()} produces @samp{}. ++Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give ++the same results (@samp{} versus @samp{} ++in this case). ++ ++@ignore ++@starindex ++@end ignore ++@tindex incyear ++The @samp{incyear(@var{date}, @var{step})} function increases ++a date form by the specified number of years, which may be ++any positive or negative integer. Note that @samp{incyear(d, n)} ++is equivalent to @w{@samp{incmonth(d, 12*n)}}, but these do not have ++simple equivalents in terms of day arithmetic because ++months and years have varying lengths. If the @var{step} ++argument is omitted, 1 year is assumed. There is no keyboard ++command for this function; use @kbd{C-u 12 t I} instead. ++ ++There is no @code{newday} function at all because @kbd{F} [@code{floor}] ++serves this purpose. Similarly, instead of @code{incday} and ++@code{incweek} simply use @expr{d + n} or @expr{d + 7 n}. ++ ++@xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command ++which can adjust a date/time form by a certain number of seconds. ++ ++@node Business Days, Time Zones, Date Functions, Date Arithmetic ++@subsection Business Days ++ ++@noindent ++Often time is measured in ``business days'' or ``working days,'' ++where weekends and holidays are skipped. Calc's normal date ++arithmetic functions use calendar days, so that subtracting two ++consecutive Mondays will yield a difference of 7 days. By contrast, ++subtracting two consecutive Mondays would yield 5 business days ++(assuming two-day weekends and the absence of holidays). ++ ++@kindex t + ++@kindex t - ++@tindex badd ++@tindex bsub ++@pindex calc-business-days-plus ++@pindex calc-business-days-minus ++The @kbd{t +} (@code{calc-business-days-plus}) [@code{badd}] ++and @kbd{t -} (@code{calc-business-days-minus}) [@code{bsub}] ++commands perform arithmetic using business days. For @kbd{t +}, ++one argument must be a date form and the other must be a real ++number (positive or negative). If the number is not an integer, ++then a certain amount of time is added as well as a number of ++days; for example, adding 0.5 business days to a time in Friday ++evening will produce a time in Monday morning. It is also ++possible to add an HMS form; adding @samp{12@@ 0' 0"} also adds ++half a business day. For @kbd{t -}, the arguments are either a ++date form and a number or HMS form, or two date forms, in which ++case the result is the number of business days between the two ++dates. ++ ++@cindex @code{Holidays} variable ++@vindex Holidays ++By default, Calc considers any day that is not a Saturday or ++Sunday to be a business day. You can define any number of ++additional holidays by editing the variable @code{Holidays}. ++(There is an @w{@kbd{s H}} convenience command for editing this ++variable.) Initially, @code{Holidays} contains the vector ++@samp{[sat, sun]}. Entries in the @code{Holidays} vector may ++be any of the following kinds of objects: ++ ++@itemize @bullet ++@item ++Date forms (pure dates, not date/time forms). These specify ++particular days which are to be treated as holidays. ++ ++@item ++Intervals of date forms. These specify a range of days, all of ++which are holidays (e.g., Christmas week). @xref{Interval Forms}. ++ ++@item ++Nested vectors of date forms. Each date form in the vector is ++considered to be a holiday. ++ ++@item ++Any Calc formula which evaluates to one of the above three things. ++If the formula involves the variable @expr{y}, it stands for a ++yearly repeating holiday; @expr{y} will take on various year ++numbers like 1992. For example, @samp{date(y, 12, 25)} specifies ++Christmas day, and @samp{newweek(date(y, 11, 7), 4) + 21} specifies ++Thanksgiving (which is held on the fourth Thursday of November). ++If the formula involves the variable @expr{m}, that variable ++takes on month numbers from 1 to 12: @samp{date(y, m, 15)} is ++a holiday that takes place on the 15th of every month. ++ ++@item ++A weekday name, such as @code{sat} or @code{sun}. This is really ++a variable whose name is a three-letter, lower-case day name. ++ ++@item ++An interval of year numbers (integers). This specifies the span of ++years over which this holiday list is to be considered valid. Any ++business-day arithmetic that goes outside this range will result ++in an error message. Use this if you are including an explicit ++list of holidays, rather than a formula to generate them, and you ++want to make sure you don't accidentally go beyond the last point ++where the holidays you entered are complete. If there is no ++limiting interval in the @code{Holidays} vector, the default ++@samp{[1 .. 2737]} is used. (This is the absolute range of years ++for which Calc's business-day algorithms will operate.) ++ ++@item ++An interval of HMS forms. This specifies the span of hours that ++are to be considered one business day. For example, if this ++range is @samp{[9@@ 0' 0" .. 17@@ 0' 0"]} (i.e., 9am to 5pm), then ++the business day is only eight hours long, so that @kbd{1.5 t +} ++on @samp{<4:00pm Fri Dec 13, 1991>} will add one business day and ++four business hours to produce @samp{<12:00pm Tue Dec 17, 1991>}. ++Likewise, @kbd{t -} will now express differences in time as ++fractions of an eight-hour day. Times before 9am will be treated ++as 9am by business date arithmetic, and times at or after 5pm will ++be treated as 4:59:59pm. If there is no HMS interval in @code{Holidays}, ++the full 24-hour day @samp{[0@ 0' 0" .. 24@ 0' 0"]} is assumed. ++(Regardless of the type of bounds you specify, the interval is ++treated as inclusive on the low end and exclusive on the high end, ++so that the work day goes from 9am up to, but not including, 5pm.) ++@end itemize ++ ++If the @code{Holidays} vector is empty, then @kbd{t +} and ++@kbd{t -} will act just like @kbd{+} and @kbd{-} because there will ++then be no difference between business days and calendar days. ++ ++Calc expands the intervals and formulas you give into a complete ++list of holidays for internal use. This is done mainly to make ++sure it can detect multiple holidays. (For example, ++@samp{} is both New Year's Day and a Sunday, but ++Calc's algorithms take care to count it only once when figuring ++the number of holidays between two dates.) ++ ++Since the complete list of holidays for all the years from 1 to ++2737 would be huge, Calc actually computes only the part of the ++list between the smallest and largest years that have been involved ++in business-day calculations so far. Normally, you won't have to ++worry about this. Keep in mind, however, that if you do one ++calculation for 1992, and another for 1792, even if both involve ++only a small range of years, Calc will still work out all the ++holidays that fall in that 200-year span. ++ ++If you add a (positive) number of days to a date form that falls on a ++weekend or holiday, the date form is treated as if it were the most ++recent business day. (Thus adding one business day to a Friday, ++Saturday, or Sunday will all yield the following Monday.) If you ++subtract a number of days from a weekend or holiday, the date is ++effectively on the following business day. (So subtracting one business ++day from Saturday, Sunday, or Monday yields the preceding Friday.) The ++difference between two dates one or both of which fall on holidays ++equals the number of actual business days between them. These ++conventions are consistent in the sense that, if you add @var{n} ++business days to any date, the difference between the result and the ++original date will come out to @var{n} business days. (It can't be ++completely consistent though; a subtraction followed by an addition ++might come out a bit differently, since @kbd{t +} is incapable of ++producing a date that falls on a weekend or holiday.) ++ ++@ignore ++@starindex ++@end ignore ++@tindex holiday ++There is a @code{holiday} function, not on any keys, that takes ++any date form and returns 1 if that date falls on a weekend or ++holiday, as defined in @code{Holidays}, or 0 if the date is a ++business day. ++ ++@node Time Zones, , Business Days, Date Arithmetic ++@subsection Time Zones ++ ++@noindent ++@cindex Time zones ++@cindex Daylight saving time ++Time zones and daylight saving time are a complicated business. ++The conversions to and from Julian and Unix-style dates automatically ++compute the correct time zone and daylight saving adjustment to use, ++provided they can figure out this information. This section describes ++Calc's time zone adjustment algorithm in detail, in case you want to ++do conversions in different time zones or in case Calc's algorithms ++can't determine the right correction to use. ++ ++Adjustments for time zones and daylight saving time are done by ++@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other ++commands. In particular, @samp{ - } evaluates ++to exactly 30 days even though there is a daylight-saving ++transition in between. This is also true for Julian pure dates: ++@samp{julian() - julian()}. But Julian ++and Unix date/times will adjust for daylight saving time: using Calc's ++default daylight saving time rule (see the explanation below), ++@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)} ++evaluates to @samp{29.95833} (that's 29 days and 23 hours) ++because one hour was lost when daylight saving commenced on ++April 7, 1991. ++ ++In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})} ++computes the actual number of 24-hour periods between two dates, whereas ++@samp{@var{date1} - @var{date2}} computes the number of calendar ++days between two dates without taking daylight saving into account. ++ ++@pindex calc-time-zone ++@ignore ++@starindex ++@end ignore ++@tindex tzone ++The @code{calc-time-zone} [@code{tzone}] command converts the time ++zone specified by its numeric prefix argument into a number of ++seconds difference from Greenwich mean time (GMT). If the argument ++is a number, the result is simply that value multiplied by 3600. ++Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If ++Daylight Saving time is in effect, one hour should be subtracted from ++the normal difference. ++ ++If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other ++date arithmetic commands that include a time zone argument) takes the ++zone argument from the top of the stack. (In the case of @kbd{t J} ++and @kbd{t U}, the normal argument is then taken from the second-to-top ++stack position.) This allows you to give a non-integer time zone ++adjustment. The time-zone argument can also be an HMS form, or ++it can be a variable which is a time zone name in upper- or lower-case. ++For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)} ++(for Pacific standard and daylight saving times, respectively). ++ ++North American and European time zone names are defined as follows; ++note that for each time zone there is one name for standard time, ++another for daylight saving time, and a third for ``generalized'' time ++in which the daylight saving adjustment is computed from context. ++ ++@smallexample ++@group ++YST PST MST CST EST AST NST GMT WET MET MEZ ++ 9 8 7 6 5 4 3.5 0 -1 -2 -2 ++ ++YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ ++ 8 7 6 5 4 3 2.5 -1 -2 -3 -3 ++ ++YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ ++9/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3 ++@end group ++@end smallexample ++ ++@vindex math-tzone-names ++To define time zone names that do not appear in the above table, ++you must modify the Lisp variable @code{math-tzone-names}. This ++is a list of lists describing the different time zone names; its ++structure is best explained by an example. The three entries for ++Pacific Time look like this: ++ ++@smallexample ++@group ++( ( "PST" 8 0 ) ; Name as an upper-case string, then standard ++ ( "PDT" 8 -1 ) ; adjustment, then daylight saving adjustment. ++ ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone. ++@end group ++@end smallexample ++ ++@cindex @code{TimeZone} variable ++@vindex TimeZone ++With no arguments, @code{calc-time-zone} or @samp{tzone()} will by ++default get the time zone and daylight saving information from the ++calendar (@pxref{Daylight Saving,Calendar/Diary,The Calendar and the Diary, ++emacs,The GNU Emacs Manual}). To use a different time zone, or if the ++calendar does not give the desired result, you can set the Calc variable ++@code{TimeZone} (which is by default @code{nil}) to an appropriate ++time zone name. (The easiest way to do this is to edit the ++@code{TimeZone} variable using Calc's @kbd{s T} command, then use the ++@kbd{s p} (@code{calc-permanent-variable}) command to save the value of ++@code{TimeZone} permanently.) ++If the time zone given by @code{TimeZone} is a generalized time zone, ++e.g., @code{EGT}, Calc examines the date being converted to tell whether ++to use standard or daylight saving time. But if the current time zone ++is explicit, e.g., @code{EST} or @code{EDT}, then that adjustment is ++used exactly and Calc's daylight saving algorithm is not consulted. ++The special time zone name @code{local} ++is equivalent to no argument; i.e., it uses the information obtained ++from the calendar. ++ ++The @kbd{t J} and @code{t U} commands with no numeric prefix ++arguments do the same thing as @samp{tzone()}; namely, use the ++information from the calendar if @code{TimeZone} is @code{nil}, ++otherwise use the time zone given by @code{TimeZone}. ++ ++@vindex math-daylight-savings-hook ++@findex math-std-daylight-savings ++When Calc computes the daylight saving information itself (i.e., when ++the @code{TimeZone} variable is set), it will by default consider ++daylight saving time to begin at 2 a.m.@: on the second Sunday of March ++(for years from 2007 on) or on the last Sunday in April (for years ++before 2007), and to end at 2 a.m.@: on the first Sunday of ++November. (for years from 2007 on) or the last Sunday in October (for ++years before 2007). These are the rules that have been in effect in ++much of North America since 1966 and take into account the rule change ++that began in 2007. If you are in a country that uses different rules ++for computing daylight saving time, you have two choices: Write your own ++daylight saving hook, or control time zones explicitly by setting the ++@code{TimeZone} variable and/or always giving a time-zone argument for ++the conversion functions. ++ ++The Lisp variable @code{math-daylight-savings-hook} holds the ++name of a function that is used to compute the daylight saving ++adjustment for a given date. The default is ++@code{math-std-daylight-savings}, which computes an adjustment ++(either 0 or @mathit{-1}) using the North American rules given above. ++ ++The daylight saving hook function is called with four arguments: ++The date, as a floating-point number in standard Calc format; ++a six-element list of the date decomposed into year, month, day, ++hour, minute, and second, respectively; a string which contains ++the generalized time zone name in upper-case, e.g., @code{"WEGT"}; ++and a special adjustment to be applied to the hour value when ++converting into a generalized time zone (see below). ++ ++@findex math-prev-weekday-in-month ++The Lisp function @code{math-prev-weekday-in-month} is useful for ++daylight saving computations. This is an internal version of ++the user-level @code{pwday} function described in the previous ++section. It takes four arguments: The floating-point date value, ++the corresponding six-element date list, the day-of-month number, ++and the weekday number (0-6). ++ ++The default daylight saving hook ignores the time zone name, but a ++more sophisticated hook could use different algorithms for different ++time zones. It would also be possible to use different algorithms ++depending on the year number, but the default hook always uses the ++algorithm for 1987 and later. Here is a listing of the default ++daylight saving hook: ++ ++@smallexample ++(defun math-std-daylight-savings (date dt zone bump) ++ (cond ((< (nth 1 dt) 4) 0) ++ ((= (nth 1 dt) 4) ++ (let ((sunday (math-prev-weekday-in-month date dt 7 0))) ++ (cond ((< (nth 2 dt) sunday) 0) ++ ((= (nth 2 dt) sunday) ++ (if (>= (nth 3 dt) (+ 3 bump)) -1 0)) ++ (t -1)))) ++ ((< (nth 1 dt) 10) -1) ++ ((= (nth 1 dt) 10) ++ (let ((sunday (math-prev-weekday-in-month date dt 31 0))) ++ (cond ((< (nth 2 dt) sunday) -1) ++ ((= (nth 2 dt) sunday) ++ (if (>= (nth 3 dt) (+ 2 bump)) 0 -1)) ++ (t 0)))) ++ (t 0)) ++) ++@end smallexample ++ ++@noindent ++The @code{bump} parameter is equal to zero when Calc is converting ++from a date form in a generalized time zone into a GMT date value. ++It is @mathit{-1} when Calc is converting in the other direction. The ++adjustments shown above ensure that the conversion behaves correctly ++and reasonably around the 2 a.m.@: transition in each direction. ++ ++There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the ++beginning of daylight saving time; converting a date/time form that ++falls in this hour results in a time value for the following hour, ++from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the ++hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time ++form that falls in this hour results in a time value for the first ++manifestation of that time (@emph{not} the one that occurs one hour ++later). ++ ++If @code{math-daylight-savings-hook} is @code{nil}, then the ++daylight saving adjustment is always taken to be zero. ++ ++In algebraic formulas, @samp{tzone(@var{zone}, @var{date})} ++computes the time zone adjustment for a given zone name at a ++given date. The @var{date} is ignored unless @var{zone} is a ++generalized time zone. If @var{date} is a date form, the ++daylight saving computation is applied to it as it appears. ++If @var{date} is a numeric date value, it is adjusted for the ++daylight-saving version of @var{zone} before being given to ++the daylight saving hook. This odd-sounding rule ensures ++that the daylight-saving computation is always done in ++local time, not in the GMT time that a numeric @var{date} ++is typically represented in. ++ ++@ignore ++@starindex ++@end ignore ++@tindex dsadj ++The @samp{dsadj(@var{date}, @var{zone})} function computes the ++daylight saving adjustment that is appropriate for @var{date} in ++time zone @var{zone}. If @var{zone} is explicitly in or not in ++daylight saving time (e.g., @code{PDT} or @code{PST}) the ++@var{date} is ignored. If @var{zone} is a generalized time zone, ++the algorithms described above are used. If @var{zone} is omitted, ++the computation is done for the current time zone. ++ ++@node Financial Functions, Binary Functions, Date Arithmetic, Arithmetic ++@section Financial Functions ++ ++@noindent ++Calc's financial or business functions use the @kbd{b} prefix ++key followed by a shifted letter. (The @kbd{b} prefix followed by ++a lower-case letter is used for operations on binary numbers.) ++ ++Note that the rate and the number of intervals given to these ++functions must be on the same time scale, e.g., both months or ++both years. Mixing an annual interest rate with a time expressed ++in months will give you very wrong answers! ++ ++It is wise to compute these functions to a higher precision than ++you really need, just to make sure your answer is correct to the ++last penny; also, you may wish to check the definitions at the end ++of this section to make sure the functions have the meaning you expect. ++ ++@menu ++* Percentages:: ++* Future Value:: ++* Present Value:: ++* Related Financial Functions:: ++* Depreciation Functions:: ++* Definitions of Financial Functions:: ++@end menu ++ ++@node Percentages, Future Value, Financial Functions, Financial Functions ++@subsection Percentages ++ ++@kindex M-% ++@pindex calc-percent ++@tindex % ++@tindex percent ++The @kbd{M-%} (@code{calc-percent}) command takes a percentage value, ++say 5.4, and converts it to an equivalent actual number. For example, ++@kbd{5.4 M-%} enters 0.054 on the stack. (That's the @key{META} or ++@key{ESC} key combined with @kbd{%}.) ++ ++Actually, @kbd{M-%} creates a formula of the form @samp{5.4%}. ++You can enter @samp{5.4%} yourself during algebraic entry. The ++@samp{%} operator simply means, ``the preceding value divided by ++100.'' The @samp{%} operator has very high precedence, so that ++@samp{1+8%} is interpreted as @samp{1+(8%)}, not as @samp{(1+8)%}. ++(The @samp{%} operator is just a postfix notation for the ++@code{percent} function, just like @samp{20!} is the notation for ++@samp{fact(20)}, or twenty-factorial.) ++ ++The formula @samp{5.4%} would normally evaluate immediately to ++0.054, but the @kbd{M-%} command suppresses evaluation as it puts ++the formula onto the stack. However, the next Calc command that ++uses the formula @samp{5.4%} will evaluate it as its first step. ++The net effect is that you get to look at @samp{5.4%} on the stack, ++but Calc commands see it as @samp{0.054}, which is what they expect. ++ ++In particular, @samp{5.4%} and @samp{0.054} are suitable values ++for the @var{rate} arguments of the various financial functions, ++but the number @samp{5.4} is probably @emph{not} suitable---it ++represents a rate of 540 percent! ++ ++The key sequence @kbd{M-% *} effectively means ``percent-of.'' ++For example, @kbd{68 @key{RET} 25 M-% *} computes 17, which is 25% of ++68 (and also 68% of 25, which comes out to the same thing). ++ ++@kindex c % ++@pindex calc-convert-percent ++The @kbd{c %} (@code{calc-convert-percent}) command converts the ++value on the top of the stack from numeric to percentage form. ++For example, if 0.08 is on the stack, @kbd{c %} converts it to ++@samp{8%}. The quantity is the same, it's just represented ++differently. (Contrast this with @kbd{M-%}, which would convert ++this number to @samp{0.08%}.) The @kbd{=} key is a convenient way ++to convert a formula like @samp{8%} back to numeric form, 0.08. ++ ++To compute what percentage one quantity is of another quantity, ++use @kbd{/ c %}. For example, @w{@kbd{17 @key{RET} 68 / c %}} displays ++@samp{25%}. ++ ++@kindex b % ++@pindex calc-percent-change ++@tindex relch ++The @kbd{b %} (@code{calc-percent-change}) [@code{relch}] command ++calculates the percentage change from one number to another. ++For example, @kbd{40 @key{RET} 50 b %} produces the answer @samp{25%}, ++since 50 is 25% larger than 40. A negative result represents a ++decrease: @kbd{50 @key{RET} 40 b %} produces @samp{-20%}, since 40 is ++20% smaller than 50. (The answers are different in magnitude ++because, in the first case, we're increasing by 25% of 40, but ++in the second case, we're decreasing by 20% of 50.) The effect ++of @kbd{40 @key{RET} 50 b %} is to compute @expr{(50-40)/40}, converting ++the answer to percentage form as if by @kbd{c %}. ++ ++@node Future Value, Present Value, Percentages, Financial Functions ++@subsection Future Value ++ ++@noindent ++@kindex b F ++@pindex calc-fin-fv ++@tindex fv ++The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes ++the future value of an investment. It takes three arguments ++from the stack: @samp{fv(@var{rate}, @var{n}, @var{payment})}. ++If you give payments of @var{payment} every year for @var{n} ++years, and the money you have paid earns interest at @var{rate} per ++year, then this function tells you what your investment would be ++worth at the end of the period. (The actual interval doesn't ++have to be years, as long as @var{n} and @var{rate} are expressed ++in terms of the same intervals.) This function assumes payments ++occur at the @emph{end} of each interval. ++ ++@kindex I b F ++@tindex fvb ++The @kbd{I b F} [@code{fvb}] command does the same computation, ++but assuming your payments are at the beginning of each interval. ++Suppose you plan to deposit $1000 per year in a savings account ++earning 5.4% interest, starting right now. How much will be ++in the account after five years? @code{fvb(5.4%, 5, 1000) = 5870.73}. ++Thus you will have earned $870 worth of interest over the years. ++Using the stack, this calculation would have been ++@kbd{5.4 M-% 5 @key{RET} 1000 I b F}. Note that the rate is expressed ++as a number between 0 and 1, @emph{not} as a percentage. ++ ++@kindex H b F ++@tindex fvl ++The @kbd{H b F} [@code{fvl}] command computes the future value ++of an initial lump sum investment. Suppose you could deposit ++those five thousand dollars in the bank right now; how much would ++they be worth in five years? @code{fvl(5.4%, 5, 5000) = 6503.89}. ++ ++The algebraic functions @code{fv} and @code{fvb} accept an optional ++fourth argument, which is used as an initial lump sum in the sense ++of @code{fvl}. In other words, @code{fv(@var{rate}, @var{n}, ++@var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment}) +++ fvl(@var{rate}, @var{n}, @var{initial})}. ++ ++To illustrate the relationships between these functions, we could ++do the @code{fvb} calculation ``by hand'' using @code{fvl}. The ++final balance will be the sum of the contributions of our five ++deposits at various times. The first deposit earns interest for ++five years: @code{fvl(5.4%, 5, 1000) = 1300.78}. The second ++deposit only earns interest for four years: @code{fvl(5.4%, 4, 1000) = ++1234.13}. And so on down to the last deposit, which earns one ++year's interest: @code{fvl(5.4%, 1, 1000) = 1054.00}. The sum of ++these five values is, sure enough, $5870.73, just as was computed ++by @code{fvb} directly. ++ ++What does @code{fv(5.4%, 5, 1000) = 5569.96} mean? The payments ++are now at the ends of the periods. The end of one year is the same ++as the beginning of the next, so what this really means is that we've ++lost the payment at year zero (which contributed $1300.78), but we're ++now counting the payment at year five (which, since it didn't have ++a chance to earn interest, counts as $1000). Indeed, @expr{5569.96 = ++5870.73 - 1300.78 + 1000} (give or take a bit of roundoff error). ++ ++@node Present Value, Related Financial Functions, Future Value, Financial Functions ++@subsection Present Value ++ ++@noindent ++@kindex b P ++@pindex calc-fin-pv ++@tindex pv ++The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes ++the present value of an investment. Like @code{fv}, it takes ++three arguments: @code{pv(@var{rate}, @var{n}, @var{payment})}. ++It computes the present value of a series of regular payments. ++Suppose you have the chance to make an investment that will ++pay $2000 per year over the next four years; as you receive ++these payments you can put them in the bank at 9% interest. ++You want to know whether it is better to make the investment, or ++to keep the money in the bank where it earns 9% interest right ++from the start. The calculation @code{pv(9%, 4, 2000)} gives the ++result 6479.44. If your initial investment must be less than this, ++say, $6000, then the investment is worthwhile. But if you had to ++put up $7000, then it would be better just to leave it in the bank. ++ ++Here is the interpretation of the result of @code{pv}: You are ++trying to compare the return from the investment you are ++considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with ++the return from leaving the money in the bank, which is ++@code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money ++you would have to put up in advance. The @code{pv} function ++finds the break-even point, @expr{x = 6479.44}, at which ++@code{fvl(9%, 4, 6479.44)} is also equal to 9146.26. This is ++the largest amount you should be willing to invest. ++ ++@kindex I b P ++@tindex pvb ++The @kbd{I b P} [@code{pvb}] command solves the same problem, ++but with payments occurring at the beginning of each interval. ++It has the same relationship to @code{fvb} as @code{pv} has ++to @code{fv}. For example @code{pvb(9%, 4, 2000) = 7062.59}, ++a larger number than @code{pv} produced because we get to start ++earning interest on the return from our investment sooner. ++ ++@kindex H b P ++@tindex pvl ++The @kbd{H b P} [@code{pvl}] command computes the present value of ++an investment that will pay off in one lump sum at the end of the ++period. For example, if we get our $8000 all at the end of the ++four years, @code{pvl(9%, 4, 8000) = 5667.40}. This is much ++less than @code{pv} reported, because we don't earn any interest ++on the return from this investment. Note that @code{pvl} and ++@code{fvl} are simple inverses: @code{fvl(9%, 4, 5667.40) = 8000}. ++ ++You can give an optional fourth lump-sum argument to @code{pv} ++and @code{pvb}; this is handled in exactly the same way as the ++fourth argument for @code{fv} and @code{fvb}. ++ ++@kindex b N ++@pindex calc-fin-npv ++@tindex npv ++The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes ++the net present value of a series of irregular investments. ++The first argument is the interest rate. The second argument is ++a vector which represents the expected return from the investment ++at the end of each interval. For example, if the rate represents ++a yearly interest rate, then the vector elements are the return ++from the first year, second year, and so on. ++ ++Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}. ++Obviously this function is more interesting when the payments are ++not all the same! ++ ++The @code{npv} function can actually have two or more arguments. ++Multiple arguments are interpreted in the same way as for the ++vector statistical functions like @code{vsum}. ++@xref{Single-Variable Statistics}. Basically, if there are several ++payment arguments, each either a vector or a plain number, all these ++values are collected left-to-right into the complete list of payments. ++A numeric prefix argument on the @kbd{b N} command says how many ++payment values or vectors to take from the stack. ++ ++@kindex I b N ++@tindex npvb ++The @kbd{I b N} [@code{npvb}] command computes the net present ++value where payments occur at the beginning of each interval ++rather than at the end. ++ ++@node Related Financial Functions, Depreciation Functions, Present Value, Financial Functions ++@subsection Related Financial Functions ++ ++@noindent ++The functions in this section are basically inverses of the ++present value functions with respect to the various arguments. ++ ++@kindex b M ++@pindex calc-fin-pmt ++@tindex pmt ++The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes ++the amount of periodic payment necessary to amortize a loan. ++Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the ++value of @var{payment} such that @code{pv(@var{rate}, @var{n}, ++@var{payment}) = @var{amount}}. ++ ++@kindex I b M ++@tindex pmtb ++The @kbd{I b M} [@code{pmtb}] command does the same computation ++but using @code{pvb} instead of @code{pv}. Like @code{pv} and ++@code{pvb}, these functions can also take a fourth argument which ++represents an initial lump-sum investment. ++ ++@kindex H b M ++The @kbd{H b M} key just invokes the @code{fvl} function, which is ++the inverse of @code{pvl}. There is no explicit @code{pmtl} function. ++ ++@kindex b # ++@pindex calc-fin-nper ++@tindex nper ++The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes ++the number of regular payments necessary to amortize a loan. ++Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals ++the value of @var{n} such that @code{pv(@var{rate}, @var{n}, ++@var{payment}) = @var{amount}}. If @var{payment} is too small ++ever to amortize a loan for @var{amount} at interest rate @var{rate}, ++the @code{nper} function is left in symbolic form. ++ ++@kindex I b # ++@tindex nperb ++The @kbd{I b #} [@code{nperb}] command does the same computation ++but using @code{pvb} instead of @code{pv}. You can give a fourth ++lump-sum argument to these functions, but the computation will be ++rather slow in the four-argument case. ++ ++@kindex H b # ++@tindex nperl ++The @kbd{H b #} [@code{nperl}] command does the same computation ++using @code{pvl}. By exchanging @var{payment} and @var{amount} you ++can also get the solution for @code{fvl}. For example, ++@code{nperl(8%, 2000, 1000) = 9.006}, so if you place $1000 in a ++bank account earning 8%, it will take nine years to grow to $2000. ++ ++@kindex b T ++@pindex calc-fin-rate ++@tindex rate ++The @kbd{b T} (@code{calc-fin-rate}) [@code{rate}] command computes ++the rate of return on an investment. This is also an inverse of @code{pv}: ++@code{rate(@var{n}, @var{payment}, @var{amount})} computes the value of ++@var{rate} such that @code{pv(@var{rate}, @var{n}, @var{payment}) = ++@var{amount}}. The result is expressed as a formula like @samp{6.3%}. ++ ++@kindex I b T ++@kindex H b T ++@tindex rateb ++@tindex ratel ++The @kbd{I b T} [@code{rateb}] and @kbd{H b T} [@code{ratel}] ++commands solve the analogous equations with @code{pvb} or @code{pvl} ++in place of @code{pv}. Also, @code{rate} and @code{rateb} can ++accept an optional fourth argument just like @code{pv} and @code{pvb}. ++To redo the above example from a different perspective, ++@code{ratel(9, 2000, 1000) = 8.00597%}, which says you will need an ++interest rate of 8% in order to double your account in nine years. ++ ++@kindex b I ++@pindex calc-fin-irr ++@tindex irr ++The @kbd{b I} (@code{calc-fin-irr}) [@code{irr}] command is the ++analogous function to @code{rate} but for net present value. ++Its argument is a vector of payments. Thus @code{irr(@var{payments})} ++computes the @var{rate} such that @code{npv(@var{rate}, @var{payments}) = 0}; ++this rate is known as the @dfn{internal rate of return}. ++ ++@kindex I b I ++@tindex irrb ++The @kbd{I b I} [@code{irrb}] command computes the internal rate of ++return assuming payments occur at the beginning of each period. ++ ++@node Depreciation Functions, Definitions of Financial Functions, Related Financial Functions, Financial Functions ++@subsection Depreciation Functions ++ ++@noindent ++The functions in this section calculate @dfn{depreciation}, which is ++the amount of value that a possession loses over time. These functions ++are characterized by three parameters: @var{cost}, the original cost ++of the asset; @var{salvage}, the value the asset will have at the end ++of its expected ``useful life''; and @var{life}, the number of years ++(or other periods) of the expected useful life. ++ ++There are several methods for calculating depreciation that differ in ++the way they spread the depreciation over the lifetime of the asset. ++ ++@kindex b S ++@pindex calc-fin-sln ++@tindex sln ++The @kbd{b S} (@code{calc-fin-sln}) [@code{sln}] command computes the ++``straight-line'' depreciation. In this method, the asset depreciates ++by the same amount every year (or period). For example, ++@samp{sln(12000, 2000, 5)} returns 2000. The asset costs $12000 ++initially and will be worth $2000 after five years; it loses $2000 ++per year. ++ ++@kindex b Y ++@pindex calc-fin-syd ++@tindex syd ++The @kbd{b Y} (@code{calc-fin-syd}) [@code{syd}] command computes the ++accelerated ``sum-of-years'-digits'' depreciation. Here the depreciation ++is higher during the early years of the asset's life. Since the ++depreciation is different each year, @kbd{b Y} takes a fourth @var{period} ++parameter which specifies which year is requested, from 1 to @var{life}. ++If @var{period} is outside this range, the @code{syd} function will ++return zero. ++ ++@kindex b D ++@pindex calc-fin-ddb ++@tindex ddb ++The @kbd{b D} (@code{calc-fin-ddb}) [@code{ddb}] command computes an ++accelerated depreciation using the double-declining balance method. ++It also takes a fourth @var{period} parameter. ++ ++For symmetry, the @code{sln} function will accept a @var{period} ++parameter as well, although it will ignore its value except that the ++return value will as usual be zero if @var{period} is out of range. ++ ++For example, pushing the vector @expr{[1,2,3,4,5]} (perhaps with @kbd{v x 5}) ++and then mapping @kbd{V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$), ++ddb(12000,2000,5,$)] @key{RET}} produces a matrix that allows us to compare ++the three depreciation methods: ++ ++@example ++@group ++[ [ 2000, 3333, 4800 ] ++ [ 2000, 2667, 2880 ] ++ [ 2000, 2000, 1728 ] ++ [ 2000, 1333, 592 ] ++ [ 2000, 667, 0 ] ] ++@end group ++@end example ++ ++@noindent ++(Values have been rounded to nearest integers in this figure.) ++We see that @code{sln} depreciates by the same amount each year, ++@kbd{syd} depreciates more at the beginning and less at the end, ++and @kbd{ddb} weights the depreciation even more toward the beginning. ++ ++Summing columns with @kbd{V R : +} yields @expr{[10000, 10000, 10000]}; ++the total depreciation in any method is (by definition) the ++difference between the cost and the salvage value. ++ ++@node Definitions of Financial Functions, , Depreciation Functions, Financial Functions ++@subsection Definitions ++ ++@noindent ++For your reference, here are the actual formulas used to compute ++Calc's financial functions. ++ ++Calc will not evaluate a financial function unless the @var{rate} or ++@var{n} argument is known. However, @var{payment} or @var{amount} can ++be a variable. Calc expands these functions according to the ++formulas below for symbolic arguments only when you use the @kbd{a "} ++(@code{calc-expand-formula}) command, or when taking derivatives or ++integrals or solving equations involving the functions. ++ ++@ifnottex ++These formulas are shown using the conventions of Big display ++mode (@kbd{d B}); for example, the formula for @code{fv} written ++linearly is @samp{pmt * ((1 + rate)^n) - 1) / rate}. ++ ++@example ++ n ++ (1 + rate) - 1 ++fv(rate, n, pmt) = pmt * --------------- ++ rate ++ ++ n ++ ((1 + rate) - 1) (1 + rate) ++fvb(rate, n, pmt) = pmt * ---------------------------- ++ rate ++ ++ n ++fvl(rate, n, pmt) = pmt * (1 + rate) ++ ++ -n ++ 1 - (1 + rate) ++pv(rate, n, pmt) = pmt * ---------------- ++ rate ++ ++ -n ++ (1 - (1 + rate) ) (1 + rate) ++pvb(rate, n, pmt) = pmt * ----------------------------- ++ rate ++ ++ -n ++pvl(rate, n, pmt) = pmt * (1 + rate) ++ ++ -1 -2 -3 ++npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate) ++ ++ -1 -2 ++npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate) ++ ++ -n ++ (amt - x * (1 + rate) ) * rate ++pmt(rate, n, amt, x) = ------------------------------- ++ -n ++ 1 - (1 + rate) ++ ++ -n ++ (amt - x * (1 + rate) ) * rate ++pmtb(rate, n, amt, x) = ------------------------------- ++ -n ++ (1 - (1 + rate) ) (1 + rate) ++ ++ amt * rate ++nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate) ++ pmt ++ ++ amt * rate ++nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate) ++ pmt * (1 + rate) ++ ++ amt ++nperl(rate, pmt, amt) = - log(---, 1 + rate) ++ pmt ++ ++ 1/n ++ pmt ++ratel(n, pmt, amt) = ------ - 1 ++ 1/n ++ amt ++ ++ cost - salv ++sln(cost, salv, life) = ----------- ++ life ++ ++ (cost - salv) * (life - per + 1) ++syd(cost, salv, life, per) = -------------------------------- ++ life * (life + 1) / 2 ++ ++ book * 2 ++ddb(cost, salv, life, per) = --------, book = cost - depreciation so far ++ life ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++$$ \code{fv}(r, n, p) = p { (1 + r)^n - 1 \over r } $$ ++$$ \code{fvb}(r, n, p) = p { ((1 + r)^n - 1) (1 + r) \over r } $$ ++$$ \code{fvl}(r, n, p) = p (1 + r)^n $$ ++$$ \code{pv}(r, n, p) = p { 1 - (1 + r)^{-n} \over r } $$ ++$$ \code{pvb}(r, n, p) = p { (1 - (1 + r)^{-n}) (1 + r) \over r } $$ ++$$ \code{pvl}(r, n, p) = p (1 + r)^{-n} $$ ++$$ \code{npv}(r, [a,b,c]) = a (1 + r)^{-1} + b (1 + r)^{-2} + c (1 + r)^{-3} $$ ++$$ \code{npvb}(r, [a,b,c]) = a + b (1 + r)^{-1} + c (1 + r)^{-2} $$ ++$$ \code{pmt}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 1 - (1 + r)^{-n} }$$ ++$$ \code{pmtb}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over ++ (1 - (1 + r)^{-n}) (1 + r) } $$ ++$$ \code{nper}(r, p, a) = -\code{log}(1 - { a r \over p }, 1 + r) $$ ++$$ \code{nperb}(r, p, a) = -\code{log}(1 - { a r \over p (1 + r) }, 1 + r) $$ ++$$ \code{nperl}(r, p, a) = -\code{log}({a \over p}, 1 + r) $$ ++$$ \code{ratel}(n, p, a) = { p^{1/n} \over a^{1/n} } - 1 $$ ++$$ \code{sln}(c, s, l) = { c - s \over l } $$ ++$$ \code{syd}(c, s, l, p) = { (c - s) (l - p + 1) \over l (l+1) / 2 } $$ ++$$ \code{ddb}(c, s, l, p) = { 2 (c - \hbox{depreciation so far}) \over l } $$ ++@end tex ++ ++@noindent ++In @code{pmt} and @code{pmtb}, @expr{x=0} if omitted. ++ ++These functions accept any numeric objects, including error forms, ++intervals, and even (though not very usefully) complex numbers. The ++above formulas specify exactly the behavior of these functions with ++all sorts of inputs. ++ ++Note that if the first argument to the @code{log} in @code{nper} is ++negative, @code{nper} leaves itself in symbolic form rather than ++returning a (financially meaningless) complex number. ++ ++@samp{rate(num, pmt, amt)} solves the equation ++@samp{pv(rate, num, pmt) = amt} for @samp{rate} using @kbd{H a R} ++(@code{calc-find-root}), with the interval @samp{[.01% .. 100%]} ++for an initial guess. The @code{rateb} function is the same except ++that it uses @code{pvb}. Note that @code{ratel} can be solved ++directly; its formula is shown in the above list. ++ ++Similarly, @samp{irr(pmts)} solves the equation @samp{npv(rate, pmts) = 0} ++for @samp{rate}. ++ ++If you give a fourth argument to @code{nper} or @code{nperb}, Calc ++will also use @kbd{H a R} to solve the equation using an initial ++guess interval of @samp{[0 .. 100]}. ++ ++A fourth argument to @code{fv} simply sums the two components ++calculated from the above formulas for @code{fv} and @code{fvl}. ++The same is true of @code{fvb}, @code{pv}, and @code{pvb}. ++ ++The @kbd{ddb} function is computed iteratively; the ``book'' value ++starts out equal to @var{cost}, and decreases according to the above ++formula for the specified number of periods. If the book value ++would decrease below @var{salvage}, it only decreases to @var{salvage} ++and the depreciation is zero for all subsequent periods. The @code{ddb} ++function returns the amount the book value decreased in the specified ++period. ++ ++@node Binary Functions, , Financial Functions, Arithmetic ++@section Binary Number Functions ++ ++@noindent ++The commands in this chapter all use two-letter sequences beginning with ++the @kbd{b} prefix. ++ ++@cindex Binary numbers ++The ``binary'' operations actually work regardless of the currently ++displayed radix, although their results make the most sense in a radix ++like 2, 8, or 16 (as obtained by the @kbd{d 2}, @kbd{d 8}, or @w{@kbd{d 6}} ++commands, respectively). You may also wish to enable display of leading ++zeros with @kbd{d z}. @xref{Radix Modes}. ++ ++@cindex Word size for binary operations ++The Calculator maintains a current @dfn{word size} @expr{w}, an ++arbitrary positive or negative integer. For a positive word size, all ++of the binary operations described here operate modulo @expr{2^w}. In ++particular, negative arguments are converted to positive integers modulo ++@expr{2^w} by all binary functions. ++ ++If the word size is negative, binary operations produce 2's complement ++integers from ++@texline @math{-2^{-w-1}} ++@infoline @expr{-(2^(-w-1))} ++to ++@texline @math{2^{-w-1}-1} ++@infoline @expr{2^(-w-1)-1} ++inclusive. Either mode accepts inputs in any range; the sign of ++@expr{w} affects only the results produced. ++ ++@kindex b c ++@pindex calc-clip ++@tindex clip ++The @kbd{b c} (@code{calc-clip}) ++[@code{clip}] command can be used to clip a number by reducing it modulo ++@expr{2^w}. The commands described in this chapter automatically clip ++their results to the current word size. Note that other operations like ++addition do not use the current word size, since integer addition ++generally is not ``binary.'' (However, @pxref{Simplification Modes}, ++@code{calc-bin-simplify-mode}.) For example, with a word size of 8 ++bits @kbd{b c} converts a number to the range 0 to 255; with a word ++size of @mathit{-8} @kbd{b c} converts to the range @mathit{-128} to 127. ++ ++@kindex b w ++@pindex calc-word-size ++The default word size is 32 bits. All operations except the shifts and ++rotates allow you to specify a different word size for that one ++operation by giving a numeric prefix argument: @kbd{C-u 8 b c} clips the ++top of stack to the range 0 to 255 regardless of the current word size. ++To set the word size permanently, use @kbd{b w} (@code{calc-word-size}). ++This command displays a prompt with the current word size; press @key{RET} ++immediately to keep this word size, or type a new word size at the prompt. ++ ++When the binary operations are written in symbolic form, they take an ++optional second (or third) word-size parameter. When a formula like ++@samp{and(a,b)} is finally evaluated, the word size current at that time ++will be used, but when @samp{and(a,b,-8)} is evaluated, a word size of ++@mathit{-8} will always be used. A symbolic binary function will be left ++in symbolic form unless the all of its argument(s) are integers or ++integer-valued floats. ++ ++If either or both arguments are modulo forms for which @expr{M} is a ++power of two, that power of two is taken as the word size unless a ++numeric prefix argument overrides it. The current word size is never ++consulted when modulo-power-of-two forms are involved. ++ ++@kindex b a ++@pindex calc-and ++@tindex and ++The @kbd{b a} (@code{calc-and}) [@code{and}] command computes the bitwise ++AND of the two numbers on the top of the stack. In other words, for each ++of the @expr{w} binary digits of the two numbers (pairwise), the corresponding ++bit of the result is 1 if and only if both input bits are 1: ++@samp{and(2#1100, 2#1010) = 2#1000}. ++ ++@kindex b o ++@pindex calc-or ++@tindex or ++The @kbd{b o} (@code{calc-or}) [@code{or}] command computes the bitwise ++inclusive OR of two numbers. A bit is 1 if either of the input bits, or ++both, are 1: @samp{or(2#1100, 2#1010) = 2#1110}. ++ ++@kindex b x ++@pindex calc-xor ++@tindex xor ++The @kbd{b x} (@code{calc-xor}) [@code{xor}] command computes the bitwise ++exclusive OR of two numbers. A bit is 1 if exactly one of the input bits ++is 1: @samp{xor(2#1100, 2#1010) = 2#0110}. ++ ++@kindex b d ++@pindex calc-diff ++@tindex diff ++The @kbd{b d} (@code{calc-diff}) [@code{diff}] command computes the bitwise ++difference of two numbers; this is defined by @samp{diff(a,b) = and(a,not(b))}, ++so that @samp{diff(2#1100, 2#1010) = 2#0100}. ++ ++@kindex b n ++@pindex calc-not ++@tindex not ++The @kbd{b n} (@code{calc-not}) [@code{not}] command computes the bitwise ++NOT of a number. A bit is 1 if the input bit is 0 and vice-versa. ++ ++@kindex b l ++@pindex calc-lshift-binary ++@tindex lsh ++The @kbd{b l} (@code{calc-lshift-binary}) [@code{lsh}] command shifts a ++number left by one bit, or by the number of bits specified in the numeric ++prefix argument. A negative prefix argument performs a logical right shift, ++in which zeros are shifted in on the left. In symbolic form, @samp{lsh(a)} ++is short for @samp{lsh(a,1)}, which in turn is short for @samp{lsh(a,n,w)}. ++Bits shifted ``off the end,'' according to the current word size, are lost. ++ ++@kindex H b l ++@kindex H b r ++@ignore ++@mindex @idots ++@end ignore ++@kindex H b L ++@ignore ++@mindex @null ++@end ignore ++@kindex H b R ++@ignore ++@mindex @null ++@end ignore ++@kindex H b t ++The @kbd{H b l} command also does a left shift, but it takes two arguments ++from the stack (the value to shift, and, at top-of-stack, the number of ++bits to shift). This version interprets the prefix argument just like ++the regular binary operations, i.e., as a word size. The Hyperbolic flag ++has a similar effect on the rest of the binary shift and rotate commands. ++ ++@kindex b r ++@pindex calc-rshift-binary ++@tindex rsh ++The @kbd{b r} (@code{calc-rshift-binary}) [@code{rsh}] command shifts a ++number right by one bit, or by the number of bits specified in the numeric ++prefix argument: @samp{rsh(a,n) = lsh(a,-n)}. ++ ++@kindex b L ++@pindex calc-lshift-arith ++@tindex ash ++The @kbd{b L} (@code{calc-lshift-arith}) [@code{ash}] command shifts a ++number left. It is analogous to @code{lsh}, except that if the shift ++is rightward (the prefix argument is negative), an arithmetic shift ++is performed as described below. ++ ++@kindex b R ++@pindex calc-rshift-arith ++@tindex rash ++The @kbd{b R} (@code{calc-rshift-arith}) [@code{rash}] command performs ++an ``arithmetic'' shift to the right, in which the leftmost bit (according ++to the current word size) is duplicated rather than shifting in zeros. ++This corresponds to dividing by a power of two where the input is interpreted ++as a signed, twos-complement number. (The distinction between the @samp{rsh} ++and @samp{rash} operations is totally independent from whether the word ++size is positive or negative.) With a negative prefix argument, this ++performs a standard left shift. ++ ++@kindex b t ++@pindex calc-rotate-binary ++@tindex rot ++The @kbd{b t} (@code{calc-rotate-binary}) [@code{rot}] command rotates a ++number one bit to the left. The leftmost bit (according to the current ++word size) is dropped off the left and shifted in on the right. With a ++numeric prefix argument, the number is rotated that many bits to the left ++or right. ++ ++@xref{Set Operations}, for the @kbd{b p} and @kbd{b u} commands that ++pack and unpack binary integers into sets. (For example, @kbd{b u} ++unpacks the number @samp{2#11001} to the set of bit-numbers ++@samp{[0, 3, 4]}.) Type @kbd{b u V #} to count the number of ``1'' ++bits in a binary integer. ++ ++Another interesting use of the set representation of binary integers ++is to reverse the bits in, say, a 32-bit integer. Type @kbd{b u} to ++unpack; type @kbd{31 @key{TAB} -} to replace each bit-number in the set ++with 31 minus that bit-number; type @kbd{b p} to pack the set back ++into a binary integer. ++ ++@node Scientific Functions, Matrix Functions, Arithmetic, Top ++@chapter Scientific Functions ++ ++@noindent ++The functions described here perform trigonometric and other transcendental ++calculations. They generally produce floating-point answers correct to the ++full current precision. The @kbd{H} (Hyperbolic) and @kbd{I} (Inverse) ++flag keys must be used to get some of these functions from the keyboard. ++ ++@kindex P ++@pindex calc-pi ++@cindex @code{pi} variable ++@vindex pi ++@kindex H P ++@cindex @code{e} variable ++@vindex e ++@kindex I P ++@cindex @code{gamma} variable ++@vindex gamma ++@cindex Gamma constant, Euler's ++@cindex Euler's gamma constant ++@kindex H I P ++@cindex @code{phi} variable ++@cindex Phi, golden ratio ++@cindex Golden ratio ++One miscellaneous command is shift-@kbd{P} (@code{calc-pi}), which pushes ++the value of @cpi{} (at the current precision) onto the stack. With the ++Hyperbolic flag, it pushes the value @expr{e}, the base of natural logarithms. ++With the Inverse flag, it pushes Euler's constant ++@texline @math{\gamma} ++@infoline @expr{gamma} ++(about 0.5772). With both Inverse and Hyperbolic, it ++pushes the ``golden ratio'' ++@texline @math{\phi} ++@infoline @expr{phi} ++(about 1.618). (At present, Euler's constant is not available ++to unlimited precision; Calc knows only the first 100 digits.) ++In Symbolic mode, these commands push the ++actual variables @samp{pi}, @samp{e}, @samp{gamma}, and @samp{phi}, ++respectively, instead of their values; @pxref{Symbolic Mode}. ++ ++@ignore ++@mindex Q ++@end ignore ++@ignore ++@mindex I Q ++@end ignore ++@kindex I Q ++@tindex sqr ++The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] function is described elsewhere; ++@pxref{Basic Arithmetic}. With the Inverse flag [@code{sqr}], this command ++computes the square of the argument. ++ ++@xref{Prefix Arguments}, for a discussion of the effect of numeric ++prefix arguments on commands in this chapter which do not otherwise ++interpret a prefix argument. ++ ++@menu ++* Logarithmic Functions:: ++* Trigonometric and Hyperbolic Functions:: ++* Advanced Math Functions:: ++* Branch Cuts:: ++* Random Numbers:: ++* Combinatorial Functions:: ++* Probability Distribution Functions:: ++@end menu ++ ++@node Logarithmic Functions, Trigonometric and Hyperbolic Functions, Scientific Functions, Scientific Functions ++@section Logarithmic Functions ++ ++@noindent ++@kindex L ++@pindex calc-ln ++@tindex ln ++@ignore ++@mindex @null ++@end ignore ++@kindex I E ++The shift-@kbd{L} (@code{calc-ln}) [@code{ln}] command computes the natural ++logarithm of the real or complex number on the top of the stack. With ++the Inverse flag it computes the exponential function instead, although ++this is redundant with the @kbd{E} command. ++ ++@kindex E ++@pindex calc-exp ++@tindex exp ++@ignore ++@mindex @null ++@end ignore ++@kindex I L ++The shift-@kbd{E} (@code{calc-exp}) [@code{exp}] command computes the ++exponential, i.e., @expr{e} raised to the power of the number on the stack. ++The meanings of the Inverse and Hyperbolic flags follow from those for ++the @code{calc-ln} command. ++ ++@kindex H L ++@kindex H E ++@pindex calc-log10 ++@tindex log10 ++@tindex exp10 ++@ignore ++@mindex @null ++@end ignore ++@kindex H I L ++@ignore ++@mindex @null ++@end ignore ++@kindex H I E ++The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common ++(base-10) logarithm of a number. (With the Inverse flag [@code{exp10}], ++it raises ten to a given power.) Note that the common logarithm of a ++complex number is computed by taking the natural logarithm and dividing ++by ++@texline @math{\ln10}. ++@infoline @expr{ln(10)}. ++ ++@kindex B ++@kindex I B ++@pindex calc-log ++@tindex log ++@tindex alog ++The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm ++to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since ++@texline @math{2^{10} = 1024}. ++@infoline @expr{2^10 = 1024}. ++In certain cases like @samp{log(3,9)}, the result ++will be either @expr{1:2} or @expr{0.5} depending on the current Fraction ++mode setting. With the Inverse flag [@code{alog}], this command is ++similar to @kbd{^} except that the order of the arguments is reversed. ++ ++@kindex f I ++@pindex calc-ilog ++@tindex ilog ++The @kbd{f I} (@code{calc-ilog}) [@code{ilog}] command computes the ++integer logarithm of a number to any base. The number and the base must ++themselves be positive integers. This is the true logarithm, rounded ++down to an integer. Thus @kbd{ilog(x,10)} is 3 for all @expr{x} in the ++range from 1000 to 9999. If both arguments are positive integers, exact ++integer arithmetic is used; otherwise, this is equivalent to ++@samp{floor(log(x,b))}. ++ ++@kindex f E ++@pindex calc-expm1 ++@tindex expm1 ++The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes ++@texline @math{e^x - 1}, ++@infoline @expr{exp(x)-1}, ++but using an algorithm that produces a more accurate ++answer when the result is close to zero, i.e., when ++@texline @math{e^x} ++@infoline @expr{exp(x)} ++is close to one. ++ ++@kindex f L ++@pindex calc-lnp1 ++@tindex lnp1 ++The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes ++@texline @math{\ln(x+1)}, ++@infoline @expr{ln(x+1)}, ++producing a more accurate answer when @expr{x} is close to zero. ++ ++@node Trigonometric and Hyperbolic Functions, Advanced Math Functions, Logarithmic Functions, Scientific Functions ++@section Trigonometric/Hyperbolic Functions ++ ++@noindent ++@kindex S ++@pindex calc-sin ++@tindex sin ++The shift-@kbd{S} (@code{calc-sin}) [@code{sin}] command computes the sine ++of an angle or complex number. If the input is an HMS form, it is interpreted ++as degrees-minutes-seconds; otherwise, the input is interpreted according ++to the current angular mode. It is best to use Radians mode when operating ++on complex numbers. ++ ++Calc's ``units'' mechanism includes angular units like @code{deg}, ++@code{rad}, and @code{grad}. While @samp{sin(45 deg)} is not evaluated ++all the time, the @kbd{u s} (@code{calc-simplify-units}) command will ++simplify @samp{sin(45 deg)} by taking the sine of 45 degrees, regardless ++of the current angular mode. @xref{Basic Operations on Units}. ++ ++Also, the symbolic variable @code{pi} is not ordinarily recognized in ++arguments to trigonometric functions, as in @samp{sin(3 pi / 4)}, but ++the @kbd{a s} (@code{calc-simplify}) command recognizes many such ++formulas when the current angular mode is Radians @emph{and} Symbolic ++mode is enabled; this example would be replaced by @samp{sqrt(2) / 2}. ++@xref{Symbolic Mode}. Beware, this simplification occurs even if you ++have stored a different value in the variable @samp{pi}; this is one ++reason why changing built-in variables is a bad idea. Arguments of ++the form @expr{x} plus a multiple of @cpiover{2} are also simplified. ++Calc includes similar formulas for @code{cos} and @code{tan}. ++ ++The @kbd{a s} command knows all angles which are integer multiples of ++@cpiover{12}, @cpiover{10}, or @cpiover{8} radians. In Degrees mode, ++analogous simplifications occur for integer multiples of 15 or 18 ++degrees, and for arguments plus multiples of 90 degrees. ++ ++@kindex I S ++@pindex calc-arcsin ++@tindex arcsin ++With the Inverse flag, @code{calc-sin} computes an arcsine. This is also ++available as the @code{calc-arcsin} command or @code{arcsin} algebraic ++function. The returned argument is converted to degrees, radians, or HMS ++notation depending on the current angular mode. ++ ++@kindex H S ++@pindex calc-sinh ++@tindex sinh ++@kindex H I S ++@pindex calc-arcsinh ++@tindex arcsinh ++With the Hyperbolic flag, @code{calc-sin} computes the hyperbolic ++sine, also available as @code{calc-sinh} [@code{sinh}]. With the ++Hyperbolic and Inverse flags, it computes the hyperbolic arcsine ++(@code{calc-arcsinh}) [@code{arcsinh}]. ++ ++@kindex C ++@pindex calc-cos ++@tindex cos ++@ignore ++@mindex @idots ++@end ignore ++@kindex I C ++@pindex calc-arccos ++@ignore ++@mindex @null ++@end ignore ++@tindex arccos ++@ignore ++@mindex @null ++@end ignore ++@kindex H C ++@pindex calc-cosh ++@ignore ++@mindex @null ++@end ignore ++@tindex cosh ++@ignore ++@mindex @null ++@end ignore ++@kindex H I C ++@pindex calc-arccosh ++@ignore ++@mindex @null ++@end ignore ++@tindex arccosh ++@ignore ++@mindex @null ++@end ignore ++@kindex T ++@pindex calc-tan ++@ignore ++@mindex @null ++@end ignore ++@tindex tan ++@ignore ++@mindex @null ++@end ignore ++@kindex I T ++@pindex calc-arctan ++@ignore ++@mindex @null ++@end ignore ++@tindex arctan ++@ignore ++@mindex @null ++@end ignore ++@kindex H T ++@pindex calc-tanh ++@ignore ++@mindex @null ++@end ignore ++@tindex tanh ++@ignore ++@mindex @null ++@end ignore ++@kindex H I T ++@pindex calc-arctanh ++@ignore ++@mindex @null ++@end ignore ++@tindex arctanh ++The shift-@kbd{C} (@code{calc-cos}) [@code{cos}] command computes the cosine ++of an angle or complex number, and shift-@kbd{T} (@code{calc-tan}) [@code{tan}] ++computes the tangent, along with all the various inverse and hyperbolic ++variants of these functions. ++ ++@kindex f T ++@pindex calc-arctan2 ++@tindex arctan2 ++The @kbd{f T} (@code{calc-arctan2}) [@code{arctan2}] command takes two ++numbers from the stack and computes the arc tangent of their ratio. The ++result is in the full range from @mathit{-180} (exclusive) to @mathit{+180} ++(inclusive) degrees, or the analogous range in radians. A similar ++result would be obtained with @kbd{/} followed by @kbd{I T}, but the ++value would only be in the range from @mathit{-90} to @mathit{+90} degrees ++since the division loses information about the signs of the two ++components, and an error might result from an explicit division by zero ++which @code{arctan2} would avoid. By (arbitrary) definition, ++@samp{arctan2(0,0)=0}. ++ ++@pindex calc-sincos ++@ignore ++@starindex ++@end ignore ++@tindex sincos ++@ignore ++@starindex ++@end ignore ++@ignore ++@mindex arc@idots ++@end ignore ++@tindex arcsincos ++The @code{calc-sincos} [@code{sincos}] command computes the sine and ++cosine of a number, returning them as a vector of the form ++@samp{[@var{cos}, @var{sin}]}. ++With the Inverse flag [@code{arcsincos}], this command takes a two-element ++vector as an argument and computes @code{arctan2} of the elements. ++(This command does not accept the Hyperbolic flag.) ++ ++@pindex calc-sec ++@tindex sec ++@pindex calc-csc ++@tindex csc ++@pindex calc-cot ++@tindex cot ++@pindex calc-sech ++@tindex sech ++@pindex calc-csch ++@tindex csch ++@pindex calc-coth ++@tindex coth ++The remaining trigonometric functions, @code{calc-sec} [@code{sec}], ++@code{calc-csc} [@code{csc}] and @code{calc-cot} [@code{cot}], are also ++available. With the Hyperbolic flag, these compute their hyperbolic ++counterparts, which are also available separately as @code{calc-sech} ++[@code{sech}], @code{calc-csch} [@code{csch}] and @code{calc-coth} ++[@code{coth}]. (These commands do not accept the Inverse flag.) ++ ++@node Advanced Math Functions, Branch Cuts, Trigonometric and Hyperbolic Functions, Scientific Functions ++@section Advanced Mathematical Functions ++ ++@noindent ++Calc can compute a variety of less common functions that arise in ++various branches of mathematics. All of the functions described in ++this section allow arbitrary complex arguments and, except as noted, ++will work to arbitrarily large precisions. They can not at present ++handle error forms or intervals as arguments. ++ ++NOTE: These functions are still experimental. In particular, their ++accuracy is not guaranteed in all domains. It is advisable to set the ++current precision comfortably higher than you actually need when ++using these functions. Also, these functions may be impractically ++slow for some values of the arguments. ++ ++@kindex f g ++@pindex calc-gamma ++@tindex gamma ++The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler ++gamma function. For positive integer arguments, this is related to the ++factorial function: @samp{gamma(n+1) = fact(n)}. For general complex ++arguments the gamma function can be defined by the following definite ++integral: ++@texline @math{\Gamma(a) = \int_0^\infty t^{a-1} e^t dt}. ++@infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}. ++(The actual implementation uses far more efficient computational methods.) ++ ++@kindex f G ++@tindex gammaP ++@ignore ++@mindex @idots ++@end ignore ++@kindex I f G ++@ignore ++@mindex @null ++@end ignore ++@kindex H f G ++@ignore ++@mindex @null ++@end ignore ++@kindex H I f G ++@pindex calc-inc-gamma ++@ignore ++@mindex @null ++@end ignore ++@tindex gammaQ ++@ignore ++@mindex @null ++@end ignore ++@tindex gammag ++@ignore ++@mindex @null ++@end ignore ++@tindex gammaG ++The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes ++the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by ++the integral, ++@texline @math{P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)}. ++@infoline @expr{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}. ++This implies that @samp{gammaP(a,inf) = 1} for any @expr{a} (see the ++definition of the normal gamma function). ++ ++Several other varieties of incomplete gamma function are defined. ++The complement of @expr{P(a,x)}, called @expr{Q(a,x) = 1-P(a,x)} by ++some authors, is computed by the @kbd{I f G} [@code{gammaQ}] command. ++You can think of this as taking the other half of the integral, from ++@expr{x} to infinity. ++ ++@ifnottex ++The functions corresponding to the integrals that define @expr{P(a,x)} ++and @expr{Q(a,x)} but without the normalizing @expr{1/gamma(a)} ++factor are called @expr{g(a,x)} and @expr{G(a,x)}, respectively ++(where @expr{g} and @expr{G} represent the lower- and upper-case Greek ++letter gamma). You can obtain these using the @kbd{H f G} [@code{gammag}] ++and @kbd{H I f G} [@code{gammaG}] commands. ++@end ifnottex ++@tex ++\turnoffactive ++The functions corresponding to the integrals that define $P(a,x)$ ++and $Q(a,x)$ but without the normalizing $1/\Gamma(a)$ ++factor are called $\gamma(a,x)$ and $\Gamma(a,x)$, respectively. ++You can obtain these using the \kbd{H f G} [\code{gammag}] and ++\kbd{I H f G} [\code{gammaG}] commands. ++@end tex ++ ++@kindex f b ++@pindex calc-beta ++@tindex beta ++The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the ++Euler beta function, which is defined in terms of the gamma function as ++@texline @math{B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)}, ++@infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)}, ++or by ++@texline @math{B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}. ++@infoline @expr{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}. ++ ++@kindex f B ++@kindex H f B ++@pindex calc-inc-beta ++@tindex betaI ++@tindex betaB ++The @kbd{f B} (@code{calc-inc-beta}) [@code{betaI}] command computes ++the incomplete beta function @expr{I(x,a,b)}. It is defined by ++@texline @math{I(x,a,b) = \left( \int_0^x t^{a-1} (1-t)^{b-1} dt \right) / B(a,b)}. ++@infoline @expr{betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)}. ++Once again, the @kbd{H} (hyperbolic) prefix gives the corresponding ++un-normalized version [@code{betaB}]. ++ ++@kindex f e ++@kindex I f e ++@pindex calc-erf ++@tindex erf ++@tindex erfc ++The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the ++error function ++@texline @math{\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt}. ++@infoline @expr{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}. ++The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}] ++is the corresponding integral from @samp{x} to infinity; the sum ++@texline @math{\hbox{erf}(x) + \hbox{erfc}(x) = 1}. ++@infoline @expr{erf(x) + erfc(x) = 1}. ++ ++@kindex f j ++@kindex f y ++@pindex calc-bessel-J ++@pindex calc-bessel-Y ++@tindex besJ ++@tindex besY ++The @kbd{f j} (@code{calc-bessel-J}) [@code{besJ}] and @kbd{f y} ++(@code{calc-bessel-Y}) [@code{besY}] commands compute the Bessel ++functions of the first and second kinds, respectively. ++In @samp{besJ(n,x)} and @samp{besY(n,x)} the ``order'' parameter ++@expr{n} is often an integer, but is not required to be one. ++Calc's implementation of the Bessel functions currently limits the ++precision to 8 digits, and may not be exact even to that precision. ++Use with care! ++ ++@node Branch Cuts, Random Numbers, Advanced Math Functions, Scientific Functions ++@section Branch Cuts and Principal Values ++ ++@noindent ++@cindex Branch cuts ++@cindex Principal values ++All of the logarithmic, trigonometric, and other scientific functions are ++defined for complex numbers as well as for reals. ++This section describes the values ++returned in cases where the general result is a family of possible values. ++Calc follows section 12.5.3 of Steele's @dfn{Common Lisp, the Language}, ++second edition, in these matters. This section will describe each ++function briefly; for a more detailed discussion (including some nifty ++diagrams), consult Steele's book. ++ ++Note that the branch cuts for @code{arctan} and @code{arctanh} were ++changed between the first and second editions of Steele. Recent ++versions of Calc follow the second edition. ++ ++The new branch cuts exactly match those of the HP-28/48 calculators. ++They also match those of Mathematica 1.2, except that Mathematica's ++@code{arctan} cut is always in the right half of the complex plane, ++and its @code{arctanh} cut is always in the top half of the plane. ++Calc's cuts are continuous with quadrants I and III for @code{arctan}, ++or II and IV for @code{arctanh}. ++ ++Note: The current implementations of these functions with complex arguments ++are designed with proper behavior around the branch cuts in mind, @emph{not} ++efficiency or accuracy. You may need to increase the floating precision ++and wait a while to get suitable answers from them. ++ ++For @samp{sqrt(a+bi)}: When @expr{a<0} and @expr{b} is small but positive ++or zero, the result is close to the @expr{+i} axis. For @expr{b} small and ++negative, the result is close to the @expr{-i} axis. The result always lies ++in the right half of the complex plane. ++ ++For @samp{ln(a+bi)}: The real part is defined as @samp{ln(abs(a+bi))}. ++The imaginary part is defined as @samp{arg(a+bi) = arctan2(b,a)}. ++Thus the branch cuts for @code{sqrt} and @code{ln} both lie on the ++negative real axis. ++ ++The following table describes these branch cuts in another way. ++If the real and imaginary parts of @expr{z} are as shown, then ++the real and imaginary parts of @expr{f(z)} will be as shown. ++Here @code{eps} stands for a small positive value; each ++occurrence of @code{eps} may stand for a different small value. ++ ++@smallexample ++ z sqrt(z) ln(z) ++---------------------------------------- ++ +, 0 +, 0 any, 0 ++ -, 0 0, + any, pi ++ -, +eps +eps, + +eps, + ++ -, -eps +eps, - +eps, - ++@end smallexample ++ ++For @samp{z1^z2}: This is defined by @samp{exp(ln(z1)*z2)}. ++One interesting consequence of this is that @samp{(-8)^1:3} does ++not evaluate to @mathit{-2} as you might expect, but to the complex ++number @expr{(1., 1.732)}. Both of these are valid cube roots ++of @mathit{-8} (as is @expr{(1., -1.732)}); Calc chooses a perhaps ++less-obvious root for the sake of mathematical consistency. ++ ++For @samp{arcsin(z)}: This is defined by @samp{-i*ln(i*z + sqrt(1-z^2))}. ++The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. ++ ++For @samp{arccos(z)}: This is defined by @samp{-i*ln(z + i*sqrt(1-z^2))}, ++or equivalently by @samp{pi/2 - arcsin(z)}. The branch cuts are on ++the real axis, less than @mathit{-1} and greater than 1. ++ ++For @samp{arctan(z)}: This is defined by ++@samp{(ln(1+i*z) - ln(1-i*z)) / (2*i)}. The branch cuts are on the ++imaginary axis, below @expr{-i} and above @expr{i}. ++ ++For @samp{arcsinh(z)}: This is defined by @samp{ln(z + sqrt(1+z^2))}. ++The branch cuts are on the imaginary axis, below @expr{-i} and ++above @expr{i}. ++ ++For @samp{arccosh(z)}: This is defined by ++@samp{ln(z + (z+1)*sqrt((z-1)/(z+1)))}. The branch cut is on the ++real axis less than 1. ++ ++For @samp{arctanh(z)}: This is defined by @samp{(ln(1+z) - ln(1-z)) / 2}. ++The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. ++ ++The following tables for @code{arcsin}, @code{arccos}, and ++@code{arctan} assume the current angular mode is Radians. The ++hyperbolic functions operate independently of the angular mode. ++ ++@smallexample ++ z arcsin(z) arccos(z) ++------------------------------------------------------- ++ (-1..1), 0 (-pi/2..pi/2), 0 (0..pi), 0 ++ (-1..1), +eps (-pi/2..pi/2), +eps (0..pi), -eps ++ (-1..1), -eps (-pi/2..pi/2), -eps (0..pi), +eps ++ <-1, 0 -pi/2, + pi, - ++ <-1, +eps -pi/2 + eps, + pi - eps, - ++ <-1, -eps -pi/2 + eps, - pi - eps, + ++ >1, 0 pi/2, - 0, + ++ >1, +eps pi/2 - eps, + +eps, - ++ >1, -eps pi/2 - eps, - +eps, + ++@end smallexample ++ ++@smallexample ++ z arccosh(z) arctanh(z) ++----------------------------------------------------- ++ (-1..1), 0 0, (0..pi) any, 0 ++ (-1..1), +eps +eps, (0..pi) any, +eps ++ (-1..1), -eps +eps, (-pi..0) any, -eps ++ <-1, 0 +, pi -, pi/2 ++ <-1, +eps +, pi - eps -, pi/2 - eps ++ <-1, -eps +, -pi + eps -, -pi/2 + eps ++ >1, 0 +, 0 +, -pi/2 ++ >1, +eps +, +eps +, pi/2 - eps ++ >1, -eps +, -eps +, -pi/2 + eps ++@end smallexample ++ ++@smallexample ++ z arcsinh(z) arctan(z) ++----------------------------------------------------- ++ 0, (-1..1) 0, (-pi/2..pi/2) 0, any ++ 0, <-1 -, -pi/2 -pi/2, - ++ +eps, <-1 +, -pi/2 + eps pi/2 - eps, - ++ -eps, <-1 -, -pi/2 + eps -pi/2 + eps, - ++ 0, >1 +, pi/2 pi/2, + ++ +eps, >1 +, pi/2 - eps pi/2 - eps, + ++ -eps, >1 -, pi/2 - eps -pi/2 + eps, + ++@end smallexample ++ ++Finally, the following identities help to illustrate the relationship ++between the complex trigonometric and hyperbolic functions. They ++are valid everywhere, including on the branch cuts. ++ ++@smallexample ++sin(i*z) = i*sinh(z) arcsin(i*z) = i*arcsinh(z) ++cos(i*z) = cosh(z) arcsinh(i*z) = i*arcsin(z) ++tan(i*z) = i*tanh(z) arctan(i*z) = i*arctanh(z) ++sinh(i*z) = i*sin(z) cosh(i*z) = cos(z) ++@end smallexample ++ ++The ``advanced math'' functions (gamma, Bessel, etc.@:) are also defined ++for general complex arguments, but their branch cuts and principal values ++are not rigorously specified at present. ++ ++@node Random Numbers, Combinatorial Functions, Branch Cuts, Scientific Functions ++@section Random Numbers ++ ++@noindent ++@kindex k r ++@pindex calc-random ++@tindex random ++The @kbd{k r} (@code{calc-random}) [@code{random}] command produces ++random numbers of various sorts. ++ ++Given a positive numeric prefix argument @expr{M}, it produces a random ++integer @expr{N} in the range ++@texline @math{0 \le N < M}. ++@infoline @expr{0 <= N < M}. ++Each possible value @expr{N} appears with equal probability. ++ ++With no numeric prefix argument, the @kbd{k r} command takes its argument ++from the stack instead. Once again, if this is a positive integer @expr{M} ++the result is a random integer less than @expr{M}. However, note that ++while numeric prefix arguments are limited to six digits or so, an @expr{M} ++taken from the stack can be arbitrarily large. If @expr{M} is negative, ++the result is a random integer in the range ++@texline @math{M < N \le 0}. ++@infoline @expr{M < N <= 0}. ++ ++If the value on the stack is a floating-point number @expr{M}, the result ++is a random floating-point number @expr{N} in the range ++@texline @math{0 \le N < M} ++@infoline @expr{0 <= N < M} ++or ++@texline @math{M < N \le 0}, ++@infoline @expr{M < N <= 0}, ++according to the sign of @expr{M}. ++ ++If @expr{M} is zero, the result is a Gaussian-distributed random real ++number; the distribution has a mean of zero and a standard deviation ++of one. The algorithm used generates random numbers in pairs; thus, ++every other call to this function will be especially fast. ++ ++If @expr{M} is an error form ++@texline @math{m} @code{+/-} @math{\sigma} ++@infoline @samp{m +/- s} ++where @var{m} and ++@texline @math{\sigma} ++@infoline @var{s} ++are both real numbers, the result uses a Gaussian distribution with mean ++@var{m} and standard deviation ++@texline @math{\sigma}. ++@infoline @var{s}. ++ ++If @expr{M} is an interval form, the lower and upper bounds specify the ++acceptable limits of the random numbers. If both bounds are integers, ++the result is a random integer in the specified range. If either bound ++is floating-point, the result is a random real number in the specified ++range. If the interval is open at either end, the result will be sure ++not to equal that end value. (This makes a big difference for integer ++intervals, but for floating-point intervals it's relatively minor: ++with a precision of 6, @samp{random([1.0..2.0))} will return any of one ++million numbers from 1.00000 to 1.99999; @samp{random([1.0..2.0])} may ++additionally return 2.00000, but the probability of this happening is ++extremely small.) ++ ++If @expr{M} is a vector, the result is one element taken at random from ++the vector. All elements of the vector are given equal probabilities. ++ ++@vindex RandSeed ++The sequence of numbers produced by @kbd{k r} is completely random by ++default, i.e., the sequence is seeded each time you start Calc using ++the current time and other information. You can get a reproducible ++sequence by storing a particular ``seed value'' in the Calc variable ++@code{RandSeed}. Any integer will do for a seed; integers of from 1 ++to 12 digits are good. If you later store a different integer into ++@code{RandSeed}, Calc will switch to a different pseudo-random ++sequence. If you ``unstore'' @code{RandSeed}, Calc will re-seed itself ++from the current time. If you store the same integer that you used ++before back into @code{RandSeed}, you will get the exact same sequence ++of random numbers as before. ++ ++@pindex calc-rrandom ++The @code{calc-rrandom} command (not on any key) produces a random real ++number between zero and one. It is equivalent to @samp{random(1.0)}. ++ ++@kindex k a ++@pindex calc-random-again ++The @kbd{k a} (@code{calc-random-again}) command produces another random ++number, re-using the most recent value of @expr{M}. With a numeric ++prefix argument @var{n}, it produces @var{n} more random numbers using ++that value of @expr{M}. ++ ++@kindex k h ++@pindex calc-shuffle ++@tindex shuffle ++The @kbd{k h} (@code{calc-shuffle}) command produces a vector of several ++random values with no duplicates. The value on the top of the stack ++specifies the set from which the random values are drawn, and may be any ++of the @expr{M} formats described above. The numeric prefix argument ++gives the length of the desired list. (If you do not provide a numeric ++prefix argument, the length of the list is taken from the top of the ++stack, and @expr{M} from second-to-top.) ++ ++If @expr{M} is a floating-point number, zero, or an error form (so ++that the random values are being drawn from the set of real numbers) ++there is little practical difference between using @kbd{k h} and using ++@kbd{k r} several times. But if the set of possible values consists ++of just a few integers, or the elements of a vector, then there is ++a very real chance that multiple @kbd{k r}'s will produce the same ++number more than once. The @kbd{k h} command produces a vector whose ++elements are always distinct. (Actually, there is a slight exception: ++If @expr{M} is a vector, no given vector element will be drawn more ++than once, but if several elements of @expr{M} are equal, they may ++each make it into the result vector.) ++ ++One use of @kbd{k h} is to rearrange a list at random. This happens ++if the prefix argument is equal to the number of values in the list: ++@kbd{[1, 1.5, 2, 2.5, 3] 5 k h} might produce the permuted list ++@samp{[2.5, 1, 1.5, 3, 2]}. As a convenient feature, if the argument ++@var{n} is negative it is replaced by the size of the set represented ++by @expr{M}. Naturally, this is allowed only when @expr{M} specifies ++a small discrete set of possibilities. ++ ++To do the equivalent of @kbd{k h} but with duplications allowed, ++given @expr{M} on the stack and with @var{n} just entered as a numeric ++prefix, use @kbd{v b} to build a vector of copies of @expr{M}, then use ++@kbd{V M k r} to ``map'' the normal @kbd{k r} function over the ++elements of this vector. @xref{Matrix Functions}. ++ ++@menu ++* Random Number Generator:: (Complete description of Calc's algorithm) ++@end menu ++ ++@node Random Number Generator, , Random Numbers, Random Numbers ++@subsection Random Number Generator ++ ++Calc's random number generator uses several methods to ensure that ++the numbers it produces are highly random. Knuth's @emph{Art of ++Computer Programming}, Volume II, contains a thorough description ++of the theory of random number generators and their measurement and ++characterization. ++ ++If @code{RandSeed} has no stored value, Calc calls Emacs' built-in ++@code{random} function to get a stream of random numbers, which it ++then treats in various ways to avoid problems inherent in the simple ++random number generators that many systems use to implement @code{random}. ++ ++When Calc's random number generator is first invoked, it ``seeds'' ++the low-level random sequence using the time of day, so that the ++random number sequence will be different every time you use Calc. ++ ++Since Emacs Lisp doesn't specify the range of values that will be ++returned by its @code{random} function, Calc exercises the function ++several times to estimate the range. When Calc subsequently uses ++the @code{random} function, it takes only 10 bits of the result ++near the most-significant end. (It avoids at least the bottom ++four bits, preferably more, and also tries to avoid the top two ++bits.) This strategy works well with the linear congruential ++generators that are typically used to implement @code{random}. ++ ++If @code{RandSeed} contains an integer, Calc uses this integer to ++seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A, ++computing ++@texline @math{X_{n-55} - X_{n-24}}. ++@infoline @expr{X_n-55 - X_n-24}). ++This method expands the seed ++value into a large table which is maintained internally; the variable ++@code{RandSeed} is changed from, e.g., 42 to the vector @expr{[42]} ++to indicate that the seed has been absorbed into this table. When ++@code{RandSeed} contains a vector, @kbd{k r} and related commands ++continue to use the same internal table as last time. There is no ++way to extract the complete state of the random number generator ++so that you can restart it from any point; you can only restart it ++from the same initial seed value. A simple way to restart from the ++same seed is to type @kbd{s r RandSeed} to get the seed vector, ++@kbd{v u} to unpack it back into a number, then @kbd{s t RandSeed} ++to reseed the generator with that number. ++ ++Calc uses a ``shuffling'' method as described in algorithm 3.2.2B ++of Knuth. It fills a table with 13 random 10-bit numbers. Then, ++to generate a new random number, it uses the previous number to ++index into the table, picks the value it finds there as the new ++random number, then replaces that table entry with a new value ++obtained from a call to the base random number generator (either ++the additive congruential generator or the @code{random} function ++supplied by the system). If there are any flaws in the base ++generator, shuffling will tend to even them out. But if the system ++provides an excellent @code{random} function, shuffling will not ++damage its randomness. ++ ++To create a random integer of a certain number of digits, Calc ++builds the integer three decimal digits at a time. For each group ++of three digits, Calc calls its 10-bit shuffling random number generator ++(which returns a value from 0 to 1023); if the random value is 1000 ++or more, Calc throws it out and tries again until it gets a suitable ++value. ++ ++To create a random floating-point number with precision @var{p}, Calc ++simply creates a random @var{p}-digit integer and multiplies by ++@texline @math{10^{-p}}. ++@infoline @expr{10^-p}. ++The resulting random numbers should be very clean, but note ++that relatively small numbers will have few significant random digits. ++In other words, with a precision of 12, you will occasionally get ++numbers on the order of ++@texline @math{10^{-9}} ++@infoline @expr{10^-9} ++or ++@texline @math{10^{-10}}, ++@infoline @expr{10^-10}, ++but those numbers will only have two or three random digits since they ++correspond to small integers times ++@texline @math{10^{-12}}. ++@infoline @expr{10^-12}. ++ ++To create a random integer in the interval @samp{[0 .. @var{m})}, Calc ++counts the digits in @var{m}, creates a random integer with three ++additional digits, then reduces modulo @var{m}. Unless @var{m} is a ++power of ten the resulting values will be very slightly biased toward ++the lower numbers, but this bias will be less than 0.1%. (For example, ++if @var{m} is 42, Calc will reduce a random integer less than 100000 ++modulo 42 to get a result less than 42. It is easy to show that the ++numbers 40 and 41 will be only 2380/2381 as likely to result from this ++modulo operation as numbers 39 and below.) If @var{m} is a power of ++ten, however, the numbers should be completely unbiased. ++ ++The Gaussian random numbers generated by @samp{random(0.0)} use the ++``polar'' method described in Knuth section 3.4.1C. This method ++generates a pair of Gaussian random numbers at a time, so only every ++other call to @samp{random(0.0)} will require significant calculations. ++ ++@node Combinatorial Functions, Probability Distribution Functions, Random Numbers, Scientific Functions ++@section Combinatorial Functions ++ ++@noindent ++Commands relating to combinatorics and number theory begin with the ++@kbd{k} key prefix. ++ ++@kindex k g ++@pindex calc-gcd ++@tindex gcd ++The @kbd{k g} (@code{calc-gcd}) [@code{gcd}] command computes the ++Greatest Common Divisor of two integers. It also accepts fractions; ++the GCD of two fractions is defined by taking the GCD of the ++numerators, and the LCM of the denominators. This definition is ++consistent with the idea that @samp{a / gcd(a,x)} should yield an ++integer for any @samp{a} and @samp{x}. For other types of arguments, ++the operation is left in symbolic form. ++ ++@kindex k l ++@pindex calc-lcm ++@tindex lcm ++The @kbd{k l} (@code{calc-lcm}) [@code{lcm}] command computes the ++Least Common Multiple of two integers or fractions. The product of ++the LCM and GCD of two numbers is equal to the product of the ++numbers. ++ ++@kindex k E ++@pindex calc-extended-gcd ++@tindex egcd ++The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes ++the GCD of two integers @expr{x} and @expr{y} and returns a vector ++@expr{[g, a, b]} where ++@texline @math{g = \gcd(x,y) = a x + b y}. ++@infoline @expr{g = gcd(x,y) = a x + b y}. ++ ++@kindex ! ++@pindex calc-factorial ++@tindex fact ++@ignore ++@mindex @null ++@end ignore ++@tindex ! ++The @kbd{!} (@code{calc-factorial}) [@code{fact}] command computes the ++factorial of the number at the top of the stack. If the number is an ++integer, the result is an exact integer. If the number is an ++integer-valued float, the result is a floating-point approximation. If ++the number is a non-integral real number, the generalized factorial is used, ++as defined by the Euler Gamma function. Please note that computation of ++large factorials can be slow; using floating-point format will help ++since fewer digits must be maintained. The same is true of many of ++the commands in this section. ++ ++@kindex k d ++@pindex calc-double-factorial ++@tindex dfact ++@ignore ++@mindex @null ++@end ignore ++@tindex !! ++The @kbd{k d} (@code{calc-double-factorial}) [@code{dfact}] command ++computes the ``double factorial'' of an integer. For an even integer, ++this is the product of even integers from 2 to @expr{N}. For an odd ++integer, this is the product of odd integers from 3 to @expr{N}. If ++the argument is an integer-valued float, the result is a floating-point ++approximation. This function is undefined for negative even integers. ++The notation @expr{N!!} is also recognized for double factorials. ++ ++@kindex k c ++@pindex calc-choose ++@tindex choose ++The @kbd{k c} (@code{calc-choose}) [@code{choose}] command computes the ++binomial coefficient @expr{N}-choose-@expr{M}, where @expr{M} is the number ++on the top of the stack and @expr{N} is second-to-top. If both arguments ++are integers, the result is an exact integer. Otherwise, the result is a ++floating-point approximation. The binomial coefficient is defined for all ++real numbers by ++@texline @math{N! \over M! (N-M)!\,}. ++@infoline @expr{N! / M! (N-M)!}. ++ ++@kindex H k c ++@pindex calc-perm ++@tindex perm ++@ifnottex ++The @kbd{H k c} (@code{calc-perm}) [@code{perm}] command computes the ++number-of-permutations function @expr{N! / (N-M)!}. ++@end ifnottex ++@tex ++The \kbd{H k c} (\code{calc-perm}) [\code{perm}] command computes the ++number-of-perm\-utations function $N! \over (N-M)!\,$. ++@end tex ++ ++@kindex k b ++@kindex H k b ++@pindex calc-bernoulli-number ++@tindex bern ++The @kbd{k b} (@code{calc-bernoulli-number}) [@code{bern}] command ++computes a given Bernoulli number. The value at the top of the stack ++is a nonnegative integer @expr{n} that specifies which Bernoulli number ++is desired. The @kbd{H k b} command computes a Bernoulli polynomial, ++taking @expr{n} from the second-to-top position and @expr{x} from the ++top of the stack. If @expr{x} is a variable or formula the result is ++a polynomial in @expr{x}; if @expr{x} is a number the result is a number. ++ ++@kindex k e ++@kindex H k e ++@pindex calc-euler-number ++@tindex euler ++The @kbd{k e} (@code{calc-euler-number}) [@code{euler}] command similarly ++computes an Euler number, and @w{@kbd{H k e}} computes an Euler polynomial. ++Bernoulli and Euler numbers occur in the Taylor expansions of several ++functions. ++ ++@kindex k s ++@kindex H k s ++@pindex calc-stirling-number ++@tindex stir1 ++@tindex stir2 ++The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command ++computes a Stirling number of the first ++@texline kind@tie{}@math{n \brack m}, ++@infoline kind, ++given two integers @expr{n} and @expr{m} on the stack. The @kbd{H k s} ++[@code{stir2}] command computes a Stirling number of the second ++@texline kind@tie{}@math{n \brace m}. ++@infoline kind. ++These are the number of @expr{m}-cycle permutations of @expr{n} objects, ++and the number of ways to partition @expr{n} objects into @expr{m} ++non-empty sets, respectively. ++ ++@kindex k p ++@pindex calc-prime-test ++@cindex Primes ++The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on ++the top of the stack is prime. For integers less than eight million, the ++answer is always exact and reasonably fast. For larger integers, a ++probabilistic method is used (see Knuth vol. II, section 4.5.4, algorithm P). ++The number is first checked against small prime factors (up to 13). Then, ++any number of iterations of the algorithm are performed. Each step either ++discovers that the number is non-prime, or substantially increases the ++certainty that the number is prime. After a few steps, the chance that ++a number was mistakenly described as prime will be less than one percent. ++(Indeed, this is a worst-case estimate of the probability; in practice ++even a single iteration is quite reliable.) After the @kbd{k p} command, ++the number will be reported as definitely prime or non-prime if possible, ++or otherwise ``probably'' prime with a certain probability of error. ++ ++@ignore ++@starindex ++@end ignore ++@tindex prime ++The normal @kbd{k p} command performs one iteration of the primality ++test. Pressing @kbd{k p} repeatedly for the same integer will perform ++additional iterations. Also, @kbd{k p} with a numeric prefix performs ++the specified number of iterations. There is also an algebraic function ++@samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @expr{n} ++is (probably) prime and 0 if not. ++ ++@kindex k f ++@pindex calc-prime-factors ++@tindex prfac ++The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command ++attempts to decompose an integer into its prime factors. For numbers up ++to 25 million, the answer is exact although it may take some time. The ++result is a vector of the prime factors in increasing order. For larger ++inputs, prime factors above 5000 may not be found, in which case the ++last number in the vector will be an unfactored integer greater than 25 ++million (with a warning message). For negative integers, the first ++element of the list will be @mathit{-1}. For inputs @mathit{-1}, @mathit{0}, and ++@mathit{1}, the result is a list of the same number. ++ ++@kindex k n ++@pindex calc-next-prime ++@ignore ++@mindex nextpr@idots ++@end ignore ++@tindex nextprime ++The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds ++the next prime above a given number. Essentially, it searches by calling ++@code{calc-prime-test} on successive integers until it finds one that ++passes the test. This is quite fast for integers less than eight million, ++but once the probabilistic test comes into play the search may be rather ++slow. Ordinarily this command stops for any prime that passes one iteration ++of the primality test. With a numeric prefix argument, a number must pass ++the specified number of iterations before the search stops. (This only ++matters when searching above eight million.) You can always use additional ++@kbd{k p} commands to increase your certainty that the number is indeed ++prime. ++ ++@kindex I k n ++@pindex calc-prev-prime ++@ignore ++@mindex prevpr@idots ++@end ignore ++@tindex prevprime ++The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command ++analogously finds the next prime less than a given number. ++ ++@kindex k t ++@pindex calc-totient ++@tindex totient ++The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the ++Euler ``totient'' ++@texline function@tie{}@math{\phi(n)}, ++@infoline function, ++the number of integers less than @expr{n} which ++are relatively prime to @expr{n}. ++ ++@kindex k m ++@pindex calc-moebius ++@tindex moebius ++The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the ++@texline M@"obius @math{\mu} ++@infoline Moebius ``mu'' ++function. If the input number is a product of @expr{k} ++distinct factors, this is @expr{(-1)^k}. If the input number has any ++duplicate factors (i.e., can be divided by the same prime more than once), ++the result is zero. ++ ++@node Probability Distribution Functions, , Combinatorial Functions, Scientific Functions ++@section Probability Distribution Functions ++ ++@noindent ++The functions in this section compute various probability distributions. ++For continuous distributions, this is the integral of the probability ++density function from @expr{x} to infinity. (These are the ``upper ++tail'' distribution functions; there are also corresponding ``lower ++tail'' functions which integrate from minus infinity to @expr{x}.) ++For discrete distributions, the upper tail function gives the sum ++from @expr{x} to infinity; the lower tail function gives the sum ++from minus infinity up to, but not including,@w{ }@expr{x}. ++ ++To integrate from @expr{x} to @expr{y}, just use the distribution ++function twice and subtract. For example, the probability that a ++Gaussian random variable with mean 2 and standard deviation 1 will ++lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)} ++(``the probability that it is greater than 2.5, but not greater than 2.8''), ++or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}. ++ ++@kindex k B ++@kindex I k B ++@pindex calc-utpb ++@tindex utpb ++@tindex ltpb ++The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the ++binomial distribution. Push the parameters @var{n}, @var{p}, and ++then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the ++probability that an event will occur @var{x} or more times out ++of @var{n} trials, if its probability of occurring in any given ++trial is @var{p}. The @kbd{I k B} [@code{ltpb}] function is ++the probability that the event will occur fewer than @var{x} times. ++ ++The other probability distribution functions similarly take the ++form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}] ++and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters ++@var{x}. The arguments to the algebraic functions are the value of ++the random variable first, then whatever other parameters define the ++distribution. Note these are among the few Calc functions where the ++order of the arguments in algebraic form differs from the order of ++arguments as found on the stack. (The random variable comes last on ++the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5 ++k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to ++recover the original arguments but substitute a new value for @expr{x}.) ++ ++@kindex k C ++@pindex calc-utpc ++@tindex utpc ++@ignore ++@mindex @idots ++@end ignore ++@kindex I k C ++@ignore ++@mindex @null ++@end ignore ++@tindex ltpc ++The @samp{utpc(x,v)} function uses the chi-square distribution with ++@texline @math{\nu} ++@infoline @expr{v} ++degrees of freedom. It is the probability that a model is ++correct if its chi-square statistic is @expr{x}. ++ ++@kindex k F ++@pindex calc-utpf ++@tindex utpf ++@ignore ++@mindex @idots ++@end ignore ++@kindex I k F ++@ignore ++@mindex @null ++@end ignore ++@tindex ltpf ++The @samp{utpf(F,v1,v2)} function uses the F distribution, used in ++various statistical tests. The parameters ++@texline @math{\nu_1} ++@infoline @expr{v1} ++and ++@texline @math{\nu_2} ++@infoline @expr{v2} ++are the degrees of freedom in the numerator and denominator, ++respectively, used in computing the statistic @expr{F}. ++ ++@kindex k N ++@pindex calc-utpn ++@tindex utpn ++@ignore ++@mindex @idots ++@end ignore ++@kindex I k N ++@ignore ++@mindex @null ++@end ignore ++@tindex ltpn ++The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution ++with mean @expr{m} and standard deviation ++@texline @math{\sigma}. ++@infoline @expr{s}. ++It is the probability that such a normal-distributed random variable ++would exceed @expr{x}. ++ ++@kindex k P ++@pindex calc-utpp ++@tindex utpp ++@ignore ++@mindex @idots ++@end ignore ++@kindex I k P ++@ignore ++@mindex @null ++@end ignore ++@tindex ltpp ++The @samp{utpp(n,x)} function uses a Poisson distribution with ++mean @expr{x}. It is the probability that @expr{n} or more such ++Poisson random events will occur. ++ ++@kindex k T ++@pindex calc-ltpt ++@tindex utpt ++@ignore ++@mindex @idots ++@end ignore ++@kindex I k T ++@ignore ++@mindex @null ++@end ignore ++@tindex ltpt ++The @samp{utpt(t,v)} function uses the Student's ``t'' distribution ++with ++@texline @math{\nu} ++@infoline @expr{v} ++degrees of freedom. It is the probability that a ++t-distributed random variable will be greater than @expr{t}. ++(Note: This computes the distribution function ++@texline @math{A(t|\nu)} ++@infoline @expr{A(t|v)} ++where ++@texline @math{A(0|\nu) = 1} ++@infoline @expr{A(0|v) = 1} ++and ++@texline @math{A(\infty|\nu) \to 0}. ++@infoline @expr{A(inf|v) -> 0}. ++The @code{UTPT} operation on the HP-48 uses a different definition which ++returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.) ++ ++While Calc does not provide inverses of the probability distribution ++functions, the @kbd{a R} command can be used to solve for the inverse. ++Since the distribution functions are monotonic, @kbd{a R} is guaranteed ++to be able to find a solution given any initial guess. ++@xref{Numerical Solutions}. ++ ++@node Matrix Functions, Algebra, Scientific Functions, Top ++@chapter Vector/Matrix Functions ++ ++@noindent ++Many of the commands described here begin with the @kbd{v} prefix. ++(For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.) ++The commands usually apply to both plain vectors and matrices; some ++apply only to matrices or only to square matrices. If the argument ++has the wrong dimensions the operation is left in symbolic form. ++ ++Vectors are entered and displayed using @samp{[a,b,c]} notation. ++Matrices are vectors of which all elements are vectors of equal length. ++(Though none of the standard Calc commands use this concept, a ++three-dimensional matrix or rank-3 tensor could be defined as a ++vector of matrices, and so on.) ++ ++@menu ++* Packing and Unpacking:: ++* Building Vectors:: ++* Extracting Elements:: ++* Manipulating Vectors:: ++* Vector and Matrix Arithmetic:: ++* Set Operations:: ++* Statistical Operations:: ++* Reducing and Mapping:: ++* Vector and Matrix Formats:: ++@end menu ++ ++@node Packing and Unpacking, Building Vectors, Matrix Functions, Matrix Functions ++@section Packing and Unpacking ++ ++@noindent ++Calc's ``pack'' and ``unpack'' commands collect stack entries to build ++composite objects such as vectors and complex numbers. They are ++described in this chapter because they are most often used to build ++vectors. ++ ++@kindex v p ++@pindex calc-pack ++The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several ++elements from the stack into a matrix, complex number, HMS form, error ++form, etc. It uses a numeric prefix argument to specify the kind of ++object to be built; this argument is referred to as the ``packing mode.'' ++If the packing mode is a nonnegative integer, a vector of that ++length is created. For example, @kbd{C-u 5 v p} will pop the top ++five stack elements and push back a single vector of those five ++elements. (@kbd{C-u 0 v p} simply creates an empty vector.) ++ ++The same effect can be had by pressing @kbd{[} to push an incomplete ++vector on the stack, using @key{TAB} (@code{calc-roll-down}) to sneak ++the incomplete object up past a certain number of elements, and ++then pressing @kbd{]} to complete the vector. ++ ++Negative packing modes create other kinds of composite objects: ++ ++@table @cite ++@item -1 ++Two values are collected to build a complex number. For example, ++@kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number ++@expr{(5, 7)}. The result is always a rectangular complex ++number. The two input values must both be real numbers, ++i.e., integers, fractions, or floats. If they are not, Calc ++will instead build a formula like @samp{a + (0, 1) b}. (The ++other packing modes also create a symbolic answer if the ++components are not suitable.) ++ ++@item -2 ++Two values are collected to build a polar complex number. ++The first is the magnitude; the second is the phase expressed ++in either degrees or radians according to the current angular ++mode. ++ ++@item -3 ++Three values are collected into an HMS form. The first ++two values (hours and minutes) must be integers or ++integer-valued floats. The third value may be any real ++number. ++ ++@item -4 ++Two values are collected into an error form. The inputs ++may be real numbers or formulas. ++ ++@item -5 ++Two values are collected into a modulo form. The inputs ++must be real numbers. ++ ++@item -6 ++Two values are collected into the interval @samp{[a .. b]}. ++The inputs may be real numbers, HMS or date forms, or formulas. ++ ++@item -7 ++Two values are collected into the interval @samp{[a .. b)}. ++ ++@item -8 ++Two values are collected into the interval @samp{(a .. b]}. ++ ++@item -9 ++Two values are collected into the interval @samp{(a .. b)}. ++ ++@item -10 ++Two integer values are collected into a fraction. ++ ++@item -11 ++Two values are collected into a floating-point number. ++The first is the mantissa; the second, which must be an ++integer, is the exponent. The result is the mantissa ++times ten to the power of the exponent. ++ ++@item -12 ++This is treated the same as @mathit{-11} by the @kbd{v p} command. ++When unpacking, @mathit{-12} specifies that a floating-point mantissa ++is desired. ++ ++@item -13 ++A real number is converted into a date form. ++ ++@item -14 ++Three numbers (year, month, day) are packed into a pure date form. ++ ++@item -15 ++Six numbers are packed into a date/time form. ++@end table ++ ++With any of the two-input negative packing modes, either or both ++of the inputs may be vectors. If both are vectors of the same ++length, the result is another vector made by packing corresponding ++elements of the input vectors. If one input is a vector and the ++other is a plain number, the number is packed along with each vector ++element to produce a new vector. For example, @kbd{C-u -4 v p} ++could be used to convert a vector of numbers and a vector of errors ++into a single vector of error forms; @kbd{C-u -5 v p} could convert ++a vector of numbers and a single number @var{M} into a vector of ++numbers modulo @var{M}. ++ ++If you don't give a prefix argument to @kbd{v p}, it takes ++the packing mode from the top of the stack. The elements to ++be packed then begin at stack level 2. Thus ++@kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to ++enter the error form @samp{1 +/- 2}. ++ ++If the packing mode taken from the stack is a vector, the result is a ++matrix with the dimensions specified by the elements of the vector, ++which must each be integers. For example, if the packing mode is ++@samp{[2, 3]}, then six numbers will be taken from the stack and ++returned in the form @samp{[@w{[a, b, c]}, [d, e, f]]}. ++ ++If any elements of the vector are negative, other kinds of ++packing are done at that level as described above. For ++example, @samp{[2, 3, -4]} takes 12 objects and creates a ++@texline @math{2\times3} ++@infoline 2x3 ++matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}. ++Also, @samp{[-4, -10]} will convert four integers into an ++error form consisting of two fractions: @samp{a:b +/- c:d}. ++ ++@ignore ++@starindex ++@end ignore ++@tindex pack ++There is an equivalent algebraic function, ++@samp{pack(@var{mode}, @var{items})} where @var{mode} is a ++packing mode (an integer or a vector of integers) and @var{items} ++is a vector of objects to be packed (re-packed, really) according ++to that mode. For example, @samp{pack([3, -4], [a,b,c,d,e,f])} ++yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}. The function is ++left in symbolic form if the packing mode is invalid, or if the ++number of data items does not match the number of items required ++by the mode. ++ ++@kindex v u ++@pindex calc-unpack ++The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex ++number, HMS form, or other composite object on the top of the stack and ++``unpacks'' it, pushing each of its elements onto the stack as separate ++objects. Thus, it is the ``inverse'' of @kbd{v p}. If the value ++at the top of the stack is a formula, @kbd{v u} unpacks it by pushing ++each of the arguments of the top-level operator onto the stack. ++ ++You can optionally give a numeric prefix argument to @kbd{v u} ++to specify an explicit (un)packing mode. If the packing mode is ++negative and the input is actually a vector or matrix, the result ++will be two or more similar vectors or matrices of the elements. ++For example, given the vector @samp{[@w{a +/- b}, c^2, d +/- 7]}, ++the result of @kbd{C-u -4 v u} will be the two vectors ++@samp{[a, c^2, d]} and @w{@samp{[b, 0, 7]}}. ++ ++Note that the prefix argument can have an effect even when the input is ++not a vector. For example, if the input is the number @mathit{-5}, then ++@kbd{c-u -1 v u} yields @mathit{-5} and 0 (the components of @mathit{-5} ++when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5 ++and 180 (assuming Degrees mode); and @kbd{C-u -10 v u} yields @mathit{-5} ++and 1 (the numerator and denominator of @mathit{-5}, viewed as a rational ++number). Plain @kbd{v u} with this input would complain that the input ++is not a composite object. ++ ++Unpacking mode @mathit{-11} converts a float into an integer mantissa and ++an integer exponent, where the mantissa is not divisible by 10 ++(except that 0.0 is represented by a mantissa and exponent of 0). ++Unpacking mode @mathit{-12} converts a float into a floating-point mantissa ++and integer exponent, where the mantissa (for non-zero numbers) ++is guaranteed to lie in the range [1 .. 10). In both cases, ++the mantissa is shifted left or right (and the exponent adjusted ++to compensate) in order to satisfy these constraints. ++ ++Positive unpacking modes are treated differently than for @kbd{v p}. ++A mode of 1 is much like plain @kbd{v u} with no prefix argument, ++except that in addition to the components of the input object, ++a suitable packing mode to re-pack the object is also pushed. ++Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the ++original object. ++ ++A mode of 2 unpacks two levels of the object; the resulting ++re-packing mode will be a vector of length 2. This might be used ++to unpack a matrix, say, or a vector of error forms. Higher ++unpacking modes unpack the input even more deeply. ++ ++@ignore ++@starindex ++@end ignore ++@tindex unpack ++There are two algebraic functions analogous to @kbd{v u}. ++The @samp{unpack(@var{mode}, @var{item})} function unpacks the ++@var{item} using the given @var{mode}, returning the result as ++a vector of components. Here the @var{mode} must be an ++integer, not a vector. For example, @samp{unpack(-4, a +/- b)} ++returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}. ++ ++@ignore ++@starindex ++@end ignore ++@tindex unpackt ++The @code{unpackt} function is like @code{unpack} but instead ++of returning a simple vector of items, it returns a vector of ++two things: The mode, and the vector of items. For example, ++@samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]}, ++and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}. ++The identity for re-building the original object is ++@samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}. (The ++@code{apply} function builds a function call given the function ++name and a vector of arguments.) ++ ++@cindex Numerator of a fraction, extracting ++Subscript notation is a useful way to extract a particular part ++of an object. For example, to get the numerator of a rational ++number, you can use @samp{unpack(-10, @var{x})_1}. ++ ++@node Building Vectors, Extracting Elements, Packing and Unpacking, Matrix Functions ++@section Building Vectors ++ ++@noindent ++Vectors and matrices can be added, ++subtracted, multiplied, and divided; @pxref{Basic Arithmetic}. ++ ++@kindex | ++@pindex calc-concat ++@ignore ++@mindex @null ++@end ignore ++@tindex | ++The @kbd{|} (@code{calc-concat}) [@code{vconcat}] command ``concatenates'' two vectors ++into one. For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack ++will contain the single vector @samp{[1, 2, 3, 4]}. If the arguments ++are matrices, the rows of the first matrix are concatenated with the ++rows of the second. (In other words, two matrices are just two vectors ++of row-vectors as far as @kbd{|} is concerned.) ++ ++If either argument to @kbd{|} is a scalar (a non-vector), it is treated ++like a one-element vector for purposes of concatenation: @kbd{1 [ 2 , 3 ] |} ++produces the vector @samp{[1, 2, 3]}. Likewise, if one argument is a ++matrix and the other is a plain vector, the vector is treated as a ++one-row matrix. ++ ++@kindex H | ++@tindex append ++The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates ++two vectors without any special cases. Both inputs must be vectors. ++Whether or not they are matrices is not taken into account. If either ++argument is a scalar, the @code{append} function is left in symbolic form. ++See also @code{cons} and @code{rcons} below. ++ ++@kindex I | ++@kindex H I | ++The @kbd{I |} and @kbd{H I |} commands are similar, but they use their ++two stack arguments in the opposite order. Thus @kbd{I |} is equivalent ++to @kbd{@key{TAB} |}, but possibly more convenient and also a bit faster. ++ ++@kindex v d ++@pindex calc-diag ++@tindex diag ++The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal ++square matrix. The optional numeric prefix gives the number of rows ++and columns in the matrix. If the value at the top of the stack is a ++vector, the elements of the vector are used as the diagonal elements; the ++prefix, if specified, must match the size of the vector. If the value on ++the stack is a scalar, it is used for each element on the diagonal, and ++the prefix argument is required. ++ ++To build a constant square matrix, e.g., a ++@texline @math{3\times3} ++@infoline 3x3 ++matrix filled with ones, use @kbd{0 M-3 v d 1 +}, i.e., build a zero ++matrix first and then add a constant value to that matrix. (Another ++alternative would be to use @kbd{v b} and @kbd{v a}; see below.) ++ ++@kindex v i ++@pindex calc-ident ++@tindex idn ++The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity ++matrix of the specified size. It is a convenient form of @kbd{v d} ++where the diagonal element is always one. If no prefix argument is given, ++this command prompts for one. ++ ++In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)}, ++except that @expr{a} is required to be a scalar (non-vector) quantity. ++If @expr{n} is omitted, @samp{idn(a)} represents @expr{a} times an ++identity matrix of unknown size. Calc can operate algebraically on ++such generic identity matrices, and if one is combined with a matrix ++whose size is known, it is converted automatically to an identity ++matrix of a suitable matching size. The @kbd{v i} command with an ++argument of zero creates a generic identity matrix, @samp{idn(1)}. ++Note that in dimensioned Matrix mode (@pxref{Matrix Mode}), generic ++identity matrices are immediately expanded to the current default ++dimensions. ++ ++@kindex v x ++@pindex calc-index ++@tindex index ++The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector ++of consecutive integers from 1 to @var{n}, where @var{n} is the numeric ++prefix argument. If you do not provide a prefix argument, you will be ++prompted to enter a suitable number. If @var{n} is negative, the result ++is a vector of negative integers from @var{n} to @mathit{-1}. ++ ++With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes ++three values from the stack: @var{n}, @var{start}, and @var{incr} (with ++@var{incr} at top-of-stack). Counting starts at @var{start} and increases ++by @var{incr} for successive vector elements. If @var{start} or @var{n} ++is in floating-point format, the resulting vector elements will also be ++floats. Note that @var{start} and @var{incr} may in fact be any kind ++of numbers or formulas. ++ ++When @var{start} and @var{incr} are specified, a negative @var{n} has a ++different interpretation: It causes a geometric instead of arithmetic ++sequence to be generated. For example, @samp{index(-3, a, b)} produces ++@samp{[a, a b, a b^2]}. If you omit @var{incr} in the algebraic form, ++@samp{index(@var{n}, @var{start})}, the default value for @var{incr} ++is one for positive @var{n} or two for negative @var{n}. ++ ++@kindex v b ++@pindex calc-build-vector ++@tindex cvec ++The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a ++vector of @var{n} copies of the value on the top of the stack, where @var{n} ++is the numeric prefix argument. In algebraic formulas, @samp{cvec(x,n,m)} ++can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}. ++(Interactively, just use @kbd{v b} twice: once to build a row, then again ++to build a matrix of copies of that row.) ++ ++@kindex v h ++@kindex I v h ++@pindex calc-head ++@pindex calc-tail ++@tindex head ++@tindex tail ++The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first ++element of a vector. The @kbd{I v h} (@code{calc-tail}) [@code{tail}] ++function returns the vector with its first element removed. In both ++cases, the argument must be a non-empty vector. ++ ++@kindex v k ++@pindex calc-cons ++@tindex cons ++The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h} ++and a vector @var{t} from the stack, and produces the vector whose head is ++@var{h} and whose tail is @var{t}. This is similar to @kbd{|}, except ++if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors ++whereas @code{cons} will insert @var{h} at the front of the vector @var{t}. ++ ++@kindex H v h ++@tindex rhead ++@ignore ++@mindex @idots ++@end ignore ++@kindex H I v h ++@ignore ++@mindex @null ++@end ignore ++@kindex H v k ++@ignore ++@mindex @null ++@end ignore ++@tindex rtail ++@ignore ++@mindex @null ++@end ignore ++@tindex rcons ++Each of these three functions also accepts the Hyperbolic flag [@code{rhead}, ++@code{rtail}, @code{rcons}] in which case @var{t} instead represents ++the @emph{last} single element of the vector, with @var{h} ++representing the remainder of the vector. Thus the vector ++@samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}. ++Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]}, ++@samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}. ++ ++@node Extracting Elements, Manipulating Vectors, Building Vectors, Matrix Functions ++@section Extracting Vector Elements ++ ++@noindent ++@kindex v r ++@pindex calc-mrow ++@tindex mrow ++The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of ++the matrix on the top of the stack, or one element of the plain vector on ++the top of the stack. The row or element is specified by the numeric ++prefix argument; the default is to prompt for the row or element number. ++The matrix or vector is replaced by the specified row or element in the ++form of a vector or scalar, respectively. ++ ++@cindex Permutations, applying ++With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of ++the element or row from the top of the stack, and the vector or matrix ++from the second-to-top position. If the index is itself a vector of ++integers, the result is a vector of the corresponding elements of the ++input vector, or a matrix of the corresponding rows of the input matrix. ++This command can be used to obtain any permutation of a vector. ++ ++With @kbd{C-u}, if the index is an interval form with integer components, ++it is interpreted as a range of indices and the corresponding subvector or ++submatrix is returned. ++ ++@cindex Subscript notation ++@kindex a _ ++@pindex calc-subscript ++@tindex subscr ++@tindex _ ++Subscript notation in algebraic formulas (@samp{a_b}) stands for the ++Calc function @code{subscr}, which is synonymous with @code{mrow}. ++Thus, @samp{[x, y, z]_k} produces @expr{x}, @expr{y}, or @expr{z} if ++@expr{k} is one, two, or three, respectively. A double subscript ++(@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will ++access the element at row @expr{i}, column @expr{j} of a matrix. ++The @kbd{a _} (@code{calc-subscript}) command creates a subscript ++formula @samp{a_b} out of two stack entries. (It is on the @kbd{a} ++``algebra'' prefix because subscripted variables are often used ++purely as an algebraic notation.) ++ ++@tindex mrrow ++Given a negative prefix argument, @kbd{v r} instead deletes one row or ++element from the matrix or vector on the top of the stack. Thus ++@kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r} ++replaces the matrix with the same matrix with its second row removed. ++In algebraic form this function is called @code{mrrow}. ++ ++@tindex getdiag ++Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements ++of a square matrix in the form of a vector. In algebraic form this ++function is called @code{getdiag}. ++ ++@kindex v c ++@pindex calc-mcol ++@tindex mcol ++@tindex mrcol ++The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is ++the analogous operation on columns of a matrix. Given a plain vector ++it extracts (or removes) one element, just like @kbd{v r}. If the ++index in @kbd{C-u v c} is an interval or vector and the argument is a ++matrix, the result is a submatrix with only the specified columns ++retained (and possibly permuted in the case of a vector index). ++ ++To extract a matrix element at a given row and column, use @kbd{v r} to ++extract the row as a vector, then @kbd{v c} to extract the column element ++from that vector. In algebraic formulas, it is often more convenient to ++use subscript notation: @samp{m_i_j} gives row @expr{i}, column @expr{j} ++of matrix @expr{m}. ++ ++@kindex v s ++@pindex calc-subvector ++@tindex subvec ++The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts ++a subvector of a vector. The arguments are the vector, the starting ++index, and the ending index, with the ending index in the top-of-stack ++position. The starting index indicates the first element of the vector ++to take. The ending index indicates the first element @emph{past} the ++range to be taken. Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces ++the subvector @samp{[b, c]}. You could get the same result using ++@samp{mrow([a, b, c, d, e], @w{[2 .. 4)})}. ++ ++If either the start or the end index is zero or negative, it is ++interpreted as relative to the end of the vector. Thus ++@samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}. In ++the algebraic form, the end index can be omitted in which case it ++is taken as zero, i.e., elements from the starting element to the ++end of the vector are used. The infinity symbol, @code{inf}, also ++has this effect when used as the ending index. ++ ++@kindex I v s ++@tindex rsubvec ++With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector ++from a vector. The arguments are interpreted the same as for the ++normal @kbd{v s} command. Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)} ++produces @samp{[a, d, e]}. It is always true that @code{subvec} and ++@code{rsubvec} return complementary parts of the input vector. ++ ++@xref{Selecting Subformulas}, for an alternative way to operate on ++vectors one element at a time. ++ ++@node Manipulating Vectors, Vector and Matrix Arithmetic, Extracting Elements, Matrix Functions ++@section Manipulating Vectors ++ ++@noindent ++@kindex v l ++@pindex calc-vlength ++@tindex vlen ++The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the ++length of a vector. The length of a non-vector is considered to be zero. ++Note that matrices are just vectors of vectors for the purposes of this ++command. ++ ++@kindex H v l ++@tindex mdims ++With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector ++of the dimensions of a vector, matrix, or higher-order object. For ++example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since ++its argument is a ++@texline @math{2\times3} ++@infoline 2x3 ++matrix. ++ ++@kindex v f ++@pindex calc-vector-find ++@tindex find ++The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches ++along a vector for the first element equal to a given target. The target ++is on the top of the stack; the vector is in the second-to-top position. ++If a match is found, the result is the index of the matching element. ++Otherwise, the result is zero. The numeric prefix argument, if given, ++allows you to select any starting index for the search. ++ ++@kindex v a ++@pindex calc-arrange-vector ++@tindex arrange ++@cindex Arranging a matrix ++@cindex Reshaping a matrix ++@cindex Flattening a matrix ++The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command ++rearranges a vector to have a certain number of columns and rows. The ++numeric prefix argument specifies the number of columns; if you do not ++provide an argument, you will be prompted for the number of columns. ++The vector or matrix on the top of the stack is @dfn{flattened} into a ++plain vector. If the number of columns is nonzero, this vector is ++then formed into a matrix by taking successive groups of @var{n} elements. ++If the number of columns does not evenly divide the number of elements ++in the vector, the last row will be short and the result will not be ++suitable for use as a matrix. For example, with the matrix ++@samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces ++@samp{[[1, 2, 3, 4]]} (a ++@texline @math{1\times4} ++@infoline 1x4 ++matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a ++@texline @math{4\times1} ++@infoline 4x1 ++matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original ++@texline @math{2\times2} ++@infoline 2x2 ++matrix), @w{@kbd{v a 3}} produces @samp{[[1, 2, 3], [4]]} (not a ++matrix), and @kbd{v a 0} produces the flattened list ++@samp{[1, 2, @w{3, 4}]}. ++ ++@cindex Sorting data ++@kindex V S ++@kindex I V S ++@pindex calc-sort ++@tindex sort ++@tindex rsort ++The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of ++a vector into increasing order. Real numbers, real infinities, and ++constant interval forms come first in this ordering; next come other ++kinds of numbers, then variables (in alphabetical order), then finally ++come formulas and other kinds of objects; these are sorted according ++to a kind of lexicographic ordering with the useful property that ++one vector is less or greater than another if the first corresponding ++unequal elements are less or greater, respectively. Since quoted strings ++are stored by Calc internally as vectors of ASCII character codes ++(@pxref{Strings}), this means vectors of strings are also sorted into ++alphabetical order by this command. ++ ++The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order. ++ ++@cindex Permutation, inverse of ++@cindex Inverse of permutation ++@cindex Index tables ++@cindex Rank tables ++@kindex V G ++@kindex I V G ++@pindex calc-grade ++@tindex grade ++@tindex rgrade ++The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command ++produces an index table or permutation vector which, if applied to the ++input vector (as the index of @kbd{C-u v r}, say), would sort the vector. ++A permutation vector is just a vector of integers from 1 to @var{n}, where ++each integer occurs exactly once. One application of this is to sort a ++matrix of data rows using one column as the sort key; extract that column, ++grade it with @kbd{V G}, then use the result to reorder the original matrix ++with @kbd{C-u v r}. Another interesting property of the @code{V G} command ++is that, if the input is itself a permutation vector, the result will ++be the inverse of the permutation. The inverse of an index table is ++a rank table, whose @var{k}th element says where the @var{k}th original ++vector element will rest when the vector is sorted. To get a rank ++table, just use @kbd{V G V G}. ++ ++With the Inverse flag, @kbd{I V G} produces an index table that would ++sort the input into decreasing order. Note that @kbd{V S} and @kbd{V G} ++use a ``stable'' sorting algorithm, i.e., any two elements which are equal ++will not be moved out of their original order. Generally there is no way ++to tell with @kbd{V S}, since two elements which are equal look the same, ++but with @kbd{V G} this can be an important issue. In the matrix-of-rows ++example, suppose you have names and telephone numbers as two columns and ++you wish to sort by phone number primarily, and by name when the numbers ++are equal. You can sort the data matrix by names first, and then again ++by phone numbers. Because the sort is stable, any two rows with equal ++phone numbers will remain sorted by name even after the second sort. ++ ++@cindex Histograms ++@kindex V H ++@pindex calc-histogram ++@ignore ++@mindex histo@idots ++@end ignore ++@tindex histogram ++The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a ++histogram of a vector of numbers. Vector elements are assumed to be ++integers or real numbers in the range [0..@var{n}) for some ``number of ++bins'' @var{n}, which is the numeric prefix argument given to the ++command. The result is a vector of @var{n} counts of how many times ++each value appeared in the original vector. Non-integers in the input ++are rounded down to integers. Any vector elements outside the specified ++range are ignored. (You can tell if elements have been ignored by noting ++that the counts in the result vector don't add up to the length of the ++input vector.) ++ ++@kindex H V H ++With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack. ++The second-to-top vector is the list of numbers as before. The top ++vector is an equal-sized list of ``weights'' to attach to the elements ++of the data vector. For example, if the first data element is 4.2 and ++the first weight is 10, then 10 will be added to bin 4 of the result ++vector. Without the hyperbolic flag, every element has a weight of one. ++ ++@kindex v t ++@pindex calc-transpose ++@tindex trn ++The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes ++the transpose of the matrix at the top of the stack. If the argument ++is a plain vector, it is treated as a row vector and transposed into ++a one-column matrix. ++ ++@kindex v v ++@pindex calc-reverse-vector ++@tindex rev ++The @kbd{v v} (@code{calc-reverse-vector}) [@code{rev}] command reverses ++a vector end-for-end. Given a matrix, it reverses the order of the rows. ++(To reverse the columns instead, just use @kbd{v t v v v t}. The same ++principle can be used to apply other vector commands to the columns of ++a matrix.) ++ ++@kindex v m ++@pindex calc-mask-vector ++@tindex vmask ++The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses ++one vector as a mask to extract elements of another vector. The mask ++is in the second-to-top position; the target vector is on the top of ++the stack. These vectors must have the same length. The result is ++the same as the target vector, but with all elements which correspond ++to zeros in the mask vector deleted. Thus, for example, ++@samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}. ++@xref{Logical Operations}. ++ ++@kindex v e ++@pindex calc-expand-vector ++@tindex vexp ++The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command ++expands a vector according to another mask vector. The result is a ++vector the same length as the mask, but with nonzero elements replaced ++by successive elements from the target vector. The length of the target ++vector is normally the number of nonzero elements in the mask. If the ++target vector is longer, its last few elements are lost. If the target ++vector is shorter, the last few nonzero mask elements are left ++unreplaced in the result. Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])} ++produces @samp{[a, 0, b, 0, 7]}. ++ ++@kindex H v e ++With the Hyperbolic flag, @kbd{H v e} takes a filler value from the ++top of the stack; the mask and target vectors come from the third and ++second elements of the stack. This filler is used where the mask is ++zero: @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces ++@samp{[a, z, c, z, 7]}. If the filler value is itself a vector, ++then successive values are taken from it, so that the effect is to ++interleave two vectors according to the mask: ++@samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces ++@samp{[a, x, b, 7, y, 0]}. ++ ++Another variation on the masking idea is to combine @samp{[a, b, c, d, e]} ++with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}. ++You can accomplish this with @kbd{V M a &}, mapping the logical ``and'' ++operation across the two vectors. @xref{Logical Operations}. Note that ++the @code{? :} operation also discussed there allows other types of ++masking using vectors. ++ ++@node Vector and Matrix Arithmetic, Set Operations, Manipulating Vectors, Matrix Functions ++@section Vector and Matrix Arithmetic ++ ++@noindent ++Basic arithmetic operations like addition and multiplication are defined ++for vectors and matrices as well as for numbers. Division of matrices, in ++the sense of multiplying by the inverse, is supported. (Division by a ++matrix actually uses LU-decomposition for greater accuracy and speed.) ++@xref{Basic Arithmetic}. ++ ++The following functions are applied element-wise if their arguments are ++vectors or matrices: @code{change-sign}, @code{conj}, @code{arg}, ++@code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean}, ++@code{float}, @code{frac}. @xref{Function Index}. ++ ++@kindex V J ++@pindex calc-conj-transpose ++@tindex ctrn ++The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes ++the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}. ++ ++@ignore ++@mindex A ++@end ignore ++@kindex A (vectors) ++@pindex calc-abs (vectors) ++@ignore ++@mindex abs ++@end ignore ++@tindex abs (vectors) ++The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the ++Frobenius norm of a vector or matrix argument. This is the square ++root of the sum of the squares of the absolute values of the ++elements of the vector or matrix. If the vector is interpreted as ++a point in two- or three-dimensional space, this is the distance ++from that point to the origin. ++ ++@kindex v n ++@pindex calc-rnorm ++@tindex rnorm ++The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes the ++infinity-norm of a vector, or the row norm of a matrix. For a plain ++vector, this is the maximum of the absolute values of the elements. For ++a matrix, this is the maximum of the row-absolute-value-sums, i.e., of ++the sums of the absolute values of the elements along the various rows. ++ ++@kindex V N ++@pindex calc-cnorm ++@tindex cnorm ++The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes ++the one-norm of a vector, or column norm of a matrix. For a plain ++vector, this is the sum of the absolute values of the elements. ++For a matrix, this is the maximum of the column-absolute-value-sums. ++General @expr{k}-norms for @expr{k} other than one or infinity are ++not provided. However, the 2-norm (or Frobenius norm) is provided for ++vectors by the @kbd{A} (@code{calc-abs}) command. ++ ++@kindex V C ++@pindex calc-cross ++@tindex cross ++The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the ++right-handed cross product of two vectors, each of which must have ++exactly three elements. ++ ++@ignore ++@mindex & ++@end ignore ++@kindex & (matrices) ++@pindex calc-inv (matrices) ++@ignore ++@mindex inv ++@end ignore ++@tindex inv (matrices) ++The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the ++inverse of a square matrix. If the matrix is singular, the inverse ++operation is left in symbolic form. Matrix inverses are recorded so ++that once an inverse (or determinant) of a particular matrix has been ++computed, the inverse and determinant of the matrix can be recomputed ++quickly in the future. ++ ++If the argument to @kbd{&} is a plain number @expr{x}, this ++command simply computes @expr{1/x}. This is okay, because the ++@samp{/} operator also does a matrix inversion when dividing one ++by a matrix. ++ ++@kindex V D ++@pindex calc-mdet ++@tindex det ++The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the ++determinant of a square matrix. ++ ++@kindex V L ++@pindex calc-mlud ++@tindex lud ++The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the ++LU decomposition of a matrix. The result is a list of three matrices ++which, when multiplied together left-to-right, form the original matrix. ++The first is a permutation matrix that arises from pivoting in the ++algorithm, the second is lower-triangular with ones on the diagonal, ++and the third is upper-triangular. ++ ++@kindex V T ++@pindex calc-mtrace ++@tindex tr ++The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the ++trace of a square matrix. This is defined as the sum of the diagonal ++elements of the matrix. ++ ++@kindex V K ++@pindex calc-kron ++@tindex kron ++The @kbd{V K} (@code{calc-kron}) [@code{kron}] command computes ++the Kronecker product of two matrices. ++ ++@node Set Operations, Statistical Operations, Vector and Matrix Arithmetic, Matrix Functions ++@section Set Operations using Vectors ++ ++@noindent ++@cindex Sets, as vectors ++Calc includes several commands which interpret vectors as @dfn{sets} of ++objects. A set is a collection of objects; any given object can appear ++only once in the set. Calc stores sets as vectors of objects in ++sorted order. Objects in a Calc set can be any of the usual things, ++such as numbers, variables, or formulas. Two set elements are considered ++equal if they are identical, except that numerically equal numbers like ++the integer 4 and the float 4.0 are considered equal even though they ++are not ``identical.'' Variables are treated like plain symbols without ++attached values by the set operations; subtracting the set @samp{[b]} ++from @samp{[a, b]} always yields the set @samp{[a]} even though if ++the variables @samp{a} and @samp{b} both equaled 17, you might ++expect the answer @samp{[]}. ++ ++If a set contains interval forms, then it is assumed to be a set of ++real numbers. In this case, all set operations require the elements ++of the set to be only things that are allowed in intervals: Real ++numbers, plus and minus infinity, HMS forms, and date forms. If ++there are variables or other non-real objects present in a real set, ++all set operations on it will be left in unevaluated form. ++ ++If the input to a set operation is a plain number or interval form ++@var{a}, it is treated like the one-element vector @samp{[@var{a}]}. ++The result is always a vector, except that if the set consists of a ++single interval, the interval itself is returned instead. ++ ++@xref{Logical Operations}, for the @code{in} function which tests if ++a certain value is a member of a given set. To test if the set @expr{A} ++is a subset of the set @expr{B}, use @samp{vdiff(A, B) = []}. ++ ++@kindex V + ++@pindex calc-remove-duplicates ++@tindex rdup ++The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command ++converts an arbitrary vector into set notation. It works by sorting ++the vector as if by @kbd{V S}, then removing duplicates. (For example, ++@kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then ++reduced to @samp{[4, 5, a]}). Overlapping intervals are merged as ++necessary. You rarely need to use @kbd{V +} explicitly, since all the ++other set-based commands apply @kbd{V +} to their inputs before using ++them. ++ ++@kindex V V ++@pindex calc-set-union ++@tindex vunion ++The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes ++the union of two sets. An object is in the union of two sets if and ++only if it is in either (or both) of the input sets. (You could ++accomplish the same thing by concatenating the sets with @kbd{|}, ++then using @kbd{V +}.) ++ ++@kindex V ^ ++@pindex calc-set-intersect ++@tindex vint ++The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes ++the intersection of two sets. An object is in the intersection if ++and only if it is in both of the input sets. Thus if the input ++sets are disjoint, i.e., if they share no common elements, the result ++will be the empty vector @samp{[]}. Note that the characters @kbd{V} ++and @kbd{^} were chosen to be close to the conventional mathematical ++notation for set ++@texline union@tie{}(@math{A \cup B}) ++@infoline union ++and ++@texline intersection@tie{}(@math{A \cap B}). ++@infoline intersection. ++ ++@kindex V - ++@pindex calc-set-difference ++@tindex vdiff ++The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes ++the difference between two sets. An object is in the difference ++@expr{A - B} if and only if it is in @expr{A} but not in @expr{B}. ++Thus subtracting @samp{[y,z]} from a set will remove the elements ++@samp{y} and @samp{z} if they are present. You can also think of this ++as a general @dfn{set complement} operator; if @expr{A} is the set of ++all possible values, then @expr{A - B} is the ``complement'' of @expr{B}. ++Obviously this is only practical if the set of all possible values in ++your problem is small enough to list in a Calc vector (or simple ++enough to express in a few intervals). ++ ++@kindex V X ++@pindex calc-set-xor ++@tindex vxor ++The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes ++the ``exclusive-or,'' or ``symmetric difference'' of two sets. ++An object is in the symmetric difference of two sets if and only ++if it is in one, but @emph{not} both, of the sets. Objects that ++occur in both sets ``cancel out.'' ++ ++@kindex V ~ ++@pindex calc-set-complement ++@tindex vcompl ++The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command ++computes the complement of a set with respect to the real numbers. ++Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}. ++For example, @samp{vcompl([2, (3 .. 4]])} evaluates to ++@samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}. ++ ++@kindex V F ++@pindex calc-set-floor ++@tindex vfloor ++The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command ++reinterprets a set as a set of integers. Any non-integer values, ++and intervals that do not enclose any integers, are removed. Open ++intervals are converted to equivalent closed intervals. Successive ++integers are converted into intervals of integers. For example, the ++complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted ++the complement with respect to the set of integers you could type ++@kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}. ++ ++@kindex V E ++@pindex calc-set-enumerate ++@tindex venum ++The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command ++converts a set of integers into an explicit vector. Intervals in ++the set are expanded out to lists of all integers encompassed by ++the intervals. This only works for finite sets (i.e., sets which ++do not involve @samp{-inf} or @samp{inf}). ++ ++@kindex V : ++@pindex calc-set-span ++@tindex vspan ++The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any ++set of reals into an interval form that encompasses all its elements. ++The lower limit will be the smallest element in the set; the upper ++limit will be the largest element. For an empty set, @samp{vspan([])} ++returns the empty interval @w{@samp{[0 .. 0)}}. ++ ++@kindex V # ++@pindex calc-set-cardinality ++@tindex vcard ++The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts ++the number of integers in a set. The result is the length of the vector ++that would be produced by @kbd{V E}, although the computation is much ++more efficient than actually producing that vector. ++ ++@cindex Sets, as binary numbers ++Another representation for sets that may be more appropriate in some ++cases is binary numbers. If you are dealing with sets of integers ++in the range 0 to 49, you can use a 50-bit binary number where a ++particular bit is 1 if the corresponding element is in the set. ++@xref{Binary Functions}, for a list of commands that operate on ++binary numbers. Note that many of the above set operations have ++direct equivalents in binary arithmetic: @kbd{b o} (@code{calc-or}), ++@kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}), ++@kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}), ++respectively. You can use whatever representation for sets is most ++convenient to you. ++ ++@kindex b p ++@kindex b u ++@pindex calc-pack-bits ++@pindex calc-unpack-bits ++@tindex vpack ++@tindex vunpack ++The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command ++converts an integer that represents a set in binary into a set ++in vector/interval notation. For example, @samp{vunpack(67)} ++returns @samp{[[0 .. 1], 6]}. If the input is negative, the set ++it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}. ++Use @kbd{V E} afterwards to expand intervals to individual ++values if you wish. Note that this command uses the @kbd{b} ++(binary) prefix key. ++ ++The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command ++converts the other way, from a vector or interval representing ++a set of nonnegative integers into a binary integer describing ++the same set. The set may include positive infinity, but must ++not include any negative numbers. The input is interpreted as a ++set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware ++that a simple input like @samp{[100]} can result in a huge integer ++representation ++@texline (@math{2^{100}}, a 31-digit integer, in this case). ++@infoline (@expr{2^100}, a 31-digit integer, in this case). ++ ++@node Statistical Operations, Reducing and Mapping, Set Operations, Matrix Functions ++@section Statistical Operations on Vectors ++ ++@noindent ++@cindex Statistical functions ++The commands in this section take vectors as arguments and compute ++various statistical measures on the data stored in the vectors. The ++references used in the definitions of these functions are Bevington's ++@emph{Data Reduction and Error Analysis for the Physical Sciences}, ++and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and ++Vetterling. ++ ++The statistical commands use the @kbd{u} prefix key followed by ++a shifted letter or other character. ++ ++@xref{Manipulating Vectors}, for a description of @kbd{V H} ++(@code{calc-histogram}). ++ ++@xref{Curve Fitting}, for the @kbd{a F} command for doing ++least-squares fits to statistical data. ++ ++@xref{Probability Distribution Functions}, for several common ++probability distribution functions. ++ ++@menu ++* Single-Variable Statistics:: ++* Paired-Sample Statistics:: ++@end menu ++ ++@node Single-Variable Statistics, Paired-Sample Statistics, Statistical Operations, Statistical Operations ++@subsection Single-Variable Statistics ++ ++@noindent ++These functions do various statistical computations on single ++vectors. Given a numeric prefix argument, they actually pop ++@var{n} objects from the stack and combine them into a data ++vector. Each object may be either a number or a vector; if a ++vector, any sub-vectors inside it are ``flattened'' as if by ++@kbd{v a 0}; @pxref{Manipulating Vectors}. By default one object ++is popped, which (in order to be useful) is usually a vector. ++ ++If an argument is a variable name, and the value stored in that ++variable is a vector, then the stored vector is used. This method ++has the advantage that if your data vector is large, you can avoid ++the slow process of manipulating it directly on the stack. ++ ++These functions are left in symbolic form if any of their arguments ++are not numbers or vectors, e.g., if an argument is a formula, or ++a non-vector variable. However, formulas embedded within vector ++arguments are accepted; the result is a symbolic representation ++of the computation, based on the assumption that the formula does ++not itself represent a vector. All varieties of numbers such as ++error forms and interval forms are acceptable. ++ ++Some of the functions in this section also accept a single error form ++or interval as an argument. They then describe a property of the ++normal or uniform (respectively) statistical distribution described ++by the argument. The arguments are interpreted in the same way as ++the @var{M} argument of the random number function @kbd{k r}. In ++particular, an interval with integer limits is considered an integer ++distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}. ++An interval with at least one floating-point limit is a continuous ++distribution: @samp{[2.0 .. 6.0)} is @emph{not} the same as ++@samp{[2.0 .. 5.0]}! ++ ++@kindex u # ++@pindex calc-vector-count ++@tindex vcount ++The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command ++computes the number of data values represented by the inputs. ++For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7. ++If the argument is a single vector with no sub-vectors, this ++simply computes the length of the vector. ++ ++@kindex u + ++@kindex u * ++@pindex calc-vector-sum ++@pindex calc-vector-prod ++@tindex vsum ++@tindex vprod ++@cindex Summations (statistical) ++The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command ++computes the sum of the data values. The @kbd{u *} ++(@code{calc-vector-prod}) [@code{vprod}] command computes the ++product of the data values. If the input is a single flat vector, ++these are the same as @kbd{V R +} and @kbd{V R *} ++(@pxref{Reducing and Mapping}). ++ ++@kindex u X ++@kindex u N ++@pindex calc-vector-max ++@pindex calc-vector-min ++@tindex vmax ++@tindex vmin ++The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command ++computes the maximum of the data values, and the @kbd{u N} ++(@code{calc-vector-min}) [@code{vmin}] command computes the minimum. ++If the argument is an interval, this finds the minimum or maximum ++value in the interval. (Note that @samp{vmax([2..6)) = 5} as ++described above.) If the argument is an error form, this returns ++plus or minus infinity. ++ ++@kindex u M ++@pindex calc-vector-mean ++@tindex vmean ++@cindex Mean of data values ++The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command ++computes the average (arithmetic mean) of the data values. ++If the inputs are error forms ++@texline @math{x \pm \sigma}, ++@infoline @samp{x +/- s}, ++this is the weighted mean of the @expr{x} values with weights ++@texline @math{1 /\sigma^2}. ++@infoline @expr{1 / s^2}. ++@tex ++\turnoffactive ++$$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over ++ \displaystyle \sum { 1 \over \sigma_i^2 } } $$ ++@end tex ++If the inputs are not error forms, this is simply the sum of the ++values divided by the count of the values. ++ ++Note that a plain number can be considered an error form with ++error ++@texline @math{\sigma = 0}. ++@infoline @expr{s = 0}. ++If the input to @kbd{u M} is a mixture of ++plain numbers and error forms, the result is the mean of the ++plain numbers, ignoring all values with non-zero errors. (By the ++above definitions it's clear that a plain number effectively ++has an infinite weight, next to which an error form with a finite ++weight is completely negligible.) ++ ++This function also works for distributions (error forms or ++intervals). The mean of an error form `@var{a} @tfn{+/-} @var{b}' is simply ++@expr{a}. The mean of an interval is the mean of the minimum ++and maximum values of the interval. ++ ++@kindex I u M ++@pindex calc-vector-mean-error ++@tindex vmeane ++The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}] ++command computes the mean of the data points expressed as an ++error form. This includes the estimated error associated with ++the mean. If the inputs are error forms, the error is the square ++root of the reciprocal of the sum of the reciprocals of the squares ++of the input errors. (I.e., the variance is the reciprocal of the ++sum of the reciprocals of the variances.) ++@tex ++\turnoffactive ++$$ \sigma_\mu^2 = {1 \over \displaystyle \sum {1 \over \sigma_i^2}} $$ ++@end tex ++If the inputs are plain ++numbers, the error is equal to the standard deviation of the values ++divided by the square root of the number of values. (This works ++out to be equivalent to calculating the standard deviation and ++then assuming each value's error is equal to this standard ++deviation.) ++@tex ++\turnoffactive ++$$ \sigma_\mu^2 = {\sigma^2 \over N} $$ ++@end tex ++ ++@kindex H u M ++@pindex calc-vector-median ++@tindex vmedian ++@cindex Median of data values ++The @kbd{H u M} (@code{calc-vector-median}) [@code{vmedian}] ++command computes the median of the data values. The values are ++first sorted into numerical order; the median is the middle ++value after sorting. (If the number of data values is even, ++the median is taken to be the average of the two middle values.) ++The median function is different from the other functions in ++this section in that the arguments must all be real numbers; ++variables are not accepted even when nested inside vectors. ++(Otherwise it is not possible to sort the data values.) If ++any of the input values are error forms, their error parts are ++ignored. ++ ++The median function also accepts distributions. For both normal ++(error form) and uniform (interval) distributions, the median is ++the same as the mean. ++ ++@kindex H I u M ++@pindex calc-vector-harmonic-mean ++@tindex vhmean ++@cindex Harmonic mean ++The @kbd{H I u M} (@code{calc-vector-harmonic-mean}) [@code{vhmean}] ++command computes the harmonic mean of the data values. This is ++defined as the reciprocal of the arithmetic mean of the reciprocals ++of the values. ++@tex ++\turnoffactive ++$$ { N \over \displaystyle \sum {1 \over x_i} } $$ ++@end tex ++ ++@kindex u G ++@pindex calc-vector-geometric-mean ++@tindex vgmean ++@cindex Geometric mean ++The @kbd{u G} (@code{calc-vector-geometric-mean}) [@code{vgmean}] ++command computes the geometric mean of the data values. This ++is the @var{n}th root of the product of the values. This is also ++equal to the @code{exp} of the arithmetic mean of the logarithms ++of the data values. ++@tex ++\turnoffactive ++$$ \exp \left ( \sum { \ln x_i } \right ) = ++ \left ( \prod { x_i } \right)^{1 / N} $$ ++@end tex ++ ++@kindex H u G ++@tindex agmean ++The @kbd{H u G} [@code{agmean}] command computes the ``arithmetic-geometric ++mean'' of two numbers taken from the stack. This is computed by ++replacing the two numbers with their arithmetic mean and geometric ++mean, then repeating until the two values converge. ++@tex ++\turnoffactive ++$$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$ ++@end tex ++ ++@cindex Root-mean-square ++Another commonly used mean, the RMS (root-mean-square), can be computed ++for a vector of numbers simply by using the @kbd{A} command. ++ ++@kindex u S ++@pindex calc-vector-sdev ++@tindex vsdev ++@cindex Standard deviation ++@cindex Sample statistics ++The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command ++computes the standard ++@texline deviation@tie{}@math{\sigma} ++@infoline deviation ++of the data values. If the values are error forms, the errors are used ++as weights just as for @kbd{u M}. This is the @emph{sample} standard ++deviation, whose value is the square root of the sum of the squares of ++the differences between the values and the mean of the @expr{N} values, ++divided by @expr{N-1}. ++@tex ++\turnoffactive ++$$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$ ++@end tex ++ ++This function also applies to distributions. The standard deviation ++of a single error form is simply the error part. The standard deviation ++of a continuous interval happens to equal the difference between the ++limits, divided by ++@texline @math{\sqrt{12}}. ++@infoline @expr{sqrt(12)}. ++The standard deviation of an integer interval is the same as the ++standard deviation of a vector of those integers. ++ ++@kindex I u S ++@pindex calc-vector-pop-sdev ++@tindex vpsdev ++@cindex Population statistics ++The @kbd{I u S} (@code{calc-vector-pop-sdev}) [@code{vpsdev}] ++command computes the @emph{population} standard deviation. ++It is defined by the same formula as above but dividing ++by @expr{N} instead of by @expr{N-1}. The population standard ++deviation is used when the input represents the entire set of ++data values in the distribution; the sample standard deviation ++is used when the input represents a sample of the set of all ++data values, so that the mean computed from the input is itself ++only an estimate of the true mean. ++@tex ++\turnoffactive ++$$ \sigma^2 = {1 \over N} \sum (x_i - \mu)^2 $$ ++@end tex ++ ++For error forms and continuous intervals, @code{vpsdev} works ++exactly like @code{vsdev}. For integer intervals, it computes the ++population standard deviation of the equivalent vector of integers. ++ ++@kindex H u S ++@kindex H I u S ++@pindex calc-vector-variance ++@pindex calc-vector-pop-variance ++@tindex vvar ++@tindex vpvar ++@cindex Variance of data values ++The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and ++@kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}] ++commands compute the variance of the data values. The variance ++is the ++@texline square@tie{}@math{\sigma^2} ++@infoline square ++of the standard deviation, i.e., the sum of the ++squares of the deviations of the data values from the mean. ++(This definition also applies when the argument is a distribution.) ++ ++@ignore ++@starindex ++@end ignore ++@tindex vflat ++The @code{vflat} algebraic function returns a vector of its ++arguments, interpreted in the same way as the other functions ++in this section. For example, @samp{vflat(1, [2, [3, 4]], 5)} ++returns @samp{[1, 2, 3, 4, 5]}. ++ ++@node Paired-Sample Statistics, , Single-Variable Statistics, Statistical Operations ++@subsection Paired-Sample Statistics ++ ++@noindent ++The functions in this section take two arguments, which must be ++vectors of equal size. The vectors are each flattened in the same ++way as by the single-variable statistical functions. Given a numeric ++prefix argument of 1, these functions instead take one object from ++the stack, which must be an ++@texline @math{N\times2} ++@infoline Nx2 ++matrix of data values. Once again, variable names can be used in place ++of actual vectors and matrices. ++ ++@kindex u C ++@pindex calc-vector-covariance ++@tindex vcov ++@cindex Covariance ++The @kbd{u C} (@code{calc-vector-covariance}) [@code{vcov}] command ++computes the sample covariance of two vectors. The covariance ++of vectors @var{x} and @var{y} is the sum of the products of the ++differences between the elements of @var{x} and the mean of @var{x} ++times the differences between the corresponding elements of @var{y} ++and the mean of @var{y}, all divided by @expr{N-1}. Note that ++the variance of a vector is just the covariance of the vector ++with itself. Once again, if the inputs are error forms the ++errors are used as weight factors. If both @var{x} and @var{y} ++are composed of error forms, the error for a given data point ++is taken as the square root of the sum of the squares of the two ++input errors. ++@tex ++\turnoffactive ++$$ \sigma_{x\!y}^2 = {1 \over N-1} \sum (x_i - \mu_x) (y_i - \mu_y) $$ ++$$ \sigma_{x\!y}^2 = ++ {\displaystyle {1 \over N-1} ++ \sum {(x_i - \mu_x) (y_i - \mu_y) \over \sigma_i^2} ++ \over \displaystyle {1 \over N} \sum {1 \over \sigma_i^2}} ++$$ ++@end tex ++ ++@kindex I u C ++@pindex calc-vector-pop-covariance ++@tindex vpcov ++The @kbd{I u C} (@code{calc-vector-pop-covariance}) [@code{vpcov}] ++command computes the population covariance, which is the same as the ++sample covariance computed by @kbd{u C} except dividing by @expr{N} ++instead of @expr{N-1}. ++ ++@kindex H u C ++@pindex calc-vector-correlation ++@tindex vcorr ++@cindex Correlation coefficient ++@cindex Linear correlation ++The @kbd{H u C} (@code{calc-vector-correlation}) [@code{vcorr}] ++command computes the linear correlation coefficient of two vectors. ++This is defined by the covariance of the vectors divided by the ++product of their standard deviations. (There is no difference ++between sample or population statistics here.) ++@tex ++\turnoffactive ++$$ r_{x\!y} = { \sigma_{x\!y}^2 \over \sigma_x^2 \sigma_y^2 } $$ ++@end tex ++ ++@node Reducing and Mapping, Vector and Matrix Formats, Statistical Operations, Matrix Functions ++@section Reducing and Mapping Vectors ++ ++@noindent ++The commands in this section allow for more general operations on the ++elements of vectors. ++ ++@kindex V A ++@pindex calc-apply ++@tindex apply ++The simplest of these operations is @kbd{V A} (@code{calc-apply}) ++[@code{apply}], which applies a given operator to the elements of a vector. ++For example, applying the hypothetical function @code{f} to the vector ++@w{@samp{[1, 2, 3]}} would produce the function call @samp{f(1, 2, 3)}. ++Applying the @code{+} function to the vector @samp{[a, b]} gives ++@samp{a + b}. Applying @code{+} to the vector @samp{[a, b, c]} is an ++error, since the @code{+} function expects exactly two arguments. ++ ++While @kbd{V A} is useful in some cases, you will usually find that either ++@kbd{V R} or @kbd{V M}, described below, is closer to what you want. ++ ++@menu ++* Specifying Operators:: ++* Mapping:: ++* Reducing:: ++* Nesting and Fixed Points:: ++* Generalized Products:: ++@end menu ++ ++@node Specifying Operators, Mapping, Reducing and Mapping, Reducing and Mapping ++@subsection Specifying Operators ++ ++@noindent ++Commands in this section (like @kbd{V A}) prompt you to press the key ++corresponding to the desired operator. Press @kbd{?} for a partial ++list of the available operators. Generally, an operator is any key or ++sequence of keys that would normally take one or more arguments from ++the stack and replace them with a result. For example, @kbd{V A H C} ++uses the hyperbolic cosine operator, @code{cosh}. (Since @code{cosh} ++expects one argument, @kbd{V A H C} requires a vector with a single ++element as its argument.) ++ ++You can press @kbd{x} at the operator prompt to select any algebraic ++function by name to use as the operator. This includes functions you ++have defined yourself using the @kbd{Z F} command. (@xref{Algebraic ++Definitions}.) If you give a name for which no function has been ++defined, the result is left in symbolic form, as in @samp{f(1, 2, 3)}. ++Calc will prompt for the number of arguments the function takes if it ++can't figure it out on its own (say, because you named a function that ++is currently undefined). It is also possible to type a digit key before ++the function name to specify the number of arguments, e.g., ++@kbd{V M 3 x f @key{RET}} calls @code{f} with three arguments even if it ++looks like it ought to have only two. This technique may be necessary ++if the function allows a variable number of arguments. For example, ++the @kbd{v e} [@code{vexp}] function accepts two or three arguments; ++if you want to map with the three-argument version, you will have to ++type @kbd{V M 3 v e}. ++ ++It is also possible to apply any formula to a vector by treating that ++formula as a function. When prompted for the operator to use, press ++@kbd{'} (the apostrophe) and type your formula as an algebraic entry. ++You will then be prompted for the argument list, which defaults to a ++list of all variables that appear in the formula, sorted into alphabetic ++order. For example, suppose you enter the formula @w{@samp{x + 2y^x}}. ++The default argument list would be @samp{(x y)}, which means that if ++this function is applied to the arguments @samp{[3, 10]} the result will ++be @samp{3 + 2*10^3}. (If you plan to use a certain formula in this ++way often, you might consider defining it as a function with @kbd{Z F}.) ++ ++Another way to specify the arguments to the formula you enter is with ++@kbd{$}, @kbd{$$}, and so on. For example, @kbd{V A ' $$ + 2$^$$} ++has the same effect as the previous example. The argument list is ++automatically taken to be @samp{($$ $)}. (The order of the arguments ++may seem backwards, but it is analogous to the way normal algebraic ++entry interacts with the stack.) ++ ++If you press @kbd{$} at the operator prompt, the effect is similar to ++the apostrophe except that the relevant formula is taken from top-of-stack ++instead. The actual vector arguments of the @kbd{V A $} or related command ++then start at the second-to-top stack position. You will still be ++prompted for an argument list. ++ ++@cindex Nameless functions ++@cindex Generic functions ++A function can be written without a name using the notation @samp{<#1 - #2>}, ++which means ``a function of two arguments that computes the first ++argument minus the second argument.'' The symbols @samp{#1} and @samp{#2} ++are placeholders for the arguments. You can use any names for these ++placeholders if you wish, by including an argument list followed by a ++colon: @samp{}. When you type @kbd{V A ' $$ + 2$^$$ @key{RET}}, ++Calc builds the nameless function @samp{<#1 + 2 #2^#1>} as the function ++to map across the vectors. When you type @kbd{V A ' x + 2y^x @key{RET} @key{RET}}, ++Calc builds the nameless function @w{@samp{}}. In both ++cases, Calc also writes the nameless function to the Trail so that you ++can get it back later if you wish. ++ ++If there is only one argument, you can write @samp{#} in place of @samp{#1}. ++(Note that @samp{< >} notation is also used for date forms. Calc tells ++that @samp{<@var{stuff}>} is a nameless function by the presence of ++@samp{#} signs inside @var{stuff}, or by the fact that @var{stuff} ++begins with a list of variables followed by a colon.) ++ ++You can type a nameless function directly to @kbd{V A '}, or put one on ++the stack and use it with @w{@kbd{V A $}}. Calc will not prompt for an ++argument list in this case, since the nameless function specifies the ++argument list as well as the function itself. In @kbd{V A '}, you can ++omit the @samp{< >} marks if you use @samp{#} notation for the arguments, ++so that @kbd{V A ' #1+#2 @key{RET}} is the same as @kbd{V A ' <#1+#2> @key{RET}}, ++which in turn is the same as @kbd{V A ' $$+$ @key{RET}}. ++ ++@cindex Lambda expressions ++@ignore ++@starindex ++@end ignore ++@tindex lambda ++The internal format for @samp{} is @samp{lambda(x, y, x + y)}. ++(The word @code{lambda} derives from Lisp notation and the theory of ++functions.) The internal format for @samp{<#1 + #2>} is @samp{lambda(ArgA, ++ArgB, ArgA + ArgB)}. Note that there is no actual Calc function called ++@code{lambda}; the whole point is that the @code{lambda} expression is ++used in its symbolic form, not evaluated for an answer until it is applied ++to specific arguments by a command like @kbd{V A} or @kbd{V M}. ++ ++(Actually, @code{lambda} does have one special property: Its arguments ++are never evaluated; for example, putting @samp{<(2/3) #>} on the stack ++will not simplify the @samp{2/3} until the nameless function is actually ++called.) ++ ++@tindex add ++@tindex sub ++@ignore ++@mindex @idots ++@end ignore ++@tindex mul ++@ignore ++@mindex @null ++@end ignore ++@tindex div ++@ignore ++@mindex @null ++@end ignore ++@tindex pow ++@ignore ++@mindex @null ++@end ignore ++@tindex neg ++@ignore ++@mindex @null ++@end ignore ++@tindex mod ++@ignore ++@mindex @null ++@end ignore ++@tindex vconcat ++As usual, commands like @kbd{V A} have algebraic function name equivalents. ++For example, @kbd{V A k g} with an argument of @samp{v} is equivalent to ++@samp{apply(gcd, v)}. The first argument specifies the operator name, ++and is either a variable whose name is the same as the function name, ++or a nameless function like @samp{<#^3+1>}. Operators that are normally ++written as algebraic symbols have the names @code{add}, @code{sub}, ++@code{mul}, @code{div}, @code{pow}, @code{neg}, @code{mod}, and ++@code{vconcat}. ++ ++@ignore ++@starindex ++@end ignore ++@tindex call ++The @code{call} function builds a function call out of several arguments: ++@samp{call(gcd, x, y)} is the same as @samp{apply(gcd, [x, y])}, which ++in turn is the same as @samp{gcd(x, y)}. The first argument of @code{call}, ++like the other functions described here, may be either a variable naming a ++function, or a nameless function (@samp{call(<#1+2#2>, x, y)} is the same ++as @samp{x + 2y}). ++ ++(Experts will notice that it's not quite proper to use a variable to name ++a function, since the name @code{gcd} corresponds to the Lisp variable ++@code{var-gcd} but to the Lisp function @code{calcFunc-gcd}. Calc ++automatically makes this translation, so you don't have to worry ++about it.) ++ ++@node Mapping, Reducing, Specifying Operators, Reducing and Mapping ++@subsection Mapping ++ ++@noindent ++@kindex V M ++@pindex calc-map ++@tindex map ++The @kbd{V M} (@code{calc-map}) [@code{map}] command applies a given ++operator elementwise to one or more vectors. For example, mapping ++@code{A} [@code{abs}] produces a vector of the absolute values of the ++elements in the input vector. Mapping @code{+} pops two vectors from ++the stack, which must be of equal length, and produces a vector of the ++pairwise sums of the elements. If either argument is a non-vector, it ++is duplicated for each element of the other vector. For example, ++@kbd{[1,2,3] 2 V M ^} squares the elements of the specified vector. ++With the 2 listed first, it would have computed a vector of powers of ++two. Mapping a user-defined function pops as many arguments from the ++stack as the function requires. If you give an undefined name, you will ++be prompted for the number of arguments to use. ++ ++If any argument to @kbd{V M} is a matrix, the operator is normally mapped ++across all elements of the matrix. For example, given the matrix ++@expr{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to ++produce another ++@texline @math{3\times2} ++@infoline 3x2 ++matrix, @expr{[[1, 2, 3], [4, 5, 6]]}. ++ ++@tindex mapr ++The command @kbd{V M _} [@code{mapr}] (i.e., type an underscore at the ++operator prompt) maps by rows instead. For example, @kbd{V M _ A} views ++the above matrix as a vector of two 3-element row vectors. It produces ++a new vector which contains the absolute values of those row vectors, ++namely @expr{[3.74, 8.77]}. (Recall, the absolute value of a vector is ++defined as the square root of the sum of the squares of the elements.) ++Some operators accept vectors and return new vectors; for example, ++@kbd{v v} reverses a vector, so @kbd{V M _ v v} would reverse each row ++of the matrix to get a new matrix, @expr{[[3, -2, 1], [-6, 5, -4]]}. ++ ++Sometimes a vector of vectors (representing, say, strings, sets, or lists) ++happens to look like a matrix. If so, remember to use @kbd{V M _} if you ++want to map a function across the whole strings or sets rather than across ++their individual elements. ++ ++@tindex mapc ++The command @kbd{V M :} [@code{mapc}] maps by columns. Basically, it ++transposes the input matrix, maps by rows, and then, if the result is a ++matrix, transposes again. For example, @kbd{V M : A} takes the absolute ++values of the three columns of the matrix, treating each as a 2-vector, ++and @kbd{V M : v v} reverses the columns to get the matrix ++@expr{[[-4, 5, -6], [1, -2, 3]]}. ++ ++(The symbols @kbd{_} and @kbd{:} were chosen because they had row-like ++and column-like appearances, and were not already taken by useful ++operators. Also, they appear shifted on most keyboards so they are easy ++to type after @kbd{V M}.) ++ ++The @kbd{_} and @kbd{:} modifiers have no effect on arguments that are ++not matrices (so if none of the arguments are matrices, they have no ++effect at all). If some of the arguments are matrices and others are ++plain numbers, the plain numbers are held constant for all rows of the ++matrix (so that @kbd{2 V M _ ^} squares every row of a matrix; squaring ++a vector takes a dot product of the vector with itself). ++ ++If some of the arguments are vectors with the same lengths as the ++rows (for @kbd{V M _}) or columns (for @kbd{V M :}) of the matrix ++arguments, those vectors are also held constant for every row or ++column. ++ ++Sometimes it is useful to specify another mapping command as the operator ++to use with @kbd{V M}. For example, @kbd{V M _ V A +} applies @kbd{V A +} ++to each row of the input matrix, which in turn adds the two values on that ++row. If you give another vector-operator command as the operator for ++@kbd{V M}, it automatically uses map-by-rows mode if you don't specify ++otherwise; thus @kbd{V M V A +} is equivalent to @kbd{V M _ V A +}. (If ++you really want to map-by-elements another mapping command, you can use ++a triple-nested mapping command: @kbd{V M V M V A +} means to map ++@kbd{V M V A +} over the rows of the matrix; in turn, @kbd{V A +} is ++mapped over the elements of each row.) ++ ++@tindex mapa ++@tindex mapd ++Previous versions of Calc had ``map across'' and ``map down'' modes ++that are now considered obsolete; the old ``map across'' is now simply ++@kbd{V M V A}, and ``map down'' is now @kbd{V M : V A}. The algebraic ++functions @code{mapa} and @code{mapd} are still supported, though. ++Note also that, while the old mapping modes were persistent (once you ++set the mode, it would apply to later mapping commands until you reset ++it), the new @kbd{:} and @kbd{_} modifiers apply only to the current ++mapping command. The default @kbd{V M} always means map-by-elements. ++ ++@xref{Algebraic Manipulation}, for the @kbd{a M} command, which is like ++@kbd{V M} but for equations and inequalities instead of vectors. ++@xref{Storing Variables}, for the @kbd{s m} command which modifies a ++variable's stored value using a @kbd{V M}-like operator. ++ ++@node Reducing, Nesting and Fixed Points, Mapping, Reducing and Mapping ++@subsection Reducing ++ ++@noindent ++@kindex V R ++@pindex calc-reduce ++@tindex reduce ++The @kbd{V R} (@code{calc-reduce}) [@code{reduce}] command applies a given ++binary operator across all the elements of a vector. A binary operator is ++a function such as @code{+} or @code{max} which takes two arguments. For ++example, reducing @code{+} over a vector computes the sum of the elements ++of the vector. Reducing @code{-} computes the first element minus each of ++the remaining elements. Reducing @code{max} computes the maximum element ++and so on. In general, reducing @code{f} over the vector @samp{[a, b, c, d]} ++produces @samp{f(f(f(a, b), c), d)}. ++ ++@kindex I V R ++@tindex rreduce ++The @kbd{I V R} [@code{rreduce}] command is similar to @kbd{V R} except ++that works from right to left through the vector. For example, plain ++@kbd{V R -} on the vector @samp{[a, b, c, d]} produces @samp{a - b - c - d} ++but @kbd{I V R -} on the same vector produces @samp{a - (b - (c - d))}, ++or @samp{a - b + c - d}. This ``alternating sum'' occurs frequently ++in power series expansions. ++ ++@kindex V U ++@tindex accum ++The @kbd{V U} (@code{calc-accumulate}) [@code{accum}] command does an ++accumulation operation. Here Calc does the corresponding reduction ++operation, but instead of producing only the final result, it produces ++a vector of all the intermediate results. Accumulating @code{+} over ++the vector @samp{[a, b, c, d]} produces the vector ++@samp{[a, a + b, a + b + c, a + b + c + d]}. ++ ++@kindex I V U ++@tindex raccum ++The @kbd{I V U} [@code{raccum}] command does a right-to-left accumulation. ++For example, @kbd{I V U -} on the vector @samp{[a, b, c, d]} produces the ++vector @samp{[a - b + c - d, b - c + d, c - d, d]}. ++ ++@tindex reducea ++@tindex rreducea ++@tindex reduced ++@tindex rreduced ++As for @kbd{V M}, @kbd{V R} normally reduces a matrix elementwise. For ++example, given the matrix @expr{[[a, b, c], [d, e, f]]}, @kbd{V R +} will ++compute @expr{a + b + c + d + e + f}. You can type @kbd{V R _} or ++@kbd{V R :} to modify this behavior. The @kbd{V R _} [@code{reducea}] ++command reduces ``across'' the matrix; it reduces each row of the matrix ++as a vector, then collects the results. Thus @kbd{V R _ +} of this ++matrix would produce @expr{[a + b + c, d + e + f]}. Similarly, @kbd{V R :} ++[@code{reduced}] reduces down; @kbd{V R : +} would produce @expr{[a + d, ++b + e, c + f]}. ++ ++@tindex reducer ++@tindex rreducer ++There is a third ``by rows'' mode for reduction that is occasionally ++useful; @kbd{V R =} [@code{reducer}] simply reduces the operator over ++the rows of the matrix themselves. Thus @kbd{V R = +} on the above ++matrix would get the same result as @kbd{V R : +}, since adding two ++row vectors is equivalent to adding their elements. But @kbd{V R = *} ++would multiply the two rows (to get a single number, their dot product), ++while @kbd{V R : *} would produce a vector of the products of the columns. ++ ++These three matrix reduction modes work with @kbd{V R} and @kbd{I V R}, ++but they are not currently supported with @kbd{V U} or @kbd{I V U}. ++ ++@tindex reducec ++@tindex rreducec ++The obsolete reduce-by-columns function, @code{reducec}, is still ++supported but there is no way to get it through the @kbd{V R} command. ++ ++The commands @kbd{C-x * :} and @kbd{C-x * _} are equivalent to typing ++@kbd{C-x * r} to grab a rectangle of data into Calc, and then typing ++@kbd{V R : +} or @kbd{V R _ +}, respectively, to sum the columns or ++rows of the matrix. @xref{Grabbing From Buffers}. ++ ++@node Nesting and Fixed Points, Generalized Products, Reducing, Reducing and Mapping ++@subsection Nesting and Fixed Points ++ ++@noindent ++@kindex H V R ++@tindex nest ++The @kbd{H V R} [@code{nest}] command applies a function to a given ++argument repeatedly. It takes two values, @samp{a} and @samp{n}, from ++the stack, where @samp{n} must be an integer. It then applies the ++function nested @samp{n} times; if the function is @samp{f} and @samp{n} ++is 3, the result is @samp{f(f(f(a)))}. The number @samp{n} may be ++negative if Calc knows an inverse for the function @samp{f}; for ++example, @samp{nest(sin, a, -2)} returns @samp{arcsin(arcsin(a))}. ++ ++@kindex H V U ++@tindex anest ++The @kbd{H V U} [@code{anest}] command is an accumulating version of ++@code{nest}: It returns a vector of @samp{n+1} values, e.g., ++@samp{[a, f(a), f(f(a)), f(f(f(a)))]}. If @samp{n} is negative and ++@samp{F} is the inverse of @samp{f}, then the result is of the ++form @samp{[a, F(a), F(F(a)), F(F(F(a)))]}. ++ ++@kindex H I V R ++@tindex fixp ++@cindex Fixed points ++The @kbd{H I V R} [@code{fixp}] command is like @kbd{H V R}, except ++that it takes only an @samp{a} value from the stack; the function is ++applied until it reaches a ``fixed point,'' i.e., until the result ++no longer changes. ++ ++@kindex H I V U ++@tindex afixp ++The @kbd{H I V U} [@code{afixp}] command is an accumulating @code{fixp}. ++The first element of the return vector will be the initial value @samp{a}; ++the last element will be the final result that would have been returned ++by @code{fixp}. ++ ++For example, 0.739085 is a fixed point of the cosine function (in radians): ++@samp{cos(0.739085) = 0.739085}. You can find this value by putting, say, ++1.0 on the stack and typing @kbd{H I V U C}. (We use the accumulating ++version so we can see the intermediate results: @samp{[1, 0.540302, 0.857553, ++0.65329, ...]}. With a precision of six, this command will take 36 steps ++to converge to 0.739085.) ++ ++Newton's method for finding roots is a classic example of iteration ++to a fixed point. To find the square root of five starting with an ++initial guess, Newton's method would look for a fixed point of the ++function @samp{(x + 5/x) / 2}. Putting a guess of 1 on the stack ++and typing @kbd{H I V R ' ($ + 5/$)/2 @key{RET}} quickly yields the result ++2.23607. This is equivalent to using the @kbd{a R} (@code{calc-find-root}) ++command to find a root of the equation @samp{x^2 = 5}. ++ ++These examples used numbers for @samp{a} values. Calc keeps applying ++the function until two successive results are equal to within the ++current precision. For complex numbers, both the real parts and the ++imaginary parts must be equal to within the current precision. If ++@samp{a} is a formula (say, a variable name), then the function is ++applied until two successive results are exactly the same formula. ++It is up to you to ensure that the function will eventually converge; ++if it doesn't, you may have to press @kbd{C-g} to stop the Calculator. ++ ++The algebraic @code{fixp} function takes two optional arguments, @samp{n} ++and @samp{tol}. The first is the maximum number of steps to be allowed, ++and must be either an integer or the symbol @samp{inf} (infinity, the ++default). The second is a convergence tolerance. If a tolerance is ++specified, all results during the calculation must be numbers, not ++formulas, and the iteration stops when the magnitude of the difference ++between two successive results is less than or equal to the tolerance. ++(This implies that a tolerance of zero iterates until the results are ++exactly equal.) ++ ++Putting it all together, @samp{fixp(<(# + A/#)/2>, B, 20, 1e-10)} ++computes the square root of @samp{A} given the initial guess @samp{B}, ++stopping when the result is correct within the specified tolerance, or ++when 20 steps have been taken, whichever is sooner. ++ ++@node Generalized Products, , Nesting and Fixed Points, Reducing and Mapping ++@subsection Generalized Products ++ ++@kindex V O ++@pindex calc-outer-product ++@tindex outer ++The @kbd{V O} (@code{calc-outer-product}) [@code{outer}] command applies ++a given binary operator to all possible pairs of elements from two ++vectors, to produce a matrix. For example, @kbd{V O *} with @samp{[a, b]} ++and @samp{[x, y, z]} on the stack produces a multiplication table: ++@samp{[[a x, a y, a z], [b x, b y, b z]]}. Element @var{r},@var{c} of ++the result matrix is obtained by applying the operator to element @var{r} ++of the lefthand vector and element @var{c} of the righthand vector. ++ ++@kindex V I ++@pindex calc-inner-product ++@tindex inner ++The @kbd{V I} (@code{calc-inner-product}) [@code{inner}] command computes ++the generalized inner product of two vectors or matrices, given a ++``multiplicative'' operator and an ``additive'' operator. These can each ++actually be any binary operators; if they are @samp{*} and @samp{+}, ++respectively, the result is a standard matrix multiplication. Element ++@var{r},@var{c} of the result matrix is obtained by mapping the ++multiplicative operator across row @var{r} of the lefthand matrix and ++column @var{c} of the righthand matrix, and then reducing with the additive ++operator. Just as for the standard @kbd{*} command, this can also do a ++vector-matrix or matrix-vector inner product, or a vector-vector ++generalized dot product. ++ ++Since @kbd{V I} requires two operators, it prompts twice. In each case, ++you can use any of the usual methods for entering the operator. If you ++use @kbd{$} twice to take both operator formulas from the stack, the ++first (multiplicative) operator is taken from the top of the stack ++and the second (additive) operator is taken from second-to-top. ++ ++@node Vector and Matrix Formats, , Reducing and Mapping, Matrix Functions ++@section Vector and Matrix Display Formats ++ ++@noindent ++Commands for controlling vector and matrix display use the @kbd{v} prefix ++instead of the usual @kbd{d} prefix. But they are display modes; in ++particular, they are influenced by the @kbd{I} and @kbd{H} prefix keys ++in the same way (@pxref{Display Modes}). Matrix display is also ++influenced by the @kbd{d O} (@code{calc-flat-language}) mode; ++@pxref{Normal Language Modes}. ++ ++@kindex V < ++@pindex calc-matrix-left-justify ++@kindex V = ++@pindex calc-matrix-center-justify ++@kindex V > ++@pindex calc-matrix-right-justify ++The commands @kbd{v <} (@code{calc-matrix-left-justify}), @kbd{v >} ++(@code{calc-matrix-right-justify}), and @w{@kbd{v =}} ++(@code{calc-matrix-center-justify}) control whether matrix elements ++are justified to the left, right, or center of their columns. ++ ++@kindex V [ ++@pindex calc-vector-brackets ++@kindex V @{ ++@pindex calc-vector-braces ++@kindex V ( ++@pindex calc-vector-parens ++The @kbd{v [} (@code{calc-vector-brackets}) command turns the square ++brackets that surround vectors and matrices displayed in the stack on ++and off. The @kbd{v @{} (@code{calc-vector-braces}) and @kbd{v (} ++(@code{calc-vector-parens}) commands use curly braces or parentheses, ++respectively, instead of square brackets. For example, @kbd{v @{} might ++be used in preparation for yanking a matrix into a buffer running ++Mathematica. (In fact, the Mathematica language mode uses this mode; ++@pxref{Mathematica Language Mode}.) Note that, regardless of the ++display mode, either brackets or braces may be used to enter vectors, ++and parentheses may never be used for this purpose. ++ ++@kindex V ] ++@pindex calc-matrix-brackets ++The @kbd{v ]} (@code{calc-matrix-brackets}) command controls the ++``big'' style display of matrices. It prompts for a string of code ++letters; currently implemented letters are @code{R}, which enables ++brackets on each row of the matrix; @code{O}, which enables outer ++brackets in opposite corners of the matrix; and @code{C}, which ++enables commas or semicolons at the ends of all rows but the last. ++The default format is @samp{RO}. (Before Calc 2.00, the format ++was fixed at @samp{ROC}.) Here are some example matrices: ++ ++@example ++@group ++[ [ 123, 0, 0 ] [ [ 123, 0, 0 ], ++ [ 0, 123, 0 ] [ 0, 123, 0 ], ++ [ 0, 0, 123 ] ] [ 0, 0, 123 ] ] ++ ++ RO ROC ++ ++@end group ++@end example ++@noindent ++@example ++@group ++ [ 123, 0, 0 [ 123, 0, 0 ; ++ 0, 123, 0 0, 123, 0 ; ++ 0, 0, 123 ] 0, 0, 123 ] ++ ++ O OC ++ ++@end group ++@end example ++@noindent ++@example ++@group ++ [ 123, 0, 0 ] 123, 0, 0 ++ [ 0, 123, 0 ] 0, 123, 0 ++ [ 0, 0, 123 ] 0, 0, 123 ++ ++ R @r{blank} ++@end group ++@end example ++ ++@noindent ++Note that of the formats shown here, @samp{RO}, @samp{ROC}, and ++@samp{OC} are all recognized as matrices during reading, while ++the others are useful for display only. ++ ++@kindex V , ++@pindex calc-vector-commas ++The @kbd{v ,} (@code{calc-vector-commas}) command turns commas on and ++off in vector and matrix display. ++ ++In vectors of length one, and in all vectors when commas have been ++turned off, Calc adds extra parentheses around formulas that might ++otherwise be ambiguous. For example, @samp{[a b]} could be a vector ++of the one formula @samp{a b}, or it could be a vector of two ++variables with commas turned off. Calc will display the former ++case as @samp{[(a b)]}. You can disable these extra parentheses ++(to make the output less cluttered at the expense of allowing some ++ambiguity) by adding the letter @code{P} to the control string you ++give to @kbd{v ]} (as described above). ++ ++@kindex V . ++@pindex calc-full-vectors ++The @kbd{v .} (@code{calc-full-vectors}) command turns abbreviated ++display of long vectors on and off. In this mode, vectors of six ++or more elements, or matrices of six or more rows or columns, will ++be displayed in an abbreviated form that displays only the first ++three elements and the last element: @samp{[a, b, c, ..., z]}. ++When very large vectors are involved this will substantially ++improve Calc's display speed. ++ ++@kindex t . ++@pindex calc-full-trail-vectors ++The @kbd{t .} (@code{calc-full-trail-vectors}) command controls a ++similar mode for recording vectors in the Trail. If you turn on ++this mode, vectors of six or more elements and matrices of six or ++more rows or columns will be abbreviated when they are put in the ++Trail. The @kbd{t y} (@code{calc-trail-yank}) command will be ++unable to recover those vectors. If you are working with very ++large vectors, this mode will improve the speed of all operations ++that involve the trail. ++ ++@kindex V / ++@pindex calc-break-vectors ++The @kbd{v /} (@code{calc-break-vectors}) command turns multi-line ++vector display on and off. Normally, matrices are displayed with one ++row per line but all other types of vectors are displayed in a single ++line. This mode causes all vectors, whether matrices or not, to be ++displayed with a single element per line. Sub-vectors within the ++vectors will still use the normal linear form. ++ ++@node Algebra, Units, Matrix Functions, Top ++@chapter Algebra ++ ++@noindent ++This section covers the Calc features that help you work with ++algebraic formulas. First, the general sub-formula selection ++mechanism is described; this works in conjunction with any Calc ++commands. Then, commands for specific algebraic operations are ++described. Finally, the flexible @dfn{rewrite rule} mechanism ++is discussed. ++ ++The algebraic commands use the @kbd{a} key prefix; selection ++commands use the @kbd{j} (for ``just a letter that wasn't used ++for anything else'') prefix. ++ ++@xref{Editing Stack Entries}, to see how to manipulate formulas ++using regular Emacs editing commands. ++ ++When doing algebraic work, you may find several of the Calculator's ++modes to be helpful, including Algebraic Simplification mode (@kbd{m A}) ++or No-Simplification mode (@kbd{m O}), ++Algebraic entry mode (@kbd{m a}), Fraction mode (@kbd{m f}), and ++Symbolic mode (@kbd{m s}). @xref{Mode Settings}, for discussions ++of these modes. You may also wish to select Big display mode (@kbd{d B}). ++@xref{Normal Language Modes}. ++ ++@menu ++* Selecting Subformulas:: ++* Algebraic Manipulation:: ++* Simplifying Formulas:: ++* Polynomials:: ++* Calculus:: ++* Solving Equations:: ++* Numerical Solutions:: ++* Curve Fitting:: ++* Summations:: ++* Logical Operations:: ++* Rewrite Rules:: ++@end menu ++ ++@node Selecting Subformulas, Algebraic Manipulation, Algebra, Algebra ++@section Selecting Sub-Formulas ++ ++@noindent ++@cindex Selections ++@cindex Sub-formulas ++@cindex Parts of formulas ++When working with an algebraic formula it is often necessary to ++manipulate a portion of the formula rather than the formula as a ++whole. Calc allows you to ``select'' a portion of any formula on ++the stack. Commands which would normally operate on that stack ++entry will now operate only on the sub-formula, leaving the ++surrounding part of the stack entry alone. ++ ++One common non-algebraic use for selection involves vectors. To work ++on one element of a vector in-place, simply select that element as a ++``sub-formula'' of the vector. ++ ++@menu ++* Making Selections:: ++* Changing Selections:: ++* Displaying Selections:: ++* Operating on Selections:: ++* Rearranging with Selections:: ++@end menu ++ ++@node Making Selections, Changing Selections, Selecting Subformulas, Selecting Subformulas ++@subsection Making Selections ++ ++@noindent ++@kindex j s ++@pindex calc-select-here ++To select a sub-formula, move the Emacs cursor to any character in that ++sub-formula, and press @w{@kbd{j s}} (@code{calc-select-here}). Calc will ++highlight the smallest portion of the formula that contains that ++character. By default the sub-formula is highlighted by blanking out ++all of the rest of the formula with dots. Selection works in any ++display mode but is perhaps easiest in Big mode (@kbd{d B}). ++Suppose you enter the following formula: ++ ++@smallexample ++@group ++ 3 ___ ++ (a + b) + V c ++1: --------------- ++ 2 x + 1 ++@end group ++@end smallexample ++ ++@noindent ++(by typing @kbd{' ((a+b)^3 + sqrt(c)) / (2x+1)}). If you move the ++cursor to the letter @samp{b} and press @w{@kbd{j s}}, the display changes ++to ++ ++@smallexample ++@group ++ . ... ++ .. . b. . . . ++1* ............... ++ . . . . ++@end group ++@end smallexample ++ ++@noindent ++Every character not part of the sub-formula @samp{b} has been changed ++to a dot. The @samp{*} next to the line number is to remind you that ++the formula has a portion of it selected. (In this case, it's very ++obvious, but it might not always be. If Embedded mode is enabled, ++the word @samp{Sel} also appears in the mode line because the stack ++may not be visible. @pxref{Embedded Mode}.) ++ ++If you had instead placed the cursor on the parenthesis immediately to ++the right of the @samp{b}, the selection would have been: ++ ++@smallexample ++@group ++ . ... ++ (a + b) . . . ++1* ............... ++ . . . . ++@end group ++@end smallexample ++ ++@noindent ++The portion selected is always large enough to be considered a complete ++formula all by itself, so selecting the parenthesis selects the whole ++formula that it encloses. Putting the cursor on the @samp{+} sign ++would have had the same effect. ++ ++(Strictly speaking, the Emacs cursor is really the manifestation of ++the Emacs ``point,'' which is a position @emph{between} two characters ++in the buffer. So purists would say that Calc selects the smallest ++sub-formula which contains the character to the right of ``point.'') ++ ++If you supply a numeric prefix argument @var{n}, the selection is ++expanded to the @var{n}th enclosing sub-formula. Thus, positioning ++the cursor on the @samp{b} and typing @kbd{C-u 1 j s} will select ++@samp{a + b}; typing @kbd{C-u 2 j s} will select @samp{(a + b)^3}, ++and so on. ++ ++If the cursor is not on any part of the formula, or if you give a ++numeric prefix that is too large, the entire formula is selected. ++ ++If the cursor is on the @samp{.} line that marks the top of the stack ++(i.e., its normal ``rest position''), this command selects the entire ++formula at stack level 1. Most selection commands similarly operate ++on the formula at the top of the stack if you haven't positioned the ++cursor on any stack entry. ++ ++@kindex j a ++@pindex calc-select-additional ++The @kbd{j a} (@code{calc-select-additional}) command enlarges the ++current selection to encompass the cursor. To select the smallest ++sub-formula defined by two different points, move to the first and ++press @kbd{j s}, then move to the other and press @kbd{j a}. This ++is roughly analogous to using @kbd{C-@@} (@code{set-mark-command}) to ++select the two ends of a region of text during normal Emacs editing. ++ ++@kindex j o ++@pindex calc-select-once ++The @kbd{j o} (@code{calc-select-once}) command selects a formula in ++exactly the same way as @kbd{j s}, except that the selection will ++last only as long as the next command that uses it. For example, ++@kbd{j o 1 +} is a handy way to add one to the sub-formula indicated ++by the cursor. ++ ++(A somewhat more precise definition: The @kbd{j o} command sets a flag ++such that the next command involving selected stack entries will clear ++the selections on those stack entries afterwards. All other selection ++commands except @kbd{j a} and @kbd{j O} clear this flag.) ++ ++@kindex j S ++@kindex j O ++@pindex calc-select-here-maybe ++@pindex calc-select-once-maybe ++The @kbd{j S} (@code{calc-select-here-maybe}) and @kbd{j O} ++(@code{calc-select-once-maybe}) commands are equivalent to @kbd{j s} ++and @kbd{j o}, respectively, except that if the formula already ++has a selection they have no effect. This is analogous to the ++behavior of some commands such as @kbd{j r} (@code{calc-rewrite-selection}; ++@pxref{Selections with Rewrite Rules}) and is mainly intended to be ++used in keyboard macros that implement your own selection-oriented ++commands. ++ ++Selection of sub-formulas normally treats associative terms like ++@samp{a + b - c + d} and @samp{x * y * z} as single levels of the formula. ++If you place the cursor anywhere inside @samp{a + b - c + d} except ++on one of the variable names and use @kbd{j s}, you will select the ++entire four-term sum. ++ ++@kindex j b ++@pindex calc-break-selections ++The @kbd{j b} (@code{calc-break-selections}) command controls a mode ++in which the ``deep structure'' of these associative formulas shows ++through. Calc actually stores the above formulas as ++@samp{((a + b) - c) + d} and @samp{x * (y * z)}. (Note that for certain ++obscure reasons, by default Calc treats multiplication as ++right-associative.) Once you have enabled @kbd{j b} mode, selecting ++with the cursor on the @samp{-} sign would only select the @samp{a + b - ++c} portion, which makes sense when the deep structure of the sum is ++considered. There is no way to select the @samp{b - c + d} portion; ++although this might initially look like just as legitimate a sub-formula ++as @samp{a + b - c}, the deep structure shows that it isn't. The @kbd{d ++U} command can be used to view the deep structure of any formula ++(@pxref{Normal Language Modes}). ++ ++When @kbd{j b} mode has not been enabled, the deep structure is ++generally hidden by the selection commands---what you see is what ++you get. ++ ++@kindex j u ++@pindex calc-unselect ++The @kbd{j u} (@code{calc-unselect}) command unselects the formula ++that the cursor is on. If there was no selection in the formula, ++this command has no effect. With a numeric prefix argument, it ++unselects the @var{n}th stack element rather than using the cursor ++position. ++ ++@kindex j c ++@pindex calc-clear-selections ++The @kbd{j c} (@code{calc-clear-selections}) command unselects all ++stack elements. ++ ++@node Changing Selections, Displaying Selections, Making Selections, Selecting Subformulas ++@subsection Changing Selections ++ ++@noindent ++@kindex j m ++@pindex calc-select-more ++Once you have selected a sub-formula, you can expand it using the ++@w{@kbd{j m}} (@code{calc-select-more}) command. If @samp{a + b} is ++selected, pressing @w{@kbd{j m}} repeatedly works as follows: ++ ++@smallexample ++@group ++ 3 ... 3 ___ 3 ___ ++ (a + b) . . . (a + b) + V c (a + b) + V c ++1* ............... 1* ............... 1* --------------- ++ . . . . . . . . 2 x + 1 ++@end group ++@end smallexample ++ ++@noindent ++In the last example, the entire formula is selected. This is roughly ++the same as having no selection at all, but because there are subtle ++differences the @samp{*} character is still there on the line number. ++ ++With a numeric prefix argument @var{n}, @kbd{j m} expands @var{n} ++times (or until the entire formula is selected). Note that @kbd{j s} ++with argument @var{n} is equivalent to plain @kbd{j s} followed by ++@kbd{j m} with argument @var{n}. If @w{@kbd{j m}} is used when there ++is no current selection, it is equivalent to @w{@kbd{j s}}. ++ ++Even though @kbd{j m} does not explicitly use the location of the ++cursor within the formula, it nevertheless uses the cursor to determine ++which stack element to operate on. As usual, @kbd{j m} when the cursor ++is not on any stack element operates on the top stack element. ++ ++@kindex j l ++@pindex calc-select-less ++The @kbd{j l} (@code{calc-select-less}) command reduces the current ++selection around the cursor position. That is, it selects the ++immediate sub-formula of the current selection which contains the ++cursor, the opposite of @kbd{j m}. If the cursor is not inside the ++current selection, the command de-selects the formula. ++ ++@kindex j 1-9 ++@pindex calc-select-part ++The @kbd{j 1} through @kbd{j 9} (@code{calc-select-part}) commands ++select the @var{n}th sub-formula of the current selection. They are ++like @kbd{j l} (@code{calc-select-less}) except they use counting ++rather than the cursor position to decide which sub-formula to select. ++For example, if the current selection is @kbd{a + b + c} or ++@kbd{f(a, b, c)} or @kbd{[a, b, c]}, then @kbd{j 1} selects @samp{a}, ++@kbd{j 2} selects @samp{b}, and @kbd{j 3} selects @samp{c}; in each of ++these cases, @kbd{j 4} through @kbd{j 9} would be errors. ++ ++If there is no current selection, @kbd{j 1} through @kbd{j 9} select ++the @var{n}th top-level sub-formula. (In other words, they act as if ++the entire stack entry were selected first.) To select the @var{n}th ++sub-formula where @var{n} is greater than nine, you must instead invoke ++@w{@kbd{j 1}} with @var{n} as a numeric prefix argument. ++ ++@kindex j n ++@kindex j p ++@pindex calc-select-next ++@pindex calc-select-previous ++The @kbd{j n} (@code{calc-select-next}) and @kbd{j p} ++(@code{calc-select-previous}) commands change the current selection ++to the next or previous sub-formula at the same level. For example, ++if @samp{b} is selected in @w{@samp{2 + a*b*c + x}}, then @kbd{j n} ++selects @samp{c}. Further @kbd{j n} commands would be in error because, ++even though there is something to the right of @samp{c} (namely, @samp{x}), ++it is not at the same level; in this case, it is not a term of the ++same product as @samp{b} and @samp{c}. However, @kbd{j m} (to select ++the whole product @samp{a*b*c} as a term of the sum) followed by ++@w{@kbd{j n}} would successfully select the @samp{x}. ++ ++Similarly, @kbd{j p} moves the selection from the @samp{b} in this ++sample formula to the @samp{a}. Both commands accept numeric prefix ++arguments to move several steps at a time. ++ ++It is interesting to compare Calc's selection commands with the ++Emacs Info system's commands for navigating through hierarchically ++organized documentation. Calc's @kbd{j n} command is completely ++analogous to Info's @kbd{n} command. Likewise, @kbd{j p} maps to ++@kbd{p}, @kbd{j 2} maps to @kbd{2}, and Info's @kbd{u} is like @kbd{j m}. ++(Note that @kbd{j u} stands for @code{calc-unselect}, not ``up''.) ++The Info @kbd{m} command is somewhat similar to Calc's @kbd{j s} and ++@kbd{j l}; in each case, you can jump directly to a sub-component ++of the hierarchy simply by pointing to it with the cursor. ++ ++@node Displaying Selections, Operating on Selections, Changing Selections, Selecting Subformulas ++@subsection Displaying Selections ++ ++@noindent ++@kindex j d ++@pindex calc-show-selections ++The @kbd{j d} (@code{calc-show-selections}) command controls how ++selected sub-formulas are displayed. One of the alternatives is ++illustrated in the above examples; if we press @kbd{j d} we switch ++to the other style in which the selected portion itself is obscured ++by @samp{#} signs: ++ ++@smallexample ++@group ++ 3 ... # ___ ++ (a + b) . . . ## # ## + V c ++1* ............... 1* --------------- ++ . . . . 2 x + 1 ++@end group ++@end smallexample ++ ++@node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas ++@subsection Operating on Selections ++ ++@noindent ++Once a selection is made, all Calc commands that manipulate items ++on the stack will operate on the selected portions of the items ++instead. (Note that several stack elements may have selections ++at once, though there can be only one selection at a time in any ++given stack element.) ++ ++@kindex j e ++@pindex calc-enable-selections ++The @kbd{j e} (@code{calc-enable-selections}) command disables the ++effect that selections have on Calc commands. The current selections ++still exist, but Calc commands operate on whole stack elements anyway. ++This mode can be identified by the fact that the @samp{*} markers on ++the line numbers are gone, even though selections are visible. To ++reactivate the selections, press @kbd{j e} again. ++ ++To extract a sub-formula as a new formula, simply select the ++sub-formula and press @key{RET}. This normally duplicates the top ++stack element; here it duplicates only the selected portion of that ++element. ++ ++To replace a sub-formula with something different, you can enter the ++new value onto the stack and press @key{TAB}. This normally exchanges ++the top two stack elements; here it swaps the value you entered into ++the selected portion of the formula, returning the old selected ++portion to the top of the stack. ++ ++@smallexample ++@group ++ 3 ... ... ___ ++ (a + b) . . . 17 x y . . . 17 x y + V c ++2* ............... 2* ............. 2: ------------- ++ . . . . . . . . 2 x + 1 ++ ++ 3 3 ++1: 17 x y 1: (a + b) 1: (a + b) ++@end group ++@end smallexample ++ ++In this example we select a sub-formula of our original example, ++enter a new formula, @key{TAB} it into place, then deselect to see ++the complete, edited formula. ++ ++If you want to swap whole formulas around even though they contain ++selections, just use @kbd{j e} before and after. ++ ++@kindex j ' ++@pindex calc-enter-selection ++The @kbd{j '} (@code{calc-enter-selection}) command is another way ++to replace a selected sub-formula. This command does an algebraic ++entry just like the regular @kbd{'} key. When you press @key{RET}, ++the formula you type replaces the original selection. You can use ++the @samp{$} symbol in the formula to refer to the original ++selection. If there is no selection in the formula under the cursor, ++the cursor is used to make a temporary selection for the purposes of ++the command. Thus, to change a term of a formula, all you have to ++do is move the Emacs cursor to that term and press @kbd{j '}. ++ ++@kindex j ` ++@pindex calc-edit-selection ++The @kbd{j `} (@code{calc-edit-selection}) command is a similar ++analogue of the @kbd{`} (@code{calc-edit}) command. It edits the ++selected sub-formula in a separate buffer. If there is no ++selection, it edits the sub-formula indicated by the cursor. ++ ++To delete a sub-formula, press @key{DEL}. This generally replaces ++the sub-formula with the constant zero, but in a few suitable contexts ++it uses the constant one instead. The @key{DEL} key automatically ++deselects and re-simplifies the entire formula afterwards. Thus: ++ ++@smallexample ++@group ++ ### ++ 17 x y + # # 17 x y 17 # y 17 y ++1* ------------- 1: ------- 1* ------- 1: ------- ++ 2 x + 1 2 x + 1 2 x + 1 2 x + 1 ++@end group ++@end smallexample ++ ++In this example, we first delete the @samp{sqrt(c)} term; Calc ++accomplishes this by replacing @samp{sqrt(c)} with zero and ++resimplifying. We then delete the @kbd{x} in the numerator; ++since this is part of a product, Calc replaces it with @samp{1} ++and resimplifies. ++ ++If you select an element of a vector and press @key{DEL}, that ++element is deleted from the vector. If you delete one side of ++an equation or inequality, only the opposite side remains. ++ ++@kindex j @key{DEL} ++@pindex calc-del-selection ++The @kbd{j @key{DEL}} (@code{calc-del-selection}) command is like ++@key{DEL} but with the auto-selecting behavior of @kbd{j '} and ++@kbd{j `}. It deletes the selected portion of the formula ++indicated by the cursor, or, in the absence of a selection, it ++deletes the sub-formula indicated by the cursor position. ++ ++@kindex j @key{RET} ++@pindex calc-grab-selection ++(There is also an auto-selecting @kbd{j @key{RET}} (@code{calc-copy-selection}) ++command.) ++ ++Normal arithmetic operations also apply to sub-formulas. Here we ++select the denominator, press @kbd{5 -} to subtract five from the ++denominator, press @kbd{n} to negate the denominator, then ++press @kbd{Q} to take the square root. ++ ++@smallexample ++@group ++ .. . .. . .. . .. . ++1* ....... 1* ....... 1* ....... 1* .......... ++ 2 x + 1 2 x - 4 4 - 2 x _________ ++ V 4 - 2 x ++@end group ++@end smallexample ++ ++Certain types of operations on selections are not allowed. For ++example, for an arithmetic function like @kbd{-} no more than one of ++the arguments may be a selected sub-formula. (As the above example ++shows, the result of the subtraction is spliced back into the argument ++which had the selection; if there were more than one selection involved, ++this would not be well-defined.) If you try to subtract two selections, ++the command will abort with an error message. ++ ++Operations on sub-formulas sometimes leave the formula as a whole ++in an ``un-natural'' state. Consider negating the @samp{2 x} term ++of our sample formula by selecting it and pressing @kbd{n} ++(@code{calc-change-sign}). ++ ++@smallexample ++@group ++ .. . .. . ++1* .......... 1* ........... ++ ......... .......... ++ . . . 2 x . . . -2 x ++@end group ++@end smallexample ++ ++Unselecting the sub-formula reveals that the minus sign, which would ++normally have cancelled out with the subtraction automatically, has ++not been able to do so because the subtraction was not part of the ++selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing ++any other mathematical operation on the whole formula will cause it ++to be simplified. ++ ++@smallexample ++@group ++ 17 y 17 y ++1: ----------- 1: ---------- ++ __________ _________ ++ V 4 - -2 x V 4 + 2 x ++@end group ++@end smallexample ++ ++@node Rearranging with Selections, , Operating on Selections, Selecting Subformulas ++@subsection Rearranging Formulas using Selections ++ ++@noindent ++@kindex j R ++@pindex calc-commute-right ++The @kbd{j R} (@code{calc-commute-right}) command moves the selected ++sub-formula to the right in its surrounding formula. Generally the ++selection is one term of a sum or product; the sum or product is ++rearranged according to the commutative laws of algebra. ++ ++As with @kbd{j '} and @kbd{j @key{DEL}}, the term under the cursor is used ++if there is no selection in the current formula. All commands described ++in this section share this property. In this example, we place the ++cursor on the @samp{a} and type @kbd{j R}, then repeat. ++ ++@smallexample ++1: a + b - c 1: b + a - c 1: b - c + a ++@end smallexample ++ ++@noindent ++Note that in the final step above, the @samp{a} is switched with ++the @samp{c} but the signs are adjusted accordingly. When moving ++terms of sums and products, @kbd{j R} will never change the ++mathematical meaning of the formula. ++ ++The selected term may also be an element of a vector or an argument ++of a function. The term is exchanged with the one to its right. ++In this case, the ``meaning'' of the vector or function may of ++course be drastically changed. ++ ++@smallexample ++1: [a, b, c] 1: [b, a, c] 1: [b, c, a] ++ ++1: f(a, b, c) 1: f(b, a, c) 1: f(b, c, a) ++@end smallexample ++ ++@kindex j L ++@pindex calc-commute-left ++The @kbd{j L} (@code{calc-commute-left}) command is like @kbd{j R} ++except that it swaps the selected term with the one to its left. ++ ++With numeric prefix arguments, these commands move the selected ++term several steps at a time. It is an error to try to move a ++term left or right past the end of its enclosing formula. ++With numeric prefix arguments of zero, these commands move the ++selected term as far as possible in the given direction. ++ ++@kindex j D ++@pindex calc-sel-distribute ++The @kbd{j D} (@code{calc-sel-distribute}) command mixes the selected ++sum or product into the surrounding formula using the distributive ++law. For example, in @samp{a * (b - c)} with the @samp{b - c} ++selected, the result is @samp{a b - a c}. This also distributes ++products or quotients into surrounding powers, and can also do ++transformations like @samp{exp(a + b)} to @samp{exp(a) exp(b)}, ++where @samp{a + b} is the selected term, and @samp{ln(a ^ b)} ++to @samp{ln(a) b}, where @samp{a ^ b} is the selected term. ++ ++For multiple-term sums or products, @kbd{j D} takes off one term ++at a time: @samp{a * (b + c - d)} goes to @samp{a * (c - d) + a b} ++with the @samp{c - d} selected so that you can type @kbd{j D} ++repeatedly to expand completely. The @kbd{j D} command allows a ++numeric prefix argument which specifies the maximum number of ++times to expand at once; the default is one time only. ++ ++@vindex DistribRules ++The @kbd{j D} command is implemented using rewrite rules. ++@xref{Selections with Rewrite Rules}. The rules are stored in ++the Calc variable @code{DistribRules}. A convenient way to view ++these rules is to use @kbd{s e} (@code{calc-edit-variable}) which ++displays and edits the stored value of a variable. Press @kbd{C-c C-c} ++to return from editing mode; be careful not to make any actual changes ++or else you will affect the behavior of future @kbd{j D} commands! ++ ++To extend @kbd{j D} to handle new cases, just edit @code{DistribRules} ++as described above. You can then use the @kbd{s p} command to save ++this variable's value permanently for future Calc sessions. ++@xref{Operations on Variables}. ++ ++@kindex j M ++@pindex calc-sel-merge ++@vindex MergeRules ++The @kbd{j M} (@code{calc-sel-merge}) command is the complement ++of @kbd{j D}; given @samp{a b - a c} with either @samp{a b} or ++@samp{a c} selected, the result is @samp{a * (b - c)}. Once ++again, @kbd{j M} can also merge calls to functions like @code{exp} ++and @code{ln}; examine the variable @code{MergeRules} to see all ++the relevant rules. ++ ++@kindex j C ++@pindex calc-sel-commute ++@vindex CommuteRules ++The @kbd{j C} (@code{calc-sel-commute}) command swaps the arguments ++of the selected sum, product, or equation. It always behaves as ++if @kbd{j b} mode were in effect, i.e., the sum @samp{a + b + c} is ++treated as the nested sums @samp{(a + b) + c} by this command. ++If you put the cursor on the first @samp{+}, the result is ++@samp{(b + a) + c}; if you put the cursor on the second @samp{+}, the ++result is @samp{c + (a + b)} (which the default simplifications ++will rearrange to @samp{(c + a) + b}). The relevant rules are stored ++in the variable @code{CommuteRules}. ++ ++You may need to turn default simplifications off (with the @kbd{m O} ++command) in order to get the full benefit of @kbd{j C}. For example, ++commuting @samp{a - b} produces @samp{-b + a}, but the default ++simplifications will ``simplify'' this right back to @samp{a - b} if ++you don't turn them off. The same is true of some of the other ++manipulations described in this section. ++ ++@kindex j N ++@pindex calc-sel-negate ++@vindex NegateRules ++The @kbd{j N} (@code{calc-sel-negate}) command replaces the selected ++term with the negative of that term, then adjusts the surrounding ++formula in order to preserve the meaning. For example, given ++@samp{exp(a - b)} where @samp{a - b} is selected, the result is ++@samp{1 / exp(b - a)}. By contrast, selecting a term and using the ++regular @kbd{n} (@code{calc-change-sign}) command negates the ++term without adjusting the surroundings, thus changing the meaning ++of the formula as a whole. The rules variable is @code{NegateRules}. ++ ++@kindex j & ++@pindex calc-sel-invert ++@vindex InvertRules ++The @kbd{j &} (@code{calc-sel-invert}) command is similar to @kbd{j N} ++except it takes the reciprocal of the selected term. For example, ++given @samp{a - ln(b)} with @samp{b} selected, the result is ++@samp{a + ln(1/b)}. The rules variable is @code{InvertRules}. ++ ++@kindex j E ++@pindex calc-sel-jump-equals ++@vindex JumpRules ++The @kbd{j E} (@code{calc-sel-jump-equals}) command moves the ++selected term from one side of an equation to the other. Given ++@samp{a + b = c + d} with @samp{c} selected, the result is ++@samp{a + b - c = d}. This command also works if the selected ++term is part of a @samp{*}, @samp{/}, or @samp{^} formula. The ++relevant rules variable is @code{JumpRules}. ++ ++@kindex j I ++@kindex H j I ++@pindex calc-sel-isolate ++The @kbd{j I} (@code{calc-sel-isolate}) command isolates the ++selected term on its side of an equation. It uses the @kbd{a S} ++(@code{calc-solve-for}) command to solve the equation, and the ++Hyperbolic flag affects it in the same way. @xref{Solving Equations}. ++When it applies, @kbd{j I} is often easier to use than @kbd{j E}. ++It understands more rules of algebra, and works for inequalities ++as well as equations. ++ ++@kindex j * ++@kindex j / ++@pindex calc-sel-mult-both-sides ++@pindex calc-sel-div-both-sides ++The @kbd{j *} (@code{calc-sel-mult-both-sides}) command prompts for a ++formula using algebraic entry, then multiplies both sides of the ++selected quotient or equation by that formula. It simplifies each ++side with @kbd{a s} (@code{calc-simplify}) before re-forming the ++quotient or equation. You can suppress this simplification by ++providing a prefix argument: @kbd{C-u j *}. There is also a @kbd{j /} ++(@code{calc-sel-div-both-sides}) which is similar to @kbd{j *} but ++dividing instead of multiplying by the factor you enter. ++ ++If the selection is a quotient with numerator 1, then Calc's default ++simplifications would normally cancel the new factors. To prevent ++this, when the @kbd{j *} command is used on a selection whose numerator is ++1 or -1, the denominator is expanded at the top level using the ++distributive law (as if using the @kbd{C-u 1 a x} command). Suppose the ++formula on the stack is @samp{1 / (a + 1)} and you wish to multiplying the ++top and bottom by @samp{a - 1}. Calc's default simplifications would ++normally change the result @samp{(a - 1) /(a + 1) (a - 1)} back ++to the original form by cancellation; when @kbd{j *} is used, Calc ++expands the denominator to @samp{a (a - 1) + a - 1} to prevent this. ++ ++If you wish the @kbd{j *} command to completely expand the denominator ++of a quotient you can call it with a zero prefix: @kbd{C-u 0 j *}. For ++example, if the formula on the stack is @samp{1 / (sqrt(a) + 1)}, you may ++wish to eliminate the square root in the denominator by multiplying ++the top and bottom by @samp{sqrt(a) - 1}. If you did this simply by using ++a simple @kbd{j *} command, you would get ++@samp{(sqrt(a)-1)/ (sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1)}. Instead, ++you would probably want to use @kbd{C-u 0 j *}, which would expand the ++bottom and give you the desired result @samp{(sqrt(a)-1)/(a-1)}. More ++generally, if @kbd{j *} is called with an argument of a positive ++integer @var{n}, then the denominator of the expression will be ++expanded @var{n} times (as if with the @kbd{C-u @var{n} a x} command). ++ ++If the selection is an inequality, @kbd{j *} and @kbd{j /} will ++accept any factor, but will warn unless they can prove the factor ++is either positive or negative. (In the latter case the direction ++of the inequality will be switched appropriately.) @xref{Declarations}, ++for ways to inform Calc that a given variable is positive or ++negative. If Calc can't tell for sure what the sign of the factor ++will be, it will assume it is positive and display a warning ++message. ++ ++For selections that are not quotients, equations, or inequalities, ++these commands pull out a multiplicative factor: They divide (or ++multiply) by the entered formula, simplify, then multiply (or divide) ++back by the formula. ++ ++@kindex j + ++@kindex j - ++@pindex calc-sel-add-both-sides ++@pindex calc-sel-sub-both-sides ++The @kbd{j +} (@code{calc-sel-add-both-sides}) and @kbd{j -} ++(@code{calc-sel-sub-both-sides}) commands analogously add to or ++subtract from both sides of an equation or inequality. For other ++types of selections, they extract an additive factor. A numeric ++prefix argument suppresses simplification of the intermediate ++results. ++ ++@kindex j U ++@pindex calc-sel-unpack ++The @kbd{j U} (@code{calc-sel-unpack}) command replaces the ++selected function call with its argument. For example, given ++@samp{a + sin(x^2)} with @samp{sin(x^2)} selected, the result ++is @samp{a + x^2}. (The @samp{x^2} will remain selected; if you ++wanted to change the @code{sin} to @code{cos}, just press @kbd{C} ++now to take the cosine of the selected part.) ++ ++@kindex j v ++@pindex calc-sel-evaluate ++The @kbd{j v} (@code{calc-sel-evaluate}) command performs the ++normal default simplifications on the selected sub-formula. ++These are the simplifications that are normally done automatically ++on all results, but which may have been partially inhibited by ++previous selection-related operations, or turned off altogether ++by the @kbd{m O} command. This command is just an auto-selecting ++version of the @w{@kbd{a v}} command (@pxref{Algebraic Manipulation}). ++ ++With a numeric prefix argument of 2, @kbd{C-u 2 j v} applies ++the @kbd{a s} (@code{calc-simplify}) command to the selected ++sub-formula. With a prefix argument of 3 or more, e.g., @kbd{C-u j v} ++applies the @kbd{a e} (@code{calc-simplify-extended}) command. ++@xref{Simplifying Formulas}. With a negative prefix argument ++it simplifies at the top level only, just as with @kbd{a v}. ++Here the ``top'' level refers to the top level of the selected ++sub-formula. ++ ++@kindex j " ++@pindex calc-sel-expand-formula ++The @kbd{j "} (@code{calc-sel-expand-formula}) command is to @kbd{a "} ++(@pxref{Algebraic Manipulation}) what @kbd{j v} is to @kbd{a v}. ++ ++You can use the @kbd{j r} (@code{calc-rewrite-selection}) command ++to define other algebraic operations on sub-formulas. @xref{Rewrite Rules}. ++ ++@node Algebraic Manipulation, Simplifying Formulas, Selecting Subformulas, Algebra ++@section Algebraic Manipulation ++ ++@noindent ++The commands in this section perform general-purpose algebraic ++manipulations. They work on the whole formula at the top of the ++stack (unless, of course, you have made a selection in that ++formula). ++ ++Many algebra commands prompt for a variable name or formula. If you ++answer the prompt with a blank line, the variable or formula is taken ++from top-of-stack, and the normal argument for the command is taken ++from the second-to-top stack level. ++ ++@kindex a v ++@pindex calc-alg-evaluate ++The @kbd{a v} (@code{calc-alg-evaluate}) command performs the normal ++default simplifications on a formula; for example, @samp{a - -b} is ++changed to @samp{a + b}. These simplifications are normally done ++automatically on all Calc results, so this command is useful only if ++you have turned default simplifications off with an @kbd{m O} ++command. @xref{Simplification Modes}. ++ ++It is often more convenient to type @kbd{=}, which is like @kbd{a v} ++but which also substitutes stored values for variables in the formula. ++Use @kbd{a v} if you want the variables to ignore their stored values. ++ ++If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies ++as if in Algebraic Simplification mode. This is equivalent to typing ++@kbd{a s}; @pxref{Simplifying Formulas}. If you give a numeric prefix ++of 3 or more, it uses Extended Simplification mode (@kbd{a e}). ++ ++If you give a negative prefix argument @mathit{-1}, @mathit{-2}, or @mathit{-3}, ++it simplifies in the corresponding mode but only works on the top-level ++function call of the formula. For example, @samp{(2 + 3) * (2 + 3)} will ++simplify to @samp{(2 + 3)^2}, without simplifying the sub-formulas ++@samp{2 + 3}. As another example, typing @kbd{V R +} to sum the vector ++@samp{[1, 2, 3, 4]} produces the formula @samp{reduce(add, [1, 2, 3, 4])} ++in No-Simplify mode. Using @kbd{a v} will evaluate this all the way to ++10; using @kbd{C-u - a v} will evaluate it only to @samp{1 + 2 + 3 + 4}. ++(@xref{Reducing and Mapping}.) ++ ++@tindex evalv ++@tindex evalvn ++The @kbd{=} command corresponds to the @code{evalv} function, and ++the related @kbd{N} command, which is like @kbd{=} but temporarily ++disables Symbolic mode (@kbd{m s}) during the evaluation, corresponds ++to the @code{evalvn} function. (These commands interpret their prefix ++arguments differently than @kbd{a v}; @kbd{=} treats the prefix as ++the number of stack elements to evaluate at once, and @kbd{N} treats ++it as a temporary different working precision.) ++ ++The @code{evalvn} function can take an alternate working precision ++as an optional second argument. This argument can be either an ++integer, to set the precision absolutely, or a vector containing ++a single integer, to adjust the precision relative to the current ++precision. Note that @code{evalvn} with a larger than current ++precision will do the calculation at this higher precision, but the ++result will as usual be rounded back down to the current precision ++afterward. For example, @samp{evalvn(pi - 3.1415)} at a precision ++of 12 will return @samp{9.265359e-5}; @samp{evalvn(pi - 3.1415, 30)} ++will return @samp{9.26535897932e-5} (computing a 25-digit result which ++is then rounded down to 12); and @samp{evalvn(pi - 3.1415, [-2])} ++will return @samp{9.2654e-5}. ++ ++@kindex a " ++@pindex calc-expand-formula ++The @kbd{a "} (@code{calc-expand-formula}) command expands functions ++into their defining formulas wherever possible. For example, ++@samp{deg(x^2)} is changed to @samp{180 x^2 / pi}. Most functions, ++like @code{sin} and @code{gcd}, are not defined by simple formulas ++and so are unaffected by this command. One important class of ++functions which @emph{can} be expanded is the user-defined functions ++created by the @kbd{Z F} command. @xref{Algebraic Definitions}. ++Other functions which @kbd{a "} can expand include the probability ++distribution functions, most of the financial functions, and the ++hyperbolic and inverse hyperbolic functions. A numeric prefix argument ++affects @kbd{a "} in the same way as it does @kbd{a v}: A positive ++argument expands all functions in the formula and then simplifies in ++various ways; a negative argument expands and simplifies only the ++top-level function call. ++ ++@kindex a M ++@pindex calc-map-equation ++@tindex mapeq ++The @kbd{a M} (@code{calc-map-equation}) [@code{mapeq}] command applies ++a given function or operator to one or more equations. It is analogous ++to @kbd{V M}, which operates on vectors instead of equations. ++@pxref{Reducing and Mapping}. For example, @kbd{a M S} changes ++@samp{x = y+1} to @samp{sin(x) = sin(y+1)}, and @kbd{a M +} with ++@samp{x = y+1} and @expr{6} on the stack produces @samp{x+6 = y+7}. ++With two equations on the stack, @kbd{a M +} would add the lefthand ++sides together and the righthand sides together to get the two ++respective sides of a new equation. ++ ++Mapping also works on inequalities. Mapping two similar inequalities ++produces another inequality of the same type. Mapping an inequality ++with an equation produces an inequality of the same type. Mapping a ++@samp{<=} with a @samp{<} or @samp{!=} (not-equal) produces a @samp{<}. ++If inequalities with opposite direction (e.g., @samp{<} and @samp{>}) ++are mapped, the direction of the second inequality is reversed to ++match the first: Using @kbd{a M +} on @samp{a < b} and @samp{a > 2} ++reverses the latter to get @samp{2 < a}, which then allows the ++combination @samp{a + 2 < b + a}, which the @kbd{a s} command can ++then simplify to get @samp{2 < b}. ++ ++Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate ++or invert an inequality will reverse the direction of the inequality. ++Other adjustments to inequalities are @emph{not} done automatically; ++@kbd{a M S} will change @w{@samp{x < y}} to @samp{sin(x) < sin(y)} even ++though this is not true for all values of the variables. ++ ++@kindex H a M ++@tindex mapeqp ++With the Hyperbolic flag, @kbd{H a M} [@code{mapeqp}] does a plain ++mapping operation without reversing the direction of any inequalities. ++Thus, @kbd{H a M &} would change @kbd{x > 2} to @kbd{1/x > 0.5}. ++(This change is mathematically incorrect, but perhaps you were ++fixing an inequality which was already incorrect.) ++ ++@kindex I a M ++@tindex mapeqr ++With the Inverse flag, @kbd{I a M} [@code{mapeqr}] always reverses ++the direction of the inequality. You might use @kbd{I a M C} to ++change @samp{x < y} to @samp{cos(x) > cos(y)} if you know you are ++working with small positive angles. ++ ++@kindex a b ++@pindex calc-substitute ++@tindex subst ++The @kbd{a b} (@code{calc-substitute}) [@code{subst}] command substitutes ++all occurrences ++of some variable or sub-expression of an expression with a new ++sub-expression. For example, substituting @samp{sin(x)} with @samp{cos(y)} ++in @samp{2 sin(x)^2 + x sin(x) + sin(2 x)} produces ++@samp{2 cos(y)^2 + x cos(y) + @w{sin(2 x)}}. ++Note that this is a purely structural substitution; the lone @samp{x} and ++the @samp{sin(2 x)} stayed the same because they did not look like ++@samp{sin(x)}. @xref{Rewrite Rules}, for a more general method for ++doing substitutions. ++ ++The @kbd{a b} command normally prompts for two formulas, the old ++one and the new one. If you enter a blank line for the first ++prompt, all three arguments are taken from the stack (new, then old, ++then target expression). If you type an old formula but then enter a ++blank line for the new one, the new formula is taken from top-of-stack ++and the target from second-to-top. If you answer both prompts, the ++target is taken from top-of-stack as usual. ++ ++Note that @kbd{a b} has no understanding of commutativity or ++associativity. The pattern @samp{x+y} will not match the formula ++@samp{y+x}. Also, @samp{y+z} will not match inside the formula @samp{x+y+z} ++because the @samp{+} operator is left-associative, so the ``deep ++structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U} ++(@code{calc-unformatted-language}) mode to see the true structure of ++a formula. The rewrite rule mechanism, discussed later, does not have ++these limitations. ++ ++As an algebraic function, @code{subst} takes three arguments: ++Target expression, old, new. Note that @code{subst} is always ++evaluated immediately, even if its arguments are variables, so if ++you wish to put a call to @code{subst} onto the stack you must ++turn the default simplifications off first (with @kbd{m O}). ++ ++@node Simplifying Formulas, Polynomials, Algebraic Manipulation, Algebra ++@section Simplifying Formulas ++ ++@noindent ++@kindex a s ++@pindex calc-simplify ++@tindex simplify ++The @kbd{a s} (@code{calc-simplify}) [@code{simplify}] command applies ++various algebraic rules to simplify a formula. This includes rules which ++are not part of the default simplifications because they may be too slow ++to apply all the time, or may not be desirable all of the time. For ++example, non-adjacent terms of sums are combined, as in @samp{a + b + 2 a} ++to @samp{b + 3 a}, and some formulas like @samp{sin(arcsin(x))} are ++simplified to @samp{x}. ++ ++The sections below describe all the various kinds of algebraic ++simplifications Calc provides in full detail. None of Calc's ++simplification commands are designed to pull rabbits out of hats; ++they simply apply certain specific rules to put formulas into ++less redundant or more pleasing forms. Serious algebra in Calc ++must be done manually, usually with a combination of selections ++and rewrite rules. @xref{Rearranging with Selections}. ++@xref{Rewrite Rules}. ++ ++@xref{Simplification Modes}, for commands to control what level of ++simplification occurs automatically. Normally only the ``default ++simplifications'' occur. ++ ++@menu ++* Default Simplifications:: ++* Algebraic Simplifications:: ++* Unsafe Simplifications:: ++* Simplification of Units:: ++@end menu ++ ++@node Default Simplifications, Algebraic Simplifications, Simplifying Formulas, Simplifying Formulas ++@subsection Default Simplifications ++ ++@noindent ++@cindex Default simplifications ++This section describes the ``default simplifications,'' those which are ++normally applied to all results. For example, if you enter the variable ++@expr{x} on the stack twice and push @kbd{+}, Calc's default ++simplifications automatically change @expr{x + x} to @expr{2 x}. ++ ++The @kbd{m O} command turns off the default simplifications, so that ++@expr{x + x} will remain in this form unless you give an explicit ++``simplify'' command like @kbd{=} or @kbd{a v}. @xref{Algebraic ++Manipulation}. The @kbd{m D} command turns the default simplifications ++back on. ++ ++The most basic default simplification is the evaluation of functions. ++For example, @expr{2 + 3} is evaluated to @expr{5}, and @expr{@tfn{sqrt}(9)} ++is evaluated to @expr{3}. Evaluation does not occur if the arguments ++to a function are somehow of the wrong type @expr{@tfn{tan}([2,3,4])}), ++range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}), ++or if the function name is not recognized (@expr{@tfn{f}(5)}), or if ++Symbolic mode (@pxref{Symbolic Mode}) prevents evaluation ++(@expr{@tfn{sqrt}(2)}). ++ ++Calc simplifies (evaluates) the arguments to a function before it ++simplifies the function itself. Thus @expr{@tfn{sqrt}(5+4)} is ++simplified to @expr{@tfn{sqrt}(9)} before the @code{sqrt} function ++itself is applied. There are very few exceptions to this rule: ++@code{quote}, @code{lambda}, and @code{condition} (the @code{::} ++operator) do not evaluate their arguments, @code{if} (the @code{? :} ++operator) does not evaluate all of its arguments, and @code{evalto} ++does not evaluate its lefthand argument. ++ ++Most commands apply the default simplifications to all arguments they ++take from the stack, perform a particular operation, then simplify ++the result before pushing it back on the stack. In the common special ++case of regular arithmetic commands like @kbd{+} and @kbd{Q} [@code{sqrt}], ++the arguments are simply popped from the stack and collected into a ++suitable function call, which is then simplified (the arguments being ++simplified first as part of the process, as described above). ++ ++The default simplifications are too numerous to describe completely ++here, but this section will describe the ones that apply to the ++major arithmetic operators. This list will be rather technical in ++nature, and will probably be interesting to you only if you are ++a serious user of Calc's algebra facilities. ++ ++@tex ++\bigskip ++@end tex ++ ++As well as the simplifications described here, if you have stored ++any rewrite rules in the variable @code{EvalRules} then these rules ++will also be applied before any built-in default simplifications. ++@xref{Automatic Rewrites}, for details. ++ ++@tex ++\bigskip ++@end tex ++ ++And now, on with the default simplifications: ++ ++Arithmetic operators like @kbd{+} and @kbd{*} always take two ++arguments in Calc's internal form. Sums and products of three or ++more terms are arranged by the associative law of algebra into ++a left-associative form for sums, @expr{((a + b) + c) + d}, and ++(by default) a right-associative form for products, ++@expr{a * (b * (c * d))}. Formulas like @expr{(a + b) + (c + d)} are ++rearranged to left-associative form, though this rarely matters since ++Calc's algebra commands are designed to hide the inner structure of sums ++and products as much as possible. Sums and products in their proper ++associative form will be written without parentheses in the examples ++below. ++ ++Sums and products are @emph{not} rearranged according to the ++commutative law (@expr{a + b} to @expr{b + a}) except in a few ++special cases described below. Some algebra programs always ++rearrange terms into a canonical order, which enables them to ++see that @expr{a b + b a} can be simplified to @expr{2 a b}. ++Calc assumes you have put the terms into the order you want ++and generally leaves that order alone, with the consequence ++that formulas like the above will only be simplified if you ++explicitly give the @kbd{a s} command. @xref{Algebraic ++Simplifications}. ++ ++Differences @expr{a - b} are treated like sums @expr{a + (-b)} ++for purposes of simplification; one of the default simplifications ++is to rewrite @expr{a + (-b)} or @expr{(-b) + a}, where @expr{-b} ++represents a ``negative-looking'' term, into @expr{a - b} form. ++``Negative-looking'' means negative numbers, negated formulas like ++@expr{-x}, and products or quotients in which either term is ++negative-looking. ++ ++Other simplifications involving negation are @expr{-(-x)} to @expr{x}; ++@expr{-(a b)} or @expr{-(a/b)} where either @expr{a} or @expr{b} is ++negative-looking, simplified by negating that term, or else where ++@expr{a} or @expr{b} is any number, by negating that number; ++@expr{-(a + b)} to @expr{-a - b}, and @expr{-(b - a)} to @expr{a - b}. ++(This, and rewriting @expr{(-b) + a} to @expr{a - b}, are the only ++cases where the order of terms in a sum is changed by the default ++simplifications.) ++ ++The distributive law is used to simplify sums in some cases: ++@expr{a x + b x} to @expr{(a + b) x}, where @expr{a} represents ++a number or an implicit 1 or @mathit{-1} (as in @expr{x} or @expr{-x}) ++and similarly for @expr{b}. Use the @kbd{a c}, @w{@kbd{a f}}, or ++@kbd{j M} commands to merge sums with non-numeric coefficients ++using the distributive law. ++ ++The distributive law is only used for sums of two terms, or ++for adjacent terms in a larger sum. Thus @expr{a + b + b + c} ++is simplified to @expr{a + 2 b + c}, but @expr{a + b + c + b} ++is not simplified. The reason is that comparing all terms of a ++sum with one another would require time proportional to the ++square of the number of terms; Calc relegates potentially slow ++operations like this to commands that have to be invoked ++explicitly, like @kbd{a s}. ++ ++Finally, @expr{a + 0} and @expr{0 + a} are simplified to @expr{a}. ++A consequence of the above rules is that @expr{0 - a} is simplified ++to @expr{-a}. ++ ++@tex ++\bigskip ++@end tex ++ ++The products @expr{1 a} and @expr{a 1} are simplified to @expr{a}; ++@expr{(-1) a} and @expr{a (-1)} are simplified to @expr{-a}; ++@expr{0 a} and @expr{a 0} are simplified to @expr{0}, except that ++in Matrix mode where @expr{a} is not provably scalar the result ++is the generic zero matrix @samp{idn(0)}, and that if @expr{a} is ++infinite the result is @samp{nan}. ++ ++Also, @expr{(-a) b} and @expr{a (-b)} are simplified to @expr{-(a b)}, ++where this occurs for negated formulas but not for regular negative ++numbers. ++ ++Products are commuted only to move numbers to the front: ++@expr{a b 2} is commuted to @expr{2 a b}. ++ ++The product @expr{a (b + c)} is distributed over the sum only if ++@expr{a} and at least one of @expr{b} and @expr{c} are numbers: ++@expr{2 (x + 3)} goes to @expr{2 x + 6}. The formula ++@expr{(-a) (b - c)}, where @expr{-a} is a negative number, is ++rewritten to @expr{a (c - b)}. ++ ++The distributive law of products and powers is used for adjacent ++terms of the product: @expr{x^a x^b} goes to ++@texline @math{x^{a+b}} ++@infoline @expr{x^(a+b)} ++where @expr{a} is a number, or an implicit 1 (as in @expr{x}), ++or the implicit one-half of @expr{@tfn{sqrt}(x)}, and similarly for ++@expr{b}. The result is written using @samp{sqrt} or @samp{1/sqrt} ++if the sum of the powers is @expr{1/2} or @expr{-1/2}, respectively. ++If the sum of the powers is zero, the product is simplified to ++@expr{1} or to @samp{idn(1)} if Matrix mode is enabled. ++ ++The product of a negative power times anything but another negative ++power is changed to use division: ++@texline @math{x^{-2} y} ++@infoline @expr{x^(-2) y} ++goes to @expr{y / x^2} unless Matrix mode is ++in effect and neither @expr{x} nor @expr{y} are scalar (in which ++case it is considered unsafe to rearrange the order of the terms). ++ ++Finally, @expr{a (b/c)} is rewritten to @expr{(a b)/c}, and also ++@expr{(a/b) c} is changed to @expr{(a c)/b} unless in Matrix mode. ++ ++@tex ++\bigskip ++@end tex ++ ++Simplifications for quotients are analogous to those for products. ++The quotient @expr{0 / x} is simplified to @expr{0}, with the same ++exceptions that were noted for @expr{0 x}. Likewise, @expr{x / 1} ++and @expr{x / (-1)} are simplified to @expr{x} and @expr{-x}, ++respectively. ++ ++The quotient @expr{x / 0} is left unsimplified or changed to an ++infinite quantity, as directed by the current infinite mode. ++@xref{Infinite Mode}. ++ ++The expression ++@texline @math{a / b^{-c}} ++@infoline @expr{a / b^(-c)} ++is changed to @expr{a b^c}, where @expr{-c} is any negative-looking ++power. Also, @expr{1 / b^c} is changed to ++@texline @math{b^{-c}} ++@infoline @expr{b^(-c)} ++for any power @expr{c}. ++ ++Also, @expr{(-a) / b} and @expr{a / (-b)} go to @expr{-(a/b)}; ++@expr{(a/b) / c} goes to @expr{a / (b c)}; and @expr{a / (b/c)} ++goes to @expr{(a c) / b} unless Matrix mode prevents this ++rearrangement. Similarly, @expr{a / (b:c)} is simplified to ++@expr{(c:b) a} for any fraction @expr{b:c}. ++ ++The distributive law is applied to @expr{(a + b) / c} only if ++@expr{c} and at least one of @expr{a} and @expr{b} are numbers. ++Quotients of powers and square roots are distributed just as ++described for multiplication. ++ ++Quotients of products cancel only in the leading terms of the ++numerator and denominator. In other words, @expr{a x b / a y b} ++is cancelled to @expr{x b / y b} but not to @expr{x / y}. Once ++again this is because full cancellation can be slow; use @kbd{a s} ++to cancel all terms of the quotient. ++ ++Quotients of negative-looking values are simplified according ++to @expr{(-a) / (-b)} to @expr{a / b}, @expr{(-a) / (b - c)} ++to @expr{a / (c - b)}, and @expr{(a - b) / (-c)} to @expr{(b - a) / c}. ++ ++@tex ++\bigskip ++@end tex ++ ++The formula @expr{x^0} is simplified to @expr{1}, or to @samp{idn(1)} ++in Matrix mode. The formula @expr{0^x} is simplified to @expr{0} ++unless @expr{x} is a negative number, complex number or zero. ++If @expr{x} is negative, complex or @expr{0.0}, @expr{0^x} is an ++infinity or an unsimplified formula according to the current infinite ++mode. The expression @expr{0^0} is simplified to @expr{1}. ++ ++Powers of products or quotients @expr{(a b)^c}, @expr{(a/b)^c} ++are distributed to @expr{a^c b^c}, @expr{a^c / b^c} only if @expr{c} ++is an integer, or if either @expr{a} or @expr{b} are nonnegative ++real numbers. Powers of powers @expr{(a^b)^c} are simplified to ++@texline @math{a^{b c}} ++@infoline @expr{a^(b c)} ++only when @expr{c} is an integer and @expr{b c} also ++evaluates to an integer. Without these restrictions these simplifications ++would not be safe because of problems with principal values. ++(In other words, ++@texline @math{((-3)^{1/2})^2} ++@infoline @expr{((-3)^1:2)^2} ++is safe to simplify, but ++@texline @math{((-3)^2)^{1/2}} ++@infoline @expr{((-3)^2)^1:2} ++is not.) @xref{Declarations}, for ways to inform Calc that your ++variables satisfy these requirements. ++ ++As a special case of this rule, @expr{@tfn{sqrt}(x)^n} is simplified to ++@texline @math{x^{n/2}} ++@infoline @expr{x^(n/2)} ++only for even integers @expr{n}. ++ ++If @expr{a} is known to be real, @expr{b} is an even integer, and ++@expr{c} is a half- or quarter-integer, then @expr{(a^b)^c} is ++simplified to @expr{@tfn{abs}(a^(b c))}. ++ ++Also, @expr{(-a)^b} is simplified to @expr{a^b} if @expr{b} is an ++even integer, or to @expr{-(a^b)} if @expr{b} is an odd integer, ++for any negative-looking expression @expr{-a}. ++ ++Square roots @expr{@tfn{sqrt}(x)} generally act like one-half powers ++@texline @math{x^{1:2}} ++@infoline @expr{x^1:2} ++for the purposes of the above-listed simplifications. ++ ++Also, note that ++@texline @math{1 / x^{1:2}} ++@infoline @expr{1 / x^1:2} ++is changed to ++@texline @math{x^{-1:2}}, ++@infoline @expr{x^(-1:2)}, ++but @expr{1 / @tfn{sqrt}(x)} is left alone. ++ ++@tex ++\bigskip ++@end tex ++ ++Generic identity matrices (@pxref{Matrix Mode}) are simplified by the ++following rules: @expr{@tfn{idn}(a) + b} to @expr{a + b} if @expr{b} ++is provably scalar, or expanded out if @expr{b} is a matrix; ++@expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)}; ++@expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to ++@expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b} ++if @expr{a} is provably non-scalar; @expr{@tfn{idn}(a) @tfn{idn}(b)} to ++@expr{@tfn{idn}(a b)}; analogous simplifications for quotients involving ++@code{idn}; and @expr{@tfn{idn}(a)^n} to @expr{@tfn{idn}(a^n)} where ++@expr{n} is an integer. ++ ++@tex ++\bigskip ++@end tex ++ ++The @code{floor} function and other integer truncation functions ++vanish if the argument is provably integer-valued, so that ++@expr{@tfn{floor}(@tfn{round}(x))} simplifies to @expr{@tfn{round}(x)}. ++Also, combinations of @code{float}, @code{floor} and its friends, ++and @code{ffloor} and its friends, are simplified in appropriate ++ways. @xref{Integer Truncation}. ++ ++The expression @expr{@tfn{abs}(-x)} changes to @expr{@tfn{abs}(x)}. ++The expression @expr{@tfn{abs}(@tfn{abs}(x))} changes to ++@expr{@tfn{abs}(x)}; in fact, @expr{@tfn{abs}(x)} changes to @expr{x} or ++@expr{-x} if @expr{x} is provably nonnegative or nonpositive ++(@pxref{Declarations}). ++ ++While most functions do not recognize the variable @code{i} as an ++imaginary number, the @code{arg} function does handle the two cases ++@expr{@tfn{arg}(@tfn{i})} and @expr{@tfn{arg}(-@tfn{i})} just for convenience. ++ ++The expression @expr{@tfn{conj}(@tfn{conj}(x))} simplifies to @expr{x}. ++Various other expressions involving @code{conj}, @code{re}, and ++@code{im} are simplified, especially if some of the arguments are ++provably real or involve the constant @code{i}. For example, ++@expr{@tfn{conj}(a + b i)} is changed to ++@expr{@tfn{conj}(a) - @tfn{conj}(b) i}, or to @expr{a - b i} if @expr{a} ++and @expr{b} are known to be real. ++ ++Functions like @code{sin} and @code{arctan} generally don't have ++any default simplifications beyond simply evaluating the functions ++for suitable numeric arguments and infinity. The @kbd{a s} command ++described in the next section does provide some simplifications for ++these functions, though. ++ ++One important simplification that does occur is that ++@expr{@tfn{ln}(@tfn{e})} is simplified to 1, and @expr{@tfn{ln}(@tfn{e}^x)} is ++simplified to @expr{x} for any @expr{x}. This occurs even if you have ++stored a different value in the Calc variable @samp{e}; but this would ++be a bad idea in any case if you were also using natural logarithms! ++ ++Among the logical functions, @tfn{!(@var{a} <= @var{b})} changes to ++@tfn{@var{a} > @var{b}} and so on. Equations and inequalities where both sides ++are either negative-looking or zero are simplified by negating both sides ++and reversing the inequality. While it might seem reasonable to simplify ++@expr{!!x} to @expr{x}, this would not be valid in general because ++@expr{!!2} is 1, not 2. ++ ++Most other Calc functions have few if any default simplifications ++defined, aside of course from evaluation when the arguments are ++suitable numbers. ++ ++@node Algebraic Simplifications, Unsafe Simplifications, Default Simplifications, Simplifying Formulas ++@subsection Algebraic Simplifications ++ ++@noindent ++@cindex Algebraic simplifications ++The @kbd{a s} command makes simplifications that may be too slow to ++do all the time, or that may not be desirable all of the time. ++If you find these simplifications are worthwhile, you can type ++@kbd{m A} to have Calc apply them automatically. ++ ++This section describes all simplifications that are performed by ++the @kbd{a s} command. Note that these occur in addition to the ++default simplifications; even if the default simplifications have ++been turned off by an @kbd{m O} command, @kbd{a s} will turn them ++back on temporarily while it simplifies the formula. ++ ++There is a variable, @code{AlgSimpRules}, in which you can put rewrites ++to be applied by @kbd{a s}. Its use is analogous to @code{EvalRules}, ++but without the special restrictions. Basically, the simplifier does ++@samp{@w{a r} AlgSimpRules} with an infinite repeat count on the whole ++expression being simplified, then it traverses the expression applying ++the built-in rules described below. If the result is different from ++the original expression, the process repeats with the default ++simplifications (including @code{EvalRules}), then @code{AlgSimpRules}, ++then the built-in simplifications, and so on. ++ ++@tex ++\bigskip ++@end tex ++ ++Sums are simplified in two ways. Constant terms are commuted to the ++end of the sum, so that @expr{a + 2 + b} changes to @expr{a + b + 2}. ++The only exception is that a constant will not be commuted away ++from the first position of a difference, i.e., @expr{2 - x} is not ++commuted to @expr{-x + 2}. ++ ++Also, terms of sums are combined by the distributive law, as in ++@expr{x + y + 2 x} to @expr{y + 3 x}. This always occurs for ++adjacent terms, but @kbd{a s} compares all pairs of terms including ++non-adjacent ones. ++ ++@tex ++\bigskip ++@end tex ++ ++Products are sorted into a canonical order using the commutative ++law. For example, @expr{b c a} is commuted to @expr{a b c}. ++This allows easier comparison of products; for example, the default ++simplifications will not change @expr{x y + y x} to @expr{2 x y}, ++but @kbd{a s} will; it first rewrites the sum to @expr{x y + x y}, ++and then the default simplifications are able to recognize a sum ++of identical terms. ++ ++The canonical ordering used to sort terms of products has the ++property that real-valued numbers, interval forms and infinities ++come first, and are sorted into increasing order. The @kbd{V S} ++command uses the same ordering when sorting a vector. ++ ++Sorting of terms of products is inhibited when Matrix mode is ++turned on; in this case, Calc will never exchange the order of ++two terms unless it knows at least one of the terms is a scalar. ++ ++Products of powers are distributed by comparing all pairs of ++terms, using the same method that the default simplifications ++use for adjacent terms of products. ++ ++Even though sums are not sorted, the commutative law is still ++taken into account when terms of a product are being compared. ++Thus @expr{(x + y) (y + x)} will be simplified to @expr{(x + y)^2}. ++A subtle point is that @expr{(x - y) (y - x)} will @emph{not} ++be simplified to @expr{-(x - y)^2}; Calc does not notice that ++one term can be written as a constant times the other, even if ++that constant is @mathit{-1}. ++ ++A fraction times any expression, @expr{(a:b) x}, is changed to ++a quotient involving integers: @expr{a x / b}. This is not ++done for floating-point numbers like @expr{0.5}, however. This ++is one reason why you may find it convenient to turn Fraction mode ++on while doing algebra; @pxref{Fraction Mode}. ++ ++@tex ++\bigskip ++@end tex ++ ++Quotients are simplified by comparing all terms in the numerator ++with all terms in the denominator for possible cancellation using ++the distributive law. For example, @expr{a x^2 b / c x^3 d} will ++cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}. ++(The terms in the denominator will then be rearranged to @expr{c d x} ++as described above.) If there is any common integer or fractional ++factor in the numerator and denominator, it is cancelled out; ++for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}. ++ ++Non-constant common factors are not found even by @kbd{a s}. To ++cancel the factor @expr{a} in @expr{(a x + a) / a^2} you could first ++use @kbd{j M} on the product @expr{a x} to Merge the numerator to ++@expr{a (1+x)}, which can then be simplified successfully. ++ ++@tex ++\bigskip ++@end tex ++ ++Integer powers of the variable @code{i} are simplified according ++to the identity @expr{i^2 = -1}. If you store a new value other ++than the complex number @expr{(0,1)} in @code{i}, this simplification ++will no longer occur. This is done by @kbd{a s} instead of by default ++in case someone (unwisely) uses the name @code{i} for a variable ++unrelated to complex numbers; it would be unfortunate if Calc ++quietly and automatically changed this formula for reasons the ++user might not have been thinking of. ++ ++Square roots of integer or rational arguments are simplified in ++several ways. (Note that these will be left unevaluated only in ++Symbolic mode.) First, square integer or rational factors are ++pulled out so that @expr{@tfn{sqrt}(8)} is rewritten as ++@texline @math{2\,@tfn{sqrt}(2)}. ++@infoline @expr{2 sqrt(2)}. ++Conceptually speaking this implies factoring the argument into primes ++and moving pairs of primes out of the square root, but for reasons of ++efficiency Calc only looks for primes up to 29. ++ ++Square roots in the denominator of a quotient are moved to the ++numerator: @expr{1 / @tfn{sqrt}(3)} changes to @expr{@tfn{sqrt}(3) / 3}. ++The same effect occurs for the square root of a fraction: ++@expr{@tfn{sqrt}(2:3)} changes to @expr{@tfn{sqrt}(6) / 3}. ++ ++@tex ++\bigskip ++@end tex ++ ++The @code{%} (modulo) operator is simplified in several ways ++when the modulus @expr{M} is a positive real number. First, if ++the argument is of the form @expr{x + n} for some real number ++@expr{n}, then @expr{n} is itself reduced modulo @expr{M}. For ++example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}. ++ ++If the argument is multiplied by a constant, and this constant ++has a common integer divisor with the modulus, then this factor is ++cancelled out. For example, @samp{12 x % 15} is changed to ++@samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15} ++is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may ++not seem ``simpler,'' they allow Calc to discover useful information ++about modulo forms in the presence of declarations. ++ ++If the modulus is 1, then Calc can use @code{int} declarations to ++evaluate the expression. For example, the idiom @samp{x % 2} is ++often used to check whether a number is odd or even. As described ++above, @w{@samp{2 n % 2}} and @samp{(2 n + 1) % 2} are simplified to ++@samp{2 (n % 1)} and @samp{2 ((n + 1:2) % 1)}, respectively; Calc ++can simplify these to 0 and 1 (respectively) if @code{n} has been ++declared to be an integer. ++ ++@tex ++\bigskip ++@end tex ++ ++Trigonometric functions are simplified in several ways. Whenever a ++products of two trigonometric functions can be replaced by a single ++function, the replacement is made; for example, ++@expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}. ++Reciprocals of trigonometric functions are replaced by their reciprocal ++function; for example, @expr{1/@tfn{sec}(x)} is simplified to ++@expr{@tfn{cos}(x)}. The corresponding simplifications for the ++hyperbolic functions are also handled. ++ ++Trigonometric functions of their inverse functions are ++simplified. The expression @expr{@tfn{sin}(@tfn{arcsin}(x))} is ++simplified to @expr{x}, and similarly for @code{cos} and @code{tan}. ++Trigonometric functions of inverses of different trigonometric ++functions can also be simplified, as in @expr{@tfn{sin}(@tfn{arccos}(x))} ++to @expr{@tfn{sqrt}(1 - x^2)}. ++ ++If the argument to @code{sin} is negative-looking, it is simplified to ++@expr{-@tfn{sin}(x)}, and similarly for @code{cos} and @code{tan}. ++Finally, certain special values of the argument are recognized; ++@pxref{Trigonometric and Hyperbolic Functions}. ++ ++Hyperbolic functions of their inverses and of negative-looking ++arguments are also handled, as are exponentials of inverse ++hyperbolic functions. ++ ++No simplifications for inverse trigonometric and hyperbolic ++functions are known, except for negative arguments of @code{arcsin}, ++@code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that ++@expr{@tfn{arcsin}(@tfn{sin}(x))} can @emph{not} safely change to ++@expr{x}, since this only correct within an integer multiple of ++@texline @math{2 \pi} ++@infoline @expr{2 pi} ++radians or 360 degrees. However, @expr{@tfn{arcsinh}(@tfn{sinh}(x))} is ++simplified to @expr{x} if @expr{x} is known to be real. ++ ++Several simplifications that apply to logarithms and exponentials ++are that @expr{@tfn{exp}(@tfn{ln}(x))}, ++@texline @tfn{e}@math{^{\ln(x)}}, ++@infoline @expr{e^@tfn{ln}(x)}, ++and ++@texline @math{10^{{\rm log10}(x)}} ++@infoline @expr{10^@tfn{log10}(x)} ++all reduce to @expr{x}. Also, @expr{@tfn{ln}(@tfn{exp}(x))}, etc., can ++reduce to @expr{x} if @expr{x} is provably real. The form ++@expr{@tfn{exp}(x)^y} is simplified to @expr{@tfn{exp}(x y)}. If @expr{x} ++is a suitable multiple of ++@texline @math{\pi i} ++@infoline @expr{pi i} ++(as described above for the trigonometric functions), then ++@expr{@tfn{exp}(x)} or @expr{e^x} will be expanded. Finally, ++@expr{@tfn{ln}(x)} is simplified to a form involving @code{pi} and ++@code{i} where @expr{x} is provably negative, positive imaginary, or ++negative imaginary. ++ ++The error functions @code{erf} and @code{erfc} are simplified when ++their arguments are negative-looking or are calls to the @code{conj} ++function. ++ ++@tex ++\bigskip ++@end tex ++ ++Equations and inequalities are simplified by cancelling factors ++of products, quotients, or sums on both sides. Inequalities ++change sign if a negative multiplicative factor is cancelled. ++Non-constant multiplicative factors as in @expr{a b = a c} are ++cancelled from equations only if they are provably nonzero (generally ++because they were declared so; @pxref{Declarations}). Factors ++are cancelled from inequalities only if they are nonzero and their ++sign is known. ++ ++Simplification also replaces an equation or inequality with ++1 or 0 (``true'' or ``false'') if it can through the use of ++declarations. If @expr{x} is declared to be an integer greater ++than 5, then @expr{x < 3}, @expr{x = 3}, and @expr{x = 7.5} are ++all simplified to 0, but @expr{x > 3} is simplified to 1. ++By a similar analysis, @expr{abs(x) >= 0} is simplified to 1, ++as is @expr{x^2 >= 0} if @expr{x} is known to be real. ++ ++@node Unsafe Simplifications, Simplification of Units, Algebraic Simplifications, Simplifying Formulas ++@subsection ``Unsafe'' Simplifications ++ ++@noindent ++@cindex Unsafe simplifications ++@cindex Extended simplification ++@kindex a e ++@pindex calc-simplify-extended ++@ignore ++@mindex esimpl@idots ++@end ignore ++@tindex esimplify ++The @kbd{a e} (@code{calc-simplify-extended}) [@code{esimplify}] command ++is like @kbd{a s} ++except that it applies some additional simplifications which are not ++``safe'' in all cases. Use this only if you know the values in your ++formula lie in the restricted ranges for which these simplifications ++are valid. The symbolic integrator uses @kbd{a e}; ++one effect of this is that the integrator's results must be used with ++caution. Where an integral table will often attach conditions like ++``for positive @expr{a} only,'' Calc (like most other symbolic ++integration programs) will simply produce an unqualified result. ++ ++Because @kbd{a e}'s simplifications are unsafe, it is sometimes better ++to type @kbd{C-u -3 a v}, which does extended simplification only ++on the top level of the formula without affecting the sub-formulas. ++In fact, @kbd{C-u -3 j v} allows you to target extended simplification ++to any specific part of a formula. ++ ++The variable @code{ExtSimpRules} contains rewrites to be applied by ++the @kbd{a e} command. These are applied in addition to ++@code{EvalRules} and @code{AlgSimpRules}. (The @kbd{a r AlgSimpRules} ++step described above is simply followed by an @kbd{a r ExtSimpRules} step.) ++ ++Following is a complete list of ``unsafe'' simplifications performed ++by @kbd{a e}. ++ ++@tex ++\bigskip ++@end tex ++ ++Inverse trigonometric or hyperbolic functions, called with their ++corresponding non-inverse functions as arguments, are simplified ++by @kbd{a e}. For example, @expr{@tfn{arcsin}(@tfn{sin}(x))} changes ++to @expr{x}. Also, @expr{@tfn{arcsin}(@tfn{cos}(x))} and ++@expr{@tfn{arccos}(@tfn{sin}(x))} both change to @expr{@tfn{pi}/2 - x}. ++These simplifications are unsafe because they are valid only for ++values of @expr{x} in a certain range; outside that range, values ++are folded down to the 360-degree range that the inverse trigonometric ++functions always produce. ++ ++Powers of powers @expr{(x^a)^b} are simplified to ++@texline @math{x^{a b}} ++@infoline @expr{x^(a b)} ++for all @expr{a} and @expr{b}. These results will be valid only ++in a restricted range of @expr{x}; for example, in ++@texline @math{(x^2)^{1:2}} ++@infoline @expr{(x^2)^1:2} ++the powers cancel to get @expr{x}, which is valid for positive values ++of @expr{x} but not for negative or complex values. ++ ++Similarly, @expr{@tfn{sqrt}(x^a)} and @expr{@tfn{sqrt}(x)^a} are both ++simplified (possibly unsafely) to ++@texline @math{x^{a/2}}. ++@infoline @expr{x^(a/2)}. ++ ++Forms like @expr{@tfn{sqrt}(1 - sin(x)^2)} are simplified to, e.g., ++@expr{@tfn{cos}(x)}. Calc has identities of this sort for @code{sin}, ++@code{cos}, @code{tan}, @code{sinh}, and @code{cosh}. ++ ++Arguments of square roots are partially factored to look for ++squared terms that can be extracted. For example, ++@expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to ++@expr{a b @tfn{sqrt}(a+b)}. ++ ++The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))}, ++@expr{@tfn{ln}(@tfn{e}^x)}, and @expr{@tfn{log10}(10^x)} to @expr{x} are also ++unsafe because of problems with principal values (although these ++simplifications are safe if @expr{x} is known to be real). ++ ++Common factors are cancelled from products on both sides of an ++equation, even if those factors may be zero: @expr{a x / b x} ++to @expr{a / b}. Such factors are never cancelled from ++inequalities: Even @kbd{a e} is not bold enough to reduce ++@expr{a x < b x} to @expr{a < b} (or @expr{a > b}, depending ++on whether you believe @expr{x} is positive or negative). ++The @kbd{a M /} command can be used to divide a factor out of ++both sides of an inequality. ++ ++@node Simplification of Units, , Unsafe Simplifications, Simplifying Formulas ++@subsection Simplification of Units ++ ++@noindent ++The simplifications described in this section are applied by the ++@kbd{u s} (@code{calc-simplify-units}) command. These are in addition ++to the regular @kbd{a s} (but not @kbd{a e}) simplifications described ++earlier. @xref{Basic Operations on Units}. ++ ++The variable @code{UnitSimpRules} contains rewrites to be applied by ++the @kbd{u s} command. These are applied in addition to @code{EvalRules} ++and @code{AlgSimpRules}. ++ ++Scalar mode is automatically put into effect when simplifying units. ++@xref{Matrix Mode}. ++ ++Sums @expr{a + b} involving units are simplified by extracting the ++units of @expr{a} as if by the @kbd{u x} command (call the result ++@expr{u_a}), then simplifying the expression @expr{b / u_a} ++using @kbd{u b} and @kbd{u s}. If the result has units then the sum ++is inconsistent and is left alone. Otherwise, it is rewritten ++in terms of the units @expr{u_a}. ++ ++If units auto-ranging mode is enabled, products or quotients in ++which the first argument is a number which is out of range for the ++leading unit are modified accordingly. ++ ++When cancelling and combining units in products and quotients, ++Calc accounts for unit names that differ only in the prefix letter. ++For example, @samp{2 km m} is simplified to @samp{2000 m^2}. ++However, compatible but different units like @code{ft} and @code{in} ++are not combined in this way. ++ ++Quotients @expr{a / b} are simplified in three additional ways. First, ++if @expr{b} is a number or a product beginning with a number, Calc ++computes the reciprocal of this number and moves it to the numerator. ++ ++Second, for each pair of unit names from the numerator and denominator ++of a quotient, if the units are compatible (e.g., they are both ++units of area) then they are replaced by the ratio between those ++units. For example, in @samp{3 s in N / kg cm} the units ++@samp{in / cm} will be replaced by @expr{2.54}. ++ ++Third, if the units in the quotient exactly cancel out, so that ++a @kbd{u b} command on the quotient would produce a dimensionless ++number for an answer, then the quotient simplifies to that number. ++ ++For powers and square roots, the ``unsafe'' simplifications ++@expr{(a b)^c} to @expr{a^c b^c}, @expr{(a/b)^c} to @expr{a^c / b^c}, ++and @expr{(a^b)^c} to ++@texline @math{a^{b c}} ++@infoline @expr{a^(b c)} ++are done if the powers are real numbers. (These are safe in the context ++of units because all numbers involved can reasonably be assumed to be ++real.) ++ ++Also, if a unit name is raised to a fractional power, and the ++base units in that unit name all occur to powers which are a ++multiple of the denominator of the power, then the unit name ++is expanded out into its base units, which can then be simplified ++according to the previous paragraph. For example, @samp{acre^1.5} ++is simplified by noting that @expr{1.5 = 3:2}, that @samp{acre} ++is defined in terms of @samp{m^2}, and that the 2 in the power of ++@code{m} is a multiple of 2 in @expr{3:2}. Thus, @code{acre^1.5} is ++replaced by approximately ++@texline @math{(4046 m^2)^{1.5}} ++@infoline @expr{(4046 m^2)^1.5}, ++which is then changed to ++@texline @math{4046^{1.5} \, (m^2)^{1.5}}, ++@infoline @expr{4046^1.5 (m^2)^1.5}, ++then to @expr{257440 m^3}. ++ ++The functions @code{float}, @code{frac}, @code{clean}, @code{abs}, ++as well as @code{floor} and the other integer truncation functions, ++applied to unit names or products or quotients involving units, are ++simplified. For example, @samp{round(1.6 in)} is changed to ++@samp{round(1.6) round(in)}; the lefthand term evaluates to 2, ++and the righthand term simplifies to @code{in}. ++ ++The functions @code{sin}, @code{cos}, and @code{tan} with arguments ++that have angular units like @code{rad} or @code{arcmin} are ++simplified by converting to base units (radians), then evaluating ++with the angular mode temporarily set to radians. ++ ++@node Polynomials, Calculus, Simplifying Formulas, Algebra ++@section Polynomials ++ ++A @dfn{polynomial} is a sum of terms which are coefficients times ++various powers of a ``base'' variable. For example, @expr{2 x^2 + 3 x - 4} ++is a polynomial in @expr{x}. Some formulas can be considered ++polynomials in several different variables: @expr{1 + 2 x + 3 y + 4 x y^2} ++is a polynomial in both @expr{x} and @expr{y}. Polynomial coefficients ++are often numbers, but they may in general be any formulas not ++involving the base variable. ++ ++@kindex a f ++@pindex calc-factor ++@tindex factor ++The @kbd{a f} (@code{calc-factor}) [@code{factor}] command factors a ++polynomial into a product of terms. For example, the polynomial ++@expr{x^3 + 2 x^2 + x} is factored into @samp{x*(x+1)^2}. As another ++example, @expr{a c + b d + b c + a d} is factored into the product ++@expr{(a + b) (c + d)}. ++ ++Calc currently has three algorithms for factoring. Formulas which are ++linear in several variables, such as the second example above, are ++merged according to the distributive law. Formulas which are ++polynomials in a single variable, with constant integer or fractional ++coefficients, are factored into irreducible linear and/or quadratic ++terms. The first example above factors into three linear terms ++(@expr{x}, @expr{x+1}, and @expr{x+1} again). Finally, formulas ++which do not fit the above criteria are handled by the algebraic ++rewrite mechanism. ++ ++Calc's polynomial factorization algorithm works by using the general ++root-finding command (@w{@kbd{a P}}) to solve for the roots of the ++polynomial. It then looks for roots which are rational numbers ++or complex-conjugate pairs, and converts these into linear and ++quadratic terms, respectively. Because it uses floating-point ++arithmetic, it may be unable to find terms that involve large ++integers (whose number of digits approaches the current precision). ++Also, irreducible factors of degree higher than quadratic are not ++found, and polynomials in more than one variable are not treated. ++(A more robust factorization algorithm may be included in a future ++version of Calc.) ++ ++@vindex FactorRules ++@ignore ++@starindex ++@end ignore ++@tindex thecoefs ++@ignore ++@starindex ++@end ignore ++@ignore ++@mindex @idots ++@end ignore ++@tindex thefactors ++The rewrite-based factorization method uses rules stored in the variable ++@code{FactorRules}. @xref{Rewrite Rules}, for a discussion of the ++operation of rewrite rules. The default @code{FactorRules} are able ++to factor quadratic forms symbolically into two linear terms, ++@expr{(a x + b) (c x + d)}. You can edit these rules to include other ++cases if you wish. To use the rules, Calc builds the formula ++@samp{thecoefs(x, [a, b, c, ...])} where @code{x} is the polynomial ++base variable and @code{a}, @code{b}, etc., are polynomial coefficients ++(which may be numbers or formulas). The constant term is written first, ++i.e., in the @code{a} position. When the rules complete, they should have ++changed the formula into the form @samp{thefactors(x, [f1, f2, f3, ...])} ++where each @code{fi} should be a factored term, e.g., @samp{x - ai}. ++Calc then multiplies these terms together to get the complete ++factored form of the polynomial. If the rules do not change the ++@code{thecoefs} call to a @code{thefactors} call, @kbd{a f} leaves the ++polynomial alone on the assumption that it is unfactorable. (Note that ++the function names @code{thecoefs} and @code{thefactors} are used only ++as placeholders; there are no actual Calc functions by those names.) ++ ++@kindex H a f ++@tindex factors ++The @kbd{H a f} [@code{factors}] command also factors a polynomial, ++but it returns a list of factors instead of an expression which is the ++product of the factors. Each factor is represented by a sub-vector ++of the factor, and the power with which it appears. For example, ++@expr{x^5 + x^4 - 33 x^3 + 63 x^2} factors to @expr{(x + 7) x^2 (x - 3)^2} ++in @kbd{a f}, or to @expr{[ [x, 2], [x+7, 1], [x-3, 2] ]} in @kbd{H a f}. ++If there is an overall numeric factor, it always comes first in the list. ++The functions @code{factor} and @code{factors} allow a second argument ++when written in algebraic form; @samp{factor(x,v)} factors @expr{x} with ++respect to the specific variable @expr{v}. The default is to factor with ++respect to all the variables that appear in @expr{x}. ++ ++@kindex a c ++@pindex calc-collect ++@tindex collect ++The @kbd{a c} (@code{calc-collect}) [@code{collect}] command rearranges a ++formula as a ++polynomial in a given variable, ordered in decreasing powers of that ++variable. For example, given @expr{1 + 2 x + 3 y + 4 x y^2} on ++the stack, @kbd{a c x} would produce @expr{(2 + 4 y^2) x + (1 + 3 y)}, ++and @kbd{a c y} would produce @expr{(4 x) y^2 + 3 y + (1 + 2 x)}. ++The polynomial will be expanded out using the distributive law as ++necessary: Collecting @expr{x} in @expr{(x - 1)^3} produces ++@expr{x^3 - 3 x^2 + 3 x - 1}. Terms not involving @expr{x} will ++not be expanded. ++ ++The ``variable'' you specify at the prompt can actually be any ++expression: @kbd{a c ln(x+1)} will collect together all terms multiplied ++by @samp{ln(x+1)} or integer powers thereof. If @samp{x} also appears ++in the formula in a context other than @samp{ln(x+1)}, @kbd{a c} will ++treat those occurrences as unrelated to @samp{ln(x+1)}, i.e., as constants. ++ ++@kindex a x ++@pindex calc-expand ++@tindex expand ++The @kbd{a x} (@code{calc-expand}) [@code{expand}] command expands an ++expression by applying the distributive law everywhere. It applies to ++products, quotients, and powers involving sums. By default, it fully ++distributes all parts of the expression. With a numeric prefix argument, ++the distributive law is applied only the specified number of times, then ++the partially expanded expression is left on the stack. ++ ++The @kbd{a x} and @kbd{j D} commands are somewhat redundant. Use ++@kbd{a x} if you want to expand all products of sums in your formula. ++Use @kbd{j D} if you want to expand a particular specified term of ++the formula. There is an exactly analogous correspondence between ++@kbd{a f} and @kbd{j M}. (The @kbd{j D} and @kbd{j M} commands ++also know many other kinds of expansions, such as ++@samp{exp(a + b) = exp(a) exp(b)}, which @kbd{a x} and @kbd{a f} ++do not do.) ++ ++Calc's automatic simplifications will sometimes reverse a partial ++expansion. For example, the first step in expanding @expr{(x+1)^3} is ++to write @expr{(x+1) (x+1)^2}. If @kbd{a x} stops there and tries ++to put this formula onto the stack, though, Calc will automatically ++simplify it back to @expr{(x+1)^3} form. The solution is to turn ++simplification off first (@pxref{Simplification Modes}), or to run ++@kbd{a x} without a numeric prefix argument so that it expands all ++the way in one step. ++ ++@kindex a a ++@pindex calc-apart ++@tindex apart ++The @kbd{a a} (@code{calc-apart}) [@code{apart}] command expands a ++rational function by partial fractions. A rational function is the ++quotient of two polynomials; @code{apart} pulls this apart into a ++sum of rational functions with simple denominators. In algebraic ++notation, the @code{apart} function allows a second argument that ++specifies which variable to use as the ``base''; by default, Calc ++chooses the base variable automatically. ++ ++@kindex a n ++@pindex calc-normalize-rat ++@tindex nrat ++The @kbd{a n} (@code{calc-normalize-rat}) [@code{nrat}] command ++attempts to arrange a formula into a quotient of two polynomials. ++For example, given @expr{1 + (a + b/c) / d}, the result would be ++@expr{(b + a c + c d) / c d}. The quotient is reduced, so that ++@kbd{a n} will simplify @expr{(x^2 + 2x + 1) / (x^2 - 1)} by dividing ++out the common factor @expr{x + 1}, yielding @expr{(x + 1) / (x - 1)}. ++ ++@kindex a \ ++@pindex calc-poly-div ++@tindex pdiv ++The @kbd{a \} (@code{calc-poly-div}) [@code{pdiv}] command divides ++two polynomials @expr{u} and @expr{v}, yielding a new polynomial ++@expr{q}. If several variables occur in the inputs, the inputs are ++considered multivariate polynomials. (Calc divides by the variable ++with the largest power in @expr{u} first, or, in the case of equal ++powers, chooses the variables in alphabetical order.) For example, ++dividing @expr{x^2 + 3 x + 2} by @expr{x + 2} yields @expr{x + 1}. ++The remainder from the division, if any, is reported at the bottom ++of the screen and is also placed in the Trail along with the quotient. ++ ++Using @code{pdiv} in algebraic notation, you can specify the particular ++variable to be used as the base: @code{pdiv(@var{a},@var{b},@var{x})}. ++If @code{pdiv} is given only two arguments (as is always the case with ++the @kbd{a \} command), then it does a multivariate division as outlined ++above. ++ ++@kindex a % ++@pindex calc-poly-rem ++@tindex prem ++The @kbd{a %} (@code{calc-poly-rem}) [@code{prem}] command divides ++two polynomials and keeps the remainder @expr{r}. The quotient ++@expr{q} is discarded. For any formulas @expr{a} and @expr{b}, the ++results of @kbd{a \} and @kbd{a %} satisfy @expr{a = q b + r}. ++(This is analogous to plain @kbd{\} and @kbd{%}, which compute the ++integer quotient and remainder from dividing two numbers.) ++ ++@kindex a / ++@kindex H a / ++@pindex calc-poly-div-rem ++@tindex pdivrem ++@tindex pdivide ++The @kbd{a /} (@code{calc-poly-div-rem}) [@code{pdivrem}] command ++divides two polynomials and reports both the quotient and the ++remainder as a vector @expr{[q, r]}. The @kbd{H a /} [@code{pdivide}] ++command divides two polynomials and constructs the formula ++@expr{q + r/b} on the stack. (Naturally if the remainder is zero, ++this will immediately simplify to @expr{q}.) ++ ++@kindex a g ++@pindex calc-poly-gcd ++@tindex pgcd ++The @kbd{a g} (@code{calc-poly-gcd}) [@code{pgcd}] command computes ++the greatest common divisor of two polynomials. (The GCD actually ++is unique only to within a constant multiplier; Calc attempts to ++choose a GCD which will be unsurprising.) For example, the @kbd{a n} ++command uses @kbd{a g} to take the GCD of the numerator and denominator ++of a quotient, then divides each by the result using @kbd{a \}. (The ++definition of GCD ensures that this division can take place without ++leaving a remainder.) ++ ++While the polynomials used in operations like @kbd{a /} and @kbd{a g} ++often have integer coefficients, this is not required. Calc can also ++deal with polynomials over the rationals or floating-point reals. ++Polynomials with modulo-form coefficients are also useful in many ++applications; if you enter @samp{(x^2 + 3 x - 1) mod 5}, Calc ++automatically transforms this into a polynomial over the field of ++integers mod 5: @samp{(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)}. ++ ++Congratulations and thanks go to Ove Ewerlid ++(@code{ewerlid@@mizar.DoCS.UU.SE}), who contributed many of the ++polynomial routines used in the above commands. ++ ++@xref{Decomposing Polynomials}, for several useful functions for ++extracting the individual coefficients of a polynomial. ++ ++@node Calculus, Solving Equations, Polynomials, Algebra ++@section Calculus ++ ++@noindent ++The following calculus commands do not automatically simplify their ++inputs or outputs using @code{calc-simplify}. You may find it helps ++to do this by hand by typing @kbd{a s} or @kbd{a e}. It may also help ++to use @kbd{a x} and/or @kbd{a c} to arrange a result in the most ++readable way. ++ ++@menu ++* Differentiation:: ++* Integration:: ++* Customizing the Integrator:: ++* Numerical Integration:: ++* Taylor Series:: ++@end menu ++ ++@node Differentiation, Integration, Calculus, Calculus ++@subsection Differentiation ++ ++@noindent ++@kindex a d ++@kindex H a d ++@pindex calc-derivative ++@tindex deriv ++@tindex tderiv ++The @kbd{a d} (@code{calc-derivative}) [@code{deriv}] command computes ++the derivative of the expression on the top of the stack with respect to ++some variable, which it will prompt you to enter. Normally, variables ++in the formula other than the specified differentiation variable are ++considered constant, i.e., @samp{deriv(y,x)} is reduced to zero. With ++the Hyperbolic flag, the @code{tderiv} (total derivative) operation is used ++instead, in which derivatives of variables are not reduced to zero ++unless those variables are known to be ``constant,'' i.e., independent ++of any other variables. (The built-in special variables like @code{pi} ++are considered constant, as are variables that have been declared ++@code{const}; @pxref{Declarations}.) ++ ++With a numeric prefix argument @var{n}, this command computes the ++@var{n}th derivative. ++ ++When working with trigonometric functions, it is best to switch to ++Radians mode first (with @w{@kbd{m r}}). The derivative of @samp{sin(x)} ++in degrees is @samp{(pi/180) cos(x)}, probably not the expected ++answer! ++ ++If you use the @code{deriv} function directly in an algebraic formula, ++you can write @samp{deriv(f,x,x0)} which represents the derivative ++of @expr{f} with respect to @expr{x}, evaluated at the point ++@texline @math{x=x_0}. ++@infoline @expr{x=x0}. ++ ++If the formula being differentiated contains functions which Calc does ++not know, the derivatives of those functions are produced by adding ++primes (apostrophe characters). For example, @samp{deriv(f(2x), x)} ++produces @samp{2 f'(2 x)}, where the function @code{f'} represents the ++derivative of @code{f}. ++ ++For functions you have defined with the @kbd{Z F} command, Calc expands ++the functions according to their defining formulas unless you have ++also defined @code{f'} suitably. For example, suppose we define ++@samp{sinc(x) = sin(x)/x} using @kbd{Z F}. If we then differentiate ++the formula @samp{sinc(2 x)}, the formula will be expanded to ++@samp{sin(2 x) / (2 x)} and differentiated. However, if we also ++define @samp{sinc'(x) = dsinc(x)}, say, then Calc will write the ++result as @samp{2 dsinc(2 x)}. @xref{Algebraic Definitions}. ++ ++For multi-argument functions @samp{f(x,y,z)}, the derivative with respect ++to the first argument is written @samp{f'(x,y,z)}; derivatives with ++respect to the other arguments are @samp{f'2(x,y,z)} and @samp{f'3(x,y,z)}. ++Various higher-order derivatives can be formed in the obvious way, e.g., ++@samp{f'@var{}'(x)} (the second derivative of @code{f}) or ++@samp{f'@var{}'2'3(x,y,z)} (@code{f} differentiated with respect to each ++argument once). ++ ++@node Integration, Customizing the Integrator, Differentiation, Calculus ++@subsection Integration ++ ++@noindent ++@kindex a i ++@pindex calc-integral ++@tindex integ ++The @kbd{a i} (@code{calc-integral}) [@code{integ}] command computes the ++indefinite integral of the expression on the top of the stack with ++respect to a prompted-for variable. The integrator is not guaranteed to ++work for all integrable functions, but it is able to integrate several ++large classes of formulas. In particular, any polynomial or rational ++function (a polynomial divided by a polynomial) is acceptable. ++(Rational functions don't have to be in explicit quotient form, however; ++@texline @math{x/(1+x^{-2})} ++@infoline @expr{x/(1+x^-2)} ++is not strictly a quotient of polynomials, but it is equivalent to ++@expr{x^3/(x^2+1)}, which is.) Also, square roots of terms involving ++@expr{x} and @expr{x^2} may appear in rational functions being ++integrated. Finally, rational functions involving trigonometric or ++hyperbolic functions can be integrated. ++ ++With an argument (@kbd{C-u a i}), this command will compute the definite ++integral of the expression on top of the stack. In this case, the ++command will again prompt for an integration variable, then prompt for a ++lower limit and an upper limit. ++ ++@ifnottex ++If you use the @code{integ} function directly in an algebraic formula, ++you can also write @samp{integ(f,x,v)} which expresses the resulting ++indefinite integral in terms of variable @code{v} instead of @code{x}. ++With four arguments, @samp{integ(f(x),x,a,b)} represents a definite ++integral from @code{a} to @code{b}. ++@end ifnottex ++@tex ++If you use the @code{integ} function directly in an algebraic formula, ++you can also write @samp{integ(f,x,v)} which expresses the resulting ++indefinite integral in terms of variable @code{v} instead of @code{x}. ++With four arguments, @samp{integ(f(x),x,a,b)} represents a definite ++integral $\int_a^b f(x) \, dx$. ++@end tex ++ ++Please note that the current implementation of Calc's integrator sometimes ++produces results that are significantly more complex than they need to ++be. For example, the integral Calc finds for ++@texline @math{1/(x+\sqrt{x^2+1})} ++@infoline @expr{1/(x+sqrt(x^2+1))} ++is several times more complicated than the answer Mathematica ++returns for the same input, although the two forms are numerically ++equivalent. Also, any indefinite integral should be considered to have ++an arbitrary constant of integration added to it, although Calc does not ++write an explicit constant of integration in its result. For example, ++Calc's solution for ++@texline @math{1/(1+\tan x)} ++@infoline @expr{1/(1+tan(x))} ++differs from the solution given in the @emph{CRC Math Tables} by a ++constant factor of ++@texline @math{\pi i / 2} ++@infoline @expr{pi i / 2}, ++due to a different choice of constant of integration. ++ ++The Calculator remembers all the integrals it has done. If conditions ++change in a way that would invalidate the old integrals, say, a switch ++from Degrees to Radians mode, then they will be thrown out. If you ++suspect this is not happening when it should, use the ++@code{calc-flush-caches} command; @pxref{Caches}. ++ ++@vindex IntegLimit ++Calc normally will pursue integration by substitution or integration by ++parts up to 3 nested times before abandoning an approach as fruitless. ++If the integrator is taking too long, you can lower this limit by storing ++a number (like 2) in the variable @code{IntegLimit}. (The @kbd{s I} ++command is a convenient way to edit @code{IntegLimit}.) If this variable ++has no stored value or does not contain a nonnegative integer, a limit ++of 3 is used. The lower this limit is, the greater the chance that Calc ++will be unable to integrate a function it could otherwise handle. Raising ++this limit allows the Calculator to solve more integrals, though the time ++it takes may grow exponentially. You can monitor the integrator's actions ++by creating an Emacs buffer called @code{*Trace*}. If such a buffer ++exists, the @kbd{a i} command will write a log of its actions there. ++ ++If you want to manipulate integrals in a purely symbolic way, you can ++set the integration nesting limit to 0 to prevent all but fast ++table-lookup solutions of integrals. You might then wish to define ++rewrite rules for integration by parts, various kinds of substitutions, ++and so on. @xref{Rewrite Rules}. ++ ++@node Customizing the Integrator, Numerical Integration, Integration, Calculus ++@subsection Customizing the Integrator ++ ++@noindent ++@vindex IntegRules ++Calc has two built-in rewrite rules called @code{IntegRules} and ++@code{IntegAfterRules} which you can edit to define new integration ++methods. @xref{Rewrite Rules}. At each step of the integration process, ++Calc wraps the current integrand in a call to the fictitious function ++@samp{integtry(@var{expr},@var{var})}, where @var{expr} is the ++integrand and @var{var} is the integration variable. If your rules ++rewrite this to be a plain formula (not a call to @code{integtry}), then ++Calc will use this formula as the integral of @var{expr}. For example, ++the rule @samp{integtry(mysin(x),x) := -mycos(x)} would define a rule to ++integrate a function @code{mysin} that acts like the sine function. ++Then, putting @samp{4 mysin(2y+1)} on the stack and typing @kbd{a i y} ++will produce the integral @samp{-2 mycos(2y+1)}. Note that Calc has ++automatically made various transformations on the integral to allow it ++to use your rule; integral tables generally give rules for ++@samp{mysin(a x + b)}, but you don't need to use this much generality ++in your @code{IntegRules}. ++ ++@cindex Exponential integral Ei(x) ++@ignore ++@starindex ++@end ignore ++@tindex Ei ++As a more serious example, the expression @samp{exp(x)/x} cannot be ++integrated in terms of the standard functions, so the ``exponential ++integral'' function ++@texline @math{{\rm Ei}(x)} ++@infoline @expr{Ei(x)} ++was invented to describe it. ++We can get Calc to do this integral in terms of a made-up @code{Ei} ++function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]} ++to @code{IntegRules}. Now entering @samp{exp(2x)/x} on the stack ++and typing @kbd{a i x} yields @samp{Ei(2 x)}. This new rule will ++work with Calc's various built-in integration methods (such as ++integration by substitution) to solve a variety of other problems ++involving @code{Ei}: For example, now Calc will also be able to ++integrate @samp{exp(exp(x))} and @samp{ln(ln(x))} (to get @samp{Ei(exp(x))} ++and @samp{x ln(ln(x)) - Ei(ln(x))}, respectively). ++ ++Your rule may do further integration by calling @code{integ}. For ++example, @samp{integtry(twice(u),x) := twice(integ(u))} allows Calc ++to integrate @samp{twice(sin(x))} to get @samp{twice(-cos(x))}. ++Note that @code{integ} was called with only one argument. This notation ++is allowed only within @code{IntegRules}; it means ``integrate this ++with respect to the same integration variable.'' If Calc is unable ++to integrate @code{u}, the integration that invoked @code{IntegRules} ++also fails. Thus integrating @samp{twice(f(x))} fails, returning the ++unevaluated integral @samp{integ(twice(f(x)), x)}. It is still valid ++to call @code{integ} with two or more arguments, however; in this case, ++if @code{u} is not integrable, @code{twice} itself will still be ++integrated: If the above rule is changed to @samp{... := twice(integ(u,x))}, ++then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}. ++ ++If a rule instead produces the formula @samp{integsubst(@var{sexpr}, ++@var{svar})}, either replacing the top-level @code{integtry} call or ++nested anywhere inside the expression, then Calc will apply the ++substitution @samp{@var{u} = @var{sexpr}(@var{svar})} to try to ++integrate the original @var{expr}. For example, the rule ++@samp{sqrt(a) := integsubst(sqrt(x),x)} says that if Calc ever finds ++a square root in the integrand, it should attempt the substitution ++@samp{u = sqrt(x)}. (This particular rule is unnecessary because ++Calc always tries ``obvious'' substitutions where @var{sexpr} actually ++appears in the integrand.) The variable @var{svar} may be the same ++as the @var{var} that appeared in the call to @code{integtry}, but ++it need not be. ++ ++When integrating according to an @code{integsubst}, Calc uses the ++equation solver to find the inverse of @var{sexpr} (if the integrand ++refers to @var{var} anywhere except in subexpressions that exactly ++match @var{sexpr}). It uses the differentiator to find the derivative ++of @var{sexpr} and/or its inverse (it has two methods that use one ++derivative or the other). You can also specify these items by adding ++extra arguments to the @code{integsubst} your rules construct; the ++general form is @samp{integsubst(@var{sexpr}, @var{svar}, @var{sinv}, ++@var{sprime})}, where @var{sinv} is the inverse of @var{sexpr} (still ++written as a function of @var{svar}), and @var{sprime} is the ++derivative of @var{sexpr} with respect to @var{svar}. If you don't ++specify these things, and Calc is not able to work them out on its ++own with the information it knows, then your substitution rule will ++work only in very specific, simple cases. ++ ++Calc applies @code{IntegRules} as if by @kbd{C-u 1 a r IntegRules}; ++in other words, Calc stops rewriting as soon as any rule in your rule ++set succeeds. (If it weren't for this, the @samp{integsubst(sqrt(x),x)} ++example above would keep on adding layers of @code{integsubst} calls ++forever!) ++ ++@vindex IntegSimpRules ++Another set of rules, stored in @code{IntegSimpRules}, are applied ++every time the integrator uses @kbd{a s} to simplify an intermediate ++result. For example, putting the rule @samp{twice(x) := 2 x} into ++@code{IntegSimpRules} would tell Calc to convert the @code{twice} ++function into a form it knows whenever integration is attempted. ++ ++One more way to influence the integrator is to define a function with ++the @kbd{Z F} command (@pxref{Algebraic Definitions}). Calc's ++integrator automatically expands such functions according to their ++defining formulas, even if you originally asked for the function to ++be left unevaluated for symbolic arguments. (Certain other Calc ++systems, such as the differentiator and the equation solver, also ++do this.) ++ ++@vindex IntegAfterRules ++Sometimes Calc is able to find a solution to your integral, but it ++expresses the result in a way that is unnecessarily complicated. If ++this happens, you can either use @code{integsubst} as described ++above to try to hint at a more direct path to the desired result, or ++you can use @code{IntegAfterRules}. This is an extra rule set that ++runs after the main integrator returns its result; basically, Calc does ++an @kbd{a r IntegAfterRules} on the result before showing it to you. ++(It also does an @kbd{a s}, without @code{IntegSimpRules}, after that ++to further simplify the result.) For example, Calc's integrator ++sometimes produces expressions of the form @samp{ln(1+x) - ln(1-x)}; ++the default @code{IntegAfterRules} rewrite this into the more readable ++form @samp{2 arctanh(x)}. Note that, unlike @code{IntegRules}, ++@code{IntegSimpRules} and @code{IntegAfterRules} are applied any number ++of times until no further changes are possible. Rewriting by ++@code{IntegAfterRules} occurs only after the main integrator has ++finished, not at every step as for @code{IntegRules} and ++@code{IntegSimpRules}. ++ ++@node Numerical Integration, Taylor Series, Customizing the Integrator, Calculus ++@subsection Numerical Integration ++ ++@noindent ++@kindex a I ++@pindex calc-num-integral ++@tindex ninteg ++If you want a purely numerical answer to an integration problem, you can ++use the @kbd{a I} (@code{calc-num-integral}) [@code{ninteg}] command. This ++command prompts for an integration variable, a lower limit, and an ++upper limit. Except for the integration variable, all other variables ++that appear in the integrand formula must have stored values. (A stored ++value, if any, for the integration variable itself is ignored.) ++ ++Numerical integration works by evaluating your formula at many points in ++the specified interval. Calc uses an ``open Romberg'' method; this means ++that it does not evaluate the formula actually at the endpoints (so that ++it is safe to integrate @samp{sin(x)/x} from zero, for example). Also, ++the Romberg method works especially well when the function being ++integrated is fairly smooth. If the function is not smooth, Calc will ++have to evaluate it at quite a few points before it can accurately ++determine the value of the integral. ++ ++Integration is much faster when the current precision is small. It is ++best to set the precision to the smallest acceptable number of digits ++before you use @kbd{a I}. If Calc appears to be taking too long, press ++@kbd{C-g} to halt it and try a lower precision. If Calc still appears ++to need hundreds of evaluations, check to make sure your function is ++well-behaved in the specified interval. ++ ++It is possible for the lower integration limit to be @samp{-inf} (minus ++infinity). Likewise, the upper limit may be plus infinity. Calc ++internally transforms the integral into an equivalent one with finite ++limits. However, integration to or across singularities is not supported: ++The integral of @samp{1/sqrt(x)} from 0 to 1 exists (it can be found ++by Calc's symbolic integrator, for example), but @kbd{a I} will fail ++because the integrand goes to infinity at one of the endpoints. ++ ++@node Taylor Series, , Numerical Integration, Calculus ++@subsection Taylor Series ++ ++@noindent ++@kindex a t ++@pindex calc-taylor ++@tindex taylor ++The @kbd{a t} (@code{calc-taylor}) [@code{taylor}] command computes a ++power series expansion or Taylor series of a function. You specify the ++variable and the desired number of terms. You may give an expression of ++the form @samp{@var{var} = @var{a}} or @samp{@var{var} - @var{a}} instead ++of just a variable to produce a Taylor expansion about the point @var{a}. ++You may specify the number of terms with a numeric prefix argument; ++otherwise the command will prompt you for the number of terms. Note that ++many series expansions have coefficients of zero for some terms, so you ++may appear to get fewer terms than you asked for. ++ ++If the @kbd{a i} command is unable to find a symbolic integral for a ++function, you can get an approximation by integrating the function's ++Taylor series. ++ ++@node Solving Equations, Numerical Solutions, Calculus, Algebra ++@section Solving Equations ++ ++@noindent ++@kindex a S ++@pindex calc-solve-for ++@tindex solve ++@cindex Equations, solving ++@cindex Solving equations ++The @kbd{a S} (@code{calc-solve-for}) [@code{solve}] command rearranges ++an equation to solve for a specific variable. An equation is an ++expression of the form @expr{L = R}. For example, the command @kbd{a S x} ++will rearrange @expr{y = 3x + 6} to the form, @expr{x = y/3 - 2}. If the ++input is not an equation, it is treated like an equation of the ++form @expr{X = 0}. ++ ++This command also works for inequalities, as in @expr{y < 3x + 6}. ++Some inequalities cannot be solved where the analogous equation could ++be; for example, solving ++@texline @math{a < b \, c} ++@infoline @expr{a < b c} ++for @expr{b} is impossible ++without knowing the sign of @expr{c}. In this case, @kbd{a S} will ++produce the result ++@texline @math{b \mathbin{\hbox{\code{!=}}} a/c} ++@infoline @expr{b != a/c} ++(using the not-equal-to operator) to signify that the direction of the ++inequality is now unknown. The inequality ++@texline @math{a \le b \, c} ++@infoline @expr{a <= b c} ++is not even partially solved. @xref{Declarations}, for a way to tell ++Calc that the signs of the variables in a formula are in fact known. ++ ++Two useful commands for working with the result of @kbd{a S} are ++@kbd{a .} (@pxref{Logical Operations}), which converts @expr{x = y/3 - 2} ++to @expr{y/3 - 2}, and @kbd{s l} (@pxref{Let Command}) which evaluates ++another formula with @expr{x} set equal to @expr{y/3 - 2}. ++ ++@menu ++* Multiple Solutions:: ++* Solving Systems of Equations:: ++* Decomposing Polynomials:: ++@end menu ++ ++@node Multiple Solutions, Solving Systems of Equations, Solving Equations, Solving Equations ++@subsection Multiple Solutions ++ ++@noindent ++@kindex H a S ++@tindex fsolve ++Some equations have more than one solution. The Hyperbolic flag ++(@code{H a S}) [@code{fsolve}] tells the solver to report the fully ++general family of solutions. It will invent variables @code{n1}, ++@code{n2}, @dots{}, which represent independent arbitrary integers, and ++@code{s1}, @code{s2}, @dots{}, which represent independent arbitrary ++signs (either @mathit{+1} or @mathit{-1}). If you don't use the Hyperbolic ++flag, Calc will use zero in place of all arbitrary integers, and plus ++one in place of all arbitrary signs. Note that variables like @code{n1} ++and @code{s1} are not given any special interpretation in Calc except by ++the equation solver itself. As usual, you can use the @w{@kbd{s l}} ++(@code{calc-let}) command to obtain solutions for various actual values ++of these variables. ++ ++For example, @kbd{' x^2 = y @key{RET} H a S x @key{RET}} solves to ++get @samp{x = s1 sqrt(y)}, indicating that the two solutions to the ++equation are @samp{sqrt(y)} and @samp{-sqrt(y)}. Another way to ++think about it is that the square-root operation is really a ++two-valued function; since every Calc function must return a ++single result, @code{sqrt} chooses to return the positive result. ++Then @kbd{H a S} doctors this result using @code{s1} to indicate ++the full set of possible values of the mathematical square-root. ++ ++There is a similar phenomenon going the other direction: Suppose ++we solve @samp{sqrt(y) = x} for @code{y}. Calc squares both sides ++to get @samp{y = x^2}. This is correct, except that it introduces ++some dubious solutions. Consider solving @samp{sqrt(y) = -3}: ++Calc will report @expr{y = 9} as a valid solution, which is true ++in the mathematical sense of square-root, but false (there is no ++solution) for the actual Calc positive-valued @code{sqrt}. This ++happens for both @kbd{a S} and @kbd{H a S}. ++ ++@cindex @code{GenCount} variable ++@vindex GenCount ++@ignore ++@starindex ++@end ignore ++@tindex an ++@ignore ++@starindex ++@end ignore ++@tindex as ++If you store a positive integer in the Calc variable @code{GenCount}, ++then Calc will generate formulas of the form @samp{as(@var{n})} for ++arbitrary signs, and @samp{an(@var{n})} for arbitrary integers, ++where @var{n} represents successive values taken by incrementing ++@code{GenCount} by one. While the normal arbitrary sign and ++integer symbols start over at @code{s1} and @code{n1} with each ++new Calc command, the @code{GenCount} approach will give each ++arbitrary value a name that is unique throughout the entire Calc ++session. Also, the arbitrary values are function calls instead ++of variables, which is advantageous in some cases. For example, ++you can make a rewrite rule that recognizes all arbitrary signs ++using a pattern like @samp{as(n)}. The @kbd{s l} command only works ++on variables, but you can use the @kbd{a b} (@code{calc-substitute}) ++command to substitute actual values for function calls like @samp{as(3)}. ++ ++The @kbd{s G} (@code{calc-edit-GenCount}) command is a convenient ++way to create or edit this variable. Press @kbd{C-c C-c} to finish. ++ ++If you have not stored a value in @code{GenCount}, or if the value ++in that variable is not a positive integer, the regular ++@code{s1}/@code{n1} notation is used. ++ ++@kindex I a S ++@kindex H I a S ++@tindex finv ++@tindex ffinv ++With the Inverse flag, @kbd{I a S} [@code{finv}] treats the expression ++on top of the stack as a function of the specified variable and solves ++to find the inverse function, written in terms of the same variable. ++For example, @kbd{I a S x} inverts @expr{2x + 6} to @expr{x/2 - 3}. ++You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a ++fully general inverse, as described above. ++ ++@kindex a P ++@pindex calc-poly-roots ++@tindex roots ++Some equations, specifically polynomials, have a known, finite number ++of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}] ++command uses @kbd{H a S} to solve an equation in general form, then, for ++all arbitrary-sign variables like @code{s1}, and all arbitrary-integer ++variables like @code{n1} for which @code{n1} only usefully varies over ++a finite range, it expands these variables out to all their possible ++values. The results are collected into a vector, which is returned. ++For example, @samp{roots(x^4 = 1, x)} returns the four solutions ++@samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree ++polynomial will always have @var{n} roots on the complex plane. ++(If you have given a @code{real} declaration for the solution ++variable, then only the real-valued solutions, if any, will be ++reported; @pxref{Declarations}.) ++ ++Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver ++symbolic solutions if the polynomial has symbolic coefficients. Also ++note that Calc's solver is not able to get exact symbolic solutions ++to all polynomials. Polynomials containing powers up to @expr{x^4} ++can always be solved exactly; polynomials of higher degree sometimes ++can be: @expr{x^6 + x^3 + 1} is converted to @expr{(x^3)^2 + (x^3) + 1}, ++which can be solved for @expr{x^3} using the quadratic equation, and then ++for @expr{x} by taking cube roots. But in many cases, like ++@expr{x^6 + x + 1}, Calc does not know how to rewrite the polynomial ++into a form it can solve. The @kbd{a P} command can still deliver a ++list of numerical roots, however, provided that Symbolic mode (@kbd{m s}) ++is not turned on. (If you work with Symbolic mode on, recall that the ++@kbd{N} (@code{calc-eval-num}) key is a handy way to reevaluate the ++formula on the stack with Symbolic mode temporarily off.) Naturally, ++@kbd{a P} can only provide numerical roots if the polynomial coefficients ++are all numbers (real or complex). ++ ++@node Solving Systems of Equations, Decomposing Polynomials, Multiple Solutions, Solving Equations ++@subsection Solving Systems of Equations ++ ++@noindent ++@cindex Systems of equations, symbolic ++You can also use the commands described above to solve systems of ++simultaneous equations. Just create a vector of equations, then ++specify a vector of variables for which to solve. (You can omit ++the surrounding brackets when entering the vector of variables ++at the prompt.) ++ ++For example, putting @samp{[x + y = a, x - y = b]} on the stack ++and typing @kbd{a S x,y @key{RET}} produces the vector of solutions ++@samp{[x = a - (a-b)/2, y = (a-b)/2]}. The result vector will ++have the same length as the variables vector, and the variables ++will be listed in the same order there. Note that the solutions ++are not always simplified as far as possible; the solution for ++@expr{x} here could be improved by an application of the @kbd{a n} ++command. ++ ++Calc's algorithm works by trying to eliminate one variable at a ++time by solving one of the equations for that variable and then ++substituting into the other equations. Calc will try all the ++possibilities, but you can speed things up by noting that Calc ++first tries to eliminate the first variable with the first ++equation, then the second variable with the second equation, ++and so on. It also helps to put the simpler (e.g., more linear) ++equations toward the front of the list. Calc's algorithm will ++solve any system of linear equations, and also many kinds of ++nonlinear systems. ++ ++@ignore ++@starindex ++@end ignore ++@tindex elim ++Normally there will be as many variables as equations. If you ++give fewer variables than equations (an ``over-determined'' system ++of equations), Calc will find a partial solution. For example, ++typing @kbd{a S y @key{RET}} with the above system of equations ++would produce @samp{[y = a - x]}. There are now several ways to ++express this solution in terms of the original variables; Calc uses ++the first one that it finds. You can control the choice by adding ++variable specifiers of the form @samp{elim(@var{v})} to the ++variables list. This says that @var{v} should be eliminated from ++the equations; the variable will not appear at all in the solution. ++For example, typing @kbd{a S y,elim(x)} would yield ++@samp{[y = a - (b+a)/2]}. ++ ++If the variables list contains only @code{elim} specifiers, ++Calc simply eliminates those variables from the equations ++and then returns the resulting set of equations. For example, ++@kbd{a S elim(x)} produces @samp{[a - 2 y = b]}. Every variable ++eliminated will reduce the number of equations in the system ++by one. ++ ++Again, @kbd{a S} gives you one solution to the system of ++equations. If there are several solutions, you can use @kbd{H a S} ++to get a general family of solutions, or, if there is a finite ++number of solutions, you can use @kbd{a P} to get a list. (In ++the latter case, the result will take the form of a matrix where ++the rows are different solutions and the columns correspond to the ++variables you requested.) ++ ++Another way to deal with certain kinds of overdetermined systems of ++equations is the @kbd{a F} command, which does least-squares fitting ++to satisfy the equations. @xref{Curve Fitting}. ++ ++@node Decomposing Polynomials, , Solving Systems of Equations, Solving Equations ++@subsection Decomposing Polynomials ++ ++@noindent ++@ignore ++@starindex ++@end ignore ++@tindex poly ++The @code{poly} function takes a polynomial and a variable as ++arguments, and returns a vector of polynomial coefficients (constant ++coefficient first). For example, @samp{poly(x^3 + 2 x, x)} returns ++@expr{[0, 2, 0, 1]}. If the input is not a polynomial in @expr{x}, ++the call to @code{poly} is left in symbolic form. If the input does ++not involve the variable @expr{x}, the input is returned in a list ++of length one, representing a polynomial with only a constant ++coefficient. The call @samp{poly(x, x)} returns the vector @expr{[0, 1]}. ++The last element of the returned vector is guaranteed to be nonzero; ++note that @samp{poly(0, x)} returns the empty vector @expr{[]}. ++Note also that @expr{x} may actually be any formula; for example, ++@samp{poly(sin(x)^2 - sin(x) + 3, sin(x))} returns @expr{[3, -1, 1]}. ++ ++@cindex Coefficients of polynomial ++@cindex Degree of polynomial ++To get the @expr{x^k} coefficient of polynomial @expr{p}, use ++@samp{poly(p, x)_(k+1)}. To get the degree of polynomial @expr{p}, ++use @samp{vlen(poly(p, x)) - 1}. For example, @samp{poly((x+1)^4, x)} ++returns @samp{[1, 4, 6, 4, 1]}, so @samp{poly((x+1)^4, x)_(2+1)} ++gives the @expr{x^2} coefficient of this polynomial, 6. ++ ++@ignore ++@starindex ++@end ignore ++@tindex gpoly ++One important feature of the solver is its ability to recognize ++formulas which are ``essentially'' polynomials. This ability is ++made available to the user through the @code{gpoly} function, which ++is used just like @code{poly}: @samp{gpoly(@var{expr}, @var{var})}. ++If @var{expr} is a polynomial in some term which includes @var{var}, then ++this function will return a vector @samp{[@var{x}, @var{c}, @var{a}]} ++where @var{x} is the term that depends on @var{var}, @var{c} is a ++vector of polynomial coefficients (like the one returned by @code{poly}), ++and @var{a} is a multiplier which is usually 1. Basically, ++@samp{@var{expr} = @var{a}*(@var{c}_1 + @var{c}_2 @var{x} + ++@var{c}_3 @var{x}^2 + ...)}. The last element of @var{c} is ++guaranteed to be non-zero, and @var{c} will not equal @samp{[1]} ++(i.e., the trivial decomposition @var{expr} = @var{x} is not ++considered a polynomial). One side effect is that @samp{gpoly(x, x)} ++and @samp{gpoly(6, x)}, both of which might be expected to recognize ++their arguments as polynomials, will not because the decomposition ++is considered trivial. ++ ++For example, @samp{gpoly((x-2)^2, x)} returns @samp{[x, [4, -4, 1], 1]}, ++since the expanded form of this polynomial is @expr{4 - 4 x + x^2}. ++ ++The term @var{x} may itself be a polynomial in @var{var}. This is ++done to reduce the size of the @var{c} vector. For example, ++@samp{gpoly(x^4 + x^2 - 1, x)} returns @samp{[x^2, [-1, 1, 1], 1]}, ++since a quadratic polynomial in @expr{x^2} is easier to solve than ++a quartic polynomial in @expr{x}. ++ ++A few more examples of the kinds of polynomials @code{gpoly} can ++discover: ++ ++@smallexample ++sin(x) - 1 [sin(x), [-1, 1], 1] ++x + 1/x - 1 [x, [1, -1, 1], 1/x] ++x + 1/x [x^2, [1, 1], 1/x] ++x^3 + 2 x [x^2, [2, 1], x] ++x + x^2:3 + sqrt(x) [x^1:6, [1, 1, 0, 1], x^1:2] ++x^(2a) + 2 x^a + 5 [x^a, [5, 2, 1], 1] ++(exp(-x) + exp(x)) / 2 [e^(2 x), [0.5, 0.5], e^-x] ++@end smallexample ++ ++The @code{poly} and @code{gpoly} functions accept a third integer argument ++which specifies the largest degree of polynomial that is acceptable. ++If this is @expr{n}, then only @var{c} vectors of length @expr{n+1} ++or less will be returned. Otherwise, the @code{poly} or @code{gpoly} ++call will remain in symbolic form. For example, the equation solver ++can handle quartics and smaller polynomials, so it calls ++@samp{gpoly(@var{expr}, @var{var}, 4)} to discover whether @var{expr} ++can be treated by its linear, quadratic, cubic, or quartic formulas. ++ ++@ignore ++@starindex ++@end ignore ++@tindex pdeg ++The @code{pdeg} function computes the degree of a polynomial; ++@samp{pdeg(p,x)} is the highest power of @code{x} that appears in ++@code{p}. This is the same as @samp{vlen(poly(p,x))-1}, but is ++much more efficient. If @code{p} is constant with respect to @code{x}, ++then @samp{pdeg(p,x) = 0}. If @code{p} is not a polynomial in @code{x} ++(e.g., @samp{pdeg(2 cos(x), x)}, the function remains unevaluated. ++It is possible to omit the second argument @code{x}, in which case ++@samp{pdeg(p)} returns the highest total degree of any term of the ++polynomial, counting all variables that appear in @code{p}. Note ++that @code{pdeg(c) = pdeg(c,x) = 0} for any nonzero constant @code{c}; ++the degree of the constant zero is considered to be @code{-inf} ++(minus infinity). ++ ++@ignore ++@starindex ++@end ignore ++@tindex plead ++The @code{plead} function finds the leading term of a polynomial. ++Thus @samp{plead(p,x)} is equivalent to @samp{poly(p,x)_vlen(poly(p,x))}, ++though again more efficient. In particular, @samp{plead((2x+1)^10, x)} ++returns 1024 without expanding out the list of coefficients. The ++value of @code{plead(p,x)} will be zero only if @expr{p = 0}. ++ ++@ignore ++@starindex ++@end ignore ++@tindex pcont ++The @code{pcont} function finds the @dfn{content} of a polynomial. This ++is the greatest common divisor of all the coefficients of the polynomial. ++With two arguments, @code{pcont(p,x)} effectively uses @samp{poly(p,x)} ++to get a list of coefficients, then uses @code{pgcd} (the polynomial ++GCD function) to combine these into an answer. For example, ++@samp{pcont(4 x y^2 + 6 x^2 y, x)} is @samp{2 y}. The content is ++basically the ``biggest'' polynomial that can be divided into @code{p} ++exactly. The sign of the content is the same as the sign of the leading ++coefficient. ++ ++With only one argument, @samp{pcont(p)} computes the numerical ++content of the polynomial, i.e., the @code{gcd} of the numerical ++coefficients of all the terms in the formula. Note that @code{gcd} ++is defined on rational numbers as well as integers; it computes ++the @code{gcd} of the numerators and the @code{lcm} of the ++denominators. Thus @samp{pcont(4:3 x y^2 + 6 x^2 y)} returns 2:3. ++Dividing the polynomial by this number will clear all the ++denominators, as well as dividing by any common content in the ++numerators. The numerical content of a polynomial is negative only ++if all the coefficients in the polynomial are negative. ++ ++@ignore ++@starindex ++@end ignore ++@tindex pprim ++The @code{pprim} function finds the @dfn{primitive part} of a ++polynomial, which is simply the polynomial divided (using @code{pdiv} ++if necessary) by its content. If the input polynomial has rational ++coefficients, the result will have integer coefficients in simplest ++terms. ++ ++@node Numerical Solutions, Curve Fitting, Solving Equations, Algebra ++@section Numerical Solutions ++ ++@noindent ++Not all equations can be solved symbolically. The commands in this ++section use numerical algorithms that can find a solution to a specific ++instance of an equation to any desired accuracy. Note that the ++numerical commands are slower than their algebraic cousins; it is a ++good idea to try @kbd{a S} before resorting to these commands. ++ ++(@xref{Curve Fitting}, for some other, more specialized, operations ++on numerical data.) ++ ++@menu ++* Root Finding:: ++* Minimization:: ++* Numerical Systems of Equations:: ++@end menu ++ ++@node Root Finding, Minimization, Numerical Solutions, Numerical Solutions ++@subsection Root Finding ++ ++@noindent ++@kindex a R ++@pindex calc-find-root ++@tindex root ++@cindex Newton's method ++@cindex Roots of equations ++@cindex Numerical root-finding ++The @kbd{a R} (@code{calc-find-root}) [@code{root}] command finds a ++numerical solution (or @dfn{root}) of an equation. (This command treats ++inequalities the same as equations. If the input is any other kind ++of formula, it is interpreted as an equation of the form @expr{X = 0}.) ++ ++The @kbd{a R} command requires an initial guess on the top of the ++stack, and a formula in the second-to-top position. It prompts for a ++solution variable, which must appear in the formula. All other variables ++that appear in the formula must have assigned values, i.e., when ++a value is assigned to the solution variable and the formula is ++evaluated with @kbd{=}, it should evaluate to a number. Any assigned ++value for the solution variable itself is ignored and unaffected by ++this command. ++ ++When the command completes, the initial guess is replaced on the stack ++by a vector of two numbers: The value of the solution variable that ++solves the equation, and the difference between the lefthand and ++righthand sides of the equation at that value. Ordinarily, the second ++number will be zero or very nearly zero. (Note that Calc uses a ++slightly higher precision while finding the root, and thus the second ++number may be slightly different from the value you would compute from ++the equation yourself.) ++ ++The @kbd{v h} (@code{calc-head}) command is a handy way to extract ++the first element of the result vector, discarding the error term. ++ ++The initial guess can be a real number, in which case Calc searches ++for a real solution near that number, or a complex number, in which ++case Calc searches the whole complex plane near that number for a ++solution, or it can be an interval form which restricts the search ++to real numbers inside that interval. ++ ++Calc tries to use @kbd{a d} to take the derivative of the equation. ++If this succeeds, it uses Newton's method. If the equation is not ++differentiable Calc uses a bisection method. (If Newton's method ++appears to be going astray, Calc switches over to bisection if it ++can, or otherwise gives up. In this case it may help to try again ++with a slightly different initial guess.) If the initial guess is a ++complex number, the function must be differentiable. ++ ++If the formula (or the difference between the sides of an equation) ++is negative at one end of the interval you specify and positive at ++the other end, the root finder is guaranteed to find a root. ++Otherwise, Calc subdivides the interval into small parts looking for ++positive and negative values to bracket the root. When your guess is ++an interval, Calc will not look outside that interval for a root. ++ ++@kindex H a R ++@tindex wroot ++The @kbd{H a R} [@code{wroot}] command is similar to @kbd{a R}, except ++that if the initial guess is an interval for which the function has ++the same sign at both ends, then rather than subdividing the interval ++Calc attempts to widen it to enclose a root. Use this mode if ++you are not sure if the function has a root in your interval. ++ ++If the function is not differentiable, and you give a simple number ++instead of an interval as your initial guess, Calc uses this widening ++process even if you did not type the Hyperbolic flag. (If the function ++@emph{is} differentiable, Calc uses Newton's method which does not ++require a bounding interval in order to work.) ++ ++If Calc leaves the @code{root} or @code{wroot} function in symbolic ++form on the stack, it will normally display an explanation for why ++no root was found. If you miss this explanation, press @kbd{w} ++(@code{calc-why}) to get it back. ++ ++@node Minimization, Numerical Systems of Equations, Root Finding, Numerical Solutions ++@subsection Minimization ++ ++@noindent ++@kindex a N ++@kindex H a N ++@kindex a X ++@kindex H a X ++@pindex calc-find-minimum ++@pindex calc-find-maximum ++@tindex minimize ++@tindex maximize ++@cindex Minimization, numerical ++The @kbd{a N} (@code{calc-find-minimum}) [@code{minimize}] command ++finds a minimum value for a formula. It is very similar in operation ++to @kbd{a R} (@code{calc-find-root}): You give the formula and an initial ++guess on the stack, and are prompted for the name of a variable. The guess ++may be either a number near the desired minimum, or an interval enclosing ++the desired minimum. The function returns a vector containing the ++value of the variable which minimizes the formula's value, along ++with the minimum value itself. ++ ++Note that this command looks for a @emph{local} minimum. Many functions ++have more than one minimum; some, like ++@texline @math{x \sin x}, ++@infoline @expr{x sin(x)}, ++have infinitely many. In fact, there is no easy way to define the ++``global'' minimum of ++@texline @math{x \sin x} ++@infoline @expr{x sin(x)} ++but Calc can still locate any particular local minimum ++for you. Calc basically goes downhill from the initial guess until it ++finds a point at which the function's value is greater both to the left ++and to the right. Calc does not use derivatives when minimizing a function. ++ ++If your initial guess is an interval and it looks like the minimum ++occurs at one or the other endpoint of the interval, Calc will return ++that endpoint only if that endpoint is closed; thus, minimizing @expr{17 x} ++over @expr{[2..3]} will return @expr{[2, 38]}, but minimizing over ++@expr{(2..3]} would report no minimum found. In general, you should ++use closed intervals to find literally the minimum value in that ++range of @expr{x}, or open intervals to find the local minimum, if ++any, that happens to lie in that range. ++ ++Most functions are smooth and flat near their minimum values. Because ++of this flatness, if the current precision is, say, 12 digits, the ++variable can only be determined meaningfully to about six digits. Thus ++you should set the precision to twice as many digits as you need in your ++answer. ++ ++@ignore ++@mindex wmin@idots ++@end ignore ++@tindex wminimize ++@ignore ++@mindex wmax@idots ++@end ignore ++@tindex wmaximize ++The @kbd{H a N} [@code{wminimize}] command, analogously to @kbd{H a R}, ++expands the guess interval to enclose a minimum rather than requiring ++that the minimum lie inside the interval you supply. ++ ++The @kbd{a X} (@code{calc-find-maximum}) [@code{maximize}] and ++@kbd{H a X} [@code{wmaximize}] commands effectively minimize the ++negative of the formula you supply. ++ ++The formula must evaluate to a real number at all points inside the ++interval (or near the initial guess if the guess is a number). If ++the initial guess is a complex number the variable will be minimized ++over the complex numbers; if it is real or an interval it will ++be minimized over the reals. ++ ++@node Numerical Systems of Equations, , Minimization, Numerical Solutions ++@subsection Systems of Equations ++ ++@noindent ++@cindex Systems of equations, numerical ++The @kbd{a R} command can also solve systems of equations. In this ++case, the equation should instead be a vector of equations, the ++guess should instead be a vector of numbers (intervals are not ++supported), and the variable should be a vector of variables. You ++can omit the brackets while entering the list of variables. Each ++equation must be differentiable by each variable for this mode to ++work. The result will be a vector of two vectors: The variable ++values that solved the system of equations, and the differences ++between the sides of the equations with those variable values. ++There must be the same number of equations as variables. Since ++only plain numbers are allowed as guesses, the Hyperbolic flag has ++no effect when solving a system of equations. ++ ++It is also possible to minimize over many variables with @kbd{a N} ++(or maximize with @kbd{a X}). Once again the variable name should ++be replaced by a vector of variables, and the initial guess should ++be an equal-sized vector of initial guesses. But, unlike the case of ++multidimensional @kbd{a R}, the formula being minimized should ++still be a single formula, @emph{not} a vector. Beware that ++multidimensional minimization is currently @emph{very} slow. ++ ++@node Curve Fitting, Summations, Numerical Solutions, Algebra ++@section Curve Fitting ++ ++@noindent ++The @kbd{a F} command fits a set of data to a @dfn{model formula}, ++such as @expr{y = m x + b} where @expr{m} and @expr{b} are parameters ++to be determined. For a typical set of measured data there will be ++no single @expr{m} and @expr{b} that exactly fit the data; in this ++case, Calc chooses values of the parameters that provide the closest ++possible fit. The model formula can be entered in various ways after ++the key sequence @kbd{a F} is pressed. ++ ++If the letter @kbd{P} is pressed after @kbd{a F} but before the model ++description is entered, the data as well as the model formula will be ++plotted after the formula is determined. This will be indicated by a ++``P'' in the minibuffer after the help message. ++ ++@menu ++* Linear Fits:: ++* Polynomial and Multilinear Fits:: ++* Error Estimates for Fits:: ++* Standard Nonlinear Models:: ++* Curve Fitting Details:: ++* Interpolation:: ++@end menu ++ ++@node Linear Fits, Polynomial and Multilinear Fits, Curve Fitting, Curve Fitting ++@subsection Linear Fits ++ ++@noindent ++@kindex a F ++@pindex calc-curve-fit ++@tindex fit ++@cindex Linear regression ++@cindex Least-squares fits ++The @kbd{a F} (@code{calc-curve-fit}) [@code{fit}] command attempts ++to fit a set of data (@expr{x} and @expr{y} vectors of numbers) to a ++straight line, polynomial, or other function of @expr{x}. For the ++moment we will consider only the case of fitting to a line, and we ++will ignore the issue of whether or not the model was in fact a good ++fit for the data. ++ ++In a standard linear least-squares fit, we have a set of @expr{(x,y)} ++data points that we wish to fit to the model @expr{y = m x + b} ++by adjusting the parameters @expr{m} and @expr{b} to make the @expr{y} ++values calculated from the formula be as close as possible to the actual ++@expr{y} values in the data set. (In a polynomial fit, the model is ++instead, say, @expr{y = a x^3 + b x^2 + c x + d}. In a multilinear fit, ++we have data points of the form @expr{(x_1,x_2,x_3,y)} and our model is ++@expr{y = a x_1 + b x_2 + c x_3 + d}. These will be discussed later.) ++ ++In the model formula, variables like @expr{x} and @expr{x_2} are called ++the @dfn{independent variables}, and @expr{y} is the @dfn{dependent ++variable}. Variables like @expr{m}, @expr{a}, and @expr{b} are called ++the @dfn{parameters} of the model. ++ ++The @kbd{a F} command takes the data set to be fitted from the stack. ++By default, it expects the data in the form of a matrix. For example, ++for a linear or polynomial fit, this would be a ++@texline @math{2\times N} ++@infoline 2xN ++matrix where the first row is a list of @expr{x} values and the second ++row has the corresponding @expr{y} values. For the multilinear fit ++shown above, the matrix would have four rows (@expr{x_1}, @expr{x_2}, ++@expr{x_3}, and @expr{y}, respectively). ++ ++If you happen to have an ++@texline @math{N\times2} ++@infoline Nx2 ++matrix instead of a ++@texline @math{2\times N} ++@infoline 2xN ++matrix, just press @kbd{v t} first to transpose the matrix. ++ ++After you type @kbd{a F}, Calc prompts you to select a model. For a ++linear fit, press the digit @kbd{1}. ++ ++Calc then prompts for you to name the variables. By default it chooses ++high letters like @expr{x} and @expr{y} for independent variables and ++low letters like @expr{a} and @expr{b} for parameters. (The dependent ++variable doesn't need a name.) The two kinds of variables are separated ++by a semicolon. Since you generally care more about the names of the ++independent variables than of the parameters, Calc also allows you to ++name only those and let the parameters use default names. ++ ++For example, suppose the data matrix ++ ++@ifnottex ++@example ++@group ++[ [ 1, 2, 3, 4, 5 ] ++ [ 5, 7, 9, 11, 13 ] ] ++@end group ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\turnoffactive ++\beforedisplay ++$$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr ++ 5 & 7 & 9 & 11 & 13 } ++$$ ++\afterdisplay ++@end tex ++ ++@noindent ++is on the stack and we wish to do a simple linear fit. Type ++@kbd{a F}, then @kbd{1} for the model, then @key{RET} to use ++the default names. The result will be the formula @expr{3. + 2. x} ++on the stack. Calc has created the model expression @kbd{a + b x}, ++then found the optimal values of @expr{a} and @expr{b} to fit the ++data. (In this case, it was able to find an exact fit.) Calc then ++substituted those values for @expr{a} and @expr{b} in the model ++formula. ++ ++The @kbd{a F} command puts two entries in the trail. One is, as ++always, a copy of the result that went to the stack; the other is ++a vector of the actual parameter values, written as equations: ++@expr{[a = 3, b = 2]}, in case you'd rather read them in a list ++than pick them out of the formula. (You can type @kbd{t y} ++to move this vector to the stack; see @ref{Trail Commands}. ++ ++Specifying a different independent variable name will affect the ++resulting formula: @kbd{a F 1 k @key{RET}} produces @kbd{3 + 2 k}. ++Changing the parameter names (say, @kbd{a F 1 k;b,m @key{RET}}) will affect ++the equations that go into the trail. ++ ++@tex ++\bigskip ++@end tex ++ ++To see what happens when the fit is not exact, we could change ++the number 13 in the data matrix to 14 and try the fit again. ++The result is: ++ ++@example ++2.6 + 2.2 x ++@end example ++ ++Evaluating this formula, say with @kbd{v x 5 @key{RET} @key{TAB} V M $ @key{RET}}, shows ++a reasonably close match to the y-values in the data. ++ ++@example ++[4.8, 7., 9.2, 11.4, 13.6] ++@end example ++ ++Since there is no line which passes through all the @var{n} data points, ++Calc has chosen a line that best approximates the data points using ++the method of least squares. The idea is to define the @dfn{chi-square} ++error measure ++ ++@ifnottex ++@example ++chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N) ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$ ++\afterdisplay ++@end tex ++ ++@noindent ++which is clearly zero if @expr{a + b x} exactly fits all data points, ++and increases as various @expr{a + b x_i} values fail to match the ++corresponding @expr{y_i} values. There are several reasons why the ++summand is squared, one of them being to ensure that ++@texline @math{\chi^2 \ge 0}. ++@infoline @expr{chi^2 >= 0}. ++Least-squares fitting simply chooses the values of @expr{a} and @expr{b} ++for which the error ++@texline @math{\chi^2} ++@infoline @expr{chi^2} ++is as small as possible. ++ ++Other kinds of models do the same thing but with a different model ++formula in place of @expr{a + b x_i}. ++ ++@tex ++\bigskip ++@end tex ++ ++A numeric prefix argument causes the @kbd{a F} command to take the ++data in some other form than one big matrix. A positive argument @var{n} ++will take @var{N} items from the stack, corresponding to the @var{n} rows ++of a data matrix. In the linear case, @var{n} must be 2 since there ++is always one independent variable and one dependent variable. ++ ++A prefix of zero or plain @kbd{C-u} is a compromise; Calc takes two ++items from the stack, an @var{n}-row matrix of @expr{x} values, and a ++vector of @expr{y} values. If there is only one independent variable, ++the @expr{x} values can be either a one-row matrix or a plain vector, ++in which case the @kbd{C-u} prefix is the same as a @w{@kbd{C-u 2}} prefix. ++ ++@node Polynomial and Multilinear Fits, Error Estimates for Fits, Linear Fits, Curve Fitting ++@subsection Polynomial and Multilinear Fits ++ ++@noindent ++To fit the data to higher-order polynomials, just type one of the ++digits @kbd{2} through @kbd{9} when prompted for a model. For example, ++we could fit the original data matrix from the previous section ++(with 13, not 14) to a parabola instead of a line by typing ++@kbd{a F 2 @key{RET}}. ++ ++@example ++2.00000000001 x - 1.5e-12 x^2 + 2.99999999999 ++@end example ++ ++Note that since the constant and linear terms are enough to fit the ++data exactly, it's no surprise that Calc chose a tiny contribution ++for @expr{x^2}. (The fact that it's not exactly zero is due only ++to roundoff error. Since our data are exact integers, we could get ++an exact answer by typing @kbd{m f} first to get Fraction mode. ++Then the @expr{x^2} term would vanish altogether. Usually, though, ++the data being fitted will be approximate floats so Fraction mode ++won't help.) ++ ++Doing the @kbd{a F 2} fit on the data set with 14 instead of 13 ++gives a much larger @expr{x^2} contribution, as Calc bends the ++line slightly to improve the fit. ++ ++@example ++0.142857142855 x^2 + 1.34285714287 x + 3.59999999998 ++@end example ++ ++An important result from the theory of polynomial fitting is that it ++is always possible to fit @var{n} data points exactly using a polynomial ++of degree @mathit{@var{n}-1}, sometimes called an @dfn{interpolating polynomial}. ++Using the modified (14) data matrix, a model number of 4 gives ++a polynomial that exactly matches all five data points: ++ ++@example ++0.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4. ++@end example ++ ++The actual coefficients we get with a precision of 12, like ++@expr{0.0416666663588}, clearly suffer from loss of precision. ++It is a good idea to increase the working precision to several ++digits beyond what you need when you do a fitting operation. ++Or, if your data are exact, use Fraction mode to get exact ++results. ++ ++You can type @kbd{i} instead of a digit at the model prompt to fit ++the data exactly to a polynomial. This just counts the number of ++columns of the data matrix to choose the degree of the polynomial ++automatically. ++ ++Fitting data ``exactly'' to high-degree polynomials is not always ++a good idea, though. High-degree polynomials have a tendency to ++wiggle uncontrollably in between the fitting data points. Also, ++if the exact-fit polynomial is going to be used to interpolate or ++extrapolate the data, it is numerically better to use the @kbd{a p} ++command described below. @xref{Interpolation}. ++ ++@tex ++\bigskip ++@end tex ++ ++Another generalization of the linear model is to assume the ++@expr{y} values are a sum of linear contributions from several ++@expr{x} values. This is a @dfn{multilinear} fit, and it is also ++selected by the @kbd{1} digit key. (Calc decides whether the fit ++is linear or multilinear by counting the rows in the data matrix.) ++ ++Given the data matrix, ++ ++@example ++@group ++[ [ 1, 2, 3, 4, 5 ] ++ [ 7, 2, 3, 5, 2 ] ++ [ 14.5, 15, 18.5, 22.5, 24 ] ] ++@end group ++@end example ++ ++@noindent ++the command @kbd{a F 1 @key{RET}} will call the first row @expr{x} and the ++second row @expr{y}, and will fit the values in the third row to the ++model @expr{a + b x + c y}. ++ ++@example ++8. + 3. x + 0.5 y ++@end example ++ ++Calc can do multilinear fits with any number of independent variables ++(i.e., with any number of data rows). ++ ++@tex ++\bigskip ++@end tex ++ ++Yet another variation is @dfn{homogeneous} linear models, in which ++the constant term is known to be zero. In the linear case, this ++means the model formula is simply @expr{a x}; in the multilinear ++case, the model might be @expr{a x + b y + c z}; and in the polynomial ++case, the model could be @expr{a x + b x^2 + c x^3}. You can get ++a homogeneous linear or multilinear model by pressing the letter ++@kbd{h} followed by a regular model key, like @kbd{1} or @kbd{2}. ++This will be indicated by an ``h'' in the minibuffer after the help ++message. ++ ++It is certainly possible to have other constrained linear models, ++like @expr{2.3 + a x} or @expr{a - 4 x}. While there is no single ++key to select models like these, a later section shows how to enter ++any desired model by hand. In the first case, for example, you ++would enter @kbd{a F ' 2.3 + a x}. ++ ++Another class of models that will work but must be entered by hand ++are multinomial fits, e.g., @expr{a + b x + c y + d x^2 + e y^2 + f x y}. ++ ++@node Error Estimates for Fits, Standard Nonlinear Models, Polynomial and Multilinear Fits, Curve Fitting ++@subsection Error Estimates for Fits ++ ++@noindent ++@kindex H a F ++@tindex efit ++With the Hyperbolic flag, @kbd{H a F} [@code{efit}] performs the same ++fitting operation as @kbd{a F}, but reports the coefficients as error ++forms instead of plain numbers. Fitting our two data matrices (first ++with 13, then with 14) to a line with @kbd{H a F} gives the results, ++ ++@example ++3. + 2. x ++2.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x ++@end example ++ ++In the first case the estimated errors are zero because the linear ++fit is perfect. In the second case, the errors are nonzero but ++moderately small, because the data are still very close to linear. ++ ++It is also possible for the @emph{input} to a fitting operation to ++contain error forms. The data values must either all include errors ++or all be plain numbers. Error forms can go anywhere but generally ++go on the numbers in the last row of the data matrix. If the last ++row contains error forms ++@texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}', ++@infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}', ++then the ++@texline @math{\chi^2} ++@infoline @expr{chi^2} ++statistic is now, ++ ++@ifnottex ++@example ++chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N) ++@end example ++@end ifnottex ++@tex ++\turnoffactive ++\beforedisplay ++$$ \chi^2 = \sum_{i=1}^N \left(y_i - (a + b x_i) \over \sigma_i\right)^2 $$ ++\afterdisplay ++@end tex ++ ++@noindent ++so that data points with larger error estimates contribute less to ++the fitting operation. ++ ++If there are error forms on other rows of the data matrix, all the ++errors for a given data point are combined; the square root of the ++sum of the squares of the errors forms the ++@texline @math{\sigma_i} ++@infoline @expr{sigma_i} ++used for the data point. ++ ++Both @kbd{a F} and @kbd{H a F} can accept error forms in the input ++matrix, although if you are concerned about error analysis you will ++probably use @kbd{H a F} so that the output also contains error ++estimates. ++ ++If the input contains error forms but all the ++@texline @math{\sigma_i} ++@infoline @expr{sigma_i} ++values are the same, it is easy to see that the resulting fitted model ++will be the same as if the input did not have error forms at all ++@texline (@math{\chi^2} ++@infoline (@expr{chi^2} ++is simply scaled uniformly by ++@texline @math{1 / \sigma^2}, ++@infoline @expr{1 / sigma^2}, ++which doesn't affect where it has a minimum). But there @emph{will} be ++a difference in the estimated errors of the coefficients reported by ++@kbd{H a F}. ++ ++Consult any text on statistical modeling of data for a discussion ++of where these error estimates come from and how they should be ++interpreted. ++ ++@tex ++\bigskip ++@end tex ++ ++@kindex I a F ++@tindex xfit ++With the Inverse flag, @kbd{I a F} [@code{xfit}] produces even more ++information. The result is a vector of six items: ++ ++@enumerate ++@item ++The model formula with error forms for its coefficients or ++parameters. This is the result that @kbd{H a F} would have ++produced. ++ ++@item ++A vector of ``raw'' parameter values for the model. These are the ++polynomial coefficients or other parameters as plain numbers, in the ++same order as the parameters appeared in the final prompt of the ++@kbd{I a F} command. For polynomials of degree @expr{d}, this vector ++will have length @expr{M = d+1} with the constant term first. ++ ++@item ++The covariance matrix @expr{C} computed from the fit. This is ++an @var{m}x@var{m} symmetric matrix; the diagonal elements ++@texline @math{C_{jj}} ++@infoline @expr{C_j_j} ++are the variances ++@texline @math{\sigma_j^2} ++@infoline @expr{sigma_j^2} ++of the parameters. The other elements are covariances ++@texline @math{\sigma_{ij}^2} ++@infoline @expr{sigma_i_j^2} ++that describe the correlation between pairs of parameters. (A related ++set of numbers, the @dfn{linear correlation coefficients} ++@texline @math{r_{ij}}, ++@infoline @expr{r_i_j}, ++are defined as ++@texline @math{\sigma_{ij}^2 / \sigma_i \, \sigma_j}.) ++@infoline @expr{sigma_i_j^2 / sigma_i sigma_j}.) ++ ++@item ++A vector of @expr{M} ``parameter filter'' functions whose ++meanings are described below. If no filters are necessary this ++will instead be an empty vector; this is always the case for the ++polynomial and multilinear fits described so far. ++ ++@item ++The value of ++@texline @math{\chi^2} ++@infoline @expr{chi^2} ++for the fit, calculated by the formulas shown above. This gives a ++measure of the quality of the fit; statisticians consider ++@texline @math{\chi^2 \approx N - M} ++@infoline @expr{chi^2 = N - M} ++to indicate a moderately good fit (where again @expr{N} is the number of ++data points and @expr{M} is the number of parameters). ++ ++@item ++A measure of goodness of fit expressed as a probability @expr{Q}. ++This is computed from the @code{utpc} probability distribution ++function using ++@texline @math{\chi^2} ++@infoline @expr{chi^2} ++with @expr{N - M} degrees of freedom. A ++value of 0.5 implies a good fit; some texts recommend that often ++@expr{Q = 0.1} or even 0.001 can signify an acceptable fit. In ++particular, ++@texline @math{\chi^2} ++@infoline @expr{chi^2} ++statistics assume the errors in your inputs ++follow a normal (Gaussian) distribution; if they don't, you may ++have to accept smaller values of @expr{Q}. ++ ++The @expr{Q} value is computed only if the input included error ++estimates. Otherwise, Calc will report the symbol @code{nan} ++for @expr{Q}. The reason is that in this case the ++@texline @math{\chi^2} ++@infoline @expr{chi^2} ++value has effectively been used to estimate the original errors ++in the input, and thus there is no redundant information left ++over to use for a confidence test. ++@end enumerate ++ ++@node Standard Nonlinear Models, Curve Fitting Details, Error Estimates for Fits, Curve Fitting ++@subsection Standard Nonlinear Models ++ ++@noindent ++The @kbd{a F} command also accepts other kinds of models besides ++lines and polynomials. Some common models have quick single-key ++abbreviations; others must be entered by hand as algebraic formulas. ++ ++Here is a complete list of the standard models recognized by @kbd{a F}: ++ ++@table @kbd ++@item 1 ++Linear or multilinear. @mathit{a + b x + c y + d z}. ++@item 2-9 ++Polynomials. @mathit{a + b x + c x^2 + d x^3}. ++@item e ++Exponential. @mathit{a} @tfn{exp}@mathit{(b x)} @tfn{exp}@mathit{(c y)}. ++@item E ++Base-10 exponential. @mathit{a} @tfn{10^}@mathit{(b x)} @tfn{10^}@mathit{(c y)}. ++@item x ++Exponential (alternate notation). @tfn{exp}@mathit{(a + b x + c y)}. ++@item X ++Base-10 exponential (alternate). @tfn{10^}@mathit{(a + b x + c y)}. ++@item l ++Logarithmic. @mathit{a + b} @tfn{ln}@mathit{(x) + c} @tfn{ln}@mathit{(y)}. ++@item L ++Base-10 logarithmic. @mathit{a + b} @tfn{log10}@mathit{(x) + c} @tfn{log10}@mathit{(y)}. ++@item ^ ++General exponential. @mathit{a b^x c^y}. ++@item p ++Power law. @mathit{a x^b y^c}. ++@item q ++Quadratic. @mathit{a + b (x-c)^2 + d (x-e)^2}. ++@item g ++Gaussian. ++@texline @math{{a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)}. ++@infoline @mathit{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}. ++@item s ++Logistic @emph{s} curve. ++@texline @math{a/(1+e^{b(x-c)})}. ++@infoline @mathit{a/(1 + exp(b (x - c)))}. ++@item b ++Logistic bell curve. ++@texline @math{ae^{b(x-c)}/(1+e^{b(x-c)})^2}. ++@infoline @mathit{a exp(b (x - c))/(1 + exp(b (x - c)))^2}. ++@item o ++Hubbert linearization. ++@texline @math{{y \over x} = a(1-x/b)}. ++@infoline @mathit{(y/x) = a (1 - x/b)}. ++@end table ++ ++All of these models are used in the usual way; just press the appropriate ++letter at the model prompt, and choose variable names if you wish. The ++result will be a formula as shown in the above table, with the best-fit ++values of the parameters substituted. (You may find it easier to read ++the parameter values from the vector that is placed in the trail.) ++ ++All models except Gaussian, logistics, Hubbert and polynomials can ++generalize as shown to any number of independent variables. Also, all ++the built-in models except for the logistic and Hubbert curves have an ++additive or multiplicative parameter shown as @expr{a} in the above table ++which can be replaced by zero or one, as appropriate, by typing @kbd{h} ++before the model key. ++ ++Note that many of these models are essentially equivalent, but express ++the parameters slightly differently. For example, @expr{a b^x} and ++the other two exponential models are all algebraic rearrangements of ++each other. Also, the ``quadratic'' model is just a degree-2 polynomial ++with the parameters expressed differently. Use whichever form best ++matches the problem. ++ ++The HP-28/48 calculators support four different models for curve ++fitting, called @code{LIN}, @code{LOG}, @code{EXP}, and @code{PWR}. ++These correspond to Calc models @samp{a + b x}, @samp{a + b ln(x)}, ++@samp{a exp(b x)}, and @samp{a x^b}, respectively. In each case, ++@expr{a} is what the HP-48 identifies as the ``intercept,'' and ++@expr{b} is what it calls the ``slope.'' ++ ++@tex ++\bigskip ++@end tex ++ ++If the model you want doesn't appear on this list, press @kbd{'} ++(the apostrophe key) at the model prompt to enter any algebraic ++formula, such as @kbd{m x - b}, as the model. (Not all models ++will work, though---see the next section for details.) ++ ++The model can also be an equation like @expr{y = m x + b}. ++In this case, Calc thinks of all the rows of the data matrix on ++equal terms; this model effectively has two parameters ++(@expr{m} and @expr{b}) and two independent variables (@expr{x} ++and @expr{y}), with no ``dependent'' variables. Model equations ++do not need to take this @expr{y =} form. For example, the ++implicit line equation @expr{a x + b y = 1} works fine as a ++model. ++ ++When you enter a model, Calc makes an alphabetical list of all ++the variables that appear in the model. These are used for the ++default parameters, independent variables, and dependent variable ++(in that order). If you enter a plain formula (not an equation), ++Calc assumes the dependent variable does not appear in the formula ++and thus does not need a name. ++ ++For example, if the model formula has the variables @expr{a,mu,sigma,t,x}, ++and the data matrix has three rows (meaning two independent variables), ++Calc will use @expr{a,mu,sigma} as the default parameters, and the ++data rows will be named @expr{t} and @expr{x}, respectively. If you ++enter an equation instead of a plain formula, Calc will use @expr{a,mu} ++as the parameters, and @expr{sigma,t,x} as the three independent ++variables. ++ ++You can, of course, override these choices by entering something ++different at the prompt. If you leave some variables out of the list, ++those variables must have stored values and those stored values will ++be used as constants in the model. (Stored values for the parameters ++and independent variables are ignored by the @kbd{a F} command.) ++If you list only independent variables, all the remaining variables ++in the model formula will become parameters. ++ ++If there are @kbd{$} signs in the model you type, they will stand ++for parameters and all other variables (in alphabetical order) ++will be independent. Use @kbd{$} for one parameter, @kbd{$$} for ++another, and so on. Thus @kbd{$ x + $$} is another way to describe ++a linear model. ++ ++If you type a @kbd{$} instead of @kbd{'} at the model prompt itself, ++Calc will take the model formula from the stack. (The data must then ++appear at the second stack level.) The same conventions are used to ++choose which variables in the formula are independent by default and ++which are parameters. ++ ++Models taken from the stack can also be expressed as vectors of ++two or three elements, @expr{[@var{model}, @var{vars}]} or ++@expr{[@var{model}, @var{vars}, @var{params}]}. Each of @var{vars} ++and @var{params} may be either a variable or a vector of variables. ++(If @var{params} is omitted, all variables in @var{model} except ++those listed as @var{vars} are parameters.) ++ ++When you enter a model manually with @kbd{'}, Calc puts a 3-vector ++describing the model in the trail so you can get it back if you wish. ++ ++@tex ++\bigskip ++@end tex ++ ++@vindex Model1 ++@vindex Model2 ++Finally, you can store a model in one of the Calc variables ++@code{Model1} or @code{Model2}, then use this model by typing ++@kbd{a F u} or @kbd{a F U} (respectively). The value stored in ++the variable can be any of the formats that @kbd{a F $} would ++accept for a model on the stack. ++ ++@tex ++\bigskip ++@end tex ++ ++Calc uses the principal values of inverse functions like @code{ln} ++and @code{arcsin} when doing fits. For example, when you enter ++the model @samp{y = sin(a t + b)} Calc actually uses the easier ++form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always ++returns results in the range from @mathit{-90} to 90 degrees (or the ++equivalent range in radians). Suppose you had data that you ++believed to represent roughly three oscillations of a sine wave, ++so that the argument of the sine might go from zero to ++@texline @math{3\times360} ++@infoline @mathit{3*360} ++degrees. ++The above model would appear to be a good way to determine the ++true frequency and phase of the sine wave, but in practice it ++would fail utterly. The righthand side of the actual model ++@samp{arcsin(y) = a t + b} will grow smoothly with @expr{t}, but ++the lefthand side will bounce back and forth between @mathit{-90} and 90. ++No values of @expr{a} and @expr{b} can make the two sides match, ++even approximately. ++ ++There is no good solution to this problem at present. You could ++restrict your data to small enough ranges so that the above problem ++doesn't occur (i.e., not straddling any peaks in the sine wave). ++Or, in this case, you could use a totally different method such as ++Fourier analysis, which is beyond the scope of the @kbd{a F} command. ++(Unfortunately, Calc does not currently have any facilities for ++taking Fourier and related transforms.) ++ ++@node Curve Fitting Details, Interpolation, Standard Nonlinear Models, Curve Fitting ++@subsection Curve Fitting Details ++ ++@noindent ++Calc's internal least-squares fitter can only handle multilinear ++models. More precisely, it can handle any model of the form ++@expr{a f(x,y,z) + b g(x,y,z) + c h(x,y,z)}, where @expr{a,b,c} ++are the parameters and @expr{x,y,z} are the independent variables ++(of course there can be any number of each, not just three). ++ ++In a simple multilinear or polynomial fit, it is easy to see how ++to convert the model into this form. For example, if the model ++is @expr{a + b x + c x^2}, then @expr{f(x) = 1}, @expr{g(x) = x}, ++and @expr{h(x) = x^2} are suitable functions. ++ ++For most other models, Calc uses a variety of algebraic manipulations ++to try to put the problem into the form ++ ++@smallexample ++Y(x,y,z) = A(a,b,c) F(x,y,z) + B(a,b,c) G(x,y,z) + C(a,b,c) H(x,y,z) ++@end smallexample ++ ++@noindent ++where @expr{Y,A,B,C,F,G,H} are arbitrary functions. It computes ++@expr{Y}, @expr{F}, @expr{G}, and @expr{H} for all the data points, ++does a standard linear fit to find the values of @expr{A}, @expr{B}, ++and @expr{C}, then uses the equation solver to solve for @expr{a,b,c} ++in terms of @expr{A,B,C}. ++ ++A remarkable number of models can be cast into this general form. ++We'll look at two examples here to see how it works. The power-law ++model @expr{y = a x^b} with two independent variables and two parameters ++can be rewritten as follows: ++ ++@example ++y = a x^b ++y = a exp(b ln(x)) ++y = exp(ln(a) + b ln(x)) ++ln(y) = ln(a) + b ln(x) ++@end example ++ ++@noindent ++which matches the desired form with ++@texline @math{Y = \ln(y)}, ++@infoline @expr{Y = ln(y)}, ++@texline @math{A = \ln(a)}, ++@infoline @expr{A = ln(a)}, ++@expr{F = 1}, @expr{B = b}, and ++@texline @math{G = \ln(x)}. ++@infoline @expr{G = ln(x)}. ++Calc thus computes the logarithms of your @expr{y} and @expr{x} values, ++does a linear fit for @expr{A} and @expr{B}, then solves to get ++@texline @math{a = \exp(A)} ++@infoline @expr{a = exp(A)} ++and @expr{b = B}. ++ ++Another interesting example is the ``quadratic'' model, which can ++be handled by expanding according to the distributive law. ++ ++@example ++y = a + b*(x - c)^2 ++y = a + b c^2 - 2 b c x + b x^2 ++@end example ++ ++@noindent ++which matches with @expr{Y = y}, @expr{A = a + b c^2}, @expr{F = 1}, ++@expr{B = -2 b c}, @expr{G = x} (the @mathit{-2} factor could just as easily ++have been put into @expr{G} instead of @expr{B}), @expr{C = b}, and ++@expr{H = x^2}. ++ ++The Gaussian model looks quite complicated, but a closer examination ++shows that it's actually similar to the quadratic model but with an ++exponential that can be brought to the top and moved into @expr{Y}. ++ ++The logistic models cannot be put into general linear form. For these ++models, and the Hubbert linearization, Calc computes a rough ++approximation for the parameters, then uses the Levenberg-Marquardt ++iterative method to refine the approximations. ++ ++Another model that cannot be put into general linear ++form is a Gaussian with a constant background added on, i.e., ++@expr{d} + the regular Gaussian formula. If you have a model like ++this, your best bet is to replace enough of your parameters with ++constants to make the model linearizable, then adjust the constants ++manually by doing a series of fits. You can compare the fits by ++graphing them, by examining the goodness-of-fit measures returned by ++@kbd{I a F}, or by some other method suitable to your application. ++Note that some models can be linearized in several ways. The ++Gaussian-plus-@var{d} model can be linearized by setting @expr{d} ++(the background) to a constant, or by setting @expr{b} (the standard ++deviation) and @expr{c} (the mean) to constants. ++ ++To fit a model with constants substituted for some parameters, just ++store suitable values in those parameter variables, then omit them ++from the list of parameters when you answer the variables prompt. ++ ++@tex ++\bigskip ++@end tex ++ ++A last desperate step would be to use the general-purpose ++@code{minimize} function rather than @code{fit}. After all, both ++functions solve the problem of minimizing an expression (the ++@texline @math{\chi^2} ++@infoline @expr{chi^2} ++sum) by adjusting certain parameters in the expression. The @kbd{a F} ++command is able to use a vastly more efficient algorithm due to its ++special knowledge about linear chi-square sums, but the @kbd{a N} ++command can do the same thing by brute force. ++ ++A compromise would be to pick out a few parameters without which the ++fit is linearizable, and use @code{minimize} on a call to @code{fit} ++which efficiently takes care of the rest of the parameters. The thing ++to be minimized would be the value of ++@texline @math{\chi^2} ++@infoline @expr{chi^2} ++returned as the fifth result of the @code{xfit} function: ++ ++@smallexample ++minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess) ++@end smallexample ++ ++@noindent ++where @code{gaus} represents the Gaussian model with background, ++@code{data} represents the data matrix, and @code{guess} represents ++the initial guess for @expr{d} that @code{minimize} requires. ++This operation will only be, shall we say, extraordinarily slow ++rather than astronomically slow (as would be the case if @code{minimize} ++were used by itself to solve the problem). ++ ++@tex ++\bigskip ++@end tex ++ ++The @kbd{I a F} [@code{xfit}] command is somewhat trickier when ++nonlinear models are used. The second item in the result is the ++vector of ``raw'' parameters @expr{A}, @expr{B}, @expr{C}. The ++covariance matrix is written in terms of those raw parameters. ++The fifth item is a vector of @dfn{filter} expressions. This ++is the empty vector @samp{[]} if the raw parameters were the same ++as the requested parameters, i.e., if @expr{A = a}, @expr{B = b}, ++and so on (which is always true if the model is already linear ++in the parameters as written, e.g., for polynomial fits). If the ++parameters had to be rearranged, the fifth item is instead a vector ++of one formula per parameter in the original model. The raw ++parameters are expressed in these ``filter'' formulas as ++@samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} for @expr{B}, ++and so on. ++ ++When Calc needs to modify the model to return the result, it replaces ++@samp{fitdummy(1)} in all the filters with the first item in the raw ++parameters list, and so on for the other raw parameters, then ++evaluates the resulting filter formulas to get the actual parameter ++values to be substituted into the original model. In the case of ++@kbd{H a F} and @kbd{I a F} where the parameters must be error forms, ++Calc uses the square roots of the diagonal entries of the covariance ++matrix as error values for the raw parameters, then lets Calc's ++standard error-form arithmetic take it from there. ++ ++If you use @kbd{I a F} with a nonlinear model, be sure to remember ++that the covariance matrix is in terms of the raw parameters, ++@emph{not} the actual requested parameters. It's up to you to ++figure out how to interpret the covariances in the presence of ++nontrivial filter functions. ++ ++Things are also complicated when the input contains error forms. ++Suppose there are three independent and dependent variables, @expr{x}, ++@expr{y}, and @expr{z}, one or more of which are error forms in the ++data. Calc combines all the error values by taking the square root ++of the sum of the squares of the errors. It then changes @expr{x} ++and @expr{y} to be plain numbers, and makes @expr{z} into an error ++form with this combined error. The @expr{Y(x,y,z)} part of the ++linearized model is evaluated, and the result should be an error ++form. The error part of that result is used for ++@texline @math{\sigma_i} ++@infoline @expr{sigma_i} ++for the data point. If for some reason @expr{Y(x,y,z)} does not return ++an error form, the combined error from @expr{z} is used directly for ++@texline @math{\sigma_i}. ++@infoline @expr{sigma_i}. ++Finally, @expr{z} is also stripped of its error ++for use in computing @expr{F(x,y,z)}, @expr{G(x,y,z)} and so on; ++the righthand side of the linearized model is computed in regular ++arithmetic with no error forms. ++ ++(While these rules may seem complicated, they are designed to do ++the most reasonable thing in the typical case that @expr{Y(x,y,z)} ++depends only on the dependent variable @expr{z}, and in fact is ++often simply equal to @expr{z}. For common cases like polynomials ++and multilinear models, the combined error is simply used as the ++@texline @math{\sigma} ++@infoline @expr{sigma} ++for the data point with no further ado.) ++ ++@tex ++\bigskip ++@end tex ++ ++@vindex FitRules ++It may be the case that the model you wish to use is linearizable, ++but Calc's built-in rules are unable to figure it out. Calc uses ++its algebraic rewrite mechanism to linearize a model. The rewrite ++rules are kept in the variable @code{FitRules}. You can edit this ++variable using the @kbd{s e FitRules} command; in fact, there is ++a special @kbd{s F} command just for editing @code{FitRules}. ++@xref{Operations on Variables}. ++ ++@xref{Rewrite Rules}, for a discussion of rewrite rules. ++ ++@ignore ++@starindex ++@end ignore ++@tindex fitvar ++@ignore ++@starindex ++@end ignore ++@ignore ++@mindex @idots ++@end ignore ++@tindex fitparam ++@ignore ++@starindex ++@end ignore ++@ignore ++@mindex @null ++@end ignore ++@tindex fitmodel ++@ignore ++@starindex ++@end ignore ++@ignore ++@mindex @null ++@end ignore ++@tindex fitsystem ++@ignore ++@starindex ++@end ignore ++@ignore ++@mindex @null ++@end ignore ++@tindex fitdummy ++Calc uses @code{FitRules} as follows. First, it converts the model ++to an equation if necessary and encloses the model equation in a ++call to the function @code{fitmodel} (which is not actually a defined ++function in Calc; it is only used as a placeholder by the rewrite rules). ++Parameter variables are renamed to function calls @samp{fitparam(1)}, ++@samp{fitparam(2)}, and so on, and independent variables are renamed ++to @samp{fitvar(1)}, @samp{fitvar(2)}, etc. The dependent variable ++is the highest-numbered @code{fitvar}. For example, the power law ++model @expr{a x^b} is converted to @expr{y = a x^b}, then to ++ ++@smallexample ++@group ++fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2)) ++@end group ++@end smallexample ++ ++Calc then applies the rewrites as if by @samp{C-u 0 a r FitRules}. ++(The zero prefix means that rewriting should continue until no further ++changes are possible.) ++ ++When rewriting is complete, the @code{fitmodel} call should have ++been replaced by a @code{fitsystem} call that looks like this: ++ ++@example ++fitsystem(@var{Y}, @var{FGH}, @var{abc}) ++@end example ++ ++@noindent ++where @var{Y} is a formula that describes the function @expr{Y(x,y,z)}, ++@var{FGH} is the vector of formulas @expr{[F(x,y,z), G(x,y,z), H(x,y,z)]}, ++and @var{abc} is the vector of parameter filters which refer to the ++raw parameters as @samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} ++for @expr{B}, etc. While the number of raw parameters (the length of ++the @var{FGH} vector) is usually the same as the number of original ++parameters (the length of the @var{abc} vector), this is not required. ++ ++The power law model eventually boils down to ++ ++@smallexample ++@group ++fitsystem(ln(fitvar(2)), ++ [1, ln(fitvar(1))], ++ [exp(fitdummy(1)), fitdummy(2)]) ++@end group ++@end smallexample ++ ++The actual implementation of @code{FitRules} is complicated; it ++proceeds in four phases. First, common rearrangements are done ++to try to bring linear terms together and to isolate functions like ++@code{exp} and @code{ln} either all the way ``out'' (so that they ++can be put into @var{Y}) or all the way ``in'' (so that they can ++be put into @var{abc} or @var{FGH}). In particular, all ++non-constant powers are converted to logs-and-exponentials form, ++and the distributive law is used to expand products of sums. ++Quotients are rewritten to use the @samp{fitinv} function, where ++@samp{fitinv(x)} represents @expr{1/x} while the @code{FitRules} ++are operating. (The use of @code{fitinv} makes recognition of ++linear-looking forms easier.) If you modify @code{FitRules}, you ++will probably only need to modify the rules for this phase. ++ ++Phase two, whose rules can actually also apply during phases one ++and three, first rewrites @code{fitmodel} to a two-argument ++form @samp{fitmodel(@var{Y}, @var{model})}, where @var{Y} is ++initially zero and @var{model} has been changed from @expr{a=b} ++to @expr{a-b} form. It then tries to peel off invertible functions ++from the outside of @var{model} and put them into @var{Y} instead, ++calling the equation solver to invert the functions. Finally, when ++this is no longer possible, the @code{fitmodel} is changed to a ++four-argument @code{fitsystem}, where the fourth argument is ++@var{model} and the @var{FGH} and @var{abc} vectors are initially ++empty. (The last vector is really @var{ABC}, corresponding to ++raw parameters, for now.) ++ ++Phase three converts a sum of items in the @var{model} to a sum ++of @samp{fitpart(@var{a}, @var{b}, @var{c})} terms which represent ++terms @samp{@var{a}*@var{b}*@var{c}} of the sum, where @var{a} ++is all factors that do not involve any variables, @var{b} is all ++factors that involve only parameters, and @var{c} is the factors ++that involve only independent variables. (If this decomposition ++is not possible, the rule set will not complete and Calc will ++complain that the model is too complex.) Then @code{fitpart}s ++with equal @var{b} or @var{c} components are merged back together ++using the distributive law in order to minimize the number of ++raw parameters needed. ++ ++Phase four moves the @code{fitpart} terms into the @var{FGH} and ++@var{ABC} vectors. Also, some of the algebraic expansions that ++were done in phase 1 are undone now to make the formulas more ++computationally efficient. Finally, it calls the solver one more ++time to convert the @var{ABC} vector to an @var{abc} vector, and ++removes the fourth @var{model} argument (which by now will be zero) ++to obtain the three-argument @code{fitsystem} that the linear ++least-squares solver wants to see. ++ ++@ignore ++@starindex ++@end ignore ++@ignore ++@mindex hasfit@idots ++@end ignore ++@tindex hasfitparams ++@ignore ++@starindex ++@end ignore ++@ignore ++@mindex @null ++@end ignore ++@tindex hasfitvars ++Two functions which are useful in connection with @code{FitRules} ++are @samp{hasfitparams(x)} and @samp{hasfitvars(x)}, which check ++whether @expr{x} refers to any parameters or independent variables, ++respectively. Specifically, these functions return ``true'' if the ++argument contains any @code{fitparam} (or @code{fitvar}) function ++calls, and ``false'' otherwise. (Recall that ``true'' means a ++nonzero number, and ``false'' means zero. The actual nonzero number ++returned is the largest @var{n} from all the @samp{fitparam(@var{n})}s ++or @samp{fitvar(@var{n})}s, respectively, that appear in the formula.) ++ ++@tex ++\bigskip ++@end tex ++ ++The @code{fit} function in algebraic notation normally takes four ++arguments, @samp{fit(@var{model}, @var{vars}, @var{params}, @var{data})}, ++where @var{model} is the model formula as it would be typed after ++@kbd{a F '}, @var{vars} is the independent variable or a vector of ++independent variables, @var{params} likewise gives the parameter(s), ++and @var{data} is the data matrix. Note that the length of @var{vars} ++must be equal to the number of rows in @var{data} if @var{model} is ++an equation, or one less than the number of rows if @var{model} is ++a plain formula. (Actually, a name for the dependent variable is ++allowed but will be ignored in the plain-formula case.) ++ ++If @var{params} is omitted, the parameters are all variables in ++@var{model} except those that appear in @var{vars}. If @var{vars} ++is also omitted, Calc sorts all the variables that appear in ++@var{model} alphabetically and uses the higher ones for @var{vars} ++and the lower ones for @var{params}. ++ ++Alternatively, @samp{fit(@var{modelvec}, @var{data})} is allowed ++where @var{modelvec} is a 2- or 3-vector describing the model ++and variables, as discussed previously. ++ ++If Calc is unable to do the fit, the @code{fit} function is left ++in symbolic form, ordinarily with an explanatory message. The ++message will be ``Model expression is too complex'' if the ++linearizer was unable to put the model into the required form. ++ ++The @code{efit} (corresponding to @kbd{H a F}) and @code{xfit} ++(for @kbd{I a F}) functions are completely analogous. ++ ++@node Interpolation, , Curve Fitting Details, Curve Fitting ++@subsection Polynomial Interpolation ++ ++@kindex a p ++@pindex calc-poly-interp ++@tindex polint ++The @kbd{a p} (@code{calc-poly-interp}) [@code{polint}] command does ++a polynomial interpolation at a particular @expr{x} value. It takes ++two arguments from the stack: A data matrix of the sort used by ++@kbd{a F}, and a single number which represents the desired @expr{x} ++value. Calc effectively does an exact polynomial fit as if by @kbd{a F i}, ++then substitutes the @expr{x} value into the result in order to get an ++approximate @expr{y} value based on the fit. (Calc does not actually ++use @kbd{a F i}, however; it uses a direct method which is both more ++efficient and more numerically stable.) ++ ++The result of @kbd{a p} is actually a vector of two values: The @expr{y} ++value approximation, and an error measure @expr{dy} that reflects Calc's ++estimation of the probable error of the approximation at that value of ++@expr{x}. If the input @expr{x} is equal to any of the @expr{x} values ++in the data matrix, the output @expr{y} will be the corresponding @expr{y} ++value from the matrix, and the output @expr{dy} will be exactly zero. ++ ++A prefix argument of 2 causes @kbd{a p} to take separate x- and ++y-vectors from the stack instead of one data matrix. ++ ++If @expr{x} is a vector of numbers, @kbd{a p} will return a matrix of ++interpolated results for each of those @expr{x} values. (The matrix will ++have two columns, the @expr{y} values and the @expr{dy} values.) ++If @expr{x} is a formula instead of a number, the @code{polint} function ++remains in symbolic form; use the @kbd{a "} command to expand it out to ++a formula that describes the fit in symbolic terms. ++ ++In all cases, the @kbd{a p} command leaves the data vectors or matrix ++on the stack. Only the @expr{x} value is replaced by the result. ++ ++@kindex H a p ++@tindex ratint ++The @kbd{H a p} [@code{ratint}] command does a rational function ++interpolation. It is used exactly like @kbd{a p}, except that it ++uses as its model the quotient of two polynomials. If there are ++@expr{N} data points, the numerator and denominator polynomials will ++each have degree @expr{N/2} (if @expr{N} is odd, the denominator will ++have degree one higher than the numerator). ++ ++Rational approximations have the advantage that they can accurately ++describe functions that have poles (points at which the function's value ++goes to infinity, so that the denominator polynomial of the approximation ++goes to zero). If @expr{x} corresponds to a pole of the fitted rational ++function, then the result will be a division by zero. If Infinite mode ++is enabled, the result will be @samp{[uinf, uinf]}. ++ ++There is no way to get the actual coefficients of the rational function ++used by @kbd{H a p}. (The algorithm never generates these coefficients ++explicitly, and quotients of polynomials are beyond @w{@kbd{a F}}'s ++capabilities to fit.) ++ ++@node Summations, Logical Operations, Curve Fitting, Algebra ++@section Summations ++ ++@noindent ++@cindex Summation of a series ++@kindex a + ++@pindex calc-summation ++@tindex sum ++The @kbd{a +} (@code{calc-summation}) [@code{sum}] command computes ++the sum of a formula over a certain range of index values. The formula ++is taken from the top of the stack; the command prompts for the ++name of the summation index variable, the lower limit of the ++sum (any formula), and the upper limit of the sum. If you ++enter a blank line at any of these prompts, that prompt and ++any later ones are answered by reading additional elements from ++the stack. Thus, @kbd{' k^2 @key{RET} ' k @key{RET} 1 @key{RET} 5 @key{RET} a + @key{RET}} ++produces the result 55. ++@tex ++\turnoffactive ++$$ \sum_{k=1}^5 k^2 = 55 $$ ++@end tex ++ ++The choice of index variable is arbitrary, but it's best not to ++use a variable with a stored value. In particular, while ++@code{i} is often a favorite index variable, it should be avoided ++in Calc because @code{i} has the imaginary constant @expr{(0, 1)} ++as a value. If you pressed @kbd{=} on a sum over @code{i}, it would ++be changed to a nonsensical sum over the ``variable'' @expr{(0, 1)}! ++If you really want to use @code{i} as an index variable, use ++@w{@kbd{s u i @key{RET}}} first to ``unstore'' this variable. ++(@xref{Storing Variables}.) ++ ++A numeric prefix argument steps the index by that amount rather ++than by one. Thus @kbd{' a_k @key{RET} C-u -2 a + k @key{RET} 10 @key{RET} 0 @key{RET}} ++yields @samp{a_10 + a_8 + a_6 + a_4 + a_2 + a_0}. A prefix ++argument of plain @kbd{C-u} causes @kbd{a +} to prompt for the ++step value, in which case you can enter any formula or enter ++a blank line to take the step value from the stack. With the ++@kbd{C-u} prefix, @kbd{a +} can take up to five arguments from ++the stack: The formula, the variable, the lower limit, the ++upper limit, and (at the top of the stack), the step value. ++ ++Calc knows how to do certain sums in closed form. For example, ++@samp{sum(6 k^2, k, 1, n) = @w{2 n^3} + 3 n^2 + n}. In particular, ++this is possible if the formula being summed is polynomial or ++exponential in the index variable. Sums of logarithms are ++transformed into logarithms of products. Sums of trigonometric ++and hyperbolic functions are transformed to sums of exponentials ++and then done in closed form. Also, of course, sums in which the ++lower and upper limits are both numbers can always be evaluated ++just by grinding them out, although Calc will use closed forms ++whenever it can for the sake of efficiency. ++ ++The notation for sums in algebraic formulas is ++@samp{sum(@var{expr}, @var{var}, @var{low}, @var{high}, @var{step})}. ++If @var{step} is omitted, it defaults to one. If @var{high} is ++omitted, @var{low} is actually the upper limit and the lower limit ++is one. If @var{low} is also omitted, the limits are @samp{-inf} ++and @samp{inf}, respectively. ++ ++Infinite sums can sometimes be evaluated: @samp{sum(.5^k, k, 1, inf)} ++returns @expr{1}. This is done by evaluating the sum in closed ++form (to @samp{1. - 0.5^n} in this case), then evaluating this ++formula with @code{n} set to @code{inf}. Calc's usual rules ++for ``infinite'' arithmetic can find the answer from there. If ++infinite arithmetic yields a @samp{nan}, or if the sum cannot be ++solved in closed form, Calc leaves the @code{sum} function in ++symbolic form. @xref{Infinities}. ++ ++As a special feature, if the limits are infinite (or omitted, as ++described above) but the formula includes vectors subscripted by ++expressions that involve the iteration variable, Calc narrows ++the limits to include only the range of integers which result in ++valid subscripts for the vector. For example, the sum ++@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}. ++ ++The limits of a sum do not need to be integers. For example, ++@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}. ++Calc computes the number of iterations using the formula ++@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must, ++after simplification as if by @kbd{a s}, evaluate to an integer. ++ ++If the number of iterations according to the above formula does ++not come out to an integer, the sum is invalid and will be left ++in symbolic form. However, closed forms are still supplied, and ++you are on your honor not to misuse the resulting formulas by ++substituting mismatched bounds into them. For example, ++@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and ++evaluate the closed form solution for the limits 1 and 10 to get ++the rather dubious answer, 29.25. ++ ++If the lower limit is greater than the upper limit (assuming a ++positive step size), the result is generally zero. However, ++Calc only guarantees a zero result when the upper limit is ++exactly one step less than the lower limit, i.e., if the number ++of iterations is @mathit{-1}. Thus @samp{sum(f(k), k, n, n-1)} is zero ++but the sum from @samp{n} to @samp{n-2} may report a nonzero value ++if Calc used a closed form solution. ++ ++Calc's logical predicates like @expr{a < b} return 1 for ``true'' ++and 0 for ``false.'' @xref{Logical Operations}. This can be ++used to advantage for building conditional sums. For example, ++@samp{sum(prime(k)*k^2, k, 1, 20)} is the sum of the squares of all ++prime numbers from 1 to 20; the @code{prime} predicate returns 1 if ++its argument is prime and 0 otherwise. You can read this expression ++as ``the sum of @expr{k^2}, where @expr{k} is prime.'' Indeed, ++@samp{sum(prime(k)*k^2, k)} would represent the sum of @emph{all} primes ++squared, since the limits default to plus and minus infinity, but ++there are no such sums that Calc's built-in rules can do in ++closed form. ++ ++As another example, @samp{sum((k != k_0) * f(k), k, 1, n)} is the ++sum of @expr{f(k)} for all @expr{k} from 1 to @expr{n}, excluding ++one value @expr{k_0}. Slightly more tricky is the summand ++@samp{(k != k_0) / (k - k_0)}, which is an attempt to describe ++the sum of all @expr{1/(k-k_0)} except at @expr{k = k_0}, where ++this would be a division by zero. But at @expr{k = k_0}, this ++formula works out to the indeterminate form @expr{0 / 0}, which ++Calc will not assume is zero. Better would be to use ++@samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does ++an ``if-then-else'' test: This expression says, ``if ++@texline @math{k \ne k_0}, ++@infoline @expr{k != k_0}, ++then @expr{1/(k-k_0)}, else zero.'' Now the formula @expr{1/(k-k_0)} ++will not even be evaluated by Calc when @expr{k = k_0}. ++ ++@cindex Alternating sums ++@kindex a - ++@pindex calc-alt-summation ++@tindex asum ++The @kbd{a -} (@code{calc-alt-summation}) [@code{asum}] command ++computes an alternating sum. Successive terms of the sequence ++are given alternating signs, with the first term (corresponding ++to the lower index value) being positive. Alternating sums ++are converted to normal sums with an extra term of the form ++@samp{(-1)^(k-@var{low})}. This formula is adjusted appropriately ++if the step value is other than one. For example, the Taylor ++series for the sine function is @samp{asum(x^k / k!, k, 1, inf, 2)}. ++(Calc cannot evaluate this infinite series, but it can approximate ++it if you replace @code{inf} with any particular odd number.) ++Calc converts this series to a regular sum with a step of one, ++namely @samp{sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)}. ++ ++@cindex Product of a sequence ++@kindex a * ++@pindex calc-product ++@tindex prod ++The @kbd{a *} (@code{calc-product}) [@code{prod}] command is ++the analogous way to take a product of many terms. Calc also knows ++some closed forms for products, such as @samp{prod(k, k, 1, n) = n!}. ++Conditional products can be written @samp{prod(k^prime(k), k, 1, n)} ++or @samp{prod(prime(k) ? k : 1, k, 1, n)}. ++ ++@kindex a T ++@pindex calc-tabulate ++@tindex table ++The @kbd{a T} (@code{calc-tabulate}) [@code{table}] command ++evaluates a formula at a series of iterated index values, just ++like @code{sum} and @code{prod}, but its result is simply a ++vector of the results. For example, @samp{table(a_i, i, 1, 7, 2)} ++produces @samp{[a_1, a_3, a_5, a_7]}. ++ ++@node Logical Operations, Rewrite Rules, Summations, Algebra ++@section Logical Operations ++ ++@noindent ++The following commands and algebraic functions return true/false values, ++where 1 represents ``true'' and 0 represents ``false.'' In cases where ++a truth value is required (such as for the condition part of a rewrite ++rule, or as the condition for a @w{@kbd{Z [ Z ]}} control structure), any ++nonzero value is accepted to mean ``true.'' (Specifically, anything ++for which @code{dnonzero} returns 1 is ``true,'' and anything for ++which @code{dnonzero} returns 0 or cannot decide is assumed ``false.'' ++Note that this means that @w{@kbd{Z [ Z ]}} will execute the ``then'' ++portion if its condition is provably true, but it will execute the ++``else'' portion for any condition like @expr{a = b} that is not ++provably true, even if it might be true. Algebraic functions that ++have conditions as arguments, like @code{? :} and @code{&&}, remain ++unevaluated if the condition is neither provably true nor provably ++false. @xref{Declarations}.) ++ ++@kindex a = ++@pindex calc-equal-to ++@tindex eq ++@tindex = ++@tindex == ++The @kbd{a =} (@code{calc-equal-to}) command, or @samp{eq(a,b)} function ++(which can also be written @samp{a = b} or @samp{a == b} in an algebraic ++formula) is true if @expr{a} and @expr{b} are equal, either because they ++are identical expressions, or because they are numbers which are ++numerically equal. (Thus the integer 1 is considered equal to the float ++1.0.) If the equality of @expr{a} and @expr{b} cannot be determined, ++the comparison is left in symbolic form. Note that as a command, this ++operation pops two values from the stack and pushes back either a 1 or ++a 0, or a formula @samp{a = b} if the values' equality cannot be determined. ++ ++Many Calc commands use @samp{=} formulas to represent @dfn{equations}. ++For example, the @kbd{a S} (@code{calc-solve-for}) command rearranges ++an equation to solve for a given variable. The @kbd{a M} ++(@code{calc-map-equation}) command can be used to apply any ++function to both sides of an equation; for example, @kbd{2 a M *} ++multiplies both sides of the equation by two. Note that just ++@kbd{2 *} would not do the same thing; it would produce the formula ++@samp{2 (a = b)} which represents 2 if the equality is true or ++zero if not. ++ ++The @code{eq} function with more than two arguments (e.g., @kbd{C-u 3 a =} ++or @samp{a = b = c}) tests if all of its arguments are equal. In ++algebraic notation, the @samp{=} operator is unusual in that it is ++neither left- nor right-associative: @samp{a = b = c} is not the ++same as @samp{(a = b) = c} or @samp{a = (b = c)} (which each compare ++one variable with the 1 or 0 that results from comparing two other ++variables). ++ ++@kindex a # ++@pindex calc-not-equal-to ++@tindex neq ++@tindex != ++The @kbd{a #} (@code{calc-not-equal-to}) command, or @samp{neq(a,b)} or ++@samp{a != b} function, is true if @expr{a} and @expr{b} are not equal. ++This also works with more than two arguments; @samp{a != b != c != d} ++tests that all four of @expr{a}, @expr{b}, @expr{c}, and @expr{d} are ++distinct numbers. ++ ++@kindex a < ++@tindex lt ++@ignore ++@mindex @idots ++@end ignore ++@kindex a > ++@ignore ++@mindex @null ++@end ignore ++@kindex a [ ++@ignore ++@mindex @null ++@end ignore ++@kindex a ] ++@pindex calc-less-than ++@pindex calc-greater-than ++@pindex calc-less-equal ++@pindex calc-greater-equal ++@ignore ++@mindex @null ++@end ignore ++@tindex gt ++@ignore ++@mindex @null ++@end ignore ++@tindex leq ++@ignore ++@mindex @null ++@end ignore ++@tindex geq ++@ignore ++@mindex @null ++@end ignore ++@tindex < ++@ignore ++@mindex @null ++@end ignore ++@tindex > ++@ignore ++@mindex @null ++@end ignore ++@tindex <= ++@ignore ++@mindex @null ++@end ignore ++@tindex >= ++The @kbd{a <} (@code{calc-less-than}) [@samp{lt(a,b)} or @samp{a < b}] ++operation is true if @expr{a} is less than @expr{b}. Similar functions ++are @kbd{a >} (@code{calc-greater-than}) [@samp{gt(a,b)} or @samp{a > b}], ++@kbd{a [} (@code{calc-less-equal}) [@samp{leq(a,b)} or @samp{a <= b}], and ++@kbd{a ]} (@code{calc-greater-equal}) [@samp{geq(a,b)} or @samp{a >= b}]. ++ ++While the inequality functions like @code{lt} do not accept more ++than two arguments, the syntax @w{@samp{a <= b < c}} is translated to an ++equivalent expression involving intervals: @samp{b in [a .. c)}. ++(See the description of @code{in} below.) All four combinations ++of @samp{<} and @samp{<=} are allowed, or any of the four combinations ++of @samp{>} and @samp{>=}. Four-argument constructions like ++@samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that ++involve both equalities and inequalities, are not allowed. ++ ++@kindex a . ++@pindex calc-remove-equal ++@tindex rmeq ++The @kbd{a .} (@code{calc-remove-equal}) [@code{rmeq}] command extracts ++the righthand side of the equation or inequality on the top of the ++stack. It also works elementwise on vectors. For example, if ++@samp{[x = 2.34, y = z / 2]} is on the stack, then @kbd{a .} produces ++@samp{[2.34, z / 2]}. As a special case, if the righthand side is a ++variable and the lefthand side is a number (as in @samp{2.34 = x}), then ++Calc keeps the lefthand side instead. Finally, this command works with ++assignments @samp{x := 2.34} as well as equations, always taking the ++righthand side, and for @samp{=>} (evaluates-to) operators, always ++taking the lefthand side. ++ ++@kindex a & ++@pindex calc-logical-and ++@tindex land ++@tindex && ++The @kbd{a &} (@code{calc-logical-and}) [@samp{land(a,b)} or @samp{a && b}] ++function is true if both of its arguments are true, i.e., are ++non-zero numbers. In this case, the result will be either @expr{a} or ++@expr{b}, chosen arbitrarily. If either argument is zero, the result is ++zero. Otherwise, the formula is left in symbolic form. ++ ++@kindex a | ++@pindex calc-logical-or ++@tindex lor ++@tindex || ++The @kbd{a |} (@code{calc-logical-or}) [@samp{lor(a,b)} or @samp{a || b}] ++function is true if either or both of its arguments are true (nonzero). ++The result is whichever argument was nonzero, choosing arbitrarily if both ++are nonzero. If both @expr{a} and @expr{b} are zero, the result is ++zero. ++ ++@kindex a ! ++@pindex calc-logical-not ++@tindex lnot ++@tindex ! ++The @kbd{a !} (@code{calc-logical-not}) [@samp{lnot(a)} or @samp{!@: a}] ++function is true if @expr{a} is false (zero), or false if @expr{a} is ++true (nonzero). It is left in symbolic form if @expr{a} is not a ++number. ++ ++@kindex a : ++@pindex calc-logical-if ++@tindex if ++@ignore ++@mindex ? : ++@end ignore ++@tindex ? ++@ignore ++@mindex @null ++@end ignore ++@tindex : ++@cindex Arguments, not evaluated ++The @kbd{a :} (@code{calc-logical-if}) [@samp{if(a,b,c)} or @samp{a ? b :@: c}] ++function is equal to either @expr{b} or @expr{c} if @expr{a} is a nonzero ++number or zero, respectively. If @expr{a} is not a number, the test is ++left in symbolic form and neither @expr{b} nor @expr{c} is evaluated in ++any way. In algebraic formulas, this is one of the few Calc functions ++whose arguments are not automatically evaluated when the function itself ++is evaluated. The others are @code{lambda}, @code{quote}, and ++@code{condition}. ++ ++One minor surprise to watch out for is that the formula @samp{a?3:4} ++will not work because the @samp{3:4} is parsed as a fraction instead of ++as three separate symbols. Type something like @samp{a ? 3 : 4} or ++@samp{a?(3):4} instead. ++ ++As a special case, if @expr{a} evaluates to a vector, then both @expr{b} ++and @expr{c} are evaluated; the result is a vector of the same length ++as @expr{a} whose elements are chosen from corresponding elements of ++@expr{b} and @expr{c} according to whether each element of @expr{a} ++is zero or nonzero. Each of @expr{b} and @expr{c} must be either a ++vector of the same length as @expr{a}, or a non-vector which is matched ++with all elements of @expr{a}. ++ ++@kindex a @{ ++@pindex calc-in-set ++@tindex in ++The @kbd{a @{} (@code{calc-in-set}) [@samp{in(a,b)}] function is true if ++the number @expr{a} is in the set of numbers represented by @expr{b}. ++If @expr{b} is an interval form, @expr{a} must be one of the values ++encompassed by the interval. If @expr{b} is a vector, @expr{a} must be ++equal to one of the elements of the vector. (If any vector elements are ++intervals, @expr{a} must be in any of the intervals.) If @expr{b} is a ++plain number, @expr{a} must be numerically equal to @expr{b}. ++@xref{Set Operations}, for a group of commands that manipulate sets ++of this sort. ++ ++@ignore ++@starindex ++@end ignore ++@tindex typeof ++The @samp{typeof(a)} function produces an integer or variable which ++characterizes @expr{a}. If @expr{a} is a number, vector, or variable, ++the result will be one of the following numbers: ++ ++@example ++ 1 Integer ++ 2 Fraction ++ 3 Floating-point number ++ 4 HMS form ++ 5 Rectangular complex number ++ 6 Polar complex number ++ 7 Error form ++ 8 Interval form ++ 9 Modulo form ++10 Date-only form ++11 Date/time form ++12 Infinity (inf, uinf, or nan) ++100 Variable ++101 Vector (but not a matrix) ++102 Matrix ++@end example ++ ++Otherwise, @expr{a} is a formula, and the result is a variable which ++represents the name of the top-level function call. ++ ++@ignore ++@starindex ++@end ignore ++@tindex integer ++@ignore ++@starindex ++@end ignore ++@tindex real ++@ignore ++@starindex ++@end ignore ++@tindex constant ++The @samp{integer(a)} function returns true if @expr{a} is an integer. ++The @samp{real(a)} function ++is true if @expr{a} is a real number, either integer, fraction, or ++float. The @samp{constant(a)} function returns true if @expr{a} is ++any of the objects for which @code{typeof} would produce an integer ++code result except for variables, and provided that the components of ++an object like a vector or error form are themselves constant. ++Note that infinities do not satisfy any of these tests, nor do ++special constants like @code{pi} and @code{e}. ++ ++@xref{Declarations}, for a set of similar functions that recognize ++formulas as well as actual numbers. For example, @samp{dint(floor(x))} ++is true because @samp{floor(x)} is provably integer-valued, but ++@samp{integer(floor(x))} does not because @samp{floor(x)} is not ++literally an integer constant. ++ ++@ignore ++@starindex ++@end ignore ++@tindex refers ++The @samp{refers(a,b)} function is true if the variable (or sub-expression) ++@expr{b} appears in @expr{a}, or false otherwise. Unlike the other ++tests described here, this function returns a definite ``no'' answer ++even if its arguments are still in symbolic form. The only case where ++@code{refers} will be left unevaluated is if @expr{a} is a plain ++variable (different from @expr{b}). ++ ++@ignore ++@starindex ++@end ignore ++@tindex negative ++The @samp{negative(a)} function returns true if @expr{a} ``looks'' negative, ++because it is a negative number, because it is of the form @expr{-x}, ++or because it is a product or quotient with a term that looks negative. ++This is most useful in rewrite rules. Beware that @samp{negative(a)} ++evaluates to 1 or 0 for @emph{any} argument @expr{a}, so it can only ++be stored in a formula if the default simplifications are turned off ++first with @kbd{m O} (or if it appears in an unevaluated context such ++as a rewrite rule condition). ++ ++@ignore ++@starindex ++@end ignore ++@tindex variable ++The @samp{variable(a)} function is true if @expr{a} is a variable, ++or false if not. If @expr{a} is a function call, this test is left ++in symbolic form. Built-in variables like @code{pi} and @code{inf} ++are considered variables like any others by this test. ++ ++@ignore ++@starindex ++@end ignore ++@tindex nonvar ++The @samp{nonvar(a)} function is true if @expr{a} is a non-variable. ++If its argument is a variable it is left unsimplified; it never ++actually returns zero. However, since Calc's condition-testing ++commands consider ``false'' anything not provably true, this is ++often good enough. ++ ++@ignore ++@starindex ++@end ignore ++@tindex lin ++@ignore ++@starindex ++@end ignore ++@tindex linnt ++@ignore ++@starindex ++@end ignore ++@tindex islin ++@ignore ++@starindex ++@end ignore ++@tindex islinnt ++@cindex Linearity testing ++The functions @code{lin}, @code{linnt}, @code{islin}, and @code{islinnt} ++check if an expression is ``linear,'' i.e., can be written in the form ++@expr{a + b x} for some constants @expr{a} and @expr{b}, and some ++variable or subformula @expr{x}. The function @samp{islin(f,x)} checks ++if formula @expr{f} is linear in @expr{x}, returning 1 if so. For ++example, @samp{islin(x,x)}, @samp{islin(-x,x)}, @samp{islin(3,x)}, and ++@samp{islin(x y / 3 - 2, x)} all return 1. The @samp{lin(f,x)} function ++is similar, except that instead of returning 1 it returns the vector ++@expr{[a, b, x]}. For the above examples, this vector would be ++@expr{[0, 1, x]}, @expr{[0, -1, x]}, @expr{[3, 0, x]}, and ++@expr{[-2, y/3, x]}, respectively. Both @code{lin} and @code{islin} ++generally remain unevaluated for expressions which are not linear, ++e.g., @samp{lin(2 x^2, x)} and @samp{lin(sin(x), x)}. The second ++argument can also be a formula; @samp{islin(2 + 3 sin(x), sin(x))} ++returns true. ++ ++The @code{linnt} and @code{islinnt} functions perform a similar check, ++but require a ``non-trivial'' linear form, which means that the ++@expr{b} coefficient must be non-zero. For example, @samp{lin(2,x)} ++returns @expr{[2, 0, x]} and @samp{lin(y,x)} returns @expr{[y, 0, x]}, ++but @samp{linnt(2,x)} and @samp{linnt(y,x)} are left unevaluated ++(in other words, these formulas are considered to be only ``trivially'' ++linear in @expr{x}). ++ ++All four linearity-testing functions allow you to omit the second ++argument, in which case the input may be linear in any non-constant ++formula. Here, the @expr{a=0}, @expr{b=1} case is also considered ++trivial, and only constant values for @expr{a} and @expr{b} are ++recognized. Thus, @samp{lin(2 x y)} returns @expr{[0, 2, x y]}, ++@samp{lin(2 - x y)} returns @expr{[2, -1, x y]}, and @samp{lin(x y)} ++returns @expr{[0, 1, x y]}. The @code{linnt} function would allow the ++first two cases but not the third. Also, neither @code{lin} nor ++@code{linnt} accept plain constants as linear in the one-argument ++case: @samp{islin(2,x)} is true, but @samp{islin(2)} is false. ++ ++@ignore ++@starindex ++@end ignore ++@tindex istrue ++The @samp{istrue(a)} function returns 1 if @expr{a} is a nonzero ++number or provably nonzero formula, or 0 if @expr{a} is anything else. ++Calls to @code{istrue} can only be manipulated if @kbd{m O} mode is ++used to make sure they are not evaluated prematurely. (Note that ++declarations are used when deciding whether a formula is true; ++@code{istrue} returns 1 when @code{dnonzero} would return 1, and ++it returns 0 when @code{dnonzero} would return 0 or leave itself ++in symbolic form.) ++ ++@node Rewrite Rules, , Logical Operations, Algebra ++@section Rewrite Rules ++ ++@noindent ++@cindex Rewrite rules ++@cindex Transformations ++@cindex Pattern matching ++@kindex a r ++@pindex calc-rewrite ++@tindex rewrite ++The @kbd{a r} (@code{calc-rewrite}) [@code{rewrite}] command makes ++substitutions in a formula according to a specified pattern or patterns ++known as @dfn{rewrite rules}. Whereas @kbd{a b} (@code{calc-substitute}) ++matches literally, so that substituting @samp{sin(x)} with @samp{cos(x)} ++matches only the @code{sin} function applied to the variable @code{x}, ++rewrite rules match general kinds of formulas; rewriting using the rule ++@samp{sin(x) := cos(x)} matches @code{sin} of any argument and replaces ++it with @code{cos} of that same argument. The only significance of the ++name @code{x} is that the same name is used on both sides of the rule. ++ ++Rewrite rules rearrange formulas already in Calc's memory. ++@xref{Syntax Tables}, to read about @dfn{syntax rules}, which are ++similar to algebraic rewrite rules but operate when new algebraic ++entries are being parsed, converting strings of characters into ++Calc formulas. ++ ++@menu ++* Entering Rewrite Rules:: ++* Basic Rewrite Rules:: ++* Conditional Rewrite Rules:: ++* Algebraic Properties of Rewrite Rules:: ++* Other Features of Rewrite Rules:: ++* Composing Patterns in Rewrite Rules:: ++* Nested Formulas with Rewrite Rules:: ++* Multi-Phase Rewrite Rules:: ++* Selections with Rewrite Rules:: ++* Matching Commands:: ++* Automatic Rewrites:: ++* Debugging Rewrites:: ++* Examples of Rewrite Rules:: ++@end menu ++ ++@node Entering Rewrite Rules, Basic Rewrite Rules, Rewrite Rules, Rewrite Rules ++@subsection Entering Rewrite Rules ++ ++@noindent ++Rewrite rules normally use the ``assignment'' operator ++@samp{@var{old} := @var{new}}. ++This operator is equivalent to the function call @samp{assign(old, new)}. ++The @code{assign} function is undefined by itself in Calc, so an ++assignment formula such as a rewrite rule will be left alone by ordinary ++Calc commands. But certain commands, like the rewrite system, interpret ++assignments in special ways. ++ ++For example, the rule @samp{sin(x)^2 := 1-cos(x)^2} says to replace ++every occurrence of the sine of something, squared, with one minus the ++square of the cosine of that same thing. All by itself as a formula ++on the stack it does nothing, but when given to the @kbd{a r} command ++it turns that command into a sine-squared-to-cosine-squared converter. ++ ++To specify a set of rules to be applied all at once, make a vector of ++rules. ++ ++When @kbd{a r} prompts you to enter the rewrite rules, you can answer ++in several ways: ++ ++@enumerate ++@item ++With a rule: @kbd{f(x) := g(x) @key{RET}}. ++@item ++With a vector of rules: @kbd{[f1(x) := g1(x), f2(x) := g2(x)] @key{RET}}. ++(You can omit the enclosing square brackets if you wish.) ++@item ++With the name of a variable that contains the rule or rules vector: ++@kbd{myrules @key{RET}}. ++@item ++With any formula except a rule, a vector, or a variable name; this ++will be interpreted as the @var{old} half of a rewrite rule, ++and you will be prompted a second time for the @var{new} half: ++@kbd{f(x) @key{RET} g(x) @key{RET}}. ++@item ++With a blank line, in which case the rule, rules vector, or variable ++will be taken from the top of the stack (and the formula to be ++rewritten will come from the second-to-top position). ++@end enumerate ++ ++If you enter the rules directly (as opposed to using rules stored ++in a variable), those rules will be put into the Trail so that you ++can retrieve them later. @xref{Trail Commands}. ++ ++It is most convenient to store rules you use often in a variable and ++invoke them by giving the variable name. The @kbd{s e} ++(@code{calc-edit-variable}) command is an easy way to create or edit a ++rule set stored in a variable. You may also wish to use @kbd{s p} ++(@code{calc-permanent-variable}) to save your rules permanently; ++@pxref{Operations on Variables}. ++ ++Rewrite rules are compiled into a special internal form for faster ++matching. If you enter a rule set directly it must be recompiled ++every time. If you store the rules in a variable and refer to them ++through that variable, they will be compiled once and saved away ++along with the variable for later reference. This is another good ++reason to store your rules in a variable. ++ ++Calc also accepts an obsolete notation for rules, as vectors ++@samp{[@var{old}, @var{new}]}. But because it is easily confused with a ++vector of two rules, the use of this notation is no longer recommended. ++ ++@node Basic Rewrite Rules, Conditional Rewrite Rules, Entering Rewrite Rules, Rewrite Rules ++@subsection Basic Rewrite Rules ++ ++@noindent ++To match a particular formula @expr{x} with a particular rewrite rule ++@samp{@var{old} := @var{new}}, Calc compares the structure of @expr{x} with ++the structure of @var{old}. Variables that appear in @var{old} are ++treated as @dfn{meta-variables}; the corresponding positions in @expr{x} ++may contain any sub-formulas. For example, the pattern @samp{f(x,y)} ++would match the expression @samp{f(12, a+1)} with the meta-variable ++@samp{x} corresponding to 12 and with @samp{y} corresponding to ++@samp{a+1}. However, this pattern would not match @samp{f(12)} or ++@samp{g(12, a+1)}, since there is no assignment of the meta-variables ++that will make the pattern match these expressions. Notice that if ++the pattern is a single meta-variable, it will match any expression. ++ ++If a given meta-variable appears more than once in @var{old}, the ++corresponding sub-formulas of @expr{x} must be identical. Thus ++the pattern @samp{f(x,x)} would match @samp{f(12, 12)} and ++@samp{f(a+1, a+1)} but not @samp{f(12, a+1)} or @samp{f(a+b, b+a)}. ++(@xref{Conditional Rewrite Rules}, for a way to match the latter.) ++ ++Things other than variables must match exactly between the pattern ++and the target formula. To match a particular variable exactly, use ++the pseudo-function @samp{quote(v)} in the pattern. For example, the ++pattern @samp{x+quote(y)} matches @samp{x+y}, @samp{2+y}, or ++@samp{sin(a)+y}. ++ ++The special variable names @samp{e}, @samp{pi}, @samp{i}, @samp{phi}, ++@samp{gamma}, @samp{inf}, @samp{uinf}, and @samp{nan} always match ++literally. Thus the pattern @samp{sin(d + e + f)} acts exactly like ++@samp{sin(d + quote(e) + f)}. ++ ++If the @var{old} pattern is found to match a given formula, that ++formula is replaced by @var{new}, where any occurrences in @var{new} ++of meta-variables from the pattern are replaced with the sub-formulas ++that they matched. Thus, applying the rule @samp{f(x,y) := g(y+x,x)} ++to @samp{f(12, a+1)} would produce @samp{g(a+13, 12)}. ++ ++The normal @kbd{a r} command applies rewrite rules over and over ++throughout the target formula until no further changes are possible ++(up to a limit of 100 times). Use @kbd{C-u 1 a r} to make only one ++change at a time. ++ ++@node Conditional Rewrite Rules, Algebraic Properties of Rewrite Rules, Basic Rewrite Rules, Rewrite Rules ++@subsection Conditional Rewrite Rules ++ ++@noindent ++A rewrite rule can also be @dfn{conditional}, written in the form ++@samp{@var{old} := @var{new} :: @var{cond}}. (There is also the obsolete ++form @samp{[@var{old}, @var{new}, @var{cond}]}.) If a @var{cond} part ++is present in the ++rule, this is an additional condition that must be satisfied before ++the rule is accepted. Once @var{old} has been successfully matched ++to the target expression, @var{cond} is evaluated (with all the ++meta-variables substituted for the values they matched) and simplified ++with @kbd{a s} (@code{calc-simplify}). If the result is a nonzero ++number or any other object known to be nonzero (@pxref{Declarations}), ++the rule is accepted. If the result is zero or if it is a symbolic ++formula that is not known to be nonzero, the rule is rejected. ++@xref{Logical Operations}, for a number of functions that return ++1 or 0 according to the results of various tests. ++ ++For example, the formula @samp{n > 0} simplifies to 1 or 0 if @expr{n} ++is replaced by a positive or nonpositive number, respectively (or if ++@expr{n} has been declared to be positive or nonpositive). Thus, ++the rule @samp{f(x,y) := g(y+x,x) :: x+y > 0} would apply to ++@samp{f(0, 4)} but not to @samp{f(-3, 2)} or @samp{f(12, a+1)} ++(assuming no outstanding declarations for @expr{a}). In the case of ++@samp{f(-3, 2)}, the condition can be shown not to be satisfied; in ++the case of @samp{f(12, a+1)}, the condition merely cannot be shown ++to be satisfied, but that is enough to reject the rule. ++ ++While Calc will use declarations to reason about variables in the ++formula being rewritten, declarations do not apply to meta-variables. ++For example, the rule @samp{f(a) := g(a+1)} will match for any values ++of @samp{a}, such as complex numbers, vectors, or formulas, even if ++@samp{a} has been declared to be real or scalar. If you want the ++meta-variable @samp{a} to match only literal real numbers, use ++@samp{f(a) := g(a+1) :: real(a)}. If you want @samp{a} to match only ++reals and formulas which are provably real, use @samp{dreal(a)} as ++the condition. ++ ++The @samp{::} operator is a shorthand for the @code{condition} ++function; @samp{@var{old} := @var{new} :: @var{cond}} is equivalent to ++the formula @samp{condition(assign(@var{old}, @var{new}), @var{cond})}. ++ ++If you have several conditions, you can use @samp{... :: c1 :: c2 :: c3} ++or @samp{... :: c1 && c2 && c3}. The two are entirely equivalent. ++ ++It is also possible to embed conditions inside the pattern: ++@samp{f(x :: x>0, y) := g(y+x, x)}. This is purely a notational ++convenience, though; where a condition appears in a rule has no ++effect on when it is tested. The rewrite-rule compiler automatically ++decides when it is best to test each condition while a rule is being ++matched. ++ ++Certain conditions are handled as special cases by the rewrite rule ++system and are tested very efficiently: Where @expr{x} is any ++meta-variable, these conditions are @samp{integer(x)}, @samp{real(x)}, ++@samp{constant(x)}, @samp{negative(x)}, @samp{x >= y} where @expr{y} ++is either a constant or another meta-variable and @samp{>=} may be ++replaced by any of the six relational operators, and @samp{x % a = b} ++where @expr{a} and @expr{b} are constants. Other conditions, like ++@samp{x >= y+1} or @samp{dreal(x)}, will be less efficient to check ++since Calc must bring the whole evaluator and simplifier into play. ++ ++An interesting property of @samp{::} is that neither of its arguments ++will be touched by Calc's default simplifications. This is important ++because conditions often are expressions that cannot safely be ++evaluated early. For example, the @code{typeof} function never ++remains in symbolic form; entering @samp{typeof(a)} will put the ++number 100 (the type code for variables like @samp{a}) on the stack. ++But putting the condition @samp{... :: typeof(a) = 6} on the stack ++is safe since @samp{::} prevents the @code{typeof} from being ++evaluated until the condition is actually used by the rewrite system. ++ ++Since @samp{::} protects its lefthand side, too, you can use a dummy ++condition to protect a rule that must itself not evaluate early. ++For example, it's not safe to put @samp{a(f,x) := apply(f, [x])} on ++the stack because it will immediately evaluate to @samp{a(f,x) := f(x)}, ++where the meta-variable-ness of @code{f} on the righthand side has been ++lost. But @samp{a(f,x) := apply(f, [x]) :: 1} is safe, and of course ++the condition @samp{1} is always true (nonzero) so it has no effect on ++the functioning of the rule. (The rewrite compiler will ensure that ++it doesn't even impact the speed of matching the rule.) ++ ++@node Algebraic Properties of Rewrite Rules, Other Features of Rewrite Rules, Conditional Rewrite Rules, Rewrite Rules ++@subsection Algebraic Properties of Rewrite Rules ++ ++@noindent ++The rewrite mechanism understands the algebraic properties of functions ++like @samp{+} and @samp{*}. In particular, pattern matching takes ++the associativity and commutativity of the following functions into ++account: ++ ++@smallexample +++ - * = != && || and or xor vint vunion vxor gcd lcm max min beta ++@end smallexample ++ ++For example, the rewrite rule: ++ ++@example ++a x + b x := (a + b) x ++@end example ++ ++@noindent ++will match formulas of the form, ++ ++@example ++a x + b x, x a + x b, a x + x b, x a + b x ++@end example ++ ++Rewrites also understand the relationship between the @samp{+} and @samp{-} ++operators. The above rewrite rule will also match the formulas, ++ ++@example ++a x - b x, x a - x b, a x - x b, x a - b x ++@end example ++ ++@noindent ++by matching @samp{b} in the pattern to @samp{-b} from the formula. ++ ++Applied to a sum of many terms like @samp{r + a x + s + b x + t}, this ++pattern will check all pairs of terms for possible matches. The rewrite ++will take whichever suitable pair it discovers first. ++ ++In general, a pattern using an associative operator like @samp{a + b} ++will try @var{2 n} different ways to match a sum of @var{n} terms ++like @samp{x + y + z - w}. First, @samp{a} is matched against each ++of @samp{x}, @samp{y}, @samp{z}, and @samp{-w} in turn, with @samp{b} ++being matched to the remainders @samp{y + z - w}, @samp{x + z - w}, etc. ++If none of these succeed, then @samp{b} is matched against each of the ++four terms with @samp{a} matching the remainder. Half-and-half matches, ++like @samp{(x + y) + (z - w)}, are not tried. ++ ++Note that @samp{*} is not commutative when applied to matrices, but ++rewrite rules pretend that it is. If you type @kbd{m v} to enable ++Matrix mode (@pxref{Matrix Mode}), rewrite rules will match @samp{*} ++literally, ignoring its usual commutativity property. (In the ++current implementation, the associativity also vanishes---it is as ++if the pattern had been enclosed in a @code{plain} marker; see below.) ++If you are applying rewrites to formulas with matrices, it's best to ++enable Matrix mode first to prevent algebraically incorrect rewrites ++from occurring. ++ ++The pattern @samp{-x} will actually match any expression. For example, ++the rule ++ ++@example ++f(-x) := -f(x) ++@end example ++ ++@noindent ++will rewrite @samp{f(a)} to @samp{-f(-a)}. To avoid this, either use ++a @code{plain} marker as described below, or add a @samp{negative(x)} ++condition. The @code{negative} function is true if its argument ++``looks'' negative, for example, because it is a negative number or ++because it is a formula like @samp{-x}. The new rule using this ++condition is: ++ ++@example ++f(x) := -f(-x) :: negative(x) @r{or, equivalently,} ++f(-x) := -f(x) :: negative(-x) ++@end example ++ ++In the same way, the pattern @samp{x - y} will match the sum @samp{a + b} ++by matching @samp{y} to @samp{-b}. ++ ++The pattern @samp{a b} will also match the formula @samp{x/y} if ++@samp{y} is a number. Thus the rule @samp{a x + @w{b x} := (a+b) x} ++will also convert @samp{a x + x / 2} to @samp{(a + 0.5) x} (or ++@samp{(a + 1:2) x}, depending on the current fraction mode). ++ ++Calc will @emph{not} take other liberties with @samp{*}, @samp{/}, and ++@samp{^}. For example, the pattern @samp{f(a b)} will not match ++@samp{f(x^2)}, and @samp{f(a + b)} will not match @samp{f(2 x)}, even ++though conceivably these patterns could match with @samp{a = b = x}. ++Nor will @samp{f(a b)} match @samp{f(x / y)} if @samp{y} is not a ++constant, even though it could be considered to match with @samp{a = x} ++and @samp{b = 1/y}. The reasons are partly for efficiency, and partly ++because while few mathematical operations are substantively different ++for addition and subtraction, often it is preferable to treat the cases ++of multiplication, division, and integer powers separately. ++ ++Even more subtle is the rule set ++ ++@example ++[ f(a) + f(b) := f(a + b), -f(a) := f(-a) ] ++@end example ++ ++@noindent ++attempting to match @samp{f(x) - f(y)}. You might think that Calc ++will view this subtraction as @samp{f(x) + (-f(y))} and then apply ++the above two rules in turn, but actually this will not work because ++Calc only does this when considering rules for @samp{+} (like the ++first rule in this set). So it will see first that @samp{f(x) + (-f(y))} ++does not match @samp{f(a) + f(b)} for any assignments of the ++meta-variables, and then it will see that @samp{f(x) - f(y)} does ++not match @samp{-f(a)} for any assignment of @samp{a}. Because Calc ++tries only one rule at a time, it will not be able to rewrite ++@samp{f(x) - f(y)} with this rule set. An explicit @samp{f(a) - f(b)} ++rule will have to be added. ++ ++Another thing patterns will @emph{not} do is break up complex numbers. ++The pattern @samp{myconj(a + @w{b i)} := a - b i} will work for formulas ++involving the special constant @samp{i} (such as @samp{3 - 4 i}), but ++it will not match actual complex numbers like @samp{(3, -4)}. A version ++of the above rule for complex numbers would be ++ ++@example ++myconj(a) := re(a) - im(a) (0,1) :: im(a) != 0 ++@end example ++ ++@noindent ++(Because the @code{re} and @code{im} functions understand the properties ++of the special constant @samp{i}, this rule will also work for ++@samp{3 - 4 i}. In fact, this particular rule would probably be better ++without the @samp{im(a) != 0} condition, since if @samp{im(a) = 0} the ++righthand side of the rule will still give the correct answer for the ++conjugate of a real number.) ++ ++It is also possible to specify optional arguments in patterns. The rule ++ ++@example ++opt(a) x + opt(b) (x^opt(c) + opt(d)) := f(a, b, c, d) ++@end example ++ ++@noindent ++will match the formula ++ ++@example ++5 (x^2 - 4) + 3 x ++@end example ++ ++@noindent ++in a fairly straightforward manner, but it will also match reduced ++formulas like ++ ++@example ++x + x^2, 2(x + 1) - x, x + x ++@end example ++ ++@noindent ++producing, respectively, ++ ++@example ++f(1, 1, 2, 0), f(-1, 2, 1, 1), f(1, 1, 1, 0) ++@end example ++ ++(The latter two formulas can be entered only if default simplifications ++have been turned off with @kbd{m O}.) ++ ++The default value for a term of a sum is zero. The default value ++for a part of a product, for a power, or for the denominator of a ++quotient, is one. Also, @samp{-x} matches the pattern @samp{opt(a) b} ++with @samp{a = -1}. ++ ++In particular, the distributive-law rule can be refined to ++ ++@example ++opt(a) x + opt(b) x := (a + b) x ++@end example ++ ++@noindent ++so that it will convert, e.g., @samp{a x - x}, to @samp{(a - 1) x}. ++ ++The pattern @samp{opt(a) + opt(b) x} matches almost any formulas which ++are linear in @samp{x}. You can also use the @code{lin} and @code{islin} ++functions with rewrite conditions to test for this; @pxref{Logical ++Operations}. These functions are not as convenient to use in rewrite ++rules, but they recognize more kinds of formulas as linear: ++@samp{x/z} is considered linear with @expr{b = 1/z} by @code{lin}, ++but it will not match the above pattern because that pattern calls ++for a multiplication, not a division. ++ ++As another example, the obvious rule to replace @samp{sin(x)^2 + cos(x)^2} ++by 1, ++ ++@example ++sin(x)^2 + cos(x)^2 := 1 ++@end example ++ ++@noindent ++misses many cases because the sine and cosine may both be multiplied by ++an equal factor. Here's a more successful rule: ++ ++@example ++opt(a) sin(x)^2 + opt(a) cos(x)^2 := a ++@end example ++ ++Note that this rule will @emph{not} match @samp{sin(x)^2 + 6 cos(x)^2} ++because one @expr{a} would have ``matched'' 1 while the other matched 6. ++ ++Calc automatically converts a rule like ++ ++@example ++f(x-1, x) := g(x) ++@end example ++ ++@noindent ++into the form ++ ++@example ++f(temp, x) := g(x) :: temp = x-1 ++@end example ++ ++@noindent ++(where @code{temp} stands for a new, invented meta-variable that ++doesn't actually have a name). This modified rule will successfully ++match @samp{f(6, 7)}, binding @samp{temp} and @samp{x} to 6 and 7, ++respectively, then verifying that they differ by one even though ++@samp{6} does not superficially look like @samp{x-1}. ++ ++However, Calc does not solve equations to interpret a rule. The ++following rule, ++ ++@example ++f(x-1, x+1) := g(x) ++@end example ++ ++@noindent ++will not work. That is, it will match @samp{f(a - 1 + b, a + 1 + b)} ++but not @samp{f(6, 8)}. Calc always interprets at least one occurrence ++of a variable by literal matching. If the variable appears ``isolated'' ++then Calc is smart enough to use it for literal matching. But in this ++last example, Calc is forced to rewrite the rule to @samp{f(x-1, temp) ++:= g(x) :: temp = x+1} where the @samp{x-1} term must correspond to an ++actual ``something-minus-one'' in the target formula. ++ ++A successful way to write this would be @samp{f(x, x+2) := g(x+1)}. ++You could make this resemble the original form more closely by using ++@code{let} notation, which is described in the next section: ++ ++@example ++f(xm1, x+1) := g(x) :: let(x := xm1+1) ++@end example ++ ++Calc does this rewriting or ``conditionalizing'' for any sub-pattern ++which involves only the functions in the following list, operating ++only on constants and meta-variables which have already been matched ++elsewhere in the pattern. When matching a function call, Calc is ++careful to match arguments which are plain variables before arguments ++which are calls to any of the functions below, so that a pattern like ++@samp{f(x-1, x)} can be conditionalized even though the isolated ++@samp{x} comes after the @samp{x-1}. ++ ++@smallexample +++ - * / \ % ^ abs sign round rounde roundu trunc floor ceil ++max min re im conj arg ++@end smallexample ++ ++You can suppress all of the special treatments described in this ++section by surrounding a function call with a @code{plain} marker. ++This marker causes the function call which is its argument to be ++matched literally, without regard to commutativity, associativity, ++negation, or conditionalization. When you use @code{plain}, the ++``deep structure'' of the formula being matched can show through. ++For example, ++ ++@example ++plain(a - a b) := f(a, b) ++@end example ++ ++@noindent ++will match only literal subtractions. However, the @code{plain} ++marker does not affect its arguments' arguments. In this case, ++commutativity and associativity is still considered while matching ++the @w{@samp{a b}} sub-pattern, so the whole pattern will match ++@samp{x - y x} as well as @samp{x - x y}. We could go still ++further and use ++ ++@example ++plain(a - plain(a b)) := f(a, b) ++@end example ++ ++@noindent ++which would do a completely strict match for the pattern. ++ ++By contrast, the @code{quote} marker means that not only the ++function name but also the arguments must be literally the same. ++The above pattern will match @samp{x - x y} but ++ ++@example ++quote(a - a b) := f(a, b) ++@end example ++ ++@noindent ++will match only the single formula @samp{a - a b}. Also, ++ ++@example ++quote(a - quote(a b)) := f(a, b) ++@end example ++ ++@noindent ++will match only @samp{a - quote(a b)}---probably not the desired ++effect! ++ ++A certain amount of algebra is also done when substituting the ++meta-variables on the righthand side of a rule. For example, ++in the rule ++ ++@example ++a + f(b) := f(a + b) ++@end example ++ ++@noindent ++matching @samp{f(x) - y} would produce @samp{f((-y) + x)} if ++taken literally, but the rewrite mechanism will simplify the ++righthand side to @samp{f(x - y)} automatically. (Of course, ++the default simplifications would do this anyway, so this ++special simplification is only noticeable if you have turned the ++default simplifications off.) This rewriting is done only when ++a meta-variable expands to a ``negative-looking'' expression. ++If this simplification is not desirable, you can use a @code{plain} ++marker on the righthand side: ++ ++@example ++a + f(b) := f(plain(a + b)) ++@end example ++ ++@noindent ++In this example, we are still allowing the pattern-matcher to ++use all the algebra it can muster, but the righthand side will ++always simplify to a literal addition like @samp{f((-y) + x)}. ++ ++@node Other Features of Rewrite Rules, Composing Patterns in Rewrite Rules, Algebraic Properties of Rewrite Rules, Rewrite Rules ++@subsection Other Features of Rewrite Rules ++ ++@noindent ++Certain ``function names'' serve as markers in rewrite rules. ++Here is a complete list of these markers. First are listed the ++markers that work inside a pattern; then come the markers that ++work in the righthand side of a rule. ++ ++@ignore ++@starindex ++@end ignore ++@tindex import ++One kind of marker, @samp{import(x)}, takes the place of a whole ++rule. Here @expr{x} is the name of a variable containing another ++rule set; those rules are ``spliced into'' the rule set that ++imports them. For example, if @samp{[f(a+b) := f(a) + f(b), ++f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF}, ++then the rule set @samp{[f(0) := 0, import(linearF)]} will apply ++all three rules. It is possible to modify the imported rules ++slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports ++the rule set @expr{x} with all occurrences of ++@texline @math{v_1}, ++@infoline @expr{v1}, ++as either a variable name or a function name, replaced with ++@texline @math{x_1} ++@infoline @expr{x1} ++and so on. (If ++@texline @math{v_1} ++@infoline @expr{v1} ++is used as a function name, then ++@texline @math{x_1} ++@infoline @expr{x1} ++must be either a function name itself or a @w{@samp{< >}} nameless ++function; @pxref{Specifying Operators}.) For example, @samp{[g(0) := 0, ++import(linearF, f, g)]} applies the linearity rules to the function ++@samp{g} instead of @samp{f}. Imports can be nested, but the ++import-with-renaming feature may fail to rename sub-imports properly. ++ ++The special functions allowed in patterns are: ++ ++@table @samp ++@item quote(x) ++@ignore ++@starindex ++@end ignore ++@tindex quote ++This pattern matches exactly @expr{x}; variable names in @expr{x} are ++not interpreted as meta-variables. The only flexibility is that ++numbers are compared for numeric equality, so that the pattern ++@samp{f(quote(12))} will match both @samp{f(12)} and @samp{f(12.0)}. ++(Numbers are always treated this way by the rewrite mechanism: ++The rule @samp{f(x,x) := g(x)} will match @samp{f(12, 12.0)}. ++The rewrite may produce either @samp{g(12)} or @samp{g(12.0)} ++as a result in this case.) ++ ++@item plain(x) ++@ignore ++@starindex ++@end ignore ++@tindex plain ++Here @expr{x} must be a function call @samp{f(x1,x2,@dots{})}. This ++pattern matches a call to function @expr{f} with the specified ++argument patterns. No special knowledge of the properties of the ++function @expr{f} is used in this case; @samp{+} is not commutative or ++associative. Unlike @code{quote}, the arguments @samp{x1,x2,@dots{}} ++are treated as patterns. If you wish them to be treated ``plainly'' ++as well, you must enclose them with more @code{plain} markers: ++@samp{plain(plain(@w{-a}) + plain(b c))}. ++ ++@item opt(x,def) ++@ignore ++@starindex ++@end ignore ++@tindex opt ++Here @expr{x} must be a variable name. This must appear as an ++argument to a function or an element of a vector; it specifies that ++the argument or element is optional. ++As an argument to @samp{+}, @samp{-}, @samp{*}, @samp{&&}, or @samp{||}, ++or as the second argument to @samp{/} or @samp{^}, the value @var{def} ++may be omitted. The pattern @samp{x + opt(y)} matches a sum by ++binding one summand to @expr{x} and the other to @expr{y}, and it ++matches anything else by binding the whole expression to @expr{x} and ++zero to @expr{y}. The other operators above work similarly. ++ ++For general miscellaneous functions, the default value @code{def} ++must be specified. Optional arguments are dropped starting with ++the rightmost one during matching. For example, the pattern ++@samp{f(opt(a,0), b, opt(c,b))} will match @samp{f(b)}, @samp{f(a,b)}, ++or @samp{f(a,b,c)}. Default values of zero and @expr{b} are ++supplied in this example for the omitted arguments. Note that ++the literal variable @expr{b} will be the default in the latter ++case, @emph{not} the value that matched the meta-variable @expr{b}. ++In other words, the default @var{def} is effectively quoted. ++ ++@item condition(x,c) ++@ignore ++@starindex ++@end ignore ++@tindex condition ++@tindex :: ++This matches the pattern @expr{x}, with the attached condition ++@expr{c}. It is the same as @samp{x :: c}. ++ ++@item pand(x,y) ++@ignore ++@starindex ++@end ignore ++@tindex pand ++@tindex &&& ++This matches anything that matches both pattern @expr{x} and ++pattern @expr{y}. It is the same as @samp{x &&& y}. ++@pxref{Composing Patterns in Rewrite Rules}. ++ ++@item por(x,y) ++@ignore ++@starindex ++@end ignore ++@tindex por ++@tindex ||| ++This matches anything that matches either pattern @expr{x} or ++pattern @expr{y}. It is the same as @w{@samp{x ||| y}}. ++ ++@item pnot(x) ++@ignore ++@starindex ++@end ignore ++@tindex pnot ++@tindex !!! ++This matches anything that does not match pattern @expr{x}. ++It is the same as @samp{!!! x}. ++ ++@item cons(h,t) ++@ignore ++@mindex cons ++@end ignore ++@tindex cons (rewrites) ++This matches any vector of one or more elements. The first ++element is matched to @expr{h}; a vector of the remaining ++elements is matched to @expr{t}. Note that vectors of fixed ++length can also be matched as actual vectors: The rule ++@samp{cons(a,cons(b,[])) := cons(a+b,[])} is equivalent ++to the rule @samp{[a,b] := [a+b]}. ++ ++@item rcons(t,h) ++@ignore ++@mindex rcons ++@end ignore ++@tindex rcons (rewrites) ++This is like @code{cons}, except that the @emph{last} element ++is matched to @expr{h}, with the remaining elements matched ++to @expr{t}. ++ ++@item apply(f,args) ++@ignore ++@mindex apply ++@end ignore ++@tindex apply (rewrites) ++This matches any function call. The name of the function, in ++the form of a variable, is matched to @expr{f}. The arguments ++of the function, as a vector of zero or more objects, are ++matched to @samp{args}. Constants, variables, and vectors ++do @emph{not} match an @code{apply} pattern. For example, ++@samp{apply(f,x)} matches any function call, @samp{apply(quote(f),x)} ++matches any call to the function @samp{f}, @samp{apply(f,[a,b])} ++matches any function call with exactly two arguments, and ++@samp{apply(quote(f), cons(a,cons(b,x)))} matches any call ++to the function @samp{f} with two or more arguments. Another ++way to implement the latter, if the rest of the rule does not ++need to refer to the first two arguments of @samp{f} by name, ++would be @samp{apply(quote(f), x :: vlen(x) >= 2)}. ++Here's a more interesting sample use of @code{apply}: ++ ++@example ++apply(f,[x+n]) := n + apply(f,[x]) ++ :: in(f, [floor,ceil,round,trunc]) :: integer(n) ++@end example ++ ++Note, however, that this will be slower to match than a rule ++set with four separate rules. The reason is that Calc sorts ++the rules of a rule set according to top-level function name; ++if the top-level function is @code{apply}, Calc must try the ++rule for every single formula and sub-formula. If the top-level ++function in the pattern is, say, @code{floor}, then Calc invokes ++the rule only for sub-formulas which are calls to @code{floor}. ++ ++Formulas normally written with operators like @code{+} are still ++considered function calls: @code{apply(f,x)} matches @samp{a+b} ++with @samp{f = add}, @samp{x = [a,b]}. ++ ++You must use @code{apply} for meta-variables with function names ++on both sides of a rewrite rule: @samp{apply(f, [x]) := f(x+1)} ++is @emph{not} correct, because it rewrites @samp{spam(6)} into ++@samp{f(7)}. The righthand side should be @samp{apply(f, [x+1])}. ++Also note that you will have to use No-Simplify mode (@kbd{m O}) ++when entering this rule so that the @code{apply} isn't ++evaluated immediately to get the new rule @samp{f(x) := f(x+1)}. ++Or, use @kbd{s e} to enter the rule without going through the stack, ++or enter the rule as @samp{apply(f, [x]) := apply(f, [x+1]) @w{:: 1}}. ++@xref{Conditional Rewrite Rules}. ++ ++@item select(x) ++@ignore ++@starindex ++@end ignore ++@tindex select ++This is used for applying rules to formulas with selections; ++@pxref{Selections with Rewrite Rules}. ++@end table ++ ++Special functions for the righthand sides of rules are: ++ ++@table @samp ++@item quote(x) ++The notation @samp{quote(x)} is changed to @samp{x} when the ++righthand side is used. As far as the rewrite rule is concerned, ++@code{quote} is invisible. However, @code{quote} has the special ++property in Calc that its argument is not evaluated. Thus, ++while it will not work to put the rule @samp{t(a) := typeof(a)} ++on the stack because @samp{typeof(a)} is evaluated immediately ++to produce @samp{t(a) := 100}, you can use @code{quote} to ++protect the righthand side: @samp{t(a) := quote(typeof(a))}. ++(@xref{Conditional Rewrite Rules}, for another trick for ++protecting rules from evaluation.) ++ ++@item plain(x) ++Special properties of and simplifications for the function call ++@expr{x} are not used. One interesting case where @code{plain} ++is useful is the rule, @samp{q(x) := quote(x)}, trying to expand a ++shorthand notation for the @code{quote} function. This rule will ++not work as shown; instead of replacing @samp{q(foo)} with ++@samp{quote(foo)}, it will replace it with @samp{foo}! The correct ++rule would be @samp{q(x) := plain(quote(x))}. ++ ++@item cons(h,t) ++Where @expr{t} is a vector, this is converted into an expanded ++vector during rewrite processing. Note that @code{cons} is a regular ++Calc function which normally does this anyway; the only way @code{cons} ++is treated specially by rewrites is that @code{cons} on the righthand ++side of a rule will be evaluated even if default simplifications ++have been turned off. ++ ++@item rcons(t,h) ++Analogous to @code{cons} except putting @expr{h} at the @emph{end} of ++the vector @expr{t}. ++ ++@item apply(f,args) ++Where @expr{f} is a variable and @var{args} is a vector, this ++is converted to a function call. Once again, note that @code{apply} ++is also a regular Calc function. ++ ++@item eval(x) ++@ignore ++@starindex ++@end ignore ++@tindex eval ++The formula @expr{x} is handled in the usual way, then the ++default simplifications are applied to it even if they have ++been turned off normally. This allows you to treat any function ++similarly to the way @code{cons} and @code{apply} are always ++treated. However, there is a slight difference: @samp{cons(2+3, [])} ++with default simplifications off will be converted to @samp{[2+3]}, ++whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}. ++ ++@item evalsimp(x) ++@ignore ++@starindex ++@end ignore ++@tindex evalsimp ++The formula @expr{x} has meta-variables substituted in the usual ++way, then algebraically simplified as if by the @kbd{a s} command. ++ ++@item evalextsimp(x) ++@ignore ++@starindex ++@end ignore ++@tindex evalextsimp ++The formula @expr{x} has meta-variables substituted in the normal ++way, then ``extendedly'' simplified as if by the @kbd{a e} command. ++ ++@item select(x) ++@xref{Selections with Rewrite Rules}. ++@end table ++ ++There are also some special functions you can use in conditions. ++ ++@table @samp ++@item let(v := x) ++@ignore ++@starindex ++@end ignore ++@tindex let ++The expression @expr{x} is evaluated with meta-variables substituted. ++The @kbd{a s} command's simplifications are @emph{not} applied by ++default, but @expr{x} can include calls to @code{evalsimp} or ++@code{evalextsimp} as described above to invoke higher levels ++of simplification. The ++result of @expr{x} is then bound to the meta-variable @expr{v}. As ++usual, if this meta-variable has already been matched to something ++else the two values must be equal; if the meta-variable is new then ++it is bound to the result of the expression. This variable can then ++appear in later conditions, and on the righthand side of the rule. ++In fact, @expr{v} may be any pattern in which case the result of ++evaluating @expr{x} is matched to that pattern, binding any ++meta-variables that appear in that pattern. Note that @code{let} ++can only appear by itself as a condition, or as one term of an ++@samp{&&} which is a whole condition: It cannot be inside ++an @samp{||} term or otherwise buried. ++ ++The alternate, equivalent form @samp{let(v, x)} is also recognized. ++Note that the use of @samp{:=} by @code{let}, while still being ++assignment-like in character, is unrelated to the use of @samp{:=} ++in the main part of a rewrite rule. ++ ++As an example, @samp{f(a) := g(ia) :: let(ia := 1/a) :: constant(ia)} ++replaces @samp{f(a)} with @samp{g} of the inverse of @samp{a}, if ++that inverse exists and is constant. For example, if @samp{a} is a ++singular matrix the operation @samp{1/a} is left unsimplified and ++@samp{constant(ia)} fails, but if @samp{a} is an invertible matrix ++then the rule succeeds. Without @code{let} there would be no way ++to express this rule that didn't have to invert the matrix twice. ++Note that, because the meta-variable @samp{ia} is otherwise unbound ++in this rule, the @code{let} condition itself always ``succeeds'' ++because no matter what @samp{1/a} evaluates to, it can successfully ++be bound to @code{ia}. ++ ++Here's another example, for integrating cosines of linear ++terms: @samp{myint(cos(y),x) := sin(y)/b :: let([a,b,x] := lin(y,x))}. ++The @code{lin} function returns a 3-vector if its argument is linear, ++or leaves itself unevaluated if not. But an unevaluated @code{lin} ++call will not match the 3-vector on the lefthand side of the @code{let}, ++so this @code{let} both verifies that @code{y} is linear, and binds ++the coefficients @code{a} and @code{b} for use elsewhere in the rule. ++(It would have been possible to use @samp{sin(a x + b)/b} for the ++righthand side instead, but using @samp{sin(y)/b} avoids gratuitous ++rearrangement of the argument of the sine.) ++ ++@ignore ++@starindex ++@end ignore ++@tindex ierf ++Similarly, here is a rule that implements an inverse-@code{erf} ++function. It uses @code{root} to search for a solution. If ++@code{root} succeeds, it will return a vector of two numbers ++where the first number is the desired solution. If no solution ++is found, @code{root} remains in symbolic form. So we use ++@code{let} to check that the result was indeed a vector. ++ ++@example ++ierf(x) := y :: let([y,z] := root(erf(a) = x, a, .5)) ++@end example ++ ++@item matches(v,p) ++The meta-variable @var{v}, which must already have been matched ++to something elsewhere in the rule, is compared against pattern ++@var{p}. Since @code{matches} is a standard Calc function, it ++can appear anywhere in a condition. But if it appears alone or ++as a term of a top-level @samp{&&}, then you get the special ++extra feature that meta-variables which are bound to things ++inside @var{p} can be used elsewhere in the surrounding rewrite ++rule. ++ ++The only real difference between @samp{let(p := v)} and ++@samp{matches(v, p)} is that the former evaluates @samp{v} using ++the default simplifications, while the latter does not. ++ ++@item remember ++@vindex remember ++This is actually a variable, not a function. If @code{remember} ++appears as a condition in a rule, then when that rule succeeds ++the original expression and rewritten expression are added to the ++front of the rule set that contained the rule. If the rule set ++was not stored in a variable, @code{remember} is ignored. The ++lefthand side is enclosed in @code{quote} in the added rule if it ++contains any variables. ++ ++For example, the rule @samp{f(n) := n f(n-1) :: remember} applied ++to @samp{f(7)} will add the rule @samp{f(7) := 7 f(6)} to the front ++of the rule set. The rule set @code{EvalRules} works slightly ++differently: There, the evaluation of @samp{f(6)} will complete before ++the result is added to the rule set, in this case as @samp{f(7) := 5040}. ++Thus @code{remember} is most useful inside @code{EvalRules}. ++ ++It is up to you to ensure that the optimization performed by ++@code{remember} is safe. For example, the rule @samp{foo(n) := n ++:: evalv(eatfoo) > 0 :: remember} is a bad idea (@code{evalv} is ++the function equivalent of the @kbd{=} command); if the variable ++@code{eatfoo} ever contains 1, rules like @samp{foo(7) := 7} will ++be added to the rule set and will continue to operate even if ++@code{eatfoo} is later changed to 0. ++ ++@item remember(c) ++@ignore ++@starindex ++@end ignore ++@tindex remember ++Remember the match as described above, but only if condition @expr{c} ++is true. For example, @samp{remember(n % 4 = 0)} in the above factorial ++rule remembers only every fourth result. Note that @samp{remember(1)} ++is equivalent to @samp{remember}, and @samp{remember(0)} has no effect. ++@end table ++ ++@node Composing Patterns in Rewrite Rules, Nested Formulas with Rewrite Rules, Other Features of Rewrite Rules, Rewrite Rules ++@subsection Composing Patterns in Rewrite Rules ++ ++@noindent ++There are three operators, @samp{&&&}, @samp{|||}, and @samp{!!!}, ++that combine rewrite patterns to make larger patterns. The ++combinations are ``and,'' ``or,'' and ``not,'' respectively, and ++these operators are the pattern equivalents of @samp{&&}, @samp{||} ++and @samp{!} (which operate on zero-or-nonzero logical values). ++ ++Note that @samp{&&&}, @samp{|||}, and @samp{!!!} are left in symbolic ++form by all regular Calc features; they have special meaning only in ++the context of rewrite rule patterns. ++ ++The pattern @samp{@var{p1} &&& @var{p2}} matches anything that ++matches both @var{p1} and @var{p2}. One especially useful case is ++when one of @var{p1} or @var{p2} is a meta-variable. For example, ++here is a rule that operates on error forms: ++ ++@example ++f(x &&& a +/- b, x) := g(x) ++@end example ++ ++This does the same thing, but is arguably simpler than, the rule ++ ++@example ++f(a +/- b, a +/- b) := g(a +/- b) ++@end example ++ ++@ignore ++@starindex ++@end ignore ++@tindex ends ++Here's another interesting example: ++ ++@example ++ends(cons(a, x) &&& rcons(y, b)) := [a, b] ++@end example ++ ++@noindent ++which effectively clips out the middle of a vector leaving just ++the first and last elements. This rule will change a one-element ++vector @samp{[a]} to @samp{[a, a]}. The similar rule ++ ++@example ++ends(cons(a, rcons(y, b))) := [a, b] ++@end example ++ ++@noindent ++would do the same thing except that it would fail to match a ++one-element vector. ++ ++@tex ++\bigskip ++@end tex ++ ++The pattern @samp{@var{p1} ||| @var{p2}} matches anything that ++matches either @var{p1} or @var{p2}. Calc first tries matching ++against @var{p1}; if that fails, it goes on to try @var{p2}. ++ ++@ignore ++@starindex ++@end ignore ++@tindex curve ++A simple example of @samp{|||} is ++ ++@example ++curve(inf ||| -inf) := 0 ++@end example ++ ++@noindent ++which converts both @samp{curve(inf)} and @samp{curve(-inf)} to zero. ++ ++Here is a larger example: ++ ++@example ++log(a, b) ||| (ln(a) :: let(b := e)) := mylog(a, b) ++@end example ++ ++This matches both generalized and natural logarithms in a single rule. ++Note that the @samp{::} term must be enclosed in parentheses because ++that operator has lower precedence than @samp{|||} or @samp{:=}. ++ ++(In practice this rule would probably include a third alternative, ++omitted here for brevity, to take care of @code{log10}.) ++ ++While Calc generally treats interior conditions exactly the same as ++conditions on the outside of a rule, it does guarantee that if all the ++variables in the condition are special names like @code{e}, or already ++bound in the pattern to which the condition is attached (say, if ++@samp{a} had appeared in this condition), then Calc will process this ++condition right after matching the pattern to the left of the @samp{::}. ++Thus, we know that @samp{b} will be bound to @samp{e} only if the ++@code{ln} branch of the @samp{|||} was taken. ++ ++Note that this rule was careful to bind the same set of meta-variables ++on both sides of the @samp{|||}. Calc does not check this, but if ++you bind a certain meta-variable only in one branch and then use that ++meta-variable elsewhere in the rule, results are unpredictable: ++ ++@example ++f(a,b) ||| g(b) := h(a,b) ++@end example ++ ++Here if the pattern matches @samp{g(17)}, Calc makes no promises about ++the value that will be substituted for @samp{a} on the righthand side. ++ ++@tex ++\bigskip ++@end tex ++ ++The pattern @samp{!!! @var{pat}} matches anything that does not ++match @var{pat}. Any meta-variables that are bound while matching ++@var{pat} remain unbound outside of @var{pat}. ++ ++For example, ++ ++@example ++f(x &&& !!! a +/- b, !!![]) := g(x) ++@end example ++ ++@noindent ++converts @code{f} whose first argument is anything @emph{except} an ++error form, and whose second argument is not the empty vector, into ++a similar call to @code{g} (but without the second argument). ++ ++If we know that the second argument will be a vector (empty or not), ++then an equivalent rule would be: ++ ++@example ++f(x, y) := g(x) :: typeof(x) != 7 :: vlen(y) > 0 ++@end example ++ ++@noindent ++where of course 7 is the @code{typeof} code for error forms. ++Another final condition, that works for any kind of @samp{y}, ++would be @samp{!istrue(y == [])}. (The @code{istrue} function ++returns an explicit 0 if its argument was left in symbolic form; ++plain @samp{!(y == [])} or @samp{y != []} would not work to replace ++@samp{!!![]} since these would be left unsimplified, and thus cause ++the rule to fail, if @samp{y} was something like a variable name.) ++ ++It is possible for a @samp{!!!} to refer to meta-variables bound ++elsewhere in the pattern. For example, ++ ++@example ++f(a, !!!a) := g(a) ++@end example ++ ++@noindent ++matches any call to @code{f} with different arguments, changing ++this to @code{g} with only the first argument. ++ ++If a function call is to be matched and one of the argument patterns ++contains a @samp{!!!} somewhere inside it, that argument will be ++matched last. Thus ++ ++@example ++f(!!!a, a) := g(a) ++@end example ++ ++@noindent ++will be careful to bind @samp{a} to the second argument of @code{f} ++before testing the first argument. If Calc had tried to match the ++first argument of @code{f} first, the results would have been ++disastrous: since @code{a} was unbound so far, the pattern @samp{a} ++would have matched anything at all, and the pattern @samp{!!!a} ++therefore would @emph{not} have matched anything at all! ++ ++@node Nested Formulas with Rewrite Rules, Multi-Phase Rewrite Rules, Composing Patterns in Rewrite Rules, Rewrite Rules ++@subsection Nested Formulas with Rewrite Rules ++ ++@noindent ++When @kbd{a r} (@code{calc-rewrite}) is used, it takes an expression from ++the top of the stack and attempts to match any of the specified rules ++to any part of the expression, starting with the whole expression ++and then, if that fails, trying deeper and deeper sub-expressions. ++For each part of the expression, the rules are tried in the order ++they appear in the rules vector. The first rule to match the first ++sub-expression wins; it replaces the matched sub-expression according ++to the @var{new} part of the rule. ++ ++Often, the rule set will match and change the formula several times. ++The top-level formula is first matched and substituted repeatedly until ++it no longer matches the pattern; then, sub-formulas are tried, and ++so on. Once every part of the formula has gotten its chance, the ++rewrite mechanism starts over again with the top-level formula ++(in case a substitution of one of its arguments has caused it again ++to match). This continues until no further matches can be made ++anywhere in the formula. ++ ++It is possible for a rule set to get into an infinite loop. The ++most obvious case, replacing a formula with itself, is not a problem ++because a rule is not considered to ``succeed'' unless the righthand ++side actually comes out to something different than the original ++formula or sub-formula that was matched. But if you accidentally ++had both @samp{ln(a b) := ln(a) + ln(b)} and the reverse ++@samp{ln(a) + ln(b) := ln(a b)} in your rule set, Calc would ++run forever switching a formula back and forth between the two ++forms. ++ ++To avoid disaster, Calc normally stops after 100 changes have been ++made to the formula. This will be enough for most multiple rewrites, ++but it will keep an endless loop of rewrites from locking up the ++computer forever. (On most systems, you can also type @kbd{C-g} to ++halt any Emacs command prematurely.) ++ ++To change this limit, give a positive numeric prefix argument. ++In particular, @kbd{M-1 a r} applies only one rewrite at a time, ++useful when you are first testing your rule (or just if repeated ++rewriting is not what is called for by your application). ++ ++@ignore ++@starindex ++@end ignore ++@ignore ++@mindex iter@idots ++@end ignore ++@tindex iterations ++You can also put a ``function call'' @samp{iterations(@var{n})} ++in place of a rule anywhere in your rules vector (but usually at ++the top). Then, @var{n} will be used instead of 100 as the default ++number of iterations for this rule set. You can use ++@samp{iterations(inf)} if you want no iteration limit by default. ++A prefix argument will override the @code{iterations} limit in the ++rule set. ++ ++@example ++[ iterations(1), ++ f(x) := f(x+1) ] ++@end example ++ ++More precisely, the limit controls the number of ``iterations,'' ++where each iteration is a successful matching of a rule pattern whose ++righthand side, after substituting meta-variables and applying the ++default simplifications, is different from the original sub-formula ++that was matched. ++ ++A prefix argument of zero sets the limit to infinity. Use with caution! ++ ++Given a negative numeric prefix argument, @kbd{a r} will match and ++substitute the top-level expression up to that many times, but ++will not attempt to match the rules to any sub-expressions. ++ ++In a formula, @code{rewrite(@var{expr}, @var{rules}, @var{n})} ++does a rewriting operation. Here @var{expr} is the expression ++being rewritten, @var{rules} is the rule, vector of rules, or ++variable containing the rules, and @var{n} is the optional ++iteration limit, which may be a positive integer, a negative ++integer, or @samp{inf} or @samp{-inf}. If @var{n} is omitted ++the @code{iterations} value from the rule set is used; if both ++are omitted, 100 is used. ++ ++@node Multi-Phase Rewrite Rules, Selections with Rewrite Rules, Nested Formulas with Rewrite Rules, Rewrite Rules ++@subsection Multi-Phase Rewrite Rules ++ ++@noindent ++It is possible to separate a rewrite rule set into several @dfn{phases}. ++During each phase, certain rules will be enabled while certain others ++will be disabled. A @dfn{phase schedule} controls the order in which ++phases occur during the rewriting process. ++ ++@ignore ++@starindex ++@end ignore ++@tindex phase ++@vindex all ++If a call to the marker function @code{phase} appears in the rules ++vector in place of a rule, all rules following that point will be ++members of the phase(s) identified in the arguments to @code{phase}. ++Phases are given integer numbers. The markers @samp{phase()} and ++@samp{phase(all)} both mean the following rules belong to all phases; ++this is the default at the start of the rule set. ++ ++If you do not explicitly schedule the phases, Calc sorts all phase ++numbers that appear in the rule set and executes the phases in ++ascending order. For example, the rule set ++ ++@example ++@group ++[ f0(x) := g0(x), ++ phase(1), ++ f1(x) := g1(x), ++ phase(2), ++ f2(x) := g2(x), ++ phase(3), ++ f3(x) := g3(x), ++ phase(1,2), ++ f4(x) := g4(x) ] ++@end group ++@end example ++ ++@noindent ++has three phases, 1 through 3. Phase 1 consists of the @code{f0}, ++@code{f1}, and @code{f4} rules (in that order). Phase 2 consists of ++@code{f0}, @code{f2}, and @code{f4}. Phase 3 consists of @code{f0} ++and @code{f3}. ++ ++When Calc rewrites a formula using this rule set, it first rewrites ++the formula using only the phase 1 rules until no further changes are ++possible. Then it switches to the phase 2 rule set and continues ++until no further changes occur, then finally rewrites with phase 3. ++When no more phase 3 rules apply, rewriting finishes. (This is ++assuming @kbd{a r} with a large enough prefix argument to allow the ++rewriting to run to completion; the sequence just described stops ++early if the number of iterations specified in the prefix argument, ++100 by default, is reached.) ++ ++During each phase, Calc descends through the nested levels of the ++formula as described previously. (@xref{Nested Formulas with Rewrite ++Rules}.) Rewriting starts at the top of the formula, then works its ++way down to the parts, then goes back to the top and works down again. ++The phase 2 rules do not begin until no phase 1 rules apply anywhere ++in the formula. ++ ++@ignore ++@starindex ++@end ignore ++@tindex schedule ++A @code{schedule} marker appearing in the rule set (anywhere, but ++conventionally at the top) changes the default schedule of phases. ++In the simplest case, @code{schedule} has a sequence of phase numbers ++for arguments; each phase number is invoked in turn until the ++arguments to @code{schedule} are exhausted. Thus adding ++@samp{schedule(3,2,1)} at the top of the above rule set would ++reverse the order of the phases; @samp{schedule(1,2,3)} would have ++no effect since this is the default schedule; and @samp{schedule(1,2,1,3)} ++would give phase 1 a second chance after phase 2 has completed, before ++moving on to phase 3. ++ ++Any argument to @code{schedule} can instead be a vector of phase ++numbers (or even of sub-vectors). Then the sub-sequence of phases ++described by the vector are tried repeatedly until no change occurs ++in any phase in the sequence. For example, @samp{schedule([1, 2], 3)} ++tries phase 1, then phase 2, then, if either phase made any changes ++to the formula, repeats these two phases until they can make no ++further progress. Finally, it goes on to phase 3 for finishing ++touches. ++ ++Also, items in @code{schedule} can be variable names as well as ++numbers. A variable name is interpreted as the name of a function ++to call on the whole formula. For example, @samp{schedule(1, simplify)} ++says to apply the phase-1 rules (presumably, all of them), then to ++call @code{simplify} which is the function name equivalent of @kbd{a s}. ++Likewise, @samp{schedule([1, simplify])} says to alternate between ++phase 1 and @kbd{a s} until no further changes occur. ++ ++Phases can be used purely to improve efficiency; if it is known that ++a certain group of rules will apply only at the beginning of rewriting, ++and a certain other group will apply only at the end, then rewriting ++will be faster if these groups are identified as separate phases. ++Once the phase 1 rules are done, Calc can put them aside and no longer ++spend any time on them while it works on phase 2. ++ ++There are also some problems that can only be solved with several ++rewrite phases. For a real-world example of a multi-phase rule set, ++examine the set @code{FitRules}, which is used by the curve-fitting ++command to convert a model expression to linear form. ++@xref{Curve Fitting Details}. This set is divided into four phases. ++The first phase rewrites certain kinds of expressions to be more ++easily linearizable, but less computationally efficient. After the ++linear components have been picked out, the final phase includes the ++opposite rewrites to put each component back into an efficient form. ++If both sets of rules were included in one big phase, Calc could get ++into an infinite loop going back and forth between the two forms. ++ ++Elsewhere in @code{FitRules}, the components are first isolated, ++then recombined where possible to reduce the complexity of the linear ++fit, then finally packaged one component at a time into vectors. ++If the packaging rules were allowed to begin before the recombining ++rules were finished, some components might be put away into vectors ++before they had a chance to recombine. By putting these rules in ++two separate phases, this problem is neatly avoided. ++ ++@node Selections with Rewrite Rules, Matching Commands, Multi-Phase Rewrite Rules, Rewrite Rules ++@subsection Selections with Rewrite Rules ++ ++@noindent ++If a sub-formula of the current formula is selected (as by @kbd{j s}; ++@pxref{Selecting Subformulas}), the @kbd{a r} (@code{calc-rewrite}) ++command applies only to that sub-formula. Together with a negative ++prefix argument, you can use this fact to apply a rewrite to one ++specific part of a formula without affecting any other parts. ++ ++@kindex j r ++@pindex calc-rewrite-selection ++The @kbd{j r} (@code{calc-rewrite-selection}) command allows more ++sophisticated operations on selections. This command prompts for ++the rules in the same way as @kbd{a r}, but it then applies those ++rules to the whole formula in question even though a sub-formula ++of it has been selected. However, the selected sub-formula will ++first have been surrounded by a @samp{select( )} function call. ++(Calc's evaluator does not understand the function name @code{select}; ++this is only a tag used by the @kbd{j r} command.) ++ ++For example, suppose the formula on the stack is @samp{2 (a + b)^2} ++and the sub-formula @samp{a + b} is selected. This formula will ++be rewritten to @samp{2 select(a + b)^2} and then the rewrite ++rules will be applied in the usual way. The rewrite rules can ++include references to @code{select} to tell where in the pattern ++the selected sub-formula should appear. ++ ++If there is still exactly one @samp{select( )} function call in ++the formula after rewriting is done, it indicates which part of ++the formula should be selected afterwards. Otherwise, the ++formula will be unselected. ++ ++You can make @kbd{j r} act much like @kbd{a r} by enclosing both parts ++of the rewrite rule with @samp{select()}. However, @kbd{j r} ++allows you to use the current selection in more flexible ways. ++Suppose you wished to make a rule which removed the exponent from ++the selected term; the rule @samp{select(a)^x := select(a)} would ++work. In the above example, it would rewrite @samp{2 select(a + b)^2} ++to @samp{2 select(a + b)}. This would then be returned to the ++stack as @samp{2 (a + b)} with the @samp{a + b} selected. ++ ++The @kbd{j r} command uses one iteration by default, unlike ++@kbd{a r} which defaults to 100 iterations. A numeric prefix ++argument affects @kbd{j r} in the same way as @kbd{a r}. ++@xref{Nested Formulas with Rewrite Rules}. ++ ++As with other selection commands, @kbd{j r} operates on the stack ++entry that contains the cursor. (If the cursor is on the top-of-stack ++@samp{.} marker, it works as if the cursor were on the formula ++at stack level 1.) ++ ++If you don't specify a set of rules, the rules are taken from the ++top of the stack, just as with @kbd{a r}. In this case, the ++cursor must indicate stack entry 2 or above as the formula to be ++rewritten (otherwise the same formula would be used as both the ++target and the rewrite rules). ++ ++If the indicated formula has no selection, the cursor position within ++the formula temporarily selects a sub-formula for the purposes of this ++command. If the cursor is not on any sub-formula (e.g., it is in ++the line-number area to the left of the formula), the @samp{select( )} ++markers are ignored by the rewrite mechanism and the rules are allowed ++to apply anywhere in the formula. ++ ++As a special feature, the normal @kbd{a r} command also ignores ++@samp{select( )} calls in rewrite rules. For example, if you used the ++above rule @samp{select(a)^x := select(a)} with @kbd{a r}, it would apply ++the rule as if it were @samp{a^x := a}. Thus, you can write general ++purpose rules with @samp{select( )} hints inside them so that they ++will ``do the right thing'' in both @kbd{a r} and @kbd{j r}, ++both with and without selections. ++ ++@node Matching Commands, Automatic Rewrites, Selections with Rewrite Rules, Rewrite Rules ++@subsection Matching Commands ++ ++@noindent ++@kindex a m ++@pindex calc-match ++@tindex match ++The @kbd{a m} (@code{calc-match}) [@code{match}] function takes a ++vector of formulas and a rewrite-rule-style pattern, and produces ++a vector of all formulas which match the pattern. The command ++prompts you to enter the pattern; as for @kbd{a r}, you can enter ++a single pattern (i.e., a formula with meta-variables), or a ++vector of patterns, or a variable which contains patterns, or ++you can give a blank response in which case the patterns are taken ++from the top of the stack. The pattern set will be compiled once ++and saved if it is stored in a variable. If there are several ++patterns in the set, vector elements are kept if they match any ++of the patterns. ++ ++For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])} ++will return @samp{[x+y, x-y, x+y+z]}. ++ ++The @code{import} mechanism is not available for pattern sets. ++ ++The @kbd{a m} command can also be used to extract all vector elements ++which satisfy any condition: The pattern @samp{x :: x>0} will select ++all the positive vector elements. ++ ++@kindex I a m ++@tindex matchnot ++With the Inverse flag [@code{matchnot}], this command extracts all ++vector elements which do @emph{not} match the given pattern. ++ ++@ignore ++@starindex ++@end ignore ++@tindex matches ++There is also a function @samp{matches(@var{x}, @var{p})} which ++evaluates to 1 if expression @var{x} matches pattern @var{p}, or ++to 0 otherwise. This is sometimes useful for including into the ++conditional clauses of other rewrite rules. ++ ++@ignore ++@starindex ++@end ignore ++@tindex vmatches ++The function @code{vmatches} is just like @code{matches}, except ++that if the match succeeds it returns a vector of assignments to ++the meta-variables instead of the number 1. For example, ++@samp{vmatches(f(1,2), f(a,b))} returns @samp{[a := 1, b := 2]}. ++If the match fails, the function returns the number 0. ++ ++@node Automatic Rewrites, Debugging Rewrites, Matching Commands, Rewrite Rules ++@subsection Automatic Rewrites ++ ++@noindent ++@cindex @code{EvalRules} variable ++@vindex EvalRules ++It is possible to get Calc to apply a set of rewrite rules on all ++results, effectively adding to the built-in set of default ++simplifications. To do this, simply store your rule set in the ++variable @code{EvalRules}. There is a convenient @kbd{s E} command ++for editing @code{EvalRules}; @pxref{Operations on Variables}. ++ ++For example, suppose you want @samp{sin(a + b)} to be expanded out ++to @samp{sin(b) cos(a) + cos(b) sin(a)} wherever it appears, and ++similarly for @samp{cos(a + b)}. The corresponding rewrite rule ++set would be, ++ ++@smallexample ++@group ++[ sin(a + b) := cos(a) sin(b) + sin(a) cos(b), ++ cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ] ++@end group ++@end smallexample ++ ++To apply these manually, you could put them in a variable called ++@code{trigexp} and then use @kbd{a r trigexp} every time you wanted ++to expand trig functions. But if instead you store them in the ++variable @code{EvalRules}, they will automatically be applied to all ++sines and cosines of sums. Then, with @samp{2 x} and @samp{45} on ++the stack, typing @kbd{+ S} will (assuming Degrees mode) result in ++@samp{0.7071 sin(2 x) + 0.7071 cos(2 x)} automatically. ++ ++As each level of a formula is evaluated, the rules from ++@code{EvalRules} are applied before the default simplifications. ++Rewriting continues until no further @code{EvalRules} apply. ++Note that this is different from the usual order of application of ++rewrite rules: @code{EvalRules} works from the bottom up, simplifying ++the arguments to a function before the function itself, while @kbd{a r} ++applies rules from the top down. ++ ++Because the @code{EvalRules} are tried first, you can use them to ++override the normal behavior of any built-in Calc function. ++ ++It is important not to write a rule that will get into an infinite ++loop. For example, the rule set @samp{[f(0) := 1, f(n) := n f(n-1)]} ++appears to be a good definition of a factorial function, but it is ++unsafe. Imagine what happens if @samp{f(2.5)} is simplified. Calc ++will continue to subtract 1 from this argument forever without reaching ++zero. A safer second rule would be @samp{f(n) := n f(n-1) :: n>0}. ++Another dangerous rule is @samp{g(x, y) := g(y, x)}. Rewriting ++@samp{g(2, 4)}, this would bounce back and forth between that and ++@samp{g(4, 2)} forever. If an infinite loop in @code{EvalRules} ++occurs, Emacs will eventually stop with a ``Computation got stuck ++or ran too long'' message. ++ ++Another subtle difference between @code{EvalRules} and regular rewrites ++concerns rules that rewrite a formula into an identical formula. For ++example, @samp{f(n) := f(floor(n))} ``fails to match'' when @expr{n} is ++already an integer. But in @code{EvalRules} this case is detected only ++if the righthand side literally becomes the original formula before any ++further simplification. This means that @samp{f(n) := f(floor(n))} will ++get into an infinite loop if it occurs in @code{EvalRules}. Calc will ++replace @samp{f(6)} with @samp{f(floor(6))}, which is different from ++@samp{f(6)}, so it will consider the rule to have matched and will ++continue simplifying that formula; first the argument is simplified ++to get @samp{f(6)}, then the rule matches again to get @samp{f(floor(6))} ++again, ad infinitum. A much safer rule would check its argument first, ++say, with @samp{f(n) := f(floor(n)) :: !dint(n)}. ++ ++(What really happens is that the rewrite mechanism substitutes the ++meta-variables in the righthand side of a rule, compares to see if the ++result is the same as the original formula and fails if so, then uses ++the default simplifications to simplify the result and compares again ++(and again fails if the formula has simplified back to its original ++form). The only special wrinkle for the @code{EvalRules} is that the ++same rules will come back into play when the default simplifications ++are used. What Calc wants to do is build @samp{f(floor(6))}, see that ++this is different from the original formula, simplify to @samp{f(6)}, ++see that this is the same as the original formula, and thus halt the ++rewriting. But while simplifying, @samp{f(6)} will again trigger ++the same @code{EvalRules} rule and Calc will get into a loop inside ++the rewrite mechanism itself.) ++ ++The @code{phase}, @code{schedule}, and @code{iterations} markers do ++not work in @code{EvalRules}. If the rule set is divided into phases, ++only the phase 1 rules are applied, and the schedule is ignored. ++The rules are always repeated as many times as possible. ++ ++The @code{EvalRules} are applied to all function calls in a formula, ++but not to numbers (and other number-like objects like error forms), ++nor to vectors or individual variable names. (Though they will apply ++to @emph{components} of vectors and error forms when appropriate.) You ++might try to make a variable @code{phihat} which automatically expands ++to its definition without the need to press @kbd{=} by writing the ++rule @samp{quote(phihat) := (1-sqrt(5))/2}, but unfortunately this rule ++will not work as part of @code{EvalRules}. ++ ++Finally, another limitation is that Calc sometimes calls its built-in ++functions directly rather than going through the default simplifications. ++When it does this, @code{EvalRules} will not be able to override those ++functions. For example, when you take the absolute value of the complex ++number @expr{(2, 3)}, Calc computes @samp{sqrt(2*2 + 3*3)} by calling ++the multiplication, addition, and square root functions directly rather ++than applying the default simplifications to this formula. So an ++@code{EvalRules} rule that (perversely) rewrites @samp{sqrt(13) := 6} ++would not apply. (However, if you put Calc into Symbolic mode so that ++@samp{sqrt(13)} will be left in symbolic form by the built-in square ++root function, your rule will be able to apply. But if the complex ++number were @expr{(3,4)}, so that @samp{sqrt(25)} must be calculated, ++then Symbolic mode will not help because @samp{sqrt(25)} can be ++evaluated exactly to 5.) ++ ++One subtle restriction that normally only manifests itself with ++@code{EvalRules} is that while a given rewrite rule is in the process ++of being checked, that same rule cannot be recursively applied. Calc ++effectively removes the rule from its rule set while checking the rule, ++then puts it back once the match succeeds or fails. (The technical ++reason for this is that compiled pattern programs are not reentrant.) ++For example, consider the rule @samp{foo(x) := x :: foo(x/2) > 0} ++attempting to match @samp{foo(8)}. This rule will be inactive while ++the condition @samp{foo(4) > 0} is checked, even though it might be ++an integral part of evaluating that condition. Note that this is not ++a problem for the more usual recursive type of rule, such as ++@samp{foo(x) := foo(x/2)}, because there the rule has succeeded and ++been reactivated by the time the righthand side is evaluated. ++ ++If @code{EvalRules} has no stored value (its default state), or if ++anything but a vector is stored in it, then it is ignored. ++ ++Even though Calc's rewrite mechanism is designed to compare rewrite ++rules to formulas as quickly as possible, storing rules in ++@code{EvalRules} may make Calc run substantially slower. This is ++particularly true of rules where the top-level call is a commonly used ++function, or is not fixed. The rule @samp{f(n) := n f(n-1) :: n>0} will ++only activate the rewrite mechanism for calls to the function @code{f}, ++but @samp{lg(n) + lg(m) := lg(n m)} will check every @samp{+} operator. ++ ++@smallexample ++apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: in(f, [ln, log10]) ++@end smallexample ++ ++@noindent ++may seem more ``efficient'' than two separate rules for @code{ln} and ++@code{log10}, but actually it is vastly less efficient because rules ++with @code{apply} as the top-level pattern must be tested against ++@emph{every} function call that is simplified. ++ ++@cindex @code{AlgSimpRules} variable ++@vindex AlgSimpRules ++Suppose you want @samp{sin(a + b)} to be expanded out not all the time, ++but only when @kbd{a s} is used to simplify the formula. The variable ++@code{AlgSimpRules} holds rules for this purpose. The @kbd{a s} command ++will apply @code{EvalRules} and @code{AlgSimpRules} to the formula, as ++well as all of its built-in simplifications. ++ ++Most of the special limitations for @code{EvalRules} don't apply to ++@code{AlgSimpRules}. Calc simply does an @kbd{a r AlgSimpRules} ++command with an infinite repeat count as the first step of @kbd{a s}. ++It then applies its own built-in simplifications throughout the ++formula, and then repeats these two steps (along with applying the ++default simplifications) until no further changes are possible. ++ ++@cindex @code{ExtSimpRules} variable ++@cindex @code{UnitSimpRules} variable ++@vindex ExtSimpRules ++@vindex UnitSimpRules ++There are also @code{ExtSimpRules} and @code{UnitSimpRules} variables ++that are used by @kbd{a e} and @kbd{u s}, respectively; these commands ++also apply @code{EvalRules} and @code{AlgSimpRules}. The variable ++@code{IntegSimpRules} contains simplification rules that are used ++only during integration by @kbd{a i}. ++ ++@node Debugging Rewrites, Examples of Rewrite Rules, Automatic Rewrites, Rewrite Rules ++@subsection Debugging Rewrites ++ ++@noindent ++If a buffer named @samp{*Trace*} exists, the rewrite mechanism will ++record some useful information there as it operates. The original ++formula is written there, as is the result of each successful rewrite, ++and the final result of the rewriting. All phase changes are also ++noted. ++ ++Calc always appends to @samp{*Trace*}. You must empty this buffer ++yourself periodically if it is in danger of growing unwieldy. ++ ++Note that the rewriting mechanism is substantially slower when the ++@samp{*Trace*} buffer exists, even if the buffer is not visible on ++the screen. Once you are done, you will probably want to kill this ++buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in ++existence and forget about it, all your future rewrite commands will ++be needlessly slow. ++ ++@node Examples of Rewrite Rules, , Debugging Rewrites, Rewrite Rules ++@subsection Examples of Rewrite Rules ++ ++@noindent ++Returning to the example of substituting the pattern ++@samp{sin(x)^2 + cos(x)^2} with 1, we saw that the rule ++@samp{opt(a) sin(x)^2 + opt(a) cos(x)^2 := a} does a good job of ++finding suitable cases. Another solution would be to use the rule ++@samp{cos(x)^2 := 1 - sin(x)^2}, followed by algebraic simplification ++if necessary. This rule will be the most effective way to do the job, ++but at the expense of making some changes that you might not desire. ++ ++Another algebraic rewrite rule is @samp{exp(x+y) := exp(x) exp(y)}. ++To make this work with the @w{@kbd{j r}} command so that it can be ++easily targeted to a particular exponential in a large formula, ++you might wish to write the rule as @samp{select(exp(x+y)) := ++select(exp(x) exp(y))}. The @samp{select} markers will be ++ignored by the regular @kbd{a r} command ++(@pxref{Selections with Rewrite Rules}). ++ ++A surprisingly useful rewrite rule is @samp{a/(b-c) := a*(b+c)/(b^2-c^2)}. ++This will simplify the formula whenever @expr{b} and/or @expr{c} can ++be made simpler by squaring. For example, applying this rule to ++@samp{2 / (sqrt(2) + 3)} yields @samp{6:7 - 2:7 sqrt(2)} (assuming ++Symbolic mode has been enabled to keep the square root from being ++evaluated to a floating-point approximation). This rule is also ++useful when working with symbolic complex numbers, e.g., ++@samp{(a + b i) / (c + d i)}. ++ ++As another example, we could define our own ``triangular numbers'' function ++with the rules @samp{[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]}. Enter ++this vector and store it in a variable: @kbd{@w{s t} trirules}. Now, given ++a suitable formula like @samp{tri(5)} on the stack, type @samp{a r trirules} ++to apply these rules repeatedly. After six applications, @kbd{a r} will ++stop with 15 on the stack. Once these rules are debugged, it would probably ++be most useful to add them to @code{EvalRules} so that Calc will evaluate ++the new @code{tri} function automatically. We could then use @kbd{Z K} on ++the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies ++@code{tri} to the value on the top of the stack. @xref{Programming}. ++ ++@cindex Quaternions ++The following rule set, contributed by ++@texline Fran\c cois ++@infoline Francois ++Pinard, implements @dfn{quaternions}, a generalization of the concept of ++complex numbers. Quaternions have four components, and are here ++represented by function calls @samp{quat(@var{w}, [@var{x}, @var{y}, ++@var{z}])} with ``real part'' @var{w} and the three ``imaginary'' parts ++collected into a vector. Various arithmetical operations on quaternions ++are supported. To use these rules, either add them to @code{EvalRules}, ++or create a command based on @kbd{a r} for simplifying quaternion ++formulas. A convenient way to enter quaternions would be a command ++defined by a keyboard macro containing: @kbd{' quat($$$$, [$$$, $$, $]) ++@key{RET}}. ++ ++@smallexample ++[ quat(w, x, y, z) := quat(w, [x, y, z]), ++ quat(w, [0, 0, 0]) := w, ++ abs(quat(w, v)) := hypot(w, v), ++ -quat(w, v) := quat(-w, -v), ++ r + quat(w, v) := quat(r + w, v) :: real(r), ++ r - quat(w, v) := quat(r - w, -v) :: real(r), ++ quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2), ++ r * quat(w, v) := quat(r * w, r * v) :: real(r), ++ plain(quat(w1, v1) * quat(w2, v2)) ++ := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)), ++ quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r), ++ z / quat(w, v) := z * quatinv(quat(w, v)), ++ quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2), ++ quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v), ++ quat(w, v)^k := quatsqr(quat(w, v)^(k / 2)) ++ :: integer(k) :: k > 0 :: k % 2 = 0, ++ quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v) ++ :: integer(k) :: k > 2, ++ quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ] ++@end smallexample ++ ++Quaternions, like matrices, have non-commutative multiplication. ++In other words, @expr{q1 * q2 = q2 * q1} is not necessarily true if ++@expr{q1} and @expr{q2} are @code{quat} forms. The @samp{quat*quat} ++rule above uses @code{plain} to prevent Calc from rearranging the ++product. It may also be wise to add the line @samp{[quat(), matrix]} ++to the @code{Decls} matrix, to ensure that Calc's other algebraic ++operations will not rearrange a quaternion product. @xref{Declarations}. ++ ++These rules also accept a four-argument @code{quat} form, converting ++it to the preferred form in the first rule. If you would rather see ++results in the four-argument form, just append the two items ++@samp{phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)} to the end ++of the rule set. (But remember that multi-phase rule sets don't work ++in @code{EvalRules}.) ++ ++@node Units, Store and Recall, Algebra, Top ++@chapter Operating on Units ++ ++@noindent ++One special interpretation of algebraic formulas is as numbers with units. ++For example, the formula @samp{5 m / s^2} can be read ``five meters ++per second squared.'' The commands in this chapter help you ++manipulate units expressions in this form. Units-related commands ++begin with the @kbd{u} prefix key. ++ ++@menu ++* Basic Operations on Units:: ++* The Units Table:: ++* Predefined Units:: ++* User-Defined Units:: ++@end menu ++ ++@node Basic Operations on Units, The Units Table, Units, Units ++@section Basic Operations on Units ++ ++@noindent ++A @dfn{units expression} is a formula which is basically a number ++multiplied and/or divided by one or more @dfn{unit names}, which may ++optionally be raised to integer powers. Actually, the value part need not ++be a number; any product or quotient involving unit names is a units ++expression. Many of the units commands will also accept any formula, ++where the command applies to all units expressions which appear in the ++formula. ++ ++A unit name is a variable whose name appears in the @dfn{unit table}, ++or a variable whose name is a prefix character like @samp{k} (for ``kilo'') ++or @samp{u} (for ``micro'') followed by a name in the unit table. ++A substantial table of built-in units is provided with Calc; ++@pxref{Predefined Units}. You can also define your own unit names; ++@pxref{User-Defined Units}. ++ ++Note that if the value part of a units expression is exactly @samp{1}, ++it will be removed by the Calculator's automatic algebra routines: The ++formula @samp{1 mm} is ``simplified'' to @samp{mm}. This is only a ++display anomaly, however; @samp{mm} will work just fine as a ++representation of one millimeter. ++ ++You may find that Algebraic mode (@pxref{Algebraic Entry}) makes working ++with units expressions easier. Otherwise, you will have to remember ++to hit the apostrophe key every time you wish to enter units. ++ ++@kindex u s ++@pindex calc-simplify-units ++@ignore ++@mindex usimpl@idots ++@end ignore ++@tindex usimplify ++The @kbd{u s} (@code{calc-simplify-units}) [@code{usimplify}] command ++simplifies a units ++expression. It uses @kbd{a s} (@code{calc-simplify}) to simplify the ++expression first as a regular algebraic formula; it then looks for ++features that can be further simplified by converting one object's units ++to be compatible with another's. For example, @samp{5 m + 23 mm} will ++simplify to @samp{5.023 m}. When different but compatible units are ++added, the righthand term's units are converted to match those of the ++lefthand term. @xref{Simplification Modes}, for a way to have this done ++automatically at all times. ++ ++Units simplification also handles quotients of two units with the same ++dimensionality, as in @w{@samp{2 in s/L cm}} to @samp{5.08 s/L}; fractional ++powers of unit expressions, as in @samp{sqrt(9 mm^2)} to @samp{3 mm} and ++@samp{sqrt(9 acre)} to a quantity in meters; and @code{floor}, ++@code{ceil}, @code{round}, @code{rounde}, @code{roundu}, @code{trunc}, ++@code{float}, @code{frac}, @code{abs}, and @code{clean} ++applied to units expressions, in which case ++the operation in question is applied only to the numeric part of the ++expression. Finally, trigonometric functions of quantities with units ++of angle are evaluated, regardless of the current angular mode. ++ ++@kindex u c ++@pindex calc-convert-units ++The @kbd{u c} (@code{calc-convert-units}) command converts a units ++expression to new, compatible units. For example, given the units ++expression @samp{55 mph}, typing @kbd{u c m/s @key{RET}} produces ++@samp{24.5872 m/s}. If you have previously converted a units expression ++with the same type of units (in this case, distance over time), you will ++be offered the previous choice of new units as a default. Continuing ++the above example, entering the units expression @samp{100 km/hr} and ++typing @kbd{u c @key{RET}} (without specifying new units) produces ++@samp{27.7777777778 m/s}. ++ ++While many of Calc's conversion factors are exact, some are necessarily ++approximate. If Calc is in fraction mode (@pxref{Fraction Mode}), then ++unit conversions will try to give exact, rational conversions, but it ++isn't always possible. Given @samp{55 mph} in fraction mode, typing ++@kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example, ++while typing @kbd{u c au/yr @key{RET}} produces ++@samp{5.18665819999e-3 au/yr}. ++ ++If the units you request are inconsistent with the original units, the ++number will be converted into your units times whatever ``remainder'' ++units are left over. For example, converting @samp{55 mph} into acres ++produces @samp{6.08e-3 acre / m s}. (Recall that multiplication binds ++more strongly than division in Calc formulas, so the units here are ++acres per meter-second.) Remainder units are expressed in terms of ++``fundamental'' units like @samp{m} and @samp{s}, regardless of the ++input units. ++ ++One special exception is that if you specify a single unit name, and ++a compatible unit appears somewhere in the units expression, then ++that compatible unit will be converted to the new unit and the ++remaining units in the expression will be left alone. For example, ++given the input @samp{980 cm/s^2}, the command @kbd{u c ms} will ++change the @samp{s} to @samp{ms} to get @samp{9.8e-4 cm/ms^2}. ++The ``remainder unit'' @samp{cm} is left alone rather than being ++changed to the base unit @samp{m}. ++ ++You can use explicit unit conversion instead of the @kbd{u s} command ++to gain more control over the units of the result of an expression. ++For example, given @samp{5 m + 23 mm}, you can type @kbd{u c m} or ++@kbd{u c mm} to express the result in either meters or millimeters. ++(For that matter, you could type @kbd{u c fath} to express the result ++in fathoms, if you preferred!) ++ ++In place of a specific set of units, you can also enter one of the ++units system names @code{si}, @code{mks} (equivalent), or @code{cgs}. ++For example, @kbd{u c si @key{RET}} converts the expression into ++International System of Units (SI) base units. Also, @kbd{u c base} ++converts to Calc's base units, which are the same as @code{si} units ++except that @code{base} uses @samp{g} as the fundamental unit of mass ++whereas @code{si} uses @samp{kg}. ++ ++@cindex Composite units ++The @kbd{u c} command also accepts @dfn{composite units}, which ++are expressed as the sum of several compatible unit names. For ++example, converting @samp{30.5 in} to units @samp{mi+ft+in} (miles, ++feet, and inches) produces @samp{2 ft + 6.5 in}. Calc first ++sorts the unit names into order of decreasing relative size. ++It then accounts for as much of the input quantity as it can ++using an integer number times the largest unit, then moves on ++to the next smaller unit, and so on. Only the smallest unit ++may have a non-integer amount attached in the result. A few ++standard unit names exist for common combinations, such as ++@code{mfi} for @samp{mi+ft+in}, and @code{tpo} for @samp{ton+lb+oz}. ++Composite units are expanded as if by @kbd{a x}, so that ++@samp{(ft+in)/hr} is first converted to @samp{ft/hr+in/hr}. ++ ++If the value on the stack does not contain any units, @kbd{u c} will ++prompt first for the old units which this value should be considered ++to have, then for the new units. Assuming the old and new units you ++give are consistent with each other, the result also will not contain ++any units. For example, @kbd{@w{u c} cm @key{RET} in @key{RET}} ++converts the number 2 on the stack to 5.08. ++ ++@kindex u b ++@pindex calc-base-units ++The @kbd{u b} (@code{calc-base-units}) command is shorthand for ++@kbd{u c base}; it converts the units expression on the top of the ++stack into @code{base} units. If @kbd{u s} does not simplify a ++units expression as far as you would like, try @kbd{u b}. ++ ++The @kbd{u c} and @kbd{u b} commands treat temperature units (like ++@samp{degC} and @samp{K}) as relative temperatures. For example, ++@kbd{u c} converts @samp{10 degC} to @samp{18 degF}: A change of 10 ++degrees Celsius corresponds to a change of 18 degrees Fahrenheit. ++ ++@kindex u t ++@pindex calc-convert-temperature ++@cindex Temperature conversion ++The @kbd{u t} (@code{calc-convert-temperature}) command converts ++absolute temperatures. The value on the stack must be a simple units ++expression with units of temperature only. This command would convert ++@samp{10 degC} to @samp{50 degF}, the equivalent temperature on the ++Fahrenheit scale. ++ ++@kindex u r ++@pindex calc-remove-units ++@kindex u x ++@pindex calc-extract-units ++The @kbd{u r} (@code{calc-remove-units}) command removes units from the ++formula at the top of the stack. The @kbd{u x} ++(@code{calc-extract-units}) command extracts only the units portion of a ++formula. These commands essentially replace every term of the formula ++that does or doesn't (respectively) look like a unit name by the ++constant 1, then resimplify the formula. ++ ++@kindex u a ++@pindex calc-autorange-units ++The @kbd{u a} (@code{calc-autorange-units}) command turns on and off a ++mode in which unit prefixes like @code{k} (``kilo'') are automatically ++applied to keep the numeric part of a units expression in a reasonable ++range. This mode affects @kbd{u s} and all units conversion commands ++except @kbd{u b}. For example, with autoranging on, @samp{12345 Hz} ++will be simplified to @samp{12.345 kHz}. Autoranging is useful for ++some kinds of units (like @code{Hz} and @code{m}), but is probably ++undesirable for non-metric units like @code{ft} and @code{tbsp}. ++(Composite units are more appropriate for those; see above.) ++ ++Autoranging always applies the prefix to the leftmost unit name. ++Calc chooses the largest prefix that causes the number to be greater ++than or equal to 1.0. Thus an increasing sequence of adjusted times ++would be @samp{1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks}. ++Generally the rule of thumb is that the number will be adjusted ++to be in the interval @samp{[1 .. 1000)}, although there are several ++exceptions to this rule. First, if the unit has a power then this ++is not possible; @samp{0.1 s^2} simplifies to @samp{100000 ms^2}. ++Second, the ``centi-'' prefix is allowed to form @code{cm} (centimeters), ++but will not apply to other units. The ``deci-,'' ``deka-,'' and ++``hecto-'' prefixes are never used. Thus the allowable interval is ++@samp{[1 .. 10)} for millimeters and @samp{[1 .. 100)} for centimeters. ++Finally, a prefix will not be added to a unit if the resulting name ++is also the actual name of another unit; @samp{1e-15 t} would normally ++be considered a ``femto-ton,'' but it is written as @samp{1000 at} ++(1000 atto-tons) instead because @code{ft} would be confused with feet. ++ ++@node The Units Table, Predefined Units, Basic Operations on Units, Units ++@section The Units Table ++ ++@noindent ++@kindex u v ++@pindex calc-enter-units-table ++The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table ++in another buffer called @code{*Units Table*}. Each entry in this table ++gives the unit name as it would appear in an expression, the definition ++of the unit in terms of simpler units, and a full name or description of ++the unit. Fundamental units are defined as themselves; these are the ++units produced by the @kbd{u b} command. The fundamental units are ++meters, seconds, grams, kelvins, amperes, candelas, moles, radians, ++and steradians. ++ ++The Units Table buffer also displays the Unit Prefix Table. Note that ++two prefixes, ``kilo'' and ``hecto,'' accept either upper- or lower-case ++prefix letters. @samp{Meg} is also accepted as a synonym for the @samp{M} ++prefix. Whenever a unit name can be interpreted as either a built-in name ++or a prefix followed by another built-in name, the former interpretation ++wins. For example, @samp{2 pt} means two pints, not two pico-tons. ++ ++The Units Table buffer, once created, is not rebuilt unless you define ++new units. To force the buffer to be rebuilt, give any numeric prefix ++argument to @kbd{u v}. ++ ++@kindex u V ++@pindex calc-view-units-table ++The @kbd{u V} (@code{calc-view-units-table}) command is like @kbd{u v} except ++that the cursor is not moved into the Units Table buffer. You can ++type @kbd{u V} again to remove the Units Table from the display. To ++return from the Units Table buffer after a @kbd{u v}, type @kbd{C-x * c} ++again or use the regular Emacs @w{@kbd{C-x o}} (@code{other-window}) ++command. You can also kill the buffer with @kbd{C-x k} if you wish; ++the actual units table is safely stored inside the Calculator. ++ ++@kindex u g ++@pindex calc-get-unit-definition ++The @kbd{u g} (@code{calc-get-unit-definition}) command retrieves a unit's ++defining expression and pushes it onto the Calculator stack. For example, ++@kbd{u g in} will produce the expression @samp{2.54 cm}. This is the ++same definition for the unit that would appear in the Units Table buffer. ++Note that this command works only for actual unit names; @kbd{u g km} ++will report that no such unit exists, for example, because @code{km} is ++really the unit @code{m} with a @code{k} (``kilo'') prefix. To see a ++definition of a unit in terms of base units, it is easier to push the ++unit name on the stack and then reduce it to base units with @kbd{u b}. ++ ++@kindex u e ++@pindex calc-explain-units ++The @kbd{u e} (@code{calc-explain-units}) command displays an English ++description of the units of the expression on the stack. For example, ++for the expression @samp{62 km^2 g / s^2 mol K}, the description is ++``Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin).'' This ++command uses the English descriptions that appear in the righthand ++column of the Units Table. ++ ++@node Predefined Units, User-Defined Units, The Units Table, Units ++@section Predefined Units ++ ++@noindent ++The definitions of many units have changed over the years. For example, ++the meter was originally defined in 1791 as one ten-millionth of the ++distance from the equator to the north pole. In order to be more ++precise, the definition was adjusted several times, and now a meter is ++defined as the distance that light will travel in a vacuum in ++1/299792458 of a second; consequently, the speed of light in a ++vacuum is exactly 299792458 m/s. Many other units have been ++redefined in terms of fundamental physical processes; a second, for ++example, is currently defined as 9192631770 periods of a certain ++radiation related to the cesium-133 atom. The only SI unit that is not ++based on a fundamental physical process (although there are efforts to ++change this) is the kilogram, which was originally defined as the mass ++of one liter of water, but is now defined as the mass of the ++International Prototype Kilogram (IPK), a cylinder of platinum-iridium ++kept at the Bureau International des Poids et Mesures in S@`evres, ++France. (There are several copies of the IPK throughout the world.) ++The British imperial units, once defined in terms of physical objects, ++were redefined in 1963 in terms of SI units. The US customary units, ++which were the same as British units until the British imperial system ++was created in 1824, were also defined in terms of the SI units in 1893. ++Because of these redefinitions, conversions between metric, British ++Imperial, and US customary units can often be done precisely. ++ ++Since the exact definitions of many kinds of units have evolved over the ++years, and since certain countries sometimes have local differences in ++their definitions, it is a good idea to examine Calc's definition of a ++unit before depending on its exact value. For example, there are three ++different units for gallons, corresponding to the US (@code{gal}), ++Canadian (@code{galC}), and British (@code{galUK}) definitions. Also, ++note that @code{oz} is a standard ounce of mass, @code{ozt} is a Troy ++ounce, and @code{ozfl} is a fluid ounce. ++ ++The temperature units corresponding to degrees Kelvin and Centigrade ++(Celsius) are the same in this table, since most units commands treat ++temperatures as being relative. The @code{calc-convert-temperature} ++command has special rules for handling the different absolute magnitudes ++of the various temperature scales. ++ ++The unit of volume ``liters'' can be referred to by either the lower-case ++@code{l} or the upper-case @code{L}. ++ ++The unit @code{A} stands for Amperes; the name @code{Ang} is used ++@tex ++for \AA ngstroms. ++@end tex ++@ifnottex ++for Angstroms. ++@end ifnottex ++ ++The unit @code{pt} stands for pints; the name @code{point} stands for ++a typographical point, defined by @samp{72 point = 1 in}. This is ++slightly different than the point defined by the American Typefounder's ++Association in 1886, but the point used by Calc has become standard ++largely due to its use by the PostScript page description language. ++There is also @code{texpt}, which stands for a printer's point as ++defined by the @TeX{} typesetting system: @samp{72.27 texpt = 1 in}. ++Other units used by @TeX{} are available; they are @code{texpc} (a pica), ++@code{texbp} (a ``big point'', equal to a standard point which is larger ++than the point used by @TeX{}), @code{texdd} (a Didot point), ++@code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point, ++all dimensions representable in @TeX{} are multiples of this value). ++ ++The unit @code{e} stands for the elementary (electron) unit of charge; ++because algebra command could mistake this for the special constant ++@expr{e}, Calc provides the alternate unit name @code{ech} which is ++preferable to @code{e}. ++ ++The name @code{g} stands for one gram of mass; there is also @code{gf}, ++one gram of force. (Likewise for @kbd{lb}, pounds, and @kbd{lbf}.) ++Meanwhile, one ``@expr{g}'' of acceleration is denoted @code{ga}. ++ ++The unit @code{ton} is a U.S. ton of @samp{2000 lb}, and @code{t} is ++a metric ton of @samp{1000 kg}. ++ ++The names @code{s} (or @code{sec}) and @code{min} refer to units of ++time; @code{arcsec} and @code{arcmin} are units of angle. ++ ++Some ``units'' are really physical constants; for example, @code{c} ++represents the speed of light, and @code{h} represents Planck's ++constant. You can use these just like other units: converting ++@samp{.5 c} to @samp{m/s} expresses one-half the speed of light in ++meters per second. You can also use this merely as a handy reference; ++the @kbd{u g} command gets the definition of one of these constants ++in its normal terms, and @kbd{u b} expresses the definition in base ++units. ++ ++Two units, @code{pi} and @code{alpha} (the fine structure constant, ++approximately @mathit{1/137}) are dimensionless. The units simplification ++commands simply treat these names as equivalent to their corresponding ++values. However you can, for example, use @kbd{u c} to convert a pure ++number into multiples of the fine structure constant, or @kbd{u b} to ++convert this back into a pure number. (When @kbd{u c} prompts for the ++``old units,'' just enter a blank line to signify that the value ++really is unitless.) ++ ++@c Describe angular units, luminosity vs. steradians problem. ++ ++@node User-Defined Units, , Predefined Units, Units ++@section User-Defined Units ++ ++@noindent ++Calc provides ways to get quick access to your selected ``favorite'' ++units, as well as ways to define your own new units. ++ ++@kindex u 0-9 ++@pindex calc-quick-units ++@vindex Units ++@cindex @code{Units} variable ++@cindex Quick units ++To select your favorite units, store a vector of unit names or ++expressions in the Calc variable @code{Units}. The @kbd{u 1} ++through @kbd{u 9} commands (@code{calc-quick-units}) provide access ++to these units. If the value on the top of the stack is a plain ++number (with no units attached), then @kbd{u 1} gives it the ++specified units. (Basically, it multiplies the number by the ++first item in the @code{Units} vector.) If the number on the ++stack @emph{does} have units, then @kbd{u 1} converts that number ++to the new units. For example, suppose the vector @samp{[in, ft]} ++is stored in @code{Units}. Then @kbd{30 u 1} will create the ++expression @samp{30 in}, and @kbd{u 2} will convert that expression ++to @samp{2.5 ft}. ++ ++The @kbd{u 0} command accesses the tenth element of @code{Units}. ++Only ten quick units may be defined at a time. If the @code{Units} ++variable has no stored value (the default), or if its value is not ++a vector, then the quick-units commands will not function. The ++@kbd{s U} command is a convenient way to edit the @code{Units} ++variable; @pxref{Operations on Variables}. ++ ++@kindex u d ++@pindex calc-define-unit ++@cindex User-defined units ++The @kbd{u d} (@code{calc-define-unit}) command records the units ++expression on the top of the stack as the definition for a new, ++user-defined unit. For example, putting @samp{16.5 ft} on the stack and ++typing @kbd{u d rod} defines the new unit @samp{rod} to be equivalent to ++16.5 feet. The unit conversion and simplification commands will now ++treat @code{rod} just like any other unit of length. You will also be ++prompted for an optional English description of the unit, which will ++appear in the Units Table. If you wish the definition of this unit to ++be displayed in a special way in the Units Table buffer (such as with an ++asterisk to indicate an approximate value), then you can call this ++command with an argument, @kbd{C-u u d}; you will then also be prompted ++for a string that will be used to display the definition. ++ ++@kindex u u ++@pindex calc-undefine-unit ++The @kbd{u u} (@code{calc-undefine-unit}) command removes a user-defined ++unit. It is not possible to remove one of the predefined units, ++however. ++ ++If you define a unit with an existing unit name, your new definition ++will replace the original definition of that unit. If the unit was a ++predefined unit, the old definition will not be replaced, only ++``shadowed.'' The built-in definition will reappear if you later use ++@kbd{u u} to remove the shadowing definition. ++ ++To create a new fundamental unit, use either 1 or the unit name itself ++as the defining expression. Otherwise the expression can involve any ++other units that you like (except for composite units like @samp{mfi}). ++You can create a new composite unit with a sum of other units as the ++defining expression. The next unit operation like @kbd{u c} or @kbd{u v} ++will rebuild the internal unit table incorporating your modifications. ++Note that erroneous definitions (such as two units defined in terms of ++each other) will not be detected until the unit table is next rebuilt; ++@kbd{u v} is a convenient way to force this to happen. ++ ++Temperature units are treated specially inside the Calculator; it is not ++possible to create user-defined temperature units. ++ ++@kindex u p ++@pindex calc-permanent-units ++@cindex Calc init file, user-defined units ++The @kbd{u p} (@code{calc-permanent-units}) command stores the user-defined ++units in your Calc init file (the file given by the variable ++@code{calc-settings-file}, typically @file{~/.calc.el}), so that the ++units will still be available in subsequent Emacs sessions. If there ++was already a set of user-defined units in your Calc init file, it ++is replaced by the new set. (@xref{General Mode Commands}, for a way to ++tell Calc to use a different file for the Calc init file.) ++ ++@node Store and Recall, Graphics, Units, Top ++@chapter Storing and Recalling ++ ++@noindent ++Calculator variables are really just Lisp variables that contain numbers ++or formulas in a form that Calc can understand. The commands in this ++section allow you to manipulate variables conveniently. Commands related ++to variables use the @kbd{s} prefix key. ++ ++@menu ++* Storing Variables:: ++* Recalling Variables:: ++* Operations on Variables:: ++* Let Command:: ++* Evaluates-To Operator:: ++@end menu ++ ++@node Storing Variables, Recalling Variables, Store and Recall, Store and Recall ++@section Storing Variables ++ ++@noindent ++@kindex s s ++@pindex calc-store ++@cindex Storing variables ++@cindex Quick variables ++@vindex q0 ++@vindex q9 ++The @kbd{s s} (@code{calc-store}) command stores the value at the top of ++the stack into a specified variable. It prompts you to enter the ++name of the variable. If you press a single digit, the value is stored ++immediately in one of the ``quick'' variables @code{q0} through ++@code{q9}. Or you can enter any variable name. ++ ++@kindex s t ++@pindex calc-store-into ++The @kbd{s s} command leaves the stored value on the stack. There is ++also an @kbd{s t} (@code{calc-store-into}) command, which removes a ++value from the stack and stores it in a variable. ++ ++If the top of stack value is an equation @samp{a = 7} or assignment ++@samp{a := 7} with a variable on the lefthand side, then Calc will ++assign that variable with that value by default, i.e., if you type ++@kbd{s s @key{RET}} or @kbd{s t @key{RET}}. In this example, the ++value 7 would be stored in the variable @samp{a}. (If you do type ++a variable name at the prompt, the top-of-stack value is stored in ++its entirety, even if it is an equation: @samp{s s b @key{RET}} ++with @samp{a := 7} on the stack stores @samp{a := 7} in @code{b}.) ++ ++In fact, the top of stack value can be a vector of equations or ++assignments with different variables on their lefthand sides; the ++default will be to store all the variables with their corresponding ++righthand sides simultaneously. ++ ++It is also possible to type an equation or assignment directly at ++the prompt for the @kbd{s s} or @kbd{s t} command: @kbd{s s foo = 7}. ++In this case the expression to the right of the @kbd{=} or @kbd{:=} ++symbol is evaluated as if by the @kbd{=} command, and that value is ++stored in the variable. No value is taken from the stack; @kbd{s s} ++and @kbd{s t} are equivalent when used in this way. ++ ++@kindex s 0-9 ++@kindex t 0-9 ++The prefix keys @kbd{s} and @kbd{t} may be followed immediately by a ++digit; @kbd{s 9} is equivalent to @kbd{s s 9}, and @kbd{t 9} is ++equivalent to @kbd{s t 9}. (The @kbd{t} prefix is otherwise used ++for trail and time/date commands.) ++ ++@kindex s + ++@kindex s - ++@ignore ++@mindex @idots ++@end ignore ++@kindex s * ++@ignore ++@mindex @null ++@end ignore ++@kindex s / ++@ignore ++@mindex @null ++@end ignore ++@kindex s ^ ++@ignore ++@mindex @null ++@end ignore ++@kindex s | ++@ignore ++@mindex @null ++@end ignore ++@kindex s n ++@ignore ++@mindex @null ++@end ignore ++@kindex s & ++@ignore ++@mindex @null ++@end ignore ++@kindex s [ ++@ignore ++@mindex @null ++@end ignore ++@kindex s ] ++@pindex calc-store-plus ++@pindex calc-store-minus ++@pindex calc-store-times ++@pindex calc-store-div ++@pindex calc-store-power ++@pindex calc-store-concat ++@pindex calc-store-neg ++@pindex calc-store-inv ++@pindex calc-store-decr ++@pindex calc-store-incr ++There are also several ``arithmetic store'' commands. For example, ++@kbd{s +} removes a value from the stack and adds it to the specified ++variable. The other arithmetic stores are @kbd{s -}, @kbd{s *}, @kbd{s /}, ++@kbd{s ^}, and @w{@kbd{s |}} (vector concatenation), plus @kbd{s n} and ++@kbd{s &} which negate or invert the value in a variable, and @w{@kbd{s [}} ++and @kbd{s ]} which decrease or increase a variable by one. ++ ++All the arithmetic stores accept the Inverse prefix to reverse the ++order of the operands. If @expr{v} represents the contents of the ++variable, and @expr{a} is the value drawn from the stack, then regular ++@w{@kbd{s -}} assigns ++@texline @math{v \coloneq v - a}, ++@infoline @expr{v := v - a}, ++but @kbd{I s -} assigns ++@texline @math{v \coloneq a - v}. ++@infoline @expr{v := a - v}. ++While @kbd{I s *} might seem pointless, it is ++useful if matrix multiplication is involved. Actually, all the ++arithmetic stores use formulas designed to behave usefully both ++forwards and backwards: ++ ++@example ++@group ++s + v := v + a v := a + v ++s - v := v - a v := a - v ++s * v := v * a v := a * v ++s / v := v / a v := a / v ++s ^ v := v ^ a v := a ^ v ++s | v := v | a v := a | v ++s n v := v / (-1) v := (-1) / v ++s & v := v ^ (-1) v := (-1) ^ v ++s [ v := v - 1 v := 1 - v ++s ] v := v - (-1) v := (-1) - v ++@end group ++@end example ++ ++In the last four cases, a numeric prefix argument will be used in ++place of the number one. (For example, @kbd{M-2 s ]} increases ++a variable by 2, and @kbd{M-2 I s ]} replaces a variable by ++minus-two minus the variable. ++ ++The first six arithmetic stores can also be typed @kbd{s t +}, @kbd{s t -}, ++etc. The commands @kbd{s s +}, @kbd{s s -}, and so on are analogous ++arithmetic stores that don't remove the value @expr{a} from the stack. ++ ++All arithmetic stores report the new value of the variable in the ++Trail for your information. They signal an error if the variable ++previously had no stored value. If default simplifications have been ++turned off, the arithmetic stores temporarily turn them on for numeric ++arguments only (i.e., they temporarily do an @kbd{m N} command). ++@xref{Simplification Modes}. Large vectors put in the trail by ++these commands always use abbreviated (@kbd{t .}) mode. ++ ++@kindex s m ++@pindex calc-store-map ++The @kbd{s m} command is a general way to adjust a variable's value ++using any Calc function. It is a ``mapping'' command analogous to ++@kbd{V M}, @kbd{V R}, etc. @xref{Reducing and Mapping}, to see ++how to specify a function for a mapping command. Basically, ++all you do is type the Calc command key that would invoke that ++function normally. For example, @kbd{s m n} applies the @kbd{n} ++key to negate the contents of the variable, so @kbd{s m n} is ++equivalent to @kbd{s n}. Also, @kbd{s m Q} takes the square root ++of the value stored in a variable, @kbd{s m v v} uses @kbd{v v} to ++reverse the vector stored in the variable, and @kbd{s m H I S} ++takes the hyperbolic arcsine of the variable contents. ++ ++If the mapping function takes two or more arguments, the additional ++arguments are taken from the stack; the old value of the variable ++is provided as the first argument. Thus @kbd{s m -} with @expr{a} ++on the stack computes @expr{v - a}, just like @kbd{s -}. With the ++Inverse prefix, the variable's original value becomes the @emph{last} ++argument instead of the first. Thus @kbd{I s m -} is also ++equivalent to @kbd{I s -}. ++ ++@kindex s x ++@pindex calc-store-exchange ++The @kbd{s x} (@code{calc-store-exchange}) command exchanges the value ++of a variable with the value on the top of the stack. Naturally, the ++variable must already have a stored value for this to work. ++ ++You can type an equation or assignment at the @kbd{s x} prompt. The ++command @kbd{s x a=6} takes no values from the stack; instead, it ++pushes the old value of @samp{a} on the stack and stores @samp{a = 6}. ++ ++@kindex s u ++@pindex calc-unstore ++@cindex Void variables ++@cindex Un-storing variables ++Until you store something in them, most variables are ``void,'' that is, ++they contain no value at all. If they appear in an algebraic formula ++they will be left alone even if you press @kbd{=} (@code{calc-evaluate}). ++The @kbd{s u} (@code{calc-unstore}) command returns a variable to the ++void state. ++ ++@kindex s c ++@pindex calc-copy-variable ++The @kbd{s c} (@code{calc-copy-variable}) command copies the stored ++value of one variable to another. One way it differs from a simple ++@kbd{s r} followed by an @kbd{s t} (aside from saving keystrokes) is ++that the value never goes on the stack and thus is never rounded, ++evaluated, or simplified in any way; it is not even rounded down to the ++current precision. ++ ++The only variables with predefined values are the ``special constants'' ++@code{pi}, @code{e}, @code{i}, @code{phi}, and @code{gamma}. You are free ++to unstore these variables or to store new values into them if you like, ++although some of the algebraic-manipulation functions may assume these ++variables represent their standard values. Calc displays a warning if ++you change the value of one of these variables, or of one of the other ++special variables @code{inf}, @code{uinf}, and @code{nan} (which are ++normally void). ++ ++Note that @code{pi} doesn't actually have 3.14159265359 stored in it, ++but rather a special magic value that evaluates to @cpi{} at the current ++precision. Likewise @code{e}, @code{i}, and @code{phi} evaluate ++according to the current precision or polar mode. If you recall a value ++from @code{pi} and store it back, this magic property will be lost. The ++magic property is preserved, however, when a variable is copied with ++@kbd{s c}. ++ ++@kindex s k ++@pindex calc-copy-special-constant ++If one of the ``special constants'' is redefined (or undefined) so that ++it no longer has its magic property, the property can be restored with ++@kbd{s k} (@code{calc-copy-special-constant}). This command will prompt ++for a special constant and a variable to store it in, and so a special ++constant can be stored in any variable. Here, the special constant that ++you enter doesn't depend on the value of the corresponding variable; ++@code{pi} will represent 3.14159@dots{} regardless of what is currently ++stored in the Calc variable @code{pi}. If one of the other special ++variables, @code{inf}, @code{uinf} or @code{nan}, is given a value, its ++original behavior can be restored by voiding it with @kbd{s u}. ++ ++@node Recalling Variables, Operations on Variables, Storing Variables, Store and Recall ++@section Recalling Variables ++ ++@noindent ++@kindex s r ++@pindex calc-recall ++@cindex Recalling variables ++The most straightforward way to extract the stored value from a variable ++is to use the @kbd{s r} (@code{calc-recall}) command. This command prompts ++for a variable name (similarly to @code{calc-store}), looks up the value ++of the specified variable, and pushes that value onto the stack. It is ++an error to try to recall a void variable. ++ ++It is also possible to recall the value from a variable by evaluating a ++formula containing that variable. For example, @kbd{' a @key{RET} =} is ++the same as @kbd{s r a @key{RET}} except that if the variable is void, the ++former will simply leave the formula @samp{a} on the stack whereas the ++latter will produce an error message. ++ ++@kindex r 0-9 ++The @kbd{r} prefix may be followed by a digit, so that @kbd{r 9} is ++equivalent to @kbd{s r 9}. ++ ++@node Operations on Variables, Let Command, Recalling Variables, Store and Recall ++@section Other Operations on Variables ++ ++@noindent ++@kindex s e ++@pindex calc-edit-variable ++The @kbd{s e} (@code{calc-edit-variable}) command edits the stored ++value of a variable without ever putting that value on the stack ++or simplifying or evaluating the value. It prompts for the name of ++the variable to edit. If the variable has no stored value, the ++editing buffer will start out empty. If the editing buffer is ++empty when you press @kbd{C-c C-c} to finish, the variable will ++be made void. @xref{Editing Stack Entries}, for a general ++description of editing. ++ ++The @kbd{s e} command is especially useful for creating and editing ++rewrite rules which are stored in variables. Sometimes these rules ++contain formulas which must not be evaluated until the rules are ++actually used. (For example, they may refer to @samp{deriv(x,y)}, ++where @code{x} will someday become some expression involving @code{y}; ++if you let Calc evaluate the rule while you are defining it, Calc will ++replace @samp{deriv(x,y)} with 0 because the formula @code{x} does ++not itself refer to @code{y}.) By contrast, recalling the variable, ++editing with @kbd{`}, and storing will evaluate the variable's value ++as a side effect of putting the value on the stack. ++ ++@kindex s A ++@kindex s D ++@ignore ++@mindex @idots ++@end ignore ++@kindex s E ++@ignore ++@mindex @null ++@end ignore ++@kindex s F ++@ignore ++@mindex @null ++@end ignore ++@kindex s G ++@ignore ++@mindex @null ++@end ignore ++@kindex s H ++@ignore ++@mindex @null ++@end ignore ++@kindex s I ++@ignore ++@mindex @null ++@end ignore ++@kindex s L ++@ignore ++@mindex @null ++@end ignore ++@kindex s P ++@ignore ++@mindex @null ++@end ignore ++@kindex s R ++@ignore ++@mindex @null ++@end ignore ++@kindex s T ++@ignore ++@mindex @null ++@end ignore ++@kindex s U ++@ignore ++@mindex @null ++@end ignore ++@kindex s X ++@pindex calc-store-AlgSimpRules ++@pindex calc-store-Decls ++@pindex calc-store-EvalRules ++@pindex calc-store-FitRules ++@pindex calc-store-GenCount ++@pindex calc-store-Holidays ++@pindex calc-store-IntegLimit ++@pindex calc-store-LineStyles ++@pindex calc-store-PointStyles ++@pindex calc-store-PlotRejects ++@pindex calc-store-TimeZone ++@pindex calc-store-Units ++@pindex calc-store-ExtSimpRules ++There are several special-purpose variable-editing commands that ++use the @kbd{s} prefix followed by a shifted letter: ++ ++@table @kbd ++@item s A ++Edit @code{AlgSimpRules}. @xref{Algebraic Simplifications}. ++@item s D ++Edit @code{Decls}. @xref{Declarations}. ++@item s E ++Edit @code{EvalRules}. @xref{Default Simplifications}. ++@item s F ++Edit @code{FitRules}. @xref{Curve Fitting}. ++@item s G ++Edit @code{GenCount}. @xref{Solving Equations}. ++@item s H ++Edit @code{Holidays}. @xref{Business Days}. ++@item s I ++Edit @code{IntegLimit}. @xref{Calculus}. ++@item s L ++Edit @code{LineStyles}. @xref{Graphics}. ++@item s P ++Edit @code{PointStyles}. @xref{Graphics}. ++@item s R ++Edit @code{PlotRejects}. @xref{Graphics}. ++@item s T ++Edit @code{TimeZone}. @xref{Time Zones}. ++@item s U ++Edit @code{Units}. @xref{User-Defined Units}. ++@item s X ++Edit @code{ExtSimpRules}. @xref{Unsafe Simplifications}. ++@end table ++ ++These commands are just versions of @kbd{s e} that use fixed variable ++names rather than prompting for the variable name. ++ ++@kindex s p ++@pindex calc-permanent-variable ++@cindex Storing variables ++@cindex Permanent variables ++@cindex Calc init file, variables ++The @kbd{s p} (@code{calc-permanent-variable}) command saves a ++variable's value permanently in your Calc init file (the file given by ++the variable @code{calc-settings-file}, typically @file{~/.calc.el}), so ++that its value will still be available in future Emacs sessions. You ++can re-execute @w{@kbd{s p}} later on to update the saved value, but the ++only way to remove a saved variable is to edit your calc init file ++by hand. (@xref{General Mode Commands}, for a way to tell Calc to ++use a different file for the Calc init file.) ++ ++If you do not specify the name of a variable to save (i.e., ++@kbd{s p @key{RET}}), all Calc variables with defined values ++are saved except for the special constants @code{pi}, @code{e}, ++@code{i}, @code{phi}, and @code{gamma}; the variables @code{TimeZone} ++and @code{PlotRejects}; ++@code{FitRules}, @code{DistribRules}, and other built-in rewrite ++rules; and @code{PlotData@var{n}} variables generated ++by the graphics commands. (You can still save these variables by ++explicitly naming them in an @kbd{s p} command.) ++ ++@kindex s i ++@pindex calc-insert-variables ++The @kbd{s i} (@code{calc-insert-variables}) command writes ++the values of all Calc variables into a specified buffer. ++The variables are written with the prefix @code{var-} in the form of ++Lisp @code{setq} commands ++which store the values in string form. You can place these commands ++in your Calc init file (or @file{.emacs}) if you wish, though in this case it ++would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i} ++omits the same set of variables as @w{@kbd{s p @key{RET}}}; the difference ++is that @kbd{s i} will store the variables in any buffer, and it also ++stores in a more human-readable format.) ++ ++@node Let Command, Evaluates-To Operator, Operations on Variables, Store and Recall ++@section The Let Command ++ ++@noindent ++@kindex s l ++@pindex calc-let ++@cindex Variables, temporary assignment ++@cindex Temporary assignment to variables ++If you have an expression like @samp{a+b^2} on the stack and you wish to ++compute its value where @expr{b=3}, you can simply store 3 in @expr{b} and ++then press @kbd{=} to reevaluate the formula. This has the side-effect ++of leaving the stored value of 3 in @expr{b} for future operations. ++ ++The @kbd{s l} (@code{calc-let}) command evaluates a formula under a ++@emph{temporary} assignment of a variable. It stores the value on the ++top of the stack into the specified variable, then evaluates the ++second-to-top stack entry, then restores the original value (or lack of one) ++in the variable. Thus after @kbd{'@w{ }a+b^2 @key{RET} 3 s l b @key{RET}}, ++the stack will contain the formula @samp{a + 9}. The subsequent command ++@kbd{@w{5 s l a} @key{RET}} will replace this formula with the number 14. ++The variables @samp{a} and @samp{b} are not permanently affected in any way ++by these commands. ++ ++The value on the top of the stack may be an equation or assignment, or ++a vector of equations or assignments, in which case the default will be ++analogous to the case of @kbd{s t @key{RET}}. @xref{Storing Variables}. ++ ++Also, you can answer the variable-name prompt with an equation or ++assignment: @kbd{s l b=3 @key{RET}} is the same as storing 3 on the stack ++and typing @kbd{s l b @key{RET}}. ++ ++The @kbd{a b} (@code{calc-substitute}) command is another way to substitute ++a variable with a value in a formula. It does an actual substitution ++rather than temporarily assigning the variable and evaluating. For ++example, letting @expr{n=2} in @samp{f(n pi)} with @kbd{a b} will ++produce @samp{f(2 pi)}, whereas @kbd{s l} would give @samp{f(6.28)} ++since the evaluation step will also evaluate @code{pi}. ++ ++@node Evaluates-To Operator, , Let Command, Store and Recall ++@section The Evaluates-To Operator ++ ++@noindent ++@tindex evalto ++@tindex => ++@cindex Evaluates-to operator ++@cindex @samp{=>} operator ++The special algebraic symbol @samp{=>} is known as the @dfn{evaluates-to ++operator}. (It will show up as an @code{evalto} function call in ++other language modes like Pascal and La@TeX{}.) This is a binary ++operator, that is, it has a lefthand and a righthand argument, ++although it can be entered with the righthand argument omitted. ++ ++A formula like @samp{@var{a} => @var{b}} is evaluated by Calc as ++follows: First, @var{a} is not simplified or modified in any ++way. The previous value of argument @var{b} is thrown away; the ++formula @var{a} is then copied and evaluated as if by the @kbd{=} ++command according to all current modes and stored variable values, ++and the result is installed as the new value of @var{b}. ++ ++For example, suppose you enter the algebraic formula @samp{2 + 3 => 17}. ++The number 17 is ignored, and the lefthand argument is left in its ++unevaluated form; the result is the formula @samp{2 + 3 => 5}. ++ ++@kindex s = ++@pindex calc-evalto ++You can enter an @samp{=>} formula either directly using algebraic ++entry (in which case the righthand side may be omitted since it is ++going to be replaced right away anyhow), or by using the @kbd{s =} ++(@code{calc-evalto}) command, which takes @var{a} from the stack ++and replaces it with @samp{@var{a} => @var{b}}. ++ ++Calc keeps track of all @samp{=>} operators on the stack, and ++recomputes them whenever anything changes that might affect their ++values, i.e., a mode setting or variable value. This occurs only ++if the @samp{=>} operator is at the top level of the formula, or ++if it is part of a top-level vector. In other words, pushing ++@samp{2 + (a => 17)} will change the 17 to the actual value of ++@samp{a} when you enter the formula, but the result will not be ++dynamically updated when @samp{a} is changed later because the ++@samp{=>} operator is buried inside a sum. However, a vector ++of @samp{=>} operators will be recomputed, since it is convenient ++to push a vector like @samp{[a =>, b =>, c =>]} on the stack to ++make a concise display of all the variables in your problem. ++(Another way to do this would be to use @samp{[a, b, c] =>}, ++which provides a slightly different format of display. You ++can use whichever you find easiest to read.) ++ ++@kindex m C ++@pindex calc-auto-recompute ++The @kbd{m C} (@code{calc-auto-recompute}) command allows you to ++turn this automatic recomputation on or off. If you turn ++recomputation off, you must explicitly recompute an @samp{=>} ++operator on the stack in one of the usual ways, such as by ++pressing @kbd{=}. Turning recomputation off temporarily can save ++a lot of time if you will be changing several modes or variables ++before you look at the @samp{=>} entries again. ++ ++Most commands are not especially useful with @samp{=>} operators ++as arguments. For example, given @samp{x + 2 => 17}, it won't ++work to type @kbd{1 +} to get @samp{x + 3 => 18}. If you want ++to operate on the lefthand side of the @samp{=>} operator on ++the top of the stack, type @kbd{j 1} (that's the digit ``one'') ++to select the lefthand side, execute your commands, then type ++@kbd{j u} to unselect. ++ ++All current modes apply when an @samp{=>} operator is computed, ++including the current simplification mode. Recall that the ++formula @samp{x + y + x} is not handled by Calc's default ++simplifications, but the @kbd{a s} command will reduce it to ++the simpler form @samp{y + 2 x}. You can also type @kbd{m A} ++to enable an Algebraic Simplification mode in which the ++equivalent of @kbd{a s} is used on all of Calc's results. ++If you enter @samp{x + y + x =>} normally, the result will ++be @samp{x + y + x => x + y + x}. If you change to ++Algebraic Simplification mode, the result will be ++@samp{x + y + x => y + 2 x}. However, just pressing @kbd{a s} ++once will have no effect on @samp{x + y + x => x + y + x}, ++because the righthand side depends only on the lefthand side ++and the current mode settings, and the lefthand side is not ++affected by commands like @kbd{a s}. ++ ++The ``let'' command (@kbd{s l}) has an interesting interaction ++with the @samp{=>} operator. The @kbd{s l} command evaluates the ++second-to-top stack entry with the top stack entry supplying ++a temporary value for a given variable. As you might expect, ++if that stack entry is an @samp{=>} operator its righthand ++side will temporarily show this value for the variable. In ++fact, all @samp{=>}s on the stack will be updated if they refer ++to that variable. But this change is temporary in the sense ++that the next command that causes Calc to look at those stack ++entries will make them revert to the old variable value. ++ ++@smallexample ++@group ++2: a => a 2: a => 17 2: a => a ++1: a + 1 => a + 1 1: a + 1 => 18 1: a + 1 => a + 1 ++ . . . ++ ++ 17 s l a @key{RET} p 8 @key{RET} ++@end group ++@end smallexample ++ ++Here the @kbd{p 8} command changes the current precision, ++thus causing the @samp{=>} forms to be recomputed after the ++influence of the ``let'' is gone. The @kbd{d @key{SPC}} command ++(@code{calc-refresh}) is a handy way to force the @samp{=>} ++operators on the stack to be recomputed without any other ++side effects. ++ ++@kindex s : ++@pindex calc-assign ++@tindex assign ++@tindex := ++Embedded mode also uses @samp{=>} operators. In Embedded mode, ++the lefthand side of an @samp{=>} operator can refer to variables ++assigned elsewhere in the file by @samp{:=} operators. The ++assignment operator @samp{a := 17} does not actually do anything ++by itself. But Embedded mode recognizes it and marks it as a sort ++of file-local definition of the variable. You can enter @samp{:=} ++operators in Algebraic mode, or by using the @kbd{s :} ++(@code{calc-assign}) [@code{assign}] command which takes a variable ++and value from the stack and replaces them with an assignment. ++ ++@xref{TeX and LaTeX Language Modes}, for the way @samp{=>} appears in ++@TeX{} language output. The @dfn{eqn} mode gives similar ++treatment to @samp{=>}. ++ ++@node Graphics, Kill and Yank, Store and Recall, Top ++@chapter Graphics ++ ++@noindent ++The commands for graphing data begin with the @kbd{g} prefix key. Calc ++uses GNUPLOT 2.0 or later to do graphics. These commands will only work ++if GNUPLOT is available on your system. (While GNUPLOT sounds like ++a relative of GNU Emacs, it is actually completely unrelated. ++However, it is free software. It can be obtained from ++@samp{http://www.gnuplot.info}.) ++ ++@vindex calc-gnuplot-name ++If you have GNUPLOT installed on your system but Calc is unable to ++find it, you may need to set the @code{calc-gnuplot-name} variable ++in your Calc init file or @file{.emacs}. You may also need to set some Lisp ++variables to show Calc how to run GNUPLOT on your system; these ++are described under @kbd{g D} and @kbd{g O} below. If you are ++using the X window system, Calc will configure GNUPLOT for you ++automatically. If you have GNUPLOT 3.0 or later and you are not using X, ++Calc will configure GNUPLOT to display graphs using simple character ++graphics that will work on any terminal. ++ ++@menu ++* Basic Graphics:: ++* Three Dimensional Graphics:: ++* Managing Curves:: ++* Graphics Options:: ++* Devices:: ++@end menu ++ ++@node Basic Graphics, Three Dimensional Graphics, Graphics, Graphics ++@section Basic Graphics ++ ++@noindent ++@kindex g f ++@pindex calc-graph-fast ++The easiest graphics command is @kbd{g f} (@code{calc-graph-fast}). ++This command takes two vectors of equal length from the stack. ++The vector at the top of the stack represents the ``y'' values of ++the various data points. The vector in the second-to-top position ++represents the corresponding ``x'' values. This command runs ++GNUPLOT (if it has not already been started by previous graphing ++commands) and displays the set of data points. The points will ++be connected by lines, and there will also be some kind of symbol ++to indicate the points themselves. ++ ++The ``x'' entry may instead be an interval form, in which case suitable ++``x'' values are interpolated between the minimum and maximum values of ++the interval (whether the interval is open or closed is ignored). ++ ++The ``x'' entry may also be a number, in which case Calc uses the ++sequence of ``x'' values @expr{x}, @expr{x+1}, @expr{x+2}, etc. ++(Generally the number 0 or 1 would be used for @expr{x} in this case.) ++ ++The ``y'' entry may be any formula instead of a vector. Calc effectively ++uses @kbd{N} (@code{calc-eval-num}) to evaluate variables in the formula; ++the result of this must be a formula in a single (unassigned) variable. ++The formula is plotted with this variable taking on the various ``x'' ++values. Graphs of formulas by default use lines without symbols at the ++computed data points. Note that if neither ``x'' nor ``y'' is a vector, ++Calc guesses at a reasonable number of data points to use. See the ++@kbd{g N} command below. (The ``x'' values must be either a vector ++or an interval if ``y'' is a formula.) ++ ++@ignore ++@starindex ++@end ignore ++@tindex xy ++If ``y'' is (or evaluates to) a formula of the form ++@samp{xy(@var{x}, @var{y})} then the result is a ++parametric plot. The two arguments of the fictitious @code{xy} function ++are used as the ``x'' and ``y'' coordinates of the curve, respectively. ++In this case the ``x'' vector or interval you specified is not directly ++visible in the graph. For example, if ``x'' is the interval @samp{[0..360]} ++and ``y'' is the formula @samp{xy(sin(t), cos(t))}, the resulting graph ++will be a circle. ++ ++Also, ``x'' and ``y'' may each be variable names, in which case Calc ++looks for suitable vectors, intervals, or formulas stored in those ++variables. ++ ++The ``x'' and ``y'' values for the data points (as pulled from the vectors, ++calculated from the formulas, or interpolated from the intervals) should ++be real numbers (integers, fractions, or floats). One exception to this ++is that the ``y'' entry can consist of a vector of numbers combined with ++error forms, in which case the points will be plotted with the ++appropriate error bars. Other than this, if either the ``x'' ++value or the ``y'' value of a given data point is not a real number, that ++data point will be omitted from the graph. The points on either side ++of the invalid point will @emph{not} be connected by a line. ++ ++See the documentation for @kbd{g a} below for a description of the way ++numeric prefix arguments affect @kbd{g f}. ++ ++@cindex @code{PlotRejects} variable ++@vindex PlotRejects ++If you store an empty vector in the variable @code{PlotRejects} ++(i.e., @kbd{[ ] s t PlotRejects}), Calc will append information to ++this vector for every data point which was rejected because its ++``x'' or ``y'' values were not real numbers. The result will be ++a matrix where each row holds the curve number, data point number, ++``x'' value, and ``y'' value for a rejected data point. ++@xref{Evaluates-To Operator}, for a handy way to keep tabs on the ++current value of @code{PlotRejects}. @xref{Operations on Variables}, ++for the @kbd{s R} command which is another easy way to examine ++@code{PlotRejects}. ++ ++@kindex g c ++@pindex calc-graph-clear ++To clear the graphics display, type @kbd{g c} (@code{calc-graph-clear}). ++If the GNUPLOT output device is an X window, the window will go away. ++Effects on other kinds of output devices will vary. You don't need ++to use @kbd{g c} if you don't want to---if you give another @kbd{g f} ++or @kbd{g p} command later on, it will reuse the existing graphics ++window if there is one. ++ ++@node Three Dimensional Graphics, Managing Curves, Basic Graphics, Graphics ++@section Three-Dimensional Graphics ++ ++@kindex g F ++@pindex calc-graph-fast-3d ++The @kbd{g F} (@code{calc-graph-fast-3d}) command makes a three-dimensional ++graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0, ++you will see a GNUPLOT error message if you try this command. ++ ++The @kbd{g F} command takes three values from the stack, called ``x'', ++``y'', and ``z'', respectively. As was the case for 2D graphs, there ++are several options for these values. ++ ++In the first case, ``x'' and ``y'' are each vectors (not necessarily of ++the same length); either or both may instead be interval forms. The ++``z'' value must be a matrix with the same number of rows as elements ++in ``x'', and the same number of columns as elements in ``y''. The ++result is a surface plot where ++@texline @math{z_{ij}} ++@infoline @expr{z_ij} ++is the height of the point ++at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will ++be displayed from a certain default viewpoint; you can change this ++viewpoint by adding a @samp{set view} to the @samp{*Gnuplot Commands*} ++buffer as described later. See the GNUPLOT documentation for a ++description of the @samp{set view} command. ++ ++Each point in the matrix will be displayed as a dot in the graph, ++and these points will be connected by a grid of lines (@dfn{isolines}). ++ ++In the second case, ``x'', ``y'', and ``z'' are all vectors of equal ++length. The resulting graph displays a 3D line instead of a surface, ++where the coordinates of points along the line are successive triplets ++of values from the input vectors. ++ ++In the third case, ``x'' and ``y'' are vectors or interval forms, and ++``z'' is any formula involving two variables (not counting variables ++with assigned values). These variables are sorted into alphabetical ++order; the first takes on values from ``x'' and the second takes on ++values from ``y'' to form a matrix of results that are graphed as a ++3D surface. ++ ++@ignore ++@starindex ++@end ignore ++@tindex xyz ++If the ``z'' formula evaluates to a call to the fictitious function ++@samp{xyz(@var{x}, @var{y}, @var{z})}, then the result is a ++``parametric surface.'' In this case, the axes of the graph are ++taken from the @var{x} and @var{y} values in these calls, and the ++``x'' and ``y'' values from the input vectors or intervals are used only ++to specify the range of inputs to the formula. For example, plotting ++@samp{[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))} ++will draw a sphere. (Since the default resolution for 3D plots is ++5 steps in each of ``x'' and ``y'', this will draw a very crude ++sphere. You could use the @kbd{g N} command, described below, to ++increase this resolution, or specify the ``x'' and ``y'' values as ++vectors with more than 5 elements. ++ ++It is also possible to have a function in a regular @kbd{g f} plot ++evaluate to an @code{xyz} call. Since @kbd{g f} plots a line, not ++a surface, the result will be a 3D parametric line. For example, ++@samp{[[0..720], xyz(sin(x), cos(x), x)]} will plot two turns of a ++helix (a three-dimensional spiral). ++ ++As for @kbd{g f}, each of ``x'', ``y'', and ``z'' may instead be ++variables containing the relevant data. ++ ++@node Managing Curves, Graphics Options, Three Dimensional Graphics, Graphics ++@section Managing Curves ++ ++@noindent ++The @kbd{g f} command is really shorthand for the following commands: ++@kbd{C-u g d g a g p}. Likewise, @w{@kbd{g F}} is shorthand for ++@kbd{C-u g d g A g p}. You can gain more control over your graph ++by using these commands directly. ++ ++@kindex g a ++@pindex calc-graph-add ++The @kbd{g a} (@code{calc-graph-add}) command adds the ``curve'' ++represented by the two values on the top of the stack to the current ++graph. You can have any number of curves in the same graph. When ++you give the @kbd{g p} command, all the curves will be drawn superimposed ++on the same axes. ++ ++The @kbd{g a} command (and many others that affect the current graph) ++will cause a special buffer, @samp{*Gnuplot Commands*}, to be displayed ++in another window. This buffer is a template of the commands that will ++be sent to GNUPLOT when it is time to draw the graph. The first ++@kbd{g a} command adds a @code{plot} command to this buffer. Succeeding ++@kbd{g a} commands add extra curves onto that @code{plot} command. ++Other graph-related commands put other GNUPLOT commands into this ++buffer. In normal usage you never need to work with this buffer ++directly, but you can if you wish. The only constraint is that there ++must be only one @code{plot} command, and it must be the last command ++in the buffer. If you want to save and later restore a complete graph ++configuration, you can use regular Emacs commands to save and restore ++the contents of the @samp{*Gnuplot Commands*} buffer. ++ ++@vindex PlotData1 ++@vindex PlotData2 ++If the values on the stack are not variable names, @kbd{g a} will invent ++variable names for them (of the form @samp{PlotData@var{n}}) and store ++the values in those variables. The ``x'' and ``y'' variables are what ++go into the @code{plot} command in the template. If you add a curve ++that uses a certain variable and then later change that variable, you ++can replot the graph without having to delete and re-add the curve. ++That's because the variable name, not the vector, interval or formula ++itself, is what was added by @kbd{g a}. ++ ++A numeric prefix argument on @kbd{g a} or @kbd{g f} changes the way ++stack entries are interpreted as curves. With a positive prefix ++argument @expr{n}, the top @expr{n} stack entries are ``y'' values ++for @expr{n} different curves which share a common ``x'' value in ++the @expr{n+1}st stack entry. (Thus @kbd{g a} with no prefix ++argument is equivalent to @kbd{C-u 1 g a}.) ++ ++A prefix of zero or plain @kbd{C-u} means to take two stack entries, ++``x'' and ``y'' as usual, but to interpret ``y'' as a vector of ++``y'' values for several curves that share a common ``x''. ++ ++A negative prefix argument tells Calc to read @expr{n} vectors from ++the stack; each vector @expr{[x, y]} describes an independent curve. ++This is the only form of @kbd{g a} that creates several curves at once ++that don't have common ``x'' values. (Of course, the range of ``x'' ++values covered by all the curves ought to be roughly the same if ++they are to look nice on the same graph.) ++ ++For example, to plot ++@texline @math{\sin n x} ++@infoline @expr{sin(n x)} ++for integers @expr{n} ++from 1 to 5, you could use @kbd{v x} to create a vector of integers ++(@expr{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)} ++across this vector. The resulting vector of formulas is suitable ++for use as the ``y'' argument to a @kbd{C-u g a} or @kbd{C-u g f} ++command. ++ ++@kindex g A ++@pindex calc-graph-add-3d ++The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve ++to the graph. It is not valid to intermix 2D and 3D curves in a ++single graph. This command takes three arguments, ``x'', ``y'', ++and ``z'', from the stack. With a positive prefix @expr{n}, it ++takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n} ++separate ``z''s). With a zero prefix, it takes three stack entries ++but the ``z'' entry is a vector of curve values. With a negative ++prefix @expr{-n}, it takes @expr{n} vectors of the form @expr{[x, y, z]}. ++The @kbd{g A} command works by adding a @code{splot} (surface-plot) ++command to the @samp{*Gnuplot Commands*} buffer. ++ ++(Although @kbd{g a} adds a 2D @code{plot} command to the ++@samp{*Gnuplot Commands*} buffer, Calc changes this to @code{splot} ++before sending it to GNUPLOT if it notices that the data points are ++evaluating to @code{xyz} calls. It will not work to mix 2D and 3D ++@kbd{g a} curves in a single graph, although Calc does not currently ++check for this.) ++ ++@kindex g d ++@pindex calc-graph-delete ++The @kbd{g d} (@code{calc-graph-delete}) command deletes the most ++recently added curve from the graph. It has no effect if there are ++no curves in the graph. With a numeric prefix argument of any kind, ++it deletes all of the curves from the graph. ++ ++@kindex g H ++@pindex calc-graph-hide ++The @kbd{g H} (@code{calc-graph-hide}) command ``hides'' or ``unhides'' ++the most recently added curve. A hidden curve will not appear in ++the actual plot, but information about it such as its name and line and ++point styles will be retained. ++ ++@kindex g j ++@pindex calc-graph-juggle ++The @kbd{g j} (@code{calc-graph-juggle}) command moves the curve ++at the end of the list (the ``most recently added curve'') to the ++front of the list. The next-most-recent curve is thus exposed for ++@w{@kbd{g d}} or similar commands to use. With @kbd{g j} you can work ++with any curve in the graph even though curve-related commands only ++affect the last curve in the list. ++ ++@kindex g p ++@pindex calc-graph-plot ++The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw ++the graph described in the @samp{*Gnuplot Commands*} buffer. Any ++GNUPLOT parameters which are not defined by commands in this buffer ++are reset to their default values. The variables named in the @code{plot} ++command are written to a temporary data file and the variable names ++are then replaced by the file name in the template. The resulting ++plotting commands are fed to the GNUPLOT program. See the documentation ++for the GNUPLOT program for more specific information. All temporary ++files are removed when Emacs or GNUPLOT exits. ++ ++If you give a formula for ``y'', Calc will remember all the values that ++it calculates for the formula so that later plots can reuse these values. ++Calc throws out these saved values when you change any circumstances ++that may affect the data, such as switching from Degrees to Radians ++mode, or changing the value of a parameter in the formula. You can ++force Calc to recompute the data from scratch by giving a negative ++numeric prefix argument to @kbd{g p}. ++ ++Calc uses a fairly rough step size when graphing formulas over intervals. ++This is to ensure quick response. You can ``refine'' a plot by giving ++a positive numeric prefix argument to @kbd{g p}. Calc goes through ++the data points it has computed and saved from previous plots of the ++function, and computes and inserts a new data point midway between ++each of the existing points. You can refine a plot any number of times, ++but beware that the amount of calculation involved doubles each time. ++ ++Calc does not remember computed values for 3D graphs. This means the ++numerix prefix argument, if any, to @kbd{g p} is effectively ignored if ++the current graph is three-dimensional. ++ ++@kindex g P ++@pindex calc-graph-print ++The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p}, ++except that it sends the output to a printer instead of to the ++screen. More precisely, @kbd{g p} looks for @samp{set terminal} ++or @samp{set output} commands in the @samp{*Gnuplot Commands*} buffer; ++lacking these it uses the default settings. However, @kbd{g P} ++ignores @samp{set terminal} and @samp{set output} commands and ++uses a different set of default values. All of these values are ++controlled by the @kbd{g D} and @kbd{g O} commands discussed below. ++Provided everything is set up properly, @kbd{g p} will plot to ++the screen unless you have specified otherwise and @kbd{g P} will ++always plot to the printer. ++ ++@node Graphics Options, Devices, Managing Curves, Graphics ++@section Graphics Options ++ ++@noindent ++@kindex g g ++@pindex calc-graph-grid ++The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid'' ++on and off. It is off by default; tick marks appear only at the ++edges of the graph. With the grid turned on, dotted lines appear ++across the graph at each tick mark. Note that this command only ++changes the setting in @samp{*Gnuplot Commands*}; to see the effects ++of the change you must give another @kbd{g p} command. ++ ++@kindex g b ++@pindex calc-graph-border ++The @kbd{g b} (@code{calc-graph-border}) command turns the border ++(the box that surrounds the graph) on and off. It is on by default. ++This command will only work with GNUPLOT 3.0 and later versions. ++ ++@kindex g k ++@pindex calc-graph-key ++The @kbd{g k} (@code{calc-graph-key}) command turns the ``key'' ++on and off. The key is a chart in the corner of the graph that ++shows the correspondence between curves and line styles. It is ++off by default, and is only really useful if you have several ++curves on the same graph. ++ ++@kindex g N ++@pindex calc-graph-num-points ++The @kbd{g N} (@code{calc-graph-num-points}) command allows you ++to select the number of data points in the graph. This only affects ++curves where neither ``x'' nor ``y'' is specified as a vector. ++Enter a blank line to revert to the default value (initially 15). ++With no prefix argument, this command affects only the current graph. ++With a positive prefix argument this command changes or, if you enter ++a blank line, displays the default number of points used for all ++graphs created by @kbd{g a} that don't specify the resolution explicitly. ++With a negative prefix argument, this command changes or displays ++the default value (initially 5) used for 3D graphs created by @kbd{g A}. ++Note that a 3D setting of 5 means that a total of @expr{5^2 = 25} points ++will be computed for the surface. ++ ++Data values in the graph of a function are normally computed to a ++precision of five digits, regardless of the current precision at the ++time. This is usually more than adequate, but there are cases where ++it will not be. For example, plotting @expr{1 + x} with @expr{x} in the ++interval @samp{[0 ..@: 1e-6]} will round all the data points down ++to 1.0! Putting the command @samp{set precision @var{n}} in the ++@samp{*Gnuplot Commands*} buffer will cause the data to be computed ++at precision @var{n} instead of 5. Since this is such a rare case, ++there is no keystroke-based command to set the precision. ++ ++@kindex g h ++@pindex calc-graph-header ++The @kbd{g h} (@code{calc-graph-header}) command sets the title ++for the graph. This will show up centered above the graph. ++The default title is blank (no title). ++ ++@kindex g n ++@pindex calc-graph-name ++The @kbd{g n} (@code{calc-graph-name}) command sets the title of an ++individual curve. Like the other curve-manipulating commands, it ++affects the most recently added curve, i.e., the last curve on the ++list in the @samp{*Gnuplot Commands*} buffer. To set the title of ++the other curves you must first juggle them to the end of the list ++with @kbd{g j}, or edit the @samp{*Gnuplot Commands*} buffer by hand. ++Curve titles appear in the key; if the key is turned off they are ++not used. ++ ++@kindex g t ++@kindex g T ++@pindex calc-graph-title-x ++@pindex calc-graph-title-y ++The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T} ++(@code{calc-graph-title-y}) commands set the titles on the ``x'' ++and ``y'' axes, respectively. These titles appear next to the ++tick marks on the left and bottom edges of the graph, respectively. ++Calc does not have commands to control the tick marks themselves, ++but you can edit them into the @samp{*Gnuplot Commands*} buffer if ++you wish. See the GNUPLOT documentation for details. ++ ++@kindex g r ++@kindex g R ++@pindex calc-graph-range-x ++@pindex calc-graph-range-y ++The @kbd{g r} (@code{calc-graph-range-x}) and @kbd{g R} ++(@code{calc-graph-range-y}) commands set the range of values on the ++``x'' and ``y'' axes, respectively. You are prompted to enter a ++suitable range. This should be either a pair of numbers of the ++form, @samp{@var{min}:@var{max}}, or a blank line to revert to the ++default behavior of setting the range based on the range of values ++in the data, or @samp{$} to take the range from the top of the stack. ++Ranges on the stack can be represented as either interval forms or ++vectors: @samp{[@var{min} ..@: @var{max}]} or @samp{[@var{min}, @var{max}]}. ++ ++@kindex g l ++@kindex g L ++@pindex calc-graph-log-x ++@pindex calc-graph-log-y ++The @kbd{g l} (@code{calc-graph-log-x}) and @kbd{g L} (@code{calc-graph-log-y}) ++commands allow you to set either or both of the axes of the graph to ++be logarithmic instead of linear. ++ ++@kindex g C-l ++@kindex g C-r ++@kindex g C-t ++@pindex calc-graph-log-z ++@pindex calc-graph-range-z ++@pindex calc-graph-title-z ++For 3D plots, @kbd{g C-t}, @kbd{g C-r}, and @kbd{g C-l} (those are ++letters with the Control key held down) are the corresponding commands ++for the ``z'' axis. ++ ++@kindex g z ++@kindex g Z ++@pindex calc-graph-zero-x ++@pindex calc-graph-zero-y ++The @kbd{g z} (@code{calc-graph-zero-x}) and @kbd{g Z} ++(@code{calc-graph-zero-y}) commands control whether a dotted line is ++drawn to indicate the ``x'' and/or ``y'' zero axes. (These are the same ++dotted lines that would be drawn there anyway if you used @kbd{g g} to ++turn the ``grid'' feature on.) Zero-axis lines are on by default, and ++may be turned off only in GNUPLOT 3.0 and later versions. They are ++not available for 3D plots. ++ ++@kindex g s ++@pindex calc-graph-line-style ++The @kbd{g s} (@code{calc-graph-line-style}) command turns the connecting ++lines on or off for the most recently added curve, and optionally selects ++the style of lines to be used for that curve. Plain @kbd{g s} simply ++toggles the lines on and off. With a numeric prefix argument, @kbd{g s} ++turns lines on and sets a particular line style. Line style numbers ++start at one and their meanings vary depending on the output device. ++GNUPLOT guarantees that there will be at least six different line styles ++available for any device. ++ ++@kindex g S ++@pindex calc-graph-point-style ++The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns ++the symbols at the data points on or off, or sets the point style. ++If you turn both lines and points off, the data points will show as ++tiny dots. If the ``y'' values being plotted contain error forms and ++the connecting lines are turned off, then this command will also turn ++the error bars on or off. ++ ++@cindex @code{LineStyles} variable ++@cindex @code{PointStyles} variable ++@vindex LineStyles ++@vindex PointStyles ++Another way to specify curve styles is with the @code{LineStyles} and ++@code{PointStyles} variables. These variables initially have no stored ++values, but if you store a vector of integers in one of these variables, ++the @kbd{g a} and @kbd{g f} commands will use those style numbers ++instead of the defaults for new curves that are added to the graph. ++An entry should be a positive integer for a specific style, or 0 to let ++the style be chosen automatically, or @mathit{-1} to turn off lines or points ++altogether. If there are more curves than elements in the vector, the ++last few curves will continue to have the default styles. Of course, ++you can later use @kbd{g s} and @kbd{g S} to change any of these styles. ++ ++For example, @kbd{'[2 -1 3] @key{RET} s t LineStyles} causes the first curve ++to have lines in style number 2, the second curve to have no connecting ++lines, and the third curve to have lines in style 3. Point styles will ++still be assigned automatically, but you could store another vector in ++@code{PointStyles} to define them, too. ++ ++@node Devices, , Graphics Options, Graphics ++@section Graphical Devices ++ ++@noindent ++@kindex g D ++@pindex calc-graph-device ++The @kbd{g D} (@code{calc-graph-device}) command sets the device name ++(or ``terminal name'' in GNUPLOT lingo) to be used by @kbd{g p} commands ++on this graph. It does not affect the permanent default device name. ++If you enter a blank name, the device name reverts to the default. ++Enter @samp{?} to see a list of supported devices. ++ ++With a positive numeric prefix argument, @kbd{g D} instead sets ++the default device name, used by all plots in the future which do ++not override it with a plain @kbd{g D} command. If you enter a ++blank line this command shows you the current default. The special ++name @code{default} signifies that Calc should choose @code{x11} if ++the X window system is in use (as indicated by the presence of a ++@code{DISPLAY} environment variable), or otherwise @code{dumb} under ++GNUPLOT 3.0 and later, or @code{postscript} under GNUPLOT 2.0. ++This is the initial default value. ++ ++The @code{dumb} device is an interface to ``dumb terminals,'' i.e., ++terminals with no special graphics facilities. It writes a crude ++picture of the graph composed of characters like @code{-} and @code{|} ++to a buffer called @samp{*Gnuplot Trail*}, which Calc then displays. ++The graph is made the same size as the Emacs screen, which on most ++dumb terminals will be ++@texline @math{80\times24} ++@infoline 80x24 ++characters. The graph is displayed in ++an Emacs ``recursive edit''; type @kbd{q} or @kbd{C-c C-c} to exit ++the recursive edit and return to Calc. Note that the @code{dumb} ++device is present only in GNUPLOT 3.0 and later versions. ++ ++The word @code{dumb} may be followed by two numbers separated by ++spaces. These are the desired width and height of the graph in ++characters. Also, the device name @code{big} is like @code{dumb} ++but creates a graph four times the width and height of the Emacs ++screen. You will then have to scroll around to view the entire ++graph. In the @samp{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL}, ++@kbd{<}, and @kbd{>} are defined to scroll by one screenful in each ++of the four directions. ++ ++With a negative numeric prefix argument, @kbd{g D} sets or displays ++the device name used by @kbd{g P} (@code{calc-graph-print}). This ++is initially @code{postscript}. If you don't have a PostScript ++printer, you may decide once again to use @code{dumb} to create a ++plot on any text-only printer. ++ ++@kindex g O ++@pindex calc-graph-output ++The @kbd{g O} (@code{calc-graph-output}) command sets the name of ++the output file used by GNUPLOT. For some devices, notably @code{x11}, ++there is no output file and this information is not used. Many other ++``devices'' are really file formats like @code{postscript}; in these ++cases the output in the desired format goes into the file you name ++with @kbd{g O}. Type @kbd{g O stdout @key{RET}} to set GNUPLOT to write ++to its standard output stream, i.e., to @samp{*Gnuplot Trail*}. ++This is the default setting. ++ ++Another special output name is @code{tty}, which means that GNUPLOT ++is going to write graphics commands directly to its standard output, ++which you wish Emacs to pass through to your terminal. Tektronix ++graphics terminals, among other devices, operate this way. Calc does ++this by telling GNUPLOT to write to a temporary file, then running a ++sub-shell executing the command @samp{cat tempfile >/dev/tty}. On ++typical Unix systems, this will copy the temporary file directly to ++the terminal, bypassing Emacs entirely. You will have to type @kbd{C-l} ++to Emacs afterwards to refresh the screen. ++ ++Once again, @kbd{g O} with a positive or negative prefix argument ++sets the default or printer output file names, respectively. In each ++case you can specify @code{auto}, which causes Calc to invent a temporary ++file name for each @kbd{g p} (or @kbd{g P}) command. This temporary file ++will be deleted once it has been displayed or printed. If the output file ++name is not @code{auto}, the file is not automatically deleted. ++ ++The default and printer devices and output files can be saved ++permanently by the @kbd{m m} (@code{calc-save-modes}) command. The ++default number of data points (see @kbd{g N}) and the X geometry ++(see @kbd{g X}) are also saved. Other graph information is @emph{not} ++saved; you can save a graph's configuration simply by saving the contents ++of the @samp{*Gnuplot Commands*} buffer. ++ ++@vindex calc-gnuplot-plot-command ++@vindex calc-gnuplot-default-device ++@vindex calc-gnuplot-default-output ++@vindex calc-gnuplot-print-command ++@vindex calc-gnuplot-print-device ++@vindex calc-gnuplot-print-output ++You may wish to configure the default and ++printer devices and output files for the whole system. The relevant ++Lisp variables are @code{calc-gnuplot-default-device} and @code{-output}, ++and @code{calc-gnuplot-print-device} and @code{-output}. The output ++file names must be either strings as described above, or Lisp ++expressions which are evaluated on the fly to get the output file names. ++ ++Other important Lisp variables are @code{calc-gnuplot-plot-command} and ++@code{calc-gnuplot-print-command}, which give the system commands to ++display or print the output of GNUPLOT, respectively. These may be ++@code{nil} if no command is necessary, or strings which can include ++@samp{%s} to signify the name of the file to be displayed or printed. ++Or, these variables may contain Lisp expressions which are evaluated ++to display or print the output. These variables are customizable ++(@pxref{Customizing Calc}). ++ ++@kindex g x ++@pindex calc-graph-display ++The @kbd{g x} (@code{calc-graph-display}) command lets you specify ++on which X window system display your graphs should be drawn. Enter ++a blank line to see the current display name. This command has no ++effect unless the current device is @code{x11}. ++ ++@kindex g X ++@pindex calc-graph-geometry ++The @kbd{g X} (@code{calc-graph-geometry}) command is a similar ++command for specifying the position and size of the X window. ++The normal value is @code{default}, which generally means your ++window manager will let you place the window interactively. ++Entering @samp{800x500+0+0} would create an 800-by-500 pixel ++window in the upper-left corner of the screen. ++ ++The buffer called @samp{*Gnuplot Trail*} holds a transcript of the ++session with GNUPLOT. This shows the commands Calc has ``typed'' to ++GNUPLOT and the responses it has received. Calc tries to notice when an ++error message has appeared here and display the buffer for you when ++this happens. You can check this buffer yourself if you suspect ++something has gone wrong. ++ ++@kindex g C ++@pindex calc-graph-command ++The @kbd{g C} (@code{calc-graph-command}) command prompts you to ++enter any line of text, then simply sends that line to the current ++GNUPLOT process. The @samp{*Gnuplot Trail*} buffer looks deceptively ++like a Shell buffer but you can't type commands in it yourself. ++Instead, you must use @kbd{g C} for this purpose. ++ ++@kindex g v ++@kindex g V ++@pindex calc-graph-view-commands ++@pindex calc-graph-view-trail ++The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V} ++(@code{calc-graph-view-trail}) commands display the @samp{*Gnuplot Commands*} ++and @samp{*Gnuplot Trail*} buffers, respectively, in another window. ++This happens automatically when Calc thinks there is something you ++will want to see in either of these buffers. If you type @kbd{g v} ++or @kbd{g V} when the relevant buffer is already displayed, the ++buffer is hidden again. ++ ++One reason to use @kbd{g v} is to add your own commands to the ++@samp{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use ++@kbd{C-x o} to switch into that window. For example, GNUPLOT has ++@samp{set label} and @samp{set arrow} commands that allow you to ++annotate your plots. Since Calc doesn't understand these commands, ++you have to add them to the @samp{*Gnuplot Commands*} buffer ++yourself, then use @w{@kbd{g p}} to replot using these new commands. Note ++that your commands must appear @emph{before} the @code{plot} command. ++To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}. ++You may have to type @kbd{g C @key{RET}} a few times to clear the ++``press return for more'' or ``subtopic of @dots{}'' requests. ++Note that Calc always sends commands (like @samp{set nolabel}) to ++reset all plotting parameters to the defaults before each plot, so ++to delete a label all you need to do is delete the @samp{set label} ++line you added (or comment it out with @samp{#}) and then replot ++with @kbd{g p}. ++ ++@kindex g q ++@pindex calc-graph-quit ++You can use @kbd{g q} (@code{calc-graph-quit}) to kill the GNUPLOT ++process that is running. The next graphing command you give will ++start a fresh GNUPLOT process. The word @samp{Graph} appears in ++the Calc window's mode line whenever a GNUPLOT process is currently ++running. The GNUPLOT process is automatically killed when you ++exit Emacs if you haven't killed it manually by then. ++ ++@kindex g K ++@pindex calc-graph-kill ++The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q} ++except that it also views the @samp{*Gnuplot Trail*} buffer so that ++you can see the process being killed. This is better if you are ++killing GNUPLOT because you think it has gotten stuck. ++ ++@node Kill and Yank, Keypad Mode, Graphics, Top ++@chapter Kill and Yank Functions ++ ++@noindent ++The commands in this chapter move information between the Calculator and ++other Emacs editing buffers. ++ ++In many cases Embedded mode is an easier and more natural way to ++work with Calc from a regular editing buffer. @xref{Embedded Mode}. ++ ++@menu ++* Killing From Stack:: ++* Yanking Into Stack:: ++* Saving Into Registers:: ++* Inserting From Registers:: ++* Grabbing From Buffers:: ++* Yanking Into Buffers:: ++* X Cut and Paste:: ++@end menu ++ ++@node Killing From Stack, Yanking Into Stack, Kill and Yank, Kill and Yank ++@section Killing from the Stack ++ ++@noindent ++@kindex C-k ++@pindex calc-kill ++@kindex M-k ++@pindex calc-copy-as-kill ++@kindex C-w ++@pindex calc-kill-region ++@kindex M-w ++@pindex calc-copy-region-as-kill ++@kindex M-C-w ++@cindex Kill ring ++@dfn{Kill} commands are Emacs commands that insert text into the ``kill ++ring,'' from which it can later be ``yanked'' by a @kbd{C-y} command. ++Three common kill commands in normal Emacs are @kbd{C-k}, which kills ++one line, @kbd{C-w}, which kills the region between mark and point, and ++@kbd{M-w}, which puts the region into the kill ring without actually ++deleting it. All of these commands work in the Calculator, too, ++although in the Calculator they operate on whole stack entries, so they ++``round up'' the specified region to encompass full lines. (To copy ++only parts of lines, the @kbd{M-C-w} command in the Calculator will copy ++the region to the kill ring without any ``rounding up'', just like the ++@kbd{M-w} command in normal Emacs.) Also, @kbd{M-k} has been provided ++to complete the set; it puts the current line into the kill ring without ++deleting anything. ++ ++The kill commands are unusual in that they pay attention to the location ++of the cursor in the Calculator buffer. If the cursor is on or below ++the bottom line, the kill commands operate on the top of the stack. ++Otherwise, they operate on whatever stack element the cursor is on. The ++text is copied into the kill ring exactly as it appears on the screen, ++including line numbers if they are enabled. ++ ++A numeric prefix argument to @kbd{C-k} or @kbd{M-k} affects the number ++of lines killed. A positive argument kills the current line and @expr{n-1} ++lines below it. A negative argument kills the @expr{-n} lines above the ++current line. Again this mirrors the behavior of the standard Emacs ++@kbd{C-k} command. Although a whole line is always deleted, @kbd{C-k} ++with no argument copies only the number itself into the kill ring, whereas ++@kbd{C-k} with a prefix argument of 1 copies the number with its trailing ++newline. ++ ++@node Yanking Into Stack, Saving Into Registers, Killing From Stack, Kill and Yank ++@section Yanking into the Stack ++ ++@noindent ++@kindex C-y ++@pindex calc-yank ++The @kbd{C-y} command yanks the most recently killed text back into the ++Calculator. It pushes this value onto the top of the stack regardless of ++the cursor position. In general it re-parses the killed text as a number ++or formula (or a list of these separated by commas or newlines). However if ++the thing being yanked is something that was just killed from the Calculator ++itself, its full internal structure is yanked. For example, if you have ++set the floating-point display mode to show only four significant digits, ++then killing and re-yanking 3.14159 (which displays as 3.142) will yank the ++full 3.14159, even though yanking it into any other buffer would yank the ++number in its displayed form, 3.142. (Since the default display modes ++show all objects to their full precision, this feature normally makes no ++difference.) ++ ++@node Saving Into Registers, Inserting From Registers, Yanking Into Stack, Kill and Yank ++@section Saving into Registers ++ ++@noindent ++@kindex r s ++@pindex calc-copy-to-register ++@pindex calc-prepend-to-register ++@pindex calc-append-to-register ++@cindex Registers ++An alternative to killing and yanking stack entries is using ++registers in Calc. Saving stack entries in registers is like ++saving text in normal Emacs registers; although, like Calc's kill ++commands, register commands always operate on whole stack ++entries. ++ ++Registers in Calc are places to store stack entries for later use; ++each register is indexed by a single character. To store the current ++region (rounded up, of course, to include full stack entries) into a ++register, use the command @kbd{r s} (@code{calc-copy-to-register}). ++You will then be prompted for a register to use, the next character ++you type will be the index for the register. To store the region in ++register @var{r}, the full command will be @kbd{r s @var{r}}. With an ++argument, @kbd{C-u r s @var{r}}, the region being copied to the ++register will be deleted from the Calc buffer. ++ ++It is possible to add additional stack entries to a register. The ++command @kbd{M-x calc-append-to-register} will prompt for a register, ++then add the stack entries in the region to the end of the register ++contents. The command @kbd{M-x calc-prepend-to-register} will ++similarly prompt for a register and add the stack entries in the ++region to the beginning of the register contents. Both commands take ++@kbd{C-u} arguments, which will cause the region to be deleted after being ++added to the register. ++ ++@node Inserting From Registers, Grabbing From Buffers, Saving Into Registers, Kill and Yank ++@section Inserting from Registers ++@noindent ++@kindex r i ++@pindex calc-insert-register ++The command @kbd{r i} (@code{calc-insert-register}) will prompt for a ++register, then insert the contents of that register into the ++Calculator. If the contents of the register were placed there from ++within Calc, then the full internal structure of the contents will be ++inserted into the Calculator, otherwise whatever text is in the ++register is reparsed and then inserted into the Calculator. ++ ++@node Grabbing From Buffers, Yanking Into Buffers, Inserting From Registers, Kill and Yank ++@section Grabbing from Other Buffers ++ ++@noindent ++@kindex C-x * g ++@pindex calc-grab-region ++The @kbd{C-x * g} (@code{calc-grab-region}) command takes the text between ++point and mark in the current buffer and attempts to parse it as a ++vector of values. Basically, it wraps the text in vector brackets ++@samp{[ ]} unless the text already is enclosed in vector brackets, ++then reads the text as if it were an algebraic entry. The contents ++of the vector may be numbers, formulas, or any other Calc objects. ++If the @kbd{C-x * g} command works successfully, it does an automatic ++@kbd{C-x * c} to enter the Calculator buffer. ++ ++A numeric prefix argument grabs the specified number of lines around ++point, ignoring the mark. A positive prefix grabs from point to the ++@expr{n}th following newline (so that @kbd{M-1 C-x * g} grabs from point ++to the end of the current line); a negative prefix grabs from point ++back to the @expr{n+1}st preceding newline. In these cases the text ++that is grabbed is exactly the same as the text that @kbd{C-k} would ++delete given that prefix argument. ++ ++A prefix of zero grabs the current line; point may be anywhere on the ++line. ++ ++A plain @kbd{C-u} prefix interprets the region between point and mark ++as a single number or formula rather than a vector. For example, ++@kbd{C-x * g} on the text @samp{2 a b} produces the vector of three ++values @samp{[2, a, b]}, but @kbd{C-u C-x * g} on the same region ++reads a formula which is a product of three things: @samp{2 a b}. ++(The text @samp{a + b}, on the other hand, will be grabbed as a ++vector of one element by plain @kbd{C-x * g} because the interpretation ++@samp{[a, +, b]} would be a syntax error.) ++ ++If a different language has been specified (@pxref{Language Modes}), ++the grabbed text will be interpreted according to that language. ++ ++@kindex C-x * r ++@pindex calc-grab-rectangle ++The @kbd{C-x * r} (@code{calc-grab-rectangle}) command takes the text between ++point and mark and attempts to parse it as a matrix. If point and mark ++are both in the leftmost column, the lines in between are parsed in their ++entirety. Otherwise, point and mark define the corners of a rectangle ++whose contents are parsed. ++ ++Each line of the grabbed area becomes a row of the matrix. The result ++will actually be a vector of vectors, which Calc will treat as a matrix ++only if every row contains the same number of values. ++ ++If a line contains a portion surrounded by square brackets (or curly ++braces), that portion is interpreted as a vector which becomes a row ++of the matrix. Any text surrounding the bracketed portion on the line ++is ignored. ++ ++Otherwise, the entire line is interpreted as a row vector as if it ++were surrounded by square brackets. Leading line numbers (in the ++format used in the Calc stack buffer) are ignored. If you wish to ++force this interpretation (even if the line contains bracketed ++portions), give a negative numeric prefix argument to the ++@kbd{C-x * r} command. ++ ++If you give a numeric prefix argument of zero or plain @kbd{C-u}, each ++line is instead interpreted as a single formula which is converted into ++a one-element vector. Thus the result of @kbd{C-u C-x * r} will be a ++one-column matrix. For example, suppose one line of the data is the ++expression @samp{2 a}. A plain @w{@kbd{C-x * r}} will interpret this as ++@samp{[2 a]}, which in turn is read as a two-element vector that forms ++one row of the matrix. But a @kbd{C-u C-x * r} will interpret this row ++as @samp{[2*a]}. ++ ++If you give a positive numeric prefix argument @var{n}, then each line ++will be split up into columns of width @var{n}; each column is parsed ++separately as a matrix element. If a line contained ++@w{@samp{2 +/- 3 4 +/- 5}}, then grabbing with a prefix argument of 8 ++would correctly split the line into two error forms. ++ ++@xref{Matrix Functions}, to see how to pull the matrix apart into its ++constituent rows and columns. (If it is a ++@texline @math{1\times1} ++@infoline 1x1 ++matrix, just hit @kbd{v u} (@code{calc-unpack}) twice.) ++ ++@kindex C-x * : ++@kindex C-x * _ ++@pindex calc-grab-sum-across ++@pindex calc-grab-sum-down ++@cindex Summing rows and columns of data ++The @kbd{C-x * :} (@code{calc-grab-sum-down}) command is a handy way to ++grab a rectangle of data and sum its columns. It is equivalent to ++typing @kbd{C-x * r}, followed by @kbd{V R : +} (the vector reduction ++command that sums the columns of a matrix; @pxref{Reducing}). The ++result of the command will be a vector of numbers, one for each column ++in the input data. The @kbd{C-x * _} (@code{calc-grab-sum-across}) command ++similarly grabs a rectangle and sums its rows by executing @w{@kbd{V R _ +}}. ++ ++As well as being more convenient, @kbd{C-x * :} and @kbd{C-x * _} are also ++much faster because they don't actually place the grabbed vector on ++the stack. In a @kbd{C-x * r V R : +} sequence, formatting the vector ++for display on the stack takes a large fraction of the total time ++(unless you have planned ahead and used @kbd{v .} and @kbd{t .} modes). ++ ++For example, suppose we have a column of numbers in a file which we ++wish to sum. Go to one corner of the column and press @kbd{C-@@} to ++set the mark; go to the other corner and type @kbd{C-x * :}. Since there ++is only one column, the result will be a vector of one number, the sum. ++(You can type @kbd{v u} to unpack this vector into a plain number if ++you want to do further arithmetic with it.) ++ ++To compute the product of the column of numbers, we would have to do ++it ``by hand'' since there's no special grab-and-multiply command. ++Use @kbd{C-x * r} to grab the column of numbers into the calculator in ++the form of a column matrix. The statistics command @kbd{u *} is a ++handy way to find the product of a vector or matrix of numbers. ++@xref{Statistical Operations}. Another approach would be to use ++an explicit column reduction command, @kbd{V R : *}. ++ ++@node Yanking Into Buffers, X Cut and Paste, Grabbing From Buffers, Kill and Yank ++@section Yanking into Other Buffers ++ ++@noindent ++@kindex y ++@pindex calc-copy-to-buffer ++The plain @kbd{y} (@code{calc-copy-to-buffer}) command inserts the number ++at the top of the stack into the most recently used normal editing buffer. ++(More specifically, this is the most recently used buffer which is displayed ++in a window and whose name does not begin with @samp{*}. If there is no ++such buffer, this is the most recently used buffer except for Calculator ++and Calc Trail buffers.) The number is inserted exactly as it appears and ++without a newline. (If line-numbering is enabled, the line number is ++normally not included.) The number is @emph{not} removed from the stack. ++ ++With a prefix argument, @kbd{y} inserts several numbers, one per line. ++A positive argument inserts the specified number of values from the top ++of the stack. A negative argument inserts the @expr{n}th value from the ++top of the stack. An argument of zero inserts the entire stack. Note ++that @kbd{y} with an argument of 1 is slightly different from @kbd{y} ++with no argument; the former always copies full lines, whereas the ++latter strips off the trailing newline. ++ ++With a lone @kbd{C-u} as a prefix argument, @kbd{y} @emph{replaces} the ++region in the other buffer with the yanked text, then quits the ++Calculator, leaving you in that buffer. A typical use would be to use ++@kbd{C-x * g} to read a region of data into the Calculator, operate on the ++data to produce a new matrix, then type @kbd{C-u y} to replace the ++original data with the new data. One might wish to alter the matrix ++display style (@pxref{Vector and Matrix Formats}) or change the current ++display language (@pxref{Language Modes}) before doing this. Also, note ++that this command replaces a linear region of text (as grabbed by ++@kbd{C-x * g}), not a rectangle (as grabbed by @kbd{C-x * r}). ++ ++If the editing buffer is in overwrite (as opposed to insert) mode, ++and the @kbd{C-u} prefix was not used, then the yanked number will ++overwrite the characters following point rather than being inserted ++before those characters. The usual conventions of overwrite mode ++are observed; for example, characters will be inserted at the end of ++a line rather than overflowing onto the next line. Yanking a multi-line ++object such as a matrix in overwrite mode overwrites the next @var{n} ++lines in the buffer, lengthening or shortening each line as necessary. ++Finally, if the thing being yanked is a simple integer or floating-point ++number (like @samp{-1.2345e-3}) and the characters following point also ++make up such a number, then Calc will replace that number with the new ++number, lengthening or shortening as necessary. The concept of ++``overwrite mode'' has thus been generalized from overwriting characters ++to overwriting one complete number with another. ++ ++@kindex C-x * y ++The @kbd{C-x * y} key sequence is equivalent to @kbd{y} except that ++it can be typed anywhere, not just in Calc. This provides an easy ++way to guarantee that Calc knows which editing buffer you want to use! ++ ++@node X Cut and Paste, , Yanking Into Buffers, Kill and Yank ++@section X Cut and Paste ++ ++@noindent ++If you are using Emacs with the X window system, there is an easier ++way to move small amounts of data into and out of the calculator: ++Use the mouse-oriented cut and paste facilities of X. ++ ++The default bindings for a three-button mouse cause the left button ++to move the Emacs cursor to the given place, the right button to ++select the text between the cursor and the clicked location, and ++the middle button to yank the selection into the buffer at the ++clicked location. So, if you have a Calc window and an editing ++window on your Emacs screen, you can use left-click/right-click ++to select a number, vector, or formula from one window, then ++middle-click to paste that value into the other window. When you ++paste text into the Calc window, Calc interprets it as an algebraic ++entry. It doesn't matter where you click in the Calc window; the ++new value is always pushed onto the top of the stack. ++ ++The @code{xterm} program that is typically used for general-purpose ++shell windows in X interprets the mouse buttons in the same way. ++So you can use the mouse to move data between Calc and any other ++Unix program. One nice feature of @code{xterm} is that a double ++left-click selects one word, and a triple left-click selects a ++whole line. So you can usually transfer a single number into Calc ++just by double-clicking on it in the shell, then middle-clicking ++in the Calc window. ++ ++@node Keypad Mode, Embedded Mode, Kill and Yank, Top ++@chapter Keypad Mode ++ ++@noindent ++@kindex C-x * k ++@pindex calc-keypad ++The @kbd{C-x * k} (@code{calc-keypad}) command starts the Calculator ++and displays a picture of a calculator-style keypad. If you are using ++the X window system, you can click on any of the ``keys'' in the ++keypad using the left mouse button to operate the calculator. ++The original window remains the selected window; in Keypad mode ++you can type in your file while simultaneously performing ++calculations with the mouse. ++ ++@pindex full-calc-keypad ++If you have used @kbd{C-x * b} first, @kbd{C-x * k} instead invokes ++the @code{full-calc-keypad} command, which takes over the whole ++Emacs screen and displays the keypad, the Calc stack, and the Calc ++trail all at once. This mode would normally be used when running ++Calc standalone (@pxref{Standalone Operation}). ++ ++If you aren't using the X window system, you must switch into ++the @samp{*Calc Keypad*} window, place the cursor on the desired ++``key,'' and type @key{SPC} or @key{RET}. If you think this ++is easier than using Calc normally, go right ahead. ++ ++Calc commands are more or less the same in Keypad mode. Certain ++keypad keys differ slightly from the corresponding normal Calc ++keystrokes; all such deviations are described below. ++ ++Keypad mode includes many more commands than will fit on the keypad ++at once. Click the right mouse button [@code{calc-keypad-menu}] ++to switch to the next menu. The bottom five rows of the keypad ++stay the same; the top three rows change to a new set of commands. ++To return to earlier menus, click the middle mouse button ++[@code{calc-keypad-menu-back}] or simply advance through the menus ++until you wrap around. Typing @key{TAB} inside the keypad window ++is equivalent to clicking the right mouse button there. ++ ++You can always click the @key{EXEC} button and type any normal ++Calc key sequence. This is equivalent to switching into the ++Calc buffer, typing the keys, then switching back to your ++original buffer. ++ ++@menu ++* Keypad Main Menu:: ++* Keypad Functions Menu:: ++* Keypad Binary Menu:: ++* Keypad Vectors Menu:: ++* Keypad Modes Menu:: ++@end menu ++ ++@node Keypad Main Menu, Keypad Functions Menu, Keypad Mode, Keypad Mode ++@section Main Menu ++ ++@smallexample ++@group ++|----+----+--Calc---+----+----1 ++|FLR |CEIL|RND |TRNC|CLN2|FLT | ++|----+----+----+----+----+----| ++| LN |EXP | |ABS |IDIV|MOD | ++|----+----+----+----+----+----| ++|SIN |COS |TAN |SQRT|y^x |1/x | ++|----+----+----+----+----+----| ++| ENTER |+/- |EEX |UNDO| <- | ++|-----+---+-+--+--+-+---++----| ++| INV | 7 | 8 | 9 | / | ++|-----+-----+-----+-----+-----| ++| HYP | 4 | 5 | 6 | * | ++|-----+-----+-----+-----+-----| ++|EXEC | 1 | 2 | 3 | - | ++|-----+-----+-----+-----+-----| ++| OFF | 0 | . | PI | + | ++|-----+-----+-----+-----+-----+ ++@end group ++@end smallexample ++ ++@noindent ++This is the menu that appears the first time you start Keypad mode. ++It will show up in a vertical window on the right side of your screen. ++Above this menu is the traditional Calc stack display. On a 24-line ++screen you will be able to see the top three stack entries. ++ ++The ten digit keys, decimal point, and @key{EEX} key are used for ++entering numbers in the obvious way. @key{EEX} begins entry of an ++exponent in scientific notation. Just as with regular Calc, the ++number is pushed onto the stack as soon as you press @key{ENTER} ++or any other function key. ++ ++The @key{+/-} key corresponds to normal Calc's @kbd{n} key. During ++numeric entry it changes the sign of the number or of the exponent. ++At other times it changes the sign of the number on the top of the ++stack. ++ ++The @key{INV} and @key{HYP} keys modify other keys. As well as ++having the effects described elsewhere in this manual, Keypad mode ++defines several other ``inverse'' operations. These are described ++below and in the following sections. ++ ++The @key{ENTER} key finishes the current numeric entry, or otherwise ++duplicates the top entry on the stack. ++ ++The @key{UNDO} key undoes the most recent Calc operation. ++@kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is ++``last arguments'' (@kbd{M-@key{RET}}). ++ ++The @key{<-} key acts as a ``backspace'' during numeric entry. ++At other times it removes the top stack entry. @kbd{INV <-} ++clears the entire stack. @kbd{HYP <-} takes an integer from ++the stack, then removes that many additional stack elements. ++ ++The @key{EXEC} key prompts you to enter any keystroke sequence ++that would normally work in Calc mode. This can include a ++numeric prefix if you wish. It is also possible simply to ++switch into the Calc window and type commands in it; there is ++nothing ``magic'' about this window when Keypad mode is active. ++ ++The other keys in this display perform their obvious calculator ++functions. @key{CLN2} rounds the top-of-stack by temporarily ++reducing the precision by 2 digits. @key{FLT} converts an ++integer or fraction on the top of the stack to floating-point. ++ ++The @key{INV} and @key{HYP} keys combined with several of these keys ++give you access to some common functions even if the appropriate menu ++is not displayed. Obviously you don't need to learn these keys ++unless you find yourself wasting time switching among the menus. ++ ++@table @kbd ++@item INV +/- ++is the same as @key{1/x}. ++@item INV + ++is the same as @key{SQRT}. ++@item INV - ++is the same as @key{CONJ}. ++@item INV * ++is the same as @key{y^x}. ++@item INV / ++is the same as @key{INV y^x} (the @expr{x}th root of @expr{y}). ++@item HYP/INV 1 ++are the same as @key{SIN} / @kbd{INV SIN}. ++@item HYP/INV 2 ++are the same as @key{COS} / @kbd{INV COS}. ++@item HYP/INV 3 ++are the same as @key{TAN} / @kbd{INV TAN}. ++@item INV/HYP 4 ++are the same as @key{LN} / @kbd{HYP LN}. ++@item INV/HYP 5 ++are the same as @key{EXP} / @kbd{HYP EXP}. ++@item INV 6 ++is the same as @key{ABS}. ++@item INV 7 ++is the same as @key{RND} (@code{calc-round}). ++@item INV 8 ++is the same as @key{CLN2}. ++@item INV 9 ++is the same as @key{FLT} (@code{calc-float}). ++@item INV 0 ++is the same as @key{IMAG}. ++@item INV . ++is the same as @key{PREC}. ++@item INV ENTER ++is the same as @key{SWAP}. ++@item HYP ENTER ++is the same as @key{RLL3}. ++@item INV HYP ENTER ++is the same as @key{OVER}. ++@item HYP +/- ++packs the top two stack entries as an error form. ++@item HYP EEX ++packs the top two stack entries as a modulo form. ++@item INV EEX ++creates an interval form; this removes an integer which is one ++of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed ++by the two limits of the interval. ++@end table ++ ++The @kbd{OFF} key turns Calc off; typing @kbd{C-x * k} or @kbd{C-x * *} ++again has the same effect. This is analogous to typing @kbd{q} or ++hitting @kbd{C-x * c} again in the normal calculator. If Calc is ++running standalone (the @code{full-calc-keypad} command appeared in the ++command line that started Emacs), then @kbd{OFF} is replaced with ++@kbd{EXIT}; clicking on this actually exits Emacs itself. ++ ++@node Keypad Functions Menu, Keypad Binary Menu, Keypad Main Menu, Keypad Mode ++@section Functions Menu ++ ++@smallexample ++@group ++|----+----+----+----+----+----2 ++|IGAM|BETA|IBET|ERF |BESJ|BESY| ++|----+----+----+----+----+----| ++|IMAG|CONJ| RE |ATN2|RAND|RAGN| ++|----+----+----+----+----+----| ++|GCD |FACT|DFCT|BNOM|PERM|NXTP| ++|----+----+----+----+----+----| ++@end group ++@end smallexample ++ ++@noindent ++This menu provides various operations from the @kbd{f} and @kbd{k} ++prefix keys. ++ ++@key{IMAG} multiplies the number on the stack by the imaginary ++number @expr{i = (0, 1)}. ++ ++@key{RE} extracts the real part a complex number. @kbd{INV RE} ++extracts the imaginary part. ++ ++@key{RAND} takes a number from the top of the stack and computes ++a random number greater than or equal to zero but less than that ++number. (@xref{Random Numbers}.) @key{RAGN} is the ``random ++again'' command; it computes another random number using the ++same limit as last time. ++ ++@key{INV GCD} computes the LCM (least common multiple) function. ++ ++@key{INV FACT} is the gamma function. ++@texline @math{\Gamma(x) = (x-1)!}. ++@infoline @expr{gamma(x) = (x-1)!}. ++ ++@key{PERM} is the number-of-permutations function, which is on the ++@kbd{H k c} key in normal Calc. ++ ++@key{NXTP} finds the next prime after a number. @kbd{INV NXTP} ++finds the previous prime. ++ ++@node Keypad Binary Menu, Keypad Vectors Menu, Keypad Functions Menu, Keypad Mode ++@section Binary Menu ++ ++@smallexample ++@group ++|----+----+----+----+----+----3 ++|AND | OR |XOR |NOT |LSH |RSH | ++|----+----+----+----+----+----| ++|DEC |HEX |OCT |BIN |WSIZ|ARSH| ++|----+----+----+----+----+----| ++| A | B | C | D | E | F | ++|----+----+----+----+----+----| ++@end group ++@end smallexample ++ ++@noindent ++The keys in this menu perform operations on binary integers. ++Note that both logical and arithmetic right-shifts are provided. ++@key{INV LSH} rotates one bit to the left. ++ ++The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}. ++The ``clip'' function (normally on @w{@kbd{b c}}) is on @key{INV NOT}. ++ ++The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the ++current radix for display and entry of numbers: Decimal, hexadecimal, ++octal, or binary. The six letter keys @key{A} through @key{F} are used ++for entering hexadecimal numbers. ++ ++The @key{WSIZ} key displays the current word size for binary operations ++and allows you to enter a new word size. You can respond to the prompt ++using either the keyboard or the digits and @key{ENTER} from the keypad. ++The initial word size is 32 bits. ++ ++@node Keypad Vectors Menu, Keypad Modes Menu, Keypad Binary Menu, Keypad Mode ++@section Vectors Menu ++ ++@smallexample ++@group ++|----+----+----+----+----+----4 ++|SUM |PROD|MAX |MAP*|MAP^|MAP$| ++|----+----+----+----+----+----| ++|MINV|MDET|MTRN|IDNT|CRSS|"x" | ++|----+----+----+----+----+----| ++|PACK|UNPK|INDX|BLD |LEN |... | ++|----+----+----+----+----+----| ++@end group ++@end smallexample ++ ++@noindent ++The keys in this menu operate on vectors and matrices. ++ ++@key{PACK} removes an integer @var{n} from the top of the stack; ++the next @var{n} stack elements are removed and packed into a vector, ++which is replaced onto the stack. Thus the sequence ++@kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector ++@samp{[1, 3, 5]} onto the stack. To enter a matrix, build each row ++on the stack as a vector, then use a final @key{PACK} to collect the ++rows into a matrix. ++ ++@key{UNPK} unpacks the vector on the stack, pushing each of its ++components separately. ++ ++@key{INDX} removes an integer @var{n}, then builds a vector of ++integers from 1 to @var{n}. @kbd{INV INDX} takes three numbers ++from the stack: The vector size @var{n}, the starting number, ++and the increment. @kbd{BLD} takes an integer @var{n} and any ++value @var{x} and builds a vector of @var{n} copies of @var{x}. ++ ++@key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n} ++identity matrix. ++ ++@key{LEN} replaces a vector by its length, an integer. ++ ++@key{...} turns on or off ``abbreviated'' display mode for large vectors. ++ ++@key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix ++inverse, determinant, and transpose, and vector cross product. ++ ++@key{SUM} replaces a vector by the sum of its elements. It is ++equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}). ++@key{PROD} computes the product of the elements of a vector, and ++@key{MAX} computes the maximum of all the elements of a vector. ++ ++@key{INV SUM} computes the alternating sum of the first element ++minus the second, plus the third, minus the fourth, and so on. ++@key{INV MAX} computes the minimum of the vector elements. ++ ++@key{HYP SUM} computes the mean of the vector elements. ++@key{HYP PROD} computes the sample standard deviation. ++@key{HYP MAX} computes the median. ++ ++@key{MAP*} multiplies two vectors elementwise. It is equivalent ++to the @kbd{V M *} command. @key{MAP^} computes powers elementwise. ++The arguments must be vectors of equal length, or one must be a vector ++and the other must be a plain number. For example, @kbd{2 MAP^} squares ++all the elements of a vector. ++ ++@key{MAP$} maps the formula on the top of the stack across the ++vector in the second-to-top position. If the formula contains ++several variables, Calc takes that many vectors starting at the ++second-to-top position and matches them to the variables in ++alphabetical order. The result is a vector of the same size as ++the input vectors, whose elements are the formula evaluated with ++the variables set to the various sets of numbers in those vectors. ++For example, you could simulate @key{MAP^} using @key{MAP$} with ++the formula @samp{x^y}. ++ ++The @kbd{"x"} key pushes the variable name @expr{x} onto the ++stack. To build the formula @expr{x^2 + 6}, you would use the ++key sequence @kbd{"x" 2 y^x 6 +}. This formula would then be ++suitable for use with the @key{MAP$} key described above. ++With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the ++@kbd{"x"} key pushes the variable names @expr{y}, @expr{z}, and ++@expr{t}, respectively. ++ ++@node Keypad Modes Menu, , Keypad Vectors Menu, Keypad Mode ++@section Modes Menu ++ ++@smallexample ++@group ++|----+----+----+----+----+----5 ++|FLT |FIX |SCI |ENG |GRP | | ++|----+----+----+----+----+----| ++|RAD |DEG |FRAC|POLR|SYMB|PREC| ++|----+----+----+----+----+----| ++|SWAP|RLL3|RLL4|OVER|STO |RCL | ++|----+----+----+----+----+----| ++@end group ++@end smallexample ++ ++@noindent ++The keys in this menu manipulate modes, variables, and the stack. ++ ++The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select ++floating-point, fixed-point, scientific, or engineering notation. ++@key{FIX} displays two digits after the decimal by default; the ++others display full precision. With the @key{INV} prefix, these ++keys pop a number-of-digits argument from the stack. ++ ++The @key{GRP} key turns grouping of digits with commas on or off. ++@kbd{INV GRP} enables grouping to the right of the decimal point as ++well as to the left. ++ ++The @key{RAD} and @key{DEG} keys switch between radians and degrees ++for trigonometric functions. ++ ++The @key{FRAC} key turns Fraction mode on or off. This affects ++whether commands like @kbd{/} with integer arguments produce ++fractional or floating-point results. ++ ++The @key{POLR} key turns Polar mode on or off, determining whether ++polar or rectangular complex numbers are used by default. ++ ++The @key{SYMB} key turns Symbolic mode on or off, in which ++operations that would produce inexact floating-point results ++are left unevaluated as algebraic formulas. ++ ++The @key{PREC} key selects the current precision. Answer with ++the keyboard or with the keypad digit and @key{ENTER} keys. ++ ++The @key{SWAP} key exchanges the top two stack elements. ++The @key{RLL3} key rotates the top three stack elements upwards. ++The @key{RLL4} key rotates the top four stack elements upwards. ++The @key{OVER} key duplicates the second-to-top stack element. ++ ++The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and ++@kbd{s r} in regular Calc. @xref{Store and Recall}. Click the ++@key{STO} or @key{RCL} key, then one of the ten digits. (Named ++variables are not available in Keypad mode.) You can also use, ++for example, @kbd{STO + 3} to add to register 3. ++ ++@node Embedded Mode, Programming, Keypad Mode, Top ++@chapter Embedded Mode ++ ++@noindent ++Embedded mode in Calc provides an alternative to copying numbers ++and formulas back and forth between editing buffers and the Calc ++stack. In Embedded mode, your editing buffer becomes temporarily ++linked to the stack and this copying is taken care of automatically. ++ ++@menu ++* Basic Embedded Mode:: ++* More About Embedded Mode:: ++* Assignments in Embedded Mode:: ++* Mode Settings in Embedded Mode:: ++* Customizing Embedded Mode:: ++@end menu ++ ++@node Basic Embedded Mode, More About Embedded Mode, Embedded Mode, Embedded Mode ++@section Basic Embedded Mode ++ ++@noindent ++@kindex C-x * e ++@pindex calc-embedded ++To enter Embedded mode, position the Emacs point (cursor) on a ++formula in any buffer and press @kbd{C-x * e} (@code{calc-embedded}). ++Note that @kbd{C-x * e} is not to be used in the Calc stack buffer ++like most Calc commands, but rather in regular editing buffers that ++are visiting your own files. ++ ++Calc will try to guess an appropriate language based on the major mode ++of the editing buffer. (@xref{Language Modes}.) If the current buffer is ++in @code{latex-mode}, for example, Calc will set its language to La@TeX{}. ++Similarly, Calc will use @TeX{} language for @code{tex-mode}, ++@code{plain-tex-mode} and @code{context-mode}, C language for ++@code{c-mode} and @code{c++-mode}, FORTRAN language for ++@code{fortran-mode} and @code{f90-mode}, Pascal for @code{pascal-mode}, ++and eqn for @code{nroff-mode} (@pxref{Customizing Calc}). ++These can be overridden with Calc's mode ++changing commands (@pxref{Mode Settings in Embedded Mode}). If no ++suitable language is available, Calc will continue with its current language. ++ ++Calc normally scans backward and forward in the buffer for the ++nearest opening and closing @dfn{formula delimiters}. The simplest ++delimiters are blank lines. Other delimiters that Embedded mode ++understands are: ++ ++@enumerate ++@item ++The @TeX{} and La@TeX{} math delimiters @samp{$ $}, @samp{$$ $$}, ++@samp{\[ \]}, and @samp{\( \)}; ++@item ++Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); ++@item ++Lines beginning with @samp{@@} (Texinfo delimiters). ++@item ++Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); ++@item ++Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. ++@end enumerate ++ ++@xref{Customizing Embedded Mode}, to see how to make Calc recognize ++your own favorite delimiters. Delimiters like @samp{$ $} can appear ++on their own separate lines or in-line with the formula. ++ ++If you give a positive or negative numeric prefix argument, Calc ++instead uses the current point as one end of the formula, and includes ++that many lines forward or backward (respectively, including the current ++line). Explicit delimiters are not necessary in this case. ++ ++With a prefix argument of zero, Calc uses the current region (delimited ++by point and mark) instead of formula delimiters. With a prefix ++argument of @kbd{C-u} only, Calc uses the current line as the formula. ++ ++@kindex C-x * w ++@pindex calc-embedded-word ++The @kbd{C-x * w} (@code{calc-embedded-word}) command will start Embedded ++mode on the current ``word''; in this case Calc will scan for the first ++non-numeric character (i.e., the first character that is not a digit, ++sign, decimal point, or upper- or lower-case @samp{e}) forward and ++backward to delimit the formula. ++ ++When you enable Embedded mode for a formula, Calc reads the text ++between the delimiters and tries to interpret it as a Calc formula. ++Calc can generally identify @TeX{} formulas and ++Big-style formulas even if the language mode is wrong. If Calc ++can't make sense of the formula, it beeps and refuses to enter ++Embedded mode. But if the current language is wrong, Calc can ++sometimes parse the formula successfully (but incorrectly); ++for example, the C expression @samp{atan(a[1])} can be parsed ++in Normal language mode, but the @code{atan} won't correspond to ++the built-in @code{arctan} function, and the @samp{a[1]} will be ++interpreted as @samp{a} times the vector @samp{[1]}! ++ ++If you press @kbd{C-x * e} or @kbd{C-x * w} to activate an embedded ++formula which is blank, say with the cursor on the space between ++the two delimiters @samp{$ $}, Calc will immediately prompt for ++an algebraic entry. ++ ++Only one formula in one buffer can be enabled at a time. If you ++move to another area of the current buffer and give Calc commands, ++Calc turns Embedded mode off for the old formula and then tries ++to restart Embedded mode at the new position. Other buffers are ++not affected by Embedded mode. ++ ++When Embedded mode begins, Calc pushes the current formula onto ++the stack. No Calc stack window is created; however, Calc copies ++the top-of-stack position into the original buffer at all times. ++You can create a Calc window by hand with @kbd{C-x * o} if you ++find you need to see the entire stack. ++ ++For example, typing @kbd{C-x * e} while somewhere in the formula ++@samp{n>2} in the following line enables Embedded mode on that ++inequality: ++ ++@example ++We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$. ++@end example ++ ++@noindent ++The formula @expr{n>2} will be pushed onto the Calc stack, and ++the top of stack will be copied back into the editing buffer. ++This means that spaces will appear around the @samp{>} symbol ++to match Calc's usual display style: ++ ++@example ++We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$. ++@end example ++ ++@noindent ++No spaces have appeared around the @samp{+} sign because it's ++in a different formula, one which we have not yet touched with ++Embedded mode. ++ ++Now that Embedded mode is enabled, keys you type in this buffer ++are interpreted as Calc commands. At this point we might use ++the ``commute'' command @kbd{j C} to reverse the inequality. ++This is a selection-based command for which we first need to ++move the cursor onto the operator (@samp{>} in this case) that ++needs to be commuted. ++ ++@example ++We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$. ++@end example ++ ++The @kbd{C-x * o} command is a useful way to open a Calc window ++without actually selecting that window. Giving this command ++verifies that @samp{2 < n} is also on the Calc stack. Typing ++@kbd{17 @key{RET}} would produce: ++ ++@example ++We define $F_n = F_(n-1)+F_(n-2)$ for all $17$. ++@end example ++ ++@noindent ++with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB} ++at this point will exchange the two stack values and restore ++@samp{2 < n} to the embedded formula. Even though you can't ++normally see the stack in Embedded mode, it is still there and ++it still operates in the same way. But, as with old-fashioned ++RPN calculators, you can only see the value at the top of the ++stack at any given time (unless you use @kbd{C-x * o}). ++ ++Typing @kbd{C-x * e} again turns Embedded mode off. The Calc ++window reveals that the formula @w{@samp{2 < n}} is automatically ++removed from the stack, but the @samp{17} is not. Entering ++Embedded mode always pushes one thing onto the stack, and ++leaving Embedded mode always removes one thing. Anything else ++that happens on the stack is entirely your business as far as ++Embedded mode is concerned. ++ ++If you press @kbd{C-x * e} in the wrong place by accident, it is ++possible that Calc will be able to parse the nearby text as a ++formula and will mangle that text in an attempt to redisplay it ++``properly'' in the current language mode. If this happens, ++press @kbd{C-x * e} again to exit Embedded mode, then give the ++regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put ++the text back the way it was before Calc edited it. Note that Calc's ++own Undo command (typed before you turn Embedded mode back off) ++will not do you any good, because as far as Calc is concerned ++you haven't done anything with this formula yet. ++ ++@node More About Embedded Mode, Assignments in Embedded Mode, Basic Embedded Mode, Embedded Mode ++@section More About Embedded Mode ++ ++@noindent ++When Embedded mode ``activates'' a formula, i.e., when it examines ++the formula for the first time since the buffer was created or ++loaded, Calc tries to sense the language in which the formula was ++written. If the formula contains any La@TeX{}-like @samp{\} sequences, ++it is parsed (i.e., read) in La@TeX{} mode. If the formula appears to ++be written in multi-line Big mode, it is parsed in Big mode. Otherwise, ++it is parsed according to the current language mode. ++ ++Note that Calc does not change the current language mode according ++the formula it reads in. Even though it can read a La@TeX{} formula when ++not in La@TeX{} mode, it will immediately rewrite this formula using ++whatever language mode is in effect. ++ ++@tex ++\bigskip ++@end tex ++ ++@kindex d p ++@pindex calc-show-plain ++Calc's parser is unable to read certain kinds of formulas. For ++example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can ++specify matrix display styles which the parser is unable to ++recognize as matrices. The @kbd{d p} (@code{calc-show-plain}) ++command turns on a mode in which a ``plain'' version of a ++formula is placed in front of the fully-formatted version. ++When Calc reads a formula that has such a plain version in ++front, it reads the plain version and ignores the formatted ++version. ++ ++Plain formulas are preceded and followed by @samp{%%%} signs ++by default. This notation has the advantage that the @samp{%} ++character begins a comment in @TeX{} and La@TeX{}, so if your formula is ++embedded in a @TeX{} or La@TeX{} document its plain version will be ++invisible in the final printed copy. Certain major modes have different ++delimiters to ensure that the ``plain'' version will be ++in a comment for those modes, also. ++See @ref{Customizing Embedded Mode} to see how to change the ``plain'' ++formula delimiters. ++ ++There are several notations which Calc's parser for ``big'' ++formatted formulas can't yet recognize. In particular, it can't ++read the large symbols for @code{sum}, @code{prod}, and @code{integ}, ++and it can't handle @samp{=>} with the righthand argument omitted. ++Also, Calc won't recognize special formats you have defined with ++the @kbd{Z C} command (@pxref{User-Defined Compositions}). In ++these cases it is important to use ``plain'' mode to make sure ++Calc will be able to read your formula later. ++ ++Another example where ``plain'' mode is important is if you have ++specified a float mode with few digits of precision. Normally ++any digits that are computed but not displayed will simply be ++lost when you save and re-load your embedded buffer, but ``plain'' ++mode allows you to make sure that the complete number is present ++in the file as well as the rounded-down number. ++ ++@tex ++\bigskip ++@end tex ++ ++Embedded buffers remember active formulas for as long as they ++exist in Emacs memory. Suppose you have an embedded formula ++which is @cpi{} to the normal 12 decimal places, and then ++type @w{@kbd{C-u 5 d n}} to display only five decimal places. ++If you then type @kbd{d n}, all 12 places reappear because the ++full number is still there on the Calc stack. More surprisingly, ++even if you exit Embedded mode and later re-enter it for that ++formula, typing @kbd{d n} will restore all 12 places because ++each buffer remembers all its active formulas. However, if you ++save the buffer in a file and reload it in a new Emacs session, ++all non-displayed digits will have been lost unless you used ++``plain'' mode. ++ ++@tex ++\bigskip ++@end tex ++ ++In some applications of Embedded mode, you will want to have a ++sequence of copies of a formula that show its evolution as you ++work on it. For example, you might want to have a sequence ++like this in your file (elaborating here on the example from ++the ``Getting Started'' chapter): ++ ++@smallexample ++The derivative of ++ ++ ln(ln(x)) ++ ++is ++ ++ @r{(the derivative of }ln(ln(x))@r{)} ++ ++whose value at x = 2 is ++ ++ @r{(the value)} ++ ++and at x = 3 is ++ ++ @r{(the value)} ++@end smallexample ++ ++@kindex C-x * d ++@pindex calc-embedded-duplicate ++The @kbd{C-x * d} (@code{calc-embedded-duplicate}) command is a ++handy way to make sequences like this. If you type @kbd{C-x * d}, ++the formula under the cursor (which may or may not have Embedded ++mode enabled for it at the time) is copied immediately below and ++Embedded mode is then enabled for that copy. ++ ++For this example, you would start with just ++ ++@smallexample ++The derivative of ++ ++ ln(ln(x)) ++@end smallexample ++ ++@noindent ++and press @kbd{C-x * d} with the cursor on this formula. The result ++is ++ ++@smallexample ++The derivative of ++ ++ ln(ln(x)) ++ ++ ++ ln(ln(x)) ++@end smallexample ++ ++@noindent ++with the second copy of the formula enabled in Embedded mode. ++You can now press @kbd{a d x @key{RET}} to take the derivative, and ++@kbd{C-x * d C-x * d} to make two more copies of the derivative. ++To complete the computations, type @kbd{3 s l x @key{RET}} to evaluate ++the last formula, then move up to the second-to-last formula ++and type @kbd{2 s l x @key{RET}}. ++ ++Finally, you would want to press @kbd{C-x * e} to exit Embedded ++mode, then go up and insert the necessary text in between the ++various formulas and numbers. ++ ++@tex ++\bigskip ++@end tex ++ ++@kindex C-x * f ++@kindex C-x * ' ++@pindex calc-embedded-new-formula ++The @kbd{C-x * f} (@code{calc-embedded-new-formula}) command ++creates a new embedded formula at the current point. It inserts ++some default delimiters, which are usually just blank lines, ++and then does an algebraic entry to get the formula (which is ++then enabled for Embedded mode). This is just shorthand for ++typing the delimiters yourself, positioning the cursor between ++the new delimiters, and pressing @kbd{C-x * e}. The key sequence ++@kbd{C-x * '} is equivalent to @kbd{C-x * f}. ++ ++@kindex C-x * n ++@kindex C-x * p ++@pindex calc-embedded-next ++@pindex calc-embedded-previous ++The @kbd{C-x * n} (@code{calc-embedded-next}) and @kbd{C-x * p} ++(@code{calc-embedded-previous}) commands move the cursor to the ++next or previous active embedded formula in the buffer. They ++can take positive or negative prefix arguments to move by several ++formulas. Note that these commands do not actually examine the ++text of the buffer looking for formulas; they only see formulas ++which have previously been activated in Embedded mode. In fact, ++@kbd{C-x * n} and @kbd{C-x * p} are a useful way to tell which ++embedded formulas are currently active. Also, note that these ++commands do not enable Embedded mode on the next or previous ++formula, they just move the cursor. ++ ++@kindex C-x * ` ++@pindex calc-embedded-edit ++The @kbd{C-x * `} (@code{calc-embedded-edit}) command edits the ++embedded formula at the current point as if by @kbd{`} (@code{calc-edit}). ++Embedded mode does not have to be enabled for this to work. Press ++@kbd{C-c C-c} to finish the edit, or @kbd{C-x k} to cancel. ++ ++@node Assignments in Embedded Mode, Mode Settings in Embedded Mode, More About Embedded Mode, Embedded Mode ++@section Assignments in Embedded Mode ++ ++@noindent ++The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators ++are especially useful in Embedded mode. They allow you to make ++a definition in one formula, then refer to that definition in ++other formulas embedded in the same buffer. ++ ++An embedded formula which is an assignment to a variable, as in ++ ++@example ++foo := 5 ++@end example ++ ++@noindent ++records @expr{5} as the stored value of @code{foo} for the ++purposes of Embedded mode operations in the current buffer. It ++does @emph{not} actually store @expr{5} as the ``global'' value ++of @code{foo}, however. Regular Calc operations, and Embedded ++formulas in other buffers, will not see this assignment. ++ ++One way to use this assigned value is simply to create an ++Embedded formula elsewhere that refers to @code{foo}, and to press ++@kbd{=} in that formula. However, this permanently replaces the ++@code{foo} in the formula with its current value. More interesting ++is to use @samp{=>} elsewhere: ++ ++@example ++foo + 7 => 12 ++@end example ++ ++@xref{Evaluates-To Operator}, for a general discussion of @samp{=>}. ++ ++If you move back and change the assignment to @code{foo}, any ++@samp{=>} formulas which refer to it are automatically updated. ++ ++@example ++foo := 17 ++ ++foo + 7 => 24 ++@end example ++ ++The obvious question then is, @emph{how} can one easily change the ++assignment to @code{foo}? If you simply select the formula in ++Embedded mode and type 17, the assignment itself will be replaced ++by the 17. The effect on the other formula will be that the ++variable @code{foo} becomes unassigned: ++ ++@example ++17 ++ ++foo + 7 => foo + 7 ++@end example ++ ++The right thing to do is first to use a selection command (@kbd{j 2} ++will do the trick) to select the righthand side of the assignment. ++Then, @kbd{17 @key{TAB} @key{DEL}} will swap the 17 into place (@pxref{Selecting ++Subformulas}, to see how this works). ++ ++@kindex C-x * j ++@pindex calc-embedded-select ++The @kbd{C-x * j} (@code{calc-embedded-select}) command provides an ++easy way to operate on assignments. It is just like @kbd{C-x * e}, ++except that if the enabled formula is an assignment, it uses ++@kbd{j 2} to select the righthand side. If the enabled formula ++is an evaluates-to, it uses @kbd{j 1} to select the lefthand side. ++A formula can also be a combination of both: ++ ++@example ++bar := foo + 3 => 20 ++@end example ++ ++@noindent ++in which case @kbd{C-x * j} will select the middle part (@samp{foo + 3}). ++ ++The formula is automatically deselected when you leave Embedded ++mode. ++ ++@kindex C-x * u ++@pindex calc-embedded-update-formula ++Another way to change the assignment to @code{foo} would simply be ++to edit the number using regular Emacs editing rather than Embedded ++mode. Then, we have to find a way to get Embedded mode to notice ++the change. The @kbd{C-x * u} (@code{calc-embedded-update-formula}) ++command is a convenient way to do this. ++ ++@example ++foo := 6 ++ ++foo + 7 => 13 ++@end example ++ ++Pressing @kbd{C-x * u} is much like pressing @kbd{C-x * e = C-x * e}, that ++is, temporarily enabling Embedded mode for the formula under the ++cursor and then evaluating it with @kbd{=}. But @kbd{C-x * u} does ++not actually use @kbd{C-x * e}, and in fact another formula somewhere ++else can be enabled in Embedded mode while you use @kbd{C-x * u} and ++that formula will not be disturbed. ++ ++With a numeric prefix argument, @kbd{C-x * u} updates all active ++@samp{=>} formulas in the buffer. Formulas which have not yet ++been activated in Embedded mode, and formulas which do not have ++@samp{=>} as their top-level operator, are not affected by this. ++(This is useful only if you have used @kbd{m C}; see below.) ++ ++With a plain @kbd{C-u} prefix, @kbd{C-u C-x * u} updates only in the ++region between mark and point rather than in the whole buffer. ++ ++@kbd{C-x * u} is also a handy way to activate a formula, such as an ++@samp{=>} formula that has freshly been typed in or loaded from a ++file. ++ ++@kindex C-x * a ++@pindex calc-embedded-activate ++The @kbd{C-x * a} (@code{calc-embedded-activate}) command scans ++through the current buffer and activates all embedded formulas ++that contain @samp{:=} or @samp{=>} symbols. This does not mean ++that Embedded mode is actually turned on, but only that the ++formulas' positions are registered with Embedded mode so that ++the @samp{=>} values can be properly updated as assignments are ++changed. ++ ++It is a good idea to type @kbd{C-x * a} right after loading a file ++that uses embedded @samp{=>} operators. Emacs includes a nifty ++``buffer-local variables'' feature that you can use to do this ++automatically. The idea is to place near the end of your file ++a few lines that look like this: ++ ++@example ++--- Local Variables: --- ++--- eval:(calc-embedded-activate) --- ++--- End: --- ++@end example ++ ++@noindent ++where the leading and trailing @samp{---} can be replaced by ++any suitable strings (which must be the same on all three lines) ++or omitted altogether; in a @TeX{} or La@TeX{} file, @samp{%} would be a good ++leading string and no trailing string would be necessary. In a ++C program, @samp{/*} and @samp{*/} would be good leading and ++trailing strings. ++ ++When Emacs loads a file into memory, it checks for a Local Variables ++section like this one at the end of the file. If it finds this ++section, it does the specified things (in this case, running ++@kbd{C-x * a} automatically) before editing of the file begins. ++The Local Variables section must be within 3000 characters of the ++end of the file for Emacs to find it, and it must be in the last ++page of the file if the file has any page separators. ++@xref{File Variables, , Local Variables in Files, emacs, the ++Emacs manual}. ++ ++Note that @kbd{C-x * a} does not update the formulas it finds. ++To do this, type, say, @kbd{M-1 C-x * u} after @w{@kbd{C-x * a}}. ++Generally this should not be a problem, though, because the ++formulas will have been up-to-date already when the file was ++saved. ++ ++Normally, @kbd{C-x * a} activates all the formulas it finds, but ++any previous active formulas remain active as well. With a ++positive numeric prefix argument, @kbd{C-x * a} first deactivates ++all current active formulas, then actives the ones it finds in ++its scan of the buffer. With a negative prefix argument, ++@kbd{C-x * a} simply deactivates all formulas. ++ ++Embedded mode has two symbols, @samp{Active} and @samp{~Active}, ++which it puts next to the major mode name in a buffer's mode line. ++It puts @samp{Active} if it has reason to believe that all ++formulas in the buffer are active, because you have typed @kbd{C-x * a} ++and Calc has not since had to deactivate any formulas (which can ++happen if Calc goes to update an @samp{=>} formula somewhere because ++a variable changed, and finds that the formula is no longer there ++due to some kind of editing outside of Embedded mode). Calc puts ++@samp{~Active} in the mode line if some, but probably not all, ++formulas in the buffer are active. This happens if you activate ++a few formulas one at a time but never use @kbd{C-x * a}, or if you ++used @kbd{C-x * a} but then Calc had to deactivate a formula ++because it lost track of it. If neither of these symbols appears ++in the mode line, no embedded formulas are active in the buffer ++(e.g., before Embedded mode has been used, or after a @kbd{M-- C-x * a}). ++ ++Embedded formulas can refer to assignments both before and after them ++in the buffer. If there are several assignments to a variable, the ++nearest preceding assignment is used if there is one, otherwise the ++following assignment is used. ++ ++@example ++x => 1 ++ ++x := 1 ++ ++x => 1 ++ ++x := 2 ++ ++x => 2 ++@end example ++ ++As well as simple variables, you can also assign to subscript ++expressions of the form @samp{@var{var}_@var{number}} (as in ++@code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}). ++Assignments to other kinds of objects can be represented by Calc, ++but the automatic linkage between assignments and references works ++only for plain variables and these two kinds of subscript expressions. ++ ++If there are no assignments to a given variable, the global ++stored value for the variable is used (@pxref{Storing Variables}), ++or, if no value is stored, the variable is left in symbolic form. ++Note that global stored values will be lost when the file is saved ++and loaded in a later Emacs session, unless you have used the ++@kbd{s p} (@code{calc-permanent-variable}) command to save them; ++@pxref{Operations on Variables}. ++ ++The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic ++recomputation of @samp{=>} forms on and off. If you turn automatic ++recomputation off, you will have to use @kbd{C-x * u} to update these ++formulas manually after an assignment has been changed. If you ++plan to change several assignments at once, it may be more efficient ++to type @kbd{m C}, change all the assignments, then use @kbd{M-1 C-x * u} ++to update the entire buffer afterwards. The @kbd{m C} command also ++controls @samp{=>} formulas on the stack; @pxref{Evaluates-To ++Operator}. When you turn automatic recomputation back on, the ++stack will be updated but the Embedded buffer will not; you must ++use @kbd{C-x * u} to update the buffer by hand. ++ ++@node Mode Settings in Embedded Mode, Customizing Embedded Mode, Assignments in Embedded Mode, Embedded Mode ++@section Mode Settings in Embedded Mode ++ ++@kindex m e ++@pindex calc-embedded-preserve-modes ++@noindent ++The mode settings can be changed while Calc is in embedded mode, but ++by default they will revert to their original values when embedded mode ++is ended. However, the modes saved when the mode-recording mode is ++@code{Save} (see below) and the modes in effect when the @kbd{m e} ++(@code{calc-embedded-preserve-modes}) command is given ++will be preserved when embedded mode is ended. ++ ++Embedded mode has a rather complicated mechanism for handling mode ++settings in Embedded formulas. It is possible to put annotations ++in the file that specify mode settings either global to the entire ++file or local to a particular formula or formulas. In the latter ++case, different modes can be specified for use when a formula ++is the enabled Embedded mode formula. ++ ++When you give any mode-setting command, like @kbd{m f} (for Fraction ++mode) or @kbd{d s} (for scientific notation), Embedded mode adds ++a line like the following one to the file just before the opening ++delimiter of the formula. ++ ++@example ++% [calc-mode: fractions: t] ++% [calc-mode: float-format: (sci 0)] ++@end example ++ ++When Calc interprets an embedded formula, it scans the text before ++the formula for mode-setting annotations like these and sets the ++Calc buffer to match these modes. Modes not explicitly described ++in the file are not changed. Calc scans all the way to the top of ++the file, or up to a line of the form ++ ++@example ++% [calc-defaults] ++@end example ++ ++@noindent ++which you can insert at strategic places in the file if this backward ++scan is getting too slow, or just to provide a barrier between one ++``zone'' of mode settings and another. ++ ++If the file contains several annotations for the same mode, the ++closest one before the formula is used. Annotations after the ++formula are never used (except for global annotations, described ++below). ++ ++The scan does not look for the leading @samp{% }, only for the ++square brackets and the text they enclose. In fact, the leading ++characters are different for different major modes. You can edit the ++mode annotations to a style that works better in context if you wish. ++@xref{Customizing Embedded Mode}, to see how to change the style ++that Calc uses when it generates the annotations. You can write ++mode annotations into the file yourself if you know the syntax; ++the easiest way to find the syntax for a given mode is to let ++Calc write the annotation for it once and see what it does. ++ ++If you give a mode-changing command for a mode that already has ++a suitable annotation just above the current formula, Calc will ++modify that annotation rather than generating a new, conflicting ++one. ++ ++Mode annotations have three parts, separated by colons. (Spaces ++after the colons are optional.) The first identifies the kind ++of mode setting, the second is a name for the mode itself, and ++the third is the value in the form of a Lisp symbol, number, ++or list. Annotations with unrecognizable text in the first or ++second parts are ignored. The third part is not checked to make ++sure the value is of a valid type or range; if you write an ++annotation by hand, be sure to give a proper value or results ++will be unpredictable. Mode-setting annotations are case-sensitive. ++ ++While Embedded mode is enabled, the word @code{Local} appears in ++the mode line. This is to show that mode setting commands generate ++annotations that are ``local'' to the current formula or set of ++formulas. The @kbd{m R} (@code{calc-mode-record-mode}) command ++causes Calc to generate different kinds of annotations. Pressing ++@kbd{m R} repeatedly cycles through the possible modes. ++ ++@code{LocEdit} and @code{LocPerm} modes generate annotations ++that look like this, respectively: ++ ++@example ++% [calc-edit-mode: float-format: (sci 0)] ++% [calc-perm-mode: float-format: (sci 5)] ++@end example ++ ++The first kind of annotation will be used only while a formula ++is enabled in Embedded mode. The second kind will be used only ++when the formula is @emph{not} enabled. (Whether the formula ++is ``active'' or not, i.e., whether Calc has seen this formula ++yet, is not relevant here.) ++ ++@code{Global} mode generates an annotation like this at the end ++of the file: ++ ++@example ++% [calc-global-mode: fractions t] ++@end example ++ ++Global mode annotations affect all formulas throughout the file, ++and may appear anywhere in the file. This allows you to tuck your ++mode annotations somewhere out of the way, say, on a new page of ++the file, as long as those mode settings are suitable for all ++formulas in the file. ++ ++Enabling a formula with @kbd{C-x * e} causes a fresh scan for local ++mode annotations; you will have to use this after adding annotations ++above a formula by hand to get the formula to notice them. Updating ++a formula with @kbd{C-x * u} will also re-scan the local modes, but ++global modes are only re-scanned by @kbd{C-x * a}. ++ ++Another way that modes can get out of date is if you add a local ++mode annotation to a formula that has another formula after it. ++In this example, we have used the @kbd{d s} command while the ++first of the two embedded formulas is active. But the second ++formula has not changed its style to match, even though by the ++rules of reading annotations the @samp{(sci 0)} applies to it, too. ++ ++@example ++% [calc-mode: float-format: (sci 0)] ++1.23e2 ++ ++456. ++@end example ++ ++We would have to go down to the other formula and press @kbd{C-x * u} ++on it in order to get it to notice the new annotation. ++ ++Two more mode-recording modes selectable by @kbd{m R} are available ++which are also available outside of Embedded mode. ++(@pxref{General Mode Commands}.) They are @code{Save}, in which mode ++settings are recorded permanently in your Calc init file (the file given ++by the variable @code{calc-settings-file}, typically @file{~/.calc.el}) ++rather than by annotating the current document, and no-recording ++mode (where there is no symbol like @code{Save} or @code{Local} in ++the mode line), in which mode-changing commands do not leave any ++annotations at all. ++ ++When Embedded mode is not enabled, mode-recording modes except ++for @code{Save} have no effect. ++ ++@node Customizing Embedded Mode, , Mode Settings in Embedded Mode, Embedded Mode ++@section Customizing Embedded Mode ++ ++@noindent ++You can modify Embedded mode's behavior by setting various Lisp ++variables described here. These variables are customizable ++(@pxref{Customizing Calc}), or you can use @kbd{M-x set-variable} ++or @kbd{M-x edit-options} to adjust a variable on the fly. ++(Another possibility would be to use a file-local variable annotation at ++the end of the file; ++@pxref{File Variables, , Local Variables in Files, emacs, the Emacs manual}.) ++Many of the variables given mentioned here can be set to depend on the ++major mode of the editing buffer (@pxref{Customizing Calc}). ++ ++@vindex calc-embedded-open-formula ++The @code{calc-embedded-open-formula} variable holds a regular ++expression for the opening delimiter of a formula. @xref{Regexp Search, ++, Regular Expression Search, emacs, the Emacs manual}, to see ++how regular expressions work. Basically, a regular expression is a ++pattern that Calc can search for. A regular expression that considers ++blank lines, @samp{$}, and @samp{$$} to be opening delimiters is ++@code{"\\`\\|^\n\\|\\$\\$?"}. Just in case the meaning of this ++regular expression is not completely plain, let's go through it ++in detail. ++ ++The surrounding @samp{" "} marks quote the text between them as a ++Lisp string. If you left them off, @code{set-variable} or ++@code{edit-options} would try to read the regular expression as a ++Lisp program. ++ ++The most obvious property of this regular expression is that it ++contains indecently many backslashes. There are actually two levels ++of backslash usage going on here. First, when Lisp reads a quoted ++string, all pairs of characters beginning with a backslash are ++interpreted as special characters. Here, @code{\n} changes to a ++new-line character, and @code{\\} changes to a single backslash. ++So the actual regular expression seen by Calc is ++@samp{\`\|^ @r{(newline)} \|\$\$?}. ++ ++Regular expressions also consider pairs beginning with backslash ++to have special meanings. Sometimes the backslash is used to quote ++a character that otherwise would have a special meaning in a regular ++expression, like @samp{$}, which normally means ``end-of-line,'' ++or @samp{?}, which means that the preceding item is optional. So ++@samp{\$\$?} matches either one or two dollar signs. ++ ++The other codes in this regular expression are @samp{^}, which matches ++``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`}, ++which matches ``beginning-of-buffer.'' So the whole pattern means ++that a formula begins at the beginning of the buffer, or on a newline ++that occurs at the beginning of a line (i.e., a blank line), or at ++one or two dollar signs. ++ ++The default value of @code{calc-embedded-open-formula} looks just ++like this example, with several more alternatives added on to ++recognize various other common kinds of delimiters. ++ ++By the way, the reason to use @samp{^\n} rather than @samp{^$} ++or @samp{\n\n}, which also would appear to match blank lines, ++is that the former expression actually ``consumes'' only one ++newline character as @emph{part of} the delimiter, whereas the ++latter expressions consume zero or two newlines, respectively. ++The former choice gives the most natural behavior when Calc ++must operate on a whole formula including its delimiters. ++ ++See the Emacs manual for complete details on regular expressions. ++But just for your convenience, here is a list of all characters ++which must be quoted with backslash (like @samp{\$}) to avoid ++some special interpretation: @samp{. * + ? [ ] ^ $ \}. (Note ++the backslash in this list; for example, to match @samp{\[} you ++must use @code{"\\\\\\["}. An exercise for the reader is to ++account for each of these six backslashes!) ++ ++@vindex calc-embedded-close-formula ++The @code{calc-embedded-close-formula} variable holds a regular ++expression for the closing delimiter of a formula. A closing ++regular expression to match the above example would be ++@code{"\\'\\|\n$\\|\\$\\$?"}. This is almost the same as the ++other one, except it now uses @samp{\'} (``end-of-buffer'') and ++@samp{\n$} (newline occurring at end of line, yet another way ++of describing a blank line that is more appropriate for this ++case). ++ ++@vindex calc-embedded-word-regexp ++The @code{calc-embedded-word-regexp} variable holds a regular expression ++used to define an expression to look for (a ``word'') when you type ++@kbd{C-x * w} to enable Embedded mode. ++ ++@vindex calc-embedded-open-plain ++The @code{calc-embedded-open-plain} variable is a string which ++begins a ``plain'' formula written in front of the formatted ++formula when @kbd{d p} mode is turned on. Note that this is an ++actual string, not a regular expression, because Calc must be able ++to write this string into a buffer as well as to recognize it. ++The default string is @code{"%%% "} (note the trailing space), but may ++be different for certain major modes. ++ ++@vindex calc-embedded-close-plain ++The @code{calc-embedded-close-plain} variable is a string which ++ends a ``plain'' formula. The default is @code{" %%%\n"}, but may be ++different for different major modes. Without ++the trailing newline here, the first line of a Big mode formula ++that followed might be shifted over with respect to the other lines. ++ ++@vindex calc-embedded-open-new-formula ++The @code{calc-embedded-open-new-formula} variable is a string ++which is inserted at the front of a new formula when you type ++@kbd{C-x * f}. Its default value is @code{"\n\n"}. If this ++string begins with a newline character and the @kbd{C-x * f} is ++typed at the beginning of a line, @kbd{C-x * f} will skip this ++first newline to avoid introducing unnecessary blank lines in ++the file. ++ ++@vindex calc-embedded-close-new-formula ++The @code{calc-embedded-close-new-formula} variable is the corresponding ++string which is inserted at the end of a new formula. Its default ++value is also @code{"\n\n"}. The final newline is omitted by ++@w{@kbd{C-x * f}} if typed at the end of a line. (It follows that if ++@kbd{C-x * f} is typed on a blank line, both a leading opening ++newline and a trailing closing newline are omitted.) ++ ++@vindex calc-embedded-announce-formula ++The @code{calc-embedded-announce-formula} variable is a regular ++expression which is sure to be followed by an embedded formula. ++The @kbd{C-x * a} command searches for this pattern as well as for ++@samp{=>} and @samp{:=} operators. Note that @kbd{C-x * a} will ++not activate just anything surrounded by formula delimiters; after ++all, blank lines are considered formula delimiters by default! ++But if your language includes a delimiter which can only occur ++actually in front of a formula, you can take advantage of it here. ++The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, but may be ++different for different major modes. ++This pattern will check for @samp{%Embed} followed by any number of ++lines beginning with @samp{%} and a space. This last is important to ++make Calc consider mode annotations part of the pattern, so that the ++formula's opening delimiter really is sure to follow the pattern. ++ ++@vindex calc-embedded-open-mode ++The @code{calc-embedded-open-mode} variable is a string (not a ++regular expression) which should precede a mode annotation. ++Calc never scans for this string; Calc always looks for the ++annotation itself. But this is the string that is inserted before ++the opening bracket when Calc adds an annotation on its own. ++The default is @code{"% "}, but may be different for different major ++modes. ++ ++@vindex calc-embedded-close-mode ++The @code{calc-embedded-close-mode} variable is a string which ++follows a mode annotation written by Calc. Its default value ++is simply a newline, @code{"\n"}, but may be different for different ++major modes. If you change this, it is a good idea still to end with a ++newline so that mode annotations will appear on lines by themselves. ++ ++@node Programming, Copying, Embedded Mode, Top ++@chapter Programming ++ ++@noindent ++There are several ways to ``program'' the Emacs Calculator, depending ++on the nature of the problem you need to solve. ++ ++@enumerate ++@item ++@dfn{Keyboard macros} allow you to record a sequence of keystrokes ++and play them back at a later time. This is just the standard Emacs ++keyboard macro mechanism, dressed up with a few more features such ++as loops and conditionals. ++ ++@item ++@dfn{Algebraic definitions} allow you to use any formula to define a ++new function. This function can then be used in algebraic formulas or ++as an interactive command. ++ ++@item ++@dfn{Rewrite rules} are discussed in the section on algebra commands. ++@xref{Rewrite Rules}. If you put your rewrite rules in the variable ++@code{EvalRules}, they will be applied automatically to all Calc ++results in just the same way as an internal ``rule'' is applied to ++evaluate @samp{sqrt(9)} to 3 and so on. @xref{Automatic Rewrites}. ++ ++@item ++@dfn{Lisp} is the programming language that Calc (and most of Emacs) ++is written in. If the above techniques aren't powerful enough, you ++can write Lisp functions to do anything that built-in Calc commands ++can do. Lisp code is also somewhat faster than keyboard macros or ++rewrite rules. ++@end enumerate ++ ++@kindex z ++Programming features are available through the @kbd{z} and @kbd{Z} ++prefix keys. New commands that you define are two-key sequences ++beginning with @kbd{z}. Commands for managing these definitions ++use the shift-@kbd{Z} prefix. (The @kbd{Z T} (@code{calc-timing}) ++command is described elsewhere; @pxref{Troubleshooting Commands}. ++The @kbd{Z C} (@code{calc-user-define-composition}) command is also ++described elsewhere; @pxref{User-Defined Compositions}.) ++ ++@menu ++* Creating User Keys:: ++* Keyboard Macros:: ++* Invocation Macros:: ++* Algebraic Definitions:: ++* Lisp Definitions:: ++@end menu ++ ++@node Creating User Keys, Keyboard Macros, Programming, Programming ++@section Creating User Keys ++ ++@noindent ++@kindex Z D ++@pindex calc-user-define ++Any Calculator command may be bound to a key using the @kbd{Z D} ++(@code{calc-user-define}) command. Actually, it is bound to a two-key ++sequence beginning with the lower-case @kbd{z} prefix. ++ ++The @kbd{Z D} command first prompts for the key to define. For example, ++press @kbd{Z D a} to define the new key sequence @kbd{z a}. You are then ++prompted for the name of the Calculator command that this key should ++run. For example, the @code{calc-sincos} command is not normally ++available on a key. Typing @kbd{Z D s sincos @key{RET}} programs the ++@kbd{z s} key sequence to run @code{calc-sincos}. This definition will remain ++in effect for the rest of this Emacs session, or until you redefine ++@kbd{z s} to be something else. ++ ++You can actually bind any Emacs command to a @kbd{z} key sequence by ++backspacing over the @samp{calc-} when you are prompted for the command name. ++ ++As with any other prefix key, you can type @kbd{z ?} to see a list of ++all the two-key sequences you have defined that start with @kbd{z}. ++Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined. ++ ++User keys are typically letters, but may in fact be any key. ++(@key{META}-keys are not permitted, nor are a terminal's special ++function keys which generate multi-character sequences when pressed.) ++You can define different commands on the shifted and unshifted versions ++of a letter if you wish. ++ ++@kindex Z U ++@pindex calc-user-undefine ++The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key. ++For example, the key sequence @kbd{Z U s} will undefine the @code{sincos} ++key we defined above. ++ ++@kindex Z P ++@pindex calc-user-define-permanent ++@cindex Storing user definitions ++@cindex Permanent user definitions ++@cindex Calc init file, user-defined commands ++The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key ++binding permanent so that it will remain in effect even in future Emacs ++sessions. (It does this by adding a suitable bit of Lisp code into ++your Calc init file; that is, the file given by the variable ++@code{calc-settings-file}, typically @file{~/.calc.el}.) For example, ++@kbd{Z P s} would register our @code{sincos} command permanently. If ++you later wish to unregister this command you must edit your Calc init ++file by hand. (@xref{General Mode Commands}, for a way to tell Calc to ++use a different file for the Calc init file.) ++ ++The @kbd{Z P} command also saves the user definition, if any, for the ++command bound to the key. After @kbd{Z F} and @kbd{Z C}, a given user ++key could invoke a command, which in turn calls an algebraic function, ++which might have one or more special display formats. A single @kbd{Z P} ++command will save all of these definitions. ++To save an algebraic function, type @kbd{'} (the apostrophe) ++when prompted for a key, and type the function name. To save a command ++without its key binding, type @kbd{M-x} and enter a function name. (The ++@samp{calc-} prefix will automatically be inserted for you.) ++(If the command you give implies a function, the function will be saved, ++and if the function has any display formats, those will be saved, but ++not the other way around: Saving a function will not save any commands ++or key bindings associated with the function.) ++ ++@kindex Z E ++@pindex calc-user-define-edit ++@cindex Editing user definitions ++The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition ++of a user key. This works for keys that have been defined by either ++keyboard macros or formulas; further details are contained in the relevant ++following sections. ++ ++@node Keyboard Macros, Invocation Macros, Creating User Keys, Programming ++@section Programming with Keyboard Macros ++ ++@noindent ++@kindex X ++@cindex Programming with keyboard macros ++@cindex Keyboard macros ++The easiest way to ``program'' the Emacs Calculator is to use standard ++keyboard macros. Press @w{@kbd{C-x (}} to begin recording a macro. From ++this point on, keystrokes you type will be saved away as well as ++performing their usual functions. Press @kbd{C-x )} to end recording. ++Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to ++execute your keyboard macro by replaying the recorded keystrokes. ++@xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further ++information. ++ ++When you use @kbd{X} to invoke a keyboard macro, the entire macro is ++treated as a single command by the undo and trail features. The stack ++display buffer is not updated during macro execution, but is instead ++fixed up once the macro completes. Thus, commands defined with keyboard ++macros are convenient and efficient. The @kbd{C-x e} command, on the ++other hand, invokes the keyboard macro with no special treatment: Each ++command in the macro will record its own undo information and trail entry, ++and update the stack buffer accordingly. If your macro uses features ++outside of Calc's control to operate on the contents of the Calc stack ++buffer, or if it includes Undo, Redo, or last-arguments commands, you ++must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date ++at all times. You could also consider using @kbd{K} (@code{calc-keep-args}) ++instead of @kbd{M-@key{RET}} (@code{calc-last-args}). ++ ++Calc extends the standard Emacs keyboard macros in several ways. ++Keyboard macros can be used to create user-defined commands. Keyboard ++macros can include conditional and iteration structures, somewhat ++analogous to those provided by a traditional programmable calculator. ++ ++@menu ++* Naming Keyboard Macros:: ++* Conditionals in Macros:: ++* Loops in Macros:: ++* Local Values in Macros:: ++* Queries in Macros:: ++@end menu ++ ++@node Naming Keyboard Macros, Conditionals in Macros, Keyboard Macros, Keyboard Macros ++@subsection Naming Keyboard Macros ++ ++@noindent ++@kindex Z K ++@pindex calc-user-define-kbd-macro ++Once you have defined a keyboard macro, you can bind it to a @kbd{z} ++key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command. ++This command prompts first for a key, then for a command name. For ++example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will ++define a keyboard macro which negates the top two numbers on the stack ++(@key{TAB} swaps the top two stack elements). Now you can type ++@kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key ++sequence. The default command name (if you answer the second prompt with ++just the @key{RET} key as in this example) will be something like ++@samp{calc-User-n}. The keyboard macro will now be available as both ++@kbd{z n} and @kbd{M-x calc-User-n}. You can backspace and enter a more ++descriptive command name if you wish. ++ ++Macros defined by @kbd{Z K} act like single commands; they are executed ++in the same way as by the @kbd{X} key. If you wish to define the macro ++as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}), ++give a negative prefix argument to @kbd{Z K}. ++ ++Once you have bound your keyboard macro to a key, you can use ++@kbd{Z P} to register it permanently with Emacs. @xref{Creating User Keys}. ++ ++@cindex Keyboard macros, editing ++The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has ++been defined by a keyboard macro tries to use the @code{edmacro} package ++edit the macro. Type @kbd{C-c C-c} to finish editing and update ++the definition stored on the key, or, to cancel the edit, kill the ++buffer with @kbd{C-x k}. ++The special characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, ++@code{DEL}, and @code{NUL} must be entered as these three character ++sequences, written in all uppercase, as must the prefixes @code{C-} and ++@code{M-}. Spaces and line breaks are ignored. Other characters are ++copied verbatim into the keyboard macro. Basically, the notation is the ++same as is used in all of this manual's examples, except that the manual ++takes some liberties with spaces: When we say @kbd{' [1 2 3] @key{RET}}, ++we take it for granted that it is clear we really mean ++@kbd{' [1 @key{SPC} 2 @key{SPC} 3] @key{RET}}. ++ ++@kindex C-x * m ++@pindex read-kbd-macro ++The @kbd{C-x * m} (@code{read-kbd-macro}) command reads an Emacs ``region'' ++of spelled-out keystrokes and defines it as the current keyboard macro. ++It is a convenient way to define a keyboard macro that has been stored ++in a file, or to define a macro without executing it at the same time. ++ ++@node Conditionals in Macros, Loops in Macros, Naming Keyboard Macros, Keyboard Macros ++@subsection Conditionals in Keyboard Macros ++ ++@noindent ++@kindex Z [ ++@kindex Z ] ++@pindex calc-kbd-if ++@pindex calc-kbd-else ++@pindex calc-kbd-else-if ++@pindex calc-kbd-end-if ++@cindex Conditional structures ++The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if}) ++commands allow you to put simple tests in a keyboard macro. When Calc ++sees the @kbd{Z [}, it pops an object from the stack and, if the object is ++a non-zero value, continues executing keystrokes. But if the object is ++zero, or if it is not provably nonzero, Calc skips ahead to the matching ++@kbd{Z ]} keystroke. @xref{Logical Operations}, for a set of commands for ++performing tests which conveniently produce 1 for true and 0 for false. ++ ++For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value ++function in the form of a keyboard macro. This macro duplicates the ++number on the top of the stack, pushes zero and compares using @kbd{a <} ++(@code{calc-less-than}), then, if the number was less than zero, ++executes @kbd{n} (@code{calc-change-sign}). Otherwise, the change-sign ++command is skipped. ++ ++To program this macro, type @kbd{C-x (}, type the above sequence of ++keystrokes, then type @kbd{C-x )}. Note that the keystrokes will be ++executed while you are making the definition as well as when you later ++re-execute the macro by typing @kbd{X}. Thus you should make sure a ++suitable number is on the stack before defining the macro so that you ++don't get a stack-underflow error during the definition process. ++ ++Conditionals can be nested arbitrarily. However, there should be exactly ++one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro. ++ ++@kindex Z : ++The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between ++two keystroke sequences. The general format is @kbd{@var{cond} Z [ ++@var{then-part} Z : @var{else-part} Z ]}. If @var{cond} is true ++(i.e., if the top of stack contains a non-zero number after @var{cond} ++has been executed), the @var{then-part} will be executed and the ++@var{else-part} will be skipped. Otherwise, the @var{then-part} will ++be skipped and the @var{else-part} will be executed. ++ ++@kindex Z | ++The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose ++between any number of alternatives. For example, ++@kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z : ++@var{part3} Z ]} will execute @var{part1} if @var{cond1} is true, ++otherwise it will execute @var{part2} if @var{cond2} is true, otherwise ++it will execute @var{part3}. ++ ++More precisely, @kbd{Z [} pops a number and conditionally skips to the ++next matching @kbd{Z :} or @kbd{Z ]} key. @w{@kbd{Z ]}} has no effect when ++actually executed. @kbd{Z :} skips to the next matching @kbd{Z ]}. ++@kbd{Z |} pops a number and conditionally skips to the next matching ++@kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally ++equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |} ++does not. ++ ++Calc's conditional and looping constructs work by scanning the ++keyboard macro for occurrences of character sequences like @samp{Z:} ++and @samp{Z]}. One side-effect of this is that if you use these ++constructs you must be careful that these character pairs do not ++occur by accident in other parts of the macros. Since Calc rarely ++uses shift-@kbd{Z} for any purpose except as a prefix character, this ++is not likely to be a problem. Another side-effect is that it will ++not work to define your own custom key bindings for these commands. ++Only the standard shift-@kbd{Z} bindings will work correctly. ++ ++@kindex Z C-g ++If Calc gets stuck while skipping characters during the definition of a ++macro, type @kbd{Z C-g} to cancel the definition. (Typing plain @kbd{C-g} ++actually adds a @kbd{C-g} keystroke to the macro.) ++ ++@node Loops in Macros, Local Values in Macros, Conditionals in Macros, Keyboard Macros ++@subsection Loops in Keyboard Macros ++ ++@noindent ++@kindex Z < ++@kindex Z > ++@pindex calc-kbd-repeat ++@pindex calc-kbd-end-repeat ++@cindex Looping structures ++@cindex Iterative structures ++The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >} ++(@code{calc-kbd-end-repeat}) commands pop a number from the stack, ++which must be an integer, then repeat the keystrokes between the brackets ++the specified number of times. If the integer is zero or negative, the ++body is skipped altogether. For example, @kbd{1 @key{TAB} Z < 2 * Z >} ++computes two to a nonnegative integer power. First, we push 1 on the ++stack and then swap the integer argument back to the top. The @kbd{Z <} ++pops that argument leaving the 1 back on top of the stack. Then, we ++repeat a multiply-by-two step however many times. ++ ++Once again, the keyboard macro is executed as it is being entered. ++In this case it is especially important to set up reasonable initial ++conditions before making the definition: Suppose the integer 1000 just ++happened to be sitting on the stack before we typed the above definition! ++Another approach is to enter a harmless dummy definition for the macro, ++then go back and edit in the real one with a @kbd{Z E} command. Yet ++another approach is to type the macro as written-out keystroke names ++in a buffer, then use @kbd{C-x * m} (@code{read-kbd-macro}) to read the ++macro. ++ ++@kindex Z / ++@pindex calc-break ++The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out ++of a keyboard macro loop prematurely. It pops an object from the stack; ++if that object is true (a non-zero number), control jumps out of the ++innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues ++after the @kbd{Z >}. If the object is false, the @kbd{Z /} has no ++effect. Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;} ++in the C language. ++ ++@kindex Z ( ++@kindex Z ) ++@pindex calc-kbd-for ++@pindex calc-kbd-end-for ++The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for}) ++commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the ++value of the counter available inside the loop. The general layout is ++@kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}. The @kbd{Z (} ++command pops initial and final values from the stack. It then creates ++a temporary internal counter and initializes it with the value @var{init}. ++The @kbd{Z (} command then repeatedly pushes the counter value onto the ++stack and executes @var{body} and @var{step}, adding @var{step} to the ++counter each time until the loop finishes. ++ ++@cindex Summations (by keyboard macros) ++By default, the loop finishes when the counter becomes greater than (or ++less than) @var{final}, assuming @var{initial} is less than (greater ++than) @var{final}. If @var{initial} is equal to @var{final}, the body ++executes exactly once. The body of the loop always executes at least ++once. For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the ++squares of the integers from 1 to 10, in steps of 1. ++ ++If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is ++forced to use upward-counting conventions. In this case, if @var{initial} ++is greater than @var{final} the body will not be executed at all. ++Note that @var{step} may still be negative in this loop; the prefix ++argument merely constrains the loop-finished test. Likewise, a prefix ++argument of @mathit{-1} forces downward-counting conventions. ++ ++@kindex Z @{ ++@kindex Z @} ++@pindex calc-kbd-loop ++@pindex calc-kbd-end-loop ++The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}} ++(@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and ++@kbd{Z >}, except that they do not pop a count from the stack---they ++effectively create an infinite loop. Every @kbd{Z @{} @dots{} @kbd{Z @}} ++loop ought to include at least one @kbd{Z /} to make sure the loop ++doesn't run forever. (If any error message occurs which causes Emacs ++to beep, the keyboard macro will also be halted; this is a standard ++feature of Emacs. You can also generally press @kbd{C-g} to halt a ++running keyboard macro, although not all versions of Unix support ++this feature.) ++ ++The conditional and looping constructs are not actually tied to ++keyboard macros, but they are most often used in that context. ++For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push ++ten copies of 23 onto the stack. This can be typed ``live'' just ++as easily as in a macro definition. ++ ++@xref{Conditionals in Macros}, for some additional notes about ++conditional and looping commands. ++ ++@node Local Values in Macros, Queries in Macros, Loops in Macros, Keyboard Macros ++@subsection Local Values in Macros ++ ++@noindent ++@cindex Local variables ++@cindex Restoring saved modes ++Keyboard macros sometimes want to operate under known conditions ++without affecting surrounding conditions. For example, a keyboard ++macro may wish to turn on Fraction mode, or set a particular ++precision, independent of the user's normal setting for those ++modes. ++ ++@kindex Z ` ++@kindex Z ' ++@pindex calc-kbd-push ++@pindex calc-kbd-pop ++Macros also sometimes need to use local variables. Assignments to ++local variables inside the macro should not affect any variables ++outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '} ++(@code{calc-kbd-pop}) commands give you both of these capabilities. ++ ++When you type @kbd{Z `} (with a backquote or accent grave character), ++the values of various mode settings are saved away. The ten ``quick'' ++variables @code{q0} through @code{q9} are also saved. When ++you type @w{@kbd{Z '}} (with an apostrophe), these values are restored. ++Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested. ++ ++If a keyboard macro halts due to an error in between a @kbd{Z `} and ++a @kbd{Z '}, the saved values will be restored correctly even though ++the macro never reaches the @kbd{Z '} command. Thus you can use ++@kbd{Z `} and @kbd{Z '} without having to worry about what happens ++in exceptional conditions. ++ ++If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts ++you into a ``recursive edit.'' You can tell you are in a recursive ++edit because there will be extra square brackets in the mode line, ++as in @samp{[(Calculator)]}. These brackets will go away when you ++type the matching @kbd{Z '} command. The modes and quick variables ++will be saved and restored in just the same way as if actual keyboard ++macros were involved. ++ ++The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision ++and binary word size, the angular mode (Deg, Rad, or HMS), the ++simplification mode, Algebraic mode, Symbolic mode, Infinite mode, ++Matrix or Scalar mode, Fraction mode, and the current complex mode ++(Polar or Rectangular). The ten ``quick'' variables' values (or lack ++thereof) are also saved. ++ ++Most mode-setting commands act as toggles, but with a numeric prefix ++they force the mode either on (positive prefix) or off (negative ++or zero prefix). Since you don't know what the environment might ++be when you invoke your macro, it's best to use prefix arguments ++for all mode-setting commands inside the macro. ++ ++In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes ++listed above to their default values. As usual, the matching @kbd{Z '} ++will restore the modes to their settings from before the @kbd{C-u Z `}. ++Also, @w{@kbd{Z `}} with a negative prefix argument resets the algebraic mode ++to its default (off) but leaves the other modes the same as they were ++outside the construct. ++ ++The contents of the stack and trail, values of non-quick variables, and ++other settings such as the language mode and the various display modes, ++are @emph{not} affected by @kbd{Z `} and @kbd{Z '}. ++ ++@node Queries in Macros, , Local Values in Macros, Keyboard Macros ++@subsection Queries in Keyboard Macros ++ ++@c @noindent ++@c @kindex Z = ++@c @pindex calc-kbd-report ++@c The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative ++@c message including the value on the top of the stack. You are prompted ++@c to enter a string. That string, along with the top-of-stack value, ++@c is displayed unless @kbd{m w} (@code{calc-working}) has been used ++@c to turn such messages off. ++ ++@noindent ++@kindex Z # ++@pindex calc-kbd-query ++The @kbd{Z #} (@code{calc-kbd-query}) command prompts for an algebraic ++entry which takes its input from the keyboard, even during macro ++execution. All the normal conventions of algebraic input, including the ++use of @kbd{$} characters, are supported. The prompt message itself is ++taken from the top of the stack, and so must be entered (as a string) ++before the @kbd{Z #} command. (Recall, as a string it can be entered by ++pressing the @kbd{"} key and will appear as a vector when it is put on ++the stack. The prompt message is only put on the stack to provide a ++prompt for the @kbd{Z #} command; it will not play any role in any ++subsequent calculations.) This command allows your keyboard macros to ++accept numbers or formulas as interactive input. ++ ++As an example, ++@kbd{2 @key{RET} "Power: " @key{RET} Z # 3 @key{RET} ^} will prompt for ++input with ``Power: '' in the minibuffer, then return 2 to the provided ++power. (The response to the prompt that's given, 3 in this example, ++will not be part of the macro.) ++ ++@xref{Keyboard Macro Query, , , emacs, the Emacs Manual}, for a description of ++@kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept ++keyboard input during a keyboard macro. In particular, you can use ++@kbd{C-x q} to enter a recursive edit, which allows the user to perform ++any Calculator operations interactively before pressing @kbd{C-M-c} to ++return control to the keyboard macro. ++ ++@node Invocation Macros, Algebraic Definitions, Keyboard Macros, Programming ++@section Invocation Macros ++ ++@kindex C-x * z ++@kindex Z I ++@pindex calc-user-invocation ++@pindex calc-user-define-invocation ++Calc provides one special keyboard macro, called up by @kbd{C-x * z} ++(@code{calc-user-invocation}), that is intended to allow you to define ++your own special way of starting Calc. To define this ``invocation ++macro,'' create the macro in the usual way with @kbd{C-x (} and ++@kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}). ++There is only one invocation macro, so you don't need to type any ++additional letters after @kbd{Z I}. From now on, you can type ++@kbd{C-x * z} at any time to execute your invocation macro. ++ ++For example, suppose you find yourself often grabbing rectangles of ++numbers into Calc and multiplying their columns. You can do this ++by typing @kbd{C-x * r} to grab, and @kbd{V R : *} to multiply columns. ++To make this into an invocation macro, just type @kbd{C-x ( C-x * r ++V R : * C-x )}, then @kbd{Z I}. Then, to multiply a rectangle of data, ++just mark the data in its buffer in the usual way and type @kbd{C-x * z}. ++ ++Invocation macros are treated like regular Emacs keyboard macros; ++all the special features described above for @kbd{Z K}-style macros ++do not apply. @kbd{C-x * z} is just like @kbd{C-x e}, except that it ++uses the macro that was last stored by @kbd{Z I}. (In fact, the ++macro does not even have to have anything to do with Calc!) ++ ++The @kbd{m m} command saves the last invocation macro defined by ++@kbd{Z I} along with all the other Calc mode settings. ++@xref{General Mode Commands}. ++ ++@node Algebraic Definitions, Lisp Definitions, Invocation Macros, Programming ++@section Programming with Formulas ++ ++@noindent ++@kindex Z F ++@pindex calc-user-define-formula ++@cindex Programming with algebraic formulas ++Another way to create a new Calculator command uses algebraic formulas. ++The @kbd{Z F} (@code{calc-user-define-formula}) command stores the ++formula at the top of the stack as the definition for a key. This ++command prompts for five things: The key, the command name, the function ++name, the argument list, and the behavior of the command when given ++non-numeric arguments. ++ ++For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula ++@samp{a + 2*b} onto the stack. We now type @kbd{Z F m} to define this ++formula on the @kbd{z m} key sequence. The next prompt is for a command ++name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form ++for the new command. If you simply press @key{RET}, a default name like ++@code{calc-User-m} will be constructed. In our example, suppose we enter ++@kbd{spam @key{RET}} to define the new command as @code{calc-spam}. ++ ++If you want to give the formula a long-style name only, you can press ++@key{SPC} or @key{RET} when asked which single key to use. For example ++@kbd{Z F @key{RET} spam @key{RET}} defines the new command as ++@kbd{M-x calc-spam}, with no keyboard equivalent. ++ ++The third prompt is for an algebraic function name. The default is to ++use the same name as the command name but without the @samp{calc-} ++prefix. (If this is of the form @samp{User-m}, the hyphen is removed so ++it won't be taken for a minus sign in algebraic formulas.) ++This is the name you will use if you want to enter your ++new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}. ++Then the new function can be invoked by pushing two numbers on the ++stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic ++formula @samp{yow(x,y)}. ++ ++The fourth prompt is for the function's argument list. This is used to ++associate values on the stack with the variables that appear in the formula. ++The default is a list of all variables which appear in the formula, sorted ++into alphabetical order. In our case, the default would be @samp{(a b)}. ++This means that, when the user types @kbd{z m}, the Calculator will remove ++two numbers from the stack, substitute these numbers for @samp{a} and ++@samp{b} (respectively) in the formula, then simplify the formula and ++push the result on the stack. In other words, @kbd{10 @key{RET} 100 z m} ++would replace the 10 and 100 on the stack with the number 210, which is ++@expr{a + 2 b} with @expr{a=10} and @expr{b=100}. Likewise, the formula ++@samp{yow(10, 100)} will be evaluated by substituting @expr{a=10} and ++@expr{b=100} in the definition. ++ ++You can rearrange the order of the names before pressing @key{RET} to ++control which stack positions go to which variables in the formula. If ++you remove a variable from the argument list, that variable will be left ++in symbolic form by the command. Thus using an argument list of @samp{(b)} ++for our function would cause @kbd{10 z m} to replace the 10 on the stack ++with the formula @samp{a + 20}. If we had used an argument list of ++@samp{(b a)}, the result with inputs 10 and 100 would have been 120. ++ ++You can also put a nameless function on the stack instead of just a ++formula, as in @samp{}. @xref{Specifying Operators}. ++In this example, the command will be defined by the formula @samp{a + 2 b} ++using the argument list @samp{(a b)}. ++ ++The final prompt is a y-or-n question concerning what to do if symbolic ++arguments are given to your function. If you answer @kbd{y}, then ++executing @kbd{z m} (using the original argument list @samp{(a b)}) with ++arguments @expr{10} and @expr{x} will leave the function in symbolic ++form, i.e., @samp{yow(10,x)}. On the other hand, if you answer @kbd{n}, ++then the formula will always be expanded, even for non-constant ++arguments: @samp{10 + 2 x}. If you never plan to feed algebraic ++formulas to your new function, it doesn't matter how you answer this ++question. ++ ++If you answered @kbd{y} to this question you can still cause a function ++call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}). ++Also, Calc will expand the function if necessary when you take a ++derivative or integral or solve an equation involving the function. ++ ++@kindex Z G ++@pindex calc-get-user-defn ++Once you have defined a formula on a key, you can retrieve this formula ++with the @kbd{Z G} (@code{calc-user-define-get-defn}) command. Press a ++key, and this command pushes the formula that was used to define that ++key onto the stack. Actually, it pushes a nameless function that ++specifies both the argument list and the defining formula. You will get ++an error message if the key is undefined, or if the key was not defined ++by a @kbd{Z F} command. ++ ++The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has ++been defined by a formula uses a variant of the @code{calc-edit} command ++to edit the defining formula. Press @kbd{C-c C-c} to finish editing and ++store the new formula back in the definition, or kill the buffer with ++@kbd{C-x k} to ++cancel the edit. (The argument list and other properties of the ++definition are unchanged; to adjust the argument list, you can use ++@kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and ++then re-execute the @kbd{Z F} command.) ++ ++As usual, the @kbd{Z P} command records your definition permanently. ++In this case it will permanently record all three of the relevant ++definitions: the key, the command, and the function. ++ ++You may find it useful to turn off the default simplifications with ++@kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be ++used as a function definition. For example, the formula @samp{deriv(a^2,v)} ++which might be used to define a new function @samp{dsqr(a,v)} will be ++``simplified'' to 0 immediately upon entry since @code{deriv} considers ++@expr{a} to be constant with respect to @expr{v}. Turning off ++default simplifications cures this problem: The definition will be stored ++in symbolic form without ever activating the @code{deriv} function. Press ++@kbd{m D} to turn the default simplifications back on afterwards. ++ ++@node Lisp Definitions, , Algebraic Definitions, Programming ++@section Programming with Lisp ++ ++@noindent ++The Calculator can be programmed quite extensively in Lisp. All you ++do is write a normal Lisp function definition, but with @code{defmath} ++in place of @code{defun}. This has the same form as @code{defun}, but it ++automagically replaces calls to standard Lisp functions like @code{+} and ++@code{zerop} with calls to the corresponding functions in Calc's own library. ++Thus you can write natural-looking Lisp code which operates on all of the ++standard Calculator data types. You can then use @kbd{Z D} if you wish to ++bind your new command to a @kbd{z}-prefix key sequence. The @kbd{Z E} command ++will not edit a Lisp-based definition. ++ ++Emacs Lisp is described in the GNU Emacs Lisp Reference Manual. This section ++assumes a familiarity with Lisp programming concepts; if you do not know ++Lisp, you may find keyboard macros or rewrite rules to be an easier way ++to program the Calculator. ++ ++This section first discusses ways to write commands, functions, or ++small programs to be executed inside of Calc. Then it discusses how ++your own separate programs are able to call Calc from the outside. ++Finally, there is a list of internal Calc functions and data structures ++for the true Lisp enthusiast. ++ ++@menu ++* Defining Functions:: ++* Defining Simple Commands:: ++* Defining Stack Commands:: ++* Argument Qualifiers:: ++* Example Definitions:: ++ ++* Calling Calc from Your Programs:: ++* Internals:: ++@end menu ++ ++@node Defining Functions, Defining Simple Commands, Lisp Definitions, Lisp Definitions ++@subsection Defining New Functions ++ ++@noindent ++@findex defmath ++The @code{defmath} function (actually a Lisp macro) is like @code{defun} ++except that code in the body of the definition can make use of the full ++range of Calculator data types. The prefix @samp{calcFunc-} is added ++to the specified name to get the actual Lisp function name. As a simple ++example, ++ ++@example ++(defmath myfact (n) ++ (if (> n 0) ++ (* n (myfact (1- n))) ++ 1)) ++@end example ++ ++@noindent ++This actually expands to the code, ++ ++@example ++(defun calcFunc-myfact (n) ++ (if (math-posp n) ++ (math-mul n (calcFunc-myfact (math-add n -1))) ++ 1)) ++@end example ++ ++@noindent ++This function can be used in algebraic expressions, e.g., @samp{myfact(5)}. ++ ++The @samp{myfact} function as it is defined above has the bug that an ++expression @samp{myfact(a+b)} will be simplified to 1 because the ++formula @samp{a+b} is not considered to be @code{posp}. A robust ++factorial function would be written along the following lines: ++ ++@smallexample ++(defmath myfact (n) ++ (if (> n 0) ++ (* n (myfact (1- n))) ++ (if (= n 0) ++ 1 ++ nil))) ; this could be simplified as: (and (= n 0) 1) ++@end smallexample ++ ++If a function returns @code{nil}, it is left unsimplified by the Calculator ++(except that its arguments will be simplified). Thus, @samp{myfact(a+1+2)} ++will be simplified to @samp{myfact(a+3)} but no further. Beware that every ++time the Calculator reexamines this formula it will attempt to resimplify ++it, so your function ought to detect the returning-@code{nil} case as ++efficiently as possible. ++ ++The following standard Lisp functions are treated by @code{defmath}: ++@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or ++@code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=}, ++@code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor}, ++@code{logandc2}, @code{lognot}. Also, @code{~=} is an abbreviation for ++@code{math-nearly-equal}, which is useful in implementing Taylor series. ++ ++For other functions @var{func}, if a function by the name ++@samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the ++name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself ++is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is ++used on the assumption that this is a to-be-defined math function. Also, if ++the function name is quoted as in @samp{('integerp a)} the function name is ++always used exactly as written (but not quoted). ++ ++Variable names have @samp{var-} prepended to them unless they appear in ++the function's argument list or in an enclosing @code{let}, @code{let*}, ++@code{for}, or @code{foreach} form, ++or their names already contain a @samp{-} character. Thus a reference to ++@samp{foo} is the same as a reference to @samp{var-foo}. ++ ++A few other Lisp extensions are available in @code{defmath} definitions: ++ ++@itemize @bullet ++@item ++The @code{elt} function accepts any number of index variables. ++Note that Calc vectors are stored as Lisp lists whose first ++element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields ++the second element of vector @code{v}, and @samp{(elt m i j)} ++yields one element of a Calc matrix. ++ ++@item ++The @code{setq} function has been extended to act like the Common ++Lisp @code{setf} function. (The name @code{setf} is recognized as ++a synonym of @code{setq}.) Specifically, the first argument of ++@code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form, ++in which case the effect is to store into the specified ++element of a list. Thus, @samp{(setq (elt m i j) x)} stores @expr{x} ++into one element of a matrix. ++ ++@item ++A @code{for} looping construct is available. For example, ++@samp{(for ((i 0 10)) body)} executes @code{body} once for each ++binding of @expr{i} from zero to 10. This is like a @code{let} ++form in that @expr{i} is temporarily bound to the loop count ++without disturbing its value outside the @code{for} construct. ++Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)}, ++are also available. For each value of @expr{i} from zero to 10, ++@expr{j} counts from 0 to @expr{i-1} in steps of two. Note that ++@code{for} has the same general outline as @code{let*}, except ++that each element of the header is a list of three or four ++things, not just two. ++ ++@item ++The @code{foreach} construct loops over elements of a list. ++For example, @samp{(foreach ((x (cdr v))) body)} executes ++@code{body} with @expr{x} bound to each element of Calc vector ++@expr{v} in turn. The purpose of @code{cdr} here is to skip over ++the initial @code{vec} symbol in the vector. ++ ++@item ++The @code{break} function breaks out of the innermost enclosing ++@code{while}, @code{for}, or @code{foreach} loop. If given a ++value, as in @samp{(break x)}, this value is returned by the ++loop. (Lisp loops otherwise always return @code{nil}.) ++ ++@item ++The @code{return} function prematurely returns from the enclosing ++function. For example, @samp{(return (+ x y))} returns @expr{x+y} ++as the value of a function. You can use @code{return} anywhere ++inside the body of the function. ++@end itemize ++ ++Non-integer numbers (and extremely large integers) cannot be included ++directly into a @code{defmath} definition. This is because the Lisp ++reader will fail to parse them long before @code{defmath} ever gets control. ++Instead, use the notation, @samp{:"3.1415"}. In fact, any algebraic ++formula can go between the quotes. For example, ++ ++@smallexample ++(defmath sqexp (x) ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5) ++ (and (numberp x) ++ (exp :"x * 0.5"))) ++@end smallexample ++ ++expands to ++ ++@smallexample ++(defun calcFunc-sqexp (x) ++ (and (math-numberp x) ++ (calcFunc-exp (math-mul x '(float 5 -1))))) ++@end smallexample ++ ++Note the use of @code{numberp} as a guard to ensure that the argument is ++a number first, returning @code{nil} if not. The exponential function ++could itself have been included in the expression, if we had preferred: ++@samp{:"exp(x * 0.5)"}. As another example, the multiplication-and-recursion ++step of @code{myfact} could have been written ++ ++@example ++:"n * myfact(n-1)" ++@end example ++ ++A good place to put your @code{defmath} commands is your Calc init file ++(the file given by @code{calc-settings-file}, typically ++@file{~/.calc.el}), which will not be loaded until Calc starts. ++If a file named @file{.emacs} exists in your home directory, Emacs reads ++and executes the Lisp forms in this file as it starts up. While it may ++seem reasonable to put your favorite @code{defmath} commands there, ++this has the unfortunate side-effect that parts of the Calculator must be ++loaded in to process the @code{defmath} commands whether or not you will ++actually use the Calculator! If you want to put the @code{defmath} ++commands there (for example, if you redefine @code{calc-settings-file} ++to be @file{.emacs}), a better effect can be had by writing ++ ++@example ++(put 'calc-define 'thing '(progn ++ (defmath ... ) ++ (defmath ... ) ++)) ++@end example ++ ++@noindent ++@vindex calc-define ++The @code{put} function adds a @dfn{property} to a symbol. Each Lisp ++symbol has a list of properties associated with it. Here we add a ++property with a name of @code{thing} and a @samp{(progn ...)} form as ++its value. When Calc starts up, and at the start of every Calc command, ++the property list for the symbol @code{calc-define} is checked and the ++values of any properties found are evaluated as Lisp forms. The ++properties are removed as they are evaluated. The property names ++(like @code{thing}) are not used; you should choose something like the ++name of your project so as not to conflict with other properties. ++ ++The net effect is that you can put the above code in your @file{.emacs} ++file and it will not be executed until Calc is loaded. Or, you can put ++that same code in another file which you load by hand either before or ++after Calc itself is loaded. ++ ++The properties of @code{calc-define} are evaluated in the same order ++that they were added. They can assume that the Calc modules @file{calc.el}, ++@file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and ++that the @samp{*Calculator*} buffer will be the current buffer. ++ ++If your @code{calc-define} property only defines algebraic functions, ++you can be sure that it will have been evaluated before Calc tries to ++call your function, even if the file defining the property is loaded ++after Calc is loaded. But if the property defines commands or key ++sequences, it may not be evaluated soon enough. (Suppose it defines the ++new command @code{tweak-calc}; the user can load your file, then type ++@kbd{M-x tweak-calc} before Calc has had chance to do anything.) To ++protect against this situation, you can put ++ ++@example ++(run-hooks 'calc-check-defines) ++@end example ++ ++@findex calc-check-defines ++@noindent ++at the end of your file. The @code{calc-check-defines} function is what ++looks for and evaluates properties on @code{calc-define}; @code{run-hooks} ++has the advantage that it is quietly ignored if @code{calc-check-defines} ++is not yet defined because Calc has not yet been loaded. ++ ++Examples of things that ought to be enclosed in a @code{calc-define} ++property are @code{defmath} calls, @code{define-key} calls that modify ++the Calc key map, and any calls that redefine things defined inside Calc. ++Ordinary @code{defun}s need not be enclosed with @code{calc-define}. ++ ++@node Defining Simple Commands, Defining Stack Commands, Defining Functions, Lisp Definitions ++@subsection Defining New Simple Commands ++ ++@noindent ++@findex interactive ++If a @code{defmath} form contains an @code{interactive} clause, it defines ++a Calculator command. Actually such a @code{defmath} results in @emph{two} ++function definitions: One, a @samp{calcFunc-} function as was just described, ++with the @code{interactive} clause removed. Two, a @samp{calc-} function ++with a suitable @code{interactive} clause and some sort of wrapper to make ++the command work in the Calc environment. ++ ++In the simple case, the @code{interactive} clause has the same form as ++for normal Emacs Lisp commands: ++ ++@smallexample ++(defmath increase-precision (delta) ++ "Increase precision by DELTA." ; This is the "documentation string" ++ (interactive "p") ; Register this as a M-x-able command ++ (setq calc-internal-prec (+ calc-internal-prec delta))) ++@end smallexample ++ ++This expands to the pair of definitions, ++ ++@smallexample ++(defun calc-increase-precision (delta) ++ "Increase precision by DELTA." ++ (interactive "p") ++ (calc-wrapper ++ (setq calc-internal-prec (math-add calc-internal-prec delta)))) ++ ++(defun calcFunc-increase-precision (delta) ++ "Increase precision by DELTA." ++ (setq calc-internal-prec (math-add calc-internal-prec delta))) ++@end smallexample ++ ++@noindent ++where in this case the latter function would never really be used! Note ++that since the Calculator stores small integers as plain Lisp integers, ++the @code{math-add} function will work just as well as the native ++@code{+} even when the intent is to operate on native Lisp integers. ++ ++@findex calc-wrapper ++The @samp{calc-wrapper} call invokes a macro which surrounds the body of ++the function with code that looks roughly like this: ++ ++@smallexample ++(let ((calc-command-flags nil)) ++ (unwind-protect ++ (save-excursion ++ (calc-select-buffer) ++ @emph{body of function} ++ @emph{renumber stack} ++ @emph{clear} Working @emph{message}) ++ @emph{realign cursor and window} ++ @emph{clear Inverse, Hyperbolic, and Keep Args flags} ++ @emph{update Emacs mode line})) ++@end smallexample ++ ++@findex calc-select-buffer ++The @code{calc-select-buffer} function selects the @samp{*Calculator*} ++buffer if necessary, say, because the command was invoked from inside ++the @samp{*Calc Trail*} window. ++ ++@findex calc-set-command-flag ++You can call, for example, @code{(calc-set-command-flag 'no-align)} to ++set the above-mentioned command flags. Calc routines recognize the ++following command flags: ++ ++@table @code ++@item renum-stack ++Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered ++after this command completes. This is set by routines like ++@code{calc-push}. ++ ++@item clear-message ++Calc should call @samp{(message "")} if this command completes normally ++(to clear a ``Working@dots{}'' message out of the echo area). ++ ++@item no-align ++Do not move the cursor back to the @samp{.} top-of-stack marker. ++ ++@item position-point ++Use the variables @code{calc-position-point-line} and ++@code{calc-position-point-column} to position the cursor after ++this command finishes. ++ ++@item keep-flags ++Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag}, ++and @code{calc-keep-args-flag} at the end of this command. ++ ++@item do-edit ++Switch to buffer @samp{*Calc Edit*} after this command. ++ ++@item hold-trail ++Do not move trail pointer to end of trail when something is recorded ++there. ++@end table ++ ++@kindex Y ++@kindex Y ? ++@vindex calc-Y-help-msgs ++Calc reserves a special prefix key, shift-@kbd{Y}, for user-written ++extensions to Calc. There are no built-in commands that work with ++this prefix key; you must call @code{define-key} from Lisp (probably ++from inside a @code{calc-define} property) to add to it. Initially only ++@kbd{Y ?} is defined; it takes help messages from a list of strings ++(initially @code{nil}) in the variable @code{calc-Y-help-msgs}. All ++other undefined keys except for @kbd{Y} are reserved for use by ++future versions of Calc. ++ ++If you are writing a Calc enhancement which you expect to give to ++others, it is best to minimize the number of @kbd{Y}-key sequences ++you use. In fact, if you have more than one key sequence you should ++consider defining three-key sequences with a @kbd{Y}, then a key that ++stands for your package, then a third key for the particular command ++within your package. ++ ++Users may wish to install several Calc enhancements, and it is possible ++that several enhancements will choose to use the same key. In the ++example below, a variable @code{inc-prec-base-key} has been defined ++to contain the key that identifies the @code{inc-prec} package. Its ++value is initially @code{"P"}, but a user can change this variable ++if necessary without having to modify the file. ++ ++Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I} ++command that increases the precision, and a @kbd{Y P D} command that ++decreases the precision. ++ ++@smallexample ++;;; Increase and decrease Calc precision. Dave Gillespie, 5/31/91. ++;; (Include copyright or copyleft stuff here.) ++ ++(defvar inc-prec-base-key "P" ++ "Base key for inc-prec.el commands.") ++ ++(put 'calc-define 'inc-prec '(progn ++ ++(define-key calc-mode-map (format "Y%sI" inc-prec-base-key) ++ 'increase-precision) ++(define-key calc-mode-map (format "Y%sD" inc-prec-base-key) ++ 'decrease-precision) ++ ++(setq calc-Y-help-msgs ++ (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key) ++ calc-Y-help-msgs)) ++ ++(defmath increase-precision (delta) ++ "Increase precision by DELTA." ++ (interactive "p") ++ (setq calc-internal-prec (+ calc-internal-prec delta))) ++ ++(defmath decrease-precision (delta) ++ "Decrease precision by DELTA." ++ (interactive "p") ++ (setq calc-internal-prec (- calc-internal-prec delta))) ++ ++)) ; end of calc-define property ++ ++(run-hooks 'calc-check-defines) ++@end smallexample ++ ++@node Defining Stack Commands, Argument Qualifiers, Defining Simple Commands, Lisp Definitions ++@subsection Defining New Stack-Based Commands ++ ++@noindent ++To define a new computational command which takes and/or leaves arguments ++on the stack, a special form of @code{interactive} clause is used. ++ ++@example ++(interactive @var{num} @var{tag}) ++@end example ++ ++@noindent ++where @var{num} is an integer, and @var{tag} is a string. The effect is ++to pop @var{num} values off the stack, resimplify them by calling ++@code{calc-normalize}, and hand them to your function according to the ++function's argument list. Your function may include @code{&optional} and ++@code{&rest} parameters, so long as calling the function with @var{num} ++parameters is valid. ++ ++Your function must return either a number or a formula in a form ++acceptable to Calc, or a list of such numbers or formulas. These value(s) ++are pushed onto the stack when the function completes. They are also ++recorded in the Calc Trail buffer on a line beginning with @var{tag}, ++a string of (normally) four characters or less. If you omit @var{tag} ++or use @code{nil} as a tag, the result is not recorded in the trail. ++ ++As an example, the definition ++ ++@smallexample ++(defmath myfact (n) ++ "Compute the factorial of the integer at the top of the stack." ++ (interactive 1 "fact") ++ (if (> n 0) ++ (* n (myfact (1- n))) ++ (and (= n 0) 1))) ++@end smallexample ++ ++@noindent ++is a version of the factorial function shown previously which can be used ++as a command as well as an algebraic function. It expands to ++ ++@smallexample ++(defun calc-myfact () ++ "Compute the factorial of the integer at the top of the stack." ++ (interactive) ++ (calc-slow-wrapper ++ (calc-enter-result 1 "fact" ++ (cons 'calcFunc-myfact (calc-top-list-n 1))))) ++ ++(defun calcFunc-myfact (n) ++ "Compute the factorial of the integer at the top of the stack." ++ (if (math-posp n) ++ (math-mul n (calcFunc-myfact (math-add n -1))) ++ (and (math-zerop n) 1))) ++@end smallexample ++ ++@findex calc-slow-wrapper ++The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper} ++that automatically puts up a @samp{Working...} message before the ++computation begins. (This message can be turned off by the user ++with an @kbd{m w} (@code{calc-working}) command.) ++ ++@findex calc-top-list-n ++The @code{calc-top-list-n} function returns a list of the specified number ++of values from the top of the stack. It resimplifies each value by ++calling @code{calc-normalize}. If its argument is zero it returns an ++empty list. It does not actually remove these values from the stack. ++ ++@findex calc-enter-result ++The @code{calc-enter-result} function takes an integer @var{num} and string ++@var{tag} as described above, plus a third argument which is either a ++Calculator data object or a list of such objects. These objects are ++resimplified and pushed onto the stack after popping the specified number ++of values from the stack. If @var{tag} is non-@code{nil}, the values ++being pushed are also recorded in the trail. ++ ++Note that if @code{calcFunc-myfact} returns @code{nil} this represents ++``leave the function in symbolic form.'' To return an actual empty list, ++in the sense that @code{calc-enter-result} will push zero elements back ++onto the stack, you should return the special value @samp{'(nil)}, a list ++containing the single symbol @code{nil}. ++ ++The @code{interactive} declaration can actually contain a limited ++Emacs-style code string as well which comes just before @var{num} and ++@var{tag}. Currently the only Emacs code supported is @samp{"p"}, as in ++ ++@example ++(defmath foo (a b &optional c) ++ (interactive "p" 2 "foo") ++ @var{body}) ++@end example ++ ++In this example, the command @code{calc-foo} will evaluate the expression ++@samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if ++executed with a numeric prefix argument of @expr{n}. ++ ++The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"} ++code as used with @code{defun}). It uses the numeric prefix argument as the ++number of objects to remove from the stack and pass to the function. ++In this case, the integer @var{num} serves as a default number of ++arguments to be used when no prefix is supplied. ++ ++@node Argument Qualifiers, Example Definitions, Defining Stack Commands, Lisp Definitions ++@subsection Argument Qualifiers ++ ++@noindent ++Anywhere a parameter name can appear in the parameter list you can also use ++an @dfn{argument qualifier}. Thus the general form of a definition is: ++ ++@example ++(defmath @var{name} (@var{param} @var{param...} ++ &optional @var{param} @var{param...} ++ &rest @var{param}) ++ @var{body}) ++@end example ++ ++@noindent ++where each @var{param} is either a symbol or a list of the form ++ ++@example ++(@var{qual} @var{param}) ++@end example ++ ++The following qualifiers are recognized: ++ ++@table @samp ++@item complete ++@findex complete ++The argument must not be an incomplete vector, interval, or complex number. ++(This is rarely needed since the Calculator itself will never call your ++function with an incomplete argument. But there is nothing stopping your ++own Lisp code from calling your function with an incomplete argument.) ++ ++@item integer ++@findex integer ++The argument must be an integer. If it is an integer-valued float ++it will be accepted but converted to integer form. Non-integers and ++formulas are rejected. ++ ++@item natnum ++@findex natnum ++Like @samp{integer}, but the argument must be non-negative. ++ ++@item fixnum ++@findex fixnum ++Like @samp{integer}, but the argument must fit into a native Lisp integer, ++which on most systems means less than 2^23 in absolute value. The ++argument is converted into Lisp-integer form if necessary. ++ ++@item float ++@findex float ++The argument is converted to floating-point format if it is a number or ++vector. If it is a formula it is left alone. (The argument is never ++actually rejected by this qualifier.) ++ ++@item @var{pred} ++The argument must satisfy predicate @var{pred}, which is one of the ++standard Calculator predicates. @xref{Predicates}. ++ ++@item not-@var{pred} ++The argument must @emph{not} satisfy predicate @var{pred}. ++@end table ++ ++For example, ++ ++@example ++(defmath foo (a (constp (not-matrixp b)) &optional (float c) ++ &rest (integer d)) ++ @var{body}) ++@end example ++ ++@noindent ++expands to ++ ++@example ++(defun calcFunc-foo (a b &optional c &rest d) ++ (and (math-matrixp b) ++ (math-reject-arg b 'not-matrixp)) ++ (or (math-constp b) ++ (math-reject-arg b 'constp)) ++ (and c (setq c (math-check-float c))) ++ (setq d (mapcar 'math-check-integer d)) ++ @var{body}) ++@end example ++ ++@noindent ++which performs the necessary checks and conversions before executing the ++body of the function. ++ ++@node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions ++@subsection Example Definitions ++ ++@noindent ++This section includes some Lisp programming examples on a larger scale. ++These programs make use of some of the Calculator's internal functions; ++@pxref{Internals}. ++ ++@menu ++* Bit Counting Example:: ++* Sine Example:: ++@end menu ++ ++@node Bit Counting Example, Sine Example, Example Definitions, Example Definitions ++@subsubsection Bit-Counting ++ ++@noindent ++@ignore ++@starindex ++@end ignore ++@tindex bcount ++Calc does not include a built-in function for counting the number of ++``one'' bits in a binary integer. It's easy to invent one using @kbd{b u} ++to convert the integer to a set, and @kbd{V #} to count the elements of ++that set; let's write a function that counts the bits without having to ++create an intermediate set. ++ ++@smallexample ++(defmath bcount ((natnum n)) ++ (interactive 1 "bcnt") ++ (let ((count 0)) ++ (while (> n 0) ++ (if (oddp n) ++ (setq count (1+ count))) ++ (setq n (lsh n -1))) ++ count)) ++@end smallexample ++ ++@noindent ++When this is expanded by @code{defmath}, it will become the following ++Emacs Lisp function: ++ ++@smallexample ++(defun calcFunc-bcount (n) ++ (setq n (math-check-natnum n)) ++ (let ((count 0)) ++ (while (math-posp n) ++ (if (math-oddp n) ++ (setq count (math-add count 1))) ++ (setq n (calcFunc-lsh n -1))) ++ count)) ++@end smallexample ++ ++If the input numbers are large, this function involves a fair amount ++of arithmetic. A binary right shift is essentially a division by two; ++recall that Calc stores integers in decimal form so bit shifts must ++involve actual division. ++ ++To gain a bit more efficiency, we could divide the integer into ++@var{n}-bit chunks, each of which can be handled quickly because ++they fit into Lisp integers. It turns out that Calc's arithmetic ++routines are especially fast when dividing by an integer less than ++1000, so we can set @var{n = 9} bits and use repeated division by 512: ++ ++@smallexample ++(defmath bcount ((natnum n)) ++ (interactive 1 "bcnt") ++ (let ((count 0)) ++ (while (not (fixnump n)) ++ (let ((qr (idivmod n 512))) ++ (setq count (+ count (bcount-fixnum (cdr qr))) ++ n (car qr)))) ++ (+ count (bcount-fixnum n)))) ++ ++(defun bcount-fixnum (n) ++ (let ((count 0)) ++ (while (> n 0) ++ (setq count (+ count (logand n 1)) ++ n (lsh n -1))) ++ count)) ++@end smallexample ++ ++@noindent ++Note that the second function uses @code{defun}, not @code{defmath}. ++Because this function deals only with native Lisp integers (``fixnums''), ++it can use the actual Emacs @code{+} and related functions rather ++than the slower but more general Calc equivalents which @code{defmath} ++uses. ++ ++The @code{idivmod} function does an integer division, returning both ++the quotient and the remainder at once. Again, note that while it ++might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are ++more efficient ways to split off the bottom nine bits of @code{n}, ++actually they are less efficient because each operation is really ++a division by 512 in disguise; @code{idivmod} allows us to do the ++same thing with a single division by 512. ++ ++@node Sine Example, , Bit Counting Example, Example Definitions ++@subsubsection The Sine Function ++ ++@noindent ++@ignore ++@starindex ++@end ignore ++@tindex mysin ++A somewhat limited sine function could be defined as follows, using the ++well-known Taylor series expansion for ++@texline @math{\sin x}: ++@infoline @samp{sin(x)}: ++ ++@smallexample ++(defmath mysin ((float (anglep x))) ++ (interactive 1 "mysn") ++ (setq x (to-radians x)) ; Convert from current angular mode. ++ (let ((sum x) ; Initial term of Taylor expansion of sin. ++ newsum ++ (nfact 1) ; "nfact" equals "n" factorial at all times. ++ (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2. ++ (for ((n 3 100 2)) ; Upper limit of 100 is a good precaution. ++ (working "mysin" sum) ; Display "Working" message, if enabled. ++ (setq nfact (* nfact (1- n) n) ++ x (* x xnegsqr) ++ newsum (+ sum (/ x nfact))) ++ (if (~= newsum sum) ; If newsum is "nearly equal to" sum, ++ (break)) ; then we are done. ++ (setq sum newsum)) ++ sum)) ++@end smallexample ++ ++The actual @code{sin} function in Calc works by first reducing the problem ++to a sine or cosine of a nonnegative number less than @cpiover{4}. This ++ensures that the Taylor series will converge quickly. Also, the calculation ++is carried out with two extra digits of precision to guard against cumulative ++round-off in @samp{sum}. Finally, complex arguments are allowed and handled ++by a separate algorithm. ++ ++@smallexample ++(defmath mysin ((float (scalarp x))) ++ (interactive 1 "mysn") ++ (setq x (to-radians x)) ; Convert from current angular mode. ++ (with-extra-prec 2 ; Evaluate with extra precision. ++ (cond ((complexp x) ++ (mysin-complex x)) ++ ((< x 0) ++ (- (mysin-raw (- x))) ; Always call mysin-raw with x >= 0. ++ (t (mysin-raw x)))))) ++ ++(defmath mysin-raw (x) ++ (cond ((>= x 7) ++ (mysin-raw (% x (two-pi)))) ; Now x < 7. ++ ((> x (pi-over-2)) ++ (- (mysin-raw (- x (pi))))) ; Now -pi/2 <= x <= pi/2. ++ ((> x (pi-over-4)) ++ (mycos-raw (- x (pi-over-2)))) ; Now -pi/2 <= x <= pi/4. ++ ((< x (- (pi-over-4))) ++ (- (mycos-raw (+ x (pi-over-2))))) ; Now -pi/4 <= x <= pi/4, ++ (t (mysin-series x)))) ; so the series will be efficient. ++@end smallexample ++ ++@noindent ++where @code{mysin-complex} is an appropriate function to handle complex ++numbers, @code{mysin-series} is the routine to compute the sine Taylor ++series as before, and @code{mycos-raw} is a function analogous to ++@code{mysin-raw} for cosines. ++ ++The strategy is to ensure that @expr{x} is nonnegative before calling ++@code{mysin-raw}. This function then recursively reduces its argument ++to a suitable range, namely, plus-or-minus @cpiover{4}. Note that each ++test, and particularly the first comparison against 7, is designed so ++that small roundoff errors cannot produce an infinite loop. (Suppose ++we compared with @samp{(two-pi)} instead; if due to roundoff problems ++the modulo operator ever returned @samp{(two-pi)} exactly, an infinite ++recursion could result!) We use modulo only for arguments that will ++clearly get reduced, knowing that the next rule will catch any reductions ++that this rule misses. ++ ++If a program is being written for general use, it is important to code ++it carefully as shown in this second example. For quick-and-dirty programs, ++when you know that your own use of the sine function will never encounter ++a large argument, a simpler program like the first one shown is fine. ++ ++@node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions ++@subsection Calling Calc from Your Lisp Programs ++ ++@noindent ++A later section (@pxref{Internals}) gives a full description of ++Calc's internal Lisp functions. It's not hard to call Calc from ++inside your programs, but the number of these functions can be daunting. ++So Calc provides one special ``programmer-friendly'' function called ++@code{calc-eval} that can be made to do just about everything you ++need. It's not as fast as the low-level Calc functions, but it's ++much simpler to use! ++ ++It may seem that @code{calc-eval} itself has a daunting number of ++options, but they all stem from one simple operation. ++ ++In its simplest manifestation, @samp{(calc-eval "1+2")} parses the ++string @code{"1+2"} as if it were a Calc algebraic entry and returns ++the result formatted as a string: @code{"3"}. ++ ++Since @code{calc-eval} is on the list of recommended @code{autoload} ++functions, you don't need to make any special preparations to load ++Calc before calling @code{calc-eval} the first time. Calc will be ++loaded and initialized for you. ++ ++All the Calc modes that are currently in effect will be used when ++evaluating the expression and formatting the result. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Additional Arguments to @code{calc-eval} ++ ++@noindent ++If the input string parses to a list of expressions, Calc returns ++the results separated by @code{", "}. You can specify a different ++separator by giving a second string argument to @code{calc-eval}: ++@samp{(calc-eval "1+2,3+4" ";")} returns @code{"3;7"}. ++ ++The ``separator'' can also be any of several Lisp symbols which ++request other behaviors from @code{calc-eval}. These are discussed ++one by one below. ++ ++You can give additional arguments to be substituted for ++@samp{$}, @samp{$$}, and so on in the main expression. For ++example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the ++expression @code{"7/(1+1)"} to yield the result @code{"3.5"} ++(assuming Fraction mode is not in effect). Note the @code{nil} ++used as a placeholder for the item-separator argument. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Error Handling ++ ++@noindent ++If @code{calc-eval} encounters an error, it returns a list containing ++the character position of the error, plus a suitable message as a ++string. Note that @samp{1 / 0} is @emph{not} an error by Calc's ++standards; it simply returns the string @code{"1 / 0"} which is the ++division left in symbolic form. But @samp{(calc-eval "1/")} will ++return the list @samp{(2 "Expected a number")}. ++ ++If you bind the variable @code{calc-eval-error} to @code{t} ++using a @code{let} form surrounding the call to @code{calc-eval}, ++errors instead call the Emacs @code{error} function which aborts ++to the Emacs command loop with a beep and an error message. ++ ++If you bind this variable to the symbol @code{string}, error messages ++are returned as strings instead of lists. The character position is ++ignored. ++ ++As a courtesy to other Lisp code which may be using Calc, be sure ++to bind @code{calc-eval-error} using @code{let} rather than changing ++it permanently with @code{setq}. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Numbers Only ++ ++@noindent ++Sometimes it is preferable to treat @samp{1 / 0} as an error ++rather than returning a symbolic result. If you pass the symbol ++@code{num} as the second argument to @code{calc-eval}, results ++that are not constants are treated as errors. The error message ++reported is the first @code{calc-why} message if there is one, ++or otherwise ``Number expected.'' ++ ++A result is ``constant'' if it is a number, vector, or other ++object that does not include variables or function calls. If it ++is a vector, the components must themselves be constants. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Default Modes ++ ++@noindent ++If the first argument to @code{calc-eval} is a list whose first ++element is a formula string, then @code{calc-eval} sets all the ++various Calc modes to their default values while the formula is ++evaluated and formatted. For example, the precision is set to 12 ++digits, digit grouping is turned off, and the Normal language ++mode is used. ++ ++This same principle applies to the other options discussed below. ++If the first argument would normally be @var{x}, then it can also ++be the list @samp{(@var{x})} to use the default mode settings. ++ ++If there are other elements in the list, they are taken as ++variable-name/value pairs which override the default mode ++settings. Look at the documentation at the front of the ++@file{calc.el} file to find the names of the Lisp variables for ++the various modes. The mode settings are restored to their ++original values when @code{calc-eval} is done. ++ ++For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)} ++computes the sum of two numbers, requiring a numeric result, and ++using default mode settings except that the precision is 8 instead ++of the default of 12. ++ ++It's usually best to use this form of @code{calc-eval} unless your ++program actually considers the interaction with Calc's mode settings ++to be a feature. This will avoid all sorts of potential ``gotchas''; ++consider what happens with @samp{(calc-eval "sqrt(2)" 'num)} ++when the user has left Calc in Symbolic mode or No-Simplify mode. ++ ++As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")} ++checks if the number in string @expr{a} is less than the one in ++string @expr{b}. Without using a list, the integer 1 might ++come out in a variety of formats which would be hard to test for ++conveniently: @code{"1"}, @code{"8#1"}, @code{"00001"}. (But ++see ``Predicates'' mode, below.) ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Raw Numbers ++ ++@noindent ++Normally all input and output for @code{calc-eval} is done with strings. ++You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)} ++in place of @samp{(+ a b)}, but this is very inefficient since the ++numbers must be converted to and from string format as they are passed ++from one @code{calc-eval} to the next. ++ ++If the separator is the symbol @code{raw}, the result will be returned ++as a raw Calc data structure rather than a string. You can read about ++how these objects look in the following sections, but usually you can ++treat them as ``black box'' objects with no important internal ++structure. ++ ++There is also a @code{rawnum} symbol, which is a combination of ++@code{raw} (returning a raw Calc object) and @code{num} (signaling ++an error if that object is not a constant). ++ ++You can pass a raw Calc object to @code{calc-eval} in place of a ++string, either as the formula itself or as one of the @samp{$} ++arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an ++addition function that operates on raw Calc objects. Of course ++in this case it would be easier to call the low-level @code{math-add} ++function in Calc, if you can remember its name. ++ ++In particular, note that a plain Lisp integer is acceptable to Calc ++as a raw object. (All Lisp integers are accepted on input, but ++integers of more than six decimal digits are converted to ``big-integer'' ++form for output. @xref{Data Type Formats}.) ++ ++When it comes time to display the object, just use @samp{(calc-eval a)} ++to format it as a string. ++ ++It is an error if the input expression evaluates to a list of ++values. The separator symbol @code{list} is like @code{raw} ++except that it returns a list of one or more raw Calc objects. ++ ++Note that a Lisp string is not a valid Calc object, nor is a list ++containing a string. Thus you can still safely distinguish all the ++various kinds of error returns discussed above. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Predicates ++ ++@noindent ++If the separator symbol is @code{pred}, the result of the formula is ++treated as a true/false value; @code{calc-eval} returns @code{t} or ++@code{nil}, respectively. A value is considered ``true'' if it is a ++non-zero number, or false if it is zero or if it is not a number. ++ ++For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether ++one value is less than another. ++ ++As usual, it is also possible for @code{calc-eval} to return one of ++the error indicators described above. Lisp will interpret such an ++indicator as ``true'' if you don't check for it explicitly. If you ++wish to have an error register as ``false'', use something like ++@samp{(eq (calc-eval ...) t)}. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Variable Values ++ ++@noindent ++Variables in the formula passed to @code{calc-eval} are not normally ++replaced by their values. If you wish this, you can use the ++@code{evalv} function (@pxref{Algebraic Manipulation}). For example, ++if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable ++@code{var-a}), then @samp{(calc-eval "a+pi")} will return the ++formula @code{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")} ++will return @code{"7.14159265359"}. ++ ++To store in a Calc variable, just use @code{setq} to store in the ++corresponding Lisp variable. (This is obtained by prepending ++@samp{var-} to the Calc variable name.) Calc routines will ++understand either string or raw form values stored in variables, ++although raw data objects are much more efficient. For example, ++to increment the Calc variable @code{a}: ++ ++@example ++(setq var-a (calc-eval "evalv(a+1)" 'raw)) ++@end example ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Stack Access ++ ++@noindent ++If the separator symbol is @code{push}, the formula argument is ++evaluated (with possible @samp{$} expansions, as usual). The ++result is pushed onto the Calc stack. The return value is @code{nil} ++(unless there is an error from evaluating the formula, in which ++case the return value depends on @code{calc-eval-error} in the ++usual way). ++ ++If the separator symbol is @code{pop}, the first argument to ++@code{calc-eval} must be an integer instead of a string. That ++many values are popped from the stack and thrown away. A negative ++argument deletes the entry at that stack level. The return value ++is the number of elements remaining in the stack after popping; ++@samp{(calc-eval 0 'pop)} is a good way to measure the size of ++the stack. ++ ++If the separator symbol is @code{top}, the first argument to ++@code{calc-eval} must again be an integer. The value at that ++stack level is formatted as a string and returned. Thus ++@samp{(calc-eval 1 'top)} returns the top-of-stack value. If the ++integer is out of range, @code{nil} is returned. ++ ++The separator symbol @code{rawtop} is just like @code{top} except ++that the stack entry is returned as a raw Calc object instead of ++as a string. ++ ++In all of these cases the first argument can be made a list in ++order to force the default mode settings, as described above. ++Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the ++second-to-top stack entry, formatted as a string using the default ++instead of current display modes, except that the radix is ++hexadecimal instead of decimal. ++ ++It is, of course, polite to put the Calc stack back the way you ++found it when you are done, unless the user of your program is ++actually expecting it to affect the stack. ++ ++Note that you do not actually have to switch into the @samp{*Calculator*} ++buffer in order to use @code{calc-eval}; it temporarily switches into ++the stack buffer if necessary. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Keyboard Macros ++ ++@noindent ++If the separator symbol is @code{macro}, the first argument must be a ++string of characters which Calc can execute as a sequence of keystrokes. ++This switches into the Calc buffer for the duration of the macro. ++For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the ++vector @samp{[1,2,3,4,5]} on the stack and then replaces it ++with the sum of those numbers. Note that @samp{\r} is the Lisp ++notation for the carriage-return, @key{RET}, character. ++ ++If your keyboard macro wishes to pop the stack, @samp{\C-d} is ++safer than @samp{\177} (the @key{DEL} character) because some ++installations may have switched the meanings of @key{DEL} and ++@kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for ++``pop-stack'' regardless of key mapping. ++ ++If you provide a third argument to @code{calc-eval}, evaluation ++of the keyboard macro will leave a record in the Trail using ++that argument as a tag string. Normally the Trail is unaffected. ++ ++The return value in this case is always @code{nil}. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Lisp Evaluation ++ ++@noindent ++Finally, if the separator symbol is @code{eval}, then the Lisp ++@code{eval} function is called on the first argument, which must ++be a Lisp expression rather than a Calc formula. Remember to ++quote the expression so that it is not evaluated until inside ++@code{calc-eval}. ++ ++The difference from plain @code{eval} is that @code{calc-eval} ++switches to the Calc buffer before evaluating the expression. ++For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)} ++will correctly affect the buffer-local Calc precision variable. ++ ++An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}. ++This is evaluating a call to the function that is normally invoked ++by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.'' ++Note that this function will leave a message in the echo area as ++a side effect. Also, all Calc functions switch to the Calc buffer ++automatically if not invoked from there, so the above call is ++also equivalent to @samp{(calc-precision 17)} by itself. ++In all cases, Calc uses @code{save-excursion} to switch back to ++your original buffer when it is done. ++ ++As usual the first argument can be a list that begins with a Lisp ++expression to use default instead of current mode settings. ++ ++The result of @code{calc-eval} in this usage is just the result ++returned by the evaluated Lisp expression. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@subsubsection Example ++ ++@noindent ++@findex convert-temp ++Here is a sample Emacs command that uses @code{calc-eval}. Suppose ++you have a document with lots of references to temperatures on the ++Fahrenheit scale, say ``98.6 F'', and you wish to convert these ++references to Centigrade. The following command does this conversion. ++Place the Emacs cursor right after the letter ``F'' and invoke the ++command to change ``98.6 F'' to ``37 C''. Or, if the temperature is ++already in Centigrade form, the command changes it back to Fahrenheit. ++ ++@example ++(defun convert-temp () ++ (interactive) ++ (save-excursion ++ (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)") ++ (let* ((top1 (match-beginning 1)) ++ (bot1 (match-end 1)) ++ (number (buffer-substring top1 bot1)) ++ (top2 (match-beginning 2)) ++ (bot2 (match-end 2)) ++ (type (buffer-substring top2 bot2))) ++ (if (equal type "F") ++ (setq type "C" ++ number (calc-eval "($ - 32)*5/9" nil number)) ++ (setq type "F" ++ number (calc-eval "$*9/5 + 32" nil number))) ++ (goto-char top2) ++ (delete-region top2 bot2) ++ (insert-before-markers type) ++ (goto-char top1) ++ (delete-region top1 bot1) ++ (if (string-match "\\.$" number) ; change "37." to "37" ++ (setq number (substring number 0 -1))) ++ (insert number)))) ++@end example ++ ++Note the use of @code{insert-before-markers} when changing between ++``F'' and ``C'', so that the character winds up before the cursor ++instead of after it. ++ ++@node Internals, , Calling Calc from Your Programs, Lisp Definitions ++@subsection Calculator Internals ++ ++@noindent ++This section describes the Lisp functions defined by the Calculator that ++may be of use to user-written Calculator programs (as described in the ++rest of this chapter). These functions are shown by their names as they ++conventionally appear in @code{defmath}. Their full Lisp names are ++generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their ++apparent names. (Names that begin with @samp{calc-} are already in ++their full Lisp form.) You can use the actual full names instead if you ++prefer them, or if you are calling these functions from regular Lisp. ++ ++The functions described here are scattered throughout the various ++Calc component files. Note that @file{calc.el} includes @code{autoload}s ++for only a few component files; when Calc wants to call an advanced ++function it calls @samp{(calc-extensions)} first; this function ++autoloads @file{calc-ext.el}, which in turn autoloads all the functions ++in the remaining component files. ++ ++Because @code{defmath} itself uses the extensions, user-written code ++generally always executes with the extensions already loaded, so ++normally you can use any Calc function and be confident that it will ++be autoloaded for you when necessary. If you are doing something ++special, check carefully to make sure each function you are using is ++from @file{calc.el} or its components, and call @samp{(calc-extensions)} ++before using any function based in @file{calc-ext.el} if you can't ++prove this file will already be loaded. ++ ++@menu ++* Data Type Formats:: ++* Interactive Lisp Functions:: ++* Stack Lisp Functions:: ++* Predicates:: ++* Computational Lisp Functions:: ++* Vector Lisp Functions:: ++* Symbolic Lisp Functions:: ++* Formatting Lisp Functions:: ++* Hooks:: ++@end menu ++ ++@node Data Type Formats, Interactive Lisp Functions, Internals, Internals ++@subsubsection Data Type Formats ++ ++@noindent ++Integers are stored in either of two ways, depending on their magnitude. ++Integers less than one million in absolute value are stored as standard ++Lisp integers. This is the only storage format for Calc data objects ++which is not a Lisp list. ++ ++Large integers are stored as lists of the form @samp{(bigpos @var{d0} ++@var{d1} @var{d2} @dots{})} for positive integers 1000000 or more, or ++@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative integers ++@mathit{-1000000} or less. Each @var{d} is a base-1000 ``digit,'' a Lisp integer ++from 0 to 999. The least significant digit is @var{d0}; the last digit, ++@var{dn}, which is always nonzero, is the most significant digit. For ++example, the integer @mathit{-12345678} is stored as @samp{(bigneg 678 345 12)}. ++ ++The distinction between small and large integers is entirely hidden from ++the user. In @code{defmath} definitions, the Lisp predicate @code{integerp} ++returns true for either kind of integer, and in general both big and small ++integers are accepted anywhere the word ``integer'' is used in this manual. ++If the distinction must be made, native Lisp integers are called @dfn{fixnums} ++and large integers are called @dfn{bignums}. ++ ++Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})} ++where @var{n} is an integer (big or small) numerator, @var{d} is an ++integer denominator greater than one, and @var{n} and @var{d} are relatively ++prime. Note that fractions where @var{d} is one are automatically converted ++to plain integers by all math routines; fractions where @var{d} is negative ++are normalized by negating the numerator and denominator. ++ ++Floating-point numbers are stored in the form, @samp{(float @var{mant} ++@var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than ++@samp{10^@var{p}} in absolute value (@var{p} represents the current ++precision), and @var{exp} (the ``exponent'') is a fixnum. The value of ++the float is @samp{@var{mant} * 10^@var{exp}}. For example, the number ++@mathit{-3.14} is stored as @samp{(float -314 -2) = -314*10^-2}. Other constraints ++are that the number 0.0 is always stored as @samp{(float 0 0)}, and, ++except for the 0.0 case, the rightmost base-10 digit of @var{mant} is ++always nonzero. (If the rightmost digit is zero, the number is ++rearranged by dividing @var{mant} by ten and incrementing @var{exp}.) ++ ++Rectangular complex numbers are stored in the form @samp{(cplx @var{re} ++@var{im})}, where @var{re} and @var{im} are each real numbers, either ++integers, fractions, or floats. The value is @samp{@var{re} + @var{im}i}. ++The @var{im} part is nonzero; complex numbers with zero imaginary ++components are converted to real numbers automatically. ++ ++Polar complex numbers are stored in the form @samp{(polar @var{r} ++@var{theta})}, where @var{r} is a positive real value and @var{theta} ++is a real value or HMS form representing an angle. This angle is ++usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees, ++or @samp{(-pi ..@: pi)} radians, according to the current angular mode. ++If the angle is 0 the value is converted to a real number automatically. ++(If the angle is 180 degrees, the value is usually also converted to a ++negative real number.) ++ ++Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m} ++@var{s})}, where @var{h} is an integer or an integer-valued float (i.e., ++a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued ++float in the range @w{@samp{[0 ..@: 60)}}, and @var{s} is any real number ++in the range @samp{[0 ..@: 60)}. ++ ++Date forms are stored as @samp{(date @var{n})}, where @var{n} is ++a real number that counts days since midnight on the morning of ++January 1, 1 AD. If @var{n} is an integer, this is a pure date ++form. If @var{n} is a fraction or float, this is a date/time form. ++ ++Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a ++positive real number or HMS form, and @var{n} is a real number or HMS ++form in the range @samp{[0 ..@: @var{m})}. ++ ++Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x} ++is the mean value and @var{sigma} is the standard deviation. Each ++component is either a number, an HMS form, or a symbolic object ++(a variable or function call). If @var{sigma} is zero, the value is ++converted to a plain real number. If @var{sigma} is negative or ++complex, it is automatically normalized to be a positive real. ++ ++Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})}, ++where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and ++@var{hi} are real numbers, HMS forms, or symbolic objects. The @var{mask} ++is a binary integer where 1 represents the fact that the interval is ++closed on the high end, and 2 represents the fact that it is closed on ++the low end. (Thus 3 represents a fully closed interval.) The interval ++@w{@samp{(intv 3 @var{x} @var{x})}} is converted to the plain number @var{x}; ++intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask} ++represent empty intervals. If @var{hi} is less than @var{lo}, the interval ++is converted to a standard empty interval by replacing @var{hi} with @var{lo}. ++ ++Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1} ++is the first element of the vector, @var{v2} is the second, and so on. ++An empty vector is stored as @samp{(vec)}. A matrix is simply a vector ++where all @var{v}'s are themselves vectors of equal lengths. Note that ++Calc vectors are unrelated to the Emacs Lisp ``vector'' type, which is ++generally unused by Calc data structures. ++ ++Variables are stored as @samp{(var @var{name} @var{sym})}, where ++@var{name} is a Lisp symbol whose print name is used as the visible name ++of the variable, and @var{sym} is a Lisp symbol in which the variable's ++value is actually stored. Thus, @samp{(var pi var-pi)} represents the ++special constant @samp{pi}. Almost always, the form is @samp{(var ++@var{v} var-@var{v})}. If the variable name was entered with @code{#} ++signs (which are converted to hyphens internally), the form is ++@samp{(var @var{u} @var{v})}, where @var{u} is a symbol whose name ++contains @code{#} characters, and @var{v} is a symbol that contains ++@code{-} characters instead. The value of a variable is the Calc ++object stored in its @var{sym} symbol's value cell. If the symbol's ++value cell is void or if it contains @code{nil}, the variable has no ++value. Special constants have the form @samp{(special-const ++@var{value})} stored in their value cell, where @var{value} is a formula ++which is evaluated when the constant's value is requested. Variables ++which represent units are not stored in any special way; they are units ++only because their names appear in the units table. If the value ++cell contains a string, it is parsed to get the variable's value when ++the variable is used. ++ ++A Lisp list with any other symbol as the first element is a function call. ++The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^}, ++and @code{|} represent special binary operators; these lists are always ++of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the ++sub-formula on the lefthand side and @var{rhs} is the sub-formula on the ++right. The symbol @code{neg} represents unary negation; this list is always ++of the form @samp{(neg @var{arg})}. Any other symbol @var{func} represents a ++function that would be displayed in function-call notation; the symbol ++@var{func} is in general always of the form @samp{calcFunc-@var{name}}. ++The function cell of the symbol @var{func} should contain a Lisp function ++for evaluating a call to @var{func}. This function is passed the remaining ++elements of the list (themselves already evaluated) as arguments; such ++functions should return @code{nil} or call @code{reject-arg} to signify ++that they should be left in symbolic form, or they should return a Calc ++object which represents their value, or a list of such objects if they ++wish to return multiple values. (The latter case is allowed only for ++functions which are the outer-level call in an expression whose value is ++about to be pushed on the stack; this feature is considered obsolete ++and is not used by any built-in Calc functions.) ++ ++@node Interactive Lisp Functions, Stack Lisp Functions, Data Type Formats, Internals ++@subsubsection Interactive Functions ++ ++@noindent ++The functions described here are used in implementing interactive Calc ++commands. Note that this list is not exhaustive! If there is an ++existing command that behaves similarly to the one you want to define, ++you may find helpful tricks by checking the source code for that command. ++ ++@defun calc-set-command-flag flag ++Set the command flag @var{flag}. This is generally a Lisp symbol, but ++may in fact be anything. The effect is to add @var{flag} to the list ++stored in the variable @code{calc-command-flags}, unless it is already ++there. @xref{Defining Simple Commands}. ++@end defun ++ ++@defun calc-clear-command-flag flag ++If @var{flag} appears among the list of currently-set command flags, ++remove it from that list. ++@end defun ++ ++@defun calc-record-undo rec ++Add the ``undo record'' @var{rec} to the list of steps to take if the ++current operation should need to be undone. Stack push and pop functions ++automatically call @code{calc-record-undo}, so the kinds of undo records ++you might need to create take the form @samp{(set @var{sym} @var{value})}, ++which says that the Lisp variable @var{sym} was changed and had previously ++contained @var{value}; @samp{(store @var{var} @var{value})} which says that ++the Calc variable @var{var} (a string which is the name of the symbol that ++contains the variable's value) was stored and its previous value was ++@var{value} (either a Calc data object, or @code{nil} if the variable was ++previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})}, ++which means that to undo requires calling the function @samp{(@var{undo} ++@var{args} @dots{})} and, if the undo is later redone, calling ++@samp{(@var{redo} @var{args} @dots{})}. ++@end defun ++ ++@defun calc-record-why msg args ++Record the error or warning message @var{msg}, which is normally a string. ++This message will be replayed if the user types @kbd{w} (@code{calc-why}); ++if the message string begins with a @samp{*}, it is considered important ++enough to display even if the user doesn't type @kbd{w}. If one or more ++@var{args} are present, the displayed message will be of the form, ++@samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are ++formatted on the assumption that they are either strings or Calc objects of ++some sort. If @var{msg} is a symbol, it is the name of a Calc predicate ++(such as @code{integerp} or @code{numvecp}) which the arguments did not ++satisfy; it is expanded to a suitable string such as ``Expected an ++integer.'' The @code{reject-arg} function calls @code{calc-record-why} ++automatically; @pxref{Predicates}. ++@end defun ++ ++@defun calc-is-inverse ++This predicate returns true if the current command is inverse, ++i.e., if the Inverse (@kbd{I} key) flag was set. ++@end defun ++ ++@defun calc-is-hyperbolic ++This predicate is the analogous function for the @kbd{H} key. ++@end defun ++ ++@node Stack Lisp Functions, Predicates, Interactive Lisp Functions, Internals ++@subsubsection Stack-Oriented Functions ++ ++@noindent ++The functions described here perform various operations on the Calc ++stack and trail. They are to be used in interactive Calc commands. ++ ++@defun calc-push-list vals n ++Push the Calc objects in list @var{vals} onto the stack at stack level ++@var{n}. If @var{n} is omitted it defaults to 1, so that the elements ++are pushed at the top of the stack. If @var{n} is greater than 1, the ++elements will be inserted into the stack so that the last element will ++end up at level @var{n}, the next-to-last at level @var{n}+1, etc. ++The elements of @var{vals} are assumed to be valid Calc objects, and ++are not evaluated, rounded, or renormalized in any way. If @var{vals} ++is an empty list, nothing happens. ++ ++The stack elements are pushed without any sub-formula selections. ++You can give an optional third argument to this function, which must ++be a list the same size as @var{vals} of selections. Each selection ++must be @code{eq} to some sub-formula of the corresponding formula ++in @var{vals}, or @code{nil} if that formula should have no selection. ++@end defun ++ ++@defun calc-top-list n m ++Return a list of the @var{n} objects starting at level @var{m} of the ++stack. If @var{m} is omitted it defaults to 1, so that the elements are ++taken from the top of the stack. If @var{n} is omitted, it also ++defaults to 1, so that the top stack element (in the form of a ++one-element list) is returned. If @var{m} is greater than 1, the ++@var{m}th stack element will be at the end of the list, the @var{m}+1st ++element will be next-to-last, etc. If @var{n} or @var{m} are out of ++range, the command is aborted with a suitable error message. If @var{n} ++is zero, the function returns an empty list. The stack elements are not ++evaluated, rounded, or renormalized. ++ ++If any stack elements contain selections, and selections have not ++been disabled by the @kbd{j e} (@code{calc-enable-selections}) command, ++this function returns the selected portions rather than the entire ++stack elements. It can be given a third ``selection-mode'' argument ++which selects other behaviors. If it is the symbol @code{t}, then ++a selection in any of the requested stack elements produces an ++``invalid operation on selections'' error. If it is the symbol @code{full}, ++the whole stack entry is always returned regardless of selections. ++If it is the symbol @code{sel}, the selected portion is always returned, ++or @code{nil} if there is no selection. (This mode ignores the @kbd{j e} ++command.) If the symbol is @code{entry}, the complete stack entry in ++list form is returned; the first element of this list will be the whole ++formula, and the third element will be the selection (or @code{nil}). ++@end defun ++ ++@defun calc-pop-stack n m ++Remove the specified elements from the stack. The parameters @var{n} ++and @var{m} are defined the same as for @code{calc-top-list}. The return ++value of @code{calc-pop-stack} is uninteresting. ++ ++If there are any selected sub-formulas among the popped elements, and ++@kbd{j e} has not been used to disable selections, this produces an ++error without changing the stack. If you supply an optional third ++argument of @code{t}, the stack elements are popped even if they ++contain selections. ++@end defun ++ ++@defun calc-record-list vals tag ++This function records one or more results in the trail. The @var{vals} ++are a list of strings or Calc objects. The @var{tag} is the four-character ++tag string to identify the values. If @var{tag} is omitted, a blank tag ++will be used. ++@end defun ++ ++@defun calc-normalize n ++This function takes a Calc object and ``normalizes'' it. At the very ++least this involves re-rounding floating-point values according to the ++current precision and other similar jobs. Also, unless the user has ++selected No-Simplify mode (@pxref{Simplification Modes}), this involves ++actually evaluating a formula object by executing the function calls ++it contains, and possibly also doing algebraic simplification, etc. ++@end defun ++ ++@defun calc-top-list-n n m ++This function is identical to @code{calc-top-list}, except that it calls ++@code{calc-normalize} on the values that it takes from the stack. They ++are also passed through @code{check-complete}, so that incomplete ++objects will be rejected with an error message. All computational ++commands should use this in preference to @code{calc-top-list}; the only ++standard Calc commands that operate on the stack without normalizing ++are stack management commands like @code{calc-enter} and @code{calc-roll-up}. ++This function accepts the same optional selection-mode argument as ++@code{calc-top-list}. ++@end defun ++ ++@defun calc-top-n m ++This function is a convenient form of @code{calc-top-list-n} in which only ++a single element of the stack is taken and returned, rather than a list ++of elements. This also accepts an optional selection-mode argument. ++@end defun ++ ++@defun calc-enter-result n tag vals ++This function is a convenient interface to most of the above functions. ++The @var{vals} argument should be either a single Calc object, or a list ++of Calc objects; the object or objects are normalized, and the top @var{n} ++stack entries are replaced by the normalized objects. If @var{tag} is ++non-@code{nil}, the normalized objects are also recorded in the trail. ++A typical stack-based computational command would take the form, ++ ++@smallexample ++(calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func} ++ (calc-top-list-n @var{n}))) ++@end smallexample ++ ++If any of the @var{n} stack elements replaced contain sub-formula ++selections, and selections have not been disabled by @kbd{j e}, ++this function takes one of two courses of action. If @var{n} is ++equal to the number of elements in @var{vals}, then each element of ++@var{vals} is spliced into the corresponding selection; this is what ++happens when you use the @key{TAB} key, or when you use a unary ++arithmetic operation like @code{sqrt}. If @var{vals} has only one ++element but @var{n} is greater than one, there must be only one ++selection among the top @var{n} stack elements; the element from ++@var{vals} is spliced into that selection. This is what happens when ++you use a binary arithmetic operation like @kbd{+}. Any other ++combination of @var{n} and @var{vals} is an error when selections ++are present. ++@end defun ++ ++@defun calc-unary-op tag func arg ++This function implements a unary operator that allows a numeric prefix ++argument to apply the operator over many stack entries. If the prefix ++argument @var{arg} is @code{nil}, this uses @code{calc-enter-result} ++as outlined above. Otherwise, it maps the function over several stack ++elements; @pxref{Prefix Arguments}. For example, ++ ++@smallexample ++(defun calc-zeta (arg) ++ (interactive "P") ++ (calc-unary-op "zeta" 'calcFunc-zeta arg)) ++@end smallexample ++@end defun ++ ++@defun calc-binary-op tag func arg ident unary ++This function implements a binary operator, analogously to ++@code{calc-unary-op}. The optional @var{ident} and @var{unary} ++arguments specify the behavior when the prefix argument is zero or ++one, respectively. If the prefix is zero, the value @var{ident} ++is pushed onto the stack, if specified, otherwise an error message ++is displayed. If the prefix is one, the unary function @var{unary} ++is applied to the top stack element, or, if @var{unary} is not ++specified, nothing happens. When the argument is two or more, ++the binary function @var{func} is reduced across the top @var{arg} ++stack elements; when the argument is negative, the function is ++mapped between the next-to-top @mathit{-@var{arg}} stack elements and the ++top element. ++@end defun ++ ++@defun calc-stack-size ++Return the number of elements on the stack as an integer. This count ++does not include elements that have been temporarily hidden by stack ++truncation; @pxref{Truncating the Stack}. ++@end defun ++ ++@defun calc-cursor-stack-index n ++Move the point to the @var{n}th stack entry. If @var{n} is zero, this ++will be the @samp{.} line. If @var{n} is from 1 to the current stack size, ++this will be the beginning of the first line of that stack entry's display. ++If line numbers are enabled, this will move to the first character of the ++line number, not the stack entry itself. ++@end defun ++ ++@defun calc-substack-height n ++Return the number of lines between the beginning of the @var{n}th stack ++entry and the bottom of the buffer. If @var{n} is zero, this ++will be one (assuming no stack truncation). If all stack entries are ++one line long (i.e., no matrices are displayed), the return value will ++be equal @var{n}+1 as long as @var{n} is in range. (Note that in Big ++mode, the return value includes the blank lines that separate stack ++entries.) ++@end defun ++ ++@defun calc-refresh ++Erase the @code{*Calculator*} buffer and reformat its contents from memory. ++This must be called after changing any parameter, such as the current ++display radix, which might change the appearance of existing stack ++entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing ++is suppressed, but a flag is set so that the entire stack will be refreshed ++rather than just the top few elements when the macro finishes.) ++@end defun ++ ++@node Predicates, Computational Lisp Functions, Stack Lisp Functions, Internals ++@subsubsection Predicates ++ ++@noindent ++The functions described here are predicates, that is, they return a ++true/false value where @code{nil} means false and anything else means ++true. These predicates are expanded by @code{defmath}, for example, ++from @code{zerop} to @code{math-zerop}. In many cases they correspond ++to native Lisp functions by the same name, but are extended to cover ++the full range of Calc data types. ++ ++@defun zerop x ++Returns true if @var{x} is numerically zero, in any of the Calc data ++types. (Note that for some types, such as error forms and intervals, ++it never makes sense to return true.) In @code{defmath}, the expression ++@samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)}, ++and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}. ++@end defun ++ ++@defun negp x ++Returns true if @var{x} is negative. This accepts negative real numbers ++of various types, negative HMS and date forms, and intervals in which ++all included values are negative. In @code{defmath}, the expression ++@samp{(< x 0)} will automatically be converted to @samp{(math-negp x)}, ++and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}. ++@end defun ++ ++@defun posp x ++Returns true if @var{x} is positive (and non-zero). For complex ++numbers, none of these three predicates will return true. ++@end defun ++ ++@defun looks-negp x ++Returns true if @var{x} is ``negative-looking.'' This returns true if ++@var{x} is a negative number, or a formula with a leading minus sign ++such as @samp{-a/b}. In other words, this is an object which can be ++made simpler by calling @code{(- @var{x})}. ++@end defun ++ ++@defun integerp x ++Returns true if @var{x} is an integer of any size. ++@end defun ++ ++@defun fixnump x ++Returns true if @var{x} is a native Lisp integer. ++@end defun ++ ++@defun natnump x ++Returns true if @var{x} is a nonnegative integer of any size. ++@end defun ++ ++@defun fixnatnump x ++Returns true if @var{x} is a nonnegative Lisp integer. ++@end defun ++ ++@defun num-integerp x ++Returns true if @var{x} is numerically an integer, i.e., either a ++true integer or a float with no significant digits to the right of ++the decimal point. ++@end defun ++ ++@defun messy-integerp x ++Returns true if @var{x} is numerically, but not literally, an integer. ++A value is @code{num-integerp} if it is @code{integerp} or ++@code{messy-integerp} (but it is never both at once). ++@end defun ++ ++@defun num-natnump x ++Returns true if @var{x} is numerically a nonnegative integer. ++@end defun ++ ++@defun evenp x ++Returns true if @var{x} is an even integer. ++@end defun ++ ++@defun looks-evenp x ++Returns true if @var{x} is an even integer, or a formula with a leading ++multiplicative coefficient which is an even integer. ++@end defun ++ ++@defun oddp x ++Returns true if @var{x} is an odd integer. ++@end defun ++ ++@defun ratp x ++Returns true if @var{x} is a rational number, i.e., an integer or a ++fraction. ++@end defun ++ ++@defun realp x ++Returns true if @var{x} is a real number, i.e., an integer, fraction, ++or floating-point number. ++@end defun ++ ++@defun anglep x ++Returns true if @var{x} is a real number or HMS form. ++@end defun ++ ++@defun floatp x ++Returns true if @var{x} is a float, or a complex number, error form, ++interval, date form, or modulo form in which at least one component ++is a float. ++@end defun ++ ++@defun complexp x ++Returns true if @var{x} is a rectangular or polar complex number ++(but not a real number). ++@end defun ++ ++@defun rect-complexp x ++Returns true if @var{x} is a rectangular complex number. ++@end defun ++ ++@defun polar-complexp x ++Returns true if @var{x} is a polar complex number. ++@end defun ++ ++@defun numberp x ++Returns true if @var{x} is a real number or a complex number. ++@end defun ++ ++@defun scalarp x ++Returns true if @var{x} is a real or complex number or an HMS form. ++@end defun ++ ++@defun vectorp x ++Returns true if @var{x} is a vector (this simply checks if its argument ++is a list whose first element is the symbol @code{vec}). ++@end defun ++ ++@defun numvecp x ++Returns true if @var{x} is a number or vector. ++@end defun ++ ++@defun matrixp x ++Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors, ++all of the same size. ++@end defun ++ ++@defun square-matrixp x ++Returns true if @var{x} is a square matrix. ++@end defun ++ ++@defun objectp x ++Returns true if @var{x} is any numeric Calc object, including real and ++complex numbers, HMS forms, date forms, error forms, intervals, and ++modulo forms. (Note that error forms and intervals may include formulas ++as their components; see @code{constp} below.) ++@end defun ++ ++@defun objvecp x ++Returns true if @var{x} is an object or a vector. This also accepts ++incomplete objects, but it rejects variables and formulas (except as ++mentioned above for @code{objectp}). ++@end defun ++ ++@defun primp x ++Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object, ++i.e., one whose components cannot be regarded as sub-formulas. This ++includes variables, and all @code{objectp} types except error forms ++and intervals. ++@end defun ++ ++@defun constp x ++Returns true if @var{x} is constant, i.e., a real or complex number, ++HMS form, date form, or error form, interval, or vector all of whose ++components are @code{constp}. ++@end defun ++ ++@defun lessp x y ++Returns true if @var{x} is numerically less than @var{y}. Returns false ++if @var{x} is greater than or equal to @var{y}, or if the order is ++undefined or cannot be determined. Generally speaking, this works ++by checking whether @samp{@var{x} - @var{y}} is @code{negp}. In ++@code{defmath}, the expression @samp{(< x y)} will automatically be ++converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=}, ++and @code{>=} are similarly converted in terms of @code{lessp}. ++@end defun ++ ++@defun beforep x y ++Returns true if @var{x} comes before @var{y} in a canonical ordering ++of Calc objects. If @var{x} and @var{y} are both real numbers, this ++will be the same as @code{lessp}. But whereas @code{lessp} considers ++other types of objects to be unordered, @code{beforep} puts any two ++objects into a definite, consistent order. The @code{beforep} ++function is used by the @kbd{V S} vector-sorting command, and also ++by @kbd{a s} to put the terms of a product into canonical order: ++This allows @samp{x y + y x} to be simplified easily to @samp{2 x y}. ++@end defun ++ ++@defun equal x y ++This is the standard Lisp @code{equal} predicate; it returns true if ++@var{x} and @var{y} are structurally identical. This is the usual way ++to compare numbers for equality, but note that @code{equal} will treat ++0 and 0.0 as different. ++@end defun ++ ++@defun math-equal x y ++Returns true if @var{x} and @var{y} are numerically equal, either because ++they are @code{equal}, or because their difference is @code{zerop}. In ++@code{defmath}, the expression @samp{(= x y)} will automatically be ++converted to @samp{(math-equal x y)}. ++@end defun ++ ++@defun equal-int x n ++Returns true if @var{x} and @var{n} are numerically equal, where @var{n} ++is a fixnum which is not a multiple of 10. This will automatically be ++used by @code{defmath} in place of the more general @code{math-equal} ++whenever possible. ++@end defun ++ ++@defun nearly-equal x y ++Returns true if @var{x} and @var{y}, as floating-point numbers, are ++equal except possibly in the last decimal place. For example, ++314.159 and 314.166 are considered nearly equal if the current ++precision is 6 (since they differ by 7 units), but not if the current ++precision is 7 (since they differ by 70 units). Most functions which ++use series expansions use @code{with-extra-prec} to evaluate the ++series with 2 extra digits of precision, then use @code{nearly-equal} ++to decide when the series has converged; this guards against cumulative ++error in the series evaluation without doing extra work which would be ++lost when the result is rounded back down to the current precision. ++In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}. ++The @var{x} and @var{y} can be numbers of any kind, including complex. ++@end defun ++ ++@defun nearly-zerop x y ++Returns true if @var{x} is nearly zero, compared to @var{y}. This ++checks whether @var{x} plus @var{y} would by be @code{nearly-equal} ++to @var{y} itself, to within the current precision, in other words, ++if adding @var{x} to @var{y} would have a negligible effect on @var{y} ++due to roundoff error. @var{X} may be a real or complex number, but ++@var{y} must be real. ++@end defun ++ ++@defun is-true x ++Return true if the formula @var{x} represents a true value in ++Calc, not Lisp, terms. It tests if @var{x} is a non-zero number ++or a provably non-zero formula. ++@end defun ++ ++@defun reject-arg val pred ++Abort the current function evaluation due to unacceptable argument values. ++This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a ++Lisp error which @code{normalize} will trap. The net effect is that the ++function call which led here will be left in symbolic form. ++@end defun ++ ++@defun inexact-value ++If Symbolic mode is enabled, this will signal an error that causes ++@code{normalize} to leave the formula in symbolic form, with the message ++``Inexact result.'' (This function has no effect when not in Symbolic mode.) ++Note that if your function calls @samp{(sin 5)} in Symbolic mode, the ++@code{sin} function will call @code{inexact-value}, which will cause your ++function to be left unsimplified. You may instead wish to call ++@samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic mode will ++return the formula @samp{sin(5)} to your function. ++@end defun ++ ++@defun overflow ++This signals an error that will be reported as a floating-point overflow. ++@end defun ++ ++@defun underflow ++This signals a floating-point underflow. ++@end defun ++ ++@node Computational Lisp Functions, Vector Lisp Functions, Predicates, Internals ++@subsubsection Computational Functions ++ ++@noindent ++The functions described here do the actual computational work of the ++Calculator. In addition to these, note that any function described in ++the main body of this manual may be called from Lisp; for example, if ++the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command, ++this means @code{calc-sqrt} is an interactive stack-based square-root ++command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt}) ++is the actual Lisp function for taking square roots. ++ ++The functions @code{math-add}, @code{math-sub}, @code{math-mul}, ++@code{math-div}, @code{math-mod}, and @code{math-neg} are not included ++in this list, since @code{defmath} allows you to write native Lisp ++@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-}, ++respectively, instead. ++ ++@defun normalize val ++(Full form: @code{math-normalize}.) ++Reduce the value @var{val} to standard form. For example, if @var{val} ++is a fixnum, it will be converted to a bignum if it is too large, and ++if @var{val} is a bignum it will be normalized by clipping off trailing ++(i.e., most-significant) zero digits and converting to a fixnum if it is ++small. All the various data types are similarly converted to their standard ++forms. Variables are left alone, but function calls are actually evaluated ++in formulas. For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will ++return 6. ++ ++If a function call fails, because the function is void or has the wrong ++number of parameters, or because it returns @code{nil} or calls ++@code{reject-arg} or @code{inexact-result}, @code{normalize} returns ++the formula still in symbolic form. ++ ++If the current simplification mode is ``none'' or ``numeric arguments ++only,'' @code{normalize} will act appropriately. However, the more ++powerful simplification modes (like Algebraic Simplification) are ++not handled by @code{normalize}. They are handled by @code{calc-normalize}, ++which calls @code{normalize} and possibly some other routines, such ++as @code{simplify} or @code{simplify-units}. Programs generally will ++never call @code{calc-normalize} except when popping or pushing values ++on the stack. ++@end defun ++ ++@defun evaluate-expr expr ++Replace all variables in @var{expr} that have values with their values, ++then use @code{normalize} to simplify the result. This is what happens ++when you press the @kbd{=} key interactively. ++@end defun ++ ++@defmac with-extra-prec n body ++Evaluate the Lisp forms in @var{body} with precision increased by @var{n} ++digits. This is a macro which expands to ++ ++@smallexample ++(math-normalize ++ (let ((calc-internal-prec (+ calc-internal-prec @var{n}))) ++ @var{body})) ++@end smallexample ++ ++The surrounding call to @code{math-normalize} causes a floating-point ++result to be rounded down to the original precision afterwards. This ++is important because some arithmetic operations assume a number's ++mantissa contains no more digits than the current precision allows. ++@end defmac ++ ++@defun make-frac n d ++Build a fraction @samp{@var{n}:@var{d}}. This is equivalent to calling ++@samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient. ++@end defun ++ ++@defun make-float mant exp ++Build a floating-point value out of @var{mant} and @var{exp}, both ++of which are arbitrary integers. This function will return a ++properly normalized float value, or signal an overflow or underflow ++if @var{exp} is out of range. ++@end defun ++ ++@defun make-sdev x sigma ++Build an error form out of @var{x} and the absolute value of @var{sigma}. ++If @var{sigma} is zero, the result is the number @var{x} directly. ++If @var{sigma} is negative or complex, its absolute value is used. ++If @var{x} or @var{sigma} is not a valid type of object for use in ++error forms, this calls @code{reject-arg}. ++@end defun ++ ++@defun make-intv mask lo hi ++Build an interval form out of @var{mask} (which is assumed to be an ++integer from 0 to 3), and the limits @var{lo} and @var{hi}. If ++@var{lo} is greater than @var{hi}, an empty interval form is returned. ++This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable. ++@end defun ++ ++@defun sort-intv mask lo hi ++Build an interval form, similar to @code{make-intv}, except that if ++@var{lo} is less than @var{hi} they are simply exchanged, and the ++bits of @var{mask} are swapped accordingly. ++@end defun ++ ++@defun make-mod n m ++Build a modulo form out of @var{n} and the modulus @var{m}. Since modulo ++forms do not allow formulas as their components, if @var{n} or @var{m} ++is not a real number or HMS form the result will be a formula which ++is a call to @code{makemod}, the algebraic version of this function. ++@end defun ++ ++@defun float x ++Convert @var{x} to floating-point form. Integers and fractions are ++converted to numerically equivalent floats; components of complex ++numbers, vectors, HMS forms, date forms, error forms, intervals, and ++modulo forms are recursively floated. If the argument is a variable ++or formula, this calls @code{reject-arg}. ++@end defun ++ ++@defun compare x y ++Compare the numbers @var{x} and @var{y}, and return @mathit{-1} if ++@samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})}, ++0 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is ++undefined or cannot be determined. ++@end defun ++ ++@defun numdigs n ++Return the number of digits of integer @var{n}, effectively ++@samp{ceil(log10(@var{n}))}, but much more efficient. Zero is ++considered to have zero digits. ++@end defun ++ ++@defun scale-int x n ++Shift integer @var{x} left @var{n} decimal digits, or right @mathit{-@var{n}} ++digits with truncation toward zero. ++@end defun ++ ++@defun scale-rounding x n ++Like @code{scale-int}, except that a right shift rounds to the nearest ++integer rather than truncating. ++@end defun ++ ++@defun fixnum n ++Return the integer @var{n} as a fixnum, i.e., a native Lisp integer. ++If @var{n} is outside the permissible range for Lisp integers (usually ++24 binary bits) the result is undefined. ++@end defun ++ ++@defun sqr x ++Compute the square of @var{x}; short for @samp{(* @var{x} @var{x})}. ++@end defun ++ ++@defun quotient x y ++Divide integer @var{x} by integer @var{y}; return an integer quotient ++and discard the remainder. If @var{x} or @var{y} is negative, the ++direction of rounding is undefined. ++@end defun ++ ++@defun idiv x y ++Perform an integer division; if @var{x} and @var{y} are both nonnegative ++integers, this uses the @code{quotient} function, otherwise it computes ++@samp{floor(@var{x}/@var{y})}. Thus the result is well-defined but ++slower than for @code{quotient}. ++@end defun ++ ++@defun imod x y ++Divide integer @var{x} by integer @var{y}; return the integer remainder ++and discard the quotient. Like @code{quotient}, this works only for ++integer arguments and is not well-defined for negative arguments. ++For a more well-defined result, use @samp{(% @var{x} @var{y})}. ++@end defun ++ ++@defun idivmod x y ++Divide integer @var{x} by integer @var{y}; return a cons cell whose ++@code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr} ++is @samp{(imod @var{x} @var{y})}. ++@end defun ++ ++@defun pow x y ++Compute @var{x} to the power @var{y}. In @code{defmath} code, this can ++also be written @samp{(^ @var{x} @var{y})} or ++@w{@samp{(expt @var{x} @var{y})}}. ++@end defun ++ ++@defun abs-approx x ++Compute a fast approximation to the absolute value of @var{x}. For ++example, for a rectangular complex number the result is the sum of ++the absolute values of the components. ++@end defun ++ ++@findex e ++@findex gamma-const ++@findex ln-2 ++@findex ln-10 ++@findex phi ++@findex pi-over-2 ++@findex pi-over-4 ++@findex pi-over-180 ++@findex sqrt-two-pi ++@findex sqrt-e ++@findex two-pi ++@defun pi ++The function @samp{(pi)} computes @samp{pi} to the current precision. ++Other related constant-generating functions are @code{two-pi}, ++@code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi}, ++@code{e}, @code{sqrt-e}, @code{ln-2}, @code{ln-10}, @code{phi} and ++@code{gamma-const}. Each function returns a floating-point value in the ++current precision, and each uses caching so that all calls after the ++first are essentially free. ++@end defun ++ ++@defmac math-defcache @var{func} @var{initial} @var{form} ++This macro, usually used as a top-level call like @code{defun} or ++@code{defvar}, defines a new cached constant analogous to @code{pi}, etc. ++It defines a function @code{func} which returns the requested value; ++if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})} ++form which serves as an initial value for the cache. If @var{func} ++is called when the cache is empty or does not have enough digits to ++satisfy the current precision, the Lisp expression @var{form} is evaluated ++with the current precision increased by four, and the result minus its ++two least significant digits is stored in the cache. For example, ++calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34 ++digits, rounds it down to 32 digits for future use, then rounds it ++again to 30 digits for use in the present request. ++@end defmac ++ ++@findex half-circle ++@findex quarter-circle ++@defun full-circle symb ++If the current angular mode is Degrees or HMS, this function returns the ++integer 360. In Radians mode, this function returns either the ++corresponding value in radians to the current precision, or the formula ++@samp{2*pi}, depending on the Symbolic mode. There are also similar ++function @code{half-circle} and @code{quarter-circle}. ++@end defun ++ ++@defun power-of-2 n ++Compute two to the integer power @var{n}, as a (potentially very large) ++integer. Powers of two are cached, so only the first call for a ++particular @var{n} is expensive. ++@end defun ++ ++@defun integer-log2 n ++Compute the base-2 logarithm of @var{n}, which must be an integer which ++is a power of two. If @var{n} is not a power of two, this function will ++return @code{nil}. ++@end defun ++ ++@defun div-mod a b m ++Divide @var{a} by @var{b}, modulo @var{m}. This returns @code{nil} if ++there is no solution, or if any of the arguments are not integers. ++@end defun ++ ++@defun pow-mod a b m ++Compute @var{a} to the power @var{b}, modulo @var{m}. If @var{a}, ++@var{b}, and @var{m} are integers, this uses an especially efficient ++algorithm. Otherwise, it simply computes @samp{(% (^ a b) m)}. ++@end defun ++ ++@defun isqrt n ++Compute the integer square root of @var{n}. This is the square root ++of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}. ++If @var{n} is itself an integer, the computation is especially efficient. ++@end defun ++ ++@defun to-hms a ang ++Convert the argument @var{a} into an HMS form. If @var{ang} is specified, ++it is the angular mode in which to interpret @var{a}, either @code{deg} ++or @code{rad}. Otherwise, the current angular mode is used. If @var{a} ++is already an HMS form it is returned as-is. ++@end defun ++ ++@defun from-hms a ang ++Convert the HMS form @var{a} into a real number. If @var{ang} is specified, ++it is the angular mode in which to express the result, otherwise the ++current angular mode is used. If @var{a} is already a real number, it ++is returned as-is. ++@end defun ++ ++@defun to-radians a ++Convert the number or HMS form @var{a} to radians from the current ++angular mode. ++@end defun ++ ++@defun from-radians a ++Convert the number @var{a} from radians to the current angular mode. ++If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}. ++@end defun ++ ++@defun to-radians-2 a ++Like @code{to-radians}, except that in Symbolic mode a degrees to ++radians conversion yields a formula like @samp{@var{a}*pi/180}. ++@end defun ++ ++@defun from-radians-2 a ++Like @code{from-radians}, except that in Symbolic mode a radians to ++degrees conversion yields a formula like @samp{@var{a}*180/pi}. ++@end defun ++ ++@defun random-digit ++Produce a random base-1000 digit in the range 0 to 999. ++@end defun ++ ++@defun random-digits n ++Produce a random @var{n}-digit integer; this will be an integer ++in the interval @samp{[0, 10^@var{n})}. ++@end defun ++ ++@defun random-float ++Produce a random float in the interval @samp{[0, 1)}. ++@end defun ++ ++@defun prime-test n iters ++Determine whether the integer @var{n} is prime. Return a list which has ++one of these forms: @samp{(nil @var{f})} means the number is non-prime ++because it was found to be divisible by @var{f}; @samp{(nil)} means it ++was found to be non-prime by table look-up (so no factors are known); ++@samp{(nil unknown)} means it is definitely non-prime but no factors ++are known because @var{n} was large enough that Fermat's probabilistic ++test had to be used; @samp{(t)} means the number is definitely prime; ++and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i} ++iterations, is @var{p} percent sure that the number is prime. The ++@var{iters} parameter is the number of Fermat iterations to use, in the ++case that this is necessary. If @code{prime-test} returns ``maybe,'' ++you can call it again with the same @var{n} to get a greater certainty; ++@code{prime-test} remembers where it left off. ++@end defun ++ ++@defun to-simple-fraction f ++If @var{f} is a floating-point number which can be represented exactly ++as a small rational number. return that number, else return @var{f}. ++For example, 0.75 would be converted to 3:4. This function is very ++fast. ++@end defun ++ ++@defun to-fraction f tol ++Find a rational approximation to floating-point number @var{f} to within ++a specified tolerance @var{tol}; this corresponds to the algebraic ++function @code{frac}, and can be rather slow. ++@end defun ++ ++@defun quarter-integer n ++If @var{n} is an integer or integer-valued float, this function ++returns zero. If @var{n} is a half-integer (i.e., an integer plus ++@mathit{1:2} or 0.5), it returns 2. If @var{n} is a quarter-integer, ++it returns 1 or 3. If @var{n} is anything else, this function ++returns @code{nil}. ++@end defun ++ ++@node Vector Lisp Functions, Symbolic Lisp Functions, Computational Lisp Functions, Internals ++@subsubsection Vector Functions ++ ++@noindent ++The functions described here perform various operations on vectors and ++matrices. ++ ++@defun math-concat x y ++Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}} ++in a symbolic formula. @xref{Building Vectors}. ++@end defun ++ ++@defun vec-length v ++Return the length of vector @var{v}. If @var{v} is not a vector, the ++result is zero. If @var{v} is a matrix, this returns the number of ++rows in the matrix. ++@end defun ++ ++@defun mat-dimens m ++Determine the dimensions of vector or matrix @var{m}. If @var{m} is not ++a vector, the result is an empty list. If @var{m} is a plain vector ++but not a matrix, the result is a one-element list containing the length ++of the vector. If @var{m} is a matrix with @var{r} rows and @var{c} columns, ++the result is the list @samp{(@var{r} @var{c})}. Higher-order tensors ++produce lists of more than two dimensions. Note that the object ++@samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size, ++and is treated by this and other Calc routines as a plain vector of two ++elements. ++@end defun ++ ++@defun dimension-error ++Abort the current function with a message of ``Dimension error.'' ++The Calculator will leave the function being evaluated in symbolic ++form; this is really just a special case of @code{reject-arg}. ++@end defun ++ ++@defun build-vector args ++Return a Calc vector with @var{args} as elements. ++For example, @samp{(build-vector 1 2 3)} returns the Calc vector ++@samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}. ++@end defun ++ ++@defun make-vec obj dims ++Return a Calc vector or matrix all of whose elements are equal to ++@var{obj}. For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix ++filled with 27's. ++@end defun ++ ++@defun row-matrix v ++If @var{v} is a plain vector, convert it into a row matrix, i.e., ++a matrix whose single row is @var{v}. If @var{v} is already a matrix, ++leave it alone. ++@end defun ++ ++@defun col-matrix v ++If @var{v} is a plain vector, convert it into a column matrix, i.e., a ++matrix with each element of @var{v} as a separate row. If @var{v} is ++already a matrix, leave it alone. ++@end defun ++ ++@defun map-vec f v ++Map the Lisp function @var{f} over the Calc vector @var{v}. For example, ++@samp{(map-vec 'math-floor v)} returns a vector of the floored components ++of vector @var{v}. ++@end defun ++ ++@defun map-vec-2 f a b ++Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}. ++If @var{a} and @var{b} are vectors of equal length, the result is a ++vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})} ++for each pair of elements @var{ai} and @var{bi}. If either @var{a} or ++@var{b} is a scalar, it is matched with each value of the other vector. ++For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v} ++with each element increased by one. Note that using @samp{'+} would not ++work here, since @code{defmath} does not expand function names everywhere, ++just where they are in the function position of a Lisp expression. ++@end defun ++ ++@defun reduce-vec f v ++Reduce the function @var{f} over the vector @var{v}. For example, if ++@var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}. ++If @var{v} is a matrix, this reduces over the rows of @var{v}. ++@end defun ++ ++@defun reduce-cols f m ++Reduce the function @var{f} over the columns of matrix @var{m}. For ++example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result ++is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}. ++@end defun ++ ++@defun mat-row m n ++Return the @var{n}th row of matrix @var{m}. This is equivalent to ++@samp{(elt m n)}. For a slower but safer version, use @code{mrow}. ++(@xref{Extracting Elements}.) ++@end defun ++ ++@defun mat-col m n ++Return the @var{n}th column of matrix @var{m}, in the form of a vector. ++The arguments are not checked for correctness. ++@end defun ++ ++@defun mat-less-row m n ++Return a copy of matrix @var{m} with its @var{n}th row deleted. The ++number @var{n} must be in range from 1 to the number of rows in @var{m}. ++@end defun ++ ++@defun mat-less-col m n ++Return a copy of matrix @var{m} with its @var{n}th column deleted. ++@end defun ++ ++@defun transpose m ++Return the transpose of matrix @var{m}. ++@end defun ++ ++@defun flatten-vector v ++Flatten nested vector @var{v} into a vector of scalars. For example, ++if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}. ++@end defun ++ ++@defun copy-matrix m ++If @var{m} is a matrix, return a copy of @var{m}. This maps ++@code{copy-sequence} over the rows of @var{m}; in Lisp terms, each ++element of the result matrix will be @code{eq} to the corresponding ++element of @var{m}, but none of the @code{cons} cells that make up ++the structure of the matrix will be @code{eq}. If @var{m} is a plain ++vector, this is the same as @code{copy-sequence}. ++@end defun ++ ++@defun swap-rows m r1 r2 ++Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place. In ++other words, unlike most of the other functions described here, this ++function changes @var{m} itself rather than building up a new result ++matrix. The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)} ++is true, with the side effect of exchanging the first two rows of ++@var{m}. ++@end defun ++ ++@node Symbolic Lisp Functions, Formatting Lisp Functions, Vector Lisp Functions, Internals ++@subsubsection Symbolic Functions ++ ++@noindent ++The functions described here operate on symbolic formulas in the ++Calculator. ++ ++@defun calc-prepare-selection num ++Prepare a stack entry for selection operations. If @var{num} is ++omitted, the stack entry containing the cursor is used; otherwise, ++it is the number of the stack entry to use. This function stores ++useful information about the current stack entry into a set of ++variables. @code{calc-selection-cache-num} contains the number of ++the stack entry involved (equal to @var{num} if you specified it); ++@code{calc-selection-cache-entry} contains the stack entry as a ++list (such as @code{calc-top-list} would return with @code{entry} ++as the selection mode); and @code{calc-selection-cache-comp} contains ++a special ``tagged'' composition (@pxref{Formatting Lisp Functions}) ++which allows Calc to relate cursor positions in the buffer with ++their corresponding sub-formulas. ++ ++A slight complication arises in the selection mechanism because ++formulas may contain small integers. For example, in the vector ++@samp{[1, 2, 1]} the first and last elements are @code{eq} to each ++other; selections are recorded as the actual Lisp object that ++appears somewhere in the tree of the whole formula, but storing ++@code{1} would falsely select both @code{1}'s in the vector. So ++@code{calc-prepare-selection} also checks the stack entry and ++replaces any plain integers with ``complex number'' lists of the form ++@samp{(cplx @var{n} 0)}. This list will be displayed the same as a ++plain @var{n} and the change will be completely invisible to the ++user, but it will guarantee that no two sub-formulas of the stack ++entry will be @code{eq} to each other. Next time the stack entry ++is involved in a computation, @code{calc-normalize} will replace ++these lists with plain numbers again, again invisibly to the user. ++@end defun ++ ++@defun calc-encase-atoms x ++This modifies the formula @var{x} to ensure that each part of the ++formula is a unique atom, using the @samp{(cplx @var{n} 0)} trick ++described above. This function may use @code{setcar} to modify ++the formula in-place. ++@end defun ++ ++@defun calc-find-selected-part ++Find the smallest sub-formula of the current formula that contains ++the cursor. This assumes @code{calc-prepare-selection} has been ++called already. If the cursor is not actually on any part of the ++formula, this returns @code{nil}. ++@end defun ++ ++@defun calc-change-current-selection selection ++Change the currently prepared stack element's selection to ++@var{selection}, which should be @code{eq} to some sub-formula ++of the stack element, or @code{nil} to unselect the formula. ++The stack element's appearance in the Calc buffer is adjusted ++to reflect the new selection. ++@end defun ++ ++@defun calc-find-nth-part expr n ++Return the @var{n}th sub-formula of @var{expr}. This function is used ++by the selection commands, and (unless @kbd{j b} has been used) treats ++sums and products as flat many-element formulas. Thus if @var{expr} ++is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with ++@var{n} equal to four will return @samp{d}. ++@end defun ++ ++@defun calc-find-parent-formula expr part ++Return the sub-formula of @var{expr} which immediately contains ++@var{part}. If @var{expr} is @samp{a*b + (c+1)*d} and @var{part} ++is @code{eq} to the @samp{c+1} term of @var{expr}, then this function ++will return @samp{(c+1)*d}. If @var{part} turns out not to be a ++sub-formula of @var{expr}, the function returns @code{nil}. If ++@var{part} is @code{eq} to @var{expr}, the function returns @code{t}. ++This function does not take associativity into account. ++@end defun ++ ++@defun calc-find-assoc-parent-formula expr part ++This is the same as @code{calc-find-parent-formula}, except that ++(unless @kbd{j b} has been used) it continues widening the selection ++to contain a complete level of the formula. Given @samp{a} from ++@samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will ++return @samp{a + b} but @code{calc-find-assoc-parent-formula} will ++return the whole expression. ++@end defun ++ ++@defun calc-grow-assoc-formula expr part ++This expands sub-formula @var{part} of @var{expr} to encompass a ++complete level of the formula. If @var{part} and its immediate ++parent are not compatible associative operators, or if @kbd{j b} ++has been used, this simply returns @var{part}. ++@end defun ++ ++@defun calc-find-sub-formula expr part ++This finds the immediate sub-formula of @var{expr} which contains ++@var{part}. It returns an index @var{n} such that ++@samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}. ++If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}. ++If @var{part} is @code{eq} to @var{expr}, it returns @code{t}. This ++function does not take associativity into account. ++@end defun ++ ++@defun calc-replace-sub-formula expr old new ++This function returns a copy of formula @var{expr}, with the ++sub-formula that is @code{eq} to @var{old} replaced by @var{new}. ++@end defun ++ ++@defun simplify expr ++Simplify the expression @var{expr} by applying various algebraic rules. ++This is what the @w{@kbd{a s}} (@code{calc-simplify}) command uses. This ++always returns a copy of the expression; the structure @var{expr} points ++to remains unchanged in memory. ++ ++More precisely, here is what @code{simplify} does: The expression is ++first normalized and evaluated by calling @code{normalize}. If any ++@code{AlgSimpRules} have been defined, they are then applied. Then ++the expression is traversed in a depth-first, bottom-up fashion; at ++each level, any simplifications that can be made are made until no ++further changes are possible. Once the entire formula has been ++traversed in this way, it is compared with the original formula (from ++before the call to @code{normalize}) and, if it has changed, ++the entire procedure is repeated (starting with @code{normalize}) ++until no further changes occur. Usually only two iterations are ++needed:@: one to simplify the formula, and another to verify that no ++further simplifications were possible. ++@end defun ++ ++@defun simplify-extended expr ++Simplify the expression @var{expr}, with additional rules enabled that ++help do a more thorough job, while not being entirely ``safe'' in all ++circumstances. (For example, this mode will simplify @samp{sqrt(x^2)} ++to @samp{x}, which is only valid when @var{x} is positive.) This is ++implemented by temporarily binding the variable @code{math-living-dangerously} ++to @code{t} (using a @code{let} form) and calling @code{simplify}. ++Dangerous simplification rules are written to check this variable ++before taking any action. ++@end defun ++ ++@defun simplify-units expr ++Simplify the expression @var{expr}, treating variable names as units ++whenever possible. This works by binding the variable ++@code{math-simplifying-units} to @code{t} while calling @code{simplify}. ++@end defun ++ ++@defmac math-defsimplify funcs body ++Register a new simplification rule; this is normally called as a top-level ++form, like @code{defun} or @code{defmath}. If @var{funcs} is a symbol ++(like @code{+} or @code{calcFunc-sqrt}), this simplification rule is ++applied to the formulas which are calls to the specified function. Or, ++@var{funcs} can be a list of such symbols; the rule applies to all ++functions on the list. The @var{body} is written like the body of a ++function with a single argument called @code{expr}. The body will be ++executed with @code{expr} bound to a formula which is a call to one of ++the functions @var{funcs}. If the function body returns @code{nil}, or ++if it returns a result @code{equal} to the original @code{expr}, it is ++ignored and Calc goes on to try the next simplification rule that applies. ++If the function body returns something different, that new formula is ++substituted for @var{expr} in the original formula. ++ ++At each point in the formula, rules are tried in the order of the ++original calls to @code{math-defsimplify}; the search stops after the ++first rule that makes a change. Thus later rules for that same ++function will not have a chance to trigger until the next iteration ++of the main @code{simplify} loop. ++ ++Note that, since @code{defmath} is not being used here, @var{body} must ++be written in true Lisp code without the conveniences that @code{defmath} ++provides. If you prefer, you can have @var{body} simply call another ++function (defined with @code{defmath}) which does the real work. ++ ++The arguments of a function call will already have been simplified ++before any rules for the call itself are invoked. Since a new argument ++list is consed up when this happens, this means that the rule's body is ++allowed to rearrange the function's arguments destructively if that is ++convenient. Here is a typical example of a simplification rule: ++ ++@smallexample ++(math-defsimplify calcFunc-arcsinh ++ (or (and (math-looks-negp (nth 1 expr)) ++ (math-neg (list 'calcFunc-arcsinh ++ (math-neg (nth 1 expr))))) ++ (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh) ++ (or math-living-dangerously ++ (math-known-realp (nth 1 (nth 1 expr)))) ++ (nth 1 (nth 1 expr))))) ++@end smallexample ++ ++This is really a pair of rules written with one @code{math-defsimplify} ++for convenience; the first replaces @samp{arcsinh(-x)} with ++@samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x}, ++replaces @samp{arcsinh(sinh(x))} with @samp{x}. ++@end defmac ++ ++@defun common-constant-factor expr ++Check @var{expr} to see if it is a sum of terms all multiplied by the ++same rational value. If so, return this value. If not, return @code{nil}. ++For example, if called on @samp{6x + 9y + 12z}, it would return 3, since ++3 is a common factor of all the terms. ++@end defun ++ ++@defun cancel-common-factor expr factor ++Assuming @var{expr} is a sum with @var{factor} as a common factor, ++divide each term of the sum by @var{factor}. This is done by ++destructively modifying parts of @var{expr}, on the assumption that ++it is being used by a simplification rule (where such things are ++allowed; see above). For example, consider this built-in rule for ++square roots: ++ ++@smallexample ++(math-defsimplify calcFunc-sqrt ++ (let ((fac (math-common-constant-factor (nth 1 expr)))) ++ (and fac (not (eq fac 1)) ++ (math-mul (math-normalize (list 'calcFunc-sqrt fac)) ++ (math-normalize ++ (list 'calcFunc-sqrt ++ (math-cancel-common-factor ++ (nth 1 expr) fac))))))) ++@end smallexample ++@end defun ++ ++@defun frac-gcd a b ++Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be ++rational numbers. This is the fraction composed of the GCD of the ++numerators of @var{a} and @var{b}, over the GCD of the denominators. ++It is used by @code{common-constant-factor}. Note that the standard ++@code{gcd} function uses the LCM to combine the denominators. ++@end defun ++ ++@defun map-tree func expr many ++Try applying Lisp function @var{func} to various sub-expressions of ++@var{expr}. Initially, call @var{func} with @var{expr} itself as an ++argument. If this returns an expression which is not @code{equal} to ++@var{expr}, apply @var{func} again until eventually it does return ++@var{expr} with no changes. Then, if @var{expr} is a function call, ++recursively apply @var{func} to each of the arguments. This keeps going ++until no changes occur anywhere in the expression; this final expression ++is returned by @code{map-tree}. Note that, unlike simplification rules, ++@var{func} functions may @emph{not} make destructive changes to ++@var{expr}. If a third argument @var{many} is provided, it is an ++integer which says how many times @var{func} may be applied; the ++default, as described above, is infinitely many times. ++@end defun ++ ++@defun compile-rewrites rules ++Compile the rewrite rule set specified by @var{rules}, which should ++be a formula that is either a vector or a variable name. If the latter, ++the compiled rules are saved so that later @code{compile-rules} calls ++for that same variable can return immediately. If there are problems ++with the rules, this function calls @code{error} with a suitable ++message. ++@end defun ++ ++@defun apply-rewrites expr crules heads ++Apply the compiled rewrite rule set @var{crules} to the expression ++@var{expr}. This will make only one rewrite and only checks at the ++top level of the expression. The result @code{nil} if no rules ++matched, or if the only rules that matched did not actually change ++the expression. The @var{heads} argument is optional; if is given, ++it should be a list of all function names that (may) appear in ++@var{expr}. The rewrite compiler tags each rule with the ++rarest-looking function name in the rule; if you specify @var{heads}, ++@code{apply-rewrites} can use this information to narrow its search ++down to just a few rules in the rule set. ++@end defun ++ ++@defun rewrite-heads expr ++Compute a @var{heads} list for @var{expr} suitable for use with ++@code{apply-rewrites}, as discussed above. ++@end defun ++ ++@defun rewrite expr rules many ++This is an all-in-one rewrite function. It compiles the rule set ++specified by @var{rules}, then uses @code{map-tree} to apply the ++rules throughout @var{expr} up to @var{many} (default infinity) ++times. ++@end defun ++ ++@defun match-patterns pat vec not-flag ++Given a Calc vector @var{vec} and an uncompiled pattern set or ++pattern set variable @var{pat}, this function returns a new vector ++of all elements of @var{vec} which do (or don't, if @var{not-flag} is ++non-@code{nil}) match any of the patterns in @var{pat}. ++@end defun ++ ++@defun deriv expr var value symb ++Compute the derivative of @var{expr} with respect to variable @var{var} ++(which may actually be any sub-expression). If @var{value} is specified, ++the derivative is evaluated at the value of @var{var}; otherwise, the ++derivative is left in terms of @var{var}. If the expression contains ++functions for which no derivative formula is known, new derivative ++functions are invented by adding primes to the names; @pxref{Calculus}. ++However, if @var{symb} is non-@code{nil}, the presence of undifferentiable ++functions in @var{expr} instead cancels the whole differentiation, and ++@code{deriv} returns @code{nil} instead. ++ ++Derivatives of an @var{n}-argument function can be defined by ++adding a @code{math-derivative-@var{n}} property to the property list ++of the symbol for the function's derivative, which will be the ++function name followed by an apostrophe. The value of the property ++should be a Lisp function; it is called with the same arguments as the ++original function call that is being differentiated. It should return ++a formula for the derivative. For example, the derivative of @code{ln} ++is defined by ++ ++@smallexample ++(put 'calcFunc-ln\' 'math-derivative-1 ++ (function (lambda (u) (math-div 1 u)))) ++@end smallexample ++ ++The two-argument @code{log} function has two derivatives, ++@smallexample ++(put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx ++ (function (lambda (x b) ... ))) ++(put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db ++ (function (lambda (x b) ... ))) ++@end smallexample ++@end defun ++ ++@defun tderiv expr var value symb ++Compute the total derivative of @var{expr}. This is the same as ++@code{deriv}, except that variables other than @var{var} are not ++assumed to be constant with respect to @var{var}. ++@end defun ++ ++@defun integ expr var low high ++Compute the integral of @var{expr} with respect to @var{var}. ++@xref{Calculus}, for further details. ++@end defun ++ ++@defmac math-defintegral funcs body ++Define a rule for integrating a function or functions of one argument; ++this macro is very similar in format to @code{math-defsimplify}. ++The main difference is that here @var{body} is the body of a function ++with a single argument @code{u} which is bound to the argument to the ++function being integrated, not the function call itself. Also, the ++variable of integration is available as @code{math-integ-var}. If ++evaluation of the integral requires doing further integrals, the body ++should call @samp{(math-integral @var{x})} to find the integral of ++@var{x} with respect to @code{math-integ-var}; this function returns ++@code{nil} if the integral could not be done. Some examples: ++ ++@smallexample ++(math-defintegral calcFunc-conj ++ (let ((int (math-integral u))) ++ (and int ++ (list 'calcFunc-conj int)))) ++ ++(math-defintegral calcFunc-cos ++ (and (equal u math-integ-var) ++ (math-from-radians-2 (list 'calcFunc-sin u)))) ++@end smallexample ++ ++In the @code{cos} example, we define only the integral of @samp{cos(x) dx}, ++relying on the general integration-by-substitution facility to handle ++cosines of more complicated arguments. An integration rule should return ++@code{nil} if it can't do the integral; if several rules are defined for ++the same function, they are tried in order until one returns a non-@code{nil} ++result. ++@end defmac ++ ++@defmac math-defintegral-2 funcs body ++Define a rule for integrating a function or functions of two arguments. ++This is exactly analogous to @code{math-defintegral}, except that @var{body} ++is written as the body of a function with two arguments, @var{u} and ++@var{v}. ++@end defmac ++ ++@defun solve-for lhs rhs var full ++Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating ++the variable @var{var} on the lefthand side; return the resulting righthand ++side, or @code{nil} if the equation cannot be solved. The variable ++@var{var} must appear at least once in @var{lhs} or @var{rhs}. Note that ++the return value is a formula which does not contain @var{var}; this is ++different from the user-level @code{solve} and @code{finv} functions, ++which return a rearranged equation or a functional inverse, respectively. ++If @var{full} is non-@code{nil}, a full solution including dummy signs ++and dummy integers will be produced. User-defined inverses are provided ++as properties in a manner similar to derivatives: ++ ++@smallexample ++(put 'calcFunc-ln 'math-inverse ++ (function (lambda (x) (list 'calcFunc-exp x)))) ++@end smallexample ++ ++This function can call @samp{(math-solve-get-sign @var{x})} to create ++a new arbitrary sign variable, returning @var{x} times that sign, and ++@samp{(math-solve-get-int @var{x})} to create a new arbitrary integer ++variable multiplied by @var{x}. These functions simply return @var{x} ++if the caller requested a non-``full'' solution. ++@end defun ++ ++@defun solve-eqn expr var full ++This version of @code{solve-for} takes an expression which will ++typically be an equation or inequality. (If it is not, it will be ++interpreted as the equation @samp{@var{expr} = 0}.) It returns an ++equation or inequality, or @code{nil} if no solution could be found. ++@end defun ++ ++@defun solve-system exprs vars full ++This function solves a system of equations. Generally, @var{exprs} ++and @var{vars} will be vectors of equal length. ++@xref{Solving Systems of Equations}, for other options. ++@end defun ++ ++@defun expr-contains expr var ++Returns a non-@code{nil} value if @var{var} occurs as a subexpression ++of @var{expr}. ++ ++This function might seem at first to be identical to ++@code{calc-find-sub-formula}. The key difference is that ++@code{expr-contains} uses @code{equal} to test for matches, whereas ++@code{calc-find-sub-formula} uses @code{eq}. In the formula ++@samp{f(a, a)}, the two @samp{a}s will be @code{equal} but not ++@code{eq} to each other. ++@end defun ++ ++@defun expr-contains-count expr var ++Returns the number of occurrences of @var{var} as a subexpression ++of @var{expr}, or @code{nil} if there are no occurrences. ++@end defun ++ ++@defun expr-depends expr var ++Returns true if @var{expr} refers to any variable the occurs in @var{var}. ++In other words, it checks if @var{expr} and @var{var} have any variables ++in common. ++@end defun ++ ++@defun expr-contains-vars expr ++Return true if @var{expr} contains any variables, or @code{nil} if @var{expr} ++contains only constants and functions with constant arguments. ++@end defun ++ ++@defun expr-subst expr old new ++Returns a copy of @var{expr}, with all occurrences of @var{old} replaced ++by @var{new}. This treats @code{lambda} forms specially with respect ++to the dummy argument variables, so that the effect is always to return ++@var{expr} evaluated at @var{old} = @var{new}. ++@end defun ++ ++@defun multi-subst expr old new ++This is like @code{expr-subst}, except that @var{old} and @var{new} ++are lists of expressions to be substituted simultaneously. If one ++list is shorter than the other, trailing elements of the longer list ++are ignored. ++@end defun ++ ++@defun expr-weight expr ++Returns the ``weight'' of @var{expr}, basically a count of the total ++number of objects and function calls that appear in @var{expr}. For ++``primitive'' objects, this will be one. ++@end defun ++ ++@defun expr-height expr ++Returns the ``height'' of @var{expr}, which is the deepest level to ++which function calls are nested. (Note that @samp{@var{a} + @var{b}} ++counts as a function call.) For primitive objects, this returns zero. ++@end defun ++ ++@defun polynomial-p expr var ++Check if @var{expr} is a polynomial in variable (or sub-expression) ++@var{var}. If so, return the degree of the polynomial, that is, the ++highest power of @var{var} that appears in @var{expr}. For example, ++for @samp{(x^2 + 3)^3 + 4} this would return 6. This function returns ++@code{nil} unless @var{expr}, when expanded out by @kbd{a x} ++(@code{calc-expand}), would consist of a sum of terms in which @var{var} ++appears only raised to nonnegative integer powers. Note that if ++@var{var} does not occur in @var{expr}, then @var{expr} is considered ++a polynomial of degree 0. ++@end defun ++ ++@defun is-polynomial expr var degree loose ++Check if @var{expr} is a polynomial in variable or sub-expression ++@var{var}, and, if so, return a list representation of the polynomial ++where the elements of the list are coefficients of successive powers of ++@var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the ++list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would ++produce the list @samp{(1 2 1)}. The highest element of the list will ++be non-zero, with the special exception that if @var{expr} is the ++constant zero, the returned value will be @samp{(0)}. Return @code{nil} ++if @var{expr} is not a polynomial in @var{var}. If @var{degree} is ++specified, this will not consider polynomials of degree higher than that ++value. This is a good precaution because otherwise an input of ++@samp{(x+1)^1000} will cause a huge coefficient list to be built. If ++@var{loose} is non-@code{nil}, then a looser definition of a polynomial ++is used in which coefficients are no longer required not to depend on ++@var{var}, but are only required not to take the form of polynomials ++themselves. For example, @samp{sin(x) x^2 + cos(x)} is a loose ++polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin ++x))}. The result will never be @code{nil} in loose mode, since any ++expression can be interpreted as a ``constant'' loose polynomial. ++@end defun ++ ++@defun polynomial-base expr pred ++Check if @var{expr} is a polynomial in any variable that occurs in it; ++if so, return that variable. (If @var{expr} is a multivariate polynomial, ++this chooses one variable arbitrarily.) If @var{pred} is specified, it should ++be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})}, ++and which should return true if @code{mpb-top-expr} (a global name for ++the original @var{expr}) is a suitable polynomial in @var{subexpr}. ++The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})}; ++you can use @var{pred} to specify additional conditions. Or, you could ++have @var{pred} build up a list of every suitable @var{subexpr} that ++is found. ++@end defun ++ ++@defun poly-simplify poly ++Simplify polynomial coefficient list @var{poly} by (destructively) ++clipping off trailing zeros. ++@end defun ++ ++@defun poly-mix a ac b bc ++Mix two polynomial lists @var{a} and @var{b} (in the form returned by ++@code{is-polynomial}) in a linear combination with coefficient expressions ++@var{ac} and @var{bc}. The result is a (not necessarily simplified) ++polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}. ++@end defun ++ ++@defun poly-mul a b ++Multiply two polynomial coefficient lists @var{a} and @var{b}. The ++result will be in simplified form if the inputs were simplified. ++@end defun ++ ++@defun build-polynomial-expr poly var ++Construct a Calc formula which represents the polynomial coefficient ++list @var{poly} applied to variable @var{var}. The @kbd{a c} ++(@code{calc-collect}) command uses @code{is-polynomial} to turn an ++expression into a coefficient list, then @code{build-polynomial-expr} ++to turn the list back into an expression in regular form. ++@end defun ++ ++@defun check-unit-name var ++Check if @var{var} is a variable which can be interpreted as a unit ++name. If so, return the units table entry for that unit. This ++will be a list whose first element is the unit name (not counting ++prefix characters) as a symbol and whose second element is the ++Calc expression which defines the unit. (Refer to the Calc sources ++for details on the remaining elements of this list.) If @var{var} ++is not a variable or is not a unit name, return @code{nil}. ++@end defun ++ ++@defun units-in-expr-p expr sub-exprs ++Return true if @var{expr} contains any variables which can be ++interpreted as units. If @var{sub-exprs} is @code{t}, the entire ++expression is searched. If @var{sub-exprs} is @code{nil}, this ++checks whether @var{expr} is directly a units expression. ++@end defun ++ ++@defun single-units-in-expr-p expr ++Check whether @var{expr} contains exactly one units variable. If so, ++return the units table entry for the variable. If @var{expr} does ++not contain any units, return @code{nil}. If @var{expr} contains ++two or more units, return the symbol @code{wrong}. ++@end defun ++ ++@defun to-standard-units expr which ++Convert units expression @var{expr} to base units. If @var{which} ++is @code{nil}, use Calc's native base units. Otherwise, @var{which} ++can specify a units system, which is a list of two-element lists, ++where the first element is a Calc base symbol name and the second ++is an expression to substitute for it. ++@end defun ++ ++@defun remove-units expr ++Return a copy of @var{expr} with all units variables replaced by ones. ++This expression is generally normalized before use. ++@end defun ++ ++@defun extract-units expr ++Return a copy of @var{expr} with everything but units variables replaced ++by ones. ++@end defun ++ ++@node Formatting Lisp Functions, Hooks, Symbolic Lisp Functions, Internals ++@subsubsection I/O and Formatting Functions ++ ++@noindent ++The functions described here are responsible for parsing and formatting ++Calc numbers and formulas. ++ ++@defun calc-eval str sep arg1 arg2 @dots{} ++This is the simplest interface to the Calculator from another Lisp program. ++@xref{Calling Calc from Your Programs}. ++@end defun ++ ++@defun read-number str ++If string @var{str} contains a valid Calc number, either integer, ++fraction, float, or HMS form, this function parses and returns that ++number. Otherwise, it returns @code{nil}. ++@end defun ++ ++@defun read-expr str ++Read an algebraic expression from string @var{str}. If @var{str} does ++not have the form of a valid expression, return a list of the form ++@samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index ++into @var{str} of the general location of the error, and @var{msg} is ++a string describing the problem. ++@end defun ++ ++@defun read-exprs str ++Read a list of expressions separated by commas, and return it as a ++Lisp list. If an error occurs in any expressions, an error list as ++shown above is returned instead. ++@end defun ++ ++@defun calc-do-alg-entry initial prompt no-norm ++Read an algebraic formula or formulas using the minibuffer. All ++conventions of regular algebraic entry are observed. The return value ++is a list of Calc formulas; there will be more than one if the user ++entered a list of values separated by commas. The result is @code{nil} ++if the user presses Return with a blank line. If @var{initial} is ++given, it is a string which the minibuffer will initially contain. ++If @var{prompt} is given, it is the prompt string to use; the default ++is ``Algebraic:''. If @var{no-norm} is @code{t}, the formulas will ++be returned exactly as parsed; otherwise, they will be passed through ++@code{calc-normalize} first. ++ ++To support the use of @kbd{$} characters in the algebraic entry, use ++@code{let} to bind @code{calc-dollar-values} to a list of the values ++to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind ++@code{calc-dollar-used} to 0. Upon return, @code{calc-dollar-used} ++will have been changed to the highest number of consecutive @kbd{$}s ++that actually appeared in the input. ++@end defun ++ ++@defun format-number a ++Convert the real or complex number or HMS form @var{a} to string form. ++@end defun ++ ++@defun format-flat-expr a prec ++Convert the arbitrary Calc number or formula @var{a} to string form, ++in the style used by the trail buffer and the @code{calc-edit} command. ++This is a simple format designed ++mostly to guarantee the string is of a form that can be re-parsed by ++@code{read-expr}. Most formatting modes, such as digit grouping, ++complex number format, and point character, are ignored to ensure the ++result will be re-readable. The @var{prec} parameter is normally 0; if ++you pass a large integer like 1000 instead, the expression will be ++surrounded by parentheses unless it is a plain number or variable name. ++@end defun ++ ++@defun format-nice-expr a width ++This is like @code{format-flat-expr} (with @var{prec} equal to 0), ++except that newlines will be inserted to keep lines down to the ++specified @var{width}, and vectors that look like matrices or rewrite ++rules are written in a pseudo-matrix format. The @code{calc-edit} ++command uses this when only one stack entry is being edited. ++@end defun ++ ++@defun format-value a width ++Convert the Calc number or formula @var{a} to string form, using the ++format seen in the stack buffer. Beware the string returned may ++not be re-readable by @code{read-expr}, for example, because of digit ++grouping. Multi-line objects like matrices produce strings that ++contain newline characters to separate the lines. The @var{w} ++parameter, if given, is the target window size for which to format ++the expressions. If @var{w} is omitted, the width of the Calculator ++window is used. ++@end defun ++ ++@defun compose-expr a prec ++Format the Calc number or formula @var{a} according to the current ++language mode, returning a ``composition.'' To learn about the ++structure of compositions, see the comments in the Calc source code. ++You can specify the format of a given type of function call by putting ++a @code{math-compose-@var{lang}} property on the function's symbol, ++whose value is a Lisp function that takes @var{a} and @var{prec} as ++arguments and returns a composition. Here @var{lang} is a language ++mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal}, ++@code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}. ++In Big mode, Calc actually tries @code{math-compose-big} first, then ++tries @code{math-compose-normal}. If this property does not exist, ++or if the function returns @code{nil}, the function is written in the ++normal function-call notation for that language. ++@end defun ++ ++@defun composition-to-string c w ++Convert a composition structure returned by @code{compose-expr} into ++a string. Multi-line compositions convert to strings containing ++newline characters. The target window size is given by @var{w}. ++The @code{format-value} function basically calls @code{compose-expr} ++followed by @code{composition-to-string}. ++@end defun ++ ++@defun comp-width c ++Compute the width in characters of composition @var{c}. ++@end defun ++ ++@defun comp-height c ++Compute the height in lines of composition @var{c}. ++@end defun ++ ++@defun comp-ascent c ++Compute the portion of the height of composition @var{c} which is on or ++above the baseline. For a one-line composition, this will be one. ++@end defun ++ ++@defun comp-descent c ++Compute the portion of the height of composition @var{c} which is below ++the baseline. For a one-line composition, this will be zero. ++@end defun ++ ++@defun comp-first-char c ++If composition @var{c} is a ``flat'' composition, return the first ++(leftmost) character of the composition as an integer. Otherwise, ++return @code{nil}. ++@end defun ++ ++@defun comp-last-char c ++If composition @var{c} is a ``flat'' composition, return the last ++(rightmost) character, otherwise return @code{nil}. ++@end defun ++ ++@comment @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals ++@comment @subsubsection Lisp Variables ++@comment ++@comment @noindent ++@comment (This section is currently unfinished.) ++ ++@node Hooks, , Formatting Lisp Functions, Internals ++@subsubsection Hooks ++ ++@noindent ++Hooks are variables which contain Lisp functions (or lists of functions) ++which are called at various times. Calc defines a number of hooks ++that help you to customize it in various ways. Calc uses the Lisp ++function @code{run-hooks} to invoke the hooks shown below. Several ++other customization-related variables are also described here. ++ ++@defvar calc-load-hook ++This hook is called at the end of @file{calc.el}, after the file has ++been loaded, before any functions in it have been called, but after ++@code{calc-mode-map} and similar variables have been set up. ++@end defvar ++ ++@defvar calc-ext-load-hook ++This hook is called at the end of @file{calc-ext.el}. ++@end defvar ++ ++@defvar calc-start-hook ++This hook is called as the last step in a @kbd{M-x calc} command. ++At this point, the Calc buffer has been created and initialized if ++necessary, the Calc window and trail window have been created, ++and the ``Welcome to Calc'' message has been displayed. ++@end defvar ++ ++@defvar calc-mode-hook ++This hook is called when the Calc buffer is being created. Usually ++this will only happen once per Emacs session. The hook is called ++after Emacs has switched to the new buffer, the mode-settings file ++has been read if necessary, and all other buffer-local variables ++have been set up. After this hook returns, Calc will perform a ++@code{calc-refresh} operation, set up the mode line display, then ++evaluate any deferred @code{calc-define} properties that have not ++been evaluated yet. ++@end defvar ++ ++@defvar calc-trail-mode-hook ++This hook is called when the Calc Trail buffer is being created. ++It is called as the very last step of setting up the Trail buffer. ++Like @code{calc-mode-hook}, this will normally happen only once ++per Emacs session. ++@end defvar ++ ++@defvar calc-end-hook ++This hook is called by @code{calc-quit}, generally because the user ++presses @kbd{q} or @kbd{C-x * c} while in Calc. The Calc buffer will ++be the current buffer. The hook is called as the very first ++step, before the Calc window is destroyed. ++@end defvar ++ ++@defvar calc-window-hook ++If this hook is non-@code{nil}, it is called to create the Calc window. ++Upon return, this new Calc window should be the current window. ++(The Calc buffer will already be the current buffer when the ++hook is called.) If the hook is not defined, Calc will ++generally use @code{split-window}, @code{set-window-buffer}, ++and @code{select-window} to create the Calc window. ++@end defvar ++ ++@defvar calc-trail-window-hook ++If this hook is non-@code{nil}, it is called to create the Calc Trail ++window. The variable @code{calc-trail-buffer} will contain the buffer ++which the window should use. Unlike @code{calc-window-hook}, this hook ++must @emph{not} switch into the new window. ++@end defvar ++ ++@defvar calc-embedded-mode-hook ++This hook is called the first time that Embedded mode is entered. ++@end defvar ++ ++@defvar calc-embedded-new-buffer-hook ++This hook is called each time that Embedded mode is entered in a ++new buffer. ++@end defvar ++ ++@defvar calc-embedded-new-formula-hook ++This hook is called each time that Embedded mode is enabled for a ++new formula. ++@end defvar ++ ++@defvar calc-edit-mode-hook ++This hook is called by @code{calc-edit} (and the other ``edit'' ++commands) when the temporary editing buffer is being created. ++The buffer will have been selected and set up to be in ++@code{calc-edit-mode}, but will not yet have been filled with ++text. (In fact it may still have leftover text from a previous ++@code{calc-edit} command.) ++@end defvar ++ ++@defvar calc-mode-save-hook ++This hook is called by the @code{calc-save-modes} command, ++after Calc's own mode features have been inserted into the ++Calc init file and just before the ``End of mode settings'' ++message is inserted. ++@end defvar ++ ++@defvar calc-reset-hook ++This hook is called after @kbd{C-x * 0} (@code{calc-reset}) has ++reset all modes. The Calc buffer will be the current buffer. ++@end defvar ++ ++@defvar calc-other-modes ++This variable contains a list of strings. The strings are ++concatenated at the end of the modes portion of the Calc ++mode line (after standard modes such as ``Deg'', ``Inv'' and ++``Hyp''). Each string should be a short, single word followed ++by a space. The variable is @code{nil} by default. ++@end defvar ++ ++@defvar calc-mode-map ++This is the keymap that is used by Calc mode. The best time ++to adjust it is probably in a @code{calc-mode-hook}. If the ++Calc extensions package (@file{calc-ext.el}) has not yet been ++loaded, many of these keys will be bound to @code{calc-missing-key}, ++which is a command that loads the extensions package and ++``retypes'' the key. If your @code{calc-mode-hook} rebinds ++one of these keys, it will probably be overridden when the ++extensions are loaded. ++@end defvar ++ ++@defvar calc-digit-map ++This is the keymap that is used during numeric entry. Numeric ++entry uses the minibuffer, but this map binds every non-numeric ++key to @code{calcDigit-nondigit} which generally calls ++@code{exit-minibuffer} and ``retypes'' the key. ++@end defvar ++ ++@defvar calc-alg-ent-map ++This is the keymap that is used during algebraic entry. This is ++mostly a copy of @code{minibuffer-local-map}. ++@end defvar ++ ++@defvar calc-store-var-map ++This is the keymap that is used during entry of variable names for ++commands like @code{calc-store} and @code{calc-recall}. This is ++mostly a copy of @code{minibuffer-local-completion-map}. ++@end defvar ++ ++@defvar calc-edit-mode-map ++This is the (sparse) keymap used by @code{calc-edit} and other ++temporary editing commands. It binds @key{RET}, @key{LFD}, ++and @kbd{C-c C-c} to @code{calc-edit-finish}. ++@end defvar ++ ++@defvar calc-mode-var-list ++This is a list of variables which are saved by @code{calc-save-modes}. ++Each entry is a list of two items, the variable (as a Lisp symbol) ++and its default value. When modes are being saved, each variable ++is compared with its default value (using @code{equal}) and any ++non-default variables are written out. ++@end defvar ++ ++@defvar calc-local-var-list ++This is a list of variables which should be buffer-local to the ++Calc buffer. Each entry is a variable name (as a Lisp symbol). ++These variables also have their default values manipulated by ++the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}. ++Since @code{calc-mode-hook} is called after this list has been ++used the first time, your hook should add a variable to the ++list and also call @code{make-local-variable} itself. ++@end defvar ++ ++@node Copying, GNU Free Documentation License, Programming, Top ++@appendix GNU GENERAL PUBLIC LICENSE ++@include gpl.texi ++ ++@node GNU Free Documentation License, Customizing Calc, Copying, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Customizing Calc, Reporting Bugs, GNU Free Documentation License, Top ++@appendix Customizing Calc ++ ++The usual prefix for Calc is the key sequence @kbd{C-x *}. If you wish ++to use a different prefix, you can put ++ ++@example ++(global-set-key "NEWPREFIX" 'calc-dispatch) ++@end example ++ ++@noindent ++in your .emacs file. ++(@xref{Key Bindings,,Customizing Key Bindings,emacs, ++The GNU Emacs Manual}, for more information on binding keys.) ++A convenient way to start Calc is with @kbd{C-x * *}; to make it equally ++convenient for users who use a different prefix, the prefix can be ++followed by @kbd{=}, @kbd{&}, @kbd{#}, @kbd{\}, @kbd{/}, @kbd{+} or ++@kbd{-} as well as @kbd{*} to start Calc, and so in many cases the last ++character of the prefix can simply be typed twice. ++ ++Calc is controlled by many variables, most of which can be reset ++from within Calc. Some variables are less involved with actual ++calculation, and can be set outside of Calc using Emacs's ++customization facilities. These variables are listed below. ++Typing @kbd{M-x customize-variable RET @var{variable-name} RET} ++will bring up a buffer in which the variable's value can be redefined. ++Typing @kbd{M-x customize-group RET calc RET} will bring up a buffer which ++contains all of Calc's customizable variables. (These variables can ++also be reset by putting the appropriate lines in your .emacs file; ++@xref{Init File, ,Init File, emacs, The GNU Emacs Manual}.) ++ ++Some of the customizable variables are regular expressions. A regular ++expression is basically a pattern that Calc can search for. ++See @ref{Regexp Search,, Regular Expression Search, emacs, The GNU Emacs Manual} ++to see how regular expressions work. ++ ++@defvar calc-settings-file ++The variable @code{calc-settings-file} holds the file name in ++which commands like @kbd{m m} and @kbd{Z P} store ``permanent'' ++definitions. ++If @code{calc-settings-file} is not your user init file (typically ++@file{~/.emacs}) and if the variable @code{calc-loaded-settings-file} is ++@code{nil}, then Calc will automatically load your settings file (if it ++exists) the first time Calc is invoked. ++ ++The default value for this variable is @code{"~/.calc.el"}. ++@end defvar ++ ++@defvar calc-gnuplot-name ++See @ref{Graphics}.@* ++The variable @code{calc-gnuplot-name} should be the name of the ++GNUPLOT program (a string). If you have GNUPLOT installed on your ++system but Calc is unable to find it, you may need to set this ++variable. You may also need to set some Lisp variables to show Calc how ++to run GNUPLOT on your system, see @ref{Devices, ,Graphical Devices} . ++The default value of @code{calc-gnuplot-name} is @code{"gnuplot"}. ++@end defvar ++ ++@defvar calc-gnuplot-plot-command ++@defvarx calc-gnuplot-print-command ++See @ref{Devices, ,Graphical Devices}.@* ++The variables @code{calc-gnuplot-plot-command} and ++@code{calc-gnuplot-print-command} represent system commands to ++display and print the output of GNUPLOT, respectively. These may be ++@code{nil} if no command is necessary, or strings which can include ++@samp{%s} to signify the name of the file to be displayed or printed. ++Or, these variables may contain Lisp expressions which are evaluated ++to display or print the output. ++ ++The default value of @code{calc-gnuplot-plot-command} is @code{nil}, ++and the default value of @code{calc-gnuplot-print-command} is ++@code{"lp %s"}. ++@end defvar ++ ++@defvar calc-language-alist ++See @ref{Basic Embedded Mode}.@* ++The variable @code{calc-language-alist} controls the languages that ++Calc will associate with major modes. When Calc embedded mode is ++enabled, it will try to use the current major mode to ++determine what language should be used. (This can be overridden using ++Calc's mode changing commands, @xref{Mode Settings in Embedded Mode}.) ++The variable @code{calc-language-alist} consists of a list of pairs of ++the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example, ++@code{(latex-mode . latex)} is one such pair. If Calc embedded is ++activated in a buffer whose major mode is @var{MAJOR-MODE}, it will set itself ++to use the language @var{LANGUAGE}. ++ ++The default value of @code{calc-language-alist} is ++@example ++ ((latex-mode . latex) ++ (tex-mode . tex) ++ (plain-tex-mode . tex) ++ (context-mode . tex) ++ (nroff-mode . eqn) ++ (pascal-mode . pascal) ++ (c-mode . c) ++ (c++-mode . c) ++ (fortran-mode . fortran) ++ (f90-mode . fortran)) ++@end example ++@end defvar ++ ++@defvar calc-embedded-announce-formula ++@defvarx calc-embedded-announce-formula-alist ++See @ref{Customizing Embedded Mode}.@* ++The variable @code{calc-embedded-announce-formula} helps determine ++what formulas @kbd{C-x * a} will activate in a buffer. It is a ++regular expression, and when activating embedded formulas with ++@kbd{C-x * a}, it will tell Calc that what follows is a formula to be ++activated. (Calc also uses other patterns to find formulas, such as ++@samp{=>} and @samp{:=}.) ++ ++The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which checks ++for @samp{%Embed} followed by any number of lines beginning with ++@samp{%} and a space. ++ ++The variable @code{calc-embedded-announce-formula-alist} is used to ++set @code{calc-embedded-announce-formula} to different regular ++expressions depending on the major mode of the editing buffer. ++It consists of a list of pairs of the form @code{(@var{MAJOR-MODE} . ++@var{REGEXP})}, and its default value is ++@example ++ ((c++-mode . "//Embed\n\\(// .*\n\\)*") ++ (c-mode . "/\\*Embed\\*/\n\\(/\\* .*\\*/\n\\)*") ++ (f90-mode . "!Embed\n\\(! .*\n\\)*") ++ (fortran-mode . "C Embed\n\\(C .*\n\\)*") ++ (html-helper-mode . "\n\\(\n\\)*") ++ (html-mode . "\n\\(\n\\)*") ++ (nroff-mode . "\\\\\"Embed\n\\(\\\\\" .*\n\\)*") ++ (pascal-mode . "@{Embed@}\n\\(@{.*@}\n\\)*") ++ (sgml-mode . "\n\\(\n\\)*") ++ (xml-mode . "\n\\(\n\\)*") ++ (texinfo-mode . "@@c Embed\n\\(@@c .*\n\\)*")) ++@end example ++Any major modes added to @code{calc-embedded-announce-formula-alist} ++should also be added to @code{calc-embedded-open-close-plain-alist} ++and @code{calc-embedded-open-close-mode-alist}. ++@end defvar ++ ++@defvar calc-embedded-open-formula ++@defvarx calc-embedded-close-formula ++@defvarx calc-embedded-open-close-formula-alist ++See @ref{Customizing Embedded Mode}.@* ++The variables @code{calc-embedded-open-formula} and ++@code{calc-embedded-close-formula} control the region that Calc will ++activate as a formula when Embedded mode is entered with @kbd{C-x * e}. ++They are regular expressions; ++Calc normally scans backward and forward in the buffer for the ++nearest text matching these regular expressions to be the ``formula ++delimiters''. ++ ++The simplest delimiters are blank lines. Other delimiters that ++Embedded mode understands by default are: ++@enumerate ++@item ++The @TeX{} and La@TeX{} math delimiters @samp{$ $}, @samp{$$ $$}, ++@samp{\[ \]}, and @samp{\( \)}; ++@item ++Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); ++@item ++Lines beginning with @samp{@@} (Texinfo delimiters). ++@item ++Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); ++@item ++Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. ++@end enumerate ++ ++The variable @code{calc-embedded-open-close-formula-alist} is used to ++set @code{calc-embedded-open-formula} and ++@code{calc-embedded-close-formula} to different regular ++expressions depending on the major mode of the editing buffer. ++It consists of a list of lists of the form ++@code{(@var{MAJOR-MODE} @var{OPEN-FORMULA-REGEXP} ++@var{CLOSE-FORMULA-REGEXP})}, and its default value is ++@code{nil}. ++@end defvar ++ ++@defvar calc-embedded-word-regexp ++@defvarx calc-embedded-word-regexp-alist ++See @ref{Customizing Embedded Mode}.@* ++The variable @code{calc-embedded-word-regexp} determines the expression ++that Calc will activate when Embedded mode is entered with @kbd{C-x * ++w}. It is a regular expressions. ++ ++The default value of @code{calc-embedded-word-regexp} is ++@code{"[-+]?[0-9]+\\(\\.[0-9]+\\)?\\([eE][-+]?[0-9]+\\)?"}. ++ ++The variable @code{calc-embedded-word-regexp-alist} is used to ++set @code{calc-embedded-word-regexp} to a different regular ++expression depending on the major mode of the editing buffer. ++It consists of a list of lists of the form ++@code{(@var{MAJOR-MODE} @var{WORD-REGEXP})}, and its default value is ++@code{nil}. ++@end defvar ++ ++@defvar calc-embedded-open-plain ++@defvarx calc-embedded-close-plain ++@defvarx calc-embedded-open-close-plain-alist ++See @ref{Customizing Embedded Mode}.@* ++The variables @code{calc-embedded-open-plain} and ++@code{calc-embedded-open-plain} are used to delimit ``plain'' ++formulas. Note that these are actual strings, not regular ++expressions, because Calc must be able to write these string into a ++buffer as well as to recognize them. ++ ++The default string for @code{calc-embedded-open-plain} is ++@code{"%%% "}, note the trailing space. The default string for ++@code{calc-embedded-close-plain} is @code{" %%%\n"}, without ++the trailing newline here, the first line of a Big mode formula ++that followed might be shifted over with respect to the other lines. ++ ++The variable @code{calc-embedded-open-close-plain-alist} is used to ++set @code{calc-embedded-open-plain} and ++@code{calc-embedded-close-plain} to different strings ++depending on the major mode of the editing buffer. ++It consists of a list of lists of the form ++@code{(@var{MAJOR-MODE} @var{OPEN-PLAIN-STRING} ++@var{CLOSE-PLAIN-STRING})}, and its default value is ++@example ++ ((c++-mode "// %% " " %%\n") ++ (c-mode "/* %% " " %% */\n") ++ (f90-mode "! %% " " %%\n") ++ (fortran-mode "C %% " " %%\n") ++ (html-helper-mode "\n") ++ (html-mode "\n") ++ (nroff-mode "\\\" %% " " %%\n") ++ (pascal-mode "@{%% " " %%@}\n") ++ (sgml-mode "\n") ++ (xml-mode "\n") ++ (texinfo-mode "@@c %% " " %%\n")) ++@end example ++Any major modes added to @code{calc-embedded-open-close-plain-alist} ++should also be added to @code{calc-embedded-announce-formula-alist} ++and @code{calc-embedded-open-close-mode-alist}. ++@end defvar ++ ++@defvar calc-embedded-open-new-formula ++@defvarx calc-embedded-close-new-formula ++@defvarx calc-embedded-open-close-new-formula-alist ++See @ref{Customizing Embedded Mode}.@* ++The variables @code{calc-embedded-open-new-formula} and ++@code{calc-embedded-close-new-formula} are strings which are ++inserted before and after a new formula when you type @kbd{C-x * f}. ++ ++The default value of @code{calc-embedded-open-new-formula} is ++@code{"\n\n"}. If this string begins with a newline character and the ++@kbd{C-x * f} is typed at the beginning of a line, @kbd{C-x * f} will skip ++this first newline to avoid introducing unnecessary blank lines in the ++file. The default value of @code{calc-embedded-close-new-formula} is ++also @code{"\n\n"}. The final newline is omitted by @w{@kbd{C-x * f}} ++if typed at the end of a line. (It follows that if @kbd{C-x * f} is ++typed on a blank line, both a leading opening newline and a trailing ++closing newline are omitted.) ++ ++The variable @code{calc-embedded-open-close-new-formula-alist} is used to ++set @code{calc-embedded-open-new-formula} and ++@code{calc-embedded-close-new-formula} to different strings ++depending on the major mode of the editing buffer. ++It consists of a list of lists of the form ++@code{(@var{MAJOR-MODE} @var{OPEN-NEW-FORMULA-STRING} ++@var{CLOSE-NEW-FORMULA-STRING})}, and its default value is ++@code{nil}. ++@end defvar ++ ++@defvar calc-embedded-open-mode ++@defvarx calc-embedded-close-mode ++@defvarx calc-embedded-open-close-mode-alist ++See @ref{Customizing Embedded Mode}.@* ++The variables @code{calc-embedded-open-mode} and ++@code{calc-embedded-close-mode} are strings which Calc will place before ++and after any mode annotations that it inserts. Calc never scans for ++these strings; Calc always looks for the annotation itself, so it is not ++necessary to add them to user-written annotations. ++ ++The default value of @code{calc-embedded-open-mode} is @code{"% "} ++and the default value of @code{calc-embedded-close-mode} is ++@code{"\n"}. ++If you change the value of @code{calc-embedded-close-mode}, it is a good ++idea still to end with a newline so that mode annotations will appear on ++lines by themselves. ++ ++The variable @code{calc-embedded-open-close-mode-alist} is used to ++set @code{calc-embedded-open-mode} and ++@code{calc-embedded-close-mode} to different strings ++expressions depending on the major mode of the editing buffer. ++It consists of a list of lists of the form ++@code{(@var{MAJOR-MODE} @var{OPEN-MODE-STRING} ++@var{CLOSE-MODE-STRING})}, and its default value is ++@example ++ ((c++-mode "// " "\n") ++ (c-mode "/* " " */\n") ++ (f90-mode "! " "\n") ++ (fortran-mode "C " "\n") ++ (html-helper-mode "\n") ++ (html-mode "\n") ++ (nroff-mode "\\\" " "\n") ++ (pascal-mode "@{ " " @}\n") ++ (sgml-mode "\n") ++ (xml-mode "\n") ++ (texinfo-mode "@@c " "\n")) ++@end example ++Any major modes added to @code{calc-embedded-open-close-mode-alist} ++should also be added to @code{calc-embedded-announce-formula-alist} ++and @code{calc-embedded-open-close-plain-alist}. ++@end defvar ++ ++@defvar calc-multiplication-has-precedence ++The variable @code{calc-multiplication-has-precedence} determines ++whether multiplication has precedence over division in algebraic ++formulas in normal language modes. If ++@code{calc-multiplication-has-precedence} is non-@code{nil}, then ++multiplication has precedence (and, for certain obscure reasons, is ++right associative), and so for example @samp{a/b*c} will be interpreted ++as @samp{a/(b*c)}. If @code{calc-multiplication-has-precedence} is ++@code{nil}, then multiplication has the same precedence as division ++(and, like division, is left associative), and so for example ++@samp{a/b*c} will be interpreted as @samp{(a/b)*c}. The default value ++of @code{calc-multiplication-has-precedence} is @code{t}. ++@end defvar ++ ++@node Reporting Bugs, Summary, Customizing Calc, Top ++@appendix Reporting Bugs ++ ++@noindent ++If you find a bug in Calc, send e-mail to Jay Belanger, ++ ++@example ++jay.p.belanger@@gmail.com ++@end example ++ ++@noindent ++There is an automatic command @kbd{M-x report-calc-bug} which helps ++you to report bugs. This command prompts you for a brief subject ++line, then leaves you in a mail editing buffer. Type @kbd{C-c C-c} to ++send your mail. Make sure your subject line indicates that you are ++reporting a Calc bug; this command sends mail to the maintainer's ++regular mailbox. ++ ++If you have suggestions for additional features for Calc, please send ++them. Some have dared to suggest that Calc is already top-heavy with ++features; this obviously cannot be the case, so if you have ideas, send ++them right in. ++ ++At the front of the source file, @file{calc.el}, is a list of ideas for ++future work. If any enthusiastic souls wish to take it upon themselves ++to work on these, please send a message (using @kbd{M-x report-calc-bug}) ++so any efforts can be coordinated. ++ ++The latest version of Calc is available from Savannah, in the Emacs ++CVS tree. See @uref{http://savannah.gnu.org/projects/emacs}. ++ ++@c [summary] ++@node Summary, Key Index, Reporting Bugs, Top ++@appendix Calc Summary ++ ++@noindent ++This section includes a complete list of Calc keystroke commands. ++Each line lists the stack entries used by the command (top-of-stack ++last), the keystrokes themselves, the prompts asked by the command, ++and the result of the command (also with top-of-stack last). ++The result is expressed using the equivalent algebraic function. ++Commands which put no results on the stack show the full @kbd{M-x} ++command name in that position. Numbers preceding the result or ++command name refer to notes at the end. ++ ++Algebraic functions and @kbd{M-x} commands that don't have corresponding ++keystrokes are not listed in this summary. ++@xref{Command Index}. @xref{Function Index}. ++ ++@iftex ++@begingroup ++@tex ++\vskip-2\baselineskip \null ++\gdef\sumrow#1{\sumrowx#1\relax}% ++\gdef\sumrowx#1\:#2\:#3\:#4\:#5\:#6\relax{% ++\leavevmode% ++{\smallfonts ++\hbox to5em{\sl\hss#1}% ++\hbox to5em{\tt#2\hss}% ++\hbox to4em{\sl#3\hss}% ++\hbox to5em{\rm\hss#4}% ++\thinspace% ++{\tt#5}% ++{\sl#6}% ++}}% ++\gdef\sumlpar{{\rm(}}% ++\gdef\sumrpar{{\rm)}}% ++\gdef\sumcomma{{\rm,\thinspace}}% ++\gdef\sumexcl{{\rm!}}% ++\gdef\sumbreak{\vskip-2.5\baselineskip\goodbreak}% ++\gdef\minus#1{{\tt-}}% ++@end tex ++@let@:=@sumsep ++@let@r=@sumrow ++@catcode`@(=@active @let(=@sumlpar ++@catcode`@)=@active @let)=@sumrpar ++@catcode`@,=@active @let,=@sumcomma ++@catcode`@!=@active @let!=@sumexcl ++@end iftex ++@format ++@iftex ++@advance@baselineskip-2.5pt ++@let@c@sumbreak ++@end iftex ++@r{ @: C-x * a @: @: 33 @:calc-embedded-activate@:} ++@r{ @: C-x * b @: @: @:calc-big-or-small@:} ++@r{ @: C-x * c @: @: @:calc@:} ++@r{ @: C-x * d @: @: @:calc-embedded-duplicate@:} ++@r{ @: C-x * e @: @: 34 @:calc-embedded@:} ++@r{ @: C-x * f @:formula @: @:calc-embedded-new-formula@:} ++@r{ @: C-x * g @: @: 35 @:calc-grab-region@:} ++@r{ @: C-x * i @: @: @:calc-info@:} ++@r{ @: C-x * j @: @: @:calc-embedded-select@:} ++@r{ @: C-x * k @: @: @:calc-keypad@:} ++@r{ @: C-x * l @: @: @:calc-load-everything@:} ++@r{ @: C-x * m @: @: @:read-kbd-macro@:} ++@r{ @: C-x * n @: @: 4 @:calc-embedded-next@:} ++@r{ @: C-x * o @: @: @:calc-other-window@:} ++@r{ @: C-x * p @: @: 4 @:calc-embedded-previous@:} ++@r{ @: C-x * q @:formula @: @:quick-calc@:} ++@r{ @: C-x * r @: @: 36 @:calc-grab-rectangle@:} ++@r{ @: C-x * s @: @: @:calc-info-summary@:} ++@r{ @: C-x * t @: @: @:calc-tutorial@:} ++@r{ @: C-x * u @: @: @:calc-embedded-update-formula@:} ++@r{ @: C-x * w @: @: @:calc-embedded-word@:} ++@r{ @: C-x * x @: @: @:calc-quit@:} ++@r{ @: C-x * y @: @:1,28,49 @:calc-copy-to-buffer@:} ++@r{ @: C-x * z @: @: @:calc-user-invocation@:} ++@r{ @: C-x * : @: @: 36 @:calc-grab-sum-down@:} ++@r{ @: C-x * _ @: @: 36 @:calc-grab-sum-across@:} ++@r{ @: C-x * ` @:editing @: 30 @:calc-embedded-edit@:} ++@r{ @: C-x * 0 @:(zero) @: @:calc-reset@:} ++ ++@c ++@r{ @: 0-9 @:number @: @:@:number} ++@r{ @: . @:number @: @:@:0.number} ++@r{ @: _ @:number @: @:-@:number} ++@r{ @: e @:number @: @:@:1e number} ++@r{ @: # @:number @: @:@:current-radix@tfn{#}number} ++@r{ @: P @:(in number) @: @:+/-@:} ++@r{ @: M @:(in number) @: @:mod@:} ++@r{ @: @@ ' " @: (in number)@: @:@:HMS form} ++@r{ @: h m s @: (in number)@: @:@:HMS form} ++ ++@c ++@r{ @: ' @:formula @: 37,46 @:@:formula} ++@r{ @: $ @:formula @: 37,46 @:$@:formula} ++@r{ @: " @:string @: 37,46 @:@:string} ++ ++@c ++@r{ a b@: + @: @: 2 @:add@:(a,b) a+b} ++@r{ a b@: - @: @: 2 @:sub@:(a,b) a@minus{}b} ++@r{ a b@: * @: @: 2 @:mul@:(a,b) a b, a*b} ++@r{ a b@: / @: @: 2 @:div@:(a,b) a/b} ++@r{ a b@: ^ @: @: 2 @:pow@:(a,b) a^b} ++@r{ a b@: I ^ @: @: 2 @:nroot@:(a,b) a^(1/b)} ++@r{ a b@: % @: @: 2 @:mod@:(a,b) a%b} ++@r{ a b@: \ @: @: 2 @:idiv@:(a,b) a\b} ++@r{ a b@: : @: @: 2 @:fdiv@:(a,b)} ++@r{ a b@: | @: @: 2 @:vconcat@:(a,b) a|b} ++@r{ a b@: I | @: @: @:vconcat@:(b,a) b|a} ++@r{ a b@: H | @: @: 2 @:append@:(a,b)} ++@r{ a b@: I H | @: @: @:append@:(b,a)} ++@r{ a@: & @: @: 1 @:inv@:(a) 1/a} ++@r{ a@: ! @: @: 1 @:fact@:(a) a!} ++@r{ a@: = @: @: 1 @:evalv@:(a)} ++@r{ a@: M-% @: @: @:percent@:(a) a%} ++ ++@c ++@r{ ... a@: @summarykey{RET} @: @: 1 @:@:... a a} ++@r{ ... a@: @summarykey{SPC} @: @: 1 @:@:... a a} ++@r{... a b@: @summarykey{TAB} @: @: 3 @:@:... b a} ++@r{. a b c@: M-@summarykey{TAB} @: @: 3 @:@:... b c a} ++@r{... a b@: @summarykey{LFD} @: @: 1 @:@:... a b a} ++@r{ ... a@: @summarykey{DEL} @: @: 1 @:@:...} ++@r{... a b@: M-@summarykey{DEL} @: @: 1 @:@:... b} ++@r{ @: M-@summarykey{RET} @: @: 4 @:calc-last-args@:} ++@r{ a@: ` @:editing @: 1,30 @:calc-edit@:} ++ ++@c ++@r{ ... a@: C-d @: @: 1 @:@:...} ++@r{ @: C-k @: @: 27 @:calc-kill@:} ++@r{ @: C-w @: @: 27 @:calc-kill-region@:} ++@r{ @: C-y @: @: @:calc-yank@:} ++@r{ @: C-_ @: @: 4 @:calc-undo@:} ++@r{ @: M-k @: @: 27 @:calc-copy-as-kill@:} ++@r{ @: M-w @: @: 27 @:calc-copy-region-as-kill@:} ++ ++@c ++@r{ @: [ @: @: @:@:[...} ++@r{[.. a b@: ] @: @: @:@:[a,b]} ++@r{ @: ( @: @: @:@:(...} ++@r{(.. a b@: ) @: @: @:@:(a,b)} ++@r{ @: , @: @: @:@:vector or rect complex} ++@r{ @: ; @: @: @:@:matrix or polar complex} ++@r{ @: .. @: @: @:@:interval} ++ ++@c ++@r{ @: ~ @: @: @:calc-num-prefix@:} ++@r{ @: < @: @: 4 @:calc-scroll-left@:} ++@r{ @: > @: @: 4 @:calc-scroll-right@:} ++@r{ @: @{ @: @: 4 @:calc-scroll-down@:} ++@r{ @: @} @: @: 4 @:calc-scroll-up@:} ++@r{ @: ? @: @: @:calc-help@:} ++ ++@c ++@r{ a@: n @: @: 1 @:neg@:(a) @minus{}a} ++@r{ @: o @: @: 4 @:calc-realign@:} ++@r{ @: p @:precision @: 31 @:calc-precision@:} ++@r{ @: q @: @: @:calc-quit@:} ++@r{ @: w @: @: @:calc-why@:} ++@r{ @: x @:command @: @:M-x calc-@:command} ++@r{ a@: y @: @:1,28,49 @:calc-copy-to-buffer@:} ++ ++@c ++@r{ a@: A @: @: 1 @:abs@:(a)} ++@r{ a b@: B @: @: 2 @:log@:(a,b)} ++@r{ a b@: I B @: @: 2 @:alog@:(a,b) b^a} ++@r{ a@: C @: @: 1 @:cos@:(a)} ++@r{ a@: I C @: @: 1 @:arccos@:(a)} ++@r{ a@: H C @: @: 1 @:cosh@:(a)} ++@r{ a@: I H C @: @: 1 @:arccosh@:(a)} ++@r{ @: D @: @: 4 @:calc-redo@:} ++@r{ a@: E @: @: 1 @:exp@:(a)} ++@r{ a@: H E @: @: 1 @:exp10@:(a) 10.^a} ++@r{ a@: F @: @: 1,11 @:floor@:(a,d)} ++@r{ a@: I F @: @: 1,11 @:ceil@:(a,d)} ++@r{ a@: H F @: @: 1,11 @:ffloor@:(a,d)} ++@r{ a@: I H F @: @: 1,11 @:fceil@:(a,d)} ++@r{ a@: G @: @: 1 @:arg@:(a)} ++@r{ @: H @:command @: 32 @:@:Hyperbolic} ++@r{ @: I @:command @: 32 @:@:Inverse} ++@r{ a@: J @: @: 1 @:conj@:(a)} ++@r{ @: K @:command @: 32 @:@:Keep-args} ++@r{ a@: L @: @: 1 @:ln@:(a)} ++@r{ a@: H L @: @: 1 @:log10@:(a)} ++@r{ @: M @: @: @:calc-more-recursion-depth@:} ++@r{ @: I M @: @: @:calc-less-recursion-depth@:} ++@r{ a@: N @: @: 5 @:evalvn@:(a)} ++@r{ @: P @: @: @:@:pi} ++@r{ @: I P @: @: @:@:gamma} ++@r{ @: H P @: @: @:@:e} ++@r{ @: I H P @: @: @:@:phi} ++@r{ a@: Q @: @: 1 @:sqrt@:(a)} ++@r{ a@: I Q @: @: 1 @:sqr@:(a) a^2} ++@r{ a@: R @: @: 1,11 @:round@:(a,d)} ++@r{ a@: I R @: @: 1,11 @:trunc@:(a,d)} ++@r{ a@: H R @: @: 1,11 @:fround@:(a,d)} ++@r{ a@: I H R @: @: 1,11 @:ftrunc@:(a,d)} ++@r{ a@: S @: @: 1 @:sin@:(a)} ++@r{ a@: I S @: @: 1 @:arcsin@:(a)} ++@r{ a@: H S @: @: 1 @:sinh@:(a)} ++@r{ a@: I H S @: @: 1 @:arcsinh@:(a)} ++@r{ a@: T @: @: 1 @:tan@:(a)} ++@r{ a@: I T @: @: 1 @:arctan@:(a)} ++@r{ a@: H T @: @: 1 @:tanh@:(a)} ++@r{ a@: I H T @: @: 1 @:arctanh@:(a)} ++@r{ @: U @: @: 4 @:calc-undo@:} ++@r{ @: X @: @: 4 @:calc-call-last-kbd-macro@:} ++ ++@c ++@r{ a b@: a = @: @: 2 @:eq@:(a,b) a=b} ++@r{ a b@: a # @: @: 2 @:neq@:(a,b) a!=b} ++@r{ a b@: a < @: @: 2 @:lt@:(a,b) a @: @: 2 @:gt@:(a,b) a>b} ++@r{ a b@: a [ @: @: 2 @:leq@:(a,b) a<=b} ++@r{ a b@: a ] @: @: 2 @:geq@:(a,b) a>=b} ++@r{ a b@: a @{ @: @: 2 @:in@:(a,b)} ++@r{ a b@: a & @: @: 2,45 @:land@:(a,b) a&&b} ++@r{ a b@: a | @: @: 2,45 @:lor@:(a,b) a||b} ++@r{ a@: a ! @: @: 1,45 @:lnot@:(a) !a} ++@r{ a b c@: a : @: @: 45 @:if@:(a,b,c) a?b:c} ++@r{ a@: a . @: @: 1 @:rmeq@:(a)} ++@r{ a@: a " @: @: 7,8 @:calc-expand-formula@:} ++ ++@c ++@r{ a@: a + @:i, l, h @: 6,38 @:sum@:(a,i,l,h)} ++@r{ a@: a - @:i, l, h @: 6,38 @:asum@:(a,i,l,h)} ++@r{ a@: a * @:i, l, h @: 6,38 @:prod@:(a,i,l,h)} ++@r{ a b@: a _ @: @: 2 @:subscr@:(a,b) a_b} ++ ++@c ++@r{ a b@: a \ @: @: 2 @:pdiv@:(a,b)} ++@r{ a b@: a % @: @: 2 @:prem@:(a,b)} ++@r{ a b@: a / @: @: 2 @:pdivrem@:(a,b) [q,r]} ++@r{ a b@: H a / @: @: 2 @:pdivide@:(a,b) q+r/b} ++ ++@c ++@r{ a@: a a @: @: 1 @:apart@:(a)} ++@r{ a@: a b @:old, new @: 38 @:subst@:(a,old,new)} ++@r{ a@: a c @:v @: 38 @:collect@:(a,v)} ++@r{ a@: a d @:v @: 4,38 @:deriv@:(a,v)} ++@r{ a@: H a d @:v @: 4,38 @:tderiv@:(a,v)} ++@r{ a@: a e @: @: @:esimplify@:(a)} ++@r{ a@: a f @: @: 1 @:factor@:(a)} ++@r{ a@: H a f @: @: 1 @:factors@:(a)} ++@r{ a b@: a g @: @: 2 @:pgcd@:(a,b)} ++@r{ a@: a i @:v @: 38 @:integ@:(a,v)} ++@r{ a@: a m @:pats @: 38 @:match@:(a,pats)} ++@r{ a@: I a m @:pats @: 38 @:matchnot@:(a,pats)} ++@r{ data x@: a p @: @: 28 @:polint@:(data,x)} ++@r{ data x@: H a p @: @: 28 @:ratint@:(data,x)} ++@r{ a@: a n @: @: 1 @:nrat@:(a)} ++@r{ a@: a r @:rules @:4,8,38 @:rewrite@:(a,rules,n)} ++@r{ a@: a s @: @: @:simplify@:(a)} ++@r{ a@: a t @:v, n @: 31,39 @:taylor@:(a,v,n)} ++@r{ a@: a v @: @: 7,8 @:calc-alg-evaluate@:} ++@r{ a@: a x @: @: 4,8 @:expand@:(a)} ++ ++@c ++@r{ data@: a F @:model, vars @: 48 @:fit@:(m,iv,pv,data)} ++@r{ data@: I a F @:model, vars @: 48 @:xfit@:(m,iv,pv,data)} ++@r{ data@: H a F @:model, vars @: 48 @:efit@:(m,iv,pv,data)} ++@r{ a@: a I @:v, l, h @: 38 @:ninteg@:(a,v,l,h)} ++@r{ a b@: a M @:op @: 22 @:mapeq@:(op,a,b)} ++@r{ a b@: I a M @:op @: 22 @:mapeqr@:(op,a,b)} ++@r{ a b@: H a M @:op @: 22 @:mapeqp@:(op,a,b)} ++@r{ a g@: a N @:v @: 38 @:minimize@:(a,v,g)} ++@r{ a g@: H a N @:v @: 38 @:wminimize@:(a,v,g)} ++@r{ a@: a P @:v @: 38 @:roots@:(a,v)} ++@r{ a g@: a R @:v @: 38 @:root@:(a,v,g)} ++@r{ a g@: H a R @:v @: 38 @:wroot@:(a,v,g)} ++@r{ a@: a S @:v @: 38 @:solve@:(a,v)} ++@r{ a@: I a S @:v @: 38 @:finv@:(a,v)} ++@r{ a@: H a S @:v @: 38 @:fsolve@:(a,v)} ++@r{ a@: I H a S @:v @: 38 @:ffinv@:(a,v)} ++@r{ a@: a T @:i, l, h @: 6,38 @:table@:(a,i,l,h)} ++@r{ a g@: a X @:v @: 38 @:maximize@:(a,v,g)} ++@r{ a g@: H a X @:v @: 38 @:wmaximize@:(a,v,g)} ++ ++@c ++@r{ a b@: b a @: @: 9 @:and@:(a,b,w)} ++@r{ a@: b c @: @: 9 @:clip@:(a,w)} ++@r{ a b@: b d @: @: 9 @:diff@:(a,b,w)} ++@r{ a@: b l @: @: 10 @:lsh@:(a,n,w)} ++@r{ a n@: H b l @: @: 9 @:lsh@:(a,n,w)} ++@r{ a@: b n @: @: 9 @:not@:(a,w)} ++@r{ a b@: b o @: @: 9 @:or@:(a,b,w)} ++@r{ v@: b p @: @: 1 @:vpack@:(v)} ++@r{ a@: b r @: @: 10 @:rsh@:(a,n,w)} ++@r{ a n@: H b r @: @: 9 @:rsh@:(a,n,w)} ++@r{ a@: b t @: @: 10 @:rot@:(a,n,w)} ++@r{ a n@: H b t @: @: 9 @:rot@:(a,n,w)} ++@r{ a@: b u @: @: 1 @:vunpack@:(a)} ++@r{ @: b w @:w @: 9,50 @:calc-word-size@:} ++@r{ a b@: b x @: @: 9 @:xor@:(a,b,w)} ++ ++@c ++@r{c s l p@: b D @: @: @:ddb@:(c,s,l,p)} ++@r{ r n p@: b F @: @: @:fv@:(r,n,p)} ++@r{ r n p@: I b F @: @: @:fvb@:(r,n,p)} ++@r{ r n p@: H b F @: @: @:fvl@:(r,n,p)} ++@r{ v@: b I @: @: 19 @:irr@:(v)} ++@r{ v@: I b I @: @: 19 @:irrb@:(v)} ++@r{ a@: b L @: @: 10 @:ash@:(a,n,w)} ++@r{ a n@: H b L @: @: 9 @:ash@:(a,n,w)} ++@r{ r n a@: b M @: @: @:pmt@:(r,n,a)} ++@r{ r n a@: I b M @: @: @:pmtb@:(r,n,a)} ++@r{ r n a@: H b M @: @: @:pmtl@:(r,n,a)} ++@r{ r v@: b N @: @: 19 @:npv@:(r,v)} ++@r{ r v@: I b N @: @: 19 @:npvb@:(r,v)} ++@r{ r n p@: b P @: @: @:pv@:(r,n,p)} ++@r{ r n p@: I b P @: @: @:pvb@:(r,n,p)} ++@r{ r n p@: H b P @: @: @:pvl@:(r,n,p)} ++@r{ a@: b R @: @: 10 @:rash@:(a,n,w)} ++@r{ a n@: H b R @: @: 9 @:rash@:(a,n,w)} ++@r{ c s l@: b S @: @: @:sln@:(c,s,l)} ++@r{ n p a@: b T @: @: @:rate@:(n,p,a)} ++@r{ n p a@: I b T @: @: @:rateb@:(n,p,a)} ++@r{ n p a@: H b T @: @: @:ratel@:(n,p,a)} ++@r{c s l p@: b Y @: @: @:syd@:(c,s,l,p)} ++ ++@r{ r p a@: b # @: @: @:nper@:(r,p,a)} ++@r{ r p a@: I b # @: @: @:nperb@:(r,p,a)} ++@r{ r p a@: H b # @: @: @:nperl@:(r,p,a)} ++@r{ a b@: b % @: @: @:relch@:(a,b)} ++ ++@c ++@r{ a@: c c @: @: 5 @:pclean@:(a,p)} ++@r{ a@: c 0-9 @: @: @:pclean@:(a,p)} ++@r{ a@: H c c @: @: 5 @:clean@:(a,p)} ++@r{ a@: H c 0-9 @: @: @:clean@:(a,p)} ++@r{ a@: c d @: @: 1 @:deg@:(a)} ++@r{ a@: c f @: @: 1 @:pfloat@:(a)} ++@r{ a@: H c f @: @: 1 @:float@:(a)} ++@r{ a@: c h @: @: 1 @:hms@:(a)} ++@r{ a@: c p @: @: @:polar@:(a)} ++@r{ a@: I c p @: @: @:rect@:(a)} ++@r{ a@: c r @: @: 1 @:rad@:(a)} ++ ++@c ++@r{ a@: c F @: @: 5 @:pfrac@:(a,p)} ++@r{ a@: H c F @: @: 5 @:frac@:(a,p)} ++ ++@c ++@r{ a@: c % @: @: @:percent@:(a*100)} ++ ++@c ++@r{ @: d . @:char @: 50 @:calc-point-char@:} ++@r{ @: d , @:char @: 50 @:calc-group-char@:} ++@r{ @: d < @: @: 13,50 @:calc-left-justify@:} ++@r{ @: d = @: @: 13,50 @:calc-center-justify@:} ++@r{ @: d > @: @: 13,50 @:calc-right-justify@:} ++@r{ @: d @{ @:label @: 50 @:calc-left-label@:} ++@r{ @: d @} @:label @: 50 @:calc-right-label@:} ++@r{ @: d [ @: @: 4 @:calc-truncate-up@:} ++@r{ @: d ] @: @: 4 @:calc-truncate-down@:} ++@r{ @: d " @: @: 12,50 @:calc-display-strings@:} ++@r{ @: d @summarykey{SPC} @: @: @:calc-refresh@:} ++@r{ @: d @summarykey{RET} @: @: 1 @:calc-refresh-top@:} ++ ++@c ++@r{ @: d 0 @: @: 50 @:calc-decimal-radix@:} ++@r{ @: d 2 @: @: 50 @:calc-binary-radix@:} ++@r{ @: d 6 @: @: 50 @:calc-hex-radix@:} ++@r{ @: d 8 @: @: 50 @:calc-octal-radix@:} ++ ++@c ++@r{ @: d b @: @:12,13,50 @:calc-line-breaking@:} ++@r{ @: d c @: @: 50 @:calc-complex-notation@:} ++@r{ @: d d @:format @: 50 @:calc-date-notation@:} ++@r{ @: d e @: @: 5,50 @:calc-eng-notation@:} ++@r{ @: d f @:num @: 31,50 @:calc-fix-notation@:} ++@r{ @: d g @: @:12,13,50 @:calc-group-digits@:} ++@r{ @: d h @:format @: 50 @:calc-hms-notation@:} ++@r{ @: d i @: @: 50 @:calc-i-notation@:} ++@r{ @: d j @: @: 50 @:calc-j-notation@:} ++@r{ @: d l @: @: 12,50 @:calc-line-numbering@:} ++@r{ @: d n @: @: 5,50 @:calc-normal-notation@:} ++@r{ @: d o @:format @: 50 @:calc-over-notation@:} ++@r{ @: d p @: @: 12,50 @:calc-show-plain@:} ++@r{ @: d r @:radix @: 31,50 @:calc-radix@:} ++@r{ @: d s @: @: 5,50 @:calc-sci-notation@:} ++@r{ @: d t @: @: 27 @:calc-truncate-stack@:} ++@r{ @: d w @: @: 12,13 @:calc-auto-why@:} ++@r{ @: d z @: @: 12,50 @:calc-leading-zeros@:} ++ ++@c ++@r{ @: d B @: @: 50 @:calc-big-language@:} ++@r{ @: d C @: @: 50 @:calc-c-language@:} ++@r{ @: d E @: @: 50 @:calc-eqn-language@:} ++@r{ @: d F @: @: 50 @:calc-fortran-language@:} ++@r{ @: d M @: @: 50 @:calc-mathematica-language@:} ++@r{ @: d N @: @: 50 @:calc-normal-language@:} ++@r{ @: d O @: @: 50 @:calc-flat-language@:} ++@r{ @: d P @: @: 50 @:calc-pascal-language@:} ++@r{ @: d T @: @: 50 @:calc-tex-language@:} ++@r{ @: d L @: @: 50 @:calc-latex-language@:} ++@r{ @: d U @: @: 50 @:calc-unformatted-language@:} ++@r{ @: d W @: @: 50 @:calc-maple-language@:} ++ ++@c ++@r{ a@: f [ @: @: 4 @:decr@:(a,n)} ++@r{ a@: f ] @: @: 4 @:incr@:(a,n)} ++ ++@c ++@r{ a b@: f b @: @: 2 @:beta@:(a,b)} ++@r{ a@: f e @: @: 1 @:erf@:(a)} ++@r{ a@: I f e @: @: 1 @:erfc@:(a)} ++@r{ a@: f g @: @: 1 @:gamma@:(a)} ++@r{ a b@: f h @: @: 2 @:hypot@:(a,b)} ++@r{ a@: f i @: @: 1 @:im@:(a)} ++@r{ n a@: f j @: @: 2 @:besJ@:(n,a)} ++@r{ a b@: f n @: @: 2 @:min@:(a,b)} ++@r{ a@: f r @: @: 1 @:re@:(a)} ++@r{ a@: f s @: @: 1 @:sign@:(a)} ++@r{ a b@: f x @: @: 2 @:max@:(a,b)} ++@r{ n a@: f y @: @: 2 @:besY@:(n,a)} ++ ++@c ++@r{ a@: f A @: @: 1 @:abssqr@:(a)} ++@r{ x a b@: f B @: @: @:betaI@:(x,a,b)} ++@r{ x a b@: H f B @: @: @:betaB@:(x,a,b)} ++@r{ a@: f E @: @: 1 @:expm1@:(a)} ++@r{ a x@: f G @: @: 2 @:gammaP@:(a,x)} ++@r{ a x@: I f G @: @: 2 @:gammaQ@:(a,x)} ++@r{ a x@: H f G @: @: 2 @:gammag@:(a,x)} ++@r{ a x@: I H f G @: @: 2 @:gammaG@:(a,x)} ++@r{ a b@: f I @: @: 2 @:ilog@:(a,b)} ++@r{ a b@: I f I @: @: 2 @:alog@:(a,b) b^a} ++@r{ a@: f L @: @: 1 @:lnp1@:(a)} ++@r{ a@: f M @: @: 1 @:mant@:(a)} ++@r{ a@: f Q @: @: 1 @:isqrt@:(a)} ++@r{ a@: I f Q @: @: 1 @:sqr@:(a) a^2} ++@r{ a n@: f S @: @: 2 @:scf@:(a,n)} ++@r{ y x@: f T @: @: @:arctan2@:(y,x)} ++@r{ a@: f X @: @: 1 @:xpon@:(a)} ++ ++@c ++@r{ x y@: g a @: @: 28,40 @:calc-graph-add@:} ++@r{ @: g b @: @: 12 @:calc-graph-border@:} ++@r{ @: g c @: @: @:calc-graph-clear@:} ++@r{ @: g d @: @: 41 @:calc-graph-delete@:} ++@r{ x y@: g f @: @: 28,40 @:calc-graph-fast@:} ++@r{ @: g g @: @: 12 @:calc-graph-grid@:} ++@r{ @: g h @:title @: @:calc-graph-header@:} ++@r{ @: g j @: @: 4 @:calc-graph-juggle@:} ++@r{ @: g k @: @: 12 @:calc-graph-key@:} ++@r{ @: g l @: @: 12 @:calc-graph-log-x@:} ++@r{ @: g n @:name @: @:calc-graph-name@:} ++@r{ @: g p @: @: 42 @:calc-graph-plot@:} ++@r{ @: g q @: @: @:calc-graph-quit@:} ++@r{ @: g r @:range @: @:calc-graph-range-x@:} ++@r{ @: g s @: @: 12,13 @:calc-graph-line-style@:} ++@r{ @: g t @:title @: @:calc-graph-title-x@:} ++@r{ @: g v @: @: @:calc-graph-view-commands@:} ++@r{ @: g x @:display @: @:calc-graph-display@:} ++@r{ @: g z @: @: 12 @:calc-graph-zero-x@:} ++ ++@c ++@r{ x y z@: g A @: @: 28,40 @:calc-graph-add-3d@:} ++@r{ @: g C @:command @: @:calc-graph-command@:} ++@r{ @: g D @:device @: 43,44 @:calc-graph-device@:} ++@r{ x y z@: g F @: @: 28,40 @:calc-graph-fast-3d@:} ++@r{ @: g H @: @: 12 @:calc-graph-hide@:} ++@r{ @: g K @: @: @:calc-graph-kill@:} ++@r{ @: g L @: @: 12 @:calc-graph-log-y@:} ++@r{ @: g N @:number @: 43,51 @:calc-graph-num-points@:} ++@r{ @: g O @:filename @: 43,44 @:calc-graph-output@:} ++@r{ @: g P @: @: 42 @:calc-graph-print@:} ++@r{ @: g R @:range @: @:calc-graph-range-y@:} ++@r{ @: g S @: @: 12,13 @:calc-graph-point-style@:} ++@r{ @: g T @:title @: @:calc-graph-title-y@:} ++@r{ @: g V @: @: @:calc-graph-view-trail@:} ++@r{ @: g X @:format @: @:calc-graph-geometry@:} ++@r{ @: g Z @: @: 12 @:calc-graph-zero-y@:} ++ ++@c ++@r{ @: g C-l @: @: 12 @:calc-graph-log-z@:} ++@r{ @: g C-r @:range @: @:calc-graph-range-z@:} ++@r{ @: g C-t @:title @: @:calc-graph-title-z@:} ++ ++@c ++@r{ @: h b @: @: @:calc-describe-bindings@:} ++@r{ @: h c @:key @: @:calc-describe-key-briefly@:} ++@r{ @: h f @:function @: @:calc-describe-function@:} ++@r{ @: h h @: @: @:calc-full-help@:} ++@r{ @: h i @: @: @:calc-info@:} ++@r{ @: h k @:key @: @:calc-describe-key@:} ++@r{ @: h n @: @: @:calc-view-news@:} ++@r{ @: h s @: @: @:calc-info-summary@:} ++@r{ @: h t @: @: @:calc-tutorial@:} ++@r{ @: h v @:var @: @:calc-describe-variable@:} ++ ++@c ++@r{ @: j 1-9 @: @: @:calc-select-part@:} ++@r{ @: j @summarykey{RET} @: @: 27 @:calc-copy-selection@:} ++@r{ @: j @summarykey{DEL} @: @: 27 @:calc-del-selection@:} ++@r{ @: j ' @:formula @: 27 @:calc-enter-selection@:} ++@r{ @: j ` @:editing @: 27,30 @:calc-edit-selection@:} ++@r{ @: j " @: @: 7,27 @:calc-sel-expand-formula@:} ++ ++@c ++@r{ @: j + @:formula @: 27 @:calc-sel-add-both-sides@:} ++@r{ @: j - @:formula @: 27 @:calc-sel-sub-both-sides@:} ++@r{ @: j * @:formula @: 27 @:calc-sel-mul-both-sides@:} ++@r{ @: j / @:formula @: 27 @:calc-sel-div-both-sides@:} ++@r{ @: j & @: @: 27 @:calc-sel-invert@:} ++ ++@c ++@r{ @: j a @: @: 27 @:calc-select-additional@:} ++@r{ @: j b @: @: 12 @:calc-break-selections@:} ++@r{ @: j c @: @: @:calc-clear-selections@:} ++@r{ @: j d @: @: 12,50 @:calc-show-selections@:} ++@r{ @: j e @: @: 12 @:calc-enable-selections@:} ++@r{ @: j l @: @: 4,27 @:calc-select-less@:} ++@r{ @: j m @: @: 4,27 @:calc-select-more@:} ++@r{ @: j n @: @: 4 @:calc-select-next@:} ++@r{ @: j o @: @: 4,27 @:calc-select-once@:} ++@r{ @: j p @: @: 4 @:calc-select-previous@:} ++@r{ @: j r @:rules @:4,8,27 @:calc-rewrite-selection@:} ++@r{ @: j s @: @: 4,27 @:calc-select-here@:} ++@r{ @: j u @: @: 27 @:calc-unselect@:} ++@r{ @: j v @: @: 7,27 @:calc-sel-evaluate@:} ++ ++@c ++@r{ @: j C @: @: 27 @:calc-sel-commute@:} ++@r{ @: j D @: @: 4,27 @:calc-sel-distribute@:} ++@r{ @: j E @: @: 27 @:calc-sel-jump-equals@:} ++@r{ @: j I @: @: 27 @:calc-sel-isolate@:} ++@r{ @: H j I @: @: 27 @:calc-sel-isolate@: (full)} ++@r{ @: j L @: @: 4,27 @:calc-commute-left@:} ++@r{ @: j M @: @: 27 @:calc-sel-merge@:} ++@r{ @: j N @: @: 27 @:calc-sel-negate@:} ++@r{ @: j O @: @: 4,27 @:calc-select-once-maybe@:} ++@r{ @: j R @: @: 4,27 @:calc-commute-right@:} ++@r{ @: j S @: @: 4,27 @:calc-select-here-maybe@:} ++@r{ @: j U @: @: 27 @:calc-sel-unpack@:} ++ ++@c ++@r{ @: k a @: @: @:calc-random-again@:} ++@r{ n@: k b @: @: 1 @:bern@:(n)} ++@r{ n x@: H k b @: @: 2 @:bern@:(n,x)} ++@r{ n m@: k c @: @: 2 @:choose@:(n,m)} ++@r{ n m@: H k c @: @: 2 @:perm@:(n,m)} ++@r{ n@: k d @: @: 1 @:dfact@:(n) n!!} ++@r{ n@: k e @: @: 1 @:euler@:(n)} ++@r{ n x@: H k e @: @: 2 @:euler@:(n,x)} ++@r{ n@: k f @: @: 4 @:prfac@:(n)} ++@r{ n m@: k g @: @: 2 @:gcd@:(n,m)} ++@r{ m n@: k h @: @: 14 @:shuffle@:(n,m)} ++@r{ n m@: k l @: @: 2 @:lcm@:(n,m)} ++@r{ n@: k m @: @: 1 @:moebius@:(n)} ++@r{ n@: k n @: @: 4 @:nextprime@:(n)} ++@r{ n@: I k n @: @: 4 @:prevprime@:(n)} ++@r{ n@: k p @: @: 4,28 @:calc-prime-test@:} ++@r{ m@: k r @: @: 14 @:random@:(m)} ++@r{ n m@: k s @: @: 2 @:stir1@:(n,m)} ++@r{ n m@: H k s @: @: 2 @:stir2@:(n,m)} ++@r{ n@: k t @: @: 1 @:totient@:(n)} ++ ++@c ++@r{ n p x@: k B @: @: @:utpb@:(x,n,p)} ++@r{ n p x@: I k B @: @: @:ltpb@:(x,n,p)} ++@r{ v x@: k C @: @: @:utpc@:(x,v)} ++@r{ v x@: I k C @: @: @:ltpc@:(x,v)} ++@r{ n m@: k E @: @: @:egcd@:(n,m)} ++@r{v1 v2 x@: k F @: @: @:utpf@:(x,v1,v2)} ++@r{v1 v2 x@: I k F @: @: @:ltpf@:(x,v1,v2)} ++@r{ m s x@: k N @: @: @:utpn@:(x,m,s)} ++@r{ m s x@: I k N @: @: @:ltpn@:(x,m,s)} ++@r{ m x@: k P @: @: @:utpp@:(x,m)} ++@r{ m x@: I k P @: @: @:ltpp@:(x,m)} ++@r{ v x@: k T @: @: @:utpt@:(x,v)} ++@r{ v x@: I k T @: @: @:ltpt@:(x,v)} ++ ++@c ++@r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:} ++@r{ @: m d @: @: @:calc-degrees-mode@:} ++@r{ @: m e @: @: @:calc-embedded-preserve-modes@:} ++@r{ @: m f @: @: 12 @:calc-frac-mode@:} ++@r{ @: m g @: @: 52 @:calc-get-modes@:} ++@r{ @: m h @: @: @:calc-hms-mode@:} ++@r{ @: m i @: @: 12,13 @:calc-infinite-mode@:} ++@r{ @: m m @: @: @:calc-save-modes@:} ++@r{ @: m p @: @: 12 @:calc-polar-mode@:} ++@r{ @: m r @: @: @:calc-radians-mode@:} ++@r{ @: m s @: @: 12 @:calc-symbolic-mode@:} ++@r{ @: m t @: @: 12 @:calc-total-algebraic-mode@:} ++@r{ @: m v @: @: 12,13 @:calc-matrix-mode@:} ++@r{ @: m w @: @: 13 @:calc-working@:} ++@r{ @: m x @: @: @:calc-always-load-extensions@:} ++ ++@c ++@r{ @: m A @: @: 12 @:calc-alg-simplify-mode@:} ++@r{ @: m B @: @: 12 @:calc-bin-simplify-mode@:} ++@r{ @: m C @: @: 12 @:calc-auto-recompute@:} ++@r{ @: m D @: @: @:calc-default-simplify-mode@:} ++@r{ @: m E @: @: 12 @:calc-ext-simplify-mode@:} ++@r{ @: m F @:filename @: 13 @:calc-settings-file-name@:} ++@r{ @: m N @: @: 12 @:calc-num-simplify-mode@:} ++@r{ @: m O @: @: 12 @:calc-no-simplify-mode@:} ++@r{ @: m R @: @: 12,13 @:calc-mode-record-mode@:} ++@r{ @: m S @: @: 12 @:calc-shift-prefix@:} ++@r{ @: m U @: @: 12 @:calc-units-simplify-mode@:} ++ ++@c ++@r{ @: r s @:register @: 27 @:calc-copy-to-register@:} ++@r{ @: r i @:register @: @:calc-insert-register@:} ++ ++@c ++@r{ @: s c @:var1, var2 @: 29 @:calc-copy-variable@:} ++@r{ @: s d @:var, decl @: @:calc-declare-variable@:} ++@r{ @: s e @:var, editing @: 29,30 @:calc-edit-variable@:} ++@r{ @: s i @:buffer @: @:calc-insert-variables@:} ++@r{ @: s k @:const, var @: 29 @:calc-copy-special-constant@:} ++@r{ a b@: s l @:var @: 29 @:@:a (letting var=b)} ++@r{ a ...@: s m @:op, var @: 22,29 @:calc-store-map@:} ++@r{ @: s n @:var @: 29,47 @:calc-store-neg@: (v/-1)} ++@r{ @: s p @:var @: 29 @:calc-permanent-variable@:} ++@r{ @: s r @:var @: 29 @:@:v (recalled value)} ++@r{ @: r 0-9 @: @: @:calc-recall-quick@:} ++@r{ a@: s s @:var @: 28,29 @:calc-store@:} ++@r{ a@: s 0-9 @: @: @:calc-store-quick@:} ++@r{ a@: s t @:var @: 29 @:calc-store-into@:} ++@r{ a@: t 0-9 @: @: @:calc-store-into-quick@:} ++@r{ @: s u @:var @: 29 @:calc-unstore@:} ++@r{ a@: s x @:var @: 29 @:calc-store-exchange@:} ++ ++@c ++@r{ @: s A @:editing @: 30 @:calc-edit-AlgSimpRules@:} ++@r{ @: s D @:editing @: 30 @:calc-edit-Decls@:} ++@r{ @: s E @:editing @: 30 @:calc-edit-EvalRules@:} ++@r{ @: s F @:editing @: 30 @:calc-edit-FitRules@:} ++@r{ @: s G @:editing @: 30 @:calc-edit-GenCount@:} ++@r{ @: s H @:editing @: 30 @:calc-edit-Holidays@:} ++@r{ @: s I @:editing @: 30 @:calc-edit-IntegLimit@:} ++@r{ @: s L @:editing @: 30 @:calc-edit-LineStyles@:} ++@r{ @: s P @:editing @: 30 @:calc-edit-PointStyles@:} ++@r{ @: s R @:editing @: 30 @:calc-edit-PlotRejects@:} ++@r{ @: s T @:editing @: 30 @:calc-edit-TimeZone@:} ++@r{ @: s U @:editing @: 30 @:calc-edit-Units@:} ++@r{ @: s X @:editing @: 30 @:calc-edit-ExtSimpRules@:} ++ ++@c ++@r{ a@: s + @:var @: 29,47 @:calc-store-plus@: (v+a)} ++@r{ a@: s - @:var @: 29,47 @:calc-store-minus@: (v-a)} ++@r{ a@: s * @:var @: 29,47 @:calc-store-times@: (v*a)} ++@r{ a@: s / @:var @: 29,47 @:calc-store-div@: (v/a)} ++@r{ a@: s ^ @:var @: 29,47 @:calc-store-power@: (v^a)} ++@r{ a@: s | @:var @: 29,47 @:calc-store-concat@: (v|a)} ++@r{ @: s & @:var @: 29,47 @:calc-store-inv@: (v^-1)} ++@r{ @: s [ @:var @: 29,47 @:calc-store-decr@: (v-1)} ++@r{ @: s ] @:var @: 29,47 @:calc-store-incr@: (v-(-1))} ++@r{ a b@: s : @: @: 2 @:assign@:(a,b) a @tfn{:=} b} ++@r{ a@: s = @: @: 1 @:evalto@:(a,b) a @tfn{=>}} ++ ++@c ++@r{ @: t [ @: @: 4 @:calc-trail-first@:} ++@r{ @: t ] @: @: 4 @:calc-trail-last@:} ++@r{ @: t < @: @: 4 @:calc-trail-scroll-left@:} ++@r{ @: t > @: @: 4 @:calc-trail-scroll-right@:} ++@r{ @: t . @: @: 12 @:calc-full-trail-vectors@:} ++ ++@c ++@r{ @: t b @: @: 4 @:calc-trail-backward@:} ++@r{ @: t d @: @: 12,50 @:calc-trail-display@:} ++@r{ @: t f @: @: 4 @:calc-trail-forward@:} ++@r{ @: t h @: @: @:calc-trail-here@:} ++@r{ @: t i @: @: @:calc-trail-in@:} ++@r{ @: t k @: @: 4 @:calc-trail-kill@:} ++@r{ @: t m @:string @: @:calc-trail-marker@:} ++@r{ @: t n @: @: 4 @:calc-trail-next@:} ++@r{ @: t o @: @: @:calc-trail-out@:} ++@r{ @: t p @: @: 4 @:calc-trail-previous@:} ++@r{ @: t r @:string @: @:calc-trail-isearch-backward@:} ++@r{ @: t s @:string @: @:calc-trail-isearch-forward@:} ++@r{ @: t y @: @: 4 @:calc-trail-yank@:} ++ ++@c ++@r{ d@: t C @:oz, nz @: @:tzconv@:(d,oz,nz)} ++@r{d oz nz@: t C @:$ @: @:tzconv@:(d,oz,nz)} ++@r{ d@: t D @: @: 15 @:date@:(d)} ++@r{ d@: t I @: @: 4 @:incmonth@:(d,n)} ++@r{ d@: t J @: @: 16 @:julian@:(d,z)} ++@r{ d@: t M @: @: 17 @:newmonth@:(d,n)} ++@r{ @: t N @: @: 16 @:now@:(z)} ++@r{ d@: t P @:1 @: 31 @:year@:(d)} ++@r{ d@: t P @:2 @: 31 @:month@:(d)} ++@r{ d@: t P @:3 @: 31 @:day@:(d)} ++@r{ d@: t P @:4 @: 31 @:hour@:(d)} ++@r{ d@: t P @:5 @: 31 @:minute@:(d)} ++@r{ d@: t P @:6 @: 31 @:second@:(d)} ++@r{ d@: t P @:7 @: 31 @:weekday@:(d)} ++@r{ d@: t P @:8 @: 31 @:yearday@:(d)} ++@r{ d@: t P @:9 @: 31 @:time@:(d)} ++@r{ d@: t U @: @: 16 @:unixtime@:(d,z)} ++@r{ d@: t W @: @: 17 @:newweek@:(d,w)} ++@r{ d@: t Y @: @: 17 @:newyear@:(d,n)} ++ ++@c ++@r{ a b@: t + @: @: 2 @:badd@:(a,b)} ++@r{ a b@: t - @: @: 2 @:bsub@:(a,b)} ++ ++@c ++@r{ @: u a @: @: 12 @:calc-autorange-units@:} ++@r{ a@: u b @: @: @:calc-base-units@:} ++@r{ a@: u c @:units @: 18 @:calc-convert-units@:} ++@r{ defn@: u d @:unit, descr @: @:calc-define-unit@:} ++@r{ @: u e @: @: @:calc-explain-units@:} ++@r{ @: u g @:unit @: @:calc-get-unit-definition@:} ++@r{ @: u p @: @: @:calc-permanent-units@:} ++@r{ a@: u r @: @: @:calc-remove-units@:} ++@r{ a@: u s @: @: @:usimplify@:(a)} ++@r{ a@: u t @:units @: 18 @:calc-convert-temperature@:} ++@r{ @: u u @:unit @: @:calc-undefine-unit@:} ++@r{ @: u v @: @: @:calc-enter-units-table@:} ++@r{ a@: u x @: @: @:calc-extract-units@:} ++@r{ a@: u 0-9 @: @: @:calc-quick-units@:} ++ ++@c ++@r{ v1 v2@: u C @: @: 20 @:vcov@:(v1,v2)} ++@r{ v1 v2@: I u C @: @: 20 @:vpcov@:(v1,v2)} ++@r{ v1 v2@: H u C @: @: 20 @:vcorr@:(v1,v2)} ++@r{ v@: u G @: @: 19 @:vgmean@:(v)} ++@r{ a b@: H u G @: @: 2 @:agmean@:(a,b)} ++@r{ v@: u M @: @: 19 @:vmean@:(v)} ++@r{ v@: I u M @: @: 19 @:vmeane@:(v)} ++@r{ v@: H u M @: @: 19 @:vmedian@:(v)} ++@r{ v@: I H u M @: @: 19 @:vhmean@:(v)} ++@r{ v@: u N @: @: 19 @:vmin@:(v)} ++@r{ v@: u S @: @: 19 @:vsdev@:(v)} ++@r{ v@: I u S @: @: 19 @:vpsdev@:(v)} ++@r{ v@: H u S @: @: 19 @:vvar@:(v)} ++@r{ v@: I H u S @: @: 19 @:vpvar@:(v)} ++@r{ @: u V @: @: @:calc-view-units-table@:} ++@r{ v@: u X @: @: 19 @:vmax@:(v)} ++ ++@c ++@r{ v@: u + @: @: 19 @:vsum@:(v)} ++@r{ v@: u * @: @: 19 @:vprod@:(v)} ++@r{ v@: u # @: @: 19 @:vcount@:(v)} ++ ++@c ++@r{ @: V ( @: @: 50 @:calc-vector-parens@:} ++@r{ @: V @{ @: @: 50 @:calc-vector-braces@:} ++@r{ @: V [ @: @: 50 @:calc-vector-brackets@:} ++@r{ @: V ] @:ROCP @: 50 @:calc-matrix-brackets@:} ++@r{ @: V , @: @: 50 @:calc-vector-commas@:} ++@r{ @: V < @: @: 50 @:calc-matrix-left-justify@:} ++@r{ @: V = @: @: 50 @:calc-matrix-center-justify@:} ++@r{ @: V > @: @: 50 @:calc-matrix-right-justify@:} ++@r{ @: V / @: @: 12,50 @:calc-break-vectors@:} ++@r{ @: V . @: @: 12,50 @:calc-full-vectors@:} ++ ++@c ++@r{ s t@: V ^ @: @: 2 @:vint@:(s,t)} ++@r{ s t@: V - @: @: 2 @:vdiff@:(s,t)} ++@r{ s@: V ~ @: @: 1 @:vcompl@:(s)} ++@r{ s@: V # @: @: 1 @:vcard@:(s)} ++@r{ s@: V : @: @: 1 @:vspan@:(s)} ++@r{ s@: V + @: @: 1 @:rdup@:(s)} ++ ++@c ++@r{ m@: V & @: @: 1 @:inv@:(m) 1/m} ++ ++@c ++@r{ v@: v a @:n @: @:arrange@:(v,n)} ++@r{ a@: v b @:n @: @:cvec@:(a,n)} ++@r{ v@: v c @:n >0 @: 21,31 @:mcol@:(v,n)} ++@r{ v@: v c @:n <0 @: 31 @:mrcol@:(v,-n)} ++@r{ m@: v c @:0 @: 31 @:getdiag@:(m)} ++@r{ v@: v d @: @: 25 @:diag@:(v,n)} ++@r{ v m@: v e @: @: 2 @:vexp@:(v,m)} ++@r{ v m f@: H v e @: @: 2 @:vexp@:(v,m,f)} ++@r{ v a@: v f @: @: 26 @:find@:(v,a,n)} ++@r{ v@: v h @: @: 1 @:head@:(v)} ++@r{ v@: I v h @: @: 1 @:tail@:(v)} ++@r{ v@: H v h @: @: 1 @:rhead@:(v)} ++@r{ v@: I H v h @: @: 1 @:rtail@:(v)} ++@r{ @: v i @:n @: 31 @:idn@:(1,n)} ++@r{ @: v i @:0 @: 31 @:idn@:(1)} ++@r{ h t@: v k @: @: 2 @:cons@:(h,t)} ++@r{ h t@: H v k @: @: 2 @:rcons@:(h,t)} ++@r{ v@: v l @: @: 1 @:vlen@:(v)} ++@r{ v@: H v l @: @: 1 @:mdims@:(v)} ++@r{ v m@: v m @: @: 2 @:vmask@:(v,m)} ++@r{ v@: v n @: @: 1 @:rnorm@:(v)} ++@r{ a b c@: v p @: @: 24 @:calc-pack@:} ++@r{ v@: v r @:n >0 @: 21,31 @:mrow@:(v,n)} ++@r{ v@: v r @:n <0 @: 31 @:mrrow@:(v,-n)} ++@r{ m@: v r @:0 @: 31 @:getdiag@:(m)} ++@r{ v i j@: v s @: @: @:subvec@:(v,i,j)} ++@r{ v i j@: I v s @: @: @:rsubvec@:(v,i,j)} ++@r{ m@: v t @: @: 1 @:trn@:(m)} ++@r{ v@: v u @: @: 24 @:calc-unpack@:} ++@r{ v@: v v @: @: 1 @:rev@:(v)} ++@r{ @: v x @:n @: 31 @:index@:(n)} ++@r{ n s i@: C-u v x @: @: @:index@:(n,s,i)} ++ ++@c ++@r{ v@: V A @:op @: 22 @:apply@:(op,v)} ++@r{ v1 v2@: V C @: @: 2 @:cross@:(v1,v2)} ++@r{ m@: V D @: @: 1 @:det@:(m)} ++@r{ s@: V E @: @: 1 @:venum@:(s)} ++@r{ s@: V F @: @: 1 @:vfloor@:(s)} ++@r{ v@: V G @: @: @:grade@:(v)} ++@r{ v@: I V G @: @: @:rgrade@:(v)} ++@r{ v@: V H @:n @: 31 @:histogram@:(v,n)} ++@r{ v w@: H V H @:n @: 31 @:histogram@:(v,w,n)} ++@r{ v1 v2@: V I @:mop aop @: 22 @:inner@:(mop,aop,v1,v2)} ++@r{ m@: V J @: @: 1 @:ctrn@:(m)} ++@r{ m1 m2@: V K @: @: @:kron@:(m1,m2)} ++@r{ m@: V L @: @: 1 @:lud@:(m)} ++@r{ v@: V M @:op @: 22,23 @:map@:(op,v)} ++@r{ v@: V N @: @: 1 @:cnorm@:(v)} ++@r{ v1 v2@: V O @:op @: 22 @:outer@:(op,v1,v2)} ++@r{ v@: V R @:op @: 22,23 @:reduce@:(op,v)} ++@r{ v@: I V R @:op @: 22,23 @:rreduce@:(op,v)} ++@r{ a n@: H V R @:op @: 22 @:nest@:(op,a,n)} ++@r{ a@: I H V R @:op @: 22 @:fixp@:(op,a)} ++@r{ v@: V S @: @: @:sort@:(v)} ++@r{ v@: I V S @: @: @:rsort@:(v)} ++@r{ m@: V T @: @: 1 @:tr@:(m)} ++@r{ v@: V U @:op @: 22 @:accum@:(op,v)} ++@r{ v@: I V U @:op @: 22 @:raccum@:(op,v)} ++@r{ a n@: H V U @:op @: 22 @:anest@:(op,a,n)} ++@r{ a@: I H V U @:op @: 22 @:afixp@:(op,a)} ++@r{ s t@: V V @: @: 2 @:vunion@:(s,t)} ++@r{ s t@: V X @: @: 2 @:vxor@:(s,t)} ++ ++@c ++@r{ @: Y @: @: @:@:user commands} ++ ++@c ++@r{ @: z @: @: @:@:user commands} ++ ++@c ++@r{ c@: Z [ @: @: 45 @:calc-kbd-if@:} ++@r{ c@: Z | @: @: 45 @:calc-kbd-else-if@:} ++@r{ @: Z : @: @: @:calc-kbd-else@:} ++@r{ @: Z ] @: @: @:calc-kbd-end-if@:} ++ ++@c ++@r{ @: Z @{ @: @: 4 @:calc-kbd-loop@:} ++@r{ c@: Z / @: @: 45 @:calc-kbd-break@:} ++@r{ @: Z @} @: @: @:calc-kbd-end-loop@:} ++@r{ n@: Z < @: @: @:calc-kbd-repeat@:} ++@r{ @: Z > @: @: @:calc-kbd-end-repeat@:} ++@r{ n m@: Z ( @: @: @:calc-kbd-for@:} ++@r{ s@: Z ) @: @: @:calc-kbd-end-for@:} ++ ++@c ++@r{ @: Z C-g @: @: @:@:cancel if/loop command} ++ ++@c ++@r{ @: Z ` @: @: @:calc-kbd-push@:} ++@r{ @: Z ' @: @: @:calc-kbd-pop@:} ++@r{ @: Z # @: @: @:calc-kbd-query@:} ++ ++@c ++@r{ comp@: Z C @:func, args @: 50 @:calc-user-define-composition@:} ++@r{ @: Z D @:key, command @: @:calc-user-define@:} ++@r{ @: Z E @:key, editing @: 30 @:calc-user-define-edit@:} ++@r{ defn@: Z F @:k, c, f, a, n@: 28 @:calc-user-define-formula@:} ++@r{ @: Z G @:key @: @:calc-get-user-defn@:} ++@r{ @: Z I @: @: @:calc-user-define-invocation@:} ++@r{ @: Z K @:key, command @: @:calc-user-define-kbd-macro@:} ++@r{ @: Z P @:key @: @:calc-user-define-permanent@:} ++@r{ @: Z S @: @: 30 @:calc-edit-user-syntax@:} ++@r{ @: Z T @: @: 12 @:calc-timing@:} ++@r{ @: Z U @:key @: @:calc-user-undefine@:} ++ ++@end format ++ ++@noindent ++NOTES ++ ++@enumerate ++@c 1 ++@item ++Positive prefix arguments apply to @expr{n} stack entries. ++Negative prefix arguments apply to the @expr{-n}th stack entry. ++A prefix of zero applies to the entire stack. (For @key{LFD} and ++@kbd{M-@key{DEL}}, the meaning of the sign is reversed.) ++ ++@c 2 ++@item ++Positive prefix arguments apply to @expr{n} stack entries. ++Negative prefix arguments apply to the top stack entry ++and the next @expr{-n} stack entries. ++ ++@c 3 ++@item ++Positive prefix arguments rotate top @expr{n} stack entries by one. ++Negative prefix arguments rotate the entire stack by @expr{-n}. ++A prefix of zero reverses the entire stack. ++ ++@c 4 ++@item ++Prefix argument specifies a repeat count or distance. ++ ++@c 5 ++@item ++Positive prefix arguments specify a precision @expr{p}. ++Negative prefix arguments reduce the current precision by @expr{-p}. ++ ++@c 6 ++@item ++A prefix argument is interpreted as an additional step-size parameter. ++A plain @kbd{C-u} prefix means to prompt for the step size. ++ ++@c 7 ++@item ++A prefix argument specifies simplification level and depth. ++1=Default, 2=like @kbd{a s}, 3=like @kbd{a e}. ++ ++@c 8 ++@item ++A negative prefix operates only on the top level of the input formula. ++ ++@c 9 ++@item ++Positive prefix arguments specify a word size of @expr{w} bits, unsigned. ++Negative prefix arguments specify a word size of @expr{w} bits, signed. ++ ++@c 10 ++@item ++Prefix arguments specify the shift amount @expr{n}. The @expr{w} argument ++cannot be specified in the keyboard version of this command. ++ ++@c 11 ++@item ++From the keyboard, @expr{d} is omitted and defaults to zero. ++ ++@c 12 ++@item ++Mode is toggled; a positive prefix always sets the mode, and a negative ++prefix always clears the mode. ++ ++@c 13 ++@item ++Some prefix argument values provide special variations of the mode. ++ ++@c 14 ++@item ++A prefix argument, if any, is used for @expr{m} instead of taking ++@expr{m} from the stack. @expr{M} may take any of these values: ++@iftex ++{@advance@tableindent10pt ++@end iftex ++@table @asis ++@item Integer ++Random integer in the interval @expr{[0 .. m)}. ++@item Float ++Random floating-point number in the interval @expr{[0 .. m)}. ++@item 0.0 ++Gaussian with mean 1 and standard deviation 0. ++@item Error form ++Gaussian with specified mean and standard deviation. ++@item Interval ++Random integer or floating-point number in that interval. ++@item Vector ++Random element from the vector. ++@end table ++@iftex ++} ++@end iftex ++ ++@c 15 ++@item ++A prefix argument from 1 to 6 specifies number of date components ++to remove from the stack. @xref{Date Conversions}. ++ ++@c 16 ++@item ++A prefix argument specifies a time zone; @kbd{C-u} says to take the ++time zone number or name from the top of the stack. @xref{Time Zones}. ++ ++@c 17 ++@item ++A prefix argument specifies a day number (0-6, 0-31, or 0-366). ++ ++@c 18 ++@item ++If the input has no units, you will be prompted for both the old and ++the new units. ++ ++@c 19 ++@item ++With a prefix argument, collect that many stack entries to form the ++input data set. Each entry may be a single value or a vector of values. ++ ++@c 20 ++@item ++With a prefix argument of 1, take a single ++@texline @var{n}@math{\times2} ++@infoline @mathit{@var{N}x2} ++matrix from the stack instead of two separate data vectors. ++ ++@c 21 ++@item ++The row or column number @expr{n} may be given as a numeric prefix ++argument instead. A plain @kbd{C-u} prefix says to take @expr{n} ++from the top of the stack. If @expr{n} is a vector or interval, ++a subvector/submatrix of the input is created. ++ ++@c 22 ++@item ++The @expr{op} prompt can be answered with the key sequence for the ++desired function, or with @kbd{x} or @kbd{z} followed by a function name, ++or with @kbd{$} to take a formula from the top of the stack, or with ++@kbd{'} and a typed formula. In the last two cases, the formula may ++be a nameless function like @samp{<#1+#2>} or @samp{}, or it ++may include @kbd{$}, @kbd{$$}, etc. (where @kbd{$} will correspond to the ++last argument of the created function), or otherwise you will be ++prompted for an argument list. The number of vectors popped from the ++stack by @kbd{V M} depends on the number of arguments of the function. ++ ++@c 23 ++@item ++One of the mapping direction keys @kbd{_} (horizontal, i.e., map ++by rows or reduce across), @kbd{:} (vertical, i.e., map by columns or ++reduce down), or @kbd{=} (map or reduce by rows) may be used before ++entering @expr{op}; these modify the function name by adding the letter ++@code{r} for ``rows,'' @code{c} for ``columns,'' @code{a} for ``across,'' ++or @code{d} for ``down.'' ++ ++@c 24 ++@item ++The prefix argument specifies a packing mode. A nonnegative mode ++is the number of items (for @kbd{v p}) or the number of levels ++(for @kbd{v u}). A negative mode is as described below. With no ++prefix argument, the mode is taken from the top of the stack and ++may be an integer or a vector of integers. ++@iftex ++{@advance@tableindent-20pt ++@end iftex ++@table @cite ++@item -1 ++(@var{2}) Rectangular complex number. ++@item -2 ++(@var{2}) Polar complex number. ++@item -3 ++(@var{3}) HMS form. ++@item -4 ++(@var{2}) Error form. ++@item -5 ++(@var{2}) Modulo form. ++@item -6 ++(@var{2}) Closed interval. ++@item -7 ++(@var{2}) Closed .. open interval. ++@item -8 ++(@var{2}) Open .. closed interval. ++@item -9 ++(@var{2}) Open interval. ++@item -10 ++(@var{2}) Fraction. ++@item -11 ++(@var{2}) Float with integer mantissa. ++@item -12 ++(@var{2}) Float with mantissa in @expr{[1 .. 10)}. ++@item -13 ++(@var{1}) Date form (using date numbers). ++@item -14 ++(@var{3}) Date form (using year, month, day). ++@item -15 ++(@var{6}) Date form (using year, month, day, hour, minute, second). ++@end table ++@iftex ++} ++@end iftex ++ ++@c 25 ++@item ++A prefix argument specifies the size @expr{n} of the matrix. With no ++prefix argument, @expr{n} is omitted and the size is inferred from ++the input vector. ++ ++@c 26 ++@item ++The prefix argument specifies the starting position @expr{n} (default 1). ++ ++@c 27 ++@item ++Cursor position within stack buffer affects this command. ++ ++@c 28 ++@item ++Arguments are not actually removed from the stack by this command. ++ ++@c 29 ++@item ++Variable name may be a single digit or a full name. ++ ++@c 30 ++@item ++Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or ++@key{LFD}, or in some cases @key{RET}) to finish the edit, or kill the ++buffer with @kbd{C-x k} to cancel the edit. The @key{LFD} key prevents evaluation ++of the result of the edit. ++ ++@c 31 ++@item ++The number prompted for can also be provided as a prefix argument. ++ ++@c 32 ++@item ++Press this key a second time to cancel the prefix. ++ ++@c 33 ++@item ++With a negative prefix, deactivate all formulas. With a positive ++prefix, deactivate and then reactivate from scratch. ++ ++@c 34 ++@item ++Default is to scan for nearest formula delimiter symbols. With a ++prefix of zero, formula is delimited by mark and point. With a ++non-zero prefix, formula is delimited by scanning forward or ++backward by that many lines. ++ ++@c 35 ++@item ++Parse the region between point and mark as a vector. A nonzero prefix ++parses @var{n} lines before or after point as a vector. A zero prefix ++parses the current line as a vector. A @kbd{C-u} prefix parses the ++region between point and mark as a single formula. ++ ++@c 36 ++@item ++Parse the rectangle defined by point and mark as a matrix. A positive ++prefix @var{n} divides the rectangle into columns of width @var{n}. ++A zero or @kbd{C-u} prefix parses each line as one formula. A negative ++prefix suppresses special treatment of bracketed portions of a line. ++ ++@c 37 ++@item ++A numeric prefix causes the current language mode to be ignored. ++ ++@c 38 ++@item ++Responding to a prompt with a blank line answers that and all ++later prompts by popping additional stack entries. ++ ++@c 39 ++@item ++Answer for @expr{v} may also be of the form @expr{v = v_0} or ++@expr{v - v_0}. ++ ++@c 40 ++@item ++With a positive prefix argument, stack contains many @expr{y}'s and one ++common @expr{x}. With a zero prefix, stack contains a vector of ++@expr{y}s and a common @expr{x}. With a negative prefix, stack ++contains many @expr{[x,y]} vectors. (For 3D plots, substitute ++@expr{z} for @expr{y} and @expr{x,y} for @expr{x}.) ++ ++@c 41 ++@item ++With any prefix argument, all curves in the graph are deleted. ++ ++@c 42 ++@item ++With a positive prefix, refines an existing plot with more data points. ++With a negative prefix, forces recomputation of the plot data. ++ ++@c 43 ++@item ++With any prefix argument, set the default value instead of the ++value for this graph. ++ ++@c 44 ++@item ++With a negative prefix argument, set the value for the printer. ++ ++@c 45 ++@item ++Condition is considered ``true'' if it is a nonzero real or complex ++number, or a formula whose value is known to be nonzero; it is ``false'' ++otherwise. ++ ++@c 46 ++@item ++Several formulas separated by commas are pushed as multiple stack ++entries. Trailing @kbd{)}, @kbd{]}, @kbd{@}}, @kbd{>}, and @kbd{"} ++delimiters may be omitted. The notation @kbd{$$$} refers to the value ++in stack level three, and causes the formula to replace the top three ++stack levels. The notation @kbd{$3} refers to stack level three without ++causing that value to be removed from the stack. Use @key{LFD} in place ++of @key{RET} to prevent evaluation; use @kbd{M-=} in place of @key{RET} ++to evaluate variables. ++ ++@c 47 ++@item ++The variable is replaced by the formula shown on the right. The ++Inverse flag reverses the order of the operands, e.g., @kbd{I s - x} ++assigns ++@texline @math{x \coloneq a-x}. ++@infoline @expr{x := a-x}. ++ ++@c 48 ++@item ++Press @kbd{?} repeatedly to see how to choose a model. Answer the ++variables prompt with @expr{iv} or @expr{iv;pv} to specify ++independent and parameter variables. A positive prefix argument ++takes @mathit{@var{n}+1} vectors from the stack; a zero prefix takes a matrix ++and a vector from the stack. ++ ++@c 49 ++@item ++With a plain @kbd{C-u} prefix, replace the current region of the ++destination buffer with the yanked text instead of inserting. ++ ++@c 50 ++@item ++All stack entries are reformatted; the @kbd{H} prefix inhibits this. ++The @kbd{I} prefix sets the mode temporarily, redraws the top stack ++entry, then restores the original setting of the mode. ++ ++@c 51 ++@item ++A negative prefix sets the default 3D resolution instead of the ++default 2D resolution. ++ ++@c 52 ++@item ++This grabs a vector of the form [@var{prec}, @var{wsize}, @var{ssize}, ++@var{radix}, @var{flfmt}, @var{ang}, @var{frac}, @var{symb}, @var{polar}, ++@var{matrix}, @var{simp}, @var{inf}]. A prefix argument from 1 to 12 ++grabs the @var{n}th mode value only. ++@end enumerate ++ ++@iftex ++(Space is provided below for you to keep your own written notes.) ++@page ++@endgroup ++@end iftex ++ ++ ++@c [end-summary] ++ ++@node Key Index, Command Index, Summary, Top ++@unnumbered Index of Key Sequences ++ ++@printindex ky ++ ++@node Command Index, Function Index, Key Index, Top ++@unnumbered Index of Calculator Commands ++ ++Since all Calculator commands begin with the prefix @samp{calc-}, the ++@kbd{x} key has been provided as a variant of @kbd{M-x} which automatically ++types @samp{calc-} for you. Thus, @kbd{x last-args} is short for ++@kbd{M-x calc-last-args}. ++ ++@printindex pg ++ ++@node Function Index, Concept Index, Command Index, Top ++@unnumbered Index of Algebraic Functions ++ ++This is a list of built-in functions and operators usable in algebraic ++expressions. Their full Lisp names are derived by adding the prefix ++@samp{calcFunc-}, as in @code{calcFunc-sqrt}. ++@iftex ++All functions except those noted with ``*'' have corresponding ++Calc keystrokes and can also be found in the Calc Summary. ++@end iftex ++ ++@printindex tp ++ ++@node Concept Index, Variable Index, Function Index, Top ++@unnumbered Concept Index ++ ++@printindex cp ++ ++@node Variable Index, Lisp Function Index, Concept Index, Top ++@unnumbered Index of Variables ++ ++The variables in this list that do not contain dashes are accessible ++as Calc variables. Add a @samp{var-} prefix to get the name of the ++corresponding Lisp variable. ++ ++The remaining variables are Lisp variables suitable for @code{setq}ing ++in your Calc init file or @file{.emacs} file. ++ ++@printindex vr ++ ++@node Lisp Function Index, , Variable Index, Top ++@unnumbered Index of Lisp Math Functions ++ ++The following functions are meant to be used with @code{defmath}, not ++@code{defun} definitions. For names that do not start with @samp{calc-}, ++the corresponding full Lisp name is derived by adding a prefix of ++@samp{math-}. ++ ++@printindex fn ++ ++@bye ++ ++ ++@ignore ++ arch-tag: 77a71809-fa4d-40be-b2cc-da3e8fb137c0 ++@end ignore +diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi +new file mode 100644 +index 0000000..0d8385e +--- /dev/null ++++ b/doc/misc/cc-mode.texi +@@ -0,0 +1,6998 @@ ++\input texinfo ++@c Notes to self regarding line handling: ++@c ++@c Empty lines are often significant before @end directives; avoid them. ++@c ++@c Empty lines before and after @example directives are significant in ++@c info output but not in TeX. Empty lines inside @example directives ++@c are significant. ++ ++@c Conventions for formatting examples: ++@c o If the example contains empty lines then put the surrounding empty ++@c lines inside the @example directives. Put them outside otherwise. ++@c o Use @group inside the example only if it shows indentation where ++@c the relation between lines inside is relevant. ++@c o Format line number columns like this: ++@c 1: foo ++@c 2: bar ++@c ^ one space ++@c ^^ two columns, right alignment ++@c o Check line lengths in TeX output; they can typically be no longer ++@c than 70 chars, 60 if the paragraph is indented. ++ ++@comment TBD: Document the finer details of statement anchoring? ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@comment %**start of header (This is for running Texinfo on a region) ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@comment How to make the various output formats: ++@comment (Thanks to Robert Chassell for supplying this information.) ++@comment Note that Texinfo 4.7 (or later) is needed. ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@ignore ++In each of the following pairs of commands, the first generates a ++version with cross references pointing to the GNU Emacs manuals, ++the second with them pointing to the XEmacs manuals. ++ ## Info output ++ makeinfo cc-mode.texi ++ makeinfo -DXEMACS cc-mode.texi ++ ++ ## DVI output ++ ## You may need to set up the environment variable TEXINPUTS so ++ ## that tex can find the file texinfo.tex - See the tex ++ ## manpage. ++ texi2dvi cc-mode.texi ++ texi2dvi -t "@set XEMACS " cc-mode.texi ++ ++ ## HTML output. (The --no-split parameter is optional) ++ makeinfo --html --no-split cc-mode.texi ++ makeinfo --html --no-split -DXEMACS cc-mode.texi ++ ++ ## Plain text output ++ makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ ++ --no-headers --output=cc-mode.txt cc-mode.texi ++ makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ ++ --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi ++ ++ ## DocBook output ++ makeinfo --docbook --no-split --paragraph-indent=0 \ ++ cc-mode.texi ++ makeinfo --docbook --no-split --paragraph-indent=0 \ ++ -DXEMACS cc-mode.texi ++ ++ ## XML output ++ makeinfo --xml --no-split --paragraph-indent=0 \ ++ cc-mode.texi ++ makeinfo --xml --no-split --paragraph-indent=0 \ ++ -DXEMACS cc-mode.texi ++ ++ #### (You must be in the same directory as the viewed file.) ++ ++ ## View DVI output ++ xdvi cc-mode.dvi & ++ ++ ## View HTML output ++ mozilla cc-mode.html ++@end ignore ++ ++@comment No overfull hbox marks in the dvi file. ++@finalout ++ ++@setfilename ../../info/ccmode ++@settitle CC Mode Manual ++@footnotestyle end ++ ++@c The following four macros generate the filenames and titles of the ++@c main (X)Emacs manual and the Elisp/Lispref manual. Leave the ++@c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it ++@c to generate an XEmacs version, e.g. with ++@c "makeinfo -DXEMACS cc-mode.texi". ++@ifset XEMACS ++@macro emacsman ++xemacs ++@end macro ++@macro emacsmantitle ++XEmacs User's Manual ++@end macro ++@macro lispref ++lispref ++@end macro ++@macro lispreftitle ++XEmacs Lisp Reference Manual ++@end macro ++@end ifset ++ ++@ifclear XEMACS ++@macro emacsman ++emacs ++@end macro ++@macro emacsmantitle ++GNU Emacs Manual ++@end macro ++@macro lispref ++elisp ++@end macro ++@macro lispreftitle ++GNU Emacs Lisp Reference Manual ++@end macro ++@end ifclear ++ ++ ++@macro ccmode ++CC Mode ++@end macro ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@comment @setchapternewpage odd !! we don't want blank pages !! ++@comment %**end of header (This is for running Texinfo on a region) ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@comment ++@comment Texinfo manual for CC Mode ++@comment Generated from the original README file by Krishna Padmasola ++@comment ++@comment ++@comment Authors: ++@comment Barry A. Warsaw ++@comment Martin Stjernholm ++@comment Alan Mackenzie ++@comment ++@comment Maintained by Martin Stjernholm and Alan Mackenzie ++@comment ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@comment Define an index for syntactic symbols. ++@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss ++ @c For Info, unlike tex, @syncodeindex needs a matching @defindex. ++@defindex ss ++@end ifnottex ++ ++@comment Combine key, syntactic symbol and concept indices into one. ++@syncodeindex ss cp ++@syncodeindex ky cp ++ ++@copying ++This manual is for CC Mode in Emacs. ++ ++Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, ++2003, 2004, 2005, 2006, 2007, 2008, 2009 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 ++ ++@comment Info directory entry for use by install-info. The indentation ++@comment here is by request from the FSF folks. ++@dircategory Emacs ++@direntry ++* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, ++ Java, Pike, AWK, and CORBA IDL code. ++@end direntry ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@comment TeX title page ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@titlepage ++@sp 10 ++ ++@center @titlefont{CC Mode 5.31} ++@sp 2 ++@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} ++@sp 2 ++@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie ++ ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++ ++This manual was generated from cc-mode.texi, which can be downloaded ++from ++@url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/doc/misc/cc-mode.texi}. ++@end titlepage ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@comment The Top node contains the master menu for the Info file. ++@comment This appears only in the Info file, not the printed manual. ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@summarycontents ++@contents ++ ++@node Top, Introduction, (dir), (dir) ++@comment node-name, next, previous, up ++ ++@ifnottex ++@top @ccmode{} ++ ++@ccmode{} is a GNU Emacs mode for editing files containing C, C++, ++Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike ++and AWK code. It provides syntax-based indentation, font locking, and ++has several handy commands and some minor modes to make the editing ++easier. It does not provide tools to look up and navigate between ++functions, classes etc - there are other packages for that. ++ ++@insertcopying ++@end ifnottex ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@menu ++* Introduction:: ++* Overview:: ++* Getting Started:: ++* Commands:: ++* Font Locking:: ++* Config Basics:: ++* Custom Filling and Breaking:: ++* Custom Auto-newlines:: ++* Clean-ups:: ++* Indentation Engine Basics:: ++* Customizing Indentation:: ++* Custom Macros:: ++* Odds and Ends:: ++* Sample .emacs File:: ++* Performance Issues:: ++* Limitations and Known Bugs:: ++* FAQ:: ++* Updating CC Mode:: ++* Mailing Lists and Bug Reports:: ++* GNU Free Documentation License:: ++* Command and Function Index:: ++* Variable Index:: ++* Concept and Key Index:: ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ ++Commands ++ ++* Indentation Commands:: ++* Comment Commands:: ++* Movement Commands:: ++* Filling and Breaking:: ++* Minor Modes:: ++* Electric Keys:: ++* Auto-newlines:: ++* Hungry WS Deletion:: ++* Subword Movement:: ++* Other Commands:: ++ ++Font Locking ++ ++* Font Locking Preliminaries:: ++* Faces:: ++* Doc Comments:: ++* AWK Mode Font Locking:: ++ ++Configuration Basics ++ ++* CC Hooks:: ++* Style Variables:: ++* Styles:: ++ ++Styles ++ ++* Built-in Styles:: ++* Choosing a Style:: ++* Adding Styles:: ++* File Styles:: ++ ++Customizing Auto-newlines ++ ++* Hanging Braces:: ++* Hanging Colons:: ++* Hanging Semicolons and Commas:: ++ ++Hanging Braces ++ ++* Custom Braces:: ++ ++Indentation Engine Basics ++ ++* Syntactic Analysis:: ++* Syntactic Symbols:: ++* Indentation Calculation:: ++ ++Syntactic Symbols ++ ++* Function Symbols:: ++* Class Symbols:: ++* Conditional Construct Symbols:: ++* Switch Statement Symbols:: ++* Brace List Symbols:: ++* External Scope Symbols:: ++* Paren List Symbols:: ++* Literal Symbols:: ++* Multiline Macro Symbols:: ++* Objective-C Method Symbols:: ++* Anonymous Class Symbol:: ++* Statement Block Symbols:: ++* K&R Symbols:: ++ ++Customizing Indentation ++ ++* c-offsets-alist:: ++* Interactive Customization:: ++* Line-Up Functions:: ++* Custom Line-Up:: ++* Other Indentation:: ++ ++Line-Up Functions ++ ++* Brace/Paren Line-Up:: ++* List Line-Up:: ++* Operator Line-Up:: ++* Comment Line-Up:: ++* Misc Line-Up:: ++ ++@end detailmenu ++@end menu ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Introduction, Overview, Top, Top ++@comment node-name, next, previous, up ++@chapter Introduction ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex BOCM ++@cindex history ++@cindex awk-mode.el ++@cindex c-mode.el ++@cindex c++-mode.el ++ ++Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C, ++C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and ++CIDL), Pike and AWK code. This incarnation of the mode is descended ++from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM ++@t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been ++maintaining since 1992, and @file{awk-mode.el}, a long neglected mode ++in the (X)Emacs base. ++ ++Late in 1997, Martin Stjernholm joined Barry on the @ccmode{} ++Maintainers Team, and implemented the Pike support. In 2000 Martin ++took over as the sole maintainer. In 2001 Alan Mackenzie joined the ++team, implementing AWK support in version 5.30. @ccmode{} did not ++originally contain the font lock support for its languages --- that ++was added in version 5.30. ++ ++This manual describes @ccmode{} ++@comment The following line must appear on its own, so that the ++version 5.31. ++@comment Release.py script can update the version number automatically ++ ++@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, ++Java, CORBA's Interface Definition Language, Pike@footnote{A C-like ++scripting language with its roots in the LPC language used in some MUD ++engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this ++way, you can easily set up consistent font locking and coding styles for ++use in editing all of these languages, although AWK is not yet as ++uniformly integrated as the other languages. ++ ++@findex c-mode ++@findex c++-mode ++@findex objc-mode ++@findex java-mode ++@findex idl-mode ++@findex pike-mode ++@findex awk-mode ++Note that the name of this package is ``@ccmode{}'', but there is no top ++level @code{cc-mode} entry point. All of the variables, commands, and ++functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and ++@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, ++@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are ++provided. This package is intended to be a replacement for ++@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}. ++ ++A special word of thanks goes to Krishna Padmasola for his work in ++converting the original @file{README} file to Texinfo format. I'd ++also like to thank all the @ccmode{} victims who help enormously ++during the early beta stages of @ccmode{}'s development. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Overview, Getting Started, Introduction, Top ++@comment node-name, next, previous, up@cindex organization of the manual ++@chapter Overview of the Manual ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@noindent ++The manual starts with several introductory chapters (including this ++one). ++ ++@noindent ++The next chunk of the manual describes the day to day @emph{use} of ++@ccmode{} (as contrasted with how to customize it). ++ ++@itemize @bullet ++@item ++The chapter ``Commands'' describes in detail how to use (nearly) all ++of @ccmode{}'s features. There are extensive cross-references from ++here to the corresponding sections later in the manual which tell you ++how to customize these features. ++ ++@item ++``Font Locking'' describes how ``syntax highlighting'' is applied to ++your buffers. It is mainly background information and can be skipped ++over at a first reading. ++@end itemize ++ ++@noindent ++The next chunk of the manual describes how to @emph{customize} ++@ccmode{}. Typically, an overview of a topic is given at the chapter ++level, then the sections and subsections describe the material in ++increasing detail. ++ ++@itemize @bullet ++@item ++The chapter ``Configuration Basics'' tells you @emph{how} to write ++customizations - whether in hooks, in styles, in both, or in neither, ++depending on your needs. It describes the @ccmode{} style system and ++lists the standard styles that @ccmode{} supplies. ++ ++@item ++The next few chapters describe in detail how to customize the various ++features of @ccmode{}. ++ ++@item ++Finally, there is a sample @file{.emacs} fragment, which might help you ++in creating your own customization. ++@end itemize ++ ++@noindent ++The manual ends with ``this and that'', things that don't fit cleanly ++into any of the previous chunks. ++ ++@itemize @bullet ++@item ++Two chapters discuss the performance of @ccmode{} and known ++bugs/limitations. ++ ++@item ++The FAQ contains a list of common problems and questions. ++ ++@item ++The next two chapters tell you how to get in touch with the @ccmode{} ++project - whether for updating @ccmode{} or submitting bug reports. ++@end itemize ++ ++@noindent ++Finally, there are the customary indices. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Getting Started, Commands, Overview, Top ++@comment node-name, next, previous, up ++@chapter Getting Started ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++If you got this version of @ccmode{} with Emacs or XEmacs, it should ++work just fine right out of the box. Note however that you might not ++have the latest @ccmode{} release and might want to upgrade your copy ++(see below). ++ ++You should probably start by skimming through the entire Commands chapter ++(@pxref{Commands}) to get an overview of @ccmode{}'s capabilities. ++ ++After trying out some commands, you may dislike some aspects of ++@ccmode{}'s default configuration. Here is an outline of how to ++change some of the settings that newcomers to @ccmode{} most often ++want to change: ++ ++@table @asis ++@item c-basic-offset ++This Lisp variable holds an integer, the number of columns @ccmode{} ++indents nested code. To set this value to 6, customize ++@code{c-basic-offset} or put this into your @file{.emacs}: ++ ++@example ++(setq c-basic-offset 6) ++@end example ++ ++@item The (indentation) style ++The basic ``shape'' of indentation created by @ccmode{}---by default, ++this is @code{gnu} style (except for Java and AWK buffers). A list of ++the available styles and their descriptions can be found in ++@ref{Built-in Styles}. A complete specification of the @ccmode{} ++style system, including how to create your own style, can be found in ++the chapter @ref{Styles}. To set your style to @code{linux}, either ++customize @code{c-default-style} or put this into your @file{.emacs}: ++ ++@example ++(setq c-default-style '((java-mode . "java") ++ (awk-mode . "awk") ++ (other . "linux"))) ++@end example ++ ++@item Electric Indentation ++Normally, when you type ``punctuation'' characters such as @samp{;} or ++@samp{@{}, @ccmode{} instantly reindents the current line. This can ++be disconcerting until you get used to it. To disable @dfn{electric ++indentation} in the current buffer, type @kbd{C-c C-l}. Type the same ++thing to enable it again. To have electric indentation disabled by ++default, put the following into your @file{.emacs} file@footnote{There ++is no ``easy customization'' facility for making this change.}: ++ ++@example ++(setq-default c-electric-flag nil) ++@end example ++ ++@noindent ++Details of this and other similar ``Minor Modes'' appear in the ++section @ref{Minor Modes}. ++ ++@item Making the @key{RET} key indent the new line ++The standard Emacs binding for @key{RET} just adds a new line. If you ++want it to reindent the new line as well, rebind the key. Note that ++the action of rebinding would fail if the pertinent keymap didn't yet ++exist---we thus need to delay the action until after @ccmode{} has ++been loaded. Put the following code into your @file{.emacs}: ++ ++@example ++(defun my-make-CR-do-indent () ++ (define-key c-mode-base-map "\C-m" 'c-context-line-break)) ++(add-hook 'c-initialization-hook 'my-make-CR-do-indent) ++@end example ++ ++@noindent ++This example demonstrates the use of a very powerful @ccmode{} (and ++Emacs) facility, the hook. The use of @ccmode{}'s hooks is described ++in @ref{CC Hooks}. ++@end table ++ ++All these settings should occur in your @file{.emacs} @emph{before} ++any @ccmode{} buffers get loaded---in particular, before any call of ++@code{desktop-read}. ++ ++As you get to know the mode better, you may want to make more ++ambitious changes to your configuration. For this, you should start ++reading the chapter @ref{Config Basics}. ++ ++If you are upgrading an existing @ccmode{} installation, please see ++the @file{README} file for installation details. In particular, if ++you are going to be editing AWK files, @file{README} describes how to ++configure your (X)Emacs so that @ccmode{} will supersede the obsolete ++@code{awk-mode.el} which might have been supplied with your (X)Emacs. ++@ccmode{} might not work with older versions of Emacs or XEmacs. See ++the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net} ++for the latest information on Emacs version and package compatibility ++(@pxref{Updating CC Mode}). ++ ++@deffn Command c-version ++@findex version (c-) ++You can find out what version of @ccmode{} you are using by visiting a C ++file and entering @kbd{M-x c-version RET}. You should see this message in ++the echo area: ++ ++@example ++Using CC Mode version 5.XX ++@end example ++ ++@noindent ++where @samp{XX} is the minor release number. ++@end deffn ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Commands, Font Locking, Getting Started, Top ++@comment node-name, next, previous, up ++@chapter Commands ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++This chapter specifies all of CC Mode's commands, and thus contains ++nearly everything you need to know to @emph{use} @ccmode{} (as ++contrasted with configuring it). @dfn{Commands} here means both ++control key sequences and @dfn{electric keys}, these being characters ++such as @samp{;} which, as well as inserting themselves into the ++buffer, also do other things. ++ ++You might well want to review ++@ifset XEMACS ++@ref{Lists,,,@emacsman{}, @emacsmantitle{}}, ++@end ifset ++@ifclear XEMACS ++@ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}}, ++@end ifclear ++which describes commands for moving around brace and parenthesis ++structures. ++ ++ ++@menu ++* Indentation Commands:: ++* Comment Commands:: ++* Movement Commands:: ++* Filling and Breaking:: ++* Minor Modes:: ++* Electric Keys:: ++* Auto-newlines:: ++* Hungry WS Deletion:: ++* Subword Movement:: ++* Other Commands:: ++@end menu ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Indentation Commands, Comment Commands, Commands, Commands ++@comment node-name, next, previous,up ++@section Indentation Commands ++@cindex indentation ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The following commands reindent C constructs. Note that when you ++change your coding style, either interactively or through some other ++means, your file does @emph{not} automatically get reindented. You ++will need to execute one of the following commands to see the effects ++of your changes. ++ ++@cindex GNU indent program ++Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} ++(@pxref{Custom Auto-newlines}) only affect how on-the-fly code is ++formatted. Changing the ``hanginess'' of a brace and then ++reindenting, will not move the brace to a different line. For this, ++you're better off getting an external program like GNU @code{indent}, ++which will rearrange brace location, amongst other things. ++ ++Preprocessor directives are handled as syntactic whitespace from other ++code, i.e. they can be interspersed anywhere without affecting the ++indentation of the surrounding code, just like comments. ++ ++The code inside macro definitions is, by default, still analyzed ++syntactically so that you get relative indentation there just as you'd ++get if the same code was outside a macro. However, since there is no ++hint about the syntactic context, i.e. whether the macro expands to an ++expression, to some statements, or perhaps to whole functions, the ++syntactic recognition can be wrong. @ccmode{} manages to figure it ++out correctly most of the time, though. ++ ++Reindenting large sections of code can take a long time. When ++@ccmode{} reindents a region of code, it is essentially equivalent to ++hitting @key{TAB} on every line of the region. ++ ++These commands indent code: ++ ++@table @asis ++@item @kbd{@key{TAB}} (@code{c-indent-command}) ++@kindex TAB ++@findex c-indent-command ++@findex indent-command (c-) ++This command indents the current line. That is all you need to know ++about it for normal use. ++ ++@code{c-indent-command} does different things, depending on the ++setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine ++Basics}): ++ ++@itemize @bullet ++@item ++When it's non-@code{nil} (which it normally is), the command indents ++the line according to its syntactic context. With a prefix argument ++(@kbd{C-u @key{TAB}}), it will re-indent the entire ++expression@footnote{this is only useful for a line starting with a ++comment opener or an opening brace, parenthesis, or string quote.} ++that begins at the line's left margin. ++ ++@item ++When it's @code{nil}, the command indents the line by an extra ++@code{c-basic-offset} columns. A prefix argument acts as a ++multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1, ++removing @code{c-basic-offset} columns from the indentation. ++@end itemize ++ ++The precise behavior is modified by several variables: With ++@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace ++in some circumstances---@code{c-insert-tab-function} then defines ++precisely what sort of ``whitespace'' this will be. Set the standard ++Emacs variable @code{indent-tabs-mode} to @code{t} if you want real ++@samp{tab} characters to be used in the indentation, to @code{nil} if ++you want only spaces. @xref{Just Spaces,,, @emacsman{}, ++@emacsmantitle{}}. ++ ++@defopt c-tab-always-indent ++@vindex tab-always-indent (c-) ++@cindex literal ++This variable modifies how @key{TAB} operates. ++@itemize @bullet ++@item ++When it is @code{t} (the default), @key{TAB} simply indents the ++current line. ++@item ++When it is @code{nil}, @key{TAB} (re)indents the line only if point is ++to the left of the first non-whitespace character on the line. ++Otherwise it inserts some whitespace (a tab or an equivalent number of ++spaces - see below) at point. ++@item ++With some other value, the line is reindented. Additionally, if point ++is within a string or comment, some whitespace is inserted. ++@end itemize ++@end defopt ++ ++@defopt c-insert-tab-function ++@vindex insert-tab-function (c-) ++@findex tab-to-tab-stop ++When ``some whitespace'' is inserted as described above, what actually ++happens is that the function stored in @code{c-insert-tab-function} is ++called. Normally, this is @code{insert-tab}, which inserts a real tab ++character or the equivalent number of spaces (depending on ++@code{indent-tabs-mode}). Some people, however, set ++@code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get ++hard tab stops when indenting. ++@end defopt ++@end table ++ ++@noindent ++The kind of indentation the next five commands do depends on the ++setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine ++Basics}): ++@itemize @bullet ++@item ++when it is non-@code{nil} (the default), the commands indent lines ++according to their syntactic context; ++@item ++when it is @code{nil}, they just indent each line the same amount as ++the previous non-blank line. The commands that indent a region aren't ++very useful in this case. ++@end itemize ++ ++@table @asis ++@item @kbd{C-j} (@code{newline-and-indent}) ++@kindex C-j ++@findex newline-and-indent ++Inserts a newline and indents the new blank line, ready to start ++typing. This is a standard (X)Emacs command. ++ ++@item @kbd{C-M-q} (@code{c-indent-exp}) ++@kindex C-M-q ++@findex c-indent-exp ++@findex indent-exp (c-) ++Indents an entire balanced brace or parenthesis expression. Note that ++point must be on the opening brace or parenthesis of the expression ++you want to indent. ++ ++@item @kbd{C-c C-q} (@code{c-indent-defun}) ++@kindex C-c C-q ++@findex c-indent-defun ++@findex indent-defun (c-) ++Indents the entire top-level function, class or macro definition ++encompassing point. It leaves point unchanged. This function can't be ++used to reindent a nested brace construct, such as a nested class or ++function, or a Java method. The top-level construct being reindented ++must be complete, i.e. it must have both a beginning brace and an ending ++brace. ++ ++@item @kbd{C-M-\} (@code{indent-region}) ++@kindex C-M-\ ++@findex indent-region ++Indents an arbitrary region of code. This is a standard Emacs command, ++tailored for C code in a @ccmode{} buffer. Note, of course, that point ++and mark must delineate the region you want to indent. ++ ++@item @kbd{C-M-h} (@code{c-mark-function}) ++@kindex C-M-h ++@findex c-mark-function ++@findex mark-function (c-) ++While not strictly an indentation command, this is useful for marking ++the current top-level function or class definition as the current ++region. As with @code{c-indent-defun}, this command operates on ++top-level constructs, and can't be used to mark say, a Java method. ++@end table ++ ++These variables are also useful when indenting code: ++ ++@defopt indent-tabs-mode ++This is a standard Emacs variable that controls how line indentation ++is composed. When it's non-@code{nil}, tabs can be used in a line's ++indentation, otherwise only spaces are used. ++@end defopt ++ ++@defopt c-progress-interval ++@vindex progress-interval (c-) ++When indenting large regions of code, this variable controls how often a ++progress message is displayed. Set this variable to @code{nil} to ++inhibit the progress messages, or set it to an integer which is how ++often (in seconds) progress messages are to be displayed. ++@end defopt ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Comment Commands, Movement Commands, Indentation Commands, Commands ++@comment node-name, next, previous, up ++@section Comment Commands ++@cindex comments (insertion of) ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@table @asis ++@item @kbd{C-c C-c} (@code{comment-region}) ++@kindex C-c C-c ++@findex comment-region ++This command comments out the lines that start in the region. With a ++negative argument, it does the opposite - it deletes the comment ++delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU ++Emacs Manual}, for fuller details. @code{comment-region} isn't ++actually part of @ccmode{} - it is given a @ccmode{} binding for ++convenience. ++ ++@item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.}) ++@kindex M-; ++@findex comment-dwim ++@findex indent-for-comment ++Insert a comment at the end of the current line, if none is there ++already. Then reindent the comment according to @code{comment-column} ++@ifclear XEMACS ++(@pxref{Options for Comments,,, emacs, GNU Emacs Manual}) ++@end ifclear ++@ifset XEMACS ++(@pxref{Comments,,, xemacs, XEmacs User's Manual}) ++@end ifset ++and the variables below. Finally, position the point after the ++comment starter. @kbd{C-u M-;} kills any comment on the current line, ++together with any whitespace before it. This is a standard Emacs ++command, but @ccmode{} enhances it a bit with two variables: ++ ++@defopt c-indent-comment-alist ++@vindex indent-comment-alist (c-) ++@vindex comment-column ++This style variable allows you to vary the column that @kbd{M-;} puts ++the comment at, depending on what sort of code is on the line, and ++possibly the indentation of any similar comment on the preceding line. ++It is an association list that maps different types of lines to ++actions describing how they should be handled. If a certain line type ++isn't present on the list then the line is indented to the column ++specified by @code{comment-column}. ++ ++See the documentation string for a full description of this ++variable (use @kbd{C-h v c-indent-comment-alist}). ++@end defopt ++ ++@defopt c-indent-comments-syntactically-p ++@vindex indent-comments-syntactically-p (c-) ++Normally, when this style variable is @code{nil}, @kbd{M-;} will ++indent comment-only lines according to @code{c-indent-comment-alist}, ++just as it does with lines where other code precede the comments. ++However, if you want it to act just like @key{TAB} for comment-only ++lines you can get that by setting ++@code{c-indent-comments-syntactically-p} to non-@code{nil}. ++ ++If @code{c-indent-comments-syntactically-p} is non-@code{nil} then ++@code{c-indent-comment-alist} won't be consulted at all for comment-only ++lines. ++@end defopt ++@end table ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Movement Commands, Filling and Breaking, Comment Commands, Commands ++@comment node-name, next, previous, up ++@section Movement Commands ++@cindex movement ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@ccmode{} contains some useful commands for moving around in C code. ++ ++@table @asis ++@item @kbd{C-M-a} (@code{c-beginning-of-defun}) ++@itemx @kbd{C-M-e} (@code{c-end-of-defun}) ++@findex c-beginning-of-defun ++@findex c-end-of-defun ++ ++Move to the beginning or end of the current or next function. Other ++constructs (such as a structs or classes) which have a brace block ++also count as ``functions'' here. To move over several functions, you ++can give these commands a repeat count. ++ ++The start of a function is at its header. The end of the function is ++after its closing brace, or after the semicolon of a construct (such ++as a @code{struct}) which doesn't end at the brace. These two ++commands try to leave point at the beginning of a line near the actual ++start or end of the function. This occasionally causes point not to ++move at all. ++ ++These functions are analogous to the Emacs built-in commands ++@code{beginning-of-defun} and @code{end-of-defun}, except they ++eliminate the constraint that the top-level opening brace of the defun ++must be in column zero. See @ref{Defuns,,,@emacsman{}, ++@emacsmantitle{}}, for more information. ++ ++@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun}) ++@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun}) ++@kindex C-M-a (AWK Mode) ++@kindex C-M-e (AWK Mode) ++@findex c-awk-beginning-of-defun ++@findex awk-beginning-of-defun (c-) ++@findex c-awk-end-of-defun ++@findex awk-end-of-defun (c-) ++Move to the beginning or end of the current or next AWK defun. These ++commands can take prefix-arguments, their functionality being entirely ++equivalent to @code{beginning-of-defun} and @code{end-of-defun}. ++ ++AWK Mode @dfn{defuns} are either pattern/action pairs (either of which ++might be implicit) or user defined functions. Having the @samp{@{} and ++@samp{@}} (if there are any) in column zero, as is suggested for some ++modes, is neither necessary nor helpful in AWK mode. ++ ++@item @kbd{M-a} (@code{c-beginning-of-statement}) ++@itemx @kbd{M-e} (@code{c-end-of-statement}) ++@kindex M-a ++@kindex M-e ++@findex c-beginning-of-statement ++@findex c-end-of-statement ++@findex beginning-of-statement (c-) ++@findex end-of-statement (c-) ++Move to the beginning or end of the innermost C statement. If point ++is already there, move to the next beginning or end of a statement, ++even if that means moving into a block. (Use @kbd{C-M-b} or ++@kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n} ++means move over @var{n} statements. ++ ++If point is within or next to a comment or a string which spans more ++than one line, these commands move by sentences instead of statements. ++ ++When called from a program, these functions take three optional ++arguments: the repetition count, a buffer position limit which is the ++farthest back to search for the syntactic context, and a flag saying ++whether to do sentence motion in or near comments and multiline ++strings. ++ ++@item @kbd{C-c C-u} (@code{c-up-conditional}) ++@kindex C-c C-u ++@findex c-up-conditional ++@findex up-conditional (c-) ++Move back to the containing preprocessor conditional, leaving the mark ++behind. A prefix argument acts as a repeat count. With a negative ++argument, move forward to the end of the containing preprocessor ++conditional. ++ ++@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the ++function stops at them when going backward, but not when going ++forward. ++ ++This key sequence is not bound in AWK Mode, which doesn't have ++preprocessor statements. ++ ++@item @kbd{M-x c-up-conditional-with-else} ++@findex c-up-conditional-with-else ++@findex up-conditional-with-else (c-) ++A variety of @code{c-up-conditional} that also stops at @samp{#else} ++lines. Normally those lines are ignored. ++ ++@item @kbd{M-x c-down-conditional} ++@findex c-down-conditional ++@findex down-conditional (c-) ++Move forward into the next nested preprocessor conditional, leaving ++the mark behind. A prefix argument acts as a repeat count. With a ++negative argument, move backward into the previous nested preprocessor ++conditional. ++ ++@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the ++function stops at them when going forward, but not when going backward. ++ ++@item @kbd{M-x c-down-conditional-with-else} ++@findex c-down-conditional-with-else ++@findex down-conditional-with-else (c-) ++A variety of @code{c-down-conditional} that also stops at @samp{#else} ++lines. Normally those lines are ignored. ++ ++@item @kbd{C-c C-p} (@code{c-backward-conditional}) ++@itemx @kbd{C-c C-n} (@code{c-forward-conditional}) ++@kindex C-c C-p ++@kindex C-c C-n ++@findex c-backward-conditional ++@findex c-forward-conditional ++@findex backward-conditional (c-) ++@findex forward-conditional (c-) ++Move backward or forward across a preprocessor conditional, leaving ++the mark behind. A prefix argument acts as a repeat count. With a ++negative argument, move in the opposite direction. ++ ++These key sequences are not bound in AWK Mode, which doesn't have ++preprocessor statements. ++ ++@item @kbd{M-x c-backward-into-nomenclature} ++@itemx @kbd{M-x c-forward-into-nomenclature} ++@findex c-backward-into-nomenclature ++@findex c-forward-into-nomenclature ++@findex backward-into-nomenclature (c-) ++@findex forward-into-nomenclature (c-) ++A popular programming style, especially for object-oriented languages ++such as C++ is to write symbols in a mixed case format, where the ++first letter of each word is capitalized, and not separated by ++underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. ++ ++These commands move backward or forward to the beginning of the next ++capitalized word. With prefix argument @var{n}, move @var{n} times. ++If @var{n} is negative, move in the opposite direction. ++ ++Note that these two commands have been superseded by ++@code{c-subword-mode}, which you should use instead. @xref{Subword ++Movement}. They might be removed from a future release of @ccmode{}. ++@end table ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Filling and Breaking, Minor Modes, Movement Commands, Commands ++@comment node-name, next, previous, up ++@section Filling and Line Breaking Commands ++@cindex text filling ++@cindex line breaking ++@cindex comment handling ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Since there's a lot of normal text in comments and string literals, ++@ccmode{} provides features to edit these like in text mode. The goal ++is to do it seamlessly, i.e. you can use auto fill mode, sentence and ++paragraph movement, paragraph filling, adaptive filling etc. wherever ++there's a piece of normal text without having to think much about it. ++@ccmode{} keeps the indentation, fixes suitable comment line prefixes, ++and so on. ++ ++You can configure the exact way comments get filled and broken, and ++where Emacs does auto-filling (see @pxref{Custom Filling and ++Breaking}). Typically, the style system (@pxref{Styles}) will have ++set this up for you, so you probably won't have to bother. ++ ++@findex auto-fill-mode ++@cindex Auto Fill mode ++@cindex paragraph filling ++Line breaks are by default handled (almost) the same regardless of ++whether they are made by auto fill mode (@pxref{Auto Fill,,, ++@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with ++@kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In ++string literals, the new line gets the same indentation as the ++previous nonempty line.@footnote{You can change this default by ++setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols} ++and @pxref{Customizing Indentation})}. ++ ++@table @asis ++@item @kbd{M-q} (@code{c-fill-paragraph}) ++@kindex M-q ++@findex c-fill-paragraph ++@findex fill-paragraph (c-) ++@cindex Javadoc markup ++@cindex Pike autodoc markup ++This command fills multiline string literals and both block ++and line style comments. In Java buffers, the Javadoc markup words ++are recognized as paragraph starters. The line oriented Pike autodoc ++markup words are recognized in the same way in Pike mode. ++ ++The formatting of the starters (@code{/*}) and enders (@code{*/}) of ++block comments are kept as they were before the filling. I.e., if ++either the starter or ender were on a line of its own, then it stays ++on its own line; conversely, if the delimiter has comment text on its ++line, it keeps at least one word of that text with it on the line. ++ ++This command is the replacement for @code{fill-paragraph} in @ccmode{} ++buffers. ++ ++@item @kbd{M-j} (@code{c-indent-new-comment-line}) ++@kindex M-j ++@findex c-indent-new-comment-line ++@findex indent-new-comment-line (c-) ++This breaks the current line at point and indents the new line. If ++point was in a comment, the new line gets the proper comment line ++prefix. If point was inside a macro, a backslash is inserted before ++the line break. It is the replacement for ++@code{indent-new-comment-line}. ++ ++@item @kbd{M-x c-context-line-break} ++@findex c-context-line-break ++@findex context-line-break (c-) ++Insert a line break suitable to the context: If the point is inside a ++comment, the new line gets the suitable indentation and comment line ++prefix like @code{c-indent-new-comment-line}. In normal code it's ++indented like @code{newline-and-indent} would do. In macros it acts ++like @code{newline-and-indent} but additionally inserts and optionally ++aligns the line ending backslash so that the macro remains unbroken. ++@xref{Custom Macros}, for details about the backslash alignment. In a ++string, a backslash is inserted only if the string is within a ++macro@footnote{In GCC, unescaped line breaks within strings are ++valid.}. ++ ++This function is not bound to a key by default, but it's intended to be ++used on the @kbd{RET} key. If you like the behavior of ++@code{newline-and-indent} on @kbd{RET}, you should consider switching to ++this function. @xref{Sample .emacs File}. ++ ++@item @kbd{M-x c-context-open-line} ++@findex c-context-open-line ++@findex context-open-line (c-) ++This is to @kbd{C-o} (@kbd{M-x open-line}) as ++@code{c-context-line-break} is to @kbd{RET}. I.e. it works just like ++@code{c-context-line-break} but leaves the point before the inserted ++line break. ++@end table ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Minor Modes, Electric Keys, Filling and Breaking, Commands ++@comment node-name, next, previous, up ++@section Minor Modes ++@cindex Minor Modes ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@ccmode{} contains several minor-mode-like features that you might ++find useful while writing new code or editing old code: ++ ++@table @asis ++@item electric mode ++When this is enabled, certain visible characters cause reformatting as ++they are typed. This is normally helpful, but can be a nuisance when ++editing chaotically formatted code. It can also be disconcerting, ++especially for users who are new to @ccmode{}. ++@item auto-newline mode ++This automatically inserts newlines where you'd probably want to type ++them yourself, e.g. after typing @samp{@}}s. Its action is suppressed ++when electric mode is disabled. ++@item hungry-delete mode ++This lets you delete a contiguous block of whitespace with a single ++key - for example, the newline and indentation just inserted by ++auto-newline when you want to back up and write a comment after the ++last statement. ++@item subword mode ++This mode makes basic word movement commands like @kbd{M-f} ++(@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the ++parts of sillycapsed symbols as different words. ++E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS}, ++@samp{Graphics}, and @samp{Context}. ++@item syntactic-indentation mode ++When this is enabled (which it normally is), indentation commands such ++as @kbd{C-j} indent lines of code according to their syntactic ++structure. Otherwise, a line is simply indented to the same level as ++the previous one and @kbd{@key{TAB}} adjusts the indentation in steps ++of `c-basic-offset'. ++@end table ++ ++Full details on how these minor modes work are at @ref{Electric Keys}, ++@ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement}, ++and @ref{Indentation Engine Basics}. ++ ++You can toggle each of these minor modes on and off, and you can ++configure @ccmode{} so that it starts up with your favourite ++combination of them (@pxref{Sample .emacs File}). By default, when ++you initialize a buffer, electric mode and syntactic-indentation mode ++are enabled but the other two modes are disabled. ++ ++@ccmode{} displays the current state of the first four of these minor ++modes on the modeline by appending letters to the major mode's name, ++one letter for each enabled minor mode - @samp{l} for electric mode, ++@samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and ++@samp{w} for subword mode. If all these modes were enabled, you'd see ++@samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of ++the language in question for the other languages @ccmode{} supports.}. ++ ++Here are the commands to toggle these modes: ++ ++@table @asis ++@item @kbd{C-c C-l} (@code{c-toggle-electric-state}) ++@kindex C-c C-l ++@findex c-toggle-electric-state ++@findex toggle-electric-state (c-) ++Toggle electric minor mode. When the command turns the mode off, it ++also suppresses auto-newline mode. ++ ++@item @kbd{C-c C-a} (@code{c-toggle-auto-newline}) ++@kindex C-c C-a ++@findex c-toggle-auto-newline ++@findex toggle-auto-newline (c-) ++Toggle auto-newline minor mode. When the command turns the mode on, ++it also enables electric minor mode. ++ ++@item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.} ++@findex c-toggle-hungry-state ++@findex toggle-hungry-state (c-) ++Toggle hungry-delete minor mode. ++ ++@item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.} ++@findex c-toggle-auto-hungry-state ++@findex toggle-auto-hungry-state (c-) ++Toggle both auto-newline and hungry delete minor modes. ++ ++@item @kbd{C-c C-w} (@code{M-x c-subword-mode}) ++@kindex C-c C-w ++@findex c-subword-mode ++@findex subword-mode (c-) ++Toggle subword mode. ++ ++@item @kbd{M-x c-toggle-syntactic-indentation} ++@findex c-toggle-syntactic-indentation ++@findex toggle-syntactic-indentation (c-) ++Toggle syntactic-indentation mode. ++@end table ++ ++Common to all the toggle functions above is that if they are called ++programmatically, they take an optional numerical argument. A ++positive value will turn on the minor mode (or both of them in the ++case of @code{c-toggle-auto-hungry-state}) and a negative value will ++turn it (or them) off. ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Electric Keys, Auto-newlines, Minor Modes, Commands ++@comment node-name, next, previous, up ++@section Electric Keys and Keywords ++@cindex electric characters ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Most punctuation keys provide @dfn{electric} behavior - as well as ++inserting themselves they perform some other action, such as ++reindenting the line. This reindentation saves you from having to ++reindent a line manually after typing, say, a @samp{@}}. A few ++keywords, such as @code{else}, also trigger electric action. ++ ++You can inhibit the electric behavior described here by disabling ++electric minor mode (@pxref{Minor Modes}). ++ ++Common to all these keys is that they only behave electrically when ++used in normal code (as contrasted with getting typed in a string ++literal or comment). Those which cause re-indentation do so only when ++@code{c-syntactic-indentation} has a non-@code{nil} value (which it ++does by default). ++ ++These keys and keywords are: ++@c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more ++@c like a bug in the code than a bug in this document. It'll get ++@c fixed in the code sometime. ++ ++@table @kbd ++@item # ++@kindex # ++@findex c-electric-pound ++@findex electric-pound (c-) ++@vindex c-electric-pound-behavior ++@vindex electric-pound-behavior (c-) ++Pound (bound to @code{c-electric-pound}) is electric when typed as the ++first non-whitespace character on a line and not within a macro ++definition. In this case, the variable @code{c-electric-pound-behavior} ++is consulted for the electric behavior. This variable takes a list ++value, although the only element currently defined is @code{alignleft}, ++which tells this command to force the @samp{#} character into column ++zero. This is useful for entering preprocessor macro definitions. ++ ++Pound is not electric in AWK buffers, where @samp{#} starts a comment, ++and is bound to @code{self-insert-command} like any typical printable ++character. ++@c ACM, 2004/8/24: Change this (and the code) to do AWK comment ++@c reindentation. ++ ++@item * ++@kindex * ++@itemx / ++@kindex / ++@findex c-electric-star ++@findex electric-star (c-) ++@findex c-electric-slash ++@findex electric-slash (c-) ++A star (bound to @code{c-electric-star}) or a slash ++(@code{c-electric-slash}) causes reindentation when you type it as the ++second component of a C style block comment opener (@samp{/*}) or a ++C++ line comment opener (@samp{//}) respectively, but only if the ++comment opener is the first thing on the line (i.e. there's only ++whitespace before it). ++ ++Additionally, you can configure @ccmode{} so that typing a slash at ++the start of a line within a block comment will terminate the ++comment. You don't need to have electric minor mode enabled to get ++this behavior. @xref{Clean-ups}. ++ ++In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not ++electric. ++ ++@item < ++@kindex < ++@itemx > ++@kindex > ++@findex c-electric-lt-gt ++@findex electric-lt-gt (c-) ++A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is ++electric in two circumstances: when it is an angle bracket in a C++ ++@samp{template} declaration (and similar constructs in other ++languages) and when it is the second of two @kbd{<} or @kbd{>} ++characters in a C++ style stream operator. In either case, the line ++is reindented. Angle brackets in C @samp{#include} directives are not ++electric. ++ ++@item ( ++@kindex ( ++@itemx ) ++@kindex ) ++@findex c-electric-paren ++@findex electric-paren (c-) ++The normal parenthesis characters @samp{(} and @samp{)} (bound to ++@code{c-electric-paren}) reindent the current line. This is useful ++for getting the closing parenthesis of an argument list aligned ++automatically. ++ ++You can also configure @ccmode{} to insert a space automatically ++between a function name and the @samp{(} you've just typed, and to ++remove it automatically after typing @samp{)}, should the argument ++list be empty. You don't need to have electric minor mode enabled to ++get these actions. @xref{Clean-ups}. ++ ++@item @{ ++@kindex @{ ++@itemx @} ++@kindex @} ++@findex c-electric-brace ++@findex electric-brace (c-) ++Typing a brace (bound to @code{c-electric-brace}) reindents the ++current line. Also, one or more newlines might be inserted if ++auto-newline minor mode is enabled. @xref{Auto-newlines}. ++Additionally, you can configure @ccmode{} to compact excess whitespace ++inserted by auto-newline mode in certain circumstances. ++@xref{Clean-ups}. ++ ++@item : ++@kindex : ++@findex c-electric-colon ++@findex electric-colon (c-) ++Typing a colon (bound to @code{c-electric-colon}) reindents the ++current line. Additionally, one or more newlines might be inserted if ++auto-newline minor mode is enabled. @xref{Auto-newlines}. If you ++type a second colon immediately after such an auto-newline, by default ++the whitespace between the two colons is removed, leaving a C++ scope ++operator. @xref{Clean-ups}. ++ ++If you prefer, you can insert @samp{::} in a single operation, ++avoiding all these spurious reindentations, newlines, and clean-ups. ++@xref{Other Commands}. ++ ++@item ; ++@kindex ; ++@itemx , ++@kindex , ++@findex c-electric-semi&comma ++@findex electric-semi&comma (c-) ++Typing a semicolon or comma (bound to @code{c-electric-semi&comma}) ++reindents the current line. Also, a newline might be inserted if ++auto-newline minor mode is enabled. @xref{Auto-newlines}. ++Additionally, you can configure @ccmode{} so that when auto-newline ++has inserted whitespace after a @samp{@}}, it will be removed again ++when you type a semicolon or comma just after it. @xref{Clean-ups}. ++ ++@end table ++ ++@deffn Command c-electric-continued-statement ++@findex electric-continued-statement (c-) ++ ++Certain keywords are electric, causing reindentation when they are ++preceded only by whitespace on the line. The keywords are those that ++continue an earlier statement instead of starting a new one: ++@code{else}, @code{while}, @code{catch} (only in C++ and Java) and ++@code{finally} (only in Java). ++ ++An example: ++ ++@example ++@group ++for (i = 0; i < 17; i++) ++ if (a[i]) ++ res += a[i]->offset; ++else ++@end group ++@end example ++ ++Here, the @code{else} should be indented like the preceding @code{if}, ++since it continues that statement. @ccmode{} will automatically ++reindent it after the @code{else} has been typed in full, since only ++then is it possible to decide whether it's a new statement or a ++continuation of the preceding @code{if}. ++ ++@vindex abbrev-mode ++@findex abbrev-mode ++@cindex Abbrev mode ++@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}}) ++to accomplish this. It's therefore turned on by default in all language ++modes except IDL mode, since CORBA IDL doesn't have any statements. ++@end deffn ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands ++@comment node-name, next, previous, up ++@section Auto-newline Insertion ++@cindex auto-newline ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor ++Modes}), @ccmode{} inserts newlines for you automatically (in certain ++syntactic contexts) when you type a left or right brace, a colon, a ++semicolon, or a comma. Sometimes a newline appears before the ++character you type, sometimes after it, sometimes both. ++ ++Auto-newline only triggers when the following conditions hold: ++ ++@itemize @bullet ++@item ++Auto-newline minor mode is enabled, as evidenced by the indicator ++@samp{a} after the mode name on the modeline (e.g. @samp{C/a} or ++@samp{C/la}). ++ ++@item ++The character was typed at the end of a line, or with only whitespace ++after it, and possibly a @samp{\} escaping the newline. ++ ++@item ++The character is not on its own line already. (This applies only to ++insertion of a newline @emph{before} the character.) ++ ++@item ++@cindex literal ++@cindex syntactic whitespace ++The character was not typed inside of a literal @footnote{A ++@dfn{literal} is defined as any comment, string, or preprocessor macro ++definition. These constructs are also known as @dfn{syntactic ++whitespace} since they are usually ignored when scanning C code.}. ++ ++@item ++No numeric argument was supplied to the command (i.e. it was typed as ++normal, with no @kbd{C-u} prefix). ++@end itemize ++ ++You can configure the precise circumstances in which newlines get ++inserted (see @pxref{Custom Auto-newlines}). Typically, the style ++system (@pxref{Styles}) will have set this up for you, so you probably ++won't have to bother. ++ ++Sometimes @ccmode{} inserts an auto-newline where you don't want one, ++such as after a @samp{@}} when you're about to type a @samp{;}. ++Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can ++activate an appropriate @dfn{clean-up}, which will remove the excess ++whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a ++full description. See also @ref{Electric Keys} for a summary of ++clean-ups listed by key. ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands ++@comment node-name, next, previous, up ++@section Hungry Deletion of Whitespace ++@cindex hungry-deletion ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++If you want to delete an entire block of whitespace at point, you can ++use @dfn{hungry deletion}. This deletes all the contiguous whitespace ++either before point or after point in a single operation. ++``Whitespace'' here includes tabs and newlines, but not comments or ++preprocessor commands. Hungry deletion can markedly cut down on the ++number of times you have to hit deletion keys when, for example, ++you've made a mistake on the preceding line and have already pressed ++@kbd{C-j}. ++ ++Hungry deletion is a simple feature that some people find extremely ++useful. In fact, you might find yourself wanting it in @strong{all} ++your editing modes! ++ ++Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the ++backspace key'' and @dfn{@key{DELETE}} means ``the forward delete ++key''. This is discussed in more detail below. ++ ++There are two different ways you can use hungry deletion: ++ ++@table @asis ++@item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d} ++Here you toggle Hungry Delete minor mode with @kbd{M-x ++c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command ++was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding ++for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This ++makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry ++deletion. ++ ++@table @asis ++@item @kbd{@key{DEL}} (@code{c-electric-backspace}) ++@kindex DEL ++@findex c-electric-backspace ++@findex electric-backspace (c-) ++This command is run by default when you hit the @kbd{DEL} key. When ++hungry delete mode is enabled, it deletes any amount of whitespace in ++the backwards direction. Otherwise, or when used with a prefix ++argument or in a literal (@pxref{Auto-newlines}), the command just ++deletes backwards in the usual way. (More precisely, it calls the ++function contained in the variable @code{c-backspace-function}, ++passing it the prefix argument, if any.) ++ ++@item @code{c-backspace-function} ++@vindex c-backspace-function ++@vindex backspace-function (c-) ++@findex backward-delete-char-untabify ++Hook that gets called by @code{c-electric-backspace} when it doesn't ++do an ``electric'' deletion of the preceding whitespace. The default ++value is @code{backward-delete-char-untabify} ++(@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which ++deletes a single character. ++ ++@item @kbd{C-d} (@code{c-electric-delete-forward}) ++@kindex C-d ++@findex c-electric-delete-forward ++@findex electric-delete-forward (c-) ++This function, which is bound to @kbd{C-d} by default, works just like ++@code{c-electric-backspace} but in the forward direction. When it ++doesn't do an ``electric'' deletion of the following whitespace, it ++just does @code{delete-char}, more or less. (Strictly speaking, it ++calls the function in @code{c-delete-function} with the prefix ++argument.) ++ ++@item @code{c-delete-function} ++@vindex c-delete-function ++@vindex delete-function (c-) ++@findex delete-char ++Hook that gets called by @code{c-electric-delete-forward} when it ++doesn't do an ``electric'' deletion of the following whitespace. The ++default value is @code{delete-char}. ++@end table ++ ++@item Using Distinct Bindings ++The other (newer and recommended) way to use hungry deletion is to ++perform @code{c-hungry-delete-backwards} and ++@code{c-hungry-delete-forward} directly through their key sequences ++rather than using the minor mode toggling. ++ ++@table @asis ++@item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.} ++@kindex C-c C- ++@kindex C-c ++@kindex C-c C-DEL ++@kindex C-c DEL ++@findex c-hungry-delete-backwards ++@findex hungry-delete-backwards (c-) ++Delete any amount of whitespace in the backwards direction (regardless ++whether hungry-delete mode is enabled or not). This command is bound ++to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more ++natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at ++a character terminal. ++ ++@item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward}) ++@kindex C-c C-d ++@kindex C-c C- ++@kindex C-c ++@findex c-hungry-delete-forward ++@findex hungry-delete-forward (c-) ++Delete any amount of whitespace in the forward direction (regardless ++whether hungry-delete mode is enabled or not). This command is bound ++to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the ++same reason as for @key{DEL} above. ++@end table ++@end table ++ ++@kindex ++@kindex ++ ++When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we ++actually do so without connecting them to the physical keys commonly ++known as @key{Backspace} and @key{Delete}. The default bindings to ++those two keys depends on the flavor of (X)Emacs you are using. ++ ++@findex c-electric-delete ++@findex electric-delete (c-) ++@findex c-hungry-delete ++@findex hungry-delete (c-) ++@vindex delete-key-deletes-forward ++In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to ++@code{c-electric-backspace} and the @key{Delete} key is bound to ++@code{c-electric-delete}. You control the direction it deletes in by ++setting the variable @code{delete-key-deletes-forward}, a standard ++XEmacs variable. ++@c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...). ++When this variable is non-@code{nil}, @code{c-electric-delete} will do ++forward deletion with @code{c-electric-delete-forward}, otherwise it ++does backward deletion with @code{c-electric-backspace}. Similarly, ++@kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to ++@code{c-hungry-delete} which is controlled in the same way by ++@code{delete-key-deletes-forward}. ++ ++@findex normal-erase-is-backspace-mode ++ ++Emacs 21 and later automatically binds @key{Backspace} and ++@key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment, ++and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}} ++etc. If you need to change the bindings through ++@code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt ++its extended bindings accordingly. ++ ++In earlier (X)Emacs versions, @ccmode{} doesn't bind either ++@key{Backspace} or @key{Delete} directly. Only the key codes ++@kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings ++to map the physical keys to them. You might need to modify this ++yourself if the defaults are unsuitable. ++ ++Getting your @key{Backspace} and @key{Delete} keys properly set up can ++sometimes be tricky. The information in @ref{DEL Does Not ++Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having ++trouble with this in GNU Emacs. ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Subword Movement, Other Commands, Hungry WS Deletion, Commands ++@comment node-name, next, previous, up ++@section Subword Movement and Editing ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex nomenclature ++@cindex subword ++In spite of the GNU Coding Standards, it is popular to name a symbol ++by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget}, ++@samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call ++these mixed case symbols @dfn{nomenclatures}. Also, each capitalized ++(or completely uppercase) part of a nomenclature is called a ++@dfn{subword}. Here are some examples: ++ ++@multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}} ++@c This could be converted to @headitem when we require Texinfo 4.7 ++@iftex ++@item @b{Nomenclature} ++ @tab @b{Subwords} ++@end iftex ++@ifnottex ++@item Nomenclature ++ @tab Subwords ++@item --------------------------------------------------------- ++@end ifnottex ++@item @samp{GtkWindow} ++ @tab @samp{Gtk} and @samp{Window} ++@item @samp{EmacsFrameClass} ++ @tab @samp{Emacs}, @samp{Frame}, and @samp{Class} ++@item @samp{NSGraphicsContext} ++ @tab @samp{NS}, @samp{Graphics}, and @samp{Context} ++@end multitable ++ ++The subword minor mode replaces the basic word oriented movement and ++editing commands with variants that recognize subwords in a ++nomenclature and treat them as separate words: ++ ++@findex c-forward-subword ++@findex forward-subword (c-) ++@findex c-backward-subword ++@findex backward-subword (c-) ++@findex c-mark-subword ++@findex mark-subword (c-) ++@findex c-kill-subword ++@findex kill-subword (c-) ++@findex c-backward-kill-subword ++@findex backward-kill-subword (c-) ++@findex c-transpose-subwords ++@findex transpose-subwords (c-) ++@findex c-capitalize-subword ++@findex capitalize-subword (c-) ++@findex c-upcase-subword ++@findex upcase-subword (c-) ++@findex c-downcase-subword ++@findex downcase-subword (c-) ++@multitable @columnfractions .20 .40 .40 ++@c This could be converted to @headitem when we require Texinfo 4.7 ++@iftex ++@item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command} ++@end iftex ++@ifnottex ++@item Key @tab Word oriented command @tab Subword oriented command ++@item ---------------------------------------------------------------------------- ++@end ifnottex ++@item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword} ++@item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword} ++@item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword} ++@item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword} ++@item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword} ++@item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords} ++@item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword} ++@item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword} ++@item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword} ++@end multitable ++ ++Note that if you have changed the key bindings for the word oriented ++commands in your @file{.emacs} or a similar place, the keys you have ++configured are also used for the corresponding subword oriented ++commands. ++ ++Type @kbd{C-c C-w} to toggle subword mode on and off. To make the ++mode turn on automatically, put the following code in your ++@file{.emacs}: ++ ++@example ++(add-hook 'c-mode-common-hook ++ (lambda () (c-subword-mode 1))) ++@end example ++ ++As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{} ++buffers by typing @kbd{M-x c-subword-mode}. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Other Commands, , Subword Movement, Commands ++@comment node-name, next, previous, up ++@section Other Commands ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Here are the various other commands that didn't fit anywhere else: ++ ++@table @asis ++@item @kbd{C-c .} (@code{c-set-style}) ++@kindex C-c . ++@findex c-set-style ++@findex set-style (c-) ++Switch to the specified style in the current buffer. Use like this: ++ ++@example ++@kbd{C-c . @var{style-name} @key{RET}} ++@end example ++ ++You can use the @key{TAB} in the normal way to do completion on the ++style name. Note that all style names are case insensitive, even the ++ones you define yourself. ++ ++Setting a style in this way does @emph{not} automatically reindent your ++file. For commands that you can use to view the effect of your changes, ++see @ref{Indentation Commands} and @ref{Filling and Breaking}. ++ ++For details of the @ccmode{} style system, see @ref{Styles}. ++@item @kbd{C-c :} (@code{c-scope-operator}) ++@kindex C-c : ++@findex c-scope-operator ++@findex scope-operator (c-) ++In C++, it is also sometimes desirable to insert the double-colon scope ++operator without performing the electric behavior of colon insertion. ++@kbd{C-c :} does just this. ++ ++@item @kbd{C-c C-\} (@code{c-backslash-region}) ++@kindex C-c C-\ ++@findex c-backslash-region ++@findex backslash-region (c-) ++This function inserts and aligns or deletes end-of-line backslashes in ++the current region. These are typically used in multi-line macros. ++ ++With no prefix argument, it inserts any missing backslashes and aligns ++them according to the @code{c-backslash-column} and ++@code{c-backslash-max-column} variables. With a prefix argument, it ++deletes any backslashes. ++ ++The function does not modify blank lines at the start of the region. If ++the region ends at the start of a line, it always deletes the backslash ++(if any) at the end of the previous line. ++ ++To customize the precise workings of this command, @ref{Custom Macros}. ++@end table ++ ++@noindent ++The recommended line breaking function, @code{c-context-line-break} ++(@pxref{Filling and Breaking}), is especially nice if you edit ++multiline macros frequently. When used inside a macro, it ++automatically inserts and adjusts the mandatory backslash at the end ++of the line to keep the macro together, and it leaves the point at the ++right indentation column for the code. Thus you can write code inside ++macros almost exactly as you can elsewhere, without having to bother ++with the trailing backslashes. ++ ++@table @asis ++@item @kbd{C-c C-e} (@code{c-macro-expand}) ++@kindex C-c C-e ++@findex c-macro-expand ++@findex macro-expand (c-) ++This command expands C, C++, Objective C or Pike macros in the region, ++using an appropriate external preprocessor program. Normally it ++displays its output in a temporary buffer, but if you give it a prefix ++arg (with @kbd{C-u C-c C-e}) it will overwrite the original region ++with the expansion. ++ ++The command does not work in any of the other modes, and the key ++sequence is not bound in these other modes. ++ ++@code{c-macro-expand} isn't actually part of @ccmode{}, even though it ++is bound to a @ccmode{} key sequence. If you need help setting it up ++or have other problems with it, you can either read its source code or ++ask for help in the standard (X)Emacs forums. ++@end table ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Font Locking, Config Basics, Commands, Top ++@comment node-name, next, previous, up ++@chapter Font Locking ++@cindex font locking ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex Font Lock mode ++ ++@ccmode{} provides font locking for its supported languages by ++supplying patterns for use with Font Lock mode. This means that you ++get distinct faces on the various syntactic parts such as comments, ++strings, keywords and types, which is very helpful in telling them ++apart at a glance and discovering syntactic errors. @xref{Font ++Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in ++@ccmode{} buffers. ++ ++@strong{Please note:} The font locking in AWK mode is currently not ++integrated with the rest of @ccmode{}. Only the last section of this ++chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other ++sections apply to the other languages. ++ ++@menu ++* Font Locking Preliminaries:: ++* Faces:: ++* Doc Comments:: ++* AWK Mode Font Locking:: ++@end menu ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Font Locking Preliminaries, Faces, Font Locking, Font Locking ++@comment node-name, next, previous, up ++@section Font Locking Preliminaries ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The font locking for most of the @ccmode{} languages were provided ++directly by the Font Lock package prior to version 5.30 of @ccmode{}. ++In the transition to @ccmode{} the patterns have been reworked ++completely and are applied uniformly across all the languages except AWK ++mode, just like the indentation rules (although each language still has ++some peculiarities of its own, of course). Since the languages ++previously had completely separate font locking patterns, this means ++that it's a bit different in most languages now. ++ ++The main goal for the font locking in @ccmode{} is accuracy, to provide ++a dependable aid in recognizing the various constructs. Some, like ++strings and comments, are easy to recognize while others, like ++declarations and types, can be very tricky. @ccmode{} can go to great ++lengths to recognize declarations and casts correctly, especially when ++the types aren't recognized by standard patterns. This is a fairly ++demanding analysis which can be slow on older hardware, and it can ++therefore be disabled by choosing a lower decoration level with the ++variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,, ++emacs, GNU Emacs Manual}). ++ ++@vindex font-lock-maximum-decoration ++ ++The decoration levels are used as follows: ++ ++@enumerate ++@comment 1 ++@item ++Minimal font locking: Fontify only comments, strings and preprocessor ++directives (in the languages that use cpp). ++ ++@comment 2 ++@item ++Fast font locking: In addition to level 1, fontify keywords, simple ++types and declarations that are easy to recognize. The variables ++@code{*-font-lock-extra-types} (where @samp{*} is the name of the ++language) are used to recognize types (see below). Documentation ++comments like Javadoc are fontified according to ++@code{c-doc-comment-style} (@pxref{Doc Comments}). ++ ++Use this if you think the font locking is too slow. It's the closest ++corresponding level to level 3 in the old font lock patterns. ++ ++@comment 3 ++@item ++Accurate font locking: Like level 2 but uses a different approach that ++can recognize types and declarations much more accurately. The ++@code{*-font-lock-extra-types} variables are still used, but user ++defined types are recognized correctly anyway in most cases. Therefore ++those variables should be fairly restrictive and not contain patterns ++that are uncertain. ++ ++@cindex Lazy Lock mode ++@cindex Just-in-time Lock mode ++ ++This level is designed for fairly modern hardware and a font lock ++support mode like Lazy Lock or Just-in-time Lock mode that only ++fontifies the parts that are actually shown. Fontifying the whole ++buffer at once can easily get bothersomely slow even on contemporary ++hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}. ++@end enumerate ++ ++@cindex user defined types ++@cindex types, user defined ++ ++Since user defined types are hard to recognize you can provide ++additional regexps to match those you use: ++ ++@defopt c-font-lock-extra-types ++@defoptx c++-font-lock-extra-types ++@defoptx objc-font-lock-extra-types ++@defoptx java-font-lock-extra-types ++@defoptx idl-font-lock-extra-types ++@defoptx pike-font-lock-extra-types ++For each language there's a variable @code{*-font-lock-extra-types}, ++where @samp{*} stands for the language in question. It contains a list ++of regexps that matches identifiers that should be recognized as types, ++e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t} ++as is customary in C code. Each regexp should not match more than a ++single identifier. ++ ++The default values contain regexps for many types in standard runtime ++libraries that are otherwise difficult to recognize, and patterns for ++standard type naming conventions like the @samp{_t} suffix in C and C++. ++Java, Objective-C and Pike have as a convention to start class names ++with capitals, so there are patterns for that in those languages. ++ ++Despite the names of these variables, they are not only used for ++fontification but in other places as well where @ccmode{} needs to ++recognize types. ++@end defopt ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Faces, Doc Comments, Font Locking Preliminaries, Font Locking ++@comment node-name, next, previous, up ++@section Faces ++@cindex faces ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@ccmode{} attempts to use the standard faces for programming languages ++in accordance with their intended purposes as far as possible. No extra ++faces are currently provided, with the exception of a replacement face ++@code{c-invalid-face} for emacsen that don't provide ++@code{font-lock-warning-face}. ++ ++@itemize @bullet ++@item ++@vindex font-lock-comment-face ++Normal comments are fontified in @code{font-lock-comment-face}. ++ ++@item ++@vindex font-lock-doc-face ++@vindex font-lock-doc-string-face ++@vindex font-lock-comment-face ++Comments that are recognized as documentation (@pxref{Doc Comments}) ++get @code{font-lock-doc-face} (Emacs) or ++@code{font-lock-doc-string-face} (XEmacs) if those faces exist. If ++they don't then @code{font-lock-comment-face} is used. ++ ++@item ++@vindex font-lock-string-face ++String and character literals are fontified in ++@code{font-lock-string-face}. ++ ++@item ++@vindex font-lock-keyword-face ++Keywords are fontified with @code{font-lock-keyword-face}. ++ ++@item ++@vindex font-lock-function-name-face ++@code{font-lock-function-name-face} is used for function names in ++declarations and definitions, and classes in those contexts. It's also ++used for preprocessor defines with arguments. ++ ++@item ++@vindex font-lock-variable-name-face ++Variables in declarations and definitions, and other identifiers in such ++variable contexts, get @code{font-lock-variable-name-face}. It's also ++used for preprocessor defines without arguments. ++ ++@item ++@vindex font-lock-constant-face ++@vindex font-lock-reference-face ++Builtin constants are fontified in @code{font-lock-constant-face} if it ++exists, @code{font-lock-reference-face} otherwise. As opposed to the ++preceding two faces, this is used on the names in expressions, and it's ++not used in declarations, even if there happen to be a @samp{const} in ++them somewhere. ++ ++@item ++@vindex font-lock-type-face ++@code{font-lock-type-face} is put on types (both predefined and user ++defined) and classes in type contexts. ++ ++@item ++@vindex font-lock-constant-face ++@vindex font-lock-reference-face ++Label identifiers get @code{font-lock-constant-face} if it exists, ++@code{font-lock-reference-face} otherwise. ++ ++@item ++Name qualifiers and identifiers for scope constructs are fontified like ++labels. ++ ++@item ++Special markup inside documentation comments are also fontified like ++labels. ++ ++@item ++@vindex font-lock-preprocessor-face ++@vindex font-lock-builtin-face ++@vindex font-lock-reference-face ++Preprocessor directives get @code{font-lock-preprocessor-face} if it ++exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face} ++or @code{font-lock-reference-face}, for lack of a closer equivalent. ++ ++@item ++@vindex font-lock-warning-face ++@vindex c-invalid-face ++@vindex invalid-face (c-) ++Some kinds of syntactic errors are fontified with ++@code{font-lock-warning-face} in Emacs. In older XEmacs versions ++there's no corresponding standard face, so there a special ++@code{c-invalid-face} is used, which is defined to stand out sharply by ++default. ++ ++Note that it's not used for @samp{#error} or @samp{#warning} directives, ++since those aren't syntactic errors in themselves. ++@end itemize ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Doc Comments, AWK Mode Font Locking, Faces, Font Locking ++@comment node-name, next, previous, up ++@section Documentation Comments ++@cindex documentation comments ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++There are various tools to supply documentation in the source as ++specially structured comments, e.g. the standard Javadoc tool in Java. ++@ccmode{} provides an extensible mechanism to fontify such comments and ++the special markup inside them. ++ ++@defopt c-doc-comment-style ++@vindex doc-comment-style (c-) ++This is a style variable that specifies which documentation comment ++style to recognize, e.g. @code{javadoc} for Javadoc comments. ++ ++The value may also be a list of styles, in which case all of them are ++recognized simultaneously (presumably with markup cues that don't ++conflict). ++ ++The value may also be an association list to specify different comment ++styles for different languages. The symbol for the major mode is then ++looked up in the alist, and the value of that element is interpreted as ++above if found. If it isn't found then the symbol `other' is looked up ++and its value is used instead. ++ ++The default value for @code{c-doc-comment-style} is ++@w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}. ++ ++Note that @ccmode{} uses this variable to set other variables that ++handle fontification etc. That's done at mode initialization or when ++you switch to a style which sets this variable. Thus, if you change it ++in some other way, e.g. interactively in a CC Mode buffer, you will need ++to do @kbd{M-x java-mode} (or whatever mode you're currently using) to ++reinitialize. ++ ++@findex c-setup-doc-comment-style ++@findex setup-doc-comment-style (c-) ++Note also that when @ccmode{} starts up, the other variables are ++modified before the mode hooks are run. If you change this variable in ++a mode hook, you'll have to call @code{c-setup-doc-comment-style} ++afterwards to redo that work. ++@end defopt ++ ++@ccmode{} currently provides handing of the following doc comment ++styles: ++ ++@table @code ++@item javadoc ++@cindex Javadoc markup ++Javadoc comments, the standard tool in Java. ++ ++@item autodoc ++@cindex Pike autodoc markup ++For Pike autodoc markup, the standard in Pike. ++ ++@item gtkdoc ++@cindex GtkDoc markup ++For GtkDoc markup, widely used in the Gnome community. ++@end table ++ ++The above is by no means complete. If you'd like to see support for ++other doc comment styles, please let us know (@pxref{Mailing Lists and ++Bug Reports}). ++ ++You can also write your own doc comment fontification support to use ++with @code{c-doc-comment-style}: Supply a variable or function ++@code{*-font-lock-keywords} where @samp{*} is the name you want to use ++in @code{c-doc-comment-style}. If it's a variable, it's prepended to ++@code{font-lock-keywords}. If it's a function, it's called at mode ++initialization and the result is prepended. For an example, see ++@code{javadoc-font-lock-keywords} in @file{cc-fonts.el}. ++ ++If you add support for another doc comment style, please consider ++contributing it - send a note to @email{bug-cc-mode@@gnu.org}. ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node AWK Mode Font Locking, , Doc Comments, Font Locking ++@comment node-name, next, previous, up ++@section AWK Mode Font Locking ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The general appearance of font-locking in AWK mode is much like in any ++other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs ++Lisp Reference Manual}. ++ ++The following faces are, however, used in a non-standard fashion in ++AWK mode: ++ ++@table @asis ++@item @code{font-lock-variable-name-face} ++This face was intended for variable declarations. Since variables are ++not declared in AWK, this face is used instead for AWK system ++variables (such as @code{NF}) and ``Special File Names'' (such as ++@code{"/dev/stderr"}). ++ ++@item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs) ++This face is normally used for preprocessor directives in @ccmode{}. ++There are no such things in AWK, so this face is used instead for ++standard functions (such as @code{match}). ++ ++@item @code{font-lock-string-face} ++As well as being used for strings, including localizable strings, ++(delimited by @samp{"} and @samp{_"}), this face is also used for AWK ++regular expressions (delimited by @samp{/}). ++ ++@item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs) ++This face highlights the following syntactically invalid AWK ++constructs: ++ ++@itemize @bullet ++@item ++An unterminated string or regular expression. Here the opening ++delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in ++@code{font-lock-warning-face}. This is most noticeable when typing in a ++new string/regular expression into a buffer, when the warning-face ++serves as a continual reminder to terminate the construct. ++ ++AWK mode fontifies unterminated strings/regular expressions ++differently from other modes: Only the text up to the end of the line ++is fontified as a string (escaped newlines being handled correctly), ++rather than the text up to the next string quote. ++ ++@item ++A space between the function name and opening parenthesis when calling ++a user function. The last character of the function name and the ++opening parenthesis are highlighted. This font-locking rule will ++spuriously highlight a valid concatenation expression where an ++identifier precedes a parenthesised expression. Unfortunately. ++ ++@item ++Whitespace following the @samp{\} in what otherwise looks like an ++escaped newline. The @samp{\} is highlighted. ++@end itemize ++@end table ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Config Basics, Custom Filling and Breaking, Font Locking, Top ++@comment node-name, next, previous, up ++@chapter Configuration Basics ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex Emacs Initialization File ++@cindex Configuration ++You configure @ccmode{} by setting Lisp variables and calling (and ++perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't ++difficult.}, which is usually done by adding code to an Emacs ++initialization file. This file might be @file{site-start.el} or ++@file{.emacs} or @file{init.el} or @file{default.el} or perhaps some ++other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For ++the sake of conciseness, we just call this file ``your @file{.emacs}'' ++throughout the rest of the manual. ++ ++Several of these variables (currently 16), are known collectively as ++@dfn{style variables}. @ccmode{} provides a special mechanism, known ++as @dfn{styles} to make it easier to set these variables as a group, ++to ``inherit'' settings from one style into another, and so on. Style ++variables remain ordinary Lisp variables, whose values can be read and ++changed independently of the style system. @xref{Style Variables}. ++ ++There are several ways you can write the code, depending on the ++precise effect you want---they are described further down on this page. ++If you are new to @ccmode{}, we suggest you begin with the simplest ++method, ``Top-level commands or the customization interface''. ++ ++If you make conflicting settings in several of these ways, the way ++that takes precedence is the one that appears latest in this list: ++@itemize @asis ++@item ++@table @asis ++@item Style ++@itemx Top-level command or ``customization interface'' ++@itemx Hook ++@itemx File Style ++@end table ++@end itemize ++ ++Here is a summary of the different ways of writing your configuration ++settings: ++ ++@table @asis ++@item Top-level commands or the ``customization interface'' ++Most simply, you can write @code{setq} and similar commands at the top ++level of your @file{.emacs} file. When you load a @ccmode{} buffer, ++it initializes its configuration from these global values (at least, ++for those settings you have given values to), so it makes sense to ++have these @code{setq} commands run @emph{before} @ccmode{} is first ++initialized---in particular, before any call to @code{desktop-read} ++(@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For ++example, you might set c-basic-offset thus: ++ ++@example ++(setq c-basic-offset 4) ++@end example ++ ++You can use the more user friendly Customization interface instead, ++but this manual does not cover in detail how that works. To do this, ++start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}. ++@xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}. ++@c The following note really belongs in the Emacs manual. ++Emacs normally writes the customizations at the end of your ++@file{.emacs} file. If you use @code{desktop-read}, you should edit ++your @file{.emacs} to place the call to @code{desktop-read} @emph{after} ++the customizations. ++ ++The first initialization of @ccmode{} puts a snapshot of the ++configuration settings into the special style @code{user}. ++@xref{Built-in Styles}. ++ ++For basic use of Emacs, either of these ways of configuring is ++adequate. However, the settings are then the same in all @ccmode{} ++buffers and it can be clumsy to communicate them between programmers. ++For more flexibility, you'll want to use one (or both) of @ccmode{}'s ++more sophisticated facilities, hooks and styles. ++ ++@item Hooks ++An Emacs @dfn{hook} is a place to put Lisp functions that you want ++Emacs to execute later in specific circumstances. ++@xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main ++hook and a language-specific hook for each language it supports - any ++functions you put onto these hooks get executed as the last part of a ++buffer's initialization. Typically you put most of your customization ++within the main hook, and use the language-specific hooks to vary the ++customization settings between language modes. For example, if you ++wanted different (non-standard) values of @code{c-basic-offset} in C ++Mode and Java Mode buffers, you could do it like this: ++ ++@example ++@group ++(defun my-c-mode-hook () ++ (setq c-basic-offset 3)) ++(add-hook 'c-mode-hook 'my-c-mode-hook) ++ ++(defun my-java-mode-hook () ++ (setq c-basic-offset 6)) ++(add-hook 'java-mode-hook 'my-java-mode-hook) ++@end group ++@end example ++ ++See @ref{CC Hooks} for more details on the use of @ccmode{} hooks. ++ ++@item Styles ++A @ccmode{} @dfn{style} is a coherent collection of customizations ++with a name. At any time, exactly one style is active in each ++@ccmode{} buffer, either the one you have selected or a default. ++@ccmode{} is delivered with several existing styles. Additionally, ++you can create your own styles, possibly based on these existing ++styles. If you worked in a programming team called the ``Free ++Group'', which had its own coding standards, you might well have this ++in your @file{.emacs} file: ++ ++@example ++(setq c-default-style '((java-mode . "java") ++ (awk-mode . "awk") ++ (other . "free-group-style"))) ++@end example ++ ++See @ref{Styles} for fuller details on using @ccmode{} styles and how ++to create them. ++ ++@item File Styles ++A @dfn{file style} is a rarely used variant of the ``style'' mechanism ++described above, which applies to an individual source file. To use ++it, you set certain Emacs local variables in a special block at the ++end of the source file. @xref{File Styles}. ++ ++@item Hooks with Styles ++For ultimate flexibility, you can use hooks and styles together. For ++example, if your team were developing a product which required a ++Linux driver, you'd probably want to use the ``linux'' style for the ++driver, and your own team's style for the rest of the code. You ++could achieve this with code like this in your @file{.emacs}: ++ ++@example ++@group ++(defun my-c-mode-hook () ++ (c-set-style ++ (if (and (buffer-file-name) ++ (string-match "/usr/src/linux" (buffer-file-name))) ++ "linux" ++ "free-group-style"))) ++(add-hook 'c-mode-hook 'my-c-mode-hook) ++@end group ++@end example ++ ++In a programming team, a hook is a also a good place for each member ++to put his own personal preferences. For example, you might be the ++only person in your team who likes Auto-newline minor mode. You could ++have it enabled by default by placing the following in your ++@file{.emacs}: ++ ++@example ++@group ++(defun my-turn-on-auto-newline () ++ (c-toggle-auto-newline 1)) ++(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline) ++@end group ++@end example ++@end table ++ ++@menu ++* CC Hooks:: ++* Style Variables:: ++* Styles:: ++@end menu ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node CC Hooks, Style Variables, Config Basics, Config Basics ++@comment node-name, next, previous, up ++@section Hooks ++@cindex mode hooks ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@c The node name is "CC Hooks" rather than "Hooks" because of a bug in ++@c some older versions of Info, e.g. the info.el in GNU Emacs 21.3. ++@c If you go to "Config Basics" and hit on the xref to "CC ++@c Hooks" the function Info-follow-reference searches for "*Note: CC ++@c Hooks" from the beginning of the page. If this node were instead ++@c named "Hooks", that search would spuriously find "*Note: ++@c Hooks(elisp)" and go to the wrong node. ++ ++@ccmode{} provides several hooks that you can use to customize the ++mode for your coding style. The main hook is ++@code{c-mode-common-hook}; typically, you'll put the bulk of your ++customizations here. In addition, each language mode has its own ++hook, allowing you to fine tune your settings individually for the ++different @ccmode{} languages, and there is a package initialization ++hook. Finally, there is @code{c-special-indent-hook}, which enables ++you to solve anomalous indentation problems. It is described in ++@ref{Other Indentation}, not here. All these hooks adhere to the ++standard Emacs conventions. ++ ++When you open a buffer, @ccmode{} first initializes it with the ++currently active style (@pxref{Styles}). Then it calls ++@code{c-mode-common-hook}, and finally it calls the language-specific ++hook. Thus, any style settings done in these hooks will override ++those set by @code{c-default-style}. ++ ++@defvar c-initialization-hook ++@vindex initialization-hook (c-) ++Hook run only once per Emacs session, when @ccmode{} is initialized. ++This is a good place to change key bindings (or add new ones) in any ++of the @ccmode{} key maps. @xref{Sample .emacs File}. ++@end defvar ++ ++@defvar c-mode-common-hook ++@vindex mode-common-hook (c-) ++Common hook across all languages. It's run immediately before the ++language specific hook. ++@end defvar ++ ++@defvar c-mode-hook ++@defvarx c++-mode-hook ++@defvarx objc-mode-hook ++@defvarx java-mode-hook ++@defvarx idl-mode-hook ++@defvarx pike-mode-hook ++@defvarx awk-mode-hook ++The language specific mode hooks. The appropriate one is run as the ++last thing when you enter that language mode. ++@end defvar ++ ++Although these hooks are variables defined in @ccmode{}, you can give ++them values before @ccmode{}'s code is loaded---indeed, this is the ++only way to use @code{c-initialization-hook}. Their values aren't ++overwritten when @ccmode{} gets loaded. ++ ++Here's a simplified example of what you can add to your @file{.emacs} ++file to do things whenever any @ccmode{} language is edited. See the ++Emacs manuals for more information on customizing Emacs via hooks. ++@xref{Sample .emacs File}, for a more complete sample @file{.emacs} ++file. ++ ++@example ++(defun my-c-mode-common-hook () ++ ;; my customizations for all of c-mode and related modes ++ (no-case-fold-search) ++ ) ++(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) ++@end example ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Style Variables, Styles, CC Hooks, Config Basics ++@comment node-name, next, previous, up ++@section Style Variables ++@cindex styles ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex style variables ++The variables that @ccmode{}'s style system control are called ++@dfn{style variables}. Note that style variables are ordinary Lisp ++variables, which the style system initializes; you can change their ++values at any time (e.g. in a hook function). The style system can ++also set other variables, to some extent. @xref{Styles}. ++ ++@dfn{Style variables} are handled specially in several ways: ++ ++@itemize @bullet ++@item ++Style variables are by default buffer-local variables. However, they ++can instead be made global by setting ++@code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is ++initialized. ++ ++@item ++@vindex c-old-style-variable-behavior ++@vindex old-style-variable-behavior (c-) ++The default global binding of any style variable (with two exceptions ++- see below) is the special symbol @code{set-from-style}. When the ++style system initializes a buffer-local copy of a style variable for a ++@ccmode{} buffer, if its global binding is still that symbol then it ++will be set from the current style. Otherwise it will retain its ++global default@footnote{This is a big change from versions of ++@ccmode{} earlier than 5.26, where such settings would get overridden ++by the style system unless special precautions were taken. That was ++changed since it was counterintuitive and confusing, especially to ++novice users. If your configuration depends on the old overriding ++behavior, you can set the variable ++@code{c-old-style-variable-behavior} to non-@code{nil}.}. This ++``otherwise'' happens, for example, when you've set the variable with ++@code{setq} at the top level of your @file{.emacs} (@pxref{Config ++Basics}). ++ ++@item ++The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is ++an association list with an element for each syntactic symbol. It's ++handled a little differently from the other style variables. It's ++default global binding is the empty list @code{nil}, rather than ++@code{set-from-style}. Before the style system is initialized, you ++can add individual elements to @code{c-offsets-alist} by calling ++@code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set ++other style variables with @code{setq}. Those elements will then ++prevail when the style system later initializes a buffer-local copy of ++@code{c-offsets-alist}. ++ ++@item ++The style variable @code{c-special-indent-hook} is also handled in a ++special way. Styles can only add functions to this hook, not remove ++them, so any global settings you put on it are always ++preserved@footnote{This did not change in version 5.26.}. The value ++you give this variable in a style definition can be either a function ++or a list of functions. ++ ++@item ++The global bindings of the style variables get captured in the special ++@code{user} style when the style system is first initialized. ++@xref{Built-in Styles}, for details. ++@end itemize ++ ++The style variables are:@* ++@code{c-indent-comment-alist}, ++@code{c-indent-comments-syntactically-p} (@pxref{Indentation ++Commands});@* ++@code{c-doc-comment-style} (@pxref{Doc Comments});@* ++@code{c-block-comment-prefix}, @code{c-comment-prefix-regexp} ++(@pxref{Custom Filling and Breaking});@* ++@code{c-hanging-braces-alist} (@pxref{Hanging Braces});@* ++@code{c-hanging-colons-alist} (@pxref{Hanging Colons});@* ++@code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and ++Commas});@* ++@code{c-cleanup-list} (@pxref{Clean-ups});@* ++@code{c-basic-offset} (@pxref{Customizing Indentation});@* ++@code{c-offsets-alist} (@pxref{c-offsets-alist});@* ++@code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@* ++@code{c-special-indent-hook}, @code{c-label-minimum-indentation} ++(@pxref{Other Indentation});@* ++@code{c-backslash-column}, @code{c-backslash-max-column} ++(@pxref{Custom Macros}). ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Styles, , Style Variables, Config Basics ++@comment node-name, next, previous, up ++@section Styles ++@cindex styles ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++By @dfn{style} we mean the layout of the code---things like how many ++columns to indent a block of code, whether an opening brace gets ++indented to the level of the code it encloses, or of the construct ++that introduces it, or ``hangs'' at the end of a line. ++ ++Most people only need to edit code formatted in just a few well-defined ++and consistent styles. For example, their organization might impose a ++``blessed'' style that all its programmers must conform to. Similarly, ++people who work on GNU software will have to use the GNU coding style. ++Some shops are more lenient, allowing a variety of coding styles, and as ++programmers come and go, there could be a number of styles in use. For ++this reason, @ccmode{} makes it convenient for you to set up logical ++groupings of customizations called @dfn{styles}, associate a single name ++for any particular style, and pretty easily start editing new or ++existing code using these styles. ++ ++@menu ++* Built-in Styles:: ++* Choosing a Style:: ++* Adding Styles:: ++* File Styles:: ++@end menu ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Built-in Styles, Choosing a Style, Styles, Styles ++@comment node-name, next, previous, up ++@subsection Built-in Styles ++@cindex styles, built-in ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++If you're lucky, one of @ccmode{}'s built-in styles might be just ++what you're looking for. These are: ++ ++@table @code ++@item gnu ++@cindex GNU style ++Coding style blessed by the Free Software Foundation ++for C code in GNU programs. ++ ++@item k&r ++@cindex K&R style ++The classic Kernighan and Ritchie style for C code. ++ ++@item bsd ++@cindex BSD style ++Also known as ``Allman style'' after Eric Allman. ++ ++@item whitesmith ++@cindex Whitesmith style ++Popularized by the examples that came with Whitesmiths C, an early ++commercial C compiler. ++ ++@item stroustrup ++@cindex Stroustrup style ++The classic Stroustrup style for C++ code. ++ ++@item ellemtel ++@cindex Ellemtel style ++Popular C++ coding standards as defined by ``Programming in C++, Rules ++and Recommendations,'' Erik Nyquist and Mats Henricson, ++Ellemtel@footnote{This document is available at ++@uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other ++places.}. ++@c N.B. This URL was still valid at 2005/8/28 (ACM). ++ ++@item linux ++@cindex Linux style ++C coding standard for Linux (the kernel). ++ ++@item python ++@cindex Python style ++C coding standard for Python extension modules@footnote{Python is a ++high level scripting language with a C/C++ foreign function interface. ++For more information, see @uref{http://www.python.org/}.}. ++ ++@item java ++@cindex Java style ++The style for editing Java code. Note that the default ++value for @code{c-default-style} installs this style when you enter ++@code{java-mode}. ++ ++@item awk ++@cindex AWK style ++The style for editing AWK code. Note that the default value for ++@code{c-default-style} installs this style when you enter ++@code{awk-mode}. ++ ++@item user ++@cindex User style ++This is a special style created by you. It consists of the factory ++defaults for all the style variables as modified by the customizations ++you do either with the Customization interface or by writing ++@code{setq}s and @code{c-set-offset}s at the top level of your ++@file{.emacs} file (@pxref{Config Basics}). The style system creates ++this style as part of its initialization and doesn't modify it ++afterwards. ++@end table ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Choosing a Style, Adding Styles, Built-in Styles, Styles ++@comment node-name, next, previous, up ++@subsection Choosing a Style ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++When you create a new buffer, its style will be set from ++@code{c-default-style}. The factory default is the style @code{gnu}, ++except in Java and AWK modes where it's @code{java} and @code{awk}. ++ ++Remember that if you set a style variable with the Customization ++interface or at the top level of your @file{.emacs} file before the ++style system is initialized (@pxref{Config Basics}), this setting will ++override the one that the style system would have given the variable. ++ ++To set a buffer's style interactively, use the command @kbd{C-c .} ++(@pxref{Other Commands}). To set it from a file's local variable ++list, @ref{File Styles}. ++ ++@defopt c-default-style ++@vindex default-style (c-) ++This variable specifies which style to install by default in new ++buffers. It takes either a style name string, or an association list ++of major mode symbols to style names: ++ ++@enumerate ++@item ++When @code{c-default-style} is a string, it must be an existing style ++name. This style is then used for all modes. ++ ++@item ++When @code{c-default-style} is an association list, the mode language ++is looked up to find a style name string. ++ ++@item ++If @code{c-default-style} is an association list where the mode ++language mode isn't found then the special symbol @samp{other} is ++looked up. If it's found then the associated style is used. ++ ++@item ++If @samp{other} is not found then the @samp{gnu} style is used. ++@end enumerate ++ ++In all cases, the style described in @code{c-default-style} is installed ++@emph{before} the language hooks are run, so you can always override ++this setting by including an explicit call to @code{c-set-style} in your ++language mode hook, or in @code{c-mode-common-hook}. ++ ++The standard value of @code{c-default-style} is @w{@code{((java-mode ++. "java") (awk-mode . "awk") (other . "gnu"))}}. ++@end defopt ++ ++@defvar c-indentation-style ++@vindex indentation-style (c-) ++This variable always contains the buffer's current style name, as a ++string. ++@end defvar ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Adding Styles, File Styles, Choosing a Style, Styles ++@comment node-name, next, previous, up ++@subsection Adding and Amending Styles ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++If none of the built-in styles is appropriate, you'll probably want to ++create a new @dfn{style definition}, possibly based on an existing ++style. To do this, put the new style's settings into a list with the ++following format - the list can then be passed as an argument to the ++function @code{c-add-style}. You can see an example of a style ++definition in @ref{Sample .emacs File}. ++ ++@cindex style definition ++@c @defvr {List} style definition ++@table @asis ++@item Structure of a Style Definition List ++([@var{base-style}] [(@var{variable} . @var{value}) @dots{}]) ++ ++Optional @var{base-style}, if present, must be a string which is the ++name of the @dfn{base style} from which this style inherits. At most ++one @var{base-style} is allowed in a style definition. If ++@var{base-style} is not specified, the style inherits from the table ++of factory default values@footnote{This table is stored internally in ++the variable c-fallback-style.} instead. All styles eventually ++inherit from this internal table. Style loops generate errors. The ++list of pre-existing styles can be seen in @ref{Built-in Styles}. ++ ++The dotted pairs (@var{variable} . @var{value}) each consist of a ++variable and the value it is to be set to when the style is later ++activated.@footnote{Note that if the variable has been given a value ++by the Customization interface or a @code{setq} at the top level of ++your @file{.emacs}, this value will override the one the style system ++tries to give it. @xref{Config Basics}.} The variable can be either a ++@ccmode{} style variable or an arbitrary Emacs variable. In the ++latter case, it is @emph{not} made buffer-local by the @ccmode{} style ++system. ++@c @end defvr ++ ++Two variables are treated specially in the dotted pair list: ++ ++@table @code ++@item c-offsets-alist ++The value is in turn a list of dotted pairs of the form ++ ++@example ++(@r{@var{syntactic-symbol}} . @r{@var{offset}}) ++@end example ++ ++as described in @ref{c-offsets-alist}. These are passed to ++@code{c-set-offset} so there is no need to set every syntactic symbol ++in your style, only those that are different from the inherited style. ++ ++@item c-special-indent-hook ++The value is added to @code{c-special-indent-hook} using ++@code{add-hook}, so any functions already on it are kept. If the value ++is a list, each element of the list is added with @code{add-hook}. ++@end table ++@end table ++ ++Styles are kept in the @code{c-style-alist} variable, but you ++should never modify this variable directly. Instead, @ccmode{} ++provides the function @code{c-add-style} for this purpose. ++ ++@defun c-add-style stylename description &optional set-p ++@findex add-style (c-) ++Add or update a style called @var{stylename}, a string. ++@var{description} is the new style definition in the form described ++above. If @var{stylename} already exists in @code{c-style-alist} then ++it is replaced by @var{description}. (Note, this replacement is ++total. The old style is @emph{not} merged into the new one.) ++Otherwise, a new style is added. ++ ++If the optional @var{set-p} is non-@code{nil} then the new style is ++applied to the current buffer as well. The use of this facility is ++deprecated and it might be removed from @ccmode{} in a future release. ++You should use @code{c-set-style} instead. ++ ++The sample @file{.emacs} file provides a concrete example of how a new ++style can be added and automatically set. @xref{Sample .emacs File}. ++@end defun ++ ++@defvar c-style-alist ++@vindex style-alist (c-) ++This is the variable that holds the definitions for the styles. It ++should not be changed directly; use @code{c-add-style} instead. ++@end defvar ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node File Styles, , Adding Styles, Styles ++@comment node-name, next, previous, up ++@subsection File Styles ++@cindex styles, file local ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex file local variables ++ ++The Emacs manual describes how you can customize certain variables on a ++per-file basis by including a @dfn{file local variable} block at the end ++of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{}, ++@emacsmantitle{}}). ++ ++So far, you've only seen a functional interface for setting styles in ++@ccmode{}, and this can't be used here. @ccmode{} fills the gap by ++providing two variables for use in a file's local variable list. ++Don't use them anywhere else! These allow you to customize the style ++on a per-file basis: ++ ++@defvar c-file-style ++@vindex file-style (c-) ++Set this variable to a style name string in the Local Variables list. ++From now on, when you visit the file, @ccmode{} will automatically set ++the file's style to this one using @code{c-set-style}. ++@end defvar ++ ++@defvar c-file-offsets ++@vindex file-offsets (c-) ++Set this variable (in the Local Variables list) to an association list ++of the same format as @code{c-offsets-alist}. From now on, when you ++visit the file, @ccmode{} will automatically institute these offsets ++using @code{c-set-offset}. ++@end defvar ++ ++Note that file style settings (i.e. @code{c-file-style}) are applied ++before file offset settings ++(i.e. @code{c-file-offsets})@footnote{Also, if either of these are set ++in a file's local variable section, all the style variable values are ++made local to that buffer, even if ++@code{c-style-variables-are-local-p} is @code{nil}. Since this ++variable is virtually always non-@code{nil} anyhow, you're unlikely to ++notice this effect.}. ++ ++If you set any variables, including style variables, by the file local ++variables mechanism, these settings take priority over all other ++settings, even those in your mode hooks (@pxref{CC Hooks}). If you ++use @code{c-file-style} or @code{c-file-offsets} and also explicitly ++set a style variable in a local variable block, the explicit setting ++will take priority. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top ++@comment node-name, next, previous, up ++@chapter Customizing Filling and Line Breaking ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Since there's a lot of normal text in comments and string literals, ++@ccmode{} provides features to edit these like in text mode. It does ++this by hooking in on the different line breaking functions and tuning ++relevant variables as necessary. ++ ++@vindex c-comment-prefix-regexp ++@vindex comment-prefix-regexp (c-) ++@cindex comment line prefix ++@vindex comment-start ++@vindex comment-end ++@vindex comment-start-skip ++@vindex paragraph-start ++@vindex paragraph-separate ++@vindex paragraph-ignore-fill-prefix ++@vindex adaptive-fill-mode ++@vindex adaptive-fill-regexp ++@vindex adaptive-fill-first-line-regexp ++To make Emacs recognize comments and treat text in them as normal ++paragraphs, @ccmode{} makes several standard ++variables@footnote{@code{comment-start}, @code{comment-end}, ++@code{comment-start-skip}, @code{paragraph-start}, ++@code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, ++@code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and ++@code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them ++according to the language syntax and the comment line prefix. ++ ++@defopt c-comment-prefix-regexp ++@vindex comment-prefix-regexp (c-) ++This style variable contains the regexp used to recognize the ++@dfn{comment line prefix}, which is the line decoration that starts ++every line in a comment. The variable is either the comment line ++prefix itself, or (more usually) an association list with different ++values for different languages. The symbol for the major mode is ++looked up in the alist to get the regexp for the language, and if it ++isn't found then the special symbol @samp{other} is looked up instead. ++ ++When a comment line gets divided by @kbd{M-j} or the like, @ccmode{} ++inserts the comment line prefix from a neighboring line at the start ++of the new line. The default value of c-comment-prefix-regexp is ++@samp{//+\\|\\**}, which matches C++ style line comments like ++ ++@example ++// blah blah ++@end example ++ ++@noindent ++with two or more slashes in front of them, and the second and ++subsequent lines of C style block comments like ++ ++@example ++@group ++/* ++ * blah blah ++ */ ++@end group ++@end example ++ ++@noindent ++with zero or more stars at the beginning of every line. If you change ++this variable, please make sure it still matches the comment starter ++(i.e. @code{//}) of line comments @emph{and} the line prefix inside ++block comments. ++ ++@findex c-setup-paragraph-variables ++@findex setup-paragraph-variables (c-) ++Also note that since @ccmode{} uses the value of ++@code{c-comment-prefix-regexp} to set up several other variables at ++mode initialization, there won't be any effect if you just change it ++inside a @ccmode{} buffer. You need to call the command ++@code{c-setup-paragraph-variables} too, to update those other ++variables. That's also the case if you modify ++@code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will ++already have set up these variables before calling the hook. ++@end defopt ++ ++In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt ++the line prefix from the other lines in the comment. ++ ++@vindex adaptive-fill-mode ++@cindex Adaptive Fill mode ++@ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU ++Emacs Manual}) to make Emacs correctly keep the line prefix when ++filling paragraphs. That also makes Emacs preserve the text ++indentation @emph{inside} the comment line prefix. E.g. in the ++following comment, both paragraphs will be filled with the left ++margins of the texts kept intact: ++ ++@example ++@group ++/* Make a balanced b-tree of the nodes in the incoming ++ * stream. But, to quote the famous words of Donald E. ++ * Knuth, ++ * ++ * Beware of bugs in the above code; I have only ++ * proved it correct, not tried it. ++ */ ++@end group ++@end example ++ ++@findex c-setup-filladapt ++@findex setup-filladapt (c-) ++@findex filladapt-mode ++@vindex filladapt-mode ++@cindex Filladapt mode ++It's also possible to use other adaptive filling packages, notably Kyle ++E. Jones' Filladapt package@footnote{It's available from ++@uref{http://www.wonderworks.com/}. As of version 2.12, it does however ++lack a feature that makes it work suboptimally when ++@code{c-comment-prefix-regexp} matches the empty string (which it does ++by default). A patch for that is available from ++@uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.}, ++@c 2005/11/22: The above is still believed to be the case. ++which handles things like bulleted lists nicely. There's a convenience ++function @code{c-setup-filladapt} that tunes the relevant variables in ++Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with ++something like this in your @file{.emacs}: ++ ++@example ++(defun my-c-mode-common-hook () ++ (c-setup-filladapt) ++ (filladapt-mode 1)) ++(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) ++@end example ++ ++@defopt c-block-comment-prefix ++@vindex block-comment-prefix (c-) ++@vindex c-comment-continuation-stars ++@vindex comment-continuation-stars (c-) ++Normally the comment line prefix inserted for a new line inside a ++comment is deduced from other lines in it. However there's one ++situation when there's no hint about what the prefix should look like, ++namely when a block comment is broken for the first time. This style ++variable@footnote{In versions before 5.26, this variable was called ++@code{c-comment-continuation-stars}. As a compatibility measure, ++@ccmode{} still uses the value on that variable if it's set.} is used ++then as the comment prefix. It defaults to @samp{* ++}@footnote{Actually, this default setting of ++@code{c-block-comment-prefix} typically gets overridden by the default ++style @code{gnu}, which sets it to blank. You can see the line ++splitting effect described here by setting a different style, ++e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment ++ ++@example ++/* Got O(n^2) here, which is a Bad Thing. */ ++@end example ++ ++@noindent ++break into ++ ++@example ++@group ++/* Got O(n^2) here, which ++ * is a Bad Thing. */ ++@end group ++@end example ++ ++Note that it won't work to adjust the indentation by putting leading ++spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the ++normal indentation engine to indent the line. Thus, the right way to ++fix the indentation is by customizing the @code{c} syntactic symbol. It ++defaults to @code{c-lineup-C-comments}, which handles the indentation of ++most common comment styles, see @ref{Line-Up Functions}. ++@end defopt ++ ++@defopt c-ignore-auto-fill ++@vindex ignore-auto-fill (c-) ++When auto fill mode is enabled, @ccmode{} can selectively ignore it ++depending on the context the line break would occur in, e.g. to never ++break a line automatically inside a string literal. This variable ++takes a list of symbols for the different contexts where auto-filling ++never should occur: ++ ++@table @code ++@item string ++Inside a string or character literal. ++@item c ++Inside a C style block comment. ++@item c++ ++Inside a C++ style line comment. ++@item cpp ++Inside a preprocessor directive. ++@item code ++Anywhere else, i.e. in normal code. ++@end table ++ ++By default, @code{c-ignore-auto-fill} is set to @code{(string cpp ++code)}, which means that when auto-fill mode is activated, ++auto-filling only occurs in comments. In literals, it's often ++desirable to have explicit control over newlines. In preprocessor ++directives, the necessary @samp{\} escape character before the newline ++is not automatically inserted, so an automatic line break would ++produce invalid code. In normal code, line breaks are normally ++dictated by some logical structure in the code rather than the last ++whitespace character, so automatic line breaks there will produce poor ++results in the current implementation. ++@end defopt ++ ++@vindex comment-multi-line ++If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,, ++@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and ++line prefix are preserved. If inside a comment and ++@code{comment-multi-line} is @code{nil}, a new comment of the same ++type is started on the next line and indented as appropriate for ++comments. ++ ++Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at ++startup. The reason is that @kbd{M-j} could otherwise produce sequences ++of single line block comments for texts that should logically be treated ++as one comment, and the rest of the paragraph handling code ++(e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to ++inconsistent behavior. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top ++@comment node-name, next, previous, up ++@chapter Customizing Auto-newlines ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@ccmode{} determines whether to insert auto-newlines in two basically ++different ways, depending on the character just typed: ++ ++@table @asis ++@item Braces and Colons ++@ccmode{} first determines the syntactic context of the brace or colon ++(@pxref{Syntactic Symbols}), then looks for a corresponding element in ++an alist. This element specifies where to put newlines - this is any ++combination of before and after the brace or colon. If no alist ++element is found, newlines are inserted both before and after a brace, ++but none are inserted around a colon. See @ref{Hanging Braces} and ++@ref{Hanging Colons}. ++ ++@item Semicolons and Commas ++The variable @code{c-hanging-semi&comma-criteria} contains a list of ++functions which determine whether to insert a newline after a newly ++typed semicolon or comma. @xref{Hanging Semicolons and Commas}. ++@end table ++ ++The names of these configuration variables contain @samp{hanging} ++because they let you @dfn{hang} the pertinent characters. A character ++which introduces a C construct is said to @dfn{hang on the right} when ++it appears at the end of a line after other code, being separated by a ++line break from the construct it introduces, like the opening brace in: ++ ++@example ++@group ++while (i < MAX) @{ ++ total += entry[i]; ++ entry [i++] = 0; ++@} ++@end group ++@end example ++ ++@noindent ++A character @dfn{hangs on the left} when it appears at the start of ++the line after the construct it closes off, like the above closing ++brace. ++ ++The next chapter, ``Clean-ups'', describes how to configure @ccmode{} ++to remove these automatically added newlines in certain specific ++circumstances. @xref{Clean-ups}. ++ ++@menu ++* Hanging Braces:: ++* Hanging Colons:: ++* Hanging Semicolons and Commas:: ++@end menu ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines ++@comment node-name, next, previous, up ++@section Hanging Braces ++@cindex hanging braces ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++To specify which kinds of braces you want auto-newlines put around, ++you set the style variable @code{c-hanging-braces-alist}. Its ++structure and semantics are described in this section. Details of how ++to set it up, and its relationship to CC Mode's style system are given ++in @ref{Style Variables}. ++ ++Say you wanted an auto-newline after (but not before) the following ++@samp{@{}: ++ ++@example ++if (foo < 17) @{ ++@end example ++ ++@noindent ++First you need to find the @dfn{syntactic context} of the brace---type ++a @key{RET} before the brace to get it on a line of its ++own@footnote{Also insert a @samp{\} at the end of the previous line if ++you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you ++something like: ++ ++@example ++((substatement-open 1061)) ++@end example ++ ++@noindent ++So here you need to put the entry @code{(substatement-open . (after))} ++into @code{c-hanging-braces-alist}. ++ ++If you don't want any auto-newlines for a particular syntactic symbol, ++put this into @code{c-hanging-braces-alist}: ++ ++@example ++(brace-entry-open) ++@end example ++ ++If some brace syntactic symbol is not in @code{c-hanging-brace-alist}, ++its entry is taken by default as @code{(before after)}---insert a ++newline both before and after the brace. In place of a ++``before/after'' list you can specify a function in this alist---this ++is useful when the auto newlines depend on the code around the brace. ++ ++@defopt c-hanging-braces-alist ++@vindex hanging-braces-alist (c-) ++ ++This variable is an association list which maps syntactic symbols to ++lists of places to insert a newline. @xref{Association ++Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the ++syntactic symbol, the associated value is either @code{nil}, a list, ++or a function. ++ ++@table @asis ++@item The Key - the syntactic symbol ++The syntactic symbols that are useful as keys in this list are ++@code{brace-list-intro}, @code{statement-cont}, ++@code{inexpr-class-open}, @code{inexpr-class-close}, and all the ++@code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols}, ++for a more detailed description of these syntactic symbols, except for ++@code{inexpr-class-open} and @code{inexpr-class-close}, which aren't ++actual syntactic symbols. Elements with any other value as a key get ++ignored. ++ ++The braces of anonymous inner classes in Java are given the special ++symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that ++they can be distinguished from the braces of normal classes@footnote{The ++braces of anonymous classes produce a combination of ++@code{inexpr-class}, and @code{class-open} or @code{class-close} in ++normal indentation analysis.}. ++ ++Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})}, ++@samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace ++lists in this regard, even though they do for normal indentation ++purposes. It's currently not possible to set automatic newlines on ++these constructs. ++ ++@item The associated value - the ``ACTION'' list or function ++The value associated with each syntactic symbol in this association ++list is called an @var{action}, which can be either a list or a ++function which returns a list. @xref{Custom Braces}, for how to use ++a function as a brace hanging @var{action}. ++ ++The list @var{action} (or the list returned by @var{action} when it's ++a function) contains some combination of the symbols @code{before} and ++@code{after}, directing @ccmode{} where to put newlines in ++relationship to the brace being inserted. Thus, if the list contains ++only the symbol @code{after}, then the brace hangs on the right side ++of the line, as in: ++ ++@example ++// here, open braces always `hang' ++void spam( int i ) @{ ++ if( i == 7 ) @{ ++ dosomething(i); ++ @} ++@} ++@end example ++ ++When the list contains both @code{after} and @code{before}, the braces ++will appear on a line by themselves, as shown by the close braces in ++the above example. The list can also be empty, in which case newlines ++are added neither before nor after the brace. ++@end table ++ ++If a syntactic symbol is missing entirely from ++@code{c-hanging-braces-alist}, it's treated in the same way as an ++@var{action} with a list containing @code{before} and @code{after}, so ++that braces by default end up on their own line. ++ ++For example, the default value of @code{c-hanging-braces-alist} is: ++ ++@example ++((brace-list-open) ++ (brace-entry-open) ++ (statement-cont) ++ (substatement-open after) ++ (block-close . c-snug-do-while) ++ (extern-lang-open after) ++ (namespace-open after) ++ (module-open after) ++ (composition-open after) ++ (inexpr-class-open after) ++ (inexpr-class-close before)) ++@end example ++ ++@noindent which says that @code{brace-list-open}, ++@code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists ++inside statements, such as initializers for static array variables ++inside functions in C, are recognized as @code{statement-cont}. All ++normal substatement blocks are recognized with other symbols.} braces ++should both hang on the right side and allow subsequent text to follow ++on the same line as the brace. Also, @code{substatement-open}, ++@code{extern-lang-open}, and @code{inexpr-class-open} braces should hang ++on the right side, but subsequent text should follow on the next line. ++The opposite holds for @code{inexpr-class-close} braces; they won't ++hang, but the following text continues on the same line. Here, in the ++@code{block-close} entry, you also see an example of using a function as ++an @var{action}. In all other cases, braces are put on a line by ++themselves. ++@end defopt ++ ++@menu ++* Custom Braces:: ++@end menu ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Custom Braces, , Hanging Braces, Hanging Braces ++@comment node-name, next, previous, up ++@subsection Custom Brace Hanging ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@vindex c-hanging-braces-alist ++@vindex hanging-braces-alist (c-) ++@cindex action functions ++Syntactic symbols aren't the only place where you can customize ++@ccmode{} with the lisp equivalent of callback functions. Remember ++that @var{action}s are usually a list containing some combination of ++the symbols @code{before} and @code{after} (@pxref{Hanging Braces}). ++For more flexibility, you can instead specify brace ``hanginess'' by ++giving a syntactic symbol an @dfn{action function} in ++@code{c-hanging-braces-alist}; this function determines the ++``hanginess'' of a brace, usually by looking at the code near it. ++ ++@cindex customization, brace hanging ++An action function is called with two arguments: the syntactic symbol ++for the brace (e.g. @code{substatement-open}), and the buffer position ++where the brace has been inserted. Point is undefined on entry to an ++action function, but the function must preserve it (e.g. by using ++@code{save-excursion}). The return value should be a list containing ++some combination of @code{before} and @code{after}, including neither ++of them (i.e. @code{nil}). ++ ++@defvar c-syntactic-context ++@vindex syntactic-context (c-) ++During the call to the indentation or brace hanging @var{action} ++function, this variable is bound to the full syntactic analysis list. ++This might be, for example, @samp{((block-close 73))}. Don't ever ++give @code{c-syntactic-context} a value yourself---this would disrupt ++the proper functioning of @ccmode{}. ++ ++This variable is also bound in three other circumstances: ++(i)@w{ }when calling a c-hanging-semi&comma-criteria function ++(@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a ++line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a ++c-special-indent-hook function (@pxref{Other Indentation}). ++@end defvar ++ ++As an example, @ccmode{} itself uses this feature to dynamically ++determine the hanginess of braces which close ``do-while'' ++constructs: ++ ++@example ++void do_list( int count, char** atleast_one_string ) ++@{ ++ int i=0; ++ do @{ ++ handle_string( atleast_one_string[i] ); ++ i++; ++ @} while( i < count ); ++@} ++@end example ++ ++@ccmode{} assigns the @code{block-close} syntactic symbol to the ++brace that closes the @code{do} construct, and normally we'd like the ++line that follows a @code{block-close} brace to begin on a separate ++line. However, with ``do-while'' constructs, we want the ++@code{while} clause to follow the closing brace. To do this, we ++associate the @code{block-close} symbol with the @var{action} function ++@code{c-snug-do-while}: ++ ++@example ++(defun c-snug-do-while (syntax pos) ++ "Dynamically calculate brace hanginess for do-while statements." ++ (save-excursion ++ (let (langelem) ++ (if (and (eq syntax 'block-close) ++ (setq langelem (assq 'block-close c-syntactic-context)) ++ (progn (goto-char (cdr langelem)) ++ (if (= (following-char) ?@{) ++ (forward-sexp -1)) ++ (looking-at "\\[^_]"))) ++ '(before) ++ '(before after))))) ++@end example ++ ++@findex c-snug-do-while ++@findex snug-do-while (c-) ++This function simply looks to see if the brace closes a ``do-while'' ++clause and if so, returns the list @samp{(before)} indicating ++that a newline should be inserted before the brace, but not after it. ++In all other cases, it returns the list @samp{(before after)} so ++that the brace appears on a line by itself. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines ++@comment node-name, next, previous, up ++@section Hanging Colons ++@cindex hanging colons ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex customization, colon hanging ++@vindex c-hanging-colons-alist ++@vindex hanging-colons-alist (c-) ++ ++Using a mechanism similar to brace hanging (@pxref{Hanging Braces}), ++colons can also be made to hang using the style variable ++@code{c-hanging-colons-alist} - When a colon is typed, @ccmode ++determines its syntactic context, looks this up in the alist ++@code{c-changing-colons-alist} and inserts up to two newlines ++accordingly. Here, however, If @ccmode fails to find an entry for a ++syntactic symbol in the alist, no newlines are inserted around the ++newly typed colon. ++ ++@defopt c-hanging-colons-alist ++@vindex hanging-colons-alist (c-) ++ ++@table @asis ++@item The Key - the syntactic symbol ++The syntactic symbols appropriate as keys in this association list ++are: @code{case-label}, @code{label}, @code{access-label}, ++@code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic ++Symbols}. Elements with any other value as a key get ignored. ++ ++@item The associate value - the ``ACTION'' list ++The @var{action} here is simply a list containing a combination of the ++symbols @code{before} and @code{after}. Unlike in ++@code{c-hanging-braces-alist}, functions as @var{actions} are not ++supported - there doesn't seem to be any need for them. ++@end table ++@end defopt ++ ++In C++, double-colons are used as a scope operator but because these ++colons always appear right next to each other, newlines before and after ++them are controlled by a different mechanism, called @dfn{clean-ups} in ++@ccmode{}. @xref{Clean-ups}, for details. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines ++@comment node-name, next, previous, up ++@section Hanging Semicolons and Commas ++@cindex hanging semicolons ++@cindex hanging commas ++@cindex customization, semicolon newlines ++@cindex customization, comma newlines ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@defopt c-hanging-semi&comma-criteria ++@vindex hanging-semi&comma-criteria (c-) ++This style variable takes a list of functions; these get called when ++you type a semicolon or comma. The functions are called in order ++without arguments. When these functions are entered, point is just ++after the newly inserted @samp{;} or @samp{,} and they must preserve ++point (e.g., by using @code{save-excursion}). During the call, the ++variable @code{c-syntactic-context} is bound to the syntactic context ++of the current line@footnote{This was first introduced in @ccmode{} ++5.31.} @pxref{Custom Braces}. These functions don't insert newlines ++themselves, rather they direct @ccmode{} whether or not to do so. ++They should return one of the following values: ++ ++@table @code ++@item t ++A newline is to be inserted after the @samp{;} or @samp{,}, and no ++more functions from the list are to be called. ++@item stop ++No more functions from the list are to be called, and no newline is to ++be inserted. ++@item nil ++No determination has been made, and the next function in the list is ++to be called. ++@end table ++ ++Note that auto-newlines are never inserted @emph{before} a semicolon ++or comma. If every function in the list is called without a ++determination being made, then no newline is added. ++ ++In AWK mode, this variable is set by default to @code{nil}. In the ++other modes, the default value is a list containing a single function, ++@code{c-semi&comma-inside-parenlist}. This inserts newlines after all ++semicolons, apart from those separating @code{for}-clause statements. ++@end defopt ++ ++@defun c-semi&comma-no-newlines-before-nonblanks ++@findex semi&comma-no-newlines-before-nonblanks (c-) ++This is an example of a criteria function, provided by @ccmode{}. It ++prevents newlines from being inserted after semicolons when there is a ++non-blank following line. Otherwise, it makes no determination. To ++use, add this function to the front of the ++@code{c-hanging-semi&comma-criteria} list. ++ ++@example ++(defun c-semi&comma-no-newlines-before-nonblanks () ++ (save-excursion ++ (if (and (eq last-command-char ?\;) ++ (zerop (forward-line 1)) ++ (not (looking-at "^[ \t]*$"))) ++ 'stop ++ nil))) ++@end example ++@end defun ++ ++@defun c-semi&comma-inside-parenlist ++@findex semi&comma-inside-parenlist (c-) ++@defunx c-semi&comma-no-newlines-for-oneline-inliners ++@findex semi&comma-no-newlines-for-oneline-inliners (c-) ++The function @code{c-semi&comma-inside-parenlist} is what prevents ++newlines from being inserted inside the parenthesis list of @code{for} ++statements. In addition to ++@code{c-semi&comma-no-newlines-before-nonblanks} described above, ++@ccmode{} also comes with the criteria function ++@code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses ++newlines after semicolons inside one-line inline method definitions ++(e.g. in C++ or Java). ++@end defun ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top ++@comment node-name, next, previous, up ++@chapter Clean-ups ++@cindex clean-ups ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add) ++whitespace in specific circumstances and are complementary to colon ++and brace hanging. You enable a clean-up by adding its symbol into ++@code{c-cleanup-list}, e.g. like this: ++ ++@example ++(add-to-list 'c-cleanup-list 'space-before-funcall) ++@end example ++ ++On the surface, it would seem that clean-ups overlap the functionality ++provided by the @code{c-hanging-*-alist} variables. Clean-ups, ++however, are used to adjust code ``after-the-fact'', i.e. to adjust ++the whitespace in constructs later than when they were typed. ++ ++Most of the clean-ups remove automatically inserted newlines, and are ++only active when auto-newline minor mode is turned on. Others will ++work all the time. Note that clean-ups are only performed when there ++is nothing but whitespace appearing between the individual components ++of the construct, and (apart from @code{comment-close-slash}) when the ++construct does not occur within a literal (@pxref{Auto-newlines}). ++ ++@defopt c-cleanup-list ++@vindex cleanup-list (c-) ++@cindex literal ++ ++You configure @ccmode{}'s clean-ups by setting the style variable ++@code{c-cleanup-list}, which is a list of clean-up symbols. By ++default, @ccmode{} cleans up only the @code{scope-operator} construct, ++which is necessary for proper C++ support. ++@end defopt ++ ++These are the clean-ups that are only active when electric and ++auto-newline minor modes are enabled: ++ ++@c TBD: Would like to use some sort of @deffoo here; @table indents a ++@c bit too much in dvi output. ++@table @code ++@item brace-else-brace ++Clean up @samp{@} else @{} constructs by placing the entire construct on ++a single line. Clean up occurs when the open brace after the ++@samp{else} is typed. So for example, this: ++ ++@example ++@group ++void spam(int i) ++@{ ++ if( i==7 ) @{ ++ dosomething(); ++ @} ++ else ++ @{ ++@end group ++@end example ++ ++@noindent ++appears like this after the last open brace is typed: ++ ++@example ++@group ++void spam(int i) ++@{ ++ if( i==7 ) @{ ++ dosomething(); ++ @} else @{ ++@end group ++@end example ++ ++@item brace-elseif-brace ++Similar to the @code{brace-else-brace} clean-up, but this cleans up ++@samp{@} else if (...) @{} constructs. For example: ++ ++@example ++@group ++void spam(int i) ++@{ ++ if( i==7 ) @{ ++ dosomething(); ++ @} ++ else if( i==3 ) ++ @{ ++@end group ++@end example ++ ++@noindent ++appears like this after the last open parenthesis is typed: ++ ++@example ++@group ++void spam(int i) ++@{ ++ if( i==7 ) @{ ++ dosomething(); ++ @} else if( ++@end group ++@end example ++ ++@noindent ++and like this after the last open brace is typed: ++ ++@example ++@group ++void spam(int i) ++@{ ++ if( i==7 ) @{ ++ dosomething(); ++ @} else if( i==3 ) @{ ++@end group ++@end example ++ ++@item brace-catch-brace ++Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch ++(...) @{} in C++ and Java mode. ++ ++@item empty-defun-braces ++Clean up braces following a top-level function or class definition that ++contains no body. Clean up occurs when the closing brace is typed. ++Thus the following: ++ ++@example ++@group ++class Spam ++@{ ++@} ++@end group ++@end example ++ ++@noindent ++is transformed into this when the close brace is typed: ++ ++@example ++@group ++class Spam ++@{@} ++@end group ++@end example ++ ++@item defun-close-semi ++Clean up the terminating semicolon on top-level function or class ++definitions when they follow a close brace. Clean up occurs when the ++semicolon is typed. So for example, the following: ++ ++@example ++@group ++class Spam ++@{ ++... ++@} ++; ++@end group ++@end example ++ ++@noindent ++is transformed into this when the semicolon is typed: ++ ++@example ++@group ++class Spam ++@{ ++... ++@}; ++@end group ++@end example ++ ++@item list-close-comma ++Clean up commas following braces in array and aggregate initializers. ++Clean up occurs when the comma is typed. The space before the comma ++is zapped just like the space before the semicolon in ++@code{defun-close-semi}. ++ ++@item scope-operator ++Clean up double colons which might designate a C++ scope operator split ++across multiple lines@footnote{Certain C++ constructs introduce ++ambiguous situations, so @code{scope-operator} clean-ups might not ++always be correct. This usually only occurs when scoped identifiers ++appear in switch label tags.}. Clean up occurs when the second colon is ++typed. You will always want @code{scope-operator} in the ++@code{c-cleanup-list} when you are editing C++ code. ++ ++@item one-liner-defun ++Clean up a single line of code enclosed by defun braces by removing ++the whitespace before and after the code. The clean-up happens when ++the closing brace is typed. If the variable ++@code{c-max-one-liner-length} is set, the cleanup is only done if the ++resulting line would be no longer than the value of that variable. ++ ++For example, consider this AWK code: ++ ++@example ++@group ++BEGIN @{ ++ FS = "\t" # use as a field separator ++@} ++@end group ++@end example ++ ++@noindent ++It gets compacted to the following when the closing brace is typed: ++ ++@example ++@group ++BEGIN @{FS = "\t"@} # use as a field separator ++@end group ++@end example ++ ++@defopt c-max-one-liner-length ++@vindex max-one-liner-length (c-) ++The maximum length of the resulting line for which the clean-up ++@code{one-liner-defun} will be triggered. This length is that of the entire ++line, including any leading whitespace and any trailing comment. Its ++default value is 80. If the value is zero or @code{nil}, no limit ++applies. ++@end defopt ++@end table ++ ++The following clean-ups are always active when they occur on ++@code{c-cleanup-list}, regardless of whether Electric minor mode or ++Auto-newline minor mode are enabled: ++ ++@table @code ++@item space-before-funcall ++Insert a space between the function name and the opening parenthesis ++of a function call. This produces function calls in the style ++mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT, ++SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening ++parenthesis is typed. This clean-up should never be active in AWK ++Mode, since such a space is syntactically invalid for user defined ++functions. ++ ++@item compact-empty-funcall ++Clean up any space between the function name and the opening parenthesis ++of a function call that has no arguments. This is typically used ++together with @code{space-before-funcall} if you prefer the GNU function ++call style for functions with arguments but think it looks ugly when ++it's only an empty parenthesis pair. I.e. you will get @samp{signal ++(SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the ++closing parenthesis is typed. ++ ++@item comment-close-slash ++When inside a block comment, terminate the comment when you type a slash ++at the beginning of a line (i.e. immediately after the comment prefix). ++This clean-up removes whitespace preceding the slash and if needed, ++inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this ++situation if you just want a literal @samp{/} inserted. ++@end table ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top ++@comment node-name, next, previous, up ++@chapter Indentation Engine Basics ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++This chapter will briefly cover how @ccmode{} indents lines of code. ++It is helpful to understand the indentation model being used so that ++you will know how to customize @ccmode{} for your personal coding ++style. All the details are in @ref{Customizing Indentation}. ++ ++@ccmode{} has an indentation engine that provides a flexible and ++general mechanism for customizing indentation. When @ccmode{} indents ++a line of code, it separates its calculations into two steps: ++ ++@enumerate ++@item ++@cindex syntactic symbol ++@cindex anchor position ++It analyzes the line to determine its @dfn{syntactic symbol(s)} (the ++kind of language construct it's looking at) and its @dfn{anchor ++position} (the position earlier in the file that @ccmode{} will indent ++the line relative to). The anchor position might be the location of ++an opening brace in the previous line, for example. @xref{Syntactic ++Analysis}. ++@item ++@cindex offsets ++@cindex indentation offset specifications ++It looks up the syntactic symbol(s) in the configuration to get the ++corresponding @dfn{offset(s)}. The symbol @code{+}, which means ++``indent this line one more level'' is a typical offset. @ccmode{} ++then applies these offset(s) to the anchor position, giving the ++indentation for the line. The different sorts of offsets are ++described in @ref{c-offsets-alist}. ++@end enumerate ++ ++In exceptional circumstances, the syntax directed indentation ++described here may be a nuisance rather than a help. You can disable ++it by setting @code{c-syntactic-indentation} to @code{nil}. (To set ++the variable interactively, @ref{Minor Modes}). ++ ++@defopt c-syntactic-indentation ++@vindex syntactic-indentation (c-) ++When this is non-@code{nil} (which it is by default), the indentation ++of code is done according to its syntactic structure. When it's ++@code{nil}, every line is just indented to the same level as the ++previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the ++indentation in steps of @code{c-basic-offset}. The current style ++(@pxref{Config Basics}) then has no effect on indentation, nor do any ++of the variables associated with indentation, not even ++@code{c-special-indent-hook}. ++@end defopt ++ ++@menu ++* Syntactic Analysis:: ++* Syntactic Symbols:: ++* Indentation Calculation:: ++@end menu ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics ++@comment node-name, next, previous, up ++@section Syntactic Analysis ++@cindex syntactic analysis ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex syntactic element ++@cindex syntactic context ++The first thing @ccmode{} does when indenting a line of code, is to ++analyze the line, determining the @dfn{syntactic context} of the ++(first) construct on that line. It's a list of @dfn{syntactic ++elements}, where each syntactic element in turn is a list@footnote{In ++@ccmode 5.28 and earlier, a syntactic element was a dotted pair; the ++cons was the syntactic symbol and the cdr was the anchor position. ++For compatibility's sake, the parameter passed to a line-up function ++still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a ++brief and typical example: ++ ++@example ++((defun-block-intro 1959)) ++@end example ++ ++@cindex syntactic symbol ++@noindent ++The first thing inside each syntactic element is always a ++@dfn{syntactic symbol}. It describes the kind of construct that was ++recognized, e.g. @code{statement}, @code{substatement}, ++@code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, ++for a complete list of currently recognized syntactic symbols and ++their semantics. The remaining entries are various data associated ++with the recognized construct - there might be zero or more. ++ ++@cindex anchor position ++Conceptually, a line of code is always indented relative to some ++position higher up in the buffer (typically the indentation of the ++previous line). That position is the @dfn{anchor position} in the ++syntactic element. If there is an entry after the syntactic symbol in ++the syntactic element list then it's either nil or that anchor position. ++ ++Here is an example. Suppose we had the following code as the only thing ++in a C++ buffer @footnote{The line numbers in this and future examples ++don't actually appear in the buffer, of course!}: ++ ++@example ++ 1: void swap( int& a, int& b ) ++ 2: @{ ++ 3: int tmp = a; ++ 4: a = b; ++ 5: b = tmp; ++ 6: @} ++@end example ++ ++@noindent ++We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to ++report what the syntactic analysis is for the current line: ++ ++@table @asis ++@item @kbd{C-c C-s} (@code{c-show-syntactic-information}) ++@kindex C-c C-s ++@findex c-show-syntactic-information ++@findex show-syntactic-information (c-) ++This command calculates the syntactic analysis of the current line and ++displays it in the minibuffer. The command also highlights the anchor ++position(s). ++@end table ++ ++ Running this command on line 4 of this example, we'd see in the echo ++area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the ++analysis is inserted into the buffer as a comment on the current ++line.}: ++ ++@example ++((statement 35)) ++@end example ++ ++@noindent ++and the @samp{i} of @code{int} on line 3 would be highlighted. This ++tells us that the line is a statement and it is indented relative to ++buffer position 35, the highlighted position. If you were to move ++point to line 3 and hit @kbd{C-c C-s}, you would see: ++ ++@example ++((defun-block-intro 29)) ++@end example ++ ++@noindent ++This indicates that the @samp{int} line is the first statement in a top ++level function block, and is indented relative to buffer position 29, ++which is the brace just after the function header. ++ ++Here's another example: ++ ++@example ++ 1: int add( int val, int incr, int doit ) ++ 2: @{ ++ 3: if( doit ) ++ 4: @{ ++ 5: return( val + incr ); ++ 6: @} ++ 7: return( val ); ++ 8: @} ++@end example ++ ++@noindent ++Hitting @kbd{C-c C-s} on line 4 gives us: ++ ++@example ++((substatement-open 46)) ++@end example ++ ++@cindex substatement ++@cindex substatement block ++@noindent ++which tells us that this is a brace that @emph{opens} a substatement ++block. @footnote{A @dfn{substatement} is the line after a ++conditional statement, such as @code{if}, @code{else}, @code{while}, ++@code{do}, @code{switch}, etc. A @dfn{substatement ++block} is a brace block following one of these conditional statements.} ++ ++@cindex comment-only line ++Syntactic contexts can contain more than one element, and syntactic ++elements need not have anchor positions. The most common example of ++this is a @dfn{comment-only line}: ++ ++@example ++ 1: void draw_list( List& drawables ) ++ 2: @{ ++ 3: // call the virtual draw() method on each element in list ++ 4: for( int i=0; i < drawables.count(), ++i ) ++ 5: @{ ++ 6: drawables[i].draw(); ++ 7: @} ++ 8: @} ++@end example ++ ++@noindent ++Hitting @kbd{C-c C-s} on line 3 of this example gives: ++ ++@example ++((comment-intro) (defun-block-intro 46)) ++@end example ++ ++@noindent ++and you can see that the syntactic context contains two syntactic ++elements. Notice that the first element, @samp{(comment-intro)}, has no ++anchor position. ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics ++@comment node-name, next, previous, up ++@section Syntactic Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex syntactic symbols, brief list ++@vindex c-offsets-alist ++@vindex offsets-alist (c-) ++This section is a complete list of the syntactic symbols which appear ++in the @code{c-offsets-alist} style variable, along with brief ++descriptions. The previous section (@pxref{Syntactic Analysis}) ++states what syntactic symbols are and how the indentation engine uses ++them. ++ ++More detailed descriptions of these symbols, together with snippets of ++source code to which they apply, appear in the examples in the ++subsections below. Note that, in the interests of brevity, the anchor ++position associated with most syntactic symbols is @emph{not} ++specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent ++line---this highlights the anchor position. ++ ++@ssindex -open symbols ++@ssindex -close symbols ++@ssindex -block-intro symbols ++The syntactic symbols which indicate brace constructs follow a general ++naming convention. When a line begins with an open or close brace, ++its syntactic symbol will contain the suffix @code{-open} or ++@code{-close} respectively. The first line within the brace block ++construct will contain the suffix @code{-block-intro}. ++ ++@ssindex -intro symbols ++@ssindex -cont symbols ++In constructs which can span several lines, a distinction is usually ++made between the first line that introduces the construct and the ++lines that continue it. The syntactic symbols that indicate these ++lines will contain the suffixes @code{-intro} or @code{-cont} ++respectively. ++ ++The best way to understand how all this works is by looking at some ++examples. Remember that you can see the syntax of any source code ++line by using @kbd{C-c C-s}. ++ ++@table @code ++@item string ++Inside a multiline string. @ref{Literal Symbols}. ++@item c ++Inside a multiline C style block comment. @ref{Literal Symbols}. ++@item defun-open ++Brace that opens a top-level function definition. @ref{Function ++Symbols}. ++@item defun-close ++Brace that closes a top-level function definition. @ref{Function ++Symbols}. ++@item defun-block-intro ++The first line in a top-level defun. @ref{Function Symbols}. ++@item class-open ++Brace that opens a class definition. @ref{Class Symbols}. ++@item class-close ++Brace that closes a class definition. @ref{Class Symbols}. ++@item inline-open ++Brace that opens an in-class inline method. @ref{Class Symbols}. ++@item inline-close ++Brace that closes an in-class inline method. @ref{Class Symbols}. ++@item func-decl-cont ++The region between a function definition's argument list and the ++function opening brace (excluding K&R argument declarations). In C, ++you cannot put anything but whitespace and comments in this region, ++however in C++ and Java, @code{throws} declarations and other things ++can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not ++@c go somewhere better?} ++@item knr-argdecl-intro ++First line of a K&R C argument declaration. @ref{K&R Symbols}. ++@item knr-argdecl ++Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}. ++@item topmost-intro ++The first line in a ``topmost'' definition. @ref{Function Symbols}. ++@item topmost-intro-cont ++Topmost definition continuation lines. This is only used in the parts ++that aren't covered by other symbols such as @code{func-decl-cont} and ++@code{knr-argdecl}. @ref{Function Symbols}. ++@item member-init-intro ++First line in a member initialization list. @ref{Class Symbols}. ++@item member-init-cont ++Subsequent member initialization list lines. @ref{Class Symbols}. ++@item inher-intro ++First line of a multiple inheritance list. @ref{Class Symbols}. ++@item inher-cont ++Subsequent multiple inheritance lines. @ref{Class Symbols}. ++@item block-open ++Statement block open brace. @ref{Literal Symbols}. ++@item block-close ++Statement block close brace. @ref{Conditional Construct Symbols}. ++@item brace-list-open ++Open brace of an enum or static array list. @ref{Brace List Symbols}. ++@item brace-list-close ++Close brace of an enum or static array list. @ref{Brace List Symbols}. ++@item brace-list-intro ++First line in an enum or static array list. @ref{Brace List Symbols}. ++@item brace-list-entry ++Subsequent lines in an enum or static array list. @ref{Brace List ++Symbols}. ++@item brace-entry-open ++Subsequent lines in an enum or static array list where the line begins ++with an open brace. @ref{Brace List Symbols}. ++@item statement ++A statement. @ref{Function Symbols}. ++@item statement-cont ++A continuation of a statement. @ref{Function Symbols}. ++@item statement-block-intro ++The first line in a new statement block. @ref{Conditional Construct ++Symbols}. ++@item statement-case-intro ++The first line in a case block. @ref{Switch Statement Symbols}. ++@item statement-case-open ++The first line in a case block that starts with a brace. @ref{Switch ++Statement Symbols}. ++@item substatement ++The first line after a conditional or loop construct. ++@ref{Conditional Construct Symbols}. ++@item substatement-open ++The brace that opens a substatement block. @ref{Conditional Construct ++Symbols}. ++@item substatement-label ++The first line after a conditional or loop construct if it's a label. ++@ref{Conditional Construct Symbols}. ++@item case-label ++A label in a @code{switch} block. @ref{Switch Statement Symbols}. ++@item access-label ++C++ access control label. @ref{Class Symbols}. ++@item label ++Any other label. @ref{Literal Symbols}. ++@item do-while-closure ++The @code{while} line that ends a @code{do}-@code{while} construct. ++@ref{Conditional Construct Symbols}. ++@item else-clause ++The @code{else} line of an @code{if}-@code{else} construct. ++@ref{Conditional Construct Symbols}. ++@item catch-clause ++The @code{catch} or @code{finally} (in Java) line of a ++@code{try}-@code{catch} construct. @ref{Conditional Construct ++Symbols}. ++@item comment-intro ++A line containing only a comment introduction. @ref{Literal Symbols}. ++@item arglist-intro ++The first line in an argument list. @ref{Paren List Symbols}. ++@item arglist-cont ++Subsequent argument list lines when no arguments follow on the same ++line as the arglist opening paren. @ref{Paren List Symbols}. ++@item arglist-cont-nonempty ++Subsequent argument list lines when at least one argument follows on ++the same line as the arglist opening paren. @ref{Paren List Symbols}. ++@item arglist-close ++The solo close paren of an argument list. @ref{Paren List Symbols}. ++@item stream-op ++Lines continuing a stream operator (C++ only). @ref{Literal ++Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?} ++@item inclass ++The line is nested inside a class definition. @ref{Class Symbols}. ++@item cpp-macro ++The start of a preprocessor macro definition. @ref{Literal Symbols}. ++@item cpp-define-intro ++The first line inside a multiline preprocessor macro if ++@code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro ++Symbols}. ++@item cpp-macro-cont ++All lines inside multiline preprocessor macros if ++@code{c-syntactic-indentation-in-macros} is @code{nil}. ++@ref{Multiline Macro Symbols}. ++@item friend ++A C++ friend declaration. @ref{Class Symbols}. ++@item objc-method-intro ++The first line of an Objective-C method definition. @ref{Objective-C ++Method Symbols}. ++@item objc-method-args-cont ++Lines continuing an Objective-C method definition. @ref{Objective-C ++Method Symbols}. ++@item objc-method-call-cont ++Lines continuing an Objective-C method call. @ref{Objective-C Method ++Symbols}. ++@item extern-lang-open ++Brace that opens an @code{extern} block (e.g. @code{extern "C" ++@{...@}}). @ref{External Scope Symbols}. ++@item extern-lang-close ++Brace that closes an @code{extern} block. @ref{External Scope ++Symbols}. ++@item inextern-lang ++Analogous to @code{inclass} syntactic symbol, but used inside ++@code{extern} blocks. @ref{External Scope Symbols}. ++@item namespace-open ++@itemx namespace-close ++@itemx innamespace ++These are analogous to the three @code{extern-lang} symbols above, but ++are returned for C++ namespace blocks. @ref{External Scope Symbols}. ++@item module-open ++@itemx module-close ++@itemx inmodule ++Analogous to the above, but for CORBA IDL @code{module} blocks. ++@ref{External Scope Symbols}. ++@item composition-open ++@itemx composition-close ++@itemx incomposition ++Analogous to the above, but for CORBA CIDL @code{composition} blocks. ++@ref{External Scope Symbols}. ++@item template-args-cont ++C++ template argument list continuations. @ref{Class Symbols}. ++@item inlambda ++Analogous to @code{inclass} syntactic symbol, but used inside lambda ++(i.e. anonymous) functions. Only used in Pike mode. @ref{Statement ++Block Symbols}. ++@item lambda-intro-cont ++Lines continuing the header of a lambda function, i.e. between the ++@code{lambda} keyword and the function body. Only used in Pike mode. ++@ref{Statement Block Symbols}. ++@item inexpr-statement ++A statement block inside an expression. The gcc C and C++ extension ++for this is recognized. It's also used for the special functions that ++take a statement block as an argument in Pike. @ref{Statement Block ++Symbols}. ++@item inexpr-class ++A class definition inside an expression. This is used for anonymous ++classes in Java. It's also used for anonymous array initializers in ++Java. @ref{Anonymous Class Symbol}. ++@end table ++ ++@menu ++* Function Symbols:: ++* Class Symbols:: ++* Conditional Construct Symbols:: ++* Switch Statement Symbols:: ++* Brace List Symbols:: ++* External Scope Symbols:: ++* Paren List Symbols:: ++* Literal Symbols:: ++* Multiline Macro Symbols:: ++* Objective-C Method Symbols:: ++* Anonymous Class Symbol:: ++* Statement Block Symbols:: ++* K&R Symbols:: ++@end menu ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Function Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++This example shows a typical function declaration. ++ ++@example ++ 1: void ++ 2: swap( int& a, int& b ) ++ 3: @{ ++ 4: int tmp = a; ++ 5: a = b; ++ 6: b = tmp; ++ 7: int ignored = ++ 8: a + b; ++ 9: @} ++@end example ++ ++@ssindex topmost-intro ++@ssindex topmost-intro-cont ++@ssindex defun-open ++@ssindex defun-close ++@ssindex defun-block-intro ++Line 1 shows a @code{topmost-intro} since it is the first line that ++introduces a top-level construct. Line 2 is a continuation of the ++top-level construct introduction so it has the syntax ++@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is ++the brace that opens a top-level function definition. Line 9 is the ++corresponding ++@code{defun-close} since it contains the brace that closes the top-level ++function definition. Line 4 is a @code{defun-block-intro}, i.e. it is ++the first line of a brace-block, enclosed in a ++top-level function definition. ++ ++@ssindex statement ++@ssindex statement-cont ++Lines 5, 6, and 7 are all given @code{statement} syntax since there ++isn't much special about them. Note however that line 8 is given ++@code{statement-cont} syntax since it continues the statement begun ++on the previous line. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Class related Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Here's an example which illustrates some C++ class syntactic symbols: ++ ++@example ++ 1: class Bass ++ 2: : public Guitar, ++ 3: public Amplifiable ++ 4: @{ ++ 5: public: ++ 6: Bass() ++ 7: : eString( new BassString( 0.105 )), ++ 8: aString( new BassString( 0.085 )), ++ 9: dString( new BassString( 0.065 )), ++10: gString( new BassString( 0.045 )) ++11: @{ ++12: eString.tune( 'E' ); ++13: aString.tune( 'A' ); ++14: dString.tune( 'D' ); ++15: gString.tune( 'G' ); ++16: @} ++17: friend class Luthier; ++18: @}; ++@end example ++ ++@ssindex class-open ++@ssindex class-close ++As in the previous example, line 1 has the @code{topmost-intro} syntax. ++Here however, the brace that opens a C++ class definition on line 4 is ++assigned the @code{class-open} syntax. Note that in C++, classes, ++structs, and unions are essentially equivalent syntactically (and are ++very similar semantically), so replacing the @code{class} keyword in the ++example above with @code{struct} or @code{union} would still result in a ++syntax of @code{class-open} for line 4 @footnote{This is the case even ++for C and Objective-C. For consistency, structs in all supported ++languages are syntactically equivalent to classes. Note however that ++the keyword @code{class} is meaningless in C and Objective-C.}. ++Similarly, line 18 is assigned @code{class-close} syntax. ++ ++@ssindex inher-intro ++@ssindex inher-cont ++Line 2 introduces the inheritance list for the class so it is assigned ++the @code{inher-intro} syntax, and line 3, which continues the ++inheritance list is given @code{inher-cont} syntax. ++ ++@ssindex access-label ++@ssindex inclass ++Hitting @kbd{C-c C-s} on line 5 shows the following analysis: ++ ++@example ++((inclass 58) (access-label 58)) ++@end example ++ ++@noindent ++The primary syntactic symbol for this line is @code{access-label} as ++this a label keyword that specifies access protection in C++. However, ++because this line is also a top-level construct inside a class ++definition, the analysis actually shows two syntactic symbols. The ++other syntactic symbol assigned to this line is @code{inclass}. ++Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} ++syntax: ++ ++@example ++((inclass 58) (topmost-intro 60)) ++@end example ++ ++@ssindex member-init-intro ++@ssindex member-init-cont ++Line 7 introduces a C++ member initialization list and as such is given ++@code{member-init-intro} syntax. Note that in this case it is ++@emph{not} assigned @code{inclass} since this is not considered a ++top-level construct. Lines 8 through 10 are all assigned ++@code{member-init-cont} since they continue the member initialization ++list started on line 7. ++ ++@cindex in-class inline methods ++@ssindex inline-open ++@ssindex inline-close ++Line 11's analysis is a bit more complicated: ++ ++@example ++((inclass 58) (inline-open)) ++@end example ++ ++This line is assigned a syntax of both @code{inline-open} and ++@code{inclass} because it opens an @dfn{in-class} C++ inline method ++definition. This is distinct from, but related to, the C++ notion of an ++inline function in that its definition occurs inside an enclosing class ++definition, which in C++ implies that the function should be inlined. ++However, if the definition of the @code{Bass} constructor appeared ++outside the class definition, the construct would be given the ++@code{defun-open} syntax, even if the keyword @code{inline} appeared ++before the method name, as in: ++ ++@example ++ 1: class Bass ++ 2: : public Guitar, ++ 3: public Amplifiable ++ 4: @{ ++ 5: public: ++ 6: Bass(); ++ 7: @}; ++ 8: ++ 9: inline ++10: Bass::Bass() ++11: : eString( new BassString( 0.105 )), ++12: aString( new BassString( 0.085 )), ++13: dString( new BassString( 0.065 )), ++14: gString( new BassString( 0.045 )) ++15: @{ ++16: eString.tune( 'E' ); ++17: aString.tune( 'A' ); ++18: dString.tune( 'D' ); ++19: gString.tune( 'G' ); ++20: @} ++@end example ++ ++@ssindex friend ++Returning to the previous example, line 16 is given @code{inline-close} ++syntax, while line 12 is given @code{defun-block-open} syntax, and lines ++13 through 15 are all given @code{statement} syntax. Line 17 is ++interesting in that its syntactic analysis list contains three ++elements: ++ ++@example ++((inclass 58) (topmost-intro 380) (friend)) ++@end example ++ ++The @code{friend} and @code{inline-open} syntactic symbols are ++modifiers that do not have anchor positions. ++ ++@ssindex template-args-cont ++Template definitions introduce yet another syntactic symbol: ++ ++@example ++ 1: ThingManager framework_callbacks; ++@end example ++ ++Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 ++are both analyzed as @code{template-args-cont} lines. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Conditional Construct Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Here is a (totally contrived) example which illustrates how syntax is ++assigned to various conditional constructs: ++ ++@example ++ 1: void spam( int index ) ++ 2: @{ ++ 3: for( int i=0; i 0 ); ++15: @} ++@end example ++ ++Only the lines that illustrate new syntactic symbols will be discussed. ++ ++@ssindex substatement-open ++@ssindex statement-block-intro ++@ssindex block-close ++Line 4 has a brace which opens a conditional's substatement block. It ++is thus assigned @code{substatement-open} syntax, and since line 5 is ++the first line in the substatement block, it is assigned ++@code{statement-block-intro} syntax. Line 10 contains the brace ++that closes the inner substatement block, and is therefore given the ++syntax @code{block-close}@footnote{@code{block-open} is used only for ++``free-standing'' blocks, and is somewhat rare (@pxref{Literal ++Symbols} for an example.)}. Line 13 is treated the same way. ++ ++@ssindex substatement ++Lines 6 and 9 are also substatements of conditionals, but since they ++don't start blocks they are given @code{substatement} syntax ++instead of @code{substatement-open}. ++ ++@ssindex substatement-label ++Line 8 contains a label, which is normally given @code{label} syntax. ++This one is however a bit special since it's between a conditional and ++its substatement. It's analyzed as @code{substatement-label} to let you ++handle this rather odd case differently from normal labels. ++ ++@ssindex else-clause ++@ssindex catch-clause ++Line 7 start with an @code{else} that matches the @code{if} statement on ++line 5. It is therefore given the @code{else-clause} syntax and is ++anchored on the matching @code{if}. The @code{try}-@code{catch} ++constructs in C++ and Java are treated this way too, except that ++@code{catch} and (in Java) @code{finally}, are marked with ++@code{catch-clause}. ++ ++@ssindex do-while-closure ++The @code{while} construct on line 14 that closes a @code{do} ++conditional is given the special syntax @code{do-while-closure} if it ++appears on a line by itself. Note that if the @code{while} appeared on ++the same line as the preceding close brace, that line would still have ++@code{block-close} syntax. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Switch Statement Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Switch statements have their own set of syntactic symbols. Here's an ++example: ++ ++@example ++ 1: void spam( enum Ingredient i ) ++ 2: @{ ++ 3: switch( i ) @{ ++ 4: case Ham: ++ 5: be_a_pig(); ++ 6: break; ++ 7: case Salt: ++ 8: drink_some_water(); ++ 9: break; ++10: default: ++11: @{ ++12: what_is_it(); ++13: break; ++14: @} ++15: @} ++14: @} ++@end example ++ ++@ssindex case-label ++@ssindex statement-case-intro ++@ssindex statement-case-open ++Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, ++while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 ++is treated slightly differently since it contains a brace that opens a ++block --- it is given @code{statement-case-open} syntax. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Brace List Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex brace lists ++There are a set of syntactic symbols that are used to recognize ++constructs inside of brace lists. A brace list is defined as an ++@code{enum} or aggregate initializer list, such as might statically ++initialize an array of structs. The three special aggregate constructs ++in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as ++brace lists too. An example: ++ ++@example ++ 1: static char* ingredients[] = ++ 2: @{ ++ 3: "Ham", ++ 4: "Salt", ++ 5: NULL ++ 6: @}; ++@end example ++ ++@ssindex brace-list-open ++@ssindex brace-list-intro ++@ssindex brace-list-close ++@ssindex brace-list-entry ++Following convention, line 2 in this example is assigned ++@code{brace-list-open} syntax, and line 3 is assigned ++@code{brace-list-intro} syntax. Likewise, line 6 is assigned ++@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned ++@code{brace-list-entry} syntax, as would all subsequent lines in this ++initializer list. ++ ++@ssindex brace-entry-open ++Your static initializer might be initializing nested structures, for ++example: ++ ++@example ++ 1: struct intpairs[] = ++ 2: @{ ++ 3: @{ 1, 2 @}, ++ 4: @{ ++ 5: 3, ++ 6: 4 ++ 7: @} ++ 8: @{ 1, ++ 9: 2 @}, ++10: @{ 3, 4 @} ++11: @}; ++@end example ++ ++Here, you've already seen the analysis of lines 1, 2, 3, and 11. On ++line 4, things get interesting; this line is assigned ++@code{brace-entry-open} syntactic symbol because it's a bracelist entry ++line that starts with an open brace. Lines 5 and 6 (and line 9) are ++pretty standard, and line 7 is a @code{brace-list-close} as you'd ++expect. Once again, line 8 is assigned as @code{brace-entry-open} as is ++line 10. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection External Scope Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++External language definition blocks also have their own syntactic ++symbols. In this example: ++ ++@example ++ 1: extern "C" ++ 2: @{ ++ 3: int thing_one( int ); ++ 4: int thing_two( double ); ++ 5: @} ++@end example ++ ++@ssindex extern-lang-open ++@ssindex extern-lang-close ++@ssindex inextern-lang ++@ssindex inclass ++@noindent ++line 2 is given the @code{extern-lang-open} syntax, while line 5 is given ++the @code{extern-lang-close} syntax. The analysis for line 3 yields: ++ ++@example ++((inextern-lang) (topmost-intro 14)) ++@end example ++ ++@noindent ++where @code{inextern-lang} is a modifier similar in purpose to ++@code{inclass}. ++ ++There are various other top level blocks like @code{extern}, and they ++are all treated in the same way except that the symbols are named after ++the keyword that introduces the block. E.g. C++ namespace blocks get ++the three symbols @code{namespace-open}, @code{namespace-close} and ++@code{innamespace}. The currently recognized top level blocks are: ++ ++@table @asis ++@item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang} ++@code{extern} blocks in C and C++.@footnote{These should logically be ++named @code{extern-open}, @code{extern-close} and @code{inextern}, but ++that isn't the case for historical reasons.} ++ ++@item @code{namespace-open}, @code{namespace-close}, @code{innamespace} ++@ssindex namespace-open ++@ssindex namespace-close ++@ssindex innamespace ++@code{namespace} blocks in C++. ++ ++@item @code{module-open}, @code{module-close}, @code{inmodule} ++@ssindex module-open ++@ssindex module-close ++@ssindex inmodule ++@code{module} blocks in CORBA IDL. ++ ++@item @code{composition-open}, @code{composition-close}, @code{incomposition} ++@ssindex composition-open ++@ssindex composition-close ++@ssindex incomposition ++@code{composition} blocks in CORBA CIDL. ++@end table ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Parenthesis (Argument) List Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++A number of syntactic symbols are associated with parenthesis lists, ++a.k.a argument lists, as found in function declarations and function ++calls. This example illustrates these: ++ ++@example ++ 1: void a_function( int line1, ++ 2: int line2 ); ++ 3: ++ 4: void a_longer_function( ++ 5: int line1, ++ 6: int line2 ++ 7: ); ++ 8: ++ 9: void call_them( int line1, int line2 ) ++10: @{ ++11: a_function( ++12: line1, ++13: line2 ++14: ); ++15: ++16: a_longer_function( line1, ++17: line2 ); ++18: @} ++@end example ++ ++@ssindex arglist-intro ++@ssindex arglist-close ++Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are ++the first line following the open parenthesis, and lines 7 and 14 are ++assigned @code{arglist-close} syntax since they contain the parenthesis ++that closes the argument list. ++ ++@ssindex arglist-cont-nonempty ++@ssindex arglist-cont ++Lines that continue argument lists can be assigned one of two syntactic ++symbols. For example, Lines 2 and 17 ++are assigned @code{arglist-cont-nonempty} syntax. What this means ++is that they continue an argument list, but that the line containing the ++parenthesis that opens the list is @emph{not empty} following the open ++parenthesis. Contrast this against lines 6 and 13 which are assigned ++@code{arglist-cont} syntax. This is because the parenthesis that opens ++their argument lists is the last character on that line. ++ ++Syntactic elements with @code{arglist-intro}, ++@code{arglist-cont-nonempty}, and @code{arglist-close} contain two ++buffer positions: the anchor position (the beginning of the ++declaration or statement) and the position of the open parenthesis. ++The latter position can be used in a line-up function (@pxref{Line-Up ++Functions}). ++ ++Note that there is no @code{arglist-open} syntax. This is because any ++parenthesis that opens an argument list, appearing on a separate line, ++is assigned the @code{statement-cont} syntax instead. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Comment String Label and Macro Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++A few miscellaneous syntactic symbols that haven't been previously ++covered are illustrated by this C++ example: ++ ++@example ++ 1: void Bass::play( int volume ) ++ 2: const ++ 3: @{ ++ 4: /* this line starts a multiline ++ 5: * comment. This line should get `c' syntax */ ++ 6: ++ 7: char* a_multiline_string = "This line starts a multiline \ ++ 8: string. This line should get `string' syntax."; ++ 9: ++10: note: ++11: @{ ++12: #ifdef LOCK ++13: Lock acquire(); ++14: #endif // LOCK ++15: slap_pop(); ++16: cout << "I played " ++17: << "a note\n"; ++18: @} ++19: @} ++@end example ++ ++The lines to note in this example include: ++ ++@itemize @bullet ++@item ++@ssindex func-decl-cont ++Line 2 is assigned the @code{func-decl-cont} syntax. ++ ++@item ++@ssindex comment-intro ++Line 4 is assigned both @code{defun-block-intro} @emph{and} ++@code{comment-intro} syntax. A syntactic element with ++@code{comment-intro} has no anchor point --- It is always accompanied ++by another syntactic element which does have one. ++ ++@item ++@ssindex c ++Line 5 is assigned @code{c} syntax. ++ ++@item ++@cindex syntactic whitespace ++Line 6 which, even though it contains nothing but whitespace, is ++assigned @code{defun-block-intro}. Note that the appearance of the ++comment on lines 4 and 5 do not cause line 6 to be assigned ++@code{statement} syntax because comments are considered to be ++@dfn{syntactic whitespace}, which are ignored when analyzing ++code. ++ ++@item ++@ssindex string ++Line 8 is assigned @code{string} syntax. ++ ++@item ++@ssindex label ++Line 10 is assigned @code{label} syntax. ++ ++@item ++@ssindex block-open ++Line 11 is assigned @code{block-open} as well as @code{statement} ++syntax. A @code{block-open} syntactic element doesn't have an anchor ++position, since it always appears with another syntactic element which ++does have one. ++ ++@item ++@ssindex cpp-macro ++Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the ++normal syntactic symbols (@code{statement-block-intro} and ++@code{statement}, respectively). Normally @code{cpp-macro} is ++configured to cancel out the normal syntactic context to make all ++preprocessor directives stick to the first column, but that's easily ++changed if you want preprocessor directives to be indented like the rest ++of the code. Like @code{comment-intro}, a syntactic element with ++@code{cpp-macro} doesn't contain an anchor position. ++ ++@item ++@ssindex stream-op ++Line 17 is assigned @code{stream-op} syntax. ++@end itemize ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Multiline Macro Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex multiline macros ++@cindex syntactic whitespace ++@ssindex cpp-define-intro ++@ssindex cpp-macro-cont ++Multiline preprocessor macro definitions are normally handled just like ++other code, i.e. the lines inside them are indented according to the ++syntactic analysis of the preceding lines inside the macro. The first ++line inside a macro definition (i.e. the line after the starting line of ++the cpp directive itself) gets @code{cpp-define-intro}. In this example: ++ ++@example ++ 1: #define LIST_LOOP(cons, listp) \ ++ 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ ++ 3: if (!CONSP (cons)) \ ++ 4: signal_error ("Invalid list format", listp); \ ++ 5: else ++@end example ++ ++@noindent ++line 1 is given the syntactic symbol @code{cpp-macro}. The first line ++of a cpp directive is always given that symbol. Line 2 is given ++@code{cpp-define-intro}, so that you can give the macro body as a whole ++some extra indentation. Lines 3 through 5 are then analyzed as normal ++code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause} ++on line 5. ++ ++The syntactic analysis inside macros can be turned off with ++@code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In ++that case, lines 2 through 5 would all be given @code{cpp-macro-cont} ++with an anchor position pointing to the @code{#} which starts the cpp ++directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed ++macros.}. ++ ++@xref{Custom Macros}, for more info about the treatment of macros. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Objective-C Method Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++In Objective-C buffers, there are three additional syntactic symbols ++assigned to various message calling constructs. Here's an example ++illustrating these: ++ ++@example ++ 1: - (void)setDelegate:anObject ++ 2: withStuff:stuff ++ 3: @{ ++ 4: [delegate masterWillRebind:self ++ 5: toDelegate:anObject ++ 6: withExtraStuff:stuff]; ++ 7: @} ++@end example ++ ++@ssindex objc-method-intro ++@ssindex objc-method-args-cont ++@ssindex objc-method-call-cont ++Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is ++assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both ++assigned @code{objc-method-call-cont} syntax. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Anonymous Class Symbol (Java) ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Java has a concept of anonymous classes which can look something like ++this: ++ ++@example ++ 1: public void watch(Observable o) @{ ++ 2: o.addObserver(new Observer() @{ ++ 3: public void update(Observable o, Object arg) @{ ++ 4: history.addElement(arg); ++ 5: @} ++ 6: @}); ++ 7: @} ++@end example ++ ++@ssindex inexpr-class ++The brace following the @code{new} operator opens the anonymous class. ++Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the ++@code{inclass} symbol used in normal classes. Thus, the class will be ++indented just like a normal class, with the added indentation given to ++@code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't ++have an anchor position. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection Statement Block Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++There are a few occasions where a statement block might be used inside ++an expression. One is in C or C++ code using the gcc extension for ++this, e.g: ++ ++@example ++ 1: int res = (@{ ++ 2: int y = foo (); int z; ++ 3: if (y > 0) z = y; else z = - y; ++ 4: z; ++ 5: @}); ++@end example ++ ++@ssindex inexpr-statement ++Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the ++symbols they'd get in a normal block. Therefore, the indentation put on ++@code{inexpr-statement} is added to the normal statement block ++indentation. An @code{inexpr-statement} syntactic element doesn't ++contain an anchor position. ++ ++In Pike code, there are a few other situations where blocks occur inside ++statements, as illustrated here: ++ ++@example ++ 1: array itgob() ++ 2: @{ ++ 3: string s = map (backtrace()[-2][3..], ++ 4: lambda ++ 5: (mixed arg) ++ 6: @{ ++ 7: return sprintf ("%t", arg); ++ 8: @}) * ", " + "\n"; ++ 9: return catch @{ ++10: write (s + "\n"); ++11: @}; ++12: @} ++@end example ++ ++@ssindex inlambda ++@ssindex lambda-intro-cont ++Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes ++by the @code{lambda} keyword. If the function argument list is put ++on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} ++syntax. The function body is handled as an inline method body, with the ++addition of the @code{inlambda} syntactic symbol. This means that line ++6 gets @code{inlambda} and @code{inline-open}, and line 8 gets ++@code{inline-close}@footnote{You might wonder why it doesn't get ++@code{inlambda} too. It's because the closing brace is relative to the ++opening brace, which stands on its own line in this example. If the ++opening brace was hanging on the previous line, then the closing brace ++would get the @code{inlambda} syntax too to be indented correctly.}. ++ ++@ssindex inexpr-statement ++On line 9, @code{catch} is a special function taking a statement block ++as its argument. The block is handled as an in-expression statement ++with the @code{inexpr-statement} syntax, just like the gcc extended C ++example above. The other similar special function, @code{gauge}, is ++handled like this too. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node K&R Symbols, , Statement Block Symbols, Syntactic Symbols ++@comment node-name, next, previous, up ++@subsection K&R Symbols ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@ssindex knr-argdecl-intro ++@ssindex knr-argdecl ++Two other syntactic symbols can appear in old style, non-prototyped C ++code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: ++ ++@example ++ 1: int add_three_integers(a, b, c) ++ 2: int a; ++ 3: int b; ++ 4: int c; ++ 5: @{ ++ 6: return a + b + c; ++ 7: @} ++@end example ++ ++Here, line 2 is the first line in an argument declaration list and so is ++given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines ++(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} ++syntax. ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics ++@comment node-name, next, previous, up ++@section Indentation Calculation ++@cindex indentation ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Indentation for a line is calculated from the syntactic context ++(@pxref{Syntactic Analysis}). ++ ++First, a buffer position is found whose column will be the base for the ++indentation calculation. It's the anchor position in the first ++syntactic element that provides one that is used. If no syntactic ++element has an anchor position then column zero is used. ++ ++Second, the syntactic symbols in each syntactic element are looked up ++in the @code{c-offsets-alist} style variable ++(@pxref{c-offsets-alist}), which is an association list of syntactic ++symbols and the offsets to apply for those symbols. These offsets are ++added together with the base column to produce the new indentation ++column. ++ ++Let's use our two code examples above to see how this works. Here is ++our first example again: ++ ++@example ++ 1: void swap( int& a, int& b ) ++ 2: @{ ++ 3: int tmp = a; ++ 4: a = b; ++ 5: b = tmp; ++ 6: @} ++@end example ++ ++Let's say point is on line 3 and we hit the @key{TAB} key to reindent ++the line. The syntactic context for that line is: ++ ++@example ++((defun-block-intro 29)) ++@end example ++ ++@noindent ++Since buffer position 29 is the first and only anchor position in the ++list, @ccmode{} goes there and asks for the current column. This brace ++is in column zero, so @ccmode{} uses @samp{0} as the base column. ++ ++Next, @ccmode{} looks up @code{defun-block-intro} in the ++@code{c-offsets-alist} style variable. Let's say it finds the value ++@samp{4}; it adds this to the base column @samp{0}, yielding a running ++total indentation of 4 spaces. ++ ++Since there is only one syntactic element on the list for this line, ++indentation calculation is complete, and the total indentation for the ++line is 4 spaces. ++ ++Here's another example: ++ ++@example ++ 1: int add( int val, int incr, int doit ) ++ 2: @{ ++ 3: if( doit ) ++ 4: @{ ++ 5: return( val + incr ); ++ 6: @} ++ 7: return( val ); ++ 8: @} ++@end example ++ ++If we were to hit @kbd{TAB} on line 4 in the above example, the same ++basic process is performed, despite the differences in the syntactic ++context. The context for this line is: ++ ++@example ++((substatement-open 46)) ++@end example ++ ++Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in ++@code{if} on line 3. This character is in the fourth column on that ++line so the base column is @samp{4}. Then @ccmode{} looks up the ++@code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it ++finds the value @samp{4}. It's added with the base column and yields an ++indentation for the line of 8 spaces. ++ ++Simple, huh? ++ ++Actually, it's a bit more complicated than that since the entries on ++@code{c-offsets-alist} can be much more than plain offsets. ++@xref{c-offsets-alist}, for the full story. ++ ++Anyway, the mode usually just does The Right Thing without you having to ++think about it in this much detail. But when customizing indentation, ++it's helpful to understand the general indentation model being used. ++ ++As you configure @ccmode{}, you might want to set the variable ++@code{c-echo-syntactic-information-p} to non-@code{nil} so that the ++syntactic context and calculated offset always is echoed in the ++minibuffer when you hit @kbd{TAB}. ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top ++@comment node-name, next, previous, up ++@chapter Customizing Indentation ++@cindex customization, indentation ++@cindex indentation ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The principal variable for customizing indentation is the style ++variable @code{c-offsets-alist}, which gives an @dfn{offset} (an ++indentation rule) for each syntactic symbol. Its structure and ++semantics are completely described in @ref{c-offsets-alist}. The ++various ways you can set the variable, including the use of the ++@ccmode{} style system, are described in @ref{Config Basics} and its ++sections, in particular @ref{Style Variables}. ++ ++The simplest and most used kind of ``offset'' setting in ++@code{c-offsets-alist} is in terms of multiples of ++@code{c-basic-offset}: ++ ++@defopt c-basic-offset ++@vindex basic-offset (c-) ++This style variable holds the basic offset between indentation levels. ++It's factory default is 4, but all the built-in styles set it ++themselves, to some value between 2 (for @code{gnu} style) and 8 (for ++@code{bsd}, @code{linux}, and @code{python} styles). ++@end defopt ++ ++The most flexible ``offset'' setting you can make in ++@code{c-offsets-alist} is a line-up function (or even a list of them), ++either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one ++you write yourself (@pxref{Custom Line-Up}). ++ ++Finally, in @ref{Other Indentation} you'll find the tool of last ++resort: a hook which is called after a line has been indented. You ++can install functions here to make ad-hoc adjustments to any line's ++indentation. ++ ++@menu ++* c-offsets-alist:: ++* Interactive Customization:: ++* Line-Up Functions:: ++* Custom Line-Up:: ++* Other Indentation:: ++@end menu ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation ++@comment node-name, next, previous, up ++@section c-offsets-alist ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++This section explains the structure and semantics of the style ++variable @code{c-offset-alist}, the principal variable for configuring ++indentation. Details of how to set it up, and its relationship to ++@ccmode{}'s style system are given in @ref{Style Variables}. ++ ++@defopt c-offsets-alist ++@vindex offsets-alist (c-) ++This is an alist which associates an offset with each syntactic ++symbol. This @dfn{offset} is a rule specifying how to indent a line ++whose syntactic context matches the symbol. @xref{Syntactic ++Analysis}. ++ ++Note that the buffer-local binding of this alist in a @ccmode{} buffer ++contains an entry for @emph{every} syntactic symbol. Its global ++binding and its settings within style specifications usually contain ++only a few entries. @xref{Style Variables}. ++ ++The offset specification associated with any particular syntactic ++symbol can be an integer, a variable name, a vector, a function or ++lambda expression, a list, or one of the following special symbols: ++@code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The ++meanings of these values are described in detail below. ++ ++Here is an example fragment of a @code{c-offsets-alist}, showing some ++of these kinds of offsets: ++ ++@example ++((statement . 0) ++ (substatement . +) ++ (cpp-macro . [0]) ++ (topmost-intro-cont . c-lineup-topmost-intro-cont) ++ (statement-block-intro . (add c-lineup-whitesmith-in-block ++ c-indent-multi-line-block)) ++ @dots{} ++@*) ++@end example ++@end defopt ++ ++@deffn Command c-set-offset (@kbd{C-c C-o}) ++@findex set-offset (c-) ++@kindex C-c C-o ++This command changes the entry for a syntactic symbol in the current ++binding of @code{c-offsets-alist}, or it inserts a new entry if there ++isn't already one for that syntactic symbol. ++ ++You can use @code{c-set-offsets} interactively within a @ccmode{} ++buffer to make experimental changes to your indentation settings. ++@kbd{C-c C-o} prompts you for the syntactic symbol to change ++(defaulting to that of the current line) and the new offset ++(defaulting to the current offset). ++ ++@code{c-set-offsets} takes two arguments when used programmatically: ++@var{symbol}, the syntactic element symbol to change and @var{offset}, ++the new offset for that syntactic element. You can call the command ++in your @file{.emacs} to change the global binding of ++@code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a ++hook function to make changes from the current style. @ccmode{} ++itself uses this function when initializing styles. ++@end deffn ++ ++@cindex offset specification ++The ``offset specifications'' in @code{c-offsets-alist} can be any of ++the following: ++ ++@table @asis ++@item An integer ++The integer specifies a relative offset. All relative ++offsets@footnote{The syntactic context @code{@w{((defun-block-intro ++2724) (comment-intro))}} would likely have two relative offsets.} will ++be added together and used to calculate the indentation relative to an ++anchor position earlier in the buffer. @xref{Indentation ++Calculation}, for details. Most of the time, it's probably better to ++use one of the special symbols like @code{+} than an integer (apart ++from zero). ++ ++@item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/} ++These special symbols describe a relative offset in multiples of ++@code{c-basic-offset}: ++ ++By defining a style's indentation in terms of @code{c-basic-offset}, ++you can change the amount of whitespace given to an indentation level ++while maintaining the same basic shape of your code. Here are the ++values that the special symbols correspond to: ++ ++@table @code ++@item + ++@code{c-basic-offset} times 1 ++@item - ++@code{c-basic-offset} times -1 ++@item ++ ++@code{c-basic-offset} times 2 ++@item -- ++@code{c-basic-offset} times -2 ++@item * ++@code{c-basic-offset} times 0.5 ++@item / ++@code{c-basic-offset} times -0.5 ++@end table ++ ++@item A vector ++The first element of the vector, an integer, sets the absolute ++indentation column. This will override any previously calculated ++indentation, but won't override relative indentation calculated from ++syntactic elements later on in the syntactic context of the line being ++indented. @xref{Indentation Calculation}. Any elements in the vector ++beyond the first will be ignored. ++ ++@item A function or lambda expression ++The function will be called and its return value will in turn be ++evaluated as an offset specification. Functions are useful when more ++context than just the syntactic symbol is needed to get the desired ++indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for ++details about them. ++ ++@item A symbol with a variable binding ++If the symbol also has a function binding, the function takes ++precedence over the variable. Otherwise the value of the variable is ++used. It must be an integer (which is used as relative offset) or a ++vector (an absolute offset). ++ ++@item A list ++The offset can also be a list containing several offset ++specifications; these are evaluated recursively and combined. A list ++is typically only useful when some of the offsets are line-up ++functions. A common strategy is calling a sequence of functions in ++turn until one of them recognizes that it is appropriate for the ++source line and returns a non-@code{nil} value. ++ ++@code{nil} values are always ignored when the offsets are combined. ++The first element of the list specifies the method of combining the ++non-@code{nil} offsets from the remaining elements: ++ ++@table @code ++@item first ++Use the first offset that doesn't evaluate to @code{nil}. Subsequent ++elements of the list don't get evaluated. ++@item min ++Use the minimum of all the offsets. All must be either relative or ++absolute - they can't be mixed. ++@item max ++Use the maximum of all the offsets. All must be either relative or ++absolute - they can't be mixed. ++@item add ++Add all the evaluated offsets together. Exactly one of them may be ++absolute, in which case the result is absolute. Any relative offsets ++that preceded the absolute one in the list will be ignored in that case. ++@end table ++ ++As a compatibility measure, if the first element is none of the above ++then it too will be taken as an offset specification and the whole list ++will be combined according to the method @code{first}. ++@end table ++ ++@vindex c-strict-syntax-p ++@vindex strict-syntax-p (c-) ++If an offset specification evaluates to @code{nil}, then a relative ++offset of 0 (zero) is used@footnote{There is however a variable ++@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an ++error to be signaled in that case. It's now considered obsolete since ++it doesn't work well with some of the alignment functions that return ++@code{nil} instead of zero. You should therefore leave ++@code{c-strict-syntax-p} set to @code{nil}.}. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation ++@comment node-name, next, previous, up ++@section Interactive Customization ++@cindex customization, interactive ++@cindex interactive customization ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++As an example of how to customize indentation, let's change the ++style of this example@footnote{In this and subsequent examples, the ++original code is formatted using the @samp{gnu} style unless otherwise ++indicated. @xref{Styles}.}: ++ ++@example ++@group ++ 1: int add( int val, int incr, int doit ) ++ 2: @{ ++ 3: if( doit ) ++ 4: @{ ++ 5: return( val + incr ); ++ 6: @} ++ 7: return( val ); ++ 8: @} ++@end group ++@end example ++ ++@noindent ++to: ++ ++@example ++@group ++ 1: int add( int val, int incr, int doit ) ++ 2: @{ ++ 3: if( doit ) ++ 4: @{ ++ 5: return( val + incr ); ++ 6: @} ++ 7: return( val ); ++ 8: @} ++@end group ++@end example ++ ++In other words, we want to change the indentation of braces that open a ++block following a condition so that the braces line up under the ++conditional, instead of being indented. Notice that the construct we ++want to change starts on line 4. To change the indentation of a line, ++we need to see which syntactic symbols affect the offset calculations ++for that line. Hitting @kbd{C-c C-s} on line 4 yields: ++ ++@example ++((substatement-open 44)) ++@end example ++ ++@noindent ++so we know that to change the offset of the open brace, we need to ++change the indentation for the @code{substatement-open} syntactic ++symbol. ++ ++To do this interactively, just hit @kbd{C-c C-o}. This prompts ++you for the syntactic symbol to change, providing a reasonable default. ++In this case, the default is @code{substatement-open}, which is just the ++syntactic symbol we want to change! ++ ++After you hit return, @ccmode{} will then prompt you for the new ++offset value, with the old value as the default. The default in this ++case is @samp{+}, but we want no extra indentation so enter ++@samp{0} and @kbd{RET}. This will associate the offset 0 with the ++syntactic symbol @code{substatement-open}. ++ ++To check your changes quickly, just hit @kbd{C-c C-q} ++(@code{c-indent-defun}) to reindent the entire function. The example ++should now look like: ++ ++@example ++@group ++ 1: int add( int val, int incr, int doit ) ++ 2: @{ ++ 3: if( doit ) ++ 4: @{ ++ 5: return( val + incr ); ++ 6: @} ++ 7: return( val ); ++ 8: @} ++@end group ++@end example ++ ++Notice how just changing the open brace offset on line 4 is all we ++needed to do. Since the other affected lines are indented relative to ++line 4, they are automatically indented the way you'd expect. For more ++complicated examples, this might not always work. The general approach ++to take is to always start adjusting offsets for lines higher up in the ++file, then reindent and see if any following lines need further ++adjustments. ++ ++@c Move this bit to "Styles" (2005/10/7) ++@deffn Command c-set-offset symbol offset ++@findex set-offset (c-) ++@kindex C-c C-o ++This is the command bound to @kbd{C-c C-o}. It provides a convenient ++way to set offsets on @code{c-offsets-alist} both interactively (see ++the example above) and from your mode hook. ++ ++It takes two arguments when used programmatically: @var{symbol} is the ++syntactic element symbol to change and @var{offset} is the new offset ++for that syntactic element. ++@end deffn ++@c End of MOVE THIS BIT. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation ++@comment node-name, next, previous, up ++@section Line-Up Functions ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@cindex line-up function ++@cindex indentation function ++Often there are cases when a simple offset setting on a syntactic ++symbol isn't enough to get the desired indentation---for example, you ++might want to line up a closing parenthesis with the matching opening ++one rather than indenting relative to its ``anchor point''. @ccmode{} ++provides this flexibility with @dfn{line-up functions}. ++ ++The way you associate a line-up function with a syntactic symbol is ++described in @ref{c-offsets-alist}. @ccmode{} comes with many ++predefined line-up functions for common situations. If none of these ++does what you want, you can write your own. @xref{Custom Line-Up}. ++Sometimes, it is easier to tweak the standard indentation by adding a ++function to @code{c-special-indent-hook} (@pxref{Other Indentation}). ++ ++The line-up functions haven't been adapted for AWK buffers or tested ++with them. Some of them might work serendipitously. There shouldn't be ++any problems writing custom line-up functions for AWK mode. ++ ++The calling convention for line-up functions is described fully in ++@ref{Custom Line-Up}. Roughly speaking, the return value is either an ++offset itself (such as @code{+} or @code{[0]}) or it's @code{nil}, ++meaning ``this function is inappropriate in this case - try a ++different one''. @xref{c-offsets-alist}. ++ ++The subsections below describe all the standard line-up functions, ++categorized by the sort of token the lining-up centers around. For ++each of these functions there is a ``works with'' list that indicates ++which syntactic symbols the function is intended to be used with. ++ ++@macro workswith ++@emph{Works with:@ } ++@end macro ++@ifinfo ++@unmacro workswith ++@macro workswith ++Works with: ++@end macro ++@end ifinfo ++ ++@macro sssTBasicOffset ++<--> @i{c-basic-offset}@c ++@end macro ++ ++@macro sssTsssTBasicOffset ++<--><--> @i{c-basic-offset}@c ++@end macro ++ ++@macro hereFn{func} ++<- @i{\func\}@c ++@end macro ++ ++@c The TeX backend seems to insert extra spaces around the argument. :P ++@iftex ++@unmacro hereFn ++@macro hereFn{func} ++<-@i{\func\}@c ++@end macro ++@end iftex ++ ++@menu ++* Brace/Paren Line-Up:: ++* List Line-Up:: ++* Operator Line-Up:: ++* Comment Line-Up:: ++* Misc Line-Up:: ++@end menu ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions ++@comment node-name, next, previous, up ++@subsection Brace and Parenthesis Line-Up Functions ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The line-up functions here calculate the indentation for braces, ++parentheses and statements within brace blocks. ++ ++@defun c-lineup-close-paren ++@findex lineup-close-paren (c-) ++Line up the closing paren under its corresponding open paren if the ++open paren is followed by code. If the open paren ends its line, no ++indentation is added. E.g: ++ ++@example ++@group ++main (int, ++ char ** ++ ) @hereFn{c-lineup-close-paren} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++main ( ++ int, char ** ++) @hereFn{c-lineup-close-paren} ++@end group ++@end example ++ ++As a special case, if a brace block is opened at the same line as the ++open parenthesis of the argument list, the indentation is ++@code{c-basic-offset} instead of the open paren column. See ++@code{c-lineup-arglist} for further discussion of this ``DWIM'' measure. ++ ++@workswith All @code{*-close} symbols. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@anchor{c-lineup-arglist-close-under-paren} ++@defun c-lineup-arglist-close-under-paren ++@findex lineup-arglist-close-under-paren (c-) ++Set your @code{arglist-close} syntactic symbol to this line-up function ++so that parentheses that close argument lists will line up under the ++parenthesis that opened the argument list. It can also be used with ++@code{arglist-cont} and @code{arglist-cont-nonempty} to line up all ++lines inside a parenthesis under the open paren. ++ ++As a special case, if a brace block is opened at the same line as the ++open parenthesis of the argument list, the indentation is ++@code{c-basic-offset} only. See @code{c-lineup-arglist} for further ++discussion of this ``DWIM'' measure. ++ ++@workswith Almost all symbols, but are typically most useful on ++@code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and ++@code{arglist-cont-nonempty}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-indent-one-line-block ++@findex indent-one-line-block (c-) ++Indent a one line block @code{c-basic-offset} extra. E.g: ++ ++@example ++@group ++if (n > 0) ++ @{m+=n; n=0;@} @hereFn{c-indent-one-line-block} ++@sssTBasicOffset{} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++if (n > 0) ++@{ @hereFn{c-indent-one-line-block} ++ m+=n; n=0; ++@} ++@end group ++@end example ++ ++The block may be surrounded by any kind of parenthesis characters. ++@code{nil} is returned if the line doesn't start with a one line block, ++which makes the function usable in list expressions. ++ ++@workswith Almost all syntactic symbols, but most useful on the ++@code{-open} symbols. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-indent-multi-line-block ++@findex indent-multi-line-block (c-) ++Indent a multiline block @code{c-basic-offset} extra. E.g: ++ ++@example ++@group ++int *foo[] = @{ ++ NULL, ++ @{17@}, @hereFn{c-indent-multi-line-block} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++int *foo[] = @{ ++ NULL, ++ @{ @hereFn{c-indent-multi-line-block} ++ 17 ++ @}, ++ @sssTBasicOffset{} ++@end group ++@end example ++ ++The block may be surrounded by any kind of parenthesis characters. ++@code{nil} is returned if the line doesn't start with a multiline ++block, which makes the function usable in list expressions. ++ ++@workswith Almost all syntactic symbols, but most useful on the ++@code{-open} symbols. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-runin-statements ++@findex lineup-runin-statements (c-) ++Line up statements for coding standards which place the first statement ++in a block on the same line as the block opening brace@footnote{Run-in ++style doesn't really work too well. You might need to write your own ++custom line-up functions to better support this style.}. E.g: ++ ++@example ++@group ++int main() ++@{ puts ("Hello!"); ++ return 0; @hereFn{c-lineup-runin-statements} ++@} ++@end group ++@end example ++ ++If there is no statement after the opening brace to align with, ++@code{nil} is returned. This makes the function usable in list ++expressions. ++ ++@workswith The @code{statement} syntactic symbol. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-inexpr-block ++@findex lineup-inexpr-block (c-) ++This can be used with the in-expression block symbols to indent the ++whole block to the column where the construct is started. E.g. for Java ++anonymous classes, this lines up the class under the @samp{new} keyword, ++and in Pike it lines up the lambda function body under the @samp{lambda} ++keyword. Returns @code{nil} if the block isn't part of such a ++construct. ++ ++@workswith @code{inlambda}, @code{inexpr-statement}, ++@code{inexpr-class}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-after-whitesmith-blocks ++@findex lineup-after-whitesmith-blocks (c-) ++Compensate for Whitesmith style indentation of blocks. Due to the way ++@ccmode{} calculates anchor positions for normal lines inside blocks, ++this function is necessary for those lines to get correct Whitesmith ++style indentation. Consider the following examples: ++ ++@example ++@group ++int foo() ++ @{ ++ a; ++ x; @hereFn{c-lineup-after-whitesmith-blocks} ++@end group ++@end example ++ ++@example ++@group ++int foo() ++ @{ ++ @{ ++ a; ++ @} ++ x; @hereFn{c-lineup-after-whitesmith-blocks} ++@end group ++@end example ++ ++The fact that the line with @code{x} is preceded by a Whitesmith style ++indented block in the latter case and not the first should not affect ++its indentation. But since CC Mode in cases like this uses the ++indentation of the preceding statement as anchor position, the @code{x} ++would in the second case be indented too much if the offset for ++@code{statement} was set simply to zero. ++ ++This lineup function corrects for this situation by detecting if the ++anchor position is at an open paren character. In that case, it instead ++indents relative to the surrounding block just like ++@code{c-lineup-whitesmith-in-block}. ++ ++@workswith @code{brace-list-entry}, @code{brace-entry-open}, ++@code{statement}, @code{arglist-cont}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-whitesmith-in-block ++@findex lineup-whitesmith-in-block (c-) ++Line up lines inside a block in Whitesmith style. It's done in a way ++that works both when the opening brace hangs and when it doesn't. E.g: ++ ++@example ++@group ++something ++ @{ ++ foo; @hereFn{c-lineup-whitesmith-in-block} ++ @} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++something @{ ++ foo; @hereFn{c-lineup-whitesmith-in-block} ++ @} ++@sssTBasicOffset{} ++@end group ++@end example ++ ++In the first case the indentation is kept unchanged, in the second ++@code{c-basic-offset} is added. ++ ++@workswith @code{defun-close}, @code{defun-block-intro}, ++@code{inline-close}, @code{block-close}, @code{brace-list-close}, ++@code{brace-list-intro}, @code{statement-block-intro}, ++@code{arglist-intro}, @code{arglist-cont-nonempty}, ++@code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass} ++and @code{inextern-lang}. ++@end defun ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions ++@comment node-name, next, previous, up ++@subsection List Line-Up Functions ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The line-up functions here calculate the indentation for lines which ++form lists of items, usually separated by commas. ++ ++The function @ref{c-lineup-arglist-close-under-paren}, which is mainly ++for indenting a close parenthesis, is also useful for the lines ++contained within parentheses. ++ ++@defun c-lineup-arglist ++@findex lineup-arglist (c-) ++Line up the current argument line under the first argument. ++ ++As a special case, if an argument on the same line as the open ++parenthesis starts with a brace block opener, the indentation is ++@code{c-basic-offset} only. This is intended as a ``DWIM'' measure in ++cases like macros that contain statement blocks, e.g: ++ ++@example ++@group ++A_VERY_LONG_MACRO_NAME (@{ ++ some (code, with + long, lines * in[it]); ++ @}); ++@sssTBasicOffset{} ++@end group ++@end example ++ ++This is motivated partly because it's more in line with how code ++blocks are handled, and partly since it approximates the behavior of ++earlier CC Mode versions, which due to inaccurate analysis tended to ++indent such cases this way. ++ ++@workswith @code{arglist-cont-nonempty}, @code{arglist-close}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-arglist-intro-after-paren ++@findex lineup-arglist-intro-after-paren (c-) ++Line up a line to just after the open paren of the surrounding paren or ++brace block. ++ ++@workswith @code{defun-block-intro}, @code{brace-list-intro}, ++@code{statement-block-intro}, @code{statement-case-intro}, ++@code{arglist-intro}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-multi-inher ++@findex lineup-multi-inher (c-) ++Line up the classes in C++ multiple inheritance clauses and member ++initializers under each other. E.g: ++ ++@example ++@group ++Foo::Foo (int a, int b): ++ Cyphr (a), ++ Bar (b) @hereFn{c-lineup-multi-inher} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++class Foo ++ : public Cyphr, ++ public Bar @hereFn{c-lineup-multi-inher} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++Foo::Foo (int a, int b) ++ : Cyphr (a) ++ , Bar (b) @hereFn{c-lineup-multi-inher} ++@end group ++@end example ++ ++@workswith @code{inher-cont}, @code{member-init-cont}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-java-inher ++@findex lineup-java-inher (c-) ++Line up Java implements and extends declarations. If class names ++follow on the same line as the @samp{implements}/@samp{extends} ++keyword, they are lined up under each other. Otherwise, they are ++indented by adding @code{c-basic-offset} to the column of the keyword. ++E.g: ++ ++@example ++@group ++class Foo ++ extends ++ Bar @hereFn{c-lineup-java-inher} ++ @sssTBasicOffset{} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++class Foo ++ extends Cyphr, ++ Bar @hereFn{c-lineup-java-inher} ++@end group ++@end example ++ ++@workswith @code{inher-cont}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-java-throws ++@findex lineup-java-throws (c-) ++Line up Java throws declarations. If exception names follow on the ++same line as the throws keyword, they are lined up under each other. ++Otherwise, they are indented by adding @code{c-basic-offset} to the ++column of the @samp{throws} keyword. The @samp{throws} keyword itself ++is also indented by @code{c-basic-offset} from the function declaration ++start if it doesn't hang. E.g: ++ ++@example ++@group ++int foo() ++ throws @hereFn{c-lineup-java-throws} ++ Bar @hereFn{c-lineup-java-throws} ++@sssTsssTBasicOffset{} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++int foo() throws Cyphr, ++ Bar, @hereFn{c-lineup-java-throws} ++ Vlod @hereFn{c-lineup-java-throws} ++@end group ++@end example ++ ++@workswith @code{func-decl-cont}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-template-args ++@findex lineup-template-args (c-) ++Line up the arguments of a template argument list under each other, but ++only in the case where the first argument is on the same line as the ++opening @samp{<}. ++ ++To allow this function to be used in a list expression, @code{nil} is ++returned if there's no template argument on the first line. ++ ++@workswith @code{template-args-cont}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-ObjC-method-call ++@findex lineup-ObjC-method-call (c-) ++For Objective-C code, line up selector args as Emacs Lisp mode does ++with function args: go to the position right after the message receiver, ++and if you are at the end of the line, indent the current line ++c-basic-offset columns from the opening bracket; otherwise you are ++looking at the first character of the first method call argument, so ++lineup the current line with it. ++ ++@workswith @code{objc-method-call-cont}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-ObjC-method-args ++@findex lineup-ObjC-method-args (c-) ++For Objective-C code, line up the colons that separate args. The colon ++on the current line is aligned with the one on the first line. ++ ++@workswith @code{objc-method-args-cont}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-ObjC-method-args-2 ++@findex lineup-ObjC-method-args-2 (c-) ++Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on ++the current line with the colon on the previous line. ++ ++@workswith @code{objc-method-args-cont}. ++@end defun ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions ++@comment node-name, next, previous, up ++@subsection Operator Line-Up Functions ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The line-up functions here calculate the indentation for lines which ++start with an operator, by lining it up with something on the previous ++line. ++ ++@defun c-lineup-argcont ++@findex lineup-argcont (c-) ++Line up a continued argument. E.g: ++ ++@example ++@group ++foo (xyz, aaa + bbb + ccc ++ + ddd + eee + fff); @hereFn{c-lineup-argcont} ++@end group ++@end example ++ ++Only continuation lines like this are touched, @code{nil} is returned on ++lines which are the start of an argument. ++ ++Within a gcc @code{asm} block, @code{:} is recognized as an argument ++separator, but of course only between operand specifications, not in the ++expressions for the operands. ++ ++@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-arglist-operators ++@findex lineup-arglist-operators (c-) ++Line up lines starting with an infix operator under the open paren. ++Return @code{nil} on lines that don't start with an operator, to leave ++those cases to other line-up functions. Example: ++ ++@example ++@group ++if ( x < 10 ++ || at_limit (x, @hereFn{c-lineup-arglist-operators} ++ list) @hereFn{c-lineup-arglist-operators@r{ returns nil}} ++ ) ++@end group ++@end example ++ ++Since this function doesn't do anything for lines without an infix ++operator you typically want to use it together with some other lineup ++settings, e.g. as follows (the @code{arglist-close} setting is just a ++suggestion to get a consistent style): ++ ++@example ++(c-set-offset 'arglist-cont ++ '(c-lineup-arglist-operators 0)) ++(c-set-offset 'arglist-cont-nonempty ++ '(c-lineup-arglist-operators c-lineup-arglist)) ++(c-set-offset 'arglist-close ++ '(c-lineup-arglist-close-under-paren)) ++@end example ++ ++@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-assignments ++@findex lineup-assignments (c-) ++Line up the current line after the assignment operator on the first line ++in the statement. If there isn't any, return nil to allow stacking with ++other line-up functions. If the current line contains an assignment ++operator too, try to align it with the first one. ++ ++@workswith @code{topmost-intro-cont}, @code{statement-cont}, ++@code{arglist-cont}, @code{arglist-cont-nonempty}. ++ ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-math ++@findex lineup-math (c-) ++Like @code{c-lineup-assignments} but indent with @code{c-basic-offset} ++if no assignment operator was found on the first line. I.e. this ++function is the same as specifying a list @code{(c-lineup-assignments +++)}. It's provided for compatibility with old configurations. ++ ++@workswith @code{topmost-intro-cont}, @code{statement-cont}, ++@code{arglist-cont}, @code{arglist-cont-nonempty}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-cascaded-calls ++@findex lineup-cascaded-calls (c-) ++Line up ``cascaded calls'' under each other. If the line begins with ++@code{->} or @code{.} and the preceding line ends with one or more ++function calls preceded by the same token, then the arrow is lined up ++with the first of those tokens. E.g: ++ ++@example ++@group ++r = proc->add(17)->add(18) ++ ->add(19) + @hereFn{c-lineup-cascaded-calls} ++ offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}} ++@end group ++@end example ++ ++In any other situation @code{nil} is returned to allow use in list ++expressions. ++ ++@workswith @code{topmost-intro-cont}, @code{statement-cont}, ++@code{arglist-cont}, @code{arglist-cont-nonempty}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-streamop ++@findex lineup-streamop (c-) ++Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). ++ ++@workswith @code{stream-op}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-string-cont ++@findex lineup-string-cont (c-) ++Line up a continued string under the one it continues. A continued ++string in this sense is where a string literal follows directly after ++another one. E.g: ++ ++@example ++@group ++result = prefix + "A message " ++ "string."; @hereFn{c-lineup-string-cont} ++@end group ++@end example ++ ++@code{nil} is returned in other situations, to allow stacking with other ++lineup functions. ++ ++@workswith @code{topmost-intro-cont}, @code{statement-cont}, ++@code{arglist-cont}, @code{arglist-cont-nonempty}. ++@end defun ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions ++@comment node-name, next, previous, up ++@subsection Comment Line-Up Functions ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The lineup functions here calculate the indentation for several types ++of comment structure. ++ ++@defun c-lineup-C-comments ++@findex lineup-C-comments (c-) ++Line up C block comment continuation lines. Various heuristics are used ++to handle most of the common comment styles. Some examples: ++ ++@example ++@group ++/* /** /* ++ * text * text text ++ */ */ */ ++@end group ++@end example ++ ++@example ++@group ++/* text /* /** ++ text ** text ** text ++*/ */ */ ++@end group ++@end example ++ ++@example ++@group ++/************************************************** ++ * text ++ *************************************************/ ++@end group ++@end example ++ ++@vindex comment-start-skip ++@example ++@group ++/************************************************** ++ Free form text comments: ++ In comments with a long delimiter line at the ++ start, the indentation is kept unchanged for lines ++ that start with an empty comment line prefix. The ++ delimiter line is whatever matches the ++ @code{comment-start-skip} regexp. ++**************************************************/ ++@end group ++@end example ++ ++The style variable @code{c-comment-prefix-regexp} is used to recognize ++the comment line prefix, e.g. the @samp{*} that usually starts every ++line inside a comment. ++ ++@workswith The @code{c} syntactic symbol. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-comment ++@findex lineup-comment (c-) ++Line up a comment-only line according to the style variable ++@code{c-comment-only-line-offset}. If the comment is lined up with a ++comment starter on the previous line, that alignment is preserved. ++ ++@defopt c-comment-only-line-offset ++@vindex comment-only-line-offset (c-) ++This style variable specifies the extra offset for the line. It can ++contain an integer or a cons cell of the form ++ ++@example ++(@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}}) ++@end example ++ ++@noindent ++where @var{non-anchored-offset} is the amount of offset given to ++non-column-zero anchored lines, and @var{anchored-offset} is the amount ++of offset to give column-zero anchored lines. Just an integer as value ++is equivalent to @code{(@r{@var{value}} . -1000)}. ++@end defopt ++ ++@workswith @code{comment-intro}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-knr-region-comment ++@findex lineup-knr-region-comment (c-) ++Line up a comment in the ``K&R region'' with the declaration. That is ++the region between the function or class header and the beginning of the ++block. E.g: ++ ++@example ++@group ++int main() ++/* Called at startup. */ @hereFn{c-lineup-knr-region-comment} ++@{ ++ return 0; ++@} ++@end group ++@end example ++ ++Return @code{nil} if called in any other situation, to be useful in list ++expressions. ++ ++@workswith @code{comment-intro}. ++@end defun ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Misc Line-Up, , Comment Line-Up, Line-Up Functions ++@comment node-name, next, previous, up ++@subsection Miscellaneous Line-Up Functions ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The line-up functions here are the odds and ends which didn't fit into ++any earlier category. ++ ++@defun c-lineup-dont-change ++@findex lineup-dont-change (c-) ++This lineup function makes the line stay at whatever indentation it ++already has; think of it as an identity function for lineups. ++ ++@workswith Any syntactic symbol. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-cpp-define ++@findex lineup-cpp-define (c-) ++Line up macro continuation lines according to the indentation of the ++construct preceding the macro. E.g: ++ ++@example ++@group ++const char msg[] = @hereFn{@r{The beginning of the preceding construct.}} ++ \"Some text.\"; ++ ++#define X(A, B) \ ++do @{ \ @hereFn{c-lineup-cpp-define} ++ printf (A, B); \ ++@} while (0) ++@end group ++@end example ++ ++@noindent ++and: ++ ++@example ++@group ++int dribble() @{ ++ if (!running) @hereFn{@r{The beginning of the preceding construct.}} ++ error(\"Not running!\"); ++ ++#define X(A, B) \ ++ do @{ \ @hereFn{c-lineup-cpp-define} ++ printf (A, B); \ ++ @} while (0) ++@end group ++@end example ++ ++If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the ++function returns the relative indentation to the macro start line to ++allow accumulation with other offsets. E.g. in the following cases, ++@code{cpp-define-intro} is combined with the ++@code{statement-block-intro} that comes from the @samp{do @{} that hangs ++on the @samp{#define} line: ++ ++@example ++@group ++const char msg[] = ++ \"Some text.\"; ++ ++#define X(A, B) do @{ \ ++ printf (A, B); \ @hereFn{c-lineup-cpp-define} ++ this->refs++; \ ++@} while (0) @hereFn{c-lineup-cpp-define} ++@end group ++@end example ++ ++@noindent ++and: ++ ++@example ++@group ++int dribble() @{ ++ if (!running) ++ error(\"Not running!\"); ++ ++#define X(A, B) do @{ \ ++ printf (A, B); \ @hereFn{c-lineup-cpp-define} ++ this->refs++; \ ++ @} while (0) @hereFn{c-lineup-cpp-define} ++@end group ++@end example ++ ++The relative indentation returned by @code{c-lineup-cpp-define} is zero ++and two, respectively, on the two lines in each of these examples. They ++are then added to the two column indentation that ++@code{statement-block-intro} gives in both cases here. ++ ++If the relative indentation is zero, then @code{nil} is returned ++instead. That is useful in a list expression to specify the default ++indentation on the top level. ++ ++If @code{c-syntactic-indentation-in-macros} is @code{nil} then this ++function keeps the current indentation, except for empty lines (ignoring ++the ending backslash) where it takes the indentation from the closest ++preceding nonempty line in the macro. If there's no such line in the ++macro then the indentation is taken from the construct preceding it, as ++described above. ++ ++@workswith @code{cpp-define-intro}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-gcc-asm-reg ++@findex lineup-gcc-asm-reg (c-) ++Line up a gcc asm register under one on a previous line. ++ ++@example ++@group ++ asm ("foo %1, %0\n" ++ "bar %0, %1" ++ : "=r" (w), ++ "=r" (x) ++ : "0" (y), ++ "1" (z)); ++@end group ++@end example ++ ++The @samp{x} line is aligned to the text after the @samp{:} on the ++@samp{w} line, and similarly @samp{z} under @samp{y}. ++ ++This is done only in an @samp{asm} or @samp{__asm__} block, and only to ++those lines mentioned. Anywhere else @code{nil} is returned. The usual ++arrangement is to have this routine as an extra feature at the start of ++arglist lineups, e.g. ++ ++@example ++(c-lineup-gcc-asm-reg c-lineup-arglist) ++@end example ++ ++@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. ++@end defun ++ ++@comment ------------------------------------------------------------ ++ ++@defun c-lineup-topmost-intro-cont ++@findex lineup-topmost-intro-cont (c-) ++Line up declaration continuation lines zero or one indentation ++step@footnote{This function is mainly provided to mimic the behavior of ++CC Mode 5.28 and earlier where this case wasn't handled consistently so ++that those lines could be analyzed as either topmost-intro-cont or ++statement-cont. It's used for @code{topmost-intro-cont} by default, but ++you might consider using @code{+} instead.}. For lines preceding a ++definition, zero is used. For other lines, @code{c-basic-offset} is ++added to the indentation. E.g: ++ ++@example ++@group ++int ++neg (int i) @hereFn{c-lineup-topmost-intro-cont} ++@{ ++ return -i; ++@} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++struct ++larch @hereFn{c-lineup-topmost-intro-cont} ++@{ ++ double height; ++@} ++ the_larch, @hereFn{c-lineup-topmost-intro-cont} ++ another_larch; @hereFn{c-lineup-topmost-intro-cont} ++@sssTBasicOffset{} ++@end group ++@end example ++ ++@noindent ++and ++ ++@example ++@group ++struct larch ++the_larch, @hereFn{c-lineup-topmost-intro-cont} ++ another_larch; @hereFn{c-lineup-topmost-intro-cont} ++@end group ++@end example ++ ++@workswith @code{topmost-intro-cont}. ++@end defun ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation ++@comment node-name, next, previous, up ++@section Custom Line-Up Functions ++@cindex customization, indentation functions ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The most flexible way to customize indentation is by writing custom ++line-up functions, and associating them with specific syntactic ++symbols (@pxref{c-offsets-alist}). Depending on the effect you want, ++it might be better to write a @code{c-special-indent-hook} function ++rather than a line-up function (@pxref{Other Indentation}). ++ ++@ccmode{} comes with an extensive set of predefined line-up functions, ++not all of which are used by the default styles. So there's a good ++chance the function you want already exists. @xref{Line-Up ++Functions}, for a list of them. If you write your own line-up ++function, it's probably a good idea to start working from one of these ++predefined functions, which can be found in the file ++@file{cc-align.el}. If you have written a line-up function that you ++think is generally useful, you're very welcome to contribute it; ++please contact @email{bug-cc-mode@@gnu.org}. ++ ++ Line-up functions are passed a single argument, the syntactic ++element (see below). The return value is a @code{c-offsets-alist} ++offset specification: for example, an integer, a symbol such as ++@code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful ++when the offset specification for a syntactic element is a list ++containing the line-up function (@pxref{c-offsets-alist}).}, or even ++another line-up function. Full details of these are in ++@ref{c-offsets-alist}. ++ ++Line-up functions must not move point or change the content of the ++buffer (except temporarily). They are however allowed to do ++@dfn{hidden buffer changes}, i.e. setting text properties for caching ++purposes etc. Buffer undo recording is disabled while they run. ++ ++The syntactic element passed as the parameter to a line-up function is ++a cons cell of the form ++ ++@example ++(@r{@var{syntactic-symbol}} . @r{@var{anchor-position}}) ++@end example ++ ++@noindent ++@c FIXME!!! The following sentence might be better omitted, since the ++@c information is in the cross reference "Syntactic Analysis". 2005/10/2. ++where @var{syntactic-symbol} is the symbol that the function was ++called for, and @var{anchor-position} is the anchor position (if any) ++for the construct that triggered the syntactic symbol ++(@pxref{Syntactic Analysis}). This cons cell is how the syntactic ++element of a line used to be represented in @ccmode{} 5.28 and ++earlier. Line-up functions are still passed this cons cell, so as to ++preserve compatibility with older configurations. In the future, we ++may decide to convert to using the full list format---you can prepare ++your setup for this by using the access functions ++(@code{c-langelem-sym}, etc.) described below. ++ ++@vindex c-syntactic-element ++@vindex syntactic-element (c-) ++@vindex c-syntactic-context ++@vindex syntactic-context (c-) ++Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more ++info in the syntactic element - typically other positions that can be ++interesting besides the anchor position. That info can't be accessed ++through the passed argument, which is a cons cell. Instead, you can ++get this information from the variable @code{c-syntactic-element}, ++which is dynamically bound to the complete syntactic element. The ++variable @code{c-syntactic-context} might also be useful - it gets ++dynamically bound to the complete syntactic context. @xref{Custom ++Braces}. ++ ++@ccmode{} provides a few functions to access parts of syntactic ++elements in a more abstract way. Besides making the code easier to ++read, they also hide the difference between the old cons cell form ++used in the line-up function argument and the new list form used in ++@code{c-syntactic-element} and everywhere else. The functions are: ++ ++@defun c-langelem-sym langelem ++@findex langelem-sym (c-) ++Return the syntactic symbol in @var{langelem}. ++@end defun ++ ++@defun c-langelem-pos langelem ++@findex langelem-pos (c-) ++Return the anchor position in @var{langelem}, or nil if there is none. ++@end defun ++ ++@defun c-langelem-col langelem &optional preserve-point ++@findex langelem-col (c-) ++Return the column of the anchor position in @var{langelem}. Also move ++the point to that position unless @var{preserve-point} is ++non-@code{nil}. ++@end defun ++ ++@defun c-langelem-2nd-pos langelem ++@findex langelem-2nd-pos (c-) ++Return the secondary position in @var{langelem}, or @code{nil} if there ++is none. ++ ++Note that the return value of this function is always @code{nil} if ++@var{langelem} is in the old cons cell form. Thus this function is ++only meaningful when used on syntactic elements taken from ++@code{c-syntactic-element} or @code{c-syntactic-context}. ++@end defun ++ ++Custom line-up functions can be as simple or as complex as you like, and ++any syntactic symbol that appears in @code{c-offsets-alist} can have a ++custom line-up function associated with it. ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Other Indentation, , Custom Line-Up, Customizing Indentation ++@comment node-name, next, previous, up ++@section Other Special Indentations ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Here are the remaining odds and ends regarding indentation: ++ ++@defopt c-label-minimum-indentation ++@vindex label-minimum-indentation (c-) ++In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is ++imposed on lines inside code blocks. This minimum indentation is ++controlled by this style variable. The default value is 1. ++ ++@findex c-gnu-impose-minimum ++@findex gnu-impose-minimum (c-) ++It's the function @code{c-gnu-impose-minimum} that enforces this minimum ++indentation. It must be present on @code{c-special-indent-hook} to ++work. ++@end defopt ++ ++@defopt c-special-indent-hook ++@vindex special-indent-hook (c-) ++This style variable is a standard hook variable that is called after ++every line is indented by @ccmode{}. It is called only if ++@code{c-syntactic-indentation} is non-@code{nil} (which it is by ++default (@pxref{Indentation Engine Basics})). You can put a function ++on this hook to do any special indentation or ad hoc line adjustments ++your style dictates, such as adding extra indentation to constructors ++or destructor declarations in a class definition, etc. Sometimes it ++is better to write a custom Line-up Function instead (@pxref{Custom ++Line-Up}). ++ ++When the indentation engine calls this hook, the variable ++@code{c-syntactic-context} is bound to the current syntactic context ++(i.e. what you would get by typing @kbd{C-c C-s} on the source line. ++@xref{Custom Braces}.). Note that you should not change point or mark ++inside a @code{c-special-indent-hook} function, i.e. you'll probably ++want to wrap your function in a @code{save-excursion}@footnote{The ++numerical value returned by @code{point} will change if you change the ++indentation of the line within a @code{save-excursion} form, but point ++itself will still be over the same piece of text.}. ++ ++Setting @code{c-special-indent-hook} in style definitions is handled ++slightly differently from other variables---A style can only add ++functions to this hook, not remove them. @xref{Style Variables}. ++@end defopt ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Custom Macros, Odds and Ends, Customizing Indentation, Top ++@comment node-name, next, previous, up ++@chapter Customizing Macros ++@cindex macros ++@cindex preprocessor directives ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Normally, the lines in a multi-line macro are indented relative to ++each other as though they were code. You can suppress this behavior ++by setting the following user option: ++ ++@defopt c-syntactic-indentation-in-macros ++@vindex syntactic-indentation-in-macros (c-) ++Enable syntactic analysis inside macros, which is the default. If this ++is @code{nil}, all lines inside macro definitions are analyzed as ++@code{cpp-macro-cont}. ++@end defopt ++ ++@ccmode{} provides some tools to help keep the line continuation ++backslashes in macros neat and tidy. Their precise action is ++customized with these variables: ++ ++@defopt c-backslash-column ++@vindex backslash-column (c-) ++@defoptx c-backslash-max-column ++@vindex backslash-max-column (c-) ++These variables control the alignment columns for line continuation ++backslashes in multiline macros. They are used by the functions that ++automatically insert or align such backslashes, ++e.g. @code{c-backslash-region} and @code{c-context-line-break}. ++ ++@code{c-backslash-column} specifies the minimum column for the ++backslashes. If any line in the macro goes past this column, then the ++next tab stop (i.e. next multiple of @code{tab-width}) in that line is ++used as the alignment column for all the backslashes, so that they ++remain in a single column. However, if any lines go past ++@code{c-backslash-max-column} then the backslashes in the rest of the ++macro will be kept at that column, so that the lines which are too ++long ``stick out'' instead. ++ ++Don't ever set these variables to @code{nil}. If you want to disable ++the automatic alignment of backslashes, use ++@code{c-auto-align-backslashes}. ++@end defopt ++ ++@defopt c-auto-align-backslashes ++@vindex auto-align-backslashes (c-) ++Align automatically inserted line continuation backslashes if ++non-@code{nil}. When line continuation backslashes are inserted ++automatically for line breaks in multiline macros, e.g. by ++@code{c-context-line-break}, they are aligned with the other ++backslashes in the same macro if this flag is set. ++ ++If @code{c-auto-align-backslashes} is @code{nil}, automatically ++inserted backslashes are preceded by a single space, and backslashes ++get aligned only when you explicitly invoke the command ++@code{c-backslash-region} (@kbd{C-c C-\}). ++@end defopt ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Odds and Ends, Sample .emacs File, Custom Macros, Top ++@comment node-name, next, previous, up ++@chapter Odds and Ends ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++The stuff that didn't fit in anywhere else is documented here. ++ ++@defopt c-require-final-newline ++@vindex require-final-newline (c-) ++Controls whether a final newline is enforced when the file is saved. ++The value is an association list that for each language mode specifies ++the value to give to @code{require-final-newline} (@pxref{Saving ++Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a ++language isn't present on the association list, CC Mode won't touch ++@code{require-final-newline} in buffers for that language. ++ ++The default is to set @code{require-final-newline} to @code{t} in the ++languages that mandate that source files should end with newlines. ++These are C, C++ and Objective-C. ++@end defopt ++ ++@defopt c-echo-syntactic-information-p ++@vindex echo-syntactic-information-p (c-) ++If non-@code{nil}, the syntactic analysis for the current line is shown ++in the echo area when it's indented (unless ++@code{c-syntactic-indentation} is @code{nil}). That's useful when ++finding out which syntactic symbols to modify to get the indentation you ++want. ++@end defopt ++ ++@defopt c-report-syntactic-errors ++@vindex report-syntactic-errors (c-) ++If non-@code{nil}, certain syntactic errors are reported with a ding and ++a message, for example when an @code{else} is indented for which there ++is no corresponding @code{if}. ++ ++Note however that @ccmode{} doesn't make any special effort to check for ++syntactic errors; that's the job of the compiler. The reason it can ++report cases like the one above is that it can't find the correct ++anchoring position to indent the line in that case. ++@end defopt ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Sample .emacs File, Performance Issues, Odds and Ends, Top ++@comment node-name, next, previous, up ++@appendix Sample .emacs File ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Here's a sample .emacs file fragment that might help you along the way. ++Just copy this region and paste it into your .emacs file. You might want ++to change some of the actual values. ++ ++@verbatim ++;; Make a non-standard key binding. We can put this in ++;; c-mode-base-map because c-mode-map, c++-mode-map, and so on, ++;; inherit from it. ++(defun my-c-initialization-hook () ++ (define-key c-mode-base-map "\C-m" 'c-context-line-break)) ++(add-hook 'c-initialization-hook 'my-c-initialization-hook) ++ ++;; offset customizations not in my-c-style ++;; This will take precedence over any setting of the syntactic symbol ++;; made by a style. ++(setq c-offsets-alist '((member-init-intro . ++))) ++ ++;; Create my personal style. ++(defconst my-c-style ++ '((c-tab-always-indent . t) ++ (c-comment-only-line-offset . 4) ++ (c-hanging-braces-alist . ((substatement-open after) ++ (brace-list-open))) ++ (c-hanging-colons-alist . ((member-init-intro before) ++ (inher-intro) ++ (case-label after) ++ (label after) ++ (access-label after))) ++ (c-cleanup-list . (scope-operator ++ empty-defun-braces ++ defun-close-semi)) ++ (c-offsets-alist . ((arglist-close . c-lineup-arglist) ++ (substatement-open . 0) ++ (case-label . 4) ++ (block-open . 0) ++ (knr-argdecl-intro . -))) ++ (c-echo-syntactic-information-p . t)) ++ "My C Programming Style") ++(c-add-style "PERSONAL" my-c-style) ++ ++;; Customizations for all modes in CC Mode. ++(defun my-c-mode-common-hook () ++ ;; set my personal style for the current buffer ++ (c-set-style "PERSONAL") ++ ;; other customizations ++ (setq tab-width 8 ++ ;; this will make sure spaces are used instead of tabs ++ indent-tabs-mode nil) ++ ;; we like auto-newline, but not hungry-delete ++ (c-toggle-auto-newline 1)) ++(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) ++@end verbatim ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top ++@comment node-name, next, previous, up ++@chapter Performance Issues ++@cindex performance ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here. ++ ++C and its derivative languages are highly complex creatures. Often, ++ambiguous code situations arise that require @ccmode{} to scan large ++portions of the buffer to determine syntactic context. Such ++pathological code can cause @ccmode{} to perform fairly badly. This ++section gives some insight in how @ccmode{} operates, how that interacts ++with some coding styles, and what you can use to improve performance. ++ ++The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take ++more than a fraction of a second) in any interactive operation. ++I.e. it's tuned to limit the maximum response time in single operations, ++which is sometimes at the expense of batch-like operations like ++reindenting whole blocks. If you find that @ccmode{} gradually gets ++slower and slower in certain situations, perhaps as the file grows in ++size or as the macro or comment you're editing gets bigger, then chances ++are that something isn't working right. You should consider reporting ++it, unless it's something that's mentioned in this section. ++ ++Because @ccmode{} has to scan the buffer backwards from the current ++insertion point, and because C's syntax is fairly difficult to parse in ++the backwards direction, @ccmode{} often tries to find the nearest ++position higher up in the buffer from which to begin a forward scan ++(it's typically an opening or closing parenthesis of some kind). The ++farther this position is from the current insertion point, the slower it ++gets. ++ ++@findex beginning-of-defun ++In earlier versions of @ccmode{}, we used to recommend putting the ++opening brace of a top-level construct@footnote{E.g. a function in C, ++or outermost class definition in C++ or Java.} into the leftmost ++column. Earlier still, this used to be a rigid Emacs constraint, as ++embodied in the @code{beginning-of-defun} function. @ccmode now ++caches syntactic information much better, so that the delay caused by ++searching for such a brace when it's not in column 0 is minimal, ++except perhaps when you've just moved a long way inside the file. ++ ++@findex defun-prompt-regexp ++@vindex c-Java-defun-prompt-regexp ++@vindex Java-defun-prompt-regexp (c-) ++A special note about @code{defun-prompt-regexp} in Java mode: The common ++style is to hang the opening braces of functions and classes on the ++right side of the line, and that doesn't work well with the Emacs ++approach. @ccmode{} comes with a constant ++@code{c-Java-defun-prompt-regexp} which tries to define a regular ++expression usable for this style, but there are problems with it. In ++some cases it can cause @code{beginning-of-defun} to hang@footnote{This ++has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, ++it is not used by default, but if you feel adventurous, you can set ++@code{defun-prompt-regexp} to it in your mode hook. In any event, ++setting and relying on @code{defun-prompt-regexp} will definitely slow ++things down because (X)Emacs will be doing regular expression searches a ++lot, so you'll probably be taking a hit either way! ++ ++@ccmode{} maintains a cache of the opening parentheses of the blocks ++surrounding the point, and it adapts that cache as the point is moved ++around. That means that in bad cases it can take noticeable time to ++indent a line in a new surrounding, but after that it gets fast as long ++as the point isn't moved far off. The farther the point is moved, the ++less useful is the cache. Since editing typically is done in ``chunks'' ++rather than on single lines far apart from each other, the cache ++typically gives good performance even when the code doesn't fit the ++Emacs approach to finding the defun starts. ++ ++@vindex c-enable-xemacs-performance-kludge-p ++@vindex enable-xemacs-performance-kludge-p (c-) ++XEmacs users can set the variable ++@code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This ++tells @ccmode{} to use XEmacs-specific built-in functions which, in some ++circumstances, can locate the top-most opening brace much more quickly than ++@code{beginning-of-defun}. Preliminary testing has shown that for ++styles where these braces are hung (e.g. most JDK-derived Java styles), ++this hack can improve performance of the core syntax parsing routines ++from 3 to 60 times. However, for styles which @emph{do} conform to ++Emacs' recommended style of putting top-level braces in column zero, ++this hack can degrade performance by about as much. Thus this variable ++is set to @code{nil} by default, since the Emacs-friendly styles should ++be more common (and encouraged!). Note that this variable has no effect ++in Emacs since the necessary built-in functions don't exist (in Emacs ++22.1 as of this writing in February 2007). ++ ++Text properties are used to speed up skipping over syntactic whitespace, ++i.e. comments and preprocessor directives. Indenting a line after a ++huge macro definition can be slow the first time, but after that the ++text properties are in place and it should be fast (even after you've ++edited other parts of the file and then moved back). ++ ++Font locking can be a CPU hog, especially the font locking done on ++decoration level 3 which tries to be very accurate. Note that that ++level is designed to be used with a font lock support mode that only ++fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time ++Lock mode, so make sure you use one of them. Fontification of a whole ++buffer with some thousand lines can often take over a minute. That is ++a known weakness; the idea is that it never should happen. ++ ++The most effective way to speed up font locking is to reduce the ++decoration level to 2 by setting @code{font-lock-maximum-decoration} ++appropriately. That level is designed to be as pretty as possible ++without sacrificing performance. @xref{Font Locking Preliminaries}, for ++more info. ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Limitations and Known Bugs, FAQ, Performance Issues, Top ++@comment node-name, next, previous, up ++@chapter Limitations and Known Bugs ++@cindex limitations ++@cindex bugs ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@itemize @bullet ++@item ++@ccmode{} doesn't support trigraphs. (These are character sequences ++such as @samp{??(}, which represents @samp{[}. They date from a time ++when some character sets didn't have all the characters that C needs, ++and are now utterly obsolete.) ++ ++@item ++There is no way to apply auto newline settings (@pxref{Auto-newlines}) ++on already typed lines. That's only a feature to ease interactive ++editing. ++ ++To generalize this issue a bit: @ccmode{} is not intended to be used as ++a reformatter for old code in some more or less batch-like way. With ++the exception of some functions like @code{c-indent-region}, it's only ++geared to be used interactively to edit new code. There's currently no ++intention to change this goal. ++ ++If you want to reformat old code, you're probably better off using some ++other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent' ++Manual}, which has more powerful reformatting capabilities than ++@ccmode{}. ++ ++@item ++The support for C++ templates (in angle brackets) is not yet complete. ++When a non-nested template is used in a declaration, @ccmode{} indents ++it and font-locks it OK. Templates used in expressions, and nested ++templates do not fare so well. Sometimes a workaround is to refontify ++the expression after typing the closing @samp{>}. ++ ++@item ++In a @dfn{k&r region} (the part of an old-fashioned C function ++declaration which specifies the types of its parameters, coming ++between the parameter list and the opening brace), there should be at ++most 20 top-level parenthesis and bracket pairs. This limit has been ++imposed for performance reasons. If it is violated, the source file ++might be incorrectly indented or fontified. ++ ++@item ++On loading @ccmode{}, sometimes this error message appears: ++ ++@example ++File mode specification error: (void-variable c-font-lock-keywords-3) ++@end example ++ ++This is due to a bug in the function @code{eval-after-load} in some ++versions of (X)Emacs. It can manifest itself when there is a symbolic ++link in the path of the directory which contains (X)Emacs. As a ++workaround, put the following into your @file{.emacs} file, fairly ++early on: ++ ++@example ++(defun my-load-cc-fonts () ++ (require "cc-fonts")) ++(add-hook 'c-initialization-hook 'my-load-cc-fonts) ++@end example ++@end itemize ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node FAQ, Updating CC Mode, Limitations and Known Bugs, Top ++@comment node-name, next, previous, up ++@appendix Frequently Asked Questions ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@itemize @bullet ++@item ++@emph{How can I change the indent level from 4 spaces to 2 spaces?} ++ ++Set the variable @code{c-basic-offset}. @xref{Getting Started}. ++ ++@item ++@kindex RET ++@kindex C-j ++@emph{Why doesn't the @kbd{RET} key indent the new line?} ++ ++Emacs' convention is that @kbd{RET} just adds a newline, and that ++@kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this ++too by adding this to your @code{c-initialization-hook}: ++ ++@example ++(define-key c-mode-base-map "\C-m" 'c-context-line-break) ++@end example ++ ++@xref{Getting Started}. This is a very common question. If you want ++this to be the default behavior, don't lobby us, lobby RMS! @t{:-)} ++ ++@item ++@emph{How do I stop my code jumping all over the place when I type?} ++ ++Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting ++Started}. ++ ++@item ++@kindex C-x h ++@kindex C-M-\ ++@emph{How do I reindent the whole file?} ++ ++Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit ++@kbd{C-M-\}. @xref{Indentation Commands}. ++ ++@item ++@kindex C-M-q ++@kindex C-M-u ++@emph{How do I reindent the current block?} ++ ++First move to the brace which opens the block with @kbd{C-M-u}, then ++reindent that expression with @kbd{C-M-q}. @xref{Indentation ++Commands}. ++ ++@item ++@emph{I put @code{(c-set-offset 'substatement-open 0)} in my ++@file{.emacs} file but I get an error saying that @code{c-set-offset}'s ++function definition is void. What's wrong?} ++ ++This means that @ccmode{} hasn't yet been loaded into your Emacs ++session by the time the @code{c-set-offset} call is reached, most ++likely because @ccmode{} is being autoloaded. Instead of putting the ++@code{c-set-offset} line in your top-level @file{.emacs} file, put it ++in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply ++modify @code{c-offsets-alist} directly: ++ ++@example ++(setq c-offsets-alist '((substatement-open . 0))) ++@end example ++ ++@item ++@cindex open paren in column zero ++@emph{I have an open paren character at column zero inside a comment or ++multiline string literal, and it causes the fontification and/or ++indentation to go haywire. What gives?} ++ ++It's due to the ad-hoc rule in (X)Emacs that such open parens always ++start defuns (which translates to functions, classes, namespaces or any ++other top-level block constructs in the @ccmode{} languages). ++@ifset XEMACS ++@xref{Defuns,,, xemacs, XEmacs User's Manual}, for details. ++@end ifset ++@ifclear XEMACS ++@xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details ++(@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual). ++@end ifclear ++ ++This heuristic is built into the core syntax analysis routines in ++(X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs ++21.1 it became possible to turn it off@footnote{Using the variable ++@code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so ++there since it's got its own system to keep track of blocks. ++ ++@end itemize ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top ++@comment node-name, next, previous, up ++@appendix Getting the Latest CC Mode Release ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@ccmode{} has been standard with all versions of Emacs since 19.34 and ++of XEmacs since 19.16. ++ ++@cindex web site ++Due to release schedule skew, it is likely that all of these Emacsen ++have old versions of @ccmode{} and so should be upgraded. Access to the ++@ccmode{} source code, as well as more detailed information on Emacsen ++compatibility, etc. are all available on the web site: ++ ++@quotation ++@uref{http://cc-mode.sourceforge.net/} ++@end quotation ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top ++@comment node-name, next, previous, up ++@appendix Mailing Lists and Submitting Bug Reports ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@kindex C-c C-b ++@findex c-submit-bug-report ++@findex submit-bug-report (c-) ++To report bugs, use the @kbd{C-c C-b} (bound to ++@code{c-submit-bug-report}) command. This provides vital information ++we need to reproduce your problem. Make sure you include a concise, ++but complete code example. Please try to boil your example down to ++just the essential code needed to reproduce the problem, and include ++an exact recipe of steps needed to expose the bug. Be especially sure ++to include any code that appears @emph{before} your bug example, if ++you think it might affect our ability to reproduce it. ++ ++Please try to produce the problem in an Emacs instance without any ++customizations loaded (i.e. start it with the @samp{-q --no-site-file} ++arguments). If it works correctly there, the problem might be caused ++by faulty customizations in either your own or your site ++configuration. In that case, we'd appreciate it if you isolate the ++Emacs Lisp code that triggers the bug and include it in your report. ++ ++@cindex bug report mailing list ++Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can ++also send other questions and suggestions (kudos? @t{;-)} to that ++address. It's a mailing list which you can join or browse an archive ++of; see the web site at @uref{http://cc-mode.sourceforge.net/} for ++further details. ++ ++@cindex announcement mailing list ++If you want to get announcements of new @ccmode{} releases, send the ++word @emph{subscribe} in the body of a message to ++@email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible ++to subscribe from the web site too. Announcements will also be posted ++to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs}, ++@code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++}, ++@code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools}, ++@code{comp.lang.idl}, and @code{comp.lang.awk}. ++@c There is no newsgroup for Pike. :-( ++ ++ ++@node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++ ++@c Removed the tentative node "Mode Initialization" from here, 2005/8/27. ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Command and Function Index, Variable Index, GNU Free Documentation License, Top ++@comment node-name, next, previous, up ++@unnumbered Command and Function Index ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Since most @ccmode{} commands are prepended with the string ++@samp{c-}, each appears under its @code{c-@var{thing}} name and its ++@code{@var{thing} (c-)} name. ++@iftex ++@sp 2 ++@end iftex ++@printindex fn ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Variable Index, Concept and Key Index, Command and Function Index, Top ++@comment node-name, next, previous, up ++@unnumbered Variable Index ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++Since most @ccmode{} variables are prepended with the string ++@samp{c-}, each appears under its @code{c-@var{thing}} name and its ++@code{@var{thing} (c-)} name. ++@iftex ++@sp 2 ++@end iftex ++@printindex vr ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@node Concept and Key Index, , Variable Index, Top ++@comment node-name, next, previous, up ++@unnumbered Concept and Key Index ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@printindex cp ++ ++ ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++@comment Epilogue. ++@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ++ ++@bye ++ ++@ignore ++ arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0 ++@end ignore +diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi +new file mode 100644 +index 0000000..fb1aace +--- /dev/null ++++ b/doc/misc/cl.texi +@@ -0,0 +1,5342 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/cl ++@settitle Common Lisp Extensions ++ ++@copying ++This file documents the GNU Emacs Common Lisp emulation package. ++ ++Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007, ++2008, 2009 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 Emacs ++@direntry ++* CL: (cl). Partial Common Lisp support for Emacs Lisp. ++@end direntry ++ ++@finalout ++ ++@titlepage ++@sp 6 ++@center @titlefont{Common Lisp Extensions} ++@sp 4 ++@center For GNU Emacs Lisp ++@sp 1 ++@center Version 2.02 ++@sp 5 ++@center Dave Gillespie ++@center daveg@@synaptics.com ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top, Overview, (dir), (dir) ++@chapter Introduction ++ ++@noindent ++This document describes a set of Emacs Lisp facilities borrowed from ++Common Lisp. All the facilities are described here in detail. While ++this document does not assume any prior knowledge of Common Lisp, it ++does assume a basic familiarity with Emacs Lisp. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview:: Installation, usage, etc. ++* Program Structure:: Arglists, `eval-when', `defalias' ++* Predicates:: `typep' and `equalp' ++* Control Structure:: `setf', `do', `loop', etc. ++* Macros:: Destructuring, `define-compiler-macro' ++* Declarations:: `proclaim', `declare', etc. ++* Symbols:: Property lists, `gensym' ++* Numbers:: Predicates, functions, random numbers ++* Sequences:: Mapping, functions, searching, sorting ++* Lists:: `caddr', `sublis', `member*', `assoc*', etc. ++* Structures:: `defstruct' ++* Assertions:: `check-type', `assert', `ignore-errors'. ++ ++* Efficiency Concerns:: Hints and techniques ++* Common Lisp Compatibility:: All known differences with Steele ++* Old CL Compatibility:: All known differences with old cl.el ++* Porting Common Lisp:: Hints for porting Common Lisp code ++ ++* GNU Free Documentation License:: The license for this documentation. ++* Function Index:: ++* Variable Index:: ++@end menu ++ ++@node Overview, Program Structure, Top, Top ++@ifnottex ++@chapter Overview ++@end ifnottex ++ ++@noindent ++Common Lisp is a huge language, and Common Lisp systems tend to be ++massive and extremely complex. Emacs Lisp, by contrast, is rather ++minimalist in the choice of Lisp features it offers the programmer. ++As Emacs Lisp programmers have grown in number, and the applications ++they write have grown more ambitious, it has become clear that Emacs ++Lisp could benefit from many of the conveniences of Common Lisp. ++ ++The @dfn{CL} package adds a number of Common Lisp functions and ++control structures to Emacs Lisp. While not a 100% complete ++implementation of Common Lisp, @dfn{CL} adds enough functionality ++to make Emacs Lisp programming significantly more convenient. ++ ++@strong{Please note:} the @dfn{CL} functions are not standard parts of ++the Emacs Lisp name space, so it is legitimate for users to define ++them with other, conflicting meanings. To avoid conflicting with ++those user activities, we have a policy that packages installed in ++Emacs must not load @dfn{CL} at run time. (It is ok for them to load ++@dfn{CL} at compile time only, with @code{eval-when-compile}, and use ++the macros it provides.) If you are writing packages that you plan to ++distribute and invite widespread use for, you might want to observe ++the same rule. ++ ++Some Common Lisp features have been omitted from this package ++for various reasons: ++ ++@itemize @bullet ++@item ++Some features are too complex or bulky relative to their benefit ++to Emacs Lisp programmers. CLOS and Common Lisp streams are fine ++examples of this group. ++ ++@item ++Other features cannot be implemented without modification to the ++Emacs Lisp interpreter itself, such as multiple return values, ++lexical scoping, case-insensitive symbols, and complex numbers. ++The @dfn{CL} package generally makes no attempt to emulate these ++features. ++ ++@item ++Some features conflict with existing things in Emacs Lisp. For ++example, Emacs' @code{assoc} function is incompatible with the ++Common Lisp @code{assoc}. In such cases, this package usually ++adds the suffix @samp{*} to the function name of the Common ++Lisp version of the function (e.g., @code{assoc*}). ++@end itemize ++ ++The package described here was written by Dave Gillespie, ++@file{daveg@@synaptics.com}. It is a total rewrite of the original ++1986 @file{cl.el} package by Cesar Quiroz. Most features of the ++Quiroz package have been retained; any incompatibilities are ++noted in the descriptions below. Care has been taken in this ++version to ensure that each function is defined efficiently, ++concisely, and with minimal impact on the rest of the Emacs ++environment. ++ ++@menu ++* Usage:: How to use the CL package ++* Organization:: The package's five component files ++* Installation:: Compiling and installing CL ++* Naming Conventions:: Notes on CL function names ++@end menu ++ ++@node Usage, Organization, Overview, Overview ++@section Usage ++ ++@noindent ++Lisp code that uses features from the @dfn{CL} package should ++include at the beginning: ++ ++@example ++(require 'cl) ++@end example ++ ++@noindent ++If you want to ensure that the new (Gillespie) version of @dfn{CL} ++is the one that is present, add an additional @code{(require 'cl-19)} ++call: ++ ++@example ++(require 'cl) ++(require 'cl-19) ++@end example ++ ++@noindent ++The second call will fail (with ``@file{cl-19.el} not found'') if ++the old @file{cl.el} package was in use. ++ ++It is safe to arrange to load @dfn{CL} at all times, e.g., ++in your @file{.emacs} file. But it's a good idea, for portability, ++to @code{(require 'cl)} in your code even if you do this. ++ ++@node Organization, Installation, Usage, Overview ++@section Organization ++ ++@noindent ++The Common Lisp package is organized into four files: ++ ++@table @file ++@item cl.el ++This is the ``main'' file, which contains basic functions ++and information about the package. This file is relatively ++compact---about 700 lines. ++ ++@item cl-extra.el ++This file contains the larger, more complex or unusual functions. ++It is kept separate so that packages which only want to use Common ++Lisp fundamentals like the @code{cadr} function won't need to pay ++the overhead of loading the more advanced functions. ++ ++@item cl-seq.el ++This file contains most of the advanced functions for operating ++on sequences or lists, such as @code{delete-if} and @code{assoc*}. ++ ++@item cl-macs.el ++This file contains the features of the packages which are macros ++instead of functions. Macros expand when the caller is compiled, ++not when it is run, so the macros generally only need to be ++present when the byte-compiler is running (or when the macros are ++used in uncompiled code such as a @file{.emacs} file). Most of ++the macros of this package are isolated in @file{cl-macs.el} so ++that they won't take up memory unless you are compiling. ++@end table ++ ++The file @file{cl.el} includes all necessary @code{autoload} ++commands for the functions and macros in the other three files. ++All you have to do is @code{(require 'cl)}, and @file{cl.el} ++will take care of pulling in the other files when they are ++needed. ++ ++There is another file, @file{cl-compat.el}, which defines some ++routines from the older @file{cl.el} package that are no longer ++present in the new package. This includes internal routines ++like @code{setelt} and @code{zip-lists}, deprecated features ++like @code{defkeyword}, and an emulation of the old-style ++multiple-values feature. @xref{Old CL Compatibility}. ++ ++@node Installation, Naming Conventions, Organization, Overview ++@section Installation ++ ++@noindent ++Installation of the @dfn{CL} package is simple: Just put the ++byte-compiled files @file{cl.elc}, @file{cl-extra.elc}, ++@file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc} ++into a directory on your @code{load-path}. ++ ++There are no special requirements to compile this package: ++The files do not have to be loaded before they are compiled, ++nor do they need to be compiled in any particular order. ++ ++You may choose to put the files into your main @file{lisp/} ++directory, replacing the original @file{cl.el} file there. Or, ++you could put them into a directory that comes before @file{lisp/} ++on your @code{load-path} so that the old @file{cl.el} is ++effectively hidden. ++ ++Also, format the @file{cl.texinfo} file and put the resulting ++Info files in the @file{info/} directory or another suitable place. ++ ++You may instead wish to leave this package's components all in ++their own directory, and then add this directory to your ++@code{load-path} and @code{Info-directory-list}. ++Add the directory to the front of the list so the old @dfn{CL} ++package and its documentation are hidden. ++ ++@node Naming Conventions, , Installation, Overview ++@section Naming Conventions ++ ++@noindent ++Except where noted, all functions defined by this package have the ++same names and calling conventions as their Common Lisp counterparts. ++ ++Following is a complete list of functions whose names were changed ++from Common Lisp, usually to avoid conflicts with Emacs. In each ++case, a @samp{*} has been appended to the Common Lisp name to obtain ++the Emacs name: ++ ++@example ++defun* defsubst* defmacro* function* ++member* assoc* rassoc* get* ++remove* delete* mapcar* sort* ++floor* ceiling* truncate* round* ++mod* rem* random* ++@end example ++ ++Internal function and variable names in the package are prefixed ++by @code{cl-}. Here is a complete list of functions @emph{not} ++prefixed by @code{cl-} which were not taken from Common Lisp: ++ ++@example ++floatp-safe lexical-let lexical-let* ++callf callf2 letf letf* ++defsubst* ++@end example ++ ++The following simple functions and macros are defined in @file{cl.el}; ++they do not cause other components like @file{cl-extra} to be loaded. ++ ++@example ++floatp-safe endp ++evenp oddp plusp minusp ++caaar .. cddddr ++list* ldiff rest first .. tenth ++copy-list subst mapcar* [2] ++adjoin [3] acons pairlis pop [4] ++push [4] pushnew [3,4] incf [4] decf [4] ++proclaim declaim ++@end example ++ ++@noindent ++[2] Only for one sequence argument or two list arguments. ++ ++@noindent ++[3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified, ++and @code{:key} is not used. ++ ++@noindent ++[4] Only when @var{place} is a plain variable name. ++ ++@iftex ++@chapno=4 ++@end iftex ++ ++@node Program Structure, Predicates, Overview, Top ++@chapter Program Structure ++ ++@noindent ++This section describes features of the @dfn{CL} package which have to ++do with programs as a whole: advanced argument lists for functions, ++and the @code{eval-when} construct. ++ ++@menu ++* Argument Lists:: `&key', `&aux', `defun*', `defmacro*'. ++* Time of Evaluation:: The `eval-when' construct. ++@end menu ++ ++@iftex ++@secno=1 ++@end iftex ++ ++@node Argument Lists, Time of Evaluation, Program Structure, Program Structure ++@section Argument Lists ++ ++@noindent ++Emacs Lisp's notation for argument lists of functions is a subset of ++the Common Lisp notation. As well as the familiar @code{&optional} ++and @code{&rest} markers, Common Lisp allows you to specify default ++values for optional arguments, and it provides the additional markers ++@code{&key} and @code{&aux}. ++ ++Since argument parsing is built-in to Emacs, there is no way for ++this package to implement Common Lisp argument lists seamlessly. ++Instead, this package defines alternates for several Lisp forms ++which you must use if you need Common Lisp argument lists. ++ ++@defspec defun* name arglist body... ++This form is identical to the regular @code{defun} form, except ++that @var{arglist} is allowed to be a full Common Lisp argument ++list. Also, the function body is enclosed in an implicit block ++called @var{name}; @pxref{Blocks and Exits}. ++@end defspec ++ ++@defspec defsubst* name arglist body... ++This is just like @code{defun*}, except that the function that ++is defined is automatically proclaimed @code{inline}, i.e., ++calls to it may be expanded into in-line code by the byte compiler. ++This is analogous to the @code{defsubst} form; ++@code{defsubst*} uses a different method (compiler macros) which ++works in all version of Emacs, and also generates somewhat more ++efficient inline expansions. In particular, @code{defsubst*} ++arranges for the processing of keyword arguments, default values, ++etc., to be done at compile-time whenever possible. ++@end defspec ++ ++@defspec defmacro* name arglist body... ++This is identical to the regular @code{defmacro} form, ++except that @var{arglist} is allowed to be a full Common Lisp ++argument list. The @code{&environment} keyword is supported as ++described in Steele. The @code{&whole} keyword is supported only ++within destructured lists (see below); top-level @code{&whole} ++cannot be implemented with the current Emacs Lisp interpreter. ++The macro expander body is enclosed in an implicit block called ++@var{name}. ++@end defspec ++ ++@defspec function* symbol-or-lambda ++This is identical to the regular @code{function} form, ++except that if the argument is a @code{lambda} form then that ++form may use a full Common Lisp argument list. ++@end defspec ++ ++Also, all forms (such as @code{defsetf} and @code{flet}) defined ++in this package that include @var{arglist}s in their syntax allow ++full Common Lisp argument lists. ++ ++Note that it is @emph{not} necessary to use @code{defun*} in ++order to have access to most @dfn{CL} features in your function. ++These features are always present; @code{defun*}'s only ++difference from @code{defun} is its more flexible argument ++lists and its implicit block. ++ ++The full form of a Common Lisp argument list is ++ ++@example ++(@var{var}... ++ &optional (@var{var} @var{initform} @var{svar})... ++ &rest @var{var} ++ &key ((@var{keyword} @var{var}) @var{initform} @var{svar})... ++ &aux (@var{var} @var{initform})...) ++@end example ++ ++Each of the five argument list sections is optional. The @var{svar}, ++@var{initform}, and @var{keyword} parts are optional; if they are ++omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}. ++ ++The first section consists of zero or more @dfn{required} arguments. ++These arguments must always be specified in a call to the function; ++there is no difference between Emacs Lisp and Common Lisp as far as ++required arguments are concerned. ++ ++The second section consists of @dfn{optional} arguments. These ++arguments may be specified in the function call; if they are not, ++@var{initform} specifies the default value used for the argument. ++(No @var{initform} means to use @code{nil} as the default.) The ++@var{initform} is evaluated with the bindings for the preceding ++arguments already established; @code{(a &optional (b (1+ a)))} ++matches one or two arguments, with the second argument defaulting ++to one plus the first argument. If the @var{svar} is specified, ++it is an auxiliary variable which is bound to @code{t} if the optional ++argument was specified, or to @code{nil} if the argument was omitted. ++If you don't use an @var{svar}, then there will be no way for your ++function to tell whether it was called with no argument, or with ++the default value passed explicitly as an argument. ++ ++The third section consists of a single @dfn{rest} argument. If ++more arguments were passed to the function than are accounted for ++by the required and optional arguments, those extra arguments are ++collected into a list and bound to the ``rest'' argument variable. ++Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp. ++Common Lisp accepts @code{&body} as a synonym for @code{&rest} in ++macro contexts; this package accepts it all the time. ++ ++The fourth section consists of @dfn{keyword} arguments. These ++are optional arguments which are specified by name rather than ++positionally in the argument list. For example, ++ ++@example ++(defun* foo (a &optional b &key c d (e 17))) ++@end example ++ ++@noindent ++defines a function which may be called with one, two, or more ++arguments. The first two arguments are bound to @code{a} and ++@code{b} in the usual way. The remaining arguments must be ++pairs of the form @code{:c}, @code{:d}, or @code{:e} followed ++by the value to be bound to the corresponding argument variable. ++(Symbols whose names begin with a colon are called @dfn{keywords}, ++and they are self-quoting in the same way as @code{nil} and ++@code{t}.) ++ ++For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five ++arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword ++appears more than once in the function call, the first occurrence ++takes precedence over the later ones. Note that it is not possible ++to specify keyword arguments without specifying the optional ++argument @code{b} as well, since @code{(foo 1 :c 2)} would bind ++@code{b} to the keyword @code{:c}, then signal an error because ++@code{2} is not a valid keyword. ++ ++If a @var{keyword} symbol is explicitly specified in the argument ++list as shown in the above diagram, then that keyword will be ++used instead of just the variable name prefixed with a colon. ++You can specify a @var{keyword} symbol which does not begin with ++a colon at all, but such symbols will not be self-quoting; you ++will have to quote them explicitly with an apostrophe in the ++function call. ++ ++Ordinarily it is an error to pass an unrecognized keyword to ++a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask ++Lisp to ignore unrecognized keywords, either by adding the ++marker @code{&allow-other-keys} after the keyword section ++of the argument list, or by specifying an @code{:allow-other-keys} ++argument in the call whose value is non-@code{nil}. If the ++function uses both @code{&rest} and @code{&key} at the same time, ++the ``rest'' argument is bound to the keyword list as it appears ++in the call. For example: ++ ++@smallexample ++(defun* find-thing (thing &rest rest &key need &allow-other-keys) ++ (or (apply 'member* thing thing-list :allow-other-keys t rest) ++ (if need (error "Thing not found")))) ++@end smallexample ++ ++@noindent ++This function takes a @code{:need} keyword argument, but also ++accepts other keyword arguments which are passed on to the ++@code{member*} function. @code{allow-other-keys} is used to ++keep both @code{find-thing} and @code{member*} from complaining ++about each others' keywords in the arguments. ++ ++The fifth section of the argument list consists of @dfn{auxiliary ++variables}. These are not really arguments at all, but simply ++variables which are bound to @code{nil} or to the specified ++@var{initforms} during execution of the function. There is no ++difference between the following two functions, except for a ++matter of stylistic taste: ++ ++@example ++(defun* foo (a b &aux (c (+ a b)) d) ++ @var{body}) ++ ++(defun* foo (a b) ++ (let ((c (+ a b)) d) ++ @var{body})) ++@end example ++ ++Argument lists support @dfn{destructuring}. In Common Lisp, ++destructuring is only allowed with @code{defmacro}; this package ++allows it with @code{defun*} and other argument lists as well. ++In destructuring, any argument variable (@var{var} in the above ++diagram) can be replaced by a list of variables, or more generally, ++a recursive argument list. The corresponding argument value must ++be a list whose elements match this recursive argument list. ++For example: ++ ++@example ++(defmacro* dolist ((var listform &optional resultform) ++ &rest body) ++ ...) ++@end example ++ ++This says that the first argument of @code{dolist} must be a list ++of two or three items; if there are other arguments as well as this ++list, they are stored in @code{body}. All features allowed in ++regular argument lists are allowed in these recursive argument lists. ++In addition, the clause @samp{&whole @var{var}} is allowed at the ++front of a recursive argument list. It binds @var{var} to the ++whole list being matched; thus @code{(&whole all a b)} matches ++a list of two things, with @code{a} bound to the first thing, ++@code{b} bound to the second thing, and @code{all} bound to the ++list itself. (Common Lisp allows @code{&whole} in top-level ++@code{defmacro} argument lists as well, but Emacs Lisp does not ++support this usage.) ++ ++One last feature of destructuring is that the argument list may be ++dotted, so that the argument list @code{(a b . c)} is functionally ++equivalent to @code{(a b &rest c)}. ++ ++If the optimization quality @code{safety} is set to 0 ++(@pxref{Declarations}), error checking for wrong number of ++arguments and invalid keyword arguments is disabled. By default, ++argument lists are rigorously checked. ++ ++@node Time of Evaluation, , Argument Lists, Program Structure ++@section Time of Evaluation ++ ++@noindent ++Normally, the byte-compiler does not actually execute the forms in ++a file it compiles. For example, if a file contains @code{(setq foo t)}, ++the act of compiling it will not actually set @code{foo} to @code{t}. ++This is true even if the @code{setq} was a top-level form (i.e., not ++enclosed in a @code{defun} or other form). Sometimes, though, you ++would like to have certain top-level forms evaluated at compile-time. ++For example, the compiler effectively evaluates @code{defmacro} forms ++at compile-time so that later parts of the file can refer to the ++macros that are defined. ++ ++@defspec eval-when (situations...) forms... ++This form controls when the body @var{forms} are evaluated. ++The @var{situations} list may contain any set of the symbols ++@code{compile}, @code{load}, and @code{eval} (or their long-winded ++ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel}, ++and @code{:execute}). ++ ++The @code{eval-when} form is handled differently depending on ++whether or not it is being compiled as a top-level form. ++Specifically, it gets special treatment if it is being compiled ++by a command such as @code{byte-compile-file} which compiles files ++or buffers of code, and it appears either literally at the ++top level of the file or inside a top-level @code{progn}. ++ ++For compiled top-level @code{eval-when}s, the body @var{forms} are ++executed at compile-time if @code{compile} is in the @var{situations} ++list, and the @var{forms} are written out to the file (to be executed ++at load-time) if @code{load} is in the @var{situations} list. ++ ++For non-compiled-top-level forms, only the @code{eval} situation is ++relevant. (This includes forms executed by the interpreter, forms ++compiled with @code{byte-compile} rather than @code{byte-compile-file}, ++and non-top-level forms.) The @code{eval-when} acts like a ++@code{progn} if @code{eval} is specified, and like @code{nil} ++(ignoring the body @var{forms}) if not. ++ ++The rules become more subtle when @code{eval-when}s are nested; ++consult Steele (second edition) for the gruesome details (and ++some gruesome examples). ++ ++Some simple examples: ++ ++@example ++;; Top-level forms in foo.el: ++(eval-when (compile) (setq foo1 'bar)) ++(eval-when (load) (setq foo2 'bar)) ++(eval-when (compile load) (setq foo3 'bar)) ++(eval-when (eval) (setq foo4 'bar)) ++(eval-when (eval compile) (setq foo5 'bar)) ++(eval-when (eval load) (setq foo6 'bar)) ++(eval-when (eval compile load) (setq foo7 'bar)) ++@end example ++ ++When @file{foo.el} is compiled, these variables will be set during ++the compilation itself: ++ ++@example ++foo1 foo3 foo5 foo7 ; `compile' ++@end example ++ ++When @file{foo.elc} is loaded, these variables will be set: ++ ++@example ++foo2 foo3 foo6 foo7 ; `load' ++@end example ++ ++And if @file{foo.el} is loaded uncompiled, these variables will ++be set: ++ ++@example ++foo4 foo5 foo6 foo7 ; `eval' ++@end example ++ ++If these seven @code{eval-when}s had been, say, inside a @code{defun}, ++then the first three would have been equivalent to @code{nil} and the ++last four would have been equivalent to the corresponding @code{setq}s. ++ ++Note that @code{(eval-when (load eval) @dots{})} is equivalent ++to @code{(progn @dots{})} in all contexts. The compiler treats ++certain top-level forms, like @code{defmacro} (sort-of) and ++@code{require}, as if they were wrapped in @code{(eval-when ++(compile load eval) @dots{})}. ++@end defspec ++ ++Emacs includes two special forms related to @code{eval-when}. ++One of these, @code{eval-when-compile}, is not quite equivalent to ++any @code{eval-when} construct and is described below. ++ ++The other form, @code{(eval-and-compile @dots{})}, is exactly ++equivalent to @samp{(eval-when (compile load eval) @dots{})} and ++so is not itself defined by this package. ++ ++@defspec eval-when-compile forms... ++The @var{forms} are evaluated at compile-time; at execution time, ++this form acts like a quoted constant of the resulting value. Used ++at top-level, @code{eval-when-compile} is just like @samp{eval-when ++(compile eval)}. In other contexts, @code{eval-when-compile} ++allows code to be evaluated once at compile-time for efficiency ++or other reasons. ++ ++This form is similar to the @samp{#.} syntax of true Common Lisp. ++@end defspec ++ ++@defspec load-time-value form ++The @var{form} is evaluated at load-time; at execution time, ++this form acts like a quoted constant of the resulting value. ++ ++Early Common Lisp had a @samp{#,} syntax that was similar to ++this, but ANSI Common Lisp replaced it with @code{load-time-value} ++and gave it more well-defined semantics. ++ ++In a compiled file, @code{load-time-value} arranges for @var{form} ++to be evaluated when the @file{.elc} file is loaded and then used ++as if it were a quoted constant. In code compiled by ++@code{byte-compile} rather than @code{byte-compile-file}, the ++effect is identical to @code{eval-when-compile}. In uncompiled ++code, both @code{eval-when-compile} and @code{load-time-value} ++act exactly like @code{progn}. ++ ++@example ++(defun report () ++ (insert "This function was executed on: " ++ (current-time-string) ++ ", compiled on: " ++ (eval-when-compile (current-time-string)) ++ ;; or '#.(current-time-string) in real Common Lisp ++ ", and loaded on: " ++ (load-time-value (current-time-string)))) ++@end example ++ ++@noindent ++Byte-compiled, the above defun will result in the following code ++(or its compiled equivalent, of course) in the @file{.elc} file: ++ ++@example ++(setq --temp-- (current-time-string)) ++(defun report () ++ (insert "This function was executed on: " ++ (current-time-string) ++ ", compiled on: " ++ '"Wed Jun 23 18:33:43 1993" ++ ", and loaded on: " ++ --temp--)) ++@end example ++@end defspec ++ ++@node Predicates, Control Structure, Program Structure, Top ++@chapter Predicates ++ ++@noindent ++This section describes functions for testing whether various ++facts are true or false. ++ ++@menu ++* Type Predicates:: `typep', `deftype', and `coerce' ++* Equality Predicates:: `equalp' ++@end menu ++ ++@node Type Predicates, Equality Predicates, Predicates, Predicates ++@section Type Predicates ++ ++@noindent ++The @dfn{CL} package defines a version of the Common Lisp @code{typep} ++predicate. ++ ++@defun typep object type ++Check if @var{object} is of type @var{type}, where @var{type} is a ++(quoted) type name of the sort used by Common Lisp. For example, ++@code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}. ++@end defun ++ ++The @var{type} argument to the above function is either a symbol ++or a list beginning with a symbol. ++ ++@itemize @bullet ++@item ++If the type name is a symbol, Emacs appends @samp{-p} to the ++symbol name to form the name of a predicate function for testing ++the type. (Built-in predicates whose names end in @samp{p} rather ++than @samp{-p} are used when appropriate.) ++ ++@item ++The type symbol @code{t} stands for the union of all types. ++@code{(typep @var{object} t)} is always true. Likewise, the ++type symbol @code{nil} stands for nothing at all, and ++@code{(typep @var{object} nil)} is always false. ++ ++@item ++The type symbol @code{null} represents the symbol @code{nil}. ++Thus @code{(typep @var{object} 'null)} is equivalent to ++@code{(null @var{object})}. ++ ++@item ++The type symbol @code{atom} represents all objects that are not cons ++cells. Thus @code{(typep @var{object} 'atom)} is equivalent to ++@code{(atom @var{object})}. ++ ++@item ++The type symbol @code{real} is a synonym for @code{number}, and ++@code{fixnum} is a synonym for @code{integer}. ++ ++@item ++The type symbols @code{character} and @code{string-char} match ++integers in the range from 0 to 255. ++ ++@item ++The type symbol @code{float} uses the @code{floatp-safe} predicate ++defined by this package rather than @code{floatp}, so it will work ++correctly even in Emacs versions without floating-point support. ++ ++@item ++The type list @code{(integer @var{low} @var{high})} represents all ++integers between @var{low} and @var{high}, inclusive. Either bound ++may be a list of a single integer to specify an exclusive limit, ++or a @code{*} to specify no limit. The type @code{(integer * *)} ++is thus equivalent to @code{integer}. ++ ++@item ++Likewise, lists beginning with @code{float}, @code{real}, or ++@code{number} represent numbers of that type falling in a particular ++range. ++ ++@item ++Lists beginning with @code{and}, @code{or}, and @code{not} form ++combinations of types. For example, @code{(or integer (float 0 *))} ++represents all objects that are integers or non-negative floats. ++ ++@item ++Lists beginning with @code{member} or @code{member*} represent ++objects @code{eql} to any of the following values. For example, ++@code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)}, ++and @code{(member nil)} is equivalent to @code{null}. ++ ++@item ++Lists of the form @code{(satisfies @var{predicate})} represent ++all objects for which @var{predicate} returns true when called ++with that object as an argument. ++@end itemize ++ ++The following function and macro (not technically predicates) are ++related to @code{typep}. ++ ++@defun coerce object type ++This function attempts to convert @var{object} to the specified ++@var{type}. If @var{object} is already of that type as determined by ++@code{typep}, it is simply returned. Otherwise, certain types of ++conversions will be made: If @var{type} is any sequence type ++(@code{string}, @code{list}, etc.) then @var{object} will be ++converted to that type if possible. If @var{type} is ++@code{character}, then strings of length one and symbols with ++one-character names can be coerced. If @var{type} is @code{float}, ++then integers can be coerced in versions of Emacs that support ++floats. In all other circumstances, @code{coerce} signals an ++error. ++@end defun ++ ++@defspec deftype name arglist forms... ++This macro defines a new type called @var{name}. It is similar ++to @code{defmacro} in many ways; when @var{name} is encountered ++as a type name, the body @var{forms} are evaluated and should ++return a type specifier that is equivalent to the type. The ++@var{arglist} is a Common Lisp argument list of the sort accepted ++by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)} ++is expanded by calling the expander with those arguments; the type ++symbol @samp{@var{name}} is expanded by calling the expander with ++no arguments. The @var{arglist} is processed the same as for ++@code{defmacro*} except that optional arguments without explicit ++defaults use @code{*} instead of @code{nil} as the ``default'' ++default. Some examples: ++ ++@example ++(deftype null () '(satisfies null)) ; predefined ++(deftype list () '(or null cons)) ; predefined ++(deftype unsigned-byte (&optional bits) ++ (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) ++(unsigned-byte 8) @equiv{} (integer 0 255) ++(unsigned-byte) @equiv{} (integer 0 *) ++unsigned-byte @equiv{} (integer 0 *) ++@end example ++ ++@noindent ++The last example shows how the Common Lisp @code{unsigned-byte} ++type specifier could be implemented if desired; this package does ++not implement @code{unsigned-byte} by default. ++@end defspec ++ ++The @code{typecase} and @code{check-type} macros also use type ++names. @xref{Conditionals}. @xref{Assertions}. The @code{map}, ++@code{concatenate}, and @code{merge} functions take type-name ++arguments to specify the type of sequence to return. @xref{Sequences}. ++ ++@node Equality Predicates, , Type Predicates, Predicates ++@section Equality Predicates ++ ++@noindent ++This package defines the Common Lisp predicate @code{equalp}. ++ ++@defun equalp a b ++This function is a more flexible version of @code{equal}. In ++particular, it compares strings case-insensitively, and it compares ++numbers without regard to type (so that @code{(equalp 3 3.0)} is ++true). Vectors and conses are compared recursively. All other ++objects are compared as if by @code{equal}. ++ ++This function differs from Common Lisp @code{equalp} in several ++respects. First, Common Lisp's @code{equalp} also compares ++@emph{characters} case-insensitively, which would be impractical ++in this package since Emacs does not distinguish between integers ++and characters. In keeping with the idea that strings are less ++vector-like in Emacs Lisp, this package's @code{equalp} also will ++not compare strings against vectors of integers. ++@end defun ++ ++Also note that the Common Lisp functions @code{member} and @code{assoc} ++use @code{eql} to compare elements, whereas Emacs Lisp follows the ++MacLisp tradition and uses @code{equal} for these two functions. ++In Emacs, use @code{member*} and @code{assoc*} to get functions ++which use @code{eql} for comparisons. ++ ++@node Control Structure, Macros, Predicates, Top ++@chapter Control Structure ++ ++@noindent ++The features described in the following sections implement ++various advanced control structures, including the powerful ++@code{setf} facility and a number of looping and conditional ++constructs. ++ ++@menu ++* Assignment:: The `psetq' form ++* Generalized Variables:: `setf', `incf', `push', etc. ++* Variable Bindings:: `progv', `lexical-let', `flet', `macrolet' ++* Conditionals:: `case', `typecase' ++* Blocks and Exits:: `block', `return', `return-from' ++* Iteration:: `do', `dotimes', `dolist', `do-symbols' ++* Loop Facility:: The Common Lisp `loop' macro ++* Multiple Values:: `values', `multiple-value-bind', etc. ++@end menu ++ ++@node Assignment, Generalized Variables, Control Structure, Control Structure ++@section Assignment ++ ++@noindent ++The @code{psetq} form is just like @code{setq}, except that multiple ++assignments are done in parallel rather than sequentially. ++ ++@defspec psetq [symbol form]@dots{} ++This special form (actually a macro) is used to assign to several ++variables simultaneously. Given only one @var{symbol} and @var{form}, ++it has the same effect as @code{setq}. Given several @var{symbol} ++and @var{form} pairs, it evaluates all the @var{form}s in advance ++and then stores the corresponding variables afterwards. ++ ++@example ++(setq x 2 y 3) ++(setq x (+ x y) y (* x y)) ++x ++ @result{} 5 ++y ; @r{@code{y} was computed after @code{x} was set.} ++ @result{} 15 ++(setq x 2 y 3) ++(psetq x (+ x y) y (* x y)) ++x ++ @result{} 5 ++y ; @r{@code{y} was computed before @code{x} was set.} ++ @result{} 6 ++@end example ++ ++The simplest use of @code{psetq} is @code{(psetq x y y x)}, which ++exchanges the values of two variables. (The @code{rotatef} form ++provides an even more convenient way to swap two variables; ++@pxref{Modify Macros}.) ++ ++@code{psetq} always returns @code{nil}. ++@end defspec ++ ++@node Generalized Variables, Variable Bindings, Assignment, Control Structure ++@section Generalized Variables ++ ++@noindent ++A ``generalized variable'' or ``place form'' is one of the many places ++in Lisp memory where values can be stored. The simplest place form is ++a regular Lisp variable. But the cars and cdrs of lists, elements ++of arrays, properties of symbols, and many other locations are also ++places where Lisp values are stored. ++ ++The @code{setf} form is like @code{setq}, except that it accepts ++arbitrary place forms on the left side rather than just ++symbols. For example, @code{(setf (car a) b)} sets the car of ++@code{a} to @code{b}, doing the same operation as @code{(setcar a b)} ++but without having to remember two separate functions for setting ++and accessing every type of place. ++ ++Generalized variables are analogous to ``lvalues'' in the C ++language, where @samp{x = a[i]} gets an element from an array ++and @samp{a[i] = x} stores an element using the same notation. ++Just as certain forms like @code{a[i]} can be lvalues in C, there ++is a set of forms that can be generalized variables in Lisp. ++ ++@menu ++* Basic Setf:: `setf' and place forms ++* Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc. ++* Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method' ++@end menu ++ ++@node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables ++@subsection Basic Setf ++ ++@noindent ++The @code{setf} macro is the most basic way to operate on generalized ++variables. ++ ++@defspec setf [place form]@dots{} ++This macro evaluates @var{form} and stores it in @var{place}, which ++must be a valid generalized variable form. If there are several ++@var{place} and @var{form} pairs, the assignments are done sequentially ++just as with @code{setq}. @code{setf} returns the value of the last ++@var{form}. ++ ++The following Lisp forms will work as generalized variables, and ++so may appear in the @var{place} argument of @code{setf}: ++ ++@itemize @bullet ++@item ++A symbol naming a variable. In other words, @code{(setf x y)} is ++exactly equivalent to @code{(setq x y)}, and @code{setq} itself is ++strictly speaking redundant now that @code{setf} exists. Many ++programmers continue to prefer @code{setq} for setting simple ++variables, though, purely for stylistic or historical reasons. ++The macro @code{(setf x y)} actually expands to @code{(setq x y)}, ++so there is no performance penalty for using it in compiled code. ++ ++@item ++A call to any of the following Lisp functions: ++ ++@smallexample ++car cdr caar .. cddddr ++nth rest first .. tenth ++aref elt nthcdr ++symbol-function symbol-value symbol-plist ++get get* getf ++gethash subseq ++@end smallexample ++ ++@noindent ++Note that for @code{nthcdr} and @code{getf}, the list argument ++of the function must itself be a valid @var{place} form. For ++example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself ++to 7. Note that @code{push} and @code{pop} on an @code{nthcdr} ++place can be used to insert or delete at any position in a list. ++The use of @code{nthcdr} as a @var{place} form is an extension ++to standard Common Lisp. ++ ++@item ++The following Emacs-specific functions are also @code{setf}-able. ++ ++@smallexample ++buffer-file-name marker-position ++buffer-modified-p match-data ++buffer-name mouse-position ++buffer-string overlay-end ++buffer-substring overlay-get ++current-buffer overlay-start ++current-case-table point ++current-column point-marker ++current-global-map point-max ++current-input-mode point-min ++current-local-map process-buffer ++current-window-configuration process-filter ++default-file-modes process-sentinel ++default-value read-mouse-position ++documentation-property screen-height ++extent-data screen-menubar ++extent-end-position screen-width ++extent-start-position selected-window ++face-background selected-screen ++face-background-pixmap selected-frame ++face-font standard-case-table ++face-foreground syntax-table ++face-underline-p window-buffer ++file-modes window-dedicated-p ++frame-height window-display-table ++frame-parameters window-height ++frame-visible-p window-hscroll ++frame-width window-point ++get-register window-start ++getenv window-width ++global-key-binding x-get-cut-buffer ++keymap-parent x-get-cutbuffer ++local-key-binding x-get-secondary-selection ++mark x-get-selection ++mark-marker ++@end smallexample ++ ++Most of these have directly corresponding ``set'' functions, like ++@code{use-local-map} for @code{current-local-map}, or @code{goto-char} ++for @code{point}. A few, like @code{point-min}, expand to longer ++sequences of code when they are @code{setf}'d (@code{(narrow-to-region ++x (point-max))} in this case). ++ ++@item ++A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, ++where @var{subplace} is itself a valid generalized variable whose ++current value is a string, and where the value stored is also a ++string. The new string is spliced into the specified part of the ++destination string. For example: ++ ++@example ++(setq a (list "hello" "world")) ++ @result{} ("hello" "world") ++(cadr a) ++ @result{} "world" ++(substring (cadr a) 2 4) ++ @result{} "rl" ++(setf (substring (cadr a) 2 4) "o") ++ @result{} "o" ++(cadr a) ++ @result{} "wood" ++a ++ @result{} ("hello" "wood") ++@end example ++ ++The generalized variable @code{buffer-substring}, listed above, ++also works in this way by replacing a portion of the current buffer. ++ ++@item ++A call of the form @code{(apply '@var{func} @dots{})} or ++@code{(apply (function @var{func}) @dots{})}, where @var{func} ++is a @code{setf}-able function whose store function is ``suitable'' ++in the sense described in Steele's book; since none of the standard ++Emacs place functions are suitable in this sense, this feature is ++only interesting when used with places you define yourself with ++@code{define-setf-method} or the long form of @code{defsetf}. ++ ++@item ++A macro call, in which case the macro is expanded and @code{setf} ++is applied to the resulting form. ++ ++@item ++Any form for which a @code{defsetf} or @code{define-setf-method} ++has been made. ++@end itemize ++ ++Using any forms other than these in the @var{place} argument to ++@code{setf} will signal an error. ++ ++The @code{setf} macro takes care to evaluate all subforms in ++the proper left-to-right order; for example, ++ ++@example ++(setf (aref vec (incf i)) i) ++@end example ++ ++@noindent ++looks like it will evaluate @code{(incf i)} exactly once, before the ++following access to @code{i}; the @code{setf} expander will insert ++temporary variables as necessary to ensure that it does in fact work ++this way no matter what setf-method is defined for @code{aref}. ++(In this case, @code{aset} would be used and no such steps would ++be necessary since @code{aset} takes its arguments in a convenient ++order.) ++ ++However, if the @var{place} form is a macro which explicitly ++evaluates its arguments in an unusual order, this unusual order ++will be preserved. Adapting an example from Steele, given ++ ++@example ++(defmacro wrong-order (x y) (list 'aref y x)) ++@end example ++ ++@noindent ++the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will ++evaluate @var{b} first, then @var{a}, just as in an actual call ++to @code{wrong-order}. ++@end defspec ++ ++@node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables ++@subsection Modify Macros ++ ++@noindent ++This package defines a number of other macros besides @code{setf} ++that operate on generalized variables. Many are interesting and ++useful even when the @var{place} is just a variable name. ++ ++@defspec psetf [place form]@dots{} ++This macro is to @code{setf} what @code{psetq} is to @code{setq}: ++When several @var{place}s and @var{form}s are involved, the ++assignments take place in parallel rather than sequentially. ++Specifically, all subforms are evaluated from left to right, then ++all the assignments are done (in an undefined order). ++@end defspec ++ ++@defspec incf place &optional x ++This macro increments the number stored in @var{place} by one, or ++by @var{x} if specified. The incremented value is returned. For ++example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and ++@code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}. ++ ++Once again, care is taken to preserve the ``apparent'' order of ++evaluation. For example, ++ ++@example ++(incf (aref vec (incf i))) ++@end example ++ ++@noindent ++appears to increment @code{i} once, then increment the element of ++@code{vec} addressed by @code{i}; this is indeed exactly what it ++does, which means the above form is @emph{not} equivalent to the ++``obvious'' expansion, ++ ++@example ++(setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong! ++@end example ++ ++@noindent ++but rather to something more like ++ ++@example ++(let ((temp (incf i))) ++ (setf (aref vec temp) (1+ (aref vec temp)))) ++@end example ++ ++@noindent ++Again, all of this is taken care of automatically by @code{incf} and ++the other generalized-variable macros. ++ ++As a more Emacs-specific example of @code{incf}, the expression ++@code{(incf (point) @var{n})} is essentially equivalent to ++@code{(forward-char @var{n})}. ++@end defspec ++ ++@defspec decf place &optional x ++This macro decrements the number stored in @var{place} by one, or ++by @var{x} if specified. ++@end defspec ++ ++@defspec pop place ++This macro removes and returns the first element of the list stored ++in @var{place}. It is analogous to @code{(prog1 (car @var{place}) ++(setf @var{place} (cdr @var{place})))}, except that it takes care ++to evaluate all subforms only once. ++@end defspec ++ ++@defspec push x place ++This macro inserts @var{x} at the front of the list stored in ++@var{place}. It is analogous to @code{(setf @var{place} (cons ++@var{x} @var{place}))}, except for evaluation of the subforms. ++@end defspec ++ ++@defspec pushnew x place @t{&key :test :test-not :key} ++This macro inserts @var{x} at the front of the list stored in ++@var{place}, but only if @var{x} was not @code{eql} to any ++existing element of the list. The optional keyword arguments ++are interpreted in the same way as for @code{adjoin}. ++@xref{Lists as Sets}. ++@end defspec ++ ++@defspec shiftf place@dots{} newvalue ++This macro shifts the @var{place}s left by one, shifting in the ++value of @var{newvalue} (which may be any Lisp expression, not just ++a generalized variable), and returning the value shifted out of ++the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c} ++@var{d})} is equivalent to ++ ++@example ++(prog1 ++ @var{a} ++ (psetf @var{a} @var{b} ++ @var{b} @var{c} ++ @var{c} @var{d})) ++@end example ++ ++@noindent ++except that the subforms of @var{a}, @var{b}, and @var{c} are actually ++evaluated only once each and in the apparent order. ++@end defspec ++ ++@defspec rotatef place@dots{} ++This macro rotates the @var{place}s left by one in circular fashion. ++Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to ++ ++@example ++(psetf @var{a} @var{b} ++ @var{b} @var{c} ++ @var{c} @var{d} ++ @var{d} @var{a}) ++@end example ++ ++@noindent ++except for the evaluation of subforms. @code{rotatef} always ++returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})} ++conveniently exchanges @var{a} and @var{b}. ++@end defspec ++ ++The following macros were invented for this package; they have no ++analogues in Common Lisp. ++ ++@defspec letf (bindings@dots{}) forms@dots{} ++This macro is analogous to @code{let}, but for generalized variables ++rather than just symbols. Each @var{binding} should be of the form ++@code{(@var{place} @var{value})}; the original contents of the ++@var{place}s are saved, the @var{value}s are stored in them, and ++then the body @var{form}s are executed. Afterwards, the @var{places} ++are set back to their original saved contents. This cleanup happens ++even if the @var{form}s exit irregularly due to a @code{throw} or an ++error. ++ ++For example, ++ ++@example ++(letf (((point) (point-min)) ++ (a 17)) ++ ...) ++@end example ++ ++@noindent ++moves ``point'' in the current buffer to the beginning of the buffer, ++and also binds @code{a} to 17 (as if by a normal @code{let}, since ++@code{a} is just a regular variable). After the body exits, @code{a} ++is set back to its original value and point is moved back to its ++original position. ++ ++Note that @code{letf} on @code{(point)} is not quite like a ++@code{save-excursion}, as the latter effectively saves a marker ++which tracks insertions and deletions in the buffer. Actually, ++a @code{letf} of @code{(point-marker)} is much closer to this ++behavior. (@code{point} and @code{point-marker} are equivalent ++as @code{setf} places; each will accept either an integer or a ++marker as the stored value.) ++ ++Since generalized variables look like lists, @code{let}'s shorthand ++of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would ++be ambiguous in @code{letf} and is not allowed. ++ ++However, a @var{binding} specifier may be a one-element list ++@samp{(@var{place})}, which is similar to @samp{(@var{place} ++@var{place})}. In other words, the @var{place} is not disturbed ++on entry to the body, and the only effect of the @code{letf} is ++to restore the original value of @var{place} afterwards. (The ++redundant access-and-store suggested by the @code{(@var{place} ++@var{place})} example does not actually occur.) ++ ++In most cases, the @var{place} must have a well-defined value on ++entry to the @code{letf} form. The only exceptions are plain ++variables and calls to @code{symbol-value} and @code{symbol-function}. ++If the symbol is not bound on entry, it is simply made unbound by ++@code{makunbound} or @code{fmakunbound} on exit. ++@end defspec ++ ++@defspec letf* (bindings@dots{}) forms@dots{} ++This macro is to @code{letf} what @code{let*} is to @code{let}: ++It does the bindings in sequential rather than parallel order. ++@end defspec ++ ++@defspec callf @var{function} @var{place} @var{args}@dots{} ++This is the ``generic'' modify macro. It calls @var{function}, ++which should be an unquoted function name, macro name, or lambda. ++It passes @var{place} and @var{args} as arguments, and assigns the ++result back to @var{place}. For example, @code{(incf @var{place} ++@var{n})} is the same as @code{(callf + @var{place} @var{n})}. ++Some more examples: ++ ++@example ++(callf abs my-number) ++(callf concat (buffer-name) "<" (int-to-string n) ">") ++(callf union happy-people (list joe bob) :test 'same-person) ++@end example ++ ++@xref{Customizing Setf}, for @code{define-modify-macro}, a way ++to create even more concise notations for modify macros. Note ++again that @code{callf} is an extension to standard Common Lisp. ++@end defspec ++ ++@defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} ++This macro is like @code{callf}, except that @var{place} is ++the @emph{second} argument of @var{function} rather than the ++first. For example, @code{(push @var{x} @var{place})} is ++equivalent to @code{(callf2 cons @var{x} @var{place})}. ++@end defspec ++ ++The @code{callf} and @code{callf2} macros serve as building ++blocks for other macros like @code{incf}, @code{pushnew}, and ++@code{define-modify-macro}. The @code{letf} and @code{letf*} ++macros are used in the processing of symbol macros; ++@pxref{Macro Bindings}. ++ ++@node Customizing Setf, , Modify Macros, Generalized Variables ++@subsection Customizing Setf ++ ++@noindent ++Common Lisp defines three macros, @code{define-modify-macro}, ++@code{defsetf}, and @code{define-setf-method}, that allow the ++user to extend generalized variables in various ways. ++ ++@defspec define-modify-macro name arglist function [doc-string] ++This macro defines a ``read-modify-write'' macro similar to ++@code{incf} and @code{decf}. The macro @var{name} is defined ++to take a @var{place} argument followed by additional arguments ++described by @var{arglist}. The call ++ ++@example ++(@var{name} @var{place} @var{args}...) ++@end example ++ ++@noindent ++will be expanded to ++ ++@example ++(callf @var{func} @var{place} @var{args}...) ++@end example ++ ++@noindent ++which in turn is roughly equivalent to ++ ++@example ++(setf @var{place} (@var{func} @var{place} @var{args}...)) ++@end example ++ ++For example: ++ ++@example ++(define-modify-macro incf (&optional (n 1)) +) ++(define-modify-macro concatf (&rest args) concat) ++@end example ++ ++Note that @code{&key} is not allowed in @var{arglist}, but ++@code{&rest} is sufficient to pass keywords on to the function. ++ ++Most of the modify macros defined by Common Lisp do not exactly ++follow the pattern of @code{define-modify-macro}. For example, ++@code{push} takes its arguments in the wrong order, and @code{pop} ++is completely irregular. You can define these macros ``by hand'' ++using @code{get-setf-method}, or consult the source file ++@file{cl-macs.el} to see how to use the internal @code{setf} ++building blocks. ++@end defspec ++ ++@defspec defsetf access-fn update-fn ++This is the simpler of two @code{defsetf} forms. Where ++@var{access-fn} is the name of a function which accesses a place, ++this declares @var{update-fn} to be the corresponding store ++function. From now on, ++ ++@example ++(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value}) ++@end example ++ ++@noindent ++will be expanded to ++ ++@example ++(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value}) ++@end example ++ ++@noindent ++The @var{update-fn} is required to be either a true function, or ++a macro which evaluates its arguments in a function-like way. Also, ++the @var{update-fn} is expected to return @var{value} as its result. ++Otherwise, the above expansion would not obey the rules for the way ++@code{setf} is supposed to behave. ++ ++As a special (non-Common-Lisp) extension, a third argument of @code{t} ++to @code{defsetf} says that the @code{update-fn}'s return value is ++not suitable, so that the above @code{setf} should be expanded to ++something more like ++ ++@example ++(let ((temp @var{value})) ++ (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp) ++ temp) ++@end example ++ ++Some examples of the use of @code{defsetf}, drawn from the standard ++suite of setf methods, are: ++ ++@example ++(defsetf car setcar) ++(defsetf symbol-value set) ++(defsetf buffer-name rename-buffer t) ++@end example ++@end defspec ++ ++@defspec defsetf access-fn arglist (store-var) forms@dots{} ++This is the second, more complex, form of @code{defsetf}. It is ++rather like @code{defmacro} except for the additional @var{store-var} ++argument. The @var{forms} should return a Lisp form which stores ++the value of @var{store-var} into the generalized variable formed ++by a call to @var{access-fn} with arguments described by @var{arglist}. ++The @var{forms} may begin with a string which documents the @code{setf} ++method (analogous to the doc string that appears at the front of a ++function). ++ ++For example, the simple form of @code{defsetf} is shorthand for ++ ++@example ++(defsetf @var{access-fn} (&rest args) (store) ++ (append '(@var{update-fn}) args (list store))) ++@end example ++ ++The Lisp form that is returned can access the arguments from ++@var{arglist} and @var{store-var} in an unrestricted fashion; ++macros like @code{setf} and @code{incf} which invoke this ++setf-method will insert temporary variables as needed to make ++sure the apparent order of evaluation is preserved. ++ ++Another example drawn from the standard package: ++ ++@example ++(defsetf nth (n x) (store) ++ (list 'setcar (list 'nthcdr n x) store)) ++@end example ++@end defspec ++ ++@defspec define-setf-method access-fn arglist forms@dots{} ++This is the most general way to create new place forms. When ++a @code{setf} to @var{access-fn} with arguments described by ++@var{arglist} is expanded, the @var{forms} are evaluated and ++must return a list of five items: ++ ++@enumerate ++@item ++A list of @dfn{temporary variables}. ++ ++@item ++A list of @dfn{value forms} corresponding to the temporary variables ++above. The temporary variables will be bound to these value forms ++as the first step of any operation on the generalized variable. ++ ++@item ++A list of exactly one @dfn{store variable} (generally obtained ++from a call to @code{gensym}). ++ ++@item ++A Lisp form which stores the contents of the store variable into ++the generalized variable, assuming the temporaries have been ++bound as described above. ++ ++@item ++A Lisp form which accesses the contents of the generalized variable, ++assuming the temporaries have been bound. ++@end enumerate ++ ++This is exactly like the Common Lisp macro of the same name, ++except that the method returns a list of five values rather ++than the five values themselves, since Emacs Lisp does not ++support Common Lisp's notion of multiple return values. ++ ++Once again, the @var{forms} may begin with a documentation string. ++ ++A setf-method should be maximally conservative with regard to ++temporary variables. In the setf-methods generated by ++@code{defsetf}, the second return value is simply the list of ++arguments in the place form, and the first return value is a ++list of a corresponding number of temporary variables generated ++by @code{gensym}. Macros like @code{setf} and @code{incf} which ++use this setf-method will optimize away most temporaries that ++turn out to be unnecessary, so there is little reason for the ++setf-method itself to optimize. ++@end defspec ++ ++@defun get-setf-method place &optional env ++This function returns the setf-method for @var{place}, by ++invoking the definition previously recorded by @code{defsetf} ++or @code{define-setf-method}. The result is a list of five ++values as described above. You can use this function to build ++your own @code{incf}-like modify macros. (Actually, it is ++better to use the internal functions @code{cl-setf-do-modify} ++and @code{cl-setf-do-store}, which are a bit easier to use and ++which also do a number of optimizations; consult the source ++code for the @code{incf} function for a simple example.) ++ ++The argument @var{env} specifies the ``environment'' to be ++passed on to @code{macroexpand} if @code{get-setf-method} should ++need to expand a macro in @var{place}. It should come from ++an @code{&environment} argument to the macro or setf-method ++that called @code{get-setf-method}. ++ ++See also the source code for the setf-methods for @code{apply} ++and @code{substring}, each of which works by calling ++@code{get-setf-method} on a simpler case, then massaging ++the result in various ways. ++@end defun ++ ++Modern Common Lisp defines a second, independent way to specify ++the @code{setf} behavior of a function, namely ``@code{setf} ++functions'' whose names are lists @code{(setf @var{name})} ++rather than symbols. For example, @code{(defun (setf foo) @dots{})} ++defines the function that is used when @code{setf} is applied to ++@code{foo}. This package does not currently support @code{setf} ++functions. In particular, it is a compile-time error to use ++@code{setf} on a form which has not already been @code{defsetf}'d ++or otherwise declared; in newer Common Lisps, this would not be ++an error since the function @code{(setf @var{func})} might be ++defined later. ++ ++@iftex ++@secno=4 ++@end iftex ++ ++@node Variable Bindings, Conditionals, Generalized Variables, Control Structure ++@section Variable Bindings ++ ++@noindent ++These Lisp forms make bindings to variables and function names, ++analogous to Lisp's built-in @code{let} form. ++ ++@xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which ++are also related to variable bindings. ++ ++@menu ++* Dynamic Bindings:: The `progv' form ++* Lexical Bindings:: `lexical-let' and lexical closures ++* Function Bindings:: `flet' and `labels' ++* Macro Bindings:: `macrolet' and `symbol-macrolet' ++@end menu ++ ++@node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings ++@subsection Dynamic Bindings ++ ++@noindent ++The standard @code{let} form binds variables whose names are known ++at compile-time. The @code{progv} form provides an easy way to ++bind variables whose names are computed at run-time. ++ ++@defspec progv symbols values forms@dots{} ++This form establishes @code{let}-style variable bindings on a ++set of variables computed at run-time. The expressions ++@var{symbols} and @var{values} are evaluated, and must return lists ++of symbols and values, respectively. The symbols are bound to the ++corresponding values for the duration of the body @var{form}s. ++If @var{values} is shorter than @var{symbols}, the last few symbols ++are made unbound (as if by @code{makunbound}) inside the body. ++If @var{symbols} is shorter than @var{values}, the excess values ++are ignored. ++@end defspec ++ ++@node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings ++@subsection Lexical Bindings ++ ++@noindent ++The @dfn{CL} package defines the following macro which ++more closely follows the Common Lisp @code{let} form: ++ ++@defspec lexical-let (bindings@dots{}) forms@dots{} ++This form is exactly like @code{let} except that the bindings it ++establishes are purely lexical. Lexical bindings are similar to ++local variables in a language like C: Only the code physically ++within the body of the @code{lexical-let} (after macro expansion) ++may refer to the bound variables. ++ ++@example ++(setq a 5) ++(defun foo (b) (+ a b)) ++(let ((a 2)) (foo a)) ++ @result{} 4 ++(lexical-let ((a 2)) (foo a)) ++ @result{} 7 ++@end example ++ ++@noindent ++In this example, a regular @code{let} binding of @code{a} actually ++makes a temporary change to the global variable @code{a}, so @code{foo} ++is able to see the binding of @code{a} to 2. But @code{lexical-let} ++actually creates a distinct local variable @code{a} for use within its ++body, without any effect on the global variable of the same name. ++ ++The most important use of lexical bindings is to create @dfn{closures}. ++A closure is a function object that refers to an outside lexical ++variable. For example: ++ ++@example ++(defun make-adder (n) ++ (lexical-let ((n n)) ++ (function (lambda (m) (+ n m))))) ++(setq add17 (make-adder 17)) ++(funcall add17 4) ++ @result{} 21 ++@end example ++ ++@noindent ++The call @code{(make-adder 17)} returns a function object which adds ++17 to its argument. If @code{let} had been used instead of ++@code{lexical-let}, the function object would have referred to the ++global @code{n}, which would have been bound to 17 only during the ++call to @code{make-adder} itself. ++ ++@example ++(defun make-counter () ++ (lexical-let ((n 0)) ++ (function* (lambda (&optional (m 1)) (incf n m))))) ++(setq count-1 (make-counter)) ++(funcall count-1 3) ++ @result{} 3 ++(funcall count-1 14) ++ @result{} 17 ++(setq count-2 (make-counter)) ++(funcall count-2 5) ++ @result{} 5 ++(funcall count-1 2) ++ @result{} 19 ++(funcall count-2) ++ @result{} 6 ++@end example ++ ++@noindent ++Here we see that each call to @code{make-counter} creates a distinct ++local variable @code{n}, which serves as a private counter for the ++function object that is returned. ++ ++Closed-over lexical variables persist until the last reference to ++them goes away, just like all other Lisp objects. For example, ++@code{count-2} refers to a function object which refers to an ++instance of the variable @code{n}; this is the only reference ++to that variable, so after @code{(setq count-2 nil)} the garbage ++collector would be able to delete this instance of @code{n}. ++Of course, if a @code{lexical-let} does not actually create any ++closures, then the lexical variables are free as soon as the ++@code{lexical-let} returns. ++ ++Many closures are used only during the extent of the bindings they ++refer to; these are known as ``downward funargs'' in Lisp parlance. ++When a closure is used in this way, regular Emacs Lisp dynamic ++bindings suffice and will be more efficient than @code{lexical-let} ++closures: ++ ++@example ++(defun add-to-list (x list) ++ (mapcar (lambda (y) (+ x y))) list) ++(add-to-list 7 '(1 2 5)) ++ @result{} (8 9 12) ++@end example ++ ++@noindent ++Since this lambda is only used while @code{x} is still bound, ++it is not necessary to make a true closure out of it. ++ ++You can use @code{defun} or @code{flet} inside a @code{lexical-let} ++to create a named closure. If several closures are created in the ++body of a single @code{lexical-let}, they all close over the same ++instance of the lexical variable. ++ ++The @code{lexical-let} form is an extension to Common Lisp. In ++true Common Lisp, all bindings are lexical unless declared otherwise. ++@end defspec ++ ++@defspec lexical-let* (bindings@dots{}) forms@dots{} ++This form is just like @code{lexical-let}, except that the bindings ++are made sequentially in the manner of @code{let*}. ++@end defspec ++ ++@node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings ++@subsection Function Bindings ++ ++@noindent ++These forms make @code{let}-like bindings to functions instead ++of variables. ++ ++@defspec flet (bindings@dots{}) forms@dots{} ++This form establishes @code{let}-style bindings on the function ++cells of symbols rather than on the value cells. Each @var{binding} ++must be a list of the form @samp{(@var{name} @var{arglist} ++@var{forms}@dots{})}, which defines a function exactly as if ++it were a @code{defun*} form. The function @var{name} is defined ++accordingly for the duration of the body of the @code{flet}; then ++the old function definition, or lack thereof, is restored. ++ ++While @code{flet} in Common Lisp establishes a lexical binding of ++@var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The ++result is that @code{flet} affects indirect calls to a function as ++well as calls directly inside the @code{flet} form itself. ++ ++You can use @code{flet} to disable or modify the behavior of a ++function in a temporary fashion. This will even work on Emacs ++primitives, although note that some calls to primitive functions ++internal to Emacs are made without going through the symbol's ++function cell, and so will not be affected by @code{flet}. For ++example, ++ ++@example ++(flet ((message (&rest args) (push args saved-msgs))) ++ (do-something)) ++@end example ++ ++This code attempts to replace the built-in function @code{message} ++with a function that simply saves the messages in a list rather ++than displaying them. The original definition of @code{message} ++will be restored after @code{do-something} exits. This code will ++work fine on messages generated by other Lisp code, but messages ++generated directly inside Emacs will not be caught since they make ++direct C-language calls to the message routines rather than going ++through the Lisp @code{message} function. ++ ++@c Bug#411. ++Also note that many primitives (e.g. @code{+}) have special byte-compile ++handling. Attempts to redefine such functions using @code{flet} will ++fail if byte-compiled. In such cases, use @code{labels} instead. ++ ++Functions defined by @code{flet} may use the full Common Lisp ++argument notation supported by @code{defun*}; also, the function ++body is enclosed in an implicit block as if by @code{defun*}. ++@xref{Program Structure}. ++@end defspec ++ ++@defspec labels (bindings@dots{}) forms@dots{} ++The @code{labels} form is like @code{flet}, except that it ++makes lexical bindings of the function names rather than ++dynamic bindings. (In true Common Lisp, both @code{flet} and ++@code{labels} make lexical bindings of slightly different sorts; ++since Emacs Lisp is dynamically bound by default, it seemed ++more appropriate for @code{flet} also to use dynamic binding. ++The @code{labels} form, with its lexical binding, is fully ++compatible with Common Lisp.) ++ ++Lexical scoping means that all references to the named ++functions must appear physically within the body of the ++@code{labels} form. References may appear both in the body ++@var{forms} of @code{labels} itself, and in the bodies of ++the functions themselves. Thus, @code{labels} can define ++local recursive functions, or mutually-recursive sets of ++functions. ++ ++A ``reference'' to a function name is either a call to that ++function, or a use of its name quoted by @code{quote} or ++@code{function} to be passed on to, say, @code{mapcar}. ++@end defspec ++ ++@node Macro Bindings, , Function Bindings, Variable Bindings ++@subsection Macro Bindings ++ ++@noindent ++These forms create local macros and ``symbol macros.'' ++ ++@defspec macrolet (bindings@dots{}) forms@dots{} ++This form is analogous to @code{flet}, but for macros instead of ++functions. Each @var{binding} is a list of the same form as the ++arguments to @code{defmacro*} (i.e., a macro name, argument list, ++and macro-expander forms). The macro is defined accordingly for ++use within the body of the @code{macrolet}. ++ ++Because of the nature of macros, @code{macrolet} is lexically ++scoped even in Emacs Lisp: The @code{macrolet} binding will ++affect only calls that appear physically within the body ++@var{forms}, possibly after expansion of other macros in the ++body. ++@end defspec ++ ++@defspec symbol-macrolet (bindings@dots{}) forms@dots{} ++This form creates @dfn{symbol macros}, which are macros that look ++like variable references rather than function calls. Each ++@var{binding} is a list @samp{(@var{var} @var{expansion})}; ++any reference to @var{var} within the body @var{forms} is ++replaced by @var{expansion}. ++ ++@example ++(setq bar '(5 . 9)) ++(symbol-macrolet ((foo (car bar))) ++ (incf foo)) ++bar ++ @result{} (6 . 9) ++@end example ++ ++A @code{setq} of a symbol macro is treated the same as a @code{setf}. ++I.e., @code{(setq foo 4)} in the above would be equivalent to ++@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}. ++ ++Likewise, a @code{let} or @code{let*} binding a symbol macro is ++treated like a @code{letf} or @code{letf*}. This differs from true ++Common Lisp, where the rules of lexical scoping cause a @code{let} ++binding to shadow a @code{symbol-macrolet} binding. In this package, ++only @code{lexical-let} and @code{lexical-let*} will shadow a symbol ++macro. ++ ++There is no analogue of @code{defmacro} for symbol macros; all symbol ++macros are local. A typical use of @code{symbol-macrolet} is in the ++expansion of another macro: ++ ++@example ++(defmacro* my-dolist ((x list) &rest body) ++ (let ((var (gensym))) ++ (list 'loop 'for var 'on list 'do ++ (list* 'symbol-macrolet (list (list x (list 'car var))) ++ body)))) ++ ++(setq mylist '(1 2 3 4)) ++(my-dolist (x mylist) (incf x)) ++mylist ++ @result{} (2 3 4 5) ++@end example ++ ++@noindent ++In this example, the @code{my-dolist} macro is similar to @code{dolist} ++(@pxref{Iteration}) except that the variable @code{x} becomes a true ++reference onto the elements of the list. The @code{my-dolist} call ++shown here expands to ++ ++@example ++(loop for G1234 on mylist do ++ (symbol-macrolet ((x (car G1234))) ++ (incf x))) ++@end example ++ ++@noindent ++which in turn expands to ++ ++@example ++(loop for G1234 on mylist do (incf (car G1234))) ++@end example ++ ++@xref{Loop Facility}, for a description of the @code{loop} macro. ++This package defines a nonstandard @code{in-ref} loop clause that ++works much like @code{my-dolist}. ++@end defspec ++ ++@node Conditionals, Blocks and Exits, Variable Bindings, Control Structure ++@section Conditionals ++ ++@noindent ++These conditional forms augment Emacs Lisp's simple @code{if}, ++@code{and}, @code{or}, and @code{cond} forms. ++ ++@defspec case keyform clause@dots{} ++This macro evaluates @var{keyform}, then compares it with the key ++values listed in the various @var{clause}s. Whichever clause matches ++the key is executed; comparison is done by @code{eql}. If no clause ++matches, the @code{case} form returns @code{nil}. The clauses are ++of the form ++ ++@example ++(@var{keylist} @var{body-forms}@dots{}) ++@end example ++ ++@noindent ++where @var{keylist} is a list of key values. If there is exactly ++one value, and it is not a cons cell or the symbol @code{nil} or ++@code{t}, then it can be used by itself as a @var{keylist} without ++being enclosed in a list. All key values in the @code{case} form ++must be distinct. The final clauses may use @code{t} in place of ++a @var{keylist} to indicate a default clause that should be taken ++if none of the other clauses match. (The symbol @code{otherwise} ++is also recognized in place of @code{t}. To make a clause that ++matches the actual symbol @code{t}, @code{nil}, or @code{otherwise}, ++enclose the symbol in a list.) ++ ++For example, this expression reads a keystroke, then does one of ++four things depending on whether it is an @samp{a}, a @samp{b}, ++a @key{RET} or @kbd{C-j}, or anything else. ++ ++@example ++(case (read-char) ++ (?a (do-a-thing)) ++ (?b (do-b-thing)) ++ ((?\r ?\n) (do-ret-thing)) ++ (t (do-other-thing))) ++@end example ++@end defspec ++ ++@defspec ecase keyform clause@dots{} ++This macro is just like @code{case}, except that if the key does ++not match any of the clauses, an error is signaled rather than ++simply returning @code{nil}. ++@end defspec ++ ++@defspec typecase keyform clause@dots{} ++This macro is a version of @code{case} that checks for types ++rather than values. Each @var{clause} is of the form ++@samp{(@var{type} @var{body}...)}. @xref{Type Predicates}, ++for a description of type specifiers. For example, ++ ++@example ++(typecase x ++ (integer (munch-integer x)) ++ (float (munch-float x)) ++ (string (munch-integer (string-to-int x))) ++ (t (munch-anything x))) ++@end example ++ ++The type specifier @code{t} matches any type of object; the word ++@code{otherwise} is also allowed. To make one clause match any of ++several types, use an @code{(or ...)} type specifier. ++@end defspec ++ ++@defspec etypecase keyform clause@dots{} ++This macro is just like @code{typecase}, except that if the key does ++not match any of the clauses, an error is signaled rather than ++simply returning @code{nil}. ++@end defspec ++ ++@node Blocks and Exits, Iteration, Conditionals, Control Structure ++@section Blocks and Exits ++ ++@noindent ++Common Lisp @dfn{blocks} provide a non-local exit mechanism very ++similar to @code{catch} and @code{throw}, but lexically rather than ++dynamically scoped. This package actually implements @code{block} ++in terms of @code{catch}; however, the lexical scoping allows the ++optimizing byte-compiler to omit the costly @code{catch} step if the ++body of the block does not actually @code{return-from} the block. ++ ++@defspec block name forms@dots{} ++The @var{forms} are evaluated as if by a @code{progn}. However, ++if any of the @var{forms} execute @code{(return-from @var{name})}, ++they will jump out and return directly from the @code{block} form. ++The @code{block} returns the result of the last @var{form} unless ++a @code{return-from} occurs. ++ ++The @code{block}/@code{return-from} mechanism is quite similar to ++the @code{catch}/@code{throw} mechanism. The main differences are ++that block @var{name}s are unevaluated symbols, rather than forms ++(such as quoted symbols) which evaluate to a tag at run-time; and ++also that blocks are lexically scoped whereas @code{catch}/@code{throw} ++are dynamically scoped. This means that functions called from the ++body of a @code{catch} can also @code{throw} to the @code{catch}, ++but the @code{return-from} referring to a block name must appear ++physically within the @var{forms} that make up the body of the block. ++They may not appear within other called functions, although they may ++appear within macro expansions or @code{lambda}s in the body. Block ++names and @code{catch} names form independent name-spaces. ++ ++In true Common Lisp, @code{defun} and @code{defmacro} surround ++the function or expander bodies with implicit blocks with the ++same name as the function or macro. This does not occur in Emacs ++Lisp, but this package provides @code{defun*} and @code{defmacro*} ++forms which do create the implicit block. ++ ++The Common Lisp looping constructs defined by this package, ++such as @code{loop} and @code{dolist}, also create implicit blocks ++just as in Common Lisp. ++ ++Because they are implemented in terms of Emacs Lisp @code{catch} ++and @code{throw}, blocks have the same overhead as actual ++@code{catch} constructs (roughly two function calls). However, ++the optimizing byte compiler will optimize away the @code{catch} ++if the block does ++not in fact contain any @code{return} or @code{return-from} calls ++that jump to it. This means that @code{do} loops and @code{defun*} ++functions which don't use @code{return} don't pay the overhead to ++support it. ++@end defspec ++ ++@defspec return-from name [result] ++This macro returns from the block named @var{name}, which must be ++an (unevaluated) symbol. If a @var{result} form is specified, it ++is evaluated to produce the result returned from the @code{block}. ++Otherwise, @code{nil} is returned. ++@end defspec ++ ++@defspec return [result] ++This macro is exactly like @code{(return-from nil @var{result})}. ++Common Lisp loops like @code{do} and @code{dolist} implicitly enclose ++themselves in @code{nil} blocks. ++@end defspec ++ ++@node Iteration, Loop Facility, Blocks and Exits, Control Structure ++@section Iteration ++ ++@noindent ++The macros described here provide more sophisticated, high-level ++looping constructs to complement Emacs Lisp's basic @code{while} ++loop. ++ ++@defspec loop forms@dots{} ++The @dfn{CL} package supports both the simple, old-style meaning of ++@code{loop} and the extremely powerful and flexible feature known as ++the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced ++facility is discussed in the following section; @pxref{Loop Facility}. ++The simple form of @code{loop} is described here. ++ ++If @code{loop} is followed by zero or more Lisp expressions, ++then @code{(loop @var{exprs}@dots{})} simply creates an infinite ++loop executing the expressions over and over. The loop is ++enclosed in an implicit @code{nil} block. Thus, ++ ++@example ++(loop (foo) (if (no-more) (return 72)) (bar)) ++@end example ++ ++@noindent ++is exactly equivalent to ++ ++@example ++(block nil (while t (foo) (if (no-more) (return 72)) (bar))) ++@end example ++ ++If any of the expressions are plain symbols, the loop is instead ++interpreted as a Loop Macro specification as described later. ++(This is not a restriction in practice, since a plain symbol ++in the above notation would simply access and throw away the ++value of a variable.) ++@end defspec ++ ++@defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} ++This macro creates a general iterative loop. Each @var{spec} is ++of the form ++ ++@example ++(@var{var} [@var{init} [@var{step}]]) ++@end example ++ ++The loop works as follows: First, each @var{var} is bound to the ++associated @var{init} value as if by a @code{let} form. Then, in ++each iteration of the loop, the @var{end-test} is evaluated; if ++true, the loop is finished. Otherwise, the body @var{forms} are ++evaluated, then each @var{var} is set to the associated @var{step} ++expression (as if by a @code{psetq} form) and the next iteration ++begins. Once the @var{end-test} becomes true, the @var{result} ++forms are evaluated (with the @var{var}s still bound to their ++values) to produce the result returned by @code{do}. ++ ++The entire @code{do} loop is enclosed in an implicit @code{nil} ++block, so that you can use @code{(return)} to break out of the ++loop at any time. ++ ++If there are no @var{result} forms, the loop returns @code{nil}. ++If a given @var{var} has no @var{step} form, it is bound to its ++@var{init} value but not otherwise modified during the @code{do} ++loop (unless the code explicitly modifies it); this case is just ++a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})} ++around the loop. If @var{init} is also omitted it defaults to ++@code{nil}, and in this case a plain @samp{@var{var}} can be used ++in place of @samp{(@var{var})}, again following the analogy with ++@code{let}. ++ ++This example (from Steele) illustrates a loop which applies the ++function @code{f} to successive pairs of values from the lists ++@code{foo} and @code{bar}; it is equivalent to the call ++@code{(mapcar* 'f foo bar)}. Note that this loop has no body ++@var{forms} at all, performing all its work as side effects of ++the rest of the loop. ++ ++@example ++(do ((x foo (cdr x)) ++ (y bar (cdr y)) ++ (z nil (cons (f (car x) (car y)) z))) ++ ((or (null x) (null y)) ++ (nreverse z))) ++@end example ++@end defspec ++ ++@defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} ++This is to @code{do} what @code{let*} is to @code{let}. In ++particular, the initial values are bound as if by @code{let*} ++rather than @code{let}, and the steps are assigned as if by ++@code{setq} rather than @code{psetq}. ++ ++Here is another way to write the above loop: ++ ++@example ++(do* ((xp foo (cdr xp)) ++ (yp bar (cdr yp)) ++ (x (car xp) (car xp)) ++ (y (car yp) (car yp)) ++ z) ++ ((or (null xp) (null yp)) ++ (nreverse z)) ++ (push (f x y) z)) ++@end example ++@end defspec ++ ++@defspec dolist (var list [result]) forms@dots{} ++This is a more specialized loop which iterates across the elements ++of a list. @var{list} should evaluate to a list; the body @var{forms} ++are executed with @var{var} bound to each element of the list in ++turn. Finally, the @var{result} form (or @code{nil}) is evaluated ++with @var{var} bound to @code{nil} to produce the result returned by ++the loop. Unlike with Emacs's built in @code{dolist}, the loop is ++surrounded by an implicit @code{nil} block. ++@end defspec ++ ++@defspec dotimes (var count [result]) forms@dots{} ++This is a more specialized loop which iterates a specified number ++of times. The body is executed with @var{var} bound to the integers ++from zero (inclusive) to @var{count} (exclusive), in turn. Then ++the @code{result} form is evaluated with @var{var} bound to the total ++number of iterations that were done (i.e., @code{(max 0 @var{count})}) ++to get the return value for the loop form. Unlike with Emacs's built in ++@code{dolist}, the loop is surrounded by an implicit @code{nil} block. ++@end defspec ++ ++@defspec do-symbols (var [obarray [result]]) forms@dots{} ++This loop iterates over all interned symbols. If @var{obarray} ++is specified and is not @code{nil}, it loops over all symbols in ++that obarray. For each symbol, the body @var{forms} are evaluated ++with @var{var} bound to that symbol. The symbols are visited in ++an unspecified order. Afterward the @var{result} form, if any, ++is evaluated (with @var{var} bound to @code{nil}) to get the return ++value. The loop is surrounded by an implicit @code{nil} block. ++@end defspec ++ ++@defspec do-all-symbols (var [result]) forms@dots{} ++This is identical to @code{do-symbols} except that the @var{obarray} ++argument is omitted; it always iterates over the default obarray. ++@end defspec ++ ++@xref{Mapping over Sequences}, for some more functions for ++iterating over vectors or lists. ++ ++@node Loop Facility, Multiple Values, Iteration, Control Structure ++@section Loop Facility ++ ++@noindent ++A common complaint with Lisp's traditional looping constructs is ++that they are either too simple and limited, such as Common Lisp's ++@code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and ++obscure, like Common Lisp's @code{do} loop. ++ ++To remedy this, recent versions of Common Lisp have added a new ++construct called the ``Loop Facility'' or ``@code{loop} macro,'' ++with an easy-to-use but very powerful and expressive syntax. ++ ++@menu ++* Loop Basics:: `loop' macro, basic clause structure ++* Loop Examples:: Working examples of `loop' macro ++* For Clauses:: Clauses introduced by `for' or `as' ++* Iteration Clauses:: `repeat', `while', `thereis', etc. ++* Accumulation Clauses:: `collect', `sum', `maximize', etc. ++* Other Clauses:: `with', `if', `initially', `finally' ++@end menu ++ ++@node Loop Basics, Loop Examples, Loop Facility, Loop Facility ++@subsection Loop Basics ++ ++@noindent ++The @code{loop} macro essentially creates a mini-language within ++Lisp that is specially tailored for describing loops. While this ++language is a little strange-looking by the standards of regular Lisp, ++it turns out to be very easy to learn and well-suited to its purpose. ++ ++Since @code{loop} is a macro, all parsing of the loop language ++takes place at byte-compile time; compiled @code{loop}s are just ++as efficient as the equivalent @code{while} loops written longhand. ++ ++@defspec loop clauses@dots{} ++A loop construct consists of a series of @var{clause}s, each ++introduced by a symbol like @code{for} or @code{do}. Clauses ++are simply strung together in the argument list of @code{loop}, ++with minimal extra parentheses. The various types of clauses ++specify initializations, such as the binding of temporary ++variables, actions to be taken in the loop, stepping actions, ++and final cleanup. ++ ++Common Lisp specifies a certain general order of clauses in a ++loop: ++ ++@example ++(loop @var{name-clause} ++ @var{var-clauses}@dots{} ++ @var{action-clauses}@dots{}) ++@end example ++ ++The @var{name-clause} optionally gives a name to the implicit ++block that surrounds the loop. By default, the implicit block ++is named @code{nil}. The @var{var-clauses} specify what ++variables should be bound during the loop, and how they should ++be modified or iterated throughout the course of the loop. The ++@var{action-clauses} are things to be done during the loop, such ++as computing, collecting, and returning values. ++ ++The Emacs version of the @code{loop} macro is less restrictive about ++the order of clauses, but things will behave most predictably if ++you put the variable-binding clauses @code{with}, @code{for}, and ++@code{repeat} before the action clauses. As in Common Lisp, ++@code{initially} and @code{finally} clauses can go anywhere. ++ ++Loops generally return @code{nil} by default, but you can cause ++them to return a value by using an accumulation clause like ++@code{collect}, an end-test clause like @code{always}, or an ++explicit @code{return} clause to jump out of the implicit block. ++(Because the loop body is enclosed in an implicit block, you can ++also use regular Lisp @code{return} or @code{return-from} to ++break out of the loop.) ++@end defspec ++ ++The following sections give some examples of the Loop Macro in ++action, and describe the particular loop clauses in great detail. ++Consult the second edition of Steele's @dfn{Common Lisp, the Language}, ++for additional discussion and examples of the @code{loop} macro. ++ ++@node Loop Examples, For Clauses, Loop Basics, Loop Facility ++@subsection Loop Examples ++ ++@noindent ++Before listing the full set of clauses that are allowed, let's ++look at a few example loops just to get a feel for the @code{loop} ++language. ++ ++@example ++(loop for buf in (buffer-list) ++ collect (buffer-file-name buf)) ++@end example ++ ++@noindent ++This loop iterates over all Emacs buffers, using the list ++returned by @code{buffer-list}. For each buffer @code{buf}, ++it calls @code{buffer-file-name} and collects the results into ++a list, which is then returned from the @code{loop} construct. ++The result is a list of the file names of all the buffers in ++Emacs' memory. The words @code{for}, @code{in}, and @code{collect} ++are reserved words in the @code{loop} language. ++ ++@example ++(loop repeat 20 do (insert "Yowsa\n")) ++@end example ++ ++@noindent ++This loop inserts the phrase ``Yowsa'' twenty times in the ++current buffer. ++ ++@example ++(loop until (eobp) do (munch-line) (forward-line 1)) ++@end example ++ ++@noindent ++This loop calls @code{munch-line} on every line until the end ++of the buffer. If point is already at the end of the buffer, ++the loop exits immediately. ++ ++@example ++(loop do (munch-line) until (eobp) do (forward-line 1)) ++@end example ++ ++@noindent ++This loop is similar to the above one, except that @code{munch-line} ++is always called at least once. ++ ++@example ++(loop for x from 1 to 100 ++ for y = (* x x) ++ until (>= y 729) ++ finally return (list x (= y 729))) ++@end example ++ ++@noindent ++This more complicated loop searches for a number @code{x} whose ++square is 729. For safety's sake it only examines @code{x} ++values up to 100; dropping the phrase @samp{to 100} would ++cause the loop to count upwards with no limit. The second ++@code{for} clause defines @code{y} to be the square of @code{x} ++within the loop; the expression after the @code{=} sign is ++reevaluated each time through the loop. The @code{until} ++clause gives a condition for terminating the loop, and the ++@code{finally} clause says what to do when the loop finishes. ++(This particular example was written less concisely than it ++could have been, just for the sake of illustration.) ++ ++Note that even though this loop contains three clauses (two ++@code{for}s and an @code{until}) that would have been enough to ++define loops all by themselves, it still creates a single loop ++rather than some sort of triple-nested loop. You must explicitly ++nest your @code{loop} constructs if you want nested loops. ++ ++@node For Clauses, Iteration Clauses, Loop Examples, Loop Facility ++@subsection For Clauses ++ ++@noindent ++Most loops are governed by one or more @code{for} clauses. ++A @code{for} clause simultaneously describes variables to be ++bound, how those variables are to be stepped during the loop, ++and usually an end condition based on those variables. ++ ++The word @code{as} is a synonym for the word @code{for}. This ++word is followed by a variable name, then a word like @code{from} ++or @code{across} that describes the kind of iteration desired. ++In Common Lisp, the phrase @code{being the} sometimes precedes ++the type of iteration; in this package both @code{being} and ++@code{the} are optional. The word @code{each} is a synonym ++for @code{the}, and the word that follows it may be singular ++or plural: @samp{for x being the elements of y} or ++@samp{for x being each element of y}. Which form you use ++is purely a matter of style. ++ ++The variable is bound around the loop as if by @code{let}: ++ ++@example ++(setq i 'happy) ++(loop for i from 1 to 10 do (do-something-with i)) ++i ++ @result{} happy ++@end example ++ ++@table @code ++@item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3} ++This type of @code{for} clause creates a counting loop. Each of ++the three sub-terms is optional, though there must be at least one ++term so that the clause is marked as a counting clause. ++ ++The three expressions are the starting value, the ending value, and ++the step value, respectively, of the variable. The loop counts ++upwards by default (@var{expr3} must be positive), from @var{expr1} ++to @var{expr2} inclusively. If you omit the @code{from} term, the ++loop counts from zero; if you omit the @code{to} term, the loop ++counts forever without stopping (unless stopped by some other ++loop clause, of course); if you omit the @code{by} term, the loop ++counts in steps of one. ++ ++You can replace the word @code{from} with @code{upfrom} or ++@code{downfrom} to indicate the direction of the loop. Likewise, ++you can replace @code{to} with @code{upto} or @code{downto}. ++For example, @samp{for x from 5 downto 1} executes five times ++with @code{x} taking on the integers from 5 down to 1 in turn. ++Also, you can replace @code{to} with @code{below} or @code{above}, ++which are like @code{upto} and @code{downto} respectively except ++that they are exclusive rather than inclusive limits: ++ ++@example ++(loop for x to 10 collect x) ++ @result{} (0 1 2 3 4 5 6 7 8 9 10) ++(loop for x below 10 collect x) ++ @result{} (0 1 2 3 4 5 6 7 8 9) ++@end example ++ ++The @code{by} value is always positive, even for downward-counting ++loops. Some sort of @code{from} value is required for downward ++loops; @samp{for x downto 5} is not a valid loop clause all by ++itself. ++ ++@item for @var{var} in @var{list} by @var{function} ++This clause iterates @var{var} over all the elements of @var{list}, ++in turn. If you specify the @code{by} term, then @var{function} ++is used to traverse the list instead of @code{cdr}; it must be a ++function taking one argument. For example: ++ ++@example ++(loop for x in '(1 2 3 4 5 6) collect (* x x)) ++ @result{} (1 4 9 16 25 36) ++(loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x)) ++ @result{} (1 9 25) ++@end example ++ ++@item for @var{var} on @var{list} by @var{function} ++This clause iterates @var{var} over all the cons cells of @var{list}. ++ ++@example ++(loop for x on '(1 2 3 4) collect x) ++ @result{} ((1 2 3 4) (2 3 4) (3 4) (4)) ++@end example ++ ++With @code{by}, there is no real reason that the @code{on} expression ++must be a list. For example: ++ ++@example ++(loop for x on first-animal by 'next-animal collect x) ++@end example ++ ++@noindent ++where @code{(next-animal x)} takes an ``animal'' @var{x} and returns ++the next in the (assumed) sequence of animals, or @code{nil} if ++@var{x} was the last animal in the sequence. ++ ++@item for @var{var} in-ref @var{list} by @var{function} ++This is like a regular @code{in} clause, but @var{var} becomes ++a @code{setf}-able ``reference'' onto the elements of the list ++rather than just a temporary variable. For example, ++ ++@example ++(loop for x in-ref my-list do (incf x)) ++@end example ++ ++@noindent ++increments every element of @code{my-list} in place. This clause ++is an extension to standard Common Lisp. ++ ++@item for @var{var} across @var{array} ++This clause iterates @var{var} over all the elements of @var{array}, ++which may be a vector or a string. ++ ++@example ++(loop for x across "aeiou" ++ do (use-vowel (char-to-string x))) ++@end example ++ ++@item for @var{var} across-ref @var{array} ++This clause iterates over an array, with @var{var} a @code{setf}-able ++reference onto the elements; see @code{in-ref} above. ++ ++@item for @var{var} being the elements of @var{sequence} ++This clause iterates over the elements of @var{sequence}, which may ++be a list, vector, or string. Since the type must be determined ++at run-time, this is somewhat less efficient than @code{in} or ++@code{across}. The clause may be followed by the additional term ++@samp{using (index @var{var2})} to cause @var{var2} to be bound to ++the successive indices (starting at 0) of the elements. ++ ++This clause type is taken from older versions of the @code{loop} macro, ++and is not present in modern Common Lisp. The @samp{using (sequence ...)} ++term of the older macros is not supported. ++ ++@item for @var{var} being the elements of-ref @var{sequence} ++This clause iterates over a sequence, with @var{var} a @code{setf}-able ++reference onto the elements; see @code{in-ref} above. ++ ++@item for @var{var} being the symbols [of @var{obarray}] ++This clause iterates over symbols, either over all interned symbols ++or over all symbols in @var{obarray}. The loop is executed with ++@var{var} bound to each symbol in turn. The symbols are visited in ++an unspecified order. ++ ++As an example, ++ ++@example ++(loop for sym being the symbols ++ when (fboundp sym) ++ when (string-match "^map" (symbol-name sym)) ++ collect sym) ++@end example ++ ++@noindent ++returns a list of all the functions whose names begin with @samp{map}. ++ ++The Common Lisp words @code{external-symbols} and @code{present-symbols} ++are also recognized but are equivalent to @code{symbols} in Emacs Lisp. ++ ++Due to a minor implementation restriction, it will not work to have ++more than one @code{for} clause iterating over symbols, hash tables, ++keymaps, overlays, or intervals in a given @code{loop}. Fortunately, ++it would rarely if ever be useful to do so. It @emph{is} valid to mix ++one of these types of clauses with other clauses like @code{for ... to} ++or @code{while}. ++ ++@item for @var{var} being the hash-keys of @var{hash-table} ++This clause iterates over the entries in @var{hash-table}. For each ++hash table entry, @var{var} is bound to the entry's key. If you write ++@samp{the hash-values} instead, @var{var} is bound to the values ++of the entries. The clause may be followed by the additional ++term @samp{using (hash-values @var{var2})} (where @code{hash-values} ++is the opposite word of the word following @code{the}) to cause ++@var{var} and @var{var2} to be bound to the two parts of each ++hash table entry. ++ ++@item for @var{var} being the key-codes of @var{keymap} ++This clause iterates over the entries in @var{keymap}. ++The iteration does not enter nested keymaps but does enter inherited ++(parent) keymaps. ++You can use @samp{the key-bindings} to access the commands bound to ++the keys rather than the key codes, and you can add a @code{using} ++clause to access both the codes and the bindings together. ++ ++@item for @var{var} being the key-seqs of @var{keymap} ++This clause iterates over all key sequences defined by @var{keymap} ++and its nested keymaps, where @var{var} takes on values which are ++vectors. The strings or vectors ++are reused for each iteration, so you must copy them if you wish to keep ++them permanently. You can add a @samp{using (key-bindings ...)} ++clause to get the command bindings as well. ++ ++@item for @var{var} being the overlays [of @var{buffer}] @dots{} ++This clause iterates over the ``overlays'' of a buffer ++(the clause @code{extents} is synonymous ++with @code{overlays}). If the @code{of} term is omitted, the current ++buffer is used. ++This clause also accepts optional @samp{from @var{pos}} and ++@samp{to @var{pos}} terms, limiting the clause to overlays which ++overlap the specified region. ++ ++@item for @var{var} being the intervals [of @var{buffer}] @dots{} ++This clause iterates over all intervals of a buffer with constant ++text properties. The variable @var{var} will be bound to conses ++of start and end positions, where one start position is always equal ++to the previous end position. The clause allows @code{of}, ++@code{from}, @code{to}, and @code{property} terms, where the latter ++term restricts the search to just the specified property. The ++@code{of} term may specify either a buffer or a string. ++ ++@item for @var{var} being the frames ++This clause iterates over all frames, i.e., X window system windows ++open on Emacs files. The ++clause @code{screens} is a synonym for @code{frames}. The frames ++are visited in @code{next-frame} order starting from ++@code{selected-frame}. ++ ++@item for @var{var} being the windows [of @var{frame}] ++This clause iterates over the windows (in the Emacs sense) of ++the current frame, or of the specified @var{frame}. ++ ++@item for @var{var} being the buffers ++This clause iterates over all buffers in Emacs. It is equivalent ++to @samp{for @var{var} in (buffer-list)}. ++ ++@item for @var{var} = @var{expr1} then @var{expr2} ++This clause does a general iteration. The first time through ++the loop, @var{var} will be bound to @var{expr1}. On the second ++and successive iterations it will be set by evaluating @var{expr2} ++(which may refer to the old value of @var{var}). For example, ++these two loops are effectively the same: ++ ++@example ++(loop for x on my-list by 'cddr do ...) ++(loop for x = my-list then (cddr x) while x do ...) ++@end example ++ ++Note that this type of @code{for} clause does not imply any sort ++of terminating condition; the above example combines it with a ++@code{while} clause to tell when to end the loop. ++ ++If you omit the @code{then} term, @var{expr1} is used both for ++the initial setting and for successive settings: ++ ++@example ++(loop for x = (random) when (> x 0) return x) ++@end example ++ ++@noindent ++This loop keeps taking random numbers from the @code{(random)} ++function until it gets a positive one, which it then returns. ++@end table ++ ++If you include several @code{for} clauses in a row, they are ++treated sequentially (as if by @code{let*} and @code{setq}). ++You can instead use the word @code{and} to link the clauses, ++in which case they are processed in parallel (as if by @code{let} ++and @code{psetq}). ++ ++@example ++(loop for x below 5 for y = nil then x collect (list x y)) ++ @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4)) ++(loop for x below 5 and y = nil then x collect (list x y)) ++ @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3)) ++@end example ++ ++@noindent ++In the first loop, @code{y} is set based on the value of @code{x} ++that was just set by the previous clause; in the second loop, ++@code{x} and @code{y} are set simultaneously so @code{y} is set ++based on the value of @code{x} left over from the previous time ++through the loop. ++ ++Another feature of the @code{loop} macro is @dfn{destructuring}, ++similar in concept to the destructuring provided by @code{defmacro}. ++The @var{var} part of any @code{for} clause can be given as a list ++of variables instead of a single variable. The values produced ++during loop execution must be lists; the values in the lists are ++stored in the corresponding variables. ++ ++@example ++(loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y)) ++ @result{} (5 9 13) ++@end example ++ ++In loop destructuring, if there are more values than variables ++the trailing values are ignored, and if there are more variables ++than values the trailing variables get the value @code{nil}. ++If @code{nil} is used as a variable name, the corresponding ++values are ignored. Destructuring may be nested, and dotted ++lists of variables like @code{(x . y)} are allowed. ++ ++@node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility ++@subsection Iteration Clauses ++ ++@noindent ++Aside from @code{for} clauses, there are several other loop clauses ++that control the way the loop operates. They might be used by ++themselves, or in conjunction with one or more @code{for} clauses. ++ ++@table @code ++@item repeat @var{integer} ++This clause simply counts up to the specified number using an ++internal temporary variable. The loops ++ ++@example ++(loop repeat (1+ n) do ...) ++(loop for temp to n do ...) ++@end example ++ ++@noindent ++are identical except that the second one forces you to choose ++a name for a variable you aren't actually going to use. ++ ++@item while @var{condition} ++This clause stops the loop when the specified condition (any Lisp ++expression) becomes @code{nil}. For example, the following two ++loops are equivalent, except for the implicit @code{nil} block ++that surrounds the second one: ++ ++@example ++(while @var{cond} @var{forms}@dots{}) ++(loop while @var{cond} do @var{forms}@dots{}) ++@end example ++ ++@item until @var{condition} ++This clause stops the loop when the specified condition is true, ++i.e., non-@code{nil}. ++ ++@item always @var{condition} ++This clause stops the loop when the specified condition is @code{nil}. ++Unlike @code{while}, it stops the loop using @code{return nil} so that ++the @code{finally} clauses are not executed. If all the conditions ++were non-@code{nil}, the loop returns @code{t}: ++ ++@example ++(if (loop for size in size-list always (> size 10)) ++ (some-big-sizes) ++ (no-big-sizes)) ++@end example ++ ++@item never @var{condition} ++This clause is like @code{always}, except that the loop returns ++@code{t} if any conditions were false, or @code{nil} otherwise. ++ ++@item thereis @var{condition} ++This clause stops the loop when the specified form is non-@code{nil}; ++in this case, it returns that non-@code{nil} value. If all the ++values were @code{nil}, the loop returns @code{nil}. ++@end table ++ ++@node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility ++@subsection Accumulation Clauses ++ ++@noindent ++These clauses cause the loop to accumulate information about the ++specified Lisp @var{form}. The accumulated result is returned ++from the loop unless overridden, say, by a @code{return} clause. ++ ++@table @code ++@item collect @var{form} ++This clause collects the values of @var{form} into a list. Several ++examples of @code{collect} appear elsewhere in this manual. ++ ++The word @code{collecting} is a synonym for @code{collect}, and ++likewise for the other accumulation clauses. ++ ++@item append @var{form} ++This clause collects lists of values into a result list using ++@code{append}. ++ ++@item nconc @var{form} ++This clause collects lists of values into a result list by ++destructively modifying the lists rather than copying them. ++ ++@item concat @var{form} ++This clause concatenates the values of the specified @var{form} ++into a string. (It and the following clause are extensions to ++standard Common Lisp.) ++ ++@item vconcat @var{form} ++This clause concatenates the values of the specified @var{form} ++into a vector. ++ ++@item count @var{form} ++This clause counts the number of times the specified @var{form} ++evaluates to a non-@code{nil} value. ++ ++@item sum @var{form} ++This clause accumulates the sum of the values of the specified ++@var{form}, which must evaluate to a number. ++ ++@item maximize @var{form} ++This clause accumulates the maximum value of the specified @var{form}, ++which must evaluate to a number. The return value is undefined if ++@code{maximize} is executed zero times. ++ ++@item minimize @var{form} ++This clause accumulates the minimum value of the specified @var{form}. ++@end table ++ ++Accumulation clauses can be followed by @samp{into @var{var}} to ++cause the data to be collected into variable @var{var} (which is ++automatically @code{let}-bound during the loop) rather than an ++unnamed temporary variable. Also, @code{into} accumulations do ++not automatically imply a return value. The loop must use some ++explicit mechanism, such as @code{finally return}, to return ++the accumulated result. ++ ++It is valid for several accumulation clauses of the same type to ++accumulate into the same place. From Steele: ++ ++@example ++(loop for name in '(fred sue alice joe june) ++ for kids in '((bob ken) () () (kris sunshine) ()) ++ collect name ++ append kids) ++ @result{} (fred bob ken sue alice joe kris sunshine june) ++@end example ++ ++@node Other Clauses, , Accumulation Clauses, Loop Facility ++@subsection Other Clauses ++ ++@noindent ++This section describes the remaining loop clauses. ++ ++@table @code ++@item with @var{var} = @var{value} ++This clause binds a variable to a value around the loop, but ++otherwise leaves the variable alone during the loop. The following ++loops are basically equivalent: ++ ++@example ++(loop with x = 17 do ...) ++(let ((x 17)) (loop do ...)) ++(loop for x = 17 then x do ...) ++@end example ++ ++Naturally, the variable @var{var} might be used for some purpose ++in the rest of the loop. For example: ++ ++@example ++(loop for x in my-list with res = nil do (push x res) ++ finally return res) ++@end example ++ ++This loop inserts the elements of @code{my-list} at the front of ++a new list being accumulated in @code{res}, then returns the ++list @code{res} at the end of the loop. The effect is similar ++to that of a @code{collect} clause, but the list gets reversed ++by virtue of the fact that elements are being pushed onto the ++front of @code{res} rather than the end. ++ ++If you omit the @code{=} term, the variable is initialized to ++@code{nil}. (Thus the @samp{= nil} in the above example is ++unnecessary.) ++ ++Bindings made by @code{with} are sequential by default, as if ++by @code{let*}. Just like @code{for} clauses, @code{with} clauses ++can be linked with @code{and} to cause the bindings to be made by ++@code{let} instead. ++ ++@item if @var{condition} @var{clause} ++This clause executes the following loop clause only if the specified ++condition is true. The following @var{clause} should be an accumulation, ++@code{do}, @code{return}, @code{if}, or @code{unless} clause. ++Several clauses may be linked by separating them with @code{and}. ++These clauses may be followed by @code{else} and a clause or clauses ++to execute if the condition was false. The whole construct may ++optionally be followed by the word @code{end} (which may be used to ++disambiguate an @code{else} or @code{and} in a nested @code{if}). ++ ++The actual non-@code{nil} value of the condition form is available ++by the name @code{it} in the ``then'' part. For example: ++ ++@example ++(setq funny-numbers '(6 13 -1)) ++ @result{} (6 13 -1) ++(loop for x below 10 ++ if (oddp x) ++ collect x into odds ++ and if (memq x funny-numbers) return (cdr it) end ++ else ++ collect x into evens ++ finally return (vector odds evens)) ++ @result{} [(1 3 5 7 9) (0 2 4 6 8)] ++(setq funny-numbers '(6 7 13 -1)) ++ @result{} (6 7 13 -1) ++(loop <@r{same thing again}>) ++ @result{} (13 -1) ++@end example ++ ++Note the use of @code{and} to put two clauses into the ``then'' ++part, one of which is itself an @code{if} clause. Note also that ++@code{end}, while normally optional, was necessary here to make ++it clear that the @code{else} refers to the outermost @code{if} ++clause. In the first case, the loop returns a vector of lists ++of the odd and even values of @var{x}. In the second case, the ++odd number 7 is one of the @code{funny-numbers} so the loop ++returns early; the actual returned value is based on the result ++of the @code{memq} call. ++ ++@item when @var{condition} @var{clause} ++This clause is just a synonym for @code{if}. ++ ++@item unless @var{condition} @var{clause} ++The @code{unless} clause is just like @code{if} except that the ++sense of the condition is reversed. ++ ++@item named @var{name} ++This clause gives a name other than @code{nil} to the implicit ++block surrounding the loop. The @var{name} is the symbol to be ++used as the block name. ++ ++@item initially [do] @var{forms}... ++This keyword introduces one or more Lisp forms which will be ++executed before the loop itself begins (but after any variables ++requested by @code{for} or @code{with} have been bound to their ++initial values). @code{initially} clauses can appear anywhere; ++if there are several, they are executed in the order they appear ++in the loop. The keyword @code{do} is optional. ++ ++@item finally [do] @var{forms}... ++This introduces Lisp forms which will be executed after the loop ++finishes (say, on request of a @code{for} or @code{while}). ++@code{initially} and @code{finally} clauses may appear anywhere ++in the loop construct, but they are executed (in the specified ++order) at the beginning or end, respectively, of the loop. ++ ++@item finally return @var{form} ++This says that @var{form} should be executed after the loop ++is done to obtain a return value. (Without this, or some other ++clause like @code{collect} or @code{return}, the loop will simply ++return @code{nil}.) Variables bound by @code{for}, @code{with}, ++or @code{into} will still contain their final values when @var{form} ++is executed. ++ ++@item do @var{forms}... ++The word @code{do} may be followed by any number of Lisp expressions ++which are executed as an implicit @code{progn} in the body of the ++loop. Many of the examples in this section illustrate the use of ++@code{do}. ++ ++@item return @var{form} ++This clause causes the loop to return immediately. The following ++Lisp form is evaluated to give the return value of the @code{loop} ++form. The @code{finally} clauses, if any, are not executed. ++Of course, @code{return} is generally used inside an @code{if} or ++@code{unless}, as its use in a top-level loop clause would mean ++the loop would never get to ``loop'' more than once. ++ ++The clause @samp{return @var{form}} is equivalent to ++@samp{do (return @var{form})} (or @code{return-from} if the loop ++was named). The @code{return} clause is implemented a bit more ++efficiently, though. ++@end table ++ ++While there is no high-level way to add user extensions to @code{loop} ++(comparable to @code{defsetf} for @code{setf}, say), this package ++does offer two properties called @code{cl-loop-handler} and ++@code{cl-loop-for-handler} which are functions to be called when ++a given symbol is encountered as a top-level loop clause or ++@code{for} clause, respectively. Consult the source code in ++file @file{cl-macs.el} for details. ++ ++This package's @code{loop} macro is compatible with that of Common ++Lisp, except that a few features are not implemented: @code{loop-finish} ++and data-type specifiers. Naturally, the @code{for} clauses which ++iterate over keymaps, overlays, intervals, frames, windows, and ++buffers are Emacs-specific extensions. ++ ++@node Multiple Values, , Loop Facility, Control Structure ++@section Multiple Values ++ ++@noindent ++Common Lisp functions can return zero or more results. Emacs Lisp ++functions, by contrast, always return exactly one result. This ++package makes no attempt to emulate Common Lisp multiple return ++values; Emacs versions of Common Lisp functions that return more ++than one value either return just the first value (as in ++@code{compiler-macroexpand}) or return a list of values (as in ++@code{get-setf-method}). This package @emph{does} define placeholders ++for the Common Lisp functions that work with multiple values, but ++in Emacs Lisp these functions simply operate on lists instead. ++The @code{values} form, for example, is a synonym for @code{list} ++in Emacs. ++ ++@defspec multiple-value-bind (var@dots{}) values-form forms@dots{} ++This form evaluates @var{values-form}, which must return a list of ++values. It then binds the @var{var}s to these respective values, ++as if by @code{let}, and then executes the body @var{forms}. ++If there are more @var{var}s than values, the extra @var{var}s ++are bound to @code{nil}. If there are fewer @var{var}s than ++values, the excess values are ignored. ++@end defspec ++ ++@defspec multiple-value-setq (var@dots{}) form ++This form evaluates @var{form}, which must return a list of values. ++It then sets the @var{var}s to these respective values, as if by ++@code{setq}. Extra @var{var}s or values are treated the same as ++in @code{multiple-value-bind}. ++@end defspec ++ ++The older Quiroz package attempted a more faithful (but still ++imperfect) emulation of Common Lisp multiple values. The old ++method ``usually'' simulated true multiple values quite well, ++but under certain circumstances would leave spurious return ++values in memory where a later, unrelated @code{multiple-value-bind} ++form would see them. ++ ++Since a perfect emulation is not feasible in Emacs Lisp, this ++package opts to keep it as simple and predictable as possible. ++ ++@node Macros, Declarations, Control Structure, Top ++@chapter Macros ++ ++@noindent ++This package implements the various Common Lisp features of ++@code{defmacro}, such as destructuring, @code{&environment}, ++and @code{&body}. Top-level @code{&whole} is not implemented ++for @code{defmacro} due to technical difficulties. ++@xref{Argument Lists}. ++ ++Destructuring is made available to the user by way of the ++following macro: ++ ++@defspec destructuring-bind arglist expr forms@dots{} ++This macro expands to code which executes @var{forms}, with ++the variables in @var{arglist} bound to the list of values ++returned by @var{expr}. The @var{arglist} can include all ++the features allowed for @code{defmacro} argument lists, ++including destructuring. (The @code{&environment} keyword ++is not allowed.) The macro expansion will signal an error ++if @var{expr} returns a list of the wrong number of arguments ++or with incorrect keyword arguments. ++@end defspec ++ ++This package also includes the Common Lisp @code{define-compiler-macro} ++facility, which allows you to define compile-time expansions and ++optimizations for your functions. ++ ++@defspec define-compiler-macro name arglist forms@dots{} ++This form is similar to @code{defmacro}, except that it only expands ++calls to @var{name} at compile-time; calls processed by the Lisp ++interpreter are not expanded, nor are they expanded by the ++@code{macroexpand} function. ++ ++The argument list may begin with a @code{&whole} keyword and a ++variable. This variable is bound to the macro-call form itself, ++i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}. ++If the macro expander returns this form unchanged, then the ++compiler treats it as a normal function call. This allows ++compiler macros to work as optimizers for special cases of a ++function, leaving complicated cases alone. ++ ++For example, here is a simplified version of a definition that ++appears as a standard part of this package: ++ ++@example ++(define-compiler-macro member* (&whole form a list &rest keys) ++ (if (and (null keys) ++ (eq (car-safe a) 'quote) ++ (not (floatp-safe (cadr a)))) ++ (list 'memq a list) ++ form)) ++@end example ++ ++@noindent ++This definition causes @code{(member* @var{a} @var{list})} to change ++to a call to the faster @code{memq} in the common case where @var{a} ++is a non-floating-point constant; if @var{a} is anything else, or ++if there are any keyword arguments in the call, then the original ++@code{member*} call is left intact. (The actual compiler macro ++for @code{member*} optimizes a number of other cases, including ++common @code{:test} predicates.) ++@end defspec ++ ++@defun compiler-macroexpand form ++This function is analogous to @code{macroexpand}, except that it ++expands compiler macros rather than regular macros. It returns ++@var{form} unchanged if it is not a call to a function for which ++a compiler macro has been defined, or if that compiler macro ++decided to punt by returning its @code{&whole} argument. Like ++@code{macroexpand}, it expands repeatedly until it reaches a form ++for which no further expansion is possible. ++@end defun ++ ++@xref{Macro Bindings}, for descriptions of the @code{macrolet} ++and @code{symbol-macrolet} forms for making ``local'' macro ++definitions. ++ ++@node Declarations, Symbols, Macros, Top ++@chapter Declarations ++ ++@noindent ++Common Lisp includes a complex and powerful ``declaration'' ++mechanism that allows you to give the compiler special hints ++about the types of data that will be stored in particular variables, ++and about the ways those variables and functions will be used. This ++package defines versions of all the Common Lisp declaration forms: ++@code{declare}, @code{locally}, @code{proclaim}, @code{declaim}, ++and @code{the}. ++ ++Most of the Common Lisp declarations are not currently useful in ++Emacs Lisp, as the byte-code system provides little opportunity ++to benefit from type information, and @code{special} declarations ++are redundant in a fully dynamically-scoped Lisp. A few ++declarations are meaningful when the optimizing byte ++compiler is being used, however. Under the earlier non-optimizing ++compiler, these declarations will effectively be ignored. ++ ++@defun proclaim decl-spec ++This function records a ``global'' declaration specified by ++@var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec} ++is evaluated and thus should normally be quoted. ++@end defun ++ ++@defspec declaim decl-specs@dots{} ++This macro is like @code{proclaim}, except that it takes any number ++of @var{decl-spec} arguments, and the arguments are unevaluated and ++unquoted. The @code{declaim} macro also puts an @code{(eval-when ++(compile load eval) ...)} around the declarations so that they will ++be registered at compile-time as well as at run-time. (This is vital, ++since normally the declarations are meant to influence the way the ++compiler treats the rest of the file that contains the @code{declaim} ++form.) ++@end defspec ++ ++@defspec declare decl-specs@dots{} ++This macro is used to make declarations within functions and other ++code. Common Lisp allows declarations in various locations, generally ++at the beginning of any of the many ``implicit @code{progn}s'' ++throughout Lisp syntax, such as function bodies, @code{let} bodies, ++etc. Currently the only declaration understood by @code{declare} ++is @code{special}. ++@end defspec ++ ++@defspec locally declarations@dots{} forms@dots{} ++In this package, @code{locally} is no different from @code{progn}. ++@end defspec ++ ++@defspec the type form ++Type information provided by @code{the} is ignored in this package; ++in other words, @code{(the @var{type} @var{form})} is equivalent ++to @var{form}. Future versions of the optimizing byte-compiler may ++make use of this information. ++ ++For example, @code{mapcar} can map over both lists and arrays. It is ++hard for the compiler to expand @code{mapcar} into an in-line loop ++unless it knows whether the sequence will be a list or an array ahead ++of time. With @code{(mapcar 'car (the vector foo))}, a future ++compiler would have enough information to expand the loop in-line. ++For now, Emacs Lisp will treat the above code as exactly equivalent ++to @code{(mapcar 'car foo)}. ++@end defspec ++ ++Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or ++@code{declare} should be a list beginning with a symbol that says ++what kind of declaration it is. This package currently understands ++@code{special}, @code{inline}, @code{notinline}, @code{optimize}, ++and @code{warn} declarations. (The @code{warn} declaration is an ++extension of standard Common Lisp.) Other Common Lisp declarations, ++such as @code{type} and @code{ftype}, are silently ignored. ++ ++@table @code ++@item special ++Since all variables in Emacs Lisp are ``special'' (in the Common ++Lisp sense), @code{special} declarations are only advisory. They ++simply tell the optimizing byte compiler that the specified ++variables are intentionally being referred to without being ++bound in the body of the function. The compiler normally emits ++warnings for such references, since they could be typographical ++errors for references to local variables. ++ ++The declaration @code{(declare (special @var{var1} @var{var2}))} is ++equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the ++optimizing compiler, or to nothing at all in older compilers (which ++do not warn for non-local references). ++ ++In top-level contexts, it is generally better to write ++@code{(defvar @var{var})} than @code{(declaim (special @var{var}))}, ++since @code{defvar} makes your intentions clearer. But the older ++byte compilers can not handle @code{defvar}s appearing inside of ++functions, while @code{(declare (special @var{var}))} takes care ++to work correctly with all compilers. ++ ++@item inline ++The @code{inline} @var{decl-spec} lists one or more functions ++whose bodies should be expanded ``in-line'' into calling functions ++whenever the compiler is able to arrange for it. For example, ++the Common Lisp function @code{cadr} is declared @code{inline} ++by this package so that the form @code{(cadr @var{x})} will ++expand directly into @code{(car (cdr @var{x}))} when it is called ++in user functions, for a savings of one (relatively expensive) ++function call. ++ ++The following declarations are all equivalent. Note that the ++@code{defsubst} form is a convenient way to define a function ++and declare it inline all at once. ++ ++@example ++(declaim (inline foo bar)) ++(eval-when (compile load eval) (proclaim '(inline foo bar))) ++(defsubst foo (...) ...) ; instead of defun ++@end example ++ ++@strong{Please note:} this declaration remains in effect after the ++containing source file is done. It is correct to use it to ++request that a function you have defined should be inlined, ++but it is impolite to use it to request inlining of an external ++function. ++ ++In Common Lisp, it is possible to use @code{(declare (inline @dots{}))} ++before a particular call to a function to cause just that call to ++be inlined; the current byte compilers provide no way to implement ++this, so @code{(declare (inline @dots{}))} is currently ignored by ++this package. ++ ++@item notinline ++The @code{notinline} declaration lists functions which should ++not be inlined after all; it cancels a previous @code{inline} ++declaration. ++ ++@item optimize ++This declaration controls how much optimization is performed by ++the compiler. Naturally, it is ignored by the earlier non-optimizing ++compilers. ++ ++The word @code{optimize} is followed by any number of lists like ++@code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several ++optimization ``qualities''; this package ignores all but @code{speed} ++and @code{safety}. The value of a quality should be an integer from ++0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.'' ++The default level for both qualities is 1. ++ ++In this package, with the optimizing compiler, the ++@code{speed} quality is tied to the @code{byte-compile-optimize} ++flag, which is set to @code{nil} for @code{(speed 0)} and to ++@code{t} for higher settings; and the @code{safety} quality is ++tied to the @code{byte-compile-delete-errors} flag, which is ++set to @code{t} for @code{(safety 3)} and to @code{nil} for all ++lower settings. (The latter flag controls whether the compiler ++is allowed to optimize out code whose only side-effect could ++be to signal an error, e.g., rewriting @code{(progn foo bar)} to ++@code{bar} when it is not known whether @code{foo} will be bound ++at run-time.) ++ ++Note that even compiling with @code{(safety 0)}, the Emacs ++byte-code system provides sufficient checking to prevent real ++harm from being done. For example, barring serious bugs in ++Emacs itself, Emacs will not crash with a segmentation fault ++just because of an error in a fully-optimized Lisp program. ++ ++The @code{optimize} declaration is normally used in a top-level ++@code{proclaim} or @code{declaim} in a file; Common Lisp allows ++it to be used with @code{declare} to set the level of optimization ++locally for a given form, but this will not work correctly with the ++current version of the optimizing compiler. (The @code{declare} ++will set the new optimization level, but that level will not ++automatically be unset after the enclosing form is done.) ++ ++@item warn ++This declaration controls what sorts of warnings are generated ++by the byte compiler. Again, only the optimizing compiler ++generates warnings. The word @code{warn} is followed by any ++number of ``warning qualities,'' similar in form to optimization ++qualities. The currently supported warning types are ++@code{redefine}, @code{callargs}, @code{unresolved}, and ++@code{free-vars}; in the current system, a value of 0 will ++disable these warnings and any higher value will enable them. ++See the documentation for the optimizing byte compiler for details. ++@end table ++ ++@node Symbols, Numbers, Declarations, Top ++@chapter Symbols ++ ++@noindent ++This package defines several symbol-related features that were ++missing from Emacs Lisp. ++ ++@menu ++* Property Lists:: `get*', `remprop', `getf', `remf' ++* Creating Symbols:: `gensym', `gentemp' ++@end menu ++ ++@node Property Lists, Creating Symbols, Symbols, Symbols ++@section Property Lists ++ ++@noindent ++These functions augment the standard Emacs Lisp functions @code{get} ++and @code{put} for operating on properties attached to symbols. ++There are also functions for working with property lists as ++first-class data structures not attached to particular symbols. ++ ++@defun get* symbol property &optional default ++This function is like @code{get}, except that if the property is ++not found, the @var{default} argument provides the return value. ++(The Emacs Lisp @code{get} function always uses @code{nil} as ++the default; this package's @code{get*} is equivalent to Common ++Lisp's @code{get}.) ++ ++The @code{get*} function is @code{setf}-able; when used in this ++fashion, the @var{default} argument is allowed but ignored. ++@end defun ++ ++@defun remprop symbol property ++This function removes the entry for @var{property} from the property ++list of @var{symbol}. It returns a true value if the property was ++indeed found and removed, or @code{nil} if there was no such property. ++(This function was probably omitted from Emacs originally because, ++since @code{get} did not allow a @var{default}, it was very difficult ++to distinguish between a missing property and a property whose value ++was @code{nil}; thus, setting a property to @code{nil} was close ++enough to @code{remprop} for most purposes.) ++@end defun ++ ++@defun getf place property &optional default ++This function scans the list @var{place} as if it were a property ++list, i.e., a list of alternating property names and values. If ++an even-numbered element of @var{place} is found which is @code{eq} ++to @var{property}, the following odd-numbered element is returned. ++Otherwise, @var{default} is returned (or @code{nil} if no default ++is given). ++ ++In particular, ++ ++@example ++(get sym prop) @equiv{} (getf (symbol-plist sym) prop) ++@end example ++ ++It is valid to use @code{getf} as a @code{setf} place, in which case ++its @var{place} argument must itself be a valid @code{setf} place. ++The @var{default} argument, if any, is ignored in this context. ++The effect is to change (via @code{setcar}) the value cell in the ++list that corresponds to @var{property}, or to cons a new property-value ++pair onto the list if the property is not yet present. ++ ++@example ++(put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val) ++@end example ++ ++The @code{get} and @code{get*} functions are also @code{setf}-able. ++The fact that @code{default} is ignored can sometimes be useful: ++ ++@example ++(incf (get* 'foo 'usage-count 0)) ++@end example ++ ++Here, symbol @code{foo}'s @code{usage-count} property is incremented ++if it exists, or set to 1 (an incremented 0) otherwise. ++ ++When not used as a @code{setf} form, @code{getf} is just a regular ++function and its @var{place} argument can actually be any Lisp ++expression. ++@end defun ++ ++@defspec remf place property ++This macro removes the property-value pair for @var{property} from ++the property list stored at @var{place}, which is any @code{setf}-able ++place expression. It returns true if the property was found. Note ++that if @var{property} happens to be first on the list, this will ++effectively do a @code{(setf @var{place} (cddr @var{place}))}, ++whereas if it occurs later, this simply uses @code{setcdr} to splice ++out the property and value cells. ++@end defspec ++ ++@iftex ++@secno=2 ++@end iftex ++ ++@node Creating Symbols, , Property Lists, Symbols ++@section Creating Symbols ++ ++@noindent ++These functions create unique symbols, typically for use as ++temporary variables. ++ ++@defun gensym &optional x ++This function creates a new, uninterned symbol (using @code{make-symbol}) ++with a unique name. (The name of an uninterned symbol is relevant ++only if the symbol is printed.) By default, the name is generated ++from an increasing sequence of numbers, @samp{G1000}, @samp{G1001}, ++@samp{G1002}, etc. If the optional argument @var{x} is a string, that ++string is used as a prefix instead of @samp{G}. Uninterned symbols ++are used in macro expansions for temporary variables, to ensure that ++their names will not conflict with ``real'' variables in the user's ++code. ++@end defun ++ ++@defvar *gensym-counter* ++This variable holds the counter used to generate @code{gensym} names. ++It is incremented after each use by @code{gensym}. In Common Lisp ++this is initialized with 0, but this package initializes it with a ++random (time-dependent) value to avoid trouble when two files that ++each used @code{gensym} in their compilation are loaded together. ++(Uninterned symbols become interned when the compiler writes them ++out to a file and the Emacs loader loads them, so their names have to ++be treated a bit more carefully than in Common Lisp where uninterned ++symbols remain uninterned after loading.) ++@end defvar ++ ++@defun gentemp &optional x ++This function is like @code{gensym}, except that it produces a new ++@emph{interned} symbol. If the symbol that is generated already ++exists, the function keeps incrementing the counter and trying ++again until a new symbol is generated. ++@end defun ++ ++The Quiroz @file{cl.el} package also defined a @code{defkeyword} ++form for creating self-quoting keyword symbols. This package ++automatically creates all keywords that are called for by ++@code{&key} argument specifiers, and discourages the use of ++keywords as data unrelated to keyword arguments, so the ++@code{defkeyword} form has been discontinued. ++ ++@iftex ++@chapno=11 ++@end iftex ++ ++@node Numbers, Sequences, Symbols, Top ++@chapter Numbers ++ ++@noindent ++This section defines a few simple Common Lisp operations on numbers ++which were left out of Emacs Lisp. ++ ++@menu ++* Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc. ++* Numerical Functions:: `abs', `floor*', etc. ++* Random Numbers:: `random*', `make-random-state' ++* Implementation Parameters:: `most-positive-float' ++@end menu ++ ++@iftex ++@secno=1 ++@end iftex ++ ++@node Predicates on Numbers, Numerical Functions, Numbers, Numbers ++@section Predicates on Numbers ++ ++@noindent ++These functions return @code{t} if the specified condition is ++true of the numerical argument, or @code{nil} otherwise. ++ ++@defun plusp number ++This predicate tests whether @var{number} is positive. It is an ++error if the argument is not a number. ++@end defun ++ ++@defun minusp number ++This predicate tests whether @var{number} is negative. It is an ++error if the argument is not a number. ++@end defun ++ ++@defun oddp integer ++This predicate tests whether @var{integer} is odd. It is an ++error if the argument is not an integer. ++@end defun ++ ++@defun evenp integer ++This predicate tests whether @var{integer} is even. It is an ++error if the argument is not an integer. ++@end defun ++ ++@defun floatp-safe object ++This predicate tests whether @var{object} is a floating-point ++number. On systems that support floating-point, this is equivalent ++to @code{floatp}. On other systems, this always returns @code{nil}. ++@end defun ++ ++@iftex ++@secno=3 ++@end iftex ++ ++@node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers ++@section Numerical Functions ++ ++@noindent ++These functions perform various arithmetic operations on numbers. ++ ++@defun gcd &rest integers ++This function returns the Greatest Common Divisor of the arguments. ++For one argument, it returns the absolute value of that argument. ++For zero arguments, it returns zero. ++@end defun ++ ++@defun lcm &rest integers ++This function returns the Least Common Multiple of the arguments. ++For one argument, it returns the absolute value of that argument. ++For zero arguments, it returns one. ++@end defun ++ ++@defun isqrt integer ++This function computes the ``integer square root'' of its integer ++argument, i.e., the greatest integer less than or equal to the true ++square root of the argument. ++@end defun ++ ++@defun floor* number &optional divisor ++This function implements the Common Lisp @code{floor} function. ++It is called @code{floor*} to avoid name conflicts with the ++simpler @code{floor} function built-in to Emacs. ++ ++With one argument, @code{floor*} returns a list of two numbers: ++The argument rounded down (toward minus infinity) to an integer, ++and the ``remainder'' which would have to be added back to the ++first return value to yield the argument again. If the argument ++is an integer @var{x}, the result is always the list @code{(@var{x} 0)}. ++If the argument is a floating-point number, the first ++result is a Lisp integer and the second is a Lisp float between ++0 (inclusive) and 1 (exclusive). ++ ++With two arguments, @code{floor*} divides @var{number} by ++@var{divisor}, and returns the floor of the quotient and the ++corresponding remainder as a list of two numbers. If ++@code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})}, ++then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r} ++between 0 (inclusive) and @var{r} (exclusive). Also, note ++that @code{(floor* @var{x})} is exactly equivalent to ++@code{(floor* @var{x} 1)}. ++ ++This function is entirely compatible with Common Lisp's @code{floor} ++function, except that it returns the two results in a list since ++Emacs Lisp does not support multiple-valued functions. ++@end defun ++ ++@defun ceiling* number &optional divisor ++This function implements the Common Lisp @code{ceiling} function, ++which is analogous to @code{floor} except that it rounds the ++argument or quotient of the arguments up toward plus infinity. ++The remainder will be between 0 and minus @var{r}. ++@end defun ++ ++@defun truncate* number &optional divisor ++This function implements the Common Lisp @code{truncate} function, ++which is analogous to @code{floor} except that it rounds the ++argument or quotient of the arguments toward zero. Thus it is ++equivalent to @code{floor*} if the argument or quotient is ++positive, or to @code{ceiling*} otherwise. The remainder has ++the same sign as @var{number}. ++@end defun ++ ++@defun round* number &optional divisor ++This function implements the Common Lisp @code{round} function, ++which is analogous to @code{floor} except that it rounds the ++argument or quotient of the arguments to the nearest integer. ++In the case of a tie (the argument or quotient is exactly ++halfway between two integers), it rounds to the even integer. ++@end defun ++ ++@defun mod* number divisor ++This function returns the same value as the second return value ++of @code{floor}. ++@end defun ++ ++@defun rem* number divisor ++This function returns the same value as the second return value ++of @code{truncate}. ++@end defun ++ ++These definitions are compatible with those in the Quiroz ++@file{cl.el} package, except that this package appends @samp{*} ++to certain function names to avoid conflicts with existing ++Emacs functions, and that the mechanism for returning ++multiple values is different. ++ ++@iftex ++@secno=8 ++@end iftex ++ ++@node Random Numbers, Implementation Parameters, Numerical Functions, Numbers ++@section Random Numbers ++ ++@noindent ++This package also provides an implementation of the Common Lisp ++random number generator. It uses its own additive-congruential ++algorithm, which is much more likely to give statistically clean ++random numbers than the simple generators supplied by many ++operating systems. ++ ++@defun random* number &optional state ++This function returns a random nonnegative number less than ++@var{number}, and of the same type (either integer or floating-point). ++The @var{state} argument should be a @code{random-state} object ++which holds the state of the random number generator. The ++function modifies this state object as a side effect. If ++@var{state} is omitted, it defaults to the variable ++@code{*random-state*}, which contains a pre-initialized ++@code{random-state} object. ++@end defun ++ ++@defvar *random-state* ++This variable contains the system ``default'' @code{random-state} ++object, used for calls to @code{random*} that do not specify an ++alternative state object. Since any number of programs in the ++Emacs process may be accessing @code{*random-state*} in interleaved ++fashion, the sequence generated from this variable will be ++irreproducible for all intents and purposes. ++@end defvar ++ ++@defun make-random-state &optional state ++This function creates or copies a @code{random-state} object. ++If @var{state} is omitted or @code{nil}, it returns a new copy of ++@code{*random-state*}. This is a copy in the sense that future ++sequences of calls to @code{(random* @var{n})} and ++@code{(random* @var{n} @var{s})} (where @var{s} is the new ++random-state object) will return identical sequences of random ++numbers. ++ ++If @var{state} is a @code{random-state} object, this function ++returns a copy of that object. If @var{state} is @code{t}, this ++function returns a new @code{random-state} object seeded from the ++date and time. As an extension to Common Lisp, @var{state} may also ++be an integer in which case the new object is seeded from that ++integer; each different integer seed will result in a completely ++different sequence of random numbers. ++ ++It is valid to print a @code{random-state} object to a buffer or ++file and later read it back with @code{read}. If a program wishes ++to use a sequence of pseudo-random numbers which can be reproduced ++later for debugging, it can call @code{(make-random-state t)} to ++get a new sequence, then print this sequence to a file. When the ++program is later rerun, it can read the original run's random-state ++from the file. ++@end defun ++ ++@defun random-state-p object ++This predicate returns @code{t} if @var{object} is a ++@code{random-state} object, or @code{nil} otherwise. ++@end defun ++ ++@node Implementation Parameters, , Random Numbers, Numbers ++@section Implementation Parameters ++ ++@noindent ++This package defines several useful constants having to with numbers. ++ ++The following parameters have to do with floating-point numbers. ++This package determines their values by exercising the computer's ++floating-point arithmetic in various ways. Because this operation ++might be slow, the code for initializing them is kept in a separate ++function that must be called before the parameters can be used. ++ ++@defun cl-float-limits ++This function makes sure that the Common Lisp floating-point parameters ++like @code{most-positive-float} have been initialized. Until it is ++called, these parameters will be @code{nil}. If this version of Emacs ++does not support floats, the parameters will remain @code{nil}. If the ++parameters have already been initialized, the function returns ++immediately. ++ ++The algorithm makes assumptions that will be valid for most modern ++machines, but will fail if the machine's arithmetic is extremely ++unusual, e.g., decimal. ++@end defun ++ ++Since true Common Lisp supports up to four different floating-point ++precisions, it has families of constants like ++@code{most-positive-single-float}, @code{most-positive-double-float}, ++@code{most-positive-long-float}, and so on. Emacs has only one ++floating-point precision, so this package omits the precision word ++from the constants' names. ++ ++@defvar most-positive-float ++This constant equals the largest value a Lisp float can hold. ++For those systems whose arithmetic supports infinities, this is ++the largest @emph{finite} value. For IEEE machines, the value ++is approximately @code{1.79e+308}. ++@end defvar ++ ++@defvar most-negative-float ++This constant equals the most-negative value a Lisp float can hold. ++(It is assumed to be equal to @code{(- most-positive-float)}.) ++@end defvar ++ ++@defvar least-positive-float ++This constant equals the smallest Lisp float value greater than zero. ++For IEEE machines, it is about @code{4.94e-324} if denormals are ++supported or @code{2.22e-308} if not. ++@end defvar ++ ++@defvar least-positive-normalized-float ++This constant equals the smallest @emph{normalized} Lisp float greater ++than zero, i.e., the smallest value for which IEEE denormalization ++will not result in a loss of precision. For IEEE machines, this ++value is about @code{2.22e-308}. For machines that do not support ++the concept of denormalization and gradual underflow, this constant ++will always equal @code{least-positive-float}. ++@end defvar ++ ++@defvar least-negative-float ++This constant is the negative counterpart of @code{least-positive-float}. ++@end defvar ++ ++@defvar least-negative-normalized-float ++This constant is the negative counterpart of ++@code{least-positive-normalized-float}. ++@end defvar ++ ++@defvar float-epsilon ++This constant is the smallest positive Lisp float that can be added ++to 1.0 to produce a distinct value. Adding a smaller number to 1.0 ++will yield 1.0 again due to roundoff. For IEEE machines, epsilon ++is about @code{2.22e-16}. ++@end defvar ++ ++@defvar float-negative-epsilon ++This is the smallest positive value that can be subtracted from ++1.0 to produce a distinct value. For IEEE machines, it is about ++@code{1.11e-16}. ++@end defvar ++ ++@iftex ++@chapno=13 ++@end iftex ++ ++@node Sequences, Lists, Numbers, Top ++@chapter Sequences ++ ++@noindent ++Common Lisp defines a number of functions that operate on ++@dfn{sequences}, which are either lists, strings, or vectors. ++Emacs Lisp includes a few of these, notably @code{elt} and ++@code{length}; this package defines most of the rest. ++ ++@menu ++* Sequence Basics:: Arguments shared by all sequence functions ++* Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc. ++* Sequence Functions:: `subseq', `remove*', `substitute', etc. ++* Searching Sequences:: `find', `position', `count', `search', etc. ++* Sorting Sequences:: `sort*', `stable-sort', `merge' ++@end menu ++ ++@node Sequence Basics, Mapping over Sequences, Sequences, Sequences ++@section Sequence Basics ++ ++@noindent ++Many of the sequence functions take keyword arguments; @pxref{Argument ++Lists}. All keyword arguments are optional and, if specified, ++may appear in any order. ++ ++The @code{:key} argument should be passed either @code{nil}, or a ++function of one argument. This key function is used as a filter ++through which the elements of the sequence are seen; for example, ++@code{(find x y :key 'car)} is similar to @code{(assoc* x y)}: ++It searches for an element of the list whose @code{car} equals ++@code{x}, rather than for an element which equals @code{x} itself. ++If @code{:key} is omitted or @code{nil}, the filter is effectively ++the identity function. ++ ++The @code{:test} and @code{:test-not} arguments should be either ++@code{nil}, or functions of two arguments. The test function is ++used to compare two sequence elements, or to compare a search value ++with sequence elements. (The two values are passed to the test ++function in the same order as the original sequence function ++arguments from which they are derived, or, if they both come from ++the same sequence, in the same order as they appear in that sequence.) ++The @code{:test} argument specifies a function which must return ++true (non-@code{nil}) to indicate a match; instead, you may use ++@code{:test-not} to give a function which returns @emph{false} to ++indicate a match. The default test function is @code{eql}. ++ ++Many functions which take @var{item} and @code{:test} or @code{:test-not} ++arguments also come in @code{-if} and @code{-if-not} varieties, ++where a @var{predicate} function is passed instead of @var{item}, ++and sequence elements match if the predicate returns true on them ++(or false in the case of @code{-if-not}). For example: ++ ++@example ++(remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq) ++@end example ++ ++@noindent ++to remove all zeros from sequence @code{seq}. ++ ++Some operations can work on a subsequence of the argument sequence; ++these function take @code{:start} and @code{:end} arguments which ++default to zero and the length of the sequence, respectively. ++Only elements between @var{start} (inclusive) and @var{end} ++(exclusive) are affected by the operation. The @var{end} argument ++may be passed @code{nil} to signify the length of the sequence; ++otherwise, both @var{start} and @var{end} must be integers, with ++@code{0 <= @var{start} <= @var{end} <= (length @var{seq})}. ++If the function takes two sequence arguments, the limits are ++defined by keywords @code{:start1} and @code{:end1} for the first, ++and @code{:start2} and @code{:end2} for the second. ++ ++A few functions accept a @code{:from-end} argument, which, if ++non-@code{nil}, causes the operation to go from right-to-left ++through the sequence instead of left-to-right, and a @code{:count} ++argument, which specifies an integer maximum number of elements ++to be removed or otherwise processed. ++ ++The sequence functions make no guarantees about the order in ++which the @code{:test}, @code{:test-not}, and @code{:key} functions ++are called on various elements. Therefore, it is a bad idea to depend ++on side effects of these functions. For example, @code{:from-end} ++may cause the sequence to be scanned actually in reverse, or it may ++be scanned forwards but computing a result ``as if'' it were scanned ++backwards. (Some functions, like @code{mapcar*} and @code{every}, ++@emph{do} specify exactly the order in which the function is called ++so side effects are perfectly acceptable in those cases.) ++ ++Strings may contain ``text properties'' as well ++as character data. Except as noted, it is undefined whether or ++not text properties are preserved by sequence functions. For ++example, @code{(remove* ?A @var{str})} may or may not preserve ++the properties of the characters copied from @var{str} into the ++result. ++ ++@node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences ++@section Mapping over Sequences ++ ++@noindent ++These functions ``map'' the function you specify over the elements ++of lists or arrays. They are all variations on the theme of the ++built-in function @code{mapcar}. ++ ++@defun mapcar* function seq &rest more-seqs ++This function calls @var{function} on successive parallel sets of ++elements from its argument sequences. Given a single @var{seq} ++argument it is equivalent to @code{mapcar}; given @var{n} sequences, ++it calls the function with the first elements of each of the sequences ++as the @var{n} arguments to yield the first element of the result ++list, then with the second elements, and so on. The mapping stops as ++soon as the shortest sequence runs out. The argument sequences may ++be any mixture of lists, strings, and vectors; the return sequence ++is always a list. ++ ++Common Lisp's @code{mapcar} accepts multiple arguments but works ++only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence ++argument. This package's @code{mapcar*} works as a compatible ++superset of both. ++@end defun ++ ++@defun map result-type function seq &rest more-seqs ++This function maps @var{function} over the argument sequences, ++just like @code{mapcar*}, but it returns a sequence of type ++@var{result-type} rather than a list. @var{result-type} must ++be one of the following symbols: @code{vector}, @code{string}, ++@code{list} (in which case the effect is the same as for ++@code{mapcar*}), or @code{nil} (in which case the results are ++thrown away and @code{map} returns @code{nil}). ++@end defun ++ ++@defun maplist function list &rest more-lists ++This function calls @var{function} on each of its argument lists, ++then on the @code{cdr}s of those lists, and so on, until the ++shortest list runs out. The results are returned in the form ++of a list. Thus, @code{maplist} is like @code{mapcar*} except ++that it passes in the list pointers themselves rather than the ++@code{car}s of the advancing pointers. ++@end defun ++ ++@defun mapc function seq &rest more-seqs ++This function is like @code{mapcar*}, except that the values returned ++by @var{function} are ignored and thrown away rather than being ++collected into a list. The return value of @code{mapc} is @var{seq}, ++the first sequence. This function is more general than the Emacs ++primitive @code{mapc}. ++@end defun ++ ++@defun mapl function list &rest more-lists ++This function is like @code{maplist}, except that it throws away ++the values returned by @var{function}. ++@end defun ++ ++@defun mapcan function seq &rest more-seqs ++This function is like @code{mapcar*}, except that it concatenates ++the return values (which must be lists) using @code{nconc}, ++rather than simply collecting them into a list. ++@end defun ++ ++@defun mapcon function list &rest more-lists ++This function is like @code{maplist}, except that it concatenates ++the return values using @code{nconc}. ++@end defun ++ ++@defun some predicate seq &rest more-seqs ++This function calls @var{predicate} on each element of @var{seq} ++in turn; if @var{predicate} returns a non-@code{nil} value, ++@code{some} returns that value, otherwise it returns @code{nil}. ++Given several sequence arguments, it steps through the sequences ++in parallel until the shortest one runs out, just as in ++@code{mapcar*}. You can rely on the left-to-right order in which ++the elements are visited, and on the fact that mapping stops ++immediately as soon as @var{predicate} returns non-@code{nil}. ++@end defun ++ ++@defun every predicate seq &rest more-seqs ++This function calls @var{predicate} on each element of the sequence(s) ++in turn; it returns @code{nil} as soon as @var{predicate} returns ++@code{nil} for any element, or @code{t} if the predicate was true ++for all elements. ++@end defun ++ ++@defun notany predicate seq &rest more-seqs ++This function calls @var{predicate} on each element of the sequence(s) ++in turn; it returns @code{nil} as soon as @var{predicate} returns ++a non-@code{nil} value for any element, or @code{t} if the predicate ++was @code{nil} for all elements. ++@end defun ++ ++@defun notevery predicate seq &rest more-seqs ++This function calls @var{predicate} on each element of the sequence(s) ++in turn; it returns a non-@code{nil} value as soon as @var{predicate} ++returns @code{nil} for any element, or @code{t} if the predicate was ++true for all elements. ++@end defun ++ ++@defun reduce function seq @t{&key :from-end :start :end :initial-value :key} ++This function combines the elements of @var{seq} using an associative ++binary operation. Suppose @var{function} is @code{*} and @var{seq} is ++the list @code{(2 3 4 5)}. The first two elements of the list are ++combined with @code{(* 2 3) = 6}; this is combined with the next ++element, @code{(* 6 4) = 24}, and that is combined with the final ++element: @code{(* 24 5) = 120}. Note that the @code{*} function happens ++to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as ++an explicit call to @code{reduce}. ++ ++If @code{:from-end} is true, the reduction is right-associative instead ++of left-associative: ++ ++@example ++(reduce '- '(1 2 3 4)) ++ @equiv{} (- (- (- 1 2) 3) 4) @result{} -8 ++(reduce '- '(1 2 3 4) :from-end t) ++ @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2 ++@end example ++ ++If @code{:key} is specified, it is a function of one argument which ++is called on each of the sequence elements in turn. ++ ++If @code{:initial-value} is specified, it is effectively added to the ++front (or rear in the case of @code{:from-end}) of the sequence. ++The @code{:key} function is @emph{not} applied to the initial value. ++ ++If the sequence, including the initial value, has exactly one element ++then that element is returned without ever calling @var{function}. ++If the sequence is empty (and there is no initial value), then ++@var{function} is called with no arguments to obtain the return value. ++@end defun ++ ++All of these mapping operations can be expressed conveniently in ++terms of the @code{loop} macro. In compiled code, @code{loop} will ++be faster since it generates the loop as in-line code with no ++function calls. ++ ++@node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences ++@section Sequence Functions ++ ++@noindent ++This section describes a number of Common Lisp functions for ++operating on sequences. ++ ++@defun subseq sequence start &optional end ++This function returns a given subsequence of the argument ++@var{sequence}, which may be a list, string, or vector. ++The indices @var{start} and @var{end} must be in range, and ++@var{start} must be no greater than @var{end}. If @var{end} ++is omitted, it defaults to the length of the sequence. The ++return value is always a copy; it does not share structure ++with @var{sequence}. ++ ++As an extension to Common Lisp, @var{start} and/or @var{end} ++may be negative, in which case they represent a distance back ++from the end of the sequence. This is for compatibility with ++Emacs' @code{substring} function. Note that @code{subseq} is ++the @emph{only} sequence function that allows negative ++@var{start} and @var{end}. ++ ++You can use @code{setf} on a @code{subseq} form to replace a ++specified range of elements with elements from another sequence. ++The replacement is done as if by @code{replace}, described below. ++@end defun ++ ++@defun concatenate result-type &rest seqs ++This function concatenates the argument sequences together to ++form a result sequence of type @var{result-type}, one of the ++symbols @code{vector}, @code{string}, or @code{list}. The ++arguments are always copied, even in cases such as ++@code{(concatenate 'list '(1 2 3))} where the result is ++identical to an argument. ++@end defun ++ ++@defun fill seq item @t{&key :start :end} ++This function fills the elements of the sequence (or the specified ++part of the sequence) with the value @var{item}. ++@end defun ++ ++@defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2} ++This function copies part of @var{seq2} into part of @var{seq1}. ++The sequence @var{seq1} is not stretched or resized; the amount ++of data copied is simply the shorter of the source and destination ++(sub)sequences. The function returns @var{seq1}. ++ ++If @var{seq1} and @var{seq2} are @code{eq}, then the replacement ++will work correctly even if the regions indicated by the start ++and end arguments overlap. However, if @var{seq1} and @var{seq2} ++are lists which share storage but are not @code{eq}, and the ++start and end arguments specify overlapping regions, the effect ++is undefined. ++@end defun ++ ++@defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end} ++This returns a copy of @var{seq} with all elements matching ++@var{item} removed. The result may share storage with or be ++@code{eq} to @var{seq} in some circumstances, but the original ++@var{seq} will not be modified. The @code{:test}, @code{:test-not}, ++and @code{:key} arguments define the matching test that is used; ++by default, elements @code{eql} to @var{item} are removed. The ++@code{:count} argument specifies the maximum number of matching ++elements that can be removed (only the leftmost @var{count} matches ++are removed). The @code{:start} and @code{:end} arguments specify ++a region in @var{seq} in which elements will be removed; elements ++outside that region are not matched or removed. The @code{:from-end} ++argument, if true, says that elements should be deleted from the ++end of the sequence rather than the beginning (this matters only ++if @var{count} was also specified). ++@end defun ++ ++@defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end} ++This deletes all elements of @var{seq} which match @var{item}. ++It is a destructive operation. Since Emacs Lisp does not support ++stretchable strings or vectors, this is the same as @code{remove*} ++for those sequence types. On lists, @code{remove*} will copy the ++list if necessary to preserve the original list, whereas ++@code{delete*} will splice out parts of the argument list. ++Compare @code{append} and @code{nconc}, which are analogous ++non-destructive and destructive list operations in Emacs Lisp. ++@end defun ++ ++@findex remove-if ++@findex remove-if-not ++@findex delete-if ++@findex delete-if-not ++The predicate-oriented functions @code{remove-if}, @code{remove-if-not}, ++@code{delete-if}, and @code{delete-if-not} are defined similarly. ++ ++@defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end} ++This function returns a copy of @var{seq} with duplicate elements ++removed. Specifically, if two elements from the sequence match ++according to the @code{:test}, @code{:test-not}, and @code{:key} ++arguments, only the rightmost one is retained. If @code{:from-end} ++is true, the leftmost one is retained instead. If @code{:start} or ++@code{:end} is specified, only elements within that subsequence are ++examined or removed. ++@end defun ++ ++@defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end} ++This function deletes duplicate elements from @var{seq}. It is ++a destructive version of @code{remove-duplicates}. ++@end defun ++ ++@defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} ++This function returns a copy of @var{seq}, with all elements ++matching @var{old} replaced with @var{new}. The @code{:count}, ++@code{:start}, @code{:end}, and @code{:from-end} arguments may be ++used to limit the number of substitutions made. ++@end defun ++ ++@defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} ++This is a destructive version of @code{substitute}; it performs ++the substitution using @code{setcar} or @code{aset} rather than ++by returning a changed copy of the sequence. ++@end defun ++ ++@findex substitute-if ++@findex substitute-if-not ++@findex nsubstitute-if ++@findex nsubstitute-if-not ++The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if}, ++and @code{nsubstitute-if-not} functions are defined similarly. For ++these, a @var{predicate} is given in place of the @var{old} argument. ++ ++@node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences ++@section Searching Sequences ++ ++@noindent ++These functions search for elements or subsequences in a sequence. ++(See also @code{member*} and @code{assoc*}; @pxref{Lists}.) ++ ++@defun find item seq @t{&key :test :test-not :key :start :end :from-end} ++This function searches @var{seq} for an element matching @var{item}. ++If it finds a match, it returns the matching element. Otherwise, ++it returns @code{nil}. It returns the leftmost match, unless ++@code{:from-end} is true, in which case it returns the rightmost ++match. The @code{:start} and @code{:end} arguments may be used to ++limit the range of elements that are searched. ++@end defun ++ ++@defun position item seq @t{&key :test :test-not :key :start :end :from-end} ++This function is like @code{find}, except that it returns the ++integer position in the sequence of the matching item rather than ++the item itself. The position is relative to the start of the ++sequence as a whole, even if @code{:start} is non-zero. The function ++returns @code{nil} if no matching element was found. ++@end defun ++ ++@defun count item seq @t{&key :test :test-not :key :start :end} ++This function returns the number of elements of @var{seq} which ++match @var{item}. The result is always a nonnegative integer. ++@end defun ++ ++@findex find-if ++@findex find-if-not ++@findex position-if ++@findex position-if-not ++@findex count-if ++@findex count-if-not ++The @code{find-if}, @code{find-if-not}, @code{position-if}, ++@code{position-if-not}, @code{count-if}, and @code{count-if-not} ++functions are defined similarly. ++ ++@defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end} ++This function compares the specified parts of @var{seq1} and ++@var{seq2}. If they are the same length and the corresponding ++elements match (according to @code{:test}, @code{:test-not}, ++and @code{:key}), the function returns @code{nil}. If there is ++a mismatch, the function returns the index (relative to @var{seq1}) ++of the first mismatching element. This will be the leftmost pair of ++elements which do not match, or the position at which the shorter of ++the two otherwise-matching sequences runs out. ++ ++If @code{:from-end} is true, then the elements are compared from right ++to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}. ++If the sequences differ, then one plus the index of the rightmost ++difference (relative to @var{seq1}) is returned. ++ ++An interesting example is @code{(mismatch str1 str2 :key 'upcase)}, ++which compares two strings case-insensitively. ++@end defun ++ ++@defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2} ++This function searches @var{seq2} for a subsequence that matches ++@var{seq1} (or part of it specified by @code{:start1} and ++@code{:end1}.) Only matches which fall entirely within the region ++defined by @code{:start2} and @code{:end2} will be considered. ++The return value is the index of the leftmost element of the ++leftmost match, relative to the start of @var{seq2}, or @code{nil} ++if no matches were found. If @code{:from-end} is true, the ++function finds the @emph{rightmost} matching subsequence. ++@end defun ++ ++@node Sorting Sequences, , Searching Sequences, Sequences ++@section Sorting Sequences ++ ++@defun sort* seq predicate @t{&key :key} ++This function sorts @var{seq} into increasing order as determined ++by using @var{predicate} to compare pairs of elements. @var{predicate} ++should return true (non-@code{nil}) if and only if its first argument ++is less than (not equal to) its second argument. For example, ++@code{<} and @code{string-lessp} are suitable predicate functions ++for sorting numbers and strings, respectively; @code{>} would sort ++numbers into decreasing rather than increasing order. ++ ++This function differs from Emacs' built-in @code{sort} in that it ++can operate on any type of sequence, not just lists. Also, it ++accepts a @code{:key} argument which is used to preprocess data ++fed to the @var{predicate} function. For example, ++ ++@example ++(setq data (sort* data 'string-lessp :key 'downcase)) ++@end example ++ ++@noindent ++sorts @var{data}, a sequence of strings, into increasing alphabetical ++order without regard to case. A @code{:key} function of @code{car} ++would be useful for sorting association lists. It should only be a ++simple accessor though, it's used heavily in the current ++implementation. ++ ++The @code{sort*} function is destructive; it sorts lists by actually ++rearranging the @code{cdr} pointers in suitable fashion. ++@end defun ++ ++@defun stable-sort seq predicate @t{&key :key} ++This function sorts @var{seq} @dfn{stably}, meaning two elements ++which are equal in terms of @var{predicate} are guaranteed not to ++be rearranged out of their original order by the sort. ++ ++In practice, @code{sort*} and @code{stable-sort} are equivalent ++in Emacs Lisp because the underlying @code{sort} function is ++stable by default. However, this package reserves the right to ++use non-stable methods for @code{sort*} in the future. ++@end defun ++ ++@defun merge type seq1 seq2 predicate @t{&key :key} ++This function merges two sequences @var{seq1} and @var{seq2} by ++interleaving their elements. The result sequence, of type @var{type} ++(in the sense of @code{concatenate}), has length equal to the sum ++of the lengths of the two input sequences. The sequences may be ++modified destructively. Order of elements within @var{seq1} and ++@var{seq2} is preserved in the interleaving; elements of the two ++sequences are compared by @var{predicate} (in the sense of ++@code{sort}) and the lesser element goes first in the result. ++When elements are equal, those from @var{seq1} precede those from ++@var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are ++both sorted according to @var{predicate}, then the result will be ++a merged sequence which is (stably) sorted according to ++@var{predicate}. ++@end defun ++ ++@node Lists, Structures, Sequences, Top ++@chapter Lists ++ ++@noindent ++The functions described here operate on lists. ++ ++@menu ++* List Functions:: `caddr', `first', `list*', etc. ++* Substitution of Expressions:: `subst', `sublis', etc. ++* Lists as Sets:: `member*', `adjoin', `union', etc. ++* Association Lists:: `assoc*', `rassoc*', `acons', `pairlis' ++@end menu ++ ++@node List Functions, Substitution of Expressions, Lists, Lists ++@section List Functions ++ ++@noindent ++This section describes a number of simple operations on lists, ++i.e., chains of cons cells. ++ ++@defun caddr x ++This function is equivalent to @code{(car (cdr (cdr @var{x})))}. ++Likewise, this package defines all 28 @code{c@var{xxx}r} functions ++where @var{xxx} is up to four @samp{a}s and/or @samp{d}s. ++All of these functions are @code{setf}-able, and calls to them ++are expanded inline by the byte-compiler for maximum efficiency. ++@end defun ++ ++@defun first x ++This function is a synonym for @code{(car @var{x})}. Likewise, ++the functions @code{second}, @code{third}, @dots{}, through ++@code{tenth} return the given element of the list @var{x}. ++@end defun ++ ++@defun rest x ++This function is a synonym for @code{(cdr @var{x})}. ++@end defun ++ ++@defun endp x ++Common Lisp defines this function to act like @code{null}, but ++signaling an error if @code{x} is neither a @code{nil} nor a ++cons cell. This package simply defines @code{endp} as a synonym ++for @code{null}. ++@end defun ++ ++@defun list-length x ++This function returns the length of list @var{x}, exactly like ++@code{(length @var{x})}, except that if @var{x} is a circular ++list (where the cdr-chain forms a loop rather than terminating ++with @code{nil}), this function returns @code{nil}. (The regular ++@code{length} function would get stuck if given a circular list.) ++@end defun ++ ++@defun list* arg &rest others ++This function constructs a list of its arguments. The final ++argument becomes the @code{cdr} of the last cell constructed. ++Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to ++@code{(cons @var{a} (cons @var{b} @var{c}))}, and ++@code{(list* @var{a} @var{b} nil)} is equivalent to ++@code{(list @var{a} @var{b})}. ++ ++(Note that this function really is called @code{list*} in Common ++Lisp; it is not a name invented for this package like @code{member*} ++or @code{defun*}.) ++@end defun ++ ++@defun ldiff list sublist ++If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to ++one of the cons cells of @var{list}, then this function returns ++a copy of the part of @var{list} up to but not including ++@var{sublist}. For example, @code{(ldiff x (cddr x))} returns ++the first two elements of the list @code{x}. The result is a ++copy; the original @var{list} is not modified. If @var{sublist} ++is not a sublist of @var{list}, a copy of the entire @var{list} ++is returned. ++@end defun ++ ++@defun copy-list list ++This function returns a copy of the list @var{list}. It copies ++dotted lists like @code{(1 2 . 3)} correctly. ++@end defun ++ ++@defun copy-tree x &optional vecp ++This function returns a copy of the tree of cons cells @var{x}. ++Unlike @code{copy-sequence} (and its alias @code{copy-list}), ++which copies only along the @code{cdr} direction, this function ++copies (recursively) along both the @code{car} and the @code{cdr} ++directions. If @var{x} is not a cons cell, the function simply ++returns @var{x} unchanged. If the optional @var{vecp} argument ++is true, this function copies vectors (recursively) as well as ++cons cells. ++@end defun ++ ++@defun tree-equal x y @t{&key :test :test-not :key} ++This function compares two trees of cons cells. If @var{x} and ++@var{y} are both cons cells, their @code{car}s and @code{cdr}s are ++compared recursively. If neither @var{x} nor @var{y} is a cons ++cell, they are compared by @code{eql}, or according to the ++specified test. The @code{:key} function, if specified, is ++applied to the elements of both trees. @xref{Sequences}. ++@end defun ++ ++@iftex ++@secno=3 ++@end iftex ++ ++@node Substitution of Expressions, Lists as Sets, List Functions, Lists ++@section Substitution of Expressions ++ ++@noindent ++These functions substitute elements throughout a tree of cons ++cells. (@xref{Sequence Functions}, for the @code{substitute} ++function, which works on just the top-level elements of a list.) ++ ++@defun subst new old tree @t{&key :test :test-not :key} ++This function substitutes occurrences of @var{old} with @var{new} ++in @var{tree}, a tree of cons cells. It returns a substituted ++tree, which will be a copy except that it may share storage with ++the argument @var{tree} in parts where no substitutions occurred. ++The original @var{tree} is not modified. This function recurses ++on, and compares against @var{old}, both @code{car}s and @code{cdr}s ++of the component cons cells. If @var{old} is itself a cons cell, ++then matching cells in the tree are substituted as usual without ++recursively substituting in that cell. Comparisons with @var{old} ++are done according to the specified test (@code{eql} by default). ++The @code{:key} function is applied to the elements of the tree ++but not to @var{old}. ++@end defun ++ ++@defun nsubst new old tree @t{&key :test :test-not :key} ++This function is like @code{subst}, except that it works by ++destructive modification (by @code{setcar} or @code{setcdr}) ++rather than copying. ++@end defun ++ ++@findex subst-if ++@findex subst-if-not ++@findex nsubst-if ++@findex nsubst-if-not ++The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and ++@code{nsubst-if-not} functions are defined similarly. ++ ++@defun sublis alist tree @t{&key :test :test-not :key} ++This function is like @code{subst}, except that it takes an ++association list @var{alist} of @var{old}-@var{new} pairs. ++Each element of the tree (after applying the @code{:key} ++function, if any), is compared with the @code{car}s of ++@var{alist}; if it matches, it is replaced by the corresponding ++@code{cdr}. ++@end defun ++ ++@defun nsublis alist tree @t{&key :test :test-not :key} ++This is a destructive version of @code{sublis}. ++@end defun ++ ++@node Lists as Sets, Association Lists, Substitution of Expressions, Lists ++@section Lists as Sets ++ ++@noindent ++These functions perform operations on lists which represent sets ++of elements. ++ ++@defun member* item list @t{&key :test :test-not :key} ++This function searches @var{list} for an element matching @var{item}. ++If a match is found, it returns the cons cell whose @code{car} was ++the matching element. Otherwise, it returns @code{nil}. Elements ++are compared by @code{eql} by default; you can use the @code{:test}, ++@code{:test-not}, and @code{:key} arguments to modify this behavior. ++@xref{Sequences}. ++ ++Note that this function's name is suffixed by @samp{*} to avoid ++the incompatible @code{member} function defined in Emacs. ++(That function uses @code{equal} for comparisons; it is equivalent ++to @code{(member* @var{item} @var{list} :test 'equal)}.) ++@end defun ++ ++@findex member-if ++@findex member-if-not ++The @code{member-if} and @code{member-if-not} functions ++analogously search for elements which satisfy a given predicate. ++ ++@defun tailp sublist list ++This function returns @code{t} if @var{sublist} is a sublist of ++@var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to ++any of its @code{cdr}s. ++@end defun ++ ++@defun adjoin item list @t{&key :test :test-not :key} ++This function conses @var{item} onto the front of @var{list}, ++like @code{(cons @var{item} @var{list})}, but only if @var{item} ++is not already present on the list (as determined by @code{member*}). ++If a @code{:key} argument is specified, it is applied to ++@var{item} as well as to the elements of @var{list} during ++the search, on the reasoning that @var{item} is ``about'' to ++become part of the list. ++@end defun ++ ++@defun union list1 list2 @t{&key :test :test-not :key} ++This function combines two lists which represent sets of items, ++returning a list that represents the union of those two sets. ++The result list will contain all items which appear in @var{list1} ++or @var{list2}, and no others. If an item appears in both ++@var{list1} and @var{list2} it will be copied only once. If ++an item is duplicated in @var{list1} or @var{list2}, it is ++undefined whether or not that duplication will survive in the ++result list. The order of elements in the result list is also ++undefined. ++@end defun ++ ++@defun nunion list1 list2 @t{&key :test :test-not :key} ++This is a destructive version of @code{union}; rather than copying, ++it tries to reuse the storage of the argument lists if possible. ++@end defun ++ ++@defun intersection list1 list2 @t{&key :test :test-not :key} ++This function computes the intersection of the sets represented ++by @var{list1} and @var{list2}. It returns the list of items ++which appear in both @var{list1} and @var{list2}. ++@end defun ++ ++@defun nintersection list1 list2 @t{&key :test :test-not :key} ++This is a destructive version of @code{intersection}. It ++tries to reuse storage of @var{list1} rather than copying. ++It does @emph{not} reuse the storage of @var{list2}. ++@end defun ++ ++@defun set-difference list1 list2 @t{&key :test :test-not :key} ++This function computes the ``set difference'' of @var{list1} ++and @var{list2}, i.e., the set of elements that appear in ++@var{list1} but @emph{not} in @var{list2}. ++@end defun ++ ++@defun nset-difference list1 list2 @t{&key :test :test-not :key} ++This is a destructive @code{set-difference}, which will try ++to reuse @var{list1} if possible. ++@end defun ++ ++@defun set-exclusive-or list1 list2 @t{&key :test :test-not :key} ++This function computes the ``set exclusive or'' of @var{list1} ++and @var{list2}, i.e., the set of elements that appear in ++exactly one of @var{list1} and @var{list2}. ++@end defun ++ ++@defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key} ++This is a destructive @code{set-exclusive-or}, which will try ++to reuse @var{list1} and @var{list2} if possible. ++@end defun ++ ++@defun subsetp list1 list2 @t{&key :test :test-not :key} ++This function checks whether @var{list1} represents a subset ++of @var{list2}, i.e., whether every element of @var{list1} ++also appears in @var{list2}. ++@end defun ++ ++@node Association Lists, , Lists as Sets, Lists ++@section Association Lists ++ ++@noindent ++An @dfn{association list} is a list representing a mapping from ++one set of values to another; any list whose elements are cons ++cells is an association list. ++ ++@defun assoc* item a-list @t{&key :test :test-not :key} ++This function searches the association list @var{a-list} for an ++element whose @code{car} matches (in the sense of @code{:test}, ++@code{:test-not}, and @code{:key}, or by comparison with @code{eql}) ++a given @var{item}. It returns the matching element, if any, ++otherwise @code{nil}. It ignores elements of @var{a-list} which ++are not cons cells. (This corresponds to the behavior of ++@code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's ++@code{assoc} ignores @code{nil}s but considers any other non-cons ++elements of @var{a-list} to be an error.) ++@end defun ++ ++@defun rassoc* item a-list @t{&key :test :test-not :key} ++This function searches for an element whose @code{cdr} matches ++@var{item}. If @var{a-list} represents a mapping, this applies ++the inverse of the mapping to @var{item}. ++@end defun ++ ++@findex assoc-if ++@findex assoc-if-not ++@findex rassoc-if ++@findex rassoc-if-not ++The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if}, ++and @code{rassoc-if-not} functions are defined similarly. ++ ++Two simple functions for constructing association lists are: ++ ++@defun acons key value alist ++This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}. ++@end defun ++ ++@defun pairlis keys values &optional alist ++This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values}) ++@var{alist})}. ++@end defun ++ ++@iftex ++@chapno=18 ++@end iftex ++ ++@node Structures, Assertions, Lists, Top ++@chapter Structures ++ ++@noindent ++The Common Lisp @dfn{structure} mechanism provides a general way ++to define data types similar to C's @code{struct} types. A ++structure is a Lisp object containing some number of @dfn{slots}, ++each of which can hold any Lisp data object. Functions are ++provided for accessing and setting the slots, creating or copying ++structure objects, and recognizing objects of a particular structure ++type. ++ ++In true Common Lisp, each structure type is a new type distinct ++from all existing Lisp types. Since the underlying Emacs Lisp ++system provides no way to create new distinct types, this package ++implements structures as vectors (or lists upon request) with a ++special ``tag'' symbol to identify them. ++ ++@defspec defstruct name slots@dots{} ++The @code{defstruct} form defines a new structure type called ++@var{name}, with the specified @var{slots}. (The @var{slots} ++may begin with a string which documents the structure type.) ++In the simplest case, @var{name} and each of the @var{slots} ++are symbols. For example, ++ ++@example ++(defstruct person name age sex) ++@end example ++ ++@noindent ++defines a struct type called @code{person} which contains three ++slots. Given a @code{person} object @var{p}, you can access those ++slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, ++and @code{(person-sex @var{p})}. You can also change these slots by ++using @code{setf} on any of these place forms: ++ ++@example ++(incf (person-age birthday-boy)) ++@end example ++ ++You can create a new @code{person} by calling @code{make-person}, ++which takes keyword arguments @code{:name}, @code{:age}, and ++@code{:sex} to specify the initial values of these slots in the ++new object. (Omitting any of these arguments leaves the corresponding ++slot ``undefined,'' according to the Common Lisp standard; in Emacs ++Lisp, such uninitialized slots are filled with @code{nil}.) ++ ++Given a @code{person}, @code{(copy-person @var{p})} makes a new ++object of the same type whose slots are @code{eq} to those of @var{p}. ++ ++Given any Lisp object @var{x}, @code{(person-p @var{x})} returns ++true if @var{x} looks like a @code{person}, false otherwise. (Again, ++in Common Lisp this predicate would be exact; in Emacs Lisp the ++best it can do is verify that @var{x} is a vector of the correct ++length which starts with the correct tag symbol.) ++ ++Accessors like @code{person-name} normally check their arguments ++(effectively using @code{person-p}) and signal an error if the ++argument is the wrong type. This check is affected by ++@code{(optimize (safety @dots{}))} declarations. Safety level 1, ++the default, uses a somewhat optimized check that will detect all ++incorrect arguments, but may use an uninformative error message ++(e.g., ``expected a vector'' instead of ``expected a @code{person}''). ++Safety level 0 omits all checks except as provided by the underlying ++@code{aref} call; safety levels 2 and 3 do rigorous checking that will ++always print a descriptive error message for incorrect inputs. ++@xref{Declarations}. ++ ++@example ++(setq dave (make-person :name "Dave" :sex 'male)) ++ @result{} [cl-struct-person "Dave" nil male] ++(setq other (copy-person dave)) ++ @result{} [cl-struct-person "Dave" nil male] ++(eq dave other) ++ @result{} nil ++(eq (person-name dave) (person-name other)) ++ @result{} t ++(person-p dave) ++ @result{} t ++(person-p [1 2 3 4]) ++ @result{} nil ++(person-p "Bogus") ++ @result{} nil ++(person-p '[cl-struct-person counterfeit person object]) ++ @result{} t ++@end example ++ ++In general, @var{name} is either a name symbol or a list of a name ++symbol followed by any number of @dfn{struct options}; each @var{slot} ++is either a slot symbol or a list of the form @samp{(@var{slot-name} ++@var{default-value} @var{slot-options}@dots{})}. The @var{default-value} ++is a Lisp form which is evaluated any time an instance of the ++structure type is created without specifying that slot's value. ++ ++Common Lisp defines several slot options, but the only one ++implemented in this package is @code{:read-only}. A non-@code{nil} ++value for this option means the slot should not be @code{setf}-able; ++the slot's value is determined when the object is created and does ++not change afterward. ++ ++@example ++(defstruct person ++ (name nil :read-only t) ++ age ++ (sex 'unknown)) ++@end example ++ ++Any slot options other than @code{:read-only} are ignored. ++ ++For obscure historical reasons, structure options take a different ++form than slot options. A structure option is either a keyword ++symbol, or a list beginning with a keyword symbol possibly followed ++by arguments. (By contrast, slot options are key-value pairs not ++enclosed in lists.) ++ ++@example ++(defstruct (person (:constructor create-person) ++ (:type list) ++ :named) ++ name age sex) ++@end example ++ ++The following structure options are recognized. ++ ++@table @code ++@iftex ++@itemmax=0 in ++@advance@leftskip-.5@tableindent ++@end iftex ++@item :conc-name ++The argument is a symbol whose print name is used as the prefix for ++the names of slot accessor functions. The default is the name of ++the struct type followed by a hyphen. The option @code{(:conc-name p-)} ++would change this prefix to @code{p-}. Specifying @code{nil} as an ++argument means no prefix, so that the slot names themselves are used ++to name the accessor functions. ++ ++@item :constructor ++In the simple case, this option takes one argument which is an ++alternate name to use for the constructor function. The default ++is @code{make-@var{name}}, e.g., @code{make-person}. The above ++example changes this to @code{create-person}. Specifying @code{nil} ++as an argument means that no standard constructor should be ++generated at all. ++ ++In the full form of this option, the constructor name is followed ++by an arbitrary argument list. @xref{Program Structure}, for a ++description of the format of Common Lisp argument lists. All ++options, such as @code{&rest} and @code{&key}, are supported. ++The argument names should match the slot names; each slot is ++initialized from the corresponding argument. Slots whose names ++do not appear in the argument list are initialized based on the ++@var{default-value} in their slot descriptor. Also, @code{&optional} ++and @code{&key} arguments which don't specify defaults take their ++defaults from the slot descriptor. It is valid to include arguments ++which don't correspond to slot names; these are useful if they are ++referred to in the defaults for optional, keyword, or @code{&aux} ++arguments which @emph{do} correspond to slots. ++ ++You can specify any number of full-format @code{:constructor} ++options on a structure. The default constructor is still generated ++as well unless you disable it with a simple-format @code{:constructor} ++option. ++ ++@example ++(defstruct ++ (person ++ (:constructor nil) ; no default constructor ++ (:constructor new-person (name sex &optional (age 0))) ++ (:constructor new-hound (&key (name "Rover") ++ (dog-years 0) ++ &aux (age (* 7 dog-years)) ++ (sex 'canine)))) ++ name age sex) ++@end example ++ ++The first constructor here takes its arguments positionally rather ++than by keyword. (In official Common Lisp terminology, constructors ++that work By Order of Arguments instead of by keyword are called ++``BOA constructors.'' No, I'm not making this up.) For example, ++@code{(new-person "Jane" 'female)} generates a person whose slots ++are @code{"Jane"}, 0, and @code{female}, respectively. ++ ++The second constructor takes two keyword arguments, @code{:name}, ++which initializes the @code{name} slot and defaults to @code{"Rover"}, ++and @code{:dog-years}, which does not itself correspond to a slot ++but which is used to initialize the @code{age} slot. The @code{sex} ++slot is forced to the symbol @code{canine} with no syntax for ++overriding it. ++ ++@item :copier ++The argument is an alternate name for the copier function for ++this type. The default is @code{copy-@var{name}}. @code{nil} ++means not to generate a copier function. (In this implementation, ++all copier functions are simply synonyms for @code{copy-sequence}.) ++ ++@item :predicate ++The argument is an alternate name for the predicate which recognizes ++objects of this type. The default is @code{@var{name}-p}. @code{nil} ++means not to generate a predicate function. (If the @code{:type} ++option is used without the @code{:named} option, no predicate is ++ever generated.) ++ ++In true Common Lisp, @code{typep} is always able to recognize a ++structure object even if @code{:predicate} was used. In this ++package, @code{typep} simply looks for a function called ++@code{@var{typename}-p}, so it will work for structure types ++only if they used the default predicate name. ++ ++@item :include ++This option implements a very limited form of C++-style inheritance. ++The argument is the name of another structure type previously ++created with @code{defstruct}. The effect is to cause the new ++structure type to inherit all of the included structure's slots ++(plus, of course, any new slots described by this struct's slot ++descriptors). The new structure is considered a ``specialization'' ++of the included one. In fact, the predicate and slot accessors ++for the included type will also accept objects of the new type. ++ ++If there are extra arguments to the @code{:include} option after ++the included-structure name, these options are treated as replacement ++slot descriptors for slots in the included structure, possibly with ++modified default values. Borrowing an example from Steele: ++ ++@example ++(defstruct person name (age 0) sex) ++ @result{} person ++(defstruct (astronaut (:include person (age 45))) ++ helmet-size ++ (favorite-beverage 'tang)) ++ @result{} astronaut ++ ++(setq joe (make-person :name "Joe")) ++ @result{} [cl-struct-person "Joe" 0 nil] ++(setq buzz (make-astronaut :name "Buzz")) ++ @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang] ++ ++(list (person-p joe) (person-p buzz)) ++ @result{} (t t) ++(list (astronaut-p joe) (astronaut-p buzz)) ++ @result{} (nil t) ++ ++(person-name buzz) ++ @result{} "Buzz" ++(astronaut-name joe) ++ @result{} error: "astronaut-name accessing a non-astronaut" ++@end example ++ ++Thus, if @code{astronaut} is a specialization of @code{person}, ++then every @code{astronaut} is also a @code{person} (but not the ++other way around). Every @code{astronaut} includes all the slots ++of a @code{person}, plus extra slots that are specific to ++astronauts. Operations that work on people (like @code{person-name}) ++work on astronauts just like other people. ++ ++@item :print-function ++In full Common Lisp, this option allows you to specify a function ++which is called to print an instance of the structure type. The ++Emacs Lisp system offers no hooks into the Lisp printer which would ++allow for such a feature, so this package simply ignores ++@code{:print-function}. ++ ++@item :type ++The argument should be one of the symbols @code{vector} or @code{list}. ++This tells which underlying Lisp data type should be used to implement ++the new structure type. Vectors are used by default, but ++@code{(:type list)} will cause structure objects to be stored as ++lists instead. ++ ++The vector representation for structure objects has the advantage ++that all structure slots can be accessed quickly, although creating ++vectors is a bit slower in Emacs Lisp. Lists are easier to create, ++but take a relatively long time accessing the later slots. ++ ++@item :named ++This option, which takes no arguments, causes a characteristic ``tag'' ++symbol to be stored at the front of the structure object. Using ++@code{:type} without also using @code{:named} will result in a ++structure type stored as plain vectors or lists with no identifying ++features. ++ ++The default, if you don't specify @code{:type} explicitly, is to ++use named vectors. Therefore, @code{:named} is only useful in ++conjunction with @code{:type}. ++ ++@example ++(defstruct (person1) name age sex) ++(defstruct (person2 (:type list) :named) name age sex) ++(defstruct (person3 (:type list)) name age sex) ++ ++(setq p1 (make-person1)) ++ @result{} [cl-struct-person1 nil nil nil] ++(setq p2 (make-person2)) ++ @result{} (person2 nil nil nil) ++(setq p3 (make-person3)) ++ @result{} (nil nil nil) ++ ++(person1-p p1) ++ @result{} t ++(person2-p p2) ++ @result{} t ++(person3-p p3) ++ @result{} error: function person3-p undefined ++@end example ++ ++Since unnamed structures don't have tags, @code{defstruct} is not ++able to make a useful predicate for recognizing them. Also, ++accessors like @code{person3-name} will be generated but they ++will not be able to do any type checking. The @code{person3-name} ++function, for example, will simply be a synonym for @code{car} in ++this case. By contrast, @code{person2-name} is able to verify ++that its argument is indeed a @code{person2} object before ++proceeding. ++ ++@item :initial-offset ++The argument must be a nonnegative integer. It specifies a ++number of slots to be left ``empty'' at the front of the ++structure. If the structure is named, the tag appears at the ++specified position in the list or vector; otherwise, the first ++slot appears at that position. Earlier positions are filled ++with @code{nil} by the constructors and ignored otherwise. If ++the type @code{:include}s another type, then @code{:initial-offset} ++specifies a number of slots to be skipped between the last slot ++of the included type and the first new slot. ++@end table ++@end defspec ++ ++Except as noted, the @code{defstruct} facility of this package is ++entirely compatible with that of Common Lisp. ++ ++@iftex ++@chapno=23 ++@end iftex ++ ++@node Assertions, Efficiency Concerns, Structures, Top ++@chapter Assertions and Errors ++ ++@noindent ++This section describes two macros that test @dfn{assertions}, i.e., ++conditions which must be true if the program is operating correctly. ++Assertions never add to the behavior of a Lisp program; they simply ++make ``sanity checks'' to make sure everything is as it should be. ++ ++If the optimization property @code{speed} has been set to 3, and ++@code{safety} is less than 3, then the byte-compiler will optimize ++away the following assertions. Because assertions might be optimized ++away, it is a bad idea for them to include side-effects. ++ ++@defspec assert test-form [show-args string args@dots{}] ++This form verifies that @var{test-form} is true (i.e., evaluates to ++a non-@code{nil} value). If so, it returns @code{nil}. If the test ++is not satisfied, @code{assert} signals an error. ++ ++A default error message will be supplied which includes @var{test-form}. ++You can specify a different error message by including a @var{string} ++argument plus optional extra arguments. Those arguments are simply ++passed to @code{error} to signal the error. ++ ++If the optional second argument @var{show-args} is @code{t} instead ++of @code{nil}, then the error message (with or without @var{string}) ++will also include all non-constant arguments of the top-level ++@var{form}. For example: ++ ++@example ++(assert (> x 10) t "x is too small: %d") ++@end example ++ ++This usage of @var{show-args} is an extension to Common Lisp. In ++true Common Lisp, the second argument gives a list of @var{places} ++which can be @code{setf}'d by the user before continuing from the ++error. Since Emacs Lisp does not support continuable errors, it ++makes no sense to specify @var{places}. ++@end defspec ++ ++@defspec check-type form type [string] ++This form verifies that @var{form} evaluates to a value of type ++@var{type}. If so, it returns @code{nil}. If not, @code{check-type} ++signals a @code{wrong-type-argument} error. The default error message ++lists the erroneous value along with @var{type} and @var{form} ++themselves. If @var{string} is specified, it is included in the ++error message in place of @var{type}. For example: ++ ++@example ++(check-type x (integer 1 *) "a positive integer") ++@end example ++ ++@xref{Type Predicates}, for a description of the type specifiers ++that may be used for @var{type}. ++ ++Note that in Common Lisp, the first argument to @code{check-type} ++must be a @var{place} suitable for use by @code{setf}, because ++@code{check-type} signals a continuable error that allows the ++user to modify @var{place}. ++@end defspec ++ ++The following error-related macro is also defined: ++ ++@defspec ignore-errors forms@dots{} ++This executes @var{forms} exactly like a @code{progn}, except that ++errors are ignored during the @var{forms}. More precisely, if ++an error is signaled then @code{ignore-errors} immediately ++aborts execution of the @var{forms} and returns @code{nil}. ++If the @var{forms} complete successfully, @code{ignore-errors} ++returns the result of the last @var{form}. ++@end defspec ++ ++@node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top ++@appendix Efficiency Concerns ++ ++@appendixsec Macros ++ ++@noindent ++Many of the advanced features of this package, such as @code{defun*}, ++@code{loop}, and @code{setf}, are implemented as Lisp macros. In ++byte-compiled code, these complex notations will be expanded into ++equivalent Lisp code which is simple and efficient. For example, ++the forms ++ ++@example ++(incf i n) ++(push x (car p)) ++@end example ++ ++@noindent ++are expanded at compile-time to the Lisp forms ++ ++@example ++(setq i (+ i n)) ++(setcar p (cons x (car p))) ++@end example ++ ++@noindent ++which are the most efficient ways of doing these respective operations ++in Lisp. Thus, there is no performance penalty for using the more ++readable @code{incf} and @code{push} forms in your compiled code. ++ ++@emph{Interpreted} code, on the other hand, must expand these macros ++every time they are executed. For this reason it is strongly ++recommended that code making heavy use of macros be compiled. ++(The features labeled ``Special Form'' instead of ``Function'' in ++this manual are macros.) A loop using @code{incf} a hundred times ++will execute considerably faster if compiled, and will also ++garbage-collect less because the macro expansion will not have ++to be generated, used, and thrown away a hundred times. ++ ++You can find out how a macro expands by using the ++@code{cl-prettyexpand} function. ++ ++@defun cl-prettyexpand form &optional full ++This function takes a single Lisp form as an argument and inserts ++a nicely formatted copy of it in the current buffer (which must be ++in Lisp mode so that indentation works properly). It also expands ++all Lisp macros which appear in the form. The easiest way to use ++this function is to go to the @code{*scratch*} buffer and type, say, ++ ++@example ++(cl-prettyexpand '(loop for x below 10 collect x)) ++@end example ++ ++@noindent ++and type @kbd{C-x C-e} immediately after the closing parenthesis; ++the expansion ++ ++@example ++(block nil ++ (let* ((x 0) ++ (G1004 nil)) ++ (while (< x 10) ++ (setq G1004 (cons x G1004)) ++ (setq x (+ x 1))) ++ (nreverse G1004))) ++@end example ++ ++@noindent ++will be inserted into the buffer. (The @code{block} macro is ++expanded differently in the interpreter and compiler, so ++@code{cl-prettyexpand} just leaves it alone. The temporary ++variable @code{G1004} was created by @code{gensym}.) ++ ++If the optional argument @var{full} is true, then @emph{all} ++macros are expanded, including @code{block}, @code{eval-when}, ++and compiler macros. Expansion is done as if @var{form} were ++a top-level form in a file being compiled. For example, ++ ++@example ++(cl-prettyexpand '(pushnew 'x list)) ++ @print{} (setq list (adjoin 'x list)) ++(cl-prettyexpand '(pushnew 'x list) t) ++ @print{} (setq list (if (memq 'x list) list (cons 'x list))) ++(cl-prettyexpand '(caddr (member* 'a list)) t) ++ @print{} (car (cdr (cdr (memq 'a list)))) ++@end example ++ ++Note that @code{adjoin}, @code{caddr}, and @code{member*} all ++have built-in compiler macros to optimize them in common cases. ++@end defun ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@appendixsec Error Checking ++ ++@noindent ++Common Lisp compliance has in general not been sacrificed for the ++sake of efficiency. A few exceptions have been made for cases ++where substantial gains were possible at the expense of marginal ++incompatibility. ++ ++The Common Lisp standard (as embodied in Steele's book) uses the ++phrase ``it is an error if'' to indicate a situation which is not ++supposed to arise in complying programs; implementations are strongly ++encouraged but not required to signal an error in these situations. ++This package sometimes omits such error checking in the interest of ++compactness and efficiency. For example, @code{do} variable ++specifiers are supposed to be lists of one, two, or three forms; ++extra forms are ignored by this package rather than signaling a ++syntax error. The @code{endp} function is simply a synonym for ++@code{null} in this package. Functions taking keyword arguments ++will accept an odd number of arguments, treating the trailing ++keyword as if it were followed by the value @code{nil}. ++ ++Argument lists (as processed by @code{defun*} and friends) ++@emph{are} checked rigorously except for the minor point just ++mentioned; in particular, keyword arguments are checked for ++validity, and @code{&allow-other-keys} and @code{:allow-other-keys} ++are fully implemented. Keyword validity checking is slightly ++time consuming (though not too bad in byte-compiled code); ++you can use @code{&allow-other-keys} to omit this check. Functions ++defined in this package such as @code{find} and @code{member*} ++do check their keyword arguments for validity. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@appendixsec Optimizing Compiler ++ ++@noindent ++Use of the optimizing Emacs compiler is highly recommended; many of the Common ++Lisp macros emit ++code which can be improved by optimization. In particular, ++@code{block}s (whether explicit or implicit in constructs like ++@code{defun*} and @code{loop}) carry a fair run-time penalty; the ++optimizing compiler removes @code{block}s which are not actually ++referenced by @code{return} or @code{return-from} inside the block. ++ ++@node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top ++@appendix Common Lisp Compatibility ++ ++@noindent ++Following is a list of all known incompatibilities between this ++package and Common Lisp as documented in Steele (2nd edition). ++ ++Certain function names, such as @code{member}, @code{assoc}, and ++@code{floor}, were already taken by (incompatible) Emacs Lisp ++functions; this package appends @samp{*} to the names of its ++Common Lisp versions of these functions. ++ ++The word @code{defun*} is required instead of @code{defun} in order ++to use extended Common Lisp argument lists in a function. Likewise, ++@code{defmacro*} and @code{function*} are versions of those forms ++which understand full-featured argument lists. The @code{&whole} ++keyword does not work in @code{defmacro} argument lists (except ++inside recursive argument lists). ++ ++The @code{equal} predicate does not distinguish ++between IEEE floating-point plus and minus zero. The @code{equalp} ++predicate has several differences with Common Lisp; @pxref{Predicates}. ++ ++The @code{setf} mechanism is entirely compatible, except that ++setf-methods return a list of five values rather than five ++values directly. Also, the new ``@code{setf} function'' concept ++(typified by @code{(defun (setf foo) @dots{})}) is not implemented. ++ ++The @code{do-all-symbols} form is the same as @code{do-symbols} ++with no @var{obarray} argument. In Common Lisp, this form would ++iterate over all symbols in all packages. Since Emacs obarrays ++are not a first-class package mechanism, there is no way for ++@code{do-all-symbols} to locate any but the default obarray. ++ ++The @code{loop} macro is complete except that @code{loop-finish} ++and type specifiers are unimplemented. ++ ++The multiple-value return facility treats lists as multiple ++values, since Emacs Lisp cannot support multiple return values ++directly. The macros will be compatible with Common Lisp if ++@code{values} or @code{values-list} is always used to return to ++a @code{multiple-value-bind} or other multiple-value receiver; ++if @code{values} is used without @code{multiple-value-@dots{}} ++or vice-versa the effect will be different from Common Lisp. ++ ++Many Common Lisp declarations are ignored, and others match ++the Common Lisp standard in concept but not in detail. For ++example, local @code{special} declarations, which are purely ++advisory in Emacs Lisp, do not rigorously obey the scoping rules ++set down in Steele's book. ++ ++The variable @code{*gensym-counter*} starts out with a pseudo-random ++value rather than with zero. This is to cope with the fact that ++generated symbols become interned when they are written to and ++loaded back from a file. ++ ++The @code{defstruct} facility is compatible, except that structures ++are of type @code{:type vector :named} by default rather than some ++special, distinct type. Also, the @code{:type} slot option is ignored. ++ ++The second argument of @code{check-type} is treated differently. ++ ++@node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top ++@appendix Old CL Compatibility ++ ++@noindent ++Following is a list of all known incompatibilities between this package ++and the older Quiroz @file{cl.el} package. ++ ++This package's emulation of multiple return values in functions is ++incompatible with that of the older package. That package attempted ++to come as close as possible to true Common Lisp multiple return ++values; unfortunately, it could not be 100% reliable and so was prone ++to occasional surprises if used freely. This package uses a simpler ++method, namely replacing multiple values with lists of values, which ++is more predictable though more noticeably different from Common Lisp. ++ ++The @code{defkeyword} form and @code{keywordp} function are not ++implemented in this package. ++ ++The @code{member}, @code{floor}, @code{ceiling}, @code{truncate}, ++@code{round}, @code{mod}, and @code{rem} functions are suffixed ++by @samp{*} in this package to avoid collision with existing ++functions in Emacs. The older package simply ++redefined these functions, overwriting the built-in meanings and ++causing serious portability problems. (Some more ++recent versions of the Quiroz package changed the names to ++@code{cl-member}, etc.; this package defines the latter names as ++aliases for @code{member*}, etc.) ++ ++Certain functions in the old package which were buggy or inconsistent ++with the Common Lisp standard are incompatible with the conforming ++versions in this package. For example, @code{eql} and @code{member} ++were synonyms for @code{eq} and @code{memq} in that package, @code{setf} ++failed to preserve correct order of evaluation of its arguments, etc. ++ ++Finally, unlike the older package, this package is careful to ++prefix all of its internal names with @code{cl-}. Except for a ++few functions which are explicitly defined as additional features ++(such as @code{floatp-safe} and @code{letf}), this package does not ++export any non-@samp{cl-} symbols which are not also part of Common ++Lisp. ++ ++@ifinfo ++@example ++ ++@end example ++@end ifinfo ++@appendixsec The @code{cl-compat} package ++ ++@noindent ++The @dfn{CL} package includes emulations of some features of the ++old @file{cl.el}, in the form of a compatibility package ++@code{cl-compat}. To use it, put @code{(require 'cl-compat)} in ++your program. ++ ++The old package defined a number of internal routines without ++@code{cl-} prefixes or other annotations. Call to these routines ++may have crept into existing Lisp code. @code{cl-compat} ++provides emulations of the following internal routines: ++@code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists}, ++@code{reassemble-arglists}, @code{duplicate-symbols-p}, ++@code{safe-idiv}. ++ ++Some @code{setf} forms translated into calls to internal ++functions that user code might call directly. The functions ++@code{setnth}, @code{setnthcdr}, and @code{setelt} fall in ++this category; they are defined by @code{cl-compat}, but the ++best fix is to change to use @code{setf} properly. ++ ++The @code{cl-compat} file defines the keyword functions ++@code{keywordp}, @code{keyword-of}, and @code{defkeyword}, ++which are not defined by the new @dfn{CL} package because the ++use of keywords as data is discouraged. ++ ++The @code{build-klist} mechanism for parsing keyword arguments ++is emulated by @code{cl-compat}; the @code{with-keyword-args} ++macro is not, however, and in any case it's best to change to ++use the more natural keyword argument processing offered by ++@code{defun*}. ++ ++Multiple return values are treated differently by the two ++Common Lisp packages. The old package's method was more ++compatible with true Common Lisp, though it used heuristics ++that caused it to report spurious multiple return values in ++certain cases. The @code{cl-compat} package defines a set ++of multiple-value macros that are compatible with the old ++CL package; again, they are heuristic in nature, but they ++are guaranteed to work in any case where the old package's ++macros worked. To avoid name collision with the ``official'' ++multiple-value facilities, the ones in @code{cl-compat} have ++capitalized names: @code{Values}, @code{Values-list}, ++@code{Multiple-value-bind}, etc. ++ ++The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate}, ++and @code{cl-round} are defined by @code{cl-compat} to use the ++old-style multiple-value mechanism, just as they did in the old ++package. The newer @code{floor*} and friends return their two ++results in a list rather than as multiple values. Note that ++older versions of the old package used the unadorned names ++@code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use ++these names because they conflict with Emacs built-ins. ++ ++@node Porting Common Lisp, GNU Free Documentation License, Old CL Compatibility, Top ++@appendix Porting Common Lisp ++ ++@noindent ++This package is meant to be used as an extension to Emacs Lisp, ++not as an Emacs implementation of true Common Lisp. Some of the ++remaining differences between Emacs Lisp and Common Lisp make it ++difficult to port large Common Lisp applications to Emacs. For ++one, some of the features in this package are not fully compliant ++with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there ++are also quite a few features that this package does not provide ++at all. Here are some major omissions that you will want to watch out ++for when bringing Common Lisp code into Emacs. ++ ++@itemize @bullet ++@item ++Case-insensitivity. Symbols in Common Lisp are case-insensitive ++by default. Some programs refer to a function or variable as ++@code{foo} in one place and @code{Foo} or @code{FOO} in another. ++Emacs Lisp will treat these as three distinct symbols. ++ ++Some Common Lisp code is written entirely in upper case. While Emacs ++is happy to let the program's own functions and variables use ++this convention, calls to Lisp builtins like @code{if} and ++@code{defun} will have to be changed to lower case. ++ ++@item ++Lexical scoping. In Common Lisp, function arguments and @code{let} ++bindings apply only to references physically within their bodies ++(or within macro expansions in their bodies). Emacs Lisp, by ++contrast, uses @dfn{dynamic scoping} wherein a binding to a ++variable is visible even inside functions called from the body. ++ ++Variables in Common Lisp can be made dynamically scoped by ++declaring them @code{special} or using @code{defvar}. In Emacs ++Lisp it is as if all variables were declared @code{special}. ++ ++Often you can use code that was written for lexical scoping ++even in a dynamically scoped Lisp, but not always. Here is ++an example of a Common Lisp code fragment that would fail in ++Emacs Lisp: ++ ++@example ++(defun map-odd-elements (func list) ++ (loop for x in list ++ for flag = t then (not flag) ++ collect (if flag x (funcall func x)))) ++ ++(defun add-odd-elements (list x) ++ (map-odd-elements (lambda (a) (+ a x)) list)) ++@end example ++ ++@noindent ++In Common Lisp, the two functions' usages of @code{x} are completely ++independent. In Emacs Lisp, the binding to @code{x} made by ++@code{add-odd-elements} will have been hidden by the binding ++in @code{map-odd-elements} by the time the @code{(+ a x)} function ++is called. ++ ++(This package avoids such problems in its own mapping functions ++by using names like @code{cl-x} instead of @code{x} internally; ++as long as you don't use the @code{cl-} prefix for your own ++variables no collision can occur.) ++ ++@xref{Lexical Bindings}, for a description of the @code{lexical-let} ++form which establishes a Common Lisp-style lexical binding, and some ++examples of how it differs from Emacs' regular @code{let}. ++ ++@item ++Reader macros. Common Lisp includes a second type of macro that ++works at the level of individual characters. For example, Common ++Lisp implements the quote notation by a reader macro called @code{'}, ++whereas Emacs Lisp's parser just treats quote as a special case. ++Some Lisp packages use reader macros to create special syntaxes ++for themselves, which the Emacs parser is incapable of reading. ++ ++@item ++Other syntactic features. Common Lisp provides a number of ++notations beginning with @code{#} that the Emacs Lisp parser ++won't understand. For example, @samp{#| ... |#} is an ++alternate comment notation, and @samp{#+lucid (foo)} tells ++the parser to ignore the @code{(foo)} except in Lucid Common ++Lisp. ++ ++@item ++Packages. In Common Lisp, symbols are divided into @dfn{packages}. ++Symbols that are Lisp built-ins are typically stored in one package; ++symbols that are vendor extensions are put in another, and each ++application program would have a package for its own symbols. ++Certain symbols are ``exported'' by a package and others are ++internal; certain packages ``use'' or import the exported symbols ++of other packages. To access symbols that would not normally be ++visible due to this importing and exporting, Common Lisp provides ++a syntax like @code{package:symbol} or @code{package::symbol}. ++ ++Emacs Lisp has a single namespace for all interned symbols, and ++then uses a naming convention of putting a prefix like @code{cl-} ++in front of the name. Some Emacs packages adopt the Common Lisp-like ++convention of using @code{cl:} or @code{cl::} as the prefix. ++However, the Emacs parser does not understand colons and just ++treats them as part of the symbol name. Thus, while @code{mapcar} ++and @code{lisp:mapcar} may refer to the same symbol in Common ++Lisp, they are totally distinct in Emacs Lisp. Common Lisp ++programs which refer to a symbol by the full name sometimes ++and the short name other times will not port cleanly to Emacs. ++ ++Emacs Lisp does have a concept of ``obarrays,'' which are ++package-like collections of symbols, but this feature is not ++strong enough to be used as a true package mechanism. ++ ++@item ++The @code{format} function is quite different between Common ++Lisp and Emacs Lisp. It takes an additional ``destination'' ++argument before the format string. A destination of @code{nil} ++means to format to a string as in Emacs Lisp; a destination ++of @code{t} means to write to the terminal (similar to ++@code{message} in Emacs). Also, format control strings are ++utterly different; @code{~} is used instead of @code{%} to ++introduce format codes, and the set of available codes is ++much richer. There are no notations like @code{\n} for ++string literals; instead, @code{format} is used with the ++``newline'' format code, @code{~%}. More advanced formatting ++codes provide such features as paragraph filling, case ++conversion, and even loops and conditionals. ++ ++While it would have been possible to implement most of Common ++Lisp @code{format} in this package (under the name @code{format*}, ++of course), it was not deemed worthwhile. It would have required ++a huge amount of code to implement even a decent subset of ++@code{format*}, yet the functionality it would provide over ++Emacs Lisp's @code{format} would rarely be useful. ++ ++@item ++Vector constants use square brackets in Emacs Lisp, but ++@code{#(a b c)} notation in Common Lisp. To further complicate ++matters, Emacs has its own @code{#(} notation for ++something entirely different---strings with properties. ++ ++@item ++Characters are distinct from integers in Common Lisp. The notation ++for character constants is also different: @code{#\A} in Common Lisp ++where Emacs Lisp uses @code{?A}. Also, @code{string=} and ++@code{string-equal} are synonyms in Emacs Lisp, whereas the latter is ++case-insensitive in Common Lisp. ++ ++@item ++Data types. Some Common Lisp data types do not exist in Emacs ++Lisp. Rational numbers and complex numbers are not present, ++nor are large integers (all integers are ``fixnums''). All ++arrays are one-dimensional. There are no readtables or pathnames; ++streams are a set of existing data types rather than a new data ++type of their own. Hash tables, random-states, structures, and ++packages (obarrays) are built from Lisp vectors or lists rather ++than being distinct types. ++ ++@item ++The Common Lisp Object System (CLOS) is not implemented, ++nor is the Common Lisp Condition System. However, the EIEIO package ++from @uref{ftp://ftp.ultranet.com/pub/zappo} does implement some ++CLOS functionality. ++ ++@item ++Common Lisp features that are completely redundant with Emacs ++Lisp features of a different name generally have not been ++implemented. For example, Common Lisp writes @code{defconstant} ++where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list} ++takes its arguments in different ways in the two Lisps but does ++exactly the same thing, so this package has not bothered to ++implement a Common Lisp-style @code{make-list}. ++ ++@item ++A few more notable Common Lisp features not included in this ++package: @code{compiler-let}, @code{tagbody}, @code{prog}, ++@code{ldb/dpb}, @code{parse-integer}, @code{cerror}. ++ ++@item ++Recursion. While recursion works in Emacs Lisp just like it ++does in Common Lisp, various details of the Emacs Lisp system ++and compiler make recursion much less efficient than it is in ++most Lisps. Some schools of thought prefer to use recursion ++in Lisp over other techniques; they would sum a list of ++numbers using something like ++ ++@example ++(defun sum-list (list) ++ (if list ++ (+ (car list) (sum-list (cdr list))) ++ 0)) ++@end example ++ ++@noindent ++where a more iteratively-minded programmer might write one of ++these forms: ++ ++@example ++(let ((total 0)) (dolist (x my-list) (incf total x)) total) ++(loop for x in my-list sum x) ++@end example ++ ++While this would be mainly a stylistic choice in most Common Lisps, ++in Emacs Lisp you should be aware that the iterative forms are ++much faster than recursion. Also, Lisp programmers will want to ++note that the current Emacs Lisp compiler does not optimize tail ++recursion. ++@end itemize ++ ++@node GNU Free Documentation License, Function Index, Porting Common Lisp, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Function Index, Variable Index, GNU Free Documentation License, Top ++@unnumbered Function Index ++ ++@printindex fn ++ ++@node Variable Index, , Function Index, Top ++@unnumbered Variable Index ++ ++@printindex vr ++ ++@bye ++ ++@ignore ++ arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8 ++@end ignore +diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi +new file mode 100644 +index 0000000..f1385f6 +--- /dev/null ++++ b/doc/misc/dbus.texi +@@ -0,0 +1,1582 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/dbus ++@c %**start of header ++@settitle Using of D-Bus ++@c @setchapternewpage odd ++@c %**end of header ++ ++@copying ++Copyright @copyright{} 2007, 2008, 2009 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 Emacs ++@direntry ++* D-Bus: (dbus). Using D-Bus in Emacs. ++@end direntry ++ ++@contents ++ ++@node Top, Overview, (dir), (dir) ++@top D-Bus integration in Emacs ++ ++This manual documents an API for usage of D-Bus in ++Emacs.@footnote{D-Bus is not enabled by default. You must run ++@command{./configure --with-dbus} in Emacs' top level directory, ++before you compile Emacs.} D-Bus is a message bus system, a simple ++way for applications to talk to one another. An overview of D-Bus can ++be found at @uref{http://dbus.freedesktop.org/}. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview:: An overview of D-Bus. ++* Inspection:: Inspection of D-Bus services. ++* Type Conversion:: Mapping Lisp types and D-Bus types. ++* Synchronous Methods:: Calling methods in a blocking way. ++* Asynchronous Methods:: Calling methods non-blocking. ++* Receiving Method Calls:: Offering own methods. ++* Signals:: Sending and receiving signals. ++* Errors and Events:: Errors and events. ++* GNU Free Documentation License:: The license for this documentation. ++@end menu ++ ++ ++@node Overview ++@chapter An overview of D-Bus ++@cindex overview ++ ++D-Bus is an inter-process communication mechanism for applications ++residing on the same host. The communication is based on ++@dfn{messages}. Data in the messages is carried in a structured way, ++it is not just a byte stream. ++ ++The communication is connection oriented to two kinds of message ++buses: a so called @dfn{system bus}, and a @dfn{session bus}. On a ++given machine, there is always one single system bus for miscellaneous ++system-wide communication, like changing of hardware configuration. ++On the other hand, the session bus is always related to a single ++user's session. ++ ++Every client application, which is connected to a bus, registers under ++a @dfn{unique name} at the bus. This name is used for identifying the ++client application. Such a unique name starts always with a colon, ++and looks like @samp{:1.42}. ++ ++Additionally, a client application can register itself to a so called ++@dfn{known name}, which is a series of identifiers separated by dots, ++as in @samp{org.gnu.Emacs}. If several applications register to the ++same known name, these registrations are queued, and only the first ++application which has registered for the known name is reachable via ++this name. If this application disconnects from the bus, the next ++queued unique name becomes the owner of this known name. ++ ++An application can install one or several objects under its name. ++Such objects are identified by an @dfn{object path}, which looks ++similar to paths in a filesystem. An example of such an object path ++could be @samp{/org/gnu/Emacs/}. ++ ++Applications might send a request to an object, that means sending a ++message with some data as input parameters, and receiving a message ++from that object with the result of this message, the output ++parameters. Such a request is called @dfn{method} in D-Bus. ++ ++The other form of communication are @dfn{signals}. The underlying ++message is emitted from an object and will be received by all other ++applications which have registered for such a signal. ++ ++All methods and signals an object supports are called @dfn{interface} ++of the object. Interfaces are specified under a hierarchical name in ++D-Bus; an object can support several interfaces. Such an interface ++name could be @samp{org.gnu.Emacs.TextEditor} or ++@samp{org.gnu.Emacs.FileManager}. ++ ++ ++@node Inspection ++@chapter Inspection of D-Bus services. ++@cindex inspection ++ ++@menu ++* Bus names:: Discovering D-Bus names. ++* Introspection:: Knowing the details of D-Bus services. ++* Nodes and Interfaces:: Detecting object paths and interfaces. ++* Methods and Signal:: Applying the functionality. ++* Properties and Annotations:: What else to know about interfaces. ++* Arguments and Signatures:: The final details. ++@end menu ++ ++ ++@node Bus names ++@section Bus names. ++ ++There are several basic functions which inspect the buses for ++registered names. Internally they use the basic interface ++@samp{org.freedesktop.DBus}, which is supported by all objects of a bus. ++ ++@defun dbus-list-activatable-names ++This function returns the D-Bus service names, which can be activated. ++An activatable service is described in a service registration file. ++Under GNU/Linux, such files are located at ++@file{/usr/share/dbus-1/services/}. ++ ++The result is a list of strings, which is @code{nil} when there are no ++activatable service names at all. ++@end defun ++ ++@defun dbus-list-names bus ++All service names, which are registered at D-Bus @var{bus}, are ++returned. The result is a list of strings, which is @code{nil} when ++there are no registered service names at all. Well known names are ++strings like @samp{org.freedesktop.DBus}. Names starting with ++@samp{:} are unique names for services. ++ ++@var{bus} must be either the symbol @code{:system} or the symbol ++@code{:session}. ++@end defun ++ ++@defun dbus-list-known-names bus ++Retrieves all services which correspond to a known name in @var{bus}. ++A service has a known name if it doesn't start with @samp{:}. The ++result is a list of strings, which is @code{nil} when there are no ++known names at all. ++ ++@var{bus} must be either the symbol @code{:system} or the symbol ++@code{:session}. ++@end defun ++ ++@defun dbus-list-queued-owners bus service ++For a given service, registered at D-Bus @var{bus} under the name ++@var{service}, all queued unique names are returned. The result is a ++list of strings, or @code{nil} when there are no queued names for ++@var{service} at all. ++ ++@var{bus} must be either the symbol @code{:system} or the symbol ++@code{:session}. @var{service} must be a known service name as ++string. ++@end defun ++ ++@defun dbus-get-name-owner bus service ++For a given service, registered at D-Bus @var{bus} under the name ++@var{service}, the unique name of the name owner is returned. The ++result is a string, or @code{nil} when there exist no name owner of ++@var{service}. ++ ++@var{bus} must be either the symbol @code{:system} or the symbol ++@code{:session}. @var{service} must be a known service name as ++string. ++@end defun ++ ++@defun dbus-ping bus service ++Check whether the service name @var{service} is registered at D-Bus ++@var{bus}. @var{service} might not have been started yet. The result ++is either @code{t} or @code{nil}. ++ ++@var{bus} must be either the symbol @code{:system} or the symbol ++@code{:session}. @var{service} must be a string. Example: ++ ++@lisp ++(message ++ "%s screensaver on board." ++ (cond ++ ((dbus-ping :session "org.gnome.ScreenSaver") "Gnome") ++ ((dbus-ping :session "org.freedesktop.ScreenSaver") "KDE") ++ (t "No"))) ++@end lisp ++@end defun ++ ++@defun dbus-get-unique-name bus ++The unique name, under which Emacs is registered at D-Bus @var{bus}, ++is returned as string. ++ ++@var{bus} must be either the symbol @code{:system} or the symbol ++@code{:session}. ++@end defun ++ ++ ++@node Introspection ++@section Knowing the details of D-Bus services. ++ ++D-Bus services publish their interfaces. This can be retrieved and ++analyzed during runtime, in order to understand the used ++implementation. ++ ++The resulting introspection data are in XML format. The root ++introspection element is always a @code{node} element. It might have ++a @code{name} attribute, which denotes the (absolute) object path an ++interface is introspected. ++ ++The root @code{node} element may have @code{node} and @code{interface} ++children. A child @code{node} element must have a @code{name} ++attribute, this case it is the relative object path to the root ++@code{node} element. ++ ++An @code{interface} element has just one attribute, @code{name}, which ++is the full name of that interface. The default interface ++@samp{org.freedesktop.DBus.Introspectable} is always present. Example: ++ ++@example ++ ++ ++ @dots{} ++ ++ ++ @dots{} ++ ++ ++ @dots{} ++ ++ ++ @dots{} ++ ++ ++ ++ ++ ++ ++@end example ++ ++Children of an @code{interface} element can be @code{method}, ++@code{signal} and @code{property} elements. A @code{method} element ++stands for a D-Bus method of the surrounding interface. The element ++itself has a @code{name} attribute, showing the method name. Children ++elements @code{arg} stand for the arguments of a method. Example: ++ ++@example ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++@end example ++ ++@code{arg} elements can have the attributes @code{name}, @code{type} ++and @code{direction}. The @code{name} attribute is optional. The ++@code{type} attribute stands for the @dfn{signature} of the argument ++in D-Bus. For a discussion of D-Bus types and their Lisp ++representation see @ref{Type Conversion}.@footnote{D-Bus signatures ++are explained in the D-Bus specification ++@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.} ++The @code{direction} attribute of an @code{arg} element can be only ++@samp{in} or @samp{out}; in case it is omitted, it defaults to ++@samp{in}. ++ ++A @code{signal} element of an @code{interface} has a similar ++structure. The @code{direction} attribute of an @code{arg} child ++element can be only @samp{out} here; which is also the default value. ++Example: ++ ++@example ++ ++ ++ ++ ++@end example ++ ++A @code{property} element has no @code{arg} child ++element. It just has the attributes @code{name}, @code{type} and ++@code{access}, which are all mandatory. The @code{access} attribute ++allows the values @samp{readwrite}, @samp{read}, and @samp{write}. ++Example: ++ ++@example ++ ++@end example ++ ++@code{annotation} elements can be children of @code{interface}, ++@code{method}, @code{signal}, and @code{property} elements. Unlike ++properties, which can change their values during lifetime of a D-Bus ++object, annotations are static. Often they are used for code ++generators of D-Bus langugae bindings. Example: ++ ++@example ++ ++@end example ++ ++Annotations have just @code{name} and @code{value} attributes, both ++must be strings. ++ ++@defun dbus-introspect bus service path ++This function returns all interfaces and sub-nodes of @var{service}, ++registered at object path @var{path} at bus @var{bus}. ++ ++@var{bus} must be either the symbol @code{:system} or the symbol ++@code{:session}. @var{service} must be a known service name, and ++@var{path} must be a valid object path. The last two parameters are ++strings. The result, the introspection data, is a string in XML ++format. Example: ++ ++@lisp ++(dbus-introspect ++ :system "org.freedesktop.Hal" ++ "/org/freedesktop/Hal/devices/computer") ++ ++@result{} " ++ ++ ++ ++ ++ ++ @dots{} ++ ++ ++ ++ ++ ++ @dots{} ++ " ++@end lisp ++ ++This example informs us, that the service @samp{org.freedesktop.Hal} ++at object path @samp{/org/freedesktop/Hal/devices/computer} offers the ++interface @samp{org.freedesktop.Hal.Device} (and 2 other interfaces ++not documented here). This interface contains the method ++@samp{GetAllProperties}, which needs no input parameters, but returns ++as output parameter an array of dictionary entries (key-value pairs). ++Every dictionary entry has a string as key, and a variant as value. ++ ++The interface offers also a signal, which returns 2 parameters: an ++integer, and an array consisting of elements which are a struct of a ++string and 2 boolean values.@footnote{ The interfaces of the service ++@samp{org.freedesktop.Hal} are described at ++@uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.} ++@end defun ++ ++@defun dbus-introspect-xml bus service path ++This function has the same intention as function ++@code{dbus-introspect}. The returned value is a parsed XML tree, ++which can be used for further analysis. Example: ++ ++@lisp ++(dbus-introspect-xml ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main") ++ ++@result{} (node ((name . "/org/freedesktop/xesam/searcher/main")) ++ (interface ((name . "org.freedesktop.xesam.Search")) ++ (method ((name . "GetHitData")) ++ (arg ((name . "search") (type . "s") (direction . "in"))) ++ (arg ((name . "hit_ids") (type . "au") (direction . "in"))) ++ (arg ((name . "fields") (type . "as") (direction . "in"))) ++ (arg ((name . "hit_data") (type . "aav") (direction . "out"))) ++ ) ++ @dots{} ++ (signal ((name . "HitsAdded")) ++ (arg ((name . "search") (type . "s"))) ++ (arg ((name . "count") (type . "u"))) ++ ) ++ ) ++ @dots{} ++ ) ++@end lisp ++@end defun ++ ++@defun dbus-introspect-get-attribute object attribute ++It returns the @var{attribute} value of a D-Bus introspection ++@var{object}. @var{object} can be every subtree of a parsed XML tree ++as retrieved with @code{dbus-introspect-xml}. @var{attribute} must be ++a string according to the attribute names in the D-Bus specification. ++Example: ++ ++@lisp ++(dbus-introspect-get-attribute ++ (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends" ++ "/org/freedesktop/SystemToolsBackends/UsersConfig") ++ "name") ++ ++@result{} "/org/freedesktop/SystemToolsBackends/UsersConfig" ++@end lisp ++ ++If @var{object} has no @var{attribute}, the function returns nil. ++@end defun ++ ++ ++@node Nodes and Interfaces ++@section Detecting object paths and interfaces. ++ ++The first elements, to be introspected for a D-Bus object, are further ++object paths and interfaces. ++ ++@defun dbus-introspect-get-node-names bus service path ++All node names of @var{service} in D-Bus @var{bus} at object path ++@var{path} are returned as list of strings. Example: ++ ++@lisp ++(dbus-introspect-get-node-names ++ :session "org.gnome.seahorse" "/org/gnome/seahorse") ++ ++@result{} ("crypto" "keys") ++@end lisp ++ ++The node names stand for further object paths of the D-Bus ++@var{service}, relative to @var{path}. In the example, ++@samp{/org/gnome/seahorse/crypto} and @samp{/org/gnome/seahorse/keys} ++are also object paths of the D-Bus service @samp{org.gnome.seahorse}. ++@end defun ++ ++@defun dbus-introspect-get-all-nodes bus service path ++This function returns all node names of @var{service} in D-Bus ++@var{bus} at object path @var{path}. It returns a list of strings ++with all object paths of @var{service}, starting at @var{path}. ++Example: ++ ++@lisp ++(dbus-introspect-get-all-nodes :session "org.gnome.seahorse" "/") ++ ++@result{} ("/" "/org" "/org/gnome" "/org/gnome/seahorse" ++ "/org/gnome/seahorse/crypto" ++ "/org/gnome/seahorse/keys" ++ "/org/gnome/seahorse/keys/openpgp" ++ "/org/gnome/seahorse/keys/openpgp/local" ++ "/org/gnome/seahorse/keys/openssh" ++ "/org/gnome/seahorse/keys/openssh/local") ++@end lisp ++@end defun ++ ++@defun dbus-introspect-get-interface-names bus service path ++There will be returned a list strings of all interface names of ++@var{service} in D-Bus @var{bus} at object path @var{path}. This list ++will contain the default interface @samp{org.freedesktop.DBus.Introspectable}. ++ ++Another default interface is @samp{org.freedesktop.DBus.Properties}. ++If present, @code{interface} elements can also have @code{property} ++children. Example: ++ ++@lisp ++(dbus-introspect-get-interface-names ++ :system "org.freedesktop.Hal" ++ "/org/freedesktop/Hal/devices/computer") ++ ++@result{} ("org.freedesktop.DBus.Introspectable" ++ "org.freedesktop.Hal.Device" ++ "org.freedesktop.Hal.Device.SystemPowerManagement" ++ "org.freedesktop.Hal.Device.CPUFreq") ++@end lisp ++@end defun ++ ++@defun dbus-introspect-get-interface bus service path interface ++Return @var{interface} of @var{service} in D-Bus @var{bus} at object ++path @var{path}. The return value is an XML element. @var{interface} ++must be a string, element of the list returned by ++@code{dbus-introspect-get-interface-names}. Example: ++ ++@lisp ++(dbus-introspect-get-interface ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main" ++ "org.freedesktop.xesam.Search") ++ ++@result{} (interface ((name . "org.freedesktop.xesam.Search")) ++ (method ((name . "GetHitData")) ++ (arg ((name . "search") (type . "s") (direction . "in"))) ++ (arg ((name . "hit_ids") (type . "au") (direction . "in"))) ++ (arg ((name . "fields") (type . "as") (direction . "in"))) ++ (arg ((name . "hit_data") (type . "aav") (direction . "out"))) ++ ) ++ @dots{} ++ (signal ((name . "HitsAdded")) ++ (arg ((name . "search") (type . "s"))) ++ (arg ((name . "count") (type . "u"))) ++ ) ++ ) ++@end lisp ++@end defun ++ ++@noindent ++With these functions, it is possible to retrieve all introspection ++data from a running system: ++ ++@lisp ++(with-current-buffer (switch-to-buffer "*introspect*") ++ (erase-buffer) ++ (dolist (service (dbus-list-known-names :session)) ++ (dolist (path (dbus-introspect-get-all-nodes :session service "/")) ++ ;; We want to introspect only elements, which have more than ++ ;; the default interface "org.freedesktop.DBus.Introspectable". ++ (when (delete ++ "org.freedesktop.DBus.Introspectable" ++ (dbus-introspect-get-interface-names :session service path)) ++ (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path) ++ (dbus-introspect :session service path)) ++ (redisplay t))))) ++@end lisp ++ ++ ++@node Methods and Signal ++@section Applying the functionality. ++ ++Methods and signals are the communicatione means to D-Bus. The ++following functions return their specifications. ++ ++@defun dbus-introspect-get-method-names bus service path interface ++Return a list of strings of all method names of @var{interface} of ++@var{service} in D-Bus @var{bus} at object path @var{path}. Example: ++ ++@lisp ++(dbus-introspect-get-method-names ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main" ++ "org.freedesktop.xesam.Search") ++ ++@result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession" ++ "CloseSession" "GetHitData" "SetProperty" "NewSearch" ++ "GetProperty" "CloseSearch") ++@end lisp ++@end defun ++ ++@defun dbus-introspect-get-method bus service path interface method ++This function returns @var{method} of @var{interface} as XML element. ++It must be located at @var{service} in D-Bus @var{bus} at object path ++@var{path}. @var{method} must be a string, element of the list ++returned by @code{dbus-introspect-get-method-names}. Example: ++ ++@lisp ++(dbus-introspect-get-method ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main" ++ "org.freedesktop.xesam.Search" "GetHitData") ++ ++@result{} (method ((name . "GetHitData")) ++ (arg ((name . "search") (type . "s") (direction . "in"))) ++ (arg ((name . "hit_ids") (type . "au") (direction . "in"))) ++ (arg ((name . "fields") (type . "as") (direction . "in"))) ++ (arg ((name . "hit_data") (type . "aav") (direction . "out"))) ++ ) ++@end lisp ++@end defun ++ ++@defun dbus-introspect-get-signal-names bus service path interface ++Return a list of strings of all signal names of @var{interface} of ++@var{service} in D-Bus @var{bus} at object path @var{path}. Example: ++ ++@lisp ++(dbus-introspect-get-signal-names ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main" ++ "org.freedesktop.xesam.Search") ++ ++@result{} ("StateChanged" "SearchDone" "HitsModified" ++ "HitsRemoved" "HitsAdded") ++@end lisp ++@end defun ++ ++@defun dbus-introspect-get-signal bus service path interface signal ++This function returns @var{signal} of @var{interface} as XML element. ++It must be located at @var{service} in D-Bus @var{bus} at object path ++@var{path}. @var{signal} must be a string, element of the list ++returned by @code{dbus-introspect-get-signal-names}. Example: ++ ++@lisp ++(dbus-introspect-get-signal ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main" ++ "org.freedesktop.xesam.Search" "HitsAdded") ++ ++@result{} (signal ((name . "HitsAdded")) ++ (arg ((name . "search") (type . "s"))) ++ (arg ((name . "count") (type . "u"))) ++ ) ++@end lisp ++@end defun ++ ++ ++@node Properties and Annotations ++@section What else to know about interfaces. ++ ++Interfaces can have properties. These can be exposed via the ++@samp{org.freedesktop.DBus.Properties} interface@footnote{See ++@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}. ++That is, properties can be retrieved and changed during lifetime of an ++element. ++ ++Annotations, on the other hand, are static values for an element. ++Often, they are used to instruct generators, how to generate code from ++the interface for a given language binding. ++ ++@defun dbus-introspect-get-property-names bus service path interface ++Return a list of strings with all property names of @var{interface} of ++@var{service} in D-Bus @var{bus} at object path @var{path}. Example: ++ ++@lisp ++(dbus-introspect-get-property-names ++ :session "org.kde.kded" "/modules/networkstatus" ++ "org.kde.Solid.Networking.Client") ++ ++@result{} ("Status") ++@end lisp ++ ++If an interface declares properties, the corresponding element supports ++also the @samp{org.freedesktop.DBus.Properties} interface. ++@end defun ++ ++@defun dbus-introspect-get-property bus service path interface property ++This function returns @var{property} of @var{interface} as XML element. ++It must be located at @var{service} in D-Bus @var{bus} at object path ++@var{path}. @var{property} must be a string, element of the list ++returned by @code{dbus-introspect-get-property-names}. ++ ++A @var{property} value can be retrieved by the function ++@code{dbus-introspect-get-attribute}. Example: ++ ++@lisp ++(dbus-introspect-get-property ++ :session "org.kde.kded" "/modules/networkstatus" ++ "org.kde.Solid.Networking.Client" "Status") ++ ++@result{} (property ((access . "read") (type . "u") (name . "Status"))) ++ ++(dbus-introspect-get-attribute ++ (dbus-introspect-get-property ++ :session "org.kde.kded" "/modules/networkstatus" ++ "org.kde.Solid.Networking.Client" "Status") ++ "access") ++ ++@result{} "read" ++@end lisp ++@end defun ++ ++@defun dbus-get-property bus service path interface property ++This function returns the value of @var{property} of @var{interface}. ++It will be checked at @var{bus}, @var{service}, @var{path}. The ++result can be any valid D-Bus value, or nil if there is no ++@var{property}. Example: ++ ++@lisp ++(dbus-get-property ++ :session "org.kde.kded" "/modules/networkstatus" ++ "org.kde.Solid.Networking.Client" "Status") ++ ++@result{} 4 ++@end lisp ++@end defun ++ ++@defun dbus-set-property bus service path interface property value ++Set value of @var{property} of @var{interface} to @var{value}. It ++will be checked at @var{bus}, @var{service}, @var{path}. When the ++value has been set successful, the result is @var{value}. Otherwise, ++@code{nil} is returned. Example: ++ ++@lisp ++(dbus-set-property ++ :session "org.kde.kaccess" "/MainApplication" ++ "com.trolltech.Qt.QApplication" "doubleClickInterval" 500) ++ ++@result{} 500 ++@end lisp ++@end defun ++ ++@defun dbus-get-all-properties bus service path interface ++This function returns all properties of @var{interface}. It will be ++checked at @var{bus}, @var{service}, @var{path}. The result is a list ++of cons. Every cons contains the name of the property, and its value. ++If there are no properties, @code{nil} is returned. Example: ++ ++@lisp ++(dbus-get-all-properties ++ :session "org.kde.kaccess" "/MainApplication" ++ "com.trolltech.Qt.QApplication") ++ ++@result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500) ++ ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3) ++ ("globalStrut" 0 0) ("startDragTime" . 500) ++ ("startDragDistance" . 4) ("quitOnLastWindowClosed" . t) ++ ("styleSheet" . "")) ++@end lisp ++@end defun ++ ++@defun dbus-introspect-get-annotation-names bus service path interface &optional name ++Return a list of all annotation names as list of strings. If ++@var{name} is @code{nil}, the annotations are children of ++@var{interface}, otherwise @var{name} must be a @code{method}, ++@code{signal}, or @code{property} XML element, where the annotations ++belong to. Example: ++ ++@lisp ++(dbus-introspect-get-annotation-names ++ :session "de.berlios.Pinot" "/de/berlios/Pinot" ++ "de.berlios.Pinot" "GetStatistics") ++ ++@result{} ("de.berlios.Pinot.GetStatistics") ++@end lisp ++ ++Default annotation names@footnote{See ++@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format}} ++are ++ ++@table @samp ++@item org.freedesktop.DBus.Deprecated ++Whether or not the entity is deprecated; defaults to @code{nil} ++ ++@item org.freedesktop.DBus.GLib.CSymbol ++The C symbol; may be used for @code{methods} and @code{interfaces} ++ ++@item org.freedesktop.DBus.Method.NoReply ++If set, don't expect a reply to the @code{method} call; defaults to @code{nil} ++@end table ++@end defun ++ ++@defun dbus-introspect-get-annotation bus service path interface name annotation ++Return annotation @var{ANNOTATION} as XML object. If @var{name} is ++@code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise ++@var{name} must be the name of a @code{method}, @code{signal}, or ++@code{property} XML element, where the @var{ANNOTATION} belongs to. ++ ++An attribute value can be retrieved by ++@code{dbus-introspect-get-attribute}. Example: ++ ++@lisp ++(dbus-introspect-get-annotation ++ :session "de.berlios.Pinot" "/de/berlios/Pinot" ++ "de.berlios.Pinot" "GetStatistics" ++ "de.berlios.Pinot.GetStatistics") ++ ++@result{} (annotation ((name . "de.berlios.Pinot.GetStatistics") ++ (value . "pinotDBus"))) ++ ++(dbus-introspect-get-attribute ++ (dbus-introspect-get-annotation ++ :session "de.berlios.Pinot" "/de/berlios/Pinot" ++ "de.berlios.Pinot" "GetStatistics" ++ "de.berlios.Pinot.GetStatistics") ++ "value") ++ ++@result{} "pinotDBus" ++@end lisp ++@end defun ++ ++ ++@node Arguments and Signatures ++@section The final details. ++ ++Methods and signals have arguments. They are described in the ++@code{arg} XML elements. ++ ++@defun dbus-introspect-get-argument-names bus service path interface name ++Return a list of all argument names as list of strings. @var{name} ++must be a @code{method} or @code{signal} XML element. Example: ++ ++@lisp ++(dbus-introspect-get-argument-names ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main" ++ "org.freedesktop.xesam.Search" "GetHitData") ++ ++@result{} ("search" "hit_ids" "fields" "hit_data") ++@end lisp ++ ++Argument names are optional; the function can return @code{nil} ++therefore, even if the method or signal has arguments. ++@end defun ++ ++@defun dbus-introspect-get-argument bus service path interface name arg ++Return argument @var{ARG} as XML object. @var{name} ++must be a @code{method} or @code{signal} XML element. Example: ++ ++@lisp ++(dbus-introspect-get-argument ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main" ++ "org.freedesktop.xesam.Search" "GetHitData" "search") ++ ++@result{} (arg ((name . "search") (type . "s") (direction . "in"))) ++@end lisp ++@end defun ++ ++@defun dbus-introspect-get-signature bus service path interface name &optional direction ++Return signature of a @code{method} or @code{signal}, represented by ++@var{name}, as string. ++ ++If @var{name} is a @code{method}, @var{direction} can be either ++@samp{in} or @samp{out}. If @var{direction} is @code{nil}, @samp{in} ++is assumed. ++ ++If @var{name} is a @code{signal}, and @var{direction} is ++non-@code{nil}, @var{direction} must be @samp{out}. Example: ++ ++@lisp ++(dbus-introspect-get-signature ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main" ++ "org.freedesktop.xesam.Search" "GetHitData" "in") ++ ++@result{} "sauas" ++ ++(dbus-introspect-get-signature ++ :session "org.freedesktop.xesam.searcher" ++ "/org/freedesktop/xesam/searcher/main" ++ "org.freedesktop.xesam.Search" "HitsAdded") ++ ++@result{} "su" ++@end lisp ++@end defun ++ ++ ++@node Type Conversion ++@chapter Mapping Lisp types and D-Bus types. ++@cindex type conversion ++ ++D-Bus method calls and signals accept usually several arguments as ++parameters, either as input parameter, or as output parameter. Every ++argument belongs to a D-Bus type. ++ ++Such arguments must be mapped between the value encoded as a D-Bus ++type, and the corresponding type of Lisp objects. The mapping is ++applied Lisp object @expansion{} D-Bus type for input parameters, and ++D-Bus type @expansion{} Lisp object for output parameters. ++ ++ ++@section Input parameters. ++ ++Input parameters for D-Bus methods and signals occur as arguments of a ++Lisp function call. The following mapping to D-Bus types is ++applied, when the corresponding D-Bus message is created: ++ ++@example ++@multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN} ++@item Lisp type @tab @tab D-Bus type ++@item ++@item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN ++@item number @tab @expansion{} @tab DBUS_TYPE_UINT32 ++@item integer @tab @expansion{} @tab DBUS_TYPE_INT32 ++@item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE ++@item string @tab @expansion{} @tab DBUS_TYPE_STRING ++@item list @tab @expansion{} @tab DBUS_TYPE_ARRAY ++@end multitable ++@end example ++ ++Other Lisp objects, like symbols or hash tables, are not accepted as ++input parameter. ++ ++If it is necessary to use another D-Bus type, a corresponding type ++symbol can be preceeded to the corresponding Lisp object. Basic D-Bus ++types are represented by the type symbols @code{:byte}, ++@code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32}, ++@code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double}, ++@code{:string}, @code{:object-path} and @code{:signature}. ++ ++@noindent ++Example: ++ ++@lisp ++(dbus-call-method @dots{} @var{NUMBER} @var{STRING}) ++@end lisp ++ ++is equivalent to ++ ++@lisp ++(dbus-call-method @dots{} :uint32 @var{NUMBER} :string @var{STRING}) ++@end lisp ++ ++but different to ++ ++@lisp ++(dbus-call-method @dots{} :int32 @var{NUMBER} :signature @var{STRING}) ++@end lisp ++ ++The value for a byte D-Bus type can be any integer in the range 0 ++through 255. If a character is used as argument, modifiers ++represented outside this range are stripped of. For example, ++@code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to ++@code{:byte ?\C-x} or @code{:byte ?\M-\C-x}. ++ ++A D-Bus compound type is always represented as a list. The @sc{car} ++of this list can be the type symbol @code{:array}, @code{:variant}, ++@code{:struct} or @code{:dict-entry}, which would result in a ++corresponding D-Bus container. @code{:array} is optional, because ++this is the default compound D-Bus type for a list. ++ ++The objects being elements of the list are checked according to the ++D-Bus compound type rules. ++ ++@itemize ++@item An array must contain only elements of the same D-Bus type. It ++can be empty. ++ ++@item A variant must contain only one single element. ++ ++@item A dictionary entry must be element of an array, and it must ++contain only a key-value pair of two elements, with a basic D-Bus type ++key. ++ ++@item There is no restriction for structs. ++@end itemize ++ ++If an empty array needs an element D-Bus type other than string, it ++can contain exactly one element of D-Bus type @code{:signature}. The ++value of this element (a string) is used as the signature of the ++elements of this array. Example: ++ ++@lisp ++(dbus-call-method ++ :session "org.freedesktop.Notifications" ++ "/org/freedesktop/Notifications" ++ "org.freedesktop.Notifications" "Notify" ++ "GNU Emacs" ;; Application name. ++ 0 ;; No replacement of other notifications. ++ "" ;; No icon. ++ "Notification summary" ;; Summary. ++ (format ;; Body. ++ "This is a test notification, raised from %s" (emacs-version)) ++ '(:array) ;; No actions (empty array of strings). ++ '(:array :signature "@{sv@}") ;; No hints ++ ;; (empty array of dictionary entries). ++ ':int32 -1) ;; Default timeout. ++ ++@result{} 3 ++@end lisp ++ ++@defun dbus-string-to-byte-array string ++Sometimes, D-Bus methods require as input parameter an array of bytes, ++instead of a string. If it is guaranteed, that @var{string} is an ++UTF8 string, this function performs the conversion. Example: ++ ++@lisp ++(dbus-string-to-byte-array "/etc/hosts") ++ ++@result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47 ++ :byte 104 :byte 111 :byte 115 :byte 116 :byte 115) ++@end lisp ++@end defun ++ ++@defun dbus-escape-as-identifier string ++Escape an arbitrary @var{string} so it follows the rules for a C ++identifier. The escaped string can be used as object path component, ++interface element component, bus name component or member name in ++D-Bus. ++ ++The escaping consists of replacing all non-alphanumerics, and the ++first character if it's a digit, with an underscore and two ++lower-case hex digits. As a special case, "" is escaped to ++"_". Example: ++ ++@lisp ++(dbus-escape-as-identifier "0123abc_xyz\x01\xff") ++ ++@result{} "_30123abc_5fxyz_01_ff" ++@end lisp ++@end defun ++ ++ ++@section Output parameters. ++ ++Output parameters of D-Bus methods and signals are mapped to Lisp ++objects. ++ ++@example ++@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}} ++@item D-Bus type @tab @tab Lisp type ++@item ++@item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil} ++@item DBUS_TYPE_BYTE @tab @expansion{} @tab number ++@item DBUS_TYPE_UINT16 @tab @expansion{} @tab number ++@item DBUS_TYPE_INT16 @tab @expansion{} @tab number ++@item DBUS_TYPE_UINT32 @tab @expansion{} @tab number or float ++@item DBUS_TYPE_INT32 @tab @expansion{} @tab number or float ++@item DBUS_TYPE_UINT64 @tab @expansion{} @tab number or float ++@item DBUS_TYPE_INT64 @tab @expansion{} @tab number or float ++@item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float ++@item DBUS_TYPE_STRING @tab @expansion{} @tab string ++@item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string ++@item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string ++@item DBUS_TYPE_ARRAY @tab @expansion{} @tab list ++@item DBUS_TYPE_VARIANT @tab @expansion{} @tab list ++@item DBUS_TYPE_STRUCT @tab @expansion{} @tab list ++@item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list ++@end multitable ++@end example ++ ++A float object in case of @code{DBUS_TYPE_UINT32}, ++@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and ++@code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the ++Emacs number size range. ++ ++The resulting list of the last 4 D-Bus compound types contains as ++elements the elements of the D-Bus container, mapped according to the ++same rules. ++ ++The signal @code{PropertyModified}, discussed as example in ++@ref{Inspection}, would offer as Lisp data the following object ++(@var{BOOL} stands here for either @code{nil} or @code{t}): ++ ++@lisp ++(@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) ++@end lisp ++ ++@defun dbus-byte-array-to-string byte-array ++If a D-Bus method or signal returns an array of bytes, which are known ++to represent an UTF8 string, this function converts @var{byte-array} ++to the corresponding string. Example: ++ ++@lisp ++(dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115)) ++ ++@result{} "/etc/hosts" ++@end lisp ++@end defun ++ ++@defun dbus-unescape-from-identifier string ++Retrieve the original string from the encoded @var{string}. ++@var{string} must have been coded with ++@code{dbus-escape-as-identifier}. Example: ++ ++@lisp ++(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff") ++ ++@ifinfo ++@result{} "0123abc_xyz^Aÿ" ++@end ifinfo ++@ifnotinfo ++@result{} "0123abc_xyz^A@"y" ++@end ifnotinfo ++@end lisp ++@end defun ++ ++ ++@node Synchronous Methods ++@chapter Calling methods in a blocking way. ++@cindex method calls, synchronous ++@cindex synchronous method calls ++ ++Methods can be called synchronously (@dfn{blocking}) or asynchronously ++(@dfn{non-blocking}). ++ ++At D-Bus level, a method call consist of two messages: one message ++which carries the input parameters to the object owning the method to ++be called, and a reply message returning the resulting output ++parameters from the object. ++ ++@defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args ++This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is ++either the symbol @code{:system} or the symbol @code{:session}. ++ ++@var{service} is the D-Bus service name to be used. @var{path} is the ++D-Bus object path, @var{service} is registered at. @var{interface} is ++an interface offered by @var{service}. It must provide @var{method}. ++ ++If the parameter @code{:timeout} is given, the following integer ++@var{timeout} specifies the maximum number of milliseconds the method ++call must return. The default value is 25.000. If the method call ++doesn't return in time, a D-Bus error is raised (@pxref{Errors and ++Events}). ++ ++All other arguments args are passed to @var{method} as arguments. ++They are converted into D-Bus types as described in @ref{Type ++Conversion}. ++ ++The function returns the resulting values of @var{method} as a list of ++Lisp objects, according to the type conversion rules described in ++@ref{Type Conversion}. Example: ++ ++@lisp ++(dbus-call-method ++ :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp" ++ "org.gnome.seahorse.Keys" "GetKeyField" ++ "openpgp:657984B8C7A966DD" "simple-name") ++ ++@result{} (t ("Philip R. Zimmermann")) ++@end lisp ++ ++If the result of the method call is just one value, the converted Lisp ++object is returned instead of a list containing this single Lisp ++object. Example: ++ ++@lisp ++(dbus-call-method ++ :system "org.freedesktop.Hal" ++ "/org/freedesktop/Hal/devices/computer" ++ "org.freedesktop.Hal.Device" "GetPropertyString" ++ "system.kernel.machine") ++ ++@result{} "i686" ++@end lisp ++ ++With the @code{dbus-introspect} function it is possible to explore the ++interfaces of @samp{org.freedesktop.Hal} service. It offers the ++interfaces @samp{org.freedesktop.Hal.Manager} for the object at the ++path @samp{/org/freedesktop/Hal/Manager} as well as the interface ++@samp{org.freedesktop.Hal.Device} for all objects prefixed with the ++path @samp{/org/freedesktop/Hal/devices}. With the methods ++@samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to ++emulate the @code{lshal} command on GNU/Linux systems: ++ ++@lisp ++(dolist (device ++ (dbus-call-method ++ :system "org.freedesktop.Hal" ++ "/org/freedesktop/Hal/Manager" ++ "org.freedesktop.Hal.Manager" "GetAllDevices")) ++ (message "\nudi = %s" device) ++ (dolist (properties ++ (dbus-call-method ++ :system "org.freedesktop.Hal" device ++ "org.freedesktop.Hal.Device" "GetAllProperties")) ++ (message " %s = %S" ++ (car properties) (or (caar (cdr properties)) "")))) ++ ++@print{} "udi = /org/freedesktop/Hal/devices/computer ++ info.addons = (\"hald-addon-acpi\") ++ info.bus = \"unknown\" ++ info.product = \"Computer\" ++ info.subsystem = \"unknown\" ++ info.udi = \"/org/freedesktop/Hal/devices/computer\" ++ linux.sysfs_path_device = \"(none)\" ++ power_management.acpi.linux.version = \"20051216\" ++ power_management.can_suspend_to_disk = t ++ power_management.can_suspend_to_ram = \"\" ++ power_management.type = \"acpi\" ++ smbios.bios.release_date = \"11/07/2001\" ++ system.chassis.manufacturer = \"COMPAL\" ++ system.chassis.type = \"Notebook\" ++ system.firmware.release_date = \"03/19/2005\" ++ @dots{}" ++@end lisp ++@end defun ++ ++@defun dbus-call-method-non-blocking bus service path interface method &optional :timeout timeout &rest args ++Call @var{method} on the D-Bus @var{bus}, but don't block the event queue. ++This is necessary for communicating to registered D-Bus methods, ++which are running in the same Emacs process. ++ ++The arguments are the same as in @code{dbus-call-method}. Example: ++ ++@lisp ++(dbus-call-method-non-blocking ++ :system "org.freedesktop.Hal" ++ "/org/freedesktop/Hal/devices/computer" ++ "org.freedesktop.Hal.Device" "GetPropertyString" ++ "system.kernel.machine") ++ ++@result{} "i686" ++@end lisp ++@end defun ++ ++ ++@node Asynchronous Methods ++@chapter Calling methods non-blocking. ++@cindex method calls, asynchronous ++@cindex asynchronous method calls ++ ++@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args ++This function calls @var{method} on the D-Bus @var{bus} ++asynchronously. @var{bus} is either the symbol @code{:system} or the ++symbol @code{:session}. ++ ++@var{service} is the D-Bus service name to be used. @var{path} is the ++D-Bus object path, @var{service} is registered at. @var{interface} is ++an interface offered by @var{service}. It must provide @var{method}. ++ ++@var{handler} is a Lisp function, which is called when the ++corresponding return message has arrived. ++ ++If the parameter @code{:timeout} is given, the following integer ++@var{timeout} specifies the maximum number of milliseconds a reply ++message must arrive. The default value is 25.000. If there is no ++reply message in time, a D-Bus error is raised (@pxref{Errors and ++Events}). ++ ++All other arguments args are passed to @var{method} as arguments. ++They are converted into D-Bus types as described in @ref{Type ++Conversion}. ++ ++The function returns a key into the hash table ++@code{dbus-registered-functions-table}. The corresponding entry in ++the hash table is removed, when the return message has been arrived, ++and @var{handler} is called. Example: ++ ++@lisp ++(dbus-call-method-asynchronously ++ :system "org.freedesktop.Hal" ++ "/org/freedesktop/Hal/devices/computer" ++ "org.freedesktop.Hal.Device" "GetPropertyString" 'message ++ "system.kernel.machine") ++ ++@result{} (:system 2) ++ ++@print{} i686 ++@end lisp ++@end defun ++ ++ ++@node Receiving Method Calls ++@chapter Offering own methods. ++@cindex method calls, returning ++@cindex returning method calls ++ ++Emacs can also offer own methods, which can be called by other ++applications. These methods could be an implementation of an ++interface of a well known service, like @samp{org.freedesktop.TextEditor}. ++ ++It could be also an implementation of an own interface. In this case, ++the service name must be @samp{org.gnu.Emacs}. The object path shall ++begin with @samp{/org/gnu/Emacs/@strong{Application}/}, and the ++interface name shall be @code{org.gnu.Emacs.@strong{Application}}. ++@samp{@strong{Application}} is the name of the application which ++provides the interface. ++ ++@deffn Constant dbus-service-emacs ++The well known service name of Emacs. ++@end deffn ++ ++@deffn Constant dbus-path-emacs ++The object path head "/org/gnu/Emacs" used by Emacs. All object ++paths, used by offered methods or signals, shall start with this ++string. ++@end deffn ++ ++@defun dbus-register-method bus service path interface method handler ++With this function, an application registers @var{method} on the D-Bus ++@var{bus}. ++ ++@var{bus} is either the symbol @code{:system} or the symbol ++@code{:session}. ++ ++@var{service} is the D-Bus service name of the D-Bus object ++@var{method} is registered for. It must be a known name. ++ ++@var{path} is the D-Bus object path @var{service} is ++registered. ++ ++@var{interface} is the interface offered by @var{service}. It must ++provide @var{method}. ++ ++@var{handler} is a Lisp function to be called when a @var{method} call ++is received. It must accept as arguments the input arguments of ++@var{method}. @var{handler} should return a list, whose elements are ++to be used as arguments for the reply message of @var{method}. This ++list can be composed like the input parameters in @ref{Type ++Conversion}. ++ ++If @var{handler} wants to return just one Lisp object and it is not a ++cons cell, @var{handler} can return this object directly, instead of ++returning a list containing the object. ++ ++The default D-Bus timeout when waiting for a message reply is 25 ++seconds. This value could be even smaller, depending on the calling ++client. Therefore, @var{handler} shall not last longer than ++absolutely necessary. ++ ++@code{dbus-register-method} returns a Lisp object, which can be used ++as argument in @code{dbus-unregister-object} for removing the ++registration for @var{method}. Example: ++ ++@lisp ++(defun my-dbus-method-handler (filename) ++ (let (result) ++ (if (find-file filename) ++ (setq result '(:boolean t)) ++ (setq result '(:boolean nil))) ++ result)) ++ ++@result{} my-dbus-method-handler ++ ++(dbus-register-method ++ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" ++ "org.freedesktop.TextEditor" "OpenFile" ++ 'my-dbus-method-handler) ++ ++@result{} ((:session "org.freedesktop.TextEditor" "OpenFile") ++ ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" ++ my-dbus-method-handler)) ++@end lisp ++ ++If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile} ++from another D-Bus application with a filename as parameter, the file ++is opened in Emacs, and the method returns either @var{true} or ++@var{false}, indicating the success if the method. As test tool one ++could use the command line tool @code{dbus-send} in a shell: ++ ++@example ++# dbus-send --session --print-reply \ ++ --dest="org.freedesktop.TextEditor" \ ++ "/org/freedesktop/TextEditor" \ ++ "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts" ++ ++@print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2 ++ boolean true ++@end example ++ ++You can indicate an error by raising the Emacs signal ++@code{dbus-error}. The handler above could be changed like this: ++ ++@lisp ++(defun my-dbus-method-handler (&rest args) ++ (unless (and (= (length args) 1) (stringp (car args))) ++ (signal 'dbus-error (list (format "Wrong argument list: %S" args)))) ++ (condition-case err ++ (find-file (car args)) ++ (error (signal 'dbus-error (cdr err)))) ++ t) ++ ++@result{} my-dbus-method-handler ++@end lisp ++ ++The test runs then ++ ++@example ++# dbus-send --session --print-reply \ ++ --dest="org.freedesktop.TextEditor" \ ++ "/org/freedesktop/TextEditor" \ ++ "org.freedesktop.TextEditor.OpenFile" \ ++ string:"/etc/hosts" string:"/etc/passwd" ++ ++@print{} Error org.freedesktop.DBus.Error.Failed: ++ Wrong argument list: ("/etc/hosts" "/etc/passwd") ++@end example ++@end defun ++ ++ ++@node Signals ++@chapter Sending and receiving signals. ++@cindex signals ++ ++Signals are broadcast messages. They carry input parameters, which ++are received by all objects which have registered for such a signal. ++ ++@defun dbus-send-signal bus service path interface signal &rest args ++This function is similar to @code{dbus-call-method}. The difference ++is, that there are no returning output parameters. ++ ++The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is ++either the symbol @code{:system} or the symbol @code{:session}. It ++doesn't matter whether another object has registered for @var{signal}. ++ ++@var{service} is the D-Bus service name of the object the signal is ++emitted from. @var{path} is the corresponding D-Bus object path, ++@var{service} is registered at. @var{interface} is an interface ++offered by @var{service}. It must provide @var{signal}. ++ ++All other arguments args are passed to @var{signal} as arguments. ++They are converted into D-Bus types as described in @ref{Type ++Conversion}. Example: ++ ++@lisp ++(dbus-send-signal ++ :session dbus-service-emacs dbus-path-emacs ++ (concat dbus-service-emacs ".FileManager") "FileModified" ++ "/home/albinus/.emacs") ++@end lisp ++@end defun ++ ++@defun dbus-register-signal bus service path interface signal handler &rest args ++With this function, an application registers for @var{signal} on the ++D-Bus @var{bus}. ++ ++@var{bus} is either the symbol @code{:system} or the symbol ++@code{:session}. ++ ++@var{service} is the D-Bus service name used by the sending D-Bus ++object. It can be either a known name or the unique name of the D-Bus ++object sending the signal. In case of a unique name, signals won't be ++received any longer once the object owning this unique name has ++disappeared, and a new queued object has replaced it. ++ ++When @var{service} is @code{nil}, related signals from all D-Bus ++objects shall be accepted. ++ ++@var{path} is the corresponding D-Bus object path, @var{service} is ++registered at. It can also be @code{nil} if the path name of incoming ++signals shall not be checked. ++ ++@var{interface} is an interface offered by @var{service}. It must ++provide @var{signal}. ++ ++@var{handler} is a Lisp function to be called when the @var{signal} is ++received. It must accept as arguments the output parameters ++@var{signal} is sending. ++ ++All other arguments @var{args}, if specified, must be strings. They ++stand for the respective arguments of @var{signal} in their order, and ++are used for filtering as well. A @code{nil} argument might be used ++to preserve the order. ++ ++@code{dbus-register-signal} returns a Lisp object, which can be used ++as argument in @code{dbus-unregister-object} for removing the ++registration for @var{signal}. Example: ++ ++@lisp ++(defun my-dbus-signal-handler (device) ++ (message "Device %s added" device)) ++ ++@result{} my-dbus-signal-handler ++ ++(dbus-register-signal ++ :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" ++ "org.freedesktop.Hal.Manager" "DeviceAdded" ++ 'my-dbus-signal-handler) ++ ++@result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded") ++ ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" ++ my-signal-handler)) ++@end lisp ++ ++As we know from the introspection data of interface ++@samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded} ++provides one single parameter, which is mapped into a Lisp string. ++The callback function @code{my-dbus-signal-handler} must define one ++single string argument therefore. Plugging an USB device to your ++machine, when registered for signal @samp{DeviceAdded}, will show you ++which objects the GNU/Linux @code{hal} daemon adds. ++@end defun ++ ++@defun dbus-unregister-object object ++Unregister @var{object} from the D-Bus. @var{object} must be the ++result of a preceding @code{dbus-register-signal} or ++@code{dbus-register-method} call. It returns @code{t} if @var{object} ++has been unregistered, @code{nil} otherwise. ++@end defun ++ ++ ++@node Errors and Events ++@chapter Errors and events. ++@cindex errors ++@cindex events ++ ++Input parameters of @code{dbus-call-method}, ++@code{dbus-call-method-non-blocking}, ++@code{dbus-call-method-asynchronously}, and ++@code{dbus-register-signal} are checked for correct D-Bus types. If ++there is a type mismatch, the Lisp error @code{wrong-type-argument} ++@code{D-Bus ARG} is raised. ++ ++All errors raised by D-Bus are signaled with the error symbol ++@code{dbus-error}. If possible, error messages from D-Bus are ++appended to the @code{dbus-error}. ++ ++@defspec dbus-ignore-errors forms@dots{} ++This executes @var{forms} exactly like a @code{progn}, except that ++@code{dbus-error} errors are ignored during the @var{forms}. These ++errors can be made visible when variable @code{dbus-debug} is set to ++@code{t}. ++@end defspec ++ ++Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc ++Events, , , elisp}). The generated event has this form: ++ ++@lisp ++(dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler} ++ &rest @var{args}) ++@end lisp ++ ++@var{bus} identifies the D-Bus the message is coming from. It is ++either the symbol @code{:system} or the symbol @code{:session}. ++ ++@var{type} is the D-Bus message type which has caused the event. It ++can be @code{dbus-message-type-invalid}, ++@code{dbus-message-type-method-call}, ++@code{dbus-message-type-method-return}, ++@code{dbus-message-type-error}, or @code{dbus-message-type-signal}. ++@var{serial} is the serial number of the received D-Bus message. ++ ++@var{service} and @var{path} are the unique name and the object path ++of the D-Bus object emitting the message. @var{interface} and ++@var{member} denote the message which has been sent. ++ ++@var{handler} is the callback function which has been registered for ++this message (see @pxref{Signals}). When a @code{dbus-event} event ++arrives, @var{handler} is called with @var{args} as arguments. ++ ++In order to inspect the @code{dbus-event} data, you could extend the ++definition of the callback function in @ref{Signals}: ++ ++@lisp ++(defun my-dbus-signal-handler (&rest args) ++ (message "my-dbus-signal-handler: %S" last-input-event)) ++@end lisp ++ ++There exist convenience functions which could be called inside a ++callback function in order to retrieve the information from the event. ++ ++@defun dbus-event-bus-name event ++Returns the bus name @var{event} is coming from. ++The result is either the symbol @code{:system} or the symbol @code{:session}. ++@end defun ++ ++@defun dbus-event-message-type event ++Returns the message type of the corresponding D-Bus message. The ++result is a number. ++@end defun ++ ++@defun dbus-event-serial-number event ++Returns the serial number of the corresponding D-Bus message. ++The result is a number. ++@end defun ++ ++@defun dbus-event-service-name event ++Returns the unique name of the D-Bus object @var{event} is coming from. ++@end defun ++ ++@defun dbus-event-path-name event ++Returns the object path of the D-Bus object @var{event} is coming from. ++@end defun ++ ++@defun dbus-event-interface-name event ++Returns the interface name of the D-Bus object @var{event} is coming from. ++@end defun ++ ++@defun dbus-event-member-name event ++Returns the member name of the D-Bus object @var{event} is coming ++from. It is either a signal name or a method name. ++@end defun ++ ++D-Bus errors are not propagated during event handling, because it is ++usually not desired. D-Bus errors in events can be made visible by ++setting the variable @code{dbus-debug} to @code{t}. They can also be ++handled by a hook function. ++ ++@defvar dbus-event-error-hooks ++This hook variable keeps a list of functions, which are called when a ++D-Bus error happens in the event handler. Every function must accept ++two arguments, the event and the error variable catched in ++@code{condition-case} by @code{dbus-error}. ++ ++Such functions can be used the adapt the error signal to be raised. ++Example: ++ ++@lisp ++(defun my-dbus-event-error-handler (event error) ++ (when (string-equal (concat dbus-service-emacs ".FileManager") ++ (dbus-event-interface-name event)) ++ (message "my-dbus-event-error-handler: %S %S" event error) ++ (signal 'file-error (cdr error)))) ++ ++(add-hook 'dbus-event-error-hooks 'my-dbus-event-error-handler) ++@end lisp ++@end defvar ++ ++Hook functions shall take into account, that there might be other ++D-Bus applications running. Therefore, they shall check carefully, ++whether a given D-Bus error is related to them. ++ ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@bye ++ ++@ignore ++ arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8 ++@end ignore +diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi +new file mode 100644 +index 0000000..56e2c86 +--- /dev/null ++++ b/doc/misc/dired-x.texi +@@ -0,0 +1,1266 @@ ++\input texinfo @comment -*-texinfo-*- ++ ++@c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs ++@c ++@c Author: Sebastian Kremer ++@c Lawrence R. Dodd ++@c [Dodd's address no longer valid.] ++ ++@comment %**start of header (This is for running Texinfo on a region.) ++@c FOR GNU EMACS USE ../info/dired-x BELOW ++@setfilename ../../info/dired-x ++@c dired-x.el REVISION NUMBER ++@settitle Dired Extra Version 2 User's Manual ++@iftex ++@finalout ++@end iftex ++@c @setchapternewpage odd % For book style double sided manual. ++@comment %**end of header (This is for running Texinfo on a region.) ++ ++@copying ++Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* Dired-X: (dired-x). Dired Extra Features. ++@end direntry ++ ++@c @smallbook ++@tex ++\overfullrule=0pt ++%\global\baselineskip 30pt % For printing in double spaces ++@end tex ++ ++@titlepage ++@sp 6 ++@c dired-x.el REVISION NUMBER ++@center @titlefont{Dired Extra Version 2} ++@sp 2 ++@center @titlefont{For The GNU Emacs} ++@sp 1 ++@center @titlefont{Directory Editor} ++@sp 4 ++@center Lawrence R@. Dodd ++@c @center @t{dodd@@roebling.poly.edu} ++@sp 5 ++@center (Based on @file{dired.texi} by Sebastian Kremer ) ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++ ++@ifnottex ++ ++@node Top ++@comment node-name, next, previous, up ++ ++@noindent ++This documents the ``extra'' features for Dired Mode for GNU Emacs that are ++provided by the file @file{dired-x.el}. ++ ++@itemize @bullet ++ ++@item ++Based on @file{dired.texi} by Sebastian Kremer ++ ++@c dired-x.el REVISION NUMBER ++@item ++For @file{dired-x.el} revision 2 ++ ++@c @item ++@c Revision of this manual: 2.53 (2001/02/25 14:05:46) ++ ++@c @item ++@c Bugs to Lawrence R. Dodd . @emph{Please} type ++@c @kbd{M-x dired-x-submit-report} to submit a bug report (@pxref{Bugs}). ++ ++@c @item ++@c You can obtain a copy of this package via anonymous ftp in ++@c @t{/roebling.poly.edu:/pub/packages/dired-x.tar.gz} ++ ++@end itemize ++ ++@insertcopying ++ ++@menu ++* Introduction:: ++* Installation:: ++* Omitting Files in Dired:: ++* Local Variables:: ++* Shell Command Guessing:: ++* Virtual Dired:: ++* Advanced Mark Commands:: ++* Multiple Dired Directories:: ++* Find File At Point:: ++* Miscellaneous Commands:: ++* Bugs:: ++ ++* GNU Free Documentation License:: ++* Concept Index:: ++* Command Index:: ++* Key Index:: ++* Variable Index:: ++ ++@end menu ++ ++@end ifnottex ++ ++@node Introduction, Installation, Top, Top ++@comment node-name, next, previous, up ++@chapter Introduction ++ ++This documents the @emph{extra} features for Dired Mode for GNU Emacs. It ++is derived from version 1.191 of Sebastian Kremer's @file{dired-x.el}. ++ ++In adopting this @file{dired-x.el} to GNU Emacs v19 some material that has ++been incorporated into @file{dired.el} and @file{dired-aux.el} of the GNU Emacs ++19 distribution has been removed and some material was modified for agreement ++with the functions in @file{dired.el} and @file{dired-aux.el}. For example, ++the code using @code{gmhist} history functions was replaced with code using ++the mini-buffer history now built into GNU Emacs. Finally, a few other ++features have been added and a few more functions have been bound to keys. ++ ++@ifnottex ++@menu ++* Features:: ++* Technical Details:: ++@end menu ++@end ifnottex ++ ++@node Features, Technical Details, , Introduction ++@comment node-name, next, previous, up ++@section Features ++@cindex Features ++ ++Some features provided by Dired Extra ++ ++@enumerate ++@item ++Omitting uninteresting files from Dired listing. ++@itemize @bullet ++@xref{Omitting Files in Dired}. ++@end itemize ++@item ++Local variables for Dired directories. ++@itemize @bullet ++@xref{Local Variables}. ++@end itemize ++@item ++Guessing shell commands in Dired buffers. ++@itemize @bullet ++@xref{Shell Command Guessing}. ++@end itemize ++@item ++Running Dired command in non-Dired buffers. ++@itemize @bullet ++@xref{Virtual Dired}. ++@end itemize ++@item ++Finding a file mentioned in a buffer ++@itemize @bullet ++@xref{Find File At Point}. ++@end itemize ++@item ++Commands using file marking. ++@itemize @bullet ++@xref{Advanced Mark Commands}. ++@end itemize ++@end enumerate ++ ++@noindent ++@file{dired-x.el} binds some functions to keys in Dired Mode (@pxref{Key ++Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to ++@code{dired-jump} (@pxref{Miscellaneous Commands}). It may also bind @kbd{C-x ++C-f} and @kbd{C-x 4 C-f} to @code{dired-x-find-file} and ++@code{dired-x-find-file-other-window}, respectively (@pxref{Find File At ++Point}). ++ ++@node Technical Details, , Features, Introduction ++@comment node-name, next, previous, up ++@section Technical Details ++@cindex Redefined functions ++@cindex @file{dired-aux.el} ++ ++When loaded this code @emph{redefines} the following functions of GNU Emacs ++from @file{dired.el} ++ ++@itemize @bullet ++@item ++@code{dired-clean-up-after-deletion} ++@item ++@code{dired-find-buffer-nocreate} ++@item ++@code{dired-initial-position} ++@item ++@code{dired-up-directory} ++@end itemize ++ ++@noindent ++and the following functions from @file{dired-aux.el} ++ ++@itemize @bullet ++@item ++@code{dired-add-entry} ++@item ++@code{dired-read-shell-command} ++@end itemize ++ ++@node Installation, Omitting Files in Dired, Introduction, Top ++@comment node-name, next, previous, up ++@chapter Installation ++ ++@noindent ++This manual describes the Dired features provided by the file ++@file{dired-x.el}. To take advantage of these features, you must load the ++file and (optionally) set some variables. ++ ++@noindent ++In your @file{.emacs} file in your home directory, or in the system-wide ++initialization file @file{default.el} in the @file{site-lisp} directory, put ++ ++@example ++(add-hook 'dired-load-hook ++ (lambda () ++ (load "dired-x") ++ ;; Set dired-x global variables here. For example: ++ ;; (setq dired-guess-shell-gnutar "gtar") ++ ;; (setq dired-x-hands-off-my-keys nil) ++ )) ++(add-hook 'dired-mode-hook ++ (lambda () ++ ;; Set dired-x buffer-local variables here. For example: ++ ;; (dired-omit-mode 1) ++ )) ++@end example ++ ++@noindent ++This will load @file{dired-x.el} when Dired is first invoked (for example, ++when you first type @kbd{C-x d}). ++ ++@ifnottex ++@menu ++* Optional Installation Dired Jump:: ++* Optional Installation File At Point:: ++@end menu ++@end ifnottex ++ ++@node Optional Installation Dired Jump, Optional Installation File At Point, , Installation ++@comment node-name, next, previous, up ++@section Optional Installation Dired Jump ++ ++@cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window} ++ ++In order to have @code{dired-jump} and @code{dired-jump-other-window} ++(@pxref{Miscellaneous Commands}) work @emph{before} @code{dired} and ++@code{dired-x} have been properly loaded the user should set-up an autoload ++for these functions. In your @file{.emacs} file put ++ ++@example ++;; Autoload `dired-jump' and `dired-jump-other-window'. ++;; We autoload from FILE dired.el. This will then load dired-x.el ++;; and hence define `dired-jump' and `dired-jump-other-window'. ++(define-key global-map "\C-x\C-j" 'dired-jump) ++(define-key global-map "\C-x4\C-j" 'dired-jump-other-window) ++ ++(autoload (quote dired-jump) "dired" "\ ++Jump to Dired buffer corresponding to current buffer. ++If in a file, Dired the current directory and move to file's line. ++If in Dired already, pop up a level and goto old directory's line. ++In case the proper Dired file line cannot be found, refresh the Dired ++buffer and try again." t nil) ++ ++(autoload (quote dired-jump-other-window) "dired" "\ ++Like \\[dired-jump] (dired-jump) but in other window." t nil) ++@end example ++ ++Note that in recent releases of GNU Emacs 19 (i.e., 19.25 or later) the file ++@file{../lisp/loaddefs.el} of the Emacs distribution already contains the ++proper auto-loading for @code{dired-jump} so you need only put ++ ++@example ++(define-key global-map "\C-x\C-j" 'dired-jump) ++@end example ++ ++@noindent ++in your @file{.emacs} file in order to have @kbd{C-x C-j} work ++before @code{dired} is loaded. ++ ++@node Optional Installation File At Point, , Optional Installation Dired Jump, Installation ++@comment node-name, next, previous, up ++@section Optional Installation File At Point ++ ++@cindex Binding @code{dired-x-find-file} ++If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over ++@code{find-file} (@pxref{Find File At Point}), then you will need to set ++@code{dired-x-hands-off-my-keys} and make a call to the function ++@code{dired-x-bind-find-file} in the @code{dired-load-hook}: ++ ++@example ++(add-hook 'dired-load-hook ++ (lambda () ++ (load "dired-x") ++ ;; Bind dired-x-find-file. ++ (setq dired-x-hands-off-my-keys nil) ++ ;; Make sure our binding preference is invoked. ++ (dired-x-bind-find-file) ++ )) ++@end example ++ ++Alternatively, you can set the variable @emph{before} @file{dired-x.el} is ++loaded ++ ++@example ++(add-hook 'dired-load-hook ++ (lambda () ++ ;; Bind dired-x-find-file. ++ (setq dired-x-hands-off-my-keys nil) ++ (load "dired-x") ++ )) ++@end example ++ ++@node Omitting Files in Dired, Local Variables, Installation, Top ++@comment node-name, next, previous, up ++@chapter Omitting Files in Dired ++ ++@cindex Omitting Files in Dired ++@cindex Uninteresting files ++@dfn{Omitting} a file means removing it from the directory listing. Omitting ++is useful for keeping Dired buffers free of ``uninteresting'' files (for ++instance, auto-save, auxiliary, backup, and revision control files) so that ++the user can concentrate on the interesting files. Like hidden files, omitted ++files are never seen by Dired. Omitting differs from hiding in several ++respects: ++ ++@itemize @bullet ++ ++@item ++Omitting works on individual files, not on directories; an entire directory ++cannot be omitted (though each of its files could be). ++ ++@item ++Omitting is wholesale; if omitting is turned on for a Dired buffer, then all ++uninteresting files listed in that buffer are omitted. The user does not omit ++(or unomit) files one at a time. ++ ++@item ++Omitting can be automatic; uninteresting file lines in the buffer can be ++removed before the user ever sees them. ++ ++@item ++Marked files are never omitted. ++@end itemize ++ ++@table @kbd ++@item M-o ++@kindex M-o ++@findex dired-omit-mode ++(@code{dired-omit-mode}) Toggle between displaying and omitting ++``uninteresting'' files. ++@item * O ++@kindex * O ++@findex dired-mark-omitted ++(@code{dired-mark-omitted}) Mark ``uninteresting'' files. ++@end table ++ ++@noindent ++In order to make Dired Omit work you first need to load @file{dired-x.el} ++inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate ++@code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}). ++ ++@ifnottex ++@menu ++* Omitting Variables:: ++* Omitting Examples:: ++* Omitting Technical:: ++@end menu ++@end ifnottex ++ ++@node Omitting Variables, Omitting Examples, , Omitting Files in Dired ++@comment node-name, next, previous, up ++ ++@section Omitting Variables ++ ++@cindex Customizing file omitting ++The following variables can be used to customize omitting. ++ ++@table @code ++ ++@vindex dired-omit-mode ++@item dired-omit-mode ++ ++Default: @code{nil} ++ ++@cindex How to make omitting the default in Dired ++If non-@code{nil}, ``uninteresting'' files are not listed. ++Uninteresting files are those whose files whose names match regexp ++@code{dired-omit-files}, plus those ending with extensions in ++@code{dired-omit-extensions}. @kbd{M-o} (@code{dired-omit-mode}) ++toggles its value, which is buffer-local. Put ++ ++@example ++(dired-omit-mode 1) ++@end example ++ ++@noindent ++inside your @code{dired-mode-hook} to have omitting initially turned on in ++@emph{every} Dired buffer (@pxref{Installation}). You can then use @kbd{M-o} to ++unomit in that buffer. ++ ++To enable omitting automatically only in certain directories one can use Dired ++Local Variables and put ++ ++@example ++Local Variables: ++dired-omit-mode: t ++End: ++@end example ++ ++@noindent ++into a file @file{.dired} (the default value of ++@code{dired-local-variables-file}) in that directory (@pxref{Local Variables}). ++ ++@table @code ++@findex dired-omit-here-always ++@item dired-omit-here-always ++ ++This is an interactive function that creates a local variables file exactly ++like the example above (if it does not already exist) in the file ++@code{dired-local-variables-file} in the current directory and then refreshes ++the directory listing (@pxref{Local Variables}). ++@end table ++ ++@vindex dired-omit-files ++@item dired-omit-files ++ ++Default: @code{"^#\\|\\.$"} ++ ++Files whose names match this buffer-local regexp will not be displayed. ++This only has effect when @code{dired-omit-mode}'s value is @code{t}. ++ ++The default value omits the special directories @file{.} and @file{..} and ++autosave files (plus other files ending in @file{.}) (@pxref{Omitting Examples}). ++ ++@vindex dired-omit-extensions ++@item dired-omit-extensions ++ ++Default: The elements of @code{completion-ignored-extensions}, ++@code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions} ++and @code{dired-texinfo-unclean-extensions}. ++ ++If non-@code{nil}, a list of extensions (strings) to omit from Dired listings. ++Its format is the same as that of @code{completion-ignored-extensions}. ++ ++@vindex dired-omit-localp ++@item dired-omit-localp ++ ++Default: @code{no-dir} ++ ++The @var{localp} argument @code{dired-omit-expunge} passes to ++@code{dired-get-filename}. If it is @code{no-dir}, omitting is much faster, ++but you can only match against the non-directory part of the file name. Set it ++to @code{nil} if you need to match the whole file name or @code{t} to match the ++file name relative to the buffer's top-level directory. ++ ++@item dired-omit-marker-char ++@vindex dired-omit-marker-char ++@cindex Omitting additional files ++Default: @kbd{C-o} ++ ++Temporary marker used by Dired to implement omitting. Should never be used ++as marker by the user or other packages. There is one exception to this rule: ++by adding ++ ++@example ++(setq dired-mark-keys "\C-o") ++;; i.e., the value of dired-omit-marker-char ++;; (which is not defined yet) ++@end example ++ ++@noindent ++to your @file{~/.emacs}, you can bind the @kbd{C-o} key to insert a ++@kbd{C-o} marker, thus causing these files to be omitted in addition to the ++usually omitted files. Unfortunately the files you omitted manually this way ++will show up again after reverting the buffer, unlike the others. ++ ++@end table ++ ++@node Omitting Examples, Omitting Technical, Omitting Variables, Omitting Files in Dired ++@comment node-name, next, previous, up ++@section Examples of Omitting Various File Types ++ ++@itemize @bullet ++ ++@item ++@cindex RCS files, how to omit them in Dired ++@cindex Omitting RCS files in Dired ++If you wish to avoid seeing RCS files and the @file{RCS} directory, then put ++ ++@example ++(setq dired-omit-files ++ (concat dired-omit-files "\\|^RCS$\\|,v$")) ++@end example ++ ++@noindent ++in the @code{dired-load-hook} (@pxref{Installation}). This assumes ++@code{dired-omit-localp} has its default value of @code{no-dir} to make the ++@code{^}-anchored matches work. As a slower alternative, with ++@code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of ++@code{^} in the regexp. ++ ++@item ++@cindex Tib files, how to omit them in Dired ++@cindex Omitting tib files in Dired ++If you use @code{tib}, the bibliography program for use with @TeX{} and ++La@TeX{}, and you ++want to omit the @file{INDEX} and the @file{*-t.tex} files, then put ++ ++@example ++(setq dired-omit-files ++ (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$")) ++@end example ++ ++@noindent ++in the @code{dired-load-hook} (@pxref{Installation}). ++ ++@item ++@cindex Dot files, how to omit them in Dired ++@cindex Omitting dot files in Dired ++If you do not wish to see @samp{dot} files (files starting with a @file{.}), ++then put ++ ++@example ++(setq dired-omit-files ++ (concat dired-omit-files "\\|^\\..+$")) ++@end example ++ ++@noindent ++in the @code{dired-load-hook} (@pxref{Installation}). ++ ++@end itemize ++ ++@node Omitting Technical, , Omitting Examples, Omitting Files in Dired ++@comment node-name, next, previous, up ++@section Some Technical Details of Omitting ++ ++Loading @file{dired-x.el} will install Dired Omit by putting ++@code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will ++call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} ++in your @code{dired-mode-hook}. ++ ++@node Local Variables, Shell Command Guessing, Omitting Files in Dired, Top ++@comment node-name, next, previous, up ++@chapter Local Variables for Dired Directories ++ ++@cindex Local Variables for Dired Directories ++@vindex dired-local-variables-file ++@vindex dired-enable-local-variables ++@noindent ++When Dired visits a directory, it looks for a file whose name is the value of ++variable @code{dired-local-variables-file} (default: @file{.dired}). If such ++a file is found, Dired will temporarily insert it into the Dired buffer and ++run @code{hack-local-variables}. ++ ++@noindent ++For example, if the user puts ++ ++@example ++Local Variables: ++dired-actual-switches: "-lat" ++dired-omit-mode: t ++End: ++@end example ++ ++@noindent ++into a file called @file{.dired} in a directory then when that directory is ++viewed it will be ++ ++@enumerate ++@item ++sorted by date ++@item ++omitted automatically ++@end enumerate ++ ++@noindent ++You can set @code{dired-local-variables-file} to @code{nil} to suppress this. ++The value of @code{dired-enable-local-variables} controls if and how these ++local variables are read. This variable exists so that if may override the ++default value of @code{enable-local-variables}. ++ ++@noindent ++Please see the GNU Emacs Manual to learn more about local variables. ++@xref{File Variables,Local Variables in Files,Local Variables in ++Files,emacs,The GNU Emacs Manual}. ++ ++@noindent ++The following variables affect Dired Local Variables ++ ++@table @code ++@vindex dired-local-variables-file ++@item dired-local-variables-file ++Default: @code{".dired"} ++ ++If non-@code{nil}, file name for local variables for Dired. If Dired finds a ++file with that name in the current directory, it will temporarily insert it ++into the Dired buffer and run @code{hack-local-variables}. ++ ++@vindex dired-enable-local-variables ++@item dired-enable-local-variables ++Default: @code{t} ++ ++Controls the use of local-variables lists in Dired. The value can be @code{t}, ++@code{nil}, or something else. A value of @code{t} means local-variables ++lists are obeyed in the @code{dired-local-variables-file}; @code{nil} means ++they are ignored; anything else means query. This variable temporarily ++overrides the value of @code{enable-local-variables} when the Dired Local ++Variables are hacked. ++@end table ++ ++@node Shell Command Guessing, Virtual Dired, Local Variables, Top ++@comment node-name, next, previous, up ++@chapter Shell Command Guessing ++@cindex Guessing shell commands for files. ++ ++Based upon the name of a file, Dired tries to guess what shell ++command you might want to apply to it. For example, if you have point ++on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess ++you want to @samp{tar xvf} it and suggest that as the default shell ++command. ++ ++The default is mentioned in brackets and you can type @kbd{M-n} to get ++the default into the minibuffer and then edit it, e.g., to change ++@samp{tar xvf} to @samp{tar tvf}. If there are several commands for a given ++file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type ++@kbd{M-n} several times to see each of the matching commands. ++ ++Dired only tries to guess a command for a single file, never for a list ++of marked files. ++ ++@table @code ++@item dired-guess-shell-alist-default ++@vindex dired-guess-shell-alist-default ++Predefined rules for shell commands. Set this to @code{nil} to turn guessing off. ++The elements of @code{dired-guess-shell-alist-user} (defined by the ++user) will override these rules.@refill ++ ++@item dired-guess-shell-alist-user ++@vindex dired-guess-shell-alist-user ++If non-@code{nil}, a user-defined alist of file regexps and their suggested ++commands. These rules take precedence over the predefined rules in the ++variable @code{dired-guess-shell-alist-default} (to which they are prepended) ++when @code{dired-do-shell-command} is run). ++@refill ++ ++Each element of the alist looks like ++ ++@example ++(@var{regexp} @var{command}@dots{}) ++@end example ++ ++@noindent ++where each @var{command} can either be a string or a Lisp expression ++that evaluates to a string. If several commands are given, all of ++them will temporarily be pushed onto the history. ++ ++If @samp{*} in the shell command, that means to substitute the file ++name. ++ ++You can set this variable in your @file{~/.emacs}. For example, ++to add rules for @samp{.foo} and @samp{.bar} file extensions, write ++ ++@example ++(setq dired-guess-shell-alist-user ++ (list ++ (list "\\.foo$" "@var{foo-command}");; fixed rule ++ ;; possibly more rules... ++ (list "\\.bar$";; rule with condition test ++ '(if @var{condition} ++ "@var{bar-command-1}" ++ "@var{bar-command-2}")))) ++@end example ++ ++@noindent ++This will override any predefined rules for the same extensions. ++ ++@item dired-guess-shell-case-fold-search ++@vindex dired-guess-shell-case-fold-search ++Default: @code{t} ++ ++Non-@code{nil} means @code{dired-guess-shell-alist-default} and ++@code{dired-guess-shell-alist-user} are matched case-insensitively. ++ ++@item dired-guess-shell-gnutar ++@vindex dired-guess-shell-gnutar ++@cindex Passing GNU Tar its @samp{z} switch. ++Default: @code{nil} ++ ++If non-@code{nil}, this is the name of the GNU Tar executable (e.g., ++@samp{tar} or @samp{gnutar}). GNU Tar's @samp{z} switch is used for ++compressed tar files. ++If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is ++then used. ++ ++@item dired-guess-shell-gzip-quiet ++@vindex dired-guess-shell-gzip-quiet ++@cindex @code{gzip} ++Default: @code{t} ++ ++A non-@code{nil} value means that @samp{-q} is passed to @code{gzip} ++overriding a verbose option in the @env{GZIP} environment variable. ++ ++@item dired-guess-shell-znew-switches nil ++@vindex dired-guess-shell-znew-switches nil ++@cindex @code{znew} ++Default: @code{nil} ++ ++A string of switches passed to @code{znew}. An example is ++@samp{-K} which will make @code{znew} keep a @file{.Z} file when it is ++smaller than the @file{.gz} file. ++ ++@item dired-shell-command-history nil ++@vindex dired-shell-command-history nil ++ ++History list for commands that read dired-shell commands. ++@end table ++ ++@node Virtual Dired, Advanced Mark Commands, Shell Command Guessing, Top ++@comment node-name, next, previous, up ++@chapter Virtual Dired ++ ++@cindex Virtual Dired ++@cindex Perusing @code{ls} listings ++@cindex @code{ls} listings, how to peruse them in Dired ++Using @dfn{Virtual Dired} means putting a buffer with Dired-like ++contents in Dired mode. The files described by the buffer contents need ++not actually exist. This is useful if you want to peruse an @samp{ls -lR} ++output file, for example one you got from an FTP server. You can use ++all motion commands usually available in Dired. You can also use ++it to save a Dired buffer in a file and resume it in a later session. ++ ++@findex dired-virtual ++@kindex g ++@findex dired-virtual-revert ++Type @kbd{M-x dired-virtual} to put the current buffer into virtual ++Dired mode. You will be prompted for the top level directory of this ++buffer, with a default value guessed from the buffer contents. To ++convert the virtual to a real Dired buffer again, type @kbd{g} (which ++calls @code{dired-virtual-revert}) in the virtual Dired buffer and ++answer @samp{y}. You don't have to do this, though: you can relist ++single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory ++headerline, leaving the buffer in virtual Dired mode all the time. ++ ++@findex dired-virtual-mode ++@vindex auto-mode-alist ++The function @samp{dired-virtual-mode} is specially designed to turn on ++virtual Dired mode from the @code{auto-mode-alist}. To edit all ++@file{*.dired} files automatically in virtual Dired mode, put this into your ++@file{~/.emacs}: ++ ++@example ++(setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode) ++ auto-mode-alist)) ++@end example ++ ++@noindent ++The regexp is a bit more complicated than usual to exclude @file{.dired} ++local-variable files. ++ ++@node Advanced Mark Commands, Multiple Dired Directories, Virtual Dired, Top ++@comment node-name, next, previous, up ++@chapter Advanced Mark Commands ++ ++@table @kbd ++@item F ++@kindex F ++@cindex Visiting several files at once ++@cindex Simultaneous visiting of several files ++@findex dired-do-find-marked-files ++(@code{dired-do-find-marked-files}) Find all marked files at once displaying ++them simultaneously. If optional @var{noselect} is non-@code{nil} then just ++find the ++files but do not select. If you want to keep the Dired buffer displayed, type ++@kbd{C-x 2} first. If you want just the marked files displayed and nothing ++else, type @kbd{C-x 1} first. ++ ++The current window is split across all files marked, as evenly as possible. ++Remaining lines go to the bottom-most window. The number of files that can be ++displayed this way is restricted by the height of the current window and the ++variable @code{window-min-height}. ++@end table ++ ++@table @code ++@item dired-mark-extension ++@findex dired-mark-extension ++Mark all files with a certain extension for use in later commands. A @samp{.} ++is not automatically prepended to the string entered, you must type it ++explicitly. ++ ++When called from Lisp, @var{extension} may also be a list of extensions ++and an optional argument @var{marker-char} specifies the marker used. ++ ++@item dired-flag-extension ++@findex dired-flag-extension ++Flag all files with a certain extension for deletion. A @samp{.} is ++@emph{not} automatically prepended to the string entered. ++@end table ++ ++@ifnottex ++@menu ++* Advanced Cleaning Functions:: ++* Advanced Cleaning Variables:: ++* Special Marking Function:: ++@end menu ++@end ifnottex ++ ++@node Advanced Cleaning Functions, Advanced Cleaning Variables, , Advanced Mark Commands ++@comment node-name, next, previous, up ++ ++@section Advanced Cleaning Functions ++ ++@table @code ++@item dired-clean-patch ++@findex dired-clean-patch ++Flag dispensable files created by the @samp{patch} program for deletion. See ++variable @code{dired-patch-unclean-extensions}. ++ ++@item dired-clean-tex ++@findex dired-clean-tex ++Flag dispensable files created by @TeX{}, La@TeX{}, and @samp{texinfo} for ++deletion. See the following variables (@pxref{Advanced Cleaning Variables}): ++ ++@itemize @bullet ++@item ++@code{dired-tex-unclean-extensions} ++@item ++@code{dired-texinfo-unclean-extensions} ++@item ++@code{dired-latex-unclean-extensions} ++@item ++@code{dired-bibtex-unclean-extensions} ++@end itemize ++ ++@item dired-very-clean-tex ++@findex dired-very-clean-tex ++Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo}, ++and @file{*.dvi} files for deletion. ++@end table ++ ++@node Advanced Cleaning Variables, Special Marking Function, Advanced Cleaning Functions, Advanced Mark Commands ++@comment node-name, next, previous, up ++ ++@section Advanced Cleaning Variables ++ ++@noindent Variables used by the above cleaning commands (and in the default value for ++variable @code{dired-omit-extensions}, @pxref{Omitting Variables}) ++ ++@table @code ++@item dired-patch-unclean-extensions ++@vindex dired-patch-unclean-extensions ++Default: @code{(".rej" ".orig")} ++ ++List of extensions of dispensable files created by the @samp{patch} program. ++ ++@item dired-tex-unclean-extensions ++@vindex dired-tex-unclean-extensions ++Default: @code{(".toc" ".log" ".aux")} ++ ++List of extensions of dispensable files created by @TeX{}. ++ ++@item dired-texinfo-unclean-extensions ++@vindex dired-texinfo-unclean-extensions ++Default: @code{(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"} ++@code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")} ++ ++List of extensions of dispensable files created by @samp{texinfo}. ++ ++@item dired-latex-unclean-extensions ++@vindex dired-latex-unclean-extensions ++Default: @code{(".idx" ".lof" ".lot" ".glo")} ++ ++List of extensions of dispensable files created by La@TeX{}. ++ ++@item dired-bibtex-unclean-extensions ++@vindex dired-bibtex-unclean-extensions ++Default: @code{(".blg" ".bbl")} ++ ++List of extensions of dispensable files created by Bib@TeX{}. ++@end table ++ ++@node Special Marking Function, , Advanced Cleaning Variables, Advanced Mark Commands ++@comment node-name, next, previous, up ++ ++@section Special Marking Function ++ ++@table @kbd ++@item M-( ++@kindex M-( ++@findex dired-mark-sexp ++@cindex Lisp expression, marking files with in Dired ++@cindex Mark file by Lisp expression ++(@code{dired-mark-sexp}) Mark files for which @var{predicate} returns ++non-@code{nil}. With a prefix argument, unflag those files instead. ++ ++The @var{predicate} is a Lisp expression that can refer to the following ++symbols: ++@table @code ++@item inode ++[@i{integer}] the inode of the file (only for @samp{ls -i} output) ++@item s ++[@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or, ++with @samp{-k}, in KBytes) ++@item mode ++[@i{string}] file permission bits, e.g., @samp{-rw-r--r--} ++@item nlink ++[@i{integer}] number of links to file ++@item uid ++[@i{string}] owner ++@item gid ++[@i{string}] group (If the gid is not displayed by @samp{ls}, this ++will still be set (to the same as uid)) ++@item size ++[@i{integer}] file size in bytes ++@item time ++[@i{string}] the time that @samp{ls} displays, e.g., @samp{Feb 12 14:17} ++@item name ++[@i{string}] the name of the file ++@item sym ++[@i{string}] if file is a symbolic link, the linked-to name, else @code{""} ++@end table ++ ++@noindent ++For example, use ++@example ++(equal 0 size) ++@end example ++to mark all zero length files. ++ ++To find out all not yet compiled Emacs Lisp files in a directory, Dired ++all @file{.el} files in the lisp directory using the wildcard ++@samp{*.el}. Then use @kbd{M-(} with ++@example ++(not (file-exists-p (concat name "c"))) ++@end example ++to mark all @file{.el} files without a corresponding @file{.elc} file. ++ ++@end table ++ ++@node Multiple Dired Directories, Find File At Point, Advanced Mark Commands, Top ++@comment node-name, next, previous, up ++@chapter Multiple Dired Directories and Non-Dired Commands ++ ++@cindex Multiple Dired directories ++@cindex Working directory ++An Emacs buffer can have but one working directory, stored in the ++buffer-local variable @code{default-directory}. A Dired buffer may have ++several subdirectories inserted, but it still has only one working ++directory: that of the top-level Dired directory in that buffer. For ++some commands it is appropriate that they use the current Dired ++directory instead of @code{default-directory}, e.g., @code{find-file} and ++@code{compile}. ++ ++A general mechanism is provided for special handling of the working ++directory in special major modes: ++ ++@table @code ++@item default-directory-alist ++@vindex default-directory-alist ++Default: @code{((dired-mode . (dired-current-directory)))} ++ ++Alist of major modes and their notion of @code{default-directory}, as a ++Lisp expression to evaluate. A resulting value of @code{nil} is ignored ++in favor of @code{default-directory}. ++ ++@item dired-default-directory ++@findex dired-default-directory ++Use this function like you would use the variable ++@code{default-directory}, except that @code{dired-default-directory} ++also consults the variable @code{default-directory-alist}. ++@end table ++ ++@node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top ++@comment node-name, next, previous, up ++ ++@section Find File At Point ++@cindex Visiting a file mentioned in a buffer ++@cindex Finding a file at point ++ ++@file{dired-x} provides a method of visiting or editing a file mentioned in ++the buffer you are viewing (e.g., a mail buffer, a news article, a ++@file{README} file, etc.) or to test if that file exists. You can then modify ++this in the minibuffer after snatching the file name. ++ ++When installed @file{dired-x} will substitute @code{dired-x-find-file} for ++@code{find-file} (normally bound to @kbd{C-x C-f}) and ++@code{dired-x-find-file-other-window} for @code{find-file-other-window} ++(normally bound to @kbd{C-x 4 C-f}). ++ ++In order to use this feature, you will need to set ++@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook} ++(@pxref{Optional Installation File At Point}). ++ ++@table @code ++@item dired-x-find-file ++@findex dired-x-find-file ++@kindex C-x C-f ++ ++@code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound ++to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which ++case it will use the file name at point as a guess for the file to visit. ++ ++For example, if the buffer you were reading contained the words ++ ++@example ++Available via anonymous ftp in ++ ++ /roebling.poly.edu:/pub/lisp/crypt++.el.gz ++@end example ++ ++@noindent ++then you could move your cursor to the line containing the ftp address and ++type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument). The ++minibuffer would read ++ ++@example ++Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz ++@end example ++ ++@noindent ++with the point after the last @code{/}. If you hit @key{RET}, emacs will visit ++the file at that address. This also works with files on your own computer. ++ ++@item dired-x-find-file-other-window ++@findex dired-x-find-file-other-window ++@kindex C-x 4 C-f ++ ++@code{dired-x-find-file-other-window} behaves exactly like ++@code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a ++prefix argument is used. See @code{dired-x-find-file} for more information. ++ ++@item dired-x-hands-off-my-keys ++@vindex dired-x-hands-off-my-keys ++If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind ++@code{dired-x-find-file} over @code{find-file} on keyboard. Similarly, it ++should not bind @code{dired-x-find-file-other-window} over ++@code{find-file-other-window}. If you change this variable after ++@file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}. The ++default value of this variable is @code{t}; by default, the binding is not ++done. See @xref{Optional Installation File At Point}. ++ ++@item dired-x-bind-find-file ++@findex dired-x-bind-find-file ++A function, which can be called interactively or in your @file{~/.emacs} file, ++that uses the value of @code{dired-x-hands-off-my-keys} to determine if ++@code{dired-x-find-file} should be bound over @code{find-file} and ++@code{dired-x-find-file-other-window} bound over ++@code{find-file-other-window}. See @xref{Optional Installation File At Point}. ++@end table ++ ++@node Miscellaneous Commands, Bugs, Find File At Point, Top ++@comment node-name, next, previous, up ++@chapter Miscellaneous Commands ++ ++Miscellaneous features not fitting anywhere else: ++ ++@table @code ++@item dired-find-subdir ++@vindex dired-find-subdir ++Default: @code{nil} ++ ++If non-@code{nil}, Dired does not make a new buffer for a directory if it can ++be found (perhaps as subdirectory) in some existing Dired buffer. ++ ++If there are several Dired buffers for a directory, the most recently ++used is chosen. ++ ++Dired avoids switching to the current buffer, so that if you have a ++normal and a wildcard buffer for the same directory, @kbd{C-x d RET} ++will toggle between those two. ++@end table ++ ++@table @kbd ++@findex dired-goto-subdir ++@kindex M-G ++@item M-G ++(@code{dired-goto-subdir}) Go to the header line of an inserted directory. ++This command reads its argument, with completion derived from the names of the ++inserted subdirectories. ++@end table ++ ++@table @code ++@item dired-smart-shell-command ++@findex dired-smart-shell-command ++@findex shell-command ++@kindex M-! ++Like function @code{shell-command}, but in the current Dired directory. ++Bound to @kbd{M-!} in Dired buffers. ++ ++@item dired-jump ++@findex dired-jump ++@kindex C-x C-j ++@cindex Jumping to Dired listing containing file. ++Bound to @kbd{C-x C-j}. Jump back to Dired: If in a file, edit the current ++directory and move to file's line. If in Dired already, pop up a level and ++go to old directory's line. In case the proper Dired file line cannot be ++found, refresh the Dired buffer and try again. ++ ++@item dired-jump-other-window ++@findex dired-jump-other-window ++@kindex C-x 4 C-j ++Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window. ++ ++These functions can be autoloaded so they work even though @file{dired-x.el} ++has not been loaded yet (@pxref{Optional Installation Dired Jump}). ++ ++@vindex dired-bind-jump ++If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be ++bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to ++@kbd{C-x 4 C-j}. ++ ++@item dired-vm ++@cindex Reading mail. ++@kindex V ++@findex dired-vm ++Bound to @kbd{V} if @code{dired-bind-vm} is @code{t}. Run VM on this ++file (assumed to be a UNIX mail folder). ++ ++@vindex dired-vm-read-only-folders ++If you give this command a prefix argument, it will visit the folder ++read-only. This only works in VM 5, not VM 4. ++ ++If the variable @code{dired-vm-read-only-folders} is @code{t}, ++@code{dired-vm} will ++visit all folders read-only. If it is neither @code{nil} nor @code{t}, e.g., ++the symbol @code{if-file-read-only}, only files not writable by you are ++visited read-only. This is the recommended value if you run VM 5. ++ ++@vindex dired-bind-vm ++If the variable @code{dired-bind-vm} is @code{t}, @code{dired-vm} will be bound ++to @kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound. ++ ++@item dired-rmail ++@cindex Reading mail. ++@findex dired-rmail ++Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this ++file (assumed to be mail folder in Rmail format). ++ ++@item dired-info ++@kindex I ++@cindex Running info. ++@findex dired-info ++Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info ++format). ++ ++@vindex dired-bind-info ++If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will ++not be bound to @kbd{I}. ++ ++@item dired-man ++@cindex Running man. ++@kindex N ++@findex dired-man ++Bound to @kbd{N}. Run man on this file (assumed to be a file in @code{nroff} ++format). ++ ++@vindex dired-bind-man ++If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not ++be bound to @kbd{N}. ++ ++@item dired-do-relsymlink ++@cindex Relative symbolic links. ++@kindex Y ++@findex dired-do-relsymlink ++Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a ++directory, or make a relative symbolic link to the current file. This creates ++relative symbolic links like ++ ++@example ++ foo -> ../bar/foo ++@end example ++ ++@noindent ++not absolute ones like ++ ++@example ++ foo -> /ugly/path/that/may/change/any/day/bar/foo ++@end example ++ ++@item dired-do-relsymlink-regexp ++@kindex %Y ++@findex dired-do-relsymlink-regexp ++Bound to @kbd{%Y}. Relative symlink all marked files containing ++@var{regexp} to @var{newname}. See functions ++@code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more ++info. ++@end table ++ ++@node Bugs, GNU Free Documentation License, Miscellaneous Commands, Top ++@comment node-name, next, previous, up ++@chapter Bugs ++@cindex Bugs ++@findex dired-x-submit-report ++ ++@noindent ++If you encounter a bug in this package, wish to suggest an ++enhancement, or want to make a smart remark, then type ++ ++@example ++@kbd{M-x dired-x-submit-report} ++@end example ++ ++@noindent ++to set up an outgoing mail buffer, with the proper address to the ++@file{dired-x.el} maintainer automatically inserted in the @samp{To:@:} field. ++This command also inserts information that the Dired X maintainer can use to ++recreate your exact setup, making it easier to verify your bug or social ++maladjustment. ++ ++Lawrence R. Dodd ++@c ++ ++@node GNU Free Documentation License, Concept Index, Bugs, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Concept Index, Command Index, GNU Free Documentation License, Top ++@comment node-name, next, previous, up ++@unnumbered Concept Index ++@printindex cp ++ ++@node Command Index, Key Index, Concept Index, Top ++@comment node-name, next, previous, up ++@unnumbered Function Index ++@printindex fn ++ ++@node Key Index, Variable Index, Command Index, Top ++@comment node-name, next, previous, up ++@unnumbered Key Index ++@printindex ky ++ ++@node Variable Index, , Key Index, Top ++@comment node-name, next, previous, up ++@unnumbered Variable Index ++@printindex vr ++ ++@bye ++ ++@ignore ++ arch-tag: 201727aa-9318-4c74-a0d7-4f51c550c4de ++@end ignore +diff --git a/doc/misc/doclicense.texi b/doc/misc/doclicense.texi +new file mode 100644 +index 0000000..d3ae2f9 +--- /dev/null ++++ b/doc/misc/doclicense.texi +@@ -0,0 +1,511 @@ ++@c -*-texinfo-*- ++@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, 2009 Free Software Foundation, Inc. ++@uref{http://fsf.org/} ++ ++Everyone is permitted to copy and distribute verbatim copies ++of this license document, but changing it is not allowed. ++@end display ++ ++@enumerate 0 ++@item ++PREAMBLE ++ ++The purpose of this License is to make a manual, textbook, or other ++functional and useful document @dfn{free} in the sense of freedom: to ++assure everyone the effective freedom to copy and redistribute it, ++with or without modifying it, either commercially or noncommercially. ++Secondarily, this License preserves for the author and publisher a way ++to get credit for their work, while not being considered responsible ++for modifications made by others. ++ ++This License is a kind of ``copyleft'', which means that derivative ++works of the document must themselves be free in the same sense. It ++complements the GNU General Public License, which is a copyleft ++license designed for free software. ++ ++We have designed this License in order to use it for manuals for free ++software, because free software needs free documentation: a free ++program should come with manuals providing the same freedoms that the ++software does. But this License is not limited to software manuals; ++it can be used for any textual work, regardless of subject matter or ++whether it is published as a printed book. We recommend this License ++principally for works whose purpose is instruction or reference. ++ ++@item ++APPLICABILITY AND DEFINITIONS ++ ++This License applies to any manual or other work, in any medium, that ++contains a notice placed by the copyright holder saying it can be ++distributed under the terms of this License. Such a notice grants a ++world-wide, royalty-free license, unlimited in duration, to use that ++work under the conditions stated herein. The ``Document'', below, ++refers to any such manual or work. Any member of the public is a ++licensee, and is addressed as ``you''. You accept the license if you ++copy, modify or distribute the work in a way requiring permission ++under copyright law. ++ ++A ``Modified Version'' of the Document means any work containing the ++Document or a portion of it, either copied verbatim, or with ++modifications and/or translated into another language. ++ ++A ``Secondary Section'' is a named appendix or a front-matter section ++of the Document that deals exclusively with the relationship of the ++publishers or authors of the Document to the Document's overall ++subject (or to related matters) and contains nothing that could fall ++directly within that overall subject. (Thus, if the Document is in ++part a textbook of mathematics, a Secondary Section may not explain ++any mathematics.) The relationship could be a matter of historical ++connection with the subject or with related matters, or of legal, ++commercial, philosophical, ethical or political position regarding ++them. ++ ++The ``Invariant Sections'' are certain Secondary Sections whose titles ++are designated, as being those of Invariant Sections, in the notice ++that says that the Document is released under this License. If a ++section does not fit the above definition of Secondary then it is not ++allowed to be designated as Invariant. The Document may contain zero ++Invariant Sections. If the Document does not identify any Invariant ++Sections then there are none. ++ ++The ``Cover Texts'' are certain short passages of text that are listed, ++as Front-Cover Texts or Back-Cover Texts, in the notice that says that ++the Document is released under this License. A Front-Cover Text may ++be at most 5 words, and a Back-Cover Text may be at most 25 words. ++ ++A ``Transparent'' copy of the Document means a machine-readable copy, ++represented in a format whose specification is available to the ++general public, that is suitable for revising the document ++straightforwardly with generic text editors or (for images composed of ++pixels) generic paint programs or (for drawings) some widely available ++drawing editor, and that is suitable for input to text formatters or ++for automatic translation to a variety of formats suitable for input ++to text formatters. A copy made in an otherwise Transparent file ++format whose markup, or absence of markup, has been arranged to thwart ++or discourage subsequent modification by readers is not Transparent. ++An image format is not Transparent if used for any substantial amount ++of text. A copy that is not ``Transparent'' is called ``Opaque''. ++ ++Examples of suitable formats for Transparent copies include plain ++@sc{ascii} without markup, Texinfo input format, La@TeX{} input ++format, @acronym{SGML} or @acronym{XML} using a publicly available ++@acronym{DTD}, and standard-conforming simple @acronym{HTML}, ++PostScript or @acronym{PDF} designed for human modification. Examples ++of transparent image formats include @acronym{PNG}, @acronym{XCF} and ++@acronym{JPG}. Opaque formats include proprietary formats that can be ++read and edited only by proprietary word processors, @acronym{SGML} or ++@acronym{XML} for which the @acronym{DTD} and/or processing tools are ++not generally available, and the machine-generated @acronym{HTML}, ++PostScript or @acronym{PDF} produced by some word processors for ++output purposes only. ++ ++The ``Title Page'' means, for a printed book, the title page itself, ++plus such following pages as are needed to hold, legibly, the material ++this License requires to appear in the title page. For works in ++formats which do not have any title page as such, ``Title Page'' means ++the text near the most prominent appearance of the work's title, ++preceding the beginning of the body of the text. ++ ++The ``publisher'' means any person or entity that distributes copies ++of the Document to the public. ++ ++A section ``Entitled XYZ'' means a named subunit of the Document whose ++title either is precisely XYZ or contains XYZ in parentheses following ++text that translates XYZ in another language. (Here XYZ stands for a ++specific section name mentioned below, such as ``Acknowledgements'', ++``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' ++of such a section when you modify the Document means that it remains a ++section ``Entitled XYZ'' according to this definition. ++ ++The Document may include Warranty Disclaimers next to the notice which ++states that this License applies to the Document. These Warranty ++Disclaimers are considered to be included by reference in this ++License, but only as regards disclaiming warranties: any other ++implication that these Warranty Disclaimers may have is void and has ++no effect on the meaning of this License. ++ ++@item ++VERBATIM COPYING ++ ++You may copy and distribute the Document in any medium, either ++commercially or noncommercially, provided that this License, the ++copyright notices, and the license notice saying this License applies ++to the Document are reproduced in all copies, and that you add no other ++conditions whatsoever to those of this License. You may not use ++technical measures to obstruct or control the reading or further ++copying of the copies you make or distribute. However, you may accept ++compensation in exchange for copies. If you distribute a large enough ++number of copies you must also follow the conditions in section 3. ++ ++You may also lend copies, under the same conditions stated above, and ++you may publicly display copies. ++ ++@item ++COPYING IN QUANTITY ++ ++If you publish printed copies (or copies in media that commonly have ++printed covers) of the Document, numbering more than 100, and the ++Document's license notice requires Cover Texts, you must enclose the ++copies in covers that carry, clearly and legibly, all these Cover ++Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on ++the back cover. Both covers must also clearly and legibly identify ++you as the publisher of these copies. The front cover must present ++the full title with all words of the title equally prominent and ++visible. You may add other material on the covers in addition. ++Copying with changes limited to the covers, as long as they preserve ++the title of the Document and satisfy these conditions, can be treated ++as verbatim copying in other respects. ++ ++If the required texts for either cover are too voluminous to fit ++legibly, you should put the first ones listed (as many as fit ++reasonably) on the actual cover, and continue the rest onto adjacent ++pages. ++ ++If you publish or distribute Opaque copies of the Document numbering ++more than 100, you must either include a machine-readable Transparent ++copy along with each Opaque copy, or state in or with each Opaque copy ++a computer-network location from which the general network-using ++public has access to download using public-standard network protocols ++a complete Transparent copy of the Document, free of added material. ++If you use the latter option, you must take reasonably prudent steps, ++when you begin distribution of Opaque copies in quantity, to ensure ++that this Transparent copy will remain thus accessible at the stated ++location until at least one year after the last time you distribute an ++Opaque copy (directly or through your agents or retailers) of that ++edition to the public. ++ ++It is requested, but not required, that you contact the authors of the ++Document well before redistributing any large number of copies, to give ++them a chance to provide you with an updated version of the Document. ++ ++@item ++MODIFICATIONS ++ ++You may copy and distribute a Modified Version of the Document under ++the conditions of sections 2 and 3 above, provided that you release ++the Modified Version under precisely this License, with the Modified ++Version filling the role of the Document, thus licensing distribution ++and modification of the Modified Version to whoever possesses a copy ++of it. In addition, you must do these things in the Modified Version: ++ ++@enumerate A ++@item ++Use in the Title Page (and on the covers, if any) a title distinct ++from that of the Document, and from those of previous versions ++(which should, if there were any, be listed in the History section ++of the Document). You may use the same title as a previous version ++if the original publisher of that version gives permission. ++ ++@item ++List on the Title Page, as authors, one or more persons or entities ++responsible for authorship of the modifications in the Modified ++Version, together with at least five of the principal authors of the ++Document (all of its principal authors, if it has fewer than five), ++unless they release you from this requirement. ++ ++@item ++State on the Title page the name of the publisher of the ++Modified Version, as the publisher. ++ ++@item ++Preserve all the copyright notices of the Document. ++ ++@item ++Add an appropriate copyright notice for your modifications ++adjacent to the other copyright notices. ++ ++@item ++Include, immediately after the copyright notices, a license notice ++giving the public permission to use the Modified Version under the ++terms of this License, in the form shown in the Addendum below. ++ ++@item ++Preserve in that license notice the full lists of Invariant Sections ++and required Cover Texts given in the Document's license notice. ++ ++@item ++Include an unaltered copy of this License. ++ ++@item ++Preserve the section Entitled ``History'', Preserve its Title, and add ++to it an item stating at least the title, year, new authors, and ++publisher of the Modified Version as given on the Title Page. If ++there is no section Entitled ``History'' in the Document, create one ++stating the title, year, authors, and publisher of the Document as ++given on its Title Page, then add an item describing the Modified ++Version as stated in the previous sentence. ++ ++@item ++Preserve the network location, if any, given in the Document for ++public access to a Transparent copy of the Document, and likewise ++the network locations given in the Document for previous versions ++it was based on. These may be placed in the ``History'' section. ++You may omit a network location for a work that was published at ++least four years before the Document itself, or if the original ++publisher of the version it refers to gives permission. ++ ++@item ++For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve ++the Title of the section, and preserve in the section all the ++substance and tone of each of the contributor acknowledgements and/or ++dedications given therein. ++ ++@item ++Preserve all the Invariant Sections of the Document, ++unaltered in their text and in their titles. Section numbers ++or the equivalent are not considered part of the section titles. ++ ++@item ++Delete any section Entitled ``Endorsements''. Such a section ++may not be included in the Modified Version. ++ ++@item ++Do not retitle any existing section to be Entitled ``Endorsements'' or ++to conflict in title with any Invariant Section. ++ ++@item ++Preserve any Warranty Disclaimers. ++@end enumerate ++ ++If the Modified Version includes new front-matter sections or ++appendices that qualify as Secondary Sections and contain no material ++copied from the Document, you may at your option designate some or all ++of these sections as invariant. To do this, add their titles to the ++list of Invariant Sections in the Modified Version's license notice. ++These titles must be distinct from any other section titles. ++ ++You may add a section Entitled ``Endorsements'', provided it contains ++nothing but endorsements of your Modified Version by various ++parties---for example, statements of peer review or that the text has ++been approved by an organization as the authoritative definition of a ++standard. ++ ++You may add a passage of up to five words as a Front-Cover Text, and a ++passage of up to 25 words as a Back-Cover Text, to the end of the list ++of Cover Texts in the Modified Version. Only one passage of ++Front-Cover Text and one of Back-Cover Text may be added by (or ++through arrangements made by) any one entity. If the Document already ++includes a cover text for the same cover, previously added by you or ++by arrangement made by the same entity you are acting on behalf of, ++you may not add another; but you may replace the old one, on explicit ++permission from the previous publisher that added the old one. ++ ++The author(s) and publisher(s) of the Document do not by this License ++give permission to use their names for publicity for or to assert or ++imply endorsement of any Modified Version. ++ ++@item ++COMBINING DOCUMENTS ++ ++You may combine the Document with other documents released under this ++License, under the terms defined in section 4 above for modified ++versions, provided that you include in the combination all of the ++Invariant Sections of all of the original documents, unmodified, and ++list them all as Invariant Sections of your combined work in its ++license notice, and that you preserve all their Warranty Disclaimers. ++ ++The combined work need only contain one copy of this License, and ++multiple identical Invariant Sections may be replaced with a single ++copy. If there are multiple Invariant Sections with the same name but ++different contents, make the title of each such section unique by ++adding at the end of it, in parentheses, the name of the original ++author or publisher of that section if known, or else a unique number. ++Make the same adjustment to the section titles in the list of ++Invariant Sections in the license notice of the combined work. ++ ++In the combination, you must combine any sections Entitled ``History'' ++in the various original documents, forming one section Entitled ++``History''; likewise combine any sections Entitled ``Acknowledgements'', ++and any sections Entitled ``Dedications''. You must delete all ++sections Entitled ``Endorsements.'' ++ ++@item ++COLLECTIONS OF DOCUMENTS ++ ++You may make a collection consisting of the Document and other documents ++released under this License, and replace the individual copies of this ++License in the various documents with a single copy that is included in ++the collection, provided that you follow the rules of this License for ++verbatim copying of each of the documents in all other respects. ++ ++You may extract a single document from such a collection, and distribute ++it individually under this License, provided you insert a copy of this ++License into the extracted document, and follow this License in all ++other respects regarding verbatim copying of that document. ++ ++@item ++AGGREGATION WITH INDEPENDENT WORKS ++ ++A compilation of the Document or its derivatives with other separate ++and independent documents or works, in or on a volume of a storage or ++distribution medium, is called an ``aggregate'' if the copyright ++resulting from the compilation is not used to limit the legal rights ++of the compilation's users beyond what the individual works permit. ++When the Document is included in an aggregate, this License does not ++apply to the other works in the aggregate which are not themselves ++derivative works of the Document. ++ ++If the Cover Text requirement of section 3 is applicable to these ++copies of the Document, then if the Document is less than one half of ++the entire aggregate, the Document's Cover Texts may be placed on ++covers that bracket the Document within the aggregate, or the ++electronic equivalent of covers if the Document is in electronic form. ++Otherwise they must appear on printed covers that bracket the whole ++aggregate. ++ ++@item ++TRANSLATION ++ ++Translation is considered a kind of modification, so you may ++distribute translations of the Document under the terms of section 4. ++Replacing Invariant Sections with translations requires special ++permission from their copyright holders, but you may include ++translations of some or all Invariant Sections in addition to the ++original versions of these Invariant Sections. You may include a ++translation of this License, and all the license notices in the ++Document, and any Warranty Disclaimers, provided that you also include ++the original English version of this License and the original versions ++of those notices and disclaimers. In case of a disagreement between ++the translation and the original version of this License or a notice ++or disclaimer, the original version will prevail. ++ ++If a section in the Document is Entitled ``Acknowledgements'', ++``Dedications'', or ``History'', the requirement (section 4) to Preserve ++its Title (section 1) will typically require changing the actual ++title. ++ ++@item ++TERMINATION ++ ++You may not copy, modify, sublicense, or distribute the Document ++except as expressly provided under this License. Any attempt ++otherwise to copy, modify, sublicense, or distribute it is void, and ++will automatically terminate your rights under this License. ++ ++However, if you cease all violation of this License, then your license ++from a particular copyright holder is reinstated (a) provisionally, ++unless and until the copyright holder explicitly and finally ++terminates your license, and (b) permanently, if the copyright holder ++fails to notify you of the violation by some reasonable means prior to ++60 days after the cessation. ++ ++Moreover, your license from a particular copyright holder is ++reinstated permanently if the copyright holder notifies you of the ++violation by some reasonable means, this is the first time you have ++received notice of violation of this License (for any work) from that ++copyright holder, and you cure the violation prior to 30 days after ++your receipt of the notice. ++ ++Termination of your rights under this section does not terminate the ++licenses of parties who have received copies or rights from you under ++this License. If your rights have been terminated and not permanently ++reinstated, receipt of a copy of some or all of the same material does ++not give you any rights to use it. ++ ++@item ++FUTURE REVISIONS OF THIS LICENSE ++ ++The Free Software Foundation may publish new, revised versions ++of the GNU Free Documentation License from time to time. Such new ++versions will be similar in spirit to the present version, but may ++differ in detail to address new problems or concerns. See ++@uref{http://www.gnu.org/copyleft/}. ++ ++Each version of the License is given a distinguishing version number. ++If the Document specifies that a particular numbered version of this ++License ``or any later version'' applies to it, you have the option of ++following the terms and conditions either of that specified version or ++of any later version that has been published (not as a draft) by the ++Free Software Foundation. If the Document does not specify a version ++number of this License, you may choose any version ever published (not ++as a draft) by the Free Software Foundation. If the Document ++specifies that a proxy can decide which future versions of this ++License can be used, that proxy's public statement of acceptance of a ++version permanently authorizes you to choose that version for the ++Document. ++ ++@item ++RELICENSING ++ ++``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any ++World Wide Web server that publishes copyrightable works and also ++provides prominent facilities for anybody to edit those works. A ++public wiki that anybody can edit is an example of such a server. A ++``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the ++site means any set of copyrightable works thus published on the MMC ++site. ++ ++``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 ++license published by Creative Commons Corporation, a not-for-profit ++corporation with a principal place of business in San Francisco, ++California, as well as future copyleft versions of that license ++published by that same organization. ++ ++``Incorporate'' means to publish or republish a Document, in whole or ++in part, as part of another Document. ++ ++An MMC is ``eligible for relicensing'' if it is licensed under this ++License, and if all works that were first published under this License ++somewhere other than this MMC, and subsequently incorporated in whole ++or in part into the MMC, (1) had no cover texts or invariant sections, ++and (2) were thus incorporated prior to November 1, 2008. ++ ++The operator of an MMC Site may republish an MMC contained in the site ++under CC-BY-SA on the same site at any time before August 1, 2009, ++provided the MMC is eligible for relicensing. ++ ++@end enumerate ++ ++@page ++@heading ADDENDUM: How to use this License for your documents ++ ++To use this License in a document you have written, include a copy of ++the License in the document and put the following copyright and ++license notices just after the title page: ++ ++@smallexample ++@group ++ Copyright (C) @var{year} @var{your name}. ++ Permission is granted to copy, distribute and/or modify this document ++ under the terms of the GNU Free Documentation License, Version 1.3 ++ or any later version published by the Free Software Foundation; ++ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover ++ Texts. A copy of the license is included in the section entitled ``GNU ++ Free Documentation License''. ++@end group ++@end smallexample ++ ++If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, ++replace the ``with@dots{}Texts.'' line with this: ++ ++@smallexample ++@group ++ with the Invariant Sections being @var{list their titles}, with ++ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts ++ being @var{list}. ++@end group ++@end smallexample ++ ++If you have Invariant Sections without Cover Texts, or some other ++combination of the three, merge those two alternatives to suit the ++situation. ++ ++If your document contains nontrivial examples of program code, we ++recommend releasing these examples in parallel under your choice of ++free software license, such as the GNU General Public License, ++to permit their use in free software. ++ ++ ++@c Local Variables: ++@c ispell-local-pdict: "ispell-dict" ++@c End: ++ ++@ignore ++ arch-tag: c1679162-1d8a-4f02-bc52-2e71765f0165 ++@end ignore +diff --git a/doc/misc/ebrowse.texi b/doc/misc/ebrowse.texi +new file mode 100644 +index 0000000..9642c3c +--- /dev/null ++++ b/doc/misc/ebrowse.texi +@@ -0,0 +1,1459 @@ ++\input texinfo @c -*-texinfo-*- ++ ++@comment %**start of header ++@setfilename ../../info/ebrowse ++@settitle A Class Browser for C++ ++@setchapternewpage odd ++@syncodeindex fn cp ++@comment %**end of header ++ ++@copying ++This file documents Ebrowse, a C++ class browser for GNU Emacs. ++ ++Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, ++2008, 2009 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 Emacs ++@direntry ++* Ebrowse: (ebrowse). A C++ class browser for Emacs. ++@end direntry ++ ++@titlepage ++@title Ebrowse User's Manual ++@sp 4 ++@subtitle Ebrowse/Emacs ++@sp 5 ++@author Gerd Moellmann ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top, Overview, (dir), (dir) ++ ++You can browse C++ class hierarchies from within Emacs by using ++Ebrowse. ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview:: What is it and how does it work? ++* Generating browser files:: How to process C++ source files ++* Loading a Tree:: How to start browsing ++* Tree Buffers:: Traversing class hierarchies ++* Member Buffers:: Looking at member information ++* Tags-like Functions:: Finding members from source files ++* GNU Free Documentation License:: The license for this documentation. ++* Concept Index:: An entry for each concept defined ++@end menu ++ ++ ++ ++ ++@node Overview, Generating browser files, Top, Top ++@chapter Introduction ++ ++When working in software projects using C++, I frequently missed ++software support for two things: ++ ++@itemize @bullet ++@item ++When you get a new class library, or you have to work on source code you ++haven't written yourself (or written sufficiently long ago), you need a ++tool to let you navigate class hierarchies and investigate ++features of the software. Without such a tool you often end up ++@command{grep}ing through dozens or even hundreds of files. ++ ++@item ++Once you are productive, it would be nice to have a tool that knows your ++sources and can help you while you are editing source code. Imagine to ++be able to jump to the definition of an identifier while you are ++editing, or something that can complete long identifier names because it ++knows what identifiers are defined in your program@dots{}. ++@end itemize ++ ++The design of Ebrowse reflects these two needs. ++ ++How does it work? ++ ++@cindex parser for C++ sources ++A fast parser written in C is used to process C++ source files. ++The parser generates a data base containing information about classes, ++members, global functions, defines, types etc.@: found in the sources. ++ ++The second part of Ebrowse is a Lisp program. This program reads ++the data base generated by the parser. It displays its contents in ++various forms and allows you to perform operations on it, or do ++something with the help of the knowledge contained in the data base. ++ ++@cindex major modes, of Ebrowse buffers ++@dfn{Navigational} use of Ebrowse is centered around two ++types of buffers which define their own major modes: ++ ++@cindex tree buffer ++@dfn{Tree buffers} are used to view class hierarchies in tree form. ++They allow you to quickly find classes, find or view class declarations, ++perform operations like query replace on sets of your source files, and ++finally tree buffers are used to produce the second buffer form---member ++buffers. @xref{Tree Buffers}. ++ ++@cindex member buffer ++Members are displayed in @dfn{member buffers}. Ebrowse ++distinguishes between six different types of members; each type is ++displayed as a member list of its own: ++ ++@itemize @bullet ++@item ++Instance member variables; ++ ++@item ++Instance member functions; ++ ++@item ++Static member variables; ++ ++@item ++Static member functions; ++ ++@item ++Friends/Defines. The list of defines is contained in the friends ++list of the pseudo-class @samp{*Globals*}; ++ ++@item ++Types (@code{enum}s, and @code{typedef}s defined with class ++scope).@refill ++@end itemize ++ ++You can switch member buffers from one list to another, or to another ++class. You can include inherited members in the display, you can set ++filters that remove categories of members from the display, and most ++importantly you can find or view member declarations and definitions ++with a keystroke. @xref{Member Buffers}. ++ ++These two buffer types and the commands they provide support the ++navigational use of the browser. The second form resembles Emacs' Tags ++package for C and other procedural languages. Ebrowse's commands of ++this type are not confined to special buffers; they are most often used ++while you are editing your source code. ++ ++To list just a subset of what you can use the Tags part of Ebrowse for: ++ ++@itemize @bullet ++@item ++Jump to the definition or declaration of an identifier in your source ++code, with an electric position stack that lets you easily navigate ++back and forth. ++ ++@item ++Complete identifiers in your source with a completion list containing ++identifiers from your source code only. ++ ++@item ++Perform search and query replace operations over some or all of your ++source files. ++ ++@item ++Show all identifiers matching a regular expression---and jump to one of ++them, if you like. ++@end itemize ++ ++ ++ ++ ++@node Generating browser files, Loading a Tree, Overview, Top ++@comment node-name, next, previous, up ++@chapter Processing Source Files ++ ++@cindex @command{ebrowse}, the program ++@cindex class data base creation ++Before you can start browsing a class hierarchy, you must run the parser ++@command{ebrowse} on your source files in order to generate a Lisp data ++base describing your program. ++ ++@cindex command line for @command{ebrowse} ++The operation of @command{ebrowse} can be tailored with command line ++options. Under normal circumstances it suffices to let the parser use ++its default settings. If you want to do that, call it with a command ++line like: ++ ++@example ++ebrowse *.h *.cc ++@end example ++ ++@noindent ++or, if your shell doesn't allow all the file names to be specified on ++the command line, ++ ++@example ++ebrowse --files=@var{file} ++@end example ++ ++@noindent ++where @var{file} contains the names of the files to be parsed, one ++per line. ++ ++@findex --help ++When invoked with option @samp{--help}, @command{ebrowse} prints a list of ++available command line options.@refill ++ ++@menu ++* Input files:: Specifying which files to parse ++* Output file:: Changing the output file name ++* Structs and unions:: Omitting @code{struct}s and @code{union}s ++* Matching:: Setting regular expression lengths ++* Verbosity:: Getting feedback for lengthy operations ++@end menu ++ ++ ++ ++ ++@comment name, next, prev, up ++@node Input files, Output file, Generating browser files, Generating browser files ++@section Specifying Input Files ++ ++@table @samp ++@cindex input files, for @command{ebrowse} ++@item file ++Each file name on the command line tells @command{ebrowse} to parse ++that file. ++ ++@cindex response files ++@findex --files ++@item --files=@var{file} ++This command line switch specifies that @var{file} contains a list of ++file names to parse. Each line in @var{file} must contain one file ++name. More than one option of this kind is allowed. You might, for ++instance, want to use one file for header files, and another for source ++files. ++ ++@cindex standard input, specifying input files ++@item standard input ++When @command{ebrowse} finds no file names on the command line, and no ++@samp{--file} option is specified, it reads file names from standard ++input. This is sometimes convenient when @command{ebrowse} is used as part ++of a command pipe. ++ ++@findex --search-path ++@item --search-path=@var{paths} ++This option lets you specify search paths for your input files. ++@var{paths} is a list of directory names, separated from each other by a ++either a colon or a semicolon, depending on the operating system. ++@end table ++ ++@cindex header files ++@cindex friend functions ++It is generally a good idea to specify input files so that header files ++are parsed before source files. This facilitates the parser's work of ++properly identifying friend functions of a class. ++ ++ ++ ++@comment name, next, prev, up ++@node Output file, Structs and unions, Input files, Generating browser files ++@section Changing the Output File Name ++ ++@table @samp ++@cindex output file name ++@findex --output-file ++@cindex @file{BROWSE} file ++@item --output-file=@var{file} ++This option instructs @command{ebrowse} to generate a Lisp data base with ++name @var{file}. By default, the data base is named @file{BROWSE}, and ++is written in the directory in which @command{ebrowse} is invoked. ++ ++If you regularly use data base names different from the default, you ++might want to add this to your init file: ++ ++@lisp ++(add-to-list 'auto-mode-alist '(@var{NAME} . ebrowse-tree-mode)) ++@end lisp ++ ++@noindent ++where @var{NAME} is the Lisp data base name you are using. ++ ++@findex --append ++@cindex appending output to class data base ++@item --append ++By default, each run of @command{ebrowse} erases the old contents of the ++output file when writing to it. You can instruct @command{ebrowse} to ++append its output to an existing file produced by @command{ebrowse} ++with this command line option. ++@end table ++ ++ ++ ++ ++@comment name, next, prev, up ++@node Structs and unions, Matching, Output file, Generating browser files ++@section Structs and Unions ++@cindex structs ++@cindex unions ++ ++@table @samp ++@findex --no-structs-or-unions ++@item --no-structs-or-unions ++This switch suppresses all classes in the data base declared as ++@code{struct} or @code{union} in the output. ++ ++This is mainly useful when you are converting an existing ++C program to C++, and do not want to see the old C structs in a class ++tree. ++@end table ++ ++ ++ ++ ++@comment name, next, prev, up ++@node Matching, Verbosity, Structs and unions, Generating browser files ++@section Regular Expressions ++ ++@cindex regular expressions, recording ++The parser @command{ebrowse} normally writes regular expressions to its ++output file that help the Lisp part of Ebrowse to find functions, ++variables etc.@: in their source files. ++ ++You can instruct @command{ebrowse} to omit these regular expressions by ++calling it with the command line switch @samp{--no-regexps}. ++ ++When you do this, the Lisp part of Ebrowse tries to guess, from member ++or class names, suitable regular expressions to locate that class or ++member in source files. This works fine in most cases, but the ++automatic generation of regular expressions can be too weak if unusual ++coding styles are used. ++ ++@table @samp ++@findex --no-regexps ++@item --no-regexps ++This option turns off regular expression recording. ++ ++@findex --min-regexp-length ++@cindex minimum regexp length for recording ++@item --min-regexp-length=@var{n} ++The number @var{n} following this option specifies the minimum length of ++the regular expressions recorded to match class and member declarations ++and definitions. The default value is set at compilation time of ++@command{ebrowse}. ++ ++The smaller the minimum length, the higher the probability that ++Ebrowse will find a wrong match. The larger the value, the ++larger the output file and therefore the memory consumption once the ++file is read from Emacs. ++ ++@findex --max-regexp-length ++@cindex maximum regexp length for recording ++@item --max-regexp-length=@var{n} ++The number following this option specifies the maximum length of the ++regular expressions used to match class and member declarations and ++definitions. The default value is set at compilation time of ++@command{ebrowse}. ++ ++The larger the maximum length, the higher the probability that the ++browser will find a correct match, but the larger the value the larger ++the output file and therefore the memory consumption once the data is ++read. As a second effect, the larger the regular expression, the higher ++the probability that it will no longer match after editing the file. ++@end table ++ ++ ++ ++ ++@node Verbosity, , Matching, Generating browser files ++@comment node-name, next, previous, up ++@section Verbose Mode ++@cindex verbose operation ++ ++@table @samp ++@findex --verbose ++@item --verbose ++When this option is specified on the command line, @command{ebrowse} prints ++a period for each file parsed, and it displays a @samp{+} for each ++class written to the output file. ++ ++@findex --very-verbose ++@item --very-verbose ++This option makes @command{ebrowse} print out the names of the files and ++the names of the classes seen. ++@end table ++ ++ ++ ++ ++@node Loading a Tree, Tree Buffers, Generating browser files, Top ++@comment node-name, next, previous, up ++@chapter Starting to Browse ++@cindex loading ++@cindex browsing ++ ++You start browsing a class hierarchy parsed by @command{ebrowse} by just ++finding the @file{BROWSE} file with @kbd{C-x C-f}. ++ ++An example of a tree buffer display is shown below. ++ ++@example ++| Collection ++| IndexedCollection ++| Array ++| FixedArray ++| Set ++| Dictionary ++@end example ++ ++@cindex mouse highlight in tree buffers ++When you run Emacs on a display which supports colors and the mouse, you ++will notice that certain areas in the tree buffer are highlighted ++when you move the mouse over them. This highlight marks mouse-sensitive ++regions in the buffer. Please notice the help strings in the echo area ++when the mouse moves over a sensitive region. ++ ++@cindex context menu ++A click with @kbd{Mouse-3} on a mouse-sensitive region opens a context ++menu. In addition to this, each buffer also has a buffer-specific menu ++that is opened with a click with @kbd{Mouse-3} somewhere in the buffer ++where no highlight is displayed. ++ ++ ++ ++@comment **************************************************************** ++@comment *** ++@comment *** TREE BUFFERS ++@comment *** ++@comment **************************************************************** ++ ++@node Tree Buffers, Member Buffers, Loading a Tree, Top ++@comment node-name, next, previous, up ++@chapter Tree Buffers ++@cindex tree buffer mode ++@cindex class trees ++ ++Class trees are displayed in @dfn{tree buffers} which install their own ++major mode. Most Emacs keys work in tree buffers in the usual way, ++e.g.@: you can move around in the buffer with the usual @kbd{C-f}, ++@kbd{C-v} etc., or you can search with @kbd{C-s}. ++ ++Tree-specific commands are bound to simple keystrokes, similar to ++@code{Gnus}. You can take a look at the key bindings by entering ++@kbd{?} which calls @code{M-x describe-mode} in both tree and member ++buffers. ++ ++@menu ++* Source Display:: Viewing and finding a class declaration ++* Member Display:: Showing members, switching to member buffers ++* Go to Class:: Finding a class ++* Quitting:: Discarding and burying the tree buffer ++* File Name Display:: Showing file names in the tree ++* Expanding and Collapsing:: Expanding and collapsing branches ++* Tree Indentation:: Changing the tree indentation ++* Killing Classes:: Removing class from the tree ++* Saving a Tree:: Saving a modified tree ++* Statistics:: Displaying class tree statistics ++* Marking Classes:: Marking and unmarking classes ++@end menu ++ ++ ++ ++@node Source Display, Member Display, Tree Buffers, Tree Buffers ++@comment node-name, next, previous, up ++@section Viewing and Finding Class Declarations ++@cindex viewing, class ++@cindex finding a class ++@cindex class declaration ++ ++You can view or find a class declaration when the cursor is on a class ++name. ++ ++@table @kbd ++@item SPC ++This command views the class declaration if the database ++contains informations about it. If you don't parse the entire source ++you are working on, some classes will only be known to exist but the ++location of their declarations and definitions will not be known.@refill ++ ++@item RET ++Works like @kbd{SPC}, except that it finds the class ++declaration rather than viewing it, so that it is ready for ++editing.@refill ++@end table ++ ++The same functionality is available from the menu opened with ++@kbd{Mouse-3} on the class name. ++ ++ ++ ++ ++@node Member Display, Go to Class, Source Display, Tree Buffers ++@comment node-name, next, previous, up ++@section Displaying Members ++@cindex @samp{*Members*} buffer ++@cindex @samp{*Globals*} ++@cindex freezing a member buffer ++@cindex member lists, in tree buffers ++ ++Ebrowse distinguishes six different kinds of members, each of ++which is displayed as a separate @dfn{member list}: instance variables, ++instance functions, static variables, static functions, friend ++functions, and types. ++ ++Each of these lists can be displayed in a member buffer with a command ++starting with @kbd{L} when the cursor is on a class name. By default, ++there is only one member buffer named @dfn{*Members*} that is reused ++each time you display a member list---this has proven to be more ++practical than to clutter up the buffer list with dozens of member ++buffers. ++ ++If you want to display more than one member list at a time you can ++@dfn{freeze} its member buffer. Freezing a member buffer prevents it ++from being overwritten the next time you display a member list. You can ++toggle this buffer status at any time. ++ ++Every member list display command in the tree buffer can be used with a ++prefix argument (@kbd{C-u}). Without a prefix argument, the command will ++pop to a member buffer displaying the member list. With prefix argument, ++the member buffer will additionally be @dfn{frozen}. ++ ++@table @kbd ++@cindex instance member variables, list ++@item L v ++This command displays the list of instance member variables. ++ ++@cindex static variables, list ++@item L V ++Display the list of static variables. ++ ++@cindex friend functions, list ++@item L d ++Display the list of friend functions. This list is used for defines if ++you are viewing the class @samp{*Globals*} which is a place holder for ++global symbols. ++ ++@cindex member functions, list ++@item L f ++Display the list of member functions. ++ ++@cindex static member functions, list ++@item L F ++Display the list of static member functions. ++ ++@cindex types, list ++@item L t ++Display a list of types. ++@end table ++ ++These lists are also available from the class' context menu invoked with ++@kbd{Mouse-3} on the class name. ++ ++ ++ ++ ++@node Go to Class, Quitting, Member Display, Tree Buffers ++@comment node-name, next, previous, up ++@section Finding a Class ++@cindex locate class ++@cindex expanding branches ++@cindex class location ++ ++@table @kbd ++@cindex search for class ++@item / ++This command reads a class name from the minibuffer with completion and ++positions the cursor on the class in the class tree. ++ ++If the branch of the class tree containing the class searched for is ++currently collapsed, the class itself and all its base classes are ++recursively made visible. (See also @ref{Expanding and ++Collapsing}.)@refill ++ ++This function is also available from the tree buffer's context menu. ++ ++@item n ++Repeat the last search done with @kbd{/}. Each tree buffer has its own ++local copy of the regular expression last searched in it. ++@end table ++ ++ ++ ++ ++@node Quitting, File Name Display, Go to Class, Tree Buffers ++@comment node-name, next, previous, up ++@section Burying a Tree Buffer ++@cindex burying tree buffer ++ ++@table @kbd ++@item q ++Is a synonym for @kbd{M-x bury-buffer}. ++@end table ++ ++ ++ ++ ++@node File Name Display, Expanding and Collapsing, Quitting, Tree Buffers ++@comment node-name, next, previous, up ++@section Displaying File Names ++ ++@table @kbd ++@cindex file names in tree buffers ++@item T f ++This command toggles the display of file names in a tree buffer. If ++file name display is switched on, the names of the files containing the ++class declaration are shown to the right of the class names. If the ++file is not known, the string @samp{unknown} is displayed. ++ ++This command is also provided in the tree buffer's context menu. ++ ++@item s ++Display file names for the current line, or for the number of lines ++given by a prefix argument. ++@end table ++ ++Here is an example of a tree buffer with file names displayed. ++ ++@example ++| Collection (unknown) ++| IndexedCollection (indexedcltn.h) ++| Array (array.h) ++| FixedArray (fixedarray.h) ++| Set (set.h) ++| Dictionary (dict.h) ++@end example ++ ++ ++ ++ ++@node Expanding and Collapsing, Tree Indentation, File Name Display, Tree Buffers ++@comment node-name, next, previous, up ++@section Expanding and Collapsing a Tree ++@cindex expand tree branch ++@cindex collapse tree branch ++@cindex branches of class tree ++@cindex class tree, collapse or expand ++ ++You can expand and collapse parts of a tree to reduce the complexity of ++large class hierarchies. Expanding or collapsing branches of a tree has ++no impact on the functionality of other commands, like @kbd{/}. (See ++also @ref{Go to Class}.)@refill ++ ++Collapsed branches are indicated with an ellipsis following the class ++name like in the example below. ++ ++@example ++| Collection ++| IndexedCollection... ++| Set ++| Dictionary ++@end example ++ ++@table @kbd ++@item - ++This command collapses the branch of the tree starting at the class the ++cursor is on. ++ ++@item + ++This command expands the branch of the tree starting at the class the ++cursor is on. Both commands for collapsing and expanding branches are ++also available from the class' object menu. ++ ++@item * ++This command expands all collapsed branches in the tree. ++@end table ++ ++ ++ ++ ++@node Tree Indentation, Killing Classes, Expanding and Collapsing, Tree Buffers ++@comment node-name, next, previous, up ++@section Changing the Tree Indentation ++@cindex tree indentation ++@cindex indentation of the tree ++ ++@table @kbd ++@item T w ++This command reads a new indentation width from the minibuffer and ++redisplays the tree buffer with the new indentation It is also ++available from the tree buffer's context menu. ++@end table ++ ++ ++ ++ ++@node Killing Classes, Saving a Tree, Tree Indentation, Tree Buffers ++@comment node-name, next, previous, up ++@section Removing Classes from the Tree ++@cindex killing classes ++@cindex class, remove from tree ++ ++@table @kbd ++@item C-k ++This command removes the class the cursor is on and all its derived ++classes from the tree. The user is asked for confirmation before the ++deletion is actually performed. ++@end table ++ ++ ++ ++ ++@node Saving a Tree, Statistics, Killing Classes, Tree Buffers ++@comment node-name, next, previous, up ++@comment node-name, next, previous, up ++@section Saving a Tree ++@cindex save tree to a file ++@cindex tree, save to a file ++@cindex class tree, save to a file ++ ++@table @kbd ++@item C-x C-s ++This command writes a class tree to the file from which it was read. ++This is useful after classes have been deleted from a tree. ++ ++@item C-x C-w ++Writes the tree to a file whose name is read from the minibuffer. ++@end table ++ ++ ++ ++ ++@node Statistics, Marking Classes, Saving a Tree, Tree Buffers ++@comment node-name, next, previous, up ++@cindex statistics for a tree ++@cindex tree statistics ++@cindex class statistics ++ ++@table @kbd ++@item x ++Display statistics for the tree, like number of classes in it, number of ++member functions, etc. This command can also be found in the buffer's ++context menu. ++@end table ++ ++ ++ ++ ++@node Marking Classes, , Statistics, Tree Buffers ++@comment node-name, next, previous, up ++@cindex marking classes ++@cindex operations on marked classes ++ ++Classes can be marked for operations similar to the standard Emacs ++commands @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} (see ++also @xref{Tags-like Functions}.)@refill ++ ++@table @kbd ++@cindex toggle mark ++@item M t ++Toggle the mark of the line point is in or for as many lines as given by ++a prefix command. This command can also be found in the class' context ++menu. ++ ++@cindex unmark all ++@item M a ++Unmark all classes. With prefix argument @kbd{C-u}, mark all classes in ++the tree. Since this command operates on the whole buffer, it can also be ++found in the buffer's object menu. ++@end table ++ ++Marked classes are displayed with an @code{>} in column one of the tree ++display, like in the following example ++ ++@example ++|> Collection ++| IndexedCollection... ++|> Set ++| Dictionary ++@end example ++ ++ ++ ++ ++@c **************************************************************** ++@c *** ++@c *** MEMBER BUFFERS ++@c *** ++@c **************************************************************** ++ ++@node Member Buffers, Tags-like Functions, Tree Buffers, Top ++@comment node-name, next, previous, up ++@chapter Member Buffers ++@cindex members ++@cindex member buffer mode ++ ++@cindex class members, types ++@cindex types of class members ++@dfn{Member buffers} are used to operate on lists of members of a class. ++Ebrowse distinguishes six kinds of lists: ++ ++@itemize @bullet ++@item ++Instance variables (normal member variables); ++@item ++Instance functions (normal member functions); ++@item ++Static variables; ++@item ++Static member functions; ++@item ++Friend functions; ++@item ++Types (@code{enum}s and @code{typedef}s defined with class scope. ++Nested classes will be shown in the class tree like normal classes. ++@end itemize ++ ++Like tree buffers, member buffers install their own major mode. Also ++like in tree buffers, menus are provided for certain areas in the ++buffer: members, classes, and the buffer itself. ++ ++@menu ++* Switching Member Lists:: Choosing which members to display ++* Finding/Viewing:: Modifying source code ++* Inherited Members:: Display of Inherited Members ++* Searching Members:: Finding members in member buffer ++* Switching to Tree:: Going back to the tree buffer ++* Filters:: Selective member display ++* Attributes:: Display of @code{virtual} etc. ++* Long and Short Display:: Comprehensive and verbose display ++* Regexp Display:: Showing matching regular expressions ++* Switching Classes:: Displaying another class ++* Killing/Burying:: Getting rid of the member buffer ++* Column Width:: Display style ++* Redisplay:: Redrawing the member list ++* Getting Help:: How to get help for key bindings ++@end menu ++ ++ ++ ++ ++@node Switching Member Lists, Finding/Viewing, Member Buffers, Member Buffers ++@comment node-name, next, previous, up ++@section Switching Member Lists ++@cindex member lists, in member buffers ++@cindex static members ++@cindex friends ++@cindex types ++@cindex defines ++ ++@table @kbd ++@cindex next member list ++@item L n ++This command switches the member buffer display to the next member list. ++ ++@cindex previous member list ++@item L p ++This command switches the member buffer display to the previous member ++list. ++ ++@item L f ++Switch to the list of member functions. ++ ++@cindex static ++@item L F ++Switch to the list of static member functions. ++ ++@item L v ++Switch to the list of member variables. ++ ++@item L V ++Switch to the list of static member variables. ++ ++@item L d ++Switch to the list of friends or defines. ++ ++@item L t ++Switch to the list of types. ++@end table ++ ++Both commands cycle through the member list. ++ ++Most of the commands are also available from the member buffer's ++context menu. ++ ++ ++ ++ ++@node Finding/Viewing, Inherited Members, Switching Member Lists, Member Buffers ++@comment node-name, next, previous, up ++@section Finding and Viewing Member Source ++@cindex finding members, in member buffers ++@cindex viewing members, in member buffers ++@cindex member definitions, in member buffers ++@cindex member declarations, in member buffers ++@cindex definition of a member, in member buffers ++@cindex declaration of a member, in member buffers ++ ++@table @kbd ++@item RET ++This command finds the definition of the member the cursor is on. ++Finding involves roughly the same as the standard Emacs tags facility ++does---loading the file and searching for a regular expression matching ++the member. ++ ++@item f ++This command finds the declaration of the member the cursor is on. ++ ++@item SPC ++This is the same command as @kbd{RET}, but views the member definition ++instead of finding the member's source file. ++ ++@item v ++This is the same command as @kbd{f}, but views the member's declaration ++instead of finding the file the declaration is in. ++@end table ++ ++You can install a hook function to perform actions after a member or ++class declaration or definition has been found, or when it is not found. ++ ++All the commands described above can also be found in the context menu ++displayed when clicking @kbd{Mouse-2} on a member name. ++ ++ ++ ++ ++@node Inherited Members, Searching Members, Finding/Viewing, Member Buffers ++@comment node-name, next, previous, up ++@section Display of Inherited Members ++@cindex superclasses, members ++@cindex base classes, members ++@cindex inherited members ++ ++@table @kbd ++@item D b ++This command toggles the display of inherited members in the member ++buffer. This is also in the buffer's context menu. ++@end table ++ ++ ++ ++ ++@node Searching Members, Switching to Tree, Inherited Members, Member Buffers ++@comment node-name, next, previous, up ++@section Searching Members ++@cindex searching members ++ ++@table @kbd ++@item G v ++Position the cursor on a member whose name is read from the minibuffer; ++only members shown in the current member buffer appear in the completion ++list. ++ ++@item G m ++Like the above command, but all members for the current class appear in ++the completion list. If necessary, the current member list is switched ++to the one containing the member. ++ ++With a prefix argument (@kbd{C-u}), all members in the class tree, ++i.e.@: all members the browser knows about appear in the completion ++list. The member display will be switched to the class and member list ++containing the member. ++ ++@item G n ++Repeat the last member search. ++@end table ++ ++Look into the buffer's context menu for a convenient way to do this with ++a mouse. ++ ++ ++ ++@node Switching to Tree, Filters, Searching Members, Member Buffers ++@comment node-name, next, previous, up ++@section Switching to Tree Buffer ++@cindex tree buffer, switch to ++@cindex buffer switching ++@cindex switching buffers ++ ++@table @kbd ++@item @key{TAB} ++Pop up the tree buffer to which the member buffer belongs. ++ ++@item t ++Do the same as @key{TAB} but also position the cursor on the class ++displayed in the member buffer. ++@end table ++ ++ ++ ++ ++@node Filters, Attributes, Switching to Tree, Member Buffers ++@comment node-name, next, previous, up ++@section Filters ++@cindex filters ++ ++@table @kbd ++@cindex @code{public} members ++@item F a u ++This command toggles the display of @code{public} members. The ++@samp{a} stands for `access'. ++ ++@cindex @code{protected} members ++@item F a o ++This command toggles the display of @code{protected} members. ++ ++@cindex @code{private} members ++@item F a i ++This command toggles the display of @code{private} members. ++ ++@cindex @code{virtual} members ++@item F v ++This command toggles the display of @code{virtual} members. ++ ++@cindex @code{inline} members ++@item F i ++This command toggles the display of @code{inline} members. ++ ++@cindex @code{const} members ++@item F c ++This command toggles the display of @code{const} members. ++ ++@cindex pure virtual members ++@item F p ++This command toggles the display of pure virtual members. ++ ++@cindex remove filters ++@item F r ++This command removes all filters. ++@end table ++ ++These commands are also found in the buffer's context menu. ++ ++ ++ ++ ++@node Attributes, Long and Short Display, Filters, Member Buffers ++@comment node-name, next, previous, up ++@section Displaying Member Attributes ++@cindex attributes ++@cindex member attribute display ++ ++@table @kbd ++@item D a ++Toggle the display of member attributes (default is on). ++ ++The nine member attributes Ebrowse knows about are displayed ++as a list a single-characters flags enclosed in angle brackets in front ++the of the member's name. A @samp{-} at a given position means that ++the attribute is false. The list of attributes from left to right is ++ ++@table @samp ++@cindex @code{template} attribute ++@item T ++The member is a template. ++ ++@cindex @code{extern "C"} attribute ++@item C ++The member is declared @code{extern "C"}. ++ ++@cindex @code{virtual} attribute ++@item v ++Means the member is declared @code{virtual}. ++ ++@cindex @code{inline} ++@item i ++The member is declared @code{inline}. ++ ++@cindex @code{const} attribute ++@item c ++The member is @code{const}. ++ ++@cindex pure virtual function attribute ++@item 0 ++The member is a pure virtual function. ++ ++@cindex @code{mutable} attribute ++@item m ++The member is declared @code{mutable}. ++ ++@cindex @code{explicit} attribute ++@item e ++The member is declared @code{explicit}. ++ ++@item t ++The member is a function with a throw list. ++@end table ++@end table ++ ++This command is also in the buffer's context menu. ++ ++ ++ ++@node Long and Short Display, Regexp Display, Attributes, Member Buffers ++@comment node-name, next, previous, up ++@section Long and Short Member Display ++@cindex display form ++@cindex long display ++@cindex short display ++ ++@table @kbd ++@item D l ++This command toggles the member buffer between short and long display ++form. The short display form displays member names, only: ++ ++@example ++| isEmpty contains hasMember create ++| storeSize hash isEqual restoreGuts ++| saveGuts ++@end example ++ ++The long display shows one member per line with member name and regular ++expressions matching the member (if known): ++ ++@example ++| isEmpty Bool isEmpty () const... ++| hash unsigned hash () const... ++| isEqual int isEqual (... ++@end example ++ ++Regular expressions will only be displayed when the Lisp database has ++not been produced with the @command{ebrowse} option @samp{--no-regexps}. ++@xref{Matching, --no-regexps, Regular Expressions}. ++@end table ++ ++ ++ ++ ++@node Regexp Display, Switching Classes, Long and Short Display, Member Buffers ++@comment node-name, next, previous, up ++@section Display of Regular Expressions ++@cindex regular expression display ++ ++@table @kbd ++@item D r ++This command toggles the long display form from displaying the regular ++expressions matching the member declarations to those expressions ++matching member definitions. ++@end table ++ ++Regular expressions will only be displayed when the Lisp database has ++not been produced with the @command{ebrowse} option @samp{--no-regexps}, ++see @ref{Matching, --no-regexps, Regular Expressions}. ++ ++ ++ ++ ++@node Switching Classes, Killing/Burying, Regexp Display, Member Buffers ++@comment node-name, next, previous, up ++@section Displaying Another Class ++@cindex base class, display ++@cindex derived class, display ++@cindex superclass, display ++@cindex subclass, display ++@cindex class display ++ ++@table @kbd ++@item C c ++This command lets you switch the member buffer to another class. It ++reads the name of the new class from the minibuffer with completion. ++ ++@item C b ++This is the same command as @kbd{C c} but restricts the classes shown in ++the completion list to immediate base classes, only. If only one base ++class exists, this one is immediately shown in the minibuffer. ++ ++@item C d ++Same as @kbd{C b}, but for derived classes. ++ ++@item C p ++Switch to the previous class in the class hierarchy on the same level as ++the class currently displayed. ++ ++@item C n ++Switch to the next sibling of the class in the class tree. ++@end table ++ ++ ++ ++ ++@node Killing/Burying, Column Width, Switching Classes, Member Buffers ++@comment node-name, next, previous, up ++@section Burying a Member Buffer ++@cindex burying member buffers ++ ++@table @kbd ++@item q ++This command is a synonym for @kbd{M-x bury-buffer}. ++@end table ++ ++ ++ ++ ++@node Column Width, Redisplay, Killing/Burying, Member Buffers ++@comment node-name, next, previous, up ++@section Setting the Column Width ++@cindex column width ++@cindex member indentation ++@cindex indentation, member ++ ++@table @kbd ++@item D w ++This command sets the column width depending on the display form used ++(long or short display). ++@end table ++ ++ ++ ++ ++@node Redisplay, Getting Help, Column Width, Member Buffers ++@comment node-name, next, previous, up ++@section Forced Redisplay ++@cindex redisplay of member buffers ++ ++@table @kbd ++@item C-l ++This command forces a redisplay of the member buffer. If the width ++of the window displaying the member buffer is changed this command ++redraws the member list with the appropriate column widths and number of ++columns. ++@end table ++ ++ ++ ++ ++@node Getting Help, , Redisplay, Member Buffers ++@comment node-name, next, previous, up ++@cindex help ++ ++@table @kbd ++@item ? ++This key is bound to @code{describe-mode}. ++@end table ++ ++ ++ ++ ++@comment ************************************************************** ++@comment *** TAGS LIKE FUNCTIONS ++@comment ************************************************************** ++ ++@node Tags-like Functions, GNU Free Documentation License, Member Buffers, Top ++@comment node-name, next, previous, up ++@chapter Tags-like Functions ++ ++Ebrowse provides tags functions similar to those of the standard ++Emacs Tags facility, but better suited to the needs of C++ programmers. ++ ++@menu ++* Finding and Viewing:: Going to a member declaration/definition ++* Position Stack:: Moving to previous locations ++* Search & Replace:: Searching and replacing over class tree files ++* Members in Files:: Listing all members in a given file ++* Apropos:: Listing members matching a regular expression ++* Symbol Completion:: Completing names while editing ++* Member Buffer Display:: Quickly display a member buffer for some ++ identifier ++@end menu ++ ++ ++ ++@node Finding and Viewing, Position Stack, Tags-like Functions, Tags-like Functions ++@comment node-name, next, previous, up ++@section Finding and Viewing Members ++@cindex finding class member, in C++ source ++@cindex viewing class member, in C++ source ++@cindex tags ++@cindex member definition, finding, in C++ source ++@cindex member declaration, finding, in C++ source ++ ++The functions in this section are similar to those described in ++@ref{Source Display}, and also in @ref{Finding/Viewing}, except that ++they work in a C++ source buffer, not in member and tree buffers created ++by Ebrowse. ++ ++@table @kbd ++@item C-c C-m f ++Find the definition of the member around point. If you invoke this ++function with a prefix argument, the declaration is searched. ++ ++If more than one class contains a member with the given name you can ++select the class with completion. If there is a scope declaration in ++front of the member name, this class name is used as initial input for ++the completion. ++ ++@item C-c C-m F ++Find the declaration of the member around point. ++ ++@item C-c C-m v ++View the definition of the member around point. ++ ++@item C-c C-m V ++View the declaration of the member around point. ++ ++@item C-c C-m 4 f ++Find a member's definition in another window. ++ ++@item C-c C-m 4 F ++Find a member's declaration in another window. ++ ++@item C-c C-m 4 v ++View a member's definition in another window. ++ ++@item C-c C-m 4 V ++View a member's declaration in another window. ++ ++@item C-c C-m 5 f ++Find a member's definition in another frame. ++ ++@item C-c C-m 5 F ++Find a member's declaration in another frame. ++ ++@item C-c C-m 5 v ++View a member's definition in another frame. ++ ++@item C-c C-m 5 V ++View a member's declaration in another frame. ++@end table ++ ++ ++ ++@node Position Stack, Search & Replace, Finding and Viewing, Tags-like Functions ++@comment node-name, next, previous, up ++@section The Position Stack ++@cindex position stack ++ ++When jumping to a member declaration or definition with one of ++Ebrowse's commands, the position from where you performed the ++jump and the position where you jumped to are recorded in a ++@dfn{position stack}. There are several ways in which you can quickly ++move to positions in the stack:@refill ++ ++@table @kbd ++@cindex return to original position ++@item C-c C-m - ++This command sets point to the previous position in the position stack. ++Directly after you performed a jump, this will put you back to the ++position where you came from. ++ ++The stack is not popped, i.e.@: you can always switch back and forth ++between positions in the stack. To avoid letting the stack grow to ++infinite size there is a maximum number of positions defined. When this ++number is reached, older positions are discarded when new positions are ++pushed on the stack. ++ ++@item C-c C-m + ++This command moves forward in the position stack, setting point to ++the next position stored in the position stack. ++ ++@item C-c C-m p ++Displays an electric buffer showing all positions saved in the stack. ++You can select a position by pressing @kbd{SPC} in a line. You can ++view a position with @kbd{v}. ++@end table ++ ++ ++ ++ ++@node Search & Replace, Members in Files, Position Stack, Tags-like Functions ++@comment node-name, next, previous, up ++@section Searching and Replacing ++@cindex searching multiple C++ files ++@cindex replacing in multiple C++ files ++@cindex restart tags-operation ++ ++Ebrowse allows you to perform operations on all or a subset of the files ++mentioned in a class tree. When you invoke one of the following ++functions and more than one class tree is loaded, you must choose a ++class tree to use from an electric tree menu. If the selected tree ++contains marked classes, the following commands operate on the files ++mentioned in the marked classes only. Otherwise all files in the class ++tree are used. ++ ++@table @kbd ++@item C-c C-m s ++This function performs a regular expression search in the chosen set of ++files. ++ ++@item C-c C-m u ++This command performs a search for calls of a given member which is ++selected in the usual way with completion. ++ ++@item C-c C-m % ++Perform a query replace over the set of files. ++ ++@item C-c C-m , ++All three operations above stop when finding a match. You can restart ++the operation with this command. ++ ++@item C-c C-m n ++This restarts the last tags operation with the next file in the list. ++@end table ++ ++ ++ ++ ++@node Members in Files, Apropos, Search & Replace, Tags-like Functions ++@comment node-name, next, previous, up ++@section Members in Files ++@cindex files ++@cindex members in file, listing ++@cindex list class members in a file ++@cindex file, members ++ ++The command @kbd{C-c C-m l}, lists all members in a given file. The file ++name is read from the minibuffer with completion. ++ ++ ++ ++ ++@node Apropos, Symbol Completion, Members in Files, Tags-like Functions ++@comment node-name, next, previous, up ++@section Member Apropos ++@cindex apropos on class members ++@cindex members, matching regexp ++ ++The command @kbd{C-c C-m a} can be used to display all members matching a ++given regular expression. This command can be very useful if you ++remember only part of a member name, and not its beginning. ++ ++A special buffer is popped up containing all identifiers matching the ++regular expression, and what kind of symbol it is (e.g.@: a member ++function, or a type). You can then switch to this buffer, and use the ++command @kbd{C-c C-m f}, for example, to jump to a specific member. ++ ++ ++ ++ ++@node Symbol Completion, Member Buffer Display, Apropos, Tags-like Functions ++@comment node-name, next, previous, up ++@section Symbol Completion ++@cindex completion ++@cindex symbol completion ++ ++The command @kbd{C-c C-m @key{TAB}} completes the symbol in front of point. ++ ++ ++ ++ ++@node Member Buffer Display, , Symbol Completion, Tags-like Functions ++@section Quick Member Display ++@cindex member buffer, for member at point ++ ++You can quickly display a member buffer containing the member the cursor ++in on with the command @kbd{C-c C-m m}. ++ ++ ++@node GNU Free Documentation License, Concept Index, Tags-like Functions, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++ ++@node Concept Index, , GNU Free Documentation License, Top ++@unnumbered Concept Index ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 52fe78ac-a1c4-48e7-815e-0a31acfad4bf ++@end ignore +diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi +new file mode 100644 +index 0000000..80540ea +--- /dev/null ++++ b/doc/misc/ediff.texi +@@ -0,0 +1,2541 @@ ++\input texinfo @c -*-texinfo-*- ++@c documentation for Ediff ++@c Written by Michael Kifer ++ ++@comment %**start of header (This is for running Texinfo on a region.) ++ ++@comment Using ediff.info instead of ediff in setfilename breaks DOS. ++@comment @setfilename ediff ++@comment @setfilename ediff.info ++@setfilename ../../info/ediff ++ ++@settitle Ediff User's Manual ++@synindex vr cp ++@synindex fn cp ++@synindex pg cp ++@synindex ky cp ++ ++@iftex ++@finalout ++@end iftex ++@c @smallbook ++@comment %**end of header (This is for running Texinfo on a region.) ++ ++@copying ++This file documents Ediff, a comprehensive visual interface to Unix diff ++and patch utilities. ++ ++Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, ++2003, 2004, 2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* Ediff: (ediff). A visual interface for comparing and merging programs. ++@end direntry ++ ++@titlepage ++@title Ediff User's Manual ++@sp 4 ++@subtitle Ediff version 2.81.2 ++@sp 1 ++@subtitle November 2008 ++@sp 5 ++@author Michael Kifer ++@page ++ ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top, Introduction, (dir), (dir) ++ ++@insertcopying ++ ++@menu ++* Introduction:: About Ediff. ++* Major Entry Points:: How to use Ediff. ++* Session Commands:: Ediff commands used within a session. ++* Registry of Ediff Sessions:: Keeping track of multiple Ediff sessions. ++* Session Groups:: Comparing and merging directories. ++* Remote and Compressed Files:: You may want to know about this. ++* Customization:: How to make Ediff work the way YOU want. ++* Credits:: Thanks to those who helped. ++* GNU Free Documentation License:: The license for this documentation. ++* Index:: ++@end menu ++ ++@node Introduction, Major Entry Points, Top, Top ++@chapter Introduction ++ ++@cindex Comparing files and buffers ++@cindex Merging files and buffers ++@cindex Patching files and buffers ++@cindex Finding differences ++ ++Ediff provides a convenient way for simultaneous browsing through ++the differences between a pair (or a triple) of files or buffers ++(which are called @samp{variants} for our purposes). The ++files being compared, file-A, file-B, and file-C (if applicable) are ++shown in separate windows (side by side, one above the another, or in ++separate frames), and the differences are highlighted as you step ++through them. You can also copy difference regions from one buffer to ++another (and recover old differences if you change your mind). ++ ++Another powerful feature is the ability to merge a pair of files into a ++third buffer. Merging with an ancestor file is also supported. ++Furthermore, Ediff is equipped with directory-level capabilities that ++allow the user to conveniently launch browsing or merging sessions on ++groups of files in two (or three) different directories. ++ ++In addition, Ediff can apply a patch to a file and then let you step through ++both files, the patched and the original one, simultaneously, ++difference-by-difference. You can even apply a patch right out of a mail ++buffer, i.e., patches received by mail don't even have to be saved. Since ++Ediff lets you copy differences between variants, you can, in effect, apply ++patches selectively (i.e., you can copy a difference region from ++@file{file.orig} to @file{file}, thereby undoing any particular patch that ++you don't like). ++ ++Ediff even understands multi-file patches and can apply them interactively! ++(Ediff can recognize multi-file patches only if they are in the context ++format or GNU unified format. All other patches are treated as 1-file ++patches. Ediff is [hopefully] using the same algorithm as @code{patch} to ++determine which files need to be patched.) ++ ++Ediff is aware of version control, which lets you compare ++files with their older versions. Ediff also works with remote and ++compressed files, automatically ftp'ing them over and uncompressing them. ++@xref{Remote and Compressed Files}, for details. ++ ++This package builds upon ideas borrowed from Emerge, and several of Ediff's ++functions are adaptations from Emerge. Although Ediff subsumes and greatly ++extends Emerge, much of the functionality in Ediff is influenced by Emerge. ++The architecture and the interface are, of course, drastically different. ++ ++@node Major Entry Points, Session Commands, Introduction, Top ++@chapter Major Entry Points ++ ++When Ediff starts up, it displays a small control window, which accepts the ++Ediff commands, and two or three windows displaying the files to be compared ++or merged. The control window can be in its own small frame or it can be ++part of a bigger frame that displays other buffers. In any case, it is ++important that the control window be active (i.e., be the one receiving the ++keystrokes) when you use Ediff. You can switch to other Emacs buffers at ++will and even edit the files currently being compared with Ediff and then ++switch back to Ediff at any time by activating the appropriate Emacs windows. ++ ++Ediff can be invoked interactively using the following functions, which can ++be run either from the minibuffer or from the menu bar. In the menu bar, ++all Ediff's entry points belong to three submenus of the Tools menu: ++Compare, Merge, and Apply Patch. ++ ++@table @code ++@item ediff-files ++@itemx ediff ++@findex ediff-files ++@findex ediff ++Compare two files. ++ ++@item ediff-backup ++@findex ediff-backup ++Compare a file with its backup. If there are several numerical backups, use ++the latest. If the file is itself a backup, then compare it with its ++original. ++ ++@item ediff-buffers ++@findex ediff-buffers ++Compare two buffers. ++ ++@item ediff-files3 ++@itemx ediff3 ++@findex ediff-files3 ++@findex ediff3 ++Compare three files. ++ ++@item ediff-buffers3 ++@findex ediff-buffers3 ++Compare three buffers. ++ ++@item edirs ++@itemx ediff-directories ++@findex edirs ++@findex ediff-directories ++ Compare files common to two directories. ++@item edirs3 ++@itemx ediff-directories3 ++@findex edirs3 ++@findex ediff-directories3 ++ Compare files common to three directories. ++@item edir-revisions ++@itemx ediff-directory-revisions ++@findex ediff-directory-revisions ++@findex edir-revisions ++ Compare versions of files in a given directory. Ediff selects only the ++files that are under version control. ++@item edir-merge-revisions ++@itemx ediff-merge-directory-revisions ++@findex edir-merge-revisions ++@findex ediff-merge-directory-revisions ++ Merge versions of files in a given directory. Ediff selects only the ++files that are under version control. ++@item edir-merge-revisions-with-ancestor ++@itemx ediff-merge-directory-revisions-with-ancestor ++@findex edir-merge-revisions-with-ancestor ++@findex ediff-merge-directory-revisions-with-ancestor ++ Merge versions of files in a given directory using other versions as ++ancestors. Ediff selects only the files that are under version control. ++ ++@item ediff-windows-wordwise ++@findex ediff-windows-wordwise ++Compare windows word-by-word. ++ ++@item ediff-windows-linewise ++@findex ediff-windows-linewise ++Compare windows line-by-line. ++ ++@item ediff-regions-wordwise ++@findex ediff-regions-wordwise ++Compare regions word-by-word. The regions can come from the same buffer ++and they can even overlap. You will be asked to specify the buffers that ++contain the regions, which you want to compare. For each buffer, you will ++also be asked to mark the regions to be compared. Pay attention to the ++messages that appear in the minibuffer. ++ ++@item ediff-regions-linewise ++@findex ediff-regions-linewise ++Similar to @code{ediff-windows-linewise}, but compares the regions ++line-by-line. See @code{ediff-windows-linewise} for more details. ++ ++@item ediff-revision ++@findex ediff-revision ++ Compare versions of the current buffer, if the buffer is visiting ++ a file under version control. ++ ++@item ediff-patch-file ++@itemx epatch ++@findex ediff-patch-file ++@findex epatch ++ ++Patch a file or multiple files, then compare. If the patch applies to just ++one file, Ediff will invoke a regular comparison session. If it is a ++multi-file patch, then a session group interface will be used and the user ++will be able to patch the files selectively. @xref{Session Groups}, for ++more details. ++ ++Since the patch might be in a buffer or a file, you will be asked which is ++the case. To avoid this extra prompt, you can invoke this command with a ++prefix argument. With an odd prefix argument, Ediff assumes the patch ++is in a file; with an even argument, a buffer is assumed. ++ ++Note that @code{ediff-patch-file} will actually use the @code{patch} ++utility to change the original files on disk. This is not that ++dangerous, since you will always have the original contents of the file ++saved in another file that has the extension @file{.orig}. ++Furthermore, if the file is under version control, then you can always back ++out to one of the previous versions (see the section on Version Control in ++the Emacs manual). ++ ++@code{ediff-patch-file} is careful about versions control: if the file ++to be patched is checked in, then Ediff will offer to check it out, because ++failing to do so may result in the loss of the changes when the file is ++checked out the next time. ++ ++If you don't intend to modify the file via the patch and just want to see ++what the patch is all about (and decide later), then ++@code{ediff-patch-buffer} might be a better choice. ++ ++@item ediff-patch-buffer ++@itemx epatch-buffer ++@findex ediff-patch-buffer ++@findex epatch-buffer ++Patch a buffer, then compare. The buffer being patched and the file visited ++by that buffer (if any) is @emph{not} modified. The result of the patch ++appears in some other buffer that has the name ending with @emph{_patched}. ++ ++This function would refuse to apply a multifile patch to a buffer. Use ++@code{ediff-patch-file} for that (and when you want the original file to be ++modified by the @code{patch} utility). ++ ++Since the patch might be in a buffer or a file, you will be asked which is ++the case. To avoid this extra prompt, you can invoke this command with a ++prefix argument. With an odd prefix argument, Ediff assumes the patch ++is in a file; with an even argument, a buffer is assumed. ++ ++@item ediff-merge-files ++@itemx ediff-merge ++@findex ediff-merge-files ++@findex ediff-merge ++Merge two files. ++ ++@item ediff-merge-files-with-ancestor ++@itemx ediff-merge-with-ancestor ++@findex ediff-merge-files-with-ancestor ++@findex ediff-merge-with-ancestor ++Like @code{ediff-merge}, but with a third ancestor file. ++ ++@item ediff-merge-buffers ++@findex ediff-merge-buffers ++Merge two buffers. ++ ++@item ediff-merge-buffers-with-ancestor ++@findex ediff-merge-buffers-with-ancestor ++Same but with ancestor. ++ ++ ++@item edirs-merge ++@itemx ediff-merge-directories ++@findex edirs-merge ++@findex ediff-merge-directories ++ Merge files common to two directories. ++@item edirs-merge-with-ancestor ++@itemx ediff-merge-directories-with-ancestor ++@findex edirs-merge-with-ancestor ++@findex ediff-merge-directories-with-ancestor ++ Same but using files in a third directory as ancestors. ++ If a pair of files doesn't have an ancestor in the ancestor-directory, you ++ will still be able to merge them without the ancestor. ++ ++@item ediff-merge-revisions ++@findex ediff-merge-revisions ++Merge two versions of the file visited by the current buffer. ++ ++@item ediff-merge-revisions-with-ancestor ++@findex ediff-merge-revisions-with-ancestor ++Same but with ancestor. ++ ++@item ediff-documentation ++@findex ediff-documentation ++Brings up this manual. ++ ++@item ediff-show-registry ++@itemx eregistry ++Brings up Ediff session registry. This feature enables you to quickly find ++and restart active Ediff sessions. ++@end table ++ ++@noindent ++If you want Ediff to be loaded from the very beginning of your Emacs ++session, you should put this line in your @file{~/.emacs} file: ++ ++@example ++(require 'ediff) ++@end example ++ ++@noindent ++Otherwise, Ediff will be loaded automatically when you use one of the ++above functions, either directly or through the menus. ++ ++When the above functions are invoked, the user is prompted for all the ++necessary information---typically the files or buffers to compare, merge, or ++patch. Ediff tries to be smart about these prompts. For instance, in ++comparing/merging files, it will offer the visible buffers as defaults. In ++prompting for files, if the user enters a directory, the previously input ++file name will be appended to that directory. In addition, if the variable ++@code{ediff-use-last-dir} is not @code{nil}, Ediff will offer ++previously entered directories as defaults (which will be maintained ++separately for each type of file, A, B, or C). ++@vindex @code{ediff-use-last-dir} ++ ++All the above functions use the POSIX @code{diff} or @code{diff3} programs ++to find differences between two files. They process the @code{diff} output ++and display it in a convenient form. At present, Ediff understands only ++the plain output from diff. Options such as @samp{-c} are not supported, ++nor is the format produced by incompatible file comparison programs such as ++the VMS version of @code{diff}. ++ ++The functions @code{ediff-files}, @code{ediff-buffers}, ++@code{ediff-files3}, @code{ediff-buffers3} first display the coarse, ++line-based difference regions, as reported by the @code{diff} program. The ++total number of difference regions and the current difference number are ++always displayed in the mode line of the control window. ++ ++Since @code{diff} may report fairly large chunks of text as being different, ++even though the difference may be localized to just a few words or even ++to the white space or line breaks, Ediff further @emph{refines} the ++regions to indicate which exact words differ. If the only difference is ++in the white space and line breaks, Ediff says so. ++ ++On a color display, fine differences are highlighted with color; on a ++monochrome display, they are underlined. @xref{Highlighting Difference ++Regions}, for information on how to customize this. ++ ++The commands @code{ediff-windows-wordwise}, ++@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and ++@code{ediff-regions-linewise} do comparison on parts of existing Emacs ++buffers. The commands @code{ediff-windows-wordwise} and ++@code{ediff-regions-wordwise} are intended for relatively small segments ++of buffers (e.g., up to 100 lines, depending on the speed of your machine), ++as they perform comparison on the basis of words rather than lines. ++(Word-wise comparison of large chunks of text can be slow.) ++ ++To compare large regions, use @code{ediff-regions-linewise}. This ++command displays differences much like @code{ediff-files} and ++@code{ediff-buffers}. ++ ++The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a ++patch to a file or a buffer and then run Ediff on the appropriate ++files/buffers, displaying the difference regions. ++ ++The entry points @code{ediff-directories}, @code{ediff-merge-directories}, ++etc., provide a convenient interface for comparing and merging files in ++different directories. The user is presented with Dired-like interface from ++which one can run a group of related Ediff sessions. ++ ++For files under version control, @code{ediff-revision} lets you compare ++the file visited by the current buffer to one of its checked-in versions. ++You can also compare two checked-in versions of the visited file. ++Moreover, the functions @code{ediff-directory-revisions}, ++@code{ediff-merge-directory-revisions}, etc., let you run a group of ++related Ediff sessions by taking a directory and comparing (or merging) ++versions of files in that directory. ++ ++@node Session Commands, Registry of Ediff Sessions, Major Entry Points, Top ++@chapter Session Commands ++ ++All Ediff commands are displayed in a Quick Help window, unless you type ++@kbd{?} to shrink the window to just one line. You can redisplay the help ++window by typing @kbd{?} again. The Quick Help commands are detailed below. ++ ++Many Ediff commands take numeric prefix arguments. For instance, if you ++type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}), ++Ediff moves to the third difference region. Typing 3 and then @kbd{a} ++(@code{ediff-diff-to-diff}) copies the 3rd difference region from variant A ++to variant B. Likewise, 4 followed by @kbd{ra} restores the 4th difference ++region in buffer A (if it was previously written over via the command ++@kbd{a}). ++ ++Some commands take negative prefix arguments as well. For instance, typing ++@kbd{-} and then @kbd{j} will make the last difference region ++current. Typing @kbd{-2} then @kbd{j} makes the penultimate difference ++region current, etc. ++ ++Without the prefix argument, all commands operate on the currently ++selected difference region. You can make any difference region ++current using the various commands explained below. ++ ++For some commands, the actual value of the prefix argument is ++immaterial. However, if supplied, the prefix argument may modify the ++command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}). ++ ++@menu ++* Quick Help Commands:: Frequently used commands. ++* Other Session Commands:: Commands that are not bound to keys. ++@end menu ++ ++@node Quick Help Commands,Other Session Commands,,Session Commands ++@section Quick Help Commands ++ ++@table @kbd ++@item ? ++@kindex ? ++Toggles the Ediff Quick Help window ON and OFF. ++@item G ++@kindex G ++Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer. ++ ++@item E ++@kindex E ++Brings up the top node of this manual, where you can find further ++information on the various Ediff functions and advanced issues, such as ++customization, session groups, etc. ++ ++@item v ++@kindex v ++Scrolls up buffers A and B (and buffer C where appropriate) in a ++coordinated fashion. ++@item V ++@kindex V ++Scrolls the buffers down. ++ ++@item < ++@kindex < ++Scrolls the buffers to the left simultaneously. ++@item > ++@kindex > ++Scrolls buffers to the right. ++ ++@item wd ++@kindex wd ++Saves the output from the diff utility, for further reference. ++ ++With prefix argument, saves the plain output from @code{diff} (see ++@code{ediff-diff-program} and @code{ediff-diff-options}). Without the ++argument, it saves customized @code{diff} output (see ++@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if ++it is available. ++ ++@item wa ++@kindex wa ++Saves buffer A, if it was modified. ++@item wb ++@kindex wb ++Saves buffer B, if it was modified. ++@item wc ++@kindex wc ++Saves buffer C, if it was modified (if you are in a session that ++compares three files simultaneously). ++ ++@item a ++@kindex a ++@emph{In comparison sessions:} ++Copies the current difference region (or the region specified as the prefix ++to this command) from buffer A to buffer B. ++Ediff saves the old contents of buffer B's region; it can ++be restored via the command @kbd{rb}, which see. ++ ++@emph{In merge sessions:} ++Copies the current difference region (or the region specified as the prefix ++to this command) from buffer A to the merge buffer. The old contents of ++this region in buffer C can be restored via the command @kbd{r}. ++ ++@item b ++@kindex b ++Works similarly, but copies the current difference region from buffer B to ++buffer A (in @emph{comparison sessions}) or the merge buffer (in ++@emph{merge sessions}). ++ ++Ediff saves the old contents of the difference region copied over; it can ++be reinstated via the command @kbd{ra} in comparison sessions and ++@kbd{r} in merge sessions. ++ ++@item ab ++@kindex ab ++Copies the current difference region (or the region specified as the prefix ++to this command) from buffer A to buffer B. This (and the next five) ++command is enabled only in sessions that compare three files ++simultaneously. The old region in buffer B is saved and can be restored ++via the command @kbd{rb}. ++@item ac ++@kindex ac ++Copies the difference region from buffer A to buffer C. ++The old region in buffer C is saved and can be restored via the command ++@kbd{rc}. ++@item ba ++@kindex ba ++Copies the difference region from buffer B to buffer A. ++The old region in buffer A is saved and can be restored via the command ++@kbd{ra}. ++@item bc ++@kindex bc ++Copies the difference region from buffer B to buffer C. ++The command @kbd{rc} undoes this. ++@item ca ++@kindex ca ++Copies the difference region from buffer C to buffer A. ++The command @kbd{ra} undoes this. ++@item cb ++@kindex cb ++Copies the difference region from buffer C to buffer B. ++The command @kbd{rb} undoes this. ++ ++@item p ++@itemx DEL ++@kindex p ++@kindex DEL ++Makes the previous difference region current. ++@item n ++@itemx SPC ++@kindex n ++@kindex SPC ++Makes the next difference region current. ++ ++@item j ++@itemx -j ++@itemx Nj ++@kindex j ++Makes the very first difference region current. ++ ++@kbd{-j} makes the last region current. Typing a number, N, and then `j' ++makes the difference region N current. Typing -N (a negative number) then ++`j' makes current the region Last - N. ++ ++@item ga ++@kindex ga ++Makes current the difference region closest to the position of the point in ++buffer A. ++ ++However, with a prefix argument, Ediff would position all variants ++around the area indicated by the current point in buffer A: if ++the point is inside a difference region, then the variants will be ++positioned at this difference region. If the point is not in any difference ++region, then it is in an area where all variants agree with each other. In ++this case, the variants will be positioned so that each would display this ++area (of agreement). ++@item gb ++@kindex gb ++Makes current the difference region closest to the position of the point in ++buffer B. ++ ++With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B. ++@item gc ++@kindex gc ++@emph{In merge sessions:} ++makes current the difference region closest to the point in the merge buffer. ++ ++@emph{In 3-file comparison sessions:} ++makes current the region closest to the point in buffer C. ++ ++With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C. ++ ++@item ! ++@kindex ! ++Recomputes the difference regions, bringing them up to date. This is often ++needed because it is common to do all sorts of editing during Ediff ++sessions, so after a while, the highlighted difference regions may no ++longer reflect the actual differences among the buffers. ++ ++@item * ++@kindex * ++Forces refinement of the current difference region, which highlights the exact ++words of disagreement among the buffers. With a negative prefix argument, ++unhighlights the current region. ++ ++Forceful refinement may be needed if Ediff encounters a difference region ++that is larger than @code{ediff-auto-refine-limit}. In this situation, ++Ediff doesn't do automatic refinement in order to improve response time. ++(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still ++works there. However, the only useful piece of information it can tell you ++is whether or not the difference regions disagree only in the amount of ++white space.) ++ ++This command is also useful when the highlighted fine differences are ++no longer current, due to user editing. ++ ++@item m ++@kindex m ++Displays the current Ediff session in a frame as wide as the physical ++display. This is useful when comparing files side-by-side. Typing `m' again ++restores the original size of the frame. ++ ++@item | ++@kindex | ++Toggles the horizontal/vertical split of the Ediff display. Horizontal ++split is convenient when it is possible to compare files ++side-by-side. If the frame in which files are displayed is too narrow ++and lines are cut off, typing @kbd{m} may help some. ++ ++@item @@ ++@kindex @@ ++Toggles auto-refinement of difference regions (i.e., automatic highlighting ++of the exact words that differ among the variants). Auto-refinement is ++turned off on devices where Emacs doesn't support highlighting. ++ ++On slow machines, it may be advantageous to turn auto-refinement off. The ++user can always forcefully refine specific difference regions by typing ++@kbd{*}. ++ ++@item h ++@kindex h ++Cycles between full highlighting, the mode where fine differences are not ++highlighted (but computed), and the mode where highlighting is done with ++@acronym{ASCII} strings. The latter is not really recommended, unless on a dumb TTY. ++ ++@item r ++@kindex r ++Restores the old contents of the region in the merge buffer. ++(If you copied a difference region from buffer A or B into the merge buffer ++using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the ++region in case you change your mind.) ++ ++This command is enabled in merge sessions only. ++ ++@item ra ++@kindex ra ++Restores the old contents of the current difference region in buffer A, ++which was previously saved when the user invoked one of these commands: ++@kbd{b}, @kbd{ba}, @kbd{ca}, which see. This command is enabled in ++comparison sessions only. ++@item rb ++@kindex rb ++Restores the old contents of the current difference region in buffer B, ++which was previously saved when the user invoked one of these commands: ++@kbd{a}, @kbd{ab}, @kbd{cb}, which see. This command is enabled in ++comparison sessions only. ++@item rc ++@kindex rc ++Restores the old contents of the current difference region in buffer C, ++which was previously saved when the user invoked one of these commands: ++@kbd{ac}, @kbd{bc}, which see. This command is enabled in 3-file ++comparison sessions only. ++ ++@item ## ++@kindex ## ++Tell Ediff to skip over regions that disagree among themselves only in the ++amount of white space and line breaks. ++ ++Even though such regions will be skipped over, you can still jump to any ++one of them by typing the region number and then `j'. Typing @kbd{##} ++again puts Ediff back in the original state. ++ ++@item #c ++@kindex #c ++@vindex ediff-ignore-case-option ++@vindex ediff-ignore-case-option3 ++@vindex ediff-ignore-case ++Toggle case sensitivity in the diff program. All diffs are recomputed. ++Case sensitivity is controlled by the variables ++@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, ++and @code{ediff-ignore-case}, which are explained elsewhere. ++ ++@item #h ++@itemx #f ++@kindex #f ++@kindex #h ++Ediff works hard to ameliorate the effects of boredom in the workplace... ++ ++Quite often differences are due to identical replacements (e.g., the word ++`foo' is replaced with the word `bar' everywhere). If the number of regions ++with such boring differences exceeds your tolerance threshold, you may be ++tempted to tell Ediff to skip these regions altogether (you will still be able ++to jump to them via the command @kbd{j}). The above commands, @kbd{#h} ++and @kbd{#f}, may well save your day! ++ ++@kbd{#h} prompts you to specify regular expressions for each ++variant. Difference regions where each variant's region matches the ++corresponding regular expression will be skipped from then on. (You can ++also tell Ediff to skip regions where at least one variant matches its ++regular expression.) ++ ++@kbd{#f} does dual job: it focuses on regions that match the corresponding ++regular expressions. All other regions will be skipped ++over. @xref{Selective Browsing}, for more. ++ ++@item A ++@kindex A ++Toggles the read-only property in buffer A. ++If file A is under version control and is checked in, it is checked out ++(with your permission). ++@item B ++@kindex B ++Toggles the read-only property in buffer B. ++If file B is under version control and is checked in, it is checked out. ++@item C ++@kindex C ++Toggles the read-only property in buffer C (in 3-file comparison sessions). ++If file C is under version control and is checked in, it is checked out. ++ ++@item ~ ++@kindex ~ ++Swaps the windows where buffers A and B are displayed. If you are comparing ++three buffers at once, then this command would rotate the windows among ++buffers A, B, and C. ++ ++@item i ++@kindex i ++Displays all kinds of useful data about the current Ediff session. ++@item D ++@kindex D ++Runs @code{ediff-custom-diff-program} on the variants and displays the ++buffer containing the output. This is useful when you must send the output ++to your Mom. ++ ++With a prefix argument, displays the plain @code{diff} output. ++@xref{Patch and Diff Programs}, for details. ++ ++@item R ++@kindex R ++Displays a list of currently active Ediff sessions---the Ediff Registry. ++You can then restart any of these sessions by either clicking on a session ++record or by putting the cursor over it and then typing the return key. ++ ++(Some poor souls leave so many active Ediff sessions around that they loose ++track of them completely... The `R' command is designed to save these ++people from the recently discovered Ediff Proficiency Syndrome.) ++ ++Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff ++Control Panel. If you don't have a control panel handy, type this in the ++minibuffer: @kbd{M-x eregistry}. @xref{Registry of Ediff Sessions}. ++ ++@item M ++@kindex M ++Shows the session group buffer that invoked the current Ediff session. ++@xref{Session Groups}, for more information on session groups. ++ ++@item z ++@kindex z ++Suspends the current Ediff session. (If you develop a condition known as ++Repetitive Ediff Injury---a serious but curable illness---you must change ++your current activity. This command tries hard to hide all Ediff-related ++buffers.) ++ ++The easiest way to resume a suspended Ediff session is through the registry ++of active sessions. @xref{Registry of Ediff Sessions}, for details. ++@item q ++@kindex q ++Terminates this Ediff session. With a prefix argument (e.g.,@kbd{1q}), asks ++if you also want to delete the buffers of the variants. ++Modified files and the results of merges are never deleted. ++ ++@item % ++@kindex % ++Toggles narrowing in Ediff buffers. Ediff buffers may be narrowed if you ++are comparing only parts of these buffers via the commands ++@code{ediff-windows-*} and @code{ediff-regions-*}, which see. ++ ++@item C-l ++@kindex C-l ++Restores the usual Ediff window setup. This is the quickest way to resume ++an Ediff session, but it works only if the control panel of that session is ++visible. ++ ++@item $$ ++@kindex $$ ++While merging with an ancestor file, Ediff is determined to reduce user's ++wear and tear by saving him and her much of unproductive, repetitive ++typing. If it notices that, say, file A's difference region is identical to ++the same difference region in the ancestor file, then the merge buffer will ++automatically get the difference region taken from buffer B. The rationale ++is that this difference region in buffer A is as old as that in the ++ancestor buffer, so the contents of that region in buffer B represents real ++change. ++ ++You may want to ignore such `obvious' merges and concentrate on difference ++regions where both files `clash' with the ancestor, since this means that ++two different people have been changing this region independently and they ++had different ideas on how to do this. ++ ++The above command does this for you by skipping the regions where only one ++of the variants clashes with the ancestor but the other variant agrees with ++it. Typing @kbd{$$} again undoes this setting. ++ ++@item $* ++@kindex $* ++When merging files with large number of differences, it is sometimes ++convenient to be able to skip the difference regions for which you already ++decided which variant is most appropriate. Typing @kbd{$*} will accomplish ++precisely this. ++ ++To be more precise, this toggles the check for whether the current merge is ++identical to its default setting, as originally decided by Ediff. For ++instance, if Ediff is merging according to the `combined' policy, then the ++merge region is skipped over if it is different from the combination of the ++regions in buffers A and B. (Warning: swapping buffers A and B will confuse ++things in this respect.) If the merge region is marked as `prefer-A' then ++this region will be skipped if it differs from the current difference ++region in buffer A, etc. ++ ++@item / ++@kindex / ++Displays the ancestor file during merges. ++@item & ++@kindex & ++In some situations, such as when one of the files agrees with the ancestor file ++on a difference region and the other doesn't, Ediff knows what to do: it copies ++the current difference region from the second buffer into the merge buffer. ++ ++In other cases, the right course of action is not that clearcut, and Ediff ++would use a default action. The above command changes the default action. ++The default action can be @samp{default-A} (choose the region from buffer ++A), @samp{default-B} (choose the region from buffer B), or @samp{combined} ++(combine the regions from the two buffers). ++@xref{Merging and diff3}, for further details. ++ ++The command @kbd{&} also affects the regions in the merge buffers that have ++@samp{default-A}, @samp{default-B}, or @samp{combined} status, provided ++they weren't changed with respect to the original. For instance, if such a ++region has the status @samp{default-A} then changing the default action to ++@samp{default-B} will also replace this merge-buffer's region with the ++corresponding region from buffer B. ++ ++@item s ++@kindex s ++Causes the merge window shrink to its minimum size, thereby exposing as much ++of the variant buffers as possible. Typing `s' again restores ++the original size of that window. ++ ++With a positive prefix argument, this command enlarges the merge window. ++E.g., @kbd{4s} increases the size of the window by about 4 lines, if ++possible. With a negative numeric argument, the size of the merge window ++shrinks by that many lines, if possible. Thus, @kbd{-s} shrinks the window ++by about 1 line and @kbd{-3s} by about 3 lines. ++ ++This command is intended only for temporary viewing; therefore, Ediff ++restores window C to its original size whenever it makes any other change ++in the window configuration. However, redisplaying (@kbd{C-l}) or jumping ++to another difference does not affect window C's size. ++ ++The split between the merge window and the variant windows is controlled by ++the variable @code{ediff-merge-window-share}, which see. ++ ++@item + ++@kindex + ++Combines the difference regions from buffers A and B and copies the ++result into the merge buffer. @xref{Merging and diff3}, and the ++variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}. ++ ++ ++@item = ++@kindex = ++You may run into situations when a large chunk of text in one file has been ++edited and then moved to a different place in another file. In such a case, ++these two chunks of text are unlikely to belong to the same difference ++region, so the refinement feature of Ediff will not be able to tell you ++what exactly differs inside these chunks. Since eyeballing large pieces of ++text is contrary to human nature, Ediff has a special command to help ++reduce the risk of developing a cataract. ++ ++In other situations, the currently highlighted region might be big and you ++might want to reconcile of them interactively. ++ ++All of this can be done with the above command, @kbd{=}, which ++compares regions within Ediff buffers. Typing @kbd{=} creates a ++child Ediff session for comparing regions in buffers A, B, or ++C as follows. ++ ++First, you will be asked whether you want to compare the fine differences ++between the currently highlighted buffers on a word-by-word basis. If you ++accept, a child Ediff session will start using the currently highlighted ++regions. Ediff will let you step over the differences word-wise. ++ ++If you reject the offer, you will be asked to select regions of your choice. ++ ++@emph{If you are comparing 2 files or buffers:} ++Ediff will ask you to select regions in buffers A and B. ++ ++@emph{If you are comparing 3 files or buffers simultaneously:} Ediff will ++ask you to choose buffers and then select regions inside those buffers. ++ ++@emph{If you are merging files or buffers (with or without ancestor):} ++Ediff will ask you to choose which buffer (A or B) to compare with the ++merge buffer and then select regions in those buffers. ++ ++@end table ++ ++@node Other Session Commands,,Quick Help Commands,Session Commands ++@section Other Session Commands ++ ++The following commands can be invoked from within any Ediff session, ++although some of them are not bound to a key. ++ ++@table @code ++@item eregistry ++@itemx ediff-show-registry ++@findex eregistry ++@findex ediff-show-registry ++This command brings up the registry of active Ediff sessions. Ediff ++registry is a device that can be used to resume any active Ediff session ++(which may have been postponed because the user switched to some other ++activity). This command is also useful for switching between multiple ++active Ediff sessions that are run at the same time. The function ++@code{eregistry} is an alias for @code{ediff-show-registry}. ++@xref{Registry of Ediff Sessions}, for more information on this registry. ++ ++@item ediff-toggle-multiframe ++@findex ediff-toggle-multiframe ++Changes the display from the multi-frame mode (where the quick help window ++is in a separate frame) to the single-frame mode (where all Ediff buffers ++share the same frame), and vice versa. See ++@code{ediff-window-setup-function} for details on how to make either of ++these modes the default one. ++ ++This function can also be invoked from the Menubar. However, in some ++cases, the change will take place only after you execute one of the Ediff ++commands, such as going to the next difference or redisplaying. ++ ++@item ediff-toggle-use-toolbar ++@findex ediff-toggle-use-toolbar ++Available in XEmacs only. The Ediff toolbar provides quick access to some ++of the common Ediff functions. This function toggles the display of the ++toolbar. If invoked from the menubar, the function may take sometimes ++effect only after you execute an Ediff command, such as going to the next ++difference. ++ ++@item ediff-use-toolbar-p ++@vindex ediff-use-toolbar-p ++The use of the toolbar can also be specified via the variable ++@code{ediff-use-toolbar-p} (default is @code{t}). This variable can be set ++only in @file{.emacs} --- do @strong{not} change it interactively. Use the ++function @code{ediff-toggle-use-toolbar} instead. ++ ++@item ediff-revert-buffers-then-recompute-diffs ++@findex ediff-revert-buffers-then-recompute-diffs ++This command reverts the buffers you are comparing and recomputes their ++differences. It is useful when, after making changes, you decided to ++make a fresh start, or if at some point you changed the files being ++compared but want to discard any changes to comparison buffers that were ++done since then. ++ ++This command normally asks for confirmation before reverting files. ++With a prefix argument, it reverts files without asking. ++ ++ ++@item ediff-profile ++@findex ediff-profile ++Ediff has an admittedly primitive (but useful) facility for profiling ++Ediff's commands. It is meant for Ediff maintenance---specifically, for ++making it run faster. The function @code{ediff-profile} toggles ++profiling of ediff commands. ++@end table ++ ++@node Registry of Ediff Sessions, Session Groups, Session Commands, Top ++@chapter Registry of Ediff Sessions ++ ++Ediff maintains a registry of all its invocations that are ++still @emph{active}. This feature is very convenient for switching among ++active Ediff sessions or for quickly restarting a suspended Ediff session. ++ ++The focal point of this activity is a buffer ++called @emph{*Ediff Registry*}. You can display this buffer by typing ++@kbd{R} in any Ediff Control Buffer or Session Group Buffer ++(@pxref{Session Groups}), or by typing ++@kbd{M-x eregistry} into the Minibuffer. ++The latter would be the fastest way to bring up the registry ++buffer if no control or group buffer is displayed in any of the visible ++Emacs windows. ++If you are in a habit of running multiple long Ediff sessions and often need to ++suspend, resume, or switch between them, it may be a good idea to have the ++registry buffer permanently displayed in a separate, dedicated window. ++ ++The registry buffer has several convenient key bindings. ++For instance, clicking mouse button 2 or typing ++@kbd{RET} or @kbd{v} over any session record resumes that session. ++Session records in the registry buffer provide a fairly complete ++description of each session, so it is usually easy to identify the right ++session to resume. ++ ++Other useful commands are bound to @kbd{SPC} (next registry record) ++and @kbd{DEL} (previous registry record). There are other commands as well, ++but you don't need to memorize them, since they are listed at the top of ++the registry buffer. ++ ++@node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top ++@chapter Session Groups ++ ++Several major entries of Ediff perform comparison and merging on ++directories. On entering @code{ediff-directories}, ++@code{ediff-directories3}, ++@code{ediff-merge-directories}, ++@code{ediff-merge-directories-with-ancestor}, ++@code{ediff-directory-revisions}, ++@code{ediff-merge-directory-revisions}, or ++@code{ediff-merge-directory-revisions-with-ancestor}, ++the user is presented with a ++Dired-like buffer that lists files common to the directories involved along ++with their sizes. (The list of common files can be further filtered through ++a regular expression, which the user is prompted for.) We call this buffer ++@emph{Session Group Panel} because all Ediff sessions associated with the ++listed files will have this buffer as a common focal point. ++ ++Clicking button 2 or typing @kbd{RET} or @kbd{v} over a ++record describing files invokes Ediff in the appropriate mode on these ++files. You can come back to the session group buffer associated with a ++particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of ++that invocation. ++ ++Many commands are available in the session group buffer; some are ++applicable only to certain types of work. The relevant commands are always ++listed at the top of each session group buffer, so there is no need to ++memorize them. ++ ++In directory comparison or merging, a session group panel displays only the ++files common to all directories involved. The differences are kept in a ++separate @emph{directory difference buffer} and are conveniently displayed ++by typing @kbd{D} to the corresponding session group panel. Thus, as an ++added benefit, Ediff can be used to compare the contents of up to three ++directories. ++ ++@cindex Directory difference buffer ++Sometimes it is desirable to copy some files from one directory to another ++without exiting Ediff. The @emph{directory difference buffer}, which is ++displayed by typing @kbd{D} as discussed above, can be used for this ++purpose. If a file is, say, in Ediff's Directory A, but is missing in ++Ediff's Directory B (Ediff will refuse to override existing files), then ++typing @kbd{C} or clicking mouse button 2 over that file (which must be ++displayed in directory difference buffer) will copy that file from ++Directory A to Directory B. ++ ++Session records in session group panels are also marked with @kbd{+}, for ++active sessions, and with @kbd{-}, for finished sessions. ++ ++Sometimes, it is convenient to exclude certain sessions from a group. ++Usually this happens when the user doesn't intend to run Ediff of certain ++files in the group, and the corresponding session records just add clutter ++to the session group buffer. To help alleviate this problem, the user can ++type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to ++actually hide the marked sessions. There actions are reversible: with a ++prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x} ++brings the hidden sessions into the view (@kbd{x} doesn't unmark them, ++though, so the user has to explicitly unmark the sessions of interest). ++ ++Group sessions also understand the command @kbd{m}, which marks sessions ++for future operations (other than hiding) on a group of sessions. At present, ++the only such group-level operation is the creation of a multi-file patch. ++ ++@vindex ediff-autostore-merges ++For group sessions created to merge files, Ediff can store all merges ++automatically in a directory. The user is asked to specify such directory ++if the value of @code{ediff-autostore-merges} is non-@code{nil}. If the value is ++@code{nil}, nothing is done to the merge buffers---it will be the user's ++responsibility to save them. If the value is @code{t}, the user will be ++asked where to save the merge buffers in all merge jobs, even those that do ++not originate from a session group. It the value is neither @code{nil} nor ++@code{t}, the merge buffer is saved @emph{only} if this merge session was ++invoked from a session group. This behavior is implemented in the function ++@code{ediff-maybe-save-and-delete-merge}, which is a hook in ++@code{ediff-quit-merge-hook}. The user can supply a different hook, if ++necessary. ++ ++The variable @code{ediff-autostore-merges} is buffer-local, so it can be ++set on a per-buffer basis. Therefore, use @code{setq-default} to change ++this variable globally. ++ ++@cindex Multi-file patches ++A multi-file patch is a concatenated output of several runs of the Unix ++@code{diff} command (some versions of @code{diff} let you create a ++multi-file patch in just one run). Ediff facilitates creation of ++multi-file patches as follows. If you are in a session group buffer ++created in response to @code{ediff-directories} or ++@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the ++desired Ediff sessions and then type @kbd{P} to create a ++multi-file patch of those marked sessions. ++Ediff will then display a buffer containing the patch. ++The patch is generated by invoking @code{diff} on all marked individual ++sessions (represented by files) and session groups (represented by ++directories). Ediff will also recursively descend into any @emph{unmarked} ++session group and will search for marked sessions there. In this way, you ++can create multi-file patches that span file subtrees that grow out of ++any given directory. ++ ++In an @code{ediff-directories} session, it is enough to just mark the ++requisite sessions. In @code{ediff-directory-revisions} revisions, the ++marked sessions must also be active, or else Ediff will refuse to produce a ++multi-file patch. This is because, in the latter-style sessions, there are ++many ways to create diff output, and it is easier to handle by running ++Ediff on the inactive sessions. ++ ++Last, but not least, by typing @kbd{==}, you can quickly find out which ++sessions have identical entries, so you won't have to run Ediff on those ++sessions. This, however, works only on local, uncompressed files. ++For compressed or remote files, this command won't report anything. ++Likewise, you can use @kbd{=h} to mark sessions with identical entries ++for hiding or, with @kbd{=m}, for further operations. ++ ++The comparison operations @kbd{==}, @kbd{=h}, and @kbd{=m} can recurse into ++subdirectories to see if they have identical contents (so the user will not ++need to descend into those subdirectories manually). These commands ask the ++user whether or not to do a recursive descent. ++ ++ ++ ++@node Remote and Compressed Files, Customization, Session Groups, Top ++@chapter Remote and Compressed Files ++ ++Ediff works with remote, compressed, and encrypted files. Ediff ++supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el} ++and @file{crypt++.el}, but it may work with other similar packages as ++well. This means that you can compare files residing on another ++machine, or you can apply a patch to a file on another machine. Even ++the patch itself can be a remote file! ++ ++When patching compressed or remote files, Ediff does not rename the source ++file (unlike what the @code{patch} utility would usually do). Instead, the ++source file retains its name and the result of applying the patch is placed ++in a temporary file that has the suffix @file{_patched} attached. ++Generally, this applies to files that are handled using black magic, such ++as special file handlers (ange-ftp and some compression and encryption ++packages also use this method). ++ ++Regular files are treated by the @code{patch} utility in the usual manner, ++i.e., the original is renamed into @file{source-name.orig} and the result ++of the patch is placed into the file source-name (@file{_orig} is used ++on systems like DOS, etc.) ++ ++@node Customization, Credits, Remote and Compressed Files, Top ++@chapter Customization ++ ++Ediff has a rather self-explanatory interface, and in most cases you ++won't need to change anything. However, should the need arise, there are ++extensive facilities for changing the default behavior. ++ ++Most of the customization can be done by setting various variables in the ++@file{.emacs} file. Some customization (mostly window-related ++customization and faces) can be done by putting appropriate lines in ++@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use. ++ ++With respect to the latter, please note that the X resource ++for Ediff customization is `Ediff', @emph{not} `emacs'. ++@xref{Window and Frame Configuration}, ++@xref{Highlighting Difference Regions}, for further details. Please also ++refer to Emacs manual for the information on how to set Emacs X resources. ++ ++@menu ++* Hooks:: Customization via the hooks. ++* Quick Help Customization:: How to customize Ediff's quick help feature. ++* Window and Frame Configuration:: Controlling the way Ediff displays things. ++* Selective Browsing:: Advanced browsing through difference regions. ++* Highlighting Difference Regions:: Controlling highlighting. ++* Narrowing:: Comparing regions, windows, etc. ++* Refinement of Difference Regions:: How to control the refinement process. ++* Patch and Diff Programs:: Changing the utilities that compute differences ++ and apply patches. ++* Merging and diff3:: How to customize Ediff in its Merge Mode. ++* Support for Version Control:: Changing the version control package. ++ You are not likely to do that. ++* Customizing the Mode Line:: Changing the look of the mode line in Ediff. ++* Miscellaneous:: Other customization. ++* Notes on Heavy-duty Customization:: Customization for the gurus. ++@end menu ++ ++@node Hooks, Quick Help Customization, Customization, Customization ++@section Hooks ++ ++The bulk of customization can be done via the following hooks: ++ ++@table @code ++@item ediff-load-hook ++@vindex ediff-load-hook ++This hook can be used to change defaults after Ediff is loaded. ++ ++@item ediff-before-setup-hook ++@vindex ediff-before-setup-hook ++Hook that is run just before Ediff rearranges windows to its liking. ++Can be used to save windows configuration. ++ ++@item ediff-keymap-setup-hook ++@vindex ediff-keymap-setup-hook ++@vindex ediff-mode-map ++This hook can be used to alter bindings in Ediff's keymap, ++@code{ediff-mode-map}. These hooks are ++run right after the default bindings are set but before ++@code{ediff-load-hook}. The regular user needs not be concerned with this ++hook---it is provided for implementors of other Emacs packages built on top ++of Ediff. ++ ++@item ediff-before-setup-windows-hook ++@itemx ediff-after-setup-windows-hook ++@vindex ediff-before-setup-windows-hook ++@vindex ediff-after-setup-windows-hook ++These two hooks are called before and after Ediff sets up its window ++configuration. These hooks are run each time Ediff rearranges windows to ++its liking. This happens whenever it detects that the user changed the ++windows setup. ++ ++@item ediff-suspend-hook ++@itemx ediff-quit-hook ++@vindex ediff-suspend-hook ++@vindex ediff-quit-hook ++These two hooks are run when you suspend or quit Ediff. They can be ++used to set desired window configurations, delete files Ediff didn't ++want to clean up after exiting, etc. ++ ++By default, @code{ediff-quit-hook} holds one hook function, ++@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in ++most cases. You probably won't want to change it, but you might ++want to add other hook functions. ++ ++Keep in mind that hooks executing before @code{ediff-cleanup-mess} start ++in @code{ediff-control-buffer;} they should also leave ++@code{ediff-control-buffer} as the current buffer when they finish. ++Hooks that are executed after @code{ediff-cleanup-mess} should expect ++the current buffer be either buffer A or buffer B. ++@code{ediff-cleanup-mess} doesn't kill the buffers being compared or ++merged (see @code{ediff-cleanup-hook}, below). ++ ++@item ediff-cleanup-hook ++@vindex ediff-cleanup-hook ++This hook is run just before @code{ediff-quit-hook}. This is a good ++place to do various cleanups, such as deleting the variant buffers. ++Ediff provides a function, @code{ediff-janitor}, as one such possible ++hook, which you can add to @code{ediff-cleanup-hook} with ++@code{add-hooks}. ++ ++@findex ediff-janitor ++This function kills buffers A, B, and, possibly, C, if these buffers aren't ++modified. In merge jobs, buffer C is never deleted. However, the side ++effect of using this function is that you may not be able to compare the ++same buffer in two separate Ediff sessions: quitting one of them will ++delete this buffer in another session as well. ++ ++@item ediff-quit-merge-hook ++@vindex ediff-quit-merge-hook ++@vindex ediff-autostore-merges ++@findex ediff-maybe-save-and-delete-merge ++This hook is called when Ediff quits a merge job. By default, the value is ++@code{ediff-maybe-save-and-delete-merge}, which is a function that attempts ++to save the merge buffer according to the value of ++@code{ediff-autostore-merges}, as described later. ++ ++@item ediff-before-setup-control-frame-hook ++@itemx ediff-after-setup-control-frame-hook ++@vindex ediff-before-setup-control-frame-hook ++@vindex ediff-after-setup-control-frame-hook ++These two hooks run before and after Ediff sets up the control frame. ++They can be used to relocate Ediff control frame when Ediff runs in a ++multiframe mode (i.e., when the control buffer is in its own dedicated ++frame). Be aware that many variables that drive Ediff are local to ++Ediff Control Panel (@code{ediff-control-buffer}), which requires ++special care in writing these hooks. Take a look at ++@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to ++see what's involved. ++ ++@item ediff-startup-hook ++@vindex ediff-startup-hook ++This hook is run at the end of Ediff startup. ++ ++@item ediff-select-hook ++@vindex ediff-select-hook ++This hook is run after Ediff selects the next difference region. ++ ++@item ediff-unselect-hook ++@vindex ediff-unselect-hook ++This hook is run after Ediff unselects the current difference region. ++ ++@item ediff-prepare-buffer-hook ++@vindex ediff-prepare-buffer-hook ++This hook is run for each Ediff buffer (A, B, C) right after the buffer ++is arranged. ++ ++@item ediff-display-help-hook ++@vindex ediff-display-help-hook ++Ediff runs this hook each time after setting up the help message. It ++can be used to alter the help message for custom packages that run on ++top of Ediff. ++ ++@item ediff-mode-hook ++@vindex ediff-mode-hook ++This hook is run just after Ediff mode is set up in the control ++buffer. This is done before any Ediff window is created. You can use it to ++set local variables that alter the look of the display. ++ ++@item ediff-registry-setup-hook ++@vindex ediff-registry-setup-hook ++Hooks run after setting up the registry for all active Ediff session. ++@xref{Session Groups}, for details. ++@item ediff-before-session-group-setup-hook ++@vindex ediff-before-session-group-setup-hook ++Hooks run before setting up a control panel for a group of related Ediff ++sessions. Can be used, for example, to save window configuration to restore ++later. ++@item ediff-after-session-group-setup-hook ++@vindex ediff-after-session-group-setup-hook ++Hooks run after setting up a control panel for a group of related Ediff ++sessions. @xref{Session Groups}, for details. ++@item ediff-quit-session-group-hook ++@vindex ediff-quit-session-group-hook ++Hooks run just before exiting a session group. ++@item ediff-meta-buffer-keymap-setup-hook ++@vindex ediff-meta-buffer-keymap-setup-hook ++@vindex ediff-meta-buffer-map ++Hooks run just after setting up the @code{ediff-meta-buffer-map} --- the ++map that controls key bindings in the meta buffer. Since ++@code{ediff-meta-buffer-map} is a local variable, you can set different ++bindings for different kinds of meta buffers. ++@end table ++ ++@node Quick Help Customization, Window and Frame Configuration, Hooks, Customization ++@section Quick Help Customization ++@vindex ediff-use-long-help-message ++@vindex ediff-control-buffer ++@vindex ediff-startup-hook ++@vindex ediff-help-message ++ ++Ediff provides quick help using its control panel window. Since this window ++takes a fair share of the screen real estate, you can toggle it off by ++typing @kbd{?}. The control window will then shrink to just one line and a ++mode line, displaying a short help message. ++ ++The variable @code{ediff-use-long-help-message} tells Ediff whether ++you use the short message or the long one. By default, it ++is set to @code{nil}, meaning that the short message is used. ++Set this to @code{t}, if you want Ediff to use the long ++message by default. This property can always be changed interactively, by ++typing @kbd{?} into Ediff Control Buffer. ++ ++If you want to change the appearance of the help message on a per-buffer ++basis, you must use @code{ediff-startup-hook} to change the value of ++the variable @code{ediff-help-message}, which is local to ++@code{ediff-control-buffer}. ++ ++@node Window and Frame Configuration, Selective Browsing, Quick Help Customization, Customization ++@section Window and Frame Configuration ++ ++On a non-windowing display, Ediff sets things up in one frame, splitting ++it between a small control window and the windows for buffers A, B, and C. ++The split between these windows can be horizontal or ++vertical, which can be changed interactively by typing @kbd{|} while the ++cursor is in the control window. ++ ++On a window display, Ediff sets up a dedicated frame for Ediff Control ++Panel and then it chooses windows as follows: If one of the buffers ++is invisible, it is displayed in the currently selected frame. If ++a buffer is visible, it is displayed in the frame where it is visible. ++If, according to the above criteria, the two buffers fall into the same ++frame, then so be it---the frame will be shared by the two. The same ++algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p} ++(@code{ediff-previous-difference}), @kbd{n} ++(@code{ediff-next-difference}), etc. ++ ++The above behavior also depends on whether the current frame is splittable, ++dedicated, etc. Unfortunately, the margin of this book is too narrow to ++present the details of this remarkable algorithm. ++ ++The upshot of all this is that you can compare buffers in one frame or ++in different frames. The former is done by default, while the latter can ++be achieved by arranging buffers A, B (and C, if applicable) to be seen in ++different frames. Ediff respects these arrangements, automatically ++adapting itself to the multi-frame mode. ++ ++Ediff uses the following variables to set up its control panel ++(a.k.a.@: control buffer, a.k.a.@: quick help window): ++ ++@table @code ++@item ediff-control-frame-parameters ++@vindex ediff-control-frame-parameters ++You can change or augment this variable including the font, color, ++etc. The X resource name of Ediff Control Panel frames is @samp{Ediff}. Under ++X-windows, you can use this name to set up preferences in your ++@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in ++use. Usually this is preferable to changing ++@code{ediff-control-frame-parameters} directly. For instance, you can ++specify in @file{~/.Xdefaults} the color of the control frame ++using the resource @samp{Ediff*background}. ++ ++In general, any X resource pertaining the control frame can be reached ++via the prefix @code{Ediff*}. ++ ++@item ediff-control-frame-position-function ++@vindex ediff-control-frame-position-function ++The preferred way of specifying the position of the control frame is by ++setting the variable @code{ediff-control-frame-position-function} to an ++appropriate function. ++The default value of this variable is ++@code{ediff-make-frame-position}. This function places the control frame in ++the vicinity of the North-East corner of the frame displaying buffer A. ++ ++@findex ediff-make-frame-position ++@end table ++ ++The following variables can be used to adjust the location produced by ++@code{ediff-make-frame-position} and for related customization. ++ ++@table @code ++@item ediff-narrow-control-frame-leftward-shift ++@vindex ediff-narrow-control-frame-leftward-shift ++Specifies the number of characters for shifting ++the control frame from the rightmost edge of frame A when the control ++frame is displayed as a small window. ++ ++@item ediff-wide-control-frame-rightward-shift ++@vindex ediff-wide-control-frame-rightward-shift ++Specifies the rightward shift of the control frame ++from the left edge of frame A when the control frame shows the full ++menu of options. ++ ++@item ediff-control-frame-upward-shift ++@vindex ediff-control-frame-upward-shift ++Specifies the number of pixels for the upward shift ++of the control frame. ++ ++@item ediff-prefer-iconified-control-frame ++@vindex ediff-prefer-iconified-control-frame ++If this variable is @code{t}, the control frame becomes iconified ++automatically when you toggle the quick help message off. This saves ++valuable real estate on the screen. Toggling help back will deiconify ++the control frame. ++ ++To start Ediff with an iconified Control Panel, you should set this ++variable to @code{t} and @code{ediff-prefer-long-help-message} to ++@code{nil} (@pxref{Quick Help Customization}). This behavior is useful ++only if icons are allowed to accept keyboard input (which depends on the ++window manager and other factors). ++@end table ++ ++@findex ediff-setup-windows ++To make more creative changes in the way Ediff sets up windows, you can ++rewrite the function @code{ediff-setup-windows}. However, we believe ++that detaching Ediff Control Panel from the rest and making it into a ++separate frame offers an important opportunity by allowing you to ++iconify that frame. The icon will usually accept all of the Ediff ++commands, but will free up valuable real estate on your screen (this may ++depend on your window manager, though). ++ ++The following variable controls how windows are set up: ++ ++@table @code ++@item ediff-window-setup-function ++@vindex ediff-window-setup-function ++The multiframe setup is done by the ++@code{ediff-setup-windows-multiframe} function, which is the default on ++windowing displays. The plain setup, one where all windows are always ++in one frame, is done by @code{ediff-setup-windows-plain}, which is the ++default on a non-windowing display (or in an xterm window). In fact, ++under Emacs, you can switch freely between these two setups by executing ++the command @code{ediff-toggle-multiframe} using the Minibuffer of the ++Menubar. ++@findex ediff-setup-windows-multiframe ++@findex ediff-setup-windows-plain ++@findex ediff-toggle-multiframe ++ ++If you don't like any of these setups, write your own function. See the ++documentation for @code{ediff-window-setup-function} for the basic ++guidelines. However, writing window setups is not easy, so you should ++first take a close look at @code{ediff-setup-windows-plain} and ++@code{ediff-setup-windows-multiframe}. ++@end table ++ ++You can run multiple Ediff sessions at once, by invoking Ediff several ++times without exiting previous Ediff sessions. Different sessions ++may even operate on the same pair of files. ++ ++Each session has its own Ediff Control Panel and all the regarding a ++particular session is local to the associated control panel buffer. You ++can switch between sessions by suspending one session and then switching ++to another control panel. (Different control panel buffers are ++distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.) ++ ++@node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization ++@section Selective Browsing ++ ++Sometimes it is convenient to be able to step through only some difference ++regions, those that match certain regular expressions, and to ignore all ++others. On other occasions, you may want to ignore difference regions that ++match some regular expressions, and to look only at the rest. ++ ++The commands @kbd{#f} and @kbd{#h} let you do precisely this. ++ ++Typing @kbd{#f} lets you specify regular expressions that match difference ++regions you want to focus on. ++We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and ++@var{regexp-C}. ++Ediff will then start stepping through only those difference regions ++where the region in buffer A matches @var{regexp-A} and/or the region in ++buffer B matches @var{regexp-B}, etc. Whether `and' or `or' will be used ++depends on how you respond to a question. ++ ++When scanning difference regions for the aforesaid regular expressions, ++Ediff narrows the buffers to those regions. This means that you can use ++the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end ++of the difference regions. ++ ++On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting ++regions. That is, if a difference region in buffer A matches ++@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B} ++and (if applicable) buffer C's region matches @var{regexp-C}, then the ++region will be ignored by the commands @kbd{n}/@key{SPC} ++(@code{ediff-next-difference}) and @kbd{p}/@key{DEL} ++(@code{ediff-previous-difference}) commands. ++ ++Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off. ++ ++Note that selective browsing affects only @code{ediff-next-difference} ++and @code{ediff-previous-difference}, i.e., the commands ++@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}. @kbd{#f} and @kbd{#h} do not ++change the position of the point in the buffers. And you can still jump ++directly (using @kbd{j}) to any numbered ++difference. ++ ++Users can supply their own functions to specify how Ediff should do ++selective browsing. To change the default Ediff function, add a function to ++@code{ediff-load-hook} which will do the following assignments: ++ ++@example ++(setq ediff-hide-regexp-matches-function 'your-hide-function) ++(setq ediff-focus-on-regexp-matches-function 'your-focus-function) ++@end example ++ ++@strong{Useful hint}: To specify a regexp that matches everything, don't ++simply type @key{RET} in response to a prompt. Typing @key{RET} tells Ediff ++to accept the default value, which may not be what you want. Instead, you ++should enter something like @key{^} or @key{$}. These match every ++line. ++ ++You can use the status command, @kbd{i}, to find out whether ++selective browsing is currently in effect. ++ ++The regular expressions you specified are kept in the local variables ++@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B}, ++@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A}, ++@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}. Their default value ++is the empty string (i.e., nothing is hidden or focused on). To change the ++default, set these variables in @file{.emacs} using @code{setq-default}. ++ ++In addition to the ability to ignore regions that match regular ++expressions, Ediff can be ordered to start skipping over certain ++``uninteresting'' difference regions. This is controlled by the following ++variable: ++ ++@table @code ++@item ediff-ignore-similar-regions ++@vindex ediff-ignore-similar-regions ++If @code{t}, causes Ediff to skip over "uninteresting" difference regions, ++which are the regions where the variants differ only in the amount of the ++white space and newlines. This feature can be toggled on/off interactively, ++via the command @kbd{##}. ++@end table ++ ++@strong{Please note:} in order for this feature to work, auto-refining of ++difference regions must be on, since otherwise Ediff won't know if there ++are fine differences between regions. On devices where Emacs can display ++faces, auto-refining is a default, but it is not turned on by default on ++text-only terminals. In that case, you must explicitly turn auto-refining ++on (such as, by typing @kbd{@@}). ++ ++@strong{Reassurance:} If many such uninteresting regions appear in a row, ++Ediff may take a long time to skip over them because it has to compute fine ++differences of all intermediate regions. This delay does not indicate any ++problem. ++ ++@vindex ediff-ignore-case-option ++@vindex ediff-ignore-case-option3 ++@vindex ediff-ignore-case ++Finally, Ediff can be told to ignore the case of the letters. This behavior ++can be toggled with @kbd{#c} and it is controlled with three variables: ++@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, and ++@code{ediff-ignore-case}. ++ ++The variable @code{ediff-ignore-case-option} specifies the option to pass ++to the diff program for comparing two files or buffers. For GNU ++@code{diff}, this option is @code{"-i"}. The variable ++@code{ediff-ignore-case-option3} specifies the option to pass to the ++@code{diff3} program in order to make it case-insensitive. GNU @code{diff3} ++does not have such an option, so when merging or comparing three files with ++this program, ignoring the letter case is not supported. ++ ++The variable @code{ediff-ignore-case} controls whether Ediff starts out by ++ignoring letter case or not. It can be set in @file{.emacs} using ++@code{setq-default}. ++ ++When case sensitivity is toggled, all difference ++regions are recomputed. ++ ++@node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization ++@section Highlighting Difference Regions ++ ++The following variables control the way Ediff highlights difference ++regions: ++ ++@table @code ++@item ediff-before-flag-bol ++@itemx ediff-after-flag-eol ++@itemx ediff-before-flag-mol ++@itemx ediff-after-flag-mol ++@vindex ediff-before-flag-bol ++@vindex ediff-after-flag-eol ++@vindex ediff-before-flag-mol ++@vindex ediff-after-flag-mol ++These variables hold strings that Ediff uses to mark the beginning and the ++end of the differences found in files A, B, and C on devices where Emacs ++cannot display faces. Ediff uses different flags to highlight regions that ++begin/end at the beginning/end of a line or in a middle of a line. ++ ++@item ediff-current-diff-face-A ++@itemx ediff-current-diff-face-B ++@itemx ediff-current-diff-face-C ++@vindex ediff-current-diff-face-A ++@vindex ediff-current-diff-face-B ++@vindex ediff-current-diff-face-C ++Ediff uses these faces to highlight current differences on devices where ++Emacs can display faces. These and subsequently described faces can be set ++either in @file{.emacs} or in @file{.Xdefaults}. The X resource for Ediff ++is @samp{Ediff}, @emph{not} @samp{emacs}. Please refer to Emacs manual for ++the information on how to set X resources. ++@item ediff-fine-diff-face-A ++@itemx ediff-fine-diff-face-B ++@itemx ediff-fine-diff-face-C ++@vindex ediff-fine-diff-face-A ++@vindex ediff-fine-diff-face-B ++@vindex ediff-fine-diff-face-C ++Ediff uses these faces to show the fine differences between the current ++differences regions in buffers A, B, and C, respectively. ++ ++@item ediff-even-diff-face-A ++@itemx ediff-even-diff-face-B ++@itemx ediff-even-diff-face-C ++@itemx ediff-odd-diff-face-A ++@itemx ediff-odd-diff-face-B ++@itemx ediff-odd-diff-face-C ++@vindex ediff-even-diff-face-A ++@vindex ediff-even-diff-face-B ++@vindex ediff-even-diff-face-C ++@vindex ediff-odd-diff-face-A ++@vindex ediff-odd-diff-face-B ++@vindex ediff-odd-diff-face-C ++Non-current difference regions are displayed using these alternating ++faces. The odd and the even faces are actually identical on monochrome ++displays, because without colors options are limited. ++So, Ediff uses italics to highlight non-current differences. ++ ++@item ediff-force-faces ++@vindex ediff-force-faces ++Ediff generally can detect when Emacs is running on a device where it can ++use highlighting with faces. However, if it fails to determine that faces ++can be used, the user can set this variable to @code{t} to make sure that ++Ediff uses faces to highlight differences. ++ ++@item ediff-highlight-all-diffs ++@vindex ediff-highlight-all-diffs ++Indicates whether---on a windowing display---Ediff should highlight ++differences using inserted strings (as on text-only terminals) or using ++colors and highlighting. Normally, Ediff highlights all differences, but ++the selected difference is highlighted more visibly. One can cycle through ++various modes of highlighting by typing @kbd{h}. By default, Ediff starts ++in the mode where all difference regions are highlighted. If you prefer to ++start in the mode where unselected differences are not highlighted, you ++should set @code{ediff-highlight-all-diffs} to @code{nil}. Type @kbd{h} to ++restore highlighting for all differences. ++ ++Ediff lets you switch between the two modes of highlighting. That is, ++you can switch interactively from highlighting using faces to ++highlighting using string flags, and back. Of course, switching has ++effect only under a windowing system. On a text-only terminal or in an ++xterm window, the only available option is highlighting with strings. ++@end table ++ ++@noindent ++If you want to change the default settings for @code{ediff-force-faces} and ++@code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff is ++loaded. ++ ++You can also change the defaults for the faces used to highlight the ++difference regions. There are two ways to do this. The simplest and the ++preferred way is to use the customization widget accessible from the ++menubar. Ediff's customization group is located under "Tools", which in ++turn is under "Programming". The faces that are used to highlight ++difference regions are located in the "Highlighting" subgroup of the Ediff ++customization group. ++ ++The second, much more arcane, method to change default faces is to include ++some Lisp code in @file{~/.emacs}. For instance, ++ ++@example ++(setq ediff-current-diff-face-A ++ (copy-face 'bold-italic 'ediff-current-diff-face-A)) ++@end example ++ ++@noindent ++would use the pre-defined face @code{bold-italic} to highlight the current ++difference region in buffer A (this face is not a good choice, by the way). ++ ++If you are unhappy with just @emph{some} of the aspects of the default ++faces, you can modify them when Ediff is being loaded using ++@code{ediff-load-hook}. For instance: ++ ++@smallexample ++(add-hook 'ediff-load-hook ++ (lambda () ++ (set-face-foreground ++ ediff-current-diff-face-B "blue") ++ (set-face-background ++ ediff-current-diff-face-B "red") ++ (make-face-italic ++ ediff-current-diff-face-B))) ++@end smallexample ++ ++@strong{Please note:} to set Ediff's faces, use only @code{copy-face} ++or @code{set/make-face-@dots{}} as shown above. Emacs' low-level ++face-manipulation functions should be avoided. ++ ++@node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization ++@section Narrowing ++ ++If buffers being compared are narrowed at the time of invocation of ++Ediff, @code{ediff-buffers} will preserve the narrowing range. However, ++if @code{ediff-files} is invoked on the files visited by these buffers, ++that would widen the buffers, since this command is defined to compare the ++entire files. ++ ++Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, or ++the corresponding @samp{-wordwise} commands, narrows the variants to the ++particular regions being compared. The original accessible ranges are ++restored when you quit Ediff. During the command, you can toggle this ++narrowing on and off with the @kbd{%} command. ++ ++These two variables control this narrowing behavior: ++ ++@table @code ++@item ediff-start-narrowed ++@vindex ediff-start-narrowed ++If @code{t}, Ediff narrows the display to the appropriate range when it ++is invoked with an @samp{ediff-regions@dots{}} or ++@samp{ediff-windows@dots{}} command. If @code{nil}, these commands do ++not automatically narrow, but you can still toggle narrowing on and off ++by typing @kbd{%}. ++ ++@item ediff-quit-widened ++@vindex ediff-quit-widened ++Controls whether on quitting Ediff should restore the accessible range ++that existed before the current invocation. ++@end table ++ ++@node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization ++@section Refinement of Difference Regions ++ ++Ediff has variables to control the way fine differences are ++highlighted. This feature gives you control over the process of refinement. ++Note that refinement ignores spaces, tabs, and newlines. ++ ++@table @code ++@item ediff-auto-refine ++@vindex ediff-auto-refine ++This variable controls whether fine differences within regions are ++highlighted automatically (``auto-refining''). The default is yes ++(@samp{on}). ++ ++On a slow machine, automatic refinement may be painful. In that case, ++you can turn auto-refining on or off interactively by typing ++@kbd{@@}. You can also turn off display of refining that has ++already been done. ++ ++When auto-refining is off, fine differences are shown only for regions ++for which these differences have been computed and saved before. If ++auto-refining and display of refining are both turned off, fine ++differences are not shown at all. ++ ++Typing @kbd{*} computes and displays fine differences for the current ++difference region, regardless of whether auto-refining is turned on. ++ ++@item ediff-auto-refine-limit ++@vindex ediff-auto-refine-limit ++If auto-refining is on, this variable limits the size of the regions to ++be auto-refined. This guards against the possible slowdown that may be ++caused by extraordinary large difference regions. ++ ++You can always refine the current region by typing @kbd{*}. ++ ++@item ediff-forward-word-function ++@vindex ediff-forward-word-function ++This variable controls how fine differences are computed. The ++value must be a Lisp function that determines how the current difference ++region should be split into words. ++ ++@vindex ediff-diff-program ++@vindex ediff-forward-word-function ++@findex ediff-forward-word ++Fine differences are computed by first splitting the current difference ++region into words and then passing the result to ++@code{ediff-diff-program}. For the default forward word function (which is ++@code{ediff-forward-word}), a word is a string consisting of letters, ++@samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits, ++or a string consisting of symbols that are neither space, nor a letter. ++ ++This default behavior is controlled by four variables: @code{ediff-word-1}, ++..., @code{ediff-word-4}. See the on-line documentation for these variables ++and for the function @code{ediff-forward-word} for an explanation of how to ++modify these variables. ++@vindex ediff-word-1 ++@vindex ediff-word-2 ++@vindex ediff-word-3 ++@vindex ediff-word-4 ++@end table ++ ++Sometimes, when a region has too many differences between the variants, ++highlighting of fine differences is inconvenient, especially on ++color displays. If that is the case, type @kbd{*} with a negative ++prefix argument. This unhighlights fine differences for the current ++region. ++ ++To unhighlight fine differences in all difference regions, use the ++command @kbd{@@}. Repeated typing of this key cycles through three ++different states: auto-refining, no-auto-refining, and no-highlighting ++of fine differences. ++ ++@node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization ++@section Patch and Diff Programs ++ ++This section describes variables that specify the programs to be used for ++applying patches and for computing the main difference regions (not the ++fine difference regions): ++ ++@table @code ++@item ediff-diff-program ++@itemx ediff-diff3-program ++@vindex ediff-patch-program ++@vindex ediff-diff-program ++@vindex ediff-diff3-program ++These variables specify the programs to use to produce differences ++and do patching. ++ ++@item ediff-diff-options ++@itemx ediff-diff3-options ++@vindex ediff-patch-options ++@vindex ediff-diff-options ++@vindex ediff-diff3-options ++These variables specify the options to pass to the above utilities. ++ ++In @code{ediff-diff-options}, it may be useful to specify options ++such as @samp{-w} that ignore certain kinds of changes. However, ++Ediff does not let you use the option @samp{-c}, as it doesn't recognize this ++format yet. ++ ++@item ediff-coding-system-for-read ++@vindex ediff-coding-system-for-read ++This variable specifies the coding system to use when reading the output ++that the programs @code{diff3} and @code{diff} send to Emacs. The default ++is @code{raw-text}, and this should work fine in Unix and in most ++cases under Windows NT/95/98/2000. There are @code{diff} programs ++for which the default option doesn't work under Windows. In such cases, ++@code{raw-text-dos} might work. If not, you will have to experiment with ++other coding systems or use GNU diff. ++ ++@item ediff-patch-program ++The program to use to apply patches. Since there are certain ++incompatibilities between the different versions of the patch program, the ++best way to stay out of trouble is to use a GNU-compatible version. ++Otherwise, you may have to tune the values of the variables ++@code{ediff-patch-options}, @code{ediff-backup-specs}, and ++@code{ediff-backup-extension} as described below. ++@item ediff-patch-options ++Options to pass to @code{ediff-patch-program}. ++ ++Note: the `-b' and `-z' options should be specified in ++`ediff-backup-specs', not in @code{ediff-patch-options}. ++ ++It is recommended to pass the `-f' option to the patch program, so it won't ++ask questions. However, some implementations don't accept this option, in ++which case the default value of this variable should be changed. ++ ++@item ediff-backup-extension ++Backup extension used by the patch program. Must be specified, even if ++@code{ediff-backup-specs} is given. ++@item ediff-backup-specs ++Backup directives to pass to the patch program. ++Ediff requires that the old version of the file (before applying the patch) ++is saved in a file named @file{the-patch-file.extension}. Usually ++`extension' is `.orig', but this can be changed by the user, and may also be ++system-dependent. Therefore, Ediff needs to know the backup extension used ++by the patch program. ++ ++Some versions of the patch program let the user specify `-b backup-extension'. ++Other versions only permit `-b', which (usually) assumes the extension `.orig'. ++Yet others force you to use `-z'. ++ ++Note that both `ediff-backup-extension' and `ediff-backup-specs' must be ++properly set. If your patch program takes the option `-b', but not ++`-b extension', the variable `ediff-backup-extension' must still ++be set so Ediff will know which extension to use. ++ ++@item ediff-custom-diff-program ++@itemx ediff-custom-diff-options ++@vindex ediff-custom-diff-program ++@vindex ediff-custom-diff-options ++@findex ediff-save-buffer ++Because Ediff limits the options you may want to pass to the @code{diff} ++program, it partially makes up for this drawback by letting you save the ++output from @code{diff} in your preferred format, which is specified via ++the above two variables. ++ ++The output generated by @code{ediff-custom-diff-program} (which doesn't ++even have to be a standard-style @code{diff}!)@: is not used by Ediff. It is ++provided exclusively so that you can ++refer to ++it later, send it over email, etc. For instance, after reviewing the ++differences, you may want to send context differences to a colleague. ++Since Ediff ignores the @samp{-c} option in ++@code{ediff-diff-program}, you would have to run @code{diff -c} separately ++just to produce the list of differences. Fortunately, ++@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options} ++eliminate this nuisance by keeping a copy of a difference list in the ++desired format in a buffer that can be displayed via the command @kbd{D}. ++ ++@item ediff-patch-default-directory ++@vindex ediff-patch-default-directory ++Specifies the default directory to look for patches. ++ ++@end table ++ ++@noindent ++@strong{Warning:} Ediff does not support the output format of VMS ++@code{diff}. Instead, make sure you are using some implementation of POSIX ++@code{diff}, such as @code{gnudiff}. ++ ++@node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization ++@section Merging and diff3 ++ ++Ediff supports three-way comparison via the functions @code{ediff-files3} and ++@code{ediff-buffers3}. The interface is the same as for two-way comparison. ++In three-way comparison and merging, Ediff reports if any two difference ++regions are identical. For instance, if the current region in buffer A ++is the same as the region in buffer C, then the mode line of buffer A will ++display @samp{[=diff(C)]} and the mode line of buffer C will display ++@samp{[=diff(A)]}. ++ ++Merging is done according to the following algorithm. ++ ++If a difference region in one of the buffers, say B, differs from the ancestor ++file while the region in the other buffer, A, doesn't, then the merge buffer, ++C, gets B's region. Similarly when buffer A's region differs from ++the ancestor and B's doesn't, A's region is used. ++ ++@vindex ediff-default-variant ++If both regions in buffers A and B differ from the ancestor file, Ediff ++chooses the region according to the value of the variable ++@code{ediff-default-variant}. If its value is @code{default-A} then A's ++region is chosen. If it is @code{default-B} then B's region is chosen. ++If it is @code{combined} then the region in buffer C will look like ++this: ++ ++@comment Use @set to avoid triggering merge conflict detectors like CVS. ++@set seven-left <<<<<<< ++@set seven-right >>>>>>> ++@example ++@value{seven-left} variant A ++the difference region from buffer A ++@value{seven-right} variant B ++the difference region from buffer B ++####### Ancestor ++the difference region from the ancestor buffer, if available ++======= end ++@end example ++ ++The above is the default template for the combined region. The user can ++customize this template using the variable ++@code{ediff-combination-pattern}. ++ ++@vindex ediff-combination-pattern ++The variable @code{ediff-combination-pattern} specifies the template that ++determines how the combined merged region looks like. The template is ++represented as a list of the form @code{(STRING1 Symbol1 STRING2 Symbol2 ++STRING3 Symbol3 STRING4)}. The symbols here must be atoms of the form ++@code{A}, @code{B}, or @code{Ancestor}. They determine the order in which ++the corresponding difference regions (from buffers A, B, and the ancestor ++buffer) are displayed in the merged region of buffer C. The strings in the ++template determine the text that separates the aforesaid regions. The ++default template is ++ ++@smallexample ++("@value{seven-left} variant A" A "@value{seven-right} variant B" B ++ "####### Ancestor" Ancestor "======= end") ++@end smallexample ++ ++@noindent ++(this is one long line) and the corresponding combined region is shown ++above. The order in which the regions are shown (and the separator ++strings) can be changed by changing the above template. It is even ++possible to add or delete region specifiers in this template (although ++the only possibly useful such modification seems to be the deletion of ++the ancestor). ++ ++In addition to the state of the difference, Ediff displays the state of the ++merge for each region. If a difference came from buffer A by default ++(because both regions A and B were different from the ancestor and ++@code{ediff-default-variant} was set to @code{default-A}) then ++@samp{[=diff(A) default-A]} is displayed in the mode line. If the ++difference in buffer C came, say, from buffer B because the difference ++region in that buffer differs from the ancestor, but the region in buffer A ++does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is ++displayed. The indicators default-A/B and prefer-A/B are inspired by ++Emerge and have the same meaning. ++ ++Another indicator of the state of merge is @samp{combined}. It appears ++with any difference region in buffer C that was obtained by combining ++the difference regions in buffers A and B as explained above. ++ ++In addition to the state of merge and state of difference indicators, while ++merging with an ancestor file or buffer, Ediff informs the user when the ++current difference region in the (normally invisible) ancestor buffer is ++empty via the @emph{AncestorEmpty} indicator. This helps determine if the ++changes made to the original in variants A and B represent pure insertion ++or deletion of text: if the mode line shows @emph{AncestorEmpty} and the ++corresponding region in buffers A or B is not empty, this means that new ++text was inserted. If this indicator is not present and the difference ++regions in buffers A or B are non-empty, this means that text was ++modified. Otherwise, the original text was deleted. ++ ++Although the ancestor buffer is normally invisible, Ediff maintains ++difference regions there and advances the current difference region ++accordingly. All highlighting of difference regions is provided in the ++ancestor buffer, except for the fine differences. Therefore, if desired, the ++user can put the ancestor buffer in a separate frame and watch it ++there. However, on a TTY, only one frame can be visible at any given time, ++and Ediff doesn't support any single-frame window configuration where all ++buffers, including the ancestor buffer, would be visible. However, the ++ancestor buffer can be displayed by typing @kbd{/} to the control ++window. (Type @kbd{C-l} to hide it again.) ++ ++Note that the state-of-difference indicators @samp{=diff(A)} and ++@samp{=diff(B)} above are not redundant, even in the presence of a ++state-of-merge indicator. In fact, the two serve different purposes. ++ ++For instance, if the mode line displays @samp{=diff(B) prefer(B)} and ++you copy a difference region from buffer A to buffer C then ++@samp{=diff(B)} will change to @samp{diff-A} and the mode line will ++display @samp{=diff(A) prefer-B}. This indicates that the difference ++region in buffer C is identical to that in buffer A, but originally ++buffer C's region came from buffer B. This is useful to know because ++you can recover the original difference region in buffer C by typing ++@kbd{r}. ++ ++ ++Ediff never changes the state-of-merge indicator, except in response to ++the @kbd{!} command (see below), in which case the indicator is lost. ++On the other hand, the state-of-difference indicator is changed ++automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r}, ++@kbd{+}. ++ ++The @kbd{!} command loses the information about origins of the regions ++in the merge buffer (default-A, prefer-B, or combined). This is because ++recomputing differences in this case means running @code{diff3} on ++buffers A, B, and the merge buffer, not on the ancestor buffer. (It ++makes no sense to recompute differences using the ancestor file, since ++in the merging mode Ediff assumes that you have not edited buffers A and ++B, but that you may have edited buffer C, and these changes are to be ++preserved.) Since some difference regions may disappear as a result of ++editing buffer C and others may arise, there is generally no simple way ++to tell where the various regions in the merge buffer came from. ++ ++In three-way comparison, Ediff tries to disregard regions that consist ++entirely of white space. For instance, if, say, the current region in ++buffer A consists of the white space only (or if it is empty), Ediff will ++not take it into account for the purpose of computing fine differences. The ++result is that Ediff can provide a better visual information regarding the ++actual fine differences in the non-white regions in buffers B and ++C. Moreover, if the regions in buffers B and C differ in the white space ++only, then a message to this effect will be displayed. ++ ++@vindex ediff-merge-window-share ++In the merge mode, the share of the split between window C (the window ++displaying the merge-buffer) and the windows displaying buffers A and B ++is controlled by the variable @code{ediff-merge-window-share}. Its ++default value is 0.5. To make the merge-buffer window smaller, reduce ++this amount. ++ ++We don't recommend increasing the size of the merge-window to more than ++half the frame (i.e., to increase the value of ++@code{ediff-merge-window-share}) to more than 0.5, since it would be ++hard to see the contents of buffers A and B. ++ ++You can temporarily shrink the merge window to just one line by ++typing @kbd{s}. This change is temporary, until Ediff finds a reason to ++redraw the screen. Typing @kbd{s} again restores the original window size. ++ ++With a positive prefix argument, the @kbd{s} command will make the merge ++window slightly taller. This change is persistent. With `@kbd{-}' or ++with a negative prefix argument, the command @kbd{s} makes the merge ++window slightly shorter. This change also persistent. ++ ++@vindex ediff-show-clashes-only ++Ediff lets you automatically ignore the regions where only one of the ++buffers A and B disagrees with the ancestor. To do this, set the ++variable @code{ediff-show-clashes-only} to non-@code{nil}. ++ ++You can toggle this feature interactively by typing @kbd{$$}. ++ ++Note that this variable affects only the show next/previous difference ++commands. You can still jump directly to any difference region directly ++using the command @kbd{j} (with a prefix argument specifying the difference ++number). ++ ++@vindex ediff-autostore-merges ++@vindex ediff-quit-merge-hook ++@findex ediff-maybe-save-and-delete-merge ++The variable @code{ediff-autostore-merges} controls what happens to the ++merge buffer when Ediff quits. If the value is @code{nil}, nothing is done ++to the merge buffer---it will be the user's responsibility to save it. ++If the value is @code{t}, the user will be asked where to save the buffer ++and whether to delete it afterwards. It the value is neither @code{nil} nor ++@code{t}, the merge buffer is saved @emph{only} if this merge session was ++invoked from a group of related Ediff session, such as those that result ++from @code{ediff-merge-directories}, ++@code{ediff-merge-directory-revisions}, etc. ++@xref{Session Groups}. This behavior is implemented in the function ++@code{ediff-maybe-save-and-delete-merge}, which is a hook in ++@code{ediff-quit-merge-hook}. The user can supply a different hook, if ++necessary. ++ ++The variable @code{ediff-autostore-merges} is buffer-local, so it can be ++set in a per-buffer manner. Therefore, use @code{setq-default} to globally ++change this variable. ++ ++@vindex ediff-merge-filename-prefix ++When merge buffers are saved automatically as directed by ++@code{ediff-autostore-merges}, Ediff attaches a prefix to each file, as ++specified by the variable @code{ediff-merge-filename-prefix}. The default ++is @code{merge_}, but this can be changed by the user. ++ ++@node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization ++@section Support for Version Control ++ ++ ++Ediff supports version control and lets you compare versions of files ++visited by Emacs buffers via the function @code{ediff-revision}. This ++feature is controlled by the following variables: ++ ++@table @code ++@item ediff-version-control-package ++@vindex ediff-version-control-package ++A symbol. The default is @samp{vc}. ++ ++If you are like most Emacs users, Ediff will use VC as the version control ++package. This is the standard Emacs interface to RCS, CVS, and SCCS. ++ ++However, if your needs are better served by other interfaces, you will ++have to tell Ediff which version control package you are using, e.g., ++@example ++(setq ediff-version-control-package 'rcs) ++@end example ++ ++Apart from the standard @file{vc.el}, Ediff supports three other interfaces ++to version control: @file{rcs.el}, @file{pcl-cvs.el} (recently renamed ++pcvs.el), and @file{generic-sc.el}. The package @file{rcs.el} is written ++by Sebastian Kremer and is available as ++@example ++@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z} ++@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z} ++@end example ++@pindex @file{vc.el} ++@pindex @file{rcs.el} ++@pindex @file{pcl-cvs.el} ++@pindex @file{generic-sc.el} ++@end table ++ ++Ediff's interface to the above packages allows the user to compare the ++versions of the current buffer or to merge them (with or without an ++ancestor-version). These operations can also be performed on directories ++containing files under version control. ++ ++In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function ++@code{run-ediff-from-cvs-buffer}---see the documentation string for this ++function. ++ ++@node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization ++@section Customizing the Mode Line ++ ++When Ediff is running, the mode line of @samp{Ediff Control Panel} ++buffer shows the current difference number and the total number of ++difference regions in the two files. ++ ++The mode line of the buffers being compared displays the type of the ++buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name. ++Ediff tries to be intelligent in choosing the mode line buffer ++identification. In particular, it works well with the ++@file{uniquify.el} and @file{mode-line.el} packages (which improve on ++the default way in which Emacs displays buffer identification). If you ++don't like the way Ediff changes the mode line, you can use ++@code{ediff-prepare-buffer-hook} to modify the mode line. ++@vindex ediff-prepare-buffer-hook ++@pindex @file{uniquify.el} ++@pindex @file{mode-line.el} ++ ++@node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization ++@section Miscellaneous ++ ++Here are a few other variables for customizing Ediff: ++ ++@table @code ++@item ediff-split-window-function ++@vindex ediff-split-window-function ++Controls the way you want the window be split between file-A and file-B ++(and file-C, if applicable). It defaults to the vertical split ++(@code{split-window-vertically}, but you can set it to ++@code{split-window-horizontally}, if you so wish. ++Ediff also lets you switch from vertical to horizontal split and back ++interactively. ++ ++Note that if Ediff detects that all the buffers it compares are displayed in ++separate frames, it assumes that the user wants them to be so displayed ++and stops splitting windows. Instead, it arranges for each buffer to ++be displayed in a separate frame. You can switch to the one-frame mode ++by hiding one of the buffers A/B/C. ++ ++You can also swap the windows where buffers are displayed by typing ++@kbd{~}. ++ ++@item ediff-merge-split-window-function ++@vindex ediff-merge-split-window-function ++Controls how windows are ++split between buffers A and B in the merge mode. ++This variable is like @code{ediff-split-window-function}, but it defaults ++to @code{split-window-horizontally} instead of ++@code{split-window-vertically}. ++ ++@item ediff-make-wide-display-function ++@vindex ediff-make-wide-display-function ++The value is a function to be called to widen the frame for displaying ++the Ediff buffers. See the on-line documentation for ++@code{ediff-make-wide-display-function} for details. It is also ++recommended to look into the source of the default function ++@code{ediff-make-wide-display}. ++ ++You can toggle wide/regular display by typing @kbd{m}. In the wide ++display mode, buffers A, B (and C, when applicable) are displayed in a ++single frame that is as wide as the entire workstation screen. This is ++useful when files are compared side-by-side. By default, the display is ++widened without changing its height. ++ ++@item ediff-use-last-dir ++@vindex ediff-use-last-dir ++Controls the way Ediff presents the ++default directory when it prompts the user for files to compare. If ++@code{nil}, ++Ediff uses the default directory of the current buffer when it ++prompts the user for file names. Otherwise, it will use the ++directories it had previously used for files A, B, or C, respectively. ++ ++@item ediff-no-emacs-help-in-control-buffer ++@vindex ediff-no-emacs-help-in-control-buffer ++If @code{t}, makes @kbd{C-h} ++behave like the @key{DEL} key, i.e., it will move you back to the previous ++difference rather than invoking help. This is useful when, in an xterm ++window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is ++positioned more conveniently than the @key{DEL} key. ++ ++@item ediff-toggle-read-only-function ++@vindex ediff-toggle-read-only-function ++This variable's value is a function that Ediff uses to toggle ++the read-only property in its buffers. ++ ++The default function that Ediff uses simply toggles the read-only property, ++unless the file is under version control. For a checked-in file under ++version control, Ediff first tries to check the file out. ++ ++@item ediff-make-buffers-readonly-at-startup nil ++@vindex ediff-make-buffers-readonly-at-startup ++If @code{t}, all variant buffers are made read-only at Ediff startup. ++ ++@item ediff-keep-variants ++@vindex @code{ediff-keep-variants} ++The default is @code{t}, meaning that the buffers being compared or merged will ++be preserved when Ediff quits. Setting this to @code{nil} causes Ediff to ++offer the user a chance to delete these buffers (if they are not modified). ++Supplying a prefix argument to the quit command (@code{q}) temporarily ++reverses the meaning of this variable. This is convenient when the user ++prefers one of the behaviors most of the time, but occasionally needs the ++other behavior. ++ ++However, Ediff temporarily resets this variable to @code{t} if it is ++invoked via one of the "buffer" jobs, such as @code{ediff-buffers}. ++This is because it is all too easy to loose day's work otherwise. ++Besides, in a "buffer" job, the variant buffers have already been loaded ++prior to starting Ediff, so Ediff just preserves status quo here. ++ ++Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants ++unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks). ++ ++@item ediff-keep-tmp-versions ++@vindex @code{ediff-keep-tmp-versions} ++Default is @code{nil}. If @code{t}, the versions of the files being ++compared or merged using operations such as @code{ediff-revision} or ++@code{ediff-merge-revisions} are not deleted on exit. The normal action is ++to clean up and delete these version files. ++ ++@item ediff-grab-mouse ++@vindex @code{ediff-grab-mouse} ++Default is @code{t}. Normally, Ediff grabs mouse and puts it in its ++control frame. This is useful since the user can be sure that when he ++needs to type an Ediff command the focus will be in an appropriate Ediff's ++frame. However, some users prefer to move the mouse by themselves. The ++above variable, if set to @code{maybe}, will prevent Ediff from grabbing ++the mouse in many situations, usually after commands that may take more ++time than usual. In other situation, Ediff will continue grabbing the mouse ++and putting it where it believes is appropriate. If the value is ++@code{nil}, then mouse is entirely user's responsibility. ++Try different settings and see which one is for you. ++@end table ++ ++ ++@node Notes on Heavy-duty Customization, , Miscellaneous, Customization ++@section Notes on Heavy-duty Customization ++ ++Some users need to customize Ediff in rather sophisticated ways, which ++requires different defaults for different kinds of files (e.g., SGML, ++etc.). Ediff supports this kind of customization in several ways. First, ++most customization variables are buffer-local. Those that aren't are ++usually accessible from within Ediff Control Panel, so one can make them ++local to the panel by calling make-local-variable from within ++@code{ediff-startup-hook}. ++ ++Second, the function @code{ediff-setup} accepts an optional sixth ++argument which has the form @code{((@var{var-name-1} .@: @var{val-1}) ++(@var{var-name-2} .@: @var{val-2}) @dots{})}. The function ++@code{ediff-setup} sets the variables in the list to the respective ++values, locally in the Ediff control buffer. This is an easy way to ++throw in custom variables (which usually should be buffer-local) that ++can then be tested in various hooks. ++ ++Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set ++properly in this case, as some things in Ediff depend on this. ++ ++Finally, if you want custom-tailored help messages, you can set the ++variables @code{ediff-brief-help-message-function} and ++@code{ediff-long-help-message-function} ++to functions that return help strings. ++@vindex ediff-startup-hook ++@findex ediff-setup ++@vindex ediff-job-name ++@vindex ediff-word-mode ++@vindex ediff-brief-help-message-function ++@vindex ediff-long-help-message-function ++ ++When customizing Ediff, some other variables are useful, although they are ++not user-definable. They are local to the Ediff control buffer, so this ++buffer must be current when you access these variables. The control buffer ++is accessible via the variable @code{ediff-control-buffer}, which is also ++local to that buffer. It is usually used for checking if the current buffer ++is also the control buffer. ++ ++Other variables of interest are: ++@table @code ++@item ediff-buffer-A ++The first of the data buffers being compared. ++ ++@item ediff-buffer-B ++The second of the data buffers being compared. ++ ++@item ediff-buffer-C ++In three-way comparisons, this is the third buffer being compared. ++In merging, this is the merge buffer. ++In two-way comparison, this variable is @code{nil}. ++ ++@item ediff-window-A ++The window displaying buffer A. If buffer A is not visible, this variable ++is @code{nil} or it may be a dead window. ++ ++@item ediff-window-B ++The window displaying buffer B. ++ ++@item ediff-window-C ++The window displaying buffer C, if any. ++ ++@item ediff-control-frame ++A dedicated frame displaying the control buffer, if it exists. It is ++non-@code{nil} only if Ediff uses the multiframe display, i.e., when ++the control buffer is in its own frame. ++@end table ++ ++@node Credits, GNU Free Documentation License, Customization, Top ++@chapter Credits ++ ++Ediff was written by Michael Kifer . It was inspired ++by emerge.el written by Dale R.@: Worley . An idea due to ++Boris Goldowsky made it possible to highlight ++fine differences in Ediff buffers. Alastair Burt ++ported Ediff to XEmacs, Eric Freudenthal ++made it work with VC, Marc Paquette wrote the ++toolbar support package for Ediff, and Hrvoje Niksic ++adapted it to the Emacs customization package. ++ ++Many people provided help with bug reports, feature suggestions, and advice. ++Without them, Ediff would not be nearly as useful as it is today. ++Here is a hopefully full list of contributors: ++ ++@example ++Adrian Aichner (aichner@@ecf.teradyne.com), ++Drew Adams (drew.adams@@oracle.com), ++Steve Baur (steve@@xemacs.org), ++Neal Becker (neal@@ctd.comsat.com), ++E.@: Jay Berkenbilt (ejb@@ql.org), ++Alastair Burt (burt@@dfki.uni-kl.de), ++Paul Bibilo (peb@@delcam.co.uk), ++Kevin Broadey (KevinB@@bartley.demon.co.uk), ++Harald Boegeholz (hwb@@machnix.mathematik.uni-stuttgart.de), ++Bradley A.@: Bosch (brad@@lachman.com), ++Michael D.@: Carney (carney@@ltx-tr.com), ++Jin S.@: Choi (jin@@atype.com), ++Scott Cummings (cummings@@adc.com), ++Albert Dvornik (bert@@mit.edu), ++Eric Eide (eeide@@asylum.cs.utah.edu), ++Paul Eggert (eggert@@twinsun.com), ++Urban Engberg (ue@@cci.dk), ++Kevin Esler (esler@@ch.hp.com), ++Robert Estes (estes@@ece.ucdavis.edu), ++Jay Finger (jayf@@microsoft.com), ++Xavier Fornari (xavier@@europe.cma.fr), ++Eric Freudenthal (freudent@@jan.ultra.nyu.edu), ++Job Ganzevoort (Job.Ganzevoort@@cwi.nl), ++Felix Heinrich Gatzemeier (felix.g@@tzemeier.info), ++Boris Goldowsky (boris@@cs.rochester.edu), ++Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu), ++Aaron Gross (aaron@@bfr.co.il), ++Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de), ++Marcus Harnisch (marcus_harnisch@@mint-tech.com), ++Steven E. Harris (seh@@panix.com), ++Aaron S. Hawley (Aaron.Hawley@@uvm.edu), ++Xiaoli Huang (hxl@@epic.com), ++Andreas Jaeger (aj@@suse.de), ++Lars Magne Ingebrigtsen (larsi@@ifi.uio.no), ++Larry Gouge (larry@@itginc.com), ++Karl Heuer (kwzh@@gnu.org), ++(irvine@@lks.csi.com), ++(jaffe@@chipmunk.cita.utoronto.ca), ++David Karr (dkarr@@nmo.gtegsc.com), ++Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de), ++Steffen Kilb (skilb@@gmx.net), ++Leigh L Klotz (klotz@@adoc.xerox.com), ++Fritz Knabe (Fritz.Knabe@@ecrc.de), ++Heinz Knutzen (hk@@informatik.uni-kiel.d400.de), ++Andrew Koenig (ark@@research.att.com), ++Hannu Koivisto (azure@@iki.fi), ++Ken Laprade (laprade@@dw3f.ess.harris.com), ++Will C Lauer (wcl@@cadre.com), ++Richard Levitte (levitte@@e.kth.se), ++Mike Long (mike.long@@analog.com), ++Dave Love (d.love@@dl.ac.uk), ++Martin Maechler (maechler@@stat.math.ethz.ch), ++Simon Marshall (simon@@gnu.org), ++Paul C. Meuse (pmeuse@@delcomsys.com), ++Richard Mlynarik (mly@@adoc.xerox.com), ++Stefan Monnier (monnier@@cs.yale.edu), ++Chris Murphy (murphycm@@sun.aston.ac.uk), ++Erik Naggum (erik@@naggum.no), ++Eyvind Ness (Eyvind.Ness@@hrp.no), ++Ray Nickson (nickson@@cs.uq.oz.au), ++Dan Nicolaescu (dann@@ics.uci.edu), ++David Petchey (petchey_david@@jpmorgan.com), ++Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk), ++Francois Pinard (pinard@@iro.umontreal.ca), ++Tibor Polgar (tlp00@@spg.amdahl.com), ++David Prince (dave0d@@fegs.co.uk), ++Paul Raines (raines@@slac.stanford.edu), ++Stefan Reicher (xsteve@@riic.at), ++Charles Rich (rich@@merl.com), ++Bill Richter (richter@@math.nwu.edu), ++C.S.@: Roberson (roberson@@aur.alcatel.com), ++Kevin Rodgers (kevin.rodgers@@ihs.com), ++Sandy Rutherford (sandy@@ibm550.sissa.it), ++Heribert Schuetz (schuetz@@ecrc.de), ++Andy Scott (ascott@@pcocd2.intel.com), ++Axel Seibert (axel@@tumbolia.ppp.informatik.uni-muenchen.de), ++Vin Shelton (acs@@xemacs.org), ++Scott O. Sherman (Scott.Sherman@@mci.com), ++Nikolaj Schumacher (n_schumacher@@web.de), ++Richard Stallman (rms@@gnu.org), ++Richard Stanton (stanton@@haas.berkeley.edu), ++Sam Steingold (sds@@goems.com), ++Ake Stenhoff (etxaksf@@aom.ericsson.se), ++Stig (stig@@hackvan.com), ++Peter Stout (Peter_Stout@@cs.cmu.edu), ++Chuck Thompson (cthomp@@cs.uiuc.edu), ++Ray Tomlinson (tomlinso@@bbn.com), ++Raymond Toy (toy@@rtp.ericsson.se), ++Stephen J. Turnbull (stephen@@xemacs.org), ++Jan Vroonhof (vroonhof@@math.ethz.ch), ++Colin Walters (walters@@cis.ohio-state.edu), ++Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be), ++Klaus Weber (gizmo@@zork.north.de), ++Ben Wing (ben@@xemacs.org), ++Tom Wurgler (twurgler@@goodyear.com), ++Steve Youngs (youngs@@xemacs.org), ++Ilya Zakharevich (ilya@@math.ohio-state.edu), ++Eli Zaretskii (eliz@@is.elta.co.il) ++@end example ++ ++@node GNU Free Documentation License, Index, Credits, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++ ++@node Index, , GNU Free Documentation License, Top ++@unnumbered Index ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 165ecb88-d03c-44b1-a921-b93f50b05b46 ++@end ignore +diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi +new file mode 100644 +index 0000000..e9a0359 +--- /dev/null ++++ b/doc/misc/emacs-mime.texi +@@ -0,0 +1,1892 @@ ++\input texinfo ++ ++@setfilename ../../info/emacs-mime ++@settitle Emacs MIME Manual ++@synindex fn cp ++@synindex vr cp ++@synindex pg cp ++ ++@copying ++This file documents the Emacs MIME interface functionality. ++ ++Copyright @copyright{} 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, ++2006, 2007, 2008, 2009 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 ++ ++@c Node ``Interface Functions'' uses Latin-1 characters ++@documentencoding ISO-8859-1 ++ ++@dircategory Emacs ++@direntry ++* Emacs MIME: (emacs-mime). Emacs MIME de/composition library. ++@end direntry ++@iftex ++@finalout ++@end iftex ++@setchapternewpage odd ++ ++@titlepage ++@title Emacs MIME Manual ++ ++@author by Lars Magne Ingebrigtsen ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top ++@top Emacs MIME ++ ++This manual documents the libraries used to compose and display ++@acronym{MIME} messages. ++ ++This manual is directed at users who want to modify the behavior of ++the @acronym{MIME} encoding/decoding process or want a more detailed ++picture of how the Emacs @acronym{MIME} library works, and people who want ++to write functions and commands that manipulate @acronym{MIME} elements. ++ ++@acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}. ++This standard is documented in a number of RFCs; mainly RFC2045 (Format ++of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message ++Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration ++Procedures), RFC2049 (Conformance Criteria and Examples). It is highly ++recommended that anyone who intends writing @acronym{MIME}-compliant software ++read at least RFC2045 and RFC2047. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Decoding and Viewing:: A framework for decoding and viewing. ++* Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts. ++* Interface Functions:: An abstraction over the basic functions. ++* Basic Functions:: Utility and basic parsing functions. ++* Standards:: A summary of RFCs and working documents used. ++* GNU Free Documentation License:: The license for this documentation. ++* Index:: Function and variable index. ++@end menu ++ ++ ++@node Decoding and Viewing ++@chapter Decoding and Viewing ++ ++This chapter deals with decoding and viewing @acronym{MIME} messages on a ++higher level. ++ ++The main idea is to first analyze a @acronym{MIME} article, and then allow ++other programs to do things based on the list of @dfn{handles} that are ++returned as a result of this analysis. ++ ++@menu ++* Dissection:: Analyzing a @acronym{MIME} message. ++* Non-MIME:: Analyzing a non-@acronym{MIME} message. ++* Handles:: Handle manipulations. ++* Display:: Displaying handles. ++* Display Customization:: Variables that affect display. ++* Files and Directories:: Saving and naming attachments. ++* New Viewers:: How to write your own viewers. ++@end menu ++ ++ ++@node Dissection ++@section Dissection ++ ++The @code{mm-dissect-buffer} is the function responsible for dissecting ++a @acronym{MIME} article. If given a multipart message, it will recursively ++descend the message, following the structure, and return a tree of ++@acronym{MIME} handles that describes the structure of the message. ++ ++@node Non-MIME ++@section Non-MIME ++@vindex mm-uu-configure-list ++ ++Gnus also understands some non-@acronym{MIME} attachments, such as ++postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp, ++diff. Each of these features can be disabled by add an item into ++@code{mm-uu-configure-list}. For example, ++ ++@lisp ++(require 'mm-uu) ++(add-to-list 'mm-uu-configure-list '(pgp-signed . disabled)) ++@end lisp ++ ++@table @code ++@item postscript ++@findex postscript ++PostScript file. ++ ++@item uu ++@findex uu ++Uuencoded file. ++ ++@item binhex ++@findex binhex ++Binhex encoded file. ++ ++@item yenc ++@findex yenc ++Yenc encoded file. ++ ++@item shar ++@findex shar ++Shar archive file. ++ ++@item forward ++@findex forward ++Non-@acronym{MIME} forwarded message. ++ ++@item gnatsweb ++@findex gnatsweb ++Gnatsweb attachment. ++ ++@item pgp-signed ++@findex pgp-signed ++@acronym{PGP} signed clear text. ++ ++@item pgp-encrypted ++@findex pgp-encrypted ++@acronym{PGP} encrypted clear text. ++ ++@item pgp-key ++@findex pgp-key ++@acronym{PGP} public keys. ++ ++@item emacs-sources ++@findex emacs-sources ++@vindex mm-uu-emacs-sources-regexp ++Emacs source code. This item works only in the groups matching ++@code{mm-uu-emacs-sources-regexp}. ++ ++@item diff ++@vindex diff ++@vindex mm-uu-diff-groups-regexp ++Patches. This is intended for groups where diffs of committed files ++are automatically sent to. It only works in groups matching ++@code{mm-uu-diff-groups-regexp}. ++ ++@item verbatim-marks ++@cindex verbatim-marks ++Slrn-style verbatim marks. ++ ++@item LaTeX ++@cindex LaTeX ++LaTeX documents. It only works in groups matching ++@code{mm-uu-tex-groups-regexp}. ++ ++@end table ++ ++@cindex text/x-verbatim ++@c Is @vindex suitable for a face? ++@vindex mm-uu-extract ++Some inlined non-@acronym{MIME} attachments are displayed using the face ++@code{mm-uu-extract}. By default, no @acronym{MIME} button for these ++parts is displayed. You can force displaying a button using @kbd{K b} ++(@code{gnus-summary-display-buttonized}) or add @code{text/x-verbatim} ++to @code{gnus-buttonized-mime-types}, @xref{MIME Commands, ,MIME ++Commands, gnus, Gnus Manual}. ++ ++@node Handles ++@section Handles ++ ++A @acronym{MIME} handle is a list that fully describes a @acronym{MIME} ++component. ++ ++The following macros can be used to access elements in a handle: ++ ++@table @code ++@item mm-handle-buffer ++@findex mm-handle-buffer ++Return the buffer that holds the contents of the undecoded @acronym{MIME} ++part. ++ ++@item mm-handle-type ++@findex mm-handle-type ++Return the parsed @code{Content-Type} of the part. ++ ++@item mm-handle-encoding ++@findex mm-handle-encoding ++Return the @code{Content-Transfer-Encoding} of the part. ++ ++@item mm-handle-undisplayer ++@findex mm-handle-undisplayer ++Return the object that can be used to remove the displayed part (if it ++has been displayed). ++ ++@item mm-handle-set-undisplayer ++@findex mm-handle-set-undisplayer ++Set the undisplayer object. ++ ++@item mm-handle-disposition ++@findex mm-handle-disposition ++Return the parsed @code{Content-Disposition} of the part. ++ ++@item mm-get-content-id ++Returns the handle(s) referred to by @code{Content-ID}. ++ ++@end table ++ ++ ++@node Display ++@section Display ++ ++Functions for displaying, removing and saving. ++ ++@table @code ++@item mm-display-part ++@findex mm-display-part ++Display the part. ++ ++@item mm-remove-part ++@findex mm-remove-part ++Remove the part (if it has been displayed). ++ ++@item mm-inlinable-p ++@findex mm-inlinable-p ++Say whether a @acronym{MIME} type can be displayed inline. ++ ++@item mm-automatic-display-p ++@findex mm-automatic-display-p ++Say whether a @acronym{MIME} type should be displayed automatically. ++ ++@item mm-destroy-part ++@findex mm-destroy-part ++Free all resources occupied by a part. ++ ++@item mm-save-part ++@findex mm-save-part ++Offer to save the part in a file. ++ ++@item mm-pipe-part ++@findex mm-pipe-part ++Offer to pipe the part to some process. ++ ++@item mm-interactively-view-part ++@findex mm-interactively-view-part ++Prompt for a mailcap method to use to view the part. ++ ++@end table ++ ++ ++@node Display Customization ++@section Display Customization ++ ++@table @code ++ ++@item mm-inline-media-tests ++@vindex mm-inline-media-tests ++This is an alist where the key is a @acronym{MIME} type, the second element ++is a function to display the part @dfn{inline} (i.e., inside Emacs), and ++the third element is a form to be @code{eval}ed to say whether the part ++can be displayed inline. ++ ++This variable specifies whether a part @emph{can} be displayed inline, ++and, if so, how to do it. It does not say whether parts are ++@emph{actually} displayed inline. ++ ++@item mm-inlined-types ++@vindex mm-inlined-types ++This, on the other hand, says what types are to be displayed inline, if ++they satisfy the conditions set by the variable above. It's a list of ++@acronym{MIME} media types. ++ ++@item mm-automatic-display ++@vindex mm-automatic-display ++This is a list of types that are to be displayed ``automatically'', but ++only if the above variable allows it. That is, only inlinable parts can ++be displayed automatically. ++ ++@item mm-automatic-external-display ++@vindex mm-automatic-external-display ++This is a list of types that will be displayed automatically in an ++external viewer. ++ ++@item mm-keep-viewer-alive-types ++@vindex mm-keep-viewer-alive-types ++This is a list of media types for which the external viewer will not ++be killed when selecting a different article. ++ ++@item mm-attachment-override-types ++@vindex mm-attachment-override-types ++Some @acronym{MIME} agents create parts that have a content-disposition of ++@samp{attachment}. This variable allows overriding that disposition and ++displaying the part inline. (Note that the disposition is only ++overridden if we are able to, and want to, display the part inline.) ++ ++@item mm-discouraged-alternatives ++@vindex mm-discouraged-alternatives ++List of @acronym{MIME} types that are discouraged when viewing ++@samp{multipart/alternative}. Viewing agents are supposed to view the ++last possible part of a message, as that is supposed to be the richest. ++However, users may prefer other types instead, and this list says what ++types are most unwanted. If, for instance, @samp{text/html} parts are ++very unwanted, and @samp{text/richtext} parts are somewhat unwanted, ++you could say something like: ++ ++@lisp ++(setq mm-discouraged-alternatives ++ '("text/html" "text/richtext") ++ mm-automatic-display ++ (remove "text/html" mm-automatic-display)) ++@end lisp ++ ++Adding @code{"image/.*"} might also be useful. Spammers use images as ++the preferred part of @samp{multipart/alternative} messages, so you might ++not notice there are other parts. See also ++@code{gnus-buttonized-mime-types}, @ref{MIME Commands, ,MIME Commands, ++gnus, Gnus Manual}. After adding @code{"multipart/alternative"} to ++@code{gnus-buttonized-mime-types} you can choose manually which ++alternative you'd like to view. For example, you can set those ++variables like: ++ ++@lisp ++(setq gnus-buttonized-mime-types ++ '("multipart/alternative" "multipart/signed") ++ mm-discouraged-alternatives ++ '("text/html" "image/.*")) ++@end lisp ++ ++In this case, Gnus will display radio buttons for such a kind of spam ++message as follows: ++ ++@example ++1. (*) multipart/alternative ( ) image/gif ++ ++2. (*) text/plain ( ) text/html ++@end example ++ ++@item mm-inline-large-images ++@vindex mm-inline-large-images ++When displaying inline images that are larger than the window, Emacs ++does not enable scrolling, which means that you cannot see the whole ++image. To prevent this, the library tries to determine the image size ++before displaying it inline, and if it doesn't fit the window, the ++library will display it externally (e.g. with @samp{ImageMagick} or ++@samp{xv}). Setting this variable to @code{t} disables this check and ++makes the library display all inline images as inline, regardless of ++their size. ++ ++@item mm-inline-override-types ++@vindex mm-inline-override-types ++@code{mm-inlined-types} may include regular expressions, for example to ++specify that all @samp{text/.*} parts be displayed inline. If a user ++prefers to have a type that matches such a regular expression be treated ++as an attachment, that can be accomplished by setting this variable to a ++list containing that type. For example assuming @code{mm-inlined-types} ++includes @samp{text/.*}, then including @samp{text/html} in this ++variable will cause @samp{text/html} parts to be treated as attachments. ++ ++@item mm-text-html-renderer ++@vindex mm-text-html-renderer ++This selects the function used to render @acronym{HTML}. The predefined ++renderers are selected by the symbols @code{w3}, ++@code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more ++information about emacs-w3m}, @code{links}, @code{lynx}, ++@code{w3m-standalone} or @code{html2text}. If @code{nil} use an ++external viewer. You can also specify a function, which will be ++called with a @acronym{MIME} handle as the argument. ++ ++@item mm-inline-text-html-with-images ++@vindex mm-inline-text-html-with-images ++Some @acronym{HTML} mails might have the trick of spammers using ++@samp{} tags. It is likely to be intended to verify whether you ++have read the mail. You can prevent your personal informations from ++leaking by setting this option to @code{nil} (which is the default). ++It is currently ignored by Emacs/w3. For emacs-w3m, you may use the ++command @kbd{t} on the image anchor to show an image even if it is ++@code{nil}.@footnote{The command @kbd{T} will load all images. If you ++have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i} ++or @kbd{I} instead.} ++ ++@item mm-w3m-safe-url-regexp ++@vindex mm-w3m-safe-url-regexp ++A regular expression that matches safe URL names, i.e. URLs that are ++unlikely to leak personal information when rendering @acronym{HTML} ++email (the default value is @samp{\\`cid:}). If @code{nil} consider ++all URLs safe. ++ ++@item mm-inline-text-html-with-w3m-keymap ++@vindex mm-inline-text-html-with-w3m-keymap ++You can use emacs-w3m command keys in the inlined text/html part by ++setting this option to non-@code{nil}. The default value is @code{t}. ++ ++@item mm-external-terminal-program ++@vindex mm-external-terminal-program ++The program used to start an external terminal. ++ ++@item mm-enable-external ++@vindex mm-enable-external ++Indicate whether external @acronym{MIME} handlers should be used. ++ ++If @code{t}, all defined external @acronym{MIME} handlers are used. If ++@code{nil}, files are saved to disk (@code{mailcap-save-binary-file}). ++If it is the symbol @code{ask}, you are prompted before the external ++@acronym{MIME} handler is invoked. ++ ++When you launch an attachment through mailcap (@pxref{mailcap}) an ++attempt is made to use a safe viewer with the safest options---this isn't ++the case if you save it to disk and launch it in a different way ++(command line or double-clicking). Anyhow, if you want to be sure not ++to launch any external programs, set this variable to @code{nil} or ++@code{ask}. ++ ++@end table ++ ++@node Files and Directories ++@section Files and Directories ++ ++@table @code ++ ++@item mm-default-directory ++@vindex mm-default-directory ++The default directory for saving attachments. If @code{nil} use ++@code{default-directory}. ++ ++@item mm-tmp-directory ++@vindex mm-tmp-directory ++Directory for storing temporary files. ++ ++@item mm-file-name-rewrite-functions ++@vindex mm-file-name-rewrite-functions ++A list of functions used for rewriting file names of @acronym{MIME} ++parts. Each function is applied successively to the file name. ++Ready-made functions include ++ ++@table @code ++@item mm-file-name-delete-control ++@findex mm-file-name-delete-control ++Delete all control characters. ++ ++@item mm-file-name-delete-gotchas ++@findex mm-file-name-delete-gotchas ++Delete characters that could have unintended consequences when used ++with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and ++@samp{-}, @samp{.} as the first character. ++ ++@item mm-file-name-delete-whitespace ++@findex mm-file-name-delete-whitespace ++Remove all whitespace. ++ ++@item mm-file-name-trim-whitespace ++@findex mm-file-name-trim-whitespace ++Remove leading and trailing whitespace. ++ ++@item mm-file-name-collapse-whitespace ++@findex mm-file-name-collapse-whitespace ++Collapse multiple whitespace characters. ++ ++@item mm-file-name-replace-whitespace ++@findex mm-file-name-replace-whitespace ++@vindex mm-file-name-replace-whitespace ++Replace whitespace with underscores. Set the variable ++@code{mm-file-name-replace-whitespace} to any other string if you do ++not like underscores. ++@end table ++ ++The standard Emacs functions @code{capitalize}, @code{downcase}, ++@code{upcase} and @code{upcase-initials} might also prove useful. ++ ++@item mm-path-name-rewrite-functions ++@vindex mm-path-name-rewrite-functions ++List of functions used for rewriting the full file names of @acronym{MIME} ++parts. This is used when viewing parts externally, and is meant for ++transforming the absolute name so that non-compliant programs can find ++the file where it's saved. ++ ++@end table ++ ++@node New Viewers ++@section New Viewers ++ ++Here's an example viewer for displaying @code{text/enriched} inline: ++ ++@lisp ++(defun mm-display-enriched-inline (handle) ++ (let (text) ++ (with-temp-buffer ++ (mm-insert-part handle) ++ (save-window-excursion ++ (enriched-decode (point-min) (point-max)) ++ (setq text (buffer-string)))) ++ (mm-insert-inline handle text))) ++@end lisp ++ ++We see that the function takes a @acronym{MIME} handle as its parameter. It ++then goes to a temporary buffer, inserts the text of the part, does some ++work on the text, stores the result, goes back to the buffer it was ++called from and inserts the result. ++ ++The two important helper functions here are @code{mm-insert-part} and ++@code{mm-insert-inline}. The first function inserts the text of the ++handle in the current buffer. It handles charset and/or content ++transfer decoding. The second function just inserts whatever text you ++tell it to insert, but it also sets things up so that the text can be ++``undisplayed'' in a convenient manner. ++ ++ ++@node Composing ++@chapter Composing ++@cindex Composing ++@cindex MIME Composing ++@cindex MML ++@cindex MIME Meta Language ++ ++Creating a @acronym{MIME} message is boring and non-trivial. Therefore, ++a library called @code{mml} has been defined that parses a language ++called @acronym{MML} (@acronym{MIME} Meta Language) and generates ++@acronym{MIME} messages. ++ ++@findex mml-generate-mime ++The main interface function is @code{mml-generate-mime}. It will ++examine the contents of the current (narrowed-to) buffer and return a ++string containing the @acronym{MIME} message. ++ ++@menu ++* Simple MML Example:: An example @acronym{MML} document. ++* MML Definition:: All valid @acronym{MML} elements. ++* Advanced MML Example:: Another example @acronym{MML} document. ++* Encoding Customization:: Variables that affect encoding. ++* Charset Translation:: How charsets are mapped from @sc{mule} to @acronym{MIME}. ++* Conversion:: Going from @acronym{MIME} to @acronym{MML} and vice versa. ++* Flowed text:: Soft and hard newlines. ++@end menu ++ ++ ++@node Simple MML Example ++@section Simple MML Example ++ ++Here's a simple @samp{multipart/alternative}: ++ ++@example ++<#multipart type=alternative> ++This is a plain text part. ++<#part type=text/enriched> ++
This is a centered enriched part
++<#/multipart> ++@end example ++ ++After running this through @code{mml-generate-mime}, we get this: ++ ++@example ++Content-Type: multipart/alternative; boundary="=-=-=" ++ ++ ++--=-=-= ++ ++ ++This is a plain text part. ++ ++--=-=-= ++Content-Type: text/enriched ++ ++ ++
This is a centered enriched part
++ ++--=-=-=-- ++@end example ++ ++ ++@node MML Definition ++@section MML Definition ++ ++The @acronym{MML} language is very simple. It looks a bit like an SGML ++application, but it's not. ++ ++The main concept of @acronym{MML} is the @dfn{part}. Each part can be of a ++different type or use a different charset. The way to delineate a part ++is with a @samp{<#part ...>} tag. Multipart parts can be introduced ++with the @samp{<#multipart ...>} tag. Parts are ended by the ++@samp{<#/part>} or @samp{<#/multipart>} tags. Parts started with the ++@samp{<#part ...>} tags are also closed by the next open tag. ++ ++There's also the @samp{<#external ...>} tag. These introduce ++@samp{external/message-body} parts. ++ ++Each tag can contain zero or more parameters on the form ++@samp{parameter=value}. The values may be enclosed in quotation marks, ++but that's not necessary unless the value contains white space. So ++@samp{filename=/home/user/#hello$^yes} is perfectly valid. ++ ++The following parameters have meaning in @acronym{MML}; parameters that have no ++meaning are ignored. The @acronym{MML} parameter names are the same as the ++@acronym{MIME} parameter names; the things in the parentheses say which ++header it will be used in. ++ ++@table @samp ++@item type ++The @acronym{MIME} type of the part (@code{Content-Type}). ++ ++@item filename ++Use the contents of the file in the body of the part ++(@code{Content-Disposition}). ++ ++@item charset ++The contents of the body of the part are to be encoded in the character ++set specified (@code{Content-Type}). @xref{Charset Translation}. ++ ++@item name ++Might be used to suggest a file name if the part is to be saved ++to a file (@code{Content-Type}). ++ ++@item disposition ++Valid values are @samp{inline} and @samp{attachment} ++(@code{Content-Disposition}). ++ ++@item encoding ++Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and ++@samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset ++Translation}. ++ ++@item description ++A description of the part (@code{Content-Description}). ++ ++@item creation-date ++RFC822 date when the part was created (@code{Content-Disposition}). ++ ++@item modification-date ++RFC822 date when the part was modified (@code{Content-Disposition}). ++ ++@item read-date ++RFC822 date when the part was read (@code{Content-Disposition}). ++ ++@item recipients ++Who to encrypt/sign the part to. This field is used to override any ++auto-detection based on the To/CC headers. ++ ++@item sender ++Identity used to sign the part. This field is used to override the ++default key used. ++ ++@item size ++The size (in octets) of the part (@code{Content-Disposition}). ++ ++@item sign ++What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp} ++or @code{pgpmime}) ++ ++@item encrypt ++What technology to encrypt this @acronym{MML} part with (@code{smime}, ++@code{pgp} or @code{pgpmime}) ++ ++@end table ++ ++Parameters for @samp{text/plain}: ++ ++@table @samp ++@item format ++Formatting parameter for the text, valid values include @samp{fixed} ++(the default) and @samp{flowed}. Normally you do not specify this ++manually, since it requires the textual body to be formatted in a ++special way described in RFC 2646. @xref{Flowed text}. ++@end table ++ ++Parameters for @samp{application/octet-stream}: ++ ++@table @samp ++@item type ++Type of the part; informal---meant for human readers ++(@code{Content-Type}). ++@end table ++ ++Parameters for @samp{message/external-body}: ++ ++@table @samp ++@item access-type ++A word indicating the supported access mechanism by which the file may ++be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp}, ++@samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.) ++ ++@item expiration ++The RFC822 date after which the file may no longer be fetched. ++(@code{Content-Type}.) ++ ++@item size ++The size (in octets) of the file. (@code{Content-Type}.) ++ ++@item permission ++Valid values are @samp{read} and @samp{read-write} ++(@code{Content-Type}). ++ ++@end table ++ ++Parameters for @samp{sign=smime}: ++ ++@table @samp ++ ++@item keyfile ++File containing key and certificate for signer. ++ ++@end table ++ ++Parameters for @samp{encrypt=smime}: ++ ++@table @samp ++ ++@item certfile ++File containing certificate for recipient. ++ ++@end table ++ ++ ++@node Advanced MML Example ++@section Advanced MML Example ++ ++Here's a complex multipart message. It's a @samp{multipart/mixed} that ++contains many parts, one of which is a @samp{multipart/alternative}. ++ ++@example ++<#multipart type=mixed> ++<#part type=image/jpeg filename=~/rms.jpg disposition=inline> ++<#multipart type=alternative> ++This is a plain text part. ++<#part type=text/enriched name=enriched.txt> ++
This is a centered enriched part
++<#/multipart> ++This is a new plain text part. ++<#part disposition=attachment> ++This plain text part is an attachment. ++<#/multipart> ++@end example ++ ++And this is the resulting @acronym{MIME} message: ++ ++@example ++Content-Type: multipart/mixed; boundary="=-=-=" ++ ++ ++--=-=-= ++ ++ ++ ++--=-=-= ++Content-Type: image/jpeg; ++ filename="~/rms.jpg" ++Content-Disposition: inline; ++ filename="~/rms.jpg" ++Content-Transfer-Encoding: base64 ++ ++/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof ++Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA ++AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR ++BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF ++RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip ++qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB ++AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI ++AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E ++sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m ++2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw ++5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc ++L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw ++34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm ++tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn ++7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC ++pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm ++jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q== ++ ++--=-=-= ++Content-Type: multipart/alternative; boundary="==-=-=" ++ ++ ++--==-=-= ++ ++ ++This is a plain text part. ++ ++--==-=-= ++Content-Type: text/enriched; ++ name="enriched.txt" ++ ++ ++
This is a centered enriched part
++ ++--==-=-=-- ++ ++--=-=-= ++ ++This is a new plain text part. ++ ++--=-=-= ++Content-Disposition: attachment ++ ++ ++This plain text part is an attachment. ++ ++--=-=-=-- ++@end example ++ ++@node Encoding Customization ++@section Encoding Customization ++ ++@table @code ++ ++@item mm-body-charset-encoding-alist ++@vindex mm-body-charset-encoding-alist ++Mapping from @acronym{MIME} charset to encoding to use. This variable is ++usually used except, e.g., when other requirements force a specific ++encoding (digitally signed messages require 7bit encodings). The ++default is ++ ++@lisp ++((iso-2022-jp . 7bit) ++ (iso-2022-jp-2 . 7bit) ++ (utf-16 . base64) ++ (utf-16be . base64) ++ (utf-16le . base64)) ++@end lisp ++ ++As an example, if you do not want to have ISO-8859-1 characters ++quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to ++this variable. You can override this setting on a per-message basis ++by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}). ++ ++@item mm-coding-system-priorities ++@vindex mm-coding-system-priorities ++Prioritize coding systems to use for outgoing messages. The default ++is @code{nil}, which means to use the defaults in Emacs, but is ++@code{(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8)} when ++running Emacs in the Japanese language environment. It is a list of ++coding system symbols (aliases of coding systems are also allowed, use ++@kbd{M-x describe-coding-system} to make sure you are specifying correct ++coding system names). For example, if you have configured Emacs ++to prefer UTF-8, but wish that outgoing messages should be sent in ++ISO-8859-1 if possible, you can set this variable to ++@code{(iso-8859-1)}. You can override this setting on a per-message ++basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}). ++ ++As different hierarchies prefer different charsets, you may want to set ++@code{mm-coding-system-priorities} according to the hierarchy in Gnus. ++Here's an example: ++ ++@c Corrections about preferred charsets are welcome. de, fr and fj ++@c should be correct, I don't know about the rest (so these are only ++@c examples): ++@lisp ++(add-to-list 'gnus-newsgroup-variables 'mm-coding-system-priorities) ++(setq gnus-parameters ++ (nconc ++ ;; Some charsets are just examples! ++ '(("^cn\\." ;; Chinese ++ (mm-coding-system-priorities ++ '(iso-8859-1 cn-big5 chinese-iso-7bit utf-8))) ++ ("^cz\\.\\|^pl\\." ;; Central and Eastern European ++ (mm-coding-system-priorities '(iso-8859-2 utf-8))) ++ ("^de\\." ;; German language ++ (mm-coding-system-priorities '(iso-8859-1 iso-8859-15 utf-8))) ++ ("^fr\\." ;; French ++ (mm-coding-system-priorities '(iso-8859-15 iso-8859-1 utf-8))) ++ ("^fj\\." ;; Japanese ++ (mm-coding-system-priorities ++ '(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8))) ++ ("^ru\\." ;; Cyrillic ++ (mm-coding-system-priorities ++ '(koi8-r iso-8859-5 iso-8859-1 utf-8)))) ++ gnus-parameters)) ++@end lisp ++ ++@item mm-content-transfer-encoding-defaults ++@vindex mm-content-transfer-encoding-defaults ++Mapping from @acronym{MIME} types to encoding to use. This variable is usually ++used except, e.g., when other requirements force a safer encoding ++(digitally signed messages require 7bit encoding). Besides the normal ++@acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for ++each case the most efficient of quoted-printable and base64 should be ++used. ++ ++@code{qp-or-base64} has another effect. It will fold long lines so that ++MIME parts may not be broken by MTA. So do @code{quoted-printable} and ++@code{base64}. ++ ++Note that it affects body encoding only when a part is a raw forwarded ++message (which will be made by @code{gnus-summary-mail-forward} with the ++arg 2 for example) or is neither the @samp{text/*} type nor the ++@samp{message/*} type. Even though in those cases, you can override ++this setting on a per-message basis by using the @code{encoding} ++@acronym{MML} tag (@pxref{MML Definition}). ++ ++@item mm-use-ultra-safe-encoding ++@vindex mm-use-ultra-safe-encoding ++When this is non-@code{nil}, it means that textual parts are encoded as ++quoted-printable if they contain lines longer than 76 characters or ++starting with "From " in the body. Non-7bit encodings (8bit, binary) ++are generally disallowed. This reduce the probability that a non-8bit ++clean MTA or MDA changes the message. This should never be set ++directly, but bound by other functions when necessary (e.g., when ++encoding messages that are to be digitally signed). ++ ++@end table ++ ++@node Charset Translation ++@section Charset Translation ++@cindex charsets ++ ++During translation from @acronym{MML} to @acronym{MIME}, for each ++@acronym{MIME} part which has been composed inside Emacs, an appropriate ++charset has to be chosen. ++ ++@vindex mail-parse-charset ++If you are running a non-@sc{mule} Emacs, this process is simple: If the ++part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset ++given by @code{mail-parse-charset} (a symbol) is used. (Never set this ++variable directly, though. If you want to change the default charset, ++please consult the documentation of the package which you use to process ++@acronym{MIME} messages. ++@xref{Various Message Variables, , Various Message Variables, message, ++ Message Manual}, for example.) ++If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is ++used, of course. ++ ++@cindex MULE ++@cindex UTF-8 ++@cindex Unicode ++@vindex mm-mime-mule-charset-alist ++Things are slightly more complicated when running Emacs with @sc{mule} ++support. In this case, a list of the @sc{mule} charsets used in the ++part is obtained, and the @sc{mule} charsets are translated to ++@acronym{MIME} charsets by consulting the table provided by Emacs itself ++or the variable @code{mm-mime-mule-charset-alist} for XEmacs. ++If this results in a single @acronym{MIME} charset, this is used to encode ++the part. But if the resulting list of @acronym{MIME} charsets contains more ++than one element, two things can happen: If it is possible to encode the ++part via UTF-8, this charset is used. (For this, Emacs must support ++the @code{utf-8} coding system, and the part must consist entirely of ++characters which have Unicode counterparts.) If UTF-8 is not available ++for some reason, the part is split into several ones, so that each one ++can be encoded with a single @acronym{MIME} charset. The part can only be ++split at line boundaries, though---if more than one @acronym{MIME} charset is ++required to encode a single line, it is not possible to encode the part. ++ ++When running Emacs with @sc{mule} support, the preferences for which ++coding system to use is inherited from Emacs itself. This means that ++if Emacs is set up to prefer UTF-8, it will be used when encoding ++messages. You can modify this by altering the ++@code{mm-coding-system-priorities} variable though (@pxref{Encoding ++Customization}). ++ ++The charset to be used can be overridden by setting the @code{charset} ++@acronym{MML} tag (@pxref{MML Definition}) when composing the message. ++ ++The encoding of characters (quoted-printable, 8bit etc) is orthogonal ++to the discussion here, and is controlled by the variables ++@code{mm-body-charset-encoding-alist} and ++@code{mm-content-transfer-encoding-defaults} (@pxref{Encoding ++Customization}). ++ ++@node Conversion ++@section Conversion ++ ++@findex mime-to-mml ++A (multipart) @acronym{MIME} message can be converted to @acronym{MML} ++with the @code{mime-to-mml} function. It works on the message in the ++current buffer, and substitutes @acronym{MML} markup for @acronym{MIME} ++boundaries. Non-textual parts do not have their contents in the buffer, ++but instead have the contents in separate buffers that are referred to ++from the @acronym{MML} tags. ++ ++@findex mml-to-mime ++An @acronym{MML} message can be converted back to @acronym{MIME} by the ++@code{mml-to-mime} function. ++ ++These functions are in certain senses ``lossy''---you will not get back ++an identical message if you run @code{mime-to-mml} and then ++@code{mml-to-mime}. Not only will trivial things like the order of the ++headers differ, but the contents of the headers may also be different. ++For instance, the original message may use base64 encoding on text, ++while @code{mml-to-mime} may decide to use quoted-printable encoding, and ++so on. ++ ++In essence, however, these two functions should be the inverse of each ++other. The resulting contents of the message should remain equivalent, ++if not identical. ++ ++ ++@node Flowed text ++@section Flowed text ++@cindex format=flowed ++ ++The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines} ++variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines, ++emacs, Emacs Manual}) when encoding a message, and the ++``format=flowed'' Content-Type parameter when decoding a message. ++ ++On encoding text, regardless of @code{use-hard-newlines}, lines ++terminated by soft newline characters are filled together and wrapped ++after the column decided by @code{fill-flowed-encode-column}. ++Quotation marks (matching @samp{^>* ?}) are respected. The variable ++controls how the text will look in a client that does not support ++flowed text, the default is to wrap after 66 characters. If hard ++newline characters are not present in the buffer, no flow encoding ++occurs. ++ ++On decoding flowed text, lines with soft newline characters are filled ++together and wrapped after the column decided by ++@code{fill-flowed-display-column}. The default is to wrap after ++@code{fill-column}. ++ ++@table @code ++@item mm-fill-flowed ++@vindex mm-fill-flowed ++If non-@code{nil} a format=flowed article will be displayed flowed. ++@end table ++ ++ ++@node Interface Functions ++@chapter Interface Functions ++@cindex interface functions ++@cindex mail-parse ++ ++The @code{mail-parse} library is an abstraction over the actual ++low-level libraries that are described in the next chapter. ++ ++Standards change, and so programs have to change to fit in the new ++mold. For instance, RFC2045 describes a syntax for the ++@code{Content-Type} header that only allows @acronym{ASCII} characters in the ++parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme ++for continuation headers and non-@acronym{ASCII} characters. ++ ++The traditional way to deal with this is just to update the library ++functions to parse the new syntax. However, this is sometimes the wrong ++thing to do. In some instances it may be vital to be able to understand ++both the old syntax as well as the new syntax, and if there is only one ++library, one must choose between the old version of the library and the ++new version of the library. ++ ++The Emacs @acronym{MIME} library takes a different tack. It defines a ++series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} ++and so on) that parses strictly according to the corresponding ++standard. However, normal programs would not use the functions ++provided by these libraries directly, but instead use the functions ++provided by the @code{mail-parse} library. The functions in this ++library are just aliases to the corresponding functions in the latest ++low-level libraries. Using this scheme, programs get a consistent ++interface they can use, and library developers are free to create ++write code that handles new standards. ++ ++The following functions are defined by this library: ++ ++@table @code ++@item mail-header-parse-content-type ++@findex mail-header-parse-content-type ++Parse a @code{Content-Type} header and return a list on the following ++format: ++ ++@lisp ++("type/subtype" ++ (attribute1 . value1) ++ (attribute2 . value2) ++ ...) ++@end lisp ++ ++Here's an example: ++ ++@example ++(mail-header-parse-content-type ++ "image/gif; name=\"b980912.gif\"") ++@result{} ("image/gif" (name . "b980912.gif")) ++@end example ++ ++@item mail-header-parse-content-disposition ++@findex mail-header-parse-content-disposition ++Parse a @code{Content-Disposition} header and return a list on the same ++format as the function above. ++ ++@item mail-content-type-get ++@findex mail-content-type-get ++Takes two parameters---a list on the format above, and an attribute. ++Returns the value of the attribute. ++ ++@example ++(mail-content-type-get ++ '("image/gif" (name . "b980912.gif")) 'name) ++@result{} "b980912.gif" ++@end example ++ ++@item mail-header-encode-parameter ++@findex mail-header-encode-parameter ++Takes a parameter string and returns an encoded version of the string. ++This is used for parameters in headers like @code{Content-Type} and ++@code{Content-Disposition}. ++ ++@item mail-header-remove-comments ++@findex mail-header-remove-comments ++Return a comment-free version of a header. ++ ++@example ++(mail-header-remove-comments ++ "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") ++@result{} "Gnus/5.070027 " ++@end example ++ ++@item mail-header-remove-whitespace ++@findex mail-header-remove-whitespace ++Remove linear white space from a header. Space inside quoted strings ++and comments is preserved. ++ ++@example ++(mail-header-remove-whitespace ++ "image/gif; name=\"Name with spaces\"") ++@result{} "image/gif;name=\"Name with spaces\"" ++@end example ++ ++@item mail-header-get-comment ++@findex mail-header-get-comment ++Return the last comment in a header. ++ ++@example ++(mail-header-get-comment ++ "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") ++@result{} "Finnish Landrace" ++@end example ++ ++@item mail-header-parse-address ++@findex mail-header-parse-address ++Parse an address and return a list containing the mailbox and the ++plaintext name. ++ ++@example ++(mail-header-parse-address ++ "Hrvoje Niksic ") ++@result{} ("hniksic@@srce.hr" . "Hrvoje Niksic") ++@end example ++ ++@item mail-header-parse-addresses ++@findex mail-header-parse-addresses ++Parse a string with list of addresses and return a list of elements like ++the one described above. ++ ++@example ++(mail-header-parse-addresses ++ "Hrvoje Niksic , Steinar Bang ") ++@result{} (("hniksic@@srce.hr" . "Hrvoje Niksic") ++ ("sb@@metis.no" . "Steinar Bang")) ++@end example ++ ++@item mail-header-parse-date ++@findex mail-header-parse-date ++Parse a date string and return an Emacs time structure. ++ ++@item mail-narrow-to-head ++@findex mail-narrow-to-head ++Narrow the buffer to the header section of the buffer. Point is placed ++at the beginning of the narrowed buffer. ++ ++@item mail-header-narrow-to-field ++@findex mail-header-narrow-to-field ++Narrow the buffer to the header under point. Understands continuation ++headers. ++ ++@item mail-header-fold-field ++@findex mail-header-fold-field ++Fold the header under point. ++ ++@item mail-header-unfold-field ++@findex mail-header-unfold-field ++Unfold the header under point. ++ ++@item mail-header-field-value ++@findex mail-header-field-value ++Return the value of the field under point. ++ ++@item mail-encode-encoded-word-region ++@findex mail-encode-encoded-word-region ++Encode the non-@acronym{ASCII} words in the region. For instance, ++@samp{Na@"{@dotless{i}}ve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}. ++ ++@item mail-encode-encoded-word-buffer ++@findex mail-encode-encoded-word-buffer ++Encode the non-@acronym{ASCII} words in the current buffer. This function is ++meant to be called narrowed to the headers of a message. ++ ++@item mail-encode-encoded-word-string ++@findex mail-encode-encoded-word-string ++Encode the words that need encoding in a string, and return the result. ++ ++@example ++(mail-encode-encoded-word-string ++ "This is na@"{@dotless{i}}ve, baby") ++@result{} "This is =?iso-8859-1?q?na=EFve,?= baby" ++@end example ++ ++@item mail-decode-encoded-word-region ++@findex mail-decode-encoded-word-region ++Decode the encoded words in the region. ++ ++@item mail-decode-encoded-word-string ++@findex mail-decode-encoded-word-string ++Decode the encoded words in the string and return the result. ++ ++@example ++(mail-decode-encoded-word-string ++ "This is =?iso-8859-1?q?na=EFve,?= baby") ++@result{} "This is na@"{@dotless{i}}ve, baby" ++@end example ++ ++@end table ++ ++Currently, @code{mail-parse} is an abstraction over @code{ietf-drums}, ++@code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented ++in the subsequent sections. ++ ++ ++ ++@node Basic Functions ++@chapter Basic Functions ++ ++This chapter describes the basic, ground-level functions for parsing and ++handling. Covered here is parsing @code{From} lines, removing comments ++from header lines, decoding encoded words, parsing date headers and so ++on. High-level functionality is dealt with in the first chapter ++(@pxref{Decoding and Viewing}). ++ ++@menu ++* rfc2045:: Encoding @code{Content-Type} headers. ++* rfc2231:: Parsing @code{Content-Type} headers. ++* ietf-drums:: Handling mail headers defined by RFC822bis. ++* rfc2047:: En/decoding encoded words in headers. ++* time-date:: Functions for parsing dates and manipulating time. ++* qp:: Quoted-Printable en/decoding. ++* base64:: Base64 en/decoding. ++* binhex:: Binhex decoding. ++* uudecode:: Uuencode decoding. ++* yenc:: Yenc decoding. ++* rfc1843:: Decoding HZ-encoded text. ++* mailcap:: How parts are displayed is specified by the @file{.mailcap} file ++@end menu ++ ++ ++@node rfc2045 ++@section rfc2045 ++ ++RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would ++imagine that there would be a lot to implement. But there isn't, since ++most of the implementation details are delegated to the subsequent ++RFCs. ++ ++So @file{rfc2045.el} has only a single function: ++ ++@table @code ++@item rfc2045-encode-string ++@findex rfc2045-encode-string ++Takes a parameter and a value and returns a @samp{PARAM=VALUE} string. ++@var{value} will be quoted if there are non-safe characters in it. ++@end table ++ ++ ++@node rfc2231 ++@section rfc2231 ++ ++RFC2231 defines a syntax for the @code{Content-Type} and ++@code{Content-Disposition} headers. Its snappy name is @dfn{MIME ++Parameter Value and Encoded Word Extensions: Character Sets, Languages, ++and Continuations}. ++ ++In short, these headers look something like this: ++ ++@example ++Content-Type: application/x-stuff; ++ title*0*=us-ascii'en'This%20is%20even%20more%20; ++ title*1*=%2A%2A%2Afun%2A%2A%2A%20; ++ title*2="isn't it!" ++@end example ++ ++They usually aren't this bad, though. ++ ++The following functions are defined by this library: ++ ++@table @code ++@item rfc2231-parse-string ++@findex rfc2231-parse-string ++Parse a @code{Content-Type} header and return a list describing its ++elements. ++ ++@example ++(rfc2231-parse-string ++ "application/x-stuff; ++ title*0*=us-ascii'en'This%20is%20even%20more%20; ++ title*1*=%2A%2A%2Afun%2A%2A%2A%20; ++ title*2=\"isn't it!\"") ++@result{} ("application/x-stuff" ++ (title . "This is even more ***fun*** isn't it!")) ++@end example ++ ++@item rfc2231-get-value ++@findex rfc2231-get-value ++Takes one of the lists on the format above and returns ++the value of the specified attribute. ++ ++@item rfc2231-encode-string ++@findex rfc2231-encode-string ++Encode a parameter in headers likes @code{Content-Type} and ++@code{Content-Disposition}. ++ ++@end table ++ ++ ++@node ietf-drums ++@section ietf-drums ++ ++@dfn{drums} is an IETF working group that is working on the replacement ++for RFC822. ++ ++The functions provided by this library include: ++ ++@table @code ++@item ietf-drums-remove-comments ++@findex ietf-drums-remove-comments ++Remove the comments from the argument and return the results. ++ ++@item ietf-drums-remove-whitespace ++@findex ietf-drums-remove-whitespace ++Remove linear white space from the string and return the results. ++Spaces inside quoted strings and comments are left untouched. ++ ++@item ietf-drums-get-comment ++@findex ietf-drums-get-comment ++Return the last most comment from the string. ++ ++@item ietf-drums-parse-address ++@findex ietf-drums-parse-address ++Parse an address string and return a list that contains the mailbox and ++the plain text name. ++ ++@item ietf-drums-parse-addresses ++@findex ietf-drums-parse-addresses ++Parse a string that contains any number of comma-separated addresses and ++return a list that contains mailbox/plain text pairs. ++ ++@item ietf-drums-parse-date ++@findex ietf-drums-parse-date ++Parse a date string and return an Emacs time structure. ++ ++@item ietf-drums-narrow-to-header ++@findex ietf-drums-narrow-to-header ++Narrow the buffer to the header section of the current buffer. ++ ++@end table ++ ++ ++@node rfc2047 ++@section rfc2047 ++ ++RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how ++non-@acronym{ASCII} text in headers are to be encoded. This is actually rather ++complicated, so a number of variables are necessary to tweak what this ++library does. ++ ++The following variables are tweakable: ++ ++@table @code ++@item rfc2047-header-encoding-alist ++@vindex rfc2047-header-encoding-alist ++This is an alist of header / encoding-type pairs. Its main purpose is ++to prevent encoding of certain headers. ++ ++The keys can either be header regexps, or @code{t}. ++ ++The values can be @code{nil}, in which case the header(s) in question ++won't be encoded, @code{mime}, which means that they will be encoded, or ++@code{address-mime}, which means the header(s) will be encoded carefully ++assuming they contain addresses. ++ ++@item rfc2047-charset-encoding-alist ++@vindex rfc2047-charset-encoding-alist ++RFC2047 specifies two forms of encoding---@code{Q} (a ++Quoted-Printable-like encoding) and @code{B} (base64). This alist ++specifies which charset should use which encoding. ++ ++@item rfc2047-encode-function-alist ++@vindex rfc2047-encode-function-alist ++This is an alist of encoding / function pairs. The encodings are ++@code{Q}, @code{B} and @code{nil}. ++ ++@item rfc2047-encoded-word-regexp ++@vindex rfc2047-encoded-word-regexp ++When decoding words, this library looks for matches to this regexp. ++ ++@item rfc2047-encoded-word-regexp-loose ++@vindex rfc2047-encoded-word-regexp-loose ++This is a version from which the regexp for the Q encoding pattern of ++@code{rfc2047-encoded-word-regexp} is made loose. ++ ++@item rfc2047-encode-encoded-words ++@vindex rfc2047-encode-encoded-words ++The boolean variable specifies whether encoded words ++(e.g. @samp{=?us-ascii?q?hello?=}) should be encoded again. ++@code{rfc2047-encoded-word-regexp} is used to look for such words. ++ ++@item rfc2047-allow-irregular-q-encoded-words ++@vindex rfc2047-allow-irregular-q-encoded-words ++The boolean variable specifies whether irregular Q encoded words ++(e.g. @samp{=?us-ascii?q?hello??=}) should be decoded. If it is ++non-@code{nil}, @code{rfc2047-encoded-word-regexp-loose} is used instead ++of @code{rfc2047-encoded-word-regexp} to look for encoded words. ++ ++@end table ++ ++Those were the variables, and these are this functions: ++ ++@table @code ++@item rfc2047-narrow-to-field ++@findex rfc2047-narrow-to-field ++Narrow the buffer to the header on the current line. ++ ++@item rfc2047-encode-message-header ++@findex rfc2047-encode-message-header ++Should be called narrowed to the header of a message. Encodes according ++to @code{rfc2047-header-encoding-alist}. ++ ++@item rfc2047-encode-region ++@findex rfc2047-encode-region ++Encodes all encodable words in the region specified. ++ ++@item rfc2047-encode-string ++@findex rfc2047-encode-string ++Encode a string and return the results. ++ ++@item rfc2047-decode-region ++@findex rfc2047-decode-region ++Decode the encoded words in the region. ++ ++@item rfc2047-decode-string ++@findex rfc2047-decode-string ++Decode a string and return the results. ++ ++@item rfc2047-encode-parameter ++@findex rfc2047-encode-parameter ++Encode a parameter in the RFC2047-like style. This is a replacement for ++the @code{rfc2231-encode-string} function. @xref{rfc2231}. ++ ++When attaching files as @acronym{MIME} parts, we should use the RFC2231 ++encoding to specify the file names containing non-@acronym{ASCII} ++characters. However, many mail softwares don't support it in practice ++and recipients won't be able to extract files with correct names. ++Instead, the RFC2047-like encoding is acceptable generally. This ++function provides the very RFC2047-like encoding, resigning to such a ++regrettable trend. To use it, put the following line in your ++@file{~/.gnus.el} file: ++ ++@lisp ++(defalias 'mail-header-encode-parameter 'rfc2047-encode-parameter) ++@end lisp ++ ++@end table ++ ++ ++@node time-date ++@section time-date ++ ++While not really a part of the @acronym{MIME} library, it is convenient to ++document this library here. It deals with parsing @code{Date} headers ++and manipulating time. (Not by using tesseracts, though, I'm sorry to ++say.) ++ ++These functions convert between five formats: A date string, an Emacs ++time structure, a decoded time list, a second number, and a day number. ++ ++Here's a bunch of time/date/second/day examples: ++ ++@example ++(parse-time-string "Sat Sep 12 12:21:54 1998 +0200") ++@result{} (54 21 12 12 9 1998 6 nil 7200) ++ ++(date-to-time "Sat Sep 12 12:21:54 1998 +0200") ++@result{} (13818 19266) ++ ++(time-to-seconds '(13818 19266)) ++@result{} 905595714.0 ++ ++(seconds-to-time 905595714.0) ++@result{} (13818 19266 0) ++ ++(time-to-days '(13818 19266)) ++@result{} 729644 ++ ++(days-to-time 729644) ++@result{} (961933 65536) ++ ++(time-since '(13818 19266)) ++@result{} (0 430) ++ ++(time-less-p '(13818 19266) '(13818 19145)) ++@result{} nil ++ ++(subtract-time '(13818 19266) '(13818 19145)) ++@result{} (0 121) ++ ++(days-between "Sat Sep 12 12:21:54 1998 +0200" ++ "Sat Sep 07 12:21:54 1998 +0200") ++@result{} 5 ++ ++(date-leap-year-p 2000) ++@result{} t ++ ++(time-to-day-in-year '(13818 19266)) ++@result{} 255 ++ ++(time-to-number-of-days ++ (time-since ++ (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) ++@result{} 4.146122685185185 ++@end example ++ ++And finally, we have @code{safe-date-to-time}, which does the same as ++@code{date-to-time}, but returns a zero time if the date is ++syntactically malformed. ++ ++The five data representations used are the following: ++ ++@table @var ++@item date ++An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12 ++12:21:54 1998 +0200"}. ++ ++@item time ++An internal Emacs time. For instance: @code{(13818 26466)}. ++ ++@item seconds ++A floating point representation of the internal Emacs time. For ++instance: @code{905595714.0}. ++ ++@item days ++An integer number representing the number of days since 00000101. For ++instance: @code{729644}. ++ ++@item decoded time ++A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t ++7200)}. ++@end table ++ ++All the examples above represent the same moment. ++ ++These are the functions available: ++ ++@table @code ++@item date-to-time ++Take a date and return a time. ++ ++@item time-to-seconds ++Take a time and return seconds. ++ ++@item seconds-to-time ++Take seconds and return a time. ++ ++@item time-to-days ++Take a time and return days. ++ ++@item days-to-time ++Take days and return a time. ++ ++@item date-to-day ++Take a date and return days. ++ ++@item time-to-number-of-days ++Take a time and return the number of days that represents. ++ ++@item safe-date-to-time ++Take a date and return a time. If the date is not syntactically valid, ++return a ``zero'' time. ++ ++@item time-less-p ++Take two times and say whether the first time is less (i. e., earlier) ++than the second time. ++ ++@item time-since ++Take a time and return a time saying how long it was since that time. ++ ++@item subtract-time ++Take two times and subtract the second from the first. I. e., return ++the time between the two times. ++ ++@item days-between ++Take two days and return the number of days between those two days. ++ ++@item date-leap-year-p ++Take a year number and say whether it's a leap year. ++ ++@item time-to-day-in-year ++Take a time and return the day number within the year that the time is ++in. ++ ++@end table ++ ++ ++@node qp ++@section qp ++ ++This library deals with decoding and encoding Quoted-Printable text. ++ ++Very briefly explained, qp encoding means translating all 8-bit ++characters (and lots of control characters) into things that look like ++@samp{=EF}; that is, an equal sign followed by the byte encoded as a hex ++string. ++ ++The following functions are defined by the library: ++ ++@table @code ++@item quoted-printable-decode-region ++@findex quoted-printable-decode-region ++QP-decode all the encoded text in the specified region. ++ ++@item quoted-printable-decode-string ++@findex quoted-printable-decode-string ++Decode the QP-encoded text in a string and return the results. ++ ++@item quoted-printable-encode-region ++@findex quoted-printable-encode-region ++QP-encode all the encodable characters in the specified region. The third ++optional parameter @var{fold} specifies whether to fold long lines. ++(Long here means 72.) ++ ++@item quoted-printable-encode-string ++@findex quoted-printable-encode-string ++QP-encode all the encodable characters in a string and return the ++results. ++ ++@end table ++ ++ ++@node base64 ++@section base64 ++@cindex base64 ++ ++Base64 is an encoding that encodes three bytes into four characters, ++thereby increasing the size by about 33%. The alphabet used for ++encoding is very resistant to mangling during transit. ++ ++The following functions are defined by this library: ++ ++@table @code ++@item base64-encode-region ++@findex base64-encode-region ++base64 encode the selected region. Return the length of the encoded ++text. Optional third argument @var{no-line-break} means do not break ++long lines into shorter lines. ++ ++@item base64-encode-string ++@findex base64-encode-string ++base64 encode a string and return the result. ++ ++@item base64-decode-region ++@findex base64-decode-region ++base64 decode the selected region. Return the length of the decoded ++text. If the region can't be decoded, return @code{nil} and don't ++modify the buffer. ++ ++@item base64-decode-string ++@findex base64-decode-string ++base64 decode a string and return the result. If the string can't be ++decoded, @code{nil} is returned. ++ ++@end table ++ ++ ++@node binhex ++@section binhex ++@cindex binhex ++@cindex Apple ++@cindex Macintosh ++ ++@code{binhex} is an encoding that originated in Macintosh environments. ++The following function is supplied to deal with these: ++ ++@table @code ++@item binhex-decode-region ++@findex binhex-decode-region ++Decode the encoded text in the region. If given a third parameter, only ++decode the @code{binhex} header and return the filename. ++ ++@end table ++ ++@node uudecode ++@section uudecode ++@cindex uuencode ++@cindex uudecode ++ ++@code{uuencode} is probably still the most popular encoding of binaries ++used on Usenet, although @code{base64} rules the mail world. ++ ++The following function is supplied by this package: ++ ++@table @code ++@item uudecode-decode-region ++@findex uudecode-decode-region ++Decode the text in the region. ++@end table ++ ++ ++@node yenc ++@section yenc ++@cindex yenc ++ ++@code{yenc} is used for encoding binaries on Usenet. The following ++function is supplied by this package: ++ ++@table @code ++@item yenc-decode-region ++@findex yenc-decode-region ++Decode the encoded text in the region. ++ ++@end table ++ ++ ++@node rfc1843 ++@section rfc1843 ++@cindex rfc1843 ++@cindex HZ ++@cindex Chinese ++ ++RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages. In ++essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this: ++ ++@example ++This sentence is in @acronym{ASCII}. ++The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye. ++@end example ++ ++Simple enough, and widely used in China. ++ ++The following functions are available to handle this encoding: ++ ++@table @code ++@item rfc1843-decode-region ++Decode HZ-encoded text in the region. ++ ++@item rfc1843-decode-string ++Decode a HZ-encoded string and return the result. ++ ++@end table ++ ++ ++@node mailcap ++@section mailcap ++ ++The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message ++handlers and describes how elements are supposed to be displayed. ++Here's an example file: ++ ++@example ++image/*; gimp -8 %s ++audio/wav; wavplayer %s ++application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc ++@end example ++ ++This says that all image files should be displayed with @code{gimp}, ++that WAVE audio files should be played by @code{wavplayer}, and that ++MS-WORD files should be inlined by @code{catdoc}. ++ ++The @code{mailcap} library parses this file, and provides functions for ++matching types. ++ ++@table @code ++@item mailcap-mime-data ++@vindex mailcap-mime-data ++This variable is an alist of alists containing backup viewing rules. ++ ++@end table ++ ++Interface functions: ++ ++@table @code ++@item mailcap-parse-mailcaps ++@findex mailcap-parse-mailcaps ++Parse the @file{~/.mailcap} file. ++ ++@item mailcap-mime-info ++Takes a @acronym{MIME} type as its argument and returns the matching viewer. ++ ++@end table ++ ++ ++ ++ ++@node Standards ++@chapter Standards ++ ++The Emacs @acronym{MIME} library implements handling of various elements ++according to a (somewhat) large number of RFCs, drafts and standards ++documents. This chapter lists the relevant ones. They can all be ++fetched from @uref{http://quimby.gnus.org/notes/}. ++ ++@table @dfn ++@item RFC822 ++@itemx STD11 ++Standard for the Format of ARPA Internet Text Messages. ++ ++@item RFC1036 ++Standard for Interchange of USENET Messages ++ ++@item RFC2045 ++Format of Internet Message Bodies ++ ++@item RFC2046 ++Media Types ++ ++@item RFC2047 ++Message Header Extensions for Non-@acronym{ASCII} Text ++ ++@item RFC2048 ++Registration Procedures ++ ++@item RFC2049 ++Conformance Criteria and Examples ++ ++@item RFC2231 ++@acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets, ++Languages, and Continuations ++ ++@item RFC1843 ++HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and ++@acronym{ASCII} characters ++ ++@item draft-ietf-drums-msg-fmt-05.txt ++Draft for the successor of RFC822 ++ ++@item RFC2112 ++The @acronym{MIME} Multipart/Related Content-type ++ ++@item RFC1892 ++The Multipart/Report Content Type for the Reporting of Mail System ++Administrative Messages ++ ++@item RFC2183 ++Communicating Presentation Information in Internet Messages: The ++Content-Disposition Header Field ++ ++@item RFC2646 ++Documentation of the text/plain format parameter for flowed text. ++ ++@end table ++ ++@node GNU Free Documentation License ++@chapter GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index ++@chapter Index ++@printindex cp ++ ++@bye ++ ++ ++@c Local Variables: ++@c mode: texinfo ++@c coding: iso-8859-1 ++@c End: ++ ++@ignore ++ arch-tag: c7ef2fd0-a91c-4e10-aa52-c1a2b11b1a8d ++@end ignore +diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi +new file mode 100644 +index 0000000..97a61cd +--- /dev/null ++++ b/doc/misc/epa.texi +@@ -0,0 +1,405 @@ ++\input texinfo @c -*- mode: texinfo -*- ++@c %**start of header ++@setfilename ../../info/epa ++@settitle EasyPG Assistant User's Manual ++@c %**end of header ++ ++@set VERSION 1.0.0 ++ ++@copying ++This file describes EasyPG Assistant @value{VERSION}. ++ ++Copyright @copyright{} 2007, 2008, 2009 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 Emacs 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.'' ++ ++This document is part of a collection distributed under the GNU Free ++Documentation License. If you want to distribute this document ++separately from the collection, you can do so by adding a copy of the ++license to the document, as described in section 6 of the license. ++@end quotation ++@end copying ++ ++@dircategory Emacs ++@direntry ++* EasyPG Assistant: (epa). An Emacs user interface to GNU Privacy Guard. ++@end direntry ++ ++@titlepage ++@title EasyPG Assistant ++ ++@author by Daiki Ueno ++@page ++ ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top ++@top EasyPG Assistant user's manual ++ ++EasyPG Assistant is an Emacs user interface to GNU Privacy Guard ++(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}). ++ ++EasyPG Assistant is a part of the package called EasyPG, an all-in-one ++GnuPG interface for Emacs. EasyPG also contains the library interface ++called EasyPG Library. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview:: ++* Quick start:: ++* Commands:: ++@end menu ++ ++@node Overview ++@chapter Overview ++ ++EasyPG Assistant provides the following features. ++ ++@itemize @bullet ++@item Key management. ++@item Cryptographic operations on regions. ++@item Cryptographic operations on files. ++@item Dired integration. ++@item Mail-mode integration. ++@item Automatic encryption/decryption of *.gpg files. ++@end itemize ++ ++@node Quick start ++@chapter Quick start ++ ++EasyPG Assistant commands are prefixed by @samp{epa-}. For example, ++ ++@itemize @bullet ++@item To browse your keyring, type @kbd{M-x epa-list-keys} ++ ++@item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region} ++ ++@item To encrypt a file, type @kbd{M-x epa-encrypt-file} ++@end itemize ++ ++EasyPG Assistant provides several cryptographic features which can be ++integrated into other Emacs functionalities. For example, automatic ++encryption/decryption of @samp{*.gpg} files. ++ ++To install these features, do @kbd{C-u 1 M-x epa-mode}. It can also ++be turned on by customize. Try @kbd{M-x customize-variable epa-mode}. ++ ++@node Commands ++@chapter Commands ++ ++This chapter introduces various commands for typical use cases. ++ ++@menu ++* Key management:: ++* Cryptographic operations on regions:: ++* Cryptographic operations on files:: ++* Dired integration:: ++* Mail-mode integration:: ++* Encrypting/decrypting *.gpg files:: ++@end menu ++ ++@node Key management ++@section Key management ++Probably the first step of using EasyPG Assistant is to browse your ++keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg ++--list-keys} from the command line. ++ ++@deffn Command epa-list-keys name mode ++Show all keys matched with @var{name} from the public keyring. ++@end deffn ++ ++@noindent ++The output looks as follows. ++ ++@example ++ u A5B6B2D4B15813FE Daiki Ueno ++@end example ++ ++@noindent ++A character on the leftmost column indicates the trust level of the ++key. If it is @samp{u}, the key is marked as ultimately trusted. The ++second column is the key ID, and the rest is the user ID. ++ ++You can move over entries by @key{TAB}. If you type @key{RET} or ++click button1 on an entry, you will see more detailed information ++about the key you selected. ++ ++@example ++ u Daiki Ueno ++ u A5B6B2D4B15813FE 1024bits DSA ++ Created: 2001-10-09 ++ Expires: 2007-09-04 ++ Capabilities: sign certify ++ Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE ++ u 4447461B2A9BEA2D 2048bits ELGAMAL_E ++ Created: 2001-10-09 ++ Expires: 2007-09-04 ++ Capabilities: encrypt ++ Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D ++@end example ++ ++@noindent ++To browse your private keyring, use @kbd{M-x epa-list-secret-keys}. ++ ++@deffn Command epa-list-secret-keys name ++Show all keys matched with @var{name} from the private keyring. ++@end deffn ++ ++@noindent ++In @samp{*Keys*} buffer, several commands are available. The common ++use case is to export some keys to a file. To do that, type @kbd{m} ++to select keys, type @kbd{o}, and then supply the filename. ++ ++Below are other commands related to key management. Some of them take ++a file as input/output, and others take the current region. ++ ++@deffn Command epa-insert-keys keys ++Insert selected @var{keys} after the point. It will let you select ++keys before insertion. By default, it will encode keys in the OpenPGP ++armor format. ++@end deffn ++ ++@deffn Command epa-import-keys file ++Import keys from @var{file} to your keyring. ++@end deffn ++ ++@deffn Command epa-import-keys-region start end ++Import keys from the current region between @var{start} and @var{end} ++to your keyring. ++@end deffn ++ ++@deffn Command epa-import-armor-in-region start end ++Import keys in the OpenPGP armor format in the current region between ++@var{start} and @var{end}. The difference from ++@code{epa-import-keys-region} is that ++@code{epa-import-armor-in-region} searches armors in the region and ++applies @code{epa-import-keys-region} to each of them. ++@end deffn ++ ++@deffn Command epa-delete-keys allow-secret ++Delete selected keys. If @var{allow-secret} is non-@code{nil}, it ++also delete the secret keys. ++@end deffn ++ ++@node Cryptographic operations on regions ++@section Cryptographic operations on regions ++ ++@deffn Command epa-decrypt-region start end ++Decrypt the current region between @var{start} and @var{end}. It ++replaces the region with the decrypted text. ++@end deffn ++ ++@deffn Command epa-decrypt-armor-in-region start end ++Decrypt OpenPGP armors in the current region between @var{start} and ++@var{end}. The difference from @code{epa-decrypt-region} is that ++@code{epa-decrypt-armor-in-region} searches armors in the region ++and applies @code{epa-decrypt-region} to each of them. That is, this ++command does not alter the original text around armors. ++@end deffn ++ ++@deffn Command epa-verify-region start end ++Verify the current region between @var{start} and @var{end}. It sends ++the verification result to the minibuffer or a popup window. It ++replaces the region with the signed text. ++@end deffn ++ ++@deffn Command epa-verify-cleartext-in-region ++Verify OpenPGP cleartext blocks in the current region between ++@var{start} and @var{end}. The difference from ++@code{epa-verify-region} is that @code{epa-verify-cleartext-in-region} ++searches OpenPGP cleartext blocks in the region and applies ++@code{epa-verify-region} to each of them. That is, this command does ++not alter the original text around OpenPGP cleartext blocks. ++@end deffn ++ ++@deffn Command epa-sign-region start end signers type ++Sign the current region between @var{start} and @var{end}. By ++default, it creates a cleartext signature. If a prefix argument is ++given, it will let you select signing keys, and then a signature ++type. ++@end deffn ++ ++@deffn Command epa-encrypt-region start end recipients sign signers ++Encrypt the current region between @var{start} and @var{end}. It will ++let you select recipients. If a prefix argument is given, it will ++also ask you whether or not to sign the text before encryption and if ++you answered yes, it will let you select the signing keys. ++@end deffn ++ ++@node Cryptographic operations on files ++@section Cryptographic operations on files ++ ++@deffn Command epa-decrypt-file file ++Decrypt @var{file}. ++@end deffn ++ ++@deffn Command epa-verify-file file ++Verify @var{file}. ++@end deffn ++ ++@deffn Command epa-sign-file file signers type ++Sign @var{file}. If a prefix argument is given, it will let you ++select signing keys, and then a signature type. ++@end deffn ++ ++@deffn Command epa-encrypt-file file recipients ++Encrypt @var{file}. It will let you select recipients. ++@end deffn ++ ++@node Dired integration ++@section Dired integration ++ ++EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to ++easily do cryptographic operations on files. For example, ++ ++@example ++M-x dired ++(mark some files) ++: e (or M-x epa-dired-do-encrypt) ++(select recipients by 'm' and click [OK]) ++@end example ++ ++@noindent ++The following keys are assigned. ++ ++@table @kbd ++@item : d ++@kindex @kbd{: d} ++@findex epa-dired-do-decrypt ++Decrypt marked files. ++ ++@item : v ++@kindex @kbd{: v} ++@findex epa-dired-do-verify ++Verify marked files. ++ ++@item : s ++@kindex @kbd{: s} ++@findex epa-dired-do-sign ++Sign marked files. ++ ++@item : e ++@kindex @kbd{: e} ++@findex epa-dired-do-encrypt ++Encrypt marked files. ++ ++@end table ++ ++@node Mail-mode integration ++@section Mail-mode integration ++ ++EasyPG Assistant provides a minor mode to help user compose inline PGP ++messages. Inline PGP is sending the OpenPGP blobs directly inside a ++mail message and it is not recommended and you should consider to use ++PGP/MIME. See ++@uref{http://josefsson.org/inline-openpgp-considered-harmful.html, ++Inline PGP in E-mail is bad, Mm'kay?}. ++ ++@noindent ++The following keys are assigned. ++ ++@table @kbd ++@item C-c C-e d ++@kindex @kbd{C-c C-e d} ++@findex epa-mail-decrypt ++Decrypt OpenPGP armors in the current buffer. ++ ++@item C-c C-e v ++@kindex @kbd{C-c C-e v} ++@findex epa-mail-verify ++Verify OpenPGP cleartext signed messages in the current buffer. ++ ++@item C-c C-e s ++@kindex @kbd{C-c C-e s} ++@findex epa-mail-sign ++Compose a signed message from the current buffer. ++ ++@item C-c C-e e ++@kindex @kbd{C-c C-e e} ++@findex epa-mail-encrypt ++Compose an encrypted message from the current buffer. ++By default it tries to build the recipient list from @samp{to}, ++@samp{cc}, and @samp{bcc} fields of the mail header. To include your ++key in the recipient list, use @samp{encrypt-to} option in ++@file{~/.gnupg/gpg.conf}. ++ ++@end table ++ ++@node Encrypting/decrypting *.gpg files ++@section Encrypting/decrypting *.gpg files ++Once @code{epa-setup} is loaded, every file whose extension is ++@samp{.gpg} will be treated as encrypted. That is, when you attempt ++to open such a file which already exists, the decrypted text is ++inserted in the buffer rather than encrypted one. On the other hand, ++when you attempt to save the buffer to a file whose extension is ++@samp{.gpg}, encrypted data is written. ++ ++If you want to temporarily disable this behavior, use @kbd{M-x ++epa-file-disable}, and then to enable this behavior use @kbd{M-x ++epa-file-enable}. ++ ++@deffn Command epa-file-disable ++Disable automatic encryption/decryption of *.gpg files. ++@end deffn ++ ++@deffn Command epa-file-enable ++Enable automatic encryption/decryption of *.gpg files. ++@end deffn ++ ++@noindent ++@code{epa-file} will let you select recipients. If you want to ++suppress this question, it might be a good idea to put the following ++line on the first line of the text being encrypted. ++@vindex epa-file-encrypt-to ++ ++@cartouche ++@lisp ++;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*- ++@end lisp ++@end cartouche ++ ++The file name extension of encrypted files can be controlled by ++@var{epa-file-name-regexp}. ++ ++@defvar epa-file-name-regexp ++Regexp which matches filenames treated as encrypted. ++@end defvar ++ ++Other variables which control the automatic encryption/decryption ++behavior are below. ++ ++@defvar epa-file-cache-passphrase-for-symmetric-encryption ++If non-@code{nil}, cache passphrase for symmetric encryption. The ++default value is @code{nil}. ++@end defvar ++ ++@defvar epa-file-inhibit-auto-save ++If non-@code{nil}, disable auto-saving when opening an encrypted file. ++The default value is @code{t}. ++@end defvar ++ ++@bye ++ ++@c End: ++ ++@ignore ++ arch-tag: 7404e246-7d4c-4db4-9332-c1293a455a4f ++@end ignore +diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi +new file mode 100644 +index 0000000..09e9479 +--- /dev/null ++++ b/doc/misc/erc.texi +@@ -0,0 +1,1066 @@ ++\input texinfo ++@c %**start of header ++@setfilename ../../info/erc ++@settitle ERC Manual ++@syncodeindex fn cp ++@c %**end of header ++ ++@copying ++This manual is for ERC version 5.3. ++ ++Copyright @copyright{} 2005, 2006, 2007, 2008, 2009 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.'' ++ ++All Emacs Lisp code contained in this document may be used, distributed, ++and modified without restriction. ++@end quotation ++@end copying ++ ++@dircategory Emacs ++@direntry ++* ERC: (erc). Powerful, modular, and extensible IRC client for Emacs. ++@end direntry ++ ++@titlepage ++@title ERC manual ++@subtitle a full-featured IRC client ++@subtitle for GNU Emacs and XEmacs ++ ++@c The following two commands ++@c start the copyright page. ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top, Introduction, (dir), (dir) ++@comment node-name, next, previous, up ++@top ERC ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* Introduction:: What is ERC? ++* Obtaining ERC:: How to get ERC releases and development ++ versions. ++* Installation:: Compiling and installing ERC. ++* Getting Started:: Quick Start guide to using ERC. ++* Keystroke Summary:: Keystrokes used in ERC buffers. ++* Modules:: Available modules for ERC. ++* Advanced Usage:: Cool ways of using ERC. ++* Getting Help and Reporting Bugs:: ++* History:: The history of ERC. ++* Copying:: The GNU General Public License gives you ++ permission to redistribute ERC on ++ certain terms; it also explains that ++ there is no warranty. ++* GNU Free Documentation License:: The license for this documentation. ++* Concept Index:: Search for terms. ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ ++Obtaining ERC ++ ++* Releases:: Released versions of ERC. ++* Development:: Latest unreleased development changes. ++ ++Getting Started ++ ++* Sample Session:: Example of connecting to the #emacs channel ++* Special Features:: Differences from standalone IRC clients ++ ++Advanced Usage ++ ++* Connecting:: Ways of connecting to an IRC server. ++* Sample Configuration:: An example configuration file. ++* Options:: Options that are available for ERC. ++ ++@end detailmenu ++@end menu ++ ++@node Introduction, Obtaining ERC, Top, Top ++@comment node-name, next, previous, up ++@chapter Introduction ++ ++ERC is a powerful, modular, and extensible IRC client for Emacs. ++ ++It comes with the following capabilities enabled by default. ++ ++@itemize @bullet ++@item Flood control ++@item Timestamps ++@item Join channels automatically ++@item Buttonize URLs, nicknames, and other text ++@item Wrap long lines ++@item Highlight or remove IRC control characters ++@item Highlight pals, fools, and other keywords ++@item Detect netsplits ++@item Complete nicknames and commands in a programmable fashion ++@item Make displayed lines read-only ++@item Input history ++@item Track channel activity in the mode-line ++ ++@end itemize ++ ++@node Obtaining ERC, Installation, Introduction, Top ++@comment node-name, next, previous, up ++@chapter Obtaining ERC ++ ++@menu ++* Releases:: Released versions of ERC. ++* Development:: Latest unreleased development changes. ++@end menu ++ ++Note that some ERC files are not included with Emacs due to copyright or ++dependency issues. If desired, they may be found at the following ++locations, or from your local GNU mirror. ++ ++@itemize @bullet ++@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.3-extras.tar.gz} ++@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.3-extras.zip} ++@end itemize ++ ++The rest of this chapter may be skipped if you are using the version of ++ERC that comes with Emacs. ++ ++@node Releases, Development, Obtaining ERC, Obtaining ERC ++@comment node-name, next, previous, up ++@section Releases ++ ++Choose to install a release if you want to minimize risk. ++ ++Errors are corrected in development first. User-visible changes will be ++announced on the @email{erc-discuss@@gnu.org} mailing list. ++@pxref{Getting Help and Reporting Bugs}. ++ ++@cindex releases, Debian package ++@cindex Debian package for ERC ++Debian users can get ERC via apt-get. The @file{erc} package is ++available in the official Debian repository. ++ ++@cindex releases, from source ++Alternatively, you can download the latest release from ++@uref{http://ftp.gnu.org/gnu/erc}, or your local GNU mirror. ++ ++@node Development, , Releases, Obtaining ERC ++@comment node-name, next, previous, up ++@section Development ++@cindex development ++ ++Choose the development version if you want to live on the bleeding edge ++of ERC development or try out new features before release. ++ ++@cindex git version control system, using ++The git version control system allows you to keep up-to-date with the ++latest changes to the development version of ERC. It also allows you ++to contribute changes (via commits, if you are have developer access to ++the repository, or via patches, otherwise). If you would like to ++contribute to ERC development, it is highly recommended that you use ++git. ++ ++If you are new to git, you might find this tutorial helpful: ++@uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}. ++ ++Downloading ERC with git and staying up-to-date involves the following ++steps. ++ ++@enumerate ++@item Install git. ++ ++@itemize @bullet ++@item Debian and Ubuntu: @kbd{apt-get install git-core}. ++@item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}. ++@item Other operating systems: download, compile, and install the source ++from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git ++package for your operating system. ++@end itemize ++ ++@item Download the ERC development branch. ++ ++If you have developer access to ERC, do: ++ ++@example ++git clone ssh://loginname@@git.sv.gnu.org/srv/git/erc.git ++@end example ++ ++otherwise, do: ++ ++@example ++git clone git://git.sv.gnu.org/erc.git ++@end example ++ ++If you are behind a restrictive firewall, and do not have developer ++access, then do the following instead: ++ ++@example ++git clone http://git.sv.gnu.org/r/erc.git ++@end example ++ ++@item List upstream changes that are missing from your local copy. ++Do this whenever you want to see whether new changes have been committed ++to ERC. If you wish, you may skip this step and proceed directly to ++the ``update'' step. ++ ++@example ++# Change to the source directory you are interested in. ++cd erc ++ ++# Fetch new changes from the repository, but don't apply them yet ++git fetch origin ++ ++# Display log messages for the new changes ++git log HEAD..origin ++@end example ++ ++``origin'' is git's name for the location where you originally got ERC ++from. You can change this location at any time by editing the ++@file{.git/config} file in the directory where the ERC source was ++placed. ++ ++@cindex updating ERC with git ++@item Update to the latest version by pulling in any missing changes. ++ ++@example ++cd erc ++git pull origin ++@end example ++ ++git will show how many files changed, and will provide a visual display ++for how many lines were changed in each file. ++ ++@end enumerate ++ ++There are other ways to interact with the ERC repository. ++ ++@itemize ++@item Browse git repo: @uref{http://git.sv.gnu.org/gitweb/?p=erc.git} ++@item Latest development snapshot: @uref{http://mwolson.org/static/dist/erc-latest.tar.gz} ++@item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/erc-latest.zip} ++@end itemize ++ ++The latest development snapshot can lag behind the git repo by as much ++as 20 minutes, but never more than that. ++ ++For further information on committing changes to ERC and performing ++development, please consult ++@uref{http://emacswiki.org/cgi-bin/wiki/ErcDevelopment}. ++ ++ ++@node Installation, Getting Started, Obtaining ERC, Top ++@comment node-name, next, previous, up ++@chapter Installation ++ ++ERC may be compiled and installed on your machine. ++ ++This section may be skipped if you are using the version of ERC that ++comes with Emacs. ++ ++@subsubheading Compilation ++ ++This is an optional step, since Emacs Lisp source code does not ++necessarily have to be byte-compiled. It will yield a speed increase, ++though. ++ ++A working copy of Emacs or XEmacs is needed in order to compile ERC. By ++default, the program that is installed with the name @command{emacs} ++will be used. ++ ++If you want to use the @command{xemacs} binary to perform the ++compilation, you would need to edit @file{Makefile} in the top-level ++directory as follows. You can put either a full path to an Emacs or ++XEmacs binary or just the command name, as long as it is in the ++@env{PATH}. ++ ++@example ++EMACS = xemacs ++SITEFLAG = -no-site-file ++@end example ++ ++Running @code{make} should compile the ERC source files in the ++@file{lisp} directory. ++ ++@subsubheading Installation ++ ++ERC may be installed into your file hierarchy by doing the following. ++ ++Edit the @file{Makefile} file so that @env{ELISPDIR} points to where you ++want the source and compiled ERC files to be installed and ++@env{INFODIR} indicates where to put the ERC manual. Of course, you ++will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the ++Compilation section if you are using XEmacs. ++ ++If you are installing ERC on a Debian system, you might want to change ++the value of @env{INSTALLINFO} as specified in @file{Makefile}. ++ ++Run @code{make} as a normal user. ++ ++Run @code{make install} as the root user if you have chosen installation ++locations that require this. ++ ++ ++@node Getting Started, Keystroke Summary, Installation, Top ++@comment node-name, next, previous, up ++@chapter Getting Started ++@cindex settings ++ ++To use ERC, add the directory containing its files to your ++@code{load-path} variable, in your @file{.emacs} file. Then, load ERC ++itself. An example follows. ++ ++@lisp ++(require 'erc) ++@end lisp ++ ++Once ERC is loaded, the command @kbd{M-x erc} will start ERC and ++prompt for the server to connect to. ++ ++If you want to place ERC settings in their own file, you can place them ++in @file{~/.emacs.d/.ercrc.el}, creating it if necessary. ++ ++If you would rather use the Customize interface to change how ERC works, ++do @kbd{M-x customize-group RET erc RET}. In particular, ERC comes with ++lots of modules that may be enabled or disabled; to select which ones ++you want, do @kbd{M-x customize-variable RET erc-modules RET}. ++ ++@menu ++* Sample Session:: Example of connecting to the #emacs channel ++* Special Features:: Differences from standalone IRC clients ++@end menu ++ ++@node Sample Session, Special Features, Getting Started, Getting Started ++@comment node-name, next, previous, up ++@section Sample Session ++ ++This is an example ERC session which shows how to connect to the #emacs ++channel on Freenode. Another IRC channel on Freenode that may be of ++interest is #erc, which is a channel where ERC users and developers hang ++out. ++ ++@itemize @bullet ++ ++@item Connect to Freenode ++ ++Run @kbd{M-x erc}. Use ``irc.freenode.net'' as the IRC server, ``6667'' ++as the port, and choose a nickname. ++ ++@item Get used to the interface ++ ++Switch to the ``irc.freenode.net:6667'' buffer, if you're not already ++there. You will see first some messages about checking for ident, and ++then a bunch of other messages that describe the current IRC server. ++ ++@item Join the #emacs channel ++ ++In that buffer, type ``/join SPC #emacs'' and hit @kbd{RET}. Depending ++on how you've set up ERC, either a new buffer for ``#emacs'' will be ++displayed, or a new buffer called ``#emacs'' will be created in the ++background. If the latter, switch to the ``#emacs'' buffer. You will ++see the channel topic and a list of the people who are currently on the ++channel. ++ ++@item Register your nickname with Freenode ++ ++If you would like to be able to talk with people privately on the ++Freenode network, you will have to ``register'' your nickname. To do ++so, switch to the ``irc.freenode.net:6667'' buffer and type ``/msg ++NickServ register '', replacing ``'' with your ++desired password. It should tell you that the operation was successful. ++ ++@item Talk to people in the channel ++ ++If you switch back to the ``#emacs'' buffer, you can type a message, and ++everyone on the channel will see it. ++ ++@item Open a query buffer to talk to someone ++ ++If you want to talk with someone in private (this should usually not be ++done for technical help, only for personal questions), type ``/query ++'', replacing ``'' with the nickname of the person you would ++like to talk to. Depending on how ERC is set up, you will either see a ++new buffer with the name of the person, or such a buffer will be created ++in the background and you will have to switch to it. Begin typing ++messages, and you will be able to have a conversation. ++ ++Note that if the other person is not registered, you will not be able to ++talk with them. ++ ++@end itemize ++ ++@node Special Features, , Sample Session, Getting Started ++@comment node-name, next, previous, up ++@section Special Features ++ ++ERC has some features that distinguish it from some IRC clients. ++ ++@itemize @bullet ++ ++@item multiple channels and multiple servers ++ ++Every channel is put in a separate buffer. Several IRC servers may be ++connected to at the same time. ++ ++@cindex query buffers ++@item private message separation ++ ++Private conversations are treated as channels, and are put into separate ++buffers in Emacs. We call these ``query buffers''. ++ ++@item highlighting ++ ++Some occurrences of words can be highlighted, which makes it easier to ++track different kinds of conversations. ++ ++@item notification ++ ++ERC can notify you that certain users are online. ++ ++@item channel tracking ++ ++Channels can be hidden and conversation continue in the background. You ++are notified when something is said in such a channel that is not ++currently visible. This makes it easy to get Real Work done while still ++maintaining an IRC presence. ++ ++@item nick completion ++ ++ERC can complete words upon hitting @kbd{TAB}, which eases the writing ++of nicknames in messages. ++ ++@cindex history ring ++@item history ++ ++Past actions are kept in history rings for future use. To navigate a ++history ring, hit @kbd{M-p} to go backwards and @kbd{M-n} to go ++forwards. ++ ++@item multiple languages ++ ++Different channels and servers may have different language encodings. ++ ++In addition, it is possible to translate the messages that ERC uses into ++multiple languages. Please contact the developers of ERC at ++@email{erc-discuss@@gnu.org} if you are interested in helping with the ++translation effort. ++ ++@item user scripting ++ ++Users can load scripts (e.g. auto greeting scripts) when ERC starts up. ++ ++It is also possible to make custom IRC commands, if you know a little ++Emacs Lisp. Just make an Emacs Lisp function and call it ++@code{erc-cmd-NEWCOMMAND}, where @code{NEWCOMMAND} is the name of the ++new command in capital letters. ++ ++@item auto reconnect ++ ++If the connection goes away at some point, ERC will try to reconnect ++automatically. If it fails to reconnect, and you want to try to ++manually reestablish the connection at some later point, switch to an ++ERC buffer and run the @code{/RECONNECT} command. ++ ++@end itemize ++ ++ ++@node Keystroke Summary, Modules, Getting Started, Top ++@comment node-name, next, previous, up ++@chapter Keys Used in ERC ++@cindex keystrokes ++ ++This is a summary of keystrokes available in every ERC buffer. ++ ++@table @kbd ++ ++@item C-a or (`erc-bol') ++Go to beginning of line or end of prompt. ++ ++@item RET (`erc-send-current-line') ++Send the current line ++ ++@item TAB (`erc-complete-word') ++If at prompt, complete the current word. ++Otherwise, move to the next link or button. ++ ++@item M-TAB (`ispell-complete-word') ++Complete the given word, using ispell. ++ ++@item C-c C-a (`erc-bol') ++Go to beginning of line or end of prompt. ++ ++@item C-c C-b (`erc-iswitchb') ++Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to. ++ ++@item C-c C-c (`erc-toggle-interpret-controls') ++Toggle interpretation of control sequences in messages. ++ ++@item C-c C-d (`erc-input-action') ++Interactively input a user action and send it to IRC. ++ ++@item C-c C-e (`erc-toggle-ctcp-autoresponse') ++Toggle automatic CTCP replies (like VERSION and PING). ++ ++@item C-c C-f (`erc-toggle-flood-control') ++Toggle use of flood control on sent messages. ++ ++@item C-c TAB (`erc-invite-only-mode') ++Turn on the invite only mode (+i) for the current channel. ++ ++@item C-c C-j (`erc-join-channel') ++Join channel. If point is at the beginning of a channel name, use that ++as default. ++ ++@item C-c C-k (`erc-go-to-log-matches-buffer') ++Interactively open an erc-log-matches buffer ++ ++@item C-c C-l (`erc-save-buffer-in-logs') ++Append buffer contents to the log file, if logging is enabled. ++ ++@item C-c C-n (`erc-channel-names') ++Run "/names #channel" in the current channel. ++ ++@item C-c C-o (`erc-get-channel-mode-from-keypress') ++Read a key sequence and call the corresponding channel mode function. ++After doing @kbd{C-c C-o}, type in a channel mode letter. ++ ++@kbd{C-g} means quit. ++@kbd{RET} lets you type more than one mode at a time. ++If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called. ++If @kbd{k} is pressed, @code{erc-set-channel-key} gets called. ++Anything else will be sent to `erc-toggle-channel-mode'. ++ ++@item C-c C-p (`erc-part-from-channel') ++Part from the current channel and prompt for a reason. ++ ++@item C-c C-q (`erc-quit-server') ++Disconnect from current server after prompting for reason. ++ ++@item C-c C-r (`erc-remove-text-properties-region') ++Clears the region (start,end) in object from all colors, etc. ++ ++@item C-c C-t (`erc-set-topic') ++Prompt for a topic for the current channel. ++ ++@item C-c C-u (`erc-kill-input') ++Kill current input line using `erc-bol' followed by `kill-line'. ++ ++@end table ++ ++ ++@node Modules, Advanced Usage, Keystroke Summary, Top ++@comment node-name, next, previous, up ++@chapter Modules ++@cindex modules ++ ++One way to add functionality to ERC is to customize which of its many ++modules are loaded. ++ ++There is a spiffy customize interface, which may be reached by typing ++@kbd{M-x customize-option erc-modules RET}. Alternatively, set ++@code{erc-modules} manually and then call @code{erc-update-modules}. ++ ++The following is a list of available modules. ++ ++@table @code ++ ++@cindex modules, autoaway ++@item autoaway ++Set away status automatically ++ ++@cindex modules, autojoin ++@item autojoin ++Join channels automatically ++ ++@cindex modules, bbdb ++@item bbdb ++Integrate with the Big Brother Database ++ ++@cindex modules, button ++@item button ++Buttonize URLs, nicknames, and other text ++ ++@cindex modules, capab-identify ++@item capab-identify ++Mark unidentified users on freenode and other servers supporting CAPAB. ++ ++@cindex modules, completion ++@cindex modules, pcomplete ++@item completion (aka pcomplete) ++Complete nicknames and commands (programmable) ++ ++@cindex modules, fill ++@item fill ++Wrap long lines ++ ++@cindex modules, hecomplete ++@item hecomplete ++Complete nicknames and commands (old). This is the old module---you ++might prefer the ``completion'' module instead. ++ ++@cindex modules, identd ++@item identd ++Launch an identd server on port 8113 ++ ++@cindex modules, irccontrols ++@item irccontrols ++Highlight or remove IRC control characters ++ ++@cindex modules, log ++@item log ++Save buffers in logs ++ ++@cindex modules, match ++@item match ++Highlight pals, fools, and other keywords ++ ++@cindex modules, menu ++@item menu ++Display a menu in ERC buffers ++ ++@cindex modules, netsplit ++@item netsplit ++Detect netsplits ++ ++@cindex modules, noncommands ++@item noncommands ++Don't display non-IRC commands after evaluation ++ ++@cindex modules, notify ++@item notify ++Notify when the online status of certain users changes ++ ++@cindex modules, page ++@item page ++Process CTCP PAGE requests from IRC ++ ++@cindex modules, readonly ++@item readonly ++Make displayed lines read-only ++ ++@cindex modules, replace ++@item replace ++Replace text in messages ++ ++@cindex modules, ring ++@item ring ++Enable an input history ++ ++@cindex modules, scrolltobottom ++@item scrolltobottom ++Scroll to the bottom of the buffer ++ ++@cindex modules, services ++@item services ++Identify to Nickserv (IRC Services) automatically ++ ++@cindex modules, smiley ++@item smiley ++Convert smileys to pretty icons ++ ++@cindex modules, sound ++@item sound ++Play sounds when you receive CTCP SOUND requests ++ ++@cindex modules, spelling ++@item spelling ++Check spelling of messages ++ ++@cindex modules, stamp ++@item stamp ++Add timestamps to messages ++ ++@cindex modules, track ++@item track ++Track channel activity in the mode-line ++ ++@cindex modules, truncate ++@item truncate ++Truncate buffers to a certain size ++ ++@cindex modules, unmorse ++@item unmorse ++Translate morse code in messages ++ ++@end table ++ ++@c PRE5_4: Document every option of every module in its own subnode ++ ++ ++@node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top ++@comment node-name, next, previous, up ++@chapter Advanced Usage ++@cindex advanced topics ++ ++@menu ++* Connecting:: Ways of connecting to an IRC server. ++* Sample Configuration:: An example configuration file. ++* Options:: Options that are available for ERC. ++@end menu ++ ++@node Connecting, Sample Configuration, Advanced Usage, Advanced Usage ++@comment node-name, next, previous, up ++@section Connecting to an IRC Server ++@cindex connecting ++ ++The easiest way to connect to an IRC server is to call @kbd{M-x erc}. ++If you want to assign this function to a keystroke, the following will ++help you figure out its parameters. ++ ++@defun erc ++Select connection parameters and run ERC. ++Non-interactively, it takes the following keyword arguments. ++ ++@itemize @bullet ++@item @var{server} ++@item @var{port} ++@item @var{nick} ++@item @var{password} ++@item @var{full-name} ++@end itemize ++ ++That is, if called with the following arguments, @var{server} and ++@var{full-name} will be set to those values, whereas ++@code{erc-compute-port}, @code{erc-compute-nick} and ++@code{erc-compute-full-name} will be invoked for the values of the other ++parameters. ++ ++@example ++(erc :server "irc.freenode.net" :full-name "Harry S Truman") ++@end example ++@end defun ++ ++@subheading Server ++ ++@defun erc-compute-server &optional server ++Return an IRC server name. ++ ++This tries a number of increasingly more default methods until a non-nil ++value is found. ++ ++@itemize @bullet ++@item @var{server} (the argument passed to this function) ++@item The @code{erc-server} option ++@item The value of the IRCSERVER environment variable ++@item The @code{erc-default-server} variable ++@end itemize ++ ++@end defun ++ ++@defopt erc-server nil ++IRC server to use if one is not provided. ++@end defopt ++ ++@subheading Port ++ ++@defun erc-compute-port &optional port ++Return a port for an IRC server. ++ ++This tries a number of increasingly more default methods until a non-nil ++value is found. ++ ++@itemize @bullet ++@item @var{port} (the argument passed to this function) ++@item The @code{erc-port} option ++@item The @code{erc-default-port} variable ++@end itemize ++ ++@end defun ++ ++@defopt erc-port ++IRC port to use if not specified. ++ ++This can be either a string or a number. ++@end defopt ++ ++@subheading Nick ++ ++@defun erc-compute-nick &optional nick ++Return user's IRC nick. ++ ++This tries a number of increasingly more default methods until a ++non-nil value is found. ++ ++@itemize ++@item @var{nick} (the argument passed to this function) ++@item The @code{erc-nick} option ++@item The value of the IRCNICK environment variable ++@item The result from the @code{user-login-name} function ++@end itemize ++ ++@end defun ++ ++@defopt erc-nick ++Nickname to use if one is not provided. ++ ++This can be either a string, or a list of strings. ++In the latter case, if the first nick in the list is already in use, ++other nicks are tried in the list order. ++@end defopt ++ ++@defopt erc-nick-uniquifier ++The string to append to the nick if it is already in use. ++@end defopt ++ ++@defopt erc-try-new-nick-p ++If the nickname you chose isn't available, and this option is non-nil, ++ERC should automatically attempt to connect with another nickname. ++ ++You can manually set another nickname with the /NICK command. ++@end defopt ++ ++@subheading Full name ++ ++@defun erc-compute-full-name &optional full-name ++Return user's full name. ++ ++This tries a number of increasingly more default methods until a ++non-nil value is found. ++ ++@itemize @bullet ++@item @var{full-name} (the argument passed to this function) ++@item The @code{erc-user-full-name} option ++@item The value of the IRCNAME environment variable ++@item The result from the @code{user-full-name} function ++@end itemize ++ ++@end defun ++ ++@defopt erc-user-full-name ++User full name. ++ ++This can be either a string or a function to call. ++@end defopt ++ ++@node Sample Configuration, Options, Connecting, Advanced Usage ++@comment node-name, next, previous, up ++@section Sample Configuration ++@cindex configuration, sample ++ ++Here is an example of configuration settings for ERC. This can go into ++your Emacs configuration file. Everything after the @code{(require ++'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}. ++ ++@lisp ++;;; Sample ERC configuration ++ ++;; Add the ERC directory to load path -- you don't need this if you are ++;; using the version of ERC that comes with Emacs ++(add-to-list 'load-path "~/elisp/erc") ++ ++;; Load ERC ++(require 'erc) ++ ++;; Load authentication info from an external source. Put sensitive ++;; passwords and the like in here. ++(load "~/.emacs.d/.erc-auth") ++ ++;; This is an example of how to make a new command. Type "/uptime" to ++;; use it. ++(defun erc-cmd-UPTIME (&rest ignore) ++ "Display the uptime of the system, as well as some load-related ++stuff, to the current ERC buffer." ++ (let ((uname-output ++ (replace-regexp-in-string ++ ", load average: " "] @{Load average@} [" ++ ;; Collapse spaces, remove ++ (replace-regexp-in-string ++ " +" " " ++ ;; Remove beginning and trailing whitespace ++ (replace-regexp-in-string ++ "^ +\\|[ \n]+$" "" ++ (shell-command-to-string "uptime")))))) ++ (erc-send-message ++ (concat "@{Uptime@} [" uname-output "]")))) ++ ++;; This causes ERC to connect to the Freenode network upon hitting ++;; C-c e f. Replace MYNICK with your IRC nick. ++(global-set-key "\C-cef" (lambda () (interactive) ++ (erc :server "irc.freenode.net" :port "6667" ++ :nick "MYNICK"))) ++ ++;; This causes ERC to connect to the IRC server on your own machine (if ++;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC ++;; nick. Often, people like to run bitlbee (http://bitlbee.org/) as an ++;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with ++;; people on those networks. ++(global-set-key "\C-ceb" (lambda () (interactive) ++ (erc :server "localhost" :port "6667" ++ :nick "MYNICK"))) ++ ++;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has ++;; been commented out to avoid confusing new users. ++;; (define-key erc-mode-map (kbd "RET") nil) ++;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line) ++;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line) ++ ++;;; Options ++ ++;; Join the #emacs and #erc channels whenever connecting to Freenode. ++(setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc"))) ++ ++;; Interpret mIRC-style color commands in IRC chats ++(setq erc-interpret-mirc-color t) ++ ++;; The following are commented out by default, but users of other ++;; non-Emacs IRC clients might find them useful. ++;; Kill buffers for channels after /part ++;; (setq erc-kill-buffer-on-part t) ++;; Kill buffers for private queries after quitting the server ++;; (setq erc-kill-queries-on-quit t) ++;; Kill buffers for server messages after quitting the server ++;; (setq erc-kill-server-buffer-on-quit t) ++@end lisp ++ ++@node Options, , Sample Configuration, Advanced Usage ++@comment node-name, next, previous, up ++@section Options ++@cindex options ++ ++@c PRE5_4: (Node) Document every ERC option (module options go in ++@c previous chapter) ++ ++This section has not yet been written. For now, the easiest way to ++check out the available options for ERC is to do ++@kbd{M-x customize-group erc RET}. ++ ++ ++@node Getting Help and Reporting Bugs, History, Advanced Usage, Top ++@comment node-name, next, previous, up ++@chapter Getting Help and Reporting Bugs ++@cindex help, getting ++@cindex bugs, reporting ++ ++After you have read this guide, if you still have questions about ERC, ++or if you have bugs to report, there are several places you can go. ++ ++@itemize @bullet ++ ++@item ++@uref{http://www.emacswiki.org/cgi-bin/wiki/ERC} is the ++emacswiki.org page for ERC. Anyone may add tips, hints, or bug ++descriptions to it. ++ ++@item ++There are several mailing lists for ERC. To subscribe, visit ++@uref{http://savannah.gnu.org/mail/?group=erc}. ++ ++The mailing lists are also available on Gmane. ++(@url{http://gmane.org/}). Gmane provides additional methods for ++accessing the mailing lists, adding content to them, and searching them. ++ ++@enumerate ++@item gmane.emacs.erc.announce: Announcements ++ ++@item gmane.emacs.erc.discuss: General discussion ++ ++@item gmane.emacs.erc.cvs: Log messages for changes to the ERC source code ++ ++@end enumerate ++ ++@item ++You can visit the IRC Freenode channel @samp{#emacs}. Many of the ++contributors are frequently around and willing to answer your ++questions. ++ ++@end itemize ++ ++ ++@node History, Copying, Getting Help and Reporting Bugs, Top ++@comment node-name, next, previous, up ++@chapter History ++@cindex history, of ERC ++ ++ERC was originally written by Alexander L. Belikoff ++@email{abel@@bfr.co.il} and Sergey Berezin ++@email{sergey.berezin@@cs.cmu.edu}. They stopped development around ++December 1999. Their last released version was ERC 2.0. ++ ++P.S.: If one of the original developers of ERC reads this, we'd like to ++receive additional information for this file and hear comments in ++general. ++ ++@itemize ++@item 2001 ++ ++In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder ++@email{alex@@gnu.org} took over development and created a ERC Project at ++@uref{http://sourceforge.net/projects/erc}. ++ ++In reaction to a mail about the new ERC development effort, Sergey ++Berezin said, ``First of all, I'm glad that my version of ERC is being ++used out there. The thing is, I do not have free time and enough ++incentive anymore to work on ERC, so I would be happy if you guys take ++over the project entirely.'' ++ ++So we happily hacked away on ERC, and soon after (September 2001) ++released the next "stable" version, 2.1. ++ ++Most of the development of the new ERC happened on #emacs on ++irc.openprojects.net. Over time, many people contributed code, ideas, ++bugfixes, and a lot of alpha/beta/gamma testing. ++ ++See the @file{CREDITS} file for a list of contributors. ++ ++@item 2003 ++ ++ERC 3.0 was released. ++ ++@item 2004 ++ ++ERC 4.0 was released. ++ ++@item 2005 ++ ++ERC 5.0 was released. Michael Olson @email{mwolson@@gnu.org} became ++the release manager and eventually the maintainer. ++ ++After some discussion between him and the Emacs developers, it was ++decided to include ERC in Emacs. ++ ++@item 2006 ++ ++ERC 5.1 was released. It was subsequently included in Emacs 22. ++ ++ERC became an official GNU project, and development moved to ++@uref{http://sv.gnu.org/projects/erc}. We switched to using GNU Arch as ++our revision control system. Our mailing list address changed as well. ++ ++@item 2007 ++ ++We switched to using git for our version control system. ++ ++@end itemize ++ ++@node Copying, GNU Free Documentation License, History, Top ++@comment node-name, next, previous, up ++@include gpl.texi ++ ++@node GNU Free Documentation License, Concept Index, Copying, Top ++@comment node-name, next, previous, up ++@include doclicense.texi ++ ++@node Concept Index, , GNU Free Documentation License, Top ++@comment node-name, next, previous, up ++@unnumbered Index ++ ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e ++@end ignore +diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi +new file mode 100644 +index 0000000..e7d4132 +--- /dev/null ++++ b/doc/misc/eshell.texi +@@ -0,0 +1,942 @@ ++\input texinfo @c -*-texinfo-*- ++@c %**start of header ++@setfilename ../../info/eshell ++@settitle Eshell: The Emacs Shell ++@synindex vr fn ++@c %**end of header ++ ++@copying ++This manual is for Eshell, the Emacs shell. ++ ++Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* Eshell: (eshell). A command shell implemented in Emacs Lisp. ++@end direntry ++ ++@titlepage ++@sp 4 ++@c The title is printed in a large font. ++@center @titlefont{User's Guide} ++@sp ++@center @titlefont{to} ++@sp ++@center @titlefont{Eshell: The Emacs Shell} ++@ignore ++@sp 2 ++@center release 2.4 ++@c -release- ++@end ignore ++@sp 3 ++@center John Wiegley ++@c -date- ++ ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@c ================================================================ ++@c The real text starts here ++@c ================================================================ ++ ++@ifnottex ++@node Top, What is Eshell?, (dir), (dir) ++@top Eshell ++ ++Eshell is a shell-like command interpretor ++implemented in Emacs Lisp. It invokes no external processes except for ++those requested by the user. It is intended to be a functional ++replacement for command shells such as @command{bash}, @command{zsh}, ++@command{rc}, or @command{4dos}; since Emacs itself is capable of ++handling the sort of tasks accomplished by those tools. ++@c This manual is updated to release 2.4 of Eshell. ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* What is Eshell?:: A brief introduction to the Emacs Shell. ++* Command basics:: The basics of command usage. ++* Commands:: ++* Arguments:: ++* Input/Output:: ++* Process control:: ++* Extension modules:: ++* Extras and Goodies:: ++* Bugs and ideas:: Known problems, and future ideas. ++* GNU Free Documentation License:: The license for this documentation. ++* Concept Index:: ++* Function and Variable Index:: ++* Key Index:: ++@end menu ++ ++@node What is Eshell? ++@chapter What is Eshell? ++@cindex what is Eshell? ++@cindex Eshell, what it is ++ ++Eshell is a @dfn{command shell} written in Emacs Lisp. Everything it ++does, it uses Emacs' facilities to do. This means that Eshell is as ++portable as Emacs itself. It also means that cooperation with Lisp code ++is natural and seamless. ++ ++What is a command shell? To properly understand the role of a shell, ++it's necessary to visualize what a computer does for you. Basically, a ++computer is a tool; in order to use that tool, you must tell it what to ++do---or give it ``commands.'' These commands take many forms, such as ++clicking with a mouse on certain parts of the screen. But that is only ++one form of command input. ++ ++By far the most versatile way to express what you want the computer to ++do is by using an abbreviated language called @dfn{script}. In ++script, instead of telling the computer, ``list my files, please'', ++one writes a standard abbreviated command word---@samp{ls}. Typing ++@samp{ls} in a command shell is a script way of telling the computer ++to list your files.@footnote{This is comparable to viewing the ++contents of a folder using a graphical display.} ++ ++The real flexibility of this approach is apparent only when you realize ++that there are many, many different ways to list files. Perhaps you ++want them sorted by name, sorted by date, in reverse order, or grouped ++by type. Most graphical browsers have simple ways to express this. But ++what about showing only a few files, or only files that meet a certain ++criteria? In very complex and specific situations, the request becomes ++too difficult to express using a mouse or pointing device. It is just ++these kinds of requests that are easily solved using a command shell. ++ ++For example, what if you want to list every Word file on your hard ++drive, larger than 100 kilobytes in size, and which hasn't been looked ++at in over six months? That is a good candidate list for deletion, when ++you go to clean up your hard drive. But have you ever tried asking your ++computer for such a list? There is no way to do it! At least, not ++without using a command shell. ++ ++The role of a command shell is to give you more control over what your ++computer does for you. Not everyone needs this amount of control, and ++it does come at a cost: Learning the necessary script commands to ++express what you want done. A complicated query, such as the example ++above, takes time to learn. But if you find yourself using your ++computer frequently enough, it is more than worthwhile in the long run. ++Any tool you use often deserves the time spent learning to master it. ++@footnote{For the understandably curious, here is what that command ++looks like: But don't let it fool you; once you know what's going on, ++it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.} ++ ++@menu ++* Contributors to Eshell:: People who have helped out! ++@end menu ++ ++@node Contributors to Eshell ++@section Contributors to Eshell ++@cindex contributors ++@cindex authors ++ ++Contributions to Eshell are welcome. I have limited time to work on ++this project, but I will gladly add any code you contribute to me to ++this package. ++ ++The following persons have made contributions to Eshell. ++ ++@itemize @bullet ++@item ++Eli Zaretskii made it possible for Eshell to run without requiring ++asynchronous subprocess support. This is important for MS-DOS, which ++does not have such support.@refill ++ ++@item ++Miles Bader contributed many fixes during the port to Emacs 21.@refill ++ ++@item ++Stefan Monnier fixed the things which bothered him, which of course made ++things better for all.@refill ++ ++@item ++Gerd Moellmann also helped to contribute bug fixes during the initial ++integration with Emacs 21.@refill ++ ++@item ++Alex Schroeder contributed code for interactively querying the user ++before overwriting files.@refill ++ ++@item ++Sudish Joseph helped with some XEmacs compatibility issues.@refill ++@end itemize ++ ++Apart from these, a lot of people have sent suggestions, ideas, ++requests, bug reports and encouragement. Thanks a lot! Without you ++there would be no new releases of Eshell. ++ ++@node Command basics ++@chapter Basic overview ++ ++A command shell is a means of entering verbally-formed commands. This ++is really all that it does, and every feature described in this manual ++is a means to that end. Therefore, it's important to take firm hold on ++exactly what a command is, and how it fits in the overall picture of ++things. ++ ++@menu ++* Commands verbs:: Commands always begin with a verb. ++* Command arguments:: Some verbs require arguments. ++@end menu ++ ++@node Commands verbs ++@section Commands verbs ++ ++Commands are expressed using @dfn{script}, a special shorthand language ++computers can understand with no trouble. Script is an extremely simple ++language; oddly enough, this is what makes it look so complicated! ++Whereas normal languages use a variety of embellishments, the form of a ++script command is always: ++ ++@example ++@var{verb} [@var{arguments}] ++@end example ++ ++The verb expresses what you want your computer to do. There are a fixed ++number of verbs, although this number is usually quite large. On the ++author's computer, it reaches almost 1400 in number. But of course, ++only a handful of these are really necessary. ++ ++Sometimes, the verb is all that's written. A verb is always a single ++word, usually related to the task it performs. @command{reboot} is a ++good example. Entering that on GNU/Linux will reboot the ++computer---assuming you have sufficient privileges. ++ ++Other verbs require more information. These are usually very capable ++verbs, and must be told specifically what to do. The extra information ++is given in the form of @dfn{arguments}. For example, the ++@command{echo} verb prints back whatever arguments you type. It ++requires these arguments to know what to echo. A proper use of ++@command{echo} looks like this: ++ ++@example ++echo This is an example of using echo! ++@end example ++ ++This script command causes the computer to echo back: ``This is an ++example of using echo!'' ++ ++Although command verbs are always simple words, like @command{reboot} or ++@command{echo}, arguments may have a wide variety of forms. There are ++textual arguments, numerical arguments---even Lisp arguments. ++Distinguishing these different types of arguments requires special ++typing, for the computer to know exactly what you mean. ++ ++@node Command arguments ++@section Command arguments ++ ++Eshell recognizes several different kinds of command arguments: ++ ++@enumerate ++@item Strings (also called textual arguments) ++@item Numbers (floating point or integer) ++@item Lisp lists ++@item Lisp symbols ++@item Emacs buffers ++@item Emacs process handles ++@end enumerate ++ ++Most users need to worry only about the first two. The third, Lisp lists, ++occur very frequently, but almost always behind the scenes. ++ ++Strings are the most common type of argument, and consist of nearly any ++character. Special characters---those used by Eshell ++specifically---must be preceded by a backslash (@samp{\}). When in doubt, it ++is safe to add backslashes anywhere and everywhere. ++ ++Here is a more complicated @command{echo} example: ++ ++@example ++echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar ++@end example ++ ++Beyond this, things get a bit more complicated. While not beyond the ++reach of someone wishing to learn, it is definitely beyond the scope of ++this manual to present it all in a simplistic manner. Get comfortable ++with Eshell as a basic command invocation tool, and learn more about the ++commands on your system; then come back when it all sits more familiarly ++on your mind. Have fun! ++ ++@node Commands ++@chapter Commands ++ ++@menu ++* Invocation:: ++* Completion:: ++* Aliases:: ++* History:: ++* Scripts:: ++* Built-ins:: ++@end menu ++ ++Essentially, a command shell is all about invoking commands---and ++everything that entails. So understanding how Eshell invokes commands ++is the key to comprehending how it all works. ++ ++@node Invocation ++@section Invocation ++ ++Unlike regular system shells, Eshell never invokes kernel functions ++directly, such as @code{exec(3)}. Instead, it uses the Lisp functions ++available in the Emacs Lisp library. It does this by transforming the ++command you specify into a callable Lisp form.@footnote{To see the Lisp ++form that will be invoked, type: @samp{eshell-parse-command "echo ++hello"}} ++ ++This transformation, from the string of text typed at the command ++prompt, to the ultimate invocation of either a Lisp function or external ++command, follows these steps: ++ ++@enumerate ++@item Parse the command string into separate arguments. ++@item ++@end enumerate ++ ++@node Completion ++@section Completion ++ ++@node Aliases ++@section Aliases ++ ++@node History ++@section History ++ ++Eshell knows a few built-in variables: ++ ++@table @code ++ ++@item $+ ++@vindex $+ ++This variable always contains the current working directory. ++ ++@item $- ++@vindex $- ++This variable always contains the previous working directory (the ++current working directory from before the last @code{cd} command). ++ ++@end table ++ ++@node Scripts ++@section Scripts ++ ++ ++@node Built-ins ++@section Built-in commands ++ ++Here is a list of built-in commands that Eshell knows about: ++ ++@table @code ++ ++@item cd ++@findex cd ++This command changes the current working directory. Usually, it is ++invoked as @samp{cd foo} where @file{foo} is the new working ++directory. But @code{cd} knows about a few special arguments: ++ ++When it receives no argument at all, it changes to the home directory. ++ ++Giving the command @samp{cd -} changes back to the previous working ++directory (this is the same as @samp{cd $-}). ++ ++The command @samp{cd =} shows the directory stack. Each line is ++numbered. ++ ++With @samp{cd =foo}, Eshell searches the directory stack for a ++directory matching the regular expression @samp{foo} and changes to ++that directory. ++ ++With @samp{cd -42}, you can access the directory stack by number. ++ ++@end table ++ ++ ++@node Arguments ++@chapter Arguments ++ ++@menu ++* The Parser:: ++* Variables:: ++* Substitution:: ++* Globbing:: ++* Predicates:: ++@end menu ++ ++@node The Parser ++@section The Parser ++ ++@node Variables ++@section Variables ++ ++@node Substitution ++@section Substitution ++ ++@node Globbing ++@section Globbing ++ ++@node Predicates ++@section Predicates ++ ++ ++@node Input/Output ++@chapter Input/Output ++ ++@node Process control ++@chapter Process control ++ ++ ++@node Extension modules ++@chapter Extension modules ++ ++@menu ++* Writing a module:: ++* Module testing:: ++* Directory handling:: ++* Key rebinding:: ++* Smart scrolling:: ++* Terminal emulation:: ++* Built-in UNIX commands:: ++@end menu ++ ++@node Writing a module ++@section Writing a module ++ ++@node Module testing ++@section Module testing ++ ++@node Directory handling ++@section Directory handling ++ ++@node Key rebinding ++@section Key rebinding ++ ++@node Smart scrolling ++@section Smart scrolling ++ ++@node Terminal emulation ++@section Terminal emulation ++ ++@node Built-in UNIX commands ++@section Built-in UNIX commands ++ ++ ++@node Extras and Goodies ++@chapter Extras and Goodies ++ ++@node Bugs and ideas ++@chapter Bugs and ideas ++@cindex reporting bugs and ideas ++@cindex bugs, how to report them ++@cindex author, how to reach ++@cindex email to the author ++@cindex FAQ ++@cindex problems, list of common ++ ++If you find a bug or misfeature, don't hesitate to let me know! Send ++email to @email{johnw@@gnu.org}. Feature requests should also be sent ++there. I prefer discussing one thing at a time. If you find several ++unrelated bugs, please report them separately. ++ ++If you have ideas for improvements, or if you have written some ++extensions to this package, I would like to hear from you. I hope you ++find this package useful! ++ ++@menu ++* Known problems:: ++@end menu ++ ++@node Known problems ++@section Known problems ++@cindex known bugs ++@cindex bugs, known ++ ++Below is complete list of known problems with Eshell version 2.4.2, ++which is the version included with Emacs 22. ++ ++@table @asis ++@item Documentation incomplete ++ ++@item Differentiate between aliases and functions ++ ++Allow for a bash-compatible syntax, such as: ++ ++@example ++alias arg=blah ++function arg () @{ blah $* @} ++@end example ++ ++@item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt ++ ++In fact, piping to a process from a looping construct doesn't work in ++general. If I change the call to @code{eshell-copy-handles} in ++@code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems ++to work, but the output occurs after the prompt is displayed. The whole ++structured command thing is too complicated at present. ++ ++@item Error with @command{bc} in @code{eshell-test} ++ ++On some XEmacs system, the subprocess interaction test fails ++inexplicably, although @command{bc} works fine at the command prompt. ++ ++@item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+ ++ ++In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that ++multiple instances of the @file{*Help*} buffer can exist. ++ ++@item Pcomplete sometimes gets stuck ++ ++You press @key{TAB}, but no completions appear, even though the ++directory has matching files. This behavior is rare. ++ ++@item @samp{grep python $} doesn't work, but using @samp{*grep} does ++ ++This happens because the @code{grep} Lisp function returns immediately, ++and then the asynchronous @command{grep} process expects to examine the ++temporary file, which has since been deleted. ++ ++@item Problem with C-r repeating text ++ ++If the text @emph{before point} reads "./run", and you type @kbd{C-r r u ++n}, it will repeat the line for every character typed. ++ ++@item Backspace doesn't scroll back after continuing (in smart mode) ++ ++Hitting space during a process invocation, such as @command{make}, will ++cause it to track the bottom of the output; but backspace no longer ++scrolls back. ++ ++@item It's not possible to fully @code{unload-feature} Eshell ++ ++@item Menu support was removed, but never put back ++ ++@item Using C-p and C-n with rebind gets into a locked state ++ ++This happened a few times in Emacs 21, but has been unreproducible ++since. ++ ++@item If an interactive process is currently running, @kbd{M-!} doesn't work ++ ++@item Use a timer instead of @code{sleep-for} when killing child processes ++ ++@item Piping to a Lisp function is not supported ++ ++Make it so that the Lisp command on the right of the pipe is repeatedly ++called with the input strings as arguments. This will require changing ++@code{eshell-do-pipeline} to handle non-process targets. ++ ++@item Input redirection is not supported ++ ++See the above entry. ++ ++@item Problem running @command{less} without arguments on Windows ++ ++The result in the Eshell buffer is: ++ ++@example ++Spawning child process: invalid argument ++@end example ++ ++Also a new @command{less} buffer was created with nothing in it@dots{} ++(presumably this holds the output of @command{less}). ++ ++If @command{less.exe} is invoked from the Eshell command line, the ++expected output is written to the buffer. ++ ++Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el ++package and the supplied shell both use the @command{cmdproxy} program ++for running shells. ++ ++@item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp} ++ ++@item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be ++ ++@item @samp{mv @var{dir} @var{file}.tar} does not remove directories ++ ++This is because the tar option --remove-files doesn't do so. Should it ++be Eshell's job? ++ ++@item Bind @code{standard-output} and @code{standard-error} ++ ++This would be so that if a Lisp function calls @code{print}, everything ++will happen as it should (albeit slowly). ++ ++@item When an extension module fails to load, @samp{cd /} gives a Lisp error ++ ++@item If a globbing pattern returns one match, should it be a list? ++ ++@item Make sure syntax table is correct in Eshell mode ++ ++So that @kbd{M-DEL} acts in a predictable manner, etc. ++ ++@item Allow all Eshell buffers to share the same history and list-dir ++ ++@item There is a problem with script commands that output to @file{/dev/null} ++ ++If a script file, somewhere in the middle, uses @samp{> /dev/null}, ++output from all subsequent commands is swallowed. ++ ++@item Split up parsing of text after @samp{$} in @file{esh-var.el} ++ ++Make it similar to the way that @file{esh-arg.el} is structured. ++Then add parsing of @samp{$[?\n]}. ++ ++@item After pressing @kbd{M-RET}, redisplay before running the next command ++ ++@item Argument predicates and modifiers should work anywhere in a path ++ ++@example ++/usr/local/src/editors/vim $ vi **/CVS(/)/Root(.) ++Invalid regexp: "Unmatched ( or \\(" ++@end example ++ ++With @command{zsh}, the glob above expands to all files named ++@file{Root} in directories named @file{CVS}. ++ ++@item Typing @samp{echo $@{locate locate@}/bin} results in a Lisp error ++ ++Perhaps it should interpolate all permutations, and make that the ++globbing result, since otherwise hitting return here will result in ++``(list of filenames)/bin'', which is never valuable. Thus, one could ++@command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}. ++In that case, having an alias command name @command{glob} for ++@command{identity} would be useful. ++ ++@item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp ++ ++@item Create @code{eshell-expand-file-name} ++ ++This would use a data table to transform things such as @samp{~+}, ++@samp{...}, etc. ++ ++@item Abstract @file{em-smart.el} into @file{smart-scroll.el} ++ ++It only really needs: to be hooked onto the output filter and the ++pre-command hook, and to have the input-end and input-start markers. ++And to know whether the last output group was ``successful.'' ++ ++@item Allow for fully persisting the state of Eshell ++ ++This would include: variables, history, buffer, input, dir stack, etc. ++ ++@item Implement D as an argument predicate ++ ++It means that files beginning with a dot should be included in the ++glob match. ++ ++@item A comma in a predicate list should mean OR ++ ++At the moment, this is not supported. ++ ++@item Error if a glob doesn't expand due to a predicate ++ ++An error should be generated only if @code{eshell-error-if-no-glob} is ++non-@code{nil}. ++ ++@item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur ++ ++@item Create @code{eshell-auto-accumulate-list} ++ ++This is a list of commands for which, if the user presses @kbd{RET}, the ++text is staged as the next Eshell command, rather than being sent to the ++current interactive process. ++ ++@item Display file and line number if an error occurs in a script ++ ++@item @command{wait} doesn't work with process ids at the moment ++ ++@item Enable the direct-to-process input code in @file{em-term.el} ++ ++@item Problem with repeating @samp{echo $@{find /tmp@}} ++ ++With smart display active, if @kbd{RET} is held down, after a while it ++can't keep up anymore and starts outputting blank lines. It only ++happens if an asynchronous process is involved@dots{} ++ ++I think the problem is that @code{eshell-send-input} is resetting the ++input target location, so that if the asynchronous process is not done ++by the time the next @kbd{RET} is received, the input processor thinks ++that the input is meant for the process; which, when smart display is ++enabled, will be the text of the last command line! That is a bug in ++itself. ++ ++In holding down @kbd{RET} while an asynchronous process is running, ++there will be a point in between termination of the process, and the ++running of @code{eshell-post-command-hook}, which would cause ++@code{eshell-send-input} to call @code{eshell-copy-old-input}, and then ++process that text as a command to be run after the process. Perhaps ++there should be a way of killing pending input between the death of the ++process, and the @code{post-command-hook}. ++ ++@item Allow for a more aggressive smart display mode ++ ++Perhaps toggled by a command, that makes each output block a smart ++display block. ++ ++@item Create more meta variables ++ ++@table @samp ++@item $! ++The reason for the failure of the last disk command, or the text of the ++last Lisp error. ++ ++@item $= ++A special associate array, which can take references of the form ++@samp{$=[REGEXP]}. It indexes into the directory ring. ++@end table ++ ++@item Eshell scripts can't execute in the background ++ ++@item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{@var{name}:-@var{val}@}} ++ ++@item Write an @command{info} alias that can take arguments ++ ++So that the user can enter @samp{info chmod}, for example. ++ ++@item Create a mode @code{eshell-browse} ++ ++It would treat the Eshell buffer as a outline. Collapsing the outline ++hides all of the output text. Collapsing again would show only the ++first command run in each directory ++ ++@item Allow other revisions of a file to be referenced using @samp{file@{rev@}} ++ ++This would be expanded by @code{eshell-expand-file-name} (see above). ++ ++@item Print ``You have new mail'' when the ``Mail'' icon is turned on ++ ++@item Implement @kbd{M-|} for Eshell ++ ++@item Implement input redirection ++ ++If it's a Lisp function, input redirection implies @command{xargs} (in a ++way@dots{}). If input redirection is added, also update the ++@code{file-name-quote-list}, and the delimiter list. ++ ++@item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax ++ ++With the handling of @emph{word} specified by an ++@code{eshell-special-alist}. ++ ++@item In @code{eshell-veal-using-options}, allow a @code{:complete} tag ++ ++It would be used to provide completion rules for that command. Then the ++macro will automagically define the completion function. ++ ++@item For @code{eshell-command-on-region}, apply redirections to the result ++ ++So that @samp{+ > 'blah} would cause the result of the @code{+} (using ++input from the current region) to be inserting into the symbol ++@code{blah}. ++ ++If an external command is being invoked, the input is sent as standard ++input, as if a @samp{cat |} had been invoked. ++ ++If a Lisp command, or an alias, is invoked, then if the line has no ++newline characters, it is divided by whitespace and passed as arguments ++to the Lisp function. Otherwise, it is divided at the newline ++characters. Thus, invoking @code{+} on a series of numbers will add ++them; @code{min} would display the smallest figure, etc. ++ ++@item Write @code{eshell-script-mode} as a minor mode ++ ++It would provide syntax, abbrev, highlighting and indenting support like ++@code{emacs-lisp-mode} and @code{shell-mode}. ++ ++@item In the history mechanism, finish the @command{bash}-style support ++ ++This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate ++from @samp{!:1*}. ++ ++@item Support the -n command line option for @command{history} ++ ++@item Implement @command{fc} in Lisp ++ ++@item Specifying a frame as a redirection target should imply the currently active window's buffer ++ ++@item Implement @samp{>@var{func-or-func-list}} ++ ++This would allow for an ``output translators'', that take a function to ++modify output with, and a target. Devise a syntax that works well with ++pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase ++regexp-quote)} or @samp{>'upcase}). ++ ++@item Allow Eshell to read/write to/from standard input and output ++ ++This would be optional, rather than always using the Eshell buffer. ++This would allow it to be run from the command line (perhaps). ++ ++@item Write a @command{help} command ++ ++It would call subcommands with @option{--help}, or @option{-h} or ++@option{/?}, as appropriate. ++ ++@item Implement @command{stty} in Lisp ++ ++@item Support @command{rc}'s matching operator, e.g. @samp{~ (@var{list}) @var{regexp}} ++ ++@item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list} ++ ++Using @command{bg} on a process that is already in the background does ++nothing. Specifying redirection targets replaces (or adds) to the list ++current being used. ++ ++@item Have @command{jobs} print only the processes for the current shell ++ ++@item How can Eshell learn if a background process has requested input? ++ ++@item Support @samp{2>&1} and @samp{>&} and @samp{2>} and @samp{|&} ++ ++The syntax table for parsing these should be customizable, such that the ++user could change it to use rc syntax: @samp{>[2=1]}. ++ ++@item Allow @samp{$_[-1]}, which would indicate the last element of the array ++ ++@item Make @samp{$x[*]} equal to listing out the full contents of @samp{x} ++ ++Return them as a list, so that @samp{$_[*]} is all the arguments of the ++last command. ++ ++@item Copy ANSI code handling from @file{term.el} into @file{em-term.el} ++ ++Make it possible for the user to send char-by-char to the underlying ++process. Ultimately, I should be able to move away from using term.el ++altogether, since everything but the ANSI code handling is already part ++of Eshell. Then, things would work correctly on MS-Windows as well ++(which doesn't have @file{/bin/sh}, although @file{term.el} tries to use ++it). ++ ++@item Make the shell spawning commands be visual ++ ++That is, make (@command{su}, @command{bash}, @command{telnet}, ++@command{rlogin}, @command{rsh}, etc.) be part of ++@code{eshell-visual-commands}. The only exception is if the shell is ++being used to invoke a single command. Then, the behavior should be ++based on what that command is. ++ ++@item Create a smart viewing command named @command{open} ++ ++This would search for some way to open its argument (similar to opening ++a file in the Windows Explorer). ++ ++@item Alias @command{read} to be the same as @command{open}, only read-only ++ ++@item Write a @command{tail} command which uses @code{view-file} ++ ++It would move point to the end of the buffer, and then turns on ++auto-revert mode in that buffer at frequent intervals---and a ++@command{head} alias which assumes an upper limit of ++@code{eshell-maximum-line-length} characters per line. ++ ++@item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search} ++ ++@item Write mesh.c ++ ++This would run Emacs with the appropriate arguments to invoke Eshell ++only. That way, it could be listed as a login shell. ++ ++@item Use an intangible @code{PS2} string for multi-line input prompts ++ ++@item Auto-detect when a command is visual, by checking @code{TERMCAP} usage ++ ++@item The first keypress after @kbd{M-x watson} triggers `eshell-send-input' ++ ++@item Make @kbd{/} electric ++ ++So that it automatically expands and corrects pathnames. Or make ++pathname completion for Pcomplete auto-expand @samp{/u/i/std} to ++@samp{/usr/include/std}. ++ ++@item Write the @command{pushd} stack to disk along with @code{last-dir-ring} ++ ++@item Add options to @code{eshell/cat} which would allow it to sort and uniq ++ ++@item Implement @command{wc} in Lisp ++ ++Add support for counting sentences, paragraphs, pages, etc. ++ ++@item Once piping is added, implement @command{sort} and @command{uniq} in Lisp ++ ++@item Implement @command{touch} in Lisp ++ ++@item Implement @command{comm} in Lisp ++ ++@item Implement an @command{epatch} command in Lisp ++ ++This would call @code{ediff-patch-file}, or @code{ediff-patch-buffer}, ++depending on its argument. ++ ++@item Have an option such that @samp{ls -l} generates a dired buffer ++ ++@item Write a version of @command{xargs} based on command rewriting ++ ++That is, @samp{find X | xargs Y} would be indicated using @samp{Y ++$@{find X@}}. Maybe @code{eshell-do-pipelines} could be changed to ++perform this on-thy-fly rewriting. ++ ++@item Write an alias for @command{less} that brings up a @code{view-mode} buffer ++ ++Such that the user can press @key{SPC} and @key{DEL}, and then @key{q} ++to return to Eshell. It would be equivalent to: ++@samp{X > #; view-buffer #}. ++ ++@item Make @code{eshell-mode} as much a full citizen as @code{shell-mode} ++ ++Everywhere in Emacs where @code{shell-mode} is specially noticed, add ++@code{eshell-mode} there. ++ ++@item Permit the umask to be selectively set on a @command{cp} target ++ ++@item Problem using @kbd{M-x eshell} after using @code{eshell-command} ++ ++If the first thing that I do after entering Emacs is to run ++@code{eshell-command} and invoke @command{ls}, and then use @kbd{M-x ++eshell}, it doesn't display anything. ++ ++@item @kbd{M-RET} during a long command (using smart display) doesn't work ++ ++Since it keeps the cursor up where the command was invoked. ++ ++@end table ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Concept Index ++@unnumbered Concept Index ++ ++@printindex cp ++ ++@node Function and Variable Index ++@unnumbered Function and Variable Index ++ ++@printindex fn ++ ++@node Key Index ++@unnumbered Key Index ++ ++@printindex ky ++@bye ++ ++@ignore ++ arch-tag: 776409ba-cb15-42b9-b2b6-d2bdc7ebad01 ++@end ignore +diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi +new file mode 100644 +index 0000000..c3adbb4 +--- /dev/null ++++ b/doc/misc/eudc.texi +@@ -0,0 +1,974 @@ ++\input texinfo.tex ++@c %**start of header ++@setfilename ../../info/eudc ++@settitle Emacs Unified Directory Client (EUDC) Manual ++@afourpaper ++@c %**end of header ++ ++@copying ++This file documents EUDC v1.30b. ++ ++EUDC is the Emacs Unified Directory Client, a common interface to ++directory servers using various protocols such as LDAP or the CCSO white ++pages directory system (PH/QI) ++ ++Copyright @copyright{} 1998, 2000, 2001, 2002, 2003, 2004, 2005, 2006, ++2007, 2008, 2009 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 Emacs ++@direntry ++* EUDC: (eudc). An Emacs client for directory servers (LDAP, PH). ++@end direntry ++ ++@footnotestyle end ++ ++@titlepage ++@title{EUDC Manual} ++@subtitle{The Emacs Unified Directory Client} ++@author by Oscar Figueiredo ++@code{1.30b} ++ ++@page ++@vskip 0pt plus 1fill ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top, Overview, (dir), (dir) ++@comment node-name, next, previous, up ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview:: Summary of EUDC features ++* Installation:: How to install EUDC ++* Usage:: The various usage possibilities explained ++* Credits:: Who's done what ++* GNU Free Documentation License:: The license for this documentation. ++* Command and Function Index:: ++* Variables Index:: ++@end menu ++ ++ ++ ++ ++ ++@node Overview, Installation, Top, Top ++@comment node-name, next, previous, up ++@chapter Overview ++ ++EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user ++interface to access directory servers using different directory ++protocols. ++ ++Currently supported back-ends are: ++ ++@itemize @bullet ++@item ++LDAP, Lightweight Directory Access Protocol ++@item ++CCSO PH/QI ++@item ++BBDB, Big Brother's Insidious Database ++@end itemize ++ ++The main features of the EUDC interface are: ++ ++@itemize @bullet ++@item ++Queries using a customizable form ++@item ++Inline query expansion (for instance you can expand a name ++to an email address in a mail message buffer using a server as an ++address book) ++@item ++Multiple servers can be tried in turn until a match is found for an ++inline query ++@item ++Fast minibuffer queries for email addresses and phone numbers ++@item ++Interface to BBDB to let you insert server records into your own BBDB database ++(@pxref{Top,,BBDB,bbdb,BBDB Manual}) ++@end itemize ++ ++@menu ++* LDAP:: What is LDAP ? ++* CCSO PH/QI:: What is CCSO, PH, QI ? ++* BBDB:: What is BBDB ? ++@end menu ++ ++ ++ ++@node LDAP, CCSO PH/QI, Overview, Overview ++@comment node-name, next, previous, up ++@section LDAP ++ ++LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication ++protocol for directory applications defined in RFC 1777. ++ ++Quoted from RFC 1777: ++ ++@quotation ++[LDAP] is designed to provide access to the X.500 Directory while not ++incurring the resource requirements of the Directory Access Protocol ++(DAP). This protocol is specifically targeted at simple management ++applications and browser applications that provide simple read/write ++interactive access to the X.500 Directory, and is intended to be a ++complement to the DAP itself. ++@end quotation ++ ++LDAP servers usually store (but are not limited to) information about ++people such as their name, phone number, email address, office ++location, etc@enddots{} More information about LDAP can be found at ++@url{http://www.openldap.org/} ++ ++EUDC requires external support to access LDAP directory servers ++(@pxref{LDAP Requirements}) ++ ++ ++@node CCSO PH/QI, BBDB, LDAP, Overview ++@comment node-name, next, previous, up ++@section CCSO PH/QI ++ ++The Central Computing Services Office (CCSO) of the University of ++Illinois at Urbana Champaign (UIUC) created and freely distributes a ++directory system that is currently in use in more than 300 organizations ++around the world. The system records information about people such as ++their address, phone number, email, academic information or any other ++details it was configured to. ++ ++The system consists of two parts: a database server traditionally called ++@samp{qi} and a command-line client called @samp{ph}. ++@url{ftp://uiarchive.cso.uiuc.edu/pub/packages/ph} is the main ++distribution site. @url{http://www.uiuc.edu/cgi-bin/ph/lookup?Query=.} ++provides a listing of the active @samp{qi} servers. ++ ++The original command-line @samp{ph} client that comes with the ++@samp{ph/qi} distribution provides additional features like the ++possibility to communicate with the server in login-mode which makes it ++possible to change records in the database. This is not implemented in ++EUDC. ++ ++ ++@node BBDB, , CCSO PH/QI, Overview ++@comment node-name, next, previous, up ++@section BBDB ++ ++BBDB is the @dfn{Big Brother's Insidious Database}, a package for Emacs ++originally written by Jamie Zawinski which provides rolodex-like ++database functionality featuring tight integration with the Emacs mail ++and news readers. ++ ++It is often used as an enhanced email address book. ++ ++EUDC considers BBDB as a directory server back end just like LDAP or ++PH/QI servers, though BBDB has no client/server protocol and thus always ++resides locally on your machine. The point in this is not to offer an ++alternate way to query your BBDB database (BBDB itself provides much ++more flexible ways to do that), but rather to offer an interface to your ++local directory that is consistent with the interface to external ++directories (LDAP, PH/QI). This is particularly interesting when ++performing queries on multiple servers. ++ ++EUDC also offers a means to insert results from directory queries into ++your own local BBDB (@pxref{Creating BBDB Records}) ++ ++@node Installation, Usage, Overview, Top ++@comment node-name, next, previous, up ++@chapter Installation ++ ++Add the following to your @file{.emacs} init file: ++@lisp ++(require 'eudc) ++@end lisp ++This will install EUDC at startup. ++ ++After installing EUDC you will find (the next time you launch Emacs) a ++new @code{Directory Search} submenu in the @samp{Tools} menu that will ++give you access to EUDC. ++ ++You may also find it useful to add the following to your @file{.emacs} ++initialization file to add a shortcut for email address expansion in ++email composition buffers (@pxref{Inline Query Expansion}) ++ ++@lisp ++(eval-after-load ++ "message" ++ '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) ++(eval-after-load ++ "sendmail" ++ '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) ++@end lisp ++ ++@menu ++* LDAP Requirements:: EUDC needs external support for LDAP ++@end menu ++ ++@node LDAP Requirements, , Installation, Installation ++@comment node-name, next, previous, up ++@section LDAP Requirements ++ ++LDAP support is added by means of @file{ldap.el} which is part of Emacs. ++@file{ldap.el} needs an external command line utility named ++@file{ldapsearch} which is available as part of LDAP toolkits: ++ ++@itemize @bullet ++@item ++Open LDAP Libraries ++(@url{http://www.openldap.org/}) ++@item ++University of Michigan's LDAP Client software ++(@url{http://www.umich.edu/~dirsvcs/ldap/}) ++@end itemize ++ ++ ++@node Usage, Credits, Installation, Top ++@comment node-name, next, previous, up ++@chapter Usage ++ ++This chapter describes the usage of EUDC. Most functions and ++customization options are available through the @samp{Directory Search} ++submenu of the @samp{Tools} submenu. ++ ++@menu ++* Querying Servers:: How queries are performed and handled ++* Query Form:: How to use and customize the query form ++* Display of Query Results:: Controlling how query results are presented ++* Inline Query Expansion:: How to use and customize inline queries ++* The Server Hotlist:: How to use and manage the server hotlist ++* Multi-server Queries:: How to query multiple servers successively ++* Creating BBDB Records:: How to insert query results into your BBDB ++* Server/Protocol Locals:: Customizing on a per server/protocol basis ++@end menu ++ ++ ++@node Querying Servers, Query Form, Usage, Usage ++@comment node-name, next, previous, up ++@section Querying Servers ++ ++EUDC's basic functionality is to let you query a directory server and ++return the results back to you. There are several things you may want ++to customize in this process. ++ ++ ++@menu ++* Selecting a Server:: The first thing to do ++* Return Attributes:: Configuring what the server should return ++* Duplicate Attributes:: What to do when records have duplicate attributes ++@end menu ++ ++@node Selecting a Server, Return Attributes, Querying Servers, Querying Servers ++@subsection Selecting a Server ++ ++Before doing any query you will need to set the directory server. You ++need to specify the name of the host machine running the server software ++and the protocol to use. If you do not set the server in any fashion, ++EUDC will ask you for one when you make your first query. ++ ++You can set the server by selecting one from your hotlist of servers ++(@pxref{The Server Hotlist}) available in the @samp{Server} submenu or ++by selecting @samp{New Server} in that same menu. ++ ++LDAP servers generally require some configuration before you can perform ++queries on them. In particular, the @dfn{search base} must be ++configured. If the server you select has no configured search base then ++EUDC will propose you to configure it at this point. A customization ++buffer will be displayed where you can edit the search base and other ++parameters for the server. ++ ++@defvar eudc-server ++The name or IP address of the remote directory server. A TCP port number ++may be specified by appending a colon and a number to the name of the ++server. You will not need this unless your server runs on a port other ++than the default (which depends on the protocol). ++If the directory server resides on your own computer (which is the case ++if you use the BBDB back end) then `localhost' is a reasonable value but ++it will be ignored anyway. ++@end defvar ++ ++@defvar eudc-protocol ++The directory protocol to use to query the server. Currently supported ++protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}. ++@end defvar ++ ++@deffn Command eudc-set-server ++This command accessible from @samp{New Server} submenu lets you specify a ++new directory server and protocol. ++@end deffn ++ ++@node Return Attributes, Duplicate Attributes, Selecting a Server, Querying Servers ++@subsection Return Attributes ++ ++Directory servers may be configured to return a default set of ++attributes for each record matching a query if the query specifies none. ++The variable @code{eudc-default-return-attributes} controls the return ++attributes you want to see, if different from the server defaults. ++ ++@defvar eudc-default-return-attributes ++A list of the default attributes to extract from directory entries. If ++set to the symbol @code{all} then all available attributes are ++returned. A value of @code{nil}, the default, means to return the ++default attributes as configured in the server. ++@end defvar ++ ++The server may return several matching records to a query. Some of the ++records may however not contain all the attributes you requested. You can ++discard those records. ++ ++@defopt eudc-strict-return-matches ++If non-@code{nil}, entries that do not contain all the requested return ++attributes are ignored. Default is @code{t}. ++@end defopt ++ ++@node Duplicate Attributes, , Return Attributes, Querying Servers ++@subsection Duplicate Attributes ++ ++Directory standards may authorize different instances of the same ++attribute in a record. For instance the record of a person may contain ++several email fields containing different email addresses. When using ++a QI directory server this is difficult to distinguish from attributes ++having multi-line values such as the postal address that may contain a ++line for the street and another one for the zip code and city name. In ++both cases, EUDC will consider the attribute duplicated. ++ ++EUDC has several methods to deal with duplicated attributes. The ++available methods are: ++ ++@table @code ++@item list ++Makes a list with the different values of the duplicate attribute. The ++record is returned with only one instance of the attribute with a list ++of all the different values as a value. This is the default method that ++is used to handle duplicate fields for which no other method has been ++specified. ++@item first ++Discards all the duplicate values of the field keeping only the first ++one. ++@item concat ++Concatenates the different values using a newline as a separator. The ++record keeps only one instance of the field the value of which is a ++single multi-line string. ++@item duplicate ++Duplicates the whole record into as many instances as there are different ++values for the field. This is the default for the email field. Thus a ++record containing 3 different email addresses is duplicated into three ++different records each having a single email address. This is ++particularly useful in combination with @code{select} as the method to ++handle multiple matches in inline expansion queries (@pxref{Inline Query ++Expansion}) because you are presented with the 3 addresses in a ++selection buffer ++@end table ++ ++Because a method may not be applicable to all fields, the variable ++@code{eudc-duplicate-attribute-handling-method} lets you specify either a ++default method for all fields or a method for each individual field. ++ ++@defvar eudc-duplicate-attribute-handling-method ++A method to handle entries containing duplicate attributes. This is ++either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol ++@var{method}. The alist form of the variable associates a method to an ++individual attribute name; the second form specifies a method applicable ++to all attribute names. Available methods are: @code{list}, ++@code{first}, @code{concat}, and @code{duplicate} (see above). The default is ++@code{list}. ++@end defvar ++ ++ ++ ++@node Query Form, Display of Query Results, Querying Servers, Usage ++@comment node-name, next, previous, up ++@section Query Form ++ ++The simplest way to query your directory server is to use the query ++form. You display the query form with the @samp{Query with Form} menu ++item or by invoking the command @kbd{M-x eudc-query-form}. The attribute ++names presented in this form are defined by the ++@code{eudc-query-form-attributes} variable (unless a non-@code{nil} ++argument is supplied to @code{eudc-query-form}). ++ ++Since the different directory protocols to which EUDC interfaces may ++use different names for equivalent attributes, EUDC defines its own set ++of attribute names and a mapping between these names and their ++protocol-specific equivalent through the variable ++@code{eudc-protocol-attributes-translation-alist}. Names currently ++defined by EUDC are @code{name}, @code{firstname}, @code{email} and ++@code{phone}. ++ ++@defvar eudc-query-form-attributes ++@findex eudc-get-attribute-list ++A list of attributes presented in the query form. Attribute names in ++this list should be either EUDC attribute names or valid attribute ++names. You can get a list of valid attribute names for the current ++protocol with the @samp{List Valid Attribute Names} menu item or the ++@kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name}, ++@code{email} and @code{phone}. ++@end defvar ++ ++@deffn Command eudc-query-form get-fields-from-server ++Display a form to query the directory server. If given a non-@code{nil} ++argument the function first queries the server for the existing fields ++and displays a corresponding form. Not all protocols may support a ++non-@code{nil} argument here. ++@end deffn ++ ++Since the names of the fields may not be explicit enough or adapted to ++be directly displayed as prompt strings in the form, the variable ++@code{eudc-user-attribute-names-alist} lets you define more explicit ++names for directory attribute names. This variable is ignored if ++@code{eudc-use-raw-directory-names} is non-@code{nil}. ++ ++@defvar eudc-user-attribute-names-alist ++This is an alist of user-defined names for the directory attributes used in ++query/response forms. Prompt strings for attributes that are not in this ++alist are derived by splitting the attribute name at underscores and ++capitalizing the individual words. ++@end defvar ++ ++@defvar eudc-use-raw-directory-names ++If non-@code{nil}, use attributes names as defined in the directory. ++Otherwise, directory query/response forms display the user attribute ++names defined in @code{eudc-user-attribute-names-alist}. ++@end defvar ++ ++@node Display of Query Results, Inline Query Expansion, Query Form, Usage ++@comment node-name, next, previous, up ++@section Display of Query Results ++ ++Upon successful completion of a form query, EUDC will display a buffer ++containing the results of the query. ++ ++The fields that are returned for each record ++are controlled by @code{eudc-default-return-attributes} (@pxref{Return ++Attributes}). ++ ++The display of each individual field can be performed by an arbitrary ++function which allows specific processing for binary values, such as ++images or audio samples, as well as values with semantics, such as ++URLs. ++ ++@defvar eudc-attribute-display-method-alist ++An alist specifying methods to display attribute values. Each member of ++the list is of the form @code{(@var{name} . @var{func})} where ++@var{name} is a lowercased string naming a directory attribute ++(translated according to @code{eudc-user-attribute-names-alist} if ++@code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a ++function that will be passed the corresponding attribute values for ++display. ++@end defvar ++ ++This variable has protocol-local definitions (see @pxref{Server/Protocol ++Locals}). For instance, it is defined as follows for LDAP: ++ ++@lisp ++(eudc-protocol-set 'eudc-attribute-display-method-alist ++ '(("jpegphoto" . eudc-display-jpeg-inline) ++ ("labeledurl" . eudc-display-url) ++ ("audio" . eudc-display-sound) ++ ("labeledurl" . eudc-display-url) ++ ("url" . eudc-display-url)) ++ 'ldap) ++@end lisp ++ ++EUDC provides a set of built-in functions to display binary value types: ++ ++@defun eudc-display-generic-binary data ++Display a button for unidentified binary @var{data}. ++@end defun ++ ++@defun eudc-display-url url ++Display URL and make it clickable. ++@end defun ++ ++@defun eudc-display-sound data ++Display a button to play the sound @var{data}. ++@end defun ++ ++@defun eudc-display-jpeg-inline data ++Display the JPEG @var{data} inline at point if possible. ++@end defun ++ ++@defun eudc-display-jpeg-as-button data ++Display a button for the JPEG @var{data}. ++@end defun ++ ++Right-clicking on a binary value button pops up a contextual menu with ++options to process the value. Among these are saving the attribute ++value to a file or sending it to an external viewer command. External ++viewers should expect the value on their standard input and should ++display it or perform arbitrary processing on it. Messages sent to ++standard output are discarded. External viewers are listed in the ++variable @code{eudc-external-viewers} which you can customize. ++ ++@defvar eudc-external-viewers ++This is a list of viewer program specifications. Each specification is ++a list whose first element is a string naming the viewer for unique ++identification, the second element is the executable program which ++should be invoked and the following elements are arguments that should ++be passed to the program. ++@end defvar ++ ++ ++@node Inline Query Expansion, The Server Hotlist, Display of Query Results, Usage ++@comment node-name, next, previous, up ++@section Inline Query Expansion ++ ++Inline query expansion is a powerful method to get completion from your ++directory server. The most common usage is for expanding names to email ++addresses in mail message buffers. The expansion is performed by the ++command @kbd{M-x eudc-expand-inline} which is available from the ++@samp{Expand Inline Query} menu item but can also be conveniently ++bound to a key shortcut (@pxref{Installation}). The operation is ++controlled by the variables @code{eudc-inline-expansion-format}, ++@code{eudc-inline-query-format}, ++@code{eudc-expanding-overwrites-query} and ++@code{eudc-multiple-match-handling-method}. ++ ++If the query fails for a server, other servers may be tried successively ++until one of them finds a match (@pxref{Multi-server Queries}). ++ ++@deffn Command eudc-expand-inline replace-p ++Query the server and expand the query string before point. The query ++string consists of the buffer substring from the point back to the ++preceding comma, colon or beginning of ++line. @code{eudc-inline-query-format} controls how individual words ++are mapped onto directory attribute names. After querying the server ++for the given string, the expansion specified by ++@code{eudc-inline-expansion-format} is inserted in the buffer at ++point. If @var{replace-p} is @code{t} then this expansion replaces the ++query string in the buffer. If @code{eudc-expanding-overwrites-query} ++is non-@code{nil} then the meaning of @var{replace-p} is negated. ++@end deffn ++ ++@defvar eudc-inline-query-format ++Format of an inline expansion query. ++This is actually a list of @var{format}s. A @var{format} is a list of ++one or more EUDC attribute names. A @var{format} applies if it contains ++as many attributes as individual words in the inline query string. If ++several @var{format}s apply then they are tried in order until a match ++is found. If @code{nil} all the words will be mapped onto the default ++server/protocol attribute name (generally @code{name}). ++ ++For instance, use the following ++@lisp ++(setq eudc-inline-query-format '((name) ++ (firstname) ++ (firstname name))) ++@end lisp ++@noindent ++to indicate that single word expansion queries are to be considered as ++surnames and if no match is found then they should be tried as first ++names. Inline queries consisting of two words are considered as ++consisting of a first name followed by a surname. If the query consists ++of more than two words, then the first one is considered as the first ++name and the remaining words are all considered as surname constituents. ++ ++@var{format}s are in fact not limited to EUDC attribute names, you can ++use server or protocol specific names in them. It may be safer if you ++do so, to set the variable @code{eudc-inline-query-format} in a protocol ++or server local fashion (see @pxref{Server/Protocol Locals}). ++ ++For instance you could use the following to match up to three words ++against the @code{cn} attribute of LDAP servers: ++@lisp ++(eudc-protocol-set 'eudc-inline-query-format ++ '((cn) ++ (cn cn) ++ (cn cn cn)) ++ 'ldap) ++@end lisp ++@end defvar ++ ++@defvar eudc-inline-expansion-format ++This variable lets you control exactly what is inserted into the buffer ++upon an inline expansion request. It is a list whose first element is a ++string passed to @code{format}. Remaining elements are symbols ++corresponding to directory attribute names. The corresponding attribute ++values are passed as additional arguments to @code{format}. Default is ++@code{("%s" email)} but you may want to consider a value like @code{("%s ++<%s>" name email)} ++@end defvar ++ ++@defvar eudc-multiple-match-handling-method ++This variable controls what to do when multiple entries match a query ++for an inline expansion. Possible values are: ++@table @code ++@item first ++The first match is considered as being the only one, the others are ++discarded. ++@item select ++A selection buffer pops up where you can choose a particular match. This ++is the default value of the variable. ++@item all ++The expansion uses all records successively ++@item abort ++An error is signaled. The expansion aborts. ++@end table ++ ++Default is @code{select} ++@end defvar ++ ++ ++ ++@node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage ++@comment node-name, next, previous, up ++@section The Server Hotlist ++ ++EUDC lets you maintain a list of frequently used servers so that you ++can easily switch from one to another. This hotlist appears in the ++@samp{Server} submenu. You select a server in this list by clicking on ++its name. You can add the current server to the list with the command ++@kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable ++@code{eudc-server-hotlist} which is stored in and retrieved from the file ++designated by @code{eudc-options-file}. EUDC also provides a facility to ++edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}). ++ ++The hotlist is also used to make queries on multiple servers ++successively (@pxref{Multi-server Queries}). The order in which the ++servers are tried is the order they appear in the hotlist, therefore it ++is important to sort the hotlist appropriately. ++ ++@deffn Command eudc-bookmark-server server ++Add @var{server} to the hotlist of servers ++@end deffn ++ ++@deffn Command eudc-bookmark-current-server ++Add the current server to the hotlist of servers ++@end deffn ++ ++@defvar eudc-options-file ++The name of a file where EUDC stores its internal variables ++(the hotlist and the current server). EUDC will try to load ++that file upon initialization so, if you choose a file name ++different from the defaults @file{~/.eudc-options}, be sure to set this ++variable to the appropriate value @emph{before} EUDC is itself ++loaded. ++@end defvar ++ ++@menu ++* The Hotlist Edit Buffer:: An interactive hotlist editing facility ++@end menu ++ ++@node The Hotlist Edit Buffer, , The Server Hotlist, The Server Hotlist ++@comment node-name, next, previous, up ++@subsection The Hotlist Edit Buffer ++ ++The hotlist edit buffer offers a means to manage a list of frequently ++used servers. Commands are available in the context pop-up menu ++generally bound to the right mouse button. Those commands also have ++equivalent key bindings. ++ ++@deffn Command eudc-hotlist-add-server ++Bound to @kbd{a}. ++Add a new server to the hotlist on the line after point ++@end deffn ++ ++@deffn Command eudc-hotlist-delete-server ++Bound to @kbd{d}. ++Delete the server on the line point is on ++@end deffn ++ ++@deffn Command eudc-hotlist-select-server ++Bound to @kbd{s}. ++Select the server the point is on as the current directory server for ++the next queries ++@end deffn ++ ++@deffn Command eudc-hotlist-transpose-servers ++Bound to @kbd{t}. ++Bubble up the server the point is on to the top of the list ++@end deffn ++ ++@deffn Command eudc-hotlist-quit-edit ++Bound to @kbd{q}. ++Save the changes and quit the hotlist edit buffer. Use @kbd{x} or ++@kbd{M-x kill-buffer} to exit without saving. ++@end deffn ++ ++ ++@node Multi-server Queries, Creating BBDB Records, The Server Hotlist, Usage ++@comment node-name, next, previous, up ++@section Multi-server Queries ++ ++When using inline query expansion (@pxref{Inline Query Expansion}), EUDC ++can try to query successively a sequence of directory servers until one ++of them successfully finds a match for the query. ++ ++@defvar eudc-inline-expansion-servers ++This variable controls which servers are tried and in which order when ++trying to perform an inline query. Possible values are: ++@table @code ++@item current-server ++Only the current directory server is tried ++@item hotlist ++The servers in the hotlist are tried in order until one finds a match ++for the query or `eudc-max-servers-to-query' is reached ++@item server-then-hotlist ++The current server then the servers in the hotlist are tried in the ++order they appear in the hotlist until one of them finds a match or ++`eudc-max-servers-to-query' is reached. This is the default. ++@end table ++@end defvar ++ ++@defvar eudc-max-servers-to-query ++This variable indicates the maximum number of servers to query when ++performing a multi-server query. The default, @code{nil}, indicates ++that all available servers should be tried. ++@end defvar ++ ++ ++ ++@node Creating BBDB Records, Server/Protocol Locals, Multi-server Queries, Usage ++@comment node-name, next, previous, up ++@section Creating BBDB Records ++ ++@findex eudc-insert-record-at-point-into-bbdb ++@findex eudc-try-bbdb-insert ++With EUDC, you can automatically create BBDB records ++(@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a ++directory server. You do this by moving point to the appropriate ++record in a query result display buffer and invoking the command ++@kbd{M-x eudc-insert-record-at-point-into-bbdb} with the ++keyboard binding @kbd{b}@footnote{This key binding does not actually ++call @code{eudc-insert-record-at-point-into-bbdb} but uses ++@code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC ++cannot update an existing BBDB record and will signal an error if you ++try to insert a record matching an existing one. ++ ++@findex eudc-batch-export-records-to-bbdb ++It is also possible to export to BBDB the whole batch of records ++contained in the directory query result with the command ++@kbd{M-x eudc-batch-export-records-to-bbdb}. ++ ++Because directory systems may not enforce a strict record format, local ++server installations may use different attribute names and have ++different ways to organize the information. Furthermore BBDB has its own ++record structure. For these reasons converting a record from its ++external directory format to the BBDB format is a highly customizable ++process. ++ ++@defvar eudc-bbdb-conversion-alist ++The value of this variable should be a symbol naming an alist defining a ++mapping between BBDB field names onto directory attribute names records. ++This is a protocol-local variable and is initialized upon protocol ++switch (@pxref{Server/Protocol Locals}). The alist is made of cells of the ++form @code{(@var{bbdb-field} . @var{spec-or-list})}. ++@var{bbdb-field} is the name of a field ++that must be defined in your BBDB environment (standard field names are ++@code{name}, @code{company}, @code{net}, @code{phone}, @code{address} ++and @code{notes}). ++@var{spec-or-list} is either a single mapping specification or a list of ++mapping specifications. Lists of mapping specifications are valid for ++the @code{phone} and @code{address} BBDB fields only. @var{spec}s are ++actually s-expressions which are evaluated as follows: ++ ++@table @asis ++@item a string ++evaluates to itself ++@item a symbol ++evaluates to the symbol value. Symbols corresponding to directory ++attribute names present in the record evaluate to the value of the field ++in the record ++@item a form ++is evaluated as a function. The argument list may contain attribute ++names which evaluate to the corresponding values in the record. The form ++evaluation should return something appropriate for the particular ++@var{bbdb-field} (see @code{bbdb-create-internal}). ++@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as ++convenience functions to parse phones and addresses. ++@end table ++@end defvar ++ ++The default value of the PH-specific value of that variable is ++@code{eudc-ph-bbdb-conversion-alist}: ++ ++@lisp ++((name . name) ++ (net . email) ++ (address . (eudc-bbdbify-address address "Address")) ++ (phone . ((eudc-bbdbify-phone phone "Phone") ++ (eudc-bbdbify-phone office_phone "Office Phone")))) ++@end lisp ++ ++This means that: ++ ++@itemize @bullet ++@item ++the @code{name} field of the BBDB record gets its value ++from the @code{name} attribute of the directory record ++@item ++the @code{net} field of the BBDB record gets its value ++from the @code{email} attribute of the directory record ++@item ++the @code{address} field of the BBDB record is obtained by parsing the ++@code{address} attribute of the directory record with the function ++@code{eudc-bbdbify-address} ++@item ++two @code{phone} fields are created (when possible) in the BBDB record. ++The first one has @cite{Phone} for location and its value is obtained by ++parsing the @code{phone} attribute of the PH/QI record with the function ++@code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location ++its value is obtained by parsing the @code{office_phone} attribute of the ++PH/QI record with the function @code{eudc-bbdbify-phone}. ++@end itemize ++ ++@defun eudc-bbdbify-phone phone location ++This is a convenience function provided for use in ++@code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector ++compatible with @code{bbdb-create-internal}. @var{phone} is either a string ++supposedly containing a phone number or a list of such strings which are ++concatenated. @var{location} is used as the phone location for BBDB. ++@end defun ++ ++@defun eudc-bbdbify-address addr location ++This is a convenience function provided for use in ++@code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector ++compatible with @code{bbdb-create-internal}. @var{addr} should be an ++address string of no more than four lines or a list of lines. The last ++line is searched for the zip code, city and state name. @var{location} ++is used as the phone location for BBDB. ++@end defun ++ ++Note that only a subset of the attributes you selected with ++@code{eudc-default-return-attributes} and that are actually displayed may ++actually be inserted as part of the newly created BBDB record. ++ ++ ++@node Server/Protocol Locals, , Creating BBDB Records, Usage ++@comment node-name, next, previous, up ++@section Server/Protocol Locals ++ ++EUDC can be customized independently for each server or directory ++protocol. All variables can be given local bindings that are activated ++when a particular server and/or protocol becomes active. This is much ++like buffer-local bindings but on a per server or per protocol basis. ++ ++@menu ++* Manipulating local bindings:: Functions to set and query local bindings ++@end menu ++ ++@node Manipulating local bindings, , Server/Protocol Locals, Server/Protocol Locals ++@comment node-name, next, previous, up ++@subsection Manipulating local bindings ++ ++EUDC offers functions that let you set and query variables on a per ++server or per protocol basis. ++ ++The following predicates allow you to test the existence of ++server/protocol local bindings for a particular variable. ++ ++@defun eudc-server-local-variable-p var ++Return non-@code{nil} if @var{var} has server-local bindings ++@end defun ++ ++@defun eudc-protocol-local-variable-p var ++Return non-@code{nil} if @var{var} has protocol-local bindings ++@end defun ++ ++The following functions allow you to set the value of a variable with ++various degrees of locality. ++ ++@defun eudc-default-set var val ++Set the EUDC default value of @var{var} to @var{val}. ++The current binding of @var{var} (if local to the current server or ++protocol) is not changed. ++@end defun ++ ++@defun eudc-protocol-set var val &optional protocol ++Set the binding of @var{var} local to @var{protocol} to @var{val}. If ++omitted, @var{protocol} defaults to the current value of ++@code{eudc-protocol}. The current binding of @var{var} is changed only ++if @var{protocol} is omitted. ++@end defun ++ ++@defun eudc-server-set var val &optional server ++Set the binding of @var{var} local to @var{server} to @var{val}. If ++omitted, @var{server} defaults to the current value of ++@code{eudc-server}. The current binding of @var{var} is changed only if ++@var{server} is omitted. ++@end defun ++ ++@defun eudc-set var val ++Set the most local (server, protocol or default) binding of @var{var} to ++@var{val}. The current binding of @var{var} is also set to @var{val}. ++@end defun ++ ++The following variables allow you to query the various bindings of a ++variable (local or non-local). ++ ++@defun eudc-variable-default-value var ++Return the default binding of @var{var} (outside of a particular server ++or protocol local binding). ++Return @code{unbound} if @var{var} has no EUDC default value. ++@end defun ++ ++@defun eudc-variable-protocol-value var &optional protocol ++Return the value of @var{var} local to @var{protocol}. Return ++@code{unbound} if @var{var} has no value local to @var{protocol}. ++@var{protocol} defaults to @code{eudc-protocol}. ++@end defun ++ ++@defun eudc-variable-server-value var [server] ++Return the value of @var{var} local to @var{server}. ++Return @code{unbound} if @var{var} has no value local to @var{server}. ++@var{server} defaults to @code{eudc-server}. ++@end defun ++ ++Changing a protocol-local or server-local value of a variable has no ++effect on its current value. The following command is used to ++synchronize the current values of variables with their local values ++given the current @code{eudc-server} and @code{eudc-protocol}: ++ ++@defun eudc-update-local-variables ++Update all EUDC variables according to their local settings. ++@end defun ++ ++ ++ ++@node Credits, GNU Free Documentation License, Usage, Top ++@comment node-name, next, previous, up ++@chapter Credits ++ ++EUDC was written by Oscar Figueiredo based on @file{ph.el} by the ++same author. ++ ++Thanks to Soren Dayton for his suggestions, his enthusiasm and his help ++in testing and proofreading the code and docs of @file{ph.el}. ++ ++@node GNU Free Documentation License, Command and Function Index, Credits, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Command and Function Index, Variables Index, GNU Free Documentation License, Top ++@comment node-name, next, previous, up ++@unnumbered Command and Function Index ++ ++@printindex fn ++ ++@node Variables Index, , Command and Function Index, Top ++@comment node-name, next, previous, up ++@unnumbered Variables Index ++ ++@printindex vr ++ ++@bye ++ ++@ignore ++ arch-tag: 1b79460b-4ea1-441d-ab45-05ddd16ef241 ++@end ignore +diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi +new file mode 100644 +index 0000000..a713d7c +--- /dev/null ++++ b/doc/misc/flymake.texi +@@ -0,0 +1,755 @@ ++\input texinfo @c -*-texinfo-*- ++@comment %**start of header ++@setfilename ../../info/flymake ++@set VERSION 0.3 ++@set UPDATED April 2004 ++@settitle GNU Flymake @value{VERSION} ++@syncodeindex pg cp ++@comment %**end of header ++ ++@copying ++This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), ++which is a universal on-the-fly syntax checker for GNU Emacs. ++ ++Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* Flymake: (flymake). A universal on-the-fly syntax checker. ++@end direntry ++ ++@titlepage ++@title GNU Flymake ++@subtitle for version @value{VERSION}, @value{UPDATED} ++@author Pavel Kobiakov(@email{pk_at_work@@yahoo.com}) ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top ++@top GNU Flymake ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview of Flymake:: ++* Installing Flymake:: ++* Using Flymake:: ++* Configuring Flymake:: ++* Flymake Implementation:: ++* GNU Free Documentation License:: ++* Index:: ++@end menu ++ ++@node Overview of Flymake ++@chapter Overview ++@cindex Overview of Flymake ++ ++Flymake is a universal on-the-fly syntax checker implemented as an ++Emacs minor mode. Flymake runs the pre-configured syntax check tool ++(compiler for C++ files, @code{perl} for perl files, etc.) in the ++background, passing it a temporary copy of the current buffer, and ++parses the output for known error/warning message patterns. Flymake ++then highlights erroneous lines (i.e. lines for which at least one ++error or warning has been reported by the syntax check tool), and ++displays an overall buffer status in the mode line. Status information ++displayed by Flymake contains total number of errors and warnings ++reported for the buffer during the last syntax check. ++ ++@code{flymake-goto-next-error} and @code{flymake-goto-prev-error} ++functions allow for easy navigation to the next/previous erroneous ++line, respectively. ++ ++Calling @code{flymake-display-err-menu-for-current-line} will popup a ++menu containing error messages reported by the syntax check tool for ++the current line. Errors/warnings belonging to another file, such as a ++@code{.h} header file included by a @code{.c} file, are shown in the ++current buffer as belonging to the first line. Menu items for such ++messages also contain a filename and a line number. Selecting such a ++menu item will automatically open the file and jump to the line with ++error. ++ ++Syntax check is done 'on-the-fly'. It is started whenever ++ ++@itemize @bullet ++@item buffer is loaded ++@item a newline character is added to the buffer ++@item some changes were made to the buffer more than @code{0.5} seconds ago (the ++delay is configurable). ++@end itemize ++ ++Flymake is a universal syntax checker in the sense that it's easily ++extended to support new syntax check tools and error message ++patterns. @xref{Configuring Flymake}. ++ ++@node Installing Flymake ++@chapter Installing ++@cindex Installing Flymake ++ ++ ++Flymake is packaged in a single file, @code{flymake.el}. ++ ++To install/update Flymake, place @code{flymake.el} to a directory ++somewhere on Emacs load path. You might also want to byte-compile ++@code{flymake.el} to improve performance. ++ ++Also, place the following line in the @code{.emacs} file. ++ ++@lisp ++(require 'flymake) ++@end lisp ++ ++You might also map the most frequently used Flymake functions, such as ++@code{flymake-goto-next-error}, to some keyboard shortcuts: ++ ++@lisp ++(global-set-key [f3] 'flymake-display-err-menu-for-current-line) ++(global-set-key [f4] 'flymake-goto-next-error) ++@end lisp ++ ++@node Using Flymake ++@chapter Using Flymake ++@cindex Using Flymake ++ ++@menu ++* Flymake mode:: ++* Running the syntax check:: ++* Navigating to error lines:: ++* Viewing error messages:: ++* Syntax check statuses:: ++* Troubleshooting:: ++@end menu ++ ++@node Flymake mode ++@section Flymake mode ++@cindex flymake-mode ++ ++Flymake is an Emacs minor mode. To use Flymake, you ++must first activate @code{flymake-mode} by using the ++@code{flymake-mode} function. ++ ++Instead of manually activating @code{flymake-mode}, you can configure ++Flymake to automatically enable @code{flymake-mode} upon opening any ++file for which syntax check is possible. To do so, place the following ++line in @code{.emacs}: ++ ++@lisp ++(add-hook 'find-file-hook 'flymake-find-file-hook) ++@end lisp ++ ++@node Running the syntax check ++@section Running the syntax check ++@cindex Manually starting the syntax check ++ ++When @code{flymake-mode} is active, syntax check is started ++automatically on any of the three conditions mentioned above. Syntax ++check can also be started manually by using the ++@code{flymake-start-syntax-check-for-current-buffer} function. This ++can be used, for example, when changes were made to some other buffer ++affecting the current buffer. ++ ++@node Navigating to error lines ++@section Navigating to error lines ++@cindex Navigating to error lines ++ ++After syntax check is completed, lines for which at least one error or ++warning has been reported are highlighted, and total number of errors ++and warning is shown in the mode line. Use the following functions to ++navigate the highlighted lines. ++ ++@multitable @columnfractions 0.25 0.75 ++ ++@item @code{flymake-goto-next-error} ++@tab Moves point to the next erroneous line, if any. ++ ++@item @code{flymake-goto-prev-error} ++@tab Moves point to the previous erroneous line. ++ ++@end multitable ++ ++These functions treat erroneous lines as a linked list. Therefore, ++@code{flymake-goto-next-error} will go to the first erroneous line ++when invoked in the end of the buffer. ++ ++@node Viewing error messages ++@section Viewing error messages ++@cindex Viewing error messages ++ ++To view error messages belonging to the current line, use the ++@code{flymake-display-err-menu-for-current-line} function. If there's ++at least one error or warning reported for the current line, this ++function will display a popup menu with error/warning texts. ++Selecting the menu item whose error belongs to another file brings ++forward that file with the help of the ++@code{flymake-goto-file-and-line} function. ++ ++@node Syntax check statuses ++@section Syntax check statuses ++@cindex Syntax check statuses ++ ++After syntax check is finished, its status is displayed in the mode line. ++The following statuses are defined. ++ ++@multitable @columnfractions 0.25 0.75 ++@item Flymake* or Flymake:E/W* ++@tab Flymake is currently running. For the second case, E/W contains the ++ error and warning count for the previous run. ++ ++@item Flymake ++@tab Syntax check is not running. Usually this means syntax check was ++ successfully passed (no errors, no warnings). Other possibilities are: ++ syntax check was killed as a result of executing ++ @code{flymake-compile}, or syntax check cannot start as compilation ++ is currently in progress. ++ ++@item Flymake:E/W ++@tab Number of errors/warnings found by the syntax check process. ++ ++@item Flymake:! ++@tab Flymake was unable to find master file for the current buffer. ++@end multitable ++ ++The following errors cause a warning message and switch flymake mode ++OFF for the buffer. ++ ++@multitable @columnfractions 0.25 0.75 ++@item CFGERR ++@tab Syntax check process returned nonzero exit code, but no ++ errors/warnings were reported. This indicates a possible configuration ++ error (for example, no suitable error message patterns for the ++ syntax check tool). ++ ++@item NOMASTER ++@tab Flymake was unable to find master file for the current buffer. ++ ++@item NOMK ++@tab Flymake was unable to find a suitable buildfile for the current buffer. ++ ++@item PROCERR ++@tab Flymake was unable to launch a syntax check process. ++@end multitable ++ ++ ++@node Troubleshooting ++@section Troubleshooting ++@cindex Logging ++@cindex Troubleshooting ++ ++Flymake uses a simple logging facility for indicating important points ++in the control flow. The logging facility sends logging messages to ++the @code{*Messages*} buffer. The information logged can be used for ++resolving various problems related to Flymake. ++ ++Logging output is controlled by the @code{flymake-log-level} ++variable. @code{3} is the most verbose level, and @code{-1} switches ++logging off. ++ ++@node Configuring Flymake ++@chapter Configuring and Extending Flymake ++@cindex Configuring and Extending Flymake ++ ++@menu ++* Customizable variables:: ++* Adding support for a new syntax check tool:: ++@end menu ++ ++Flymake was designed to be easily extended for supporting new syntax ++check tools and error message patterns. ++ ++@node Customizable variables ++@section Customizable variables ++@cindex Customizable variables ++ ++This section summarizes variables used for Flymake ++configuration. ++ ++@table @code ++@item flymake-log-level ++Controls logging output, see @ref{Troubleshooting}. ++ ++@item flymake-allowed-file-name-masks ++A list of @code{(filename-regexp, init-function, cleanup-function ++getfname-function)} for configuring syntax check tools. @xref{Adding ++support for a new syntax check tool}. ++ ++@item flymake-buildfile-dirs ++A list of directories (relative paths) for searching a ++buildfile. @xref{Locating the buildfile}. ++ ++@item flymake-master-file-dirs ++A list of directories for searching a master file. @xref{Locating a ++master file}. ++ ++@item flymake-get-project-include-dirs-function ++A function used for obtaining a list of project include dirs (C/C++ ++specific). @xref{Getting the include directories}. ++ ++@item flymake-master-file-count-limit ++@itemx flymake-check-file-limit ++Used when looking for a master file. @xref{Locating a master file}. ++ ++@item flymake-err-line-patterns ++Patterns for error/warning messages in the form @code{(regexp file-idx ++line-idx col-idx err-text-idx)}. @xref{Parsing the output}. ++ ++@item flymake-compilation-prevents-syntax-check ++A flag indicating whether compilation and syntax check of the same ++file cannot be run simultaneously. ++ ++@item flymake-no-changes-timeout ++If any changes are made to the buffer, syntax check is automatically ++started after @code{flymake-no-changes-timeout} seconds. ++ ++@item flymake-gui-warnings-enabled ++A boolean flag indicating whether Flymake will show message boxes for ++non-recoverable errors. If @code{flymake-gui-warnings-enabled} is ++@code{nil}, these errors will only be logged to the @code{*Messages*} ++buffer. ++ ++@item flymake-start-syntax-check-on-newline ++A boolean flag indicating whether to start syntax check after a ++newline character is added to the buffer. ++ ++@item flymake-errline ++A custom face for highlighting lines for which at least one error has ++been reported. ++ ++@item flymake-warnline ++A custom face for highlighting lines for which at least one warning ++and no errors have been reported. ++ ++@end table ++ ++@node Adding support for a new syntax check tool ++@section Adding support for a new syntax check tool ++@cindex Adding support for a new syntax check tool ++ ++@menu ++* Example -- Configuring a tool called directly:: ++* Example -- Configuring a tool called via make:: ++@end menu ++ ++Syntax check tools are configured using the ++@code{flymake-allowed-file-name-masks} list. Each item of this list ++has the following format: ++ ++@lisp ++(filename-regexp, init-function, cleanup-function, getfname-function) ++@end lisp ++ ++@table @code ++@item filename-regexp ++This field is used as a key for locating init/cleanup/getfname ++functions for the buffer. Items in ++@code{flymake-allowed-file-name-masks} are searched sequentially. The ++first item with @code{filename-regexp} matching buffer filename is ++selected. If no match is found, @code{flymake-mode} is switched off. ++ ++@item init-function ++@code{init-function} is required to initialize the syntax check, ++usually by creating a temporary copy of the buffer contents. The ++function must return @code{(list cmd-name arg-list)}. If ++@code{init-function} returns null, syntax check is aborted, by ++@code{flymake-mode} is not switched off. ++ ++@item cleanup-function ++@code{cleanup-function} is called after the syntax check process is ++complete and should take care of proper deinitialization, which is ++usually deleting a temporary copy created by the @code{init-function}. ++ ++@item getfname-function ++This function is used for translating filenames reported by the syntax ++check tool into ``real'' filenames. Filenames reported by the tool ++will be different from the real ones, as actually the tool works with ++the temporary copy. In most cases, the default implementation ++provided by Flymake, @code{flymake-get-real-file-name}, can be used as ++@code{getfname-function}. ++ ++@end table ++ ++To add support for a new syntax check tool, write corresponding ++@code{init-function}, and, optionally @code{cleanup-function} and ++@code{getfname-function}. If the format of error messages reported by ++the new tool is not yet supported by Flymake, add a new entry to ++the @code{flymake-err-line-patterns} list. ++ ++The following sections contain some examples of configuring Flymake ++support for various syntax check tools. ++ ++@node Example -- Configuring a tool called directly ++@subsection Example -- Configuring a tool called directly ++@cindex Adding support for perl ++ ++In this example, we will add support for @code{perl} as a syntax check ++tool. @code{perl} supports the @code{-c} option which does syntax ++checking. ++ ++First, we write the @code{init-function}: ++ ++@lisp ++(defun flymake-perl-init () ++ (let* ((temp-file (flymake-init-create-temp-buffer-copy ++ 'flymake-create-temp-inplace)) ++ (local-file (file-relative-name ++ temp-file ++ (file-name-directory buffer-file-name)))) ++ (list "perl" (list "-wc " local-file)))) ++@end lisp ++ ++@code{flymake-perl-init} creates a temporary copy of the buffer ++contents with the help of ++@code{flymake-init-create-temp-buffer-copy}, and builds an appropriate ++command line. ++ ++Next, we add a new entry to the ++@code{flymake-allowed-file-name-masks}: ++ ++@lisp ++(setq flymake-allowed-file-name-masks ++ (cons '(".+\\.pl$" ++ flymake-perl-init ++ flymake-simple-cleanup ++ flymake-get-real-file-name) ++ flymake-allowed-file-name-masks)) ++@end lisp ++ ++Note that we use standard @code{cleanup-function} and ++@code{getfname-function}. ++ ++Finally, we add an entry to @code{flymake-err-line-patterns}: ++ ++@lisp ++(setq flymake-err-line-patterns ++ (cons '("\\(.*\\) at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]" ++ 2 3 nil 1) ++ flymake-err-line-patterns)) ++@end lisp ++ ++@node Example -- Configuring a tool called via make ++@subsection Example -- Configuring a tool called via make ++@cindex Adding support for C (gcc+make) ++ ++In this example we will add support for C files syntax checked by ++@code{gcc} called via @code{make}. ++ ++We're not required to write any new functions, as Flymake already has ++functions for @code{make}. We just add a new entry to the ++@code{flymake-allowed-file-name-masks}: ++ ++@lisp ++(setq flymake-allowed-file-name-masks ++ (cons '(".+\\.c$" ++ flymake-simple-make-init ++ flymake-simple-cleanup ++ flymake-get-real-file-name) ++ flymake-allowed-file-name-masks)) ++@end lisp ++ ++@code{flymake-simple-make-init} builds the following @code{make} ++command line: ++ ++@lisp ++(list "make" ++ (list "-s" "-C" ++ base-dir ++ (concat "CHK_SOURCES=" source) ++ "SYNTAX_CHECK_MODE=1" ++ "check-syntax")) ++@end lisp ++ ++@code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}. ++ ++Thus, @code{Makefile} must contain the @code{check-syntax} target. In ++our case this target might look like this: ++ ++@verbatim ++check-syntax: ++ gcc -o nul -S ${CHK_SOURCES} ++@end verbatim ++ ++The format of error messages reported by @code{gcc} is already ++supported by Flymake, so we don't have to add a new entry to ++@code{flymake-err-line-patterns}. ++ ++@node Flymake Implementation ++@chapter Flymake Implementation ++@cindex Implementation details ++ ++@menu ++* Determining whether syntax check is possible:: ++* Making a temporary copy:: ++* Locating a master file:: ++* Getting the include directories:: ++* Locating the buildfile:: ++* Starting the syntax check process:: ++* Parsing the output:: ++* Highlighting erroneous lines:: ++* Interaction with other modes:: ++@end menu ++ ++Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}. ++Flymake first determines whether it is able to do syntax ++check. It then saves a copy of the buffer in a temporary file in the ++buffer's directory (or in the system temp directory -- for java ++files), creates a syntax check command and launches a process with ++this command. The output is parsed using a list of error message patterns, ++and error information (file name, line number, type and text) is ++saved. After the process has finished, Flymake highlights erroneous ++lines in the buffer using the accumulated error information. ++ ++@node Determining whether syntax check is possible ++@section Determining whether syntax check is possible ++@cindex Syntax check models ++@cindex Master file ++ ++Syntax check is considered possible if there's an entry in ++@code{flymake-allowed-file-name-masks} matching buffer's filename and ++its @code{init-function} returns non-@code{nil} value. ++ ++Two syntax check modes are distinguished: ++ ++@enumerate ++ ++@item ++Buffer can be syntax checked in a standalone fashion, that is, the ++file (its temporary copy, in fact) can be passed over to the compiler to ++do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java) ++sources. ++ ++@item ++Buffer can be syntax checked, but additional file, called master file, ++is required to perform this operation. A master file is a file that ++includes the current file, so that running a syntax check tool on it ++will also check syntax in the current file. Examples are C/C++ (.h, ++.hpp) headers. ++ ++@end enumerate ++ ++These modes are handled inside init/cleanup/getfname functions, see ++@ref{Adding support for a new syntax check tool}. ++ ++Flymake contains implementations of all functionality required to ++support different syntax check modes described above (making ++temporary copies, finding master files, etc.), as well as some ++tool-specific (routines for @code{make}, @code{Ant}, etc.) code. ++ ++ ++@node Making a temporary copy ++@section Making a temporary copy ++@cindex Temporary copy of the buffer ++@cindex Master file ++ ++After the possibility of the syntax check has been determined, a ++temporary copy of the current buffer is made so that the most recent ++unsaved changes could be seen by the syntax check tool. Making a copy ++is quite straightforward in a standalone case (mode @code{1}), as it's ++just saving buffer contents to a temporary file. ++ ++Things get trickier, however, when master file is involved, as it ++requires to ++ ++@itemize @bullet ++@item locate a master file ++@item patch it to include the current file using its new (temporary) ++name. ++@end itemize ++ ++Locating a master file is discussed in the following section. ++ ++Patching just changes all appropriate lines of the master file so that they ++use the new (temporary) name of the current file. For example, suppose current ++file name is @code{file.h}, the master file is @code{file.cpp}, and ++it includes current file via @code{#include "file.h"}. Current file's copy ++is saved to file @code{file_flymake.h}, so the include line must be ++changed to @code{#include "file_flymake.h"}. Finally, patched master file ++is saved to @code{file_flymake_master.cpp}, and the last one is passed to ++the syntax check tool. ++ ++@node Locating a master file ++@section Locating a master file ++@cindex Master file ++ ++Master file is located in two steps. ++ ++First, a list of possible master files is built. A simple name ++matching is used to find the files. For a C++ header @code{file.h}, ++Flymake searches for all @code{.cpp} files in the directories whose relative paths are ++stored in a customizable variable @code{flymake-master-file-dirs}, which ++usually contains something like @code{("." "./src")}. No more than ++@code{flymake-master-file-count-limit} entries is added to the master file ++list. The list is then sorted to move files with names @code{file.cpp} to ++the top. ++ ++Next, each master file in a list is checked to contain the appropriate ++include directives. No more than @code{flymake-check-file-limit} of each ++file are parsed. ++ ++For @code{file.h}, the include directives to look for are ++@code{#include "file.h"}, @code{#include "../file.h"}, etc. Each ++include is checked against a list of include directories ++(see @ref{Getting the include directories}) to be sure it points to the ++correct @code{file.h}. ++ ++First matching master file found stops the search. The master file is then ++patched and saved to disk. In case no master file is found, syntax check is ++aborted, and corresponding status (!) is reported in the mode line. ++ ++@node Getting the include directories ++@section Getting the include directories ++@cindex Include directories (C/C++ specific) ++ ++Two sets of include directories are distinguished: system include directories ++and project include directories. The former is just the contents of the ++@code{INCLUDE} environment variable. The latter is not so easy to obtain, ++and the way it can be obtained can vary greatly for different projects. ++Therefore, a customizable variable ++@code{flymake-get-project-include-dirs-function} is used to provide the ++way to implement the desired behavior. ++ ++The default implementation, @code{flymake-get-project-include-dirs-imp}, ++uses a @code{make} call. This requires a correct base directory, that is, a ++directory containing a correct @code{Makefile}, to be determined. ++ ++As obtaining the project include directories might be a costly operation, its ++return value is cached in the hash table. The cache is cleared in the beginning ++of every syntax check attempt. ++ ++@node Locating the buildfile ++@section Locating the buildfile ++@cindex Locating the buildfile ++@cindex buildfile, locating ++@cindex Makefile, locating ++ ++Flymake can be configured to use different tools for performing syntax ++checks. For example, it can use direct compiler call to syntax check a perl ++script or a call to @code{make} for a more complicated case of a ++@code{C/C++} source. The general idea is that simple files, like perl ++scripts and html pages, can be checked by directly invoking a ++corresponding tool. Files that are usually more complex and generally ++used as part of larger projects, might require non-trivial options to ++be passed to the syntax check tool, like include directories for ++C++. The latter files are syntax checked using some build tool, like ++@code{make} or @code{Ant}. ++ ++All @code{make} configuration data is usually stored in a file called ++@code{Makefile}. To allow for future extensions, flymake uses a notion of ++buildfile to reference the 'project configuration' file. ++ ++Special function, @code{flymake-find-buildfile} is provided for locating buildfiles. ++Searching for a buildfile is done in a manner similar to that of searching ++for possible master files. A customizable variable ++@code{flymake-buildfile-dirs} holds a list of relative paths to the ++buildfile. They are checked sequentially until a buildfile is found. In case ++there's no build file, syntax check is aborted. ++ ++Buildfile values are also cached. ++ ++@node Starting the syntax check process ++@section Starting the syntax check process ++@cindex Syntax check process ++ ++The command line (command name and the list of arguments) for launching a process is returned by the ++initialization function. Flymake then just calls @code{start-process} ++to start an asynchronous process and configures process filter and ++sentinel which is used for processing the output of the syntax check ++tool. ++ ++@node Parsing the output ++@section Parsing the output ++@cindex Parsing the output ++ ++The output generated by the syntax check tool is parsed in the process ++filter/sentinel using the error message patterns stored in the ++@code{flymake-err-line-patterns} variable. This variable contains a ++list of items of the form @code{(regexp file-idx line-idx ++err-text-idx)}, used to determine whether a particular line is an ++error message and extract file name, line number and error text, ++respectively. Error type (error/warning) is also guessed by matching ++error text with the '@code{^[wW]arning}' pattern. Anything that was not ++classified as a warning is considered an error. Type is then used to ++sort error menu items, which shows error messages first. ++ ++Flymake is also able to interpret error message patterns missing err-text-idx ++information. This is done by merely taking the rest of the matched line ++(@code{(substring line (match-end 0))}) as error text. This trick allows ++to make use of a huge collection of error message line patterns from ++@code{compile.el}. All these error patterns are appended to ++the end of @code{flymake-err-line-patterns}. ++ ++The error information obtained is saved in a buffer local ++variable. The buffer for which the process output belongs is ++determined from the process-id@w{}->@w{}buffer mapping updated ++after every process launch/exit. ++ ++@node Highlighting erroneous lines ++@section Highlighting erroneous lines ++@cindex Erroneous lines, faces ++ ++Highlighting is implemented with overlays and happens in the process ++sentinel, after calling the cleanup function. Two customizable faces ++are used: @code{flymake-errline} and ++@code{flymake-warnline}. Errors belonging outside the current ++buffer are considered to belong to line 1 of the current buffer. ++ ++@node Interaction with other modes ++@section Interaction with other modes ++@cindex Interaction with other modes ++@cindex Interaction with compile mode ++ ++The only mode flymake currently knows about is @code{compile}. ++ ++Flymake can be configured to not start syntax check if it thinks the ++compilation is in progress. The check is made by the ++@code{flymake-compilation-is-running}, which tests the ++@code{compilation-in-progress} variable. The reason why this might be ++useful is saving CPU time in case both syntax check and compilation ++are very CPU intensive. The original reason for adding this feature, ++though, was working around a locking problem with MS Visual C++ compiler. ++ ++Flymake also provides an alternative command for starting compilation, ++@code{flymake-compile}: ++ ++@lisp ++(defun flymake-compile () ++ "Kill all flymake syntax checks then start compilation." ++ (interactive) ++ (flymake-stop-all-syntax-checks) ++ (call-interactively 'compile)) ++@end lisp ++ ++It just kills all the active syntax check processes before calling ++@code{compile}. ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index ++@unnumbered Index ++ ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 9f0db077-5598-49ab-90b9-8df9248a63ec ++@end ignore +diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi +new file mode 100644 +index 0000000..4f6280b +--- /dev/null ++++ b/doc/misc/forms.texi +@@ -0,0 +1,982 @@ ++\input texinfo @c -*-texinfo-*- ++@c documentation for forms-mode ++@c Written by Johan Vromans, and edited by Richard Stallman ++ ++@comment %**start of header (This is for running Texinfo on a region.) ++@setfilename ../../info/forms ++@settitle Forms Mode User's Manual ++@syncodeindex vr cp ++@syncodeindex fn cp ++@syncodeindex ky cp ++@iftex ++@finalout ++@setchapternewpage odd ++@end iftex ++@c @smallbook ++@comment %**end of header (This is for running Texinfo on a region.) ++ ++@copying ++This file documents Forms mode, a form-editing major mode for GNU Emacs. ++ ++Copyright @copyright{} 1989, 1997, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* Forms: (forms). Emacs package for editing data bases ++ by filling in forms. ++@end direntry ++ ++@titlepage ++@sp 6 ++@center @titlefont{Forms Mode User's Manual} ++@sp 4 ++@center Forms-Mode version 2 ++@sp 1 ++@center for GNU Emacs 22.1 ++@sp 1 ++@center April 2007 ++@sp 5 ++@center Johan Vromans ++@center @i{jvromans@@squirrel.nl} ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top ++@top Forms Mode ++ ++Forms mode is an Emacs major mode for working with simple textual data ++bases in a forms-oriented manner. In Forms mode, the information in ++these files is presented in an Emacs window in a user-defined format, ++one record at a time. The user can view records or modify their ++contents. ++ ++Forms mode is not a simple major mode, but requires two files to do its ++job: a control file and a data file. The data file holds the ++actual data to be presented. The control file describes ++how to present it. ++ ++@insertcopying ++ ++@menu ++* Forms Example:: An example: editing the password data base. ++* Entering and Exiting Forms Mode:: ++ How to visit a file in Forms mode. ++* Forms Commands:: Special commands to use while in Forms mode. ++* Data File Format:: How to format the data file. ++* Control File Format:: How to control forms mode. ++* Format Description:: How to define the forms layout. ++* Modifying Forms Contents:: How to modify. ++* Miscellaneous:: Forms mode messages and other remarks. ++* Error Messages:: List of error messages forms mode can produce. ++* Long Example:: A more complex control file example. ++* GNU Free Documentation License:: The license for this documentation. ++* Credits:: Thanks everyone. ++* Index:: Index to this manual. ++@end menu ++@end ifnottex ++ ++@node Forms Example ++@chapter Forms Example ++ ++Let's illustrate Forms mode with an example. Suppose you are looking at ++the @file{/etc/passwd} file, and the screen looks like this: ++ ++@example ++====== /etc/passwd ====== ++ ++User : root Uid: 0 Gid: 1 ++ ++Name : Super User ++ ++Home : / ++ ++Shell: /bin/sh ++@end example ++ ++As you can see, the familiar fields from the entry for the super user ++are all there, but instead of being colon-separated on one single line, ++they make up a forms. ++ ++The contents of the forms consist of the contents of the fields of the ++record (e.g. @samp{root}, @samp{0}, @samp{1}, @samp{Super User}) ++interspersed with normal text (e.g @samp{User : }, @samp{Uid: }). ++ ++If you modify the contents of the fields, Forms mode will analyze your ++changes and update the file appropriately. You cannot modify the ++interspersed explanatory text (unless you go to some trouble about it), ++because that is marked read-only (@pxref{Text Properties,,, elisp, The ++Emacs Lisp Reference Manual}). ++ ++The Forms mode control file specifies the relationship between the ++format of @file{/etc/passwd} and what appears on the screen in Forms ++mode. @xref{Control File Format}. ++ ++@node Entering and Exiting Forms Mode ++@chapter Entering and Exiting Forms Mode ++ ++@table @kbd ++@findex forms-find-file ++@item M-x forms-find-file @key{RET} @var{control-file} @key{RET} ++Visit a database using Forms mode. Specify the name of the ++@strong{control file}, not the data file! ++ ++@findex forms-find-file-other-window ++@item M-x forms-find-file-other-window @key{RET} @var{control-file} @key{RET} ++Similar, but displays the file in another window. ++@end table ++ ++The command @code{forms-find-file} evaluates the file ++@var{control-file}, and also visits it in Forms mode. What you see in ++its buffer is not the contents of this file, but rather a single record ++of the corresponding data file that is visited in its own buffer. So ++there are two buffers involved in Forms mode: the @dfn{forms buffer} ++that is initially used to visit the control file and that shows the ++records being browsed, and the @dfn{data buffer} that holds the data ++file being visited. The latter buffer is normally not visible. ++ ++Initially, the first record is displayed in the forms buffer. ++The mode line displays the major mode name @samp{Forms}, followed by the ++minor mode @samp{View} if the data base is read-only. The number of the ++current record (@var{n}) and the total number of records in the ++file(@var{t}) are shown in the mode line as @samp{@var{n}/@var{t}}. For ++example: ++ ++@example ++--%%-Emacs: passwd-demo (Forms View 1/54)----All------- ++@end example ++ ++If the buffer is not read-only, you may change the buffer to modify the ++fields in the record. When you move to a different record, the contents ++of the buffer are parsed using the specifications in ++@code{forms-format-list}, and the data file is updated. If the record ++has fields that aren't included in the display, they are not changed. ++ ++@vindex forms-mode-hooks ++Entering Forms mode runs the normal hook @code{forms-mode-hooks} to ++perform user-defined customization. ++ ++To save any modified data, you can use @kbd{C-x C-s} ++(@code{forms-save-buffer}). This does not save the forms buffer (which would ++be rather useless), but instead saves the buffer visiting the data file. ++ ++To terminate Forms mode, you can use @kbd{C-x C-s} (@code{forms-save-buffer}) ++and then kill the forms buffer. However, the data buffer will still ++remain. If this is not desired, you have to kill this buffer too. ++ ++@node Forms Commands ++@chapter Forms Commands ++ ++The commands of Forms mode belong to the @kbd{C-c} prefix, with one ++exception: @key{TAB}, which moves to the next field. Forms mode uses ++different key maps for normal mode and read-only mode. In read-only ++Forms mode, you can access most of the commands without the @kbd{C-c} ++prefix, but you must type ordinary letters instead of control ++characters; for example, type @kbd{n} instead of @kbd{C-c C-n}. ++ ++If your Emacs has been built with X-toolkit support, Forms mode will ++provide its own menu with a number of Forms mode commands. ++ ++@table @kbd ++@findex forms-next-record ++@kindex C-c C-n ++@item C-c C-n ++Show the next record (@code{forms-next-record}). With a numeric ++argument @var{n}, show the @var{n}th next record. ++ ++@findex forms-prev-record ++@kindex C-c C-p ++@item C-c C-p ++Show the previous record (@code{forms-prev-record}). With a numeric ++argument @var{n}, show the @var{n}th previous record. ++ ++@findex forms-jump-record ++@kindex C-c C-l ++@item C-c C-l ++Jump to a record by number (@code{forms-jump-record}). Specify ++the record number with a numeric argument. ++ ++@findex forms-first-record ++@kindex C-c < ++@item C-c < ++Jump to the first record (@code{forms-first-record}). ++ ++@findex forms-last-record ++@kindex C-c > ++@item C-c > ++Jump to the last record (@code{forms-last-record}). This command also ++recalculates the number of records in the data file. ++ ++@findex forms-next-field ++@kindex TAB ++@item @key{TAB} ++@kindex C-c TAB ++@itemx C-c @key{TAB} ++Jump to the next field in the current record (@code{forms-next-field}). ++With a numeric argument @var{n}, jump forward @var{n} fields. If this command ++would move past the last field, it wraps around to the first field. ++ ++@findex forms-toggle-read-only ++@kindex C-c C-q ++@item C-c C-q ++Toggles read-only mode (@code{forms-toggle-read-only}). In read-only ++Forms mode, you cannot edit the fields; most Forms mode commands can be ++accessed without the prefix @kbd{C-c} if you use the normal letter ++instead (for example, type @kbd{n} instead of @kbd{C-c C-n}). In edit ++mode, you can edit the fields and thus change the contents of the data ++base; you must begin Forms mode commands with @code{C-c}. Switching ++to edit mode is allowed only if you have write access to the data file. ++ ++@findex forms-insert-record ++@kindex C-c C-o ++@item C-c C-o ++Create a new record and insert it before the current record ++(@code{forms-insert-record}). It starts out with empty (or default) ++contents for its fields; you can then edit the fields. With a numeric ++argument, the new record is created @emph{after} the current one. ++See also @code{forms-modified-record-filter} in @ref{Modifying Forms ++Contents}. ++ ++@findex forms-delete-record ++@kindex C-c C-k ++@item C-c C-k ++Delete the current record (@code{forms-delete-record}). You are ++prompted for confirmation before the record is deleted unless a numeric ++argument has been provided. ++ ++@findex forms-search-forward ++@kindex C-c C-s @var{regexp} @key{RET} ++@item C-c C-s @var{regexp} @key{RET} ++Search forward for @var{regexp} in all records following this one ++(@code{forms-search-forward}). If found, this record is shown. ++If you give an empty argument, the previous regexp is used again. ++ ++@findex forms-search-backward ++@kindex C-c C-r @var{regexp} @key{RET} ++@item C-c C-r @var{regexp} @key{RET} ++Search backward for @var{regexp} in all records following this one ++(@code{forms-search-backward}). If found, this record is shown. ++If you give an empty argument, the previous regexp is used again. ++ ++@ignore ++@findex forms-exit ++@kindex C-c C-x ++@item C-c C-x ++Terminate Forms mode processing (@code{forms-exit}). The data file is ++saved if it has been modified. ++ ++@findex forms-exit-no-save ++@item M-x forms-exit-no-save ++Terminates forms mode processing without saving modified data first. ++@end ignore ++ ++@findex forms-prev-field ++@item M-x forms-prev-field ++Similar to @code{forms-next-field} but moves backwards. ++ ++@findex forms-save-buffer ++@item M-x forms-save-buffer ++@kindex C-x C-s ++@itemx C-x C-s ++Forms mode replacement for @code{save-buffer}. When executed in the ++forms buffer it will save the contents of the (modified) data buffer ++instead. In Forms mode this function will be bound to @kbd{C-x C-s}. ++ ++@findex forms-print ++@item M-x forms-print ++This command can be used to make a formatted print ++of the contents of the data file. ++ ++@end table ++ ++In addition the command @kbd{M-x revert-buffer} is useful in Forms mode ++just as in other modes. ++ ++@ignore ++@vindex forms-forms-scroll ++@findex scroll-up ++@findex scroll-down ++If the variable @code{forms-forms-scrolls} is set to a value other ++than @code{nil} (which it is, by default), the Emacs functions ++@code{scroll-up} and @code{scroll-down} will perform a ++@code{forms-next-record} and @code{forms-prev-record} when in forms ++mode. So you can use your favorite page commands to page through the ++data file. ++ ++@vindex forms-forms-jump ++@findex beginning-of-buffer ++@findex end-of-buffer ++Likewise, if the variable @code{forms-forms-jump} is not @code{nil} ++(which it is, by default), Emacs functions @code{beginning-of-buffer} ++and @code{end-of-buffer} will perform @code{forms-first-record} and ++@code{forms-last-record} when in forms mode. ++@end ignore ++ ++The following function key definitions are set up in Forms mode ++(whether read-only or not): ++ ++@table @kbd ++@kindex next ++@item next ++forms-next-record ++ ++@kindex prior ++@item prior ++forms-prev-record ++ ++@kindex begin ++@item begin ++forms-first-record ++ ++@kindex end ++@item end ++forms-last-record ++ ++@kindex S-Tab ++@findex forms-prev-field ++@item S-Tab ++forms-prev-field ++@end table ++ ++@node Data File Format ++@chapter Data File Format ++ ++@cindex record ++@cindex field ++@vindex forms-field-sep ++Files for use with Forms mode are very simple---each @dfn{record} ++(usually one line) forms the contents of one form. Each record consists ++of a number of @dfn{fields}, which are separated by the value of the ++string @code{forms-field-sep}, which is @code{"\t"} (a Tab) by default. ++ ++@vindex forms-read-file-filter ++@vindex forms-write-file-filter ++If the format of the data file is not suitable enough you can define the ++filter functions @code{forms-read-file-filter} and ++@code{forms-write-file-filter}. @code{forms-read-file-filter} is called ++when the data file is read from disk into the data buffer. It operates ++on the data buffer, ignoring read-only protections. When the data file ++is saved to disk @code{forms-write-file-filter} is called to cancel the ++effects of @code{forms-read-file-filter}. After being saved, ++@code{forms-read-file-filter} is called again to prepare the data buffer ++for further processing. ++ ++@cindex pseudo-newline ++@vindex forms-multi-line ++Fields may contain text which shows up in the forms in multiple lines. ++These lines are separated in the field using a ``pseudo-newline'' ++character which is defined by the value of the string ++@code{forms-multi-line}. Its default value is @code{"\^k"} (a Control-K ++character). If it is ++set to @code{nil}, multiple line fields are prohibited. ++ ++If the data file does not exist, it is automatically created. ++ ++@node Control File Format ++@chapter Control File Format ++ ++@cindex control file ++The Forms mode @dfn{control file} serves two purposes. First, it names ++the data file to use, and defines its format and properties. Second, ++the Emacs buffer it occupies is used by Forms mode to display the forms. ++ ++The contents of the control file are evaluated as a Lisp program. It ++should set the following Lisp variables to suitable values: ++ ++@table @code ++@vindex forms-file ++@item forms-file ++This variable specifies the name of the data file. Example: ++ ++@example ++(setq forms-file "my/data-file") ++@end example ++ ++If the control file doesn't set @code{forms-file}, Forms mode ++reports an error. ++ ++@vindex forms-format-list ++@item forms-format-list ++This variable describes the way the fields of the record are formatted on ++the screen. For details, see @ref{Format Description}. ++ ++@vindex forms-number-of-fields ++@item forms-number-of-fields ++This variable holds the number of fields in each record of the data ++file. Example: ++ ++@example ++(setq forms-number-of-fields 10) ++@end example ++@end table ++ ++If the control file does not set @code{forms-format-list} a default ++format is used. In this situation, Forms mode will deduce the number of ++fields from the data file providing this file exists and ++@code{forms-number-of-records} has not been set in the control file. ++ ++The control file can optionally set the following additional Forms mode ++variables. Most of them have default values that are good for most ++applications. ++ ++@table @code ++@vindex forms-field-sep ++@item forms-field-sep ++This variable may be used to designate the string which separates the ++fields in the records of the data file. If not set, it defaults to the ++string @code{"\t"} (a Tab character). Example: ++ ++@example ++(setq forms-field-sep "\t") ++@end example ++ ++@vindex forms-read-only ++@item forms-read-only ++If the value is non-@code{nil}, the data file is treated read-only. (Forms ++mode also treats the data file as read-only if you don't have access to ++write it.) Example: ++ ++@example ++(set forms-read-only t) ++@end example ++ ++@vindex forms-multi-line ++@item forms-multi-line ++This variable specifies the @dfn{pseudo newline} separator that allows ++multi-line fields. This separator goes between the ``lines'' within a ++field---thus, the field doesn't really contain multiple lines, but it ++appears that way when displayed in Forms mode. If the value is ++@code{nil}, multi-line text fields are prohibited. The pseudo newline ++must not be a character contained in @code{forms-field-sep}. ++ ++The default value is @code{"\^k"}, the character Control-K. Example: ++ ++@example ++(setq forms-multi-line "\^k") ++@end example ++ ++@ignore ++@vindex forms-forms-scroll ++@item forms-forms-scroll ++@xref{Forms Mode Commands}, for details. ++ ++@vindex forms-forms-jump ++@item forms-forms-jump ++@xref{Forms Mode Commands}, for details. ++@end ignore ++ ++@findex forms-read-file-filter ++@item forms-read-file-filter ++This variable holds the name of a function to be called after the data ++file has been read in. This can be used to transform the contents of the ++data file into a format more suitable for forms processing. ++If it is @code{nil}, no function is called. For example, to maintain a ++gzipped database: ++ ++@example ++(defun gzip-read-file-filter () ++ (shell-command-on-region (point-min) (point-max) ++ "gzip -d" t t)) ++(setq forms-read-file-filter 'gzip-read-file-filter) ++@end example ++ ++@findex forms-write-file-filter ++@item forms-write-file-filter ++This variable holds the name of a function to be called before writing ++out the contents of the data file. ++This can be used to undo the effects of @code{forms-read-file-filter}. ++If it is @code{nil}, no function is called. Example: ++ ++@example ++(defun gzip-write-file-filter () ++ (make-variable-buffer-local 'require-final-newline) ++ (setq require-final-newline nil) ++ (shell-command-on-region (point-min) (point-max) ++ "gzip" t t)) ++(setq forms-write-file-filter 'gzip-write-file-filter) ++@end example ++ ++@findex forms-new-record-filter ++@item forms-new-record-filter ++This variable holds a function to be called whenever a new record is created ++to supply default values for fields. If it is @code{nil}, no function is ++called. ++@xref{Modifying Forms Contents}, for details. ++ ++@findex forms-modified-record-filter ++@item forms-modified-record-filter ++This variable holds a function to be called whenever a record is ++modified, just before updating the Forms data file. If it is ++@code{nil}, no function is called. ++@xref{Modifying Forms Contents}, for details. ++ ++@findex forms-insert-after ++@item forms-insert-after ++If this variable is not @code{nil}, new records are created @emph{after} the ++current record. Also, upon visiting a file, the initial position will be ++at the last record instead of the first one. ++ ++@findex forms-check-number-of-fields ++@item forms-check-number-of-fields ++Normally each record is checked to contain the correct number of fields. ++Under certain circumstances, this can be undesirable. ++If this variable is set to @code{nil}, these checks will be bypassed. ++@end table ++ ++@node Format Description ++@chapter The Format Description ++ ++@vindex forms-format-list ++ The variable @code{forms-format-list} specifies the format of the data ++in the data file, and how to convert the data for display in Forms mode. ++Its value must be a list of Forms mode @dfn{formatting elements}, each ++of which can be a string, a number, a Lisp list, or a Lisp symbol that ++evaluates to one of those. The formatting elements are processed in the ++order they appear in the list. ++ ++@table @var ++@item string ++A string formatting element is inserted in the forms ``as is,'' as text ++that the user cannot alter. ++ ++@item number ++A number element selects a field of the record. The contents of this ++field are inserted in the display at this point. Field numbers count ++starting from 1 (one). ++ ++@item list ++A formatting element that is a list specifies a function call. This ++function is called every time a record is displayed, and its result, ++which must be a string, is inserted in the display text. The function ++should do nothing but returning a string. ++ ++@vindex forms-fields ++The function you call can access the fields of the record as a list in ++the variable ++@code{forms-fields}. ++ ++@item symbol ++A symbol used as a formatting element should evaluate to a string, number, ++or list; the value is interpreted as a formatting element, as described ++above. ++@end table ++ ++If a record does not contain the number of fields as specified in ++@code{forms-number-of-fields}, a warning message will be printed. Excess ++fields are ignored, missing fields are set to empty. ++ ++The control file which displays @file{/etc/passwd} file as demonstrated ++in the beginning of this manual might look as follows: ++ ++@example ++;; @r{This demo visits @file{/etc/passwd}.} ++ ++(setq forms-file "/etc/passwd") ++(setq forms-number-of-fields 7) ++(setq forms-read-only t) ; @r{to make sure} ++(setq forms-field-sep ":") ++;; @r{Don't allow multi-line fields.} ++(setq forms-multi-line nil) ++ ++(setq forms-format-list ++ (list ++ "====== /etc/passwd ======\n\n" ++ "User : " 1 ++ " Uid: " 3 ++ " Gid: " 4 ++ "\n\n" ++ "Name : " 5 ++ "\n\n" ++ "Home : " 6 ++ "\n\n" ++ "Shell: " 7 ++ "\n")) ++@end example ++ ++When you construct the value of @code{forms-format-list}, you should ++usually either quote the whole value, like this, ++ ++@example ++(setq forms-format-list ++ '( ++ "====== " forms-file " ======\n\n" ++ "User : " 1 ++ (make-string 20 ?-) ++ @dots{} ++ )) ++@end example ++ ++@noindent ++or quote the elements which are lists, like this: ++ ++@example ++(setq forms-format-list ++ (list ++ "====== " forms-file " ======\n\n" ++ "User : " 1 ++ '(make-string 20 ?-) ++ @dots{} ++ )) ++@end example ++ ++Forms mode validates the contents of @code{forms-format-list} when you ++visit a database. If there are errors, processing is aborted with an ++error message which includes a descriptive text. @xref{Error Messages}, ++for a detailed list of error messages. ++ ++If no @code{forms-format-list} is specified, Forms mode will supply a ++default format list. This list contains the name of the file being ++visited, and a simple label for each field indicating the field number. ++ ++@node Modifying Forms Contents ++@chapter Modifying The Forms Contents ++ ++If @code{forms-read-only} is @code{nil}, the user can modify the fields ++and records of the database. ++ ++All normal editing commands are available for editing the contents of the ++displayed record. You cannot delete or modify the fixed, explanatory ++text that comes from string formatting elements, but you can modify the ++actual field contents. ++ ++@ignore ++@c This is for the Emacs 18 version only. ++If the contents of the forms cannot be recognized properly, this is ++signaled using a descriptive text. @xref{Error Messages}, for more info. ++The cursor will indicate the last part of the forms which was ++successfully parsed. It's important to avoid entering field contents ++that would cause confusion with the field-separating fixed text. ++@end ignore ++ ++If the variable @code{forms-modified-record-filter} is non-@code{nil}, ++it is called as a function before the new data is written to the data ++file. The function receives one argument, a vector that contains the ++contents of the fields of the record. ++ ++The function can refer to fields with @code{aref} and modify them with ++@code{aset}. The first field has number 1 (one); thus, element 0 of the ++vector is not used. The function should return the same vector it was ++passed; the (possibly modified) contents of the vector determine what is ++actually written in the file. Here is an example: ++ ++@example ++(defun my-modified-record-filter (record) ++ ;; @r{Modify second field.} ++ (aset record 2 (current-time-string)) ++ ;; @r{Return the field vector.} ++ record) ++ ++(setq forms-modified-record-filter 'my-modified-record-filter) ++@end example ++ ++If the variable @code{forms-new-record-filter} is non-@code{nil}, its ++value is a function to be called to fill in default values for the ++fields of a new record. The function is passed a vector of empty ++strings, one for each field; it should return the same vector, with ++the desired field values stored in it. Fields are numbered starting ++from 1 (one). Example: ++ ++@example ++(defun my-new-record-filter (fields) ++ (aset fields 5 (login-name)) ++ (aset fields 1 (current-time-string)) ++ fields) ++ ++(setq forms-new-record-filter 'my-new-record-filter) ++@end example ++ ++@node Miscellaneous ++@chapter Miscellaneous ++ ++@vindex forms-version ++The global variable @code{forms-version} holds the version information ++of the Forms mode software. ++ ++@findex forms-enumerate ++It is very convenient to use symbolic names for the fields in a record. ++The function @code{forms-enumerate} provides an elegant means to define ++a series of variables whose values are consecutive integers. The ++function returns the highest number used, so it can be used to set ++@code{forms-number-of-fields} also. For example: ++ ++@example ++(setq forms-number-of-fields ++ (forms-enumerate ++ '(field1 field2 field3 @dots{}))) ++@end example ++ ++This sets @code{field1} to 1, @code{field2} to 2, and so on. ++ ++Care has been taken to keep the Forms mode variables buffer-local, so it ++is possible to visit multiple files in Forms mode simultaneously, even ++if they have different properties. ++ ++@findex forms-mode ++If you have visited the control file in normal fashion with ++@code{find-file} or a like command, you can switch to Forms mode with ++the command @code{M-x forms-mode}. If you put @samp{-*- forms -*-} in ++the first line of the control file, then visiting it enables Forms mode ++automatically. But this makes it hard to edit the control file itself, ++so you'd better think twice before using this. ++ ++The default format for the data file, using @code{"\t"} to separate ++fields and @code{"\^k"} to separate lines within a field, matches the ++file format of some popular database programs, e.g. FileMaker. So ++@code{forms-mode} can decrease the need to use proprietary software. ++ ++@node Error Messages ++@chapter Error Messages ++ ++This section describes all error messages which can be generated by ++forms mode. Error messages that result from parsing the control file ++all start with the text @samp{Forms control file error}. Messages ++generated while analyzing the definition of @code{forms-format-list} ++start with @samp{Forms format error}. ++ ++@table @code ++@item Forms control file error: `forms-file' has not been set ++The variable @code{forms-file} was not set by the control file. ++ ++@item Forms control file error: `forms-number-of-fields' has not been set ++The variable @code{forms-number-of-fields} was not set by the control ++file. ++ ++@item Forms control file error: `forms-number-of-fields' must be a number > 0 ++The variable @code{forms-number-of-fields} did not contain a positive ++number. ++ ++@item Forms control file error: `forms-field-sep' is not a string ++@itemx Forms control file error: `forms-multi-line' must be nil or a one-character string ++The variable @code{forms-multi-line} was set to something other than ++@code{nil} or a single-character string. ++ ++@item Forms control file error: `forms-multi-line' is equal to 'forms-field-sep' ++The variable @code{forms-multi-line} may not be equal to ++@code{forms-field-sep} for this would make it impossible to distinguish ++fields and the lines in the fields. ++ ++@item Forms control file error: `forms-new-record-filter' is not a function ++@itemx Forms control file error: `forms-modified-record-filter' is not a function ++The variable has been set to something else than a function. ++ ++@item Forms control file error: `forms-format-list' is not a list ++The variable @code{forms-format-list} was not set to a Lisp list ++by the control file. ++ ++@item Forms format error: field number @var{xx} out of range 1..@var{nn} ++A field number was supplied in @code{forms-format-list} with a value of ++@var{xx}, which was not greater than zero and smaller than or equal to ++the number of fields in the forms, @var{nn}. ++ ++@item Forms format error: @var{fun} is not a function ++The first element of a list which is an element of ++@code{forms-format-list} was not a valid Lisp function. ++ ++@item Forms format error: invalid element @var{xx} ++A list element was supplied in @code{forms-format-list} which was not a ++string, number or list. ++ ++@ignore ++@c This applies to Emacs 18 only. ++@c Error messages generated while a modified form is being analyzed. ++ ++@item Parse error: not looking at `...' ++When re-parsing the contents of a forms, the text shown could not ++be found. ++ ++@item Parse error: cannot find `...' ++When re-parsing the contents of a forms, the text shown, which ++separates two fields, could not be found. ++ ++@item Parse error: cannot parse adjacent fields @var{xx} and @var{yy} ++Fields @var{xx} and @var{yy} were not separated by text, so could not be ++parsed again. ++@end ignore ++ ++@item Warning: this record has @var{xx} fields instead of @var{yy} ++The number of fields in this record in the data file did not match ++@code{forms-number-of-fields}. Missing fields will be made empty. ++ ++@item Multi-line fields in this record - update refused! ++The current record contains newline characters, hence can not be written ++back to the data file, for it would corrupt it. Probably you inserted a ++newline in a field, while @code{forms-multi-line} was @code{nil}. ++ ++@item Field separator occurs in record - update refused! ++The current record contains the field separator string inside one of the ++fields. It can not be written back to the data file, for it would ++corrupt it. Probably you inserted the field separator string in a field. ++ ++@item Record number @var{xx} out of range 1..@var{yy} ++A jump was made to non-existing record @var{xx}. @var{yy} denotes the ++number of records in the file. ++ ++@item Stuck at record @var{xx} ++An internal error prevented a specific record from being retrieved. ++ ++@item No write access to @code{"}@var{file}@code{"} ++An attempt was made to enable edit mode on a file that has been write ++protected. ++ ++@item Search failed: @var{regexp} ++The @var{regexp} could not be found in the data file. Forward searching ++is done from the current location until the end of the file, then ++retrying from the beginning of the file until the current location. ++Backward searching is done from the current location until the beginning ++of the file, then retrying from the end of the file until the current ++location. ++ ++@item Wrapped ++A search completed successfully after wrapping around. ++ ++@item Warning: number of records changed to @var{nn} ++Forms mode's idea of the number of records has been adjusted to the ++number of records actually present in the data file. ++ ++@item Problem saving buffers? ++An error occurred while saving the data file buffer. Most likely, Emacs ++did ask to confirm deleting the buffer because it had been modified, and ++you said `no'. ++@end table ++ ++@node Long Example ++@chapter Long Example ++ ++The following example exploits most of the features of Forms mode. ++This example is included in the distribution as file @file{forms-d2.el}. ++ ++@example ++;; demo2 -- demo forms-mode -*- emacs-lisp -*- ++ ++;; @r{This sample forms exploit most of the features of forms mode.} ++ ++;; @r{Set the name of the data file.} ++(setq forms-file "forms-d2.dat") ++ ++;; @r{Use @code{forms-enumerate} to set field names and number thereof.} ++(setq forms-number-of-fields ++ (forms-enumerate ++ '(arch-newsgroup ; 1 ++ arch-volume ; 2 ++ arch-issue ; and ... ++ arch-article ; ... so ++ arch-shortname ; ... ... on ++ arch-parts ++ arch-from ++ arch-longname ++ arch-keywords ++ arch-date ++ arch-remarks))) ++ ++;; @r{The following functions are used by this form for layout purposes.} ++;; ++(defun arch-tocol (target &optional fill) ++ "Produces a string to skip to column TARGET. ++Prepends newline if needed. ++The optional FILL should be a character, used to fill to the column." ++ (if (null fill) ++ (setq fill ? )) ++ (if (< target (current-column)) ++ (concat "\n" (make-string target fill)) ++ (make-string (- target (current-column)) fill))) ++;; ++(defun arch-rj (target field &optional fill) ++ "Produces a string to skip to column TARGET\ ++ minus the width of field FIELD. ++Prepends newline if needed. ++The optional FILL should be a character, ++used to fill to the column." ++ (arch-tocol (- target (length (nth field forms-fields))) fill)) ++ ++;; @r{Record filters.} ++;; ++(defun new-record-filter (the-record) ++ "Form a new record with some defaults." ++ (aset the-record arch-from (user-full-name)) ++ (aset the-record arch-date (current-time-string)) ++ the-record) ; return it ++(setq forms-new-record-filter 'new-record-filter) ++ ++;; @r{The format list.} ++(setq forms-format-list ++ (list ++ "====== Public Domain Software Archive ======\n\n" ++ arch-shortname ++ " - " arch-longname ++ "\n\n" ++ "Article: " arch-newsgroup ++ "/" arch-article ++ " " ++ '(arch-tocol 40) ++ "Issue: " arch-issue ++ " " ++ '(arch-rj 73 10) ++ "Date: " arch-date ++ "\n\n" ++ "Submitted by: " arch-from ++ "\n" ++ '(arch-tocol 79 ?-) ++ "\n" ++ "Keywords: " arch-keywords ++ "\n\n" ++ "Parts: " arch-parts ++ "\n\n====== Remarks ======\n\n" ++ arch-remarks ++ )) ++ ++;; @r{That's all, folks!} ++@end example ++ ++@node Credits ++@chapter Credits ++ ++Bug fixes and other useful suggestions were supplied by ++Harald Hanche-Olsen (@code{hanche@@imf.unit.no}), ++@code{cwitty@@portia.stanford.edu}, ++Jonathan I. Kamens, ++Per Cederqvist (@code{ceder@@signum.se}), ++Michael Lipka (@code{lipka@@lip.hanse.de}), ++Andy Piper (@code{ajp@@eng.cam.ac.uk}), ++Frederic Pierresteguy (@code{F.Pierresteguy@@frcl.bull.fr}), ++Ignatios Souvatzis ++and Richard Stallman (@code{rms@@gnu.org}). ++ ++This documentation was slightly inspired by the documentation of ``rolo ++mode'' by Paul Davis at Schlumberger Cambridge Research ++(@code{davis%scrsu1%sdr.slb.com@@relay.cs.net}). ++ ++None of this would have been possible without GNU Emacs of the Free ++Software Foundation. Thanks, Richard! ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index ++@unnumbered Index ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 2ac9810b-aa49-4ea6-8030-d7f1ecd467ed ++@end ignore +diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi +new file mode 100644 +index 0000000..a384e8b +--- /dev/null ++++ b/doc/misc/gnus-coding.texi +@@ -0,0 +1,387 @@ ++\input texinfo ++ ++@setfilename gnus-coding ++@settitle Gnus Coding Style and Maintainance Guide ++@syncodeindex fn cp ++@syncodeindex vr cp ++@syncodeindex pg cp ++ ++@copying ++Copyright @copyright{} 2004, 2005, 2007, 2008, 2009 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 Gnus 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.'' ++ ++This document is part of a collection distributed under the GNU Free ++Documentation License. If you want to distribute this document ++separately from the collection, you can do so by adding a copy of the ++license to the document, as described in section 6 of the license. ++@end quotation ++@end copying ++ ++ ++@titlepage ++@title Gnus Coding Style and Maintainance Guide ++ ++@author by Reiner Steib ++ ++@insertcopying ++@end titlepage ++ ++@c Obviously this is only a very rudimentary draft. We put it in CVS ++@c anyway hoping that it might annoy someone enough to fix it. ;-) ++@c Fixing only a paragraph also is appreciated. ++ ++@ifnottex ++@node Top ++@top Gnus Coding Style and Maintainance Guide ++This manual describes @dots{} ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* Gnus Coding Style:: Gnus Coding Style ++* Gnus Maintainance Guide:: Gnus Maintainance Guide ++@end menu ++ ++@c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader} ++ ++@node Gnus Coding Style ++@chapter Gnus Coding Style ++@section Dependencies ++ ++The Gnus distribution contains a lot of libraries that have been written ++for Gnus and used intensively for Gnus. But many of those libraries are ++useful on their own. E.g. other Emacs Lisp packages might use the ++@acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME ++Manual}. ++ ++@subsection General purpose libraries ++ ++@table @file ++ ++@item netrc.el ++@file{.netrc} parsing functionality. ++@c As of 2005-10-21... ++There are no Gnus dependencies in this file. ++ ++@item format-spec.el ++Functions for formatting arbitrary formatting strings. ++@c As of 2005-10-21... ++There are no Gnus dependencies in this file. ++ ++@item hex-util.el ++Functions to encode/decode hexadecimal string. ++@c As of 2007-08-25... ++There are no Gnus dependencies in these files. ++@end table ++ ++@subsection Encryption and security ++ ++@table @file ++@item encrypt.el ++File encryption routines ++@c As of 2005-10-25... ++There are no Gnus dependencies in this file. ++ ++@item password.el ++Read passwords from user, possibly using a password cache. ++@c As of 2005-10-21... ++There are no Gnus dependencies in this file. ++ ++@item tls.el ++TLS/SSL support via wrapper around GnuTLS ++@c As of 2005-10-21... ++There are no Gnus dependencies in this file. ++ ++@item pgg*.el ++Glue for the various PGP implementations. ++@c As of 2005-10-21... ++There are no Gnus dependencies in these files. ++ ++@item sha1.el ++SHA1 Secure Hash Algorithm. ++@c As of 2007-08-25... ++There are no Gnus dependencies in these files. ++@end table ++ ++@subsection Networking ++ ++@table @file ++@item dig.el ++Domain Name System dig interface. ++@c As of 2005-10-21... ++There are no serious Gnus dependencies in this file. Uses ++@code{gnus-run-mode-hooks} (a wrapper function). ++ ++@item dns.el, dns-mode.el ++Domain Name Service lookups. ++@c As of 2005-10-21... ++There are no Gnus dependencies in these files. ++@end table ++ ++@subsection Mail and News related RFCs ++ ++@table @file ++@item pop3.el ++Post Office Protocol (RFC 1460) interface. ++@c As of 2005-10-21... ++There are no Gnus dependencies in this file. ++ ++@item imap.el ++@acronym{IMAP} library. ++@c As of 2005-10-21... ++There are no Gnus dependencies in this file. ++ ++@item ietf-drums.el ++Functions for parsing RFC822bis headers. ++@c As of 2005-10-21... ++There are no Gnus dependencies in this file. ++ ++@item rfc1843.el ++HZ (rfc1843) decoding. HZ is a data format for exchanging files of ++arbitrarily mixed Chinese and @acronym{ASCII} characters. ++@c As of 2005-10-21... ++@code{rfc1843-gnus-setup} seem to be useful only for Gnus. Maybe this ++function should be relocated to remove dependencies on Gnus. Other ++minor dependencies: @code{gnus-newsgroup-name} could be eliminated by ++using an optional argument to @code{rfc1843-decode-article-body}. ++ ++@item rfc2045.el ++Functions for decoding rfc2045 headers ++@c As of 2007-08-25... ++There are no Gnus dependencies in these files. ++ ++@item rfc2047.el ++Functions for encoding and decoding rfc2047 messages ++@c As of 2007-08-25... ++There are no Gnus dependencies in these files. ++@c ++Only a couple of tests for gnusy symbols. ++ ++@item rfc2104.el ++RFC2104 Hashed Message Authentication Codes ++@c As of 2007-08-25... ++There are no Gnus dependencies in these files. ++ ++@item rfc2231.el ++Functions for decoding rfc2231 headers ++@c As of 2007-08-25... ++There are no Gnus dependencies in these files. ++ ++@item flow-fill.el ++Interpret RFC2646 "flowed" text. ++@c As of 2005-10-27... ++There are no Gnus dependencies in this file. ++ ++@item uudecode.el ++Elisp native uudecode. ++@c As of 2005-12-06... ++There are no Gnus dependencies in this file. ++@c ... but the custom group is gnus-extract. ++ ++@item canlock.el ++Functions for Cancel-Lock feature ++@c Cf. draft-ietf-usefor-cancel-lock-01.txt ++@c Although this draft has expired, Canlock-Lock revived in 2007 when ++@c major news providers (e.g. news.individual.org) started to use it. ++@c As of 2007-08-25... ++There are no Gnus dependencies in these files. ++ ++@end table ++ ++@subsection message ++ ++All message composition from Gnus (both mail and news) takes place in ++Message mode buffers. Message mode is intended to be a replacement for ++Emacs mail mode. There should be no Gnus dependencies in ++@file{message.el}. Alas it is not anymore. Patches and suggestions to ++remove the dependencies are welcome. ++ ++@c message.el requires nnheader which requires gnus-util. ++ ++@subsection Emacs @acronym{MIME} ++ ++The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME} ++functionality for Emacs. ++ ++@acronym{MML} (@acronym{MIME} Meta Language) is supposed to be ++independent from Gnus. Alas it is not anymore. Patches and suggestions ++to remove the dependencies are welcome. ++ ++@subsection Gnus backends ++ ++The files @file{nn*.el} provide functionality for accessing NNTP ++(@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back ++ends (probably @file{nnml.el}, @file{nnfolder.el} and ++@file{nnmaildir.el} are the most widely used mail back ends). ++ ++@c mm-uu requires nnheader which requires gnus-util. message.el also ++@c requires nnheader. ++ ++ ++@section Compatibility ++ ++No Gnus and Gnus 5.10.10 and up should work on: ++@itemize @bullet ++@item ++Emacs 21.1 and up. ++@item ++XEmacs 21.4 and up. ++@end itemize ++ ++Gnus 5.10.8 and below should work on: ++@itemize @bullet ++@item ++Emacs 20.7 and up. ++@item ++XEmacs 21.1 and up. ++@end itemize ++ ++@node Gnus Maintainance Guide ++@chapter Gnus Maintainance Guide ++ ++@section Stable and development versions ++ ++The development of Gnus normally is done on the CVS trunk, i.e. there ++are no separate branches to develop and test new features. Most of the ++time, the trunk is developed quite actively with more or less daily ++changes. Only after a new major release, e.g. 5.10.1, there's usually a ++feature period of several months. After the release of Gnus 5.10.6 the ++development of new features started again on the trunk while the 5.10 ++series is continued on the stable branch (v5-10) from which more stable ++releases will be done when needed (5.10.8, @dots{}). ++@ref{Gnus Development, ,Gnus Development, gnus, The Gnus Newsreader} ++ ++Stable releases of Gnus finally become part of Emacs. E.g. Gnus 5.8 ++became a part of Emacs 21 (relabeled to Gnus 5.9). The 5.10 series ++became part of Emacs 22 as Gnus 5.11. ++ ++@section Syncing ++ ++@c Some MIDs related to this follow. Use http://thread.gmane.org/MID ++@c (and click on the subject) to get the thread on Gmane. ++ ++@c Some quotes from Miles Bader follow... ++ ++@c ++@c ++ ++In the past, the inclusion of Gnus into Emacs was quite cumbersome. For ++each change made to Gnus in Emacs repository, it had to be checked that ++it was applied to the new Gnus version, too. Else, bug fixes done in ++Emacs repository might have been lost. ++ ++With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus ++gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus ++CVS semi-automatically. These bug fixes are installed on the stable ++branch and on the trunk. Basically the idea is that the gateway will ++cause all common files in Emacs and Gnus v5-10 to be identical except ++when there's a very good reason (e.g., the Gnus version string in Emacs ++says @samp{5.11}, but the v5-10 version string remains @samp{5.10.x}). ++Furthermore, all changes in these files in either Emacs or the v5-10 ++branch will be installed into the Gnus CVS trunk, again except where ++there's a good reason. ++@c (typically so far the only exception has been that the changes ++@c already exist in the trunk in modified form). ++Because of this, when the next major version of Gnus will be included in ++Emacs, it should be very easy -- just plonk in the files from the Gnus ++trunk without worrying about lost changes from the Emacs tree. ++ ++The effect of this is that as hacker, you should generally only have to ++make changes in one place: ++ ++@itemize ++@item ++If it's a file which is thought of as being outside of Gnus (e.g., the ++new @file{encrypt.el}), you should probably make the change in the Emacs ++tree, and it will show up in the Gnus tree a few days later. ++ ++If you don't have Emacs CVS access (or it's inconvenient), you can ++change such a file in the v5-10 branch, and it should propagate to Emacs ++CVS -- however, it will get some extra scrutiny (by Miles) to see if the ++changes are possibly controversial and need discussion on the mailing ++list. Many changes are obvious bug-fixes however, so often there won't ++be any problem. ++ ++@item ++If it's to a Gnus file, and it's important enough that it should be part ++of Emacs and the v5-10 branch, then you can make the change on the v5-10 ++branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few days ++later). The most prominent examples for such changes are bug-fixed ++including improvements on the documentation. ++ ++If you know that there will be conflicts (perhaps because the affected ++source code is different in v5-10 and the Gnus CVS trunk), then you can ++install your change in both places, and when I try to sync them, there ++will be a conflict -- however, since in most such cases there would be a ++conflict @emph{anyway}, it's often easier for me to resolve it simply if ++I see two @samp{identical} changes, and can just choose the proper one, ++rather than having to actually fix the code. ++ ++@item ++For general Gnus development changes, of course you just make the ++change on the Gnus CVS trunk and it goes into Emacs a few years ++later... :-) ++@end itemize ++ ++Of course in any case, if you just can't wait for me to sync your ++change, you can commit it in more than one place and probably there will ++be no problem; usually the changes are textually identical anyway, so ++can be easily resolved automatically (sometimes I notice silly things in ++such multiple commits, like whitespace differences, and unify those ;-). ++ ++ ++@c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to ++@c require more manual work. ++ ++@c By default I sync about once a week. I also try to follow any Gnus ++@c threads on the mailing lists and make sure any changes being discussed ++@c are kept more up-to-date (so say 1-2 days delay for "topical" changes). ++ ++@c ++ ++@c BTW, just to add even more verbose explanation about the syncing thing: ++ ++@section Miscellanea ++ ++@heading @file{GNUS-NEWS} ++ ++Starting from No Gnus, the @file{GNUS-NEWS} is created from ++@file{texi/gnus-news.texi}. Don't edit @file{GNUS-NEWS}. Edit ++@file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the ++@file{texi} directory and commit @file{GNUS-NEWS} and ++@file{texi/gnus-news.texi}. ++ ++@heading Conventions for version information in defcustoms ++ ++For new customizable variables introduced in Oort Gnus (including the ++v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} (including the ++comment) or e.g. @code{:version "22.2" ;; Gnus 5.10.10} if the feature ++was added for Emacs 22.2 and Gnus 5.10.10. ++@c ++If the variable is new in No Gnus use @code{:version "23.1" ;; No Gnus}. ++ ++The same applies for customizable variables when its default value was ++changed. ++ ++@c Local Variables: ++@c mode: texinfo ++@c coding: iso-8859-1 ++@c End: ++ ++@ignore ++ arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931 ++@end ignore +diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi +new file mode 100644 +index 0000000..d374dfd +--- /dev/null ++++ b/doc/misc/gnus-faq.texi +@@ -0,0 +1,2337 @@ ++@c \input texinfo @c -*-texinfo-*- ++@c Uncomment 1st line before texing this file alone. ++@c %**start of header ++@c Copyright (C) 1995, 2001, 2002, 2003, 2004, 2005, 2006, 2007, ++@c 2008, 2009 Free Software Foundation, Inc. ++@c ++@c Do not modify this file, it was generated from gnus-faq.xml, available from ++@c . ++@c ++@setfilename gnus-faq.info ++@settitle Frequently Asked Questions ++@c %**end of header ++@c ++ ++@node Frequently Asked Questions ++@section Frequently Asked Questions ++ ++@menu ++* FAQ - Changes:: ++* FAQ - Introduction:: About Gnus and this FAQ. ++* FAQ 1 - Installation FAQ:: Installation of Gnus. ++* FAQ 2 - Startup / Group buffer:: Start up questions and the ++ first buffer Gnus shows you. ++* FAQ 3 - Getting Messages:: Making Gnus read your mail ++ and news. ++* FAQ 4 - Reading messages:: How to efficiently read ++ messages. ++* FAQ 5 - Composing messages:: Composing mails or Usenet ++ postings. ++* FAQ 6 - Old messages:: Importing, archiving, ++ searching and deleting messages. ++* FAQ 7 - Gnus in a dial-up environment:: Reading mail and news while ++ offline. ++* FAQ 8 - Getting help:: When this FAQ isn't enough. ++* FAQ 9 - Tuning Gnus:: How to make Gnus faster. ++* FAQ - Glossary:: Terms used in the FAQ ++ explained. ++@end menu ++ ++@subheading Abstract ++ ++This is the new Gnus Frequently Asked Questions list. ++If you have a Web browser, the official hypertext version is at ++@uref{http://my.gnus.org/FAQ/}, ++the Docbook source is available from ++@uref{http://sourceforge.net/projects/gnus/, http://sourceforge.net}. ++ ++Please submit features and suggestions to the ++@email{faq-discuss@@my.gnus.org, FAQ discussion list}. ++The list is protected against junk mail with ++@uref{http://smarden.org/qconfirm/index.html, qconfirm}. As ++a subscriber, your submissions will automatically pass. You can ++also subscribe to the list by sending a blank email to ++@email{faq-discuss-subscribe@@my.gnus.org, faq-discuss-subscribe@@my.gnus.org} ++and @uref{http://mail1.kens.com/cgi-bin/ezmlm-browse?command=monthbythread%26list=faq-discuss, browse ++the archive (BROKEN)}. ++ ++@node FAQ - Changes ++@subheading Changes ++ ++ ++ ++@itemize @bullet ++ ++@item ++2008-06-15: Adjust for message-fill-column. Add x-face-file. ++Clarify difference between ding and gnu.emacs.gnus. Remove ++reference to discontinued service. ++ ++@item ++2006-04-15: Added tip on how to delete sent buffer on exit. ++@end itemize ++ ++@node FAQ - Introduction ++@subheading Introduction ++ ++This is the Gnus Frequently Asked Questions list. ++ ++Gnus is a Usenet Newsreader and Electronic Mail User Agent implemented ++as a part of Emacs. It's been around in some form for almost a decade ++now, and has been distributed as a standard part of Emacs for much of ++that time. Gnus 5 is the latest (and greatest) incarnation. The ++original version was called GNUS, and was written by Masanobu UMEDA. ++When autumn crept up in '94, Lars Magne Ingebrigtsen grew bored and ++decided to rewrite Gnus. ++ ++Its biggest strength is the fact that it is extremely ++customizable. It is somewhat intimidating at first glance, but ++most of the complexity can be ignored until you're ready to take ++advantage of it. If you receive a reasonable volume of e-mail ++(you're on various mailing lists), or you would like to read ++high-volume mailing lists but cannot keep up with them, or read ++high volume newsgroups or are just bored, then Gnus is what you ++want. ++ ++This FAQ was maintained by Justin Sheehy until March 2002. He ++would like to thank Steve Baur and Per Abrahamsen for doing a wonderful ++job with this FAQ before him. We would like to do the same - thanks, ++Justin! ++ ++If you have a Web browser, the official hypertext version is at: ++@uref{http://my.gnus.org/FAQ/}. ++This version is much nicer than the unofficial hypertext ++versions that are archived at Utrecht, Oxford, Smart Pages, Ohio ++State, and other FAQ archives. See the resources question below ++if you want information on obtaining it in another format. ++ ++The information contained here was compiled with the assistance ++of the Gnus development mailing list, and any errors or ++misprints are the my.gnus.org team's fault, sorry. ++ ++@node FAQ 1 - Installation FAQ ++@subsection Installation FAQ ++ ++@menu ++* FAQ 1-1:: What is the latest version of Gnus? ++* FAQ 1-2:: What's new in 5.10? ++* FAQ 1-3:: Where and how to get Gnus? ++* FAQ 1-4:: What to do with the tarball now? ++* FAQ 1-5:: I sometimes read references to No Gnus and Oort Gnus, ++ what are those? ++* FAQ 1-6:: Which version of Emacs do I need? ++* FAQ 1-7:: How do I run Gnus on both Emacs and XEmacs? ++@end menu ++ ++@node FAQ 1-1 ++@subsubheading Question 1.1 ++ ++What is the latest version of Gnus? ++ ++@subsubheading Answer ++ ++Jingle please: Gnus 5.10 is released, get it while it's ++hot! As well as the step in version number is rather ++small, Gnus 5.10 has tons of new features which you ++shouldn't miss. The current release (5.13) should be at ++least as stable as the latest release of the 5.8 series. ++ ++@node FAQ 1-2 ++@subsubheading Question 1.2 ++ ++What's new in 5.10? ++ ++@subsubheading Answer ++ ++First of all, you should have a look into the file ++GNUS-NEWS in the toplevel directory of the Gnus tarball, ++there the most important changes are listed. Here's a ++short list of the changes I find especially ++important/interesting: ++ ++@itemize @bullet ++ ++@item ++Major rewrite of the Gnus agent, Gnus agent is now ++active by default. ++ ++@item ++Many new article washing functions for dealing with ++ugly formatted articles. ++ ++@item ++Anti Spam features. ++ ++@item ++Message-utils now included in Gnus. ++ ++@item ++New format specifiers for summary lines, e.g. %B for ++a complex trn-style thread tree. ++@end itemize ++ ++@node FAQ 1-3 ++@subsubheading Question 1.3 ++ ++Where and how to get Gnus? ++ ++@subsubheading Answer ++ ++Gnus is released independent from releases of Emacs and XEmacs. ++Therefore, the version bundled with Emacs or the version in XEmacs' ++package system might not be up to date (e.g. Gnus 5.9 bundled with Emacs ++21 is outdated). ++You can get the latest released version of Gnus from ++@uref{http://www.gnus.org/dist/gnus.tar.gz} ++or via anonymous FTP from ++@uref{ftp://ftp.gnus.org/pub/gnus/gnus.tar.gz}. ++ ++@node FAQ 1-4 ++@subsubheading Question 1.4 ++ ++What to do with the tarball now? ++ ++@subsubheading Answer ++ ++Untar it via @samp{tar xvzf gnus.tar.gz} and do the common ++@samp{./configure; make; make install} circle. ++(under MS-Windows either get the Cygwin environment from ++@uref{http://www.cygwin.com} ++which allows you to do what's described above or unpack the ++tarball with some packer (e.g. Winace from ++@uref{http://www.winace.com}) ++and use the batch-file make.bat included in the tarball to install ++Gnus.) If you don't want to (or aren't allowed to) install Gnus ++system-wide, you can install it in your home directory and add the ++following lines to your ~/.xemacs/init.el or ~/.emacs: ++ ++@example ++(add-to-list 'load-path "/path/to/gnus/lisp") ++(if (featurep 'xemacs) ++ (add-to-list 'Info-directory-list "/path/to/gnus/texi/") ++ (add-to-list 'Info-default-directory-list "/path/to/gnus/texi/")) ++@end example ++@noindent ++ ++Make sure that you don't have any Gnus related stuff ++before this line, on MS Windows use something like ++"C:/path/to/lisp" (yes, "/"). ++ ++@node FAQ 1-5 ++@subsubheading Question 1.5 ++ ++I sometimes read references to No Gnus and Oort Gnus, ++what are those? ++ ++@subsubheading Answer ++ ++Oort Gnus was the name of the development version of ++Gnus, which became Gnus 5.10 in autumn 2003. No Gnus is ++the name of the current development version which will ++once become Gnus 5.12 or Gnus 6. (If you're wondering why ++not 5.11, the odd version numbers are normally used for ++the Gnus versions bundled with Emacs) ++ ++@node FAQ 1-6 ++@subsubheading Question 1.6 ++ ++Which version of Emacs do I need? ++ ++@subsubheading Answer ++ ++Gnus 5.10 requires an Emacs version that is greater than or equal ++to Emacs 20.7 or XEmacs 21.1. ++The development versions of Gnus (aka No Gnus) requires Emacs 21 ++or XEmacs 21.4. ++ ++@node FAQ 1-7 ++@subsubheading Question 1.7 ++ ++How do I run Gnus on both Emacs and XEmacs? ++ ++@subsubheading Answer ++ ++You can't use the same copy of Gnus in both as the Lisp ++files are byte-compiled to a format which is different ++depending on which Emacs did the compilation. Get one copy ++of Gnus for Emacs and one for XEmacs. ++ ++@node FAQ 2 - Startup / Group buffer ++@subsection Startup / Group buffer ++ ++@menu ++* FAQ 2-1:: Every time I start Gnus I get a message "Gnus auto-save ++ file exists. Do you want to read it?", what does this mean and ++ how to prevent it? ++* FAQ 2-2:: Gnus doesn't remember which groups I'm subscribed to, ++ what's this? ++* FAQ 2-3:: How to change the format of the lines in Group buffer? ++* FAQ 2-4:: My group buffer becomes a bit crowded, is there a way to ++ sort my groups into categories so I can easier browse through ++ them? ++* FAQ 2-5:: How to manually sort the groups in Group buffer? How to ++ sort the groups in a topic? ++@end menu ++ ++@node FAQ 2-1 ++@subsubheading Question 2.1 ++ ++Every time I start Gnus I get a message "Gnus auto-save ++file exists. Do you want to read it?", what does this mean ++and how to prevent it? ++ ++@subsubheading Answer ++ ++This message means that the last time you used Gnus, it ++wasn't properly exited and therefor couldn't write its ++informations to disk (e.g. which messages you read), you ++are now asked if you want to restore those informations ++from the auto-save file. ++ ++To prevent this message make sure you exit Gnus ++via @samp{q} in group buffer instead of ++just killing Emacs. ++ ++@node FAQ 2-2 ++@subsubheading Question 2.2 ++ ++Gnus doesn't remember which groups I'm subscribed to, ++what's this? ++ ++@subsubheading Answer ++ ++You get the message described in the q/a pair above while ++starting Gnus, right? It's an other symptom for the same ++problem, so read the answer above. ++ ++@node FAQ 2-3 ++@subsubheading Question 2.3 ++ ++How to change the format of the lines in Group buffer? ++ ++@subsubheading Answer ++ ++You've got to tweak the value of the variable ++gnus-group-line-format. See the manual node "Group Line ++Specification" for information on how to do this. An ++example for this (guess from whose .gnus :-)): ++ ++@example ++(setq gnus-group-line-format "%P%M%S[%5t]%5y : %(%g%)\n") ++@end example ++@noindent ++ ++@node FAQ 2-4 ++@subsubheading Question 2.4 ++ ++My group buffer becomes a bit crowded, is there a way to ++sort my groups into categories so I can easier browse ++through them? ++ ++@subsubheading Answer ++ ++Gnus offers the topic mode, it allows you to sort your ++groups in, well, topics, e.g. all groups dealing with ++Linux under the topic linux, all dealing with music under ++the topic music and all dealing with scottish music under ++the topic scottish which is a subtopic of music. ++ ++To enter topic mode, just hit t while in Group buffer. Now ++you can use @samp{T n} to create a topic ++at point and @samp{T m} to move a group to ++a specific topic. For more commands see the manual or the ++menu. You might want to include the %P specifier at the ++beginning of your gnus-group-line-format variable to have ++the groups nicely indented. ++ ++@node FAQ 2-5 ++@subsubheading Question 2.5 ++ ++How to manually sort the groups in Group buffer? How to ++sort the groups in a topic? ++ ++@subsubheading Answer ++ ++Move point over the group you want to move and ++hit @samp{C-k}, now move point to the ++place where you want the group to be and ++hit @samp{C-y}. ++ ++@node FAQ 3 - Getting Messages ++@subsection Getting Messages ++ ++@menu ++* FAQ 3-1:: I just installed Gnus, started it via @samp{M-x gnus} ++ but it only says "nntp (news) open error", what to do? ++* FAQ 3-2:: I'm working under Windows and have no idea what ++ ~/.gnus.el means. ++* FAQ 3-3:: My news server requires authentication, how to store ++ user name and password on disk? ++* FAQ 3-4:: Gnus seems to start up OK, but I can't find out how to ++ subscribe to a group. ++* FAQ 3-5:: Gnus doesn't show all groups / Gnus says I'm not allowed ++ to post on this server as well as I am, what's that? ++* FAQ 3-6:: I want Gnus to fetch news from several servers, is this ++ possible? ++* FAQ 3-7:: And how about local spool files? ++* FAQ 3-8:: OK, reading news works now, but I want to be able to ++ read my mail with Gnus, too. How to do it? ++* FAQ 3-9:: And what about IMAP? ++* FAQ 3-10:: At the office we use one of those MS Exchange servers, ++ can I use Gnus to read my mail from it? ++* FAQ 3-11:: Can I tell Gnus not to delete the mails on the server it ++ retrieves via POP3? ++@end menu ++ ++@node FAQ 3-1 ++@subsubheading Question 3.1 ++ ++I just installed Gnus, started it via ++@samp{M-x gnus} ++but it only says "nntp (news) open error", what to do? ++ ++@subsubheading Answer ++ ++You've got to tell Gnus where to fetch the news from. Read ++the documentation for information on how to do this. As a ++first start, put those lines in ~/.gnus.el: ++ ++@example ++(setq gnus-select-method '(nntp "news.yourprovider.net")) ++(setq user-mail-address "you@@yourprovider.net") ++(setq user-full-name "Your Name") ++@end example ++@noindent ++ ++@node FAQ 3-2 ++@subsubheading Question 3.2 ++ ++I'm working under Windows and have no idea what ~/.gnus.el means. ++ ++@subsubheading Answer ++ ++The ~/ means the home directory where Gnus and Emacs look ++for the configuration files. However, you don't really ++need to know what this means, it suffices that Emacs knows ++what it means :-) You can type ++@samp{C-x C-f ~/.gnus.el RET } ++(yes, with the forward slash, even on Windows), and ++Emacs will open the right file for you. (It will most ++likely be new, and thus empty.) ++However, I'd discourage you from doing so, since the ++directory Emacs chooses will most certainly not be what ++you want, so let's do it the correct way. ++The first thing you've got to do is to ++create a suitable directory (no blanks in directory name ++please) e.g. c:\myhome. Then you must set the environment ++variable HOME to this directory. To do this under Win9x ++or Me include the line ++ ++@example ++SET HOME=C:\myhome ++@end example ++@noindent ++ ++in your autoexec.bat and reboot. Under NT, 2000 and XP, hit ++Winkey+Pause/Break to enter system options (if it doesn't work, go ++to Control Panel -> System -> Advanced). There you'll find the ++possibility to set environment variables. Create a new one with ++name HOME and value C:\myhome. Rebooting is not necessary. ++ ++Now to create ~/.gnus.el, say ++@samp{C-x C-f ~/.gnus.el RET C-x C-s}. ++in Emacs. ++ ++@node FAQ 3-3 ++@subsubheading Question 3.3 ++ ++My news server requires authentication, how to store ++user name and password on disk? ++ ++@subsubheading Answer ++ ++Create a file ~/.authinfo which includes for each server a line like this ++ ++@example ++machine news.yourprovider.net login YourUserName password YourPassword ++@end example ++@noindent ++. ++Make sure that the file isn't readable to others if you ++work on a OS which is capable of doing so. (Under Unix ++say ++@example ++chmod 600 ~/.authinfo ++@end example ++@noindent ++ ++in a shell.) ++ ++@node FAQ 3-4 ++@subsubheading Question 3.4 ++ ++Gnus seems to start up OK, but I can't find out how to ++subscribe to a group. ++ ++@subsubheading Answer ++ ++If you know the name of the group say @samp{U ++name.of.group RET} in group buffer (use the ++tab-completion Luke). Otherwise hit ^ in group buffer, ++this brings you to the server buffer. Now place point (the ++cursor) over the server which carries the group you want, ++hit @samp{RET}, move point to the group ++you want to subscribe to and say @samp{u} ++to subscribe to it. ++ ++@node FAQ 3-5 ++@subsubheading Question 3.5 ++ ++Gnus doesn't show all groups / Gnus says I'm not allowed to ++post on this server as well as I am, what's that? ++ ++@subsubheading Answer ++ ++Some providers allow restricted anonymous access and full ++access only after authorization. To make Gnus send authinfo ++to those servers append ++ ++@example ++force yes ++@end example ++@noindent ++ ++to the line for those servers in ~/.authinfo. ++ ++@node FAQ 3-6 ++@subsubheading Question 3.6 ++ ++I want Gnus to fetch news from several servers, is this possible? ++ ++@subsubheading Answer ++ ++Of course. You can specify more sources for articles in the ++variable gnus-secondary-select-methods. Add something like ++this in ~/.gnus.el: ++ ++@example ++(add-to-list 'gnus-secondary-select-methods ++ '(nntp "news.yourSecondProvider.net")) ++(add-to-list 'gnus-secondary-select-methods ++ '(nntp "news.yourThirdProvider.net")) ++@end example ++@noindent ++ ++@node FAQ 3-7 ++@subsubheading Question 3.7 ++ ++And how about local spool files? ++ ++@subsubheading Answer ++ ++No problem, this is just one more select method called ++nnspool, so you want this: ++ ++@example ++(add-to-list 'gnus-secondary-select-methods '(nnspool "")) ++@end example ++@noindent ++ ++Or this if you don't want an NNTP Server as primary news source: ++ ++@example ++(setq gnus-select-method '(nnspool "")) ++@end example ++@noindent ++ ++Gnus will look for the spool file in /usr/spool/news, if you ++want something different, change the line above to something like this: ++ ++@example ++(add-to-list 'gnus-secondary-select-methods ++ '(nnspool "" ++ (nnspool-directory "/usr/local/myspoolddir"))) ++@end example ++@noindent ++ ++This sets the spool directory for this server only. ++You might have to specify more stuff like the program used ++to post articles, see the Gnus manual on how to do this. ++ ++@node FAQ 3-8 ++@subsubheading Question 3.8 ++ ++OK, reading news works now, but I want to be able to read my mail ++with Gnus, too. How to do it? ++ ++@subsubheading Answer ++ ++That's a bit harder since there are many possible sources ++for mail, many possible ways for storing mail and many ++different ways for sending mail. The most common cases are ++these: 1: You want to read your mail from a pop3 server and ++send them directly to a SMTP Server 2: Some program like ++fetchmail retrieves your mail and stores it on disk from ++where Gnus shall read it. Outgoing mail is sent by ++Sendmail, Postfix or some other MTA. Sometimes, you even ++need a combination of the above cases. ++ ++However, the first thing to do is to tell Gnus in which way ++it should store the mail, in Gnus terminology which back end ++to use. Gnus supports many different back ends, the most ++commonly used one is nnml. It stores every mail in one file ++and is therefor quite fast. However you might prefer a one ++file per group approach if your file system has problems with ++many small files, the nnfolder back end is then probably the ++choice for you. To use nnml add the following to ~/.gnus.el: ++ ++@example ++(add-to-list 'gnus-secondary-select-methods '(nnml "")) ++@end example ++@noindent ++ ++As you might have guessed, if you want nnfolder, it's ++ ++@example ++(add-to-list 'gnus-secondary-select-methods '(nnfolder "")) ++@end example ++@noindent ++ ++Now we need to tell Gnus, where to get it's mail from. If ++it's a POP3 server, then you need something like this: ++ ++@example ++(eval-after-load "mail-source" ++ '(add-to-list 'mail-sources '(pop :server "pop.YourProvider.net" ++ :user "yourUserName" ++ :password "yourPassword"))) ++@end example ++@noindent ++ ++Make sure ~/.gnus.el isn't readable to others if you store ++your password there. If you want to read your mail from a ++traditional spool file on your local machine, it's ++ ++@example ++(eval-after-load "mail-source" ++ '(add-to-list 'mail-sources '(file :path "/path/to/spool/file")) ++@end example ++@noindent ++ ++If it's a Maildir, with one file per message as used by ++postfix, Qmail and (optionally) fetchmail it's ++ ++@example ++(eval-after-load "mail-source" ++ '(add-to-list 'mail-sources '(maildir :path "/path/to/Maildir/" ++ :subdirs ("cur" "new"))) ++@end example ++@noindent ++ ++And finally if you want to read your mail from several files ++in one directory, for example because procmail already split your ++mail, it's ++ ++@example ++(eval-after-load "mail-source" ++ '(add-to-list 'mail-sources ++ '(directory :path "/path/to/procmail-dir/" ++ :suffix ".prcml"))) ++@end example ++@noindent ++ ++Where :suffix ".prcml" tells Gnus only to use files with the ++suffix .prcml. ++ ++OK, now you only need to tell Gnus how to send mail. If you ++want to send mail via sendmail (or whichever MTA is playing ++the role of sendmail on your system), you don't need to do ++anything. However, if you want to send your mail to an ++SMTP Server you need the following in your ~/.gnus.el ++ ++@example ++(setq send-mail-function 'smtpmail-send-it) ++(setq message-send-mail-function 'smtpmail-send-it) ++(setq smtpmail-default-smtp-server "smtp.yourProvider.net") ++@end example ++@noindent ++ ++@node FAQ 3-9 ++@subsubheading Question 3.9 ++ ++And what about IMAP? ++ ++@subsubheading Answer ++ ++There are two ways of using IMAP with Gnus. The first one is ++to use IMAP like POP3, that means Gnus fetches the mail from ++the IMAP server and stores it on disk. If you want to do ++this (you don't really want to do this) add the following to ++~/.gnus.el ++ ++@example ++(add-to-list 'mail-sources '(imap :server "mail.mycorp.com" ++ :user "username" ++ :pass "password" ++ :stream network ++ :authentication login ++ :mailbox "INBOX" ++ :fetchflag "\\Seen")) ++@end example ++@noindent ++ ++You might have to tweak the values for stream and/or ++authentication, see the Gnus manual node "Mail Source ++Specifiers" for possible values. ++ ++If you want to use IMAP the way it's intended, you've got to ++follow a different approach. You've got to add the nnimap ++back end to your select method and give the information ++about the server there. ++ ++@example ++(add-to-list 'gnus-secondary-select-methods ++ '(nnimap "Give the baby a name" ++ (nnimap-address "imap.yourProvider.net") ++ (nnimap-port 143) ++ (nnimap-list-pattern "archive.*"))) ++@end example ++@noindent ++ ++Again, you might have to specify how to authenticate to the ++server if Gnus can't guess the correct way, see the Manual ++Node "IMAP" for detailed information. ++ ++@node FAQ 3-10 ++@subsubheading Question 3.10 ++ ++At the office we use one of those MS Exchange servers, can I use ++Gnus to read my mail from it? ++ ++@subsubheading Answer ++ ++Offer your administrator a pair of new running shoes for ++activating IMAP on the server and follow the instructions ++above. ++ ++@node FAQ 3-11 ++@subsubheading Question 3.11 ++ ++Can I tell Gnus not to delete the mails on the server it ++retrieves via POP3? ++ ++@subsubheading Answer ++ ++First of all, that's not the way POP3 is intended to work, ++if you have the possibility, you should use the IMAP ++Protocol if you want your messages to stay on the ++server. Nevertheless there might be situations where you ++need the feature, but sadly Gnus itself has no predefined ++functionality to do so. ++ ++However this is Gnus county so there are possibilities to ++achieve what you want. The easiest way is to get an external ++program which retrieves copies of the mail and stores them ++on disk, so Gnus can read it from there. On Unix systems you ++could use e.g. fetchmail for this, on MS Windows you can use ++Hamster, an excellent local news and mail server. ++ ++The other solution would be, to replace the method Gnus ++uses to get mail from POP3 servers by one which is capable ++of leaving the mail on the server. If you use XEmacs, get ++the package mail-lib, it includes an enhanced pop3.el, ++look in the file, there's documentation on how to tell ++Gnus to use it and not to delete the retrieved mail. For ++GNU Emacs look for the file epop3.el which can do the same ++(If you know the home of this file, please send me an ++e-mail). You can also tell Gnus to use an external program ++(e.g. fetchmail) to fetch your mail, see the info node ++"Mail Source Specifiers" in the Gnus manual on how to do ++it. ++ ++@node FAQ 4 - Reading messages ++@subsection Reading messages ++ ++@menu ++* FAQ 4-1:: When I enter a group, all read messages are gone. How to ++ view them again? ++* FAQ 4-2:: How to tell Gnus to show an important message every time ++ I enter a group, even when it's read? ++* FAQ 4-3:: How to view the headers of a message? ++* FAQ 4-4:: How to view the raw unformatted message? ++* FAQ 4-5:: How can I change the headers Gnus displays by default at ++ the top of the article buffer? ++* FAQ 4-6:: I'd like Gnus NOT to render HTML-mails but show me the ++ text part if it's available. How to do it? ++* FAQ 4-7:: Can I use some other browser than w3 to render my ++ HTML-mails? ++* FAQ 4-8:: Is there anything I can do to make poorly formatted ++ mails more readable? ++* FAQ 4-9:: Is there a way to automatically ignore posts by specific ++ authors or with specific words in the subject? And can I ++ highlight more interesting ones in some way? ++* FAQ 4-10:: How can I disable threading in some (e.g. mail-) groups, ++ or set other variables specific for some groups? ++* FAQ 4-11:: Can I highlight messages written by me and follow-ups to ++ those? ++* FAQ 4-12:: The number of total messages in a group which Gnus ++ displays in group buffer is by far to high, especially in mail ++ groups. Is this a bug? ++* FAQ 4-13:: I don't like the layout of summary and article buffer, ++ how to change it? Perhaps even a three pane display? ++* FAQ 4-14:: I don't like the way the Summary buffer looks, how to ++ tweak it? ++* FAQ 4-15:: How to split incoming mails in several groups? ++@end menu ++ ++@node FAQ 4-1 ++@subsubheading Question 4.1 ++ ++When I enter a group, all read messages are gone. How to view them again? ++ ++@subsubheading Answer ++ ++If you enter the group by saying ++@samp{RET} ++in group buffer with point over the group, only unread and ticked messages are loaded. Say ++@samp{C-u RET} ++instead to load all available messages. If you want only the e.g. 300 newest say ++@samp{C-u 300 RET} ++ ++Loading only unread messages can be annoying if you have threaded view enabled, say ++ ++@example ++(setq gnus-fetch-old-headers 'some) ++@end example ++@noindent ++ ++in ~/.gnus.el to load enough old articles to prevent teared threads, replace 'some with t to load ++all articles (Warning: Both settings enlarge the amount of data which is ++fetched when you enter a group and slow down the process of entering a group). ++ ++If you already use Gnus 5.10, you can say ++@samp{/o N} ++In summary buffer to load the last N messages, this feature is not available in 5.8.8 ++ ++If you don't want all old messages, but the parent of the message you're just reading, ++you can say @samp{^}, if you want to retrieve the whole thread ++the message you're just reading belongs to, @samp{A T} is your friend. ++ ++@node FAQ 4-2 ++@subsubheading Question 4.2 ++ ++How to tell Gnus to show an important message every time I ++enter a group, even when it's read? ++ ++@subsubheading Answer ++ ++You can tick important messages. To do this hit ++@samp{u} while point is in summary buffer ++over the message. When you want to remove the mark, hit ++either @samp{d} (this deletes the tick ++mark and set's unread mark) or @samp{M c} ++(which deletes all marks for the message). ++ ++@node FAQ 4-3 ++@subsubheading Question 4.3 ++ ++How to view the headers of a message? ++ ++@subsubheading Answer ++ ++Say @samp{t} ++to show all headers, one more ++@samp{t} ++hides them again. ++ ++@node FAQ 4-4 ++@subsubheading Question 4.4 ++ ++How to view the raw unformatted message? ++ ++@subsubheading Answer ++ ++Say ++@samp{C-u g} ++to show the raw message ++@samp{g} ++returns to normal view. ++ ++@node FAQ 4-5 ++@subsubheading Question 4.5 ++ ++How can I change the headers Gnus displays by default at ++the top of the article buffer? ++ ++@subsubheading Answer ++ ++The variable gnus-visible-headers controls which headers ++are shown, its value is a regular expression, header lines ++which match it are shown. So if you want author, subject, ++date, and if the header exists, Followup-To and MUA / NUA ++say this in ~/.gnus.el: ++ ++@example ++(setq gnus-visible-headers ++ '("^From" "^Subject" "^Date" "^Newsgroups" "^Followup-To" ++ "^User-Agent" "^X-Newsreader" "^X-Mailer")) ++@end example ++@noindent ++ ++@node FAQ 4-6 ++@subsubheading Question 4.6 ++ ++I'd like Gnus NOT to render HTML-mails but show me the ++text part if it's available. How to do it? ++ ++@subsubheading Answer ++ ++Say ++ ++@example ++(eval-after-load "mm-decode" ++ '(progn ++ (add-to-list 'mm-discouraged-alternatives "text/html") ++ (add-to-list 'mm-discouraged-alternatives "text/richtext"))) ++@end example ++@noindent ++ ++in ~/.gnus.el. If you don't want HTML rendered, even if there's no text alternative add ++ ++@example ++(setq mm-automatic-display (remove "text/html" mm-automatic-display)) ++@end example ++@noindent ++ ++too. ++ ++@node FAQ 4-7 ++@subsubheading Question 4.7 ++ ++Can I use some other browser than w3 to render my HTML-mails? ++ ++@subsubheading Answer ++ ++Only if you use Gnus 5.10 or younger. In this case you've got the ++choice between w3, w3m, links, lynx and html2text, which ++one is used can be specified in the variable ++mm-text-html-renderer, so if you want links to render your ++mail say ++ ++@example ++(setq mm-text-html-renderer 'links) ++@end example ++@noindent ++ ++@node FAQ 4-8 ++@subsubheading Question 4.8 ++ ++Is there anything I can do to make poorly formatted mails ++more readable? ++ ++@subsubheading Answer ++ ++Gnus offers you several functions to "wash" incoming mail, you can ++find them if you browse through the menu, item ++Article->Washing. The most interesting ones are probably "Wrap ++long lines" (@samp{W w}), "Decode ROT13" ++(@samp{W r}) and "Outlook Deuglify" which repairs ++the dumb quoting used by many users of Microsoft products ++(@samp{W Y f} gives you full deuglify. ++See @samp{W Y C-h} or have a look at the menus for ++other deuglifications). Outlook deuglify is only available since ++Gnus 5.10. ++ ++@node FAQ 4-9 ++@subsubheading Question 4.9 ++ ++Is there a way to automatically ignore posts by specific ++authors or with specific words in the subject? And can I ++highlight more interesting ones in some way? ++ ++@subsubheading Answer ++ ++You want Scoring. Scoring means, that you define rules ++which assign each message an integer value. Depending on ++the value the message is highlighted in summary buffer (if ++it's high, say +2000) or automatically marked read (if the ++value is low, say -800) or some other action happens. ++ ++There are basically three ways of setting up rules which assign ++the scoring-value to messages. The first and easiest way is to set ++up rules based on the article you are just reading. Say you're ++reading a message by a guy who always writes nonsense and you want ++to ignore his messages in the future. Hit ++@samp{L}, to set up a rule which lowers the score. ++Now Gnus asks you which the criteria for lowering the Score shall ++be. Hit @samp{?} twice to see all possibilities, ++we want @samp{a} which means the author (the from ++header). Now Gnus wants to know which kind of matching we want. ++Hit either @samp{e} for an exact match or ++@samp{s} for substring-match and delete afterwards ++everything but the name to score down all authors with the given ++name no matter which email address is used. Now you need to tell ++Gnus when to apply the rule and how long it should last, hit e.g. ++@samp{p} to apply the rule now and let it last ++forever. If you want to raise the score instead of lowering it say ++@samp{I} instead of @samp{L}. ++ ++You can also set up rules by hand. To do this say @samp{V ++f} in summary buffer. Then you are asked for the name ++of the score file, it's name.of.group.SCORE for rules valid in ++only one group or all.Score for rules valid in all groups. See the ++Gnus manual for the exact syntax, basically it's one big list ++whose elements are lists again. the first element of those lists ++is the header to score on, then one more list with what to match, ++which score to assign, when to expire the rule and how to do the ++matching. If you find me very interesting, you could e.g. add the ++following to your all.Score: ++ ++@example ++(("references" ("hschmi22.userfqdn.rz-online.de" 500 nil s)) ++ ("message-id" ("hschmi22.userfqdn.rz-online.de" 999 nil s))) ++@end example ++@noindent ++ ++This would add 999 to the score of messages written by me ++and 500 to the score of messages which are a (possibly ++indirect) answer to a message written by me. Of course ++nobody with a sane mind would do this :-) ++ ++The third alternative is adaptive scoring. This means Gnus ++watches you and tries to find out what you find ++interesting and what annoying and sets up rules ++which reflect this. Adaptive scoring can be a huge help ++when reading high traffic groups. If you want to activate ++adaptive scoring say ++ ++@example ++(setq gnus-use-adaptive-scoring t) ++@end example ++@noindent ++ ++in ~/.gnus.el. ++ ++@node FAQ 4-10 ++@subsubheading Question 4.10 ++ ++How can I disable threading in some (e.g. mail-) groups, or ++set other variables specific for some groups? ++ ++@subsubheading Answer ++ ++While in group buffer move point over the group and hit ++@samp{G c}, this opens a buffer where you ++can set options for the group. At the bottom of the buffer ++you'll find an item that allows you to set variables ++locally for the group. To disable threading enter ++gnus-show-threads as name of variable and nil as ++value. Hit button done at the top of the buffer when ++you're ready. ++ ++@node FAQ 4-11 ++@subsubheading Question 4.11 ++ ++Can I highlight messages written by me and follow-ups to ++those? ++ ++@subsubheading Answer ++ ++Stop those "Can I ..." questions, the answer is always yes ++in Gnus Country :-). It's a three step process: First we ++make faces (specifications of how summary-line shall look ++like) for those postings, then we'll give them some ++special score and finally we'll tell Gnus to use the new ++faces. You can find detailed instructions on how to do it on ++@uref{http://my.gnus.org/node/view/224, my.gnus.org} ++ ++@node FAQ 4-12 ++@subsubheading Question 4.12 ++ ++The number of total messages in a group which Gnus ++displays in group buffer is by far to high, especially in ++mail groups. Is this a bug? ++ ++@subsubheading Answer ++ ++No, that's a matter of design of Gnus, fixing this would ++mean reimplementation of major parts of Gnus' ++back ends. Gnus thinks "highest-article-number - ++lowest-article-number = total-number-of-articles". This ++works OK for Usenet groups, but if you delete and move ++many messages in mail groups, this fails. To cure the ++symptom, enter the group via @samp{C-u RET} ++(this makes Gnus get all messages), then ++hit @samp{M P b} to mark all messages and ++then say @samp{B m name.of.group} to move ++all messages to the group they have been in before, they ++get new message numbers in this process and the count is ++right again (until you delete and move your mail to other ++groups again). ++ ++@node FAQ 4-13 ++@subsubheading Question 4.13 ++ ++I don't like the layout of summary and article buffer, how ++to change it? Perhaps even a three pane display? ++ ++@subsubheading Answer ++ ++You can control the windows configuration by calling the ++function gnus-add-configuration. The syntax is a bit ++complicated but explained very well in the manual node ++"Window Layout". Some popular examples: ++ ++Instead 25% summary 75% article buffer 35% summary and 65% ++article (the 1.0 for article means "take the remaining ++space"): ++ ++@example ++(gnus-add-configuration ++ '(article (vertical 1.0 (summary .35 point) (article 1.0)))) ++@end example ++@noindent ++ ++A three pane layout, Group buffer on the left, summary ++buffer top-right, article buffer bottom-right: ++ ++@example ++(gnus-add-configuration ++ '(article ++ (horizontal 1.0 ++ (vertical 25 ++ (group 1.0)) ++ (vertical 1.0 ++ (summary 0.25 point) ++ (article 1.0))))) ++(gnus-add-configuration ++ '(summary ++ (horizontal 1.0 ++ (vertical 25 ++ (group 1.0)) ++ (vertical 1.0 ++ (summary 1.0 point))))) ++@end example ++@noindent ++ ++@node FAQ 4-14 ++@subsubheading Question 4.14 ++ ++I don't like the way the Summary buffer looks, how to tweak it? ++ ++@subsubheading Answer ++ ++You've got to play around with the variable ++gnus-summary-line-format. It's value is a string of ++symbols which stand for things like author, date, subject ++etc. A list of the available specifiers can be found in the ++manual node "Summary Buffer Lines" and the often forgotten ++node "Formatting Variables" and it's sub-nodes. There ++you'll find useful things like positioning the cursor and ++tabulators which allow you a summary in table form, but ++sadly hard tabulators are broken in 5.8.8. ++ ++Since 5.10, Gnus offers you some very nice new specifiers, ++e.g. %B which draws a thread-tree and %&user-date which ++gives you a date where the details are dependent of the ++articles age. Here's an example which uses both: ++ ++@example ++(setq gnus-summary-line-format ":%U%R %B %s %-60=|%4L |%-20,20f |%&user-date; \n") ++@end example ++@noindent ++ ++resulting in: ++ ++@example ++:O Re: [Richard Stallman] rfc2047.el | 13 |Lars Magne Ingebrigt |Sat 23:06 ++:O Re: Revival of the ding-patches list | 13 |Lars Magne Ingebrigt |Sat 23:12 ++:R > Re: Find correct list of articles for a gro| 25 |Lars Magne Ingebrigt |Sat 23:16 ++:O \-> ... | 21 |Kai Grossjohann | 0:01 ++:R > Re: Cry for help: deuglify.el - moving stuf| 28 |Lars Magne Ingebrigt |Sat 23:34 ++:O \-> ... | 115 |Raymond Scholz | 1:24 ++:O \-> ... | 19 |Lars Magne Ingebrigt |15:33 ++:O Slow mailing list | 13 |Lars Magne Ingebrigt |Sat 23:49 ++:O Re: `@@' mark not documented | 13 |Lars Magne Ingebrigt |Sat 23:50 ++:R > Re: Gnus still doesn't count messages prope| 23 |Lars Magne Ingebrigt |Sat 23:57 ++:O \-> ... | 18 |Kai Grossjohann | 0:35 ++:O \-> ... | 13 |Lars Magne Ingebrigt | 0:56 ++@end example ++@noindent ++ ++@node FAQ 4-15 ++@subsubheading Question 4.15 ++ ++How to split incoming mails in several groups? ++ ++@subsubheading Answer ++ ++Gnus offers two possibilities for splitting mail, the easy ++nnmail-split-methods and the more powerful Fancy Mail ++Splitting. I'll only talk about the first one, refer to ++the manual, node "Fancy Mail Splitting" for the latter. ++ ++The value of nnmail-split-methods is a list, each element ++is a list which stands for a splitting rule. Each rule has ++the form "group where matching articles should go to", ++"regular expression which has to be matched", the first ++rule which matches wins. The last rule must always be a ++general rule (regular expression .*) which denotes where ++articles should go which don't match any other rule. If ++the folder doesn't exist yet, it will be created as soon ++as an article lands there. By default the mail will be ++send to all groups whose rules match. If you ++don't want that (you probably don't want), say ++ ++@example ++(setq nnmail-crosspost nil) ++@end example ++@noindent ++ ++in ~/.gnus.el. ++ ++An example might be better than thousand words, so here's ++my nnmail-split-methods. Note that I send duplicates in a ++special group and that the default group is spam, since I ++filter all mails out which are from some list I'm ++subscribed to or which are addressed directly to me ++before. Those rules kill about 80% of the Spam which ++reaches me (Email addresses are changed to prevent spammers ++from using them): ++ ++@example ++(setq nnmail-split-methods ++ '(("duplicates" "^Gnus-Warning:.*duplicate") ++ ("XEmacs-NT" "^\\(To:\\|CC:\\).*localpart@@xemacs.invalid.*") ++ ("Gnus-Tut" "^\\(To:\\|CC:\\).*localpart@@socha.invalid.*") ++ ("tcsh" "^\\(To:\\|CC:\\).*localpart@@mx.gw.invalid.*") ++ ("BAfH" "^\\(To:\\|CC:\\).*localpart@@.*uni-muenchen.invalid.*") ++ ("Hamster-src" "^\\(CC:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") ++ ("Tagesschau" "^From: tagesschau $") ++ ("Replies" "^\\(CC:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") ++ ("EK" "^From:.*\\(localpart@@privateprovider.invalid\\|localpart@@workplace.invalid\\).*") ++ ("Spam" "^Content-Type:.*\\(ks_c_5601-1987\\|EUC-KR\\|big5\\|iso-2022-jp\\).*") ++ ("Spam" "^Subject:.*\\(This really work\\|XINGA\\|ADV:\\|XXX\\|adult\\|sex\\).*") ++ ("Spam" "^Subject:.*\\(\=\?ks_c_5601-1987\?\\|\=\?euc-kr\?\\|\=\?big5\?\\).*") ++ ("Spam" "^X-Mailer:\\(.*BulkMailer.*\\|.*MIME::Lite.*\\|\\)") ++ ("Spam" "^X-Mailer:\\(.*CyberCreek Avalanche\\|.*http\:\/\/GetResponse\.com\\)") ++ ("Spam" "^From:.*\\(verizon\.net\\|prontomail\.com\\|money\\|ConsumerDirect\\).*") ++ ("Spam" "^Delivered-To: GMX delivery to spamtrap@@gmx.invalid$") ++ ("Spam" "^Received: from link2buy.com") ++ ("Spam" "^CC: .*azzrael@@t-online.invalid") ++ ("Spam" "^X-Mailer-Version: 1.50 BETA") ++ ("Uni" "^\\(CC:\\|To:\\).*localpart@@uni-koblenz.invalid.*") ++ ("Inbox" "^\\(CC:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|adress@@two.invalid\\)") ++ ("Spam" ""))) ++@end example ++@noindent ++ ++@node FAQ 5 - Composing messages ++@subsection Composing messages ++ ++@menu ++* FAQ 5-1:: What are the basic commands I need to know for sending ++ mail and postings? ++* FAQ 5-2:: How to enable automatic word-wrap when composing ++ messages? ++* FAQ 5-3:: How to set stuff like From, Organization, Reply-To, ++ signature...? ++* FAQ 5-4:: Can I set things like From, Signature etc group based on ++ the group I post too? ++* FAQ 5-5:: Is there a spell-checker? Perhaps even on-the-fly ++ spell-checking? ++* FAQ 5-6:: Can I set the dictionary based on the group I'm posting ++ to? ++* FAQ 5-7:: Is there some kind of address-book, so I needn't ++ remember all those email addresses? ++* FAQ 5-8:: Sometimes I see little images at the top of article ++ buffer. What's that and how can I send one with my postings, ++ too? ++* FAQ 5-9:: Sometimes I accidentally hit r instead of f in ++ newsgroups. Can Gnus warn me, when I'm replying by mail in ++ newsgroups? ++* FAQ 5-10:: How to tell Gnus not to generate a sender header? ++* FAQ 5-11:: I want Gnus to locally store copies of my send mail and ++ news, how to do it? ++* FAQ 5-12:: I want Gnus to kill the buffer after successful sending ++ instead of keeping it alive as "Sent mail to...", how to do it? ++* FAQ 5-13:: People tell me my Message-IDs are not correct, why ++ aren't they and how to fix it? ++@end menu ++ ++@node FAQ 5-1 ++@subsubheading Question 5.1 ++ ++What are the basic commands I need to know for sending mail and postings? ++ ++@subsubheading Answer ++ ++To start composing a new mail hit @samp{m} ++either in Group or Summary buffer, for a posting, it's ++either @samp{a} in Group buffer and ++filling the Newsgroups header manually ++or @samp{a} in the Summary buffer of the ++group where the posting shall be send to. Replying by mail ++is ++@samp{r} if you don't want to cite the ++author, or import the cited text manually and ++@samp{R} to cite the text of the original ++message. For a follow up to a newsgroup, it's ++@samp{f} and @samp{F} ++(analogously to @samp{r} and ++@samp{R}). ++ ++Enter new headers above the line saying "--text follows ++this line--", enter the text below the line. When ready ++hit @samp{C-c C-c}, to send the message, ++if you want to finish it later hit @samp{C-c ++C-d} to save it in the drafts group, where you ++can start editing it again by saying @samp{D ++e}. ++ ++@node FAQ 5-2 ++@subsubheading Question 5.2 ++ ++How to enable automatic word-wrap when composing messages? ++ ++@subsubheading Answer ++ ++Starting from No Gnus, automatic word-wrap is already enabled by ++default, see the variable message-fill-column. ++ ++For other versions of Gnus, say ++ ++@example ++(unless (boundp 'message-fill-column) ++ (add-hook 'message-mode-hook ++ (lambda () ++ (setq fill-column 72) ++ (turn-on-auto-fill)))) ++@end example ++@noindent ++ ++in ~/.gnus.el. ++ ++You can reformat a paragraph by hitting @samp{M-q} ++(as usual). ++ ++@node FAQ 5-3 ++@subsubheading Question 5.3 ++ ++How to set stuff like From, Organization, Reply-To, signature...? ++ ++@subsubheading Answer ++ ++There are other ways, but you should use posting styles ++for this. (See below why). ++This example should make the syntax clear: ++ ++@example ++(setq gnus-posting-styles ++ '((".*" ++ (name "Frank Schmitt") ++ (address "me@@there.invalid") ++ (organization "Hamme net, kren mer och nimmi") ++ (signature-file "~/.signature") ++ ("X-SampleHeader" "foobar") ++ (eval (setq some-variable "Foo bar"))))) ++@end example ++@noindent ++ ++The ".*" means that this settings are the default ones ++(see below), valid values for the first element of the ++following lists are signature, signature-file, ++organization, address, name or body. The attribute name ++can also be a string. In that case, this will be used as ++a header name, and the value will be inserted in the ++headers of the article; if the value is `nil', the header ++name will be removed. You can also say (eval (foo bar)), ++then the function foo will be evaluated with argument bar ++and the result will be thrown away. ++ ++@node FAQ 5-4 ++@subsubheading Question 5.4 ++ ++Can I set things like From, Signature etc group based on the group I post too? ++ ++@subsubheading Answer ++ ++That's the strength of posting styles. Before, we used ".*" ++to set the default for all groups. You can use a regexp ++like "^gmane" and the following settings are only applied ++to postings you send to the gmane hierarchy, use ++".*binaries" instead and they will be applied to postings ++send to groups containing the string binaries in their ++name etc. ++ ++You can instead of specifying a regexp specify a function ++which is evaluated, only if it returns true, the ++corresponding settings take effect. Two interesting ++candidates for this are message-news-p which returns t if ++the current Group is a newsgroup and the corresponding ++message-mail-p. ++ ++Note that all forms that match are applied, that means in ++the example below, when I post to ++gmane.mail.spam.spamassassin.general, the settings under ++".*" are applied and the settings under message-news-p and ++those under "^gmane" and those under ++"^gmane\\.mail\\.spam\\.spamassassin\\.general$". Because ++of this put general settings at the top and specific ones ++at the bottom. ++ ++@example ++(setq gnus-posting-styles ++ '((".*" ;;default ++ (name "Frank Schmitt") ++ (organization "Hamme net, kren mer och nimmi") ++ (signature-file "~/.signature")) ++ ((message-news-p) ;;Usenet news? ++ (address "mySpamTrap@@Frank-Schmitt.invalid") ++ (reply-to "hereRealRepliesOnlyPlease@@Frank-Schmitt.invalid")) ++ ((message-mail-p) ;;mail? ++ (address "usedForMails@@Frank-Schmitt.invalid")) ++ ("^gmane" ;;this is mail, too in fact ++ (address "usedForMails@@Frank-Schmitt.invalid") ++ (reply-to nil)) ++ ("^gmane\\.mail\\.spam\\.spamassassin\\.general$" ++ (eval (set (make-local-variable 'message-sendmail-envelope-from) ++ "Azzrael@@rz-online.de"))))) ++@end example ++@noindent ++ ++@node FAQ 5-5 ++@subsubheading Question 5.5 ++ ++Is there a spell-checker? Perhaps even on-the-fly spell-checking? ++ ++@subsubheading Answer ++ ++You can use ispell.el to spell-check stuff in Emacs. So the ++first thing to do is to make sure that you've got either ++@uref{http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html, ispell} ++or @uref{http://aspell.sourceforge.net/, aspell} ++installed and in your Path. Then you need ++@uref{http://www.kdstevens.com/~stevens/ispell-page.html, ispell.el} ++and for on-the-fly spell-checking ++@uref{http://www-sop.inria.fr/mimosa/personnel/Manuel.Serrano/flyspell/flyspell.html, flyspell.el}. ++Ispell.el is shipped with Emacs and available through the XEmacs package system, ++flyspell.el is shipped with Emacs and part of XEmacs text-modes package which is ++available through the package system, so there should be no need to install them ++manually. ++ ++Ispell.el assumes you use ispell, if you choose aspell say ++ ++@example ++(setq ispell-program-name "aspell") ++@end example ++@noindent ++ ++in your Emacs configuration file. ++ ++If you want your outgoing messages to be spell-checked, say ++ ++@example ++(add-hook 'message-send-hook 'ispell-message) ++@end example ++@noindent ++ ++In your ~/.gnus.el, if you prefer on-the-fly spell-checking say ++ ++@example ++(add-hook 'message-mode-hook (lambda () (flyspell-mode 1))) ++@end example ++@noindent ++ ++@node FAQ 5-6 ++@subsubheading Question 5.6 ++ ++Can I set the dictionary based on the group I'm posting to? ++ ++@subsubheading Answer ++ ++Yes, say something like ++ ++@example ++(add-hook 'gnus-select-group-hook ++ (lambda () ++ (cond ++ ((string-match ++ "^de\\." (gnus-group-real-name gnus-newsgroup-name)) ++ (ispell-change-dictionary "deutsch8")) ++ (t ++ (ispell-change-dictionary "english"))))) ++@end example ++@noindent ++ ++in ~/.gnus.el. Change "^de\\." and "deutsch8" to something ++that suits your needs. ++ ++@node FAQ 5-7 ++@subsubheading Question 5.7 ++ ++Is there some kind of address-book, so I needn't remember ++all those email addresses? ++ ++@subsubheading Answer ++ ++There's an very basic solution for this, mail aliases. ++You can store your mail addresses in a ~/.mailrc file using a simple ++alias syntax: ++ ++@example ++alias al "Al " ++@end example ++@noindent ++ ++Then typing your alias (followed by a space or punctuation ++character) on a To: or Cc: line in the message buffer will ++cause Gnus to insert the full address for you. See the ++node "Mail Aliases" in Message (not Gnus) manual for ++details. ++ ++However, what you really want is the Insidious Big Brother ++Database bbdb. Get it through the XEmacs package system or from ++@uref{http://bbdb.sourceforge.net/, bbdb's homepage}. ++Now place the following in ~/.gnus.el, to activate bbdb for Gnus: ++ ++@example ++(require 'bbdb) ++(bbdb-initialize 'gnus 'message) ++@end example ++@noindent ++ ++Now you probably want some general bbdb configuration, ++place them in ~/.emacs: ++ ++@example ++(require 'bbdb) ++;;If you don't live in Northern America, you should disable the ++;;syntax check for telephone numbers by saying ++(setq bbdb-north-american-phone-numbers-p nil) ++;;Tell bbdb about your email address: ++(setq bbdb-user-mail-names ++ (regexp-opt '("Your.Email@@here.invalid" ++ "Your.other@@mail.there.invalid"))) ++;;cycling while completing email addresses ++(setq bbdb-complete-name-allow-cycling t) ++;;No popup-buffers ++(setq bbdb-use-pop-up nil) ++@end example ++@noindent ++ ++Now you should be ready to go. Say @samp{M-x bbdb RET ++RET} to open a bbdb buffer showing all ++entries. Say @samp{c} to create a new ++entry, @samp{b} to search your BBDB and ++@samp{C-o} to add a new field to an ++entry. If you want to add a sender to the BBDB you can ++also just hit `:' on the posting in the summary buffer and ++you are done. When you now compose a new mail, ++hit @samp{TAB} to cycle through know ++recipients. ++ ++@node FAQ 5-8 ++@subsubheading Question 5.8 ++ ++Sometimes I see little images at the top of article ++buffer. What's that and how can I send one with my ++postings, too? ++ ++@subsubheading Answer ++ ++Those images are called X-Faces. They are 48*48 pixel b/w ++pictures, encoded in a header line. If you want to include ++one in your posts, you've got to convert some image to a ++X-Face. So fire up some image manipulation program (say ++Gimp), open the image you want to include, cut out the ++relevant part, reduce color depth to 1 bit, resize to ++48*48 and save as bitmap. Now you should get the compface ++package from ++@uref{ftp://ftp.cs.indiana.edu:/pub/faces/, this site}. ++and create the actual X-face by saying ++ ++@example ++cat file.xbm | xbm2ikon | compface > file.face ++cat file.face | sed 's/\\/\\\\/g;s/\"/\\\"/g;' > file.face.quoted ++@end example ++@noindent ++ ++If you can't use compface, there's an online X-face converter at ++@uref{http://www.dairiki.org/xface/}. ++If you use MS Windows, you could also use the WinFace program from ++@uref{http://www.xs4all.nl/~walterln/winface/}. ++Now you only have to tell Gnus to include the X-face in your postings by saying ++ ++@example ++(setq message-default-headers ++ (with-temp-buffer ++ (insert "X-Face: ") ++ (insert-file-contents "~/.xface") ++ (buffer-string))) ++@end example ++@noindent ++ ++in ~/.gnus.el. If you use Gnus 5.10, you can simply add an entry ++ ++@example ++(x-face-file "~/.xface") ++@end example ++@noindent ++ ++to gnus-posting-styles. ++ ++@node FAQ 5-9 ++@subsubheading Question 5.9 ++ ++Sometimes I accidentally hit r instead of f in ++newsgroups. Can Gnus warn me, when I'm replying by mail in ++newsgroups? ++ ++@subsubheading Answer ++ ++Put this in ~/.gnus.el: ++ ++@example ++(setq gnus-confirm-mail-reply-to-news t) ++@end example ++@noindent ++ ++if you already use Gnus 5.10, if you still use 5.8.8 or ++5.9 try this instead: ++ ++@example ++(eval-after-load "gnus-msg" ++ '(unless (boundp 'gnus-confirm-mail-reply-to-news) ++ (defadvice gnus-summary-reply (around reply-in-news activate) ++ "Request confirmation when replying to news." ++ (interactive) ++ (when (or (not (gnus-news-group-p gnus-newsgroup-name)) ++ (y-or-n-p "Really reply by mail to article author? ")) ++ ad-do-it)))) ++@end example ++@noindent ++ ++@node FAQ 5-10 ++@subsubheading Question 5.10 ++ ++How to tell Gnus not to generate a sender header? ++ ++@subsubheading Answer ++ ++Since 5.10 Gnus doesn't generate a sender header by ++default. For older Gnus' try this in ~/.gnus.el: ++ ++@example ++(eval-after-load "message" ++ '(add-to-list 'message-syntax-checks '(sender . disabled))) ++@end example ++@noindent ++ ++@node FAQ 5-11 ++@subsubheading Question 5.11 ++ ++I want Gnus to locally store copies of my send mail and ++news, how to do it? ++ ++@subsubheading Answer ++ ++You must set the variable gnus-message-archive-group to do ++this. You can set it to a string giving the name of the ++group where the copies shall go or like in the example ++below use a function which is evaluated and which returns ++the group to use. ++ ++@example ++(setq gnus-message-archive-group ++ '((if (message-news-p) ++ "nnml:Send-News" ++ "nnml:Send-Mail"))) ++@end example ++@noindent ++ ++@node FAQ 5-12 ++@subsubheading Question 5.12 ++ ++I want Gnus to kill the buffer after successful sending instead of keeping ++it alive as "Sent mail to...", how to do it? ++ ++@subsubheading Answer ++ ++Add this to your ~/.gnus: ++ ++@example ++(setq message-kill-buffer-on-exit t) ++@end example ++@noindent ++ ++@node FAQ 5-13 ++@subsubheading Question 5.13 ++ ++People tell me my Message-IDs are not correct, why ++aren't they and how to fix it? ++ ++@subsubheading Answer ++ ++The message-ID is an unique identifier for messages you ++send. To make it unique, Gnus need to know which machine ++name to put after the "@@". If the name of the machine ++where Gnus is running isn't suitable (it probably isn't ++at most private machines) you can tell Gnus what to use ++by saying: ++ ++@example ++(setq message-user-fqdn "yourmachine.yourdomain.tld") ++@end example ++@noindent ++ ++in ~/.gnus.el. If you use Gnus 5.9 or earlier, you can use this ++instead (works for newer versions as well): ++ ++@example ++(eval-after-load "message" ++ '(let ((fqdn "yourmachine.yourdomain.tld"));; <-- Edit this! ++ (if (boundp 'message-user-fqdn) ++ (setq message-user-fqdn fqdn) ++ (gnus-message 1 "Redefining `message-make-fqdn'.") ++ (defun message-make-fqdn () ++ "Return user's fully qualified domain name." ++ fqdn)))) ++@end example ++@noindent ++ ++If you have no idea what to insert for ++"yourmachine.yourdomain.tld", you've got several ++choices. You can either ask your provider if he allows ++you to use something like ++yourUserName.userfqdn.provider.net, or you can use ++somethingUnique.yourdomain.tld if you own the domain ++yourdomain.tld, or you can register at a service which ++gives private users a FQDN for free. ++ ++Finally you can tell Gnus not to generate a Message-ID ++for News at all (and letting the server do the job) by saying ++ ++@example ++(setq message-required-news-headers ++ (remove' Message-ID message-required-news-headers)) ++@end example ++@noindent ++ ++you can also tell Gnus not to generate Message-IDs for mail by saying ++ ++@example ++(setq message-required-mail-headers ++ (remove' Message-ID message-required-mail-headers)) ++@end example ++@noindent ++ ++, however some mail servers don't generate proper ++Message-IDs, too, so test if your Mail Server behaves ++correctly by sending yourself a Mail and looking at the Message-ID. ++ ++@node FAQ 6 - Old messages ++@subsection Old messages ++ ++@menu ++* FAQ 6-1:: How to import my old mail into Gnus? ++* FAQ 6-2:: How to archive interesting messages? ++* FAQ 6-3:: How to search for a specific message? ++* FAQ 6-4:: How to get rid of old unwanted mail? ++* FAQ 6-5:: I want that all read messages are expired (at least in ++ some groups). How to do it? ++* FAQ 6-6:: I don't want expiration to delete my mails but to move ++ them to another group. ++@end menu ++ ++@node FAQ 6-1 ++@subsubheading Question 6.1 ++ ++How to import my old mail into Gnus? ++ ++@subsubheading Answer ++ ++The easiest way is to tell your old mail program to ++export the messages in mbox format. Most Unix mailers ++are able to do this, if you come from the MS Windows ++world, you may find tools at ++@uref{http://mbx2mbox.sourceforge.net/}. ++ ++Now you've got to import this mbox file into Gnus. To do ++this, create a nndoc group based on the mbox file by ++saying @samp{G f /path/file.mbox RET} in ++Group buffer. You now have read-only access to your ++mail. If you want to import the messages to your normal ++Gnus mail groups hierarchy, enter the nndoc group you've ++just created by saying @samp{C-u RET} ++(thus making sure all messages are retrieved), mark all ++messages by saying @samp{M P b} and ++either copy them to the desired group by saying ++@samp{B c name.of.group RET} or send them ++through nnmail-split-methods (respool them) by saying ++@samp{B r}. ++ ++@node FAQ 6-2 ++@subsubheading Question 6.2 ++ ++How to archive interesting messages? ++ ++@subsubheading Answer ++ ++If you stumble across an interesting message, say in ++gnu.emacs.gnus and want to archive it there are several ++solutions. The first and easiest is to save it to a file ++by saying @samp{O f}. However, wouldn't ++it be much more convenient to have more direct access to ++the archived message from Gnus? If you say yes, put this ++snippet by Frank Haun in ++~/.gnus.el: ++ ++@example ++(defun my-archive-article (&optional n) ++ "Copies one or more article(s) to a corresponding `nnml:' group, e.g. ++`gnus.ding' goes to `nnml:1.gnus.ding'. And `nnml:List-gnus.ding' goes ++to `nnml:1.List-gnus-ding'. ++ ++Use process marks or mark a region in the summary buffer to archive ++more then one article." ++ (interactive "P") ++ (let ((archive-name ++ (format ++ "nnml:1.%s" ++ (if (featurep 'xemacs) ++ (replace-in-string gnus-newsgroup-name "^.*:" "") ++ (replace-regexp-in-string "^.*:" "" gnus-newsgroup-name))))) ++ (gnus-summary-copy-article n archive-name))) ++@end example ++@noindent ++ ++You can now say @samp{M-x ++my-archive-article} in summary buffer to ++archive the article under the cursor in a nnml ++group. (Change nnml to your preferred back end) ++ ++Of course you can also make sure the cache is enabled by saying ++ ++@example ++(setq gnus-use-cache t) ++@end example ++@noindent ++ ++then you only have to set either the tick or the dormant ++mark for articles you want to keep, setting the read ++mark will remove them from cache. ++ ++@node FAQ 6-3 ++@subsubheading Question 6.3 ++ ++How to search for a specific message? ++ ++@subsubheading Answer ++ ++There are several ways for this, too. For a posting from ++a Usenet group the easiest solution is probably to ask ++@uref{http://groups.google.com, groups.google.com}, ++if you found the posting there, tell Google to display ++the raw message, look for the message-id, and say ++@samp{M-^ the@@message.id RET} in a ++summary buffer. ++Since Gnus 5.10 there's also a Gnus interface for ++groups.google.com which you can call with ++@samp{G W}) in group buffer. ++ ++Another idea which works for both mail and news groups ++is to enter the group where the message you are ++searching is and use the standard Emacs search ++@samp{C-s}, it's smart enough to look at ++articles in collapsed threads, too. If you want to ++search bodies, too try @samp{M-s} ++instead. Further on there are the ++gnus-summary-limit-to-foo functions, which can help you, ++too. ++ ++Of course you can also use grep to search through your ++local mail, but this is both slow for big archives and ++inconvenient since you are not displaying the found mail ++in Gnus. Here comes nnir into action. Nnir is a front end ++to search engines like swish-e or swish++ and ++others. You index your mail with one of those search ++engines and with the help of nnir you can search trough ++the indexed mail and generate a temporary group with all ++messages which met your search criteria. If this sound ++cool to you get nnir.el from ++@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/} ++or @uref{ftp://ftp.is.informatik.uni-duisburg.de/pub/src/emacs/}. ++Instructions on how to use it are at the top of the file. ++ ++@node FAQ 6-4 ++@subsubheading Question 6.4 ++ ++How to get rid of old unwanted mail? ++ ++@subsubheading Answer ++ ++You can of course just mark the mail you don't need ++anymore by saying @samp{#} with point ++over the mail and then say @samp{B DEL} ++to get rid of them forever. You could also instead of ++actually deleting them, send them to a junk-group by ++saying @samp{B m nnml:trash-bin} which ++you clear from time to time, but both are not the intended ++way in Gnus. ++ ++In Gnus, we let mail expire like news expires on a news ++server. That means you tell Gnus the message is ++expirable (you tell Gnus "I don't need this mail ++anymore") by saying @samp{E} with point ++over the mail in summary buffer. Now when you leave the ++group, Gnus looks at all messages which you marked as ++expirable before and if they are old enough (default is ++older than a week) they are deleted. ++ ++@node FAQ 6-5 ++@subsubheading Question 6.5 ++ ++I want that all read messages are expired (at least in ++some groups). How to do it? ++ ++@subsubheading Answer ++ ++If you want all read messages to be expired (e.g. in ++mailing lists where there's an online archive), you've ++got two choices: auto-expire and ++total-expire. Auto-expire means, that every article ++which has no marks set and is selected for reading is ++marked as expirable, Gnus hits @samp{E} ++for you every time you read a message. Total-expire ++follows a slightly different approach, here all article ++where the read mark is set are expirable. ++ ++To activate auto-expire, include auto-expire in the ++Group parameters for the group. (Hit @samp{G ++c} in summary buffer with point over the ++group to change group parameters). For total-expire add ++total-expire to the group-parameters. ++ ++Which method you choose is merely a matter of taste: ++Auto-expire is faster, but it doesn't play together with ++Adaptive Scoring, so if you want to use this feature, ++you should use total-expire. ++ ++If you want a message to be excluded from expiration in ++a group where total or auto expire is active, set either ++tick (hit @samp{u}) or dormant mark (hit ++@samp{u}), when you use auto-expire, you ++can also set the read mark (hit ++@samp{d}). ++ ++@node FAQ 6-6 ++@subsubheading Question 6.6 ++ ++I don't want expiration to delete my mails but to move them ++to another group. ++ ++@subsubheading Answer ++ ++Say something like this in ~/.gnus.el: ++ ++@example ++(setq nnmail-expiry-target "nnml:expired") ++@end example ++@noindent ++ ++(If you want to change the value of nnmail-expiry-target ++on a per group basis see the question "How can I disable ++threading in some (e.g. mail-) groups, or set other ++variables specific for some groups?") ++ ++@node FAQ 7 - Gnus in a dial-up environment ++@subsection Gnus in a dial-up environment ++ ++@menu ++* FAQ 7-1:: I don't have a permanent connection to the net, how can I ++ minimize the time I've got to be connected? ++* FAQ 7-2:: So what was this thing about the Agent? ++* FAQ 7-3:: I want to store article bodies on disk, too. How to do ++ it? ++* FAQ 7-4:: How to tell Gnus not to try to send mails / postings ++ while I'm offline? ++@end menu ++ ++@node FAQ 7-1 ++@subsubheading Question 7.1 ++ ++I don't have a permanent connection to the net, how can ++I minimize the time I've got to be connected? ++ ++@subsubheading Answer ++ ++You've got basically two options: Either you use the ++Gnus Agent (see below) for this, or you can install ++programs which fetch your news and mail to your local ++disk and Gnus reads the stuff from your local ++machine. ++ ++If you want to follow the second approach, you need a ++program which fetches news and offers them to Gnus, a ++program which does the same for mail and a program which ++receives the mail you write from Gnus and sends them ++when you're online. ++ ++Let's talk about Unix systems first: For the news part, ++the easiest solution is a small nntp server like ++@uref{http://www.leafnode.org/, Leafnode} or ++@uref{http://infa.abo.fi/~patrik/sn/, sn}, ++of course you can also install a full featured news ++server like ++@uref{http://www.isc.org/products/INN/, inn}. ++Then you want to fetch your Mail, popular choices ++are @uref{http://www.catb.org/~esr/fetchmail/, fetchmail} ++and @uref{http://www.qcc.ca/~charlesc/software/getmail-3.0/, getmail}. ++You should tell those to write the mail to your disk and ++Gnus to read it from there. Last but not least the mail ++sending part: This can be done with every MTA like ++@uref{http://www.sendmail.org/, sendmail}, ++@uref{http://www.qmail.org/, postfix}, ++@uref{http://www.exim.org/, exim} or ++@uref{http://www.qmail.org/, qmail}. ++ ++On windows boxes I'd vote for ++@uref{http://www.tglsoft.de/, Hamster}, ++it's a small freeware, open-source program which fetches ++your mail and news from remote servers and offers them ++to Gnus (or any other mail and/or news reader) via nntp ++respectively POP3 or IMAP. It also includes a smtp ++server for receiving mails from Gnus. ++ ++@node FAQ 7-2 ++@subsubheading Question 7.2 ++ ++So what was this thing about the Agent? ++ ++@subsubheading Answer ++ ++The Gnus agent is part of Gnus, it allows you to fetch ++mail and news and store them on disk for reading them ++later when you're offline. It kind of mimics offline ++newsreaders like e.g. Forte Agent. If you want to use ++the Agent place the following in ~/.gnus.el if you are ++still using 5.8.8 or 5.9 (it's the default since 5.10): ++ ++@example ++(setq gnus-agent t) ++@end example ++@noindent ++ ++Now you've got to select the servers whose groups can be ++stored locally. To do this, open the server buffer ++(that is press @samp{^} while in the ++group buffer). Now select a server by moving point to ++the line naming that server. Finally, agentize the ++server by typing @samp{J a}. If you ++make a mistake, or change your mind, you can undo this ++action by typing @samp{J r}. When ++you're done, type 'q' to return to the group buffer. ++Now the next time you enter a group on a agentized ++server, the headers will be stored on disk and read from ++there the next time you enter the group. ++ ++@node FAQ 7-3 ++@subsubheading Question 7.3 ++ ++I want to store article bodies on disk, too. How to do it? ++ ++@subsubheading Answer ++ ++You can tell the agent to automatically fetch the bodies ++of articles which fulfill certain predicates, this is ++done in a special buffer which can be reached by ++saying @samp{J c} in group ++buffer. Please refer to the documentation for ++information which predicates are possible and how ++exactly to do it. ++ ++Further on you can tell the agent manually which ++articles to store on disk. There are two ways to do ++this: Number one: In the summary buffer, process mark a ++set of articles that shall be stored in the agent by ++saying @samp{#} with point over the ++article and then type @samp{J s}. The ++other possibility is to set, again in the summary ++buffer, downloadable (%) marks for the articles you ++want by typing @samp{@@} with point over ++the article and then typing @samp{J u}. ++What's the difference? Well, process marks are erased as ++soon as you exit the summary buffer while downloadable ++marks are permanent. You can actually set downloadable ++marks in several groups then use fetch session ('J s' in ++the GROUP buffer) to fetch all of those articles. The ++only downside is that fetch session also fetches all of ++the headers for every selected group on an agentized ++server. Depending on the volume of headers, the initial ++fetch session could take hours. ++ ++@node FAQ 7-4 ++@subsubheading Question 7.4 ++ ++How to tell Gnus not to try to send mails / postings ++while I'm offline? ++ ++@subsubheading Answer ++ ++All you've got to do is to tell Gnus when you are online ++(plugged) and when you are offline (unplugged), the rest ++works automatically. You can toggle plugged/unplugged ++state by saying @samp{J j} in group ++buffer. To start Gnus unplugged say @samp{M-x ++gnus-unplugged} instead of ++@samp{M-x gnus}. Note that for this to ++work, the agent must be active. ++ ++@node FAQ 8 - Getting help ++@subsection Getting help ++ ++@menu ++* FAQ 8-1:: How to find information and help inside Emacs? ++* FAQ 8-2:: I can't find anything in the Gnus manual about X (e.g. ++ attachments, PGP, MIME...), is it not documented? ++* FAQ 8-3:: Which websites should I know? ++* FAQ 8-4:: Which mailing lists and newsgroups are there? ++* FAQ 8-5:: Where to report bugs? ++* FAQ 8-6:: I need real-time help, where to find it? ++@end menu ++ ++@node FAQ 8-1 ++@subsubheading Question 8.1 ++ ++How to find information and help inside Emacs? ++ ++@subsubheading Answer ++ ++The first stop should be the Gnus manual (Say ++@samp{C-h i d m Gnus RET} to start the ++Gnus manual, then walk through the menus or do a ++full-text search with @samp{s}). Then ++there are the general Emacs help commands starting with ++C-h, type @samp{C-h ? ?} to get a list ++of all available help commands and their meaning. Finally ++@samp{M-x apropos-command} lets you ++search through all available functions and @samp{M-x ++apropos} searches the bound variables. ++ ++@node FAQ 8-2 ++@subsubheading Question 8.2 ++ ++I can't find anything in the Gnus manual about X ++(e.g. attachments, PGP, MIME...), is it not documented? ++ ++@subsubheading Answer ++ ++There's not only the Gnus manual but also the manuals ++for message, emacs-mime, sieve and pgg. Those packages ++are distributed with Gnus and used by Gnus but aren't ++really part of core Gnus, so they are documented in ++different info files, you should have a look in those ++manuals, too. ++ ++@node FAQ 8-3 ++@subsubheading Question 8.3 ++ ++Which websites should I know? ++ ++@subsubheading Answer ++ ++The two most important ones are the ++@uref{http://www.gnus.org, official Gnus website}. ++and it's sister site ++@uref{http://my.gnus.org, my.gnus.org (MGO)}, ++hosting an archive of lisp snippets, howtos, a (not ++really finished) tutorial and this FAQ. ++ ++Tell me about other sites which are interesting. ++ ++@node FAQ 8-4 ++@subsubheading Question 8.4 ++ ++Which mailing lists and newsgroups are there? ++ ++@subsubheading Answer ++ ++There's the newsgroup gnu.emacs.gnus (also available as ++@uref{http://dir.gmane.org/gmane.emacs.gnus.user, ++gmane.emacs.gnus.user}) which deals with general Gnus ++questions. If you have questions about development versions of ++Gnus, you should better ask on the ding mailing list, see below. ++ ++If you want to stay in the big8, ++news.software.readers is also read by some Gnus ++users (but chances for qualified help are much better in ++the above groups). If you speak German, there's ++de.comm.software.gnus. ++ ++The ding mailing list (ding@@gnus.org) deals with development of ++Gnus. You can read the ding list via NNTP, too under the name ++@uref{http://dir.gmane.org/gmane.emacs.gnus.general, ++gmane.emacs.gnus.general} from news.gmane.org. ++ ++@node FAQ 8-5 ++@subsubheading Question 8.5 ++ ++Where to report bugs? ++ ++@subsubheading Answer ++ ++Say @samp{M-x gnus-bug}, this will start ++a message to the ++@email{bugs@@gnus.org, gnus bug mailing list} ++including information about your environment which make ++it easier to help you. ++ ++@node FAQ 8-6 ++@subsubheading Question 8.6 ++ ++I need real-time help, where to find it? ++ ++@subsubheading Answer ++ ++Point your IRC client to irc.freenode.net, channel #gnus. ++ ++@node FAQ 9 - Tuning Gnus ++@subsection Tuning Gnus ++ ++@menu ++* FAQ 9-1:: Starting Gnus is really slow, how to speed it up? ++* FAQ 9-2:: How to speed up the process of entering a group? ++* FAQ 9-3:: Sending mail becomes slower and slower, what's up? ++@end menu ++ ++@node FAQ 9-1 ++@subsubheading Question 9.1 ++ ++Starting Gnus is really slow, how to speed it up? ++ ++@subsubheading Answer ++ ++The reason for this could be the way Gnus reads it's ++active file, see the node "The Active File" in the Gnus ++manual for things you might try to speed the process up. ++An other idea would be to byte compile your ~/.gnus.el (say ++@samp{M-x byte-compile-file RET ~/.gnus.el ++RET} to do it). Finally, if you have require ++statements in your .gnus, you could replace them with ++eval-after-load, which loads the stuff not at startup ++time, but when it's needed. Say you've got this in your ++~/.gnus.el: ++ ++@example ++(require 'message) ++(add-to-list 'message-syntax-checks '(sender . disabled)) ++@end example ++@noindent ++ ++then as soon as you start Gnus, message.el is loaded. If ++you replace it with ++ ++@example ++(eval-after-load "message" ++ '(add-to-list 'message-syntax-checks '(sender . disabled))) ++@end example ++@noindent ++ ++it's loaded when it's needed. ++ ++@node FAQ 9-2 ++@subsubheading Question 9.2 ++ ++How to speed up the process of entering a group? ++ ++@subsubheading Answer ++ ++A speed killer is setting the variable ++gnus-fetch-old-headers to anything different from nil, ++so don't do this if speed is an issue. To speed up ++building of summary say ++ ++@example ++(gnus-compile) ++@end example ++@noindent ++ ++at the bottom of your ~/.gnus.el, this will make gnus ++byte-compile things like ++gnus-summary-line-format. ++then you could increase the value of gc-cons-threshold ++by saying something like ++ ++@example ++(setq gc-cons-threshold 3500000) ++@end example ++@noindent ++ ++in ~/.emacs. If you don't care about width of CJK ++characters or use Gnus 5.10 or younger together with a ++recent GNU Emacs, you should say ++ ++@example ++(setq gnus-use-correct-string-widths nil) ++@end example ++@noindent ++ ++in ~/.gnus.el (thanks to Jesper harder for the last ++two suggestions). Finally if you are still using 5.8.8 ++or 5.9 and experience speed problems with summary ++buffer generation, you definitely should update to ++5.10 since there quite some work on improving it has ++been done. ++ ++@node FAQ 9-3 ++@subsubheading Question 9.3 ++ ++Sending mail becomes slower and slower, what's up? ++ ++@subsubheading Answer ++ ++The reason could be that you told Gnus to archive the ++messages you wrote by setting ++gnus-message-archive-group. Try to use a nnml group ++instead of an archive group, this should bring you back ++to normal speed. ++ ++@node FAQ - Glossary ++@subsection Glossary ++ ++@table @dfn ++ ++@item ~/.gnus.el ++When the term ~/.gnus.el is used it just means your Gnus ++configuration file. You might as well call it ~/.gnus or ++specify another name. ++ ++@item Back End ++In Gnus terminology a back end is a virtual server, a layer ++between core Gnus and the real NNTP-, POP3-, IMAP- or ++whatever-server which offers Gnus a standardized interface ++to functions like "get message", "get Headers" etc. ++ ++@item Emacs ++When the term Emacs is used in this FAQ, it means either GNU ++Emacs or XEmacs. ++ ++@item Message ++In this FAQ message means a either a mail or a posting to a ++Usenet Newsgroup or to some other fancy back end, no matter ++of which kind it is. ++ ++@item MUA ++MUA is an acronym for Mail User Agent, it's the program you ++use to read and write e-mails. ++ ++@item NUA ++NUA is an acronym for News User Agent, it's the program you ++use to read and write Usenet news. ++ ++@end table ++ ++@ignore ++arch-tag: 64dc5692-edb4-4848-a965-7aa0181acbb8 ++@end ignore +diff --git a/doc/misc/gnus-news.el b/doc/misc/gnus-news.el +new file mode 100644 +index 0000000..05192f1 +--- /dev/null ++++ b/doc/misc/gnus-news.el +@@ -0,0 +1,117 @@ ++;;; gnus-news.el --- a hack to create GNUS-NEWS from texinfo source ++;; Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++ ++;; Author: Reiner Steib ++;; Keywords: tools ++ ++;; This file is part of GNU Emacs. ++ ++;; GNU Emacs 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. ++ ++;; GNU Emacs 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 GNU Emacs. If not, see . ++ ++;;; Commentary: ++ ++;;; Code: ++ ++(defvar gnus-news-header-disclaimer ++"GNUS NEWS -- history of user-visible changes. ++ ++Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, ++ 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++See the end of the file for license conditions. ++ ++Please send Gnus bug reports to bugs@gnus.org. ++For older news, see Gnus info node \"New Features\".\n\n") ++ ++(defvar gnus-news-trailer ++" ++* For older news, see Gnus info node \"New Features\". ++ ++---------------------------------------------------------------------- ++ ++This file is part of GNU Emacs. ++ ++GNU Emacs 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. ++ ++GNU Emacs 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 GNU Emacs. If not, see . ++ ++ \nLocal variables:\nmode: outline ++paragraph-separate: \"[ ]*$\"\nend:\n") ++ ++(defvar gnus-news-makeinfo-command "makeinfo") ++ ++(defvar gnus-news-fill-column 80) ++ ++(defvar gnus-news-makeinfo-switches ++ (concat " --no-headers --paragraph-indent=0" ++ " --no-validate" ;; Allow unresolved references. ++ " --fill-column=" (number-to-string ++ (+ 3 ;; will strip leading spaces later ++ (or gnus-news-fill-column 80))))) ++ ++(defun batch-gnus-news () ++ "Make GNUS-NEWS in batch mode." ++ (let (infile outfile) ++ (setq infile (car command-line-args-left) ++ command-line-args-left (cdr command-line-args-left) ++ outfile (car command-line-args-left) ++ command-line-args-left nil) ++ (if (and infile outfile) ++ (message "Creating `%s' from `%s'..." outfile infile) ++ (error "Not enough files given.")) ++ (gnus-news-translate-file infile outfile))) ++ ++(defun gnus-news-translate-file (infile outfile) ++ "Translate INFILE (texinfo) to OUTFILE (GNUS-NEWS)." ++ (let* ((dir (concat (or (getenv "srcdir") ".") "/")) ++ (infile (concat dir infile)) ++ (buffer (find-file-noselect (concat dir outfile)))) ++ (with-temp-buffer ++ ;; Could be done using `texinfmt' stuff as in `infohack.el'. ++ (insert ++ (shell-command-to-string ++ (concat gnus-news-makeinfo-command " " ++ gnus-news-makeinfo-switches " " infile))) ++ (goto-char (point-max)) ++ (delete-char -1) ++ (goto-char (point-min)) ++ (save-excursion ++ (while (re-search-forward "^ \\* " nil t) ++ (replace-match "\f\n* "))) ++ (save-excursion ++ (while (re-search-forward "^ \\* " nil t) ++ (replace-match "** "))) ++ (save-excursion ++ (while (re-search-forward "^ " nil t) ++ (replace-match ""))) ++ ;; Avoid `*' from @ref at beginning of line: ++ (save-excursion ++ (while (re-search-forward "^\\*Note" nil t) ++ (replace-match " \\&"))) ++ (goto-char (point-min)) ++ (insert gnus-news-header-disclaimer) ++ (goto-char (point-max)) ++ (insert gnus-news-trailer) ++ (write-region (point-min) (point-max) outfile)))) ++ ++;; arch-tag: e23cdd27-eafd-4ba0-816f-98f5edb0dc29 ++;;; gnus-news.el ends here +diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi +new file mode 100644 +index 0000000..09d7be5 +--- /dev/null ++++ b/doc/misc/gnus-news.texi +@@ -0,0 +1,322 @@ ++@c -*-texinfo-*- ++ ++@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. ++ ++@c Permission is granted to anyone to make or distribute verbatim copies ++@c of this document as received, in any medium, provided that the ++@c copyright notice and this permission notice are preserved, ++@c thus giving the recipient permission to redistribute in turn. ++ ++@c Permission is granted to distribute modified versions ++@c of this document, or of portions of it, ++@c under the above conditions, provided also that they ++@c carry prominent notices stating who last changed them. ++ ++@c This file contains a list of news features Gnus. It is supposed to be ++@c included in `gnus.texi'. `GNUS-NEWS' is automatically generated from ++@c this file (see `gnus-news.el'). ++ ++@itemize @bullet ++ ++@item Installation changes ++ ++@itemize @bullet ++@item Upgrading from previous (stable) version if you have used No Gnus. ++ ++If you have tried No Gnus (the unstable Gnus branch leading to this ++release) but went back to a stable version, be careful when upgrading ++to this version. In particular, you will probably want to remove the ++@file{~/News/marks} directory (perhaps selectively), so that flags are ++read from your @file{~/.newsrc.eld} instead of from the stale marks ++file, where this release will store flags for nntp. See a later entry ++for more information about nntp marks. Note that downgrading isn't ++safe in general. ++ ++@item Incompatibility when switching from Emacs 23 to Emacs 22 ++In Emacs 23, Gnus uses Emacs' new internal coding system @code{utf-8-emacs} ++for saving articles drafts and @file{~/.newsrc.eld}. These files may not ++be read correctly in Emacs 22 and below. If you want to use Gnus across ++different Emacs versions, you may set @code{mm-auto-save-coding-system} ++to @code{emacs-mule}. ++@c FIXME: Untested. (Or did anyone test it?) ++@c Cf. http://thread.gmane.org/gmane.emacs.gnus.general/66251/focus=66344 ++ ++@item Lisp files are now installed in @file{.../site-lisp/gnus/} by default. ++It defaulted to @file{.../site-lisp/} formerly. In addition to this, ++the new installer issues a warning if other Gnus installations which ++will shadow the latest one are detected. You can then remove those ++shadows manually or remove them using @code{make ++remove-installed-shadows}. ++ ++@item The installation directory name is allowed to have spaces and/or tabs. ++@end itemize ++ ++@item New packages and libraries within Gnus ++ ++@itemize @bullet ++ ++@item Gnus includes the Emacs Lisp @acronym{SASL} library. ++ ++This provides a clean @acronym{API} to @acronym{SASL} mechanisms from ++within Emacs. The user visible aspects of this, compared to the earlier ++situation, include support for @acronym{DIGEST}-@acronym{MD5} and ++@acronym{NTLM}. @xref{Top, ,Emacs SASL, sasl, Emacs SASL}. ++ ++@item ManageSieve connections uses the @acronym{SASL} library by default. ++ ++The primary change this brings is support for @acronym{DIGEST-MD5} and ++@acronym{NTLM}, when the server supports it. ++ ++@item Gnus includes a password cache mechanism in password.el. ++ ++It is enabled by default (see @code{password-cache}), with a short ++timeout of 16 seconds (see @code{password-cache-expiry}). If ++@acronym{PGG} is used as the @acronym{PGP} back end, the @acronym{PGP} ++passphrase is managed by this mechanism. Passwords for ManageSieve ++connections are managed by this mechanism, after querying the user ++about whether to do so. ++ ++@item Using EasyPG with Gnus ++When EasyPG, is available, Gnus will use it instead of @acronym{PGG}. ++EasyPG is an Emacs user interface to GNU Privacy Guard. @xref{Top, ++,EasyPG Assistant user's manual, epa, EasyPG Assistant user's manual}. ++EasyPG is included in Emacs 23 and available separately as well. ++@end itemize ++ ++@item Changes in group mode ++@c ************************ ++ ++@itemize @bullet ++@item ++Old intermediate incoming mail files (@file{Incoming*}) are deleted ++after a couple of days, not immediately. @xref{Mail Source ++Customization}. ++(New in Gnus 5.10.10 / No Gnus 0.8) ++@c This entry is also present in the node "Oort Gnus". ++ ++@end itemize ++ ++@item Changes in summary and article mode ++ ++@itemize @bullet ++ ++@item Gnus now supports sticky article buffers. Those are article buffers ++that are not reused when you select another article. @xref{Sticky ++Articles}. ++ ++@c @item Bookmarks ++@c FIXME: To be added ++ ++@item Gnus can selectively display @samp{text/html} articles ++with a WWW browser with @kbd{K H}. @xref{MIME Commands}. ++ ++@c gnus-registry-marks ++@c FIXME: To be added ++ ++@item International host names (@acronym{IDNA}) can now be decoded ++inside article bodies using @kbd{W i} ++(@code{gnus-summary-idna-message}). This requires that GNU Libidn ++(@url{http://www.gnu.org/software/libidn/}) has been installed. ++@c FIXME: Also mention @code{message-use-idna}? ++ ++@item The non-@acronym{ASCII} group names handling has been much ++improved. The back ends that fully support non-@acronym{ASCII} group ++names are now @code{nntp}, @code{nnml}, and @code{nnrss}. Also the ++agent, the cache, and the marks features work with those back ends. ++@xref{Non-ASCII Group Names}. ++ ++@item Gnus now displays @acronym{DNS} master files sent as text/dns ++using dns-mode. ++ ++@item Gnus supports new limiting commands in the Summary buffer: ++@kbd{/ r} (@code{gnus-summary-limit-to-replied}) and @kbd{/ R} ++(@code{gnus-summary-limit-to-recipient}). @xref{Limiting}. ++ ++@item You can now fetch all ticked articles from the server using ++@kbd{Y t} (@code{gnus-summary-insert-ticked-articles}). @xref{Summary ++Generation Commands}. ++ ++@item Gnus supports a new sort command in the Summary buffer: ++@kbd{C-c C-s C-t} (@code{gnus-summary-sort-by-recipient}). @xref{Summary ++Sorting}. ++ ++@item @acronym{S/MIME} now features @acronym{LDAP} user certificate searches. ++You need to configure the server in @code{smime-ldap-host-list}. ++ ++@item URLs inside Open@acronym{PGP} headers are retrieved and imported ++to your PGP key ring when you click on them. ++ ++@item ++Picons can be displayed right from the textual address, see ++@code{gnus-picon-style}. @xref{Picons}. ++ ++@item @acronym{ANSI} @acronym{SGR} control sequences can be transformed ++using @kbd{W A}. ++ ++@acronym{ANSI} sequences are used in some Chinese hierarchies for ++highlighting articles (@code{gnus-article-treat-ansi-sequences}). ++ ++@item Gnus now MIME decodes articles even when they lack "MIME-Version" header. ++This changes the default of @code{gnus-article-loose-mime}. ++ ++@item @code{gnus-decay-scores} can be a regexp matching score files. ++For example, set it to @samp{\\.ADAPT\\'} and only adaptive score files ++will be decayed. @xref{Score Decays}. ++ ++@item Strings prefixing to the @code{To} and @code{Newsgroup} headers in ++summary lines when using @code{gnus-ignored-from-addresses} can be ++customized with @code{gnus-summary-to-prefix} and ++@code{gnus-summary-newsgroup-prefix}. @xref{To From Newsgroups}. ++ ++@item You can replace @acronym{MIME} parts with external bodies. ++See @code{gnus-mime-replace-part} and @code{gnus-article-replace-part}. ++@xref{MIME Commands}, @ref{Using MIME}. ++ ++@item ++The option @code{mm-fill-flowed} can be used to disable treatment of ++format=flowed messages. Also, flowed text is disabled when sending ++inline @acronym{PGP} signed messages. @xref{Flowed text, ,Flowed text, ++emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) ++@c This entry is also present in the node "Oort Gnus". ++ ++@item Now the new command @kbd{S W} ++(@code{gnus-article-wide-reply-with-original}) for a wide reply in the ++article buffer yanks a text that is in the active region, if it is set, ++as well as the @kbd{R} (@code{gnus-article-reply-with-original}) command. ++Note that the @kbd{R} command in the article buffer no longer accepts a ++prefix argument, which was used to make it do a wide reply. ++@xref{Article Keymap}. ++ ++@item The new command @kbd{C-h b} ++(@code{gnus-article-describe-bindings}) used in the article buffer now ++shows not only the article commands but also the real summary commands ++that are accessible from the article buffer. ++ ++@end itemize ++ ++@item Changes in Message mode ++ ++@itemize @bullet ++@item Gnus now supports the ``hashcash'' client puzzle anti-spam mechanism. ++Use @code{(setq message-generate-hashcash t)} to enable. ++@xref{Hashcash}. ++ ++@item You can now drag and drop attachments to the Message buffer. ++See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. ++@xref{MIME, ,MIME, message, Message Manual}. ++ ++@item The option @code{message-yank-empty-prefix} now controls how ++empty lines are prefixed in cited text. @xref{Insertion Variables, ++,Insertion Variables, message, Message Manual}. ++ ++@item Gnus uses narrowing to hide headers in Message buffers. ++The @code{References} header is hidden by default. To make all ++headers visible, use @code{(setq message-hidden-headers nil)}. ++@xref{Message Headers, ,Message Headers, message, Message Manual}. ++ ++@item You can highlight different levels of citations like in the ++article buffer. See @code{gnus-message-highlight-citation}. ++ ++@item @code{auto-fill-mode} is enabled by default in Message mode. ++See @code{message-fill-column}. @xref{Various Message Variables, , ++Message Headers, message, Message Manual}. ++ ++@item You can now store signature files in a special directory ++named @code{message-signature-directory}. ++ ++@item The option @code{message-citation-line-format} controls the format ++of the "Whomever writes:" line. You need to set ++@code{message-citation-line-function} to ++@code{message-insert-formatted-citation-line} as well. ++@end itemize ++ ++@item Changes in back ends ++ ++@itemize @bullet ++@item The nntp back end stores article marks in @file{~/News/marks}. ++ ++The directory can be changed using the (customizable) variable ++@code{nntp-marks-directory}, and marks can be disabled using the ++(back end) variable @code{nntp-marks-is-evil}. The advantage of this ++is that you can copy @file{~/News/marks} (using rsync, scp or ++whatever) to another Gnus installation, and it will realize what ++articles you have read and marked. The data in @file{~/News/marks} ++has priority over the same data in @file{~/.newsrc.eld}. ++ ++@item ++You can import and export your @acronym{RSS} subscriptions from ++@acronym{OPML} files. @xref{RSS}. ++ ++@item @acronym{IMAP} identity (@acronym{RFC} 2971) is supported. ++ ++By default, Gnus does not send any information about itself, but you can ++customize it using the variable @code{nnimap-id}. ++ ++@item The @code{nnrss} back end now supports multilingual text. ++Non-@acronym{ASCII} group names for the @code{nnrss} groups are also ++supported. @xref{RSS}. ++ ++@item Retrieving mail with @acronym{POP3} is supported over @acronym{SSL}/@acronym{TLS} and with StartTLS. ++ ++@item The nnml back end allows other compression programs beside @file{gzip} ++for compressed message files. @xref{Mail Spool}. ++ ++@item The nnml back end supports group compaction. ++ ++This feature, accessible via the functions ++@code{gnus-group-compact-group} (@kbd{G z} in the group buffer) and ++@code{gnus-server-compact-server} (@kbd{z} in the server buffer) ++renumbers all articles in a group, starting from 1 and removing gaps. ++As a consequence, you get a correct total article count (until ++messages are deleted again). ++ ++@c @item nnmairix.el ++@c FIXME ++ ++@c @item nnir.el ++@c FIXME ++ ++@end itemize ++ ++@item Appearance ++@c Maybe it's not worth to separate this from "Miscellaneous"? ++ ++@itemize @bullet ++ ++@item The tool bar has been updated to use GNOME icons. ++You can also customize the tool bars: @kbd{M-x customize-apropos RET ++-tool-bar$} should get you started. (Only for Emacs, not in XEmacs.) ++@c FIXME: Document this in the manual ++ ++@item The tool bar icons are now (de)activated correctly ++in the group buffer, see the variable @code{gnus-group-update-tool-bar}. ++Its default value depends on your Emacs version. ++@c FIXME: Document this in the manual ++ ++@item You can change the location of XEmacs' toolbars in Gnus buffers. ++See @code{gnus-use-toolbar} and @code{message-use-toolbar}. ++ ++@end itemize ++ ++@item Miscellaneous changes ++ ++@itemize @bullet ++@item Having edited the select-method for the foreign server in the ++server buffer is immediately reflected to the subscription of the groups ++which use the server in question. For instance, if you change ++@code{nntp-via-address} into @samp{bar.example.com} from ++@samp{foo.example.com}, Gnus will connect to the news host by way of the ++intermediate host @samp{bar.example.com} from next time. ++ ++@item The @file{all.SCORE} file can be edited from the group buffer ++using @kbd{W e}. ++ ++@end itemize ++ ++@end itemize ++ ++@c gnus-news.texi ends here. ++ ++@ignore ++ arch-tag: 872c7569-4340-4d73-9d1d-7826d9f94a51 ++@end ignore +diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi +new file mode 100644 +index 0000000..a7eb081 +--- /dev/null ++++ b/doc/misc/gnus.texi +@@ -0,0 +1,31302 @@ ++\input texinfo ++ ++@setfilename ../../info/gnus ++@settitle Gnus Manual ++@syncodeindex fn cp ++@syncodeindex vr cp ++@syncodeindex pg cp ++ ++@documentencoding ISO-8859-1 ++ ++@copying ++Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, ++2003, 2004, 2005, 2006, 2007, 2008, 2009 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 ++ ++@iftex ++@iflatex ++\documentclass[twoside,a4paper,openright,11pt]{book} ++\usepackage[latin1]{inputenc} ++\usepackage{pagestyle} ++\usepackage{epsfig} ++\usepackage{pixidx} ++\input{gnusconfig.tex} ++ ++\ifx\pdfoutput\undefined ++\else ++\usepackage[pdftex,bookmarks,colorlinks=true]{hyperref} ++\usepackage{thumbpdf} ++\pdfcompresslevel=9 ++\fi ++ ++\makeindex ++\begin{document} ++ ++% Adjust ../Makefile.in if you change the following line: ++\newcommand{\gnusversionname}{Gnus v5.13} ++\newcommand{\gnuschaptername}{} ++\newcommand{\gnussectionname}{} ++ ++\newcommand{\gnusbackslash}{/} ++ ++\newcommand{\gnusref}[1]{``#1'' on page \pageref{#1}} ++\ifx\pdfoutput\undefined ++\newcommand{\gnusuref}[1]{\gnustt{#1}} ++\else ++\newcommand{\gnusuref}[1]{\href{#1}{\gnustt{#1}}} ++\fi ++\newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}} ++\newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}} ++ ++\newcommand{\gnuskindex}[1]{\index{#1}} ++\newcommand{\gnusindex}[1]{\index{#1}} ++ ++\newcommand{\gnustt}[1]{{\gnusselectttfont{}#1}} ++\newcommand{\gnuscode}[1]{\gnustt{#1}} ++\newcommand{\gnusasis}[1]{\gnustt{#1}} ++\newcommand{\gnusurl}[1]{\gnustt{#1}} ++\newcommand{\gnuscommand}[1]{\gnustt{#1}} ++\newcommand{\gnusenv}[1]{\gnustt{#1}} ++\newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\gnusselectttfont{}#1}''} ++\newcommand{\gnuslisp}[1]{\gnustt{#1}} ++\newcommand{\gnuskbd}[1]{`\gnustt{#1}'} ++\newcommand{\gnuskey}[1]{`\gnustt{#1}'} ++\newcommand{\gnusfile}[1]{`\gnustt{#1}'} ++\newcommand{\gnusdfn}[1]{\textit{#1}} ++\newcommand{\gnusi}[1]{\textit{#1}} ++\newcommand{\gnusr}[1]{\textrm{#1}} ++\newcommand{\gnusstrong}[1]{\textbf{#1}} ++\newcommand{\gnusemph}[1]{\textit{#1}} ++\newcommand{\gnusvar}[1]{{\fontsize{10pt}{10}\selectfont\textsl{\textsf{#1}}}} ++\newcommand{\gnussc}[1]{\textsc{#1}} ++\newcommand{\gnustitle}[1]{{\huge\textbf{#1}}} ++\newcommand{\gnusversion}[1]{{\small\textit{#1}}} ++\newcommand{\gnusauthor}[1]{{\large\textbf{#1}}} ++\newcommand{\gnusresult}[1]{\gnustt{=> #1}} ++\newcommand{\gnusacronym}[1]{\textsc{#1}} ++\newcommand{\gnusemail}[1]{\textit{#1}} ++ ++\newcommand{\gnusbullet}{{${\bullet}$}} ++\newcommand{\gnusdollar}{\$} ++\newcommand{\gnusampersand}{\&} ++\newcommand{\gnuspercent}{\%} ++\newcommand{\gnushash}{\#} ++\newcommand{\gnushat}{\symbol{"5E}} ++\newcommand{\gnusunderline}{\symbol{"5F}} ++\newcommand{\gnusnot}{$\neg$} ++\newcommand{\gnustilde}{\symbol{"7E}} ++\newcommand{\gnusless}{{$<$}} ++\newcommand{\gnusgreater}{{$>$}} ++\newcommand{\gnusbraceleft}{{$>$}} ++\newcommand{\gnusbraceright}{{$>$}} ++ ++\newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head,height=1cm}}} ++\newcommand{\gnusinteresting}{ ++\marginpar[\mbox{}\hfill\gnushead]{\gnushead} ++} ++ ++\newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi} ++ ++\newcommand{\gnuspagechapter}[1]{ ++{\mbox{}} ++} ++ ++\newdimen{\gnusdimen} ++\gnusdimen 0pt ++ ++\newcommand{\gnuschapter}[2]{ ++\gnuscleardoublepage ++\ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi ++\chapter{#2} ++\renewcommand{\gnussectionname}{} ++\renewcommand{\gnuschaptername}{#2} ++\thispagestyle{empty} ++\hspace*{-2cm} ++\begin{picture}(500,500)(0,0) ++\put(480,350){\makebox(0,0)[tr]{#1}} ++\put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}} ++\end{picture} ++\clearpage ++} ++ ++\newcommand{\gnusfigure}[3]{ ++\begin{figure} ++\mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2) ++#3 ++\end{picture} ++\caption{#1} ++\end{figure} ++} ++ ++\newcommand{\gnusicon}[1]{ ++\marginpar[\mbox{}\hfill\raisebox{-1.5cm}{\epsfig{figure=ps/#1-up,height=1.5cm}}]{\raisebox{-1cm}{\epsfig{figure=ps/#1-up,height=1cm}}} ++} ++ ++\newcommand{\gnuspicon}[1]{ ++\margindex{\epsfig{figure=#1,width=2cm}} ++} ++ ++\newcommand{\gnusxface}[2]{ ++\margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}} ++} ++ ++\newcommand{\gnussmiley}[2]{ ++\margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}} ++} ++ ++\newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1} ++ ++\newcommand{\gnussection}[1]{ ++\renewcommand{\gnussectionname}{#1} ++\section{#1} ++} ++ ++\newenvironment{codelist}% ++{\begin{list}{}{ ++} ++}{\end{list}} ++ ++\newenvironment{asislist}% ++{\begin{list}{}{ ++} ++}{\end{list}} ++ ++\newenvironment{kbdlist}% ++{\begin{list}{}{ ++\labelwidth=0cm ++} ++}{\end{list}} ++ ++\newenvironment{dfnlist}% ++{\begin{list}{}{ ++} ++}{\end{list}} ++ ++\newenvironment{stronglist}% ++{\begin{list}{}{ ++} ++}{\end{list}} ++ ++\newenvironment{samplist}% ++{\begin{list}{}{ ++} ++}{\end{list}} ++ ++\newenvironment{varlist}% ++{\begin{list}{}{ ++} ++}{\end{list}} ++ ++\newenvironment{emphlist}% ++{\begin{list}{}{ ++} ++}{\end{list}} ++ ++\newlength\gnusheadtextwidth ++\setlength{\gnusheadtextwidth}{\headtextwidth} ++\addtolength{\gnusheadtextwidth}{1cm} ++ ++\newpagestyle{gnuspreamble}% ++{ ++{ ++\ifodd\count0 ++{ ++\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}} ++} ++\else ++{ ++\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}} ++} ++} ++\fi ++} ++} ++{ ++\ifodd\count0 ++\mbox{} \hfill ++\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} ++\else ++\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} ++\hfill \mbox{} ++\fi ++} ++ ++\newpagestyle{gnusindex}% ++{ ++{ ++\ifodd\count0 ++{ ++\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}} ++} ++\else ++{ ++\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}} ++} ++\fi ++} ++} ++{ ++\ifodd\count0 ++\mbox{} \hfill ++\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} ++\else ++\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} ++\hfill \mbox{} ++\fi ++} ++ ++\newpagestyle{gnus}% ++{ ++{ ++\ifodd\count0 ++{ ++\makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}} ++} ++\else ++{ ++\makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}} ++} ++\fi ++} ++} ++{ ++\ifodd\count0 ++\mbox{} \hfill ++\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} ++\else ++\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} ++\hfill \mbox{} ++\fi ++} ++ ++\pagenumbering{roman} ++\pagestyle{gnuspreamble} ++ ++@end iflatex ++@end iftex ++ ++@iftex ++@iflatex ++ ++\begin{titlepage} ++{ ++ ++%\addtolength{\oddsidemargin}{-5cm} ++%\addtolength{\evensidemargin}{-5cm} ++\parindent=0cm ++\addtolength{\textheight}{2cm} ++ ++\gnustitle{\gnustitlename}\hfill\gnusversion{\gnusversionname}\\ ++\rule{15cm}{1mm}\\ ++\vfill ++\hspace*{0cm}\epsfig{figure=ps/gnus-big-logo,height=15cm} ++\vfill ++\rule{15cm}{1mm}\\ ++\gnusauthor{by Lars Magne Ingebrigtsen} ++\newpage ++} ++ ++\mbox{} ++\vfill ++ ++\thispagestyle{empty} ++ ++@c @insertcopying ++\newpage ++\end{titlepage} ++@end iflatex ++@end iftex ++ ++@dircategory Emacs ++@direntry ++* Gnus: (gnus). The newsreader Gnus. ++@end direntry ++@iftex ++@finalout ++@end iftex ++ ++ ++@titlepage ++@title Gnus Manual ++ ++@author by Lars Magne Ingebrigtsen ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@summarycontents ++@contents ++ ++@node Top ++@top The Gnus Newsreader ++ ++@ifinfo ++ ++You can read news (and mail) from within Emacs by using Gnus. The news ++can be gotten by any nefarious means you can think of---@acronym{NNTP}, local ++spool or your mbox file. All at the same time, if you want to push your ++luck. ++ ++@c Adjust ../Makefile.in if you change the following line: ++This manual corresponds to Gnus v5.13 ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@end ifinfo ++ ++@iftex ++ ++@iflatex ++\tableofcontents ++\gnuscleardoublepage ++@end iflatex ++ ++Gnus is the advanced, self-documenting, customizable, extensible ++unreal-time newsreader for GNU Emacs. ++ ++Oops. That sounds oddly familiar, so let's start over again to avoid ++being accused of plagiarism: ++ ++Gnus is a message-reading laboratory. It will let you look at just ++about anything as if it were a newsgroup. You can read mail with it, ++you can browse directories with it, you can @code{ftp} with it---you ++can even read news with it! ++ ++Gnus tries to empower people who read news the same way Emacs empowers ++people who edit text. Gnus sets no limits to what the user should be ++allowed to do. Users are encouraged to extend Gnus to make it behave ++like they want it to behave. A program should not control people; ++people should be empowered to do what they want by using (or abusing) ++the program. ++ ++@c Adjust ../Makefile.in if you change the following line: ++This manual corresponds to Gnus v5.13 ++ ++@heading Other related manuals ++@itemize ++@item Message manual: Composing messages ++@item Emacs-MIME: Composing messages; @acronym{MIME}-specific parts. ++@item Sieve: Managing Sieve scripts in Emacs. ++@item PGG: @acronym{PGP/MIME} with Gnus. ++@item SASL: @acronym{SASL} authentication in Emacs. ++@end itemize ++ ++@end iftex ++ ++@menu ++* Starting Up:: Finding news can be a pain. ++* Group Buffer:: Selecting, subscribing and killing groups. ++* Summary Buffer:: Reading, saving and posting articles. ++* Article Buffer:: Displaying and handling articles. ++* Composing Messages:: Information on sending mail and news. ++* Select Methods:: Gnus reads all messages from various select methods. ++* Scoring:: Assigning values to articles. ++* Various:: General purpose settings. ++* The End:: Farewell and goodbye. ++* Appendices:: Terminology, Emacs intro, @acronym{FAQ}, History, Internals. ++* GNU Free Documentation License:: The license for this documentation. ++* Index:: Variable, function and concept index. ++* Key Index:: Key Index. ++ ++Other related manuals ++ ++* Message:(message). Composing messages. ++* Emacs-MIME:(emacs-mime). Composing messages; @acronym{MIME}-specific parts. ++* Sieve:(sieve). Managing Sieve scripts in Emacs. ++* PGG:(pgg). @acronym{PGP/MIME} with Gnus. ++* SASL:(sasl). @acronym{SASL} authentication in Emacs. ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ ++Starting Gnus ++ ++* Finding the News:: Choosing a method for getting news. ++* The First Time:: What does Gnus do the first time you start it? ++* The Server is Down:: How can I read my mail then? ++* Slave Gnusae:: You can have more than one Gnus active at a time. ++* Fetching a Group:: Starting Gnus just to read a group. ++* New Groups:: What is Gnus supposed to do with new groups? ++* Changing Servers:: You may want to move from one server to another. ++* Startup Files:: Those pesky startup files---@file{.newsrc}. ++* Auto Save:: Recovering from a crash. ++* The Active File:: Reading the active file over a slow line Takes Time. ++* Startup Variables:: Other variables you might change. ++ ++New Groups ++ ++* Checking New Groups:: Determining what groups are new. ++* Subscription Methods:: What Gnus should do with new groups. ++* Filtering New Groups:: Making Gnus ignore certain new groups. ++ ++Group Buffer ++ ++* Group Buffer Format:: Information listed and how you can change it. ++* Group Maneuvering:: Commands for moving in the group buffer. ++* Selecting a Group:: Actually reading news. ++* Subscription Commands:: Unsubscribing, killing, subscribing. ++* Group Data:: Changing the info for a group. ++* Group Levels:: Levels? What are those, then? ++* Group Score:: A mechanism for finding out what groups you like. ++* Marking Groups:: You can mark groups for later processing. ++* Foreign Groups:: Creating and editing groups. ++* Group Parameters:: Each group may have different parameters set. ++* Listing Groups:: Gnus can list various subsets of the groups. ++* Sorting Groups:: Re-arrange the group order. ++* Group Maintenance:: Maintaining a tidy @file{.newsrc} file. ++* Browse Foreign Server:: You can browse a server. See what it has to offer. ++* Exiting Gnus:: Stop reading news and get some work done. ++* Group Topics:: A folding group mode divided into topics. ++* Non-ASCII Group Names:: Accessing groups of non-English names. ++* Misc Group Stuff:: Other stuff that you can to do. ++ ++Group Buffer Format ++ ++* Group Line Specification:: Deciding how the group buffer is to look. ++* Group Mode Line Specification:: The group buffer mode line. ++* Group Highlighting:: Having nice colors in the group buffer. ++ ++Group Topics ++ ++* Topic Commands:: Interactive E-Z commands. ++* Topic Variables:: How to customize the topics the Lisp Way. ++* Topic Sorting:: Sorting each topic individually. ++* Topic Topology:: A map of the world. ++* Topic Parameters:: Parameters that apply to all groups in a topic. ++ ++Misc Group Stuff ++ ++* Scanning New Messages:: Asking Gnus to see whether new messages have arrived. ++* Group Information:: Information and help on groups and Gnus. ++* Group Timestamp:: Making Gnus keep track of when you last read a group. ++* File Commands:: Reading and writing the Gnus files. ++* Sieve Commands:: Managing Sieve scripts. ++ ++Summary Buffer ++ ++* Summary Buffer Format:: Deciding how the summary buffer is to look. ++* Summary Maneuvering:: Moving around the summary buffer. ++* Choosing Articles:: Reading articles. ++* Paging the Article:: Scrolling the current article. ++* Reply Followup and Post:: Posting articles. ++* Delayed Articles:: Send articles at a later time. ++* Marking Articles:: Marking articles as read, expirable, etc. ++* Limiting:: You can limit the summary buffer. ++* Threading:: How threads are made. ++* Sorting the Summary Buffer:: How articles and threads are sorted. ++* Asynchronous Fetching:: Gnus might be able to pre-fetch articles. ++* Article Caching:: You may store articles in a cache. ++* Persistent Articles:: Making articles expiry-resistant. ++* Sticky Articles:: Article buffers that are not reused. ++* Article Backlog:: Having already read articles hang around. ++* Saving Articles:: Ways of customizing article saving. ++* Decoding Articles:: Gnus can treat series of (uu)encoded articles. ++* Article Treatment:: The article buffer can be mangled at will. ++* MIME Commands:: Doing MIMEy things with the articles. ++* Charsets:: Character set issues. ++* Article Commands:: Doing various things with the article buffer. ++* Summary Sorting:: Sorting the summary buffer in various ways. ++* Finding the Parent:: No child support? Get the parent. ++* Alternative Approaches:: Reading using non-default summaries. ++* Tree Display:: A more visual display of threads. ++* Mail Group Commands:: Some commands can only be used in mail groups. ++* Various Summary Stuff:: What didn't fit anywhere else. ++* Exiting the Summary Buffer:: Returning to the Group buffer, ++ or reselecting the current group. ++* Crosspost Handling:: How crossposted articles are dealt with. ++* Duplicate Suppression:: An alternative when crosspost handling fails. ++* Security:: Decrypt and Verify. ++* Mailing List:: Mailing list minor mode. ++ ++Summary Buffer Format ++ ++* Summary Buffer Lines:: You can specify how summary lines should look. ++* To From Newsgroups:: How to not display your own name. ++* Summary Buffer Mode Line:: You can say how the mode line should look. ++* Summary Highlighting:: Making the summary buffer all pretty and nice. ++ ++Choosing Articles ++ ++* Choosing Commands:: Commands for choosing articles. ++* Choosing Variables:: Variables that influence these commands. ++ ++Reply, Followup and Post ++ ++* Summary Mail Commands:: Sending mail. ++* Summary Post Commands:: Sending news. ++* Summary Message Commands:: Other Message-related commands. ++* Canceling and Superseding:: ++ ++Marking Articles ++ ++* Unread Articles:: Marks for unread articles. ++* Read Articles:: Marks for read articles. ++* Other Marks:: Marks that do not affect readedness. ++* Setting Marks:: How to set and remove marks. ++* Generic Marking Commands:: How to customize the marking. ++* Setting Process Marks:: How to mark articles for later processing. ++ ++Threading ++ ++* Customizing Threading:: Variables you can change to affect the threading. ++* Thread Commands:: Thread based commands in the summary buffer. ++ ++Customizing Threading ++ ++* Loose Threads:: How Gnus gathers loose threads into bigger threads. ++* Filling In Threads:: Making the threads displayed look fuller. ++* More Threading:: Even more variables for fiddling with threads. ++* Low-Level Threading:: You thought it was over@dots{} but you were wrong! ++ ++Decoding Articles ++ ++* Uuencoded Articles:: Uudecode articles. ++* Shell Archives:: Unshar articles. ++* PostScript Files:: Split PostScript. ++* Other Files:: Plain save and binhex. ++* Decoding Variables:: Variables for a happy decoding. ++* Viewing Files:: You want to look at the result of the decoding? ++ ++Decoding Variables ++ ++* Rule Variables:: Variables that say how a file is to be viewed. ++* Other Decode Variables:: Other decode variables. ++* Uuencoding and Posting:: Variables for customizing uuencoding. ++ ++Article Treatment ++ ++* Article Highlighting:: You want to make the article look like fruit salad. ++* Article Fontisizing:: Making emphasized text look nice. ++* Article Hiding:: You also want to make certain info go away. ++* Article Washing:: Lots of way-neat functions to make life better. ++* Article Header:: Doing various header transformations. ++* Article Buttons:: Click on URLs, Message-IDs, addresses and the like. ++* Article Button Levels:: Controlling appearance of buttons. ++* Article Date:: Grumble, UT! ++* Article Display:: Display various stuff---X-Face, Picons, Smileys ++* Article Signature:: What is a signature? ++* Article Miscellanea:: Various other stuff. ++ ++Alternative Approaches ++ ++* Pick and Read:: First mark articles and then read them. ++* Binary Groups:: Auto-decode all articles. ++ ++Various Summary Stuff ++ ++* Summary Group Information:: Information oriented commands. ++* Searching for Articles:: Multiple article commands. ++* Summary Generation Commands:: ++* Really Various Summary Commands:: Those pesky non-conformant commands. ++ ++Article Buffer ++ ++* Hiding Headers:: Deciding what headers should be displayed. ++* Using MIME:: Pushing articles through @acronym{MIME} before reading them. ++* Customizing Articles:: Tailoring the look of the articles. ++* Article Keymap:: Keystrokes available in the article buffer. ++* Misc Article:: Other stuff. ++ ++Composing Messages ++ ++* Mail:: Mailing and replying. ++* Posting Server:: What server should you post and mail via? ++* POP before SMTP:: You cannot send a mail unless you read a mail. ++* Mail and Post:: Mailing and posting at the same time. ++* Archived Messages:: Where Gnus stores the messages you've sent. ++* Posting Styles:: An easier way to specify who you are. ++* Drafts:: Postponing messages and rejected messages. ++* Rejected Articles:: What happens if the server doesn't like your article? ++* Signing and encrypting:: How to compose secure messages. ++ ++Select Methods ++ ++* Server Buffer:: Making and editing virtual servers. ++* Getting News:: Reading USENET news with Gnus. ++* Getting Mail:: Reading your personal mail with Gnus. ++* Browsing the Web:: Getting messages from a plethora of Web sources. ++* IMAP:: Using Gnus as a @acronym{IMAP} client. ++* Other Sources:: Reading directories, files, SOUP packets. ++* Combined Groups:: Combining groups into one group. ++* Email Based Diary:: Using mails to manage diary events in Gnus. ++* Gnus Unplugged:: Reading news and mail offline. ++ ++Server Buffer ++ ++* Server Buffer Format:: You can customize the look of this buffer. ++* Server Commands:: Commands to manipulate servers. ++* Example Methods:: Examples server specifications. ++* Creating a Virtual Server:: An example session. ++* Server Variables:: Which variables to set. ++* Servers and Methods:: You can use server names as select methods. ++* Unavailable Servers:: Some servers you try to contact may be down. ++ ++Getting News ++ ++* NNTP:: Reading news from an @acronym{NNTP} server. ++* News Spool:: Reading news from the local spool. ++ ++@acronym{NNTP} ++ ++* Direct Functions:: Connecting directly to the server. ++* Indirect Functions:: Connecting indirectly to the server. ++* Common Variables:: Understood by several connection functions. ++* NNTP marks:: Storing marks for @acronym{NNTP} servers. ++ ++Getting Mail ++ ++* Mail in a Newsreader:: Important introductory notes. ++* Getting Started Reading Mail:: A simple cookbook example. ++* Splitting Mail:: How to create mail groups. ++* Mail Sources:: How to tell Gnus where to get mail from. ++* Mail Back End Variables:: Variables for customizing mail handling. ++* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. ++* Group Mail Splitting:: Use group customize to drive mail splitting. ++* Incorporating Old Mail:: What about the old mail you have? ++* Expiring Mail:: Getting rid of unwanted mail. ++* Washing Mail:: Removing cruft from the mail you get. ++* Duplicates:: Dealing with duplicated mail. ++* Not Reading Mail:: Using mail back ends for reading other files. ++* Choosing a Mail Back End:: Gnus can read a variety of mail formats. ++ ++Mail Sources ++ ++* Mail Source Specifiers:: How to specify what a mail source is. ++* Mail Source Customization:: Some variables that influence things. ++* Fetching Mail:: Using the mail source specifiers. ++ ++Choosing a Mail Back End ++ ++* Unix Mail Box:: Using the (quite) standard Un*x mbox. ++* Babyl:: Babyl was used by older versions of Rmail. ++* Mail Spool:: Store your mail in a private spool? ++* MH Spool:: An mhspool-like back end. ++* Maildir:: Another one-file-per-message format. ++* Mail Folders:: Having one file for each group. ++* Comparing Mail Back Ends:: An in-depth looks at pros and cons. ++ ++Browsing the Web ++ ++* Archiving Mail:: ++* Web Searches:: Creating groups from articles that match a string. ++* Slashdot:: Reading the Slashdot comments. ++* Ultimate:: The Ultimate Bulletin Board systems. ++* Web Archive:: Reading mailing list archived on web. ++* RSS:: Reading RDF site summary. ++* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. ++ ++@acronym{IMAP} ++ ++* Splitting in IMAP:: Splitting mail with nnimap. ++* Expiring in IMAP:: Expiring mail with nnimap. ++* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. ++* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button. ++* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus. ++* Debugging IMAP:: What to do when things don't work. ++ ++Other Sources ++ ++* Directory Groups:: You can read a directory as if it was a newsgroup. ++* Anything Groups:: Dired? Who needs dired? ++* Document Groups:: Single files can be the basis of a group. ++* SOUP:: Reading @sc{soup} packets ``offline''. ++* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. ++ ++Document Groups ++ ++* Document Server Internals:: How to add your own document types. ++ ++SOUP ++ ++* SOUP Commands:: Commands for creating and sending @sc{soup} packets ++* SOUP Groups:: A back end for reading @sc{soup} packets. ++* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news. ++ ++Combined Groups ++ ++* Virtual Groups:: Combining articles from many groups. ++* Kibozed Groups:: Looking through parts of the newsfeed for articles. ++ ++Email Based Diary ++ ++* The NNDiary Back End:: Basic setup and usage. ++* The Gnus Diary Library:: Utility toolkit on top of nndiary. ++* Sending or Not Sending:: A final note on sending diary messages. ++ ++The NNDiary Back End ++ ++* Diary Messages:: What makes a message valid for nndiary. ++* Running NNDiary:: NNDiary has two modes of operation. ++* Customizing NNDiary:: Bells and whistles. ++ ++The Gnus Diary Library ++ ++* Diary Summary Line Format:: A nicer summary buffer line format. ++* Diary Articles Sorting:: A nicer way to sort messages. ++* Diary Headers Generation:: Not doing it manually. ++* Diary Group Parameters:: Not handling them manually. ++ ++Gnus Unplugged ++ ++* Agent Basics:: How it all is supposed to work. ++* Agent Categories:: How to tell the Gnus Agent what to download. ++* Agent Commands:: New commands for all the buffers. ++* Agent Visuals:: Ways that the agent may effect your summary buffer. ++* Agent as Cache:: The Agent is a big cache too. ++* Agent Expiry:: How to make old articles go away. ++* Agent Regeneration:: How to recover from lost connections and other accidents. ++* Agent and flags:: How the Agent maintains flags. ++* Agent and IMAP:: How to use the Agent with @acronym{IMAP}. ++* Outgoing Messages:: What happens when you post/mail something? ++* Agent Variables:: Customizing is fun. ++* Example Setup:: An example @file{~/.gnus.el} file for offline people. ++* Batching Agents:: How to fetch news from a @code{cron} job. ++* Agent Caveats:: What you think it'll do and what it does. ++ ++Agent Categories ++ ++* Category Syntax:: What a category looks like. ++* Category Buffer:: A buffer for maintaining categories. ++* Category Variables:: Customize'r'Us. ++ ++Agent Commands ++ ++* Group Agent Commands:: Configure groups and fetch their contents. ++* Summary Agent Commands:: Manually select then fetch specific articles. ++* Server Agent Commands:: Select the servers that are supported by the agent. ++ ++Scoring ++ ++* Summary Score Commands:: Adding score entries for the current group. ++* Group Score Commands:: General score commands. ++* Score Variables:: Customize your scoring. (My, what terminology). ++* Score File Format:: What a score file may contain. ++* Score File Editing:: You can edit score files by hand as well. ++* Adaptive Scoring:: Big Sister Gnus knows what you read. ++* Home Score File:: How to say where new score entries are to go. ++* Followups To Yourself:: Having Gnus notice when people answer you. ++* Scoring On Other Headers:: Scoring on non-standard headers. ++* Scoring Tips:: How to score effectively. ++* Reverse Scoring:: That problem child of old is not problem. ++* Global Score Files:: Earth-spanning, ear-splitting score files. ++* Kill Files:: They are still here, but they can be ignored. ++* Converting Kill Files:: Translating kill files to score files. ++* Advanced Scoring:: Using logical expressions to build score rules. ++* Score Decays:: It can be useful to let scores wither away. ++ ++Advanced Scoring ++ ++* Advanced Scoring Syntax:: A definition. ++* Advanced Scoring Examples:: What they look like. ++* Advanced Scoring Tips:: Getting the most out of it. ++ ++Various ++ ++* Process/Prefix:: A convention used by many treatment commands. ++* Interactive:: Making Gnus ask you many questions. ++* Symbolic Prefixes:: How to supply some Gnus functions with options. ++* Formatting Variables:: You can specify what buffers should look like. ++* Window Layout:: Configuring the Gnus buffer windows. ++* Faces and Fonts:: How to change how faces look. ++* Compilation:: How to speed Gnus up. ++* Mode Lines:: Displaying information in the mode lines. ++* Highlighting and Menus:: Making buffers look all nice and cozy. ++* Buttons:: Get tendinitis in ten easy steps! ++* Daemons:: Gnus can do things behind your back. ++* NoCeM:: How to avoid spam and other fatty foods. ++* Undo:: Some actions can be undone. ++* Predicate Specifiers:: Specifying predicates. ++* Moderation:: What to do if you're a moderator. ++* Image Enhancements:: Modern versions of Emacs/XEmacs can display images. ++* Fuzzy Matching:: What's the big fuzz? ++* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. ++* Spam Package:: A package for filtering and processing spam. ++* The Gnus Registry:: A package for tracking messages by Message-ID. ++* Other modes:: Interaction with other modes. ++* Various Various:: Things that are really various. ++ ++Formatting Variables ++ ++* Formatting Basics:: A formatting variable is basically a format string. ++* Mode Line Formatting:: Some rules about mode line formatting variables. ++* Advanced Formatting:: Modifying output in various ways. ++* User-Defined Specs:: Having Gnus call your own functions. ++* Formatting Fonts:: Making the formatting look colorful and nice. ++* Positioning Point:: Moving point to a position after an operation. ++* Tabulation:: Tabulating your output. ++* Wide Characters:: Dealing with wide characters. ++ ++Image Enhancements ++ ++* X-Face:: Display a funky, teensy black-and-white image. ++* Face:: Display a funkier, teensier colored image. ++* Smileys:: Show all those happy faces the way they were ++ meant to be shown. ++* Picons:: How to display pictures of what you're reading. ++* XVarious:: Other XEmacsy Gnusey variables. ++ ++Thwarting Email Spam ++ ++* The problem of spam:: Some background, and some solutions ++* Anti-Spam Basics:: Simple steps to reduce the amount of spam. ++* SpamAssassin:: How to use external anti-spam tools. ++* Hashcash:: Reduce spam by burning CPU time. ++ ++Spam Package ++ ++* Spam Package Introduction:: ++* Filtering Incoming Mail:: ++* Detecting Spam in Groups:: ++* Spam and Ham Processors:: ++* Spam Package Configuration Examples:: ++* Spam Back Ends:: ++* Extending the Spam package:: ++* Spam Statistics Package:: ++ ++Spam Statistics Package ++ ++* Creating a spam-stat dictionary:: ++* Splitting mail using spam-stat:: ++* Low-level interface to the spam-stat dictionary:: ++ ++Appendices ++ ++* XEmacs:: Requirements for installing under XEmacs. ++* History:: How Gnus got where it is today. ++* On Writing Manuals:: Why this is not a beginner's guide. ++* Terminology:: We use really difficult, like, words here. ++* Customization:: Tailoring Gnus to your needs. ++* Troubleshooting:: What you might try if things do not work. ++* Gnus Reference Guide:: Rilly, rilly technical stuff. ++* Emacs for Heathens:: A short introduction to Emacsian terms. ++* Frequently Asked Questions:: The Gnus FAQ ++ ++History ++ ++* Gnus Versions:: What Gnus versions have been released. ++* Other Gnus Versions:: Other Gnus versions that also have been released. ++* Why?:: What's the point of Gnus? ++* Compatibility:: Just how compatible is Gnus with @sc{gnus}? ++* Conformity:: Gnus tries to conform to all standards. ++* Emacsen:: Gnus can be run on a few modern Emacsen. ++* Gnus Development:: How Gnus is developed. ++* Contributors:: Oodles of people. ++* New Features:: Pointers to some of the new stuff in Gnus. ++ ++New Features ++ ++* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. ++* September Gnus:: The Thing Formally Known As Gnus 5.2/5.3. ++* Red Gnus:: Third time best---Gnus 5.4/5.5. ++* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7. ++* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9. ++* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11. ++* No Gnus:: Very punny. ++ ++Customization ++ ++* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. ++* Slow Terminal Connection:: You run a remote Emacs. ++* Little Disk Space:: You feel that having large setup files is icky. ++* Slow Machine:: You feel like buying a faster machine. ++ ++Gnus Reference Guide ++ ++* Gnus Utility Functions:: Common functions and variable to use. ++* Back End Interface:: How Gnus communicates with the servers. ++* Score File Syntax:: A BNF definition of the score file standard. ++* Headers:: How Gnus stores headers internally. ++* Ranges:: A handy format for storing mucho numbers. ++* Group Info:: The group info format. ++* Extended Interactive:: Symbolic prefixes and stuff. ++* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. ++* Various File Formats:: Formats of files that Gnus use. ++ ++Back End Interface ++ ++* Required Back End Functions:: Functions that must be implemented. ++* Optional Back End Functions:: Functions that need not be implemented. ++* Error Messaging:: How to get messages and report errors. ++* Writing New Back Ends:: Extending old back ends. ++* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end. ++* Mail-like Back Ends:: Some tips on mail back ends. ++ ++Various File Formats ++ ++* Active File Format:: Information on articles and groups available. ++* Newsgroups File Format:: Group descriptions. ++ ++Emacs for Heathens ++ ++* Keystrokes:: Entering text and executing commands. ++* Emacs Lisp:: The built-in Emacs programming language. ++ ++@end detailmenu ++@end menu ++ ++@node Starting Up ++@chapter Starting Gnus ++@cindex starting up ++ ++If you haven't used Emacs much before using Gnus, read @ref{Emacs for ++Heathens} first. ++ ++@kindex M-x gnus ++@findex gnus ++If your system administrator has set things up properly, starting Gnus ++and reading news is extremely easy---you just type @kbd{M-x gnus} in ++your Emacs. If not, you should customize the variable ++@code{gnus-select-method} as described in @ref{Finding the News}. For a ++minimal setup for posting should also customize the variables ++@code{user-full-name} and @code{user-mail-address}. ++ ++@findex gnus-other-frame ++@kindex M-x gnus-other-frame ++If you want to start Gnus in a different frame, you can use the command ++@kbd{M-x gnus-other-frame} instead. ++ ++If things do not go smoothly at startup, you have to twiddle some ++variables in your @file{~/.gnus.el} file. This file is similar to ++@file{~/.emacs}, but is read when Gnus starts. ++ ++If you puzzle at any terms used in this manual, please refer to the ++terminology section (@pxref{Terminology}). ++ ++@menu ++* Finding the News:: Choosing a method for getting news. ++* The First Time:: What does Gnus do the first time you start it? ++* The Server is Down:: How can I read my mail then? ++* Slave Gnusae:: You can have more than one Gnus active at a time. ++* New Groups:: What is Gnus supposed to do with new groups? ++* Changing Servers:: You may want to move from one server to another. ++* Startup Files:: Those pesky startup files---@file{.newsrc}. ++* Auto Save:: Recovering from a crash. ++* The Active File:: Reading the active file over a slow line Takes Time. ++* Startup Variables:: Other variables you might change. ++@end menu ++ ++ ++@node Finding the News ++@section Finding the News ++@cindex finding news ++ ++@vindex gnus-select-method ++@c @head ++The @code{gnus-select-method} variable says where Gnus should look for ++news. This variable should be a list where the first element says ++@dfn{how} and the second element says @dfn{where}. This method is your ++native method. All groups not fetched with this method are ++foreign groups. ++ ++For instance, if the @samp{news.somewhere.edu} @acronym{NNTP} server is where ++you want to get your daily dosage of news from, you'd say: ++ ++@lisp ++(setq gnus-select-method '(nntp "news.somewhere.edu")) ++@end lisp ++ ++If you want to read directly from the local spool, say: ++ ++@lisp ++(setq gnus-select-method '(nnspool "")) ++@end lisp ++ ++If you can use a local spool, you probably should, as it will almost ++certainly be much faster. But do not use the local spool if your ++server is running Leafnode (which is a simple, standalone private news ++server); in this case, use @code{(nntp "localhost")}. ++ ++@vindex gnus-nntpserver-file ++@cindex NNTPSERVER ++@cindex @acronym{NNTP} server ++If this variable is not set, Gnus will take a look at the ++@env{NNTPSERVER} environment variable. If that variable isn't set, ++Gnus will see whether @code{gnus-nntpserver-file} ++(@file{/etc/nntpserver} by default) has any opinions on the matter. ++If that fails as well, Gnus will try to use the machine running Emacs ++as an @acronym{NNTP} server. That's a long shot, though. ++ ++@vindex gnus-nntp-server ++If @code{gnus-nntp-server} is set, this variable will override ++@code{gnus-select-method}. You should therefore set ++@code{gnus-nntp-server} to @code{nil}, which is what it is by default. ++ ++@vindex gnus-secondary-servers ++@vindex gnus-nntp-server ++You can also make Gnus prompt you interactively for the name of an ++@acronym{NNTP} server. If you give a non-numerical prefix to @code{gnus} ++(i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers ++in the @code{gnus-secondary-servers} list (if any). You can also just ++type in the name of any server you feel like visiting. (Note that this ++will set @code{gnus-nntp-server}, which means that if you then @kbd{M-x ++gnus} later in the same Emacs session, Gnus will contact the same ++server.) ++ ++@findex gnus-group-browse-foreign-server ++@kindex B (Group) ++However, if you use one @acronym{NNTP} server regularly and are just ++interested in a couple of groups from a different server, you would be ++better served by using the @kbd{B} command in the group buffer. It will ++let you have a look at what groups are available, and you can subscribe ++to any of the groups you want to. This also makes @file{.newsrc} ++maintenance much tidier. @xref{Foreign Groups}. ++ ++@vindex gnus-secondary-select-methods ++@c @head ++A slightly different approach to foreign groups is to set the ++@code{gnus-secondary-select-methods} variable. The select methods ++listed in this variable are in many ways just as native as the ++@code{gnus-select-method} server. They will also be queried for active ++files during startup (if that's required), and new newsgroups that ++appear on these servers will be subscribed (or not) just as native ++groups are. ++ ++For instance, if you use the @code{nnmbox} back end to read your mail, ++you would typically set this variable to ++ ++@lisp ++(setq gnus-secondary-select-methods '((nnmbox ""))) ++@end lisp ++ ++Note: the @acronym{NNTP} back end stores marks in marks files ++(@pxref{NNTP marks}). This feature makes it easy to share marks between ++several Gnus installations, but may slow down things a bit when fetching ++new articles. @xref{NNTP marks}, for more information. ++ ++ ++@node The First Time ++@section The First Time ++@cindex first time usage ++ ++If no startup files exist (@pxref{Startup Files}), Gnus will try to ++determine what groups should be subscribed by default. ++ ++@vindex gnus-default-subscribed-newsgroups ++If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus ++will subscribe you to just those groups in that list, leaving the rest ++killed. Your system administrator should have set this variable to ++something useful. ++ ++Since she hasn't, Gnus will just subscribe you to a few arbitrarily ++picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is defined ++here as @dfn{whatever Lars thinks you should read}.) ++ ++You'll also be subscribed to the Gnus documentation group, which should ++help you with most common problems. ++ ++If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just ++use the normal functions for handling new groups, and not do anything ++special. ++ ++ ++@node The Server is Down ++@section The Server is Down ++@cindex server errors ++ ++If the default server is down, Gnus will understandably have some ++problems starting. However, if you have some mail groups in addition to ++the news groups, you may want to start Gnus anyway. ++ ++Gnus, being the trusting sort of program, will ask whether to proceed ++without a native select method if that server can't be contacted. This ++will happen whether the server doesn't actually exist (i.e., you have ++given the wrong address) or the server has just momentarily taken ill ++for some reason or other. If you decide to continue and have no foreign ++groups, you'll find it difficult to actually do anything in the group ++buffer. But, hey, that's your problem. Blllrph! ++ ++@findex gnus-no-server ++@kindex M-x gnus-no-server ++@c @head ++If you know that the server is definitely down, or you just want to read ++your mail without bothering with the server at all, you can use the ++@code{gnus-no-server} command to start Gnus. That might come in handy ++if you're in a hurry as well. This command will not attempt to contact ++your primary server---instead, it will just activate all groups on level ++1 and 2. (You should preferably keep no native groups on those two ++levels.) Also @pxref{Group Levels}. ++ ++ ++@node Slave Gnusae ++@section Slave Gnusae ++@cindex slave ++ ++You might want to run more than one Emacs with more than one Gnus at the ++same time. If you are using different @file{.newsrc} files (e.g., if you ++are using the two different Gnusae to read from two different servers), ++that is no problem whatsoever. You just do it. ++ ++The problem appears when you want to run two Gnusae that use the same ++@file{.newsrc} file. ++ ++To work around that problem some, we here at the Think-Tank at the Gnus ++Towers have come up with a new concept: @dfn{Masters} and ++@dfn{slaves}. (We have applied for a patent on this concept, and have ++taken out a copyright on those words. If you wish to use those words in ++conjunction with each other, you have to send $1 per usage instance to ++me. Usage of the patent (@dfn{Master/Slave Relationships In Computer ++Applications}) will be much more expensive, of course.) ++ ++@findex gnus-slave ++Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or ++however you do it). Each subsequent slave Gnusae should be started with ++@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc} ++files, but instead save @dfn{slave files} that contain information only ++on what groups have been read in the slave session. When a master Gnus ++starts, it will read (and delete) these slave files, incorporating all ++information from them. (The slave files will be read in the sequence ++they were created, so the latest changes will have precedence.) ++ ++Information from the slave files has, of course, precedence over the ++information in the normal (i.e., master) @file{.newsrc} file. ++ ++If the @file{.newsrc*} files have not been saved in the master when the ++slave starts, you may be prompted as to whether to read an auto-save ++file. If you answer ``yes'', the unsaved changes to the master will be ++incorporated into the slave. If you answer ``no'', the slave may see some ++messages as unread that have been read in the master. ++ ++ ++ ++@node New Groups ++@section New Groups ++@cindex new groups ++@cindex subscription ++ ++@vindex gnus-check-new-newsgroups ++If you are satisfied that you really never want to see any new groups, ++you can set @code{gnus-check-new-newsgroups} to @code{nil}. This will ++also save you some time at startup. Even if this variable is ++@code{nil}, you can always subscribe to the new groups just by pressing ++@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable ++is @code{ask-server} by default. If you set this variable to ++@code{always}, then Gnus will query the back ends for new groups even ++when you do the @kbd{g} command (@pxref{Scanning New Messages}). ++ ++@menu ++* Checking New Groups:: Determining what groups are new. ++* Subscription Methods:: What Gnus should do with new groups. ++* Filtering New Groups:: Making Gnus ignore certain new groups. ++@end menu ++ ++ ++@node Checking New Groups ++@subsection Checking New Groups ++ ++Gnus normally determines whether a group is new or not by comparing the ++list of groups from the active file(s) with the lists of subscribed and ++dead groups. This isn't a particularly fast method. If ++@code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the ++server for new groups since the last time. This is both faster and ++cheaper. This also means that you can get rid of the list of killed ++groups altogether, so you may set @code{gnus-save-killed-list} to ++@code{nil}, which will save time both at startup, at exit, and all over. ++Saves disk space, too. Why isn't this the default, then? ++Unfortunately, not all servers support this command. ++ ++I bet I know what you're thinking now: How do I find out whether my ++server supports @code{ask-server}? No? Good, because I don't have a ++fail-safe answer. I would suggest just setting this variable to ++@code{ask-server} and see whether any new groups appear within the next ++few days. If any do, then it works. If none do, then it doesn't ++work. I could write a function to make Gnus guess whether the server ++supports @code{ask-server}, but it would just be a guess. So I won't. ++You could @code{telnet} to the server and say @code{HELP} and see ++whether it lists @samp{NEWGROUPS} among the commands it understands. If ++it does, then it might work. (But there are servers that lists ++@samp{NEWGROUPS} without supporting the function properly.) ++ ++This variable can also be a list of select methods. If so, Gnus will ++issue an @code{ask-server} command to each of the select methods, and ++subscribe them (or not) using the normal methods. This might be handy ++if you are monitoring a few servers for new groups. A side effect is ++that startup will take much longer, so you can meditate while waiting. ++Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss. ++ ++ ++@node Subscription Methods ++@subsection Subscription Methods ++ ++@vindex gnus-subscribe-newsgroup-method ++What Gnus does when it encounters a new group is determined by the ++@code{gnus-subscribe-newsgroup-method} variable. ++ ++This variable should contain a function. This function will be called ++with the name of the new group as the only parameter. ++ ++Some handy pre-fab functions are: ++ ++@table @code ++ ++@item gnus-subscribe-zombies ++@vindex gnus-subscribe-zombies ++Make all new groups zombies. This is the default. You can browse the ++zombies later (with @kbd{A z}) and either kill them all off properly ++(with @kbd{S z}), or subscribe to them (with @kbd{u}). ++ ++@item gnus-subscribe-randomly ++@vindex gnus-subscribe-randomly ++Subscribe all new groups in arbitrary order. This really means that all ++new groups will be added at ``the top'' of the group buffer. ++ ++@item gnus-subscribe-alphabetically ++@vindex gnus-subscribe-alphabetically ++Subscribe all new groups in alphabetical order. ++ ++@item gnus-subscribe-hierarchically ++@vindex gnus-subscribe-hierarchically ++Subscribe all new groups hierarchically. The difference between this ++function and @code{gnus-subscribe-alphabetically} is slight. ++@code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly ++alphabetical fashion, while this function will enter groups into its ++hierarchy. So if you want to have the @samp{rec} hierarchy before the ++@samp{comp} hierarchy, this function will not mess that configuration ++up. Or something like that. ++ ++@item gnus-subscribe-interactively ++@vindex gnus-subscribe-interactively ++Subscribe new groups interactively. This means that Gnus will ask ++you about @strong{all} new groups. The groups you choose to subscribe ++to will be subscribed hierarchically. ++ ++@item gnus-subscribe-killed ++@vindex gnus-subscribe-killed ++Kill all new groups. ++ ++@item gnus-subscribe-topics ++@vindex gnus-subscribe-topics ++Put the groups into the topic that has a matching @code{subscribe} topic ++parameter (@pxref{Topic Parameters}). For instance, a @code{subscribe} ++topic parameter that looks like ++ ++@example ++"nnslashdot" ++@end example ++ ++will mean that all groups that match that regex will be subscribed under ++that topic. ++ ++If no topics match the groups, the groups will be subscribed in the ++top-level topic. ++ ++@end table ++ ++@vindex gnus-subscribe-hierarchical-interactive ++A closely related variable is ++@code{gnus-subscribe-hierarchical-interactive}. (That's quite a ++mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a ++hierarchical fashion whether to subscribe to new groups or not. Gnus ++will ask you for each sub-hierarchy whether you want to descend the ++hierarchy or not. ++ ++One common mistake is to set the variable a few paragraphs above ++(@code{gnus-subscribe-newsgroup-method}) to ++@code{gnus-subscribe-hierarchical-interactive}. This is an error. This ++will not work. This is ga-ga. So don't do it. ++ ++ ++@node Filtering New Groups ++@subsection Filtering New Groups ++ ++A nice and portable way to control which new newsgroups should be ++subscribed (or ignored) is to put an @dfn{options} line at the start of ++the @file{.newsrc} file. Here's an example: ++ ++@example ++options -n !alt.all !rec.all sci.all ++@end example ++ ++@vindex gnus-subscribe-options-newsgroup-method ++This line obviously belongs to a serious-minded intellectual scientific ++person (or she may just be plain old boring), because it says that all ++groups that have names beginning with @samp{alt} and @samp{rec} should ++be ignored, and all groups with names beginning with @samp{sci} should ++be subscribed. Gnus will not use the normal subscription method for ++subscribing these groups. ++@code{gnus-subscribe-options-newsgroup-method} is used instead. This ++variable defaults to @code{gnus-subscribe-alphabetically}. ++ ++@vindex gnus-options-not-subscribe ++@vindex gnus-options-subscribe ++If you don't want to mess with your @file{.newsrc} file, you can just ++set the two variables @code{gnus-options-subscribe} and ++@code{gnus-options-not-subscribe}. These two variables do exactly the ++same as the @file{.newsrc} @samp{options -n} trick. Both are regexps, ++and if the new group matches the former, it will be unconditionally ++subscribed, and if it matches the latter, it will be ignored. ++ ++@vindex gnus-auto-subscribed-groups ++Yet another variable that meddles here is ++@code{gnus-auto-subscribed-groups}. It works exactly like ++@code{gnus-options-subscribe}, and is therefore really superfluous, ++but I thought it would be nice to have two of these. This variable is ++more meant for setting some ground rules, while the other variable is ++used more for user fiddling. By default this variable makes all new ++groups that come from mail back ends (@code{nnml}, @code{nnbabyl}, ++@code{nnfolder}, @code{nnmbox}, @code{nnmh}, and @code{nnmaildir}) ++subscribed. If you don't like that, just set this variable to ++@code{nil}. ++ ++New groups that match this regexp are subscribed using ++@code{gnus-subscribe-options-newsgroup-method}. ++ ++ ++@node Changing Servers ++@section Changing Servers ++@cindex changing servers ++ ++Sometimes it is necessary to move from one @acronym{NNTP} server to another. ++This happens very rarely, but perhaps you change jobs, or one server is ++very flaky and you want to use another. ++ ++Changing the server is pretty easy, right? You just change ++@code{gnus-select-method} to point to the new server? ++ ++@emph{Wrong!} ++ ++Article numbers are not (in any way) kept synchronized between different ++@acronym{NNTP} servers, and the only way Gnus keeps track of what articles ++you have read is by keeping track of article numbers. So when you ++change @code{gnus-select-method}, your @file{.newsrc} file becomes ++worthless. ++ ++Gnus provides a few functions to attempt to translate a @file{.newsrc} ++file from one server to another. They all have one thing in ++common---they take a looong time to run. You don't want to use these ++functions more than absolutely necessary. ++ ++@kindex M-x gnus-change-server ++@findex gnus-change-server ++If you have access to both servers, Gnus can request the headers for all ++the articles you have read and compare @code{Message-ID}s and map the ++article numbers of the read articles and article marks. The @kbd{M-x ++gnus-change-server} command will do this for all your native groups. It ++will prompt for the method you want to move to. ++ ++@kindex M-x gnus-group-move-group-to-server ++@findex gnus-group-move-group-to-server ++You can also move individual groups with the @kbd{M-x ++gnus-group-move-group-to-server} command. This is useful if you want to ++move a (foreign) group from one server to another. ++ ++@kindex M-x gnus-group-clear-data-on-native-groups ++@findex gnus-group-clear-data-on-native-groups ++If you don't have access to both the old and new server, all your marks ++and read ranges have become worthless. You can use the @kbd{M-x ++gnus-group-clear-data-on-native-groups} command to clear out all data ++that you have on your native groups. Use with caution. ++ ++@kindex M-x gnus-group-clear-data ++@findex gnus-group-clear-data ++Clear the data from the current group only---nix out marks and the ++list of read articles (@code{gnus-group-clear-data}). ++ ++After changing servers, you @strong{must} move the cache hierarchy away, ++since the cached articles will have wrong article numbers, which will ++affect which articles Gnus thinks are read. ++@code{gnus-group-clear-data-on-native-groups} will ask you if you want ++to have it done automatically; for @code{gnus-group-clear-data}, you ++can use @kbd{M-x gnus-cache-move-cache} (but beware, it will move the ++cache for all groups). ++ ++ ++@node Startup Files ++@section Startup Files ++@cindex startup files ++@cindex .newsrc ++@cindex .newsrc.el ++@cindex .newsrc.eld ++ ++Most common Unix news readers use a shared startup file called ++@file{.newsrc}. This file contains all the information about what ++groups are subscribed, and which articles in these groups have been ++read. ++ ++Things got a bit more complicated with @sc{gnus}. In addition to ++keeping the @file{.newsrc} file updated, it also used a file called ++@file{.newsrc.el} for storing all the information that didn't fit into ++the @file{.newsrc} file. (Actually, it also duplicated everything in ++the @file{.newsrc} file.) @sc{gnus} would read whichever one of these ++files was the most recently saved, which enabled people to swap between ++@sc{gnus} and other newsreaders. ++ ++That was kinda silly, so Gnus went one better: In addition to the ++@file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called ++@file{.newsrc.eld}. It will read whichever of these files that are most ++recent, but it will never write a @file{.newsrc.el} file. You should ++never delete the @file{.newsrc.eld} file---it contains much information ++not stored in the @file{.newsrc} file. ++ ++@vindex gnus-save-newsrc-file ++@vindex gnus-read-newsrc-file ++You can turn off writing the @file{.newsrc} file by setting ++@code{gnus-save-newsrc-file} to @code{nil}, which means you can delete ++the file and save some space, as well as exiting from Gnus faster. ++However, this will make it impossible to use other newsreaders than ++Gnus. But hey, who would want to, right? Similarly, setting ++@code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the ++@file{.newsrc} file and any @file{.newsrc-SERVER} files, which can be ++convenient if you use a different news reader occasionally, and you ++want to read a different subset of the available groups with that ++news reader. ++ ++@vindex gnus-save-killed-list ++If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus ++will not save the list of killed groups to the startup file. This will ++save both time (when starting and quitting) and space (on disk). It ++will also mean that Gnus has no record of what groups are new or old, ++so the automatic new groups subscription methods become meaningless. ++You should always set @code{gnus-check-new-newsgroups} to @code{nil} or ++@code{ask-server} if you set this variable to @code{nil} (@pxref{New ++Groups}). This variable can also be a regular expression. If that's ++the case, remove all groups that do not match this regexp before ++saving. This can be useful in certain obscure situations that involve ++several servers where not all servers support @code{ask-server}. ++ ++@vindex gnus-startup-file ++@vindex gnus-backup-startup-file ++@vindex version-control ++The @code{gnus-startup-file} variable says where the startup files are. ++The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup ++file being whatever that one is, with a @samp{.eld} appended. ++If you want version control for this file, set ++@code{gnus-backup-startup-file}. It respects the same values as the ++@code{version-control} variable. ++ ++@vindex gnus-save-newsrc-hook ++@vindex gnus-save-quick-newsrc-hook ++@vindex gnus-save-standard-newsrc-hook ++@code{gnus-save-newsrc-hook} is called before saving any of the newsrc ++files, while @code{gnus-save-quick-newsrc-hook} is called just before ++saving the @file{.newsrc.eld} file, and ++@code{gnus-save-standard-newsrc-hook} is called just before saving the ++@file{.newsrc} file. The latter two are commonly used to turn version ++control on or off. Version control is on by default when saving the ++startup files. If you want to turn backup creation off, say something like: ++ ++@lisp ++(defun turn-off-backup () ++ (set (make-local-variable 'backup-inhibited) t)) ++ ++(add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup) ++(add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup) ++@end lisp ++ ++@vindex gnus-init-file ++@vindex gnus-site-init-file ++When Gnus starts, it will read the @code{gnus-site-init-file} ++(@file{.../site-lisp/gnus-init} by default) and @code{gnus-init-file} ++(@file{~/.gnus} by default) files. These are normal Emacs Lisp files ++and can be used to avoid cluttering your @file{~/.emacs} and ++@file{site-init} files with Gnus stuff. Gnus will also check for files ++with the same names as these, but with @file{.elc} and @file{.el} ++suffixes. In other words, if you have set @code{gnus-init-file} to ++@file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el}, ++and finally @file{~/.gnus} (in this order). If Emacs was invoked with ++the @option{-q} or @option{--no-init-file} options (@pxref{Initial ++Options, ,Initial Options, emacs, The Emacs Manual}), Gnus doesn't read ++@code{gnus-init-file}. ++ ++ ++@node Auto Save ++@section Auto Save ++@cindex dribble file ++@cindex auto-save ++ ++Whenever you do something that changes the Gnus data (reading articles, ++catching up, killing/subscribing groups), the change is added to a ++special @dfn{dribble buffer}. This buffer is auto-saved the normal ++Emacs way. If your Emacs should crash before you have saved the ++@file{.newsrc} files, all changes you have made can be recovered from ++this file. ++ ++If Gnus detects this file at startup, it will ask the user whether to ++read it. The auto save file is deleted whenever the real startup file is ++saved. ++ ++@vindex gnus-use-dribble-file ++If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and ++maintain a dribble buffer. The default is @code{t}. ++ ++@vindex gnus-dribble-directory ++Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If ++this variable is @code{nil}, which it is by default, Gnus will dribble ++into the directory where the @file{.newsrc} file is located. (This is ++normally the user's home directory.) The dribble file will get the same ++file permissions as the @file{.newsrc} file. ++ ++@vindex gnus-always-read-dribble-file ++If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will ++read the dribble file on startup without querying the user. ++ ++ ++@node The Active File ++@section The Active File ++@cindex active file ++@cindex ignored groups ++ ++When Gnus starts, or indeed whenever it tries to determine whether new ++articles have arrived, it reads the active file. This is a very large ++file that lists all the active groups and articles on the server. ++ ++@vindex gnus-ignored-newsgroups ++Before examining the active file, Gnus deletes all lines that match the ++regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject ++any groups with bogus names, but you can use this variable to make Gnus ++ignore hierarchies you aren't ever interested in. However, this is not ++recommended. In fact, it's highly discouraged. Instead, @pxref{New ++Groups} for an overview of other variables that can be used instead. ++ ++@c This variable is ++@c @code{nil} by default, and will slow down active file handling somewhat ++@c if you set it to anything else. ++ ++@vindex gnus-read-active-file ++@c @head ++The active file can be rather Huge, so if you have a slow network, you ++can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from ++reading the active file. This variable is @code{some} by default. ++ ++Gnus will try to make do by getting information just on the groups that ++you actually subscribe to. ++ ++Note that if you subscribe to lots and lots of groups, setting this ++variable to @code{nil} will probably make Gnus slower, not faster. At ++present, having this variable @code{nil} will slow Gnus down ++considerably, unless you read news over a 2400 baud modem. ++ ++This variable can also have the value @code{some}. Gnus will then ++attempt to read active info only on the subscribed groups. On some ++servers this is quite fast (on sparkling, brand new INN servers that ++support the @code{LIST ACTIVE group} command), on others this isn't fast ++at all. In any case, @code{some} should be faster than @code{nil}, and ++is certainly faster than @code{t} over slow lines. ++ ++Some news servers (old versions of Leafnode and old versions of INN, for ++instance) do not support the @code{LIST ACTIVE group}. For these ++servers, @code{nil} is probably the most efficient value for this ++variable. ++ ++If this variable is @code{nil}, Gnus will ask for group info in total ++lock-step, which isn't very fast. If it is @code{some} and you use an ++@acronym{NNTP} server, Gnus will pump out commands as fast as it can, and ++read all the replies in one swoop. This will normally result in better ++performance, but if the server does not support the aforementioned ++@code{LIST ACTIVE group} command, this isn't very nice to the server. ++ ++If you think that starting up Gnus takes too long, try all the three ++different values for this variable and see what works best for you. ++ ++In any case, if you use @code{some} or @code{nil}, you should definitely ++kill all groups that you aren't interested in to speed things up. ++ ++Note that this variable also affects active file retrieval from ++secondary select methods. ++ ++ ++@node Startup Variables ++@section Startup Variables ++ ++@table @code ++ ++@item gnus-load-hook ++@vindex gnus-load-hook ++A hook run while Gnus is being loaded. Note that this hook will ++normally be run just once in each Emacs session, no matter how many ++times you start Gnus. ++ ++@item gnus-before-startup-hook ++@vindex gnus-before-startup-hook ++A hook called as the first thing when Gnus is started. ++ ++@item gnus-startup-hook ++@vindex gnus-startup-hook ++A hook run as the very last thing after starting up Gnus ++ ++@item gnus-started-hook ++@vindex gnus-started-hook ++A hook that is run as the very last thing after starting up Gnus ++successfully. ++ ++@item gnus-setup-news-hook ++@vindex gnus-setup-news-hook ++A hook that is run after reading the @file{.newsrc} file(s), but before ++generating the group buffer. ++ ++@item gnus-check-bogus-newsgroups ++@vindex gnus-check-bogus-newsgroups ++If non-@code{nil}, Gnus will check for and delete all bogus groups at ++startup. A @dfn{bogus group} is a group that you have in your ++@file{.newsrc} file, but doesn't exist on the news server. Checking for ++bogus groups can take quite a while, so to save time and resources it's ++best to leave this option off, and do the checking for bogus groups once ++in a while from the group buffer instead (@pxref{Group Maintenance}). ++ ++@item gnus-inhibit-startup-message ++@vindex gnus-inhibit-startup-message ++If non-@code{nil}, the startup message won't be displayed. That way, ++your boss might not notice as easily that you are reading news instead ++of doing your job. Note that this variable is used before ++@file{~/.gnus.el} is loaded, so it should be set in @file{.emacs} instead. ++ ++@item gnus-no-groups-message ++@vindex gnus-no-groups-message ++Message displayed by Gnus when no groups are available. ++ ++@item gnus-play-startup-jingle ++@vindex gnus-play-startup-jingle ++If non-@code{nil}, play the Gnus jingle at startup. ++ ++@item gnus-startup-jingle ++@vindex gnus-startup-jingle ++Jingle to be played if the above variable is non-@code{nil}. The ++default is @samp{Tuxedomoon.Jingle4.au}. ++ ++@end table ++ ++ ++@node Group Buffer ++@chapter Group Buffer ++@cindex group buffer ++ ++@c Alex Schroeder suggests to rearrange this as follows: ++@c ++@c ok, just save it for reference. I'll go to bed in a minute. ++@c 1. Selecting a Group, 2. (new) Finding a Group, 3. Group Levels, ++@c 4. Subscription Commands, 5. Group Maneuvering, 6. Group Data, ++@c 7. Group Score, 8. Group Buffer Format ++@c Group Levels should have more information on levels 5 to 9. I ++@c suggest to split the 4th paragraph ("Gnus considers groups...") as follows: ++@c First, "Gnus considers groups... (default 9)." ++@c New, a table summarizing what levels 1 to 9 mean. ++@c Third, "Gnus treats subscribed ... reasons of efficiency" ++@c Then expand the next paragraph or add some more to it. ++@c This short one sentence explains levels 1 and 2, therefore I understand ++@c that I should keep important news at 3 and boring news at 4. ++@c Say so! Then go on to explain why I should bother with levels 6 to 9. ++@c Maybe keep those that you don't want to read temporarily at 6, ++@c those that you never want to read at 8, those that offend your ++@c human rights at 9... ++ ++ ++The @dfn{group buffer} lists all (or parts) of the available groups. It ++is the first buffer shown when Gnus starts, and will never be killed as ++long as Gnus is active. ++ ++@iftex ++@iflatex ++\gnusfigure{The Group Buffer}{320}{ ++\put(75,50){\epsfig{figure=ps/group,height=9cm}} ++\put(120,37){\makebox(0,0)[t]{Buffer name}} ++\put(120,38){\vector(1,2){10}} ++\put(40,60){\makebox(0,0)[r]{Mode line}} ++\put(40,58){\vector(1,0){30}} ++\put(200,28){\makebox(0,0)[t]{Native select method}} ++\put(200,26){\vector(-1,2){15}} ++} ++@end iflatex ++@end iftex ++ ++@menu ++* Group Buffer Format:: Information listed and how you can change it. ++* Group Maneuvering:: Commands for moving in the group buffer. ++* Selecting a Group:: Actually reading news. ++* Subscription Commands:: Unsubscribing, killing, subscribing. ++* Group Data:: Changing the info for a group. ++* Group Levels:: Levels? What are those, then? ++* Group Score:: A mechanism for finding out what groups you like. ++* Marking Groups:: You can mark groups for later processing. ++* Foreign Groups:: Creating and editing groups. ++* Group Parameters:: Each group may have different parameters set. ++* Listing Groups:: Gnus can list various subsets of the groups. ++* Sorting Groups:: Re-arrange the group order. ++* Group Maintenance:: Maintaining a tidy @file{.newsrc} file. ++* Browse Foreign Server:: You can browse a server. See what it has to offer. ++* Exiting Gnus:: Stop reading news and get some work done. ++* Group Topics:: A folding group mode divided into topics. ++* Non-ASCII Group Names:: Accessing groups of non-English names. ++* Searching:: Mail search engines. ++* Misc Group Stuff:: Other stuff that you can to do. ++@end menu ++ ++ ++@node Group Buffer Format ++@section Group Buffer Format ++ ++@menu ++* Group Line Specification:: Deciding how the group buffer is to look. ++* Group Mode Line Specification:: The group buffer mode line. ++* Group Highlighting:: Having nice colors in the group buffer. ++@end menu ++ ++You can customize the Group Mode tool bar, see @kbd{M-x ++customize-apropos RET gnus-group-tool-bar}. This feature is only ++available in Emacs. ++ ++The tool bar icons are now (de)activated correctly depending on the ++cursor position. Therefore, moving around in the Group Buffer is ++slower. You can disable this via the variable ++@code{gnus-group-update-tool-bar}. Its default value depends on your ++Emacs version. ++ ++@node Group Line Specification ++@subsection Group Line Specification ++@cindex group buffer format ++ ++The default format of the group buffer is nice and dull, but you can ++make it as exciting and ugly as you feel like. ++ ++Here's a couple of example group lines: ++ ++@example ++ 25: news.announce.newusers ++ * 0: alt.fan.andrea-dworkin ++@end example ++ ++Quite simple, huh? ++ ++You can see that there are 25 unread articles in ++@samp{news.announce.newusers}. There are no unread articles, but some ++ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little ++asterisk at the beginning of the line?). ++ ++@vindex gnus-group-line-format ++You can change that format to whatever you want by fiddling with the ++@code{gnus-group-line-format} variable. This variable works along the ++lines of a @code{format} specification, which is pretty much the same as ++a @code{printf} specifications, for those of you who use (feh!) C. ++@xref{Formatting Variables}. ++ ++@samp{%M%S%5y:%B%(%g%)\n} is the value that produced those lines above. ++ ++There should always be a colon on the line; the cursor always moves to ++the colon after performing an operation. @xref{Positioning ++Point}. Nothing else is required---not even the group name. All ++displayed text is just window dressing, and is never examined by Gnus. ++Gnus stores all real information it needs using text properties. ++ ++(Note that if you make a really strange, wonderful, spreadsheet-like ++layout, everybody will believe you are hard at work with the accounting ++instead of wasting time reading news.) ++ ++Here's a list of all available format characters: ++ ++@table @samp ++ ++@item M ++An asterisk if the group only has marked articles. ++ ++@item S ++Whether the group is subscribed. ++ ++@item L ++Level of subscribedness. ++ ++@item N ++Number of unread articles. ++ ++@item I ++Number of dormant articles. ++ ++@item T ++Number of ticked articles. ++ ++@item R ++Number of read articles. ++ ++@item U ++Number of unseen articles. ++ ++@item t ++Estimated total number of articles. (This is really @var{max-number} ++minus @var{min-number} plus 1.) ++ ++Gnus uses this estimation because the @acronym{NNTP} protocol provides ++efficient access to @var{max-number} and @var{min-number} but getting ++the true unread message count is not possible efficiently. For ++hysterical raisins, even the mail back ends, where the true number of ++unread messages might be available efficiently, use the same limited ++interface. To remove this restriction from Gnus means that the back ++end interface has to be changed, which is not an easy job. ++ ++The nnml backend (@pxref{Mail Spool}) has a feature called ``group ++compaction'' which circumvents this deficiency: the idea is to ++renumber all articles from 1, removing all gaps between numbers, hence ++getting a correct total count. Other backends may support this in the ++future. In order to keep your total article count relatively up to ++date, you might want to compact your groups (or even directly your ++server) from time to time. @xref{Misc Group Stuff}, @xref{Server Commands}. ++ ++@item y ++Number of unread, unticked, non-dormant articles. ++ ++@item i ++Number of ticked and dormant articles. ++ ++@item g ++Full group name. ++ ++@item G ++Group name. ++ ++@item C ++Group comment (@pxref{Group Parameters}) or group name if there is no ++comment element in the group parameters. ++ ++@item D ++Newsgroup description. You need to read the group descriptions ++before these will appear, and to do that, you either have to set ++@code{gnus-read-active-file} or use the group buffer @kbd{M-d} ++command. ++ ++@item o ++@samp{m} if moderated. ++ ++@item O ++@samp{(m)} if moderated. ++ ++@item s ++Select method. ++ ++@item B ++If the summary buffer for the group is open or not. ++ ++@item n ++Select from where. ++ ++@item z ++A string that looks like @samp{<%s:%n>} if a foreign select method is ++used. ++ ++@item P ++Indentation based on the level of the topic (@pxref{Group Topics}). ++ ++@item c ++@vindex gnus-group-uncollapsed-levels ++Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels} ++variable says how many levels to leave at the end of the group name. ++The default is 1---this will mean that group names like ++@samp{gnu.emacs.gnus} will be shortened to @samp{g.e.gnus}. ++ ++@item m ++@vindex gnus-new-mail-mark ++@cindex % ++@samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to ++the group lately. ++ ++@item p ++@samp{#} (@code{gnus-process-mark}) if the group is process marked. ++ ++@item d ++A string that says when you last read the group (@pxref{Group ++Timestamp}). ++ ++@item F ++The disk space used by the articles fetched by both the cache and ++agent. The value is automatically scaled to bytes(B), kilobytes(K), ++megabytes(M), or gigabytes(G) to minimize the column width. A format ++of %7F is sufficient for a fixed-width column. ++ ++@item u ++User defined specifier. The next character in the format string should ++be a letter. Gnus will call the function ++@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter ++following @samp{%u}. The function will be passed a single dummy ++parameter as argument. The function should return a string, which will ++be inserted into the buffer just like information from any other ++specifier. ++@end table ++ ++@cindex * ++All the ``number-of'' specs will be filled with an asterisk (@samp{*}) ++if no info is available---for instance, if it is a non-activated foreign ++group, or a bogus native group. ++ ++ ++@node Group Mode Line Specification ++@subsection Group Mode Line Specification ++@cindex group mode line ++ ++@vindex gnus-group-mode-line-format ++The mode line can be changed by setting ++@code{gnus-group-mode-line-format} (@pxref{Mode Line Formatting}). It ++doesn't understand that many format specifiers: ++ ++@table @samp ++@item S ++The native news server. ++@item M ++The native select method. ++@end table ++ ++ ++@node Group Highlighting ++@subsection Group Highlighting ++@cindex highlighting ++@cindex group highlighting ++ ++@vindex gnus-group-highlight ++Highlighting in the group buffer is controlled by the ++@code{gnus-group-highlight} variable. This is an alist with elements ++that look like @code{(@var{form} . @var{face})}. If @var{form} evaluates to ++something non-@code{nil}, the @var{face} will be used on the line. ++ ++Here's an example value for this variable that might look nice if the ++background is dark: ++ ++@lisp ++(cond (window-system ++ (setq custom-background-mode 'light) ++ (defface my-group-face-1 ++ '((t (:foreground "Red" :bold t))) "First group face") ++ (defface my-group-face-2 ++ '((t (:foreground "DarkSeaGreen4" :bold t))) ++ "Second group face") ++ (defface my-group-face-3 ++ '((t (:foreground "Green4" :bold t))) "Third group face") ++ (defface my-group-face-4 ++ '((t (:foreground "SteelBlue" :bold t))) "Fourth group face") ++ (defface my-group-face-5 ++ '((t (:foreground "Blue" :bold t))) "Fifth group face"))) ++ ++(setq gnus-group-highlight ++ '(((> unread 200) . my-group-face-1) ++ ((and (< level 3) (zerop unread)) . my-group-face-2) ++ ((< level 3) . my-group-face-3) ++ ((zerop unread) . my-group-face-4) ++ (t . my-group-face-5))) ++@end lisp ++ ++Also @pxref{Faces and Fonts}. ++ ++Variables that are dynamically bound when the forms are evaluated ++include: ++ ++@table @code ++@item group ++The group name. ++@item unread ++The number of unread articles in the group. ++@item method ++The select method. ++@item mailp ++Whether the group is a mail group. ++@item level ++The level of the group. ++@item score ++The score of the group. ++@item ticked ++The number of ticked articles in the group. ++@item total ++The total number of articles in the group. Or rather, ++@var{max-number} minus @var{min-number} plus one. ++@item topic ++When using the topic minor mode, this variable is bound to the current ++topic being inserted. ++@end table ++ ++When the forms are @code{eval}ed, point is at the beginning of the line ++of the group in question, so you can use many of the normal Gnus ++functions for snarfing info on the group. ++ ++@vindex gnus-group-update-hook ++@findex gnus-group-highlight-line ++@code{gnus-group-update-hook} is called when a group line is changed. ++It will not be called when @code{gnus-visual} is @code{nil}. This hook ++calls @code{gnus-group-highlight-line} by default. ++ ++ ++@node Group Maneuvering ++@section Group Maneuvering ++@cindex group movement ++ ++All movement commands understand the numeric prefix and will behave as ++expected, hopefully. ++ ++@table @kbd ++ ++@item n ++@kindex n (Group) ++@findex gnus-group-next-unread-group ++Go to the next group that has unread articles ++(@code{gnus-group-next-unread-group}). ++ ++@item p ++@itemx DEL ++@kindex DEL (Group) ++@kindex p (Group) ++@findex gnus-group-prev-unread-group ++Go to the previous group that has unread articles ++(@code{gnus-group-prev-unread-group}). ++ ++@item N ++@kindex N (Group) ++@findex gnus-group-next-group ++Go to the next group (@code{gnus-group-next-group}). ++ ++@item P ++@kindex P (Group) ++@findex gnus-group-prev-group ++Go to the previous group (@code{gnus-group-prev-group}). ++ ++@item M-n ++@kindex M-n (Group) ++@findex gnus-group-next-unread-group-same-level ++Go to the next unread group on the same (or lower) level ++(@code{gnus-group-next-unread-group-same-level}). ++ ++@item M-p ++@kindex M-p (Group) ++@findex gnus-group-prev-unread-group-same-level ++Go to the previous unread group on the same (or lower) level ++(@code{gnus-group-prev-unread-group-same-level}). ++@end table ++ ++Three commands for jumping to groups: ++ ++@table @kbd ++ ++@item j ++@kindex j (Group) ++@findex gnus-group-jump-to-group ++Jump to a group (and make it visible if it isn't already) ++(@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just ++like living groups. ++ ++@item , ++@kindex , (Group) ++@findex gnus-group-best-unread-group ++Jump to the unread group with the lowest level ++(@code{gnus-group-best-unread-group}). ++ ++@item . ++@kindex . (Group) ++@findex gnus-group-first-unread-group ++Jump to the first group with unread articles ++(@code{gnus-group-first-unread-group}). ++@end table ++ ++@vindex gnus-group-goto-unread ++If @code{gnus-group-goto-unread} is @code{nil}, all the movement ++commands will move to the next group, not the next unread group. Even ++the commands that say they move to the next unread group. The default ++is @code{t}. ++ ++@vindex gnus-summary-next-group-on-exit ++If @code{gnus-summary-next-group-on-exit} is @code{t}, when a summary is ++exited, the point in the group buffer is moved to the next unread group. ++Otherwise, the point is set to the group just exited. The default is ++@code{t}. ++ ++@node Selecting a Group ++@section Selecting a Group ++@cindex group selection ++ ++@table @kbd ++ ++@item SPACE ++@kindex SPACE (Group) ++@findex gnus-group-read-group ++Select the current group, switch to the summary buffer and display the ++first unread article (@code{gnus-group-read-group}). If there are no ++unread articles in the group, or if you give a non-numerical prefix to ++this command, Gnus will offer to fetch all the old articles in this ++group from the server. If you give a numerical prefix @var{n}, @var{n} ++determines the number of articles Gnus will fetch. If @var{n} is ++positive, Gnus fetches the @var{n} newest articles, if @var{n} is ++negative, Gnus fetches the @code{abs(@var{n})} oldest articles. ++ ++Thus, @kbd{SPC} enters the group normally, @kbd{C-u SPC} offers old ++articles, @kbd{C-u 4 2 SPC} fetches the 42 newest articles, and @kbd{C-u ++- 4 2 SPC} fetches the 42 oldest ones. ++ ++When you are in the group (in the Summary buffer), you can type ++@kbd{M-g} to fetch new articles, or @kbd{C-u M-g} to also show the old ++ones. ++ ++@item RET ++@kindex RET (Group) ++@findex gnus-group-select-group ++Select the current group and switch to the summary buffer ++(@code{gnus-group-select-group}). Takes the same arguments as ++@code{gnus-group-read-group}---the only difference is that this command ++does not display the first unread article automatically upon group ++entry. ++ ++@item M-RET ++@kindex M-RET (Group) ++@findex gnus-group-quick-select-group ++This does the same as the command above, but tries to do it with the ++minimum amount of fuzz (@code{gnus-group-quick-select-group}). No ++scoring/killing will be performed, there will be no highlights and no ++expunging. This might be useful if you're in a real hurry and have to ++enter some humongous group. If you give a 0 prefix to this command ++(i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer, ++which is useful if you want to toggle threading before generating the ++summary buffer (@pxref{Summary Generation Commands}). ++ ++@item M-SPACE ++@kindex M-SPACE (Group) ++@findex gnus-group-visible-select-group ++This is yet one more command that does the same as the @kbd{RET} ++command, but this one does it without expunging and hiding dormants ++(@code{gnus-group-visible-select-group}). ++ ++@item C-M-RET ++@kindex C-M-RET (Group) ++@findex gnus-group-select-group-ephemerally ++Finally, this command selects the current group ephemerally without ++doing any processing of its contents ++(@code{gnus-group-select-group-ephemerally}). Even threading has been ++turned off. Everything you do in the group after selecting it in this ++manner will have no permanent effects. ++ ++@end table ++ ++@vindex gnus-large-newsgroup ++The @code{gnus-large-newsgroup} variable says what Gnus should ++consider to be a big group. If it is @code{nil}, no groups are ++considered big. The default value is 200. If the group has more ++(unread and/or ticked) articles than this, Gnus will query the user ++before entering the group. The user can then specify how many ++articles should be fetched from the server. If the user specifies a ++negative number (@var{-n}), the @var{n} oldest articles will be ++fetched. If it is positive, the @var{n} articles that have arrived ++most recently will be fetched. ++ ++@vindex gnus-large-ephemeral-newsgroup ++@code{gnus-large-ephemeral-newsgroup} is the same as ++@code{gnus-large-newsgroup}, but is only used for ephemeral ++newsgroups. ++ ++@vindex gnus-newsgroup-maximum-articles ++In groups in some news servers, there might be a big gap between a few ++very old articles that will never be expired and the recent ones. In ++such a case, the server will return the data like @code{(1 . 30000000)} ++for the @code{LIST ACTIVE group} command, for example. Even if there ++are actually only the articles 1-10 and 29999900-30000000, Gnus doesn't ++know it at first and prepares for getting 30000000 articles. However, ++it will consume hundreds megabytes of memories and might make Emacs get ++stuck as the case may be. If you use such news servers, set the ++variable @code{gnus-newsgroup-maximum-articles} to a positive number. ++The value means that Gnus ignores articles other than this number of the ++latest ones in every group. For instance, the value 10000 makes Gnus ++get only the articles 29990001-30000000 (if the latest article number is ++30000000 in a group). Note that setting this variable to a number might ++prevent you from reading very old articles. The default value of the ++variable @code{gnus-newsgroup-maximum-articles} is @code{nil}, which ++means Gnus never ignores old articles. ++ ++@vindex gnus-select-group-hook ++@vindex gnus-auto-select-first ++@vindex gnus-auto-select-subject ++If @code{gnus-auto-select-first} is non-@code{nil}, select an article ++automatically when entering a group with the @kbd{SPACE} command. ++Which article this is controlled by the ++@code{gnus-auto-select-subject} variable. Valid values for this ++variable are: ++ ++@table @code ++ ++@item unread ++Place point on the subject line of the first unread article. ++ ++@item first ++Place point on the subject line of the first article. ++ ++@item unseen ++Place point on the subject line of the first unseen article. ++ ++@item unseen-or-unread ++Place point on the subject line of the first unseen article, and if ++there is no such article, place point on the subject line of the first ++unread article. ++ ++@item best ++Place point on the subject line of the highest-scored unread article. ++ ++@end table ++ ++This variable can also be a function. In that case, that function ++will be called to place point on a subject line. ++ ++If you want to prevent automatic selection in some group (say, in a ++binary group with Huge articles) you can set the ++@code{gnus-auto-select-first} variable to @code{nil} in ++@code{gnus-select-group-hook}, which is called when a group is ++selected. ++ ++ ++@node Subscription Commands ++@section Subscription Commands ++@cindex subscription ++ ++@table @kbd ++ ++@item S t ++@itemx u ++@kindex S t (Group) ++@kindex u (Group) ++@findex gnus-group-unsubscribe-current-group ++@c @icon{gnus-group-unsubscribe} ++Toggle subscription to the current group ++(@code{gnus-group-unsubscribe-current-group}). ++ ++@item S s ++@itemx U ++@kindex S s (Group) ++@kindex U (Group) ++@findex gnus-group-unsubscribe-group ++Prompt for a group to subscribe, and then subscribe it. If it was ++subscribed already, unsubscribe it instead ++(@code{gnus-group-unsubscribe-group}). ++ ++@item S k ++@itemx C-k ++@kindex S k (Group) ++@kindex C-k (Group) ++@findex gnus-group-kill-group ++@c @icon{gnus-group-kill-group} ++Kill the current group (@code{gnus-group-kill-group}). ++ ++@item S y ++@itemx C-y ++@kindex S y (Group) ++@kindex C-y (Group) ++@findex gnus-group-yank-group ++Yank the last killed group (@code{gnus-group-yank-group}). ++ ++@item C-x C-t ++@kindex C-x C-t (Group) ++@findex gnus-group-transpose-groups ++Transpose two groups (@code{gnus-group-transpose-groups}). This isn't ++really a subscription command, but you can use it instead of a ++kill-and-yank sequence sometimes. ++ ++@item S w ++@itemx C-w ++@kindex S w (Group) ++@kindex C-w (Group) ++@findex gnus-group-kill-region ++Kill all groups in the region (@code{gnus-group-kill-region}). ++ ++@item S z ++@kindex S z (Group) ++@findex gnus-group-kill-all-zombies ++Kill all zombie groups (@code{gnus-group-kill-all-zombies}). ++ ++@item S C-k ++@kindex S C-k (Group) ++@findex gnus-group-kill-level ++Kill all groups on a certain level (@code{gnus-group-kill-level}). ++These groups can't be yanked back after killing, so this command should ++be used with some caution. The only time where this command comes in ++really handy is when you have a @file{.newsrc} with lots of unsubscribed ++groups that you want to get rid off. @kbd{S C-k} on level 7 will ++kill off all unsubscribed groups that do not have message numbers in the ++@file{.newsrc} file. ++ ++@end table ++ ++Also @pxref{Group Levels}. ++ ++ ++@node Group Data ++@section Group Data ++ ++@table @kbd ++ ++@item c ++@kindex c (Group) ++@findex gnus-group-catchup-current ++@vindex gnus-group-catchup-group-hook ++@c @icon{gnus-group-catchup-current} ++Mark all unticked articles in this group as read ++(@code{gnus-group-catchup-current}). ++@code{gnus-group-catchup-group-hook} is called when catching up a group from ++the group buffer. ++ ++@item C ++@kindex C (Group) ++@findex gnus-group-catchup-current-all ++Mark all articles in this group, even the ticked ones, as read ++(@code{gnus-group-catchup-current-all}). ++ ++@item M-c ++@kindex M-c (Group) ++@findex gnus-group-clear-data ++Clear the data from the current group---nix out marks and the list of ++read articles (@code{gnus-group-clear-data}). ++ ++@item M-x gnus-group-clear-data-on-native-groups ++@kindex M-x gnus-group-clear-data-on-native-groups ++@findex gnus-group-clear-data-on-native-groups ++If you have switched from one @acronym{NNTP} server to another, all your marks ++and read ranges have become worthless. You can use this command to ++clear out all data that you have on your native groups. Use with ++caution. ++ ++@end table ++ ++ ++@node Group Levels ++@section Group Levels ++@cindex group level ++@cindex level ++ ++All groups have a level of @dfn{subscribedness}. For instance, if a ++group is on level 2, it is more subscribed than a group on level 5. You ++can ask Gnus to just list groups on a given level or lower ++(@pxref{Listing Groups}), or to just check for new articles in groups on ++a given level or lower (@pxref{Scanning New Messages}). ++ ++Remember: The higher the level of the group, the less important it is. ++ ++@table @kbd ++ ++@item S l ++@kindex S l (Group) ++@findex gnus-group-set-current-level ++Set the level of the current group. If a numeric prefix is given, the ++next @var{n} groups will have their levels set. The user will be ++prompted for a level. ++@end table ++ ++@vindex gnus-level-killed ++@vindex gnus-level-zombie ++@vindex gnus-level-unsubscribed ++@vindex gnus-level-subscribed ++Gnus considers groups from levels 1 to ++@code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed, ++@code{gnus-level-subscribed} (exclusive) and ++@code{gnus-level-unsubscribed} (inclusive) (default 7) to be ++unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead) ++(default 8) and @code{gnus-level-killed} to be killed (completely dead) ++(default 9). Gnus treats subscribed and unsubscribed groups exactly the ++same, but zombie and killed groups have no information on what articles ++you have read, etc, stored. This distinction between dead and living ++groups isn't done because it is nice or clever, it is done purely for ++reasons of efficiency. ++ ++It is recommended that you keep all your mail groups (if any) on quite ++low levels (e.g. 1 or 2). ++ ++Maybe the following description of the default behavior of Gnus helps to ++understand what these levels are all about. By default, Gnus shows you ++subscribed nonempty groups, but by hitting @kbd{L} you can have it show ++empty subscribed groups and unsubscribed groups, too. Type @kbd{l} to ++go back to showing nonempty subscribed groups again. Thus, unsubscribed ++groups are hidden, in a way. ++ ++Zombie and killed groups are similar to unsubscribed groups in that they ++are hidden by default. But they are different from subscribed and ++unsubscribed groups in that Gnus doesn't ask the news server for ++information (number of messages, number of unread messages) on zombie ++and killed groups. Normally, you use @kbd{C-k} to kill the groups you ++aren't interested in. If most groups are killed, Gnus is faster. ++ ++Why does Gnus distinguish between zombie and killed groups? Well, when ++a new group arrives on the server, Gnus by default makes it a zombie ++group. This means that you are normally not bothered with new groups, ++but you can type @kbd{A z} to get a list of all new groups. Subscribe ++the ones you like and kill the ones you don't want. (@kbd{A k} shows a ++list of killed groups.) ++ ++If you want to play with the level variables, you should show some care. ++Set them once, and don't touch them ever again. Better yet, don't touch ++them at all unless you know exactly what you're doing. ++ ++@vindex gnus-level-default-unsubscribed ++@vindex gnus-level-default-subscribed ++Two closely related variables are @code{gnus-level-default-subscribed} ++(default 3) and @code{gnus-level-default-unsubscribed} (default 6), ++which are the levels that new groups will be put on if they are ++(un)subscribed. These two variables should, of course, be inside the ++relevant valid ranges. ++ ++@vindex gnus-keep-same-level ++If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands ++will only move to groups of the same level (or lower). In ++particular, going from the last article in one group to the next group ++will go to the next group of the same level (or lower). This might be ++handy if you want to read the most important groups before you read the ++rest. ++ ++If this variable is @code{best}, Gnus will make the next newsgroup the ++one with the best level. ++ ++@vindex gnus-group-default-list-level ++All groups with a level less than or equal to ++@code{gnus-group-default-list-level} will be listed in the group buffer ++by default. ++ ++@vindex gnus-group-list-inactive-groups ++If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active ++groups will be listed along with the unread groups. This variable is ++@code{t} by default. If it is @code{nil}, inactive groups won't be ++listed. ++ ++@vindex gnus-group-use-permanent-levels ++If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you ++give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will ++use this level as the ``work'' level. ++ ++@vindex gnus-activate-level ++Gnus will normally just activate (i. e., query the server about) groups ++on level @code{gnus-activate-level} or less. If you don't want to ++activate unsubscribed groups, for instance, you might set this variable ++to 5. The default is 6. ++ ++ ++@node Group Score ++@section Group Score ++@cindex group score ++@cindex group rank ++@cindex rank ++ ++You would normally keep important groups on high levels, but that scheme ++is somewhat restrictive. Don't you wish you could have Gnus sort the ++group buffer according to how often you read groups, perhaps? Within ++reason? ++ ++This is what @dfn{group score} is for. You can have Gnus assign a score ++to each group through the mechanism described below. You can then sort ++the group buffer based on this score. Alternatively, you can sort on ++score and then level. (Taken together, the level and the score is ++called the @dfn{rank} of the group. A group that is on level 4 and has ++a score of 1 has a higher rank than a group on level 5 that has a score ++of 300. (The level is the most significant part and the score is the ++least significant part.)) ++ ++@findex gnus-summary-bubble-group ++If you want groups you read often to get higher scores than groups you ++read seldom you can add the @code{gnus-summary-bubble-group} function to ++the @code{gnus-summary-exit-hook} hook. This will result (after ++sorting) in a bubbling sort of action. If you want to see that in ++action after each summary exit, you can add ++@code{gnus-group-sort-groups-by-rank} or ++@code{gnus-group-sort-groups-by-score} to the same hook, but that will ++slow things down somewhat. ++ ++ ++@node Marking Groups ++@section Marking Groups ++@cindex marking groups ++ ++If you want to perform some command on several groups, and they appear ++subsequently in the group buffer, you would normally just give a ++numerical prefix to the command. Most group commands will then do your ++bidding on those groups. ++ ++However, if the groups are not in sequential order, you can still ++perform a command on several groups. You simply mark the groups first ++with the process mark and then execute the command. ++ ++@table @kbd ++ ++@item # ++@kindex # (Group) ++@itemx M m ++@kindex M m (Group) ++@findex gnus-group-mark-group ++Set the mark on the current group (@code{gnus-group-mark-group}). ++ ++@item M-# ++@kindex M-# (Group) ++@itemx M u ++@kindex M u (Group) ++@findex gnus-group-unmark-group ++Remove the mark from the current group ++(@code{gnus-group-unmark-group}). ++ ++@item M U ++@kindex M U (Group) ++@findex gnus-group-unmark-all-groups ++Remove the mark from all groups (@code{gnus-group-unmark-all-groups}). ++ ++@item M w ++@kindex M w (Group) ++@findex gnus-group-mark-region ++Mark all groups between point and mark (@code{gnus-group-mark-region}). ++ ++@item M b ++@kindex M b (Group) ++@findex gnus-group-mark-buffer ++Mark all groups in the buffer (@code{gnus-group-mark-buffer}). ++ ++@item M r ++@kindex M r (Group) ++@findex gnus-group-mark-regexp ++Mark all groups that match some regular expression ++(@code{gnus-group-mark-regexp}). ++@end table ++ ++Also @pxref{Process/Prefix}. ++ ++@findex gnus-group-universal-argument ++If you want to execute some command on all groups that have been marked ++with the process mark, you can use the @kbd{M-&} ++(@code{gnus-group-universal-argument}) command. It will prompt you for ++the command to be executed. ++ ++ ++@node Foreign Groups ++@section Foreign Groups ++@cindex foreign groups ++ ++Below are some group mode commands for making and editing general foreign ++groups, as well as commands to ease the creation of a few ++special-purpose groups. All these commands insert the newly created ++groups under point---@code{gnus-subscribe-newsgroup-method} is not ++consulted. ++ ++Changes from the group editing commands are stored in ++@file{~/.newsrc.eld} (@code{gnus-startup-file}). An alternative is the ++variable @code{gnus-parameters}, @xref{Group Parameters}. ++ ++@table @kbd ++ ++@item G m ++@kindex G m (Group) ++@findex gnus-group-make-group ++@cindex making groups ++Make a new group (@code{gnus-group-make-group}). Gnus will prompt you ++for a name, a method and possibly an @dfn{address}. For an easier way ++to subscribe to @acronym{NNTP} groups (@pxref{Browse Foreign Server}). ++ ++@item G M ++@kindex G M (Group) ++@findex gnus-group-read-ephemeral-group ++Make an ephemeral group (@code{gnus-group-read-ephemeral-group}). Gnus ++will prompt you for a name, a method and an @dfn{address}. ++ ++@item G r ++@kindex G r (Group) ++@findex gnus-group-rename-group ++@cindex renaming groups ++Rename the current group to something else ++(@code{gnus-group-rename-group}). This is valid only on some ++groups---mail groups mostly. This command might very well be quite slow ++on some back ends. ++ ++@item G c ++@kindex G c (Group) ++@cindex customizing ++@findex gnus-group-customize ++Customize the group parameters (@code{gnus-group-customize}). ++ ++@item G e ++@kindex G e (Group) ++@findex gnus-group-edit-group-method ++@cindex renaming groups ++Enter a buffer where you can edit the select method of the current ++group (@code{gnus-group-edit-group-method}). ++ ++@item G p ++@kindex G p (Group) ++@findex gnus-group-edit-group-parameters ++Enter a buffer where you can edit the group parameters ++(@code{gnus-group-edit-group-parameters}). ++ ++@item G E ++@kindex G E (Group) ++@findex gnus-group-edit-group ++Enter a buffer where you can edit the group info ++(@code{gnus-group-edit-group}). ++ ++@item G d ++@kindex G d (Group) ++@findex gnus-group-make-directory-group ++@cindex nndir ++Make a directory group (@pxref{Directory Groups}). You will be prompted ++for a directory name (@code{gnus-group-make-directory-group}). ++ ++@item G h ++@kindex G h (Group) ++@cindex help group ++@findex gnus-group-make-help-group ++Make the Gnus help group (@code{gnus-group-make-help-group}). ++ ++@item G a ++@kindex G a (Group) ++@cindex (ding) archive ++@cindex archive group ++@findex gnus-group-make-archive-group ++@vindex gnus-group-archive-directory ++@vindex gnus-group-recent-archive-directory ++Make a Gnus archive group (@code{gnus-group-make-archive-group}). By ++default a group pointing to the most recent articles will be created ++(@code{gnus-group-recent-archive-directory}), but given a prefix, a full ++group will be created from @code{gnus-group-archive-directory}. ++ ++@item G k ++@kindex G k (Group) ++@findex gnus-group-make-kiboze-group ++@cindex nnkiboze ++Make a kiboze group. You will be prompted for a name, for a regexp to ++match groups to be ``included'' in the kiboze group, and a series of ++strings to match on headers (@code{gnus-group-make-kiboze-group}). ++@xref{Kibozed Groups}. ++ ++@item G D ++@kindex G D (Group) ++@findex gnus-group-enter-directory ++@cindex nneething ++Read an arbitrary directory as if it were a newsgroup with the ++@code{nneething} back end (@code{gnus-group-enter-directory}). ++@xref{Anything Groups}. ++ ++@item G f ++@kindex G f (Group) ++@findex gnus-group-make-doc-group ++@cindex ClariNet Briefs ++@cindex nndoc ++Make a group based on some file or other ++(@code{gnus-group-make-doc-group}). If you give a prefix to this ++command, you will be prompted for a file name and a file type. ++Currently supported types are @code{mbox}, @code{babyl}, ++@code{digest}, @code{news}, @code{rnews}, @code{mmdf}, @code{forward}, ++@code{rfc934}, @code{rfc822-forward}, @code{mime-parts}, ++@code{standard-digest}, @code{slack-digest}, @code{clari-briefs}, ++@code{nsmail}, @code{outlook}, @code{oe-dbx}, and @code{mailman}. If ++you run this command without a prefix, Gnus will guess at the file ++type. @xref{Document Groups}. ++ ++@item G u ++@kindex G u (Group) ++@vindex gnus-useful-groups ++@findex gnus-group-make-useful-group ++Create one of the groups mentioned in @code{gnus-useful-groups} ++(@code{gnus-group-make-useful-group}). ++ ++@item G w ++@kindex G w (Group) ++@findex gnus-group-make-web-group ++@cindex Google ++@cindex nnweb ++@cindex gmane ++Make an ephemeral group based on a web search ++(@code{gnus-group-make-web-group}). If you give a prefix to this ++command, make a solid group instead. You will be prompted for the ++search engine type and the search string. Valid search engine types ++include @code{google}, @code{dejanews}, and @code{gmane}. ++@xref{Web Searches}. ++ ++If you use the @code{google} search engine, you can limit the search ++to a particular group by using a match string like ++@samp{shaving group:alt.sysadmin.recovery}. ++ ++@item G R ++@kindex G R (Group) ++@findex gnus-group-make-rss-group ++Make a group based on an @acronym{RSS} feed ++(@code{gnus-group-make-rss-group}). You will be prompted for an URL. ++@xref{RSS}. ++ ++@item G DEL ++@kindex G DEL (Group) ++@findex gnus-group-delete-group ++This function will delete the current group ++(@code{gnus-group-delete-group}). If given a prefix, this function will ++actually delete all the articles in the group, and forcibly remove the ++group itself from the face of the Earth. Use a prefix only if you are ++absolutely sure of what you are doing. This command can't be used on ++read-only groups (like @code{nntp} groups), though. ++ ++@item G V ++@kindex G V (Group) ++@findex gnus-group-make-empty-virtual ++Make a new, fresh, empty @code{nnvirtual} group ++(@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}. ++ ++@item G v ++@kindex G v (Group) ++@findex gnus-group-add-to-virtual ++Add the current group to an @code{nnvirtual} group ++(@code{gnus-group-add-to-virtual}). Uses the process/prefix convention. ++@end table ++ ++@xref{Select Methods}, for more information on the various select ++methods. ++ ++@vindex gnus-activate-foreign-newsgroups ++If @code{gnus-activate-foreign-newsgroups} is a positive number, ++Gnus will check all foreign groups with this level or lower at startup. ++This might take quite a while, especially if you subscribe to lots of ++groups from different @acronym{NNTP} servers. Also @pxref{Group Levels}; ++@code{gnus-activate-level} also affects activation of foreign ++newsgroups. ++ ++ ++The following commands create ephemeral groups. They can be called not ++only from the Group buffer, but in any Gnus buffer. ++ ++@table @code ++@item gnus-read-ephemeral-gmane-group ++@findex gnus-read-ephemeral-gmane-group ++@vindex gnus-gmane-group-download-format ++Read an ephemeral group on Gmane.org. The articles are downloaded via ++HTTP using the URL specified by @code{gnus-gmane-group-download-format}. ++Gnus will prompt you for a group name, the start article number and an ++the article range. ++ ++@item gnus-read-ephemeral-gmane-group-url ++@findex gnus-read-ephemeral-gmane-group-url ++This command is similar to @code{gnus-read-ephemeral-gmane-group}, but ++the group name and the article number and range are constructed from a ++given @acronym{URL}. Supported @acronym{URL} formats include e.g. ++@url{http://thread.gmane.org/gmane.foo.bar/12300/focus=12399}, ++@url{http://thread.gmane.org/gmane.foo.bar/12345/}, ++@url{http://article.gmane.org/gmane.foo.bar/12345/}, ++@url{http://permalink.gmane.org/gmane.foo.bar/12345/}, and ++@url{http://news.gmane.org/group/gmane.foo.bar/thread=12345}. ++ ++@item gnus-read-ephemeral-emacs-bug-group ++@findex gnus-read-ephemeral-emacs-bug-group ++Read an Emacs bug report in an ephemeral group. Gnus will prompt for a ++bug number. The default is the number at point. The @acronym{URL} is ++specified in @code{gnus-bug-group-download-format-alist}. ++ ++@item gnus-read-ephemeral-debian-bug-group ++@findex gnus-read-ephemeral-debian-bug-group ++Read a Debian bug report in an ephemeral group. Analog to ++@code{gnus-read-ephemeral-emacs-bug-group}. ++@end table ++ ++Some of these command are also useful for article buttons, @xref{Article ++Buttons}. ++ ++Here is an example: ++@lisp ++(require 'gnus-art) ++(add-to-list ++ 'gnus-button-alist ++ '("#\\([0-9]+\\)\\>" 1 ++ (string-match "\\" (or gnus-newsgroup-name "")) ++ gnus-read-ephemeral-emacs-bug-group 1)) ++@end lisp ++ ++ ++@node Group Parameters ++@section Group Parameters ++@cindex group parameters ++ ++The group parameters store information local to a particular group. ++ ++Use the @kbd{G p} or the @kbd{G c} command to edit group parameters of a ++group. (@kbd{G p} presents you with a Lisp-based interface, @kbd{G c} ++presents you with a Customize-like interface. The latter helps avoid ++silly Lisp errors.) You might also be interested in reading about topic ++parameters (@pxref{Topic Parameters}). ++Additionally, you can set group parameters via the ++@code{gnus-parameters} variable, see below. ++ ++Here's an example group parameter list: ++ ++@example ++((to-address . "ding@@gnus.org") ++ (auto-expire . t)) ++@end example ++ ++We see that each element consists of a ``dotted pair''---the thing before ++the dot is the key, while the thing after the dot is the value. All the ++parameters have this form @emph{except} local variable specs, which are ++not dotted pairs, but proper lists. ++ ++Some parameters have correspondent customizable variables, each of which ++is an alist of regexps and values. ++ ++The following group parameters can be used: ++ ++@table @code ++@item to-address ++@cindex to-address ++Address used by when doing followups and new posts. ++ ++@example ++(to-address . "some@@where.com") ++@end example ++ ++This is primarily useful in mail groups that represent closed mailing ++lists---mailing lists where it's expected that everybody that writes to ++the mailing list is subscribed to it. Since using this parameter ++ensures that the mail only goes to the mailing list itself, it means ++that members won't receive two copies of your followups. ++ ++Using @code{to-address} will actually work whether the group is foreign ++or not. Let's say there's a group on the server that is called ++@samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten ++the articles from a mail-to-news gateway. Posting directly to this ++group is therefore impossible---you have to send mail to the mailing ++list address instead. ++ ++See also @code{gnus-parameter-to-address-alist}. ++ ++@item to-list ++@cindex to-list ++Address used when doing @kbd{a} in that group. ++ ++@example ++(to-list . "some@@where.com") ++@end example ++ ++It is totally ignored ++when doing a followup---except that if it is present in a news group, ++you'll get mail group semantics when doing @kbd{f}. ++ ++If you do an @kbd{a} command in a mail group and you have neither a ++@code{to-list} group parameter nor a @code{to-address} group parameter, ++then a @code{to-list} group parameter will be added automatically upon ++sending the message if @code{gnus-add-to-list} is set to @code{t}. ++@vindex gnus-add-to-list ++ ++@findex gnus-mailing-list-mode ++@cindex mail list groups ++If this variable is set, @code{gnus-mailing-list-mode} is turned on when ++entering summary buffer. ++ ++See also @code{gnus-parameter-to-list-alist}. ++ ++@anchor{subscribed} ++@item subscribed ++@cindex subscribed ++@cindex Mail-Followup-To ++@findex gnus-find-subscribed-addresses ++If this parameter is set to @code{t}, Gnus will consider the ++to-address and to-list parameters for this group as addresses of ++mailing lists you are subscribed to. Giving Gnus this information is ++(only) a first step in getting it to generate correct Mail-Followup-To ++headers for your posts to these lists. The second step is to put the ++following in your @file{.gnus.el} ++ ++@lisp ++(setq message-subscribed-address-functions ++ '(gnus-find-subscribed-addresses)) ++@end lisp ++ ++@xref{Mailing Lists, ,Mailing Lists, message, The Message Manual}, for ++a complete treatment of available MFT support. ++ ++@item visible ++@cindex visible ++If the group parameter list has the element @code{(visible . t)}, ++that group will always be visible in the Group buffer, regardless ++of whether it has any unread articles. ++ ++This parameter cannot be set via @code{gnus-parameters}. See ++@code{gnus-permanently-visible-groups} as an alternative. ++ ++@item broken-reply-to ++@cindex broken-reply-to ++Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To} ++headers in this group are to be ignored, and for the header to be hidden ++if @code{reply-to} is part of @code{gnus-boring-article-headers}. This ++can be useful if you're reading a mailing list group where the listserv ++has inserted @code{Reply-To} headers that point back to the listserv ++itself. That is broken behavior. So there! ++ ++@item to-group ++@cindex to-group ++Elements like @code{(to-group . "some.group.name")} means that all ++posts in that group will be sent to @code{some.group.name}. ++ ++@item newsgroup ++@cindex newsgroup ++If you have @code{(newsgroup . t)} in the group parameter list, Gnus ++will treat all responses as if they were responses to news articles. ++This can be useful if you have a mail group that's really a mirror of a ++news group. ++ ++@item gcc-self ++@cindex gcc-self ++If @code{(gcc-self . t)} is present in the group parameter list, newly ++composed messages will be @code{Gcc}'d to the current group. If ++@code{(gcc-self . none)} is present, no @code{Gcc:} header will be ++generated, if @code{(gcc-self . "string")} is present, this string will ++be inserted literally as a @code{gcc} header. This parameter takes ++precedence over any default @code{Gcc} rules as described later ++(@pxref{Archived Messages}). ++ ++@strong{Caveat}: Adding @code{(gcc-self . t)} to the parameter list of ++@code{nntp} groups (or the like) isn't valid. An @code{nntp} server ++doesn't accept articles. ++ ++@item auto-expire ++@cindex auto-expire ++@cindex expiring mail ++If the group parameter has an element that looks like @code{(auto-expire ++. t)}, all articles read will be marked as expirable. For an ++alternative approach, @pxref{Expiring Mail}. ++ ++See also @code{gnus-auto-expirable-newsgroups}. ++ ++@item total-expire ++@cindex total-expire ++@cindex expiring mail ++If the group parameter has an element that looks like ++@code{(total-expire . t)}, all read articles will be put through the ++expiry process, even if they are not marked as expirable. Use with ++caution. Unread, ticked and dormant articles are not eligible for ++expiry. ++ ++See also @code{gnus-total-expirable-newsgroups}. ++ ++@item expiry-wait ++@cindex expiry-wait ++@vindex nnmail-expiry-wait-function ++If the group parameter has an element that looks like ++@code{(expiry-wait . 10)}, this value will override any ++@code{nnmail-expiry-wait} and @code{nnmail-expiry-wait-function} ++(@pxref{Expiring Mail}) when expiring expirable messages. The value ++can either be a number of days (not necessarily an integer) or the ++symbols @code{never} or @code{immediate}. ++ ++@item expiry-target ++@cindex expiry-target ++Where expired messages end up. This parameter overrides ++@code{nnmail-expiry-target}. ++ ++@item score-file ++@cindex score file group parameter ++Elements that look like @code{(score-file . "file")} will make ++@file{file} into the current score file for the group in question. All ++interactive score entries will be put into this file. ++ ++@item adapt-file ++@cindex adapt file group parameter ++Elements that look like @code{(adapt-file . "file")} will make ++@file{file} into the current adaptive file for the group in question. ++All adaptive score entries will be put into this file. ++ ++@item admin-address ++@cindex admin-address ++When unsubscribing from a mailing list you should never send the ++unsubscription notice to the mailing list itself. Instead, you'd send ++messages to the administrative address. This parameter allows you to ++put the admin address somewhere convenient. ++ ++@item display ++@cindex display ++Elements that look like @code{(display . MODE)} say which articles to ++display on entering the group. Valid values are: ++ ++@table @code ++@item all ++Display all articles, both read and unread. ++ ++@item an integer ++Display the last @var{integer} articles in the group. This is the same as ++entering the group with @kbd{C-u @var{integer}}. ++ ++@item default ++Display the default visible articles, which normally includes unread and ++ticked articles. ++ ++@item an array ++Display articles that satisfy a predicate. ++ ++Here are some examples: ++ ++@table @code ++@item [unread] ++Display only unread articles. ++ ++@item [not expire] ++Display everything except expirable articles. ++ ++@item [and (not reply) (not expire)] ++Display everything except expirable and articles you've already ++responded to. ++@end table ++ ++The available operators are @code{not}, @code{and} and @code{or}. ++Predicates include @code{tick}, @code{unsend}, @code{undownload}, ++@code{unread}, @code{dormant}, @code{expire}, @code{reply}, ++@code{killed}, @code{bookmark}, @code{score}, @code{save}, ++@code{cache}, @code{forward}, @code{unseen} and @code{recent}. ++ ++@end table ++ ++The @code{display} parameter works by limiting the summary buffer to ++the subset specified. You can pop the limit by using the @kbd{/ w} ++command (@pxref{Limiting}). ++ ++@item comment ++@cindex comment ++Elements that look like @code{(comment . "This is a comment")} are ++arbitrary comments on the group. You can display comments in the ++group line (@pxref{Group Line Specification}). ++ ++@item charset ++@cindex charset ++Elements that look like @code{(charset . iso-8859-1)} will make ++@code{iso-8859-1} the default charset; that is, the charset that will be ++used for all articles that do not specify a charset. ++ ++See also @code{gnus-group-charset-alist}. ++ ++@item ignored-charsets ++@cindex ignored-charset ++Elements that look like @code{(ignored-charsets x-unknown iso-8859-1)} ++will make @code{iso-8859-1} and @code{x-unknown} ignored; that is, the ++default charset will be used for decoding articles. ++ ++See also @code{gnus-group-ignored-charsets-alist}. ++ ++@item posting-style ++@cindex posting-style ++You can store additional posting style information for this group ++here (@pxref{Posting Styles}). The format is that of an entry in the ++@code{gnus-posting-styles} alist, except that there's no regexp matching ++the group name (of course). Style elements in this group parameter will ++take precedence over the ones found in @code{gnus-posting-styles}. ++ ++For instance, if you want a funky name and signature in this group only, ++instead of hacking @code{gnus-posting-styles}, you could put something ++like this in the group parameters: ++ ++@example ++(posting-style ++ (name "Funky Name") ++ ("X-My-Header" "Funky Value") ++ (signature "Funky Signature")) ++@end example ++ ++If you're using topics to organize your group buffer ++(@pxref{Group Topics}), note that posting styles can also be set in ++the topics parameters. Posting styles in topic parameters apply to all ++groups in this topic. More precisely, the posting-style settings for a ++group result from the hierarchical merging of all posting-style ++entries in the parameters of this group and all the topics it belongs ++to. ++ ++ ++@item post-method ++@cindex post-method ++If it is set, the value is used as the method for posting message ++instead of @code{gnus-post-method}. ++ ++@item mail-source ++@cindex mail-source ++If it is set, and the setting of @code{mail-sources} includes a ++@code{group} mail source (@pxref{Mail Sources}), the value is a ++mail source for this group. ++ ++@item banner ++@cindex banner ++An item like @code{(banner . @var{regexp})} causes any part of an article ++that matches the regular expression @var{regexp} to be stripped. Instead of ++@var{regexp}, you can also use the symbol @code{signature} which strips the ++last signature or any of the elements of the alist ++@code{gnus-article-banner-alist}. ++ ++@item sieve ++@cindex sieve ++This parameter contains a Sieve test that should match incoming mail ++that should be placed in this group. From this group parameter, a ++Sieve @samp{IF} control structure is generated, having the test as the ++condition and @samp{fileinto "group.name";} as the body. ++ ++For example, if the @samp{INBOX.list.sieve} group has the @code{(sieve ++address "sender" "sieve-admin@@extundo.com")} group parameter, when ++translating the group parameter into a Sieve script (@pxref{Sieve ++Commands}) the following Sieve code is generated: ++ ++@example ++if address "sender" "sieve-admin@@extundo.com" @{ ++ fileinto "INBOX.list.sieve"; ++@} ++@end example ++ ++To generate tests for multiple email-addresses use a group parameter ++like @code{(sieve address "sender" ("name@@one.org" else@@two.org"))}. ++When generating a sieve script (@pxref{Sieve Commands}) Sieve code ++like the following is generated: ++ ++@example ++if address "sender" ["name@@one.org", "else@@two.org"] @{ ++ fileinto "INBOX.list.sieve"; ++@} ++@end example ++ ++See @pxref{Sieve Commands} for commands and variables that might be of ++interest in relation to the sieve parameter. ++ ++The Sieve language is described in RFC 3028. @xref{Top, Emacs Sieve, ++Top, sieve, Emacs Sieve}. ++ ++@item (agent parameters) ++If the agent has been enabled, you can set any of the its parameters ++to control the behavior of the agent in individual groups. See Agent ++Parameters in @ref{Category Syntax}. Most users will choose to set ++agent parameters in either an agent category or group topic to ++minimize the configuration effort. ++ ++@item (@var{variable} @var{form}) ++You can use the group parameters to set variables local to the group you ++are entering. If you want to turn threading off in @samp{news.answers}, ++you could put @code{(gnus-show-threads nil)} in the group parameters of ++that group. @code{gnus-show-threads} will be made into a local variable ++in the summary buffer you enter, and the form @code{nil} will be ++@code{eval}ed there. ++ ++Note that this feature sets the variable locally to the summary buffer ++if and only if @var{variable} has been bound as a variable. Otherwise, ++only evaluating the form will take place. So, you may want to bind the ++variable in advance using @code{defvar} or other if the result of the ++form needs to be set to it. ++ ++But some variables are evaluated in the article buffer, or in the ++message buffer (of a reply or followup or otherwise newly created ++message). As a workaround, it might help to add the variable in ++question to @code{gnus-newsgroup-variables}. @xref{Various Summary ++Stuff}. So if you want to set @code{message-from-style} via the group ++parameters, then you may need the following statement elsewhere in your ++@file{~/.gnus.el} file: ++ ++@lisp ++(add-to-list 'gnus-newsgroup-variables 'message-from-style) ++@end lisp ++ ++@vindex gnus-list-identifiers ++A use for this feature is to remove a mailing list identifier tag in ++the subject fields of articles. E.g. if the news group ++ ++@example ++nntp+news.gnus.org:gmane.text.docbook.apps ++@end example ++ ++has the tag @samp{DOC-BOOK-APPS:} in the subject of all articles, this ++tag can be removed from the article subjects in the summary buffer for ++the group by putting @code{(gnus-list-identifiers "DOCBOOK-APPS:")} ++into the group parameters for the group. ++ ++This can also be used as a group-specific hook function. If you want to ++hear a beep when you enter a group, you could put something like ++@code{(dummy-variable (ding))} in the parameters of that group. If ++@code{dummy-variable} has been bound (see above), it will be set to the ++(meaningless) result of the @code{(ding)} form. ++ ++Alternatively, since the VARIABLE becomes local to the group, this ++pattern can be used to temporarily change a hook. For example, if the ++following is added to a group parameter ++ ++@lisp ++(gnus-summary-prepared-hook ++ '(lambda nil (local-set-key "d" (local-key-binding "n")))) ++@end lisp ++ ++when the group is entered, the 'd' key will not mark the article as ++expired. ++ ++@end table ++ ++@vindex gnus-parameters ++Group parameters can be set via the @code{gnus-parameters} variable too. ++But some variables, such as @code{visible}, have no effect (For this ++case see @code{gnus-permanently-visible-groups} as an alternative.). ++For example: ++ ++@lisp ++(setq gnus-parameters ++ '(("mail\\..*" ++ (gnus-show-threads nil) ++ (gnus-use-scoring nil) ++ (gnus-summary-line-format ++ "%U%R%z%I%(%[%d:%ub%-23,23f%]%) %s\n") ++ (gcc-self . t) ++ (display . all)) ++ ++ ("^nnimap:\\(foo.bar\\)$" ++ (to-group . "\\1")) ++ ++ ("mail\\.me" ++ (gnus-use-scoring t)) ++ ++ ("list\\..*" ++ (total-expire . t) ++ (broken-reply-to . t)))) ++@end lisp ++ ++String value of parameters will be subjected to regexp substitution, as ++the @code{to-group} example shows. ++ ++@vindex gnus-parameters-case-fold-search ++By default, whether comparing the group name and one of those regexps ++specified in @code{gnus-parameters} is done in a case-sensitive manner ++or a case-insensitive manner depends on the value of ++@code{case-fold-search} at the time when the comparison is done. The ++value of @code{case-fold-search} is typically @code{t}; it means, for ++example, the element @code{("INBOX\\.FOO" (total-expire . t))} might be ++applied to both the @samp{INBOX.FOO} group and the @samp{INBOX.foo} ++group. If you want to make those regexps always case-sensitive, set the ++value of the @code{gnus-parameters-case-fold-search} variable to ++@code{nil}. Otherwise, set it to @code{t} if you want to compare them ++always in a case-insensitive manner. ++ ++You can define different sorting to different groups via ++@code{gnus-parameters}. Here is an example to sort an @acronym{NNTP} ++group by reverse date to see the latest news at the top and an ++@acronym{RSS} group by subject. In this example, the first group is the ++Debian daily news group @code{gmane.linux.debian.user.news} from ++news.gmane.org. The @acronym{RSS} group corresponds to the Debian ++weekly news RSS feed ++@url{http://packages.debian.org/unstable/newpkg_main.en.rdf}, ++@xref{RSS}. ++ ++@lisp ++(setq ++ gnus-parameters ++ '(("nntp.*gmane\\.debian\\.user\\.news" ++ (gnus-show-threads nil) ++ (gnus-article-sort-functions '((not gnus-article-sort-by-date))) ++ (gnus-use-adaptive-scoring nil) ++ (gnus-use-scoring nil)) ++ ("nnrss.*debian" ++ (gnus-show-threads nil) ++ (gnus-article-sort-functions 'gnus-article-sort-by-subject) ++ (gnus-use-adaptive-scoring nil) ++ (gnus-use-scoring t) ++ (gnus-score-find-score-files-function 'gnus-score-find-single) ++ (gnus-summary-line-format "%U%R%z%d %I%(%[ %s %]%)\n")))) ++@end lisp ++ ++ ++@node Listing Groups ++@section Listing Groups ++@cindex group listing ++ ++These commands all list various slices of the groups available. ++ ++@table @kbd ++ ++@item l ++@itemx A s ++@kindex A s (Group) ++@kindex l (Group) ++@findex gnus-group-list-groups ++List all groups that have unread articles ++(@code{gnus-group-list-groups}). If the numeric prefix is used, this ++command will list only groups of level ARG and lower. By default, it ++only lists groups of level five (i.e., ++@code{gnus-group-default-list-level}) or lower (i.e., just subscribed ++groups). ++ ++@item L ++@itemx A u ++@kindex A u (Group) ++@kindex L (Group) ++@findex gnus-group-list-all-groups ++List all groups, whether they have unread articles or not ++(@code{gnus-group-list-all-groups}). If the numeric prefix is used, ++this command will list only groups of level ARG and lower. By default, ++it lists groups of level seven or lower (i.e., just subscribed and ++unsubscribed groups). ++ ++@item A l ++@kindex A l (Group) ++@findex gnus-group-list-level ++List all unread groups on a specific level ++(@code{gnus-group-list-level}). If given a prefix, also list the groups ++with no unread articles. ++ ++@item A k ++@kindex A k (Group) ++@findex gnus-group-list-killed ++List all killed groups (@code{gnus-group-list-killed}). If given a ++prefix argument, really list all groups that are available, but aren't ++currently (un)subscribed. This could entail reading the active file ++from the server. ++ ++@item A z ++@kindex A z (Group) ++@findex gnus-group-list-zombies ++List all zombie groups (@code{gnus-group-list-zombies}). ++ ++@item A m ++@kindex A m (Group) ++@findex gnus-group-list-matching ++List all unread, subscribed groups with names that match a regexp ++(@code{gnus-group-list-matching}). ++ ++@item A M ++@kindex A M (Group) ++@findex gnus-group-list-all-matching ++List groups that match a regexp (@code{gnus-group-list-all-matching}). ++ ++@item A A ++@kindex A A (Group) ++@findex gnus-group-list-active ++List absolutely all groups in the active file(s) of the ++server(s) you are connected to (@code{gnus-group-list-active}). This ++might very well take quite a while. It might actually be a better idea ++to do a @kbd{A M} to list all matching, and just give @samp{.} as the ++thing to match on. Also note that this command may list groups that ++don't exist (yet)---these will be listed as if they were killed groups. ++Take the output with some grains of salt. ++ ++@item A a ++@kindex A a (Group) ++@findex gnus-group-apropos ++List all groups that have names that match a regexp ++(@code{gnus-group-apropos}). ++ ++@item A d ++@kindex A d (Group) ++@findex gnus-group-description-apropos ++List all groups that have names or descriptions that match a regexp ++(@code{gnus-group-description-apropos}). ++ ++@item A c ++@kindex A c (Group) ++@findex gnus-group-list-cached ++List all groups with cached articles (@code{gnus-group-list-cached}). ++ ++@item A ? ++@kindex A ? (Group) ++@findex gnus-group-list-dormant ++List all groups with dormant articles (@code{gnus-group-list-dormant}). ++ ++@item A / ++@kindex A / (Group) ++@findex gnus-group-list-limit ++List groups limited within the current selection ++(@code{gnus-group-list-limit}). ++ ++@item A f ++@kindex A f (Group) ++@findex gnus-group-list-flush ++Flush groups from the current selection (@code{gnus-group-list-flush}). ++ ++@item A p ++@kindex A p (Group) ++@findex gnus-group-list-plus ++List groups plus the current selection (@code{gnus-group-list-plus}). ++ ++@end table ++ ++@vindex gnus-permanently-visible-groups ++@cindex visible group parameter ++Groups that match the @code{gnus-permanently-visible-groups} regexp will ++always be shown, whether they have unread articles or not. You can also ++add the @code{visible} element to the group parameters in question to ++get the same effect. ++ ++@vindex gnus-list-groups-with-ticked-articles ++Groups that have just ticked articles in it are normally listed in the ++group buffer. If @code{gnus-list-groups-with-ticked-articles} is ++@code{nil}, these groups will be treated just like totally empty ++groups. It is @code{t} by default. ++ ++ ++@node Sorting Groups ++@section Sorting Groups ++@cindex sorting groups ++ ++@kindex C-c C-s (Group) ++@findex gnus-group-sort-groups ++@vindex gnus-group-sort-function ++The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the ++group buffer according to the function(s) given by the ++@code{gnus-group-sort-function} variable. Available sorting functions ++include: ++ ++@table @code ++ ++@item gnus-group-sort-by-alphabet ++@findex gnus-group-sort-by-alphabet ++Sort the group names alphabetically. This is the default. ++ ++@item gnus-group-sort-by-real-name ++@findex gnus-group-sort-by-real-name ++Sort the group alphabetically on the real (unprefixed) group names. ++ ++@item gnus-group-sort-by-level ++@findex gnus-group-sort-by-level ++Sort by group level. ++ ++@item gnus-group-sort-by-score ++@findex gnus-group-sort-by-score ++Sort by group score. @xref{Group Score}. ++ ++@item gnus-group-sort-by-rank ++@findex gnus-group-sort-by-rank ++Sort by group score and then the group level. The level and the score ++are, when taken together, the group's @dfn{rank}. @xref{Group Score}. ++ ++@item gnus-group-sort-by-unread ++@findex gnus-group-sort-by-unread ++Sort by number of unread articles. ++ ++@item gnus-group-sort-by-method ++@findex gnus-group-sort-by-method ++Sort alphabetically on the select method. ++ ++@item gnus-group-sort-by-server ++@findex gnus-group-sort-by-server ++Sort alphabetically on the Gnus server name. ++ ++ ++@end table ++ ++@code{gnus-group-sort-function} can also be a list of sorting ++functions. In that case, the most significant sort key function must be ++the last one. ++ ++ ++There are also a number of commands for sorting directly according to ++some sorting criteria: ++ ++@table @kbd ++@item G S a ++@kindex G S a (Group) ++@findex gnus-group-sort-groups-by-alphabet ++Sort the group buffer alphabetically by group name ++(@code{gnus-group-sort-groups-by-alphabet}). ++ ++@item G S u ++@kindex G S u (Group) ++@findex gnus-group-sort-groups-by-unread ++Sort the group buffer by the number of unread articles ++(@code{gnus-group-sort-groups-by-unread}). ++ ++@item G S l ++@kindex G S l (Group) ++@findex gnus-group-sort-groups-by-level ++Sort the group buffer by group level ++(@code{gnus-group-sort-groups-by-level}). ++ ++@item G S v ++@kindex G S v (Group) ++@findex gnus-group-sort-groups-by-score ++Sort the group buffer by group score ++(@code{gnus-group-sort-groups-by-score}). @xref{Group Score}. ++ ++@item G S r ++@kindex G S r (Group) ++@findex gnus-group-sort-groups-by-rank ++Sort the group buffer by group rank ++(@code{gnus-group-sort-groups-by-rank}). @xref{Group Score}. ++ ++@item G S m ++@kindex G S m (Group) ++@findex gnus-group-sort-groups-by-method ++Sort the group buffer alphabetically by back end name@* ++(@code{gnus-group-sort-groups-by-method}). ++ ++@item G S n ++@kindex G S n (Group) ++@findex gnus-group-sort-groups-by-real-name ++Sort the group buffer alphabetically by real (unprefixed) group name ++(@code{gnus-group-sort-groups-by-real-name}). ++ ++@end table ++ ++All the commands below obey the process/prefix convention ++(@pxref{Process/Prefix}). ++ ++When given a symbolic prefix (@pxref{Symbolic Prefixes}), all these ++commands will sort in reverse order. ++ ++You can also sort a subset of the groups: ++ ++@table @kbd ++@item G P a ++@kindex G P a (Group) ++@findex gnus-group-sort-selected-groups-by-alphabet ++Sort the groups alphabetically by group name ++(@code{gnus-group-sort-selected-groups-by-alphabet}). ++ ++@item G P u ++@kindex G P u (Group) ++@findex gnus-group-sort-selected-groups-by-unread ++Sort the groups by the number of unread articles ++(@code{gnus-group-sort-selected-groups-by-unread}). ++ ++@item G P l ++@kindex G P l (Group) ++@findex gnus-group-sort-selected-groups-by-level ++Sort the groups by group level ++(@code{gnus-group-sort-selected-groups-by-level}). ++ ++@item G P v ++@kindex G P v (Group) ++@findex gnus-group-sort-selected-groups-by-score ++Sort the groups by group score ++(@code{gnus-group-sort-selected-groups-by-score}). @xref{Group Score}. ++ ++@item G P r ++@kindex G P r (Group) ++@findex gnus-group-sort-selected-groups-by-rank ++Sort the groups by group rank ++(@code{gnus-group-sort-selected-groups-by-rank}). @xref{Group Score}. ++ ++@item G P m ++@kindex G P m (Group) ++@findex gnus-group-sort-selected-groups-by-method ++Sort the groups alphabetically by back end name@* ++(@code{gnus-group-sort-selected-groups-by-method}). ++ ++@item G P n ++@kindex G P n (Group) ++@findex gnus-group-sort-selected-groups-by-real-name ++Sort the groups alphabetically by real (unprefixed) group name ++(@code{gnus-group-sort-selected-groups-by-real-name}). ++ ++@item G P s ++@kindex G P s (Group) ++@findex gnus-group-sort-selected-groups ++Sort the groups according to @code{gnus-group-sort-function}. ++ ++@end table ++ ++And finally, note that you can use @kbd{C-k} and @kbd{C-y} to manually ++move groups around. ++ ++ ++@node Group Maintenance ++@section Group Maintenance ++@cindex bogus groups ++ ++@table @kbd ++@item b ++@kindex b (Group) ++@findex gnus-group-check-bogus-groups ++Find bogus groups and delete them ++(@code{gnus-group-check-bogus-groups}). ++ ++@item F ++@kindex F (Group) ++@findex gnus-group-find-new-groups ++Find new groups and process them (@code{gnus-group-find-new-groups}). ++With 1 @kbd{C-u}, use the @code{ask-server} method to query the server ++for new groups. With 2 @kbd{C-u}'s, use most complete method possible ++to query the server for new groups, and subscribe the new groups as ++zombies. ++ ++@item C-c C-x ++@kindex C-c C-x (Group) ++@findex gnus-group-expire-articles ++@cindex expiring mail ++Run all expirable articles in the current group through the expiry ++process (if any) (@code{gnus-group-expire-articles}). That is, delete ++all expirable articles in the group that have been around for a while. ++(@pxref{Expiring Mail}). ++ ++@item C-c C-M-x ++@kindex C-c C-M-x (Group) ++@findex gnus-group-expire-all-groups ++@cindex expiring mail ++Run all expirable articles in all groups through the expiry process ++(@code{gnus-group-expire-all-groups}). ++ ++@end table ++ ++ ++@node Browse Foreign Server ++@section Browse Foreign Server ++@cindex foreign servers ++@cindex browsing servers ++ ++@table @kbd ++@item B ++@kindex B (Group) ++@findex gnus-group-browse-foreign-server ++You will be queried for a select method and a server name. Gnus will ++then attempt to contact this server and let you browse the groups there ++(@code{gnus-group-browse-foreign-server}). ++@end table ++ ++@findex gnus-browse-mode ++A new buffer with a list of available groups will appear. This buffer ++will use the @code{gnus-browse-mode}. This buffer looks a bit (well, ++a lot) like a normal group buffer. ++ ++Here's a list of keystrokes available in the browse mode: ++ ++@table @kbd ++@item n ++@kindex n (Browse) ++@findex gnus-group-next-group ++Go to the next group (@code{gnus-group-next-group}). ++ ++@item p ++@kindex p (Browse) ++@findex gnus-group-prev-group ++Go to the previous group (@code{gnus-group-prev-group}). ++ ++@item SPACE ++@kindex SPACE (Browse) ++@findex gnus-browse-read-group ++Enter the current group and display the first article ++(@code{gnus-browse-read-group}). ++ ++@item RET ++@kindex RET (Browse) ++@findex gnus-browse-select-group ++Enter the current group (@code{gnus-browse-select-group}). ++ ++@item u ++@kindex u (Browse) ++@findex gnus-browse-unsubscribe-current-group ++Unsubscribe to the current group, or, as will be the case here, ++subscribe to it (@code{gnus-browse-unsubscribe-current-group}). ++ ++@item l ++@itemx q ++@kindex q (Browse) ++@kindex l (Browse) ++@findex gnus-browse-exit ++Exit browse mode (@code{gnus-browse-exit}). ++ ++@item d ++@kindex d (Browse) ++@findex gnus-browse-describe-group ++Describe the current group (@code{gnus-browse-describe-group}). ++ ++@item ? ++@kindex ? (Browse) ++@findex gnus-browse-describe-briefly ++Describe browse mode briefly (well, there's not much to describe, is ++there) (@code{gnus-browse-describe-briefly}). ++@end table ++ ++ ++@node Exiting Gnus ++@section Exiting Gnus ++@cindex exiting Gnus ++ ++Yes, Gnus is ex(c)iting. ++ ++@table @kbd ++@item z ++@kindex z (Group) ++@findex gnus-group-suspend ++Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus, ++but it kills all buffers except the Group buffer. I'm not sure why this ++is a gain, but then who am I to judge? ++ ++@item q ++@kindex q (Group) ++@findex gnus-group-exit ++@c @icon{gnus-group-exit} ++Quit Gnus (@code{gnus-group-exit}). ++ ++@item Q ++@kindex Q (Group) ++@findex gnus-group-quit ++Quit Gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}). ++The dribble file will be saved, though (@pxref{Auto Save}). ++@end table ++ ++@vindex gnus-exit-gnus-hook ++@vindex gnus-suspend-gnus-hook ++@vindex gnus-after-exiting-gnus-hook ++@code{gnus-suspend-gnus-hook} is called when you suspend Gnus and ++@code{gnus-exit-gnus-hook} is called when you quit Gnus, while ++@code{gnus-after-exiting-gnus-hook} is called as the final item when ++exiting Gnus. ++ ++Note: ++ ++@quotation ++Miss Lisa Cannifax, while sitting in English class, felt her feet go ++numbly heavy and herself fall into a hazy trance as the boy sitting ++behind her drew repeated lines with his pencil across the back of her ++plastic chair. ++@end quotation ++ ++ ++@node Group Topics ++@section Group Topics ++@cindex topics ++ ++If you read lots and lots of groups, it might be convenient to group ++them hierarchically according to topics. You put your Emacs groups over ++here, your sex groups over there, and the rest (what, two groups or so?) ++you put in some misc section that you never bother with anyway. You can ++even group the Emacs sex groups as a sub-topic to either the Emacs ++groups or the sex groups---or both! Go wild! ++ ++@iftex ++@iflatex ++\gnusfigure{Group Topics}{400}{ ++\put(75,50){\epsfig{figure=ps/group-topic,height=9cm}} ++} ++@end iflatex ++@end iftex ++ ++Here's an example: ++ ++@example ++Gnus ++ Emacs -- I wuw it! ++ 3: comp.emacs ++ 2: alt.religion.emacs ++ Naughty Emacs ++ 452: alt.sex.emacs ++ 0: comp.talk.emacs.recovery ++ Misc ++ 8: comp.binaries.fractals ++ 13: comp.sources.unix ++@end example ++ ++@findex gnus-topic-mode ++@kindex t (Group) ++To get this @emph{fab} functionality you simply turn on (ooh!) the ++@code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This ++is a toggling command.) ++ ++Go ahead, just try it. I'll still be here when you get back. La de ++dum@dots{} Nice tune, that@dots{} la la la@dots{} What, you're back? ++Yes, and now press @kbd{l}. There. All your groups are now listed ++under @samp{misc}. Doesn't that make you feel all warm and fuzzy? ++Hot and bothered? ++ ++If you want this permanently enabled, you should add that minor mode to ++the hook for the group mode. Put the following line in your ++@file{~/.gnus.el} file: ++ ++@lisp ++(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) ++@end lisp ++ ++@menu ++* Topic Commands:: Interactive E-Z commands. ++* Topic Variables:: How to customize the topics the Lisp Way. ++* Topic Sorting:: Sorting each topic individually. ++* Topic Topology:: A map of the world. ++* Topic Parameters:: Parameters that apply to all groups in a topic. ++@end menu ++ ++ ++@node Topic Commands ++@subsection Topic Commands ++@cindex topic commands ++ ++When the topic minor mode is turned on, a new @kbd{T} submap will be ++available. In addition, a few of the standard keys change their ++definitions slightly. ++ ++In general, the following kinds of operations are possible on topics. ++First of all, you want to create topics. Secondly, you want to put ++groups in topics and to move them around until you have an order you ++like. The third kind of operation is to show/hide parts of the whole ++shebang. You might want to hide a topic including its subtopics and ++groups, to get a better overview of the other groups. ++ ++Here is a list of the basic keys that you might need to set up topics ++the way you like. ++ ++@table @kbd ++ ++@item T n ++@kindex T n (Topic) ++@findex gnus-topic-create-topic ++Prompt for a new topic name and create it ++(@code{gnus-topic-create-topic}). ++ ++@item T TAB ++@itemx TAB ++@kindex T TAB (Topic) ++@kindex TAB (Topic) ++@findex gnus-topic-indent ++``Indent'' the current topic so that it becomes a sub-topic of the ++previous topic (@code{gnus-topic-indent}). If given a prefix, ++``un-indent'' the topic instead. ++ ++@item M-TAB ++@kindex M-TAB (Topic) ++@findex gnus-topic-unindent ++``Un-indent'' the current topic so that it becomes a sub-topic of the ++parent of its current parent (@code{gnus-topic-unindent}). ++ ++@end table ++ ++The following two keys can be used to move groups and topics around. ++They work like the well-known cut and paste. @kbd{C-k} is like cut and ++@kbd{C-y} is like paste. Of course, this being Emacs, we use the terms ++kill and yank rather than cut and paste. ++ ++@table @kbd ++ ++@item C-k ++@kindex C-k (Topic) ++@findex gnus-topic-kill-group ++Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the ++topic will be removed along with the topic. ++ ++@item C-y ++@kindex C-y (Topic) ++@findex gnus-topic-yank-group ++Yank the previously killed group or topic ++(@code{gnus-topic-yank-group}). Note that all topics will be yanked ++before all groups. ++ ++So, to move a topic to the beginning of the list of topics, just hit ++@kbd{C-k} on it. This is like the ``cut'' part of cut and paste. Then, ++move the cursor to the beginning of the buffer (just below the ``Gnus'' ++topic) and hit @kbd{C-y}. This is like the ``paste'' part of cut and ++paste. Like I said -- E-Z. ++ ++You can use @kbd{C-k} and @kbd{C-y} on groups as well as on topics. So ++you can move topics around as well as groups. ++ ++@end table ++ ++After setting up the topics the way you like them, you might wish to ++hide a topic, or to show it again. That's why we have the following ++key. ++ ++@table @kbd ++ ++@item RET ++@kindex RET (Topic) ++@findex gnus-topic-select-group ++@itemx SPACE ++Either select a group or fold a topic (@code{gnus-topic-select-group}). ++When you perform this command on a group, you'll enter the group, as ++usual. When done on a topic line, the topic will be folded (if it was ++visible) or unfolded (if it was folded already). So it's basically a ++toggling command on topics. In addition, if you give a numerical ++prefix, group on that level (and lower) will be displayed. ++ ++@end table ++ ++Now for a list of other commands, in no particular order. ++ ++@table @kbd ++ ++@item T m ++@kindex T m (Topic) ++@findex gnus-topic-move-group ++Move the current group to some other topic ++(@code{gnus-topic-move-group}). This command uses the process/prefix ++convention (@pxref{Process/Prefix}). ++ ++@item T j ++@kindex T j (Topic) ++@findex gnus-topic-jump-to-topic ++Go to a topic (@code{gnus-topic-jump-to-topic}). ++ ++@item T c ++@kindex T c (Topic) ++@findex gnus-topic-copy-group ++Copy the current group to some other topic ++(@code{gnus-topic-copy-group}). This command uses the process/prefix ++convention (@pxref{Process/Prefix}). ++ ++@item T h ++@kindex T h (Topic) ++@findex gnus-topic-hide-topic ++Hide the current topic (@code{gnus-topic-hide-topic}). If given ++a prefix, hide the topic permanently. ++ ++@item T s ++@kindex T s (Topic) ++@findex gnus-topic-show-topic ++Show the current topic (@code{gnus-topic-show-topic}). If given ++a prefix, show the topic permanently. ++ ++@item T D ++@kindex T D (Topic) ++@findex gnus-topic-remove-group ++Remove a group from the current topic (@code{gnus-topic-remove-group}). ++This command is mainly useful if you have the same group in several ++topics and wish to remove it from one of the topics. You may also ++remove a group from all topics, but in that case, Gnus will add it to ++the root topic the next time you start Gnus. In fact, all new groups ++(which, naturally, don't belong to any topic) will show up in the root ++topic. ++ ++This command uses the process/prefix convention ++(@pxref{Process/Prefix}). ++ ++@item T M ++@kindex T M (Topic) ++@findex gnus-topic-move-matching ++Move all groups that match some regular expression to a topic ++(@code{gnus-topic-move-matching}). ++ ++@item T C ++@kindex T C (Topic) ++@findex gnus-topic-copy-matching ++Copy all groups that match some regular expression to a topic ++(@code{gnus-topic-copy-matching}). ++ ++@item T H ++@kindex T H (Topic) ++@findex gnus-topic-toggle-display-empty-topics ++Toggle hiding empty topics ++(@code{gnus-topic-toggle-display-empty-topics}). ++ ++@item T # ++@kindex T # (Topic) ++@findex gnus-topic-mark-topic ++Mark all groups in the current topic with the process mark ++(@code{gnus-topic-mark-topic}). This command works recursively on ++sub-topics unless given a prefix. ++ ++@item T M-# ++@kindex T M-# (Topic) ++@findex gnus-topic-unmark-topic ++Remove the process mark from all groups in the current topic ++(@code{gnus-topic-unmark-topic}). This command works recursively on ++sub-topics unless given a prefix. ++ ++@item C-c C-x ++@kindex C-c C-x (Topic) ++@findex gnus-topic-expire-articles ++@cindex expiring mail ++Run all expirable articles in the current group or topic through the ++expiry process (if any) ++(@code{gnus-topic-expire-articles}). (@pxref{Expiring Mail}). ++ ++@item T r ++@kindex T r (Topic) ++@findex gnus-topic-rename ++Rename a topic (@code{gnus-topic-rename}). ++ ++@item T DEL ++@kindex T DEL (Topic) ++@findex gnus-topic-delete ++Delete an empty topic (@code{gnus-topic-delete}). ++ ++@item A T ++@kindex A T (Topic) ++@findex gnus-topic-list-active ++List all groups that Gnus knows about in a topics-ified way ++(@code{gnus-topic-list-active}). ++ ++@item T M-n ++@kindex T M-n (Topic) ++@findex gnus-topic-goto-next-topic ++Go to the next topic (@code{gnus-topic-goto-next-topic}). ++ ++@item T M-p ++@kindex T M-p (Topic) ++@findex gnus-topic-goto-previous-topic ++Go to the previous topic (@code{gnus-topic-goto-previous-topic}). ++ ++@item G p ++@kindex G p (Topic) ++@findex gnus-topic-edit-parameters ++@cindex group parameters ++@cindex topic parameters ++@cindex parameters ++Edit the topic parameters (@code{gnus-topic-edit-parameters}). ++@xref{Topic Parameters}. ++ ++@end table ++ ++ ++@node Topic Variables ++@subsection Topic Variables ++@cindex topic variables ++ ++The previous section told you how to tell Gnus which topics to display. ++This section explains how to tell Gnus what to display about each topic. ++ ++@vindex gnus-topic-line-format ++The topic lines themselves are created according to the ++@code{gnus-topic-line-format} variable (@pxref{Formatting Variables}). ++Valid elements are: ++ ++@table @samp ++@item i ++Indentation. ++@item n ++Topic name. ++@item v ++Visibility. ++@item l ++Level. ++@item g ++Number of groups in the topic. ++@item a ++Number of unread articles in the topic. ++@item A ++Number of unread articles in the topic and all its subtopics. ++@end table ++ ++@vindex gnus-topic-indent-level ++Each sub-topic (and the groups in the sub-topics) will be indented with ++@code{gnus-topic-indent-level} times the topic level number of spaces. ++The default is 2. ++ ++@vindex gnus-topic-mode-hook ++@code{gnus-topic-mode-hook} is called in topic minor mode buffers. ++ ++@vindex gnus-topic-display-empty-topics ++The @code{gnus-topic-display-empty-topics} says whether to display even ++topics that have no unread articles in them. The default is @code{t}. ++ ++ ++@node Topic Sorting ++@subsection Topic Sorting ++@cindex topic sorting ++ ++You can sort the groups in each topic individually with the following ++commands: ++ ++ ++@table @kbd ++@item T S a ++@kindex T S a (Topic) ++@findex gnus-topic-sort-groups-by-alphabet ++Sort the current topic alphabetically by group name ++(@code{gnus-topic-sort-groups-by-alphabet}). ++ ++@item T S u ++@kindex T S u (Topic) ++@findex gnus-topic-sort-groups-by-unread ++Sort the current topic by the number of unread articles ++(@code{gnus-topic-sort-groups-by-unread}). ++ ++@item T S l ++@kindex T S l (Topic) ++@findex gnus-topic-sort-groups-by-level ++Sort the current topic by group level ++(@code{gnus-topic-sort-groups-by-level}). ++ ++@item T S v ++@kindex T S v (Topic) ++@findex gnus-topic-sort-groups-by-score ++Sort the current topic by group score ++(@code{gnus-topic-sort-groups-by-score}). @xref{Group Score}. ++ ++@item T S r ++@kindex T S r (Topic) ++@findex gnus-topic-sort-groups-by-rank ++Sort the current topic by group rank ++(@code{gnus-topic-sort-groups-by-rank}). @xref{Group Score}. ++ ++@item T S m ++@kindex T S m (Topic) ++@findex gnus-topic-sort-groups-by-method ++Sort the current topic alphabetically by back end name ++(@code{gnus-topic-sort-groups-by-method}). ++ ++@item T S e ++@kindex T S e (Topic) ++@findex gnus-topic-sort-groups-by-server ++Sort the current topic alphabetically by server name ++(@code{gnus-topic-sort-groups-by-server}). ++ ++@item T S s ++@kindex T S s (Topic) ++@findex gnus-topic-sort-groups ++Sort the current topic according to the function(s) given by the ++@code{gnus-group-sort-function} variable ++(@code{gnus-topic-sort-groups}). ++ ++@end table ++ ++When given a prefix argument, all these commands will sort in reverse ++order. @xref{Sorting Groups}, for more information about group ++sorting. ++ ++ ++@node Topic Topology ++@subsection Topic Topology ++@cindex topic topology ++@cindex topology ++ ++So, let's have a look at an example group buffer: ++ ++@example ++@group ++Gnus ++ Emacs -- I wuw it! ++ 3: comp.emacs ++ 2: alt.religion.emacs ++ Naughty Emacs ++ 452: alt.sex.emacs ++ 0: comp.talk.emacs.recovery ++ Misc ++ 8: comp.binaries.fractals ++ 13: comp.sources.unix ++@end group ++@end example ++ ++So, here we have one top-level topic (@samp{Gnus}), two topics under ++that, and one sub-topic under one of the sub-topics. (There is always ++just one (1) top-level topic). This topology can be expressed as ++follows: ++ ++@lisp ++(("Gnus" visible) ++ (("Emacs -- I wuw it!" visible) ++ (("Naughty Emacs" visible))) ++ (("Misc" visible))) ++@end lisp ++ ++@vindex gnus-topic-topology ++This is in fact how the variable @code{gnus-topic-topology} would look ++for the display above. That variable is saved in the @file{.newsrc.eld} ++file, and shouldn't be messed with manually---unless you really want ++to. Since this variable is read from the @file{.newsrc.eld} file, ++setting it in any other startup files will have no effect. ++ ++This topology shows what topics are sub-topics of what topics (right), ++and which topics are visible. Two settings are currently ++allowed---@code{visible} and @code{invisible}. ++ ++ ++@node Topic Parameters ++@subsection Topic Parameters ++@cindex topic parameters ++ ++All groups in a topic will inherit group parameters from the parent ++(and ancestor) topic parameters. All valid group parameters are valid ++topic parameters (@pxref{Group Parameters}). When the agent is ++enabled, all agent parameters (See Agent Parameters in @ref{Category ++Syntax}) are also valid topic parameters. ++ ++In addition, the following parameters are only valid as topic ++parameters: ++ ++@table @code ++@item subscribe ++When subscribing new groups by topic (@pxref{Subscription Methods}), the ++@code{subscribe} topic parameter says what groups go in what topic. Its ++value should be a regexp to match the groups that should go in that ++topic. ++ ++@item subscribe-level ++When subscribing new groups by topic (see the @code{subscribe} parameter), ++the group will be subscribed with the level specified in the ++@code{subscribe-level} instead of @code{gnus-level-default-subscribed}. ++ ++@end table ++ ++Group parameters (of course) override topic parameters, and topic ++parameters in sub-topics override topic parameters in super-topics. You ++know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a ++verb, although you may feel free to disagree with me here.) ++ ++@example ++@group ++Gnus ++ Emacs ++ 3: comp.emacs ++ 2: alt.religion.emacs ++ 452: alt.sex.emacs ++ Relief ++ 452: alt.sex.emacs ++ 0: comp.talk.emacs.recovery ++ Misc ++ 8: comp.binaries.fractals ++ 13: comp.sources.unix ++ 452: alt.sex.emacs ++@end group ++@end example ++ ++The @samp{Emacs} topic has the topic parameter @code{(score-file ++. "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter ++@code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the ++topic parameter @code{(score-file . "emacs.SCORE")}. In addition, ++@* @samp{alt.religion.emacs} has the group parameter @code{(score-file ++. "religion.SCORE")}. ++ ++Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you ++will get the @file{relief.SCORE} home score file. If you enter the same ++group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home ++score file. If you enter the group @samp{alt.religion.emacs}, you'll ++get the @file{religion.SCORE} home score file. ++ ++This seems rather simple and self-evident, doesn't it? Well, yes. But ++there are some problems, especially with the @code{total-expiry} ++parameter. Say you have a mail group in two topics; one with ++@code{total-expiry} and one without. What happens when you do @kbd{M-x ++gnus-expire-all-expirable-groups}? Gnus has no way of telling which one ++of these topics you mean to expire articles from, so anything may ++happen. In fact, I hereby declare that it is @dfn{undefined} what ++happens. You just have to be careful if you do stuff like that. ++ ++ ++@node Non-ASCII Group Names ++@section Accessing groups of non-English names ++@cindex non-ascii group names ++ ++There are some news servers that provide groups of which the names are ++expressed with their native languages in the world. For instance, in a ++certain news server there are some newsgroups of which the names are ++spelled in Chinese, where people are talking in Chinese. You can, of ++course, subscribe to such news groups using Gnus. Currently Gnus ++supports non-@acronym{ASCII} group names not only with the @code{nntp} ++back end but also with the @code{nnml} back end and the @code{nnrss} ++back end. ++ ++Every such group name is encoded by a certain charset in the server ++side (in an @acronym{NNTP} server its administrator determines the ++charset, but for groups in the other back ends it is determined by you). ++Gnus has to display the decoded ones for you in the group buffer and the ++article buffer, and needs to use the encoded ones when communicating ++with servers. However, Gnus doesn't know what charset is used for each ++non-@acronym{ASCII} group name. The following two variables are just ++the ones for telling Gnus what charset should be used for each group: ++ ++@table @code ++@item gnus-group-name-charset-method-alist ++@vindex gnus-group-name-charset-method-alist ++An alist of select methods and charsets. The default value is ++@code{nil}. The names of groups in the server specified by that select ++method are all supposed to use the corresponding charset. For example: ++ ++@lisp ++(setq gnus-group-name-charset-method-alist ++ '(((nntp "news.com.cn") . cn-gb-2312))) ++@end lisp ++ ++Charsets specified for groups with this variable are preferred to the ++ones specified for the same groups with the ++@code{gnus-group-name-charset-group-alist} variable (see below). ++ ++A select method can be very long, like: ++ ++@lisp ++(nntp "gmane" ++ (nntp-address "news.gmane.org") ++ (nntp-end-of-line "\n") ++ (nntp-open-connection-function ++ nntp-open-via-rlogin-and-telnet) ++ (nntp-via-rlogin-command "ssh") ++ (nntp-via-rlogin-command-switches ++ ("-C" "-t" "-e" "none")) ++ (nntp-via-address @dots{})) ++@end lisp ++ ++In that case, you can truncate it into @code{(nntp "gmane")} in this ++variable. That is, it is enough to contain only the back end name and ++the server name. ++ ++@item gnus-group-name-charset-group-alist ++@cindex UTF-8 group names ++@vindex gnus-group-name-charset-group-alist ++An alist of regexp of group name and the charset for group names. ++@code{((".*" . utf-8))} is the default value if UTF-8 is supported, ++otherwise the default is @code{nil}. For example: ++ ++@lisp ++(setq gnus-group-name-charset-group-alist ++ '(("\\.com\\.cn:" . cn-gb-2312) ++ (".*" . utf-8))) ++@end lisp ++ ++Note that this variable is ignored if the match is made with ++@code{gnus-group-name-charset-method-alist}. ++@end table ++ ++Those two variables are used also to determine the charset for encoding ++and decoding non-@acronym{ASCII} group names that are in the back ends ++other than @code{nntp}. It means that it is you who determine it. If ++you do nothing, the charset used for group names in those back ends will ++all be @code{utf-8} because of the last element of ++@code{gnus-group-name-charset-group-alist}. ++ ++There is one more important variable for non-@acronym{ASCII} group ++names: ++ ++@table @code ++@item nnmail-pathname-coding-system ++@vindex nnmail-pathname-coding-system ++The value of this variable should be a coding system or @code{nil}. The ++default is @code{nil} in Emacs, or is the aliasee of the coding system ++named @code{file-name} (a certain coding system of which an alias is ++@code{file-name}) in XEmacs. ++ ++The @code{nnml} back end, the @code{nnrss} back end, the @acronym{NNTP} ++marks feature (@pxref{NNTP marks}), the agent, and the cache use ++non-@acronym{ASCII} group names in those files and directories. This ++variable overrides the value of @code{file-name-coding-system} which ++specifies the coding system used when encoding and decoding those file ++names and directory names. ++ ++In XEmacs (with the @code{mule} feature), @code{file-name-coding-system} ++is the only means to specify the coding system used to encode and decode ++file names. On the other hand, Emacs uses the value of ++@code{default-file-name-coding-system} if @code{file-name-coding-system} ++is @code{nil} or it is bound to the value of ++@code{nnmail-pathname-coding-system} which is @code{nil}. ++ ++Normally the value of @code{default-file-name-coding-system} in Emacs or ++@code{nnmail-pathname-coding-system} in XEmacs is initialized according ++to the locale, so you will need to do nothing if the value is suitable ++to encode and decode non-@acronym{ASCII} group names. ++ ++The value of this variable (or @code{default-file-name-coding-system}) ++does not necessarily need to be the same value that is determined by ++@code{gnus-group-name-charset-method-alist} and ++@code{gnus-group-name-charset-group-alist}. ++ ++If @code{default-file-name-coding-system} or this variable is ++initialized by default to @code{iso-latin-1} for example, although you ++want to subscribe to the groups spelled in Chinese, that is the most ++typical case where you have to customize ++@code{nnmail-pathname-coding-system}. The @code{utf-8} coding system is ++a good candidate for it. Otherwise, you may change the locale in your ++system so that @code{default-file-name-coding-system} or this variable ++may be initialized to an appropriate value. ++@end table ++ ++Note that when you copy or move articles from a non-@acronym{ASCII} ++group to another group, the charset used to encode and decode group ++names should be the same in both groups. Otherwise the Newsgroups ++header will be displayed incorrectly in the article buffer. ++ ++ ++@node Searching ++@section Searching ++ ++@menu ++* nnir:: Searching on IMAP, with swish, namazu, etc. ++* nnmairix:: Searching maildir, MH or mbox with Mairix. ++@end menu ++ ++@cindex Searching ++ ++FIXME: This node is a stub. ++ ++FIXME: Add a brief overview of Gnus search capabilities. A brief ++comparison of nnir, nnmairix, contrib/gnus-namazu would be nice ++as well. ++ ++FIXME: Explain difference to @ref{Searching for Articles}, add reference ++and back-reference. ++ ++@node nnir ++@subsection nnir ++ ++FIXME: As a first step, convert the commentary of @file{nnir} to texi. ++@cindex nnir ++ ++@node nnmairix ++@subsection nnmairix ++ ++@cindex mairix ++@cindex nnmairix ++This paragraph describes how to set up mairix and the back end ++@code{nnmairix} for indexing and searching your mail from within ++Gnus. Additionally, you can create permanent ``smart'' groups which are ++bound to mairix searches and are automatically updated. ++ ++@menu ++* About mairix:: About the mairix mail search engine ++* nnmairix requirements:: What you will need for using nnmairix ++* What nnmairix does:: What does nnmairix actually do? ++* Setting up mairix:: Set up your mairix installation ++* Configuring nnmairix:: Set up the nnmairix back end ++* nnmairix keyboard shortcuts:: List of available keyboard shortcuts ++* Propagating marks:: How to propagate marks from nnmairix groups ++* nnmairix tips and tricks:: Some tips, tricks and examples ++* nnmairix caveats:: Some more stuff you might want to know ++@end menu ++ ++@c FIXME: The markup in this section might need improvement. ++@c E.g. adding @samp, @var, @file, @command, etc. ++@c Cf. (info "(texinfo)Indicating") ++ ++@node About mairix ++@subsubsection About mairix ++ ++Mairix is a tool for indexing and searching words in locally stored ++mail. It was written by Richard Curnow and is licensed under the ++GPL. Mairix comes with most popular GNU/Linux distributions, but it also ++runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can ++be found at ++@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} ++ ++Though mairix might not be as flexible as other search tools like ++swish++ or namazu, which you can use via the @code{nnir} back end, it ++has the prime advantage of being incredibly fast. On current systems, it ++can easily search through headers and message bodies of thousands and ++thousands of mails in well under a second. Building the database ++necessary for searching might take a minute or two, but only has to be ++done once fully. Afterwards, the updates are done incrementally and ++therefore are really fast, too. Additionally, mairix is very easy to set ++up. ++ ++For maximum speed though, mairix should be used with mails stored in ++@code{Maildir} or @code{MH} format (this includes the @code{nnml} back ++end), although it also works with mbox. Mairix presents the search ++results by populating a @emph{virtual} maildir/MH folder with symlinks ++which point to the ``real'' message files (if mbox is used, copies are ++made). Since mairix already presents search results in such a virtual ++mail folder, it is very well suited for using it as an external program ++for creating @emph{smart} mail folders, which represent certain mail ++searches. This is similar to a Kiboze group (@pxref{Kibozed Groups}), ++but much faster. ++ ++@node nnmairix requirements ++@subsubsection nnmairix requirements ++ ++Mairix searches local mail---that means, mairix absolutely must have ++direct access to your mail folders. If your mail resides on another ++server (e.g. an @acronym{IMAP} server) and you happen to have shell ++access, @code{nnmairix} supports running mairix remotely, e.g. via ssh. ++ ++Additionally, @code{nnmairix} only supports the following Gnus back ++ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use ++one of these back ends for using @code{nnmairix}. Other back ends, like ++@code{nnmbox}, @code{nnfolder} or @code{nnmh}, won't work. ++ ++If you absolutely must use mbox and still want to use @code{nnmairix}, ++you can set up a local @acronym{IMAP} server, which you then access via ++@code{nnimap}. This is a rather massive setup for accessing some mbox ++files, so just change to MH or Maildir already... However, if you're ++really, really passionate about using mbox, you might want to look into ++the package @file{mairix.el}, which comes with Emacs 23. ++ ++@node What nnmairix does ++@subsubsection What nnmairix does ++ ++The back end @code{nnmairix} enables you to call mairix from within Gnus, ++either to query mairix with a search term or to update the ++database. While visiting a message in the summary buffer, you can use ++several pre-defined shortcuts for calling mairix, e.g. to quickly ++search for all mails from the sender of the current message or to ++display the whole thread associated with the message, even if the ++mails are in different folders. ++ ++Additionally, you can create permanent @code{nnmairix} groups which are bound ++to certain mairix searches. This way, you can easily create a group ++containing mails from a certain sender, with a certain subject line or ++even for one specific thread based on the Message-ID. If you check for ++new mail in these folders (e.g. by pressing @kbd{g} or @kbd{M-g}), they ++automatically update themselves by calling mairix. ++ ++You might ask why you need @code{nnmairix} at all, since mairix already ++creates the group, populates it with links to the mails so that you can ++then access it with Gnus, right? Well, this @emph{might} work, but often ++does not---at least not without problems. Most probably you will get ++strange article counts, and sometimes you might see mails which Gnus ++claims have already been canceled and are inaccessible. This is due to ++the fact that Gnus isn't really amused when things are happening behind ++its back. Another problem can be the mail back end itself, e.g. if you ++use mairix with an @acronym{IMAP} server (I had Dovecot complaining ++about corrupt index files when mairix changed the contents of the search ++group). Using @code{nnmairix} should circumvent these problems. ++ ++@code{nnmairix} is not really a mail back end---it's actually more like ++a wrapper, sitting between a ``real'' mail back end where mairix stores ++the searches and the Gnus front end. You can choose between three ++different mail back ends for the mairix folders: @code{nnml}, ++@code{nnmaildir} or @code{nnimap}. @code{nnmairix} will call the mairix ++binary so that the search results are stored in folders named ++@code{zz_mairix--} on this mail back end, but it will ++present these folders in the Gnus front end only with @code{}. ++You can use an existing mail back end where you already store your mail, ++but if you're uncomfortable with @code{nnmairix} creating new mail ++groups alongside your other mail, you can also create e.g. a new ++@code{nnmaildir} or @code{nnml} server exclusively for mairix, but then ++make sure those servers do not accidentally receive your new mail ++(@pxref{nnmairix caveats}). A special case exists if you want to use ++mairix remotely on an IMAP server with @code{nnimap}---here the mairix ++folders and your other mail must be on the same @code{nnimap} back end. ++ ++@node Setting up mairix ++@subsubsection Setting up mairix ++ ++First: create a backup of your mail folders (@pxref{nnmairix caveats}). ++ ++Setting up mairix is easy: simply create a @file{.mairixrc} file with ++(at least) the following entries: ++ ++@example ++# Your Maildir/MH base folder ++base=~/Maildir ++@end example ++ ++This is the base folder for your mails. All the following directories ++are relative to this base folder. If you want to use @code{nnmairix} ++with @code{nnimap}, this base directory has to point to the mail ++directory where the @acronym{IMAP} server stores the mail folders! ++ ++@example ++maildir= ... your maildir folders which should be indexed ... ++mh= ... your nnml/mh folders which should be indexed ... ++mbox = ... your mbox files which should be indexed ... ++@end example ++ ++This specifies all your mail folders and mbox files (relative to the ++base directory!) you want to index with mairix. Note that the ++@code{nnml} back end saves mails in MH format, so you have to put those ++directories in the @code{mh} line. See the example at the end of this ++section and mairixrc's man-page for further details. ++ ++@example ++omit=zz_mairix-* ++@end example ++ ++@vindex nnmairix-group-prefix ++This should make sure that you don't accidentally index the mairix ++search results. You can change the prefix of these folders with the ++variable @code{nnmairix-group-prefix}. ++ ++@example ++mformat= ... 'maildir' or 'mh' ... ++database= ... location of database file ... ++@end example ++ ++The @code{format} setting specifies the output format for the mairix ++search folder. Set this to @code{mh} if you want to access search results ++with @code{nnml}. Otherwise choose @code{maildir}. ++ ++To summarize, here is my shortened @file{.mairixrc} file as an example: ++ ++@example ++base=~/Maildir ++maildir=.personal:.work:.logcheck:.sent ++mh=../Mail/nnml/*... ++mbox=../mboxmail/mailarchive_year* ++mformat=maildir ++omit=zz_mairix-* ++database=~/.mairixdatabase ++@end example ++ ++In this case, the base directory is @file{~/Maildir}, where all my Maildir ++folders are stored. As you can see, the folders are separated by ++colons. If you wonder why every folder begins with a dot: this is ++because I use Dovecot as @acronym{IMAP} server, which again uses ++@code{Maildir++} folders. For testing nnmairix, I also have some ++@code{nnml} mail, which is saved in @file{~/Mail/nnml}. Since this has ++to be specified relative to the @code{base} directory, the @code{../Mail} ++notation is needed. Note that the line ends in @code{*...}, which means ++to recursively scan all files under this directory. Without the three ++dots, the wildcard @code{*} will not work recursively. I also have some ++old mbox files with archived mail lying around in @file{~/mboxmail}. ++The other lines should be obvious. ++ ++See the man page for @code{mairixrc} for details and further options, ++especially regarding wildcard usage, which may be a little different ++than you are used to. ++ ++Now simply call @code{mairix} to create the index for the first time. ++Note that this may take a few minutes, but every following index will do ++the updates incrementally and hence is very fast. ++ ++@node Configuring nnmairix ++@subsubsection Configuring nnmairix ++ ++In group mode, type @kbd{G b c} ++(@code{nnmairix-create-server-and-default-group}). This will ask you for all ++necessary information and create a @code{nnmairix} server as a foreign ++server. You will have to specify the following: ++ ++@itemize @bullet ++ ++@item ++The @strong{name} of the @code{nnmairix} server---choose whatever you ++want. ++ ++@item ++The name of the @strong{back end server} where mairix should store its ++searches. This must be a full server name, like @code{nnml:mymail}. ++Just hit @kbd{TAB} to see the available servers. Currently, servers ++which are accessed through @code{nnmaildir}, @code{nnimap} and ++@code{nnml} are supported. As explained above, for locally stored ++mails, this can be an existing server where you store your mails. ++However, you can also create e.g. a new @code{nnmaildir} or @code{nnml} ++server exclusively for @code{nnmairix} in your secondary select methods ++(@pxref{Finding the News}). If you use a secondary @code{nnml} server ++just for mairix, make sure that you explicitly set the server variable ++@code{nnml-get-new-mail} to @code{nil}, or you might loose mail ++(@pxref{nnmairix caveats}). If you want to use mairix remotely on an ++@acronym{IMAP} server, you have to choose the corresponding ++@code{nnimap} server here. ++ ++@item ++@vindex nnmairix-mairix-search-options ++The @strong{command} to call the mairix binary. This will usually just ++be @code{mairix}, but you can also choose something like @code{ssh ++SERVER mairix} if you want to call mairix remotely, e.g. on your ++@acronym{IMAP} server. If you want to add some default options to ++mairix, you could do this here, but better use the variable ++@code{nnmairix-mairix-search-options} instead. ++ ++@item ++The name of the @strong{default search group}. This will be the group ++where all temporary mairix searches are stored, i.e. all searches which ++are not bound to permanent @code{nnmairix} groups. Choose whatever you ++like. ++ ++@item ++If the mail back end is @code{nnimap} or @code{nnmaildir}, you will be ++asked if you work with @strong{Maildir++}, i.e. with hidden maildir ++folders (=beginning with a dot). For example, you have to answer ++@samp{yes} here if you work with the Dovecot @acronym{IMAP} ++server. Otherwise, you should answer @samp{no} here. ++ ++@end itemize ++ ++@node nnmairix keyboard shortcuts ++@subsubsection nnmairix keyboard shortcuts ++ ++In group mode: ++ ++@table @kbd ++ ++@item G b c ++@kindex G b c (Group) ++@findex nnmairix-create-server-and-default-group ++Creates @code{nnmairix} server and default search group for this server ++(@code{nnmairix-create-server-and-default-group}). You should have done ++this by now (@pxref{Configuring nnmairix}). ++ ++@item G b s ++@kindex G b s (Group) ++@findex nnmairix-search ++Prompts for query which is then sent to the mairix binary. Search ++results are put into the default search group which is automatically ++displayed (@code{nnmairix-search}). ++ ++@item G b m ++@kindex G b m (Group) ++@findex nnmairix-widget-search ++Allows you to create a mairix search or a permanent group more ++comfortably using graphical widgets, similar to a customization ++group. Just try it to see how it works (@code{nnmairix-widget-search}). ++ ++@item G b i ++@kindex G b i (Group) ++@findex nnmairix-search-interactive ++Another command for creating a mairix query more comfortably, but uses ++only the minibuffer (@code{nnmairix-search-interactive}). ++ ++@item G b g ++@kindex G b g (Group) ++@findex nnmairix-create-search-group ++Creates a permanent group which is associated with a search query ++(@code{nnmairix-create-search-group}). The @code{nnmairix} back end ++automatically calls mairix when you update this group with @kbd{g} or ++@kbd{M-g}. ++ ++@item G b q ++@kindex G b q (Group) ++@findex nnmairix-group-change-query-this-group ++Changes the search query for the @code{nnmairix} group under cursor ++(@code{nnmairix-group-change-query-this-group}). ++ ++@item G b t ++@kindex G b t (Group) ++@findex nnmairix-group-toggle-threads-this-group ++Toggles the 'threads' parameter for the @code{nnmairix} group under cursor, ++i.e. if you want see the whole threads of the found messages ++(@code{nnmairix-group-toggle-threads-this-group}). ++ ++@item G b u ++@kindex G b u (Group) ++@findex nnmairix-update-database ++@vindex nnmairix-mairix-update-options ++Calls mairix binary for updating the database ++(@code{nnmairix-update-database}). The default parameters are @code{-F} ++and @code{-Q} for making this as fast as possible (see variable ++@code{nnmairix-mairix-update-options} for defining these default ++options). ++ ++@item G b r ++@kindex G b r (Group) ++@findex nnmairix-group-toggle-readmarks-this-group ++Keep articles in this @code{nnmairix} group always read or unread, or leave the ++marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}). ++ ++@item G b d ++@kindex G b d (Group) ++@findex nnmairix-group-delete-recreate-this-group ++Recreate @code{nnmairix} group on the ``real'' mail back end ++(@code{nnmairix-group-delete-recreate-this-group}). You can do this if ++you always get wrong article counts with a @code{nnmairix} group. ++ ++@item G b a ++@kindex G b a (Group) ++@findex nnmairix-group-toggle-allowfast-this-group ++Toggles the @code{allow-fast} parameters for group under cursor ++(@code{nnmairix-group-toggle-allowfast-this-group}). The default ++behavior of @code{nnmairix} is to do a mairix search every time you ++update or enter the group. With the @code{allow-fast} parameter set, ++mairix will only be called when you explicitly update the group, but not ++upon entering. This makes entering the group faster, but it may also ++lead to dangling symlinks if something changed between updating and ++entering the group which is not yet in the mairix database. ++ ++@item G b p ++@kindex G b p (Group) ++@findex nnmairix-group-toggle-propmarks-this-group ++Toggle marks propagation for this group ++(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating ++marks}). ++ ++@item G b o ++@kindex G b o (Group) ++@findex nnmairix-propagate-marks ++Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when ++@code{nnmairix-propagate-marks-upon-close} is set to @code{nil}. ++ ++@end table ++ ++In summary mode: ++ ++@table @kbd ++ ++@item $ m ++@kindex $ m (Summary) ++@findex nnmairix-widget-search-from-this-article ++Allows you to create a mairix query or group based on the current ++message using graphical widgets (same as @code{nnmairix-widget-search}) ++(@code{nnmairix-widget-search-from-this-article}). ++ ++@item $ g ++@kindex $ g (Summary) ++@findex nnmairix-create-search-group-from-message ++Interactively creates a new search group with query based on the current ++message, but uses the minibuffer instead of graphical widgets ++(@code{nnmairix-create-search-group-from-message}). ++ ++@item $ t ++@kindex $ t (Summary) ++@findex nnmairix-search-thread-this-article ++Searches thread for the current article ++(@code{nnmairix-search-thread-this-article}). This is effectively a ++shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the ++current article and enabled threads. ++ ++@item $ f ++@kindex $ f (Summary) ++@findex nnmairix-search-from-this-article ++Searches all messages from sender of the current article ++(@code{nnmairix-search-from-this-article}). This is a shortcut for ++calling @code{nnmairix-search} with @samp{f:From}. ++ ++@item $ o ++@kindex $ o (Summary) ++@findex nnmairix-goto-original-article ++(Only in @code{nnmairix} groups!) Tries determine the group this article ++originally came from and displays the article in this group, so that ++e.g. replying to this article the correct posting styles/group ++parameters are applied (@code{nnmairix-goto-original-article}). This ++function will use the registry if available, but can also parse the ++article file name as a fallback method. ++ ++@item $ u ++@kindex $ u (Summary) ++@findex nnmairix-remove-tick-mark-original-article ++Remove possibly existing tick mark from original article ++(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix ++tips and tricks}). ++ ++@end table ++ ++@node Propagating marks ++@subsubsection Propagating marks ++ ++First of: you really need a patched mairix binary for using the marks ++propagation feature efficiently. Otherwise, you would have to update ++the mairix database all the time. You can get the patch at ++ ++@uref{http://www.randomsample.de/mairix-maildir-patch.tar} ++ ++You need the mairix v0.21 source code for this patch; everything else ++is explained in the accompanied readme file. If you don't want to use ++marks propagation, you don't have to apply these patches, but they also ++fix some annoyances regarding changing maildir flags, so it might still ++be useful to you. ++ ++With the patched mairix binary, you can use @code{nnmairix} as an ++alternative to mail splitting (@pxref{Fancy Mail Splitting}). For ++example, instead of splitting all mails from @samp{david@@foobar.com} ++into a group, you can simply create a search group with the query ++@samp{f:david@@foobar.com}. This is actually what ``smart folders'' are ++all about: simply put everything in one mail folder and dynamically ++create searches instead of splitting. This is more flexible, since you ++can dynamically change your folders any time you want to. This also ++implies that you will usually read your mails in the @code{nnmairix} ++groups instead of your ``real'' mail groups. ++ ++There is one problem, though: say you got a new mail from ++@samp{david@@foobar.com}; it will now show up in two groups, the ++``real'' group (your INBOX, for example) and in the @code{nnmairix} ++search group (provided you have updated the mairix database). Now you ++enter the @code{nnmairix} group and read the mail. The mail will be ++marked as read, but only in the @code{nnmairix} group---in the ``real'' ++mail group it will be still shown as unread. ++ ++You could now catch up the mail group (@pxref{Group Data}), but this is ++tedious and error prone, since you may overlook mails you don't have ++created @code{nnmairix} groups for. Of course, you could first use ++@code{nnmairix-goto-original-article} (@pxref{nnmairix keyboard ++shortcuts}) and then read the mail in the original group, but that's ++even more cumbersome. ++ ++Clearly, the easiest way would be if marks could somehow be ++automatically set for the original article. This is exactly what ++@emph{marks propagation} is about. ++ ++Marks propagation is deactivated by default. You can activate it for a ++certain @code{nnmairix} group with ++@code{nnmairix-group-toggle-propmarks-this-group} (bound to @kbd{G b ++p}). This function will warn you if you try to use it with your default ++search group; the reason is that the default search group is used for ++temporary searches, and it's easy to accidentally propagate marks from ++this group. However, you can ignore this warning if you really want to. ++ ++With marks propagation enabled, all the marks you set in a @code{nnmairix} ++group should now be propagated to the original article. For example, ++you can now tick an article (by default with @kbd{!}) and this mark should ++magically be set for the original article, too. ++ ++A few more remarks which you may or may not want to know: ++ ++@vindex nnmairix-propagate-marks-upon-close ++Marks will not be set immediately, but only upon closing a group. This ++not only makes marks propagation faster, it also avoids problems with ++dangling symlinks when dealing with maildir files (since changing flags ++will change the file name). You can also control when to propagate marks ++via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for ++details). ++ ++Obviously, @code{nnmairix} will have to look up the original group for every ++article you want to set marks for. If available, @code{nnmairix} will first use ++the registry for determining the original group. The registry is very ++fast, hence you should really, really enable the registry when using ++marks propagation. If you don't have to worry about RAM and disc space, ++set @code{gnus-registry-max-entries} to a large enough value; to be on ++the safe side, choose roughly the amount of mails you index with mairix. ++ ++@vindex nnmairix-only-use-registry ++If you don't want to use the registry or the registry hasn't seen the ++original article yet, @code{nnmairix} will use an additional mairix ++search for determining the file name of the article. This, of course, is ++way slower than the registry---if you set hundreds or even thousands of ++marks this way, it might take some time. You can avoid this situation by ++setting @code{nnmairix-only-use-registry} to t. ++ ++Maybe you also want to propagate marks the other way round, i.e. if you ++tick an article in a "real" mail group, you'd like to have the same ++article in a @code{nnmairix} group ticked, too. For several good ++reasons, this can only be done efficiently if you use maildir. To ++immediately contradict myself, let me mention that it WON'T work with ++@code{nnmaildir}, since @code{nnmaildir} stores the marks externally and ++not in the file name. Therefore, propagating marks to @code{nnmairix} ++groups will usually only work if you use an IMAP server which uses ++maildir as its file format. ++ ++@vindex nnmairix-propagate-marks-to-nnmairix-groups ++If you work with this setup, just set ++@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t} and see what ++happens. If you don't like what you see, just set it to @code{nil} again. One ++problem might be that you get a wrong number of unread articles; this ++usually happens when you delete or expire articles in the original ++groups. When this happens, you can recreate the @code{nnmairix} group on the ++back end using @kbd{G b d}. ++ ++@node nnmairix tips and tricks ++@subsubsection nnmairix tips and tricks ++ ++@itemize ++@item ++Checking Mail ++ ++@findex nnmairix-update-groups ++I put all my important mail groups at group level 1. The mairix groups ++have group level 5, so they do not get checked at start up (@pxref{Group ++Levels}). ++ ++I use the following to check for mails: ++ ++@lisp ++(defun my-check-mail-mairix-update (level) ++ (interactive "P") ++ ;; if no prefix given, set level=1 ++ (gnus-group-get-new-news (or level 1)) ++ (nnmairix-update-groups "mairixsearch" t t) ++ (gnus-group-list-groups)) ++ ++(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update) ++@end lisp ++ ++Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix} ++server. See the doc string for @code{nnmairix-update-groups} for ++details. ++ ++@item ++Example: search group for ticked articles ++ ++For example, you can create a group for all ticked articles, where the ++articles always stay unread: ++ ++Hit @kbd{G b g}, enter group name (e.g. @samp{important}), use ++@samp{F:f} as query and do not include threads. ++ ++Now activate marks propagation for this group by using @kbd{G b p}. Then ++activate the always-unread feature by using @kbd{G b r} twice. ++ ++So far so good---but how do you remove the tick marks in the @code{nnmairix} ++group? There are two options: You may simply use ++@code{nnmairix-remove-tick-mark-original-article} (bound to @kbd{$ u}) to remove ++tick marks from the original article. The other possibility is to set ++@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t}, but see the above ++comments about this option. If it works for you, the tick marks should ++also exist in the @code{nnmairix} group and you can remove them as usual, ++e.g. by marking an article as read. ++ ++When you have removed a tick mark from the original article, this ++article should vanish from the @code{nnmairix} group after you have updated the ++mairix database and updated the group. Fortunately, there is a function ++for doing exactly that: @code{nnmairix-update-groups}. See the previous code ++snippet and the doc string for details. ++ ++@item ++Dealing with auto-subscription of mail groups ++ ++As described before, all @code{nnmairix} groups are in fact stored on ++the mail back end in the form @samp{zz_mairix--}. You can ++see them when you enter the back end server in the server buffer. You ++should not subscribe these groups! Unfortunately, these groups will ++usually get @emph{auto-subscribed} when you use @code{nnmaildir} or ++@code{nnml}, i.e. you will suddenly see groups of the form ++@samp{zz_mairix*} pop up in your group buffer. If this happens to you, ++simply kill these groups with C-k. For avoiding this, turn off ++auto-subscription completely by setting the variable ++@code{gnus-auto-subscribed-groups} to @code{nil} (@pxref{Filtering New ++Groups}), or if you like to keep this feature use the following kludge ++for turning it off for all groups beginning with @samp{zz_}: ++ ++@lisp ++(setq gnus-auto-subscribed-groups ++ "^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*") ++@end lisp ++ ++@end itemize ++ ++@node nnmairix caveats ++@subsubsection nnmairix caveats ++ ++@itemize ++@item ++You can create a secondary @code{nnml} server just for nnmairix, but then ++you have to explicitly set the corresponding server variable ++@code{nnml-get-new-mail} to @code{nil}. Otherwise, new mail might get ++put into this secondary server (and would never show up again). Here's ++an example server definition: ++ ++@lisp ++(nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil)) ++@end lisp ++ ++(The @code{nnmaildir} back end also has a server variabe ++@code{get-new-mail}, but its default value is @code{nil}, so you don't ++have to explicitly set it if you use a @code{nnmaildir} server just for ++mairix.) ++ ++@item ++If you use the Gnus registry: don't use the registry with ++@code{nnmairix} groups (put them in ++@code{gnus-registry-unfollowed-groups}). Be @emph{extra careful} if ++you use @code{gnus-registry-split-fancy-with-parent}; mails which are ++split into @code{nnmairix} groups are usually gone for good as soon as ++you check the group for new mail (yes, it has happened to me...). ++ ++@item ++Therefore: @emph{Never ever} put ``real'' mails into @code{nnmairix} ++groups (you shouldn't be able to, anyway). ++ ++@item ++If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize ++@code{nnmairix} groups (though I have no idea what happens if you do). ++ ++@item ++mairix does only support us-ascii characters. ++ ++@item ++@code{nnmairix} uses a rather brute force method to force Gnus to ++completely reread the group on the mail back end after mairix was ++called---it simply deletes and re-creates the group on the mail ++back end. So far, this has worked for me without any problems, and I ++don't see how @code{nnmairix} could delete other mail groups than its ++own, but anyway: you really should have a backup of your mail ++folders. ++ ++@item ++All necessary information is stored in the group parameters ++(@pxref{Group Parameters}). This has the advantage that no active file ++is needed, but also implies that when you kill a @code{nnmairix} group, ++it is gone for good. ++ ++@item ++@findex nnmairix-purge-old-groups ++If you create and kill a lot of @code{nnmairix} groups, the ++``zz_mairix-*'' groups will accumulate on the mail back end server. To ++delete old groups which are no longer needed, call ++@code{nnmairix-purge-old-groups}. Note that this assumes that you don't ++save any ``real'' mail in folders of the form ++@code{zz_mairix--}. You can change the prefix of ++@code{nnmairix} groups by changing the variable ++@code{nnmairix-group-prefix}. ++ ++@item ++The following only applies if you @emph{don't} use the mentioned patch ++for mairix (@pxref{Propagating marks}): ++ ++A problem can occur when using @code{nnmairix} with maildir folders and ++comes with the fact that maildir stores mail flags like @samp{Seen} or ++@samp{Replied} by appending chars @samp{S} and @samp{R} to the message ++file name, respectively. This implies that currently you would have to ++update the mairix database not only when new mail arrives, but also when ++mail flags are changing. The same applies to new mails which are indexed ++while they are still in the @samp{new} folder but then get moved to ++@samp{cur} when Gnus has seen the mail. If you don't update the database ++after this has happened, a mairix query can lead to symlinks pointing to ++non-existing files. In Gnus, these messages will usually appear with ++``(none)'' entries in the header and can't be accessed. If this happens ++to you, using @kbd{G b u} and updating the group will usually fix this. ++ ++@end itemize ++ ++@node Misc Group Stuff ++@section Misc Group Stuff ++ ++@menu ++* Scanning New Messages:: Asking Gnus to see whether new messages have arrived. ++* Group Information:: Information and help on groups and Gnus. ++* Group Timestamp:: Making Gnus keep track of when you last read a group. ++* File Commands:: Reading and writing the Gnus files. ++* Sieve Commands:: Managing Sieve scripts. ++@end menu ++ ++@table @kbd ++ ++@item v ++@kindex v (Group) ++@cindex keys, reserved for users (Group) ++The key @kbd{v} is reserved for users. You can bind it to some ++command or better use it as a prefix key. For example: ++ ++@lisp ++(define-key gnus-group-mode-map (kbd "v j d") ++ (lambda () ++ (interactive) ++ (gnus-group-jump-to-group "nndraft:drafts"))) ++@end lisp ++ ++On keys reserved for users in Emacs and on keybindings in general ++@xref{Keymaps, Keymaps, , emacs, The Emacs Editor}. ++ ++@item ^ ++@kindex ^ (Group) ++@findex gnus-group-enter-server-mode ++Enter the server buffer (@code{gnus-group-enter-server-mode}). ++@xref{Server Buffer}. ++ ++@item a ++@kindex a (Group) ++@findex gnus-group-post-news ++Start composing a message (a news by default) ++(@code{gnus-group-post-news}). If given a prefix, post to the group ++under the point. If the prefix is 1, prompt for a group to post to. ++Contrary to what the name of this function suggests, the prepared ++article might be a mail instead of a news, if a mail group is specified ++with the prefix argument. @xref{Composing Messages}. ++ ++@item m ++@kindex m (Group) ++@findex gnus-group-mail ++Mail a message somewhere (@code{gnus-group-mail}). If given a prefix, ++use the posting style of the group under the point. If the prefix is 1, ++prompt for a group name to find the posting style. ++@xref{Composing Messages}. ++ ++@item i ++@kindex i (Group) ++@findex gnus-group-news ++Start composing a news (@code{gnus-group-news}). If given a prefix, ++post to the group under the point. If the prefix is 1, prompt ++for group to post to. @xref{Composing Messages}. ++ ++This function actually prepares a news even when using mail groups. ++This is useful for ``posting'' messages to mail groups without actually ++sending them over the network: they're just saved directly to the group ++in question. The corresponding back end must have a request-post method ++for this to work though. ++ ++@item G z ++@kindex G z (Group) ++@findex gnus-group-compact-group ++ ++Compact the group under point (@code{gnus-group-compact-group}). ++Currently implemented only in nnml (@pxref{Mail Spool}). This removes ++gaps between article numbers, hence getting a correct total article ++count. ++ ++@end table ++ ++Variables for the group buffer: ++ ++@table @code ++ ++@item gnus-group-mode-hook ++@vindex gnus-group-mode-hook ++is called after the group buffer has been ++created. ++ ++@item gnus-group-prepare-hook ++@vindex gnus-group-prepare-hook ++is called after the group buffer is ++generated. It may be used to modify the buffer in some strange, ++unnatural way. ++ ++@item gnus-group-prepared-hook ++@vindex gnus-group-prepare-hook ++is called as the very last thing after the group buffer has been ++generated. It may be used to move point around, for instance. ++ ++@item gnus-permanently-visible-groups ++@vindex gnus-permanently-visible-groups ++Groups matching this regexp will always be listed in the group buffer, ++whether they are empty or not. ++ ++@end table ++ ++@node Scanning New Messages ++@subsection Scanning New Messages ++@cindex new messages ++@cindex scanning new news ++ ++@table @kbd ++ ++@item g ++@kindex g (Group) ++@findex gnus-group-get-new-news ++@c @icon{gnus-group-get-new-news} ++Check the server(s) for new articles. If the numerical prefix is used, ++this command will check only groups of level @var{arg} and lower ++(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this ++command will force a total re-reading of the active file(s) from the ++back end(s). ++ ++@item M-g ++@kindex M-g (Group) ++@findex gnus-group-get-new-news-this-group ++@vindex gnus-goto-next-group-when-activating ++@c @icon{gnus-group-get-new-news-this-group} ++Check whether new articles have arrived in the current group ++(@code{gnus-group-get-new-news-this-group}). ++@code{gnus-goto-next-group-when-activating} says whether this command is ++to move point to the next group or not. It is @code{t} by default. ++ ++@findex gnus-activate-all-groups ++@cindex activating groups ++@item C-c M-g ++@kindex C-c M-g (Group) ++Activate absolutely all groups (@code{gnus-activate-all-groups}). ++ ++@item R ++@kindex R (Group) ++@cindex restarting ++@findex gnus-group-restart ++Restart Gnus (@code{gnus-group-restart}). This saves the @file{.newsrc} ++file(s), closes the connection to all servers, clears up all run-time ++Gnus variables, and then starts Gnus all over again. ++ ++@end table ++ ++@vindex gnus-get-new-news-hook ++@code{gnus-get-new-news-hook} is run just before checking for new news. ++ ++@vindex gnus-after-getting-new-news-hook ++@code{gnus-after-getting-new-news-hook} is run after checking for new ++news. ++ ++ ++@node Group Information ++@subsection Group Information ++@cindex group information ++@cindex information on groups ++ ++@table @kbd ++ ++ ++@item H f ++@kindex H f (Group) ++@findex gnus-group-fetch-faq ++@vindex gnus-group-faq-directory ++@cindex FAQ ++@cindex ange-ftp ++Try to fetch the @acronym{FAQ} for the current group ++(@code{gnus-group-fetch-faq}). Gnus will try to get the @acronym{FAQ} ++from @code{gnus-group-faq-directory}, which is usually a directory on ++a remote machine. This variable can also be a list of directories. ++In that case, giving a prefix to this command will allow you to choose ++between the various sites. @code{ange-ftp} (or @code{efs}) will be ++used for fetching the file. ++ ++If fetching from the first site is unsuccessful, Gnus will attempt to go ++through @code{gnus-group-faq-directory} and try to open them one by one. ++ ++@item H c ++@kindex H c (Group) ++@findex gnus-group-fetch-charter ++@vindex gnus-group-charter-alist ++@cindex charter ++Try to open the charter for the current group in a web browser ++(@code{gnus-group-fetch-charter}). Query for a group if given a ++prefix argument. ++ ++Gnus will use @code{gnus-group-charter-alist} to find the location of ++the charter. If no location is known, Gnus will fetch the control ++messages for the group, which in some cases includes the charter. ++ ++@item H C ++@kindex H C (Group) ++@findex gnus-group-fetch-control ++@vindex gnus-group-fetch-control-use-browse-url ++@cindex control message ++Fetch the control messages for the group from the archive at ++@code{ftp.isc.org} (@code{gnus-group-fetch-control}). Query for a ++group if given a prefix argument. ++ ++If @code{gnus-group-fetch-control-use-browse-url} is non-@code{nil}, ++Gnus will open the control messages in a browser using ++@code{browse-url}. Otherwise they are fetched using @code{ange-ftp} ++and displayed in an ephemeral group. ++ ++Note that the control messages are compressed. To use this command ++you need to turn on @code{auto-compression-mode} (@pxref{Compressed ++Files, ,Compressed Files, emacs, The Emacs Manual}). ++ ++@item H d ++@itemx C-c C-d ++@c @icon{gnus-group-describe-group} ++@kindex H d (Group) ++@kindex C-c C-d (Group) ++@cindex describing groups ++@cindex group description ++@findex gnus-group-describe-group ++Describe the current group (@code{gnus-group-describe-group}). If given ++a prefix, force Gnus to re-read the description from the server. ++ ++@item M-d ++@kindex M-d (Group) ++@findex gnus-group-describe-all-groups ++Describe all groups (@code{gnus-group-describe-all-groups}). If given a ++prefix, force Gnus to re-read the description file from the server. ++ ++@item H v ++@itemx V ++@kindex V (Group) ++@kindex H v (Group) ++@cindex version ++@findex gnus-version ++Display current Gnus version numbers (@code{gnus-version}). ++ ++@item ? ++@kindex ? (Group) ++@findex gnus-group-describe-briefly ++Give a very short help message (@code{gnus-group-describe-briefly}). ++ ++@item C-c C-i ++@kindex C-c C-i (Group) ++@cindex info ++@cindex manual ++@findex gnus-info-find-node ++Go to the Gnus info node (@code{gnus-info-find-node}). ++@end table ++ ++ ++@node Group Timestamp ++@subsection Group Timestamp ++@cindex timestamps ++@cindex group timestamps ++ ++It can be convenient to let Gnus keep track of when you last read a ++group. To set the ball rolling, you should add ++@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}: ++ ++@lisp ++(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp) ++@end lisp ++ ++After doing this, each time you enter a group, it'll be recorded. ++ ++This information can be displayed in various ways---the easiest is to ++use the @samp{%d} spec in the group line format: ++ ++@lisp ++(setq gnus-group-line-format ++ "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n") ++@end lisp ++ ++This will result in lines looking like: ++ ++@example ++* 0: mail.ding 19961002T012943 ++ 0: custom 19961002T012713 ++@end example ++ ++As you can see, the date is displayed in compact ISO 8601 format. This ++may be a bit too much, so to just display the date, you could say ++something like: ++ ++@lisp ++(setq gnus-group-line-format ++ "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n") ++@end lisp ++ ++If you would like greater control of the time format, you can use a ++user-defined format spec. Something like the following should do the ++trick: ++ ++@lisp ++(setq gnus-group-line-format ++ "%M\%S\%p\%P\%5y: %(%-40,40g%) %ud\n") ++(defun gnus-user-format-function-d (headers) ++ (let ((time (gnus-group-timestamp gnus-tmp-group))) ++ (if time ++ (format-time-string "%b %d %H:%M" time) ++ ""))) ++@end lisp ++ ++ ++@node File Commands ++@subsection File Commands ++@cindex file commands ++ ++@table @kbd ++ ++@item r ++@kindex r (Group) ++@findex gnus-group-read-init-file ++@vindex gnus-init-file ++@cindex reading init file ++Re-read the init file (@code{gnus-init-file}, which defaults to ++@file{~/.gnus.el}) (@code{gnus-group-read-init-file}). ++ ++@item s ++@kindex s (Group) ++@findex gnus-group-save-newsrc ++@cindex saving .newsrc ++Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted) ++(@code{gnus-group-save-newsrc}). If given a prefix, force saving the ++file(s) whether Gnus thinks it is necessary or not. ++ ++@c @item Z ++@c @kindex Z (Group) ++@c @findex gnus-group-clear-dribble ++@c Clear the dribble buffer (@code{gnus-group-clear-dribble}). ++ ++@end table ++ ++ ++@node Sieve Commands ++@subsection Sieve Commands ++@cindex group sieve commands ++ ++Sieve is a server-side mail filtering language. In Gnus you can use ++the @code{sieve} group parameter (@pxref{Group Parameters}) to specify ++sieve rules that should apply to each group. Gnus provides two ++commands to translate all these group parameters into a proper Sieve ++script that can be transfered to the server somehow. ++ ++@vindex gnus-sieve-file ++@vindex gnus-sieve-region-start ++@vindex gnus-sieve-region-end ++The generated Sieve script is placed in @code{gnus-sieve-file} (by ++default @file{~/.sieve}). The Sieve code that Gnus generate is placed ++between two delimiters, @code{gnus-sieve-region-start} and ++@code{gnus-sieve-region-end}, so you may write additional Sieve code ++outside these delimiters that will not be removed the next time you ++regenerate the Sieve script. ++ ++@vindex gnus-sieve-crosspost ++The variable @code{gnus-sieve-crosspost} controls how the Sieve script ++is generated. If it is non-@code{nil} (the default) articles is ++placed in all groups that have matching rules, otherwise the article ++is only placed in the group with the first matching rule. For ++example, the group parameter @samp{(sieve address "sender" ++"owner-ding@@hpc.uh.edu")} will generate the following piece of Sieve ++code if @code{gnus-sieve-crosspost} is @code{nil}. (When ++@code{gnus-sieve-crosspost} is non-@code{nil}, it looks the same ++except that the line containing the call to @code{stop} is removed.) ++ ++@example ++if address "sender" "owner-ding@@hpc.uh.edu" @{ ++ fileinto "INBOX.ding"; ++ stop; ++@} ++@end example ++ ++@xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}. ++ ++@table @kbd ++ ++@item D g ++@kindex D g (Group) ++@findex gnus-sieve-generate ++@vindex gnus-sieve-file ++@cindex generating sieve script ++Regenerate a Sieve script from the @code{sieve} group parameters and ++put you into the @code{gnus-sieve-file} without saving it. ++ ++@item D u ++@kindex D u (Group) ++@findex gnus-sieve-update ++@vindex gnus-sieve-file ++@cindex updating sieve script ++Regenerates the Gnus managed part of @code{gnus-sieve-file} using the ++@code{sieve} group parameters, save the file and upload it to the ++server using the @code{sieveshell} program. ++ ++@end table ++ ++ ++@node Summary Buffer ++@chapter Summary Buffer ++@cindex summary buffer ++ ++A line for each article is displayed in the summary buffer. You can ++move around, read articles, post articles and reply to articles. ++ ++The most common way to a summary buffer is to select a group from the ++group buffer (@pxref{Selecting a Group}). ++ ++You can have as many summary buffers open as you wish. ++ ++You can customize the Summary Mode tool bar, see @kbd{M-x ++customize-apropos RET gnus-summary-tool-bar}. This feature is only ++available in Emacs. ++ ++@kindex v (Summary) ++@cindex keys, reserved for users (Summary) ++The key @kbd{v} is reserved for users. You can bind it to some ++command or better use it as a prefix key. For example: ++@lisp ++(define-key gnus-summary-mode-map (kbd "v -") "LrS") ;; lower subthread ++@end lisp ++ ++@menu ++* Summary Buffer Format:: Deciding how the summary buffer is to look. ++* Summary Maneuvering:: Moving around the summary buffer. ++* Choosing Articles:: Reading articles. ++* Paging the Article:: Scrolling the current article. ++* Reply Followup and Post:: Posting articles. ++* Delayed Articles:: Send articles at a later time. ++* Marking Articles:: Marking articles as read, expirable, etc. ++* Limiting:: You can limit the summary buffer. ++* Threading:: How threads are made. ++* Sorting the Summary Buffer:: How articles and threads are sorted. ++* Asynchronous Fetching:: Gnus might be able to pre-fetch articles. ++* Article Caching:: You may store articles in a cache. ++* Persistent Articles:: Making articles expiry-resistant. ++* Sticky Articles:: Article buffers that are not reused. ++* Article Backlog:: Having already read articles hang around. ++* Saving Articles:: Ways of customizing article saving. ++* Decoding Articles:: Gnus can treat series of (uu)encoded articles. ++* Article Treatment:: The article buffer can be mangled at will. ++* MIME Commands:: Doing MIMEy things with the articles. ++* Charsets:: Character set issues. ++* Article Commands:: Doing various things with the article buffer. ++* Summary Sorting:: Sorting the summary buffer in various ways. ++* Finding the Parent:: No child support? Get the parent. ++* Alternative Approaches:: Reading using non-default summaries. ++* Tree Display:: A more visual display of threads. ++* Mail Group Commands:: Some commands can only be used in mail groups. ++* Various Summary Stuff:: What didn't fit anywhere else. ++* Exiting the Summary Buffer:: Returning to the Group buffer, ++ or reselecting the current group. ++* Crosspost Handling:: How crossposted articles are dealt with. ++* Duplicate Suppression:: An alternative when crosspost handling fails. ++* Security:: Decrypt and Verify. ++* Mailing List:: Mailing list minor mode. ++@end menu ++ ++ ++@node Summary Buffer Format ++@section Summary Buffer Format ++@cindex summary buffer format ++ ++@iftex ++@iflatex ++\gnusfigure{The Summary Buffer}{180}{ ++\put(0,0){\epsfig{figure=ps/summary,width=7.5cm}} ++\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-article,width=7.5cm}}} ++} ++@end iflatex ++@end iftex ++ ++@menu ++* Summary Buffer Lines:: You can specify how summary lines should look. ++* To From Newsgroups:: How to not display your own name. ++* Summary Buffer Mode Line:: You can say how the mode line should look. ++* Summary Highlighting:: Making the summary buffer all pretty and nice. ++@end menu ++ ++@findex mail-extract-address-components ++@findex gnus-extract-address-components ++@vindex gnus-extract-address-components ++Gnus will use the value of the @code{gnus-extract-address-components} ++variable as a function for getting the name and address parts of a ++@code{From} header. Two pre-defined functions exist: ++@code{gnus-extract-address-components}, which is the default, quite ++fast, and too simplistic solution; and ++@code{mail-extract-address-components}, which works very nicely, but is ++slower. The default function will return the wrong answer in 5% of the ++cases. If this is unacceptable to you, use the other function instead: ++ ++@lisp ++(setq gnus-extract-address-components ++ 'mail-extract-address-components) ++@end lisp ++ ++@vindex gnus-summary-same-subject ++@code{gnus-summary-same-subject} is a string indicating that the current ++article has the same subject as the previous. This string will be used ++with those specs that require it. The default is @code{""}. ++ ++ ++@node Summary Buffer Lines ++@subsection Summary Buffer Lines ++ ++@vindex gnus-summary-line-format ++You can change the format of the lines in the summary buffer by changing ++the @code{gnus-summary-line-format} variable. It works along the same ++lines as a normal @code{format} string, with some extensions ++(@pxref{Formatting Variables}). ++ ++There should always be a colon or a point position marker on the line; ++the cursor always moves to the point position marker or the colon after ++performing an operation. (Of course, Gnus wouldn't be Gnus if it wasn't ++possible to change this. Just write a new function ++@code{gnus-goto-colon} which does whatever you like with the cursor.) ++@xref{Positioning Point}. ++ ++The default string is @samp{%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n}. ++ ++The following format specification characters and extended format ++specification(s) are understood: ++ ++@table @samp ++@item N ++Article number. ++@item S ++Subject string. List identifiers stripped, ++@code{gnus-list-identifiers}. @xref{Article Hiding}. ++@item s ++Subject if the article is the root of the thread or the previous article ++had a different subject, @code{gnus-summary-same-subject} otherwise. ++(@code{gnus-summary-same-subject} defaults to @code{""}.) ++@item F ++Full @code{From} header. ++@item n ++The name (from the @code{From} header). ++@item f ++The name, @code{To} header or the @code{Newsgroups} header (@pxref{To ++From Newsgroups}). ++@item a ++The name (from the @code{From} header). This differs from the @code{n} ++spec in that it uses the function designated by the ++@code{gnus-extract-address-components} variable, which is slower, but ++may be more thorough. ++@item A ++The address (from the @code{From} header). This works the same way as ++the @code{a} spec. ++@item L ++Number of lines in the article. ++@item c ++Number of characters in the article. This specifier is not supported ++in some methods (like nnfolder). ++@item k ++Pretty-printed version of the number of characters in the article; ++for example, @samp{1.2k} or @samp{0.4M}. ++@item I ++Indentation based on thread level (@pxref{Customizing Threading}). ++@item B ++A complex trn-style thread tree, showing response-connecting trace ++lines. A thread could be drawn like this: ++ ++@example ++> +++-> ++| +-> ++| | \-> ++| | \-> ++| \-> +++-> ++\-> ++@end example ++ ++You can customize the appearance with the following options. Note ++that it is possible to make the thread display look really neat by ++replacing the default @acronym{ASCII} characters with graphic ++line-drawing glyphs. ++@table @code ++@item gnus-sum-thread-tree-root ++@vindex gnus-sum-thread-tree-root ++Used for the root of a thread. If @code{nil}, use subject ++instead. The default is @samp{> }. ++ ++@item gnus-sum-thread-tree-false-root ++@vindex gnus-sum-thread-tree-false-root ++Used for the false root of a thread (@pxref{Loose Threads}). If ++@code{nil}, use subject instead. The default is @samp{> }. ++ ++@item gnus-sum-thread-tree-single-indent ++@vindex gnus-sum-thread-tree-single-indent ++Used for a thread with just one message. If @code{nil}, use subject ++instead. The default is @samp{}. ++ ++@item gnus-sum-thread-tree-vertical ++@vindex gnus-sum-thread-tree-vertical ++Used for drawing a vertical line. The default is @samp{| }. ++ ++@item gnus-sum-thread-tree-indent ++@vindex gnus-sum-thread-tree-indent ++Used for indenting. The default is @samp{ }. ++ ++@item gnus-sum-thread-tree-leaf-with-other ++@vindex gnus-sum-thread-tree-leaf-with-other ++Used for a leaf with brothers. The default is @samp{+-> }. ++ ++@item gnus-sum-thread-tree-single-leaf ++@vindex gnus-sum-thread-tree-single-leaf ++Used for a leaf without brothers. The default is @samp{\-> } ++ ++@end table ++ ++@item T ++Nothing if the article is a root and lots of spaces if it isn't (it ++pushes everything after it off the screen). ++@item [ ++Opening bracket, which is normally @samp{[}, but can also be @samp{<} ++for adopted articles (@pxref{Customizing Threading}). ++@item ] ++Closing bracket, which is normally @samp{]}, but can also be @samp{>} ++for adopted articles. ++@item > ++One space for each thread level. ++@item < ++Twenty minus thread level spaces. ++@item U ++Unread. @xref{Read Articles}. ++ ++@item R ++This misleadingly named specifier is the @dfn{secondary mark}. This ++mark will say whether the article has been replied to, has been cached, ++or has been saved. @xref{Other Marks}. ++ ++@item i ++Score as a number (@pxref{Scoring}). ++@item z ++@vindex gnus-summary-zcore-fuzz ++Zcore, @samp{+} if above the default level and @samp{-} if below the ++default level. If the difference between ++@code{gnus-summary-default-score} and the score is less than ++@code{gnus-summary-zcore-fuzz}, this spec will not be used. ++@item V ++Total thread score. ++@item x ++@code{Xref}. ++@item D ++@code{Date}. ++@item d ++The @code{Date} in @code{DD-MMM} format. ++@item o ++The @code{Date} in @var{YYYYMMDD}@code{T}@var{HHMMSS} format. ++@item M ++@code{Message-ID}. ++@item r ++@code{References}. ++@item t ++Number of articles in the current sub-thread. Using this spec will slow ++down summary buffer generation somewhat. ++@item e ++An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the ++article has any children. ++@item P ++The line number. ++@item O ++Download mark. ++@item * ++Desired cursor position (instead of after first colon). ++@item &user-date; ++Age sensitive date format. Various date format is defined in ++@code{gnus-user-date-format-alist}. ++@item u ++User defined specifier. The next character in the format string should ++be a letter. Gnus will call the function ++@code{gnus-user-format-function-@var{x}}, where @var{x} is the letter ++following @samp{%u}. The function will be passed the current header as ++argument. The function should return a string, which will be inserted ++into the summary just like information from any other summary specifier. ++@end table ++ ++Text between @samp{%(} and @samp{%)} will be highlighted with ++@code{gnus-mouse-face} when the mouse point is placed inside the area. ++There can only be one such area. ++ ++The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs ++have to be handled with care. For reasons of efficiency, Gnus will ++compute what column these characters will end up in, and ``hard-code'' ++that. This means that it is invalid to have these specs after a ++variable-length spec. Well, you might not be arrested, but your summary ++buffer will look strange, which is bad enough. ++ ++The smart choice is to have these specs as far to the left as possible. ++(Isn't that the case with everything, though? But I digress.) ++ ++This restriction may disappear in later versions of Gnus. ++ ++ ++@node To From Newsgroups ++@subsection To From Newsgroups ++@cindex To ++@cindex Newsgroups ++ ++In some groups (particularly in archive groups), the @code{From} header ++isn't very interesting, since all the articles there are written by ++you. To display the information in the @code{To} or @code{Newsgroups} ++headers instead, you need to decide three things: What information to ++gather; where to display it; and when to display it. ++ ++@enumerate ++@item ++@vindex gnus-extra-headers ++The reading of extra header information is controlled by the ++@code{gnus-extra-headers}. This is a list of header symbols. For ++instance: ++ ++@lisp ++(setq gnus-extra-headers ++ '(To Newsgroups X-Newsreader)) ++@end lisp ++ ++This will result in Gnus trying to obtain these three headers, and ++storing it in header structures for later easy retrieval. ++ ++@item ++@findex gnus-extra-header ++The value of these extra headers can be accessed via the ++@code{gnus-extra-header} function. Here's a format line spec that will ++access the @code{X-Newsreader} header: ++ ++@example ++"%~(form (gnus-extra-header 'X-Newsreader))@@" ++@end example ++ ++@item ++@vindex gnus-ignored-from-addresses ++The @code{gnus-ignored-from-addresses} variable says when the @samp{%f} ++summary line spec returns the @code{To}, @code{Newsreader} or ++@code{From} header. If this regexp matches the contents of the ++@code{From} header, the value of the @code{To} or @code{Newsreader} ++headers are used instead. ++ ++To distinguish regular articles from those where the @code{From} field ++has been swapped, a string is prefixed to the @code{To} or ++@code{Newsgroups} header in the summary line. By default the string is ++@samp{-> } for @code{To} and @samp{=> } for @code{Newsgroups}, you can ++customize these strings with @code{gnus-summary-to-prefix} and ++@code{gnus-summary-newsgroup-prefix}. ++ ++@end enumerate ++ ++@vindex nnmail-extra-headers ++A related variable is @code{nnmail-extra-headers}, which controls when ++to include extra headers when generating overview (@acronym{NOV}) files. ++If you have old overview files, you should regenerate them after ++changing this variable, by entering the server buffer using @kbd{^}, ++and then @kbd{g} on the appropriate mail server (e.g. nnml) to cause ++regeneration. ++ ++@vindex gnus-summary-line-format ++You also have to instruct Gnus to display the data by changing the ++@code{%n} spec to the @code{%f} spec in the ++@code{gnus-summary-line-format} variable. ++ ++In summary, you'd typically put something like the following in ++@file{~/.gnus.el}: ++ ++@lisp ++(setq gnus-extra-headers ++ '(To Newsgroups)) ++(setq nnmail-extra-headers gnus-extra-headers) ++(setq gnus-summary-line-format ++ "%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n") ++(setq gnus-ignored-from-addresses ++ "Your Name Here") ++@end lisp ++ ++(The values listed above are the default values in Gnus. Alter them ++to fit your needs.) ++ ++A note for news server administrators, or for users who wish to try to ++convince their news server administrator to provide some additional ++support: ++ ++The above is mostly useful for mail groups, where you have control over ++the @acronym{NOV} files that are created. However, if you can persuade your ++nntp admin to add (in the usual implementation, notably INN): ++ ++@example ++Newsgroups:full ++@end example ++ ++to the end of her @file{overview.fmt} file, then you can use that just ++as you would the extra headers from the mail groups. ++ ++ ++@node Summary Buffer Mode Line ++@subsection Summary Buffer Mode Line ++ ++@vindex gnus-summary-mode-line-format ++You can also change the format of the summary mode bar (@pxref{Mode Line ++Formatting}). Set @code{gnus-summary-mode-line-format} to whatever you ++like. The default is @samp{Gnus: %%b [%A] %Z}. ++ ++Here are the elements you can play with: ++ ++@table @samp ++@item G ++Group name. ++@item p ++Unprefixed group name. ++@item A ++Current article number. ++@item z ++Current article score. ++@item V ++Gnus version. ++@item U ++Number of unread articles in this group. ++@item e ++Number of unread articles in this group that aren't displayed in the ++summary buffer. ++@item Z ++A string with the number of unread and unselected articles represented ++either as @samp{<%U(+%e) more>} if there are both unread and unselected ++articles, and just as @samp{<%U more>} if there are just unread articles ++and no unselected ones. ++@item g ++Shortish group name. For instance, @samp{rec.arts.anime} will be ++shortened to @samp{r.a.anime}. ++@item S ++Subject of the current article. ++@item u ++User-defined spec (@pxref{User-Defined Specs}). ++@item s ++Name of the current score file (@pxref{Scoring}). ++@item d ++Number of dormant articles (@pxref{Unread Articles}). ++@item t ++Number of ticked articles (@pxref{Unread Articles}). ++@item r ++Number of articles that have been marked as read in this session. ++@item E ++Number of articles expunged by the score files. ++@end table ++ ++ ++@node Summary Highlighting ++@subsection Summary Highlighting ++ ++@table @code ++ ++@item gnus-visual-mark-article-hook ++@vindex gnus-visual-mark-article-hook ++This hook is run after selecting an article. It is meant to be used for ++highlighting the article in some way. It is not run if ++@code{gnus-visual} is @code{nil}. ++ ++@item gnus-summary-update-hook ++@vindex gnus-summary-update-hook ++This hook is called when a summary line is changed. It is not run if ++@code{gnus-visual} is @code{nil}. ++ ++@item gnus-summary-selected-face ++@vindex gnus-summary-selected-face ++This is the face (or @dfn{font} as some people call it) used to ++highlight the current article in the summary buffer. ++ ++@item gnus-summary-highlight ++@vindex gnus-summary-highlight ++Summary lines are highlighted according to this variable, which is a ++list where the elements are of the format @code{(@var{form} ++. @var{face})}. If you would, for instance, like ticked articles to be ++italic and high-scored articles to be bold, you could set this variable ++to something like ++@lisp ++(((eq mark gnus-ticked-mark) . italic) ++ ((> score default) . bold)) ++@end lisp ++As you may have guessed, if @var{form} returns a non-@code{nil} value, ++@var{face} will be applied to the line. ++@end table ++ ++ ++@node Summary Maneuvering ++@section Summary Maneuvering ++@cindex summary movement ++ ++All the straight movement commands understand the numeric prefix and ++behave pretty much as you'd expect. ++ ++None of these commands select articles. ++ ++@table @kbd ++@item G M-n ++@itemx M-n ++@kindex M-n (Summary) ++@kindex G M-n (Summary) ++@findex gnus-summary-next-unread-subject ++Go to the next summary line of an unread article ++(@code{gnus-summary-next-unread-subject}). ++ ++@item G M-p ++@itemx M-p ++@kindex M-p (Summary) ++@kindex G M-p (Summary) ++@findex gnus-summary-prev-unread-subject ++Go to the previous summary line of an unread article ++(@code{gnus-summary-prev-unread-subject}). ++ ++@item G g ++@kindex G g (Summary) ++@findex gnus-summary-goto-subject ++Ask for an article number and then go to the summary line of that article ++without displaying the article (@code{gnus-summary-goto-subject}). ++@end table ++ ++If Gnus asks you to press a key to confirm going to the next group, you ++can use the @kbd{C-n} and @kbd{C-p} keys to move around the group ++buffer, searching for the next group to read without actually returning ++to the group buffer. ++ ++Variables related to summary movement: ++ ++@table @code ++ ++@vindex gnus-auto-select-next ++@item gnus-auto-select-next ++If you issue one of the movement commands (like @kbd{n}) and there are ++no more unread articles after the current one, Gnus will offer to go to ++the next group. If this variable is @code{t} and the next group is ++empty, Gnus will exit summary mode and return to the group buffer. If ++this variable is neither @code{t} nor @code{nil}, Gnus will select the ++next group with unread articles. As a special case, if this variable ++is @code{quietly}, Gnus will select the next group without asking for ++confirmation. If this variable is @code{almost-quietly}, the same ++will happen only if you are located on the last article in the group. ++Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n} ++command will go to the next group without confirmation. Also ++@pxref{Group Levels}. ++ ++@item gnus-auto-select-same ++@vindex gnus-auto-select-same ++If non-@code{nil}, all the movement commands will try to go to the next ++article with the same subject as the current. (@dfn{Same} here might ++mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit} ++for details (@pxref{Customizing Threading}).) If there are no more ++articles with the same subject, go to the first unread article. ++ ++This variable is not particularly useful if you use a threaded display. ++ ++@item gnus-summary-check-current ++@vindex gnus-summary-check-current ++If non-@code{nil}, all the ``unread'' movement commands will not proceed ++to the next (or previous) article if the current article is unread. ++Instead, they will choose the current article. ++ ++@item gnus-auto-center-summary ++@vindex gnus-auto-center-summary ++If non-@code{nil}, Gnus will keep the point in the summary buffer ++centered at all times. This makes things quite tidy, but if you have a ++slow network connection, or simply do not like this un-Emacsism, you can ++set this variable to @code{nil} to get the normal Emacs scrolling ++action. This will also inhibit horizontal re-centering of the summary ++buffer, which might make it more inconvenient to read extremely long ++threads. ++ ++This variable can also be a number. In that case, center the window at ++the given number of lines from the top. ++ ++@end table ++ ++ ++@node Choosing Articles ++@section Choosing Articles ++@cindex selecting articles ++ ++@menu ++* Choosing Commands:: Commands for choosing articles. ++* Choosing Variables:: Variables that influence these commands. ++@end menu ++ ++ ++@node Choosing Commands ++@subsection Choosing Commands ++ ++None of the following movement commands understand the numeric prefix, ++and they all select and display an article. ++ ++If you want to fetch new articles or redisplay the group, see ++@ref{Exiting the Summary Buffer}. ++ ++@table @kbd ++@item SPACE ++@kindex SPACE (Summary) ++@findex gnus-summary-next-page ++Select the current article, or, if that one's read already, the next ++unread article (@code{gnus-summary-next-page}). ++ ++If you have an article window open already and you press @kbd{SPACE} ++again, the article will be scrolled. This lets you conveniently ++@kbd{SPACE} through an entire newsgroup. @xref{Paging the Article}. ++ ++@item G n ++@itemx n ++@kindex n (Summary) ++@kindex G n (Summary) ++@findex gnus-summary-next-unread-article ++@c @icon{gnus-summary-next-unread} ++Go to next unread article (@code{gnus-summary-next-unread-article}). ++ ++@item G p ++@itemx p ++@kindex p (Summary) ++@findex gnus-summary-prev-unread-article ++@c @icon{gnus-summary-prev-unread} ++Go to previous unread article (@code{gnus-summary-prev-unread-article}). ++ ++@item G N ++@itemx N ++@kindex N (Summary) ++@kindex G N (Summary) ++@findex gnus-summary-next-article ++Go to the next article (@code{gnus-summary-next-article}). ++ ++@item G P ++@itemx P ++@kindex P (Summary) ++@kindex G P (Summary) ++@findex gnus-summary-prev-article ++Go to the previous article (@code{gnus-summary-prev-article}). ++ ++@item G C-n ++@kindex G C-n (Summary) ++@findex gnus-summary-next-same-subject ++Go to the next article with the same subject ++(@code{gnus-summary-next-same-subject}). ++ ++@item G C-p ++@kindex G C-p (Summary) ++@findex gnus-summary-prev-same-subject ++Go to the previous article with the same subject ++(@code{gnus-summary-prev-same-subject}). ++ ++@item G f ++@itemx . ++@kindex G f (Summary) ++@kindex . (Summary) ++@findex gnus-summary-first-unread-article ++Go to the first unread article ++(@code{gnus-summary-first-unread-article}). ++ ++@item G b ++@itemx , ++@kindex G b (Summary) ++@kindex , (Summary) ++@findex gnus-summary-best-unread-article ++Go to the unread article with the highest score ++(@code{gnus-summary-best-unread-article}). If given a prefix argument, ++go to the first unread article that has a score over the default score. ++ ++@item G l ++@itemx l ++@kindex l (Summary) ++@kindex G l (Summary) ++@findex gnus-summary-goto-last-article ++Go to the previous article read (@code{gnus-summary-goto-last-article}). ++ ++@item G o ++@kindex G o (Summary) ++@findex gnus-summary-pop-article ++@cindex history ++@cindex article history ++Pop an article off the summary history and go to this article ++(@code{gnus-summary-pop-article}). This command differs from the ++command above in that you can pop as many previous articles off the ++history as you like, while @kbd{l} toggles the two last read articles. ++For a somewhat related issue (if you use these commands a lot), ++@pxref{Article Backlog}. ++ ++@item G j ++@itemx j ++@kindex j (Summary) ++@kindex G j (Summary) ++@findex gnus-summary-goto-article ++Ask for an article number or @code{Message-ID}, and then go to that ++article (@code{gnus-summary-goto-article}). ++ ++@end table ++ ++ ++@node Choosing Variables ++@subsection Choosing Variables ++ ++Some variables relevant for moving and selecting articles: ++ ++@table @code ++@item gnus-auto-extend-newsgroup ++@vindex gnus-auto-extend-newsgroup ++All the movement commands will try to go to the previous (or next) ++article, even if that article isn't displayed in the Summary buffer if ++this variable is non-@code{nil}. Gnus will then fetch the article from ++the server and display it in the article buffer. ++ ++@item gnus-select-article-hook ++@vindex gnus-select-article-hook ++This hook is called whenever an article is selected. The default is ++@code{nil}. If you would like each article to be saved in the Agent as ++you read it, putting @code{gnus-agent-fetch-selected-article} on this ++hook will do so. ++ ++@item gnus-mark-article-hook ++@vindex gnus-mark-article-hook ++@findex gnus-summary-mark-unread-as-read ++@findex gnus-summary-mark-read-and-unread-as-read ++@findex gnus-unread-mark ++This hook is called whenever an article is selected. It is intended to ++be used for marking articles as read. The default value is ++@code{gnus-summary-mark-read-and-unread-as-read}, and will change the ++mark of almost any article you read to @code{gnus-read-mark}. The only ++articles not affected by this function are ticked, dormant, and ++expirable articles. If you'd instead like to just have unread articles ++marked as read, you can use @code{gnus-summary-mark-unread-as-read} ++instead. It will leave marks like @code{gnus-low-score-mark}, ++@code{gnus-del-mark} (and so on) alone. ++ ++@end table ++ ++ ++@node Paging the Article ++@section Scrolling the Article ++@cindex article scrolling ++ ++@table @kbd ++ ++@item SPACE ++@kindex SPACE (Summary) ++@findex gnus-summary-next-page ++Pressing @kbd{SPACE} will scroll the current article forward one page, ++or, if you have come to the end of the current article, will choose the ++next article (@code{gnus-summary-next-page}). ++ ++@vindex gnus-article-boring-faces ++@vindex gnus-article-skip-boring ++If @code{gnus-article-skip-boring} is non-@code{nil} and the rest of ++the article consists only of citations and signature, then it will be ++skipped; the next article will be shown instead. You can customize ++what is considered uninteresting with ++@code{gnus-article-boring-faces}. You can manually view the article's ++pages, no matter how boring, using @kbd{C-M-v}. ++ ++@item DEL ++@kindex DEL (Summary) ++@findex gnus-summary-prev-page ++Scroll the current article back one page (@code{gnus-summary-prev-page}). ++ ++@item RET ++@kindex RET (Summary) ++@findex gnus-summary-scroll-up ++Scroll the current article one line forward ++(@code{gnus-summary-scroll-up}). ++ ++@item M-RET ++@kindex M-RET (Summary) ++@findex gnus-summary-scroll-down ++Scroll the current article one line backward ++(@code{gnus-summary-scroll-down}). ++ ++@item A g ++@itemx g ++@kindex A g (Summary) ++@kindex g (Summary) ++@findex gnus-summary-show-article ++@vindex gnus-summary-show-article-charset-alist ++(Re)fetch the current article (@code{gnus-summary-show-article}). If ++given a prefix, fetch the current article, but don't run any of the ++article treatment functions. This will give you a ``raw'' article, just ++the way it came from the server. ++ ++@cindex charset, view article with different charset ++If given a numerical prefix, you can do semi-manual charset stuff. ++@kbd{C-u 0 g cn-gb-2312 RET} will decode the message as if it were ++encoded in the @code{cn-gb-2312} charset. If you have ++ ++@lisp ++(setq gnus-summary-show-article-charset-alist ++ '((1 . cn-gb-2312) ++ (2 . big5))) ++@end lisp ++ ++then you can say @kbd{C-u 1 g} to get the same effect. ++ ++@item A < ++@itemx < ++@kindex < (Summary) ++@kindex A < (Summary) ++@findex gnus-summary-beginning-of-article ++Scroll to the beginning of the article ++(@code{gnus-summary-beginning-of-article}). ++ ++@item A > ++@itemx > ++@kindex > (Summary) ++@kindex A > (Summary) ++@findex gnus-summary-end-of-article ++Scroll to the end of the article (@code{gnus-summary-end-of-article}). ++ ++@item A s ++@itemx s ++@kindex A s (Summary) ++@kindex s (Summary) ++@findex gnus-summary-isearch-article ++Perform an isearch in the article buffer ++(@code{gnus-summary-isearch-article}). ++ ++@item h ++@kindex h (Summary) ++@findex gnus-summary-select-article-buffer ++Select the article buffer (@code{gnus-summary-select-article-buffer}). ++ ++@end table ++ ++ ++@node Reply Followup and Post ++@section Reply, Followup and Post ++ ++@menu ++* Summary Mail Commands:: Sending mail. ++* Summary Post Commands:: Sending news. ++* Summary Message Commands:: Other Message-related commands. ++* Canceling and Superseding:: ++@end menu ++ ++ ++@node Summary Mail Commands ++@subsection Summary Mail Commands ++@cindex mail ++@cindex composing mail ++ ++Commands for composing a mail message: ++ ++@table @kbd ++ ++@item S r ++@itemx r ++@kindex S r (Summary) ++@kindex r (Summary) ++@findex gnus-summary-reply ++@c @icon{gnus-summary-mail-reply} ++@c @icon{gnus-summary-reply} ++Mail a reply to the author of the current article ++(@code{gnus-summary-reply}). ++ ++@item S R ++@itemx R ++@kindex R (Summary) ++@kindex S R (Summary) ++@findex gnus-summary-reply-with-original ++@c @icon{gnus-summary-reply-with-original} ++Mail a reply to the author of the current article and include the ++original message (@code{gnus-summary-reply-with-original}). This ++command uses the process/prefix convention. ++ ++@item S w ++@kindex S w (Summary) ++@findex gnus-summary-wide-reply ++Mail a wide reply to the author of the current article ++(@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that ++goes out to all people listed in the @code{To}, @code{From} (or ++@code{Reply-to}) and @code{Cc} headers. If @code{Mail-Followup-To} is ++present, that's used instead. ++ ++@item S W ++@kindex S W (Summary) ++@findex gnus-summary-wide-reply-with-original ++Mail a wide reply to the current article and include the original ++message (@code{gnus-summary-wide-reply-with-original}). This command uses ++the process/prefix convention. ++ ++@item S v ++@kindex S v (Summary) ++@findex gnus-summary-very-wide-reply ++Mail a very wide reply to the author of the current article ++(@code{gnus-summary-wide-reply}). A @dfn{very wide reply} is a reply ++that goes out to all people listed in the @code{To}, @code{From} (or ++@code{Reply-to}) and @code{Cc} headers in all the process/prefixed ++articles. This command uses the process/prefix convention. ++ ++@item S V ++@kindex S V (Summary) ++@findex gnus-summary-very-wide-reply-with-original ++Mail a very wide reply to the author of the current article and include the ++original message (@code{gnus-summary-very-wide-reply-with-original}). This ++command uses the process/prefix convention. ++ ++@item S B r ++@kindex S B r (Summary) ++@findex gnus-summary-reply-broken-reply-to ++Mail a reply to the author of the current article but ignore the ++@code{Reply-To} field (@code{gnus-summary-reply-broken-reply-to}). ++If you need this because a mailing list incorrectly sets a ++@code{Reply-To} header pointing to the list, you probably want to set ++the @code{broken-reply-to} group parameter instead, so things will work ++correctly. @xref{Group Parameters}. ++ ++@item S B R ++@kindex S B R (Summary) ++@findex gnus-summary-reply-broken-reply-to-with-original ++Mail a reply to the author of the current article and include the ++original message but ignore the @code{Reply-To} field ++(@code{gnus-summary-reply-broken-reply-to-with-original}). ++ ++@item S o m ++@itemx C-c C-f ++@kindex S o m (Summary) ++@kindex C-c C-f (Summary) ++@findex gnus-summary-mail-forward ++@c @icon{gnus-summary-mail-forward} ++Forward the current article to some other person ++(@code{gnus-summary-mail-forward}). If no prefix is given, the message ++is forwarded according to the value of (@code{message-forward-as-mime}) ++and (@code{message-forward-show-mml}); if the prefix is 1, decode the ++message and forward directly inline; if the prefix is 2, forward message ++as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and ++forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message ++directly inline; otherwise, the message is forwarded as no prefix given ++but use the flipped value of (@code{message-forward-as-mime}). By ++default, the message is decoded and forwarded as an rfc822 @acronym{MIME} ++section. ++ ++@item S m ++@itemx m ++@kindex m (Summary) ++@kindex S m (Summary) ++@findex gnus-summary-mail-other-window ++@c @icon{gnus-summary-mail-originate} ++Prepare a mail (@code{gnus-summary-mail-other-window}). By default, use ++the posting style of the current group. If given a prefix, disable that. ++If the prefix is 1, prompt for a group name to find the posting style. ++ ++@item S i ++@itemx i ++@kindex i (Summary) ++@kindex S i (Summary) ++@findex gnus-summary-news-other-window ++Prepare a news (@code{gnus-summary-news-other-window}). By default, ++post to the current group. If given a prefix, disable that. If the ++prefix is 1, prompt for a group to post to. ++ ++This function actually prepares a news even when using mail groups. ++This is useful for ``posting'' messages to mail groups without actually ++sending them over the network: they're just saved directly to the group ++in question. The corresponding back end must have a request-post method ++for this to work though. ++ ++@item S D b ++@kindex S D b (Summary) ++@findex gnus-summary-resend-bounced-mail ++@cindex bouncing mail ++If you have sent a mail, but the mail was bounced back to you for some ++reason (wrong address, transient failure), you can use this command to ++resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You ++will be popped into a mail buffer where you can edit the headers before ++sending the mail off again. If you give a prefix to this command, and ++the bounced mail is a reply to some other mail, Gnus will try to fetch ++that mail and display it for easy perusal of its headers. This might ++very well fail, though. ++ ++@item S D r ++@kindex S D r (Summary) ++@findex gnus-summary-resend-message ++Not to be confused with the previous command, ++@code{gnus-summary-resend-message} will prompt you for an address to ++send the current message off to, and then send it to that place. The ++headers of the message won't be altered---but lots of headers that say ++@code{Resent-To}, @code{Resent-From} and so on will be added. This ++means that you actually send a mail to someone that has a @code{To} ++header that (probably) points to yourself. This will confuse people. ++So, natcherly you'll only do that if you're really eVIl. ++ ++This command is mainly used if you have several accounts and want to ++ship a mail to a different account of yours. (If you're both ++@code{root} and @code{postmaster} and get a mail for @code{postmaster} ++to the @code{root} account, you may want to resend it to ++@code{postmaster}. Ordnung muss sein! ++ ++This command understands the process/prefix convention ++(@pxref{Process/Prefix}). ++ ++@item S D e ++@kindex S D e (Summary) ++@findex gnus-summary-resend-message-edit ++ ++Like the previous command, but will allow you to edit the message as ++if it were a new message before resending. ++ ++@item S O m ++@kindex S O m (Summary) ++@findex gnus-uu-digest-mail-forward ++Digest the current series (@pxref{Decoding Articles}) and forward the ++result using mail (@code{gnus-uu-digest-mail-forward}). This command ++uses the process/prefix convention (@pxref{Process/Prefix}). ++ ++@item S M-c ++@kindex S M-c (Summary) ++@findex gnus-summary-mail-crosspost-complaint ++@cindex crossposting ++@cindex excessive crossposting ++Send a complaint about excessive crossposting to the author of the ++current article (@code{gnus-summary-mail-crosspost-complaint}). ++ ++@findex gnus-crosspost-complaint ++This command is provided as a way to fight back against the current ++crossposting pandemic that's sweeping Usenet. It will compose a reply ++using the @code{gnus-crosspost-complaint} variable as a preamble. This ++command understands the process/prefix convention ++(@pxref{Process/Prefix}) and will prompt you before sending each mail. ++ ++@end table ++ ++Also @xref{Header Commands, ,Header Commands, message, The Message ++Manual}, for more information. ++ ++ ++@node Summary Post Commands ++@subsection Summary Post Commands ++@cindex post ++@cindex composing news ++ ++Commands for posting a news article: ++ ++@table @kbd ++@item S p ++@itemx a ++@kindex a (Summary) ++@kindex S p (Summary) ++@findex gnus-summary-post-news ++@c @icon{gnus-summary-post-news} ++Prepare for posting an article (@code{gnus-summary-post-news}). By ++default, post to the current group. If given a prefix, disable that. ++If the prefix is 1, prompt for another group instead. ++ ++@item S f ++@itemx f ++@kindex f (Summary) ++@kindex S f (Summary) ++@findex gnus-summary-followup ++@c @icon{gnus-summary-followup} ++Post a followup to the current article (@code{gnus-summary-followup}). ++ ++@item S F ++@itemx F ++@kindex S F (Summary) ++@kindex F (Summary) ++@c @icon{gnus-summary-followup-with-original} ++@findex gnus-summary-followup-with-original ++Post a followup to the current article and include the original message ++(@code{gnus-summary-followup-with-original}). This command uses the ++process/prefix convention. ++ ++@item S n ++@kindex S n (Summary) ++@findex gnus-summary-followup-to-mail ++Post a followup to the current article via news, even if you got the ++message through mail (@code{gnus-summary-followup-to-mail}). ++ ++@item S N ++@kindex S N (Summary) ++@findex gnus-summary-followup-to-mail-with-original ++Post a followup to the current article via news, even if you got the ++message through mail and include the original message ++(@code{gnus-summary-followup-to-mail-with-original}). This command uses ++the process/prefix convention. ++ ++@item S o p ++@kindex S o p (Summary) ++@findex gnus-summary-post-forward ++Forward the current article to a newsgroup ++(@code{gnus-summary-post-forward}). ++ If no prefix is given, the message is forwarded according to the value ++of (@code{message-forward-as-mime}) and ++(@code{message-forward-show-mml}); if the prefix is 1, decode the ++message and forward directly inline; if the prefix is 2, forward message ++as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and ++forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message ++directly inline; otherwise, the message is forwarded as no prefix given ++but use the flipped value of (@code{message-forward-as-mime}). By ++default, the message is decoded and forwarded as an rfc822 @acronym{MIME} section. ++ ++@item S O p ++@kindex S O p (Summary) ++@findex gnus-uu-digest-post-forward ++@cindex digests ++@cindex making digests ++Digest the current series and forward the result to a newsgroup ++(@code{gnus-uu-digest-post-forward}). This command uses the ++process/prefix convention. ++ ++@item S u ++@kindex S u (Summary) ++@findex gnus-uu-post-news ++@c @icon{gnus-uu-post-news} ++Uuencode a file, split it into parts, and post it as a series ++(@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}). ++@end table ++ ++Also @xref{Header Commands, ,Header Commands, message, The Message ++Manual}, for more information. ++ ++ ++@node Summary Message Commands ++@subsection Summary Message Commands ++ ++@table @kbd ++@item S y ++@kindex S y (Summary) ++@findex gnus-summary-yank-message ++Yank the current article into an already existing Message composition ++buffer (@code{gnus-summary-yank-message}). This command prompts for ++what message buffer you want to yank into, and understands the ++process/prefix convention (@pxref{Process/Prefix}). ++ ++@end table ++ ++ ++@node Canceling and Superseding ++@subsection Canceling Articles ++@cindex canceling articles ++@cindex superseding articles ++ ++Have you ever written something, and then decided that you really, ++really, really wish you hadn't posted that? ++ ++Well, you can't cancel mail, but you can cancel posts. ++ ++@findex gnus-summary-cancel-article ++@kindex C (Summary) ++@c @icon{gnus-summary-cancel-article} ++Find the article you wish to cancel (you can only cancel your own ++articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S ++c} (@code{gnus-summary-cancel-article}). Your article will be ++canceled---machines all over the world will be deleting your article. ++This command uses the process/prefix convention (@pxref{Process/Prefix}). ++ ++Be aware, however, that not all sites honor cancels, so your article may ++live on here and there, while most sites will delete the article in ++question. ++ ++Gnus will use the ``current'' select method when canceling. If you ++want to use the standard posting method, use the @samp{a} symbolic ++prefix (@pxref{Symbolic Prefixes}). ++ ++Gnus ensures that only you can cancel your own messages using a ++@code{Cancel-Lock} header (@pxref{Canceling News, Canceling News, , ++message, Message Manual}). ++ ++If you discover that you have made some mistakes and want to do some ++corrections, you can post a @dfn{superseding} article that will replace ++your original article. ++ ++@findex gnus-summary-supersede-article ++@kindex S (Summary) ++Go to the original article and press @kbd{S s} ++(@code{gnus-summary-supersede-article}). You will be put in a buffer ++where you can edit the article all you want before sending it off the ++usual way. ++ ++The same goes for superseding as for canceling, only more so: Some ++sites do not honor superseding. On those sites, it will appear that you ++have posted almost the same article twice. ++ ++If you have just posted the article, and change your mind right away, ++there is a trick you can use to cancel/supersede the article without ++waiting for the article to appear on your site first. You simply return ++to the post buffer (which is called @code{*sent ...*}). There you will ++find the article you just posted, with all the headers intact. Change ++the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes} ++header by substituting one of those words for the word ++@code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as ++you would do normally. The previous article will be ++canceled/superseded. ++ ++Just remember, kids: There is no 'c' in 'supersede'. ++ ++@node Delayed Articles ++@section Delayed Articles ++@cindex delayed sending ++@cindex send delayed ++ ++Sometimes, you might wish to delay the sending of a message. For ++example, you might wish to arrange for a message to turn up just in time ++to remind your about the birthday of your Significant Other. For this, ++there is the @code{gnus-delay} package. Setup is simple: ++ ++@lisp ++(gnus-delay-initialize) ++@end lisp ++ ++@findex gnus-delay-article ++Normally, to send a message you use the @kbd{C-c C-c} command from ++Message mode. To delay a message, use @kbd{C-c C-j} ++(@code{gnus-delay-article}) instead. This will ask you for how long the ++message should be delayed. Possible answers are: ++ ++@itemize @bullet ++@item ++A time span. Consists of an integer and a letter. For example, ++@code{42d} means to delay for 42 days. Available letters are @code{m} ++(minutes), @code{h} (hours), @code{d} (days), @code{w} (weeks), @code{M} ++(months) and @code{Y} (years). ++ ++@item ++A specific date. Looks like @code{YYYY-MM-DD}. The message will be ++delayed until that day, at a specific time (eight o'clock by default). ++See also @code{gnus-delay-default-hour}. ++ ++@item ++A specific time of day. Given in @code{hh:mm} format, 24h, no am/pm ++stuff. The deadline will be at that time today, except if that time has ++already passed, then it's at the given time tomorrow. So if it's ten ++o'clock in the morning and you specify @code{11:15}, then the deadline ++is one hour and fifteen minutes hence. But if you specify @code{9:20}, ++that means a time tomorrow. ++@end itemize ++ ++The action of the @code{gnus-delay-article} command is influenced by a ++couple of variables: ++ ++@table @code ++@item gnus-delay-default-hour ++@vindex gnus-delay-default-hour ++When you specify a specific date, the message will be due on that hour ++on the given date. Possible values are integers 0 through 23. ++ ++@item gnus-delay-default-delay ++@vindex gnus-delay-default-delay ++This is a string and gives the default delay. It can be of any of the ++formats described above. ++ ++@item gnus-delay-group ++@vindex gnus-delay-group ++Delayed articles will be kept in this group on the drafts server until ++they are due. You probably don't need to change this. The default ++value is @code{"delayed"}. ++ ++@item gnus-delay-header ++@vindex gnus-delay-header ++The deadline for each article will be stored in a header. This variable ++is a string and gives the header name. You probably don't need to ++change this. The default value is @code{"X-Gnus-Delayed"}. ++@end table ++ ++The way delaying works is like this: when you use the ++@code{gnus-delay-article} command, you give a certain delay. Gnus ++calculates the deadline of the message and stores it in the ++@code{X-Gnus-Delayed} header and puts the message in the ++@code{nndraft:delayed} group. ++ ++@findex gnus-delay-send-queue ++And whenever you get new news, Gnus looks through the group for articles ++which are due and sends them. It uses the @code{gnus-delay-send-queue} ++function for this. By default, this function is added to the hook ++@code{gnus-get-new-news-hook}. But of course, you can change this. ++Maybe you want to use the demon to send drafts? Just tell the demon to ++execute the @code{gnus-delay-send-queue} function. ++ ++@table @code ++@item gnus-delay-initialize ++@findex gnus-delay-initialize ++By default, this function installs @code{gnus-delay-send-queue} in ++@code{gnus-get-new-news-hook}. But it accepts the optional second ++argument @code{no-check}. If it is non-@code{nil}, ++@code{gnus-get-new-news-hook} is not changed. The optional first ++argument is ignored. ++ ++For example, @code{(gnus-delay-initialize nil t)} means to do nothing. ++Presumably, you want to use the demon for sending due delayed articles. ++Just don't forget to set that up :-) ++@end table ++ ++ ++@node Marking Articles ++@section Marking Articles ++@cindex article marking ++@cindex article ticking ++@cindex marks ++ ++There are several marks you can set on an article. ++ ++You have marks that decide the @dfn{readedness} (whoo, neato-keano ++neologism ohoy!) of the article. Alphabetic marks generally mean ++@dfn{read}, while non-alphabetic characters generally mean @dfn{unread}. ++ ++In addition, you also have marks that do not affect readedness. ++ ++@ifinfo ++There's a plethora of commands for manipulating these marks. ++@end ifinfo ++ ++@menu ++* Unread Articles:: Marks for unread articles. ++* Read Articles:: Marks for read articles. ++* Other Marks:: Marks that do not affect readedness. ++* Setting Marks:: How to set and remove marks. ++* Generic Marking Commands:: How to customize the marking. ++* Setting Process Marks:: How to mark articles for later processing. ++@end menu ++ ++ ++@node Unread Articles ++@subsection Unread Articles ++ ++The following marks mark articles as (kinda) unread, in one form or ++other. ++ ++@table @samp ++@item ! ++@vindex gnus-ticked-mark ++Marked as ticked (@code{gnus-ticked-mark}). ++ ++@dfn{Ticked articles} are articles that will remain visible always. If ++you see an article that you find interesting, or you want to put off ++reading it, or replying to it, until sometime later, you'd typically ++tick it. However, articles can be expired (from news servers by the ++news server software, Gnus itself never expires ticked messages), so if ++you want to keep an article forever, you'll have to make it persistent ++(@pxref{Persistent Articles}). ++ ++@item ? ++@vindex gnus-dormant-mark ++Marked as dormant (@code{gnus-dormant-mark}). ++ ++@dfn{Dormant articles} will only appear in the summary buffer if there ++are followups to it. If you want to see them even if they don't have ++followups, you can use the @kbd{/ D} command (@pxref{Limiting}). ++Otherwise (except for the visibility issue), they are just like ticked ++messages. ++ ++@item SPACE ++@vindex gnus-unread-mark ++Marked as unread (@code{gnus-unread-mark}). ++ ++@dfn{Unread articles} are articles that haven't been read at all yet. ++@end table ++ ++ ++@node Read Articles ++@subsection Read Articles ++@cindex expirable mark ++ ++All the following marks mark articles as read. ++ ++@table @samp ++ ++@item r ++@vindex gnus-del-mark ++These are articles that the user has marked as read with the @kbd{d} ++command manually, more or less (@code{gnus-del-mark}). ++ ++@item R ++@vindex gnus-read-mark ++Articles that have actually been read (@code{gnus-read-mark}). ++ ++@item O ++@vindex gnus-ancient-mark ++Articles that were marked as read in previous sessions and are now ++@dfn{old} (@code{gnus-ancient-mark}). ++ ++@item K ++@vindex gnus-killed-mark ++Marked as killed (@code{gnus-killed-mark}). ++ ++@item X ++@vindex gnus-kill-file-mark ++Marked as killed by kill files (@code{gnus-kill-file-mark}). ++ ++@item Y ++@vindex gnus-low-score-mark ++Marked as read by having too low a score (@code{gnus-low-score-mark}). ++ ++@item C ++@vindex gnus-catchup-mark ++Marked as read by a catchup (@code{gnus-catchup-mark}). ++ ++@item G ++@vindex gnus-canceled-mark ++Canceled article (@code{gnus-canceled-mark}) ++ ++@item F ++@vindex gnus-souped-mark ++@sc{soup}ed article (@code{gnus-souped-mark}). @xref{SOUP}. ++ ++@item Q ++@vindex gnus-sparse-mark ++Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing ++Threading}. ++ ++@item M ++@vindex gnus-duplicate-mark ++Article marked as read by duplicate suppression ++(@code{gnus-duplicate-mark}). @xref{Duplicate Suppression}. ++ ++@end table ++ ++All these marks just mean that the article is marked as read, really. ++They are interpreted differently when doing adaptive scoring, though. ++ ++One more special mark, though: ++ ++@table @samp ++@item E ++@vindex gnus-expirable-mark ++Marked as expirable (@code{gnus-expirable-mark}). ++ ++Marking articles as @dfn{expirable} (or have them marked as such ++automatically) doesn't make much sense in normal groups---a user doesn't ++control expiring of news articles, but in mail groups, for instance, ++articles marked as @dfn{expirable} can be deleted by Gnus at ++any time. ++@end table ++ ++ ++@node Other Marks ++@subsection Other Marks ++@cindex process mark ++@cindex bookmarks ++ ++There are some marks that have nothing to do with whether the article is ++read or not. ++ ++@itemize @bullet ++ ++@item ++You can set a bookmark in the current article. Say you are reading a ++long thesis on cats' urinary tracts, and have to go home for dinner ++before you've finished reading the thesis. You can then set a bookmark ++in the article, and Gnus will jump to this bookmark the next time it ++encounters the article. @xref{Setting Marks}. ++ ++@item ++@vindex gnus-replied-mark ++All articles that you have replied to or made a followup to (i.e., have ++answered) will be marked with an @samp{A} in the second column ++(@code{gnus-replied-mark}). ++ ++@item ++@vindex gnus-forwarded-mark ++All articles that you have forwarded will be marked with an @samp{F} in ++the second column (@code{gnus-forwarded-mark}). ++ ++@item ++@vindex gnus-cached-mark ++Articles stored in the article cache will be marked with an @samp{*} in ++the second column (@code{gnus-cached-mark}). @xref{Article Caching}. ++ ++@item ++@vindex gnus-saved-mark ++Articles ``saved'' (in some manner or other; not necessarily ++religiously) are marked with an @samp{S} in the second column ++(@code{gnus-saved-mark}). ++ ++@item ++@vindex gnus-recent-mark ++Articles that according to the server haven't been shown to the user ++before are marked with a @samp{N} in the second column ++(@code{gnus-recent-mark}). Note that not all servers support this ++mark, in which case it simply never appears. Compare with ++@code{gnus-unseen-mark}. ++ ++@item ++@vindex gnus-unseen-mark ++Articles that haven't been seen before in Gnus by the user are marked ++with a @samp{.} in the second column (@code{gnus-unseen-mark}). ++Compare with @code{gnus-recent-mark}. ++ ++@item ++@vindex gnus-downloaded-mark ++When using the Gnus agent (@pxref{Agent Basics}), articles may be ++downloaded for unplugged (offline) viewing. If you are using the ++@samp{%O} spec, these articles get the @samp{+} mark in that spec. ++(The variable @code{gnus-downloaded-mark} controls which character to ++use.) ++ ++@item ++@vindex gnus-undownloaded-mark ++When using the Gnus agent (@pxref{Agent Basics}), some articles might ++not have been downloaded. Such articles cannot be viewed while you ++are unplugged (offline). If you are using the @samp{%O} spec, these ++articles get the @samp{-} mark in that spec. (The variable ++@code{gnus-undownloaded-mark} controls which character to use.) ++ ++@item ++@vindex gnus-downloadable-mark ++The Gnus agent (@pxref{Agent Basics}) downloads some articles ++automatically, but it is also possible to explicitly mark articles for ++download, even if they would not be downloaded automatically. Such ++explicitly-marked articles get the @samp{%} mark in the first column. ++(The variable @code{gnus-downloadable-mark} controls which character to ++use.) ++ ++@item ++@vindex gnus-not-empty-thread-mark ++@vindex gnus-empty-thread-mark ++If the @samp{%e} spec is used, the presence of threads or not will be ++marked with @code{gnus-not-empty-thread-mark} and ++@code{gnus-empty-thread-mark} in the third column, respectively. ++ ++@item ++@vindex gnus-process-mark ++Finally we have the @dfn{process mark} (@code{gnus-process-mark}). A ++variety of commands react to the presence of the process mark. For ++instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view ++all articles that have been marked with the process mark. Articles ++marked with the process mark have a @samp{#} in the second column. ++ ++@end itemize ++ ++You might have noticed that most of these ``non-readedness'' marks ++appear in the second column by default. So if you have a cached, saved, ++replied article that you have process-marked, what will that look like? ++ ++Nothing much. The precedence rules go as follows: process -> cache -> ++replied -> saved. So if the article is in the cache and is replied, ++you'll only see the cache mark and not the replied mark. ++ ++ ++@node Setting Marks ++@subsection Setting Marks ++@cindex setting marks ++ ++All the marking commands understand the numeric prefix. ++ ++@table @kbd ++@item M c ++@itemx M-u ++@kindex M c (Summary) ++@kindex M-u (Summary) ++@findex gnus-summary-clear-mark-forward ++@cindex mark as unread ++Clear all readedness-marks from the current article ++(@code{gnus-summary-clear-mark-forward}). In other words, mark the ++article as unread. ++ ++@item M t ++@itemx ! ++@kindex ! (Summary) ++@kindex M t (Summary) ++@findex gnus-summary-tick-article-forward ++Tick the current article (@code{gnus-summary-tick-article-forward}). ++@xref{Article Caching}. ++ ++@item M ? ++@itemx ? ++@kindex ? (Summary) ++@kindex M ? (Summary) ++@findex gnus-summary-mark-as-dormant ++Mark the current article as dormant ++(@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}. ++ ++@item M d ++@itemx d ++@kindex M d (Summary) ++@kindex d (Summary) ++@findex gnus-summary-mark-as-read-forward ++Mark the current article as read ++(@code{gnus-summary-mark-as-read-forward}). ++ ++@item D ++@kindex D (Summary) ++@findex gnus-summary-mark-as-read-backward ++Mark the current article as read and move point to the previous line ++(@code{gnus-summary-mark-as-read-backward}). ++ ++@item M k ++@itemx k ++@kindex k (Summary) ++@kindex M k (Summary) ++@findex gnus-summary-kill-same-subject-and-select ++Mark all articles that have the same subject as the current one as read, ++and then select the next unread article ++(@code{gnus-summary-kill-same-subject-and-select}). ++ ++@item M K ++@itemx C-k ++@kindex M K (Summary) ++@kindex C-k (Summary) ++@findex gnus-summary-kill-same-subject ++Mark all articles that have the same subject as the current one as read ++(@code{gnus-summary-kill-same-subject}). ++ ++@item M C ++@kindex M C (Summary) ++@findex gnus-summary-catchup ++@c @icon{gnus-summary-catchup} ++Mark all unread articles as read (@code{gnus-summary-catchup}). ++ ++@item M C-c ++@kindex M C-c (Summary) ++@findex gnus-summary-catchup-all ++Mark all articles in the group as read---even the ticked and dormant ++articles (@code{gnus-summary-catchup-all}). ++ ++@item M H ++@kindex M H (Summary) ++@findex gnus-summary-catchup-to-here ++Catchup the current group to point (before the point) ++(@code{gnus-summary-catchup-to-here}). ++ ++@item M h ++@kindex M h (Summary) ++@findex gnus-summary-catchup-from-here ++Catchup the current group from point (after the point) ++(@code{gnus-summary-catchup-from-here}). ++ ++@item C-w ++@kindex C-w (Summary) ++@findex gnus-summary-mark-region-as-read ++Mark all articles between point and mark as read ++(@code{gnus-summary-mark-region-as-read}). ++ ++@item M V k ++@kindex M V k (Summary) ++@findex gnus-summary-kill-below ++Kill all articles with scores below the default score (or below the ++numeric prefix) (@code{gnus-summary-kill-below}). ++ ++@item M e ++@itemx E ++@kindex M e (Summary) ++@kindex E (Summary) ++@findex gnus-summary-mark-as-expirable ++Mark the current article as expirable ++(@code{gnus-summary-mark-as-expirable}). ++ ++@item M b ++@kindex M b (Summary) ++@findex gnus-summary-set-bookmark ++Set a bookmark in the current article ++(@code{gnus-summary-set-bookmark}). ++ ++@item M B ++@kindex M B (Summary) ++@findex gnus-summary-remove-bookmark ++Remove the bookmark from the current article ++(@code{gnus-summary-remove-bookmark}). ++ ++@item M V c ++@kindex M V c (Summary) ++@findex gnus-summary-clear-above ++Clear all marks from articles with scores over the default score (or ++over the numeric prefix) (@code{gnus-summary-clear-above}). ++ ++@item M V u ++@kindex M V u (Summary) ++@findex gnus-summary-tick-above ++Tick all articles with scores over the default score (or over the ++numeric prefix) (@code{gnus-summary-tick-above}). ++ ++@item M V m ++@kindex M V m (Summary) ++@findex gnus-summary-mark-above ++Prompt for a mark, and mark all articles with scores over the default ++score (or over the numeric prefix) with this mark ++(@code{gnus-summary-clear-above}). ++@end table ++ ++@vindex gnus-summary-goto-unread ++The @code{gnus-summary-goto-unread} variable controls what action should ++be taken after setting a mark. If non-@code{nil}, point will move to ++the next/previous unread article. If @code{nil}, point will just move ++one line up or down. As a special case, if this variable is ++@code{never}, all the marking commands as well as other commands (like ++@kbd{SPACE}) will move to the next article, whether it is unread or not. ++The default is @code{t}. ++ ++ ++@node Generic Marking Commands ++@subsection Generic Marking Commands ++ ++Some people would like the command that ticks an article (@kbd{!}) go to ++the next article. Others would like it to go to the next unread ++article. Yet others would like it to stay on the current article. And ++even though I haven't heard of anybody wanting it to go to the ++previous (unread) article, I'm sure there are people that want that as ++well. ++ ++Multiply these five behaviors with five different marking commands, and ++you get a potentially complex set of variable to control what each ++command should do. ++ ++To sidestep that mess, Gnus provides commands that do all these ++different things. They can be found on the @kbd{M M} map in the summary ++buffer. Type @kbd{M M C-h} to see them all---there are too many of them ++to list in this manual. ++ ++While you can use these commands directly, most users would prefer ++altering the summary mode keymap. For instance, if you would like the ++@kbd{!} command to go to the next article instead of the next unread ++article, you could say something like: ++ ++@lisp ++@group ++(add-hook 'gnus-summary-mode-hook 'my-alter-summary-map) ++(defun my-alter-summary-map () ++ (local-set-key "!" 'gnus-summary-put-mark-as-ticked-next)) ++@end group ++@end lisp ++ ++@noindent ++or ++ ++@lisp ++(defun my-alter-summary-map () ++ (local-set-key "!" "MM!n")) ++@end lisp ++ ++ ++@node Setting Process Marks ++@subsection Setting Process Marks ++@cindex setting process marks ++ ++Process marks are displayed as @code{#} in the summary buffer, and are ++used for marking articles in such a way that other commands will ++process these articles. For instance, if you process mark four ++articles and then use the @kbd{*} command, Gnus will enter these four ++articles into the cache. For more information, ++@pxref{Process/Prefix}. ++ ++@table @kbd ++ ++@item M P p ++@itemx # ++@kindex # (Summary) ++@kindex M P p (Summary) ++@findex gnus-summary-mark-as-processable ++Mark the current article with the process mark ++(@code{gnus-summary-mark-as-processable}). ++@findex gnus-summary-unmark-as-processable ++ ++@item M P u ++@itemx M-# ++@kindex M P u (Summary) ++@kindex M-# (Summary) ++Remove the process mark, if any, from the current article ++(@code{gnus-summary-unmark-as-processable}). ++ ++@item M P U ++@kindex M P U (Summary) ++@findex gnus-summary-unmark-all-processable ++Remove the process mark from all articles ++(@code{gnus-summary-unmark-all-processable}). ++ ++@item M P i ++@kindex M P i (Summary) ++@findex gnus-uu-invert-processable ++Invert the list of process marked articles ++(@code{gnus-uu-invert-processable}). ++ ++@item M P R ++@kindex M P R (Summary) ++@findex gnus-uu-mark-by-regexp ++Mark articles that have a @code{Subject} header that matches a regular ++expression (@code{gnus-uu-mark-by-regexp}). ++ ++@item M P G ++@kindex M P G (Summary) ++@findex gnus-uu-unmark-by-regexp ++Unmark articles that have a @code{Subject} header that matches a regular ++expression (@code{gnus-uu-unmark-by-regexp}). ++ ++@item M P r ++@kindex M P r (Summary) ++@findex gnus-uu-mark-region ++Mark articles in region (@code{gnus-uu-mark-region}). ++ ++@item M P g ++@kindex M P g (Summary) ++@findex gnus-uu-unmark-region ++Unmark articles in region (@code{gnus-uu-unmark-region}). ++ ++@item M P t ++@kindex M P t (Summary) ++@findex gnus-uu-mark-thread ++Mark all articles in the current (sub)thread ++(@code{gnus-uu-mark-thread}). ++ ++@item M P T ++@kindex M P T (Summary) ++@findex gnus-uu-unmark-thread ++Unmark all articles in the current (sub)thread ++(@code{gnus-uu-unmark-thread}). ++ ++@item M P v ++@kindex M P v (Summary) ++@findex gnus-uu-mark-over ++Mark all articles that have a score above the prefix argument ++(@code{gnus-uu-mark-over}). ++ ++@item M P s ++@kindex M P s (Summary) ++@findex gnus-uu-mark-series ++Mark all articles in the current series (@code{gnus-uu-mark-series}). ++ ++@item M P S ++@kindex M P S (Summary) ++@findex gnus-uu-mark-sparse ++Mark all series that have already had some articles marked ++(@code{gnus-uu-mark-sparse}). ++ ++@item M P a ++@kindex M P a (Summary) ++@findex gnus-uu-mark-all ++Mark all articles in series order (@code{gnus-uu-mark-all}). ++ ++@item M P b ++@kindex M P b (Summary) ++@findex gnus-uu-mark-buffer ++Mark all articles in the buffer in the order they appear ++(@code{gnus-uu-mark-buffer}). ++ ++@item M P k ++@kindex M P k (Summary) ++@findex gnus-summary-kill-process-mark ++Push the current process mark set onto the stack and unmark all articles ++(@code{gnus-summary-kill-process-mark}). ++ ++@item M P y ++@kindex M P y (Summary) ++@findex gnus-summary-yank-process-mark ++Pop the previous process mark set from the stack and restore it ++(@code{gnus-summary-yank-process-mark}). ++ ++@item M P w ++@kindex M P w (Summary) ++@findex gnus-summary-save-process-mark ++Push the current process mark set onto the stack ++(@code{gnus-summary-save-process-mark}). ++ ++@end table ++ ++Also see the @kbd{&} command in @ref{Searching for Articles}, for how to ++set process marks based on article body contents. ++ ++ ++@node Limiting ++@section Limiting ++@cindex limiting ++ ++It can be convenient to limit the summary buffer to just show some ++subset of the articles currently in the group. The effect most limit ++commands have is to remove a few (or many) articles from the summary ++buffer. ++ ++Limiting commands work on subsets of the articles already fetched from ++the servers. These commands don't query the server for additional ++articles. ++ ++@table @kbd ++ ++@item / / ++@itemx / s ++@kindex / / (Summary) ++@findex gnus-summary-limit-to-subject ++Limit the summary buffer to articles that match some subject ++(@code{gnus-summary-limit-to-subject}). If given a prefix, exclude ++matching articles. ++ ++@item / a ++@kindex / a (Summary) ++@findex gnus-summary-limit-to-author ++Limit the summary buffer to articles that match some author ++(@code{gnus-summary-limit-to-author}). If given a prefix, exclude ++matching articles. ++ ++@item / R ++@kindex / R (Summary) ++@findex gnus-summary-limit-to-recipient ++Limit the summary buffer to articles that match some recipient ++(@code{gnus-summary-limit-to-recipient}). If given a prefix, exclude ++matching articles. ++ ++@item / A ++@kindex / A (Summary) ++@findex gnus-summary-limit-to-address ++Limit the summary buffer to articles in which contents of From, To or Cc ++header match a given address (@code{gnus-summary-limit-to-address}). If ++given a prefix, exclude matching articles. ++ ++@item / S ++@kindex / S (Summary) ++@findex gnus-summary-limit-to-singletons ++Limit the summary buffer to articles that aren't part of any displayed ++threads (@code{gnus-summary-limit-to-singletons}). If given a prefix, ++limit to articles that are part of displayed threads. ++ ++@item / x ++@kindex / x (Summary) ++@findex gnus-summary-limit-to-extra ++Limit the summary buffer to articles that match one of the ``extra'' ++headers (@pxref{To From Newsgroups}) ++(@code{gnus-summary-limit-to-extra}). If given a prefix, exclude ++matching articles. ++ ++@item / u ++@itemx x ++@kindex / u (Summary) ++@kindex x (Summary) ++@findex gnus-summary-limit-to-unread ++Limit the summary buffer to articles not marked as read ++(@code{gnus-summary-limit-to-unread}). If given a prefix, limit the ++buffer to articles strictly unread. This means that ticked and ++dormant articles will also be excluded. ++ ++@item / m ++@kindex / m (Summary) ++@findex gnus-summary-limit-to-marks ++Ask for a mark and then limit to all articles that have been marked ++with that mark (@code{gnus-summary-limit-to-marks}). ++ ++@item / t ++@kindex / t (Summary) ++@findex gnus-summary-limit-to-age ++Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days ++(@code{gnus-summary-limit-to-age}). If given a prefix, limit to ++articles younger than that number of days. ++ ++@item / n ++@kindex / n (Summary) ++@findex gnus-summary-limit-to-articles ++With prefix @samp{n}, limit the summary buffer to the next @samp{n} ++articles. If not given a prefix, use the process marked articles ++instead. (@code{gnus-summary-limit-to-articles}). ++ ++@item / w ++@kindex / w (Summary) ++@findex gnus-summary-pop-limit ++Pop the previous limit off the stack and restore it ++(@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off ++the stack. ++ ++@item / . ++@kindex / . (Summary) ++@findex gnus-summary-limit-to-unseen ++Limit the summary buffer to the unseen articles ++(@code{gnus-summary-limit-to-unseen}). ++ ++@item / v ++@kindex / v (Summary) ++@findex gnus-summary-limit-to-score ++Limit the summary buffer to articles that have a score at or above some ++score (@code{gnus-summary-limit-to-score}). ++ ++@item / p ++@kindex / p (Summary) ++@findex gnus-summary-limit-to-display-predicate ++Limit the summary buffer to articles that satisfy the @code{display} ++group parameter predicate ++(@code{gnus-summary-limit-to-display-predicate}). @xref{Group ++Parameters}, for more on this predicate. ++ ++@item / r ++@kindex / r (Summary) ++@findex gnus-summary-limit-to-replied ++Limit the summary buffer to replied articles ++(@code{gnus-summary-limit-to-replied}). If given a prefix, exclude ++replied articles. ++ ++@item / E ++@itemx M S ++@kindex M S (Summary) ++@kindex / E (Summary) ++@findex gnus-summary-limit-include-expunged ++Include all expunged articles in the limit ++(@code{gnus-summary-limit-include-expunged}). ++ ++@item / D ++@kindex / D (Summary) ++@findex gnus-summary-limit-include-dormant ++Include all dormant articles in the limit ++(@code{gnus-summary-limit-include-dormant}). ++ ++@item / * ++@kindex / * (Summary) ++@findex gnus-summary-limit-include-cached ++Include all cached articles in the limit ++(@code{gnus-summary-limit-include-cached}). ++ ++@item / d ++@kindex / d (Summary) ++@findex gnus-summary-limit-exclude-dormant ++Exclude all dormant articles from the limit ++(@code{gnus-summary-limit-exclude-dormant}). ++ ++@item / M ++@kindex / M (Summary) ++@findex gnus-summary-limit-exclude-marks ++Exclude all marked articles (@code{gnus-summary-limit-exclude-marks}). ++ ++@item / T ++@kindex / T (Summary) ++@findex gnus-summary-limit-include-thread ++Include all the articles in the current thread in the limit. ++ ++@item / c ++@kindex / c (Summary) ++@findex gnus-summary-limit-exclude-childless-dormant ++Exclude all dormant articles that have no children from the limit@* ++(@code{gnus-summary-limit-exclude-childless-dormant}). ++ ++@item / C ++@kindex / C (Summary) ++@findex gnus-summary-limit-mark-excluded-as-read ++Mark all excluded unread articles as read ++(@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix, ++also mark excluded ticked and dormant articles as read. ++ ++@item / b ++@kindex / b (Summary) ++@findex gnus-summary-limit-to-bodies ++Limit the summary buffer to articles that have bodies that match a ++certain regexp (@code{gnus-summary-limit-to-bodies}). If given a ++prefix, reverse the limit. This command is quite slow since it ++requires selecting each article to find the matches. ++ ++@item / h ++@kindex / h (Summary) ++@findex gnus-summary-limit-to-headers ++Like the previous command, only limit to headers instead ++(@code{gnus-summary-limit-to-headers}). ++ ++@end table ++ ++ ++The following commands aren't limiting commands, but use the @kbd{/} ++prefix as well. ++ ++@table @kbd ++@item / N ++@kindex / N (Summary) ++@findex gnus-summary-insert-new-articles ++Insert all new articles in the summary buffer. It scans for new emails ++if @var{back-end}@code{-get-new-mail} is non-@code{nil}. ++ ++@item / o ++@kindex / o (Summary) ++@findex gnus-summary-insert-old-articles ++Insert all old articles in the summary buffer. If given a numbered ++prefix, fetch this number of articles. ++ ++@end table ++ ++ ++@node Threading ++@section Threading ++@cindex threading ++@cindex article threading ++ ++Gnus threads articles by default. @dfn{To thread} is to put responses ++to articles directly after the articles they respond to---in a ++hierarchical fashion. ++ ++Threading is done by looking at the @code{References} headers of the ++articles. In a perfect world, this would be enough to build pretty ++trees, but unfortunately, the @code{References} header is often broken ++or simply missing. Weird news propagation exacerbates the problem, ++so one has to employ other heuristics to get pleasing results. A ++plethora of approaches exists, as detailed in horrible detail in ++@ref{Customizing Threading}. ++ ++First, a quick overview of the concepts: ++ ++@table @dfn ++@item root ++The top-most article in a thread; the first article in the thread. ++ ++@item thread ++A tree-like article structure. ++ ++@item sub-thread ++A small(er) section of this tree-like structure. ++ ++@item loose threads ++Threads often lose their roots due to article expiry, or due to the root ++already having been read in a previous session, and not displayed in the ++summary buffer. We then typically have many sub-threads that really ++belong to one thread, but are without connecting roots. These are ++called loose threads. ++ ++@item thread gathering ++An attempt to gather loose threads into bigger threads. ++ ++@item sparse threads ++A thread where the missing articles have been ``guessed'' at, and are ++displayed as empty lines in the summary buffer. ++ ++@end table ++ ++ ++@menu ++* Customizing Threading:: Variables you can change to affect the threading. ++* Thread Commands:: Thread based commands in the summary buffer. ++@end menu ++ ++ ++@node Customizing Threading ++@subsection Customizing Threading ++@cindex customizing threading ++ ++@menu ++* Loose Threads:: How Gnus gathers loose threads into bigger threads. ++* Filling In Threads:: Making the threads displayed look fuller. ++* More Threading:: Even more variables for fiddling with threads. ++* Low-Level Threading:: You thought it was over@dots{} but you were wrong! ++@end menu ++ ++ ++@node Loose Threads ++@subsubsection Loose Threads ++@cindex < ++@cindex > ++@cindex loose threads ++ ++@table @code ++@item gnus-summary-make-false-root ++@vindex gnus-summary-make-false-root ++If non-@code{nil}, Gnus will gather all loose subtrees into one big tree ++and create a dummy root at the top. (Wait a minute. Root at the top? ++Yup.) Loose subtrees occur when the real root has expired, or you've ++read or killed the root in a previous session. ++ ++When there is no real root of a thread, Gnus will have to fudge ++something. This variable says what fudging method Gnus should use. ++There are four possible values: ++ ++@iftex ++@iflatex ++\gnusfigure{The Summary Buffer}{390}{ ++\put(0,0){\epsfig{figure=ps/summary-adopt,width=7.5cm}} ++\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-empty,width=7.5cm}}} ++\put(0,400){\makebox(0,0)[tl]{\epsfig{figure=ps/summary-none,width=7.5cm}}} ++\put(445,400){\makebox(0,0)[tr]{\epsfig{figure=ps/summary-dummy,width=7.5cm}}} ++} ++@end iflatex ++@end iftex ++ ++@cindex adopting articles ++ ++@table @code ++ ++@item adopt ++Gnus will make the first of the orphaned articles the parent. This ++parent will adopt all the other articles. The adopted articles will be ++marked as such by pointy brackets (@samp{<>}) instead of the standard ++square brackets (@samp{[]}). This is the default method. ++ ++@item dummy ++@vindex gnus-summary-dummy-line-format ++@vindex gnus-summary-make-false-root-always ++Gnus will create a dummy summary line that will pretend to be the ++parent. This dummy line does not correspond to any real article, so ++selecting it will just select the first real article after the dummy ++article. @code{gnus-summary-dummy-line-format} is used to specify the ++format of the dummy roots. It accepts only one format spec: @samp{S}, ++which is the subject of the article. @xref{Formatting Variables}. ++If you want all threads to have a dummy root, even the non-gathered ++ones, set @code{gnus-summary-make-false-root-always} to @code{t}. ++ ++@item empty ++Gnus won't actually make any article the parent, but simply leave the ++subject field of all orphans except the first empty. (Actually, it will ++use @code{gnus-summary-same-subject} as the subject (@pxref{Summary ++Buffer Format}).) ++ ++@item none ++Don't make any article parent at all. Just gather the threads and ++display them after one another. ++ ++@item nil ++Don't gather loose threads. ++@end table ++ ++@item gnus-summary-gather-subject-limit ++@vindex gnus-summary-gather-subject-limit ++Loose threads are gathered by comparing subjects of articles. If this ++variable is @code{nil}, Gnus requires an exact match between the ++subjects of the loose threads before gathering them into one big ++super-thread. This might be too strict a requirement, what with the ++presence of stupid newsreaders that chop off long subject lines. If ++you think so, set this variable to, say, 20 to require that only the ++first 20 characters of the subjects have to match. If you set this ++variable to a really low number, you'll find that Gnus will gather ++everything in sight into one thread, which isn't very helpful. ++ ++@cindex fuzzy article gathering ++If you set this variable to the special value @code{fuzzy}, Gnus will ++use a fuzzy string comparison algorithm on the subjects (@pxref{Fuzzy ++Matching}). ++ ++@item gnus-simplify-subject-fuzzy-regexp ++@vindex gnus-simplify-subject-fuzzy-regexp ++This can either be a regular expression or list of regular expressions ++that match strings that will be removed from subjects if fuzzy subject ++simplification is used. ++ ++@item gnus-simplify-ignored-prefixes ++@vindex gnus-simplify-ignored-prefixes ++If you set @code{gnus-summary-gather-subject-limit} to something as low ++as 10, you might consider setting this variable to something sensible: ++ ++@c Written by Michael Ernst ++@lisp ++(setq gnus-simplify-ignored-prefixes ++ (concat ++ "\\`\\[?\\(" ++ (mapconcat ++ 'identity ++ '("looking" ++ "wanted" "followup" "summary\\( of\\)?" ++ "help" "query" "problem" "question" ++ "answer" "reference" "announce" ++ "How can I" "How to" "Comparison of" ++ ;; ... ++ ) ++ "\\|") ++ "\\)\\s *\\(" ++ (mapconcat 'identity ++ '("for" "for reference" "with" "about") ++ "\\|") ++ "\\)?\\]?:?[ \t]*")) ++@end lisp ++ ++All words that match this regexp will be removed before comparing two ++subjects. ++ ++@item gnus-simplify-subject-functions ++@vindex gnus-simplify-subject-functions ++If non-@code{nil}, this variable overrides ++@code{gnus-summary-gather-subject-limit}. This variable should be a ++list of functions to apply to the @code{Subject} string iteratively to ++arrive at the simplified version of the string. ++ ++Useful functions to put in this list include: ++ ++@table @code ++@item gnus-simplify-subject-re ++@findex gnus-simplify-subject-re ++Strip the leading @samp{Re:}. ++ ++@item gnus-simplify-subject-fuzzy ++@findex gnus-simplify-subject-fuzzy ++Simplify fuzzily. ++ ++@item gnus-simplify-whitespace ++@findex gnus-simplify-whitespace ++Remove excessive whitespace. ++ ++@item gnus-simplify-all-whitespace ++@findex gnus-simplify-all-whitespace ++Remove all whitespace. ++@end table ++ ++You may also write your own functions, of course. ++ ++ ++@item gnus-summary-gather-exclude-subject ++@vindex gnus-summary-gather-exclude-subject ++Since loose thread gathering is done on subjects only, that might lead ++to many false hits, especially with certain common subjects like ++@samp{} and @samp{(none)}. To make the situation slightly better, ++you can use the regexp @code{gnus-summary-gather-exclude-subject} to say ++what subjects should be excluded from the gathering process.@* ++The default is @samp{^ *$\\|^(none)$}. ++ ++@item gnus-summary-thread-gathering-function ++@vindex gnus-summary-thread-gathering-function ++Gnus gathers threads by looking at @code{Subject} headers. This means ++that totally unrelated articles may end up in the same ``thread'', which ++is confusing. An alternate approach is to look at all the ++@code{Message-ID}s in all the @code{References} headers to find matches. ++This will ensure that no gathered threads ever include unrelated ++articles, but it also means that people who have posted with broken ++newsreaders won't be gathered properly. The choice is yours---plague or ++cholera: ++ ++@table @code ++@item gnus-gather-threads-by-subject ++@findex gnus-gather-threads-by-subject ++This function is the default gathering function and looks at ++@code{Subject}s exclusively. ++ ++@item gnus-gather-threads-by-references ++@findex gnus-gather-threads-by-references ++This function looks at @code{References} headers exclusively. ++@end table ++ ++If you want to test gathering by @code{References}, you could say ++something like: ++ ++@lisp ++(setq gnus-summary-thread-gathering-function ++ 'gnus-gather-threads-by-references) ++@end lisp ++ ++@end table ++ ++ ++@node Filling In Threads ++@subsubsection Filling In Threads ++ ++@table @code ++@item gnus-fetch-old-headers ++@vindex gnus-fetch-old-headers ++If non-@code{nil}, Gnus will attempt to build old threads by fetching ++more old headers---headers to articles marked as read. If you would ++like to display as few summary lines as possible, but still connect as ++many loose threads as possible, you should set this variable to ++@code{some} or a number. If you set it to a number, no more than that ++number of extra old headers will be fetched. In either case, fetching ++old headers only works if the back end you are using carries overview ++files---this would normally be @code{nntp}, @code{nnspool}, ++@code{nnml}, and @code{nnmaildir}. Also remember that if the root of ++the thread has been expired by the server, there's not much Gnus can ++do about that. ++ ++This variable can also be set to @code{invisible}. This won't have any ++visible effects, but is useful if you use the @kbd{A T} command a lot ++(@pxref{Finding the Parent}). ++ ++The server has to support @acronym{NOV} for any of this to work. ++ ++@cindex Gmane, gnus-fetch-old-headers ++This feature can seriously impact performance it ignores all locally ++cached header entries. Setting it to @code{t} for groups for a server ++that doesn't expire articles (such as news.gmane.org), leads to very ++slow summary generation. ++ ++@item gnus-fetch-old-ephemeral-headers ++@vindex gnus-fetch-old-ephemeral-headers ++Same as @code{gnus-fetch-old-headers}, but only used for ephemeral ++newsgroups. ++ ++@item gnus-build-sparse-threads ++@vindex gnus-build-sparse-threads ++Fetching old headers can be slow. A low-rent similar effect can be ++gotten by setting this variable to @code{some}. Gnus will then look at ++the complete @code{References} headers of all articles and try to string ++together articles that belong in the same thread. This will leave ++@dfn{gaps} in the threading display where Gnus guesses that an article ++is missing from the thread. (These gaps appear like normal summary ++lines. If you select a gap, Gnus will try to fetch the article in ++question.) If this variable is @code{t}, Gnus will display all these ++``gaps'' without regard for whether they are useful for completing the ++thread or not. Finally, if this variable is @code{more}, Gnus won't cut ++off sparse leaf nodes that don't lead anywhere. This variable is ++@code{nil} by default. ++ ++@item gnus-read-all-available-headers ++@vindex gnus-read-all-available-headers ++This is a rather obscure variable that few will find useful. It's ++intended for those non-news newsgroups where the back end has to fetch ++quite a lot to present the summary buffer, and where it's impossible to ++go back to parents of articles. This is mostly the case in the ++web-based groups, like the @code{nnultimate} groups. ++ ++If you don't use those, then it's safe to leave this as the default ++@code{nil}. If you want to use this variable, it should be a regexp ++that matches the group name, or @code{t} for all groups. ++ ++@end table ++ ++ ++@node More Threading ++@subsubsection More Threading ++ ++@table @code ++@item gnus-show-threads ++@vindex gnus-show-threads ++If this variable is @code{nil}, no threading will be done, and all of ++the rest of the variables here will have no effect. Turning threading ++off will speed group selection up a bit, but it is sure to make reading ++slower and more awkward. ++ ++@item gnus-thread-hide-subtree ++@vindex gnus-thread-hide-subtree ++If non-@code{nil}, all threads will be hidden when the summary buffer is ++generated. ++ ++This can also be a predicate specifier (@pxref{Predicate Specifiers}). ++Available predicates are @code{gnus-article-unread-p} and ++@code{gnus-article-unseen-p}. ++ ++Here's an example: ++ ++@lisp ++(setq gnus-thread-hide-subtree ++ '(or gnus-article-unread-p ++ gnus-article-unseen-p)) ++@end lisp ++ ++(It's a pretty nonsensical example, since all unseen articles are also ++unread, but you get my drift.) ++ ++ ++@item gnus-thread-expunge-below ++@vindex gnus-thread-expunge-below ++All threads that have a total score (as defined by ++@code{gnus-thread-score-function}) less than this number will be ++expunged. This variable is @code{nil} by default, which means that no ++threads are expunged. ++ ++@item gnus-thread-hide-killed ++@vindex gnus-thread-hide-killed ++if you kill a thread and this variable is non-@code{nil}, the subtree ++will be hidden. ++ ++@item gnus-thread-ignore-subject ++@vindex gnus-thread-ignore-subject ++Sometimes somebody changes the subject in the middle of a thread. If ++this variable is non-@code{nil}, which is the default, the subject ++change is ignored. If it is @code{nil}, a change in the subject will ++result in a new thread. ++ ++@item gnus-thread-indent-level ++@vindex gnus-thread-indent-level ++This is a number that says how much each sub-thread should be indented. ++The default is 4. ++ ++@item gnus-sort-gathered-threads-function ++@vindex gnus-sort-gathered-threads-function ++Sometimes, particularly with mailing lists, the order in which mails ++arrive locally is not necessarily the same as the order in which they ++arrived on the mailing list. Consequently, when sorting sub-threads ++using the default @code{gnus-thread-sort-by-number}, responses can end ++up appearing before the article to which they are responding to. ++Setting this variable to an alternate value ++(e.g. @code{gnus-thread-sort-by-date}), in a group's parameters or in an ++appropriate hook (e.g. @code{gnus-summary-generate-hook}) can produce a ++more logical sub-thread ordering in such instances. ++ ++@end table ++ ++ ++@node Low-Level Threading ++@subsubsection Low-Level Threading ++ ++@table @code ++ ++@item gnus-parse-headers-hook ++@vindex gnus-parse-headers-hook ++Hook run before parsing any headers. ++ ++@item gnus-alter-header-function ++@vindex gnus-alter-header-function ++If non-@code{nil}, this function will be called to allow alteration of ++article header structures. The function is called with one parameter, ++the article header vector, which it may alter in any way. For instance, ++if you have a mail-to-news gateway which alters the @code{Message-ID}s ++in systematic ways (by adding prefixes and such), you can use this ++variable to un-scramble the @code{Message-ID}s so that they are more ++meaningful. Here's one example: ++ ++@lisp ++(setq gnus-alter-header-function 'my-alter-message-id) ++ ++(defun my-alter-message-id (header) ++ (let ((id (mail-header-id header))) ++ (when (string-match ++ "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id) ++ (mail-header-set-id ++ (concat (match-string 1 id) "@@" (match-string 2 id)) ++ header)))) ++@end lisp ++ ++@end table ++ ++ ++@node Thread Commands ++@subsection Thread Commands ++@cindex thread commands ++ ++@table @kbd ++ ++@item T k ++@itemx C-M-k ++@kindex T k (Summary) ++@kindex C-M-k (Summary) ++@findex gnus-summary-kill-thread ++Mark all articles in the current (sub-)thread as read ++(@code{gnus-summary-kill-thread}). If the prefix argument is positive, ++remove all marks instead. If the prefix argument is negative, tick ++articles instead. ++ ++@item T l ++@itemx C-M-l ++@kindex T l (Summary) ++@kindex C-M-l (Summary) ++@findex gnus-summary-lower-thread ++Lower the score of the current (sub-)thread ++(@code{gnus-summary-lower-thread}). ++ ++@item T i ++@kindex T i (Summary) ++@findex gnus-summary-raise-thread ++Increase the score of the current (sub-)thread ++(@code{gnus-summary-raise-thread}). ++ ++@item T # ++@kindex T # (Summary) ++@findex gnus-uu-mark-thread ++Set the process mark on the current (sub-)thread ++(@code{gnus-uu-mark-thread}). ++ ++@item T M-# ++@kindex T M-# (Summary) ++@findex gnus-uu-unmark-thread ++Remove the process mark from the current (sub-)thread ++(@code{gnus-uu-unmark-thread}). ++ ++@item T T ++@kindex T T (Summary) ++@findex gnus-summary-toggle-threads ++Toggle threading (@code{gnus-summary-toggle-threads}). ++ ++@item T s ++@kindex T s (Summary) ++@findex gnus-summary-show-thread ++Expose the (sub-)thread hidden under the current article, if any@* ++(@code{gnus-summary-show-thread}). ++ ++@item T h ++@kindex T h (Summary) ++@findex gnus-summary-hide-thread ++Hide the current (sub-)thread (@code{gnus-summary-hide-thread}). ++ ++@item T S ++@kindex T S (Summary) ++@findex gnus-summary-show-all-threads ++Expose all hidden threads (@code{gnus-summary-show-all-threads}). ++ ++@item T H ++@kindex T H (Summary) ++@findex gnus-summary-hide-all-threads ++Hide all threads (@code{gnus-summary-hide-all-threads}). ++ ++@item T t ++@kindex T t (Summary) ++@findex gnus-summary-rethread-current ++Re-thread the current article's thread ++(@code{gnus-summary-rethread-current}). This works even when the ++summary buffer is otherwise unthreaded. ++ ++@item T ^ ++@kindex T ^ (Summary) ++@findex gnus-summary-reparent-thread ++Make the current article the child of the marked (or previous) article ++(@code{gnus-summary-reparent-thread}). ++ ++@item T M-^ ++@kindex T M-^ (Summary) ++@findex gnus-summary-reparent-children ++Make the current article the parent of the marked articles ++(@code{gnus-summary-reparent-children}). ++ ++@end table ++ ++The following commands are thread movement commands. They all ++understand the numeric prefix. ++ ++@table @kbd ++ ++@item T n ++@kindex T n (Summary) ++@itemx C-M-f ++@kindex C-M-n (Summary) ++@itemx M-down ++@kindex M-down (Summary) ++@findex gnus-summary-next-thread ++Go to the next thread (@code{gnus-summary-next-thread}). ++ ++@item T p ++@kindex T p (Summary) ++@itemx C-M-b ++@kindex C-M-p (Summary) ++@itemx M-up ++@kindex M-up (Summary) ++@findex gnus-summary-prev-thread ++Go to the previous thread (@code{gnus-summary-prev-thread}). ++ ++@item T d ++@kindex T d (Summary) ++@findex gnus-summary-down-thread ++Descend the thread (@code{gnus-summary-down-thread}). ++ ++@item T u ++@kindex T u (Summary) ++@findex gnus-summary-up-thread ++Ascend the thread (@code{gnus-summary-up-thread}). ++ ++@item T o ++@kindex T o (Summary) ++@findex gnus-summary-top-thread ++Go to the top of the thread (@code{gnus-summary-top-thread}). ++@end table ++ ++@vindex gnus-thread-operation-ignore-subject ++If you ignore subject while threading, you'll naturally end up with ++threads that have several different subjects in them. If you then issue ++a command like @kbd{T k} (@code{gnus-summary-kill-thread}) you might not ++wish to kill the entire thread, but just those parts of the thread that ++have the same subject as the current article. If you like this idea, ++you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it ++is non-@code{nil} (which it is by default), subjects will be ignored ++when doing thread commands. If this variable is @code{nil}, articles in ++the same thread with different subjects will not be included in the ++operation in question. If this variable is @code{fuzzy}, only articles ++that have subjects fuzzily equal will be included (@pxref{Fuzzy ++Matching}). ++ ++ ++@node Sorting the Summary Buffer ++@section Sorting the Summary Buffer ++ ++@findex gnus-thread-sort-by-total-score ++@findex gnus-thread-sort-by-date ++@findex gnus-thread-sort-by-score ++@findex gnus-thread-sort-by-subject ++@findex gnus-thread-sort-by-author ++@findex gnus-thread-sort-by-recipient ++@findex gnus-thread-sort-by-number ++@findex gnus-thread-sort-by-random ++@vindex gnus-thread-sort-functions ++@findex gnus-thread-sort-by-most-recent-number ++@findex gnus-thread-sort-by-most-recent-date ++If you are using a threaded summary display, you can sort the threads by ++setting @code{gnus-thread-sort-functions}, which can be either a single ++function, a list of functions, or a list containing functions and ++@code{(not some-function)} elements. ++ ++By default, sorting is done on article numbers. Ready-made sorting ++predicate functions include @code{gnus-thread-sort-by-number}, ++@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-recipient}, ++@code{gnus-thread-sort-by-subject}, ++@code{gnus-thread-sort-by-date}, ++@code{gnus-thread-sort-by-score}, ++@code{gnus-thread-sort-by-most-recent-number}, ++@code{gnus-thread-sort-by-most-recent-date}, ++@code{gnus-thread-sort-by-random} and ++@code{gnus-thread-sort-by-total-score}. ++ ++Each function takes two threads and returns non-@code{nil} if the first ++thread should be sorted before the other. Note that sorting really is ++normally done by looking only at the roots of each thread. ++ ++If you use more than one function, the primary sort key should be the ++last function in the list. You should probably always include ++@code{gnus-thread-sort-by-number} in the list of sorting ++functions---preferably first. This will ensure that threads that are ++equal with respect to the other sort criteria will be displayed in ++ascending article order. ++ ++If you would like to sort by reverse score, then by subject, and finally ++by number, you could do something like: ++ ++@lisp ++(setq gnus-thread-sort-functions ++ '(gnus-thread-sort-by-number ++ gnus-thread-sort-by-subject ++ (not gnus-thread-sort-by-total-score))) ++@end lisp ++ ++The threads that have highest score will be displayed first in the ++summary buffer. When threads have the same score, they will be sorted ++alphabetically. The threads that have the same score and the same ++subject will be sorted by number, which is (normally) the sequence in ++which the articles arrived. ++ ++If you want to sort by score and then reverse arrival order, you could ++say something like: ++ ++@lisp ++(setq gnus-thread-sort-functions ++ '((not gnus-thread-sort-by-number) ++ gnus-thread-sort-by-score)) ++@end lisp ++ ++@vindex gnus-thread-score-function ++The function in the @code{gnus-thread-score-function} variable (default ++@code{+}) is used for calculating the total score of a thread. Useful ++functions might be @code{max}, @code{min}, or squared means, or whatever ++tickles your fancy. ++ ++@findex gnus-article-sort-functions ++@findex gnus-article-sort-by-date ++@findex gnus-article-sort-by-most-recent-date ++@findex gnus-article-sort-by-score ++@findex gnus-article-sort-by-subject ++@findex gnus-article-sort-by-author ++@findex gnus-article-sort-by-random ++@findex gnus-article-sort-by-number ++@findex gnus-article-sort-by-most-recent-number ++If you are using an unthreaded display for some strange reason or ++other, you have to fiddle with the @code{gnus-article-sort-functions} ++variable. It is very similar to the ++@code{gnus-thread-sort-functions}, except that it uses slightly ++different functions for article comparison. Available sorting ++predicate functions are @code{gnus-article-sort-by-number}, ++@code{gnus-article-sort-by-author}, ++@code{gnus-article-sort-by-subject}, @code{gnus-article-sort-by-date}, ++@code{gnus-article-sort-by-random}, and ++@code{gnus-article-sort-by-score}. ++ ++If you want to sort an unthreaded summary display by subject, you could ++say something like: ++ ++@lisp ++(setq gnus-article-sort-functions ++ '(gnus-article-sort-by-number ++ gnus-article-sort-by-subject)) ++@end lisp ++ ++You can define group specific sorting via @code{gnus-parameters}, ++@xref{Group Parameters}. ++ ++ ++@node Asynchronous Fetching ++@section Asynchronous Article Fetching ++@cindex asynchronous article fetching ++@cindex article pre-fetch ++@cindex pre-fetch ++ ++If you read your news from an @acronym{NNTP} server that's far away, the ++network latencies may make reading articles a chore. You have to wait ++for a while after pressing @kbd{n} to go to the next article before the ++article appears. Why can't Gnus just go ahead and fetch the article ++while you are reading the previous one? Why not, indeed. ++ ++First, some caveats. There are some pitfalls to using asynchronous ++article fetching, especially the way Gnus does it. ++ ++Let's say you are reading article 1, which is short, and article 2 is ++quite long, and you are not interested in reading that. Gnus does not ++know this, so it goes ahead and fetches article 2. You decide to read ++article 3, but since Gnus is in the process of fetching article 2, the ++connection is blocked. ++ ++To avoid these situations, Gnus will open two (count 'em two) ++connections to the server. Some people may think this isn't a very nice ++thing to do, but I don't see any real alternatives. Setting up that ++extra connection takes some time, so Gnus startup will be slower. ++ ++Gnus will fetch more articles than you will read. This will mean that ++the link between your machine and the @acronym{NNTP} server will become more ++loaded than if you didn't use article pre-fetch. The server itself will ++also become more loaded---both with the extra article requests, and the ++extra connection. ++ ++Ok, so now you know that you shouldn't really use this thing@dots{} unless ++you really want to. ++ ++@vindex gnus-asynchronous ++Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should ++happen automatically. ++ ++@vindex gnus-use-article-prefetch ++You can control how many articles are to be pre-fetched by setting ++@code{gnus-use-article-prefetch}. This is 30 by default, which means ++that when you read an article in the group, the back end will pre-fetch ++the next 30 articles. If this variable is @code{t}, the back end will ++pre-fetch all the articles it can without bound. If it is ++@code{nil}, no pre-fetching will be done. ++ ++@vindex gnus-async-prefetch-article-p ++@findex gnus-async-unread-p ++There are probably some articles that you don't want to pre-fetch---read ++articles, for instance. The @code{gnus-async-prefetch-article-p} ++variable controls whether an article is to be pre-fetched. This ++function should return non-@code{nil} when the article in question is ++to be pre-fetched. The default is @code{gnus-async-unread-p}, which ++returns @code{nil} on read articles. The function is called with an ++article data structure as the only parameter. ++ ++If, for instance, you wish to pre-fetch only unread articles shorter ++than 100 lines, you could say something like: ++ ++@lisp ++(defun my-async-short-unread-p (data) ++ "Return non-nil for short, unread articles." ++ (and (gnus-data-unread-p data) ++ (< (mail-header-lines (gnus-data-header data)) ++ 100))) ++ ++(setq gnus-async-prefetch-article-p 'my-async-short-unread-p) ++@end lisp ++ ++These functions will be called many, many times, so they should ++preferably be short and sweet to avoid slowing down Gnus too much. ++It's probably a good idea to byte-compile things like this. ++ ++@vindex gnus-prefetched-article-deletion-strategy ++Articles have to be removed from the asynch buffer sooner or later. The ++@code{gnus-prefetched-article-deletion-strategy} says when to remove ++articles. This is a list that may contain the following elements: ++ ++@table @code ++@item read ++Remove articles when they are read. ++ ++@item exit ++Remove articles when exiting the group. ++@end table ++ ++The default value is @code{(read exit)}. ++ ++@c @vindex gnus-use-header-prefetch ++@c If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles ++@c from the next group. ++ ++ ++@node Article Caching ++@section Article Caching ++@cindex article caching ++@cindex caching ++ ++If you have an @emph{extremely} slow @acronym{NNTP} connection, you may ++consider turning article caching on. Each article will then be stored ++locally under your home directory. As you may surmise, this could ++potentially use @emph{huge} amounts of disk space, as well as eat up all ++your inodes so fast it will make your head swim. In vodka. ++ ++Used carefully, though, it could be just an easier way to save articles. ++ ++@vindex gnus-use-long-file-name ++@vindex gnus-cache-directory ++@vindex gnus-use-cache ++To turn caching on, set @code{gnus-use-cache} to @code{t}. By default, ++all articles ticked or marked as dormant will then be copied ++over to your local cache (@code{gnus-cache-directory}). Whether this ++cache is flat or hierarchical is controlled by the ++@code{gnus-use-long-file-name} variable, as usual. ++ ++When re-selecting a ticked or dormant article, it will be fetched from the ++cache instead of from the server. As articles in your cache will never ++expire, this might serve as a method of saving articles while still ++keeping them where they belong. Just mark all articles you want to save ++as dormant, and don't worry. ++ ++When an article is marked as read, is it removed from the cache. ++ ++@vindex gnus-cache-remove-articles ++@vindex gnus-cache-enter-articles ++The entering/removal of articles from the cache is controlled by the ++@code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles} ++variables. Both are lists of symbols. The first is @code{(ticked ++dormant)} by default, meaning that ticked and dormant articles will be ++put in the cache. The latter is @code{(read)} by default, meaning that ++articles marked as read are removed from the cache. Possibly ++symbols in these two lists are @code{ticked}, @code{dormant}, ++@code{unread} and @code{read}. ++ ++@findex gnus-jog-cache ++So where does the massive article-fetching and storing come into the ++picture? The @code{gnus-jog-cache} command will go through all ++subscribed newsgroups, request all unread articles, score them, and ++store them in the cache. You should only ever, ever ever ever, use this ++command if 1) your connection to the @acronym{NNTP} server is really, really, ++really slow and 2) you have a really, really, really huge disk. ++Seriously. One way to cut down on the number of articles downloaded is ++to score unwanted articles down and have them marked as read. They will ++not then be downloaded by this command. ++ ++@vindex gnus-uncacheable-groups ++@vindex gnus-cacheable-groups ++It is likely that you do not want caching on all groups. For instance, ++if your @code{nnml} mail is located under your home directory, it makes no ++sense to cache it somewhere else under your home directory. Unless you ++feel that it's neat to use twice as much space. ++ ++To limit the caching, you could set @code{gnus-cacheable-groups} to a ++regexp of groups to cache, @samp{^nntp} for instance, or set the ++@code{gnus-uncacheable-groups} regexp to @samp{^nnml}, for instance. ++Both variables are @code{nil} by default. If a group matches both ++variables, the group is not cached. ++ ++@findex gnus-cache-generate-nov-databases ++@findex gnus-cache-generate-active ++@vindex gnus-cache-active-file ++The cache stores information on what articles it contains in its active ++file (@code{gnus-cache-active-file}). If this file (or any other parts ++of the cache) becomes all messed up for some reason or other, Gnus ++offers two functions that will try to set things right. @kbd{M-x ++gnus-cache-generate-nov-databases} will (re)build all the @acronym{NOV} ++files, and @kbd{gnus-cache-generate-active} will (re)generate the active ++file. ++ ++@findex gnus-cache-move-cache ++@code{gnus-cache-move-cache} will move your whole ++@code{gnus-cache-directory} to some other location. You get asked to ++where, isn't that cool? ++ ++@node Persistent Articles ++@section Persistent Articles ++@cindex persistent articles ++ ++Closely related to article caching, we have @dfn{persistent articles}. ++In fact, it's just a different way of looking at caching, and much more ++useful in my opinion. ++ ++Say you're reading a newsgroup, and you happen on to some valuable gem ++that you want to keep and treasure forever. You'd normally just save it ++(using one of the many saving commands) in some file. The problem with ++that is that it's just, well, yucky. Ideally you'd prefer just having ++the article remain in the group where you found it forever; untouched by ++the expiry going on at the news server. ++ ++This is what a @dfn{persistent article} is---an article that just won't ++be deleted. It's implemented using the normal cache functions, but ++you use two explicit commands for managing persistent articles: ++ ++@table @kbd ++ ++@item * ++@kindex * (Summary) ++@findex gnus-cache-enter-article ++Make the current article persistent (@code{gnus-cache-enter-article}). ++ ++@item M-* ++@kindex M-* (Summary) ++@findex gnus-cache-remove-article ++Remove the current article from the persistent articles ++(@code{gnus-cache-remove-article}). This will normally delete the ++article. ++@end table ++ ++Both these commands understand the process/prefix convention. ++ ++To avoid having all ticked articles (and stuff) entered into the cache, ++you should set @code{gnus-use-cache} to @code{passive} if you're just ++interested in persistent articles: ++ ++@lisp ++(setq gnus-use-cache 'passive) ++@end lisp ++ ++@node Sticky Articles ++@section Sticky Articles ++@cindex sticky articles ++ ++When you select an article the current article buffer will be reused ++according to the value of the variable ++@code{gnus-single-article-buffer}. If its value is non-@code{nil} (the ++default) all articles reuse the same article buffer. Else each group ++has its own article buffer. ++ ++This implies that it's not possible to have more than one article buffer ++in a group at a time. But sometimes you might want to display all the ++latest emails from your mother, your father, your aunt, your uncle and ++your 17 cousins to coordinate the next christmas party. ++ ++That's where sticky articles come in handy. A sticky article buffer ++basically is a normal article buffer, but it won't be reused when you ++select another article. You can make an article sticky with: ++ ++@table @kbd ++@item A S ++@kindex A S (Summary) ++@findex gnus-sticky-article ++Make the current article sticky. If a prefix arg is given, ask for a ++name for this sticky article buffer. ++@end table ++ ++To close a sticky article buffer you can use these commands: ++ ++@table @kbd ++@item q ++@kindex q (Article) ++@findex bury-buffer ++Puts this sticky article buffer at the end of the list of all buffers. ++ ++@item k ++@kindex k (Article) ++@findex gnus-kill-sticky-article-buffer ++Kills this sticky article buffer. ++@end table ++ ++To kill all sticky article buffers you can use: ++ ++@defun gnus-kill-sticky-article-buffers ARG ++Kill all sticky article buffers. ++If a prefix ARG is given, ask for confirmation. ++@end defun ++ ++@node Article Backlog ++@section Article Backlog ++@cindex backlog ++@cindex article backlog ++ ++If you have a slow connection, but the idea of using caching seems ++unappealing to you (and it is, really), you can help the situation some ++by switching on the @dfn{backlog}. This is where Gnus will buffer ++already read articles so that it doesn't have to re-fetch articles ++you've already read. This only helps if you are in the habit of ++re-selecting articles you've recently read, of course. If you never do ++that, turning the backlog on will slow Gnus down a little bit, and ++increase memory usage some. ++ ++@vindex gnus-keep-backlog ++If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store ++at most @var{n} old articles in a buffer for later re-fetching. If this ++variable is non-@code{nil} and is not a number, Gnus will store ++@emph{all} read articles, which means that your Emacs will grow without ++bound before exploding and taking your machine down with you. I put ++that in there just to keep y'all on your toes. ++ ++The default value is 20. ++ ++ ++@node Saving Articles ++@section Saving Articles ++@cindex saving articles ++ ++Gnus can save articles in a number of ways. Below is the documentation ++for saving articles in a fairly straight-forward fashion (i.e., little ++processing of the article is done before it is saved). For a different ++approach (uudecoding, unsharing) you should use @code{gnus-uu} ++(@pxref{Decoding Articles}). ++ ++For the commands listed here, the target is a file. If you want to ++save to a group, see the @kbd{B c} (@code{gnus-summary-copy-article}) ++command (@pxref{Mail Group Commands}). ++ ++@vindex gnus-save-all-headers ++If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete ++unwanted headers before saving the article. ++ ++@vindex gnus-saved-headers ++If the preceding variable is @code{nil}, all headers that match the ++@code{gnus-saved-headers} regexp will be kept, while the rest will be ++deleted before saving. ++ ++@table @kbd ++ ++@item O o ++@itemx o ++@kindex O o (Summary) ++@kindex o (Summary) ++@findex gnus-summary-save-article ++@c @icon{gnus-summary-save-article} ++Save the current article using the default article saver ++(@code{gnus-summary-save-article}). ++ ++@item O m ++@kindex O m (Summary) ++@findex gnus-summary-save-article-mail ++Save the current article in a Unix mail box (mbox) file ++(@code{gnus-summary-save-article-mail}). ++ ++@item O r ++@kindex O r (Summary) ++@findex gnus-summary-save-article-rmail ++Save the current article in Rmail format ++(@code{gnus-summary-save-article-rmail}). This is mbox since Emacs 23, ++Babyl in older versions. ++ ++@item O f ++@kindex O f (Summary) ++@findex gnus-summary-save-article-file ++@c @icon{gnus-summary-save-article-file} ++Save the current article in plain file format ++(@code{gnus-summary-save-article-file}). ++ ++@item O F ++@kindex O F (Summary) ++@findex gnus-summary-write-article-file ++Write the current article in plain file format, overwriting any previous ++file contents (@code{gnus-summary-write-article-file}). ++ ++@item O b ++@kindex O b (Summary) ++@findex gnus-summary-save-article-body-file ++Save the current article body in plain file format ++(@code{gnus-summary-save-article-body-file}). ++ ++@item O h ++@kindex O h (Summary) ++@findex gnus-summary-save-article-folder ++Save the current article in mh folder format ++(@code{gnus-summary-save-article-folder}). ++ ++@item O v ++@kindex O v (Summary) ++@findex gnus-summary-save-article-vm ++Save the current article in a VM folder ++(@code{gnus-summary-save-article-vm}). ++ ++@item O p ++@itemx | ++@kindex O p (Summary) ++@kindex | (Summary) ++@findex gnus-summary-pipe-output ++@vindex gnus-summary-pipe-output-default-command ++Save the current article in a pipe. Uhm, like, what I mean is---Pipe ++the current article to a process (@code{gnus-summary-pipe-output}). ++If given a symbolic prefix (@pxref{Symbolic Prefixes}), include the ++complete headers in the piped output. The symbolic prefix @code{r} is ++special; it lets this command pipe a raw article including all headers. ++The @code{gnus-summary-pipe-output-default-command} variable can be set ++to a string containing the default command and options (default ++@code{nil}). ++ ++@item O P ++@kindex O P (Summary) ++@findex gnus-summary-muttprint ++@vindex gnus-summary-muttprint-program ++Save the current article into muttprint. That is, print it using the ++external program @uref{http://muttprint.sourceforge.net/, ++Muttprint}. The program name and options to use is controlled by the ++variable @code{gnus-summary-muttprint-program}. ++(@code{gnus-summary-muttprint}). ++ ++@end table ++ ++@vindex gnus-prompt-before-saving ++All these commands use the process/prefix convention ++(@pxref{Process/Prefix}). If you save bunches of articles using these ++functions, you might get tired of being prompted for files to save each ++and every article in. The prompting action is controlled by ++the @code{gnus-prompt-before-saving} variable, which is @code{always} by ++default, giving you that excessive prompting action you know and ++loathe. If you set this variable to @code{t} instead, you'll be prompted ++just once for each series of articles you save. If you like to really ++have Gnus do all your thinking for you, you can even set this variable ++to @code{nil}, which means that you will never be prompted for files to ++save articles in. Gnus will simply save all the articles in the default ++files. ++ ++ ++@vindex gnus-default-article-saver ++You can customize the @code{gnus-default-article-saver} variable to make ++Gnus do what you want it to. You can use any of the eight ready-made ++functions below, or you can create your own. ++ ++@table @code ++ ++@item gnus-summary-save-in-rmail ++@findex gnus-summary-save-in-rmail ++@vindex gnus-rmail-save-name ++@findex gnus-plain-save-name ++This is the default format, that used by the Rmail package. Since Emacs ++23, Rmail uses standard mbox format. Before this, it used the ++@dfn{Babyl} format. Accordingly, this command writes mbox format since ++Emacs 23, unless appending to an existing Babyl file. In older versions ++of Emacs, it always uses Babyl format. Uses the function in the ++@code{gnus-rmail-save-name} variable to get a file name to save the ++article in. The default is @code{gnus-plain-save-name}. ++ ++@item gnus-summary-save-in-mail ++@findex gnus-summary-save-in-mail ++@vindex gnus-mail-save-name ++Save in a Unix mail (mbox) file. Uses the function in the ++@code{gnus-mail-save-name} variable to get a file name to save the ++article in. The default is @code{gnus-plain-save-name}. ++ ++@item gnus-summary-save-in-file ++@findex gnus-summary-save-in-file ++@vindex gnus-file-save-name ++@findex gnus-numeric-save-name ++Append the article straight to an ordinary file. Uses the function in ++the @code{gnus-file-save-name} variable to get a file name to save the ++article in. The default is @code{gnus-numeric-save-name}. ++ ++@item gnus-summary-write-to-file ++@findex gnus-summary-write-to-file ++Write the article straight to an ordinary file. The file is ++overwritten if it exists. Uses the function in the ++@code{gnus-file-save-name} variable to get a file name to save the ++article in. The default is @code{gnus-numeric-save-name}. ++ ++@item gnus-summary-save-body-in-file ++@findex gnus-summary-save-body-in-file ++Append the article body to an ordinary file. Uses the function in the ++@code{gnus-file-save-name} variable to get a file name to save the ++article in. The default is @code{gnus-numeric-save-name}. ++ ++@item gnus-summary-write-body-to-file ++@findex gnus-summary-write-body-to-file ++Write the article body straight to an ordinary file. The file is ++overwritten if it exists. Uses the function in the ++@code{gnus-file-save-name} variable to get a file name to save the ++article in. The default is @code{gnus-numeric-save-name}. ++ ++@item gnus-summary-save-in-folder ++@findex gnus-summary-save-in-folder ++@findex gnus-folder-save-name ++@findex gnus-Folder-save-name ++@vindex gnus-folder-save-name ++@cindex rcvstore ++@cindex MH folders ++Save the article to an MH folder using @code{rcvstore} from the MH ++library. Uses the function in the @code{gnus-folder-save-name} variable ++to get a file name to save the article in. The default is ++@code{gnus-folder-save-name}, but you can also use ++@code{gnus-Folder-save-name}, which creates capitalized names. ++ ++@item gnus-summary-save-in-vm ++@findex gnus-summary-save-in-vm ++Save the article in a VM folder. You have to have the VM mail ++reader to use this setting. ++ ++@item gnus-summary-save-in-pipe ++@findex gnus-summary-save-in-pipe ++Pipe the article to a shell command. This function takes optional two ++arguments COMMAND and RAW. Valid values for COMMAND include: ++ ++@itemize @bullet ++@item a string@* ++The executable command name and possibly arguments. ++@item @code{nil}@* ++You will be prompted for the command in the minibuffer. ++@item the symbol @code{default}@* ++It will be replaced with the command which the variable ++@code{gnus-summary-pipe-output-default-command} holds or the command ++last used for saving. ++@end itemize ++ ++Non-@code{nil} value for RAW overrides @code{:decode} and ++@code{:headers} properties (see below) and the raw article including all ++headers will be piped. ++@end table ++ ++The symbol of each function may have the following properties: ++ ++@table @code ++@item :decode ++The value non-@code{nil} means save decoded articles. This is ++meaningful only with @code{gnus-summary-save-in-file}, ++@code{gnus-summary-save-body-in-file}, ++@code{gnus-summary-write-to-file}, ++@code{gnus-summary-write-body-to-file}, and ++@code{gnus-summary-save-in-pipe}. ++ ++@item :function ++The value specifies an alternative function which appends, not ++overwrites, articles to a file. This implies that when saving many ++articles at a time, @code{gnus-prompt-before-saving} is bound to ++@code{t} and all articles are saved in a single file. This is ++meaningful only with @code{gnus-summary-write-to-file} and ++@code{gnus-summary-write-body-to-file}. ++ ++@item :headers ++The value specifies the symbol of a variable of which the value ++specifies headers to be saved. If it is omitted, ++@code{gnus-save-all-headers} and @code{gnus-saved-headers} control what ++headers should be saved. ++@end table ++ ++@vindex gnus-article-save-directory ++All of these functions, except for the last one, will save the article ++in the @code{gnus-article-save-directory}, which is initialized from the ++@env{SAVEDIR} environment variable. This is @file{~/News/} by ++default. ++ ++As you can see above, the functions use different functions to find a ++suitable name of a file to save the article in. Below is a list of ++available functions that generate names: ++ ++@table @code ++ ++@item gnus-Numeric-save-name ++@findex gnus-Numeric-save-name ++File names like @file{~/News/Alt.andrea-dworkin/45}. ++ ++@item gnus-numeric-save-name ++@findex gnus-numeric-save-name ++File names like @file{~/News/alt.andrea-dworkin/45}. ++ ++@item gnus-Plain-save-name ++@findex gnus-Plain-save-name ++File names like @file{~/News/Alt.andrea-dworkin}. ++ ++@item gnus-plain-save-name ++@findex gnus-plain-save-name ++File names like @file{~/News/alt.andrea-dworkin}. ++ ++@item gnus-sender-save-name ++@findex gnus-sender-save-name ++File names like @file{~/News/larsi}. ++@end table ++ ++@vindex gnus-split-methods ++You can have Gnus suggest where to save articles by plonking a regexp into ++the @code{gnus-split-methods} alist. For instance, if you would like to ++save articles related to Gnus in the file @file{gnus-stuff}, and articles ++related to VM in @file{vm-stuff}, you could set this variable to something ++like: ++ ++@lisp ++(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff") ++ ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff") ++ (my-choosing-function "../other-dir/my-stuff") ++ ((equal gnus-newsgroup-name "mail.misc") "mail-stuff")) ++@end lisp ++ ++We see that this is a list where each element is a list that has two ++elements---the @dfn{match} and the @dfn{file}. The match can either be ++a string (in which case it is used as a regexp to match on the article ++head); it can be a symbol (which will be called as a function with the ++group name as a parameter); or it can be a list (which will be ++@code{eval}ed). If any of these actions have a non-@code{nil} result, ++the @dfn{file} will be used as a default prompt. In addition, the ++result of the operation itself will be used if the function or form ++called returns a string or a list of strings. ++ ++You basically end up with a list of file names that might be used when ++saving the current article. (All ``matches'' will be used.) You will ++then be prompted for what you really want to use as a name, with file ++name completion over the results from applying this variable. ++ ++This variable is @code{((gnus-article-archive-name))} by default, which ++means that Gnus will look at the articles it saves for an ++@code{Archive-name} line and use that as a suggestion for the file ++name. ++ ++Here's an example function to clean up file names somewhat. If you have ++lots of mail groups called things like ++@samp{nnml:mail.whatever}, you may want to chop off the beginning of ++these group names before creating the file name to save to. The ++following will do just that: ++ ++@lisp ++(defun my-save-name (group) ++ (when (string-match "^nnml:mail." group) ++ (substring group (match-end 0)))) ++ ++(setq gnus-split-methods ++ '((gnus-article-archive-name) ++ (my-save-name))) ++@end lisp ++ ++ ++@vindex gnus-use-long-file-name ++Finally, you have the @code{gnus-use-long-file-name} variable. If it is ++@code{nil}, all the preceding functions will replace all periods ++(@samp{.}) in the group names with slashes (@samp{/})---which means that ++the functions will generate hierarchies of directories instead of having ++all the files in the top level directory ++(@file{~/News/alt/andrea-dworkin} instead of ++@file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default ++on most systems. However, for historical reasons, this is @code{nil} on ++Xenix and usg-unix-v machines by default. ++ ++This function also affects kill and score file names. If this variable ++is a list, and the list contains the element @code{not-score}, long file ++names will not be used for score files, if it contains the element ++@code{not-save}, long file names will not be used for saving, and if it ++contains the element @code{not-kill}, long file names will not be used ++for kill files. ++ ++If you'd like to save articles in a hierarchy that looks something like ++a spool, you could ++ ++@lisp ++(setq gnus-use-long-file-name '(not-save)) ; @r{to get a hierarchy} ++(setq gnus-default-article-saver ++ 'gnus-summary-save-in-file) ; @r{no encoding} ++@end lisp ++ ++Then just save with @kbd{o}. You'd then read this hierarchy with ++ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and ++the top level directory as the argument (@file{~/News/}). Then just walk ++around to the groups/directories with @code{nneething}. ++ ++ ++@node Decoding Articles ++@section Decoding Articles ++@cindex decoding articles ++ ++Sometime users post articles (or series of articles) that have been ++encoded in some way or other. Gnus can decode them for you. ++ ++@menu ++* Uuencoded Articles:: Uudecode articles. ++* Shell Archives:: Unshar articles. ++* PostScript Files:: Split PostScript. ++* Other Files:: Plain save and binhex. ++* Decoding Variables:: Variables for a happy decoding. ++* Viewing Files:: You want to look at the result of the decoding? ++@end menu ++ ++@cindex series ++@cindex article series ++All these functions use the process/prefix convention ++(@pxref{Process/Prefix}) for finding out what articles to work on, with ++the extension that a ``single article'' means ``a single series''. Gnus ++can find out by itself what articles belong to a series, decode all the ++articles and unpack/view/save the resulting file(s). ++ ++Gnus guesses what articles are in the series according to the following ++simplish rule: The subjects must be (nearly) identical, except for the ++last two numbers of the line. (Spaces are largely ignored, however.) ++ ++For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus ++will find all the articles that match the regexp @samp{^cat.gif ++([0-9]+/[0-9]+).*$}. ++ ++Subjects that are non-standard, like @samp{cat.gif (2/3) Part 6 of a ++series}, will not be properly recognized by any of the automatic viewing ++commands, and you have to mark the articles manually with @kbd{#}. ++ ++ ++@node Uuencoded Articles ++@subsection Uuencoded Articles ++@cindex uudecode ++@cindex uuencoded articles ++ ++@table @kbd ++ ++@item X u ++@kindex X u (Summary) ++@findex gnus-uu-decode-uu ++@c @icon{gnus-uu-decode-uu} ++Uudecodes the current series (@code{gnus-uu-decode-uu}). ++ ++@item X U ++@kindex X U (Summary) ++@findex gnus-uu-decode-uu-and-save ++Uudecodes and saves the current series ++(@code{gnus-uu-decode-uu-and-save}). ++ ++@item X v u ++@kindex X v u (Summary) ++@findex gnus-uu-decode-uu-view ++Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}). ++ ++@item X v U ++@kindex X v U (Summary) ++@findex gnus-uu-decode-uu-and-save-view ++Uudecodes, views and saves the current series ++(@code{gnus-uu-decode-uu-and-save-view}). ++ ++@end table ++ ++Remember that these all react to the presence of articles marked with ++the process mark. If, for instance, you'd like to decode and save an ++entire newsgroup, you'd typically do @kbd{M P a} ++(@code{gnus-uu-mark-all}) and then @kbd{X U} ++(@code{gnus-uu-decode-uu-and-save}). ++ ++All this is very much different from how @code{gnus-uu} worked with ++@sc{gnus 4.1}, where you had explicit keystrokes for everything under ++the sun. This version of @code{gnus-uu} generally assumes that you mark ++articles in some way (@pxref{Setting Process Marks}) and then press ++@kbd{X u}. ++ ++@vindex gnus-uu-notify-files ++Note: When trying to decode articles that have names matching ++@code{gnus-uu-notify-files}, which is hard-coded to ++@samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will ++automatically post an article on @samp{comp.unix.wizards} saying that ++you have just viewed the file in question. This feature can't be turned ++off. ++ ++ ++@node Shell Archives ++@subsection Shell Archives ++@cindex unshar ++@cindex shell archives ++@cindex shared articles ++ ++Shell archives (``shar files'') used to be a popular way to distribute ++sources, but it isn't used all that much today. In any case, we have ++some commands to deal with these: ++ ++@table @kbd ++ ++@item X s ++@kindex X s (Summary) ++@findex gnus-uu-decode-unshar ++Unshars the current series (@code{gnus-uu-decode-unshar}). ++ ++@item X S ++@kindex X S (Summary) ++@findex gnus-uu-decode-unshar-and-save ++Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}). ++ ++@item X v s ++@kindex X v s (Summary) ++@findex gnus-uu-decode-unshar-view ++Unshars and views the current series (@code{gnus-uu-decode-unshar-view}). ++ ++@item X v S ++@kindex X v S (Summary) ++@findex gnus-uu-decode-unshar-and-save-view ++Unshars, views and saves the current series ++(@code{gnus-uu-decode-unshar-and-save-view}). ++@end table ++ ++ ++@node PostScript Files ++@subsection PostScript Files ++@cindex PostScript ++ ++@table @kbd ++ ++@item X p ++@kindex X p (Summary) ++@findex gnus-uu-decode-postscript ++Unpack the current PostScript series (@code{gnus-uu-decode-postscript}). ++ ++@item X P ++@kindex X P (Summary) ++@findex gnus-uu-decode-postscript-and-save ++Unpack and save the current PostScript series ++(@code{gnus-uu-decode-postscript-and-save}). ++ ++@item X v p ++@kindex X v p (Summary) ++@findex gnus-uu-decode-postscript-view ++View the current PostScript series ++(@code{gnus-uu-decode-postscript-view}). ++ ++@item X v P ++@kindex X v P (Summary) ++@findex gnus-uu-decode-postscript-and-save-view ++View and save the current PostScript series ++(@code{gnus-uu-decode-postscript-and-save-view}). ++@end table ++ ++ ++@node Other Files ++@subsection Other Files ++ ++@table @kbd ++@item X o ++@kindex X o (Summary) ++@findex gnus-uu-decode-save ++Save the current series ++(@code{gnus-uu-decode-save}). ++ ++@item X b ++@kindex X b (Summary) ++@findex gnus-uu-decode-binhex ++Unbinhex the current series (@code{gnus-uu-decode-binhex}). This ++doesn't really work yet. ++ ++@item X Y ++@kindex X Y (Summary) ++@findex gnus-uu-decode-yenc ++yEnc-decode the current series and save it (@code{gnus-uu-decode-yenc}). ++@end table ++ ++ ++@node Decoding Variables ++@subsection Decoding Variables ++ ++Adjective, not verb. ++ ++@menu ++* Rule Variables:: Variables that say how a file is to be viewed. ++* Other Decode Variables:: Other decode variables. ++* Uuencoding and Posting:: Variables for customizing uuencoding. ++@end menu ++ ++ ++@node Rule Variables ++@subsubsection Rule Variables ++@cindex rule variables ++ ++Gnus uses @dfn{rule variables} to decide how to view a file. All these ++variables are of the form ++ ++@lisp ++ (list '(regexp1 command2) ++ '(regexp2 command2) ++ ...) ++@end lisp ++ ++@table @code ++ ++@item gnus-uu-user-view-rules ++@vindex gnus-uu-user-view-rules ++@cindex sox ++This variable is consulted first when viewing files. If you wish to use, ++for instance, @code{sox} to convert an @file{.au} sound file, you could ++say something like: ++@lisp ++(setq gnus-uu-user-view-rules ++ (list '("\\\\.au$" "sox %s -t .aiff > /dev/audio"))) ++@end lisp ++ ++@item gnus-uu-user-view-rules-end ++@vindex gnus-uu-user-view-rules-end ++This variable is consulted if Gnus couldn't make any matches from the ++user and default view rules. ++ ++@item gnus-uu-user-archive-rules ++@vindex gnus-uu-user-archive-rules ++This variable can be used to say what commands should be used to unpack ++archives. ++@end table ++ ++ ++@node Other Decode Variables ++@subsubsection Other Decode Variables ++ ++@table @code ++@vindex gnus-uu-grabbed-file-functions ++ ++@item gnus-uu-grabbed-file-functions ++All functions in this list will be called right after each file has been ++successfully decoded---so that you can move or view files right away, ++and don't have to wait for all files to be decoded before you can do ++anything. Ready-made functions you can put in this list are: ++ ++@table @code ++ ++@item gnus-uu-grab-view ++@findex gnus-uu-grab-view ++View the file. ++ ++@item gnus-uu-grab-move ++@findex gnus-uu-grab-move ++Move the file (if you're using a saving function.) ++@end table ++ ++@item gnus-uu-be-dangerous ++@vindex gnus-uu-be-dangerous ++Specifies what to do if unusual situations arise during decoding. If ++@code{nil}, be as conservative as possible. If @code{t}, ignore things ++that didn't work, and overwrite existing files. Otherwise, ask each ++time. ++ ++@item gnus-uu-ignore-files-by-name ++@vindex gnus-uu-ignore-files-by-name ++Files with name matching this regular expression won't be viewed. ++ ++@item gnus-uu-ignore-files-by-type ++@vindex gnus-uu-ignore-files-by-type ++Files with a @acronym{MIME} type matching this variable won't be viewed. ++Note that Gnus tries to guess what type the file is based on the name. ++@code{gnus-uu} is not a @acronym{MIME} package (yet), so this is slightly ++kludgey. ++ ++@item gnus-uu-tmp-dir ++@vindex gnus-uu-tmp-dir ++Where @code{gnus-uu} does its work. ++ ++@item gnus-uu-do-not-unpack-archives ++@vindex gnus-uu-do-not-unpack-archives ++Non-@code{nil} means that @code{gnus-uu} won't peek inside archives ++looking for files to display. ++ ++@item gnus-uu-view-and-save ++@vindex gnus-uu-view-and-save ++Non-@code{nil} means that the user will always be asked to save a file ++after viewing it. ++ ++@item gnus-uu-ignore-default-view-rules ++@vindex gnus-uu-ignore-default-view-rules ++Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing ++rules. ++ ++@item gnus-uu-ignore-default-archive-rules ++@vindex gnus-uu-ignore-default-archive-rules ++Non-@code{nil} means that @code{gnus-uu} will ignore the default archive ++unpacking commands. ++ ++@item gnus-uu-kill-carriage-return ++@vindex gnus-uu-kill-carriage-return ++Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns ++from articles. ++ ++@item gnus-uu-unmark-articles-not-decoded ++@vindex gnus-uu-unmark-articles-not-decoded ++Non-@code{nil} means that @code{gnus-uu} will mark unsuccessfully ++decoded articles as unread. ++ ++@item gnus-uu-correct-stripped-uucode ++@vindex gnus-uu-correct-stripped-uucode ++Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix ++uuencoded files that have had trailing spaces deleted. ++ ++@item gnus-uu-pre-uudecode-hook ++@vindex gnus-uu-pre-uudecode-hook ++Hook run before sending a message to @code{uudecode}. ++ ++@item gnus-uu-view-with-metamail ++@vindex gnus-uu-view-with-metamail ++@cindex metamail ++Non-@code{nil} means that @code{gnus-uu} will ignore the viewing ++commands defined by the rule variables and just fudge a @acronym{MIME} ++content type based on the file name. The result will be fed to ++@code{metamail} for viewing. ++ ++@item gnus-uu-save-in-digest ++@vindex gnus-uu-save-in-digest ++Non-@code{nil} means that @code{gnus-uu}, when asked to save without ++decoding, will save in digests. If this variable is @code{nil}, ++@code{gnus-uu} will just save everything in a file without any ++embellishments. The digesting almost conforms to RFC 1153---no easy way ++to specify any meaningful volume and issue numbers were found, so I ++simply dropped them. ++ ++@end table ++ ++ ++@node Uuencoding and Posting ++@subsubsection Uuencoding and Posting ++ ++@table @code ++ ++@item gnus-uu-post-include-before-composing ++@vindex gnus-uu-post-include-before-composing ++Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode ++before you compose the article. If this variable is @code{t}, you can ++either include an encoded file with @kbd{C-c C-i} or have one included ++for you when you post the article. ++ ++@item gnus-uu-post-length ++@vindex gnus-uu-post-length ++Maximum length of an article. The encoded file will be split into how ++many articles it takes to post the entire file. ++ ++@item gnus-uu-post-threaded ++@vindex gnus-uu-post-threaded ++Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a ++thread. This may not be smart, as no other decoder I have seen is able ++to follow threads when collecting uuencoded articles. (Well, I have ++seen one package that does that---@code{gnus-uu}, but somehow, I don't ++think that counts@dots{}) Default is @code{nil}. ++ ++@item gnus-uu-post-separate-description ++@vindex gnus-uu-post-separate-description ++Non-@code{nil} means that the description will be posted in a separate ++article. The first article will typically be numbered (0/x). If this ++variable is @code{nil}, the description the user enters will be included ++at the beginning of the first article, which will be numbered (1/x). ++Default is @code{t}. ++ ++@end table ++ ++ ++@node Viewing Files ++@subsection Viewing Files ++@cindex viewing files ++@cindex pseudo-articles ++ ++After decoding, if the file is some sort of archive, Gnus will attempt ++to unpack the archive and see if any of the files in the archive can be ++viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz} ++containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will ++uncompress and de-tar the main file, and then view the two pictures. ++This unpacking process is recursive, so if the archive contains archives ++of archives, it'll all be unpacked. ++ ++Finally, Gnus will normally insert a @dfn{pseudo-article} for each ++extracted file into the summary buffer. If you go to these ++``articles'', you will be prompted for a command to run (usually Gnus ++will make a suggestion), and then the command will be run. ++ ++@vindex gnus-view-pseudo-asynchronously ++If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait ++until the viewing is done before proceeding. ++ ++@vindex gnus-view-pseudos ++If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert ++the pseudo-articles into the summary buffer, but view them ++immediately. If this variable is @code{not-confirm}, the user won't even ++be asked for a confirmation before viewing is done. ++ ++@vindex gnus-view-pseudos-separately ++If @code{gnus-view-pseudos-separately} is non-@code{nil}, one ++pseudo-article will be created for each file to be viewed. If ++@code{nil}, all files that use the same viewing command will be given as ++a list of parameters to that command. ++ ++@vindex gnus-insert-pseudo-articles ++If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert ++pseudo-articles when decoding. It is @code{t} by default. ++ ++So; there you are, reading your @emph{pseudo-articles} in your ++@emph{virtual newsgroup} from the @emph{virtual server}; and you think: ++Why isn't anything real anymore? How did we get here? ++ ++ ++@node Article Treatment ++@section Article Treatment ++ ++Reading through this huge manual, you may have quite forgotten that the ++object of newsreaders is to actually, like, read what people have ++written. Reading articles. Unfortunately, people are quite bad at ++writing, so there are tons of functions and variables to make reading ++these articles easier. ++ ++@menu ++* Article Highlighting:: You want to make the article look like fruit salad. ++* Article Fontisizing:: Making emphasized text look nice. ++* Article Hiding:: You also want to make certain info go away. ++* Article Washing:: Lots of way-neat functions to make life better. ++* Article Header:: Doing various header transformations. ++* Article Buttons:: Click on URLs, Message-IDs, addresses and the like. ++* Article Button Levels:: Controlling appearance of buttons. ++* Article Date:: Grumble, UT! ++* Article Display:: Display various stuff---X-Face, Picons, Smileys ++* Article Signature:: What is a signature? ++* Article Miscellanea:: Various other stuff. ++@end menu ++ ++ ++@node Article Highlighting ++@subsection Article Highlighting ++@cindex highlighting ++ ++Not only do you want your article buffer to look like fruit salad, but ++you want it to look like technicolor fruit salad. ++ ++@table @kbd ++ ++@item W H a ++@kindex W H a (Summary) ++@findex gnus-article-highlight ++@findex gnus-article-maybe-highlight ++Do much highlighting of the current article ++(@code{gnus-article-highlight}). This function highlights header, cited ++text, the signature, and adds buttons to the body and the head. ++ ++@item W H h ++@kindex W H h (Summary) ++@findex gnus-article-highlight-headers ++@vindex gnus-header-face-alist ++Highlight the headers (@code{gnus-article-highlight-headers}). The ++highlighting will be done according to the @code{gnus-header-face-alist} ++variable, which is a list where each element has the form ++@code{(@var{regexp} @var{name} @var{content})}. ++@var{regexp} is a regular expression for matching the ++header, @var{name} is the face used for highlighting the header name ++(@pxref{Faces and Fonts}) and @var{content} is the face for highlighting ++the header value. The first match made will be used. Note that ++@var{regexp} shouldn't have @samp{^} prepended---Gnus will add one. ++ ++@item W H c ++@kindex W H c (Summary) ++@findex gnus-article-highlight-citation ++Highlight cited text (@code{gnus-article-highlight-citation}). ++ ++Some variables to customize the citation highlights: ++ ++@table @code ++@vindex gnus-cite-parse-max-size ++ ++@item gnus-cite-parse-max-size ++If the article size in bytes is bigger than this variable (which is ++25000 by default), no citation highlighting will be performed. ++ ++@item gnus-cite-max-prefix ++@vindex gnus-cite-max-prefix ++Maximum possible length for a citation prefix (default 20). ++ ++@item gnus-cite-face-list ++@vindex gnus-cite-face-list ++List of faces used for highlighting citations (@pxref{Faces and Fonts}). ++When there are citations from multiple articles in the same message, ++Gnus will try to give each citation from each article its own face. ++This should make it easier to see who wrote what. ++ ++@item gnus-supercite-regexp ++@vindex gnus-supercite-regexp ++Regexp matching normal Supercite attribution lines. ++ ++@item gnus-supercite-secondary-regexp ++@vindex gnus-supercite-secondary-regexp ++Regexp matching mangled Supercite attribution lines. ++ ++@item gnus-cite-minimum-match-count ++@vindex gnus-cite-minimum-match-count ++Minimum number of identical prefixes we have to see before we believe ++that it's a citation. ++ ++@item gnus-cite-attribution-prefix ++@vindex gnus-cite-attribution-prefix ++Regexp matching the beginning of an attribution line. ++ ++@item gnus-cite-attribution-suffix ++@vindex gnus-cite-attribution-suffix ++Regexp matching the end of an attribution line. ++ ++@item gnus-cite-attribution-face ++@vindex gnus-cite-attribution-face ++Face used for attribution lines. It is merged with the face for the ++cited text belonging to the attribution. ++ ++@item gnus-cite-ignore-quoted-from ++@vindex gnus-cite-ignore-quoted-from ++If non-@code{nil}, no citation highlighting will be performed on lines ++beginning with @samp{>From }. Those lines may have been quoted by MTAs ++in order not to mix up with the envelope From line. The default value ++is @code{t}. ++ ++@end table ++ ++ ++@item W H s ++@kindex W H s (Summary) ++@vindex gnus-signature-separator ++@vindex gnus-signature-face ++@findex gnus-article-highlight-signature ++Highlight the signature (@code{gnus-article-highlight-signature}). ++Everything after @code{gnus-signature-separator} (@pxref{Article ++Signature}) in an article will be considered a signature and will be ++highlighted with @code{gnus-signature-face}, which is @code{italic} by ++default. ++ ++@end table ++ ++@xref{Customizing Articles}, for how to highlight articles automatically. ++ ++ ++@node Article Fontisizing ++@subsection Article Fontisizing ++@cindex emphasis ++@cindex article emphasis ++ ++@findex gnus-article-emphasize ++@kindex W e (Summary) ++People commonly add emphasis to words in news articles by writing things ++like @samp{_this_} or @samp{*this*} or @samp{/this/}. Gnus can make ++this look nicer by running the article through the @kbd{W e} ++(@code{gnus-article-emphasize}) command. ++ ++@vindex gnus-emphasis-alist ++How the emphasis is computed is controlled by the ++@code{gnus-emphasis-alist} variable. This is an alist where the first ++element is a regular expression to be matched. The second is a number ++that says what regular expression grouping is used to find the entire ++emphasized word. The third is a number that says what regexp grouping ++should be displayed and highlighted. (The text between these two ++groupings will be hidden.) The fourth is the face used for ++highlighting. ++ ++@lisp ++(setq gnus-emphasis-alist ++ '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline) ++ ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold))) ++@end lisp ++ ++@cindex slash ++@cindex asterisk ++@cindex underline ++@cindex / ++@cindex * ++ ++@vindex gnus-emphasis-underline ++@vindex gnus-emphasis-bold ++@vindex gnus-emphasis-italic ++@vindex gnus-emphasis-underline-bold ++@vindex gnus-emphasis-underline-italic ++@vindex gnus-emphasis-bold-italic ++@vindex gnus-emphasis-underline-bold-italic ++By default, there are seven rules, and they use the following faces: ++@code{gnus-emphasis-bold}, @code{gnus-emphasis-italic}, ++@code{gnus-emphasis-underline}, @code{gnus-emphasis-bold-italic}, ++@code{gnus-emphasis-underline-italic}, ++@code{gnus-emphasis-underline-bold}, and ++@code{gnus-emphasis-underline-bold-italic}. ++ ++If you want to change these faces, you can either use @kbd{M-x ++customize}, or you can use @code{copy-face}. For instance, if you want ++to make @code{gnus-emphasis-italic} use a red face instead, you could ++say something like: ++ ++@lisp ++(copy-face 'red 'gnus-emphasis-italic) ++@end lisp ++ ++@vindex gnus-group-highlight-words-alist ++ ++If you want to highlight arbitrary words, you can use the ++@code{gnus-group-highlight-words-alist} variable, which uses the same ++syntax as @code{gnus-emphasis-alist}. The @code{highlight-words} group ++parameter (@pxref{Group Parameters}) can also be used. ++ ++@xref{Customizing Articles}, for how to fontize articles automatically. ++ ++ ++@node Article Hiding ++@subsection Article Hiding ++@cindex article hiding ++ ++Or rather, hiding certain things in each article. There usually is much ++too much cruft in most articles. ++ ++@table @kbd ++ ++@item W W a ++@kindex W W a (Summary) ++@findex gnus-article-hide ++Do quite a lot of hiding on the article buffer ++(@kbd{gnus-article-hide}). In particular, this function will hide ++headers, @acronym{PGP}, cited text and the signature. ++ ++@item W W h ++@kindex W W h (Summary) ++@findex gnus-article-hide-headers ++Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding ++Headers}. ++ ++@item W W b ++@kindex W W b (Summary) ++@findex gnus-article-hide-boring-headers ++Hide headers that aren't particularly interesting ++(@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}. ++ ++@item W W s ++@kindex W W s (Summary) ++@findex gnus-article-hide-signature ++Hide signature (@code{gnus-article-hide-signature}). @xref{Article ++Signature}. ++ ++@item W W l ++@kindex W W l (Summary) ++@findex gnus-article-hide-list-identifiers ++@vindex gnus-list-identifiers ++Strip list identifiers specified in @code{gnus-list-identifiers}. These ++are strings some mailing list servers add to the beginning of all ++@code{Subject} headers---for example, @samp{[zebra 4711]}. Any leading ++@samp{Re: } is skipped before stripping. @code{gnus-list-identifiers} ++may not contain @code{\\(..\\)}. ++ ++@table @code ++ ++@item gnus-list-identifiers ++@vindex gnus-list-identifiers ++A regular expression that matches list identifiers to be removed from ++subject. This can also be a list of regular expressions. ++ ++@end table ++ ++@item W W P ++@kindex W W P (Summary) ++@findex gnus-article-hide-pem ++Hide @acronym{PEM} (privacy enhanced messages) cruft ++(@code{gnus-article-hide-pem}). ++ ++@item W W B ++@kindex W W B (Summary) ++@findex gnus-article-strip-banner ++@vindex gnus-article-banner-alist ++@vindex gnus-article-address-banner-alist ++@cindex banner ++@cindex OneList ++@cindex stripping advertisements ++@cindex advertisements ++Strip the banner specified by the @code{banner} group parameter ++(@code{gnus-article-strip-banner}). This is mainly used to hide those ++annoying banners and/or signatures that some mailing lists and moderated ++groups adds to all the messages. The way to use this function is to add ++the @code{banner} group parameter (@pxref{Group Parameters}) to the ++group you want banners stripped from. The parameter either be a string, ++which will be interpreted as a regular expression matching text to be ++removed, or the symbol @code{signature}, meaning that the (last) ++signature should be removed, or other symbol, meaning that the ++corresponding regular expression in @code{gnus-article-banner-alist} is ++used. ++ ++Regardless of a group, you can hide things like advertisements only when ++the sender of an article has a certain mail address specified in ++@code{gnus-article-address-banner-alist}. ++ ++@table @code ++ ++@item gnus-article-address-banner-alist ++@vindex gnus-article-address-banner-alist ++Alist of mail addresses and banners. Each element has the form ++@code{(@var{address} . @var{banner})}, where @var{address} is a regexp ++matching a mail address in the From header, @var{banner} is one of a ++symbol @code{signature}, an item in @code{gnus-article-banner-alist}, ++a regexp and @code{nil}. If @var{address} matches author's mail ++address, it will remove things like advertisements. For example, if a ++sender has the mail address @samp{hail@@yoo-hoo.co.jp} and there is a ++banner something like @samp{Do You Yoo-hoo!?} in all articles he ++sends, you can use the following element to remove them: ++ ++@lisp ++("@@yoo-hoo\\.co\\.jp\\'" . ++ "\n_+\nDo You Yoo-hoo!\\?\n.*\n.*\n") ++@end lisp ++ ++@end table ++ ++@item W W c ++@kindex W W c (Summary) ++@findex gnus-article-hide-citation ++Hide citation (@code{gnus-article-hide-citation}). Some variables for ++customizing the hiding: ++ ++@table @code ++ ++@item gnus-cited-opened-text-button-line-format ++@itemx gnus-cited-closed-text-button-line-format ++@vindex gnus-cited-closed-text-button-line-format ++@vindex gnus-cited-opened-text-button-line-format ++Gnus adds buttons to show where the cited text has been hidden, and to ++allow toggle hiding the text. The format of the variable is specified ++by these format-like variable (@pxref{Formatting Variables}). These ++specs are valid: ++ ++@table @samp ++@item b ++Starting point of the hidden text. ++@item e ++Ending point of the hidden text. ++@item l ++Number of characters in the hidden region. ++@item n ++Number of lines of hidden text. ++@end table ++ ++@item gnus-cited-lines-visible ++@vindex gnus-cited-lines-visible ++The number of lines at the beginning of the cited text to leave ++shown. This can also be a cons cell with the number of lines at the top ++and bottom of the text, respectively, to remain visible. ++ ++@end table ++ ++@item W W C-c ++@kindex W W C-c (Summary) ++@findex gnus-article-hide-citation-maybe ++ ++Hide citation (@code{gnus-article-hide-citation-maybe}) depending on the ++following two variables: ++ ++@table @code ++@item gnus-cite-hide-percentage ++@vindex gnus-cite-hide-percentage ++If the cited text is of a bigger percentage than this variable (default ++50), hide the cited text. ++ ++@item gnus-cite-hide-absolute ++@vindex gnus-cite-hide-absolute ++The cited text must have at least this length (default 10) before it ++is hidden. ++@end table ++ ++@item W W C ++@kindex W W C (Summary) ++@findex gnus-article-hide-citation-in-followups ++Hide cited text in articles that aren't roots ++(@code{gnus-article-hide-citation-in-followups}). This isn't very ++useful as an interactive command, but might be a handy function to stick ++have happen automatically (@pxref{Customizing Articles}). ++ ++@end table ++ ++All these ``hiding'' commands are toggles, but if you give a negative ++prefix to these commands, they will show what they have previously ++hidden. If you give a positive prefix, they will always hide. ++ ++Also @pxref{Article Highlighting} for further variables for ++citation customization. ++ ++@xref{Customizing Articles}, for how to hide article elements ++automatically. ++ ++ ++@node Article Washing ++@subsection Article Washing ++@cindex washing ++@cindex article washing ++ ++We call this ``article washing'' for a really good reason. Namely, the ++@kbd{A} key was taken, so we had to use the @kbd{W} key instead. ++ ++@dfn{Washing} is defined by us as ``changing something from something to ++something else'', but normally results in something looking better. ++Cleaner, perhaps. ++ ++@xref{Customizing Articles}, if you want to change how Gnus displays ++articles by default. ++ ++@table @kbd ++ ++@item C-u g ++This is not really washing, it's sort of the opposite of washing. If ++you type this, you see the article exactly as it exists on disk or on ++the server. ++ ++@item g ++Force redisplaying of the current article ++(@code{gnus-summary-show-article}). This is also not really washing. ++If you type this, you see the article without any previously applied ++interactive Washing functions but with all default treatments ++(@pxref{Customizing Articles}). ++ ++@item W l ++@kindex W l (Summary) ++@findex gnus-summary-stop-page-breaking ++Remove page breaks from the current article ++(@code{gnus-summary-stop-page-breaking}). @xref{Misc Article}, for page ++delimiters. ++ ++@item W r ++@kindex W r (Summary) ++@findex gnus-summary-caesar-message ++@c @icon{gnus-summary-caesar-message} ++Do a Caesar rotate (rot13) on the article buffer ++(@code{gnus-summary-caesar-message}). ++Unreadable articles that tell you to read them with Caesar rotate or rot13. ++(Typically offensive jokes and such.) ++ ++It's commonly called ``rot13'' because each letter is rotated 13 ++positions in the alphabet, e. g. @samp{B} (letter #2) -> @samp{O} (letter ++#15). It is sometimes referred to as ``Caesar rotate'' because Caesar ++is rumored to have employed this form of, uh, somewhat weak encryption. ++ ++@item W m ++@kindex W m (Summary) ++@findex gnus-summary-morse-message ++Morse decode the article buffer (@code{gnus-summary-morse-message}). ++ ++@item W i ++@kindex W i (Summary) ++@findex gnus-summary-idna-message ++Decode IDNA encoded domain names in the current articles. IDNA ++encoded domain names looks like @samp{xn--bar}. If a string remain ++unencoded after running invoking this, it is likely an invalid IDNA ++string (@samp{xn--bar} is invalid). You must have GNU Libidn ++(@url{http://www.gnu.org/software/libidn/}) installed for this command ++to work. ++ ++@item W t ++@item t ++@kindex W t (Summary) ++@kindex t (Summary) ++@findex gnus-summary-toggle-header ++Toggle whether to display all headers in the article buffer ++(@code{gnus-summary-toggle-header}). ++ ++@item W v ++@kindex W v (Summary) ++@findex gnus-summary-verbose-headers ++Toggle whether to display all headers in the article buffer permanently ++(@code{gnus-summary-verbose-headers}). ++ ++@item W o ++@kindex W o (Summary) ++@findex gnus-article-treat-overstrike ++Treat overstrike (@code{gnus-article-treat-overstrike}). ++ ++@item W d ++@kindex W d (Summary) ++@findex gnus-article-treat-dumbquotes ++@vindex gnus-article-dumbquotes-map ++@cindex Smartquotes ++@cindex M****s*** sm*rtq**t*s ++@cindex Latin 1 ++Treat M****s*** sm*rtq**t*s according to ++@code{gnus-article-dumbquotes-map} ++(@code{gnus-article-treat-dumbquotes}). Note that this function guesses ++whether a character is a sm*rtq**t* or not, so it should only be used ++interactively. ++ ++Sm*rtq**t*s are M****s***'s unilateral extension to the character map in ++an attempt to provide more quoting characters. If you see something ++like @code{\222} or @code{\264} where you're expecting some kind of ++apostrophe or quotation mark, then try this wash. ++ ++@item W Y f ++@kindex W Y f (Summary) ++@findex gnus-article-outlook-deuglify-article ++@cindex Outlook Express ++Full deuglify of broken Outlook (Express) articles: Treat dumbquotes, ++unwrap lines, repair attribution and rearrange citation. ++(@code{gnus-article-outlook-deuglify-article}). ++ ++@item W Y u ++@kindex W Y u (Summary) ++@findex gnus-article-outlook-unwrap-lines ++@vindex gnus-outlook-deuglify-unwrap-min ++@vindex gnus-outlook-deuglify-unwrap-max ++Unwrap lines that appear to be wrapped citation lines. You can control ++what lines will be unwrapped by frobbing ++@code{gnus-outlook-deuglify-unwrap-min} and ++@code{gnus-outlook-deuglify-unwrap-max}, indicating the minimum and ++maximum length of an unwrapped citation line. ++(@code{gnus-article-outlook-unwrap-lines}). ++ ++@item W Y a ++@kindex W Y a (Summary) ++@findex gnus-article-outlook-repair-attribution ++Repair a broken attribution line.@* ++(@code{gnus-article-outlook-repair-attribution}). ++ ++@item W Y c ++@kindex W Y c (Summary) ++@findex gnus-article-outlook-rearrange-citation ++Repair broken citations by rearranging the text. ++(@code{gnus-article-outlook-rearrange-citation}). ++ ++@item W w ++@kindex W w (Summary) ++@findex gnus-article-fill-cited-article ++Do word wrap (@code{gnus-article-fill-cited-article}). ++ ++You can give the command a numerical prefix to specify the width to use ++when filling. ++ ++@item W Q ++@kindex W Q (Summary) ++@findex gnus-article-fill-long-lines ++Fill long lines (@code{gnus-article-fill-long-lines}). ++ ++@item W C ++@kindex W C (Summary) ++@findex gnus-article-capitalize-sentences ++Capitalize the first word in each sentence ++(@code{gnus-article-capitalize-sentences}). ++ ++@item W c ++@kindex W c (Summary) ++@findex gnus-article-remove-cr ++Translate CRLF pairs (i. e., @samp{^M}s on the end of the lines) into LF ++(this takes care of DOS line endings), and then translate any remaining ++CRs into LF (this takes care of Mac line endings) ++(@code{gnus-article-remove-cr}). ++ ++@item W q ++@kindex W q (Summary) ++@findex gnus-article-de-quoted-unreadable ++Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}). ++Quoted-Printable is one common @acronym{MIME} encoding employed when ++sending non-@acronym{ASCII} (i.e., 8-bit) articles. It typically ++makes strings like @samp{d@'ej@`a vu} look like @samp{d=E9j=E0 vu}, ++which doesn't look very readable to me. Note that this is usually ++done automatically by Gnus if the message in question has a ++@code{Content-Transfer-Encoding} header that says that this encoding ++has been done. If a prefix is given, a charset will be asked for. ++ ++@item W 6 ++@kindex W 6 (Summary) ++@findex gnus-article-de-base64-unreadable ++Treat base64 (@code{gnus-article-de-base64-unreadable}). Base64 is ++one common @acronym{MIME} encoding employed when sending ++non-@acronym{ASCII} (i.e., 8-bit) articles. Note that this is ++usually done automatically by Gnus if the message in question has a ++@code{Content-Transfer-Encoding} header that says that this encoding ++has been done. If a prefix is given, a charset will be asked for. ++ ++@item W Z ++@kindex W Z (Summary) ++@findex gnus-article-decode-HZ ++Treat HZ or HZP (@code{gnus-article-decode-HZ}). HZ (or HZP) is one ++common encoding employed when sending Chinese articles. It typically ++makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}. ++ ++@item W A ++@kindex W A (Summary) ++@findex gnus-article-treat-ansi-sequences ++@cindex @acronym{ANSI} control sequences ++Translate @acronym{ANSI} SGR control sequences into overlays or ++extents (@code{gnus-article-treat-ansi-sequences}). @acronym{ANSI} ++sequences are used in some Chinese hierarchies for highlighting. ++ ++@item W u ++@kindex W u (Summary) ++@findex gnus-article-unsplit-urls ++Remove newlines from within URLs. Some mailers insert newlines into ++outgoing email messages to keep lines short. This reformatting can ++split long URLs onto multiple lines. Repair those URLs by removing ++the newlines (@code{gnus-article-unsplit-urls}). ++ ++@item W h ++@kindex W h (Summary) ++@findex gnus-article-wash-html ++Treat @acronym{HTML} (@code{gnus-article-wash-html}). Note that this is ++usually done automatically by Gnus if the message in question has a ++@code{Content-Type} header that says that the message is @acronym{HTML}. ++ ++If a prefix is given, a charset will be asked for. If it is a number, ++the charset defined in @code{gnus-summary-show-article-charset-alist} ++(@pxref{Paging the Article}) will be used. ++ ++@vindex gnus-article-wash-function ++The default is to use the function specified by ++@code{mm-text-html-renderer} (@pxref{Display Customization, ,Display ++Customization, emacs-mime, The Emacs MIME Manual}) to convert the ++@acronym{HTML}, but this is controlled by the ++@code{gnus-article-wash-function} variable. Pre-defined functions you ++can use include: ++ ++@table @code ++@item w3 ++Use Emacs/W3. ++ ++@item w3m ++Use @uref{http://emacs-w3m.namazu.org/, emacs-w3m}. ++ ++@item w3m-standalone ++Use @uref{http://w3m.sourceforge.net/, w3m}. ++ ++@item links ++Use @uref{http://links.sf.net/, Links}. ++ ++@item lynx ++Use @uref{http://lynx.isc.org/, Lynx}. ++ ++@item html2text ++Use html2text---a simple @acronym{HTML} converter included with Gnus. ++ ++@end table ++ ++@item W b ++@kindex W b (Summary) ++@findex gnus-article-add-buttons ++Add clickable buttons to the article (@code{gnus-article-add-buttons}). ++@xref{Article Buttons}. ++ ++@item W B ++@kindex W B (Summary) ++@findex gnus-article-add-buttons-to-head ++Add clickable buttons to the article headers ++(@code{gnus-article-add-buttons-to-head}). ++ ++@item W p ++@kindex W p (Summary) ++@findex gnus-article-verify-x-pgp-sig ++Verify a signed control message ++(@code{gnus-article-verify-x-pgp-sig}). Control messages such as ++@code{newgroup} and @code{checkgroups} are usually signed by the ++hierarchy maintainer. You need to add the @acronym{PGP} public key of ++the maintainer to your keyring to verify the ++message.@footnote{@acronym{PGP} keys for many hierarchies are ++available at @uref{ftp://ftp.isc.org/pub/pgpcontrol/README.html}} ++ ++@item W s ++@kindex W s (Summary) ++@findex gnus-summary-force-verify-and-decrypt ++Verify a signed (@acronym{PGP}, @acronym{PGP/MIME} or ++@acronym{S/MIME}) message ++(@code{gnus-summary-force-verify-and-decrypt}). @xref{Security}. ++ ++@item W a ++@kindex W a (Summary) ++@findex gnus-article-strip-headers-in-body ++Strip headers like the @code{X-No-Archive} header from the beginning of ++article bodies (@code{gnus-article-strip-headers-in-body}). ++ ++@item W E l ++@kindex W E l (Summary) ++@findex gnus-article-strip-leading-blank-lines ++Remove all blank lines from the beginning of the article ++(@code{gnus-article-strip-leading-blank-lines}). ++ ++@item W E m ++@kindex W E m (Summary) ++@findex gnus-article-strip-multiple-blank-lines ++Replace all blank lines with empty lines and then all multiple empty ++lines with a single empty line. ++(@code{gnus-article-strip-multiple-blank-lines}). ++ ++@item W E t ++@kindex W E t (Summary) ++@findex gnus-article-remove-trailing-blank-lines ++Remove all blank lines at the end of the article ++(@code{gnus-article-remove-trailing-blank-lines}). ++ ++@item W E a ++@kindex W E a (Summary) ++@findex gnus-article-strip-blank-lines ++Do all the three commands above ++(@code{gnus-article-strip-blank-lines}). ++ ++@item W E A ++@kindex W E A (Summary) ++@findex gnus-article-strip-all-blank-lines ++Remove all blank lines ++(@code{gnus-article-strip-all-blank-lines}). ++ ++@item W E s ++@kindex W E s (Summary) ++@findex gnus-article-strip-leading-space ++Remove all white space from the beginning of all lines of the article ++body (@code{gnus-article-strip-leading-space}). ++ ++@item W E e ++@kindex W E e (Summary) ++@findex gnus-article-strip-trailing-space ++Remove all white space from the end of all lines of the article ++body (@code{gnus-article-strip-trailing-space}). ++ ++@end table ++ ++@xref{Customizing Articles}, for how to wash articles automatically. ++ ++ ++@node Article Header ++@subsection Article Header ++ ++These commands perform various transformations of article header. ++ ++@table @kbd ++ ++@item W G u ++@kindex W G u (Summary) ++@findex gnus-article-treat-unfold-headers ++Unfold folded header lines (@code{gnus-article-treat-unfold-headers}). ++ ++@item W G n ++@kindex W G n (Summary) ++@findex gnus-article-treat-fold-newsgroups ++Fold the @code{Newsgroups} and @code{Followup-To} headers ++(@code{gnus-article-treat-fold-newsgroups}). ++ ++@item W G f ++@kindex W G f (Summary) ++@findex gnus-article-treat-fold-headers ++Fold all the message headers ++(@code{gnus-article-treat-fold-headers}). ++ ++@item W E w ++@kindex W E w (Summary) ++@findex gnus-article-remove-leading-whitespace ++Remove excessive whitespace from all headers ++(@code{gnus-article-remove-leading-whitespace}). ++ ++@end table ++ ++ ++@node Article Buttons ++@subsection Article Buttons ++@cindex buttons ++ ++People often include references to other stuff in articles, and it would ++be nice if Gnus could just fetch whatever it is that people talk about ++with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse ++button on these references. ++ ++@vindex gnus-button-man-handler ++Gnus adds @dfn{buttons} to certain standard references by default: ++Well-formed URLs, mail addresses, Message-IDs, Info links, man pages and ++Emacs or Gnus related references. This is controlled by two variables, ++one that handles article bodies and one that handles article heads: ++ ++@table @code ++ ++@item gnus-button-alist ++@vindex gnus-button-alist ++This is an alist where each entry has this form: ++ ++@lisp ++(@var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par}) ++@end lisp ++ ++@table @var ++ ++@item regexp ++All text that match this regular expression (case insensitive) will be ++considered an external reference. Here's a typical regexp that matches ++embedded URLs: @samp{]*\\)>}. This can also be a ++variable containing a regexp, useful variables to use include ++@code{gnus-button-url-regexp} and @code{gnus-button-mid-or-mail-regexp}. ++ ++@item button-par ++Gnus has to know which parts of the matches is to be highlighted. This ++is a number that says what sub-expression of the regexp is to be ++highlighted. If you want it all highlighted, you use 0 here. ++ ++@item use-p ++This form will be @code{eval}ed, and if the result is non-@code{nil}, ++this is considered a match. This is useful if you want extra sifting to ++avoid false matches. Often variables named ++@code{gnus-button-@var{*}-level} are used here, @xref{Article Button ++Levels}, but any other form may be used too. ++ ++@c @code{use-p} is @code{eval}ed only if @code{regexp} matches. ++ ++@item function ++This function will be called when you click on this button. ++ ++@item data-par ++As with @var{button-par}, this is a sub-expression number, but this one ++says which part of the match is to be sent as data to @var{function}. ++ ++@end table ++ ++So the full entry for buttonizing URLs is then ++ ++@lisp ++("]*\\)>" 0 t gnus-button-url 1) ++@end lisp ++ ++@item gnus-header-button-alist ++@vindex gnus-header-button-alist ++This is just like the other alist, except that it is applied to the ++article head only, and that each entry has an additional element that is ++used to say what headers to apply the buttonize coding to: ++ ++@lisp ++(@var{header} @var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par}) ++@end lisp ++ ++@var{header} is a regular expression. ++@end table ++ ++@subsubsection Related variables and functions ++ ++@table @code ++@item gnus-button-@var{*}-level ++@xref{Article Button Levels}. ++ ++@c Stuff related to gnus-button-browse-level ++ ++@item gnus-button-url-regexp ++@vindex gnus-button-url-regexp ++A regular expression that matches embedded URLs. It is used in the ++default values of the variables above. ++ ++@c Stuff related to gnus-button-man-level ++ ++@item gnus-button-man-handler ++@vindex gnus-button-man-handler ++The function to use for displaying man pages. It must take at least one ++argument with a string naming the man page. ++ ++@c Stuff related to gnus-button-message-level ++ ++@item gnus-button-mid-or-mail-regexp ++@vindex gnus-button-mid-or-mail-regexp ++Regular expression that matches a message ID or a mail address. ++ ++@item gnus-button-prefer-mid-or-mail ++@vindex gnus-button-prefer-mid-or-mail ++This variable determines what to do when the button on a string as ++@samp{foo123@@bar.invalid} is pushed. Strings like this can be either a ++message ID or a mail address. If it is one of the symbols @code{mid} or ++@code{mail}, Gnus will always assume that the string is a message ID or ++a mail address, respectively. If this variable is set to the symbol ++@code{ask}, always query the user what to do. If it is a function, this ++function will be called with the string as its only argument. The ++function must return @code{mid}, @code{mail}, @code{invalid} or ++@code{ask}. The default value is the function ++@code{gnus-button-mid-or-mail-heuristic}. ++ ++@item gnus-button-mid-or-mail-heuristic ++@findex gnus-button-mid-or-mail-heuristic ++Function that guesses whether its argument is a message ID or a mail ++address. Returns @code{mid} if it's a message IDs, @code{mail} if ++it's a mail address, @code{ask} if unsure and @code{invalid} if the ++string is invalid. ++ ++@item gnus-button-mid-or-mail-heuristic-alist ++@vindex gnus-button-mid-or-mail-heuristic-alist ++An alist of @code{(RATE . REGEXP)} pairs used by the function ++@code{gnus-button-mid-or-mail-heuristic}. ++ ++@c Stuff related to gnus-button-tex-level ++ ++@item gnus-button-ctan-handler ++@findex gnus-button-ctan-handler ++The function to use for displaying CTAN links. It must take one ++argument, the string naming the URL. ++ ++@item gnus-ctan-url ++@vindex gnus-ctan-url ++Top directory of a CTAN (Comprehensive TeX Archive Network) archive used ++by @code{gnus-button-ctan-handler}. ++ ++@c Misc stuff ++ ++@item gnus-article-button-face ++@vindex gnus-article-button-face ++Face used on buttons. ++ ++@item gnus-article-mouse-face ++@vindex gnus-article-mouse-face ++Face used when the mouse cursor is over a button. ++ ++@end table ++ ++@xref{Customizing Articles}, for how to buttonize articles automatically. ++ ++ ++@node Article Button Levels ++@subsection Article button levels ++@cindex button levels ++The higher the value of the variables @code{gnus-button-@var{*}-level}, ++the more buttons will appear. If the level is zero, no corresponding ++buttons are displayed. With the default value (which is 5) you should ++already see quite a lot of buttons. With higher levels, you will see ++more buttons, but you may also get more false positives. To avoid them, ++you can set the variables @code{gnus-button-@var{*}-level} local to ++specific groups (@pxref{Group Parameters}). Here's an example for the ++variable @code{gnus-parameters}: ++ ++@lisp ++;; @r{increase @code{gnus-button-*-level} in some groups:} ++(setq gnus-parameters ++ '(("\\<\\(emacs\\|gnus\\)\\>" (gnus-button-emacs-level 10)) ++ ("\\" (gnus-button-man-level 10)) ++ ("\\" (gnus-button-tex-level 10)))) ++@end lisp ++ ++@table @code ++ ++@item gnus-button-browse-level ++@vindex gnus-button-browse-level ++Controls the display of references to message IDs, mail addresses and ++news URLs. Related variables and functions include ++@code{gnus-button-url-regexp}, @code{browse-url}, and ++@code{browse-url-browser-function}. ++ ++@item gnus-button-emacs-level ++@vindex gnus-button-emacs-level ++Controls the display of Emacs or Gnus references. Related functions are ++@code{gnus-button-handle-custom}, ++@code{gnus-button-handle-describe-function}, ++@code{gnus-button-handle-describe-variable}, ++@code{gnus-button-handle-symbol}, ++@code{gnus-button-handle-describe-key}, ++@code{gnus-button-handle-apropos}, ++@code{gnus-button-handle-apropos-command}, ++@code{gnus-button-handle-apropos-variable}, ++@code{gnus-button-handle-apropos-documentation}, and ++@code{gnus-button-handle-library}. ++ ++@item gnus-button-man-level ++@vindex gnus-button-man-level ++Controls the display of references to (Unix) man pages. ++See @code{gnus-button-man-handler}. ++ ++@item gnus-button-message-level ++@vindex gnus-button-message-level ++Controls the display of message IDs, mail addresses and news URLs. ++Related variables and functions include ++@code{gnus-button-mid-or-mail-regexp}, ++@code{gnus-button-prefer-mid-or-mail}, ++@code{gnus-button-mid-or-mail-heuristic}, and ++@code{gnus-button-mid-or-mail-heuristic-alist}. ++ ++@item gnus-button-tex-level ++@vindex gnus-button-tex-level ++Controls the display of references to @TeX{} or LaTeX stuff, e.g. for CTAN ++URLs. See the variables @code{gnus-ctan-url}, ++@code{gnus-button-ctan-handler}, ++@code{gnus-button-ctan-directory-regexp}, and ++@code{gnus-button-handle-ctan-bogus-regexp}. ++ ++@end table ++ ++ ++@node Article Date ++@subsection Article Date ++ ++The date is most likely generated in some obscure timezone you've never ++heard of, so it's quite nice to be able to find out what the time was ++when the article was sent. ++ ++@table @kbd ++ ++@item W T u ++@kindex W T u (Summary) ++@findex gnus-article-date-ut ++Display the date in UT (aka. GMT, aka ZULU) ++(@code{gnus-article-date-ut}). ++ ++@item W T i ++@kindex W T i (Summary) ++@findex gnus-article-date-iso8601 ++@cindex ISO 8601 ++Display the date in international format, aka. ISO 8601 ++(@code{gnus-article-date-iso8601}). ++ ++@item W T l ++@kindex W T l (Summary) ++@findex gnus-article-date-local ++Display the date in the local timezone (@code{gnus-article-date-local}). ++ ++@item W T p ++@kindex W T p (Summary) ++@findex gnus-article-date-english ++Display the date in a format that's easily pronounceable in English ++(@code{gnus-article-date-english}). ++ ++@item W T s ++@kindex W T s (Summary) ++@vindex gnus-article-time-format ++@findex gnus-article-date-user ++@findex format-time-string ++Display the date using a user-defined format ++(@code{gnus-article-date-user}). The format is specified by the ++@code{gnus-article-time-format} variable, and is a string that's passed ++to @code{format-time-string}. See the documentation of that variable ++for a list of possible format specs. ++ ++@item W T e ++@kindex W T e (Summary) ++@findex gnus-article-date-lapsed ++@findex gnus-start-date-timer ++@findex gnus-stop-date-timer ++Say how much time has elapsed between the article was posted and now ++(@code{gnus-article-date-lapsed}). It looks something like: ++ ++@example ++X-Sent: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago ++@end example ++ ++@vindex gnus-article-date-lapsed-new-header ++The value of @code{gnus-article-date-lapsed-new-header} determines ++whether this header will just be added below the old Date one, or will ++replace it. ++ ++An advantage of using Gnus to read mail is that it converts simple bugs ++into wonderful absurdities. ++ ++If you want to have this line updated continually, you can put ++ ++@lisp ++(gnus-start-date-timer) ++@end lisp ++ ++in your @file{~/.gnus.el} file, or you can run it off of some hook. If ++you want to stop the timer, you can use the @code{gnus-stop-date-timer} ++command. ++ ++@item W T o ++@kindex W T o (Summary) ++@findex gnus-article-date-original ++Display the original date (@code{gnus-article-date-original}). This can ++be useful if you normally use some other conversion function and are ++worried that it might be doing something totally wrong. Say, claiming ++that the article was posted in 1854. Although something like that is ++@emph{totally} impossible. Don't you trust me? *titter* ++ ++@end table ++ ++@xref{Customizing Articles}, for how to display the date in your ++preferred format automatically. ++ ++ ++@node Article Display ++@subsection Article Display ++@cindex picons ++@cindex x-face ++@cindex smileys ++ ++These commands add various frivolous display gimmicks to the article ++buffer in Emacs versions that support them. ++ ++@code{X-Face} headers are small black-and-white images supplied by the ++message headers (@pxref{X-Face}). ++ ++@code{Face} headers are small colored images supplied by the message ++headers (@pxref{Face}). ++ ++Smileys are those little @samp{:-)} symbols that people like to litter ++their messages with (@pxref{Smileys}). ++ ++Picons, on the other hand, reside on your own system, and Gnus will ++try to match the headers to what you have (@pxref{Picons}). ++ ++All these functions are toggles---if the elements already exist, ++they'll be removed. ++ ++@table @kbd ++@item W D x ++@kindex W D x (Summary) ++@findex gnus-article-display-x-face ++Display an @code{X-Face} in the @code{From} header. ++(@code{gnus-article-display-x-face}). ++ ++@item W D d ++@kindex W D d (Summary) ++@findex gnus-article-display-face ++Display a @code{Face} in the @code{From} header. ++(@code{gnus-article-display-face}). ++ ++@item W D s ++@kindex W D s (Summary) ++@findex gnus-treat-smiley ++Display smileys (@code{gnus-treat-smiley}). ++ ++@item W D f ++@kindex W D f (Summary) ++@findex gnus-treat-from-picon ++Piconify the @code{From} header (@code{gnus-treat-from-picon}). ++ ++@item W D m ++@kindex W D m (Summary) ++@findex gnus-treat-mail-picon ++Piconify all mail headers (i. e., @code{Cc}, @code{To}) ++(@code{gnus-treat-mail-picon}). ++ ++@item W D n ++@kindex W D n (Summary) ++@findex gnus-treat-newsgroups-picon ++Piconify all news headers (i. e., @code{Newsgroups} and ++@code{Followup-To}) (@code{gnus-treat-newsgroups-picon}). ++ ++@item W D D ++@kindex W D D (Summary) ++@findex gnus-article-remove-images ++Remove all images from the article buffer ++(@code{gnus-article-remove-images}). ++ ++@end table ++ ++ ++ ++@node Article Signature ++@subsection Article Signature ++@cindex signatures ++@cindex article signature ++ ++@vindex gnus-signature-separator ++Each article is divided into two parts---the head and the body. The ++body can be divided into a signature part and a text part. The variable ++that says what is to be considered a signature is ++@code{gnus-signature-separator}. This is normally the standard ++@samp{^-- $} as mandated by son-of-RFC 1036. However, many people use ++non-standard signature separators, so this variable can also be a list ++of regular expressions to be tested, one by one. (Searches are done ++from the end of the body towards the beginning.) One likely value is: ++ ++@lisp ++(setq gnus-signature-separator ++ '("^-- $" ; @r{The standard} ++ "^-- *$" ; @r{A common mangling} ++ "^-------*$" ; @r{Many people just use a looong} ++ ; @r{line of dashes. Shame!} ++ "^ *--------*$" ; @r{Double-shame!} ++ "^________*$" ; @r{Underscores are also popular} ++ "^========*$")) ; @r{Pervert!} ++@end lisp ++ ++The more permissive you are, the more likely it is that you'll get false ++positives. ++ ++@vindex gnus-signature-limit ++@code{gnus-signature-limit} provides a limit to what is considered a ++signature when displaying articles. ++ ++@enumerate ++@item ++If it is an integer, no signature may be longer (in characters) than ++that integer. ++@item ++If it is a floating point number, no signature may be longer (in lines) ++than that number. ++@item ++If it is a function, the function will be called without any parameters, ++and if it returns @code{nil}, there is no signature in the buffer. ++@item ++If it is a string, it will be used as a regexp. If it matches, the text ++in question is not a signature. ++@end enumerate ++ ++This variable can also be a list where the elements may be of the types ++listed above. Here's an example: ++ ++@lisp ++(setq gnus-signature-limit ++ '(200.0 "^---*Forwarded article")) ++@end lisp ++ ++This means that if there are more than 200 lines after the signature ++separator, or the text after the signature separator is matched by ++the regular expression @samp{^---*Forwarded article}, then it isn't a ++signature after all. ++ ++ ++@node Article Miscellanea ++@subsection Article Miscellanea ++ ++@table @kbd ++@item A t ++@kindex A t (Summary) ++@findex gnus-article-babel ++Translate the article from one language to another ++(@code{gnus-article-babel}). ++ ++@end table ++ ++ ++@node MIME Commands ++@section MIME Commands ++@cindex MIME decoding ++@cindex attachments ++@cindex viewing attachments ++ ++The following commands all understand the numerical prefix. For ++instance, @kbd{3 K v} means ``view the third @acronym{MIME} part''. ++ ++@table @kbd ++@item b ++@itemx K v ++@kindex b (Summary) ++@kindex K v (Summary) ++View the @acronym{MIME} part. ++ ++@item K o ++@kindex K o (Summary) ++Save the @acronym{MIME} part. ++ ++@item K O ++@kindex K O (Summary) ++Prompt for a file name, then save the @acronym{MIME} part and strip it ++from the article. The stripped @acronym{MIME} object will be referred ++via the message/external-body @acronym{MIME} type. ++ ++@item K r ++@kindex K r (Summary) ++Replace the @acronym{MIME} part with an external body. ++ ++@item K d ++@kindex K d (Summary) ++Delete the @acronym{MIME} part and add some information about the ++removed part. ++ ++@item K c ++@kindex K c (Summary) ++Copy the @acronym{MIME} part. ++ ++@item K e ++@kindex K e (Summary) ++View the @acronym{MIME} part externally. ++ ++@item K i ++@kindex K i (Summary) ++View the @acronym{MIME} part internally. ++ ++@item K | ++@kindex K | (Summary) ++Pipe the @acronym{MIME} part to an external command. ++@end table ++ ++The rest of these @acronym{MIME} commands do not use the numerical prefix in ++the same manner: ++ ++@table @kbd ++@item K H ++@kindex K H (Summary) ++@findex gnus-article-browse-html-article ++View @samp{text/html} parts of the current article with a WWW browser. ++The message header is added to the beginning of every html part unless ++the prefix argument is given. ++ ++Warning: Spammers use links to images in HTML articles to verify whether ++you have read the message. As this command passes the @acronym{HTML} ++content to the browser without eliminating these ``web bugs'' you should ++only use it for mails from trusted senders. ++ ++If you always want to display @acronym{HTML} parts in the browser, set ++@code{mm-text-html-renderer} to @code{nil}. ++ ++@item K b ++@kindex K b (Summary) ++Make all the @acronym{MIME} parts have buttons in front of them. This is ++mostly useful if you wish to save (or perform other actions) on inlined ++parts. ++ ++@item K m ++@kindex K m (Summary) ++@findex gnus-summary-repair-multipart ++Some multipart messages are transmitted with missing or faulty headers. ++This command will attempt to ``repair'' these messages so that they can ++be viewed in a more pleasant manner ++(@code{gnus-summary-repair-multipart}). ++ ++@item X m ++@kindex X m (Summary) ++@findex gnus-summary-save-parts ++Save all parts matching a @acronym{MIME} type to a directory ++(@code{gnus-summary-save-parts}). Understands the process/prefix ++convention (@pxref{Process/Prefix}). ++ ++@item M-t ++@kindex M-t (Summary) ++@findex gnus-summary-toggle-display-buttonized ++Toggle the buttonized display of the article buffer ++(@code{gnus-summary-toggle-display-buttonized}). ++ ++@item W M w ++@kindex W M w (Summary) ++@findex gnus-article-decode-mime-words ++Decode RFC 2047-encoded words in the article headers ++(@code{gnus-article-decode-mime-words}). ++ ++@item W M c ++@kindex W M c (Summary) ++@findex gnus-article-decode-charset ++Decode encoded article bodies as well as charsets ++(@code{gnus-article-decode-charset}). ++ ++This command looks in the @code{Content-Type} header to determine the ++charset. If there is no such header in the article, you can give it a ++prefix, which will prompt for the charset to decode as. In regional ++groups where people post using some common encoding (but do not ++include @acronym{MIME} headers), you can set the @code{charset} group/topic ++parameter to the required charset (@pxref{Group Parameters}). ++ ++@item W M v ++@kindex W M v (Summary) ++@findex gnus-mime-view-all-parts ++View all the @acronym{MIME} parts in the current article ++(@code{gnus-mime-view-all-parts}). ++ ++@end table ++ ++Relevant variables: ++ ++@table @code ++@item gnus-ignored-mime-types ++@vindex gnus-ignored-mime-types ++This is a list of regexps. @acronym{MIME} types that match a regexp from ++this list will be completely ignored by Gnus. The default value is ++@code{nil}. ++ ++To have all Vcards be ignored, you'd say something like this: ++ ++@lisp ++(setq gnus-ignored-mime-types ++ '("text/x-vcard")) ++@end lisp ++ ++@item gnus-article-loose-mime ++@vindex gnus-article-loose-mime ++If non-@code{nil}, Gnus won't require the @samp{MIME-Version} header ++before interpreting the message as a @acronym{MIME} message. This helps ++when reading messages from certain broken mail user agents. The ++default is @code{t}. ++ ++@item gnus-article-emulate-mime ++@vindex gnus-article-emulate-mime ++@cindex uuencode ++@cindex yEnc ++There are other, non-@acronym{MIME} encoding methods used. The most common ++is @samp{uuencode}, but yEncode is also getting to be popular. If ++this variable is non-@code{nil}, Gnus will look in message bodies to ++see if it finds these encodings, and if so, it'll run them through the ++Gnus @acronym{MIME} machinery. The default is @code{t}. Only ++single-part yEnc encoded attachments can be decoded. There's no support ++for encoding in Gnus. ++ ++@item gnus-unbuttonized-mime-types ++@vindex gnus-unbuttonized-mime-types ++This is a list of regexps. @acronym{MIME} types that match a regexp from ++this list won't have @acronym{MIME} buttons inserted unless they aren't ++displayed or this variable is overridden by ++@code{gnus-buttonized-mime-types}. The default value is ++@code{(".*/.*")}. This variable is only used when ++@code{gnus-inhibit-mime-unbuttonizing} is @code{nil}. ++ ++@item gnus-buttonized-mime-types ++@vindex gnus-buttonized-mime-types ++This is a list of regexps. @acronym{MIME} types that match a regexp from ++this list will have @acronym{MIME} buttons inserted unless they aren't ++displayed. This variable overrides ++@code{gnus-unbuttonized-mime-types}. The default value is @code{nil}. ++This variable is only used when @code{gnus-inhibit-mime-unbuttonizing} ++is @code{nil}. ++ ++To see e.g. security buttons but no other buttons, you could set this ++variable to @code{("multipart/signed")} and leave ++@code{gnus-unbuttonized-mime-types} at the default value. ++ ++You could also add @code{"multipart/alternative"} to this list to ++display radio buttons that allow you to choose one of two media types ++those mails include. See also @code{mm-discouraged-alternatives} ++(@pxref{Display Customization, ,Display Customization, emacs-mime, The ++Emacs MIME Manual}). ++ ++@item gnus-inhibit-mime-unbuttonizing ++@vindex gnus-inhibit-mime-unbuttonizing ++If this is non-@code{nil}, then all @acronym{MIME} parts get buttons. The ++default value is @code{nil}. ++ ++@item gnus-article-mime-part-function ++@vindex gnus-article-mime-part-function ++For each @acronym{MIME} part, this function will be called with the @acronym{MIME} ++handle as the parameter. The function is meant to be used to allow ++users to gather information from the article (e. g., add Vcard info to ++the bbdb database) or to do actions based on parts (e. g., automatically ++save all jpegs into some directory). ++ ++Here's an example function the does the latter: ++ ++@lisp ++(defun my-save-all-jpeg-parts (handle) ++ (when (equal (car (mm-handle-type handle)) "image/jpeg") ++ (with-temp-buffer ++ (insert (mm-get-part handle)) ++ (write-region (point-min) (point-max) ++ (read-file-name "Save jpeg to: "))))) ++(setq gnus-article-mime-part-function ++ 'my-save-all-jpeg-parts) ++@end lisp ++ ++@vindex gnus-mime-multipart-functions ++@item gnus-mime-multipart-functions ++Alist of @acronym{MIME} multipart types and functions to handle them. ++ ++@vindex gnus-mime-display-multipart-alternative-as-mixed ++@item gnus-mime-display-multipart-alternative-as-mixed ++Display "multipart/alternative" parts as "multipart/mixed". ++ ++@vindex gnus-mime-display-multipart-related-as-mixed ++@item gnus-mime-display-multipart-related-as-mixed ++Display "multipart/related" parts as "multipart/mixed". ++ ++If displaying @samp{text/html} is discouraged, see ++@code{mm-discouraged-alternatives}, images or other material inside a ++"multipart/related" part might be overlooked when this variable is ++@code{nil}. @ref{Display Customization, Display Customization, , ++emacs-mime, Emacs-Mime Manual}. ++ ++@vindex gnus-mime-display-multipart-as-mixed ++@item gnus-mime-display-multipart-as-mixed ++Display "multipart" parts as "multipart/mixed". If @code{t}, it ++overrides @code{nil} values of ++@code{gnus-mime-display-multipart-alternative-as-mixed} and ++@code{gnus-mime-display-multipart-related-as-mixed}. ++ ++@vindex mm-file-name-rewrite-functions ++@item mm-file-name-rewrite-functions ++List of functions used for rewriting file names of @acronym{MIME} parts. ++Each function takes a file name as input and returns a file name. ++ ++Ready-made functions include@* ++@code{mm-file-name-delete-whitespace}, ++@code{mm-file-name-trim-whitespace}, ++@code{mm-file-name-collapse-whitespace}, and ++@code{mm-file-name-replace-whitespace}. The later uses the value of ++the variable @code{mm-file-name-replace-whitespace} to replace each ++whitespace character in a file name with that string; default value ++is @code{"_"} (a single underscore). ++@findex mm-file-name-delete-whitespace ++@findex mm-file-name-trim-whitespace ++@findex mm-file-name-collapse-whitespace ++@findex mm-file-name-replace-whitespace ++@vindex mm-file-name-replace-whitespace ++ ++The standard functions @code{capitalize}, @code{downcase}, ++@code{upcase}, and @code{upcase-initials} may be useful, too. ++ ++Everybody knows that whitespace characters in file names are evil, ++except those who don't know. If you receive lots of attachments from ++such unenlightened users, you can make live easier by adding ++ ++@lisp ++(setq mm-file-name-rewrite-functions ++ '(mm-file-name-trim-whitespace ++ mm-file-name-collapse-whitespace ++ mm-file-name-replace-whitespace)) ++@end lisp ++ ++@noindent ++to your @file{~/.gnus.el} file. ++ ++@end table ++ ++ ++@node Charsets ++@section Charsets ++@cindex charsets ++ ++People use different charsets, and we have @acronym{MIME} to let us know what ++charsets they use. Or rather, we wish we had. Many people use ++newsreaders and mailers that do not understand or use @acronym{MIME}, and ++just send out messages without saying what character sets they use. To ++help a bit with this, some local news hierarchies have policies that say ++what character set is the default. For instance, the @samp{fj} ++hierarchy uses @code{iso-2022-jp}. ++ ++@vindex gnus-group-charset-alist ++This knowledge is encoded in the @code{gnus-group-charset-alist} ++variable, which is an alist of regexps (use the first item to match full ++group names) and default charsets to be used when reading these groups. ++ ++@vindex gnus-newsgroup-ignored-charsets ++In addition, some people do use soi-disant @acronym{MIME}-aware agents that ++aren't. These blithely mark messages as being in @code{iso-8859-1} ++even if they really are in @code{koi-8}. To help here, the ++@code{gnus-newsgroup-ignored-charsets} variable can be used. The ++charsets that are listed here will be ignored. The variable can be ++set on a group-by-group basis using the group parameters (@pxref{Group ++Parameters}). The default value is @code{(unknown-8bit x-unknown)}, ++which includes values some agents insist on having in there. ++ ++@vindex gnus-group-posting-charset-alist ++When posting, @code{gnus-group-posting-charset-alist} is used to ++determine which charsets should not be encoded using the @acronym{MIME} ++encodings. For instance, some hierarchies discourage using ++quoted-printable header encoding. ++ ++This variable is an alist of regexps and permitted unencoded charsets ++for posting. Each element of the alist has the form @code{(}@var{test ++header body-list}@code{)}, where: ++ ++@table @var ++@item test ++is either a regular expression matching the newsgroup header or a ++variable to query, ++@item header ++is the charset which may be left unencoded in the header (@code{nil} ++means encode all charsets), ++@item body-list ++is a list of charsets which may be encoded using 8bit content-transfer ++encoding in the body, or one of the special values @code{nil} (always ++encode using quoted-printable) or @code{t} (always use 8bit). ++@end table ++ ++@cindex Russian ++@cindex koi8-r ++@cindex koi8-u ++@cindex iso-8859-5 ++@cindex coding system aliases ++@cindex preferred charset ++ ++@xref{Encoding Customization, , Encoding Customization, emacs-mime, ++The Emacs MIME Manual}, for additional variables that control which ++MIME charsets are used when sending messages. ++ ++Other charset tricks that may be useful, although not Gnus-specific: ++ ++If there are several @acronym{MIME} charsets that encode the same Emacs ++charset, you can choose what charset to use by saying the following: ++ ++@lisp ++(put-charset-property 'cyrillic-iso8859-5 ++ 'preferred-coding-system 'koi8-r) ++@end lisp ++ ++This means that Russian will be encoded using @code{koi8-r} instead of ++the default @code{iso-8859-5} @acronym{MIME} charset. ++ ++If you want to read messages in @code{koi8-u}, you can cheat and say ++ ++@lisp ++(define-coding-system-alias 'koi8-u 'koi8-r) ++@end lisp ++ ++This will almost do the right thing. ++ ++And finally, to read charsets like @code{windows-1251}, you can say ++something like ++ ++@lisp ++(codepage-setup 1251) ++(define-coding-system-alias 'windows-1251 'cp1251) ++@end lisp ++ ++ ++@node Article Commands ++@section Article Commands ++ ++@table @kbd ++ ++@item A P ++@cindex PostScript ++@cindex printing ++@kindex A P (Summary) ++@vindex gnus-ps-print-hook ++@findex gnus-summary-print-article ++Generate and print a PostScript image of the article buffer ++(@code{gnus-summary-print-article}). @code{gnus-ps-print-hook} will ++be run just before printing the buffer. An alternative way to print ++article is to use Muttprint (@pxref{Saving Articles}). ++ ++@end table ++ ++ ++@node Summary Sorting ++@section Summary Sorting ++@cindex summary sorting ++ ++You can have the summary buffer sorted in various ways, even though I ++can't really see why you'd want that. ++ ++@table @kbd ++ ++@item C-c C-s C-n ++@kindex C-c C-s C-n (Summary) ++@findex gnus-summary-sort-by-number ++Sort by article number (@code{gnus-summary-sort-by-number}). ++ ++@item C-c C-s C-m C-n ++@kindex C-c C-s C-n (Summary) ++@findex gnus-summary-sort-by-most-recent-number ++Sort by most recent article number ++(@code{gnus-summary-sort-by-most-recent-number}). ++ ++@item C-c C-s C-a ++@kindex C-c C-s C-a (Summary) ++@findex gnus-summary-sort-by-author ++Sort by author (@code{gnus-summary-sort-by-author}). ++ ++@item C-c C-s C-t ++@kindex C-c C-s C-t (Summary) ++@findex gnus-summary-sort-by-recipient ++Sort by recipient (@code{gnus-summary-sort-by-recipient}). ++ ++@item C-c C-s C-s ++@kindex C-c C-s C-s (Summary) ++@findex gnus-summary-sort-by-subject ++Sort by subject (@code{gnus-summary-sort-by-subject}). ++ ++@item C-c C-s C-d ++@kindex C-c C-s C-d (Summary) ++@findex gnus-summary-sort-by-date ++Sort by date (@code{gnus-summary-sort-by-date}). ++ ++@item C-c C-s C-m C-d ++@kindex C-c C-s C-m C-d (Summary) ++@findex gnus-summary-sort-by-most-recent-date ++Sort by most recent date (@code{gnus-summary-sort-by-most-recent-date}). ++ ++@item C-c C-s C-l ++@kindex C-c C-s C-l (Summary) ++@findex gnus-summary-sort-by-lines ++Sort by lines (@code{gnus-summary-sort-by-lines}). ++ ++@item C-c C-s C-c ++@kindex C-c C-s C-c (Summary) ++@findex gnus-summary-sort-by-chars ++Sort by article length (@code{gnus-summary-sort-by-chars}). ++ ++@item C-c C-s C-i ++@kindex C-c C-s C-i (Summary) ++@findex gnus-summary-sort-by-score ++Sort by score (@code{gnus-summary-sort-by-score}). ++ ++@item C-c C-s C-r ++@kindex C-c C-s C-r (Summary) ++@findex gnus-summary-sort-by-random ++Randomize (@code{gnus-summary-sort-by-random}). ++ ++@item C-c C-s C-o ++@kindex C-c C-s C-o (Summary) ++@findex gnus-summary-sort-by-original ++Sort using the default sorting method ++(@code{gnus-summary-sort-by-original}). ++@end table ++ ++These functions will work both when you use threading and when you don't ++use threading. In the latter case, all summary lines will be sorted, ++line by line. In the former case, sorting will be done on a ++root-by-root basis, which might not be what you were looking for. To ++toggle whether to use threading, type @kbd{T T} (@pxref{Thread ++Commands}). ++ ++If a prefix argument if given, the sort order is reversed. ++ ++ ++@node Finding the Parent ++@section Finding the Parent ++@cindex parent articles ++@cindex referring articles ++ ++@table @kbd ++@item ^ ++@kindex ^ (Summary) ++@findex gnus-summary-refer-parent-article ++If you'd like to read the parent of the current article, and it is not ++displayed in the summary buffer, you might still be able to. That is, ++if the current group is fetched by @acronym{NNTP}, the parent hasn't expired ++and the @code{References} in the current article are not mangled, you ++can just press @kbd{^} or @kbd{A r} ++(@code{gnus-summary-refer-parent-article}). If everything goes well, ++you'll get the parent. If the parent is already displayed in the ++summary buffer, point will just move to this article. ++ ++If given a positive numerical prefix, fetch that many articles back into ++the ancestry. If given a negative numerical prefix, fetch just that ++ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the ++grandparent and the grandgrandparent of the current article. If you say ++@kbd{-3 ^}, Gnus will only fetch the grandgrandparent of the current ++article. ++ ++@item A R (Summary) ++@findex gnus-summary-refer-references ++@kindex A R (Summary) ++Fetch all articles mentioned in the @code{References} header of the ++article (@code{gnus-summary-refer-references}). ++ ++@item A T (Summary) ++@findex gnus-summary-refer-thread ++@kindex A T (Summary) ++Display the full thread where the current article appears ++(@code{gnus-summary-refer-thread}). This command has to fetch all the ++headers in the current group to work, so it usually takes a while. If ++you do it often, you may consider setting @code{gnus-fetch-old-headers} ++to @code{invisible} (@pxref{Filling In Threads}). This won't have any ++visible effects normally, but it'll make this command work a whole lot ++faster. Of course, it'll make group entry somewhat slow. ++ ++@vindex gnus-refer-thread-limit ++The @code{gnus-refer-thread-limit} variable says how many old (i. e., ++articles before the first displayed in the current group) headers to ++fetch when doing this command. The default is 200. If @code{t}, all ++the available headers will be fetched. This variable can be overridden ++by giving the @kbd{A T} command a numerical prefix. ++ ++@item M-^ (Summary) ++@findex gnus-summary-refer-article ++@kindex M-^ (Summary) ++@cindex Message-ID ++@cindex fetching by Message-ID ++You can also ask Gnus for an arbitrary article, no matter what group it ++belongs to. @kbd{M-^} (@code{gnus-summary-refer-article}) will ask you ++for a @code{Message-ID}, which is one of those long, hard-to-read ++thingies that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. ++You have to get it all exactly right. No fuzzy searches, I'm afraid. ++ ++Gnus looks for the @code{Message-ID} in the headers that have already ++been fetched, but also tries all the select methods specified by ++@code{gnus-refer-article-method} if it is not found. ++@end table ++ ++@vindex gnus-refer-article-method ++If the group you are reading is located on a back end that does not ++support fetching by @code{Message-ID} very well (like @code{nnspool}), ++you can set @code{gnus-refer-article-method} to an @acronym{NNTP} method. It ++would, perhaps, be best if the @acronym{NNTP} server you consult is the one ++updating the spool you are reading from, but that's not really ++necessary. ++ ++It can also be a list of select methods, as well as the special symbol ++@code{current}, which means to use the current select method. If it ++is a list, Gnus will try all the methods in the list until it finds a ++match. ++ ++Here's an example setting that will first try the current method, and ++then ask Google if that fails: ++ ++@lisp ++(setq gnus-refer-article-method ++ '(current ++ (nnweb "google" (nnweb-type google)))) ++@end lisp ++ ++Most of the mail back ends support fetching by @code{Message-ID}, but ++do not do a particularly excellent job at it. That is, @code{nnmbox}, ++@code{nnbabyl}, @code{nnmaildir}, @code{nnml}, are able to locate ++articles from any groups, while @code{nnfolder}, and @code{nnimap} are ++only able to locate articles that have been posted to the current ++group. (Anything else would be too time consuming.) @code{nnmh} does ++not support this at all. ++ ++ ++@node Alternative Approaches ++@section Alternative Approaches ++ ++Different people like to read news using different methods. This being ++Gnus, we offer a small selection of minor modes for the summary buffers. ++ ++@menu ++* Pick and Read:: First mark articles and then read them. ++* Binary Groups:: Auto-decode all articles. ++@end menu ++ ++ ++@node Pick and Read ++@subsection Pick and Read ++@cindex pick and read ++ ++Some newsreaders (like @code{nn} and, uhm, @code{Netnews} on VM/CMS) use ++a two-phased reading interface. The user first marks in a summary ++buffer the articles she wants to read. Then she starts reading the ++articles with just an article buffer displayed. ++ ++@findex gnus-pick-mode ++@kindex M-x gnus-pick-mode ++Gnus provides a summary buffer minor mode that allows ++this---@code{gnus-pick-mode}. This basically means that a few process ++mark commands become one-keystroke commands to allow easy marking, and ++it provides one additional command for switching to the summary buffer. ++ ++Here are the available keystrokes when using pick mode: ++ ++@table @kbd ++@item . ++@kindex . (Pick) ++@findex gnus-pick-article-or-thread ++Pick the article or thread on the current line ++(@code{gnus-pick-article-or-thread}). If the variable ++@code{gnus-thread-hide-subtree} is true, then this key selects the ++entire thread when used at the first article of the thread. Otherwise, ++it selects just the article. If given a numerical prefix, go to that ++thread or article and pick it. (The line number is normally displayed ++at the beginning of the summary pick lines.) ++ ++@item SPACE ++@kindex SPACE (Pick) ++@findex gnus-pick-next-page ++Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If ++at the end of the buffer, start reading the picked articles. ++ ++@item u ++@kindex u (Pick) ++@findex gnus-pick-unmark-article-or-thread. ++Unpick the thread or article ++(@code{gnus-pick-unmark-article-or-thread}). If the variable ++@code{gnus-thread-hide-subtree} is true, then this key unpicks the ++thread if used at the first article of the thread. Otherwise it unpicks ++just the article. You can give this key a numerical prefix to unpick ++the thread or article at that line. ++ ++@item RET ++@kindex RET (Pick) ++@findex gnus-pick-start-reading ++@vindex gnus-pick-display-summary ++Start reading the picked articles (@code{gnus-pick-start-reading}). If ++given a prefix, mark all unpicked articles as read first. If ++@code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer ++will still be visible when you are reading. ++ ++@end table ++ ++All the normal summary mode commands are still available in the ++pick-mode, with the exception of @kbd{u}. However @kbd{!} is available ++which is mapped to the same function ++@code{gnus-summary-tick-article-forward}. ++ ++If this sounds like a good idea to you, you could say: ++ ++@lisp ++(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) ++@end lisp ++ ++@vindex gnus-pick-mode-hook ++@code{gnus-pick-mode-hook} is run in pick minor mode buffers. ++ ++@vindex gnus-mark-unpicked-articles-as-read ++If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark ++all unpicked articles as read. The default is @code{nil}. ++ ++@vindex gnus-summary-pick-line-format ++The summary line format in pick mode is slightly different from the ++standard format. At the beginning of each line the line number is ++displayed. The pick mode line format is controlled by the ++@code{gnus-summary-pick-line-format} variable (@pxref{Formatting ++Variables}). It accepts the same format specs that ++@code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}). ++ ++ ++@node Binary Groups ++@subsection Binary Groups ++@cindex binary groups ++ ++@findex gnus-binary-mode ++@kindex M-x gnus-binary-mode ++If you spend much time in binary groups, you may grow tired of hitting ++@kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode} ++is a minor mode for summary buffers that makes all ordinary Gnus article ++selection functions uudecode series of articles and display the result ++instead of just displaying the articles the normal way. ++ ++@kindex g (Binary) ++@findex gnus-binary-show-article ++The only way, in fact, to see the actual articles is the @kbd{g} ++command, when you have turned on this mode ++(@code{gnus-binary-show-article}). ++ ++@vindex gnus-binary-mode-hook ++@code{gnus-binary-mode-hook} is called in binary minor mode buffers. ++ ++ ++@node Tree Display ++@section Tree Display ++@cindex trees ++ ++@vindex gnus-use-trees ++If you don't like the normal Gnus summary display, you might try setting ++@code{gnus-use-trees} to @code{t}. This will create (by default) an ++additional @dfn{tree buffer}. You can execute all summary mode commands ++in the tree buffer. ++ ++There are a few variables to customize the tree display, of course: ++ ++@table @code ++@item gnus-tree-mode-hook ++@vindex gnus-tree-mode-hook ++A hook called in all tree mode buffers. ++ ++@item gnus-tree-mode-line-format ++@vindex gnus-tree-mode-line-format ++A format string for the mode bar in the tree mode buffers (@pxref{Mode ++Line Formatting}). The default is @samp{Gnus: %%b %S %Z}. For a list ++of valid specs, @pxref{Summary Buffer Mode Line}. ++ ++@item gnus-selected-tree-face ++@vindex gnus-selected-tree-face ++Face used for highlighting the selected article in the tree buffer. The ++default is @code{modeline}. ++ ++@item gnus-tree-line-format ++@vindex gnus-tree-line-format ++A format string for the tree nodes. The name is a bit of a misnomer, ++though---it doesn't define a line, but just the node. The default value ++is @samp{%(%[%3,3n%]%)}, which displays the first three characters of ++the name of the poster. It is vital that all nodes are of the same ++length, so you @emph{must} use @samp{%4,4n}-like specifiers. ++ ++Valid specs are: ++ ++@table @samp ++@item n ++The name of the poster. ++@item f ++The @code{From} header. ++@item N ++The number of the article. ++@item [ ++The opening bracket. ++@item ] ++The closing bracket. ++@item s ++The subject. ++@end table ++ ++@xref{Formatting Variables}. ++ ++Variables related to the display are: ++ ++@table @code ++@item gnus-tree-brackets ++@vindex gnus-tree-brackets ++This is used for differentiating between ``real'' articles and ++``sparse'' articles. The format is ++@example ++((@var{real-open} . @var{real-close}) ++ (@var{sparse-open} . @var{sparse-close}) ++ (@var{dummy-open} . @var{dummy-close})) ++@end example ++and the default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}. ++ ++@item gnus-tree-parent-child-edges ++@vindex gnus-tree-parent-child-edges ++This is a list that contains the characters used for connecting parent ++nodes to their children. The default is @code{(?- ?\\ ?|)}. ++ ++@end table ++ ++@item gnus-tree-minimize-window ++@vindex gnus-tree-minimize-window ++If this variable is non-@code{nil}, Gnus will try to keep the tree ++buffer as small as possible to allow more room for the other Gnus ++windows. If this variable is a number, the tree buffer will never be ++higher than that number. The default is @code{t}. Note that if you ++have several windows displayed side-by-side in a frame and the tree ++buffer is one of these, minimizing the tree window will also resize all ++other windows displayed next to it. ++ ++You may also wish to add the following hook to keep the window minimized ++at all times: ++ ++@lisp ++(add-hook 'gnus-configure-windows-hook ++ 'gnus-tree-perhaps-minimize) ++@end lisp ++ ++@item gnus-generate-tree-function ++@vindex gnus-generate-tree-function ++@findex gnus-generate-horizontal-tree ++@findex gnus-generate-vertical-tree ++The function that actually generates the thread tree. Two predefined ++functions are available: @code{gnus-generate-horizontal-tree} and ++@code{gnus-generate-vertical-tree} (which is the default). ++ ++@end table ++ ++Here's an example from a horizontal tree buffer: ++ ++@example ++@{***@}-(***)-[odd]-[Gun] ++ | \[Jan] ++ | \[odd]-[Eri] ++ | \(***)-[Eri] ++ | \[odd]-[Paa] ++ \[Bjo] ++ \[Gun] ++ \[Gun]-[Jor] ++@end example ++ ++Here's the same thread displayed in a vertical tree buffer: ++ ++@example ++@group ++@{***@} ++ |--------------------------\-----\-----\ ++(***) [Bjo] [Gun] [Gun] ++ |--\-----\-----\ | ++[odd] [Jan] [odd] (***) [Jor] ++ | | |--\ ++[Gun] [Eri] [Eri] [odd] ++ | ++ [Paa] ++@end group ++@end example ++ ++If you're using horizontal trees, it might be nice to display the trees ++side-by-side with the summary buffer. You could add something like the ++following to your @file{~/.gnus.el} file: ++ ++@lisp ++(setq gnus-use-trees t ++ gnus-generate-tree-function 'gnus-generate-horizontal-tree ++ gnus-tree-minimize-window nil) ++(gnus-add-configuration ++ '(article ++ (vertical 1.0 ++ (horizontal 0.25 ++ (summary 0.75 point) ++ (tree 1.0)) ++ (article 1.0)))) ++@end lisp ++ ++@xref{Window Layout}. ++ ++ ++@node Mail Group Commands ++@section Mail Group Commands ++@cindex mail group commands ++ ++Some commands only make sense in mail groups. If these commands are ++invalid in the current group, they will raise a hell and let you know. ++ ++All these commands (except the expiry and edit commands) use the ++process/prefix convention (@pxref{Process/Prefix}). ++ ++@table @kbd ++ ++@item B e ++@kindex B e (Summary) ++@findex gnus-summary-expire-articles ++@cindex expiring mail ++Run all expirable articles in the current group through the expiry ++process (@code{gnus-summary-expire-articles}). That is, delete all ++expirable articles in the group that have been around for a while. ++(@pxref{Expiring Mail}). ++ ++@item B C-M-e ++@kindex B C-M-e (Summary) ++@findex gnus-summary-expire-articles-now ++@cindex expiring mail ++Delete all the expirable articles in the group ++(@code{gnus-summary-expire-articles-now}). This means that @strong{all} ++articles eligible for expiry in the current group will ++disappear forever into that big @file{/dev/null} in the sky. ++ ++@item B DEL ++@kindex B DEL (Summary) ++@findex gnus-summary-delete-article ++@c @icon{gnus-summary-mail-delete} ++Delete the mail article. This is ``delete'' as in ``delete it from your ++disk forever and ever, never to return again.'' Use with caution. ++(@code{gnus-summary-delete-article}). ++ ++@item B m ++@kindex B m (Summary) ++@cindex move mail ++@findex gnus-summary-move-article ++@vindex gnus-preserve-marks ++Move the article from one mail group to another ++(@code{gnus-summary-move-article}). Marks will be preserved if ++@code{gnus-preserve-marks} is non-@code{nil} (which is the default). ++ ++@item B c ++@kindex B c (Summary) ++@cindex copy mail ++@findex gnus-summary-copy-article ++@c @icon{gnus-summary-mail-copy} ++Copy the article from one group (mail group or not) to a mail group ++(@code{gnus-summary-copy-article}). Marks will be preserved if ++@code{gnus-preserve-marks} is non-@code{nil} (which is the default). ++ ++@item B B ++@kindex B B (Summary) ++@cindex crosspost mail ++@findex gnus-summary-crosspost-article ++Crosspost the current article to some other group ++(@code{gnus-summary-crosspost-article}). This will create a new copy of ++the article in the other group, and the Xref headers of the article will ++be properly updated. ++ ++@item B i ++@kindex B i (Summary) ++@findex gnus-summary-import-article ++Import an arbitrary file into the current mail newsgroup ++(@code{gnus-summary-import-article}). You will be prompted for a file ++name, a @code{From} header and a @code{Subject} header. ++ ++@item B I ++@kindex B I (Summary) ++@findex gnus-summary-create-article ++Create an empty article in the current mail newsgroups ++(@code{gnus-summary-create-article}). You will be prompted for a ++@code{From} header and a @code{Subject} header. ++ ++@item B r ++@kindex B r (Summary) ++@findex gnus-summary-respool-article ++@vindex gnus-summary-respool-default-method ++Respool the mail article (@code{gnus-summary-respool-article}). ++@code{gnus-summary-respool-default-method} will be used as the default ++select method when respooling. This variable is @code{nil} by default, ++which means that the current group select method will be used instead. ++Marks will be preserved if @code{gnus-preserve-marks} is non-@code{nil} ++(which is the default). ++ ++@item B w ++@itemx e ++@kindex B w (Summary) ++@kindex e (Summary) ++@findex gnus-summary-edit-article ++@kindex C-c C-c (Article) ++@findex gnus-summary-edit-article-done ++Edit the current article (@code{gnus-summary-edit-article}). To finish ++editing and make the changes permanent, type @kbd{C-c C-c} ++(@code{gnus-summary-edit-article-done}). If you give a prefix to the ++@kbd{C-c C-c} command, Gnus won't re-highlight the article. ++ ++@item B q ++@kindex B q (Summary) ++@findex gnus-summary-respool-query ++If you want to re-spool an article, you might be curious as to what group ++the article will end up in before you do the re-spooling. This command ++will tell you (@code{gnus-summary-respool-query}). ++ ++@item B t ++@kindex B t (Summary) ++@findex gnus-summary-respool-trace ++Similarly, this command will display all fancy splitting patterns used ++when respooling, if any (@code{gnus-summary-respool-trace}). ++ ++@item B p ++@kindex B p (Summary) ++@findex gnus-summary-article-posted-p ++Some people have a tendency to send you ``courtesy'' copies when they ++follow up to articles you have posted. These usually have a ++@code{Newsgroups} header in them, but not always. This command ++(@code{gnus-summary-article-posted-p}) will try to fetch the current ++article from your news server (or rather, from ++@code{gnus-refer-article-method} or @code{gnus-select-method}) and will ++report back whether it found the article or not. Even if it says that ++it didn't find the article, it may have been posted anyway---mail ++propagation is much faster than news propagation, and the news copy may ++just not have arrived yet. ++ ++@item K E ++@kindex K E (Summary) ++@findex gnus-article-encrypt-body ++@vindex gnus-article-encrypt-protocol ++Encrypt the body of an article (@code{gnus-article-encrypt-body}). ++The body is encrypted with the encryption protocol specified by the ++variable @code{gnus-article-encrypt-protocol}. ++ ++@end table ++ ++@vindex gnus-move-split-methods ++@cindex moving articles ++If you move (or copy) articles regularly, you might wish to have Gnus ++suggest where to put the articles. @code{gnus-move-split-methods} is a ++variable that uses the same syntax as @code{gnus-split-methods} ++(@pxref{Saving Articles}). You may customize that variable to create ++suggestions you find reasonable. (Note that ++@code{gnus-move-split-methods} uses group names where ++@code{gnus-split-methods} uses file names.) ++ ++@lisp ++(setq gnus-move-split-methods ++ '(("^From:.*Lars Magne" "nnml:junk") ++ ("^Subject:.*gnus" "nnfolder:important") ++ (".*" "nnml:misc"))) ++@end lisp ++ ++ ++@node Various Summary Stuff ++@section Various Summary Stuff ++ ++@menu ++* Summary Group Information:: Information oriented commands. ++* Searching for Articles:: Multiple article commands. ++* Summary Generation Commands:: ++* Really Various Summary Commands:: Those pesky non-conformant commands. ++@end menu ++ ++@table @code ++@vindex gnus-summary-display-while-building ++@item gnus-summary-display-while-building ++If non-@code{nil}, show and update the summary buffer as it's being ++built. If @code{t}, update the buffer after every line is inserted. ++If the value is an integer, @var{n}, update the display every @var{n} ++lines. The default is @code{nil}. ++ ++@vindex gnus-summary-display-arrow ++@item gnus-summary-display-arrow ++If non-@code{nil}, display an arrow in the fringe to indicate the ++current article. ++ ++@vindex gnus-summary-mode-hook ++@item gnus-summary-mode-hook ++This hook is called when creating a summary mode buffer. ++ ++@vindex gnus-summary-generate-hook ++@item gnus-summary-generate-hook ++This is called as the last thing before doing the threading and the ++generation of the summary buffer. It's quite convenient for customizing ++the threading variables based on what data the newsgroup has. This hook ++is called from the summary buffer after most summary buffer variables ++have been set. ++ ++@vindex gnus-summary-prepare-hook ++@item gnus-summary-prepare-hook ++It is called after the summary buffer has been generated. You might use ++it to, for instance, highlight lines or modify the look of the buffer in ++some other ungodly manner. I don't care. ++ ++@vindex gnus-summary-prepared-hook ++@item gnus-summary-prepared-hook ++A hook called as the very last thing after the summary buffer has been ++generated. ++ ++@vindex gnus-summary-ignore-duplicates ++@item gnus-summary-ignore-duplicates ++When Gnus discovers two articles that have the same @code{Message-ID}, ++it has to do something drastic. No articles are allowed to have the ++same @code{Message-ID}, but this may happen when reading mail from some ++sources. Gnus allows you to customize what happens with this variable. ++If it is @code{nil} (which is the default), Gnus will rename the ++@code{Message-ID} (for display purposes only) and display the article as ++any other article. If this variable is @code{t}, it won't display the ++article---it'll be as if it never existed. ++ ++@vindex gnus-alter-articles-to-read-function ++@item gnus-alter-articles-to-read-function ++This function, which takes two parameters (the group name and the list ++of articles to be selected), is called to allow the user to alter the ++list of articles to be selected. ++ ++For instance, the following function adds the list of cached articles to ++the list in one particular group: ++ ++@lisp ++(defun my-add-cached-articles (group articles) ++ (if (string= group "some.group") ++ (append gnus-newsgroup-cached articles) ++ articles)) ++@end lisp ++ ++@vindex gnus-newsgroup-variables ++@item gnus-newsgroup-variables ++A list of newsgroup (summary buffer) local variables, or cons of ++variables and their default expressions to be evalled (when the default ++values are not @code{nil}), that should be made global while the summary ++buffer is active. ++ ++Note: The default expressions will be evaluated (using function ++@code{eval}) before assignment to the local variable rather than just ++assigned to it. If the default expression is the symbol @code{global}, ++that symbol will not be evaluated but the global value of the local ++variable will be used instead. ++ ++These variables can be used to set variables in the group parameters ++while still allowing them to affect operations done in other ++buffers. For example: ++ ++@lisp ++(setq gnus-newsgroup-variables ++ '(message-use-followup-to ++ (gnus-visible-headers . ++ "^From:\\|^Newsgroups:\\|^Subject:\\|^Date:\\|^To:"))) ++@end lisp ++ ++Also @pxref{Group Parameters}. ++ ++@vindex gnus-propagate-marks ++@item gnus-propagate-marks ++If non-@code{nil}, propagate marks to the backends for possible ++storing. @xref{NNTP marks}, and friends, for a more fine-grained ++sieve. ++ ++@end table ++ ++ ++@node Summary Group Information ++@subsection Summary Group Information ++ ++@table @kbd ++ ++@item H f ++@kindex H f (Summary) ++@findex gnus-summary-fetch-faq ++@vindex gnus-group-faq-directory ++Try to fetch the @acronym{FAQ} (list of frequently asked questions) ++for the current group (@code{gnus-summary-fetch-faq}). Gnus will try ++to get the @acronym{FAQ} from @code{gnus-group-faq-directory}, which ++is usually a directory on a remote machine. This variable can also be ++a list of directories. In that case, giving a prefix to this command ++will allow you to choose between the various sites. @code{ange-ftp} ++or @code{efs} will probably be used for fetching the file. ++ ++@item H d ++@kindex H d (Summary) ++@findex gnus-summary-describe-group ++Give a brief description of the current group ++(@code{gnus-summary-describe-group}). If given a prefix, force ++rereading the description from the server. ++ ++@item H h ++@kindex H h (Summary) ++@findex gnus-summary-describe-briefly ++Give an extremely brief description of the most important summary ++keystrokes (@code{gnus-summary-describe-briefly}). ++ ++@item H i ++@kindex H i (Summary) ++@findex gnus-info-find-node ++Go to the Gnus info node (@code{gnus-info-find-node}). ++@end table ++ ++ ++@node Searching for Articles ++@subsection Searching for Articles ++ ++@table @kbd ++ ++@item M-s ++@kindex M-s (Summary) ++@findex gnus-summary-search-article-forward ++Search through all subsequent (raw) articles for a regexp ++(@code{gnus-summary-search-article-forward}). ++ ++@item M-r ++@kindex M-r (Summary) ++@findex gnus-summary-search-article-backward ++Search through all previous (raw) articles for a regexp ++(@code{gnus-summary-search-article-backward}). ++ ++@item M-S ++@kindex M-S (Summary) ++@findex gnus-summary-repeat-search-article-forward ++Repeat the previous search forwards ++(@code{gnus-summary-repeat-search-article-forward}). ++ ++@item M-R ++@kindex M-R (Summary) ++@findex gnus-summary-repeat-search-article-backward ++Repeat the previous search backwards ++(@code{gnus-summary-repeat-search-article-backward}). ++ ++@item & ++@kindex & (Summary) ++@findex gnus-summary-execute-command ++This command will prompt you for a header, a regular expression to match ++on this field, and a command to be executed if the match is made ++(@code{gnus-summary-execute-command}). If the header is an empty ++string, the match is done on the entire article. If given a prefix, ++search backward instead. ++ ++For instance, @kbd{& RET some.*string RET #} will put the process mark on ++all articles that have heads or bodies that match @samp{some.*string}. ++ ++@item M-& ++@kindex M-& (Summary) ++@findex gnus-summary-universal-argument ++Perform any operation on all articles that have been marked with ++the process mark (@code{gnus-summary-universal-argument}). ++@end table ++ ++@node Summary Generation Commands ++@subsection Summary Generation Commands ++ ++@table @kbd ++ ++@item Y g ++@kindex Y g (Summary) ++@findex gnus-summary-prepare ++Regenerate the current summary buffer (@code{gnus-summary-prepare}). ++ ++@item Y c ++@kindex Y c (Summary) ++@findex gnus-summary-insert-cached-articles ++Pull all cached articles (for the current group) into the summary buffer ++(@code{gnus-summary-insert-cached-articles}). ++ ++@item Y d ++@kindex Y d (Summary) ++@findex gnus-summary-insert-dormant-articles ++Pull all dormant articles (for the current group) into the summary buffer ++(@code{gnus-summary-insert-dormant-articles}). ++ ++@item Y t ++@kindex Y t (Summary) ++@findex gnus-summary-insert-ticked-articles ++Pull all ticked articles (for the current group) into the summary buffer ++(@code{gnus-summary-insert-ticked-articles}). ++ ++@end table ++ ++ ++@node Really Various Summary Commands ++@subsection Really Various Summary Commands ++ ++@table @kbd ++ ++@item A D ++@itemx C-d ++@kindex C-d (Summary) ++@kindex A D (Summary) ++@findex gnus-summary-enter-digest-group ++If the current article is a collection of other articles (for instance, ++a digest), you might use this command to enter a group based on the that ++article (@code{gnus-summary-enter-digest-group}). Gnus will try to ++guess what article type is currently displayed unless you give a prefix ++to this command, which forces a ``digest'' interpretation. Basically, ++whenever you see a message that is a collection of other messages of ++some format, you @kbd{C-d} and read these messages in a more convenient ++fashion. ++ ++@vindex gnus-auto-select-on-ephemeral-exit ++The variable @code{gnus-auto-select-on-ephemeral-exit} controls what ++article should be selected after exiting a digest group. Valid values ++include: ++ ++@table @code ++@item next ++Select the next article. ++ ++@item next-unread ++Select the next unread article. ++ ++@item next-noselect ++Move the cursor to the next article. This is the default. ++ ++@item next-unread-noselect ++Move the cursor to the next unread article. ++@end table ++ ++If it has any other value or there is no next (unread) article, the ++article selected before entering to the digest group will appear. ++ ++@item C-M-d ++@kindex C-M-d (Summary) ++@findex gnus-summary-read-document ++This command is very similar to the one above, but lets you gather ++several documents into one biiig group ++(@code{gnus-summary-read-document}). It does this by opening several ++@code{nndoc} groups for each document, and then opening an ++@code{nnvirtual} group on top of these @code{nndoc} groups. This ++command understands the process/prefix convention ++(@pxref{Process/Prefix}). ++ ++@item C-t ++@kindex C-t (Summary) ++@findex gnus-summary-toggle-truncation ++Toggle truncation of summary lines ++(@code{gnus-summary-toggle-truncation}). This will probably confuse the ++line centering function in the summary buffer, so it's not a good idea ++to have truncation switched off while reading articles. ++ ++@item = ++@kindex = (Summary) ++@findex gnus-summary-expand-window ++Expand the summary buffer window (@code{gnus-summary-expand-window}). ++If given a prefix, force an @code{article} window configuration. ++ ++@item C-M-e ++@kindex C-M-e (Summary) ++@findex gnus-summary-edit-parameters ++Edit the group parameters (@pxref{Group Parameters}) of the current ++group (@code{gnus-summary-edit-parameters}). ++ ++@item C-M-a ++@kindex C-M-a (Summary) ++@findex gnus-summary-customize-parameters ++Customize the group parameters (@pxref{Group Parameters}) of the current ++group (@code{gnus-summary-customize-parameters}). ++ ++@end table ++ ++ ++@node Exiting the Summary Buffer ++@section Exiting the Summary Buffer ++@cindex summary exit ++@cindex exiting groups ++ ++Exiting from the summary buffer will normally update all info on the ++group and return you to the group buffer. ++ ++@table @kbd ++ ++@item Z Z ++@itemx Z Q ++@itemx q ++@kindex Z Z (Summary) ++@kindex Z Q (Summary) ++@kindex q (Summary) ++@findex gnus-summary-exit ++@vindex gnus-summary-exit-hook ++@vindex gnus-summary-prepare-exit-hook ++@vindex gnus-group-no-more-groups-hook ++@c @icon{gnus-summary-exit} ++Exit the current group and update all information on the group ++(@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is ++called before doing much of the exiting, which calls ++@code{gnus-summary-expire-articles} by default. ++@code{gnus-summary-exit-hook} is called after finishing the exit ++process. @code{gnus-group-no-more-groups-hook} is run when returning to ++group mode having no more (unread) groups. ++ ++@item Z E ++@itemx Q ++@kindex Z E (Summary) ++@kindex Q (Summary) ++@findex gnus-summary-exit-no-update ++Exit the current group without updating any information on the group ++(@code{gnus-summary-exit-no-update}). ++ ++@item Z c ++@itemx c ++@kindex Z c (Summary) ++@kindex c (Summary) ++@findex gnus-summary-catchup-and-exit ++@c @icon{gnus-summary-catchup-and-exit} ++Mark all unticked articles in the group as read and then exit ++(@code{gnus-summary-catchup-and-exit}). ++ ++@item Z C ++@kindex Z C (Summary) ++@findex gnus-summary-catchup-all-and-exit ++Mark all articles, even the ticked ones, as read and then exit ++(@code{gnus-summary-catchup-all-and-exit}). ++ ++@item Z n ++@kindex Z n (Summary) ++@findex gnus-summary-catchup-and-goto-next-group ++Mark all articles as read and go to the next group ++(@code{gnus-summary-catchup-and-goto-next-group}). ++ ++@item Z p ++@kindex Z p (Summary) ++@findex gnus-summary-catchup-and-goto-prev-group ++Mark all articles as read and go to the previous group ++(@code{gnus-summary-catchup-and-goto-prev-group}). ++ ++@item Z R ++@itemx C-x C-s ++@kindex Z R (Summary) ++@kindex C-x C-s (Summary) ++@findex gnus-summary-reselect-current-group ++Exit this group, and then enter it again ++(@code{gnus-summary-reselect-current-group}). If given a prefix, select ++all articles, both read and unread. ++ ++@item Z G ++@itemx M-g ++@kindex Z G (Summary) ++@kindex M-g (Summary) ++@findex gnus-summary-rescan-group ++@c @icon{gnus-summary-mail-get} ++Exit the group, check for new articles in the group, and select the ++group (@code{gnus-summary-rescan-group}). If given a prefix, select all ++articles, both read and unread. ++ ++@item Z N ++@kindex Z N (Summary) ++@findex gnus-summary-next-group ++Exit the group and go to the next group ++(@code{gnus-summary-next-group}). ++ ++@item Z P ++@kindex Z P (Summary) ++@findex gnus-summary-prev-group ++Exit the group and go to the previous group ++(@code{gnus-summary-prev-group}). ++ ++@item Z s ++@kindex Z s (Summary) ++@findex gnus-summary-save-newsrc ++Save the current number of read/marked articles in the dribble buffer ++and then save the dribble buffer (@code{gnus-summary-save-newsrc}). If ++given a prefix, also save the @file{.newsrc} file(s). Using this ++command will make exit without updating (the @kbd{Q} command) worthless. ++@end table ++ ++@vindex gnus-exit-group-hook ++@code{gnus-exit-group-hook} is called when you exit the current group ++with an ``updating'' exit. For instance @kbd{Q} ++(@code{gnus-summary-exit-no-update}) does not call this hook. ++ ++@findex gnus-summary-wake-up-the-dead ++@findex gnus-dead-summary-mode ++@vindex gnus-kill-summary-on-exit ++If you're in the habit of exiting groups, and then changing your mind ++about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}. ++If you do that, Gnus won't kill the summary buffer when you exit it. ++(Quelle surprise!) Instead it will change the name of the buffer to ++something like @samp{*Dead Summary ... *} and install a minor mode ++called @code{gnus-dead-summary-mode}. Now, if you switch back to this ++buffer, you'll find that all keys are mapped to a function called ++@code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead ++summary buffer will result in a live, normal summary buffer. ++ ++There will never be more than one dead summary buffer at any one time. ++ ++@vindex gnus-use-cross-reference ++The data on the current group will be updated (which articles you have ++read, which articles you have replied to, etc.) when you exit the ++summary buffer. If the @code{gnus-use-cross-reference} variable is ++@code{t} (which is the default), articles that are cross-referenced to ++this group and are marked as read, will also be marked as read in the ++other subscribed groups they were cross-posted to. If this variable is ++neither @code{nil} nor @code{t}, the article will be marked as read in ++both subscribed and unsubscribed groups (@pxref{Crosspost Handling}). ++ ++ ++@node Crosspost Handling ++@section Crosspost Handling ++ ++@cindex velveeta ++@cindex spamming ++Marking cross-posted articles as read ensures that you'll never have to ++read the same article more than once. Unless, of course, somebody has ++posted it to several groups separately. Posting the same article to ++several groups (not cross-posting) is called @dfn{spamming}, and you are ++by law required to send nasty-grams to anyone who perpetrates such a ++heinous crime. You may want to try NoCeM handling to filter out spam ++(@pxref{NoCeM}). ++ ++Remember: Cross-posting is kinda ok, but posting the same article ++separately to several groups is not. Massive cross-posting (aka. ++@dfn{velveeta}) is to be avoided at all costs, and you can even use the ++@code{gnus-summary-mail-crosspost-complaint} command to complain about ++excessive crossposting (@pxref{Summary Mail Commands}). ++ ++@cindex cross-posting ++@cindex Xref ++@cindex @acronym{NOV} ++One thing that may cause Gnus to not do the cross-posting thing ++correctly is if you use an @acronym{NNTP} server that supports @sc{xover} ++(which is very nice, because it speeds things up considerably) which ++does not include the @code{Xref} header in its @acronym{NOV} lines. This is ++Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing ++even with @sc{xover} by registering the @code{Xref} lines of all ++articles you actually read, but if you kill the articles, or just mark ++them as read without reading them, Gnus will not get a chance to snoop ++the @code{Xref} lines out of these articles, and will be unable to use ++the cross reference mechanism. ++ ++@cindex LIST overview.fmt ++@cindex overview.fmt ++To check whether your @acronym{NNTP} server includes the @code{Xref} header ++in its overview files, try @samp{telnet your.nntp.server nntp}, ++@samp{MODE READER} on @code{inn} servers, and then say @samp{LIST ++overview.fmt}. This may not work, but if it does, and the last line you ++get does not read @samp{Xref:full}, then you should shout and whine at ++your news admin until she includes the @code{Xref} header in the ++overview files. ++ ++If you want Gnus to get the @code{Xref}s right all the time, you have to ++set @code{nntp-nov-is-evil} to @code{t}, which slows things down ++considerably. Also @pxref{Slow/Expensive Connection}. ++ ++C'est la vie. ++ ++For an alternative approach, @pxref{Duplicate Suppression}. ++ ++ ++@node Duplicate Suppression ++@section Duplicate Suppression ++ ++By default, Gnus tries to make sure that you don't have to read the same ++article more than once by utilizing the crossposting mechanism ++(@pxref{Crosspost Handling}). However, that simple and efficient ++approach may not work satisfactory for some users for various ++reasons. ++ ++@enumerate ++@item ++The @acronym{NNTP} server may fail to generate the @code{Xref} header. This ++is evil and not very common. ++ ++@item ++The @acronym{NNTP} server may fail to include the @code{Xref} header in the ++@file{.overview} data bases. This is evil and all too common, alas. ++ ++@item ++You may be reading the same group (or several related groups) from ++different @acronym{NNTP} servers. ++ ++@item ++You may be getting mail that duplicates articles posted to groups. ++@end enumerate ++ ++I'm sure there are other situations where @code{Xref} handling fails as ++well, but these four are the most common situations. ++ ++If, and only if, @code{Xref} handling fails for you, then you may ++consider switching on @dfn{duplicate suppression}. If you do so, Gnus ++will remember the @code{Message-ID}s of all articles you have read or ++otherwise marked as read, and then, as if by magic, mark them as read ++all subsequent times you see them---in @emph{all} groups. Using this ++mechanism is quite likely to be somewhat inefficient, but not overly ++so. It's certainly preferable to reading the same articles more than ++once. ++ ++Duplicate suppression is not a very subtle instrument. It's more like a ++sledge hammer than anything else. It works in a very simple ++fashion---if you have marked an article as read, it adds this Message-ID ++to a cache. The next time it sees this Message-ID, it will mark the ++article as read with the @samp{M} mark. It doesn't care what group it ++saw the article in. ++ ++@table @code ++@item gnus-suppress-duplicates ++@vindex gnus-suppress-duplicates ++If non-@code{nil}, suppress duplicates. ++ ++@item gnus-save-duplicate-list ++@vindex gnus-save-duplicate-list ++If non-@code{nil}, save the list of duplicates to a file. This will ++make startup and shutdown take longer, so the default is @code{nil}. ++However, this means that only duplicate articles read in a single Gnus ++session are suppressed. ++ ++@item gnus-duplicate-list-length ++@vindex gnus-duplicate-list-length ++This variable says how many @code{Message-ID}s to keep in the duplicate ++suppression list. The default is 10000. ++ ++@item gnus-duplicate-file ++@vindex gnus-duplicate-file ++The name of the file to store the duplicate suppression list in. The ++default is @file{~/News/suppression}. ++@end table ++ ++If you have a tendency to stop and start Gnus often, setting ++@code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If ++you leave Gnus running for weeks on end, you may have it @code{nil}. On ++the other hand, saving the list makes startup and shutdown much slower, ++so that means that if you stop and start Gnus often, you should set ++@code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up ++to you to figure out, I think. ++ ++@node Security ++@section Security ++ ++Gnus is able to verify signed messages or decrypt encrypted messages. ++The formats that are supported are @acronym{PGP}, @acronym{PGP/MIME} ++and @acronym{S/MIME}, however you need some external programs to get ++things to work: ++ ++@enumerate ++@item ++To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to ++install an OpenPGP implementation such as GnuPG. The Lisp interface ++to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG, ++epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg, ++PGG Manual}), Mailcrypt, and gpg.el are also supported. ++ ++@item ++To handle @acronym{S/MIME} message, you need to install OpenSSL. OpenSSL 0.9.6 ++or newer is recommended. ++ ++@end enumerate ++ ++The variables that control security functionality on reading messages ++include: ++ ++@table @code ++@item mm-verify-option ++@vindex mm-verify-option ++Option of verifying signed parts. @code{never}, not verify; ++@code{always}, always verify; @code{known}, only verify known ++protocols. Otherwise, ask user. ++ ++@item mm-decrypt-option ++@vindex mm-decrypt-option ++Option of decrypting encrypted parts. @code{never}, no decryption; ++@code{always}, always decrypt; @code{known}, only decrypt known ++protocols. Otherwise, ask user. ++ ++@item mml1991-use ++@vindex mml1991-use ++Symbol indicating elisp interface to OpenPGP implementation for ++@acronym{PGP} messages. The default is @code{epg}, but @code{pgg}, ++@code{mailcrypt}, and @code{gpg} are also supported although ++deprecated. By default, Gnus uses the first available interface in ++this order. ++ ++@item mml2015-use ++@vindex mml2015-use ++Symbol indicating elisp interface to OpenPGP implementation for ++@acronym{PGP/MIME} messages. The default is @code{epg}, but ++@code{pgg}, @code{mailcrypt}, and @code{gpg} are also supported ++although deprecated. By default, Gnus uses the first available ++interface in this order. ++ ++@end table ++ ++By default the buttons that display security information are not ++shown, because they clutter reading the actual e-mail. You can type ++@kbd{K b} manually to display the information. Use the ++@code{gnus-buttonized-mime-types} and ++@code{gnus-unbuttonized-mime-types} variables to control this ++permanently. @ref{MIME Commands} for further details, and hints on ++how to customize these variables to always display security ++information. ++ ++@cindex snarfing keys ++@cindex importing PGP keys ++@cindex PGP key ring import ++Snarfing OpenPGP keys (i.e., importing keys from articles into your ++key ring) is not supported explicitly through a menu item or command, ++rather Gnus do detect and label keys as @samp{application/pgp-keys}, ++allowing you to specify whatever action you think is appropriate ++through the usual @acronym{MIME} infrastructure. You can use a ++@file{~/.mailcap} entry (@pxref{mailcap, , mailcap, emacs-mime, The ++Emacs MIME Manual}) such as the following to import keys using GNU ++Privacy Guard when you click on the @acronym{MIME} button ++(@pxref{Using MIME}). ++ ++@example ++application/pgp-keys; gpg --import --interactive --verbose; needsterminal ++@end example ++@noindent ++This happens to also be the default action defined in ++@code{mailcap-mime-data}. ++ ++More information on how to set things for sending outgoing signed and ++encrypted messages up can be found in the message manual ++(@pxref{Security, ,Security, message, Message Manual}). ++ ++@node Mailing List ++@section Mailing List ++@cindex mailing list ++@cindex RFC 2396 ++ ++@kindex A M (summary) ++@findex gnus-mailing-list-insinuate ++Gnus understands some mailing list fields of RFC 2369. To enable it, ++add a @code{to-list} group parameter (@pxref{Group Parameters}), ++possibly using @kbd{A M} (@code{gnus-mailing-list-insinuate}) in the ++summary buffer. ++ ++That enables the following commands to the summary buffer: ++ ++@table @kbd ++ ++@item C-c C-n h ++@kindex C-c C-n h (Summary) ++@findex gnus-mailing-list-help ++Send a message to fetch mailing list help, if List-Help field exists. ++ ++@item C-c C-n s ++@kindex C-c C-n s (Summary) ++@findex gnus-mailing-list-subscribe ++Send a message to subscribe the mailing list, if List-Subscribe field exists. ++ ++@item C-c C-n u ++@kindex C-c C-n u (Summary) ++@findex gnus-mailing-list-unsubscribe ++Send a message to unsubscribe the mailing list, if List-Unsubscribe ++field exists. ++ ++@item C-c C-n p ++@kindex C-c C-n p (Summary) ++@findex gnus-mailing-list-post ++Post to the mailing list, if List-Post field exists. ++ ++@item C-c C-n o ++@kindex C-c C-n o (Summary) ++@findex gnus-mailing-list-owner ++Send a message to the mailing list owner, if List-Owner field exists. ++ ++@item C-c C-n a ++@kindex C-c C-n a (Summary) ++@findex gnus-mailing-list-archive ++Browse the mailing list archive, if List-Archive field exists. ++ ++@end table ++ ++ ++@node Article Buffer ++@chapter Article Buffer ++@cindex article buffer ++ ++The articles are displayed in the article buffer, of which there is only ++one. All the summary buffers share the same article buffer unless you ++tell Gnus otherwise. ++ ++@menu ++* Hiding Headers:: Deciding what headers should be displayed. ++* Using MIME:: Pushing articles through @acronym{MIME} before reading them. ++* Customizing Articles:: Tailoring the look of the articles. ++* Article Keymap:: Keystrokes available in the article buffer. ++* Misc Article:: Other stuff. ++@end menu ++ ++ ++@node Hiding Headers ++@section Hiding Headers ++@cindex hiding headers ++@cindex deleting headers ++ ++The top section of each article is the @dfn{head}. (The rest is the ++@dfn{body}, but you may have guessed that already.) ++ ++@vindex gnus-show-all-headers ++There is a lot of useful information in the head: the name of the person ++who wrote the article, the date it was written and the subject of the ++article. That's well and nice, but there's also lots of information ++most people do not want to see---what systems the article has passed ++through before reaching you, the @code{Message-ID}, the ++@code{References}, etc. ad nauseam---and you'll probably want to get rid ++of some of those lines. If you want to keep all those lines in the ++article buffer, you can set @code{gnus-show-all-headers} to @code{t}. ++ ++Gnus provides you with two variables for sifting headers: ++ ++@table @code ++ ++@item gnus-visible-headers ++@vindex gnus-visible-headers ++If this variable is non-@code{nil}, it should be a regular expression ++that says what headers you wish to keep in the article buffer. All ++headers that do not match this variable will be hidden. ++ ++For instance, if you only want to see the name of the person who wrote ++the article and the subject, you'd say: ++ ++@lisp ++(setq gnus-visible-headers "^From:\\|^Subject:") ++@end lisp ++ ++This variable can also be a list of regexps to match headers to ++remain visible. ++ ++@item gnus-ignored-headers ++@vindex gnus-ignored-headers ++This variable is the reverse of @code{gnus-visible-headers}. If this ++variable is set (and @code{gnus-visible-headers} is @code{nil}), it ++should be a regular expression that matches all lines that you want to ++hide. All lines that do not match this variable will remain visible. ++ ++For instance, if you just want to get rid of the @code{References} line ++and the @code{Xref} line, you might say: ++ ++@lisp ++(setq gnus-ignored-headers "^References:\\|^Xref:") ++@end lisp ++ ++This variable can also be a list of regexps to match headers to ++be removed. ++ ++Note that if @code{gnus-visible-headers} is non-@code{nil}, this ++variable will have no effect. ++ ++@end table ++ ++@vindex gnus-sorted-header-list ++Gnus can also sort the headers for you. (It does this by default.) You ++can control the sorting by setting the @code{gnus-sorted-header-list} ++variable. It is a list of regular expressions that says in what order ++the headers are to be displayed. ++ ++For instance, if you want the name of the author of the article first, ++and then the subject, you might say something like: ++ ++@lisp ++(setq gnus-sorted-header-list '("^From:" "^Subject:")) ++@end lisp ++ ++Any headers that are to remain visible, but are not listed in this ++variable, will be displayed in random order after all the headers listed in this variable. ++ ++@findex gnus-article-hide-boring-headers ++@vindex gnus-boring-article-headers ++You can hide further boring headers by setting ++@code{gnus-treat-hide-boring-headers} to @code{head}. What this function ++does depends on the @code{gnus-boring-article-headers} variable. It's a ++list, but this list doesn't actually contain header names. Instead it ++lists various @dfn{boring conditions} that Gnus can check and remove ++from sight. ++ ++These conditions are: ++@table @code ++@item empty ++Remove all empty headers. ++@item followup-to ++Remove the @code{Followup-To} header if it is identical to the ++@code{Newsgroups} header. ++@item reply-to ++Remove the @code{Reply-To} header if it lists the same addresses as ++the @code{From} header, or if the @code{broken-reply-to} group ++parameter is set. ++@item newsgroups ++Remove the @code{Newsgroups} header if it only contains the current group ++name. ++@item to-address ++Remove the @code{To} header if it only contains the address identical to ++the current group's @code{to-address} parameter. ++@item to-list ++Remove the @code{To} header if it only contains the address identical to ++the current group's @code{to-list} parameter. ++@item cc-list ++Remove the @code{Cc} header if it only contains the address identical to ++the current group's @code{to-list} parameter. ++@item date ++Remove the @code{Date} header if the article is less than three days ++old. ++@item long-to ++Remove the @code{To} and/or @code{Cc} header if it is very long. ++@item many-to ++Remove all @code{To} and/or @code{Cc} headers if there are more than one. ++@end table ++ ++To include these three elements, you could say something like: ++ ++@lisp ++(setq gnus-boring-article-headers ++ '(empty followup-to reply-to)) ++@end lisp ++ ++This is also the default value for this variable. ++ ++ ++@node Using MIME ++@section Using MIME ++@cindex @acronym{MIME} ++ ++Mime is a standard for waving your hands through the air, aimlessly, ++while people stand around yawning. ++ ++@acronym{MIME}, however, is a standard for encoding your articles, aimlessly, ++while all newsreaders die of fear. ++ ++@acronym{MIME} may specify what character set the article uses, the encoding ++of the characters, and it also makes it possible to embed pictures and ++other naughty stuff in innocent-looking articles. ++ ++@vindex gnus-display-mime-function ++@findex gnus-display-mime ++Gnus pushes @acronym{MIME} articles through @code{gnus-display-mime-function} ++to display the @acronym{MIME} parts. This is @code{gnus-display-mime} by ++default, which creates a bundle of clickable buttons that can be used to ++display, save and manipulate the @acronym{MIME} objects. ++ ++The following commands are available when you have placed point over a ++@acronym{MIME} button: ++ ++@table @kbd ++@findex gnus-article-press-button ++@item RET (Article) ++@kindex RET (Article) ++@itemx BUTTON-2 (Article) ++Toggle displaying of the @acronym{MIME} object ++(@code{gnus-article-press-button}). If built-in viewers can not display ++the object, Gnus resorts to external viewers in the @file{mailcap} ++files. If a viewer has the @samp{copiousoutput} specification, the ++object is displayed inline. ++ ++@findex gnus-mime-view-part ++@item M-RET (Article) ++@kindex M-RET (Article) ++@itemx v (Article) ++Prompt for a method, and then view the @acronym{MIME} object using this ++method (@code{gnus-mime-view-part}). ++ ++@findex gnus-mime-view-part-as-type ++@item t (Article) ++@kindex t (Article) ++View the @acronym{MIME} object as if it were a different @acronym{MIME} media type ++(@code{gnus-mime-view-part-as-type}). ++ ++@findex gnus-mime-view-part-as-charset ++@item C (Article) ++@kindex C (Article) ++Prompt for a charset, and then view the @acronym{MIME} object using this ++charset (@code{gnus-mime-view-part-as-charset}). ++ ++@findex gnus-mime-save-part ++@item o (Article) ++@kindex o (Article) ++Prompt for a file name, and then save the @acronym{MIME} object ++(@code{gnus-mime-save-part}). ++ ++@findex gnus-mime-save-part-and-strip ++@item C-o (Article) ++@kindex C-o (Article) ++Prompt for a file name, then save the @acronym{MIME} object and strip it from ++the article. Then proceed to article editing, where a reasonable ++suggestion is being made on how the altered article should look ++like. The stripped @acronym{MIME} object will be referred via the ++message/external-body @acronym{MIME} type. ++(@code{gnus-mime-save-part-and-strip}). ++ ++@findex gnus-mime-replace-part ++@item r (Article) ++@kindex r (Article) ++Prompt for a file name, replace the @acronym{MIME} object with an ++external body refering to the file via the message/external-body ++@acronym{MIME} type. (@code{gnus-mime-replace-part}). ++ ++@findex gnus-mime-delete-part ++@item d (Article) ++@kindex d (Article) ++Delete the @acronym{MIME} object from the article and replace it with some ++information about the removed @acronym{MIME} object ++(@code{gnus-mime-delete-part}). ++ ++@c FIXME: gnus-auto-select-part should be documented here ++ ++@findex gnus-mime-copy-part ++@item c (Article) ++@kindex c (Article) ++Copy the @acronym{MIME} object to a fresh buffer and display this buffer ++(@code{gnus-mime-copy-part}). If given a prefix, copy the raw contents ++without decoding. If given a numerical prefix, you can do semi-manual ++charset stuff (see @code{gnus-summary-show-article-charset-alist} in ++@ref{Paging the Article}). Compressed files like @file{.gz} and ++@file{.bz2} are automatically decompressed if ++@code{auto-compression-mode} is enabled (@pxref{Compressed Files,, ++Accessing Compressed Files, emacs, The Emacs Editor}). ++ ++@findex gnus-mime-print-part ++@item p (Article) ++@kindex p (Article) ++Print the @acronym{MIME} object (@code{gnus-mime-print-part}). This ++command respects the @samp{print=} specifications in the ++@file{.mailcap} file. ++ ++@findex gnus-mime-inline-part ++@item i (Article) ++@kindex i (Article) ++Insert the contents of the @acronym{MIME} object into the buffer ++(@code{gnus-mime-inline-part}) as @samp{text/plain}. If given a prefix, insert ++the raw contents without decoding. If given a numerical prefix, you can ++do semi-manual charset stuff (see ++@code{gnus-summary-show-article-charset-alist} in @ref{Paging the ++Article}). Compressed files like @file{.gz} and @file{.bz2} are ++automatically decompressed depending on @code{jka-compr} regardless of ++@code{auto-compression-mode} (@pxref{Compressed Files,, Accessing ++Compressed Files, emacs, The Emacs Editor}). ++ ++@findex gnus-mime-view-part-internally ++@item E (Article) ++@kindex E (Article) ++View the @acronym{MIME} object with an internal viewer. If no internal ++viewer is available, use an external viewer ++(@code{gnus-mime-view-part-internally}). ++ ++@findex gnus-mime-view-part-externally ++@item e (Article) ++@kindex e (Article) ++View the @acronym{MIME} object with an external viewer. ++(@code{gnus-mime-view-part-externally}). ++ ++@findex gnus-mime-pipe-part ++@item | (Article) ++@kindex | (Article) ++Output the @acronym{MIME} object to a process (@code{gnus-mime-pipe-part}). ++ ++@findex gnus-mime-action-on-part ++@item . (Article) ++@kindex . (Article) ++Interactively run an action on the @acronym{MIME} object ++(@code{gnus-mime-action-on-part}). ++ ++@end table ++ ++Gnus will display some @acronym{MIME} objects automatically. The way Gnus ++determines which parts to do this with is described in the Emacs ++@acronym{MIME} manual. ++ ++It might be best to just use the toggling functions from the article ++buffer to avoid getting nasty surprises. (For instance, you enter the ++group @samp{alt.sing-a-long} and, before you know it, @acronym{MIME} has ++decoded the sound file in the article and some horrible sing-a-long song ++comes screaming out your speakers, and you can't find the volume button, ++because there isn't one, and people are starting to look at you, and you ++try to stop the program, but you can't, and you can't find the program ++to control the volume, and everybody else in the room suddenly decides ++to look at you disdainfully, and you'll feel rather stupid.) ++ ++Any similarity to real events and people is purely coincidental. Ahem. ++ ++Also @pxref{MIME Commands}. ++ ++ ++@node Customizing Articles ++@section Customizing Articles ++@cindex article customization ++ ++A slew of functions for customizing how the articles are to look like ++exist. You can call these functions interactively ++(@pxref{Article Washing}), or you can have them ++called automatically when you select the articles. ++ ++To have them called automatically, you should set the corresponding ++``treatment'' variable. For instance, to have headers hidden, you'd set ++@code{gnus-treat-hide-headers}. Below is a list of variables that can ++be set, but first we discuss the values these variables can have. ++ ++Note: Some values, while valid, make little sense. Check the list below ++for sensible values. ++ ++@enumerate ++@item ++@code{nil}: Don't do this treatment. ++ ++@item ++@code{t}: Do this treatment on all body parts. ++ ++@item ++@code{head}: Do the treatment on the headers. ++ ++@item ++@code{first}: Do this treatment on the first body part. ++ ++@item ++@code{last}: Do this treatment on the last body part. ++ ++@item ++An integer: Do this treatment on all body parts that have a length less ++than this number. ++ ++@item ++A list of strings: Do this treatment on all body parts that are in ++articles that are read in groups that have names that match one of the ++regexps in the list. ++ ++@item ++A list where the first element is not a string: ++ ++The list is evaluated recursively. The first element of the list is a ++predicate. The following predicates are recognized: @code{or}, ++@code{and}, @code{not} and @code{typep}. Here's an example: ++ ++@lisp ++(or last ++ (typep "text/x-vcard")) ++@end lisp ++ ++@end enumerate ++ ++You may have noticed that the word @dfn{part} is used here. This refers ++to the fact that some messages are @acronym{MIME} multipart articles that may ++be divided into several parts. Articles that are not multiparts are ++considered to contain just a single part. ++ ++@vindex gnus-article-treat-types ++Are the treatments applied to all sorts of multipart parts? Yes, if you ++want to, but by default, only @samp{text/plain} parts are given the ++treatment. This is controlled by the @code{gnus-article-treat-types} ++variable, which is a list of regular expressions that are matched to the ++type of the part. This variable is ignored if the value of the ++controlling variable is a predicate list, as described above. ++ ++@ifinfo ++@c Avoid sort of redundant entries in the same section for the printed ++@c manual, but add them in info to allow `i gnus-treat-foo-bar RET' or ++@c `i foo-bar'. ++@vindex gnus-treat-buttonize ++@vindex gnus-treat-buttonize-head ++@vindex gnus-treat-capitalize-sentences ++@vindex gnus-treat-overstrike ++@vindex gnus-treat-strip-cr ++@vindex gnus-treat-strip-headers-in-body ++@vindex gnus-treat-strip-leading-blank-lines ++@vindex gnus-treat-strip-multiple-blank-lines ++@vindex gnus-treat-strip-pem ++@vindex gnus-treat-strip-trailing-blank-lines ++@vindex gnus-treat-unsplit-urls ++@vindex gnus-treat-wash-html ++@vindex gnus-treat-date-english ++@vindex gnus-treat-date-iso8601 ++@vindex gnus-treat-date-lapsed ++@vindex gnus-treat-date-local ++@vindex gnus-treat-date-original ++@vindex gnus-treat-date-user-defined ++@vindex gnus-treat-date-ut ++@vindex gnus-treat-from-picon ++@vindex gnus-treat-mail-picon ++@vindex gnus-treat-newsgroups-picon ++@vindex gnus-treat-display-smileys ++@vindex gnus-treat-body-boundary ++@vindex gnus-treat-display-x-face ++@vindex gnus-treat-display-face ++@vindex gnus-treat-emphasize ++@vindex gnus-treat-fill-article ++@vindex gnus-treat-fill-long-lines ++@vindex gnus-treat-hide-boring-headers ++@vindex gnus-treat-hide-citation ++@vindex gnus-treat-hide-citation-maybe ++@vindex gnus-treat-hide-headers ++@vindex gnus-treat-hide-signature ++@vindex gnus-treat-strip-banner ++@vindex gnus-treat-strip-list-identifiers ++@vindex gnus-treat-highlight-citation ++@vindex gnus-treat-highlight-headers ++@vindex gnus-treat-highlight-signature ++@vindex gnus-treat-play-sounds ++@vindex gnus-treat-translate ++@vindex gnus-treat-x-pgp-sig ++@vindex gnus-treat-unfold-headers ++@vindex gnus-treat-fold-headers ++@vindex gnus-treat-fold-newsgroups ++@vindex gnus-treat-leading-whitespace ++@end ifinfo ++ ++The following treatment options are available. The easiest way to ++customize this is to examine the @code{gnus-article-treat} customization ++group. Values in parenthesis are suggested sensible values. Others are ++possible but those listed are probably sufficient for most people. ++ ++@table @code ++@item gnus-treat-buttonize (t, integer) ++@item gnus-treat-buttonize-head (head) ++ ++@xref{Article Buttons}. ++ ++@item gnus-treat-capitalize-sentences (t, integer) ++@item gnus-treat-overstrike (t, integer) ++@item gnus-treat-strip-cr (t, integer) ++@item gnus-treat-strip-headers-in-body (t, integer) ++@item gnus-treat-strip-leading-blank-lines (t, first, integer) ++@item gnus-treat-strip-multiple-blank-lines (t, integer) ++@item gnus-treat-strip-pem (t, last, integer) ++@item gnus-treat-strip-trailing-blank-lines (t, last, integer) ++@item gnus-treat-unsplit-urls (t, integer) ++@item gnus-treat-wash-html (t, integer) ++ ++@xref{Article Washing}. ++ ++@item gnus-treat-date-english (head) ++@item gnus-treat-date-iso8601 (head) ++@item gnus-treat-date-lapsed (head) ++@item gnus-treat-date-local (head) ++@item gnus-treat-date-original (head) ++@item gnus-treat-date-user-defined (head) ++@item gnus-treat-date-ut (head) ++ ++@xref{Article Date}. ++ ++@item gnus-treat-from-picon (head) ++@item gnus-treat-mail-picon (head) ++@item gnus-treat-newsgroups-picon (head) ++ ++@xref{Picons}. ++ ++@item gnus-treat-display-smileys (t, integer) ++ ++@item gnus-treat-body-boundary (head) ++ ++@vindex gnus-body-boundary-delimiter ++Adds a delimiter between header and body, the string used as delimiter ++is controlled by @code{gnus-body-boundary-delimiter}. ++ ++@xref{Smileys}. ++ ++@vindex gnus-treat-display-x-face ++@item gnus-treat-display-x-face (head) ++ ++@xref{X-Face}. ++ ++@vindex gnus-treat-display-face ++@item gnus-treat-display-face (head) ++ ++@xref{Face}. ++ ++@vindex gnus-treat-emphasize ++@item gnus-treat-emphasize (t, head, integer) ++@vindex gnus-treat-fill-article ++@item gnus-treat-fill-article (t, integer) ++@vindex gnus-treat-fill-long-lines ++@item gnus-treat-fill-long-lines (t, integer) ++@vindex gnus-treat-hide-boring-headers ++@item gnus-treat-hide-boring-headers (head) ++@vindex gnus-treat-hide-citation ++@item gnus-treat-hide-citation (t, integer) ++@vindex gnus-treat-hide-citation-maybe ++@item gnus-treat-hide-citation-maybe (t, integer) ++@vindex gnus-treat-hide-headers ++@item gnus-treat-hide-headers (head) ++@vindex gnus-treat-hide-signature ++@item gnus-treat-hide-signature (t, last) ++@vindex gnus-treat-strip-banner ++@item gnus-treat-strip-banner (t, last) ++@vindex gnus-treat-strip-list-identifiers ++@item gnus-treat-strip-list-identifiers (head) ++ ++@xref{Article Hiding}. ++ ++@vindex gnus-treat-highlight-citation ++@item gnus-treat-highlight-citation (t, integer) ++@vindex gnus-treat-highlight-headers ++@item gnus-treat-highlight-headers (head) ++@vindex gnus-treat-highlight-signature ++@item gnus-treat-highlight-signature (t, last, integer) ++ ++@xref{Article Highlighting}. ++ ++@vindex gnus-treat-play-sounds ++@item gnus-treat-play-sounds ++@vindex gnus-treat-translate ++@item gnus-treat-translate ++@item gnus-treat-ansi-sequences (t) ++@vindex gnus-treat-x-pgp-sig ++@item gnus-treat-x-pgp-sig (head) ++ ++@vindex gnus-treat-unfold-headers ++@item gnus-treat-unfold-headers (head) ++@vindex gnus-treat-fold-headers ++@item gnus-treat-fold-headers (head) ++@vindex gnus-treat-fold-newsgroups ++@item gnus-treat-fold-newsgroups (head) ++@vindex gnus-treat-leading-whitespace ++@item gnus-treat-leading-whitespace (head) ++ ++@xref{Article Header}. ++ ++ ++@end table ++ ++@vindex gnus-part-display-hook ++You can, of course, write your own functions to be called from ++@code{gnus-part-display-hook}. The functions are called narrowed to the ++part, and you can do anything you like, pretty much. There is no ++information that you have to keep in the buffer---you can change ++everything. ++ ++ ++@node Article Keymap ++@section Article Keymap ++ ++Most of the keystrokes in the summary buffer can also be used in the ++article buffer. They should behave as if you typed them in the summary ++buffer, which means that you don't actually have to have a summary ++buffer displayed while reading. You can do it all from the article ++buffer. ++ ++@kindex v (Article) ++@cindex keys, reserved for users (Article) ++The key @kbd{v} is reserved for users. You can bind it to some ++command or better use it as a prefix key. ++ ++A few additional keystrokes are available: ++ ++@table @kbd ++ ++@item SPACE ++@kindex SPACE (Article) ++@findex gnus-article-next-page ++Scroll forwards one page (@code{gnus-article-next-page}). ++This is exactly the same as @kbd{h SPACE h}. ++ ++@item DEL ++@kindex DEL (Article) ++@findex gnus-article-prev-page ++Scroll backwards one page (@code{gnus-article-prev-page}). ++This is exactly the same as @kbd{h DEL h}. ++ ++@item C-c ^ ++@kindex C-c ^ (Article) ++@findex gnus-article-refer-article ++If point is in the neighborhood of a @code{Message-ID} and you press ++@kbd{C-c ^}, Gnus will try to get that article from the server ++(@code{gnus-article-refer-article}). ++ ++@item C-c C-m ++@kindex C-c C-m (Article) ++@findex gnus-article-mail ++Send a reply to the address near point (@code{gnus-article-mail}). If ++given a prefix, include the mail. ++ ++@item s ++@kindex s (Article) ++@findex gnus-article-show-summary ++Reconfigure the buffers so that the summary buffer becomes visible ++(@code{gnus-article-show-summary}). ++ ++@item ? ++@kindex ? (Article) ++@findex gnus-article-describe-briefly ++Give a very brief description of the available keystrokes ++(@code{gnus-article-describe-briefly}). ++ ++@item TAB ++@kindex TAB (Article) ++@findex gnus-article-next-button ++Go to the next button, if any (@code{gnus-article-next-button}). This ++only makes sense if you have buttonizing turned on. ++ ++@item M-TAB ++@kindex M-TAB (Article) ++@findex gnus-article-prev-button ++Go to the previous button, if any (@code{gnus-article-prev-button}). ++ ++@item R ++@kindex R (Article) ++@findex gnus-article-reply-with-original ++Send a reply to the current article and yank the current article ++(@code{gnus-article-reply-with-original}). If the region is active, ++only yank the text in the region. ++ ++@item S W ++@kindex S W (Article) ++@findex gnus-article-wide-reply-with-original ++Send a wide reply to the current article and yank the current article ++(@code{gnus-article-wide-reply-with-original}). If the region is ++active, only yank the text in the region. ++ ++@item F ++@kindex F (Article) ++@findex gnus-article-followup-with-original ++Send a followup to the current article and yank the current article ++(@code{gnus-article-followup-with-original}). If the region is active, ++only yank the text in the region. ++ ++ ++@end table ++ ++ ++@node Misc Article ++@section Misc Article ++ ++@table @code ++ ++@item gnus-single-article-buffer ++@vindex gnus-single-article-buffer ++@cindex article buffers, several ++If non-@code{nil}, use the same article buffer for all the groups. ++(This is the default.) If @code{nil}, each group will have its own ++article buffer. ++ ++@vindex gnus-article-decode-hook ++@item gnus-article-decode-hook ++@cindex @acronym{MIME} ++Hook used to decode @acronym{MIME} articles. The default value is ++@code{(article-decode-charset article-decode-encoded-words)} ++ ++@vindex gnus-article-prepare-hook ++@item gnus-article-prepare-hook ++This hook is called right after the article has been inserted into the ++article buffer. It is mainly intended for functions that do something ++depending on the contents; it should probably not be used for changing ++the contents of the article buffer. ++ ++@item gnus-article-mode-hook ++@vindex gnus-article-mode-hook ++Hook called in article mode buffers. ++ ++@item gnus-article-mode-syntax-table ++@vindex gnus-article-mode-syntax-table ++Syntax table used in article buffers. It is initialized from ++@code{text-mode-syntax-table}. ++ ++@vindex gnus-article-over-scroll ++@item gnus-article-over-scroll ++If non-@code{nil}, allow scrolling the article buffer even when there ++no more new text to scroll in. The default is @code{nil}. ++ ++@vindex gnus-article-mode-line-format ++@item gnus-article-mode-line-format ++This variable is a format string along the same lines as ++@code{gnus-summary-mode-line-format} (@pxref{Summary Buffer Mode ++Line}). It accepts the same format specifications as that variable, ++with two extensions: ++ ++@table @samp ++ ++@item w ++The @dfn{wash status} of the article. This is a short string with one ++character for each possible article wash operation that may have been ++performed. The characters and their meaning: ++ ++@table @samp ++ ++@item c ++Displayed when cited text may be hidden in the article buffer. ++ ++@item h ++Displayed when headers are hidden in the article buffer. ++ ++@item p ++Displayed when article is digitally signed or encrypted, and Gnus has ++hidden the security headers. (N.B. does not tell anything about ++security status, i.e. good or bad signature.) ++ ++@item s ++Displayed when the signature has been hidden in the Article buffer. ++ ++@item o ++Displayed when Gnus has treated overstrike characters in the article buffer. ++ ++@item e ++Displayed when Gnus has treated emphasized strings in the article buffer. ++ ++@end table ++ ++@item m ++The number of @acronym{MIME} parts in the article. ++ ++@end table ++ ++@vindex gnus-break-pages ++ ++@item gnus-break-pages ++Controls whether @dfn{page breaking} is to take place. If this variable ++is non-@code{nil}, the articles will be divided into pages whenever a ++page delimiter appears in the article. If this variable is @code{nil}, ++paging will not be done. ++ ++@item gnus-page-delimiter ++@vindex gnus-page-delimiter ++This is the delimiter mentioned above. By default, it is @samp{^L} ++(formfeed). ++ ++@cindex IDNA ++@cindex internationalized domain names ++@vindex gnus-use-idna ++@item gnus-use-idna ++This variable controls whether Gnus performs IDNA decoding of ++internationalized domain names inside @samp{From}, @samp{To} and ++@samp{Cc} headers. @xref{IDNA, ,IDNA,message, The Message Manual}, ++for how to compose such messages. This requires ++@uref{http://www.gnu.org/software/libidn/, GNU Libidn}, and this ++variable is only enabled if you have installed it. ++ ++@end table ++ ++ ++@node Composing Messages ++@chapter Composing Messages ++@cindex composing messages ++@cindex messages ++@cindex mail ++@cindex sending mail ++@cindex reply ++@cindex followup ++@cindex post ++@cindex using gpg ++@cindex using s/mime ++@cindex using smime ++ ++@kindex C-c C-c (Post) ++All commands for posting and mailing will put you in a message buffer ++where you can edit the article all you like, before you send the ++article by pressing @kbd{C-c C-c}. @xref{Top, , Overview, message, ++Message Manual}. Where the message will be posted/mailed to depends ++on your setup (@pxref{Posting Server}). ++ ++@menu ++* Mail:: Mailing and replying. ++* Posting Server:: What server should you post and mail via? ++* POP before SMTP:: You cannot send a mail unless you read a mail. ++* Mail and Post:: Mailing and posting at the same time. ++* Archived Messages:: Where Gnus stores the messages you've sent. ++* Posting Styles:: An easier way to specify who you are. ++* Drafts:: Postponing messages and rejected messages. ++* Rejected Articles:: What happens if the server doesn't like your article? ++* Signing and encrypting:: How to compose secure messages. ++@end menu ++ ++Also @pxref{Canceling and Superseding} for information on how to ++remove articles you shouldn't have posted. ++ ++ ++@node Mail ++@section Mail ++ ++Variables for customizing outgoing mail: ++ ++@table @code ++@item gnus-uu-digest-headers ++@vindex gnus-uu-digest-headers ++List of regexps to match headers included in digested messages. The ++headers will be included in the sequence they are matched. If ++@code{nil} include all headers. ++ ++@item gnus-add-to-list ++@vindex gnus-add-to-list ++If non-@code{nil}, add a @code{to-list} group parameter to mail groups ++that have none when you do a @kbd{a}. ++ ++@item gnus-confirm-mail-reply-to-news ++@vindex gnus-confirm-mail-reply-to-news ++If non-@code{nil}, Gnus will ask you for a confirmation when you are ++about to reply to news articles by mail. If it is @code{nil}, nothing ++interferes in what you want to do. This can also be a function ++receiving the group name as the only parameter which should return ++non-@code{nil} if a confirmation is needed, or a regular expression ++matching group names, where confirmation should be asked for. ++ ++If you find yourself never wanting to reply to mail, but occasionally ++press @kbd{R} anyway, this variable might be for you. ++ ++@item gnus-confirm-treat-mail-like-news ++@vindex gnus-confirm-treat-mail-like-news ++If non-@code{nil}, Gnus also requests confirmation according to ++@code{gnus-confirm-mail-reply-to-news} when replying to mail. This is ++useful for treating mailing lists like newsgroups. ++ ++@end table ++ ++ ++@node Posting Server ++@section Posting Server ++ ++When you press those magical @kbd{C-c C-c} keys to ship off your latest ++(extremely intelligent, of course) article, where does it go? ++ ++Thank you for asking. I hate you. ++ ++It can be quite complicated. ++ ++@vindex gnus-post-method ++When posting news, Message usually invokes @code{message-send-news} ++(@pxref{News Variables, , News Variables, message, Message Manual}). ++Normally, Gnus will post using the same select method as you're ++reading from (which might be convenient if you're reading lots of ++groups from different private servers). However. If the server ++you're reading from doesn't allow posting, just reading, you probably ++want to use some other server to post your (extremely intelligent and ++fabulously interesting) articles. You can then set the ++@code{gnus-post-method} to some other method: ++ ++@lisp ++(setq gnus-post-method '(nnspool "")) ++@end lisp ++ ++Now, if you've done this, and then this server rejects your article, or ++this server is down, what do you do then? To override this variable you ++can use a non-zero prefix to the @kbd{C-c C-c} command to force using ++the ``current'' server, to get back the default behavior, for posting. ++ ++If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command, ++Gnus will prompt you for what method to use for posting. ++ ++You can also set @code{gnus-post-method} to a list of select methods. ++If that's the case, Gnus will always prompt you for what method to use ++for posting. ++ ++Finally, if you want to always post using the native select method, ++you can set this variable to @code{native}. ++ ++@vindex message-send-mail-function ++When sending mail, Message invokes the function specified by the ++variable @code{message-send-mail-function}. Gnus tries to set it to a ++value suitable for your system. ++@xref{Mail Variables, ,Mail Variables,message,Message manual}, for more ++information. ++ ++@node POP before SMTP ++@section POP before SMTP ++@cindex pop before smtp ++@findex message-smtpmail-send-it ++@findex mail-source-touch-pop ++ ++Does your @acronym{ISP} require the @acronym{POP}-before-@acronym{SMTP} ++authentication? It is whether you need to connect to the @acronym{POP} ++mail server within a certain time before sending mails. If so, there is ++a convenient way. To do that, put the following lines in your ++@file{~/.gnus.el} file: ++ ++@lisp ++(setq message-send-mail-function 'message-smtpmail-send-it) ++(add-hook 'message-send-mail-hook 'mail-source-touch-pop) ++@end lisp ++ ++@noindent ++It means to let Gnus connect to the @acronym{POP} mail server in advance ++whenever you send a mail. The @code{mail-source-touch-pop} function ++does only a @acronym{POP} authentication according to the value of ++@code{mail-sources} without fetching mails, just before sending a mail. ++Note that you have to use @code{message-smtpmail-send-it} which runs ++@code{message-send-mail-hook} rather than @code{smtpmail-send-it} and ++set the value of @code{mail-sources} for a @acronym{POP} connection ++correctly. @xref{Mail Sources}. ++ ++If you have two or more @acronym{POP} mail servers set in ++@code{mail-sources}, you may want to specify one of them to ++@code{mail-source-primary-source} as the @acronym{POP} mail server to be ++used for the @acronym{POP}-before-@acronym{SMTP} authentication. If it ++is your primary @acronym{POP} mail server (i.e., you are fetching mails ++mainly from that server), you can set it permanently as follows: ++ ++@lisp ++(setq mail-source-primary-source ++ '(pop :server "pop3.mail.server" ++ :password "secret")) ++@end lisp ++ ++@noindent ++Otherwise, bind it dynamically only when performing the ++@acronym{POP}-before-@acronym{SMTP} authentication as follows: ++ ++@lisp ++(add-hook 'message-send-mail-hook ++ (lambda () ++ (let ((mail-source-primary-source ++ '(pop :server "pop3.mail.server" ++ :password "secret"))) ++ (mail-source-touch-pop)))) ++@end lisp ++ ++@node Mail and Post ++@section Mail and Post ++ ++Here's a list of variables relevant to both mailing and ++posting: ++ ++@table @code ++@item gnus-mailing-list-groups ++@findex gnus-mailing-list-groups ++@cindex mailing lists ++ ++If your news server offers groups that are really mailing lists ++gatewayed to the @acronym{NNTP} server, you can read those groups without ++problems, but you can't post/followup to them without some difficulty. ++One solution is to add a @code{to-address} to the group parameters ++(@pxref{Group Parameters}). An easier thing to do is set the ++@code{gnus-mailing-list-groups} to a regexp that matches the groups that ++really are mailing lists. Then, at least, followups to the mailing ++lists will work most of the time. Posting to these groups (@kbd{a}) is ++still a pain, though. ++ ++@item gnus-user-agent ++@vindex gnus-user-agent ++@cindex User-Agent ++ ++This variable controls which information should be exposed in the ++User-Agent header. It can be a list of symbols or a string. Valid ++symbols are @code{gnus} (show Gnus version) and @code{emacs} (show Emacs ++version). In addition to the Emacs version, you can add @code{codename} ++(show (S)XEmacs codename) or either @code{config} (show system ++configuration) or @code{type} (show system type). If you set it to a ++string, be sure to use a valid format, see RFC 2616. ++ ++@end table ++ ++You may want to do spell-checking on messages that you send out. Or, if ++you don't want to spell-check by hand, you could add automatic ++spell-checking via the @code{ispell} package: ++ ++@cindex ispell ++@findex ispell-message ++@lisp ++(add-hook 'message-send-hook 'ispell-message) ++@end lisp ++ ++If you want to change the @code{ispell} dictionary based on what group ++you're in, you could say something like the following: ++ ++@lisp ++(add-hook 'gnus-select-group-hook ++ (lambda () ++ (cond ++ ((string-match ++ "^de\\." (gnus-group-real-name gnus-newsgroup-name)) ++ (ispell-change-dictionary "deutsch")) ++ (t ++ (ispell-change-dictionary "english"))))) ++@end lisp ++ ++Modify to suit your needs. ++ ++@vindex gnus-message-highlight-citation ++If @code{gnus-message-highlight-citation} is t, different levels of ++citations are highlighted like in Gnus article buffers also in message ++mode buffers. ++ ++@node Archived Messages ++@section Archived Messages ++@cindex archived messages ++@cindex sent messages ++ ++Gnus provides a few different methods for storing the mail and news you ++send. The default method is to use the @dfn{archive virtual server} to ++store the messages. If you want to disable this completely, the ++@code{gnus-message-archive-group} variable should be @code{nil}, which ++is the default. ++ ++For archiving interesting messages in a group you read, see the ++@kbd{B c} (@code{gnus-summary-copy-article}) command (@pxref{Mail ++Group Commands}). ++ ++@vindex gnus-message-archive-method ++@code{gnus-message-archive-method} says what virtual server Gnus is to ++use to store sent messages. The default is @code{"archive"}, and when ++actually being used it is expanded into: ++ ++@lisp ++(nnfolder "archive" ++ (nnfolder-directory "~/Mail/archive") ++ (nnfolder-active-file "~/Mail/archive/active") ++ (nnfolder-get-new-mail nil) ++ (nnfolder-inhibit-expiry t)) ++@end lisp ++ ++@quotation ++@vindex gnus-update-message-archive-method ++Note: a server like this is saved in the @file{~/.newsrc.eld} file first ++so that it may be used as a real method of the server which is named ++@code{"archive"} (that is, for the case where ++@code{gnus-message-archive-method} is set to @code{"archive"}) ever ++since. If it once has been saved, it will never be updated by default ++even if you change the value of @code{gnus-message-archive-method} ++afterward. Therefore, the server @code{"archive"} doesn't necessarily ++mean the @code{nnfolder} server like this at all times. If you want the ++saved method to reflect always the value of ++@code{gnus-message-archive-method}, set the ++@code{gnus-update-message-archive-method} variable to a non-@code{nil} ++value. The default value of this variable is @code{nil}. ++@end quotation ++ ++You can, however, use any mail select method (@code{nnml}, ++@code{nnmbox}, etc.). @code{nnfolder} is a quite likable select method ++for doing this sort of thing, though. If you don't like the default ++directory chosen, you could say something like: ++ ++@lisp ++(setq gnus-message-archive-method ++ '(nnfolder "archive" ++ (nnfolder-inhibit-expiry t) ++ (nnfolder-active-file "~/News/sent-mail/active") ++ (nnfolder-directory "~/News/sent-mail/"))) ++@end lisp ++ ++@vindex gnus-message-archive-group ++@cindex Gcc ++Gnus will insert @code{Gcc} headers in all outgoing messages that point ++to one or more group(s) on that server. Which group to use is ++determined by the @code{gnus-message-archive-group} variable. ++ ++This variable can be used to do the following: ++ ++@table @asis ++@item a string ++Messages will be saved in that group. ++ ++Note that you can include a select method in the group name, then the ++message will not be stored in the select method given by ++@code{gnus-message-archive-method}, but in the select method specified ++by the group name, instead. Suppose @code{gnus-message-archive-method} ++has the default value shown above. Then setting ++@code{gnus-message-archive-group} to @code{"foo"} means that outgoing ++messages are stored in @samp{nnfolder+archive:foo}, but if you use the ++value @code{"nnml:foo"}, then outgoing messages will be stored in ++@samp{nnml:foo}. ++ ++@item a list of strings ++Messages will be saved in all those groups. ++ ++@item an alist of regexps, functions and forms ++When a key ``matches'', the result is used. ++ ++@item @code{nil} ++No message archiving will take place. This is the default. ++@end table ++ ++Let's illustrate: ++ ++Just saving to a single group called @samp{MisK}: ++@lisp ++(setq gnus-message-archive-group "MisK") ++@end lisp ++ ++Saving to two groups, @samp{MisK} and @samp{safe}: ++@lisp ++(setq gnus-message-archive-group '("MisK" "safe")) ++@end lisp ++ ++Save to different groups based on what group you are in: ++@lisp ++(setq gnus-message-archive-group ++ '(("^alt" "sent-to-alt") ++ ("mail" "sent-to-mail") ++ (".*" "sent-to-misc"))) ++@end lisp ++ ++More complex stuff: ++@lisp ++(setq gnus-message-archive-group ++ '((if (message-news-p) ++ "misc-news" ++ "misc-mail"))) ++@end lisp ++ ++How about storing all news messages in one file, but storing all mail ++messages in one file per month: ++ ++@lisp ++(setq gnus-message-archive-group ++ '((if (message-news-p) ++ "misc-news" ++ (concat "mail." (format-time-string "%Y-%m"))))) ++@end lisp ++ ++@c (XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to ++@c use a different value for @code{gnus-message-archive-group} there.) ++ ++Now, when you send a message off, it will be stored in the appropriate ++group. (If you want to disable storing for just one particular message, ++you can just remove the @code{Gcc} header that has been inserted.) The ++archive group will appear in the group buffer the next time you start ++Gnus, or the next time you press @kbd{F} in the group buffer. You can ++enter it and read the articles in it just like you'd read any other ++group. If the group gets really big and annoying, you can simply rename ++if (using @kbd{G r} in the group buffer) to something ++nice---@samp{misc-mail-september-1995}, or whatever. New messages will ++continue to be stored in the old (now empty) group. ++ ++That's the default method of archiving sent messages. Gnus offers a ++different way for the people who don't like the default method. In that ++case you should set @code{gnus-message-archive-group} to @code{nil}; ++this will disable archiving. ++ ++@table @code ++@item gnus-outgoing-message-group ++@vindex gnus-outgoing-message-group ++All outgoing messages will be put in this group. If you want to store ++all your outgoing mail and articles in the group @samp{nnml:archive}, ++you set this variable to that value. This variable can also be a list of ++group names. ++ ++If you want to have greater control over what group to put each ++message in, you can set this variable to a function that checks the ++current newsgroup name and then returns a suitable group name (or list ++of names). ++ ++This variable can be used instead of @code{gnus-message-archive-group}, ++but the latter is the preferred method. ++ ++@item gnus-gcc-mark-as-read ++@vindex gnus-gcc-mark-as-read ++If non-@code{nil}, automatically mark @code{Gcc} articles as read. ++ ++@item gnus-gcc-externalize-attachments ++@vindex gnus-gcc-externalize-attachments ++If @code{nil}, attach files as normal parts in Gcc copies; if a regexp ++and matches the Gcc group name, attach files as external parts; if it is ++@code{all}, attach local files as external parts; if it is other ++non-@code{nil}, the behavior is the same as @code{all}, but it may be ++changed in the future. ++ ++@end table ++ ++ ++@node Posting Styles ++@section Posting Styles ++@cindex posting styles ++@cindex styles ++ ++All them variables, they make my head swim. ++ ++So what if you want a different @code{Organization} and signature based ++on what groups you post to? And you post both from your home machine ++and your work machine, and you want different @code{From} lines, and so ++on? ++ ++@vindex gnus-posting-styles ++One way to do stuff like that is to write clever hooks that change the ++variables you need to have changed. That's a bit boring, so somebody ++came up with the bright idea of letting the user specify these things in ++a handy alist. Here's an example of a @code{gnus-posting-styles} ++variable: ++ ++@lisp ++((".*" ++ (signature "Peace and happiness") ++ (organization "What me?")) ++ ("^comp" ++ (signature "Death to everybody")) ++ ("comp.emacs.i-love-it" ++ (organization "Emacs is it"))) ++@end lisp ++ ++As you might surmise from this example, this alist consists of several ++@dfn{styles}. Each style will be applicable if the first element ++``matches'', in some form or other. The entire alist will be iterated ++over, from the beginning towards the end, and each match will be ++applied, which means that attributes in later styles that match override ++the same attributes in earlier matching styles. So ++@samp{comp.programming.literate} will have the @samp{Death to everybody} ++signature and the @samp{What me?} @code{Organization} header. ++ ++The first element in each style is called the @code{match}. If it's a ++string, then Gnus will try to regexp match it against the group name. ++If it is the form @code{(header @var{match} @var{regexp})}, then Gnus ++will look in the original article for a header whose name is ++@var{match} and compare that @var{regexp}. @var{match} and ++@var{regexp} are strings. (The original article is the one you are ++replying or following up to. If you are not composing a reply or a ++followup, then there is nothing to match against.) If the ++@code{match} is a function symbol, that function will be called with ++no arguments. If it's a variable symbol, then the variable will be ++referenced. If it's a list, then that list will be @code{eval}ed. In ++any case, if this returns a non-@code{nil} value, then the style is ++said to @dfn{match}. ++ ++Each style may contain an arbitrary amount of @dfn{attributes}. Each ++attribute consists of a @code{(@var{name} @var{value})} pair. In ++addition, you can also use the @code{(@var{name} :file @var{value})} ++form or the @code{(@var{name} :value @var{value})} form. Where ++@code{:file} signifies @var{value} represents a file name and its ++contents should be used as the attribute value, @code{:value} signifies ++@var{value} does not represent a file name explicitly. The attribute ++name can be one of: ++ ++@itemize @bullet ++@item @code{signature} ++@item @code{signature-file} ++@item @code{x-face-file} ++@item @code{address}, overriding @code{user-mail-address} ++@item @code{name}, overriding @code{(user-full-name)} ++@item @code{body} ++@end itemize ++ ++Note that the @code{signature-file} attribute honors the variable ++@code{message-signature-directory}. ++ ++The attribute name can also be a string or a symbol. In that case, ++this will be used as a header name, and the value will be inserted in ++the headers of the article; if the value is @code{nil}, the header ++name will be removed. If the attribute name is @code{eval}, the form ++is evaluated, and the result is thrown away. ++ ++The attribute value can be a string (used verbatim), a function with ++zero arguments (the return value will be used), a variable (its value ++will be used) or a list (it will be @code{eval}ed and the return value ++will be used). The functions and sexps are called/@code{eval}ed in the ++message buffer that is being set up. The headers of the current article ++are available through the @code{message-reply-headers} variable, which ++is a vector of the following headers: number subject from date id ++references chars lines xref extra. ++ ++@vindex message-reply-headers ++ ++If you wish to check whether the message you are about to compose is ++meant to be a news article or a mail message, you can check the values ++of the @code{message-news-p} and @code{message-mail-p} functions. ++ ++@findex message-mail-p ++@findex message-news-p ++ ++So here's a new example: ++ ++@lisp ++(setq gnus-posting-styles ++ '((".*" ++ (signature-file "~/.signature") ++ (name "User Name") ++ (x-face-file "~/.xface") ++ (x-url (getenv "WWW_HOME")) ++ (organization "People's Front Against MWM")) ++ ("^rec.humor" ++ (signature my-funny-signature-randomizer)) ++ ((equal (system-name) "gnarly") ;; @r{A form} ++ (signature my-quote-randomizer)) ++ (message-news-p ;; @r{A function symbol} ++ (signature my-news-signature)) ++ (window-system ;; @r{A value symbol} ++ ("X-Window-System" (format "%s" window-system))) ++ ;; @r{If I'm replying to Larsi, set the Organization header.} ++ ((header "from" "larsi.*org") ++ (Organization "Somewhere, Inc.")) ++ ((posting-from-work-p) ;; @r{A user defined function} ++ (signature-file "~/.work-signature") ++ (address "user@@bar.foo") ++ (body "You are fired.\n\nSincerely, your boss.") ++ (organization "Important Work, Inc")) ++ ("nnml:.*" ++ (From (save-excursion ++ (set-buffer gnus-article-buffer) ++ (message-fetch-field "to")))) ++ ("^nn.+:" ++ (signature-file "~/.mail-signature")))) ++@end lisp ++ ++The @samp{nnml:.*} rule means that you use the @code{To} address as the ++@code{From} address in all your outgoing replies, which might be handy ++if you fill many roles. ++You may also use @code{message-alternative-emails} instead. ++@xref{Message Headers, ,Message Headers, message, Message Manual}. ++ ++@node Drafts ++@section Drafts ++@cindex drafts ++ ++If you are writing a message (mail or news) and suddenly remember that ++you have a steak in the oven (or some pesto in the food processor, you ++craaazy vegetarians), you'll probably wish there was a method to save ++the message you are writing so that you can continue editing it some ++other day, and send it when you feel its finished. ++ ++Well, don't worry about it. Whenever you start composing a message of ++some sort using the Gnus mail and post commands, the buffer you get will ++automatically associate to an article in a special @dfn{draft} group. ++If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the ++article will be saved there. (Auto-save files also go to the draft ++group.) ++ ++@cindex nndraft ++@vindex nndraft-directory ++The draft group is a special group (which is implemented as an ++@code{nndraft} group, if you absolutely have to know) called ++@samp{nndraft:drafts}. The variable @code{nndraft-directory} says where ++@code{nndraft} is to store its files. What makes this group special is ++that you can't tick any articles in it or mark any articles as ++read---all articles in the group are permanently unread. ++ ++If the group doesn't exist, it will be created and you'll be subscribed ++to it. The only way to make it disappear from the Group buffer is to ++unsubscribe it. The special properties of the draft group comes from ++a group property (@pxref{Group Parameters}), and if lost the group ++behaves like any other group. This means the commands below will not ++be available. To restore the special properties of the group, the ++simplest way is to kill the group, using @kbd{C-k}, and restart ++Gnus. The group is automatically created again with the ++correct parameters. The content of the group is not lost. ++ ++@c @findex gnus-dissociate-buffer-from-draft ++@c @kindex C-c M-d (Mail) ++@c @kindex C-c M-d (Post) ++@c @findex gnus-associate-buffer-with-draft ++@c @kindex C-c C-d (Mail) ++@c @kindex C-c C-d (Post) ++@c If you're writing some super-secret message that you later want to ++@c encode with PGP before sending, you may wish to turn the auto-saving ++@c (and association with the draft group) off. You never know who might be ++@c interested in reading all your extremely valuable and terribly horrible ++@c and interesting secrets. The @kbd{C-c M-d} ++@c (@code{gnus-dissociate-buffer-from-draft}) command does that for you. ++@c If you change your mind and want to turn the auto-saving back on again, ++@c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that. ++@c ++@c @vindex gnus-use-draft ++@c To leave association with the draft group off by default, set ++@c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default. ++ ++@findex gnus-draft-edit-message ++@kindex D e (Draft) ++When you want to continue editing the article, you simply enter the ++draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do ++that. You will be placed in a buffer where you left off. ++ ++Rejected articles will also be put in this draft group (@pxref{Rejected ++Articles}). ++ ++@findex gnus-draft-send-all-messages ++@kindex D s (Draft) ++@findex gnus-draft-send-message ++@kindex D S (Draft) ++If you have lots of rejected messages you want to post (or mail) without ++doing further editing, you can use the @kbd{D s} command ++(@code{gnus-draft-send-message}). This command understands the ++process/prefix convention (@pxref{Process/Prefix}). The @kbd{D S} ++command (@code{gnus-draft-send-all-messages}) will ship off all messages ++in the buffer. ++ ++@findex gnus-draft-toggle-sending ++@kindex D t (Draft) ++If you have some messages that you wish not to send, you can use the ++@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message ++as unsendable. This is a toggling command. ++ ++ ++@node Rejected Articles ++@section Rejected Articles ++@cindex rejected articles ++ ++Sometimes a news server will reject an article. Perhaps the server ++doesn't like your face. Perhaps it just feels miserable. Perhaps ++@emph{there be demons}. Perhaps you have included too much cited text. ++Perhaps the disk is full. Perhaps the server is down. ++ ++These situations are, of course, totally beyond the control of Gnus. ++(Gnus, of course, loves the way you look, always feels great, has angels ++fluttering around inside of it, doesn't care about how much cited text ++you include, never runs full and never goes down.) So Gnus saves these ++articles until some later time when the server feels better. ++ ++The rejected articles will automatically be put in a special draft group ++(@pxref{Drafts}). When the server comes back up again, you'd then ++typically enter that group and send all the articles off. ++ ++@node Signing and encrypting ++@section Signing and encrypting ++@cindex using gpg ++@cindex using s/mime ++@cindex using smime ++ ++Gnus can digitally sign and encrypt your messages, using vanilla ++@acronym{PGP} format or @acronym{PGP/MIME} or @acronym{S/MIME}. For ++decoding such messages, see the @code{mm-verify-option} and ++@code{mm-decrypt-option} options (@pxref{Security}). ++ ++@vindex gnus-message-replysign ++@vindex gnus-message-replyencrypt ++@vindex gnus-message-replysignencrypted ++Often, you would like to sign replies to people who send you signed ++messages. Even more often, you might want to encrypt messages which ++are in reply to encrypted messages. Gnus offers ++@code{gnus-message-replysign} to enable the former, and ++@code{gnus-message-replyencrypt} for the latter. In addition, setting ++@code{gnus-message-replysignencrypted} (on by default) will sign ++automatically encrypted messages. ++ ++Instructing @acronym{MML} to perform security operations on a ++@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for ++signing and the @kbd{C-c C-m c} key map for encryption, as follows. ++ ++@table @kbd ++ ++@item C-c C-m s s ++@kindex C-c C-m s s (Message) ++@findex mml-secure-message-sign-smime ++ ++Digitally sign current message using @acronym{S/MIME}. ++ ++@item C-c C-m s o ++@kindex C-c C-m s o (Message) ++@findex mml-secure-message-sign-pgp ++ ++Digitally sign current message using @acronym{PGP}. ++ ++@item C-c C-m s p ++@kindex C-c C-m s p (Message) ++@findex mml-secure-message-sign-pgp ++ ++Digitally sign current message using @acronym{PGP/MIME}. ++ ++@item C-c C-m c s ++@kindex C-c C-m c s (Message) ++@findex mml-secure-message-encrypt-smime ++ ++Digitally encrypt current message using @acronym{S/MIME}. ++ ++@item C-c C-m c o ++@kindex C-c C-m c o (Message) ++@findex mml-secure-message-encrypt-pgp ++ ++Digitally encrypt current message using @acronym{PGP}. ++ ++@item C-c C-m c p ++@kindex C-c C-m c p (Message) ++@findex mml-secure-message-encrypt-pgpmime ++ ++Digitally encrypt current message using @acronym{PGP/MIME}. ++ ++@item C-c C-m C-n ++@kindex C-c C-m C-n (Message) ++@findex mml-unsecure-message ++Remove security related @acronym{MML} tags from message. ++ ++@end table ++ ++@xref{Security, ,Security, message, Message Manual}, for more information. ++ ++@node Select Methods ++@chapter Select Methods ++@cindex foreign groups ++@cindex select methods ++ ++A @dfn{foreign group} is a group not read by the usual (or ++default) means. It could be, for instance, a group from a different ++@acronym{NNTP} server, it could be a virtual group, or it could be your own ++personal mail group. ++ ++A foreign group (or any group, really) is specified by a @dfn{name} and ++a @dfn{select method}. To take the latter first, a select method is a ++list where the first element says what back end to use (e.g. @code{nntp}, ++@code{nnspool}, @code{nnml}) and the second element is the @dfn{server ++name}. There may be additional elements in the select method, where the ++value may have special meaning for the back end in question. ++ ++One could say that a select method defines a @dfn{virtual server}---so ++we do just that (@pxref{Server Buffer}). ++ ++The @dfn{name} of the group is the name the back end will recognize the ++group as. ++ ++For instance, the group @samp{soc.motss} on the @acronym{NNTP} server ++@samp{some.where.edu} will have the name @samp{soc.motss} and select ++method @code{(nntp "some.where.edu")}. Gnus will call this group ++@samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp} ++back end just knows this group as @samp{soc.motss}. ++ ++The different methods all have their peculiarities, of course. ++ ++@menu ++* Server Buffer:: Making and editing virtual servers. ++* Getting News:: Reading USENET news with Gnus. ++* Getting Mail:: Reading your personal mail with Gnus. ++* Browsing the Web:: Getting messages from a plethora of Web sources. ++* IMAP:: Using Gnus as a @acronym{IMAP} client. ++* Other Sources:: Reading directories, files, SOUP packets. ++* Combined Groups:: Combining groups into one group. ++* Email Based Diary:: Using mails to manage diary events in Gnus. ++* Gnus Unplugged:: Reading news and mail offline. ++@end menu ++ ++ ++@node Server Buffer ++@section Server Buffer ++ ++Traditionally, a @dfn{server} is a machine or a piece of software that ++one connects to, and then requests information from. Gnus does not ++connect directly to any real servers, but does all transactions through ++one back end or other. But that's just putting one layer more between ++the actual media and Gnus, so we might just as well say that each ++back end represents a virtual server. ++ ++For instance, the @code{nntp} back end may be used to connect to several ++different actual @acronym{NNTP} servers, or, perhaps, to many different ports ++on the same actual @acronym{NNTP} server. You tell Gnus which back end to ++use, and what parameters to set by specifying a @dfn{select method}. ++ ++These select method specifications can sometimes become quite ++complicated---say, for instance, that you want to read from the ++@acronym{NNTP} server @samp{news.funet.fi} on port number 13, which ++hangs if queried for @acronym{NOV} headers and has a buggy select. Ahem. ++Anyway, if you had to specify that for each group that used this ++server, that would be too much work, so Gnus offers a way of naming ++select methods, which is what you do in the server buffer. ++ ++To enter the server buffer, use the @kbd{^} ++(@code{gnus-group-enter-server-mode}) command in the group buffer. ++ ++@menu ++* Server Buffer Format:: You can customize the look of this buffer. ++* Server Commands:: Commands to manipulate servers. ++* Example Methods:: Examples server specifications. ++* Creating a Virtual Server:: An example session. ++* Server Variables:: Which variables to set. ++* Servers and Methods:: You can use server names as select methods. ++* Unavailable Servers:: Some servers you try to contact may be down. ++@end menu ++ ++@vindex gnus-server-mode-hook ++@code{gnus-server-mode-hook} is run when creating the server buffer. ++ ++ ++@node Server Buffer Format ++@subsection Server Buffer Format ++@cindex server buffer format ++ ++@vindex gnus-server-line-format ++You can change the look of the server buffer lines by changing the ++@code{gnus-server-line-format} variable. This is a @code{format}-like ++variable, with some simple extensions: ++ ++@table @samp ++ ++@item h ++How the news is fetched---the back end name. ++ ++@item n ++The name of this server. ++ ++@item w ++Where the news is to be fetched from---the address. ++ ++@item s ++The opened/closed/denied status of the server. ++ ++@item a ++Whether this server is agentized. ++@end table ++ ++@vindex gnus-server-mode-line-format ++The mode line can also be customized by using the ++@code{gnus-server-mode-line-format} variable (@pxref{Mode Line ++Formatting}). The following specs are understood: ++ ++@table @samp ++@item S ++Server name. ++ ++@item M ++Server method. ++@end table ++ ++Also @pxref{Formatting Variables}. ++ ++ ++@node Server Commands ++@subsection Server Commands ++@cindex server commands ++ ++@table @kbd ++ ++@item v ++@kindex v (Server) ++@cindex keys, reserved for users (Server) ++The key @kbd{v} is reserved for users. You can bind it to some ++command or better use it as a prefix key. ++ ++@item a ++@kindex a (Server) ++@findex gnus-server-add-server ++Add a new server (@code{gnus-server-add-server}). ++ ++@item e ++@kindex e (Server) ++@findex gnus-server-edit-server ++Edit a server (@code{gnus-server-edit-server}). ++ ++@item SPACE ++@kindex SPACE (Server) ++@findex gnus-server-read-server ++Browse the current server (@code{gnus-server-read-server}). ++ ++@item q ++@kindex q (Server) ++@findex gnus-server-exit ++Return to the group buffer (@code{gnus-server-exit}). ++ ++@item k ++@kindex k (Server) ++@findex gnus-server-kill-server ++Kill the current server (@code{gnus-server-kill-server}). ++ ++@item y ++@kindex y (Server) ++@findex gnus-server-yank-server ++Yank the previously killed server (@code{gnus-server-yank-server}). ++ ++@item c ++@kindex c (Server) ++@findex gnus-server-copy-server ++Copy the current server (@code{gnus-server-copy-server}). ++ ++@item l ++@kindex l (Server) ++@findex gnus-server-list-servers ++List all servers (@code{gnus-server-list-servers}). ++ ++@item s ++@kindex s (Server) ++@findex gnus-server-scan-server ++Request that the server scan its sources for new articles ++(@code{gnus-server-scan-server}). This is mainly sensible with mail ++servers. ++ ++@item g ++@kindex g (Server) ++@findex gnus-server-regenerate-server ++Request that the server regenerate all its data structures ++(@code{gnus-server-regenerate-server}). This can be useful if you have ++a mail back end that has gotten out of sync. ++ ++@item z ++@kindex z (Server) ++@findex gnus-server-compact-server ++ ++Compact all groups in the server under point ++(@code{gnus-server-compact-server}). Currently implemented only in ++nnml (@pxref{Mail Spool}). This removes gaps between article numbers, ++hence getting a correct total article count. ++ ++@end table ++ ++ ++@node Example Methods ++@subsection Example Methods ++ ++Most select methods are pretty simple and self-explanatory: ++ ++@lisp ++(nntp "news.funet.fi") ++@end lisp ++ ++Reading directly from the spool is even simpler: ++ ++@lisp ++(nnspool "") ++@end lisp ++ ++As you can see, the first element in a select method is the name of the ++back end, and the second is the @dfn{address}, or @dfn{name}, if you ++will. ++ ++After these two elements, there may be an arbitrary number of ++@code{(@var{variable} @var{form})} pairs. ++ ++To go back to the first example---imagine that you want to read from ++port 15 on that machine. This is what the select method should ++look like then: ++ ++@lisp ++(nntp "news.funet.fi" (nntp-port-number 15)) ++@end lisp ++ ++You should read the documentation to each back end to find out what ++variables are relevant, but here's an @code{nnmh} example: ++ ++@code{nnmh} is a mail back end that reads a spool-like structure. Say ++you have two structures that you wish to access: One is your private ++mail spool, and the other is a public one. Here's the possible spec for ++your private mail: ++ ++@lisp ++(nnmh "private" (nnmh-directory "~/private/mail/")) ++@end lisp ++ ++(This server is then called @samp{private}, but you may have guessed ++that.) ++ ++Here's the method for a public spool: ++ ++@lisp ++(nnmh "public" ++ (nnmh-directory "/usr/information/spool/") ++ (nnmh-get-new-mail nil)) ++@end lisp ++ ++@cindex proxy ++@cindex firewall ++ ++If you are behind a firewall and only have access to the @acronym{NNTP} ++server from the firewall machine, you can instruct Gnus to @code{rlogin} ++on the firewall machine and connect with ++@uref{http://netcat.sourceforge.net/, netcat} from there to the ++@acronym{NNTP} server. ++Doing this can be rather fiddly, but your virtual server definition ++should probably look something like this: ++ ++@lisp ++(nntp "firewall" ++ (nntp-open-connection-function nntp-open-via-rlogin-and-netcat) ++ (nntp-via-address "the.firewall.machine") ++ (nntp-address "the.real.nntp.host")) ++@end lisp ++ ++If you want to use the wonderful @code{ssh} program to provide a ++compressed connection over the modem line, you could add the following ++configuration to the example above: ++ ++@lisp ++ (nntp-via-rlogin-command "ssh") ++@end lisp ++ ++See also @code{nntp-via-rlogin-command-switches}. Here's an example for ++an indirect connection: ++ ++@lisp ++(setq gnus-select-method ++ '(nntp "indirect" ++ (nntp-address "news.server.example") ++ (nntp-via-user-name "intermediate_user_name") ++ (nntp-via-address "intermediate.host.example") ++ (nntp-via-rlogin-command "ssh") ++ (nntp-via-rlogin-command-switches ("-C")) ++ (nntp-open-connection-function nntp-open-via-rlogin-and-netcat))) ++@end lisp ++ ++This means that you have to have set up @code{ssh-agent} correctly to ++provide automatic authorization, of course. ++ ++If you're behind a firewall, but have direct access to the outside world ++through a wrapper command like "runsocks", you could open a socksified ++netcat connection to the news server as follows: ++ ++@lisp ++(nntp "outside" ++ (nntp-pre-command "runsocks") ++ (nntp-open-connection-function nntp-open-netcat-stream) ++ (nntp-address "the.news.server")) ++@end lisp ++ ++ ++@node Creating a Virtual Server ++@subsection Creating a Virtual Server ++ ++If you're saving lots of articles in the cache by using persistent ++articles, you may want to create a virtual server to read the cache. ++ ++First you need to add a new server. The @kbd{a} command does that. It ++would probably be best to use @code{nnml} to read the cache. You ++could also use @code{nnspool} or @code{nnmh}, though. ++ ++Type @kbd{a nnml RET cache RET}. ++ ++You should now have a brand new @code{nnml} virtual server called ++@samp{cache}. You now need to edit it to have the right definitions. ++Type @kbd{e} to edit the server. You'll be entered into a buffer that ++will contain the following: ++ ++@lisp ++(nnml "cache") ++@end lisp ++ ++Change that to: ++ ++@lisp ++(nnml "cache" ++ (nnml-directory "~/News/cache/") ++ (nnml-active-file "~/News/cache/active")) ++@end lisp ++ ++Type @kbd{C-c C-c} to return to the server buffer. If you now press ++@kbd{RET} over this virtual server, you should be entered into a browse ++buffer, and you should be able to enter any of the groups displayed. ++ ++ ++@node Server Variables ++@subsection Server Variables ++@cindex server variables ++@cindex server parameters ++ ++One sticky point when defining variables (both on back ends and in Emacs ++in general) is that some variables are typically initialized from other ++variables when the definition of the variables is being loaded. If you ++change the ``base'' variable after the variables have been loaded, you ++won't change the ``derived'' variables. ++ ++This typically affects directory and file variables. For instance, ++@code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml} ++directory variables are initialized from that variable, so ++@code{nnml-active-file} will be @file{~/Mail/active}. If you define a ++new virtual @code{nnml} server, it will @emph{not} suffice to set just ++@code{nnml-directory}---you have to explicitly set all the file ++variables to be what you want them to be. For a complete list of ++variables for each back end, see each back end's section later in this ++manual, but here's an example @code{nnml} definition: ++ ++@lisp ++(nnml "public" ++ (nnml-directory "~/my-mail/") ++ (nnml-active-file "~/my-mail/active") ++ (nnml-newsgroups-file "~/my-mail/newsgroups")) ++@end lisp ++ ++Server variables are often called @dfn{server parameters}. ++ ++@node Servers and Methods ++@subsection Servers and Methods ++ ++Wherever you would normally use a select method ++(e.g. @code{gnus-secondary-select-method}, in the group select method, ++when browsing a foreign server) you can use a virtual server name ++instead. This could potentially save lots of typing. And it's nice all ++over. ++ ++ ++@node Unavailable Servers ++@subsection Unavailable Servers ++ ++If a server seems to be unreachable, Gnus will mark that server as ++@code{denied}. That means that any subsequent attempt to make contact ++with that server will just be ignored. ``It can't be opened,'' Gnus ++will tell you, without making the least effort to see whether that is ++actually the case or not. ++ ++That might seem quite naughty, but it does make sense most of the time. ++Let's say you have 10 groups subscribed to on server ++@samp{nephelococcygia.com}. This server is located somewhere quite far ++away from you and the machine is quite slow, so it takes 1 minute just ++to find out that it refuses connection to you today. If Gnus were to ++attempt to do that 10 times, you'd be quite annoyed, so Gnus won't ++attempt to do that. Once it has gotten a single ``connection refused'', ++it will regard that server as ``down''. ++ ++So, what happens if the machine was only feeling unwell temporarily? ++How do you test to see whether the machine has come up again? ++ ++You jump to the server buffer (@pxref{Server Buffer}) and poke it ++with the following commands: ++ ++@table @kbd ++ ++@item O ++@kindex O (Server) ++@findex gnus-server-open-server ++Try to establish connection to the server on the current line ++(@code{gnus-server-open-server}). ++ ++@item C ++@kindex C (Server) ++@findex gnus-server-close-server ++Close the connection (if any) to the server ++(@code{gnus-server-close-server}). ++ ++@item D ++@kindex D (Server) ++@findex gnus-server-deny-server ++Mark the current server as unreachable ++(@code{gnus-server-deny-server}). ++ ++@item M-o ++@kindex M-o (Server) ++@findex gnus-server-open-all-servers ++Open the connections to all servers in the buffer ++(@code{gnus-server-open-all-servers}). ++ ++@item M-c ++@kindex M-c (Server) ++@findex gnus-server-close-all-servers ++Close the connections to all servers in the buffer ++(@code{gnus-server-close-all-servers}). ++ ++@item R ++@kindex R (Server) ++@findex gnus-server-remove-denials ++Remove all marks to whether Gnus was denied connection from any servers ++(@code{gnus-server-remove-denials}). ++ ++@item L ++@kindex L (Server) ++@findex gnus-server-offline-server ++Set server status to offline (@code{gnus-server-offline-server}). ++ ++@end table ++ ++ ++@node Getting News ++@section Getting News ++@cindex reading news ++@cindex news back ends ++ ++A newsreader is normally used for reading news. Gnus currently provides ++only two methods of getting news---it can read from an @acronym{NNTP} server, ++or it can read from a local spool. ++ ++@menu ++* NNTP:: Reading news from an @acronym{NNTP} server. ++* News Spool:: Reading news from the local spool. ++@end menu ++ ++ ++@node NNTP ++@subsection NNTP ++@cindex nntp ++ ++Subscribing to a foreign group from an @acronym{NNTP} server is rather easy. ++You just specify @code{nntp} as method and the address of the @acronym{NNTP} ++server as the, uhm, address. ++ ++If the @acronym{NNTP} server is located at a non-standard port, setting the ++third element of the select method to this port number should allow you ++to connect to the right port. You'll have to edit the group info for ++that (@pxref{Foreign Groups}). ++ ++The name of the foreign group can be the same as a native group. In ++fact, you can subscribe to the same group from as many different servers ++you feel like. There will be no name collisions. ++ ++The following variables can be used to create a virtual @code{nntp} ++server: ++ ++@table @code ++ ++@item nntp-server-opened-hook ++@vindex nntp-server-opened-hook ++@cindex @sc{mode reader} ++@cindex authinfo ++@cindex authentication ++@cindex nntp authentication ++@findex nntp-send-authinfo ++@findex nntp-send-mode-reader ++is run after a connection has been made. It can be used to send ++commands to the @acronym{NNTP} server after it has been contacted. By ++default it sends the command @code{MODE READER} to the server with the ++@code{nntp-send-mode-reader} function. This function should always be ++present in this hook. ++ ++@item nntp-authinfo-function ++@vindex nntp-authinfo-function ++@findex nntp-send-authinfo ++@vindex nntp-authinfo-file ++This function will be used to send @samp{AUTHINFO} to the @acronym{NNTP} ++server. The default function is @code{nntp-send-authinfo}, which looks ++through your @file{~/.authinfo} (or whatever you've set the ++@code{nntp-authinfo-file} variable to) for applicable entries. If none ++are found, it will prompt you for a login name and a password. The ++format of the @file{~/.authinfo} file is (almost) the same as the ++@code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp} ++manual page, but here are the salient facts: ++ ++@enumerate ++@item ++The file contains one or more line, each of which define one server. ++ ++@item ++Each line may contain an arbitrary number of token/value pairs. ++ ++The valid tokens include @samp{machine}, @samp{login}, @samp{password}, ++@samp{default}. In addition Gnus introduces two new tokens, not present ++in the original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and ++@samp{force}. (This is the only way the @file{.authinfo} file format ++deviates from the @file{.netrc} file format.) @samp{port} is used to ++indicate what port on the server the credentials apply to and ++@samp{force} is explained below. ++ ++@end enumerate ++ ++Here's an example file: ++ ++@example ++machine news.uio.no login larsi password geheimnis ++machine nntp.ifi.uio.no login larsi force yes ++@end example ++ ++The token/value pairs may appear in any order; @samp{machine} doesn't ++have to be first, for instance. ++ ++In this example, both login name and password have been supplied for the ++former server, while the latter has only the login name listed, and the ++user will be prompted for the password. The latter also has the ++@samp{force} tag, which means that the authinfo will be sent to the ++@var{nntp} server upon connection; the default (i.e., when there is not ++@samp{force} tag) is to not send authinfo to the @var{nntp} server ++until the @var{nntp} server asks for it. ++ ++You can also add @samp{default} lines that will apply to all servers ++that don't have matching @samp{machine} lines. ++ ++@example ++default force yes ++@end example ++ ++This will force sending @samp{AUTHINFO} commands to all servers not ++previously mentioned. ++ ++Remember to not leave the @file{~/.authinfo} file world-readable. ++ ++@item nntp-server-action-alist ++@vindex nntp-server-action-alist ++This is a list of regexps to match on server types and actions to be ++taken when matches are made. For instance, if you want Gnus to beep ++every time you connect to innd, you could say something like: ++ ++@lisp ++(setq nntp-server-action-alist ++ '(("innd" (ding)))) ++@end lisp ++ ++You probably don't want to do that, though. ++ ++The default value is ++ ++@lisp ++'(("nntpd 1\\.5\\.11t" ++ (remove-hook 'nntp-server-opened-hook ++ 'nntp-send-mode-reader))) ++@end lisp ++ ++This ensures that Gnus doesn't send the @code{MODE READER} command to ++nntpd 1.5.11t, since that command chokes that server, I've been told. ++ ++@item nntp-maximum-request ++@vindex nntp-maximum-request ++If the @acronym{NNTP} server doesn't support @acronym{NOV} headers, this back end ++will collect headers by sending a series of @code{head} commands. To ++speed things up, the back end sends lots of these commands without ++waiting for reply, and then reads all the replies. This is controlled ++by the @code{nntp-maximum-request} variable, and is 400 by default. If ++your network is buggy, you should set this to 1. ++ ++@item nntp-connection-timeout ++@vindex nntp-connection-timeout ++If you have lots of foreign @code{nntp} groups that you connect to ++regularly, you're sure to have problems with @acronym{NNTP} servers not ++responding properly, or being too loaded to reply within reasonable ++time. This is can lead to awkward problems, which can be helped ++somewhat by setting @code{nntp-connection-timeout}. This is an integer ++that says how many seconds the @code{nntp} back end should wait for a ++connection before giving up. If it is @code{nil}, which is the default, ++no timeouts are done. ++ ++@item nntp-nov-is-evil ++@vindex nntp-nov-is-evil ++If the @acronym{NNTP} server does not support @acronym{NOV}, you could set this ++variable to @code{t}, but @code{nntp} usually checks automatically whether @acronym{NOV} ++can be used. ++ ++@item nntp-xover-commands ++@vindex nntp-xover-commands ++@cindex @acronym{NOV} ++@cindex XOVER ++List of strings used as commands to fetch @acronym{NOV} lines from a ++server. The default value of this variable is @code{("XOVER" ++"XOVERVIEW")}. ++ ++@item nntp-nov-gap ++@vindex nntp-nov-gap ++@code{nntp} normally sends just one big request for @acronym{NOV} lines to ++the server. The server responds with one huge list of lines. However, ++if you have read articles 2-5000 in the group, and only want to read ++article 1 and 5001, that means that @code{nntp} will fetch 4999 @acronym{NOV} ++lines that you will not need. This variable says how ++big a gap between two consecutive articles is allowed to be before the ++@code{XOVER} request is split into several request. Note that if your ++network is fast, setting this variable to a really small number means ++that fetching will probably be slower. If this variable is @code{nil}, ++@code{nntp} will never split requests. The default is 5. ++ ++@item nntp-xref-number-is-evil ++@vindex nntp-xref-number-is-evil ++When Gnus refers to an article having the @code{Message-ID} that a user ++specifies or having the @code{Message-ID} of the parent article of the ++current one (@pxref{Finding the Parent}), Gnus sends a @code{HEAD} ++command to the @acronym{NNTP} server to know where it is, and the server ++returns the data containing the pairs of a group and an article number ++in the @code{Xref} header. Gnus normally uses the article number to ++refer to the article if the data shows that that article is in the ++current group, while it uses the @code{Message-ID} otherwise. However, ++some news servers, e.g., ones running Diablo, run multiple engines ++having the same articles but article numbers are not kept synchronized ++between them. In that case, the article number that appears in the ++@code{Xref} header varies by which engine is chosen, so you cannot refer ++to the parent article that is in the current group, for instance. If ++you connect to such a server, set this variable to a non-@code{nil} ++value, and Gnus never uses article numbers. For example: ++ ++@lisp ++(setq gnus-select-method ++ '(nntp "newszilla" ++ (nntp-address "newszilla.example.com") ++ (nntp-xref-number-is-evil t) ++ @dots{})) ++@end lisp ++ ++The default value of this server variable is @code{nil}. ++ ++@item nntp-prepare-server-hook ++@vindex nntp-prepare-server-hook ++A hook run before attempting to connect to an @acronym{NNTP} server. ++ ++@item nntp-record-commands ++@vindex nntp-record-commands ++If non-@code{nil}, @code{nntp} will log all commands it sends to the ++@acronym{NNTP} server (along with a timestamp) in the @samp{*nntp-log*} ++buffer. This is useful if you are debugging a Gnus/@acronym{NNTP} connection ++that doesn't seem to work. ++ ++@item nntp-open-connection-function ++@vindex nntp-open-connection-function ++It is possible to customize how the connection to the nntp server will ++be opened. If you specify an @code{nntp-open-connection-function} ++parameter, Gnus will use that function to establish the connection. ++Seven pre-made functions are supplied. These functions can be grouped ++in two categories: direct connection functions (four pre-made), and ++indirect ones (three pre-made). ++ ++@item nntp-never-echoes-commands ++@vindex nntp-never-echoes-commands ++Non-@code{nil} means the nntp server never echoes commands. It is ++reported that some nntps server doesn't echo commands. So, you may want ++to set this to non-@code{nil} in the method for such a server setting ++@code{nntp-open-connection-function} to @code{nntp-open-ssl-stream} for ++example. The default value is @code{nil}. Note that the ++@code{nntp-open-connection-functions-never-echo-commands} variable ++overrides the @code{nil} value of this variable. ++ ++@item nntp-open-connection-functions-never-echo-commands ++@vindex nntp-open-connection-functions-never-echo-commands ++List of functions that never echo commands. Add or set a function which ++you set to @code{nntp-open-connection-function} to this list if it does ++not echo commands. Note that a non-@code{nil} value of the ++@code{nntp-never-echoes-commands} variable overrides this variable. The ++default value is @code{(nntp-open-network-stream)}. ++ ++@item nntp-prepare-post-hook ++@vindex nntp-prepare-post-hook ++A hook run just before posting an article. If there is no ++@code{Message-ID} header in the article and the news server provides the ++recommended ID, it will be added to the article before running this ++hook. It is useful to make @code{Cancel-Lock} headers even if you ++inhibit Gnus to add a @code{Message-ID} header, you could say: ++ ++@lisp ++(add-hook 'nntp-prepare-post-hook 'canlock-insert-header) ++@end lisp ++ ++Note that not all servers support the recommended ID. This works for ++INN versions 2.3.0 and later, for instance. ++ ++@end table ++ ++@menu ++* Direct Functions:: Connecting directly to the server. ++* Indirect Functions:: Connecting indirectly to the server. ++* Common Variables:: Understood by several connection functions. ++* NNTP marks:: Storing marks for @acronym{NNTP} servers. ++@end menu ++ ++ ++@node Direct Functions ++@subsubsection Direct Functions ++@cindex direct connection functions ++ ++These functions are called direct because they open a direct connection ++between your machine and the @acronym{NNTP} server. The behavior of these ++functions is also affected by commonly understood variables ++(@pxref{Common Variables}). ++ ++@table @code ++@findex nntp-open-network-stream ++@item nntp-open-network-stream ++This is the default, and simply connects to some port or other on the ++remote system. ++ ++@findex nntp-open-tls-stream ++@item nntp-open-tls-stream ++Opens a connection to a server over a @dfn{secure} channel. To use ++this you must have @uref{http://www.gnu.org/software/gnutls/, GNUTLS} ++installed. You then define a server as follows: ++ ++@lisp ++;; @r{"nntps" is port 563 and is predefined in our @file{/etc/services}} ++;; @r{however, @samp{gnutls-cli -p} doesn't like named ports.} ++;; ++(nntp "snews.bar.com" ++ (nntp-open-connection-function nntp-open-tls-stream) ++ (nntp-port-number ) ++ (nntp-address "snews.bar.com")) ++@end lisp ++ ++@findex nntp-open-ssl-stream ++@item nntp-open-ssl-stream ++Opens a connection to a server over a @dfn{secure} channel. To use ++this you must have @uref{http://www.openssl.org, OpenSSL} or ++@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay} installed. You ++then define a server as follows: ++ ++@lisp ++;; @r{"snews" is port 563 and is predefined in our @file{/etc/services}} ++;; @r{however, @samp{openssl s_client -port} doesn't like named ports.} ++;; ++(nntp "snews.bar.com" ++ (nntp-open-connection-function nntp-open-ssl-stream) ++ (nntp-port-number 563) ++ (nntp-address "snews.bar.com")) ++@end lisp ++ ++@findex nntp-open-netcat-stream ++@item nntp-open-netcat-stream ++Opens a connection to an @acronym{NNTP} server using the @code{netcat} ++program. You might wonder why this function exists, since we have ++the default @code{nntp-open-network-stream} which would do the job. (One ++of) the reason(s) is that if you are behind a firewall but have direct ++connections to the outside world thanks to a command wrapper like ++@code{runsocks}, you can use it like this: ++ ++@lisp ++(nntp "socksified" ++ (nntp-pre-command "runsocks") ++ (nntp-open-connection-function nntp-open-netcat-stream) ++ (nntp-address "the.news.server")) ++@end lisp ++ ++With the default method, you would need to wrap your whole Emacs ++session, which is not a good idea. ++ ++@findex nntp-open-telnet-stream ++@item nntp-open-telnet-stream ++Like @code{nntp-open-netcat-stream}, but uses @code{telnet} rather than ++@code{netcat}. @code{telnet} is a bit less robust because of things ++like line-end-conversion, but sometimes netcat is simply ++not available. The previous example would turn into: ++ ++@lisp ++(nntp "socksified" ++ (nntp-pre-command "runsocks") ++ (nntp-open-connection-function nntp-open-telnet-stream) ++ (nntp-address "the.news.server") ++ (nntp-end-of-line "\n")) ++@end lisp ++@end table ++ ++ ++@node Indirect Functions ++@subsubsection Indirect Functions ++@cindex indirect connection functions ++ ++These functions are called indirect because they connect to an ++intermediate host before actually connecting to the @acronym{NNTP} server. ++All of these functions and related variables are also said to belong to ++the ``via'' family of connection: they're all prefixed with ``via'' to make ++things cleaner. The behavior of these functions is also affected by ++commonly understood variables (@pxref{Common Variables}). ++ ++@table @code ++@item nntp-open-via-rlogin-and-netcat ++@findex nntp-open-via-rlogin-and-netcat ++Does an @samp{rlogin} on a remote system, and then uses @code{netcat} to connect ++to the real @acronym{NNTP} server from there. This is useful for instance if ++you need to connect to a firewall machine first. ++ ++@code{nntp-open-via-rlogin-and-netcat}-specific variables: ++ ++@table @code ++@item nntp-via-rlogin-command ++@vindex nntp-via-rlogin-command ++Command used to log in on the intermediate host. The default is ++@samp{rsh}, but @samp{ssh} is a popular alternative. ++ ++@item nntp-via-rlogin-command-switches ++@vindex nntp-via-rlogin-command-switches ++List of strings to be used as the switches to ++@code{nntp-via-rlogin-command}. The default is @code{nil}. If you use ++@samp{ssh} for @code{nntp-via-rlogin-command}, you may set this to ++@samp{("-C")} in order to compress all data connections. ++@end table ++ ++@item nntp-open-via-rlogin-and-telnet ++@findex nntp-open-via-rlogin-and-telnet ++Does essentially the same, but uses @code{telnet} instead of @samp{netcat} ++to connect to the real @acronym{NNTP} server from the intermediate host. ++@code{telnet} is a bit less robust because of things like ++line-end-conversion, but sometimes @code{netcat} is simply not available. ++ ++@code{nntp-open-via-rlogin-and-telnet}-specific variables: ++ ++@table @code ++@item nntp-telnet-command ++@vindex nntp-telnet-command ++Command used to connect to the real @acronym{NNTP} server from the ++intermediate host. The default is @samp{telnet}. ++ ++@item nntp-telnet-switches ++@vindex nntp-telnet-switches ++List of strings to be used as the switches to the ++@code{nntp-telnet-command} command. The default is @code{("-8")}. ++ ++@item nntp-via-rlogin-command ++@vindex nntp-via-rlogin-command ++Command used to log in on the intermediate host. The default is ++@samp{rsh}, but @samp{ssh} is a popular alternative. ++ ++@item nntp-via-rlogin-command-switches ++@vindex nntp-via-rlogin-command-switches ++List of strings to be used as the switches to ++@code{nntp-via-rlogin-command}. If you use @samp{ssh}, you may need to set ++this to @samp{("-t" "-e" "none")} or @samp{("-C" "-t" "-e" "none")} if ++the telnet command requires a pseudo-tty allocation on an intermediate ++host. The default is @code{nil}. ++@end table ++ ++Note that you may want to change the value for @code{nntp-end-of-line} ++to @samp{\n} (@pxref{Common Variables}). ++ ++@item nntp-open-via-telnet-and-telnet ++@findex nntp-open-via-telnet-and-telnet ++Does essentially the same, but uses @samp{telnet} instead of ++@samp{rlogin} to connect to the intermediate host. ++ ++@code{nntp-open-via-telnet-and-telnet}-specific variables: ++ ++@table @code ++@item nntp-via-telnet-command ++@vindex nntp-via-telnet-command ++Command used to @code{telnet} the intermediate host. The default is ++@samp{telnet}. ++ ++@item nntp-via-telnet-switches ++@vindex nntp-via-telnet-switches ++List of strings to be used as the switches to the ++@code{nntp-via-telnet-command} command. The default is @samp{("-8")}. ++ ++@item nntp-via-user-password ++@vindex nntp-via-user-password ++Password to use when logging in on the intermediate host. ++ ++@item nntp-via-envuser ++@vindex nntp-via-envuser ++If non-@code{nil}, the intermediate @code{telnet} session (client and ++server both) will support the @code{ENVIRON} option and not prompt for ++login name. This works for Solaris @code{telnet}, for instance. ++ ++@item nntp-via-shell-prompt ++@vindex nntp-via-shell-prompt ++Regexp matching the shell prompt on the intermediate host. The default ++is @samp{bash\\|\$ *\r?$\\|> *\r?}. ++ ++@end table ++ ++Note that you may want to change the value for @code{nntp-end-of-line} ++to @samp{\n} (@pxref{Common Variables}). ++@end table ++ ++ ++Here are some additional variables that are understood by all the above ++functions: ++ ++@table @code ++ ++@item nntp-via-user-name ++@vindex nntp-via-user-name ++User name to use when connecting to the intermediate host. ++ ++@item nntp-via-address ++@vindex nntp-via-address ++Address of the intermediate host to connect to. ++ ++@end table ++ ++ ++@node Common Variables ++@subsubsection Common Variables ++ ++The following variables affect the behavior of all, or several of the ++pre-made connection functions. When not specified, all functions are ++affected (the values of the following variables will be used as the ++default if each virtual @code{nntp} server doesn't specify those server ++variables individually). ++ ++@table @code ++ ++@item nntp-pre-command ++@vindex nntp-pre-command ++A command wrapper to use when connecting through a non native ++connection function (all except @code{nntp-open-network-stream}, ++@code{nntp-open-tls-stream}, and @code{nntp-open-ssl-stream}). This is ++where you would put a @samp{SOCKS} wrapper for instance. ++ ++@item nntp-address ++@vindex nntp-address ++The address of the @acronym{NNTP} server. ++ ++@item nntp-port-number ++@vindex nntp-port-number ++Port number to connect to the @acronym{NNTP} server. The default is ++@samp{nntp}. If you use @acronym{NNTP} over ++@acronym{TLS}/@acronym{SSL}, you may want to use integer ports rather ++than named ports (i.e, use @samp{563} instead of @samp{snews} or ++@samp{nntps}), because external @acronym{TLS}/@acronym{SSL} tools may ++not work with named ports. ++ ++@item nntp-end-of-line ++@vindex nntp-end-of-line ++String to use as end-of-line marker when talking to the @acronym{NNTP} ++server. This is @samp{\r\n} by default, but should be @samp{\n} when ++using a non native telnet connection function. ++ ++@item nntp-netcat-command ++@vindex nntp-netcat-command ++Command to use when connecting to the @acronym{NNTP} server through ++@samp{netcat}. This is @emph{not} for an intermediate host. This is ++just for the real @acronym{NNTP} server. The default is ++@samp{nc}. ++ ++@item nntp-netcat-switches ++@vindex nntp-netcat-switches ++A list of switches to pass to @code{nntp-netcat-command}. The default ++is @samp{()}. ++ ++@end table ++ ++@node NNTP marks ++@subsubsection NNTP marks ++@cindex storing NNTP marks ++ ++Gnus stores marks (@pxref{Marking Articles}) for @acronym{NNTP} ++servers in marks files. A marks file records what marks you have set ++in a group and each file is specific to the corresponding server. ++Marks files are stored in @file{~/News/marks} ++(@code{nntp-marks-directory}) under a classic hierarchy resembling ++that of a news server, for example marks for the group ++@samp{gmane.discuss} on the news.gmane.org server will be stored in ++the file @file{~/News/marks/news.gmane.org/gmane/discuss/.marks}. ++ ++Marks files are useful because you can copy the @file{~/News/marks} ++directory (using rsync, scp or whatever) to another Gnus installation, ++and it will realize what articles you have read and marked. The data ++in @file{~/News/marks} has priority over the same data in ++@file{~/.newsrc.eld}. ++ ++Note that marks files are very much server-specific: Gnus remembers ++the article numbers so if you don't use the same servers on both ++installations things are most likely to break (most @acronym{NNTP} ++servers do not use the same article numbers as any other server). ++However, if you use servers A, B, C on one installation and servers A, ++D, E on the other, you can sync the marks files for A and then you'll ++get synchronization for that server between the two installations. ++ ++Using @acronym{NNTP} marks can possibly incur a performance penalty so ++if Gnus feels sluggish, try setting the @code{nntp-marks-is-evil} ++variable to @code{t}. Marks will then be stored in @file{~/.newsrc.eld}. ++ ++Related variables: ++ ++@table @code ++ ++@item nntp-marks-is-evil ++@vindex nntp-marks-is-evil ++If non-@code{nil}, this back end will ignore any marks files. The ++default is @code{nil}. ++ ++@item nntp-marks-directory ++@vindex nntp-marks-directory ++The directory where marks for nntp groups will be stored. ++ ++@end table ++ ++ ++@node News Spool ++@subsection News Spool ++@cindex nnspool ++@cindex news spool ++ ++Subscribing to a foreign group from the local spool is extremely easy, ++and might be useful, for instance, to speed up reading groups that ++contain very big articles---@samp{alt.binaries.pictures.furniture}, for ++instance. ++ ++Anyway, you just specify @code{nnspool} as the method and @code{""} (or ++anything else) as the address. ++ ++If you have access to a local spool, you should probably use that as the ++native select method (@pxref{Finding the News}). It is normally faster ++than using an @code{nntp} select method, but might not be. It depends. ++You just have to try to find out what's best at your site. ++ ++@table @code ++ ++@item nnspool-inews-program ++@vindex nnspool-inews-program ++Program used to post an article. ++ ++@item nnspool-inews-switches ++@vindex nnspool-inews-switches ++Parameters given to the inews program when posting an article. ++ ++@item nnspool-spool-directory ++@vindex nnspool-spool-directory ++Where @code{nnspool} looks for the articles. This is normally ++@file{/usr/spool/news/}. ++ ++@item nnspool-nov-directory ++@vindex nnspool-nov-directory ++Where @code{nnspool} will look for @acronym{NOV} files. This is normally@* ++@file{/usr/spool/news/over.view/}. ++ ++@item nnspool-lib-dir ++@vindex nnspool-lib-dir ++Where the news lib dir is (@file{/usr/lib/news/} by default). ++ ++@item nnspool-active-file ++@vindex nnspool-active-file ++The name of the active file. ++ ++@item nnspool-newsgroups-file ++@vindex nnspool-newsgroups-file ++The name of the group descriptions file. ++ ++@item nnspool-history-file ++@vindex nnspool-history-file ++The name of the news history file. ++ ++@item nnspool-active-times-file ++@vindex nnspool-active-times-file ++The name of the active date file. ++ ++@item nnspool-nov-is-evil ++@vindex nnspool-nov-is-evil ++If non-@code{nil}, @code{nnspool} won't try to use any @acronym{NOV} files ++that it finds. ++ ++@item nnspool-sift-nov-with-sed ++@vindex nnspool-sift-nov-with-sed ++@cindex sed ++If non-@code{nil}, which is the default, use @code{sed} to get the ++relevant portion from the overview file. If @code{nil}, ++@code{nnspool} will load the entire file into a buffer and process it ++there. ++ ++@end table ++ ++ ++@node Getting Mail ++@section Getting Mail ++@cindex reading mail ++@cindex mail ++ ++Reading mail with a newsreader---isn't that just plain WeIrD? But of ++course. ++ ++@menu ++* Mail in a Newsreader:: Important introductory notes. ++* Getting Started Reading Mail:: A simple cookbook example. ++* Splitting Mail:: How to create mail groups. ++* Mail Sources:: How to tell Gnus where to get mail from. ++* Mail Back End Variables:: Variables for customizing mail handling. ++* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. ++* Group Mail Splitting:: Use group customize to drive mail splitting. ++* Incorporating Old Mail:: What about the old mail you have? ++* Expiring Mail:: Getting rid of unwanted mail. ++* Washing Mail:: Removing cruft from the mail you get. ++* Duplicates:: Dealing with duplicated mail. ++* Not Reading Mail:: Using mail back ends for reading other files. ++* Choosing a Mail Back End:: Gnus can read a variety of mail formats. ++@end menu ++ ++ ++@node Mail in a Newsreader ++@subsection Mail in a Newsreader ++ ++If you are used to traditional mail readers, but have decided to switch ++to reading mail with Gnus, you may find yourself experiencing something ++of a culture shock. ++ ++Gnus does not behave like traditional mail readers. If you want to make ++it behave that way, you can, but it's an uphill battle. ++ ++Gnus, by default, handles all its groups using the same approach. This ++approach is very newsreaderly---you enter a group, see the new/unread ++messages, and when you read the messages, they get marked as read, and ++you don't see them any more. (Unless you explicitly ask for them.) ++ ++In particular, you do not do anything explicitly to delete messages. ++ ++Does this mean that all the messages that have been marked as read are ++deleted? How awful! ++ ++But, no, it means that old messages are @dfn{expired} according to some ++scheme or other. For news messages, the expire process is controlled by ++the news administrator; for mail, the expire process is controlled by ++you. The expire process for mail is covered in depth in @ref{Expiring ++Mail}. ++ ++What many Gnus users find, after using it a while for both news and ++mail, is that the transport mechanism has very little to do with how ++they want to treat a message. ++ ++Many people subscribe to several mailing lists. These are transported ++via @acronym{SMTP}, and are therefore mail. But we might go for weeks without ++answering, or even reading these messages very carefully. We may not ++need to save them because if we should need to read one again, they are ++archived somewhere else. ++ ++Some people have local news groups which have only a handful of readers. ++These are transported via @acronym{NNTP}, and are therefore news. But we may need ++to read and answer a large fraction of the messages very carefully in ++order to do our work. And there may not be an archive, so we may need ++to save the interesting messages the same way we would personal mail. ++ ++The important distinction turns out to be not the transport mechanism, ++but other factors such as how interested we are in the subject matter, ++or how easy it is to retrieve the message if we need to read it again. ++ ++Gnus provides many options for sorting mail into ``groups'' which behave ++like newsgroups, and for treating each group (whether mail or news) ++differently. ++ ++Some users never get comfortable using the Gnus (ahem) paradigm and wish ++that Gnus should grow up and be a male, er, mail reader. It is possible ++to whip Gnus into a more mailreaderly being, but, as said before, it's ++not easy. People who prefer proper mail readers should try @sc{vm} ++instead, which is an excellent, and proper, mail reader. ++ ++I don't mean to scare anybody off, but I want to make it clear that you ++may be required to learn a new way of thinking about messages. After ++you've been subjected to The Gnus Way, you will come to love it. I can ++guarantee it. (At least the guy who sold me the Emacs Subliminal ++Brain-Washing Functions that I've put into Gnus did guarantee it. You ++Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way. ++You Do.) ++ ++ ++@node Getting Started Reading Mail ++@subsection Getting Started Reading Mail ++ ++It's quite easy to use Gnus to read your new mail. You just plonk the ++mail back end of your choice into @code{gnus-secondary-select-methods}, ++and things will happen automatically. ++ ++For instance, if you want to use @code{nnml} (which is a ``one file per ++mail'' back end), you could put the following in your @file{~/.gnus.el} file: ++ ++@lisp ++(setq gnus-secondary-select-methods '((nnml ""))) ++@end lisp ++ ++Now, the next time you start Gnus, this back end will be queried for new ++articles, and it will move all the messages in your spool file to its ++directory, which is @file{~/Mail/} by default. The new group that will ++be created (@samp{mail.misc}) will be subscribed, and you can read it ++like any other group. ++ ++You will probably want to split the mail into several groups, though: ++ ++@lisp ++(setq nnmail-split-methods ++ '(("junk" "^From:.*Lars Ingebrigtsen") ++ ("crazy" "^Subject:.*die\\|^Organization:.*flabby") ++ ("other" ""))) ++@end lisp ++ ++This will result in three new @code{nnml} mail groups being created: ++@samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the ++mail that doesn't fit into the first two groups will be placed in the ++last group. ++ ++This should be sufficient for reading mail with Gnus. You might want to ++give the other sections in this part of the manual a perusal, though. ++Especially @pxref{Choosing a Mail Back End} and @pxref{Expiring Mail}. ++ ++ ++@node Splitting Mail ++@subsection Splitting Mail ++@cindex splitting mail ++@cindex mail splitting ++@cindex mail filtering (splitting) ++ ++@vindex nnmail-split-methods ++The @code{nnmail-split-methods} variable says how the incoming mail is ++to be split into groups. ++ ++@lisp ++(setq nnmail-split-methods ++ '(("mail.junk" "^From:.*Lars Ingebrigtsen") ++ ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby") ++ ("mail.other" ""))) ++@end lisp ++ ++This variable is a list of lists, where the first element of each of ++these lists is the name of the mail group (they do not have to be called ++something beginning with @samp{mail}, by the way), and the second ++element is a regular expression used on the header of each mail to ++determine if it belongs in this mail group. The first string may ++contain @samp{\\1} forms, like the ones used by @code{replace-match} to ++insert sub-expressions from the matched text. For instance: ++ ++@lisp ++("list.\\1" "From:.* \\(.*\\)-list@@majordomo.com") ++@end lisp ++ ++@noindent ++In that case, @code{nnmail-split-lowercase-expanded} controls whether ++the inserted text should be made lowercase. @xref{Fancy Mail Splitting}. ++ ++The second element can also be a function. In that case, it will be ++called narrowed to the headers with the first element of the rule as the ++argument. It should return a non-@code{nil} value if it thinks that the ++mail belongs in that group. ++ ++@cindex @samp{bogus} group ++The last of these groups should always be a general one, and the regular ++expression should @emph{always} be @samp{""} so that it matches any mails ++that haven't been matched by any of the other regexps. (These rules are ++processed from the beginning of the alist toward the end. The first rule ++to make a match will ``win'', unless you have crossposting enabled. In ++that case, all matching rules will ``win''.) If no rule matched, the mail ++will end up in the @samp{bogus} group. When new groups are created by ++splitting mail, you may want to run @code{gnus-group-find-new-groups} to ++see the new groups. This also applies to the @samp{bogus} group. ++ ++If you like to tinker with this yourself, you can set this variable to a ++function of your choice. This function will be called without any ++arguments in a buffer narrowed to the headers of an incoming mail ++message. The function should return a list of group names that it ++thinks should carry this mail message. ++ ++Note that the mail back ends are free to maul the poor, innocent, ++incoming headers all they want to. They all add @code{Lines} headers; ++some add @code{X-Gnus-Group} headers; most rename the Unix mbox ++@code{From} line to something else. ++ ++@vindex nnmail-crosspost ++The mail back ends all support cross-posting. If several regexps match, ++the mail will be ``cross-posted'' to all those groups. ++@code{nnmail-crosspost} says whether to use this mechanism or not. Note ++that no articles are crossposted to the general (@samp{""}) group. ++ ++@vindex nnmail-crosspost-link-function ++@cindex crosspost ++@cindex links ++@code{nnmh} and @code{nnml} makes crossposts by creating hard links to ++the crossposted articles. However, not all file systems support hard ++links. If that's the case for you, set ++@code{nnmail-crosspost-link-function} to @code{copy-file}. (This ++variable is @code{add-name-to-file} by default.) ++ ++@kindex M-x nnmail-split-history ++@findex nnmail-split-history ++If you wish to see where the previous mail split put the messages, you ++can use the @kbd{M-x nnmail-split-history} command. If you wish to see ++where re-spooling messages would put the messages, you can use ++@code{gnus-summary-respool-trace} and related commands (@pxref{Mail ++Group Commands}). ++ ++@vindex nnmail-split-header-length-limit ++Header lines longer than the value of ++@code{nnmail-split-header-length-limit} are excluded from the split ++function. ++ ++@vindex nnmail-mail-splitting-decodes ++@vindex nnmail-mail-splitting-charset ++By default, splitting does not decode headers, so you can not match on ++non-@acronym{ASCII} strings. But it is useful if you want to match ++articles based on the raw header data. To enable it, set the ++@code{nnmail-mail-splitting-decodes} variable to a non-@code{nil} value. ++In addition, the value of the @code{nnmail-mail-splitting-charset} ++variable is used for decoding non-@acronym{MIME} encoded string when ++@code{nnmail-mail-splitting-decodes} is non-@code{nil}. The default ++value is @code{nil} which means not to decode non-@acronym{MIME} encoded ++string. A suitable value for you will be @code{undecided} or be the ++charset used normally in mails you are interested in. ++ ++@vindex nnmail-resplit-incoming ++By default, splitting is performed on all incoming messages. If you ++specify a @code{directory} entry for the variable @code{mail-sources} ++(@pxref{Mail Source Specifiers}), however, then splitting does ++@emph{not} happen by default. You can set the variable ++@code{nnmail-resplit-incoming} to a non-@code{nil} value to make ++splitting happen even in this case. (This variable has no effect on ++other kinds of entries.) ++ ++Gnus gives you all the opportunity you could possibly want for shooting ++yourself in the foot. Let's say you create a group that will contain ++all the mail you get from your boss. And then you accidentally ++unsubscribe from the group. Gnus will still put all the mail from your ++boss in the unsubscribed group, and so, when your boss mails you ``Have ++that report ready by Monday or you're fired!'', you'll never see it and, ++come Tuesday, you'll still believe that you're gainfully employed while ++you really should be out collecting empty bottles to save up for next ++month's rent money. ++ ++ ++@node Mail Sources ++@subsection Mail Sources ++ ++Mail can be gotten from many different sources---the mail spool, from ++a @acronym{POP} mail server, from a procmail directory, or from a ++maildir, for instance. ++ ++@menu ++* Mail Source Specifiers:: How to specify what a mail source is. ++* Mail Source Customization:: Some variables that influence things. ++* Fetching Mail:: Using the mail source specifiers. ++@end menu ++ ++ ++@node Mail Source Specifiers ++@subsubsection Mail Source Specifiers ++@cindex POP ++@cindex mail server ++@cindex procmail ++@cindex mail spool ++@cindex mail source ++ ++You tell Gnus how to fetch mail by setting @code{mail-sources} ++(@pxref{Fetching Mail}) to a @dfn{mail source specifier}. ++ ++Here's an example: ++ ++@lisp ++(pop :server "pop3.mailserver.com" :user "myname") ++@end lisp ++ ++As can be observed, a mail source specifier is a list where the first ++element is a @dfn{mail source type}, followed by an arbitrary number of ++@dfn{keywords}. Keywords that are not explicitly specified are given ++default values. ++ ++The @code{mail-sources} is global for all mail groups. You can specify ++an additional mail source for a particular group by including the ++@code{group} mail specifier in @code{mail-sources}, and setting a ++@code{mail-source} group parameter (@pxref{Group Parameters}) specifying ++a single mail source. When this is used, @code{mail-sources} is ++typically just @code{(group)}; the @code{mail-source} parameter for a ++group might look like this: ++ ++@lisp ++(mail-source . (file :path "home/user/spools/foo.spool")) ++@end lisp ++ ++This means that the group's (and only this group's) messages will be ++fetched from the spool file @samp{/user/spools/foo.spool}. ++ ++The following mail source types are available: ++ ++@table @code ++@item file ++Get mail from a single file; typically from the mail spool. ++ ++Keywords: ++ ++@table @code ++@item :path ++The file name. Defaults to the value of the @env{MAIL} ++environment variable or the value of @code{rmail-spool-directory} ++(usually something like @file{/usr/mail/spool/user-name}). ++ ++@item :prescript ++@itemx :postscript ++Script run before/after fetching mail. ++@end table ++ ++An example file mail source: ++ ++@lisp ++(file :path "/usr/spool/mail/user-name") ++@end lisp ++ ++Or using the default file name: ++ ++@lisp ++(file) ++@end lisp ++ ++If the mail spool file is not located on the local machine, it's best ++to use @acronym{POP} or @acronym{IMAP} or the like to fetch the mail. ++You can not use ange-ftp file names here---it has no way to lock the ++mail spool while moving the mail. ++ ++If it's impossible to set up a proper server, you can use ssh instead. ++ ++@lisp ++(setq mail-sources ++ '((file :prescript "ssh host bin/getmail >%t"))) ++@end lisp ++ ++The @samp{getmail} script would look something like the following: ++ ++@example ++#!/bin/sh ++# getmail - move mail from spool to stdout ++# flu@@iki.fi ++ ++MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail ++TMP=$HOME/Mail/tmp ++rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP ++@end example ++ ++Alter this script to fit the @samp{movemail} and temporary ++file you want to use. ++ ++ ++@item directory ++@vindex nnmail-scan-directory-mail-source-once ++Get mail from several files in a directory. This is typically used ++when you have procmail split the incoming mail into several files. ++That is, there is a one-to-one correspondence between files in that ++directory and groups, so that mail from the file @file{foo.bar.spool} ++will be put in the group @code{foo.bar}. (You can change the suffix ++to be used instead of @code{.spool}.) Setting ++@code{nnmail-scan-directory-mail-source-once} to non-@code{nil} forces ++Gnus to scan the mail source only once. This is particularly useful ++if you want to scan mail groups at a specified level. ++ ++@vindex nnmail-resplit-incoming ++There is also the variable @code{nnmail-resplit-incoming}, if you set ++that to a non-@code{nil} value, then the normal splitting process is ++applied to all the files from the directory, @ref{Splitting Mail}. ++ ++Keywords: ++ ++@table @code ++@item :path ++The name of the directory where the files are. There is no default ++value. ++ ++@item :suffix ++Only files ending with this suffix are used. The default is ++@samp{.spool}. ++ ++@item :predicate ++Only files that have this predicate return non-@code{nil} are returned. ++The default is @code{identity}. This is used as an additional ++filter---only files that have the right suffix @emph{and} satisfy this ++predicate are considered. ++ ++@item :prescript ++@itemx :postscript ++Script run before/after fetching mail. ++ ++@end table ++ ++An example directory mail source: ++ ++@lisp ++(directory :path "/home/user-name/procmail-dir/" ++ :suffix ".prcml") ++@end lisp ++ ++@item pop ++Get mail from a @acronym{POP} server. ++ ++Keywords: ++ ++@table @code ++@item :server ++The name of the @acronym{POP} server. The default is taken from the ++@env{MAILHOST} environment variable. ++ ++@item :port ++The port number of the @acronym{POP} server. This can be a number (eg, ++@samp{:port 1234}) or a string (eg, @samp{:port "pop3"}). If it is a ++string, it should be a service name as listed in @file{/etc/services} on ++Unix systems. The default is @samp{"pop3"}. On some systems you might ++need to specify it as @samp{"pop-3"} instead. ++ ++@item :user ++The user name to give to the @acronym{POP} server. The default is the login ++name. ++ ++@item :password ++The password to give to the @acronym{POP} server. If not specified, ++the user is prompted. ++ ++@item :program ++The program to use to fetch mail from the @acronym{POP} server. This ++should be a @code{format}-like string. Here's an example: ++ ++@example ++fetchmail %u@@%s -P %p %t ++@end example ++ ++The valid format specifier characters are: ++ ++@table @samp ++@item t ++The name of the file the mail is to be moved to. This must always be ++included in this string. ++ ++@item s ++The name of the server. ++ ++@item P ++The port number of the server. ++ ++@item u ++The user name to use. ++ ++@item p ++The password to use. ++@end table ++ ++The values used for these specs are taken from the values you give the ++corresponding keywords. ++ ++@item :prescript ++A script to be run before fetching the mail. The syntax is the same as ++the @code{:program} keyword. This can also be a function to be run. ++ ++@item :postscript ++A script to be run after fetching the mail. The syntax is the same as ++the @code{:program} keyword. This can also be a function to be run. ++ ++@item :function ++The function to use to fetch mail from the @acronym{POP} server. The ++function is called with one parameter---the name of the file where the ++mail should be moved to. ++ ++@item :authentication ++This can be either the symbol @code{password} or the symbol @code{apop} ++and says what authentication scheme to use. The default is ++@code{password}. ++ ++@end table ++ ++@vindex pop3-movemail ++@vindex pop3-leave-mail-on-server ++If the @code{:program} and @code{:function} keywords aren't specified, ++@code{pop3-movemail} will be used. If @code{pop3-leave-mail-on-server} ++is non-@code{nil} the mail is to be left on the @acronym{POP} server ++after fetching when using @code{pop3-movemail}. Note that POP servers ++maintain no state information between sessions, so what the client ++believes is there and what is actually there may not match up. If they ++do not, then you may get duplicate mails or the whole thing can fall ++apart and leave you with a corrupt mailbox. ++ ++Here are some examples for getting mail from a @acronym{POP} server. ++Fetch from the default @acronym{POP} server, using the default user ++name, and default fetcher: ++ ++@lisp ++(pop) ++@end lisp ++ ++Fetch from a named server with a named user and password: ++ ++@lisp ++(pop :server "my.pop.server" ++ :user "user-name" :password "secret") ++@end lisp ++ ++Use @samp{movemail} to move the mail: ++ ++@lisp ++(pop :program "movemail po:%u %t %p") ++@end lisp ++ ++@item maildir ++Get mail from a maildir. This is a type of mailbox that is supported by ++at least qmail and postfix, where each file in a special directory ++contains exactly one mail. ++ ++Keywords: ++ ++@table @code ++@item :path ++The name of the directory where the mails are stored. The default is ++taken from the @env{MAILDIR} environment variable or ++@file{~/Maildir/}. ++@item :subdirs ++The subdirectories of the Maildir. The default is ++@samp{("new" "cur")}. ++ ++@c If you sometimes look at your mail through a pop3 daemon before fetching ++@c them with Gnus, you may also have to fetch your mails from the ++@c @code{cur} directory inside the maildir, like in the first example ++@c below. ++ ++You can also get mails from remote hosts (because maildirs don't suffer ++from locking problems). ++ ++@end table ++ ++Two example maildir mail sources: ++ ++@lisp ++(maildir :path "/home/user-name/Maildir/" ++ :subdirs ("cur" "new")) ++@end lisp ++ ++@lisp ++(maildir :path "/user@@remotehost.org:~/Maildir/" ++ :subdirs ("new")) ++@end lisp ++ ++@item imap ++Get mail from a @acronym{IMAP} server. If you don't want to use ++@acronym{IMAP} as intended, as a network mail reading protocol (ie ++with nnimap), for some reason or other, Gnus let you treat it similar ++to a @acronym{POP} server and fetches articles from a given ++@acronym{IMAP} mailbox. @xref{IMAP}, for more information. ++ ++Note that for the Kerberos, GSSAPI, @acronym{TLS}/@acronym{SSL} and STARTTLS support you ++may need external programs and libraries, @xref{IMAP}. ++ ++Keywords: ++ ++@table @code ++@item :server ++The name of the @acronym{IMAP} server. The default is taken from the ++@env{MAILHOST} environment variable. ++ ++@item :port ++The port number of the @acronym{IMAP} server. The default is @samp{143}, or ++@samp{993} for @acronym{TLS}/@acronym{SSL} connections. ++ ++@item :user ++The user name to give to the @acronym{IMAP} server. The default is the login ++name. ++ ++@item :password ++The password to give to the @acronym{IMAP} server. If not specified, the user is ++prompted. ++ ++@item :stream ++What stream to use for connecting to the server, this is one of the ++symbols in @code{imap-stream-alist}. Right now, this means ++@samp{gssapi}, @samp{kerberos4}, @samp{starttls}, @samp{tls}, ++@samp{ssl}, @samp{shell} or the default @samp{network}. ++ ++@item :authentication ++Which authenticator to use for authenticating to the server, this is ++one of the symbols in @code{imap-authenticator-alist}. Right now, ++this means @samp{gssapi}, @samp{kerberos4}, @samp{digest-md5}, ++@samp{cram-md5}, @samp{anonymous} or the default @samp{login}. ++ ++@item :program ++When using the `shell' :stream, the contents of this variable is ++mapped into the @code{imap-shell-program} variable. This should be a ++@code{format}-like string (or list of strings). Here's an example: ++ ++@example ++ssh %s imapd ++@end example ++ ++Make sure nothing is interfering with the output of the program, e.g., ++don't forget to redirect the error output to the void. The valid format ++specifier characters are: ++ ++@table @samp ++@item s ++The name of the server. ++ ++@item l ++User name from @code{imap-default-user}. ++ ++@item p ++The port number of the server. ++@end table ++ ++The values used for these specs are taken from the values you give the ++corresponding keywords. ++ ++@item :mailbox ++The name of the mailbox to get mail from. The default is @samp{INBOX} ++which normally is the mailbox which receives incoming mail. ++ ++@item :predicate ++The predicate used to find articles to fetch. The default, @samp{UNSEEN ++UNDELETED}, is probably the best choice for most people, but if you ++sometimes peek in your mailbox with a @acronym{IMAP} client and mark some ++articles as read (or; SEEN) you might want to set this to @samp{1:*}. ++Then all articles in the mailbox is fetched, no matter what. For a ++complete list of predicates, see RFC 2060 section 6.4.4. ++ ++@item :fetchflag ++How to flag fetched articles on the server, the default @samp{\Deleted} ++will mark them as deleted, an alternative would be @samp{\Seen} which ++would simply mark them as read. These are the two most likely choices, ++but more flags are defined in RFC 2060 section 2.3.2. ++ ++@item :dontexpunge ++If non-@code{nil}, don't remove all articles marked as deleted in the ++mailbox after finishing the fetch. ++ ++@end table ++ ++An example @acronym{IMAP} mail source: ++ ++@lisp ++(imap :server "mail.mycorp.com" ++ :stream kerberos4 ++ :fetchflag "\\Seen") ++@end lisp ++ ++@item webmail ++Get mail from a webmail server, such as @uref{http://www.hotmail.com/}, ++@uref{http://webmail.netscape.com/}, @uref{http://www.netaddress.com/}, ++@uref{http://mail.yahoo.com/}. ++ ++NOTE: Webmail largely depends on cookies. A "one-line-cookie" patch is ++required for url "4.0pre.46". ++ ++WARNING: Mails may be lost. NO WARRANTY. ++ ++Keywords: ++ ++@table @code ++@item :subtype ++The type of the webmail server. The default is @code{hotmail}. The ++alternatives are @code{netscape}, @code{netaddress}, @code{my-deja}. ++ ++@item :user ++The user name to give to the webmail server. The default is the login ++name. ++ ++@item :password ++The password to give to the webmail server. If not specified, the user is ++prompted. ++ ++@item :dontexpunge ++If non-@code{nil}, only fetch unread articles and don't move them to ++trash folder after finishing the fetch. ++ ++@end table ++ ++An example webmail source: ++ ++@lisp ++(webmail :subtype 'hotmail ++ :user "user-name" ++ :password "secret") ++@end lisp ++ ++@item group ++Get the actual mail source from the @code{mail-source} group parameter, ++@xref{Group Parameters}. ++ ++@end table ++ ++@table @dfn ++@item Common Keywords ++Common keywords can be used in any type of mail source. ++ ++Keywords: ++ ++@table @code ++@item :plugged ++If non-@code{nil}, fetch the mail even when Gnus is unplugged. If you ++use directory source to get mail, you can specify it as in this ++example: ++ ++@lisp ++(setq mail-sources ++ '((directory :path "/home/pavel/.Spool/" ++ :suffix "" ++ :plugged t))) ++@end lisp ++ ++Gnus will then fetch your mail even when you are unplugged. This is ++useful when you use local mail and news. ++ ++@end table ++@end table ++ ++@subsubsection Function Interface ++ ++Some of the above keywords specify a Lisp function to be executed. ++For each keyword @code{:foo}, the Lisp variable @code{foo} is bound to ++the value of the keyword while the function is executing. For example, ++consider the following mail-source setting: ++ ++@lisp ++(setq mail-sources '((pop :user "jrl" ++ :server "pophost" :function fetchfunc))) ++@end lisp ++ ++While the function @code{fetchfunc} is executing, the symbol @code{user} ++is bound to @code{"jrl"}, and the symbol @code{server} is bound to ++@code{"pophost"}. The symbols @code{port}, @code{password}, ++@code{program}, @code{prescript}, @code{postscript}, @code{function}, ++and @code{authentication} are also bound (to their default values). ++ ++See above for a list of keywords for each type of mail source. ++ ++ ++@node Mail Source Customization ++@subsubsection Mail Source Customization ++ ++The following is a list of variables that influence how the mail is ++fetched. You would normally not need to set or change any of these ++variables. ++ ++@table @code ++@item mail-source-crash-box ++@vindex mail-source-crash-box ++File where mail will be stored while processing it. The default is@* ++@file{~/.emacs-mail-crash-box}. ++ ++@cindex Incoming* ++@item mail-source-delete-incoming ++@vindex mail-source-delete-incoming ++If non-@code{nil}, delete incoming files after handling them. If ++@code{t}, delete the files immediately, if @code{nil}, never delete any ++files. If a positive number, delete files older than number of days ++(the deletion will only happen when receiving new mail). You may also ++set @code{mail-source-delete-incoming} to @code{nil} and call ++@code{mail-source-delete-old-incoming} from a hook or interactively. ++@code{mail-source-delete-incoming} defaults to @code{10} in alpha Gnusae ++and @code{2} in released Gnusae. @xref{Gnus Development}. ++ ++@item mail-source-delete-old-incoming-confirm ++@vindex mail-source-delete-old-incoming-confirm ++If non-@code{nil}, ask for confirmation before deleting old incoming ++files. This variable only applies when ++@code{mail-source-delete-incoming} is a positive number. ++ ++@item mail-source-ignore-errors ++@vindex mail-source-ignore-errors ++If non-@code{nil}, ignore errors when reading mail from a mail source. ++ ++@item mail-source-directory ++@vindex mail-source-directory ++Directory where incoming mail source files (if any) will be stored. The ++default is @file{~/Mail/}. At present, the only thing this is used for ++is to say where the incoming files will be stored if the variable ++@code{mail-source-delete-incoming} is @code{nil} or a number. ++ ++@item mail-source-incoming-file-prefix ++@vindex mail-source-incoming-file-prefix ++Prefix for file name for storing incoming mail. The default is ++@file{Incoming}, in which case files will end up with names like ++@file{Incoming30630D_} or @file{Incoming298602ZD}. This is really only ++relevant if @code{mail-source-delete-incoming} is @code{nil} or a ++number. ++ ++@item mail-source-default-file-modes ++@vindex mail-source-default-file-modes ++All new mail files will get this file mode. The default is 384. ++ ++@item mail-source-movemail-program ++@vindex mail-source-movemail-program ++If non-@code{nil}, name of program for fetching new mail. If ++@code{nil}, @code{movemail} in @var{exec-directory}. ++ ++@end table ++ ++ ++@node Fetching Mail ++@subsubsection Fetching Mail ++ ++@vindex mail-sources ++The way to actually tell Gnus where to get new mail from is to set ++@code{mail-sources} to a list of mail source specifiers ++(@pxref{Mail Source Specifiers}). ++ ++If this variable is @code{nil}, the mail back ends will never attempt to ++fetch mail by themselves. ++ ++If you want to fetch mail both from your local spool as well as a ++@acronym{POP} mail server, you'd say something like: ++ ++@lisp ++(setq mail-sources ++ '((file) ++ (pop :server "pop3.mail.server" ++ :password "secret"))) ++@end lisp ++ ++Or, if you don't want to use any of the keyword defaults: ++ ++@lisp ++(setq mail-sources ++ '((file :path "/var/spool/mail/user-name") ++ (pop :server "pop3.mail.server" ++ :user "user-name" ++ :port "pop3" ++ :password "secret"))) ++@end lisp ++ ++ ++When you use a mail back end, Gnus will slurp all your mail from your ++inbox and plonk it down in your home directory. Gnus doesn't move any ++mail if you're not using a mail back end---you have to do a lot of magic ++invocations first. At the time when you have finished drawing the ++pentagram, lightened the candles, and sacrificed the goat, you really ++shouldn't be too surprised when Gnus moves your mail. ++ ++ ++ ++@node Mail Back End Variables ++@subsection Mail Back End Variables ++ ++These variables are (for the most part) pertinent to all the various ++mail back ends. ++ ++@table @code ++@vindex nnmail-read-incoming-hook ++@item nnmail-read-incoming-hook ++The mail back ends all call this hook after reading new mail. You can ++use this hook to notify any mail watch programs, if you want to. ++ ++@vindex nnmail-split-hook ++@item nnmail-split-hook ++@findex gnus-article-decode-encoded-words ++@cindex RFC 1522 decoding ++@cindex RFC 2047 decoding ++Hook run in the buffer where the mail headers of each message is kept ++just before the splitting based on these headers is done. The hook is ++free to modify the buffer contents in any way it sees fit---the buffer ++is discarded after the splitting has been done, and no changes performed ++in the buffer will show up in any files. ++@code{gnus-article-decode-encoded-words} is one likely function to add ++to this hook. ++ ++@vindex nnmail-pre-get-new-mail-hook ++@vindex nnmail-post-get-new-mail-hook ++@item nnmail-pre-get-new-mail-hook ++@itemx nnmail-post-get-new-mail-hook ++These are two useful hooks executed when treating new incoming ++mail---@code{nnmail-pre-get-new-mail-hook} (is called just before ++starting to handle the new mail) and ++@code{nnmail-post-get-new-mail-hook} (is called when the mail handling ++is done). Here's and example of using these two hooks to change the ++default file modes the new mail files get: ++ ++@lisp ++(add-hook 'nnmail-pre-get-new-mail-hook ++ (lambda () (set-default-file-modes 511))) ++ ++(add-hook 'nnmail-post-get-new-mail-hook ++ (lambda () (set-default-file-modes 551))) ++@end lisp ++ ++@item nnmail-use-long-file-names ++@vindex nnmail-use-long-file-names ++If non-@code{nil}, the mail back ends will use long file and directory ++names. Groups like @samp{mail.misc} will end up in directories ++(assuming use of @code{nnml} back end) or files (assuming use of ++@code{nnfolder} back end) like @file{mail.misc}. If it is @code{nil}, ++the same group will end up in @file{mail/misc}. ++ ++@item nnmail-delete-file-function ++@vindex nnmail-delete-file-function ++@findex delete-file ++Function called to delete files. It is @code{delete-file} by default. ++ ++@item nnmail-cache-accepted-message-ids ++@vindex nnmail-cache-accepted-message-ids ++If non-@code{nil}, put the @code{Message-ID}s of articles imported into ++the back end (via @code{Gcc}, for instance) into the mail duplication ++discovery cache. The default is @code{nil}. ++ ++@item nnmail-cache-ignore-groups ++@vindex nnmail-cache-ignore-groups ++This can be a regular expression or a list of regular expressions. ++Group names that match any of the regular expressions will never be ++recorded in the @code{Message-ID} cache. ++ ++This can be useful, for example, when using Fancy Splitting ++(@pxref{Fancy Mail Splitting}) together with the function ++@code{nnmail-split-fancy-with-parent}. ++ ++@end table ++ ++ ++@node Fancy Mail Splitting ++@subsection Fancy Mail Splitting ++@cindex mail splitting ++@cindex fancy mail splitting ++ ++@vindex nnmail-split-fancy ++@findex nnmail-split-fancy ++If the rather simple, standard method for specifying how to split mail ++doesn't allow you to do what you want, you can set ++@code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can ++play with the @code{nnmail-split-fancy} variable. ++ ++Let's look at an example value of this variable first: ++ ++@lisp ++;; @r{Messages from the mailer daemon are not crossposted to any of} ++;; @r{the ordinary groups. Warnings are put in a separate group} ++;; @r{from real errors.} ++(| ("from" mail (| ("subject" "warn.*" "mail.warning") ++ "mail.misc")) ++ ;; @r{Non-error messages are crossposted to all relevant} ++ ;; @r{groups, but we don't crosspost between the group for the} ++ ;; @r{(ding) list and the group for other (ding) related mail.} ++ (& (| (any "ding@@ifi\\.uio\\.no" "ding.list") ++ ("subject" "ding" "ding.misc")) ++ ;; @r{Other mailing lists@dots{}} ++ (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list") ++ (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list") ++ ;; @r{Both lists below have the same suffix, so prevent} ++ ;; @r{cross-posting to mkpkg.list of messages posted only to} ++ ;; @r{the bugs- list, but allow cross-posting when the} ++ ;; @r{message was really cross-posted.} ++ (any "bugs-mypackage@@somewhere" "mypkg.bugs") ++ (any "mypackage@@somewhere" - "bugs-mypackage" "mypkg.list") ++ ;; @r{People@dots{}} ++ (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) ++ ;; @r{Unmatched mail goes to the catch all group.} ++ "misc.misc") ++@end lisp ++ ++This variable has the format of a @dfn{split}. A split is a ++(possibly) recursive structure where each split may contain other ++splits. Here are the possible split syntaxes: ++ ++@table @code ++ ++@item group ++If the split is a string, that will be taken as a group name. Normal ++regexp match expansion will be done. See below for examples. ++ ++@c Don't fold this line. ++@item (@var{field} @var{value} [- @var{restrict} [@dots{}] ] @var{split} [@var{invert-partial}]) ++The split can be a list containing at least three elements. If the ++first element @var{field} (a regexp matching a header) contains ++@var{value} (also a regexp) then store the message as specified by ++@var{split}. ++ ++If @var{restrict} (yet another regexp) matches some string after ++@var{field} and before the end of the matched @var{value}, the ++@var{split} is ignored. If none of the @var{restrict} clauses match, ++@var{split} is processed. ++ ++The last element @var{invert-partial} is optional. If it is ++non-@code{nil}, the match-partial-words behavior controlled by the ++variable @code{nnmail-split-fancy-match-partial-words} (see below) is ++be inverted. (New in Gnus 5.10.7) ++ ++@item (| @var{split} @dots{}) ++If the split is a list, and the first element is @code{|} (vertical ++bar), then process each @var{split} until one of them matches. A ++@var{split} is said to match if it will cause the mail message to be ++stored in one or more groups. ++ ++@item (& @var{split} @dots{}) ++If the split is a list, and the first element is @code{&}, then ++process all @var{split}s in the list. ++ ++@item junk ++If the split is the symbol @code{junk}, then don't save (i.e., delete) ++this message. Use with extreme caution. ++ ++@item (: @var{function} @var{arg1} @var{arg2} @dots{}) ++If the split is a list, and the first element is @samp{:}, then the ++second element will be called as a function with @var{args} given as ++arguments. The function should return a @var{split}. ++ ++@cindex body split ++For instance, the following function could be used to split based on the ++body of the messages: ++ ++@lisp ++(defun split-on-body () ++ (save-excursion ++ (save-restriction ++ (widen) ++ (goto-char (point-min)) ++ (when (re-search-forward "Some.*string" nil t) ++ "string.group")))) ++@end lisp ++ ++The buffer is narrowed to the header of the message in question when ++@var{function} is run. That's why @code{(widen)} needs to be called ++after @code{save-excursion} and @code{save-restriction} in the example ++above. Also note that with the nnimap backend, message bodies will ++not be downloaded by default. You need to set ++@code{nnimap-split-download-body} to @code{t} to do that ++(@pxref{Splitting in IMAP}). ++ ++@item (! @var{func} @var{split}) ++If the split is a list, and the first element is @code{!}, then ++@var{split} will be processed, and @var{func} will be called as a ++function with the result of @var{split} as argument. @var{func} ++should return a split. ++ ++@item nil ++If the split is @code{nil}, it is ignored. ++ ++@end table ++ ++In these splits, @var{field} must match a complete field name. ++ ++Normally, @var{value} in these splits must match a complete @emph{word} ++according to the fundamental mode syntax table. In other words, all ++@var{value}'s will be implicitly surrounded by @code{\<...\>} markers, ++which are word delimiters. Therefore, if you use the following split, ++for example, ++ ++@example ++(any "joe" "joemail") ++@end example ++ ++@noindent ++messages sent from @samp{joedavis@@foo.org} will normally not be filed ++in @samp{joemail}. If you want to alter this behavior, you can use any ++of the following three ways: ++ ++@enumerate ++@item ++@vindex nnmail-split-fancy-match-partial-words ++You can set the @code{nnmail-split-fancy-match-partial-words} variable ++to non-@code{nil} in order to ignore word boundaries and instead the ++match becomes more like a grep. This variable controls whether partial ++words are matched during fancy splitting. The default value is ++@code{nil}. ++ ++Note that it influences all @var{value}'s in your split rules. ++ ++@item ++@var{value} beginning with @code{.*} ignores word boundaries in front of ++a word. Similarly, if @var{value} ends with @code{.*}, word boundaries ++in the rear of a word will be ignored. For example, the @var{value} ++@code{"@@example\\.com"} does not match @samp{foo@@example.com} but ++@code{".*@@example\\.com"} does. ++ ++@item ++You can set the @var{invert-partial} flag in your split rules of the ++@samp{(@var{field} @var{value} @dots{})} types, aforementioned in this ++section. If the flag is set, word boundaries on both sides of a word ++are ignored even if @code{nnmail-split-fancy-match-partial-words} is ++@code{nil}. Contrarily, if the flag is set, word boundaries are not ++ignored even if @code{nnmail-split-fancy-match-partial-words} is ++non-@code{nil}. (New in Gnus 5.10.7) ++@end enumerate ++ ++@vindex nnmail-split-abbrev-alist ++@var{field} and @var{value} can also be Lisp symbols, in that case ++they are expanded as specified by the variable ++@code{nnmail-split-abbrev-alist}. This is an alist of cons cells, ++where the @sc{car} of a cell contains the key, and the @sc{cdr} ++contains the associated value. Predefined entries in ++@code{nnmail-split-abbrev-alist} include: ++ ++@table @code ++@item from ++Matches the @samp{From}, @samp{Sender} and @samp{Resent-From} fields. ++@item to ++Matches the @samp{To}, @samp{Cc}, @samp{Apparently-To}, ++@samp{Resent-To} and @samp{Resent-Cc} fields. ++@item any ++Is the union of the @code{from} and @code{to} entries. ++@end table ++ ++@vindex nnmail-split-fancy-syntax-table ++@code{nnmail-split-fancy-syntax-table} is the syntax table in effect ++when all this splitting is performed. ++ ++If you want to have Gnus create groups dynamically based on some ++information in the headers (i.e., do @code{replace-match}-like ++substitutions in the group names), you can say things like: ++ ++@example ++(any "debian-\\b\\(\\w+\\)@@lists.debian.org" "mail.debian.\\1") ++@end example ++ ++In this example, messages sent to @samp{debian-foo@@lists.debian.org} ++will be filed in @samp{mail.debian.foo}. ++ ++If the string contains the element @samp{\&}, then the previously ++matched string will be substituted. Similarly, the elements @samp{\\1} ++up to @samp{\\9} will be substituted with the text matched by the ++groupings 1 through 9. ++ ++@vindex nnmail-split-lowercase-expanded ++Where @code{nnmail-split-lowercase-expanded} controls whether the ++lowercase of the matched string should be used for the substitution. ++Setting it as non-@code{nil} is useful to avoid the creation of multiple ++groups when users send to an address using different case ++(i.e. mailing-list@@domain vs Mailing-List@@Domain). The default value ++is @code{t}. ++ ++@findex nnmail-split-fancy-with-parent ++@code{nnmail-split-fancy-with-parent} is a function which allows you to ++split followups into the same groups their parents are in. Sometimes ++you can't make splitting rules for all your mail. For example, your ++boss might send you personal mail regarding different projects you are ++working on, and as you can't tell your boss to put a distinguishing ++string into the subject line, you have to resort to manually moving the ++messages into the right group. With this function, you only have to do ++it once per thread. ++ ++To use this feature, you have to set @code{nnmail-treat-duplicates} ++and @code{nnmail-cache-accepted-message-ids} to a non-@code{nil} ++value. And then you can include @code{nnmail-split-fancy-with-parent} ++using the colon feature, like so: ++@lisp ++(setq nnmail-treat-duplicates 'warn ; @r{or @code{delete}} ++ nnmail-cache-accepted-message-ids t ++ nnmail-split-fancy ++ '(| (: nnmail-split-fancy-with-parent) ++ ;; @r{other splits go here} ++ )) ++@end lisp ++ ++This feature works as follows: when @code{nnmail-treat-duplicates} is ++non-@code{nil}, Gnus records the message id of every message it sees ++in the file specified by the variable ++@code{nnmail-message-id-cache-file}, together with the group it is in ++(the group is omitted for non-mail messages). When mail splitting is ++invoked, the function @code{nnmail-split-fancy-with-parent} then looks ++at the References (and In-Reply-To) header of each message to split ++and searches the file specified by @code{nnmail-message-id-cache-file} ++for the message ids. When it has found a parent, it returns the ++corresponding group name unless the group name matches the regexp ++@code{nnmail-split-fancy-with-parent-ignore-groups}. It is ++recommended that you set @code{nnmail-message-id-cache-length} to a ++somewhat higher number than the default so that the message ids are ++still in the cache. (A value of 5000 appears to create a file some ++300 kBytes in size.) ++@vindex nnmail-cache-accepted-message-ids ++When @code{nnmail-cache-accepted-message-ids} is non-@code{nil}, Gnus ++also records the message ids of moved articles, so that the followup ++messages goes into the new group. ++ ++Also see the variable @code{nnmail-cache-ignore-groups} if you don't ++want certain groups to be recorded in the cache. For example, if all ++outgoing messages are written to an ``outgoing'' group, you could set ++@code{nnmail-cache-ignore-groups} to match that group name. ++Otherwise, answers to all your messages would end up in the ++``outgoing'' group. ++ ++ ++@node Group Mail Splitting ++@subsection Group Mail Splitting ++@cindex mail splitting ++@cindex group mail splitting ++ ++@findex gnus-group-split ++If you subscribe to dozens of mailing lists but you don't want to ++maintain mail splitting rules manually, group mail splitting is for you. ++You just have to set @code{to-list} and/or @code{to-address} in group ++parameters or group customization and set @code{nnmail-split-methods} to ++@code{gnus-group-split}. This splitting function will scan all groups ++for those parameters and split mail accordingly, i.e., messages posted ++from or to the addresses specified in the parameters @code{to-list} or ++@code{to-address} of a mail group will be stored in that group. ++ ++Sometimes, mailing lists have multiple addresses, and you may want mail ++splitting to recognize them all: just set the @code{extra-aliases} group ++parameter to the list of additional addresses and it's done. If you'd ++rather use a regular expression, set @code{split-regexp}. ++ ++All these parameters in a group will be used to create an ++@code{nnmail-split-fancy} split, in which the @var{field} is @samp{any}, ++the @var{value} is a single regular expression that matches ++@code{to-list}, @code{to-address}, all of @code{extra-aliases} and all ++matches of @code{split-regexp}, and the @var{split} is the name of the ++group. @var{restrict}s are also supported: just set the ++@code{split-exclude} parameter to a list of regular expressions. ++ ++If you can't get the right split to be generated using all these ++parameters, or you just need something fancier, you can set the ++parameter @code{split-spec} to an @code{nnmail-split-fancy} split. In ++this case, all other aforementioned parameters will be ignored by ++@code{gnus-group-split}. In particular, @code{split-spec} may be set to ++@code{nil}, in which case the group will be ignored by ++@code{gnus-group-split}. ++ ++@vindex gnus-group-split-default-catch-all-group ++@code{gnus-group-split} will do cross-posting on all groups that match, ++by defining a single @code{&} fancy split containing one split for each ++group. If a message doesn't match any split, it will be stored in the ++group named in @code{gnus-group-split-default-catch-all-group}, unless ++some group has @code{split-spec} set to @code{catch-all}, in which case ++that group is used as the catch-all group. Even though this variable is ++often used just to name a group, it may also be set to an arbitrarily ++complex fancy split (after all, a group name is a fancy split), and this ++may be useful to split mail that doesn't go to any mailing list to ++personal mail folders. Note that this fancy split is added as the last ++element of a @code{|} split list that also contains a @code{&} split ++with the rules extracted from group parameters. ++ ++It's time for an example. Assume the following group parameters have ++been defined: ++ ++@example ++nnml:mail.bar: ++((to-address . "bar@@femail.com") ++ (split-regexp . ".*@@femail\\.com")) ++nnml:mail.foo: ++((to-list . "foo@@nowhere.gov") ++ (extra-aliases "foo@@localhost" "foo-redist@@home") ++ (split-exclude "bugs-foo" "rambling-foo") ++ (admin-address . "foo-request@@nowhere.gov")) ++nnml:mail.others: ++((split-spec . catch-all)) ++@end example ++ ++Setting @code{nnmail-split-methods} to @code{gnus-group-split} will ++behave as if @code{nnmail-split-fancy} had been selected and variable ++@code{nnmail-split-fancy} had been set as follows: ++ ++@lisp ++(| (& (any "\\(bar@@femail\\.com\\|.*@@femail\\.com\\)" "mail.bar") ++ (any "\\(foo@@nowhere\\.gov\\|foo@@localhost\\|foo-redist@@home\\)" ++ - "bugs-foo" - "rambling-foo" "mail.foo")) ++ "mail.others") ++@end lisp ++ ++@findex gnus-group-split-fancy ++If you'd rather not use group splitting for all your mail groups, you ++may use it for only some of them, by using @code{nnmail-split-fancy} ++splits like this: ++ ++@lisp ++(: gnus-group-split-fancy @var{groups} @var{no-crosspost} @var{catch-all}) ++@end lisp ++ ++@var{groups} may be a regular expression or a list of group names whose ++parameters will be scanned to generate the output split. ++@var{no-crosspost} can be used to disable cross-posting; in this case, a ++single @code{|} split will be output. @var{catch-all} is the fall back ++fancy split, used like @code{gnus-group-split-default-catch-all-group}. ++If @var{catch-all} is @code{nil}, or if @code{split-regexp} matches the ++empty string in any selected group, no catch-all split will be issued. ++Otherwise, if some group has @code{split-spec} set to @code{catch-all}, ++this group will override the value of the @var{catch-all} argument. ++ ++@findex gnus-group-split-setup ++Unfortunately, scanning all groups and their parameters can be quite ++slow, especially considering that it has to be done for every message. ++But don't despair! The function @code{gnus-group-split-setup} can be ++used to enable @code{gnus-group-split} in a much more efficient way. It ++sets @code{nnmail-split-methods} to @code{nnmail-split-fancy} and sets ++@code{nnmail-split-fancy} to the split produced by ++@code{gnus-group-split-fancy}. Thus, the group parameters are only ++scanned once, no matter how many messages are split. ++ ++@findex gnus-group-split-update ++However, if you change group parameters, you'd have to update ++@code{nnmail-split-fancy} manually. You can do it by running ++@code{gnus-group-split-update}. If you'd rather have it updated ++automatically, just tell @code{gnus-group-split-setup} to do it for ++you. For example, add to your @file{~/.gnus.el}: ++ ++@lisp ++(gnus-group-split-setup @var{auto-update} @var{catch-all}) ++@end lisp ++ ++If @var{auto-update} is non-@code{nil}, @code{gnus-group-split-update} ++will be added to @code{nnmail-pre-get-new-mail-hook}, so you won't ever ++have to worry about updating @code{nnmail-split-fancy} again. If you ++don't omit @var{catch-all} (it's optional, equivalent to @code{nil}), ++@code{gnus-group-split-default-catch-all-group} will be set to its ++value. ++ ++@vindex gnus-group-split-updated-hook ++Because you may want to change @code{nnmail-split-fancy} after it is set ++by @code{gnus-group-split-update}, this function will run ++@code{gnus-group-split-updated-hook} just before finishing. ++ ++@node Incorporating Old Mail ++@subsection Incorporating Old Mail ++@cindex incorporating old mail ++@cindex import old mail ++ ++Most people have lots of old mail stored in various file formats. If ++you have set up Gnus to read mail using one of the spiffy Gnus mail ++back ends, you'll probably wish to have that old mail incorporated into ++your mail groups. ++ ++Doing so can be quite easy. ++ ++To take an example: You're reading mail using @code{nnml} ++(@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a ++satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox ++file filled with important, but old, mail. You want to move it into ++your @code{nnml} groups. ++ ++Here's how: ++ ++@enumerate ++@item ++Go to the group buffer. ++ ++@item ++Type @kbd{G f} and give the file name to the mbox file when prompted to create an ++@code{nndoc} group from the mbox file (@pxref{Foreign Groups}). ++ ++@item ++Type @kbd{SPACE} to enter the newly created group. ++ ++@item ++Type @kbd{M P b} to process-mark all articles in this group's buffer ++(@pxref{Setting Process Marks}). ++ ++@item ++Type @kbd{B r} to respool all the process-marked articles, and answer ++@samp{nnml} when prompted (@pxref{Mail Group Commands}). ++@end enumerate ++ ++All the mail messages in the mbox file will now also be spread out over ++all your @code{nnml} groups. Try entering them and check whether things ++have gone without a glitch. If things look ok, you may consider ++deleting the mbox file, but I wouldn't do that unless I was absolutely ++sure that all the mail has ended up where it should be. ++ ++Respooling is also a handy thing to do if you're switching from one mail ++back end to another. Just respool all the mail in the old mail groups ++using the new mail back end. ++ ++ ++@node Expiring Mail ++@subsection Expiring Mail ++@cindex article expiry ++@cindex expiring mail ++ ++Traditional mail readers have a tendency to remove mail articles when ++you mark them as read, in some way. Gnus takes a fundamentally ++different approach to mail reading. ++ ++Gnus basically considers mail just to be news that has been received in ++a rather peculiar manner. It does not think that it has the power to ++actually change the mail, or delete any mail messages. If you enter a ++mail group, and mark articles as ``read'', or kill them in some other ++fashion, the mail articles will still exist on the system. I repeat: ++Gnus will not delete your old, read mail. Unless you ask it to, of ++course. ++ ++To make Gnus get rid of your unwanted mail, you have to mark the ++articles as @dfn{expirable}. (With the default key bindings, this means ++that you have to type @kbd{E}.) This does not mean that the articles ++will disappear right away, however. In general, a mail article will be ++deleted from your system if, 1) it is marked as expirable, AND 2) it is ++more than one week old. If you do not mark an article as expirable, it ++will remain on your system until hell freezes over. This bears ++repeating one more time, with some spurious capitalizations: IF you do ++NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES. ++ ++You do not have to mark articles as expirable by hand. Gnus provides ++two features, called ``auto-expire'' and ``total-expire'', that can help you ++with this. In a nutshell, ``auto-expire'' means that Gnus hits @kbd{E} ++for you when you select an article. And ``total-expire'' means that Gnus ++considers all articles as expirable that are read. So, in addition to ++the articles marked @samp{E}, also the articles marked @samp{r}, ++@samp{R}, @samp{O}, @samp{K}, @samp{Y} and so on are considered ++expirable. ++ ++When should either auto-expire or total-expire be used? Most people ++who are subscribed to mailing lists split each list into its own group ++and then turn on auto-expire or total-expire for those groups. ++(@xref{Splitting Mail}, for more information on splitting each list ++into its own group.) ++ ++Which one is better, auto-expire or total-expire? It's not easy to ++answer. Generally speaking, auto-expire is probably faster. Another ++advantage of auto-expire is that you get more marks to work with: for ++the articles that are supposed to stick around, you can still choose ++between tick and dormant and read marks. But with total-expire, you ++only have dormant and ticked to choose from. The advantage of ++total-expire is that it works well with adaptive scoring (@pxref{Adaptive ++Scoring}). Auto-expire works with normal scoring but not with adaptive ++scoring. ++ ++@vindex gnus-auto-expirable-newsgroups ++Groups that match the regular expression ++@code{gnus-auto-expirable-newsgroups} will have all articles that you ++read marked as expirable automatically. All articles marked as ++expirable have an @samp{E} in the first column in the summary buffer. ++ ++By default, if you have auto expiry switched on, Gnus will mark all the ++articles you read as expirable, no matter if they were read or unread ++before. To avoid having articles marked as read marked as expirable ++automatically, you can put something like the following in your ++@file{~/.gnus.el} file: ++ ++@vindex gnus-mark-article-hook ++@lisp ++(remove-hook 'gnus-mark-article-hook ++ 'gnus-summary-mark-read-and-unread-as-read) ++(add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read) ++@end lisp ++ ++Note that making a group auto-expirable doesn't mean that all read ++articles are expired---only the articles marked as expirable ++will be expired. Also note that using the @kbd{d} command won't make ++articles expirable---only semi-automatic marking of articles as read will ++mark the articles as expirable in auto-expirable groups. ++ ++Let's say you subscribe to a couple of mailing lists, and you want the ++articles you have read to disappear after a while: ++ ++@lisp ++(setq gnus-auto-expirable-newsgroups ++ "mail.nonsense-list\\|mail.nice-list") ++@end lisp ++ ++Another way to have auto-expiry happen is to have the element ++@code{auto-expire} in the group parameters of the group. ++ ++If you use adaptive scoring (@pxref{Adaptive Scoring}) and ++auto-expiring, you'll have problems. Auto-expiring and adaptive scoring ++don't really mix very well. ++ ++@vindex nnmail-expiry-wait ++The @code{nnmail-expiry-wait} variable supplies the default time an ++expirable article has to live. Gnus starts counting days from when the ++message @emph{arrived}, not from when it was sent. The default is seven ++days. ++ ++Gnus also supplies a function that lets you fine-tune how long articles ++are to live, based on what group they are in. Let's say you want to ++have one month expiry period in the @samp{mail.private} group, a one day ++expiry period in the @samp{mail.junk} group, and a six day expiry period ++everywhere else: ++ ++@vindex nnmail-expiry-wait-function ++@lisp ++(setq nnmail-expiry-wait-function ++ (lambda (group) ++ (cond ((string= group "mail.private") ++ 31) ++ ((string= group "mail.junk") ++ 1) ++ ((string= group "important") ++ 'never) ++ (t ++ 6)))) ++@end lisp ++ ++The group names this function is fed are ``unadorned'' group ++names---no @samp{nnml:} prefixes and the like. ++ ++The @code{nnmail-expiry-wait} variable and ++@code{nnmail-expiry-wait-function} function can either be a number (not ++necessarily an integer) or one of the symbols @code{immediate} or ++@code{never}. ++ ++You can also use the @code{expiry-wait} group parameter to selectively ++change the expiry period (@pxref{Group Parameters}). ++ ++@vindex nnmail-expiry-target ++The normal action taken when expiring articles is to delete them. ++However, in some circumstances it might make more sense to move them ++to other groups instead of deleting them. The variable ++@code{nnmail-expiry-target} (and the @code{expiry-target} group ++parameter) controls this. The variable supplies a default value for ++all groups, which can be overridden for specific groups by the group ++parameter. default value is @code{delete}, but this can also be a ++string (which should be the name of the group the message should be ++moved to), or a function (which will be called in a buffer narrowed to ++the message in question, and with the name of the group being moved ++from as its parameter) which should return a target---either a group ++name or @code{delete}. ++ ++Here's an example for specifying a group name: ++@lisp ++(setq nnmail-expiry-target "nnml:expired") ++@end lisp ++ ++@findex nnmail-fancy-expiry-target ++@vindex nnmail-fancy-expiry-targets ++Gnus provides a function @code{nnmail-fancy-expiry-target} which will ++expire mail to groups according to the variable ++@code{nnmail-fancy-expiry-targets}. Here's an example: ++ ++@lisp ++ (setq nnmail-expiry-target 'nnmail-fancy-expiry-target ++ nnmail-fancy-expiry-targets ++ '((to-from "boss" "nnfolder:Work") ++ ("subject" "IMPORTANT" "nnfolder:IMPORTANT.%Y.%b") ++ ("from" ".*" "nnfolder:Archive-%Y"))) ++@end lisp ++ ++With this setup, any mail that has @code{IMPORTANT} in its Subject ++header and was sent in the year @code{YYYY} and month @code{MMM}, will ++get expired to the group @code{nnfolder:IMPORTANT.YYYY.MMM}. If its ++From or To header contains the string @code{boss}, it will get expired ++to @code{nnfolder:Work}. All other mail will get expired to ++@code{nnfolder:Archive-YYYY}. ++ ++@vindex nnmail-keep-last-article ++If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never ++expire the final article in a mail newsgroup. This is to make life ++easier for procmail users. ++ ++@vindex gnus-total-expirable-newsgroups ++By the way: That line up there, about Gnus never expiring non-expirable ++articles, is a lie. If you put @code{total-expire} in the group ++parameters, articles will not be marked as expirable, but all read ++articles will be put through the expiry process. Use with extreme ++caution. Even more dangerous is the ++@code{gnus-total-expirable-newsgroups} variable. All groups that match ++this regexp will have all read articles put through the expiry process, ++which means that @emph{all} old mail articles in the groups in question ++will be deleted after a while. Use with extreme caution, and don't come ++crying to me when you discover that the regexp you used matched the ++wrong group and all your important mail has disappeared. Be a ++@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable ++with! So there! ++ ++Most people make most of their mail groups total-expirable, though. ++ ++@vindex gnus-inhibit-user-auto-expire ++If @code{gnus-inhibit-user-auto-expire} is non-@code{nil}, user marking ++commands will not mark an article as expirable, even if the group has ++auto-expire turned on. ++ ++ ++@node Washing Mail ++@subsection Washing Mail ++@cindex mail washing ++@cindex list server brain damage ++@cindex incoming mail treatment ++ ++Mailers and list servers are notorious for doing all sorts of really, ++really stupid things with mail. ``Hey, RFC 822 doesn't explicitly ++prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the ++end of all lines passing through our server, so let's do that!!!!1!'' ++Yes, but RFC 822 wasn't designed to be read by morons. Things that were ++considered to be self-evident were not discussed. So. Here we are. ++ ++Case in point: The German version of Microsoft Exchange adds @samp{AW: ++} to the subjects of replies instead of @samp{Re: }. I could pretend to ++be shocked and dismayed by this, but I haven't got the energy. It is to ++laugh. ++ ++Gnus provides a plethora of functions for washing articles while ++displaying them, but it might be nicer to do the filtering before ++storing the mail to disk. For that purpose, we have three hooks and ++various functions that can be put in these hooks. ++ ++@table @code ++@item nnmail-prepare-incoming-hook ++@vindex nnmail-prepare-incoming-hook ++This hook is called before doing anything with the mail and is meant for ++grand, sweeping gestures. It is called in a buffer that contains all ++the new, incoming mail. Functions to be used include: ++ ++@table @code ++@item nnheader-ms-strip-cr ++@findex nnheader-ms-strip-cr ++Remove trailing carriage returns from each line. This is default on ++Emacs running on MS machines. ++ ++@end table ++ ++@item nnmail-prepare-incoming-header-hook ++@vindex nnmail-prepare-incoming-header-hook ++This hook is called narrowed to each header. It can be used when ++cleaning up the headers. Functions that can be used include: ++ ++@table @code ++@item nnmail-remove-leading-whitespace ++@findex nnmail-remove-leading-whitespace ++Clear leading white space that ``helpful'' listservs have added to the ++headers to make them look nice. Aaah. ++ ++(Note that this function works on both the header on the body of all ++messages, so it is a potentially dangerous function to use (if a body ++of a message contains something that looks like a header line). So ++rather than fix the bug, it is of course the right solution to make it ++into a feature by documenting it.) ++ ++@item nnmail-remove-list-identifiers ++@findex nnmail-remove-list-identifiers ++Some list servers add an identifier---for example, @samp{(idm)}---to the ++beginning of all @code{Subject} headers. I'm sure that's nice for ++people who use stone age mail readers. This function will remove ++strings that match the @code{nnmail-list-identifiers} regexp, which can ++also be a list of regexp. @code{nnmail-list-identifiers} may not contain ++@code{\\(..\\)}. ++ ++For instance, if you want to remove the @samp{(idm)} and the ++@samp{nagnagnag} identifiers: ++ ++@lisp ++(setq nnmail-list-identifiers ++ '("(idm)" "nagnagnag")) ++@end lisp ++ ++This can also be done non-destructively with ++@code{gnus-list-identifiers}, @xref{Article Hiding}. ++ ++@item nnmail-remove-tabs ++@findex nnmail-remove-tabs ++Translate all @samp{TAB} characters into @samp{SPACE} characters. ++ ++@item nnmail-ignore-broken-references ++@findex nnmail-ignore-broken-references ++@c @findex nnmail-fix-eudora-headers ++@cindex Eudora ++@cindex Pegasus ++Some mail user agents (e.g. Eudora and Pegasus) produce broken ++@code{References} headers, but correct @code{In-Reply-To} headers. This ++function will get rid of the @code{References} header if the headers ++contain a line matching the regular expression ++@code{nnmail-broken-references-mailers}. ++ ++@end table ++ ++@item nnmail-prepare-incoming-message-hook ++@vindex nnmail-prepare-incoming-message-hook ++This hook is called narrowed to each message. Functions to be used ++include: ++ ++@table @code ++@item article-de-quoted-unreadable ++@findex article-de-quoted-unreadable ++Decode Quoted Readable encoding. ++ ++@end table ++@end table ++ ++ ++@node Duplicates ++@subsection Duplicates ++ ++@vindex nnmail-treat-duplicates ++@vindex nnmail-message-id-cache-length ++@vindex nnmail-message-id-cache-file ++@cindex duplicate mails ++If you are a member of a couple of mailing lists, you will sometimes ++receive two copies of the same mail. This can be quite annoying, so ++@code{nnmail} checks for and treats any duplicates it might find. To do ++this, it keeps a cache of old @code{Message-ID}s--- ++@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by ++default. The approximate maximum number of @code{Message-ID}s stored ++there is controlled by the @code{nnmail-message-id-cache-length} ++variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be ++stored.) If all this sounds scary to you, you can set ++@code{nnmail-treat-duplicates} to @code{warn} (which is what it is by ++default), and @code{nnmail} won't delete duplicate mails. Instead it ++will insert a warning into the head of the mail saying that it thinks ++that this is a duplicate of a different message. ++ ++This variable can also be a function. If that's the case, the function ++will be called from a buffer narrowed to the message in question with ++the @code{Message-ID} as a parameter. The function must return either ++@code{nil}, @code{warn}, or @code{delete}. ++ ++You can turn this feature off completely by setting the variable to ++@code{nil}. ++ ++If you want all the duplicate mails to be put into a special ++@dfn{duplicates} group, you could do that using the normal mail split ++methods: ++ ++@lisp ++(setq nnmail-split-fancy ++ '(| ;; @r{Messages duplicates go to a separate group.} ++ ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate") ++ ;; @r{Message from daemons, postmaster, and the like to another.} ++ (any mail "mail.misc") ++ ;; @r{Other rules.} ++ [...] )) ++@end lisp ++@noindent ++Or something like: ++@lisp ++(setq nnmail-split-methods ++ '(("duplicates" "^Gnus-Warning:.*duplicate") ++ ;; @r{Other rules.} ++ [...])) ++@end lisp ++ ++Here's a neat feature: If you know that the recipient reads her mail ++with Gnus, and that she has @code{nnmail-treat-duplicates} set to ++@code{delete}, you can send her as many insults as you like, just by ++using a @code{Message-ID} of a mail that you know that she's already ++received. Think of all the fun! She'll never see any of it! Whee! ++ ++ ++@node Not Reading Mail ++@subsection Not Reading Mail ++ ++If you start using any of the mail back ends, they have the annoying ++habit of assuming that you want to read mail with them. This might not ++be unreasonable, but it might not be what you want. ++ ++If you set @code{mail-sources} and @code{nnmail-spool-file} to ++@code{nil}, none of the back ends will ever attempt to read incoming ++mail, which should help. ++ ++@vindex nnbabyl-get-new-mail ++@vindex nnmbox-get-new-mail ++@vindex nnml-get-new-mail ++@vindex nnmh-get-new-mail ++@vindex nnfolder-get-new-mail ++This might be too much, if, for instance, you are reading mail quite ++happily with @code{nnml} and just want to peek at some old (pre-Emacs ++23) Rmail file you have stashed away with @code{nnbabyl}. All back ends have ++variables called back-end-@code{get-new-mail}. If you want to disable ++the @code{nnbabyl} mail reading, you edit the virtual server for the ++group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}. ++ ++All the mail back ends will call @code{nn}*@code{-prepare-save-mail-hook} ++narrowed to the article to be saved before saving it when reading ++incoming mail. ++ ++ ++@node Choosing a Mail Back End ++@subsection Choosing a Mail Back End ++ ++Gnus will read the mail spool when you activate a mail group. The mail ++file is first copied to your home directory. What happens after that ++depends on what format you want to store your mail in. ++ ++There are six different mail back ends in the standard Gnus, and more ++back ends are available separately. The mail back end most people use ++(because it is possibly the fastest) is @code{nnml} (@pxref{Mail ++Spool}). ++ ++@menu ++* Unix Mail Box:: Using the (quite) standard Un*x mbox. ++* Babyl:: Babyl was used by older versions of Rmail. ++* Mail Spool:: Store your mail in a private spool? ++* MH Spool:: An mhspool-like back end. ++* Maildir:: Another one-file-per-message format. ++* Mail Folders:: Having one file for each group. ++* Comparing Mail Back Ends:: An in-depth looks at pros and cons. ++@end menu ++ ++ ++@node Unix Mail Box ++@subsubsection Unix Mail Box ++@cindex nnmbox ++@cindex unix mail box ++ ++@vindex nnmbox-active-file ++@vindex nnmbox-mbox-file ++The @dfn{nnmbox} back end will use the standard Un*x mbox file to store ++mail. @code{nnmbox} will add extra headers to each mail article to say ++which group it belongs in. ++ ++Virtual server settings: ++ ++@table @code ++@item nnmbox-mbox-file ++@vindex nnmbox-mbox-file ++The name of the mail box in the user's home directory. Default is ++@file{~/mbox}. ++ ++@item nnmbox-active-file ++@vindex nnmbox-active-file ++The name of the active file for the mail box. Default is ++@file{~/.mbox-active}. ++ ++@item nnmbox-get-new-mail ++@vindex nnmbox-get-new-mail ++If non-@code{nil}, @code{nnmbox} will read incoming mail and split it ++into groups. Default is @code{t}. ++@end table ++ ++ ++@node Babyl ++@subsubsection Babyl ++@cindex nnbabyl ++ ++@vindex nnbabyl-active-file ++@vindex nnbabyl-mbox-file ++The @dfn{nnbabyl} back end will use a Babyl mail box to store mail. ++@code{nnbabyl} will add extra headers to each mail article to say which ++group it belongs in. ++ ++Virtual server settings: ++ ++@table @code ++@item nnbabyl-mbox-file ++@vindex nnbabyl-mbox-file ++The name of the Babyl file. The default is @file{~/RMAIL} ++ ++@item nnbabyl-active-file ++@vindex nnbabyl-active-file ++The name of the active file for the Babyl file. The default is ++@file{~/.rmail-active} ++ ++@item nnbabyl-get-new-mail ++@vindex nnbabyl-get-new-mail ++If non-@code{nil}, @code{nnbabyl} will read incoming mail. Default is ++@code{t} ++@end table ++ ++ ++@node Mail Spool ++@subsubsection Mail Spool ++@cindex nnml ++@cindex mail @acronym{NOV} spool ++ ++The @dfn{nnml} spool mail format isn't compatible with any other known ++format. It should be used with some caution. ++ ++@vindex nnml-directory ++If you use this back end, Gnus will split all incoming mail into files, ++one file for each mail, and put the articles into the corresponding ++directories under the directory specified by the @code{nnml-directory} ++variable. The default value is @file{~/Mail/}. ++ ++You do not have to create any directories beforehand; Gnus will take ++care of all that. ++ ++If you have a strict limit as to how many files you are allowed to store ++in your account, you should not use this back end. As each mail gets its ++own file, you might very well occupy thousands of inodes within a few ++weeks. If this is no problem for you, and it isn't a problem for you ++having your friendly systems administrator walking around, madly, ++shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should ++know that this is probably the fastest format to use. You do not have ++to trudge through a big mbox file just to read your new mail. ++ ++@code{nnml} is probably the slowest back end when it comes to article ++splitting. It has to create lots of files, and it also generates ++@acronym{NOV} databases for the incoming mails. This makes it possibly the ++fastest back end when it comes to reading mail. ++ ++@cindex self contained nnml servers ++@cindex marks ++When the marks file is used (which it is by default), @code{nnml} ++servers have the property that you may backup them using @code{tar} or ++similar, and later be able to restore them into Gnus (by adding the ++proper @code{nnml} server) and have all your marks be preserved. Marks ++for a group are usually stored in the @code{.marks} file (but see ++@code{nnml-marks-file-name}) within each @code{nnml} group's directory. ++Individual @code{nnml} groups are also possible to backup, use @kbd{G m} ++to restore the group (after restoring the backup into the nnml ++directory). ++ ++If for some reason you believe your @file{.marks} files are screwed ++up, you can just delete them all. Gnus will then correctly regenerate ++them next time it starts. ++ ++Virtual server settings: ++ ++@table @code ++@item nnml-directory ++@vindex nnml-directory ++All @code{nnml} directories will be placed under this directory. The ++default is the value of @code{message-directory} (whose default value ++is @file{~/Mail}). ++ ++@item nnml-active-file ++@vindex nnml-active-file ++The active file for the @code{nnml} server. The default is ++@file{~/Mail/active}. ++ ++@item nnml-newsgroups-file ++@vindex nnml-newsgroups-file ++The @code{nnml} group descriptions file. @xref{Newsgroups File ++Format}. The default is @file{~/Mail/newsgroups}. ++ ++@item nnml-get-new-mail ++@vindex nnml-get-new-mail ++If non-@code{nil}, @code{nnml} will read incoming mail. The default is ++@code{t}. ++ ++@item nnml-nov-is-evil ++@vindex nnml-nov-is-evil ++If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The ++default is @code{nil}. ++ ++@item nnml-nov-file-name ++@vindex nnml-nov-file-name ++The name of the @acronym{NOV} files. The default is @file{.overview}. ++ ++@item nnml-prepare-save-mail-hook ++@vindex nnml-prepare-save-mail-hook ++Hook run narrowed to an article before saving. ++ ++@item nnml-marks-is-evil ++@vindex nnml-marks-is-evil ++If non-@code{nil}, this back end will ignore any @sc{marks} files. The ++default is @code{nil}. ++ ++@item nnml-marks-file-name ++@vindex nnml-marks-file-name ++The name of the @dfn{marks} files. The default is @file{.marks}. ++ ++@item nnml-use-compressed-files ++@vindex nnml-use-compressed-files ++If non-@code{nil}, @code{nnml} will allow using compressed message ++files. This requires @code{auto-compression-mode} to be enabled ++(@pxref{Compressed Files, ,Compressed Files, emacs, The Emacs Manual}). ++If the value of @code{nnml-use-compressed-files} is a string, it is used ++as the file extension specifying the compression program. You can set it ++to @samp{.bz2} if your Emacs supports it. A value of @code{t} is ++equivalent to @samp{.gz}. ++ ++@item nnml-compressed-files-size-threshold ++@vindex nnml-compressed-files-size-threshold ++Default size threshold for compressed message files. Message files with ++bodies larger than that many characters will be automatically compressed ++if @code{nnml-use-compressed-files} is non-@code{nil}. ++ ++@end table ++ ++@findex nnml-generate-nov-databases ++If your @code{nnml} groups and @acronym{NOV} files get totally out of ++whack, you can do a complete update by typing @kbd{M-x ++nnml-generate-nov-databases}. This command will trawl through the ++entire @code{nnml} hierarchy, looking at each and every article, so it ++might take a while to complete. A better interface to this ++functionality can be found in the server buffer (@pxref{Server ++Commands}). ++ ++ ++@node MH Spool ++@subsubsection MH Spool ++@cindex nnmh ++@cindex mh-e mail spool ++ ++@code{nnmh} is just like @code{nnml}, except that is doesn't generate ++@acronym{NOV} databases and it doesn't keep an active file or marks ++file. This makes @code{nnmh} a @emph{much} slower back end than ++@code{nnml}, but it also makes it easier to write procmail scripts ++for. ++ ++Virtual server settings: ++ ++@table @code ++@item nnmh-directory ++@vindex nnmh-directory ++All @code{nnmh} directories will be located under this directory. The ++default is the value of @code{message-directory} (whose default is ++@file{~/Mail}) ++ ++@item nnmh-get-new-mail ++@vindex nnmh-get-new-mail ++If non-@code{nil}, @code{nnmh} will read incoming mail. The default is ++@code{t}. ++ ++@item nnmh-be-safe ++@vindex nnmh-be-safe ++If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make ++sure that the articles in the folder are actually what Gnus thinks ++they are. It will check date stamps and stat everything in sight, so ++setting this to @code{t} will mean a serious slow-down. If you never ++use anything but Gnus to read the @code{nnmh} articles, you do not ++have to set this variable to @code{t}. The default is @code{nil}. ++@end table ++ ++ ++@node Maildir ++@subsubsection Maildir ++@cindex nnmaildir ++@cindex maildir ++ ++@code{nnmaildir} stores mail in the maildir format, with each maildir ++corresponding to a group in Gnus. This format is documented here: ++@uref{http://cr.yp.to/proto/maildir.html} and here: ++@uref{http://www.qmail.org/man/man5/maildir.html}. @code{nnmaildir} ++also stores extra information in the @file{.nnmaildir/} directory ++within a maildir. ++ ++Maildir format was designed to allow concurrent deliveries and ++reading, without needing locks. With other back ends, you would have ++your mail delivered to a spool of some kind, and then you would ++configure Gnus to split mail from that spool into your groups. You ++can still do that with @code{nnmaildir}, but the more common ++configuration is to have your mail delivered directly to the maildirs ++that appear as group in Gnus. ++ ++@code{nnmaildir} is designed to be perfectly reliable: @kbd{C-g} will ++never corrupt its data in memory, and @code{SIGKILL} will never ++corrupt its data in the filesystem. ++ ++@code{nnmaildir} stores article marks and @acronym{NOV} data in each ++maildir. So you can copy a whole maildir from one Gnus setup to ++another, and you will keep your marks. ++ ++Virtual server settings: ++ ++@table @code ++@item directory ++For each of your @code{nnmaildir} servers (it's very unlikely that ++you'd need more than one), you need to create a directory and populate ++it with maildirs or symlinks to maildirs (and nothing else; do not ++choose a directory already used for other purposes). Each maildir ++will be represented in Gnus as a newsgroup on that server; the ++filename of the symlink will be the name of the group. Any filenames ++in the directory starting with @samp{.} are ignored. The directory is ++scanned when you first start Gnus, and each time you type @kbd{g} in ++the group buffer; if any maildirs have been removed or added, ++@code{nnmaildir} notices at these times. ++ ++The value of the @code{directory} parameter should be a Lisp form ++which is processed by @code{eval} and @code{expand-file-name} to get ++the path of the directory for this server. The form is @code{eval}ed ++only when the server is opened; the resulting string is used until the ++server is closed. (If you don't know about forms and @code{eval}, ++don't worry---a simple string will work.) This parameter is not ++optional; you must specify it. I don't recommend using ++@code{"~/Mail"} or a subdirectory of it; several other parts of Gnus ++use that directory by default for various things, and may get confused ++if @code{nnmaildir} uses it too. @code{"~/.nnmaildir"} is a typical ++value. ++ ++@item target-prefix ++This should be a Lisp form which is processed by @code{eval} and ++@code{expand-file-name}. The form is @code{eval}ed only when the ++server is opened; the resulting string is used until the server is ++closed. ++ ++When you create a group on an @code{nnmaildir} server, the maildir is ++created with @code{target-prefix} prepended to its name, and a symlink ++pointing to that maildir is created, named with the plain group name. ++So if @code{directory} is @code{"~/.nnmaildir"} and ++@code{target-prefix} is @code{"../maildirs/"}, then when you create ++the group @code{foo}, @code{nnmaildir} will create ++@file{~/.nnmaildir/../maildirs/foo} as a maildir, and will create ++@file{~/.nnmaildir/foo} as a symlink pointing to ++@file{../maildirs/foo}. ++ ++You can set @code{target-prefix} to a string without any slashes to ++create both maildirs and symlinks in the same @code{directory}; in ++this case, any maildirs found in @code{directory} whose names start ++with @code{target-prefix} will not be listed as groups (but the ++symlinks pointing to them will be). ++ ++As a special case, if @code{target-prefix} is @code{""} (the default), ++then when you create a group, the maildir will be created in ++@code{directory} without a corresponding symlink. Beware that you ++cannot use @code{gnus-group-delete-group} on such groups without the ++@code{force} argument. ++ ++@item directory-files ++This should be a function with the same interface as ++@code{directory-files} (such as @code{directory-files} itself). It is ++used to scan the server's @code{directory} for maildirs. This ++parameter is optional; the default is ++@code{nnheader-directory-files-safe} if ++@code{nnheader-directory-files-is-safe} is @code{nil}, and ++@code{directory-files} otherwise. ++(@code{nnheader-directory-files-is-safe} is checked only once when the ++server is opened; if you want to check it each time the directory is ++scanned, you'll have to provide your own function that does that.) ++ ++@item get-new-mail ++If non-@code{nil}, then after scanning for new mail in the group ++maildirs themselves as usual, this server will also incorporate mail ++the conventional Gnus way, from @code{mail-sources} according to ++@code{nnmail-split-methods} or @code{nnmail-split-fancy}. The default ++value is @code{nil}. ++ ++Do @emph{not} use the same maildir both in @code{mail-sources} and as ++an @code{nnmaildir} group. The results might happen to be useful, but ++that would be by chance, not by design, and the results might be ++different in the future. If your split rules create new groups, ++remember to supply a @code{create-directory} server parameter. ++@end table ++ ++@subsubsection Group parameters ++ ++@code{nnmaildir} uses several group parameters. It's safe to ignore ++all this; the default behavior for @code{nnmaildir} is the same as the ++default behavior for other mail back ends: articles are deleted after ++one week, etc. Except for the expiry parameters, all this ++functionality is unique to @code{nnmaildir}, so you can ignore it if ++you're just trying to duplicate the behavior you already have with ++another back end. ++ ++If the value of any of these parameters is a vector, the first element ++is evaluated as a Lisp form and the result is used, rather than the ++original value. If the value is not a vector, the value itself is ++evaluated as a Lisp form. (This is why these parameters use names ++different from those of other, similar parameters supported by other ++back ends: they have different, though similar, meanings.) (For ++numbers, strings, @code{nil}, and @code{t}, you can ignore the ++@code{eval} business again; for other values, remember to use an extra ++quote and wrap the value in a vector when appropriate.) ++ ++@table @code ++@item expire-age ++An integer specifying the minimum age, in seconds, of an article ++before it will be expired, or the symbol @code{never} to specify that ++articles should never be expired. If this parameter is not set, ++@code{nnmaildir} falls back to the usual ++@code{nnmail-expiry-wait}(@code{-function}) variables (the ++@code{expiry-wait} group parameter overrides @code{nnmail-expiry-wait} ++and makes @code{nnmail-expiry-wait-function} ineffective). If you ++wanted a value of 3 days, you could use something like @code{[(* 3 24 ++60 60)]}; @code{nnmaildir} will evaluate the form and use the result. ++An article's age is measured starting from the article file's ++modification time. Normally, this is the same as the article's ++delivery time, but editing an article makes it younger. Moving an ++article (other than via expiry) may also make an article younger. ++ ++@item expire-group ++If this is set to a string such as a full Gnus group name, like ++@example ++"backend+server.address.string:group.name" ++@end example ++and if it is not the name of the same group that the parameter belongs ++to, then articles will be moved to the specified group during expiry ++before being deleted. @emph{If this is set to an @code{nnmaildir} ++group, the article will be just as old in the destination group as it ++was in the source group.} So be careful with @code{expire-age} in the ++destination group. If this is set to the name of the same group that ++the parameter belongs to, then the article is not expired at all. If ++you use the vector form, the first element is evaluated once for each ++article. So that form can refer to ++@code{nnmaildir-article-file-name}, etc., to decide where to put the ++article. @emph{Even if this parameter is not set, @code{nnmaildir} ++does not fall back to the @code{expiry-target} group parameter or the ++@code{nnmail-expiry-target} variable.} ++ ++@item read-only ++If this is set to @code{t}, @code{nnmaildir} will treat the articles ++in this maildir as read-only. This means: articles are not renamed ++from @file{new/} into @file{cur/}; articles are only found in ++@file{new/}, not @file{cur/}; articles are never deleted; articles ++cannot be edited. @file{new/} is expected to be a symlink to the ++@file{new/} directory of another maildir---e.g., a system-wide mailbox ++containing a mailing list of common interest. Everything in the ++maildir outside @file{new/} is @emph{not} treated as read-only, so for ++a shared mailbox, you do still need to set up your own maildir (or ++have write permission to the shared mailbox); your maildir just won't ++contain extra copies of the articles. ++ ++@item directory-files ++A function with the same interface as @code{directory-files}. It is ++used to scan the directories in the maildir corresponding to this ++group to find articles. The default is the function specified by the ++server's @code{directory-files} parameter. ++ ++@item distrust-Lines: ++If non-@code{nil}, @code{nnmaildir} will always count the lines of an ++article, rather than use the @code{Lines:} header field. If ++@code{nil}, the header field will be used if present. ++ ++@item always-marks ++A list of mark symbols, such as @code{['(read expire)]}. Whenever ++Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will ++say that all articles have these marks, regardless of whether the ++marks stored in the filesystem say so. This is a proof-of-concept ++feature that will probably be removed eventually; it ought to be done ++in Gnus proper, or abandoned if it's not worthwhile. ++ ++@item never-marks ++A list of mark symbols, such as @code{['(tick expire)]}. Whenever ++Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will ++say that no articles have these marks, regardless of whether the marks ++stored in the filesystem say so. @code{never-marks} overrides ++@code{always-marks}. This is a proof-of-concept feature that will ++probably be removed eventually; it ought to be done in Gnus proper, or ++abandoned if it's not worthwhile. ++ ++@item nov-cache-size ++An integer specifying the size of the @acronym{NOV} memory cache. To ++speed things up, @code{nnmaildir} keeps @acronym{NOV} data in memory ++for a limited number of articles in each group. (This is probably not ++worthwhile, and will probably be removed in the future.) This ++parameter's value is noticed only the first time a group is seen after ++the server is opened---i.e., when you first start Gnus, typically. ++The @acronym{NOV} cache is never resized until the server is closed ++and reopened. The default is an estimate of the number of articles ++that would be displayed in the summary buffer: a count of articles ++that are either marked with @code{tick} or not marked with ++@code{read}, plus a little extra. ++@end table ++ ++@subsubsection Article identification ++Articles are stored in the @file{cur/} subdirectory of each maildir. ++Each article file is named like @code{uniq:info}, where @code{uniq} ++contains no colons. @code{nnmaildir} ignores, but preserves, the ++@code{:info} part. (Other maildir readers typically use this part of ++the filename to store marks.) The @code{uniq} part uniquely ++identifies the article, and is used in various places in the ++@file{.nnmaildir/} subdirectory of the maildir to store information ++about the corresponding article. The full pathname of an article is ++available in the variable @code{nnmaildir-article-file-name} after you ++request the article in the summary buffer. ++ ++@subsubsection NOV data ++An article identified by @code{uniq} has its @acronym{NOV} data (used ++to generate lines in the summary buffer) stored in ++@code{.nnmaildir/nov/uniq}. There is no ++@code{nnmaildir-generate-nov-databases} function. (There isn't much ++need for it---an article's @acronym{NOV} data is updated automatically ++when the article or @code{nnmail-extra-headers} has changed.) You can ++force @code{nnmaildir} to regenerate the @acronym{NOV} data for a ++single article simply by deleting the corresponding @acronym{NOV} ++file, but @emph{beware}: this will also cause @code{nnmaildir} to ++assign a new article number for this article, which may cause trouble ++with @code{seen} marks, the Agent, and the cache. ++ ++@subsubsection Article marks ++An article identified by @code{uniq} is considered to have the mark ++@code{flag} when the file @file{.nnmaildir/marks/flag/uniq} exists. ++When Gnus asks @code{nnmaildir} for a group's marks, @code{nnmaildir} ++looks for such files and reports the set of marks it finds. When Gnus ++asks @code{nnmaildir} to store a new set of marks, @code{nnmaildir} ++creates and deletes the corresponding files as needed. (Actually, ++rather than create a new file for each mark, it just creates hard ++links to @file{.nnmaildir/markfile}, to save inodes.) ++ ++You can invent new marks by creating a new directory in ++@file{.nnmaildir/marks/}. You can tar up a maildir and remove it from ++your server, untar it later, and keep your marks. You can add and ++remove marks yourself by creating and deleting mark files. If you do ++this while Gnus is running and your @code{nnmaildir} server is open, ++it's best to exit all summary buffers for @code{nnmaildir} groups and ++type @kbd{s} in the group buffer first, and to type @kbd{g} or ++@kbd{M-g} in the group buffer afterwards. Otherwise, Gnus might not ++pick up the changes, and might undo them. ++ ++ ++@node Mail Folders ++@subsubsection Mail Folders ++@cindex nnfolder ++@cindex mbox folders ++@cindex mail folders ++ ++@code{nnfolder} is a back end for storing each mail group in a ++separate file. Each file is in the standard Un*x mbox format. ++@code{nnfolder} will add extra headers to keep track of article ++numbers and arrival dates. ++ ++@cindex self contained nnfolder servers ++@cindex marks ++When the marks file is used (which it is by default), @code{nnfolder} ++servers have the property that you may backup them using @code{tar} or ++similar, and later be able to restore them into Gnus (by adding the ++proper @code{nnfolder} server) and have all your marks be preserved. ++Marks for a group are usually stored in a file named as the mbox file ++with @code{.mrk} concatenated to it (but see ++@code{nnfolder-marks-file-suffix}) within the @code{nnfolder} ++directory. Individual @code{nnfolder} groups are also possible to ++backup, use @kbd{G m} to restore the group (after restoring the backup ++into the @code{nnfolder} directory). ++ ++Virtual server settings: ++ ++@table @code ++@item nnfolder-directory ++@vindex nnfolder-directory ++All the @code{nnfolder} mail boxes will be stored under this ++directory. The default is the value of @code{message-directory} ++(whose default is @file{~/Mail}) ++ ++@item nnfolder-active-file ++@vindex nnfolder-active-file ++The name of the active file. The default is @file{~/Mail/active}. ++ ++@item nnfolder-newsgroups-file ++@vindex nnfolder-newsgroups-file ++The name of the group descriptions file. @xref{Newsgroups File ++Format}. The default is @file{~/Mail/newsgroups} ++ ++@item nnfolder-get-new-mail ++@vindex nnfolder-get-new-mail ++If non-@code{nil}, @code{nnfolder} will read incoming mail. The ++default is @code{t} ++ ++@item nnfolder-save-buffer-hook ++@vindex nnfolder-save-buffer-hook ++@cindex backup files ++Hook run before saving the folders. Note that Emacs does the normal ++backup renaming of files even with the @code{nnfolder} buffers. If ++you wish to switch this off, you could say something like the ++following in your @file{.emacs} file: ++ ++@lisp ++(defun turn-off-backup () ++ (set (make-local-variable 'backup-inhibited) t)) ++ ++(add-hook 'nnfolder-save-buffer-hook 'turn-off-backup) ++@end lisp ++ ++@item nnfolder-delete-mail-hook ++@vindex nnfolder-delete-mail-hook ++Hook run in a buffer narrowed to the message that is to be deleted. ++This function can be used to copy the message to somewhere else, or to ++extract some information from it before removing it. ++ ++@item nnfolder-nov-is-evil ++@vindex nnfolder-nov-is-evil ++If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The ++default is @code{nil}. ++ ++@item nnfolder-nov-file-suffix ++@vindex nnfolder-nov-file-suffix ++The extension for @acronym{NOV} files. The default is @file{.nov}. ++ ++@item nnfolder-nov-directory ++@vindex nnfolder-nov-directory ++The directory where the @acronym{NOV} files should be stored. If ++@code{nil}, @code{nnfolder-directory} is used. ++ ++@item nnfolder-marks-is-evil ++@vindex nnfolder-marks-is-evil ++If non-@code{nil}, this back end will ignore any @sc{marks} files. The ++default is @code{nil}. ++ ++@item nnfolder-marks-file-suffix ++@vindex nnfolder-marks-file-suffix ++The extension for @sc{marks} files. The default is @file{.mrk}. ++ ++@item nnfolder-marks-directory ++@vindex nnfolder-marks-directory ++The directory where the @sc{marks} files should be stored. If ++@code{nil}, @code{nnfolder-directory} is used. ++ ++@end table ++ ++ ++@findex nnfolder-generate-active-file ++@kindex M-x nnfolder-generate-active-file ++If you have lots of @code{nnfolder}-like files you'd like to read with ++@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file} ++command to make @code{nnfolder} aware of all likely files in ++@code{nnfolder-directory}. This only works if you use long file names, ++though. ++ ++@node Comparing Mail Back Ends ++@subsubsection Comparing Mail Back Ends ++ ++First, just for terminology, the @dfn{back end} is the common word for a ++low-level access method---a transport, if you will, by which something ++is acquired. The sense is that one's mail has to come from somewhere, ++and so selection of a suitable back end is required in order to get that ++mail within spitting distance of Gnus. ++ ++The same concept exists for Usenet itself: Though access to articles is ++typically done by @acronym{NNTP} these days, once upon a midnight dreary, everyone ++in the world got at Usenet by running a reader on the machine where the ++articles lay (the machine which today we call an @acronym{NNTP} server), and ++access was by the reader stepping into the articles' directory spool ++area directly. One can still select between either the @code{nntp} or ++@code{nnspool} back ends, to select between these methods, if one happens ++actually to live on the server (or can see its spool directly, anyway, ++via NFS). ++ ++The goal in selecting a mail back end is to pick one which ++simultaneously represents a suitable way of dealing with the original ++format plus leaving mail in a form that is convenient to use in the ++future. Here are some high and low points on each: ++ ++@table @code ++@item nnmbox ++ ++UNIX systems have historically had a single, very common, and well- ++defined format. All messages arrive in a single @dfn{spool file}, and ++they are delineated by a line whose regular expression matches ++@samp{^From_}. (My notational use of @samp{_} is to indicate a space, ++to make it clear in this instance that this is not the RFC-specified ++@samp{From:} header.) Because Emacs and therefore Gnus emanate ++historically from the Unix environment, it is simplest if one does not ++mess a great deal with the original mailbox format, so if one chooses ++this back end, Gnus' primary activity in getting mail from the real spool ++area to Gnus' preferred directory is simply to copy it, with no ++(appreciable) format change in the process. It is the ``dumbest'' way ++to move mail into availability in the Gnus environment. This makes it ++fast to move into place, but slow to parse, when Gnus has to look at ++what's where. ++ ++@item nnbabyl ++ ++Once upon a time, there was the DEC-10 and DEC-20, running operating ++systems called TOPS and related things, and the usual (only?) mail ++reading environment was a thing called Babyl. I don't know what format ++was used for mail landing on the system, but Babyl had its own internal ++format to which mail was converted, primarily involving creating a ++spool-file-like entity with a scheme for inserting Babyl-specific ++headers and status bits above the top of each message in the file. ++Rmail was Emacs' first mail reader, it was written by Richard Stallman, ++and Stallman came out of that TOPS/Babyl environment, so he wrote Rmail ++to understand the mail files folks already had in existence. Gnus (and ++VM, for that matter) continue to support this format because it's ++perceived as having some good qualities in those mailer-specific ++headers/status bits stuff. Rmail itself still exists as well, of ++course, and is still maintained within Emacs. Since Emacs 23, it ++uses standard mbox format rather than Babyl. ++ ++Both of the above forms leave your mail in a single file on your ++file system, and they must parse that entire file each time you take a ++look at your mail. ++ ++@item nnml ++ ++@code{nnml} is the back end which smells the most as though you were ++actually operating with an @code{nnspool}-accessed Usenet system. (In ++fact, I believe @code{nnml} actually derived from @code{nnspool} code, ++lo these years ago.) One's mail is taken from the original spool file, ++and is then cut up into individual message files, 1:1. It maintains a ++Usenet-style active file (analogous to what one finds in an INN- or ++CNews-based news system in (for instance) @file{/var/lib/news/active}, ++or what is returned via the @samp{NNTP LIST} verb) and also creates ++@dfn{overview} files for efficient group entry, as has been defined for ++@acronym{NNTP} servers for some years now. It is slower in mail-splitting, ++due to the creation of lots of files, updates to the @code{nnml} active ++file, and additions to overview files on a per-message basis, but it is ++extremely fast on access because of what amounts to the indexing support ++provided by the active file and overviews. ++ ++@code{nnml} costs @dfn{inodes} in a big way; that is, it soaks up the ++resource which defines available places in the file system to put new ++files. Sysadmins take a dim view of heavy inode occupation within ++tight, shared file systems. But if you live on a personal machine where ++the file system is your own and space is not at a premium, @code{nnml} ++wins big. ++ ++It is also problematic using this back end if you are living in a ++FAT16-based Windows world, since much space will be wasted on all these ++tiny files. ++ ++@item nnmh ++ ++The Rand MH mail-reading system has been around UNIX systems for a very ++long time; it operates by splitting one's spool file of messages into ++individual files, but with little or no indexing support---@code{nnmh} ++is considered to be semantically equivalent to ``@code{nnml} without ++active file or overviews''. This is arguably the worst choice, because ++one gets the slowness of individual file creation married to the ++slowness of access parsing when learning what's new in one's groups. ++ ++@item nnfolder ++ ++Basically the effect of @code{nnfolder} is @code{nnmbox} (the first ++method described above) on a per-group basis. That is, @code{nnmbox} ++itself puts @emph{all} one's mail in one file; @code{nnfolder} provides a ++little bit of optimization to this so that each of one's mail groups has ++a Unix mail box file. It's faster than @code{nnmbox} because each group ++can be parsed separately, and still provides the simple Unix mail box ++format requiring minimal effort in moving the mail around. In addition, ++it maintains an ``active'' file making it much faster for Gnus to figure ++out how many messages there are in each separate group. ++ ++If you have groups that are expected to have a massive amount of ++messages, @code{nnfolder} is not the best choice, but if you receive ++only a moderate amount of mail, @code{nnfolder} is probably the most ++friendly mail back end all over. ++ ++@item nnmaildir ++ ++For configuring expiry and other things, @code{nnmaildir} uses ++incompatible group parameters, slightly different from those of other ++mail back ends. ++ ++@code{nnmaildir} is largely similar to @code{nnml}, with some notable ++differences. Each message is stored in a separate file, but the ++filename is unrelated to the article number in Gnus. @code{nnmaildir} ++also stores the equivalent of @code{nnml}'s overview files in one file ++per article, so it uses about twice as many inodes as @code{nnml}. (Use ++@code{df -i} to see how plentiful your inode supply is.) If this slows ++you down or takes up very much space, consider switching to ++@uref{http://www.namesys.com/, ReiserFS} or another non-block-structured ++file system. ++ ++Since maildirs don't require locking for delivery, the maildirs you use ++as groups can also be the maildirs your mail is directly delivered to. ++This means you can skip Gnus' mail splitting if your mail is already ++organized into different mailboxes during delivery. A @code{directory} ++entry in @code{mail-sources} would have a similar effect, but would ++require one set of mailboxes for spooling deliveries (in mbox format, ++thus damaging message bodies), and another set to be used as groups (in ++whatever format you like). A maildir has a built-in spool, in the ++@code{new/} subdirectory. Beware that currently, mail moved from ++@code{new/} to @code{cur/} instead of via mail splitting will not ++undergo treatment such as duplicate checking. ++ ++@code{nnmaildir} stores article marks for a given group in the ++corresponding maildir, in a way designed so that it's easy to manipulate ++them from outside Gnus. You can tar up a maildir, unpack it somewhere ++else, and still have your marks. @code{nnml} also stores marks, but ++it's not as easy to work with them from outside Gnus as with ++@code{nnmaildir}. ++ ++@code{nnmaildir} uses a significant amount of memory to speed things up. ++(It keeps in memory some of the things that @code{nnml} stores in files ++and that @code{nnmh} repeatedly parses out of message files.) If this ++is a problem for you, you can set the @code{nov-cache-size} group ++parameter to something small (0 would probably not work, but 1 probably ++would) to make it use less memory. This caching will probably be ++removed in the future. ++ ++Startup is likely to be slower with @code{nnmaildir} than with other ++back ends. Everything else is likely to be faster, depending in part ++on your file system. ++ ++@code{nnmaildir} does not use @code{nnoo}, so you cannot use @code{nnoo} ++to write an @code{nnmaildir}-derived back end. ++ ++@end table ++ ++ ++@node Browsing the Web ++@section Browsing the Web ++@cindex web ++@cindex browsing the web ++@cindex www ++@cindex http ++ ++Web-based discussion forums are getting more and more popular. On many ++subjects, the web-based forums have become the most important forums, ++eclipsing the importance of mailing lists and news groups. The reason ++is easy to understand---they are friendly to new users; you just point ++and click, and there's the discussion. With mailing lists, you have to ++go through a cumbersome subscription procedure, and most people don't ++even know what a news group is. ++ ++The problem with this scenario is that web browsers are not very good at ++being newsreaders. They do not keep track of what articles you've read; ++they do not allow you to score on subjects you're interested in; they do ++not allow off-line browsing; they require you to click around and drive ++you mad in the end. ++ ++So---if web browsers suck at reading discussion forums, why not use Gnus ++to do it instead? ++ ++Gnus has been getting a bit of a collection of back ends for providing ++interfaces to these sources. ++ ++@menu ++* Archiving Mail:: ++* Web Searches:: Creating groups from articles that match a string. ++* Slashdot:: Reading the Slashdot comments. ++* Ultimate:: The Ultimate Bulletin Board systems. ++* Web Archive:: Reading mailing list archived on web. ++* RSS:: Reading RDF site summary. ++* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. ++@end menu ++ ++All the web sources require Emacs/W3 and the url library or those ++alternatives to work. ++ ++The main caveat with all these web sources is that they probably won't ++work for a very long time. Gleaning information from the @acronym{HTML} data ++is guesswork at best, and when the layout is altered, the Gnus back end ++will fail. If you have reasonably new versions of these back ends, ++though, you should be ok. ++ ++One thing all these Web methods have in common is that the Web sources ++are often down, unavailable or just plain too slow to be fun. In those ++cases, it makes a lot of sense to let the Gnus Agent (@pxref{Gnus ++Unplugged}) handle downloading articles, and then you can read them at ++leisure from your local disk. No more World Wide Wait for you. ++ ++@node Archiving Mail ++@subsection Archiving Mail ++@cindex archiving mail ++@cindex backup of mail ++ ++Some of the back ends, notably @code{nnml}, @code{nnfolder}, and ++@code{nnmaildir}, now actually store the article marks with each group. ++For these servers, archiving and restoring a group while preserving ++marks is fairly simple. ++ ++(Preserving the group level and group parameters as well still ++requires ritual dancing and sacrifices to the @file{.newsrc.eld} deity ++though.) ++ ++To archive an entire @code{nnml}, @code{nnfolder}, or @code{nnmaildir} ++server, take a recursive copy of the server directory. There is no need ++to shut down Gnus, so archiving may be invoked by @code{cron} or ++similar. You restore the data by restoring the directory tree, and ++adding a server definition pointing to that directory in Gnus. The ++@ref{Article Backlog}, @ref{Asynchronous Fetching} and other things ++might interfere with overwriting data, so you may want to shut down Gnus ++before you restore the data. ++ ++It is also possible to archive individual @code{nnml}, ++@code{nnfolder}, or @code{nnmaildir} groups, while preserving marks. ++For @code{nnml} or @code{nnmaildir}, you copy all files in the group's ++directory. For @code{nnfolder} you need to copy both the base folder ++file itself (@file{FOO}, say), and the marks file (@file{FOO.mrk} in ++this example). Restoring the group is done with @kbd{G m} from the Group ++buffer. The last step makes Gnus notice the new directory. ++@code{nnmaildir} notices the new directory automatically, so @kbd{G m} ++is unnecessary in that case. ++ ++@node Web Searches ++@subsection Web Searches ++@cindex nnweb ++@cindex Google ++@cindex dejanews ++@cindex gmane ++@cindex Usenet searches ++@cindex searching the Usenet ++ ++It's, like, too neat to search the Usenet for articles that match a ++string, but it, like, totally @emph{sucks}, like, totally, to use one of ++those, like, Web browsers, and you, like, have to, rilly, like, look at ++the commercials, so, like, with Gnus you can do @emph{rad}, rilly, ++searches without having to use a browser. ++ ++The @code{nnweb} back end allows an easy interface to the mighty search ++engine. You create an @code{nnweb} group, enter a search pattern, and ++then enter the group and read the articles like you would any normal ++group. The @kbd{G w} command in the group buffer (@pxref{Foreign ++Groups}) will do this in an easy-to-use fashion. ++ ++@code{nnweb} groups don't really lend themselves to being solid ++groups---they have a very fleeting idea of article numbers. In fact, ++each time you enter an @code{nnweb} group (not even changing the search ++pattern), you are likely to get the articles ordered in a different ++manner. Not even using duplicate suppression (@pxref{Duplicate ++Suppression}) will help, since @code{nnweb} doesn't even know the ++@code{Message-ID} of the articles before reading them using some search ++engines (Google, for instance). The only possible way to keep track ++of which articles you've read is by scoring on the @code{Date} ++header---mark all articles posted before the last date you read the ++group as read. ++ ++If the search engine changes its output substantially, @code{nnweb} ++won't be able to parse it and will fail. One could hardly fault the Web ++providers if they were to do this---their @emph{raison d'@^etre} is to ++make money off of advertisements, not to provide services to the ++community. Since @code{nnweb} washes the ads off all the articles, one ++might think that the providers might be somewhat miffed. We'll see. ++ ++You must have the @code{url} and @code{W3} package or those alternatives ++(try @code{customize-group} on the @samp{mm-url} variable group) ++installed to be able to use @code{nnweb}. ++ ++Virtual server variables: ++ ++@table @code ++@item nnweb-type ++@vindex nnweb-type ++What search engine type is being used. The currently supported types ++are @code{google}, @code{dejanews}, and @code{gmane}. Note that ++@code{dejanews} is an alias to @code{google}. ++ ++@item nnweb-search ++@vindex nnweb-search ++The search string to feed to the search engine. ++ ++@item nnweb-max-hits ++@vindex nnweb-max-hits ++Advisory maximum number of hits per search to display. The default is ++999. ++ ++@item nnweb-type-definition ++@vindex nnweb-type-definition ++Type-to-definition alist. This alist says what @code{nnweb} should do ++with the various search engine types. The following elements must be ++present: ++ ++@table @code ++@item article ++Function to decode the article and provide something that Gnus ++understands. ++ ++@item map ++Function to create an article number to message header and URL alist. ++ ++@item search ++Function to send the search string to the search engine. ++ ++@item address ++The address the aforementioned function should send the search string ++to. ++ ++@item id ++Format string URL to fetch an article by @code{Message-ID}. ++@end table ++ ++@end table ++ ++ ++@node Slashdot ++@subsection Slashdot ++@cindex Slashdot ++@cindex nnslashdot ++ ++@uref{http://slashdot.org/, Slashdot} is a popular news site, with ++lively discussion following the news articles. @code{nnslashdot} will ++let you read this forum in a convenient manner. ++ ++The easiest way to read this source is to put something like the ++following in your @file{~/.gnus.el} file: ++ ++@lisp ++(setq gnus-secondary-select-methods ++ '((nnslashdot ""))) ++@end lisp ++ ++This will make Gnus query the @code{nnslashdot} back end for new comments ++and groups. The @kbd{F} command will subscribe each new news article as ++a new Gnus group, and you can read the comments by entering these ++groups. (Note that the default subscription method is to subscribe new ++groups as zombies. Other methods are available (@pxref{Subscription ++Methods}). ++ ++If you want to remove an old @code{nnslashdot} group, the @kbd{G DEL} ++command is the most handy tool (@pxref{Foreign Groups}). ++ ++When following up to @code{nnslashdot} comments (or posting new ++comments), some light @acronym{HTML}izations will be performed. In ++particular, text quoted with @samp{> } will be quoted with ++@samp{blockquote} instead, and signatures will have @samp{br} added to ++the end of each line. Other than that, you can just write @acronym{HTML} ++directly into the message buffer. Note that Slashdot filters out some ++@acronym{HTML} forms. ++ ++The following variables can be altered to change its behavior: ++ ++@table @code ++@item nnslashdot-threaded ++Whether @code{nnslashdot} should display threaded groups or not. The ++default is @code{t}. To be able to display threads, @code{nnslashdot} ++has to retrieve absolutely all comments in a group upon entry. If a ++threaded display is not required, @code{nnslashdot} will only retrieve ++the comments that are actually wanted by the user. Threading is nicer, ++but much, much slower than unthreaded. ++ ++@item nnslashdot-login-name ++@vindex nnslashdot-login-name ++The login name to use when posting. ++ ++@item nnslashdot-password ++@vindex nnslashdot-password ++The password to use when posting. ++ ++@item nnslashdot-directory ++@vindex nnslashdot-directory ++Where @code{nnslashdot} will store its files. The default is ++@file{~/News/slashdot/}. ++ ++@item nnslashdot-active-url ++@vindex nnslashdot-active-url ++The @acronym{URL} format string that will be used to fetch the ++information on news articles and comments. The default is@* ++@samp{http://slashdot.org/search.pl?section=&min=%d}. ++ ++@item nnslashdot-comments-url ++@vindex nnslashdot-comments-url ++The @acronym{URL} format string that will be used to fetch comments. ++ ++@item nnslashdot-article-url ++@vindex nnslashdot-article-url ++The @acronym{URL} format string that will be used to fetch the news ++article. The default is ++@samp{http://slashdot.org/article.pl?sid=%s&mode=nocomment}. ++ ++@item nnslashdot-threshold ++@vindex nnslashdot-threshold ++The score threshold. The default is -1. ++ ++@item nnslashdot-group-number ++@vindex nnslashdot-group-number ++The number of old groups, in addition to the ten latest, to keep ++updated. The default is 0. ++ ++@end table ++ ++ ++ ++@node Ultimate ++@subsection Ultimate ++@cindex nnultimate ++@cindex Ultimate Bulletin Board ++ ++@uref{http://www.ultimatebb.com/, The Ultimate Bulletin Board} is ++probably the most popular Web bulletin board system used. It has a ++quite regular and nice interface, and it's possible to get the ++information Gnus needs to keep groups updated. ++ ++The easiest way to get started with @code{nnultimate} is to say ++something like the following in the group buffer: @kbd{B nnultimate RET ++http://www.tcj.com/messboard/ubbcgi/ RET}. (Substitute the @acronym{URL} ++(not including @samp{Ultimate.cgi} or the like at the end) for a forum ++you're interested in; there's quite a list of them on the Ultimate web ++site.) Then subscribe to the groups you're interested in from the ++server buffer, and read them from the group buffer. ++ ++The following @code{nnultimate} variables can be altered: ++ ++@table @code ++@item nnultimate-directory ++@vindex nnultimate-directory ++The directory where @code{nnultimate} stores its files. The default is@* ++@file{~/News/ultimate/}. ++@end table ++ ++ ++@node Web Archive ++@subsection Web Archive ++@cindex nnwarchive ++@cindex Web Archive ++ ++Some mailing lists only have archives on Web servers, such as ++@uref{http://www.egroups.com/} and ++@uref{http://www.mail-archive.com/}. It has a quite regular and nice ++interface, and it's possible to get the information Gnus needs to keep ++groups updated. ++ ++@findex gnus-group-make-warchive-group ++The easiest way to get started with @code{nnwarchive} is to say ++something like the following in the group buffer: @kbd{M-x ++gnus-group-make-warchive-group RET @var{an_egroup} RET egroups RET ++www.egroups.com RET @var{your@@email.address} RET}. (Substitute the ++@var{an_egroup} with the mailing list you subscribed, the ++@var{your@@email.address} with your email address.), or to browse the ++back end by @kbd{B nnwarchive RET mail-archive RET}. ++ ++The following @code{nnwarchive} variables can be altered: ++ ++@table @code ++@item nnwarchive-directory ++@vindex nnwarchive-directory ++The directory where @code{nnwarchive} stores its files. The default is@* ++@file{~/News/warchive/}. ++ ++@item nnwarchive-login ++@vindex nnwarchive-login ++The account name on the web server. ++ ++@item nnwarchive-passwd ++@vindex nnwarchive-passwd ++The password for your account on the web server. ++@end table ++ ++@node RSS ++@subsection RSS ++@cindex nnrss ++@cindex RSS ++ ++Some web sites have an RDF Site Summary (@acronym{RSS}). ++@acronym{RSS} is a format for summarizing headlines from news related ++sites (such as BBC or CNN). But basically anything list-like can be ++presented as an @acronym{RSS} feed: weblogs, changelogs or recent ++changes to a wiki (e.g. @url{http://cliki.net/recent-changes.rdf}). ++ ++@acronym{RSS} has a quite regular and nice interface, and it's ++possible to get the information Gnus needs to keep groups updated. ++ ++Note: you had better use Emacs which supports the @code{utf-8} coding ++system because @acronym{RSS} uses UTF-8 for encoding non-@acronym{ASCII} ++text by default. It is also used by default for non-@acronym{ASCII} ++group names. ++ ++@kindex G R (Group) ++Use @kbd{G R} from the group buffer to subscribe to a feed---you will be ++prompted for the location, the title and the description of the feed. ++The title, which allows any characters, will be used for the group name ++and the name of the group data file. The description can be omitted. ++ ++An easy way to get started with @code{nnrss} is to say something like ++the following in the group buffer: @kbd{B nnrss RET RET y}, then ++subscribe to groups. ++ ++The @code{nnrss} back end saves the group data file in ++@code{nnrss-directory} (see below) for each @code{nnrss} group. File ++names containing non-@acronym{ASCII} characters will be encoded by the ++coding system specified with the @code{nnmail-pathname-coding-system} ++variable or other. Also @xref{Non-ASCII Group Names}, for more ++information. ++ ++The @code{nnrss} back end generates @samp{multipart/alternative} ++@acronym{MIME} articles in which each contains a @samp{text/plain} part ++and a @samp{text/html} part. ++ ++@cindex OPML ++You can also use the following commands to import and export your ++subscriptions from a file in @acronym{OPML} format (Outline Processor ++Markup Language). ++ ++@defun nnrss-opml-import file ++Prompt for an @acronym{OPML} file, and subscribe to each feed in the ++file. ++@end defun ++ ++@defun nnrss-opml-export ++Write your current @acronym{RSS} subscriptions to a buffer in ++@acronym{OPML} format. ++@end defun ++ ++The following @code{nnrss} variables can be altered: ++ ++@table @code ++@item nnrss-directory ++@vindex nnrss-directory ++The directory where @code{nnrss} stores its files. The default is ++@file{~/News/rss/}. ++ ++@item nnrss-file-coding-system ++@vindex nnrss-file-coding-system ++The coding system used when reading and writing the @code{nnrss} groups ++data files. The default is the value of ++@code{mm-universal-coding-system} (which defaults to @code{emacs-mule} ++in Emacs or @code{escape-quoted} in XEmacs). ++ ++@item nnrss-ignore-article-fields ++@vindex nnrss-ignore-article-fields ++Some feeds update constantly article fields during their publications, ++e.g. to indicate the number of comments. However, if there is ++a difference between the local article and the distant one, the latter ++is considered to be new. To avoid this and discard some fields, set this ++variable to the list of fields to be ignored. The default is ++@code{'(slash:comments)}. ++ ++@item nnrss-use-local ++@vindex nnrss-use-local ++@findex nnrss-generate-download-script ++If you set @code{nnrss-use-local} to @code{t}, @code{nnrss} will read ++the feeds from local files in @code{nnrss-directory}. You can use ++the command @code{nnrss-generate-download-script} to generate a ++download script using @command{wget}. ++ ++@item nnrss-wash-html-in-text-plain-parts ++Non-@code{nil} means that @code{nnrss} renders text in @samp{text/plain} ++parts as @acronym{HTML}. The function specified by the ++@code{mm-text-html-renderer} variable (@pxref{Display Customization, ++,Display Customization, emacs-mime, The Emacs MIME Manual}) will be used ++to render text. If it is @code{nil}, which is the default, text will ++simply be folded. Leave it @code{nil} if you prefer to see ++@samp{text/html} parts. ++@end table ++ ++The following code may be helpful, if you want to show the description in ++the summary buffer. ++ ++@lisp ++(add-to-list 'nnmail-extra-headers nnrss-description-field) ++(setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-15,15f%]%) %s%uX\n") ++ ++(defun gnus-user-format-function-X (header) ++ (let ((descr ++ (assq nnrss-description-field (mail-header-extra header)))) ++ (if descr (concat "\n\t" (cdr descr)) ""))) ++@end lisp ++ ++The following code may be useful to open an nnrss url directly from the ++summary buffer. ++ ++@lisp ++(require 'browse-url) ++ ++(defun browse-nnrss-url (arg) ++ (interactive "p") ++ (let ((url (assq nnrss-url-field ++ (mail-header-extra ++ (gnus-data-header ++ (assq (gnus-summary-article-number) ++ gnus-newsgroup-data)))))) ++ (if url ++ (progn ++ (browse-url (cdr url)) ++ (gnus-summary-mark-as-read-forward 1)) ++ (gnus-summary-scroll-up arg)))) ++ ++(eval-after-load "gnus" ++ #'(define-key gnus-summary-mode-map ++ (kbd "") 'browse-nnrss-url)) ++(add-to-list 'nnmail-extra-headers nnrss-url-field) ++@end lisp ++ ++Even if you have added @samp{text/html} to the ++@code{mm-discouraged-alternatives} variable (@pxref{Display ++Customization, ,Display Customization, emacs-mime, The Emacs MIME ++Manual}) since you don't want to see @acronym{HTML} parts, it might be ++more useful especially in @code{nnrss} groups to display ++@samp{text/html} parts. Here's an example of setting ++@code{mm-discouraged-alternatives} as a group parameter (@pxref{Group ++Parameters}) in order to display @samp{text/html} parts only in ++@code{nnrss} groups: ++ ++@lisp ++;; @r{Set the default value of @code{mm-discouraged-alternatives}.} ++(eval-after-load "gnus-sum" ++ '(add-to-list ++ 'gnus-newsgroup-variables ++ '(mm-discouraged-alternatives ++ . '("text/html" "image/.*")))) ++ ++;; @r{Display @samp{text/html} parts in @code{nnrss} groups.} ++(add-to-list ++ 'gnus-parameters ++ '("\\`nnrss:" (mm-discouraged-alternatives nil))) ++@end lisp ++ ++ ++@node Customizing W3 ++@subsection Customizing W3 ++@cindex W3 ++@cindex html ++@cindex url ++@cindex Netscape ++ ++Gnus uses the url library to fetch web pages and Emacs/W3 (or those ++alternatives) to display web pages. Emacs/W3 is documented in its own ++manual, but there are some things that may be more relevant for Gnus ++users. ++ ++For instance, a common question is how to make Emacs/W3 follow links ++using the @code{browse-url} functions (which will call some external web ++browser like Netscape). Here's one way: ++ ++@lisp ++(eval-after-load "w3" ++ '(progn ++ (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) ++ (defun w3-fetch (&optional url target) ++ (interactive (list (w3-read-url-with-default))) ++ (if (eq major-mode 'gnus-article-mode) ++ (browse-url url) ++ (w3-fetch-orig url target))))) ++@end lisp ++ ++Put that in your @file{.emacs} file, and hitting links in W3-rendered ++@acronym{HTML} in the Gnus article buffers will use @code{browse-url} to ++follow the link. ++ ++ ++@node IMAP ++@section IMAP ++@cindex nnimap ++@cindex @acronym{IMAP} ++ ++@acronym{IMAP} is a network protocol for reading mail (or news, or @dots{}), ++think of it as a modernized @acronym{NNTP}. Connecting to a @acronym{IMAP} ++server is much similar to connecting to a news server, you just ++specify the network address of the server. ++ ++@acronym{IMAP} has two properties. First, @acronym{IMAP} can do ++everything that @acronym{POP} can, it can hence be viewed as a ++@acronym{POP++}. Secondly, @acronym{IMAP} is a mail storage protocol, ++similar to @acronym{NNTP} being a news storage protocol---however, ++@acronym{IMAP} offers more features than @acronym{NNTP} because news ++is more or less read-only whereas mail is read-write. ++ ++If you want to use @acronym{IMAP} as a @acronym{POP++}, use an imap ++entry in @code{mail-sources}. With this, Gnus will fetch mails from ++the @acronym{IMAP} server and store them on the local disk. This is ++not the usage described in this section---@xref{Mail Sources}. ++ ++If you want to use @acronym{IMAP} as a mail storage protocol, use an nnimap ++entry in @code{gnus-secondary-select-methods}. With this, Gnus will ++manipulate mails stored on the @acronym{IMAP} server. This is the kind of ++usage explained in this section. ++ ++A server configuration in @file{~/.gnus.el} with a few @acronym{IMAP} ++servers might look something like the following. (Note that for ++@acronym{TLS}/@acronym{SSL}, you need external programs and libraries, ++see below.) ++ ++@lisp ++(setq gnus-secondary-select-methods ++ '((nnimap "simpleserver") ; @r{no special configuration} ++ ; @r{perhaps a ssh port forwarded server:} ++ (nnimap "dolk" ++ (nnimap-address "localhost") ++ (nnimap-server-port 1430)) ++ ; @r{a UW server running on localhost} ++ (nnimap "barbar" ++ (nnimap-server-port 143) ++ (nnimap-address "localhost") ++ (nnimap-list-pattern ("INBOX" "mail/*"))) ++ ; @r{anonymous public cyrus server:} ++ (nnimap "cyrus.andrew.cmu.edu" ++ (nnimap-authenticator anonymous) ++ (nnimap-list-pattern "archive.*") ++ (nnimap-stream network)) ++ ; @r{a ssl server on a non-standard port:} ++ (nnimap "vic20" ++ (nnimap-address "vic20.somewhere.com") ++ (nnimap-server-port 9930) ++ (nnimap-stream ssl)))) ++@end lisp ++ ++After defining the new server, you can subscribe to groups on the ++server using normal Gnus commands such as @kbd{U} in the Group Buffer ++(@pxref{Subscription Commands}) or via the Server Buffer ++(@pxref{Server Buffer}). ++ ++The following variables can be used to create a virtual @code{nnimap} ++server: ++ ++@table @code ++ ++@item nnimap-address ++@vindex nnimap-address ++ ++The address of the remote @acronym{IMAP} server. Defaults to the virtual ++server name if not specified. ++ ++@item nnimap-server-port ++@vindex nnimap-server-port ++Port on server to contact. Defaults to port 143, or 993 for @acronym{TLS}/@acronym{SSL}. ++ ++Note that this should be an integer, example server specification: ++ ++@lisp ++(nnimap "mail.server.com" ++ (nnimap-server-port 4711)) ++@end lisp ++ ++@item nnimap-list-pattern ++@vindex nnimap-list-pattern ++String or list of strings of mailboxes to limit available groups to. ++This is used when the server has very many mailboxes and you're only ++interested in a few---some servers export your home directory via ++@acronym{IMAP}, you'll probably want to limit the mailboxes to those in ++@file{~/Mail/*} then. ++ ++The string can also be a cons of REFERENCE and the string as above, what ++REFERENCE is used for is server specific, but on the University of ++Washington server it's a directory that will be concatenated with the ++mailbox. ++ ++Example server specification: ++ ++@lisp ++(nnimap "mail.server.com" ++ (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" ++ ("~friend/Mail/" . "list/*")))) ++@end lisp ++ ++@item nnimap-stream ++@vindex nnimap-stream ++The type of stream used to connect to your server. By default, nnimap ++will detect and automatically use all of the below, with the exception ++of @acronym{TLS}/@acronym{SSL}. (@acronym{IMAP} over ++@acronym{TLS}/@acronym{SSL} is being replaced by STARTTLS, which can ++be automatically detected, but it's not widely deployed yet.) ++ ++Example server specification: ++ ++@lisp ++(nnimap "mail.server.com" ++ (nnimap-stream ssl)) ++@end lisp ++ ++Please note that the value of @code{nnimap-stream} is a symbol! ++ ++@itemize @bullet ++@item ++@dfn{gssapi:} Connect with GSSAPI (usually Kerberos 5). Requires the ++@samp{gsasl} or @samp{imtest} program. ++@item ++@dfn{kerberos4:} Connect with Kerberos 4. Requires the @samp{imtest} program. ++@item ++@dfn{starttls:} Connect via the STARTTLS extension (similar to ++@acronym{TLS}/@acronym{SSL}). Requires the external library @samp{starttls.el} and program ++@samp{starttls}. ++@item ++@dfn{tls:} Connect through @acronym{TLS}. Requires GNUTLS (the program ++@samp{gnutls-cli}). ++@item ++@dfn{ssl:} Connect through @acronym{SSL}. Requires OpenSSL (the program ++@samp{openssl}) or SSLeay (@samp{s_client}). ++@item ++@dfn{shell:} Use a shell command to start @acronym{IMAP} connection. ++@item ++@dfn{network:} Plain, TCP/IP network connection. ++@end itemize ++ ++@vindex imap-kerberos4-program ++The @samp{imtest} program is shipped with Cyrus IMAPD. If you're ++using @samp{imtest} from Cyrus IMAPD < 2.0.14 (which includes version ++1.5.x and 1.6.x) you need to frob @code{imap-process-connection-type} ++to make @code{imap.el} use a pty instead of a pipe when communicating ++with @samp{imtest}. You will then suffer from a line length ++restrictions on @acronym{IMAP} commands, which might make Gnus seem to hang ++indefinitely if you have many articles in a mailbox. The variable ++@code{imap-kerberos4-program} contain parameters to pass to the imtest ++program. ++ ++For @acronym{TLS} connection, the @code{gnutls-cli} program from GNUTLS is ++needed. It is available from ++@uref{http://www.gnu.org/software/gnutls/}. ++ ++@vindex imap-gssapi-program ++This parameter specifies a list of command lines that invoke a GSSAPI ++authenticated @acronym{IMAP} stream in a subshell. They are tried ++sequentially until a connection is made, or the list has been ++exhausted. By default, @samp{gsasl} from GNU SASL, available from ++@uref{http://www.gnu.org/software/gsasl/}, and the @samp{imtest} ++program from Cyrus IMAPD (see @code{imap-kerberos4-program}), are ++tried. ++ ++@vindex imap-ssl-program ++For @acronym{SSL} connections, the OpenSSL program is available from ++@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay, ++and nnimap support it too---although the most recent versions of ++SSLeay, 0.9.x, are known to have serious bugs making it ++useless. Earlier versions, especially 0.8.x, of SSLeay are known to ++work. The variable @code{imap-ssl-program} contain parameters to pass ++to OpenSSL/SSLeay. ++ ++@vindex imap-shell-program ++@vindex imap-shell-host ++For @acronym{IMAP} connections using the @code{shell} stream, the ++variable @code{imap-shell-program} specify what program to call. Make ++sure nothing is interfering with the output of the program, e.g., don't ++forget to redirect the error output to the void. ++ ++@item nnimap-authenticator ++@vindex nnimap-authenticator ++ ++The authenticator used to connect to the server. By default, nnimap ++will use the most secure authenticator your server is capable of. ++ ++Example server specification: ++ ++@lisp ++(nnimap "mail.server.com" ++ (nnimap-authenticator anonymous)) ++@end lisp ++ ++Please note that the value of @code{nnimap-authenticator} is a symbol! ++ ++@itemize @bullet ++@item ++@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Requires ++external program @code{gsasl} or @code{imtest}. ++@item ++@dfn{kerberos4:} Kerberos 4 authentication. Requires external program ++@code{imtest}. ++@item ++@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Requires ++external library @code{digest-md5.el}. ++@item ++@dfn{cram-md5:} Encrypted username/password via CRAM-MD5. ++@item ++@dfn{login:} Plain-text username/password via LOGIN. ++@item ++@dfn{anonymous:} Login as ``anonymous'', supplying your email address as password. ++@end itemize ++ ++@item nnimap-expunge-on-close ++@cindex expunging ++@vindex nnimap-expunge-on-close ++Unlike Parmenides the @acronym{IMAP} designers have decided things that ++don't exist actually do exist. More specifically, @acronym{IMAP} has ++this concept of marking articles @code{Deleted} which doesn't actually ++delete them, and this (marking them @code{Deleted}, that is) is what ++nnimap does when you delete an article in Gnus (with @kbd{B DEL} or ++similar). ++ ++Since the articles aren't really removed when we mark them with the ++@code{Deleted} flag we'll need a way to actually delete them. Feel like ++running in circles yet? ++ ++Traditionally, nnimap has removed all articles marked as @code{Deleted} ++when closing a mailbox but this is now configurable by this server ++variable. ++ ++The possible options are: ++ ++@table @code ++ ++@item always ++The default behavior, delete all articles marked as ``Deleted'' when ++closing a mailbox. ++@item never ++Never actually delete articles. Currently there is no way of showing ++the articles marked for deletion in nnimap, but other @acronym{IMAP} clients ++may allow you to do this. If you ever want to run the EXPUNGE command ++manually, @xref{Expunging mailboxes}. ++@item ask ++When closing mailboxes, nnimap will ask if you wish to expunge deleted ++articles or not. ++ ++@end table ++ ++@item nnimap-importantize-dormant ++@vindex nnimap-importantize-dormant ++ ++If non-@code{nil} (the default), marks dormant articles as ticked (as ++well), for other @acronym{IMAP} clients. Within Gnus, dormant articles will ++naturally still (only) be marked as dormant. This is to make dormant ++articles stand out, just like ticked articles, in other @acronym{IMAP} ++clients. (In other words, Gnus has two ``Tick'' marks and @acronym{IMAP} ++has only one.) ++ ++Probably the only reason for frobbing this would be if you're trying ++enable per-user persistent dormant flags, using something like: ++ ++@lisp ++(setcdr (assq 'dormant nnimap-mark-to-flag-alist) ++ (format "gnus-dormant-%s" (user-login-name))) ++(setcdr (assq 'dormant nnimap-mark-to-predicate-alist) ++ (format "KEYWORD gnus-dormant-%s" (user-login-name))) ++@end lisp ++ ++In this case, you would not want the per-user dormant flag showing up ++as ticked for other users. ++ ++@item nnimap-expunge-search-string ++@cindex expunging ++@vindex nnimap-expunge-search-string ++@cindex expiring @acronym{IMAP} mail ++ ++This variable contain the @acronym{IMAP} search command sent to server when ++searching for articles eligible for expiring. The default is ++@code{"UID %s NOT SINCE %s"}, where the first @code{%s} is replaced by ++UID set and the second @code{%s} is replaced by a date. ++ ++Probably the only useful value to change this to is ++@code{"UID %s NOT SENTSINCE %s"}, which makes nnimap use the Date: in ++messages instead of the internal article date. See section 6.4.4 of ++RFC 2060 for more information on valid strings. ++ ++However, if @code{nnimap-search-uids-not-since-is-evil} ++is true, this variable has no effect since the search logic ++is reversed, as described below. ++ ++@item nnimap-authinfo-file ++@vindex nnimap-authinfo-file ++ ++A file containing credentials used to log in on servers. The format is ++(almost) the same as the @code{ftp} @file{~/.netrc} file. See the ++variable @code{nntp-authinfo-file} for exact syntax; also see ++@ref{NNTP}. An example of an .authinfo line for an IMAP server, is: ++ ++@example ++machine students.uio.no login larsi password geheimnis port imap ++@end example ++ ++Note that it should be @code{port imap}, or @code{port 143}, if you ++use a @code{nnimap-stream} of @code{tls} or @code{ssl}, even if the ++actual port number used is port 993 for secured IMAP. For ++convenience, Gnus will accept @code{port imaps} as a synonym of ++@code{port imap}. ++ ++@item nnimap-need-unselect-to-notice-new-mail ++@vindex nnimap-need-unselect-to-notice-new-mail ++ ++Unselect mailboxes before looking for new mail in them. Some servers ++seem to need this under some circumstances; it was reported that ++Courier 1.7.1 did. ++ ++@item nnimap-nov-is-evil ++@vindex nnimap-nov-is-evil ++@cindex Courier @acronym{IMAP} server ++@cindex @acronym{NOV} ++ ++Never generate or use a local @acronym{NOV} database. Defaults to the ++value of @code{gnus-agent}. ++ ++Using a @acronym{NOV} database usually makes header fetching much ++faster, but it uses the @code{UID SEARCH UID} command, which is very ++slow on some servers (notably some versions of Courier). Since the Gnus ++Agent caches the information in the @acronym{NOV} database without using ++the slow command, this variable defaults to true if the Agent is in use, ++and false otherwise. ++ ++@item nnimap-search-uids-not-since-is-evil ++@vindex nnimap-search-uids-not-since-is-evil ++@cindex Courier @acronym{IMAP} server ++@cindex expiring @acronym{IMAP} mail ++ ++Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE ++@var{date}} command, which is slow on some @acronym{IMAP} servers ++(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE ++@var{date}} and prune the list of expirable articles within Gnus. ++ ++When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a ++list of expirable articles and asks the IMAP server questions like ``Of ++these articles, which ones are older than a week?'' While this seems ++like a perfectly reasonable question, some IMAP servers take a long time ++to answer it, since they seemingly go looking into every old article to ++see if it is one of the expirable ones. Curiously, the question ``Of ++@emph{all} articles, which ones are newer than a week?'' seems to be ++much faster to answer, so setting this variable causes Gnus to ask this ++question and figure out the answer to the real question itself. ++ ++This problem can really sneak up on you: when you first configure Gnus, ++everything works fine, but once you accumulate a couple thousand ++messages, you start cursing Gnus for being so slow. On the other hand, ++if you get a lot of email within a week, setting this variable will ++cause a lot of network traffic between Gnus and the IMAP server. ++ ++@item nnimap-logout-timeout ++@vindex nnimap-logout-timeout ++ ++There is a case where a connection to a @acronym{IMAP} server is unable ++to close, when connecting to the server via a certain kind of network, ++e.g. @acronym{VPN}. In that case, it will be observed that a connection ++between Emacs and the local network looks alive even if the server has ++closed a connection for some reason (typically, a timeout). ++Consequently, Emacs continues waiting for a response from the server for ++the @code{LOGOUT} command that Emacs sent, or hangs in other words. If ++you are in such a network, setting this variable to a number of seconds ++will be helpful. If it is set, a hung connection will be closed ++forcibly, after this number of seconds from the time Emacs sends the ++@code{LOGOUT} command. It should not be too small value but too large ++value will be inconvenient too. Perhaps the value 1.0 will be a good ++candidate but it might be worth trying some other values. ++ ++Example server specification: ++ ++@lisp ++(nnimap "mail.server.com" ++ (nnimap-logout-timeout 1.0)) ++@end lisp ++ ++@end table ++ ++@menu ++* Splitting in IMAP:: Splitting mail with nnimap. ++* Expiring in IMAP:: Expiring mail with nnimap. ++* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. ++* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button. ++* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus. ++* Debugging IMAP:: What to do when things don't work. ++@end menu ++ ++ ++ ++@node Splitting in IMAP ++@subsection Splitting in IMAP ++@cindex splitting imap mail ++ ++Splitting is something Gnus users have loved and used for years, and now ++the rest of the world is catching up. Yeah, dream on, not many ++@acronym{IMAP} servers have server side splitting and those that have ++splitting seem to use some non-standard protocol. This means that ++@acronym{IMAP} support for Gnus has to do its own splitting. ++ ++And it does. ++ ++(Incidentally, people seem to have been dreaming on, and Sieve has ++gaining a market share and is supported by several IMAP servers. ++Fortunately, Gnus support it too, @xref{Sieve Commands}.) ++ ++Here are the variables of interest: ++ ++@table @code ++ ++@item nnimap-split-crosspost ++@cindex splitting, crosspost ++@cindex crosspost ++@vindex nnimap-split-crosspost ++ ++If non-@code{nil}, do crossposting if several split methods match the ++mail. If @code{nil}, the first match in @code{nnimap-split-rule} ++found will be used. ++ ++Nnmail equivalent: @code{nnmail-crosspost}. ++ ++@item nnimap-split-inbox ++@cindex splitting, inbox ++@cindex inbox ++@vindex nnimap-split-inbox ++ ++A string or a list of strings that gives the name(s) of @acronym{IMAP} ++mailboxes to split from. Defaults to @code{nil}, which means that ++splitting is disabled! ++ ++@lisp ++(setq nnimap-split-inbox ++ '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap")) ++@end lisp ++ ++No nnmail equivalent. ++ ++@item nnimap-split-rule ++@cindex splitting, rules ++@vindex nnimap-split-rule ++ ++New mail found in @code{nnimap-split-inbox} will be split according to ++this variable. ++ ++This variable contains a list of lists, where the first element in the ++sublist gives the name of the @acronym{IMAP} mailbox to move articles ++matching the regexp in the second element in the sublist. Got that? ++Neither did I, we need examples. ++ ++@lisp ++(setq nnimap-split-rule ++ '(("INBOX.nnimap" ++ "^Sender: owner-nnimap@@vic20.globalcom.se") ++ ("INBOX.junk" "^Subject:.*MAKE MONEY") ++ ("INBOX.private" ""))) ++@end lisp ++ ++This will put all articles from the nnimap mailing list into mailbox ++INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line ++into INBOX.junk and everything else in INBOX.private. ++ ++The first string may contain @samp{\\1} forms, like the ones used by ++replace-match to insert sub-expressions from the matched text. For ++instance: ++ ++@lisp ++("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@@") ++@end lisp ++ ++The first element can also be the symbol @code{junk} to indicate that ++matching messages should simply be deleted. Use with care. ++ ++The second element can also be a function. In that case, it will be ++called with the first element of the rule as the argument, in a buffer ++containing the headers of the article. It should return a ++non-@code{nil} value if it thinks that the mail belongs in that group. ++ ++Nnmail users might recollect that the last regexp had to be empty to ++match all articles (like in the example above). This is not required in ++nnimap. Articles not matching any of the regexps will not be moved out ++of your inbox. (This might affect performance if you keep lots of ++unread articles in your inbox, since the splitting code would go over ++them every time you fetch new mail.) ++ ++These rules are processed from the beginning of the alist toward the ++end. The first rule to make a match will ``win'', unless you have ++crossposting enabled. In that case, all matching rules will ``win''. ++ ++This variable can also have a function as its value, the function will ++be called with the headers narrowed and should return a group where it ++thinks the article should be split to. See @code{nnimap-split-fancy}. ++ ++The splitting code tries to create mailboxes if it needs to. ++ ++To allow for different split rules on different virtual servers, and ++even different split rules in different inboxes on the same server, ++the syntax of this variable have been extended along the lines of: ++ ++@lisp ++(setq nnimap-split-rule ++ '(("my1server" (".*" (("ding" "ding@@gnus.org") ++ ("junk" "From:.*Simon")))) ++ ("my2server" ("INBOX" nnimap-split-fancy)) ++ ("my[34]server" (".*" (("private" "To:.*Simon") ++ ("junk" my-junk-func)))))) ++@end lisp ++ ++The virtual server name is in fact a regexp, so that the same rules ++may apply to several servers. In the example, the servers ++@code{my3server} and @code{my4server} both use the same rules. ++Similarly, the inbox string is also a regexp. The actual splitting ++rules are as before, either a function, or a list with group/regexp or ++group/function elements. ++ ++Nnmail equivalent: @code{nnmail-split-methods}. ++ ++@item nnimap-split-predicate ++@cindex splitting ++@vindex nnimap-split-predicate ++ ++Mail matching this predicate in @code{nnimap-split-inbox} will be ++split, it is a string and the default is @samp{UNSEEN UNDELETED}. ++ ++This might be useful if you use another @acronym{IMAP} client to read mail in ++your inbox but would like Gnus to split all articles in the inbox ++regardless of readedness. Then you might change this to ++@samp{UNDELETED}. ++ ++@item nnimap-split-fancy ++@cindex splitting, fancy ++@findex nnimap-split-fancy ++@vindex nnimap-split-fancy ++ ++It's possible to set @code{nnimap-split-rule} to ++@code{nnmail-split-fancy} if you want to use fancy ++splitting. @xref{Fancy Mail Splitting}. ++ ++However, to be able to have different fancy split rules for nnmail and ++nnimap back ends you can set @code{nnimap-split-rule} to ++@code{nnimap-split-fancy} and define the nnimap specific fancy split ++rule in @code{nnimap-split-fancy}. ++ ++Example: ++ ++@lisp ++(setq nnimap-split-rule 'nnimap-split-fancy ++ nnimap-split-fancy ...) ++@end lisp ++ ++Nnmail equivalent: @code{nnmail-split-fancy}. ++ ++@item nnimap-split-download-body ++@findex nnimap-split-download-body ++@vindex nnimap-split-download-body ++ ++Set to non-@code{nil} to download entire articles during splitting. ++This is generally not required, and will slow things down ++considerably. You may need it if you want to use an advanced ++splitting function that analyzes the body to split the article. ++ ++@end table ++ ++@node Expiring in IMAP ++@subsection Expiring in IMAP ++@cindex expiring @acronym{IMAP} mail ++ ++Even though @code{nnimap} is not a proper @code{nnmail} derived back ++end, it supports most features in regular expiring (@pxref{Expiring ++Mail}). Unlike splitting in @acronym{IMAP} (@pxref{Splitting in ++IMAP}) it does not clone the @code{nnmail} variables (i.e., creating ++@var{nnimap-expiry-wait}) but reuse the @code{nnmail} variables. What ++follows below are the variables used by the @code{nnimap} expiry ++process. ++ ++A note on how the expire mark is stored on the @acronym{IMAP} server is ++appropriate here as well. The expire mark is translated into a ++@code{imap} client specific mark, @code{gnus-expire}, and stored on the ++message. This means that likely only Gnus will understand and treat ++the @code{gnus-expire} mark properly, although other clients may allow ++you to view client specific flags on the message. It also means that ++your server must support permanent storage of client specific flags on ++messages. Most do, fortunately. ++ ++If expiring @acronym{IMAP} mail seems very slow, try setting the server ++variable @code{nnimap-search-uids-not-since-is-evil}. ++ ++@table @code ++ ++@item nnmail-expiry-wait ++@item nnmail-expiry-wait-function ++ ++These variables are fully supported. The expire value can be a ++number, the symbol @code{immediate} or @code{never}. ++ ++@item nnmail-expiry-target ++ ++This variable is supported, and internally implemented by calling the ++@code{nnmail} functions that handle this. It contains an optimization ++that if the destination is a @acronym{IMAP} group on the same server, the ++article is copied instead of appended (that is, uploaded again). ++ ++@end table ++ ++@node Editing IMAP ACLs ++@subsection Editing IMAP ACLs ++@cindex editing imap acls ++@cindex Access Control Lists ++@cindex Editing @acronym{IMAP} ACLs ++@kindex G l (Group) ++@findex gnus-group-nnimap-edit-acl ++ ++ACL stands for Access Control List. ACLs are used in @acronym{IMAP} for ++limiting (or enabling) other users access to your mail boxes. Not all ++@acronym{IMAP} servers support this, this function will give an error if it ++doesn't. ++ ++To edit an ACL for a mailbox, type @kbd{G l} ++(@code{gnus-group-edit-nnimap-acl}) and you'll be presented with an ACL ++editing window with detailed instructions. ++ ++Some possible uses: ++ ++@itemize @bullet ++@item ++Giving ``anyone'' the ``lrs'' rights (lookup, read, keep seen/unseen flags) ++on your mailing list mailboxes enables other users on the same server to ++follow the list without subscribing to it. ++@item ++At least with the Cyrus server, you are required to give the user ++``anyone'' posting ("p") capabilities to have ``plussing'' work (that is, ++mail sent to user+mailbox@@domain ending up in the @acronym{IMAP} mailbox ++INBOX.mailbox). ++@end itemize ++ ++@node Expunging mailboxes ++@subsection Expunging mailboxes ++@cindex expunging ++ ++@cindex expunge ++@cindex manual expunging ++@kindex G x (Group) ++@findex gnus-group-nnimap-expunge ++ ++If you're using the @code{never} setting of @code{nnimap-expunge-on-close}, ++you may want the option of expunging all deleted articles in a mailbox ++manually. This is exactly what @kbd{G x} does. ++ ++Currently there is no way of showing deleted articles, you can just ++delete them. ++ ++@node A note on namespaces ++@subsection A note on namespaces ++@cindex IMAP namespace ++@cindex namespaces ++ ++The @acronym{IMAP} protocol has a concept called namespaces, described ++by the following text in the RFC2060: ++ ++@display ++5.1.2. Mailbox Namespace Naming Convention ++ ++ By convention, the first hierarchical element of any mailbox name ++ which begins with "#" identifies the "namespace" of the remainder of ++ the name. This makes it possible to disambiguate between different ++ types of mailbox stores, each of which have their own namespaces. ++ ++ For example, implementations which offer access to USENET ++ newsgroups MAY use the "#news" namespace to partition the USENET ++ newsgroup namespace from that of other mailboxes. Thus, the ++ comp.mail.misc newsgroup would have an mailbox name of ++ "#news.comp.mail.misc", and the name "comp.mail.misc" could refer ++ to a different object (e.g. a user's private mailbox). ++@end display ++ ++While there is nothing in this text that warrants concern for the ++@acronym{IMAP} implementation in Gnus, some servers use namespace ++prefixes in a way that does not work with how Gnus uses mailbox names. ++ ++Specifically, University of Washington's @acronym{IMAP} server uses ++mailbox names like @code{#driver.mbx/read-mail} which are valid only ++in the @sc{create} and @sc{append} commands. After the mailbox is ++created (or a messages is appended to a mailbox), it must be accessed ++without the namespace prefix, i.e. @code{read-mail}. Since Gnus do ++not make it possible for the user to guarantee that user entered ++mailbox names will only be used with the CREATE and APPEND commands, ++you should simply not use the namespace prefixed mailbox names in ++Gnus. ++ ++See the UoW IMAPD documentation for the @code{#driver.*/} prefix ++for more information on how to use the prefixes. They are a power ++tool and should be used only if you are sure what the effects are. ++ ++@node Debugging IMAP ++@subsection Debugging IMAP ++@cindex IMAP debugging ++@cindex protocol dump (IMAP) ++ ++@acronym{IMAP} is a complex protocol, more so than @acronym{NNTP} or ++@acronym{POP3}. Implementation bugs are not unlikely, and we do our ++best to fix them right away. If you encounter odd behavior, chances ++are that either the server or Gnus is buggy. ++ ++If you are familiar with network protocols in general, you will ++probably be able to extract some clues from the protocol dump of the ++exchanges between Gnus and the server. Even if you are not familiar ++with network protocols, when you include the protocol dump in ++@acronym{IMAP}-related bug reports you are helping us with data ++critical to solving the problem. Therefore, we strongly encourage you ++to include the protocol dump when reporting IMAP bugs in Gnus. ++ ++ ++@vindex imap-log ++Because the protocol dump, when enabled, generates lots of data, it is ++disabled by default. You can enable it by setting @code{imap-log} as ++follows: ++ ++@lisp ++(setq imap-log t) ++@end lisp ++ ++This instructs the @code{imap.el} package to log any exchanges with ++the server. The log is stored in the buffer @samp{*imap-log*}. Look ++for error messages, which sometimes are tagged with the keyword ++@code{BAD}---but when submitting a bug, make sure to include all the ++data. ++ ++@node Other Sources ++@section Other Sources ++ ++Gnus can do more than just read news or mail. The methods described ++below allow Gnus to view directories and files as if they were ++newsgroups. ++ ++@menu ++* Directory Groups:: You can read a directory as if it was a newsgroup. ++* Anything Groups:: Dired? Who needs dired? ++* Document Groups:: Single files can be the basis of a group. ++* SOUP:: Reading @sc{soup} packets ``offline''. ++* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. ++@end menu ++ ++ ++@node Directory Groups ++@subsection Directory Groups ++@cindex nndir ++@cindex directory groups ++ ++If you have a directory that has lots of articles in separate files in ++it, you might treat it as a newsgroup. The files have to have numerical ++names, of course. ++ ++This might be an opportune moment to mention @code{ange-ftp} (and its ++successor @code{efs}), that most wonderful of all wonderful Emacs ++packages. When I wrote @code{nndir}, I didn't think much about it---a ++back end to read directories. Big deal. ++ ++@code{ange-ftp} changes that picture dramatically. For instance, if you ++enter the @code{ange-ftp} file name ++@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name, ++@code{ange-ftp} or @code{efs} will actually allow you to read this ++directory over at @samp{sina} as a newsgroup. Distributed news ahoy! ++ ++@code{nndir} will use @acronym{NOV} files if they are present. ++ ++@code{nndir} is a ``read-only'' back end---you can't delete or expire ++articles with this method. You can use @code{nnmh} or @code{nnml} for ++whatever you use @code{nndir} for, so you could switch to any of those ++methods if you feel the need to have a non-read-only @code{nndir}. ++ ++ ++@node Anything Groups ++@subsection Anything Groups ++@cindex nneething ++ ++From the @code{nndir} back end (which reads a single spool-like ++directory), it's just a hop and a skip to @code{nneething}, which ++pretends that any arbitrary directory is a newsgroup. Strange, but ++true. ++ ++When @code{nneething} is presented with a directory, it will scan this ++directory and assign article numbers to each file. When you enter such ++a group, @code{nneething} must create ``headers'' that Gnus can use. ++After all, Gnus is a newsreader, in case you're forgetting. ++@code{nneething} does this in a two-step process. First, it snoops each ++file in question. If the file looks like an article (i.e., the first ++few lines look like headers), it will use this as the head. If this is ++just some arbitrary file without a head (e.g. a C source file), ++@code{nneething} will cobble up a header out of thin air. It will use ++file ownership, name and date and do whatever it can with these ++elements. ++ ++All this should happen automatically for you, and you will be presented ++with something that looks very much like a newsgroup. Totally like a ++newsgroup, to be precise. If you select an article, it will be displayed ++in the article buffer, just as usual. ++ ++If you select a line that represents a directory, Gnus will pop you into ++a new summary buffer for this @code{nneething} group. And so on. You can ++traverse the entire disk this way, if you feel like, but remember that ++Gnus is not dired, really, and does not intend to be, either. ++ ++There are two overall modes to this action---ephemeral or solid. When ++doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus ++will not store information on what files you have read, and what files ++are new, and so on. If you create a solid @code{nneething} group the ++normal way with @kbd{G m}, Gnus will store a mapping table between ++article numbers and file names, and you can treat this group like any ++other groups. When you activate a solid @code{nneething} group, you will ++be told how many unread articles it contains, etc., etc. ++ ++Some variables: ++ ++@table @code ++@item nneething-map-file-directory ++@vindex nneething-map-file-directory ++All the mapping files for solid @code{nneething} groups will be stored ++in this directory, which defaults to @file{~/.nneething/}. ++ ++@item nneething-exclude-files ++@vindex nneething-exclude-files ++All files that match this regexp will be ignored. Nice to use to exclude ++auto-save files and the like, which is what it does by default. ++ ++@item nneething-include-files ++@vindex nneething-include-files ++Regexp saying what files to include in the group. If this variable is ++non-@code{nil}, only files matching this regexp will be included. ++ ++@item nneething-map-file ++@vindex nneething-map-file ++Name of the map files. ++@end table ++ ++ ++@node Document Groups ++@subsection Document Groups ++@cindex nndoc ++@cindex documentation group ++@cindex help group ++ ++@code{nndoc} is a cute little thing that will let you read a single file ++as a newsgroup. Several files types are supported: ++ ++@table @code ++@cindex Babyl ++@item babyl ++The Babyl format. ++ ++@cindex mbox ++@cindex Unix mbox ++@item mbox ++The standard Unix mbox file. ++ ++@cindex MMDF mail box ++@item mmdf ++The MMDF mail box format. ++ ++@item news ++Several news articles appended into a file. ++ ++@cindex rnews batch files ++@item rnews ++The rnews batch transport format. ++ ++@item nsmail ++Netscape mail boxes. ++ ++@item mime-parts ++@acronym{MIME} multipart messages. ++ ++@item standard-digest ++The standard (RFC 1153) digest format. ++ ++@item mime-digest ++A @acronym{MIME} digest of messages. ++ ++@item lanl-gov-announce ++Announcement messages from LANL Gov Announce. ++ ++@cindex forwarded messages ++@item rfc822-forward ++A message forwarded according to RFC822. ++ ++@item outlook ++The Outlook mail box. ++ ++@item oe-dbx ++The Outlook Express dbx mail box. ++ ++@item exim-bounce ++A bounce message from the Exim MTA. ++ ++@item forward ++A message forwarded according to informal rules. ++ ++@item rfc934 ++An RFC934-forwarded message. ++ ++@item mailman ++A mailman digest. ++ ++@item clari-briefs ++A digest of Clarinet brief news items. ++ ++@item slack-digest ++Non-standard digest format---matches most things, but does it badly. ++ ++@item mail-in-mail ++The last resort. ++@end table ++ ++You can also use the special ``file type'' @code{guess}, which means ++that @code{nndoc} will try to guess what file type it is looking at. ++@code{digest} means that @code{nndoc} should guess what digest type the ++file is. ++ ++@code{nndoc} will not try to change the file or insert any extra headers into ++it---it will simply, like, let you use the file as the basis for a ++group. And that's it. ++ ++If you have some old archived articles that you want to insert into your ++new & spiffy Gnus mail back end, @code{nndoc} can probably help you with ++that. Say you have an old @file{RMAIL} file with mail that you now want ++to split into your new @code{nnml} groups. You look at that file using ++@code{nndoc} (using the @kbd{G f} command in the group buffer ++(@pxref{Foreign Groups})), set the process mark on all the articles in ++the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) ++using @code{nnml}. If all goes well, all the mail in the @file{RMAIL} ++file is now also stored in lots of @code{nnml} directories, and you can ++delete that pesky @file{RMAIL} file. If you have the guts! ++ ++Virtual server variables: ++ ++@table @code ++@item nndoc-article-type ++@vindex nndoc-article-type ++This should be one of @code{mbox}, @code{babyl}, @code{digest}, ++@code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934}, ++@code{rfc822-forward}, @code{mime-parts}, @code{standard-digest}, ++@code{slack-digest}, @code{clari-briefs}, @code{nsmail}, @code{outlook}, ++@code{oe-dbx}, @code{mailman}, and @code{mail-in-mail} or @code{guess}. ++ ++@item nndoc-post-type ++@vindex nndoc-post-type ++This variable says whether Gnus is to consider the group a news group or ++a mail group. There are two valid values: @code{mail} (the default) ++and @code{news}. ++@end table ++ ++@menu ++* Document Server Internals:: How to add your own document types. ++@end menu ++ ++ ++@node Document Server Internals ++@subsubsection Document Server Internals ++ ++Adding new document types to be recognized by @code{nndoc} isn't ++difficult. You just have to whip up a definition of what the document ++looks like, write a predicate function to recognize that document type, ++and then hook into @code{nndoc}. ++ ++First, here's an example document type definition: ++ ++@example ++(mmdf ++ (article-begin . "^\^A\^A\^A\^A\n") ++ (body-end . "^\^A\^A\^A\^A\n")) ++@end example ++ ++The definition is simply a unique @dfn{name} followed by a series of ++regexp pseudo-variable settings. Below are the possible ++variables---don't be daunted by the number of variables; most document ++types can be defined with very few settings: ++ ++@table @code ++@item first-article ++If present, @code{nndoc} will skip past all text until it finds ++something that match this regexp. All text before this will be ++totally ignored. ++ ++@item article-begin ++This setting has to be present in all document type definitions. It ++says what the beginning of each article looks like. To do more ++complicated things that cannot be dealt with a simple regexp, you can ++use @code{article-begin-function} instead of this. ++ ++@item article-begin-function ++If present, this should be a function that moves point to the beginning ++of each article. This setting overrides @code{article-begin}. ++ ++@item head-begin ++If present, this should be a regexp that matches the head of the ++article. To do more complicated things that cannot be dealt with a ++simple regexp, you can use @code{head-begin-function} instead of this. ++ ++@item head-begin-function ++If present, this should be a function that moves point to the head of ++the article. This setting overrides @code{head-begin}. ++ ++@item head-end ++This should match the end of the head of the article. It defaults to ++@samp{^$}---the empty line. ++ ++@item body-begin ++This should match the beginning of the body of the article. It defaults ++to @samp{^\n}. To do more complicated things that cannot be dealt with ++a simple regexp, you can use @code{body-begin-function} instead of this. ++ ++@item body-begin-function ++If present, this function should move point to the beginning of the body ++of the article. This setting overrides @code{body-begin}. ++ ++@item body-end ++If present, this should match the end of the body of the article. To do ++more complicated things that cannot be dealt with a simple regexp, you ++can use @code{body-end-function} instead of this. ++ ++@item body-end-function ++If present, this function should move point to the end of the body of ++the article. This setting overrides @code{body-end}. ++ ++@item file-begin ++If present, this should match the beginning of the file. All text ++before this regexp will be totally ignored. ++ ++@item file-end ++If present, this should match the end of the file. All text after this ++regexp will be totally ignored. ++ ++@end table ++ ++So, using these variables @code{nndoc} is able to dissect a document ++file into a series of articles, each with a head and a body. However, a ++few more variables are needed since not all document types are all that ++news-like---variables needed to transform the head or the body into ++something that's palatable for Gnus: ++ ++@table @code ++@item prepare-body-function ++If present, this function will be called when requesting an article. It ++will be called with point at the start of the body, and is useful if the ++document has encoded some parts of its contents. ++ ++@item article-transform-function ++If present, this function is called when requesting an article. It's ++meant to be used for more wide-ranging transformation of both head and ++body of the article. ++ ++@item generate-head-function ++If present, this function is called to generate a head that Gnus can ++understand. It is called with the article number as a parameter, and is ++expected to generate a nice head for the article in question. It is ++called when requesting the headers of all articles. ++ ++@item generate-article-function ++If present, this function is called to generate an entire article that ++Gnus can understand. It is called with the article number as a ++parameter when requesting all articles. ++ ++@item dissection-function ++If present, this function is called to dissect a document by itself, ++overriding @code{first-article}, @code{article-begin}, ++@code{article-begin-function}, @code{head-begin}, ++@code{head-begin-function}, @code{head-end}, @code{body-begin}, ++@code{body-begin-function}, @code{body-end}, @code{body-end-function}, ++@code{file-begin}, and @code{file-end}. ++ ++@end table ++ ++Let's look at the most complicated example I can come up with---standard ++digests: ++ ++@example ++(standard-digest ++ (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+")) ++ (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+")) ++ (prepare-body-function . nndoc-unquote-dashes) ++ (body-end-function . nndoc-digest-body-end) ++ (head-end . "^ ?$") ++ (body-begin . "^ ?\n") ++ (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$") ++ (subtype digest guess)) ++@end example ++ ++We see that all text before a 70-width line of dashes is ignored; all ++text after a line that starts with that @samp{^End of} is also ignored; ++each article begins with a 30-width line of dashes; the line separating ++the head from the body may contain a single space; and that the body is ++run through @code{nndoc-unquote-dashes} before being delivered. ++ ++To hook your own document definition into @code{nndoc}, use the ++@code{nndoc-add-type} function. It takes two parameters---the first ++is the definition itself and the second (optional) parameter says ++where in the document type definition alist to put this definition. ++The alist is traversed sequentially, and ++@code{nndoc-@var{type}-type-p} is called for a given type @var{type}. ++So @code{nndoc-mmdf-type-p} is called to see whether a document is of ++@code{mmdf} type, and so on. These type predicates should return ++@code{nil} if the document is not of the correct type; @code{t} if it ++is of the correct type; and a number if the document might be of the ++correct type. A high number means high probability; a low number ++means low probability with @samp{0} being the lowest valid number. ++ ++ ++@node SOUP ++@subsection SOUP ++@cindex SOUP ++@cindex offline ++ ++In the PC world people often talk about ``offline'' newsreaders. These ++are thingies that are combined reader/news transport monstrosities. ++With built-in modem programs. Yecchh! ++ ++Of course, us Unix Weenie types of human beans use things like ++@code{uucp} and, like, @code{nntpd} and set up proper news and mail ++transport things like Ghod intended. And then we just use normal ++newsreaders. ++ ++However, it can sometimes be convenient to do something that's a bit ++easier on the brain if you have a very slow modem, and you're not really ++that interested in doing things properly. ++ ++A file format called @sc{soup} has been developed for transporting news ++and mail from servers to home machines and back again. It can be a bit ++fiddly. ++ ++First some terminology: ++ ++@table @dfn ++ ++@item server ++This is the machine that is connected to the outside world and where you ++get news and/or mail from. ++ ++@item home machine ++This is the machine that you want to do the actual reading and responding ++on. It is typically not connected to the rest of the world in any way. ++ ++@item packet ++Something that contains messages and/or commands. There are two kinds ++of packets: ++ ++@table @dfn ++@item message packets ++These are packets made at the server, and typically contain lots of ++messages for you to read. These are called @file{SoupoutX.tgz} by ++default, where @var{x} is a number. ++ ++@item response packets ++These are packets made at the home machine, and typically contains ++replies that you've written. These are called @file{SoupinX.tgz} by ++default, where @var{x} is a number. ++ ++@end table ++ ++@end table ++ ++ ++@enumerate ++ ++@item ++You log in on the server and create a @sc{soup} packet. You can either ++use a dedicated @sc{soup} thingie (like the @code{awk} program), or you ++can use Gnus to create the packet with its @sc{soup} commands (@kbd{O ++s} and/or @kbd{G s b}; and then @kbd{G s p}) (@pxref{SOUP Commands}). ++ ++@item ++You transfer the packet home. Rail, boat, car or modem will do fine. ++ ++@item ++You put the packet in your home directory. ++ ++@item ++You fire up Gnus on your home machine using the @code{nnsoup} back end as ++the native or secondary server. ++ ++@item ++You read articles and mail and answer and followup to the things you ++want (@pxref{SOUP Replies}). ++ ++@item ++You do the @kbd{G s r} command to pack these replies into a @sc{soup} ++packet. ++ ++@item ++You transfer this packet to the server. ++ ++@item ++You use Gnus to mail this packet out with the @kbd{G s s} command. ++ ++@item ++You then repeat until you die. ++ ++@end enumerate ++ ++So you basically have a bipartite system---you use @code{nnsoup} for ++reading and Gnus for packing/sending these @sc{soup} packets. ++ ++@menu ++* SOUP Commands:: Commands for creating and sending @sc{soup} packets ++* SOUP Groups:: A back end for reading @sc{soup} packets. ++* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news. ++@end menu ++ ++ ++@node SOUP Commands ++@subsubsection SOUP Commands ++ ++These are commands for creating and manipulating @sc{soup} packets. ++ ++@table @kbd ++@item G s b ++@kindex G s b (Group) ++@findex gnus-group-brew-soup ++Pack all unread articles in the current group ++(@code{gnus-group-brew-soup}). This command understands the ++process/prefix convention. ++ ++@item G s w ++@kindex G s w (Group) ++@findex gnus-soup-save-areas ++Save all @sc{soup} data files (@code{gnus-soup-save-areas}). ++ ++@item G s s ++@kindex G s s (Group) ++@findex gnus-soup-send-replies ++Send all replies from the replies packet ++(@code{gnus-soup-send-replies}). ++ ++@item G s p ++@kindex G s p (Group) ++@findex gnus-soup-pack-packet ++Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}). ++ ++@item G s r ++@kindex G s r (Group) ++@findex nnsoup-pack-replies ++Pack all replies into a replies packet (@code{nnsoup-pack-replies}). ++ ++@item O s ++@kindex O s (Summary) ++@findex gnus-soup-add-article ++This summary-mode command adds the current article to a @sc{soup} packet ++(@code{gnus-soup-add-article}). It understands the process/prefix ++convention (@pxref{Process/Prefix}). ++ ++@end table ++ ++ ++There are a few variables to customize where Gnus will put all these ++thingies: ++ ++@table @code ++ ++@item gnus-soup-directory ++@vindex gnus-soup-directory ++Directory where Gnus will save intermediate files while composing ++@sc{soup} packets. The default is @file{~/SoupBrew/}. ++ ++@item gnus-soup-replies-directory ++@vindex gnus-soup-replies-directory ++This is what Gnus will use as a temporary directory while sending our ++reply packets. @file{~/SoupBrew/SoupReplies/} is the default. ++ ++@item gnus-soup-prefix-file ++@vindex gnus-soup-prefix-file ++Name of the file where Gnus stores the last used prefix. The default is ++@samp{gnus-prefix}. ++ ++@item gnus-soup-packer ++@vindex gnus-soup-packer ++A format string command for packing a @sc{soup} packet. The default is ++@samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}. ++ ++@item gnus-soup-unpacker ++@vindex gnus-soup-unpacker ++Format string command for unpacking a @sc{soup} packet. The default is ++@samp{gunzip -c %s | tar xvf -}. ++ ++@item gnus-soup-packet-directory ++@vindex gnus-soup-packet-directory ++Where Gnus will look for reply packets. The default is @file{~/}. ++ ++@item gnus-soup-packet-regexp ++@vindex gnus-soup-packet-regexp ++Regular expression matching @sc{soup} reply packets in ++@code{gnus-soup-packet-directory}. ++ ++@end table ++ ++ ++@node SOUP Groups ++@subsubsection SOUP Groups ++@cindex nnsoup ++ ++@code{nnsoup} is the back end for reading @sc{soup} packets. It will ++read incoming packets, unpack them, and put them in a directory where ++you can read them at leisure. ++ ++These are the variables you can use to customize its behavior: ++ ++@table @code ++ ++@item nnsoup-tmp-directory ++@vindex nnsoup-tmp-directory ++When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this ++directory. (@file{/tmp/} by default.) ++ ++@item nnsoup-directory ++@vindex nnsoup-directory ++@code{nnsoup} then moves each message and index file to this directory. ++The default is @file{~/SOUP/}. ++ ++@item nnsoup-replies-directory ++@vindex nnsoup-replies-directory ++All replies will be stored in this directory before being packed into a ++reply packet. The default is @file{~/SOUP/replies/}. ++ ++@item nnsoup-replies-format-type ++@vindex nnsoup-replies-format-type ++The @sc{soup} format of the replies packets. The default is @samp{?n} ++(rnews), and I don't think you should touch that variable. I probably ++shouldn't even have documented it. Drats! Too late! ++ ++@item nnsoup-replies-index-type ++@vindex nnsoup-replies-index-type ++The index type of the replies packet. The default is @samp{?n}, which ++means ``none''. Don't fiddle with this one either! ++ ++@item nnsoup-active-file ++@vindex nnsoup-active-file ++Where @code{nnsoup} stores lots of information. This is not an ``active ++file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose ++this file or mess it up in any way, you're dead. The default is ++@file{~/SOUP/active}. ++ ++@item nnsoup-packer ++@vindex nnsoup-packer ++Format string command for packing a reply @sc{soup} packet. The default ++is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}. ++ ++@item nnsoup-unpacker ++@vindex nnsoup-unpacker ++Format string command for unpacking incoming @sc{soup} packets. The ++default is @samp{gunzip -c %s | tar xvf -}. ++ ++@item nnsoup-packet-directory ++@vindex nnsoup-packet-directory ++Where @code{nnsoup} will look for incoming packets. The default is ++@file{~/}. ++ ++@item nnsoup-packet-regexp ++@vindex nnsoup-packet-regexp ++Regular expression matching incoming @sc{soup} packets. The default is ++@samp{Soupout}. ++ ++@item nnsoup-always-save ++@vindex nnsoup-always-save ++If non-@code{nil}, save the replies buffer after each posted message. ++ ++@end table ++ ++ ++@node SOUP Replies ++@subsubsection SOUP Replies ++ ++Just using @code{nnsoup} won't mean that your postings and mailings end ++up in @sc{soup} reply packets automagically. You have to work a bit ++more for that to happen. ++ ++@findex nnsoup-set-variables ++The @code{nnsoup-set-variables} command will set the appropriate ++variables to ensure that all your followups and replies end up in the ++@sc{soup} system. ++ ++In specific, this is what it does: ++ ++@lisp ++(setq message-send-news-function 'nnsoup-request-post) ++(setq message-send-mail-function 'nnsoup-request-mail) ++@end lisp ++ ++And that's it, really. If you only want news to go into the @sc{soup} ++system you just use the first line. If you only want mail to be ++@sc{soup}ed you use the second. ++ ++ ++@node Mail-To-News Gateways ++@subsection Mail-To-News Gateways ++@cindex mail-to-news gateways ++@cindex gateways ++ ++If your local @code{nntp} server doesn't allow posting, for some reason ++or other, you can post using one of the numerous mail-to-news gateways. ++The @code{nngateway} back end provides the interface. ++ ++Note that you can't read anything from this back end---it can only be ++used to post with. ++ ++Server variables: ++ ++@table @code ++@item nngateway-address ++@vindex nngateway-address ++This is the address of the mail-to-news gateway. ++ ++@item nngateway-header-transformation ++@vindex nngateway-header-transformation ++News headers often have to be transformed in some odd way or other ++for the mail-to-news gateway to accept it. This variable says what ++transformation should be called, and defaults to ++@code{nngateway-simple-header-transformation}. The function is called ++narrowed to the headers to be transformed and with one parameter---the ++gateway address. ++ ++This default function just inserts a new @code{To} header based on the ++@code{Newsgroups} header and the gateway address. ++For instance, an article with this @code{Newsgroups} header: ++ ++@example ++Newsgroups: alt.religion.emacs ++@end example ++ ++will get this @code{To} header inserted: ++ ++@example ++To: alt-religion-emacs@@GATEWAY ++@end example ++ ++The following pre-defined functions exist: ++ ++@findex nngateway-simple-header-transformation ++@table @code ++ ++@item nngateway-simple-header-transformation ++Creates a @code{To} header that looks like ++@var{newsgroup}@@@code{nngateway-address}. ++ ++@findex nngateway-mail2news-header-transformation ++ ++@item nngateway-mail2news-header-transformation ++Creates a @code{To} header that looks like ++@code{nngateway-address}. ++@end table ++ ++@end table ++ ++Here's an example: ++ ++@lisp ++(setq gnus-post-method ++ '(nngateway ++ "mail2news@@replay.com" ++ (nngateway-header-transformation ++ nngateway-mail2news-header-transformation))) ++@end lisp ++ ++So, to use this, simply say something like: ++ ++@lisp ++(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS")) ++@end lisp ++ ++ ++ ++@node Combined Groups ++@section Combined Groups ++ ++Gnus allows combining a mixture of all the other group types into bigger ++groups. ++ ++@menu ++* Virtual Groups:: Combining articles from many groups. ++* Kibozed Groups:: Looking through parts of the newsfeed for articles. ++@end menu ++ ++ ++@node Virtual Groups ++@subsection Virtual Groups ++@cindex nnvirtual ++@cindex virtual groups ++@cindex merging groups ++ ++An @dfn{nnvirtual group} is really nothing more than a collection of ++other groups. ++ ++For instance, if you are tired of reading many small groups, you can ++put them all in one big group, and then grow tired of reading one ++big, unwieldy group. The joys of computing! ++ ++You specify @code{nnvirtual} as the method. The address should be a ++regexp to match component groups. ++ ++All marks in the virtual group will stick to the articles in the ++component groups. So if you tick an article in a virtual group, the ++article will also be ticked in the component group from whence it ++came. (And vice versa---marks from the component groups will also be ++shown in the virtual group.). To create an empty virtual group, run ++@kbd{G V} (@code{gnus-group-make-empty-virtual}) in the group buffer ++and edit the method regexp with @kbd{M-e} ++(@code{gnus-group-edit-group-method}) ++ ++Here's an example @code{nnvirtual} method that collects all Andrea Dworkin ++newsgroups into one, big, happy newsgroup: ++ ++@lisp ++(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*") ++@end lisp ++ ++The component groups can be native or foreign; everything should work ++smoothly, but if your computer explodes, it was probably my fault. ++ ++Collecting the same group from several servers might actually be a good ++idea if users have set the Distribution header to limit distribution. ++If you would like to read @samp{soc.motss} both from a server in Japan ++and a server in Norway, you could use the following as the group regexp: ++ ++@example ++"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$" ++@end example ++ ++(Remember, though, that if you're creating the group with @kbd{G m}, you ++shouldn't double the backslashes, and you should leave off the quote ++characters at the beginning and the end of the string.) ++ ++This should work kinda smoothly---all articles from both groups should ++end up in this one, and there should be no duplicates. Threading (and ++the rest) will still work as usual, but there might be problems with the ++sequence of articles. Sorting on date might be an option here ++(@pxref{Selecting a Group}). ++ ++One limitation, however---all groups included in a virtual ++group have to be alive (i.e., subscribed or unsubscribed). Killed or ++zombie groups can't be component groups for @code{nnvirtual} groups. ++ ++@vindex nnvirtual-always-rescan ++If the @code{nnvirtual-always-rescan} variable is non-@code{nil} (which ++is the default), @code{nnvirtual} will always scan groups for unread ++articles when entering a virtual group. If this variable is @code{nil} ++and you read articles in a component group after the virtual group has ++been activated, the read articles from the component group will show up ++when you enter the virtual group. You'll also see this effect if you ++have two virtual groups that have a component group in common. If ++that's the case, you should set this variable to @code{t}. Or you can ++just tap @code{M-g} on the virtual group every time before you enter ++it---it'll have much the same effect. ++ ++@code{nnvirtual} can have both mail and news groups as component groups. ++When responding to articles in @code{nnvirtual} groups, @code{nnvirtual} ++has to ask the back end of the component group the article comes from ++whether it is a news or mail back end. However, when you do a @kbd{^}, ++there is typically no sure way for the component back end to know this, ++and in that case @code{nnvirtual} tells Gnus that the article came from a ++not-news back end. (Just to be on the safe side.) ++ ++@kbd{C-c C-n} in the message buffer will insert the @code{Newsgroups} ++line from the article you respond to in these cases. ++ ++@code{nnvirtual} groups do not inherit anything but articles and marks ++from component groups---group parameters, for instance, are not ++inherited. ++ ++ ++@node Kibozed Groups ++@subsection Kibozed Groups ++@cindex nnkiboze ++@cindex kibozing ++ ++@dfn{Kibozing} is defined by the @acronym{OED} as ``grepping through ++(parts of) the news feed''. @code{nnkiboze} is a back end that will ++do this for you. Oh joy! Now you can grind any @acronym{NNTP} server ++down to a halt with useless requests! Oh happiness! ++ ++@kindex G k (Group) ++To create a kibozed group, use the @kbd{G k} command in the group ++buffer. ++ ++The address field of the @code{nnkiboze} method is, as with ++@code{nnvirtual}, a regexp to match groups to be ``included'' in the ++@code{nnkiboze} group. That's where most similarities between ++@code{nnkiboze} and @code{nnvirtual} end. ++ ++In addition to this regexp detailing component groups, an ++@code{nnkiboze} group must have a score file to say what articles are ++to be included in the group (@pxref{Scoring}). ++ ++@kindex M-x nnkiboze-generate-groups ++@findex nnkiboze-generate-groups ++You must run @kbd{M-x nnkiboze-generate-groups} after creating the ++@code{nnkiboze} groups you want to have. This command will take time. ++Lots of time. Oodles and oodles of time. Gnus has to fetch the ++headers from all the articles in all the component groups and run them ++through the scoring process to determine if there are any articles in ++the groups that are to be part of the @code{nnkiboze} groups. ++ ++Please limit the number of component groups by using restrictive ++regexps. Otherwise your sysadmin may become annoyed with you, and the ++@acronym{NNTP} site may throw you off and never let you back in again. ++Stranger things have happened. ++ ++@code{nnkiboze} component groups do not have to be alive---they can be dead, ++and they can be foreign. No restrictions. ++ ++@vindex nnkiboze-directory ++The generation of an @code{nnkiboze} group means writing two files in ++@code{nnkiboze-directory}, which is @file{~/News/kiboze/} by default. ++One contains the @acronym{NOV} header lines for all the articles in ++the group, and the other is an additional @file{.newsrc} file to store ++information on what groups have been searched through to find ++component articles. ++ ++Articles marked as read in the @code{nnkiboze} group will have ++their @acronym{NOV} lines removed from the @acronym{NOV} file. ++ ++ ++@node Email Based Diary ++@section Email Based Diary ++@cindex diary ++@cindex email based diary ++@cindex calendar ++ ++This section describes a special mail back end called @code{nndiary}, ++and its companion library @code{gnus-diary}. It is ``special'' in the ++sense that it is not meant to be one of the standard alternatives for ++reading mail with Gnus. See @ref{Choosing a Mail Back End} for that. ++Instead, it is used to treat @emph{some} of your mails in a special way, ++namely, as event reminders. ++ ++Here is a typical scenario: ++ ++@itemize @bullet ++@item ++You've got a date with Andy Mc Dowell or Bruce Willis (select according ++to your sexual preference) in one month. You don't want to forget it. ++@item ++So you send a ``reminder'' message (actually, a diary one) to yourself. ++@item ++You forget all about it and keep on getting and reading new mail, as usual. ++@item ++From time to time, as you type `g' in the group buffer and as the date ++is getting closer, the message will pop up again to remind you of your ++appointment, just as if it were new and unread. ++@item ++Read your ``new'' messages, this one included, and start dreaming again ++of the night you're gonna have. ++@item ++Once the date is over (you actually fell asleep just after dinner), the ++message will be automatically deleted if it is marked as expirable. ++@end itemize ++ ++The Gnus Diary back end has the ability to handle regular appointments ++(that wouldn't ever be deleted) as well as punctual ones, operates as a ++real mail back end and is configurable in many ways. All of this is ++explained in the sections below. ++ ++@menu ++* The NNDiary Back End:: Basic setup and usage. ++* The Gnus Diary Library:: Utility toolkit on top of nndiary. ++* Sending or Not Sending:: A final note on sending diary messages. ++@end menu ++ ++ ++@node The NNDiary Back End ++@subsection The NNDiary Back End ++@cindex nndiary ++@cindex the nndiary back end ++ ++@code{nndiary} is a back end very similar to @code{nnml} (@pxref{Mail ++Spool}). Actually, it could appear as a mix of @code{nnml} and ++@code{nndraft}. If you know @code{nnml}, you're already familiar with ++the message storing scheme of @code{nndiary}: one file per message, one ++directory per group. ++ ++ Before anything, there is one requirement to be able to run ++@code{nndiary} properly: you @emph{must} use the group timestamp feature ++of Gnus. This adds a timestamp to each group's parameters. @ref{Group ++Timestamp} to see how it's done. ++ ++@menu ++* Diary Messages:: What makes a message valid for nndiary. ++* Running NNDiary:: NNDiary has two modes of operation. ++* Customizing NNDiary:: Bells and whistles. ++@end menu ++ ++@node Diary Messages ++@subsubsection Diary Messages ++@cindex nndiary messages ++@cindex nndiary mails ++ ++@code{nndiary} messages are just normal ones, except for the mandatory ++presence of 7 special headers. These headers are of the form ++@code{X-Diary-}, @code{} being one of ++@code{Minute}, @code{Hour}, @code{Dom}, @code{Month}, @code{Year}, ++@code{Time-Zone} and @code{Dow}. @code{Dom} means ``Day of Month'', and ++@code{dow} means ``Day of Week''. These headers actually behave like ++crontab specifications and define the event date(s): ++ ++@itemize @bullet ++@item ++For all headers except the @code{Time-Zone} one, a header value is ++either a star (meaning all possible values), or a list of fields ++(separated by a comma). ++@item ++A field is either an integer, or a range. ++@item ++A range is two integers separated by a dash. ++@item ++Possible integer values are 0--59 for @code{Minute}, 0--23 for ++@code{Hour}, 1--31 for @code{Dom}, 1--12 for @code{Month}, above 1971 ++for @code{Year} and 0--6 for @code{Dow} (0 meaning Sunday). ++@item ++As a special case, a star in either @code{Dom} or @code{Dow} doesn't ++mean ``all possible values'', but ``use only the other field''. Note ++that if both are star'ed, the use of either one gives the same result. ++@item ++The @code{Time-Zone} header is special in that it can only have one ++value (@code{GMT}, for instance). A star doesn't mean ``all possible ++values'' (because it makes no sense), but ``the current local time ++zone''. Most of the time, you'll be using a star here. However, for a ++list of available time zone values, see the variable ++@code{nndiary-headers}. ++@end itemize ++ ++As a concrete example, here are the diary headers to add to your message ++for specifying ``Each Monday and each 1st of month, at 12:00, 20:00, ++21:00, 22:00, 23:00 and 24:00, from 1999 to 2010'' (I'll let you find ++what to do then): ++ ++@example ++X-Diary-Minute: 0 ++X-Diary-Hour: 12, 20-24 ++X-Diary-Dom: 1 ++X-Diary-Month: * ++X-Diary-Year: 1999-2010 ++X-Diary-Dow: 1 ++X-Diary-Time-Zone: * ++@end example ++ ++@node Running NNDiary ++@subsubsection Running NNDiary ++@cindex running nndiary ++@cindex nndiary operation modes ++ ++@code{nndiary} has two modes of operation: ``traditional'' (the default) ++and ``autonomous''. In traditional mode, @code{nndiary} does not get new ++mail by itself. You have to move (@kbd{B m}) or copy (@kbd{B c}) mails ++from your primary mail back end to nndiary groups in order to handle them ++as diary messages. In autonomous mode, @code{nndiary} retrieves its own ++mail and handles it independently from your primary mail back end. ++ ++One should note that Gnus is not inherently designed to allow several ++``master'' mail back ends at the same time. However, this does make ++sense with @code{nndiary}: you really want to send and receive diary ++messages to your diary groups directly. So, @code{nndiary} supports ++being sort of a ``second primary mail back end'' (to my knowledge, it is ++the only back end offering this feature). However, there is a limitation ++(which I hope to fix some day): respooling doesn't work in autonomous ++mode. ++ ++In order to use @code{nndiary} in autonomous mode, you have several ++things to do: ++ ++@itemize @bullet ++@item ++Allow @code{nndiary} to retrieve new mail by itself. Put the following ++line in your @file{~/.gnus.el} file: ++ ++@lisp ++(setq nndiary-get-new-mail t) ++@end lisp ++@item ++You must arrange for diary messages (those containing @code{X-Diary-*} ++headers) to be split in a private folder @emph{before} Gnus treat them. ++Again, this is needed because Gnus cannot (yet ?) properly handle ++multiple primary mail back ends. Getting those messages from a separate ++source will compensate this misfeature to some extent. ++ ++As an example, here's my procmailrc entry to store diary files in ++@file{~/.nndiary} (the default @code{nndiary} mail source file): ++ ++@example ++:0 HD : ++* ^X-Diary ++.nndiary ++@end example ++@end itemize ++ ++Once this is done, you might want to customize the following two options ++that affect the diary mail retrieval and splitting processes: ++ ++@defvar nndiary-mail-sources ++This is the diary-specific replacement for the standard ++@code{mail-sources} variable. It obeys the same syntax, and defaults to ++@code{(file :path "~/.nndiary")}. ++@end defvar ++ ++@defvar nndiary-split-methods ++This is the diary-specific replacement for the standard ++@code{nnmail-split-methods} variable. It obeys the same syntax. ++@end defvar ++ ++ Finally, you may add a permanent @code{nndiary} virtual server ++(something like @code{(nndiary "diary")} should do) to your ++@code{gnus-secondary-select-methods}. ++ ++ Hopefully, almost everything (see the TODO section in ++@file{nndiary.el}) will work as expected when you restart Gnus: in ++autonomous mode, typing @kbd{g} and @kbd{M-g} in the group buffer, will ++also get your new diary mails and split them according to your ++diary-specific rules, @kbd{F} will find your new diary groups etc. ++ ++@node Customizing NNDiary ++@subsubsection Customizing NNDiary ++@cindex customizing nndiary ++@cindex nndiary customization ++ ++Now that @code{nndiary} is up and running, it's time to customize it. ++The custom group is called @code{nndiary} (no, really ?!). You should ++browse it to figure out which options you'd like to tweak. The following ++two variables are probably the only ones you will want to change: ++ ++@defvar nndiary-reminders ++This is the list of times when you want to be reminded of your ++appointments (e.g. 3 weeks before, then 2 days before, then 1 hour ++before and that's it). Remember that ``being reminded'' means that the ++diary message will pop up as brand new and unread again when you get new ++mail. ++@end defvar ++ ++@defvar nndiary-week-starts-on-monday ++Rather self-explanatory. Otherwise, Sunday is assumed (this is the ++default). ++@end defvar ++ ++ ++@node The Gnus Diary Library ++@subsection The Gnus Diary Library ++@cindex gnus-diary ++@cindex the gnus diary library ++ ++Using @code{nndiary} manually (I mean, writing the headers by hand and ++so on) would be rather boring. Fortunately, there is a library called ++@code{gnus-diary} written on top of @code{nndiary}, that does many ++useful things for you. ++ ++ In order to use it, add the following line to your @file{~/.gnus.el} file: ++ ++@lisp ++(require 'gnus-diary) ++@end lisp ++ ++ Also, you shouldn't use any @code{gnus-user-format-function-[d|D]} ++(@pxref{Summary Buffer Lines}). @code{gnus-diary} provides both of these ++(sorry if you used them before). ++ ++ ++@menu ++* Diary Summary Line Format:: A nicer summary buffer line format. ++* Diary Articles Sorting:: A nicer way to sort messages. ++* Diary Headers Generation:: Not doing it manually. ++* Diary Group Parameters:: Not handling them manually. ++@end menu ++ ++@node Diary Summary Line Format ++@subsubsection Diary Summary Line Format ++@cindex diary summary buffer line ++@cindex diary summary line format ++ ++Displaying diary messages in standard summary line format (usually ++something like @samp{From Joe: Subject}) is pretty useless. Most of ++the time, you're the one who wrote the message, and you mostly want to ++see the event's date. ++ ++ @code{gnus-diary} provides two supplemental user formats to be used in ++summary line formats. @code{D} corresponds to a formatted time string ++for the next occurrence of the event (e.g. ``Sat, Sep 22 01, 12:00''), ++while @code{d} corresponds to an approximative remaining time until the ++next occurrence of the event (e.g. ``in 6 months, 1 week''). ++ ++ For example, here's how Joe's birthday is displayed in my ++@code{nndiary+diary:birthdays} summary buffer (note that the message is ++expirable, but will never be deleted, as it specifies a periodic event): ++ ++@example ++ E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week) ++@end example ++ ++In order to get something like the above, you would normally add the ++following line to your diary groups'parameters: ++ ++@lisp ++(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n") ++@end lisp ++ ++However, @code{gnus-diary} does it automatically (@pxref{Diary Group ++Parameters}). You can however customize the provided summary line format ++with the following user options: ++ ++@defvar gnus-diary-summary-line-format ++Defines the summary line format used for diary groups (@pxref{Summary ++Buffer Lines}). @code{gnus-diary} uses it to automatically update the ++diary groups'parameters. ++@end defvar ++ ++@defvar gnus-diary-time-format ++Defines the format to display dates in diary summary buffers. This is ++used by the @code{D} user format. See the docstring for details. ++@end defvar ++ ++@defvar gnus-diary-delay-format-function ++Defines the format function to use for displaying delays (remaining ++times) in diary summary buffers. This is used by the @code{d} user ++format. There are currently built-in functions for English and French; ++you can also define your own. See the docstring for details. ++@end defvar ++ ++@node Diary Articles Sorting ++@subsubsection Diary Articles Sorting ++@cindex diary articles sorting ++@cindex diary summary lines sorting ++@findex gnus-summary-sort-by-schedule ++@findex gnus-thread-sort-by-schedule ++@findex gnus-article-sort-by-schedule ++ ++@code{gnus-diary} provides new sorting functions (@pxref{Sorting the ++Summary Buffer} ) called @code{gnus-summary-sort-by-schedule}, ++@code{gnus-thread-sort-by-schedule} and ++@code{gnus-article-sort-by-schedule}. These functions let you organize ++your diary summary buffers from the closest event to the farthest one. ++ ++@code{gnus-diary} automatically installs ++@code{gnus-summary-sort-by-schedule} as a menu item in the summary ++buffer's ``sort'' menu, and the two others as the primary (hence ++default) sorting functions in the group parameters (@pxref{Diary Group ++Parameters}). ++ ++@node Diary Headers Generation ++@subsubsection Diary Headers Generation ++@cindex diary headers generation ++@findex gnus-diary-check-message ++ ++@code{gnus-diary} provides a function called ++@code{gnus-diary-check-message} to help you handle the @code{X-Diary-*} ++headers. This function ensures that the current message contains all the ++required diary headers, and prompts you for values or corrections if ++needed. ++ ++ This function is hooked into the @code{nndiary} back end, so that ++moving or copying an article to a diary group will trigger it ++automatically. It is also bound to @kbd{C-c C-f d} in ++@code{message-mode} and @code{article-edit-mode} in order to ease the ++process of converting a usual mail to a diary one. ++ ++ This function takes a prefix argument which will force prompting of ++all diary headers, regardless of their presence or validity. That way, ++you can very easily reschedule an already valid diary message, for ++instance. ++ ++@node Diary Group Parameters ++@subsubsection Diary Group Parameters ++@cindex diary group parameters ++ ++When you create a new diary group, or visit one, @code{gnus-diary} ++automatically checks your group parameters and if needed, sets the ++summary line format to the diary-specific value, installs the ++diary-specific sorting functions, and also adds the different ++@code{X-Diary-*} headers to the group's posting-style. It is then easier ++to send a diary message, because if you use @kbd{C-u a} or @kbd{C-u m} ++on a diary group to prepare a message, these headers will be inserted ++automatically (although not filled with proper values yet). ++ ++@node Sending or Not Sending ++@subsection Sending or Not Sending ++ ++Well, assuming you've read all of the above, here are two final notes on ++mail sending with @code{nndiary}: ++ ++@itemize @bullet ++@item ++@code{nndiary} is a @emph{real} mail back end. You really send real diary ++messsages for real. This means for instance that you can give ++appointments to anybody (provided they use Gnus and @code{nndiary}) by ++sending the diary message to them as well. ++@item ++However, since @code{nndiary} also has a @code{request-post} method, you ++can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the ++message won't actually be sent; just stored locally in the group. This ++comes in very handy for private appointments. ++@end itemize ++ ++@node Gnus Unplugged ++@section Gnus Unplugged ++@cindex offline ++@cindex unplugged ++@cindex agent ++@cindex Gnus agent ++@cindex Gnus unplugged ++ ++In olden times (ca. February '88), people used to run their newsreaders ++on big machines with permanent connections to the net. News transport ++was dealt with by news servers, and all the newsreaders had to do was to ++read news. Believe it or not. ++ ++Nowadays most people read news and mail at home, and use some sort of ++modem to connect to the net. To avoid running up huge phone bills, it ++would be nice to have a way to slurp down all the news and mail, hang up ++the phone, read for several hours, and then upload any responses you ++have to make. And then you repeat the procedure. ++ ++Of course, you can use news servers for doing this as well. I've used ++@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail} ++for some years, but doing that's a bore. Moving the news server ++functionality up to the newsreader makes sense if you're the only person ++reading news on a machine. ++ ++Setting up Gnus as an ``offline'' newsreader is quite simple. In ++fact, you don't have to configure anything as the agent is now enabled ++by default (@pxref{Agent Variables, gnus-agent}). ++ ++Of course, to use it as such, you have to learn a few new commands. ++ ++@menu ++* Agent Basics:: How it all is supposed to work. ++* Agent Categories:: How to tell the Gnus Agent what to download. ++* Agent Commands:: New commands for all the buffers. ++* Agent Visuals:: Ways that the agent may effect your summary buffer. ++* Agent as Cache:: The Agent is a big cache too. ++* Agent Expiry:: How to make old articles go away. ++* Agent Regeneration:: How to recover from lost connections and other accidents. ++* Agent and flags:: How the Agent maintains flags. ++* Agent and IMAP:: How to use the Agent with @acronym{IMAP}. ++* Outgoing Messages:: What happens when you post/mail something? ++* Agent Variables:: Customizing is fun. ++* Example Setup:: An example @file{~/.gnus.el} file for offline people. ++* Batching Agents:: How to fetch news from a @code{cron} job. ++* Agent Caveats:: What you think it'll do and what it does. ++@end menu ++ ++ ++@node Agent Basics ++@subsection Agent Basics ++ ++First, let's get some terminology out of the way. ++ ++The Gnus Agent is said to be @dfn{unplugged} when you have severed the ++connection to the net (and notified the Agent that this is the case). ++When the connection to the net is up again (and Gnus knows this), the ++Agent is @dfn{plugged}. ++ ++The @dfn{local} machine is the one you're running on, and which isn't ++connected to the net continuously. ++ ++@dfn{Downloading} means fetching things from the net to your local ++machine. @dfn{Uploading} is doing the opposite. ++ ++You know that Gnus gives you all the opportunity you'd ever want for ++shooting yourself in the foot. Some people call it flexibility. Gnus ++is also customizable to a great extent, which means that the user has a ++say on how Gnus behaves. Other newsreaders might unconditionally shoot ++you in your foot, but with Gnus, you have a choice! ++ ++Gnus is never really in plugged or unplugged state. Rather, it applies ++that state to each server individually. This means that some servers ++can be plugged while others can be unplugged. Additionally, some ++servers can be ignored by the Agent altogether (which means that ++they're kinda like plugged always). ++ ++So when you unplug the Agent and then wonder why is Gnus opening a ++connection to the Net, the next step to do is to look whether all ++servers are agentized. If there is an unagentized server, you found ++the culprit. ++ ++Another thing is the @dfn{offline} state. Sometimes, servers aren't ++reachable. When Gnus notices this, it asks you whether you want the ++server to be switched to offline state. If you say yes, then the ++server will behave somewhat as if it was unplugged, except that Gnus ++will ask you whether you want to switch it back online again. ++ ++Let's take a typical Gnus session using the Agent. ++ ++@itemize @bullet ++ ++@item ++@findex gnus-unplugged ++You start Gnus with @code{gnus-unplugged}. This brings up the Gnus ++Agent in a disconnected state. You can read all the news that you have ++already fetched while in this mode. ++ ++@item ++You then decide to see whether any new news has arrived. You connect ++your machine to the net (using PPP or whatever), and then hit @kbd{J j} ++to make Gnus become @dfn{plugged} and use @kbd{g} to check for new mail ++as usual. To check for new mail in unplugged mode (@pxref{Mail ++Source Specifiers}). ++ ++@item ++You can then read the new news immediately, or you can download the ++news onto your local machine. If you want to do the latter, you press ++@kbd{g} to check if there are any new news and then @kbd{J s} to fetch ++all the eligible articles in all the groups. (To let Gnus know which ++articles you want to download, @pxref{Agent Categories}). ++ ++@item ++After fetching the articles, you press @kbd{J j} to make Gnus become ++unplugged again, and you shut down the PPP thing (or whatever). And ++then you read the news offline. ++ ++@item ++And then you go to step 2. ++@end itemize ++ ++Here are some things you should do the first time (or so) that you use ++the Agent. ++ ++@itemize @bullet ++ ++@item ++Decide which servers should be covered by the Agent. If you have a mail ++back end, it would probably be nonsensical to have it covered by the ++Agent. Go to the server buffer (@kbd{^} in the group buffer) and press ++@kbd{J a} on the server (or servers) that you wish to have covered by the ++Agent (@pxref{Server Agent Commands}), or @kbd{J r} on automatically ++added servers you do not wish to have covered by the Agent. By default, ++all @code{nntp} and @code{nnimap} servers in @code{gnus-select-method} and ++@code{gnus-secondary-select-methods} are agentized. ++ ++@item ++Decide on download policy. It's fairly simple once you decide whether ++you are going to use agent categories, topic parameters, and/or group ++parameters to implement your policy. If you're new to gnus, it ++is probably best to start with a category, @xref{Agent Categories}. ++ ++Both topic parameters (@pxref{Topic Parameters}) and agent categories ++(@pxref{Agent Categories}) provide for setting a policy that applies ++to multiple groups. Which you use is entirely up to you. Topic ++parameters do override categories so, if you mix the two, you'll have ++to take that into account. If you have a few groups that deviate from ++your policy, you can use group parameters (@pxref{Group Parameters}) to ++configure them. ++ ++@item ++Uhm@dots{} that's it. ++@end itemize ++ ++ ++@node Agent Categories ++@subsection Agent Categories ++ ++One of the main reasons to integrate the news transport layer into the ++newsreader is to allow greater control over what articles to download. ++There's not much point in downloading huge amounts of articles, just to ++find out that you're not interested in reading any of them. It's better ++to be somewhat more conservative in choosing what to download, and then ++mark the articles for downloading manually if it should turn out that ++you're interested in the articles anyway. ++ ++One of the more effective methods for controlling what is to be ++downloaded is to create a @dfn{category} and then assign some (or all) ++groups to this category. Groups that do not belong in any other ++category belong to the @code{default} category. Gnus has its own ++buffer for creating and managing categories. ++ ++If you prefer, you can also use group parameters (@pxref{Group ++Parameters}) and topic parameters (@pxref{Topic Parameters}) for an ++alternative approach to controlling the agent. The only real ++difference is that categories are specific to the agent (so there is ++less to learn) while group and topic parameters include the kitchen ++sink. ++ ++Since you can set agent parameters in several different places we have ++a rule to decide which source to believe. This rule specifies that ++the parameter sources are checked in the following order: group ++parameters, topic parameters, agent category, and finally customizable ++variables. So you can mix all of these sources to produce a wide range ++of behavior, just don't blame me if you don't remember where you put ++your settings. ++ ++@menu ++* Category Syntax:: What a category looks like. ++* Category Buffer:: A buffer for maintaining categories. ++* Category Variables:: Customize'r'Us. ++@end menu ++ ++ ++@node Category Syntax ++@subsubsection Category Syntax ++ ++A category consists of a name, the list of groups belonging to the ++category, and a number of optional parameters that override the ++customizable variables. The complete list of agent parameters are ++listed below. ++ ++@cindex Agent Parameters ++@table @code ++@item agent-groups ++The list of groups that are in this category. ++ ++@item agent-predicate ++A predicate which (generally) gives a rough outline of which articles ++are eligible for downloading; and ++ ++@item agent-score ++a score rule which (generally) gives you a finer granularity when ++deciding what articles to download. (Note that this @dfn{download ++score} is not necessarily related to normal scores.) ++ ++@item agent-enable-expiration ++a boolean indicating whether the agent should expire old articles in ++this group. Most groups should be expired to conserve disk space. In ++fact, its probably safe to say that the gnus.* hierarchy contains the ++only groups that should not be expired. ++ ++@item agent-days-until-old ++an integer indicating the number of days that the agent should wait ++before deciding that a read article is safe to expire. ++ ++@item agent-low-score ++an integer that overrides the value of @code{gnus-agent-low-score}. ++ ++@item agent-high-score ++an integer that overrides the value of @code{gnus-agent-high-score}. ++ ++@item agent-short-article ++an integer that overrides the value of ++@code{gnus-agent-short-article}. ++ ++@item agent-long-article ++an integer that overrides the value of @code{gnus-agent-long-article}. ++ ++@item agent-enable-undownloaded-faces ++a symbol indicating whether the summary buffer should display ++undownloaded articles using the @code{gnus-summary-*-undownloaded-face} ++faces. Any symbol other than @code{nil} will enable the use of ++undownloaded faces. ++@end table ++ ++The name of a category can not be changed once the category has been ++created. ++ ++Each category maintains a list of groups that are exclusive members of ++that category. The exclusivity rule is automatically enforced, add a ++group to a new category and it is automatically removed from its old ++category. ++ ++A predicate in its simplest form can be a single predicate such as ++@code{true} or @code{false}. These two will download every available ++article or nothing respectively. In the case of these two special ++predicates an additional score rule is superfluous. ++ ++Predicates of @code{high} or @code{low} download articles in respect of ++their scores in relationship to @code{gnus-agent-high-score} and ++@code{gnus-agent-low-score} as described below. ++ ++To gain even finer control of what is to be regarded eligible for ++download a predicate can consist of a number of predicates with logical ++operators sprinkled in between. ++ ++Perhaps some examples are in order. ++ ++Here's a simple predicate. (It's the default predicate, in fact, used ++for all groups that don't belong to any other category.) ++ ++@lisp ++short ++@end lisp ++ ++Quite simple, eh? This predicate is true if and only if the article is ++short (for some value of ``short''). ++ ++Here's a more complex predicate: ++ ++@lisp ++(or high ++ (and ++ (not low) ++ (not long))) ++@end lisp ++ ++This means that an article should be downloaded if it has a high score, ++or if the score is not low and the article is not long. You get the ++drift. ++ ++The available logical operators are @code{or}, @code{and} and ++@code{not}. (If you prefer, you can use the more ``C''-ish operators ++@samp{|}, @code{&} and @code{!} instead.) ++ ++The following predicates are pre-defined, but if none of these fit what ++you want to do, you can write your own. ++ ++When evaluating each of these predicates, the named constant will be ++bound to the value determined by calling ++@code{gnus-agent-find-parameter} on the appropriate parameter. For ++example, gnus-agent-short-article will be bound to ++@code{(gnus-agent-find-parameter group 'agent-short-article)}. This ++means that you can specify a predicate in your category then tune that ++predicate to individual groups. ++ ++@table @code ++@item short ++True if the article is shorter than @code{gnus-agent-short-article} ++lines; default 100. ++ ++@item long ++True if the article is longer than @code{gnus-agent-long-article} ++lines; default 200. ++ ++@item low ++True if the article has a download score less than ++@code{gnus-agent-low-score}; default 0. ++ ++@item high ++True if the article has a download score greater than ++@code{gnus-agent-high-score}; default 0. ++ ++@item spam ++True if the Gnus Agent guesses that the article is spam. The ++heuristics may change over time, but at present it just computes a ++checksum and sees whether articles match. ++ ++@item true ++Always true. ++ ++@item false ++Always false. ++@end table ++ ++If you want to create your own predicate function, here's what you have ++to know: The functions are called with no parameters, but the ++@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to ++useful values. ++ ++For example, you could decide that you don't want to download articles ++that were posted more than a certain number of days ago (e.g. posted ++more than @code{gnus-agent-expire-days} ago) you might write a function ++something along the lines of the following: ++ ++@lisp ++(defun my-article-old-p () ++ "Say whether an article is old." ++ (< (time-to-days (date-to-time (mail-header-date gnus-headers))) ++ (- (time-to-days (current-time)) gnus-agent-expire-days))) ++@end lisp ++ ++with the predicate then defined as: ++ ++@lisp ++(not my-article-old-p) ++@end lisp ++ ++or you could append your predicate to the predefined ++@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or ++wherever. ++ ++@lisp ++(require 'gnus-agent) ++(setq gnus-category-predicate-alist ++ (append gnus-category-predicate-alist ++ '((old . my-article-old-p)))) ++@end lisp ++ ++and simply specify your predicate as: ++ ++@lisp ++(not old) ++@end lisp ++ ++If/when using something like the above, be aware that there are many ++misconfigured systems/mailers out there and so an article's date is not ++always a reliable indication of when it was posted. Hell, some people ++just don't give a damn. ++ ++The above predicates apply to @emph{all} the groups which belong to the ++category. However, if you wish to have a specific predicate for an ++individual group within a category, or you're just too lazy to set up a ++new category, you can enter a group's individual predicate in its group ++parameters like so: ++ ++@lisp ++(agent-predicate . short) ++@end lisp ++ ++This is the group/topic parameter equivalent of the agent category default. ++Note that when specifying a single word predicate like this, the ++@code{agent-predicate} specification must be in dotted pair notation. ++ ++The equivalent of the longer example from above would be: ++ ++@lisp ++(agent-predicate or high (and (not low) (not long))) ++@end lisp ++ ++The outer parenthesis required in the category specification are not ++entered here as, not being in dotted pair notation, the value of the ++predicate is assumed to be a list. ++ ++ ++Now, the syntax of the download score is the same as the syntax of ++normal score files, except that all elements that require actually ++seeing the article itself are verboten. This means that only the ++following headers can be scored on: @code{Subject}, @code{From}, ++@code{Date}, @code{Message-ID}, @code{References}, @code{Chars}, ++@code{Lines}, and @code{Xref}. ++ ++As with predicates, the specification of the @code{download score rule} ++to use in respect of a group can be in either the category definition if ++it's to be applicable to all groups in therein, or a group's parameters ++if it's to be specific to that group. ++ ++In both of these places the @code{download score rule} can take one of ++three forms: ++ ++@enumerate ++@item ++Score rule ++ ++This has the same syntax as a normal Gnus score file except only a ++subset of scoring keywords are available as mentioned above. ++ ++example: ++ ++@itemize @bullet ++@item ++Category specification ++ ++@lisp ++(("from" ++ ("Lars Ingebrigtsen" 1000000 nil s)) ++("lines" ++ (500 -100 nil <))) ++@end lisp ++ ++@item ++Group/Topic Parameter specification ++ ++@lisp ++(agent-score ("from" ++ ("Lars Ingebrigtsen" 1000000 nil s)) ++ ("lines" ++ (500 -100 nil <))) ++@end lisp ++ ++Again, note the omission of the outermost parenthesis here. ++@end itemize ++ ++@item ++Agent score file ++ ++These score files must @emph{only} contain the permitted scoring ++keywords stated above. ++ ++example: ++ ++@itemize @bullet ++@item ++Category specification ++ ++@lisp ++("~/News/agent.SCORE") ++@end lisp ++ ++or perhaps ++ ++@lisp ++("~/News/agent.SCORE" "~/News/agent.group.SCORE") ++@end lisp ++ ++@item ++Group Parameter specification ++ ++@lisp ++(agent-score "~/News/agent.SCORE") ++@end lisp ++ ++Additional score files can be specified as above. Need I say anything ++about parenthesis? ++@end itemize ++ ++@item ++Use @code{normal} score files ++ ++If you don't want to maintain two sets of scoring rules for a group, and ++your desired @code{downloading} criteria for a group are the same as your ++@code{reading} criteria then you can tell the agent to refer to your ++@code{normal} score files when deciding what to download. ++ ++These directives in either the category definition or a group's ++parameters will cause the agent to read in all the applicable score ++files for a group, @emph{filtering out} those sections that do not ++relate to one of the permitted subset of scoring keywords. ++ ++@itemize @bullet ++@item ++Category Specification ++ ++@lisp ++file ++@end lisp ++ ++@item ++Group Parameter specification ++ ++@lisp ++(agent-score . file) ++@end lisp ++@end itemize ++@end enumerate ++ ++@node Category Buffer ++@subsubsection Category Buffer ++ ++You'd normally do all category maintenance from the category buffer. ++When you enter it for the first time (with the @kbd{J c} command from ++the group buffer), you'll only see the @code{default} category. ++ ++The following commands are available in this buffer: ++ ++@table @kbd ++@item q ++@kindex q (Category) ++@findex gnus-category-exit ++Return to the group buffer (@code{gnus-category-exit}). ++ ++@item e ++@kindex e (Category) ++@findex gnus-category-customize-category ++Use a customization buffer to set all of the selected category's ++parameters at one time (@code{gnus-category-customize-category}). ++ ++@item k ++@kindex k (Category) ++@findex gnus-category-kill ++Kill the current category (@code{gnus-category-kill}). ++ ++@item c ++@kindex c (Category) ++@findex gnus-category-copy ++Copy the current category (@code{gnus-category-copy}). ++ ++@item a ++@kindex a (Category) ++@findex gnus-category-add ++Add a new category (@code{gnus-category-add}). ++ ++@item p ++@kindex p (Category) ++@findex gnus-category-edit-predicate ++Edit the predicate of the current category ++(@code{gnus-category-edit-predicate}). ++ ++@item g ++@kindex g (Category) ++@findex gnus-category-edit-groups ++Edit the list of groups belonging to the current category ++(@code{gnus-category-edit-groups}). ++ ++@item s ++@kindex s (Category) ++@findex gnus-category-edit-score ++Edit the download score rule of the current category ++(@code{gnus-category-edit-score}). ++ ++@item l ++@kindex l (Category) ++@findex gnus-category-list ++List all the categories (@code{gnus-category-list}). ++@end table ++ ++ ++@node Category Variables ++@subsubsection Category Variables ++ ++@table @code ++@item gnus-category-mode-hook ++@vindex gnus-category-mode-hook ++Hook run in category buffers. ++ ++@item gnus-category-line-format ++@vindex gnus-category-line-format ++Format of the lines in the category buffer (@pxref{Formatting ++Variables}). Valid elements are: ++ ++@table @samp ++@item c ++The name of the category. ++ ++@item g ++The number of groups in the category. ++@end table ++ ++@item gnus-category-mode-line-format ++@vindex gnus-category-mode-line-format ++Format of the category mode line (@pxref{Mode Line Formatting}). ++ ++@item gnus-agent-short-article ++@vindex gnus-agent-short-article ++Articles that have fewer lines than this are short. Default 100. ++ ++@item gnus-agent-long-article ++@vindex gnus-agent-long-article ++Articles that have more lines than this are long. Default 200. ++ ++@item gnus-agent-low-score ++@vindex gnus-agent-low-score ++Articles that have a score lower than this have a low score. Default ++0. ++ ++@item gnus-agent-high-score ++@vindex gnus-agent-high-score ++Articles that have a score higher than this have a high score. Default ++0. ++ ++@item gnus-agent-expire-days ++@vindex gnus-agent-expire-days ++The number of days that a @samp{read} article must stay in the agent's ++local disk before becoming eligible for expiration (While the name is ++the same, this doesn't mean expiring the article on the server. It ++just means deleting the local copy of the article). What is also ++important to understand is that the counter starts with the time the ++article was written to the local disk and not the time the article was ++read. ++Default 7. ++ ++@item gnus-agent-enable-expiration ++@vindex gnus-agent-enable-expiration ++Determines whether articles in a group are, by default, expired or ++retained indefinitely. The default is @code{ENABLE} which means that ++you'll have to disable expiration when desired. On the other hand, ++you could set this to @code{DISABLE}. In that case, you would then ++have to enable expiration in selected groups. ++ ++@end table ++ ++ ++@node Agent Commands ++@subsection Agent Commands ++@findex gnus-agent-toggle-plugged ++@kindex J j (Agent) ++ ++All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j} ++(@code{gnus-agent-toggle-plugged}) command works in all modes, and ++toggles the plugged/unplugged state of the Gnus Agent. ++ ++ ++@menu ++* Group Agent Commands:: Configure groups and fetch their contents. ++* Summary Agent Commands:: Manually select then fetch specific articles. ++* Server Agent Commands:: Select the servers that are supported by the agent. ++@end menu ++ ++ ++ ++ ++@node Group Agent Commands ++@subsubsection Group Agent Commands ++ ++@table @kbd ++@item J u ++@kindex J u (Agent Group) ++@findex gnus-agent-fetch-groups ++Fetch all eligible articles in the current group ++(@code{gnus-agent-fetch-groups}). ++ ++@item J c ++@kindex J c (Agent Group) ++@findex gnus-enter-category-buffer ++Enter the Agent category buffer (@code{gnus-enter-category-buffer}). ++ ++@item J s ++@kindex J s (Agent Group) ++@findex gnus-agent-fetch-session ++Fetch all eligible articles in all groups ++(@code{gnus-agent-fetch-session}). ++ ++@item J S ++@kindex J S (Agent Group) ++@findex gnus-group-send-queue ++Send all sendable messages in the queue group ++(@code{gnus-group-send-queue}). @xref{Drafts}. ++ ++@item J a ++@kindex J a (Agent Group) ++@findex gnus-agent-add-group ++Add the current group to an Agent category ++(@code{gnus-agent-add-group}). This command understands the ++process/prefix convention (@pxref{Process/Prefix}). ++ ++@item J r ++@kindex J r (Agent Group) ++@findex gnus-agent-remove-group ++Remove the current group from its category, if any ++(@code{gnus-agent-remove-group}). This command understands the ++process/prefix convention (@pxref{Process/Prefix}). ++ ++@item J Y ++@kindex J Y (Agent Group) ++@findex gnus-agent-synchronize-flags ++Synchronize flags changed while unplugged with remote server, if any. ++ ++ ++@end table ++ ++ ++@node Summary Agent Commands ++@subsubsection Summary Agent Commands ++ ++@table @kbd ++@item J # ++@kindex J # (Agent Summary) ++@findex gnus-agent-mark-article ++Mark the article for downloading (@code{gnus-agent-mark-article}). ++ ++@item J M-# ++@kindex J M-# (Agent Summary) ++@findex gnus-agent-unmark-article ++Remove the downloading mark from the article ++(@code{gnus-agent-unmark-article}). ++ ++@cindex % ++@item @@ ++@kindex @@ (Agent Summary) ++@findex gnus-agent-toggle-mark ++Toggle whether to download the article ++(@code{gnus-agent-toggle-mark}). The download mark is @samp{%} by ++default. ++ ++@item J c ++@kindex J c (Agent Summary) ++@findex gnus-agent-catchup ++Mark all articles as read (@code{gnus-agent-catchup}) that are neither cached, downloaded, nor downloadable. ++ ++@item J S ++@kindex J S (Agent Summary) ++@findex gnus-agent-fetch-group ++Download all eligible (@pxref{Agent Categories}) articles in this group. ++(@code{gnus-agent-fetch-group}). ++ ++@item J s ++@kindex J s (Agent Summary) ++@findex gnus-agent-summary-fetch-series ++Download all processable articles in this group. ++(@code{gnus-agent-summary-fetch-series}). ++ ++@item J u ++@kindex J u (Agent Summary) ++@findex gnus-agent-summary-fetch-group ++Download all downloadable articles in the current group ++(@code{gnus-agent-summary-fetch-group}). ++ ++@end table ++ ++ ++@node Server Agent Commands ++@subsubsection Server Agent Commands ++ ++@table @kbd ++@item J a ++@kindex J a (Agent Server) ++@findex gnus-agent-add-server ++Add the current server to the list of servers covered by the Gnus Agent ++(@code{gnus-agent-add-server}). ++ ++@item J r ++@kindex J r (Agent Server) ++@findex gnus-agent-remove-server ++Remove the current server from the list of servers covered by the Gnus ++Agent (@code{gnus-agent-remove-server}). ++ ++@end table ++ ++ ++@node Agent Visuals ++@subsection Agent Visuals ++ ++If you open a summary while unplugged and, Gnus knows from the group's ++active range that there are more articles than the headers currently ++stored in the Agent, you may see some articles whose subject looks ++something like @samp{[Undownloaded article #####]}. These are ++placeholders for the missing headers. Aside from setting a mark, ++there is not much that can be done with one of these placeholders. ++When Gnus finally gets a chance to fetch the group's headers, the ++placeholders will automatically be replaced by the actual headers. ++You can configure the summary buffer's maneuvering to skip over the ++placeholders if you care (See @code{gnus-auto-goto-ignores}). ++ ++While it may be obvious to all, the only headers and articles ++available while unplugged are those headers and articles that were ++fetched into the Agent while previously plugged. To put it another ++way, ``If you forget to fetch something while plugged, you might have a ++less than satisfying unplugged session''. For this reason, the Agent ++adds two visual effects to your summary buffer. These effects display ++the download status of each article so that you always know which ++articles will be available when unplugged. ++ ++The first visual effect is the @samp{%O} spec. If you customize ++@code{gnus-summary-line-format} to include this specifier, you will add ++a single character field that indicates an article's download status. ++Articles that have been fetched into either the Agent or the Cache, ++will display @code{gnus-downloaded-mark} (defaults to @samp{+}). All ++other articles will display @code{gnus-undownloaded-mark} (defaults to ++@samp{-}). If you open a group that has not been agentized, a space ++(@samp{ }) will be displayed. ++ ++The second visual effect are the undownloaded faces. The faces, there ++are three indicating the article's score (low, normal, high), seem to ++result in a love/hate response from many Gnus users. The problem is ++that the face selection is controlled by a list of condition tests and ++face names (See @code{gnus-summary-highlight}). Each condition is ++tested in the order in which it appears in the list so early ++conditions have precedence over later conditions. All of this means ++that, if you tick an undownloaded article, the article will continue ++to be displayed in the undownloaded face rather than the ticked face. ++ ++If you use the Agent as a cache (to avoid downloading the same article ++each time you visit it or to minimize your connection time), the ++undownloaded face will probably seem like a good idea. The reason ++being that you do all of our work (marking, reading, deleting) with ++downloaded articles so the normal faces always appear. For those ++users using the agent to improve online performance by caching the NOV ++database (most users since 5.10.2), the undownloaded faces may appear ++to be an absolutely horrible idea. The issue being that, since none ++of their articles have been fetched into the Agent, all of the ++normal faces will be obscured by the undownloaded faces. ++ ++If you would like to use the undownloaded faces, you must enable the ++undownloaded faces by setting the @code{agent-enable-undownloaded-faces} ++group parameter to @code{t}. This parameter, like all other agent ++parameters, may be set on an Agent Category (@pxref{Agent Categories}), ++a Group Topic (@pxref{Topic Parameters}), or an individual group ++(@pxref{Group Parameters}). ++ ++The one problem common to all users using the agent is how quickly it ++can consume disk space. If you using the agent on many groups, it is ++even more difficult to effectively recover disk space. One solution ++is the @samp{%F} format available in @code{gnus-group-line-format}. ++This format will display the actual disk space used by articles ++fetched into both the agent and cache. By knowing which groups use ++the most space, users know where to focus their efforts when ``agent ++expiring'' articles. ++ ++@node Agent as Cache ++@subsection Agent as Cache ++ ++When Gnus is plugged, it is not efficient to download headers or ++articles from the server again, if they are already stored in the ++Agent. So, Gnus normally only downloads headers once, and stores them ++in the Agent. These headers are later used when generating the summary ++buffer, regardless of whether you are plugged or unplugged. Articles ++are not cached in the Agent by default though (that would potentially ++consume lots of disk space), but if you have already downloaded an ++article into the Agent, Gnus will not download the article from the ++server again but use the locally stored copy instead. ++ ++If you so desire, you can configure the agent (see @code{gnus-agent-cache} ++@pxref{Agent Variables}) to always download headers and articles while ++plugged. Gnus will almost certainly be slower, but it will be kept ++synchronized with the server. That last point probably won't make any ++sense if you are using a nntp or nnimap back end. ++ ++@node Agent Expiry ++@subsection Agent Expiry ++ ++@vindex gnus-agent-expire-days ++@findex gnus-agent-expire ++@kindex M-x gnus-agent-expire ++@kindex M-x gnus-agent-expire-group ++@findex gnus-agent-expire-group ++@cindex agent expiry ++@cindex Gnus agent expiry ++@cindex expiry, in Gnus agent ++ ++The Agent back end, @code{nnagent}, doesn't handle expiry. Well, at ++least it doesn't handle it like other back ends. Instead, there are ++special @code{gnus-agent-expire} and @code{gnus-agent-expire-group} ++commands that will expire all read articles that are older than ++@code{gnus-agent-expire-days} days. They can be run whenever you feel ++that you're running out of space. Neither are particularly fast or ++efficient, and it's not a particularly good idea to interrupt them (with ++@kbd{C-g} or anything else) once you've started one of them. ++ ++Note that other functions, e.g. @code{gnus-request-expire-articles}, ++might run @code{gnus-agent-expire} for you to keep the agent ++synchronized with the group. ++ ++The agent parameter @code{agent-enable-expiration} may be used to ++prevent expiration in selected groups. ++ ++@vindex gnus-agent-expire-all ++If @code{gnus-agent-expire-all} is non-@code{nil}, the agent ++expiration commands will expire all articles---unread, read, ticked ++and dormant. If @code{nil} (which is the default), only read articles ++are eligible for expiry, and unread, ticked and dormant articles will ++be kept indefinitely. ++ ++If you find that some articles eligible for expiry are never expired, ++perhaps some Gnus Agent files are corrupted. There's are special ++commands, @code{gnus-agent-regenerate} and ++@code{gnus-agent-regenerate-group}, to fix possible problems. ++ ++@node Agent Regeneration ++@subsection Agent Regeneration ++ ++@cindex agent regeneration ++@cindex Gnus agent regeneration ++@cindex regeneration ++ ++The local data structures used by @code{nnagent} may become corrupted ++due to certain exceptional conditions. When this happens, ++@code{nnagent} functionality may degrade or even fail. The solution ++to this problem is to repair the local data structures by removing all ++internal inconsistencies. ++ ++For example, if your connection to your server is lost while ++downloaded articles into the agent, the local data structures will not ++know about articles successfully downloaded prior to the connection ++failure. Running @code{gnus-agent-regenerate} or ++@code{gnus-agent-regenerate-group} will update the data structures ++such that you don't need to download these articles a second time. ++ ++@findex gnus-agent-regenerate ++@kindex M-x gnus-agent-regenerate ++The command @code{gnus-agent-regenerate} will perform ++@code{gnus-agent-regenerate-group} on every agentized group. While ++you can run @code{gnus-agent-regenerate} in any buffer, it is strongly ++recommended that you first close all summary buffers. ++ ++@findex gnus-agent-regenerate-group ++@kindex M-x gnus-agent-regenerate-group ++The command @code{gnus-agent-regenerate-group} uses the local copies ++of individual articles to repair the local @acronym{NOV}(header) database. It ++then updates the internal data structures that document which articles ++are stored locally. An optional argument will mark articles in the ++agent as unread. ++ ++@node Agent and flags ++@subsection Agent and flags ++ ++The Agent works with any Gnus back end including those, such as ++nnimap, that store flags (read, ticked, etc) on the server. Sadly, ++the Agent does not actually know which backends keep their flags in ++the backend server rather than in @file{.newsrc}. This means that the ++Agent, while unplugged or disconnected, will always record all changes ++to the flags in its own files. ++ ++When you plug back in, Gnus will then check to see if you have any ++changed any flags and ask if you wish to synchronize these with the ++server. This behavior is customizable by @code{gnus-agent-synchronize-flags}. ++ ++@vindex gnus-agent-synchronize-flags ++If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will ++never automatically synchronize flags. If it is @code{ask}, which is ++the default, the Agent will check if you made any changes and if so ++ask if you wish to synchronize these when you re-connect. If it has ++any other value, all flags will be synchronized automatically. ++ ++If you do not wish to synchronize flags automatically when you ++re-connect, you can do it manually with the ++@code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y} ++in the group buffer. ++ ++Technical note: the synchronization algorithm does not work by ``pushing'' ++all local flags to the server, but rather by incrementally updated the ++server view of flags by changing only those flags that were changed by ++the user. Thus, if you set one flag on an article, quit the group then ++re-select the group and remove the flag; the flag will be set and ++removed from the server when you ``synchronize''. The queued flag ++operations can be found in the per-server @code{flags} file in the Agent ++directory. It's emptied when you synchronize flags. ++ ++@node Agent and IMAP ++@subsection Agent and IMAP ++ ++The Agent works with any Gnus back end, including nnimap. However, ++since there are some conceptual differences between @acronym{NNTP} and ++@acronym{IMAP}, this section (should) provide you with some information to ++make Gnus Agent work smoother as a @acronym{IMAP} Disconnected Mode client. ++ ++Some things are currently not implemented in the Agent that you'd might ++expect from a disconnected @acronym{IMAP} client, including: ++ ++@itemize @bullet ++ ++@item ++Copying/moving articles into nnimap groups when unplugged. ++ ++@item ++Creating/deleting nnimap groups when unplugged. ++ ++@end itemize ++ ++@node Outgoing Messages ++@subsection Outgoing Messages ++ ++By default, when Gnus is unplugged, all outgoing messages (both mail ++and news) are stored in the draft group ``queue'' (@pxref{Drafts}). ++You can view them there after posting, and edit them at will. ++ ++You can control the circumstances under which outgoing mail is queued ++(see @code{gnus-agent-queue-mail}, @pxref{Agent Variables}). Outgoing ++news is always queued when Gnus is unplugged, and never otherwise. ++ ++You can send the messages either from the draft group with the special ++commands available there, or you can use the @kbd{J S} command in the ++group buffer to send all the sendable messages in the draft group. ++Posting news will only work when Gnus is plugged, but you can send ++mail at any time. ++ ++If sending mail while unplugged does not work for you and you worry ++about hitting @kbd{J S} by accident when unplugged, you can have Gnus ++ask you to confirm your action (see ++@code{gnus-agent-prompt-send-queue}, @pxref{Agent Variables}). ++ ++@node Agent Variables ++@subsection Agent Variables ++ ++@table @code ++@item gnus-agent ++@vindex gnus-agent ++Is the agent enabled? The default is @code{t}. When first enabled, ++the agent will use @code{gnus-agent-auto-agentize-methods} to ++automatically mark some back ends as agentized. You may change which ++back ends are agentized using the agent commands in the server buffer. ++ ++To enter the server buffer, use the @kbd{^} ++(@code{gnus-group-enter-server-mode}) command in the group buffer. ++ ++ ++@item gnus-agent-directory ++@vindex gnus-agent-directory ++Where the Gnus Agent will store its files. The default is ++@file{~/News/agent/}. ++ ++@item gnus-agent-handle-level ++@vindex gnus-agent-handle-level ++Groups on levels (@pxref{Group Levels}) higher than this variable will ++be ignored by the Agent. The default is @code{gnus-level-subscribed}, ++which means that only subscribed group will be considered by the Agent ++by default. ++ ++@item gnus-agent-plugged-hook ++@vindex gnus-agent-plugged-hook ++Hook run when connecting to the network. ++ ++@item gnus-agent-unplugged-hook ++@vindex gnus-agent-unplugged-hook ++Hook run when disconnecting from the network. ++ ++@item gnus-agent-fetched-hook ++@vindex gnus-agent-fetched-hook ++Hook run when finished fetching articles. ++ ++@item gnus-agent-cache ++@vindex gnus-agent-cache ++Variable to control whether use the locally stored @acronym{NOV} and ++articles when plugged, e.g. essentially using the Agent as a cache. ++The default is non-@code{nil}, which means to use the Agent as a cache. ++ ++@item gnus-agent-go-online ++@vindex gnus-agent-go-online ++If @code{gnus-agent-go-online} is @code{nil}, the Agent will never ++automatically switch offline servers into online status. If it is ++@code{ask}, the default, the Agent will ask if you wish to switch ++offline servers into online status when you re-connect. If it has any ++other value, all offline servers will be automatically switched into ++online status. ++ ++@item gnus-agent-mark-unread-after-downloaded ++@vindex gnus-agent-mark-unread-after-downloaded ++If @code{gnus-agent-mark-unread-after-downloaded} is non-@code{nil}, ++mark articles as unread after downloading. This is usually a safe ++thing to do as the newly downloaded article has obviously not been ++read. The default is @code{t}. ++ ++@item gnus-agent-synchronize-flags ++@vindex gnus-agent-synchronize-flags ++If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will ++never automatically synchronize flags. If it is @code{ask}, which is ++the default, the Agent will check if you made any changes and if so ++ask if you wish to synchronize these when you re-connect. If it has ++any other value, all flags will be synchronized automatically. ++ ++@item gnus-agent-consider-all-articles ++@vindex gnus-agent-consider-all-articles ++If @code{gnus-agent-consider-all-articles} is non-@code{nil}, the ++agent will let the agent predicate decide whether articles need to be ++downloaded or not, for all articles. When @code{nil}, the default, ++the agent will only let the predicate decide whether unread articles ++are downloaded or not. If you enable this, you may also want to look ++into the agent expiry settings (@pxref{Category Variables}), so that ++the agent doesn't download articles which the agent will later expire, ++over and over again. ++ ++@item gnus-agent-max-fetch-size ++@vindex gnus-agent-max-fetch-size ++The agent fetches articles into a temporary buffer prior to parsing ++them into individual files. To avoid exceeding the max. buffer size, ++the agent alternates between fetching and parsing until all articles ++have been fetched. @code{gnus-agent-max-fetch-size} provides a size ++limit to control how often the cycling occurs. A large value improves ++performance. A small value minimizes the time lost should the ++connection be lost while fetching (You may need to run ++@code{gnus-agent-regenerate-group} to update the group's state. ++However, all articles parsed prior to loosing the connection will be ++available while unplugged). The default is 10M so it is unusual to ++see any cycling. ++ ++@item gnus-server-unopen-status ++@vindex gnus-server-unopen-status ++Perhaps not an Agent variable, but closely related to the Agent, this ++variable says what will happen if Gnus cannot open a server. If the ++Agent is enabled, the default, @code{nil}, makes Gnus ask the user ++whether to deny the server or whether to unplug the agent. If the ++Agent is disabled, Gnus always simply deny the server. Other choices ++for this variable include @code{denied} and @code{offline} the latter ++is only valid if the Agent is used. ++ ++@item gnus-auto-goto-ignores ++@vindex gnus-auto-goto-ignores ++Another variable that isn't an Agent variable, yet so closely related ++that most will look for it here, this variable tells the summary ++buffer how to maneuver around undownloaded (only headers stored in the ++agent) and unfetched (neither article nor headers stored) articles. ++ ++The valid values are @code{nil} (maneuver to any article), ++@code{undownloaded} (maneuvering while unplugged ignores articles that ++have not been fetched), @code{always-undownloaded} (maneuvering always ++ignores articles that have not been fetched), @code{unfetched} ++(maneuvering ignores articles whose headers have not been fetched). ++ ++@item gnus-agent-queue-mail ++@vindex gnus-agent-queue-mail ++When @code{gnus-agent-queue-mail} is @code{always}, Gnus will always ++queue mail rather than sending it straight away. When @code{t}, Gnus ++will queue mail when unplugged only. When @code{nil}, never queue ++mail. The default is @code{t}. ++ ++@item gnus-agent-prompt-send-queue ++@vindex gnus-agent-prompt-send-queue ++When @code{gnus-agent-prompt-send-queue} is non-@code{nil} Gnus will ++prompt you to confirm that you really wish to proceed if you hit ++@kbd{J S} while unplugged. The default is @code{nil}. ++ ++@item gnus-agent-auto-agentize-methods ++@vindex gnus-agent-auto-agentize-methods ++If you have never used the Agent before (or more technically, if ++@file{~/News/agent/lib/servers} does not exist), Gnus will ++automatically agentize a few servers for you. This variable control ++which back ends should be auto-agentized. It is typically only useful ++to agentize remote back ends. The auto-agentizing has the same effect ++as running @kbd{J a} on the servers (@pxref{Server Agent Commands}). ++If the file exist, you must manage the servers manually by adding or ++removing them, this variable is only applicable the first time you ++start Gnus. The default is @samp{(nntp nnimap)}. ++ ++@end table ++ ++ ++@node Example Setup ++@subsection Example Setup ++ ++If you don't want to read this manual, and you have a fairly standard ++setup, you may be able to use something like the following as your ++@file{~/.gnus.el} file to get started. ++ ++@lisp ++;; @r{Define how Gnus is to fetch news. We do this over @acronym{NNTP}} ++;; @r{from your ISP's server.} ++(setq gnus-select-method '(nntp "news.your-isp.com")) ++ ++;; @r{Define how Gnus is to read your mail. We read mail from} ++;; @r{your ISP's @acronym{POP} server.} ++(setq mail-sources '((pop :server "pop.your-isp.com"))) ++ ++;; @r{Say how Gnus is to store the mail. We use nnml groups.} ++(setq gnus-secondary-select-methods '((nnml ""))) ++ ++;; @r{Make Gnus into an offline newsreader.} ++;; (gnus-agentize) ; @r{The obsolete setting.} ++;; (setq gnus-agent t) ; @r{Now the default.} ++@end lisp ++ ++That should be it, basically. Put that in your @file{~/.gnus.el} file, ++edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x ++gnus}. ++ ++If this is the first time you've run Gnus, you will be subscribed ++automatically to a few default newsgroups. You'll probably want to ++subscribe to more groups, and to do that, you have to query the ++@acronym{NNTP} server for a complete list of groups with the @kbd{A A} ++command. This usually takes quite a while, but you only have to do it ++once. ++ ++After reading and parsing a while, you'll be presented with a list of ++groups. Subscribe to the ones you want to read with the @kbd{u} ++command. @kbd{l} to make all the killed groups disappear after you've ++subscribe to all the groups you want to read. (@kbd{A k} will bring ++back all the killed groups.) ++ ++You can now read the groups at once, or you can download the articles ++with the @kbd{J s} command. And then read the rest of this manual to ++find out which of the other gazillion things you want to customize. ++ ++ ++@node Batching Agents ++@subsection Batching Agents ++@findex gnus-agent-batch ++ ++Having the Gnus Agent fetch articles (and post whatever messages you've ++written) is quite easy once you've gotten things set up properly. The ++following shell script will do everything that is necessary: ++ ++You can run a complete batch command from the command line with the ++following incantation: ++ ++@example ++#!/bin/sh ++emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-agent-batch >/dev/null 2>&1 ++@end example ++ ++ ++@node Agent Caveats ++@subsection Agent Caveats ++ ++The Gnus Agent doesn't seem to work like most other offline ++newsreaders. Here are some common questions that some imaginary people ++may ask: ++ ++@table @dfn ++@item If I read an article while plugged, do they get entered into the Agent? ++ ++@strong{No}. If you want this behavior, add ++@code{gnus-agent-fetch-selected-article} to ++@code{gnus-select-article-hook}. ++ ++@item If I read an article while plugged, and the article already exists in ++the Agent, will it get downloaded once more? ++ ++@strong{No}, unless @code{gnus-agent-cache} is @code{nil}. ++ ++@end table ++ ++In short, when Gnus is unplugged, it only looks into the locally stored ++articles; when it's plugged, it talks to your ISP and may also use the ++locally stored articles. ++ ++ ++@node Scoring ++@chapter Scoring ++@cindex scoring ++ ++Other people use @dfn{kill files}, but we here at Gnus Towers like ++scoring better than killing, so we'd rather switch than fight. They do ++something completely different as well, so sit up straight and pay ++attention! ++ ++@vindex gnus-summary-mark-below ++All articles have a default score (@code{gnus-summary-default-score}), ++which is 0 by default. This score may be raised or lowered either ++interactively or by score files. Articles that have a score lower than ++@code{gnus-summary-mark-below} are marked as read. ++ ++Gnus will read any @dfn{score files} that apply to the current group ++before generating the summary buffer. ++ ++There are several commands in the summary buffer that insert score ++entries based on the current article. You can, for instance, ask Gnus to ++lower or increase the score of all articles with a certain subject. ++ ++There are two sorts of scoring entries: Permanent and temporary. ++Temporary score entries are self-expiring entries. Any entries that are ++temporary and have not been used for, say, a week, will be removed ++silently to help keep the sizes of the score files down. ++ ++@menu ++* Summary Score Commands:: Adding score entries for the current group. ++* Group Score Commands:: General score commands. ++* Score Variables:: Customize your scoring. (My, what terminology). ++* Score File Format:: What a score file may contain. ++* Score File Editing:: You can edit score files by hand as well. ++* Adaptive Scoring:: Big Sister Gnus knows what you read. ++* Home Score File:: How to say where new score entries are to go. ++* Followups To Yourself:: Having Gnus notice when people answer you. ++* Scoring On Other Headers:: Scoring on non-standard headers. ++* Scoring Tips:: How to score effectively. ++* Reverse Scoring:: That problem child of old is not problem. ++* Global Score Files:: Earth-spanning, ear-splitting score files. ++* Kill Files:: They are still here, but they can be ignored. ++* Converting Kill Files:: Translating kill files to score files. ++* Advanced Scoring:: Using logical expressions to build score rules. ++* Score Decays:: It can be useful to let scores wither away. ++@end menu ++ ++ ++@node Summary Score Commands ++@section Summary Score Commands ++@cindex score commands ++ ++The score commands that alter score entries do not actually modify real ++score files. That would be too inefficient. Gnus maintains a cache of ++previously loaded score files, one of which is considered the ++@dfn{current score file alist}. The score commands simply insert ++entries into this list, and upon group exit, this list is saved. ++ ++The current score file is by default the group's local score file, even ++if no such score file actually exists. To insert score commands into ++some other score file (e.g. @file{all.SCORE}), you must first make this ++score file the current one. ++ ++General score commands that don't actually change the score file: ++ ++@table @kbd ++ ++@item V s ++@kindex V s (Summary) ++@findex gnus-summary-set-score ++Set the score of the current article (@code{gnus-summary-set-score}). ++ ++@item V S ++@kindex V S (Summary) ++@findex gnus-summary-current-score ++Display the score of the current article ++(@code{gnus-summary-current-score}). ++ ++@item V t ++@kindex V t (Summary) ++@findex gnus-score-find-trace ++Display all score rules that have been used on the current article ++(@code{gnus-score-find-trace}). In the @code{*Score Trace*} buffer, you ++may type @kbd{e} to edit score file corresponding to the score rule on ++current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the ++score file and edit it. ++ ++@item V w ++@kindex V w (Summary) ++@findex gnus-score-find-favourite-words ++List words used in scoring (@code{gnus-score-find-favourite-words}). ++ ++@item V R ++@kindex V R (Summary) ++@findex gnus-summary-rescore ++Run the current summary through the scoring process ++(@code{gnus-summary-rescore}). This might be useful if you're playing ++around with your score files behind Gnus' back and want to see the ++effect you're having. ++ ++@item V c ++@kindex V c (Summary) ++@findex gnus-score-change-score-file ++Make a different score file the current ++(@code{gnus-score-change-score-file}). ++ ++@item V e ++@kindex V e (Summary) ++@findex gnus-score-edit-current-scores ++Edit the current score file (@code{gnus-score-edit-current-scores}). ++You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score ++File Editing}). ++ ++@item V f ++@kindex V f (Summary) ++@findex gnus-score-edit-file ++Edit a score file and make this score file the current one ++(@code{gnus-score-edit-file}). ++ ++@item V F ++@kindex V F (Summary) ++@findex gnus-score-flush-cache ++Flush the score cache (@code{gnus-score-flush-cache}). This is useful ++after editing score files. ++ ++@item V C ++@kindex V C (Summary) ++@findex gnus-score-customize ++Customize a score file in a visually pleasing manner ++(@code{gnus-score-customize}). ++ ++@end table ++ ++The rest of these commands modify the local score file. ++ ++@table @kbd ++ ++@item V m ++@kindex V m (Summary) ++@findex gnus-score-set-mark-below ++Prompt for a score, and mark all articles with a score below this as ++read (@code{gnus-score-set-mark-below}). ++ ++@item V x ++@kindex V x (Summary) ++@findex gnus-score-set-expunge-below ++Prompt for a score, and add a score rule to the current score file to ++expunge all articles below this score ++(@code{gnus-score-set-expunge-below}). ++@end table ++ ++The keystrokes for actually making score entries follow a very regular ++pattern, so there's no need to list all the commands. (Hundreds of ++them.) ++ ++@findex gnus-summary-increase-score ++@findex gnus-summary-lower-score ++ ++@enumerate ++@item ++The first key is either @kbd{I} (upper case i) for increasing the score ++or @kbd{L} for lowering the score. ++@item ++The second key says what header you want to score on. The following ++keys are available: ++@table @kbd ++ ++@item a ++Score on the author name. ++ ++@item s ++Score on the subject line. ++ ++@item x ++Score on the @code{Xref} line---i.e., the cross-posting line. ++ ++@item r ++Score on the @code{References} line. ++ ++@item d ++Score on the date. ++ ++@item l ++Score on the number of lines. ++ ++@item i ++Score on the @code{Message-ID} header. ++ ++@item e ++Score on an ``extra'' header, that is, one of those in gnus-extra-headers, ++if your @acronym{NNTP} server tracks additional header data in overviews. ++ ++@item f ++Score on followups---this matches the author name, and adds scores to ++the followups to this author. (Using this key leads to the creation of ++@file{ADAPT} files.) ++ ++@item b ++Score on the body. ++ ++@item h ++Score on the head. ++ ++@item t ++Score on thread. (Using this key leads to the creation of @file{ADAPT} ++files.) ++ ++@end table ++ ++@item ++The third key is the match type. Which match types are valid depends on ++what headers you are scoring on. ++ ++@table @code ++ ++@item strings ++ ++@table @kbd ++ ++@item e ++Exact matching. ++ ++@item s ++Substring matching. ++ ++@item f ++Fuzzy matching (@pxref{Fuzzy Matching}). ++ ++@item r ++Regexp matching ++@end table ++ ++@item date ++@table @kbd ++ ++@item b ++Before date. ++ ++@item a ++After date. ++ ++@item n ++This date. ++@end table ++ ++@item number ++@table @kbd ++ ++@item < ++Less than number. ++ ++@item = ++Equal to number. ++ ++@item > ++Greater than number. ++@end table ++@end table ++ ++@item ++The fourth and usually final key says whether this is a temporary (i.e., ++expiring) score entry, or a permanent (i.e., non-expiring) score entry, ++or whether it is to be done immediately, without adding to the score ++file. ++@table @kbd ++ ++@item t ++Temporary score entry. ++ ++@item p ++Permanent score entry. ++ ++@item i ++Immediately scoring. ++@end table ++ ++@item ++If you are scoring on `e' (extra) headers, you will then be prompted for ++the header name on which you wish to score. This must be a header named ++in gnus-extra-headers, and @samp{TAB} completion is available. ++ ++@end enumerate ++ ++So, let's say you want to increase the score on the current author with ++exact matching permanently: @kbd{I a e p}. If you want to lower the ++score based on the subject line, using substring matching, and make a ++temporary score entry: @kbd{L s s t}. Pretty easy. ++ ++To make things a bit more complicated, there are shortcuts. If you use ++a capital letter on either the second or third keys, Gnus will use ++defaults for the remaining one or two keystrokes. The defaults are ++``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s ++t}, and @kbd{I a R} is the same as @kbd{I a r t}. ++ ++These functions take both the numerical prefix and the symbolic prefix ++(@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower ++(or increase) the score of the article. A symbolic prefix of @code{a} ++says to use the @file{all.SCORE} file for the command instead of the ++current score file. ++ ++@vindex gnus-score-mimic-keymap ++The @code{gnus-score-mimic-keymap} says whether these commands will ++pretend they are keymaps or not. ++ ++ ++@node Group Score Commands ++@section Group Score Commands ++@cindex group score commands ++ ++There aren't many of these as yet, I'm afraid. ++ ++@table @kbd ++ ++@item W e ++@kindex W e (Group) ++@findex gnus-score-edit-all-score ++Edit the apply-to-all-groups all.SCORE file. You will be popped into ++a @code{gnus-score-mode} buffer (@pxref{Score File Editing}). ++ ++@item W f ++@kindex W f (Group) ++@findex gnus-score-flush-cache ++Gnus maintains a cache of score alists to avoid having to reload them ++all the time. This command will flush the cache ++(@code{gnus-score-flush-cache}). ++ ++@end table ++ ++You can do scoring from the command line by saying something like: ++ ++@findex gnus-batch-score ++@cindex batch scoring ++@example ++$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score ++@end example ++ ++ ++@node Score Variables ++@section Score Variables ++@cindex score variables ++ ++@table @code ++ ++@item gnus-use-scoring ++@vindex gnus-use-scoring ++If @code{nil}, Gnus will not check for score files, and will not, in ++general, do any score-related work. This is @code{t} by default. ++ ++@item gnus-kill-killed ++@vindex gnus-kill-killed ++If this variable is @code{nil}, Gnus will never apply score files to ++articles that have already been through the kill process. While this ++may save you lots of time, it also means that if you apply a kill file ++to a group, and then change the kill file and want to run it over you ++group again to kill more articles, it won't work. You have to set this ++variable to @code{t} to do that. (It is @code{t} by default.) ++ ++@item gnus-kill-files-directory ++@vindex gnus-kill-files-directory ++All kill and score files will be stored in this directory, which is ++initialized from the @env{SAVEDIR} environment variable by default. ++This is @file{~/News/} by default. ++ ++@item gnus-score-file-suffix ++@vindex gnus-score-file-suffix ++Suffix to add to the group name to arrive at the score file name ++(@file{SCORE} by default.) ++ ++@item gnus-score-uncacheable-files ++@vindex gnus-score-uncacheable-files ++@cindex score cache ++All score files are normally cached to avoid excessive re-loading of ++score files. However, this might make your Emacs grow big and ++bloated, so this regexp can be used to weed out score files unlikely ++to be needed again. It would be a bad idea to deny caching of ++@file{all.SCORE}, while it might be a good idea to not cache ++@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this ++variable is @samp{ADAPT$} by default, so no adaptive score files will ++be cached. ++ ++@item gnus-save-score ++@vindex gnus-save-score ++If you have really complicated score files, and do lots of batch ++scoring, then you might set this variable to @code{t}. This will make ++Gnus save the scores into the @file{.newsrc.eld} file. ++ ++If you do not set this to @code{t}, then manual scores (like those set ++with @kbd{V s} (@code{gnus-summary-set-score})) will not be preserved ++across group visits. ++ ++@item gnus-score-interactive-default-score ++@vindex gnus-score-interactive-default-score ++Score used by all the interactive raise/lower commands to raise/lower ++score with. Default is 1000, which may seem excessive, but this is to ++ensure that the adaptive scoring scheme gets enough room to play with. ++We don't want the small changes from the adaptive scoring to overwrite ++manually entered data. ++ ++@item gnus-summary-default-score ++@vindex gnus-summary-default-score ++Default score of an article, which is 0 by default. ++ ++@item gnus-summary-expunge-below ++@vindex gnus-summary-expunge-below ++Don't display the summary lines of articles that have scores lower than ++this variable. This is @code{nil} by default, which means that no ++articles will be hidden. This variable is local to the summary buffers, ++and has to be set from @code{gnus-summary-mode-hook}. ++ ++@item gnus-score-over-mark ++@vindex gnus-score-over-mark ++Mark (in the third column) used for articles with a score over the ++default. Default is @samp{+}. ++ ++@item gnus-score-below-mark ++@vindex gnus-score-below-mark ++Mark (in the third column) used for articles with a score below the ++default. Default is @samp{-}. ++ ++@item gnus-score-find-score-files-function ++@vindex gnus-score-find-score-files-function ++Function used to find score files for the current group. This function ++is called with the name of the group as the argument. ++ ++Predefined functions available are: ++@table @code ++ ++@item gnus-score-find-single ++@findex gnus-score-find-single ++Only apply the group's own score file. ++ ++@item gnus-score-find-bnews ++@findex gnus-score-find-bnews ++Apply all score files that match, using bnews syntax. This is the ++default. If the current group is @samp{gnu.emacs.gnus}, for instance, ++@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and ++@file{gnu.all.SCORE} would all apply. In short, the instances of ++@samp{all} in the score file names are translated into @samp{.*}, and ++then a regexp match is done. ++ ++This means that if you have some score entries that you want to apply to ++all groups, then you put those entries in the @file{all.SCORE} file. ++ ++The score files are applied in a semi-random order, although Gnus will ++try to apply the more general score files before the more specific score ++files. It does this by looking at the number of elements in the score ++file names---discarding the @samp{all} elements. ++ ++@item gnus-score-find-hierarchical ++@findex gnus-score-find-hierarchical ++Apply all score files from all the parent groups. This means that you ++can't have score files like @file{all.SCORE}, but you can have ++@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE} for each ++server. ++ ++@end table ++This variable can also be a list of functions. In that case, all ++these functions will be called with the group name as argument, and ++all the returned lists of score files will be applied. These ++functions can also return lists of lists of score alists directly. In ++that case, the functions that return these non-file score alists ++should probably be placed before the ``real'' score file functions, to ++ensure that the last score file returned is the local score file. ++Phu. ++ ++For example, to do hierarchical scoring but use a non-server-specific ++overall score file, you could use the value ++@example ++(list (lambda (group) ("all.SCORE")) ++ 'gnus-score-find-hierarchical) ++@end example ++ ++@item gnus-score-expiry-days ++@vindex gnus-score-expiry-days ++This variable says how many days should pass before an unused score file ++entry is expired. If this variable is @code{nil}, no score file entries ++are expired. It's 7 by default. ++ ++@item gnus-update-score-entry-dates ++@vindex gnus-update-score-entry-dates ++If this variable is non-@code{nil}, temporary score entries that have ++been triggered (matched) will have their dates updated. (This is how Gnus ++controls expiry---all non-matched-entries will become too old while ++matched entries will stay fresh and young.) However, if you set this ++variable to @code{nil}, even matched entries will grow old and will ++have to face that oh-so grim reaper. ++ ++@item gnus-score-after-write-file-function ++@vindex gnus-score-after-write-file-function ++Function called with the name of the score file just written. ++ ++@item gnus-score-thread-simplify ++@vindex gnus-score-thread-simplify ++If this variable is non-@code{nil}, article subjects will be ++simplified for subject scoring purposes in the same manner as with ++threading---according to the current value of ++@code{gnus-simplify-subject-functions}. If the scoring entry uses ++@code{substring} or @code{exact} matching, the match will also be ++simplified in this manner. ++ ++@end table ++ ++ ++@node Score File Format ++@section Score File Format ++@cindex score file format ++ ++A score file is an @code{emacs-lisp} file that normally contains just a ++single form. Casual users are not expected to edit these files; ++everything can be changed from the summary buffer. ++ ++Anyway, if you'd like to dig into it yourself, here's an example: ++ ++@lisp ++(("from" ++ ("Lars Ingebrigtsen" -10000) ++ ("Per Abrahamsen") ++ ("larsi\\|lmi" -50000 nil R)) ++ ("subject" ++ ("Ding is Badd" nil 728373)) ++ ("xref" ++ ("alt.politics" -1000 728372 s)) ++ ("lines" ++ (2 -100 nil <)) ++ (mark 0) ++ (expunge -1000) ++ (mark-and-expunge -10) ++ (read-only nil) ++ (orphan -10) ++ (adapt t) ++ (files "/hom/larsi/News/gnu.SCORE") ++ (exclude-files "all.SCORE") ++ (local (gnus-newsgroup-auto-expire t) ++ (gnus-summary-make-false-root empty)) ++ (eval (ding))) ++@end lisp ++ ++This example demonstrates most score file elements. @xref{Advanced ++Scoring}, for a different approach. ++ ++Even though this looks much like Lisp code, nothing here is actually ++@code{eval}ed. The Lisp reader is used to read this form, though, so it ++has to be valid syntactically, if not semantically. ++ ++Six keys are supported by this alist: ++ ++@table @code ++ ++@item STRING ++If the key is a string, it is the name of the header to perform the ++match on. Scoring can only be performed on these eight headers: ++@code{From}, @code{Subject}, @code{References}, @code{Message-ID}, ++@code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to ++these headers, there are three strings to tell Gnus to fetch the entire ++article and do the match on larger parts of the article: @code{Body} ++will perform the match on the body of the article, @code{Head} will ++perform the match on the head of the article, and @code{All} will ++perform the match on the entire article. Note that using any of these ++last three keys will slow down group entry @emph{considerably}. The ++final ``header'' you can score on is @code{Followup}. These score ++entries will result in new score entries being added for all follow-ups ++to articles that matches these score entries. ++ ++Following this key is an arbitrary number of score entries, where each ++score entry has one to four elements. ++@enumerate ++ ++@item ++The first element is the @dfn{match element}. On most headers this will ++be a string, but on the Lines and Chars headers, this must be an ++integer. ++ ++@item ++If the second element is present, it should be a number---the @dfn{score ++element}. This number should be an integer in the neginf to posinf ++interval. This number is added to the score of the article if the match ++is successful. If this element is not present, the ++@code{gnus-score-interactive-default-score} number will be used ++instead. This is 1000 by default. ++ ++@item ++If the third element is present, it should be a number---the @dfn{date ++element}. This date says when the last time this score entry matched, ++which provides a mechanism for expiring the score entries. It this ++element is not present, the score entry is permanent. The date is ++represented by the number of days since December 31, 1 BCE. ++ ++@item ++If the fourth element is present, it should be a symbol---the @dfn{type ++element}. This element specifies what function should be used to see ++whether this score entry matches the article. What match types that can ++be used depends on what header you wish to perform the match on. ++@table @dfn ++ ++@item From, Subject, References, Xref, Message-ID ++For most header types, there are the @code{r} and @code{R} (regexp), as ++well as @code{s} and @code{S} (substring) types, and @code{e} and ++@code{E} (exact match), and @code{w} (word match) types. If this ++element is not present, Gnus will assume that substring matching should ++be used. @code{R}, @code{S}, and @code{E} differ from the others in ++that the matches will be done in a case-sensitive manner. All these ++one-letter types are really just abbreviations for the @code{regexp}, ++@code{string}, @code{exact}, and @code{word} types, which you can use ++instead, if you feel like. ++ ++@item Extra ++Just as for the standard string overview headers, if you are using ++gnus-extra-headers, you can score on these headers' values. In this ++case, there is a 5th element in the score entry, being the name of the ++header to be scored. The following entry is useful in your ++@file{all.SCORE} file in case of spam attacks from a single origin ++host, if your @acronym{NNTP} server tracks @samp{NNTP-Posting-Host} in ++overviews: ++ ++@lisp ++("111.222.333.444" -1000 nil s ++ "NNTP-Posting-Host") ++@end lisp ++ ++@item Lines, Chars ++These two headers use different match types: @code{<}, @code{>}, ++@code{=}, @code{>=} and @code{<=}. ++ ++These predicates are true if ++ ++@example ++(PREDICATE HEADER MATCH) ++@end example ++ ++evaluates to non-@code{nil}. For instance, the advanced match ++@code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the ++following form: ++ ++@lisp ++(< header-value 4) ++@end lisp ++ ++Or to put it another way: When using @code{<} on @code{Lines} with 4 as ++the match, we get the score added if the article has less than 4 lines. ++(It's easy to get confused and think it's the other way around. But ++it's not. I think.) ++ ++When matching on @code{Lines}, be careful because some back ends (like ++@code{nndir}) do not generate @code{Lines} header, so every article ends ++up being marked as having 0 lines. This can lead to strange results if ++you happen to lower score of the articles with few lines. ++ ++@item Date ++For the Date header we have three kinda silly match types: ++@code{before}, @code{at} and @code{after}. I can't really imagine this ++ever being useful, but, like, it would feel kinda silly not to provide ++this function. Just in case. You never know. Better safe than sorry. ++Once burnt, twice shy. Don't judge a book by its cover. Never not have ++sex on a first date. (I have been told that at least one person, and I ++quote, ``found this function indispensable'', however.) ++ ++@cindex ISO8601 ++@cindex date ++A more useful match type is @code{regexp}. With it, you can match the ++date string using a regular expression. The date is normalized to ++ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If ++you want to match all articles that have been posted on April 1st in ++every year, you could use @samp{....0401.........} as a match string, ++for instance. (Note that the date is kept in its original time zone, so ++this will match articles that were posted when it was April 1st where ++the article was posted from. Time zones are such wholesome fun for the ++whole family, eh?) ++ ++@item Head, Body, All ++These three match keys use the same match types as the @code{From} (etc) ++header uses. ++ ++@item Followup ++This match key is somewhat special, in that it will match the ++@code{From} header, and affect the score of not only the matching ++articles, but also all followups to the matching articles. This allows ++you e.g. increase the score of followups to your own articles, or ++decrease the score of followups to the articles of some known ++trouble-maker. Uses the same match types as the @code{From} header ++uses. (Using this match key will lead to creation of @file{ADAPT} ++files.) ++ ++@item Thread ++This match key works along the same lines as the @code{Followup} match ++key. If you say that you want to score on a (sub-)thread started by an ++article with a @code{Message-ID} @var{x}, then you add a @samp{thread} ++match. This will add a new @samp{thread} match for each article that ++has @var{x} in its @code{References} header. (These new @samp{thread} ++matches will use the @code{Message-ID}s of these matching articles.) ++This will ensure that you can raise/lower the score of an entire thread, ++even though some articles in the thread may not have complete ++@code{References} headers. Note that using this may lead to ++undeterministic scores of the articles in the thread. (Using this match ++key will lead to creation of @file{ADAPT} files.) ++@end table ++@end enumerate ++ ++@cindex score file atoms ++@item mark ++The value of this entry should be a number. Any articles with a score ++lower than this number will be marked as read. ++ ++@item expunge ++The value of this entry should be a number. Any articles with a score ++lower than this number will be removed from the summary buffer. ++ ++@item mark-and-expunge ++The value of this entry should be a number. Any articles with a score ++lower than this number will be marked as read and removed from the ++summary buffer. ++ ++@item thread-mark-and-expunge ++The value of this entry should be a number. All articles that belong to ++a thread that has a total score below this number will be marked as read ++and removed from the summary buffer. @code{gnus-thread-score-function} ++says how to compute the total score for a thread. ++ ++@item files ++The value of this entry should be any number of file names. These files ++are assumed to be score files as well, and will be loaded the same way ++this one was. ++ ++@item exclude-files ++The clue of this entry should be any number of files. These files will ++not be loaded, even though they would normally be so, for some reason or ++other. ++ ++@item eval ++The value of this entry will be @code{eval}el. This element will be ++ignored when handling global score files. ++ ++@item read-only ++Read-only score files will not be updated or saved. Global score files ++should feature this atom (@pxref{Global Score Files}). (Note: ++@dfn{Global} here really means @dfn{global}; not your personal ++apply-to-all-groups score files.) ++ ++@item orphan ++The value of this entry should be a number. Articles that do not have ++parents will get this number added to their scores. Imagine you follow ++some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you ++will only follow a few of the threads, also want to see any new threads. ++ ++You can do this with the following two score file entries: ++ ++@example ++ (orphan -500) ++ (mark-and-expunge -100) ++@end example ++ ++When you enter the group the first time, you will only see the new ++threads. You then raise the score of the threads that you find ++interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the ++rest. Next time you enter the group, you will see new articles in the ++interesting threads, plus any new threads. ++ ++I.e.---the orphan score atom is for high-volume groups where a few ++interesting threads which can't be found automatically by ordinary ++scoring rules exist. ++ ++@item adapt ++This entry controls the adaptive scoring. If it is @code{t}, the ++default adaptive scoring rules will be used. If it is @code{ignore}, no ++adaptive scoring will be performed on this group. If it is a list, this ++list will be used as the adaptive scoring rules. If it isn't present, ++or is something other than @code{t} or @code{ignore}, the default ++adaptive scoring rules will be used. If you want to use adaptive ++scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to ++@code{t}, and insert an @code{(adapt ignore)} in the groups where you do ++not want adaptive scoring. If you only want adaptive scoring in a few ++groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and ++insert @code{(adapt t)} in the score files of the groups where you want ++it. ++ ++@item adapt-file ++All adaptive score entries will go to the file named by this entry. It ++will also be applied when entering the group. This atom might be handy ++if you want to adapt on several groups at once, using the same adaptive ++file for a number of groups. ++ ++@item local ++@cindex local variables ++The value of this entry should be a list of @code{(@var{var} ++@var{value})} pairs. Each @var{var} will be made buffer-local to the ++current summary buffer, and set to the value specified. This is a ++convenient, if somewhat strange, way of setting variables in some ++groups if you don't like hooks much. Note that the @var{value} won't ++be evaluated. ++@end table ++ ++ ++@node Score File Editing ++@section Score File Editing ++ ++You normally enter all scoring commands from the summary buffer, but you ++might feel the urge to edit them by hand as well, so we've supplied you ++with a mode for that. ++ ++It's simply a slightly customized @code{emacs-lisp} mode, with these ++additional commands: ++ ++@table @kbd ++ ++@item C-c C-c ++@kindex C-c C-c (Score) ++@findex gnus-score-edit-exit ++Save the changes you have made and return to the summary buffer ++(@code{gnus-score-edit-exit}). ++ ++@item C-c C-d ++@kindex C-c C-d (Score) ++@findex gnus-score-edit-insert-date ++Insert the current date in numerical format ++(@code{gnus-score-edit-insert-date}). This is really the day number, if ++you were wondering. ++ ++@item C-c C-p ++@kindex C-c C-p (Score) ++@findex gnus-score-pretty-print ++The adaptive score files are saved in an unformatted fashion. If you ++intend to read one of these files, you want to @dfn{pretty print} it ++first. This command (@code{gnus-score-pretty-print}) does that for ++you. ++ ++@end table ++ ++Type @kbd{M-x gnus-score-mode} to use this mode. ++ ++@vindex gnus-score-mode-hook ++@code{gnus-score-menu-hook} is run in score mode buffers. ++ ++In the summary buffer you can use commands like @kbd{V f}, @kbd{V e} and ++@kbd{V t} to begin editing score files. ++ ++ ++@node Adaptive Scoring ++@section Adaptive Scoring ++@cindex adaptive scoring ++ ++If all this scoring is getting you down, Gnus has a way of making it all ++happen automatically---as if by magic. Or rather, as if by artificial ++stupidity, to be precise. ++ ++@vindex gnus-use-adaptive-scoring ++When you read an article, or mark an article as read, or kill an ++article, you leave marks behind. On exit from the group, Gnus can sniff ++these marks and add score elements depending on what marks it finds. ++You turn on this ability by setting @code{gnus-use-adaptive-scoring} to ++@code{t} or @code{(line)}. If you want score adaptively on separate ++words appearing in the subjects, you should set this variable to ++@code{(word)}. If you want to use both adaptive methods, set this ++variable to @code{(word line)}. ++ ++@vindex gnus-default-adaptive-score-alist ++To give you complete control over the scoring process, you can customize ++the @code{gnus-default-adaptive-score-alist} variable. For instance, it ++might look something like this: ++ ++@lisp ++(setq gnus-default-adaptive-score-alist ++ '((gnus-unread-mark) ++ (gnus-ticked-mark (from 4)) ++ (gnus-dormant-mark (from 5)) ++ (gnus-del-mark (from -4) (subject -1)) ++ (gnus-read-mark (from 4) (subject 2)) ++ (gnus-expirable-mark (from -1) (subject -1)) ++ (gnus-killed-mark (from -1) (subject -3)) ++ (gnus-kill-file-mark) ++ (gnus-ancient-mark) ++ (gnus-low-score-mark) ++ (gnus-catchup-mark (from -1) (subject -1)))) ++@end lisp ++ ++As you see, each element in this alist has a mark as a key (either a ++variable name or a ``real'' mark---a character). Following this key is ++a arbitrary number of header/score pairs. If there are no header/score ++pairs following the key, no adaptive scoring will be done on articles ++that have that key as the article mark. For instance, articles with ++@code{gnus-unread-mark} in the example above will not get adaptive score ++entries. ++ ++Each article can have only one mark, so just a single of these rules ++will be applied to each article. ++ ++To take @code{gnus-del-mark} as an example---this alist says that all ++articles that have that mark (i.e., are marked with @samp{e}) will have a ++score entry added to lower based on the @code{From} header by -4, and ++lowered by @code{Subject} by -1. Change this to fit your prejudices. ++ ++If you have marked 10 articles with the same subject with ++@code{gnus-del-mark}, the rule for that mark will be applied ten times. ++That means that that subject will get a score of ten times -1, which ++should be, unless I'm much mistaken, -10. ++ ++If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all ++the read articles will be marked with the @samp{E} mark. This'll ++probably make adaptive scoring slightly impossible, so auto-expiring and ++adaptive scoring doesn't really mix very well. ++ ++The headers you can score on are @code{from}, @code{subject}, ++@code{message-id}, @code{references}, @code{xref}, @code{lines}, ++@code{chars} and @code{date}. In addition, you can score on ++@code{followup}, which will create an adaptive score entry that matches ++on the @code{References} header using the @code{Message-ID} of the ++current article, thereby matching the following thread. ++ ++If you use this scheme, you should set the score file atom @code{mark} ++to something small---like -300, perhaps, to avoid having small random ++changes result in articles getting marked as read. ++ ++After using adaptive scoring for a week or so, Gnus should start to ++become properly trained and enhance the authors you like best, and kill ++the authors you like least, without you having to say so explicitly. ++ ++You can control what groups the adaptive scoring is to be performed on ++by using the score files (@pxref{Score File Format}). This will also ++let you use different rules in different groups. ++ ++@vindex gnus-adaptive-file-suffix ++The adaptive score entries will be put into a file where the name is the ++group name with @code{gnus-adaptive-file-suffix} appended. The default ++is @file{ADAPT}. ++ ++@vindex gnus-adaptive-pretty-print ++Adaptive score files can get huge and are not meant to be edited by ++human hands. If @code{gnus-adaptive-pretty-print} is @code{nil} (the ++deafult) those files will not be written in a human readable way. ++ ++@vindex gnus-score-exact-adapt-limit ++When doing adaptive scoring, substring or fuzzy matching would probably ++give you the best results in most cases. However, if the header one ++matches is short, the possibility for false positives is great, so if ++the length of the match is less than ++@code{gnus-score-exact-adapt-limit}, exact matching will be used. If ++this variable is @code{nil}, exact matching will always be used to avoid ++this problem. ++ ++@vindex gnus-default-adaptive-word-score-alist ++As mentioned above, you can adapt either on individual words or entire ++headers. If you adapt on words, the ++@code{gnus-default-adaptive-word-score-alist} variable says what score ++each instance of a word should add given a mark. ++ ++@lisp ++(setq gnus-default-adaptive-word-score-alist ++ `((,gnus-read-mark . 30) ++ (,gnus-catchup-mark . -10) ++ (,gnus-killed-mark . -20) ++ (,gnus-del-mark . -15))) ++@end lisp ++ ++This is the default value. If you have adaption on words enabled, every ++word that appears in subjects of articles marked with ++@code{gnus-read-mark} will result in a score rule that increase the ++score with 30 points. ++ ++@vindex gnus-default-ignored-adaptive-words ++@vindex gnus-ignored-adaptive-words ++Words that appear in the @code{gnus-default-ignored-adaptive-words} list ++will be ignored. If you wish to add more words to be ignored, use the ++@code{gnus-ignored-adaptive-words} list instead. ++ ++@vindex gnus-adaptive-word-length-limit ++Some may feel that short words shouldn't count when doing adaptive ++scoring. If so, you may set @code{gnus-adaptive-word-length-limit} to ++an integer. Words shorter than this number will be ignored. This ++variable defaults to @code{nil}. ++ ++@vindex gnus-adaptive-word-syntax-table ++When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the ++syntax table in effect. It is similar to the standard syntax table, but ++it considers numbers to be non-word-constituent characters. ++ ++@vindex gnus-adaptive-word-minimum ++If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive ++word scoring process will never bring down the score of an article to ++below this number. The default is @code{nil}. ++ ++@vindex gnus-adaptive-word-no-group-words ++If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus ++won't adaptively word score any of the words in the group name. Useful ++for groups like @samp{comp.editors.emacs}, where most of the subject ++lines contain the word @samp{emacs}. ++ ++After using this scheme for a while, it might be nice to write a ++@code{gnus-psychoanalyze-user} command to go through the rules and see ++what words you like and what words you don't like. Or perhaps not. ++ ++Note that the adaptive word scoring thing is highly experimental and is ++likely to change in the future. Initial impressions seem to indicate ++that it's totally useless as it stands. Some more work (involving more ++rigorous statistical methods) will have to be done to make this useful. ++ ++ ++@node Home Score File ++@section Home Score File ++ ++The score file where new score file entries will go is called the ++@dfn{home score file}. This is normally (and by default) the score file ++for the group itself. For instance, the home score file for ++@samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}. ++ ++However, this may not be what you want. It is often convenient to share ++a common home score file among many groups---all @samp{emacs} groups ++could perhaps use the same home score file. ++ ++@vindex gnus-home-score-file ++The variable that controls this is @code{gnus-home-score-file}. It can ++be: ++ ++@enumerate ++@item ++A string. Then this file will be used as the home score file for all ++groups. ++ ++@item ++A function. The result of this function will be used as the home score ++file. The function will be called with the name of the group as the ++parameter. ++ ++@item ++A list. The elements in this list can be: ++ ++@enumerate ++@item ++@code{(@var{regexp} @var{file-name})}. If the @var{regexp} matches the ++group name, the @var{file-name} will be used as the home score file. ++ ++@item ++A function. If the function returns non-@code{nil}, the result will ++be used as the home score file. The function will be called with the ++name of the group as the parameter. ++ ++@item ++A string. Use the string as the home score file. ++@end enumerate ++ ++The list will be traversed from the beginning towards the end looking ++for matches. ++ ++@end enumerate ++ ++So, if you want to use just a single score file, you could say: ++ ++@lisp ++(setq gnus-home-score-file ++ "my-total-score-file.SCORE") ++@end lisp ++ ++If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and ++@file{rec.SCORE} for all @samp{rec} groups (and so on), you can say: ++ ++@findex gnus-hierarchial-home-score-file ++@lisp ++(setq gnus-home-score-file ++ 'gnus-hierarchial-home-score-file) ++@end lisp ++ ++This is a ready-made function provided for your convenience. ++Other functions include ++ ++@table @code ++@item gnus-current-home-score-file ++@findex gnus-current-home-score-file ++Return the ``current'' regular score file. This will make scoring ++commands add entry to the ``innermost'' matching score file. ++ ++@end table ++ ++If you want to have one score file for the @samp{emacs} groups and ++another for the @samp{comp} groups, while letting all other groups use ++their own home score files: ++ ++@lisp ++(setq gnus-home-score-file ++ ;; @r{All groups that match the regexp @code{"\\.emacs"}} ++ '(("\\.emacs" "emacs.SCORE") ++ ;; @r{All the comp groups in one score file} ++ ("^comp" "comp.SCORE"))) ++@end lisp ++ ++@vindex gnus-home-adapt-file ++@code{gnus-home-adapt-file} works exactly the same way as ++@code{gnus-home-score-file}, but says what the home adaptive score file ++is instead. All new adaptive file entries will go into the file ++specified by this variable, and the same syntax is allowed. ++ ++In addition to using @code{gnus-home-score-file} and ++@code{gnus-home-adapt-file}, you can also use group parameters ++(@pxref{Group Parameters}) and topic parameters (@pxref{Topic ++Parameters}) to achieve much the same. Group and topic parameters take ++precedence over this variable. ++ ++ ++@node Followups To Yourself ++@section Followups To Yourself ++ ++Gnus offers two commands for picking out the @code{Message-ID} header in ++the current buffer. Gnus will then add a score rule that scores using ++this @code{Message-ID} on the @code{References} header of other ++articles. This will, in effect, increase the score of all articles that ++respond to the article in the current buffer. Quite useful if you want ++to easily note when people answer what you've said. ++ ++@table @code ++ ++@item gnus-score-followup-article ++@findex gnus-score-followup-article ++This will add a score to articles that directly follow up your own ++article. ++ ++@item gnus-score-followup-thread ++@findex gnus-score-followup-thread ++This will add a score to all articles that appear in a thread ``below'' ++your own article. ++@end table ++ ++@vindex message-sent-hook ++These two functions are both primarily meant to be used in hooks like ++@code{message-sent-hook}, like this: ++@lisp ++(add-hook 'message-sent-hook 'gnus-score-followup-thread) ++@end lisp ++ ++ ++If you look closely at your own @code{Message-ID}, you'll notice that ++the first two or three characters are always the same. Here's two of ++mine: ++ ++@example ++ ++ ++@end example ++ ++So ``my'' ident on this machine is @samp{x6}. This can be ++exploited---the following rule will raise the score on all followups to ++myself: ++ ++@lisp ++("references" ++ ("" ++ 1000 nil r)) ++@end lisp ++ ++Whether it's the first two or first three characters that are ``yours'' ++is system-dependent. ++ ++ ++@node Scoring On Other Headers ++@section Scoring On Other Headers ++@cindex scoring on other headers ++ ++Gnus is quite fast when scoring the ``traditional'' ++headers---@samp{From}, @samp{Subject} and so on. However, scoring ++other headers requires writing a @code{head} scoring rule, which means ++that Gnus has to request every single article from the back end to find ++matches. This takes a long time in big groups. ++ ++@vindex gnus-inhibit-slow-scoring ++You can inhibit this slow scoring on headers or body by setting the ++variable @code{gnus-inhibit-slow-scoring}. If ++@code{gnus-inhibit-slow-scoring} is regexp, slow scoring is inhibited if ++the group matches the regexp. If it is t, slow scoring on it is ++inhibited for all groups. ++ ++Now, there's not much you can do about the slowness for news groups, but for ++mail groups, you have greater control. In @ref{To From Newsgroups}, ++it's explained in greater detail what this mechanism does, but here's ++a cookbook example for @code{nnml} on how to allow scoring on the ++@samp{To} and @samp{Cc} headers. ++ ++Put the following in your @file{~/.gnus.el} file. ++ ++@lisp ++(setq gnus-extra-headers '(To Cc Newsgroups Keywords) ++ nnmail-extra-headers gnus-extra-headers) ++@end lisp ++ ++Restart Gnus and rebuild your @code{nnml} overview files with the ++@kbd{M-x nnml-generate-nov-databases} command. This will take a long ++time if you have much mail. ++ ++Now you can score on @samp{To} and @samp{Cc} as ``extra headers'' like ++so: @kbd{I e s p To RET RET}. ++ ++See? Simple. ++ ++ ++@node Scoring Tips ++@section Scoring Tips ++@cindex scoring tips ++ ++@table @dfn ++ ++@item Crossposts ++@cindex crossposts ++@cindex scoring crossposts ++If you want to lower the score of crossposts, the line to match on is ++the @code{Xref} header. ++@lisp ++("xref" (" talk.politics.misc:" -1000)) ++@end lisp ++ ++@item Multiple crossposts ++If you want to lower the score of articles that have been crossposted to ++more than, say, 3 groups: ++@lisp ++("xref" ++ ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" ++ -1000 nil r)) ++@end lisp ++ ++@item Matching on the body ++This is generally not a very good idea---it takes a very long time. ++Gnus actually has to fetch each individual article from the server. But ++you might want to anyway, I guess. Even though there are three match ++keys (@code{Head}, @code{Body} and @code{All}), you should choose one ++and stick with it in each score file. If you use any two, each article ++will be fetched @emph{twice}. If you want to match a bit on the ++@code{Head} and a bit on the @code{Body}, just use @code{All} for all ++the matches. ++ ++@item Marking as read ++You will probably want to mark articles that have scores below a certain ++number as read. This is most easily achieved by putting the following ++in your @file{all.SCORE} file: ++@lisp ++((mark -100)) ++@end lisp ++You may also consider doing something similar with @code{expunge}. ++ ++@item Negated character classes ++If you say stuff like @code{[^abcd]*}, you may get unexpected results. ++That will match newlines, which might lead to, well, The Unknown. Say ++@code{[^abcd\n]*} instead. ++@end table ++ ++ ++@node Reverse Scoring ++@section Reverse Scoring ++@cindex reverse scoring ++ ++If you want to keep just articles that have @samp{Sex with Emacs} in the ++subject header, and expunge all other articles, you could put something ++like this in your score file: ++ ++@lisp ++(("subject" ++ ("Sex with Emacs" 2)) ++ (mark 1) ++ (expunge 1)) ++@end lisp ++ ++So, you raise all articles that match @samp{Sex with Emacs} and mark the ++rest as read, and expunge them to boot. ++ ++ ++@node Global Score Files ++@section Global Score Files ++@cindex global score files ++ ++Sure, other newsreaders have ``global kill files''. These are usually ++nothing more than a single kill file that applies to all groups, stored ++in the user's home directory. Bah! Puny, weak newsreaders! ++ ++What I'm talking about here are Global Score Files. Score files from ++all over the world, from users everywhere, uniting all nations in one ++big, happy score file union! Ange-score! New and untested! ++ ++@vindex gnus-global-score-files ++All you have to do to use other people's score files is to set the ++@code{gnus-global-score-files} variable. One entry for each score file, ++or each score file directory. Gnus will decide by itself what score ++files are applicable to which group. ++ ++To use the score file ++@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and ++all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory, ++say this: ++ ++@lisp ++(setq gnus-global-score-files ++ '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE" ++ "/ftp@@ftp.some-where:/pub/score/")) ++@end lisp ++ ++@findex gnus-score-search-global-directories ++@noindent ++Simple, eh? Directory names must end with a @samp{/}. These ++directories are typically scanned only once during each Gnus session. ++If you feel the need to manually re-scan the remote directories, you can ++use the @code{gnus-score-search-global-directories} command. ++ ++Note that, at present, using this option will slow down group entry ++somewhat. (That is---a lot.) ++ ++If you want to start maintaining score files for other people to use, ++just put your score file up for anonymous ftp and announce it to the ++world. Become a retro-moderator! Participate in the retro-moderator ++wars sure to ensue, where retro-moderators battle it out for the ++sympathy of the people, luring them to use their score files on false ++premises! Yay! The net is saved! ++ ++Here are some tips for the would-be retro-moderator, off the top of my ++head: ++ ++@itemize @bullet ++ ++@item ++Articles heavily crossposted are probably junk. ++@item ++To lower a single inappropriate article, lower by @code{Message-ID}. ++@item ++Particularly brilliant authors can be raised on a permanent basis. ++@item ++Authors that repeatedly post off-charter for the group can safely be ++lowered out of existence. ++@item ++Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest ++articles completely. ++ ++@item ++Use expiring score entries to keep the size of the file down. You ++should probably have a long expiry period, though, as some sites keep ++old articles for a long time. ++@end itemize ++ ++@dots{} I wonder whether other newsreaders will support global score files ++in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue ++Wave, xrn and 1stReader are bound to implement scoring. Should we start ++holding our breath yet? ++ ++ ++@node Kill Files ++@section Kill Files ++@cindex kill files ++ ++Gnus still supports those pesky old kill files. In fact, the kill file ++entries can now be expiring, which is something I wrote before Daniel ++Quinlan thought of doing score files, so I've left the code in there. ++ ++In short, kill processing is a lot slower (and I do mean @emph{a lot}) ++than score processing, so it might be a good idea to rewrite your kill ++files into score files. ++ ++Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any ++forms into this file, which means that you can use kill files as some ++sort of primitive hook function to be run on group entry, even though ++that isn't a very good idea. ++ ++Normal kill files look like this: ++ ++@lisp ++(gnus-kill "From" "Lars Ingebrigtsen") ++(gnus-kill "Subject" "ding") ++(gnus-expunge "X") ++@end lisp ++ ++This will mark every article written by me as read, and remove the ++marked articles from the summary buffer. Very useful, you'll agree. ++ ++Other programs use a totally different kill file syntax. If Gnus ++encounters what looks like a @code{rn} kill file, it will take a stab at ++interpreting it. ++ ++Two summary functions for editing a @sc{gnus} kill file: ++ ++@table @kbd ++ ++@item M-k ++@kindex M-k (Summary) ++@findex gnus-summary-edit-local-kill ++Edit this group's kill file (@code{gnus-summary-edit-local-kill}). ++ ++@item M-K ++@kindex M-K (Summary) ++@findex gnus-summary-edit-global-kill ++Edit the general kill file (@code{gnus-summary-edit-global-kill}). ++@end table ++ ++Two group mode functions for editing the kill files: ++ ++@table @kbd ++ ++@item M-k ++@kindex M-k (Group) ++@findex gnus-group-edit-local-kill ++Edit this group's kill file (@code{gnus-group-edit-local-kill}). ++ ++@item M-K ++@kindex M-K (Group) ++@findex gnus-group-edit-global-kill ++Edit the general kill file (@code{gnus-group-edit-global-kill}). ++@end table ++ ++Kill file variables: ++ ++@table @code ++@item gnus-kill-file-name ++@vindex gnus-kill-file-name ++A kill file for the group @samp{soc.motss} is normally called ++@file{soc.motss.KILL}. The suffix appended to the group name to get ++this file name is detailed by the @code{gnus-kill-file-name} variable. ++The ``global'' kill file (not in the score file sense of ``global'', of ++course) is just called @file{KILL}. ++ ++@vindex gnus-kill-save-kill-file ++@item gnus-kill-save-kill-file ++If this variable is non-@code{nil}, Gnus will save the ++kill file after processing, which is necessary if you use expiring ++kills. ++ ++@item gnus-apply-kill-hook ++@vindex gnus-apply-kill-hook ++@findex gnus-apply-kill-file-unless-scored ++@findex gnus-apply-kill-file ++A hook called to apply kill files to a group. It is ++@code{(gnus-apply-kill-file)} by default. If you want to ignore the ++kill file if you have a score file for the same group, you can set this ++hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want ++kill files to be processed, you should set this variable to @code{nil}. ++ ++@item gnus-kill-file-mode-hook ++@vindex gnus-kill-file-mode-hook ++A hook called in kill-file mode buffers. ++ ++@end table ++ ++ ++@node Converting Kill Files ++@section Converting Kill Files ++@cindex kill files ++@cindex converting kill files ++ ++If you have loads of old kill files, you may want to convert them into ++score files. If they are ``regular'', you can use ++the @file{gnus-kill-to-score.el} package; if not, you'll have to do it ++by hand. ++ ++The kill to score conversion package isn't included in Emacs by default. ++You can fetch it from the contrib directory of the Gnus distribution or ++from ++@uref{http://heim.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}. ++ ++If your old kill files are very complex---if they contain more ++non-@code{gnus-kill} forms than not, you'll have to convert them by ++hand. Or just let them be as they are. Gnus will still use them as ++before. ++ ++ ++@node Advanced Scoring ++@section Advanced Scoring ++ ++Scoring on Subjects and From headers is nice enough, but what if you're ++really interested in what a person has to say only when she's talking ++about a particular subject? Or what if you really don't want to ++read what person A has to say when she's following up to person B, but ++want to read what she says when she's following up to person C? ++ ++By using advanced scoring rules you may create arbitrarily complex ++scoring patterns. ++ ++@menu ++* Advanced Scoring Syntax:: A definition. ++* Advanced Scoring Examples:: What they look like. ++* Advanced Scoring Tips:: Getting the most out of it. ++@end menu ++ ++ ++@node Advanced Scoring Syntax ++@subsection Advanced Scoring Syntax ++ ++Ordinary scoring rules have a string as the first element in the rule. ++Advanced scoring rules have a list as the first element. The second ++element is the score to be applied if the first element evaluated to a ++non-@code{nil} value. ++ ++These lists may consist of three logical operators, one redirection ++operator, and various match operators. ++ ++Logical operators: ++ ++@table @code ++@item & ++@itemx and ++This logical operator will evaluate each of its arguments until it finds ++one that evaluates to @code{false}, and then it'll stop. If all arguments ++evaluate to @code{true} values, then this operator will return ++@code{true}. ++ ++@item | ++@itemx or ++This logical operator will evaluate each of its arguments until it finds ++one that evaluates to @code{true}. If no arguments are @code{true}, ++then this operator will return @code{false}. ++ ++@item ! ++@itemx not ++@itemx ¬ ++This logical operator only takes a single argument. It returns the ++logical negation of the value of its argument. ++ ++@end table ++ ++There is an @dfn{indirection operator} that will make its arguments ++apply to the ancestors of the current article being scored. For ++instance, @code{1-} will make score rules apply to the parent of the ++current article. @code{2-} will make score rules apply to the ++grandparent of the current article. Alternatively, you can write ++@code{^^}, where the number of @code{^}s (carets) says how far back into ++the ancestry you want to go. ++ ++Finally, we have the match operators. These are the ones that do the ++real work. Match operators are header name strings followed by a match ++and a match type. A typical match operator looks like @samp{("from" ++"Lars Ingebrigtsen" s)}. The header names are the same as when using ++simple scoring, and the match types are also the same. ++ ++ ++@node Advanced Scoring Examples ++@subsection Advanced Scoring Examples ++ ++Please note that the following examples are score file rules. To ++make a complete score file from them, surround them with another pair ++of parentheses. ++ ++Let's say you want to increase the score of articles written by Lars ++when he's talking about Gnus: ++ ++@example ++@group ++((& ++ ("from" "Lars Ingebrigtsen") ++ ("subject" "Gnus")) ++ 1000) ++@end group ++@end example ++ ++Quite simple, huh? ++ ++When he writes long articles, he sometimes has something nice to say: ++ ++@example ++((& ++ ("from" "Lars Ingebrigtsen") ++ (| ++ ("subject" "Gnus") ++ ("lines" 100 >))) ++ 1000) ++@end example ++ ++However, when he responds to things written by Reig Eigil Logge, you ++really don't want to read what he's written: ++ ++@example ++((& ++ ("from" "Lars Ingebrigtsen") ++ (1- ("from" "Reig Eigil Logge"))) ++ -100000) ++@end example ++ ++Everybody that follows up Redmondo when he writes about disappearing ++socks should have their scores raised, but only when they talk about ++white socks. However, when Lars talks about socks, it's usually not ++very interesting: ++ ++@example ++((& ++ (1- ++ (& ++ ("from" "redmondo@@.*no" r) ++ ("body" "disappearing.*socks" t))) ++ (! ("from" "Lars Ingebrigtsen")) ++ ("body" "white.*socks")) ++ 1000) ++@end example ++ ++Suppose you're reading a high volume group and you're only interested ++in replies. The plan is to score down all articles that don't have ++subject that begin with "Re:", "Fw:" or "Fwd:" and then score up all ++parents of articles that have subjects that begin with reply marks. ++ ++@example ++((! ("subject" "re:\\|fwd?:" r)) ++ -200) ++((1- ("subject" "re:\\|fwd?:" r)) ++ 200) ++@end example ++ ++The possibilities are endless. ++ ++@node Advanced Scoring Tips ++@subsection Advanced Scoring Tips ++ ++The @code{&} and @code{|} logical operators do short-circuit logic. ++That is, they stop processing their arguments when it's clear what the ++result of the operation will be. For instance, if one of the arguments ++of an @code{&} evaluates to @code{false}, there's no point in evaluating ++the rest of the arguments. This means that you should put slow matches ++(@samp{body}, @samp{header}) last and quick matches (@samp{from}, ++@samp{subject}) first. ++ ++The indirection arguments (@code{1-} and so on) will make their ++arguments work on previous generations of the thread. If you say ++something like: ++ ++@example ++... ++(1- ++ (1- ++ ("from" "lars"))) ++... ++@end example ++ ++Then that means ``score on the from header of the grandparent of the ++current article''. An indirection is quite fast, but it's better to say: ++ ++@example ++(1- ++ (& ++ ("from" "Lars") ++ ("subject" "Gnus"))) ++@end example ++ ++than it is to say: ++ ++@example ++(& ++ (1- ("from" "Lars")) ++ (1- ("subject" "Gnus"))) ++@end example ++ ++ ++@node Score Decays ++@section Score Decays ++@cindex score decays ++@cindex decays ++ ++You may find that your scores have a tendency to grow without ++bounds, especially if you're using adaptive scoring. If scores get too ++big, they lose all meaning---they simply max out and it's difficult to ++use them in any sensible way. ++ ++@vindex gnus-decay-scores ++@findex gnus-decay-score ++@vindex gnus-decay-score-function ++Gnus provides a mechanism for decaying scores to help with this problem. ++When score files are loaded and @code{gnus-decay-scores} is ++non-@code{nil}, Gnus will run the score files through the decaying ++mechanism thereby lowering the scores of all non-permanent score rules. ++If @code{gnus-decay-scores} is a regexp, only score files matching this ++regexp are treated. E.g. you may set it to @samp{\\.ADAPT\\'} if only ++@emph{adaptive} score files should be decayed. The decay itself if ++performed by the @code{gnus-decay-score-function} function, which is ++@code{gnus-decay-score} by default. Here's the definition of that ++function: ++ ++@lisp ++(defun gnus-decay-score (score) ++ "Decay SCORE according to `gnus-score-decay-constant' ++and `gnus-score-decay-scale'." ++ (let ((n (- score ++ (* (if (< score 0) -1 1) ++ (min (abs score) ++ (max gnus-score-decay-constant ++ (* (abs score) ++ gnus-score-decay-scale))))))) ++ (if (and (featurep 'xemacs) ++ ;; XEmacs' floor can handle only the floating point ++ ;; number below the half of the maximum integer. ++ (> (abs n) (lsh -1 -2))) ++ (string-to-number ++ (car (split-string (number-to-string n) "\\."))) ++ (floor n)))) ++@end lisp ++ ++@vindex gnus-score-decay-scale ++@vindex gnus-score-decay-constant ++@code{gnus-score-decay-constant} is 3 by default and ++@code{gnus-score-decay-scale} is 0.05. This should cause the following: ++ ++@enumerate ++@item ++Scores between -3 and 3 will be set to 0 when this function is called. ++ ++@item ++Scores with magnitudes between 3 and 60 will be shrunk by 3. ++ ++@item ++Scores with magnitudes greater than 60 will be shrunk by 5% of the ++score. ++@end enumerate ++ ++If you don't like this decay function, write your own. It is called ++with the score to be decayed as its only parameter, and it should return ++the new score, which should be an integer. ++ ++Gnus will try to decay scores once a day. If you haven't run Gnus for ++four days, Gnus will decay the scores four times, for instance. ++ ++@iftex ++@iflatex ++@chapter Message ++@include message.texi ++@chapter Emacs MIME ++@include emacs-mime.texi ++@chapter Sieve ++@include sieve.texi ++@chapter PGG ++@include pgg.texi ++@chapter SASL ++@include sasl.texi ++@end iflatex ++@end iftex ++ ++@node Various ++@chapter Various ++ ++@menu ++* Process/Prefix:: A convention used by many treatment commands. ++* Interactive:: Making Gnus ask you many questions. ++* Symbolic Prefixes:: How to supply some Gnus functions with options. ++* Formatting Variables:: You can specify what buffers should look like. ++* Window Layout:: Configuring the Gnus buffer windows. ++* Faces and Fonts:: How to change how faces look. ++* Compilation:: How to speed Gnus up. ++* Mode Lines:: Displaying information in the mode lines. ++* Highlighting and Menus:: Making buffers look all nice and cozy. ++* Buttons:: Get tendinitis in ten easy steps! ++* Daemons:: Gnus can do things behind your back. ++* NoCeM:: How to avoid spam and other fatty foods. ++* Undo:: Some actions can be undone. ++* Predicate Specifiers:: Specifying predicates. ++* Moderation:: What to do if you're a moderator. ++* Fetching a Group:: Starting Gnus just to read a group. ++* Image Enhancements:: Modern versions of Emacs/XEmacs can display images. ++* Fuzzy Matching:: What's the big fuzz? ++* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. ++* Spam Package:: A package for filtering and processing spam. ++* The Gnus Registry:: A package for tracking messages by Message-ID. ++* Other modes:: Interaction with other modes. ++* Various Various:: Things that are really various. ++@end menu ++ ++ ++@node Process/Prefix ++@section Process/Prefix ++@cindex process/prefix convention ++ ++Many functions, among them functions for moving, decoding and saving ++articles, use what is known as the @dfn{Process/Prefix convention}. ++ ++This is a method for figuring out what articles the user wants the ++command to be performed on. ++ ++It goes like this: ++ ++If the numeric prefix is N, perform the operation on the next N ++articles, starting with the current one. If the numeric prefix is ++negative, perform the operation on the previous N articles, starting ++with the current one. ++ ++@vindex transient-mark-mode ++If @code{transient-mark-mode} in non-@code{nil} and the region is ++active, all articles in the region will be worked upon. ++ ++If there is no numeric prefix, but some articles are marked with the ++process mark, perform the operation on the articles marked with ++the process mark. ++ ++If there is neither a numeric prefix nor any articles marked with the ++process mark, just perform the operation on the current article. ++ ++Quite simple, really, but it needs to be made clear so that surprises ++are avoided. ++ ++Commands that react to the process mark will push the current list of ++process marked articles onto a stack and will then clear all process ++marked articles. You can restore the previous configuration with the ++@kbd{M P y} command (@pxref{Setting Process Marks}). ++ ++@vindex gnus-summary-goto-unread ++One thing that seems to shock & horrify lots of people is that, for ++instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}. ++Since each @kbd{d} (which marks the current article as read) by default ++goes to the next unread article after marking, this means that @kbd{3 d} ++will mark the next three unread articles as read, no matter what the ++summary buffer looks like. Set @code{gnus-summary-goto-unread} to ++@code{nil} for a more straightforward action. ++ ++Many commands do not use the process/prefix convention. All commands ++that do explicitly say so in this manual. To apply the process/prefix ++convention to commands that do not use it, you can use the @kbd{M-&} ++command. For instance, to mark all the articles in the group as ++expirable, you could say @kbd{M P b M-& E}. ++ ++ ++@node Interactive ++@section Interactive ++@cindex interaction ++ ++@table @code ++ ++@item gnus-novice-user ++@vindex gnus-novice-user ++If this variable is non-@code{nil}, you are either a newcomer to the ++World of Usenet, or you are very cautious, which is a nice thing to be, ++really. You will be given questions of the type ``Are you sure you want ++to do this?'' before doing anything dangerous. This is @code{t} by ++default. ++ ++@item gnus-expert-user ++@vindex gnus-expert-user ++If this variable is non-@code{nil}, you will seldom be asked any ++questions by Gnus. It will simply assume you know what you're doing, no ++matter how strange. ++ ++@item gnus-interactive-catchup ++@vindex gnus-interactive-catchup ++Require confirmation before catching up a group if non-@code{nil}. It ++is @code{t} by default. ++ ++@item gnus-interactive-exit ++@vindex gnus-interactive-exit ++Require confirmation before exiting Gnus. This variable is @code{t} by ++default. ++@end table ++ ++ ++@node Symbolic Prefixes ++@section Symbolic Prefixes ++@cindex symbolic prefixes ++ ++Quite a lot of Emacs commands react to the (numeric) prefix. For ++instance, @kbd{C-u 4 C-f} moves point four characters forward, and ++@kbd{C-u 9 0 0 I s s p} adds a permanent @code{Subject} substring score ++rule of 900 to the current article. ++ ++This is all nice and well, but what if you want to give a command some ++additional information? Well, what most commands do is interpret the ++``raw'' prefix in some special way. @kbd{C-u 0 C-x C-s} means that one ++doesn't want a backup file to be created when saving the current buffer, ++for instance. But what if you want to save without making a backup ++file, and you want Emacs to flash lights and play a nice tune at the ++same time? You can't, and you're probably perfectly happy that way. ++ ++@kindex M-i (Summary) ++@findex gnus-symbolic-argument ++I'm not, so I've added a second prefix---the @dfn{symbolic prefix}. The ++prefix key is @kbd{M-i} (@code{gnus-symbolic-argument}), and the next ++character typed in is the value. You can stack as many @kbd{M-i} ++prefixes as you want. @kbd{M-i a C-M-u} means ``feed the @kbd{C-M-u} ++command the symbolic prefix @code{a}''. @kbd{M-i a M-i b C-M-u} means ++``feed the @kbd{C-M-u} command the symbolic prefixes @code{a} and ++@code{b}''. You get the drift. ++ ++Typing in symbolic prefixes to commands that don't accept them doesn't ++hurt, but it doesn't do any good either. Currently not many Gnus ++functions make use of the symbolic prefix. ++ ++If you're interested in how Gnus implements this, @pxref{Extended ++Interactive}. ++ ++ ++@node Formatting Variables ++@section Formatting Variables ++@cindex formatting variables ++ ++Throughout this manual you've probably noticed lots of variables called ++things like @code{gnus-group-line-format} and ++@code{gnus-summary-mode-line-format}. These control how Gnus is to ++output lines in the various buffers. There's quite a lot of them. ++Fortunately, they all use the same syntax, so there's not that much to ++be annoyed by. ++ ++Here's an example format spec (from the group buffer): @samp{%M%S%5y: ++%(%g%)\n}. We see that it is indeed extremely ugly, and that there are ++lots of percentages everywhere. ++ ++@menu ++* Formatting Basics:: A formatting variable is basically a format string. ++* Mode Line Formatting:: Some rules about mode line formatting variables. ++* Advanced Formatting:: Modifying output in various ways. ++* User-Defined Specs:: Having Gnus call your own functions. ++* Formatting Fonts:: Making the formatting look colorful and nice. ++* Positioning Point:: Moving point to a position after an operation. ++* Tabulation:: Tabulating your output. ++* Wide Characters:: Dealing with wide characters. ++@end menu ++ ++Currently Gnus uses the following formatting variables: ++@code{gnus-group-line-format}, @code{gnus-summary-line-format}, ++@code{gnus-server-line-format}, @code{gnus-topic-line-format}, ++@code{gnus-group-mode-line-format}, ++@code{gnus-summary-mode-line-format}, ++@code{gnus-article-mode-line-format}, ++@code{gnus-server-mode-line-format}, and ++@code{gnus-summary-pick-line-format}. ++ ++All these format variables can also be arbitrary elisp forms. In that ++case, they will be @code{eval}ed to insert the required lines. ++ ++@kindex M-x gnus-update-format ++@findex gnus-update-format ++Gnus includes a command to help you while creating your own format ++specs. @kbd{M-x gnus-update-format} will @code{eval} the current form, ++update the spec in question and pop you to a buffer where you can ++examine the resulting Lisp code to be run to generate the line. ++ ++ ++ ++@node Formatting Basics ++@subsection Formatting Basics ++ ++Each @samp{%} element will be replaced by some string or other when the ++buffer in question is generated. @samp{%5y} means ``insert the @samp{y} ++spec, and pad with spaces to get a 5-character field''. ++ ++As with normal C and Emacs Lisp formatting strings, the numerical ++modifier between the @samp{%} and the formatting type character will ++@dfn{pad} the output so that it is always at least that long. ++@samp{%5y} will make the field always (at least) five characters wide by ++padding with spaces to the left. If you say @samp{%-5y}, it will pad to ++the right instead. ++ ++You may also wish to limit the length of the field to protect against ++particularly wide values. For that you can say @samp{%4,6y}, which ++means that the field will never be more than 6 characters wide and never ++less than 4 characters wide. ++ ++Also Gnus supports some extended format specifications, such as ++@samp{%&user-date;}. ++ ++ ++@node Mode Line Formatting ++@subsection Mode Line Formatting ++ ++Mode line formatting variables (e.g., ++@code{gnus-summary-mode-line-format}) follow the same rules as other, ++buffer line oriented formatting variables (@pxref{Formatting Basics}) ++with the following two differences: ++ ++@enumerate ++ ++@item ++There must be no newline (@samp{\n}) at the end. ++ ++@item ++The special @samp{%%b} spec can be used to display the buffer name. ++Well, it's no spec at all, really---@samp{%%} is just a way to quote ++@samp{%} to allow it to pass through the formatting machinery unmangled, ++so that Emacs receives @samp{%b}, which is something the Emacs mode line ++display interprets to mean ``show the buffer name''. For a full list of ++mode line specs Emacs understands, see the documentation of the ++@code{mode-line-format} variable. ++ ++@end enumerate ++ ++ ++@node Advanced Formatting ++@subsection Advanced Formatting ++ ++It is frequently useful to post-process the fields in some way. ++Padding, limiting, cutting off parts and suppressing certain values can ++be achieved by using @dfn{tilde modifiers}. A typical tilde spec might ++look like @samp{%~(cut 3)~(ignore "0")y}. ++ ++These are the valid modifiers: ++ ++@table @code ++@item pad ++@itemx pad-left ++Pad the field to the left with spaces until it reaches the required ++length. ++ ++@item pad-right ++Pad the field to the right with spaces until it reaches the required ++length. ++ ++@item max ++@itemx max-left ++Cut off characters from the left until it reaches the specified length. ++ ++@item max-right ++Cut off characters from the right until it reaches the specified ++length. ++ ++@item cut ++@itemx cut-left ++Cut off the specified number of characters from the left. ++ ++@item cut-right ++Cut off the specified number of characters from the right. ++ ++@item ignore ++Return an empty string if the field is equal to the specified value. ++ ++@item form ++Use the specified form as the field value when the @samp{@@} spec is ++used. ++ ++Here's an example: ++ ++@lisp ++"~(form (current-time-string))@@" ++@end lisp ++ ++@end table ++ ++Let's take an example. The @samp{%o} spec in the summary mode lines ++will return a date in compact ISO8601 format---@samp{19960809T230410}. ++This is quite a mouthful, so we want to shave off the century number and ++the time, leaving us with a six-character date. That would be ++@samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before ++maxing, and we need the padding to ensure that the date is never less ++than 6 characters to make it look nice in columns.) ++ ++Ignoring is done first; then cutting; then maxing; and then as the very ++last operation, padding. ++ ++If you use lots of these advanced thingies, you'll find that Gnus gets ++quite slow. This can be helped enormously by running @kbd{M-x ++gnus-compile} when you are satisfied with the look of your lines. ++@xref{Compilation}. ++ ++ ++@node User-Defined Specs ++@subsection User-Defined Specs ++ ++All the specs allow for inserting user defined specifiers---@samp{u}. ++The next character in the format string should be a letter. Gnus ++will call the function @code{gnus-user-format-function-}@samp{X}, where ++@samp{X} is the letter following @samp{%u}. The function will be passed ++a single parameter---what the parameter means depends on what buffer ++it's being called from. The function should return a string, which will ++be inserted into the buffer just like information from any other ++specifier. This function may also be called with dummy values, so it ++should protect against that. ++ ++Also Gnus supports extended user-defined specs, such as @samp{%u&foo;}. ++Gnus will call the function @code{gnus-user-format-function-}@samp{foo}. ++ ++You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve ++much the same without defining new functions. Here's an example: ++@samp{%~(form (count-lines (point-min) (point)))@@}. The form ++given here will be evaluated to yield the current line number, and then ++inserted. ++ ++ ++@node Formatting Fonts ++@subsection Formatting Fonts ++ ++@cindex %(, %) ++@vindex gnus-mouse-face ++There are specs for highlighting, and these are shared by all the format ++variables. Text inside the @samp{%(} and @samp{%)} specifiers will get ++the special @code{mouse-face} property set, which means that it will be ++highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer ++over it. ++ ++@cindex %@{, %@} ++@vindex gnus-face-0 ++Text inside the @samp{%@{} and @samp{%@}} specifiers will have their ++normal faces set using @code{gnus-face-0}, which is @code{bold} by ++default. If you say @samp{%1@{}, you'll get @code{gnus-face-1} instead, ++and so on. Create as many faces as you wish. The same goes for the ++@code{mouse-face} specs---you can say @samp{%3(hello%)} to have ++@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}. ++ ++@cindex %<<, %>>, guillemets ++@c @cindex %<<, %>>, %«, %», guillemets ++@vindex gnus-balloon-face-0 ++Text inside the @samp{%<<} and @samp{%>>} specifiers will get the ++special @code{balloon-help} property set to ++@code{gnus-balloon-face-0}. If you say @samp{%1<<}, you'll get ++@code{gnus-balloon-face-1} and so on. The @code{gnus-balloon-face-*} ++variables should be either strings or symbols naming functions that ++return a string. When the mouse passes over text with this property ++set, a balloon window will appear and display the string. Please ++refer to @ref{Tooltips, ,Tooltips, emacs, The Emacs Manual}, ++(in GNU Emacs) or the doc string of @code{balloon-help-mode} (in ++XEmacs) for more information on this. (For technical reasons, the ++guillemets have been approximated as @samp{<<} and @samp{>>} in this ++paragraph.) ++ ++Here's an alternative recipe for the group buffer: ++ ++@lisp ++;; @r{Create three face types.} ++(setq gnus-face-1 'bold) ++(setq gnus-face-3 'italic) ++ ++;; @r{We want the article count to be in} ++;; @r{a bold and green face. So we create} ++;; @r{a new face called @code{my-green-bold}.} ++(copy-face 'bold 'my-green-bold) ++;; @r{Set the color.} ++(set-face-foreground 'my-green-bold "ForestGreen") ++(setq gnus-face-2 'my-green-bold) ++ ++;; @r{Set the new & fancy format.} ++(setq gnus-group-line-format ++ "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n") ++@end lisp ++ ++I'm sure you'll be able to use this scheme to create totally unreadable ++and extremely vulgar displays. Have fun! ++ ++Note that the @samp{%(} specs (and friends) do not make any sense on the ++mode-line variables. ++ ++@node Positioning Point ++@subsection Positioning Point ++ ++Gnus usually moves point to a pre-defined place on each line in most ++buffers. By default, point move to the first colon character on the ++line. You can customize this behavior in three different ways. ++ ++You can move the colon character to somewhere else on the line. ++ ++@findex gnus-goto-colon ++You can redefine the function that moves the point to the colon. The ++function is called @code{gnus-goto-colon}. ++ ++But perhaps the most convenient way to deal with this, if you don't want ++to have a colon in your line, is to use the @samp{%*} specifier. If you ++put a @samp{%*} somewhere in your format line definition, Gnus will ++place point there. ++ ++ ++@node Tabulation ++@subsection Tabulation ++ ++You can usually line up your displays by padding and cutting your ++strings. However, when combining various strings of different size, it ++can often be more convenient to just output the strings, and then worry ++about lining up the following text afterwards. ++ ++To do that, Gnus supplies tabulator specs---@samp{%=}. There are two ++different types---@dfn{hard tabulators} and @dfn{soft tabulators}. ++ ++@samp{%50=} will insert space characters to pad the line up to column ++50. If the text is already past column 50, nothing will be inserted. ++This is the soft tabulator. ++ ++@samp{%-50=} will insert space characters to pad the line up to column ++50. If the text is already past column 50, the excess text past column ++50 will be removed. This is the hard tabulator. ++ ++ ++@node Wide Characters ++@subsection Wide Characters ++ ++Fixed width fonts in most countries have characters of the same width. ++Some countries, however, use Latin characters mixed with wider ++characters---most notable East Asian countries. ++ ++The problem is that when formatting, Gnus assumes that if a string is 10 ++characters wide, it'll be 10 Latin characters wide on the screen. In ++these countries, that's not true. ++ ++@vindex gnus-use-correct-string-widths ++To help fix this, you can set @code{gnus-use-correct-string-widths} to ++@code{t}. This makes buffer generation slower, but the results will be ++prettier. The default value under XEmacs is @code{t} but @code{nil} ++for Emacs. ++ ++ ++@node Window Layout ++@section Window Layout ++@cindex window layout ++ ++No, there's nothing here about X, so be quiet. ++ ++@vindex gnus-use-full-window ++If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all ++other windows and occupy the entire Emacs screen by itself. It is ++@code{t} by default. ++ ++Setting this variable to @code{nil} kinda works, but there are ++glitches. Use at your own peril. ++ ++@vindex gnus-buffer-configuration ++@code{gnus-buffer-configuration} describes how much space each Gnus ++buffer should be given. Here's an excerpt of this variable: ++ ++@lisp ++((group (vertical 1.0 (group 1.0 point) ++ (if gnus-carpal (group-carpal 4)))) ++ (article (vertical 1.0 (summary 0.25 point) ++ (article 1.0)))) ++@end lisp ++ ++This is an alist. The @dfn{key} is a symbol that names some action or ++other. For instance, when displaying the group buffer, the window ++configuration function will use @code{group} as the key. A full list of ++possible names is listed below. ++ ++The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer ++should occupy. To take the @code{article} split as an example - ++ ++@lisp ++(article (vertical 1.0 (summary 0.25 point) ++ (article 1.0))) ++@end lisp ++ ++This @dfn{split} says that the summary buffer should occupy 25% of upper ++half of the screen, and that it is placed over the article buffer. As ++you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all ++reaching for that calculator there). However, the special number ++@code{1.0} is used to signal that this buffer should soak up all the ++rest of the space available after the rest of the buffers have taken ++whatever they need. There should be only one buffer with the @code{1.0} ++size spec per split. ++ ++Point will be put in the buffer that has the optional third element ++@code{point}. In a @code{frame} split, the last subsplit having a leaf ++split where the tag @code{frame-focus} is a member (i.e. is the third or ++fourth element in the list, depending on whether the @code{point} tag is ++present) gets focus. ++ ++Here's a more complicated example: ++ ++@lisp ++(article (vertical 1.0 (group 4) ++ (summary 0.25 point) ++ (if gnus-carpal (summary-carpal 4)) ++ (article 1.0))) ++@end lisp ++ ++If the size spec is an integer instead of a floating point number, ++then that number will be used to say how many lines a buffer should ++occupy, not a percentage. ++ ++If the @dfn{split} looks like something that can be @code{eval}ed (to be ++precise---if the @code{car} of the split is a function or a subr), this ++split will be @code{eval}ed. If the result is non-@code{nil}, it will ++be used as a split. This means that there will be three buffers if ++@code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal} ++is non-@code{nil}. ++ ++Not complicated enough for you? Well, try this on for size: ++ ++@lisp ++(article (horizontal 1.0 ++ (vertical 0.5 ++ (group 1.0) ++ (gnus-carpal 4)) ++ (vertical 1.0 ++ (summary 0.25 point) ++ (summary-carpal 4) ++ (article 1.0)))) ++@end lisp ++ ++Whoops. Two buffers with the mystery 100% tag. And what's that ++@code{horizontal} thingie? ++ ++If the first element in one of the split is @code{horizontal}, Gnus will ++split the window horizontally, giving you two windows side-by-side. ++Inside each of these strips you may carry on all you like in the normal ++fashion. The number following @code{horizontal} says what percentage of ++the screen is to be given to this strip. ++ ++For each split, there @emph{must} be one element that has the 100% tag. ++The splitting is never accurate, and this buffer will eat any leftover ++lines from the splits. ++ ++To be slightly more formal, here's a definition of what a valid split ++may look like: ++ ++@example ++@group ++split = frame | horizontal | vertical | buffer | form ++frame = "(frame " size *split ")" ++horizontal = "(horizontal " size *split ")" ++vertical = "(vertical " size *split ")" ++buffer = "(" buf-name " " size *[ "point" ] *[ "frame-focus"] ")" ++size = number | frame-params ++buf-name = group | article | summary ... ++@end group ++@end example ++ ++The limitations are that the @code{frame} split can only appear as the ++top-level split. @var{form} should be an Emacs Lisp form that should ++return a valid split. We see that each split is fully recursive, and ++may contain any number of @code{vertical} and @code{horizontal} splits. ++ ++@vindex gnus-window-min-width ++@vindex gnus-window-min-height ++@cindex window height ++@cindex window width ++Finding the right sizes can be a bit complicated. No window may be less ++than @code{gnus-window-min-height} (default 1) characters high, and all ++windows must be at least @code{gnus-window-min-width} (default 1) ++characters wide. Gnus will try to enforce this before applying the ++splits. If you want to use the normal Emacs window width/height limit, ++you can just set these two variables to @code{nil}. ++ ++If you're not familiar with Emacs terminology, @code{horizontal} and ++@code{vertical} splits may work the opposite way of what you'd expect. ++Windows inside a @code{horizontal} split are shown side-by-side, and ++windows within a @code{vertical} split are shown above each other. ++ ++@findex gnus-configure-frame ++If you want to experiment with window placement, a good tip is to call ++@code{gnus-configure-frame} directly with a split. This is the function ++that does all the real work when splitting buffers. Below is a pretty ++nonsensical configuration with 5 windows; two for the group buffer and ++three for the article buffer. (I said it was nonsensical.) If you ++@code{eval} the statement below, you can get an idea of how that would ++look straight away, without going through the normal Gnus channels. ++Play with it until you're satisfied, and then use ++@code{gnus-add-configuration} to add your new creation to the buffer ++configuration list. ++ ++@lisp ++(gnus-configure-frame ++ '(horizontal 1.0 ++ (vertical 10 ++ (group 1.0) ++ (article 0.3 point)) ++ (vertical 1.0 ++ (article 1.0) ++ (horizontal 4 ++ (group 1.0) ++ (article 10))))) ++@end lisp ++ ++You might want to have several frames as well. No prob---just use the ++@code{frame} split: ++ ++@lisp ++(gnus-configure-frame ++ '(frame 1.0 ++ (vertical 1.0 ++ (summary 0.25 point frame-focus) ++ (article 1.0)) ++ (vertical ((height . 5) (width . 15) ++ (user-position . t) ++ (left . -1) (top . 1)) ++ (picon 1.0)))) ++ ++@end lisp ++ ++This split will result in the familiar summary/article window ++configuration in the first (or ``main'') frame, while a small additional ++frame will be created where picons will be shown. As you can see, ++instead of the normal @code{1.0} top-level spec, each additional split ++should have a frame parameter alist as the size spec. ++@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp ++Reference Manual}. Under XEmacs, a frame property list will be ++accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)} ++is such a plist. ++The list of all possible keys for @code{gnus-buffer-configuration} can ++be found in its default value. ++ ++Note that the @code{message} key is used for both ++@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If ++it is desirable to distinguish between the two, something like this ++might be used: ++ ++@lisp ++(message (horizontal 1.0 ++ (vertical 1.0 (message 1.0 point)) ++ (vertical 0.24 ++ (if (buffer-live-p gnus-summary-buffer) ++ '(summary 0.5)) ++ (group 1.0)))) ++@end lisp ++ ++One common desire for a multiple frame split is to have a separate frame ++for composing mail and news while leaving the original frame intact. To ++accomplish that, something like the following can be done: ++ ++@lisp ++(message ++ (frame 1.0 ++ (if (not (buffer-live-p gnus-summary-buffer)) ++ (car (cdr (assoc 'group gnus-buffer-configuration))) ++ (car (cdr (assoc 'summary gnus-buffer-configuration)))) ++ (vertical ((user-position . t) (top . 1) (left . 1) ++ (name . "Message")) ++ (message 1.0 point)))) ++@end lisp ++ ++@findex gnus-add-configuration ++Since the @code{gnus-buffer-configuration} variable is so long and ++complicated, there's a function you can use to ease changing the config ++of a single setting: @code{gnus-add-configuration}. If, for instance, ++you want to change the @code{article} setting, you could say: ++ ++@lisp ++(gnus-add-configuration ++ '(article (vertical 1.0 ++ (group 4) ++ (summary .25 point) ++ (article 1.0)))) ++@end lisp ++ ++You'd typically stick these @code{gnus-add-configuration} calls in your ++@file{~/.gnus.el} file or in some startup hook---they should be run after ++Gnus has been loaded. ++ ++@vindex gnus-always-force-window-configuration ++If all windows mentioned in the configuration are already visible, Gnus ++won't change the window configuration. If you always want to force the ++``right'' window configuration, you can set ++@code{gnus-always-force-window-configuration} to non-@code{nil}. ++ ++If you're using tree displays (@pxref{Tree Display}), and the tree ++window is displayed vertically next to another window, you may also want ++to fiddle with @code{gnus-tree-minimize-window} to avoid having the ++windows resized. ++ ++@subsection Example Window Configurations ++ ++@itemize @bullet ++@item ++Narrow left hand side occupied by group buffer. Right hand side split ++between summary buffer (top one-sixth) and article buffer (bottom). ++ ++@ifinfo ++@example +++---+---------+ ++| G | Summary | ++| r +---------+ ++| o | | ++| u | Article | ++| p | | +++---+---------+ ++@end example ++@end ifinfo ++ ++@lisp ++(gnus-add-configuration ++ '(article ++ (horizontal 1.0 ++ (vertical 25 (group 1.0)) ++ (vertical 1.0 ++ (summary 0.16 point) ++ (article 1.0))))) ++ ++(gnus-add-configuration ++ '(summary ++ (horizontal 1.0 ++ (vertical 25 (group 1.0)) ++ (vertical 1.0 (summary 1.0 point))))) ++@end lisp ++ ++@end itemize ++ ++ ++@node Faces and Fonts ++@section Faces and Fonts ++@cindex faces ++@cindex fonts ++@cindex colors ++ ++Fiddling with fonts and faces used to be very difficult, but these days ++it is very simple. You simply say @kbd{M-x customize-face}, pick out ++the face you want to alter, and alter it via the standard Customize ++interface. ++ ++ ++@node Compilation ++@section Compilation ++@cindex compilation ++@cindex byte-compilation ++ ++@findex gnus-compile ++ ++Remember all those line format specification variables? ++@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so ++on. Now, Gnus will of course heed whatever these variables are, but, ++unfortunately, changing them will mean a quite significant slow-down. ++(The default values of these variables have byte-compiled functions ++associated with them, while the user-generated versions do not, of ++course.) ++ ++To help with this, you can run @kbd{M-x gnus-compile} after you've ++fiddled around with the variables and feel that you're (kind of) ++satisfied. This will result in the new specs being byte-compiled, and ++you'll get top speed again. Gnus will save these compiled specs in the ++@file{.newsrc.eld} file. (User-defined functions aren't compiled by ++this function, though---you should compile them yourself by sticking ++them into the @file{~/.gnus.el} file and byte-compiling that file.) ++ ++ ++@node Mode Lines ++@section Mode Lines ++@cindex mode lines ++ ++@vindex gnus-updated-mode-lines ++@code{gnus-updated-mode-lines} says what buffers should keep their mode ++lines updated. It is a list of symbols. Supported symbols include ++@code{group}, @code{article}, @code{summary}, @code{server}, ++@code{browse}, and @code{tree}. If the corresponding symbol is present, ++Gnus will keep that mode line updated with information that may be ++pertinent. If this variable is @code{nil}, screen refresh may be ++quicker. ++ ++@cindex display-time ++ ++@vindex gnus-mode-non-string-length ++By default, Gnus displays information on the current article in the mode ++lines of the summary and article buffers. The information Gnus wishes ++to display (e.g. the subject of the article) is often longer than the ++mode lines, and therefore have to be cut off at some point. The ++@code{gnus-mode-non-string-length} variable says how long the other ++elements on the line is (i.e., the non-info part). If you put ++additional elements on the mode line (e.g. a clock), you should modify ++this variable: ++ ++@c Hook written by Francesco Potorti` ++@lisp ++(add-hook 'display-time-hook ++ (lambda () (setq gnus-mode-non-string-length ++ (+ 21 ++ (if line-number-mode 5 0) ++ (if column-number-mode 4 0) ++ (length display-time-string))))) ++@end lisp ++ ++If this variable is @code{nil} (which is the default), the mode line ++strings won't be chopped off, and they won't be padded either. Note ++that the default is unlikely to be desirable, as even the percentage ++complete in the buffer may be crowded off the mode line; the user should ++configure this variable appropriately for her configuration. ++ ++ ++@node Highlighting and Menus ++@section Highlighting and Menus ++@cindex visual ++@cindex highlighting ++@cindex menus ++ ++@vindex gnus-visual ++The @code{gnus-visual} variable controls most of the Gnus-prettifying ++aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy ++colors or fonts. This will also inhibit loading the @file{gnus-vis.el} ++file. ++ ++This variable can be a list of visual properties that are enabled. The ++following elements are valid, and are all included by default: ++ ++@table @code ++@item group-highlight ++Do highlights in the group buffer. ++@item summary-highlight ++Do highlights in the summary buffer. ++@item article-highlight ++Do highlights in the article buffer. ++@item highlight ++Turn on highlighting in all buffers. ++@item group-menu ++Create menus in the group buffer. ++@item summary-menu ++Create menus in the summary buffers. ++@item article-menu ++Create menus in the article buffer. ++@item browse-menu ++Create menus in the browse buffer. ++@item server-menu ++Create menus in the server buffer. ++@item score-menu ++Create menus in the score buffers. ++@item menu ++Create menus in all buffers. ++@end table ++ ++So if you only want highlighting in the article buffer and menus in all ++buffers, you could say something like: ++ ++@lisp ++(setq gnus-visual '(article-highlight menu)) ++@end lisp ++ ++If you want highlighting only and no menus whatsoever, you'd say: ++ ++@lisp ++(setq gnus-visual '(highlight)) ++@end lisp ++ ++If @code{gnus-visual} is @code{t}, highlighting and menus will be used ++in all Gnus buffers. ++ ++Other general variables that influence the look of all buffers include: ++ ++@table @code ++@item gnus-mouse-face ++@vindex gnus-mouse-face ++This is the face (i.e., font) used for mouse highlighting in Gnus. No ++mouse highlights will be done if @code{gnus-visual} is @code{nil}. ++ ++@end table ++ ++There are hooks associated with the creation of all the different menus: ++ ++@table @code ++ ++@item gnus-article-menu-hook ++@vindex gnus-article-menu-hook ++Hook called after creating the article mode menu. ++ ++@item gnus-group-menu-hook ++@vindex gnus-group-menu-hook ++Hook called after creating the group mode menu. ++ ++@item gnus-summary-menu-hook ++@vindex gnus-summary-menu-hook ++Hook called after creating the summary mode menu. ++ ++@item gnus-server-menu-hook ++@vindex gnus-server-menu-hook ++Hook called after creating the server mode menu. ++ ++@item gnus-browse-menu-hook ++@vindex gnus-browse-menu-hook ++Hook called after creating the browse mode menu. ++ ++@item gnus-score-menu-hook ++@vindex gnus-score-menu-hook ++Hook called after creating the score mode menu. ++ ++@end table ++ ++ ++@node Buttons ++@section Buttons ++@cindex buttons ++@cindex mouse ++@cindex click ++ ++Those new-fangled @dfn{mouse} contraptions is very popular with the ++young, hep kids who don't want to learn the proper way to do things ++these days. Why, I remember way back in the summer of '89, when I was ++using Emacs on a Tops 20 system. Three hundred users on one single ++machine, and every user was running Simula compilers. Bah! ++ ++Right. ++ ++@vindex gnus-carpal ++Well, you can make Gnus display bufferfuls of buttons you can click to ++do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple, ++really. Tell the chiropractor I sent you. ++ ++ ++@table @code ++ ++@item gnus-carpal-mode-hook ++@vindex gnus-carpal-mode-hook ++Hook run in all carpal mode buffers. ++ ++@item gnus-carpal-button-face ++@vindex gnus-carpal-button-face ++Face used on buttons. ++ ++@item gnus-carpal-header-face ++@vindex gnus-carpal-header-face ++Face used on carpal buffer headers. ++ ++@item gnus-carpal-group-buffer-buttons ++@vindex gnus-carpal-group-buffer-buttons ++Buttons in the group buffer. ++ ++@item gnus-carpal-summary-buffer-buttons ++@vindex gnus-carpal-summary-buffer-buttons ++Buttons in the summary buffer. ++ ++@item gnus-carpal-server-buffer-buttons ++@vindex gnus-carpal-server-buffer-buttons ++Buttons in the server buffer. ++ ++@item gnus-carpal-browse-buffer-buttons ++@vindex gnus-carpal-browse-buffer-buttons ++Buttons in the browse buffer. ++@end table ++ ++All the @code{buttons} variables are lists. The elements in these list ++are either cons cells where the @code{car} contains a text to be displayed and ++the @code{cdr} contains a function symbol, or a simple string. ++ ++ ++@node Daemons ++@section Daemons ++@cindex demons ++@cindex daemons ++ ++Gnus, being larger than any program ever written (allegedly), does lots ++of strange stuff that you may wish to have done while you're not ++present. For instance, you may want it to check for new mail once in a ++while. Or you may want it to close down all connections to all servers ++when you leave Emacs idle. And stuff like that. ++ ++Gnus will let you do stuff like that by defining various ++@dfn{handlers}. Each handler consists of three elements: A ++@var{function}, a @var{time}, and an @var{idle} parameter. ++ ++Here's an example of a handler that closes connections when Emacs has ++been idle for thirty minutes: ++ ++@lisp ++(gnus-demon-close-connections nil 30) ++@end lisp ++ ++Here's a handler that scans for @acronym{PGP} headers every hour when ++Emacs is idle: ++ ++@lisp ++(gnus-demon-scan-pgp 60 t) ++@end lisp ++ ++This @var{time} parameter and that @var{idle} parameter work together ++in a strange, but wonderful fashion. Basically, if @var{idle} is ++@code{nil}, then the function will be called every @var{time} minutes. ++ ++If @var{idle} is @code{t}, then the function will be called after ++@var{time} minutes only if Emacs is idle. So if Emacs is never idle, ++the function will never be called. But once Emacs goes idle, the ++function will be called every @var{time} minutes. ++ ++If @var{idle} is a number and @var{time} is a number, the function will ++be called every @var{time} minutes only when Emacs has been idle for ++@var{idle} minutes. ++ ++If @var{idle} is a number and @var{time} is @code{nil}, the function ++will be called once every time Emacs has been idle for @var{idle} ++minutes. ++ ++And if @var{time} is a string, it should look like @samp{07:31}, and ++the function will then be called once every day somewhere near that ++time. Modified by the @var{idle} parameter, of course. ++ ++@vindex gnus-demon-timestep ++(When I say ``minute'' here, I really mean @code{gnus-demon-timestep} ++seconds. This is 60 by default. If you change that variable, ++all the timings in the handlers will be affected.) ++ ++So, if you want to add a handler, you could put something like this in ++your @file{~/.gnus.el} file: ++ ++@findex gnus-demon-add-handler ++@lisp ++(gnus-demon-add-handler 'gnus-demon-close-connections 30 t) ++@end lisp ++ ++@findex gnus-demon-add-nocem ++@findex gnus-demon-add-scanmail ++@findex gnus-demon-add-rescan ++@findex gnus-demon-add-scan-timestamps ++@findex gnus-demon-add-disconnection ++Some ready-made functions to do this have been created: ++@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, ++@code{gnus-demon-add-nntp-close-connection}, ++@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and ++@code{gnus-demon-add-scanmail}. Just put those functions in your ++@file{~/.gnus.el} if you want those abilities. ++ ++@findex gnus-demon-init ++@findex gnus-demon-cancel ++@vindex gnus-demon-handlers ++If you add handlers to @code{gnus-demon-handlers} directly, you should ++run @code{gnus-demon-init} to make the changes take hold. To cancel all ++daemons, you can use the @code{gnus-demon-cancel} function. ++ ++Note that adding daemons can be pretty naughty if you over do it. Adding ++functions that scan all news and mail from all servers every two seconds ++is a sure-fire way of getting booted off any respectable system. So ++behave. ++ ++ ++@node NoCeM ++@section NoCeM ++@cindex nocem ++@cindex spam ++ ++@dfn{Spamming} is posting the same article lots and lots of times. ++Spamming is bad. Spamming is evil. ++ ++Spamming is usually canceled within a day or so by various anti-spamming ++agencies. These agencies usually also send out @dfn{NoCeM} messages. ++NoCeM is pronounced ``no see-'em'', and means what the name ++implies---these are messages that make the offending articles, like, go ++away. ++ ++What use are these NoCeM messages if the articles are canceled anyway? ++Some sites do not honor cancel messages and some sites just honor cancels ++from a select few people. Then you may wish to make use of the NoCeM ++messages, which are distributed in the newsgroups ++@samp{news.lists.filters}, @samp{alt.nocem.misc}, etc. ++ ++Gnus can read and parse the messages in this group automatically, and ++this will make spam disappear. ++ ++There are some variables to customize, of course: ++ ++@table @code ++@item gnus-use-nocem ++@vindex gnus-use-nocem ++Set this variable to @code{t} to set the ball rolling. It is @code{nil} ++by default. ++ ++You can also set this variable to a positive number as a group level. ++In that case, Gnus scans NoCeM messages when checking new news if this ++value is not exceeding a group level that you specify as the prefix ++argument to some commands, e.g. @code{gnus}, ++@code{gnus-group-get-new-news}, etc. Otherwise, Gnus does not scan ++NoCeM messages if you specify a group level that is smaller than this ++value to those commands. For example, if you use 1 or 2 on the mail ++groups and the levels on the news groups remain the default, 3 is the ++best choice. ++ ++@item gnus-nocem-groups ++@vindex gnus-nocem-groups ++Gnus will look for NoCeM messages in the groups in this list. The ++default is ++@lisp ++("news.lists.filters" "alt.nocem.misc") ++@end lisp ++ ++@item gnus-nocem-issuers ++@vindex gnus-nocem-issuers ++There are many people issuing NoCeM messages. This list says what ++people you want to listen to. The default is: ++ ++@lisp ++("Adri Verhoef" ++ "alba-nocem@@albasani.net" ++ "bleachbot@@httrack.com" ++ "news@@arcor-online.net" ++ "news@@uni-berlin.de" ++ "nocem@@arcor.de" ++ "pgpmoose@@killfile.org" ++ "xjsppl@@gmx.de") ++@end lisp ++ ++Known despammers that you can put in this list are listed at@* ++@uref{http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html}. ++ ++You do not have to heed NoCeM messages from all these people---just the ++ones you want to listen to. You also don't have to accept all NoCeM ++messages from the people you like. Each NoCeM message has a @dfn{type} ++header that gives the message a (more or less, usually less) rigorous ++definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf}, ++@samp{binary}, and @samp{troll}. To specify this, you have to use ++@code{(@var{issuer} @var{conditions} @dots{})} elements in the list. ++Each condition is either a string (which is a regexp that matches types ++you want to use) or a list on the form @code{(not @var{string})}, where ++@var{string} is a regexp that matches types you don't want to use. ++ ++For instance, if you want all NoCeM messages from Chris Lewis except his ++@samp{troll} messages, you'd say: ++ ++@lisp ++("clewis@@ferret.ocunix.on.ca" ".*" (not "troll")) ++@end lisp ++ ++On the other hand, if you just want nothing but his @samp{spam} and ++@samp{spew} messages, you'd say: ++ ++@lisp ++("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam") ++@end lisp ++ ++The specs are applied left-to-right. ++ ++ ++@item gnus-nocem-verifyer ++@vindex gnus-nocem-verifyer ++@findex gnus-nocem-epg-verify ++@findex pgg-verify ++This should be a function for verifying that the NoCeM issuer is who she ++says she is. This variable defaults to @code{gnus-nocem-epg-verify} if ++EasyPG is available, otherwise defaults to @code{pgg-verify}. The ++function should return non-@code{nil} if the verification is successful, ++otherwise (including the case the NoCeM message was not signed) should ++return @code{nil}. If this is too slow and you don't care for ++verification (which may be dangerous), you can set this variable to ++@code{nil}. ++ ++Formerly the default was @code{mc-verify}, which is a Mailcrypt ++function. While you can still use it, you can change it into ++@code{gnus-nocem-epg-verify} or @code{pgg-verify} running with GnuPG if ++you are willing to add the @acronym{PGP} public keys to GnuPG's keyring. ++ ++@item gnus-nocem-directory ++@vindex gnus-nocem-directory ++This is where Gnus will store its NoCeM cache files. The default is@* ++@file{~/News/NoCeM/}. ++ ++@item gnus-nocem-expiry-wait ++@vindex gnus-nocem-expiry-wait ++The number of days before removing old NoCeM entries from the cache. ++The default is 15. If you make it shorter Gnus will be faster, but you ++might then see old spam. ++ ++@item gnus-nocem-check-from ++@vindex gnus-nocem-check-from ++Non-@code{nil} means check for valid issuers in message bodies. ++Otherwise don't bother fetching articles unless their author matches a ++valid issuer; that is much faster if you are selective about the ++issuers. ++ ++@item gnus-nocem-check-article-limit ++@vindex gnus-nocem-check-article-limit ++If non-@code{nil}, the maximum number of articles to check in any NoCeM ++group. @code{nil} means no restriction. NoCeM groups can be huge and ++very slow to process. ++ ++@end table ++ ++Using NoCeM could potentially be a memory hog. If you have many living ++(i. e., subscribed or unsubscribed groups), your Emacs process will grow ++big. If this is a problem, you should kill off all (or most) of your ++unsubscribed groups (@pxref{Subscription Commands}). ++ ++ ++@node Undo ++@section Undo ++@cindex undo ++ ++It is very useful to be able to undo actions one has done. In normal ++Emacs buffers, it's easy enough---you just push the @code{undo} button. ++In Gnus buffers, however, it isn't that simple. ++ ++The things Gnus displays in its buffer is of no value whatsoever to ++Gnus---it's all just data designed to look nice to the user. ++Killing a group in the group buffer with @kbd{C-k} makes the line ++disappear, but that's just a side-effect of the real action---the ++removal of the group in question from the internal Gnus structures. ++Undoing something like that can't be done by the normal Emacs ++@code{undo} function. ++ ++Gnus tries to remedy this somewhat by keeping track of what the user ++does and coming up with actions that would reverse the actions the user ++takes. When the user then presses the @code{undo} key, Gnus will run ++the code to reverse the previous action, or the previous actions. ++However, not all actions are easily reversible, so Gnus currently offers ++a few key functions to be undoable. These include killing groups, ++yanking groups, and changing the list of read articles of groups. ++That's it, really. More functions may be added in the future, but each ++added function means an increase in data to be stored, so Gnus will ++never be totally undoable. ++ ++@findex gnus-undo-mode ++@vindex gnus-use-undo ++@findex gnus-undo ++The undoability is provided by the @code{gnus-undo-mode} minor mode. It ++is used if @code{gnus-use-undo} is non-@code{nil}, which is the ++default. The @kbd{C-M-_} key performs the @code{gnus-undo} ++command, which should feel kinda like the normal Emacs @code{undo} ++command. ++ ++ ++@node Predicate Specifiers ++@section Predicate Specifiers ++@cindex predicate specifiers ++ ++Some Gnus variables are @dfn{predicate specifiers}. This is a special ++form that allows flexible specification of predicates without having ++to type all that much. ++ ++These specifiers are lists consisting of functions, symbols and lists. ++ ++Here's an example: ++ ++@lisp ++(or gnus-article-unseen-p ++ gnus-article-unread-p) ++@end lisp ++ ++The available symbols are @code{or}, @code{and} and @code{not}. The ++functions all take one parameter. ++ ++@findex gnus-make-predicate ++Internally, Gnus calls @code{gnus-make-predicate} on these specifiers ++to create a function that can be called. This input parameter to this ++function will be passed along to all the functions in the predicate ++specifier. ++ ++ ++@node Moderation ++@section Moderation ++@cindex moderation ++ ++If you are a moderator, you can use the @file{gnus-mdrtn.el} package. ++It is not included in the standard Gnus package. Write a mail to ++@samp{larsi@@gnus.org} and state what group you moderate, and you'll ++get a copy. ++ ++The moderation package is implemented as a minor mode for summary ++buffers. Put ++ ++@lisp ++(add-hook 'gnus-summary-mode-hook 'gnus-moderate) ++@end lisp ++ ++in your @file{~/.gnus.el} file. ++ ++If you are the moderator of @samp{rec.zoofle}, this is how it's ++supposed to work: ++ ++@enumerate ++@item ++You split your incoming mail by matching on ++@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted ++articles in some mail group---for instance, @samp{nnml:rec.zoofle}. ++ ++@item ++You enter that group once in a while and post articles using the @kbd{e} ++(edit-and-post) or @kbd{s} (just send unedited) commands. ++ ++@item ++If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some ++articles that weren't approved by you, you can cancel them with the ++@kbd{c} command. ++@end enumerate ++ ++To use moderation mode in these two groups, say: ++ ++@lisp ++(setq gnus-moderated-list ++ "^nnml:rec.zoofle$\\|^rec.zoofle$") ++@end lisp ++ ++ ++@node Fetching a Group ++@section Fetching a Group ++@cindex fetching a group ++ ++@findex gnus-fetch-group ++It is sometimes convenient to be able to just say ``I want to read this ++group and I don't care whether Gnus has been started or not''. This is ++perhaps more useful for people who write code than for users, but the ++command @code{gnus-fetch-group} provides this functionality in any case. ++It takes the group name as a parameter. ++ ++ ++@node Image Enhancements ++@section Image Enhancements ++ ++XEmacs, as well as Emacs 21@footnote{Emacs 21 on MS Windows doesn't ++support images, Emacs 22 does.} and up, are able to display pictures and ++stuff, so Gnus has taken advantage of that. ++ ++@menu ++* X-Face:: Display a funky, teensy black-and-white image. ++* Face:: Display a funkier, teensier colored image. ++* Smileys:: Show all those happy faces the way they were meant to be shown. ++* Picons:: How to display pictures of what you're reading. ++* XVarious:: Other XEmacsy Gnusey variables. ++@end menu ++ ++ ++@node X-Face ++@subsection X-Face ++@cindex x-face ++ ++@code{X-Face} headers describe a 48x48 pixel black-and-white (1 bit ++depth) image that's supposed to represent the author of the message. ++It seems to be supported by an ever-growing number of mail and news ++readers. ++ ++@cindex x-face ++@findex gnus-article-display-x-face ++@vindex gnus-article-x-face-command ++@vindex gnus-article-x-face-too-ugly ++@iftex ++@iflatex ++\include{xface} ++@end iflatex ++@end iftex ++@c @anchor{X-Face} ++ ++Viewing an @code{X-Face} header either requires an Emacs that has ++@samp{compface} support (which most XEmacs versions have), or that you ++have suitable conversion or display programs installed. If your Emacs ++has image support the default action is to display the face before the ++@code{From} header. If there's no native @code{X-Face} support, Gnus ++will try to convert the @code{X-Face} header using external programs ++from the @code{pbmplus} package and friends, see below. For XEmacs it's ++faster if XEmacs has been compiled with @code{X-Face} support. The ++default action under Emacs without image support is to fork off the ++@code{display} program. ++ ++On a GNU/Linux system, the @code{display} program is included in the ++ImageMagick package. For external conversion programs look for packages ++with names like @code{netpbm}, @code{libgr-progs} and @code{compface}. ++On Windows, you may use the packages @code{netpbm} and @code{compface} ++from @url{http://gnuwin32.sourceforge.net}. You need to add the ++@code{bin} directory to your @code{PATH} environment variable. ++@c In fact only the following DLLs and binaries seem to be required: ++@c compface1.dll uncompface.exe libnetpbm10.dll icontopbm.exe ++ ++The variable @code{gnus-article-x-face-command} controls which programs ++are used to display the @code{X-Face} header. If this variable is a ++string, this string will be executed in a sub-shell. If it is a ++function, this function will be called with the face as the argument. ++If @code{gnus-article-x-face-too-ugly} (which is a regexp) matches the ++@code{From} header, the face will not be shown. ++ ++(Note: @code{x-face} is used in the variable/function names, not ++@code{xface}). ++ ++@noindent ++Face and variable: ++ ++@table @code ++@item gnus-x-face ++@vindex gnus-x-face ++Face to show X-Face. The colors from this face are used as the ++foreground and background colors of the displayed X-Faces. The ++default colors are black and white. ++ ++@item gnus-face-properties-alist ++@vindex gnus-face-properties-alist ++Alist of image types and properties applied to Face (@pxref{Face}) and ++X-Face images. The default value is @code{((pbm . (:face gnus-x-face)) ++(png . nil))} for Emacs or @code{((xface . (:face gnus-x-face)))} for ++XEmacs. Here are examples: ++ ++@lisp ++;; Specify the altitude of Face and X-Face images in the From header. ++(setq gnus-face-properties-alist ++ '((pbm . (:face gnus-x-face :ascent 80)) ++ (png . (:ascent 80)))) ++ ++;; Show Face and X-Face images as pressed buttons. ++(setq gnus-face-properties-alist ++ '((pbm . (:face gnus-x-face :relief -2)) ++ (png . (:relief -2)))) ++@end lisp ++ ++@pxref{Image Descriptors, ,Image Descriptors, elisp, The Emacs Lisp ++Reference Manual} for the valid properties for various image types. ++Currently, @code{pbm} is used for X-Face images and @code{png} is used ++for Face images in Emacs. Only the @code{:face} property is effective ++on the @code{xface} image type in XEmacs if it is built with the ++@samp{libcompface} library. ++@end table ++ ++If you use posting styles, you can use an @code{x-face-file} entry in ++@code{gnus-posting-styles}, @xref{Posting Styles}. If you don't, Gnus ++provides a few convenience functions and variables to allow easier ++insertion of X-Face headers in outgoing messages. You also need the ++above mentioned ImageMagick, netpbm or other image conversion packages ++(depending the values of the variables below) for these functions. ++ ++@findex gnus-random-x-face ++@vindex gnus-convert-pbm-to-x-face-command ++@vindex gnus-x-face-directory ++@code{gnus-random-x-face} goes through all the @samp{pbm} files in ++@code{gnus-x-face-directory} and picks one at random, and then ++converts it to the X-Face format by using the ++@code{gnus-convert-pbm-to-x-face-command} shell command. The ++@samp{pbm} files should be 48x48 pixels big. It returns the X-Face ++header data as a string. ++ ++@findex gnus-insert-random-x-face-header ++@code{gnus-insert-random-x-face-header} calls ++@code{gnus-random-x-face} and inserts a @samp{X-Face} header with the ++randomly generated data. ++ ++@findex gnus-x-face-from-file ++@vindex gnus-convert-image-to-x-face-command ++@code{gnus-x-face-from-file} takes a GIF file as the parameter, and then ++converts the file to X-Face format by using the ++@code{gnus-convert-image-to-x-face-command} shell command. ++ ++Here's how you would typically use the first function. Put something ++like the following in your @file{~/.gnus.el} file: ++ ++@lisp ++(setq message-required-news-headers ++ (nconc message-required-news-headers ++ (list '(X-Face . gnus-random-x-face)))) ++@end lisp ++ ++Using the last function would be something like this: ++ ++@lisp ++(setq message-required-news-headers ++ (nconc message-required-news-headers ++ (list '(X-Face . (lambda () ++ (gnus-x-face-from-file ++ "~/My-face.gif")))))) ++@end lisp ++ ++ ++@node Face ++@subsection Face ++@cindex face ++ ++@c #### FIXME: faces and x-faces' implementations should really be harmonized. ++ ++@code{Face} headers are essentially a funkier version of @code{X-Face} ++ones. They describe a 48x48 pixel colored image that's supposed to ++represent the author of the message. ++ ++@cindex face ++@findex gnus-article-display-face ++The contents of a @code{Face} header must be a base64 encoded PNG image. ++See @uref{http://quimby.gnus.org/circus/face/} for the precise ++specifications. ++ ++The @code{gnus-face-properties-alist} variable affects the appearance of ++displayed Face images. @xref{X-Face}. ++ ++Viewing an @code{Face} header requires an Emacs that is able to display ++PNG images. ++@c Maybe add this: ++@c (if (featurep 'xemacs) ++@c (featurep 'png) ++@c (image-type-available-p 'png)) ++ ++Gnus provides a few convenience functions and variables to allow ++easier insertion of Face headers in outgoing messages. ++ ++@findex gnus-convert-png-to-face ++@code{gnus-convert-png-to-face} takes a 48x48 PNG image, no longer than ++726 bytes long, and converts it to a face. ++ ++@findex gnus-face-from-file ++@vindex gnus-convert-image-to-face-command ++@code{gnus-face-from-file} takes a JPEG file as the parameter, and then ++converts the file to Face format by using the ++@code{gnus-convert-image-to-face-command} shell command. ++ ++Here's how you would typically use this function. Put something like the ++following in your @file{~/.gnus.el} file: ++ ++@lisp ++(setq message-required-news-headers ++ (nconc message-required-news-headers ++ (list '(Face . (lambda () ++ (gnus-face-from-file "~/face.jpg")))))) ++@end lisp ++ ++ ++@node Smileys ++@subsection Smileys ++@cindex smileys ++ ++@iftex ++@iflatex ++\gnusfig{-3cm}{0.5cm}{\epsfig{figure=ps/BigFace,height=20cm}} ++\input{smiley} ++@end iflatex ++@end iftex ++ ++@dfn{Smiley} is a package separate from Gnus, but since Gnus is ++currently the only package that uses Smiley, it is documented here. ++ ++In short---to use Smiley in Gnus, put the following in your ++@file{~/.gnus.el} file: ++ ++@lisp ++(setq gnus-treat-display-smileys t) ++@end lisp ++ ++Smiley maps text smiley faces---@samp{:-)}, @samp{8-)}, @samp{:-(} and ++the like---to pictures and displays those instead of the text smiley ++faces. The conversion is controlled by a list of regexps that matches ++text and maps that to file names. ++ ++@vindex smiley-regexp-alist ++The alist used is specified by the @code{smiley-regexp-alist} ++variable. The first item in each element is the regexp to be matched; ++the second element is the regexp match group that is to be replaced by ++the picture; and the third element is the name of the file to be ++displayed. ++ ++The following variables customize the appearance of the smileys: ++ ++@table @code ++ ++@item smiley-style ++@vindex smiley-style ++Specifies the smiley style. Predefined smiley styles include ++@code{low-color} (small 13x14 pixel, three-color images), @code{medium} ++(more colorful images, 16x16 pixel), and @code{grayscale} (grayscale ++images, 14x14 pixel). The default depends on the height of the default ++face. ++ ++@item smiley-data-directory ++@vindex smiley-data-directory ++Where Smiley will look for smiley faces files. You shouldn't set this ++variable anymore. Customize @code{smiley-style} instead. ++ ++@item gnus-smiley-file-types ++@vindex gnus-smiley-file-types ++List of suffixes on smiley file names to try. ++ ++@end table ++ ++ ++@node Picons ++@subsection Picons ++ ++@iftex ++@iflatex ++\include{picons} ++@end iflatex ++@end iftex ++ ++So@dots{} You want to slow down your news reader even more! This is a ++good way to do so. It's also a great way to impress people staring ++over your shoulder as you read news. ++ ++What are Picons? To quote directly from the Picons Web site: ++ ++@iftex ++@iflatex ++\margindex{} ++@end iflatex ++@end iftex ++ ++@quotation ++@dfn{Picons} is short for ``personal icons''. They're small, ++constrained images used to represent users and domains on the net, ++organized into databases so that the appropriate image for a given ++e-mail address can be found. Besides users and domains, there are picon ++databases for Usenet newsgroups and weather forecasts. The picons are ++in either monochrome @code{XBM} format or color @code{XPM} and ++@code{GIF} formats. ++@end quotation ++ ++@vindex gnus-picon-databases ++For instructions on obtaining and installing the picons databases, ++point your Web browser at ++@uref{http://www.cs.indiana.edu/picons/ftp/index.html}. ++ ++If you are using Debian GNU/Linux, saying @samp{apt-get install ++picons.*} will install the picons where Gnus can find them. ++ ++To enable displaying picons, simply make sure that ++@code{gnus-picon-databases} points to the directory containing the ++Picons databases. ++ ++@vindex gnus-picon-style ++The variable @code{gnus-picon-style} controls how picons are displayed. ++If @code{inline}, the textual representation is replaced. If ++@code{right}, picons are added right to the textual representation. ++ ++The following variables offer control over where things are located. ++ ++@table @code ++ ++@item gnus-picon-databases ++@vindex gnus-picon-databases ++The location of the picons database. This is a list of directories ++containing the @file{news}, @file{domains}, @file{users} (and so on) ++subdirectories. Defaults to @code{("/usr/lib/picon" ++"/usr/local/faces")}. ++ ++@item gnus-picon-news-directories ++@vindex gnus-picon-news-directories ++List of subdirectories to search in @code{gnus-picon-databases} for ++newsgroups faces. @code{("news")} is the default. ++ ++@item gnus-picon-user-directories ++@vindex gnus-picon-user-directories ++List of subdirectories to search in @code{gnus-picon-databases} for user ++faces. @code{("users" "usenix" "local" "misc")} is the default. ++ ++@item gnus-picon-domain-directories ++@vindex gnus-picon-domain-directories ++List of subdirectories to search in @code{gnus-picon-databases} for ++domain name faces. Defaults to @code{("domains")}. Some people may ++want to add @samp{"unknown"} to this list. ++ ++@item gnus-picon-file-types ++@vindex gnus-picon-file-types ++Ordered list of suffixes on picon file names to try. Defaults to ++@code{("xpm" "gif" "xbm")} minus those not built-in your Emacs. ++ ++@end table ++ ++ ++@node XVarious ++@subsection Various XEmacs Variables ++ ++@table @code ++@item gnus-xmas-glyph-directory ++@vindex gnus-xmas-glyph-directory ++This is where Gnus will look for pictures. Gnus will normally ++auto-detect this directory, but you may set it manually if you have an ++unusual directory structure. ++ ++@item gnus-xmas-modeline-glyph ++@vindex gnus-xmas-modeline-glyph ++A glyph displayed in all Gnus mode lines. It is a tiny gnu head by ++default. ++ ++@end table ++ ++@subsubsection Toolbar ++ ++@table @code ++ ++@item gnus-use-toolbar ++@vindex gnus-use-toolbar ++This variable specifies the position to display the toolbar. If ++@code{nil}, don't display toolbars. If it is non-@code{nil}, it should ++be one of the symbols @code{default}, @code{top}, @code{bottom}, ++@code{right}, and @code{left}. @code{default} means to use the default ++toolbar, the rest mean to display the toolbar on the place which those ++names show. The default is @code{default}. ++ ++@item gnus-toolbar-thickness ++@vindex gnus-toolbar-thickness ++Cons of the height and the width specifying the thickness of a toolbar. ++The height is used for the toolbar displayed on the top or the bottom, ++the width is used for the toolbar displayed on the right or the left. ++The default is that of the default toolbar. ++ ++@item gnus-group-toolbar ++@vindex gnus-group-toolbar ++The toolbar in the group buffer. ++ ++@item gnus-summary-toolbar ++@vindex gnus-summary-toolbar ++The toolbar in the summary buffer. ++ ++@item gnus-summary-mail-toolbar ++@vindex gnus-summary-mail-toolbar ++The toolbar in the summary buffer of mail groups. ++ ++@end table ++ ++@iftex ++@iflatex ++\margindex{} ++@end iflatex ++@end iftex ++ ++ ++@node Fuzzy Matching ++@section Fuzzy Matching ++@cindex fuzzy matching ++ ++Gnus provides @dfn{fuzzy matching} of @code{Subject} lines when doing ++things like scoring, thread gathering and thread comparison. ++ ++As opposed to regular expression matching, fuzzy matching is very fuzzy. ++It's so fuzzy that there's not even a definition of what @dfn{fuzziness} ++means, and the implementation has changed over time. ++ ++Basically, it tries to remove all noise from lines before comparing. ++@samp{Re: }, parenthetical remarks, white space, and so on, are filtered ++out of the strings before comparing the results. This often leads to ++adequate results---even when faced with strings generated by text ++manglers masquerading as newsreaders. ++ ++ ++@node Thwarting Email Spam ++@section Thwarting Email Spam ++@cindex email spam ++@cindex spam ++@cindex UCE ++@cindex unsolicited commercial email ++ ++In these last days of the Usenet, commercial vultures are hanging about ++and grepping through news like crazy to find email addresses they can ++foist off their scams and products to. As a reaction to this, many ++people have started putting nonsense addresses into their @code{From} ++lines. I think this is counterproductive---it makes it difficult for ++people to send you legitimate mail in response to things you write, as ++well as making it difficult to see who wrote what. This rewriting may ++perhaps be a bigger menace than the unsolicited commercial email itself ++in the end. ++ ++The biggest problem I have with email spam is that it comes in under ++false pretenses. I press @kbd{g} and Gnus merrily informs me that I ++have 10 new emails. I say ``Golly gee! Happy is me!'' and select the ++mail group, only to find two pyramid schemes, seven advertisements ++(``New! Miracle tonic for growing full, lustrous hair on your toes!'') ++and one mail asking me to repent and find some god. ++ ++This is annoying. Here's what you can do about it. ++ ++@menu ++* The problem of spam:: Some background, and some solutions ++* Anti-Spam Basics:: Simple steps to reduce the amount of spam. ++* SpamAssassin:: How to use external anti-spam tools. ++* Hashcash:: Reduce spam by burning CPU time. ++@end menu ++ ++@node The problem of spam ++@subsection The problem of spam ++@cindex email spam ++@cindex spam filtering approaches ++@cindex filtering approaches, spam ++@cindex UCE ++@cindex unsolicited commercial email ++ ++First, some background on spam. ++ ++If you have access to e-mail, you are familiar with spam (technically ++termed @acronym{UCE}, Unsolicited Commercial E-mail). Simply put, it ++exists because e-mail delivery is very cheap compared to paper mail, ++so only a very small percentage of people need to respond to an UCE to ++make it worthwhile to the advertiser. Ironically, one of the most ++common spams is the one offering a database of e-mail addresses for ++further spamming. Senders of spam are usually called @emph{spammers}, ++but terms like @emph{vermin}, @emph{scum}, @emph{sociopaths}, and ++@emph{morons} are in common use as well. ++ ++Spam comes from a wide variety of sources. It is simply impossible to ++dispose of all spam without discarding useful messages. A good ++example is the TMDA system, which requires senders ++unknown to you to confirm themselves as legitimate senders before ++their e-mail can reach you. Without getting into the technical side ++of TMDA, a downside is clearly that e-mail from legitimate sources may ++be discarded if those sources can't or won't confirm themselves ++through the TMDA system. Another problem with TMDA is that it ++requires its users to have a basic understanding of e-mail delivery ++and processing. ++ ++The simplest approach to filtering spam is filtering, at the mail ++server or when you sort through incoming mail. If you get 200 spam ++messages per day from @samp{random-address@@vmadmin.com}, you block ++@samp{vmadmin.com}. If you get 200 messages about @samp{VIAGRA}, you ++discard all messages with @samp{VIAGRA} in the message. If you get ++lots of spam from Bulgaria, for example, you try to filter all mail ++from Bulgarian IPs. ++ ++This, unfortunately, is a great way to discard legitimate e-mail. The ++risks of blocking a whole country (Bulgaria, Norway, Nigeria, China, ++etc.) or even a continent (Asia, Africa, Europe, etc.) from contacting ++you should be obvious, so don't do it if you have the choice. ++ ++In another instance, the very informative and useful RISKS digest has ++been blocked by overzealous mail filters because it @strong{contained} ++words that were common in spam messages. Nevertheless, in isolated ++cases, with great care, direct filtering of mail can be useful. ++ ++Another approach to filtering e-mail is the distributed spam ++processing, for instance DCC implements such a system. In essence, ++@var{N} systems around the world agree that a machine @var{X} in ++Ghana, Estonia, or California is sending out spam e-mail, and these ++@var{N} systems enter @var{X} or the spam e-mail from @var{X} into a ++database. The criteria for spam detection vary---it may be the number ++of messages sent, the content of the messages, and so on. When a user ++of the distributed processing system wants to find out if a message is ++spam, he consults one of those @var{N} systems. ++ ++Distributed spam processing works very well against spammers that send ++a large number of messages at once, but it requires the user to set up ++fairly complicated checks. There are commercial and free distributed ++spam processing systems. Distributed spam processing has its risks as ++well. For instance legitimate e-mail senders have been accused of ++sending spam, and their web sites and mailing lists have been shut ++down for some time because of the incident. ++ ++The statistical approach to spam filtering is also popular. It is ++based on a statistical analysis of previous spam messages. Usually ++the analysis is a simple word frequency count, with perhaps pairs of ++words or 3-word combinations thrown into the mix. Statistical ++analysis of spam works very well in most of the cases, but it can ++classify legitimate e-mail as spam in some cases. It takes time to ++run the analysis, the full message must be analyzed, and the user has ++to store the database of spam analysis. Statistical analysis on the ++server is gaining popularity. This has the advantage of letting the ++user Just Read Mail, but has the disadvantage that it's harder to tell ++the server that it has misclassified mail. ++ ++Fighting spam is not easy, no matter what anyone says. There is no ++magic switch that will distinguish Viagra ads from Mom's e-mails. ++Even people are having a hard time telling spam apart from non-spam, ++because spammers are actively looking to fool us into thinking they ++are Mom, essentially. Spamming is irritating, irresponsible, and ++idiotic behavior from a bunch of people who think the world owes them ++a favor. We hope the following sections will help you in fighting the ++spam plague. ++ ++@node Anti-Spam Basics ++@subsection Anti-Spam Basics ++@cindex email spam ++@cindex spam ++@cindex UCE ++@cindex unsolicited commercial email ++ ++One way of dealing with spam is having Gnus split out all spam into a ++@samp{spam} mail group (@pxref{Splitting Mail}). ++ ++First, pick one (1) valid mail address that you can be reached at, and ++put it in your @code{From} header of all your news articles. (I've ++chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form ++@samp{larsi+usenet@@ifi.uio.no} will be a better choice. Ask your ++sysadmin whether your sendmail installation accepts keywords in the local ++part of the mail address.) ++ ++@lisp ++(setq message-default-news-headers ++ "From: Lars Magne Ingebrigtsen \n") ++@end lisp ++ ++Then put the following split rule in @code{nnmail-split-fancy} ++(@pxref{Fancy Mail Splitting}): ++ ++@lisp ++(... ++ (to "larsi@@trym.ifi.uio.no" ++ (| ("subject" "re:.*" "misc") ++ ("references" ".*@@.*" "misc") ++ "spam")) ++ ...) ++@end lisp ++ ++This says that all mail to this address is suspect, but if it has a ++@code{Subject} that starts with a @samp{Re:} or has a @code{References} ++header, it's probably ok. All the rest goes to the @samp{spam} group. ++(This idea probably comes from Tim Pierce.) ++ ++In addition, many mail spammers talk directly to your @acronym{SMTP} server ++and do not include your email address explicitly in the @code{To} ++header. Why they do this is unknown---perhaps it's to thwart this ++thwarting scheme? In any case, this is trivial to deal with---you just ++put anything not addressed to you in the @samp{spam} group by ending ++your fancy split rule in this way: ++ ++@lisp ++( ++ ... ++ (to "larsi" "misc") ++ "spam") ++@end lisp ++ ++In my experience, this will sort virtually everything into the right ++group. You still have to check the @samp{spam} group from time to time to ++check for legitimate mail, though. If you feel like being a good net ++citizen, you can even send off complaints to the proper authorities on ++each unsolicited commercial email---at your leisure. ++ ++This works for me. It allows people an easy way to contact me (they can ++just press @kbd{r} in the usual way), and I'm not bothered at all with ++spam. It's a win-win situation. Forging @code{From} headers to point ++to non-existent domains is yucky, in my opinion. ++ ++Be careful with this approach. Spammers are wise to it. ++ ++ ++@node SpamAssassin ++@subsection SpamAssassin, Vipul's Razor, DCC, etc ++@cindex SpamAssassin ++@cindex Vipul's Razor ++@cindex DCC ++ ++The days where the hints in the previous section were sufficient in ++avoiding spam are coming to an end. There are many tools out there ++that claim to reduce the amount of spam you get. This section could ++easily become outdated fast, as new products replace old, but ++fortunately most of these tools seem to have similar interfaces. Even ++though this section will use SpamAssassin as an example, it should be ++easy to adapt it to most other tools. ++ ++Note that this section does not involve the @code{spam.el} package, ++which is discussed in the next section. If you don't care for all ++the features of @code{spam.el}, you can make do with these simple ++recipes. ++ ++If the tool you are using is not installed on the mail server, you ++need to invoke it yourself. Ideas on how to use the ++@code{:postscript} mail source parameter (@pxref{Mail Source ++Specifiers}) follow. ++ ++@lisp ++(setq mail-sources ++ '((file :prescript "formail -bs spamassassin < /var/mail/%u") ++ (pop :user "jrl" ++ :server "pophost" ++ :postscript ++ "mv %t /tmp/foo; formail -bs spamc < /tmp/foo > %t"))) ++@end lisp ++ ++Once you manage to process your incoming spool somehow, thus making ++the mail contain e.g.@: a header indicating it is spam, you are ready to ++filter it out. Using normal split methods (@pxref{Splitting Mail}): ++ ++@lisp ++(setq nnmail-split-methods '(("spam" "^X-Spam-Flag: YES") ++ ...)) ++@end lisp ++ ++Or using fancy split methods (@pxref{Fancy Mail Splitting}): ++ ++@lisp ++(setq nnmail-split-methods 'nnmail-split-fancy ++ nnmail-split-fancy '(| ("X-Spam-Flag" "YES" "spam") ++ ...)) ++@end lisp ++ ++Some people might not like the idea of piping the mail through various ++programs using a @code{:prescript} (if some program is buggy, you ++might lose all mail). If you are one of them, another solution is to ++call the external tools during splitting. Example fancy split method: ++ ++@lisp ++(setq nnmail-split-fancy '(| (: kevin-spamassassin) ++ ...)) ++(defun kevin-spamassassin () ++ (save-excursion ++ (save-restriction ++ (widen) ++ (if (eq 1 (call-process-region (point-min) (point-max) ++ "spamc" nil nil nil "-c")) ++ "spam")))) ++@end lisp ++ ++Note that with the nnimap back end, message bodies will not be ++downloaded by default. You need to set ++@code{nnimap-split-download-body} to @code{t} to do that ++(@pxref{Splitting in IMAP}). ++ ++That is about it. As some spam is likely to get through anyway, you ++might want to have a nifty function to call when you happen to read ++spam. And here is the nifty function: ++ ++@lisp ++(defun my-gnus-raze-spam () ++ "Submit SPAM to Vipul's Razor, then mark it as expirable." ++ (interactive) ++ (gnus-summary-save-in-pipe "razor-report -f -d" t) ++ (gnus-summary-mark-as-expirable 1)) ++@end lisp ++ ++@node Hashcash ++@subsection Hashcash ++@cindex hashcash ++ ++A novel technique to fight spam is to require senders to do something ++costly and demonstrably unique for each message they send. This has ++the obvious drawback that you cannot rely on everyone in the world ++using this technique, since it is not part of the Internet standards, ++but it may be useful in smaller communities. ++ ++While the tools in the previous section work well in practice, they ++work only because the tools are constantly maintained and updated as ++new form of spam appears. This means that a small percentage of spam ++will always get through. It also means that somewhere, someone needs ++to read lots of spam to update these tools. Hashcash avoids that, but ++instead prefers that everyone you contact through e-mail supports the ++scheme. You can view the two approaches as pragmatic vs dogmatic. ++The approaches have their own advantages and disadvantages, but as ++often in the real world, a combination of them is stronger than either ++one of them separately. ++ ++@cindex X-Hashcash ++The ``something costly'' is to burn CPU time, more specifically to ++compute a hash collision up to a certain number of bits. The ++resulting hashcash cookie is inserted in a @samp{X-Hashcash:} header. ++For more details, and for the external application @code{hashcash} you ++need to install to use this feature, see ++@uref{http://www.hashcash.org/}. Even more information can be found ++at @uref{http://www.camram.org/}. ++ ++If you wish to generate hashcash for each message you send, you can ++customize @code{message-generate-hashcash} (@pxref{Mail Headers, ,Mail ++Headers,message, The Message Manual}), as in: ++ ++@lisp ++(setq message-generate-hashcash t) ++@end lisp ++ ++You will need to set up some additional variables as well: ++ ++@table @code ++ ++@item hashcash-default-payment ++@vindex hashcash-default-payment ++This variable indicates the default number of bits the hash collision ++should consist of. By default this is 20. Suggested useful values ++include 17 to 29. ++ ++@item hashcash-payment-alist ++@vindex hashcash-payment-alist ++Some receivers may require you to spend burn more CPU time than the ++default. This variable contains a list of @samp{(@var{addr} ++@var{amount})} cells, where @var{addr} is the receiver (email address ++or newsgroup) and @var{amount} is the number of bits in the collision ++that is needed. It can also contain @samp{(@var{addr} @var{string} ++@var{amount})} cells, where the @var{string} is the string to use ++(normally the email address or newsgroup name is used). ++ ++@item hashcash-path ++@vindex hashcash-path ++Where the @code{hashcash} binary is installed. This variable should ++be automatically set by @code{executable-find}, but if it's @code{nil} ++(usually because the @code{hashcash} binary is not in your path) ++you'll get a warning when you check hashcash payments and an error ++when you generate hashcash payments. ++ ++@end table ++ ++Gnus can verify hashcash cookies, although this can also be done by ++hand customized mail filtering scripts. To verify a hashcash cookie ++in a message, use the @code{mail-check-payment} function in the ++@code{hashcash.el} library. You can also use the @code{spam.el} ++package with the @code{spam-use-hashcash} back end to validate hashcash ++cookies in incoming mail and filter mail accordingly (@pxref{Anti-spam ++Hashcash Payments}). ++ ++@node Spam Package ++@section Spam Package ++@cindex spam filtering ++@cindex spam ++ ++The Spam package provides Gnus with a centralized mechanism for ++detecting and filtering spam. It filters new mail, and processes ++messages according to whether they are spam or ham. (@dfn{Ham} is the ++name used throughout this manual to indicate non-spam messages.) ++ ++@menu ++* Spam Package Introduction:: ++* Filtering Incoming Mail:: ++* Detecting Spam in Groups:: ++* Spam and Ham Processors:: ++* Spam Package Configuration Examples:: ++* Spam Back Ends:: ++* Extending the Spam package:: ++* Spam Statistics Package:: ++@end menu ++ ++@node Spam Package Introduction ++@subsection Spam Package Introduction ++@cindex spam filtering ++@cindex spam filtering sequence of events ++@cindex spam ++ ++You must read this section to understand how the Spam package works. ++Do not skip, speed-read, or glance through this section. ++ ++Make sure you read the section on the @code{spam.el} sequence of ++events. See @xref{Extending the Spam package}. ++ ++@cindex spam-initialize ++@vindex spam-use-stat ++To use the Spam package, you @strong{must} first run the function ++@code{spam-initialize}: ++ ++@example ++(spam-initialize) ++@end example ++ ++This autoloads @code{spam.el} and installs the various hooks necessary ++to let the Spam package do its job. In order to make use of the Spam ++package, you have to set up certain group parameters and variables, ++which we will describe below. All of the variables controlling the ++Spam package can be found in the @samp{spam} customization group. ++ ++There are two ``contact points'' between the Spam package and the rest ++of Gnus: checking new mail for spam, and leaving a group. ++ ++Checking new mail for spam is done in one of two ways: while splitting ++incoming mail, or when you enter a group. ++ ++The first way, checking for spam while splitting incoming mail, is ++suited to mail back ends such as @code{nnml} or @code{nnimap}, where ++new mail appears in a single spool file. The Spam package processes ++incoming mail, and sends mail considered to be spam to a designated ++``spam'' group. @xref{Filtering Incoming Mail}. ++ ++The second way is suited to back ends such as @code{nntp}, which have ++no incoming mail spool, or back ends where the server is in charge of ++splitting incoming mail. In this case, when you enter a Gnus group, ++the unseen or unread messages in that group are checked for spam. ++Detected spam messages are marked as spam. @xref{Detecting Spam in ++Groups}. ++ ++@cindex spam back ends ++In either case, you have to tell the Spam package what method to use ++to detect spam messages. There are several methods, or @dfn{spam back ++ends} (not to be confused with Gnus back ends!) to choose from: spam ++``blacklists'' and ``whitelists'', dictionary-based filters, and so ++forth. @xref{Spam Back Ends}. ++ ++In the Gnus summary buffer, messages that have been identified as spam ++always appear with a @samp{$} symbol. ++ ++The Spam package divides Gnus groups into three categories: ham ++groups, spam groups, and unclassified groups. You should mark each of ++the groups you subscribe to as either a ham group or a spam group, ++using the @code{spam-contents} group parameter (@pxref{Group ++Parameters}). Spam groups have a special property: when you enter a ++spam group, all unseen articles are marked as spam. Thus, mail split ++into a spam group is automatically marked as spam. ++ ++Identifying spam messages is only half of the Spam package's job. The ++second half comes into play whenever you exit a group buffer. At this ++point, the Spam package does several things: ++ ++First, it calls @dfn{spam and ham processors} to process the articles ++according to whether they are spam or ham. There is a pair of spam ++and ham processors associated with each spam back end, and what the ++processors do depends on the back end. At present, the main role of ++spam and ham processors is for dictionary-based spam filters: they add ++the contents of the messages in the group to the filter's dictionary, ++to improve its ability to detect future spam. The @code{spam-process} ++group parameter specifies what spam processors to use. @xref{Spam and ++Ham Processors}. ++ ++If the spam filter failed to mark a spam message, you can mark it ++yourself, so that the message is processed as spam when you exit the ++group: ++ ++@table @kbd ++@item M-d ++@itemx M s x ++@itemx S x ++@kindex M-d ++@kindex S x ++@kindex M s x ++@findex gnus-summary-mark-as-spam ++@findex gnus-summary-mark-as-spam ++Mark current article as spam, showing it with the @samp{$} mark ++(@code{gnus-summary-mark-as-spam}). ++@end table ++ ++@noindent ++Similarly, you can unmark an article if it has been erroneously marked ++as spam. @xref{Setting Marks}. ++ ++Normally, a ham message found in a non-ham group is not processed as ++ham---the rationale is that it should be moved into a ham group for ++further processing (see below). However, you can force these articles ++to be processed as ham by setting ++@code{spam-process-ham-in-spam-groups} and ++@code{spam-process-ham-in-nonham-groups}. ++ ++@vindex gnus-ham-process-destinations ++@vindex gnus-spam-process-destinations ++The second thing that the Spam package does when you exit a group is ++to move ham articles out of spam groups, and spam articles out of ham ++groups. Ham in a spam group is moved to the group specified by the ++variable @code{gnus-ham-process-destinations}, or the group parameter ++@code{ham-process-destination}. Spam in a ham group is moved to the ++group specified by the variable @code{gnus-spam-process-destinations}, ++or the group parameter @code{spam-process-destination}. If these ++variables are not set, the articles are left in their current group. ++If an article cannot be moved (e.g., with a read-only backend such ++as @acronym{NNTP}), it is copied. ++ ++If an article is moved to another group, it is processed again when ++you visit the new group. Normally, this is not a problem, but if you ++want each article to be processed only once, load the ++@code{gnus-registry.el} package and set the variable ++@code{spam-log-to-registry} to @code{t}. @xref{Spam Package ++Configuration Examples}. ++ ++Normally, spam groups ignore @code{gnus-spam-process-destinations}. ++However, if you set @code{spam-move-spam-nonspam-groups-only} to ++@code{nil}, spam will also be moved out of spam groups, depending on ++the @code{spam-process-destination} parameter. ++ ++The final thing the Spam package does is to mark spam articles as ++expired, which is usually the right thing to do. ++ ++If all this seems confusing, don't worry. Soon it will be as natural ++as typing Lisp one-liners on a neural interface@dots{} err, sorry, that's ++50 years in the future yet. Just trust us, it's not so bad. ++ ++@node Filtering Incoming Mail ++@subsection Filtering Incoming Mail ++@cindex spam filtering ++@cindex spam filtering incoming mail ++@cindex spam ++ ++To use the Spam package to filter incoming mail, you must first set up ++fancy mail splitting. @xref{Fancy Mail Splitting}. The Spam package ++defines a special splitting function that you can add to your fancy ++split variable (either @code{nnmail-split-fancy} or ++@code{nnimap-split-fancy}, depending on your mail back end): ++ ++@example ++(: spam-split) ++@end example ++ ++@vindex spam-split-group ++@noindent ++The @code{spam-split} function scans incoming mail according to your ++chosen spam back end(s), and sends messages identified as spam to a ++spam group. By default, the spam group is a group named @samp{spam}, ++but you can change this by customizing @code{spam-split-group}. Make ++sure the contents of @code{spam-split-group} are an unqualified group ++name. For instance, in an @code{nnimap} server @samp{your-server}, ++the value @samp{spam} means @samp{nnimap+your-server:spam}. The value ++@samp{nnimap+server:spam} is therefore wrong---it gives the group ++@samp{nnimap+your-server:nnimap+server:spam}. ++ ++@code{spam-split} does not modify the contents of messages in any way. ++ ++@vindex nnimap-split-download-body ++Note for IMAP users: if you use the @code{spam-check-bogofilter}, ++@code{spam-check-ifile}, and @code{spam-check-stat} spam back ends, ++you should also set the variable @code{nnimap-split-download-body} ++to @code{t}. These spam back ends are most useful when they can ++``scan'' the full message body. By default, the nnimap back end only ++retrieves the message headers; @code{nnimap-split-download-body} tells ++it to retrieve the message bodies as well. We don't set this by ++default because it will slow @acronym{IMAP} down, and that is not an ++appropriate decision to make on behalf of the user. @xref{Splitting ++in IMAP}. ++ ++You have to specify one or more spam back ends for @code{spam-split} ++to use, by setting the @code{spam-use-*} variables. @xref{Spam Back ++Ends}. Normally, @code{spam-split} simply uses all the spam back ends ++you enabled in this way. However, you can tell @code{spam-split} to ++use only some of them. Why this is useful? Suppose you are using the ++@code{spam-use-regex-headers} and @code{spam-use-blackholes} spam back ++ends, and the following split rule: ++ ++@example ++ nnimap-split-fancy '(| ++ (any "ding" "ding") ++ (: spam-split) ++ ;; @r{default mailbox} ++ "mail") ++@end example ++ ++@noindent ++The problem is that you want all ding messages to make it to the ding ++folder. But that will let obvious spam (for example, spam detected by ++SpamAssassin, and @code{spam-use-regex-headers}) through, when it's ++sent to the ding list. On the other hand, some messages to the ding ++list are from a mail server in the blackhole list, so the invocation ++of @code{spam-split} can't be before the ding rule. ++ ++The solution is to let SpamAssassin headers supersede ding rules, and ++perform the other @code{spam-split} rules (including a second ++invocation of the regex-headers check) after the ding rule. This is ++done by passing a parameter to @code{spam-split}: ++ ++@example ++nnimap-split-fancy ++ '(| ++ ;; @r{spam detected by @code{spam-use-regex-headers} goes to @samp{regex-spam}} ++ (: spam-split "regex-spam" 'spam-use-regex-headers) ++ (any "ding" "ding") ++ ;; @r{all other spam detected by spam-split goes to @code{spam-split-group}} ++ (: spam-split) ++ ;; @r{default mailbox} ++ "mail") ++@end example ++ ++@noindent ++This lets you invoke specific @code{spam-split} checks depending on ++your particular needs, and target the results of those checks to a ++particular spam group. You don't have to throw all mail into all the ++spam tests. Another reason why this is nice is that messages to ++mailing lists you have rules for don't have to have resource-intensive ++blackhole checks performed on them. You could also specify different ++spam checks for your nnmail split vs. your nnimap split. Go crazy. ++ ++You should set the @code{spam-use-*} variables for whatever spam back ++ends you intend to use. The reason is that when loading ++@file{spam.el}, some conditional loading is done depending on what ++@code{spam-use-xyz} variables you have set. @xref{Spam Back Ends}. ++ ++@c @emph{TODO: spam.el needs to provide a uniform way of training all the ++@c statistical databases. Some have that functionality built-in, others ++@c don't.} ++ ++@node Detecting Spam in Groups ++@subsection Detecting Spam in Groups ++ ++To detect spam when visiting a group, set the group's ++@code{spam-autodetect} and @code{spam-autodetect-methods} group ++parameters. These are accessible with @kbd{G c} or @kbd{G p}, as ++usual (@pxref{Group Parameters}). ++ ++You should set the @code{spam-use-*} variables for whatever spam back ++ends you intend to use. The reason is that when loading ++@file{spam.el}, some conditional loading is done depending on what ++@code{spam-use-xyz} variables you have set. ++ ++By default, only unseen articles are processed for spam. You can ++force Gnus to recheck all messages in the group by setting the ++variable @code{spam-autodetect-recheck-messages} to @code{t}. ++ ++If you use the @code{spam-autodetect} method of checking for spam, you ++can specify different spam detection methods for different groups. ++For instance, the @samp{ding} group may have @code{spam-use-BBDB} as ++the autodetection method, while the @samp{suspect} group may have the ++@code{spam-use-blacklist} and @code{spam-use-bogofilter} methods ++enabled. Unlike with @code{spam-split}, you don't have any control ++over the @emph{sequence} of checks, but this is probably unimportant. ++ ++@node Spam and Ham Processors ++@subsection Spam and Ham Processors ++@cindex spam filtering ++@cindex spam filtering variables ++@cindex spam variables ++@cindex spam ++ ++@vindex gnus-spam-process-newsgroups ++Spam and ham processors specify special actions to take when you exit ++a group buffer. Spam processors act on spam messages, and ham ++processors on ham messages. At present, the main role of these ++processors is to update the dictionaries of dictionary-based spam back ++ends such as Bogofilter (@pxref{Bogofilter}) and the Spam Statistics ++package (@pxref{Spam Statistics Filtering}). ++ ++The spam and ham processors that apply to each group are determined by ++the group's@code{spam-process} group parameter. If this group ++parameter is not defined, they are determined by the variable ++@code{gnus-spam-process-newsgroups}. ++ ++@vindex gnus-spam-newsgroup-contents ++Gnus learns from the spam you get. You have to collect your spam in ++one or more spam groups, and set or customize the variable ++@code{spam-junk-mailgroups} as appropriate. You can also declare ++groups to contain spam by setting their group parameter ++@code{spam-contents} to @code{gnus-group-spam-classification-spam}, or ++by customizing the corresponding variable ++@code{gnus-spam-newsgroup-contents}. The @code{spam-contents} group ++parameter and the @code{gnus-spam-newsgroup-contents} variable can ++also be used to declare groups as @emph{ham} groups if you set their ++classification to @code{gnus-group-spam-classification-ham}. If ++groups are not classified by means of @code{spam-junk-mailgroups}, ++@code{spam-contents}, or @code{gnus-spam-newsgroup-contents}, they are ++considered @emph{unclassified}. All groups are unclassified by ++default. ++ ++@vindex gnus-spam-mark ++@cindex $ ++In spam groups, all messages are considered to be spam by default: ++they get the @samp{$} mark (@code{gnus-spam-mark}) when you enter the ++group. If you have seen a message, had it marked as spam, then ++unmarked it, it won't be marked as spam when you enter the group ++thereafter. You can disable that behavior, so all unread messages ++will get the @samp{$} mark, if you set the ++@code{spam-mark-only-unseen-as-spam} parameter to @code{nil}. You ++should remove the @samp{$} mark when you are in the group summary ++buffer for every message that is not spam after all. To remove the ++@samp{$} mark, you can use @kbd{M-u} to ``unread'' the article, or ++@kbd{d} for declaring it read the non-spam way. When you leave a ++group, all spam-marked (@samp{$}) articles are sent to a spam ++processor which will study them as spam samples. ++ ++Messages may also be deleted in various other ways, and unless ++@code{ham-marks} group parameter gets overridden below, marks @samp{R} ++and @samp{r} for default read or explicit delete, marks @samp{X} and ++@samp{K} for automatic or explicit kills, as well as mark @samp{Y} for ++low scores, are all considered to be associated with articles which ++are not spam. This assumption might be false, in particular if you ++use kill files or score files as means for detecting genuine spam, you ++should then adjust the @code{ham-marks} group parameter. ++ ++@defvar ham-marks ++You can customize this group or topic parameter to be the list of ++marks you want to consider ham. By default, the list contains the ++deleted, read, killed, kill-filed, and low-score marks (the idea is ++that these articles have been read, but are not spam). It can be ++useful to also include the tick mark in the ham marks. It is not ++recommended to make the unread mark a ham mark, because it normally ++indicates a lack of classification. But you can do it, and we'll be ++happy for you. ++@end defvar ++ ++@defvar spam-marks ++You can customize this group or topic parameter to be the list of ++marks you want to consider spam. By default, the list contains only ++the spam mark. It is not recommended to change that, but you can if ++you really want to. ++@end defvar ++ ++When you leave @emph{any} group, regardless of its ++@code{spam-contents} classification, all spam-marked articles are sent ++to a spam processor, which will study these as spam samples. If you ++explicit kill a lot, you might sometimes end up with articles marked ++@samp{K} which you never saw, and which might accidentally contain ++spam. Best is to make sure that real spam is marked with @samp{$}, ++and nothing else. ++ ++@vindex gnus-ham-process-destinations ++When you leave a @emph{spam} group, all spam-marked articles are ++marked as expired after processing with the spam processor. This is ++not done for @emph{unclassified} or @emph{ham} groups. Also, any ++@strong{ham} articles in a spam group will be moved to a location ++determined by either the @code{ham-process-destination} group ++parameter or a match in the @code{gnus-ham-process-destinations} ++variable, which is a list of regular expressions matched with group ++names (it's easiest to customize this variable with @kbd{M-x ++customize-variable @key{RET} gnus-ham-process-destinations}). Each ++group name list is a standard Lisp list, if you prefer to customize ++the variable manually. If the @code{ham-process-destination} ++parameter is not set, ham articles are left in place. If the ++@code{spam-mark-ham-unread-before-move-from-spam-group} parameter is ++set, the ham articles are marked as unread before being moved. ++ ++If ham can not be moved---because of a read-only back end such as ++@acronym{NNTP}, for example, it will be copied. ++ ++Note that you can use multiples destinations per group or regular ++expression! This enables you to send your ham to a regular mail ++group and to a @emph{ham training} group. ++ ++When you leave a @emph{ham} group, all ham-marked articles are sent to ++a ham processor, which will study these as non-spam samples. ++ ++@vindex spam-process-ham-in-spam-groups ++By default the variable @code{spam-process-ham-in-spam-groups} is ++@code{nil}. Set it to @code{t} if you want ham found in spam groups ++to be processed. Normally this is not done, you are expected instead ++to send your ham to a ham group and process it there. ++ ++@vindex spam-process-ham-in-nonham-groups ++By default the variable @code{spam-process-ham-in-nonham-groups} is ++@code{nil}. Set it to @code{t} if you want ham found in non-ham (spam ++or unclassified) groups to be processed. Normally this is not done, ++you are expected instead to send your ham to a ham group and process ++it there. ++ ++@vindex gnus-spam-process-destinations ++When you leave a @emph{ham} or @emph{unclassified} group, all ++@strong{spam} articles are moved to a location determined by either ++the @code{spam-process-destination} group parameter or a match in the ++@code{gnus-spam-process-destinations} variable, which is a list of ++regular expressions matched with group names (it's easiest to ++customize this variable with @kbd{M-x customize-variable @key{RET} ++gnus-spam-process-destinations}). Each group name list is a standard ++Lisp list, if you prefer to customize the variable manually. If the ++@code{spam-process-destination} parameter is not set, the spam ++articles are only expired. The group name is fully qualified, meaning ++that if you see @samp{nntp:servername} before the group name in the ++group buffer then you need it here as well. ++ ++If spam can not be moved---because of a read-only back end such as ++@acronym{NNTP}, for example, it will be copied. ++ ++Note that you can use multiples destinations per group or regular ++expression! This enables you to send your spam to multiple @emph{spam ++training} groups. ++ ++@vindex spam-log-to-registry ++The problem with processing ham and spam is that Gnus doesn't track ++this processing by default. Enable the @code{spam-log-to-registry} ++variable so @code{spam.el} will use @code{gnus-registry.el} to track ++what articles have been processed, and avoid processing articles ++multiple times. Keep in mind that if you limit the number of registry ++entries, this won't work as well as it does without a limit. ++ ++@vindex spam-mark-only-unseen-as-spam ++Set this variable if you want only unseen articles in spam groups to ++be marked as spam. By default, it is set. If you set it to ++@code{nil}, unread articles will also be marked as spam. ++ ++@vindex spam-mark-ham-unread-before-move-from-spam-group ++Set this variable if you want ham to be unmarked before it is moved ++out of the spam group. This is very useful when you use something ++like the tick mark @samp{!} to mark ham---the article will be placed ++in your @code{ham-process-destination}, unmarked as if it came fresh ++from the mail server. ++ ++@vindex spam-autodetect-recheck-messages ++When autodetecting spam, this variable tells @code{spam.el} whether ++only unseen articles or all unread articles should be checked for ++spam. It is recommended that you leave it off. ++ ++@node Spam Package Configuration Examples ++@subsection Spam Package Configuration Examples ++@cindex spam filtering ++@cindex spam filtering configuration examples ++@cindex spam configuration examples ++@cindex spam ++ ++@subsubheading Ted's setup ++ ++From Ted Zlatanov . ++@example ++;; @r{for @code{gnus-registry-split-fancy-with-parent} and spam autodetection} ++;; @r{see @file{gnus-registry.el} for more information} ++(gnus-registry-initialize) ++(spam-initialize) ++ ++(setq ++ spam-log-to-registry t ; @r{for spam autodetection} ++ spam-use-BBDB t ++ spam-use-regex-headers t ; @r{catch X-Spam-Flag (SpamAssassin)} ++ ;; @r{all groups with @samp{spam} in the name contain spam} ++ gnus-spam-newsgroup-contents ++ '(("spam" gnus-group-spam-classification-spam)) ++ ;; @r{see documentation for these} ++ spam-move-spam-nonspam-groups-only nil ++ spam-mark-only-unseen-as-spam t ++ spam-mark-ham-unread-before-move-from-spam-group t ++ nnimap-split-rule 'nnimap-split-fancy ++ ;; @r{understand what this does before you copy it to your own setup!} ++ nnimap-split-fancy '(| ++ ;; @r{trace references to parents and put in their group} ++ (: gnus-registry-split-fancy-with-parent) ++ ;; @r{this will catch server-side SpamAssassin tags} ++ (: spam-split 'spam-use-regex-headers) ++ (any "ding" "ding") ++ ;; @r{note that spam by default will go to @samp{spam}} ++ (: spam-split) ++ ;; @r{default mailbox} ++ "mail")) ++ ++;; @r{my parameters, set with @kbd{G p}} ++ ++;; @r{all nnml groups, and all nnimap groups except} ++;; @r{@samp{nnimap+mail.lifelogs.com:train} and} ++;; @r{@samp{nnimap+mail.lifelogs.com:spam}: any spam goes to nnimap training,} ++;; @r{because it must have been detected manually} ++ ++((spam-process-destination . "nnimap+mail.lifelogs.com:train")) ++ ++;; @r{all @acronym{NNTP} groups} ++;; @r{autodetect spam with the blacklist and ham with the BBDB} ++((spam-autodetect-methods spam-use-blacklist spam-use-BBDB) ++;; @r{send all spam to the training group} ++ (spam-process-destination . "nnimap+mail.lifelogs.com:train")) ++ ++;; @r{only some @acronym{NNTP} groups, where I want to autodetect spam} ++((spam-autodetect . t)) ++ ++;; @r{my nnimap @samp{nnimap+mail.lifelogs.com:spam} group} ++ ++;; @r{this is a spam group} ++((spam-contents gnus-group-spam-classification-spam) ++ ++ ;; @r{any spam (which happens when I enter for all unseen messages,} ++ ;; @r{because of the @code{gnus-spam-newsgroup-contents} setting above), goes to} ++ ;; @r{@samp{nnimap+mail.lifelogs.com:train} unless I mark it as ham} ++ ++ (spam-process-destination "nnimap+mail.lifelogs.com:train") ++ ++ ;; @r{any ham goes to my @samp{nnimap+mail.lifelogs.com:mail} folder, but} ++ ;; @r{also to my @samp{nnimap+mail.lifelogs.com:trainham} folder for training} ++ ++ (ham-process-destination "nnimap+mail.lifelogs.com:mail" ++ "nnimap+mail.lifelogs.com:trainham") ++ ;; @r{in this group, only @samp{!} marks are ham} ++ (ham-marks ++ (gnus-ticked-mark)) ++ ;; @r{remembers senders in the blacklist on the way out---this is} ++ ;; @r{definitely not needed, it just makes me feel better} ++ (spam-process (gnus-group-spam-exit-processor-blacklist))) ++ ++;; @r{Later, on the @acronym{IMAP} server I use the @samp{train} group for training} ++;; @r{SpamAssassin to recognize spam, and the @samp{trainham} group fora} ++;; @r{recognizing ham---but Gnus has nothing to do with it.} ++ ++@end example ++ ++@subsubheading Using @code{spam.el} on an IMAP server with a statistical filter on the server ++From Reiner Steib . ++ ++My provider has set up bogofilter (in combination with @acronym{DCC}) on ++the mail server (@acronym{IMAP}). Recognized spam goes to ++@samp{spam.detected}, the rest goes through the normal filter rules, ++i.e. to @samp{some.folder} or to @samp{INBOX}. Training on false ++positives or negatives is done by copying or moving the article to ++@samp{training.ham} or @samp{training.spam} respectively. A cron job on ++the server feeds those to bogofilter with the suitable ham or spam ++options and deletes them from the @samp{training.ham} and ++@samp{training.spam} folders. ++ ++With the following entries in @code{gnus-parameters}, @code{spam.el} ++does most of the job for me: ++ ++@lisp ++ ("nnimap:spam\\.detected" ++ (gnus-article-sort-functions '(gnus-article-sort-by-chars)) ++ (ham-process-destination "nnimap:INBOX" "nnimap:training.ham") ++ (spam-contents gnus-group-spam-classification-spam)) ++ ("nnimap:\\(INBOX\\|other-folders\\)" ++ (spam-process-destination . "nnimap:training.spam") ++ (spam-contents gnus-group-spam-classification-ham)) ++@end lisp ++ ++@itemize ++ ++@item @b{The Spam folder:} ++ ++In the folder @samp{spam.detected}, I have to check for false positives ++(i.e. legitimate mails, that were wrongly judged as spam by ++bogofilter or DCC). ++ ++Because of the @code{gnus-group-spam-classification-spam} entry, all ++messages are marked as spam (with @code{$}). When I find a false ++positive, I mark the message with some other ham mark ++(@code{ham-marks}, @ref{Spam and Ham Processors}). On group exit, ++those messages are copied to both groups, @samp{INBOX} (where I want ++to have the article) and @samp{training.ham} (for training bogofilter) ++and deleted from the @samp{spam.detected} folder. ++ ++The @code{gnus-article-sort-by-chars} entry simplifies detection of ++false positives for me. I receive lots of worms (sweN, @dots{}), that all ++have a similar size. Grouping them by size (i.e. chars) makes finding ++other false positives easier. (Of course worms aren't @i{spam} ++(@acronym{UCE}, @acronym{UBE}) strictly speaking. Anyhow, bogofilter is ++an excellent tool for filtering those unwanted mails for me.) ++ ++@item @b{Ham folders:} ++ ++In my ham folders, I just hit @kbd{S x} ++(@code{gnus-summary-mark-as-spam}) whenever I see an unrecognized spam ++mail (false negative). On group exit, those messages are moved to ++@samp{training.spam}. ++@end itemize ++ ++@subsubheading Reporting spam articles in Gmane groups with @code{spam-report.el} ++ ++From Reiner Steib . ++ ++With following entry in @code{gnus-parameters}, @kbd{S x} ++(@code{gnus-summary-mark-as-spam}) marks articles in @code{gmane.*} ++groups as spam and reports the to Gmane at group exit: ++ ++@lisp ++ ("^gmane\\." ++ (spam-process (gnus-group-spam-exit-processor-report-gmane))) ++@end lisp ++ ++Additionally, I use @code{(setq spam-report-gmane-use-article-number nil)} ++because I don't read the groups directly from news.gmane.org, but ++through my local news server (leafnode). I.e. the article numbers are ++not the same as on news.gmane.org, thus @code{spam-report.el} has to check ++the @code{X-Report-Spam} header to find the correct number. ++ ++@node Spam Back Ends ++@subsection Spam Back Ends ++@cindex spam back ends ++ ++The spam package offers a variety of back ends for detecting spam. ++Each back end defines a set of methods for detecting spam ++(@pxref{Filtering Incoming Mail}, @pxref{Detecting Spam in Groups}), ++and a pair of spam and ham processors (@pxref{Spam and Ham ++Processors}). ++ ++@menu ++* Blacklists and Whitelists:: ++* BBDB Whitelists:: ++* Gmane Spam Reporting:: ++* Anti-spam Hashcash Payments:: ++* Blackholes:: ++* Regular Expressions Header Matching:: ++* Bogofilter:: ++* SpamAssassin back end:: ++* ifile spam filtering:: ++* Spam Statistics Filtering:: ++* SpamOracle:: ++@end menu ++ ++@node Blacklists and Whitelists ++@subsubsection Blacklists and Whitelists ++@cindex spam filtering ++@cindex whitelists, spam filtering ++@cindex blacklists, spam filtering ++@cindex spam ++ ++@defvar spam-use-blacklist ++ ++Set this variable to @code{t} if you want to use blacklists when ++splitting incoming mail. Messages whose senders are in the blacklist ++will be sent to the @code{spam-split-group}. This is an explicit ++filter, meaning that it acts only on mail senders @emph{declared} to ++be spammers. ++ ++@end defvar ++ ++@defvar spam-use-whitelist ++ ++Set this variable to @code{t} if you want to use whitelists when ++splitting incoming mail. Messages whose senders are not in the ++whitelist will be sent to the next spam-split rule. This is an ++explicit filter, meaning that unless someone is in the whitelist, their ++messages are not assumed to be spam or ham. ++ ++@end defvar ++ ++@defvar spam-use-whitelist-exclusive ++ ++Set this variable to @code{t} if you want to use whitelists as an ++implicit filter, meaning that every message will be considered spam ++unless the sender is in the whitelist. Use with care. ++ ++@end defvar ++ ++@defvar gnus-group-spam-exit-processor-blacklist ++ ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameters or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is ++added to a group's @code{spam-process} parameter, the senders of ++spam-marked articles will be added to the blacklist. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-spam-exit-processor-blacklist}, it is recommended ++that you use @code{(spam spam-use-blacklist)}. Everything will work ++the same way, we promise. ++ ++@end defvar ++ ++@defvar gnus-group-ham-exit-processor-whitelist ++ ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameters or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is ++added to a group's @code{spam-process} parameter, the senders of ++ham-marked articles in @emph{ham} groups will be added to the ++whitelist. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-ham-exit-processor-whitelist}, it is recommended ++that you use @code{(ham spam-use-whitelist)}. Everything will work ++the same way, we promise. ++ ++@end defvar ++ ++Blacklists are lists of regular expressions matching addresses you ++consider to be spam senders. For instance, to block mail from any ++sender at @samp{vmadmin.com}, you can put @samp{vmadmin.com} in your ++blacklist. You start out with an empty blacklist. Blacklist entries ++use the Emacs regular expression syntax. ++ ++Conversely, whitelists tell Gnus what addresses are considered ++legitimate. All messages from whitelisted addresses are considered ++non-spam. Also see @ref{BBDB Whitelists}. Whitelist entries use the ++Emacs regular expression syntax. ++ ++The blacklist and whitelist file locations can be customized with the ++@code{spam-directory} variable (@file{~/News/spam} by default), or ++the @code{spam-whitelist} and @code{spam-blacklist} variables ++directly. The whitelist and blacklist files will by default be in the ++@code{spam-directory} directory, named @file{whitelist} and ++@file{blacklist} respectively. ++ ++@node BBDB Whitelists ++@subsubsection BBDB Whitelists ++@cindex spam filtering ++@cindex BBDB whitelists, spam filtering ++@cindex BBDB, spam filtering ++@cindex spam ++ ++@defvar spam-use-BBDB ++ ++Analogous to @code{spam-use-whitelist} (@pxref{Blacklists and ++Whitelists}), but uses the BBDB as the source of whitelisted ++addresses, without regular expressions. You must have the BBDB loaded ++for @code{spam-use-BBDB} to work properly. Messages whose senders are ++not in the BBDB will be sent to the next spam-split rule. This is an ++explicit filter, meaning that unless someone is in the BBDB, their ++messages are not assumed to be spam or ham. ++ ++@end defvar ++ ++@defvar spam-use-BBDB-exclusive ++ ++Set this variable to @code{t} if you want to use the BBDB as an ++implicit filter, meaning that every message will be considered spam ++unless the sender is in the BBDB. Use with care. Only sender ++addresses in the BBDB will be allowed through; all others will be ++classified as spammers. ++ ++While @code{spam-use-BBDB-exclusive} @emph{can} be used as an alias ++for @code{spam-use-BBDB} as far as @code{spam.el} is concerned, it is ++@emph{not} a separate back end. If you set ++@code{spam-use-BBDB-exclusive} to t, @emph{all} your BBDB splitting ++will be exclusive. ++ ++@end defvar ++ ++@defvar gnus-group-ham-exit-processor-BBDB ++ ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameters or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is ++added to a group's @code{spam-process} parameter, the senders of ++ham-marked articles in @emph{ham} groups will be added to the ++BBDB. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-ham-exit-processor-BBDB}, it is recommended ++that you use @code{(ham spam-use-BBDB)}. Everything will work ++the same way, we promise. ++ ++@end defvar ++ ++@node Gmane Spam Reporting ++@subsubsection Gmane Spam Reporting ++@cindex spam reporting ++@cindex Gmane, spam reporting ++@cindex Gmane, spam reporting ++@cindex spam ++ ++@defvar gnus-group-spam-exit-processor-report-gmane ++ ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameters or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is ++added to a group's @code{spam-process} parameter, the spam-marked ++articles groups will be reported to the Gmane administrators via a ++HTTP request. ++ ++Gmane can be found at @uref{http://gmane.org}. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-spam-exit-processor-report-gmane}, it is recommended ++that you use @code{(spam spam-use-gmane)}. Everything will work the ++same way, we promise. ++ ++@end defvar ++ ++@defvar spam-report-gmane-use-article-number ++ ++This variable is @code{t} by default. Set it to @code{nil} if you are ++running your own news server, for instance, and the local article ++numbers don't correspond to the Gmane article numbers. When ++@code{spam-report-gmane-use-article-number} is @code{nil}, ++@code{spam-report.el} will fetch the number from the article headers. ++ ++@end defvar ++ ++@defvar spam-report-user-mail-address ++ ++Mail address exposed in the User-Agent spam reports to Gmane. It allows ++the Gmane administrators to contact you in case of misreports. The ++default is @code{user-mail-address}. ++ ++@end defvar ++ ++@node Anti-spam Hashcash Payments ++@subsubsection Anti-spam Hashcash Payments ++@cindex spam filtering ++@cindex hashcash, spam filtering ++@cindex spam ++ ++@defvar spam-use-hashcash ++ ++Similar to @code{spam-use-whitelist} (@pxref{Blacklists and ++Whitelists}), but uses hashcash tokens for whitelisting messages ++instead of the sender address. Messages without a hashcash payment ++token will be sent to the next spam-split rule. This is an explicit ++filter, meaning that unless a hashcash token is found, the messages ++are not assumed to be spam or ham. ++ ++@end defvar ++ ++@node Blackholes ++@subsubsection Blackholes ++@cindex spam filtering ++@cindex blackholes, spam filtering ++@cindex spam ++ ++@defvar spam-use-blackholes ++ ++This option is disabled by default. You can let Gnus consult the ++blackhole-type distributed spam processing systems (DCC, for instance) ++when you set this option. The variable @code{spam-blackhole-servers} ++holds the list of blackhole servers Gnus will consult. The current ++list is fairly comprehensive, but make sure to let us know if it ++contains outdated servers. ++ ++The blackhole check uses the @code{dig.el} package, but you can tell ++@code{spam.el} to use @code{dns.el} instead for better performance if ++you set @code{spam-use-dig} to @code{nil}. It is not recommended at ++this time to set @code{spam-use-dig} to @code{nil} despite the ++possible performance improvements, because some users may be unable to ++use it, but you can try it and see if it works for you. ++ ++@end defvar ++ ++@defvar spam-blackhole-servers ++ ++The list of servers to consult for blackhole checks. ++ ++@end defvar ++ ++@defvar spam-blackhole-good-server-regex ++ ++A regular expression for IPs that should not be checked against the ++blackhole server list. When set to @code{nil}, it has no effect. ++ ++@end defvar ++ ++@defvar spam-use-dig ++ ++Use the @code{dig.el} package instead of the @code{dns.el} package. ++The default setting of @code{t} is recommended. ++ ++@end defvar ++ ++Blackhole checks are done only on incoming mail. There is no spam or ++ham processor for blackholes. ++ ++@node Regular Expressions Header Matching ++@subsubsection Regular Expressions Header Matching ++@cindex spam filtering ++@cindex regular expressions header matching, spam filtering ++@cindex spam ++ ++@defvar spam-use-regex-headers ++ ++This option is disabled by default. You can let Gnus check the ++message headers against lists of regular expressions when you set this ++option. The variables @code{spam-regex-headers-spam} and ++@code{spam-regex-headers-ham} hold the list of regular expressions. ++Gnus will check against the message headers to determine if the ++message is spam or ham, respectively. ++ ++@end defvar ++ ++@defvar spam-regex-headers-spam ++ ++The list of regular expressions that, when matched in the headers of ++the message, positively identify it as spam. ++ ++@end defvar ++ ++@defvar spam-regex-headers-ham ++ ++The list of regular expressions that, when matched in the headers of ++the message, positively identify it as ham. ++ ++@end defvar ++ ++Regular expression header checks are done only on incoming mail. ++There is no specific spam or ham processor for regular expressions. ++ ++@node Bogofilter ++@subsubsection Bogofilter ++@cindex spam filtering ++@cindex bogofilter, spam filtering ++@cindex spam ++ ++@defvar spam-use-bogofilter ++ ++Set this variable if you want @code{spam-split} to use Eric Raymond's ++speedy Bogofilter. ++ ++With a minimum of care for associating the @samp{$} mark for spam ++articles only, Bogofilter training all gets fairly automatic. You ++should do this until you get a few hundreds of articles in each ++category, spam or not. The command @kbd{S t} in summary mode, either ++for debugging or for curiosity, shows the @emph{spamicity} score of ++the current article (between 0.0 and 1.0). ++ ++Bogofilter determines if a message is spam based on a specific ++threshold. That threshold can be customized, consult the Bogofilter ++documentation. ++ ++If the @code{bogofilter} executable is not in your path, Bogofilter ++processing will be turned off. ++ ++You should not enable this if you use @code{spam-use-bogofilter-headers}. ++ ++@end defvar ++ ++@table @kbd ++@item M s t ++@itemx S t ++@kindex M s t ++@kindex S t ++@findex spam-bogofilter-score ++Get the Bogofilter spamicity score (@code{spam-bogofilter-score}). ++@end table ++ ++@defvar spam-use-bogofilter-headers ++ ++Set this variable if you want @code{spam-split} to use Eric Raymond's ++speedy Bogofilter, looking only at the message headers. It works ++similarly to @code{spam-use-bogofilter}, but the @code{X-Bogosity} header ++must be in the message already. Normally you would do this with a ++procmail recipe or something similar; consult the Bogofilter ++installation documents for details. ++ ++You should not enable this if you use @code{spam-use-bogofilter}. ++ ++@end defvar ++ ++@defvar gnus-group-spam-exit-processor-bogofilter ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameters or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is ++added to a group's @code{spam-process} parameter, spam-marked articles ++will be added to the Bogofilter spam database. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-spam-exit-processor-bogofilter}, it is recommended ++that you use @code{(spam spam-use-bogofilter)}. Everything will work ++the same way, we promise. ++@end defvar ++ ++@defvar gnus-group-ham-exit-processor-bogofilter ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameters or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is ++added to a group's @code{spam-process} parameter, the ham-marked ++articles in @emph{ham} groups will be added to the Bogofilter database ++of non-spam messages. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-ham-exit-processor-bogofilter}, it is recommended ++that you use @code{(ham spam-use-bogofilter)}. Everything will work ++the same way, we promise. ++@end defvar ++ ++@defvar spam-bogofilter-database-directory ++ ++This is the directory where Bogofilter will store its databases. It ++is not specified by default, so Bogofilter will use its own default ++database directory. ++ ++@end defvar ++ ++The Bogofilter mail classifier is similar to @command{ifile} in intent and ++purpose. A ham and a spam processor are provided, plus the ++@code{spam-use-bogofilter} and @code{spam-use-bogofilter-headers} ++variables to indicate to spam-split that Bogofilter should either be ++used, or has already been used on the article. The 0.9.2.1 version of ++Bogofilter was used to test this functionality. ++ ++@node SpamAssassin back end ++@subsubsection SpamAssassin back end ++@cindex spam filtering ++@cindex spamassassin, spam filtering ++@cindex spam ++ ++@defvar spam-use-spamassassin ++ ++Set this variable if you want @code{spam-split} to use SpamAssassin. ++ ++SpamAssassin assigns a score to each article based on a set of rules ++and tests, including a Bayesian filter. The Bayesian filter can be ++trained by associating the @samp{$} mark for spam articles. The ++spam score can be viewed by using the command @kbd{S t} in summary ++mode. ++ ++If you set this variable, each article will be processed by ++SpamAssassin when @code{spam-split} is called. If your mail is ++preprocessed by SpamAssassin, and you want to just use the ++SpamAssassin headers, set @code{spam-use-spamassassin-headers} ++instead. ++ ++You should not enable this if you use ++@code{spam-use-spamassassin-headers}. ++ ++@end defvar ++ ++@defvar spam-use-spamassassin-headers ++ ++Set this variable if your mail is preprocessed by SpamAssassin and ++want @code{spam-split} to split based on the SpamAssassin headers. ++ ++You should not enable this if you use @code{spam-use-spamassassin}. ++ ++@end defvar ++ ++@defvar spam-spamassassin-program ++ ++This variable points to the SpamAssassin executable. If you have ++@code{spamd} running, you can set this variable to the @code{spamc} ++executable for faster processing. See the SpamAssassin documentation ++for more information on @code{spamd}/@code{spamc}. ++ ++@end defvar ++ ++SpamAssassin is a powerful and flexible spam filter that uses a wide ++variety of tests to identify spam. A ham and a spam processors are ++provided, plus the @code{spam-use-spamassassin} and ++@code{spam-use-spamassassin-headers} variables to indicate to ++spam-split that SpamAssassin should be either used, or has already ++been used on the article. The 2.63 version of SpamAssassin was used ++to test this functionality. ++ ++@node ifile spam filtering ++@subsubsection ifile spam filtering ++@cindex spam filtering ++@cindex ifile, spam filtering ++@cindex spam ++ ++@defvar spam-use-ifile ++ ++Enable this variable if you want @code{spam-split} to use @command{ifile}, a ++statistical analyzer similar to Bogofilter. ++ ++@end defvar ++ ++@defvar spam-ifile-all-categories ++ ++Enable this variable if you want @code{spam-use-ifile} to give you all ++the ifile categories, not just spam/non-spam. If you use this, make ++sure you train ifile as described in its documentation. ++ ++@end defvar ++ ++@defvar spam-ifile-spam-category ++ ++This is the category of spam messages as far as ifile is concerned. ++The actual string used is irrelevant, but you probably want to leave ++the default value of @samp{spam}. ++@end defvar ++ ++@defvar spam-ifile-database ++ ++This is the filename for the ifile database. It is not specified by ++default, so ifile will use its own default database name. ++ ++@end defvar ++ ++The ifile mail classifier is similar to Bogofilter in intent and ++purpose. A ham and a spam processor are provided, plus the ++@code{spam-use-ifile} variable to indicate to spam-split that ifile ++should be used. The 1.2.1 version of ifile was used to test this ++functionality. ++ ++@node Spam Statistics Filtering ++@subsubsection Spam Statistics Filtering ++@cindex spam filtering ++@cindex spam-stat, spam filtering ++@cindex spam-stat ++@cindex spam ++ ++This back end uses the Spam Statistics Emacs Lisp package to perform ++statistics-based filtering (@pxref{Spam Statistics Package}). Before ++using this, you may want to perform some additional steps to ++initialize your Spam Statistics dictionary. @xref{Creating a ++spam-stat dictionary}. ++ ++@defvar spam-use-stat ++ ++@end defvar ++ ++@defvar gnus-group-spam-exit-processor-stat ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameters or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is ++added to a group's @code{spam-process} parameter, the spam-marked ++articles will be added to the spam-stat database of spam messages. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-spam-exit-processor-stat}, it is recommended ++that you use @code{(spam spam-use-stat)}. Everything will work ++the same way, we promise. ++@end defvar ++ ++@defvar gnus-group-ham-exit-processor-stat ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameters or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is ++added to a group's @code{spam-process} parameter, the ham-marked ++articles in @emph{ham} groups will be added to the spam-stat database ++of non-spam messages. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-ham-exit-processor-stat}, it is recommended ++that you use @code{(ham spam-use-stat)}. Everything will work ++the same way, we promise. ++@end defvar ++ ++This enables @code{spam.el} to cooperate with @file{spam-stat.el}. ++@file{spam-stat.el} provides an internal (Lisp-only) spam database, ++which unlike ifile or Bogofilter does not require external programs. ++A spam and a ham processor, and the @code{spam-use-stat} variable for ++@code{spam-split} are provided. ++ ++@node SpamOracle ++@subsubsection Using SpamOracle with Gnus ++@cindex spam filtering ++@cindex SpamOracle ++@cindex spam ++ ++An easy way to filter out spam is to use SpamOracle. SpamOracle is an ++statistical mail filtering tool written by Xavier Leroy and needs to be ++installed separately. ++ ++There are several ways to use SpamOracle with Gnus. In all cases, your ++mail is piped through SpamOracle in its @emph{mark} mode. SpamOracle will ++then enter an @samp{X-Spam} header indicating whether it regards the ++mail as a spam mail or not. ++ ++One possibility is to run SpamOracle as a @code{:prescript} from the ++@xref{Mail Source Specifiers}, (@pxref{SpamAssassin}). This method has ++the advantage that the user can see the @emph{X-Spam} headers. ++ ++The easiest method is to make @file{spam.el} (@pxref{Spam Package}) ++call SpamOracle. ++ ++@vindex spam-use-spamoracle ++To enable SpamOracle usage by @code{spam.el}, set the variable ++@code{spam-use-spamoracle} to @code{t} and configure the ++@code{nnmail-split-fancy} or @code{nnimap-split-fancy}. @xref{Spam ++Package}. In this example the @samp{INBOX} of an nnimap server is ++filtered using SpamOracle. Mails recognized as spam mails will be ++moved to @code{spam-split-group}, @samp{Junk} in this case. Ham ++messages stay in @samp{INBOX}: ++ ++@example ++(setq spam-use-spamoracle t ++ spam-split-group "Junk" ++ nnimap-split-inbox '("INBOX") ++ nnimap-split-rule 'nnimap-split-fancy ++ nnimap-split-fancy '(| (: spam-split) "INBOX")) ++@end example ++ ++@defvar spam-use-spamoracle ++Set to @code{t} if you want Gnus to enable spam filtering using ++SpamOracle. ++@end defvar ++ ++@defvar spam-spamoracle-binary ++Gnus uses the SpamOracle binary called @file{spamoracle} found in the ++user's PATH. Using the variable @code{spam-spamoracle-binary}, this ++can be customized. ++@end defvar ++ ++@defvar spam-spamoracle-database ++By default, SpamOracle uses the file @file{~/.spamoracle.db} as a database to ++store its analysis. This is controlled by the variable ++@code{spam-spamoracle-database} which defaults to @code{nil}. That means ++the default SpamOracle database will be used. In case you want your ++database to live somewhere special, set ++@code{spam-spamoracle-database} to this path. ++@end defvar ++ ++SpamOracle employs a statistical algorithm to determine whether a ++message is spam or ham. In order to get good results, meaning few ++false hits or misses, SpamOracle needs training. SpamOracle learns ++the characteristics of your spam mails. Using the @emph{add} mode ++(training mode) one has to feed good (ham) and spam mails to ++SpamOracle. This can be done by pressing @kbd{|} in the Summary ++buffer and pipe the mail to a SpamOracle process or using ++@file{spam.el}'s spam- and ham-processors, which is much more ++convenient. For a detailed description of spam- and ham-processors, ++@xref{Spam Package}. ++ ++@defvar gnus-group-spam-exit-processor-spamoracle ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameter or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is added ++to a group's @code{spam-process} parameter, spam-marked articles will be ++sent to SpamOracle as spam samples. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-spam-exit-processor-spamoracle}, it is recommended ++that you use @code{(spam spam-use-spamoracle)}. Everything will work ++the same way, we promise. ++@end defvar ++ ++@defvar gnus-group-ham-exit-processor-spamoracle ++Add this symbol to a group's @code{spam-process} parameter by ++customizing the group parameter or the ++@code{gnus-spam-process-newsgroups} variable. When this symbol is added ++to a group's @code{spam-process} parameter, the ham-marked articles in ++@emph{ham} groups will be sent to the SpamOracle as samples of ham ++messages. ++ ++@emph{WARNING} ++ ++Instead of the obsolete ++@code{gnus-group-ham-exit-processor-spamoracle}, it is recommended ++that you use @code{(ham spam-use-spamoracle)}. Everything will work ++the same way, we promise. ++@end defvar ++ ++@emph{Example:} These are the Group Parameters of a group that has been ++classified as a ham group, meaning that it should only contain ham ++messages. ++@example ++ ((spam-contents gnus-group-spam-classification-ham) ++ (spam-process ((ham spam-use-spamoracle) ++ (spam spam-use-spamoracle)))) ++@end example ++For this group the @code{spam-use-spamoracle} is installed for both ++ham and spam processing. If the group contains spam message ++(e.g. because SpamOracle has not had enough sample messages yet) and ++the user marks some messages as spam messages, these messages will be ++processed by SpamOracle. The processor sends the messages to ++SpamOracle as new samples for spam. ++ ++@node Extending the Spam package ++@subsection Extending the Spam package ++@cindex spam filtering ++@cindex spam elisp package, extending ++@cindex extending the spam elisp package ++ ++Say you want to add a new back end called blackbox. For filtering ++incoming mail, provide the following: ++ ++@enumerate ++ ++@item ++Code ++ ++@lisp ++(defvar spam-use-blackbox nil ++ "True if blackbox should be used.") ++@end lisp ++ ++Write @code{spam-check-blackbox} if Blackbox can check incoming mail. ++ ++Write @code{spam-blackbox-register-routine} and ++@code{spam-blackbox-unregister-routine} using the bogofilter ++register/unregister routines as a start, or other restister/unregister ++routines more appropriate to Blackbox, if Blackbox can ++register/unregister spam and ham. ++ ++@item ++Functionality ++ ++The @code{spam-check-blackbox} function should return @samp{nil} or ++@code{spam-split-group}, observing the other conventions. See the ++existing @code{spam-check-*} functions for examples of what you can ++do, and stick to the template unless you fully understand the reasons ++why you aren't. ++ ++@end enumerate ++ ++For processing spam and ham messages, provide the following: ++ ++@enumerate ++ ++@item ++Code ++ ++Note you don't have to provide a spam or a ham processor. Only ++provide them if Blackbox supports spam or ham processing. ++ ++Also, ham and spam processors are being phased out as single ++variables. Instead the form @code{(spam spam-use-blackbox)} or ++@code{(ham spam-use-blackbox)} is favored. For now, spam/ham ++processor variables are still around but they won't be for long. ++ ++@lisp ++(defvar gnus-group-spam-exit-processor-blackbox "blackbox-spam" ++ "The Blackbox summary exit spam processor. ++Only applicable to spam groups.") ++ ++(defvar gnus-group-ham-exit-processor-blackbox "blackbox-ham" ++ "The whitelist summary exit ham processor. ++Only applicable to non-spam (unclassified and ham) groups.") ++ ++@end lisp ++ ++@item ++Gnus parameters ++ ++Add ++@lisp ++(const :tag "Spam: Blackbox" (spam spam-use-blackbox)) ++(const :tag "Ham: Blackbox" (ham spam-use-blackbox)) ++@end lisp ++to the @code{spam-process} group parameter in @code{gnus.el}. Make ++sure you do it twice, once for the parameter and once for the ++variable customization. ++ ++Add ++@lisp ++(variable-item spam-use-blackbox) ++@end lisp ++to the @code{spam-autodetect-methods} group parameter in ++@code{gnus.el} if Blackbox can check incoming mail for spam contents. ++ ++Finally, use the appropriate @code{spam-install-*-backend} function in ++@code{spam.el}. Here are the available functions. ++ ++ ++@enumerate ++ ++@item ++@code{spam-install-backend-alias} ++ ++This function will simply install an alias for a back end that does ++everything like the original back end. It is currently only used to ++make @code{spam-use-BBDB-exclusive} act like @code{spam-use-BBDB}. ++ ++@item ++@code{spam-install-nocheck-backend} ++ ++This function installs a back end that has no check function, but can ++register/unregister ham or spam. The @code{spam-use-gmane} back end is ++such a back end. ++ ++@item ++@code{spam-install-checkonly-backend} ++ ++This function will install a back end that can only check incoming mail ++for spam contents. It can't register or unregister messages. ++@code{spam-use-blackholes} and @code{spam-use-hashcash} are such ++back ends. ++ ++@item ++@code{spam-install-statistical-checkonly-backend} ++ ++This function installs a statistical back end (one which requires the ++full body of a message to check it) that can only check incoming mail ++for contents. @code{spam-use-regex-body} is such a filter. ++ ++@item ++@code{spam-install-statistical-backend} ++ ++This function install a statistical back end with incoming checks and ++registration/unregistration routines. @code{spam-use-bogofilter} is ++set up this way. ++ ++@item ++@code{spam-install-backend} ++ ++This is the most normal back end installation, where a back end that can ++check and register/unregister messages is set up without statistical ++abilities. The @code{spam-use-BBDB} is such a back end. ++ ++@item ++@code{spam-install-mover-backend} ++ ++Mover back ends are internal to @code{spam.el} and specifically move ++articles around when the summary is exited. You will very probably ++never install such a back end. ++@end enumerate ++ ++@end enumerate ++ ++@node Spam Statistics Package ++@subsection Spam Statistics Package ++@cindex Paul Graham ++@cindex Graham, Paul ++@cindex naive Bayesian spam filtering ++@cindex Bayesian spam filtering, naive ++@cindex spam filtering, naive Bayesian ++ ++Paul Graham has written an excellent essay about spam filtering using ++statistics: @uref{http://www.paulgraham.com/spam.html,A Plan for ++Spam}. In it he describes the inherent deficiency of rule-based ++filtering as used by SpamAssassin, for example: Somebody has to write ++the rules, and everybody else has to install these rules. You are ++always late. It would be much better, he argues, to filter mail based ++on whether it somehow resembles spam or non-spam. One way to measure ++this is word distribution. He then goes on to describe a solution ++that checks whether a new mail resembles any of your other spam mails ++or not. ++ ++The basic idea is this: Create a two collections of your mail, one ++with spam, one with non-spam. Count how often each word appears in ++either collection, weight this by the total number of mails in the ++collections, and store this information in a dictionary. For every ++word in a new mail, determine its probability to belong to a spam or a ++non-spam mail. Use the 15 most conspicuous words, compute the total ++probability of the mail being spam. If this probability is higher ++than a certain threshold, the mail is considered to be spam. ++ ++The Spam Statistics package adds support to Gnus for this kind of ++filtering. It can be used as one of the back ends of the Spam package ++(@pxref{Spam Package}), or by itself. ++ ++Before using the Spam Statistics package, you need to set it up. ++First, you need two collections of your mail, one with spam, one with ++non-spam. Then you need to create a dictionary using these two ++collections, and save it. And last but not least, you need to use ++this dictionary in your fancy mail splitting rules. ++ ++@menu ++* Creating a spam-stat dictionary:: ++* Splitting mail using spam-stat:: ++* Low-level interface to the spam-stat dictionary:: ++@end menu ++ ++@node Creating a spam-stat dictionary ++@subsubsection Creating a spam-stat dictionary ++ ++Before you can begin to filter spam based on statistics, you must ++create these statistics based on two mail collections, one with spam, ++one with non-spam. These statistics are then stored in a dictionary ++for later use. In order for these statistics to be meaningful, you ++need several hundred emails in both collections. ++ ++Gnus currently supports only the nnml back end for automated dictionary ++creation. The nnml back end stores all mails in a directory, one file ++per mail. Use the following: ++ ++@defun spam-stat-process-spam-directory ++Create spam statistics for every file in this directory. Every file ++is treated as one spam mail. ++@end defun ++ ++@defun spam-stat-process-non-spam-directory ++Create non-spam statistics for every file in this directory. Every ++file is treated as one non-spam mail. ++@end defun ++ ++Usually you would call @code{spam-stat-process-spam-directory} on a ++directory such as @file{~/Mail/mail/spam} (this usually corresponds to ++the group @samp{nnml:mail.spam}), and you would call ++@code{spam-stat-process-non-spam-directory} on a directory such as ++@file{~/Mail/mail/misc} (this usually corresponds to the group ++@samp{nnml:mail.misc}). ++ ++When you are using @acronym{IMAP}, you won't have the mails available ++locally, so that will not work. One solution is to use the Gnus Agent ++to cache the articles. Then you can use directories such as ++@file{"~/News/agent/nnimap/mail.yourisp.com/personal_spam"} for ++@code{spam-stat-process-spam-directory}. @xref{Agent as Cache}. ++ ++@defvar spam-stat ++This variable holds the hash-table with all the statistics---the ++dictionary we have been talking about. For every word in either ++collection, this hash-table stores a vector describing how often the ++word appeared in spam and often it appeared in non-spam mails. ++@end defvar ++ ++If you want to regenerate the statistics from scratch, you need to ++reset the dictionary. ++ ++@defun spam-stat-reset ++Reset the @code{spam-stat} hash-table, deleting all the statistics. ++@end defun ++ ++When you are done, you must save the dictionary. The dictionary may ++be rather large. If you will not update the dictionary incrementally ++(instead, you will recreate it once a month, for example), then you ++can reduce the size of the dictionary by deleting all words that did ++not appear often enough or that do not clearly belong to only spam or ++only non-spam mails. ++ ++@defun spam-stat-reduce-size ++Reduce the size of the dictionary. Use this only if you do not want ++to update the dictionary incrementally. ++@end defun ++ ++@defun spam-stat-save ++Save the dictionary. ++@end defun ++ ++@defvar spam-stat-file ++The filename used to store the dictionary. This defaults to ++@file{~/.spam-stat.el}. ++@end defvar ++ ++@node Splitting mail using spam-stat ++@subsubsection Splitting mail using spam-stat ++ ++This section describes how to use the Spam statistics ++@emph{independently} of the @xref{Spam Package}. ++ ++First, add the following to your @file{~/.gnus.el} file: ++ ++@lisp ++(require 'spam-stat) ++(spam-stat-load) ++@end lisp ++ ++This will load the necessary Gnus code, and the dictionary you ++created. ++ ++Next, you need to adapt your fancy splitting rules: You need to ++determine how to use @code{spam-stat}. The following examples are for ++the nnml back end. Using the nnimap back end works just as well. Just ++use @code{nnimap-split-fancy} instead of @code{nnmail-split-fancy}. ++ ++In the simplest case, you only have two groups, @samp{mail.misc} and ++@samp{mail.spam}. The following expression says that mail is either ++spam or it should go into @samp{mail.misc}. If it is spam, then ++@code{spam-stat-split-fancy} will return @samp{mail.spam}. ++ ++@lisp ++(setq nnmail-split-fancy ++ `(| (: spam-stat-split-fancy) ++ "mail.misc")) ++@end lisp ++ ++@defvar spam-stat-split-fancy-spam-group ++The group to use for spam. Default is @samp{mail.spam}. ++@end defvar ++ ++If you also filter mail with specific subjects into other groups, use ++the following expression. Only mails not matching the regular ++expression are considered potential spam. ++ ++@lisp ++(setq nnmail-split-fancy ++ `(| ("Subject" "\\bspam-stat\\b" "mail.emacs") ++ (: spam-stat-split-fancy) ++ "mail.misc")) ++@end lisp ++ ++If you want to filter for spam first, then you must be careful when ++creating the dictionary. Note that @code{spam-stat-split-fancy} must ++consider both mails in @samp{mail.emacs} and in @samp{mail.misc} as ++non-spam, therefore both should be in your collection of non-spam ++mails, when creating the dictionary! ++ ++@lisp ++(setq nnmail-split-fancy ++ `(| (: spam-stat-split-fancy) ++ ("Subject" "\\bspam-stat\\b" "mail.emacs") ++ "mail.misc")) ++@end lisp ++ ++You can combine this with traditional filtering. Here, we move all ++HTML-only mails into the @samp{mail.spam.filtered} group. Note that since ++@code{spam-stat-split-fancy} will never see them, the mails in ++@samp{mail.spam.filtered} should be neither in your collection of spam mails, ++nor in your collection of non-spam mails, when creating the ++dictionary! ++ ++@lisp ++(setq nnmail-split-fancy ++ `(| ("Content-Type" "text/html" "mail.spam.filtered") ++ (: spam-stat-split-fancy) ++ ("Subject" "\\bspam-stat\\b" "mail.emacs") ++ "mail.misc")) ++@end lisp ++ ++ ++@node Low-level interface to the spam-stat dictionary ++@subsubsection Low-level interface to the spam-stat dictionary ++ ++The main interface to using @code{spam-stat}, are the following functions: ++ ++@defun spam-stat-buffer-is-spam ++Called in a buffer, that buffer is considered to be a new spam mail. ++Use this for new mail that has not been processed before. ++@end defun ++ ++@defun spam-stat-buffer-is-no-spam ++Called in a buffer, that buffer is considered to be a new non-spam ++mail. Use this for new mail that has not been processed before. ++@end defun ++ ++@defun spam-stat-buffer-change-to-spam ++Called in a buffer, that buffer is no longer considered to be normal ++mail but spam. Use this to change the status of a mail that has ++already been processed as non-spam. ++@end defun ++ ++@defun spam-stat-buffer-change-to-non-spam ++Called in a buffer, that buffer is no longer considered to be spam but ++normal mail. Use this to change the status of a mail that has already ++been processed as spam. ++@end defun ++ ++@defun spam-stat-save ++Save the hash table to the file. The filename used is stored in the ++variable @code{spam-stat-file}. ++@end defun ++ ++@defun spam-stat-load ++Load the hash table from a file. The filename used is stored in the ++variable @code{spam-stat-file}. ++@end defun ++ ++@defun spam-stat-score-word ++Return the spam score for a word. ++@end defun ++ ++@defun spam-stat-score-buffer ++Return the spam score for a buffer. ++@end defun ++ ++@defun spam-stat-split-fancy ++Use this function for fancy mail splitting. Add the rule @samp{(: ++spam-stat-split-fancy)} to @code{nnmail-split-fancy} ++@end defun ++ ++Make sure you load the dictionary before using it. This requires the ++following in your @file{~/.gnus.el} file: ++ ++@lisp ++(require 'spam-stat) ++(spam-stat-load) ++@end lisp ++ ++Typical test will involve calls to the following functions: ++ ++@smallexample ++Reset: (setq spam-stat (make-hash-table :test 'equal)) ++Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") ++Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") ++Save table: (spam-stat-save) ++File size: (nth 7 (file-attributes spam-stat-file)) ++Number of words: (hash-table-count spam-stat) ++Test spam: (spam-stat-test-directory "~/Mail/mail/spam") ++Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") ++Reduce table size: (spam-stat-reduce-size) ++Save table: (spam-stat-save) ++File size: (nth 7 (file-attributes spam-stat-file)) ++Number of words: (hash-table-count spam-stat) ++Test spam: (spam-stat-test-directory "~/Mail/mail/spam") ++Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") ++@end smallexample ++ ++Here is how you would create your dictionary: ++ ++@smallexample ++Reset: (setq spam-stat (make-hash-table :test 'equal)) ++Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") ++Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") ++Repeat for any other non-spam group you need... ++Reduce table size: (spam-stat-reduce-size) ++Save table: (spam-stat-save) ++@end smallexample ++ ++@node The Gnus Registry ++@section The Gnus Registry ++@cindex registry ++@cindex split ++@cindex track ++ ++The Gnus registry is a package that tracks messages by their ++Message-ID across all backends. This allows Gnus users to do several ++cool things, be the envy of the locals, get free haircuts, and be ++experts on world issues. Well, maybe not all of those, but the ++features are pretty cool. ++ ++Although they will be explained in detail shortly, here's a quick list ++of said features in case your attention span is... never mind. ++ ++@enumerate ++@item ++Split messages to their parent ++ ++This keeps discussions in the same group. You can use the subject and ++the sender in addition to the Message-ID. Several strategies are ++available. ++ ++@item ++Store custom flags and keywords ++ ++The registry can store custom flags and keywords for a message. For ++instance, you can mark a message ``To-Do'' this way and the flag will ++persist whether the message is in the nnimap, nnml, nnmaildir, ++etc. backends. ++ ++@item ++Store arbitrary data ++ ++Through a simple ELisp API, the registry can remember any data for a ++message. A built-in inverse map, when activated, allows quick lookups ++of all messages matching a particular set of criteria. ++@end enumerate ++ ++@menu ++* Setup:: ++* Fancy splitting to parent:: ++* Store custom flags and keywords:: ++* Store arbitrary data:: ++@end menu ++ ++@node Setup ++@subsection Setup ++ ++Fortunately, setting up the Gnus registry is pretty easy: ++ ++@lisp ++(setq gnus-registry-max-entries 2500 ++ gnus-registry-use-long-group-names t) ++ ++(gnus-registry-initialize) ++@end lisp ++ ++This adds registry saves to Gnus newsrc saves (which happen on exit ++and when you press @kbd{s} from the @code{*Group*} buffer. It also ++adds registry calls to article actions in Gnus (copy, move, etc.) so ++it's not easy to undo the initialization. See ++@code{gnus-registry-initialize} for the gory details. ++ ++Here are other settings used by the author of the registry (understand ++what they do before you copy them blindly). ++ ++@lisp ++(setq ++ gnus-registry-split-strategy 'majority ++ gnus-registry-ignored-groups '(("nntp" t) ++ ("nnrss" t) ++ ("spam" t) ++ ("train" t)) ++ gnus-registry-max-entries 500000 ++ gnus-registry-use-long-group-names t ++ gnus-registry-track-extra '(sender subject)) ++@end lisp ++ ++They say: keep a lot of messages around, use long group names, track ++messages by sender and subject (not just parent Message-ID), and when ++the registry splits incoming mail, use a majority rule to decide where ++messages should go if there's more than one possibility. In addition, ++the registry should ignore messages in groups that match ``nntp'', ++``nnrss'', ``spam'', or ``train.'' ++ ++You are doubtless impressed by all this, but you ask: ``I am a Gnus ++user, I customize to live. Give me more.'' Here you go, these are ++the general settings. ++ ++@defvar gnus-registry-unfollowed-groups ++The groups that will not be followed by ++@code{gnus-registry-split-fancy-with-parent}. They will still be ++remembered by the registry. This is a list of regular expressions. ++@end defvar ++ ++@defvar gnus-registry-ignored-groups ++The groups that will not be remembered by the registry. This is a ++list of regular expressions, also available through Group/Topic ++customization (so you can ignore or keep a specific group or a whole ++topic). ++@end defvar ++ ++@defvar gnus-registry-use-long-group-names ++Whether the registry will use long group names. It's recommended to ++set this to @code{t}, although everything works if you don't. Future ++functionality will require it. ++@end defvar ++ ++@defvar gnus-registry-max-entries ++The number (an integer or @code{nil} for unlimited) of entries the ++registry will keep. ++@end defvar ++ ++@defvar gnus-registry-cache-file ++The file where the registry will be stored between Gnus sessions. ++@end defvar ++ ++@node Fancy splitting to parent ++@subsection Fancy splitting to parent ++ ++Simply put, this lets you put followup e-mail where it belongs. ++ ++Every message has a Message-ID, which is unique, and the registry ++remembers it. When the message is moved or copied, the registry will ++notice this and offer the new group as a choice to the splitting ++strategy. ++ ++When a followup is made, usually it mentions the original message's ++Message-ID in the headers. The registry knows this and uses that ++mention to find the group where the original message lives. You only ++have to put a rule like this: ++ ++@lisp ++(setq nnimap-my-split-fancy '(| ++ ++ ;; split to parent: you need this ++ (: gnus-registry-split-fancy-with-parent) ++ ++ ;; other rules, as an example ++ (: spam-split) ++ ;; default mailbox ++ "mail") ++@end lisp ++ ++in your fancy split setup. In addition, you may want to customize the ++following variables. ++ ++@defvar gnus-registry-track-extra ++This is a list of symbols, so it's best to change it from the ++Customize interface. By default it's @code{nil}, but you may want to ++track @code{subject} and @code{sender} as well when splitting by parent. ++It may work for you. It can be annoying if your mail flow is large and ++people don't stick to the same groups. ++@end defvar ++ ++@defvar gnus-registry-split-strategy ++This is a symbol, so it's best to change it from the Customize ++interface. By default it's @code{nil}, but you may want to set it to ++@code{majority} or @code{first} to split by sender or subject based on ++the majority of matches or on the first found. ++@end defvar ++ ++@node Store custom flags and keywords ++@subsection Store custom flags and keywords ++ ++The registry lets you set custom flags and keywords per message. You ++can use the Gnus->Registry Marks menu or the @kbd{M M x} keyboard ++shortcuts, where @code{x} is the first letter of the mark's name. ++ ++@defvar gnus-registry-marks ++The custom marks that the registry can use. You can modify the ++default list, if you like. If you do, you'll have to exit Emacs ++before they take effect (you can also unload the registry and reload ++it or evaluate the specific macros you'll need, but you probably don't ++want to bother). Use the Customize interface to modify the list. ++ ++By default this list has the @code{Important}, @code{Work}, ++@code{Personal}, @code{To-Do}, and @code{Later} marks. They all have ++keyboard shortcuts like @kbd{M M i} for Important, using the first ++letter. ++@end defvar ++ ++@defun gnus-registry-mark-article ++Call this function to mark an article with a custom registry mark. It ++will offer the available marks for completion. ++@end defun ++ ++@node Store arbitrary data ++@subsection Store arbitrary data ++ ++The registry has a simple API that uses a Message-ID as the key to ++store arbitrary data (as long as it can be converted to a list for ++storage). ++ ++@defun gnus-registry-store-extra-entry (id key value) ++Store @code{value} in the extra data key @code{key} for message ++@code{id}. ++@end defun ++ ++@defun gnus-registry-delete-extra-entry (id key) ++Delete the extra data key @code{key} for message @code{id}. ++@end defun ++ ++@defun gnus-registry-fetch-extra (id key) ++Get the extra data key @code{key} for message @code{id}. ++@end defun ++ ++@defvar gnus-registry-extra-entries-precious ++If any extra entries are precious, their presence will make the ++registry keep the whole entry forever, even if there are no groups for ++the Message-ID and if the size limit of the registry is reached. By ++default this is just @code{(marks)} so the custom registry marks are ++precious. ++@end defvar ++ ++@node Other modes ++@section Interaction with other modes ++ ++@subsection Dired ++@cindex dired ++ ++@code{gnus-dired-minor-mode} provides some useful functions for dired ++buffers. It is enabled with ++@lisp ++(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode) ++@end lisp ++ ++@table @kbd ++@item C-c C-m C-a ++@findex gnus-dired-attach ++@cindex attachments, selection via dired ++Send dired's marked files as an attachment (@code{gnus-dired-attach}). ++You will be prompted for a message buffer. ++ ++@item C-c C-m C-l ++@findex gnus-dired-find-file-mailcap ++Visit a file according to the appropriate mailcap entry ++(@code{gnus-dired-find-file-mailcap}). With prefix, open file in a new ++buffer. ++ ++@item C-c C-m C-p ++@findex gnus-dired-print ++Print file according to the mailcap entry (@code{gnus-dired-print}). If ++there is no print command, print in a PostScript image. ++@end table ++ ++@node Various Various ++@section Various Various ++@cindex mode lines ++@cindex highlights ++ ++@table @code ++ ++@item gnus-home-directory ++@vindex gnus-home-directory ++All Gnus file and directory variables will be initialized from this ++variable, which defaults to @file{~/}. ++ ++@item gnus-directory ++@vindex gnus-directory ++Most Gnus storage file and directory variables will be initialized from ++this variable, which defaults to the @env{SAVEDIR} environment ++variable, or @file{~/News/} if that variable isn't set. ++ ++Note that Gnus is mostly loaded when the @file{~/.gnus.el} file is read. ++This means that other directory variables that are initialized from this ++variable won't be set properly if you set this variable in ++@file{~/.gnus.el}. Set this variable in @file{.emacs} instead. ++ ++@item gnus-default-directory ++@vindex gnus-default-directory ++Not related to the above variable at all---this variable says what the ++default directory of all Gnus buffers should be. If you issue commands ++like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's ++default directory. If this variable is @code{nil} (which is the ++default), the default directory will be the default directory of the ++buffer you were in when you started Gnus. ++ ++@item gnus-verbose ++@vindex gnus-verbose ++This variable is an integer between zero and ten. The higher the value, ++the more messages will be displayed. If this variable is zero, Gnus ++will never flash any messages, if it is seven (which is the default), ++most important messages will be shown, and if it is ten, Gnus won't ever ++shut up, but will flash so many messages it will make your head swim. ++ ++@item gnus-verbose-backends ++@vindex gnus-verbose-backends ++This variable works the same way as @code{gnus-verbose}, but it applies ++to the Gnus back ends instead of Gnus proper. ++ ++@item gnus-add-timestamp-to-message ++@vindex gnus-add-timestamp-to-message ++This variable controls whether to add timestamps to messages that are ++controlled by @code{gnus-verbose} and @code{gnus-verbose-backends} and ++are issued. The default value is @code{nil} which means never to add ++timestamp. If it is @code{log}, add timestamps to only the messages ++that go into the @samp{*Messages*} buffer (in XEmacs, it is the ++@w{@samp{ *Message-Log*}} buffer). If it is neither @code{nil} nor ++@code{log}, add timestamps not only to log messages but also to the ones ++displayed in the echo area. ++ ++@item nnheader-max-head-length ++@vindex nnheader-max-head-length ++When the back ends read straight heads of articles, they all try to read ++as little as possible. This variable (default 8192) specifies ++the absolute max length the back ends will try to read before giving up ++on finding a separator line between the head and the body. If this ++variable is @code{nil}, there is no upper read bound. If it is ++@code{t}, the back ends won't try to read the articles piece by piece, ++but read the entire articles. This makes sense with some versions of ++@code{ange-ftp} or @code{efs}. ++ ++@item nnheader-head-chop-length ++@vindex nnheader-head-chop-length ++This variable (default 2048) says how big a piece of each article to ++read when doing the operation described above. ++ ++@item nnheader-file-name-translation-alist ++@vindex nnheader-file-name-translation-alist ++@cindex file names ++@cindex invalid characters in file names ++@cindex characters in file names ++This is an alist that says how to translate characters in file names. ++For instance, if @samp{:} is invalid as a file character in file names ++on your system (you OS/2 user you), you could say something like: ++ ++@lisp ++@group ++(setq nnheader-file-name-translation-alist ++ '((?: . ?_))) ++@end group ++@end lisp ++ ++In fact, this is the default value for this variable on OS/2 and MS ++Windows (phooey) systems. ++ ++@item gnus-hidden-properties ++@vindex gnus-hidden-properties ++This is a list of properties to use to hide ``invisible'' text. It is ++@code{(invisible t intangible t)} by default on most systems, which ++makes invisible text invisible and intangible. ++ ++@item gnus-parse-headers-hook ++@vindex gnus-parse-headers-hook ++A hook called before parsing headers. It can be used, for instance, to ++gather statistics on the headers fetched, or perhaps you'd like to prune ++some headers. I don't see why you'd want that, though. ++ ++@item gnus-shell-command-separator ++@vindex gnus-shell-command-separator ++String used to separate two shell commands. The default is @samp{;}. ++ ++@item gnus-invalid-group-regexp ++@vindex gnus-invalid-group-regexp ++ ++Regexp to match ``invalid'' group names when querying user for a group ++name. The default value catches some @strong{really} invalid group ++names who could possibly mess up Gnus internally (like allowing ++@samp{:} in a group name, which is normally used to delimit method and ++group). ++ ++@acronym{IMAP} users might want to allow @samp{/} in group names though. ++ ++ ++@end table ++ ++@node The End ++@chapter The End ++ ++Well, that's the manual---you can get on with your life now. Keep in ++touch. Say hello to your cats from me. ++ ++My @strong{ghod}---I just can't stand goodbyes. Sniffle. ++ ++Ol' Charles Reznikoff said it pretty well, so I leave the floor to him: ++ ++@quotation ++@strong{Te Deum} ++ ++@sp 1 ++Not because of victories @* ++I sing,@* ++having none,@* ++but for the common sunshine,@* ++the breeze,@* ++the largess of the spring. ++ ++@sp 1 ++Not for victory@* ++but for the day's work done@* ++as well as I was able;@* ++not for a seat upon the dais@* ++but at the common table.@* ++@end quotation ++ ++ ++@node Appendices ++@chapter Appendices ++ ++@menu ++* XEmacs:: Requirements for installing under XEmacs. ++* History:: How Gnus got where it is today. ++* On Writing Manuals:: Why this is not a beginner's guide. ++* Terminology:: We use really difficult, like, words here. ++* Customization:: Tailoring Gnus to your needs. ++* Troubleshooting:: What you might try if things do not work. ++* Gnus Reference Guide:: Rilly, rilly technical stuff. ++* Emacs for Heathens:: A short introduction to Emacsian terms. ++* Frequently Asked Questions:: The Gnus FAQ ++@end menu ++ ++ ++@node XEmacs ++@section XEmacs ++@cindex XEmacs ++@cindex installing under XEmacs ++ ++XEmacs is distributed as a collection of packages. You should install ++whatever packages the Gnus XEmacs package requires. The current ++requirements are @samp{gnus}, @samp{mail-lib}, @samp{xemacs-base}, ++@samp{eterm}, @samp{sh-script}, @samp{net-utils}, @samp{os-utils}, ++@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{W3}, ++@samp{pgg}, @samp{mailcrypt}, @samp{ecrypto}, and @samp{sasl}. ++ ++ ++@node History ++@section History ++ ++@cindex history ++@sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in ++'94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus. ++ ++If you want to investigate the person responsible for this outrage, ++you can point your (feh!) web browser to ++@uref{http://quimby.gnus.org/}. This is also the primary ++distribution point for the new and spiffy versions of Gnus, and is ++known as The Site That Destroys Newsrcs And Drives People Mad. ++ ++During the first extended alpha period of development, the new Gnus was ++called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for ++@dfn{ding is not Gnus}, which is a total and utter lie, but who cares? ++(Besides, the ``Gnus'' in this abbreviation should probably be ++pronounced ``news'' as @sc{Umeda} intended, which makes it a more ++appropriate name, don't you think?) ++ ++In any case, after spending all that energy on coming up with a new and ++spunky name, we decided that the name was @emph{too} spunky, so we ++renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs. ++``@sc{gnus}''. New vs. old. ++ ++@menu ++* Gnus Versions:: What Gnus versions have been released. ++* Other Gnus Versions:: Other Gnus versions that also have been released. ++* Why?:: What's the point of Gnus? ++* Compatibility:: Just how compatible is Gnus with @sc{gnus}? ++* Conformity:: Gnus tries to conform to all standards. ++* Emacsen:: Gnus can be run on a few modern Emacsen. ++* Gnus Development:: How Gnus is developed. ++* Contributors:: Oodles of people. ++* New Features:: Pointers to some of the new stuff in Gnus. ++@end menu ++ ++ ++@node Gnus Versions ++@subsection Gnus Versions ++@cindex ding Gnus ++@cindex September Gnus ++@cindex Red Gnus ++@cindex Quassia Gnus ++@cindex Pterodactyl Gnus ++@cindex Oort Gnus ++@cindex No Gnus ++@cindex Gnus versions ++ ++The first ``proper'' release of Gnus 5 was done in November 1995 when it ++was included in the Emacs 19.30 distribution (132 (ding) Gnus releases ++plus 15 Gnus 5.0 releases). ++ ++In May 1996 the next Gnus generation (aka. ``September Gnus'' (after 99 ++releases)) was released under the name ``Gnus 5.2'' (40 releases). ++ ++On July 28th 1996 work on Red Gnus was begun, and it was released on ++January 25th 1997 (after 84 releases) as ``Gnus 5.4'' (67 releases). ++ ++On September 13th 1997, Quassia Gnus was started and lasted 37 releases. ++It was released as ``Gnus 5.6'' on March 8th 1998 (46 releases). ++ ++Gnus 5.6 begat Pterodactyl Gnus on August 29th 1998 and was released as ++``Gnus 5.8'' (after 99 releases and a CVS repository) on December 3rd ++1999. ++ ++On the 26th of October 2000, Oort Gnus was begun and was released as ++Gnus 5.10 on May 1st 2003 (24 releases). ++ ++On the January 4th 2004, No Gnus was begun. ++ ++If you happen upon a version of Gnus that has a prefixed name -- ++``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'', ++``Pterodactyl Gnus'', ``Oort Gnus'', ``No Gnus'' -- don't panic. ++Don't let it know that you're frightened. Back away. Slowly. Whatever ++you do, don't run. Walk away, calmly, until you're out of its reach. ++Find a proper released version of Gnus and snuggle up to that instead. ++ ++ ++@node Other Gnus Versions ++@subsection Other Gnus Versions ++@cindex Semi-gnus ++ ++In addition to the versions of Gnus which have had their releases ++coordinated by Lars, one major development has been Semi-gnus from ++Japan. It's based on a library called @acronym{SEMI}, which provides ++@acronym{MIME} capabilities. ++ ++These Gnusae are based mainly on Gnus 5.6 and Pterodactyl Gnus. ++Collectively, they are called ``Semi-gnus'', and different strains are ++called T-gnus, ET-gnus, Nana-gnus and Chaos. These provide powerful ++@acronym{MIME} and multilingualization things, especially important for ++Japanese users. ++ ++ ++@node Why? ++@subsection Why? ++ ++What's the point of Gnus? ++ ++I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep'' ++newsreader, that lets you do anything you can think of. That was my ++original motivation, but while working on Gnus, it has become clear to ++me that this generation of newsreaders really belong in the stone age. ++Newsreaders haven't developed much since the infancy of the net. If the ++volume continues to rise with the current rate of increase, all current ++newsreaders will be pretty much useless. How do you deal with ++newsgroups that have thousands of new articles each day? How do you ++keep track of millions of people who post? ++ ++Gnus offers no real solutions to these questions, but I would very much ++like to see Gnus being used as a testing ground for new methods of ++reading and fetching news. Expanding on @sc{Umeda}-san's wise decision ++to separate the newsreader from the back ends, Gnus now offers a simple ++interface for anybody who wants to write new back ends for fetching mail ++and news from different sources. I have added hooks for customizations ++everywhere I could imagine it being useful. By doing so, I'm inviting ++every one of you to explore and invent. ++ ++May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and ++@kbd{C-u 100 M-x all-hail-xemacs}. ++ ++ ++@node Compatibility ++@subsection Compatibility ++ ++@cindex compatibility ++Gnus was designed to be fully compatible with @sc{gnus}. Almost all key ++bindings have been kept. More key bindings have been added, of course, ++but only in one or two obscure cases have old bindings been changed. ++ ++Our motto is: ++@quotation ++@cartouche ++@center In a cloud bones of steel. ++@end cartouche ++@end quotation ++ ++All commands have kept their names. Some internal functions have changed ++their names. ++ ++The @code{gnus-uu} package has changed drastically. @xref{Decoding ++Articles}. ++ ++One major compatibility question is the presence of several summary ++buffers. All variables relevant while reading a group are ++buffer-local to the summary buffer they belong in. Although many ++important variables have their values copied into their global ++counterparts whenever a command is executed in the summary buffer, this ++change might lead to incorrect values being used unless you are careful. ++ ++All code that relies on knowledge of @sc{gnus} internals will probably ++fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or ++changing it in any way, as a matter of fact) is strictly verboten. Gnus ++maintains a hash table that points to the entries in this alist (which ++speeds up many functions), and changing the alist directly will lead to ++peculiar results. ++ ++@cindex hilit19 ++@cindex highlighting ++Old hilit19 code does not work at all. In fact, you should probably ++remove all hilit code from all Gnus hooks ++(@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}). ++Gnus provides various integrated functions for highlighting. These are ++faster and more accurate. To make life easier for everybody, Gnus will ++by default remove all hilit calls from all hilit hooks. Uncleanliness! ++Away! ++ ++Packages like @code{expire-kill} will no longer work. As a matter of ++fact, you should probably remove all old @sc{gnus} packages (and other ++code) when you start using Gnus. More likely than not, Gnus already ++does what you have written code to make @sc{gnus} do. (Snicker.) ++ ++Even though old methods of doing things are still supported, only the ++new methods are documented in this manual. If you detect a new method of ++doing something while reading this manual, that does not mean you have ++to stop doing it the old way. ++ ++Gnus understands all @sc{gnus} startup files. ++ ++@kindex M-x gnus-bug ++@findex gnus-bug ++@cindex reporting bugs ++@cindex bugs ++Overall, a casual user who hasn't written much code that depends on ++@sc{gnus} internals should suffer no problems. If problems occur, ++please let me know by issuing that magic command @kbd{M-x gnus-bug}. ++ ++@vindex gnus-bug-create-help-buffer ++If you are in the habit of sending bug reports @emph{very} often, you ++may find the helpful help buffer annoying after a while. If so, set ++@code{gnus-bug-create-help-buffer} to @code{nil} to avoid having it pop ++up at you. ++ ++ ++@node Conformity ++@subsection Conformity ++ ++No rebels without a clue here, ma'am. We conform to all standards known ++to (wo)man. Except for those standards and/or conventions we disagree ++with, of course. ++ ++@table @strong ++ ++@item RFC (2)822 ++@cindex RFC 822 ++@cindex RFC 2822 ++There are no known breaches of this standard. ++ ++@item RFC 1036 ++@cindex RFC 1036 ++There are no known breaches of this standard, either. ++ ++@item Son-of-RFC 1036 ++@cindex Son-of-RFC 1036 ++We do have some breaches to this one. ++ ++@table @emph ++ ++@item X-Newsreader ++@itemx User-Agent ++These are considered to be ``vanity headers'', while I consider them ++to be consumer information. After seeing so many badly formatted ++articles coming from @code{tin} and @code{Netscape} I know not to use ++either of those for posting articles. I would not have known that if ++it wasn't for the @code{X-Newsreader} header. ++@end table ++ ++@item USEFOR ++@cindex USEFOR ++USEFOR is an IETF working group writing a successor to RFC 1036, based ++on Son-of-RFC 1036. They have produced a number of drafts proposing ++various changes to the format of news articles. The Gnus towers will ++look into implementing the changes when the draft is accepted as an RFC. ++ ++@item MIME - RFC 2045-2049 etc ++@cindex @acronym{MIME} ++All the various @acronym{MIME} RFCs are supported. ++ ++@item Disposition Notifications - RFC 2298 ++Message Mode is able to request notifications from the receiver. ++ ++@item PGP - RFC 1991 and RFC 2440 ++@cindex RFC 1991 ++@cindex RFC 2440 ++RFC 1991 is the original @acronym{PGP} message specification, ++published as an informational RFC. RFC 2440 was the follow-up, now ++called Open PGP, and put on the Standards Track. Both document a ++non-@acronym{MIME} aware @acronym{PGP} format. Gnus supports both ++encoding (signing and encryption) and decoding (verification and ++decryption). ++ ++@item PGP/MIME - RFC 2015/3156 ++RFC 2015 (superseded by 3156 which references RFC 2440 instead of RFC ++1991) describes the @acronym{MIME}-wrapping around the RFC 1991/2440 format. ++Gnus supports both encoding and decoding. ++ ++@item S/MIME - RFC 2633 ++RFC 2633 describes the @acronym{S/MIME} format. ++ ++@item IMAP - RFC 1730/2060, RFC 2195, RFC 2086, RFC 2359, RFC 2595, RFC 1731 ++RFC 1730 is @acronym{IMAP} version 4, updated somewhat by RFC 2060 ++(@acronym{IMAP} 4 revision 1). RFC 2195 describes CRAM-MD5 ++authentication for @acronym{IMAP}. RFC 2086 describes access control ++lists (ACLs) for @acronym{IMAP}. RFC 2359 describes a @acronym{IMAP} ++protocol enhancement. RFC 2595 describes the proper @acronym{TLS} ++integration (STARTTLS) with @acronym{IMAP}. RFC 1731 describes the ++GSSAPI/Kerberos4 mechanisms for @acronym{IMAP}. ++ ++@end table ++ ++If you ever notice Gnus acting non-compliant with regards to the texts ++mentioned above, don't hesitate to drop a note to Gnus Towers and let us ++know. ++ ++ ++@node Emacsen ++@subsection Emacsen ++@cindex Emacsen ++@cindex XEmacs ++@cindex Mule ++@cindex Emacs ++ ++This version of Gnus should work on: ++ ++@itemize @bullet ++ ++@item ++Emacs 21.1 and up. ++ ++@item ++XEmacs 21.4 and up. ++ ++@end itemize ++ ++This Gnus version will absolutely not work on any Emacsen older than ++that. Not reliably, at least. Older versions of Gnus may work on older ++Emacs versions. Particularly, Gnus 5.10.8 should also work on Emacs ++20.7 and XEmacs 21.1. ++ ++@c No-merge comment: The paragraph added in v5-10 here must not be ++@c synced here! ++ ++@node Gnus Development ++@subsection Gnus Development ++ ++Gnus is developed in a two-phased cycle. The first phase involves much ++discussion on the development mailing list @samp{ding@@gnus.org}, where people ++propose changes and new features, post patches and new back ends. This ++phase is called the @dfn{alpha} phase, since the Gnusae released in this ++phase are @dfn{alpha releases}, or (perhaps more commonly in other ++circles) @dfn{snapshots}. During this phase, Gnus is assumed to be ++unstable and should not be used by casual users. Gnus alpha releases ++have names like ``Oort Gnus'' and ``No Gnus''. @xref{Gnus Versions}. ++ ++After futzing around for 10-100 alpha releases, Gnus is declared ++@dfn{frozen}, and only bug fixes are applied. Gnus loses the prefix, ++and is called things like ``Gnus 5.10.1'' instead. Normal people are ++supposed to be able to use these, and these are mostly discussed on the ++@samp{gnu.emacs.gnus} newsgroup. This newgroup is mirrored to the ++mailing list @samp{info-gnus-english@@gnu.org} which is carried on Gmane ++as @samp{gmane.emacs.gnus.user}. These releases are finally integrated ++in Emacs. ++ ++@cindex Incoming* ++@vindex mail-source-delete-incoming ++Some variable defaults differ between alpha Gnusae and released Gnusae, ++in particular, @code{mail-source-delete-incoming}. This is to prevent ++lossage of mail if an alpha release hiccups while handling the mail. ++@xref{Mail Source Customization}. ++ ++The division of discussion between the ding mailing list and the Gnus ++newsgroup is not purely based on publicity concerns. It's true that ++having people write about the horrible things that an alpha Gnus release ++can do (sometimes) in a public forum may scare people off, but more ++importantly, talking about new experimental features that have been ++introduced may confuse casual users. New features are frequently ++introduced, fiddled with, and judged to be found wanting, and then ++either discarded or totally rewritten. People reading the mailing list ++usually keep up with these rapid changes, while people on the newsgroup ++can't be assumed to do so. ++ ++So if you have problems with or questions about the alpha versions, ++direct those to the ding mailing list @samp{ding@@gnus.org}. This list ++is also available on Gmane as @samp{gmane.emacs.gnus.general}. ++ ++@cindex Incoming* ++@vindex mail-source-delete-incoming ++Some variable defaults differ between alpha Gnusae and released Gnusae, ++in particular, @code{mail-source-delete-incoming}. This is to prevent ++lossage of mail if an alpha release hiccups while handling the mail. ++@xref{Mail Source Customization}. ++ ++@node Contributors ++@subsection Contributors ++@cindex contributors ++ ++The new Gnus version couldn't have been done without the help of all the ++people on the (ding) mailing list. Every day for over a year I have ++gotten billions of nice bug reports from them, filling me with joy, ++every single one of them. Smooches. The people on the list have been ++tried beyond endurance, what with my ``oh, that's a neat idea , yup, I'll release it right away no wait, that doesn't ++work at all , yup, I'll ship that one off right away no, wait, that absolutely does not work'' policy for releases. ++Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that ++``worser''? ``much worser''? ``worsest''?) ++ ++I would like to take this opportunity to thank the Academy for@dots{} oops, ++wrong show. ++ ++@itemize @bullet ++ ++@item ++Masanobu @sc{Umeda}---the writer of the original @sc{gnus}. ++ ++@item ++Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el, webmail.el, ++nnwarchive and many, many other things connected with @acronym{MIME} and ++other types of en/decoding, as well as general bug fixing, new ++functionality and stuff. ++ ++@item ++Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as ++well as numerous other things). ++ ++@item ++Luis Fernandes---design and graphics. ++ ++@item ++Joe Reiss---creator of the smiley faces. ++ ++@item ++Justin Sheehy---the @acronym{FAQ} maintainer. ++ ++@item ++Erik Naggum---help, ideas, support, code and stuff. ++ ++@item ++Wes Hardaker---@file{gnus-picon.el} and the manual section on ++@dfn{picons} (@pxref{Picons}). ++ ++@item ++Kim-Minh Kaplan---further work on the picon code. ++ ++@item ++Brad Miller---@file{gnus-gl.el} and the GroupLens manual section. ++ ++@item ++Sudish Joseph---innumerable bug fixes. ++ ++@item ++Ilja Weis---@file{gnus-topic.el}. ++ ++@item ++Steven L. Baur---lots and lots and lots of bugs detections and fixes. ++ ++@item ++Vladimir Alexiev---the refcard and reference booklets. ++ ++@item ++Felix Lee & Jamie Zawinski---I stole some pieces from the XGnus ++distribution by Felix Lee and JWZ. ++ ++@item ++Scott Byer---@file{nnfolder.el} enhancements & rewrite. ++ ++@item ++Peter Mutsaers---orphan article scoring code. ++ ++@item ++Ken Raeburn---POP mail support. ++ ++@item ++Hallvard B Furuseth---various bits and pieces, especially dealing with ++.newsrc files. ++ ++@item ++Brian Edmonds---@file{gnus-bbdb.el}. ++ ++@item ++David Moore---rewrite of @file{nnvirtual.el} and many other things. ++ ++@item ++Kevin Davidson---came up with the name @dfn{ding}, so blame him. ++ ++@item ++Fran@,{c}ois Pinard---many, many interesting and thorough bug reports, as ++well as autoconf support. ++ ++@end itemize ++ ++This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark ++Borges, and Jost Krieger proof-reading parts of the manual. ++ ++The following people have contributed many patches and suggestions: ++ ++Christopher Davis, ++Andrew Eskilsson, ++Kai Grossjohann, ++Kevin Greiner, ++Jesper Harder, ++Paul Jarc, ++Simon Josefsson, ++David K@aa{}gedal, ++Richard Pieri, ++Fabrice Popineau, ++Daniel Quinlan, ++Michael Shields, ++Reiner Steib, ++Jason L. Tibbitts, III, ++Jack Vinson, ++Katsumi Yamaoka, @c Yamaoka ++and ++Teodor Zlatanov. ++ ++Also thanks to the following for patches and stuff: ++ ++Jari Aalto, ++Adrian Aichner, ++Vladimir Alexiev, ++Russ Allbery, ++Peter Arius, ++Matt Armstrong, ++Marc Auslander, ++Miles Bader, ++Alexei V. Barantsev, ++Frank Bennett, ++Robert Bihlmeyer, ++Chris Bone, ++Mark Borges, ++Mark Boyns, ++Lance A. Brown, ++Rob Browning, ++Kees de Bruin, ++Martin Buchholz, ++Joe Buehler, ++Kevin Buhr, ++Alastair Burt, ++Joao Cachopo, ++Zlatko Calusic, ++Massimo Campostrini, ++Castor, ++David Charlap, ++Dan Christensen, ++Kevin Christian, ++Jae-you Chung, @c ? ++James H. Cloos, Jr., ++Laura Conrad, ++Michael R. Cook, ++Glenn Coombs, ++Andrew J. Cosgriff, ++Neil Crellin, ++Frank D. Cringle, ++Geoffrey T. Dairiki, ++Andre Deparade, ++Ulrik Dickow, ++Dave Disser, ++Rui-Tao Dong, @c ? ++Joev Dubach, ++Michael Welsh Duggan, ++Dave Edmondson, ++Paul Eggert, ++Mark W. Eichin, ++Karl Eichwalder, ++Enami Tsugutomo, @c Enami ++Michael Ernst, ++Luc Van Eycken, ++Sam Falkner, ++Nelson Jose dos Santos Ferreira, ++Sigbjorn Finne, ++Sven Fischer, ++Paul Fisher, ++Decklin Foster, ++Gary D. Foster, ++Paul Franklin, ++Guy Geens, ++Arne Georg Gleditsch, ++David S. Goldberg, ++Michelangelo Grigni, ++Dale Hagglund, ++D. Hall, ++Magnus Hammerin, ++Kenichi Handa, @c Handa ++Raja R. Harinath, ++Yoshiki Hayashi, @c Hayashi ++P. E. Jareth Hein, ++Hisashige Kenji, @c Hisashige ++Scott Hofmann, ++Tassilo Horn, ++Marc Horowitz, ++Gunnar Horrigmo, ++Richard Hoskins, ++Brad Howes, ++Miguel de Icaza, ++Fran@,{c}ois Felix Ingrand, ++Tatsuya Ichikawa, @c Ichikawa ++Ishikawa Ichiro, @c Ishikawa ++Lee Iverson, ++Iwamuro Motonori, @c Iwamuro ++Rajappa Iyer, ++Andreas Jaeger, ++Adam P. Jenkins, ++Randell Jesup, ++Fred Johansen, ++Gareth Jones, ++Greg Klanderman, ++Karl Kleinpaste, ++Michael Klingbeil, ++Peter Skov Knudsen, ++Shuhei Kobayashi, @c Kobayashi ++Petr Konecny, ++Koseki Yoshinori, @c Koseki ++Thor Kristoffersen, ++Jens Lautenbacher, ++Martin Larose, ++Seokchan Lee, @c Lee ++Joerg Lenneis, ++Carsten Leonhardt, ++James LewisMoss, ++Christian Limpach, ++Markus Linnala, ++Dave Love, ++Mike McEwan, ++Tonny Madsen, ++Shlomo Mahlab, ++Nat Makarevitch, ++Istvan Marko, ++David Martin, ++Jason R. Mastaler, ++Gordon Matzigkeit, ++Timo Metzemakers, ++Richard Mlynarik, ++Lantz Moore, ++Morioka Tomohiko, @c Morioka ++Erik Toubro Nielsen, ++Hrvoje Niksic, ++Andy Norman, ++Fred Oberhauser, ++C. R. Oldham, ++Alexandre Oliva, ++Ken Olstad, ++Masaharu Onishi, @c Onishi ++Hideki Ono, @c Ono ++Ettore Perazzoli, ++William Perry, ++Stephen Peters, ++Jens-Ulrik Holger Petersen, ++Ulrich Pfeifer, ++Matt Pharr, ++Andy Piper, ++John McClary Prevost, ++Bill Pringlemeir, ++Mike Pullen, ++Jim Radford, ++Colin Rafferty, ++Lasse Rasinen, ++Lars Balker Rasmussen, ++Joe Reiss, ++Renaud Rioboo, ++Roland B. Roberts, ++Bart Robinson, ++Christian von Roques, ++Markus Rost, ++Jason Rumney, ++Wolfgang Rupprecht, ++Jay Sachs, ++Dewey M. Sasser, ++Conrad Sauerwald, ++Loren Schall, ++Dan Schmidt, ++Ralph Schleicher, ++Philippe Schnoebelen, ++Andreas Schwab, ++Randal L. Schwartz, ++Danny Siu, ++Matt Simmons, ++Paul D. Smith, ++Jeff Sparkes, ++Toby Speight, ++Michael Sperber, ++Darren Stalder, ++Richard Stallman, ++Greg Stark, ++Sam Steingold, ++Paul Stevenson, ++Jonas Steverud, ++Paul Stodghill, ++Kiyokazu Suto, @c Suto ++Kurt Swanson, ++Samuel Tardieu, ++Teddy, ++Chuck Thompson, ++Tozawa Akihiko, @c Tozawa ++Philippe Troin, ++James Troup, ++Trung Tran-Duc, ++Jack Twilley, ++Aaron M. Ucko, ++Aki Vehtari, ++Didier Verna, ++Vladimir Volovich, ++Jan Vroonhof, ++Stefan Waldherr, ++Pete Ware, ++Barry A. Warsaw, ++Christoph Wedler, ++Joe Wells, ++Lee Willis, ++and ++Lloyd Zusman. ++ ++ ++For a full overview of what each person has done, the ChangeLogs ++included in the Gnus alpha distributions should give ample reading ++(550kB and counting). ++ ++Apologies to everybody that I've forgotten, of which there are many, I'm ++sure. ++ ++Gee, that's quite a list of people. I guess that must mean that there ++actually are people who are using Gnus. Who'd'a thunk it! ++ ++ ++@node New Features ++@subsection New Features ++@cindex new features ++ ++@menu ++* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. ++* September Gnus:: The Thing Formally Known As Gnus 5.2/5.3. ++* Red Gnus:: Third time best---Gnus 5.4/5.5. ++* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7. ++* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9. ++* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11. ++* No Gnus:: Very punny. ++@end menu ++ ++These lists are, of course, just @emph{short} overviews of the ++@emph{most} important new features. No, really. There are tons more. ++Yes, we have feeping creaturism in full effect. ++ ++@node ding Gnus ++@subsubsection (ding) Gnus ++ ++New features in Gnus 5.0/5.1: ++ ++@itemize @bullet ++ ++@item ++The look of all buffers can be changed by setting format-like variables ++(@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}). ++ ++@item ++Local spool and several @acronym{NNTP} servers can be used at once ++(@pxref{Select Methods}). ++ ++@item ++You can combine groups into virtual groups (@pxref{Virtual Groups}). ++ ++@item ++You can read a number of different mail formats (@pxref{Getting Mail}). ++All the mail back ends implement a convenient mail expiry scheme ++(@pxref{Expiring Mail}). ++ ++@item ++Gnus can use various strategies for gathering threads that have lost ++their roots (thereby gathering loose sub-threads into one thread) or it ++can go back and retrieve enough headers to build a complete thread ++(@pxref{Customizing Threading}). ++ ++@item ++Killed groups can be displayed in the group buffer, and you can read ++them as well (@pxref{Listing Groups}). ++ ++@item ++Gnus can do partial group updates---you do not have to retrieve the ++entire active file just to check for new articles in a few groups ++(@pxref{The Active File}). ++ ++@item ++Gnus implements a sliding scale of subscribedness to groups ++(@pxref{Group Levels}). ++ ++@item ++You can score articles according to any number of criteria ++(@pxref{Scoring}). You can even get Gnus to find out how to score ++articles for you (@pxref{Adaptive Scoring}). ++ ++@item ++Gnus maintains a dribble buffer that is auto-saved the normal Emacs ++manner, so it should be difficult to lose much data on what you have ++read if your machine should go down (@pxref{Auto Save}). ++ ++@item ++Gnus now has its own startup file (@file{~/.gnus.el}) to avoid ++cluttering up the @file{.emacs} file. ++ ++@item ++You can set the process mark on both groups and articles and perform ++operations on all the marked items (@pxref{Process/Prefix}). ++ ++@item ++You can grep through a subset of groups and create a group from the ++results (@pxref{Kibozed Groups}). ++ ++@item ++You can list subsets of groups according to, well, anything ++(@pxref{Listing Groups}). ++ ++@item ++You can browse foreign servers and subscribe to groups from those ++servers (@pxref{Browse Foreign Server}). ++ ++@item ++Gnus can fetch articles, asynchronously, on a second connection to the ++server (@pxref{Asynchronous Fetching}). ++ ++@item ++You can cache articles locally (@pxref{Article Caching}). ++ ++@item ++The uudecode functions have been expanded and generalized ++(@pxref{Decoding Articles}). ++ ++@item ++You can still post uuencoded articles, which was a little-known feature ++of @sc{gnus}' past (@pxref{Uuencoding and Posting}). ++ ++@item ++Fetching parents (and other articles) now actually works without ++glitches (@pxref{Finding the Parent}). ++ ++@item ++Gnus can fetch @acronym{FAQ}s and group descriptions (@pxref{Group Information}). ++ ++@item ++Digests (and other files) can be used as the basis for groups ++(@pxref{Document Groups}). ++ ++@item ++Articles can be highlighted and customized (@pxref{Customizing ++Articles}). ++ ++@item ++URLs and other external references can be buttonized (@pxref{Article ++Buttons}). ++ ++@item ++You can do lots of strange stuff with the Gnus window & frame ++configuration (@pxref{Window Layout}). ++ ++@item ++You can click on buttons instead of using the keyboard ++(@pxref{Buttons}). ++ ++@end itemize ++ ++ ++@node September Gnus ++@subsubsection September Gnus ++ ++@iftex ++@iflatex ++\gnusfig{-28cm}{0cm}{\epsfig{figure=ps/september,height=20cm}} ++@end iflatex ++@end iftex ++ ++New features in Gnus 5.2/5.3: ++ ++@itemize @bullet ++ ++@item ++A new message composition mode is used. All old customization variables ++for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are ++now obsolete. ++ ++@item ++Gnus is now able to generate @dfn{sparse} threads---threads where ++missing articles are represented by empty nodes (@pxref{Customizing ++Threading}). ++ ++@lisp ++(setq gnus-build-sparse-threads 'some) ++@end lisp ++ ++@item ++Outgoing articles are stored on a special archive server ++(@pxref{Archived Messages}). ++ ++@item ++Partial thread regeneration now happens when articles are ++referred. ++ ++@item ++Gnus can make use of GroupLens predictions. ++ ++@item ++Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}). ++ ++@item ++A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}). ++ ++@lisp ++(setq gnus-use-trees t) ++@end lisp ++ ++@item ++An @code{nn}-like pick-and-read minor mode is available for the summary ++buffers (@pxref{Pick and Read}). ++ ++@lisp ++(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) ++@end lisp ++ ++@item ++In binary groups you can use a special binary minor mode (@pxref{Binary ++Groups}). ++ ++@item ++Groups can be grouped in a folding topic hierarchy (@pxref{Group ++Topics}). ++ ++@lisp ++(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) ++@end lisp ++ ++@item ++Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}). ++ ++@item ++Groups can now have a score, and bubbling based on entry frequency ++is possible (@pxref{Group Score}). ++ ++@lisp ++(add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group) ++@end lisp ++ ++@item ++Groups can be process-marked, and commands can be performed on ++groups of groups (@pxref{Marking Groups}). ++ ++@item ++Caching is possible in virtual groups. ++ ++@item ++@code{nndoc} now understands all kinds of digests, mail boxes, rnews ++news batches, ClariNet briefs collections, and just about everything ++else (@pxref{Document Groups}). ++ ++@item ++Gnus has a new back end (@code{nnsoup}) to create/read SOUP packets ++(@pxref{SOUP}). ++ ++@item ++The Gnus cache is much faster. ++ ++@item ++Groups can be sorted according to many criteria (@pxref{Sorting ++Groups}). ++ ++@item ++New group parameters have been introduced to set list-addresses and ++expiry times (@pxref{Group Parameters}). ++ ++@item ++All formatting specs allow specifying faces to be used ++(@pxref{Formatting Fonts}). ++ ++@item ++There are several more commands for setting/removing/acting on process ++marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}). ++ ++@item ++The summary buffer can be limited to show parts of the available ++articles based on a wide range of criteria. These commands have been ++bound to keys on the @kbd{/} submap (@pxref{Limiting}). ++ ++@item ++Articles can be made persistent with the @kbd{*} command ++(@pxref{Persistent Articles}). ++ ++@item ++All functions for hiding article elements are now toggles. ++ ++@item ++Article headers can be buttonized (@pxref{Article Washing}). ++ ++@item ++All mail back ends support fetching articles by @code{Message-ID}. ++ ++@item ++Duplicate mail can now be treated properly (@pxref{Duplicates}). ++ ++@item ++All summary mode commands are available directly from the article ++buffer (@pxref{Article Keymap}). ++ ++@item ++Frames can be part of @code{gnus-buffer-configuration} (@pxref{Window ++Layout}). ++ ++@item ++Mail can be re-scanned by a daemonic process (@pxref{Daemons}). ++@iftex ++@iflatex ++\marginpar[\mbox{}\hfill\epsfig{figure=ps/fseptember,height=5cm}]{\epsfig{figure=ps/fseptember,height=5cm}} ++@end iflatex ++@end iftex ++ ++@item ++Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}). ++ ++@lisp ++(setq gnus-use-nocem t) ++@end lisp ++ ++@item ++Groups can be made permanently visible (@pxref{Listing Groups}). ++ ++@lisp ++(setq gnus-permanently-visible-groups "^nnml:") ++@end lisp ++ ++@item ++Many new hooks have been introduced to make customizing easier. ++ ++@item ++Gnus respects the @code{Mail-Copies-To} header. ++ ++@item ++Threads can be gathered by looking at the @code{References} header ++(@pxref{Customizing Threading}). ++ ++@lisp ++(setq gnus-summary-thread-gathering-function ++ 'gnus-gather-threads-by-references) ++@end lisp ++ ++@item ++Read articles can be stored in a special backlog buffer to avoid ++refetching (@pxref{Article Backlog}). ++ ++@lisp ++(setq gnus-keep-backlog 50) ++@end lisp ++ ++@item ++A clean copy of the current article is always stored in a separate ++buffer to allow easier treatment. ++ ++@item ++Gnus can suggest where to save articles (@pxref{Saving Articles}). ++ ++@item ++Gnus doesn't have to do as much prompting when saving (@pxref{Saving ++Articles}). ++ ++@lisp ++(setq gnus-prompt-before-saving t) ++@end lisp ++ ++@item ++@code{gnus-uu} can view decoded files asynchronously while fetching ++articles (@pxref{Other Decode Variables}). ++ ++@lisp ++(setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view) ++@end lisp ++ ++@item ++Filling in the article buffer now works properly on cited text ++(@pxref{Article Washing}). ++ ++@item ++Hiding cited text adds buttons to toggle hiding, and how much ++cited text to hide is now customizable (@pxref{Article Hiding}). ++ ++@lisp ++(setq gnus-cited-lines-visible 2) ++@end lisp ++ ++@item ++Boring headers can be hidden (@pxref{Article Hiding}). ++ ++@item ++Default scoring values can now be set from the menu bar. ++ ++@item ++Further syntax checking of outgoing articles have been added. ++ ++@end itemize ++ ++ ++@node Red Gnus ++@subsubsection Red Gnus ++ ++New features in Gnus 5.4/5.5: ++ ++@iftex ++@iflatex ++\gnusfig{-5.5cm}{-4cm}{\epsfig{figure=ps/red,height=20cm}} ++@end iflatex ++@end iftex ++ ++@itemize @bullet ++ ++@item ++@file{nntp.el} has been totally rewritten in an asynchronous fashion. ++ ++@item ++Article prefetching functionality has been moved up into ++Gnus (@pxref{Asynchronous Fetching}). ++ ++@item ++Scoring can now be performed with logical operators like @code{and}, ++@code{or}, @code{not}, and parent redirection (@pxref{Advanced ++Scoring}). ++ ++@item ++Article washing status can be displayed in the ++article mode line (@pxref{Misc Article}). ++ ++@item ++@file{gnus.el} has been split into many smaller files. ++ ++@item ++Suppression of duplicate articles based on Message-ID can be done ++(@pxref{Duplicate Suppression}). ++ ++@lisp ++(setq gnus-suppress-duplicates t) ++@end lisp ++ ++@item ++New variables for specifying what score and adapt files are to be ++considered home score and adapt files (@pxref{Home Score File}) have ++been added. ++ ++@item ++@code{nndoc} was rewritten to be easily extendable (@pxref{Document ++Server Internals}). ++ ++@item ++Groups can inherit group parameters from parent topics (@pxref{Topic ++Parameters}). ++ ++@item ++Article editing has been revamped and is now actually usable. ++ ++@item ++Signatures can be recognized in more intelligent fashions ++(@pxref{Article Signature}). ++ ++@item ++Summary pick mode has been made to look more @code{nn}-like. Line ++numbers are displayed and the @kbd{.} command can be used to pick ++articles (@code{Pick and Read}). ++ ++@item ++Commands for moving the @file{.newsrc.eld} from one server to ++another have been added (@pxref{Changing Servers}). ++ ++@item ++There's a way now to specify that ``uninteresting'' fields be suppressed ++when generating lines in buffers (@pxref{Advanced Formatting}). ++ ++@item ++Several commands in the group buffer can be undone with @kbd{C-M-_} ++(@pxref{Undo}). ++ ++@item ++Scoring can be done on words using the new score type @code{w} ++(@pxref{Score File Format}). ++ ++@item ++Adaptive scoring can be done on a Subject word-by-word basis ++(@pxref{Adaptive Scoring}). ++ ++@lisp ++(setq gnus-use-adaptive-scoring '(word)) ++@end lisp ++ ++@item ++Scores can be decayed (@pxref{Score Decays}). ++ ++@lisp ++(setq gnus-decay-scores t) ++@end lisp ++ ++@item ++Scoring can be performed using a regexp on the Date header. The Date is ++normalized to compact ISO 8601 format first (@pxref{Score File Format}). ++ ++@item ++A new command has been added to remove all data on articles from ++the native server (@pxref{Changing Servers}). ++ ++@item ++A new command for reading collections of documents ++(@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{C-M-d} ++(@pxref{Really Various Summary Commands}). ++ ++@item ++Process mark sets can be pushed and popped (@pxref{Setting Process ++Marks}). ++ ++@item ++A new mail-to-news back end makes it possible to post even when the @acronym{NNTP} ++server doesn't allow posting (@pxref{Mail-To-News Gateways}). ++ ++@item ++A new back end for reading searches from Web search engines ++(@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added ++(@pxref{Web Searches}). ++ ++@item ++Groups inside topics can now be sorted using the standard sorting ++functions, and each topic can be sorted independently (@pxref{Topic ++Sorting}). ++ ++@item ++Subsets of the groups can be sorted independently (@code{Sorting ++Groups}). ++ ++@item ++Cached articles can be pulled into the groups (@pxref{Summary Generation ++Commands}). ++@iftex ++@iflatex ++\marginpar[\mbox{}\hfill\epsfig{figure=ps/fred,width=3cm}]{\epsfig{figure=ps/fred,width=3cm}} ++@end iflatex ++@end iftex ++ ++@item ++Score files are now applied in a more reliable order (@pxref{Score ++Variables}). ++ ++@item ++Reports on where mail messages end up can be generated (@pxref{Splitting ++Mail}). ++ ++@item ++More hooks and functions have been added to remove junk from incoming ++mail before saving the mail (@pxref{Washing Mail}). ++ ++@item ++Emphasized text can be properly fontisized: ++ ++@end itemize ++ ++ ++@node Quassia Gnus ++@subsubsection Quassia Gnus ++ ++New features in Gnus 5.6: ++ ++@itemize @bullet ++ ++@item ++New functionality for using Gnus as an offline newsreader has been ++added. A plethora of new commands and modes have been added. ++@xref{Gnus Unplugged}, for the full story. ++ ++@item ++The @code{nndraft} back end has returned, but works differently than ++before. All Message buffers are now also articles in the @code{nndraft} ++group, which is created automatically. ++ ++@item ++@code{gnus-alter-header-function} can now be used to alter header ++values. ++ ++@item ++@code{gnus-summary-goto-article} now accept Message-ID's. ++ ++@item ++A new Message command for deleting text in the body of a message ++outside the region: @kbd{C-c C-v}. ++ ++@item ++You can now post to component group in @code{nnvirtual} groups with ++@kbd{C-u C-c C-c}. ++ ++@item ++ @code{nntp-rlogin-program}---new variable to ease customization. ++ ++@item ++@code{C-u C-c C-c} in @code{gnus-article-edit-mode} will now inhibit ++re-highlighting of the article buffer. ++ ++@item ++New element in @code{gnus-boring-article-headers}---@code{long-to}. ++ ++@item ++@kbd{M-i} symbolic prefix command. @xref{Symbolic Prefixes}, for ++details. ++ ++@item ++@kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix ++@kbd{a} to add the score rule to the @file{all.SCORE} file. ++ ++@item ++@code{gnus-simplify-subject-functions} variable to allow greater ++control over simplification. ++ ++@item ++@kbd{A T}---new command for fetching the current thread. ++ ++@item ++@kbd{/ T}---new command for including the current thread in the ++limit. ++ ++@item ++@kbd{M-RET} is a new Message command for breaking cited text. ++ ++@item ++@samp{\\1}-expressions are now valid in @code{nnmail-split-methods}. ++ ++@item ++The @code{custom-face-lookup} function has been removed. ++If you used this function in your initialization files, you must ++rewrite them to use @code{face-spec-set} instead. ++ ++@item ++Canceling now uses the current select method. Symbolic prefix ++@kbd{a} forces normal posting method. ++ ++@item ++New command to translate M******** sm*rtq**t*s into proper ++text---@kbd{W d}. ++ ++@item ++For easier debugging of @code{nntp}, you can set ++@code{nntp-record-commands} to a non-@code{nil} value. ++ ++@item ++@code{nntp} now uses @file{~/.authinfo}, a @file{.netrc}-like file, for ++controlling where and how to send @sc{authinfo} to @acronym{NNTP} servers. ++ ++@item ++A command for editing group parameters from the summary buffer ++has been added. ++ ++@item ++A history of where mails have been split is available. ++ ++@item ++A new article date command has been added---@code{article-date-iso8601}. ++ ++@item ++Subjects can be simplified when threading by setting ++@code{gnus-score-thread-simplify}. ++ ++@item ++A new function for citing in Message has been ++added---@code{message-cite-original-without-signature}. ++ ++@item ++@code{article-strip-all-blank-lines}---new article command. ++ ++@item ++A new Message command to kill to the end of the article has ++been added. ++ ++@item ++A minimum adaptive score can be specified by using the ++@code{gnus-adaptive-word-minimum} variable. ++ ++@item ++The ``lapsed date'' article header can be kept continually ++updated by the @code{gnus-start-date-timer} command. ++ ++@item ++Web listserv archives can be read with the @code{nnlistserv} back end. ++ ++@item ++Old dejanews archives can now be read by @code{nnweb}. ++ ++@end itemize ++ ++@node Pterodactyl Gnus ++@subsubsection Pterodactyl Gnus ++ ++New features in Gnus 5.8: ++ ++@itemize @bullet ++ ++@item ++The mail-fetching functions have changed. See the manual for the ++many details. In particular, all procmail fetching variables are gone. ++ ++If you used procmail like in ++ ++@lisp ++(setq nnmail-use-procmail t) ++(setq nnmail-spool-file 'procmail) ++(setq nnmail-procmail-directory "~/mail/incoming/") ++(setq nnmail-procmail-suffix "\\.in") ++@end lisp ++ ++this now has changed to ++ ++@lisp ++(setq mail-sources ++ '((directory :path "~/mail/incoming/" ++ :suffix ".in"))) ++@end lisp ++ ++@xref{Mail Source Specifiers}. ++ ++@item ++Gnus is now a @acronym{MIME}-capable reader. This affects many parts of ++Gnus, and adds a slew of new commands. See the manual for details. ++ ++@item ++Gnus has also been multilingualized. This also affects too ++many parts of Gnus to summarize here, and adds many new variables. ++ ++@item ++@code{gnus-auto-select-first} can now be a function to be ++called to position point. ++ ++@item ++The user can now decide which extra headers should be included in ++summary buffers and @acronym{NOV} files. ++ ++@item ++@code{gnus-article-display-hook} has been removed. Instead, a number ++of variables starting with @code{gnus-treat-} have been added. ++ ++@item ++The Gnus posting styles have been redone again and now works in a ++subtly different manner. ++ ++@item ++New web-based back ends have been added: @code{nnslashdot}, ++@code{nnwarchive} and @code{nnultimate}. nnweb has been revamped, ++again, to keep up with ever-changing layouts. ++ ++@item ++Gnus can now read @acronym{IMAP} mail via @code{nnimap}. ++ ++@end itemize ++ ++@node Oort Gnus ++@subsubsection Oort Gnus ++@cindex Oort Gnus ++ ++New features in Gnus 5.10: ++ ++@itemize @bullet ++ ++@item Installation changes ++@c *********************** ++ ++@itemize @bullet ++@item ++Upgrading from previous (stable) version if you have used Oort. ++ ++If you have tried Oort (the unstable Gnus branch leading to this ++release) but went back to a stable version, be careful when upgrading to ++this version. In particular, you will probably want to remove all ++@file{.marks} (nnml) and @file{.mrk} (nnfolder) files, so that flags are ++read from your @file{.newsrc.eld} instead of from the ++@file{.marks}/@file{.mrk} file where this release store flags. See a ++later entry for more information about marks. Note that downgrading ++isn't save in general. ++ ++@item ++Lisp files are now installed in @file{.../site-lisp/gnus/} by default. ++It defaulted to @file{.../site-lisp/} formerly. In addition to this, ++the new installer issues a warning if other Gnus installations which ++will shadow the latest one are detected. You can then remove those ++shadows manually or remove them using @code{make ++remove-installed-shadows}. ++ ++@item ++New @file{make.bat} for compiling and installing Gnus under MS Windows ++ ++Use @file{make.bat} if you want to install Gnus under MS Windows, the ++first argument to the batch-program should be the directory where ++@file{xemacs.exe} respectively @file{emacs.exe} is located, if you want ++to install Gnus after compiling it, give @file{make.bat} @code{/copy} as ++the second parameter. ++ ++@file{make.bat} has been rewritten from scratch, it now features ++automatic recognition of XEmacs and GNU Emacs, generates ++@file{gnus-load.el}, checks if errors occur while compilation and ++generation of info files and reports them at the end of the build ++process. It now uses @code{makeinfo} if it is available and falls ++back to @file{infohack.el} otherwise. @file{make.bat} should now ++install all files which are necessary to run Gnus and be generally a ++complete replacement for the @code{configure; make; make install} ++cycle used under Unix systems. ++ ++The new @file{make.bat} makes @file{make-x.bat} and @file{xemacs.mak} ++superfluous, so they have been removed. ++ ++@item ++@file{~/News/overview/} not used. ++ ++As a result of the following change, the @file{~/News/overview/} ++directory is not used any more. You can safely delete the entire ++hierarchy. ++ ++@c FIXME: `gnus-load' is mentioned in README, which is not included in ++@c CVS. We should find a better place for this item. ++@item ++@code{(require 'gnus-load)} ++ ++If you use a stand-alone Gnus distribution, you'd better add ++@code{(require 'gnus-load)} into your @file{~/.emacs} after adding the Gnus ++lisp directory into load-path. ++ ++File @file{gnus-load.el} contains autoload commands, functions and variables, ++some of which may not be included in distributions of Emacsen. ++ ++@end itemize ++ ++@item New packages and libraries within Gnus ++@c ***************************************** ++ ++@itemize @bullet ++ ++@item ++The revised Gnus @acronym{FAQ} is included in the manual, ++@xref{Frequently Asked Questions}. ++ ++@item ++@acronym{TLS} wrapper shipped with Gnus ++ ++@acronym{TLS}/@acronym{SSL} is now supported in @acronym{IMAP} and ++@acronym{NNTP} via @file{tls.el} and GNUTLS. The old ++@acronym{TLS}/@acronym{SSL} support via (external third party) ++@file{ssl.el} and OpenSSL still works. ++ ++@item ++Improved anti-spam features. ++ ++Gnus is now able to take out spam from your mail and news streams ++using a wide variety of programs and filter rules. Among the supported ++methods are RBL blocklists, bogofilter and white/blacklists. Hooks ++for easy use of external packages such as SpamAssassin and Hashcash ++are also new. @ref{Thwarting Email Spam} and @ref{Spam Package}. ++@c FIXME: @xref{Spam Package}?. Should this be under Misc? ++ ++@item ++Gnus supports server-side mail filtering using Sieve. ++ ++Sieve rules can be added as Group Parameters for groups, and the ++complete Sieve script is generated using @kbd{D g} from the Group ++buffer, and then uploaded to the server using @kbd{C-c C-l} in the ++generated Sieve buffer. @xref{Sieve Commands}, and the new Sieve ++manual @ref{Top, , Top, sieve, Emacs Sieve}. ++ ++@end itemize ++ ++@item Changes in group mode ++@c ************************ ++ ++@itemize @bullet ++ ++@item ++@code{gnus-group-read-ephemeral-group} can be called interactively, ++using @kbd{G M}. ++ ++@item ++Retrieval of charters and control messages ++ ++There are new commands for fetching newsgroup charters (@kbd{H c}) and ++control messages (@kbd{H C}). ++ ++@item ++The new variable @code{gnus-parameters} can be used to set group parameters. ++ ++Earlier this was done only via @kbd{G p} (or @kbd{G c}), which stored ++the parameters in @file{~/.newsrc.eld}, but via this variable you can ++enjoy the powers of customize, and simplified backups since you set the ++variable in @file{~/.gnus.el} instead of @file{~/.newsrc.eld}. The ++variable maps regular expressions matching group names to group ++parameters, a'la: ++@lisp ++(setq gnus-parameters ++ '(("mail\\..*" ++ (gnus-show-threads nil) ++ (gnus-use-scoring nil)) ++ ("^nnimap:\\(foo.bar\\)$" ++ (to-group . "\\1")))) ++@end lisp ++ ++@item ++Unread count correct in nnimap groups. ++ ++The estimated number of unread articles in the group buffer should now ++be correct for nnimap groups. This is achieved by calling ++@code{nnimap-fixup-unread-after-getting-new-news} from the ++@code{gnus-setup-news-hook} (called on startup) and ++@code{gnus-after-getting-new-news-hook}. (called after getting new ++mail). If you have modified those variables from the default, you may ++want to add @code{nnimap-fixup-unread-after-getting-new-news} again. If ++you were happy with the estimate and want to save some (minimal) time ++when getting new mail, remove the function. ++ ++@item ++Group names are treated as UTF-8 by default. ++ ++This is supposedly what USEFOR wanted to migrate to. See ++@code{gnus-group-name-charset-group-alist} and ++@code{gnus-group-name-charset-method-alist} for customization. ++ ++@item ++@code{gnus-group-charset-alist} and ++@code{gnus-group-ignored-charsets-alist}. ++ ++The regexps in these variables are compared with full group names ++instead of real group names in 5.8. Users who customize these ++variables should change those regexps accordingly. For example: ++@lisp ++("^han\\>" euc-kr) -> ("\\(^\\|:\\)han\\>" euc-kr) ++@end lisp ++ ++@item ++Old intermediate incoming mail files (@file{Incoming*}) are deleted ++after a couple of days, not immediately. @xref{Mail Source ++Customization}. (New in Gnus 5.10.10 / Emacs 22.2) ++ ++@end itemize ++ ++@item Changes in summary and article mode ++@c ************************************** ++ ++@itemize @bullet ++ ++@item ++@kbd{F} (@code{gnus-article-followup-with-original}) and @kbd{R} ++(@code{gnus-article-reply-with-original}) only yank the text in the ++region if the region is active. ++ ++@item ++In draft groups, @kbd{e} is now bound to @code{gnus-draft-edit-message}. ++Use @kbd{B w} for @code{gnus-summary-edit-article} instead. ++ ++@item ++Article Buttons ++ ++More buttons for URLs, mail addresses, Message-IDs, Info links, man ++pages and Emacs or Gnus related references. @xref{Article Buttons}. The ++variables @code{gnus-button-@var{*}-level} can be used to control the ++appearance of all article buttons. @xref{Article Button Levels}. ++ ++@item ++Single-part yenc encoded attachments can be decoded. ++ ++@item ++Picons ++ ++The picons code has been reimplemented to work in GNU Emacs---some of ++the previous options have been removed or renamed. ++ ++Picons are small ``personal icons'' representing users, domain and ++newsgroups, which can be displayed in the Article buffer. ++@xref{Picons}. ++ ++@item ++If the new option @code{gnus-treat-body-boundary} is non-@code{nil}, a ++boundary line is drawn at the end of the headers. ++ ++@item ++Signed article headers (X-PGP-Sig) can be verified with @kbd{W p}. ++ ++@item ++The Summary Buffer uses an arrow in the fringe to indicate the current ++article. Use @code{(setq gnus-summary-display-arrow nil)} to disable it. ++ ++@item ++Warn about email replies to news ++ ++Do you often find yourself replying to news by email by mistake? Then ++the new option @code{gnus-confirm-mail-reply-to-news} is just the thing for ++you. ++ ++@item ++If the new option @code{gnus-summary-display-while-building} is ++non-@code{nil}, the summary buffer is shown and updated as it's being ++built. ++ ++@item ++The new @code{recent} mark @samp{.} indicates newly arrived messages (as ++opposed to old but unread messages). ++ ++@item ++Gnus supports RFC 2369 mailing list headers, and adds a number of ++related commands in mailing list groups. @xref{Mailing List}. ++ ++@item ++The Date header can be displayed in a format that can be read aloud ++in English. @xref{Article Date}. ++ ++@item ++diffs are automatically highlighted in groups matching ++@code{mm-uu-diff-groups-regexp} ++ ++@item ++Better handling of Microsoft citation styles ++ ++Gnus now tries to recognize the mangled header block that some Microsoft ++mailers use to indicate that the rest of the message is a citation, even ++though it is not quoted in any way. The variable ++@code{gnus-cite-unsightly-citation-regexp} matches the start of these ++citations. ++ ++The new command @kbd{W Y f} ++(@code{gnus-article-outlook-deuglify-article}) allows deuglifying broken ++Outlook (Express) articles. ++ ++@item ++@code{gnus-article-skip-boring} ++ ++If you set @code{gnus-article-skip-boring} to @code{t}, then Gnus will ++not scroll down to show you a page that contains only boring text, ++which by default means cited text and signature. You can customize ++what is skippable using @code{gnus-article-boring-faces}. ++ ++This feature is especially useful if you read many articles that ++consist of a little new content at the top with a long, untrimmed ++message cited below. ++ ++@item ++Smileys (@samp{:-)}, @samp{;-)} etc) are now displayed graphically in ++Emacs too. ++ ++Put @code{(setq gnus-treat-display-smileys nil)} in @file{~/.gnus.el} to ++disable it. ++ ++@item ++Face headers handling. @xref{Face}. ++ ++@item ++In the summary buffer, the new command @kbd{/ N} inserts new messages ++and @kbd{/ o} inserts old messages. ++ ++@item ++Gnus decodes morse encoded messages if you press @kbd{W m}. ++ ++@item ++@code{gnus-summary-line-format} ++ ++The default value changed to @samp{%U%R%z%I%(%[%4L: %-23,23f%]%) ++%s\n}. Moreover @code{gnus-extra-headers}, ++@code{nnmail-extra-headers} and @code{gnus-ignored-from-addresses} ++changed their default so that the users name will be replaced by the ++recipient's name or the group name posting to for @acronym{NNTP} ++groups. ++ ++@item ++Deleting of attachments. ++ ++The command @code{gnus-mime-save-part-and-strip} (bound to @kbd{C-o} ++on @acronym{MIME} buttons) saves a part and replaces the part with an ++external one. @code{gnus-mime-delete-part} (bound to @kbd{d} on ++@acronym{MIME} buttons) removes a part. It works only on back ends ++that support editing. ++ ++@item ++@code{gnus-default-charset} ++ ++The default value is determined from the ++@code{current-language-environment} variable, instead of ++@code{iso-8859-1}. Also the @samp{.*} item in ++@code{gnus-group-charset-alist} is removed. ++ ++@item ++Printing capabilities are enhanced. ++ ++Gnus supports Muttprint natively with @kbd{O P} from the Summary and ++Article buffers. Also, each individual @acronym{MIME} part can be ++printed using @kbd{p} on the @acronym{MIME} button. ++ ++@item ++Extended format specs. ++ ++Format spec @samp{%&user-date;} is added into ++@code{gnus-summary-line-format-alist}. Also, user defined extended ++format specs are supported. The extended format specs look like ++@samp{%u&foo;}, which invokes function ++@code{gnus-user-format-function-@var{foo}}. Because @samp{&} is used as the ++escape character, old user defined format @samp{%u&} is no longer supported. ++ ++@item ++@kbd{/ *} (@code{gnus-summary-limit-include-cached}) is rewritten. ++@c FIXME: Was this a user-visible change? ++ ++It was aliased to @kbd{Y c} ++(@code{gnus-summary-insert-cached-articles}). The new function filters ++out other articles. ++ ++@item ++Some limiting commands accept a @kbd{C-u} prefix to negate the match. ++ ++If @kbd{C-u} is used on subject, author or extra headers, i.e., @kbd{/ ++s}, @kbd{/ a}, and @kbd{/ x} ++(@code{gnus-summary-limit-to-@{subject,author,extra@}}) respectively, the ++result will be to display all articles that do not match the expression. ++ ++@item ++Gnus inlines external parts (message/external). ++ ++@end itemize ++ ++@item Changes in Message mode and related Gnus features ++@c **************************************************** ++ ++@itemize @bullet ++ ++@item ++Delayed articles ++ ++You can delay the sending of a message with @kbd{C-c C-j} in the Message ++buffer. The messages are delivered at specified time. This is useful ++for sending yourself reminders. @xref{Delayed Articles}. ++ ++@item ++If the new option @code{nnml-use-compressed-files} is non-@code{nil}, ++the nnml back end allows compressed message files. ++ ++@item ++The new option @code{gnus-gcc-mark-as-read} automatically marks ++Gcc articles as read. ++ ++@item ++Externalizing of attachments ++ ++If @code{gnus-gcc-externalize-attachments} or ++@code{message-fcc-externalize-attachments} is non-@code{nil}, attach ++local files as external parts. ++ ++@item ++The envelope sender address can be customized when using Sendmail. ++@xref{Mail Variables, Mail Variables,, message, Message Manual}. ++ ++@item ++Gnus no longer generate the Sender: header automatically. ++ ++Earlier it was generated when the user configurable email address was ++different from the Gnus guessed default user address. As the guessing ++algorithm is rarely correct these days, and (more controversially) the ++only use of the Sender: header was to check if you are entitled to ++cancel/supersede news (which is now solved by Cancel Locks instead, ++see another entry), generation of the header has been disabled by ++default. See the variables @code{message-required-headers}, ++@code{message-required-news-headers}, and ++@code{message-required-mail-headers}. ++ ++@item ++Features from third party @file{message-utils.el} added to @file{message.el}. ++ ++Message now asks if you wish to remove @samp{(was: )} from ++subject lines (see @code{message-subject-trailing-was-query}). @kbd{C-c ++M-m} and @kbd{C-c M-f} inserts markers indicating included text. ++@kbd{C-c C-f a} adds a X-No-Archive: header. @kbd{C-c C-f x} inserts ++appropriate headers and a note in the body for cross-postings and ++followups (see the variables @code{message-cross-post-@var{*}}). ++ ++@item ++References and X-Draft-From headers are no longer generated when you ++start composing messages and @code{message-generate-headers-first} is ++@code{nil}. ++ ++@item ++Easy inclusion of X-Faces headers. @xref{X-Face}. ++ ++@item ++Group Carbon Copy (GCC) quoting ++ ++To support groups that contains SPC and other weird characters, groups ++are quoted before they are placed in the Gcc: header. This means ++variables such as @code{gnus-message-archive-group} should no longer ++contain quote characters to make groups containing SPC work. Also, if ++you are using the string @samp{nnml:foo, nnml:bar} (indicating Gcc ++into two groups) you must change it to return the list ++@code{("nnml:foo" "nnml:bar")}, otherwise the Gcc: line will be quoted ++incorrectly. Note that returning the string @samp{nnml:foo, nnml:bar} ++was incorrect earlier, it just didn't generate any problems since it ++was inserted directly. ++ ++@item ++@code{message-insinuate-rmail} ++ ++@c FIXME should that not be 'message-user-agent? ++Adding @code{(message-insinuate-rmail)} and @code{(setq ++mail-user-agent 'gnus-user-agent)} in @file{.emacs} convinces Rmail to ++compose, reply and forward messages in message-mode, where you can ++enjoy the power of @acronym{MML}. ++ ++@item ++@code{message-minibuffer-local-map} ++ ++The line below enables BBDB in resending a message: ++@lisp ++(define-key message-minibuffer-local-map [(tab)] ++ 'bbdb-complete-name) ++@end lisp ++ ++@item ++@code{gnus-posting-styles} ++ ++Add a new format of match like ++@lisp ++((header "to" "larsi.*org") ++ (Organization "Somewhere, Inc.")) ++@end lisp ++The old format like the lines below is obsolete, but still accepted. ++@lisp ++(header "to" "larsi.*org" ++ (Organization "Somewhere, Inc.")) ++@end lisp ++ ++@item ++@code{message-ignored-news-headers} and @code{message-ignored-mail-headers} ++ ++@samp{X-Draft-From} and @samp{X-Gnus-Agent-Meta-Information} have been ++added into these two variables. If you customized those, perhaps you ++need add those two headers too. ++ ++@item ++Gnus supports the ``format=flowed'' (RFC 2646) parameter. On ++composing messages, it is enabled by @code{use-hard-newlines}. ++Decoding format=flowed was present but not documented in earlier ++versions. ++ ++@item ++The option @code{mm-fill-flowed} can be used to disable treatment of ++``format=flowed'' messages. Also, flowed text is disabled when sending ++inline PGP signed messages. @xref{Flowed text, , Flowed text, ++emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) ++@c This entry is also present in the node "No Gnus". ++ ++@item ++Gnus supports the generation of RFC 2298 Disposition Notification requests. ++ ++This is invoked with the @kbd{C-c M-n} key binding from message mode. ++ ++@item ++Message supports the Importance: (RFC 2156) header. ++ ++In the message buffer, @kbd{C-c C-f C-i} or @kbd{C-c C-u} cycles through ++the valid values. ++ ++@item ++Gnus supports Cancel Locks in News. ++ ++This means a header @samp{Cancel-Lock} is inserted in news posting. It is ++used to determine if you wrote an article or not (for canceling and ++superseding). Gnus generates a random password string the first time ++you post a message, and saves it in your @file{~/.emacs} using the Custom ++system. While the variable is called @code{canlock-password}, it is not ++security sensitive data. Publishing your canlock string on the web ++will not allow anyone to be able to anything she could not already do. ++The behavior can be changed by customizing @code{message-insert-canlock}. ++ ++@item ++Gnus supports @acronym{PGP} (RFC 1991/2440), @acronym{PGP/MIME} (RFC ++2015/3156) and @acronym{S/MIME} (RFC 2630-2633). ++ ++It needs an external @acronym{S/MIME} and OpenPGP implementation, but no ++additional Lisp libraries. This add several menu items to the ++Attachments menu, and @kbd{C-c RET} key bindings, when composing ++messages. This also obsoletes @code{gnus-article-hide-pgp-hook}. ++ ++@item ++@acronym{MML} (Mime compose) prefix changed from @kbd{M-m} to @kbd{C-c ++C-m}. ++ ++This change was made to avoid conflict with the standard binding of ++@code{back-to-indentation}, which is also useful in message mode. ++ ++@item ++The default for @code{message-forward-show-mml} changed to the symbol ++@code{best}. ++ ++The behavior for the @code{best} value is to show @acronym{MML} (i.e., ++convert to @acronym{MIME}) when appropriate. @acronym{MML} will not be ++used when forwarding signed or encrypted messages, as the conversion ++invalidate the digital signature. ++ ++@item ++If @code{auto-compression-mode} is enabled, attachments are automatically ++decompressed when activated. ++@c FIXME: Does this affect article or message mode? ++ ++@item ++Support for non-@acronym{ASCII} domain names ++ ++Message supports non-@acronym{ASCII} domain names in From:, To: and ++Cc: and will query you whether to perform encoding when you try to ++send a message. The variable @code{message-use-idna} controls this. ++Gnus will also decode non-@acronym{ASCII} domain names in From:, To: ++and Cc: when you view a message. The variable @code{gnus-use-idna} ++controls this. ++ ++@item You can now drag and drop attachments to the Message buffer. ++See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. ++@xref{MIME, ,MIME, message, Message Manual}. ++@c New in 5.10.9 / 5.11 (Emacs 22.1) ++ ++@item @code{auto-fill-mode} is enabled by default in Message mode. ++See @code{message-fill-column}. @xref{Various Message Variables, , ++Message Headers, message, Message Manual}. ++@c New in Gnus 5.10.12 / 5.11 (Emacs 22.3) ++ ++@end itemize ++ ++@item Changes in back ends ++@c *********************** ++ ++@itemize @bullet ++@item ++Gnus can display RSS newsfeeds as a newsgroup. @xref{RSS}. ++ ++@item ++The nndoc back end now supports mailman digests and exim bounces. ++ ++@item ++Gnus supports Maildir groups. ++ ++Gnus includes a new back end @file{nnmaildir.el}. @xref{Maildir}. ++ ++@item ++The nnml and nnfolder back ends store marks for each groups. ++ ++This makes it possible to take backup of nnml/nnfolder servers/groups ++separately of @file{~/.newsrc.eld}, while preserving marks. It also ++makes it possible to share articles and marks between users (without ++sharing the @file{~/.newsrc.eld} file) within e.g. a department. It ++works by storing the marks stored in @file{~/.newsrc.eld} in a per-group ++file @file{.marks} (for nnml) and @file{@var{groupname}.mrk} (for ++nnfolder, named @var{groupname}). If the nnml/nnfolder is moved to ++another machine, Gnus will automatically use the @file{.marks} or ++@file{.mrk} file instead of the information in @file{~/.newsrc.eld}. ++The new server variables @code{nnml-marks-is-evil} and ++@code{nnfolder-marks-is-evil} can be used to disable this feature. ++ ++@end itemize ++ ++@item Appearance ++@c ************* ++ ++@itemize @bullet ++ ++@item ++The menu bar item (in Group and Summary buffer) named ``Misc'' has ++been renamed to ``Gnus''. ++ ++@item ++The menu bar item (in Message mode) named ``@acronym{MML}'' has been ++renamed to ``Attachments''. Note that this menu also contains security ++related stuff, like signing and encryption (@pxref{Security, Security,, ++message, Message Manual}). ++ ++@item ++The tool bars have been updated to use GNOME icons in Group, Summary and ++Message mode. You can also customize the tool bars: @kbd{M-x ++customize-apropos RET -tool-bar$} should get you started. This is a new ++feature in Gnus 5.10.10. (Only for Emacs, not in XEmacs.) ++ ++@item The tool bar icons are now (de)activated correctly ++in the group buffer, see the variable @code{gnus-group-update-tool-bar}. ++Its default value depends on your Emacs version. This is a new feature ++in Gnus 5.10.9. ++@end itemize ++ ++ ++@item Miscellaneous changes ++@c ************************ ++ ++@itemize @bullet ++ ++@item ++@code{gnus-agent} ++ ++The Gnus Agent has seen a major updated and is now enabled by default, ++and all nntp and nnimap servers from @code{gnus-select-method} and ++@code{gnus-secondary-select-method} are agentized by default. Earlier ++only the server in @code{gnus-select-method} was agentized by the ++default, and the agent was disabled by default. When the agent is ++enabled, headers are now also retrieved from the Agent cache instead ++of the back ends when possible. Earlier this only happened in the ++unplugged state. You can enroll or remove servers with @kbd{J a} and ++@kbd{J r} in the server buffer. Gnus will not download articles into ++the Agent cache, unless you instruct it to do so, though, by using ++@kbd{J u} or @kbd{J s} from the Group buffer. You revert to the old ++behavior of having the Agent disabled with @code{(setq gnus-agent ++nil)}. Note that putting @code{(gnus-agentize)} in @file{~/.gnus.el} ++is not needed any more. ++ ++@item ++Gnus reads the @acronym{NOV} and articles in the Agent if plugged. ++ ++If one reads an article while plugged, and the article already exists ++in the Agent, it won't get downloaded once more. @code{(setq ++gnus-agent-cache nil)} reverts to the old behavior. ++ ++@item ++Dired integration ++ ++@code{gnus-dired-minor-mode} (see @ref{Other modes}) installs key ++bindings in dired buffers to send a file as an attachment, open a file ++using the appropriate mailcap entry, and print a file using the mailcap ++entry. ++ ++@item ++The format spec @code{%C} for positioning point has changed to @code{%*}. ++ ++@item ++@code{gnus-slave-unplugged} ++ ++A new command which starts Gnus offline in slave mode. ++ ++@end itemize ++ ++@end itemize ++ ++@node No Gnus ++@subsubsection No Gnus ++@cindex No Gnus ++ ++New features in No Gnus: ++@c FIXME: Gnus 5.12? ++ ++@include gnus-news.texi ++ ++@iftex ++ ++@page ++@node The Manual ++@section The Manual ++@cindex colophon ++@cindex manual ++ ++This manual was generated from a TeXinfo file and then run through ++either @code{texi2dvi} ++@iflatex ++or my own home-brewed TeXinfo to \LaTeX\ transformer, ++and then run through @code{latex} and @code{dvips} ++@end iflatex ++to get what you hold in your hands now. ++ ++The following conventions have been used: ++ ++@enumerate ++ ++@item ++This is a @samp{string} ++ ++@item ++This is a @kbd{keystroke} ++ ++@item ++This is a @file{file} ++ ++@item ++This is a @code{symbol} ++ ++@end enumerate ++ ++So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would ++mean: ++ ++@lisp ++(setq flargnoze "yes") ++@end lisp ++ ++If I say ``set @code{flumphel} to @code{yes}'', that would mean: ++ ++@lisp ++(setq flumphel 'yes) ++@end lisp ++ ++@samp{yes} and @code{yes} are two @emph{very} different things---don't ++ever get them confused. ++ ++@iflatex ++@c @head ++Of course, everything in this manual is of vital interest, so you should ++read it all. Several times. However, if you feel like skimming the ++manual, look for that gnu head you should see in the margin over ++there---it means that what's being discussed is of more importance than ++the rest of the stuff. (On the other hand, if everything is infinitely ++important, how can anything be more important than that? Just one more ++of the mysteries of this world, I guess.) ++@end iflatex ++ ++@end iftex ++ ++ ++@node On Writing Manuals ++@section On Writing Manuals ++ ++I guess most manuals are written after-the-fact; documenting a program ++that's already there. This is not how this manual is written. When ++implementing something, I write the manual entry for that something ++straight away. I then see that it's difficult to explain the ++functionality, so I write how it's supposed to be, and then I change the ++implementation. Writing the documentation and writing the code go hand ++in hand. ++ ++This, of course, means that this manual has no, or little, flow. It ++documents absolutely everything in Gnus, but often not where you're ++looking for it. It is a reference manual, and not a guide to how to get ++started with Gnus. ++ ++That would be a totally different book, that should be written using the ++reference manual as source material. It would look quite different. ++ ++ ++@page ++@node Terminology ++@section Terminology ++ ++@cindex terminology ++@table @dfn ++ ++@item news ++@cindex news ++This is what you are supposed to use this thing for---reading news. ++News is generally fetched from a nearby @acronym{NNTP} server, and is ++generally publicly available to everybody. If you post news, the entire ++world is likely to read just what you have written, and they'll all ++snigger mischievously. Behind your back. ++ ++@item mail ++@cindex mail ++Everything that's delivered to you personally is mail. Some news/mail ++readers (like Gnus) blur the distinction between mail and news, but ++there is a difference. Mail is private. News is public. Mailing is ++not posting, and replying is not following up. ++ ++@item reply ++@cindex reply ++Send a mail to the person who has written what you are reading. ++ ++@item follow up ++@cindex follow up ++Post an article to the current newsgroup responding to the article you ++are reading. ++ ++@item back end ++@cindex back end ++Gnus considers mail and news to be mostly the same, really. The only ++difference is how to access the actual articles. News articles are ++commonly fetched via the protocol @acronym{NNTP}, whereas mail ++messages could be read from a file on the local disk. The internal ++architecture of Gnus thus comprises a ``front end'' and a number of ++``back ends''. Internally, when you enter a group (by hitting ++@key{RET}, say), you thereby invoke a function in the front end in ++Gnus. The front end then ``talks'' to a back end and says things like ++``Give me the list of articles in the foo group'' or ``Show me article ++number 4711''. ++ ++So a back end mainly defines either a protocol (the @code{nntp} back ++end accesses news via @acronym{NNTP}, the @code{nnimap} back end ++accesses mail via @acronym{IMAP}) or a file format and directory ++layout (the @code{nnspool} back end accesses news via the common ++``spool directory'' format, the @code{nnml} back end access mail via a ++file format and directory layout that's quite similar). ++ ++Gnus does not handle the underlying media, so to speak---this is all ++done by the back ends. A back end is a collection of functions to ++access the articles. ++ ++However, sometimes the term ``back end'' is also used where ``server'' ++would have been more appropriate. And then there is the term ``select ++method'' which can mean either. The Gnus terminology can be quite ++confusing. ++ ++@item native ++@cindex native ++Gnus will always use one method (and back end) as the @dfn{native}, or ++default, way of getting news. ++ ++@item foreign ++@cindex foreign ++You can also have any number of foreign groups active at the same time. ++These are groups that use non-native non-secondary back ends for getting ++news. ++ ++@item secondary ++@cindex secondary ++Secondary back ends are somewhere half-way between being native and being ++foreign, but they mostly act like they are native. ++ ++@item article ++@cindex article ++A message that has been posted as news. ++ ++@item mail message ++@cindex mail message ++A message that has been mailed. ++ ++@item message ++@cindex message ++A mail message or news article ++ ++@item head ++@cindex head ++The top part of a message, where administrative information (etc.) is ++put. ++ ++@item body ++@cindex body ++The rest of an article. Everything not in the head is in the ++body. ++ ++@item header ++@cindex header ++A line from the head of an article. ++ ++@item headers ++@cindex headers ++A collection of such lines, or a collection of heads. Or even a ++collection of @acronym{NOV} lines. ++ ++@item @acronym{NOV} ++@cindex @acronym{NOV} ++@acronym{NOV} stands for News OverView, which is a type of news server ++header which provide datas containing the condensed header information ++of articles. They are produced by the server itself; in the @code{nntp} ++back end Gnus uses the ones that the @acronym{NNTP} server makes, but ++Gnus makes them by itself for some backends (in particular, @code{nnml}). ++ ++When Gnus enters a group, it asks the back end for the headers of all ++unread articles in the group. Most servers support the News OverView ++format, which is more compact and much faster to read and parse than the ++normal @sc{head} format. ++ ++The @acronym{NOV} data consist of one or more text lines (@pxref{Text ++Lines, ,Motion by Text Lines, elisp, The Emacs Lisp Reference Manual}) ++where each line has the header information of one article. The header ++information is a tab-separated series of the header's contents including ++an article number, a subject, an author, a date, a message-id, ++references, etc. ++ ++Those data enable Gnus to generate summary lines quickly. However, if ++the server does not support @acronym{NOV} or you disable it purposely or ++for some reason, Gnus will try to generate the header information by ++parsing each article's headers one by one. It will take time. ++Therefore, it is not usually a good idea to set nn*-nov-is-evil ++(@pxref{Slow/Expensive Connection}) to a non-@code{nil} value unless you ++know that the server makes wrong @acronym{NOV} data. ++ ++@item level ++@cindex levels ++Each group is subscribed at some @dfn{level} or other (1-9). The ones ++that have a lower level are ``more'' subscribed than the groups with a ++higher level. In fact, groups on levels 1-5 are considered ++@dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9 ++are @dfn{killed}. Commands for listing groups and scanning for new ++articles will all use the numeric prefix as @dfn{working level}. ++ ++@item killed groups ++@cindex killed groups ++No information on killed groups is stored or updated, which makes killed ++groups much easier to handle than subscribed groups. ++ ++@item zombie groups ++@cindex zombie groups ++Just like killed groups, only slightly less dead. ++ ++@item active file ++@cindex active file ++The news server has to keep track of what articles it carries, and what ++groups exist. All this information in stored in the active file, which ++is rather large, as you might surmise. ++ ++@item bogus groups ++@cindex bogus groups ++A group that exists in the @file{.newsrc} file, but isn't known to the ++server (i.e., it isn't in the active file), is a @emph{bogus group}. ++This means that the group probably doesn't exist (any more). ++ ++@item activating ++@cindex activating groups ++The act of asking the server for info on a group and computing the ++number of unread articles is called @dfn{activating the group}. ++Un-activated groups are listed with @samp{*} in the group buffer. ++ ++@item spool ++@cindex spool ++News servers store their articles locally in one fashion or other. ++One old-fashioned storage method is to have just one file per ++article. That's called a ``traditional spool''. ++ ++@item server ++@cindex server ++A machine one can connect to and get news (or mail) from. ++ ++@item select method ++@cindex select method ++A structure that specifies the back end, the server and the virtual ++server settings. ++ ++@item virtual server ++@cindex virtual server ++A named select method. Since a select method defines all there is to ++know about connecting to a (physical) server, taking the thing as a ++whole is a virtual server. ++ ++@item washing ++@cindex washing ++Taking a buffer and running it through a filter of some sort. The ++result will (more often than not) be cleaner and more pleasing than the ++original. ++ ++@item ephemeral groups ++@cindex ephemeral groups ++@cindex temporary groups ++Most groups store data on what articles you have read. @dfn{Ephemeral} ++groups are groups that will have no data stored---when you exit the ++group, it'll disappear into the aether. ++ ++@item solid groups ++@cindex solid groups ++This is the opposite of ephemeral groups. All groups listed in the ++group buffer are solid groups. ++ ++@item sparse articles ++@cindex sparse articles ++These are article placeholders shown in the summary buffer when ++@code{gnus-build-sparse-threads} has been switched on. ++ ++@item threading ++@cindex threading ++To put responses to articles directly after the articles they respond ++to---in a hierarchical fashion. ++ ++@item root ++@cindex root ++@cindex thread root ++The first article in a thread is the root. It is the ancestor of all ++articles in the thread. ++ ++@item parent ++@cindex parent ++An article that has responses. ++ ++@item child ++@cindex child ++An article that responds to a different article---its parent. ++ ++@item digest ++@cindex digest ++A collection of messages in one file. The most common digest format is ++specified by RFC 1153. ++ ++@item splitting ++@cindex splitting, terminology ++@cindex mail sorting ++@cindex mail filtering (splitting) ++The action of sorting your emails according to certain rules. Sometimes ++incorrectly called mail filtering. ++ ++@end table ++ ++ ++@page ++@node Customization ++@section Customization ++@cindex general customization ++ ++All variables are properly documented elsewhere in this manual. This ++section is designed to give general pointers on how to customize Gnus ++for some quite common situations. ++ ++@menu ++* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. ++* Slow Terminal Connection:: You run a remote Emacs. ++* Little Disk Space:: You feel that having large setup files is icky. ++* Slow Machine:: You feel like buying a faster machine. ++@end menu ++ ++ ++@node Slow/Expensive Connection ++@subsection Slow/Expensive Connection ++ ++If you run Emacs on a machine locally, and get your news from a machine ++over some very thin strings, you want to cut down on the amount of data ++Gnus has to get from the server. ++ ++@table @code ++ ++@item gnus-read-active-file ++Set this to @code{nil}, which will inhibit Gnus from requesting the ++entire active file from the server. This file is often very large. You ++also have to set @code{gnus-check-new-newsgroups} and ++@code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus ++doesn't suddenly decide to fetch the active file anyway. ++ ++@item gnus-nov-is-evil ++@vindex gnus-nov-is-evil ++Usually this one must @emph{always} be @code{nil} (which is the ++default). If, for example, you wish to not use @acronym{NOV} ++(@pxref{Terminology}) with the @code{nntp} back end (@pxref{Crosspost ++Handling}), set @code{nntp-nov-is-evil} to a non-@code{nil} value ++instead of setting this. But you normally do not need to set ++@code{nntp-nov-is-evil} since Gnus by itself will detect whether the ++@acronym{NNTP} server supports @acronym{NOV}. Anyway, grabbing article ++headers from the @acronym{NNTP} server will not be very fast if you tell ++Gnus not to use @acronym{NOV}. ++ ++As the variables for the other back ends, there are ++@code{nndiary-nov-is-evil}, @code{nndir-nov-is-evil}, ++@code{nnfolder-nov-is-evil}, @code{nnimap-nov-is-evil}, ++@code{nnml-nov-is-evil}, @code{nnspool-nov-is-evil}, and ++@code{nnwarchive-nov-is-evil}. Note that a non-@code{nil} value for ++@code{gnus-nov-is-evil} overrides all those variables.@footnote{Although ++the back ends @code{nnkiboze}, @code{nnslashdot}, @code{nnultimate}, and ++@code{nnwfm} don't have their own nn*-nov-is-evil.} ++@end table ++ ++ ++@node Slow Terminal Connection ++@subsection Slow Terminal Connection ++ ++Let's say you use your home computer for dialing up the system that runs ++Emacs and Gnus. If your modem is slow, you want to reduce (as much as ++possible) the amount of data sent over the wires. ++ ++@table @code ++ ++@item gnus-auto-center-summary ++Set this to @code{nil} to inhibit Gnus from re-centering the summary ++buffer all the time. If it is @code{vertical}, do only vertical ++re-centering. If it is neither @code{nil} nor @code{vertical}, do both ++horizontal and vertical recentering. ++ ++@item gnus-visible-headers ++Cut down on the headers included in the articles to the ++minimum. You can, in fact, make do without them altogether---most of the ++useful data is in the summary buffer, anyway. Set this variable to ++@samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need. ++ ++Use the following to enable all the available hiding features: ++@lisp ++(setq gnus-treat-hide-headers 'head ++ gnus-treat-hide-signature t ++ gnus-treat-hide-citation t) ++@end lisp ++ ++@item gnus-use-full-window ++By setting this to @code{nil}, you can make all the windows smaller. ++While this doesn't really cut down much generally, it means that you ++have to see smaller portions of articles before deciding that you didn't ++want to read them anyway. ++ ++@item gnus-thread-hide-subtree ++If this is non-@code{nil}, all threads in the summary buffer will be ++hidden initially. ++ ++ ++@item gnus-updated-mode-lines ++If this is @code{nil}, Gnus will not put information in the buffer mode ++lines, which might save some time. ++@end table ++ ++ ++@node Little Disk Space ++@subsection Little Disk Space ++@cindex disk space ++ ++The startup files can get rather large, so you may want to cut their ++sizes a bit if you are running out of space. ++ ++@table @code ++ ++@item gnus-save-newsrc-file ++If this is @code{nil}, Gnus will never save @file{.newsrc}---it will ++only save @file{.newsrc.eld}. This means that you will not be able to ++use any other newsreaders than Gnus. This variable is @code{t} by ++default. ++ ++@item gnus-read-newsrc-file ++If this is @code{nil}, Gnus will never read @file{.newsrc}---it will ++only read @file{.newsrc.eld}. This means that you will not be able to ++use any other newsreaders than Gnus. This variable is @code{t} by ++default. ++ ++@item gnus-save-killed-list ++If this is @code{nil}, Gnus will not save the list of dead groups. You ++should also set @code{gnus-check-new-newsgroups} to @code{ask-server} ++and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this ++variable to @code{nil}. This variable is @code{t} by default. ++ ++@end table ++ ++ ++@node Slow Machine ++@subsection Slow Machine ++@cindex slow machine ++ ++If you have a slow machine, or are just really impatient, there are a ++few things you can do to make Gnus run faster. ++ ++Set @code{gnus-check-new-newsgroups} and ++@code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster. ++ ++Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and ++@code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the ++summary buffer faster. Also @pxref{Slow/Expensive Connection}. ++ ++ ++@page ++@node Troubleshooting ++@section Troubleshooting ++@cindex troubleshooting ++ ++Gnus works @emph{so} well straight out of the box---I can't imagine any ++problems, really. ++ ++Ahem. ++ ++@enumerate ++ ++@item ++Make sure your computer is switched on. ++ ++@item ++Make sure that you really load the current Gnus version. If you have ++been running @sc{gnus}, you need to exit Emacs and start it up again before ++Gnus will work. ++ ++@item ++Try doing an @kbd{M-x gnus-version}. If you get something that looks ++like @c ++@samp{Gnus v5.13} @c Adjust ../Makefile.in if you change this line! ++@c ++you have the right files loaded. Otherwise you have some old @file{.el} ++files lying around. Delete these. ++ ++@item ++Read the help group (@kbd{G h} in the group buffer) for a ++@acronym{FAQ} and a how-to. ++ ++@item ++@vindex max-lisp-eval-depth ++Gnus works on many recursive structures, and in some extreme (and very ++rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at ++you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or ++something like that. ++@end enumerate ++ ++If all else fails, report the problem as a bug. ++ ++@cindex bugs ++@cindex reporting bugs ++ ++@kindex M-x gnus-bug ++@findex gnus-bug ++If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug} ++command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send ++me the backtrace. I will fix bugs, but I can only fix them if you send ++me a precise description as to how to reproduce the bug. ++ ++You really can never be too detailed in a bug report. Always use the ++@kbd{M-x gnus-bug} command when you make bug reports, even if it creates ++a 10Kb mail each time you use it, and even if you have sent me your ++environment 500 times before. I don't care. I want the full info each ++time. ++ ++It is also important to remember that I have no memory whatsoever. If ++you send a bug report, and I send you a reply, and then you just send ++back ``No, it's not! Moron!'', I will have no idea what you are ++insulting me about. Always over-explain everything. It's much easier ++for all of us---if I don't have all the information I need, I will just ++mail you and ask for more info, and everything takes more time. ++ ++If the problem you're seeing is very visual, and you can't quite explain ++it, copy the Emacs window to a file (with @code{xwd}, for instance), put ++it somewhere it can be reached, and include the URL of the picture in ++the bug report. ++ ++@cindex patches ++If you would like to contribute a patch to fix bugs or make ++improvements, please produce the patch using @samp{diff -u}. ++ ++@cindex edebug ++If you want to debug your problem further before reporting, possibly ++in order to solve the problem yourself and send a patch, you can use ++edebug. Debugging Lisp code is documented in the Elisp manual ++(@pxref{Debugging, , Debugging Lisp Programs, elisp, The GNU Emacs ++Lisp Reference Manual}). To get you started with edebug, consider if ++you discover some weird behavior when pressing @kbd{c}, the first ++step is to do @kbd{C-h k c} and click on the hyperlink (Emacs only) in ++the documentation buffer that leads you to the function definition, ++then press @kbd{M-x edebug-defun RET} with point inside that function, ++return to Gnus and press @kbd{c} to invoke the code. You will be ++placed in the lisp buffer and can single step using @kbd{SPC} and ++evaluate expressions using @kbd{M-:} or inspect variables using ++@kbd{C-h v}, abort execution with @kbd{q}, and resume execution with ++@kbd{c} or @kbd{g}. ++ ++@cindex elp ++@cindex profile ++@cindex slow ++Sometimes, a problem do not directly generate an elisp error but ++manifests itself by causing Gnus to be very slow. In these cases, you ++can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-g} when things are ++slow, and then try to analyze the backtrace (repeating the procedure ++helps isolating the real problem areas). ++ ++A fancier approach is to use the elisp profiler, ELP. The profiler is ++(or should be) fully documented elsewhere, but to get you started ++there are a few steps that need to be followed. First, instrument the ++part of Gnus you are interested in for profiling, e.g. @kbd{M-x ++elp-instrument-package RET gnus} or @kbd{M-x elp-instrument-package ++RET message}. Then perform the operation that is slow and press ++@kbd{M-x elp-results}. You will then see which operations that takes ++time, and can debug them further. If the entire operation takes much ++longer than the time spent in the slowest function in the profiler ++output, you probably profiled the wrong part of Gnus. To reset ++profiling statistics, use @kbd{M-x elp-reset-all}. @kbd{M-x ++elp-restore-all} is supposed to remove profiling, but given the ++complexities and dynamic code generation in Gnus, it might not always ++work perfectly. ++ ++@cindex gnu.emacs.gnus ++@cindex ding mailing list ++If you just need help, you are better off asking on ++@samp{gnu.emacs.gnus}. I'm not very helpful. You can also ask on ++@email{ding@@gnus.org, the ding mailing list}. Write to ++@email{ding-request@@gnus.org} to subscribe. ++ ++ ++@page ++@node Gnus Reference Guide ++@section Gnus Reference Guide ++ ++It is my hope that other people will figure out smart stuff that Gnus ++can do, and that other people will write those smart things as well. To ++facilitate that I thought it would be a good idea to describe the inner ++workings of Gnus. And some of the not-so-inner workings, while I'm at ++it. ++ ++You can never expect the internals of a program not to change, but I ++will be defining (in some details) the interface between Gnus and its ++back ends (this is written in stone), the format of the score files ++(ditto), data structures (some are less likely to change than others) ++and general methods of operation. ++ ++@menu ++* Gnus Utility Functions:: Common functions and variable to use. ++* Back End Interface:: How Gnus communicates with the servers. ++* Score File Syntax:: A BNF definition of the score file standard. ++* Headers:: How Gnus stores headers internally. ++* Ranges:: A handy format for storing mucho numbers. ++* Group Info:: The group info format. ++* Extended Interactive:: Symbolic prefixes and stuff. ++* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. ++* Various File Formats:: Formats of files that Gnus use. ++@end menu ++ ++ ++@node Gnus Utility Functions ++@subsection Gnus Utility Functions ++@cindex Gnus utility functions ++@cindex utility functions ++@cindex functions ++@cindex internal variables ++ ++When writing small functions to be run from hooks (and stuff), it's ++vital to have access to the Gnus internal functions and variables. ++Below is a list of the most common ones. ++ ++@table @code ++ ++@item gnus-newsgroup-name ++@vindex gnus-newsgroup-name ++This variable holds the name of the current newsgroup. ++ ++@item gnus-find-method-for-group ++@findex gnus-find-method-for-group ++A function that returns the select method for @var{group}. ++ ++@item gnus-group-real-name ++@findex gnus-group-real-name ++Takes a full (prefixed) Gnus group name, and returns the unprefixed ++name. ++ ++@item gnus-group-prefixed-name ++@findex gnus-group-prefixed-name ++Takes an unprefixed group name and a select method, and returns the full ++(prefixed) Gnus group name. ++ ++@item gnus-get-info ++@findex gnus-get-info ++Returns the group info list for @var{group}. ++ ++@item gnus-group-unread ++@findex gnus-group-unread ++The number of unread articles in @var{group}, or @code{t} if that is ++unknown. ++ ++@item gnus-active ++@findex gnus-active ++The active entry for @var{group}. ++ ++@item gnus-set-active ++@findex gnus-set-active ++Set the active entry for @var{group}. ++ ++@item gnus-add-current-to-buffer-list ++@findex gnus-add-current-to-buffer-list ++Adds the current buffer to the list of buffers to be killed on Gnus ++exit. ++ ++@item gnus-continuum-version ++@findex gnus-continuum-version ++Takes a Gnus version string as a parameter and returns a floating point ++number. Earlier versions will always get a lower number than later ++versions. ++ ++@item gnus-group-read-only-p ++@findex gnus-group-read-only-p ++Says whether @var{group} is read-only or not. ++ ++@item gnus-news-group-p ++@findex gnus-news-group-p ++Says whether @var{group} came from a news back end. ++ ++@item gnus-ephemeral-group-p ++@findex gnus-ephemeral-group-p ++Says whether @var{group} is ephemeral or not. ++ ++@item gnus-server-to-method ++@findex gnus-server-to-method ++Returns the select method corresponding to @var{server}. ++ ++@item gnus-server-equal ++@findex gnus-server-equal ++Says whether two virtual servers are equal. ++ ++@item gnus-group-native-p ++@findex gnus-group-native-p ++Says whether @var{group} is native or not. ++ ++@item gnus-group-secondary-p ++@findex gnus-group-secondary-p ++Says whether @var{group} is secondary or not. ++ ++@item gnus-group-foreign-p ++@findex gnus-group-foreign-p ++Says whether @var{group} is foreign or not. ++ ++@item gnus-group-find-parameter ++@findex gnus-group-find-parameter ++Returns the parameter list of @var{group}. If given a second parameter, ++returns the value of that parameter for @var{group}. ++ ++@item gnus-group-set-parameter ++@findex gnus-group-set-parameter ++Takes three parameters; @var{group}, @var{parameter} and @var{value}. ++ ++@item gnus-narrow-to-body ++@findex gnus-narrow-to-body ++Narrows the current buffer to the body of the article. ++ ++@item gnus-check-backend-function ++@findex gnus-check-backend-function ++Takes two parameters, @var{function} and @var{group}. If the back end ++@var{group} comes from supports @var{function}, return non-@code{nil}. ++ ++@lisp ++(gnus-check-backend-function "request-scan" "nnml:misc") ++@result{} t ++@end lisp ++ ++@item gnus-read-method ++@findex gnus-read-method ++Prompts the user for a select method. ++ ++@end table ++ ++ ++@node Back End Interface ++@subsection Back End Interface ++ ++Gnus doesn't know anything about @acronym{NNTP}, spools, mail or virtual ++groups. It only knows how to talk to @dfn{virtual servers}. A virtual ++server is a @dfn{back end} and some @dfn{back end variables}. As examples ++of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As ++examples of the latter we have @code{nntp-port-number} and ++@code{nnmbox-directory}. ++ ++When Gnus asks for information from a back end---say @code{nntp}---on ++something, it will normally include a virtual server name in the ++function parameters. (If not, the back end should use the ``current'' ++virtual server.) For instance, @code{nntp-request-list} takes a virtual ++server as its only (optional) parameter. If this virtual server hasn't ++been opened, the function should fail. ++ ++Note that a virtual server name has no relation to some physical server ++name. Take this example: ++ ++@lisp ++(nntp "odd-one" ++ (nntp-address "ifi.uio.no") ++ (nntp-port-number 4324)) ++@end lisp ++ ++Here the virtual server name is @samp{odd-one} while the name of ++the physical server is @samp{ifi.uio.no}. ++ ++The back ends should be able to switch between several virtual servers. ++The standard back ends implement this by keeping an alist of virtual ++server environments that they pull down/push up when needed. ++ ++There are two groups of interface functions: @dfn{required functions}, ++which must be present, and @dfn{optional functions}, which Gnus will ++always check for presence before attempting to call 'em. ++ ++All these functions are expected to return data in the buffer ++@code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat ++unfortunately named, but we'll have to live with it. When I talk about ++@dfn{resulting data}, I always refer to the data in that buffer. When I ++talk about @dfn{return value}, I talk about the function value returned by ++the function call. Functions that fail should return @code{nil} as the ++return value. ++ ++Some back ends could be said to be @dfn{server-forming} back ends, and ++some might be said not to be. The latter are back ends that generally ++only operate on one group at a time, and have no concept of ``server'' ++---they have a group, and they deliver info on that group and nothing ++more. ++ ++Gnus identifies each message by way of group name and article number. A ++few remarks about these article numbers might be useful. First of all, ++the numbers are positive integers. Secondly, it is normally not ++possible for later articles to ``re-use'' older article numbers without ++confusing Gnus. That is, if a group has ever contained a message ++numbered 42, then no other message may get that number, or Gnus will get ++mightily confused.@footnote{See the function ++@code{nnchoke-request-update-info}, @ref{Optional Back End Functions}.} ++Third, article numbers must be assigned in order of arrival in the ++group; this is not necessarily the same as the date of the message. ++ ++The previous paragraph already mentions all the ``hard'' restrictions that ++article numbers must fulfill. But it seems that it might be useful to ++assign @emph{consecutive} article numbers, for Gnus gets quite confused ++if there are holes in the article numbering sequence. However, due to ++the ``no-reuse'' restriction, holes cannot be avoided altogether. It's ++also useful for the article numbers to start at 1 to avoid running out ++of numbers as long as possible. ++ ++Note that by convention, back ends are named @code{nnsomething}, but ++Gnus also comes with some @code{nnnotbackends}, such as ++@file{nnheader.el}, @file{nnmail.el} and @file{nnoo.el}. ++ ++In the examples and definitions I will refer to the imaginary back end ++@code{nnchoke}. ++ ++@cindex @code{nnchoke} ++ ++@menu ++* Required Back End Functions:: Functions that must be implemented. ++* Optional Back End Functions:: Functions that need not be implemented. ++* Error Messaging:: How to get messages and report errors. ++* Writing New Back Ends:: Extending old back ends. ++* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end. ++* Mail-like Back Ends:: Some tips on mail back ends. ++@end menu ++ ++ ++@node Required Back End Functions ++@subsubsection Required Back End Functions ++ ++@table @code ++ ++@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD) ++ ++@var{articles} is either a range of article numbers or a list of ++@code{Message-ID}s. Current back ends do not fully support either---only ++sequences (lists) of article numbers, and most back ends do not support ++retrieval of @code{Message-ID}s. But they should try for both. ++ ++The result data should either be HEADs or @acronym{NOV} lines, and the result ++value should either be @code{headers} or @code{nov} to reflect this. ++This might later be expanded to @code{various}, which will be a mixture ++of HEADs and @acronym{NOV} lines, but this is currently not supported by Gnus. ++ ++If @var{fetch-old} is non-@code{nil} it says to try fetching ``extra ++headers'', in some meaning of the word. This is generally done by ++fetching (at most) @var{fetch-old} extra headers less than the smallest ++article number in @code{articles}, and filling the gaps as well. The ++presence of this parameter can be ignored if the back end finds it ++cumbersome to follow the request. If this is non-@code{nil} and not a ++number, do maximum fetches. ++ ++Here's an example HEAD: ++ ++@example ++221 1056 Article retrieved. ++Path: ifi.uio.no!sturles ++From: sturles@@ifi.uio.no (Sturle Sunde) ++Newsgroups: ifi.discussion ++Subject: Re: Something very droll ++Date: 27 Oct 1994 14:02:57 +0100 ++Organization: Dept. of Informatics, University of Oslo, Norway ++Lines: 26 ++Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no> ++References: <38jdmq$4qu@@visbur.ifi.uio.no> ++NNTP-Posting-Host: holmenkollen.ifi.uio.no ++. ++@end example ++ ++So a @code{headers} return value would imply that there's a number of ++these in the data buffer. ++ ++Here's a BNF definition of such a buffer: ++ ++@example ++headers = *head ++head = error / valid-head ++error-message = [ "4" / "5" ] 2number " " eol ++valid-head = valid-message *header "." eol ++valid-message = "221 " " Article retrieved." eol ++header = eol ++@end example ++ ++@cindex BNF ++(The version of BNF used here is the one used in RFC822.) ++ ++If the return value is @code{nov}, the data buffer should contain ++@dfn{network overview database} lines. These are basically fields ++separated by tabs. ++ ++@example ++nov-buffer = *nov-line ++nov-line = field 7*8[ field ] eol ++field = ++@end example ++ ++For a closer look at what should be in those fields, ++@pxref{Headers}. ++ ++ ++@item (nnchoke-open-server SERVER &optional DEFINITIONS) ++ ++@var{server} is here the virtual server name. @var{definitions} is a ++list of @code{(VARIABLE VALUE)} pairs that define this virtual server. ++ ++If the server can't be opened, no error should be signaled. The back end ++may then choose to refuse further attempts at connecting to this ++server. In fact, it should do so. ++ ++If the server is opened already, this function should return a ++non-@code{nil} value. There should be no data returned. ++ ++ ++@item (nnchoke-close-server &optional SERVER) ++ ++Close connection to @var{server} and free all resources connected ++to it. Return @code{nil} if the server couldn't be closed for some ++reason. ++ ++There should be no data returned. ++ ++ ++@item (nnchoke-request-close) ++ ++Close connection to all servers and free all resources that the back end ++have reserved. All buffers that have been created by that back end ++should be killed. (Not the @code{nntp-server-buffer}, though.) This ++function is generally only called when Gnus is shutting down. ++ ++There should be no data returned. ++ ++ ++@item (nnchoke-server-opened &optional SERVER) ++ ++If @var{server} is the current virtual server, and the connection to the ++physical server is alive, then this function should return a ++non-@code{nil} value. This function should under no circumstances ++attempt to reconnect to a server we have lost connection to. ++ ++There should be no data returned. ++ ++ ++@item (nnchoke-status-message &optional SERVER) ++ ++This function should return the last error message from @var{server}. ++ ++There should be no data returned. ++ ++ ++@item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER) ++ ++The result data from this function should be the article specified by ++@var{article}. This might either be a @code{Message-ID} or a number. ++It is optional whether to implement retrieval by @code{Message-ID}, but ++it would be nice if that were possible. ++ ++If @var{to-buffer} is non-@code{nil}, the result data should be returned ++in this buffer instead of the normal data buffer. This is to make it ++possible to avoid copying large amounts of data from one buffer to ++another, while Gnus mainly requests articles to be inserted directly ++into its article buffer. ++ ++If it is at all possible, this function should return a cons cell where ++the @code{car} is the group name the article was fetched from, and the @code{cdr} is ++the article number. This will enable Gnus to find out what the real ++group and article numbers are when fetching articles by ++@code{Message-ID}. If this isn't possible, @code{t} should be returned ++on successful article retrieval. ++ ++ ++@item (nnchoke-request-group GROUP &optional SERVER FAST) ++ ++Get data on @var{group}. This function also has the side effect of ++making @var{group} the current group. ++ ++If @var{fast}, don't bother to return useful data, just make @var{group} ++the current group. ++ ++Here's an example of some result data and a definition of the same: ++ ++@example ++211 56 1000 1059 ifi.discussion ++@end example ++ ++The first number is the status, which should be 211. Next is the ++total number of articles in the group, the lowest article number, the ++highest article number, and finally the group name. Note that the total ++number of articles may be less than one might think while just ++considering the highest and lowest article numbers, but some articles ++may have been canceled. Gnus just discards the total-number, so ++whether one should take the bother to generate it properly (if that is a ++problem) is left as an exercise to the reader. If the group contains no ++articles, the lowest article number should be reported as 1 and the ++highest as 0. ++ ++@example ++group-status = [ error / info ] eol ++error = [ "4" / "5" ] 2 " " ++info = "211 " 3* [ " " ] ++@end example ++ ++ ++@item (nnchoke-close-group GROUP &optional SERVER) ++ ++Close @var{group} and free any resources connected to it. This will be ++a no-op on most back ends. ++ ++There should be no data returned. ++ ++ ++@item (nnchoke-request-list &optional SERVER) ++ ++Return a list of all groups available on @var{server}. And that means ++@emph{all}. ++ ++Here's an example from a server that only carries two groups: ++ ++@example ++ifi.test 0000002200 0000002000 y ++ifi.discussion 3324 3300 n ++@end example ++ ++On each line we have a group name, then the highest article number in ++that group, the lowest article number, and finally a flag. If the group ++contains no articles, the lowest article number should be reported as 1 ++and the highest as 0. ++ ++@example ++active-file = *active-line ++active-line = name " " " " " " flags eol ++name = ++flags = "n" / "y" / "m" / "x" / "j" / "=" name ++@end example ++ ++The flag says whether the group is read-only (@samp{n}), is moderated ++(@samp{m}), is dead (@samp{x}), is aliased to some other group ++(@samp{=other-group}) or none of the above (@samp{y}). ++ ++ ++@item (nnchoke-request-post &optional SERVER) ++ ++This function should post the current buffer. It might return whether ++the posting was successful or not, but that's not required. If, for ++instance, the posting is done asynchronously, it has generally not been ++completed by the time this function concludes. In that case, this ++function should set up some kind of sentinel to beep the user loud and ++clear if the posting could not be completed. ++ ++There should be no result data from this function. ++ ++@end table ++ ++ ++@node Optional Back End Functions ++@subsubsection Optional Back End Functions ++ ++@table @code ++ ++@item (nnchoke-retrieve-groups GROUPS &optional SERVER) ++ ++@var{groups} is a list of groups, and this function should request data ++on all those groups. How it does it is of no concern to Gnus, but it ++should attempt to do this in a speedy fashion. ++ ++The return value of this function can be either @code{active} or ++@code{group}, which says what the format of the result data is. The ++former is in the same format as the data from ++@code{nnchoke-request-list}, while the latter is a buffer full of lines ++in the same format as @code{nnchoke-request-group} gives. ++ ++@example ++group-buffer = *active-line / *group-status ++@end example ++ ++ ++@item (nnchoke-request-update-info GROUP INFO &optional SERVER) ++ ++A Gnus group info (@pxref{Group Info}) is handed to the back end for ++alterations. This comes in handy if the back end really carries all ++the information (as is the case with virtual and imap groups). This ++function should destructively alter the info to suit its needs, and ++should return a non-@code{nil} value (exceptionally, ++@code{nntp-request-update-info} always returns @code{nil} not to waste ++the network resources). ++ ++There should be no result data from this function. ++ ++ ++@item (nnchoke-request-type GROUP &optional ARTICLE) ++ ++When the user issues commands for ``sending news'' (@kbd{F} in the ++summary buffer, for instance), Gnus has to know whether the article the ++user is following up on is news or mail. This function should return ++@code{news} if @var{article} in @var{group} is news, @code{mail} if it ++is mail and @code{unknown} if the type can't be decided. (The ++@var{article} parameter is necessary in @code{nnvirtual} groups which ++might very well combine mail groups and news groups.) Both @var{group} ++and @var{article} may be @code{nil}. ++ ++There should be no result data from this function. ++ ++ ++@item (nnchoke-request-set-mark GROUP ACTION &optional SERVER) ++ ++Set/remove/add marks on articles. Normally Gnus handles the article ++marks (such as read, ticked, expired etc) internally, and store them in ++@file{~/.newsrc.eld}. Some back ends (such as @acronym{IMAP}) however carry ++all information about the articles on the server, so Gnus need to ++propagate the mark information to the server. ++ ++@var{action} is a list of mark setting requests, having this format: ++ ++@example ++(RANGE ACTION MARK) ++@end example ++ ++@var{range} is a range of articles you wish to update marks on. ++@var{action} is @code{add} or @code{del}, used to add marks or remove ++marks (preserving all marks not mentioned). @var{mark} is a list of ++marks; where each mark is a symbol. Currently used marks are ++@code{read}, @code{tick}, @code{reply}, @code{expire}, @code{killed}, ++@code{dormant}, @code{save}, @code{download}, @code{unsend}, ++@code{forward} and @code{recent}, but your back end should, if ++possible, not limit itself to these. ++ ++Given contradictory actions, the last action in the list should be the ++effective one. That is, if your action contains a request to add the ++@code{tick} mark on article 1 and, later in the list, a request to ++remove the mark on the same article, the mark should in fact be removed. ++ ++An example action list: ++ ++@example ++(((5 12 30) 'del '(tick)) ++ ((10 . 90) 'add '(read expire)) ++ ((92 94) 'del '(read))) ++@end example ++ ++The function should return a range of articles it wasn't able to set the ++mark on (currently not used for anything). ++ ++There should be no result data from this function. ++ ++@item (nnchoke-request-update-mark GROUP ARTICLE MARK) ++ ++If the user tries to set a mark that the back end doesn't like, this ++function may change the mark. Gnus will use whatever this function ++returns as the mark for @var{article} instead of the original ++@var{mark}. If the back end doesn't care, it must return the original ++@var{mark}, and not @code{nil} or any other type of garbage. ++ ++The only use for this I can see is what @code{nnvirtual} does with ++it---if a component group is auto-expirable, marking an article as read ++in the virtual group should result in the article being marked as ++expirable. ++ ++There should be no result data from this function. ++ ++ ++@item (nnchoke-request-scan &optional GROUP SERVER) ++ ++This function may be called at any time (by Gnus or anything else) to ++request that the back end check for incoming articles, in one way or ++another. A mail back end will typically read the spool file or query ++the @acronym{POP} server when this function is invoked. The ++@var{group} doesn't have to be heeded---if the back end decides that ++it is too much work just scanning for a single group, it may do a ++total scan of all groups. It would be nice, however, to keep things ++local if that's practical. ++ ++There should be no result data from this function. ++ ++ ++@item (nnchoke-request-group-description GROUP &optional SERVER) ++ ++The result data from this function should be a description of ++@var{group}. ++ ++@example ++description-line = name description eol ++name = ++description = ++@end example ++ ++@item (nnchoke-request-list-newsgroups &optional SERVER) ++ ++The result data from this function should be the description of all ++groups available on the server. ++ ++@example ++description-buffer = *description-line ++@end example ++ ++ ++@item (nnchoke-request-newgroups DATE &optional SERVER) ++ ++The result data from this function should be all groups that were ++created after @samp{date}, which is in normal human-readable date format ++(i.e., the date format used in mail and news headers, and returned by ++the function @code{message-make-date} by default). The data should be ++in the active buffer format. ++ ++It is okay for this function to return ``too many'' groups; some back ends ++might find it cheaper to return the full list of groups, rather than ++just the new groups. But don't do this for back ends with many groups. ++Normally, if the user creates the groups herself, there won't be too ++many groups, so @code{nnml} and the like are probably safe. But for ++back ends like @code{nntp}, where the groups have been created by the ++server, it is quite likely that there can be many groups. ++ ++ ++@item (nnchoke-request-create-group GROUP &optional SERVER) ++ ++This function should create an empty group with name @var{group}. ++ ++There should be no return data. ++ ++ ++@item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE) ++ ++This function should run the expiry process on all articles in the ++@var{articles} range (which is currently a simple list of article ++numbers.) It is left up to the back end to decide how old articles ++should be before they are removed by this function. If @var{force} is ++non-@code{nil}, all @var{articles} should be deleted, no matter how new ++they are. ++ ++This function should return a list of articles that it did not/was not ++able to delete. ++ ++There should be no result data returned. ++ ++ ++@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM &optional LAST) ++ ++This function should move @var{article} (which is a number) from ++@var{group} by calling @var{accept-form}. ++ ++This function should ready the article in question for moving by ++removing any header lines it has added to the article, and generally ++should ``tidy up'' the article. Then it should @code{eval} ++@var{accept-form} in the buffer where the ``tidy'' article is. This ++will do the actual copying. If this @code{eval} returns a ++non-@code{nil} value, the article should be removed. ++ ++If @var{last} is @code{nil}, that means that there is a high likelihood ++that there will be more requests issued shortly, so that allows some ++optimizations. ++ ++The function should return a cons where the @code{car} is the group name and ++the @code{cdr} is the article number that the article was entered as. ++ ++There should be no data returned. ++ ++ ++@item (nnchoke-request-accept-article GROUP &optional SERVER LAST) ++ ++This function takes the current buffer and inserts it into @var{group}. ++If @var{last} in @code{nil}, that means that there will be more calls to ++this function in short order. ++ ++The function should return a cons where the @code{car} is the group name and ++the @code{cdr} is the article number that the article was entered as. ++ ++The group should exist before the back end is asked to accept the ++article for that group. ++ ++There should be no data returned. ++ ++ ++@item (nnchoke-request-replace-article ARTICLE GROUP BUFFER) ++ ++This function should remove @var{article} (which is a number) from ++@var{group} and insert @var{buffer} there instead. ++ ++There should be no data returned. ++ ++ ++@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER) ++ ++This function should delete @var{group}. If @var{force}, it should ++really delete all the articles in the group, and then delete the group ++itself. (If there is such a thing as ``the group itself''.) ++ ++There should be no data returned. ++ ++ ++@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER) ++ ++This function should rename @var{group} into @var{new-name}. All ++articles in @var{group} should move to @var{new-name}. ++ ++There should be no data returned. ++ ++@end table ++ ++ ++@node Error Messaging ++@subsubsection Error Messaging ++ ++@findex nnheader-report ++@findex nnheader-get-report ++The back ends should use the function @code{nnheader-report} to report ++error conditions---they should not raise errors when they aren't able to ++perform a request. The first argument to this function is the back end ++symbol, and the rest are interpreted as arguments to @code{format} if ++there are multiple of them, or just a string if there is one of them. ++This function must always returns @code{nil}. ++ ++@lisp ++(nnheader-report 'nnchoke "You did something totally bogus") ++ ++(nnheader-report 'nnchoke "Could not request group %s" group) ++@end lisp ++ ++Gnus, in turn, will call @code{nnheader-get-report} when it gets a ++@code{nil} back from a server, and this function returns the most ++recently reported message for the back end in question. This function ++takes one argument---the server symbol. ++ ++Internally, these functions access @var{back-end}@code{-status-string}, ++so the @code{nnchoke} back end will have its error message stored in ++@code{nnchoke-status-string}. ++ ++ ++@node Writing New Back Ends ++@subsubsection Writing New Back Ends ++ ++Many back ends are quite similar. @code{nnml} is just like ++@code{nnspool}, but it allows you to edit the articles on the server. ++@code{nnmh} is just like @code{nnml}, but it doesn't use an active file, ++and it doesn't maintain overview databases. @code{nndir} is just like ++@code{nnml}, but it has no concept of ``groups'', and it doesn't allow ++editing articles. ++ ++It would make sense if it were possible to ``inherit'' functions from ++back ends when writing new back ends. And, indeed, you can do that if you ++want to. (You don't have to if you don't want to, of course.) ++ ++All the back ends declare their public variables and functions by using a ++package called @code{nnoo}. ++ ++To inherit functions from other back ends (and allow other back ends to ++inherit functions from the current back end), you should use the ++following macros: ++ ++@table @code ++ ++@item nnoo-declare ++This macro declares the first parameter to be a child of the subsequent ++parameters. For instance: ++ ++@lisp ++(nnoo-declare nndir ++ nnml nnmh) ++@end lisp ++ ++@code{nndir} has declared here that it intends to inherit functions from ++both @code{nnml} and @code{nnmh}. ++ ++@item defvoo ++This macro is equivalent to @code{defvar}, but registers the variable as ++a public server variable. Most state-oriented variables should be ++declared with @code{defvoo} instead of @code{defvar}. ++ ++In addition to the normal @code{defvar} parameters, it takes a list of ++variables in the parent back ends to map the variable to when executing ++a function in those back ends. ++ ++@lisp ++(defvoo nndir-directory nil ++ "Where nndir will look for groups." ++ nnml-current-directory nnmh-current-directory) ++@end lisp ++ ++This means that @code{nnml-current-directory} will be set to ++@code{nndir-directory} when an @code{nnml} function is called on behalf ++of @code{nndir}. (The same with @code{nnmh}.) ++ ++@item nnoo-define-basics ++This macro defines some common functions that almost all back ends should ++have. ++ ++@lisp ++(nnoo-define-basics nndir) ++@end lisp ++ ++@item deffoo ++This macro is just like @code{defun} and takes the same parameters. In ++addition to doing the normal @code{defun} things, it registers the ++function as being public so that other back ends can inherit it. ++ ++@item nnoo-map-functions ++This macro allows mapping of functions from the current back end to ++functions from the parent back ends. ++ ++@lisp ++(nnoo-map-functions nndir ++ (nnml-retrieve-headers 0 nndir-current-group 0 0) ++ (nnmh-request-article 0 nndir-current-group 0 0)) ++@end lisp ++ ++This means that when @code{nndir-retrieve-headers} is called, the first, ++third, and fourth parameters will be passed on to ++@code{nnml-retrieve-headers}, while the second parameter is set to the ++value of @code{nndir-current-group}. ++ ++@item nnoo-import ++This macro allows importing functions from back ends. It should be the ++last thing in the source file, since it will only define functions that ++haven't already been defined. ++ ++@lisp ++(nnoo-import nndir ++ (nnmh ++ nnmh-request-list ++ nnmh-request-newgroups) ++ (nnml)) ++@end lisp ++ ++This means that calls to @code{nndir-request-list} should just be passed ++on to @code{nnmh-request-list}, while all public functions from ++@code{nnml} that haven't been defined in @code{nndir} yet should be ++defined now. ++ ++@end table ++ ++Below is a slightly shortened version of the @code{nndir} back end. ++ ++@lisp ++;;; @r{nndir.el --- single directory newsgroup access for Gnus} ++;; @r{Copyright (C) 1995,1996 Free Software Foundation, Inc.} ++ ++;;; @r{Code:} ++ ++(require 'nnheader) ++(require 'nnmh) ++(require 'nnml) ++(require 'nnoo) ++(eval-when-compile (require 'cl)) ++ ++(nnoo-declare nndir ++ nnml nnmh) ++ ++(defvoo nndir-directory nil ++ "Where nndir will look for groups." ++ nnml-current-directory nnmh-current-directory) ++ ++(defvoo nndir-nov-is-evil nil ++ "*Non-nil means that nndir will never retrieve NOV headers." ++ nnml-nov-is-evil) ++ ++(defvoo nndir-current-group "" ++ nil ++ nnml-current-group nnmh-current-group) ++(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory) ++(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail) ++ ++(defvoo nndir-status-string "" nil nnmh-status-string) ++(defconst nndir-version "nndir 1.0") ++ ++;;; @r{Interface functions.} ++ ++(nnoo-define-basics nndir) ++ ++(deffoo nndir-open-server (server &optional defs) ++ (setq nndir-directory ++ (or (cadr (assq 'nndir-directory defs)) ++ server)) ++ (unless (assq 'nndir-directory defs) ++ (push `(nndir-directory ,server) defs)) ++ (push `(nndir-current-group ++ ,(file-name-nondirectory ++ (directory-file-name nndir-directory))) ++ defs) ++ (push `(nndir-top-directory ++ ,(file-name-directory (directory-file-name nndir-directory))) ++ defs) ++ (nnoo-change-server 'nndir server defs)) ++ ++(nnoo-map-functions nndir ++ (nnml-retrieve-headers 0 nndir-current-group 0 0) ++ (nnmh-request-article 0 nndir-current-group 0 0) ++ (nnmh-request-group nndir-current-group 0 0) ++ (nnmh-close-group nndir-current-group 0)) ++ ++(nnoo-import nndir ++ (nnmh ++ nnmh-status-message ++ nnmh-request-list ++ nnmh-request-newgroups)) ++ ++(provide 'nndir) ++@end lisp ++ ++ ++@node Hooking New Back Ends Into Gnus ++@subsubsection Hooking New Back Ends Into Gnus ++ ++@vindex gnus-valid-select-methods ++@findex gnus-declare-backend ++Having Gnus start using your new back end is rather easy---you just ++declare it with the @code{gnus-declare-backend} functions. This will ++enter the back end into the @code{gnus-valid-select-methods} variable. ++ ++@code{gnus-declare-backend} takes two parameters---the back end name and ++an arbitrary number of @dfn{abilities}. ++ ++Here's an example: ++ ++@lisp ++(gnus-declare-backend "nnchoke" 'mail 'respool 'address) ++@end lisp ++ ++The above line would then go in the @file{nnchoke.el} file. ++ ++The abilities can be: ++ ++@table @code ++@item mail ++This is a mailish back end---followups should (probably) go via mail. ++@item post ++This is a newsish back end---followups should (probably) go via news. ++@item post-mail ++This back end supports both mail and news. ++@item none ++This is neither a post nor mail back end---it's something completely ++different. ++@item respool ++It supports respooling---or rather, it is able to modify its source ++articles and groups. ++@item address ++The name of the server should be in the virtual server name. This is ++true for almost all back ends. ++@item prompt-address ++The user should be prompted for an address when doing commands like ++@kbd{B} in the group buffer. This is true for back ends like ++@code{nntp}, but not @code{nnmbox}, for instance. ++@end table ++ ++ ++@node Mail-like Back Ends ++@subsubsection Mail-like Back Ends ++ ++One of the things that separate the mail back ends from the rest of the ++back ends is the heavy dependence by most of the mail back ends on ++common functions in @file{nnmail.el}. For instance, here's the ++definition of @code{nnml-request-scan}: ++ ++@lisp ++(deffoo nnml-request-scan (&optional group server) ++ (setq nnml-article-file-alist nil) ++ (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group)) ++@end lisp ++ ++It simply calls @code{nnmail-get-new-mail} with a few parameters, ++and @code{nnmail} takes care of all the moving and splitting of the ++mail. ++ ++This function takes four parameters. ++ ++@table @var ++@item method ++This should be a symbol to designate which back end is responsible for ++the call. ++ ++@item exit-function ++This function should be called after the splitting has been performed. ++ ++@item temp-directory ++Where the temporary files should be stored. ++ ++@item group ++This optional argument should be a group name if the splitting is to be ++performed for one group only. ++@end table ++ ++@code{nnmail-get-new-mail} will call @var{back-end}@code{-save-mail} to ++save each article. @var{back-end}@code{-active-number} will be called to ++find the article number assigned to this article. ++ ++The function also uses the following variables: ++@var{back-end}@code{-get-new-mail} (to see whether to get new mail for ++this back end); and @var{back-end}@code{-group-alist} and ++@var{back-end}@code{-active-file} to generate the new active file. ++@var{back-end}@code{-group-alist} should be a group-active alist, like ++this: ++ ++@example ++(("a-group" (1 . 10)) ++ ("some-group" (34 . 39))) ++@end example ++ ++ ++@node Score File Syntax ++@subsection Score File Syntax ++ ++Score files are meant to be easily parseable, but yet extremely ++mallable. It was decided that something that had the same read syntax ++as an Emacs Lisp list would fit that spec. ++ ++Here's a typical score file: ++ ++@lisp ++(("summary" ++ ("win95" -10000 nil s) ++ ("Gnus")) ++ ("from" ++ ("Lars" -1000)) ++ (mark -100)) ++@end lisp ++ ++BNF definition of a score file: ++ ++@example ++score-file = "" / "(" *element ")" ++element = rule / atom ++rule = string-rule / number-rule / date-rule ++string-rule = "(" quote string-header quote space *string-match ")" ++number-rule = "(" quote number-header quote space *number-match ")" ++date-rule = "(" quote date-header quote space *date-match ")" ++quote = ++string-header = "subject" / "from" / "references" / "message-id" / ++ "xref" / "body" / "head" / "all" / "followup" ++number-header = "lines" / "chars" ++date-header = "date" ++string-match = "(" quote quote [ "" / [ space score [ "" / ++ space date [ "" / [ space string-match-t ] ] ] ] ] ")" ++score = "nil" / ++date = "nil" / ++string-match-t = "nil" / "s" / "substring" / "S" / "Substring" / ++ "r" / "regex" / "R" / "Regex" / ++ "e" / "exact" / "E" / "Exact" / ++ "f" / "fuzzy" / "F" / "Fuzzy" ++number-match = "(" [ "" / [ space score [ "" / ++ space date [ "" / [ space number-match-t ] ] ] ] ] ")" ++number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<=" ++date-match = "(" quote quote [ "" / [ space score [ "" / ++ space date [ "" / [ space date-match-t ] ] ] ] ")" ++date-match-t = "nil" / "at" / "before" / "after" ++atom = "(" [ required-atom / optional-atom ] ")" ++required-atom = mark / expunge / mark-and-expunge / files / ++ exclude-files / read-only / touched ++optional-atom = adapt / local / eval ++mark = "mark" space nil-or-number ++nil-or-number = "nil" / ++expunge = "expunge" space nil-or-number ++mark-and-expunge = "mark-and-expunge" space nil-or-number ++files = "files" *[ space ] ++exclude-files = "exclude-files" *[ space ] ++read-only = "read-only" [ space "nil" / space "t" ] ++adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ] ++adapt-rule = "(" *[ *[ "(" ")" ] ")" ++local = "local" *[ space "(" space
")" ] ++eval = "eval" space ++space = *[ " " / / ] ++@end example ++ ++Any unrecognized elements in a score file should be ignored, but not ++discarded. ++ ++As you can see, white space is needed, but the type and amount of white ++space is irrelevant. This means that formatting of the score file is ++left up to the programmer---if it's simpler to just spew it all out on ++one looong line, then that's ok. ++ ++The meaning of the various atoms are explained elsewhere in this ++manual (@pxref{Score File Format}). ++ ++ ++@node Headers ++@subsection Headers ++ ++Internally Gnus uses a format for storing article headers that ++corresponds to the @acronym{NOV} format in a mysterious fashion. One could ++almost suspect that the author looked at the @acronym{NOV} specification and ++just shamelessly @emph{stole} the entire thing, and one would be right. ++ ++@dfn{Header} is a severely overloaded term. ``Header'' is used in ++RFC 1036 to talk about lines in the head of an article (e.g., ++@code{From}). It is used by many people as a synonym for ++``head''---``the header and the body''. (That should be avoided, in my ++opinion.) And Gnus uses a format internally that it calls ``header'', ++which is what I'm talking about here. This is a 9-element vector, ++basically, with each header (ouch) having one slot. ++ ++These slots are, in order: @code{number}, @code{subject}, @code{from}, ++@code{date}, @code{id}, @code{references}, @code{chars}, @code{lines}, ++@code{xref}, and @code{extra}. There are macros for accessing and ++setting these slots---they all have predictable names beginning with ++@code{mail-header-} and @code{mail-header-set-}, respectively. ++ ++All these slots contain strings, except the @code{extra} slot, which ++contains an alist of header/value pairs (@pxref{To From Newsgroups}). ++ ++ ++@node Ranges ++@subsection Ranges ++ ++@sc{gnus} introduced a concept that I found so useful that I've started ++using it a lot and have elaborated on it greatly. ++ ++The question is simple: If you have a large amount of objects that are ++identified by numbers (say, articles, to take a @emph{wild} example) ++that you want to qualify as being ``included'', a normal sequence isn't ++very useful. (A 200,000 length sequence is a bit long-winded.) ++ ++The solution is as simple as the question: You just collapse the ++sequence. ++ ++@example ++(1 2 3 4 5 6 10 11 12) ++@end example ++ ++is transformed into ++ ++@example ++((1 . 6) (10 . 12)) ++@end example ++ ++To avoid having those nasty @samp{(13 . 13)} elements to denote a ++lonesome object, a @samp{13} is a valid element: ++ ++@example ++((1 . 6) 7 (10 . 12)) ++@end example ++ ++This means that comparing two ranges to find out whether they are equal ++is slightly tricky: ++ ++@example ++((1 . 5) 7 8 (10 . 12)) ++@end example ++ ++and ++ ++@example ++((1 . 5) (7 . 8) (10 . 12)) ++@end example ++ ++are equal. In fact, any non-descending list is a range: ++ ++@example ++(1 2 3 4 5) ++@end example ++ ++is a perfectly valid range, although a pretty long-winded one. This is ++also valid: ++ ++@example ++(1 . 5) ++@end example ++ ++and is equal to the previous range. ++ ++Here's a BNF definition of ranges. Of course, one must remember the ++semantic requirement that the numbers are non-descending. (Any number ++of repetition of the same number is allowed, but apt to disappear in ++range handling.) ++ ++@example ++range = simple-range / normal-range ++simple-range = "(" number " . " number ")" ++normal-range = "(" start-contents ")" ++contents = "" / simple-range *[ " " contents ] / ++ number *[ " " contents ] ++@end example ++ ++Gnus currently uses ranges to keep track of read articles and article ++marks. I plan on implementing a number of range operators in C if The ++Powers That Be are willing to let me. (I haven't asked yet, because I ++need to do some more thinking on what operators I need to make life ++totally range-based without ever having to convert back to normal ++sequences.) ++ ++ ++@node Group Info ++@subsection Group Info ++ ++Gnus stores all permanent info on groups in a @dfn{group info} list. ++This list is from three to six elements (or more) long and exhaustively ++describes the group. ++ ++Here are two example group infos; one is a very simple group while the ++second is a more complex one: ++ ++@example ++("no.group" 5 ((1 . 54324))) ++ ++("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55)) ++ ((tick (15 . 19)) (replied 3 6 (19 . 3))) ++ (nnml "") ++ ((auto-expire . t) (to-address . "ding@@gnus.org"))) ++@end example ++ ++The first element is the @dfn{group name}---as Gnus knows the group, ++anyway. The second element is the @dfn{subscription level}, which ++normally is a small integer. (It can also be the @dfn{rank}, which is a ++cons cell where the @code{car} is the level and the @code{cdr} is the ++score.) The third element is a list of ranges of read articles. The ++fourth element is a list of lists of article marks of various kinds. ++The fifth element is the select method (or virtual server, if you like). ++The sixth element is a list of @dfn{group parameters}, which is what ++this section is about. ++ ++Any of the last three elements may be missing if they are not required. ++In fact, the vast majority of groups will normally only have the first ++three elements, which saves quite a lot of cons cells. ++ ++Here's a BNF definition of the group info format: ++ ++@example ++info = "(" group space ralevel space read ++ [ "" / [ space marks-list [ "" / [ space method [ "" / ++ space parameters ] ] ] ] ] ")" ++group = quote quote ++ralevel = rank / level ++level = ++rank = "(" level "." score ")" ++score = ++read = range ++marks-lists = nil / "(" *marks ")" ++marks = "(" range ")" ++method = "(" *elisp-forms ")" ++parameters = "(" *elisp-forms ")" ++@end example ++ ++Actually that @samp{marks} rule is a fib. A @samp{marks} is a ++@samp{} consed on to a @samp{range}, but that's a bitch to say ++in pseudo-BNF. ++ ++If you have a Gnus info and want to access the elements, Gnus offers a ++series of macros for getting/setting these elements. ++ ++@table @code ++@item gnus-info-group ++@itemx gnus-info-set-group ++@findex gnus-info-group ++@findex gnus-info-set-group ++Get/set the group name. ++ ++@item gnus-info-rank ++@itemx gnus-info-set-rank ++@findex gnus-info-rank ++@findex gnus-info-set-rank ++Get/set the group rank (@pxref{Group Score}). ++ ++@item gnus-info-level ++@itemx gnus-info-set-level ++@findex gnus-info-level ++@findex gnus-info-set-level ++Get/set the group level. ++ ++@item gnus-info-score ++@itemx gnus-info-set-score ++@findex gnus-info-score ++@findex gnus-info-set-score ++Get/set the group score (@pxref{Group Score}). ++ ++@item gnus-info-read ++@itemx gnus-info-set-read ++@findex gnus-info-read ++@findex gnus-info-set-read ++Get/set the ranges of read articles. ++ ++@item gnus-info-marks ++@itemx gnus-info-set-marks ++@findex gnus-info-marks ++@findex gnus-info-set-marks ++Get/set the lists of ranges of marked articles. ++ ++@item gnus-info-method ++@itemx gnus-info-set-method ++@findex gnus-info-method ++@findex gnus-info-set-method ++Get/set the group select method. ++ ++@item gnus-info-params ++@itemx gnus-info-set-params ++@findex gnus-info-params ++@findex gnus-info-set-params ++Get/set the group parameters. ++@end table ++ ++All the getter functions take one parameter---the info list. The setter ++functions take two parameters---the info list and the new value. ++ ++The last three elements in the group info aren't mandatory, so it may be ++necessary to extend the group info before setting the element. If this ++is necessary, you can just pass on a non-@code{nil} third parameter to ++the three final setter functions to have this happen automatically. ++ ++ ++@node Extended Interactive ++@subsection Extended Interactive ++@cindex interactive ++@findex gnus-interactive ++ ++Gnus extends the standard Emacs @code{interactive} specification ++slightly to allow easy use of the symbolic prefix (@pxref{Symbolic ++Prefixes}). Here's an example of how this is used: ++ ++@lisp ++(defun gnus-summary-increase-score (&optional score symp) ++ (interactive (gnus-interactive "P\ny")) ++ ... ++ ) ++@end lisp ++ ++The best thing to do would have been to implement ++@code{gnus-interactive} as a macro which would have returned an ++@code{interactive} form, but this isn't possible since Emacs checks ++whether a function is interactive or not by simply doing an @code{assq} ++on the lambda form. So, instead we have @code{gnus-interactive} ++function that takes a string and returns values that are usable to ++@code{interactive}. ++ ++This function accepts (almost) all normal @code{interactive} specs, but ++adds a few more. ++ ++@table @samp ++@item y ++@vindex gnus-current-prefix-symbol ++The current symbolic prefix---the @code{gnus-current-prefix-symbol} ++variable. ++ ++@item Y ++@vindex gnus-current-prefix-symbols ++A list of the current symbolic prefixes---the ++@code{gnus-current-prefix-symbol} variable. ++ ++@item A ++The current article number---the @code{gnus-summary-article-number} ++function. ++ ++@item H ++The current article header---the @code{gnus-summary-article-header} ++function. ++ ++@item g ++The current group name---the @code{gnus-group-group-name} ++function. ++ ++@end table ++ ++ ++@node Emacs/XEmacs Code ++@subsection Emacs/XEmacs Code ++@cindex XEmacs ++@cindex Emacsen ++ ++While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the ++platforms must be the primary one. I chose Emacs. Not because I don't ++like XEmacs or Mule, but because it comes first alphabetically. ++ ++This means that Gnus will byte-compile under Emacs with nary a warning, ++while XEmacs will pump out gigabytes of warnings while byte-compiling. ++As I use byte-compilation warnings to help me root out trivial errors in ++Gnus, that's very useful. ++ ++I've also consistently used Emacs function interfaces, but have used ++Gnusey aliases for the functions. To take an example: Emacs defines a ++@code{run-at-time} function while XEmacs defines a @code{start-itimer} ++function. I then define a function called @code{gnus-run-at-time} that ++takes the same parameters as the Emacs @code{run-at-time}. When running ++Gnus under Emacs, the former function is just an alias for the latter. ++However, when running under XEmacs, the former is an alias for the ++following function: ++ ++@lisp ++(defun gnus-xmas-run-at-time (time repeat function &rest args) ++ (start-itimer ++ "gnus-run-at-time" ++ `(lambda () ++ (,function ,@@args)) ++ time repeat)) ++@end lisp ++ ++This sort of thing has been done for bunches of functions. Gnus does ++not redefine any native Emacs functions while running under XEmacs---it ++does this @code{defalias} thing with Gnus equivalents instead. Cleaner ++all over. ++ ++In the cases where the XEmacs function interface was obviously cleaner, ++I used it instead. For example @code{gnus-region-active-p} is an alias ++for @code{region-active-p} in XEmacs, whereas in Emacs it is a function. ++ ++Of course, I could have chosen XEmacs as my native platform and done ++mapping functions the other way around. But I didn't. The performance ++hit these indirections impose on Gnus under XEmacs should be slight. ++ ++ ++@node Various File Formats ++@subsection Various File Formats ++ ++@menu ++* Active File Format:: Information on articles and groups available. ++* Newsgroups File Format:: Group descriptions. ++@end menu ++ ++ ++@node Active File Format ++@subsubsection Active File Format ++ ++The active file lists all groups available on the server in ++question. It also lists the highest and lowest current article numbers ++in each group. ++ ++Here's an excerpt from a typical active file: ++ ++@example ++soc.motss 296030 293865 y ++alt.binaries.pictures.fractals 3922 3913 n ++comp.sources.unix 1605 1593 m ++comp.binaries.ibm.pc 5097 5089 y ++no.general 1000 900 y ++@end example ++ ++Here's a pseudo-BNF definition of this file: ++ ++@example ++active = *group-line ++group-line = group spc high-number spc low-number spc flag ++group = ++spc = " " ++high-number = ++low-number = ++flag = "y" / "n" / "m" / "j" / "x" / "=" group ++@end example ++ ++For a full description of this file, see the manual pages for ++@samp{innd}, in particular @samp{active(5)}. ++ ++ ++@node Newsgroups File Format ++@subsubsection Newsgroups File Format ++ ++The newsgroups file lists groups along with their descriptions. Not all ++groups on the server have to be listed, and not all groups in the file ++have to exist on the server. The file is meant purely as information to ++the user. ++ ++The format is quite simple; a group name, a tab, and the description. ++Here's the definition: ++ ++@example ++newsgroups = *line ++line = group tab description ++group = ++tab = ++description = ++@end example ++ ++ ++@page ++@node Emacs for Heathens ++@section Emacs for Heathens ++ ++Believe it or not, but some people who use Gnus haven't really used ++Emacs much before they embarked on their journey on the Gnus Love Boat. ++If you are one of those unfortunates whom ``@kbd{C-M-a}'', ``kill the ++region'', and ``set @code{gnus-flargblossen} to an alist where the key ++is a regexp that is used for matching on the group name'' are magical ++phrases with little or no meaning, then this appendix is for you. If ++you are already familiar with Emacs, just ignore this and go fondle your ++cat instead. ++ ++@menu ++* Keystrokes:: Entering text and executing commands. ++* Emacs Lisp:: The built-in Emacs programming language. ++@end menu ++ ++ ++@node Keystrokes ++@subsection Keystrokes ++ ++@itemize @bullet ++@item ++Q: What is an experienced Emacs user? ++ ++@item ++A: A person who wishes that the terminal had pedals. ++@end itemize ++ ++Yes, when you use Emacs, you are apt to use the control key, the shift ++key and the meta key a lot. This is very annoying to some people ++(notably @code{vi}le users), and the rest of us just love the hell out ++of it. Just give up and submit. Emacs really does stand for ++``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you ++may have heard from other disreputable sources (like the Emacs author). ++ ++The shift keys are normally located near your pinky fingers, and are ++normally used to get capital letters and stuff. You probably use it all ++the time. The control key is normally marked ``CTRL'' or something like ++that. The meta key is, funnily enough, never marked as such on any ++keyboard. The one I'm currently at has a key that's marked ``Alt'', ++which is the meta key on this keyboard. It's usually located somewhere ++to the left hand side of the keyboard, usually on the bottom row. ++ ++Now, us Emacs people don't say ``press the meta-control-m key'', ++because that's just too inconvenient. We say ``press the @kbd{C-M-m} ++key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the ++prefix that means ``control''. So ``press @kbd{C-k}'' means ``press ++down the control key, and hold it down while you press @kbd{k}''. ++``Press @kbd{C-M-k}'' means ``press down and hold down the meta key and ++the control key and then press @kbd{k}''. Simple, ay? ++ ++This is somewhat complicated by the fact that not all keyboards have a ++meta key. In that case you can use the ``escape'' key. Then @kbd{M-k} ++means ``press escape, release escape, press @kbd{k}''. That's much more ++work than if you have a meta key, so if that's the case, I respectfully ++suggest you get a real keyboard with a meta key. You can't live without ++it. ++ ++ ++ ++@node Emacs Lisp ++@subsection Emacs Lisp ++ ++Emacs is the King of Editors because it's really a Lisp interpreter. ++Each and every key you tap runs some Emacs Lisp code snippet, and since ++Emacs Lisp is an interpreted language, that means that you can configure ++any key to run any arbitrary code. You just, like, do it. ++ ++Gnus is written in Emacs Lisp, and is run as a bunch of interpreted ++functions. (These are byte-compiled for speed, but it's still ++interpreted.) If you decide that you don't like the way Gnus does ++certain things, it's trivial to have it do something a different way. ++(Well, at least if you know how to write Lisp code.) However, that's ++beyond the scope of this manual, so we are simply going to talk about ++some common constructs that you normally use in your @file{~/.gnus.el} ++file to customize Gnus. (You can also use the @file{~/.emacs} file, but ++in order to set things of Gnus up, it is much better to use the ++@file{~/.gnus.el} file, @xref{Startup Files}.) ++ ++If you want to set the variable @code{gnus-florgbnize} to four (4), you ++write the following: ++ ++@lisp ++(setq gnus-florgbnize 4) ++@end lisp ++ ++This function (really ``special form'') @code{setq} is the one that can ++set a variable to some value. This is really all you need to know. Now ++you can go and fill your @file{~/.gnus.el} file with lots of these to ++change how Gnus works. ++ ++If you have put that thing in your @file{~/.gnus.el} file, it will be ++read and @code{eval}ed (which is Lisp-ese for ``run'') the next time you ++start Gnus. If you want to change the variable right away, simply say ++@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the ++previous ``form'', which is a simple @code{setq} statement here. ++ ++Go ahead---just try it, if you're located at your Emacs. After you ++@kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which ++is the return value of the form you @code{eval}ed. ++ ++Some pitfalls: ++ ++If the manual says ``set @code{gnus-read-active-file} to @code{some}'', ++that means: ++ ++@lisp ++(setq gnus-read-active-file 'some) ++@end lisp ++ ++On the other hand, if the manual says ``set @code{gnus-nntp-server} to ++@samp{nntp.ifi.uio.no}'', that means: ++ ++@lisp ++(setq gnus-nntp-server "nntp.ifi.uio.no") ++@end lisp ++ ++So be careful not to mix up strings (the latter) with symbols (the ++former). The manual is unambiguous, but it can be confusing. ++ ++@page ++@include gnus-faq.texi ++ ++@node GNU Free Documentation License ++@chapter GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index ++@chapter Index ++@printindex cp ++ ++@node Key Index ++@chapter Key Index ++@printindex ky ++ ++@bye ++ ++@iftex ++@iflatex ++\end{document} ++@end iflatex ++@end iftex ++ ++@c Local Variables: ++@c mode: texinfo ++@c coding: iso-8859-1 ++@c End: ++ ++@ignore ++ arch-tag: c9fa47e7-78ca-4681-bda9-9fef45d1c819 ++@end ignore +diff --git a/doc/misc/gpl.texi b/doc/misc/gpl.texi +new file mode 100644 +index 0000000..5b416d3 +--- /dev/null ++++ b/doc/misc/gpl.texi +@@ -0,0 +1,721 @@ ++@c The GNU General Public License. ++@center Version 3, 29 June 2007 ++ ++@c This file is intended to be included within another document, ++@c hence no sectioning command or @node. ++ ++@display ++Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} ++ ++Everyone is permitted to copy and distribute verbatim copies of this ++license document, but changing it is not allowed. ++@end display ++ ++@heading Preamble ++ ++The GNU General Public License is a free, copyleft license for ++software and other kinds of works. ++ ++The licenses for most software and other practical works are designed ++to take away your freedom to share and change the works. By contrast, ++the GNU General Public License is intended to guarantee your freedom ++to share and change all versions of a program---to make sure it remains ++free software for all its users. We, the Free Software Foundation, ++use the GNU General Public License for most of our software; it ++applies also to any other work released this way by its authors. You ++can apply it to your programs, too. ++ ++When we speak of free software, we are referring to freedom, not ++price. Our General Public Licenses are designed to make sure that you ++have the freedom to distribute copies of free software (and charge for ++them 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. ++ ++To protect your rights, we need to prevent others from denying you ++these rights or asking you to surrender the rights. Therefore, you ++have certain responsibilities if you distribute copies of the ++software, or if you modify it: responsibilities to respect the freedom ++of others. ++ ++For example, if you distribute copies of such a program, whether ++gratis or for a fee, you must pass on to the recipients the same ++freedoms that you received. You must make sure that they, too, ++receive or can get the source code. And you must show them these ++terms so they know their rights. ++ ++Developers that use the GNU GPL protect your rights with two steps: ++(1) assert copyright on the software, and (2) offer you this License ++giving you legal permission to copy, distribute and/or modify it. ++ ++For the developers' and authors' protection, the GPL clearly explains ++that there is no warranty for this free software. For both users' and ++authors' sake, the GPL requires that modified versions be marked as ++changed, so that their problems will not be attributed erroneously to ++authors of previous versions. ++ ++Some devices are designed to deny users access to install or run ++modified versions of the software inside them, although the ++manufacturer can do so. This is fundamentally incompatible with the ++aim of protecting users' freedom to change the software. The ++systematic pattern of such abuse occurs in the area of products for ++individuals to use, which is precisely where it is most unacceptable. ++Therefore, we have designed this version of the GPL to prohibit the ++practice for those products. If such problems arise substantially in ++other domains, we stand ready to extend this provision to those ++domains in future versions of the GPL, as needed to protect the ++freedom of users. ++ ++Finally, every program is threatened constantly by software patents. ++States should not allow patents to restrict development and use of ++software on general-purpose computers, but in those that do, we wish ++to avoid the special danger that patents applied to a free program ++could make it effectively proprietary. To prevent this, the GPL ++assures that patents cannot be used to render the program non-free. ++ ++The precise terms and conditions for copying, distribution and ++modification follow. ++ ++@heading TERMS AND CONDITIONS ++ ++@enumerate 0 ++@item Definitions. ++ ++``This License'' refers to version 3 of the GNU General Public License. ++ ++``Copyright'' also means copyright-like laws that apply to other kinds ++of works, such as semiconductor masks. ++ ++``The Program'' refers to any copyrightable work licensed under this ++License. Each licensee is addressed as ``you''. ``Licensees'' and ++``recipients'' may be individuals or organizations. ++ ++To ``modify'' a work means to copy from or adapt all or part of the work ++in a fashion requiring copyright permission, other than the making of ++an exact copy. The resulting work is called a ``modified version'' of ++the earlier work or a work ``based on'' the earlier work. ++ ++A ``covered work'' means either the unmodified Program or a work based ++on the Program. ++ ++To ``propagate'' a work means to do anything with it that, without ++permission, would make you directly or secondarily liable for ++infringement under applicable copyright law, except executing it on a ++computer or modifying a private copy. Propagation includes copying, ++distribution (with or without modification), making available to the ++public, and in some countries other activities as well. ++ ++To ``convey'' a work means any kind of propagation that enables other ++parties to make or receive copies. Mere interaction with a user ++through a computer network, with no transfer of a copy, is not ++conveying. ++ ++An interactive user interface displays ``Appropriate Legal Notices'' to ++the extent that it includes a convenient and prominently visible ++feature that (1) displays an appropriate copyright notice, and (2) ++tells the user that there is no warranty for the work (except to the ++extent that warranties are provided), that licensees may convey the ++work under this License, and how to view a copy of this License. If ++the interface presents a list of user commands or options, such as a ++menu, a prominent item in the list meets this criterion. ++ ++@item Source Code. ++ ++The ``source code'' for a work means the preferred form of the work for ++making modifications to it. ``Object code'' means any non-source form ++of a work. ++ ++A ``Standard Interface'' means an interface that either is an official ++standard defined by a recognized standards body, or, in the case of ++interfaces specified for a particular programming language, one that ++is widely used among developers working in that language. ++ ++The ``System Libraries'' of an executable work include anything, other ++than the work as a whole, that (a) is included in the normal form of ++packaging a Major Component, but which is not part of that Major ++Component, and (b) serves only to enable use of the work with that ++Major Component, or to implement a Standard Interface for which an ++implementation is available to the public in source code form. A ++``Major Component'', in this context, means a major essential component ++(kernel, window system, and so on) of the specific operating system ++(if any) on which the executable work runs, or a compiler used to ++produce the work, or an object code interpreter used to run it. ++ ++The ``Corresponding Source'' for a work in object code form means all ++the source code needed to generate, install, and (for an executable ++work) run the object code and to modify the work, including scripts to ++control those activities. However, it does not include the work's ++System Libraries, or general-purpose tools or generally available free ++programs which are used unmodified in performing those activities but ++which are not part of the work. For example, Corresponding Source ++includes interface definition files associated with source files for ++the work, and the source code for shared libraries and dynamically ++linked subprograms that the work is specifically designed to require, ++such as by intimate data communication or control flow between those ++subprograms and other parts of the work. ++ ++The Corresponding Source need not include anything that users can ++regenerate automatically from other parts of the Corresponding Source. ++ ++The Corresponding Source for a work in source code form is that same ++work. ++ ++@item Basic Permissions. ++ ++All rights granted under this License are granted for the term of ++copyright on the Program, and are irrevocable provided the stated ++conditions are met. This License explicitly affirms your unlimited ++permission to run the unmodified Program. The output from running a ++covered work is covered by this License only if the output, given its ++content, constitutes a covered work. This License acknowledges your ++rights of fair use or other equivalent, as provided by copyright law. ++ ++You may make, run and propagate covered works that you do not convey, ++without conditions so long as your license otherwise remains in force. ++You may convey covered works to others for the sole purpose of having ++them make modifications exclusively for you, or provide you with ++facilities for running those works, provided that you comply with the ++terms of this License in conveying all material for which you do not ++control copyright. Those thus making or running the covered works for ++you must do so exclusively on your behalf, under your direction and ++control, on terms that prohibit them from making any copies of your ++copyrighted material outside their relationship with you. ++ ++Conveying under any other circumstances is permitted solely under the ++conditions stated below. Sublicensing is not allowed; section 10 ++makes it unnecessary. ++ ++@item Protecting Users' Legal Rights From Anti-Circumvention Law. ++ ++No covered work shall be deemed part of an effective technological ++measure under any applicable law fulfilling obligations under article ++11 of the WIPO copyright treaty adopted on 20 December 1996, or ++similar laws prohibiting or restricting circumvention of such ++measures. ++ ++When you convey a covered work, you waive any legal power to forbid ++circumvention of technological measures to the extent such ++circumvention is effected by exercising rights under this License with ++respect to the covered work, and you disclaim any intention to limit ++operation or modification of the work as a means of enforcing, against ++the work's users, your or third parties' legal rights to forbid ++circumvention of technological measures. ++ ++@item Conveying Verbatim Copies. ++ ++You may convey verbatim copies of the Program's source code as you ++receive it, in any medium, provided that you conspicuously and ++appropriately publish on each copy an appropriate copyright notice; ++keep intact all notices stating that this License and any ++non-permissive terms added in accord with section 7 apply to the code; ++keep intact all notices of the absence of any warranty; and give all ++recipients a copy of this License along with the Program. ++ ++You may charge any price or no price for each copy that you convey, ++and you may offer support or warranty protection for a fee. ++ ++@item Conveying Modified Source Versions. ++ ++You may convey a work based on the Program, or the modifications to ++produce it from the Program, in the form of source code under the ++terms of section 4, provided that you also meet all of these ++conditions: ++ ++@enumerate a ++@item ++The work must carry prominent notices stating that you modified it, ++and giving a relevant date. ++ ++@item ++The work must carry prominent notices stating that it is released ++under this License and any conditions added under section 7. This ++requirement modifies the requirement in section 4 to ``keep intact all ++notices''. ++ ++@item ++You must license the entire work, as a whole, under this License to ++anyone who comes into possession of a copy. This License will ++therefore apply, along with any applicable section 7 additional terms, ++to the whole of the work, and all its parts, regardless of how they ++are packaged. This License gives no permission to license the work in ++any other way, but it does not invalidate such permission if you have ++separately received it. ++ ++@item ++If the work has interactive user interfaces, each must display ++Appropriate Legal Notices; however, if the Program has interactive ++interfaces that do not display Appropriate Legal Notices, your work ++need not make them do so. ++@end enumerate ++ ++A compilation of a covered work with other separate and independent ++works, which are not by their nature extensions of the covered work, ++and which are not combined with it such as to form a larger program, ++in or on a volume of a storage or distribution medium, is called an ++``aggregate'' if the compilation and its resulting copyright are not ++used to limit the access or legal rights of the compilation's users ++beyond what the individual works permit. Inclusion of a covered work ++in an aggregate does not cause this License to apply to the other ++parts of the aggregate. ++ ++@item Conveying Non-Source Forms. ++ ++You may convey a covered work in object code form under the terms of ++sections 4 and 5, provided that you also convey the machine-readable ++Corresponding Source under the terms of this License, in one of these ++ways: ++ ++@enumerate a ++@item ++Convey the object code in, or embodied in, a physical product ++(including a physical distribution medium), accompanied by the ++Corresponding Source fixed on a durable physical medium customarily ++used for software interchange. ++ ++@item ++Convey the object code in, or embodied in, a physical product ++(including a physical distribution medium), accompanied by a written ++offer, valid for at least three years and valid for as long as you ++offer spare parts or customer support for that product model, to give ++anyone who possesses the object code either (1) a copy of the ++Corresponding Source for all the software in the product that is ++covered by this License, on a durable physical medium customarily used ++for software interchange, for a price no more than your reasonable ++cost of physically performing this conveying of source, or (2) access ++to copy the Corresponding Source from a network server at no charge. ++ ++@item ++Convey individual copies of the object code with a copy of the written ++offer to provide the Corresponding Source. This alternative is ++allowed only occasionally and noncommercially, and only if you ++received the object code with such an offer, in accord with subsection ++6b. ++ ++@item ++Convey the object code by offering access from a designated place ++(gratis or for a charge), and offer equivalent access to the ++Corresponding Source in the same way through the same place at no ++further charge. You need not require recipients to copy the ++Corresponding Source along with the object code. If the place to copy ++the object code is a network server, the Corresponding Source may be ++on a different server (operated by you or a third party) that supports ++equivalent copying facilities, provided you maintain clear directions ++next to the object code saying where to find the Corresponding Source. ++Regardless of what server hosts the Corresponding Source, you remain ++obligated to ensure that it is available for as long as needed to ++satisfy these requirements. ++ ++@item ++Convey the object code using peer-to-peer transmission, provided you ++inform other peers where the object code and Corresponding Source of ++the work are being offered to the general public at no charge under ++subsection 6d. ++ ++@end enumerate ++ ++A separable portion of the object code, whose source code is excluded ++from the Corresponding Source as a System Library, need not be ++included in conveying the object code work. ++ ++A ``User Product'' is either (1) a ``consumer product'', which means any ++tangible personal property which is normally used for personal, ++family, or household purposes, or (2) anything designed or sold for ++incorporation into a dwelling. In determining whether a product is a ++consumer product, doubtful cases shall be resolved in favor of ++coverage. For a particular product received by a particular user, ++``normally used'' refers to a typical or common use of that class of ++product, regardless of the status of the particular user or of the way ++in which the particular user actually uses, or expects or is expected ++to use, the product. A product is a consumer product regardless of ++whether the product has substantial commercial, industrial or ++non-consumer uses, unless such uses represent the only significant ++mode of use of the product. ++ ++``Installation Information'' for a User Product means any methods, ++procedures, authorization keys, or other information required to ++install and execute modified versions of a covered work in that User ++Product from a modified version of its Corresponding Source. The ++information must suffice to ensure that the continued functioning of ++the modified object code is in no case prevented or interfered with ++solely because modification has been made. ++ ++If you convey an object code work under this section in, or with, or ++specifically for use in, a User Product, and the conveying occurs as ++part of a transaction in which the right of possession and use of the ++User Product is transferred to the recipient in perpetuity or for a ++fixed term (regardless of how the transaction is characterized), the ++Corresponding Source conveyed under this section must be accompanied ++by the Installation Information. But this requirement does not apply ++if neither you nor any third party retains the ability to install ++modified object code on the User Product (for example, the work has ++been installed in ROM). ++ ++The requirement to provide Installation Information does not include a ++requirement to continue to provide support service, warranty, or ++updates for a work that has been modified or installed by the ++recipient, or for the User Product in which it has been modified or ++installed. Access to a network may be denied when the modification ++itself materially and adversely affects the operation of the network ++or violates the rules and protocols for communication across the ++network. ++ ++Corresponding Source conveyed, and Installation Information provided, ++in accord with this section must be in a format that is publicly ++documented (and with an implementation available to the public in ++source code form), and must require no special password or key for ++unpacking, reading or copying. ++ ++@item Additional Terms. ++ ++``Additional permissions'' are terms that supplement the terms of this ++License by making exceptions from one or more of its conditions. ++Additional permissions that are applicable to the entire Program shall ++be treated as though they were included in this License, to the extent ++that they are valid under applicable law. If additional permissions ++apply only to part of the Program, that part may be used separately ++under those permissions, but the entire Program remains governed by ++this License without regard to the additional permissions. ++ ++When you convey a copy of a covered work, you may at your option ++remove any additional permissions from that copy, or from any part of ++it. (Additional permissions may be written to require their own ++removal in certain cases when you modify the work.) You may place ++additional permissions on material, added by you to a covered work, ++for which you have or can give appropriate copyright permission. ++ ++Notwithstanding any other provision of this License, for material you ++add to a covered work, you may (if authorized by the copyright holders ++of that material) supplement the terms of this License with terms: ++ ++@enumerate a ++@item ++Disclaiming warranty or limiting liability differently from the terms ++of sections 15 and 16 of this License; or ++ ++@item ++Requiring preservation of specified reasonable legal notices or author ++attributions in that material or in the Appropriate Legal Notices ++displayed by works containing it; or ++ ++@item ++Prohibiting misrepresentation of the origin of that material, or ++requiring that modified versions of such material be marked in ++reasonable ways as different from the original version; or ++ ++@item ++Limiting the use for publicity purposes of names of licensors or ++authors of the material; or ++ ++@item ++Declining to grant rights under trademark law for use of some trade ++names, trademarks, or service marks; or ++ ++@item ++Requiring indemnification of licensors and authors of that material by ++anyone who conveys the material (or modified versions of it) with ++contractual assumptions of liability to the recipient, for any ++liability that these contractual assumptions directly impose on those ++licensors and authors. ++@end enumerate ++ ++All other non-permissive additional terms are considered ``further ++restrictions'' within the meaning of section 10. If the Program as you ++received it, or any part of it, contains a notice stating that it is ++governed by this License along with a term that is a further ++restriction, you may remove that term. If a license document contains ++a further restriction but permits relicensing or conveying under this ++License, you may add to a covered work material governed by the terms ++of that license document, provided that the further restriction does ++not survive such relicensing or conveying. ++ ++If you add terms to a covered work in accord with this section, you ++must place, in the relevant source files, a statement of the ++additional terms that apply to those files, or a notice indicating ++where to find the applicable terms. ++ ++Additional terms, permissive or non-permissive, may be stated in the ++form of a separately written license, or stated as exceptions; the ++above requirements apply either way. ++ ++@item Termination. ++ ++You may not propagate or modify a covered work except as expressly ++provided under this License. Any attempt otherwise to propagate or ++modify it is void, and will automatically terminate your rights under ++this License (including any patent licenses granted under the third ++paragraph of section 11). ++ ++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, you do not qualify to receive new licenses for the same ++material under section 10. ++ ++@item Acceptance Not Required for Having Copies. ++ ++You are not required to accept this License in order to receive or run ++a copy of the Program. Ancillary propagation of a covered work ++occurring solely as a consequence of using peer-to-peer transmission ++to receive a copy likewise does not require acceptance. However, ++nothing other than this License grants you permission to propagate or ++modify any covered work. These actions infringe copyright if you do ++not accept this License. Therefore, by modifying or propagating a ++covered work, you indicate your acceptance of this License to do so. ++ ++@item Automatic Licensing of Downstream Recipients. ++ ++Each time you convey a covered work, the recipient automatically ++receives a license from the original licensors, to run, modify and ++propagate that work, subject to this License. You are not responsible ++for enforcing compliance by third parties with this License. ++ ++An ``entity transaction'' is a transaction transferring control of an ++organization, or substantially all assets of one, or subdividing an ++organization, or merging organizations. If propagation of a covered ++work results from an entity transaction, each party to that ++transaction who receives a copy of the work also receives whatever ++licenses to the work the party's predecessor in interest had or could ++give under the previous paragraph, plus a right to possession of the ++Corresponding Source of the work from the predecessor in interest, if ++the predecessor has it or can get it with reasonable efforts. ++ ++You may not impose any further restrictions on the exercise of the ++rights granted or affirmed under this License. For example, you may ++not impose a license fee, royalty, or other charge for exercise of ++rights granted under this License, and you may not initiate litigation ++(including a cross-claim or counterclaim in a lawsuit) alleging that ++any patent claim is infringed by making, using, selling, offering for ++sale, or importing the Program or any portion of it. ++ ++@item Patents. ++ ++A ``contributor'' is a copyright holder who authorizes use under this ++License of the Program or a work on which the Program is based. The ++work thus licensed is called the contributor's ``contributor version''. ++ ++A contributor's ``essential patent claims'' are all patent claims owned ++or controlled by the contributor, whether already acquired or ++hereafter acquired, that would be infringed by some manner, permitted ++by this License, of making, using, or selling its contributor version, ++but do not include claims that would be infringed only as a ++consequence of further modification of the contributor version. For ++purposes of this definition, ``control'' includes the right to grant ++patent sublicenses in a manner consistent with the requirements of ++this License. ++ ++Each contributor grants you a non-exclusive, worldwide, royalty-free ++patent license under the contributor's essential patent claims, to ++make, use, sell, offer for sale, import and otherwise run, modify and ++propagate the contents of its contributor version. ++ ++In the following three paragraphs, a ``patent license'' is any express ++agreement or commitment, however denominated, not to enforce a patent ++(such as an express permission to practice a patent or covenant not to ++sue for patent infringement). To ``grant'' such a patent license to a ++party means to make such an agreement or commitment not to enforce a ++patent against the party. ++ ++If you convey a covered work, knowingly relying on a patent license, ++and the Corresponding Source of the work is not available for anyone ++to copy, free of charge and under the terms of this License, through a ++publicly available network server or other readily accessible means, ++then you must either (1) cause the Corresponding Source to be so ++available, or (2) arrange to deprive yourself of the benefit of the ++patent license for this particular work, or (3) arrange, in a manner ++consistent with the requirements of this License, to extend the patent ++license to downstream recipients. ``Knowingly relying'' means you have ++actual knowledge that, but for the patent license, your conveying the ++covered work in a country, or your recipient's use of the covered work ++in a country, would infringe one or more identifiable patents in that ++country that you have reason to believe are valid. ++ ++If, pursuant to or in connection with a single transaction or ++arrangement, you convey, or propagate by procuring conveyance of, a ++covered work, and grant a patent license to some of the parties ++receiving the covered work authorizing them to use, propagate, modify ++or convey a specific copy of the covered work, then the patent license ++you grant is automatically extended to all recipients of the covered ++work and works based on it. ++ ++A patent license is ``discriminatory'' if it does not include within the ++scope of its coverage, prohibits the exercise of, or is conditioned on ++the non-exercise of one or more of the rights that are specifically ++granted under this License. You may not convey a covered work if you ++are a party to an arrangement with a third party that is in the ++business of distributing software, under which you make payment to the ++third party based on the extent of your activity of conveying the ++work, and under which the third party grants, to any of the parties ++who would receive the covered work from you, a discriminatory patent ++license (a) in connection with copies of the covered work conveyed by ++you (or copies made from those copies), or (b) primarily for and in ++connection with specific products or compilations that contain the ++covered work, unless you entered into that arrangement, or that patent ++license was granted, prior to 28 March 2007. ++ ++Nothing in this License shall be construed as excluding or limiting ++any implied license or other defenses to infringement that may ++otherwise be available to you under applicable patent law. ++ ++@item No Surrender of Others' Freedom. ++ ++If conditions are imposed on you (whether by court order, agreement or ++otherwise) that contradict the conditions of this License, they do not ++excuse you from the conditions of this License. If you cannot convey ++a covered work so as to satisfy simultaneously your obligations under ++this License and any other pertinent obligations, then as a ++consequence you may not convey it at all. For example, if you agree ++to terms that obligate you to collect a royalty for further conveying ++from those to whom you convey the Program, the only way you could ++satisfy both those terms and this License would be to refrain entirely ++from conveying the Program. ++ ++@item Use with the GNU Affero General Public License. ++ ++Notwithstanding any other provision of this License, you have ++permission to link or combine any covered work with a work licensed ++under version 3 of the GNU Affero General Public License into a single ++combined work, and to convey the resulting work. The terms of this ++License will continue to apply to the part which is the covered work, ++but the special requirements of the GNU Affero General Public License, ++section 13, concerning interaction through a network will apply to the ++combination as such. ++ ++@item Revised Versions of this License. ++ ++The Free Software Foundation may publish revised and/or new versions ++of the GNU General Public 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. ++ ++Each version is given a distinguishing version number. If the Program ++specifies that a certain numbered version of the GNU General Public ++License ``or any later version'' applies to it, you have the option of ++following the terms and conditions either of that numbered version or ++of any later version published by the Free Software Foundation. If ++the Program does not specify a version number of the GNU General ++Public License, you may choose any version ever published by the Free ++Software Foundation. ++ ++If the Program specifies that a proxy can decide which future versions ++of the GNU General Public License can be used, that proxy's public ++statement of acceptance of a version permanently authorizes you to ++choose that version for the Program. ++ ++Later license versions may give you additional or different ++permissions. However, no additional obligations are imposed on any ++author or copyright holder as a result of your choosing to follow a ++later version. ++ ++@item Disclaimer of Warranty. ++ ++THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY ++APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT ++HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT ++WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT ++LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ++A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND ++PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE ++DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR ++CORRECTION. ++ ++@item Limitation of Liability. ++ ++IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING ++WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR ++CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, ++INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ++ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT ++NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR ++LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM ++TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER ++PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. ++ ++@item Interpretation of Sections 15 and 16. ++ ++If the disclaimer of warranty and limitation of liability provided ++above cannot be given local legal effect according to their terms, ++reviewing courts shall apply local law that most closely approximates ++an absolute waiver of all civil liability in connection with the ++Program, unless a warranty or assumption of liability accompanies a ++copy of the Program in return for a fee. ++ ++@end enumerate ++ ++@heading END OF TERMS AND CONDITIONS ++ ++@heading How to Apply These Terms to Your New Programs ++ ++If you develop a new program, and you want it to be of the greatest ++possible use to the public, the best way to achieve this is to make it ++free software which everyone can redistribute and change under these ++terms. ++ ++To do so, attach the following notices to the program. It is safest ++to attach them to the start of each source file to most effectively ++state the exclusion of warranty; and each file should have at least ++the ``copyright'' line and a pointer to where the full notice is found. ++ ++@smallexample ++@var{one line to give the program's name and a brief idea of what it does.} ++Copyright (C) @var{year} @var{name of author} ++ ++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 @url{http://www.gnu.org/licenses/}. ++@end smallexample ++ ++Also add information on how to contact you by electronic and paper mail. ++ ++If the program does terminal interaction, make it output a short ++notice like this when it starts in an interactive mode: ++ ++@smallexample ++@var{program} Copyright (C) @var{year} @var{name of author} ++This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. ++This is free software, and you are welcome to redistribute it ++under certain conditions; type @samp{show c} for details. ++@end smallexample ++ ++The hypothetical commands @samp{show w} and @samp{show c} should show ++the appropriate parts of the General Public License. Of course, your ++program's commands might be different; for a GUI interface, you would ++use an ``about box''. ++ ++You should also get your employer (if you work as a programmer) or school, ++if any, to sign a ``copyright disclaimer'' for the program, if necessary. ++For more information on this, and how to apply and follow the GNU GPL, see ++@url{http://www.gnu.org/licenses/}. ++ ++The GNU General Public License does not permit incorporating your ++program into proprietary programs. If your program is a subroutine ++library, you may consider it more useful to permit linking proprietary ++applications with the library. If this is what you want to do, use ++the GNU Lesser General Public License instead of this License. But ++first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. ++ ++@ignore ++ arch-tag: 0c4a2556-f87e-464f-9b1d-efd920fcaf67 ++@end ignore +diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi +new file mode 100644 +index 0000000..0d24177 +--- /dev/null ++++ b/doc/misc/idlwave.texi +@@ -0,0 +1,4301 @@ ++\input texinfo @c -*-texinfo-*- ++@c %**start of header ++@setfilename ../../info/idlwave ++@settitle IDLWAVE User Manual ++@synindex ky cp ++@syncodeindex vr cp ++@syncodeindex fn cp ++@set VERSION 6.1 ++@set EDITION 6.1 ++@set IDLVERSION 6.3 ++@set NSYSROUTINES 4346 ++@set DATE April, 2007 ++@set AUTHOR J.D. Smith & Carsten Dominik ++@set MAINTAINER J.D. Smith ++@c %**end of header ++@finalout ++ ++@copying ++This file documents IDLWAVE, a major mode for editing IDL files with ++Emacs, and interacting with an IDL shell run as a subprocess. ++ ++This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE ++@value{VERSION}. ++ ++Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, ++2007, 2008, 2009 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 Emacs ++@direntry ++* IDLWAVE: (idlwave). Major mode and shell for IDL files. ++@end direntry ++ ++@titlepage ++@title IDLWAVE User Manual ++@subtitle Emacs major mode and shell for IDL ++@subtitle Edition @value{EDITION}, @value{DATE} ++@author by J.D. Smith & Carsten Dominik ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top, Introduction, (dir), (dir) ++ ++IDLWAVE is a package which supports editing source code written in the ++Interactive Data Language (IDL), and running IDL as an inferior shell. ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* Introduction:: What IDLWAVE is, and what it is not ++* IDLWAVE in a Nutshell:: One page quick-start guide ++* Getting Started:: Tutorial ++* The IDLWAVE Major Mode:: The mode for editing IDL programs ++* The IDLWAVE Shell:: The mode for running IDL as an inferior program ++* Acknowledgements:: Who did what ++* Sources of Routine Info:: How does IDLWAVE know about routine XYZ ++* HTML Help Browser Tips:: ++* Configuration Examples:: The user is king ++* Windows and MacOS:: What still works, and how ++* Troubleshooting:: When good computers turn bad ++* GNU Free Documentation License:: The license for this documentation. ++* Index:: Fast access ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ ++Getting Started (Tutorial) ++ ++* Lesson I -- Development Cycle:: ++* Lesson II -- Customization:: ++* Lesson III -- User Catalog:: ++ ++The IDLWAVE Major Mode ++ ++* Code Formatting:: Making code look nice ++* Routine Info:: Calling Sequence and Keyword List ++* Online Help:: One key press from source to help ++* Completion:: Completing routine names and Keywords ++* Routine Source:: Finding routines, the easy way ++* Resolving Routines:: Force the Shell to compile a routine ++* Code Templates:: Frequent code constructs ++* Abbreviations:: Abbreviations for common commands ++* Actions:: Changing case, Padding, End checking ++* Doc Header:: Inserting a standard header ++* Motion Commands:: Moving through the structure of a program ++* Misc Options:: Things that fit nowhere else ++ ++Code Formatting ++ ++* Code Indentation:: Reflecting the logical structure ++* Continued Statement Indentation:: ++* Comment Indentation:: Special indentation for comment lines ++* Continuation Lines:: Splitting statements over lines ++* Syntax Highlighting:: Font-lock support ++* Octals and Highlighting:: Why "123 causes problems ++ ++Online Help ++ ++* Help with HTML Documentation:: ++* Help with Source:: ++ ++Completion ++ ++* Case of Completed Words:: CaseOFcomPletedWords ++* Object Method Completion and Class Ambiguity:: obj->Method, what? ++* Object Method Completion in the Shell:: ++* Class and Keyword Inheritance:: obj->Method, _EXTRA=e ++* Structure Tag Completion:: Completing state.Tag ++ ++Actions ++ ++* Block Boundary Check:: Is the END statement correct? ++* Padding Operators:: Enforcing space around `=' etc ++* Case Changes:: Enforcing upper case keywords ++ ++The IDLWAVE Shell ++ ++* Starting the Shell:: How to launch IDL as a subprocess ++* Using the Shell:: Interactively working with the Shell ++* Commands Sent to the Shell:: ++* Debugging IDL Programs:: ++* Examining Variables:: ++* Custom Expression Examination:: ++ ++Debugging IDL Programs ++ ++* A Tale of Two Modes:: ++* Debug Key Bindings:: ++* Breakpoints and Stepping:: ++* Compiling Programs:: ++* Walking the Calling Stack:: ++* Electric Debug Mode:: ++ ++Sources of Routine Info ++ ++* Routine Definitions:: Where IDL Routines are defined. ++* Routine Information Sources:: So how does IDLWAVE know about... ++* Catalogs:: ++* Load-Path Shadows:: Routines defined in several places ++* Documentation Scan:: Scanning the IDL Manuals ++ ++Catalogs ++ ++* Library Catalogs:: ++* User Catalog:: ++ ++@end detailmenu ++@end menu ++ ++@node Introduction, IDLWAVE in a Nutshell, Top, Top ++@chapter Introduction ++@cindex Introduction ++@cindex CORBA (Common Object Request Broker Architecture) ++@cindex Interface Definition Language ++@cindex Interactive Data Language ++@cindex cc-mode.el ++@cindex @file{idl.el} ++@cindex @file{idl-shell.el} ++@cindex Feature overview ++ ++IDLWAVE is a package which supports editing source files written in ++the Interactive Data Language (IDL), and running IDL as an inferior shell@footnote{IDLWAVE can also be used ++for editing source files for the related WAVE/CL language, but with only ++limited support.}. It is a feature-rich replacement for the IDLDE ++development environment included with IDL, and uses the full power of ++Emacs to make editing and running IDL programs easier, quicker, and more ++structured. ++ ++IDLWAVE consists of two main parts: a major mode for editing IDL ++source files (@code{idlwave-mode}) and a mode for running the IDL ++program as an inferior shell (@code{idlwave-shell-mode}). Although ++one mode can be used without the other, both work together closely to ++form a complete development environment. Here is a brief summary of ++what IDLWAVE does: ++ ++@itemize @bullet ++@item ++Smart code indentation and automatic-formatting. ++@item ++Three level syntax highlighting support. ++@item ++Context-sensitive display of calling sequences and keywords for more ++than 1000 native IDL routines, extendible to any additional number of ++local routines, and already available with many pre-scanned libraries. ++@item ++Fast, context-sensitive online HTML help, or source-header help for ++undocumented routines. ++@item ++Context sensitive completion of routine names, keywords, system ++variables, class names and much more. ++@item ++Easy insertion of code templates and abbreviations of common constructs. ++@item ++Automatic corrections to enforce a variety of customizable coding ++standards. ++@item ++Integrity checks and auto-termination of logical blocks. ++@item ++Routine name space conflict search with likelihood-of-use ranking. ++@item ++Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). ++@item ++Documentation support. ++@item ++Running IDL as an inferior Shell with history search, command line ++editing and all the completion and routine info capabilities present in ++IDL source buffers. ++@item ++Full handling of debugging with breakpoints, with interactive setting ++of break conditions, and easy stepping through code. ++@item ++Compilation, execution and interactive single-keystroke debugging of ++programs directly from the source buffer. ++@item ++Quick, source-guided navigation of the calling stack, with variable ++inspection, etc. ++@item ++Examining variables and expressions with a mouse click. ++@item ++And much, much more... ++@end itemize ++ ++@ifnottex ++@cindex Screenshots ++Here are a number of screenshots showing IDLWAVE in action: ++ ++@itemize @bullet ++@item ++@uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer} ++@item ++@uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed} ++@item ++@uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.} ++@item ++@uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed} ++@item ++@uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code ++stopped at a breakpoint} ++@end itemize ++@end ifnottex ++ ++IDLWAVE is the distant successor to the @file{idl.el} and ++@file{idl-shell.el} files written by Chris Chase. The modes and files ++had to be renamed because of a name space conflict with CORBA's ++@code{idl-mode}, defined in Emacs in the file @file{cc-mode.el}. ++ ++In this manual, each section ends with a list of related user options. ++Don't be confused by the sheer number of options available --- in most ++cases the default settings are just fine. The variables are listed here ++to make sure you know where to look if you want to change anything. For ++a full description of what a particular variable does and how to ++configure it, see the documentation string of that variable (available ++with @kbd{C-h v}). Some configuration examples are also given in the ++appendix. ++ ++@node IDLWAVE in a Nutshell, Getting Started, Introduction, Top ++@chapter IDLWAVE in a Nutshell ++@cindex Summary of important commands ++@cindex IDLWAVE in a Nutshell ++@cindex Nutshell, IDLWAVE in a ++ ++@subheading Editing IDL Programs ++ ++@multitable @columnfractions .15 .85 ++@item @key{TAB} ++@tab Indent the current line relative to context. ++@item @kbd{C-M-\} ++@tab Re-indent all lines in the current region. ++@item @kbd{C-M-q} ++@tab Re-indent all lines in the current routine. ++@item @kbd{C-u @key{TAB}} ++@tab Re-indent all lines in the current statement. ++@item @kbd{M-@key{RET}} ++@tab Start a continuation line, splitting the current line at point. ++@item @kbd{M-;} ++@tab Start new comment at line beginning or after code, or (un)comment ++highlighted region. ++@item @kbd{M-q} ++@tab Fill the current comment paragraph. ++@item @kbd{C-c ?} ++@tab Display calling sequence and keywords for the procedure or function call ++at point. ++@item @kbd{M-?} ++@tab Load context sensitive online help for nearby routine, keyword, etc. ++@item @kbd{M-@key{TAB}} ++@tab Complete a procedure name, function name or keyword in the buffer. ++@item @kbd{C-c C-i} ++@tab Update IDLWAVE's knowledge about functions and procedures. ++@item @kbd{C-c C-v} ++@tab Visit the source code of a procedure/function. ++@item @kbd{C-u C-c C-v} ++@tab Visit the source code of a procedure/function in this buffer. ++@item @kbd{C-c C-h} ++@tab Insert a standard documentation header. ++@item @kbd{C-c @key{RET}} ++@tab Insert a new timestamp and history item in the documentation header. ++@end multitable ++ ++@subheading Running the IDLWAVE Shell, Debugging Programs ++ ++@multitable @columnfractions .15 .85 ++@item @kbd{C-c C-s} ++@tab Start IDL as a subprocess and/or switch to the shell buffer. ++@item @key{Up}, @kbd{M-p} ++@tab Cycle back through IDL command history. ++@item @key{Down},@kbd{M-n} ++@tab Cycle forward. ++@item @kbd{@key{TAB}} ++@tab Complete a procedure name, function name or keyword in the shell buffer. ++@item @kbd{C-c C-d C-c} ++@tab Save and compile the source file in the current buffer. ++@item @kbd{C-c C-d C-e} ++@tab Compile and run the current region. ++@item @kbd{C-c C-d C-x} ++@tab Go to next syntax error. ++@item @kbd{C-c C-d C-v} ++@tab Switch to electric debug mode. ++@item @kbd{C-c C-d C-b} ++@tab Set a breakpoint at the nearest viable source line. ++@item @kbd{C-c C-d C-d} ++@tab Clear the nearest breakpoint. ++@item @kbd{C-c C-d [} ++@tab Go to the previous breakpoint. ++@item @kbd{C-c C-d ]} ++@tab Go to the next breakpoint. ++@item @kbd{C-c C-d C-p} ++@tab Print the value of the expression near point in IDL. ++@end multitable ++ ++@subheading Commonly used Settings in @file{.emacs} ++@lisp ++;; Change the indentation preferences ++;; Start autoloading routine info after 2 idle seconds ++(setq idlwave-init-rinfo-when-idle-after 2) ++;; Pad operators with spaces ++(setq idlwave-do-actions t ++ idlwave-surround-by-blank t) ++;; Syntax Highlighting ++(add-hook 'idlwave-mode-hook 'turn-on-font-lock) ++;; Automatically start the shell when needed ++(setq idlwave-shell-automatic-start t) ++;; Bind debugging commands with CONTROL and SHIFT modifiers ++(setq idlwave-shell-debug-modifiers '(control shift)) ++@end lisp ++ ++@html ++ ++@end html ++ ++@node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top ++@chapter Getting Started (Tutorial) ++@cindex Quick-Start ++@cindex Tutorial ++@cindex Getting Started ++ ++@menu ++* Lesson I -- Development Cycle:: ++* Lesson II -- Customization:: ++* Lesson III -- User Catalog:: ++@end menu ++ ++@node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started ++@section Lesson I: Development Cycle ++ ++The purpose of this tutorial is to guide you through a very basic ++development cycle using IDLWAVE. We will paste a simple program into ++a buffer and use the shell to compile, debug and run it. On the way ++we will use many of the important IDLWAVE commands. Note, however, ++that IDLWAVE has many more capabilities than covered here, which can ++be discovered by reading the entire manual, or hovering over the ++shoulder of your nearest IDLWAVE guru for a few days. ++ ++It is assumed that you have access to Emacs or XEmacs with the full ++IDLWAVE package including online help. We also assume that you are ++familiar with Emacs and can read the nomenclature of key presses in ++Emacs (in particular, @kbd{C} stands for @key{CONTROL} and @kbd{M} for ++@key{META} (often the @key{ALT} key carries this functionality)). ++ ++Open a new source file by typing: ++ ++@example ++@kbd{C-x C-f tutorial.pro @key{RET}} ++@end example ++ ++A buffer for this file will pop up, and it should be in IDLWAVE mode, ++indicated in the mode line just below the editing window. Also, the ++menu bar should contain @samp{IDLWAVE}. ++ ++Now cut-and-paste the following code, also available as ++@file{tutorial.pro} in the IDLWAVE distribution. ++ ++@example ++function daynr,d,m,y ++ ;; compute a sequence number for a date ++ ;; works 1901-2099. ++ if y lt 100 then y = y+1900 ++ if m le 2 then delta = 1 else delta = 0 ++ m1 = m + delta*12 + 1 ++ y1 = y * delta ++ return, d + floor(m1*30.6)+floor(y1*365.25)+5 ++end ++ ++function weekday,day,month,year ++ ;; compute weekday number for date ++ nr = daynr(day,month,year) ++ return, nr mod 7 ++end ++ ++pro plot_wday,day,month ++ ;; Plot the weekday of a date in the first 10 years of this century. ++ years = 2000,+indgen(10) ++ wdays = intarr(10) ++ for i=0,n_elements(wdays)-1 do begin ++ wdays[i] = weekday(day,month,years[i]) ++ end ++ plot,years,wdays,YS=2,YT="Wday (0=Sunday)" ++end ++@end example ++ ++The indentation probably looks funny, since it's different from the ++settings you use, so use the @key{TAB} key in each line to ++automatically line it up (or, more quickly, @emph{select} the entire ++buffer with @kbd{C-x h}, and indent the whole region with ++@kbd{C-M-\}). Notice how different syntactical elements are ++highlighted in different colors, if you have set up support for ++font-lock. ++ ++Let's check out two particular editing features of IDLWAVE. Place the ++cursor after the @code{end} statement of the @code{for} loop and press ++@key{SPC}. IDLWAVE blinks back to the beginning of the block and ++changes the generic @code{end} to the specific @code{endfor} ++automatically (as long as the variable @code{idlwave-expand-generic-end} ++is turned on --- @pxref{Lesson II -- Customization}). Now place the ++cursor in any line you would like to split and press @kbd{M-@key{RET}}. ++The line is split at the cursor position, with the continuation @samp{$} ++and indentation all taken care of. Use @kbd{C-/} to undo the last ++change. ++ ++The procedure @code{plot_wday} is supposed to plot the day of the week ++of a given date for the first 10 years of the 21st century. As in ++most code, there are a few bugs, which we are going to use IDLWAVE to ++help us fix. ++ ++First, let's launch the IDLWAVE shell. You do this with the command ++@kbd{C-c C-s}. The Emacs window will split or another window will popup ++to display IDL running in a shell interaction buffer. Type a few ++commands like @code{print,!PI} to convince yourself that you can work ++there just as well as in a terminal, or the IDLDE. Use the arrow keys ++to cycle through your command history. Are we having fun now? ++ ++Now go back to the source window and type @kbd{C-c C-d C-c} to compile ++the program. If you watch the shell buffer, you see that IDLWAVE types ++@samp{.run "tutorial.pro"} for you. But the compilation fails because ++there is a comma in the line @samp{years=...}. The line with the error ++is highlighted and the cursor positioned at the error, so remove the ++comma (you should only need to hit @kbd{Delete}!). Compile again, using ++the same keystrokes as before. Notice that the file is automatically ++saved for you. This time everything should work fine, and you should ++see the three routines compile. ++ ++Now we want to use the command to plot the day of the week on January ++1st. We could type the full command ourselves, but why do that? Go ++back to the shell window, type @samp{plot_} and hit @key{TAB}. After ++a bit of a delay (while IDLWAVE initializes its routine info database, ++if necessary), the window will split to show all procedures it knows ++starting with that string, and @w{@code{plot_wday}} should be one of ++them. Saving the buffer alerted IDLWAVE about this new routine. ++Click with the middle mouse button on @code{plot_wday} and it will be ++copied to the shell buffer, or if you prefer, add @samp{w} to ++@samp{plot_} to make it unambiguous (depending on what other routines ++starting with @samp{plot_} you have installed on your system), hit ++@key{TAB} again, and the full routine name will be completed. Now ++provide the two arguments: ++ ++@example ++plot_wday,1,1 ++@end example ++ ++@noindent and press @key{RET}. This fails with an error message telling ++you the @code{YT} keyword to plot is ambiguous. What are the allowed ++keywords again? Go back to the source window and put the cursor into ++the `plot' line and press @kbd{C-c ?}. This shows the routine info ++window for the plot routine, which contains a list of keywords, along ++with the argument list. Oh, we wanted @code{YTITLE}. Fix that up. ++Recompile with @kbd{C-c C-d C-c}. Jump back into the shell with ++@kbd{C-c C-s}, press the @key{UP} arrow to recall the previous command ++and execute again. ++ ++This time we get a plot, but it is pretty ugly --- the points are all ++connected with a line. Hmm, isn't there a way for @code{plot} to use ++symbols instead? What was that keyword? Position the cursor on the ++plot line after a comma (where you'd normally type a keyword), and hit ++@kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, ++there it is, @code{PSYM}. Middle click to insert it. An @samp{=} ++sign is included for you too. Now what were the values of @code{PSYM} ++supposed to be? With the cursor on or after the keyword, press ++@kbd{M-?} for online help (alternatively, you could have right clicked ++on the colored keyword itself in the completion list). A browser will ++pop up showing the HTML documentation for the @code{PYSM} keyword. ++OK, let's use diamonds=4. Fix this, recompile (you know the command ++by now: @kbd{C-c C-d C-c}), go back to the shell (if it's vanished, ++you know what to do: @kbd{C-c C-s}) and execute again. Now things ++look pretty good. ++ ++Let's try a different day --- how about April fool's day? ++ ++@example ++plot_wday,1,4 ++@end example ++ ++Oops, this looks very wrong. All April Fool's days cannot be Fridays! ++We've got a bug in the program, perhaps in the @code{daynr} function. ++Let's put a breakpoint on the last line there. Position the cursor on ++the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a ++breakpoint (as you see in the shell window), and the break line is ++indicated. Back to the shell buffer, re-execute the previous command. ++IDL stops at the line with the breakpoint. Now hold down the SHIFT ++key and click with the middle mouse button on a few variables there: ++@samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't ++the correct type. CONTROL-SHIFT middle-click on it for help. Well, ++it's an integer, so that's not the problem. Aha, @samp{y1} is zero, ++but it should be the year, depending on delta. Shift click ++@samp{delta} to see that it's 0. Below, we see the offending line: ++@samp{y1=y*delta...} the multiplication should have been a minus sign! ++Hit @kbd{q} to exit the debugging mode, and fix the line to read: ++ ++@example ++y1 = y - delta ++@end example ++ ++Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the ++command. Everything should now work fine. How about those leap years? ++Change the code to plot 100 years and see that every 28 years, the ++sequence of weekdays repeats. ++ ++@node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started ++@section Lesson II: Customization ++ ++Emacs is probably the most customizable piece of software ever written, ++and it would be a shame if you did not make use of this to adapt IDLWAVE ++to your own preferences. Customizing Emacs or IDLWAVE is accomplished ++by setting Lisp variables in the @file{.emacs} file in your home ++directory --- but do not be dismayed; for the most part, you can just ++copy and work from the examples given here. ++ ++Let's first use a boolean variable. These are variables which you turn ++on or off, much like a checkbox. A value of @samp{t} means on, a value ++of @samp{nil} means off. Copy the following line into your ++@file{.emacs} file, exit and restart Emacs. ++ ++@lisp ++(setq idlwave-reserved-word-upcase t) ++@end lisp ++ ++When this option is turned on, each reserved word you type into an IDL ++source buffer will be converted to upper case when you press @key{SPC} ++or @key{RET} right after the word. Try it out! @samp{if} changes to ++@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this ++behavior, remove the option again from your @file{.emacs} file and ++restart Emacs. ++ ++You likely have your own indentation preferences for IDL code. For ++example, some may prefer to indent the main block of an IDL program ++slightly from the margin and use only 3 spaces as indentation between ++@code{BEGIN} and @code{END}. Try the following lines in @file{.emacs}: ++ ++@lisp ++(setq idlwave-main-block-indent 1) ++(setq idlwave-block-indent 3) ++(setq idlwave-end-offset -3) ++@end lisp ++ ++Restart Emacs, and re-indent the program we developed in the first part ++of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep ++these lines in @file{.emacs}, with values adjusted to your likings. If ++you want to get more information about any of these variables, type, ++e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which ++variables can be customized, look for items marked @samp{User Option:} ++throughout this manual. ++ ++If you cannot seem to master this Lisp customization in @file{.emacs}, ++there is another, more user-friendly way to customize all the IDLWAVE ++variables. You can access it through the IDLWAVE menu in one of the ++@file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE ++Group}. Here you'll be presented with all the various variables grouped ++into categories. You can navigate the hierarchy (e.g. @samp{IDLWAVE ++Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand ++Generic End} to turn on @code{END} expansion), read about the variables, ++change them, and `Save for Future Sessions'. Few of these variables ++need customization, but you can exercise considerable control over ++IDLWAVE's functionality with them. ++ ++You may also find the key bindings used for the debugging commands too ++long and complicated. Often we have heard complaints along the lines ++of, ``Do I really have to go through the finger gymnastics of @kbd{C-c ++C-d C-c} to run a simple command?'' Due to Emacs rules and ++conventions, shorter bindings cannot be set by default, but you can ++easily enable them. First, there is a way to assign all debugging ++commands in a single sweep to another simpler combination. The only ++problem is that we have to use something which Emacs does not need for ++other important commands. One good option is to execute debugging ++commands by holding down @key{CONTROL} and @key{SHIFT} while pressing ++a single character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} ++for compiling the current source file, @kbd{C-S-a} for deleting all ++breakpoints (try it, it's easier). You can enable this with: ++ ++@lisp ++(setq idlwave-shell-debug-modifiers '(shift control)) ++@end lisp ++ ++@noindent If you have a special keyboard with, for example, a ++@key{SUPER} key, you could even shorten that: ++ ++@lisp ++(setq idlwave-shell-debug-modifiers '(super)) ++@end lisp ++ ++@noindent to get compilation on @kbd{S-c}. Often, a modifier key like ++@key{SUPER} or @key{HYPER} is bound or can be bound to an otherwise ++unused key on your keyboard --- consult your system documentation. ++ ++You can also assign specific commands to keys. This you must do in the ++@emph{mode-hook}, a special function which is run when a new IDLWAVE ++buffer gets set up. The possibilities for key customization are ++endless. Here we set function keys f4-f8 to common debugging commands. ++ ++@lisp ++;; First for the source buffer ++(add-hook 'idlwave-mode-hook ++ (lambda () ++ (local-set-key [f4] 'idlwave-shell-retall) ++ (local-set-key [f5] 'idlwave-shell-break-here) ++ (local-set-key [f6] 'idlwave-shell-clear-current-bp) ++ (local-set-key [f7] 'idlwave-shell-cont) ++ (local-set-key [f8] 'idlwave-shell-clear-all-bp))) ++;; Then for the shell buffer ++(add-hook 'idlwave-shell-mode-hook ++ (lambda () ++ (local-set-key [f4] 'idlwave-shell-retall) ++ (local-set-key [f5] 'idlwave-shell-break-here) ++ (local-set-key [f6] 'idlwave-shell-clear-current-bp) ++ (local-set-key [f7] 'idlwave-shell-cont) ++ (local-set-key [f8] 'idlwave-shell-clear-all-bp))) ++@end lisp ++ ++@node Lesson III -- User Catalog, , Lesson II -- Customization, Getting Started ++@section Lesson III: User and Library Catalogs ++ ++We have already used the routine info display in the first part of this ++tutorial. This was the invoked using @kbd{C-c ?}, and displays ++information about the IDL routine near the cursor position. Wouldn't it ++be nice to have the same kind of information available for your own ++routines and for the huge amount of code in major libraries like JHUPL ++or the IDL-Astro library? In many cases, you may already have this ++information. Files named @file{.idlwave_catalog} in library directories ++contain scanned information on the routines in that directory; many ++popular libraries ship with these ``library catalogs'' pre-scanned. ++Users can scan their own routines in one of two ways: either using the ++supplied tool to scan directories and build their own ++@file{.idlwave_catalog} files, or using the built-in method to create a ++single ``user catalog'', which we'll show here. @xref{Catalogs}, for ++more information on choosing which method to use. ++ ++To build a user catalog, select @code{Routine Info/Select Catalog ++Directories} from the IDLWAVE entry in the menu bar. If necessary, ++start the shell first with @kbd{C-c C-s} (@pxref{Starting the Shell}). ++IDLWAVE will find out about the IDL @code{!PATH} variable and offer a ++list of directories on the path. Simply select them all (or whichever ++you want --- directories with existing library catalogs will not be ++selected by default) and click on the @samp{Scan&Save} button. Then ++go for a cup of coffee while IDLWAVE collects information for each and ++every IDL routine on your search path. All this information is ++written to the file @file{.idlwave/idlusercat.el} in your home ++directory and will from now on automatically load whenever you use ++IDLWAVE. You may find it necessary to rebuild the catalog on occasion ++as your local libraries change, or build a library catalog for those ++directories instead. Invoke routine info (@kbd{C-c ?}) or completion ++(@kbd{M-@key{TAB}}) on any routine or partial routine name you know to ++be located in the library. E.g., if you have scanned the IDL-Astro ++library: ++ ++@example ++ a=readf@key{M-@key{TAB}} ++@end example ++ ++expands to `readfits('. Then try ++ ++@example ++ a=readfits(@key{C-c ?} ++@end example ++ ++and you get: ++ ++@example ++Usage: Result = READFITS(filename, header, heap) ++... ++@end example ++ ++I hope you made it until here. Now you are set to work with IDLWAVE. ++On the way you will want to change other things, and to learn more ++about the possibilities not discussed in this short tutorial. Read ++the manual, look at the documentation strings of interesting variables ++(with @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the ++remaining questions on the newsgroup @code{comp.lang.idl-pvwave}. ++ ++@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top ++@chapter The IDLWAVE Major Mode ++@cindex IDLWAVE major mode ++@cindex Major mode, @code{idlwave-mode} ++ ++The IDLWAVE major mode supports editing IDL source files. In this ++chapter we describe the main features of the mode and how to customize ++them. ++ ++@menu ++* Code Formatting:: Making code look nice ++* Routine Info:: Calling Sequence and Keyword List ++* Online Help:: One key press from source to help ++* Completion:: Completing routine names and Keywords ++* Routine Source:: Finding routines, the easy way ++* Resolving Routines:: Force the Shell to compile a routine ++* Code Templates:: Frequent code constructs ++* Abbreviations:: Abbreviations for common commands ++* Actions:: Changing case, Padding, End checking ++* Doc Header:: Inserting a standard header ++* Motion Commands:: Moving through the structure of a program ++* Misc Options:: Things that fit nowhere else ++@end menu ++ ++@node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode ++@section Code Formatting ++@cindex Code formatting ++@cindex Formatting, of code ++ ++@menu ++* Code Indentation:: Reflecting the logical structure ++* Continued Statement Indentation:: ++* Comment Indentation:: Special indentation for comment lines ++* Continuation Lines:: Splitting statements over lines ++* Syntax Highlighting:: Font-lock support ++* Octals and Highlighting:: Why "123 causes problems ++@end menu ++ ++The IDL language, with its early roots in FORTRAN, modern ++implementation in C, and liberal borrowing of features of many vector ++and other languages along its 25+ year history, has inherited an ++unusual mix of syntax elements. Left to his or her own devices, a ++novice IDL programmer will often conjure code which is very difficult ++to read and impossible to adapt. Much can be gleaned from studying ++available IDL code libraries for coding style pointers, but, due to ++the variety of IDL syntax elements, replicating this style can be ++challenging at best. Luckily, IDLWAVE understands the structure of ++IDL code very well, and takes care of almost all formatting issues for ++you. After configuring it to match your coding standards, you can ++rely on it to help keep your code neat and organized. ++ ++ ++@node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting ++@subsection Code Indentation ++@cindex Code indentation ++@cindex Indentation ++ ++Like all Emacs programming modes, IDLWAVE performs code indentation. ++The @key{TAB} key indents the current line relative to context. ++@key{LFD} insert a newline and indents the new line. The indentation is ++governed by a number of variables. IDLWAVE indents blocks (between ++@code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and ++continuation lines. ++ ++@cindex Foreign code, adapting ++@cindex Indentation, of foreign code ++@kindex C-M-\ ++To re-indent a larger portion of code (e.g. when working with foreign ++code written with different conventions), use @kbd{C-M-\} ++(@code{indent-region}) after marking the relevant code. Useful marking ++commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current ++subprogram). The command @kbd{C-M-q} reindents the entire current ++routine. @xref{Actions}, for information how to impose additional ++formatting conventions on foreign code. ++ ++@defopt idlwave-main-block-indent (@code{2}) ++Extra indentation for the main block of code. That is the block between ++the FUNCTION/PRO statement and the END statement for that program ++unit. ++@end defopt ++ ++@defopt idlwave-block-indent (@code{3}) ++Extra indentation applied to block lines. If you change this, you ++probably also want to change @code{idlwave-end-offset}. ++@end defopt ++ ++@defopt idlwave-end-offset (@code{-3}) ++Extra indentation applied to block END lines. A value equal to negative ++@code{idlwave-block-indent} will make END lines line up with the block ++BEGIN lines. ++@end defopt ++ ++@node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting ++@subsection Continued Statement Indentation ++@cindex Indentation, continued statement ++@cindex Continued statement indentation ++Continuation lines (following a line ending with @code{$}) can receive a ++fixed indentation offset from the main level, but in several situations ++IDLWAVE can use a special form of indentation which aligns continued ++statements more naturally. Special indentation is calculated for ++continued routine definition statements and calls, enclosing parentheses ++(like function calls, structure/class definitions, explicit structures ++or lists, etc.), and continued assignments. An attempt is made to line ++up with the first non-whitespace character after the relevant opening ++punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}). For ++lines without any non-comment characters on the line with the opening ++punctuation, the continued line(s) are aligned just past the ++punctuation. An example: ++ ++@example ++function foo, a, b, $ ++ c, d ++ bar = sin( a + b + $ ++ c + d) ++end ++@end example ++@noindent ++ ++The only drawback to this special continued statement indentation is ++that it consumes more space, e.g., for long function names or left hand ++sides of an assignment: ++ ++@example ++function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $ ++ c, d ++@end example ++ ++You can instruct IDLWAVE when to avoid using this special continuation ++indentation by setting the variable ++@code{idlwave-max-extra-continuation-indent}, which specifies the ++maximum additional indentation beyond the basic indent to be ++tolerated, otherwise defaulting to a fixed-offset from the enclosing ++indent (the size of which offset is set in ++@code{idlwave-continuation-indent}). As a special case, continuations ++of routine calls without any arguments or keywords will @emph{not} ++align the continued line, under the assumption that you continued ++because you needed the space. ++ ++Also, since the indentation level can be somewhat dynamic in continued ++statements with special continuation indentation, especially if ++@code{idlwave-max-extra-continuation-indent} is small, the key ++@kbd{C-u @key{TAB}} will re-indent all lines in the current statement. ++Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil}, ++overrides the @code{idlwave-max-extra-continuation-indent} limit, for ++parentheses only, forcing them always to line up. ++ ++ ++@defopt idlwave-continuation-indent (@code{2}) ++Extra indentation applied to normal continuation lines. ++@end defopt ++ ++@defopt idlwave-max-extra-continuation-indent (@code{20}) ++The maximum additional indentation (over the basic continuation-indent) ++that will be permitted for special continues. To effectively disable ++special continuation indentation, set to @code{0}. To enable it ++constantly, set to a large number (like @code{100}). Note that the ++indentation in a long continued statement never decreases from line to ++line, outside of nested parentheses statements. ++@end defopt ++ ++@defopt idlwave-indent-to-open-paren (@code{t}) ++Non-@code{nil} means indent continuation lines to innermost open ++parenthesis, regardless of whether the ++@code{idlwave-max-extra-continuation-indent} limit is satisfied. ++@end defopt ++ ++@node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting ++@subsection Comment Indentation ++@cindex Comment indentation ++@cindex Hanging paragraphs ++@cindex Paragraphs, filling ++@cindex Paragraphs, hanging ++ ++In IDL, lines starting with a @samp{;} are called @emph{comment lines}. ++Comment lines are indented as follows: ++ ++@multitable @columnfractions .1 .90 ++@item @code{;;;} ++@tab The indentation of lines starting with three semicolons remains ++unchanged. ++@item @code{;;} ++@tab Lines starting with two semicolons are indented like the surrounding code. ++@item @code{;} ++@tab Lines starting with a single semicolon are indented to a minimum column. ++@end multitable ++ ++@noindent ++The indentation of comments starting in column 0 is never changed. ++ ++@defopt idlwave-no-change-comment ++The indentation of a comment starting with this regexp will not be ++changed. ++@end defopt ++ ++@defopt idlwave-begin-line-comment ++A comment anchored at the beginning of line. ++@end defopt ++ ++@defopt idlwave-code-comment ++A comment that starts with this regexp is indented as if it is a part of ++IDL code. ++@end defopt ++ ++@node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting ++@subsection Continuation Lines and Filling ++@cindex Continuation lines ++@cindex Line splitting ++@cindex String splitting ++@cindex Splitting, of lines ++ ++@kindex M-@key{RET} ++In IDL, a newline character terminates a statement unless preceded by a ++@samp{$}. If you would like to start a continuation line, use ++@kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}. ++It inserts the continuation character @samp{$}, terminates the line and ++indents the new line. The command @kbd{M-@key{RET}} can also be invoked ++inside a string to split it at that point, in which case the @samp{+} ++concatenation operator is used. ++ ++@cindex Filling ++@cindex @code{auto-fill-mode} ++@cindex Hanging paragraphs ++When filling comment paragraphs, IDLWAVE overloads the normal filling ++functions and uses a function which creates the hanging paragraphs ++customary in IDL routine headers. When @code{auto-fill-mode} is turned ++on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the ++first line of a paragraph contains a match for ++@code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent ++lines are positioned to line up after it, as in the following example. ++ ++@example ++@group ++;================================= ++; x - an array containing ++; lots of interesting numbers. ++; ++; y - another variable where ++; a hanging paragraph is used ++; to describe it. ++;================================= ++@end group ++@end example ++ ++@kindex M-q ++You can also refill a comment at any time paragraph with @kbd{M-q}. ++Comment delimiting lines as in the above example, consisting of one or ++more @samp{;} followed by one or more of the characters @samp{+=-_*}, ++are kept in place, as is. ++ ++@defopt idlwave-fill-comment-line-only (@code{t}) ++Non-@code{nil} means auto fill will only operate on comment lines. ++@end defopt ++ ++@defopt idlwave-auto-fill-split-string (@code{t}) ++Non-@code{nil} means auto fill will split strings with the IDL @samp{+} ++operator. ++@end defopt ++ ++@defopt idlwave-split-line-string (@code{t}) ++Non-@code{nil} means @code{idlwave-split-line} will split strings with ++@samp{+}. ++@end defopt ++ ++@defopt idlwave-hanging-indent (@code{t}) ++Non-@code{nil} means comment paragraphs are indented under the hanging ++indent given by @code{idlwave-hang-indent-regexp} match in the first ++line of the paragraph. ++@end defopt ++ ++@defopt idlwave-hang-indent-regexp (@code{"- "}) ++Regular expression matching the position of the hanging indent ++in the first line of a comment paragraph. ++@end defopt ++ ++@defopt idlwave-use-last-hang-indent (@code{nil}) ++Non-@code{nil} means use last match on line for ++@code{idlwave-indent-regexp}. ++@end defopt ++ ++@node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting ++@subsection Syntax Highlighting ++@cindex Syntax highlighting ++@cindex Highlighting of syntax ++@cindex Font lock ++ ++Highlighting of keywords, comments, strings etc. can be accomplished ++with @code{font-lock}. If you are using @code{global-font-lock-mode} ++(in Emacs), or have @code{font-lock} turned on in any other buffer in ++XEmacs, it should also automatically work in IDLWAVE buffers. If you'd ++prefer invoking font-lock individually by mode, you can enforce it in ++@code{idlwave-mode} with the following line in your @file{.emacs}: ++ ++@lisp ++(add-hook 'idlwave-mode-hook 'turn-on-font-lock) ++@end lisp ++ ++@noindent IDLWAVE supports 3 increasing levels of syntax highlighting. ++The variable @code{font-lock-maximum-decoration} determines which level ++is selected. Individual categories of special tokens can be selected ++for highlighting using the variable ++@code{idlwave-default-font-lock-items}. ++ ++@defopt idlwave-default-font-lock-items ++Items which should be fontified on the default fontification level ++2. ++@end defopt ++ ++@node Octals and Highlighting, , Syntax Highlighting, Code Formatting ++@subsection Octals and Highlighting ++@cindex Syntax highlighting, Octals ++@cindex Highlighting of syntax, Octals ++ ++A rare syntax highlighting problem results from an extremely unfortunate ++notation for octal numbers in IDL: @code{"123}. This unpaired quotation ++mark is very difficult to parse, given that it can be mixed on a single ++line with any number of strings. Emacs will incorrectly identify this ++as a string, and the highlighting of following lines of code can be ++distorted, since the string is never terminated. ++ ++One solution to this involves terminating the mistakenly identified ++string yourself by providing a closing quotation mark in a comment: ++ ++@example ++ string("305B) + $ ;" <--- for font-lock ++ ' is an Angstrom.' ++@end example ++ ++@noindent A far better solution is to abandon this notation for octals ++altogether, and use the more sensible alternative IDL provides: ++ ++@example ++ string('305'OB) + ' is an Angstrom.' ++@end example ++ ++@noindent This simultaneously solves the font-lock problem and is more ++consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}. ++ ++@node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode ++@section Routine Info ++@cindex Routine info ++@cindex Updating routine info ++@cindex Scanning buffers for routine info ++@cindex Buffers, scanning for routine info ++@cindex Shell, querying for routine info ++ ++@kindex C-c C-i ++IDL comes bundled with more than one thousand procedures, functions ++and object methods, and large libraries typically contain hundreds or ++even thousands more (each with a few to tens of keywords and ++arguments). This large command set can make it difficult to remember ++the calling sequence and keywords for the routines you use, but ++IDLWAVE can help. It builds up routine information from a wide ++variety of sources; IDLWAVE in fact knows far more about the ++@samp{.pro} routines on your system than IDL itself! It maintains a ++list of all built-in routines, with calling sequences and ++keywords@footnote{This list is created by scanning the IDL manuals and ++might contain (very few) errors. Please report any errors to the ++maintainer, so that they can be fixed.}. It also scans Emacs buffers ++for routine definitions, queries the IDLWAVE-Shell for information ++about routines currently compiled there, and automatically locates ++library and user-created catalogs. This information is updated ++automatically, and so should usually be current. To force a global ++update and refresh the routine information, use @kbd{C-c C-i} ++(@code{idlwave-update-routine-info}). ++ ++@kindex C-c ? ++To display the information about a routine, press @kbd{C-c ?}, which ++calls the command @code{idlwave-routine-info}. When the current cursor ++position is on the name or in the argument list of a procedure or ++function, information will be displayed about the routine. For example, ++consider the indicated cursor positions in the following line: ++ ++@example ++plot,x,alog(x+5*sin(x) + 2), ++ | | | | | | | | ++ 1 2 3 4 5 6 7 8 ++@end example ++ ++@cindex Default routine, for info and help ++On positions 1,2 and 8, information about the @samp{plot} procedure will ++be shown. On positions 3,4, and 7, the @samp{alog} function will be ++described, while positions 5 and 6 will investigate the @samp{sin} ++function. ++ ++When you ask for routine information about an object method, and the ++method exists in several classes, IDLWAVE queries for the class of the ++object, unless the class is already known through a text property on the ++@samp{->} operator (@pxref{Object Method Completion and Class ++Ambiguity}), or by having been explicitly included in the call ++(e.g. @code{a->myclass::Foo}). ++ ++@cindex Calling sequences ++@cindex Keywords of a routine ++@cindex Routine source information ++The description displayed contains the calling sequence, the list of ++keywords and the source location of this routine. It looks like this: ++ ++@example ++Usage: XMANAGER, NAME, ID ++Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER ++ JUST_REG MODAL NO_BLOCK ++Source: SystemLib [LCSB] /soft1/idl53/lib/xmanager.pro ++@end example ++ ++@cindex Categories, of routines ++@cindex Load-path shadows ++@cindex Shadows, load-path ++@cindex IDL variable @code{!PATH} ++@cindex @code{!PATH}, IDL variable ++@cindex IDL variable @code{!DIR} ++@cindex @code{!DIR}, IDL variable ++ ++If a definition of this routine exists in several files accessible to ++IDLWAVE, several @samp{Source} lines will point to the different ++files. This may indicate that your routine is shadowing a system ++library routine, which may or may not be what you want ++(@pxref{Load-Path Shadows}). The information about the calling ++sequence and keywords is derived from the first source listed. ++Library routines are available only if you have scanned your local IDL ++directories or are using pre-scanned libraries (@pxref{Catalogs}). ++The source entry consists of a @emph{source category}, a set of ++@emph{flags} and the path to the @emph{source file}. The following ++default categories exist: ++ ++@multitable @columnfractions .15 .85 ++@item @i{System} ++@tab A system routine of unknown origin. When the system library has ++been scanned as part of a catalog (@pxref{Catalogs}), this category ++will automatically split into the next two. ++@item @i{Builtin} ++@tab A builtin system routine with no source code available. ++@item @i{SystemLib} ++@tab A library system routine in the official lib directory @file{!DIR/lib}. ++@item @i{Obsolete} ++@tab A library routine in the official lib directory @file{!DIR/lib/obsolete}. ++@item @i{Library} ++@tab A routine in a file on IDL's search path @code{!PATH}. ++@item @i{Other} ++@tab Any other routine with a file not known to be on the search path. ++@item @i{Unresolved} ++@tab An otherwise unknown routine the shell lists as unresolved ++(referenced, but not compiled). ++@end multitable ++ ++Any routines discovered in library catalogs (@pxref{Library ++Catalogs}), will display the category assigned during creation, ++e.g. @samp{NasaLib}. For routines not discovered in this way, you can ++create additional categories based on the routine's filename using the ++variable @code{idlwave-special-lib-alist}. ++ ++@cindex Flags, in routine info ++@cindex Duplicate routines ++@cindex Multiply defined routines ++@cindex Routine definitions, multiple ++The flags @code{[LCSB]} indicate the source of the information IDLWAVE ++has regarding the file: from a library catalog (@w{@code{[L---]}}), ++from a user catalog (@w{@code{[-C--]}}, from the IDL Shell ++(@w{@code{[--S-]}}) or from an Emacs buffer (@w{@code{[---B]}}). ++Combinations are possible (a compiled library routine visited in a ++buffer might read @w{@code{[L-SB]}}). If a file contains multiple ++definitions of the same routine, the file name will be prefixed with ++@samp{(Nx)} where @samp{N} is the number of definitions. ++ ++@cindex Online Help from the routine info buffer ++@cindex Active text, in routine info ++@cindex Inserting keywords, from routine info ++@cindex Source file, access from routine info ++Some of the text in the @file{*Help*} routine info buffer will be active ++(it is highlighted when the mouse moves over it). Typically, clicking ++with the right mouse button invokes online help lookup, and clicking ++with the middle mouse button inserts keywords or visits files: ++ ++@multitable @columnfractions 0.15 0.85 ++@item @i{Usage} ++@tab If online help is installed, a click with the @emph{right} mouse ++button on the @i{Usage:} line will access the help for the ++routine (@pxref{Online Help}). ++@item @i{Keyword} ++@tab Online help about keywords is also available with the ++@emph{right} mouse button. Clicking on a keyword with the @emph{middle} ++mouse button will insert this keyword in the buffer from where ++@code{idlwave-routine-info} was called. Holding down @key{SHIFT} while ++clicking also adds the initial @samp{/}. ++@item @i{Source} ++@tab Clicking with the @emph{middle} mouse button on a @samp{Source} line ++finds the source file of the routine and visits it in another window. ++Another click on the same line switches back to the buffer from which ++@kbd{C-c ?} was called. If you use the @emph{right} mouse button, the ++source will not be visited by a buffer, but displayed in the online help ++window. ++@item @i{Classes} ++@tab The @i{Classes} line is only included in the routine info window if ++the current class inherits from other classes. You can click with the ++@emph{middle} mouse button to display routine info about the current ++method in other classes on the inheritance chain, if such a method ++exists there. ++@end multitable ++ ++@defopt idlwave-resize-routine-help-window (@code{t}) ++Non-@code{nil} means resize the Routine-info @file{*Help*} window to ++fit the content. ++@end defopt ++ ++@defopt idlwave-special-lib-alist ++Alist of regular expressions matching special library directories. ++@end defopt ++ ++@defopt idlwave-rinfo-max-source-lines (@code{5}) ++Maximum number of source files displayed in the Routine Info window. ++@end defopt ++ ++ ++@html ++ ++@end html ++@node Online Help, Completion, Routine Info, The IDLWAVE Major Mode ++@section Online Help ++ ++@cindex Online Help ++@cindex @file{idlw-help.txt} ++@cindex @file{idlw-help.el} ++@cindex Installing online help ++@cindex Online Help, Installation ++@cindex Speed, of online help ++@cindex XML Help Catalog ++ ++For IDL system routines, extensive documentation is supplied with IDL. ++IDLWAVE can access the HTML version of this documentation very quickly ++and accurately, based on the local context. This can be @emph{much} ++faster than using the IDL online help application, because IDLWAVE ++usually gets you to the right place in the documentation directly --- ++e.g. a specific keyword of a routine --- without any additional browsing ++and scrolling. ++ ++For this online help to work, an HTML version of the IDL documentation ++is required. Beginning with IDL 6.2, HTML documentation is distributed ++directly with IDL, along with an XML-based catalog of routine ++information. By default, IDLWAVE automatically attempts to convert this ++XML catalog into a format Emacs can more easily understand, and caches ++this information in your @code{idlwave_config_directory} ++(@file{~/.idlwave/}, by default). It also re-scans the XML catalog if ++it is newer than the current cached version. You can force rescan with ++the menu entry @code{IDLWAVE->Routine Info->Rescan XML Help Catalog}. ++ ++Before IDL 6.2, the HTML help was not distributed with IDL, and was not ++part of the standalone IDLWAVE distribution, but had to be downloaded ++separately. This is no longer necessary: all help and routine ++information is supplied with IDL versions 6.2 and later. ++ ++There are a variety of options for displaying the HTML help: see below. ++Help for routines without HTML documentation is also available, by using ++the routine documentation header and/or routine source. ++ ++@kindex M-? ++In any IDL program (or, as with most IDLWAVE commands, in the IDL ++Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with ++@kbd{S-Mouse-3} to access context sensitive online help. The following ++locations are recognized context for help: ++ ++@cindex Context, for online help ++@multitable @columnfractions .25 .75 ++@item @i{Routine names} ++@tab The name of a routine (function, procedure, method). ++@item @i{Keyword Parameters} ++@tab A keyword parameter of a routine. ++@item @i{System Variables} ++@tab System variables like @code{!DPI}. ++@item @i{System Variable Tags} ++@tab System variables tags like @code{!D.X_SIZE}. ++@item @i{IDL Statements} ++@tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. ++@item @i{IDL Controls} ++@tab Control structures like @code{FOR}, @code{SWITCH}, etc. ++@item @i{Class names} ++@tab A class name in an @code{OBJ_NEW} call. ++@item @i{Class Init Keywords} ++@tab Beyond the class name in an @code{OBJ_NEW} call. ++@item @i{Executive Command} ++@tab An executive command like @code{.RUN}. Mostly useful in the shell. ++@item @i{Structure Tags} ++@tab Structure tags like @code{state.xsize} ++@item @i{Class Tags} ++@tab Class tags like @code{self.value}. ++@item @i{Default} ++@tab The routine that would be selected for routine info display. ++@end multitable ++ ++@cindex @code{OBJ_NEW}, special online help ++Note that the @code{OBJ_NEW} function is special in that the help ++displayed depends on the cursor position. If the cursor is on the ++@samp{OBJ_NEW}, this function is described. If it is on the class ++name inside the quotes, the documentation for the class is pulled up. ++If the cursor is @emph{after} the class name, anywhere in the argument ++list, the documentation for the corresponding @code{Init} method and ++its keywords is targeted. ++ ++Apart from an IDLWAVE buffer or shell, there are two more places from ++which online help can be accessed. ++ ++@itemize @bullet ++@item ++Online help for routines and keywords can be accessed through the ++Routine Info display. Click with @kbd{Mouse-3} on an item to see the ++corresponding help (@pxref{Routine Info}). ++@item ++When using completion and Emacs pops up a @file{*Completions*} buffer ++with possible completions, clicking with @kbd{Mouse-3} on a completion ++item invokes help on that item (@pxref{Completion}). Items for which ++help is available in the online system documentation (vs. just the ++program source itself) will be emphasized (e.g. colored blue). ++@end itemize ++@noindent ++In both cases, a blue face indicates that the item is documented in ++the IDL manual, but an attempt will be made to visit non-blue items ++directly in the originating source file. ++ ++ ++@menu ++* Help with HTML Documentation:: ++* Help with Source:: ++@end menu ++ ++@node Help with HTML Documentation, Help with Source, Online Help, Online Help ++@subsection Help with HTML Documentation ++@cindex HTML Help ++@cindex Help using HTML manuals ++@cindex IDL manual, HTML version ++@cindex IDL Assistant ++ ++Help using the HTML documentation is invoked with the built-in Emacs ++command @code{browse-url}, which displays the relevant help topic in a ++browser of your choosing. Beginning with version 6.2, IDL comes with ++the help browser @emph{IDL Assistant}, which it uses by default for ++displaying online help on all supported platforms. This browser ++offers topical searches, an index, and is also now the default and ++recommended IDLWAVE help browser. The variable ++@code{idlwave-help-use-assistant} controls whether this browser is ++used. Note that, due to limitations in the Assistant, invoking help ++within IDLWAVE and @code{? topic} within IDL will result in two ++running copies of Assistant. ++ ++Aside from the IDL Assistant, there are many possible browsers to choose ++among, with differing advantages and disadvantages. The variable ++@code{idlwave-help-browser-function} controls which browser help is sent ++to (as long as @code{idlwave-help-use-assistant} is not set). This ++function is used to set the variable @code{browse-url-browser-function} ++locally for IDLWAVE help only. Customize the latter variable to see ++what choices of browsers your system offers. Certain browsers like ++@code{w3} (bundled with many versions of Emacs) and @code{w3m} ++(@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use ++Emacs buffers to display the HTML help. This can be convenient, ++especially on small displays, and images can even be displayed in-line ++on newer Emacs versions. However, better formatting results are often ++achieved with external browsers, like Mozilla. IDLWAVE assumes any ++browser function containing "w3" is displayed in a local buffer. If you ++are using another Emacs-local browser for which this is not true, set ++the variable @code{idlwave-help-browser-is-local}. ++ ++With IDL 6.2 or later, it is important to ensure that the variable ++@code{idlwave-system-directory} is set (@pxref{Catalogs}). One easy way ++to ensure this is to run the IDL Shell (@kbd{C-c C-s}). It will be ++queried for this directory, and the results will be cached to file for ++subsequent use. ++ ++@xref{HTML Help Browser Tips}, for more information on selecting and ++configuring a browser for use with IDL's HTML help system. ++ ++@defopt idlwave-html-system-help-location @file{help/online_help} ++Relative directory of the system-supplied HTML help directory, ++considered with respect to @code{idlwave-system-directory}. Relevant ++for IDL 6.2 and greater. Should not change. ++@end defopt ++ ++@defopt idlwave-html-help-location @file{/usr/local/etc/} ++The directory where the @file{idl_html_help} HTML directory live. ++Obsolete and ignored for IDL 6.2 and greater ++(@code{idlwave-html-system-help-location} is used instead). ++@end defopt ++ ++@defopt idlwave-help-use-assistant @code{t} ++If set, use the IDL Assistant if possible for online HTML help, ++otherwise use the browser function specified in ++@code{idlwave-help-browser-function}. ++@end defopt ++ ++@defopt idlwave-help-browser-function ++The browser function to use to display IDLWAVE HTML help. Should be ++one of the functions available for setting ++@code{browse-url-browser-function}, which see. ++@end defopt ++ ++@defopt idlwave-help-browser-is-local ++Is the browser selected in @code{idlwave-help-browser-function} run in a ++local Emacs buffer or window? Defaults to @code{t} if the function ++contains "-w3". ++@end defopt ++ ++@defopt idlwave-help-link-face ++The face for links to IDLWAVE online help. ++@end defopt ++ ++@node Help with Source, , Help with HTML Documentation, Online Help ++@subsection Help with Source ++@cindex Help using routine source ++ ++@cindex Source code, as online help ++@cindex DocLib header, as online help ++For routines which are not documented in an HTML manual (for example ++personal or library routines), the source code itself is used as help ++text. If the requested information can be found in a (more or less) ++standard DocLib file header, IDLWAVE shows the header (scrolling down to ++a keyword, if appropriate). Otherwise the routine definition statement ++(@code{pro}/@code{function}) is shown. The doclib header sections which ++are searched for include @samp{NAME} and @samp{KEYWORDS}. Localization ++support can be added by customizing the @code{idlwave-help-doclib-name} ++and @code{idlwave-help-doclib-keyword} variables. ++ ++@cindex Structure tags, in online help ++@cindex Class tags, in online help ++Help is also available for class structure tags (@code{self.TAG}), and ++generic structure tags, if structure tag completion is enabled ++(@pxref{Structure Tag Completion}). This is implemented by visiting the ++tag within the class or structure definition source itself. Help is not ++available on built-in system class tags. ++ ++The help window is normally displayed in the same frame, but can be ++popped-up in a separate frame. The following commands can be used to ++navigate inside the help system for source files: ++ ++@multitable @columnfractions .15 .85 ++@item @kbd{@key{SPACE}} ++@tab Scroll forward one page. ++@item @kbd{@key{RET}} ++@tab Scroll forward one line. ++@item @kbd{@key{DEL}} ++@tab Scroll back one page. ++@item @kbd{h} ++@tab Jump to DocLib Header of the routine whose source is displayed ++as help. ++@item @kbd{H} ++@tab Jump to the first DocLib Header in the file. ++@item @kbd{.} @r{(Dot)} ++@tab Jump back and forth between the routine definition (the ++@code{pro}/@code{function} statement) and the description of the help ++item in the DocLib header. ++@item @kbd{F} ++@tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}. ++@item @kbd{q} ++@tab Kill the help window. ++@end multitable ++ ++ ++@defopt idlwave-help-use-dedicated-frame (@code{nil}) ++Non-@code{nil} means use a separate frame for Online Help if possible. ++@end defopt ++ ++@defopt idlwave-help-frame-parameters ++The frame parameters for the special Online Help frame. ++@end defopt ++ ++@defopt idlwave-max-popup-menu-items (@code{20}) ++Maximum number of items per pane in pop-up menus. ++@end defopt ++ ++@defopt idlwave-extra-help-function ++Function to call for help if the normal help fails. ++@end defopt ++ ++@defopt idlwave-help-fontify-source-code (@code{nil}) ++Non-@code{nil} means fontify source code displayed as help. ++@end defopt ++ ++@defopt idlwave-help-source-try-header (@code{t}) ++Non-@code{nil} means try to find help in routine header when ++displaying source file. ++@end defopt ++ ++@defopt idlwave-help-doclib-name (@code{"name"}) ++The case-insensitive heading word in doclib headers to locate the ++@emph{name} section. Can be a regexp, e.g. @code{"\\(name\\|nom\\)"}. ++@end defopt ++ ++@defopt idlwave-help-doclib-keyword (@code{"KEYWORD"}) ++The case-insensitive heading word in doclib headers to locate the ++@emph{keywords} section. Can be a regexp. ++@end defopt ++ ++ ++@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode ++@section Completion ++@cindex Completion ++@cindex Keyword completion ++@cindex Method completion ++@cindex Object method completion ++@cindex Class name completion ++@cindex Function name completion ++@cindex Procedure name completion ++ ++@kindex M-@key{TAB} ++@kindex C-c C-i ++IDLWAVE offers completion for class names, routine names, keywords, ++system variables, system variable tags, class structure tags, regular ++structure tags and file names. As in many programming modes, completion ++is bound to @kbd{M-@key{TAB}} (or simply @kbd{@key{TAB}} in the IDLWAVE ++Shell --- @pxref{Using the Shell}). Completion uses exactly the same ++internal information as routine info, so when necessary (rarely) it can ++be updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}). ++ ++The completion function is context sensitive and figures out what to ++complete based on the location of the point. Here are example lines and ++what @kbd{M-@key{TAB}} would try to complete when the cursor is on the ++position marked with a @samp{_}: ++ ++@example ++plo_ @r{Procedure} ++x = a_ @r{Function} ++plot,xra_ @r{Keyword of @code{plot} procedure} ++plot,x,y,/x_ @r{Keyword of @code{plot} procedure} ++plot,min(_ @r{Keyword of @code{min} function} ++obj -> a_ @r{Object method (procedure)} ++a[2,3] = obj -> a_ @r{Object method (function)} ++x = obj_new('IDL_ @r{Class name} ++x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}} ++pro A_ @r{Class name} ++pro _ @r{Fill in @code{Class::} of first method in this file} ++!v_ @r{System variable} ++!version.t_ @r{Structure tag of system variable} ++self.g_ @r{Class structure tag in methods} ++state.w_ @r{Structure tag, if tag completion enabled} ++name = 'a_ @r{File name (default inside quotes)} ++@end example ++ ++@cindex Completion, ambiguity ++@cindex Completion, forcing function name ++The only place where completion is ambiguous is procedure/function ++@emph{keywords} versus @emph{functions}. After @samp{plot,x,_}, IDLWAVE ++will always assume a keyword to @samp{plot}. However, a function is ++also a possible completion here. You can force completion of a function ++name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}. ++ ++Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a ++regular expression to search among the commands to be completed. As ++an example, completing a blank line in this way will allow you to ++search for a procedure matching a regexp. ++ ++@cindex Scrolling the @file{*Completions*} window ++@cindex Completion, scrolling ++@cindex Completion, Online Help ++@cindex Online Help in @file{*Completions*} buffer ++If the list of completions is too long to fit in the ++@file{*Completions*} window, the window can be scrolled by pressing ++@kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each ++possible completion is available by clicking with @kbd{Mouse-3} on the ++item. Items for which system online help (from the IDL manual) is ++available will be emphasized (e.g. colored blue). For other items, the ++corresponding source code or DocLib header will be used as the help ++text. ++ ++@cindex Completion, cancelling ++@cindex Cancelling completion ++Completion is not a blocking operation --- you are free to continue ++editing, enter commands, or simply ignore the @file{*Completions*} ++buffer during a completion operation. If, however, the most recent ++command was a completion, @kbd{C-g} will remove the buffer and restore ++the window configuration. You can also remove the buffer at any time ++with no negative consequences. ++ ++@defopt idlwave-keyword-completion-adds-equal (@code{t}) ++Non-@code{nil} means completion automatically adds @samp{=} after ++completed keywords. ++@end defopt ++ ++@defopt idlwave-function-completion-adds-paren (@code{t}) ++Non-@code{nil} means completion automatically adds @samp{(} after ++completed function. A value of `2' means also add the closing ++parenthesis and position the cursor between the two. ++@end defopt ++ ++@defopt idlwave-completion-restore-window-configuration (@code{t}) ++Non-@code{nil} means restore window configuration after successful ++completion. ++@end defopt ++ ++@defopt idlwave-highlight-help-links-in-completion (@code{t}) ++Non-@code{nil} means highlight completions for which system help is ++available. ++@end defopt ++ ++@menu ++* Case of Completed Words:: CaseOFcomPletedWords ++* Object Method Completion and Class Ambiguity:: obj->Method, what? ++* Object Method Completion in the Shell:: ++* Class and Keyword Inheritance:: obj->Method, _EXTRA=e ++* Structure Tag Completion:: Completing state.Tag ++@end menu ++ ++@node Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion ++@subsection Case of Completed Words ++@cindex Case of completed words ++@cindex Mixed case completion ++IDL is a case-insensitive language, so casing is a matter of style ++only. IDLWAVE helps maintain a consistent casing style for completed ++items. The case of the completed words is determined by what is ++already in the buffer. As an exception, when the partial word being ++completed is all lower case, the completion will be lower case as ++well. If at least one character is upper case, the string will be ++completed in upper case or mixed case, depending on the value of the ++variable @code{idlwave-completion-case}. The default is to use upper ++case for procedures, functions and keywords, and mixed case for object ++class names and methods, similar to the conventions in the IDL ++manuals. For instance, to enable mixed-case completion for routines ++in addition to classes and methods, you need an entry such as ++@code{(routine . preserve)} in that variable. To enable total control ++over the case of completed items, independent of buffer context, set ++@code{idlwave-completion-force-default-case} to non-@code{nil}. ++ ++@defopt idlwave-completion-case ++Association list setting the case (UPPER/lower/Capitalized/MixedCase...) ++of completed words. ++@end defopt ++ ++@defopt idlwave-completion-force-default-case (@code{nil}) ++Non-@code{nil} means completion will always honor the settings in ++@code{idlwave-completion-case}. When nil (the default), entirely lower ++case strings will always be completed to lower case, no matter what the ++settings in @code{idlwave-completion-case}. ++@end defopt ++ ++@defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) ++Non-@code{nil} means the empty string is considered lower case for ++completion. ++@end defopt ++ ++@node Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion ++@subsection Object Method Completion and Class Ambiguity ++@cindex Object methods ++@cindex Class ambiguity ++@cindex @code{self} object, default class ++An object method is not uniquely determined without the object's class. ++Since the class is almost always omitted in the calling source (as ++required to obtain the true benefits of object-based programming), ++IDLWAVE considers all available methods in all classes as possible ++method name completions. The combined list of keywords of the current ++method in @emph{all} known classes which contain that method will be ++considered for keyword completion. In the @file{*Completions*} buffer, ++the matching classes will be shown next to each item (see option ++@code{idlwave-completion-show-classes}). As a special case, the class ++of an object called @samp{self} is always taken to be the class of the ++current routine, when in an IDLWAVE buffer. All inherits classes are ++considered as well. ++ ++@cindex Forcing class query. ++@cindex Class query, forcing ++You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u ++M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to ++narrow down the number of possible completions. The variable ++@code{idlwave-query-class} can be configured to make such prompting the ++default for all methods (not recommended), or selectively for very ++common methods for which the number of completing keywords would be too ++large (e.g. @code{Init,SetProperty,GetProperty}). ++ ++@cindex Saving object class on @code{->} ++@cindex @code{->} ++After you have specified the class for a particular statement (e.g. when ++completing the method), IDLWAVE can remember it for the rest of the ++editing session. Subsequent completions in the same statement ++(e.g. keywords) can then reuse this class information. This works by ++placing a text property on the method invocation operator @samp{->}, ++after which the operator will be shown in a different face (bold by ++default). The variable @code{idlwave-store-inquired-class} can be used ++to turn it off or on. ++ ++@defopt idlwave-completion-show-classes (@code{1}) ++Non-@code{nil} means show up to that many classes in ++@file{*Completions*} buffer when completing object methods and ++keywords. ++@end defopt ++ ++@defopt idlwave-completion-fontify-classes (@code{t}) ++Non-@code{nil} means fontify the classes in completions buffer. ++@end defopt ++ ++@defopt idlwave-query-class (@code{nil}) ++Association list governing query for object classes during completion. ++@end defopt ++ ++@defopt idlwave-store-inquired-class (@code{t}) ++Non-@code{nil} means store class of a method call as text property on ++@samp{->}. ++@end defopt ++ ++@defopt idlwave-class-arrow-face ++Face to highlight object operator arrows @samp{->} which carry a saved ++class text property. ++@end defopt ++ ++@node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion ++@subsection Object Method Completion in the Shell ++@cindex Method Completion in Shell ++In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which ++methods are being invoked have a special property: they must exist as ++variables, and so their class can be determined (for instance, using the ++@code{obj_class()} function). In the Shell, when attempting completion, ++routine info, or online help within a method routine, a query is sent to ++determine the class of the object. If this query is successful, the ++class found will be used to select appropriate completions, routine ++info, or help. If unsuccessful, information from all known classes will ++be used (as in the buffer). ++ ++@node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion ++@subsection Class and Keyword Inheritance ++@cindex Inheritance, class ++@cindex Keyword inheritance ++@cindex Inheritance, keyword ++ ++Class inheritance affects which methods are called in IDL. An object of ++a class which inherits methods from one or more superclasses can ++override that method by defining its own method of the same name, extend ++the method by calling the method(s) of its superclass(es) in its ++version, or inherit the method directly by making no modifications. ++IDLWAVE examines class definitions during completion and routine ++information display, and records all inheritance information it finds. ++This information is displayed if appropriate with the calling sequence ++for methods (@pxref{Routine Info}), as long as variable ++@code{idlwave-support-inheritance} is non-@code{nil}. ++ ++In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and ++@code{_REF_EXTRA}) is used hand-in-hand with class inheritance and ++method overriding. E.g., in a @code{SetProperty} method, this technique ++allows a single call @code{obj->SetProperty} to set properties up the ++entire class inheritance chain. This is often referred to as ++@emph{chaining}, and is characterized by chained method calls like ++@w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}. ++ ++IDLWAVE can accommodate this special synergy between class and keyword ++inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a ++method's keyword parameters, all keywords of superclass versions of ++the method being considered can be included in completion. There is ++of course no guarantee that this type of keyword chaining actually ++occurs, but for some methods it's a very convenient assumption. The ++variable @code{idlwave-keyword-class-inheritance} can be used to ++configure which methods have keyword inheritance treated in this ++simple, class-driven way. By default, only @code{Init} and ++@code{(Get|Set)Property} are. The completion buffer will label ++keywords based on their originating class. ++ ++@defopt idlwave-support-inheritance (@code{t}) ++Non-@code{nil} means consider inheritance during completion, online help etc. ++@end defopt ++ ++@defopt idlwave-keyword-class-inheritance ++A list of regular expressions to match methods for which simple ++class-driven keyword inheritance will be used for Completion. ++@end defopt ++ ++@node Structure Tag Completion, , Class and Keyword Inheritance, Completion ++@subsection Structure Tag Completion ++@cindex Completion, structure tag ++@cindex Structure tag completion ++ ++In many programs, especially those involving widgets, large structures ++(e.g. the @samp{state} structure) are used to communicate among ++routines. It is very convenient to be able to complete structure tags, ++in the same way as for instance variables (tags) of the @samp{self} ++object (@pxref{Object Method Completion and Class Ambiguity}). Add-in ++code for structure tag completion is available in the form of a loadable ++completion module: @file{idlw-complete-structtag.el}. Tag completion in ++structures is highly ambiguous (much more so than @samp{self} ++completion), so @code{idlw-complete-structtag} makes an unusual and very ++specific assumption: the exact same variable name is used to refer to ++the structure in all parts of the program. This is entirely unenforced ++by the IDL language, but is a typical convention. If you consistently ++refer to the same structure with the same variable name ++(e.g. @samp{state}), structure tags which are read from its definition ++in the same file can be used for completion. ++ ++Structure tag completion is not enabled by default. To enable it, ++simply add the following to your @file{.emacs}: ++ ++@lisp ++ (add-hook 'idlwave-load-hook ++ (lambda () (require 'idlw-complete-structtag))) ++@end lisp ++ ++Once enabled, you'll also be able to access online help on the structure ++tags, using the usual methods (@pxref{Online Help}). In addition, ++structure variables in the shell will be queried for tag names, similar ++to the way object variables in the shell are queried for method names. ++So, e.g.: ++ ++@example ++IDL> st.[Tab] ++@end example ++ ++@noindent will complete with all structure fields of the structure ++@code{st}. ++ ++@node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode ++@section Routine Source ++@cindex Routine source file ++@cindex Module source file ++@cindex Source file, of a routine ++@kindex C-c C-v ++In addition to clicking on a @i{Source:} line in the routine info ++window, there is another way to quickly visit the source file of a ++routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks ++for a module name, offering the same default as ++@code{idlwave-routine-info} would have used, taken from nearby buffer ++contents. In the minibuffer, specify a complete routine name (including ++any class part). IDLWAVE will display the source file in another ++window, positioned at the routine in question. You can also limit this ++to a routine in the current buffer only, with completion, and a ++context-sensitive default, by using a single prefix (@kbd{C-u C-c C-v}) ++or the convenience binding @kbd{C-c C-t}. ++ ++@cindex Buffers, killing ++@cindex Killing autoloaded buffers ++Since getting the source of a routine into a buffer is so easy with ++IDLWAVE, too many buffers visiting different IDL source files are ++sometimes created. The special command @kbd{C-c C-k} ++(@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove ++these buffers. ++ ++@node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode ++@section Resolving Routines ++@cindex @code{RESOLVE_ROUTINE} ++@cindex Compiling library modules ++@cindex Routines, resolving ++ ++The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve} ++and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL ++in order to resolve (compile) it. The default routine to be resolved is ++taken from context, but you get a chance to edit it. Usually this is ++not necessary, since IDL automatically discovers routines on its path. ++ ++@code{idlwave-resolve} is one way to get a library module within reach ++of IDLWAVE's routine info collecting functions. A better way is to ++keep routine information available in catalogs (@pxref{Catalogs}). ++Routine info on modules will then be available without the need to ++compile the modules first, and even without a running shell. ++ ++@xref{Sources of Routine Info}, for more information on the ways IDLWAVE ++collects data about routines, and how to update this information. ++ ++@node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode ++@section Code Templates ++@cindex Code templates ++@cindex Templates ++ ++IDLWAVE can insert IDL code templates into the buffer. For a few ++templates, this is done with direct key bindings: ++ ++@multitable @columnfractions .15 .85 ++@item @kbd{C-c C-c} ++@tab @code{CASE} statement template ++@item @kbd{C-c C-f} ++@tab @code{FOR} loop template ++@item @kbd{C-c C-r} ++@tab @code{REPEAT} loop template ++@item @kbd{C-c C-w} ++@tab @code{WHILE} loop template ++@end multitable ++ ++All code templates are also available as abbreviations ++(@pxref{Abbreviations}). ++ ++@node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode ++@section Abbreviations ++@cindex Abbreviations ++ ++Special abbreviations exist to enable rapid entry of commonly used ++commands. Emacs abbreviations are expanded by typing text into the ++buffer and pressing @key{SPC} or @key{RET}. The special abbreviations ++used to insert code templates all start with a @samp{\} (the backslash), ++or, optionally, any other character set in ++@code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are ++only expanded where they should be (i.e., not in a string or comment), ++and permits the point to be moved after an abbreviation expansion --- ++very useful for positioning the mark inside of parentheses, etc. ++ ++Special abbreviations are pre-defined for code templates and other ++useful items. To visit the full list of abbreviations, use @kbd{M-x ++idlwave-list-abbrevs}. ++ ++Template abbreviations: ++ ++@multitable @columnfractions .15 .85 ++@item @code{\pr} ++@tab @code{PROCEDURE} template ++@item @code{\fu} ++@tab @code{FUNCTION} template ++@item @code{\c} ++@tab @code{CASE} statement template ++@item @code{\f} ++@tab @code{FOR} loop template ++@item @code{\r} ++@tab @code{REPEAT} loop template ++@item @code{\w} ++@tab @code{WHILE} loop template ++@item @code{\i} ++@tab @code{IF} statement template ++@item @code{\elif} ++@tab @code{IF-ELSE} statement template ++@end multitable ++ ++String abbreviations: ++ ++@multitable @columnfractions .15 .85 ++@item @code{\ap} ++@tab @code{arg_present()} ++@item @code{\b} ++@tab @code{begin} ++@item @code{\cb} ++@tab @code{byte()} ++@item @code{\cc} ++@tab @code{complex()} ++@item @code{\cd} ++@tab @code{double()} ++@item @code{\cf} ++@tab @code{float()} ++@item @code{\cl} ++@tab @code{long()} ++@item @code{\co} ++@tab @code{common} ++@item @code{\cs} ++@tab @code{string()} ++@item @code{\cx} ++@tab @code{fix()} ++@item @code{\e} ++@tab @code{else} ++@item @code{\ec} ++@tab @code{endcase} ++@item @code{\ee} ++@tab @code{endelse} ++@item @code{\ef} ++@tab @code{endfor} ++@item @code{\ei} ++@tab @code{endif else if} ++@item @code{\el} ++@tab @code{endif else} ++@item @code{\en} ++@tab @code{endif} ++@item @code{\er} ++@tab @code{endrep} ++@item @code{\es} ++@tab @code{endswitch} ++@item @code{\ew} ++@tab @code{endwhile} ++@item @code{\g} ++@tab @code{goto,} ++@item @code{\h} ++@tab @code{help,} ++@item @code{\ik} ++@tab @code{if keyword_set() then} ++@item @code{\iap} ++@tab @code{if arg_present() then} ++@item @code{\ine} ++@tab @code{if n_elements() eq 0 then} ++@item @code{\inn} ++@tab @code{if n_elements() ne 0 then} ++@item @code{\k} ++@tab @code{keyword_set()} ++@item @code{\n} ++@tab @code{n_elements()} ++@item @code{\np} ++@tab @code{n_params()} ++@item @code{\oi} ++@tab @code{on_ioerror,} ++@item @code{\or} ++@tab @code{openr,} ++@item @code{\ou} ++@tab @code{openu,} ++@item @code{\ow} ++@tab @code{openw,} ++@item @code{\p} ++@tab @code{print,} ++@item @code{\pt} ++@tab @code{plot,} ++@item @code{\pv} ++@tab @code{ptr_valid()} ++@item @code{\re} ++@tab @code{read,} ++@item @code{\rf} ++@tab @code{readf,} ++@item @code{\rt} ++@tab @code{return} ++@item @code{\ru} ++@tab @code{readu,} ++@item @code{\s} ++@tab @code{size()} ++@item @code{\sc} ++@tab @code{strcompress()} ++@item @code{\sl} ++@tab @code{strlowcase()} ++@item @code{\sm} ++@tab @code{strmid()} ++@item @code{\sn} ++@tab @code{strlen()} ++@item @code{\sp} ++@tab @code{strpos()} ++@item @code{\sr} ++@tab @code{strtrim()} ++@item @code{\st} ++@tab @code{strput()} ++@item @code{\su} ++@tab @code{strupcase()} ++@item @code{\t} ++@tab @code{then} ++@item @code{\u} ++@tab @code{until} ++@item @code{\wc} ++@tab @code{widget_control,} ++@item @code{\wi} ++@tab @code{widget_info()} ++@item @code{\wu} ++@tab @code{writeu,} ++@end multitable ++ ++@noindent You can easily add your own abbreviations or override existing ++abbrevs with @code{define-abbrev} in your mode hook, using the ++convenience function @code{idlwave-define-abbrev}: ++ ++@lisp ++(add-hook 'idlwave-mode-hook ++ (lambda () ++ (idlwave-define-abbrev "wb" "widget_base()" ++ (idlwave-keyword-abbrev 1)) ++ (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN" ++ (idlwave-keyword-abbrev 11)))) ++@end lisp ++ ++Notice how the abbreviation (here @emph{wb}) and its expansion ++(@emph{widget_base()}) are given as arguments, and the single argument to ++@code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to ++move the point upon expansion (in this example, to put it between the ++parentheses). ++ ++The abbreviations are expanded in upper or lower case, depending upon ++the variables @code{idlwave-abbrev-change-case} and, for reserved word ++templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}). ++ ++@defopt idlwave-abbrev-start-char (@code{"\"}) ++A single character string used to start abbreviations in abbrev mode. ++Beware of common characters which might naturally occur in sequence with ++abbreviation strings. ++@end defopt ++ ++@defopt idlwave-abbrev-move (@code{t}) ++Non-@code{nil} means the abbrev hook can move point, e.g. to end up ++between the parentheses of a function call. ++@end defopt ++ ++@node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode ++@section Actions ++@cindex Actions ++@cindex Coding standards, enforcing ++ ++@emph{Actions} are special formatting commands which are executed ++automatically while you write code in order to check the structure of ++the program or to enforce coding standards. Most actions which have ++been implemented in IDLWAVE are turned off by default, assuming that the ++average user wants her code the way she writes it. But if you are a ++lazy typist and want your code to adhere to certain standards, actions ++can be helpful. ++ ++Actions can be applied in three ways: ++ ++@itemize @bullet ++@item ++Some actions are applied directly while typing. For example, pressing ++@samp{=} can run a check to make sure that this operator is surrounded ++by spaces and insert these spaces if necessary. Pressing @key{SPC} ++after a reserved word can call a command to change the word to upper ++case. ++@item ++When a line is re-indented with @key{TAB}, actions can be applied to the ++entire line. To enable this, the variable @code{idlwave-do-actions} ++must be non-@code{nil}. ++@item ++@cindex Foreign code, adapting ++@cindex Actions, applied to foreign code ++Actions can also be applied to a larger piece of code, e.g. to convert ++foreign code to your own style. To do this, mark the relevant part of ++the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking ++commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current ++subprogram). @xref{Code Indentation}, for information how to adjust the ++indentation of the code. ++@end itemize ++ ++@defopt idlwave-do-actions (@code{nil}) ++Non-@code{nil} means performs actions when indenting. Individual action ++settings are described below and set separately. ++@end defopt ++ ++@menu ++* Block Boundary Check:: Is the END statement correct? ++* Padding Operators:: Enforcing space around `=' etc ++* Case Changes:: Enforcing upper case keywords ++@end menu ++ ++@node Block Boundary Check, Padding Operators, Actions, Actions ++@subsection Block Boundary Check ++@cindex Block boundary check ++@cindex @code{END} type checking ++@cindex @code{END}, automatic insertion ++@cindex @code{END}, expanding ++@cindex Block, closing ++@cindex Closing a block ++ ++Whenever you type an @code{END} statement, IDLWAVE finds the ++corresponding start of the block and the cursor blinks back to that ++location for a second. If you have typed a specific @code{END}, like ++@code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator ++does not match the type of block it terminates. ++ ++Set the variable @code{idlwave-expand-generic-end} in order to have all ++generic @code{END} statements automatically expanded to the appropriate ++type. You can also type @kbd{C-c ]} to close the current block by ++inserting the appropriate @code{END} statement. ++ ++@defopt idlwave-show-block (@code{t}) ++Non-@code{nil} means point blinks to block beginning for ++@code{idlwave-show-begin}. ++@end defopt ++ ++@defopt idlwave-expand-generic-end (@code{t}) ++Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc. ++@end defopt ++ ++@defopt idlwave-reindent-end (@code{t}) ++Non-@code{nil} means re-indent line after END was typed. ++@end defopt ++ ++@node Padding Operators, Case Changes, Block Boundary Check, Actions ++@subsection Padding Operators ++@cindex Padding operators with spaces ++@cindex Operators, padding with spaces ++@cindex Space, around operators ++ ++Some operators can be automatically surrounded by spaces. This can ++happen when the operator is typed, or later when the line is indented. ++IDLWAVE can pad the operators @samp{<}, @samp{>}, @samp{,}, @samp{=}, ++and @samp{->}, as well as the modified assignment operators ++(@samp{AND=}, @samp{OR=}, etc.). This feature is turned off by default. ++If you want to turn it on, customize the variables ++@code{idlwave-surround-by-blank} and @code{idlwave-do-actions} and turn ++both on. You can also define similar actions for other operators by ++using the function @code{idlwave-action-and-binding} in the mode hook. ++For example, to enforce space padding of the @samp{+} and @samp{*} ++operators (outside of strings and comments, of course), try this in ++@file{.emacs} ++ ++@lisp ++(add-hook 'idlwave-mode-hook ++ (lambda () ++ (setq idlwave-surround-by-blank t) ; Turn this type of actions on ++ (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) ++ (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) ++@end lisp ++ ++Note that the modified assignment operators which begin with a word ++(@samp{AND=}, @samp{OR=}, @samp{NOT=}, etc.) require a leading space to ++be recognized (e.g @code{vAND=4} would be interpreted as a variable ++@code{vAND}). Also note that, since e.g., @code{>} and @code{>=} are ++both valid operators, it is impossible to surround both by blanks while ++they are being typed. Similarly with @code{&} and @code{&&}. For ++these, a compromise is made: the padding is placed on the left, and if ++the longer operator is keyed in, on the right as well (otherwise you ++must insert spaces to pad right yourself, or press simply press Tab to ++repad everything if @code{idlwave-do-actions} is on). ++ ++@defopt idlwave-surround-by-blank (@code{nil}) ++Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil}, ++@samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->}, and the ++modified assignment operators (@samp{AND=}, @samp{OR=}, etc.) are ++surrounded with spaces by @code{idlwave-surround}. ++@end defopt ++ ++@defopt idlwave-pad-keyword (@code{t}) ++Non-@code{nil} means space-pad the @samp{=} in keyword assignments. ++@end defopt ++ ++@node Case Changes, , Padding Operators, Actions ++@subsection Case Changes ++@cindex Case changes ++@cindex Upcase, enforcing for reserved words ++@cindex Downcase, enforcing for reserved words ++ ++Actions can be used to change the case of reserved words or expanded ++abbreviations by customizing the variables ++@code{idlwave-abbrev-change-case} and ++@code{idlwave-reserved-word-upcase}. If you want to change the case of ++additional words automatically, put something like the following into ++your @file{.emacs} file: ++ ++@lisp ++(add-hook 'idlwave-mode-hook ++ (lambda () ++ ;; Capitalize system vars ++ (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t) ++ ;; Capitalize procedure name ++ (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" ++ '(capitalize-word 1) t) ++ ;; Capitalize common block name ++ (idlwave-action-and-binding "\\[ \t]+\\<" ++ '(capitalize-word 1) t))) ++@end lisp ++ ++For more information, see the documentation string for the function ++@code{idlwave-action-and-binding}. For information on controlling the ++case of routines, keywords, classes, and methods as they are completed, see ++@ref{Completion}. ++ ++@defopt idlwave-abbrev-change-case (@code{nil}) ++Non-@code{nil} means all abbrevs will be forced to either upper or lower ++case. Valid values are @code{nil}, @code{t}, and @code{down}. ++@end defopt ++ ++@defopt idlwave-reserved-word-upcase (@code{nil}) ++Non-@code{nil} means reserved words will be made upper case via abbrev ++expansion. ++@end defopt ++ ++ ++@node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode ++@section Documentation Header ++@cindex Documentation header ++@cindex DocLib header ++@cindex Modification timestamp ++@cindex Header, for file documentation ++@cindex Timestamp, in doc header. ++@cindex Changelog, in doc header. ++ ++@kindex C-c C-h ++@kindex C-c C-m ++The command @kbd{C-c C-h} inserts a standard routine header into the ++buffer, with the usual fields for documentation (a different header can ++be specified with @code{idlwave-file-header}). One of the keywords is ++@samp{MODIFICATION HISTORY} under which the changes to a routine can be ++recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION ++HISTORY} of the current routine or file and inserts the user name with a ++timestamp. ++ ++@defopt idlwave-file-header ++The doc-header template or a path to a file containing it. ++@end defopt ++ ++@defopt idlwave-header-to-beginning-of-file (@code{nil}) ++Non-@code{nil} means the documentation header will always be at start ++of file. ++@end defopt ++ ++@defopt idlwave-timestamp-hook ++The hook function used to update the timestamp of a function. ++@end defopt ++ ++@defopt idlwave-doc-modifications-keyword ++The modifications keyword to use with the log documentation commands. ++@end defopt ++ ++@defopt idlwave-doclib-start ++Regexp matching the start of a document library header. ++@end defopt ++ ++@defopt idlwave-doclib-end ++Regexp matching the start of a document library header. ++@end defopt ++ ++@node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode ++@section Motion Commands ++@cindex Motion commands ++@cindex Program structure, moving through ++@cindex Code structure, moving through ++@cindex @file{Func-menu}, XEmacs package ++@cindex @file{Imenu}, Emacs package ++@cindex Function definitions, jumping to ++@cindex Procedure definitions, jumping to ++ ++IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages ++which make it easy to jump to the definitions of functions and ++procedures in the current file with a pop-up selection. To bind ++@file{Imenu} to a mouse-press, use in your @file{.emacs}: ++ ++@lisp ++(define-key global-map [S-down-mouse-3] 'imenu) ++@end lisp ++ ++@cindex @file{Speedbar}, Emacs package ++ ++In addition, @file{Speedbar} support allows convenient navigation of a ++source tree of IDL routine files, quickly stepping to routine ++definitions. See @code{Tools->Display Speedbar}. ++ ++Several commands allow you to move quickly through the structure of an ++IDL program: ++ ++@multitable @columnfractions .15 .85 ++@item @kbd{C-M-a} ++@tab Beginning of subprogram ++@item @kbd{C-M-e} ++@tab End of subprogram ++@item @kbd{C-c @{} ++@tab Beginning of block (stay inside the block) ++@item @kbd{C-c @}} ++@tab End of block (stay inside the block) ++@item @kbd{C-M-n} ++@tab Forward block (on same level) ++@item @kbd{C-M-p} ++@tab Backward block (on same level) ++@item @kbd{C-M-d} ++@tab Down block (enters a block) ++@item @kbd{C-M-u} ++@tab Backward up block (leaves a block) ++@item @kbd{C-c C-n} ++@tab Next Statement ++@end multitable ++ ++ ++@node Misc Options, , Motion Commands, The IDLWAVE Major Mode ++@section Miscellaneous Options ++@cindex Hooks ++ ++@defopt idlwave-help-application ++The external application providing reference help for programming. ++@end defopt ++ ++@defopt idlwave-startup-message (@code{t}) ++Non-@code{nil} means display a startup message when @code{idlwave-mode}' ++is first called. ++@end defopt ++ ++@defopt idlwave-mode-hook ++Normal hook. Executed when a buffer is put into @code{idlwave-mode}. ++@end defopt ++ ++@defopt idlwave-load-hook ++Normal hook. Executed when @file{idlwave.el} is loaded. ++@end defopt ++ ++@node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top ++@chapter The IDLWAVE Shell ++@cindex IDLWAVE shell ++@cindex Major mode, @code{idlwave-shell-mode} ++@cindex IDL, as Emacs subprocess ++@cindex Subprocess of Emacs, IDL ++@cindex Comint, Emacs package ++@cindex Windows ++@cindex MacOS ++ ++The IDLWAVE shell is an Emacs major mode which permits running the IDL ++program as an inferior process of Emacs, and works closely with the ++IDLWAVE major mode in buffers. It can be used to work with IDL ++interactively, to compile and run IDL programs in Emacs buffers and to ++debug these programs. The IDLWAVE shell is built on @file{comint}, an ++Emacs packages which handles the communication with the IDL program. ++Unfortunately, IDL for Windows does not have command-prompt versions and ++thus do not allow the interaction with Emacs --- so the IDLWAVE shell ++currently only works under Unix and MacOSX. ++ ++@menu ++* Starting the Shell:: How to launch IDL as a subprocess ++* Using the Shell:: Interactively working with the Shell ++* Commands Sent to the Shell:: ++* Debugging IDL Programs:: ++* Examining Variables:: ++* Custom Expression Examination:: ++@end menu ++ ++@node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell ++@section Starting the Shell ++@cindex Starting the shell ++@cindex Shell, starting ++@cindex Dedicated frame, for shell buffer ++@cindex Frame, for shell buffer ++@cindex Subprocess of Emacs, IDL ++ ++@kindex C-c C-s ++The IDLWAVE shell can be started with the command @kbd{M-x ++idlwave-shell}. In @code{idlwave-mode} the function is bound to ++@kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to ++interact with the shell. If the shell is already running, @kbd{C-c ++C-s} will simply switch to the shell buffer. The command @kbd{C-c ++C-l} (@code{idlwave-shell-recenter-shell-window}) displays the shell ++window without selecting it. The shell can also be started ++automatically when another command tries to send a command to it. To ++enable auto start, set the variable ++@code{idlwave-shell-automatic-start} to @code{t}. ++ ++In order to create a separate frame for the IDLWAVE shell buffer, call ++@code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or ++@kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell ++window, configure the variable ++@code{idlwave-shell-use-dedicated-frame}. ++ ++To launch a quick IDLWAVE shell directly from a shell prompt without ++an IDLWAVE buffer (e.g., as a replacement for running inside an ++xterm), define a system alias with the following content: ++ ++@example ++emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" ++@end example ++ ++Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer ++the Emacs process to run directly inside the terminal window. ++ ++@cindex ENVI ++@cindex IDL> Prompt ++ ++To use IDLWAVE with ENVI or other custom packages which change the ++@samp{IDL> } prompt, you must change the ++@code{idlwave-shell-prompt-pattern}, which defaults to @samp{"^ ?IDL> ++"}. Normally, you can just replace the @samp{IDL} in this expression ++with the prompt you see. A suitable pattern which matches the prompt ++for both ENVI and IDL simultaneously is @samp{"^ ?\\(ENVI\\|IDL\\)> "}. ++ ++@defopt idlwave-shell-explicit-file-name (@file{idl}) ++This is the command to run IDL. ++@end defopt ++ ++@defopt idlwave-shell-command-line-options ++A list of command line options for calling the IDL program. ++@end defopt ++ ++@defopt idlwave-shell-prompt-pattern ++Regexp to match IDL prompt at beginning of a line. ++@end defopt ++ ++@defopt idlwave-shell-process-name ++Name to be associated with the IDL process. ++@end defopt ++ ++@defopt idlwave-shell-automatic-start (@code{nil}) ++Non-@code{nil} means attempt to invoke idlwave-shell if not already ++running. ++@end defopt ++ ++@defopt idlwave-shell-initial-commands ++Initial commands, separated by newlines, to send to IDL. ++@end defopt ++ ++@defopt idlwave-shell-save-command-history (@code{t}) ++Non-@code{nil} means preserve command history between sessions. ++@end defopt ++ ++@defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist}) ++The file in which the command history of the idlwave shell is saved. ++Unless it's an absolute path, it goes in ++@code{idlwave-config-directory}. ++@end defopt ++ ++@defopt idlwave-shell-use-dedicated-frame (@code{nil}) ++Non-@code{nil} means IDLWAVE should use a special frame to display the ++shell buffer. ++@end defopt ++ ++@defopt idlwave-shell-use-dedicated-window (@code{nil}) ++Non-@code{nil} means use a dedicated window for the shell, taking care ++not it replace it with other buffers. ++@end defopt ++ ++@defopt idlwave-shell-frame-parameters ++The frame parameters for a dedicated idlwave-shell frame. ++@end defopt ++ ++@defopt idlwave-shell-raise-frame (@code{t}) ++Non-@code{nil} means `idlwave-shell' raises the frame showing the shell ++window. ++@end defopt ++ ++@defopt idlwave-shell-temp-pro-prefix ++The prefix for temporary IDL files used when compiling regions. ++@end defopt ++ ++@cindex Hooks ++@defopt idlwave-shell-mode-hook ++Hook for customizing @code{idlwave-shell-mode}. ++@end defopt ++ ++@node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell ++@section Using the Shell ++@cindex Comint ++@cindex Shell, basic commands ++ ++The IDLWAVE shell works in the same fashion as other shell modes in ++Emacs. It provides command history, command line editing and job ++control. The @key{UP} and @key{DOWN} arrows cycle through the input ++history just like in an X terminal@footnote{This is different from ++normal Emacs/Comint behavior, but more like an xterm. If you prefer the ++default comint functionality, check the variable ++@code{idlwave-shell-arrows-do-history}.}. The history is preserved ++between emacs and IDL sessions. Here is a list of commonly used ++commands: ++ ++@multitable @columnfractions .12 .88 ++@item @key{UP}, @key{M-p} ++@tab Cycle backwards in input history ++@item @key{DOWN}, @key{M-n} ++@tab Cycle forwards in input history ++@item @kbd{M-r} ++@tab Previous input matching a regexp ++@item @kbd{M-s} ++@tab Next input matching a regexp ++@item @kbd{return} ++@tab Send input or copy line to current prompt ++@item @kbd{C-c C-a} ++@tab Beginning of line; skip prompt ++@item @kbd{C-c C-u} ++@tab Kill input to beginning of line ++@item @kbd{C-c C-w} ++@tab Kill word before cursor ++@item @kbd{C-c C-c} ++@tab Send ^C ++@item @kbd{C-c C-z} ++@tab Send ^Z ++@item @kbd{C-c C-\} ++@tab Send ^\ ++@item @kbd{C-c C-o} ++@tab Delete last batch of process output ++@item @kbd{C-c C-r} ++@tab Show last batch of process output ++@item @kbd{C-c C-l} ++@tab List input history ++@end multitable ++ ++In addition to these standard @file{comint} commands, ++@code{idlwave-shell-mode} provides many of the same commands which ++simplify writing IDL code available in IDLWAVE buffers. This includes ++abbreviations, online help, and completion. See @ref{Routine Info} and ++@ref{Online Help} and @ref{Completion} for more information on these ++commands. ++ ++@cindex Completion, in the shell ++@cindex Routine info, in the shell ++@cindex Online Help, in the shell ++@multitable @columnfractions .12 .88 ++@item @kbd{@key{TAB}} ++@tab Completion of file names (between quotes and after executive ++commands @samp{.run} and @samp{.compile}), routine names, class names, ++keywords, system variables, system variable tags etc. ++(@code{idlwave-shell-complete}). ++@item @kbd{M-@key{TAB}} ++@tab Same as @key{TAB} ++@item @kbd{C-c ?} ++@tab Routine Info display (@code{idlwave-routine-info}) ++@item @kbd{M-?} ++@tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp}) ++@item @kbd{C-c C-i} ++@tab Update routine info from buffers and shell ++(@code{idlwave-update-routine-info}) ++@item @kbd{C-c C-v} ++@tab Find the source file of a routine (@code{idlwave-find-module}) ++@item @kbd{C-c C-t} ++@tab Find the source file of a routine in the currently visited file ++(@code{idlwave-find-module-this-file}). ++@item @kbd{C-c =} ++@tab Compile a library routine (@code{idlwave-resolve}) ++@end multitable ++ ++@defopt idlwave-shell-arrows-do-history (@code{t}) ++Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command ++history like xterm. ++@end defopt ++ ++@defopt idlwave-shell-comint-settings ++Alist of special settings for the comint variables in the IDLWAVE Shell. ++@end defopt ++ ++@defopt idlwave-shell-file-name-chars ++The characters allowed in file names, as a string. Used for file name ++completion. ++@end defopt ++ ++@defopt idlwave-shell-graphics-window-size ++Size of IDL graphics windows popped up by special IDLWAVE command. ++@end defopt ++ ++@cindex Input mode ++@cindex Character input mode (Shell) ++@cindex Line input mode (Shell) ++@cindex Magic spells, for input mode ++@cindex Spells, magic ++IDLWAVE works in line input mode: You compose a full command line, using ++all the power Emacs gives you to do this. When you press @key{RET}, the ++whole line is sent to IDL. Sometimes it is necessary to send single ++characters (without a newline), for example when an IDL program is ++waiting for single character input with the @code{GET_KBRD} function. ++You can send a single character to IDL with the command @kbd{C-c C-x} ++(@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y} ++(@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop ++which accepts characters and immediately sends them to IDL. The loop ++can be exited with @kbd{C-g}. It terminates also automatically when the ++current IDL command is finished. Check the documentation of the two ++variables described below for a way to make IDL programs trigger ++automatic switches of the input mode. ++ ++@defopt idlwave-shell-use-input-mode-magic (@code{nil}) ++Non-@code{nil} means IDLWAVE should check for input mode spells in ++output. ++@end defopt ++ ++@defopt idlwave-shell-input-mode-spells ++The three regular expressions which match the magic spells for input ++modes. ++@end defopt ++ ++@node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell ++@section Commands Sent to the Shell ++@cindex Commands in shell, showing ++@cindex Showing commands in shell ++ ++The IDLWAVE buffers and shell interact very closely. In addition to the ++normal commands you enter at the @code{IDL>} prompt, many other special ++commands are sent to the shell, sometimes as a direct result of invoking ++a key command, menu item, or toolbar button, but also automatically, as ++part of the normal flow of information updates between the buffer and ++shell. ++ ++The commands sent include @code{breakpoint}, @code{.step} and other ++debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other ++compilation statements (@pxref{Compiling Programs}), examination ++commands like @code{print} and @code{help} (@pxref{Examining ++Variables}), and other special purpose commands designed to keep ++information on the running shell current. ++ ++By default, much of this background shell input and output is hidden ++from the user, but this is configurable. The custom variable ++@code{idlwave-abbrev-show-commands} allows you to configure which ++commands sent to the shell are shown there. For a related customization ++for separating the output of @emph{examine} commands, see @ref{Examining ++Variables}. ++ ++@defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)}) ++A list of command types to echo in the shell when sent. Possible values ++are @code{run} for @code{.run}, @code{.compile} and other run commands, ++@code{misc} for lesser used commands like @code{window}, ++@code{retall},@code{close}, etc., @code{breakpoint} for breakpoint ++setting and clearing commands, and @code{debug} for other debug, ++stepping, and continue commands. In addition, if the variable is set to ++the single symbol @code{'everything}, all the copious shell input is ++displayed (which is probably only useful for debugging purposes). ++N.B. For hidden commands which produce output by side-effect, that ++output remains hidden (e.g., stepping through a @code{print} command). ++As a special case, any error message in the output will be displayed ++(e.g., stepping to an error). ++@end defopt ++ ++@node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell ++@section Debugging IDL Programs ++@cindex Debugging ++@cindex Keybindings for debugging ++@cindex Toolbar ++ ++Programs can be compiled, run, and debugged directly from the source ++buffer in Emacs, walking through arbitrarily deeply nested code, ++printing expressions and skipping up and down the calling stack along ++the way. IDLWAVE makes compiling and debugging IDL programs far less ++cumbersome by providing a full-featured, key/menu/toolbar-driven ++interface to commands like @code{breakpoint}, @code{.step}, ++@code{.run}, etc. It can even perform complex debug operations not ++natively supported by IDL (like continuing to the line at the cursor). ++ ++The IDLWAVE shell installs key bindings both in the shell buffer and ++in all IDL code buffers of the current Emacs session, so debug ++commands work in both places (in the shell, commands operate on the ++last file compiled). On Emacs versions which support it, a debugging ++toolbar is also installed. The toolbar display can be toggled with ++@kbd{C-c C-d C-t} (@code{idlwave-shell-toggle-toolbar}). ++ ++ ++@defopt idlwave-shell-use-toolbar (@code{t}) ++Non-@code{nil} means use the debugging toolbar in all IDL related ++buffers. ++@end defopt ++ ++@menu ++* A Tale of Two Modes:: ++* Debug Key Bindings:: ++* Breakpoints and Stepping:: ++* Compiling Programs:: ++* Walking the Calling Stack:: ++* Electric Debug Mode:: ++@end menu ++ ++ ++@node A Tale of Two Modes, Debug Key Bindings, Debugging IDL Programs, Debugging IDL Programs ++@subsection A Tale of Two Modes ++@cindex Electric Debug Mode ++@cindex Debugging Interface ++ ++The many debugging, compiling, and examination commands provided in ++IDLWAVE are available simultaneously through two different interfaces: ++the original, multi-key command interface, and the new Electric Debug ++Mode. The functionality they offer is similar, but the way you interact ++with them is quite different. The main difference is that, in Electric ++Debug Mode, the source buffers are made read-only, and single ++key-strokes are used to step through, examine expressions, set and ++remove breakpoints, etc. The same variables, prefix arguments, and ++settings apply to both versions, and both can be used interchangeably. ++By default, when breakpoints are hit, Electric Debug Mode is enabled. ++The traditional interface is described first. @xref{Electric Debug ++Mode}, for more on that mode. Note that electric debug mode can be ++prevented from activating automatically by customizing the variable ++@code{idlwave-shell-automatic-electric-debug}. ++ ++@node Debug Key Bindings, Breakpoints and Stepping, A Tale of Two Modes, Debugging IDL Programs ++@subsection Debug Key Bindings ++@kindex C-c C-d ++@cindex Key bindings ++ ++The standard debugging key bindings are always available by default on ++the prefix key @kbd{C-c C-d}, so, for example, setting a breakpoint is ++done with @kbd{C-c C-d C-b}, and compiling a source file with @kbd{C-c ++C-d C-c}. You can also easily configure IDLWAVE to use one or more ++modifier keys not in use by other commands, in lieu of the prefix ++@kbd{C-c C-d} (though these bindings will typically also be available ++--- see @code{idlwave-shell-activate-prefix-keybindings}). For ++example, if you include in @file{.emacs}: ++ ++@lisp ++(setq idlwave-shell-debug-modifiers '(control shift)) ++@end lisp ++ ++@noindent a breakpoint can then be set by pressing @kbd{b} while holding down ++@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a ++source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}, ++etc. In the remainder of this chapter we will assume that the ++@kbd{C-c C-d} bindings are active, but each of these bindings will ++have an equivalent shortcut if modifiers are given in the ++@code{idlwave-shell-debug-modifiers} variable (@pxref{Lesson II -- ++Customization}). A much simpler and faster form of debugging for ++running code is also available by default --- see @ref{Electric Debug ++Mode}. ++ ++@defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) ++The prefix key for the debugging map ++@code{idlwave-shell-mode-prefix-map}. ++@end defopt ++ ++@defopt idlwave-shell-activate-prefix-keybindings (@code{t}) ++Non-@code{nil} means debug commands will be bound to the prefix ++key, like @kbd{C-c C-d C-b}. ++@end defopt ++ ++@defopt idlwave-shell-debug-modifiers (@code{nil}) ++List of modifier keys to use for additional, alternative binding of ++debugging commands in the shell and source buffers. Can be one or ++more of @code{control}, @code{meta}, @code{super}, @code{hyper}, ++@code{alt}, and @code{shift}. ++@end defopt ++ ++@node Breakpoints and Stepping, Compiling Programs, Debug Key Bindings, Debugging IDL Programs ++@subsection Breakpoints and Stepping ++@cindex Breakpoints ++@cindex Stepping ++@cindex Execution, controlled ++ ++@kindex C-c C-d C-b ++@kindex C-c C-d C-b ++IDLWAVE helps you set breakpoints and step through code. Setting a ++breakpoint in the current line of the source buffer is accomplished ++with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a ++prefix arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a ++@code{/ONCE} keyword, meaning that it will be deleted after first use. ++With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), ++the breakpoint will only be active the @code{nth} time it is hit. ++With a single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt ++for a condition --- an IDL expression to be evaluated and trigger the ++breakpoint only if true. To clear the breakpoint in the current line, ++use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When ++executed from the shell window, the breakpoint where IDL is currently ++stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d ++C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled ++and re-enabled: @kbd{C-c C-d C-\} ++(@code{idlwave-shell-toggle-enable-current-bp}). ++ ++Breakpoint lines are highlighted or indicated with an icon in the source ++code (different icons for conditional, after, and other break types). ++Disabled breakpoints are @emph{grayed out} by default. Note that IDL ++places breakpoints as close as possible on or after the line you ++specify. IDLWAVE queries the shell for the actual breakpoint location ++which was set, so the exact line you specify may not be marked. You can ++re-sync the breakpoint list and update the display at any time (e.g., if ++you add or remove some on the command line) using @kbd{C-c C-d C-l}. ++ ++In recent IDLWAVE versions, the breakpoint line is highlighted when the ++mouse is moved over it, and a tooltip pops up describing the break ++details. @kbd{Mouse-3} on the breakpoint line pops up a menu of ++breakpoint actions, including clearing, disabling, and adding or ++changing break conditions or ``after'' break count. ++ ++Once the program has stopped somewhere, you can step through it. The ++most important stepping commands are @kbd{C-c C-d C-s} to execute one ++line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line, ++treating procedure and function calls as a single step ("step over"); ++@kbd{C-c C-d C-h} to continue execution to the line at the cursor and ++@kbd{C-c C-d C-r} to continue execution. @xref{Commands Sent to the ++Shell}, for information on displaying or hiding the breakpoint and ++stepping commands the shell receives. Here is a summary of the ++breakpoint and stepping commands: ++ ++@multitable @columnfractions .23 .77 ++@item @kbd{C-c C-d C-b} ++@tab Set breakpoint (@code{idlwave-shell-break-here}) ++@item @kbd{C-c C-d C-i} ++@tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) ++@item @kbd{C-c C-d C-d} ++@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) ++@item @kbd{C-c C-d C-a} ++@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) ++@item @kbd{C-c C-d [} ++@tab Go to the previous breakpoint (@code{idlwave-shell-goto-previous-bp}) ++@item @kbd{C-c C-d ]} ++@tab Go to the next breakpoint (@code{idlwave-shell-goto-next-bp}) ++@item @kbd{C-c C-d C-\} ++@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) ++@item @kbd{C-c C-d C-j} ++@tab Set a breakpoint at the beginning of the enclosing routine. ++@item @kbd{C-c C-d C-s} ++@tab Step, into function calls (@code{idlwave-shell-step}) ++@item @kbd{C-c C-d C-n} ++@tab Step, over function calls (@code{idlwave-shell-stepover}) ++@item @kbd{C-c C-d C-k} ++@tab Skip one statement (@code{idlwave-shell-skip}) ++@item @kbd{C-c C-d C-u} ++@tab Continue to end of block (@code{idlwave-shell-up}) ++@item @kbd{C-c C-d C-m} ++@tab Continue to end of function (@code{idlwave-shell-return}) ++@item @kbd{C-c C-d C-o} ++@tab Continue past end of function (@code{idlwave-shell-out}) ++@item @kbd{C-c C-d C-h} ++@tab Continue to line at cursor position (@code{idlwave-shell-to-here}) ++@item @kbd{C-c C-d C-r} ++@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) ++@item @kbd{C-c C-d C-up} ++@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) ++@item @kbd{C-c C-d C-down} ++@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) ++@end multitable ++ ++All of these commands have equivalents in Electric Debug Mode, which ++provides faster single-key access (@pxref{Electric Debug Mode}). ++ ++The line where IDL is currently stopped, at breakpoints, halts, and ++errors, etc., is marked with a color overlay or arrow, depending on the ++setting in @code{idlwave-shell-mark-stop-line}. If an overlay face is ++used to mark the stop line (as it is by default), when stepping through ++code, the face color is temporarily changed to gray, until IDL completes ++the next command and moves to the new line. ++ ++@defopt idlwave-shell-mark-breakpoints (@code{t}) ++Non-@code{nil} means mark breakpoints in the source file buffers. The ++value indicates the preferred method. Valid values are @code{nil}, ++@code{t}, @code{face}, and @code{glyph}. ++@end defopt ++ ++@defopt idlwave-shell-breakpoint-face ++The face for breakpoint lines in the source code if ++@code{idlwave-shell-mark-breakpoints} has the value @code{face}. ++@end defopt ++ ++@defopt idlwave-shell-breakpoint-popup-menu (@code{t}) ++Whether to pop-up a menu and present a tooltip description on ++breakpoint lines. ++@end defopt ++ ++@defopt idlwave-shell-mark-stop-line (@code{t}) ++Non-@code{nil} means mark the source code line where IDL is currently ++stopped. The value specifies the preferred method. Valid values are ++@code{nil}, @code{t}, @code{arrow}, and @code{face}. ++@end defopt ++ ++@defopt idlwave-shell-overlay-arrow (@code{">"}) ++The overlay arrow to display at source lines where execution halts, if ++configured in @code{idlwave-shell-mark-stop-line}. ++@end defopt ++ ++@defopt idlwave-shell-stop-line-face ++The face which highlights the source line where IDL is stopped, if ++configured in @code{idlwave-shell-mark-stop-line}. ++@end defopt ++ ++ ++@node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs ++@subsection Compiling Programs ++@cindex Compiling programs ++@cindex Programs, compiling ++@cindex Default command line, executing ++@cindex Executing a default command line ++ ++@kindex C-c C-d C-c ++In order to compile the current buffer under the IDLWAVE shell, press ++@kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the ++current buffer and then sends the command @samp{.run path/to/file} to the ++shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in ++which case the most recently compiled buffer will be saved and ++re-compiled. ++ ++When developing or debugging a program, it is often necessary to execute ++the same command line many times. A convenient way to do this is ++@kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}). ++This command first resets IDL from a state of interrupted execution by ++closing all files and returning to the main interpreter level. Then a ++default command line is send to the shell. To edit the default command ++line, call @code{idlwave-shell-execute-default-command-line} with a ++prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has ++been set (or you give two prefix arguments), the last command on the ++@code{comint} input history is sent. ++ ++@kindex C-c C-d C-e ++@cindex Compiling regions ++For quickly compiling and running the currently marked region as a main ++level program @kbd{C-c C-d C-e} (@code{idlwave-shell-run-region}) is ++very useful. A temporary file is created holding the contents of the ++current region (with @code{END} appended), and run from the shell. ++ ++@node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs ++@subsection Walking the Calling Stack ++@cindex Calling stack, walking ++ ++While debugging a program, it can be very useful to check the context in ++which the current routine was called, for instance to help understand ++the value of the arguments passed. To do so conveniently you need to ++examine the calling stack. If execution is stopped somewhere deep in a ++program, you can use the commands @kbd{C-c C-d C-@key{UP}} ++(@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}} ++(@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons, ++to move up or down through the calling stack. The mode line of the ++shell window will indicate the position within the stack with a label ++like @samp{[-3:MYPRO]}. The line of IDL code at that stack position ++will be highlighted. If you continue execution, IDLWAVE will ++automatically return to the current level. @xref{Examining Variables}, ++for information how to examine the value of variables and expressions on ++higher calling stack levels. ++ ++@html ++ ++@end html ++@node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs ++@subsection Electric Debug Mode ++@cindex Electric Debug Mode ++@cindex @samp{*Debugging*} ++ ++Even with a convenient debug key prefix enabled, repetitive stepping, ++variable examination (@pxref{Examining Variables}), and other debugging ++activities can be awkward and slow using commands which require multiple ++keystrokes. Luckily, there's a better way, inspired by the lisp e-debug ++mode, and available through the @emph{Electric Debug Mode}. By default, ++as soon as a breakpoint is hit, this minor mode is enabled. The buffer ++showing the line where execution has halted is switched to Electric ++Debug Mode. This mode is visible as @samp{*Debugging*} in the mode ++line, and a different face (violet by default, if color is available) ++for the line stopped at point. The buffer is made read-only and ++single-character bindings for the most commonly used debugging commands ++are enabled. These character commands (a list of which is available ++with @kbd{C-?}) are: ++ ++@multitable @columnfractions .2 .8 ++@item @kbd{a} ++@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) ++@item @kbd{b} ++@tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here}) ++@item @kbd{d} ++@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) ++@item @kbd{e} ++@tab Prompt for expression to print (@code{idlwave-shell-clear-current-bp}). ++@item @kbd{h} ++@tab Continue to the line at cursor position (@code{idlwave-shell-to-here}) ++@item @kbd{i} ++@tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) ++@item @kbd{[} ++@tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp}) ++@item @kbd{]} ++@tab Go to the next breakpoint in the file ++(@code{idlwave-shell-goto-next-bp}) ++@item @kbd{\} ++@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) ++@item @kbd{j} ++@tab Set breakpoint at beginning of enclosing routine (@code{idlwave-shell-break-this-module}) ++@item @kbd{k} ++@tab Skip one statement (@code{idlwave-shell-skip}) ++@item @kbd{m} ++@tab Continue to end of function (@code{idlwave-shell-return}) ++@item @kbd{n} ++@tab Step, over function calls (@code{idlwave-shell-stepover}) ++@item @kbd{o} ++@tab Continue past end of function (@code{idlwave-shell-out}) ++@item @kbd{p} ++@tab Print expression near point or in region with @kbd{C-u p} (@code{idlwave-shell-print}) ++@item @kbd{q} ++@tab End the debugging session and return to the Shell's main level ++(@code{idlwave-shell-retall}) ++@item @kbd{r} ++@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) ++@item @kbd{s} or @kbd{@key{SPACE}} ++@tab Step, into function calls (@code{idlwave-shell-step}) ++@item @kbd{t} ++@tab Print a calling-level traceback in the shell ++@item @kbd{u} ++@tab Continue to end of block (@code{idlwave-shell-up}) ++@item @kbd{v} ++@tab Turn Electric Debug Mode off ++(@code{idlwave-shell-electric-debug-mode}) ++@item @kbd{x} ++@tab Examine expression near point (or in region with @kbd{C-u x}) ++with shortcut of examine type. ++@item @kbd{z} ++@tab Reset IDL (@code{idlwave-shell-reset}) ++@item @kbd{+} or @kbd{=} ++@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) ++@item @kbd{-} or @kbd{_} ++@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) ++@item @kbd{?} ++@tab Help on expression near point or in region with @kbd{C-u ?} ++(@code{idlwave-shell-help-expression}) ++@item @kbd{C-?} ++@tab Show help on the commands available. ++@end multitable ++ ++Most single-character electric debug bindings use the final keystroke ++of the equivalent multiple key commands (which are of course also ++still available), but some differ (e.g. @kbd{e},@kbd{t},@kbd{q},@kbd{x}). ++Some have additional convenience bindings (like @kbd{@key{SPACE}} for ++stepping). All prefix and other argument options described in this ++section for the commands invoked by electric debug bindings are still ++valid. For example, @kbd{C-u b} sets a conditional breakpoint, just ++as it did with @kbd{C-u C-c C-d C-b}. ++ ++You can toggle the electric debug mode at any time in a buffer using ++@kbd{C-c C-d C-v} (@kbd{v} to turn it off while in the mode), or from ++the Debug menu. Normally the mode will be enabled and disabled at the ++appropriate times, but occasionally you might want to edit a file ++while still debugging it, or switch to the mode for conveniently ++setting lots of breakpoints. ++ ++To quickly abandon a debugging session and return to normal editing at ++the Shell's main level, use @kbd{q} (@code{idlwave-shell-retall}). ++This disables electric debug mode in all IDLWAVE buffers@footnote{Note ++that this binding is not symmetric: @kbd{C-c C-d C-q} is bound to ++@code{idlwave-shell-quit}, which quits your IDL session.}. Help is ++available for the command shortcuts with @kbd{C-?}. If you find this ++mode gets in your way, you can keep it from automatically activating ++by setting the variable @code{idlwave-shell-automatic-electric-debug} ++to @code{nil}, or @code{'breakpoint}. If you'd like the convenient ++electric debug shortcuts available also when run-time errors are ++encountered, set to @code{t}. ++ ++@defopt idlwave-shell-automatic-electric-debug (@code{'breakpoint}) ++Whether to enter electric debug mode automatically when a breakpoint ++or run-time error is encountered, and then disable it in all buffers ++when the $MAIN$ level is reached (either through normal program ++execution, or retall). In addition to @code{nil} for never, and ++@code{t} for both breakpoints and errors, this can be ++@code{'breakpoint} (the default) to enable it only at breakpoint ++halts. ++@end defopt ++ ++@defopt idlwave-shell-electric-stop-color (Violet) ++Default color of the stopped line overlay when in electric debug mode. ++@end defopt ++ ++@defopt idlwave-shell-electric-stop-line-face ++The face to use for the stopped line. Defaults to a face similar to the ++modeline, with color @code{idlwave-shell-electric-stop-color}. ++@end defopt ++ ++@defopt idlwave-shell-electric-zap-to-file (@code{t}) ++If set, when entering electric debug mode, select the window displaying ++the file where point is stopped. This takes point away from the shell ++window, but is useful for immediate stepping, etc. ++@end defopt ++ ++@html ++ ++@end html ++@node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell ++@section Examining Variables ++@cindex @code{PRINT} expressions ++@cindex @code{HELP}, on expressions ++@cindex Expressions, printing & help ++@cindex Examining expressions ++@cindex Printing expressions ++@cindex Mouse binding to print expressions ++ ++@kindex C-c C-d C-p ++Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)}, ++and similar statements to remind yourself of the ++type/size/structure/value/etc. of variables and expressions in your code ++or at the command line? IDLWAVE has a suite of special commands to ++automate these types of variable or expression examinations. They work ++by sending statements to the shell formatted to include the indicated ++expression, and can be accessed in several ways. ++ ++These @emph{examine} commands can be used in the shell or buffer at any ++time (as long as the shell is running), and are very useful when ++execution is stopped in a buffer due to a triggered breakpoint or error, ++or while composing a long command in the IDLWAVE shell. In the latter ++case, the command is sent to the shell and its output is visible, but ++point remains unmoved in the command being composed --- you can inspect ++the constituents of a command you're building without interrupting the ++process of building it! You can even print arbitrary expressions from ++older input or output further up in the shell window --- any expression, ++variable, number, or function you see can be examined. ++ ++If the variable @code{idlwave-shell-separate-examine-output} is ++non-@code{nil} (the default), all examine output will be sent to a ++special @file{*Examine*} buffer, rather than the shell. The output of ++prior examine commands is saved in this buffer. In this buffer @key{c} ++clears the contents, and @key{q} hides the buffer. ++ ++The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to ++print the expression at point, and @kbd{C-c C-d ?}, to invoke help on ++this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric ++Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is ++either an array expression or a function call, or the contents of a pair ++of parentheses. The chosen expression is highlighted, and ++simultaneously the resulting output is highlighted in the shell or ++separate output buffer. Calling the above commands with a prefix ++argument will use the current region as expression instead of using the ++one at point. which can be useful for examining complicated, multi-line ++expressions. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will ++prompt for an expression to print directly. By default, when invoking ++print, only an initial portion of long arrays will be printed, up to ++@code{idlwave-shell-max-print-length}. ++ ++For added speed and convenience, there are mouse bindings which allow ++you to click on expressions and examine their values. Use ++@kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke ++help (i.e. you need to hold down @key{META} and @key{CONTROL} while ++clicking with the middle mouse button). If you simply click, the ++nearest expression will be selected in the same manner as described ++above. You can also @emph{drag} the mouse in order to highlight ++exactly the specific expression or sub-expression you want to examine. ++For custom expression examination, and the powerful customizable ++pop-up examine selection, @xref{Custom Expression Examination}. ++ ++@cindex Printing expressions, on calling stack ++@cindex Restrictions for expression printing ++The same variable inspection commands work both in the IDL Shell and ++IDLWAVE buffers, and even for variables at higher levels of the calling ++stack. For instance, if you're stopped at a breakpoint in a routine, ++you can examine the values of variables and expressions inside its ++calling routine, and so on, all the way up through the calling stack. ++Simply step up the stack, and print variables as you see them ++(@pxref{Walking the Calling Stack}, for information on stepping back ++through the calling stack). The following restrictions apply for all ++levels except the current: ++ ++@itemize @bullet ++@item ++Array expressions must use the @samp{[ ]} index delimiters. Identifiers ++with a @samp{( )} will be interpreted as function calls. ++@item ++@cindex ROUTINE_NAMES, IDL procedure ++N.B.: printing values of expressions on higher levels of the calling ++stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, ++which may or may not be available in future versions of IDL. Caveat ++Examinor. ++@end itemize ++ ++@defopt idlwave-shell-expression-face ++The face for @code{idlwave-shell-expression-overlay}. ++Allows you to choose the font, color and other properties for ++the expression printed by IDL. ++@end defopt ++ ++@defopt idlwave-shell-output-face ++The face for @code{idlwave-shell-output-overlay}. ++Allows to choose the font, color and other properties for the most ++recent output of IDL when examining an expression." ++@end defopt ++ ++@defopt idlwave-shell-separate-examine-output (@code{t}) ++If non-@code{nil}, re-direct the output of examine commands to a special ++@file{*Examine*} buffer, instead of in the shell itself. ++@end defopt ++ ++@defopt idlwave-shell-max-print-length (200) ++The maximum number of leading array entries to print, when examining ++array expressions. ++@end defopt ++ ++@node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell ++@section Custom Expression Examination ++@cindex Expressions, custom examination ++@cindex Custom expression examination ++ ++The variety of possible variable and expression examination commands is ++endless (just look, for instance, at the keyword list to ++@code{widget_info()}). Rather than attempt to include them all, IDLWAVE ++provides two easy methods to customize your own commands, with a special ++mouse examine command, and two macros for generating your own examine ++key and mouse bindings. ++ ++The most powerful and flexible mouse examine command of all is ++available on @kbd{C-S-Mouse-2}. Just as for all the other mouse ++examine commands, it permits click or drag expression selection, but ++instead of sending hard-coded commands to the shell, it pops-up a ++customizable selection list of examine functions to choose among, ++configured with the @code{idlwave-shell-examine-alist} ++variable@footnote{In Electric Debug Mode (@pxref{Electric Debug ++Mode}), the key @kbd{x} provides a single-character shortcut interface ++to the same examine functions for the expression at point or marked by ++the region.}. This variable is a list of key-value pairs (an ++@emph{alist} in Emacs parlance), where the key gives a name to be ++shown for the examine command, and the value is the command strings ++itself, in which the text @code{___} (three underscores) will be ++replaced by the selected expression before being sent to the shell. ++An example might be key @code{Structure Help} with value ++@code{help,___,/STRUCTURE}. In that case, you'd be prompted with ++@emph{Structure Help}, which might send something like ++@code{help,var,/STRUCTURE} to the shell for output. ++@code{idlwave-shell-examine-alist} comes configured by default with a ++large list of examine commands, but you can easily customize it to add ++your own. ++ ++In addition to configuring the functions available to the pop-up mouse ++command, you can easily create your own customized bindings to inspect ++expressions using the two convenience macros ++@code{idlwave-shell-examine} and @code{idlwave-shell-mouse-examine}. ++These create keyboard or mouse-based custom inspections of variables, ++sharing all the same properties of the built-in examine commands. ++Both functions take a single string argument sharing the syntax of the ++@code{idlwave-shell-examine-alist} values, e.g.: ++ ++@lisp ++(add-hook 'idlwave-shell-mode-hook ++ (lambda () ++ (idlwave-shell-define-key-both [s-down-mouse-2] ++ (idlwave-shell-mouse-examine ++ "print, size(___,/DIMENSIONS)")) ++ (idlwave-shell-define-key-both [f9] (idlwave-shell-examine ++ "print, size(___,/DIMENSIONS)")) ++ (idlwave-shell-define-key-both [f10] (idlwave-shell-examine ++ "print,size(___,/TNAME)")) ++ (idlwave-shell-define-key-both [f11] (idlwave-shell-examine ++ "help,___,/STRUCTURE")))) ++@end lisp ++ ++@noindent Now pressing @key{f9}, or middle-mouse dragging with the ++@key{SUPER} key depressed, will print the dimensions of the nearby or ++highlighted expression. Pressing @key{f10} will give the type string, ++and @key{f11} will show the contents of a nearby structure. As you can ++see, the possibilities are only marginally finite. ++ ++@defopt idlwave-shell-examine-alist ++An alist of examine commands in which the keys name the command and ++are displayed in the selection pop-up, and the values are custom IDL ++examine command strings to send, after all instances of @code{___} ++(three underscores) are replaced by the indicated expression. ++@end defopt ++ ++@node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top ++@chapter Acknowledgements ++@cindex Acknowledgements ++@cindex Maintainer, of IDLWAVE ++@cindex Authors, of IDLWAVE ++@cindex Contributors, to IDLWAVE ++@cindex Email address, of Maintainer ++@cindex Thanks ++ ++@noindent ++The main contributors to the IDLWAVE package have been: ++ ++@itemize @minus ++@item ++@uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author. ++Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them ++for several years. ++ ++@item ++@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge ++of the package from version 3.0, during which time he overhauled almost ++everything, modernized IDLWAVE with many new features, and developed the ++manual. ++ ++@item ++@uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current ++maintainer, as of version 4.10, helped shape object method completion ++and most new features introduced in versions 4.x, and introduced many ++new features for IDLWAVE versions 5.x and 6.x. ++@end itemize ++ ++@noindent ++The following people have also contributed to the development of IDLWAVE ++with patches, ideas, bug reports and suggestions. ++ ++@itemize @minus ++@item ++Ulrik Dickow ++@item ++Eric E. Dors ++@item ++Stein Vidar H. Haugan ++@item ++David Huenemoerder ++@item ++Kevin Ivory ++@item ++Dick Jackson ++@item ++Xuyong Liu ++@item ++Simon Marshall ++@item ++Craig Markwardt ++@item ++Laurent Mugnier ++@item ++Lubos Pochman ++@item ++Bob Portmann ++@item ++Patrick M. Ryan ++@item ++Marty Ryba ++@item ++Phil Williams ++@item ++Phil Sterne ++@item ++Paul Sorenson ++@end itemize ++ ++Doug Dirks was instrumental in providing the crucial IDL XML catalog to ++support HTML help with IDL v6.2 and later, and Ali Bahrami provided ++scripts and documentation to interface with the IDL Assistant. ++ ++@noindent ++Thanks to everyone! ++ ++@node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top ++@appendix Sources of Routine Info ++ ++@cindex Sources of routine information ++In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE ++displays the calling sequence and keywords of routines, and completes ++routine names and keywords. For these features to work, IDLWAVE must ++know about the accessible routines. ++ ++@menu ++* Routine Definitions:: Where IDL Routines are defined. ++* Routine Information Sources:: So how does IDLWAVE know about... ++* Catalogs:: ++* Load-Path Shadows:: Routines defined in several places ++* Documentation Scan:: Scanning the IDL Manuals ++@end menu ++ ++@node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info ++@appendixsec Routine Definitions ++@cindex Routine definitions ++@cindex IDL variable @code{!PATH} ++@cindex @code{!PATH}, IDL variable ++@cindex @code{CALL_EXTERNAL}, IDL routine ++@cindex @code{LINKIMAGE}, IDL routine ++@cindex External routines ++ ++@noindent Routines which can be used in an IDL program can be defined in ++several places: ++ ++@enumerate ++@item ++@emph{Builtin routines} are defined inside IDL itself. The source code ++of such routines is not available, but instead are learned about through ++the IDL documentation. ++@item ++Routines which are @emph{part of the current program}, are defined in a ++file explicitly compiled by the user. This file may or may not be ++located on the IDL search path. ++@item ++@emph{Library routines} are defined in files located on IDL's search ++path. When a library routine is called for the first time, IDL will ++find the source file and compile it dynamically. A special sub-category ++of library routines are the @emph{system routines} distributed with IDL, ++and usually available in the @file{lib} subdirectory of the IDL ++distribution. ++@item ++External routines written in other languages (like Fortran or C) can be ++called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, ++or included as dynamically loaded modules (DLMs). Currently IDLWAVE ++cannot provide routine info and completion for such external routines, ++except by querying the Shell for calling information (DLMs only). ++@end enumerate ++ ++@node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info ++@appendixsec Routine Information Sources ++@cindex Routine info sources ++@cindex Builtin list of routines ++@cindex Updating routine info ++@cindex Scanning buffers for routine info ++@cindex Buffers, scanning for routine info ++@cindex Shell, querying for routine info ++ ++@noindent To maintain the most comprehensive information about all IDL ++routines on a system, IDLWAVE collects data from many sources: ++ ++@enumerate ++ ++@item ++It has a @emph{builtin list} with information about the routines IDL ++ships with. IDLWAVE @value{VERSION} is distributed with a list of ++@value{NSYSROUTINES} routines and object methods, reflecting IDL version ++@value{IDLVERSION}. As of IDL v6.2, the routine info is distributed ++directly with IDL in the form of an XML catalog which IDLWAVE scans. ++Formerly, this list was created by scanning the IDL manuals to produce ++the file @file{idlw-rinfo.el}. ++ ++@item ++IDLWAVE @emph{scans} all its @emph{buffers} in the current Emacs session ++for routine definitions. This is done automatically when routine ++information or completion is first requested by the user. Each new ++buffer and each buffer saved after making changes is also scanned. The ++command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used ++at any time to rescan all buffers. ++ ++@item ++If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will ++@emph{query the shell} for compiled routines and their arguments. This ++happens automatically when routine information or completion is first ++requested by the user. Each time an Emacs buffer is compiled with ++@kbd{C-c C-d C-c}, the routine info for that file is queried. Though ++rarely necessary, the command @kbd{C-c C-i} ++(@code{idlwave-update-routine-info}) can be used to explicitly update ++the shell routine data. ++ ++@item ++Many popular libraries are distributed with routine information already ++scanned into @emph{library catalogs} (@pxref{Library Catalogs}). These ++per-directory catalog files can also be built by the user with the ++supplied @file{idlwave_catalog} tool. They are automatically discovered ++by IDLWAVE. ++ ++@item ++IDLWAVE can scan selected directories of source files and store the ++result in a single @emph{user catalog} file which will be ++automatically loaded just like @file{idlw-rinfo.el}. @xref{User ++Catalog}, for information on how to scan files in this way. ++@end enumerate ++ ++Loading all the routine and catalog information can be a time consuming ++process, especially over slow networks. Depending on the system and ++network configuration it could take up to 30 seconds (though locally on ++fast systems is usually only a few seconds). In order to minimize the ++wait time upon your first completion or routine info command in a ++session, IDLWAVE uses Emacs idle time to do the initialization in six ++steps, yielding to user input in between. If this gets into your way, ++set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero). ++The more routines documented in library and user catalogs, the slower ++the loading will be, so reducing this number can help alleviate any long ++load times. ++ ++@defopt idlwave-init-rinfo-when-idle-after (@code{10}) ++Seconds of idle time before routine info is automatically initialized. ++@end defopt ++ ++@defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) ++Non-@code{nil} means scan all buffers for IDL programs when updating ++info. ++@end defopt ++ ++@defopt idlwave-query-shell-for-routine-info (@code{t}) ++Non-@code{nil} means query the shell for info about compiled routines. ++@end defopt ++ ++@defopt idlwave-auto-routine-info-updates ++Controls under what circumstances routine info is updated automatically. ++@end defopt ++ ++@html ++ ++@end html ++@node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info ++@appendixsec Catalogs ++@cindex Catalogs ++ ++@emph{Catalogs} are files containing scanned information on individual ++routines, including arguments and keywords, calling sequence, file path, ++class and procedure vs. function type, etc. They represent a way of ++extending the internal built-in information available for IDL system ++routines (@pxref{Routine Info}) to other source collections. ++ ++Starting with version 5.0, there are two types of catalogs available ++with IDLWAVE. The traditional @emph{user catalog} and the newer ++@emph{library catalogs}. Although they can be used interchangeably, the ++library catalogs are more flexible, and preferred. There are few ++occasions when a user catalog might be preferred --- read below. Both ++types of catalogs can coexist without causing problems. ++ ++To facilitate the catalog systems, IDLWAVE stores information it gathers ++from the shell about the IDL search paths, and can write this ++information out automatically, or on-demand (menu @code{Debug->Save Path ++Info}). On systems with no shell from which to discover the path ++information (e.g. Windows), a library path must be specified in ++@code{idlwave-library-path} to allow library catalogs to be located, and ++to setup directories for user catalog scan (@pxref{User Catalog} for ++more on this variable). Note that, before the shell is running, IDLWAVE ++can only know about the IDL search path by consulting the file pointed ++to by @code{idlwave-path-file} (@file{~/.idlwave/idlpath.el}, by ++default). If @code{idlwave-auto-write-path} is enabled (which is the ++default), the paths are written out whenever the IDLWAVE shell is ++started. ++ ++@defopt idlwave-auto-write-path (@code{t}) ++Write out information on the !PATH and !DIR paths from IDL automatically ++when they change and when the Shell is closed. These paths are needed ++to locate library catalogs. ++@end defopt ++ ++@defopt idlwave-library-path ++IDL library path for Windows and MacOS. Under Unix/MacOSX, will be ++obtained from the Shell when run. ++@end defopt ++ ++@defopt idlwave-system-directory ++The IDL system directory for Windows and MacOS. Also needed for ++locating HTML help and the IDL Assistant for IDL v6.2 and later. Under ++Unix/MacOSX, will be obtained from the Shell and recorded, if run. ++@end defopt ++ ++@defopt idlwave-config-directory (@file{~/.idlwave}) ++Default path where IDLWAVE saves configuration information, a user ++catalog (if any), and a cached scan of the XML catalog (IDL v6.2 and ++later). ++@end defopt ++ ++@menu ++* Library Catalogs:: ++* User Catalog:: ++@end menu ++ ++@html ++ ++@end html ++@node Library Catalogs, User Catalog, Catalogs, Catalogs ++@appendixsubsec Library Catalogs ++@cindex @file{.idlwave_catalog} ++@cindex Library catalogs ++@cindex @code{idlwave_catalog} ++ ++Library catalogs consist of files named @file{.idlwave_catalog} stored ++in directories containing @code{.pro} routine files. They are ++discovered on the IDL search path and loaded automatically when routine ++information is read. Each catalog file documents the routines found in ++that directory --- one catalog per directory. Every catalog has a ++library name associated with it (e.g. @emph{AstroLib}). This name will ++be shown briefly when the catalog is found, and in the routine info of ++routines it documents. ++ ++Many popular libraries of routines are shipped with IDLWAVE catalog ++files by default, and so will be automatically discovered. Library ++catalogs are scanned externally to Emacs using a tool provided with ++IDLWAVE. Each catalog can be re-scanned independently of any other. ++Catalogs can easily be made available system-wide with a common source ++repository, providing uniform routine information, and lifting the ++burden of scanning from the user (who may not even know they're using a ++scanned catalog). Since all catalogs are independent, they can be ++re-scanned automatically to gather updates, e.g. in a @file{cron} job. ++Scanning is much faster than with the built-in user catalog method. One ++minor disadvantage: the entire IDL search path is scanned for catalog ++files every time IDLWAVE starts up, which might be slow if accessing IDL ++routines over a slow network. ++ ++A Perl tool to create library catalogs is distributed with IDLWAVE: ++@code{idlwave_catalog}. It can be called quite simply: ++@example ++idlwave_catalog MyLib ++@end example ++ ++@noindent This will scan all directories recursively beneath the current and ++populate them with @file{.idlwave_catalog} files, tagging the routines ++found there with the name library ``MyLib''. The full usage ++information: ++ ++@example ++Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname ++ libname - Unique name of the catalog (4 or more alphanumeric ++ characters). ++ -l - Scan local directory only, otherwise recursively ++ catalog all directories at or beneath this one. ++ -v - Print verbose information. ++ -d - Instead of scanning, delete all .idlwave_catalog files ++ here or below. ++ -s - Be silent. ++ -f - Force overwriting any catalogs found with a different ++ library name. ++ -h - Print this usage. ++@end example ++ ++To re-load the library catalogs on the IDL path, force a system routine ++info update using a single prefix to @code{idlwave-update-routine-info}: ++@kbd{C-u C-c C-i}. ++ ++@defopt idlwave-use-library-catalogs (@code{t}) ++Whether to search for and load library catalogs. Disable if load ++performance is a problem and/or the catalogs are not needed. ++@end defopt ++ ++@node User Catalog, , Library Catalogs, Catalogs ++@appendixsubsec User Catalog ++@cindex User catalog ++@cindex IDL library routine info ++@cindex Windows ++@cindex MacOS ++@cindex IDL variable @code{!DIR} ++@cindex @code{!DIR}, IDL variable ++ ++The user catalog is the old routine catalog system. It is produced ++within Emacs, and stored in a single file in the user's home directory ++(@file{.idlwave/idlusercat.el} by default). Although library catalogs ++are more flexible, there may be reasons to prefer a user catalog ++instead, including: ++ ++@itemize @bullet ++@item The scan is internal to Emacs, so you don't need a working Perl ++installation, as you do for library catalogs. ++@item Can be used to scan directories for which the user has no write ++privileges. ++@item Easy widget-based path selection. ++@end itemize ++ ++However, no routine info is available in the user catalog by default; ++the user must actively complete a scan. In addition, this type of ++catalog is all or nothing: if a single routine changes, the entire ++catalog must be rescanned to update it. Creating the user catalog is ++also much slower than scanning library catalogs. ++ ++You can scan any of the directories on the currently known path. Under ++Windows and MacOS (not OSX), you need to specify the IDL search path in ++the variable @code{idlwave-library-path}, and the location of the IDL ++directory (the value of the @code{!DIR} system variable) in the variable ++@code{idlwave-system-directory}, like this@footnote{The initial @samp{+} ++leads to recursive expansion of the path, just like in IDL}: ++ ++@lisp ++(setq idlwave-library-path ++ '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs")) ++(setq idlwave-system-directory "c:/RSI/IDL56/") ++@end lisp ++ ++@noindent Under GNU/Linux and UNIX, these values will be automatically ++gathered from the IDLWAVE shell, if run. ++ ++The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item ++@samp{IDLWAVE->Routine Info->Select Catalog Directories}) can then be ++used to create a user catalog. It brings up a widget in which you can ++select some or all directories on the search path. Directories which ++already contain a library catalog are marked with @samp{[LIB]}, and need ++not be scanned (although there is no harm if you do so, other than the ++additional memory used for the duplication). ++ ++After selecting directories, click on the @w{@samp{[Scan & Save]}} ++button in the widget to scan all files in the selected directories and ++write out the resulting routine information. In order to update the ++library information using the directory selection, call the command ++@code{idlwave-update-routine-info} with a double prefix argument: ++@w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously ++selected directories, write an updated version of the user catalog file ++and rebuild IDLWAVE's internal lists. If you give three prefix ++arguments @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a ++background job@footnote{Unix systems only, I think.}. You can continue ++to work, and the library catalog will be re-read when it is ready. If ++you find you need to update the user catalog often, you should consider ++building a library catalog for your routines instead (@pxref{Library ++Catalogs}). ++ ++@defopt idlwave-special-lib-alist ++Alist of regular expressions matching special library directories for ++labeling in routine-info display. ++@end defopt ++ ++@node Load-Path Shadows, Documentation Scan, Catalogs, Sources of Routine Info ++@appendixsec Load-Path Shadows ++@cindex Load-path shadows ++@cindex Shadows, load-path ++@cindex Duplicate routines ++@cindex Multiply defined routines ++@cindex Routine definitions, multiple ++@cindex Application, testing for shadowing ++@cindex Buffer, testing for shadowing ++ ++IDLWAVE can compile a list of routines which are (re-)defined in more ++than one file. Since one definition will hide (shadow) the others ++depending on which file is compiled first, such multiple definitions are ++called "load-path shadows". IDLWAVE has several routines to scan for ++load path shadows. The output is placed into the special buffer ++@file{*Shadows*}. The format of the output is identical to the source ++section of the routine info buffer (@pxref{Routine Info}). The ++different definitions of a routine are ordered by @emph{likelihood of ++use}. So the first entry will be most likely the one you'll get if an ++unsuspecting command uses that routine. Before listing shadows, you ++should make sure that routine info is up-to-date by pressing @kbd{C-c ++C-i}. Here are the different routines (also available in the Menu ++@samp{IDLWAVE->Routine Info}): ++ ++@table @asis ++@item @kbd{M-x idlwave-list-buffer-load-path-shadows} ++This commands checks the names of all routines defined in the current ++buffer for shadowing conflicts with other routines accessible to ++IDLWAVE. The command also has a key binding: @kbd{C-c C-b} ++@item @kbd{M-x idlwave-list-shell-load-path-shadows}. ++Checks all routines compiled under the shell for shadowing. This is ++very useful when you have written a complete application. Just compile ++the application, use @code{RESOLVE_ALL} to compile any routines used by ++your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and ++then check for shadowing. ++@item @kbd{M-x idlwave-list-all-load-path-shadows} ++This command checks all routines accessible to IDLWAVE for conflicts. ++@end table ++ ++For these commands to work fully you need to scan the entire load path ++in either a user or library catalog. Also, IDLWAVE should be able to ++distinguish between the system library files (normally installed in ++@file{/usr/local/rsi/idl/lib}) and any site specific or user specific ++files. Therefore, such local files should not be installed inside the ++@file{lib} directory of the IDL directory. This is also advisable for ++many other reasons. ++ ++@cindex Windows ++@cindex MacOS ++@cindex IDL variable @code{!DIR} ++@cindex @code{!DIR}, IDL variable ++Users of Windows and MacOS (not X) also must set the variable ++@code{idlwave-system-directory} to the value of the @code{!DIR} system ++variable in IDL. IDLWAVE appends @file{lib} to the value of this ++variable and assumes that all files found on that path are system ++routines. ++ ++Another way to find out if a specific routine has multiple definitions ++on the load path is routine info display (@pxref{Routine Info}). ++ ++@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info ++@appendixsec Documentation Scan ++@cindex @file{get_html_rinfo} ++@cindex @file{idlw-rinfo.el} ++@cindex Scanning the documentation ++@cindex Perl program, to create @file{idlw-rinfo.el} ++ ++@strong{Starting with version 6.2, IDL is distributed directly with HTML ++online help, and an XML-based catalog of routine information}. This ++makes scanning the manuals with the tool @file{get_html_rinfo}, and the ++@file{idlw-rinfo.el} file it produced, as described here, entirely ++unnecessary. The information is left here for users wishing to produce ++a catalog of older IDL versions' help. ++ ++ ++IDLWAVE derives its knowledge about system routines from the IDL ++manuals. The file @file{idlw-rinfo.el} contains the routine information ++for the IDL system routines, and links to relevant sections of the HTML ++documentation. The Online Help feature of IDLWAVE requires HTML ++versions of the IDL manuals to be available; the HTML documentation is ++not distributed with IDLWAVE by default, but must be downloaded ++separately. ++ ++The HTML files and related images can be produced from the ++@file{idl.chm} HTMLHelp file distributed with IDL using the free ++Microsoft HTML Help Workshop. If you are lucky, the maintainer of ++IDLWAVE will always have access to the newest version of IDL and provide ++updates. The IDLWAVE distribution also contains the Perl program ++@file{get_html_rinfo} which constructs the @file{idlw-rinfo.el} file by ++scanning the HTML documents produced from the IDL documentation. ++Instructions on how to use @file{get_html_rinfo} are in the program ++itself. ++ ++@node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top ++@appendix HTML Help Browser Tips ++@cindex Browser Tips ++ ++There are a wide variety of possible browsers to use for displaying ++the online HTML help available with IDLWAVE (starting with version ++5.0). Since IDL v6.2, a single cross-platform HTML help browser, the ++@emph{IDL Assistant} is distributed with IDL. If this help browser is ++available, it is the preferred choice, and the default. The variable ++@code{idlwave-help-use-assistant}, enabled by default, controls ++whether this help browser is used. If you use the IDL Assistant, the ++tips here are not relevant. ++ ++Since IDLWAVE runs on a many different system types, a single browser ++configuration is not possible, but choices abound. On many systems, ++the default browser configured in @code{browse-url-browser-function}, ++and hence inherited by default by ++@code{idlwave-help-browser-function}, is Netscape. Unfortunately, the ++HTML manuals decompiled from the original source contain formatting ++structures which Netscape 4.x does not handle well, though they are ++still readable. A much better choice is Mozilla, or one of the ++Mozilla-derived browsers such as ++@uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux), ++@uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or ++@uref{http://www.mozilla.org/projects/firebird/,Firebird} (all ++platforms). Newer versions of Emacs provide a browser-function choice ++@code{browse-url-gnome-moz} which uses the Gnome-configured browser. ++ ++Note that the HTML files decompiled from the help sources contain ++specific references to the @samp{Symbol} font, which by default is not ++permitted in normal encodings (it's invalid, technically). Though it ++only impacts a few symbols, you can trick Mozilla-based browsers into ++recognizing @samp{Symbol} by following the directions ++@uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With ++this fix in place, HTML help pages look almost identical to their PDF ++equivalents (yet can be bookmarked, browsed as history, searched, ++etc.). ++ ++@noindent Individual platform recommendations: ++ ++@itemize @bullet ++@item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser ++and its associated ++@uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode ++provide in-buffer browsing with image display, and excellent speed and ++formatting. Both the Emacs mode and the browser itself must be ++downloaded separately. To use this browser, include ++ ++@lisp ++(setq idlwave-help-browser-function 'w3m-browse-url) ++@end lisp ++ ++in your @file{.emacs}. Setting a few other nice @code{w3m} options ++cuts down on screen clutter: ++ ++@lisp ++(setq w3m-use-tab nil ++ w3m-use-header-line nil ++ w3m-use-toolbar nil) ++@end lisp ++ ++If you use a dedicated frame for help, you might want to add the ++following, to get consistent behavior with the @kbd{q} key: ++ ++@lisp ++;; Close my help window when w3m closes. ++(defadvice w3m-close-window (after idlwave-close activate) ++ (if (boundp 'idlwave-help-frame) ++ (idlwave-help-quit))) ++@end lisp ++ ++Note that you can open the file in an external browser from within ++@code{w3m} using @kbd{M}. ++@end itemize ++ ++@node Configuration Examples, Windows and MacOS, HTML Help Browser Tips, Top ++@appendix Configuration Examples ++@cindex Configuration examples ++@cindex Example configuration ++@cindex @file{.emacs} ++@cindex Default settings, of options ++@cindex Interview, with the maintainer ++ ++@noindent ++@b{Question:} You have all these complicated configuration options in ++your package, but which ones do @emph{you} as the maintainer actually ++set in your own configuration? ++ ++@noindent ++@b{Answer:} Not many, beyond custom key bindings. I set most defaults ++the way that seems best. However, the default settings do not turn on ++features which: ++ ++@itemize @minus ++@item ++are not self-evident (i.e. too magic) when used by an unsuspecting user. ++@item ++are too intrusive. ++@item ++will not work properly on all Emacs installations. ++@item ++break with widely used standards. ++@item ++use function or other non-standard keys. ++@item ++are purely personal customizations, like additional key bindings, and ++library names. ++@end itemize ++ ++@noindent To see what I mean, here is the @emph{entire} configuration ++the old maintainer had in his @file{.emacs}: ++ ++@lisp ++(setq idlwave-shell-debug-modifiers '(control shift) ++ idlwave-store-inquired-class t ++ idlwave-shell-automatic-start t ++ idlwave-main-block-indent 2 ++ idlwave-init-rinfo-when-idle-after 2 ++ idlwave-help-dir "~/lib/emacs/idlwave" ++ idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib") ++ ("/jhuapl/" . "JHUAPL-Lib") ++ ("/dominik/lib/idl/" . "MyLib"))) ++@end lisp ++ ++However, if you are an Emacs power-user and want IDLWAVE to work ++completely differently, you can change almost every aspect of it. Here ++is an example of a much more extensive configuration of IDLWAVE. The ++user is King! ++ ++@example ++;;; Settings for IDLWAVE mode ++ ++(setq idlwave-block-indent 3) ; Indentation settings ++(setq idlwave-main-block-indent 3) ++(setq idlwave-end-offset -3) ++(setq idlwave-continuation-indent 1) ++(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" ++ ; anchored at start of line. ++(setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> ++(setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' ++(setq idlwave-expand-generic-end t) ; convert END to ENDIF etc... ++(setq idlwave-reserved-word-upcase t) ; Make reserved words upper case ++ ; (with abbrevs only) ++(setq idlwave-abbrev-change-case nil) ; Don't force case of expansions ++(setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill ++(setq idlwave-show-block nil) ; Turn off blinking to begin ++(setq idlwave-abbrev-move t) ; Allow abbrevs to move point ++(setq idlwave-query-class '((method-default . nil) ; No query for method ++ (keyword-default . nil); or keyword completion ++ ("INIT" . t) ; except for these ++ ("CLEANUP" . t) ++ ("SETPROPERTY" .t) ++ ("GETPROPERTY" .t))) ++ ++;; Using w3m for help (must install w3m and emacs-w3m) ++(autoload 'w3m-browse-url "w3m" "Interface for w3m on Emacs." t) ++(setq idlwave-help-browser-function 'w3m-browse-url ++ w3m-use-tab nil ; no tabs, location line, or toolbar ++ w3m-use-header-line nil ++ w3m-use-toolbar nil) ++ ++;; Close my help window or frame when w3m closes with `q' ++(defadvice w3m-close-window (after idlwave-close activate) ++ (if (boundp 'idlwave-help-frame) ++ (idlwave-help-quit))) ++ ++;; Some setting can only be done from a mode hook. Here is an example: ++(add-hook 'idlwave-mode-hook ++ (lambda () ++ (setq case-fold-search nil) ; Make searches case sensitive ++ ;; Run other functions here ++ (font-lock-mode 1) ; Turn on font-lock mode ++ (idlwave-auto-fill-mode 0) ; Turn off auto filling ++ (setq idlwave-help-browser-function 'browse-url-w3) ++ ++ ;; Pad with 1 space (if -n is used then make the ++ ;; padding a minimum of n spaces.) The defaults use -1 ++ ;; instead of 1. ++ (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1)) ++ (idlwave-action-and-binding "<" '(idlwave-surround 1 1)) ++ (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-))) ++ (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) ++ ++ ;; Only pad after comma and with exactly 1 space ++ (idlwave-action-and-binding "," '(idlwave-surround nil 1)) ++ (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) ++ ++ ;; Pad only after `->', remove any space before the arrow ++ (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2)) ++ ++ ;; Set some personal bindings ++ ;; (In this case, makes `,' have the normal self-insert behavior.) ++ (local-set-key "," 'self-insert-command) ++ (local-set-key [f5] 'idlwave-shell-break-here) ++ (local-set-key [f6] 'idlwave-shell-clear-current-bp) ++ ++ ;; Create a newline, indenting the original and new line. ++ ;; A similar function that does _not_ reindent the original ++ ;; line is on "\C-j" (The default for emacs programming modes). ++ (local-set-key "\n" 'idlwave-newline) ++ ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. ++ ++ ;; Some personal abbreviations ++ (define-abbrev idlwave-mode-abbrev-table ++ (concat idlwave-abbrev-start-char "wb") "widget_base()" ++ (idlwave-keyword-abbrev 1)) ++ (define-abbrev idlwave-mode-abbrev-table ++ (concat idlwave-abbrev-start-char "on") "obj_new()" ++ (idlwave-keyword-abbrev 1)) ++ )) ++ ++;;; Settings for IDLWAVE SHELL mode ++ ++(setq idlwave-shell-overlay-arrow "=>") ; default is ">" ++(setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame ++(setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> " ++(setq idlwave-shell-explicit-file-name "wave") ++(setq idlwave-shell-process-name "wave") ++(setq idlwave-shell-use-toolbar nil) ; No toolbar ++ ++;; Most shell interaction settings can be done from the shell-mode-hook. ++(add-hook 'idlwave-shell-mode-hook ++ (lambda () ++ ;; Set up some custom key and mouse examine commands ++ (idlwave-shell-define-key-both [s-down-mouse-2] ++ (idlwave-shell-mouse-examine ++ "print, size(___,/DIMENSIONS)")) ++ (idlwave-shell-define-key-both [f9] (idlwave-shell-examine ++ "print, size(___,/DIMENSIONS)")) ++ (idlwave-shell-define-key-both [f10] (idlwave-shell-examine ++ "print,size(___,/TNAME)")) ++ (idlwave-shell-define-key-both [f11] (idlwave-shell-examine ++ "help,___,/STRUCTURE")))) ++@end example ++ ++@html ++ ++@end html ++@node Windows and MacOS, Troubleshooting, Configuration Examples, Top ++@appendix Windows and MacOS ++@cindex Windows ++@cindex MacOS ++@cindex MacOSX ++ ++IDLWAVE was developed on a UNIX system. However, thanks to the ++portability of Emacs, much of IDLWAVE does also work under different ++operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS. ++ ++The only real problem is that there is no command-line version of IDL ++for Windows or MacOS(<=9) with which IDLWAVE can interact. As a ++result, the IDLWAVE Shell does not work and you have to rely on IDLDE ++to run and debug your programs. However, editing IDL source files ++with Emacs/IDLWAVE works with all bells and whistles, including ++routine info, completion and fast online help. Only a small amount of ++additional information must be specified in your @file{.emacs} file: ++the path names which, on a UNIX system, are automatically gathered by ++talking to the IDL program. ++ ++Here is an example of the additional configuration needed for a Windows ++system. I am assuming that IDLWAVE has been installed in ++@w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in ++@w{@samp{C:\RSI\IDL63}}. ++ ++@lisp ++;; location of the lisp files (only needed if IDLWAVE is not part of ++;; your default X/Emacs installation) ++(setq load-path (cons "c:/program files/IDLWAVE" load-path)) ++ ++;; The location of the IDL library directories, both standard, and your own. ++;; note that the initial "+" expands the path recursively ++(setq idlwave-library-path ++ '("+c:/RSI/IDL63/lib/" "+c:/path/to/my/idllibs" )) ++ ++;; location of the IDL system directory (try "print,!DIR") ++(setq idlwave-system-directory "c:/RSI/IDL63/") ++ ++@end lisp ++ ++@noindent Furthermore, Windows sometimes tries to outsmart you --- make ++sure you check the following things: ++ ++@itemize @bullet ++@item When you download the IDLWAVE distribution, make sure you save the ++file under the names @file{idlwave.tar.gz}. ++@item M-TAB switches among running programs --- use Esc-TAB ++instead. ++@item Other issues as yet unnamed... ++@end itemize ++ ++Windows users who'd like to make use of IDLWAVE's context-aware HTML ++help can skip the browser and use the HTMLHelp functionality directly. ++@xref{Help with HTML Documentation}. ++ ++@html ++ ++@end html ++@node Troubleshooting, GNU Free Documentation License, Windows and MacOS, Top ++@appendix Troubleshooting ++@cindex Troubleshooting ++ ++Although IDLWAVE usually installs and works without difficulty, a few ++common problems and their solutions are documented below. ++ ++@enumerate ++ ++@item @strong{Whenever an IDL error occurs or a breakpoint is hit, I get ++errors or strange behavior when I try to type anything into some of my ++IDLWAVE buffers.} ++ ++This is a @emph{feature}, not an error. You're in @emph{Electric ++Debug Mode} (@pxref{Electric Debug Mode}). You should see ++@code{*Debugging*} in the mode-line. The buffer is read-only and all ++debugging and examination commands are available as single keystrokes; ++@kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and ++customize the variable @code{idlwave-shell-automatic-electric-debug} ++if you prefer not to enter electric debug on breakpoints@dots{} but ++you really should try it before you disable it! You can also ++customize this variable to enter debug mode when errors are ++encountered. ++ ++@item @strong{I get errors like @samp{Searching for program: no such ++file or directory, idl} when attempting to start the IDL shell.} ++ ++IDLWAVE needs to know where IDL is in order to run it as a process. ++By default, it attempts to invoke it simply as @samp{idl}, which ++presumes such an executable is on your search path. You need to ++ensure @samp{idl} is on your @samp{$PATH}, or specify the full ++pathname to the idl program with the variable ++@code{idlwave-shell-explicit-file-name}. Note that you may need to ++set your shell search path in two places when running Emacs as an Aqua ++application with MacOSX; see the next topic. ++ ++@item @strong{IDLWAVE is disregarding my @samp{IDL_PATH} which I set ++under MacOSX} ++ ++If you run Emacs directly as an Aqua application, rather than from the ++console shell, the environment is set not from your usual shell ++configuration files (e.g. @file{.cshrc}), but from the file ++@file{~/.MacOSX/environment.plist}. Either include your path settings ++there, or start Emacs and IDLWAVE from the shell. ++ ++@item @strong{I get errors like @samp{Symbol's function is void: ++overlayp}} ++ ++You don't have the @samp{fsf-compat} package installed, which IDLWAVE ++needs to run under XEmacs. Install it, or find an XEmacs distribution ++which includes it by default. ++ ++@item @strong{I'm getting errors like @samp{Symbol's value as variable is void: ++cl-builtin-gethash} on completion or routine info.} ++ ++This error arises if you upgraded Emacs from 20.x to 21.x without ++re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible ++in compiled lisp files. Presumably, you kept the original .elc files in ++place, and this is the source of the error. If you recompile (or just ++"make; make install") from source, it should resolve this problem. ++Another option is to recompile the @file{idlw*.el} files by hand using ++@kbd{M-x byte-compile-file}. ++ ++@item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches ++windows on my desktop.} ++ ++Your system is trapping @kbd{M-@key{TAB}} and using it for its own ++nefarious purposes: Emacs never sees the keystrokes. On many Unix ++systems, you can reconfigure your window manager to use another key ++sequence for switching among windows. Another option is to use the ++equivalent sequence @kbd{@key{ESC}-@key{TAB}}. ++ ++@item @strong{When stopping at breakpoints or errors, IDLWAVE does not ++seem to highlight the relevant line in the source.} ++ ++IDLWAVE scans for error and halt messages and highlights the stop ++location in the correct file. However, if you've changed the system ++variable @samp{!ERROR_STATE.MSG_PREFIX}, it is unable to parse these ++message correctly. Don't do that. ++ ++@item @strong{IDLWAVE doesn't work correctly when using ENVI.} ++ ++Though IDLWAVE was not written with ENVI in mind, it works just fine ++with it, as long as you update the prompt it's looking for (@samp{IDL> ++} by default). You can do this with the variable ++@code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g., ++in your @file{.emacs}: ++ ++@lisp ++(setq idlwave-shell-prompt-pattern "^\r? ?\\(ENVI\\|IDL\\)> ") ++@end lisp ++ ++@item @strong{Attempts to set breakpoints fail: no breakpoint is ++indicated in the IDLWAVE buffer.} ++ ++IDL changed its breakpoint reporting format starting with IDLv5.5. The ++first version of IDLWAVE to support the new format is IDLWAVE v4.10. If ++you have an older version and are using IDL >v5.5, you need to upgrade, ++and/or make sure your recent version of IDLWAVE is being found on the ++Emacs load-path (see the next entry). You can list the version being ++used with @kbd{C-h v idlwave-mode-version @key{RET}}. ++ ++@item @strong{I installed a new version of IDLWAVE, but the old ++version is still being used} or @strong{IDLWAVE works, but when I ++tried to install the optional modules @file{idlw-roprompt.el} or ++@file{idlw-complete-structtag}, I get errors like @samp{Cannot open ++load file}}. ++ ++The problem is that your Emacs is not finding the version of IDLWAVE you ++installed. Many Emacsen come with an older bundled copy of IDLWAVE ++(e.g. v4.7 for Emacs 21.x), which is likely what's being used instead. ++You need to make sure your Emacs @emph{load-path} contains the directory ++where IDLWAVE is installed (@file{/usr/local/share/emacs/site-lisp}, by ++default), @emph{before} Emacs' default search directories. You can ++accomplish this by putting the following in your @file{.emacs}: ++ ++@lisp ++(setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path)) ++@end lisp ++ ++@noindent You can check on your load-path value using @kbd{C-h v ++load-path @key{RET}}, and @kbd{C-h m} in an IDLWAVE buffer should show ++you the version Emacs is using. ++ ++@item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.} ++ ++Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated ++programming mode for CORBA's Interface Definition Language (you should ++see @samp{(IDL)}, not @samp{(IDLWAVE)} in the mode-line). One ++solution: don't name your file @file{.idl}, but rather @file{.pro}. ++Another solution: make sure @file{.idl} files load IDLWAVE instead of ++@samp{idl-mode} by adding the following to your @file{.emacs}: ++ ++@lisp ++(setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode) ++@end lisp ++ ++@item @strong{The routine info for my local routines is out of date!} ++ ++IDLWAVE collects routine info from various locations (@pxref{Routine ++Information Sources}). Routines in files visited in a buffer or ++compiled in the shell should be up to date. For other routines, the ++information is only as current as the most recent scan. If you have a ++rapidly changing set of routines, and you'd like the latest routine ++information to be available for it, one powerful technique is to make ++use of the library catalog tool, @samp{idlwave_catalog}. Simply add a ++line to your @samp{cron} file (@samp{crontab -e} will let you edit this ++on some systems), like this ++ ++@example ++45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib) ++@end example ++ ++@noindent where @samp{MyLib} is the name of your library. This will ++rescan all @file{.pro} files at or below @file{/path/to/myidllib} every ++week night at 3:45am. You can even scan site-wide libraries with this ++method, and the most recent information will be available to all users. ++Since the scanning is very fast, there is very little impact. ++ ++@item @strong{All the Greek-font characters in the HTML help are ++displayed as Latin characters!} ++ ++Unfortunately, the HTMLHelp files RSI provides attempt to switch to ++@samp{Symbol} font to display Greek characters, which is not really an ++permitted method for doing this in HTML. There is a "workaround" for ++some browsers: @xref{HTML Help Browser Tips}. ++ ++@item @strong{In the shell, my long commands are truncated at 256 characters!} ++ ++This actually happens when running IDL in an XTerm as well. There are ++a couple of workarounds: @code{define_key,/control,'^d'} (e.g. in ++your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character ++and give you a 512 character limit. You won't be able to use ++@key{C-d} to quit the shell, however. Another possibility is ++@code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a ++memory-bounded limit), but disables the processing of background ++widget events (those with @code{/NO_BLOCK} passed to @code{XManager}). ++ ++@item @strong{When I invoke IDL HTML help on a routine, the page which ++is loaded is one page off, e.g. for @code{CONVERT_COORD}, I get ++@code{CONTOUR}.} ++ ++You have a mismatch between your help index and the HTML help package ++you downloaded. You need to ensure you download a ``downgrade kit'' if ++you are using anything older than the latest HTML help package. A new ++help package appears with each IDL release (assuming the documentation ++is updated). ++Starting with IDL 6.2, the HTML help and its catalog are ++distributed with IDL, and so should never be inconsistent. ++ ++@item @strong{I get errors such as @samp{void-variable ++browse-url-browser-function} or similar when attempting to load IDLWAVE ++under XEmacs.} ++ ++You don't have the @samp{browse-url} (or other required) XEmacs package. ++Unlike GNU Emacs, XEmacs distributes many packages separately from the ++main program. IDLWAVE is actually among these, but is not always the ++most up to date. When installing IDLWAVE as an XEmacs package, it ++should prompt you for required additional packages. When installing it ++from source, it won't and you'll get this error. The easiest solution ++is to install all the packages when you install XEmacs (the so-called ++@samp{sumo} bundle). The minimum set of XEmacs packages required by ++IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}. ++ ++@end enumerate ++ ++@node GNU Free Documentation License, Index, Troubleshooting, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index, , GNU Free Documentation License, Top ++@unnumbered Index ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492 ++@end ignore +diff --git a/doc/misc/info.texi b/doc/misc/info.texi +new file mode 100644 +index 0000000..147e0b7 +--- /dev/null ++++ b/doc/misc/info.texi +@@ -0,0 +1,1506 @@ ++\input texinfo.tex @c -*-texinfo-*- ++@c We must \input texinfo.tex instead of texinfo, otherwise make ++@c distcheck in the Texinfo distribution fails, because the texinfo Info ++@c file is made first, and texi2dvi must include . first in the path. ++@comment %**start of header ++@setfilename info.info ++@settitle Info ++@syncodeindex fn cp ++@syncodeindex vr cp ++@syncodeindex ky cp ++@comment %**end of header ++ ++@copying ++This file describes how to use Info, the on-line, menu-driven GNU ++documentation system. ++ ++Copyright @copyright{} 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, ++2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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 Emacs 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.'' ++ ++This document is part of a collection distributed under the GNU Free ++Documentation License. If you want to distribute this document ++separately from the collection, you can do so by adding a copy of the ++license to the document, as described in section 6 of the license. ++@end quotation ++@end copying ++ ++@dircategory Texinfo documentation system ++@direntry ++* Info: (info). How to use the documentation browsing system. ++@end direntry ++ ++@titlepage ++@title Info ++@subtitle The online, hyper-text GNU documentation system ++@author Brian Fox ++@author and the GNU Texinfo community ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top ++@top Info: An Introduction ++ ++The GNU Project distributes most of its on-line manuals in the ++@dfn{Info format}, which you read using an @dfn{Info reader}. You are ++probably using an Info reader to read this now. ++ ++There are two primary Info readers: @code{info}, a stand-alone program ++designed just to read Info files (@pxref{Top,,What is Info?, ++info-stnd, GNU Info}), and the @code{info} package in GNU Emacs, a ++general-purpose editor. At present, only the Emacs reader supports ++using a mouse. ++ ++@ifinfo ++If you are new to the Info reader and want to learn how to use it, ++type the command @kbd{h} now. It brings you to a programmed ++instruction sequence. ++ ++To read about advanced Info commands, type @kbd{n} twice. This ++brings you to @cite{Advanced Info Commands}, skipping over the `Getting ++Started' chapter. ++@end ifinfo ++@end ifnottex ++ ++@insertcopying ++ ++@menu ++* Getting Started:: Getting started using an Info reader. ++* Advanced:: Advanced Info commands. ++* Expert Info:: Info commands for experts. ++* Index:: An index of topics, commands, and variables. ++@end menu ++ ++@node Getting Started, Advanced, Top, Top ++@comment node-name, next, previous, up ++@chapter Getting Started ++ ++This first part of this Info manual describes how to get around inside ++of Info. The second part of the manual describes various advanced ++Info commands. The third part briefly explains how to generate Info ++files from Texinfo files, and describes how to write an Info file ++by hand. ++ ++@ifnotinfo ++This manual is primarily designed for browsing with an Info reader ++program on a computer, so that you can try Info commands while reading ++about them. Reading it on paper or with an HTML browser is less ++effective, since you must take it on faith that the commands described ++really do what the manual says. By all means go through this manual ++now that you have it; but please try going through the on-line version ++as well. ++ ++@cindex Info reader, how to invoke ++@cindex entering Info ++There are two ways of looking at the online version of this manual: ++ ++@enumerate ++@item ++Type @code{info} at your shell's command line. This approach uses a ++stand-alone program designed just to read Info files. ++ ++@item ++Type @code{emacs} at the command line; then type @kbd{C-h i} ++(@kbd{Control-h}, followed by @kbd{i}). This approach uses the Info ++mode of the Emacs editor. ++@end enumerate ++ ++In either case, then type @kbd{mInfo} (just the letters), followed by ++@key{RET}---the ``Return'' or ``Enter'' key. At this point, you should ++be ready to follow the instructions in this manual as you read them on ++the screen. ++@c FIXME! (pesch@cygnus.com, 14 dec 1992) ++@c Is it worth worrying about what-if the beginner goes to somebody ++@c else's Emacs session, which already has an Info running in the middle ++@c of something---in which case these simple instructions won't work? ++@end ifnotinfo ++ ++@menu ++* Help-Small-Screen:: Starting Info on a Small Screen. ++* Help:: How to use Info. ++* Help-P:: Returning to the Previous node. ++* Help-^L:: The Space, DEL, B and ^L commands. ++* Help-Inv:: Invisible text in Emacs Info. ++* Help-M:: Menus. ++* Help-Xref:: Following cross-references. ++* Help-Int:: Some intermediate Info commands. ++* Help-Q:: Quitting Info. ++@end menu ++ ++@node Help-Small-Screen ++@section Starting Info on a Small Screen ++ ++@ifnotinfo ++(In Info, you only see this section if your terminal has a small ++number of lines; most readers pass by it without seeing it.) ++@end ifnotinfo ++ ++@cindex small screen, moving around ++Since your terminal has a relatively small number of lines on its ++screen, it is necessary to give you special advice at the beginning. ++ ++If the entire text you are looking at fits on the screen, the text ++@samp{All} will be displayed at the bottom of the screen. In the ++stand-alone Info reader, it is displayed at the bottom right corner of ++the screen; in Emacs, it is displayed on the modeline. If you see the ++text @samp{Top} instead, it means that there is more text below that ++does not fit. To move forward through the text and see another screen ++full, press @key{SPC}, the Space bar. To move back up, press the key ++labeled @samp{Backspace} or @samp{DEL} (on some keyboards, this key ++might be labeled @samp{Delete}). ++ ++@ifinfo ++Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and ++see what they do. At the end are instructions of what you should do ++next. ++ ++@format ++This is line 20 ++This is line 21 ++This is line 22 ++This is line 23 ++This is line 24 ++This is line 25 ++This is line 26 ++This is line 27 ++This is line 28 ++This is line 29 ++This is line 30 ++This is line 31 ++This is line 32 ++This is line 33 ++This is line 34 ++This is line 35 ++This is line 36 ++This is line 37 ++This is line 38 ++This is line 39 ++This is line 40 ++This is line 41 ++This is line 42 ++This is line 43 ++This is line 44 ++This is line 45 ++This is line 46 ++This is line 47 ++This is line 48 ++This is line 49 ++This is line 50 ++This is line 51 ++This is line 52 ++This is line 53 ++This is line 54 ++This is line 55 ++This is line 56 ++This is line 57 ++This is line 58 ++This is line 59 ++@end format ++ ++If you have managed to get here, go back to the beginning with ++@kbd{DEL} (or @key{BACKSPACE}), and come back here again, then you ++understand the about the @samp{Space} and @samp{Backspace} keys. So ++now type an @kbd{n}---just one character; don't type the quotes and ++don't type the Return key afterward---to get to the normal start of ++the course. ++@end ifinfo ++ ++@node Help, Help-P, Help-Small-Screen, Getting Started ++@comment node-name, next, previous, up ++@section How to use Info ++ ++You are talking to the program Info, for reading documentation. ++ ++ There are two ways to use Info: from within Emacs or as a ++stand-alone reader that you can invoke from a shell using the command ++@command{info}. ++ ++@cindex node, in Info documents ++ Right now you are looking at one @dfn{Node} of Information. ++A node contains text describing a specific topic at a specific ++level of detail. This node's topic is ``how to use Info''. The mode ++line says that this is node @samp{Help} in the file @file{info}. ++ ++@cindex header of Info node ++ The top line of a node is its @dfn{header}. This node's header ++(look at it now) says that the @samp{Next} node after this one is the ++node called @samp{Help-P}. An advanced Info command lets you go to ++any node whose name you know. In the stand-alone Info reader program, ++the header line shows the names of this node and the Info file as ++well. In Emacs, the header line is displayed with a special typeface, ++and remains at the top of the window all the time even if you scroll ++through the node. ++ ++ Besides a @samp{Next}, a node can have a @samp{Previous} link, or an ++@samp{Up} link, or both. As you can see, this node has all of these ++links. ++ ++@kindex n @r{(Info mode)} ++ Now it is time to move on to the @samp{Next} node, named @samp{Help-P}. ++ ++@format ++>> Type @kbd{n} to move there. Type just one character; ++ do not type the quotes and do not type a @key{RET} afterward. ++@end format ++ ++@noindent ++@samp{>>} in the margin means it is really time to try a command. ++ ++@format ++>> If you are in Emacs and have a mouse, and if you already practiced ++ typing @kbd{n} to get to the next node, click now with the left ++ mouse button on the @samp{Next} link to do the same ``the mouse way''. ++@end format ++ ++@node Help-P, Help-^L, Help, Getting Started ++@comment node-name, next, previous, up ++@section Returning to the Previous node ++ ++@kindex p @r{(Info mode)} ++This node is called @samp{Help-P}. The @samp{Previous} node, as you see, ++is @samp{Help}, which is the one you just came from using the @kbd{n} ++command. Another @kbd{n} command now would take you to the next ++node, @samp{Help-^L}. ++ ++@format ++>> But do not type @kbd{n} yet. First, try the @kbd{p} command, or ++ (in Emacs) click on the @samp{Prev} link. That takes you to ++ the @samp{Previous} node. Then use @kbd{n} to return here. ++@end format ++ ++ If you read this in Emacs, you will see an @samp{Info} item in the ++menu bar, close to its right edge. Clicking the mouse on the ++@samp{Info} menu-bar item opens a menu of commands which include ++@samp{Next} and @samp{Previous} (and also some others which you didn't yet ++learn about). ++ ++ This all probably seems insultingly simple so far, but @emph{please ++don't} start skimming. Things will get complicated soon enough! ++Also, please do not try a new command until you are told it is time ++to. You could make Info skip past an important warning that was ++coming up. ++ ++@format ++>> Now do an @kbd{n}, or (in Emacs) click the middle mouse button on ++ the @samp{Next} link, to get to the node @samp{Help-^L} and learn more. ++@end format ++ ++@node Help-^L, Help-Inv, Help-P, Getting Started ++@comment node-name, next, previous, up ++@section The Space, DEL, B and ^L commands ++ ++ This node's mode line tells you that you are now at node ++@samp{Help-^L}, and the header line tells you that @kbd{p} would get ++you back to @samp{Help-P}. The node's title is highlighted and may be ++underlined as well; it says what the node is about. ++ ++ This is a big node and it does not all fit on your display screen. ++You can tell that there is more that is not visible because you ++can see the text @samp{Top} rather than @samp{All} near the bottom of ++the screen. ++ ++@kindex SPC @r{(Info mode)} ++@kindex DEL @r{(Info mode)} ++@kindex BACKSPACE @r{(Info mode)} ++@findex Info-scroll-up ++@findex Info-scroll-down ++ The @key{SPC}, @key{BACKSPACE} (or @key{DEL})@footnote{The key which ++we call ``Backspace or DEL'' in this manual is labeled differently on ++different keyboards. Look for a key which is a little ways above the ++@key{ENTER} or @key{RET} key and which you normally use outside Emacs ++to erase the character before the cursor, i.e.@: the character you ++typed last. It might be labeled @samp{Backspace} or @samp{<-} or ++@samp{DEL}, or sometimes @samp{Delete}.} and @kbd{b} commands exist to ++allow you to ``move around'' in a node that does not all fit on the ++screen at once. @key{SPC} moves forward, to show what was below the ++bottom of the screen. @key{DEL} or @key{BACKSPACE} moves backward, to ++show what was above the top of the screen (there is not anything above ++the top until you have typed some spaces). ++ ++@format ++>> Now try typing a @key{SPC} (afterward, type a @key{BACKSPACE} to ++ return here). ++@end format ++ ++ When you type the @key{SPC}, the two lines that were at the bottom of ++the screen appear at the top, followed by more lines. @key{DEL} or ++@key{BACKSPACE} takes the two lines from the top and moves them to the ++bottom, @emph{usually}, but if there are not a full screen's worth of ++lines above them they may not make it all the way to the bottom. ++ ++ If you are reading this in Emacs, note that the header line is ++always visible, never scrolling off the display. That way, you can ++always see the @samp{Next}, @samp{Prev}, and @samp{Up} links, and you ++can conveniently go to one of these links at any time by ++clicking the middle mouse button on the link. ++ ++@cindex reading Info documents top to bottom ++@cindex Info documents as tutorials ++ @key{SPC} and @key{DEL} not only move forward and backward through ++the current node. They also move between nodes. @key{SPC} at the end ++of a node moves to the next node; @key{DEL} (or @key{BACKSPACE}) at ++the beginning of a node moves to the previous node. In effect, these ++commands scroll through all the nodes in an Info file as a single ++logical sequence. You can read an entire manual top to bottom by just ++typing @key{SPC}, and move backward through the entire manual from ++bottom to top by typing @key{DEL} (or @key{BACKSPACE}). ++ ++ In this sequence, a node's subnodes appear following their parent. ++If a node has a menu, @key{SPC} takes you into the subnodes listed in ++the menu, one by one. Once you reach the end of a node, and have seen ++all of its subnodes, @key{SPC} takes you to the next node or to the ++parent's next node. ++ ++@kindex PAGEUP @r{(Info mode)} ++@kindex PAGEDOWN @r{(Info mode)} ++ Many keyboards nowadays have two scroll keys labeled @samp{PageUp} ++and @samp{PageDown} (or maybe @samp{Prior} and @samp{Next}). If your ++keyboard has these keys, you can use them to move forward and backward ++through the text of one node, like @key{SPC} and @key{BACKSPACE} (or ++@key{DEL}). However, @key{PAGEUP} and @key{PAGEDOWN} keys never ++scroll beyond the beginning or the end of the current node. ++ ++@kindex C-l @r{(Info mode)} ++ If your screen is ever garbaged, you can tell Info to display it ++again by typing @kbd{C-l} (@kbd{Control-L}---that is, hold down ++@key{CTRL} and type @kbd{L} or @kbd{l}). ++ ++@format ++>> Type @kbd{C-l} now. ++@end format ++ ++@kindex b @r{(Info mode)} ++ To move back to the beginning of the node you are on, you can type ++the @key{BACKSPACE} key (or @key{DEL}) many times. You can also type ++@kbd{b} just once. @kbd{b} stands for ``beginning.'' ++ ++@format ++>> Try that now. (We have put in enough verbiage to push this past ++ the first screenful, but screens are so big nowadays that perhaps it ++ isn't enough. You may need to shrink your Emacs or Info window.) ++ Then come back, by typing @key{SPC} one or more times. ++@end format ++ ++@kindex ? @r{(Info mode)} ++@findex Info-summary ++ You have just learned a considerable number of commands. If you ++want to use one but have trouble remembering which, you should type ++@kbd{?}, which displays a brief list of commands. When you are ++finished looking at the list, make it go away by typing @key{SPC} ++repeatedly. ++ ++@format ++>> Type a @key{?} now. Press @key{SPC} to see consecutive screenfuls of ++ the list until finished. Then type @key{SPC} several times. If ++ you are using Emacs, the help will then go away automatically. ++@end format ++ ++ (If you are using the stand-alone Info reader, type @kbd{C-x 0} to ++return here, that is---press and hold @key{CTRL}, type an @kbd{x}, ++then release @key{CTRL} and @kbd{x}, and press @kbd{0}; that's a zero, ++not the letter ``o''.) ++ ++ From now on, you will encounter large nodes without warning, and ++will be expected to know how to use @key{SPC} and @key{BACKSPACE} to ++move around in them without being told. Since not all terminals have ++the same size screen, it would be impossible to warn you anyway. ++ ++@format ++>> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link, ++ to visit the next node. ++@end format ++ ++@node Help-Inv, Help-M, Help-^L, Getting Started ++@comment node-name, next, previous, up ++@section Invisible text in Emacs Info ++ ++ Before discussing menus, we need to make some remarks that are only ++relevant to users reading Info using Emacs. Users of the stand-alone ++version can skip this node by typing @kbd{]} now. ++ ++@cindex invisible text in Emacs ++ In Emacs, certain text that appears in the stand-alone version is ++normally hidden, technically because it has the @samp{invisibility} ++property. Invisible text is really a part of the text. It becomes ++visible (by default) after killing and yanking, it appears in printed ++output, it gets saved to file just like any other text, and so on. ++Thus it is useful to know it is there. ++ ++@findex visible-mode ++You can make invisible text visible by using the command @kbd{M-x ++visible-mode}. Visible mode is a minor mode, so using the command a ++second time will make the text invisible again. Watch the effects of ++the command on the ``menu'' below and the top line of this node. ++ ++If you prefer to @emph{always} see the invisible text, you can set ++@code{Info-hide-note-references} to @code{nil}. Enabling Visible mode ++permanently is not a real alternative, because Emacs Info also uses ++(although less extensively) another text property that can change the ++text being displayed, the @samp{display} property. Only the ++invisibility property is affected by Visible mode. When, in this ++tutorial, we refer to the @samp{Emacs} behavior, we mean the ++@emph{default} Emacs behavior. ++ ++Now type @kbd{]}, to learn about the @kbd{]} and @kbd{[} commands. ++ ++@menu ++* ]: Help-]. Node telling about ]. ++* stuff: Help-]. Same node. ++* Help-]:: Yet again, same node. ++@end menu ++ ++@node Help-], , , Help-Inv ++@subsection The @kbd{]} and @kbd{[} commands ++ ++If you type @kbd{n} now, you get an error message saying that this ++node has no next node. Similarly, if you type @kbd{p}, the error ++message tells you that there is no previous node. (The exact message ++depends on the Info reader you use.) This is because @kbd{n} and ++@kbd{p} carry you to the next and previous node @emph{at the same ++level}. The present node is contained in a menu (see next) of the ++node you came from, and hence is considered to be at a lower level. ++It is the only node in the previous node's menu (even though it was ++listed three times). Hence it has no next or previous node that ++@kbd{n} or @kbd{p} could move to. ++ ++If you systematically move through a manual by typing @kbd{n}, you run ++the risk of skipping many nodes. You do not run this risk if you ++systematically use @kbd{@key{SPC}}, because, when you scroll to the ++bottom of a node and type another @kbd{@key{SPC}}, then this carries ++you to the following node in the manual @emph{regardless of level}. ++If you immediately want to go to that node, without having to scroll ++to the bottom of the screen first, you can type @kbd{]}. ++ ++Similarly, @kbd{@key{BACKSPACE}} carries you to the preceding node ++regardless of level, after you scrolled to the beginning of the ++present node. If you want to go to the preceding node immediately, ++you can type @kbd{[}. ++ ++For instance, typing this sequence will come back here in three steps: ++@kbd{[ n [}. To do the same backward, type @kbd{] p ]}. ++ ++Now type @kbd{]} to go to the next node and learn about menus. ++ ++@node Help-M, Help-Xref, Help-Inv, Getting Started ++@comment node-name, next, previous, up ++@section Menus and the @kbd{m} command ++ ++@cindex menus in an Info document ++@cindex Info menus ++ With only the @kbd{n} (next), @kbd{p} (previous), @kbd{@key{SPC}}, ++@kbd{@key{BACKSPACE}}, @kbd{]} and @kbd{[} commands for moving between ++nodes, nodes are restricted to a linear sequence. Menus allow a ++branching structure. A menu is a list of other nodes you can move to. ++It is actually just part of the text of the node formatted specially ++so that Info can interpret it. The beginning of a menu is always ++identified by a line which starts with @w{@samp{* Menu:}}. A node ++contains a menu if and only if it has a line in it which starts that ++way. The only menu you can use at any moment is the one in the node ++you are in. To use a menu in any other node, you must move to that ++node first. ++ ++ After the start of the menu, each line that starts with a @samp{*} ++identifies one subtopic. The line usually contains a brief name for ++the subtopic (followed by a @samp{:}, normally hidden in Emacs), the ++name of the node that talks about that subtopic (again, normally ++hidden in Emacs), and optionally some further description of the ++subtopic. Lines in the menu that do not start with a @samp{*} have no ++special meaning---they are only for the human reader's benefit and do ++not define additional subtopics. Here is an example: ++ ++@example ++* Foo: Node about FOO. This tells about FOO. ++@end example ++ ++The subtopic name is Foo, and the node describing it is @samp{Node ++about FOO}. The rest of the line is just for the reader's ++Information. [[ But this line is not a real menu item, simply because ++there is no line above it which starts with @w{@samp{* Menu:}}. Also, ++in a real menu item, the @samp{*} would appear at the very start of ++the line. This is why the ``normally hidden'' text in Emacs, namely ++@samp{: Node about FOO.}, is actually visible in this example, even ++when Visible mode is off.]] ++ ++ When you use a menu to go to another node (in a way that will be ++described soon), what you specify is the subtopic name, the first ++thing in the menu line. Info uses it to find the menu line, extracts ++the node name from it, and goes to that node. The reason that there ++is both a subtopic name and a node name is that the node name must be ++meaningful to the computer and may therefore have to be ugly looking. ++The subtopic name can be chosen just to be convenient for the user to ++specify. Often the node name is convenient for the user to specify ++and so both it and the subtopic name are the same. There is an ++abbreviation for this: ++ ++@example ++* Foo:: This tells about FOO. ++@end example ++ ++@noindent ++This means that the subtopic name and node name are the same; they are ++both @samp{Foo}. (The @samp{::} is normally hidden in Emacs.) ++ ++@format ++>> Now use @key{SPC} to find the menu in this node, then come back to ++ the front with a @kbd{b} and some @key{SPC}s. As you see, a menu is ++ actually visible in its node. If you cannot find a menu in a node ++ by looking at it, then the node does not have a menu and the ++ @kbd{m} command is not available. ++@end format ++ ++If you keep typing @key{SPC} once the menu appears on the screen, it ++will move to another node (the first one in the menu). If that ++happens, type @key{BACKSPACE} to come back. ++ ++@kindex m @r{(Info mode)} ++ The command to go to one of the subnodes is @kbd{m}. This is very ++different from the commands you have used: it is a command that ++prompts you for more input. ++ ++ The Info commands you know do not need additional input; when you ++type one of them, Info processes it instantly and then is ready for ++another command. The @kbd{m} command is different: it needs to know ++the @dfn{name of the subtopic}. Once you have typed @kbd{m}, Info ++tries to read the subtopic name. ++ ++ Now, in the stand-alone Info, look for the line containing many ++dashes near the bottom of the screen. (This is the stand-alone ++equivalent for the mode line in Emacs.) There is one more line ++beneath that one, but usually it is blank. (In Emacs, this is the ++echo area.) When it is blank, Info is ready for a command, such as ++@kbd{n} or @kbd{b} or @key{SPC} or @kbd{m}. If that line contains ++text ending in a colon, it means Info is reading more input for the ++last command. You can't type an Info command then, because Info is ++trying to read input, not commands. You must either give the input ++and finish the command you started, or type @kbd{Control-g} to cancel ++the command. When you have done one of those things, the input entry ++line becomes blank again. Then you can type Info commands again. ++ ++@findex Info-menu ++ The command to go to a subnode via a menu is @kbd{m}. After you type ++the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }. ++You must then type the name of the subtopic you want, and end it with ++a @key{RET}. ++ ++@cindex abbreviating Info subnodes ++ You can abbreviate the subtopic name. If the abbreviation is not ++unique, the first matching subtopic is chosen. Some menus put ++the shortest possible abbreviation for each subtopic name in capital ++letters, so you can see how much you need to type. It does not ++matter whether you use upper case or lower case when you type the ++subtopic. You should not put any spaces at the end, or inside of the ++item name, except for one space where a space appears in the item in ++the menu. ++ ++@cindex completion of Info node names ++ You can also use the @dfn{completion} feature to help enter the ++subtopic name. If you type the @key{TAB} key after entering part of a ++name, it will fill in more of the name---as much as Info can deduce ++from the part you have entered. ++ ++ If you move the cursor to one of the menu subtopic lines, then you do ++not need to type the argument: you just type a @key{RET}, and it ++stands for the subtopic of the line you are on. You can also click ++the middle mouse button directly on the subtopic line to go there. ++ ++Here is a menu to give you a chance to practice. This menu gives you ++three ways of going to one place, Help-FOO: ++ ++@menu ++* Foo: Help-FOO. A node you can visit for fun. ++* Bar: Help-FOO. We have made two ways to get to the same place. ++* Help-FOO:: And yet another! ++@end menu ++ ++(Turn Visible mode on if you are using Emacs.) ++ ++@format ++>> Now type just an @kbd{m} and see what happens: ++@end format ++ ++ Now you are ``inside'' an @kbd{m} command. Commands cannot be used ++now; the next thing you will type must be the name of a subtopic. ++ ++ You can change your mind about doing the @kbd{m} by typing ++@kbd{Control-g}. ++ ++@format ++>> Try that now; notice the bottom line clear. ++@end format ++ ++@format ++>> Then type another @kbd{m}. ++@end format ++ ++@format ++>> Now type @kbd{BAR}, the item name. Do not type @key{RET} yet. ++@end format ++ ++ While you are typing the item name, you can use the @key{DEL} (or ++@key{BACKSPACE}) key to cancel one character at a time if you make a ++mistake. ++ ++@format ++>> Press @key{DEL} to cancel the @samp{R}. You could type another @kbd{R} ++ to replace it. But you do not have to, since @samp{BA} is a valid ++ abbreviation. ++@end format ++ ++@format ++>> Now you are ready to go. Type a @key{RET}. ++@end format ++ ++ After visiting @samp{Help-FOO}, you should return here. ++ ++ Another way to move to the menu subtopic lines and between them is ++to type @key{TAB}. Each time you type a @key{TAB}, you move to the ++next subtopic line. To move to a previous subtopic line in the ++stand-alone reader, type @kbd{M-@key{TAB}}---that is, press and hold ++the @key{META} key and then press @key{TAB}. (On some keyboards, the ++@key{META} key might be labeled @samp{Alt}.) In Emacs Info, type ++@kbd{S-@key{TAB}} to move to a previous subtopic line (press and hold ++the @key{Shift} key and then press @key{TAB}). ++ ++ Once you move cursor to a subtopic line, press @key{RET} to go to ++that subtopic's node. ++ ++@cindex mouse support in Info mode ++@kindex Mouse-2 @r{(Info mode)} ++ If your terminal supports a mouse, you have yet another way of going ++to a subtopic. Move your mouse pointer to the subtopic line, ++somewhere between the beginning @samp{*} and the colon @samp{:} which ++ends the subtopic's brief name. You will see the subtopic's name ++change its appearance (usually, its background color will change), and ++the shape of the mouse pointer will change if your platform supports ++that. After a while, if you leave the mouse on that spot, a small ++window will pop up, saying ``Mouse-2: go to that node,'' or the same ++message may appear at the bottom of the screen. ++ ++ @kbd{Mouse-2} is the second button of your mouse counting from the ++left---the middle button on a 3-button mouse. (On a 2-button mouse, ++you may have to press both buttons together to ``press the middle ++button''.) The message tells you pressing @kbd{Mouse-2} with the ++current position of the mouse pointer (on subtopic in the menu) will ++go to that subtopic. ++ ++@findex Info-mouse-follow-nearest-node ++ More generally, @kbd{Mouse-2} in an Info buffer finds the nearest ++link to another node and goes there. For example, near a cross ++reference it acts like @kbd{f}, in a menu it acts like @kbd{m}, on the ++node's header line it acts like @kbd{n}, @kbd{p}, or @kbd{u}, etc. At ++end of the node's text @kbd{Mouse-2} moves to the next node, or up if ++there's no next node. ++ ++@format ++>> Type @kbd{n} to see more commands. ++@end format ++ ++@node Help-FOO, , , Help-M ++@subsection The @kbd{u} command ++ ++ Congratulations! This is the node @samp{Help-FOO}. It has an @samp{Up} ++pointer @samp{Help-M}, the node you just came from via the @kbd{m} ++command. This is the usual convention---the nodes you reach from a menu ++have @samp{Up} nodes that lead back to the menu. Menus move Down in the ++tree, and @samp{Up} moves Up. @samp{Previous}, on the other hand, is ++usually used to ``stay on the same level but go backwards''. ++ ++@kindex u @r{(Info mode)} ++@findex Info-up ++ You can go back to the node @samp{Help-M} by typing the command ++@kbd{u} for ``Up''. This puts you at the menu subtopic line pointing ++to the subnode that the @kbd{u} command brought you from. (Some Info ++readers may put you at the @emph{front} of the node instead---to get ++back to where you were reading, you have to type some @key{SPC}s.) ++ ++ Another way to go Up is to click @kbd{Mouse-2} on the @samp{Up} ++pointer shown in the header line (provided that you have a mouse). ++ ++@format ++>> Now type @kbd{u} to move back up to @samp{Help-M}. ++@end format ++ ++@node Help-Xref, Help-Int, Help-M, Getting Started ++@comment node-name, next, previous, up ++@section Following Cross-References ++ ++@cindex cross references in Info documents ++ In Info documentation, you will see many @dfn{cross references}. ++Cross references look like this: @xref{Help-Cross, Cross}. That text ++is a real, live cross reference, whose name is @samp{Cross} and which ++points to the node named @samp{Help-Cross}. (The node name is hidden ++in Emacs. Do @kbd{M-x visible-mode} to show or hide it.) ++ ++@kindex f @r{(Info mode)} ++@findex Info-follow-reference ++ You can follow a cross reference by moving the cursor to it and ++press @key{RET}, just as in a menu. In Emacs, you can also click ++@kbd{Mouse-1} on a cross reference to follow it; you can see that the ++cross reference is mouse-sensitive by moving the mouse pointer to the ++reference and watching how the underlying text and the mouse pointer ++change in response. ++ ++ Another way to follow a cross reference is to type @kbd{f} and then ++specify the name of the cross reference (in this case, @samp{Cross}) ++as an argument. For this command, it does not matter where the cursor ++was. If the cursor is on or near a cross reference, @kbd{f} suggests ++that reference name in parentheses as the default; typing @key{RET} ++will follow that reference. However, if you type a different ++reference name, @kbd{f} will follow the other reference which has that ++name. ++ ++@format ++>> Type @kbd{f}, followed by @kbd{Cross}, and then @key{RET}. ++@end format ++ ++ As you enter the reference name, you can use the @key{DEL} (or ++@key{BACKSPACE}) key to edit your input. If you change your mind ++about following any reference, you can use @kbd{Control-g} to cancel ++the command. Completion is available in the @kbd{f} command; you can ++complete among all the cross reference names in the current node by ++typing a @key{TAB}. ++ ++ To get a list of all the cross references in the current node, you ++can type @kbd{?} after an @kbd{f}. The @kbd{f} continues to await a ++cross reference name even after displaying the list, so if you don't ++actually want to follow a reference, you should type a @kbd{Control-g} ++to cancel the @kbd{f}. ++ ++@format ++>> Type @kbd{f?} to get a list of the cross references in this node. Then ++ type a @kbd{Control-g} and see how the @samp{f} gives up. ++@end format ++ ++ The @key{TAB}, @kbd{M-@key{TAB}} and @kbd{S-@key{TAB}} keys, ++which move between menu items in a menu, also move between cross ++references outside of menus. ++ ++ Sometimes a cross reference (or a node) can lead to another file (in ++other words another ``manual''), or, on occasion, even a file on a ++remote machine (although Info files distributed with Emacs or the ++stand-alone Info avoid using remote links). Such a cross reference ++looks like this: @xref{Top,, Overview of Texinfo, texinfo, Texinfo: ++The GNU Documentation Format}. (After following this link, type ++@kbd{l} to get back to this node.) Here the name @samp{texinfo} ++between parentheses refers to the file name. This file name appears ++in cross references and node names if it differs from the current ++file, so you can always know that you are going to be switching to ++another manual and which one. ++ ++However, Emacs normally hides some other text in cross-references. ++If you put your mouse over the cross reference, then the information ++appearing in a separate box (tool tip) or in the echo area will show ++the full cross-reference including the file name and the node name of ++the cross reference. If you have a mouse, just leave it over the ++cross reference @xref{Top,, Overview of Texinfo, texinfo, Texinfo: ++The GNU Documentation Format}, and watch what happens. If you ++always like to have that information visible without having to move ++your mouse over the cross reference, use @kbd{M-x visible-mode}, or ++set @code{Info-hide-note-references} to a value other than @code{t} ++(@pxref{Emacs Info Variables}). ++ ++@format ++>> Now type @kbd{n} to learn more commands. ++@end format ++ ++@node Help-Int, Help-Q, Help-Xref, Getting Started ++@comment node-name, next, previous, up ++@section Some intermediate Info commands ++ ++ The introductory course is almost over; please continue ++a little longer to learn some intermediate-level commands. ++ ++ Most Info files have an index, which is actually a large node ++containing little but a menu. The menu has one menu item for each ++topic listed in the index. (As a special feature, menus for indices ++may also include the line number within the node of the index entry. ++This allows Info readers to go to the exact line of an entry, not just ++the start of the containing node.) ++ ++ You can get to the index from the main menu of the file with the ++@kbd{m} command and the name of the index node; then you can use the ++@kbd{m} command again in the index node to go to the node that ++describes the topic you want. ++ ++ There is also a short-cut Info command, @kbd{i}, which does all of ++that for you. It searches the index for a given topic (a string) and ++goes to the node which is listed in the index for that topic. ++@xref{Search Index}, for a full explanation. ++ ++@kindex l @r{(Info mode)} ++@findex Info-history-back ++@cindex going back in Info history ++ If you have been moving around to different nodes and wish to ++retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will ++do that, one node-step at a time. As you move from node to node, Info ++records the nodes where you have been in a special history list. The ++@kbd{l} command revisits nodes in the history list; each successive ++@kbd{l} command moves one step back through the history. ++ ++@format ++>> Try typing @kbd{p p n} and then three @kbd{l}'s, pausing in between ++to see what each @kbd{l} does. You should wind up right back here. ++@end format ++ ++ Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to ++where @emph{you} last were, whereas @kbd{p} always moves to the node ++which the header says is the @samp{Previous} node (from this node, the ++@samp{Prev} link leads to @samp{Help-Xref}). ++ ++@kindex r @r{(Info mode)} ++@findex Info-history-forward ++@cindex going forward in Info history ++ You can use the @kbd{r} command (@code{Info-history-forward} in Emacs) ++to revisit nodes in the history list in the forward direction, so that ++@kbd{r} will return you to the node you came from by typing @kbd{l}. ++ ++@kindex L @r{(Info mode)} ++@findex Info-history ++@cindex history list of visited nodes ++ The @kbd{L} command (@code{Info-history} in Emacs) creates a virtual ++node that contains a list of all nodes you visited. You can select ++a previously visited node from this menu to revisit it. ++ ++@kindex d @r{(Info mode)} ++@findex Info-directory ++@cindex go to Directory node ++ The @kbd{d} command (@code{Info-directory} in Emacs) gets you ++instantly to the Directory node. This node, which is the first one ++you saw when you entered Info, has a menu which leads (directly or ++indirectly, through other menus), to all the nodes that exist. The ++Directory node lists all the manuals and other Info documents that ++are, or could be, installed on your system. ++ ++@format ++>> Try doing a @kbd{d}, then do an @kbd{l} to return here (yes, ++ @emph{do} return). ++@end format ++ ++@kindex t @r{(Info mode)} ++@findex Info-top-node ++@cindex go to Top node ++ The @kbd{t} command moves to the @samp{Top} node of the manual. ++This is useful if you want to browse the manual's main menu, or select ++some specific top-level menu item. The Emacs command run by @kbd{t} ++is @code{Info-top-node}. ++ ++@format ++>> Now type @kbd{n} to see the last node of the course. ++@end format ++ ++ @xref{Advanced}, for more advanced Info features. ++ ++@c If a menu appears at the end of this node, remove it. ++@c It is an accident of the menu updating command. ++ ++@node Help-Q, , Help-Int, Getting Started ++@comment node-name, next, previous, up ++@section Quitting Info ++ ++@kindex q @r{(Info mode)} ++@findex Info-exit ++@cindex quitting Info mode ++ To get out of Info, back to what you were doing before, type @kbd{q} ++for @dfn{Quit}. This runs @code{Info-exit} in Emacs. ++ ++ This is the end of the basic course on using Info. You have learned ++how to move in an Info document, and how to follow menus and cross ++references. This makes you ready for reading manuals top to bottom, ++as new users should do when they learn a new package. ++ ++ Another set of Info commands is useful when you need to find ++something quickly in a manual---that is, when you need to use a manual ++as a reference rather than as a tutorial. We urge you to learn ++these search commands as well. If you want to do that now, follow this ++cross reference to @ref{Advanced}. ++ ++Yet another set of commands are meant for experienced users; you can ++find them by looking in the Directory node for documentation on Info. ++Finding them will be a good exercise in using Info in the usual ++manner. ++ ++@format ++>> Type @kbd{d} to go to the Info directory node; then type ++ @kbd{mInfo} and Return, to get to the node about Info and ++ see what other help is available. ++@end format ++ ++ ++@node Advanced ++@chapter Advanced Info Commands ++ ++ This chapter describes various advanced Info commands. (If you ++are using a stand-alone Info reader, there are additional commands ++specific to it, which are documented in several chapters of @ref{Top,, ++GNU Info, info-stnd, GNU Info}.) ++ ++@kindex C-q @r{(Info mode)} ++ One advanced command useful with most of the others described here ++is @kbd{C-q}, which ``quotes'' the next character so that it is ++entered literally (@pxref{Inserting Text,,,emacs,The GNU Emacs ++Manual}). For example, pressing @kbd{?} ordinarily brings up a list ++of completion possibilities. If you want to (for example) search for ++an actual @samp{?} character, the simplest way is to insert it using ++@kbd{C-q ?}. This works the same in Emacs and stand-alone Info. ++ ++@menu ++* Search Text:: How to search Info documents. ++* Search Index:: How to search the indices for specific subjects. ++* Go to node:: How to go to a node by name. ++* Choose menu subtopic:: How to choose a menu subtopic by its number. ++* Create Info buffer:: How to create a new Info buffer in Emacs. ++* Emacs Info Variables:: Variables modifying the behavior of Emacs Info. ++@end menu ++ ++ ++@node Search Text, Search Index, , Advanced ++@comment node-name, next, previous, up ++@section @kbd{s} searches Info documents ++ ++@cindex searching Info documents ++@cindex Info document as a reference ++ The commands which move between and inside nodes allow you to read ++the entire manual or its large portions. But what if you need to find ++some information in the manual as fast as you can, and you don't know ++or don't remember in what node to look for it? This need arises when ++you use a manual as a @dfn{reference}, or when it is impractical to ++read the entire manual before you start using the programs it ++describes. ++ ++ Info has powerful searching facilities that let you find things ++quickly. You can search either the manual text or its indices. ++ ++@kindex s @r{(Info mode)} ++@findex Info-search ++ The @kbd{s} command allows you to search a whole Info file for a string. ++It switches to the next node if and when that is necessary. You ++type @kbd{s} followed by the string to search for, terminated by ++@key{RET}. To search for the same string again, just @kbd{s} followed ++by @key{RET} will do. The file's nodes are scanned in the order ++they are in the file, which has no necessary relationship to the ++order that they may be in the tree structure of menus and @samp{next} ++pointers. But normally the two orders are not very different. In any ++case, you can always look at the mode line to find out what node you have ++reached, if the header is not visible (this can happen, because @kbd{s} ++puts your cursor at the occurrence of the string, not at the beginning ++of the node). ++ ++@kindex C-s @r{(Info mode)} ++@kindex C-r @r{(Info mode)} ++@findex isearch ++ Instead of using @kbd{s} in Emacs Info and in the stand-alone Info, ++you can use an incremental search started with @kbd{C-s} or @kbd{C-r}. ++It can search through multiple Info nodes. @xref{Incremental Search,,, ++emacs, The GNU Emacs Manual}. In Emacs, you can disable this behavior ++by setting the variable @code{Info-isearch-search} to @code{nil} ++(@pxref{Emacs Info Variables}). ++ ++@node Search Index, Go to node, Search Text, Advanced ++@comment node-name, next, previous, up ++@section @kbd{i} searches the indices for specific subjects ++ ++@cindex searching Info indices ++@kindex i @r{(Info mode)} ++@findex Info-index ++ Since most topics in the manual should be indexed, you should try ++the index search first before the text search. The @kbd{i} command ++prompts you for a subject and then looks up that subject in the ++indices. If it finds an index entry with the subject you typed, it ++goes to the node to which that index entry points. You should browse ++through that node to see whether the issue you are looking for is ++described there. If it isn't, type @kbd{,} one or more times to go ++through additional index entries which match your subject. ++ ++ The @kbd{i} command and subsequent @kbd{,} commands find all index ++entries which include the string you typed @emph{as a substring}. ++For each match, Info shows in the echo area the full index entry it ++found. Often, the text of the full index entry already gives you ++enough information to decide whether it is relevant to what you are ++looking for, so we recommend that you read what Info shows in the echo ++area before looking at the node it displays. ++ ++ Since @kbd{i} looks for a substring, you can search for subjects even ++if you are not sure how they are spelled in the index. For example, ++suppose you want to find something that is pertinent to commands which ++complete partial input (e.g., when you type @key{TAB}). If you want ++to catch index entries that refer to ``complete,'' ``completion,'' and ++``completing,'' you could type @kbd{icomplet@key{RET}}. ++ ++ Info documents which describe programs should index the commands, ++options, and key sequences that the program provides. If you are ++looking for a description of a command, an option, or a key, just type ++their names when @kbd{i} prompts you for a topic. For example, if you ++want to read the description of what the @kbd{C-l} key does, type ++@kbd{iC-l@key{RET}} literally. ++ ++@findex info-apropos ++@findex index-apropos ++If you aren't sure which manual documents the topic you are looking ++for, try the @kbd{M-x info-apropos} command in Emacs, or the @kbd{M-x ++index-apropos} command in the stand-alone reader. It prompts for ++a string and then looks up that string in all the indices of all the ++Info documents installed on your system. ++ ++@node Go to node, Choose menu subtopic, Search Index, Advanced ++@comment node-name, next, previous, up ++@section @kbd{g} goes to a node by name ++ ++@kindex g @r{(Info mode)} ++@findex Info-goto-node ++@cindex go to a node by name ++ If you know a node's name, you can go there by typing @kbd{g}, the ++name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node ++called @samp{Top} in this file. (This is equivalent to @kbd{t}, see ++@ref{Help-Int}.) @kbd{gGo to node@key{RET}} would come back here. ++ ++ Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. ++But it does allow completion, so you can type @key{TAB} to complete a ++partial node name. ++ ++@cindex go to another Info file ++ To go to a node in another file, you can include the file name in the ++node name by putting it at the front, in parentheses. Thus, ++@kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is ++the node @samp{Top} in the Info file @file{dir}. Likewise, ++@kbd{g(emacs)Top@key{RET}} goes to the top node of the Emacs manual. ++ ++ The node name @samp{*} specifies the whole file. So you can look at ++all of the current file by typing @kbd{g*@key{RET}} or all of any ++other file with @kbd{g(@var{filename})*@key{RET}}. ++ ++@node Choose menu subtopic, Create Info buffer, Go to node, Advanced ++@comment node-name, next, previous, up ++@section @kbd{1}--@kbd{9} choose a menu subtopic by its number ++ ++@kindex 1 @r{through} 9 @r{(Info mode)} ++@findex Info-nth-menu-item ++@cindex select @var{n}'th menu item ++ If you begrudge each character of type-in which your system requires, ++you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, ++@dots{}, @kbd{9}. They are short for the @kbd{m} command together ++with a name of a menu subtopic. @kbd{1} goes through the first item ++in the current node's menu; @kbd{2} goes through the second item, etc. ++In the stand-alone reader, @kbd{0} goes through the last menu item; ++this is so you need not count how many entries are there. ++ ++ If your display supports multiple fonts, colors or underlining, and ++you are using Emacs' Info mode to read Info files, the third, sixth ++and ninth menu items have a @samp{*} that stands out, either in color ++or in some other attribute, such as underline; this makes it easy to ++see at a glance which number to use for an item. ++ ++ Some terminals don't support either multiple fonts, colors or ++underlining. If you need to actually count items, it is better to use ++@kbd{m} instead, and specify the name, or use @key{TAB} to quickly ++move between menu items. ++ ++@node Create Info buffer, Emacs Info Variables, Choose menu subtopic, Advanced ++@comment node-name, next, previous, up ++@section @kbd{M-n} creates a new independent Info buffer in Emacs ++ ++@kindex M-n @r{(Info mode)} ++@findex clone-buffer ++@cindex multiple Info buffers ++ If you are reading Info in Emacs, you can select a new independent ++Info buffer in a new Emacs window by typing @kbd{M-n}. The new buffer ++starts out as an exact copy of the old one, but you will be able to ++move independently between nodes in the two buffers. (In Info mode, ++@kbd{M-n} runs the Emacs command @code{clone-buffer}.) ++ ++ In Emacs Info, you can also produce new Info buffers by giving a ++numeric prefix argument to the @kbd{m} and @kbd{g} commands. @kbd{C-u ++m} and @kbd{C-u g} go to a new node in exactly the same way that ++@kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they ++select in another window. ++ ++ Another way to produce new Info buffers in Emacs is to use a numeric ++prefix argument for the @kbd{C-h i} command (@code{info}) which ++switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i} ++switches to the buffer @samp{*info*<2>}, creating it if necessary. ++ ++@node Emacs Info Variables, , Create Info buffer, Advanced ++@comment node-name, next, previous, up ++@section Emacs Info-mode Variables ++ ++The following variables may modify the behavior of Info-mode in Emacs; ++you may wish to set one or several of these variables interactively, ++or in your init file. @xref{Examining, Examining and Setting ++Variables, Examining and Setting Variables, emacs, The GNU Emacs ++Manual}. The stand-alone Info reader program has its own set of ++variables, described in @ref{Variables,, Manipulating Variables, ++info-stnd, GNU Info}. ++ ++@vtable @code ++@item Info-directory-list ++The list of directories to search for Info files. Each element is a ++string (directory name) or @code{nil} (try default directory). If not ++initialized Info uses the environment variable @env{INFOPATH} to ++initialize it, or @code{Info-default-directory-list} if there is no ++@env{INFOPATH} variable in the environment. ++ ++If you wish to customize the Info directory search list for both Emacs ++Info and stand-alone Info, it is best to set the @env{INFOPATH} ++environment variable, since that applies to both programs. ++ ++@item Info-additional-directory-list ++A list of additional directories to search for Info documentation files. ++These directories are not searched for merging the @file{dir} file. ++ ++@item Info-mode-hook ++Hooks run when @code{Info-mode} is called. By default, it contains ++the hook @code{turn-on-font-lock} which enables highlighting of Info ++files. You can change how the highlighting looks by customizing the ++faces @code{info-node}, @code{info-xref}, @code{info-xref-visited}, ++@code{info-header-xref}, @code{info-header-node}, @code{info-menu-header}, ++@code{info-menu-star}, and @code{info-title-@var{n}} (where @var{n} ++is the level of the section, a number between 1 and 4). To customize ++a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}}, ++where @var{face} is one of the face names listed here. ++ ++@item Info-fontify-maximum-menu-size ++Maximum size of menu to fontify if @code{font-lock-mode} is non-@code{nil}. ++ ++@item Info-fontify-visited-nodes ++If non-@code{nil}, menu items and cross-references pointing to visited ++nodes are displayed in the @code{info-xref-visited} face. ++ ++@item Info-use-header-line ++If non-@code{nil}, Emacs puts in the Info buffer a header line showing ++the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does ++not scroll with the rest of the buffer, making these links always ++visible. ++ ++@item Info-hide-note-references ++As explained in earlier nodes, the Emacs version of Info normally ++hides some text in menus and cross-references. You can completely ++disable this feature, by setting this option to @code{nil}. Setting ++it to a value that is neither @code{nil} nor @code{t} produces an ++intermediate behavior, hiding a limited amount of text, but showing ++all text that could potentially be useful. ++ ++@item Info-scroll-prefer-subnodes ++If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or ++@key{DEL}) keys in a menu visit subnodes of the current node before ++scrolling to its end or beginning, respectively. For example, if the ++node's menu appears on the screen, the next @key{SPC} moves to a ++subnode indicated by the following menu item. Setting this option to ++@code{nil} results in behavior similar to the stand-alone Info reader ++program, which visits the first subnode from the menu only when you ++hit the end of the current node. The default is @code{nil}. ++ ++@item Info-isearch-search ++If non-@code{nil}, isearch in Info searches through multiple nodes. ++ ++@item Info-enable-active-nodes ++When set to a non-@code{nil} value, allows Info to execute Lisp code ++associated with nodes. The Lisp code is executed when the node is ++selected. The Lisp code to be executed should follow the node ++delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like ++this: ++ ++@example ++^_execute: (message "This is an active node!") ++@end example ++@end vtable ++ ++ ++@node Expert Info ++@chapter Info for Experts ++ ++ This chapter explains how to write an Info file by hand. However, ++in most cases, writing a Texinfo file is better, since you can use it ++to make a printed manual or produce other formats, such as HTML and ++DocBook, as well as for generating Info files. ++ ++The @code{makeinfo} command converts a Texinfo file into an Info file; ++@code{texinfo-format-region} and @code{texinfo-format-buffer} are GNU ++Emacs functions that do the same. ++ ++@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU ++Documentation Format}, for how to write a Texinfo file. ++ ++@xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation ++Format}, for how to create an Info file from a Texinfo file. ++ ++@xref{Installing an Info File,,, texinfo, Texinfo: The GNU ++Documentation Format}, for how to install an Info file after you ++have created one. ++ ++However, if you want to edit an Info file manually and install it manually, ++here is how. ++ ++@menu ++* Add:: Describes how to add new nodes to the hierarchy. ++ Also tells what nodes look like. ++* Menus:: How to add to or create menus in Info nodes. ++* Cross-refs:: How to add cross-references to Info nodes. ++* Tags:: How to make tags tables for Info files. ++* Checking:: Checking an Info File. ++@end menu ++ ++@node Add, Menus, , Expert Info ++@comment node-name, next, previous, up ++@section Adding a new node to Info ++ ++To add a new topic to the list in the Info directory, you must: ++ ++@enumerate ++@item ++Create some nodes, in some file, to document that topic. ++@item ++Put that topic in the menu in the directory. @xref{Menus, Menu}. ++@end enumerate ++ ++@cindex node delimiters ++ The new node can live in an existing documentation file, or in a new ++one. It must have a @samp{^_} character before it (invisible to the ++user; this node has one but you cannot see it), and it ends with either ++a @samp{^_}, a @samp{^L} (``formfeed''), or the end of file.@footnote{If ++you put in a @samp{^L} to end a new node, be sure that there is a ++@samp{^_} after it to start the next one, since @samp{^L} cannot ++@emph{start} a node. Also, a nicer way to make a node boundary be a ++page boundary as well is to put a @samp{^L} @emph{right after} the ++@samp{^_}.} ++ ++ The @samp{^_} starting a node must be followed by a newline or a ++@samp{^L} newline, after which comes the node's header line. The ++header line must give the node's name (by which Info finds it), and ++state the names of the @samp{Next}, @samp{Previous}, and @samp{Up} ++nodes (if there are any). As you can see, this node's @samp{Up} node ++is the node @samp{Expert Info}. The @samp{Next} node is @samp{Menus}. ++ ++@cindex node header line format ++@cindex format of node headers ++ The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up} ++may appear in any order, anywhere in the header line, but the ++recommended order is the one in this sentence. Each keyword must be ++followed by a colon, spaces and tabs, and then the appropriate name. ++The name may be terminated with a tab, a comma, or a newline. A space ++does not end it; node names may contain spaces. The case of letters ++in the names is insignificant. ++ ++@cindex node name format ++@cindex Directory node ++ A node name has two forms. A node in the current file is named by ++what appears after the @samp{Node: } in that node's first line. For ++example, this node's name is @samp{Add}. A node in another file is ++named by @samp{(@var{filename})@var{node-within-file}}, as in ++@samp{(info)Add} for this node. If the file name starts with @samp{./}, ++then it is relative to the current directory; otherwise, it is ++relative starting from the standard directory for Info files of your ++site. The name @samp{(@var{filename})Top} can be abbreviated to just ++@samp{(@var{filename})}. By convention, the name @samp{Top} is used ++for the ``highest'' node in any single file---the node whose @samp{Up} ++points out of the file. The @samp{Directory} node is @file{(dir)}, it ++points to a file @file{dir} which holds a large menu listing all the ++Info documents installed on your site. The @samp{Top} node of a ++document file listed in the @samp{Directory} should have an @samp{Up: ++(dir)} in it. ++ ++@cindex unstructured documents ++ The node name @kbd{*} is special: it refers to the entire file. ++Thus, @kbd{g*} shows you the whole current file. The use of the ++node @kbd{*} is to make it possible to make old-fashioned, ++unstructured files into nodes of the tree. ++ ++ The @samp{Node:} name, in which a node states its own name, must not ++contain a file name, since when Info searches for a node, it does not ++expect a file name to be there. The @samp{Next}, @samp{Previous} and ++@samp{Up} names may contain them. In this node, since the @samp{Up} ++node is in the same file, it was not necessary to use one. ++ ++ Note that the nodes in this file have a file name in the header ++line. The file names are ignored by Info, but they serve as comments ++to help identify the node for the user. ++ ++@node Menus, Cross-refs, Add, Expert Info ++@comment node-name, next, previous, up ++@section How to Create Menus ++ ++ Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. ++The @kbd{m} command searches the current node's menu for the topic which it ++reads from the terminal. ++ ++@cindex menu and menu entry format ++ A menu begins with a line starting with @w{@samp{* Menu:}}. The ++rest of the line is a comment. After the starting line, every line ++that begins with a @samp{* } lists a single topic. The name of the ++topic---what the user must type at the @kbd{m}'s command prompt to ++select this topic---comes right after the star and space, and is ++followed by a colon, spaces and tabs, and the name of the node which ++discusses that topic. The node name, like node names following ++@samp{Next}, @samp{Previous} and @samp{Up}, may be terminated with a ++tab, comma, or newline; it may also be terminated with a period. ++ ++ If the node name and topic name are the same, then rather than ++giving the name twice, the abbreviation @samp{* @var{name}::} may be ++used (and should be used, whenever possible, as it reduces the visual ++clutter in the menu). ++ ++ It is considerate to choose the topic names so that they differ ++from each other very near the beginning---this allows the user to type ++short abbreviations. In a long menu, it is a good idea to capitalize ++the beginning of each item name which is the minimum acceptable ++abbreviation for it (a long menu is more than 5 or so entries). ++ ++ The nodes listed in a node's menu are called its ``subnodes,'' and it ++is their ``superior''. They should each have an @samp{Up:} pointing at ++the superior. It is often useful to arrange all or most of the subnodes ++in a sequence of @samp{Next} and @samp{Previous} pointers so that ++someone who wants to see them all need not keep revisiting the Menu. ++ ++ The Info Directory is simply the menu of the node @samp{(dir)Top}---that ++is, node @samp{Top} in file @file{.../info/dir}. You can put new entries ++in that menu just like any other menu. The Info Directory is @emph{not} the ++same as the file directory called @file{info}. It happens that many of ++Info's files live in that file directory, but they do not have to; and ++files in that directory are not automatically listed in the Info ++Directory node. ++ ++ Also, although the Info node graph is claimed to be a ``hierarchy,'' ++in fact it can be @emph{any} directed graph. Shared structures and ++pointer cycles are perfectly possible, and can be used if they are ++appropriate to the meaning to be expressed. There is no need for all ++the nodes in a file to form a connected structure. In fact, this file ++has two connected components. You are in one of them, which is under ++the node @samp{Top}; the other contains the node @samp{Help} which the ++@kbd{h} command goes to. In fact, since there is no garbage ++collector on the node graph, nothing terrible happens if a substructure ++is not pointed to, but such a substructure is rather useless since nobody ++can ever find out that it exists. ++ ++@node Cross-refs, Tags, Menus, Expert Info ++@comment node-name, next, previous, up ++@section Creating Cross References ++ ++@cindex cross reference format ++ A cross reference can be placed anywhere in the text, unlike a menu ++item which must go at the front of a line. A cross reference looks ++like a menu item except that it has @samp{*note} instead of @samp{*}. ++It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are ++so often part of node names. If you wish to enclose a cross reference ++in parentheses, terminate it with a period first. Here are two ++examples of cross references pointers: ++ ++@example ++*Note details: commands. (See *note 3: Full Proof.) ++@end example ++ ++@noindent ++@emph{These are just examples.} The places they ``lead to'' do not ++really exist! ++ ++@menu ++* Help-Cross:: Target of a cross-reference. ++@end menu ++ ++ ++@node Help-Cross, , , Cross-refs ++@subsection The node reached by the cross reference in Info ++ ++ This is the node reached by the cross reference named @samp{Cross}. ++ ++ While this node is specifically intended to be reached by a cross ++reference, most cross references lead to nodes that ``belong'' ++someplace else far away in the structure of an Info document. So you ++cannot expect this node to have a @samp{Next}, @samp{Previous} or ++@samp{Up} links pointing back to where you came from. In general, the ++@kbd{l} (el) command is the only way to get back there. ++ ++@format ++>> Type @kbd{l} to return to the node where the cross reference was. ++@end format ++ ++@node Tags, Checking, Cross-refs, Expert Info ++@comment node-name, next, previous, up ++@section Tags Tables for Info Files ++ ++@cindex tags tables in Info files ++ You can speed up the access to nodes of a large Info file by giving ++it a tags table. Unlike the tags table for a program, the tags table for ++an Info file lives inside the file itself and is used ++automatically whenever Info reads in the file. ++ ++@findex Info-tagify ++ To make a tags table, go to a node in the file using Emacs Info mode and type ++@kbd{M-x Info-tagify}. Then you must use @kbd{C-x C-s} to save the ++file. Info files produced by the @code{makeinfo} command that is part ++of the Texinfo package always have tags tables to begin with. ++ ++@cindex stale tags tables ++@cindex update Info tags table ++ Once the Info file has a tags table, you must make certain it is up ++to date. If you edit an Info file directly (as opposed to editing its ++Texinfo source), and, as a result of deletion of text, any node moves back ++more than a thousand characters in the file from the position ++recorded in the tags table, Info will no longer be able to find that ++node. To update the tags table, use the @code{Info-tagify} command ++again. ++ ++ An Info file tags table appears at the end of the file and looks like ++this: ++ ++@example ++^_^L ++Tag Table: ++File: info, Node: Cross-refs^?21419 ++File: info, Node: Tags^?22145 ++^_ ++End Tag Table ++@end example ++ ++@noindent ++Note that it contains one line per node, and this line contains ++the beginning of the node's header (ending just after the node name), ++a @samp{DEL} character, and the character position in the file of the ++beginning of the node. ++ ++@node Checking, , Tags, Expert Info ++@section Checking an Info File ++ ++When creating an Info file, it is easy to forget the name of a node when ++you are making a pointer to it from another node. If you put in the ++wrong name for a node, this is not detected until someone tries to go ++through the pointer using Info. Verification of the Info file is an ++automatic process which checks all pointers to nodes and reports any ++pointers which are invalid. Every @samp{Next}, @samp{Previous}, and ++@samp{Up} is checked, as is every menu item and every cross reference. In ++addition, any @samp{Next} which does not have a @samp{Previous} pointing ++back is reported. Only pointers within the file are checked, because ++checking pointers to other files would be terribly slow. But those are ++usually few. ++ ++@findex Info-validate ++To check an Info file, do @kbd{M-x Info-validate} while looking at any ++node of the file with Emacs Info mode. ++ ++@node Index ++@unnumbered Index ++ ++This is an alphabetical listing of all the commands, variables, and ++topics discussed in this document. ++ ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 965c1638-01d6-4156-9227-b10418b9d8e8 ++@end ignore +diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi +new file mode 100644 +index 0000000..a059a48 +--- /dev/null ++++ b/doc/misc/mairix-el.texi +@@ -0,0 +1,355 @@ ++\input texinfo.tex ++ ++@setfilename ../../info/mairix-el ++@settitle Emacs Interface for Mairix ++ ++@documentencoding ISO-8859-1 ++ ++@copying ++Copyright @copyright{} 2008, 2009 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 Emacs ++@direntry ++* Mairix: (mairix-el). Emacs interface to the Mairix mail indexer. ++@end direntry ++ ++@titlepage ++@title mairix.el - Mairix interface for Emacs ++ ++@author David Engster ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top ++@top mairix.el - Mairix interface for Emacs ++ ++Mairix is a tool for indexing and searching words in locally stored ++mail. It was written by Richard Curnow and is licensed under the ++GPL. ++ ++@code{mairix.el} is an interface to the mairix search engine. It allows you to ++call mairix with a search term, easily create searches based on the ++currently displayed mail, save regularly used searches in your ++@file{.emacs} for future use and lets you call mairix for updating the ++database. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* About mairix and mairix.el:: About the mairix search engine and mairix.el ++* Configuring mairix:: How to configure mairix ++* Setting up mairix.el:: Set up mairix.el ++* Using mairix.el:: List of interactive functions ++* Extending mairix.el:: Support your favorite mail reader! ++@end menu ++ ++@node About mairix and mairix.el ++@chapter About mairix and mairix.el ++ ++Mairix is a tool for indexing and searching words in locally stored ++mail. It was written by Richard Curnow and is licensed under the ++GPL. Mairix comes with most popular GNU/Linux distributions, but it also ++runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can ++be found at ++@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} ++ ++Though mairix might not be as flexible as other search tools like ++swish++ or namazu, it has the prime advantage of being incredibly fast. ++On current systems, it can easily search through headers and message ++bodies of thousands and thousands of mails in well under a second. ++Building the database necessary for searching might take a minute or ++two, but only has to be done once fully. Afterwards, the updates are ++done incrementally and therefore are really fast, too. Additionally, ++mairix is very easy to set up. ++ ++Mairix presents the search results by either populating a @emph{virtual} ++maildir/MH folder with symlinks which point to the ``real'' message ++files, or if mbox is used, it creates a new mbox file which contains ++copies of the found messages. ++ ++@code{mairix.el} is an interface to the mairix search engine. It allows ++you to call mairix with a search term, easily create searches based on ++the currently displayed mail, save regularly used searches in your ++@file{.emacs} for future use and lets you call mairix for updating the ++database. It also lets you easily create search queries using graphical ++widgets, similar to a customization buffer. ++ ++Currently, @code{mairix.el} is only tested with mbox output together ++with RMail, Gnus, or VM as the Emacs mail program. However, it should ++also work with Maildir or MH, and it should be very easy to integrate ++other Emacs mail programs into @code{mairix.el} ++(@pxref{Extending mairix.el}). ++ ++If you use Gnus with maildir or MH, you should really use the native ++Gnus back end @code{nnmairix} instead, since it is more tightly ++integrated into Gnus and has more features. ++ ++@node Configuring mairix ++@chapter Configuring mairix ++ ++Setting up mairix is easy: simply create a @file{.mairixrc} file with ++(at least) the following entries: ++ ++@example ++# Your mail base folder ++base=~/Mail ++@end example ++ ++This is the base folder for your mails. All the following directories, ++except the one for the database, are relative to this base folder. ++ ++@example ++mbox = ... your mbox files which should be indexed ... ++maildir= ... your maildir folders which should be indexed ... ++mh= ... your nnml/mh folders which should be indexed ... ++@end example ++ ++Specify all your maildir/nnml folders and mbox files (relative to the ++base directory!) you want to index with mairix. Use colons to separate ++different files. See the man-page for @code{mairixrc} for details. ++ ++@example ++mformat = mbox ++database = ... location of database file ... ++@end example ++ ++This chooses @code{mbox} as the output format for the mairix search ++results. Currently, this is the supported format by mairix.el, but ++technically it should be possible to also use maildir or mh; it's just ++not tested (yet). ++ ++You should make sure that you don't accidentally index the search ++results produced by mairix. This can be done by pointing ++`mairix-file-path' to a directory which is surely not indexed by mairix. ++Another possibility is to use something like ++ ++@example ++omit = mairix* ++@end example ++ ++in the @file{.mairixrc} file, and prefix every search file you use with ++``mairix''. ++ ++@example ++database = /home/user/.mairixdatabase ++@end example ++ ++This specifies the name of the database file. Note that this is not ++relative to the @code{base} folder. ++ ++See the man page for @code{mairixrc} for details and further options, ++especially regarding wildcard usage, which may be a little different ++than you are used to. ++ ++Now simply call @code{mairix} to create the index for the first time. ++Note that this may take a few minutes, but every following index will do ++the updates incrementally and hence is very fast. ++ ++@node Setting up mairix.el ++@chapter Setting up mairix.el ++ ++First, put @code{mairix.el} in your Emacs search path and put ++@code{(require 'mairix)} into your @file{.emacs} file. Then, use ++@kbd{M-x customize-group mairix RET} to set your preferences for ++mairix.el. The most important items are @emph{Mairix File Path}, ++@emph{Mairix Search File} and @emph{Mairix Mail Program}. The latter ++specifies which mail program should be used to display the mairix search ++results. Currently, RMail, Gnus with mbox files, and VM are supported. ++If you use Gnus with maildir or mh, use the native Gnus back end ++nnmairix instead. ++ ++If you use another Emacs mail program which is not yet supported by ++mairix.el, it is pretty easy to integrate it. @xref{Extending ++mairix.el}, on how to integrate it into mairix.el. ++ ++Now you should be ready to go. @xref{Using mairix.el}, for the available ++commands. ++ ++@node Using mairix.el ++@chapter Using mairix.el ++ ++There are currently no default key bindings for mairix.el, since those ++should depend on the used mail program and I personally do not use ++RMail, so I wouldn't know which key bindings are reasonable. I hope some ++day this will change and @code{mairix.el} will come with some good ++key bindings for the different mail programs. Feel free to send me your ++suggestions. Until then, define some bindings yourself. Here's a quick ++and dirty solution with global key definitions I currently use, which ++might or might not collide with some other modes. Simply include them ++in your @file{.emacs} and adapt to your needs: ++ ++@lisp ++(global-set-key (kbd "C-c C-o m") 'mairix-search) ++(global-set-key (kbd "C-c C-o w") 'mairix-widget-search) ++(global-set-key (kbd "C-c C-o u") 'mairix-update-database) ++(global-set-key (kbd "C-c C-o f") 'mairix-search-from-this-article) ++(global-set-key (kbd "C-c C-o t") 'mairix-search-thread-this-article) ++(global-set-key (kbd "C-c C-o b") 'mairix-widget-search-based-on-article) ++(global-set-key (kbd "C-c C-o s") 'mairix-save-search) ++(global-set-key (kbd "C-c C-o i") 'mairix-use-saved-search) ++(global-set-key (kbd "C-c C-o e") 'mairix-edit-saved-searches) ++@end lisp ++ ++Here's a description of the available interactive functions: ++ ++@table @code ++ ++@item mairix-search ++@kindex M-x mairix-search ++@findex mairix-search ++@vindex mairix-search-file ++@vindex mairix-file-path ++@vindex mairix-command ++@vindex mairix-search-options ++Call mairix with a search query. You will also be asked if you want to ++include whole threads. The results are saved by mairix in the default ++mail file, which is set through the variable `mairix-search-file', which ++again is prefixed by `mairix-file-path'. The results will then be ++displayed with the chosen mail program. The command used to call mairix ++is specified by the variable `mairix-command', together with the options ++`mairix-search-options'. The latter has the default ``-F'' for making ++searching faster. ++ ++@item mairix-widget-search ++@kindex M-x mairix-widget-search ++@findex mairix-widget-search ++@vindex mairix-widget-fields-list ++Creates a mairix query using graphical widgets. Very handy if you're ++not (yet) familiar with the mairix search syntax. Just call it to see ++how it works. You can then directly call mairix with the search term or ++save it for future use. Since mairix allows almost arbitrary ++combinations of search commands (like ``tc'' for ``to or cc''), you ++might want to include some other fields. This can be easily done by ++modifying `mairix-widget-fields-list'. ++ ++@item mairix-widget-search-based-on-article ++@kindex M-x mairix-widget-search-based-on-article ++@findex mairix-widget-search-based-on-article ++Create a mairix query using graphical widgets, but based on the ++currently displayed article, i.e. the available fields will be filled ++with the current header values. ++ ++@item mairix-search-from-this-article ++@kindex M-x mairix-search-from-this-article ++@findex mairix-search-from-this-article ++Search messages from sender of the current article. This is effectively ++a shortcut for calling @code{mairix-search} with @code{f:current_from}. ++If used with a prefix, include whole threads of the found messages. ++ ++@item mairix-search-thread-this-article ++@kindex M-x mairix-search-thread-this-article ++@findex mairix-search-thread-this-article ++Search thread for the current article. This is effectively a shortcut ++for calling @code{mairix-search} with @code{m:msgid} of the current article and ++enabled threads. ++ ++@item mairix-save-search ++@kindex M-x mairix-save-search ++@findex mairix-save-search ++Save the last search for future use. You will have to specify a name ++for the search and will then be asked if you want to save your saved ++searches in your @file{.emacs}. If you answer with yes, the variable ++@code{mairix-saved-searches} will be saved in the customize section of ++your @file{.emacs}. You can also do this later by using ++`mairix-edit-saved-searches'. ++ ++@item mairix-use-saved-search ++@kindex M-x mairix-use-saved-search ++@findex mairix-use-saved-search ++Call mairix with a previously saved search. You will be asked for the ++name of the saved search (use @kbd{TAB} for completion). ++ ++@item mairix-edit-saved-searches ++@kindex M-x mairix-edit-saved-searches ++@findex mairix-edit-saved-searches ++Edit your current mairix searches. This is a simple major mode for ++editing the contents of the variable @code{mairix-saved-searches}. You ++can edit and delete searches and save them in your @file{.emacs}. You ++can also use this mode to call mairix with one of the saved searches. ++Additionally, you can specify a file name for mairix to use for a ++certain search instead of the default one. This is useful if you want ++to open different searches at the same time, or if you want to regularly ++access certain searches without the need to call mairix. ++ ++@item mairix-edit-saved-searches-customize ++@kindex M-x mairix-edit-saved-searches-customize ++@findex mairix-edit-saved-searches-customize ++Edit the variable @code{mairix-saved-searches} in a normal customization ++buffer. This function exists more or less for historic reasons, but ++maybe you like it. ++ ++@item mairix-update-database ++@kindex M-x mairix-update-database ++@findex mairix-update-database ++@vindex mairix-update-options ++@vindex mairix-synchronous-update ++Call mairix to update the database. Mairix will be called with the ++options `mairix-update-options'; the default is ``-F'' and ``-Q'' to ++make updates as fast as possible. Note that by using these options, ++absolutely no integrity checking is done. If your database somehow gets ++corrupted, simply delete it and update. If `mairix-synchronous-update' ++is nil (the default), mairix will be called in a subprocess so Emacs ++will still be usable while the update is done. ++ ++@end table ++ ++ ++@node Extending mairix.el ++@chapter Extending mairix.el ++ ++Your favorite Emacs mail program is not supported? Shame on me. But ++it is really easy to integrate other mail programs into mairix.el. Just ++do the following: ++ ++@table @strong ++@item Write a display function ++Write a function that displays the mairix search results. This function ++will be called from @code{mairix.el} with the mail file/folder as the ++single argument. For example, the function @code{mairix-rmail-display} ++is currently used for RMail and @code{mairix-gnus-ephemeral-nndoc} is ++used for Gnus. ++ ++@item Write a get-header function ++Write a function that retrieves a header from the currently active mail. ++The single argument for this function is a string with the header name. ++For examples, see @code{mairix-rmail-fetch-field} and ++@code{mairix-gnus-fetch-field} for RMail and Gnus, respectively. ++ ++@item Integrate the functions into mairix.el ++Add your mail program to the defcustom of @code{mairix-mail-program}. ++Then add the functions to @code{mairix-display-functions} and ++@code{mairix-get-mail-header-functions}. ++ ++@item Let me know... ++...so that I can eventually integrate it into future versions of mairix.el. ++@end table ++ ++And that's it! ++ ++ ++ ++@bye ++ ++@ignore ++ arch-tag: cb81470f-e080-489d-bb67-0d11516b63b9 ++@end ignore +diff --git a/doc/misc/makefile.w32-in b/doc/misc/makefile.w32-in +new file mode 100644 +index 0000000..c48df1d +--- /dev/null ++++ b/doc/misc/makefile.w32-in +@@ -0,0 +1,357 @@ ++#### -*- Makefile -*- for documentation other than the Emacs manual. ++ ++# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++# Free Software Foundation, Inc. ++ ++# This file is part of GNU Emacs. ++ ++# GNU Emacs 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. ++ ++# GNU Emacs 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 GNU Emacs. If not, see . ++ ++ ++# Where to find the source code. The source code for Emacs's C kernel is ++# expected to be in $(srcdir)/src, and the source code for Emacs's ++# utility programs is expected to be in $(srcdir)/lib-src. This is ++# set by the configure script's `--srcdir' option. ++srcdir=. ++ ++infodir = $(srcdir)/../../info ++ ++# The makeinfo program is part of the Texinfo distribution. ++MAKEINFO = makeinfo --force ++MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat ++INFO_TARGETS = $(infodir)/ccmode \ ++ $(infodir)/cl $(infodir)/dbus $(infodir)/dired-x \ ++ $(infodir)/ediff $(infodir)/forms $(infodir)/gnus \ ++ $(infodir)/message $(infodir)/sieve $(infodir)/pgg \ ++ $(infodir)/emacs-mime $(infodir)/info $(infodir)/mh-e \ ++ $(infodir)/reftex $(infodir)/sc $(infodir)/vip \ ++ $(infodir)/viper $(infodir)/widget $(infodir)/efaq \ ++ $(infodir)/ada-mode $(infodir)/autotype $(infodir)/calc \ ++ $(infodir)/idlwave $(infodir)/eudc $(infodir)/ebrowse \ ++ $(infodir)/pcl-cvs $(infodir)/woman $(infodir)/eshell \ ++ $(infodir)/org $(infodir)/url $(infodir)/speedbar \ ++ $(infodir)/tramp $(infodir)/ses $(infodir)/smtpmail \ ++ $(infodir)/flymake $(infodir)/newsticker $(infodir)/rcirc \ ++ $(infodir)/erc $(infodir)/remember $(infodir)/nxml-mode \ ++ $(infodir)/epa $(infodir)/mairix-el $(infodir)/sasl \ ++ $(infodir)/auth ++DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dbus.dvi dired-x.dvi \ ++ ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \ ++ sieve.dvi pgg.dvi mh-e.dvi \ ++ reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \ ++ ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \ ++ pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \ ++ speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \ ++ newsticker.dvi rcirc.dvi erc.dvi remember.dvi nxml-mode.dvi \ ++ epa.dvi mairix-el.dvi sasl.dvi auth.dvi ++INFOSOURCES = info.texi ++ ++# The following rule does not work with all versions of `make'. ++.SUFFIXES: .texi .dvi ++.texi.dvi: ++ texi2dvi $< ++ ++TEXI2DVI = texi2dvi ++ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ ++ "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C ++ ++ ++info: $(INFO_TARGETS) ++ ++dvi: $(DVI_TARGETS) ++ ++# Note that all the Info targets build the Info files ++# in srcdir. There is no provision for Info files ++# to exist in the build directory. ++# In a distribution of Emacs, the Info files should be up to date. ++ ++$(infodir)/dir: ++ $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) ++ ++# The following target uses an explicit -o switch to work around ++# the @setfilename directive in info.texi, which is required for ++# the Texinfo distribution. ++# Some Windows ports of makeinfo seem to require -o to come before the ++# texi filename, contrary to GNU standards. ++ ++$(infodir)/info: $(INFOSOURCES) ++ $(MAKEINFO) --no-split -o $@ info.texi ++ ++info.dvi: $(INFOSOURCES) ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/info.texi ++ ++ ++$(infodir)/ccmode: cc-mode.texi ++ $(MAKEINFO) cc-mode.texi ++cc-mode.dvi: cc-mode.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/cc-mode.texi ++ ++$(infodir)/ada-mode: ada-mode.texi ++ $(MAKEINFO) ada-mode.texi ++ada-mode.dvi: ada-mode.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/ada-mode.texi ++ ++$(infodir)/pcl-cvs: pcl-cvs.texi ++ $(MAKEINFO) pcl-cvs.texi ++pcl-cvs.dvi: pcl-cvs.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/pcl-cvs.texi ++ ++$(infodir)/eshell: eshell.texi ++ $(MAKEINFO) eshell.texi ++eshell.dvi: eshell.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/eshell.texi ++ ++$(infodir)/cl: cl.texi ++ $(MAKEINFO) cl.texi ++cl.dvi: cl.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/cl.texi ++ ++$(infodir)/dbus: dbus.texi ++ $(MAKEINFO) dbus.texi ++dbus.dvi: dbus.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/dbus.texi ++ ++$(infodir)/dired-x: dired-x.texi ++ $(MAKEINFO) dired-x.texi ++dired-x.dvi: dired-x.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/dired-x.texi ++ ++$(infodir)/ediff: ediff.texi ++ $(MAKEINFO) ediff.texi ++ediff.dvi: ediff.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/ediff.texi ++ ++$(infodir)/flymake: flymake.texi ++ $(MAKEINFO) flymake.texi ++flymake.dvi: flymake.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/flymake.texi ++ ++$(infodir)/forms: forms.texi ++ $(MAKEINFO) forms.texi ++forms.dvi: forms.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/forms.texi ++ ++# gnus/message/emacs-mime/sieve/pgg are part of Gnus: ++$(infodir)/gnus: gnus.texi ++ $(MAKEINFO) gnus.texi ++gnus.dvi: gnus.texi ++ sed -e "/@iflatex/,/@end iflatex/d" $(srcdir)/gnus.texi > gnustmp.texi ++ $(ENVADD) $(TEXI2DVI) gnustmp.texi ++ cp gnustmp.dvi $*.dvi ++ rm gnustmp.* ++# ++$(infodir)/message: message.texi ++ $(MAKEINFO) message.texi ++message.dvi: message.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/message.texi ++# ++$(infodir)/emacs-mime: emacs-mime.texi ++ $(MAKEINFO) --enable-encoding emacs-mime.texi ++emacs-mime.dvi: emacs-mime.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-mime.texi ++# ++$(infodir)/sieve: sieve.texi ++ $(MAKEINFO) sieve.texi ++sieve.dvi: sieve.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/sieve.texi ++# ++$(infodir)/pgg: pgg.texi ++ $(MAKEINFO) pgg.texi ++pgg.dvi: pgg.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/pgg.texi ++ ++$(infodir)/mh-e: mh-e.texi ++ $(MAKEINFO) mh-e.texi ++mh-e.dvi: mh-e.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/mh-e.texi ++ ++$(infodir)/reftex: reftex.texi ++ $(MAKEINFO) reftex.texi ++reftex.dvi: reftex.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/reftex.texi ++ ++$(infodir)/remember: remember.texi ++ $(MAKEINFO) remember.texi ++remember.dvi: remember.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/remember.texi ++ ++$(infodir)/sasl: sasl.texi ++ $(MAKEINFO) sasl.texi ++sasl.dvi: sasl.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/sasl.texi ++ ++$(infodir)/sc: sc.texi ++ $(MAKEINFO) sc.texi ++sc.dvi: sc.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/sc.texi ++ ++$(infodir)/vip: vip.texi ++ $(MAKEINFO) vip.texi ++vip.dvi: vip.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/vip.texi ++ ++$(infodir)/viper: viper.texi ++ $(MAKEINFO) viper.texi ++viper.dvi: viper.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/viper.texi ++ ++$(infodir)/widget: widget.texi ++ $(MAKEINFO) widget.texi ++widget.dvi: widget.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/widget.texi ++ ++$(infodir)/efaq: faq.texi ++ $(MAKEINFO) faq.texi ++faq.dvi: faq.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/faq.texi ++ ++$(infodir)/autotype: autotype.texi ++ $(MAKEINFO) autotype.texi ++autotype.dvi: autotype.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/autotype.texi ++ ++$(infodir)/calc: calc.texi ++ $(MAKEINFO) calc.texi ++ ++calc.dvi: calc.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/calc.texi ++ ++# This is produced with --no-split to avoid making files whose ++# names clash on DOS 8+3 filesystems ++$(infodir)/idlwave: idlwave.texi ++ $(MAKEINFO) --no-split idlwave.texi ++idlwave.dvi: idlwave.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/idlwave.texi ++ ++$(infodir)/eudc: eudc.texi ++ $(MAKEINFO) eudc.texi ++eudc.dvi: eudc.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/eudc.texi ++ ++$(infodir)/ebrowse: ebrowse.texi ++ $(MAKEINFO) ebrowse.texi ++ebrowse.dvi: ebrowse.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/ebrowse.texi ++ ++$(infodir)/woman: woman.texi ++ $(MAKEINFO) woman.texi ++woman.dvi: woman.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/woman.texi ++ ++$(infodir)/speedbar: speedbar.texi ++ $(MAKEINFO) speedbar.texi ++speedbar.dvi: speedbar.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/speedbar.texi ++ ++$(infodir)/tramp: tramp.texi ++ $(MAKEINFO) tramp.texi ++tramp.dvi: tramp.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/tramp.texi ++ ++$(infodir)/ses: ses.texi ++ $(MAKEINFO) ses.texi ++ses.dvi: ses.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/ses.texi ++ ++$(infodir)/smtpmail: smtpmail.texi ++ $(MAKEINFO) smtpmail.texi ++smtpmail.dvi: smtpmail.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/smtpmail.texi ++ ++$(infodir)/org: org.texi ++ $(MAKEINFO) org.texi ++org.dvi: org.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/org.texi ++ ++$(infodir)/url: url.texi ++ $(MAKEINFO) url.texi ++url.dvi: url.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/url.texi ++ ++$(infodir)/newsticker: newsticker.texi ++ $(MAKEINFO) newsticker.texi ++newsticker.dvi: newsticker.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/newsticker.texi ++ ++$(infodir)/nxml-mode: nxml-mode.texi ++ $(MAKEINFO) nxml-mode.texi ++nxml-mod.dvi: nxml-mode.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/nxml-mode.texi ++ ++$(infodir)/rcirc: rcirc.texi ++ $(MAKEINFO) rcirc.texi ++rcirc.dvi: rcirc.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/rcirc.texi ++ ++$(infodir)/erc: erc.texi ++ $(MAKEINFO) erc.texi ++erc.dvi: erc.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/erc.texi ++ ++$(infodir)/epa: epa.texi ++ $(MAKEINFO) epa.texi ++epa.dvi: epa.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/epa.texi ++ ++$(infodir)/mairix-el: mairix-el.texi ++ $(MAKEINFO) mairix-el.texi ++mairix-el.dvi: mairix-el.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/mairix-el.texi ++ ++$(infodir)/auth: auth.texi ++ $(MAKEINFO) auth.texi ++auth.dvi: auth.texi ++ $(ENVADD) $(TEXI2DVI) $(srcdir)/auth.texi ++ ++mostlyclean: ++ - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* ++ ++clean: mostlyclean ++ - $(DEL) *.dvi ++ - $(DEL) $(infodir)/ccmode* $(infodir)/cl* \ ++ $(infodir)/dbus* $(infodir)/dired-x* \ ++ $(infodir)/ediff* $(infodir)/forms* \ ++ $(infodir)/gnus* $(infodir)/info* \ ++ $(infodir)/message* $(infodir)/mh-e* \ ++ $(infodir)/reftex* $(infodir)/sc* \ ++ $(infodir)/vip* $(infodir)/widget* \ ++ $(infodir)/efaq* $(infodir)/ada-mode* \ ++ $(infodir)/autotype* $(infodir)/calc* \ ++ $(infodir)/idlwave* $(infodir)/eudc* \ ++ $(infodir)/ebrowse* $(infodir)/pcl-cvs* \ ++ $(infodir)/woman* $(infodir)/eshell* \ ++ $(infodir)/speedbar* $(infodir)/tramp* \ ++ $(infodir)/ses* $(infodir)/smtpmail* \ ++ $(infodir)/url* $(infodir)/org* \ ++ $(infodir)/flymake* $(infodir)/newsticker* \ ++ $(infodir)/sieve* $(infodir)/pgg* \ ++ $(infodir)/erc* $(infodir)/rcirc* \ ++ $(infodir)/remember* $(infodir)/nxml-mode* \ ++ $(infodir)/epa* $(infodir)/sasl* \ ++ $(infodir)/mairix-el* $(infodir)/auth* ++ ++distclean: clean ++ - $(DEL) makefile ++ ++maintainer-clean: distclean ++ - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc ++# Don't delete these, because they are outside the current directory. ++# for file in $(INFO_TARGETS); do rm -f $${file}*; done ++ ++ ++# Formerly this directory had texindex.c and getopt.c in it ++# and this makefile built them to make texindex. ++# That caused trouble because this is run entirely in the source directory. ++# Since we expect to get texi2dvi from elsewhere, ++# it is ok to expect texindex from elsewhere also. +diff --git a/doc/misc/message.texi b/doc/misc/message.texi +new file mode 100644 +index 0000000..388745c +--- /dev/null ++++ b/doc/misc/message.texi +@@ -0,0 +1,2446 @@ ++\input texinfo @c -*-texinfo-*- ++ ++@setfilename ../../info/message ++@settitle Message Manual ++@synindex fn cp ++@synindex vr cp ++@synindex pg cp ++@copying ++This file documents Message, the Emacs message composition mode. ++ ++Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, ++2004, 2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* Message: (message). Mail and news composition mode that goes with Gnus. ++@end direntry ++@iftex ++@finalout ++@end iftex ++ ++@titlepage ++@title Message Manual ++ ++@author by Lars Magne Ingebrigtsen ++@page ++ ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@summarycontents ++@contents ++ ++@node Top ++@top Message ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++All message composition from Gnus (both mail and news) takes place in ++Message mode buffers. ++ ++@menu ++* Interface:: Setting up message buffers. ++* Commands:: Commands you can execute in message mode buffers. ++* Variables:: Customizing the message buffers. ++* Compatibility:: Making Message backwards compatible. ++* Appendices:: More technical things. ++* GNU Free Documentation License:: The license for this documentation. ++* Index:: Variable, function and concept index. ++* Key Index:: List of Message mode keys. ++@end menu ++ ++@c Adjust ../Makefile.in if you change the following lines: ++Message is distributed with Gnus. The Gnus distribution ++@c ++corresponding to this manual is Gnus v5.13 ++ ++ ++@node Interface ++@chapter Interface ++ ++When a program (or a person) wants to respond to a message---reply, ++follow up, forward, cancel---the program (or person) should just put ++point in the buffer where the message is and call the required command. ++@code{Message} will then pop up a new @code{message} mode buffer with ++appropriate headers filled out, and the user can edit the message before ++sending it. ++ ++@menu ++* New Mail Message:: Editing a brand new mail message. ++* New News Message:: Editing a brand new news message. ++* Reply:: Replying via mail. ++* Wide Reply:: Responding to all people via mail. ++* Followup:: Following up via news. ++* Canceling News:: Canceling a news article. ++* Superseding:: Superseding a message. ++* Forwarding:: Forwarding a message via news or mail. ++* Resending:: Resending a mail message. ++* Bouncing:: Bouncing a mail message. ++* Mailing Lists:: Send mail to mailing lists. ++@end menu ++ ++You can customize the Message Mode tool bar, see @kbd{M-x ++customize-apropos RET message-tool-bar}. This feature is only available ++in Emacs. ++ ++@node New Mail Message ++@section New Mail Message ++ ++@findex message-mail ++The @code{message-mail} command pops up a new message buffer. ++ ++Two optional parameters are accepted: The first will be used as the ++@code{To} header and the second as the @code{Subject} header. If these ++are @code{nil}, those two headers will be empty. ++ ++ ++@node New News Message ++@section New News Message ++ ++@findex message-news ++The @code{message-news} command pops up a new message buffer. ++ ++This function accepts two optional parameters. The first will be used ++as the @code{Newsgroups} header and the second as the @code{Subject} ++header. If these are @code{nil}, those two headers will be empty. ++ ++ ++@node Reply ++@section Reply ++ ++@findex message-reply ++The @code{message-reply} function pops up a message buffer that's a ++reply to the message in the current buffer. ++ ++@vindex message-reply-to-function ++Message uses the normal methods to determine where replies are to go ++(@pxref{Responses}), but you can change the behavior to suit your needs ++by fiddling with the @code{message-reply-to-function} variable. ++ ++If you want the replies to go to the @code{Sender} instead of the ++@code{From}, you could do something like this: ++ ++@lisp ++(setq message-reply-to-function ++ (lambda () ++ (cond ((equal (mail-fetch-field "from") "somebody") ++ (list (cons 'To (mail-fetch-field "sender")))) ++ (t ++ nil)))) ++@end lisp ++ ++This function will be called narrowed to the head of the article that is ++being replied to. ++ ++As you can see, this function should return a list. In this case, it ++returns @code{((To . "Whom"))} if it has an opinion as to what the To ++header should be. If it does not, it should just return @code{nil}, and ++the normal methods for determining the To header will be used. ++ ++Each list element should be a cons, where the @sc{car} should be the ++name of a header (e.g. @code{Cc}) and the @sc{cdr} should be the header ++value (e.g. @samp{larsi@@ifi.uio.no}). All these headers will be ++inserted into the head of the outgoing mail. ++ ++ ++@node Wide Reply ++@section Wide Reply ++ ++@findex message-wide-reply ++The @code{message-wide-reply} pops up a message buffer that's a wide ++reply to the message in the current buffer. A @dfn{wide reply} is a ++reply that goes out to all people listed in the @code{To}, @code{From} ++(or @code{Reply-to}) and @code{Cc} headers. ++ ++@vindex message-wide-reply-to-function ++Message uses the normal methods to determine where wide replies are to go, ++but you can change the behavior to suit your needs by fiddling with the ++@code{message-wide-reply-to-function}. It is used in the same way as ++@code{message-reply-to-function} (@pxref{Reply}). ++ ++@vindex message-dont-reply-to-names ++Addresses that match the @code{message-dont-reply-to-names} regular ++expression (or list of regular expressions) will be removed from the ++@code{Cc} header. A value of @code{nil} means exclude your name only. ++ ++@vindex message-wide-reply-confirm-recipients ++If @code{message-wide-reply-confirm-recipients} is non-@code{nil} you ++will be asked to confirm that you want to reply to multiple ++recipients. The default is @code{nil}. ++ ++@node Followup ++@section Followup ++ ++@findex message-followup ++The @code{message-followup} command pops up a message buffer that's a ++followup to the message in the current buffer. ++ ++@vindex message-followup-to-function ++Message uses the normal methods to determine where followups are to go, ++but you can change the behavior to suit your needs by fiddling with the ++@code{message-followup-to-function}. It is used in the same way as ++@code{message-reply-to-function} (@pxref{Reply}). ++ ++@vindex message-use-followup-to ++The @code{message-use-followup-to} variable says what to do about ++@code{Followup-To} headers. If it is @code{use}, always use the value. ++If it is @code{ask} (which is the default), ask whether to use the ++value. If it is @code{t}, use the value unless it is @samp{poster}. If ++it is @code{nil}, don't use the value. ++ ++ ++@node Canceling News ++@section Canceling News ++ ++@findex message-cancel-news ++The @code{message-cancel-news} command cancels the article in the ++current buffer. ++ ++@vindex message-cancel-message ++The value of @code{message-cancel-message} is inserted in the body of ++the cancel message. The default is @samp{I am canceling my own ++article.}. ++ ++@cindex Cancel Locks ++@vindex message-insert-canlock ++@cindex canlock ++When Message posts news messages, it inserts @code{Cancel-Lock} ++headers by default. This is a cryptographic header that ensures that ++only you can cancel your own messages, which is nice. The downside ++is that if you lose your @file{.emacs} file (which is where Gnus ++stores the secret cancel lock password (which is generated ++automatically the first time you use this feature)), you won't be ++able to cancel your message. If you want to manage a password yourself, ++you can put something like the following in your @file{~/.gnus.el} file: ++ ++@lisp ++(setq canlock-password "geheimnis" ++ canlock-password-for-verify canlock-password) ++@end lisp ++ ++Whether to insert the header or not is controlled by the ++@code{message-insert-canlock} variable. ++ ++Not many news servers respect the @code{Cancel-Lock} header yet, but ++this is expected to change in the future. ++ ++ ++@node Superseding ++@section Superseding ++ ++@findex message-supersede ++The @code{message-supersede} command pops up a message buffer that will ++supersede the message in the current buffer. ++ ++@vindex message-ignored-supersedes-headers ++Headers matching the @code{message-ignored-supersedes-headers} are ++removed before popping up the new message buffer. The default is@* ++@samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@* ++^Received:\\|^X-From-Line:\\|^X-Trace:\\|^X-Complaints-To:\\|@* ++Return-Path:\\|^Supersedes:\\|^NNTP-Posting-Date:\\|^X-Trace:\\|@* ++^X-Complaints-To:\\|^Cancel-Lock:\\|^Cancel-Key:\\|^X-Hashcash:\\|@* ++^X-Payment:\\|^Approved:}. ++ ++ ++ ++@node Forwarding ++@section Forwarding ++ ++@findex message-forward ++The @code{message-forward} command pops up a message buffer to forward ++the message in the current buffer. If given a prefix, forward using ++news. ++ ++@table @code ++@item message-forward-ignored-headers ++@vindex message-forward-ignored-headers ++All headers that match this regexp will be deleted when forwarding a message. ++ ++@item message-make-forward-subject-function ++@vindex message-make-forward-subject-function ++A list of functions that are called to generate a subject header for ++forwarded messages. The subject generated by the previous function is ++passed into each successive function. ++ ++The provided functions are: ++ ++@table @code ++@item message-forward-subject-author-subject ++@findex message-forward-subject-author-subject ++Source of article (author or newsgroup), in brackets followed by the ++subject. ++ ++@item message-forward-subject-fwd ++Subject of article with @samp{Fwd:} prepended to it. ++@end table ++ ++@item message-wash-forwarded-subjects ++@vindex message-wash-forwarded-subjects ++If this variable is @code{t}, the subjects of forwarded messages have ++the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:}, ++@samp{(fwd)}) removed before the new subject is ++constructed. The default value is @code{nil}. ++ ++@item message-forward-as-mime ++@vindex message-forward-as-mime ++If this variable is @code{t} (the default), forwarded messages are ++included as inline @acronym{MIME} RFC822 parts. If it's @code{nil}, forwarded ++messages will just be copied inline to the new message, like previous, ++non @acronym{MIME}-savvy versions of Gnus would do. ++ ++@item message-forward-before-signature ++@vindex message-forward-before-signature ++If non-@code{nil}, put forwarded message before signature, else after. ++ ++@end table ++ ++ ++@node Resending ++@section Resending ++ ++@findex message-resend ++The @code{message-resend} command will prompt the user for an address ++and resend the message in the current buffer to that address. ++ ++@vindex message-ignored-resent-headers ++Headers that match the @code{message-ignored-resent-headers} regexp will ++be removed before sending the message. ++ ++ ++@node Bouncing ++@section Bouncing ++ ++@findex message-bounce ++The @code{message-bounce} command will, if the current buffer contains a ++bounced mail message, pop up a message buffer stripped of the bounce ++information. A @dfn{bounced message} is typically a mail you've sent ++out that has been returned by some @code{mailer-daemon} as ++undeliverable. ++ ++@vindex message-ignored-bounced-headers ++Headers that match the @code{message-ignored-bounced-headers} regexp ++will be removed before popping up the buffer. The default is ++@samp{^\\(Received\\|Return-Path\\|Delivered-To\\):}. ++ ++ ++@node Mailing Lists ++@section Mailing Lists ++ ++@cindex Mail-Followup-To ++Sometimes while posting to mailing lists, the poster needs to direct ++followups to the post to specific places. The Mail-Followup-To (MFT) ++was created to enable just this. Three example scenarios where this is ++useful: ++ ++@itemize @bullet ++@item ++A mailing list poster can use MFT to express that responses should be ++sent to just the list, and not the poster as well. This will happen ++if the poster is already subscribed to the list. ++ ++@item ++A mailing list poster can use MFT to express that responses should be ++sent to the list and the poster as well. This will happen if the poster ++is not subscribed to the list. ++ ++@item ++If a message is posted to several mailing lists, MFT may also be used ++to direct the following discussion to one list only, because ++discussions that are spread over several lists tend to be fragmented ++and very difficult to follow. ++ ++@end itemize ++ ++Gnus honors the MFT header in other's messages (i.e. while following ++up to someone else's post) and also provides support for generating ++sensible MFT headers for outgoing messages as well. ++ ++@c @menu ++@c * Honoring an MFT post:: What to do when one already exists ++@c * Composing with a MFT header:: Creating one from scratch. ++@c @end menu ++ ++@c @node Composing with a MFT header ++@subsection Composing a correct MFT header automagically ++ ++The first step in getting Gnus to automagically generate a MFT header ++in posts you make is to give Gnus a list of the mailing lists ++addresses you are subscribed to. You can do this in more than one ++way. The following variables would come in handy. ++ ++@table @code ++ ++@vindex message-subscribed-addresses ++@item message-subscribed-addresses ++This should be a list of addresses the user is subscribed to. Its ++default value is @code{nil}. Example: ++@lisp ++(setq message-subscribed-addresses ++ '("ding@@gnus.org" "bing@@noose.org")) ++@end lisp ++ ++@vindex message-subscribed-regexps ++@item message-subscribed-regexps ++This should be a list of regexps denoting the addresses of mailing ++lists subscribed to. Default value is @code{nil}. Example: If you ++want to achieve the same result as above: ++@lisp ++(setq message-subscribed-regexps ++ '("\\(ding@@gnus\\)\\|\\(bing@@noose\\)\\.org") ++@end lisp ++ ++@vindex message-subscribed-address-functions ++@item message-subscribed-address-functions ++This can be a list of functions to be called (one at a time!!) to ++determine the value of MFT headers. It is advisable that these ++functions not take any arguments. Default value is @code{nil}. ++ ++There is a pre-defined function in Gnus that is a good candidate for ++this variable. @code{gnus-find-subscribed-addresses} is a function ++that returns a list of addresses corresponding to the groups that have ++the @code{subscribed} (@pxref{Group Parameters, ,Group Parameters, ++gnus, The Gnus Manual}) group parameter set to a non-@code{nil} value. ++This is how you would do it. ++ ++@lisp ++(setq message-subscribed-address-functions ++ '(gnus-find-subscribed-addresses)) ++@end lisp ++ ++@vindex message-subscribed-address-file ++@item message-subscribed-address-file ++You might be one organized human freak and have a list of addresses of ++all subscribed mailing lists in a separate file! Then you can just ++set this variable to the name of the file and life would be good. ++ ++@end table ++ ++You can use one or more of the above variables. All their values are ++``added'' in some way that works :-) ++ ++Now you are all set. Just start composing a message as you normally do. ++And just send it; as always. Just before the message is sent out, Gnus' ++MFT generation thingy kicks in and checks if the message already has a ++MFT field. If there is one, it is left alone. (Except if it's empty - ++in that case, the field is removed and is not replaced with an ++automatically generated one. This lets you disable MFT generation on a ++per-message basis.) If there is none, then the list of recipient ++addresses (in the To: and Cc: headers) is checked to see if one of them ++is a list address you are subscribed to. If none of them is a list ++address, then no MFT is generated; otherwise, a MFT is added to the ++other headers and set to the value of all addresses in To: and Cc: ++ ++@kindex C-c C-f C-a ++@findex message-generate-unsubscribed-mail-followup-to ++@kindex C-c C-f C-m ++@findex message-goto-mail-followup-to ++Hm. ``So'', you ask, ``what if I send an email to a list I am not ++subscribed to? I want my MFT to say that I want an extra copy.'' (This ++is supposed to be interpreted by others the same way as if there were no ++MFT, but you can use an explicit MFT to override someone else's ++to-address group parameter.) The function ++@code{message-generate-unsubscribed-mail-followup-to} might come in ++handy. It is bound to @kbd{C-c C-f C-a} by default. In any case, you ++can insert a MFT of your own choice; @kbd{C-c C-f C-m} ++(@code{message-goto-mail-followup-to}) will help you get started. ++ ++@c @node Honoring an MFT post ++@subsection Honoring an MFT post ++ ++@vindex message-use-mail-followup-to ++When you followup to a post on a mailing list, and the post has a MFT ++header, Gnus' action will depend on the value of the variable ++@code{message-use-mail-followup-to}. This variable can be one of: ++ ++@table @code ++@item use ++ Always honor MFTs. The To: and Cc: headers in your followup will be ++ derived from the MFT header of the original post. This is the default. ++ ++@item nil ++ Always dishonor MFTs (just ignore the darned thing) ++ ++@item ask ++Gnus will prompt you for an action. ++ ++@end table ++ ++It is considered good netiquette to honor MFT, as it is assumed the ++fellow who posted a message knows where the followups need to go ++better than you do. ++ ++@node Commands ++@chapter Commands ++ ++@menu ++* Buffer Entry:: Commands after entering a Message buffer. ++* Header Commands:: Commands for moving headers or changing headers. ++* Movement:: Moving around in message buffers. ++* Insertion:: Inserting things into message buffers. ++* MIME:: @acronym{MIME} considerations. ++* IDNA:: Non-@acronym{ASCII} domain name considerations. ++* Security:: Signing and encrypting messages. ++* Various Commands:: Various things. ++* Sending:: Actually sending the message. ++* Mail Aliases:: How to use mail aliases. ++* Spelling:: Having Emacs check your spelling. ++@end menu ++ ++ ++@node Buffer Entry ++@section Buffer Entry ++@cindex undo ++@kindex C-_ ++ ++You most often end up in a Message buffer when responding to some other ++message of some sort. Message does lots of handling of quoted text, and ++may remove signatures, reformat the text, or the like---depending on ++which used settings you're using. Message usually gets things right, ++but sometimes it stumbles. To help the user unwind these stumblings, ++Message sets the undo boundary before each major automatic action it ++takes. If you press the undo key (usually located at @kbd{C-_}) a few ++times, you will get back the un-edited message you're responding to. ++ ++ ++@node Header Commands ++@section Header Commands ++ ++@subsection Commands for moving to headers ++ ++These following commands move to the header in question. If it doesn't ++exist, it will be inserted. ++ ++@table @kbd ++ ++@item C-c ? ++@kindex C-c ? ++@findex describe-mode ++Describe the message mode. ++ ++@item C-c C-f C-t ++@kindex C-c C-f C-t ++@findex message-goto-to ++Go to the @code{To} header (@code{message-goto-to}). ++ ++@item C-c C-f C-o ++@kindex C-c C-f C-o ++@findex message-goto-from ++Go to the @code{From} header (@code{message-goto-from}). (The ``o'' ++in the key binding is for Originator.) ++ ++@item C-c C-f C-b ++@kindex C-c C-f C-b ++@findex message-goto-bcc ++Go to the @code{Bcc} header (@code{message-goto-bcc}). ++ ++@item C-c C-f C-w ++@kindex C-c C-f C-w ++@findex message-goto-fcc ++Go to the @code{Fcc} header (@code{message-goto-fcc}). ++ ++@item C-c C-f C-c ++@kindex C-c C-f C-c ++@findex message-goto-cc ++Go to the @code{Cc} header (@code{message-goto-cc}). ++ ++@item C-c C-f C-s ++@kindex C-c C-f C-s ++@findex message-goto-subject ++Go to the @code{Subject} header (@code{message-goto-subject}). ++ ++@item C-c C-f C-r ++@kindex C-c C-f C-r ++@findex message-goto-reply-to ++Go to the @code{Reply-To} header (@code{message-goto-reply-to}). ++ ++@item C-c C-f C-n ++@kindex C-c C-f C-n ++@findex message-goto-newsgroups ++Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}). ++ ++@item C-c C-f C-d ++@kindex C-c C-f C-d ++@findex message-goto-distribution ++Go to the @code{Distribution} header (@code{message-goto-distribution}). ++ ++@item C-c C-f C-f ++@kindex C-c C-f C-f ++@findex message-goto-followup-to ++Go to the @code{Followup-To} header (@code{message-goto-followup-to}). ++ ++@item C-c C-f C-k ++@kindex C-c C-f C-k ++@findex message-goto-keywords ++Go to the @code{Keywords} header (@code{message-goto-keywords}). ++ ++@item C-c C-f C-u ++@kindex C-c C-f C-u ++@findex message-goto-summary ++Go to the @code{Summary} header (@code{message-goto-summary}). ++ ++@item C-c C-f C-i ++@kindex C-c C-f C-i ++@findex message-insert-or-toggle-importance ++This inserts the @samp{Importance:} header with a value of ++@samp{high}. This header is used to signal the importance of the ++message to the receiver. If the header is already present in the ++buffer, it cycles between the three valid values according to RFC ++1376: @samp{low}, @samp{normal} and @samp{high}. ++ ++@item C-c C-f C-a ++@kindex C-c C-f C-a ++@findex message-generate-unsubscribed-mail-followup-to ++Insert a reasonable @samp{Mail-Followup-To:} header ++(@pxref{Mailing Lists}) in a post to an ++unsubscribed list. When making original posts to a mailing list you are ++not subscribed to, you have to type in a @samp{Mail-Followup-To:} header ++by hand. The contents, usually, are the addresses of the list and your ++own address. This function inserts such a header automatically. It ++fetches the contents of the @samp{To:} header in the current mail ++buffer, and appends the current @code{user-mail-address}. ++ ++If the optional argument @code{include-cc} is non-@code{nil}, the ++addresses in the @samp{Cc:} header are also put into the ++@samp{Mail-Followup-To:} header. ++ ++@end table ++ ++@subsection Commands to change headers ++ ++@table @kbd ++ ++@item C-c C-o ++@kindex C-c C-o ++@findex message-sort-headers ++@vindex message-header-format-alist ++Sort headers according to @code{message-header-format-alist} ++(@code{message-sort-headers}). ++ ++@item C-c C-t ++@kindex C-c C-t ++@findex message-insert-to ++Insert a @code{To} header that contains the @code{Reply-To} or ++@code{From} header of the message you're following up ++(@code{message-insert-to}). ++ ++@item C-c C-n ++@kindex C-c C-n ++@findex message-insert-newsgroups ++Insert a @code{Newsgroups} header that reflects the @code{Followup-To} ++or @code{Newsgroups} header of the article you're replying to ++(@code{message-insert-newsgroups}). ++ ++@item C-c C-l ++@kindex C-c C-l ++@findex message-to-list-only ++Send a message to the list only. Remove all addresses but the list ++address from @code{To:} and @code{Cc:} headers. ++ ++@item C-c M-n ++@kindex C-c M-n ++@findex message-insert-disposition-notification-to ++Insert a request for a disposition ++notification. (@code{message-insert-disposition-notification-to}). ++This means that if the recipient support RFC 2298 she might send you a ++notification that she received the message. ++ ++@item M-x message-insert-importance-high ++@kindex M-x message-insert-importance-high ++@findex message-insert-importance-high ++@cindex Importance ++Insert an @samp{Importance} header with a value of @samp{high}, ++deleting headers if necessary. ++ ++@item M-x message-insert-importance-low ++@kindex M-x message-insert-importance-low ++@findex message-insert-importance-low ++@cindex Importance ++Insert an @samp{Importance} header with a value of @samp{low}, deleting ++headers if necessary. ++ ++@item C-c C-f s ++@kindex C-c C-f s ++@findex message-change-subject ++@cindex Subject ++Change the current @samp{Subject} header. Ask for new @samp{Subject} ++header and append @samp{(was: )}. The old subject can be ++stripped on replying, see @code{message-subject-trailing-was-query} ++(@pxref{Message Headers}). ++ ++@item C-c C-f x ++@kindex C-c C-f x ++@findex message-cross-post-followup-to ++@vindex message-cross-post-default ++@vindex message-cross-post-note-function ++@cindex X-Post ++@cindex cross-post ++Set up the @samp{FollowUp-To} header with a target newsgroup for a ++cross-post, add that target newsgroup to the @samp{Newsgroups} header if ++it is not a member of @samp{Newsgroups}, and insert a note in the body. ++If @code{message-cross-post-default} is @code{nil} or if this command is ++called with a prefix-argument, only the @samp{FollowUp-To} header will ++be set but the target newsgroup will not be added to the ++@samp{Newsgroups} header. The function to insert a note is controlled ++by the @code{message-cross-post-note-function} variable. ++ ++@item C-c C-f t ++@kindex C-c C-f t ++@findex message-reduce-to-to-cc ++Replace contents of @samp{To} header with contents of @samp{Cc} or ++@samp{Bcc} header. (Iff @samp{Cc} header is not present, @samp{Bcc} ++header will be used instead.) ++ ++@item C-c C-f w ++@kindex C-c C-f w ++@findex message-insert-wide-reply ++Insert @samp{To} and @samp{Cc} headers as if you were doing a wide ++reply even if the message was not made for a wide reply first. ++ ++@item C-c C-f a ++@kindex C-c C-f a ++@findex message-add-archive-header ++@vindex message-archive-header ++@vindex message-archive-note ++@cindex X-No-Archive ++Insert @samp{X-No-Archive: Yes} in the header and a note in the body. ++The header and the note can be customized using ++@code{message-archive-header} and @code{message-archive-note}. When ++called with a prefix argument, ask for a text to insert. If you don't ++want the note in the body, set @code{message-archive-note} to ++@code{nil}. ++ ++@end table ++ ++ ++@node Movement ++@section Movement ++ ++@table @kbd ++@item C-c C-b ++@kindex C-c C-b ++@findex message-goto-body ++Move to the beginning of the body of the message ++(@code{message-goto-body}). ++ ++@item C-c C-i ++@kindex C-c C-i ++@findex message-goto-signature ++Move to the signature of the message (@code{message-goto-signature}). ++ ++@item C-a ++@kindex C-a ++@findex message-beginning-of-line ++@vindex message-beginning-of-line ++If at beginning of header value, go to beginning of line, else go to ++beginning of header value. (The header value comes after the header ++name and the colon.) This behavior can be disabled by toggling ++the variable @code{message-beginning-of-line}. ++ ++@end table ++ ++ ++@node Insertion ++@section Insertion ++ ++@table @kbd ++ ++@item C-c C-y ++@kindex C-c C-y ++@findex message-yank-original ++Yank the message that's being replied to into the message buffer ++(@code{message-yank-original}). ++ ++@item C-c C-M-y ++@kindex C-c C-M-y ++@findex message-yank-buffer ++Prompt for a buffer name and yank the contents of that buffer into the ++message buffer (@code{message-yank-buffer}). ++ ++@item C-c C-q ++@kindex C-c C-q ++@findex message-fill-yanked-message ++Fill the yanked message (@code{message-fill-yanked-message}). Warning: ++Can severely mess up the yanked text if its quoting conventions are ++strange. You'll quickly get a feel for when it's safe, though. Anyway, ++just remember that @kbd{C-x u} (@code{undo}) is available and you'll be ++all right. ++ ++@item C-c C-w ++@kindex C-c C-w ++@findex message-insert-signature ++Insert a signature at the end of the buffer ++(@code{message-insert-signature}). ++ ++@item C-c M-h ++@kindex C-c M-h ++@findex message-insert-headers ++Insert the message headers (@code{message-insert-headers}). ++ ++@item C-c M-m ++@kindex C-c M-m ++@findex message-mark-inserted-region ++Mark some region in the current article with enclosing tags. See ++@code{message-mark-insert-begin} and @code{message-mark-insert-end}. ++When called with a prefix argument, use slrn style verbatim marks ++(@samp{#v+} and @samp{#v-}). ++ ++@item C-c M-f ++@kindex C-c M-f ++@findex message-mark-insert-file ++Insert a file in the current article with enclosing tags. ++See @code{message-mark-insert-begin} and @code{message-mark-insert-end}. ++When called with a prefix argument, use slrn style verbatim marks ++(@samp{#v+} and @samp{#v-}). ++ ++@end table ++ ++ ++@node MIME ++@section MIME ++@cindex MML ++@cindex MIME ++@cindex multipart ++@cindex attachment ++ ++Message is a @acronym{MIME}-compliant posting agent. The user generally ++doesn't have to do anything to make the @acronym{MIME} happen---Message will ++automatically add the @code{Content-Type} and ++@code{Content-Transfer-Encoding} headers. ++ ++@findex mml-attach-file ++@kindex C-c C-a ++The most typical thing users want to use the multipart things in ++@acronym{MIME} for is to add ``attachments'' to mail they send out. ++This can be done with the @kbd{C-c C-a} command (@kbd{M-x mml-attach-file}), ++which will prompt for a file name and a @acronym{MIME} type. ++ ++@vindex mml-dnd-protocol-alist ++@vindex mml-dnd-attach-options ++If your Emacs supports drag and drop, you can also drop the file in the ++Message buffer. The variable @code{mml-dnd-protocol-alist} specifies ++what kind of action is done when you drop a file into the Message ++buffer. The variable @code{mml-dnd-attach-options} controls which ++@acronym{MIME} options you want to specify when dropping a file. If it ++is a list, valid members are @code{type}, @code{description} and ++@code{disposition}. @code{disposition} implies @code{type}. If it is ++@code{nil}, don't ask for options. If it is @code{t}, ask the user ++whether or not to specify options. ++ ++You can also create arbitrarily complex multiparts using the @acronym{MML} ++language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME ++Manual}). ++ ++@node IDNA ++@section IDNA ++@cindex IDNA ++@cindex internationalized domain names ++@cindex non-ascii domain names ++ ++Message is a @acronym{IDNA}-compliant posting agent. The user ++generally doesn't have to do anything to make the @acronym{IDNA} ++happen---Message will encode non-@acronym{ASCII} domain names in @code{From}, ++@code{To}, and @code{Cc} headers automatically. ++ ++Until @acronym{IDNA} becomes more well known, Message queries you ++whether @acronym{IDNA} encoding of the domain name really should ++occur. Some users might not be aware that domain names can contain ++non-@acronym{ASCII} now, so this gives them a safety net if they accidently ++typed a non-@acronym{ASCII} domain name. ++ ++@vindex message-use-idna ++The @code{message-use-idna} variable control whether @acronym{IDNA} is ++used. If the variable is @code{nil} no @acronym{IDNA} encoding will ++ever happen, if it is set to the symbol @code{ask} the user will be ++queried, and if set to @code{t} (which is the default if @acronym{IDNA} ++is fully available) @acronym{IDNA} encoding happens automatically. ++ ++@findex message-idna-to-ascii-rhs ++If you want to experiment with the @acronym{IDNA} encoding, you can ++invoke @kbd{M-x message-idna-to-ascii-rhs RET} in the message buffer ++to have the non-@acronym{ASCII} domain names encoded while you edit ++the message. ++ ++Note that you must have @uref{http://www.gnu.org/software/libidn/, GNU ++Libidn} installed in order to use this functionality. ++ ++@node Security ++@section Security ++@cindex Security ++@cindex S/MIME ++@cindex PGP ++@cindex PGP/MIME ++@cindex sign ++@cindex encrypt ++@cindex secure ++ ++Using the @acronym{MML} language, Message is able to create digitally ++signed and digitally encrypted messages. Message (or rather ++@acronym{MML}) currently support @acronym{PGP} (RFC 1991), ++@acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}. ++ ++@menu ++* Signing and encryption:: Signing and encrypting commands. ++* Using S/MIME:: Using S/MIME ++* Using PGP/MIME:: Using PGP/MIME ++* PGP Compatibility:: Compatibility with older implementations ++@end menu ++ ++@node Signing and encryption ++@subsection Signing and encrypting commands ++ ++Instructing @acronym{MML} to perform security operations on a ++@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for ++signing and the @kbd{C-c C-m c} key map for encryption, as follows. ++@table @kbd ++ ++@item C-c C-m s s ++@kindex C-c C-m s s ++@findex mml-secure-message-sign-smime ++ ++Digitally sign current message using @acronym{S/MIME}. ++ ++@item C-c C-m s o ++@kindex C-c C-m s o ++@findex mml-secure-message-sign-pgp ++ ++Digitally sign current message using @acronym{PGP}. ++ ++@item C-c C-m s p ++@kindex C-c C-m s p ++@findex mml-secure-message-sign-pgpmime ++ ++Digitally sign current message using @acronym{PGP/MIME}. ++ ++@item C-c C-m c s ++@kindex C-c C-m c s ++@findex mml-secure-message-encrypt-smime ++ ++Digitally encrypt current message using @acronym{S/MIME}. ++ ++@item C-c C-m c o ++@kindex C-c C-m c o ++@findex mml-secure-message-encrypt-pgp ++ ++Digitally encrypt current message using @acronym{PGP}. ++ ++@item C-c C-m c p ++@kindex C-c C-m c p ++@findex mml-secure-message-encrypt-pgpmime ++ ++Digitally encrypt current message using @acronym{PGP/MIME}. ++ ++@item C-c C-m C-n ++@kindex C-c C-m C-n ++@findex mml-unsecure-message ++Remove security related @acronym{MML} tags from message. ++ ++@end table ++ ++These commands do not immediately sign or encrypt the message, they ++merely insert the proper @acronym{MML} secure tag to instruct the ++@acronym{MML} engine to perform that operation when the message is ++actually sent. They may perform other operations too, such as locating ++and retrieving a @acronym{S/MIME} certificate of the person you wish to ++send encrypted mail to. When the mml parsing engine converts your ++@acronym{MML} into a properly encoded @acronym{MIME} message, the secure ++tag will be replaced with either a part or a multipart tag. If your ++message contains other mml parts, a multipart tag will be used; if no ++other parts are present in your message a single part tag will be used. ++This way, message mode will do the Right Thing (TM) with ++signed/encrypted multipart messages. ++ ++Since signing and especially encryption often is used when sensitive ++information is sent, you may want to have some way to ensure that your ++mail is actually signed or encrypted. After invoking the above ++sign/encrypt commands, it is possible to preview the raw article by ++using @kbd{C-u C-c RET P} (@code{mml-preview}). Then you can ++verify that your long rant about what your ex-significant other or ++whomever actually did with that funny looking person at that strange ++party the other night, actually will be sent encrypted. ++ ++@emph{Note!} Neither @acronym{PGP/MIME} nor @acronym{S/MIME} encrypt/signs ++RFC822 headers. They only operate on the @acronym{MIME} object. Keep this ++in mind before sending mail with a sensitive Subject line. ++ ++By default, when encrypting a message, Gnus will use the ++``signencrypt'' mode, which means the message is both signed and ++encrypted. If you would like to disable this for a particular ++message, give the @code{mml-secure-message-encrypt-*} command a prefix ++argument, e.g., @kbd{C-u C-c C-m c p}. ++ ++Actually using the security commands above is not very difficult. At ++least not compared with making sure all involved programs talk with each ++other properly. Thus, we now describe what external libraries or ++programs are required to make things work, and some small general hints. ++ ++@node Using S/MIME ++@subsection Using S/MIME ++ ++@emph{Note!} This section assume you have a basic familiarity with ++modern cryptography, @acronym{S/MIME}, various PKCS standards, OpenSSL and ++so on. ++ ++The @acronym{S/MIME} support in Message (and @acronym{MML}) require ++OpenSSL. OpenSSL performs the actual @acronym{S/MIME} sign/encrypt ++operations. OpenSSL can be found at @uref{http://www.openssl.org/}. ++OpenSSL 0.9.6 and later should work. Version 0.9.5a cannot extract mail ++addresses from certificates, and it insert a spurious CR character into ++@acronym{MIME} separators so you may wish to avoid it if you would like ++to avoid being regarded as someone who send strange mail. (Although by ++sending @acronym{S/MIME} messages you've probably already lost that ++contest.) ++ ++To be able to send encrypted mail, a personal certificate is not ++required. Message (@acronym{MML}) need a certificate for the person to whom you ++wish to communicate with though. You're asked for this when you type ++@kbd{C-c C-m c s}. Currently there are two ways to retrieve this ++certificate, from a local file or from DNS. If you chose a local ++file, it need to contain a X.509 certificate in @acronym{PEM} format. ++If you chose DNS, you're asked for the domain name where the ++certificate is stored, the default is a good guess. To my belief, ++Message (@acronym{MML}) is the first mail agent in the world to support ++retrieving @acronym{S/MIME} certificates from DNS, so you're not ++likely to find very many certificates out there. At least there ++should be one, stored at the domain @code{simon.josefsson.org}. LDAP ++is a more popular method of distributing certificates, support for it ++is planned. (Meanwhile, you can use @code{ldapsearch} from the ++command line to retrieve a certificate into a file and use it.) ++ ++As for signing messages, OpenSSL can't perform signing operations ++without some kind of configuration. Especially, you need to tell it ++where your private key and your certificate is stored. @acronym{MML} ++uses an Emacs interface to OpenSSL, aptly named @code{smime.el}, and it ++contain a @code{custom} group used for this configuration. So, try ++@kbd{M-x customize-group RET smime RET} and look around. ++ ++Currently there is no support for talking to a CA (or RA) to create ++your own certificate. None is planned either. You need to do this ++manually with OpenSSL or using some other program. I used Netscape ++and got a free @acronym{S/MIME} certificate from one of the big CA's on the ++net. Netscape is able to export your private key and certificate in ++PKCS #12 format. Use OpenSSL to convert this into a plain X.509 ++certificate in PEM format as follows. ++ ++@example ++$ openssl pkcs12 -in ns.p12 -clcerts -nodes > key+cert.pem ++@end example ++ ++The @file{key+cert.pem} file should be pointed to from the ++@code{smime-keys} variable. You should now be able to send signed mail. ++ ++@emph{Note!} Your private key is now stored unencrypted in the file, ++so take care in handling it. Storing encrypted keys on the disk are ++supported, and Gnus will ask you for a passphrase before invoking ++OpenSSL. Read the OpenSSL documentation for how to achieve this. If ++you use unencrypted keys (e.g., if they are on a secure storage, or if ++you are on a secure single user machine) simply press @code{RET} at ++the passphrase prompt. ++ ++@node Using PGP/MIME ++@subsection Using PGP/MIME ++ ++@acronym{PGP/MIME} requires an external OpenPGP implementation, such ++as @uref{http://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP ++implementations such as PGP 2.x and PGP 5.x are also supported. One ++Emacs interface to the PGP implementations, PGG (@pxref{Top, ,PGG, ++pgg, PGG Manual}), is included, but Mailcrypt and Florian Weimer's ++@code{gpg.el} are also supported. @xref{PGP Compatibility}. ++ ++@cindex gpg-agent ++Message internally calls GnuPG (the @command{gpg} command) to perform ++data encryption, and in certain cases (decrypting or signing for ++example), @command{gpg} requires user's passphrase. Currently the ++recommended way to supply your passphrase to @command{gpg} is to use the ++@command{gpg-agent} program. ++ ++To use @command{gpg-agent} in Emacs, you need to run the following ++command from the shell before starting Emacs. ++ ++@example ++eval `gpg-agent --daemon` ++@end example ++ ++This will invoke @command{gpg-agent} and set the environment variable ++@code{GPG_AGENT_INFO} to allow @command{gpg} to communicate with it. ++It might be good idea to put this command in your @file{.xsession} or ++@file{.bash_profile}. @xref{Invoking GPG-AGENT, , , gnupg, Using the ++GNU Privacy Guard}. ++ ++Once your @command{gpg-agent} is set up, it will ask you for a ++passphrase as needed for @command{gpg}. Under the X Window System, ++you will see a new passphrase input dialog appear. The dialog is ++provided by PIN Entry (the @command{pinentry} command), and as of ++version 0.7.2, @command{pinentry} cannot cooperate with Emacs on a ++single tty. So, if you are using a text console, you may need to put ++a passphrase into gpg-agent's cache beforehand. The following command ++does the trick. ++ ++@example ++gpg --use-agent --sign < /dev/null > /dev/null ++@end example ++ ++The Lisp variable @code{pgg-gpg-use-agent} controls whether to use ++@command{gpg-agent}. See also @xref{Caching passphrase, , , pgg, The ++PGG Manual}. ++ ++ ++@node PGP Compatibility ++@subsection Compatibility with older implementations ++ ++@vindex gpg-temp-directory ++Note, if you are using the @code{gpg.el} you must make sure that the ++directory specified by @code{gpg-temp-directory} have permissions ++0700. ++ ++Creating your own key is described in detail in the documentation of ++your PGP implementation, so we refer to it. ++ ++If you have imported your old PGP 2.x key into GnuPG, and want to send ++signed and encrypted messages to your fellow PGP 2.x users, you'll ++discover that the receiver cannot understand what you send. One ++solution is to use PGP 2.x instead (i.e., if you use @code{pgg}, set ++@code{pgg-default-scheme} to @code{pgp}). If you do want to use ++GnuPG, you can use a compatibility script called @code{gpg-2comp} ++available from ++@uref{http://muppet.faveve.uni-stuttgart.de/~gero/gpg-2comp/}. You ++could also convince your fellow PGP 2.x users to convert to GnuPG. ++@vindex mml-signencrypt-style-alist ++As a final workaround, you can make the sign and encryption work in ++two steps; separately sign, then encrypt a message. If you would like ++to change this behavior you can customize the ++@code{mml-signencrypt-style-alist} variable. For example: ++ ++@lisp ++(setq mml-signencrypt-style-alist '(("smime" separate) ++ ("pgp" separate) ++ ("pgpauto" separate) ++ ("pgpmime" separate))) ++@end lisp ++ ++This causes to sign and encrypt in two passes, thus generating a ++message that can be understood by PGP version 2. ++ ++(Refer to @uref{http://www.gnupg.org/gph/en/pgp2x.html} for more ++information about the problem.) ++ ++@node Various Commands ++@section Various Commands ++ ++@table @kbd ++ ++@item C-c C-r ++@kindex C-c C-r ++@findex message-caesar-buffer-body ++Caesar rotate (aka. rot13) the current message ++(@code{message-caesar-buffer-body}). If narrowing is in effect, just ++rotate the visible portion of the buffer. A numerical prefix says how ++many places to rotate the text. The default is 13. ++ ++@item C-c C-e ++@kindex C-c C-e ++@findex message-elide-region ++@vindex message-elide-ellipsis ++Elide the text between point and mark (@code{message-elide-region}). ++The text is killed and replaced with the contents of the variable ++@code{message-elide-ellipsis}. The default value is to use an ellipsis ++(@samp{[...]}). ++ ++@item C-c M-k ++@kindex C-c M-k ++@findex message-kill-address ++Kill the address under point. ++ ++@item C-c C-z ++@kindex C-c C-z ++@findex message-kill-to-signature ++Kill all the text up to the signature, or if that's missing, up to the ++end of the message (@code{message-kill-to-signature}). ++ ++@item C-c C-v ++@kindex C-c C-v ++@findex message-delete-not-region ++Delete all text in the body of the message that is outside the region ++(@code{message-delete-not-region}). ++ ++@item M-RET ++@kindex M-RET ++@findex message-newline-and-reformat ++Insert four newlines, and then reformat if inside quoted text. ++ ++Here's an example: ++ ++@example ++> This is some quoted text. And here's more quoted text. ++@end example ++ ++If point is before @samp{And} and you press @kbd{M-RET}, you'll get: ++ ++@example ++> This is some quoted text. ++ ++* ++ ++> And here's more quoted text. ++@end example ++ ++@samp{*} says where point will be placed. ++ ++@item C-c M-r ++@kindex C-c M-r ++@findex message-rename-buffer ++Rename the buffer (@code{message-rename-buffer}). If given a prefix, ++prompt for a new buffer name. ++ ++@item TAB ++@kindex TAB ++@findex message-tab ++@vindex message-tab-body-function ++If @code{message-tab-body-function} is non-@code{nil}, execute the ++function it specifies. Otherwise use the function bound to @kbd{TAB} in ++@code{text-mode-map} or @code{global-map}. ++ ++@end table ++ ++ ++@node Sending ++@section Sending ++ ++@table @kbd ++@item C-c C-c ++@kindex C-c C-c ++@findex message-send-and-exit ++Send the message and bury the current buffer ++(@code{message-send-and-exit}). ++ ++@item C-c C-s ++@kindex C-c C-s ++@findex message-send ++Send the message (@code{message-send}). ++ ++@item C-c C-d ++@kindex C-c C-d ++@findex message-dont-send ++Bury the message buffer and exit (@code{message-dont-send}). ++ ++@item C-c C-k ++@kindex C-c C-k ++@findex message-kill-buffer ++Kill the message buffer and exit (@code{message-kill-buffer}). ++ ++@end table ++ ++ ++ ++@node Mail Aliases ++@section Mail Aliases ++@cindex mail aliases ++@cindex aliases ++@cindex completion ++@cindex ecomplete ++ ++@vindex message-mail-alias-type ++The @code{message-mail-alias-type} variable controls what type of mail ++alias expansion to use. Currently two forms are supported: ++@code{mailabbrev} and @code{ecomplete}. If this variable is ++@code{nil}, no mail alias expansion will be performed. ++ ++@code{mailabbrev} works by parsing the @file{/etc/mailrc} and ++@file{~/.mailrc} files. These files look like: ++ ++@example ++alias lmi "Lars Magne Ingebrigtsen " ++alias ding "ding@@ifi.uio.no (ding mailing list)" ++@end example ++ ++After adding lines like this to your @file{~/.mailrc} file, you should ++be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so ++on) headers and press @kbd{SPC} to expand the alias. ++ ++No expansion will be performed upon sending of the message---all ++expansions have to be done explicitly. ++ ++If you're using @code{ecomplete}, all addresses from @code{To} and ++@code{Cc} headers will automatically be put into the ++@file{~/.ecompleterc} file. When you enter text in the @code{To} and ++@code{Cc} headers, @code{ecomplete} will check out the values stored ++there and ``electrically'' say what completions are possible. To ++choose one of these completions, use the @kbd{M-n} command to move ++down to the list. Use @kbd{M-n} and @kbd{M-p} to move down and up the ++list, and @kbd{RET} to choose a completion. ++ ++@node Spelling ++@section Spelling ++@cindex spelling ++@findex ispell-message ++ ++There are two popular ways to have Emacs spell-check your messages: ++@code{ispell} and @code{flyspell}. @code{ispell} is the older and ++probably more popular package. You typically first write the message, ++and then run the entire thing through @code{ispell} and fix all the ++typos. To have this happen automatically when you send a message, put ++something like the following in your @file{.emacs} file: ++ ++@lisp ++(add-hook 'message-send-hook 'ispell-message) ++@end lisp ++ ++@vindex ispell-message-dictionary-alist ++If you're in the habit of writing in different languages, this can be ++controlled by the @code{ispell-message-dictionary-alist} variable: ++ ++@lisp ++(setq ispell-message-dictionary-alist ++ '(("^Newsgroups:.*\\bde\\." . "deutsch8") ++ (".*" . "default"))) ++@end lisp ++ ++@code{ispell} depends on having the external @samp{ispell} command ++installed. ++ ++The other popular method is using @code{flyspell}. This package checks ++your spelling while you're writing, and marks any mis-spelled words in ++various ways. ++ ++To use @code{flyspell}, put something like the following in your ++@file{.emacs} file: ++ ++@lisp ++(defun my-message-setup-routine () ++ (flyspell-mode 1)) ++(add-hook 'message-setup-hook 'my-message-setup-routine) ++@end lisp ++ ++@code{flyspell} depends on having the external @samp{ispell} command ++installed. ++ ++ ++@node Variables ++@chapter Variables ++ ++@menu ++* Message Headers:: General message header stuff. ++* Mail Headers:: Customizing mail headers. ++* Mail Variables:: Other mail variables. ++* News Headers:: Customizing news headers. ++* News Variables:: Other news variables. ++* Insertion Variables:: Customizing how things are inserted. ++* Various Message Variables:: Other message variables. ++* Sending Variables:: Variables for sending. ++* Message Buffers:: How Message names its buffers. ++* Message Actions:: Actions to be performed when exiting. ++@end menu ++ ++ ++@node Message Headers ++@section Message Headers ++ ++Message is quite aggressive on the message generation front. It has to ++be---it's a combined news and mail agent. To be able to send combined ++messages, it has to generate all headers itself (instead of letting the ++mail/news system do it) to ensure that mail and news copies of messages ++look sufficiently similar. ++ ++@table @code ++ ++@item message-generate-headers-first ++@vindex message-generate-headers-first ++If @code{t}, generate all required headers before starting to ++compose the message. This can also be a list of headers to generate: ++ ++@lisp ++(setq message-generate-headers-first ++ '(References)) ++@end lisp ++ ++@vindex message-required-headers ++The variables @code{message-required-headers}, ++@code{message-required-mail-headers} and ++@code{message-required-news-headers} specify which headers are ++required. ++ ++Note that some headers will be removed and re-generated before posting, ++because of the variable @code{message-deletable-headers} (see below). ++ ++@item message-draft-headers ++@vindex message-draft-headers ++When running Message from Gnus, the message buffers are associated ++with a draft group. @code{message-draft-headers} says which headers ++should be generated when a draft is written to the draft group. ++ ++@item message-from-style ++@vindex message-from-style ++Specifies how @code{From} headers should look. There are four valid ++values: ++ ++@table @code ++@item nil ++Just the address---@samp{king@@grassland.com}. ++ ++@item parens ++@samp{king@@grassland.com (Elvis Parsley)}. ++ ++@item angles ++@samp{Elvis Parsley }. ++ ++@item default ++Look like @code{angles} if that doesn't require quoting, and ++@code{parens} if it does. If even @code{parens} requires quoting, use ++@code{angles} anyway. ++ ++@end table ++ ++@item message-deletable-headers ++@vindex message-deletable-headers ++Headers in this list that were previously generated by Message will be ++deleted before posting. Let's say you post an article. Then you decide ++to post it again to some other group, you naughty boy, so you jump back ++to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and ++ship it off again. By default, this variable makes sure that the old ++generated @code{Message-ID} is deleted, and a new one generated. If ++this isn't done, the entire empire would probably crumble, anarchy would ++prevail, and cats would start walking on two legs and rule the world. ++Allegedly. ++ ++@item message-default-headers ++@vindex message-default-headers ++This string is inserted at the end of the headers in all message ++buffers. ++ ++@item message-subject-re-regexp ++@vindex message-subject-re-regexp ++@cindex Aw ++@cindex Sv ++@cindex Re ++Responses to messages have subjects that start with @samp{Re: }. This ++is @emph{not} an abbreviation of the English word ``response'', but is ++Latin, and means ``in response to''. Some illiterate nincompoops have ++failed to grasp this fact, and have ``internationalized'' their software ++to use abominations like @samp{Aw: } (``antwort'') or @samp{Sv: } ++(``svar'') instead, which is meaningless and evil. However, you may ++have to deal with users that use these evil tools, in which case you may ++set this variable to a regexp that matches these prefixes. Myself, I ++just throw away non-compliant mail. ++ ++Here's an example of a value to deal with these headers when ++responding to a message: ++ ++@lisp ++(setq message-subject-re-regexp ++ (concat ++ "^[ \t]*" ++ "\\(" ++ "\\(" ++ "[Aa][Nn][Tt][Ww]\\.?\\|" ; antw ++ "[Aa][Ww]\\|" ; aw ++ "[Ff][Ww][Dd]?\\|" ; fwd ++ "[Oo][Dd][Pp]\\|" ; odp ++ "[Rr][Ee]\\|" ; re ++ "[Rr][\311\351][Ff]\\.?\\|" ; ref ++ "[Ss][Vv]" ; sv ++ "\\)" ++ "\\(\\[[0-9]*\\]\\)" ++ "*:[ \t]*" ++ "\\)" ++ "*[ \t]*" ++ )) ++@end lisp ++ ++@item message-subject-trailing-was-query ++@vindex message-subject-trailing-was-query ++@vindex message-subject-trailing-was-ask-regexp ++@vindex message-subject-trailing-was-regexp ++Controls what to do with trailing @samp{(was: )} in subject ++lines. If @code{nil}, leave the subject unchanged. If it is the symbol ++@code{ask}, query the user what to do. In this case, the subject is ++matched against @code{message-subject-trailing-was-ask-regexp}. If ++@code{message-subject-trailing-was-query} is @code{t}, always strip the ++trailing old subject. In this case, ++@code{message-subject-trailing-was-regexp} is used. ++ ++@item message-alternative-emails ++@vindex message-alternative-emails ++Regexp matching alternative email addresses. The first address in the ++To, Cc or From headers of the original article matching this variable is ++used as the From field of outgoing messages, replacing the default From ++value. ++ ++For example, if you have two secondary email addresses john@@home.net ++and john.doe@@work.com and want to use them in the From field when ++composing a reply to a message addressed to one of them, you could set ++this variable like this: ++ ++@lisp ++(setq message-alternative-emails ++ (regexp-opt '("john@@home.net" "john.doe@@work.com"))) ++@end lisp ++ ++This variable has precedence over posting styles and anything that runs ++off @code{message-setup-hook}. ++ ++@item message-allow-no-recipients ++@vindex message-allow-no-recipients ++Specifies what to do when there are no recipients other than ++@code{Gcc} or @code{Fcc}. If it is @code{always}, the posting is ++allowed. If it is @code{never}, the posting is not allowed. If it is ++@code{ask} (the default), you are prompted. ++ ++@item message-hidden-headers ++@vindex message-hidden-headers ++A regexp, a list of regexps, or a list where the first element is ++@code{not} and the rest are regexps. It says which headers to keep ++hidden when composing a message. ++ ++@lisp ++(setq message-hidden-headers ++ '(not "From" "Subject" "To" "Cc" "Newsgroups")) ++@end lisp ++ ++Headers are hidden using narrowing, you can use @kbd{M-x widen} to ++expose them in the buffer. ++ ++@item message-header-synonyms ++@vindex message-header-synonyms ++A list of lists of header synonyms. E.g., if this list contains a ++member list with elements @code{Cc} and @code{To}, then ++@code{message-carefully-insert-headers} will not insert a @code{To} ++header when the message is already @code{Cc}ed to the recipient. ++ ++@end table ++ ++ ++@node Mail Headers ++@section Mail Headers ++ ++@table @code ++@item message-required-mail-headers ++@vindex message-required-mail-headers ++@xref{News Headers}, for the syntax of this variable. It is ++@code{(From Subject Date (optional . In-Reply-To) Message-ID ++(optional . User-Agent))} by default. ++ ++@item message-ignored-mail-headers ++@vindex message-ignored-mail-headers ++Regexp of headers to be removed before mailing. The default is@* ++@samp{^[GF]cc:\\|^Resent-Fcc:\\|^Xref:\\|^X-Draft-From:\\|@* ++^X-Gnus-Agent-Meta-Information:}. ++ ++@item message-default-mail-headers ++@vindex message-default-mail-headers ++This string is inserted at the end of the headers in all message ++buffers that are initialized as mail. ++ ++@item message-generate-hashcash ++@vindex message-generate-hashcash ++Variable that indicates whether @samp{X-Hashcash} headers ++should be computed for the message. @xref{Hashcash, ,Hashcash,gnus, ++The Gnus Manual}. If @code{opportunistic}, only generate the headers ++when it doesn't lead to the user having to wait. ++ ++@end table ++ ++ ++@node Mail Variables ++@section Mail Variables ++ ++@table @code ++@item message-send-mail-function ++@vindex message-send-mail-function ++@findex message-send-mail-function ++@findex message-send-mail-with-sendmail ++@findex message-send-mail-with-mh ++@findex message-send-mail-with-qmail ++@findex message-smtpmail-send-it ++@findex smtpmail-send-it ++@findex feedmail-send-it ++@findex message-send-mail-with-mailclient ++Function used to send the current buffer as mail. The default is ++@code{message-send-mail-with-sendmail}, or @code{smtpmail-send-it} ++according to the system. Other valid values include ++@code{message-send-mail-with-mailclient}, ++@code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail}, ++@code{message-smtpmail-send-it} and @code{feedmail-send-it}. ++ ++The function ++@code{message-send-mail-with-sendmail} pipes your article to the ++@code{sendmail} binary for further queuing and sending. When your local ++system is not configured for sending mail using @code{sendmail}, and you ++have access to a remote @acronym{SMTP} server, you can set ++@code{message-send-mail-function} to @code{smtpmail-send-it} and make ++sure to setup the @code{smtpmail} package correctly. An example: ++ ++@lisp ++(setq message-send-mail-function 'smtpmail-send-it ++ smtpmail-default-smtp-server "YOUR SMTP HOST") ++@end lisp ++ ++To the thing similar to this, there is ++@code{message-smtpmail-send-it}. It is useful if your @acronym{ISP} ++requires the @acronym{POP}-before-@acronym{SMTP} authentication. ++@xref{POP before SMTP, , POP before SMTP, gnus, The Gnus Manual}. ++ ++@item message-mh-deletable-headers ++@vindex message-mh-deletable-headers ++Most versions of MH doesn't like being fed messages that contain the ++headers in this variable. If this variable is non-@code{nil} (which is ++the default), these headers will be removed before mailing when sending ++messages via MH. Set it to @code{nil} if your MH can handle these ++headers. ++ ++@item message-qmail-inject-program ++@vindex message-qmail-inject-program ++@cindex qmail ++Location of the qmail-inject program. ++ ++@item message-qmail-inject-args ++@vindex message-qmail-inject-args ++Arguments passed to qmail-inject programs. ++This should be a list of strings, one string for each argument. It ++may also be a function. ++ ++For e.g., if you wish to set the envelope sender address so that bounces ++go to the right place or to deal with listserv's usage of that address, you ++might set this variable to @code{'("-f" "you@@some.where")}. ++ ++@item message-sendmail-f-is-evil ++@vindex message-sendmail-f-is-evil ++@cindex sendmail ++Non-@code{nil} means don't add @samp{-f username} to the sendmail ++command line. Doing so would be even more evil than leaving it out. ++ ++@item message-sendmail-envelope-from ++@vindex message-sendmail-envelope-from ++When @code{message-sendmail-f-is-evil} is @code{nil}, this specifies ++the address to use in the @acronym{SMTP} envelope. If it is ++@code{nil}, use @code{user-mail-address}. If it is the symbol ++@code{header}, use the @samp{From} header of the message. ++ ++@item message-mailer-swallows-blank-line ++@vindex message-mailer-swallows-blank-line ++Set this to non-@code{nil} if the system's mailer runs the header and ++body together. (This problem exists on SunOS 4 when sendmail is run ++in remote mode.) The value should be an expression to test whether ++the problem will actually occur. ++ ++@item message-send-mail-partially-limit ++@vindex message-send-mail-partially-limit ++@cindex split large message ++The limitation of messages sent as message/partial. The lower bound ++of message size in characters, beyond which the message should be sent ++in several parts. If it is @code{nil}, the size is unlimited. ++ ++@end table ++ ++ ++@node News Headers ++@section News Headers ++ ++@vindex message-required-news-headers ++@code{message-required-news-headers} a list of header symbols. These ++headers will either be automatically generated, or, if that's ++impossible, they will be prompted for. The following symbols are valid: ++ ++@table @code ++ ++@item From ++@cindex From ++@findex user-full-name ++@findex user-mail-address ++This required header will be filled out with the result of the ++@code{message-make-from} function, which depends on the ++@code{message-from-style}, @code{user-full-name}, ++@code{user-mail-address} variables. ++ ++@item Subject ++@cindex Subject ++This required header will be prompted for if not present already. ++ ++@item Newsgroups ++@cindex Newsgroups ++This required header says which newsgroups the article is to be posted ++to. If it isn't present already, it will be prompted for. ++ ++@item Organization ++@cindex organization ++@vindex message-user-organization ++@vindex message-user-organization-file ++This optional header will be filled out depending on the ++@code{message-user-organization} variable. ++@code{message-user-organization-file} will be used if this variable is ++@code{t}. This variable can also be a string (in which case this string ++will be used), or it can be a function (which will be called with no ++parameters and should return a string to be used). ++ ++@item Lines ++@cindex Lines ++This optional header will be computed by Message. ++ ++@item Message-ID ++@cindex Message-ID ++@vindex message-user-fqdn ++@vindex mail-host-address ++@vindex user-mail-address ++@findex system-name ++@cindex Sun ++@cindex i-did-not-set--mail-host-address--so-tickle-me ++This required header will be generated by Message. A unique ID will be ++created based on the date, time, user name (for the local part) and the ++domain part. For the domain part, message will look (in this order) at ++@code{message-user-fqdn}, @code{system-name}, @code{mail-host-address} ++and @code{message-user-mail-address} (i.e. @code{user-mail-address}) ++until a probably valid fully qualified domain name (FQDN) was found. ++ ++@item User-Agent ++@cindex User-Agent ++This optional header will be filled out according to the ++@code{message-newsreader} local variable. ++ ++@item In-Reply-To ++This optional header is filled out using the @code{Date} and @code{From} ++header of the article being replied to. ++ ++@item Expires ++@cindex Expires ++@vindex message-expires ++This extremely optional header will be inserted according to the ++@code{message-expires} variable. It is highly deprecated and shouldn't ++be used unless you know what you're doing. ++ ++@item Distribution ++@cindex Distribution ++@vindex message-distribution-function ++This optional header is filled out according to the ++@code{message-distribution-function} variable. It is a deprecated and ++much misunderstood header. ++ ++@item Path ++@cindex path ++@vindex message-user-path ++This extremely optional header should probably never be used. ++However, some @emph{very} old servers require that this header is ++present. @code{message-user-path} further controls how this ++@code{Path} header is to look. If it is @code{nil}, use the server name ++as the leaf node. If it is a string, use the string. If it is neither ++a string nor @code{nil}, use the user name only. However, it is highly ++unlikely that you should need to fiddle with this variable at all. ++@end table ++ ++@findex yow ++@cindex Mime-Version ++In addition, you can enter conses into this list. The @sc{car} of this cons ++should be a symbol. This symbol's name is the name of the header, and ++the @sc{cdr} can either be a string to be entered verbatim as the value of ++this header, or it can be a function to be called. This function should ++return a string to be inserted. For instance, if you want to insert ++@code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")} ++into the list. If you want to insert a funny quote, you could enter ++something like @code{(X-Yow . yow)} into the list. The function ++@code{yow} will then be called without any arguments. ++ ++If the list contains a cons where the @sc{car} of the cons is ++@code{optional}, the @sc{cdr} of this cons will only be inserted if it is ++non-@code{nil}. ++ ++If you want to delete an entry from this list, the following Lisp ++snippet might be useful. Adjust accordingly if you want to remove ++another element. ++ ++@lisp ++(setq message-required-news-headers ++ (delq 'Message-ID message-required-news-headers)) ++@end lisp ++ ++Other variables for customizing outgoing news articles: ++ ++@table @code ++ ++@item message-syntax-checks ++@vindex message-syntax-checks ++Controls what syntax checks should not be performed on outgoing posts. ++To disable checking of long signatures, for instance, add ++ ++@lisp ++(signature . disabled) ++@end lisp ++ ++to this list. ++ ++Valid checks are: ++ ++@table @code ++@item approved ++@cindex approved ++Check whether the article has an @code{Approved} header, which is ++something only moderators should include. ++@item continuation-headers ++Check whether there are continuation header lines that don't begin with ++whitespace. ++@item control-chars ++Check for invalid characters. ++@item empty ++Check whether the article is empty. ++@item existing-newsgroups ++Check whether the newsgroups mentioned in the @code{Newsgroups} and ++@code{Followup-To} headers exist. ++@item from ++Check whether the @code{From} header seems nice. ++@item illegible-text ++Check whether there is any non-printable character in the body. ++@item invisible-text ++Check whether there is any invisible text in the buffer. ++@item long-header-lines ++Check for too long header lines. ++@item long-lines ++@cindex long lines ++Check for too long lines in the body. ++@item message-id ++Check whether the @code{Message-ID} looks syntactically ok. ++@item multiple-headers ++Check for the existence of multiple equal headers. ++@item new-text ++Check whether there is any new text in the messages. ++@item newsgroups ++Check whether the @code{Newsgroups} header exists and is not empty. ++@item quoting-style ++Check whether text follows last quoted portion. ++@item repeated-newsgroups ++Check whether the @code{Newsgroups} and @code{Followup-to} headers ++contains repeated group names. ++@item reply-to ++Check whether the @code{Reply-To} header looks ok. ++@item sender ++@cindex Sender ++Insert a new @code{Sender} header if the @code{From} header looks odd. ++@item sendsys ++@cindex sendsys ++Check for the existence of version and sendsys commands. ++@item shoot ++Check whether the domain part of the @code{Message-ID} header looks ok. ++@item shorten-followup-to ++Check whether to add a @code{Followup-to} header to shorten the number ++of groups to post to. ++@item signature ++Check the length of the signature. ++@item size ++Check for excessive size. ++@item subject ++Check whether the @code{Subject} header exists and is not empty. ++@item subject-cmsg ++Check the subject for commands. ++@item valid-newsgroups ++Check whether the @code{Newsgroups} and @code{Followup-to} headers ++are valid syntactically. ++@end table ++ ++All these conditions are checked by default, except for @code{sender} ++for which the check is disabled by default if ++@code{message-insert-canlock} is non-@code{nil} (@pxref{Canceling News}). ++ ++@item message-ignored-news-headers ++@vindex message-ignored-news-headers ++Regexp of headers to be removed before posting. The default is@* ++@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:\\|@* ++^X-Draft-From:\\|^X-Gnus-Agent-Meta-Information:}. ++ ++@item message-default-news-headers ++@vindex message-default-news-headers ++This string is inserted at the end of the headers in all message ++buffers that are initialized as news. ++ ++@end table ++ ++ ++@node News Variables ++@section News Variables ++ ++@table @code ++@item message-send-news-function ++@vindex message-send-news-function ++Function used to send the current buffer as news. The default is ++@code{message-send-news}. ++ ++@item message-post-method ++@vindex message-post-method ++Gnusish @dfn{select method} (see the Gnus manual for details) used for ++posting a prepared news message. ++ ++@end table ++ ++ ++@node Insertion Variables ++@section Insertion Variables ++ ++@table @code ++@item message-ignored-cited-headers ++@vindex message-ignored-cited-headers ++All headers that match this regexp will be removed from yanked ++messages. The default is @samp{.}, which means that all headers will be ++removed. ++ ++@item message-cite-prefix-regexp ++@vindex message-cite-prefix-regexp ++Regexp matching the longest possible citation prefix on a line. ++ ++@item message-citation-line-function ++@vindex message-citation-line-function ++@cindex attribution line ++Function called to insert the citation line. The default is ++@code{message-insert-citation-line}, which will lead to citation lines ++that look like: ++ ++@example ++Hallvard B Furuseth writes: ++@end example ++ ++@c FIXME: Add `message-insert-formated-citation-line' and ++@c `message-citation-line-format' ++ ++Point will be at the beginning of the body of the message when this ++function is called. ++ ++Note that Gnus provides a feature where clicking on `writes:' hides the ++cited text. If you change the citation line too much, readers of your ++messages will have to adjust their Gnus, too. See the variable ++@code{gnus-cite-attribution-suffix}. @xref{Article Highlighting, , ++Article Highlighting, gnus, The Gnus Manual}, for details. ++ ++@item message-yank-prefix ++@vindex message-yank-prefix ++@cindex yanking ++@cindex quoting ++When you are replying to or following up an article, you normally want ++to quote the person you are answering. Inserting quoted text is done by ++@dfn{yanking}, and each line you yank will have ++@code{message-yank-prefix} prepended to it (except for quoted lines ++which use @code{message-yank-cited-prefix} and empty lines which use ++@code{message-yank-empty-prefix}). The default is @samp{> }. ++ ++@item message-yank-cited-prefix ++@vindex message-yank-cited-prefix ++@cindex yanking ++@cindex cited ++@cindex quoting ++When yanking text from an article which contains already cited text, ++each line will be prefixed with the contents of this variable. The ++default is @samp{>}. See also @code{message-yank-prefix}. ++ ++@item message-yank-empty-prefix ++@vindex message-yank-empty-prefix ++@cindex yanking ++@cindex quoting ++When yanking text from an article, each empty line will be prefixed with ++the contents of this variable. The default is @samp{>}. You can set ++this variable to an empty string to split the cited text into paragraphs ++automatically. See also @code{message-yank-prefix}. ++ ++@item message-indentation-spaces ++@vindex message-indentation-spaces ++Number of spaces to indent yanked messages. ++ ++@item message-cite-function ++@vindex message-cite-function ++@findex message-cite-original ++@findex message-cite-original-without-signature ++Function for citing an original message. The default is ++@code{message-cite-original}, which simply inserts the original message ++and prepends @samp{> } to each line. ++@code{message-cite-original-without-signature} does the same, but elides ++the signature. ++ ++@item message-indent-citation-function ++@vindex message-indent-citation-function ++Function for modifying a citation just inserted in the mail buffer. ++This can also be a list of functions. Each function can find the ++citation between @code{(point)} and @code{(mark t)}. And each function ++should leave point and mark around the citation text as modified. ++ ++@item message-mark-insert-begin ++@vindex message-mark-insert-begin ++String to mark the beginning of some inserted text. ++ ++@item message-mark-insert-end ++@vindex message-mark-insert-end ++String to mark the end of some inserted text. ++ ++@item message-signature ++@vindex message-signature ++String to be inserted at the end of the message buffer. If @code{t} ++(which is the default), the @code{message-signature-file} file will be ++inserted instead. If a function, the result from the function will be ++used instead. If a form, the result from the form will be used instead. ++If this variable is @code{nil}, no signature will be inserted at all. ++ ++@item message-signature-file ++@vindex message-signature-file ++File containing the signature to be inserted at the end of the buffer. ++If a path is specified, the value of ++@code{message-signature-directory} is ignored, even if set. ++The default is @file{~/.signature}. ++ ++@item message-signature-directory ++@vindex message-signature-directory ++Name of directory containing signature files. Comes in handy if you ++have many such files, handled via Gnus posting styles for instance. ++If @code{nil} (the default), @code{message-signature-file} is expected ++to specify the directory if needed. ++ ++ ++@item message-signature-insert-empty-line ++@vindex message-signature-insert-empty-line ++If @code{t} (the default value) an empty line is inserted before the ++signature separator. ++ ++@end table ++ ++Note that RFC1036bis says that a signature should be preceded by the three ++characters @samp{-- } on a line by themselves. This is to make it ++easier for the recipient to automatically recognize and process the ++signature. So don't remove those characters, even though you might feel ++that they ruin your beautiful design, like, totally. ++ ++Also note that no signature should be more than four lines long. ++Including @acronym{ASCII} graphics is an efficient way to get ++everybody to believe that you are silly and have nothing important to ++say. ++ ++ ++@node Various Message Variables ++@section Various Message Variables ++ ++@table @code ++@item message-default-charset ++@vindex message-default-charset ++@cindex charset ++Symbol naming a @acronym{MIME} charset. Non-@acronym{ASCII} characters ++in messages are assumed to be encoded using this charset. The default ++is @code{iso-8859-1} on non-@sc{mule} Emacsen; otherwise @code{nil}, ++which means ask the user. (This variable is used only on non-@sc{mule} ++Emacsen.) @xref{Charset Translation, , Charset Translation, emacs-mime, ++Emacs MIME Manual}, for details on the @sc{mule}-to-@acronym{MIME} ++translation process. ++ ++@item message-fill-column ++@vindex message-fill-column ++@cindex auto-fill ++Local value for the column beyond which automatic line-wrapping should ++happen for message buffers. If non-nil (the default), also turn on ++auto-fill in message buffers. ++ ++@item message-signature-separator ++@vindex message-signature-separator ++Regexp matching the signature separator. It is @samp{^-- *$} by ++default. ++ ++@item mail-header-separator ++@vindex mail-header-separator ++String used to separate the headers from the body. It is @samp{--text ++follows this line--} by default. ++ ++@item message-directory ++@vindex message-directory ++Directory used by many mailey things. The default is @file{~/Mail/}. ++All other mail file variables are derived from @code{message-directory}. ++ ++@item message-auto-save-directory ++@vindex message-auto-save-directory ++Directory where Message auto-saves buffers if Gnus isn't running. If ++@code{nil}, Message won't auto-save. The default is @file{~/Mail/drafts/}. ++ ++@item message-signature-setup-hook ++@vindex message-signature-setup-hook ++Hook run when initializing the message buffer. It is run after the ++headers have been inserted but before the signature has been inserted. ++ ++@item message-setup-hook ++@vindex message-setup-hook ++Hook run as the last thing when the message buffer has been initialized, ++but before yanked text is inserted. ++ ++@item message-header-setup-hook ++@vindex message-header-setup-hook ++Hook called narrowed to the headers after initializing the headers. ++ ++For instance, if you're running Gnus and wish to insert a ++@samp{Mail-Copies-To} header in all your news articles and all messages ++you send to mailing lists, you could do something like the following: ++ ++@lisp ++(defun my-message-header-setup-hook () ++ (let ((group (or gnus-newsgroup-name ""))) ++ (when (or (message-fetch-field "newsgroups") ++ (gnus-group-find-parameter group 'to-address) ++ (gnus-group-find-parameter group 'to-list)) ++ (insert "Mail-Copies-To: never\n")))) ++ ++(add-hook 'message-header-setup-hook ++ 'my-message-header-setup-hook) ++@end lisp ++ ++@item message-send-hook ++@vindex message-send-hook ++Hook run before sending messages. ++ ++If you want to add certain headers before sending, you can use the ++@code{message-add-header} function in this hook. For instance: ++@findex message-add-header ++ ++@lisp ++(add-hook 'message-send-hook 'my-message-add-content) ++(defun my-message-add-content () ++ (message-add-header "X-In-No-Sense: Nonsense") ++ (message-add-header "X-Whatever: no")) ++@end lisp ++ ++This function won't add the header if the header is already present. ++ ++@item message-send-mail-hook ++@vindex message-send-mail-hook ++Hook run before sending mail messages. This hook is run very late -- ++just before the message is actually sent as mail. ++ ++@item message-send-news-hook ++@vindex message-send-news-hook ++Hook run before sending news messages. This hook is run very late -- ++just before the message is actually sent as news. ++ ++@item message-sent-hook ++@vindex message-sent-hook ++Hook run after sending messages. ++ ++@item message-cancel-hook ++@vindex message-cancel-hook ++Hook run when canceling news articles. ++ ++@item message-mode-syntax-table ++@vindex message-mode-syntax-table ++Syntax table used in message mode buffers. ++ ++@item message-cite-articles-with-x-no-archive ++@vindex message-cite-articles-with-x-no-archive ++If non-@code{nil}, don't strip quoted text from articles that have ++@samp{X-No-Archive} set. Even if this variable isn't set, you can ++undo the stripping by hitting the @code{undo} keystroke. ++ ++@item message-strip-special-text-properties ++@vindex message-strip-special-text-properties ++Emacs has a number of special text properties which can break message ++composing in various ways. If this option is set, message will strip ++these properties from the message composition buffer. However, some ++packages requires these properties to be present in order to work. If ++you use one of these packages, turn this option off, and hope the ++message composition doesn't break too bad. ++ ++@item message-send-method-alist ++@vindex message-send-method-alist ++@findex message-mail-p ++@findex message-news-p ++@findex message-send-via-mail ++@findex message-send-via-news ++Alist of ways to send outgoing messages. Each element has the form: ++ ++@lisp ++(@var{type} @var{predicate} @var{function}) ++@end lisp ++ ++@table @var ++@item type ++A symbol that names the method. ++ ++@item predicate ++A function called without any parameters to determine whether the ++message is a message of type @var{type}. The function will be called in ++the buffer where the message is. ++ ++@item function ++A function to be called if @var{predicate} returns non-@code{nil}. ++@var{function} is called with one parameter---the prefix. ++@end table ++ ++The default is: ++ ++@lisp ++((news message-news-p message-send-via-news) ++ (mail message-mail-p message-send-via-mail)) ++@end lisp ++ ++The @code{message-news-p} function returns non-@code{nil} if the message ++looks like news, and the @code{message-send-via-news} function sends the ++message according to the @code{message-send-news-function} variable ++(@pxref{News Variables}). The @code{message-mail-p} function returns ++non-@code{nil} if the message looks like mail, and the ++@code{message-send-via-mail} function sends the message according to the ++@code{message-send-mail-function} variable (@pxref{Mail Variables}). ++ ++All the elements in this alist will be tried in order, so a message ++containing both a valid @samp{Newsgroups} header and a valid @samp{To} ++header, for example, will be sent as news, and then as mail. ++@end table ++ ++ ++ ++@node Sending Variables ++@section Sending Variables ++ ++@table @code ++ ++@item message-fcc-handler-function ++@vindex message-fcc-handler-function ++A function called to save outgoing articles. This function will be ++called with the name of the file to store the article in. The default ++function is @code{message-output} which saves in Unix mailbox format. ++ ++@item message-courtesy-message ++@vindex message-courtesy-message ++When sending combined messages, this string is inserted at the start of ++the mailed copy. If the string contains the format spec @samp{%s}, the ++newsgroups the article has been posted to will be inserted there. If ++this variable is @code{nil}, no such courtesy message will be added. ++The default value is @samp{"The following message is a courtesy copy of ++an article\\nthat has been posted to %s as well.\\n\\n"}. ++ ++@item message-fcc-externalize-attachments ++@vindex message-fcc-externalize-attachments ++If @code{nil}, attach files as normal parts in Fcc copies; if it is ++non-@code{nil}, attach local files as external parts. ++ ++@item message-interactive ++@vindex message-interactive ++If non-@code{nil} wait for and display errors when sending a message; ++if @code{nil} let the mailer mail back a message to report errors. ++ ++@item message-confirm-send ++@vindex message-confirm-send ++When non-@code{nil}, Gnus will ask for confirmation when sending a ++message. ++ ++@end table ++ ++ ++@node Message Buffers ++@section Message Buffers ++ ++Message will generate new buffers with unique buffer names when you ++request a message buffer. When you send the message, the buffer isn't ++normally killed off. Its name is changed and a certain number of old ++message buffers are kept alive. ++ ++@table @code ++@item message-generate-new-buffers ++@vindex message-generate-new-buffers ++Controls whether to create a new message buffer to compose a message. ++Valid values include: ++ ++@table @code ++@item nil ++Generate the buffer name in the Message way (e.g., *mail*, *news*, *mail ++to whom*, *news on group*, etc.) and continue editing in the existing ++buffer of that name. If there is no such buffer, it will be newly ++created. ++ ++@item unique ++@item t ++Create the new buffer with the name generated in the Message way. This ++is the default. ++ ++@item unsent ++Similar to @code{unique} but the buffer name begins with "*unsent ". ++ ++@item standard ++Similar to @code{nil} but the buffer name is simpler like *mail ++message*. ++@end table ++@table @var ++@item function ++If this is a function, call that function with three parameters: The ++type, the To address and the group name (any of these may be ++@code{nil}). The function should return the new buffer name. ++@end table ++ ++The default value is @code{unique}. ++ ++@item message-max-buffers ++@vindex message-max-buffers ++This variable says how many old message buffers to keep. If there are ++more message buffers than this, the oldest buffer will be killed. The ++default is 10. If this variable is @code{nil}, no old message buffers ++will ever be killed. ++ ++@item message-send-rename-function ++@vindex message-send-rename-function ++After sending a message, the buffer is renamed from, for instance, ++@samp{*reply to Lars*} to @samp{*sent reply to Lars*}. If you don't ++like this, set this variable to a function that renames the buffer in a ++manner you like. If you don't want to rename the buffer at all, you can ++say: ++ ++@lisp ++(setq message-send-rename-function 'ignore) ++@end lisp ++ ++@item message-kill-buffer-on-exit ++@findex message-kill-buffer-on-exit ++If non-@code{nil}, kill the buffer immediately on exit. ++ ++@end table ++ ++ ++@node Message Actions ++@section Message Actions ++ ++When Message is being used from a news/mail reader, the reader is likely ++to want to perform some task after the message has been sent. Perhaps ++return to the previous window configuration or mark an article as ++replied. ++ ++@vindex message-kill-actions ++@vindex message-postpone-actions ++@vindex message-exit-actions ++@vindex message-send-actions ++The user may exit from the message buffer in various ways. The most ++common is @kbd{C-c C-c}, which sends the message and exits. Other ++possibilities are @kbd{C-c C-s} which just sends the message, @kbd{C-c ++C-d} which postpones the message editing and buries the message buffer, ++and @kbd{C-c C-k} which kills the message buffer. Each of these actions ++have lists associated with them that contains actions to be executed: ++@code{message-send-actions}, @code{message-exit-actions}, ++@code{message-postpone-actions}, and @code{message-kill-actions}. ++ ++Message provides a function to interface with these lists: ++@code{message-add-action}. The first parameter is the action to be ++added, and the rest of the arguments are which lists to add this action ++to. Here's an example from Gnus: ++ ++@lisp ++ (message-add-action ++ `(set-window-configuration ,(current-window-configuration)) ++ 'exit 'postpone 'kill) ++@end lisp ++ ++This restores the Gnus window configuration when the message buffer is ++killed, postponed or exited. ++ ++An @dfn{action} can be either: a normal function, or a list where the ++@sc{car} is a function and the @sc{cdr} is the list of arguments, or ++a form to be @code{eval}ed. ++ ++ ++@node Compatibility ++@chapter Compatibility ++@cindex compatibility ++ ++Message uses virtually only its own variables---older @code{mail-} ++variables aren't consulted. To force Message to take those variables ++into account, you can put the following in your @file{.emacs} file: ++ ++@lisp ++(require 'messcompat) ++@end lisp ++ ++This will initialize many Message variables from the values in the ++corresponding mail variables. ++ ++ ++@node Appendices ++@chapter Appendices ++ ++@menu ++* Responses:: Standard rules for determining where responses go. ++@end menu ++ ++ ++@node Responses ++@section Responses ++ ++To determine where a message is to go, the following algorithm is used ++by default. ++ ++@table @dfn ++@item reply ++A @dfn{reply} is when you want to respond @emph{just} to the person who ++sent the message via mail. There will only be one recipient. To ++determine who the recipient will be, the following headers are ++consulted, in turn: ++ ++@table @code ++@item Reply-To ++ ++@item From ++@end table ++ ++ ++@item wide reply ++A @dfn{wide reply} is a mail response that includes @emph{all} entities ++mentioned in the message you are responded to. All mailboxes from the ++following headers will be concatenated to form the outgoing ++@code{To}/@code{Cc} headers: ++ ++@table @code ++@item From ++(unless there's a @code{Reply-To}, in which case that is used instead). ++ ++@item Cc ++ ++@item To ++@end table ++ ++If a @code{Mail-Copies-To} header is present, it will also be included ++in the list of mailboxes. If this header is @samp{never}, that means ++that the @code{From} (or @code{Reply-To}) mailbox will be suppressed. ++ ++ ++@item followup ++A @dfn{followup} is a response sent via news. The following headers ++(listed in order of precedence) determine where the response is to be ++sent: ++ ++@table @code ++ ++@item Followup-To ++ ++@item Newsgroups ++ ++@end table ++ ++If a @code{Mail-Copies-To} header is present, it will be used as the ++basis of the new @code{Cc} header, except if this header is ++@samp{never}. ++ ++@end table ++ ++ ++@node GNU Free Documentation License ++@chapter GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index ++@chapter Index ++@printindex cp ++ ++@node Key Index ++@chapter Key Index ++@printindex ky ++ ++@bye ++ ++@c End: ++ ++@ignore ++ arch-tag: 16ab76af-a281-4e34-aed6-5624569f7601 ++@end ignore +diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi +new file mode 100644 +index 0000000..b973962 +--- /dev/null ++++ b/doc/misc/mh-e.texi +@@ -0,0 +1,9066 @@ ++\input texinfo @c -*-texinfo-*- ++@c ++@c Note: This document requires makeinfo version 4.6 or greater to build. ++@c ++@c %**start of header ++@setfilename ../../info/mh-e ++@settitle The MH-E Manual ++@c %**end of header ++ ++@c Version of the software and manual. ++@set VERSION 8.2 ++@c Edition of the manual. It is either empty for the first edition or ++@c has the form ", nth Edition" (without the quotes). ++@set EDITION ++@set UPDATED 2009-06-13 ++@set UPDATE-MONTH June, 2009 ++ ++@c Other variables. ++@set MH-BOOK-HOME http://rand-mh.sourceforge.net/book/mh ++@set MH-E-HOME http://mh-e.sourceforge.net/ ++ ++@c Copyright ++@copying ++This is version @value{VERSION}@value{EDITION} of @cite{The MH-E ++Manual}, last updated @value{UPDATED}. ++ ++Copyright @copyright{} 1995, 2001, 2002, 2003, 2005, 2006, 2007, 2008, 2009 ++Free Software Foundation, Inc. ++ ++@c This dual license has been agreed upon by the FSF. ++ ++@quotation ++Permission is granted to copy, distribute and/or modify this document ++under the terms of either: ++ ++@enumerate a ++@item ++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.'' ++ ++@item ++the GNU General Public License as published by the Free Software ++Foundation; either version 3, or (at your option) any later version. A ++copy of the license is included in the section entitled ``GNU General ++Public License.'' ++@end enumerate ++ ++@end quotation ++@end copying ++ ++@c Info Directory Entry ++@dircategory Emacs ++@direntry ++* MH-E: (mh-e). Emacs interface to the MH mail system. ++@end direntry ++ ++@c Title Page ++@titlepage ++@title The MH-E Manual ++@subtitle Version @value{VERSION}@value{EDITION} ++@subtitle @value{UPDATE-MONTH} ++@author Bill Wohler ++ ++@c Copyright Page ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@ifnottex ++@html ++ ++@end html ++@insertcopying ++@end ifnottex ++ ++@c Table of Contents ++@contents ++ ++@html ++ ++@end html ++ ++@node Preface, Conventions, Top, Top ++@unnumbered Preface ++ ++@cindex Emacs ++@cindex Unix commands, Emacs ++@cindex preface ++ ++This manual introduces another interface to the MH mail system that is ++accessible through the GNU Emacs editor, namely, @emph{MH-E}. MH-E is ++easy to use. I don't assume that you know GNU Emacs or even MH at this ++point, since I didn't know either of them when I discovered MH-E. ++However, MH-E was the tip of the iceberg, and I discovered more and ++more niceties about GNU Emacs and MH@. Now I'm fully hooked on both of ++them. ++ ++The MH-E package is distributed with GNU Emacs@footnote{Version ++@value{VERSION} of MH-E will appear in GNU Emacs 23.1. It is supported ++in GNU Emacs 21 and 22, as well as XEmacs 21 (except for versions ++21.5.9-21.5.16). It is compatible with MH versions 6.8.4 and higher, ++all versions of nmh, and GNU mailutils 1.0 and higher.}, so you ++shouldn't have to do anything special to use it. Gnus is also ++required; version 5.10 or higher is recommended. This manual covers ++MH-E version @value{VERSION}. To help you decide which version you ++have, see @ref{Getting Started}. ++ ++@findex help-with-tutorial ++@kindex C-h t ++ ++If you don't already use GNU Emacs but want to learn more, you can ++read an online tutorial by starting GNU Emacs and typing @kbd{C-h t} ++(@code{help-with-tutorial}). (To learn about this notation, see ++@ref{Conventions}.) If you want to take the plunge, consult the ++@iftex ++@cite{GNU Emacs Manual}, ++@end iftex ++@ifinfo ++@ref{top, , GNU Emacs Manual, emacs, GNU Emacs Manual}, ++@end ifinfo ++@ifhtml ++@uref{http://www.gnu.org/software/emacs/manual/html_node/, ++@cite{GNU Emacs Manual}}, ++@end ifhtml ++from the Free Software Foundation. ++ ++If more information is needed, you can go to the Unix manual pages of ++the individual MH commands. When the name is not obvious, I'll guide ++you to a relevant MH manual page that describes the action more fully. ++ ++@cindex @cite{MH & nmh: Email for Users & Programmers} ++@cindex MH book ++@cindex info ++@kindex C-h i ++ ++This manual is available in both Info and online formats. The Info ++version is distributed with Emacs and can be accessed with the ++@command{info} command (@samp{info mh-e}) or within Emacs (@kbd{C-h i ++m mh-e @key{RET}}). The online version is available at ++@uref{http://mh-e.sourceforge.net/manual/, SourceForge}. Another great ++online resource is the book @uref{http://www.ics.uci.edu/~mh/book/, ++@cite{MH & nmh: Email for Users & Programmers}} (also known as ++@dfn{the MH book}). ++ ++I hope you enjoy this manual! If you have any comments, or suggestions ++for this document, please let me know. ++ ++@cindex Bill Wohler ++@cindex Wohler, Bill ++ ++@noindent ++Bill Wohler <@i{wohler at newt.com}>@* ++8 February 1995@* ++24 February 2006 ++ ++@node Conventions, Getting Started, Preface, Top ++@chapter GNU Emacs Terms and Conventions ++ ++@cindex Emacs ++@cindex Emacs, conventions ++@cindex Emacs, terms ++@cindex Unix commands, Emacs ++@cindex conventions, Emacs ++@cindex terms, Emacs ++ ++If you're an experienced Emacs user, you can skip the following ++conventions and definition of terms and go directly to the next ++section (@pxref{Getting Started}). ++ ++@cindex Emacs commands ++@cindex MH commands ++@cindex Unix commands ++@cindex commands ++@cindex commands, MH ++@cindex commands, Unix ++@cindex commands, shell ++@cindex functions ++@cindex shell commands ++ ++In general, @dfn{functions} in this text refer to Emacs Lisp functions ++that one would call from within Emacs Lisp programs (for example, ++@code{(mh-inc-folder)}). On the other hand, @dfn{commands} are those ++things that are run by the user, such as @kbd{i} or @kbd{M-x ++mh-inc-folder}. Programs outside of Emacs are specifically called MH ++commands, shell commands, or Unix commands. ++ ++@cindex conventions, key names ++@cindex key names ++ ++The conventions for key names are as follows: ++ ++@table @kbd ++@item C-x ++Hold down the @key{CTRL} (Control) key and press the @kbd{x} key. ++@c ------------------------- ++@item M-x ++Hold down the @key{META} or @key{ALT} key and press the @kbd{x} key. ++ ++Since some keyboards don't have a @key{META} key, you can generate ++@kbd{M-x}, for example, by pressing @key{ESC} (Escape), ++@emph{releasing it}, and then pressing the @kbd{x} key. ++@c ------------------------- ++@item @key{RET} ++Press the @key{RETURN} or @key{ENTER} key. This is normally used to ++complete a command. ++@c ------------------------- ++@item @key{SPC} ++Press the space bar. ++@c ------------------------- ++@item @key{TAB} ++Press the @key{TAB} key. ++@c ------------------------- ++@item @key{DEL} ++Press the @key{DELETE} key. ++@c ------------------------- ++@item @key{BS} ++Press the @key{BACKSPACE} key@footnote{If you are using Version 20 or ++earlier of Emacs, you will need to use the @key{DEL} key.}. ++@end table ++ ++@cindex Emacs, prefix argument ++@cindex prefix argument ++@kindex C-u ++ ++A @dfn{prefix argument} allows you to pass an argument to any Emacs ++function. To pass an argument, type @kbd{C-u} before the Emacs command ++or keystroke. Numeric arguments can be passed as well. For example, to ++insert five f's, use @kbd{C-u 5 f}. There is a default of four when ++using @kbd{C-u}, and you can use multiple prefix arguments to provide ++arguments of powers of four. To continue our example, you could insert ++four f's with @kbd{C-u f}, 16 f's with @kbd{C-u C-u f}, 64 f's with ++@kbd{C-u C-u C-u f}, and so on. Numeric and valueless negative ++arguments can also be inserted with the @key{META} key. Examples ++include @kbd{M-5} to specify an argument of 5, or @kbd{M--} which ++specifies a negative argument with no particular value. ++ ++@sp 1 ++@center @strong{NOTE} ++ ++@quotation ++The prefix @kbd{C-u} or @kbd{M-} is not necessary in MH-E's MH-Folder ++mode (@pxref{Reading Mail Tour}). In this mode, simply enter the ++numerical argument before entering the command. ++@end quotation ++@sp 1 ++ ++@cindex @file{.emacs} ++@cindex Emacs, variables ++@cindex files, @file{.emacs} ++@cindex variables ++@findex setq ++ ++Emacs uses @dfn{variables} to hold values. These can be changed via ++calls to the function @code{setq} in @file{~/.emacs}. ++ ++@cindex Emacs, options ++@cindex options ++@findex customize-group ++@findex customize-option ++ ++Variables in MH-E that are normally modified by the user are called ++@dfn{options} and are modified through the customize functions (such ++as @kbd{M-x customize-option} or @kbd{M-x customize-group}). ++@ifnothtml ++@xref{Easy Customization,,,emacs,The GNU Emacs Manual}, in @cite{The ++GNU Emacs Manual}. ++@end ifnothtml ++@ifhtml ++See section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Easy-Customization.html, ++Easy Customization} in @cite{The GNU Emacs Manual}. ++@end ifhtml ++@xref{Options}. ++ ++@cindex Emacs, faces ++@cindex faces ++@cindex highlighting ++@findex customize-face ++ ++You can specify various styles for displaying text using @dfn{faces}. ++MH-E provides a set of faces that you can use to personalize the look ++of your MH-E buffers. Use the command @kbd{M-x customize-face} to do ++this. ++@ifnothtml ++@xref{Face Customization,,,emacs,The GNU Emacs Manual}, in @cite{The ++GNU Emacs Manual}. ++@end ifnothtml ++@ifhtml ++See section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Face-Customization.html, ++Face Customization} in @cite{The GNU Emacs Manual}. ++@end ifhtml ++ ++@cindex abnormal hooks ++@cindex hooks ++@cindex normal hooks ++@findex add-hook ++@findex customize-option ++ ++Commands often offer @dfn{hooks} which enable you to extend or modify ++the way a command works. ++@ifnothtml ++@ref{Hooks, , Hooks, emacs, The GNU Emacs Manual}, in @cite{The GNU ++Emacs Manual} ++@end ifnothtml ++@ifhtml ++See section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Hooks.html, ++Hooks} in @cite{The GNU Emacs Manual} ++@end ifhtml ++for a description about @dfn{normal hooks} and @dfn{abnormal hooks}. ++MH-E uses normal hooks in nearly all cases, so you can assume that we ++are talking about normal hooks unless we explicitly mention that a ++hook is abnormal. We also follow the conventions described in that ++section: the name of the abnormal hooks end in @code{-hooks} and all ++the rest of the MH-E hooks end in @code{-hook}. You can add hooks with ++either @code{customize-option} or @code{add-hook}. ++ ++@cindex Emacs, mark ++@cindex Emacs, point ++@cindex Emacs, region ++@cindex mark ++@cindex point ++@cindex region ++@kindex C-@@ ++@kindex C-@key{SPC} ++ ++There are several other terms that are used in Emacs that you should ++know. The @dfn{point} is where the cursor currently is. You can save ++your current place in the file by setting a @dfn{mark}. This operation ++is useful in several ways. The mark can be later used when defining a ++@dfn{region}, which is the text between the point and mark. Many ++commands operate on regions, such as those for deleting text or ++filling paragraphs. A mark can be set with @kbd{C-@@} (or ++@kbd{C-@key{SPC}}). ++ ++@cindex completion ++@cindex Emacs, completion ++@cindex Emacs, file completion ++@cindex Emacs, folder completion ++@cindex Emacs, minibuffer ++@cindex file completion ++@cindex folder completion ++@cindex minibuffer ++@kindex SPC ++@kindex TAB ++ ++The @dfn{minibuffer} is the bottom line of the Emacs window, where all ++prompting and multiple-character input is directed. You can use ++@dfn{completion} to enter values such as folders. Completion means ++that Emacs fills in text for you when you type @key{SPC} or @key{TAB}. ++A second @key{SPC} or @key{TAB} will list all possibilities at that ++point. ++@ifnothtml ++@xref{Completion, , Completion, emacs, The GNU Emacs Manual}. ++@end ifnothtml ++@ifhtml ++See the section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Completion.html, ++Completion} in @cite{The GNU Emacs Manual}. ++@end ifhtml ++Note that @key{SPC} cannot be used for completing filenames and ++folders. ++ ++@findex help-with-tutorial ++@kindex C-h t ++@kindex M-x ++ ++The minibuffer is also where you enter Emacs function names after ++typing @kbd{M-x}. For example, in the preface, I mentioned that you ++could obtain help with @kbd{C-h t} (@code{help-with-tutorial}). What ++this means is that you can get a tutorial by typing either @kbd{C-h t} ++or @kbd{M-x help-with-tutorial}. In the latter case, you are prompted ++for @samp{help-with-tutorial} in the minibuffer after typing ++@kbd{M-x}. ++ ++@cindex ~ ++ ++The @samp{~} notation in filenames represents your home directory. ++This notation is used by many shells including @command{bash}, ++@code{tcsh}, and @command{csh}. It is analogous to the environment ++variable @samp{$HOME}. For example, @file{~/.emacs} can be written ++@file{$HOME/.emacs} or using the absolute path as in ++@file{/home/wohler/.emacs} instead. ++ ++@cindex Emacs, interrupting ++@cindex Emacs, quitting ++@cindex interrupting ++@cindex quitting ++ ++@i{In case of trouble:} Emacs can be interrupted at any time with ++@kbd{C-g}. For example, if you've started a command that requests that ++you enter something in the minibuffer, but then you change your mind, ++type @kbd{C-g} and you'll be back where you started. If you want to ++exit Emacs entirely, use @kbd{C-x C-c}. ++ ++@node Getting Started, Tour Through MH-E, Conventions, Top ++@chapter Getting Started ++ ++@cindex MH-E, versions ++@cindex history ++@cindex versions of MH-E ++ ++Because there are many old versions of MH-E out there, it is important ++to know which version you have. I'll be talking about @w{Version 8} ++which is pretty close to @w{Version 6} and @w{Version 7}. It differs ++from @w{Version 4} and @w{Version 5} and is vastly different from ++@w{Version 3}. @xref{History}. ++ ++@findex mh-version ++ ++To determine which version of MH-E that you have, enter @kbd{M-x ++mh-version @key{RET}}. Hopefully it says that you're running ++@w{Version @value{VERSION}} which is the latest version as of this ++printing. ++ ++If your version is much older than this, please consider upgrading. ++You can have your system administrator upgrade the system-wide ++version, or you can install your own personal version. It's really ++quite easy. @xref{Getting MH-E}, for instructions for getting and ++installing MH-E. ++ ++If the @code{mh-version} command displays @samp{No MH variant ++detected}@footnote{In very old versions of MH-E, you may get the error ++message, @samp{Cannot find the commands `inc' and `mhl' and the file ++`components'} if MH-E can't find MH. In this case, you need to update ++MH-E, and you may need to install MH too. However, newer versions of ++MH-E are better at finding MH if it is on your system.}, then you need ++to install MH or tell MH-E where to find MH. ++ ++@cindex Debian ++@cindex nmh ++@cindex GNU mailutils MH ++ ++If you don't have MH on your system already, you must install a ++variant of MH. The Debian mh-e package does this for you automatically ++(@pxref{Getting MH-E}). Most people use ++@uref{http://www.nongnu.org/nmh/, nmh}, but you may be interested in ++trying out @uref{http://www.gnu.org/software/mailutils/, GNU mailutils ++MH}, which supports IMAP. Your GNU/Linux distribution probably has ++packages for both of these. ++ ++@cindex @command{install-mh} ++@cindex MH commands, @command{install-mh} ++@cindex MH book ++ ++If you've never run MH before, you need to run @command{install-mh} ++from the shell before you continue. This sets up your personal MH ++environment@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/../overall/setup.html, Setting Up MH} in the ++MH book.}. If you don't, you'll be greeted with the error message: ++@samp{Install MH and run install-mh before running MH-E}. This is all ++you need to know about MH to use MH-E, but the more you know about MH, ++the more you can leverage its power. See the ++@uref{@value{MH-BOOK-HOME}/../, MH book} to learn more about MH. ++ ++@cindex @samp{Path:} MH profile component ++@cindex MH profile ++@cindex MH profile component ++@cindex MH profile component, @samp{Path:} ++ ++Your MH environment includes your @dfn{MH profile} which is found in ++the file @file{~/.mh_profile}, or the file named in the environment ++variable @samp{$MH}. This file contains a number of @dfn{MH ++profile components}. For example, the @samp{Path:} MH profile ++component contains the path to your mail directory, which is ++@file{~/Mail} by default. ++ ++@cindex @command{mhparam} ++@cindex MH commands, @command{mhparam} ++@vindex exec-path ++@vindex mh-path ++@vindex mh-sys-path ++@vindex mh-variant ++@vindex mh-variant-in-use ++ ++There are several options MH-E uses to interact with your MH ++installation. The option @code{mh-variant} specifies the variant used ++by MH-E (@pxref{Options}). The default setting of this option is ++@samp{Auto-detect} which means that MH-E will automatically choose the ++first of nmh, MH, or GNU mailutils MH that it finds in the directories ++listed in @code{mh-path} (which you can customize), ++@code{mh-sys-path}, and @code{exec-path}. If MH-E can't find MH at ++all, you may have to customize @code{mh-path} and add the directory in ++which the command @command{mhparam} is located. If, on the other hand, ++you have both nmh and GNU mailutils MH installed (for example) and ++@code{mh-variant-in-use} was initialized to nmh but you want to use ++GNU mailutils MH, then you can set @code{mh-variant} to ++@samp{gnu-mh}. ++ ++@vindex mh-flists-present-flag ++@vindex mh-lib ++@vindex mh-lib-progs ++@vindex mh-progs ++ ++When @code{mh-variant} is changed, MH-E resets @code{mh-progs}, ++@code{mh-lib}, @code{mh-lib-progs}, @code{mh-flists-present-flag}, and ++@code{mh-variant-in-use} accordingly. ++ ++@cindex @file{.emacs} ++@cindex files, @file{.emacs} ++ ++@sp 1 ++@center @strong{NOTE} ++ ++@quotation ++Prior to version 8, it was often necessary to set some of these ++variables in @file{~/.emacs}; now it is no longer necessary and can ++actually cause problems. ++@end quotation ++@sp 1 ++ ++@cindex MH profile component, @samp{Draft-Folder:} ++@cindex MH profile component, @samp{Path:} ++@cindex MH profile component, @samp{Previous-Sequence:} ++@cindex MH profile component, @samp{Unseen-Sequence:} ++@cindex @samp{Draft-Folder:} MH profile component ++@cindex @samp{Path:} MH profile component ++@cindex @samp{Previous-Sequence:} MH profile component ++@cindex @samp{Unseen-Sequence:} MH profile component ++@findex mh-find-path ++@vindex mh-draft-folder ++@vindex mh-find-path-hook ++@vindex mh-inbox ++@vindex mh-previous-seq ++@vindex mh-unseen-seq ++@vindex mh-user-path ++ ++In addition to setting variables that point to MH itself, MH-E also ++sets a handful of variables that point to where you keep your mail. ++During initialization, the function @code{mh-find-path} sets ++@code{mh-user-path} from your @samp{Path:} MH profile component (but ++defaults to @samp{Mail} if one isn't present), @code{mh-draft-folder} ++from @samp{Draft-Folder:}, @code{mh-unseen-seq} from ++@samp{Unseen-Sequence:}, @code{mh-previous-seq} from ++@samp{Previous-Sequence:}, and @code{mh-inbox} from @samp{Inbox:} ++(defaults to @samp{+inbox}). The hook @code{mh-find-path-hook} is run ++after these variables have been set. This hook can be used the change ++the value of these variables if you need to run with different values ++between MH and MH-E. ++ ++@node Tour Through MH-E, Using This Manual, Getting Started, Top ++@chapter Tour Through MH-E ++ ++@cindex introduction ++@cindex tour ++@cindex tutorial ++ ++This chapter introduces some of the terms you'll need to know and then ++takes you on a tour of MH-E@footnote{The keys mentioned in these ++chapters refer to the default key bindings. If you've changed the ++bindings, refer to the command summaries at the beginning of each ++chapter for a mapping between default key bindings and function ++names.}. When you're done, you'll be able to send, read, and file ++mail, which is all that a lot of people ever do. But if you're the ++curious or adventurous type, read the rest of the manual to be able to ++use all the features of MH-E. I suggest you read this chapter first to ++get the big picture, and then you can read the manual as you wish. ++ ++@menu ++* Sending Mail Tour:: ++* Reading Mail Tour:: ++* Processing Mail Tour:: ++* Leaving MH-E:: ++* More About MH-E:: ++@end menu ++ ++@node Sending Mail Tour, Reading Mail Tour, Tour Through MH-E, Tour Through MH-E ++@section Sending Mail ++ ++@cindex MH-Letter mode ++@cindex mode ++@cindex modes, MH-Letter ++@cindex sending mail ++@findex mh-smail ++@kindex M-x mh-smail ++ ++Let's start our tour by sending ourselves a message which we can later ++read and process. Enter @kbd{M-x mh-smail} to invoke the MH-E program ++to send messages. Your message appears in an Emacs buffer whose ++mode@footnote{A @dfn{mode} changes Emacs to make it easier to edit a ++particular type of text.} is MH-Letter. ++ ++Enter your login name in the @samp{To:} header field. Press the ++@key{TAB} twice to move the cursor past the @samp{Cc:} field, since no ++carbon copies are to be sent, and on to the @samp{Subject:} field. ++Enter @kbd{Test} or anything else that comes to mind. ++ ++Press @key{TAB} again to move the cursor to the body of the message. ++Enter some text, using normal Emacs commands. You should now have ++something like this@footnote{If you're running Emacs under the X ++Window System, then you would also see a menu bar and a tool bar. I've ++left out the menu bar and tool bar in all of the example screens.}: ++ ++@cartouche ++@smallexample ++ ++ ++ ++ ++ ++ ++--:-- *scratch* All L1 (Lisp Interaction)------------------------- ++To: wohler ++cc: ++Subject: Test ++X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 ++-------- ++This is a test message to get the wheels churning...# ++ ++ ++--:** @{draft@} All L5 (MH-Letter)---------------------------------- ++Type C-c C-c to send message, C-C ? for help ++@end smallexample ++@end cartouche ++@i{MH-E message composition window} ++ ++Note the line of dashes that separates the header and the body of the ++message. It is essential that these dashes (or a blank line) are ++present or the body of your message will be considered to be part of ++the header. ++ ++@cindex help ++@findex describe-mode ++@kindex C-c ? ++@kindex C-c C-c ++@kindex C-h m ++ ++There are several commands specific to MH-Letter mode@footnote{You can ++get quick help for the commands used most often with @kbd{C-c ?} or ++more complete help with the @kbd{C-h m} (@code{describe-mode}) ++command.}, but at this time we'll only use @kbd{C-c C-c} to send your ++message. Type @kbd{C-c C-c} now. That's all there is to it! ++ ++@node Reading Mail Tour, Processing Mail Tour, Sending Mail Tour, Tour Through MH-E ++@section Receiving Mail ++ ++@cindex @command{inc} ++@cindex @command{scan} ++@cindex MH commands, @command{inc} ++@cindex MH commands, @command{scan} ++@cindex MH-Folder mode ++@cindex modes, MH-Folder ++@cindex reading mail ++@findex mh-rmail ++@kindex M-x mh-rmail ++ ++To read the mail you've just sent yourself, enter @kbd{M-x mh-rmail}. ++This incorporates the new mail and puts the output from ++@command{inc}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next ++prev} in the MH book.} (called @dfn{scan lines} after the MH program ++@command{scan}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/faswsprs.html, Find and Specify with scan ++pick Ranges Sequences} in the MH book.} which prints a one-line ++summary of each message) into a buffer called @samp{+inbox} whose ++major mode is MH-Folder. ++ ++@findex mh-rmail ++@kindex F r ++@kindex M-x mh-rmail ++ ++@sp 1 ++@center @strong{NOTE} ++ ++@quotation ++ ++The @kbd{M-x mh-rmail} command will show you only new mail, not mail ++you have already read. If you were to run this tour again, you would ++use @kbd{F r} to pull all your messages into MH-E. ++@end quotation ++@sp 1 ++ ++@kindex @key{RET} ++@kindex n ++@kindex p ++ ++You should see the scan line for your message, and perhaps others. Use ++@kbd{n} or @kbd{p} to move the cursor to your test message and type ++@key{RET} to read your message. You should see something like: ++ ++@cartouche ++@smallexample ++ 3 t08/24 root received fax files on Wed Aug 24 11:00:13 PDT 1 ++# 4+t08/24 To:wohler Test< ++ ++This is a test message to get the wheels churning... ++ ++ ++ ++--:-- @{show-+inbox@} 4 All L1 (MH-Show)---------------------------- ++ ++@end smallexample ++@end cartouche ++@i{After incorporating new messages} ++ ++@kindex @key{DEL} ++@kindex @key{SPC} ++ ++If you typed a long message, you can view subsequent pages with ++@key{SPC} and previous pages with @key{DEL}. ++ ++@node Processing Mail Tour, Leaving MH-E, Reading Mail Tour, Tour Through MH-E ++@section Processing Mail ++ ++@cindex processing mail ++@kindex @key{RET} ++@kindex r ++ ++The first thing we want to do is reply to the message that we sent ++ourselves. Ensure that the cursor is still on the same line as your ++test message and type @kbd{r}. You are prompted in the minibuffer with ++@samp{Reply to whom:}. Here MH-E is asking whether you'd like to reply ++to the original sender only, to the sender and primary recipients, or ++to the sender and all recipients. You can press @key{TAB} to see these ++choices. If you simply press @key{RET}, you'll reply only to the ++sender. Press @key{RET} now. ++ ++You'll find yourself in an Emacs buffer similar to that when you were ++sending the original message, like this: ++ ++@cartouche ++@smallexample ++To: ++cc: ++Subject: Re: Test ++In-reply-to: <31054.1142621351@@stop.mail-abuse.org> ++References: <31054.1142621351@@stop.mail-abuse.org> ++Comments: In-reply-to Bill Wohler ++ message dated "Fri, 17 Mar 2006 10:49:11 -0800." ++X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 ++-------- ++# ++ ++--:-- @{draft@} All L10 (MH-Letter)---------------------------------- ++To: wohler ++Subject: Test ++X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 ++Date: Fri, 17 Mar 2006 10:49:11 -0800 ++From: Bill Wohler ++ ++This is a test message to get the wheels churning... ++ ++--:-- @{show-+inbox@} 4 All L1 (MH-Show)---------------------------- ++Type C-c C-c to send message, C-c ? for help ++@end smallexample ++@end cartouche ++@i{Composition window during reply} ++ ++@findex backward-char ++@findex forward-char ++@findex next-line ++@findex previous-line ++@kindex C-b ++@kindex C-c C-c ++@kindex C-c C-f C-t ++@kindex C-f ++@kindex C-n ++@kindex C-p ++@kindex @key{BS} ++ ++By default, MH will not add you to the address list of your replies, ++so if you find that the @samp{To:} header field is missing, don't ++worry. In this case, type @kbd{C-c C-f C-t} to create and go to the ++@samp{To:} field, where you can type your login name again. You can ++move around with the arrow keys or with @kbd{C-p} ++(@code{previous-line}), @kbd{C-n} (@code{next-line}), @kbd{C-b} ++(@code{backward-char}), and @kbd{C-f} (@code{forward-char}) and can ++delete the previous character with @key{BS}. When you're finished ++editing your message, send it with @kbd{C-c C-c} as before. ++ ++@cindex @command{refile} ++@cindex MH commands, @command{refile} ++@cindex folders ++@kindex @key{SPC} ++@kindex o ++ ++You'll often want to save messages that were sent to you in an ++organized fashion. This is done with @dfn{folders}. You can use ++folders to keep messages from your friends, or messages related to a ++particular topic. With your cursor in the MH-Folder buffer and ++positioned on the message you sent to yourself, type @kbd{o} to output ++(@command{refile} in MH parlance) that message to a folder. Enter ++@kbd{test} at the @samp{Destination folder:} prompt and type @kbd{y} ++(or @key{SPC}) when MH-E asks to create the folder @samp{+test}. Note ++that a @samp{^} (caret) appears next to the message number, which ++means that the message has been marked for refiling but has not yet ++been refiled. We'll talk about how the refile is actually carried out ++in a moment. ++ ++@cindex MH-Folder mode ++@cindex modes, MH-Folder ++@kindex d ++@kindex i ++@kindex @key{RET} ++@kindex n ++@kindex p ++@kindex x ++ ++Your previous reply is now waiting in the system mailbox. You ++incorporate this mail into your MH-Folder buffer named @samp{+inbox} ++with the @kbd{i} command. Do this now. After the mail is incorporated, ++use @kbd{n} or @kbd{p} to move the cursor to the new message, and read ++it with @key{RET}. Let's delete this message by typing @kbd{d}. Note ++that a @samp{D} appears next to the message number. This means that ++the message is marked for deletion but is not yet deleted. To perform ++the deletion (and the refile we did previously), use the @kbd{x} ++command. ++ ++@findex mh-smail ++@kindex m ++@kindex M-x mh-smail ++ ++If you want to send another message you can use @kbd{m} instead of ++@kbd{M-x mh-smail}. So go ahead, send some mail to your friends! ++ ++@cindex help ++@cindex prefix characters ++@findex describe-mode ++@kindex ? ++@kindex C-h m ++@kindex F ? ++ ++You can get a quick reminder about these commands by typing @kbd{?}. ++This lists several @dfn{prefix characters}. To list the commands ++available via the prefix characters, type the prefix character ++followed by a @kbd{?}, for example, @kbd{F ?}. More complete help is ++available with the @kbd{C-h m} (@code{describe-mode}) command. ++ ++@node Leaving MH-E, More About MH-E, Processing Mail Tour, Tour Through MH-E ++@section Leaving MH-E ++ ++@cindex Emacs, quitting ++@cindex quitting ++@kindex C-x C-c ++@kindex x ++ ++You may now wish to exit @command{emacs} entirely. Use @kbd{C-x C-c} ++to exit @command{emacs}. If you exited without running @kbd{x} in the ++@samp{+inbox} buffer, Emacs will offer to save it for you. Type ++@kbd{y} or @key{SPC} to save @samp{+inbox} changes, which means to ++perform any refiles and deletes that you did there. ++ ++@findex mh-rmail ++@kindex C-x b ++@kindex C-x k ++@kindex M-x mh-rmail ++@kindex q ++ ++If you don't want to leave Emacs, you can type @kbd{q} to bury (hide) ++the MH-E folder or delete it entirely with @kbd{C-x k}. You can then ++later recall it with @kbd{C-x b} or @kbd{M-x mh-rmail}. ++ ++@cindex @command{packf} ++@cindex MH commands, @command{packf} ++@cindex exporting folders ++@cindex folders, exporting ++@cindex mbox-style folder ++ ++On the other hand, if you no longer want to use MH and MH-E, you can ++take your mail with you. You can copy all of your mail into a single ++file, mbox-style, by using the MH command @command{packf}. For ++example, to create a file called @file{msgbox} with the messages in ++your @samp{+inbox} folder, use @samp{packf +inbox}. The ++@command{packf} command will append the messages to the file if it ++already exists, so you can use @samp{folders -recurse -fast} in a ++script to copy all of your messages into a single file, or using the ++@samp{-file} argument, a file for each folder. ++ ++@node More About MH-E, , Leaving MH-E, Tour Through MH-E ++@section More About MH-E ++ ++These are the basic commands to get you going, but there are plenty ++more. If you think that MH-E is for you, read the rest of the manual ++to find out how you can: ++ ++@itemize @bullet ++@item ++Print your messages (@pxref{Printing}). ++@c ------------------------- ++@item ++Edit messages and include your signature (@pxref{Editing Drafts}). ++@c ------------------------- ++@item ++Forward messages (@pxref{Forwarding}). ++@c ------------------------- ++@item ++Read digests (@pxref{Digests}). ++@c ------------------------- ++@item ++Edit bounced messages (@pxref{Editing Again}). ++@c ------------------------- ++@item ++Send multimedia messages (@pxref{Adding Attachments}). ++@c ------------------------- ++@item ++Read HTML messages (@pxref{HTML}). ++@c ------------------------- ++@item ++Use aliases and identities (see @ref{Aliases}, @pxref{Identities}). ++@c ------------------------- ++@item ++Create different views of your mail (see @ref{Threading}, @pxref{Limits}). ++@c ------------------------- ++@item ++Deal with junk mail (@pxref{Junk}). ++@c ------------------------- ++@item ++Handle signed and encrypted messages (see @ref{Reading PGP}, ++@pxref{Sending PGP}). ++@c ------------------------- ++@item ++Process mail that was sent with @command{shar} or @command{uuencode} ++(@pxref{Files and Pipes}). ++@c ------------------------- ++@item ++Use sequences conveniently (@pxref{Sequences}). ++@c ------------------------- ++@item ++Use the speedbar, tool bar, and menu bar (see @ref{Speedbar}, see @ref{Tool ++Bar}, @pxref{Menu Bar}). ++@c ------------------------- ++@item ++Show header fields in different fonts (@pxref{Reading Mail}). ++@c ------------------------- ++@item ++Find previously refiled messages (@pxref{Searching}). ++@c ------------------------- ++@item ++Place messages in a file (@pxref{Files and Pipes}). ++@end itemize ++ ++Remember that you can also use MH commands when you're not running ++MH-E (and when you are!). ++ ++@node Using This Manual, Incorporating Mail, Tour Through MH-E, Top ++@chapter Using This Manual ++ ++This chapter begins the meat of the manual which goes into more detail ++about every MH-E command and option. ++ ++@cindex Emacs, info ++@cindex Emacs, online help ++@cindex info ++@cindex online help ++@findex describe-mode ++@findex mh-help ++@kindex ? ++@kindex C-c ? ++@kindex C-h C-h ++@kindex C-h C-k i ++@kindex C-h i ++@kindex C-h m ++ ++There are many commands, but don't get intimidated. There are command ++summaries at the beginning of each chapter. In case you have or would ++like to rebind the keys, the command summaries also list the ++associated Emacs Lisp function. Furthermore, even if you're stranded ++on a desert island with a laptop and are without your manuals, you can ++get a summary of all these commands with GNU Emacs online help: use ++@kbd{C-h m} (@code{describe-mode}) for a brief summary of commands, ++@kbd{?} (@code{mh-help}) for an even briefer summary@footnote{This ++help appears in a buffer called @samp{*MH-E Help*} ++(@pxref{Miscellaneous}).} (@kbd{C-c ?} in MH-Letter mode), or @kbd{C-h ++i} to read this manual via Info. The online help is quite good; try ++running @kbd{C-h C-h}. This brings up a list of available help topics, ++one of which displays the documentation for a given key (like @kbd{C-h ++k C-n}). Another useful help feature is to view the manual section ++that describes a given key (such as @kbd{C-h K i}). In addition, ++review @ref{Conventions}, if any of the GNU Emacs conventions are ++strange to you. ++ ++In addition to all of the commands, it is also possible to reconfigure ++MH-E to fit the needs of even the most demanding user. The following ++chapters also describe all of the options, show the defaults, and make ++recommendations for customization. ++ ++However, when customizing your mail environment, first try to change ++what you want in MH, and only change MH-E if changing MH is not ++possible. That way you will get the same behavior inside and outside ++GNU Emacs. Note that MH-E does not provide hooks for customizations ++that can be done in MH; this omission is intentional. ++ ++@cindex Emacs Lisp Manual ++@cindex Emacs, Emacs Lisp Manual ++@cindex Emacs, info ++@cindex Emacs, online help ++@cindex info ++@cindex online help ++ ++I hope I've included enough examples here to get you well on your way. ++If you want to explore Emacs Lisp further, a programming manual does ++exist, ++@c Yes, some of the stuff in the following sections is redundant, but ++@c TeX barfs if the @ifs are inside the @footnote. ++@iftex ++@footnote{The @cite{GNU Emacs Lisp Reference Manual} may be available ++online in the Info system by typing @kbd{C-h i m Emacs Lisp ++@key{RET}}. It is also available online at @* ++@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You ++can also order a printed manual, which has the desirable side-effect ++of helping to support the Free Software Foundation which made all this ++great software available. You can find an order form by running ++@kbd{C-h C-d}, or you can request an order form from @i{gnu at ++gnu.org}.} ++@end iftex ++@ifinfo ++@footnote{@xref{Top, The GNU Emacs Lisp Reference Manual, , elisp, GNU ++Emacs Lisp Reference Manual}, which may be available online in the ++Info system. It is also available online at ++@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You ++can also order a printed manual, which has the desirable side-effect ++of helping to support the Free Software Foundation which made all this ++great software available. You can find an order form by running ++@kbd{C-h C-d}, or you can request an order form from @i{gnu at ++gnu.org}.} ++@end ifinfo ++@ifhtml ++@footnote{The ++@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/, ++The GNU Emacs Lisp Reference Manual} may also be available online in ++the Info system by typing @kbd{C-h i m Emacs Lisp @key{RET}}. You can ++also order a printed manual, which has the desirable side-effect of ++helping to support the Free Software Foundation which made all this ++great software available. You can find an order form by running ++@kbd{C-h C-d}, or you can request an order form from @i{gnu at ++gnu.org}.} ++@end ifhtml ++and you can look at the code itself for examples. Look in the Emacs ++Lisp directory on your system (such as ++@file{/usr/local/lib/emacs/lisp/mh-e}) and find all the @file{mh-*.el} ++files there. When calling MH-E and other Emacs Lisp functions directly ++from Emacs Lisp code, you'll need to know the correct arguments. Use ++the online help for this. For example, try @kbd{C-h f ++mh-execute-commands @key{RET}}. If you write your own functions, ++please do not prefix your symbols (variables and functions) with ++@samp{mh-}. This prefix is reserved for the MH-E package. To avoid ++conflicts with existing MH-E symbols, use a prefix like @samp{my-} or ++your initials. (Unless, of course, your initials happen to be @emph{mh}!) ++ ++@menu ++* Options:: ++* Ranges:: ++* Folder Selection:: ++@end menu ++ ++@node Options, Ranges, Using This Manual, Using This Manual ++@section Options ++ ++@cindex Emacs, customizing ++@cindex Emacs, setting options ++@cindex customizing MH-E ++@cindex setting options ++@findex customize-option ++@vindex mh-lpr-command-format, example ++ ++Many string or integer options are easy to modify using @kbd{M-x ++customize-option}. For example, to modify the option that controls ++printing, you would run @kbd{M-x customize-option @key{RET} ++mh-lpr-command-format @key{RET}}. In the buffer that appears, modify ++the string to the right of the variable. For example, you may change ++the @command{lpr} command with @samp{nenscript -G -r -2 -i'%s'}. Then ++use the @samp{State} combo box and select @samp{Save for Future ++Sessions}. To read more about @code{mh-lpr-command-format}, see ++@ref{Printing}. ++ ++@cindex nil ++@cindex off, option ++@cindex on, option ++@cindex option, turning on and off ++@cindex t ++@findex customize-option ++@vindex mh-bury-show-buffer-flag, example ++ ++Options can also hold boolean values. In Emacs Lisp, the boolean ++values are @code{nil}, which means false, and @code{t}, which means ++true. The @code{customize-option} function makes it easy to change ++boolean values; simply click on the toggle button in the customize ++buffer to switch between @samp{on} (@code{t}) and @samp{off} ++(@code{nil}). For example, try setting @code{mh-bury-show-buffer-flag} ++to @samp{off} to keep the MH-Show buffer at the top of the buffer ++stack. Use the @samp{State} combo box and choose @samp{Set for Current ++Session} to see how the option affects the show buffer. Then choose ++the @samp{Erase Customization} menu item to reset the option to the ++default, which places the MH-Show buffer at the bottom of the buffer ++stack. ++ ++@vindex mh-mhl-format-file, example ++ ++The text usually says to turn on an option by setting it to a ++@emph{non-@code{nil}} value, because sometimes values other than ++@samp{on} are meaningful. An example of this is the variable ++@code{mh-mhl-format-file} (@pxref{Viewing}). Other options, such as ++hooks, involve a little more Emacs Lisp programming expertise. ++ ++@cindex customization group, @samp{mh} ++@cindex @samp{mh} customization group ++@findex customize-group ++@findex mh-customize ++ ++You can browse all of the MH-E options with the @code{customize-group} ++function. Try entering @kbd{M-x customize-group @key{RET} mh ++@key{RET}} to view the top-level options as well as buttons for all of ++the MH-E customization groups. Another way to view the MH-E ++customization group is to use @kbd{M-x mh-customize @key{RET}}. ++ ++@node Ranges, Folder Selection, Options, Using This Manual ++@section Ranges ++ ++@c Sync with mh-folder-mode docstring. ++ ++@cindex message abbreviations ++@cindex message ranges ++@cindex ranges ++ ++Many commands that operate on individual messages, such as ++@code{mh-forward} or @code{mh-refile-msg} take a @code{RANGE} ++argument. This argument can be used in several ways. ++ ++@kindex C-u, with ranges ++ ++If you provide the prefix argument @kbd{C-u} to these commands, then ++you will be prompted for the message range. This can be any valid MH ++range which can include messages, sequences (@pxref{Sequences}), and ++the abbreviations (described in the @command{mh}(1) man page): ++ ++@table @samp ++@item - ++Indicates all messages in the range to , inclusive. The ++range must be nonempty. ++@c ------------------------- ++@item :N ++@itemx :+N ++@itemx :-N ++Up to N messages beginning with (or ending with) message num. Num may ++be any of the predefined symbols: first, prev, cur, next or last. ++@c ------------------------- ++@item first:N ++@itemx prev:N ++@itemx next:N ++@itemx last:N ++The first, previous, next or last messages, if they exist. ++@c ------------------------- ++@item all ++All of the messages. ++@end table ++ ++For example, a range that shows all of these things is @samp{1 2 3 ++5-10 last:5 unseen}. ++ ++@vindex transient-mark-mode ++ ++If the option @code{transient-mark-mode} is turned on and you set a ++region in the MH-Folder buffer, then the MH-E command will perform the ++operation on all messages in that region. ++ ++@cindex @samp{mh-range} customization group ++@cindex customization group, @samp{mh-range} ++ ++The @samp{mh-range} customization group contains a single option which ++affects how ranges are interpreted. ++ ++@vtable @code ++@item mh-interpret-number-as-range-flag ++On means interpret a number as a range (default: @samp{on}). ++@end vtable ++ ++@vindex mh-interpret-number-as-range-flag ++ ++Since one of the most frequent ranges used is @samp{last:N}, MH-E will ++interpret input such as @samp{200} as @samp{last:200} if the ++@code{mh-interpret-number-as-range-flag} option is on (which is the ++default). If you need to scan just the message 200, then use the range ++@samp{200:1} or @samp{200-200}. ++ ++@node Folder Selection, , Ranges, Using This Manual ++@section Folder Selection ++ ++@cindex completion, folders ++@cindex folders, completion ++@cindex folders, selecting ++ ++When you choose a folder in MH-E via a command such as @kbd{o} ++(@code{mh-refile-msg}), completion is used to enter the folder ++@ifnothtml ++(@pxref{Completion, , , emacs, The GNU Emacs Manual}). ++@end ifnothtml ++@ifhtml ++(see the section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Completion.html, ++Completion} in @cite{The GNU Emacs Manual}). ++@end ifhtml ++In addition, MH-E has several ways of choosing a suitable default so ++that the folder can often be selected with a single @key{RET} key. ++ ++@cindex customization group, @samp{mh-folder-selection} ++@cindex @samp{mh-folder-selection} customization group ++ ++The @samp{mh-folder-selection} customization group contains some ++options which are used to help with this. ++ ++@vtable @code ++@item mh-default-folder-for-message-function ++Function to select a default folder for refiling or @samp{Fcc:} ++(default: @code{nil}). ++@c ------------------------- ++@item mh-default-folder-list ++List of addresses and folders (default: @code{nil}). ++@c ------------------------- ++@item mh-default-folder-must-exist-flag ++On means guessed folder name must exist to be used (default: ++@samp{on}). ++@c ------------------------- ++@item mh-default-folder-prefix ++Prefix used for folder names generated from aliases (default: @code{""}). ++@end vtable ++ ++@vindex mh-default-folder-for-message-function ++ ++You can set the option @code{mh-default-folder-for-message-function} ++to a function that provides a default folder for the message to be ++refiled. When this function is called, the current buffer contains the ++message being refiled and point is at the start of the message. This ++function should return the default folder as a string with a leading ++@samp{+} sign. It can also return @code{nil} so that the last folder ++name is used as the default, or an empty string to suppress the ++default entirely. ++ ++Otherwise, the name of the destination folder is derived from the ++sender as follows: ++ ++@enumerate ++@vindex mh-default-folder-list ++@item ++The folder name associated with the first address found in the list ++@code{mh-default-folder-list} is used. Each element in this list ++contains a @samp{Check Recipient} item. If this item is turned on, ++then the address is checked against the recipient instead of the ++sender. This is useful for mailing lists. ++@c ------------------------- ++@vindex mh-default-folder-prefix ++@item ++An alias prefixed by @code{mh-default-folder-prefix} corresponding to ++the address is used. The prefix is used to prevent clutter in your ++mail directory. @xref{Aliases}. ++@end enumerate ++ ++@vindex mh-default-folder-must-exist-flag ++ ++If the derived folder does not exist, and ++@code{mh-default-folder-must-exist-flag} is @code{t}, then the last ++folder name used is suggested. This is useful if you get mail from ++various people for whom you have an alias, but file them all in the ++same project folder. ++ ++@node Incorporating Mail, Reading Mail, Using This Manual, Top ++@chapter Incorporating Your Mail ++ ++@cindex @samp{Folder} menu ++@cindex incorporating ++@cindex menu, @samp{Folder} ++ ++This chapter talks about getting mail from your system mailbox into ++your MH @samp{+inbox} folder. The following command accomplishes that ++and is found in the @samp{Folder} menu. ++ ++@table @kbd ++@cindex @samp{Folder > Incorporate New Mail} menu item ++@cindex menu item, @samp{Folder > Incorporate New Mail} ++@findex mh-inc-folder ++@kindex i ++@item i ++Incorporate new mail into a folder (@code{mh-inc-folder}). ++@end table ++ ++@cindex @samp{mh-inc} customization group ++@cindex customization group, @samp{mh-inc} ++ ++The following options in the @samp{mh-inc} customization group are ++used. ++ ++@vtable @code ++@item mh-inc-prog ++Program to incorporate mail (default: @code{"inc"}). ++@c ------------------------- ++@item mh-inc-spool-list ++Alternate spool files (default: @code{nil}). ++@end vtable ++ ++The following hook is available. ++ ++@vtable @code ++@findex mh-inc-folder ++@item mh-inc-folder-hook ++Hook run by @code{mh-inc-folder} after incorporating mail into a ++folder (default: @code{nil}). ++@end vtable ++ ++@cindex @samp{+inbox} ++@findex mh-inc-folder ++@kindex i ++ ++If at any time you receive new mail, incorporate the new mail into ++your @samp{+inbox} buffer with @kbd{i} (@code{mh-inc-folder}). Note ++that @kbd{i} will display the @samp{+inbox} buffer, even if there ++isn't any new mail. You can incorporate mail from any file into the ++current folder by specifying a prefix argument; you'll be prompted for ++the name of the file to use as well as the destination folder (for ++example, @kbd{C-u i ~/mbox @key{RET} +tmp @key{RET}}). ++ ++@cindex @file{.emacs} ++@cindex Emacs, notification of new mail ++@cindex files, @file{.emacs} ++@cindex new mail ++@cindex notification of new mail ++ ++Emacs can notify you when you have new mail by displaying @samp{Mail} ++in the mode line. To enable this behavior, and to have a clock in the ++mode line as well, add the following to @file{~/.emacs}: ++ ++@findex display-time ++ ++@smalllisp ++(display-time) ++@end smalllisp ++ ++@cindex @command{inc} ++@cindex incorporating ++@cindex MH commands, @command{inc} ++@vindex mh-inc-prog ++@vindex mh-progs ++ ++The name of the program that incorporates new mail is stored in ++@code{mh-inc-prog}; it is @code{"inc"} by default. This program ++generates a one-line summary for each of the new messages. Unless it ++is an absolute pathname, the file is assumed to be in the ++@code{mh-progs} directory (@pxref{Getting Started}). You may also link ++a file to @command{inc} that uses a different format (see ++@samp{mh-profile}(5), and sections ++@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next ++prev} and @uref{@value{MH-BOOK-HOME}/mhstr.html, MH Format Strings} in ++the MH book). You'll then need to modify several variables ++appropriately (@pxref{Scan Line Formats}). ++ ++@vindex mh-inc-spool-list ++ ++You can use the @code{mh-inc-spool-list} variable to direct MH-E to ++retrieve mail from arbitrary spool files other than your system ++mailbox, file it in folders other than your @samp{+inbox}, and assign ++key bindings to incorporate this mail. ++ ++@cindex @command{procmail} ++@cindex @file{.procmailrc} ++@cindex Unix commands, @command{procmail} ++@cindex files, @file{.procmailrc} ++ ++Suppose you are subscribed to the @i{mh-e-devel} mailing list and you ++use @command{procmail} to filter this mail into @file{~/mail/mh-e} ++with the following recipe in @file{.procmailrc}: ++ ++@smallexample ++PATH=$PATH:/usr/bin/mh ++MAILDIR=$HOME/`mhparam Path` ++:0: ++* ^From mh-e-devel-admin@@stop.mail-abuse.org ++mh-e ++@end smallexample ++ ++@findex mh-inc-spool-* ++@kindex I * ++ ++In order to incorporate @file{~/mail/mh-e} into @samp{+mh-e} with an ++@kbd{I m} (@code{mh-inc-spool-mh-e}) command, customize this option, ++and click on the @samp{INS} button. Enter a @samp{Spool File} of ++@samp{~/mail/mh-e}, a @samp{Folder} of @samp{mh-e}, and a @samp{Key ++Binding} of @samp{m}. ++ ++@cindex @command{emacsclient} ++@cindex @command{gnuclient} ++@cindex @command{xbuffy} ++@cindex @samp{gnuserv} ++@cindex Unix commands, @command{emacsclient} ++@cindex Unix commands, @command{gnuclient} ++@cindex Unix commands, @command{xbuffy} ++ ++You can use @command{xbuffy} to automate the incorporation of this ++mail using the Emacs 23 command @command{emacsclient} as follows: ++ ++@smallexample ++box ~/mail/mh-e ++ title mh-e ++ origMode ++ polltime 10 ++ headertime 0 ++ command emacsclient --eval '(mh-inc-spool-mh-e)' ++@end smallexample ++ ++In XEmacs, the command @command{gnuclient} is used in a similar ++fashion. ++ ++@findex mh-inc-folder ++@kindex i ++@vindex mh-inc-folder-hook ++ ++You can set the hook @code{mh-inc-folder-hook}, which is called after ++new mail is incorporated by the @kbd{i} (@code{mh-inc-folder}) ++command. A good use of this hook is to rescan the whole folder either ++after running @kbd{M-x mh-rmail} the first time or when you've changed ++the message numbers from outside of MH-E. ++ ++@findex mh-execute-commands ++@findex mh-rescan-folder, example ++@findex mh-show, example ++@vindex mh-inc-folder-hook, example ++ ++@smalllisp ++@group ++(defun my-mh-inc-folder-hook () ++ "Hook to rescan folder after incorporating mail." ++ (if (buffer-modified-p) ; @r{if outstanding refiles and deletes,} ++ (mh-execute-commands)) ; @r{carry them out} ++ (mh-rescan-folder) ; @r{synchronize with +inbox} ++ (mh-show)) ; @r{show the current message} ++ ++(add-hook 'mh-inc-folder-hook 'my-mh-inc-folder-hook) ++ ++@i{Rescan folder after incorporating new mail via mh-inc-folder-hook} ++ ++@end group ++@end smalllisp ++ ++@node Reading Mail, Folders, Incorporating Mail, Top ++@chapter Reading Your Mail ++ ++@cindex @samp{+inbox} ++@cindex MH-Folder mode ++@cindex MH-Show mode ++@cindex modes, MH-Folder ++@cindex modes, MH-Show ++@cindex reading mail ++@findex mh-rmail ++@kindex F r ++@kindex F v ++@kindex M-x mh-rmail ++ ++The MH-E entry point for reading mail is @kbd{M-x mh-rmail}. This ++command incorporates your mail and creates a buffer called ++@samp{+inbox} in MH-Folder mode. The command @kbd{M-x mh-rmail} shows ++you only new mail, not mail you have already read@footnote{If you want ++to see your old mail as well, use @kbd{F r} to pull all your messages ++into MH-E. Or, give a prefix argument to @code{mh-rmail} so it will ++prompt you for folder to visit like @kbd{F v} (for example, @kbd{C-u ++M-x mh-rmail @key{RET} bob @key{RET}}). @xref{Folders}.}. ++ ++@findex display-time ++@vindex read-mail-command ++ ++There are some commands that need to read mail, such as @kbd{Mouse-2} ++over the @samp{Mail} button that @code{display-time} adds to the mode ++line. You can configure Emacs to have these commands use MH-E by ++setting the option @code{read-mail-command} to @samp{mh-rmail}. ++ ++@cindex @command{scan} ++@cindex @samp{Message} menu ++@cindex MH commands, @command{scan} ++@cindex menu, @samp{Message} ++@cindex scan lines ++ ++The @samp{+inbox} buffer contains @dfn{scan lines}, which are one-line ++summaries of each incorporated message. You can perform most MH ++commands on these messages via one- or two-letter commands in either ++the MH-Folder or MH-Show buffers or by using the @samp{Message} menu. ++See @command{scan}(1) for a description of the contents of the scan ++lines, and see the Figure in @ref{Reading Mail Tour}, for an example. ++ ++@table @kbd ++@kindex ? ++@findex mh-help ++@item ? ++Display cheat sheet for the MH-E commands (@code{mh-help}). ++@c ------------------------- ++@cindex @samp{Message > Show Message} menu item ++@cindex menu item, @samp{Message > Show Message} ++@kindex @key{RET} ++@findex mh-show ++@item @key{RET} ++Display message (@code{mh-show}). ++@c ------------------------- ++@cindex @samp{Message > Show Message with Header} menu item ++@cindex menu item, @samp{Message > Show Message with Header} ++@kindex , (comma) ++@findex mh-header-display ++@item , (comma) ++Display message with all header fields (@code{mh-header-display}). ++@c ------------------------- ++@cindex @samp{Message > Show Message with Preferred Alternative} menu item ++@cindex menu item, @samp{Message > Show Message with Preferred Alternative} ++@kindex : (colon) ++@findex mh-show-preferred-alternative ++@item : (colon) ++Display message with the default preferred alternative ++(@code{mh-show-preferred-alternative}). ++@c ------------------------- ++@kindex ; (semicolon) ++@findex mh-toggle-mh-decode-mime-flag ++@item ; (semicolon) ++Toggle the value of @code{mh-decode-mime-flag} ++(@code{mh-toggle-mh-decode-mime-flag}). ++@c ------------------------- ++@kindex @key{SPC} ++@findex mh-page-msg ++@item @key{SPC} ++Display next page in message (@code{mh-page-msg}). ++@c ------------------------- ++@kindex @key{BS} ++@findex mh-previous-page ++@item @key{BS} ++Display previous page in message (@code{mh-previous-page}). ++@c ------------------------- ++@cindex @samp{Message > Write Message to File...} menu item ++@cindex menu item, @samp{Message > Write Message to File...} ++@kindex > ++@findex mh-write-msg-to-file ++@item > ++Append message to end of file (@code{mh-write-msg-to-file}). ++@c ------------------------- ++@cindex @samp{Message > Pipe Message to Command...} menu item ++@cindex menu item, @samp{Message > Pipe Message to Command...} ++@kindex | ++@findex mh-pipe-msg ++@item | ++Pipe message through shell command (@code{mh-pipe-msg}). ++@c ------------------------- ++@kindex C-d ++@findex mh-delete-msg-no-motion ++@item C-d ++Delete range, don't move to next message ++(@code{mh-delete-msg-no-motion}). ++@c ------------------------- ++@cindex @samp{Message > Delete Message} menu item ++@cindex menu item, @samp{Message > Delete Message} ++@kindex d ++@findex mh-delete-msg ++@item d ++Delete range (@code{mh-delete-msg}). ++@c ------------------------- ++@kindex D ? ++@findex mh-prefix-help ++@item D ? ++Display cheat sheet for the commands of the current prefix in ++minibuffer (@code{mh-prefix-help}). ++@c ------------------------- ++@kindex D @key{SPC} ++@findex mh-page-digest ++@item D @key{SPC} ++Display next message in digest (@code{mh-page-digest}). ++@c ------------------------- ++@kindex D @key{BS} ++@findex mh-page-digest-backwards ++@item D @key{BS} ++Display previous message in digest (@code{mh-page-digest-backwards}). ++@c ------------------------- ++@cindex @samp{Message > Burst Digest Message} menu item ++@cindex menu item, @samp{Message > Burst Digest Message} ++@kindex D b ++@findex mh-burst-digest ++@item D b ++Break up digest into separate messages (@code{mh-burst-digest}). ++@c ------------------------- ++@cindex @samp{Message > Go to Message by Number...} menu item ++@cindex menu item, @samp{Message > Go to Message by Number...} ++@kindex g ++@findex mh-goto-msg ++@item g ++Go to a message (@code{mh-goto-msg}). ++@c ------------------------- ++@kindex k ++@findex mh-delete-subject-or-thread ++@item k ++Delete messages with same subject or thread ++(@code{mh-delete-subject-or-thread}). ++@c ------------------------- ++@kindex K ? ++@findex mh-prefix-help ++@item K ? ++Display cheat sheet for the commands of the current prefix in ++minibuffer (@code{mh-prefix-help}). ++@c ------------------------- ++@kindex K @key{TAB} ++@findex mh-next-button ++@item K @key{TAB} ++Go to the next button (@code{mh-next-button}). ++@c ------------------------- ++@kindex K S-@key{TAB} ++@findex mh-prev-button ++@item K S-@key{TAB} ++Go to the previous button (@code{mh-prev-button}). ++@c ------------------------- ++@kindex K a ++@findex mh-mime-save-parts ++@item K a ++Save attachments (@code{mh-mime-save-parts}). ++@c ------------------------- ++@kindex K e ++@findex mh-display-with-external-viewer ++@item K e ++View attachment externally (@code{mh-display-with-external-viewer}). ++@c ------------------------- ++@kindex K i ++@findex mh-folder-inline-mime-part ++@item K i ++Show attachment verbatim (@code{mh-folder-inline-mime-part}). ++@c ------------------------- ++@kindex K o ++@findex mh-folder-save-mime-part ++@item K o ++Save (output) attachment (@code{mh-folder-save-mime-part}). ++@c ------------------------- ++@kindex K t ++@findex mh-toggle-mime-buttons ++@item K t ++Toggle option @code{mh-display-buttons-for-inline-parts-flag} ++(@code{mh-toggle-mime-buttons}). ++@c ------------------------- ++@kindex K v ++@findex mh-folder-toggle-mime-part ++@item K v ++View attachment (@code{mh-folder-toggle-mime-part}). ++@c ------------------------- ++@cindex @samp{Message > Modify Message} menu item ++@cindex menu item, @samp{Message > Modify Message} ++@kindex M ++@findex mh-modify ++@item M ++Edit message (@code{mh-modify}). ++@c ------------------------- ++@cindex @samp{Message > Go to First Message} menu item ++@cindex menu item, @samp{Message > Go to First Message} ++@kindex M-< ++@findex mh-first-msg ++@item M-< ++Display first message (@code{mh-first-msg}). ++@c ------------------------- ++@cindex @samp{Message > Go to Last Message} menu item ++@cindex menu item, @samp{Message > Go to Last Message} ++@kindex M-> ++@findex mh-last-msg ++@item M-> ++Display last message (@code{mh-last-msg}). ++@c ------------------------- ++@kindex M-n ++@findex mh-next-unread-msg ++@item M-n ++Display next unread message (@code{mh-next-unread-msg}). ++@c ------------------------- ++@kindex M-p ++@findex mh-previous-unread-msg ++@item M-p ++Display previous unread message (@code{mh-previous-unread-msg}). ++@c ------------------------- ++@cindex @samp{Message > Next Message} menu item ++@cindex menu item, @samp{Message > Next Message} ++@kindex n ++@findex mh-next-undeleted-msg ++@item n ++Display next message (@code{mh-next-undeleted-msg}). ++@c ------------------------- ++@cindex @samp{Message > Previous Message} menu item ++@cindex menu item, @samp{Message > Previous Message} ++@kindex p ++@findex mh-previous-undeleted-msg ++@item p ++Display previous message (@code{mh-previous-undeleted-msg}). ++@c ------------------------- ++@kindex P ? ++@findex mh-prefix-help ++@item P ? ++Display cheat sheet for the commands of the current prefix in ++minibuffer (@code{mh-prefix-help}). ++@c ------------------------- ++@kindex P C ++@findex mh-ps-print-toggle-color ++@item P C ++Toggle whether color is used in printing messages ++(@code{mh-ps-print-toggle-color}). ++@c ------------------------- ++@kindex P F ++@findex mh-ps-print-toggle-faces ++@item P F ++Toggle whether printing is done with faces or not ++(@code{mh-ps-print-toggle-faces}). ++@c ------------------------- ++@kindex P f ++@findex mh-ps-print-msg-file ++@item P f ++Print range to file (@code{mh-ps-print-msg-file}). ++@c ------------------------- ++@cindex @samp{Message > Print Message} menu item ++@cindex menu item, @samp{Message > Print Message} ++@kindex P l ++@findex mh-print-msg ++@item P l ++Print range the old fashioned way ++(@code{mh-print-msg}). ++@c ------------------------- ++@kindex P p ++@findex mh-ps-print-msg ++@item P p ++Print range (@code{mh-ps-print-msg}). ++@c ------------------------- ++@kindex X ? ++@findex mh-prefix-help ++@item X ? ++Display cheat sheet for the commands of the current prefix in ++minibuffer (@code{mh-prefix-help}). ++@c ------------------------- ++@cindex @samp{Message > Unpack Uuencoded Message...} menu item ++@cindex menu item, @samp{Message > Unpack Uuencoded Message...} ++@kindex X s ++@kindex X u ++@findex mh-store-msg ++@item X s ++@itemx X u ++Unpack message created with @command{uudecode} or @command{shar} ++(@code{mh-store-msg}). ++@c ------------------------- ++@kindex Mouse-2 ++@findex mh-show-mouse ++@item Mouse-2 ++Move point to mouse event and show message (@code{mh-show-mouse}). ++@end table ++ ++Within the MH-Show buffer, the following command is defined. ++ ++@table @kbd ++@kindex @key{RET} ++@kindex Mouse-1 ++@kindex Mouse-2 ++@findex mh-press-button ++@item @key{RET} ++@itemx Mouse-1 ++@itemx Mouse-2 ++View contents of button (@code{mh-press-button}). ++@end table ++ ++@cindex @samp{mh-show} customization group ++@cindex customization group, @samp{mh-show} ++ ++The following table lists options in the @samp{mh-show} customization ++group that are used while reading mail. ++ ++@vtable @code ++@item mh-bury-show-buffer-flag ++On means show buffer is buried (default: @samp{on}). ++@c ------------------------- ++@item mh-clean-message-header-flag ++On means remove extraneous header fields (default: @samp{on}). ++@c ------------------------- ++@item mh-decode-mime-flag ++On means attachments are handled (default: @samp{on} if the Gnus ++@samp{mm-decode} package is present). ++@c ------------------------- ++@item mh-display-buttons-for-alternatives-flag ++On means display buttons for all alternative attachments (default: ++@samp{off}). ++@c ------------------------- ++@item mh-display-buttons-for-inline-parts-flag ++On means display buttons for all inline attachments (default: ++@samp{off}). ++@c ------------------------- ++@item mh-do-not-confirm-flag ++On means non-reversible commands do not prompt for confirmation ++(default: @samp{off}). ++@c ------------------------- ++@item mh-fetch-x-image-url ++Control fetching of @samp{X-Image-URL:} header field image (default: ++@samp{Never Fetch}). ++@c ------------------------- ++@item mh-graphical-smileys-flag ++On means graphical smileys are displayed (default: @samp{on}). ++@c ------------------------- ++@item mh-graphical-emphasis-flag ++On means graphical emphasis is displayed (default: @samp{on}). ++@c ------------------------- ++@item mh-highlight-citation-style ++Style for highlighting citations (default: @samp{Multicolor}). ++@c ------------------------- ++@item mh-invisible-header-fields-default ++List of hidden header fields (default: a checklist too long to list ++here). ++@c ------------------------- ++@item mh-invisible-header-fields ++Additional header fields to hide (default: @code{nil}). ++@c ------------------------- ++@item mh-lpr-command-format ++Command used to print (default: @code{"lpr -J '%s'"}). ++@c ------------------------- ++@item mh-max-inline-image-height ++Maximum inline image height if @samp{Content-Disposition:} is not ++present (default: 0). ++@c ------------------------- ++@item mh-max-inline-image-width ++Maximum inline image width if @samp{Content-Disposition:} is not ++present(default: 0). ++@c ------------------------- ++@item mh-mhl-format-file ++Specifies the format file to pass to the @command{mhl} program ++(default: @samp{Use Default mhl Format (Printing Only)}). ++@c ------------------------- ++@item mh-mime-save-parts-default-directory ++Default directory to use for @kbd{K a}. ++@c ------------------------- ++@item mh-print-background-flag ++On means messages should be printed in the background (default: ++@samp{off}). ++@c ------------------------- ++@item mh-show-buffer-mode-line-buffer-id ++Format string to produce @code{mode-line-buffer-identification} for ++show buffers (default: @code{" @{show-%s@} %d"}). ++@c ------------------------- ++@item mh-show-maximum-size ++Maximum size of message (in bytes) to display automatically (default: ++0). ++@c ------------------------- ++@item mh-show-use-xface-flag ++On means display face images in MH-Show buffers (default: @samp{on}). ++@c ------------------------- ++@item mh-store-default-directory ++Default directory for @kbd{X s} (default: @samp{Current}). ++@c ------------------------- ++@item mh-summary-height ++Number of lines in MH-Folder buffer (including the mode line) ++(default: depends on size of frame). ++@end vtable ++ ++The following hooks are available. ++ ++@vtable @code ++@item mh-delete-msg-hook ++Hook run after marking each message for deletion (default: @code{nil}). ++@c ------------------------- ++@item mh-show-hook ++Hook run after @key{RET} shows a message (default: @code{nil}). ++@c ------------------------- ++@item mh-show-mode-hook ++Hook run upon entry to @code{mh-show-mode} (default: @code{nil}). ++@end vtable ++ ++The following faces are available. ++ ++@vtable @code ++@item mh-show-cc ++Face used to highlight @samp{cc:} header fields. ++@c ------------------------- ++@item mh-show-date ++Face used to highlight @samp{Date:} header fields. ++@c ------------------------- ++@item mh-show-from ++Face used to highlight @samp{From:} header fields. ++@c ------------------------- ++@item mh-show-header ++Face used to deemphasize less interesting header fields. ++@c ------------------------- ++@item mh-show-pgg-bad ++Bad PGG signature face. ++@c ------------------------- ++@item mh-show-pgg-good ++Good PGG signature face. ++@c ------------------------- ++@item mh-show-pgg-unknown ++Unknown or untrusted PGG signature face. ++@c ------------------------- ++@item mh-show-signature ++Signature face. ++@c ------------------------- ++@item mh-show-subject ++Face used to highlight @samp{Subject:} header fields. ++@c ------------------------- ++@item mh-show-to ++Face used to highlight @samp{To:} header fields. ++@c ------------------------- ++@item mh-show-xface ++X-Face image face. ++@end vtable ++ ++The functions and variables introduced here are explained in more ++detail in the following sections. ++ ++@menu ++* Viewing:: ++* Viewing Attachments:: ++* HTML:: ++* Digests:: ++* Reading PGP:: ++* Printing:: ++* Files and Pipes:: ++* Navigating:: ++* Miscellaneous Commands and Options:: ++@end menu ++ ++@node Viewing, Viewing Attachments, Reading Mail, Reading Mail ++@section Viewing Your Mail ++ ++@findex mh-header-display ++@findex mh-page-msg ++@findex mh-previous-page ++@findex mh-show ++@findex mh-show-mouse ++@kindex , (comma) ++@kindex . (period) ++@kindex @key{BS} ++@kindex @key{RET} ++@kindex @key{SPC} ++@kindex Mouse-2 ++ ++The command @key{RET} (@code{mh-show}) displays the message that the ++cursor is on while @kbd{Mouse-2} (@code{mh-show-mouse}) displays the ++message that the mouse cursor is on. If the message is already ++displayed, it scrolls to the beginning of the message. Use @key{SPC} ++(@code{mh-page-msg}) and @key{BS} (@code{mh-previous-page}) to move ++forwards and backwards one page at a time through the message. You can ++give either of these commands a prefix argument that specifies the ++number of lines to scroll (such as @kbd{10 @key{SPC}}). The @key{SPC} ++command will also show the next undeleted message if it is used at the ++bottom of a message. MH-E normally hides a lot of the superfluous ++header fields that mailers add to a message, but if you wish to see ++all of them, use the command @kbd{,} (comma; ++@code{mh-header-display}). ++ ++@vindex mh-show-maximum-size ++ ++The option @code{mh-show-maximum-size} provides an opportunity to skip ++over large messages which may be slow to load. The default value of 0 ++means that all message are shown regardless of size. ++ ++A litany of options control what displayed messages look like. ++ ++@vindex mh-show-cc ++@vindex mh-show-date ++@vindex mh-show-from ++@vindex mh-show-header ++@vindex mh-show-subject ++@vindex mh-show-to ++ ++First, the appearance of the header fields can be modified by ++customizing the associated face: @code{mh-show-to}, @code{mh-show-cc}, ++@code{mh-show-from}, @code{mh-show-date}, and @code{mh-show-subject}. ++The face @code{mh-show-header} is used to deemphasize the other, less ++interesting, header fields. ++ ++@cindex regular expressions, @code{mh-invisible-header-fields} ++@vindex mh-clean-message-header-flag ++@vindex mh-invisible-header-fields ++@vindex mh-invisible-header-fields-default ++ ++Normally messages are delivered with a handful of uninteresting header ++fields. These are hidden by turning on the option ++@code{mh-clean-message-header-flag} (which it is by default). The ++header fields listed in the option ++@code{mh-invisible-header-fields-default} are hidden, although you can ++check off any field that you would like to see. Header fields that you ++would like to hide that aren't listed can be added to the option ++@code{mh-invisible-header-fields} with a couple of caveats. Regular ++expressions are not allowed. Unique fields should have a @samp{:} ++suffix; otherwise, the element can be used to render invisible an ++entire class of fields that start with the same prefix. If you think a ++header field should be generally ignored, please update ++@uref{https://sourceforge.net/tracker/index.php?func=detail&aid=1916032&group_id=13357&atid=113357, ++SF #1916032}. ++ ++@cindex header field, @samp{Face:} ++@cindex header field, @samp{X-Face:} ++@cindex header field, @samp{X-Image-URL:} ++@cindex @samp{Face:} header field ++@cindex @samp{X-Face:} header field ++@cindex @samp{X-Image-URL:} header field ++@vindex mh-show-use-xface-flag ++ ++MH-E can display the content of @samp{Face:}, @samp{X-Face:}, and ++@samp{X-Image-URL:} header fields. If any of these fields occur in the ++header of your message, the sender's face will appear in the ++@samp{From:} header field. If more than one of these fields appear, ++then the first field found in the order @samp{Face:}, @samp{X-Face:}, ++and @samp{X-Image-URL:} will be used. The option ++@code{mh-show-use-xface-flag} is used to turn this feature on and off. ++This feature will be turned on by default if your system supports it. ++ ++The first header field used, if present, is the Gnus-specific ++@samp{Face:} field@footnote{The @samp{Face:} field appeared in GNU ++Emacs 21 and XEmacs. For more information, see ++@uref{http://quimby.gnus.org/circus/face/}.}. ++ ++@cindex @command{uncompface} ++@cindex Emacs, packages, x-face ++@cindex Unix commands, @command{uncompface} ++@cindex x-face package ++@vindex mh-show-xface ++ ++Next is the traditional @samp{X-Face:} header field@footnote{The ++display of this field requires the ++@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z, ++@command{uncompface} program}. Recent versions of XEmacs have internal ++support for @samp{X-Face:} images. If your version of XEmacs does not, ++then you'll need both @command{uncompface} and the ++@uref{ftp://ftp.jpl.org/pub/elisp/, @samp{x-face} package}.}. MH-E ++renders the foreground and background of the image using the ++associated attributes of the face @code{mh-show-xface}. ++ ++@cindex @command{convert} ++@cindex @command{wget} ++@cindex ImageMagick ++@cindex Unix commands, @command{convert} ++@cindex Unix commands, @command{wget} ++@vindex mh-fetch-x-image-url ++ ++Finally, MH-E will display images referenced by the ++@samp{X-Image-URL:} header field if neither the @samp{Face:} nor the ++@samp{X-Face:} fields are present@footnote{The display of the images ++requires the @uref{http://www.gnu.org/software/wget/wget.html, ++@command{wget} program} to fetch the image and the @command{convert} ++program from the @uref{http://www.imagemagick.org/, ImageMagick ++suite}.}. Of the three header fields this is the most efficient in ++terms of network usage since the image doesn't need to be transmitted ++with every single mail. The option @code{mh-fetch-x-image-url} ++controls the fetching of the @samp{X-Image-URL:} header field image ++with the following values: ++ ++@table @samp ++@item Ask Before Fetching ++You are prompted before the image is fetched. MH-E will remember your ++reply and will either use the already fetched image the next time the ++same URL is encountered or silently skip it if you didn't fetch it the ++first time. This is a good setting. ++@c ------------------------- ++@item Never Fetch ++Images are never fetched and only displayed if they are already ++present in the cache. This is the default. ++@end table ++ ++There isn't a value of @samp{Always Fetch} for privacy and DOS (denial ++of service) reasons. For example, fetching a URL can tip off a spammer ++that you've read his email (which is why you shouldn't blindly answer ++yes if you've set this option to @samp{Ask Before Fetching}). Someone ++may also flood your network and fill your disk drive by sending a ++torrent of messages, each specifying a unique URL to a very large ++file. ++ ++@cindex @file{.mhe-x-image-cache} ++@cindex files, @file{.mhe-x-image-cache} ++ ++The cache of images is found in the directory ++@file{.mhe-x-image-cache} within your MH directory. You can add your ++own face to the @samp{From:} field too. @xref{Picture}. ++ ++@cindex @command{mhl} ++@cindex MH commands, @command{mhl} ++@vindex mh-mhl-format-file ++ ++Normally MH-E takes care of displaying messages itself (rather than ++calling an MH program to do the work). If you'd rather have ++@command{mhl} display the message (within MH-E), change the option ++@code{mh-mhl-format-file} from its default value of @samp{Use Default ++mhl Format (Printing Only)}. You can set this option to @samp{Use ++Default mhl Format} to get the same output as you would get if you ran ++@command{mhl} from the shell. If you have a format file that you want ++MH-E to use, you can set this option to @samp{Specify an mhl Format ++File} and enter the name of your format file (@command{mhl}(1) or ++section @uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in ++the MH book tells you how to write one). Your format file should ++specify a non-zero value for @samp{overflowoffset} to allow MH-E to ++parse the header. Note that @command{mhl} is always used for printing ++and forwarding; in this case, the value of @code{mh-mhl-format-file} ++is consulted if you have specified a format file. ++ ++@cindex citations, highlighting ++@cindex highlighting citations ++@vindex mh-highlight-citation-style ++ ++If the sender of the message has cited other messages in his message, ++then MH-E will highlight these citations to emphasize the sender's ++actual response. The option @code{mh-highlight-citation-style} can be ++customized to change the highlighting style. The @samp{Multicolor} ++method uses a different color for each indentation while the ++@samp{Monotone} method highlights all citations in red. To disable ++highlighting of citations entirely, choose @samp{None}. ++ ++@cindex URLs, highlighting ++@cindex email addresses, highlighting ++@cindex highlighting URLs ++@cindex highlighting email addresses ++@cindex links, following ++@findex goto-address-at-point ++@kindex C-c @key{RET} ++@kindex Mouse-2 ++@vindex goto-address-highlight-p ++ ++Email addresses and URLs in the message are highlighted if the option ++@code{goto-address-highlight-p} is on, which it is by default. To view ++the web page for a highlighted URL or to send a message using a ++highlighted email address, use @kbd{Mouse-2} or @kbd{C-c @key{RET}} ++(@code{goto-address-at-point}). @xref{Sending Mail}, to see how to ++configure Emacs to send the message using MH-E. ++ ++@cindex boldface, showing ++@cindex emphasis ++@cindex italics, showing ++@cindex smileys ++@cindex typesetting ++@cindex underline, showing ++@vindex gnus-emphasis-alist ++@vindex mh-decode-mime-flag ++@vindex mh-graphical-emphasis-flag ++@vindex mh-graphical-smileys-flag ++ ++It is a long standing custom to inject body language using a ++cornucopia of punctuation, also known as the @dfn{smileys}. MH-E can ++render these as graphical widgets if the option ++@code{mh-graphical-smileys-flag} is turned on, which it is by default. ++Smileys include patterns such as :-) and ;-). Similarly, a few ++typesetting features are indicated in ASCII text with certain ++characters. If your terminal supports it, MH-E can render these ++typesetting directives naturally if the option ++@code{mh-graphical-emphasis-flag} is turned on, which it is by ++default. For example, _underline_ will be ++@ifhtml ++@html ++underlined, ++@end html ++@end ifhtml ++@ifnothtml ++underlined, ++@end ifnothtml ++*bold* will appear in @b{bold}, /italics/ will appear in @i{italics}, ++and so on. See the option @code{gnus-emphasis-alist} for the whole ++list. Both of these options are disabled if the option ++@code{mh-decode-mime-flag} is turned off. @xref{Viewing Attachments}. ++ ++@cindex signature separator ++@cindex vCard ++@vindex mh-show-signature ++ ++MH-E normally renders signatures and vCards in italics so that the ++body of the message stands out more. MH-E depends on the presence of ++the @dfn{signature separator} (@code{"-- "}) to do this. You can also ++customize the face @code{mh-show-signature} so the appearance of the ++signature block is more to your liking. ++ ++@vindex mh-show-hook ++@vindex mh-show-mode-hook ++ ++Two hooks can be used to control how messages are displayed. The first ++hook, @code{mh-show-mode-hook}, is called early on in the process of ++the message display. It is usually used to perform some action on the ++message's content. The second hook, @code{mh-show-hook}, is the last ++thing called after messages are displayed. It's used to affect the ++behavior of MH-E in general or when @code{mh-show-mode-hook} is too ++early. ++ ++@cindex MH-Show mode ++@cindex modes, MH-Show ++@vindex mh-show-buffer-mode-line-buffer-id ++ ++For those who like to modify their mode lines, use ++@code{mh-show-buffer-mode-line-buffer-id} to modify the mode line in ++the MH-Show buffers. Place the two escape strings @samp{%s} and ++@samp{%d}, which will display the folder name and the message number, ++respectively, somewhere in the string in that order. The default value ++of @code{"@{show-%s@} %d"} yields a mode line of ++ ++@smallexample ++-----@{show-+inbox@} 4 (MH-Show)--Bot-------------------------------- ++@end smallexample ++ ++@node Viewing Attachments, HTML, Viewing, Reading Mail ++@section Viewing Attachments ++ ++@cindex attachments ++@cindex body parts ++@cindex @command{mhshow} ++@cindex @command{show} ++@cindex MH commands, @command{mhshow} ++@cindex MH commands, @command{show} ++@cindex MIME ++@cindex multimedia mail ++ ++MH has the ability to display @dfn{@sc{mime}} (Multipurpose Internet ++Mail Extensions) messages which are simply messages with additional ++@dfn{body parts} or @dfn{attachments}. You can use the MH commands ++@command{show}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next ++prev} in the MH book.} or @command{mhshow}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/usimim.html#ReMIMa, Reading MIME Mail} in ++the MH book.} from the shell to read @sc{mime} messages@footnote{You ++can call them directly from Emacs if you're running the X Window ++System: type @kbd{M-! xterm -e mhshow @var{message-number}}. You can ++leave out the @samp{xterm -e} if you use @command{mhlist} or ++@command{mhstore}.}. ++ ++@cindex Emacs, packages, mm-decode ++@cindex mm-decode package ++@findex mh-toggle-mh-decode-mime-flag ++@kindex ; (semicolon) ++@vindex mh-decode-mime-flag ++ ++MH-E can handle attachments as well if the Gnus @samp{mm-decode} ++package is present. If so, the option @code{mh-decode-mime-flag} will ++be on. Otherwise, you'll see the @sc{mime} body parts rather than text ++or attachments. There isn't much point in turning off the option ++@code{mh-decode-mime-flag}; however, you can inspect it if it appears ++that the body parts are not being interpreted correctly or toggle it ++with the command @kbd{;} (semicolon; ++@code{mh-toggle-mh-decode-mime-flag}) to view the raw message. This ++option also controls the display of quoted-printable messages and ++other graphical widgets. @xref{Viewing}. ++ ++@cindex buttons ++ ++Attachments in MH-E are indicated by @dfn{buttons} like this: ++ ++@smallexample ++[1. image/jpeg; foo.jpg]... ++@end smallexample ++ ++@findex mh-next-button ++@findex mh-press-button ++@findex mh-prev-button ++@kindex @key{RET} ++@kindex K @key{TAB} ++@kindex K S-@key{TAB} ++@kindex Mouse-1 ++@kindex Mouse-2 ++ ++To view the contents of the button, use either @kbd{Mouse-1} or ++@kbd{Mouse-2} on the button or @key{RET} (@code{mh-press-button}) when ++the cursor is over the button. This command is a toggle so if you use ++it again on the same attachment, it is hidden. If Emacs does not know ++how to display the attachment, then Emacs offers to save the ++attachment in a file. To move the cursor to the next button, use the ++command @kbd{K @key{TAB}} (@code{mh-next-button}). If the end of the ++buffer is reached then the search wraps over to the start of the ++buffer. To move the cursor to the previous button, use the command ++@kbd{K S-@key{TAB}} (@code{mh-prev-button}). If the beginning of the ++buffer is reached then the search wraps over to the end of the buffer. ++ ++@cindex attachments, viewing ++@cindex viewing attachments ++@findex mh-folder-toggle-mime-part ++@kindex K v ++ ++Another way to view the contents of a button is to use the command ++@kbd{K v} (@code{mh-folder-toggle-mime-part}). This command displays ++(or hides) the attachment associated with the button under the cursor. ++If the cursor is not located over a button, then the cursor first ++moves to the next button, wrapping to the beginning of the message if ++necessary. This command has the advantage over the previous commands ++of working from the MH-Folder buffer. You can also provide a numeric ++prefix argument (as in @kbd{4 K v}) to view the attachment labeled ++with that number. If Emacs does not know how to display the ++attachment, then Emacs offers to save the attachment in a file. ++ ++@cindex @file{/etc/mailcap} ++@cindex files, @file{/etc/mailcap} ++@findex mailcap-mime-info ++@findex mh-display-with-external-viewer ++@kindex K e ++ ++If Emacs does not know how to view an attachment, you could save it ++into a file and then run some program to open it. It is easier, ++however, to launch the program directly from MH-E with the command ++@kbd{K e} (@code{mh-display-with-external-viewer}). While you'll most ++likely use this to view spreadsheets and documents, it is also useful ++to use your browser to view HTML attachments with higher fidelity than ++what Emacs can provide. This command displays the attachment ++associated with the button under the cursor. If the cursor is not ++located over a button, then the cursor first moves to the next button, ++wrapping to the beginning of the message if necessary. You can provide ++a numeric prefix argument (as in @kbd{4 K e}) to view the attachment ++labeled with that number. This command tries to provide a reasonable ++default for the viewer by calling the Emacs function ++@code{mailcap-mime-info}. This function usually reads the file ++@file{/etc/mailcap}. ++ ++@cindex attachments, saving ++@cindex saving attachments ++@findex mh-folder-save-mime-part ++@kindex K o ++ ++Use the command @kbd{K o} (@code{mh-folder-save-mime-part}) to save ++attachments (the mnemonic is ``output''). This command saves the ++attachment associated with the button under the cursor. If the cursor ++is not located over a button, then the cursor first moves to the next ++button, wrapping to the beginning of the message if necessary. You can ++also provide a numeric prefix argument (as in @kbd{3 K o}) to save the ++attachment labeled with that number. This command prompts you for a ++filename and suggests a specific name if it is available. ++ ++@cindex @command{mhn} ++@cindex @command{mhstore} ++@cindex MH commands, @command{mhn} ++@cindex MH commands, @command{mhstore} ++@findex mh-mime-save-parts ++@kindex K a ++@vindex mh-mime-save-parts-default-directory ++ ++You can save all of the attachments at once with the command @kbd{K a} ++(@code{mh-mime-save-parts}). The attachments are saved in the ++directory specified by the option ++@code{mh-mime-save-parts-default-directory} unless you use a prefix ++argument (as in @kbd{C-u K a}) in which case you are prompted for the ++directory. These directories may be superseded by MH profile ++components, since this function calls on @command{mhstore} ++(@command{mhn}) to do the work. ++ ++@vindex mh-mime-save-parts-default-directory ++ ++The default value for the option ++@code{mh-mime-save-parts-default-directory} is @samp{Prompt Always} so ++that you are always prompted for the directory in which to save the ++attachments. However, if you usually use the same directory within a ++session, then you can set this option to @samp{Prompt the First Time} ++to avoid the prompt each time. you can make this directory permanent ++by choosing @samp{Directory} and entering the directory's name. ++ ++@cindex attachments, inline ++@cindex inline attachments ++@findex mh-toggle-mime-buttons ++@kindex K t ++@vindex mh-display-buttons-for-inline-parts-flag ++ ++The sender can request that attachments should be viewed inline so ++that they do not really appear like an attachment at all to the ++reader. Most of the time, this is desirable, so by default MH-E ++suppresses the buttons for inline attachments. On the other hand, you ++may receive code or HTML which the sender has added to his message as ++inline attachments so that you can read them in MH-E. In this case, it ++is useful to see the buttons so that you know you don't have to cut ++and paste the code into a file; you can simply save the attachment. If ++you want to make the buttons visible for inline attachments, you can ++use the command @kbd{K t} (@code{mh-toggle-mime-buttons}) to toggle ++the visibility of these buttons. You can turn on these buttons ++permanently by turning on the option ++@code{mh-display-buttons-for-inline-parts-flag}. ++ ++MH-E cannot display all attachments inline however. It can display ++text (including @sc{html}) and images. ++ ++@cindex header field, @samp{Content-Disposition:} ++@cindex inline images ++@cindex @samp{Content-Disposition:} header field ++@vindex mh-max-inline-image-height ++@vindex mh-max-inline-image-width ++ ++Some older mail programs do not insert the needed ++plumbing@footnote{This plumbing is the @samp{Content-Disposition:} ++header field.} to tell MH-E whether to display the attachments inline ++or not. If this is the case, MH-E will display these images inline if ++they are smaller than the window. However, you might want to allow ++larger images to be displayed inline. To do this, you can change the ++options @code{mh-max-inline-image-width} and ++@code{mh-max-inline-image-height} from their default value of zero to ++a large number. The size of your screen is a good choice for these ++numbers. ++ ++@cindex alternatives ++@cindex attachments, alternatives ++@vindex mh-display-buttons-for-alternatives-flag ++ ++Sometimes, a mail program will produce multiple alternatives of an ++attachment in increasing degree of faithfulness to the original ++content. By default, only the preferred alternative is displayed. If ++the option @code{mh-display-buttons-for-alternatives-flag} is on, then ++the preferred part is shown inline and buttons are shown for each of ++the other alternatives. ++ ++@vindex mm-discouraged-alternatives ++ ++Many people prefer to see the @samp{text/plain} alternative rather ++than the @samp{text/html} alternative. To do this in MH-E, customize ++the option @code{mm-discouraged-alternatives}, and add ++@samp{text/html}. The next best alternative, if any, will be shown. ++ ++@findex mh-show-preferred-alternative ++@kindex : (colon) ++ ++Occasionally, though, you might want to see the preferred alternative. ++The command @kbd{:} (@code{mh-show-preferred-alternative}) displays ++the message with the default preferred alternative. This is as if ++@code{mm-discouraged-alternatives} is set to @samp{nil}. Use the ++command @key{RET} (@code{mh-show}) to show the message normally again. ++ ++@kindex K i ++@findex mh-folder-inline-mime-part ++ ++You can view the raw contents of an attachment with the command @kbd{K ++i} (@code{mh-folder-inline-mime-part}). This command displays (or ++hides) the contents of the attachment associated with the button under ++the cursor verbatim. If the cursor is not located over a button, then ++the cursor first moves to the next button, wrapping to the beginning ++of the message if necessary. You can also provide a numeric prefix ++argument (as in @kbd{4 K i}) to view the attachment labeled with that ++number. ++ ++For additional information on buttons, see ++@ifinfo ++@ref{Article Buttons,,,gnus}, and @ref{MIME Commands,,,gnus}. ++@end ifinfo ++@ifnotinfo ++the chapters @uref{http://www.gnus.org/manual/gnus_101.html#SEC101, ++Article Buttons} and ++@uref{http://www.gnus.org/manual/gnus_108.html#SEC108, MIME Commands} ++in the @cite{The Gnus Manual}. ++@end ifnotinfo ++ ++@node HTML, Digests, Viewing Attachments, Reading Mail ++@section HTML ++ ++@cindex HTML ++@cindex Gnus ++ ++MH-E can display messages that have been sent in HTML@footnote{This ++feature depends on a version of Gnus that is at least 5.10.}. The ++content of the message will appear in the MH-Show buffer as you would ++expect if the entire message is HTML, or there is an inline HTML body ++part. However, if there is an HTML body part that is an attachment, ++then you'll see a button like this: ++ ++@smallexample ++[1. text/html; foo.html]... ++@end smallexample ++ ++To see how to read the contents of this body part, see @ref{Viewing ++Attachments}. ++ ++@vindex mm-text-html-renderer ++ ++The browser that MH-E uses is determined by the option ++@code{mm-text-html-renderer}. The default setting is set automatically ++based upon the presence of a known browser on your system. If you wish ++to use a different browser, then set this option accordingly. See the ++documentation for the browser you use for additional information on ++how to use it. In particular, find and disable the option to render ++images as this can tip off spammers that the email address they have ++used is valid. ++ ++@vindex mm-text-html-renderer ++ ++If you're confused about which @code{mm-text-html-renderer} to use, ++here's a brief description of each, sorted by popularity, that ++includes the results of a quick poll of MH-E users from 2005-12-23. ++ ++@table @asis ++@cindex browser, @samp{w3m} ++@cindex @samp{w3m} ++@kindex Mouse-2 ++@item @samp{w3m} 7 ++The @samp{w3m} browser requires an external program. It's quick, ++produces pretty nice output, and best of all, it's the only browser ++that highlights links. These can be clicked with @kbd{Mouse-2} to view ++the content of the link in @samp{w3m}. The @samp{w3m} browser handles ++tables well and actually respects the table's width parameter (which ++can cause text to wrap if the author didn't anticipate that the page ++would be viewed in Emacs). ++@c ------------------------- ++@cindex browser, @samp{w3m-standalone} ++@cindex @samp{w3m-standalone} ++@item @samp{w3m-standalone} 3 ++This browser, along with @samp{nil} for the external browser, are the ++only choices that work without having to download a separate lisp ++package or external program. This browser is quick, but does not show ++links. It handles simple tables but some tables get rendered much ++wider than the Emacs frame. This browser was the only one not to ++handle the escape @samp{–} (it printed a @samp{?}), but it did ++render @samp{®}. ++@c ------------------------- ++@cindex browser, @samp{links} ++@cindex @samp{links} ++@item @samp{links} 1 ++The @samp{links} browser requires an external program. It's quick, and ++produces nicer output than @samp{lynx} on single column mails in ++tables. However, it doesn't show links and it doesn't do as nice a job ++on multi-column tables as some lines wrap. At least it fits in 80 ++columns and thus seems better than @samp{w3} and ++@samp{w3m-standalone}. Converts escapes such as @samp{®} to (R). ++@c ------------------------- ++@cindex browser, @samp{lynx} ++@cindex @samp{lynx} ++@item @samp{lynx} 1 ++The @samp{lynx} browser requires an external program. It's quick and ++produces pretty decent output but it doesn't show links. It doesn't ++seem to do multi-column tables which makes output much cleaner. It ++centers the output and wraps long lines more than most. Handles ++@samp{®}. ++@c ------------------------- ++@item @samp{nil} 1 ++This choice obviously requires an external browser. Like ++@samp{w3m-standalone}, it works out of the box. With this setting, ++HTML messages have a button for the body part which you can view with ++@kbd{K v} (@code{mh-folder-toggle-mime-part}). ++@c ------------------------- ++@cindex browser, @samp{w3} ++@cindex @samp{w3} ++@item @samp{w3} 0 ++This choice does not require an external program as all of the ++rendering is done in lisp. You do need to get the package separately. ++This browser is @strong{slow}, and doesn't appear to have been updated ++since 2001 and the author hasn't responded to my emails. It displays ++unknown tags instead of hiding them, so you get to see all the ++Microsoft crap in certain messages. Tends to make multi-column tables ++wider than even a full-screen Emacs can handle. Like @samp{w3m}, you ++can follow links, but you have to find them first as they are not ++highlighted. Performs well on single-column tables and handles escapes ++such as @samp{®}. ++@c ------------------------- ++@cindex browser, @samp{html2text} ++@cindex @samp{html2text} ++@item @samp{html2text} 0 ++The @samp{html2text} browser requires an external program. I noticed ++that it can do some nasty things with simple HTML mails (like filling ++the entire message as if it were one paragraph, including signature). ++On another message, it displayed half of the HTML tags for some ++reason. ++@end table ++ ++@vindex mm-text-html-renderer ++ ++For a couple more sources of information about ++@code{mm-text-html-renderer}, ++@ifinfo ++@xref{Display Customization,,,emacs-mime}, and the documentation for ++the Gnus command @kbd{W h} (@pxref{Article Washing,,,gnus},). ++@end ifinfo ++@ifnotinfo ++see section @uref{http://www.gnus.org/manual/emacs-mime_6.html, ++Display Customization} in the @cite{The Emacs MIME Manual} and the ++documentation for the Gnus command @kbd{W h} (see section ++@uref{http://www.gnus.org/manual/gnus_99.html, Article Washing} in the ++@cite{The Gnus Manual}). ++@end ifnotinfo ++ ++@cindex @file{.emacs} ++@cindex files, @file{.emacs} ++@findex browse-url-at-mouse ++@kindex S-Mouse-2 ++ ++A useful key binding that you can add to @file{~/.emacs} is the ++following which displays an HTML link or textual URL in an external ++browser when clicked with @kbd{S-mouse-2}. This binding works in any ++buffer, including HTML buffers. ++ ++@smalllisp ++(global-set-key [S-mouse-2] 'browse-url-at-mouse) ++@end smalllisp ++ ++@node Digests, Reading PGP, HTML, Reading Mail ++@section Digests ++ ++@cindex digests ++@findex mh-page-digest ++@findex mh-page-digest-backwards ++@kindex D @key{BS} ++@kindex D @key{SPC} ++@kindex @key{BS} ++@kindex @key{SPC} ++ ++A digest is a message that contains other messages. Special MH-E ++commands let you read digests conveniently. You can use @key{SPC} and ++@key{BS} to page through the digest as if it were a normal message, ++but if you wish to skip to the next message in the digest, use ++@kbd{D @key{SPC}} (@code{mh-page-digest}). To return to a previous message, ++use @kbd{D @key{BS}} (@code{mh-page-digest-backwards}). ++ ++@cindex @command{burst} ++@cindex MH commands, @command{burst} ++@cindex MH-Folder Show mode ++@cindex modes, MH-Folder Show ++@findex mh-burst-digest ++@kindex d ++@kindex D b ++@kindex t ++ ++Another handy command is @kbd{D b} (@code{mh-burst-digest}). This ++command uses the MH command @command{burst}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/burdig.html, Bursting Messages} in the MH ++book.} to break out each message in the digest into its own message. ++Using this command, you can quickly delete unwanted messages, like ++this: Once the digest is split up, toggle out of MH-Folder Show mode ++with @kbd{t} (@pxref{Folders}) so that the scan lines fill the screen ++and messages aren't displayed. Then use @kbd{d} (@pxref{Reading Mail}) ++to quickly delete messages that you don't want to read (based on the ++@samp{Subject:} header field). You can also burst the digest to reply ++directly to the people who posted the messages in the digest. One ++problem you may encounter is that the @samp{From:} header fields are ++preceded with a @samp{>} so that your reply can't create the ++@samp{To:} field correctly. In this case, you must correct the ++@samp{To:} field yourself. This is described later (@pxref{Editing ++Drafts}). ++ ++@node Reading PGP, Printing, Digests, Reading Mail ++@section Signed and Encrypted Messages ++ ++@cindex GPG ++@cindex GnuPG ++@cindex Gnus ++@cindex OpenPGP ++@cindex PGP ++@cindex RFC 3156 ++@cindex encrypted messages ++@cindex security ++@cindex signed messages ++ ++You can read encrypted or signed PGP or GPG messages with ++MH-E@footnote{This feature depends on post-5.10 versions of Gnus. ++@cite{MIME Security with OpenPGP} is documented in ++@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. However, ++MH-E can also decrypt old-style PGP messages that are not in MIME ++format.}. This section assumes that you already have a good ++understanding of GPG and have set up your keys appropriately. ++ ++If someone sends you a signed message, here is what you'll see: ++ ++@smallexample ++@group ++[[PGP Signed Part:Bill Wohler ]] ++This is a signed message. ++ ++[[End of PGP Signed Part]] ++@end group ++@end smallexample ++ ++@cindex keychain ++@cindex key server ++@cindex signed messages ++ ++If the key for the given signature is not in your keychain, you'll be ++given the opportunity to fetch the key from a key server and verify ++the key. If the message is really large, the verification process can ++take a long time. You can press @kbd{C-g} at any time to ++cancel@footnote{Unfortunately in the current version, the validation ++process doesn't display a message so it appears that MH-E has hung. We ++hope that this will be fixed in the future.}. ++ ++If the signature doesn't check out, you might see something like this: ++ ++@smallexample ++@group ++[[PGP Signed Part:Failed]] ++This is a signed message. ++This is garbage added after the signature was made. ++ ++[[End of PGP Signed Part]] ++@end group ++@end smallexample ++ ++@cindex decrypting messages ++ ++If someone sends you an encrypted message, MH-E will ask for your ++passphrase to decrypt the message. You should see something like this: ++ ++@smallexample ++@group ++[[PGP Encrypted Part:OK]] ++ ++[[PGP Signed Part:Bill Wohler ]] ++This is the secret message. ++ ++[[End of PGP Signed Part]] ++ ++[[End of PGP Encrypted Part]] ++@end group ++@end smallexample ++ ++If there is a problem decrypting the message, the button will say: ++ ++@smallexample ++[[PGP Encrypted Part:Failed]] ++@end smallexample ++ ++You can read the contents of this button using the methods described in ++@ref{Viewing Attachments}. If the message were corrupted, you'd see ++this: ++ ++@smallexample ++[[PGP Encrypted Part:Failed] ++Invalid base64 data] ++@end smallexample ++ ++If your passphrase were incorrect, you'd see something like this: ++ ++@smallexample ++[GNUPG:] ENC_TO CD9C88BB610BD9AD 1 0 ++[GNUPG:] USERID_HINT CD9C88BB610BD9AD Bill Wohler ++[GNUPG:] NEED_PASSPHRASE CD9C88BB610BD9AD CD9C88BB610BD9AD 1 0 ++[GNUPG:] BAD_PASSPHRASE CD9C88BB610BD9AD ++gpg: encrypted with 1024-bit RSA key, ID 610BD9AD, created 1997-09-09 ++ "Bill Wohler " ++gpg: public key decryption failed: bad passphrase ++[GNUPG:] BEGIN_DECRYPTION ++[GNUPG:] DECRYPTION_FAILED ++gpg: decryption failed: secret key not available ++[GNUPG:] END_DECRYPTION ++ ++gpg exited abnormally: '2' ++@end smallexample ++ ++@vindex mh-show-pgg-bad ++@vindex mh-show-pgg-good ++@vindex mh-show-pgg-unknown ++ ++The appearance of the buttons is controlled by the faces ++@code{mh-show-pgg-good}, @code{mh-show-pgg-bad}, and ++@code{mh-show-pgg-unknown} depending on the validity of the signature. ++The latter is used whether the signature is unknown or untrusted. ++ ++@cindex @samp{pgg} customization group ++@cindex PGG ++@cindex customization group, @samp{pgg} ++ ++The @samp{pgg} customization group may have some settings which may ++interest you. ++@iftex ++See @cite{The PGG Manual}. ++@end iftex ++@ifinfo ++@xref{Top, , The PGG Manual, pgg, The PGG Manual}. ++@end ifinfo ++@ifhtml ++See ++@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html, ++@cite{The PGG Manual}}. ++@end ifhtml ++ ++@node Printing, Files and Pipes, Reading PGP, Reading Mail ++@section Printing Your Mail ++ ++@cindex printing ++@findex mh-ps-print-msg ++@findex mh-ps-print-msg-file ++@kindex P f ++@kindex P p ++@vindex mh-lpr-command-format ++@vindex mh-print-background-flag ++ ++To print messages in MH-E, use the command @kbd{P p} ++(@code{mh-ps-print-msg}). You can print all the messages in a range ++(as in @kbd{C-u P p 1 3 5-7 last:5 frombob @key{RET}}, ++@pxref{Ranges}). You can also send the output to a file with @kbd{P f} ++(@code{mh-ps-print-msg-file}). This command will print inline text ++attachments but will not decrypt messages. However, when a message is ++displayed in an MH-Show buffer, then that buffer is used verbatim for ++printing with the caveat that only text attachments, if opened inline, ++are printed. Therefore, encrypted messages can be printed by showing ++and decrypting them first. The commands @kbd{P p} and @kbd{P f} do not ++use the options @code{mh-lpr-command-format} or ++@code{mh-print-background-flag}, described below. ++ ++@findex mh-ps-print-toggle-color ++@kindex P C ++@vindex ps-print-color-p ++ ++Colors are emulated on black-and-white printers with shades of gray. ++This might produce illegible output, even if your screen colors only ++use shades of gray. If this is the case, try using the command @kbd{P ++C} (@code{mh-ps-print-toggle-color}) to toggle between color, no ++color, and a black and white representation of the colors and see ++which works best. You change this setting permanently by customizing ++the option @code{ps-print-color-p}. ++ ++@findex mh-ps-print-toggle-faces ++@kindex P F ++ ++Another related function is the command @kbd{P F} ++(@code{mh-ps-print-toggle-faces}). This command toggles between using ++faces and not. When faces are enabled, the printed message will look ++very similar to the message in the MH-Show buffer. ++ ++@cindex ps-print package ++@cindex Emacs, packages, ps-print ++ ++MH-E uses the @samp{ps-print} package to do the printing, so you can ++customize the printing further by going to the @samp{ps-print} ++customization group. ++ ++@cindex @command{lpr} ++@cindex @command{mhl} ++@cindex MH commands, @command{mhl} ++@cindex Unix commands, @command{lpr} ++@findex mh-print-msg ++@kindex P l ++ ++An alternative to using the @samp{ps-print} package is the command ++@kbd{P l} (@code{mh-print-msg}) (the @i{l} is for @i{l}ine printer or ++@i{l}pr). You can print all the messages in a range. The message is ++formatted with @command{mhl}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in the MH ++book.} and printed with the @command{lpr} command. ++ ++@kindex P f ++@kindex P l ++@kindex P p ++@vindex mh-lpr-command-format ++@vindex mh-print-background-flag ++ ++The command @kbd{P l} uses two options. The option ++@code{mh-lpr-command-format} contains the Unix command line which ++performs the actual printing. The string can contain one escape, ++@samp{%s}, which is replaced by the name of the folder and the message ++number and is useful for print job names. The default setting is ++@code{"lpr -J '%s'"}. I use @code{"mpage -h'%s' -b Letter -H1of -mlrtb ++-P"} which produces a nice header and adds a bit of margin so the text ++fits within my printer's margins. Normally messages are printed in the ++foreground. If this is slow on your system, you may elect to turn on ++the option @code{mh-print-background-flag} to print in the background. ++If you do this, do not delete the message until it is printed or else ++the output may be truncated. These options are not used by the ++commands @kbd{P p} or @kbd{P f}. ++ ++@node Files and Pipes, Navigating, Printing, Reading Mail ++@section Files and Pipes ++ ++@cindex files ++@cindex pipes ++@findex mh-refile-or-write-again ++@findex mh-write-msg-to-file ++@kindex > ++@kindex ! ++ ++MH-E does offer a couple of commands that are not a part of MH@. The ++first one, @kbd{>} (@code{mh-write-msg-to-file}), writes a message to ++a file. You are prompted for the filename. If the file already exists, ++the message is appended to it. You can also write the message to the ++file without the header by specifying a prefix argument (such as ++@kbd{C-u > /tmp/foobar @key{RET}}). Subsequent writes to the same file ++can be made with the command @kbd{!} ++(@code{mh-refile-or-write-again}). ++ ++@findex mh-pipe-msg ++@kindex | ++@kindex l ++ ++You can also pipe the message through a Unix shell command with the ++command @kbd{|} (@code{mh-pipe-msg}). You are prompted for the Unix ++command through which you wish to run your message. If you give a ++prefix argument to this command, the message header is included in the ++text passed to the command (the contrived example @kbd{C-u | lpr} ++would be done with the @kbd{l} command instead). ++ ++@cindex @command{shar} ++@cindex @command{uuencode} ++@cindex Unix commands, @command{shar} ++@cindex Unix commands, @command{uuencode} ++@findex mh-store-msg ++@kindex X s ++@vindex mh-store-default-directory ++ ++If the message is a shell archive @command{shar} or has been run ++through @command{uuencode} use @kbd{X s} (@code{mh-store-msg}) to ++extract the body of the message. The default directory for extraction ++is the current directory; however, you have a chance to specify a ++different extraction directory. The next time you use this command, ++the default directory is the last directory you used. If you would ++like to change the initial default directory, customize the option ++@code{mh-store-default-directory}, change the value from ++@samp{Current} to @samp{Directory}, and then enter the name of the ++directory for storing the content of these messages. ++ ++@findex mh-store-buffer ++@kindex @key{RET} ++@kindex X s ++ ++By the way, @kbd{X s} calls the Emacs Lisp function ++@code{mh-store-buffer}. I mention this because you can use it directly ++if you're editing a buffer that contains a file that has been run ++through @command{uuencode} or @command{shar}. For example, you can ++extract the contents of the current buffer in your home directory by ++typing @kbd{M-x mh-store-buffer @key{RET} ~ @key{RET}}. ++ ++@node Navigating, Miscellaneous Commands and Options, Files and Pipes, Reading Mail ++@section Navigating ++ ++@cindex moving between messages ++@cindex navigation ++@findex mh-first-msg ++@findex mh-goto-msg ++@findex mh-last-msg ++@findex mh-next-undeleted-msg ++@findex mh-next-unread-msg ++@findex mh-previous-undeleted-msg ++@findex mh-previous-unread-msg ++@kindex g ++@kindex M-< ++@kindex M-> ++@kindex M-n ++@kindex M-p ++@kindex n ++@kindex p ++ ++To move on to the next message, use the command @kbd{n} ++(@code{mh-next-undeleted-msg}); use @kbd{p} ++(@code{mh-previous-undeleted-msg}) to read the previous message. To ++move to the next unread message, use @kbd{M-n} ++(@code{mh-next-unread-msg}); use @kbd{M-p} ++(@code{mh-previous-unread-msg}) to move to the previous unread ++message. These commands can be given a prefix argument to specify how ++many messages to skip (for example, @kbd{5 n}). You can also move to a ++specific message with @kbd{g} (@code{mh-goto-msg}). You can enter the ++message number either before or after typing @kbd{g}. In the latter ++case, Emacs prompts you. Finally, you can go to the first or last ++message with @kbd{M-<} (@code{mh-first-msg}) and @kbd{M->} ++(@code{mh-last-msg}) respectively. ++ ++@cindex MH-Folder mode ++@cindex modes, MH-Folder ++@findex next-line ++@findex previous-line ++@kindex C-n ++@kindex C-p ++@kindex @key{RET} ++ ++You can also use the Emacs commands @kbd{C-p} (@code{previous-line}) ++and @kbd{C-n} (@code{next-line}) to move up and down the scan lines in ++the MH-Folder window. These commands can be used in conjunction with ++@key{RET} to look at deleted or refiled messages. ++ ++@cindex deleting messages ++@findex mh-delete-msg ++@kindex d ++@kindex n ++@kindex p ++ ++To mark a message for deletion, use the command @kbd{d} ++(@code{mh-delete-msg}). A @samp{D} is placed by the message in the ++scan window, and the next undeleted message is displayed. If the ++previous command had been @kbd{p}, then the next message displayed is ++the first undeleted message previous to the message just deleted. Use ++@kbd{n} to force subsequent @kbd{d} commands to move forward to the ++next undeleted message after deleting the message under the cursor. ++You may also specify a range (for example, @kbd{C-u d 1 3 5-7 last:5 ++frombob @key{RET}}, @pxref{Ranges}). ++ ++@findex mh-delete-msg-no-motion ++@kindex C-d ++ ++The command @kbd{C-d} (@code{mh-delete-msg-no-motion}) marks the ++message (or messages in range) for deletion but leaves the cursor at ++the current message in case you wish to perform other operations on ++the message. ++ ++@findex mh-delete-subject ++@findex mh-delete-subject-or-thread ++@findex mh-thread-delete ++@findex mh-undo ++@kindex k ++@kindex T d ++@kindex u ++ ++And to delete more messages faster, you can use @kbd{k} ++(@code{mh-delete-subject-or-thread}) to delete all the messages with ++the same subject as the current message. This command puts these ++messages in a sequence named @samp{subject}. You can undo this action ++by using @kbd{u} (@code{mh-undo}) with a prefix argument and then ++specifying the @samp{subject} sequence. However, if the buffer is ++displaying a threaded view of the folder then @kbd{k} behaves like ++@kbd{T d} (@code{mh-thread-delete}). @xref{Threading}. ++ ++@findex mh-execute-commands ++@kindex x ++ ++However you mark a message for deletion, the command @kbd{x} ++(@code{mh-execute-commands}) actually carries out the deletion ++(@pxref{Folders}). ++ ++@vindex mh-delete-msg-hook ++ ++The hook @code{mh-delete-msg-hook} is called after you mark a message ++for deletion. For example, a past maintainer of MH-E used this once ++when he kept statistics on his mail usage. ++ ++@node Miscellaneous Commands and Options, , Navigating, Reading Mail ++@section Miscellaneous Commands and Options ++ ++This section contains a few more miscellaneous commands and options. ++ ++@cindex editing message ++@findex mh-modify ++@kindex M ++ ++There are times when you need to edit a message. For example, you may ++need to fix a broken Content-Type header field. You can do this with ++the command @kbd{M} (@code{mh-modify}). It displays the raw message in ++an editable buffer. When you are done editing, save and kill the ++buffer as you would any other. ++ ++@findex mh-kill-folder ++@findex mh-pack-folder ++@vindex mh-do-not-confirm-flag ++ ++Commands such as @code{mh-pack-folder} prompt to confirm whether to ++process outstanding moves and deletes or not before continuing. ++Turning on the option @code{mh-do-not-confirm-flag} means that these ++actions will be performed---which is usually desired but cannot be ++retracted---without question@footnote{In previous versions of MH-E, ++this option suppressed the confirmation in @code{mh-kill-folder}. ++Since this kept most users from setting this option, ++@code{mh-kill-folder} was modified in version 6.0 to always ask for ++confirmation subject to @code{mh-kill-folder-suppress-prompt-hook}. ++@xref{Folders}.}. ++ ++@cindex MH-Folder mode ++@cindex modes, MH-Folder ++@vindex mh-summary-height ++ ++The option @code{mh-summary-height} controls the number of scan lines ++displayed in the MH-Folder window, including the mode line. The ++default value of this option is @samp{Automatic} which means that the ++MH-Folder buffer will maintain the same proportional size if the frame ++is resized. If you'd prefer a fixed height, then choose the ++@samp{Fixed Size} option and enter the number of lines you'd like to ++see. ++ ++@vindex mh-bury-show-buffer-flag ++ ++Normally the buffer for displaying messages is buried at the bottom at ++the buffer stack. You may wish to disable this feature by turning off ++the option @code{mh-bury-show-buffer-flag}. One advantage of not ++burying the show buffer is that one can delete the show buffer more ++easily in an electric buffer list because of its proximity to its ++associated MH-Folder buffer. Try running @kbd{M-x ++electric-buffer-list} to see what I mean. ++ ++@cindex @file{.emacs} ++@cindex files, @file{.emacs} ++@cindex reading mail ++ ++Before we leave this section, I'll include a function that I use as a ++front end to MH-E@footnote{Stephen Gildea's favorite binding is ++@kbd{(global-set-key "\C-cr" 'mh-rmail)}.}. It toggles between your ++working window configuration, which may be quite involved---windows ++filled with source, compilation output, man pages, and other ++documentation---and your MH-E window configuration. Like the rest of ++the customization described in this section, simply add the following ++code to @file{~/.emacs}. ++ ++@iftex ++@filbreak ++@end iftex ++ ++@findex mh-rmail, example ++ ++@smalllisp ++@group ++(defvar my-mh-screen-saved nil ++ "Set to non-@code{nil} when MH-E window configuration shown.") ++(defvar my-normal-screen nil "Normal window configuration.") ++(defvar my-mh-screen nil "MH-E window configuration.") ++ ++(defun my-mh-rmail (&optional arg) ++ "Toggle between MH-E and normal screen configurations. ++With non-@code{nil} or prefix argument, @i{inc} mailbox as well ++when going into mail." ++ (interactive "P") ; @r{user callable function, P=prefix arg} ++ (setq my-mh-screen-saved ; @r{save state} ++ (cond ++ ;; @r{Bring up MH-E screen if arg or normal window configuration.} ++ ;; @r{If arg or +inbox buffer doesn't exist, run mh-rmail.} ++ ((or arg (null my-mh-screen-saved)) ++ (setq my-normal-screen (current-window-configuration)) ++ (if (or arg (null (get-buffer "+inbox"))) ++ (mh-rmail) ++ (set-window-configuration my-mh-screen)) ++ t) ; @r{set my-mh-screen-saved to @code{t}} ++ ;; @r{Otherwise, save MH-E screen and restore normal screen.} ++ (t ++ (setq my-mh-screen (current-window-configuration)) ++ (set-window-configuration my-normal-screen) ++ nil)))) ; @r{set my-mh-screen-saved to nil} ++ ++(global-set-key "\C-x\r" 'my-mh-rmail) ;@r{ call with C-x @key{RET}} ++ ++@i{Starting MH-E} ++ ++@end group ++@end smalllisp ++ ++If you type an argument (@kbd{C-u}) or if @code{my-mh-screen-saved} is ++@code{nil} (meaning a non-MH-E window configuration), the current ++window configuration is saved, either the @samp{+inbox} buffer is ++displayed or @code{mh-rmail} is run, and the MH-E window configuration ++is shown. Otherwise, the MH-E window configuration is saved and the ++original configuration is displayed. ++ ++@node Folders, Sending Mail, Reading Mail, Top ++@chapter Organizing Your Mail with Folders ++ ++@cindex @samp{Folder} menu ++@cindex @samp{Message} menu ++@cindex folders ++@cindex menu, @samp{Folder} ++@cindex menu, @samp{Message} ++@cindex using folders ++ ++This chapter discusses the things you can do with folders within MH-E. ++The commands in this chapter are also found in the @samp{Folder} and ++@samp{Message} menus. ++ ++@table @kbd ++@kindex ? ++@findex mh-help ++@item ? ++Display cheat sheet for the MH-E commands (@code{mh-help}). ++@c ------------------------- ++@kindex ! ++@findex mh-refile-or-write-again ++@item ! ++Repeat last output command (@code{mh-refile-or-write-again}). ++@c ------------------------- ++@cindex @samp{Message > Copy Message to Folder...} menu item ++@cindex menu item, @samp{Message > Copy Message to Folder...} ++@kindex c ++@findex mh-copy-msg ++@item c ++Copy range to folder (@code{mh-copy-msg}). ++@c ------------------------- ++@kindex F ? ++@findex mh-prefix-help ++@item F ? ++Display cheat sheet for the commands of the current prefix in ++minibuffer (@code{mh-prefix-help}). ++@c ------------------------- ++@kindex F ' ++@findex mh-index-ticked-messages ++@item F ' ++Display ticked messages (@code{mh-index-ticked-messages}). ++@c ------------------------- ++@kindex F c ++@findex mh-catchup ++@item F c ++Delete range from the @samp{unseen} sequence (@code{mh-catchup}). ++@c ------------------------- ++@kindex F k ++@findex mh-kill-folder ++@item F k ++Remove folder (@code{mh-kill-folder}). ++@c ------------------------- ++@cindex @samp{Folder > List Folders} menu item ++@cindex menu item, @samp{Folder > List Folders} ++@kindex F l ++@findex mh-list-folders ++@item F l ++List all folders (@code{mh-list-folders}). ++@c ------------------------- ++@cindex @samp{Folder > View New Messages} menu item ++@cindex menu item, @samp{Folder > View New Messages} ++@kindex F n ++@findex mh-index-new-messages ++@item F n ++Display unseen messages (@code{mh-index-new-messages}). ++@c ------------------------- ++@cindex @samp{Folder > Pack Folder} menu item ++@cindex menu item, @samp{Folder > Pack Folder} ++@kindex F p ++@findex mh-pack-folder ++@item F p ++Pack folder (@code{mh-pack-folder}). ++@c ------------------------- ++@kindex F q ++@findex mh-index-sequenced-messages ++@item F q ++Display messages in any sequence (@code{mh-index-sequenced-messages}). ++@c ------------------------- ++@cindex @samp{Folder > Rescan Folder} menu item ++@cindex menu item, @samp{Folder > Rescan Folder} ++@kindex F r ++@findex mh-rescan-folder ++@item F r ++Rescan folder (@code{mh-rescan-folder}). ++@c ------------------------- ++@cindex @samp{Folder > Search...} menu item ++@cindex menu item, @samp{Folder > Search...} ++@kindex F s ++@findex mh-search ++@item F s ++Search your MH mail (@code{mh-search}). ++@c ------------------------- ++@cindex @samp{Folder > Sort Folder} menu item ++@cindex menu item, @samp{Folder > Sort Folder} ++@kindex F S ++@findex mh-sort-folder ++@item F S ++Sort folder (@code{mh-sort-folder}). ++@c ------------------------- ++@kindex F u ++@findex mh-undo-folder ++@item F u ++Undo all refiles and deletes in the current folder (@code{mh-undo-folder}). ++@c ------------------------- ++@cindex @samp{Folder > Visit a Folder...} menu item ++@cindex menu item, @samp{Folder > Visit a Folder...} ++@kindex F v ++@findex mh-visit-folder ++@item F v ++Visit folder (@code{mh-visit-folder}). ++@c ------------------------- ++@cindex @samp{Message > Refile Message} menu item ++@cindex menu item, @samp{Message > Refile Message} ++@kindex o ++@findex mh-refile-msg ++@item o ++Refile (output) range into folder (@code{mh-refile-msg}). ++@c ------------------------- ++@cindex @samp{Folder > Quit MH-E} menu item ++@cindex menu item, @samp{Folder > Quit MH-E} ++@kindex q ++@findex mh-quit ++@item q ++Quit the current MH-E folder (@code{mh-quit}). ++@c ------------------------- ++@cindex @samp{Folder > Toggle Show/Folder} menu item ++@cindex menu item, @samp{Folder > Toggle Show/Folder} ++@kindex t ++@findex mh-toggle-showing ++@item t ++Toggle between MH-Folder and MH-Folder Show modes ++(@code{mh-toggle-showing}). ++@c ------------------------- ++@cindex @samp{Message > Undo Delete/Refile} menu item ++@cindex menu item, @samp{Message > Undo Delete/Refile} ++@kindex u ++@findex mh-undo ++@item u ++Undo pending deletes or refiles in range (@code{mh-undo}). ++@c ------------------------- ++@cindex @samp{Message > Execute Delete/Refile} menu item ++@cindex menu item, @samp{Message > Execute Delete/Refile} ++@kindex x ++@findex mh-execute-commands ++@item x ++Process outstanding delete and refile requests ++(@code{mh-execute-commands}). ++@end table ++ ++@cindex @samp{mh-folder} customization group ++@cindex customization group, @samp{mh-folder} ++ ++The @samp{mh-folder} customization group is used to tune these ++commands. ++ ++@vtable @code ++@item mh-new-messages-folders ++Folders searched for the @samp{unseen} sequence (default: ++@code{Inbox}). ++@c ------------------------- ++@item mh-ticked-messages-folders ++Folders searched for @code{mh-tick-seq} (default: @code{t}). ++@c ------------------------- ++@item mh-large-folder ++The number of messages that indicates a large folder (default: 200). ++@c ------------------------- ++@item mh-recenter-summary-flag ++On means to recenter the summary window (default: @samp{off}). ++@c ------------------------- ++@item mh-recursive-folders-flag ++On means that commands which operate on folders do so recursively ++(default: @samp{off}). ++@c ------------------------- ++@item mh-sortm-args ++Additional arguments for @command{sortm} (default: @code{nil}). ++@end vtable ++ ++The following hooks are available. ++ ++@vtable @code ++@item mh-after-commands-processed-hook ++Hook run by @kbd{x} after performing outstanding refile and delete ++requests (default: @code{nil}). ++@c ------------------------- ++@item mh-before-commands-processed-hook ++Hook run by @kbd{x} before performing outstanding refile and delete ++requests (default: @code{nil}). ++@c ------------------------- ++@item mh-before-quit-hook ++Hook run by q before quitting MH-E (default: @code{nil}). ++@c ------------------------- ++@item mh-folder-mode-hook ++Hook run by @code{mh-folder-mode} when visiting a new folder (default: ++@code{nil}). ++@c ------------------------- ++@item mh-kill-folder-suppress-prompt-hook ++Abnormal hook run at the beginning of @code{mh-kill-folder} (default: ++@code{'mh-search-p}). ++@c ------------------------- ++@item mh-pack-folder-hook ++Hook run by @code{mh-pack-folder} after renumbering the messages ++(default: @code{nil}). ++@c ------------------------- ++@item mh-quit-hook ++Hook run by q after quitting MH-E (default: @code{nil}). ++@c ------------------------- ++@item mh-refile-msg-hook ++Hook run by o after marking each message for refiling (default: ++@code{nil}). ++@end vtable ++ ++The following faces are available for customizing the appearance of ++the MH-Folder buffer. @xref{Scan Line Formats}. ++ ++@vtable @code ++@item mh-folder-address ++Recipient face. ++@c ------------------------- ++@item mh-folder-body ++Body text face. ++@c ------------------------- ++@item mh-folder-cur-msg-number ++Current message number face. ++@c ------------------------- ++@item mh-folder-date ++Date face. ++@c ------------------------- ++@item mh-folder-deleted ++Deleted message face. ++@c ------------------------- ++@item mh-folder-followup ++@samp{Re:} face. ++@c ------------------------- ++@item mh-folder-msg-number ++Message number face. ++@c ------------------------- ++@item mh-folder-refiled ++Refiled message face. ++@c ------------------------- ++@vindex mh-scan-format-nmh ++@vindex mh-scan-sent-to-me-sender-regexp ++@item mh-folder-sent-to-me-hint ++Fontification hint face in messages sent directly to us. The detection ++of messages sent to us is governed by the scan format ++@code{mh-scan-format-nmh} and regular expression ++@code{mh-scan-sent-to-me-sender-regexp}. ++@c ------------------------- ++@vindex mh-scan-format-nmh ++@vindex mh-scan-sent-to-me-sender-regexp ++@item mh-folder-scan-format ++Sender face in messages sent directly to us. The detection of messages ++sent to us is governed by the scan format @code{mh-scan-format-nmh} ++and regular expression @code{mh-scan-sent-to-me-sender-regexp}. ++@c ------------------------- ++@item mh-folder-subject ++Subject face. ++@c ------------------------- ++@item mh-folder-tick ++Ticked message face. ++@c ------------------------- ++@item mh-folder-to ++@samp{To:} face. ++@end vtable ++ ++@vindex mh-folder-mode-hook ++ ++The hook @code{mh-folder-mode-hook} is called when visiting a new ++folder in MH-Folder mode. This could be used to set your own key ++bindings, for example: ++ ++@vindex mh-folder-mode-hook, example ++ ++@smalllisp ++@group ++(defvar my-mh-init-done nil ++ "Non-@code{nil} when one-time MH-E settings made.") ++ ++(defun my-mh-folder-mode-hook () ++ "Hook to set key bindings in MH-Folder mode." ++ (if (not my-mh-init-done) ; @r{only need to bind the keys once } ++ (progn ++ (local-set-key "//" 'my-search-msg) ++ (local-set-key "b" 'mh-burst-digest) ; @r{better use of @kbd{b}} ++ (setq my-mh-init-done t)))) ++ ++(add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook) ++ ++(defun my-search-msg () ++ "Search for a regexp in the current message." ++ (interactive) ; @r{user function} ++ (save-window-excursion ++ (other-window 1) ; @r{go to next window} ++ (isearch-forward-regexp))) ; @r{string search; hit return} ++ ; @r{ when done} ++ ++@i{Create additional key bindings via mh-folder-mode-hook} ++ ++@end group ++@end smalllisp ++ ++@cindex @command{folder} ++@cindex @command{refile} ++@cindex MH commands, @command{folder} ++@cindex MH commands, @command{refile} ++@findex mh-refile-msg ++@kindex o ++@vindex mh-refile-msg-hook ++ ++MH-E has analogies for each of the MH @command{folder} and ++@command{refile} commands@footnote{See the sections ++@uref{@value{MH-BOOK-HOME}/fol.html#Youfol, Your Current Folder: ++folder} and @uref{@value{MH-BOOK-HOME}/fol.html#Movref, Moving and ++Linking Messages: refile} in the MH book.}. To refile a message in ++another folder, use the command @kbd{o} (@code{mh-refile-msg}) ++(mnemonic: ``output''). You are prompted for the folder name ++(@pxref{Folder Selection}). Note that this command can also be used to ++create folders. If you specify a folder that does not exist, you will ++be prompted to create it. The hook @code{mh-refile-msg-hook} is called ++after a message is marked to be refiled. ++ ++@findex mh-write-msg-to-file ++@kindex ! ++ ++If you are refiling several messages into the same folder, you can use ++the command @kbd{!} (@code{mh-refile-or-write-again}) to repeat the ++last refile or write (for the description of @kbd{>} ++(@code{mh-write-msg-to-file}), @pxref{Files and Pipes}). You can use a ++range in either case (for example, @kbd{C-u o 1 3 5-7 last:5 frombob ++@key{RET}}, @pxref{Ranges}). ++ ++@cindex expunging refiles and deletes ++@cindex undoing refiles and deletes ++@findex mh-undo ++@kindex u ++ ++If you've deleted a message or refiled it, but changed your mind, you ++can cancel the action before you've executed it. Use @kbd{u} ++(@code{mh-undo}) to undo a refile on or deletion of a single message. ++You can also undo refiles and deletes for messages that are found in a ++given range (@pxref{Ranges}). ++ ++@findex mh-undo-folder ++@kindex F u ++ ++Alternatively, you can use @kbd{F u} (@code{mh-undo-folder}) to undo ++all refiles and deletes in the current folder. ++ ++@findex mh-execute-commands ++@kindex x ++ ++If you've marked messages to be deleted or refiled and you want to go ++ahead and delete or refile the messages, use @kbd{x} ++(@code{mh-execute-commands}). Many MH-E commands that may affect the ++numbering of the messages (such as @kbd{F r} or @kbd{F p}) will ask if ++you want to process refiles or deletes first and then either run ++@kbd{x} for you or undo the pending refiles and deletes. ++ ++@kindex x ++@vindex mh-after-commands-processed-hook ++@vindex mh-before-commands-processed-hook ++@vindex mh-current-folder ++ ++The command @kbd{x} runs @code{mh-before-commands-processed-hook} ++before the commands are processed and ++@code{mh-after-commands-processed-hook} after the commands are ++processed. Variables that are useful with the former hook include ++@code{mh-delete-list} and @code{mh-refile-list} which can be used to ++see which changes will be made to the current folder, ++@code{mh-current-folder}. Variables that are useful with the latter ++hook include @code{mh-folders-changed}, which lists which folders were ++affected by deletes and refiles. This list will always include the ++current folder @code{mh-current-folder}. ++ ++@findex mh-copy-msg ++@kindex c ++@kindex o ++ ++If you wish to copy a message to another folder, you can use the ++command @kbd{c} (@code{mh-copy-msg}) (see the @option{-link} argument ++to @command{refile}(1)). Like the command @kbd{o}, this command ++prompts you for the name of the target folder and you can specify a ++range (@pxref{Ranges}). Note that unlike the command @kbd{o}, the copy ++takes place immediately. The original copy remains in the current ++folder. ++ ++@cindex junk mail ++@cindex MH-Folder mode ++@cindex MH-Folder Show mode ++@cindex modes, MH-Folder ++@cindex modes, MH-Folder Show ++@cindex spam ++@findex mh-toggle-showing ++@kindex t ++ ++The command @kbd{t} (@code{mh-toggle-showing}) switches between ++MH-Folder mode and MH-Folder Show mode@footnote{For you Emacs wizards, ++this is implemented as an Emacs minor mode.}. MH-Folder mode turns off ++the associated show buffer so that you can perform operations on the ++messages quickly without reading them. This is an excellent way to ++prune out your junk mail or to refile a group of messages to another ++folder for later examination. ++ ++@cindex MH-Folder mode ++@cindex MH-Show mode ++@cindex modes, MH-Folder ++@cindex modes, MH-Show ++@cindex moving between messages ++@kindex t ++@vindex mh-recenter-summary-flag ++ ++When you use @kbd{t} to toggle from MH-Folder Show mode to MH-Folder ++mode, the MH-Show buffer is hidden and the MH-Folder buffer is left ++alone. Setting @code{mh-recenter-summary-flag} to a non-@code{nil} ++value causes the toggle to display as many scan lines as possible, ++with the cursor at the middle. The effect of ++@code{mh-recenter-summary-flag} is rather useful, but it can be ++annoying on a slow network connection. ++ ++@findex mh-visit-folder ++@kindex F v ++@vindex mh-large-folder ++ ++When you want to read the messages that you have refiled into folders, ++use the command @kbd{F v} (@code{mh-visit-folder}) to visit the ++folder. You are prompted for the folder name. The folder buffer will ++show just unseen messages if there are any; otherwise, it will show ++all the messages in the buffer as long there are fewer than ++@code{mh-large-folder} messages. If there are more, then you are ++prompted for a range of messages to scan. You can provide a prefix ++argument in order to specify a range of messages to show when you ++visit the folder (@pxref{Ranges}). In this case, regions are not used ++to specify the range and @code{mh-large-folder} is ignored. Note that ++this command can also be used to create folders. If you specify a ++folder that does not exist, you will be prompted to create it. ++ ++@findex mh-search ++@kindex F s ++ ++If you forget where you've refiled your messages, you can find them ++using @kbd{F s} (@code{mh-search}). @xref{Searching}. ++ ++@cindex @command{procmail} ++@cindex @samp{unseen} sequence ++@cindex sequence, @samp{unseen} ++@cindex Unix commands, @command{procmail} ++@cindex unseen messages, viewing ++@findex mh-index-new-messages ++@kindex F n ++@vindex mh-new-messages-folders ++ ++If you use a program such as @command{procmail} to file your incoming ++mail automatically, you can display new, unseen, messages using the ++command @kbd{F n} (@code{mh-index-new-messages}). All messages in the ++@samp{unseen} sequence from the folders in ++@code{mh-new-messages-folders} are listed. However, this list of ++folders can be overridden with a prefix argument: with a prefix ++argument, enter a space-separated list of folders, or nothing to ++search all folders. ++ ++@cindex @samp{tick} sequence ++@cindex sequence, @samp{tick} ++@cindex ticked messages, viewing ++@findex mh-index-ticked-messages ++@kindex F ' ++@vindex mh-ticked-messages-folders ++ ++If you have ticked messages (@pxref{Sequences}), you can display them ++using the command @kbd{F '} (@code{mh-index-ticked-messages}). All ++messages in the @samp{tick} sequence from the folders in ++@code{mh-ticked-messages-folders} are listed. With a prefix argument, ++enter a space-separated list of folders, or nothing to search all ++folders. ++ ++@findex mh-index-sequenced-messages ++@kindex F q ++@vindex mh-new-messages-folders ++ ++You can display messages in any sequence with the command @kbd{F q} ++(@code{mh-index-sequenced-messages}). All messages from the folders in ++@code{mh-new-messages-folders} in the sequence you provide are listed. ++With a prefix argument, enter a space-separated list of folders at the ++prompt, or nothing to search all folders. ++ ++@vindex mh-new-messages-folders ++@vindex mh-recursive-folders-flag ++@vindex mh-ticked-messages-folders ++ ++Set the options @code{mh-new-messages-folders} and ++@code{mh-ticked-messages-folders} to @samp{Inbox} to search the ++@samp{+inbox} folder or @samp{All} to search all of the top level ++folders. Otherwise, list the folders that should be searched with the ++@samp{Choose Folders} menu item. See @code{mh-recursive-folders-flag}. ++ ++@cindex buffers, @samp{*MH-E Folders*} ++@cindex @samp{*MH-E Folders*} ++@findex mh-kill-folder ++@findex mh-list-folders ++@findex mh-pack-folder ++@findex mh-rescan-folder ++@findex mh-sort-folder ++@kindex F k ++@kindex F l ++@kindex F p ++@kindex F r ++@kindex F S ++ ++Other commands you can perform on folders include: @kbd{F l} ++(@code{mh-list-folders}), to place a listing of all the folders in ++your mail directory in a buffer called @samp{*MH-E Folders*} ++(@pxref{Miscellaneous}); @kbd{F k} (@code{mh-kill-folder}), to remove ++a folder; @kbd{F S} (@code{mh-sort-folder}), to sort the messages by ++date (see @command{sortm}(1) to see how to sort by other criteria); ++@kbd{F p} (@code{mh-pack-folder}), to pack a folder, removing gaps ++from the numbering sequence; and @kbd{F r} (@code{mh-rescan-folder}), ++to rescan the folder, which is useful to grab all messages in your ++@samp{+inbox} after processing your new mail for the first time. If ++you don't want to rescan the entire folder, the commands @kbd{F r} or ++@kbd{F p} will accept a range (@pxref{Ranges}). ++ ++@kindex F p ++@vindex mh-pack-folder-hook ++ ++The command @kbd{F p} runs @code{mh-pack-folder-hook} after ++renumbering the messages. A variable that is useful with this hook ++is @code{mh-current-folder}. ++ ++@kindex @key{TAB} ++@vindex mh-recursive-folders-flag ++ ++By default, operations on folders work only one level at a time. Set ++@code{mh-recursive-folders-flag} to non-@code{nil} to operate on all ++folders. This mostly means that you'll be able to see all your folders ++when you press @key{TAB} when prompted for a folder name. ++ ++@findex mh-search-p ++@kindex k ++@vindex mh-kill-folder-suppress-prompt-hooks ++ ++The hook @code{mh-kill-folder-suppress-prompt-hooks} is an abnormal ++hook run at the beginning of the command @kbd{k}. The hook functions ++are called with no arguments and should return a non-nil value to ++suppress the normal prompt when you remove a folder. This is useful ++for folders that are easily regenerated. The default value of ++@code{mh-search-p} suppresses the prompt on folders generated by ++searching. ++ ++@sp 1 ++@center @strong{NOTE} ++ ++@quotation ++Use this hook with care. If there is a bug in your hook which returns ++@code{t} on @samp{+inbox} and you press @kbd{k} by accident in the ++@code{+inbox} folder, you will not be happy. ++@end quotation ++@sp 1 ++ ++@cindex @command{sortm} ++@cindex @file{.mh_profile} ++@cindex files, @file{.mh_profile} ++@cindex MH commands, @command{sortm} ++@cindex MH profile component, @samp{sortm:} ++@cindex @samp{sortm:} MH profile component ++@kindex F S ++@vindex mh-sortm-args ++ ++The option @code{mh-sortm-args} holds extra arguments to pass on to ++the command @command{sortm}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/sorsor.html, Sorting Messages: sortm} in the ++MH book.} when a prefix argument is used with @kbd{F S}. Normally ++default arguments to @command{sortm} are specified in the MH profile. ++This option may be used to provide an alternate view. For example, ++@samp{'(\"-nolimit\" \"-textfield\" \"subject\")} is a useful setting. ++ ++@cindex exiting ++@cindex quitting ++@findex mh-quit ++@kindex q ++ ++When you want to quit using MH-E and go back to editing, you can use ++the @kbd{q} (@code{mh-quit}) command. This buries the buffers of the ++current MH-E folder and restores the buffers that were present when ++you first ran @kbd{M-x mh-rmail}. It also removes any MH-E working ++buffers whose name begins with @samp{ *mh-} or @samp{*MH-E } ++(@pxref{Miscellaneous}). You can later restore your MH-E session by ++selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail} ++again. ++ ++@findex mh-execute-commands ++@kindex q ++@vindex mh-before-quit-hook ++@vindex mh-before-quit-hook, example ++@vindex mh-quit-hook ++@vindex mh-quit-hook, example ++ ++The two hooks @code{mh-before-quit-hook} and @code{mh-quit-hook} are ++called by @kbd{q}. The former one is called before the quit occurs, so ++you might use it to perform any MH-E operations; you could perform ++some query and abort the quit or call @code{mh-execute-commands}, for ++example. The latter is not run in an MH-E context, so you might use it ++to modify the window setup. If you find that @kbd{q} buries a lot of ++buffers that you would rather remove, you can use both ++@code{mh-before-quit-hook} and @code{mh-quit-hook} to accomplish that. ++ ++@smalllisp ++@group ++(defvar my-mh-folder-buffer-to-delete nil ++ "Folder buffer that is being quit.") ++ ++(defun my-mh-before-quit-hook () ++ "Save folder buffer that is to be deleted." ++ (setq my-mh-folder-buffer-to-delete (current-buffer))) ++ ++(defun my-mh-quit-hook () ++ "Kill folder buffer rather than just bury it." ++ (set-buffer my-mh-folder-buffer-to-delete) ++ (if (get-buffer mh-show-buffer) ++ (kill-buffer mh-show-buffer)) ++ (kill-buffer (current-buffer))) ++ ++@i{Kill MH-Folder buffer instead of burying it} ++@end group ++@end smalllisp ++ ++@cindex folders, renaming ++@cindex renaming folders ++@findex dired ++@findex dired-do-rename ++ ++You can use dired to manipulate the folders themselves. For example, I ++renamed my @samp{+out} folder to the more common @samp{+outbox} by ++running dired on my mail directory (@kbd{M-x dired RET ~/Mail RET}), ++moving my cursor to @samp{out} and using the command @kbd{R} ++(@code{dired-do-rename}). ++ ++@node Sending Mail, Editing Drafts, Folders, Top ++@chapter Sending Mail ++ ++@cindex sending mail ++@findex mh-smail ++@kindex M-x mh-smail ++ ++You can send a mail message in several ways. You can call @kbd{M-x ++mh-smail} directly, or from the command line like this: ++ ++@cindex starting from command line ++ ++@smallexample ++$ @kbd{emacs -f mh-smail} ++@end smallexample ++ ++@findex goto-address-at-point ++@vindex mail-user-agent ++ ++There are some commands that need to send a mail message, such as ++@code{goto-address-at-point}. You can configure Emacs to have these ++commands use MH-E by setting the option @code{mail-user-agent} to ++@samp{Emacs interface to MH}. ++ ++@cindex @samp{Message} menu ++@cindex menu, @samp{Message} ++ ++From within MH-E's MH-Folder mode, other methods of sending mail are ++available as well. These can also be found in the @samp{Message} menu. ++ ++@table @kbd ++@cindex @samp{Message > Edit Message Again} menu item ++@cindex menu item, @samp{Message > Edit Message Again} ++@kindex e ++@findex mh-edit-again ++@item e ++Edit a message to send it again (@code{mh-edit-again}). ++@c ------------------------- ++@cindex @samp{Message > Re-edit a Bounced Message} menu item ++@cindex menu item, @samp{Message > Re-edit a Bounced Message} ++@kindex E ++@findex mh-extract-rejected-mail ++@item E ++Edit a message that was returned by the mail system ++(@code{mh-extract-rejected-mail}). ++@c ------------------------- ++@cindex @samp{Message > Forward Message...} menu item ++@cindex menu item, @samp{Message > Forward Message...} ++@kindex f ++@findex mh-forward ++@item f ++Forward message (@code{mh-forward}). ++@c ------------------------- ++@cindex @samp{Message > Reply to Message...} menu item ++@cindex menu item, @samp{Message > Reply to Message...} ++@kindex r ++@findex mh-reply ++@item r ++Reply to a message (@code{mh-reply}). ++@c ------------------------- ++@cindex @samp{Message > Compose a New Message} menu item ++@cindex menu item, @samp{Message > Compose a New Message} ++@kindex s ++@findex mh-send ++@item s ++Compose a message (@code{mh-send}). ++@c ------------------------- ++@cindex @samp{Message > Redistribute Message...} menu item ++@cindex menu item, @samp{Message > Redistribute Message...} ++@kindex M-d ++@findex mh-redistribute ++@item M-d ++Redistribute a message (@code{mh-redistribute}). ++@c ------------------------- ++@findex mh-smail ++@item M-x mh-smail ++Compose a message with the MH mail system. ++@c ------------------------- ++@findex mh-smail-other-window ++@item M-x mh-smail-other-window ++Compose a message with the MH mail system in other window. ++@end table ++ ++@cindex @samp{mh-sending-mail} customization group ++@cindex customization group, @samp{mh-sending-mail} ++ ++In addition, several options from the @samp{mh-sending-mail} ++customization group are useful when sending mail or replying to mail. ++They are summarized in the following table. ++ ++@vtable @code ++@item mh-compose-forward-as-mime-flag ++On means that messages are forwarded as attachments (default: ++@samp{on}). ++@c ------------------------- ++@item mh-compose-letter-function ++Hook run when starting a new draft (default: @code{nil}). ++@c ------------------------- ++@item mh-compose-prompt-flag ++On means prompt for header fields when composing a new draft (default: ++@samp{off}). ++@c ------------------------- ++@item mh-forward-subject-format ++Format string for forwarded message subject (default: @code{"%s: ++%s"}). ++@c ------------------------- ++@item mh-insert-x-mailer-flag ++On means append an @samp{X-Mailer:} header field to the header ++(default: @samp{on}). ++@c ------------------------- ++@item mh-redist-full-contents-flag ++On means the @command{dist} command needs entire letter for ++redistribution (default: @samp{off}). ++@c ------------------------- ++@item mh-reply-default-reply-to ++Sets the person or persons to whom a reply will be sent (default: ++@samp{Prompt}). ++@c ------------------------- ++@item mh-reply-show-message-flag ++On means the MH-Show buffer is displayed using @kbd{r} ++(@code{mh-reply}) (default: @samp{on}). ++@end vtable ++ ++The following hooks are available. ++ ++@vtable @code ++@item mh-annotate-msg-hook ++Hook run by @code{mh-annotate-msg} after annotation (default: ++@code{nil}). ++@c ------------------------- ++@item mh-forward-hook ++Hook run by @code{mh-forward} on a forwarded letter (default: ++@code{nil}). ++@c ------------------------- ++@item mh-letter-mode-hook ++Hook run by @code{mh-letter-mode} on a new letter (default: ++@code{nil}). ++@end vtable ++ ++@findex mh-annotate-msg ++@vindex mh-annotate-list ++@vindex mh-annotate-msg-hook ++@vindex mh-current-folder ++ ++A hook that is called whenever a message is sent and after the scan ++lines and message are annotated is @code{mh-annotate-msg-hook}. Hook ++functions can access the current folder name with ++@code{mh-current-folder} and obtain the message numbers of the ++annotated messages with @code{mh-annotate-list}. ++ ++The rest of the functions and options introduced here are explained in ++more detail in the following sections. ++ ++@menu ++* Composing:: ++* Replying:: ++* Forwarding:: ++* Redistributing:: ++* Editing Again:: ++@end menu ++ ++@node Composing, Replying, Sending Mail, Sending Mail ++@section Composing ++ ++@cindex @file{.emacs} ++@cindex MH-Folder mode ++@cindex composing mail ++@cindex draft ++@cindex files, @file{.emacs} ++@cindex modes, MH-Folder ++@cindex sending mail ++@findex mh-smail ++@findex mh-smail-other-window ++@kindex M-x mh-smail ++@kindex M-x mh-smail-other-window ++ ++Outside of an MH-Folder buffer, you must call either @kbd{M-x ++mh-smail} or @kbd{M-x mh-smail-other-window} to compose a new message. ++The former command always creates a two-window layout with the current ++buffer on top and the draft on the bottom. Use the latter command if ++you would rather preserve the window layout. You may find adding the ++following key bindings to @file{~/.emacs} useful: ++ ++@smalllisp ++(global-set-key "\C-xm" 'mh-smail) ++(global-set-key "\C-x4m" 'mh-smail-other-window) ++@end smalllisp ++ ++@cindex draft folder ++@cindex MH-Letter mode ++@cindex modes, MH-Letter ++@findex mh-send ++@kindex m ++ ++From within a MH-Folder buffer, you can simply use the command @kbd{m} ++(@code{mh-send}). However you invoke @code{mh-send}, your letter ++appears in an Emacs buffer whose mode is MH-Letter (to see what the ++buffer looks like, @pxref{Sending Mail Tour}). MH-Letter mode allows ++you to edit your message, to check the validity of the recipients, to ++insert attachments and other messages into your message, and to send ++the message. We'll go more into depth about editing a ++@dfn{draft}@footnote{I highly recommend that you use a @dfn{draft ++folder} so that you can edit several drafts in parallel. To do so, ++create a folder named @samp{+drafts} for example, and add the profile ++component @samp{Draft-Folder: drafts} (see @code{mh-profile}(5)).} (a ++message you're composing) in just a moment (@pxref{Editing Drafts}). ++ ++@vindex mh-compose-prompt-flag ++ ++If you prefer to be prompted for the recipient and subject fields ++before the MH-Letter buffer appears, turn on the option ++@code{mh-compose-prompt-flag}. ++ ++@cindex header field, @samp{X-Mailer:} ++@cindex @samp{X-Mailer:} header field ++@vindex mh-insert-x-mailer-flag ++ ++MH-E adds an @samp{X-Mailer:} header field to the header that includes ++the version of MH-E and Emacs that you are using. If you don't want to ++participate in our marketing, you can turn off the option ++@code{mh-insert-x-mailer-flag}. ++ ++@cindex @command{repl} ++@cindex @file{components} ++@cindex MH commands, @command{repl} ++@cindex MH-Letter mode ++@cindex Mail mode ++@cindex files, @file{components} ++@cindex modes, MH-Letter ++@cindex modes, Mail ++@vindex mail-mode-hook ++@vindex mh-letter-mode-hook ++@vindex text-mode-hook ++ ++Two hooks are provided to run commands on your freshly created draft. ++The first hook, @code{mh-letter-mode-hook}, allows you to do some ++processing before editing a letter@footnote{Actually, because ++MH-Letter mode inherits from Mail mode, the hooks ++@code{text-mode-hook} and @code{mail-mode-hook} are run (in that ++order) before @code{mh-letter-mode-hook}.}. For example, you may wish ++to modify the header after @command{repl} has done its work, or you ++may have a complicated @file{components} file and need to tell MH-E ++where the cursor should go. Here's an example of how you would use ++this hook. ++ ++@findex mh-insert-signature, example ++ ++@smalllisp ++@group ++(defvar letter-mode-init-done-flag nil ++ "Non-nil means one-time MH-E settings have been made.") ++ ++(defun my-mh-letter-mode-hook () ++ "Prepare letter for editing." ++ (when (not letter-mode-init-done) ; @r{only need to bind the keys once} ++ (local-set-key "\C-ctb" 'add-enriched-text) ++ (local-set-key "\C-cti" 'add-enriched-text) ++ (local-set-key "\C-ctf" 'add-enriched-text) ++ (local-set-key "\C-cts" 'add-enriched-text) ++ (local-set-key "\C-ctB" 'add-enriched-text) ++ (local-set-key "\C-ctu" 'add-enriched-text) ++ (local-set-key "\C-ctc" 'add-enriched-text) ++ (setq letter-mode-init-done t)) ++ (save-excursion ++ (goto-char (point-max)) ; @r{go to end of message to} ++ (mh-insert-signature))) ; @r{insert signature} ++ ++@i{Prepare draft for editing via mh-letter-mode-hook} ++ ++@end group ++@end smalllisp ++ ++The function, @code{add-enriched-text} is defined in the example in ++@ref{Adding Attachments}. ++ ++@vindex mh-compose-letter-function ++@vindex mh-letter-mode-hook ++ ++The second hook, a function really, is ++@code{mh-compose-letter-function}. Like @code{mh-letter-mode-hook}, it ++is called just before editing a new message; however, it is the last ++function called before you edit your message. The consequence of this ++is that you can write a function to write and send the message for ++you. This function is passed three arguments: the contents of the ++@samp{To:}, @samp{Subject:}, and @samp{Cc:} header fields. ++ ++@node Replying, Forwarding, Composing, Sending Mail ++@section Replying to Mail ++ ++@cindex @command{mhl} ++@cindex @file{mhl.reply} ++@cindex MH commands, @command{mhl} ++@cindex files, @file{mhl.reply} ++@cindex replying ++@findex mh-reply ++@kindex r ++ ++To compose a reply to a message, use the @kbd{r} (@code{mh-reply}) ++command. ++ ++When you reply to a message, you are first prompted with @samp{Reply ++to whom?}. You have several choices here. ++ ++@quotation ++@multitable @columnfractions .20 .80 ++@c @headitem Response @tab Reply Goes To ++@c XXX @headitem not yet supported by SourceForge's texi2pdf. ++@item @b{Response} @tab @b{Reply Goes To} ++@c ------------------------- ++@item @kbd{from} ++@tab ++The person who sent the message. This is the default, so @key{RET} is ++sufficient. ++@c ------------------------- ++@item @kbd{to} ++@tab ++Replies to the sender, plus all recipients in the @samp{To:} header field. ++@c ------------------------- ++@item @kbd{cc}@*@kbd{all} ++@tab ++Forms a reply to the addresses in the @samp{Mail-Followup-To:} header ++field if one exists; otherwise forms a reply to the sender, plus all ++recipients. ++@end multitable ++@end quotation ++ ++@cindex @command{repl} ++@cindex MH commands, @command{repl} ++@vindex mh-reply-default-reply-to ++ ++Depending on your answer, @command{repl}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/reprep.html, Replying to Messages: repl} in ++the MH book.} is given a different argument to form your reply. ++Specifically, a choice of @kbd{from} or none at all runs @samp{repl ++-nocc all}, and a choice of @kbd{to} runs @samp{repl -cc to}. Finally, ++either @kbd{cc} or @kbd{all} runs @samp{repl -cc all -nocc me}. If you ++find that most of the time you specify one of these choices when you ++reply to a message, you can change the option ++@code{mh-reply-default-reply-to} from its default value of ++@samp{Prompt} to one of the choices listed above. You can always edit ++the recipients in the draft. ++ ++@cindex @samp{repl:} MH profile component ++@cindex MH profile component, @samp{repl:} ++@cindex MH-Letter mode ++@cindex MH-Show mode ++@cindex draft ++@cindex modes, MH-Letter ++@cindex modes, MH-Show ++ ++Two windows are then created. One window contains the message to which ++you are replying in an MH-Show buffer. Your draft, in MH-Letter mode ++(@pxref{Editing Drafts}), is in the other window. If the reply draft ++was not one that you expected, check the things that affect the ++behavior of @command{repl} which include the @samp{repl:} profile ++component and the @file{replcomps} and @file{replgroupcomps} files. ++ ++If you supply a prefix argument (as in @kbd{C-u r}), the message you ++are replying to is inserted in your reply after having first been run ++through @command{mhl} with the format file @file{mhl.reply}. See ++@command{mhl}(1) or the section ++@uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in the MH ++book to see how you can modify the default @file{mhl.reply} file. ++ ++@vindex mh-yank-behavior ++ ++Alternatively, you can customize the option @code{mh-yank-behavior} ++and choose one of its @samp{Automatically} variants to do the same ++thing. @xref{Inserting Letter}. If you do so, the prefix argument has ++no effect. ++ ++Another way to include the message automatically in your draft is to ++use @samp{repl: -filter repl.filter} in your MH profile. ++ ++@vindex mh-reply-show-message-flag ++ ++If you include the message automatically, you can hide the MH-Show ++buffer by turning off the option @code{mh-reply-show-message-flag}. ++ ++If you wish to customize the header or other parts of the reply draft, ++please see @command{repl}(1) and @code{mh-format}(5). ++ ++@node Forwarding, Redistributing, Replying, Sending Mail ++@section Forwarding Mail ++ ++@cindex @command{forw} ++@cindex draft ++@cindex forwarding ++@cindex MH commands, @command{forw} ++@findex mh-forward ++@kindex f ++@vindex mh-forward-hook ++ ++To forward a message, use the @kbd{f} (@code{mh-forward}) command. You ++are prompted for the @samp{To:} and @samp{cc:} recipients. You are ++given a draft to edit that looks like it would if you had run the MH ++command @command{forw}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/forfor.html, Forwarding Messages: forw} in ++the MH book.}. You can then add some text (@pxref{Editing Drafts}). ++You can forward several messages by using a range (@pxref{Ranges}). ++All of the messages in the range are inserted into your draft. The ++hook @code{mh-forward-hook} is called on the draft. ++ ++@cindex @file{.mh_profile} ++@cindex files, @file{.mh_profile} ++@cindex MH profile component, @samp{forw:} ++@cindex @samp{forw:} MH profile component ++@vindex mh-compose-forward-as-mime-flag ++ ++By default, the option @code{mh-compose-forward-as-mime-flag} is on ++which means that the forwarded messages are included as attachments. ++These are inline attachments so the forwarded message should appear in ++the body of your recipient's mail program. If you would prefer to ++forward your messages verbatim (as text, inline), then turn off this ++option. Forwarding messages verbatim works well for short, textual ++messages, but your recipient won't be able to view any non-textual ++attachments that were in the forwarded message. Be aware that if you ++have @samp{forw: -mime} in your MH profile, then forwarded messages ++will always be included as attachments regardless of the settings of ++@code{mh-compose-forward-as-mime-flag}. ++ ++@vindex mh-forward-subject-format ++ ++The format of the @samp{Subject:} header field for forwarded messages ++is controlled by the option @code{mh-forward-subject-format}. This ++option is a string which includes two escapes (@samp{%s}). The first ++@samp{%s} is replaced with the sender of the original message, and the ++second one is replaced with the original @samp{Subject:}. The default ++value of @code{"%s: %s"} takes a message with the header: ++ ++@smallexample ++@group ++To: Bill Wohler ++Subject: Re: 49er football ++From: Greg DesBrisay ++@end group ++@end smallexample ++ ++and creates a subject header field of: ++ ++@smallexample ++Subject: Greg DesBrisay: Re: 49er football ++@end smallexample ++ ++@node Redistributing, Editing Again, Forwarding, Sending Mail ++@section Redistributing Your Mail ++ ++@cindex @command{dist} ++@cindex MH commands, @command{dist} ++@cindex redistributing ++@findex mh-redistribute ++@kindex M-d ++ ++The command @kbd{M-d} (@code{mh-redistribute}) is similar in function ++to forwarding mail, but it does not allow you to edit the message, nor ++does it add your name to the @samp{From:} header field. It appears to ++the recipient as if the message had come from the original sender. ++When you run this command, you are prompted for the recipients. ++ ++@findex mh-edit-again ++@kindex e ++ ++For more information on redistributing messages, see ++@command{dist}(1). Also investigate the command @kbd{e} ++(@code{mh-edit-again}) for another way to redistribute messages ++(@pxref{Editing Again}). ++ ++@cindex @command{send} ++@cindex MH commands, @command{send} ++@vindex mh-redist-full-contents-flag ++ ++The option @code{mh-redist-full-contents-flag} must be turned on if ++@command{dist}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/disdis.html, Distributing Messages with ++dist} in the MH book.} requires the whole letter for redistribution, ++which is the case if @command{send}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/sensen.html, Sending Some Mail: comp send} ++in the MH book.} is compiled with the @sc{berk} option (which many ++people abhor). If you find that MH will not allow you to redistribute ++a message that has been redistributed before, turn off this option. ++ ++The hook @code{mh-annotate-msg-hook} is run after annotating the ++message and scan line (@pxref{Sending Mail}). ++ ++@node Editing Again, , Redistributing, Sending Mail ++@section Editing Old Drafts and Bounced Messages ++ ++@cindex @file{draft} ++@cindex files, @file{draft} ++@cindex re-editing drafts ++@findex mh-edit-again ++@kindex F v drafts ++@kindex e ++@kindex n ++ ++If you don't complete a draft for one reason or another, and if the ++draft buffer is no longer available, you can pick your draft up again ++with @kbd{e} (@code{mh-edit-again}). If you don't use a draft ++folder, your last @file{draft} file will be used. If you use draft ++folders, you'll need to visit the draft folder with @kbd{F v drafts ++@key{RET}}, use @kbd{n} to move to the appropriate message, and then ++use @kbd{e} to prepare the message for editing. ++ ++@kindex e ++ ++The @kbd{e} command can also be used to take messages that were sent ++to you and to send them to more people. ++ ++@cindex Mailer-Daemon ++@findex mh-extract-rejected-mail ++@kindex C-c C-c ++@kindex E ++ ++Don't use @kbd{e} to re-edit a message from a @i{Mailer-Daemon} who ++complained that your mail wasn't posted for some reason or another. In ++this case, use @kbd{E} (@code{mh-extract-rejected-mail}) to prepare ++the message for editing by removing the @i{Mailer-Daemon} envelope and ++unneeded header fields. Fix whatever addressing problem you had, and ++send the message again with @kbd{C-c C-c}. ++ ++@node Editing Drafts, Aliases, Sending Mail, Top ++@chapter Editing a Draft ++ ++@cindex @samp{Letter} menu ++@cindex MH-Letter mode ++@cindex draft ++@cindex editing draft ++@cindex menu, @samp{Letter} ++@cindex modes, MH-Letter ++ ++When you edit a message that you want to send (called a @dfn{draft} in ++this case), the mode used is MH-Letter. This mode provides several ++commands in addition to the normal Emacs editing commands to help you ++edit your draft. These can also be found in the @samp{Letter} menu. ++ ++@table @kbd ++@kindex @key{SPC} ++@findex mh-letter-complete-or-space ++@item @key{SPC} ++Perform completion or insert space (@code{mh-letter-complete-or-space}). ++@c ------------------------- ++@kindex M-@key{TAB} ++@findex mh-letter-complete ++@item M-@key{TAB} ++Perform completion on header field or word preceding point ++(@code{mh-letter-complete}). ++@c ------------------------- ++@kindex , (comma) ++@findex mh-letter-confirm-address ++@item , (comma) ++Flash alias expansion (@code{mh-letter-confirm-address}). ++@c ------------------------- ++@kindex @key{TAB} ++@findex mh-letter-next-header-field-or-indent ++@item @key{TAB} ++Cycle to next field (@code{mh-letter-next-header-field-or-indent}). ++@c ------------------------- ++@kindex S-@key{TAB} ++@findex mh-letter-previous-header-field ++@item S-@key{TAB} ++Cycle to the previous header field ++(@code{mh-letter-previous-header-field}). ++@c ------------------------- ++@kindex C-c ? ++@findex mh-help ++@item C-c ? ++Display cheat sheet for the MH-E commands (@code{mh-help}). ++@c ------------------------- ++@cindex @samp{Letter > Send This Draft} menu item ++@cindex menu item, @samp{Letter > Send This Draft} ++@kindex C-c C-c ++@findex mh-send-letter ++@item C-c C-c ++Save draft and send message (@code{mh-send-letter}). ++@c ------------------------- ++@kindex C-c C-d ++@findex mh-insert-identity ++@item C-c C-d ++Insert fields specified by the given identity ++(@code{mh-insert-identity}). @xref{Identities}. ++@c ------------------------- ++@cindex @samp{Letter > Pull in All Compositions (MH)} menu item ++@cindex menu item, @samp{Letter > Pull in All Compositions (MH)} ++@kindex C-c C-e ++@findex mh-mh-to-mime ++@item C-c C-e ++Compose @sc{mime} message from MH-style directives ++(@code{mh-mh-to-mime}). ++@c ------------------------- ++@kindex C-c C-f C-a ++@kindex C-c C-f a ++@findex mh-to-field ++@item C-c C-f C-a ++@itemx C-c C-f a ++Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-b ++@kindex C-c C-f b ++@item C-c C-f C-b ++@itemx C-c C-f b ++Move to @samp{Bcc:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-c ++@kindex C-c C-f c ++@item C-c C-f C-c ++@itemx C-c C-f c ++Move to @samp{Cc:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-d ++@kindex C-c C-f d ++@item C-c C-f C-d ++@itemx C-c C-f d ++Move to @samp{Dcc:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-f ++@kindex C-c C-f f ++@findex mh-to-fcc ++@item C-c C-f C-f ++@itemx C-c C-f f ++Move to @samp{Fcc:} header field (@code{mh-to-fcc}). ++@c ------------------------- ++@kindex C-c C-f C-l ++@kindex C-c C-f l ++@item C-c C-f C-l ++@itemx C-c C-f l ++Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-m ++@kindex C-c C-f m ++@item C-c C-f C-m ++@itemx C-c C-f m ++Move to @samp{From:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-r ++@kindex C-c C-f r ++@item C-c C-f C-r ++@itemx C-c C-f r ++Move to @samp{Reply-To:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-s ++@kindex C-c C-f s ++@item C-c C-f C-s ++@itemx C-c C-f s ++Move to @samp{Subject:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-t ++@kindex C-c C-f t ++@item C-c C-f C-t ++@itemx C-c C-f t ++Move to @samp{To:} header field (@code{mh-to-field}). ++@c ------------------------- ++@cindex @samp{Letter > Insert a Message...} menu item ++@cindex menu item, @samp{Letter > Insert a Message...} ++@kindex C-c C-i ++@findex mh-insert-letter ++@item C-c C-i ++Insert a message (@code{mh-insert-letter}). ++@c ------------------------- ++@kindex C-c C-m C-e ++@findex mh-mml-secure-message-encrypt ++@item C-c C-m C-e ++Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}). ++@c ------------------------- ++@cindex @samp{Letter > Compose Forward...} menu item ++@cindex menu item, @samp{Letter > Compose Forward...} ++@kindex C-c C-m C-f ++@kindex C-c C-m f ++@findex mh-compose-forward ++@item C-c C-m C-f ++@itemx C-c C-m f ++Add tag to forward a message (@code{mh-compose-forward}). ++@c ------------------------- ++@cindex @samp{Letter > Compose Get File (MH)...} menu item ++@cindex menu item, @samp{Letter > Compose Get File (MH)...} ++@kindex C-c C-m C-g ++@kindex C-c C-m g ++@findex mh-mh-compose-anon-ftp ++@item C-c C-m C-g ++@itemx C-c C-m g ++Add tag to include anonymous ftp reference to a file ++(@code{mh-mh-compose-anon-ftp}). ++@c ------------------------- ++@cindex @samp{Letter > Compose Insertion...} menu item ++@cindex menu item, @samp{Letter > Compose Insertion...} ++@kindex C-c C-m C-i ++@kindex C-c C-m i ++@findex mh-compose-insertion ++@item C-c C-m C-i ++@itemx C-c C-m i ++Add tag to include a file such as an image or sound ++(@code{mh-compose-insertion}). ++@c ------------------------- ++@cindex @samp{Letter > Pull in All Compositions (MML)} menu item ++@cindex menu item, @samp{Letter > Pull in All Compositions (MML)} ++@kindex C-c C-m C-m ++@kindex C-c C-m m ++@findex mh-mml-to-mime ++@item C-c C-m C-m ++@itemx C-c C-m m ++Compose @sc{mime} message from MML tags (@code{mh-mml-to-mime}). ++@c ------------------------- ++@kindex C-c C-m C-n ++@kindex C-c C-m n ++@findex mh-mml-unsecure-message ++@item C-c C-m C-n ++@itemx C-c C-m n ++Remove any secure message tags (@code{mh-mml-unsecure-message}). ++@c ------------------------- ++@kindex C-c C-m C-s ++@findex mh-mml-secure-message-sign ++@item C-c C-m C-s ++Add tag to sign the message (@code{mh-mml-secure-message-sign}). ++@c ------------------------- ++@cindex @samp{Letter > Compose Compressed tar (MH)...} menu item ++@cindex menu item, @samp{Letter > Compose Compressed tar (MH)...} ++@kindex C-c C-m C-t ++@kindex C-c C-m t ++@findex mh-mh-compose-external-compressed-tar ++@item C-c C-m C-t ++@itemx C-c C-m t ++Add tag to include anonymous ftp reference to a compressed tar file ++(@code{mh-mh-compose-external-compressed-tar}). ++@c ------------------------- ++@cindex @samp{Letter > Revert to Non-MIME Edit (MH)} menu item ++@cindex menu item, @samp{Letter > Revert to Non-MIME Edit (MH)} ++@kindex C-c C-m C-u ++@kindex C-c C-m u ++@findex mh-mh-to-mime-undo ++@item C-c C-m C-u ++@itemx C-c C-m u ++Undo effects of @kbd{C-c C-e} (@code{mh-mh-to-mime-undo}). ++@c ------------------------- ++@kindex C-c C-m C-x ++@kindex C-c C-m x ++@findex mh-mh-compose-external-type ++@item C-c C-m C-x ++@itemx C-c C-m x ++Add tag to refer to a remote file ++(@code{mh-mh-compose-external-type}). ++@c ------------------------- ++@kindex C-c C-m e e ++@findex mh-mml-secure-message-encrypt ++@item C-c C-m e e ++Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}). ++@c ------------------------- ++@kindex C-c C-m e s ++@findex mh-mml-secure-message-signencrypt ++@item C-c C-m e s ++Add tag to encrypt and sign the message@* ++(@code{mh-mml-secure-message-signencrypt}). ++@c ------------------------- ++@kindex C-c C-m s e ++@findex mh-mml-secure-message-signencrypt ++@item C-c C-m s e ++Add tag to encrypt and sign the message@* ++(@code{mh-mml-secure-message-signencrypt}). ++@c ------------------------- ++@kindex C-c C-m s s ++@findex mh-mml-secure-message-sign ++@item C-c C-m s s ++Add tag to sign the message (@code{mh-mml-secure-message-sign}). ++@c ------------------------- ++@cindex @samp{Letter > Split Current Line} menu item ++@cindex menu item, @samp{Letter > Split Current Line} ++@kindex C-c C-o ++@findex mh-open-line ++@item C-c C-o ++Insert a newline and leave point before it (@code{mh-open-line}). ++@c ------------------------- ++@cindex @samp{Letter > Kill This Draft} menu item ++@cindex menu item, @samp{Letter > Kill This Draft} ++@kindex C-c C-q ++@findex mh-fully-kill-draft ++@item C-c C-q ++Quit editing and delete draft message (@code{mh-fully-kill-draft}). ++@c ------------------------- ++@cindex @samp{Letter > Insert Signature} menu item ++@cindex menu item, @samp{Letter > Insert Signature} ++@kindex C-c C-s ++@findex mh-insert-signature ++@item C-c C-s ++Insert signature in message (@code{mh-insert-signature}). ++@c ------------------------- ++@kindex C-c C-t ++@findex mh-letter-toggle-header-field-display ++@item C-c C-t ++Toggle display of header field at point ++(@code{mh-letter-toggle-header-field-display}). ++@c ------------------------- ++@cindex @samp{Letter > Check Recipient} menu item ++@cindex menu item, @samp{Letter > Check Recipient} ++@kindex C-c C-w ++@findex mh-check-whom ++@item C-c C-w ++Verify recipients, showing expansion of any aliases ++(@code{mh-check-whom}). ++@c ------------------------- ++@cindex @samp{Letter > Yank Current Message} menu item ++@cindex menu item, @samp{Letter > Yank Current Message} ++@kindex C-c C-y ++@findex mh-yank-cur-msg ++@item C-c C-y ++Insert the current message into the draft buffer ++(@code{mh-yank-cur-msg}). ++@c ------------------------- ++@kindex C-c M-d ++@findex mh-insert-auto-fields ++@item C-c M-d ++Insert custom fields if recipient is found in ++@code{mh-auto-fields-list} (@code{mh-insert-auto-fields}). ++@xref{Identities}. ++@end table ++ ++@cindex @samp{mh-letter} customization group ++@cindex customization group, @samp{mh-letter} ++ ++Several options from the @samp{mh-letter} customization group are used ++while editing a draft. ++ ++@vtable @code ++@item mh-compose-insertion ++Type of @sc{mime} message tags in messages (default: @samp{MML} if ++available; otherwise @samp{MH}). ++@c ------------------------- ++@item mh-compose-skipped-header-fields ++List of header fields to skip over when navigating in draft (default: ++@code{'("From"} @code{"Organization"} @code{"References"} ++@code{"In-Reply-To"} @code{"X-Face"} @code{"Face"} ++@code{"X-Image-URL"} @code{"X-Mailer")}. ++@c ------------------------- ++@item mh-compose-space-does-completion-flag ++On means @key{SPC} does completion in message header (default: ++@samp{off}). ++@c ------------------------- ++@item mh-delete-yanked-msg-window-flag ++On means delete any window displaying the message (default: @samp{off}). ++@c ------------------------- ++@item mh-extract-from-attribution-verb ++Verb to use for attribution when a message is yanked by @kbd{C-c C-y} ++(default: @code{"wrote:"}). ++@c ------------------------- ++@item mh-ins-buf-prefix ++String to put before each line of a yanked or inserted message ++(default: @code{"> "}). ++@c ------------------------- ++@item mh-letter-complete-function ++Function to call when completing outside of address or folder fields ++(default: @code{ispell-complete-word}). ++@c ------------------------- ++@item mh-letter-fill-column ++Fill column to use in MH-Letter mode (default: 72). ++@c ------------------------- ++@item mh-mml-method-default ++Default method to use in security tags (default: @samp{PGP (MIME)} if ++support for it is available; otherwise @samp{None}). ++@c ------------------------- ++@item mh-signature-file-name ++Source of user's signature (default: @code{"~/.signature"}). ++@c ------------------------- ++@item mh-signature-separator-flag ++On means a signature separator should be inserted (default: ++@samp{on}). ++@c ------------------------- ++@item mh-x-face-file ++File containing X-Face or Face header field to insert in outgoing mail. ++(default: @code{"~/.face"}). ++@c ------------------------- ++@item mh-yank-behavior ++Controls which part of a message is yanked by @kbd{C-c C-y} (default: ++@samp{Body With Attribution}). ++@end vtable ++ ++The following hooks are available. ++ ++@vtable @code ++@item mail-citation-hook ++Hook for modifying a citation just inserted in the mail buffer ++(default: @code{nil}). ++@c ------------------------- ++@item mh-before-send-letter-hook ++Hook run at the beginning of the @kbd{C-c C-c} command (default: ++@samp{nil}). ++@c ------------------------- ++@item mh-mh-to-mime-hook ++Hook run on the formatted letter by @kbd{C-c C-e} (default: ++@samp{nil}). ++@c ------------------------- ++@item mh-insert-signature-hook ++Hook run by @kbd{C-c C-s} after signature has been inserted (default: ++@code{nil}). ++@end vtable ++ ++The following face is available. ++ ++@vtable @code ++@item mh-letter-header-field ++Editable header field value face in draft buffers. ++@end vtable ++ ++The commands and options introduced here are explained in more ++detail in the following sections. ++ ++@menu ++* Editing Message:: ++* Inserting Letter:: ++* Inserting Messages:: ++* Signature:: ++* Picture:: ++* Adding Attachments:: ++* Sending PGP:: ++* Checking Recipients:: ++* Sending Message:: ++* Killing Draft:: ++@end menu ++ ++@node Editing Message, Inserting Letter, Editing Drafts, Editing Drafts ++@section Editing the Message ++ ++@cindex @samp{Bcc:} header field ++@cindex @samp{Cc:} header field ++@cindex @samp{Dcc:} header field ++@cindex @samp{From:} header field ++@cindex @samp{Mail-Followup-To:} header field ++@cindex @samp{Mail-Reply-To:} header field ++@cindex @samp{Reply-To:} header field ++@cindex @samp{Subject:} header field ++@cindex @samp{To:} header field ++@cindex editing header ++@cindex header field, @samp{Bcc:} ++@cindex header field, @samp{Cc:} ++@cindex header field, @samp{Dcc:} ++@cindex header field, @samp{From:} ++@cindex header field, @samp{Mail-Followup-To:} ++@cindex header field, @samp{Mail-Reply-To:} ++@cindex header field, @samp{Reply-To:} ++@cindex header field, @samp{Subject:} ++@cindex header field, @samp{To:} ++@findex mh-to-field ++@kindex C-c C-f C-t ++@kindex C-c C-f t ++ ++Because the header is part of the message, you can edit the header ++fields as you wish. However, several convenience commands exist to ++help you create and edit them. For example, the command @kbd{C-c C-f ++C-t} (@code{mh-to-field}; alternatively, @kbd{C-c C-f t}) moves the ++cursor to the @samp{To:} header field, creating it if necessary. The ++commands for moving to the @samp{Cc:}, @samp{Subject:}, @samp{From:}, ++@samp{Reply-To:}, @samp{Mail-Reply-To:}, @samp{Mail-Followup-To}, ++@samp{Bcc:}, and @samp{Dcc:} header fields are similar. ++ ++@findex mh-to-fcc ++@kindex C-c C-f C-f ++@kindex C-c C-f f ++ ++One command behaves differently from the others, namely, @kbd{C-c C-f ++C-f} (@code{mh-to-fcc}; alternatively, @kbd{C-c C-f f}). This command ++will prompt you for the folder name in which to file a copy of the ++draft. @xref{Folder Selection}. ++ ++@findex indent-relative ++@findex mh-letter-next-header-field-or-indent ++@findex mh-letter-previous-header-field ++@kindex @key{TAB} ++@kindex S-@key{TAB} ++@vindex mh-compose-skipped-header-fields ++@vindex mh-letter-header-field ++ ++Within the header of the message, the command@* @key{TAB} ++(@code{mh-letter-next-header-field-or-indent}) moves between fields ++that are highlighted with the face @code{mh-letter-header-field}, ++skipping those fields listed in ++@code{mh-compose-skipped-header-fields}. After the last field, this ++command then moves point to the message body before cycling back to ++the first field. If point is already past the first line of the ++message body, then this command indents by calling ++@code{indent-relative} with the given prefix argument. The command ++@kbd{S-@key{TAB}} (@code{mh-letter-previous-header-field}) moves ++backwards between the fields and cycles to the body of the message ++after the first field. Unlike the command @key{TAB}, it will always ++take point to the last field from anywhere in the body. ++ ++@cindex alias completion ++@cindex completion ++@cindex spell check ++@findex ispell-complete-word ++@findex mh-letter-complete ++@findex mh-letter-complete-or-space ++@findex mh-letter-confirm-address ++@kindex , (comma) ++@kindex @key{SPC} ++@kindex M-@key{TAB} ++@vindex mh-alias-flash-on-comma ++@vindex mh-compose-space-does-completion-flag ++@vindex mh-letter-complete-function ++ ++If the field contains addresses (for example, @samp{To:} or ++@samp{Cc:}) or folders (for example, @samp{Fcc:}) then the command ++@kbd{M-@key{TAB}} (@code{mh-letter-complete}) will provide alias ++completion (@pxref{Aliases}). In the body of the message, ++@kbd{M-@key{TAB}} runs @code{mh-letter-complete-function} instead, ++which is set to @samp{'ispell-complete-word} by default. The command ++@kbd{M-@key{TAB}} (@code{mh-letter-complete}) takes a prefix argument ++that is passed to the @code{mh-letter-complete-function}. In addition, ++turn on the option @code{mh-compose-space-does-completion-flag} to use ++the command @key{SPC} (@code{mh-letter-complete-or-space}) to perform ++completion in the header as well; use a prefix argument to specify ++more than one space. Addresses are separated by a comma; when you ++press the comma, the command @code{mh-letter-confirm-address} flashes ++the alias expansion in the minibuffer if ++@code{mh-alias-flash-on-comma} is turned on. ++ ++@c XXX Document the replacement for the inaccessible 'long argument. ++ ++@findex mh-letter-toggle-header-field-display ++@kindex C-c C-t ++ ++Use the command @kbd{C-c C-t} ++@code{mh-letter-toggle-header-field-display} to display truncated ++header fields. This command is a toggle so entering it again will hide ++the field. This command takes a prefix argument: if negative then the ++field is hidden, if positive then the field is displayed (for example, ++@kbd{C-u C-c C-t}). ++ ++Be sure to leave a row of dashes or a blank line between the header ++and the body of the message. ++ ++@vindex mh-letter-fill-column ++ ++The body of the message is edited as you would edit any Emacs buffer ++although there are a few commands and options to assist you. You can ++change the fill column in MH-Letter mode with the option ++@code{mh-letter-fill-column}. By default, this option is 72 to allow ++others to quote your message without line wrapping. ++ ++@cindex filling paragraphs ++@cindex paragraphs, filling ++@findex fill-paragraph ++@kindex M-q ++@vindex mh-ins-buf-prefix ++ ++You'll often include messages that were sent from user agents that ++haven't yet realized that paragraphs consist of more than a single ++line. This makes for long lines that wrap in an ugly fashion. You'll ++find that @kbd{M-q} (@code{fill-paragraph}) works well even on these ++quoted messages, even if they are nested, just as long as all of the ++quotes match the value of @code{mh-ins-buf-prefix} (@pxref{Inserting ++Letter}). For example, let's assume you have the following in your ++draft: ++ ++@smallexample ++@group ++> Hopefully this gives you an idea of what I'm currently doing. I'm \ ++not sure yet whether I'm completely satisfied with my setup, but \ ++it's worked okay for me so far. ++@end group ++@end smallexample ++ ++Running @kbd{M-q} on this paragraph produces: ++ ++@smallexample ++@group ++> Hopefully this gives you an idea of what I'm currently doing. I'm not ++> sure yet whether I'm completely satisfied with my setup, but it's ++> worked okay for me so far. ++@end group ++@end smallexample ++ ++@findex mh-open-line ++@findex open-line ++@kindex C-c C-o ++@kindex C-o ++ ++The command @kbd{C-c C-o} (@code{mh-open-line}) is similar to the ++command @kbd{C-o} (@code{open-line}) in that it inserts a newline ++after point. It differs in that it also inserts the right number of ++quoting characters and spaces so that the next line begins in the same ++column as it was. This is useful when breaking up paragraphs in ++replies. For example, if this command was used when point was after ++the first period in the paragraph above, the result would be this: ++ ++@smallexample ++@group ++> Hopefully this gives you an idea of what I'm currently doing. ++ ++> I'm not ++> sure yet whether I'm completely satisfied with my setup, but it's ++> worked okay for me so far. ++@end group ++@end smallexample ++ ++@node Inserting Letter, Inserting Messages, Editing Message, Editing Drafts ++@section Inserting Letter to Which You're Replying ++ ++@cindex inserting messages ++@cindex replying to messages ++@cindex yanking messages ++@findex mh-yank-cur-msg ++@kindex C-c C-y ++@vindex mh-ins-buf-prefix ++ ++It is often useful to insert a snippet of text from a letter that ++someone mailed to provide some context for your reply. The command ++@kbd{C-c C-y} (@code{mh-yank-cur-msg}) does this by adding an ++attribution, yanking a portion of text from the message to which ++you're replying, and inserting @code{mh-ins-buf-prefix} (@samp{> }) ++before each line. ++ ++@smallexample ++@group ++Michael W Thelen wrote: ++ ++> Hopefully this gives you an idea of what I'm currently doing. I'm not ++> sure yet whether I'm completely satisfied with my setup, but it's ++> worked okay for me so far. ++@end group ++@end smallexample ++ ++@vindex mh-extract-from-attribution-verb ++ ++The attribution consists of the sender's name and email address ++followed by the content of the option ++@code{mh-extract-from-attribution-verb}. This option can be set to ++@samp{wrote:}, @samp{a écrit:}, and @samp{schrieb:}. You can also use ++the @samp{Custom String} menu item to enter your own verb. ++ ++@vindex mail-citation-hook ++@vindex mh-ins-buf-prefix ++@vindex mh-yank-behavior ++ ++The prefix @code{"> "} is the default setting for the option ++@code{mh-ins-buf-prefix}. I suggest that you not modify this option ++since it is used by many mailers and news readers: messages are far ++easier to read if several included messages have all been indented by ++the same string. This prefix is not inserted if you use one of the ++supercite flavors of @code{mh-yank-behavior} or you have added a ++@code{mail-citation-hook} as described below. ++ ++@vindex mh-delete-yanked-msg-window-flag ++ ++You can also turn on the @code{mh-delete-yanked-msg-window-flag} ++option to delete the window containing the original message after ++yanking it to make more room on your screen for your reply. ++ ++@cindex Emacs, packages, supercite ++@cindex supercite package ++@kindex r ++@vindex mail-citation-hook ++@vindex mh-yank-behavior ++ ++You can control how the message to which you are replying is yanked ++into your reply using @code{mh-yank-behavior}. To include the entire ++message, including the entire header, use @samp{Body and ++Header}@footnote{If you'd rather have the header cleaned up, use ++@kbd{C-u r} instead of @kbd{r} when replying ++(@pxref{Replying}).}@footnote{In the past you would use this setting ++and set @code{mail-citation-hook} to @samp{supercite}, but this usage ++is now deprecated in favor of the @samp{Invoke supercite} setting.}. ++Use @samp{Body} to yank just the body without the header. To yank only ++the portion of the message following the point, set this option to ++@samp{Below Point}. ++ ++Choose @samp{Invoke supercite}@footnote{@emph{Supercite} is a ++full-bodied, full-featured, citation package that comes standard with ++Emacs.} to pass the entire message and header through supercite. ++ ++@vindex mh-extract-from-attribution-verb ++ ++If the @samp{Body With Attribution} setting is used, then the message ++minus the header is yanked and a simple attribution line is added at ++the top using the value of the option ++@code{mh-extract-from-attribution-verb}. This is the default. ++ ++@kindex C-c C-y ++@vindex mh-delete-yanked-msg-window-flag ++ ++If the @samp{Invoke supercite} or @samp{Body With Attribution} ++settings are used, the @samp{-noformat} argument is passed to the ++@command{repl} program to override a @samp{-filter} or @samp{-format} ++argument. These settings also have @samp{Automatically} variants that ++perform the action automatically when you reply so that you don't need ++to use @kbd{C-c C-y} at all. Note that this automatic action is only ++performed if the show buffer matches the message being replied to. ++People who use the automatic variants tend to turn on the option ++@code{mh-delete-yanked-msg-window-flag} as well so that the show ++window is never displayed. ++ ++@vindex mh-yank-behavior ++ ++If the show buffer has a region, the option @code{mh-yank-behavior} is ++ignored unless its value is one of @samp{Attribution} variants in ++which case the attribution is added to the yanked region. ++ ++@findex trivial-cite ++@vindex mail-citation-hook ++@vindex mh-ins-buf-prefix ++@vindex mh-yank-behavior ++ ++If this isn't enough, you can gain full control over the appearance of ++the included text by setting @code{mail-citation-hook} to a function ++that modifies it. This hook is ignored if the option ++@code{mh-yank-behavior} is set to one of the supercite flavors. ++Otherwise, this option controls how much of the message is passed to ++the hook. The function can find the citation between point and mark ++and it should leave point and mark around the modified citation text ++for the next hook function. The standard prefix ++@code{mh-ins-buf-prefix} is not added if this hook is set. ++ ++@cindex Emacs, packages, trivial-cite ++@cindex trivial-cite package ++@vindex mh-yank-behavior ++ ++For example, if you use the hook function ++@uref{http://shasta.cs.uiuc.edu/~lrclause/tc.html, ++@code{trivial-cite}} (which is NOT part of Emacs), set ++@code{mh-yank-behavior} to @samp{Body and Header}. ++ ++@node Inserting Messages, Signature, Inserting Letter, Editing Drafts ++@section Inserting Messages ++ ++@cindex inserting messages ++@findex mh-insert-letter ++@findex mh-yank-behavior ++@kindex C-c C-i ++@vindex mh-ins-buf-prefix ++@vindex mh-invisible-header-fields-compiled ++@vindex mh-yank-behavior ++ ++Messages can be inserted with @kbd{C-c C-i} (@code{mh-insert-letter}). ++This command prompts you for the folder and message number, which ++defaults to the current message in that folder. It then inserts the ++messages, indented by @code{mh-ins-buf-prefix} (@samp{> }) unless ++@code{mh-yank-behavior} is set to one of the supercite flavors in ++which case supercite is used to format the message. Certain ++undesirable header fields (see ++@code{mh-invisible-header-fields-compiled}) are removed before ++insertion. ++ ++If given a prefix argument (like @kbd{C-u C-c C-i}), the header is ++left intact, the message is not indented, and @samp{> } is not ++inserted before each line. This command leaves the mark before the ++letter and point after it. ++ ++@node Signature, Picture, Inserting Messages, Editing Drafts ++@section Inserting Your Signature ++ ++@cindex signature ++@findex mh-insert-signature ++@kindex C-c C-s ++ ++You can insert your signature at the current cursor location with the ++command @kbd{C-c C-s} (@code{mh-insert-signature}). ++ ++@cindex files, @file{.signature} ++@cindex @file{.signature} ++@cindex vCard ++@vindex mh-signature-file-name ++ ++By default, the text of your signature is taken from the file ++@file{~/.signature}. You can read from other sources by changing the ++option @code{mh-signature-file-name}. This file may contain a ++@dfn{vCard} in which case an attachment is added with the vCard. ++ ++@findex mh-signature-separator-p ++@vindex mh-signature-file-name ++@vindex mh-signature-separator ++@vindex mh-signature-separator-regexp ++ ++The option @code{mh-signature-file-name} may also be a symbol, in ++which case that function is called. You may not want a signature ++separator to be added for you; instead you may want to insert one ++yourself. Options that you may find useful to do this include ++@code{mh-signature-separator} (when inserting a signature separator) ++and @code{mh-signature-separator-regexp} (for finding said separator). ++The function @code{mh-signature-separator-p}, which reports @code{t} ++if the buffer contains a separator, may be useful as well. ++ ++@cindex signature separator ++@vindex mh-signature-separator-flag ++ ++A signature separator (@code{"-- "}) will be added if the signature ++block does not contain one and @code{mh-signature-separator-flag} is ++on. It is not recommended that you change this option since various ++mail user agents, including MH-E, use the separator to present the ++signature differently, and to suppress the signature when replying or ++yanking a letter into a draft. ++ ++@vindex mh-insert-signature-hook ++@vindex mh-signature-file-name ++ ++The hook @code{mh-insert-signature-hook} is run after the signature is ++inserted. Hook functions may access the actual name of the file or the ++function used to insert the signature with ++@code{mh-signature-file-name}. ++ ++The signature can also be inserted using Identities. ++@xref{Identities}. ++ ++@node Picture, Adding Attachments, Signature, Editing Drafts ++@section Inserting Your Picture ++ ++@cindex @file{.face} ++@cindex files, @file{.face} ++@vindex mh-x-face-file ++ ++You can insert your picture in the header of your mail message so that ++recipients see your face in the @samp{From:} header field if their ++mail user agent is sophisticated enough. In MH-E, this is done by ++placing your image in the file named by the option ++@code{mh-x-face-file} which is @file{~/.face} by default. ++ ++@cindex @samp{Face:} header field ++@cindex @samp{X-Face:} header field ++@cindex @samp{X-Image-URL:} header field ++@cindex header field, @samp{Face:} ++@cindex header field, @samp{X-Face:} ++@cindex header field, @samp{X-Image-URL:} ++ ++If the file starts with either of the strings @samp{X-Face:}, ++@samp{Face:} or @samp{X-Image-URL:} then the contents are added to the ++message header verbatim. Otherwise it is assumed that the file ++contains the value of the @samp{X-Face:} header field. ++ ++@cindex @command{compface} ++@cindex Unix commands, @command{compface} ++ ++The @samp{X-Face:} header field, which is a low-resolution, black and ++white image, can be generated using the ++@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z, ++@command{compface}} command. The @uref{http://www.dairiki.org/xface/, ++@cite{Online X-Face Converter}} is a useful resource for quick ++conversion of images into @samp{X-Face:} header fields. ++ ++Use the @uref{http://quimby.gnus.org/circus/face/make-face, ++@command{make-face}} script to convert a JPEG image to the higher ++resolution, color, @samp{Face:} header field. ++ ++The URL of any image can be used for the @samp{X-Image-URL:} field and ++no processing of the image is required. ++ ++@vindex mh-x-face-file ++ ++To prevent the setting of any of these header fields, either set ++@code{mh-x-face-file} to @code{nil}, or simply ensure that the file ++defined by this option doesn't exist. ++ ++@xref{Viewing}, to see how these header fields are displayed in MH-E. ++ ++@node Adding Attachments, Sending PGP, Picture, Editing Drafts ++@section Adding Attachments ++ ++@cindex @command{mhbuild} ++@cindex @command{mhn} ++@cindex MH commands, @command{mhbuild} ++@cindex MH commands, @command{mhn} ++@cindex MIME ++@cindex multimedia mail ++ ++MH-E has the capability to create multimedia messages. It uses the ++@sc{mime} (Multipurpose Internet Mail Extensions) ++protocol@footnote{@sc{mime} is defined in ++@uref{http://www.rfc-editor.org/rfc/rfc2045.txt, RFC 2045}.} The ++@sc{mime} protocol allows you to incorporate images, sound, video, ++binary files, and even commands that fetch a file with @samp{ftp} when ++your recipient reads the message! ++ ++@kindex C-c C-m ++ ++If you were to create a multimedia message with plain MH commands, you ++would insert @command{mhbuild} or @command{mhn} directives (henceforth ++called @dfn{MH-style directives} into your draft and use the ++@command{mhbuild} command in nmh or @command{mhn} command in MH and ++GNU mailutils to expand them. MH-E works in much the same way, ++although it provides a handful of commands prefixed with @kbd{C-c C-m} ++to insert the directives so you don't need to remember the syntax of ++them. Remember: you can always add MH-style directives by ++hand@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/usimim.html#SeMIMa, Sending MIME Mail} in ++the MH book.}. ++ ++@cindex MIME Meta Language (MML) ++@cindex MML ++@vindex mh-compose-insertion ++ ++In addition to MH-style directives, MH-E also supports MML (@sc{mime} ++Meta Language) tags@footnote{ ++@ifinfo ++@c Although the third argument should default to the ++@c first, makeinfo goes to the wrong Info file without it being ++@c different--it seems to be getting our own Composing node. ++@xref{Composing,,Composing with MML,emacs-mime}. ++@end ifinfo ++@ifnotinfo ++See the section Composing in ++@uref{http://www.gnus.org/manual/emacs-mime.html, @cite{The Emacs MIME ++Manual}}. ++@end ifnotinfo ++}. The option @code{mh-compose-insertion} can be used to choose ++between them. By default, this option is set to @samp{MML} if it is ++supported since it provides a lot more functionality. This option can ++also be set to @samp{MH} if MH-style directives are preferred. ++ ++@cindex media types ++@cindex MIME, media types ++ ++The MH-E @sc{mime} commands require a @dfn{media type} for each body ++part or attachment. For example, a PDF document is of type ++@samp{application/pdf} and an HTML document is of type ++@samp{text/html}. Some commands fill in the media type for you, ++whereas others require you to enter one. ++ ++@cindex @command{file} ++@cindex @file{/etc/mime.types} ++@cindex files, @file{/etc/mime.types} ++@cindex Unix commands, @command{file} ++@findex mailcap-mime-types ++ ++In the cases where MH-E can do so, it will determine the media type ++automatically. It uses the @command{file} command to do this. Failing ++that, the Emacs function @code{mailcap-mime-types} is used to provide ++a list from which to choose. This function usually reads the file ++@file{/etc/mime.types}. ++ ++Whether the media type is chosen automatically, or you choose it from ++a list, use the type that seems to match best the file that you are ++including. In the case of binaries, the media type ++@samp{application/x-executable} can be useful. If you can't find an ++appropriate media type, use @samp{text/plain} for text messages and ++@samp{application/octet-stream} for everything else. ++ ++@cindex content description ++@cindex MIME, content description ++ ++You are also sometimes asked for a @dfn{content description}. This is ++simply an optional brief phrase, in your own words, that describes the ++object. If you don't care to enter a content description, just press ++return and none will be included; however, a reader may skip over ++multimedia fields unless the content description is compelling. ++ ++You can also create your own @sc{mime} body parts. In the following ++example, I describe how you can create and edit a @samp{text/enriched} ++body part to liven up your plain text messages with boldface, ++underlining, and italics. I include an Emacs function which inserts ++enriched text tags. ++ ++@smalllisp ++@group ++(defvar enriched-text-types '(("b" . "bold") ("i" . "italic") ++ ("u" . "underline") ++ ("s" . "smaller") ("B" . "bigger") ++ ("f" . "fixed") ++ ("c" . "center")) ++ "Alist of (final-character . tag) choices for add-enriched-text. ++Additional types can be found in RFC 1563.") ++ ++(defun add-enriched-text (begin end) ++ "Add enriched text tags around region. ++The tag used comes from the list enriched-text-types and is ++specified by the last keystroke of the command. When called from Lisp, ++arguments are BEGIN and END@." ++ (interactive "r") ++ ;; @r{Set type to the tag indicated by the last keystroke.} ++ (let ((type (cdr (assoc (char-to-string (logior last-input-char ?@w{`})) ++ enriched-text-types)))) ++ (save-restriction ; @r{restores state from narrow-to-region} ++ (narrow-to-region begin end) ; @r{narrow view to region} ++ (goto-char (point-min)) ; @r{move to beginning of text} ++ (insert "<" type ">") ; @r{insert beginning tag} ++ (goto-char (point-max)) ; @r{move to end of text} ++ (insert "")))) ; @r{insert terminating tag} ++@i{Emacs function for entering enriched text} ++ ++@end group ++@end smalllisp ++ ++To use the function @code{add-enriched-text}, first add it to ++@file{~/.emacs} and create key bindings for it (@pxref{Composing}). ++ ++Then, in your plain text message, set the mark with @kbd{C-@@} or ++@kbd{C-@key{SPC}}, type in the text to be highlighted, and type @kbd{C-c t ++b}. This adds @samp{} where you set the mark and adds ++@samp{} at the location of your cursor, giving you something ++like: @samp{You should be very}. ++ ++Before sending this message, use @kbd{C-c C-m C-m} ++(@code{mh-mml-to-mime})@footnote{Use @kbd{C-c C-e} ++(@code{mh-mh-to-mime}) if you're using MH-style directives.} to add ++MIME header fields. Then replace @samp{text/plain} with ++@samp{text/enriched} in the @samp{Content-Type:} header field. ++ ++You may also be interested in investigating @code{sgml-mode}. ++ ++@subheading Including Files ++ ++@cindex attachments, inserting ++@cindex images ++@cindex MIME, images ++@cindex MIME, sound ++@cindex MIME, video ++@cindex sound ++@cindex video ++@findex mh-compose-insertion ++@kindex C-c C-m C-i ++@kindex C-c C-m i ++@vindex mh-compose-insertion ++ ++Binaries, images, sound, and video can be inserted in your message ++with the command @kbd{C-c C-m C-i} (@code{mh-compose-insertion}). You ++are prompted for the filename containing the object, the media type if ++it cannot be determined automatically, and a content description. If ++you're using MH-style directives, you will also be prompted for ++additional attributes. ++ ++@subheading Forwarding Multimedia Messages ++ ++@findex mh-compose-forward ++@kindex C-c C-m C-f ++@kindex C-c C-m f ++ ++Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m ++C-f} (@code{mh-compose-forward}). You are prompted for a content ++description, the name of the folder in which the messages to forward ++are located, and a range of messages, which defaults to the current ++message in that folder. @xref{Ranges}. ++ ++@subheading Including an FTP Reference ++ ++@cindex @command{ftp} ++@cindex MIME, @command{ftp} ++@cindex Unix commands, @command{ftp} ++@findex mh-mh-compose-anon-ftp ++@kindex C-c C-m C-g ++@kindex C-c C-m g ++ ++You can have your message initiate an @command{ftp} transfer when the ++recipient reads the message. To do this, use the command @kbd{C-c C-m ++C-g} (@code{mh-mh-compose-anon-ftp}). You are prompted for the remote ++host and filename, the media type, and the content description. ++ ++@subheading Including tar Files ++ ++@cindex @command{ftp} ++@cindex @command{tar} ++@cindex MIME, @command{ftp} ++@cindex MIME, @command{tar} ++@cindex Unix commands, @command{ftp} ++@cindex Unix commands, @command{tar} ++@findex mh-mh-compose-anon-ftp ++@findex mh-mh-compose-external-compressed-tar ++@kindex C-c C-m C-g ++@kindex C-c C-m C-t ++@kindex C-c C-m t ++ ++If the remote file is a compressed tar file, you can use @kbd{C-c C-m ++C-t} (@code{mh-mh-compose-external-compressed-tar}). Then, in addition ++to retrieving the file via anonymous @emph{ftp} as per the command ++@kbd{C-c C-m C-g} (@code{mh-mh-compose-anon-ftp}), the file will also ++be uncompressed and untarred. You are prompted for the remote host and ++filename and the content description. ++ ++@subheading Including Other External Files ++ ++@findex mh-mh-compose-external-type ++@kindex C-c C-m C-x ++@kindex C-c C-m x ++ ++The command @kbd{C-c C-m C-x} (@code{mh-mh-compose-external-type}) is ++a general utility for referencing external files. In fact, all of the ++other commands that insert tags to access external files call this ++command. You are prompted for the access type, remote host and ++filename, and content type. If you provide a prefix argument, you are ++also prompted for a content description, attributes, parameters, and a ++comment. ++ ++@subheading Previewing Multimedia Messages ++ ++When you are finished editing a @sc{mime} message, it might look like this: ++ ++@cartouche ++@smallexample ++3 t08/24 root received fax files on Wed Aug 24 11:00: ++4+t08/24 To:wohler Test< ++<#/part> ++--:** @{draft@} All L8 (MH-Letter)---------------------------------- ++ ++@end smallexample ++@end cartouche ++@i{MH-E @sc{mime} draft} ++ ++@findex mh-mml-to-mime ++@kindex C-c C-m C-m ++@kindex C-c C-m m ++ ++Typically, you send a message with attachments just like any other ++message (@pxref{Sending Message}). ++ ++@findex mh-mml-to-mime ++@kindex C-c C-m C-m ++ ++However, you may take a sneak preview of the @sc{mime} encoding if you ++wish by running the command @kbd{C-c C-m C-m} (@code{mh-mml-to-mime}). ++The following screen shows the @sc{mime} encoding specified by the ++tags. You can see why mail user agents are usually built to hide these ++details from the user. ++ ++@cartouche ++@smallexample ++To: wohler ++cc: ++Subject: Test of MIME ++X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 ++MIME-Version: 1.0 ++Content-Type: multipart/mixed; boundary="=-=-=" ++-------- ++--=-=-= ++ ++Here is the SETI@@Home logo: ++ ++ ++--=-=-= ++Content-Type: image/x-xpm ++Content-Disposition: inline; filename=setiathome.xpm ++Content-Transfer-Encoding: base64 ++Content-Description: SETI@@home logo ++ ++LyogWFBNICovCnN0YXRpYyBjaGFyICogc2V0aWF0aG9tZV94cG1bXSA9IHsKIjQ1IDQ1IDc2N ++--:-- @{draft@} Top L1 (MH-Letter)---------------------------------- ++ ++@end smallexample ++@end cartouche ++@i{MH-E @sc{mime} draft ready to send} ++ ++@cindex undo effects of mh-mml-to-mime ++ ++This action can be undone by running @kbd{C-_} (@code{undo}). ++ ++@cindex @command{mhbuild} ++@cindex @command{mhn} ++@cindex MH commands, @command{mhbuild} ++@cindex MH commands, @command{mhn} ++@cindex undo effects of mh-mh-to-mime ++@findex mh-mh-to-mime ++@findex mh-mh-to-mime-undo ++@kindex C-c C-e ++@kindex C-c C-m C-m ++@kindex C-c C-m C-u ++@kindex C-c C-m u ++ ++If you're using MH-style directives, use @kbd{C-c C-e} ++(@code{mh-mh-to-mime}) instead of @kbd{C-c C-m C-m}. This runs the ++command @command{mhbuild} (@command{mhn}) on the message which expands ++the tags@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/usimim.html#SeMIMa, Sending MIME Mail} in ++the MH book.}. This action can be undone by running @kbd{C-c C-m C-u} ++(@code{mh-mh-to-mime-undo}), which works by reverting to a backup ++file. You are prompted to confirm this action, but you can avoid the ++confirmation by adding an argument (for example, @kbd{C-u C-c C-m ++C-u}). ++ ++@kindex C-c C-e ++@vindex mh-mh-to-mime-args ++ ++If you wish to pass additional arguments to @command{mhbuild} ++(@command{mhn}) to affect how it builds your message, use the option ++@code{mh-mh-to-mime-args}. For example, you can build a consistency ++check into the message by setting @code{mh-mh-to-mime-args} to ++@samp{-check}. The recipient of your message can then run ++@samp{mhbuild -check} on the message---@command{mhbuild} ++(@command{mhn}) will complain if the message has been corrupted on the ++way. The command @kbd{C-c C-e} only consults this option when given a ++prefix argument (as in @kbd{C-u C-c C-e}). ++ ++@kindex C-c C-e ++@vindex mh-mh-to-mime-hook ++ ++The hook @code{mh-mh-to-mime-hook} is called after the message has ++been formatted by @kbd{C-c C-e}. ++ ++@node Sending PGP, Checking Recipients, Adding Attachments, Editing Drafts ++@section Signing and Encrypting Messages ++ ++@cindex signing messages ++@cindex encrypting messages ++@cindex RFC 3156 ++ ++MH-E can sign and encrypt messages as defined in ++@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. If you ++should choose to sign or encrypt your message, use one of the ++following commands to do so any time before sending your message. ++ ++@findex mh-mml-secure-message-encrypt ++@findex mh-mml-secure-message-sign ++@findex mh-mml-secure-message-signencrypt ++@kindex C-c C-m C-e ++@kindex C-c C-m C-s ++@kindex C-c C-m e e ++@kindex C-c C-m e s ++@kindex C-c C-m s e ++@kindex C-c C-m s s ++ ++The command @kbd{C-c C-m C-s} (@code{mh-mml-secure-message-sign}) ++inserts the following tag: ++ ++@smallexample ++<#secure method=pgpmime mode=sign> ++@end smallexample ++ ++This is used to sign your message digitally. Likewise, the command ++@kbd{C-c C-m C-e} (@code{mh-mml-secure-message-encrypt}) inserts the ++following tag: ++ ++@smallexample ++<#secure method=pgpmime mode=encrypt> ++@end smallexample ++ ++This is used to encrypt your message. Finally, the command @kbd{C-c ++C-m s e} (@code{mh-mml-secure-message-signencrypt}) inserts the ++following tag: ++ ++@smallexample ++<#secure method=pgpmime mode=signencrypt> ++@end smallexample ++ ++@findex mh-mml-unsecure-message ++@kindex C-c C-m C-n ++@kindex C-c C-m n ++@vindex mh-mml-method-default ++ ++This is used to sign and encrypt your message. In each of these cases, ++a proper multipart message is created for you when you send the ++message. Use the command @kbd{C-c C-m C-n} ++(@code{mh-mml-unsecure-message}) to remove these tags. Use a prefix ++argument (as in @kbd{C-u C-c C-m s e}) to be prompted for one of the ++possible security methods (see @code{mh-mml-method-default}). ++ ++@vindex mh-mml-method-default ++ ++The option @code{mh-mml-method-default} is used to select between a ++variety of mail security mechanisms. The default is @samp{PGP (MIME)} ++if it is supported; otherwise, the default is @samp{None}. Other ++mechanisms include vanilla @samp{PGP} and @samp{S/MIME}. ++ ++@cindex @samp{pgg} customization group ++@cindex PGG ++@cindex customization group, @samp{pgg} ++ ++The @samp{pgg} customization group may have some settings which may ++interest you. ++@iftex ++See @cite{The PGG Manual}. ++@end iftex ++@ifinfo ++@xref{Top, , The PGG Manual, pgg, The PGG Manual}. ++@end ifinfo ++@ifhtml ++See ++@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html, ++@cite{The PGG Manual}}. ++@end ifhtml ++ ++@cindex header field, @samp{Fcc:} ++@cindex @samp{Fcc:} header field ++@vindex pgg-encrypt-for-me ++ ++In particular, I turn on the option @code{pgg-encrypt-for-me} so that ++all messages I encrypt are encrypted with my public key as well. If ++you keep a copy of all of your outgoing mail with a @samp{Fcc:} header ++field, this setting is vital so that you can read the mail you write! ++ ++@node Checking Recipients, Sending Message, Sending PGP, Editing Drafts ++@section Checking Recipients ++ ++@cindex @samp{*MH-E Recipients*} ++@cindex @command{whom} ++@cindex MH commands, @command{whom} ++@cindex buffers, @samp{*MH-E Recipients*} ++@cindex checking recipients ++@cindex recipients, checking ++@findex mh-check-whom ++@kindex C-c C-w ++ ++The command @kbd{C-c C-w} (@code{mh-check-whom}) expands aliases so ++you can check the actual address(es) in the alias. A new buffer named ++@samp{*MH-E Recipients*} is created with the output of @command{whom} ++(@pxref{Miscellaneous})@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/senove.html#WhaPro, What now? -- and the ++whatnow Program} in the MH book.}. ++ ++@node Sending Message, Killing Draft, Checking Recipients, Editing Drafts ++@section Sending a Message ++ ++@cindex buffers, @samp{*MH-E Mail Delivery*} ++@cindex @samp{*MH-E Mail Delivery*} ++@cindex sending mail ++@findex mh-send-letter ++@kindex C-c C-c ++ ++When you are all through editing a message, you send it with the ++command @kbd{C-c C-c} (@code{mh-send-letter}). You can give a prefix ++argument (as in @kbd{C-u C-c C-c}) to monitor the first stage of the ++delivery; this output can be found in a buffer called @samp{*MH-E Mail ++Delivery*} (@pxref{Miscellaneous}). ++ ++@cindex sending mail ++@cindex spell check ++@findex ispell-message ++@kindex C-c C-c ++@vindex mh-before-send-letter-hook ++ ++The hook @code{mh-before-send-letter-hook} is run at the beginning of ++the command @kbd{C-c C-c}. For example, if you want to check your ++spelling in your message before sending, add the function ++@code{ispell-message}. ++ ++@cindex @command{send} ++@cindex MH commands, @command{send} ++@vindex mh-send-prog ++ ++In case the MH @command{send} program@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/sensen.html, Sending Some Mail: comp send} ++in the MH book.} is installed under a different name, use ++@code{mh-send-prog} to tell MH-E the name. ++ ++The hook @code{mh-annotate-msg-hook} is run after annotating the ++message and scan line (@pxref{Sending Mail}). ++ ++@node Killing Draft, , Sending Message, Editing Drafts ++@section Killing the Draft ++ ++@cindex killing draft ++@findex kill-buffer ++@findex mh-fully-kill-draft ++@kindex C-c C-q ++@kindex C-x k ++ ++If for some reason you are not happy with the draft, you can use the ++command @kbd{C-c C-q} (@code{mh-fully-kill-draft}) to kill the draft ++buffer and delete the draft message. Use the command @kbd{C-x k} ++(@code{kill-buffer}) if you don't want to delete the draft message. ++ ++@node Aliases, Identities, Editing Drafts, Top ++@chapter Aliases ++ ++@cindex aliases ++ ++MH aliases are used in the same way in MH-E as they are in MH. Any ++alias listed as a recipient will be expanded when the message is sent. ++This chapter discusses other things you can do with aliases in MH-E. ++ ++@cindex MH-Letter mode ++@cindex modes, MH-Letter ++ ++The following commands are available in MH-Letter mode with the ++exception of @code{mh-alias-reload} which can be called from anywhere. ++ ++@table @kbd ++@kindex @key{SPC} ++@findex mh-letter-complete-or-space ++@item @key{SPC} ++Perform completion or insert space (@code{mh-letter-complete-or-space}). ++@c ------------------------- ++@kindex M-@key{TAB} ++@findex mh-letter-complete ++@item M-@key{TAB} ++Perform completion on header field or word preceding point ++(@code{mh-letter-complete}). ++@c ------------------------- ++@findex mh-alias-apropos ++@item mh-alias-apropos ++Show all aliases or addresses that match a regular expression. ++@c ------------------------- ++@findex mh-alias-grab-from-field ++@item mh-alias-grab-from-field ++Add alias for the sender of the current message ++@c ------------------------- ++@findex mh-alias-reload ++@item mh-alias-reload ++Reload MH aliases. ++@end table ++ ++@cindex @samp{mh-alias} customization group ++@cindex customization group, @samp{mh-alias} ++ ++The @samp{mh-alias} customization group contains options associated ++with aliases. ++ ++@vtable @code ++@item mh-alias-completion-ignore-case-flag ++On means don't consider case significant in MH alias completion ++(default: @samp{on}). ++@c ------------------------- ++@item mh-alias-expand-aliases-flag ++On means to expand aliases entered in the minibuffer (default: ++@samp{off}). ++@c ------------------------- ++@item mh-alias-flash-on-comma ++Specify whether to flash address or warn on translation (default: @samp{Flash ++but Don't Warn If No Alias}). ++@c ------------------------- ++@item mh-alias-insert-file ++Filename used to store a new MH-E alias (default: @samp{Use Aliasfile ++Profile Component}). ++@c ------------------------- ++@item mh-alias-insertion-location ++Specifies where new aliases are entered in alias files (default: ++@samp{Alphabetical}). ++@c ------------------------- ++@item mh-alias-local-users ++If @samp{on}, local users are added to alias completion (default: ++@samp{on}). ++@c ------------------------- ++@item mh-alias-local-users-prefix ++String prefixed to the real names of users from the password file ++(default: @code{"local."}. ++@c ------------------------- ++@item mh-alias-passwd-gecos-comma-separator-flag ++On means the GECOS field in the password file uses a comma separator ++(default: @samp{on}). ++@end vtable ++ ++The following hook is available. ++ ++@vtable @code ++@item mh-alias-reloaded-hook ++Hook run by @code{mh-alias-reload} after loading aliases (default: ++@code{nil}). ++@end vtable ++ ++@subheading Adding Addresses to Draft ++ ++You can use aliases when you are adding recipients to a message. ++ ++@findex minibuffer-complete ++@kindex @key{TAB} ++@vindex mh-alias-expand-aliases-flag ++@vindex mh-compose-prompt-flag ++ ++In order to use minibuffer prompting for recipients and the subject ++line in the minibuffer, turn on the option ++@code{mh-compose-prompt-flag} (@pxref{Composing}), and use the ++@key{TAB} (@code{minibuffer-complete}) command to complete aliases ++(and optionally local logins) when prompted for the recipients. Turn ++on the option @code{mh-alias-expand-aliases-flag} if you want these ++aliases to be expanded to their respective addresses in the draft. ++ ++@findex mh-letter-complete ++@findex mh-letter-complete-or-space ++@kindex @key{SPC} ++@kindex M-@key{TAB} ++ ++Otherwise, you can complete aliases in the header of the draft with ++@kbd{M-@key{TAB}} (@code{mh-letter-complete}) or @key{SPC} ++(@code{mh-letter-complete-or-space}). ++ ++@vindex mh-alias-completion-ignore-case-flag ++ ++As MH ignores case in the aliases, so too does MH-E. However, you may ++turn off the option @code{mh-alias-completion-ignore-case-flag} to ++make case significant which can be used to segregate completion of ++your aliases. You might use uppercase for mailing lists and lowercase ++for people. For example, you might have: ++ ++@smallexample ++mark.baushke: Mark Baushke ++MH-E: MH-E Mailing List ++@end smallexample ++ ++When this option is turned off, if you were to type @kbd{M} in the ++@samp{To:} field and then @kbd{M-@key{TAB}}, then you'd get the list; ++if you started with @kbd{m} and then entered @kbd{M-@key{TAB}}, then ++you'd get Mark's address. Note that this option affects completion ++only. If you were to enter @kbd{Mark.Baushke}, it would still be ++identified with your @samp{mark.baushke} alias. ++ ++@findex mh-alias-minibuffer-confirm-address ++@findex mh-letter-confirm-address ++@vindex mh-alias-flash-on-comma ++@vindex mh-compose-prompt-flag ++ ++To verify that the alias you've entered is valid, the alias will be ++displayed in the minibuffer when you type a comma ++(@code{mh-letter-confirm-address} or ++@code{mh-alias-minibuffer-confirm-address} if the option ++@code{mh-compose-prompt-flag} is turned on). @xref{Composing}. This ++behavior can be controlled with the option ++@code{mh-alias-flash-on-comma} which provides three choices: ++@samp{Flash but Don't Warn If No Alias}, @samp{Flash and Warn If No ++Alias}, and @samp{Don't Flash Nor Warn If No Alias}. ++ ++For another way to verify the alias expansion, see @ref{Checking ++Recipients}. ++ ++@subheading Loading Aliases ++ ++@cindex @command{ali} ++@cindex @file{/etc/nmh/MailAliases} ++@cindex @samp{Aliasfile:} MH profile component ++@cindex MH commands, @command{ali} ++@cindex MH profile component, @samp{Aliasfile:} ++@cindex files, @file{/etc/nmh/MailAliases} ++ ++MH-E loads aliases for completion and folder name hints from various ++places. It uses the MH command @command{ali}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/mh.html, MH Aliases} in the MH book.} to ++read aliases from the files listed in the profile component ++@samp{Aliasfile:} as well as system-wide aliases (for example, ++@file{/etc/nmh/MailAliases}). ++ ++@cindex @file{/etc/passwd} ++@cindex files, @file{/etc/passwd} ++ ++In addition, aliases are created from @file{/etc/passwd} entries with ++a user ID larger than a magical number, typically 200. This can be a ++handy tool on a machine where you and co-workers exchange messages. ++These aliases have the form @samp{local.@var{first.last}} if a real ++name is present in the password file. Otherwise, the alias will have ++the form @samp{local.@var{login}}. ++ ++@vindex mh-alias-local-users-prefix ++ ++The prefix @samp{local.} can be modified via the option ++@code{mh-alias-local-users-prefix}. This option can also be set to ++@samp{Use Login}. ++ ++For example, consider the following password file entry: ++ ++@smallexample ++psg:x:1000:1000:Peter S Galbraith,,,:/home/psg:/bin/tcsh ++@end smallexample ++ ++@vindex mh-alias-local-users-prefix ++ ++The following settings of option @code{mh-alias-local-users-prefix} ++will produce the associated aliases: ++ ++@table @code ++@item "local." ++local.peter.galbraith ++@c ------------------------- ++@item "" ++peter.galbraith ++@c ------------------------- ++@item Use Login ++psg ++@end table ++ ++@vindex mh-alias-passwd-gecos-comma-separator-flag ++ ++In the example above, commas are used to separate different values ++within the so-called GECOS field. This is a fairly common usage. ++However, in the rare case that the GECOS field in your password file ++is not separated by commas and whose contents may contain commas, you ++can turn the option @code{mh-alias-passwd-gecos-comma-separator-flag} ++off. ++ ++@cindex NIS, obtaining local aliases from ++@cindex @samp{ypcat passwd} ++@vindex mh-alias-local-users ++ ++If you're on a system with thousands of users you don't know, and the ++loading of local aliases slows MH-E down noticeably, then the local ++alias feature can be disabled by turning off the option ++@code{mh-alias-local-users}. This option also takes a string which is ++executed to generate the password file. For example, use @samp{ypcat ++passwd} to obtain the NIS password file. ++ ++@findex mh-alias-reload ++@kindex M-x mh-alias-reload ++@vindex mh-alias-reloaded-hook ++ ++Since aliases are updated frequently, MH-E reloads aliases ++automatically whenever an alias lookup occurs if an alias source has ++changed. However, you can reload your aliases manually by calling the ++command @kbd{M-x mh-alias-reload} directly. This command runs ++@code{mh-alias-reloaded-hook} after the aliases have been loaded. ++ ++@subheading Adding Aliases ++ ++In the past, you have manually added aliases to your alias file(s) ++listed in your @samp{Aliasfile:} profile component. MH-E provides ++other methods for maintaining your alias file(s). ++ ++@findex mh-alias-add-alias ++@kindex M-x mh-alias-add-alias ++ ++You can use the @kbd{M-x mh-alias-add-alias} command which will prompt ++you for the alias and address that you would like to add. If the alias ++exists already, you will have the choice of inserting the new alias ++before or after the old alias. In the former case, this alias will be ++used when sending mail to this alias. In the latter case, the alias ++serves as an additional folder name hint when filing messages ++(@pxref{Folder Selection}). ++ ++Earlier, the alias prefix @samp{local} was presented. You can use ++other prefixes to organize your aliases or disambiguate entries. You ++might use prefixes for locales, jobs, or activities. For example, I ++have: ++ ++@smallexample ++@group ++; Work ++attensity.don.mitchell: Don Mitchell ++isharp.don.mitchell: Don Mitchell ++... ++; Sport ++diving.ken.mayer: Ken Mayer ++sailing.mike.maloney: Mike Maloney ++... ++; Personal ++ariane.kolkmann: Ariane Kolkmann ++... ++@end group ++@end smallexample ++ ++Using prefixes instead of postfixes helps you explore aliases during ++completion. If you forget the name of an old dive buddy, you can enter ++@samp{div} and then @key{SPC} to get a listing of all your dive buddies. ++ ++@kindex M-x mh-alias-add-address-under-point ++@kindex M-x mh-alias-grab-from-field ++ ++An alias for the sender of the current message is added automatically ++by clicking on the @samp{Grab From alias} tool bar button or by running ++the @kbd{M-x mh-alias-grab-from-field} command. Aliases for other ++recipients of the current message are added by placing your cursor ++over the desired recipient and giving the @kbd{M-x ++mh-alias-add-address-under-point} command. ++ ++@vindex mh-alias-insert-file ++@vindex mh-alias-insertion-location ++ ++The options @code{mh-alias-insert-file} and ++@code{mh-alias-insertion-location} controls how and where these aliases ++are inserted. ++ ++@vindex mh-alias-insert-file ++ ++The default setting of option @code{mh-alias-insert-file} is @samp{Use ++Aliasfile Profile Component}. This option can also hold the name of a ++file or a list a file names. If this option is set to a list of file ++names, or the @samp{Aliasfile:} profile component contains more than ++one file name, MH-E will prompt for one of them. ++ ++@vindex mh-alias-insertion-location ++ ++The option @code{mh-alias-insertion-location} is set to ++@samp{Alphabetical} by default. If you organize your alias file in ++other ways, then the settings @samp{Top} and @samp{Bottom} might be ++more appropriate. ++ ++@subheading Querying Aliases ++ ++@cindex regular expressions, @code{mh-alias-apropos} ++@findex mh-alias-apropos ++@kindex M-x mh-alias-apropos ++ ++If you can't quite remember an alias, you can use @kbd{M-x ++mh-alias-apropos} to show all aliases or addresses that match a ++regular expression ++@ifnothtml ++(@pxref{Regexps, , Syntax of Regular Expressions, emacs, The ++GNU Emacs Manual}). ++@end ifnothtml ++@ifhtml ++(see the section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, ++Syntax of Regular Expressions} in ++@cite{The GNU Emacs Manual}). ++@end ifhtml ++ ++@node Identities, Speedbar, Aliases, Top ++@chapter Identities ++ ++@cindex identities ++@cindex multiple personalities ++ ++MH-E supports the concept of multiple personalities or identities. ++This means that you can easily have a different header and signature ++at home and at work. ++ ++@cindex @samp{Identity} menu ++@cindex menu, @samp{Identity} ++ ++A couple of commands are used to insert identities in MH-Letter mode ++which are also found in the @samp{Identity} menu. ++ ++@table @kbd ++@kindex C-c C-d ++@findex mh-insert-identity ++@item C-c C-d ++Insert fields specified by given identity (@code{mh-insert-identity}). ++@c ------------------------- ++@cindex @samp{Identity > Insert Auto Fields} menu item ++@cindex menu item, @samp{Identity > Insert Auto Fields} ++@kindex C-c M-d ++@findex mh-insert-auto-fields ++@item C-c M-d ++Insert custom fields if recipient found in @code{mh-auto-fields-list} ++(@code{mh-insert-auto-fields}). ++@end table ++ ++@cindex @samp{mh-identity} customization group ++@cindex customization group, @samp{mh-identity} ++ ++The @samp{mh-identity} customization group contains the following ++options. ++ ++@vtable @code ++@item mh-auto-fields-list ++List of recipients for which header lines are automatically inserted ++(default: @code{nil}). ++@c ------------------------- ++@item mh-auto-fields-prompt-flag ++On means to prompt before sending if fields inserted (default: ++@samp{on}) ++@c ------------------------- ++@item mh-identity-default ++Default identity to use when @code{mh-letter-mode} is called (default: ++@samp{None}). ++@c ------------------------- ++@item mh-identity-handlers ++Handler functions for fields in @code{mh-identity-list}. ++@c ------------------------- ++@item mh-identity-list ++List of identities (default: @code{nil}). ++@end vtable ++ ++Some of the common header fields that people change depending on the ++context are the @samp{From:} and @samp{Organization:} fields, as well ++as the signature. ++ ++@vindex mh-identity-list ++ ++This is done by customizing the option @code{mh-identity-list}. In the ++customization buffer for this option, click on the @samp{INS} button ++and enter a label such as @samp{Home} or @samp{Work}. Then click on ++the @samp{INS} button with the label @samp{Add at least one item ++below}. The @samp{Value Menu} has the following menu items: ++ ++@table @samp ++@cindex header field, @samp{From:} ++@cindex @samp{From:} header field ++@item From Field ++Specify an alternate @samp{From:} header field. You must include a ++valid email address. A standard format is @samp{First Last ++}. If you use an initial with a period, then you ++must quote your name as in @samp{"First I. Last" ++}. ++@c ------------------------- ++@cindex header field, @samp{Organization:} ++@cindex @samp{Organization:} header field ++@item Organization Field ++People usually list the name of the company where they work here. ++@c ------------------------- ++@item Other Field ++Set any arbitrary header field and value here. Unless the header field ++is a standard one, precede the name of your field's label with ++@samp{X-}, as in @samp{X-Fruit-of-the-Day:}. ++@c ------------------------- ++@item Attribution Verb ++This value overrides the setting of ++@code{mh-extract-from-attribution-verb}. @xref{Inserting Letter}. ++@c ------------------------- ++@cindex signature ++@vindex mh-signature-file-name ++@item Signature ++Set your signature with this item. You can specify the contents of ++@code{mh-signature-file-name}, a file, or a function. ++@xref{Signature}. ++@c ------------------------- ++@item GPG Key ID ++Specify a different key to sign or encrypt messages. ++@end table ++ ++@cindex Identity menu ++@cindex menu, Identity ++@findex mh-insert-identity ++@kindex C-c C-d ++ ++You can select the identities you have added via the menu called ++@samp{Identity} in the MH-Letter buffer. You can also use @kbd{C-c ++C-d} (@code{mh-insert-identity}). To clear the fields and signature ++added by the identity, select the @samp{None} identity. ++ ++@cindex menu item, @samp{Identity > Customize Identities} ++@cindex menu item, @samp{Identity > Save as Default} ++@cindex menu item, @samp{Identity > Set Default for Session} ++@cindex @samp{Identity > Customize Identities} menu item ++@cindex @samp{Identity > Save as Default} menu item ++@cindex @samp{Identity > Set Default for Session} menu item ++@vindex mh-identity-default ++ ++The @samp{Identity} menu contains two other items to save you from ++having to set the identity on every message. The menu item @samp{Set ++Default for Session} can be used to set the default identity to the ++current identity until you exit Emacs. The menu item @samp{Save as ++Default} sets the option @code{mh-identity-default} to the current ++identity setting. You can also customize the option ++@code{mh-identity-default} in the usual fashion. If you find that you ++need to add another identity, the menu item @samp{Customize ++Identities} is available for your convenience. ++ ++@cindex regular expressions, @code{mh-auto-fields-list} ++@vindex mh-auto-fields-list ++ ++The option @code{mh-auto-fields-list} can also be used to set the ++identity depending on the recipient to provide even more control. To ++customize @code{mh-auto-fields-list}, click on the @samp{INS} button ++and enter a regular expression for the recipient's address ++@ifnothtml ++(@pxref{Regexps, , Syntax of Regular Expressions, emacs, The ++GNU Emacs Manual}). ++@end ifnothtml ++@ifhtml ++(see the section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, ++Syntax of Regular Expressions} in ++@cite{The GNU Emacs Manual}). ++@end ifhtml ++Click on the @samp{INS} button with the @samp{Add at least one item ++below} label. The @samp{Value Menu} contains the following menu items: ++ ++@table @samp ++@item Identity ++Select an identity from those configured in @code{mh-identity-list}. ++All of the information for that identity will be added if the ++recipient matches. ++@c ------------------------- ++@cindex @samp{Fcc:} header field ++@cindex header field, @samp{Fcc:} ++@item Fcc Field ++Insert an @samp{Fcc:} header field with the folder you provide. When ++you send the message, MH will put a copy of your message in this ++folder. ++@c ------------------------- ++@cindex @samp{Mail-Followup-To:} header field ++@cindex header field, @samp{Mail-Followup-To:} ++@item Mail-Followup-To Field ++Insert an @samp{Mail-Followup-To:} header field with the recipients ++you provide. If the recipient's mail user agent supports this header ++field@footnote{@samp{Mail-Followup-To:} is supported by nmh.}, then ++their replies will go to the addresses listed. This is useful if their ++replies go both to the list and to you and you don't have a mechanism ++to suppress duplicates. If you reply to someone not on the list, you ++must either remove the @samp{Mail-Followup-To:} field, or ensure the ++recipient is also listed there so that he receives replies to your ++reply. ++@c ------------------------- ++@item Other Field ++Other header fields may be added using this menu item. ++@end table ++ ++@findex mh-insert-auto-fields ++@kindex C-c M-d ++@vindex mh-auto-fields-prompt-flag ++ ++These fields can only be added after the recipient is known. Because ++you can continue to add recipients as you edit the draft, MH-E waits ++until the message is sent to perform the auto-insertions. This seems ++strange at first, but you'll get used to it. There are two ways to ++help you feel that the desired fields are added. The first is the ++action when the message is sent: if any fields are added ++automatically, you are given a chance to see and to confirm these ++fields before the message is actually sent. You can do away with this ++confirmation by turning off the option ++@code{mh-auto-fields-prompt-flag}. The second method is manual: once ++the header contains one or more recipients, you may run the command ++@kbd{C-c M-d} (@code{mh-insert-auto-fields}) or choose the ++@samp{Identity -> Insert Auto Fields} menu item to insert these fields ++manually. However, if you use this command, the automatic insertion ++when the message is sent is disabled. ++ ++@vindex mh-auto-fields-list ++@vindex mh-identity-list ++ ++You should avoid using the same header field in ++@code{mh-auto-fields-list} and @code{mh-identity-list} definitions ++that may apply to the same message as the result is undefined. ++ ++@vindex mh-identity-handlers ++@vindex mh-identity-list ++ ++The option @code{mh-identity-handlers} is used to change the way that ++fields, signatures, and attributions in @code{mh-identity-list} are ++added. To customize @code{mh-identity-handlers}, replace the name of ++an existing handler function associated with the field you want to ++change with the name of a function you have written. You can also ++click on an @samp{INS} button and insert a field of your choice and ++the name of the function you have written to handle it. ++ ++@vindex mh-identity-list ++ ++The @samp{Field} field can be any field that you've used in your ++@code{mh-identity-list}. The special fields @samp{:attribution-verb}, ++@samp{:signature}, or @samp{:pgg-default-user-id} are used for the ++@code{mh-identity-list} choices @samp{Attribution Verb}, ++@samp{Signature}, and @samp{GPG Key ID} respectively. ++ ++The handler associated with the @samp{:default} field is used when no ++other field matches. ++ ++The handler functions are passed two or three arguments: the field ++itself (for example, @samp{From}), or one of the special fields (for ++example, @samp{:signature}), and the action @samp{'remove} or ++@samp{'add}. If the action is @samp{'add}, an additional argument ++containing the value for the field is given. ++ ++@node Speedbar, Menu Bar, Identities, Top ++@chapter The Speedbar ++ ++@cindex folder navigation ++@cindex speedbar ++@findex mh-visit-folder ++@kindex F v ++@kindex M-x speedbar ++@kindex Mouse-2 ++ ++You can also use the speedbar ++@ifnothtml ++(@pxref{Speedbar, , Speedbar Frames, emacs, The GNU Emacs Manual},) ++@end ifnothtml ++@ifhtml ++(see the section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Speedbar.html, ++Speedbar Frames} in @cite{The GNU Emacs Manual}) ++@end ifhtml ++to view your folders. To bring up the speedbar, run @kbd{M-x speedbar ++@key{RET}}. You will see a new frame appear with all of your MH ++folders. Folders with unseen messages appear in boldface. Click on a ++folder name with @kbd{Mouse-2} to visit that folder in a similar ++fashion to the command @kbd{F v} (@code{mh-visit-folder}) ++(@pxref{Folders}). Click on the @samp{+} icon to expand and view the ++sub-folders of that folder. ++ ++The speedbar can be manipulated with the keyboard as well. Use the ++Emacs navigational keys (like the arrow keys, or @kbd{C-n}) to move ++the cursor over the desired folder and then use the shortcuts for the ++menu items listed in the table below. ++ ++@table @samp ++@findex mh-speed-view ++@item Visit Folder (@key{RET}) ++Visits the selected folder just as if you had used @kbd{F v} ++(@code{mh-speed-view}). ++@c ------------------------- ++@findex mh-speed-expand-folder ++@item Expand Nested Folders (@kbd{+}) ++Expands the selected folder in the speedbar, exposing the children ++folders inside it (@code{mh-speed-expand-folder}). ++@c ------------------------- ++@findex mh-speed-contract-folder ++@item Contract Nested Folders (@kbd{-}) ++Contracts or collapses the selected folder in the speedbar, hiding the ++children folders inside it (@code{mh-speed-contract-folder}). ++@c ------------------------- ++@findex mh-speed-refresh ++@item Refresh Speedbar (@kbd{r}) ++Regenerates the list of folders in the speedbar. Run this command if ++you've added or deleted a folder, or want to update the unseen message ++count before the next automatic update (@code{mh-speed-refresh}). ++@end table ++ ++@findex delete-frame ++@kindex C-x 5 0 ++@kindex Mouse-3 ++ ++You can click on @kbd{Mouse-3} to bring up a context menu that ++contains these items. Dismiss the speedbar with @kbd{C-x 5 0} ++(@code{delete-frame}). ++ ++@cindex @command{flists} ++@cindex MH commands, @command{flists} ++@cindex @samp{mh-speedbar} customization group ++@cindex customization group, @samp{mh-speedbar} ++ ++The MH-E speedbar uses the MH command @command{flists}@footnote{See ++the section @uref{@value{MH-BOOK-HOME}/morseq.html#flist, Searching for ++Sequences with flist} in the MH book.} to generate the list of ++folders. The @samp{mh-speedbar} customization group contains the ++following option which controls how often the speedbar calls ++@command{flists}. ++ ++@vtable @code ++@item mh-speed-update-interval ++Time between speedbar updates in seconds (default: 60). Set to 0 to ++disable automatic update. ++@end vtable ++ ++You can modify the appearance of the folders in the speedbar by ++customizing the following faces. ++ ++@vtable @code ++@item mh-speedbar-folder ++Basic folder face. ++@c ------------------------- ++@item mh-speedbar-folder-with-unseen-messages ++Folder face when folder contains unread messages. ++@c ------------------------- ++@item mh-speedbar-selected-folder ++Selected folder face. ++@c ------------------------- ++@item mh-speedbar-selected-folder-with-unseen-messages ++Selected folder face when folder contains unread messages. ++@end vtable ++ ++@node Menu Bar, Tool Bar, Speedbar, Top ++@chapter The Menu Bar ++ ++@cindex @samp{Folder} menu ++@cindex @samp{Identity} menu ++@cindex @samp{Letter} menu ++@cindex @samp{Message} menu ++@cindex @samp{Search} menu ++@cindex @samp{Sequence} menu ++@cindex Folder menu ++@cindex Identity menu ++@cindex Letter menu ++@cindex MH-Folder mode ++@cindex MH-Letter mode ++@cindex MH-Search mode ++@cindex Message menu ++@cindex Search menu ++@cindex Sequence menu ++@cindex menu bar ++@cindex menu, Folder ++@cindex menu, Identity ++@cindex menu, Letter ++@cindex menu, Message ++@cindex menu, Search ++@cindex menu, Sequence ++@cindex menu, @samp{Folder} ++@cindex menu, @samp{Identity} ++@cindex menu, @samp{Letter} ++@cindex menu, @samp{Message} ++@cindex menu, @samp{Search} ++@cindex menu, @samp{Sequence} ++@cindex modes, MH-Folder ++@cindex modes, MH-Letter ++@cindex modes, MH-Search ++ ++For those of you who prefer to mouse and menu instead of using the ++meta-coke-bottle-bucky keys, MH-E provides menu items for most of its ++functions. The MH-Folder buffer adds the @samp{Folder}, ++@samp{Message}, and @samp{Sequence} menus. The MH-Letter buffer adds ++the @samp{Identity} and @samp{Letter} menus. The MH-Search buffer adds ++the @samp{Search} menu. There's no need to list the actual items here, ++as you can more easily see them for yourself, and the functions are ++already described elsewhere in this manual. ++ ++For a description of the menu bar, please ++@ifnothtml ++@xref{Menu Bar, , The Menu Bar, emacs, The GNU Emacs Manual}. ++@end ifnothtml ++@ifhtml ++see the section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Menu-Bar.html, ++The Menu Bar} in @cite{The GNU Emacs Manual}. ++@end ifhtml ++ ++The Emacs manual describes how to get online help for a particular ++menu item. You can also look up a menu item in the index of this ++manual in two ways: all of the menu items are listed alphabetically, ++and you can also browse all of the items under the index entry ++@samp{menu item}. ++ ++@node Tool Bar, Searching, Menu Bar, Top ++@chapter The Tool Bar ++ ++@cindex tool bar ++ ++Emacs also provides a graphical tool bar. For a description of the ++tool bar, please ++@ifnothtml ++@xref{Tool Bars, , Tool Bars, emacs, The GNU Emacs Manual}. ++@end ifnothtml ++@ifhtml ++see the section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Tool-Bars.html, ++Tool Bars} in @cite{The GNU Emacs Manual}. ++@end ifhtml ++ ++@cindex @samp{mh-tool-bar} customization group ++@cindex customization group, @samp{mh-tool-bar} ++ ++MH-E adds several icons to this tool bar; you can modify the MH-E ++aspects of the tool bar via the @samp{mh-tool-bar} customization group. ++ ++@vtable @code ++@item mh-tool-bar-folder-buttons ++List of buttons to include in MH-Folder tool bar (default: a checklist ++too long to list here). ++@c ------------------------- ++@item mh-tool-bar-letter-buttons ++List of buttons to include in MH-Letter tool bar (default: a checklist ++too long to list here). ++@c ------------------------- ++@item mh-tool-bar-search-function ++Function called by the tool bar search button (default: ++@code{mh-search}). ++@c ------------------------- ++@item mh-xemacs-tool-bar-position ++Tool bar location (default: @samp{Same As Default Tool Bar}). ++@c ------------------------- ++@item mh-xemacs-use-tool-bar-flag ++If @samp{on}, use tool bar (default: @samp{on}, if supported). ++@end vtable ++ ++In GNU Emacs, icons for some of MH-E's functions are added to the tool ++bar. In XEmacs, you have the opportunity to create a separate tool bar for ++the MH-E icons. ++ ++@vindex mh-tool-bar-folder-buttons ++@vindex mh-tool-bar-letter-buttons ++ ++In either case, you can select which of these functions you'd like to ++see by customizing the options @code{mh-tool-bar-folder-buttons} and ++@code{mh-tool-bar-letter-buttons}. As you probably guessed, the former ++customizes the tool bar in MH-Folder mode and the latter in MH-Letter ++mode. Both of these options present you with a list of functions; ++check the functions whose icons you want to see and clear the check ++boxes for those you don't. ++ ++@findex mh-search ++@vindex mh-tool-bar-search-function ++ ++The function associated with the searching icon can be set via the ++option @code{mh-tool-bar-search-function}. By default, this is set to ++@code{mh-search}. @xref{Searching}. You can also choose @samp{Other ++Function} from the @samp{Value Menu} and enter a function of your own ++choosing. ++ ++@vindex mh-xemacs-use-tool-bar-flag ++ ++XEmacs provides a couple of extra options. The first, ++@code{mh-xemacs-use-tool-bar-flag}, controls whether to show the MH-E ++icons at all. By default, this option is turned on if the window ++system supports tool bars. If your system doesn't support tool bars, ++then you won't be able to turn on this option. ++ ++@vindex mh-xemacs-tool-bar-position ++ ++The second extra option is @code{mh-xemacs-tool-bar-position} which ++controls the placement of the tool bar along the four edges of the ++frame. You can choose from one of @samp{Same As Default Tool Bar}, ++@samp{Top}, @samp{Bottom}, @samp{Left}, or @samp{Right}. If this ++variable is set to anything other than @samp{Same As Default Tool Bar} ++and the default tool bar is in a different location, then two tool ++bars will be displayed: the MH-E tool bar and the default tool bar. ++ ++@node Searching, Threading, Tool Bar, Top ++@chapter Searching Through Messages ++ ++@cindex @samp{Search} menu ++@cindex menu, @samp{Search} ++@cindex searching ++@findex mh-search ++@kindex F s ++ ++Earlier, the command @kbd{F s} (@code{mh-search}) was introduced which ++helps you find messages that lie buried in your folders ++(@pxref{Folders}). This chapter covers this command in more detail. ++Several commands are used to compose the search criteria and to start ++searching. A couple of them can be found in the @samp{Search} menu. ++ ++@table @kbd ++@kindex C-c ? ++@findex mh-help ++@item C-c ? ++Display cheat sheet for the MH-E commands (@code{mh-help}). ++@c ------------------------- ++@cindex @samp{Search > Perform Search} menu item ++@cindex menu item, @samp{Search > Perform Search} ++@kindex C-c C-c ++@findex mh-index-do-search ++@item C-c C-c ++Find messages using @code{mh-search-program} ++(@code{mh-index-do-search}). ++@c ------------------------- ++@cindex @samp{Search > Search with pick} menu item ++@cindex menu item, @samp{Search > Search with pick} ++@kindex C-c C-p ++@findex mh-pick-do-search ++@item C-c C-p ++Find messages using @command{pick} (@code{mh-pick-do-search}). ++@c ------------------------- ++@kindex C-c ? ++@findex mh-help ++@item C-c ? ++Display cheat sheet for the MH-E commands (@code{mh-help}). ++@c ------------------------- ++@kindex C-c C-f C-a ++@kindex C-c C-f a ++@findex mh-to-field ++@item C-c C-f a ++@itemx C-c C-f C-a ++Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-b ++@kindex C-c C-f b ++@item C-c C-f b ++@itemx C-c C-f C-b ++Move to @samp{Bcc:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-c ++@kindex C-c C-f c ++@item C-c C-f c ++@itemx C-c C-f C-c ++Move to @samp{Cc:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-d ++@kindex C-c C-f d ++@item C-c C-f d ++@itemx C-c C-f C-d ++Move to @samp{Dcc:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-f ++@kindex C-c C-f f ++@item C-c C-f f ++@itemx C-c C-f C-f ++Move to @samp{Fcc:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-l ++@kindex C-c C-f l ++@item C-c C-f l ++@itemx C-c C-f C-l ++Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-m ++@kindex C-c C-f m ++@item C-c C-f m ++@itemx C-c C-f C-m ++Move to @samp{From:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-r ++@kindex C-c C-f r ++@item C-c C-f r ++@itemx C-c C-f C-r ++Move to @samp{Reply-To:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-s ++@kindex C-c C-f s ++@item C-c C-f s ++@itemx C-c C-f C-s ++Move to @samp{Subject:} header field (@code{mh-to-field}). ++@c ------------------------- ++@kindex C-c C-f C-t ++@kindex C-c C-f t ++@item C-c C-f t ++@itemx C-c C-f C-t ++Move to @samp{To:} header field (@code{mh-to-field}). ++@end table ++ ++Another few commands are available in the MH-Folder buffer resulting ++from a search. ++ ++@table @kbd ++@kindex @key{TAB} ++@findex mh-index-next-folder ++@item @key{TAB} ++Jump to the next folder marker (@code{mh-index-next-folder}). ++@c ------------------------- ++@kindex S-@key{TAB} ++@findex mh-index-previous-folder ++@item S-@key{TAB} ++Jump to the previous folder marker (@code{mh-index-previous-folder}). ++@c ------------------------- ++@kindex v ++@findex mh-index-visit-folder ++@item v ++Visit original folder from where the message at point was found ++(@code{mh-index-visit-folder}). ++@end table ++ ++@cindex @samp{mh-search} customization group ++@cindex customization group, @samp{mh-search} ++ ++There is one option from the @samp{mh-search} customization group used ++in searching. ++ ++@vtable @code ++@item mh-search-program ++Search program that MH-E shall use (default: @samp{Auto-detect}). ++@end vtable ++ ++The following hook is available. ++ ++@vtable @code ++@item mh-search-mode-hook ++Hook run upon entry to @code{mh-search-mode} (default: @code{nil}). ++@end vtable ++ ++The following face is available. ++ ++@vtable @code ++@item mh-search-folder ++Folder heading face in MH-Folder buffers created by searches. ++@end vtable ++ ++@findex mh-search-folder ++@kindex F s ++ ++The command @kbd{F s} (@code{mh-search-folder}) helps you find ++messages in your entire corpus of mail. You can search for messages to ++or from a particular person or about a particular subject. In fact, ++you can also search for messages containing selected strings in any ++arbitrary header field or any string found within the messages. ++ ++@cindex @command{pick} ++@cindex MH commands, @command{pick} ++ ++Out of the box, MH-E uses @command{pick} to find messages. With a ++little extra effort, you can set an indexing program which rewards you ++with extremely quick results. The drawback is that sometimes the index ++does not contain the words you're looking for. You can still use ++@command{pick} in these situations. ++ ++You are prompted for the folder to search. This can be @samp{all} to ++search all folders. Note that the search works recursively on the ++listed folder. ++ ++@cindex MH-Search mode ++@cindex modes, MH-Search ++ ++Next, an MH-Search buffer appears where you can enter search criteria. ++ ++@cartouche ++@smallexample ++From: ++To: ++Cc: ++Date: ++Subject: ++-------- ++# ++ ++ ++ ++ ++ ++ ++ ++ ++--:** search-pattern All L7 (MH-Search)--------------------------- ++Type C-c C-c to search messages, C-c C-p to use pick, C-c ? for help ++@end smallexample ++@end cartouche ++@i{Search window} ++ ++@cindex @command{pick} ++@cindex MH commands, @command{pick} ++ ++Edit this template by entering your search criteria in an appropriate ++header field that is already there, or create a new field yourself. If ++the string you're looking for could be anywhere in a message, then ++place the string underneath the row of dashes. ++ ++As an example, let's say that we want to find messages from Ginnean ++about horseback riding in the Kosciusko National Park (Australia) ++during January, 1994. Normally we would start with a broad search and ++narrow it down if necessary to produce a manageable amount of data, ++but we'll cut to the chase and create a fairly restrictive set of ++criteria as follows: ++ ++@smallexample ++@group ++From: ginnean ++To: ++Cc: ++Date: Jan 1994 ++Subject: ++-------- ++horse ++kosciusko ++@end group ++@end smallexample ++ ++@findex mh-to-field ++@kindex C-c C-f C-t ++ ++As with MH-Letter mode, MH-Search provides commands like @kbd{C-c C-f ++C-t} (@code{mh-to-field}) to help you fill in the blanks. ++@xref{Editing Message}. ++ ++@kindex F s ++@vindex mh-search-mode-hook ++ ++If you find that you do the same thing over and over when editing the ++search template, you may wish to bind some shortcuts to keys. This can ++be done with the variable @code{mh-search-mode-hook}, which is called ++when @kbd{F s} is run on a new pattern. ++ ++@findex mh-index-do-search ++@findex mh-pick-do-search ++@kindex C-c C-c ++@kindex C-c C-p ++ ++To perform the search, type @kbd{C-c C-c} (@code{mh-index-do-search}). ++Sometimes you're searching for text that is either not indexed, or ++hasn't been indexed yet. In this case you can override the default ++method with the pick method by running the command @kbd{C-c C-p} ++(@code{mh-pick-do-search}). ++ ++@cindex folders, @samp{+mhe-index} ++@cindex @samp{+mhe-index} ++@findex mh-index-next-folder ++@findex mh-index-previous-folder ++@kindex @key{TAB} ++@kindex S-@key{TAB} ++@vindex mh-search-folder ++ ++The messages that are found are put in a temporary sub-folder of ++@samp{+mhe-index} and are displayed in an MH-Folder buffer. This ++buffer is special because it displays messages from multiple folders; ++each set of messages from a given folder has a heading with the folder ++name. The appearance of the heading can be modified by customizing the ++face @code{mh-search-folder}. You can jump back and forth between the ++headings using the commands @kbd{@key{TAB}} ++(@code{mh-index-next-folder}) and @kbd{S-@key{TAB}} ++(@code{mh-index-previous-folder}). ++ ++@findex mh-index-visit-folder ++@findex mh-rescan-folder ++@kindex F r ++@kindex v ++ ++In addition, the command @kbd{v} (@code{mh-index-visit-folder}) can be ++used to visit the folder of the message at point. Initially, only the ++messages that matched the search criteria are displayed in the folder. ++While the temporary buffer has its own set of message numbers, the ++actual messages numbers are shown in the visited folder. Thus, the ++command @kbd{v} is useful to find the actual message number of an ++interesting message, or to view surrounding messages with the command ++@kbd{F r} @code{mh-rescan-folder}. @xref{Folders}. ++ ++@findex mh-kill-folder ++@kindex F k ++ ++Because this folder is temporary, you'll probably get in the habit of ++killing it when you're done with @kbd{F k} (@code{mh-kill-folder}). ++@xref{Folders}. ++ ++@kindex F s ++ ++You can regenerate the results by running @kbd{F s} with a prefix ++argument. ++ ++@cindex @command{procmail} ++@cindex Unix commands, @command{procmail} ++@cindex @samp{X-MHE-Checksum:} header field ++@cindex header field, @samp{X-MHE-Checksum:} ++ ++Note: This command uses an @samp{X-MHE-Checksum:} header field to ++cache the MD5 checksum of a message. This means that if an incoming ++message already contains an @samp{X-MHE-Checksum:} field, that message ++might not be found by this command. The following @command{procmail} ++recipe avoids this problem by renaming the existing header field: ++ ++@smallexample ++@group ++:0 wf ++| formail -R "X-MHE-Checksum" "X-Old-MHE-Checksum" ++@end group ++@end smallexample ++ ++@xref{Limits}, for an alternative interface to searching. ++ ++@section Configuring Indexed Searches ++ ++@cindex @command{grep} ++@cindex @command{mairix} ++@cindex @command{namazu} ++@cindex @command{pick} ++@cindex @command{swish++} ++@cindex @command{swish-e} ++@cindex Unix commands, @command{grep} ++@cindex Unix commands, @command{mairix} ++@cindex Unix commands, @command{namazu} ++@cindex Unix commands, @command{pick} ++@cindex Unix commands, @command{swish++} ++@cindex Unix commands, @command{swish-e} ++@findex mh-search ++@kindex F s ++@vindex mh-search-program ++ ++The command @kbd{F s} (@code{mh-search}) runs the command defined by ++the option @code{mh-search-program}. The default value is ++@samp{Auto-detect} which means that MH-E will automatically choose one ++of @command{swish++}, @command{swish-e}, @command{mairix}, ++@command{namazu}, @command{pick} and @command{grep} in that order. If, ++for example, you have both @command{swish++} and @command{mairix} ++installed and you want to use @command{mairix}, then you can set this ++option to @samp{mairix}. ++ ++The following sub-sections describe how to set up the various indexing ++programs to use with MH-E. ++ ++@subsection swish++ ++ ++@cindex @command{swish++} ++@cindex Unix commands, @command{swish++} ++ ++In the examples below, replace @file{/home/user/Mail} with the path to ++your MH directory. ++ ++First create the directory @file{/home/user/Mail/.swish++}. Then ++create the file @file{/home/user/Mail/.swish++/swish++.conf} with the ++following contents: ++ ++@smallexample ++@group ++IncludeMeta Bcc Cc Comments Content-Description From Keywords ++IncludeMeta Newsgroups Resent-To Subject To ++IncludeMeta Message-Id References In-Reply-To ++IncludeFile Mail * ++IndexFile /home/user/Mail/.swish++/swish++.index ++@end group ++@end smallexample ++ ++Use the following command line to generate the swish index. Run this ++daily from cron: ++ ++@smallexample ++@group ++find /home/user/Mail -path /home/user/Mail/mhe-index -prune \ ++ -o -path /home/user/Mail/.swish++ -prune \ ++ -o -name "[0-9]*" -print \ ++ | index -c /home/user/Mail/.swish++/swish++.conf - ++@end group ++@end smallexample ++ ++This command does not index the folders that hold the results of your ++searches in @samp{+mhe-index} since they tend to be ephemeral and the ++original messages are indexed anyway. ++ ++@cindex @command{index} ++@cindex Unix commands, @command{index} ++@cindex @command{index++} ++@cindex Unix commands, @command{index++} ++ ++On some systems (Debian GNU/Linux, for example), use @command{index++} ++instead of @command{index}. ++ ++@subsection swish ++ ++@cindex @command{swish-e} ++@cindex Unix commands, @command{swish-e} ++ ++In the examples below, replace @file{/home/user/Mail} with the path to ++your MH directory. ++ ++First create the directory @file{/home/user/Mail/.swish}. Then create ++the file @file{/home/user/Mail/.swish/config} with the following ++contents: ++ ++@smallexample ++@group ++DefaultContents TXT* ++IndexDir /home/user/Mail ++IndexFile /home/user/Mail/.swish/index ++IndexName "Mail Index" ++IndexDescription "Mail Index" ++IndexPointer "http://nowhere" ++IndexAdmin "nobody" ++#MetaNames automatic ++IndexReport 3 ++FollowSymLinks no ++UseStemming no ++IgnoreTotalWordCountWhenRanking yes ++WordCharacters abcdefghijklmnopqrstuvwxyz0123456789- ++BeginCharacters abcdefghijklmnopqrstuvwxyz ++EndCharacters abcdefghijklmnopqrstuvwxyz0123456789 ++IgnoreLimit 50 1000 ++IndexComments 0 ++FileRules filename contains \D ++FileRules pathname contains /home/user/Mail/.swish ++FileRules pathname contains /home/user/Mail/mhe-index ++FileRules filename is index ++@end group ++@end smallexample ++ ++This configuration does not index the folders that hold the results of ++your searches in @samp{+mhe-index} since they tend to be ephemeral and ++the original messages are indexed anyway. ++ ++If there are any directories you would like to ignore, append lines ++like the following to @file{config}: ++ ++@smallexample ++FileRules pathname contains /home/user/Mail/scripts ++@end smallexample ++ ++@cindex @command{swish-e} ++@cindex Unix commands, @command{swish-e} ++ ++Use the following command line to generate the swish index. Run this ++daily from cron: ++ ++@smallexample ++swish-e -c /home/user/Mail/.swish/config ++@end smallexample ++ ++@subsection mairix ++ ++@cindex @command{mairix} ++@cindex Unix commands, @command{mairix} ++ ++In the examples below, replace @file{/home/user/Mail} with the path to ++your MH directory. ++ ++First create the directory @file{/home/user/Mail/.mairix}. Then create ++the file @file{/home/user/Mail/.mairix/config} with the following ++contents: ++ ++@smallexample ++@group ++base=/home/user/Mail ++ ++# List of folders that should be indexed. 3 dots at the end means there ++# are subfolders within the folder ++mh=archive...:inbox:drafts:news:sent:trash ++ ++vfolder_format=raw ++database=/home/user/Mail/mairix/database ++@end group ++@end smallexample ++ ++Use the following command line to generate the mairix index. Run this daily ++from cron: ++ ++@smallexample ++mairix -f /home/user/Mail/.mairix/config ++@end smallexample ++ ++@subsection namazu ++ ++@cindex @command{namazu} ++@cindex Unix commands, @command{namazu} ++ ++In the examples below, replace @file{/home/user/Mail} with the path to ++your MH directory. ++ ++First create the directory @file{/home/user/Mail/.namazu}. Then create ++the file @file{/home/user/Mail/.namazu/mknmzrc} with the following ++contents: ++ ++@smallexample ++@group ++package conf; # Don't remove this line! ++$ADDRESS = 'user@@localhost'; ++$ALLOW_FILE = "[0-9]*"; ++$EXCLUDE_PATH = "^/home/user/Mail/(mhe-index|spam)"; ++@end group ++@end smallexample ++ ++This configuration does not index the folders that hold the results of ++your searches in @samp{+mhe-index} since they tend to be ephemeral and ++the original messages are indexed anyway. ++ ++Use the following command line to generate the namazu index. Run this ++daily from cron: ++ ++@smallexample ++mknmz -f /home/user/Mail/.namazu/mknmzrc -O /home/user/Mail/.namazu \ ++ /home/user/Mail ++@end smallexample ++ ++@subsection pick ++ ++@cindex @command{pick} ++@cindex MH commands, @command{pick} ++ ++This search method does not require any setup. ++ ++Read @command{pick}(1) or the section ++@uref{@value{MH-BOOK-HOME}/finpic.html, Finding Messages with pick} in ++the MH book to find out more about how to enter the criteria. ++ ++@subsection grep ++ ++@cindex @command{grep} ++@cindex Unix commands, @command{grep} ++ ++This search method does not require any setup. ++ ++Unlike the other search methods, this method does not use the ++MH-Search buffer. Instead, you simply enter a regular expression in ++the minibuffer. For help in constructing regular expressions, see your ++man page for @command{grep}. ++ ++@node Threading, Limits, Searching, Top ++@chapter Viewing Message Threads ++ ++@cindex threading ++ ++MH-E groups messages by @dfn{threads} which are messages that are part ++of the same discussion and usually all have the same @samp{Subject:} ++header field. Other ways to organize messages in a folder include ++limiting (@pxref{Limits}) or using full-text indexed searches ++(@pxref{Searching}). ++ ++@cindex root, in threads ++@cindex siblings, in threads ++@cindex ancestor, in threads ++ ++A thread begins with a single message called a @dfn{root}. All replies ++to the same message are @dfn{siblings} of each other. Any message that ++has replies to it is an @dfn{ancestor} of those replies. ++ ++There are several commands that you can use to navigate and operate on ++threads. ++ ++@table @kbd ++@kindex T ? ++@findex mh-prefix-help ++@item T ? ++Display cheat sheet for the commands of the current prefix in ++minibuffer (@code{mh-prefix-help}). ++@c ------------------------- ++@kindex T o ++@findex mh-thread-refile ++@item T o ++Refile (output) thread into folder (@code{mh-thread-refile}). ++@c ------------------------- ++@kindex T d ++@findex mh-thread-delete ++@item T d ++Delete thread (@code{mh-thread-delete}). ++@c ------------------------- ++@kindex T t ++@findex mh-toggle-threads ++@item T t ++Toggle threaded view of folder (@code{mh-toggle-threads}). ++@c ------------------------- ++@kindex T n ++@findex mh-thread-next-sibling ++@item T n ++Display next sibling (@code{mh-thread-next-sibling}). ++@c ------------------------- ++@kindex T p ++@findex mh-thread-previous-sibling ++@item T p ++Display previous sibling (@code{mh-thread-previous-sibling}). ++@c ------------------------- ++@kindex T u ++@findex mh-thread-ancestor ++@item T u ++Display ancestor of current message (@code{mh-thread-ancestor}). ++@end table ++ ++@cindex @samp{mh-thread} customization group ++@cindex customization group, @samp{mh-thread} ++ ++The @samp{mh-thread} customization group contains one option. ++ ++@vtable @code ++@item mh-show-threads-flag ++On means new folders start in threaded mode (default: @samp{off}). ++@end vtable ++ ++@findex mh-toggle-threads ++@kindex T t ++@vindex mh-large-folder ++@vindex mh-show-threads-flag ++ ++Threading large number of messages can be time consuming so the option ++@code{mh-show-threads-flag} is turned off by default. If you turn on ++this option, then threading will be done only if the number of ++messages being threaded is less than @code{mh-large-folder}. In any ++event, threading can be turned on (and off) with the command @kbd{T t} ++(@code{mh-toggle-threads}). ++ ++@findex mh-thread-ancestor ++@findex mh-thread-next-sibling ++@findex mh-thread-previous-sibling ++@kindex T n ++@kindex T p ++@kindex T u ++ ++There are a few commands to help you navigate threads. If you do not ++care for the way a particular thread has turned, you can move up the ++chain of messages with the command @kbd{T u} ++(@code{mh-thread-ancestor}. At any point you can use @kbd{T n} ++(@code{mh-thread-next-sibling} or @kbd{T p} ++(@code{mh-thread-previous-sibling}) to jump to the next or previous ++sibling, skipping the sub-threads. The command @kbd{T u} can also take ++a prefix argument to jump to the message that started everything. ++ ++@findex mh-delete-subject-or-thread ++@findex mh-thread-delete ++@findex mh-thread-refile ++@kindex k ++@kindex T d ++@kindex T o ++ ++There are threaded equivalents for the commands that delete and refile ++messages. For example, @kbd{T o} (@code{mh-thread-refile}) refiles the ++current message and all its children. Similarly, the command @kbd{T d} ++(@code{mh-thread-delete}) deletes the current message and all its ++children. These commands do not refile or delete sibling messages. ++@xref{Navigating}, for a description of the similar command @kbd{k} ++(@code{mh-delete-subject-or-thread}). ++ ++@vindex mh-large-folder ++ ++If you find that threading is too slow, it may be that you have ++@code{mh-large-folder} set too high. Also, threading is one of the few ++features of MH-E that really benefits from compiling. If you haven't ++compiled MH-E, I encourage you to do so@footnote{If you're not sure if ++MH-E has been byte-compiled, you could try running @samp{locate ++mh-thread.elc} or otherwise find MH-E on your system and ensure that ++@file{mh-thread.elc} exists. If you have multiple versions and you ++find that one is compiled but the other is not, then go into your ++@samp{*scratch*} buffer in Emacs, enter @kbd{load-path C-j}, and ++ensure that the byte-compiled version appears first in the ++@code{load-path}. If you find that MH-E is not compiled and you ++installed MH-E yourself, please refer to the installation directions ++in the file @file{README} in the distribution.}. ++ ++@node Limits, Sequences, Threading, Top ++@chapter Limiting Display ++ ++@cindex limits ++@cindex filters ++ ++Another way to organize messages in a folder besides threading ++(@pxref{Threading}) or using full-text indexed searches ++(@pxref{Searching}) is by limiting the folder display to messages that ++are similar to the current message. ++ ++@table @kbd ++@kindex / ? ++@findex mh-prefix-help ++@item / ? ++Display cheat sheet for the commands of the current prefix in ++minibuffer (@code{mh-prefix-help}). ++@c ------------------------- ++@cindex @samp{Sequence > Narrow to Tick Sequence} menu item ++@cindex menu item, @samp{Sequence > Narrow to Tick Sequence} ++@kindex / ' ++@findex mh-narrow-to-tick ++@item / ' ++Limit to messages in the @samp{tick} sequence ++(@code{mh-narrow-to-tick}). ++@c ------------------------- ++@kindex / c ++@findex mh-narrow-to-cc ++@item / c ++Limit to messages with the same @samp{Cc:} field ++(@code{mh-narrow-to-cc}). ++@c ------------------------- ++@kindex / m ++@findex mh-narrow-to-from ++@item / m ++Limit to messages with the same @samp{From:} field ++(@code{mh-narrow-to-from}). ++@c ------------------------- ++@kindex / g ++@findex mh-narrow-to-range ++@item / g ++Limit to range (@code{mh-narrow-to-range}). ++@c ------------------------- ++@cindex @samp{Sequence > Narrow to Subject Sequence} menu item ++@cindex menu item, @samp{Sequence > Narrow to Subject Sequence} ++@kindex / s ++@findex mh-narrow-to-subject ++@item / s ++Limit to messages with the same @samp{Subject:} field ++(@code{mh-narrow-to-subject}). ++@c ------------------------- ++@kindex / t ++@findex mh-narrow-to-to ++@item / t ++Limit to messages with the same @samp{To:} field ++(@code{mh-narrow-to-to}). ++@c ------------------------- ++@cindex @samp{Sequence > Widen from Sequence} menu item ++@cindex menu item, @samp{Sequence > Widen from Sequence} ++@kindex / w ++@findex mh-widen ++@item / w ++Remove last restriction (@code{mh-widen}). ++@end table ++ ++All of the limiting commands above refine the display in some way. ++ ++@cindex @command{pick} ++@cindex MH commands, @command{pick} ++@findex mh-narrow-to-cc ++@findex mh-narrow-to-from ++@findex mh-narrow-to-subject ++@findex mh-narrow-to-to ++@kindex / c ++@kindex / m ++@kindex / s ++@kindex / t ++ ++The commands @kbd{/ c} (@code{mh-narrow-to-cc}), @kbd{/ m} ++(@code{mh-narrow-to-from}), @kbd{/ s} (@code{mh-narrow-to-subject}), ++and @kbd{/ t} (@code{mh-narrow-to-to}) restrict the display to ++messages matching the content of the respective field in the current ++message. However, you can give any of these a prefix argument to edit ++the @command{pick} expression used to narrow the view@footnote{See ++@command{pick}(1) or the section ++@uref{@value{MH-BOOK-HOME}/finpic.html, Finding Messages with pick} in ++the MH book.}. ++ ++@cindex @samp{tick} sequence ++@cindex sequence, @samp{tick} ++@cindex ticked messages, viewing ++@findex mh-narrow-to-range ++@findex mh-narrow-to-tick ++@kindex / ' ++@kindex / g ++ ++You can also limit the display to messages in the @samp{tick} sequence ++with the command @kbd{/ '} (@code{mh-narrow-to-tick}). ++@xref{Sequences}, for information on putting message into the ++@samp{tick} sequence. Use the @kbd{/ g} (@code{mh-narrow-to-range}) ++command to limit the display to messages in a range (@pxref{Ranges}). ++ ++@findex mh-widen ++@kindex / w ++ ++Each limit can be undone in turn with the @kbd{/ w} (@code{mh-widen}) ++command. Give this command a prefix argument to remove all limits. ++ ++@node Sequences, Junk, Limits, Top ++@chapter Using Sequences ++ ++@cindex @samp{Sequence} menu ++@cindex menu, @samp{Sequence} ++@cindex sequences ++ ++For the whole scoop on MH sequences, refer to ++@samp{mh-sequence}(5)@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/morseq.html, More About Sequences} in the MH ++book.}. As you've read, several of the MH-E commands can operate on a ++sequence, which is a shorthand for a range or group of messages. For ++example, you might want to forward several messages to a friend or ++colleague. Here's how to manipulate sequences. These commands are also ++available in the @samp{Sequence} menu. ++ ++@table @kbd ++@cindex @samp{Sequence > Toggle Tick Mark} menu item ++@cindex menu item, @samp{Sequence > Toggle Tick Mark} ++@kindex ' ++@findex mh-toggle-tick ++@item ' ++Toggle tick mark of range (@code{mh-toggle-tick}). ++@c ------------------------- ++@kindex S ? ++@findex mh-prefix-help ++@item S ? ++Display cheat sheet for the commands of the current prefix in ++minibuffer (@code{mh-prefix-help}). ++@c ------------------------- ++@cindex @samp{Sequence > Narrow to Tick Sequence} menu item ++@cindex menu item, @samp{Sequence > Narrow to Tick Sequence} ++@kindex S ' ++@findex mh-narrow-to-tick ++@item S ' ++Limit to ticked messages (@code{mh-narrow-to-tick}). ++@c ------------------------- ++@cindex @samp{Sequence > Delete Message from Sequence...} menu item ++@cindex menu item, @samp{Sequence > Delete Message from Sequence...} ++@kindex S d ++@findex mh-delete-msg-from-seq ++@item S d ++Delete range from sequence (@code{mh-delete-msg-from-seq}). ++@c ------------------------- ++@cindex @samp{Sequence > Delete Sequence...} menu item ++@cindex menu item, @samp{Sequence > Delete Sequence...} ++@kindex S k ++@findex mh-delete-seq ++@item S k ++Delete sequence (@code{mh-delete-seq}). ++@c ------------------------- ++@cindex @samp{Sequence > List Sequences in Folder...} menu item ++@cindex menu item, @samp{Sequence > List Sequences in Folder...} ++@kindex S l ++@findex mh-list-sequences ++@item S l ++List all sequences in folder (@code{mh-list-sequences}). ++@c ------------------------- ++@cindex @samp{Sequence > Narrow to Sequence...} menu item ++@cindex menu item, @samp{Sequence > Narrow to Sequence...} ++@kindex S n ++@findex mh-narrow-to-seq ++@item S n ++Restrict display to messages in sequence (@code{mh-narrow-to-seq}). ++@c ------------------------- ++@cindex @samp{Sequence > Add Message to Sequence...} menu item ++@cindex menu item, @samp{Sequence > Add Message to Sequence...} ++@kindex S p ++@findex mh-put-msg-in-seq ++@item S p ++Add range to sequence (@code{mh-put-msg-in-seq}). ++@c ------------------------- ++@cindex @samp{Sequence > List Sequences for Message} menu item ++@cindex menu item, @samp{Sequence > List Sequences for Message} ++@kindex S s ++@findex mh-msg-is-in-seq ++@item S s ++Display the sequences in which the current message appears ++(@code{mh-msg-is-in-seq}). ++@c ------------------------- ++@cindex @samp{Sequence > Widen from Sequence} menu item ++@cindex menu item, @samp{Sequence > Widen from Sequence} ++@kindex S w ++@findex mh-widen ++@item S w ++Remove last restriction (@code{mh-widen}). ++@c ------------------------- ++@findex mh-update-sequences ++@item M-x mh-update-sequences ++Flush MH-E's state out to MH@. ++@end table ++ ++@cindex @samp{mh-sequences} customization group ++@cindex customization group, @samp{mh-sequences} ++ ++The @samp{mh-sequences} customization group contains the options ++associated with sequences. ++ ++@vtable @code ++@item mh-refile-preserves-sequences-flag ++On means that sequences are preserved when messages are refiled ++(default: @samp{on}). ++@c ------------------------- ++@item mh-tick-seq ++The name of the MH sequence for ticked messages (default: @samp{'tick}). ++@c ------------------------- ++@item mh-update-sequences-after-mh-show-flag ++On means flush MH sequences to disk after message is shown (default: ++@samp{on}). ++@end vtable ++ ++The following hook is available. ++ ++@vtable @code ++@item mh-unseen-updated-hook ++Hook run after the unseen sequence has been updated (default: @code{nil}). ++@end vtable ++ ++@cindex @command{pick} ++@cindex MH commands, @command{pick} ++@findex mh-put-msg-in-seq ++@kindex S p ++ ++To place a message in a sequence, use @kbd{S p} ++(@code{mh-put-msg-in-seq}). Give @kbd{S p} a range and you can add all ++the messages in a sequence to another sequence (for example, @kbd{C-u ++S p SourceSequence @key{RET} DestSequence @key{RET}}, @pxref{Ranges}). ++ ++@cindex @samp{tick} sequence ++@cindex sequence, @samp{tick} ++@cindex ticking messages ++@findex mh-index-ticked-messages ++@findex mh-toggle-tick ++@kindex ' ++@kindex F ' ++@kindex S p ++ ++One specific use of the @kbd{S p} command is @kbd{'} ++(@code{mh-toggle-tick}) which adds messages to the @samp{tick} ++sequence. This sequence can be viewed later with the @kbd{F '} ++(@code{mh-index-ticked-messages}) command (@pxref{Folders}). ++ ++@vindex mh-tick-seq ++ ++You can customize the option @code{mh-tick-seq} if you already use the ++@samp{tick} sequence for your own use. You can also disable all of the ++ticking functions by choosing the @samp{Disable Ticking} item but ++there isn't much advantage to that. ++ ++@cindex MH-Folder mode ++@cindex modes, MH-Folder ++@findex mh-narrow-to-seq ++@findex mh-narrow-to-tick ++@findex mh-widen ++@kindex S ' ++@kindex S n ++@kindex S w ++ ++Once you've placed some messages in a sequence, you may wish to narrow ++the field of view to just those messages in the sequence you've ++created. To do this, use @kbd{S n} (@code{mh-narrow-to-seq}). You are ++prompted for the name of the sequence. What this does is show only ++those messages that are in the selected sequence in the MH-Folder ++buffer. In addition, it limits further MH-E searches to just those ++messages. To narrow the view to the messages in the @samp{tick} ++sequence, use @kbd{S '} (@code{mh-narrow-to-tick}). When you want to ++widen the view to all your messages again, use @kbd{S w} ++(@code{mh-widen}). ++ ++@cindex buffers, @samp{*MH-E Sequences*} ++@cindex @samp{*MH-E Sequences*} ++@findex mh-list-sequences ++@findex mh-msg-is-in-seq ++@kindex S l ++@kindex S s ++ ++You can see which sequences in which a message appears with the ++command @kbd{S s} (@code{mh-msg-is-in-seq}). Use a prefix argument to ++display the sequences in which another message appears (as in @kbd{C-u ++42 S s @key{RET}}). Or, you can list all sequences in a selected ++folder (default is current folder) with @kbd{S l} ++(@code{mh-list-sequences}). The list appears in a buffer named ++@samp{*MH-E Sequences*} (@pxref{Miscellaneous}). ++ ++@cindex MH profile component, @samp{Previous-Sequence:} ++@cindex @samp{cur} sequence ++@cindex @samp{Previous-Sequence:} MH profile component ++@cindex sequence, @samp{cur} ++@cindex sequence, @samp{Previous-Sequence} ++@vindex mh-refile-preserves-sequences-flag ++ ++If a message is in any sequence (except ++@samp{Previous-Sequence:}@footnote{See @samp{mh-profile}(5)).} and ++@samp{cur}) when it is refiled, then it will still be in those ++sequences in the destination folder. If this behavior is not desired, ++then turn off the option @code{mh-refile-preserves-sequences-flag}. ++ ++@findex mh-delete-msg-from-seq ++@findex mh-delete-seq ++@kindex d ++@kindex S d ++@kindex S k ++ ++If you want to remove a message (or range, @pxref{Ranges}) from a ++sequence, use @kbd{S d} (@code{mh-delete-msg-from-seq}). If you want ++to delete an entire sequence, use @kbd{S k} (@code{mh-delete-seq}). In ++the latter case you are prompted for the sequence to delete. Note that ++this deletes only the sequence, not the messages in the sequence. If ++you want to delete the messages, use @kbd{C-u d} (@pxref{Reading ++Mail}). ++ ++@cindex @samp{Unseen-Sequence:} MH profile component ++@cindex @samp{cur} sequence ++@cindex @samp{tick} sequence ++@cindex MH profile component, @samp{Unseen-Sequence:} ++@cindex sequence, @samp{Unseen-Sequence} ++@cindex sequence, @samp{cur} ++@cindex sequence, @samp{tick} ++@findex mh-update-sequences ++@kindex M-x mh-update-sequences ++@kindex q ++@kindex x ++@vindex mh-tick-seq ++@vindex mh-update-sequences-after-mh-show-flag ++ ++Three sequences are maintained internally by MH-E and pushed out to MH ++when a message is shown. They include the sequence specified by your ++@samp{Unseen-Sequence:} profile component, @samp{cur}, and the ++sequence listed by the option @code{mh-tick-seq} which is @samp{tick} ++by default. If you do not like this behavior, turn off the option ++@code{mh-update-sequences-after-mh-show-flag}. You can then update the ++state manually with the @kbd{x}, @kbd{q}, or @kbd{M-x ++mh-update-sequences} commands. ++ ++@vindex mh-seen-list ++@vindex mh-unseen-updated-hook ++ ++The hook @code{mh-unseen-updated-hook} is run after the unseen ++sequence has been updated. The variable @code{mh-seen-list} can be ++used by this hook to obtain the list of messages which were removed ++from the unseen sequence. ++ ++@cindex @command{mark} ++@cindex MH commands, @command{mark} ++@kindex S n ++@kindex S w ++ ++With the exceptions of @kbd{S n} and @kbd{S w}, the underlying MH ++command dealing with sequences is @command{mark}@footnote{See the ++section @uref{@value{MH-BOOK-HOME}/mmbwm.html, Make Message Bookmarks ++with mark} in the MH book.}. ++ ++@node Junk, Miscellaneous, Sequences, Top ++@chapter Dealing With Junk Mail ++ ++@cindex Marshall Rose ++@cindex junk mail ++@cindex spam ++ ++Marshall Rose once wrote a paper on MH entitled, @cite{How to process ++200 messages a day and still get some real work done}. This chapter ++could be entitled, @cite{How to process 1000 spams a day and still get ++some real work done}. ++ ++@cindex blacklisting ++@cindex ham ++@cindex viruses ++@cindex whitelisting ++@cindex worms ++ ++We use the terms @dfn{junk mail} and @dfn{spam} interchangeably for ++any unwanted message which includes spam, @dfn{viruses}, and ++@dfn{worms}. The opposite of spam is @dfn{ham}. The act of classifying ++a sender as one who sends junk mail is called @dfn{blacklisting}; the ++opposite is called @dfn{whitelisting}. ++ ++@table @kbd ++@kindex J ? ++@findex mh-prefix-help ++@item J ? ++Display cheat sheet for the commands of the current prefix in ++minibuffer (@code{mh-prefix-help}). ++@c ------------------------- ++@kindex J b ++@findex mh-junk-blacklist ++@item J b ++Blacklist range as spam (@code{mh-junk-blacklist}). ++@c ------------------------- ++@kindex J w ++@findex mh-junk-whitelist ++@item J w ++Whitelist range as ham (@code{mh-junk-whitelist}). ++@c ------------------------- ++@item @code{mh-spamassassin-identify-spammers} ++Identify spammers who are repeat offenders. ++@end table ++ ++@cindex @samp{mh-junk} customization group ++@cindex customization group, @samp{mh-junk} ++ ++The following table lists the options from the @samp{mh-junk} ++customization group. ++ ++@vtable @code ++@item mh-junk-background ++If on, spam programs are run in background (default: @samp{off}). ++@c ------------------------- ++@item mh-junk-disposition ++Disposition of junk mail (default: @samp{Delete Spam}). ++@c ------------------------- ++@item mh-junk-program ++Spam program that MH-E should use (default: @samp{Auto-detect}). ++@end vtable ++ ++@cindex SpamProbe ++@cindex Spamassassin ++@cindex bogofilter ++@cindex spam filters, SpamProbe ++@cindex spam filters, Spamassassin ++@cindex spam filters, bogofilter ++ ++MH-E depends on @uref{http://spamassassin.apache.org/, SpamAssassin}, ++@uref{http://bogofilter.sourceforge.net/, bogofilter}, or ++@uref{http://spamprobe.sourceforge.net/, SpamProbe} to throw the dreck ++away. This chapter describes briefly how to configure these programs ++to work well with MH-E and how to use MH-E's interface that provides ++continuing education for these programs. ++ ++@vindex mh-junk-program ++ ++The default setting of the option @code{mh-junk-program} is ++@samp{Auto-detect} which means that MH-E will automatically choose one ++of SpamAssassin, bogofilter, or SpamProbe in that order. If, for ++example, you have both SpamAssassin and bogofilter installed and you ++want to use bogofilter, then you can set this option to ++@samp{Bogofilter}. ++ ++@findex mh-junk-blacklist ++@kindex J b ++@vindex mh-junk-disposition ++ ++The command @kbd{J b} (@code{mh-junk-blacklist}) trains the spam ++program in use with the content of the range (@pxref{Ranges}) and then ++handles the message(s) as specified by the option ++@code{mh-junk-disposition}. By default, this option is set to ++@samp{Delete Spam} but you can also specify the name of the folder ++which is useful for building a corpus of spam for training purposes. ++ ++@findex mh-junk-whitelist ++@kindex J w ++ ++In contrast, the command @kbd{J w} (@code{mh-junk-whitelist}) ++reclassifies a range of messages (@pxref{Ranges}) as ham if it were ++incorrectly classified as spam. It then refiles the message into the ++@file{+inbox} folder. ++ ++@cindex @samp{*MH-E Log*} ++@cindex buffers, @samp{*MH-E Log*} ++@findex call-process ++@vindex mh-junk-background ++ ++By default, the programs are run in the foreground, but this can be ++slow when junking large numbers of messages. If you have enough memory ++or don't junk that many messages at the same time, you might try ++turning on the option @code{mh-junk-background}. @footnote{Note that ++the option @code{mh-junk-background} is used as the @code{display} ++argument in the call to @code{call-process}. Therefore, turning on ++this option means setting its value to @samp{0}. You can also set its ++value to @samp{t} to direct the programs' output to the @samp{*MH-E ++Log*} buffer; this may be useful for debugging.} ++ ++The following sections discuss the various counter-spam measures that ++MH-E can work with. ++ ++@cindex @file{.procmailrc} ++@cindex files, @file{.procmailrc} ++ ++@subheading SpamAssassin ++ ++@cindex Spamassassin ++@cindex spam filters, Spamassassin ++ ++SpamAssassin is one of the more popular spam filtering programs. Get ++it from your local distribution or from the ++@uref{http://spamassassin.apache.org/, SpamAssassin web site}. ++ ++To use SpamAssassin, add the following recipes to @file{~/.procmailrc}: ++ ++@cindex @command{spamc} ++@cindex @samp{X-Spam-Level:} header field ++@cindex @samp{X-Spam-Status:} header field ++@cindex header field, @samp{X-Spam-Level:} ++@cindex header field, @samp{X-Spam-Status:} ++ ++@smallexample ++PATH=$PATH:/usr/bin/mh ++MAILDIR=$HOME/`mhparam Path` ++ ++# Fight spam with SpamAssassin. ++:0fw ++| spamc ++ ++# Anything with a spam level of 10 or more is junked immediately. ++:0: ++* ^X-Spam-Level: .......... ++/dev/null ++ ++:0: ++* ^X-Spam-Status: Yes ++spam/. ++@end smallexample ++ ++If you don't use @command{spamc}, use @samp{spamassassin -P -a}. ++ ++Note that one of the recipes above throws away messages with a score ++greater than or equal to 10. Here's how you can determine a value that ++works best for you. ++ ++First, run @samp{spamassassin -t} on every mail message in your ++archive and use @command{gnumeric} to verify that the average plus the ++standard deviation of good mail is under 5, the SpamAssassin default ++for ``spam''. ++ ++Using @command{gnumeric}, sort the messages by score and view the ++messages with the highest score. Determine the score which encompasses ++all of your interesting messages and add a couple of points to be ++conservative. Add that many dots to the @samp{X-Spam-Level:} header ++field above to send messages with that score down the drain. ++ ++In the example above, messages with a score of 5-9 are set aside in ++the @samp{+spam} folder for later review. The major weakness of ++rules-based filters is a plethora of false positives so it is ++worthwhile to check. ++ ++@findex mh-junk-blacklist ++@findex mh-junk-whitelist ++@kindex J b ++@kindex J w ++ ++If SpamAssassin classifies a message incorrectly, or is unsure, you can ++use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and ++@kbd{J w} (@code{mh-junk-whitelist}). ++ ++@cindex @command{sa-learn} ++@cindex @file{.spamassassin/user_prefs} ++@cindex files, @file{.spamassassin/user_prefs} ++ ++The command @kbd{J b} (@code{mh-junk-blacklist}) adds a ++@samp{blacklist_from} entry to @file{~/spamassassin/user_prefs}, ++deletes the message, and sends the message to the Razor, so that ++others might not see this spam. If the @command{sa-learn} command is ++available, the message is also recategorized as spam. ++ ++The command@kbd{J w} (@code{mh-junk-whitelist}) adds a ++@samp{whitelist_from} rule to @samp{~/.spamassassin/user_prefs}. If ++the @command{sa-learn} command is available, the message is also ++recategorized as ham. ++ ++Over time, you'll observe that the same host or domain occurs ++repeatedly in the @samp{blacklist_from} entries, so you might think ++that you could avoid future spam by blacklisting all mail from a ++particular domain. The utility function ++@code{mh-spamassassin-identify-spammers} helps you do precisely that. ++This function displays a frequency count of the hosts and domains in ++the @samp{blacklist_from} entries from the last blank line in ++@file{~/.spamassassin/user_prefs} to the end of the file. This ++information can be used so that you can replace multiple ++@samp{blacklist_from} entries with a single wildcard entry such as: ++ ++@smallexample ++blacklist_from *@@*amazingoffersdirect2u.com ++@end smallexample ++ ++In versions of SpamAssassin (2.50 and on) that support a Bayesian ++classifier, @kbd{J b} @code{(mh-junk-blacklist}) uses the program ++@command{sa-learn} to recategorize the message as spam. Neither MH-E, ++nor SpamAssassin, rebuilds the database after adding words, so you ++will need to run @samp{sa-learn --rebuild} periodically. This can be ++done by adding the following to your @file{crontab}: ++ ++@smallexample ++0 * * * * sa-learn --rebuild > /dev/null 2>&1 ++@end smallexample ++ ++@subheading Bogofilter ++ ++@cindex bogofilter ++@cindex spam filters, bogofilter ++ ++Bogofilter is a Bayesian spam filtering program. Get it from your ++local distribution or from the ++@uref{http://bogofilter.sourceforge.net/, bogofilter web site}. ++ ++Bogofilter is taught by running: ++ ++@smallexample ++bogofilter -n < good-message ++@end smallexample ++ ++on every good message, and ++ ++@smallexample ++bogofilter -s < spam-message ++@end smallexample ++ ++@cindex full training ++ ++on every spam message. This is called a @dfn{full training}; three ++other training methods are described in the FAQ that is distributed ++with bogofilter. Note that most Bayesian filters need 1000 to 5000 of ++each type of message to start doing a good job. ++ ++To use bogofilter, add the following recipes to @file{~/.procmailrc}: ++ ++@cindex @samp{X-Bogosity:} header field ++@cindex header field, @samp{X-Bogosity:} ++ ++@smallexample ++PATH=$PATH:/usr/bin/mh ++MAILDIR=$HOME/`mhparam Path` ++ ++# Fight spam with Bogofilter. ++:0fw ++| bogofilter -3 -e -p ++ ++:0: ++* ^X-Bogosity: Yes, tests=bogofilter ++spam/. ++ ++:0: ++* ^X-Bogosity: Unsure, tests=bogofilter ++spam/unsure/. ++@end smallexample ++ ++@findex mh-junk-blacklist ++@findex mh-junk-whitelist ++@kindex J b ++@kindex J w ++ ++If bogofilter classifies a message incorrectly, or is unsure, you can ++use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J ++w} (@code{mh-junk-whitelist}) to update bogofilter's training. ++ ++The @cite{Bogofilter FAQ} suggests that you run the following ++occasionally to shrink the database: ++ ++@smallexample ++bogoutil -d wordlist.db | bogoutil -l wordlist.db.new ++mv wordlist.db wordlist.db.prv ++mv wordlist.db.new wordlist.db ++@end smallexample ++ ++The @cite{Bogofilter tuning HOWTO} describes how you can fine-tune ++bogofilter. ++ ++@subheading SpamProbe ++ ++@cindex SpamProbe ++@cindex spam filters, SpamProbe ++ ++SpamProbe is a Bayesian spam filtering program. Get it from your local ++distribution or from the @uref{http://spamprobe.sourceforge.net, ++SpamProbe web site}. ++ ++To use SpamProbe, add the following recipes to @file{~/.procmailrc}: ++ ++@cindex @command{formail} ++@cindex @samp{X-SpamProbe:} header field ++@cindex header field, @samp{X-SpamProbe:} ++ ++@smallexample ++PATH=$PATH:/usr/bin/mh ++MAILDIR=$HOME/`mhparam Path` ++ ++# Fight spam with SpamProbe. ++:0 ++SCORE=| spamprobe receive ++ ++:0 wf ++| formail -I "X-SpamProbe: $SCORE" ++ ++:0: ++*^X-SpamProbe: SPAM ++spam/. ++@end smallexample ++ ++@findex mh-junk-blacklist ++@findex mh-junk-whitelist ++@kindex J b ++@kindex J w ++ ++If SpamProbe classifies a message incorrectly, you can use the MH-E ++commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J w} ++(@code{mh-junk-whitelist}) to update SpamProbe's training. ++ ++@subheading Other Things You Can Do ++ ++There are a couple of things that you can add to @file{~/.procmailrc} ++in order to filter out a lot of spam and viruses. The first is to ++eliminate any message with a Windows executable (which is most likely ++a virus). The second is to eliminate mail in character sets that you ++can't read. ++ ++@cindex @samp{Content-Transfer-Encoding:} header field ++@cindex @samp{Content-Type:} header field ++@cindex @samp{Subject:} header field ++@cindex header field, @samp{Content-Transfer-Encoding:} ++@cindex header field, @samp{Content-Type:} ++@cindex header field, @samp{Subject:} ++ ++@smallexample ++PATH=$PATH:/usr/bin/mh ++MAILDIR=$HOME/`mhparam Path` ++ ++# ++# Filter messages with win32 executables/virii. ++# ++# These attachments are base64 and have a TVqQAAMAAAAEAAAA//8AALg ++# pattern. The string "this program cannot be run in MS-DOS mode" ++# encoded in base64 is 4fug4AtAnNIbg and helps to avoid false ++# positives (Roland Smith via Pete from the bogofilter mailing list). ++# ++:0 B: ++* ^Content-Transfer-Encoding:.*base64 ++* ^TVqQAAMAAAAEAAAA//8AALg ++* 4fug4AtAnNIbg ++spam/exe/. ++ ++# ++# Filter mail in unreadable character sets (from the Bogofilter FAQ). ++# ++UNREADABLE='[^?"]*big5|iso-2022-jp|ISO-2022-KR|euc-kr|gb2312|ks_c_5601-1987' ++ ++:0: ++* 1^0 $ ^Subject:.*=\?($UNREADABLE) ++* 1^0 $ ^Content-Type:.*charset="?($UNREADABLE) ++spam/unreadable/. ++ ++:0: ++* ^Content-Type:.*multipart ++* B ?? $ ^Content-Type:.*^?.*charset="?($UNREADABLE) ++spam/unreadable/. ++@end smallexample ++ ++@node Miscellaneous, Scan Line Formats, Junk, Top ++@chapter Miscellaneous Commands, Variables, and Buffers ++ ++This chapter covers the following command and the various MH-E ++buffers, ++ ++@ftable @code ++@item mh-version ++Display version information about MH-E and the MH mail handling ++system. ++@end ftable ++ ++@cindex buffers, @samp{*MH-E Info*} ++@cindex MH-E version ++@cindex @samp{*MH-E Info*} ++@cindex version ++@kindex M-x mh-version ++ ++One command worth noting is @kbd{M-x mh-version}. You can compare the ++version this command prints to the latest release (@pxref{Getting ++MH-E}). The output of @kbd{M-x mh-version}, found in a buffer named ++@samp{*MH-E Info*}, should usually be included with any bug report you ++submit (@pxref{Bug Reports}). ++ ++@subheading MH-E Buffers ++ ++Besides the MH-Folder, MH-Show, and MH-Letter buffers, MH-E creates ++several other buffers. They are: ++ ++@table @samp ++@cindex @samp{*MH-E Folders*} ++@cindex buffers, @samp{*MH-E Folders*} ++@findex mh-list-folders ++@item *MH-E Folders* ++@kindex F l ++This buffer contains the output of @kbd{F l} (@code{mh-list-folders}). ++@xref{Folders}. ++@c ------------------------- ++@cindex @samp{*MH-E Help*} ++@cindex buffers, @samp{*MH-E Help*} ++@findex mh-help ++@item *MH-E Help* ++@kindex ? ++@kindex C-c ? ++This buffer contains the output of @kbd{?} (@code{mh-help}) and ++@kbd{C-c ?} in MH-Letter mode. @xref{Using This Manual}. ++@c ------------------------- ++@cindex @samp{*MH-E Info*} ++@cindex buffers, @samp{*MH-E Info*} ++@item *MH-E Info* ++This buffer contains the output of @kbd{M-x mh-version @key{RET}}. ++@c ------------------------- ++@cindex @samp{*MH-E Log*} ++@cindex buffers, @samp{*MH-E Log*} ++@item *MH-E Log* ++This buffer contains the last 100 lines of the output of the various ++MH commands. ++@c ------------------------- ++@cindex @samp{*MH-E Mail Delivery*} ++@cindex buffers, @samp{*MH-E Mail Delivery*} ++@item *MH-E Mail Delivery* ++This buffer contains the transcript of a mail delivery. @xref{Sending ++Message}. ++@c ------------------------- ++@cindex @samp{*MH-E Recipients*} ++@cindex buffers, @samp{*MH-E Recipients*} ++@findex mh-check-whom ++@item *MH-E Recipients* ++@kindex C-c C-w ++This buffer contains the output of @kbd{C-c C-w} ++(@code{mh-check-whom}) and is killed when draft is sent. ++@xref{Checking Recipients}. ++@c ------------------------- ++@cindex @samp{*MH-E Sequences*} ++@cindex buffers, @samp{*MH-E Sequences*} ++@item *MH-E Sequences* ++This buffer contains the output of @kbd{S l} ++(@code{mh-list-sequences}). @xref{Sequences}. ++@c ------------------------- ++@cindex @samp{*mh-temp*} ++@cindex buffers, @samp{*mh-temp*} ++@item *mh-temp* ++This is a scratch, ephemeral, buffer used by MH-E functions. Note that ++it is hidden because the first character in the name is a space. ++You'll generally not have any need for this buffer. ++@end table ++ ++@node Scan Line Formats, Procmail, Miscellaneous, Top ++@appendix Scan Line Formats ++ ++@cindex scan line formats ++ ++This appendix discusses how MH-E creates, parses, and manipulates scan ++lines. If you have your own MH scan or inc format files, you ++@strong{can} teach MH-E how to handle them, but it isn't easy as ++you'll see. ++ ++@cindex @samp{mh-scan-line-formats} customization group ++@cindex customization group, @samp{mh-scan-line-formats} ++ ++This table lists the options in the @samp{mh-scan-line-formats} ++customization group. ++ ++@vtable @code ++@item mh-adaptive-cmd-note-flag ++On means that the message number width is determined dynamically ++(default: @samp{on}). ++@c ------------------------- ++@item mh-scan-format-file ++Specifies the format file to pass to the scan program (default: ++@samp{Use MH-E scan Format}). ++@c ------------------------- ++@item mh-scan-prog ++Program used to scan messages (default: @code{"scan"}). ++@end vtable ++ ++@vindex mh-adaptive-cmd-note-flag ++ ++There are a couple of caveats when creating your own scan format file. ++First, MH-E will not work if your scan lines do not include message ++numbers. It will work poorly if you don't dedicate a column for ++showing the current message and notations. It is also best to keep the ++first column empty to make room for the cursor and so that text isn't ++obscured by the current message's overlay arrow when running in a ++terminal. You won't be able to use the option ++@code{mh-adaptive-cmd-note-flag} or the threading features ++(@pxref{Threading}). ++ ++@cindex message numbers ++@findex mh-set-cmd-note ++@vindex mh-adaptive-cmd-note-flag ++@vindex mh-scan-format-file ++ ++If you've created your own format to handle long message numbers, ++you'll be pleased to know you no longer need it since MH-E adapts its ++internal format based upon the largest message number if ++@code{mh-adaptive-cmd-note-flag} is on (the default). If you prefer ++fixed-width message numbers, turn off @code{mh-adaptive-cmd-note-flag} ++and call @code{mh-set-cmd-note} with the width specified by your ++format file (see @code{mh-scan-format-file}). For example, the default ++width is 4, so you would use @samp{(mh-set-cmd-note 4)}. ++ ++@vindex mh-adaptive-cmd-note-flag ++@vindex mh-scan-format-file ++@vindex mh-scan-format-mh ++@vindex mh-scan-format-nmh ++ ++The default setting for @code{mh-scan-format-file} is @samp{Use MH-E ++scan Format}. This means that the format string will be taken from the ++either @code{mh-scan-format-mh} or @code{mh-scan-format-nmh} depending ++on whether MH or nmh (or GNU mailutils MH) is in use. This setting ++also enables you to turn on the option ++@code{mh-adaptive-cmd-note-flag}. You can also set this option to ++@samp{Use Default scan Format} to get the same output as you would get ++if you ran @command{scan} from the shell. If you have a format file ++that you want MH-E to use but not MH, you can set this option to ++@samp{Specify a scan Format File} and enter the name of your format ++file. ++ ++@vindex mh-scan-format-file ++@vindex mh-scan-format-mh ++@vindex mh-scan-format-nmh ++ ++The scan format that MH-E uses when @code{mh-scan-format-file} is set ++to its default of @samp{Use MH-E scan Format} is held in the variables ++@code{mh-scan-format-nmh} and @code{mh-scan-format-mh} depending on ++whether you are using nmh (or GNU mailutils MH) or not. Typically, you ++create your own format files rather than modifying these variables. ++The value of @code{mh-scan-format-nmh} is: ++ ++@smallexample ++(concat ++ "%4(msg)" ++ "%<(cur)+%| %>" ++ "%<@{replied@}-" ++ "%?(nonnull(comp@{to@}))%<(mymbox@{to@})t%>" ++ "%?(nonnull(comp@{cc@}))%<(mymbox@{cc@})c%>" ++ "%?(nonnull(comp@{bcc@}))%<(mymbox@{bcc@})b%>" ++ "%?(nonnull(comp@{newsgroups@}))n%>" ++ "%<(zero) %>" ++ "%02(mon@{date@})/%02(mday@{date@})%<@{date@} %|*%>" ++ "%<(mymbox@{from@})%<@{to@}To:%14(decode(friendly@{to@}))%>%>" ++ "%<(zero)%17(decode(friendly@{from@}))%> " ++ "%(decode@{subject@})%<@{body@}<<%@{body@}%>") ++@end smallexample ++ ++@cindex decoding RFC 2047 ++@cindex RFC 2047, decoding ++@vindex mh-scan-format-mh ++ ++The setting for @code{mh-scan-format-mh} is similar, except that MH ++doesn't have the function @code{decode} (which is used to decode RFC ++2047 encodings). ++ ++@cindex notations, scan line ++@cindex scan line notations ++ ++These strings are passed to the @command{scan} program via the ++@option{-format} argument. The formats are identical to the defaults ++except that additional hints for fontification have been added to the ++existing notations in the fifth column (remember that in Emacs, the ++columns start at 0). The values of the fifth column, in priority ++order, are: @samp{-} if the message has been replied to, @samp{t} if ++an address in the @samp{To:} field matches one of the mailboxes of the ++current user, @samp{c} if the @samp{Cc:} field matches, @samp{b} if ++the @samp{Bcc:} field matches, and @samp{n} if a non-empty ++@samp{Newsgroups:} field is present. ++ ++@cindex @command{scan} ++@cindex MH commands, @command{scan} ++@vindex mh-progs ++@vindex mh-scan-prog ++ ++The name of the program that generates a listing of one line per ++message is held in @code{mh-scan-prog} (default: @code{"scan"}). ++Unless this variable contains an absolute pathname, it is assumed to ++be in the @code{mh-progs} directory (@pxref{Getting Started}). You may ++link another program to @command{scan} (see @samp{mh-profile}(5)) to ++produce a different type of listing@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/faswsprs.html, Find and Specify with scan ++pick Ranges Sequences} in the MH book.}. ++ ++@cindex regular expressions, scan line formats ++@findex mh-set-cmd-note ++@findex setq ++ ++If you change the format of the scan lines you'll need to tell MH-E ++how to parse the new format. As you will see, quite a lot of variables ++are involved to do that. Use @kbd{M-x apropos @key{RET} ++mh-scan.*regexp @key{RET}} to obtain a list of these variables. You ++will also have to call @code{mh-set-cmd-note} if your notations are ++not in column 4 (columns in Emacs start with 0). Note that unlike most ++of the user options described in this manual, these are variables and ++must be set with @code{setq} instead of in a customization buffer. For ++help with regular expressions, see ++@ifnothtml ++@ref{Regexps, , Syntax of Regular Expressions, emacs, The ++GNU Emacs Manual}. ++@end ifnothtml ++@ifhtml ++section ++@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, ++Syntax of Regular Expressions} in @cite{The GNU Emacs Manual}. ++@end ifhtml ++ ++The first variable has to do with pruning out garbage. ++ ++@vtable @code ++@cindex @command{inc} ++@cindex MH commands, @command{inc} ++@cindex @command{scan} ++@cindex MH commands, @command{scan} ++@item mh-scan-valid-regexp ++This regular expression describes a valid scan line. This is used to ++eliminate error messages that are occasionally produced by ++@command{inc}@footnote{See the section ++@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next ++prev} in the MH book.} or @command{scan} (default: @code{"^ *[0-9]"}). ++@end vtable ++ ++Next, many variables control how the scan lines are parsed. ++ ++@vtable @code ++@vindex mh-folder-body ++@vindex mh-folder-font-lock-keywords ++@item mh-scan-body-regexp ++This regular expression matches the message body fragment. Note that ++the default setting of @code{mh-folder-font-lock-keywords} expects ++this expression to contain at least one parenthesized expression which ++matches the body text as in the default of ++@code{"\\(<<\\([^\n]+\\)?\\)"}. If this regular expression is not ++correct, the body fragment will not be highlighted with the face ++@code{mh-folder-body}. ++@c ------------------------- ++@vindex mh-folder-cur-msg-number ++@vindex mh-folder-font-lock-keywords ++@vindex mh-note-cur ++@item mh-scan-cur-msg-number-regexp ++This regular expression matches the current message. It must match ++from the beginning of the line. Note that the default setting of ++@code{mh-folder-font-lock-keywords} expects this expression to contain ++at least one parenthesized expression which matches the message number ++as in the default of @w{@code{"^\\( *[0-9]+\\+\\).*"}}. This ++expression includes the leading space and current message marker ++@samp{+} within the parenthesis since it looks better to highlight ++these items as well. The highlighting is done with the face ++@code{mh-folder-cur-msg-number}. This regular expression should be ++correct as it is needed by non-fontification functions. See also ++@code{mh-note-cur}. ++@c ------------------------- ++@vindex mh-folder-date ++@vindex mh-folder-font-lock-keywords ++@vindex mh-scan-sent-to-me-sender-regexp ++@item mh-scan-date-regexp ++This regular expression matches a valid date. It must @strong{not} be ++anchored to the beginning or the end of the line. Note that the ++default setting of @code{mh-folder-font-lock-keywords} expects this ++expression to contain only one parenthesized expression which matches ++the date field as in the default of ++@code{"\\([0-9][0-9]/[0-9][0-9]\\)"}. If this regular expression is ++not correct, the date will not be highlighted with the face ++@code{mh-folder-date}. ++@c ------------------------- ++@vindex mh-folder-deleted ++@vindex mh-folder-font-lock-keywords ++@vindex mh-note-deleted ++@item mh-scan-deleted-msg-regexp ++This regular expression matches deleted messages. It must match from ++the beginning of the line. Note that the default setting of ++@code{mh-folder-font-lock-keywords} expects this expression to contain ++at least one parenthesized expression which matches the message number ++as in the default of @code{"^\\( *[0-9]+\\)D"}. This expression ++includes the leading space within the parenthesis since it looks ++better to highlight it as well. The highlighting is done with the face ++@code{mh-folder-deleted}. This regular expression should be correct as ++it is needed by non-fontification functions. See also ++@code{mh-note-deleted}. ++@c ------------------------- ++@vindex mh-folder-font-lock-keywords ++@vindex mh-folder-msg-number ++@item mh-scan-good-msg-regexp ++This regular expression matches ``good'' messages. It must match from ++the beginning of the line. Note that the default setting of ++@code{mh-folder-font-lock-keywords} expects this expression to contain ++at least one parenthesized expression which matches the message number ++as in the default of @w{@code{"^\\( *[0-9]+\\)[^D^0-9]"}}. This ++expression includes the leading space within the parenthesis since it ++looks better to highlight it as well. The highlighting is done with ++the face @code{mh-folder-msg-number}. This regular expression should ++be correct as it is needed by non-fontification functions. ++@c ------------------------- ++@vindex mh-scan-format-file ++@item mh-scan-msg-format-regexp ++This regular expression finds the message number width in a scan ++format. Note that the message number must be placed in a parenthesized ++expression as in the default of @code{"%\\([0-9]*\\)(msg)"}. This ++variable is only consulted if @code{mh-scan-format-file} is set to ++@samp{Use MH-E scan Format}. ++@c ------------------------- ++@vindex mh-scan-format-file ++@item mh-scan-msg-format-string ++This is a format string for the width of the message number in a scan ++format. Use @samp{0%d} for zero-filled message numbers. This variable ++is only consulted if @code{mh-scan-format-file} is set to @samp{Use ++MH-E scan Format} (default: @code{"%d"}). ++@c ------------------------- ++@item mh-scan-msg-number-regexp ++This regular expression extracts the message number. It must match ++from the beginning of the line. Note that the message number must be ++placed in a parenthesized expression as in the default of @w{@code{"^ ++*\\([0-9]+\\)"}}. ++@c ------------------------- ++@item mh-scan-msg-overflow-regexp ++This regular expression matches overflowed message numbers (default: ++@code{"^[?0-9][0-9]"}). ++@c ------------------------- ++@item mh-scan-msg-search-regexp ++This regular expression matches a particular message. It is a format ++string; use @samp{%d} to represent the location of the message number ++within the expression as in the default of @code{"^[^0-9]*%d[^0-9]"}. ++@c ------------------------- ++@vindex mh-folder-address ++@vindex mh-folder-font-lock-keywords ++@vindex mh-folder-to ++@item mh-scan-rcpt-regexp ++This regular expression specifies the recipient in messages you sent. ++Note that the default setting of @code{mh-folder-font-lock-keywords} ++expects this expression to contain two parenthesized expressions. The ++first is expected to match the @samp{To:} that the default scan format ++file generates. The second is expected to match the recipient's name ++as in the default of @code{"\\(To:\\)\\(..............\\)"}. If this ++regular expression is not correct, the @samp{To:} string will not be ++highlighted with the face @code{mh-folder-to} and the recipient will not be ++highlighted with the face @code{mh-folder-address}. ++@c ------------------------- ++@vindex mh-folder-font-lock-keywords ++@vindex mh-folder-refiled ++@vindex mh-note-refiled ++@item mh-scan-refiled-msg-regexp ++This regular expression matches refiled messages. It must match from ++the beginning of the line. Note that the default setting of ++@code{mh-folder-font-lock-keywords} expects this expression to contain ++at least one parenthesized expression which matches the message number ++as in the default of @w{@code{"^\\( *[0-9]+\\)\\^"}}. This expression ++includes the leading space within the parenthesis since it looks ++better to highlight it as well. The highlighting is done with the face ++@code{mh-folder-refiled}. This regular expression should be correct as ++it is needed by non-fontification functions. See also ++@code{mh-note-refiled}. ++@c ------------------------- ++@vindex mh-folder-font-lock-keywords ++@vindex mh-folder-sent-to-me-sender ++@vindex mh-mh-folder-sent-to-me-hint ++@vindex mh-scan-format-nmh ++@item mh-scan-sent-to-me-sender-regexp ++This regular expression matches messages sent to us. Note that the ++default setting of @code{mh-folder-font-lock-keywords} expects this ++expression to contain at least two parenthesized expressions. The ++first should match the fontification hint (see ++@code{mh-scan-format-nmh}) and the second should match the user name ++as in the default of ++@w{@code{"^ *[0-9]+.\\([bct]\\).....[ ]*\\(..................\\)"}}. ++If this regular expression is not correct, the notation hints will not ++be highlighted with the face @code{mh-mh-folder-sent-to-me-hint} and ++the sender will not be highlighted with the face ++@code{mh-folder-sent-to-me-sender}. ++@c ------------------------- ++@vindex mh-folder-followup ++@vindex mh-folder-font-lock-keywords ++@vindex mh-folder-subject ++@item mh-scan-subject-regexp ++This regular expression matches the subject. It must match from the ++beginning of the line. Note that the default setting of ++@samp{mh-folder-font-lock-keywords} expects this expression to contain ++at least three parenthesized expressions. The first is expected to ++match the @samp{Re:} string, if any, and is highlighted with the face ++@code{mh-folder-followup}. The second matches an optional bracketed ++number after @samp{Re:}, such as in @samp{Re[2]:} (and is thus a ++sub-expression of the first expression). The third is expected to ++match the subject line itself which is highlighted with the face ++@code{mh-folder-subject}. For example, the default is ++@w{@code{"^ *[0-9]+........[ ]*...................}}@* ++@w{@code{\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\([^<\n]*\\)"}}. ++This regular expression should be correct as it is needed by ++non-fontification functions. Note that this example is broken up on ++two lines for readability, but is actually a single string. ++@end vtable ++ ++Finally, there are a slew of variables that control how MH-E annotates ++the scan lines. ++ ++@vtable @code ++@findex mh-set-cmd-note ++@vindex mh-adaptive-cmd-note-flag ++@item mh-cmd-note ++Column for notations (default: 4). This variable should be set with ++the function @code{mh-set-cmd-note}. This variable may be updated ++dynamically if @code{mh-adaptive-cmd-note-flag} is on. The following ++variables contain the notational characters. Note that columns in ++Emacs start with 0. ++@c ------------------------- ++@item mh-note-copied ++Messages that have been copied are marked by this character (default: ++@code{?C}). ++@c ------------------------- ++@vindex mh-scan-cur-msg-number-regexp ++@item mh-note-cur ++The current message (in MH, not in MH-E) is marked by this character ++(default: @code{?+}). See also @code{mh-scan-cur-msg-number-regexp}. ++@c ------------------------- ++@vindex mh-scan-deleted-msg-regexp ++@item mh-note-deleted ++Messages that have been deleted are marked by this character (default: ++@code{?D}). See also @code{mh-scan-deleted-msg-regexp}. ++@c ------------------------- ++@item mh-note-dist ++Messages that have been redistributed are marked by this character ++(default: @code{?R}). ++@c ------------------------- ++@item mh-note-forw ++Messages that have been forwarded are marked by this character ++(default: @code{?F}). ++@c ------------------------- ++@item mh-note-printed ++Messages that have been printed are marked by this character (default: ++@code{?P}). ++@c ------------------------- ++@vindex mh-scan-refiled-msg-regexp ++@item mh-note-refiled ++Messages that have been refiled are marked by this character (default: ++@code{?^}). See also @code{mh-scan-refiled-msg-regexp}. ++@c ------------------------- ++@item mh-note-repl ++Messages that have been replied to are marked by this character ++(default: @code{?-}). ++@c ------------------------- ++@item mh-note-seq ++Messages in a user-defined sequence are marked by this character ++(default: @code{?%}). Messages in the @samp{search} sequence are ++marked by this character as well. ++@end vtable ++ ++For example, let's say I have the following in @file{scan.format} ++which displays the sender, the subject, and the message number. This ++format places a @samp{+} after the message number for the current ++message according to MH; it also uses that column for notations. ++ ++@smallexample ++%20(decode(friendly@{from@})) %50(decode@{subject@}) %4(msg)%<(cur)+%| %> ++@end smallexample ++ ++@vindex mh-adaptive-cmd-note-flag ++@vindex mh-scan-format-file ++@vindex mh-scan-format-file, example ++ ++The first thing you have to do is tell MH-E to use this file. ++Customize @code{mh-scan-format-file} and set its value to @samp{Use ++Default scan Format}. If you didn't get already turn off ++@code{mh-adaptive-cmd-note-flag}, you'll need to do that first. ++ ++Next, tell MH-E what a valid scan line looks like so that you can at ++least display the output of scan in your MH-Folder buffer. ++ ++@vindex mh-scan-valid-regexp, example ++ ++@smalllisp ++(setq mh-scan-valid-regexp "[0-9]+[+D^ ]$") ++@end smalllisp ++ ++Now, in order to get rid of the @samp{Cursor not pointing to message} ++message, you need to tell MH-E how to access the message number. You ++should also see why MH-E requires that you include a message number in ++the first place. ++ ++@vindex mh-scan-msg-number-regexp, example ++@vindex mh-scan-msg-search-regexp, example ++ ++@smalllisp ++(setq mh-scan-msg-number-regexp "^.* \\([0-9]+\\)[+D^ ]$") ++(setq mh-scan-msg-search-regexp " %d[+D^ ]$") ++@end smalllisp ++ ++In order to get the next and previous commands working, add this. ++ ++@vindex mh-scan-good-msg-regexp, example ++ ++@smalllisp ++(setq mh-scan-good-msg-regexp "^.* \\([0-9]+\\)[+D^ ]$") ++@end smalllisp ++ ++Note that the current message isn't marked with a @samp{+} when moving ++between the next and previous messages. Here is the code required to ++get this working. ++ ++@vindex set-mh-cmd-note, example ++@vindex mh-scan-cur-msg-number-regexp, example ++ ++@smalllisp ++(set-mh-cmd-note 76) ++(setq mh-scan-cur-msg-number-regexp "^.* \\([0-9]+\\)\\+$") ++@end smalllisp ++ ++Finally, add the following to delete and refile messages. ++ ++@vindex mh-scan-deleted-msg-regexp, example ++@vindex mh-scan-refiled-msg-regexp, example ++ ++@smalllisp ++(setq mh-scan-deleted-msg-regexp "^.* \\([0-9]+\\)D$") ++(setq mh-scan-refiled-msg-regexp "^.* \\([0-9]+\\)\\^$") ++@end smalllisp ++ ++This is just a bare minimum; it's best to adjust all of the regular ++expressions to ensure that MH-E and highlighting perform well. ++ ++@node Procmail, Odds and Ends, Scan Line Formats, Top ++@appendix Reading Mailing Lists Effectively ++ ++@cindex @command{procmail} ++@cindex @command{slocal} ++@cindex Gnus ++@cindex MH commands, @command{slocal} ++@cindex Unix commands, @command{procmail} ++@cindex mailing lists, reading ++ ++This appendix explains how to use @uref{http://www.procmail.org/, ++procmail} to file mail from mailing lists into folders which can then ++be read easily with MH-E@footnote{The MH equivalent, @command{slocal}, ++can be used as well, but procmail is more flexible and more packages ++exist for procmail than for slocal.}. Some mailing lists have such ++high traffic that Gnus must be used and I discuss how to use Gnus ++side-by-side with MH-E. ++ ++@cindex @file{.procmailrc} ++@cindex files, @file{.procmailrc} ++ ++First, I'll describe how to put mail from your mailing lists directly ++into an MH folder using @command{procmail}. First, add the following ++to @file{~/.procmailrc}. While the logging variables aren't strictly ++necessary, they are extremely useful. ++ ++@smallexample ++[1] # Update PATH so procmail can find myrcvstore, rcvstore and mhparam. ++[2] PATH=$PATH:/usr/lib/mh:/usr/bin/mh:$HOME/bin ++[3] ++[4] # Point LOGFILE at the actual log file. ++[5] LOGFILE=$HOME/.procmail.log ++[6] ++[7] # This setting provides just the right amount of information. ++[8] LOGABSTRACT=all ++[9] ++[10] # Uncomment the following line to see how your patterns match. ++[11] #VERBOSE=yes ++[12] ++[13] # Place mail sent to any MH-E mailing list in +mh-e. ++[14] :0 w: mh-e$LOCKEXT ++[15] * ^TO.*mh-e-.*@.*sourceforge.net ++[16] | myrcvstore -create +mh-e ++@end smallexample ++ ++@cindex @command{rcvstore} ++@cindex MH commands, @command{rcvstore} ++ ++Line 14 creates a lock file in your mail directory based upon the name ++of the folder. This is done because @command{rcvstore} does not ++perform locking. While this lock file will prevent @command{procmail} ++from writing to a folder concurrently, there is a slight chance that ++you might lose a message if you're performing operations on a folder ++at the same time @command{rcvstore} is placing a message there. You ++have been warned. Now that that disclaimer is out of the way, note ++that I've been using this set-up for over a decade and haven't lost ++anything to my knowledge@footnote{See ++@uref{https://savannah.nongnu.org/bugs/?func=detailbug&bug_id=4361&group_id=2166, ++Savannah issue #4361} to see if @command{rcvstore} locking is still an ++issue.}. ++ ++@cindex @samp{Unseen-Sequence:} MH profile component ++@cindex MH profile component, @samp{Unseen-Sequence:} ++ ++Line 16 uses the following script, @code{myrcvstore}, to massage the ++message as described in the comment and file the message in the given ++folder@footnote{The @samp{-create} argument wasn't always the default ++to @command{rcvstore}.}. ++ ++@smallexample ++#! /bin/sh ++ ++# Accepts a message on standard input and passes it through rcvstore ++# after first passing it through any filters. All arguments are passed ++# on to rcvstore. ++ ++# Force the "From user date" to become part of header. One reason this ++# is done is because the presence of the From field confuses dist so ++# that dist adds a new header, rather than using the existing header. ++# Note that this should not be done for any message that goes into a ++# Gnus incoming file (Gnus will thrown an error) nor should it be ++# applied to any message that goes to the system mailbox because the ++# entire mailbox will be incorporated as a single message. ++formail -c -z -R 'From ' X-Envelope-From: | ++rcvstore $@@ ++@end smallexample ++ ++If your version of @command{rcvstore} doesn't add messages to the ++@samp{unseen} sequence by default, add the following line to your MH ++profile: ++ ++@smallexample ++Unseen-Sequence: unseen ++@end smallexample ++ ++Now view your new messages with the speedbar (@pxref{Speedbar}) or with ++@kbd{F n} (@code{mh-index-new-messages}). @xref{Folders}. ++ ++If you're on a mailing list that is so voluminous that it is ++impossible to read every message, it usually better to read the ++mailing list like a newsgroup in a news reader. Emacs has a built-in ++newsreader called Gnus. The remainder of this appendix talks about how ++to use Gnus with an MH message store. The version of Gnus that was ++used to prepare this manual was 5.10. Versions 5.8 through 5.10 should ++work but versions prior to 5.8 use different options. ++ ++This table contains a list of Gnus options that you will have to ++modify. Note that for them to become accessible, you'll have to load ++@file{nnml.el} first. This can be done with @kbd{M-x load-library ++@key{RET} nnml @key{RET}}. ++ ++@vtable @code ++@item gnus-secondary-select-methods ++Select the @samp{nnml} value. This select method uses directories for ++folders and individual files for messages, just like MH. You do not ++have to set an address. ++@c ------------------------- ++@item mail-sources ++Select the @samp{Several files in a directory} value, check the ++@samp{Path} box and enter @file{~/Mail} to tell Gnus where to find ++your mail. ++@c ------------------------- ++@vindex mail-user-agent ++@item message-mail-user-agent ++In order to send mail within Gnus using MH-E, set this option to ++@samp{mail-user-agent} and set the @code{mail-user-agent} option to ++@samp{Emacs interface to MH}. ++@c ------------------------- ++@item nnmail-keep-last-article ++Since Gnus keeps track of which messages you have read, it would be ++bad if Gnus expired the last message, for example, message 100, and ++@command{rcvstore} gave the next new message number 1. Gnus would then ++ignore it since it thinks that you've read messages 1-100. Turning on ++this option ensures that the last message is never removed thereby ++eliminating this problem. ++@end vtable ++ ++Next add the following to @file{~/.procmailrc}. If you don't subscribe ++to the GnuCash mailing list, substitute one to which you are ++subscribed. ++ ++@smallexample ++PATH=$PATH:/usr/bin/mh ++MAILDIR=$HOME/`mhparam Path` ++# Place mail sent to the GnuCash mailing list in gnucash.spool, where ++# Gnus will pick it up. ++:0: ++* ^TO.*gnucash.*@.*gnucash.org ++gnucash.spool ++@end smallexample ++ ++Wait for some messages to appear in @file{gnucash.spool} and run Gnus ++with @kbd{M-x gnus @key{RET}}. To view the folder created in the ++example above, you would tell Gnus about it the first time only with ++@kbd{G m gnucash @key{RET} nnml @key{RET}}. In MH-E, this folder is ++known as @samp{+gnucash}. ++ ++@node Odds and Ends, History, Procmail, Top ++@appendix Odds and Ends ++ ++This appendix covers a few topics that don't fit elsewhere. Here I ++tell you how to report bugs and how to get on the MH-E mailing lists. ++I also point out some additional sources of information. ++ ++@menu ++* Bug Reports:: ++* Mailing Lists:: ++* MH FAQ and Support:: ++* Getting MH-E:: ++@end menu ++ ++@node Bug Reports, Mailing Lists, Odds and Ends, Odds and Ends ++@appendixsec Bug Reports ++ ++@cindex bugs ++@cindex SourceForge ++@kindex M-x mh-version ++ ++Bug reports should be filed at ++@uref{https://sourceforge.net/tracker/?group_id=13357&atid=113357, ++SourceForge}. You need to be a SourceForge user to submit bug reports, ++but this is easy enough to do that it shouldn't be a restriction for ++you. Please include the output of @kbd{M-x mh-version} ++(@pxref{Miscellaneous}) in any bug report you send unless you're 110% ++positive we won't ask for it. ++ ++@node Mailing Lists, MH FAQ and Support, Bug Reports, Odds and Ends ++@appendixsec MH-E Mailing Lists ++ ++@cindex SourceForge ++@cindex mailing lists ++ ++There are several mailing lists for MH-E. They are @i{mh-e-users at ++lists.sourceforge.net}, @i{mh-e-announce at lists.sourceforge.net}, ++and @i{mh-e-devel at lists.sourceforge.net}. You can subscribe or view ++the archives at @uref{https://sourceforge.net/mail/?group_id=13357, ++SourceForge}. Do not report bugs on these lists; please submit them ++via SourceForge (@pxref{Bug Reports}). ++ ++@node MH FAQ and Support, Getting MH-E, Mailing Lists, Odds and Ends ++@appendixsec MH FAQ and Support ++ ++@cindex FAQ ++@cindex MH FAQ ++ ++The article @uref{http://www.newt.com/faq/mh.html, @cite{MH Frequently ++Asked Questions (FAQ) with Answers}} appears monthly in the newsgroup ++@samp{comp.mail.mh}. While very little is there that deals with MH-E ++specifically, there is an incredible wealth of material about MH ++itself which you will find useful. ++ ++@cindex support ++ ++You can find FAQs on MH-E at the ++@uref{https://sourceforge.net/tracker/?group_id=13357&atid=213357, ++Support Requests} page on SourceForge. If you don't find the answer to ++your question, file a support request and your question will become a ++new FAQ! ++ ++@node Getting MH-E, , MH FAQ and Support, Odds and Ends ++@appendixsec Getting MH-E ++ ++@cindex MH-E, obtaining ++@cindex getting MH-E ++@cindex obtaining MH-E ++ ++Because MH-E is undergoing a phase of sustained growth, the version of ++MH-E in your Emacs is likely to be out of date although it is most ++likely to be more up to date than the copy that comes with the MH ++distribution in @file{miscellany/mh-e}. ++ ++@cindex change log ++@cindex release notes ++ ++New MH-E releases are always available for downloading at ++@uref{https://sourceforge.net/project/showfiles.php?group_id=13357, ++SourceForge} before they appear in an Emacs release. You can read the ++release notes on that page to determine if the given release of MH-E ++is already installed in your version of Emacs. You can also read the ++change log to see if you are interested in what the given release of ++MH-E has to offer (although we have no doubt that you will be ++extremely interested in all new releases). ++ ++@cindex Debian ++ ++If you use Debian, you can install the Debian ++@uref{http://packages.debian.org/unstable/mail/mh-e, mh-e package} ++instead. ++ ++@cindex files, @samp{MH-E-NEWS} ++@cindex files, @samp{README} ++@cindex news ++@cindex @samp{MH-E-NEWS} ++@cindex @samp{README} ++@kindex M-x mh-version ++ ++After you download and extract the MH-E tarball, read the ++@file{README} file and @file{MH-E-NEWS}. These correspond to the ++release notes and change log mentioned above. The file @file{README} ++contains instructions on installing MH-E. If you're already running ++Emacs, please quit that session and start again to load in the new ++MH-E. Check that you're running the new version with the command ++@kbd{M-x mh-version}. ++ ++@cindex contributed software ++@cindex manual ++@cindex documentation ++ ++In addition to the mh-e package, the ++@uref{https://sourceforge.net/project/showfiles.php?group_id=13357, ++SourceForge} site also contains doc and contrib packages. The former ++is the latest release of this manual, and the latter contains a few ++contributed packages you might find useful. ++ ++@node History, GFDL, Odds and Ends, Top ++@appendix History of MH-E ++ ++@cindex Bill Wohler ++@cindex Brian Reid ++@cindex Gildea, Stephen ++@cindex Jim Larus ++@cindex Larus, Jim ++@cindex MH-E, versions ++@cindex Reid, Brian ++@cindex SourceForge ++@cindex Stephen Gildea ++@cindex Wohler, Bill ++@cindex history of MH-E ++@cindex versions of MH-E ++ ++MH-E was originally written by Brian Reid in 1983 and has changed ++hands several times since then. Jim Larus wanted to do something ++similar for GNU Emacs, and ended up completely rewriting it that same ++year. In 1989, Stephen Gildea picked it up and added many ++improvements. Bill Wohler then took over in 2000 and moved its ++development to @uref{http://sourceforge.net/, SourceForge} where it ++lives today. ++ ++@menu ++* From Brian Reid:: ++* From Jim Larus:: ++* From Stephen Gildea:: ++* From Bill Wohler:: ++@end menu ++ ++@node From Brian Reid, From Jim Larus, History, History ++@appendixsec From Brian Reid ++ ++@cindex Brian Reid ++@cindex Reid, Brian ++ ++One day in 1983 I got the flu and had to stay home from work for three ++days with nothing to do. I used that time to write MHE@. The ++fundamental idea behind MHE was that it was a ``puppeteer'' driving ++the MH programs underneath it. MH had a model that the editor was ++supposed to run as a sub-process of the mailer, which seemed to me at ++the time to be the tail wagging the dog. So I turned it around and ++made the editor drive the MH programs. I made sure that the UCI people ++(who were maintaining MH at the time) took in my changes and made them ++stick. ++ ++Today, I still use my own version of MHE because I don't at all like ++the way that GNU MH-E works and I've never gotten to be good enough at ++hacking Emacs Lisp to make GNU MH-E do what I want. The Gosling-emacs ++version of MHE and the GNU Emacs version of MH-E have almost nothing ++in common except similar names. They work differently, have different ++conceptual models, and have different key bindings@footnote{After ++reading this article, I questioned Brian about his version of MHE, and ++received some great ideas for improving MH-E such as a dired-like ++method of selecting folders; and removing the prompting when sending ++mail, filling in the blanks in the draft buffer instead. I passed them ++on to Stephen Gildea, the current maintainer, and he was excited about ++the ideas as well. Perhaps one day, MH-E will again resemble MHE ++(draft form editing was introduced in version 7.4).}. ++ ++Brian Reid, June 1994 ++ ++@node From Jim Larus, From Stephen Gildea, From Brian Reid, History ++@appendixsec From Jim Larus ++ ++@cindex Jim Larus ++@cindex Larus, Jim ++ ++Brian Reid, while at CMU or shortly after going to Stanford wrote a ++mail reading program called MHE for Gosling Emacs. It had much the ++same structure as MH-E (i.e., invoked MH programs), though it was ++simpler and the commands were slightly different. Unfortunately, I no ++longer have a copy so the differences are lost in the mists of time. ++ ++In '82-83, I was working at BBN and wrote a lot of mlisp code in ++Gosling Emacs to make it look more like Tennex Emacs. One of the ++packages that I picked up and improved was Reid's mail system. In '83, ++I went back to Berkeley. About that time, Stallman's first version of ++GNU Emacs came out and people started to move to it from Gosling Emacs ++(as I recall, the transition took a year or two). I decided to port ++Reid's MHE and used the mlisp to Emacs Lisp translator that came with ++GNU Emacs. It did a lousy job and the resulting code didn't work, so I ++bit the bullet and rewrote the code by hand (it was a lot smaller and ++simpler then, so it took only a day or two). ++ ++Soon after that, MH-E became part of the standard Emacs distribution ++and suggestions kept dribbling in for improvements. MH-E soon reached ++sufficient functionality to keep me happy, but I kept on improving it ++because I was a graduate student with plenty of time on my hands and ++it was more fun than my dissertation. In retrospect, the one thing ++that I regret is not writing any documentation, which seriously ++limited the use and appeal of the package. ++ ++@cindex @command{xmh}, in MH-E history ++ ++In '89, I came to Wisconsin as a professor and decided not to work on ++MH-E. It was stable, except for minor bugs, and had enough ++functionality, so I let it be for a few years. Stephen Gildea of BBN ++began to pester me about the bugs, but I ignored them. In 1990, he ++went off to the X Consortium, said good bye, and said that he would ++now be using @command{xmh}. A few months later, he came back and said ++that he couldn't stand @command{xmh} and could I put a few more bug fixes ++into MH-E. At that point, I had no interest in fixing MH-E, so I gave ++the responsibility of maintenance to him and he has done a fine job ++since then. ++ ++Jim Larus, June 1994 ++ ++@node From Stephen Gildea, From Bill Wohler, From Jim Larus, History ++@appendixsec From Stephen Gildea ++ ++@cindex Gildea, Stephen ++@cindex Stephen Gildea ++ ++In 1987 I went to work for Bolt Beranek and Newman, as Jim had before ++me. In my previous job, I had been using RMAIL, but as my folders tend ++to run large, I was frustrated with the speed of RMAIL@. However, I ++stuck with it because I wanted the GNU Emacs interface. I am very ++familiar and comfortable with the Emacs interface (with just a few ++modifications of my own) and dislike having to use applications with ++embedded editors; they never live up to Emacs. ++ ++MH is the mail reader of choice at BBN, so I converted to it. Since I ++didn't want to give up using an Emacs interface, I started using MH-E. ++As is my wont, I started hacking on it almost immediately. I first ++used version 3.4m. One of the first features I added was to treat the ++folder buffer as a file-visiting buffer: you could lock it, save it, ++and be warned of unsaved changes when killing it. I also worked to ++bring its functionality a little closer to RMAIL@. Jim Larus was very ++cooperative about merging in my changes, and my efforts first appeared ++in version 3.6, distributed with Emacs 18.52 in 1988. Next I decided ++MH-E was too slow and optimized it a lot. Version, 3.7, distributed ++with Emacs 18.56 in 1990, was noticeably faster. ++ ++When I moved to the X Consortium I became the first person there to ++not use xmh. (There is now one other engineer there using MH-E.) About ++this point I took over maintenance of MH-E from Jim and was finally ++able to add some features Jim hadn't accepted, such as the backward ++searching undo. My first release was 3.8 (Emacs 18.58) in 1992. ++ ++Now, in 1994, we see a flurry of releases, with both 4.0 and 5.0. ++Version 4.0 added many new features, including background folder ++collection and support for composing @sc{mime} messages. (Reading ++@sc{mime} messages remains to be done, alas.) While writing this book, ++Bill Wohler gave MH-E its closest examination ever, uncovering bugs ++and inconsistencies that required a new major version to fix, and so ++version 5 was released. ++ ++Stephen Gildea, June 1994 ++ ++@node From Bill Wohler, , From Stephen Gildea, History ++@appendixsec From Bill Wohler ++ ++@cindex Wohler, Bill ++@cindex Bill Wohler ++ ++The preface originally included the following text which I use to ++begin my story: ++ ++@quotation ++But it's important to note a brief history of MH-E. ++ ++@w{Version 3} was prevalent through the @w{Emacs 18} and early ++@w{Emacs 19} years. Then @w{Version 4} came out (@w{Emacs 19.23}), ++which introduced several new and changed commands. Next, @w{Version ++5.0} was released, which fixed some bugs and incompatibilities, and ++was incorporated into @w{Emacs 19.29}. ++@end quotation ++ ++After a long break, Stephen handed the reins over to me in 2000. I ++moved the project to a new site called SourceForge and organized a ++great team of developers. Our first release in late 2001 was version ++6. It appeared around the time of Emacs 21.2 and had menus and tool ++bar buttons. ++ ++Then, indexed searches, improved MIME handling, a speedbar, multiple ++identities, alias completion, an index view of unseen messages, spam ++software support, Face and X-Image-URL header field support, Fcc ++completion, arbitrary range handling, and draft form editing were ++introduced in the version 7 series around the time of Emacs 21.4 ++(2004). Still, Emacs itself contained version 5 of MH-E released back ++in 1994. ++ ++Version 8 development was mostly driven by the rewrite of the manual. ++It also brought GNU mailutils MH support, S/MIME support, picon ++support, and an improved interface for hiding header fields. The CVS ++repository was migrated from SourceForge to Savannah (only for those ++files that were already part of Emacs) and the software was completely ++reorganized to push back two decades of entropy. Version 8 appeared in ++Emacs 22.1 in 2006. ++ ++Development was then quiet for a couple of years. Emacs 23.1, which is ++due out in 2009, will contain version 8.1. This version includes a few ++new features and several bug fixes. ++ ++Bill Wohler, August 2008 ++ ++@node GFDL, GPL, History, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node GPL, Key Index, GFDL, Top ++@appendix GNU General Public License ++@include gpl.texi ++ ++@node Key Index, Command Index, GPL, Top ++@unnumbered Key (Character) Index ++@printindex ky ++ ++@node Command Index, Option Index, Key Index, Top ++@unnumbered Command Index ++@printindex fn ++ ++@node Option Index, Concept Index, Command Index, Top ++@unnumbered Option (Variable) Index ++@printindex vr ++ ++@node Concept Index, , Option Index, Top ++@unnumbered Concept Index ++@printindex cp ++ ++@bye ++ ++@c Ispell Helpers ++@c ++@c The following are words that ispell should ignore that would not ++@c normally be in a dictionary (global or personal). Be careful not to ++@c include words here that could potentially be typos of other words ++@c (such as url, elisp, or MHE). ++@c ++@c LocalWords: CTRL ESC SPC f's ++@c LocalWords: addr Aliasfile alist ++@c LocalWords: Baushke Bcc BBN Beranek bogofilter bogofilter's ++@c LocalWords: cmd CMU contrib cron ++@c LocalWords: DesBrisay Dcc devel dir dired docstring filll forw ++@c LocalWords: GECOS Gildea Gildea's Ginnean GnuCash goto gnuserv htm ++@c LocalWords: ImageMagick inbox ispell keychain ++@c LocalWords: Larus licensor LocalWords lookup lpr ++@c LocalWords: makeinfo mairix mbox mh mhbuild mhl mhpath mlisp ++@c LocalWords: MML msg multipart ++@c LocalWords: Namazu NIS nenscript nnml num ++@c LocalWords: packmbox passphrase pathname prev procmail prog repl ++@c LocalWords: slocal sortm SpamAssassin spammers SpamProbe SpamProbe's ++@c LocalWords: sublicense supercite speedbar ++@c LocalWords: Tennex texi texinfo Thelen thelenm ++@c LocalWords: UCI undeleted whatnow wohler xmh ypcat ++@c ++@c See http://www.oreilly.com/oreilly/author/stylesheet.html. ++@c See http://en.wikipedia.org/. ++@c ++@c Note the lowercase mh which is needed to avoid hits in the ++@c functions and variables. Occasionally, check for accidental ++@c inclusion of mh in text by uncommenting the following and executing ++@c it with C-x C-e. You want to see "Search failed" ++@c (let ((case-fold-search nil)) ++@c (goto-char (point-min)) ++@c (search-forward-regexp "^mh\\( \\|$\\)")) ++@c ++@c An extremely useful setting for texinfo-mode-hook is: ++@c (add-to-list ++@c 'ispell-skip-region-alist ++@c (list ++@c (concat "\\(@\\(small\\)?\\(example\\|lisp\\)" ++@c "\\(@\\([irw]\\|code\\|var\\){[^}]+}\\|" ++@c "@[@{}.]\\|" ++@c "[^@]\\|" ++@c "@\\(end \\)?group\\|" ++@c "@\\(end \\)?cartouche\\)+" ++@c "@end \\(small\\)?\\(example\\|lisp\\)\\|" ++@c "@\\(code\\|command\\|file\\|kbd\\|sc\\){[^}]+}\\|" ++@c "^@end [a-z]+$\\|" ++@c "^@\\([fv]\\|print\\)index .*$\\|" ++@c "@uref{[^,]+,\\|" ++@c "@[a-z]+\\|" ++@c "/[a-z.]+[/}]\\)"))))) ++@c ++@c Cross References ++@c ++@c See existing cross-references to the Emacs manual and the Emacs ++@c Lisp manual (search for ``GNU Emacs Manual'' and ``GNU ++@c Emacs Lisp Reference Manual'' respectively). ++ ++@c @ftable Sorting ++@c ++@c As per index (sort of): Punctuation, keyboard characters (such as ++@c RET and BS) upper and lowercase mixed (lower comes before ++@c uppercase), control characters go with uppercase C, meta characters ++@c go with uppercase M. ++@c In some cases, the sort isn't strictly ASCII. ++@c For example, SPC (mh-page-msg) reads better before BS ++@c (mh-previous-page) and . (mh-show) is better before , ++@c (mh-header-display). ++ ++@c @vtable Sorting ++@c ++@c Alphabetical, pull hooks into their own table. ++ ++@c Local Variables: ++@c sentence-end-double-space: nil ++@c End: ++ ++@ignore ++ arch-tag: b778477d-1a10-4a99-84de-f877a2ea6bef ++@end ignore +diff --git a/doc/misc/newsticker.texi b/doc/misc/newsticker.texi +new file mode 100644 +index 0000000..10ac006 +--- /dev/null ++++ b/doc/misc/newsticker.texi +@@ -0,0 +1,321 @@ ++\input texinfo @c -*-texinfo-*- ++@comment %**start of header ++@setfilename ../../info/newsticker ++@set VERSION 1.99 ++@set UPDATED June 2008 ++@settitle Newsticker @value{VERSION} ++@syncodeindex vr cp ++@syncodeindex fn cp ++@syncodeindex pg cp ++@comment %**end of header ++ ++@copying ++This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}). ++ ++@noindent ++Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 ++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 Emacs ++@direntry ++* Newsticker: (newsticker). A Newsticker for Emacs. ++@end direntry ++ ++@titlepage ++@title Newsticker -- a Newsticker for Emacs ++@subtitle for version @value{VERSION}, @value{UPDATED} ++@author Ulf Jasper ++@author @email{ulf.jasper@@web.de} ++@author @uref{http://ulf.epplejasper.de/} ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top ++@top Newsticker ++ ++@insertcopying ++ ++@end ifnottex ++ ++@menu ++* Overview:: General description of newsticker. ++* Requirements:: Requirements for using newsticker. ++* Installation:: Installing newsticker on your system. ++* Usage:: Basic newsticker instructions. ++* Configuration:: Customizable newsticker settings. ++* Remarks:: Remarks about newsticker. ++* GNU Free Documentation License:: The license for this documentation. ++* Index:: Variable, function, and concept index. ++@end menu ++ ++@node Overview ++@chapter Overview ++ ++Newsticker provides a newsticker for Emacs. A newsticker is a thing ++that asynchronously retrieves headlines from a list of news sites, ++prepares these headlines for reading, and allows for loading the ++corresponding articles in a web browser. ++ ++ ++Headlines consist of a title and (possibly) a small description. They ++are contained in "RSS" (RDF Site Summary) or "Atom" files. Newsticker ++works with the following RSS formats: ++ ++@itemize ++@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or ++@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}), ++@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}), ++@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec} ++@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}), ++@end itemize ++@itemize ++as well as the following Atom formats: ++@item Atom 0.3 ++@item Atom 1.0 (see ++@uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}). ++@end itemize ++ ++That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed ++aggregator'', or ``Feed reader''. ++ ++Newsticker provides several commands for reading headlines, navigating ++through them, marking them as read/unread, hiding old headlines etc. ++Headlines can be displayed as plain text or as rendered HTML. ++ ++Headlines can be displayed in the echo area, either scrolling like ++messages in a stock-quote ticker, or just changing. ++ ++Newsticker allows for automatic processing of headlines by providing ++hooks and (sample) functions for automatically downloading images and ++enclosed files (as delivered by podcasts, e.g.). ++ ++@ifhtml ++Here are screen shots of the @uref{newsticker-1.7.png, version 1.7 ++(current version)} and some older screen shots: ++@uref{newsticker-1.6.png, version 1.6}, ++@uref{newsticker-1.5.png, version 1.5}, ++@uref{newsticker-1.4.png, version 1.4} ++@uref{newsticker-1.3.png, version 1.3}, ++@uref{newsticker-1.0.png, version 1.0}. ++@end ifhtml ++ ++@node Requirements ++@chapter Requirements ++ ++Newsticker can be used with ++@uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version ++21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}. It ++requires an XML-parser (@file{xml.el}) which is part of GNU Emacs. If ++you are using XEmacs you want to get the @file{net-utils} package ++which contains @file{xml.el} for XEmacs. ++ ++Newsticker retrieves headlines either via Emacs' built-in retrieval ++functions, by an arbitrary external program that retrieves files via ++http and prints them to stdout (like ++@uref{http://www.gnu.org/software/wget/wget.html, wget}, or -- on a ++per feed basis -- via an arbitrary Lisp command. ++ ++ ++@node Installation ++@chapter Installation ++ ++As Newsticker is part of GNU Emacs there is no need to perform any ++installation steps in order to use Newsticker. ++ ++However, if you are using imenu, which allows for navigating with the ++help of a menu, you should add the following to your Emacs startup file ++(@file{~/.emacs}). ++ ++@lisp ++(add-hook 'newsticker-mode-hook 'imenu-add-menubar-index) ++@end lisp ++ ++That's it. ++ ++@node Usage ++@chapter Usage ++ ++@findex newsticker-show-news ++The command @code{newsticker-show-news} will display all available ++headlines. It will also start the asynchronous download of headlines. ++ ++You can choose between two different frontends for reading headlines: ++@itemize ++@item Newsticker's @emph{treeview} uses separate windows for the ++feeds (in tree form), a list of headlines for the current feed, and ++the content of the current headline. Feeds can be placed into groups ++which itself can be placed in groups and so on. ++@item Newsticker's @emph{plainview} displays all headlines in a ++single buffer, called @samp{*newsticker*}. The modeline in the ++@samp{*newsticker*} buffer informs whenever new headlines have ++arrived. ++@end itemize ++In both views clicking mouse-button 2 or pressing RET on a headline ++will call @code{browse-url} to load the corresponding news story in ++your favourite web browser. ++ ++@findex newsticker-start-ticker ++@findex newsticker-stop-ticker ++The scrolling, or flashing of headlines in the echo area, can be ++started with the command @code{newsticker-start-ticker}. It can be ++stopped with @code{newsticker-stop-ticker}. ++ ++@findex newsticker-start ++@findex newsticker-stop ++If you just want to start the periodic download of headlines use the ++command @code{newsticker-start}. Calling @code{newsticker-stop} will ++stop the periodic download, but will call ++@code{newsticker-stop-ticker} as well. ++ ++@node Configuration ++@chapter Configuration ++ ++All Newsticker options are customizable, i.e. they can be changed with ++Emacs customization methods: Call the command ++@code{customize-group} and enter @samp{newsticker} for the customization ++group. ++ ++All Newsticker options have reasonable default values, so that in most ++cases it is not necessary to customize settings before starting Newsticker ++for the first time. ++ ++The following list shows the available groups of newsticker options ++and some of the most important options. ++ ++@itemize ++ ++@item ++@code{newsticker-retrieval} contains options that define which news ++feeds are retrieved and how this is done. ++ ++@itemize ++@item ++@vindex newsticker-url-list ++@code{newsticker-url-list} defines the list of headlines which are ++retrieved. ++@item ++@vindex newsticker-retrieval-method ++@code{newsticker-retrieval-method} defines how headlines are ++retrieved. This is either done using Emacs' built-in download ++capabilities or using an external tool. ++@item ++@vindex newsticker-retrieval-interval ++@code{newsticker-retrieval-interval} defines how often headlines ++are retrieved. ++@end itemize ++ ++@item ++@code{newsticker-headline-processing} contains options that define ++how the retrieved headlines are processed. ++ ++@itemize ++@item ++@vindex newsticker-keep-obsolete-items ++@code{newsticker-keep-obsolete-items} decides whether unread ++headlines that have been removed from the feed are kept in the ++Newsticker cache. ++@item ++@vindex newsticker-auto-mark-filter-list ++@code{newsticker-auto-mark-filter-list} provides the possibility to ++automatically mark headlines as immortal or old. ++@end itemize ++ ++@item ++@code{newsticker-hooks} contains options for hooking other Emacs ++commands to newsticker functions. ++@itemize ++@item ++@vindex newsticker-new-item-functions ++@code{newsticker-new-item-functions} allows for automatic ++processing of headlines. See `newsticker-download-images', and ++`newsticker-download-enclosures' for sample functions. ++@item ++@vindex newsticker-plainview-hooks ++The subgroup @code{newsticker-plainview-hooks} contains hook which ++apply to the plainview reader only. ++@end itemize ++ ++@item ++@code{newsticker-miscellaneous} contains other Newsticker options. ++ ++@item ++@code{newsticker-ticker} contains options that define how headlines ++are shown in the echo area, i.e. the ``ticker''. ++ ++@itemize ++@item ++@vindex newsticker-display-interval ++@vindex newsticker-scroll-smoothly ++@code{newsticker-ticker-interval} and ++@code{newsticker-scroll-smoothly} define how headlines are shown in ++the echo area. ++@end itemize ++ ++ ++@item ++@code{newsticker-reader} contains options for adjusting the headline reader. ++ ++@itemize ++@item ++@vindex newsticker-frontend ++@code{newsticker-frontend} determines the actual headline reader. The ++``plainview'' reader uses a single buffer, the ``treeview'' uses ++separate buffers and windows. ++@end itemize ++ ++@itemize ++@item ++@vindex newsticker-plainview ++The subgroup @code{newsticker-plainview} contains options for the ++plainview reader. ++@item ++@vindex newsticker-treeview ++The subgroup @code{newsticker-treeview} contains options for the ++treeview reader. ++@end itemize ++ ++@end itemize ++ ++For the complete list of options please have a look at the ++customization buffers. ++ ++@node Remarks ++@chapter Remarks ++ ++Byte-compiling newsticker.el is recommended. ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index ++@unnumbered Index ++ ++@printindex cp ++ ++@bye ++ ++ ++ ++@ignore ++ arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0 ++@end ignore +diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi +new file mode 100644 +index 0000000..a27835a +--- /dev/null ++++ b/doc/misc/nxml-mode.texi +@@ -0,0 +1,865 @@ ++\input texinfo @c -*- texinfo -*- ++@c %**start of header ++@setfilename ../../info/nxml-mode ++@settitle nXML Mode ++@c %**end of header ++ ++@copying ++This manual documents nxml-mode, an Emacs major mode for editing ++XML with RELAX NG support. ++ ++Copyright @copyright{} 2007, 2008, 2009 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 Emacs 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.'' ++ ++This document is part of a collection distributed under the GNU Free ++Documentation License. If you want to distribute this document ++separately from the collection, you can do so by adding a copy of the ++license to the document, as described in section 6 of the license. ++@end quotation ++@end copying ++ ++@dircategory Emacs ++@direntry ++* nXML Mode: (nxml-mode). XML editing mode with RELAX NG support. ++@end direntry ++ ++@node Top ++@top nXML Mode ++ ++@insertcopying ++ ++This manual is not yet complete. ++ ++@menu ++* Completion:: ++* Inserting end-tags:: ++* Paragraphs:: ++* Outlining:: ++* Locating a schema:: ++* DTDs:: ++* Limitations:: ++@end menu ++ ++@node Completion ++@chapter Completion ++ ++Apart from real-time validation, the most important feature that ++nxml-mode provides for assisting in document creation is "completion". ++Completion assists the user in inserting characters at point, based on ++knowledge of the schema and on the contents of the buffer before ++point. ++ ++The traditional GNU Emacs key combination for completion in a ++buffer is @kbd{M-@key{TAB}}. However, many window systems ++and window managers use this key combination themselves (typically for ++switching between windows) and do not pass it to applications. It's ++hard to find key combinations in GNU Emacs that are both easy to type ++and not taken by something else. @kbd{C-@key{RET}} (i.e. ++pressing the Enter or Return key, while the Ctrl key is held down) is ++available. It won't be available on a traditional terminal (because ++it is indistinguishable from Return), but it will work with a window ++system. Therefore we adopt the following solution by default: use ++@kbd{C-@key{RET}} when there's a window system and ++@kbd{M-@key{TAB}} when there's not. In the following, I ++will assume that a window system is being used and will therefore ++refer to @kbd{C-@key{RET}}. ++ ++Completion works by examining the symbol preceding point. This ++is the symbol to be completed. The symbol to be completed may be the ++empty. Completion considers what symbols starting with the symbol to ++be completed would be valid replacements for the symbol to be ++completed, given the schema and the contents of the buffer before ++point. These symbols are the possible completions. An example may ++make this clearer. Suppose the buffer looks like this (where @point{} ++indicates point): ++ ++@example ++ ++ ++ ++<@point{} ++@end example ++ ++@noindent ++In this case, the symbol to be completed is empty, and the possible ++completions are @samp{base}, @samp{isindex}, ++@samp{link}, @samp{meta}, @samp{script}, ++@samp{style}, @samp{title}. Another example is: ++ ++@example ++ ++<@point{} ++@end example ++ ++@noindent ++@kbd{C-@key{RET}} will yield ++ ++@example ++ ++ ++ ++ ++ ++ ++@end example ++ ++@noindent ++This says to use the schema @samp{xhtml.rnc} for a document with ++namespace @samp{http://www.w3.org/1999/xhtml}, and to use the ++schema @samp{docbook.rnc} for a document whose local name is ++@samp{book}. If the document element had both a namespace URI ++of @samp{http://www.w3.org/1999/xhtml} and a local name of ++@samp{book}, then the matching rule that comes first will be ++used and so the schema @samp{xhtml.rnc} would be used. There is ++no precedence between different types of rule; the first matching rule ++of any type is used. ++ ++As usual with XML-related technologies, resources are identified ++by URIs. The @samp{uri} attribute identifies the schema by ++specifying the URI. The URI may be relative. If so, it is resolved ++relative to the URI of the schema locating file that contains ++attribute. This means that if the value of @samp{uri} attribute ++does not contain a @samp{/}, then it will refer to a filename in ++the same directory as the schema locating file. ++ ++@node Using the document's URI to locate a schema ++@subsection Using the document's URI to locate a schema ++ ++A @samp{uri} rule locates a schema based on the URI of the ++document. The @samp{uri} attribute specifies the URI of the ++schema. The @samp{resource} attribute can be used to specify ++the schema for a particular document. For example, ++ ++@example ++ ++@end example ++ ++@noindent ++specifies that the schema for @samp{spec.xml} is ++@samp{docbook.rnc}. ++ ++The @samp{pattern} attribute can be used instead of the ++@samp{resource} attribute to specify the schema for any document ++whose URI matches a pattern. The pattern has the same syntax as an ++absolute or relative URI except that the path component of the URI can ++use a @samp{*} character to stand for zero or more characters ++within a path segment (i.e. any character other @samp{/}). ++Typically, the URI pattern looks like a relative URI, but, whereas a ++relative URI in the @samp{resource} attribute is resolved into a ++particular absolute URI using the base URI of the schema locating ++file, a relative URI pattern matches if it matches some number of ++complete path segments of the document's URI ending with the last path ++segment of the document's URI. For example, ++ ++@example ++ ++@end example ++ ++@noindent ++specifies that the schema for documents with a URI whose path ends ++with @samp{.xsl} is @samp{xslt.rnc}. ++ ++A @samp{transformURI} rule locates a schema by ++transforming the URI of the document. The @samp{fromPattern} ++attribute specifies a URI pattern with the same meaning as the ++@samp{pattern} attribute of the @samp{uri} element. The ++@samp{toPattern} attribute is a URI pattern that is used to ++generate the URI of the schema. Each @samp{*} in the ++@samp{toPattern} is replaced by the string that matched the ++corresponding @samp{*} in the @samp{fromPattern}. The ++resulting string is appended to the initial part of the document's URI ++that was not explicitly matched by the @samp{fromPattern}. The ++rule matches only if the transformed URI identifies an existing ++resource. For example, the rule ++ ++@example ++ ++@end example ++ ++@noindent ++would transform the URI @samp{file:///home/jjc/docs/spec.xml} ++into the URI @samp{file:///home/jjc/docs/spec.rnc}. Thus, this ++rule specifies that to locate a schema for a document ++@samp{@var{foo}.xml}, Emacs should test whether a file ++@samp{@var{foo}.rnc} exists in the same directory as ++@samp{@var{foo}.xml}, and, if so, should use it as the ++schema. ++ ++@node Using the document element to locate a schema ++@subsection Using the document element to locate a schema ++ ++A @samp{documentElement} rule locates a schema based on ++the local name and prefix of the document element. For example, a rule ++ ++@example ++ ++@end example ++ ++@noindent ++specifies that when the name of the document element is ++@samp{xsl:stylesheet}, then @samp{xslt.rnc} should be used ++as the schema. Either the @samp{prefix} or ++@samp{localName} attribute may be omitted to allow any prefix or ++local name. ++ ++A @samp{namespace} rule locates a schema based on the ++namespace URI of the document element. For example, a rule ++ ++@example ++ ++@end example ++ ++@noindent ++specifies that when the namespace URI of the document is ++@samp{http://www.w3.org/1999/XSL/Transform}, then ++@samp{xslt.rnc} should be used as the schema. ++ ++@node Using type identifiers in schema locating files ++@subsection Using type identifiers in schema locating files ++ ++Type identifiers allow a level of indirection in locating the ++schema for a document. Instead of associating the document directly ++with a schema URI, the document is associated with a type identifier, ++which is in turn associated with a schema URI. nXML mode does not ++constrain the format of type identifiers. They can be simply strings ++without any formal structure or they can be public identifiers or ++URIs. Note that these type identifiers have nothing to do with the ++DOCTYPE declaration. When comparing type identifiers, whitespace is ++normalized in the same way as with the @samp{xsd:token} ++datatype: leading and trailing whitespace is stripped; other sequences ++of whitespace are normalized to a single space character. ++ ++Each of the rules described in previous sections that uses a ++@samp{uri} attribute to specify a schema, can instead use a ++@samp{typeId} attribute to specify a type identifier. The type ++identifier can be associated with a URI using a @samp{typeId} ++element. For example, ++ ++@example ++ ++ ++ ++ ++ ++ ++@end example ++ ++@noindent ++declares three type identifiers @samp{XHTML} (representing the ++default variant of XHTML to be used), @samp{XHTML Strict} and ++@samp{XHTML Transitional}. Such a schema locating file would ++use @samp{xhtml-strict.rnc} for a document whose namespace is ++@samp{http://www.w3.org/1999/xhtml}. But it is considerably ++more flexible than a schema locating file that simply specified ++ ++@example ++ ++@end example ++ ++@noindent ++A user can easily use @kbd{C-c C-s C-t} to select between XHTML ++Strict and XHTML Transitional. Also, a user can easily add a catalog ++ ++@example ++ ++ ++ ++@end example ++ ++@noindent ++that makes the default variant of XHTML be XHTML Transitional. ++ ++@node Using multiple schema locating files ++@subsection Using multiple schema locating files ++ ++The @samp{include} element includes rules from another ++schema locating file. The behavior is exactly as if the rules from ++that file were included in place of the @samp{include} element. ++Relative URIs are resolved into absolute URIs before the inclusion is ++performed. For example, ++ ++@example ++ ++@end example ++ ++@noindent ++includes the rules from @samp{rules.xml}. ++ ++The process of locating a schema takes as input a list of schema ++locating files. The rules in all these files and in the files they ++include are resolved into a single list of rules, which are applied ++strictly in order. Sometimes this order is not what is needed. ++For example, suppose you have two schema locating files, a private ++file ++ ++@example ++ ++ ++ ++@end example ++ ++@noindent ++followed by a public file ++ ++@example ++ ++ ++ ++ ++@end example ++ ++@noindent ++The effect of these two files is that the XHTML @samp{namespace} ++rule takes precedence over the @samp{transformURI} rule, which ++is almost certainly not what is needed. This can be solved by adding ++an @samp{applyFollowingRules} to the private file. ++ ++@example ++ ++ ++ ++ ++@end example ++ ++@node DTDs ++@chapter DTDs ++ ++nxml-mode is designed to support the creation of standalone XML ++documents that do not depend on a DTD. Although it is common practice ++to insert a DOCTYPE declaration referencing an external DTD, this has ++undesirable side-effects. It means that the document is no longer ++self-contained. It also means that different XML parsers may interpret ++the document in different ways, since the XML Recommendation does not ++require XML parsers to read the DTD. With DTDs, it was impractical to ++get validation without using an external DTD or reference to an ++parameter entity. With RELAX NG and other schema languages, you can ++simulataneously get the benefits of validation and standalone XML ++documents. Therefore, I recommend that you do not reference an ++external DOCTYPE in your XML documents. ++ ++One problem is entities for characters. Typically, as well as ++providing validation, DTDs also provide a set of character entities ++for documents to use. Schemas cannot provide this functionality, ++because schema validation happens after XML parsing. The recommended ++solution is to either use the Unicode characters directly, or, if this ++is impractical, use character references. nXML mode supports this by ++providing commands for entering characters and character references ++using the Unicode names, and can display the glyph corresponding to a ++character reference. ++ ++@node Limitations ++@chapter Limitations ++ ++nXML mode has some limitations: ++ ++@itemize @bullet ++@item ++DTD support is limited. Internal parsed general entities declared ++in the internal subset are supported provided they do not contain ++elements. Other usage of DTDs is ignored. ++@item ++The restrictions on RELAX NG schemas in section 7 of the RELAX NG ++specification are not enforced. ++@item ++Unicode support has problems. This stems mostly from the fact that ++the XML (and RELAX NG) character model is based squarely on Unicode, ++whereas the Emacs character model is not. Emacs 22 is slated to have ++full Unicode support, which should improve the situation here. ++@end itemize ++ ++@bye ++ ++@ignore ++ arch-tag: 3b6e8ac2-ae8d-4f38-bd43-ce9f80be04d6 ++@end ignore +diff --git a/doc/misc/org.texi b/doc/misc/org.texi +new file mode 100644 +index 0000000..aad3495 +--- /dev/null ++++ b/doc/misc/org.texi +@@ -0,0 +1,10525 @@ ++\input texinfo ++@c %**start of header ++@setfilename ../../info/org ++@settitle The Org Manual ++ ++@set VERSION 6.21b ++@set DATE February 2009 ++ ++@c Version and Contact Info ++@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} ++@set AUTHOR Carsten Dominik ++@set MAINTAINER Carsten Dominik ++@set MAINTAINEREMAIL @email{carsten at orgmode dot org} ++@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer} ++@c %**end of header ++@finalout ++ ++@c Macro definitions ++ ++@c Subheadings inside a table. ++@macro tsubheading{text} ++@ifinfo ++@subsubheading \text\ ++@end ifinfo ++@ifnotinfo ++@item @b{\text\} ++@end ifnotinfo ++@end macro ++ ++@copying ++This manual is for Org (version @value{VERSION}). ++ ++Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation ++ ++@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.'' ++ ++This document is part of a collection distributed under the GNU Free ++Documentation License. If you want to distribute this document ++separately from the collection, you can do so by adding a copy of the ++license to the document, as described in section 6 of the license. ++@end quotation ++@end copying ++ ++@dircategory Emacs ++@direntry ++* Org Mode: (org). Outline-based notes management and organizer ++@end direntry ++ ++@titlepage ++@title The Org Manual ++ ++@subtitle Release @value{VERSION} ++@author by Carsten Dominik ++ ++@c The following two commands start the copyright page. ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@c Output the table of contents at the beginning. ++@contents ++ ++@ifnottex ++@node Top, Introduction, (dir), (dir) ++@top Org Mode Manual ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* Introduction:: Getting started ++* Document Structure:: A tree works like your brain ++* Tables:: Pure magic for quick formatting ++* Hyperlinks:: Notes in context ++* TODO Items:: Every tree branch can be a TODO item ++* Tags:: Tagging headlines and matching sets of tags ++* Properties and Columns:: Storing information about an entry ++* Dates and Times:: Making items useful for planning ++* Capture:: Creating tasks and attaching files ++* Agenda Views:: Collecting information into views ++* Embedded LaTeX:: LaTeX fragments and formulas ++* Exporting:: Sharing and publishing of notes ++* Publishing:: Create a web site of linked Org files ++* Miscellaneous:: All the rest which did not fit elsewhere ++* Extensions:: Add-ons for Org mode ++* Hacking:: How to hack your way around ++* History and Acknowledgments:: How Org came into being ++* Main Index:: An index of Org's concepts and features ++* Key Index:: Key bindings and where they are described ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ ++Introduction ++ ++* Summary:: Brief summary of what Org does ++* Installation:: How to install a downloaded version of Org ++* Activation:: How to activate Org for certain buffers ++* Feedback:: Bug reports, ideas, patches etc. ++* Conventions:: Type-setting conventions in the manual ++ ++Document Structure ++ ++* Outlines:: Org is based on Outline mode ++* Headlines:: How to typeset Org tree headlines ++* Visibility cycling:: Show and hide, much simplified ++* Motion:: Jumping to other headlines ++* Structure editing:: Changing sequence and level of headlines ++* Archiving:: Move done task trees to a different place ++* Sparse trees:: Matches embedded in context ++* Plain lists:: Additional structure within an entry ++* Drawers:: Tucking stuff away ++* Footnotes:: How footnotes are defined in Org's syntax ++* Orgstruct mode:: Structure editing outside Org ++ ++Archiving ++ ++* ARCHIVE tag:: Marking a tree as inactive ++* Moving subtrees:: Moving a tree to an archive file ++ ++Tables ++ ++* Built-in table editor:: Simple tables ++* Narrow columns:: Stop wasting space in tables ++* Column groups:: Grouping to trigger vertical lines ++* Orgtbl mode:: The table editor as minor mode ++* The spreadsheet:: The table editor has spreadsheet capabilities ++* Org Plot:: Plotting from org tables ++ ++The spreadsheet ++ ++* References:: How to refer to another field or range ++* Formula syntax for Calc:: Using Calc to compute stuff ++* Formula syntax for Lisp:: Writing formulas in Emacs Lisp ++* Field formulas:: Formulas valid for a single field ++* Column formulas:: Formulas valid for an entire column ++* Editing and debugging formulas:: Fixing formulas ++* Updating the table:: Recomputing all dependent fields ++* Advanced features:: Field names, parameters and automatic recalc ++ ++Hyperlinks ++ ++* Link format:: How links in Org are formatted ++* Internal links:: Links to other places in the current file ++* External links:: URL-like links to the world ++* Handling links:: Creating, inserting and following ++* Using links outside Org:: Linking from my C source code? ++* Link abbreviations:: Shortcuts for writing complex links ++* Search options:: Linking to a specific location ++* Custom searches:: When the default search is not enough ++ ++Internal links ++ ++* Radio targets:: Make targets trigger links in plain text ++ ++TODO Items ++ ++* TODO basics:: Marking and displaying TODO entries ++* TODO extensions:: Workflow and assignments ++* Progress logging:: Dates and notes for progress ++* Priorities:: Some things are more important than others ++* Breaking down tasks:: Splitting a task into manageable pieces ++* Checkboxes:: Tick-off lists ++ ++Extended use of TODO keywords ++ ++* Workflow states:: From TODO to DONE in steps ++* TODO types:: I do this, Fred does the rest ++* Multiple sets in one file:: Mixing it all, and still finding your way ++* Fast access to TODO states:: Single letter selection of a state ++* Per-file keywords:: Different files, different requirements ++* Faces for TODO keywords:: Highlighting states ++* TODO dependencies:: When one task needs to wait for others ++ ++Progress logging ++ ++* Closing items:: When was this entry marked DONE? ++* Tracking TODO state changes:: When did the status change? ++ ++Tags ++ ++* Tag inheritance:: Tags use the tree structure of the outline ++* Setting tags:: How to assign tags to a headline ++* Tag searches:: Searching for combinations of tags ++ ++Properties and Columns ++ ++* Property syntax:: How properties are spelled out ++* Special properties:: Access to other Org mode features ++* Property searches:: Matching property values ++* Property inheritance:: Passing values down the tree ++* Column view:: Tabular viewing and editing ++* Property API:: Properties for Lisp programmers ++ ++Column view ++ ++* Defining columns:: The COLUMNS format property ++* Using column view:: How to create and use column view ++* Capturing column view:: A dynamic block for column view ++ ++Defining columns ++ ++* Scope of column definitions:: Where defined, where valid? ++* Column attributes:: Appearance and content of a column ++ ++Dates and Times ++ ++* Timestamps:: Assigning a time to a tree entry ++* Creating timestamps:: Commands which insert timestamps ++* Deadlines and scheduling:: Planning your work ++* Clocking work time:: Tracking how long you spend on a task ++* Effort estimates:: Planning work effort in advance ++* Relative timer:: Notes with a running timer ++ ++Creating timestamps ++ ++* The date/time prompt:: How Org mode helps you entering date and time ++* Custom time format:: Making dates look different ++ ++Deadlines and scheduling ++ ++* Inserting deadline/schedule:: Planning items ++* Repeated tasks:: Items that show up again and again ++ ++Capture ++ ++* Remember:: Capture new tasks/ideas with little interruption ++* Attachments:: Add files to tasks. ++ ++Remember ++ ++* Setting up Remember:: Some code for .emacs to get things going ++* Remember templates:: Define the outline of different note types ++* Storing notes:: Directly get the note to where it belongs ++* Refiling notes:: Moving a note or task to a project ++ ++Agenda Views ++ ++* Agenda files:: Files being searched for agenda information ++* Agenda dispatcher:: Keyboard access to agenda views ++* Built-in agenda views:: What is available out of the box? ++* Presentation and sorting:: How agenda items are prepared for display ++* Agenda commands:: Remote editing of Org trees ++* Custom agenda views:: Defining special searches and views ++* Agenda column view:: Using column view for collected entries ++ ++The built-in agenda views ++ ++* Weekly/daily agenda:: The calendar page with current tasks ++* Global TODO list:: All unfinished action items ++* Matching tags and properties:: Structured information with fine-tuned search ++* Timeline:: Time-sorted view for single file ++* Keyword search:: Finding entries by keyword ++* Stuck projects:: Find projects you need to review ++ ++Presentation and sorting ++ ++* Categories:: Not all tasks are equal ++* Time-of-day specifications:: How the agenda knows the time ++* Sorting of agenda items:: The order of things ++ ++Custom agenda views ++ ++* Storing searches:: Type once, use often ++* Block agenda:: All the stuff you need in a single buffer ++* Setting Options:: Changing the rules ++* Exporting Agenda Views:: Writing agendas to files ++* Using the agenda elsewhere:: Using agenda information in other programs ++ ++Embedded LaTeX ++ ++* Math symbols:: TeX macros for symbols and Greek letters ++* Subscripts and superscripts:: Simple syntax for raising/lowering text ++* LaTeX fragments:: Complex formulas made easy ++* Processing LaTeX fragments:: Previewing LaTeX processing ++* CDLaTeX mode:: Speed up entering of formulas ++ ++Exporting ++ ++* Markup rules:: Which structures are recognized? ++* Selective export:: Using tags to select and exclude trees ++* Export options:: Per-file export settings ++* The export dispatcher:: How to access exporter commands ++* ASCII export:: Exporting to plain ASCII ++* HTML export:: Exporting to HTML ++* LaTeX and PDF export:: Exporting to LaTeX, and processing to PDF ++* XOXO export:: Exporting to XOXO ++* iCalendar export:: Exporting in iCalendar format ++ ++Markup rules ++ ++* Document title:: How the document title is determined ++* Headings and sections:: The main structure of the exported document ++* Table of contents:: If, where, how to create a table of contents ++* Initial text:: Text before the first headline ++* Lists:: Plain lists are exported ++* Paragraphs:: What determines beginning and ending ++* Literal examples:: Source code and other examples ++* Include files:: Include the contents of a file during export ++* Tables exported:: Tables are exported richly ++* Inlined images:: How to inline images during export ++* Footnote markup:: ++* Emphasis and monospace:: To bold or not to bold ++* TeX macros and LaTeX fragments:: Create special, rich export. ++* Horizontal rules:: A line across the page ++* Comment lines:: Some lines will not be exported ++ ++HTML export ++ ++* HTML Export commands:: How to invoke HTML export ++* Quoting HTML tags:: Using direct HTML in Org mode ++* Links:: Transformation of links for HTML ++* Images in HTML export:: How to insert figures into HTML output ++* Text areas in HTML export:: An alternative way to show an example ++* CSS support:: Changing the appearance of the output ++* Javascript support:: Info and Folding in a web browser ++ ++LaTeX and PDF export ++ ++* LaTeX/PDF export commands:: Which key invokes which commands ++* Quoting LaTeX code:: Incorporating literal LaTeX code ++* Sectioning structure:: Changing sectioning in LaTeX output ++* Tables in LaTeX export:: Options for exporting tables to LaTeX ++* Images in LaTeX export:: How to insert figures into LaTeX output ++ ++Publishing ++ ++* Configuration:: Defining projects ++* Sample configuration:: Example projects ++* Triggering publication:: Publication commands ++ ++Configuration ++ ++* Project alist:: The central configuration variable ++* Sources and destinations:: From here to there ++* Selecting files:: What files are part of the project? ++* Publishing action:: Setting the function doing the publishing ++* Publishing options:: Tweaking HTML export ++* Publishing links:: Which links keep working after publishing? ++* Project page index:: Publishing a list of project files ++ ++Sample configuration ++ ++* Simple example:: One-component publishing ++* Complex example:: A multi-component publishing example ++ ++Miscellaneous ++ ++* Completion:: M-TAB knows what you need ++* Customization:: Adapting Org to your taste ++* In-buffer settings:: Overview of the #+KEYWORDS ++* The very busy C-c C-c key:: When in doubt, press C-c C-c ++* Clean view:: Getting rid of leading stars in the outline ++* TTY keys:: Using Org on a tty ++* Interaction:: Other Emacs packages ++* Bugs:: Things which do not work perfectly ++ ++Interaction with other packages ++ ++* Cooperation:: Packages Org cooperates with ++* Conflicts:: Packages that lead to conflicts ++ ++Extensions ++ ++* Extensions in the contrib directory:: These come with the Org distro ++* Other extensions:: These you have to find on the web. ++ ++Hacking ++ ++* Adding hyperlink types:: New custom link types ++* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs ++* Dynamic blocks:: Automatically filled blocks ++* Special agenda views:: Customized views ++* Using the property API:: Writing programs that use entry properties ++* Using the mapping API:: Mapping over all or selected entries ++ ++Tables and lists in arbitrary syntax ++ ++* Radio tables:: Sending and receiving ++* A LaTeX example:: Step by step, almost a tutorial ++* Translator functions:: Copy and modify ++* Radio lists:: Doing the same for lists ++ ++@end detailmenu ++@end menu ++ ++@node Introduction, Document Structure, Top, Top ++@chapter Introduction ++@cindex introduction ++ ++@menu ++* Summary:: Brief summary of what Org does ++* Installation:: How to install a downloaded version of Org ++* Activation:: How to activate Org for certain buffers ++* Feedback:: Bug reports, ideas, patches etc. ++* Conventions:: Type-setting conventions in the manual ++@end menu ++ ++@node Summary, Installation, Introduction, Introduction ++@section Summary ++@cindex summary ++ ++Org is a mode for keeping notes, maintaining TODO lists, and doing ++project planning with a fast and effective plain-text system. ++ ++Org develops organizational tasks around NOTES files that contain ++lists or information about projects as plain text. Org is ++implemented on top of Outline mode, which makes it possible to keep the ++content of large files well structured. Visibility cycling and ++structure editing help to work with the tree. Tables are easily created ++with a built-in table editor. Org supports TODO items, deadlines, ++time stamps, and scheduling. It dynamically compiles entries into an ++agenda that utilizes and smoothly integrates much of the Emacs calendar ++and diary. Plain text URL-like links connect to websites, emails, ++Usenet messages, BBDB entries, and any files related to the projects. ++For printing and sharing of notes, an Org file can be exported as a ++structured ASCII file, as HTML, or (TODO and agenda items only) as an ++iCalendar file. It can also serve as a publishing tool for a set of ++linked web pages. ++ ++An important design aspect that distinguishes Org from for example ++Planner/Muse is that it encourages to store every piece of information ++only once. In Planner, you have project pages, day pages and possibly ++other files, duplicating some information such as tasks. In Org, ++you only have notes files. In your notes you mark entries as tasks, ++label them with tags and timestamps. All necessary lists like a ++schedule for the day, the agenda for a meeting, tasks lists selected by ++tags etc are created dynamically when you need them. ++ ++Org keeps simple things simple. When first fired up, it should ++feel like a straightforward, easy to use outliner. Complexity is not ++imposed, but a large amount of functionality is available when you need ++it. Org is a toolbox and can be used in different ways, for ++example as: ++ ++@example ++@r{@bullet{} outline extension with visibility cycling and structure editing} ++@r{@bullet{} ASCII system and table editor for taking structured notes} ++@r{@bullet{} ASCII table editor with spreadsheet-like capabilities} ++@r{@bullet{} TODO list editor} ++@r{@bullet{} full agenda and planner with deadlines and work scheduling} ++@r{@bullet{} environment to implement David Allen's GTD system} ++@r{@bullet{} a basic database application} ++@r{@bullet{} simple hypertext system, with HTML and LaTeX export} ++@r{@bullet{} publishing tool to create a set of interlinked webpages} ++@end example ++ ++Org's automatic, context sensitive table editor with spreadsheet ++capabilities can be integrated into any major mode by activating the ++minor Orgtbl mode. Using a translation step, it can be used to maintain ++tables in arbitrary file types, for example in La@TeX{}. The structure ++editing and list creation capabilities can be used outside Org with ++the minor Orgstruct mode. ++ ++@cindex FAQ ++There is a website for Org which provides links to the newest ++version of Org, as well as additional information, frequently asked ++questions (FAQ), links to tutorials etc. This page is located at ++@uref{http://orgmode.org}. ++ ++@page ++ ++ ++@node Installation, Activation, Summary, Introduction ++@section Installation ++@cindex installation ++@cindex XEmacs ++ ++@b{Important:} @i{If Org is part of the Emacs distribution or an ++XEmacs package, please skip this section and go directly to ++@ref{Activation}.} ++ ++If you have downloaded Org from the Web, either as a distribution @file{.zip} ++or @file{.tar} file, or as a GIT archive, you must take the following steps ++to install it: Go into the unpacked Org distribution directory and edit the ++top section of the file @file{Makefile}. You must set the name of the Emacs ++binary (likely either @file{emacs} or @file{xemacs}), and the paths to the ++directories where local Lisp and Info files are kept. If you don't have ++access to the system-wide directories, you can simply run Org directly from ++the distribution directory by adding the @file{lisp} subdirectory to the ++Emacs load path. To do this, add the following line to @file{.emacs}: ++ ++@example ++(setq load-path (cons "~/path/to/orgdir/lisp" load-path)) ++@end example ++ ++@noindent ++If you plan to use code from the @file{contrib} subdirectory, do a similar ++step for this directory: ++ ++@example ++(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) ++@end example ++ ++@b{XEmacs users now need to install the file @file{noutline.el} from ++the @file{xemacs} sub-directory of the Org distribution. Use the ++command:} ++ ++@example ++@b{make install-noutline} ++@end example ++ ++@noindent Now byte-compile the Lisp files with the shell command: ++ ++@example ++make ++@end example ++ ++@noindent If you are running Org from the distribution directory, this is ++all. If you want to install into the system directories, use ++ ++@example ++make install ++make install-info ++@end example ++ ++@noindent Then add to @file{.emacs}: ++ ++@lisp ++;; This line only if Org is not part of the X/Emacs distribution. ++(require 'org-install) ++@end lisp ++ ++Do not forget to activate Org as described in the following section. ++ ++@node Activation, Feedback, Installation, Introduction ++@section Activation ++@cindex activation ++@cindex autoload ++@cindex global key bindings ++@cindex key bindings, global ++ ++@iftex ++@b{Important:} @i{If you use copy-and-paste to copy lisp code from the ++PDF documentation as viewed by some PDF viewers to your .emacs file, the ++single quote character comes out incorrectly and the code will not work. ++You need to fix the single quotes by hand, or copy from Info ++documentation.} ++@end iftex ++ ++Add the following lines to your @file{.emacs} file. The last three lines ++define @emph{global} keys for the commands @command{org-store-link}, ++@command{org-agenda}, and @command{org-iswitchb} - please choose suitable ++keys yourself. ++ ++@lisp ++;; The following lines are always needed. Choose your own keys. ++(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) ++(global-set-key "\C-cl" 'org-store-link) ++(global-set-key "\C-ca" 'org-agenda) ++(global-set-key "\C-cb" 'org-iswitchb) ++@end lisp ++ ++Furthermore, you must activate @code{font-lock-mode} in Org ++buffers, because significant functionality depends on font-locking being ++active. You can do this with either one of the following two lines ++(XEmacs user must use the second option): ++@lisp ++(global-font-lock-mode 1) ; for all buffers ++(add-hook 'org-mode-hook 'turn-on-font-lock) ; Org buffers only ++@end lisp ++ ++@cindex Org mode, turning on ++With this setup, all files with extension @samp{.org} will be put ++into Org mode. As an alternative, make the first line of a file look ++like this: ++ ++@example ++MY PROJECTS -*- mode: org; -*- ++@end example ++ ++@noindent which will select Org mode for this buffer no matter what ++the file's name is. See also the variable ++@code{org-insert-mode-line-in-empty-file}. ++ ++Many commands in Org work on the region if the region is active. To make use ++of this, you need to have @code{transient-mark-mode} (@code{zmacs-regions} in ++XEmacs) turned on. In Emacs 23 this is the default, in Emacs 22 you need to ++do this yourself with ++ ++@lisp ++(transient-mark-mode 1) ++@end lisp ++ ++@node Feedback, Conventions, Activation, Introduction ++@section Feedback ++@cindex feedback ++@cindex bug reports ++@cindex maintainer ++@cindex author ++ ++If you find problems with Org, or if you have questions, remarks, or ideas ++about it, please mail to the Org mailing list @code{emacs-orgmode@@gnu.org}. ++If you are not a member of the mailing list, your mail will be reviewed by a ++moderator and then passed through to the list. ++ ++For bug reports, please provide as much information as possible, ++including the version information of Emacs (@kbd{C-h v emacs-version ++@key{RET}}) and Org (@kbd{C-h v org-version @key{RET}}), as well as ++the Org related setup in @file{.emacs}. If an error occurs, a ++backtrace can be very useful (see below on how to create one). Often a ++small example file helps, along with clear information about: ++ ++@enumerate ++@item What exactly did you do? ++@item What did you expect to happen? ++@item What happened instead? ++@end enumerate ++@noindent Thank you for helping to improve this mode. ++ ++@subsubheading How to create a useful backtrace ++ ++@cindex backtrace of an error ++If working with Org produces an error with a message you don't ++understand, you may have hit a bug. The best way to report this is by ++providing, in addition to what was mentioned above, a @emph{Backtrace}. ++This is information from the built-in debugger about where and how the ++error occurred. Here is how to produce a useful backtrace: ++ ++@enumerate ++@item ++Start a fresh Emacs or XEmacs, and make sure that it will load the ++original Lisp code in @file{org.el} instead of the compiled version in ++@file{org.elc}. The backtrace contains much more information if it is ++produced with uncompiled code. To do this, either rename @file{org.elc} ++to something else before starting Emacs, or ask Emacs explicitly to load ++@file{org.el} by using the command line ++@example ++emacs -l /path/to/org.el ++@end example ++@item ++Go to the @code{Options} menu and select @code{Enter Debugger on Error} ++(XEmacs has this option in the @code{Troubleshooting} sub-menu). ++@item ++Do whatever you have to do to hit the error. Don't forget to ++document the steps you take. ++@item ++When you hit the error, a @file{*Backtrace*} buffer will appear on the ++screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and ++attach it to your bug report. ++@end enumerate ++ ++@node Conventions, , Feedback, Introduction ++@section Typesetting conventions used in this manual ++ ++Org uses three types of keywords: TODO keywords, tags, and property ++names. In this manual we use the following conventions: ++ ++@table @code ++@item TODO ++@itemx WAITING ++TODO keywords are written with all capitals, even if they are ++user-defined. ++@item boss ++@itemx ARCHIVE ++User-defined tags are written in lowercase; built-in tags with special ++meaning are written with all capitals. ++@item Release ++@itemx PRIORITY ++User-defined properties are capitalized; built-in properties with ++special meaning are written with all capitals. ++@end table ++ ++@node Document Structure, Tables, Introduction, Top ++@chapter Document Structure ++@cindex document structure ++@cindex structure of document ++ ++Org is based on outline mode and provides flexible commands to ++edit the structure of the document. ++ ++@menu ++* Outlines:: Org is based on Outline mode ++* Headlines:: How to typeset Org tree headlines ++* Visibility cycling:: Show and hide, much simplified ++* Motion:: Jumping to other headlines ++* Structure editing:: Changing sequence and level of headlines ++* Archiving:: Move done task trees to a different place ++* Sparse trees:: Matches embedded in context ++* Plain lists:: Additional structure within an entry ++* Drawers:: Tucking stuff away ++* Footnotes:: How footnotes are defined in Org's syntax ++* Orgstruct mode:: Structure editing outside Org ++@end menu ++ ++@node Outlines, Headlines, Document Structure, Document Structure ++@section Outlines ++@cindex outlines ++@cindex Outline mode ++ ++Org is implemented on top of Outline mode. Outlines allow a ++document to be organized in a hierarchical structure, which (at least ++for me) is the best representation of notes and thoughts. An overview ++of this structure is achieved by folding (hiding) large parts of the ++document to show only the general document structure and the parts ++currently being worked on. Org greatly simplifies the use of ++outlines by compressing the entire show/hide functionality into a single ++command @command{org-cycle}, which is bound to the @key{TAB} key. ++ ++@node Headlines, Visibility cycling, Outlines, Document Structure ++@section Headlines ++@cindex headlines ++@cindex outline tree ++ ++Headlines define the structure of an outline tree. The headlines in ++Org start with one or more stars, on the left margin@footnote{See ++the variable @code{org-special-ctrl-a/e} to configure special behavior ++of @kbd{C-a} and @kbd{C-e} in headlines.}. For example: ++ ++@example ++* Top level headline ++** Second level ++*** 3rd level ++ some text ++*** 3rd level ++ more text ++ ++* Another top level headline ++@end example ++ ++@noindent Some people find the many stars too noisy and would prefer an ++outline that has whitespace followed by a single star as headline ++starters. @ref{Clean view} describes a setup to realize this. ++ ++An empty line after the end of a subtree is considered part of it and ++will be hidden when the subtree is folded. However, if you leave at ++least two empty lines, one empty line will remain visible after folding ++the subtree, in order to structure the collapsed view. See the ++variable @code{org-cycle-separator-lines} to modify this behavior. ++ ++@node Visibility cycling, Motion, Headlines, Document Structure ++@section Visibility cycling ++@cindex cycling, visibility ++@cindex visibility cycling ++@cindex trees, visibility ++@cindex show hidden text ++@cindex hide text ++ ++Outlines make it possible to hide parts of the text in the buffer. ++Org uses just two commands, bound to @key{TAB} and ++@kbd{S-@key{TAB}} to change the visibility in the buffer. ++ ++@cindex subtree visibility states ++@cindex subtree cycling ++@cindex folded, subtree visibility state ++@cindex children, subtree visibility state ++@cindex subtree, subtree visibility state ++@table @kbd ++@kindex @key{TAB} ++@item @key{TAB} ++@emph{Subtree cycling}: Rotate current subtree among the states ++ ++@example ++,-> FOLDED -> CHILDREN -> SUBTREE --. ++'-----------------------------------' ++@end example ++ ++The cursor must be on a headline for this to work@footnote{see, however, ++the option @code{org-cycle-emulate-tab}.}. When the cursor is at the ++beginning of the buffer and the first line is not a headline, then ++@key{TAB} actually runs global cycling (see below)@footnote{see the ++option @code{org-cycle-global-at-bob}.}. Also when called with a prefix ++argument (@kbd{C-u @key{TAB}}), global cycling is invoked. ++ ++@cindex global visibility states ++@cindex global cycling ++@cindex overview, global visibility state ++@cindex contents, global visibility state ++@cindex show all, global visibility state ++@kindex S-@key{TAB} ++@item S-@key{TAB} ++@itemx C-u @key{TAB} ++@emph{Global cycling}: Rotate the entire buffer among the states ++ ++@example ++,-> OVERVIEW -> CONTENTS -> SHOW ALL --. ++'--------------------------------------' ++@end example ++ ++When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the ++CONTENTS view up to headlines of level N will be shown. Note that inside ++tables, @kbd{S-@key{TAB}} jumps to the previous field. ++ ++@cindex show all, command ++@kindex C-u C-u C-u @key{TAB} ++@item C-u C-u C-u @key{TAB} ++Show all, including drawers. ++@kindex C-c C-r ++@item C-c C-r ++Reveal context around point, showing the current entry, the following heading ++and the hierarchy above. Useful for working near a location that has been ++exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command ++(@pxref{Agenda commands}). With a prefix argument show, on each ++level, all sibling headings. ++@kindex C-c C-x b ++@item C-c C-x b ++Show the current subtree in an indirect buffer@footnote{The indirect ++buffer ++@ifinfo ++(@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) ++@end ifinfo ++@ifnotinfo ++(see the Emacs manual for more information about indirect buffers) ++@end ifnotinfo ++will contain the entire buffer, but will be narrowed to the current ++tree. Editing the indirect buffer will also change the original buffer, ++but without affecting visibility in that buffer.}. With a numeric ++prefix argument N, go up to level N and then take that tree. If N is ++negative then go up that many levels. With a @kbd{C-u} prefix, do not remove ++the previously used indirect buffer. ++@end table ++ ++When Emacs first visits an Org file, the global state is set to ++OVERVIEW, i.e. only the top level headlines are visible. This can be ++configured through the variable @code{org-startup-folded}, or on a ++per-file basis by adding one of the following lines anywhere in the ++buffer: ++ ++@example ++#+STARTUP: overview ++#+STARTUP: content ++#+STARTUP: showall ++@end example ++ ++@noindent ++Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties ++and Columns}) will get their visibility adapted accordingly. Allowed values ++for this property are @code{folded}, @code{children}, @code{content}, and ++@code{all}. ++@table @kbd ++@kindex C-u C-u @key{TAB} ++@item C-u C-u @key{TAB} ++Switch back to the startup visibility of the buffer, i.e. whatever is ++requested by startup options and @samp{VISIBILITY} properties in individual ++entries. ++@end table ++ ++@node Motion, Structure editing, Visibility cycling, Document Structure ++@section Motion ++@cindex motion, between headlines ++@cindex jumping, to headlines ++@cindex headline navigation ++The following commands jump to other headlines in the buffer. ++ ++@table @kbd ++@kindex C-c C-n ++@item C-c C-n ++Next heading. ++@kindex C-c C-p ++@item C-c C-p ++Previous heading. ++@kindex C-c C-f ++@item C-c C-f ++Next heading same level. ++@kindex C-c C-b ++@item C-c C-b ++Previous heading same level. ++@kindex C-c C-u ++@item C-c C-u ++Backward to higher level heading. ++@kindex C-c C-j ++@item C-c C-j ++Jump to a different place without changing the current outline ++visibility. Shows the document structure in a temporary buffer, where ++you can use the following keys to find your destination: ++@example ++@key{TAB} @r{Cycle visibility.} ++@key{down} / @key{up} @r{Next/previous visible headline.} ++@key{RET} @r{Select this location.} ++@kbd{/} @r{Do a Sparse-tree search} ++@r{The following keys work if you turn off @code{org-goto-auto-isearch}} ++n / p @r{Next/previous visible headline.} ++f / b @r{Next/previous headline same level.} ++u @r{One level up.} ++0-9 @r{Digit argument.} ++q @r{Quit} ++@end example ++See also the variable@code{org-goto-interface}. ++@end table ++ ++@node Structure editing, Archiving, Motion, Document Structure ++@section Structure editing ++@cindex structure editing ++@cindex headline, promotion and demotion ++@cindex promotion, of subtrees ++@cindex demotion, of subtrees ++@cindex subtree, cut and paste ++@cindex pasting, of subtrees ++@cindex cutting, of subtrees ++@cindex copying, of subtrees ++@cindex subtrees, cut and paste ++ ++@table @kbd ++@kindex M-@key{RET} ++@item M-@key{RET} ++Insert new heading with same level as current. If the cursor is in a ++plain list item, a new item is created (@pxref{Plain lists}). To force ++creation of a new headline, use a prefix argument, or first press @key{RET} ++to get to the beginning of the next line. When this command is used in ++the middle of a line, the line is split and the rest of the line becomes ++the new headline@footnote{If you do not want the line to be split, ++customize the variable @code{org-M-RET-may-split-line}.}. If the ++command is used at the beginning of a headline, the new headline is ++created before the current line. If at the beginning of any other line, ++the content of that line is made the new heading. If the command is ++used at the end of a folded subtree (i.e. behind the ellipses at the end ++of a headline), then a headline like the current one will be inserted ++after the end of the subtree. ++@kindex C-@key{RET} ++@item C-@key{RET} ++Just like @kbd{M-@key{RET}}, except when adding a new heading below the ++current heading, the new heading is placed after the body instead of before ++it. This command works from anywhere in the entry. ++@kindex M-S-@key{RET} ++@item M-S-@key{RET} ++Insert new TODO entry with same level as current heading. ++@kindex C-S-@key{RET} ++@item C-S-@key{RET} ++Insert new TODO entry with same level as current heading. Like ++@kbd{C-@key{RET}}, the new headline will be inserted after the current ++subtree. ++@kindex M-@key{left} ++@item M-@key{left} ++Promote current heading by one level. ++@kindex M-@key{right} ++@item M-@key{right} ++Demote current heading by one level. ++@kindex M-S-@key{left} ++@item M-S-@key{left} ++Promote the current subtree by one level. ++@kindex M-S-@key{right} ++@item M-S-@key{right} ++Demote the current subtree by one level. ++@kindex M-S-@key{up} ++@item M-S-@key{up} ++Move subtree up (swap with previous subtree of same ++level). ++@kindex M-S-@key{down} ++@item M-S-@key{down} ++Move subtree down (swap with next subtree of same level). ++@kindex C-c C-x C-w ++@item C-c C-x C-w ++Kill subtree, i.e. remove it from buffer but save in kill ring. ++With a numeric prefix argument N, kill N sequential subtrees. ++@kindex C-c C-x M-w ++@item C-c C-x M-w ++Copy subtree to kill ring. With a numeric prefix argument N, copy the N ++sequential subtrees. ++@kindex C-c C-x C-y ++@item C-c C-x C-y ++Yank subtree from kill ring. This does modify the level of the subtree to ++make sure the tree fits in nicely at the yank position. The yank level can ++also be specified with a numeric prefix argument, or by yanking after a ++headline marker like @samp{****}. ++@kindex C-y ++@item C-y ++Depending on the variables @code{org-yank-adjusted-subtrees} and ++@code{org-yank-folded-subtrees}, Org's internal @code{yank} command will ++paste subtrees folded and in a clever way, using the same command as @kbd{C-c ++C-x C-y}. With the default settings, no level adjustment will take place, ++but the yanked tree will be folded unless doing so would swallow text ++previously visible. Any prefix argument to this command will force a normal ++@code{yank} to be executed, with the prefix passed along. A good way to ++force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a ++yank, it will yank previous kill items plainly, without adjustment and ++folding. ++@kindex C-c C-w ++@item C-c C-w ++Refile entry or region to a different location. @xref{Refiling notes}. ++@kindex C-c ^ ++@item C-c ^ ++Sort same-level entries. When there is an active region, all entries in the ++region will be sorted. Otherwise the children of the current headline are ++sorted. The command prompts for the sorting method, which can be ++alphabetically, numerically, by time (using the first time stamp in each ++entry), by priority, or by TODO keyword (in the sequence the keywords have ++been defined in the setup). Reverse sorting is possible as well. You can ++also supply your own function to extract the sorting key. With a @kbd{C-u} ++prefix, sorting will be case-sensitive. With two @kbd{C-u C-u} prefixes, ++duplicate entries will also be removed. ++@kindex C-x n s ++@item C-x n s ++Narrow buffer to current subtree. ++@kindex C-x n w ++@item C-x n w ++Widen buffer to remove a narrowing. ++@kindex C-c * ++@item C-c * ++Turn a normal line or plain list item into a headline (so that it becomes a ++subheading at its location). Also turn a headline into a normal line by ++removing the stars. If there is an active region, turn all lines in the ++region into headlines. If the first line in the region was an item, turn ++only the item lines into headlines. Finally, if the first line is a ++headline, remove the stars from all headlines in the region. ++@end table ++ ++@cindex region, active ++@cindex active region ++@cindex Transient mark mode ++When there is an active region (Transient mark mode), promotion and ++demotion work on all headlines in the region. To select a region of ++headlines, it is best to place both point and mark at the beginning of a ++line, mark at the beginning of the first headline, and point at the line ++just after the last headline to change. Note that when the cursor is ++inside a table (@pxref{Tables}), the Meta-Cursor keys have different ++functionality. ++ ++@node Archiving, Sparse trees, Structure editing, Document Structure ++@section Archiving ++@cindex archiving ++ ++When a project represented by a (sub)tree is finished, you may want ++to move the tree out of the way and to stop it from contributing to the ++agenda. Org mode knows two ways of archiving. You can mark a tree with ++the ARCHIVE tag, or you can move an entire (sub)tree to a different ++location. ++ ++@menu ++* ARCHIVE tag:: Marking a tree as inactive ++* Moving subtrees:: Moving a tree to an archive file ++@end menu ++ ++@node ARCHIVE tag, Moving subtrees, Archiving, Archiving ++@subsection The ARCHIVE tag ++@cindex internal archiving ++ ++A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at ++its location in the outline tree, but behaves in the following way: ++@itemize @minus ++@item ++It does not open when you attempt to do so with a visibility cycling ++command (@pxref{Visibility cycling}). You can force cycling archived ++subtrees with @kbd{C-@key{TAB}}, or by setting the option ++@code{org-cycle-open-archived-trees}. Also normal outline commands like ++@code{show-all} will open archived subtrees. ++@item ++During sparse tree construction (@pxref{Sparse trees}), matches in ++archived subtrees are not exposed, unless you configure the option ++@code{org-sparse-tree-open-archived-trees}. ++@item ++During agenda view construction (@pxref{Agenda Views}), the content of ++archived trees is ignored unless you configure the option ++@code{org-agenda-skip-archived-trees}, in which case these trees will always ++be included. In the agenda you can press the @kbd{v} key to get archives ++temporarily included. ++@item ++Archived trees are not exported (@pxref{Exporting}), only the headline ++is. Configure the details using the variable ++@code{org-export-with-archived-trees}. ++@end itemize ++ ++The following commands help managing the ARCHIVE tag: ++ ++@table @kbd ++@kindex C-c C-x a ++@item C-c C-x a ++Toggle the ARCHIVE tag for the current headline. When the tag is set, ++the headline changes to a shadowed face, and the subtree below it is ++hidden. ++@kindex C-u C-c C-x a ++@item C-u C-c C-x a ++Check if any direct children of the current headline should be archived. ++To do this, each subtree is checked for open TODO entries. If none are ++found, the command offers to set the ARCHIVE tag for the child. If the ++cursor is @emph{not} on a headline when this command is invoked, the ++level 1 trees will be checked. ++@kindex C-@kbd{TAB} ++@item C-@kbd{TAB} ++Cycle a tree even if it is tagged with ARCHIVE. ++@end table ++ ++@node Moving subtrees, , ARCHIVE tag, Archiving ++@subsection Moving subtrees ++@cindex external archiving ++ ++Once an entire project is finished, you may want to move it to a different ++location. Org can move it to an @emph{Archive Sibling} in the same tree, to a ++different tree in the current file, or to a different file, the archive file. ++ ++@table @kbd ++@kindex C-c C-x A ++@item C-c C-x A ++Move the current entry to the @emph{Archive Sibling}. This is a sibling of ++the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE} ++(@pxref{ARCHIVE tag}). The entry becomes a child of that sibling and in this ++way retains a lot of its original context, including inherited tags and ++approximate position in the outline. ++@kindex C-c C-x C-s ++@item C-c C-x C-s ++Archive the subtree starting at the cursor position to the location ++given by @code{org-archive-location}. Context information that could be ++lost like the file name, the category, inherited tags, and the TODO ++state will be store as properties in the entry. ++@kindex C-u C-c C-x C-s ++@item C-u C-c C-x C-s ++Check if any direct children of the current headline could be moved to ++the archive. To do this, each subtree is checked for open TODO entries. ++If none are found, the command offers to move it to the archive ++location. If the cursor is @emph{not} on a headline when this command ++is invoked, the level 1 trees will be checked. ++@end table ++ ++@cindex archive locations ++The default archive location is a file in the same directory as the ++current file, with the name derived by appending @file{_archive} to the ++current file name. For information and examples on how to change this, ++see the documentation string of the variable ++@code{org-archive-location}. There is also an in-buffer option for ++setting this variable, for example@footnote{For backward compatibility, ++the following also works: If there are several such lines in a file, ++each specifies the archive location for the text below it. The first ++such line also applies to any text before its definition. However, ++using this method is @emph{strongly} deprecated as it is incompatible ++with the outline structure of the document. The correct method for ++setting multiple archive locations in a buffer is using properties.}: ++ ++@example ++#+ARCHIVE: %s_done:: ++@end example ++ ++@noindent ++If you would like to have a special ARCHIVE location for a single entry ++or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the ++location as the value (@pxref{Properties and Columns}). ++ ++When a subtree is moved, it receives a number of special properties that ++record context information like the file from where the entry came, it's ++outline path the archiving time etc. Configure the variable ++@code{org-archive-save-context-info} to adjust the amount of information ++added. ++ ++@node Sparse trees, Plain lists, Archiving, Document Structure ++@section Sparse trees ++@cindex sparse trees ++@cindex trees, sparse ++@cindex folding, sparse trees ++@cindex occur, command ++ ++An important feature of Org mode is the ability to construct @emph{sparse ++trees} for selected information in an outline tree, so that the entire ++document is folded as much as possible, but the selected information is made ++visible along with the headline structure above it@footnote{See also the ++variables @code{org-show-hierarchy-above}, @code{org-show-following-heading}, ++@code{org-show-siblings}, and @code{org-show-entry-below} for detailed ++control on how much context is shown around each match.}. Just try it out ++and you will see immediately how it works. ++ ++Org mode contains several commands creating such trees, all these ++commands can be accessed through a dispatcher: ++ ++@table @kbd ++@kindex C-c / ++@item C-c / ++This prompts for an extra key to select a sparse-tree creating command. ++@kindex C-c / r ++@item C-c / r ++Occur. Prompts for a regexp and shows a sparse tree with all matches. If ++the match is in a headline, the headline is made visible. If the match is in ++the body of an entry, headline and body are made visible. In order to ++provide minimal context, also the full hierarchy of headlines above the match ++is shown, as well as the headline following the match. Each match is also ++highlighted; the highlights disappear when the buffer is changed by an ++editing command@footnote{depending on the option ++@code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}. ++When called with a @kbd{C-u} prefix argument, previous highlights are kept, ++so several calls to this command can be stacked. ++@end table ++ ++@noindent ++For frequently used sparse trees of specific search strings, you can ++use the variable @code{org-agenda-custom-commands} to define fast ++keyboard access to specific sparse trees. These commands will then be ++accessible through the agenda dispatcher (@pxref{Agenda dispatcher}). ++For example: ++ ++@lisp ++(setq org-agenda-custom-commands ++ '(("f" occur-tree "FIXME"))) ++@end lisp ++ ++@noindent will define the key @kbd{C-c a f} as a shortcut for creating ++a sparse tree matching the string @samp{FIXME}. ++ ++The other sparse tree commands select headings based on TODO keywords, ++tags, or properties and will be discussed later in this manual. ++ ++@kindex C-c C-e v ++@cindex printing sparse trees ++@cindex visible text, printing ++To print a sparse tree, you can use the Emacs command ++@code{ps-print-buffer-with-faces} which does not print invisible parts ++of the document @footnote{This does not work under XEmacs, because ++XEmacs uses selective display for outlining, not text properties.}. ++Or you can use the command @kbd{C-c C-e v} to export only the visible ++part of the document and print the resulting file. ++ ++@node Plain lists, Drawers, Sparse trees, Document Structure ++@section Plain lists ++@cindex plain lists ++@cindex lists, plain ++@cindex lists, ordered ++@cindex ordered lists ++ ++Within an entry of the outline tree, hand-formatted lists can provide ++additional structure. They also provide a way to create lists of ++checkboxes (@pxref{Checkboxes}). Org supports editing such lists, ++and the HTML exporter (@pxref{Exporting}) parses and formats them. ++ ++Org knows ordered lists, unordered lists, and description lists. ++@itemize @bullet ++@item ++@emph{Unordered} list items start with @samp{-}, @samp{+}, or ++@samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or ++they will be seen as top-level headlines. Also, when you are hiding leading ++stars to get a clean outline view, plain list items starting with a star are ++visually indistinguishable from true headlines. In short: even though ++@samp{*} is supported, it may be better to not use it for plain list items.} ++as bullets. ++@item ++@emph{Ordered} list items start with a numeral followed by either a period or ++a right parenthesis, such as @samp{1.} or @samp{1)}. ++@item ++@emph{Description} list items are like unordered list items, but contain the ++separator @samp{ :: } to separate the description @emph{term} from the ++description. ++@end itemize ++ ++Items belonging to the same list must have the same indentation on the first ++line. In particular, if an ordered list reaches number @samp{10.}, then the ++2--digit numbers must be written left-aligned with the other numbers in the ++list. Indentation also determines the end of a list item. It ends before ++the next line that is indented like the bullet/number, or less. Empty lines ++are part of the previous item, so you can have several paragraphs in one ++item. If you would like an empty line to terminate all currently open plain ++lists, configure the variable @code{org-empty-line-terminates-plain-lists}. ++Here is an example: ++ ++@example ++@group ++** Lord of the Rings ++ My favorite scenes are (in this order) ++ 1. The attack of the Rohirrim ++ 2. Eowyn's fight with the witch king ++ + this was already my favorite scene in the book ++ + I really like Miranda Otto. ++ 3. Peter Jackson being shot by Legolas ++ - on DVD only ++ He makes a really funny face when it happens. ++ But in the end, no individual scenes matter but the film as a whole. ++ Important actors in this film are: ++ - @b{Elijah Wood} :: He plays Frodo ++ - @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember ++ him very well from his role as Mikey Walsh in the Goonies. ++@end group ++@end example ++ ++Org supports these lists by tuning filling and wrapping commands to ++deal with them correctly@footnote{Org only changes the filling ++settings for Emacs. For XEmacs, you should use Kyle E. Jones' ++@file{filladapt.el}. To turn this on, put into @file{.emacs}: ++@code{(require 'filladapt)}}, and by exporting them properly ++(@pxref{Exporting}). ++ ++The following commands act on items when the cursor is in the first line ++of an item (the line with the bullet or number). ++ ++@table @kbd ++@kindex @key{TAB} ++@item @key{TAB} ++Items can be folded just like headline levels if you set the variable ++@code{org-cycle-include-plain-lists}. The level of an item is then ++given by the indentation of the bullet/number. Items are always ++subordinate to real headlines, however; the hierarchies remain ++completely separated. ++ ++If @code{org-cycle-include-plain-lists} has not been set, @key{TAB} ++fixes the indentation of the current line in a heuristic way. ++@kindex M-@key{RET} ++@item M-@key{RET} ++Insert new item at current level. With a prefix argument, force a new ++heading (@pxref{Structure editing}). If this command is used in the middle ++of a line, the line is @emph{split} and the rest of the line becomes the new ++item@footnote{If you do not want the line to be split, customize the variable ++@code{org-M-RET-may-split-line}.}. If this command is executed in the ++@emph{whitespace before a bullet or number}, the new item is created ++@emph{before} the current item. If the command is executed in the white ++space before the text that is part of an item but does not contain the ++bullet, a bullet is added to the current line. ++@kindex M-S-@key{RET} ++@item M-S-@key{RET} ++Insert a new item with a checkbox (@pxref{Checkboxes}). ++@kindex S-@key{up} ++@kindex S-@key{down} ++@item S-@key{up} ++@itemx S-@key{down} ++@cindex shift-selection-mode ++Jump to the previous/next item in the current list, but only if ++@code{org-support-shift-select} is off. If not, you can still use paragraph ++jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite ++similar effect. ++@kindex M-S-@key{up} ++@kindex M-S-@key{down} ++@item M-S-@key{up} ++@itemx M-S-@key{down} ++Move the item including subitems up/down (swap with previous/next item ++of same indentation). If the list is ordered, renumbering is ++automatic. ++@kindex M-S-@key{left} ++@kindex M-S-@key{right} ++@item M-S-@key{left} ++@itemx M-S-@key{right} ++Decrease/increase the indentation of the item, including subitems. ++Initially, the item tree is selected based on current indentation. ++When these commands are executed several times in direct succession, ++the initially selected region is used, even if the new indentation ++would imply a different hierarchy. To use the new hierarchy, break ++the command chain with a cursor motion or so. ++@kindex C-c C-c ++@item C-c C-c ++If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the ++state of the checkbox. If not, this command makes sure that all the ++items on this list level use the same bullet. Furthermore, if this is ++an ordered list, make sure the numbering is OK. ++@kindex C-c - ++@item C-c - ++Cycle the entire list level through the different itemize/enumerate bullets ++(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). With a numeric prefix ++argument N, select the Nth bullet from this list. If there is an active ++region when calling this, all lines will be converted to list items. If the ++first line already was a list item, any item markers will be removed from the ++list. Finally, even without an active region, a normal line will be ++converted into a list item. ++@kindex S-@key{left} ++@kindex S-@key{right} ++@item S-@key{left}/@key{right} ++This command also cycles bullet styles when the cursor in on the bullet or ++anywhere in an item line, details depending on ++@code{org-support-shift-select}. ++@end table ++ ++@node Drawers, Footnotes, Plain lists, Document Structure ++@section Drawers ++@cindex drawers ++@cindex visibility cycling, drawers ++ ++Sometimes you want to keep information associated with an entry, but you ++normally don't want to see it. For this, Org mode has @emph{drawers}. ++Drawers need to be configured with the variable ++@code{org-drawers}@footnote{You can define drawers on a per-file basis ++with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers ++look like this: ++ ++@example ++** This is a headline ++ Still outside the drawer ++ :DRAWERNAME: ++ This is inside the drawer. ++ :END: ++ After the drawer. ++@end example ++ ++Visibility cycling (@pxref{Visibility cycling}) on the headline will ++hide and show the entry, but keep the drawer collapsed to a single line. ++In order to look inside the drawer, you need to move the cursor to the ++drawer line and press @key{TAB} there. Org mode uses a drawer for ++storing properties (@pxref{Properties and Columns}), and another one for ++storing clock times (@pxref{Clocking work time}). ++ ++@node Footnotes, Orgstruct mode, Drawers, Document Structure ++@section Footnotes ++@cindex footnotes ++ ++Org-mode supports the creation of footnotes. In contrast to the ++@file{footnote.el} package, Org-mode's footnotes are designed for work on a ++larger document, not only for one-off documents like emails. The basic ++syntax is similar to the one used by @file{footnote.el}, i.e. a footnote is ++defined in a paragraph that is started by a footnote marker in square ++brackets in column 0, no indentation allowed. If you need a paragraph break ++inside a footnote, use the LaTeX idiom @samp{\par}. The footnote reference ++is simply the marker in square brackets, inside text. For example: ++ ++@example ++The Org homepage[fn:1] now looks a lot better than it used to. ++... ++[fn:1] The link is: http://orgmode.org ++@end example ++ ++Org-mode extends the number-based syntax to @emph{named} footnotes and ++optional inline definition. Using plain numbers as markers (as ++@file{footnote.el} does) is supported for backward compatibility, but not ++encouraged because of possible conflicts with LaTeX snippets @pxref{Embedded ++LaTeX}. Here are the valid references: ++ ++@table @code ++@item [1] ++A plain numeric footnote marker. ++@item [fn:name] ++A named footnote reference, where @code{name} is a unique label word, or, for ++simplicity of automatic creation, a number. ++@item [fn:: This is the inline definition of this footnote] ++A LaTeX-like anonymous footnote where the definition is given directly at the ++reference point. ++@item [fn:name: a definition] ++An inline definition of a footnote, which also specifies a name for the note. ++Since Org allows multiple references to the same note, you can then use ++@code{[fn:name]} to create additional references. ++@end table ++ ++Footnote labels can be created automatically, or you create names yourself. ++This is handled by the variable @code{org-footnote-auto-label} and its ++corresponding @code{#+STARTUP} keywords, see the docstring of that variable ++for details. ++ ++@noindent The following command handles footnotes: ++ ++@table @kbd ++@kindex C-c C-x f ++@item C-c C-x f ++The footnote action command. ++ ++When the cursor is on a footnote reference, jump to the definition. When it ++is at a definition, jump to the (first) reference. ++ ++Otherwise, create a new footnote. Depending on the variable ++@code{org-footnote-define-inline}@footnote{The corresponding in-buffer ++setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the ++definition will be placed right into the text as part of the reference, or ++separately into the location determined by the variable ++@code{org-footnote-section}. ++ ++When this command is called with a prefix argument, a menu of additional ++options is offered: ++@example ++s @r{Sort the footnote definitions by reference sequence. During editing,} ++ @r{Org makes no effort to sort footnote definitions into a particular} ++ @r{sequence. If you want them sorted, use this command, which will} ++ @r{also move entries according to @code{org-footnote-section}.} ++n @r{Normalize the footnotes by collecting all definitions (including} ++ @r{inline definitions) into a special section, and then numbering them} ++ @r{in sequence. The references will then also be numbers. This is} ++ @r{meant to be the final step before finishing a document (e.g. sending} ++ @r{off an email). The exporters do this automatically, and so could} ++ @r{something like @code{message-send-hook}.} ++d @r{Delete the footnote at point, and all definitions of and references} ++ @r{to it.} ++@end example ++@kindex C-c C-c ++@item C-c C-c ++If the cursor is on a footnote reference, jump to the definition. If it is a ++the definition, jump back to the reference. When called at a footnote ++location with a prefix argument, offer the same menu as @kbd{C-c C-x f}. ++@kindex C-c C-o ++@kindex mouse-1 ++@kindex mouse-2 ++@item C-c C-c @r{or} mouse-1/2 ++Footnote labels are also links to the corresponding definition/reference, and ++you can use the usual commands to follow these links. ++@end table ++ ++@node Orgstruct mode, , Footnotes, Document Structure ++@section The Orgstruct minor mode ++@cindex Orgstruct mode ++@cindex minor mode for structure editing ++ ++If you like the intuitive way the Org mode structure editing and list ++formatting works, you might want to use these commands in other modes ++like Text mode or Mail mode as well. The minor mode Orgstruct mode ++makes this possible. You can always toggle the mode with @kbd{M-x ++orgstruct-mode}. To turn it on by default, for example in Mail mode, ++use ++ ++@lisp ++(add-hook 'mail-mode-hook 'turn-on-orgstruct) ++@end lisp ++ ++When this mode is active and the cursor is on a line that looks to ++Org like a headline of the first line of a list item, most ++structure editing commands will work, even if the same keys normally ++have different functionality in the major mode you are using. If the ++cursor is not in one of those special lines, Orgstruct mode lurks ++silently in the shadow. ++ ++@node Tables, Hyperlinks, Document Structure, Top ++@chapter Tables ++@cindex tables ++@cindex editing tables ++ ++Org comes with a fast and intuitive table editor. Spreadsheet-like ++calculations are supported in connection with the Emacs @file{calc} ++package ++@ifinfo ++(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}). ++@end ifinfo ++@ifnotinfo ++(see the Emacs Calculator manual for more information about the Emacs ++calculator). ++@end ifnotinfo ++ ++@menu ++* Built-in table editor:: Simple tables ++* Narrow columns:: Stop wasting space in tables ++* Column groups:: Grouping to trigger vertical lines ++* Orgtbl mode:: The table editor as minor mode ++* The spreadsheet:: The table editor has spreadsheet capabilities ++* Org Plot:: Plotting from org tables ++@end menu ++ ++@node Built-in table editor, Narrow columns, Tables, Tables ++@section The built-in table editor ++@cindex table editor, built-in ++ ++Org makes it easy to format tables in plain ASCII. Any line with ++@samp{|} as the first non-whitespace character is considered part of a ++table. @samp{|} is also the column separator. A table might look like ++this: ++ ++@example ++| Name | Phone | Age | ++|-------+-------+-----| ++| Peter | 1234 | 17 | ++| Anna | 4321 | 25 | ++@end example ++ ++A table is re-aligned automatically each time you press @key{TAB} or ++@key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to ++the next field (@key{RET} to the next row) and creates new table rows ++at the end of the table or before horizontal lines. The indentation ++of the table is set by the first line. Any line starting with ++@samp{|-} is considered as a horizontal separator line and will be ++expanded on the next re-align to span the whole table width. So, to ++create the above table, you would only type ++ ++@example ++|Name|Phone|Age| ++|- ++@end example ++ ++@noindent and then press @key{TAB} to align the table and start filling in ++fields. Even faster would be to type @code{|Name|Phone|Age} followed by ++@kbd{C-c @key{RET}}. ++ ++When typing text into a field, Org treats @key{DEL}, ++@key{Backspace}, and all character keys in a special way, so that ++inserting and deleting avoids shifting other fields. Also, when ++typing @emph{immediately after the cursor was moved into a new field ++with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the ++field is automatically made blank. If this behavior is too ++unpredictable for you, configure the variables ++@code{org-enable-table-editor} and @code{org-table-auto-blank-field}. ++ ++@table @kbd ++@tsubheading{Creation and conversion} ++@kindex C-c | ++@item C-c | ++Convert the active region to table. If every line contains at least one ++TAB character, the function assumes that the material is tab separated. ++If every line contains a comma, comma-separated values (CSV) are assumed. ++If not, lines are split at whitespace into fields. You can use a prefix ++argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u ++C-u} forces TAB, and a numeric argument N indicates that at least N ++consecutive spaces, or alternatively a TAB will be the separator. ++@* ++If there is no active region, this command creates an empty Org ++table. But it's easier just to start typing, like ++@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}. ++ ++@tsubheading{Re-aligning and field motion} ++@kindex C-c C-c ++@item C-c C-c ++Re-align the table without moving the cursor. ++@c ++@kindex @key{TAB} ++@item @key{TAB} ++Re-align the table, move to the next field. Creates a new row if ++necessary. ++@c ++@kindex S-@key{TAB} ++@item S-@key{TAB} ++Re-align, move to previous field. ++@c ++@kindex @key{RET} ++@item @key{RET} ++Re-align the table and move down to next row. Creates a new row if ++necessary. At the beginning or end of a line, @key{RET} still does ++NEWLINE, so it can be used to split a table. ++ ++@tsubheading{Column and row editing} ++@kindex M-@key{left} ++@kindex M-@key{right} ++@item M-@key{left} ++@itemx M-@key{right} ++Move the current column left/right. ++@c ++@kindex M-S-@key{left} ++@item M-S-@key{left} ++Kill the current column. ++@c ++@kindex M-S-@key{right} ++@item M-S-@key{right} ++Insert a new column to the left of the cursor position. ++@c ++@kindex M-@key{up} ++@kindex M-@key{down} ++@item M-@key{up} ++@itemx M-@key{down} ++Move the current row up/down. ++@c ++@kindex M-S-@key{up} ++@item M-S-@key{up} ++Kill the current row or horizontal line. ++@c ++@kindex M-S-@key{down} ++@item M-S-@key{down} ++Insert a new row above the current row. With a prefix argument, the line is ++created below the current one. ++@c ++@kindex C-c - ++@item C-c - ++Insert a horizontal line below current row. With a prefix argument, the line ++is created above the current line. ++@c ++@kindex C-c @key{RET} ++@item C-c @key{RET} ++Insert a horizontal line below current row, and move the cursor into the row ++below that line. ++@c ++@kindex C-c ^ ++@item C-c ^ ++Sort the table lines in the region. The position of point indicates the ++column to be used for sorting, and the range of lines is the range ++between the nearest horizontal separator lines, or the entire table. If ++point is before the first column, you will be prompted for the sorting ++column. If there is an active region, the mark specifies the first line ++and the sorting column, while point should be in the last line to be ++included into the sorting. The command prompts for the sorting type ++(alphabetically, numerically, or by time). When called with a prefix ++argument, alphabetic sorting will be case-sensitive. ++ ++@tsubheading{Regions} ++@kindex C-c C-x M-w ++@item C-c C-x M-w ++Copy a rectangular region from a table to a special clipboard. Point ++and mark determine edge fields of the rectangle. The process ignores ++horizontal separator lines. ++@c ++@kindex C-c C-x C-w ++@item C-c C-x C-w ++Copy a rectangular region from a table to a special clipboard, and ++blank all fields in the rectangle. So this is the ``cut'' operation. ++@c ++@kindex C-c C-x C-y ++@item C-c C-x C-y ++Paste a rectangular region into a table. ++The upper left corner ends up in the current field. All involved fields ++will be overwritten. If the rectangle does not fit into the present table, ++the table is enlarged as needed. The process ignores horizontal separator ++lines. ++@c ++@kindex M-@key{RET} ++@itemx M-@kbd{RET} ++Wrap several fields in a column like a paragraph. If there is an active ++region, and both point and mark are in the same column, the text in the ++column is wrapped to minimum width for the given number of lines. A numeric ++prefix argument may be used to change the number of desired lines. If there ++is no region, the current field is split at the cursor position and the text ++fragment to the right of the cursor is prepended to the field one line ++down. If there is no region, but you specify a prefix argument, the current ++field is made blank, and the content is appended to the field above. ++ ++@tsubheading{Calculations} ++@cindex formula, in tables ++@cindex calculations, in tables ++@cindex region, active ++@cindex active region ++@cindex Transient mark mode ++@kindex C-c + ++@item C-c + ++Sum the numbers in the current column, or in the rectangle defined by ++the active region. The result is shown in the echo area and can ++be inserted with @kbd{C-y}. ++@c ++@kindex S-@key{RET} ++@item S-@key{RET} ++When current field is empty, copy from first non-empty field above. When not ++empty, copy current field down to next row and move cursor along with it. ++Depending on the variable @code{org-table-copy-increment}, integer field ++values will be incremented during copy. Integers that are too large will not ++be incremented. Also, a @code{0} prefix argument temporarily disables the ++increment. This key is also used by CUA mode (@pxref{Cooperation}). ++ ++@tsubheading{Miscellaneous} ++@kindex C-c ` ++@item C-c ` ++Edit the current field in a separate window. This is useful for fields ++that are not fully visible (@pxref{Narrow columns}). When called with a ++@kbd{C-u} prefix, just make the full field visible, so that it can be ++edited in place. ++@c ++@item M-x org-table-import ++Import a file as a table. The table should be TAB- or whitespace ++separated. Useful, for example, to import a spreadsheet table or data ++from a database, because these programs generally can write ++TAB-separated text files. This command works by inserting the file into ++the buffer and then converting the region to a table. Any prefix ++argument is passed on to the converter, which uses it to determine the ++separator. ++@item C-c | ++Tables can also be imported by pasting tabular text into the Org ++buffer, selecting the pasted text with @kbd{C-x C-x} and then using the ++@kbd{C-c |} command (see above under @i{Creation and conversion}). ++@c ++@item M-x org-table-export ++Export the table, by default as a TAB-separated file. Useful for data ++exchange with, for example, spreadsheet or database programs. The format ++used to export the file can be configured in the variable ++@code{org-table-export-default-format}. You may also use properties ++@code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file ++name and the format for table export in a subtree. Org supports quite ++general formats for exported tables. The exporter format is the same as the ++format used by Orgtbl radio tables, see @ref{Translator functions} for a ++detailed description. ++@end table ++ ++If you don't like the automatic table editor because it gets in your ++way on lines which you would like to start with @samp{|}, you can turn ++it off with ++ ++@lisp ++(setq org-enable-table-editor nil) ++@end lisp ++ ++@noindent Then the only table command that still works is ++@kbd{C-c C-c} to do a manual re-align. ++ ++@node Narrow columns, Column groups, Built-in table editor, Tables ++@section Narrow columns ++@cindex narrow columns in tables ++ ++The width of columns is automatically determined by the table editor. ++Sometimes a single field or a few fields need to carry more text, ++leading to inconveniently wide columns. To limit@footnote{This feature ++does not work on XEmacs.} the width of a column, one field anywhere in ++the column may contain just the string @samp{} where @samp{N} is an ++integer specifying the width of the column in characters. The next ++re-align will then set the width of this column to no more than this ++value. ++ ++@example ++@group ++|---+------------------------------| |---+--------| ++| | | | | <6> | ++| 1 | one | | 1 | one | ++| 2 | two | ----\ | 2 | two | ++| 3 | This is a long chunk of text | ----/ | 3 | This=> | ++| 4 | four | | 4 | four | ++|---+------------------------------| |---+--------| ++@end group ++@end example ++ ++@noindent ++Fields that are wider become clipped and end in the string @samp{=>}. ++Note that the full text is still in the buffer, it is only invisible. ++To see the full text, hold the mouse over the field - a tool-tip window ++will show the full content. To edit such a field, use the command ++@kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will ++open a new window with the full field. Edit it and finish with @kbd{C-c ++C-c}. ++ ++When visiting a file containing a table with narrowed columns, the ++necessary character hiding has not yet happened, and the table needs to ++be aligned before it looks nice. Setting the option ++@code{org-startup-align-all-tables} will realign all tables in a file ++upon visiting, but also slow down startup. You can also set this option ++on a per-file basis with: ++ ++@example ++#+STARTUP: align ++#+STARTUP: noalign ++@end example ++ ++@node Column groups, Orgtbl mode, Narrow columns, Tables ++@section Column groups ++@cindex grouping columns in tables ++ ++When Org exports tables, it does so by default without vertical ++lines because that is visually more satisfying in general. Occasionally ++however, vertical lines can be useful to structure a table into groups ++of columns, much like horizontal lines can do for groups of rows. In ++order to specify column groups, you can use a special row where the ++first field contains only @samp{/}. The further fields can either ++contain @samp{<} to indicate that this column should start a group, ++@samp{>} to indicate the end of a column, or @samp{<>} to make a column ++a group of its own. Boundaries between column groups will upon export be ++marked with vertical lines. Here is an example: ++ ++@example ++| | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | ++|---+----+-----+-----+-----+---------+------------| ++| / | <> | < | | > | < | > | ++| # | 1 | 1 | 1 | 1 | 1 | 1 | ++| # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 | ++| # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 | ++|---+----+-----+-----+-----+---------+------------| ++#+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))) ++@end example ++ ++It is also sufficient to just insert the column group starters after ++every vertical line you'd like to have: ++ ++@example ++| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | ++|----+-----+-----+-----+---------+------------| ++| / | < | | | < | | ++@end example ++ ++@node Orgtbl mode, The spreadsheet, Column groups, Tables ++@section The Orgtbl minor mode ++@cindex Orgtbl mode ++@cindex minor mode for tables ++ ++If you like the intuitive way the Org table editor works, you ++might also want to use it in other modes like Text mode or Mail mode. ++The minor mode Orgtbl mode makes this possible. You can always toggle ++the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for ++example in mail mode, use ++ ++@lisp ++(add-hook 'mail-mode-hook 'turn-on-orgtbl) ++@end lisp ++ ++Furthermore, with some special setup, it is possible to maintain tables ++in arbitrary syntax with Orgtbl mode. For example, it is possible to ++construct La@TeX{} tables with the underlying ease and power of ++Orgtbl mode, including spreadsheet capabilities. For details, see ++@ref{Tables in arbitrary syntax}. ++ ++@node The spreadsheet, Org Plot, Orgtbl mode, Tables ++@section The spreadsheet ++@cindex calculations, in tables ++@cindex spreadsheet capabilities ++@cindex @file{calc} package ++ ++The table editor makes use of the Emacs @file{calc} package to implement ++spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to ++derive fields from other fields. While fully featured, Org's ++implementation is not identical to other spreadsheets. For example, ++Org knows the concept of a @emph{column formula} that will be ++applied to all non-header fields in a column without having to copy the ++formula to each relevant field. ++ ++@menu ++* References:: How to refer to another field or range ++* Formula syntax for Calc:: Using Calc to compute stuff ++* Formula syntax for Lisp:: Writing formulas in Emacs Lisp ++* Field formulas:: Formulas valid for a single field ++* Column formulas:: Formulas valid for an entire column ++* Editing and debugging formulas:: Fixing formulas ++* Updating the table:: Recomputing all dependent fields ++* Advanced features:: Field names, parameters and automatic recalc ++@end menu ++ ++@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet ++@subsection References ++@cindex references ++ ++To compute fields in the table from other fields, formulas must ++reference other fields or ranges. In Org, fields can be referenced ++by name, by absolute coordinates, and by relative coordinates. To find ++out what the coordinates of a field are, press @kbd{C-c ?} in that ++field, or press @kbd{C-c @}} to toggle the display of a grid. ++ ++@subsubheading Field references ++@cindex field references ++@cindex references, to fields ++ ++Formulas can reference the value of another field in two ways. Like in ++any other spreadsheet, you may reference fields with a letter/number ++combination like @code{B3}, meaning the 2nd field in the 3rd row. ++@c Such references are always fixed to that field, they don't change ++@c when you copy and paste a formula to a different field. So ++@c Org's @code{B3} behaves like @code{$B$3} in other spreadsheets. ++ ++@noindent ++Org also uses another, more general operator that looks like this: ++@example ++@@row$column ++@end example ++ ++@noindent ++Column references can be absolute like @samp{1}, @samp{2},...@samp{N}, ++or relative to the current column like @samp{+1} or @samp{-2}. ++ ++The row specification only counts data lines and ignores horizontal ++separator lines (hlines). You can use absolute row numbers ++@samp{1}...@samp{N}, and row numbers relative to the current row like ++@samp{+3} or @samp{-1}. Or specify the row relative to one of the ++hlines: @samp{I} refers to the first hline@footnote{Note that only ++hlines are counted that @emph{separate} table lines. If the table ++starts with a hline above the header, it does not count.}, @samp{II} to ++the second etc. @samp{-I} refers to the first such line above the ++current line, @samp{+I} to the first such line below the current line. ++You can also write @samp{III+2} which is the second data line after the ++third hline in the table. Relative row numbers like @samp{-3} will not ++cross hlines if the current line is too close to the hline. Instead, ++the value directly at the hline is used. ++ ++@samp{0} refers to the current row and column. Also, if you omit ++either the column or the row part of the reference, the current ++row/column is implied. ++ ++Org's references with @emph{unsigned} numbers are fixed references ++in the sense that if you use the same reference in the formula for two ++different fields, the same field will be referenced each time. ++Org's references with @emph{signed} numbers are floating ++references because the same reference operator can reference different ++fields depending on the field being calculated by the formula. ++ ++As a special case references like @samp{$LR5} and @samp{$LR12} can be used to ++refer in a stable way to the 5th and 12th field in the last row of the ++table. ++ ++Here are a few examples: ++ ++@example ++@@2$3 @r{2nd row, 3rd column} ++C2 @r{same as previous} ++$5 @r{column 5 in the current row} ++E& @r{same as previous} ++@@2 @r{current column, row 2} ++@@-1$-3 @r{the field one row up, three columns to the left} ++@@-I$2 @r{field just under hline above current row, column 2} ++@end example ++ ++@subsubheading Range references ++@cindex range references ++@cindex references, to ranges ++ ++You may reference a rectangular range of fields by specifying two field ++references connected by two dots @samp{..}. If both fields are in the ++current row, you may simply use @samp{$2..$7}, but if at least one field ++is in a different row, you need to use the general @code{@@row$column} ++format at least for the first field (i.e the reference must start with ++@samp{@@} in order to be interpreted correctly). Examples: ++ ++@example ++$1..$3 @r{First three fields in the current row.} ++$P..$Q @r{Range, using column names (see under Advanced)} ++@@2$1..@@4$3 @r{6 fields between these two fields.} ++A2..C4 @r{Same as above.} ++@@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row} ++@end example ++ ++@noindent Range references return a vector of values that can be fed ++into Calc vector functions. Empty fields in ranges are normally ++suppressed, so that the vector contains only the non-empty fields (but ++see the @samp{E} mode switch below). If there are no non-empty fields, ++@samp{[0]} is returned to avoid syntax errors in formulas. ++ ++@subsubheading Named references ++@cindex named references ++@cindex references, named ++@cindex name, of column or field ++@cindex constants, in calculations ++ ++@samp{$name} is interpreted as the name of a column, parameter or ++constant. Constants are defined globally through the variable ++@code{org-table-formula-constants}, and locally (for the file) through a ++line like ++ ++@example ++#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 ++@end example ++ ++@noindent ++Also properties (@pxref{Properties and Columns}) can be used as ++constants in table formulas: For a property @samp{:Xyz:} use the name ++@samp{$PROP_Xyz}, and the property will be searched in the current ++outline entry and in the hierarchy above it. If you have the ++@file{constants.el} package, it will also be used to resolve constants, ++including natural constants like @samp{$h} for Planck's constant, and ++units like @samp{$km} for kilometers@footnote{@file{Constant.el} can ++supply the values of constants in two different unit systems, @code{SI} ++and @code{cgs}. Which one is used depends on the value of the variable ++@code{constants-unit-system}. You can use the @code{#+STARTUP} options ++@code{constSI} and @code{constcgs} to set this value for the current ++buffer.}. Column names and parameters can be specified in special table ++lines. These are described below, see @ref{Advanced features}. All ++names must start with a letter, and further consist of letters and ++numbers. ++ ++@subsubheading Remote references ++@cindex remote references ++@cindex references, remote ++@cindex references, to a different table ++@cindex name, of column or field ++@cindex constants, in calculations ++ ++You may also reference constants, fields and ranges from a different table, ++either in the current file or even in a different file. The syntax is ++ ++@example ++remote(NAME-OR-ID,REF) ++@end example ++ ++@noindent ++where NAME can be the name of a table in the current file as set by a ++@code{#+TBLNAME: NAME} line before the table. It can also be the ID of an ++entry, even in a different file, and the reference then refers to the first ++table in that entry. REF is an absolute field or range reference as ++described above, valid in the referenced table. ++ ++@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet ++@subsection Formula syntax for Calc ++@cindex formula syntax, Calc ++@cindex syntax, of formulas ++ ++A formula can be any algebraic expression understood by the Emacs ++@file{Calc} package. @b{Note that @file{calc} has the ++non-standard convention that @samp{/} has lower precedence than ++@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before ++evaluation by @code{calc-eval} (@pxref{Calling Calc from ++Your Programs,calc-eval,Calling Calc from Your Lisp Programs,Calc,GNU ++Emacs Calc Manual}), ++@c FIXME: The link to the Calc manual in HTML does not work. ++variable substitution takes place according to the rules described above. ++@cindex vectors, in table calculations ++The range vectors can be directly fed into the Calc vector functions ++like @samp{vmean} and @samp{vsum}. ++ ++@cindex format specifier ++@cindex mode, for @file{calc} ++A formula can contain an optional mode string after a semicolon. This ++string consists of flags to influence Calc and other modes during ++execution. By default, Org uses the standard Calc modes (precision ++12, angular units degrees, fraction and symbolic modes off). The display ++format, however, has been changed to @code{(float 5)} to keep tables ++compact. The default settings can be configured using the variable ++@code{org-calc-default-modes}. ++ ++@example ++p20 @r{switch the internal precision to 20 digits} ++n3 s3 e2 f4 @r{normal, scientific, engineering, or fixed display format} ++D R @r{angle modes: degrees, radians} ++F S @r{fraction and symbolic modes} ++N @r{interpret all fields as numbers, use 0 for non-numbers} ++T @r{force text interpretation} ++E @r{keep empty fields in ranges} ++@end example ++ ++@noindent ++In addition, you may provide a @code{printf} format specifier to ++reformat the final result. A few examples: ++ ++@example ++$1+$2 @r{Sum of first and second field} ++$1+$2;%.2f @r{Same, format result to two decimals} ++exp($2)+exp($1) @r{Math functions can be used} ++$0;%.1f @r{Reformat current cell to 1 decimal} ++($3-32)*5/9 @r{Degrees F -> C conversion} ++$c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}} ++tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1} ++sin($1);Dp3%.1e @r{Same, but use printf specifier for display} ++vmean($2..$7) @r{Compute column range mean, using vector function} ++vmean($2..$7);EN @r{Same, but treat empty fields as 0} ++taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree} ++@end example ++ ++Calc also contains a complete set of logical operations. For example ++ ++@example ++if($1<20,teen,string("")) @r{``teen'' if age $1 less than 20, else empty} ++@end example ++ ++@node Formula syntax for Lisp, Field formulas, Formula syntax for Calc, The spreadsheet ++@subsection Emacs Lisp forms as formulas ++@cindex Lisp forms, as table formulas ++ ++It is also possible to write a formula in Emacs Lisp; this can be useful ++for string manipulation and control structures, if Calc's ++functionality is not enough. If a formula starts with a single quote ++followed by an opening parenthesis, then it is evaluated as a lisp form. ++The evaluation should return either a string or a number. Just as with ++@file{calc} formulas, you can specify modes and a printf format after a ++semicolon. With Emacs Lisp forms, you need to be conscious about the way ++field references are interpolated into the form. By default, a ++reference will be interpolated as a Lisp string (in double quotes) ++containing the field. If you provide the @samp{N} mode switch, all ++referenced elements will be numbers (non-number fields will be zero) and ++interpolated as Lisp numbers, without quotes. If you provide the ++@samp{L} flag, all fields will be interpolated literally, without quotes. ++I.e., if you want a reference to be interpreted as a string by the Lisp ++form, enclose the reference operator itself in double quotes, like ++@code{"$3"}. Ranges are inserted as space-separated fields, so you can ++embed them in list or vector syntax. A few examples, note how the ++@samp{N} mode is used when we do computations in lisp. ++ ++@example ++@r{Swap the first two characters of the content of column 1} ++ '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) ++@r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}} ++ '(+ $1 $2);N ++@r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}} ++ '(apply '+ '($1..$4));N ++@end example ++ ++@node Field formulas, Column formulas, Formula syntax for Lisp, The spreadsheet ++@subsection Field formulas ++@cindex field formula ++@cindex formula, for individual table field ++ ++To assign a formula to a particular field, type it directly into the ++field, preceded by @samp{:=}, for example @samp{:=$1+$2}. When you ++press @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in ++the field, the formula will be stored as the formula for this field, ++evaluated, and the current field replaced with the result. ++ ++Formulas are stored in a special line starting with @samp{#+TBLFM:} ++directly below the table. If you typed the equation in the 4th field of ++the 3rd data line in the table, the formula will look like ++@samp{@@3$4=$1+$2}. When inserting/deleting/swapping column and rows ++with the appropriate commands, @i{absolute references} (but not relative ++ones) in stored formulas are modified in order to still reference the ++same field. Of cause this is not true if you edit the table structure ++with normal editing commands - then you must fix the equations yourself. ++The left hand side of a formula may also be a named field (@pxref{Advanced ++features}), or a last-row reference like @samp{$LR3}. ++ ++Instead of typing an equation into the field, you may also use the ++following command ++ ++@table @kbd ++@kindex C-u C-c = ++@item C-u C-c = ++Install a new formula for the current field. The command prompts for a ++formula, with default taken from the @samp{#+TBLFM:} line, applies ++it to the current field and stores it. ++@end table ++ ++@node Column formulas, Editing and debugging formulas, Field formulas, The spreadsheet ++@subsection Column formulas ++@cindex column formula ++@cindex formula, for table column ++ ++Often in a table, the same formula should be used for all fields in a ++particular column. Instead of having to copy the formula to all fields ++in that column, Org allows to assign a single formula to an entire ++column. If the table contains horizontal separator hlines, everything ++before the first such line is considered part of the table @emph{header} ++and will not be modified by column formulas. ++ ++To assign a formula to a column, type it directly into any field in the ++column, preceded by an equal sign, like @samp{=$1+$2}. When you press ++@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the ++field, the formula will be stored as the formula for the current column, ++evaluated and the current field replaced with the result. If the field ++contains only @samp{=}, the previously stored formula for this column is ++used. For each column, Org will only remember the most recently ++used formula. In the @samp{TBLFM:} line, column formulas will look like ++@samp{$4=$1+$2}. ++ ++Instead of typing an equation into the field, you may also use the ++following command: ++ ++@table @kbd ++@kindex C-c = ++@item C-c = ++Install a new formula for the current column and replace current field with ++the result of the formula. The command prompts for a formula, with default ++taken from the @samp{#+TBLFM} line, applies it to the current field and ++stores it. With a numeric prefix argument(e.g. @kbd{C-5 C-c =}) the command ++will apply it to that many consecutive fields in the current column. ++@end table ++ ++@node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet ++@subsection Editing and debugging formulas ++@cindex formula editing ++@cindex editing, of table formulas ++ ++You can edit individual formulas in the minibuffer or directly in the ++field. Org can also prepare a special buffer with all active ++formulas of a table. When offering a formula for editing, Org ++converts references to the standard format (like @code{B3} or @code{D&}) ++if possible. If you prefer to only work with the internal format (like ++@code{@@3$2} or @code{$4}), configure the variable ++@code{org-table-use-standard-references}. ++ ++@table @kbd ++@kindex C-c = ++@kindex C-u C-c = ++@item C-c = ++@itemx C-u C-c = ++Edit the formula associated with the current column/field in the ++minibuffer. See @ref{Column formulas} and @ref{Field formulas}. ++@kindex C-u C-u C-c = ++@item C-u C-u C-c = ++Re-insert the active formula (either a ++field formula, or a column formula) into the current field, so that you ++can edit it directly in the field. The advantage over editing in the ++minibuffer is that you can use the command @kbd{C-c ?}. ++@kindex C-c ? ++@item C-c ? ++While editing a formula in a table field, highlight the field(s) ++referenced by the reference at the cursor position in the formula. ++@kindex C-c @} ++@item C-c @} ++Toggle the display of row and column numbers for a table, using ++overlays. These are updated each time the table is aligned, you can ++force it with @kbd{C-c C-c}. ++@kindex C-c @{ ++@item C-c @{ ++Toggle the formula debugger on and off. See below. ++@kindex C-c ' ++@item C-c ' ++Edit all formulas for the current table in a special buffer, where the ++formulas will be displayed one per line. If the current field has an ++active formula, the cursor in the formula editor will mark it. ++While inside the special buffer, Org will automatically highlight ++any field or range reference at the cursor position. You may edit, ++remove and add formulas, and use the following commands: ++@table @kbd ++@kindex C-c C-c ++@kindex C-x C-s ++@item C-c C-c ++@itemx C-x C-s ++Exit the formula editor and store the modified formulas. With @kbd{C-u} ++prefix, also apply the new formulas to the entire table. ++@kindex C-c C-q ++@item C-c C-q ++Exit the formula editor without installing changes. ++@kindex C-c C-r ++@item C-c C-r ++Toggle all references in the formula editor between standard (like ++@code{B3}) and internal (like @code{@@3$2}). ++@kindex @key{TAB} ++@item @key{TAB} ++Pretty-print or indent lisp formula at point. When in a line containing ++a lisp formula, format the formula according to Emacs Lisp rules. ++Another @key{TAB} collapses the formula back again. In the open ++formula, @key{TAB} re-indents just like in Emacs lisp mode. ++@kindex M-@key{TAB} ++@item M-@key{TAB} ++Complete Lisp symbols, just like in Emacs lisp mode. ++@kindex S-@key{up} ++@kindex S-@key{down} ++@kindex S-@key{left} ++@kindex S-@key{right} ++@item S-@key{up}/@key{down}/@key{left}/@key{right} ++Shift the reference at point. For example, if the reference is ++@code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}. ++This also works for relative references, and for hline references. ++@kindex M-S-@key{up} ++@kindex M-S-@key{down} ++@item M-S-@key{up}/@key{down} ++Move the test line for column formulas in the Org buffer up and ++down. ++@kindex M-@key{up} ++@kindex M-@key{down} ++@item M-@key{up}/@key{down} ++Scroll the window displaying the table. ++@kindex C-c @} ++@item C-c @} ++Turn the coordinate grid in the table on and off. ++@end table ++@end table ++ ++Making a table field blank does not remove the formula associated with ++the field, because that is stored in a different line (the @samp{TBLFM} ++line) - during the next recalculation the field will be filled again. ++To remove a formula from a field, you have to give an empty reply when ++prompted for the formula, or to edit the @samp{#+TBLFM} line. ++ ++@kindex C-c C-c ++You may edit the @samp{#+TBLFM} directly and re-apply the changed ++equations with @kbd{C-c C-c} in that line, or with the normal ++recalculation commands in the table. ++ ++@subsubheading Debugging formulas ++@cindex formula debugging ++@cindex debugging, of table formulas ++When the evaluation of a formula leads to an error, the field content ++becomes the string @samp{#ERROR}. If you would like see what is going ++on during variable substitution and calculation in order to find a bug, ++turn on formula debugging in the @code{Tbl} menu and repeat the ++calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a ++field. Detailed information will be displayed. ++ ++@node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet ++@subsection Updating the table ++@cindex recomputing table fields ++@cindex updating, table ++ ++Recalculation of a table is normally not automatic, but needs to be ++triggered by a command. See @ref{Advanced features} for a way to make ++recalculation at least semi-automatically. ++ ++In order to recalculate a line of a table or the entire table, use the ++following commands: ++ ++@table @kbd ++@kindex C-c * ++@item C-c * ++Recalculate the current row by first applying the stored column formulas ++from left to right, and all field formulas in the current row. ++@c ++@kindex C-u C-c * ++@item C-u C-c * ++@kindex C-u C-c C-c ++@itemx C-u C-c C-c ++Recompute the entire table, line by line. Any lines before the first ++hline are left alone, assuming that these are part of the table header. ++@c ++@kindex C-u C-u C-c * ++@kindex C-u C-u C-c C-c ++@item C-u C-u C-c * ++@itemx C-u C-u C-c C-c ++Iterate the table by recomputing it until no further changes occur. ++This may be necessary if some computed fields use the value of other ++fields that are computed @i{later} in the calculation sequence. ++@end table ++ ++@node Advanced features, , Updating the table, The spreadsheet ++@subsection Advanced features ++ ++If you want the recalculation of fields to happen automatically, or if ++you want to be able to assign @i{names} to fields and columns, you need ++to reserve the first column of the table for special marking characters. ++@table @kbd ++@kindex C-# ++@item C-# ++Rotate the calculation mark in first column through the states @samp{}, ++@samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region, ++change all marks in the region. ++@end table ++ ++Here is an example of a table that collects exam results of students and ++makes use of these features: ++ ++@example ++@group ++|---+---------+--------+--------+--------+-------+------| ++| | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note | ++|---+---------+--------+--------+--------+-------+------| ++| ! | | P1 | P2 | P3 | Tot | | ++| # | Maximum | 10 | 15 | 25 | 50 | 10.0 | ++| ^ | | m1 | m2 | m3 | mt | | ++|---+---------+--------+--------+--------+-------+------| ++| # | Peter | 10 | 8 | 23 | 41 | 8.2 | ++| # | Sam | 2 | 4 | 3 | 9 | 1.8 | ++|---+---------+--------+--------+--------+-------+------| ++| | Average | | | | 29.7 | | ++| ^ | | | | | at | | ++| $ | max=50 | | | | | | ++|---+---------+--------+--------+--------+-------+------| ++#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f ++@end group ++@end example ++ ++@noindent @b{Important}: Please note that for these special tables, ++recalculating the table with @kbd{C-u C-c *} will only affect rows that ++are marked @samp{#} or @samp{*}, and fields that have a formula assigned ++to the field itself. The column formulas are not applied in rows with ++empty first field. ++ ++@cindex marking characters, tables ++The marking characters have the following meaning: ++@table @samp ++@item ! ++The fields in this line define names for the columns, so that you may ++refer to a column as @samp{$Tot} instead of @samp{$6}. ++@item ^ ++This row defines names for the fields @emph{above} the row. With such ++a definition, any formula in the table may use @samp{$m1} to refer to ++the value @samp{10}. Also, if you assign a formula to a names field, it ++will be stored as @samp{$name=...}. ++@item _ ++Similar to @samp{^}, but defines names for the fields in the row ++@emph{below}. ++@item $ ++Fields in this row can define @emph{parameters} for formulas. For ++example, if a field in a @samp{$} row contains @samp{max=50}, then ++formulas in this table can refer to the value 50 using @samp{$max}. ++Parameters work exactly like constants, only that they can be defined on ++a per-table basis. ++@item # ++Fields in this row are automatically recalculated when pressing ++@key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row ++is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked ++lines will be left alone by this command. ++@item * ++Selects this line for global recalculation with @kbd{C-u C-c *}, but ++not for automatic recalculation. Use this when automatic ++recalculation slows down editing too much. ++@item ++Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}. ++All lines that should be recalculated should be marked with @samp{#} ++or @samp{*}. ++@item / ++Do not export this line. Useful for lines that contain the narrowing ++@samp{} markers. ++@end table ++ ++Finally, just to whet your appetite on what can be done with the ++fantastic @file{calc} package, here is a table that computes the Taylor ++series of degree @code{n} at location @code{x} for a couple of ++functions. ++ ++@example ++@group ++|---+-------------+---+-----+--------------------------------------| ++| | Func | n | x | Result | ++|---+-------------+---+-----+--------------------------------------| ++| # | exp(x) | 1 | x | 1 + x | ++| # | exp(x) | 2 | x | 1 + x + x^2 / 2 | ++| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 | ++| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 | ++| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 | ++| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 | ++|---+-------------+---+-----+--------------------------------------| ++#+TBLFM: $5=taylor($2,$4,$3);n3 ++@end group ++@end example ++ ++@page ++@node Org Plot, , The spreadsheet, Tables ++@section Org Plot ++@cindex graph, in tables ++@cindex plot tables using gnuplot ++ ++Org Plot can produce 2D and 3D graphs of information stored in org tables ++using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode} ++@uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}. To see ++this in action ensure that you have both Gnuplot and Gnuplot-mode installed ++on your system, then call @code{org-plot/gnuplot} on the following table. ++ ++@example ++@group ++#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]" ++| Sede | Max cites | H-index | ++|-----------+-----------+---------| ++| Chile | 257.72 | 21.39 | ++| Leeds | 165.77 | 19.68 | ++| Sao Paolo | 71.00 | 11.50 | ++| Stockholm | 134.19 | 14.33 | ++| Morelia | 257.56 | 17.67 | ++@end group ++@end example ++ ++Notice that Org Plot is smart enough to apply the tables headers as labels. ++Further control over the labels, type, content, and appearance of plots can ++be exercised through the @code{#+Plot:} lines preceding a table. See below ++for a complete list of Org plot options. For more information and examples ++see the org-plot tutorial at ++@uref{http://orgmode.org/worg/org-tutorials/org-plot.php}. ++ ++@subsubheading Plot Options ++ ++@table @code ++@item set ++Specify any @file{gnuplot} option to be set when graphing. ++ ++@item title ++Specify the title of the plot. ++ ++@item ind ++Specify which column of the table to use as the @code{x} axis. ++ ++@item deps ++Specify the columns to graph as a lisp style list, surrounded by parenthesis ++and separated by spaces for example @code{dep:(3 4)} to graph the third and ++fourth columns (defaults to graphing all other columns aside from the ind ++column). ++ ++@item type ++Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}. ++ ++@item with ++Specify a @code{with} option to be inserted for every col being plotted ++(e.g. @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...). ++Defaults to @code{lines}. ++ ++@item file ++If you want to plot to a file specify the @code{"path/to/desired/output-file"}. ++ ++@item labels ++List of labels to be used for the deps (defaults to column headers if they ++exist). ++ ++@item line ++Specify an entire line to be inserted in the gnuplot script. ++ ++@item map ++When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a ++flat mapping rather than a @code{3d} slope. ++ ++@item timefmt ++Specify format of org-mode timestamps as they will be parsed by gnuplot. ++Defaults to @samp{%Y-%m-%d-%H:%M:%S}. ++ ++@item script ++If you want total control you can specify a script file (place the file name ++between double quotes) which will be used to plot. Before plotting, every ++instance of @code{$datafile} in the specified script will be replaced with ++the path to the generated data file. Note even if you set this option you ++may still want to specify the plot type, as that can impact the content of ++the data file. ++@end table ++ ++@node Hyperlinks, TODO Items, Tables, Top ++@chapter Hyperlinks ++@cindex hyperlinks ++ ++Like HTML, Org provides links inside a file, external links to ++other files, Usenet articles, emails, and much more. ++ ++@menu ++* Link format:: How links in Org are formatted ++* Internal links:: Links to other places in the current file ++* External links:: URL-like links to the world ++* Handling links:: Creating, inserting and following ++* Using links outside Org:: Linking from my C source code? ++* Link abbreviations:: Shortcuts for writing complex links ++* Search options:: Linking to a specific location ++* Custom searches:: When the default search is not enough ++@end menu ++ ++@node Link format, Internal links, Hyperlinks, Hyperlinks ++@section Link format ++@cindex link format ++@cindex format, of links ++ ++Org will recognize plain URL-like links and activate them as ++clickable links. The general link format, however, looks like this: ++ ++@example ++[[link][description]] @r{or alternatively} [[link]] ++@end example ++ ++Once a link in the buffer is complete (all brackets present), Org ++will change the display so that @samp{description} is displayed instead ++of @samp{[[link][description]]} and @samp{link} is displayed instead of ++@samp{[[link]]}. Links will be highlighted in the face @code{org-link}, ++which by default is an underlined face. You can directly edit the ++visible part of a link. Note that this can be either the @samp{link} ++part (if there is no description) or the @samp{description} part. To ++edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the ++cursor on the link. ++ ++If you place the cursor at the beginning or just behind the end of the ++displayed text and press @key{BACKSPACE}, you will remove the ++(invisible) bracket at that location. This makes the link incomplete ++and the internals are again displayed as plain text. Inserting the ++missing bracket hides the link internals again. To show the ++internal structure of all links, use the menu entry ++@code{Org->Hyperlinks->Literal links}. ++ ++@node Internal links, External links, Link format, Hyperlinks ++@section Internal links ++@cindex internal links ++@cindex links, internal ++@cindex targets, for links ++ ++If the link does not look like a URL, it is considered to be internal in ++the current file. Links such as @samp{[[My Target]]} or @samp{[[My ++Target][Find my target]]} lead to a text search in the current file. ++The link can be followed with @kbd{C-c C-o} when the cursor is on the ++link, or with a mouse click (@pxref{Handling links}). The preferred ++match for such a link is a dedicated target: the same string in double ++angular brackets. Targets may be located anywhere; sometimes it is ++convenient to put them into a comment line. For example ++ ++@example ++# <> ++@end example ++ ++@noindent In HTML export (@pxref{HTML export}), such targets will become ++named anchors for direct access through @samp{http} links@footnote{Note that ++text before the first headline is usually not exported, so the first such ++target should be after the first headline, or in the line directly before the ++first headline.}. ++ ++If no dedicated target exists, Org will search for the words in the ++link. In the above example the search would be for @samp{my target}. ++Links starting with a star like @samp{*My Target} restrict the search to ++headlines. When searching, Org mode will first try an exact match, but ++then move on to more and more lenient searches. For example, the link ++@samp{[[*My Targets]]} will find any of the following: ++ ++@example ++** My targets ++** TODO my targets are bright ++** my 20 targets are ++@end example ++ ++To insert a link targeting a headline, in-buffer completion can be used. ++Just type a star followed by a few optional letters into the buffer and ++press @kbd{M-@key{TAB}}. All headlines in the current buffer will be ++offered as completions. @xref{Handling links}, for more commands ++creating links. ++ ++Following a link pushes a mark onto Org's own mark ring. You can ++return to the previous position with @kbd{C-c &}. Using this command ++several times in direct succession goes back to positions recorded ++earlier. ++ ++@menu ++* Radio targets:: Make targets trigger links in plain text ++@end menu ++ ++@node Radio targets, , Internal links, Internal links ++@subsection Radio targets ++@cindex radio targets ++@cindex targets, radio ++@cindex links, radio targets ++ ++Org can automatically turn any occurrences of certain target names ++in normal text into a link. So without explicitly creating a link, the ++text connects to the target radioing its position. Radio targets are ++enclosed by triple angular brackets. For example, a target @samp{<<>>} causes each occurrence of @samp{my target} in normal text to ++become activated as a link. The Org file is scanned automatically ++for radio targets only when the file is first loaded into Emacs. To ++update the target list during editing, press @kbd{C-c C-c} with the ++cursor on or at a target. ++ ++@node External links, Handling links, Internal links, Hyperlinks ++@section External links ++@cindex links, external ++@cindex external links ++@cindex links, external ++@cindex Gnus links ++@cindex BBDB links ++@cindex IRC links ++@cindex URL links ++@cindex file links ++@cindex VM links ++@cindex RMAIL links ++@cindex WANDERLUST links ++@cindex MH-E links ++@cindex USENET links ++@cindex SHELL links ++@cindex Info links ++@cindex elisp links ++ ++Org supports links to files, websites, Usenet and email messages, ++BBDB database entries and links to both IRC conversations and their ++logs. External links are URL-like locators. They start with a short ++identifying string followed by a colon. There can be no space after ++the colon. The following list shows examples for each link type. ++ ++@example ++http://www.astro.uva.nl/~dominik @r{on the web} ++file:/home/dominik/images/jupiter.jpg @r{file, absolute path} ++/home/dominik/images/jupiter.jpg @r{same as above} ++file:papers/last.pdf @r{file, relative path} ++./papers/last.pdf @r{same as above} ++file:projects.org @r{another org file} ++file:projects.org::some words @r{text search in org file} ++file:projects.org::*task title @r{heading search in org file} ++id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} ++news:comp.emacs @r{Usenet link} ++mailto:adent@@galaxy.net @r{Mail link} ++vm:folder @r{VM folder link} ++vm:folder#id @r{VM message link} ++vm://myself@@some.where.org/folder#id @r{VM on remote machine} ++wl:folder @r{WANDERLUST folder link} ++wl:folder#id @r{WANDERLUST message link} ++mhe:folder @r{MH-E folder link} ++mhe:folder#id @r{MH-E message link} ++rmail:folder @r{RMAIL folder link} ++rmail:folder#id @r{RMAIL message link} ++gnus:group @r{Gnus group link} ++gnus:group#id @r{Gnus article link} ++bbdb:R.*Stallman @r{BBDB link (with regexp)} ++irc:/irc.com/#emacs/bob @r{IRC link} ++shell:ls *.org @r{A shell command} ++elisp:org-agenda @r{Interactive elisp command} ++elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} ++@end example ++ ++A link should be enclosed in double brackets and may contain a ++descriptive text to be displayed instead of the URL (@pxref{Link ++format}), for example: ++ ++@example ++[[http://www.gnu.org/software/emacs/][GNU Emacs]] ++@end example ++ ++@noindent ++If the description is a file name or URL that points to an image, HTML ++export (@pxref{HTML export}) will inline the image as a clickable ++button. If there is no description at all and the link points to an ++image, ++that image will be inlined into the exported HTML file. ++ ++@cindex angular brackets, around links ++@cindex plain text external links ++Org also finds external links in the normal text and activates them ++as links. If spaces must be part of the link (for example in ++@samp{bbdb:Richard Stallman}), or if you need to remove ambiguities ++about the end of the link, enclose them in angular brackets. ++ ++@node Handling links, Using links outside Org, External links, Hyperlinks ++@section Handling links ++@cindex links, handling ++ ++Org provides methods to create a link in the correct syntax, to ++insert it into an Org file, and to follow the link. ++ ++@table @kbd ++@kindex C-c l ++@cindex storing links ++@item C-c l ++Store a link to the current location. This is a @emph{global} command (you ++must create the key binding yourself) which can be used in any buffer to ++create a link. The link will be stored for later insertion into an Org ++buffer (see below). ++ ++For Org files, if there is a @samp{<>} at the cursor, the link points ++to the target. Otherwise it points to the current headline, either by text ++(unsafe), or, if @file{org-id.el} is loaded and @code{org-link-to-org-use-id} ++is set, by ID property. ++ ++For VM, Rmail, Wanderlust, MH-E, Gnus and BBDB buffers, the link will ++indicate the current article/entry. For W3 and W3M buffers, the link goes to ++the current URL. For IRC links, if you set the variable ++@code{org-irc-link-to-logs} to non-nil then @kbd{C-c l} will store a ++@samp{file:/} style link to the relevant point in the logs for the current ++conversation. Otherwise an @samp{irc:/} style link to the user/channel/server ++under the point will be stored. ++ ++For any other files, the link will point to the file, with a search string ++(@pxref{Search options}) pointing to the contents of the current line. If ++there is an active region, the selected words will form the basis of the ++search string. If the automatically created link is not working correctly or ++accurately enough, you can write custom functions to select the search string ++and to do the search for particular file types - see @ref{Custom searches}. ++The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}. ++@c ++@kindex C-c C-l ++@cindex link completion ++@cindex completion, of links ++@cindex inserting links ++@item C-c C-l ++Insert a link. This prompts for a link to be inserted into the buffer. You ++can just type a link, using text for an internal link, or one of the link ++type prefixes mentioned in the examples above. All links stored during the ++current session are part of the history for this prompt, so you can access ++them with @key{up} and @key{down} (or @kbd{M-p/n}). Completion, on the other ++hand, will help you to insert valid link prefixes like @samp{http:} or ++@samp{ftp:}, including the prefixes defined through link abbreviations ++(@pxref{Link abbreviations}). The link will be inserted into the ++buffer@footnote{After insertion of a stored link, the link will be removed ++from the list of stored links. To keep it in the list later use, use a ++triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option ++@code{org-keep-stored-link-after-insertion}.}, along with a descriptive text. ++If some text was selected when this command is called, the selected text ++becomes the default description.@* Note that you don't have to use this ++command to insert a link. Links in Org are plain text, and you can type ++or paste them straight into the buffer. By using this command, the links are ++automatically enclosed in double brackets, and you will be asked for the ++optional descriptive text. ++@c ++@c If the link is a @samp{file:} link and ++@c the linked file is located in the same directory as the current file or ++@c a subdirectory of it, the path of the file will be inserted relative to ++@c the current directory. ++@c ++@kindex C-u C-c C-l ++@cindex file name completion ++@cindex completion, of file names ++@item C-u C-c C-l ++When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to ++a file will be inserted and you may use file name completion to select ++the name of the file. The path to the file is inserted relative to the ++directory of the current org file, if the linked file is in the current ++directory or in a sub-directory of it, or if the path is written relative ++to the current directory using @samp{../}. Otherwise an absolute path ++is used, if possible with @samp{~/} for your home directory. You can ++force an absolute path with two @kbd{C-u} prefixes. ++@c ++@item C-c C-l @r{(with cursor on existing link)} ++When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the ++link and description parts of the link. ++@c ++@cindex following links ++@kindex C-c C-o ++@kindex RET ++@item C-c C-o ++Open link at point. This will launch a web browser for URLs (using ++@command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for ++the corresponding links, and execute the command in a shell link. When the ++cursor is on an internal link, this commands runs the corresponding search. ++When the cursor is on a TAG list in a headline, it creates the corresponding ++TAGS view. If the cursor is on a time stamp, it compiles the agenda for that ++date. Furthermore, it will visit text and remote files in @samp{file:} links ++with Emacs and select a suitable application for local non-text files. ++Classification of files is based on file extension only. See option ++@code{org-file-apps}. If you want to override the default application and ++visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid ++opening in Emacs, use a @kbd{C-u C-u} prefix. ++@c ++@kindex mouse-2 ++@kindex mouse-1 ++@item mouse-2 ++@itemx mouse-1 ++On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o} ++would. Under Emacs 22, also @kbd{mouse-1} will follow a link. ++@c ++@kindex mouse-3 ++@item mouse-3 ++Like @kbd{mouse-2}, but force file links to be opened with Emacs, and ++internal links to be displayed in another window@footnote{See the ++variable @code{org-display-internal-link-with-indirect-buffer}}. ++@c ++@cindex mark ring ++@kindex C-c % ++@item C-c % ++Push the current position onto the mark ring, to be able to return ++easily. Commands following an internal link do this automatically. ++@c ++@cindex links, returning to ++@kindex C-c & ++@item C-c & ++Jump back to a recorded position. A position is recorded by the ++commands following internal links, and by @kbd{C-c %}. Using this ++command several times in direct succession moves through a ring of ++previously recorded positions. ++@c ++@kindex C-c C-x C-n ++@kindex C-c C-x C-p ++@cindex links, finding next/previous ++@item C-c C-x C-n ++@itemx C-c C-x C-p ++Move forward/backward to the next link in the buffer. At the limit of ++the buffer, the search fails once, and then wraps around. The key ++bindings for this are really too long, you might want to bind this also ++to @kbd{C-n} and @kbd{C-p} ++@lisp ++(add-hook 'org-load-hook ++ (lambda () ++ (define-key 'org-mode-map "\C-n" 'org-next-link) ++ (define-key 'org-mode-map "\C-p" 'org-previous-link))) ++@end lisp ++@end table ++ ++@node Using links outside Org, Link abbreviations, Handling links, Hyperlinks ++@section Using links outside Org ++ ++You can insert and follow links that have Org syntax not only in ++Org, but in any Emacs buffer. For this, you should create two ++global commands, like this (please select suitable global keys ++yourself): ++ ++@lisp ++(global-set-key "\C-c L" 'org-insert-link-global) ++(global-set-key "\C-c o" 'org-open-at-point-global) ++@end lisp ++ ++@node Link abbreviations, Search options, Using links outside Org, Hyperlinks ++@section Link abbreviations ++@cindex link abbreviations ++@cindex abbreviation, links ++ ++Long URLs can be cumbersome to type, and often many similar links are ++needed in a document. For this you can use link abbreviations. An ++abbreviated link looks like this ++ ++@example ++[[linkword:tag][description]] ++@end example ++ ++@noindent ++where the tag is optional. Such abbreviations are resolved according to ++the information in the variable @code{org-link-abbrev-alist} that ++relates the linkwords to replacement text. Here is an example: ++ ++@lisp ++@group ++(setq org-link-abbrev-alist ++ '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") ++ ("google" . "http://www.google.com/search?q=") ++ ("ads" . "http://adsabs.harvard.edu/cgi-bin/ ++ nph-abs_connect?author=%s&db_key=AST"))) ++@end group ++@end lisp ++ ++If the replacement text contains the string @samp{%s}, it will be ++replaced with the tag. Otherwise the tag will be appended to the string ++in order to create the link. You may also specify a function that will ++be called with the tag as the only argument to create the link. ++ ++With the above setting, you could link to a specific bug with ++@code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with ++@code{[[google:OrgMode]]} and find out what the Org author is ++doing besides Emacs hacking with @code{[[ads:Dominik,C]]}. ++ ++If you need special abbreviations just for a single Org buffer, you ++can define them in the file with ++ ++@example ++#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id= ++#+LINK: google http://www.google.com/search?q=%s ++@end example ++ ++@noindent ++In-buffer completion @pxref{Completion} can be used after @samp{[} to ++complete link abbreviations. ++ ++@node Search options, Custom searches, Link abbreviations, Hyperlinks ++@section Search options in file links ++@cindex search option in file links ++@cindex file links, searching ++ ++File links can contain additional information to make Emacs jump to a ++particular location in the file when following a link. This can be a ++line number or a search option after a double@footnote{For backward ++compatibility, line numbers can also follow a single colon.} colon. For ++example, when the command @kbd{C-c l} creates a link (@pxref{Handling ++links}) to a file, it encodes the words in the current line as a search ++string that can be used to find this line back later when following the ++link with @kbd{C-c C-o}. ++ ++Here is the syntax of the different ways to attach a search to a file ++link, together with an explanation: ++ ++@example ++[[file:~/code/main.c::255]] ++[[file:~/xx.org::My Target]] ++[[file:~/xx.org::*My Target]] ++[[file:~/xx.org::/regexp/]] ++@end example ++ ++@table @code ++@item 255 ++Jump to line 255. ++@item My Target ++Search for a link target @samp{<>}, or do a text search for ++@samp{my target}, similar to the search in internal links, see ++@ref{Internal links}. In HTML export (@pxref{HTML export}), such a file ++link will become an HTML reference to the corresponding named anchor in ++the linked file. ++@item *My Target ++In an Org file, restrict search to headlines. ++@item /regexp/ ++Do a regular expression search for @code{regexp}. This uses the Emacs ++command @code{occur} to list all matches in a separate window. If the ++target file is in Org mode, @code{org-occur} is used to create a ++sparse tree with the matches. ++@c If the target file is a directory, ++@c @code{grep} will be used to search all files in the directory. ++@end table ++ ++As a degenerate case, a file link with an empty file name can be used ++to search the current file. For example, @code{[[file:::find me]]} does ++a search for @samp{find me} in the current file, just as ++@samp{[[find me]]} would. ++ ++@node Custom searches, , Search options, Hyperlinks ++@section Custom Searches ++@cindex custom search strings ++@cindex search strings, custom ++ ++The default mechanism for creating search strings and for doing the ++actual search related to a file link may not work correctly in all ++cases. For example, BibTeX database files have many entries like ++@samp{year="1993"} which would not result in good search strings, ++because the only unique identification for a BibTeX entry is the ++citation key. ++ ++If you come across such a problem, you can write custom functions to set ++the right search string for a particular file type, and to do the search ++for the string in the file. Using @code{add-hook}, these functions need ++to be added to the hook variables ++@code{org-create-file-search-functions} and ++@code{org-execute-file-search-functions}. See the docstring for these ++variables for more information. Org actually uses this mechanism ++for Bib@TeX{} database files, and you can use the corresponding code as ++an implementation example. See the file @file{org-bibtex.el}. ++ ++@node TODO Items, Tags, Hyperlinks, Top ++@chapter TODO Items ++@cindex TODO items ++ ++Org mode does not maintain TODO lists as separate documents@footnote{Of ++course, you can make a document that contains only long lists of TODO items, ++but this is not required.}. Instead, TODO items are an integral part of the ++notes file, because TODO items usually come up while taking notes! With Org ++mode, simply mark any entry in a tree as being a TODO item. In this way, ++information is not duplicated, and the entire context from which the TODO ++item emerged is always present. ++ ++Of course, this technique for managing TODO items scatters them ++throughout your notes file. Org mode compensates for this by providing ++methods to give you an overview of all the things that you have to do. ++ ++@menu ++* TODO basics:: Marking and displaying TODO entries ++* TODO extensions:: Workflow and assignments ++* Progress logging:: Dates and notes for progress ++* Priorities:: Some things are more important than others ++* Breaking down tasks:: Splitting a task into manageable pieces ++* Checkboxes:: Tick-off lists ++@end menu ++ ++@node TODO basics, TODO extensions, TODO Items, TODO Items ++@section Basic TODO functionality ++ ++Any headline becomes a TODO item when it starts with the word ++@samp{TODO}, for example: ++ ++@example ++*** TODO Write letter to Sam Fortune ++@end example ++ ++@noindent ++The most important commands to work with TODO entries are: ++ ++@table @kbd ++@kindex C-c C-t ++@cindex cycling, of TODO states ++@item C-c C-t ++Rotate the TODO state of the current item among ++ ++@example ++,-> (unmarked) -> TODO -> DONE --. ++'--------------------------------' ++@end example ++ ++The same rotation can also be done ``remotely'' from the timeline and ++agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). ++ ++@kindex C-u C-c C-t ++@item C-u C-c C-t ++Select a specific keyword using completion or (if it has been set up) ++the fast selection interface. For the latter, you need to assign keys ++to TODO states, see @ref{Per-file keywords} and @ref{Setting tags} for ++more information. ++ ++@kindex S-@key{right} ++@kindex S-@key{left} ++@item S-@key{right} ++@itemx S-@key{left} ++Select the following/preceding TODO state, similar to cycling. Useful ++mostly if more than two TODO states are possible (@pxref{TODO ++extensions}). See also @ref{Conflicts} for a discussion of the interaction ++with @code{shift-selection-mode}. ++@kindex C-c C-v ++@kindex C-c / t ++@cindex sparse tree, for TODO ++@item C-c C-v ++@itemx C-c / t ++View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds ++the entire buffer, but shows all TODO items and the headings hierarchy ++above them. With a prefix argument, search for a specific TODO. You will be ++prompted for the keyword, and you can also give a list of keywords like ++@code{KWD1|KWD2|...}. With numeric prefix argument N, show the tree for the ++Nth keyword in the variable @code{org-todo-keywords}. With two prefix ++arguments, find all TODO and DONE entries. ++@kindex C-c a t ++@item C-c a t ++Show the global TODO list. Collects the TODO items from all agenda ++files (@pxref{Agenda Views}) into a single buffer. The new buffer will ++be in @code{agenda-mode}, which provides commands to examine and ++manipulate the TODO entries from the new buffer (@pxref{Agenda ++commands}). @xref{Global TODO list}, for more information. ++@kindex S-M-@key{RET} ++@item S-M-@key{RET} ++Insert a new TODO entry below the current one. ++@end table ++ ++@noindent ++Changing a TODO state can also trigger tag changes. See the docstring of the ++option @code{org-todo-state-tags-triggers} for details. ++ ++@node TODO extensions, Progress logging, TODO basics, TODO Items ++@section Extended use of TODO keywords ++@cindex extended TODO keywords ++ ++By default, marked TODO entries have one of only two states: TODO and ++DONE. Org mode allows you to classify TODO items in more complex ways ++with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With ++special setup, the TODO keyword system can work differently in different ++files. ++ ++Note that @i{tags} are another way to classify headlines in general and ++TODO items in particular (@pxref{Tags}). ++ ++@menu ++* Workflow states:: From TODO to DONE in steps ++* TODO types:: I do this, Fred does the rest ++* Multiple sets in one file:: Mixing it all, and still finding your way ++* Fast access to TODO states:: Single letter selection of a state ++* Per-file keywords:: Different files, different requirements ++* Faces for TODO keywords:: Highlighting states ++* TODO dependencies:: When one task needs to wait for others ++@end menu ++ ++@node Workflow states, TODO types, TODO extensions, TODO extensions ++@subsection TODO keywords as workflow states ++@cindex TODO workflow ++@cindex workflow states as TODO keywords ++ ++You can use TODO keywords to indicate different @emph{sequential} states ++in the process of working on an item, for example@footnote{Changing ++this variable only becomes effective after restarting Org mode in a ++buffer.}: ++ ++@lisp ++(setq org-todo-keywords ++ '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) ++@end lisp ++ ++The vertical bar separates the TODO keywords (states that @emph{need ++action}) from the DONE states (which need @emph{no further action}). If ++you don't provide the separator bar, the last state is used as the DONE ++state. ++@cindex completion, of TODO keywords ++With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO ++to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may ++also use a numeric prefix argument to quickly select a specific state. For ++example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY. ++Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you ++define many keywords, you can use in-buffer completion ++(@pxref{Completion}) or even a special one-key selection scheme ++(@pxref{Fast access to TODO states}) to insert these words into the ++buffer. Changing a TODO state can be logged with a timestamp, see ++@ref{Tracking TODO state changes} for more information. ++ ++@node TODO types, Multiple sets in one file, Workflow states, TODO extensions ++@subsection TODO keywords as types ++@cindex TODO types ++@cindex names as TODO keywords ++@cindex types as TODO keywords ++ ++The second possibility is to use TODO keywords to indicate different ++@emph{types} of action items. For example, you might want to indicate ++that items are for ``work'' or ``home''. Or, when you work with several ++people on a single project, you might want to assign action items ++directly to persons, by using their names as TODO keywords. This would ++be set up like this: ++ ++@lisp ++(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE"))) ++@end lisp ++ ++In this case, different keywords do not indicate a sequence, but rather ++different types. So the normal work flow would be to assign a task to a ++person, and later to mark it DONE. Org mode supports this style by adapting ++the workings of the command @kbd{C-c C-t}@footnote{This is also true for the ++@kbd{t} command in the timeline and agenda buffers.}. When used several ++times in succession, it will still cycle through all names, in order to first ++select the right type for a task. But when you return to the item after some ++time and execute @kbd{C-c C-t} again, it will switch from any name directly ++to DONE. Use prefix arguments or completion to quickly select a specific ++name. You can also review the items of a specific TODO type in a sparse tree ++by using a numeric prefix to @kbd{C-c C-v}. For example, to see all things ++Lucy has to do, you would use @kbd{C-3 C-c C-v}. To collect Lucy's items ++from all agenda files into a single buffer, you would use the numeric prefix ++argument as well when creating the global TODO list: @kbd{C-3 C-c t}. ++ ++@node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions ++@subsection Multiple keyword sets in one file ++@cindex TODO keyword sets ++ ++Sometimes you may want to use different sets of TODO keywords in ++parallel. For example, you may want to have the basic ++@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a ++separate state indicating that an item has been canceled (so it is not ++DONE, but also does not require action). Your setup would then look ++like this: ++ ++@lisp ++(setq org-todo-keywords ++ '((sequence "TODO" "|" "DONE") ++ (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") ++ (sequence "|" "CANCELED"))) ++@end lisp ++ ++The keywords should all be different, this helps Org mode to keep track ++of which subsequence should be used for a given entry. In this setup, ++@kbd{C-c C-t} only operates within a subsequence, so it switches from ++@code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to ++(nothing) to @code{REPORT}. Therefore you need a mechanism to initially ++select the correct sequence. Besides the obvious ways like typing a ++keyword or using completion, you may also apply the following commands: ++ ++@table @kbd ++@kindex C-S-@key{right} ++@kindex C-S-@key{left} ++@kindex C-u C-u C-c C-t ++@item C-u C-u C-c C-t ++@itemx C-S-@key{right} ++@itemx C-S-@key{left} ++These keys jump from one TODO subset to the next. In the above example, ++@kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or ++@code{DONE} to @code{REPORT}, and any of the words in the second row to ++@code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with ++@code{shift-selection-mode} (@pxref{Conflicts}). ++@kindex S-@key{right} ++@kindex S-@key{left} ++@item S-@key{right} ++@itemx S-@key{left} ++@kbd{S-@key{}} and @kbd{S-@key{}} and walk through @emph{all} ++keywords from all sets, so for example @kbd{S-@key{}} would switch ++from @code{DONE} to @code{REPORT} in the example above. See also ++@ref{Conflicts} for a discussion of the interaction with ++@code{shift-selection-mode}. ++@end table ++ ++@node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions ++@subsection Fast access to TODO states ++ ++If you would like to quickly change an entry to an arbitrary TODO state ++instead of cycling through the states, you can set up keys for ++single-letter access to the states. This is done by adding the section ++key after each keyword, in parenthesis. For example: ++ ++@lisp ++(setq org-todo-keywords ++ '((sequence "TODO(t)" "|" "DONE(d)") ++ (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") ++ (sequence "|" "CANCELED(c)"))) ++@end lisp ++ ++If you then press @code{C-c C-t} followed by the selection key, the entry ++will be switched to this state. @key{SPC} can be used to remove any TODO ++keyword from an entry.@footnote{Check also the variable ++@code{org-fast-tag-selection-include-todo}, it allows to change the TODO ++state through the tags interface (@pxref{Setting tags}), in case you like to ++mingle the two concepts. Note that this means you need to come up with ++unique keys across both sets of keywords.} ++ ++@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions ++@subsection Setting up keywords for individual files ++@cindex keyword options ++@cindex per-file keywords ++ ++It can be very useful to use different aspects of the TODO mechanism in ++different files. For file-local settings, you need to add special lines ++to the file which set the keywords and interpretation for that file ++only. For example, to set one of the two examples discussed above, you ++need one of the following lines, starting in column zero anywhere in the ++file: ++ ++@example ++#+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED ++@end example ++or ++@example ++#+TYP_TODO: Fred Sara Lucy Mike | DONE ++@end example ++ ++A setup for using several sets in parallel would be: ++ ++@example ++#+SEQ_TODO: TODO | DONE ++#+SEQ_TODO: REPORT BUG KNOWNCAUSE | FIXED ++#+SEQ_TODO: | CANCELED ++@end example ++ ++@cindex completion, of option keywords ++@kindex M-@key{TAB} ++@noindent To make sure you are using the correct keyword, type ++@samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion. ++ ++@cindex DONE, final TODO keyword ++Remember that the keywords after the vertical bar (or the last keyword ++if no bar is there) must always mean that the item is DONE (although you ++may use a different word). After changing one of these lines, use ++@kbd{C-c C-c} with the cursor still in the line to make the changes ++known to Org mode@footnote{Org mode parses these lines only when ++Org mode is activated after visiting a file. @kbd{C-c C-c} with the ++cursor in a line starting with @samp{#+} is simply restarting Org mode ++for the current buffer.}. ++ ++@node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions ++@subsection Faces for TODO keywords ++@cindex faces, for TODO keywords ++ ++Org mode highlights TODO keywords with special faces: @code{org-todo} ++for keywords indicating that an item still has to be acted upon, and ++@code{org-done} for keywords indicating that an item is finished. If ++you are using more than 2 different states, you might want to use ++special faces for some of them. This can be done using the variable ++@code{org-todo-keyword-faces}. For example: ++ ++@lisp ++@group ++(setq org-todo-keyword-faces ++ '(("TODO" . org-warning) ++ ("DEFERRED" . shadow) ++ ("CANCELED" . (:foreground "blue" :weight bold)))) ++@end group ++@end lisp ++ ++While using a list with face properties as shown for CANCELED ++@emph{should} work, this does not aways seem to be the case. If ++necessary, define a special face and use that. ++ ++@node TODO dependencies, , Faces for TODO keywords, TODO extensions ++@subsection TODO dependencies ++@cindex TODO dependencies ++@cindex dependencies, of TODO states ++ ++The structure of Org files (hierarchy and lists) makes it easy to define TODO ++dependencies. Usually, a parent TODO task should not be marked DONE until ++all subtasks (defined as children tasks) are marked as DONE. And sometimes ++there is a logical sequence to a number of (sub)tasks, so that one task ++cannot be acted upon before all siblings above it are done. If you customize ++the variable @code{org-enforce-todo-dependencies}, Org will block entries ++from changing state to DONE while they have children that are not DONE. ++Furthermore, if an entry has a property @code{ORDERED}, each of its children ++will be blocked until all earlier siblings are marked DONE. Here is an ++example: ++ ++@example ++* TODO Blocked until (two) is done ++** DONE one ++** TODO two ++ ++* Parent ++ :PROPERTIES: ++ :ORDERED: t ++ :END: ++** TODO a ++** TODO b, needs to wait for (a) ++** TODO c, needs to wait for (a) and (b) ++@end example ++ ++@table @kbd ++@kindex C-c C-x o ++@item C-c C-x o ++Toggle the @code{ORDERED} property of the current entry. ++@kindex C-u C-u C-u C-c C-t ++@item C-u C-u C-u C-c C-t ++Change TODO state, circumventin any state blocking. ++@end table ++ ++If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries ++that cannot be closed because of such dependencies will be shown in a dimmed ++font or even made invisible in agenda views (@pxref{Agenda Views}). ++ ++@cindex checkboxes and TODO dependencies ++You can also block changes of TODO states by looking at checkboxes ++(@pxref{Checkboxes}). If you set the variable ++@code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked ++checkboxes will be blocked from switching to DONE. ++ ++If you need more complex dependency structures, for example dependencies ++between entries in different trees or files, check out the contributed ++module @file{org-depend.el}. ++ ++@page ++@node Progress logging, Priorities, TODO extensions, TODO Items ++@section Progress logging ++@cindex progress logging ++@cindex logging, of progress ++ ++Org mode can automatically record a time stamp and possibly a note when ++you mark a TODO item as DONE, or even each time you change the state of ++a TODO item. This system is highly configurable, settings can be on a ++per-keyword basis and can be localized to a file or even a subtree. For ++information on how to clock working time for a task, see @ref{Clocking ++work time}. ++ ++@menu ++* Closing items:: When was this entry marked DONE? ++* Tracking TODO state changes:: When did the status change? ++@end menu ++ ++@node Closing items, Tracking TODO state changes, Progress logging, Progress logging ++@subsection Closing items ++ ++The most basic logging is to keep track of @emph{when} a certain TODO ++item was finished. This is achieved with@footnote{The corresponding ++in-buffer setting is: @code{#+STARTUP: logdone}}. ++ ++@lisp ++(setq org-log-done 'time) ++@end lisp ++ ++@noindent ++Then each time you turn an entry from a TODO (not-done) state into any ++of the DONE states, a line @samp{CLOSED: [timestamp]} will be inserted ++just after the headline. If you turn the entry back into a TODO item ++through further state cycling, that line will be removed again. If you ++want to record a note along with the timestamp, use@footnote{The ++corresponding in-buffer setting is: @code{#+STARTUP: lognotedone}} ++ ++@lisp ++(setq org-log-done 'note) ++@end lisp ++ ++@noindent ++You will then be prompted for a note, and that note will be stored below ++the entry with a @samp{Closing Note} heading. ++ ++In the timeline (@pxref{Timeline}) and in the agenda ++(@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key to ++display the TODO items with a @samp{CLOSED} timestamp on each day, ++giving you an overview of what has been done. ++ ++@node Tracking TODO state changes, , Closing items, Progress logging ++@subsection Tracking TODO state changes ++ ++When TODO keywords are used as workflow states (@pxref{Workflow ++states}), you might want to keep track of when a state change occurred ++and maybe take a note about this change. Since it is normally too much ++to record a note for every state, Org mode expects configuration on a ++per-keyword basis for this. This is achieved by adding special markers ++@samp{!} (for a time stamp) and @samp{@@} (for a note) in parenthesis ++after each keyword. For example, with the setting ++ ++@lisp ++(setq org-todo-keywords ++ '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)"))) ++@end lisp ++ ++@noindent ++you not only define global TODO keywords and fast access keys, but also ++request that a time is recorded when the entry is turned into ++DONE@footnote{It is possible that Org mode will record two time stamps ++when you are using both @code{org-log-done} and state change logging. ++However, it will never prompt for two notes - if you have configured ++both, the state change recording note will take precedence and cancel ++the @samp{Closing Note}.}, and that a note is recorded when switching to ++WAIT or CANCELED. The setting for WAIT is even more special: The ++@samp{!} after the slash means that in addition to the note taken when ++entering the state, a time stamp should be recorded when @i{leaving} the ++WAIT state, if and only if the @i{target} state does not configure ++logging for entering it. So it has no effect when switching from WAIT ++to DONE, because DONE is configured to record a timestamp only. But ++when switching from WAIT back to TODO, the @samp{/!} in the WAIT ++setting now triggers a timestamp even though TODO has no logging ++configured. ++ ++You can use the exact same syntax for setting logging preferences local ++to a buffer: ++@example ++#+SEQ_TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) ++@end example ++ ++In order to define logging settings that are local to a subtree or a ++single item, define a LOGGING property in this entry. Any non-empty ++LOGGING property resets all logging settings to nil. You may then turn ++on logging for this specific tree using STARTUP keywords like ++@code{lognotedone} or @code{logrepeat}, as well as adding state specific ++settings like @code{TODO(!)}. For example ++ ++@example ++* TODO Log each state with only a time ++ :PROPERTIES: ++ :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!) ++ :END: ++* TODO Only log when switching to WAIT, and when repeating ++ :PROPERTIES: ++ :LOGGING: WAIT(@@) logrepeat ++ :END: ++* TODO No logging at all ++ :PROPERTIES: ++ :LOGGING: nil ++ :END: ++@end example ++ ++@node Priorities, Breaking down tasks, Progress logging, TODO Items ++@section Priorities ++@cindex priorities ++ ++If you use Org mode extensively, you may end up enough TODO items that ++it starts to make sense to prioritize them. Prioritizing can be done by ++placing a @emph{priority cookie} into the headline of a TODO item, like ++this ++ ++@example ++*** TODO [#A] Write letter to Sam Fortune ++@end example ++ ++@noindent ++By default, Org mode supports three priorities: @samp{A}, @samp{B}, and ++@samp{C}. @samp{A} is the highest priority. An entry without a cookie ++is treated as priority @samp{B}. Priorities make a difference only in ++the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they have ++no inherent meaning to Org mode. ++ ++Priorities can be attached to any outline tree entries; they do not need ++to be TODO items. ++ ++@table @kbd ++@kindex @kbd{C-c ,} ++@item @kbd{C-c ,} ++Set the priority of the current headline. The command prompts for a ++priority character @samp{A}, @samp{B} or @samp{C}. When you press ++@key{SPC} instead, the priority cookie is removed from the headline. ++The priorities can also be changed ``remotely'' from the timeline and ++agenda buffer with the @kbd{,} command (@pxref{Agenda commands}). ++@c ++@kindex S-@key{up} ++@kindex S-@key{down} ++@item S-@key{up} ++@itemx S-@key{down} ++Increase/decrease priority of current headline@footnote{See also the option ++@code{org-priority-start-cycle-with-default'}.}. Note that these keys are ++also used to modify time stamps (@pxref{Creating timestamps}). See also ++@ref{Conflicts} for a discussion of the interaction with ++@code{shift-selection-mode}. ++@end table ++ ++You can change the range of allowed priorities by setting the variables ++@code{org-highest-priority}, @code{org-lowest-priority}, and ++@code{org-default-priority}. For an individual buffer, you may set ++these values (highest, lowest, default) like this (please make sure that ++the highest priority is earlier in the alphabet than the lowest ++priority): ++ ++@example ++#+PRIORITIES: A C B ++@end example ++ ++@node Breaking down tasks, Checkboxes, Priorities, TODO Items ++@section Breaking tasks down into subtasks ++@cindex tasks, breaking down ++ ++It is often advisable to break down large tasks into smaller, manageable ++subtasks. You can do this by creating an outline tree below a TODO item, ++with detailed subtasks on the tree@footnote{To keep subtasks out of the ++global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep ++the overview over the fraction of subtasks that are already completed, insert ++either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will ++be updates each time the todo status of a child changes. For example: ++ ++@example ++* Organize Party [33%] ++** TODO Call people [1/2] ++*** TODO Peter ++*** DONE Sarah ++** TODO Buy food ++** DONE Talk to neighbor ++@end example ++ ++If you would like a TODO entry to automatically change to DONE when all ++children are done, you can use the following setup: ++ ++@example ++(defun org-summary-todo (n-done n-not-done) ++ "Switch entry to DONE when all subentries are done, to TODO otherwise." ++ (let (org-log-done org-log-states) ; turn off logging ++ (org-todo (if (= n-not-done 0) "DONE" "TODO")))) ++ ++(add-hook 'org-after-todo-statistics-hook 'org-summary-todo) ++@end example ++ ++ ++Another possibility is the use of checkboxes to identify (a hierarchy of) a ++large number of subtasks (@pxref{Checkboxes}). ++ ++ ++@node Checkboxes, , Breaking down tasks, TODO Items ++@section Checkboxes ++@cindex checkboxes ++ ++Every item in a plain list (@pxref{Plain lists}) can be made into a ++checkbox by starting it with the string @samp{[ ]}. This feature is ++similar to TODO items (@pxref{TODO Items}), but is more lightweight. ++Checkboxes are not included into the global TODO list, so they are often ++great to split a task into a number of simple steps. Or you can use ++them in a shopping list. To toggle a checkbox, use @kbd{C-c C-c}, or ++use the mouse (thanks to Piotr Zielinski's @file{org-mouse.el}). ++ ++Here is an example of a checkbox list. ++ ++@example ++* TODO Organize party [2/4] ++ - [-] call people [1/3] ++ - [ ] Peter ++ - [X] Sarah ++ - [ ] Sam ++ - [X] order food ++ - [ ] think about what music to play ++ - [X] talk to the neighbors ++@end example ++ ++Checkboxes work hierarchically, so if a checkbox item has children that ++are checkboxes, toggling one of the children checkboxes will make the ++parent checkbox reflect if none, some, or all of the children are ++checked. ++ ++@cindex statistics, for checkboxes ++@cindex checkbox statistics ++The @samp{[2/4]} and @samp{[1/3]} in the first and second line are ++cookies indicating how many checkboxes present in this entry have been ++checked off, and the total number of checkboxes are present. This can ++give you an idea on how many checkboxes remain, even without opening a ++folded entry. The cookies can be placed into a headline or into (the ++first line of) a plain list item. Each cookie covers all checkboxes ++structurally below the headline/item on which the cookie appear. You ++have to insert the cookie yourself by typing either @samp{[/]} or ++@samp{[%]}. With @samp{[/]} you get an @samp{n out of m} result, as in ++the examples above. With @samp{[%]} you get information about the ++percentage of checkboxes checked (in the above example, this would be ++@samp{[50%]} and @samp{[33%]}, respectively). ++ ++@noindent The following commands work with checkboxes: ++ ++@table @kbd ++@kindex C-c C-c ++@item C-c C-c ++Toggle checkbox at point. With a prefix argument, set it to @samp{[-]}, ++which is considered to be an intermediate state. ++@kindex C-c C-x C-b ++@item C-c C-x C-b ++Toggle checkbox status or (with prefix arg) checkbox presence at point. ++@itemize @minus ++@item ++If there is an active region, toggle the first checkbox in the region ++and set all remaining boxes to the same status as the first. With a prefix ++arg, add or remove the checkbox for all items in the region. ++@item ++If the cursor is in a headline, toggle checkboxes in the region between ++this headline and the next (so @emph{not} the entire subtree). ++@item ++If there is no active region, just toggle the checkbox at point. ++@end itemize ++@kindex M-S-@key{RET} ++@item M-S-@key{RET} ++Insert a new item with a checkbox. ++This works only if the cursor is already in a plain list item ++(@pxref{Plain lists}). ++@kindex C-c # ++@item C-c # ++Update the checkbox statistics in the current outline entry. When ++called with a @kbd{C-u} prefix, update the entire file. Checkbox ++statistic cookies are updated automatically if you toggle checkboxes ++with @kbd{C-c C-c} and make new ones with @kbd{M-S-@key{RET}}. If you ++delete boxes or add/change them by hand, use this command to get things ++back into sync. Or simply toggle any checkbox twice with @kbd{C-c C-c}. ++@end table ++ ++@node Tags, Properties and Columns, TODO Items, Top ++@chapter Tags ++@cindex tags ++@cindex headline tagging ++@cindex matching, tags ++@cindex sparse tree, tag based ++ ++An excellent way to implement labels and contexts for cross-correlating ++information is to assign @i{tags} to headlines. Org mode has extensive ++support for tags. ++ ++Every headline can contain a list of tags; they occur at the end of the ++headline. Tags are normal words containing letters, numbers, @samp{_}, and ++@samp{@@}. Tags must be preceded and followed by a single colon, e.g., ++@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. ++Tags will by default get a bold face with the same color as the headline. ++You may specify special faces for specific tags using the variable ++@code{org-tag-faces}, much in the same way as you can do for TODO keywords ++(@pxref{Faces for TODO keywords}). ++ ++@menu ++* Tag inheritance:: Tags use the tree structure of the outline ++* Setting tags:: How to assign tags to a headline ++* Tag searches:: Searching for combinations of tags ++@end menu ++ ++@node Tag inheritance, Setting tags, Tags, Tags ++@section Tag inheritance ++@cindex tag inheritance ++@cindex inheritance, of tags ++@cindex sublevels, inclusion into tags match ++ ++@i{Tags} make use of the hierarchical structure of outline trees. If a ++heading has a certain tag, all subheadings will inherit the tag as ++well. For example, in the list ++ ++@example ++* Meeting with the French group :work: ++** Summary by Frank :boss:notes: ++*** TODO Prepare slides for him :action: ++@end example ++ ++@noindent ++the final heading will have the tags @samp{:work:}, @samp{:boss:}, ++@samp{:notes:}, and @samp{:action:} even though the final heading is not ++explicitly marked with those tags. You can also set tags that all entries in ++a file should inherit as if these tags would be defined in a hypothetical ++level zero that surrounds the entire file. ++ ++@example ++#+FILETAGS: :Peter:Boss:Secret: ++@end example ++ ++@noindent ++To limit tag inheritance to specific tags, or to turn it off entirely, use ++the variables @code{org-use-tag-inheritance} and ++@code{org-tags-exclude-from-inheritance}. ++ ++When a headline matches during a tags search while tag inheritance is turned ++on, all the sublevels in the same tree will (for a simple match form) match ++as well@footnote{This is only true if the search does not involve more ++complex tests including properties (@pxref{Property searches}).}. The list ++of matches may then become very long. If you only want to see the first tags ++match in a subtree, configure the variable ++@code{org-tags-match-list-sublevels} (not recommended). ++ ++@node Setting tags, Tag searches, Tag inheritance, Tags ++@section Setting tags ++@cindex setting tags ++@cindex tags, setting ++ ++@kindex M-@key{TAB} ++Tags can simply be typed into the buffer at the end of a headline. ++After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is ++also a special command for inserting tags: ++ ++@table @kbd ++@kindex C-c C-q ++@item C-c C-q ++@cindex completion, of tags ++Enter new tags for the current headline. Org mode will either offer ++completion or a special single-key interface for setting tags, see ++below. After pressing @key{RET}, the tags will be inserted and aligned ++to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all ++tags in the current buffer will be aligned to that column, just to make ++things look nice. TAGS are automatically realigned after promotion, ++demotion, and TODO state changes (@pxref{TODO basics}). ++@kindex C-c C-c ++@item C-c C-c ++When the cursor is in a headline, this does the same as @kbd{C-c C-q}. ++@end table ++ ++Org will support tag insertion based on a @emph{list of tags}. By ++default this list is constructed dynamically, containing all tags ++currently used in the buffer. You may also globally specify a hard list ++of tags with the variable @code{org-tag-alist}. Finally you can set ++the default tags for a given file with lines like ++ ++@example ++#+TAGS: @@work @@home @@tennisclub ++#+TAGS: laptop car pc sailboat ++@end example ++ ++If you have globally defined your preferred set of tags using the ++variable @code{org-tag-alist}, but would like to use a dynamic tag list ++in a specific file, add an empty TAGS option line to that file: ++ ++@example ++#+TAGS: ++@end example ++ ++By default Org mode uses the standard minibuffer completion facilities for ++entering tags. However, it also implements another, quicker, tag selection ++method called @emph{fast tag selection}. This allows you to select and ++deselect tags with just a single key press. For this to work well you should ++assign unique letters to most of your commonly used tags. You can do this ++globally by configuring the variable @code{org-tag-alist} in your ++@file{.emacs} file. For example, you may find the need to tag many items in ++different files with @samp{:@@home:}. In this case you can set something ++like: ++ ++@lisp ++(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) ++@end lisp ++ ++@noindent If the tag is only relevant to the file you are working on then you ++can, instead, set the TAGS option line as: ++ ++@example ++#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) ++@end example ++ ++@noindent ++You can also group together tags that are mutually exclusive. By using ++braces, as in: ++ ++@example ++#+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p) ++@end example ++ ++@noindent you indicate that at most one of @samp{@@work}, @samp{@@home}, ++and @samp{@@tennisclub} should be selected. Multiple such groups are allowed. ++ ++@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of ++these lines to activate any changes. ++ ++@noindent ++To set these mutually exclusive groups in the variable @code{org-mode-alist} ++you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead ++of the braces. The previous example would be set globally by the following ++configuration: ++ ++@lisp ++(setq org-tag-alist '((:startgroup . nil) ++ ("@@work" . ?w) ("@@home" . ?h) ++ ("@@tennisclub" . ?t) ++ (:endgroup . nil) ++ ("laptop" . ?l) ("pc" . ?p))) ++@end lisp ++ ++If at least one tag has a selection key then pressing @kbd{C-c C-c} will ++automatically present you with a special interface, listing inherited tags, ++the tags of the current headline, and a list of all valid tags with ++corresponding keys@footnote{Keys will automatically be assigned to tags which ++have no configured keys.}. In this interface, you can use the following ++keys: ++ ++@table @kbd ++@item a-z... ++Pressing keys assigned to tags will add or remove them from the list of ++tags in the current line. Selecting a tag in a group of mutually ++exclusive tags will turn off any other tags from that group. ++@kindex @key{TAB} ++@item @key{TAB} ++Enter a tag in the minibuffer, even if the tag is not in the predefined ++list. You will be able to complete on all tags present in the buffer. ++@kindex @key{SPC} ++@item @key{SPC} ++Clear all tags for this line. ++@kindex @key{RET} ++@item @key{RET} ++Accept the modified set. ++@item C-g ++Abort without installing changes. ++@item q ++If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}. ++@item ! ++Turn off groups of mutually exclusive tags. Use this to (as an ++exception) assign several tags from such a group. ++@item C-c ++Toggle auto-exit after the next change (see below). ++If you are using expert mode, the first @kbd{C-c} will display the ++selection window. ++@end table ++ ++@noindent ++This method lets you assign tags to a headline with very few keys. With ++the above setup, you could clear the current tags and set @samp{@@home}, ++@samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c ++C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to ++@samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or ++alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag ++@samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h ++@key{RET} @key{RET}}. ++ ++If you find that most of the time, you need only a single key press to ++modify your list of tags, set the variable ++@code{org-fast-tag-selection-single-key}. Then you no longer have to ++press @key{RET} to exit fast tag selection - it will immediately exit ++after the first change. If you then occasionally need more keys, press ++@kbd{C-c} to turn off auto-exit for the current tag selection process ++(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c ++C-c}). If you set the variable to the value @code{expert}, the special ++window is not even shown for single-key tag selection, it comes up only ++when you press an extra @kbd{C-c}. ++ ++@node Tag searches, , Setting tags, Tags ++@section Tag searches ++@cindex tag searches ++@cindex searching for tags ++ ++Once a system of tags has been set up, it can be used to collect related ++information into special lists. ++ ++@table @kbd ++@kindex C-c \ ++@kindex C-c / T ++@item C-c \ ++@itemx C-c / T ++Create a sparse tree with all headlines matching a tags search. With a ++@kbd{C-u} prefix argument, ignore headlines that are not a TODO line. ++@kindex C-c a m ++@item C-c a m ++Create a global list of tag matches from all agenda files. ++@xref{Matching tags and properties}. ++@kindex C-c a M ++@item C-c a M ++Create a global list of tag matches from all agenda files, but check ++only TODO items and force checking subitems (see variable ++@code{org-tags-match-list-sublevels}). ++@end table ++ ++@cindex Boolean logic, for tag searches ++A @i{tags} search string can use Boolean operators @samp{&} for AND and ++@samp{|} for OR. @samp{&} binds more strongly than @samp{|}. ++Parenthesis are currently not implemented. A tag may also be preceded ++by @samp{-}, to select against it, and @samp{+} is syntactic sugar for ++positive selection. The AND operator @samp{&} is optional when @samp{+} ++or @samp{-} is present. Examples: ++ ++@table @samp ++@item +work-boss ++Select headlines tagged @samp{:work:}, but discard those also tagged ++@samp{:boss:}. ++@item work|laptop ++Selects lines tagged @samp{:work:} or @samp{:laptop:}. ++@item work|laptop&night ++Like before, but require the @samp{:laptop:} lines to be tagged also ++@samp{:night:}. ++@end table ++ ++@cindex TODO keyword matching, with tags search ++You may also test for TODO keywords (@pxref{TODO extensions}) and properties ++(@pxref{Properties and Columns}) at the same time as matching tags. For a ++guide on how to match properties, see @ref{Property searches}. To match a ++specific TODO keyword, include an expression like @samp{+TODO="NEXT"} as one ++of the terms in a tags search. ++ ++There is also the possibility to end the tags part of the match (which may ++include several terms connected with @samp{|}) with a @samp{/} and then ++specify a Boolean expression just for TODO keywords. The syntax is then ++similar to the tag matches, but should be applied with consideration: For ++example, a positive selection on several TODO keywords can not meaningfully ++be combined with boolean AND. However, @emph{negative selection} combined ++with AND can be meaningful. To make sure that only lines are checked that ++actually have any TODO keyword (resulting in a speed-up), use @kbd{C-c a M}, ++or equivalently start the TODO part after the slash with @samp{!}. Examples: ++ ++@table @samp ++@item work+TODO="WAITING" ++Select @samp{:work:}-tagged TODO lines with the specific TODO ++keyword @samp{WAITING}. ++@item work+TODO="WAITING"|home+TODO="WAITING" ++Waiting tasks both at work and at home. ++@item work/WAITING ++Same as the first example. ++@item work/!-WAITING-NEXT ++Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING} ++nor @samp{NEXT} ++@item work/!+WAITING|+NEXT ++Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or ++@samp{NEXT}. ++@end table ++ ++@cindex regular expressions, with tags search ++Any element of the tag/todo match can be a regular expression - in this ++case it must be enclosed in curly braces. For example, ++@samp{work+@{^boss.*@}} matches headlines that contain the tag ++@samp{:work:} and any tag @i{starting} with @samp{boss}. You may also use a ++regular expression in @samp{TODO=@{^W@}} which would match TODO keywords ++starting with the letter @samp{W}. ++ ++@cindex level, require for tags/property match ++@cindex category, require for tags/property match ++You can also require a headline to be of a certain level or category, by ++writing instead of any TAG an expression like @samp{LEVEL=3} or ++@samp{CATEGORY="work"}, respectively. For example, a search ++@samp{+LEVEL=3+boss/-DONE} lists all level three headlines that have the ++tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE. ++ ++Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing any ++other properties will slow down the search. ++ ++@node Properties and Columns, Dates and Times, Tags, Top ++@chapter Properties and Columns ++@cindex properties ++ ++Properties are a set of key-value pairs associated with an entry. There ++are two main applications for properties in Org mode. First, properties ++are like tags, but with a value. Second, you can use properties to ++implement (very basic) database capabilities in an Org buffer. For ++an example of the first application, imagine maintaining a file where ++you document bugs and plan releases of a piece of software. Instead of ++using tags like @code{:release_1:}, @code{:release_2:}, one can use a ++property, say @code{:Release:}, that in different subtrees has different ++values, such as @code{1.0} or @code{2.0}. For an example of the second ++application of properties, imagine keeping track of your music CDs, ++where properties could be things such as the album artist, date of ++release, number of tracks, and so on. ++ ++Properties can be conveniently edited and viewed in column view ++(@pxref{Column view}). ++ ++@menu ++* Property syntax:: How properties are spelled out ++* Special properties:: Access to other Org mode features ++* Property searches:: Matching property values ++* Property inheritance:: Passing values down the tree ++* Column view:: Tabular viewing and editing ++* Property API:: Properties for Lisp programmers ++@end menu ++ ++@node Property syntax, Special properties, Properties and Columns, Properties and Columns ++@section Property syntax ++@cindex property syntax ++@cindex drawer, for properties ++ ++Properties are key-value pairs. They need to be inserted into a special ++drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property ++is specified on a single line, with the key (surrounded by colons) ++first, and the value after it. Here is an example: ++ ++@example ++* CD collection ++** Classic ++*** Goldberg Variations ++ :PROPERTIES: ++ :Title: Goldberg Variations ++ :Composer: J.S. Bach ++ :Artist: Glen Gould ++ :Publisher: Deutsche Grammphon ++ :NDisks: 1 ++ :END: ++@end example ++ ++You may define the allowed values for a particular property @samp{:Xyz:} ++by setting a property @samp{:Xyz_ALL:}. This special property is ++@emph{inherited}, so if you set it in a level 1 entry, it will apply to ++the entire tree. When allowed values are defined, setting the ++corresponding property becomes easier and is less prone to typing ++errors. For the example with the CD collection, we can predefine ++publishers and the number of disks in a box like this: ++ ++@example ++* CD collection ++ :PROPERTIES: ++ :NDisks_ALL: 1 2 3 4 ++ :Publisher_ALL: "Deutsche Grammophon" Philips EMI ++ :END: ++@end example ++ ++If you want to set properties that can be inherited by any entry in a ++file, use a line like ++ ++@example ++#+PROPERTY: NDisks_ALL 1 2 3 4 ++@end example ++ ++Property values set with the global variable ++@code{org-global-properties} can be inherited by all entries in all ++Org files. ++ ++@noindent ++The following commands help to work with properties: ++ ++@table @kbd ++@kindex M-@key{TAB} ++@item M-@key{TAB} ++After an initial colon in a line, complete property keys. All keys used ++in the current file will be offered as possible completions. ++@kindex C-c C-x p ++@item C-c C-x p ++Set a property. This prompts for a property name and a value. If ++necessary, the property drawer is created as well. ++@item M-x org-insert-property-drawer ++Insert a property drawer into the current entry. The drawer will be ++inserted early in the entry, but after the lines with planning ++information like deadlines. ++@kindex C-c C-c ++@item C-c C-c ++With the cursor in a property drawer, this executes property commands. ++@item C-c C-c s ++Set a property in the current entry. Both the property and the value ++can be inserted using completion. ++@kindex S-@key{right} ++@kindex S-@key{left} ++@item S-@key{left}/@key{right} ++Switch property at point to the next/previous allowed value. ++@item C-c C-c d ++Remove a property from the current entry. ++@item C-c C-c D ++Globally remove a property, from all entries in the current file. ++@item C-c C-c c ++Compute the property at point, using the operator and scope from the ++nearest column format definition. ++@end table ++ ++@node Special properties, Property searches, Property syntax, Properties and Columns ++@section Special properties ++@cindex properties, special ++ ++Special properties provide alternative access method to Org mode ++features discussed in the previous chapters, like the TODO state or the ++priority of an entry. This interface exists so that you can include ++these states into columns view (@pxref{Column view}), or to use them in ++queries. The following property names are special and should not be ++used as keys in the properties drawer: ++ ++@example ++TODO @r{The TODO keyword of the entry.} ++TAGS @r{The tags defined directly in the headline.} ++ALLTAGS @r{All tags, including inherited ones.} ++PRIORITY @r{The priority of the entry, a string with a single letter.} ++DEADLINE @r{The deadline time string, without the angular brackets.} ++SCHEDULED @r{The scheduling time stamp, without the angular brackets.} ++TIMESTAMP @r{The first keyword-less time stamp in the entry.} ++TIMESTAMP_IA @r{The first inactive time stamp in the entry.} ++CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}} ++ @r{must be run first to compute the values.} ++@end example ++ ++@node Property searches, Property inheritance, Special properties, Properties and Columns ++@section Property searches ++@cindex properties, searching ++@cindex searching, of properties ++ ++To create sparse trees and special lists with selection based on properties, ++the same commands are used as for tag searches (@pxref{Tag searches}), and ++the same logic applies. For example, here is a search string: ++ ++@example +++work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \ ++ +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>" ++@end example ++ ++@noindent ++The type of comparison will depend on how the comparison value is written: ++@itemize @minus ++@item ++If the comparison value is a plain number, a numerical comparison is done, ++and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=}, ++@samp{>=}, and @samp{<>}. ++@item ++If the comparison value is enclosed in double ++quotes, a string comparison is done, and the same operators are allowed. ++@item ++If the comparison value is enclosed in double quotes @emph{and} angular ++brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are ++assumed to be date/time specifications in the standard Org way, and the ++comparison will be done accordingly. Special values that will be recognized ++are @code{""} for now (including time), and @code{""}, and ++@code{""} for these days at 0:00 hours, i.e. without a time ++specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units ++@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year, ++respectively, can be used. ++@item ++If the comparison value is enclosed ++in curly braces, a regexp match is performed, with @samp{=} meaning that the ++regexp matches the property value, and @samp{<>} meaning that it does not ++match. ++@end itemize ++ ++So the search string in the example finds entries tagged @samp{:work:} but ++not @samp{:boss:}, which also have a priority value @samp{A}, a ++@samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort} ++property that is numerically smaller than 2, a @samp{:With:} property that is ++matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled ++on or after October 11, 2008. ++ ++You can configure Org mode to use property inheritance during a search, but ++beware that this can slow down searches considerably. See @ref{Property ++inheritance} for details. ++ ++There is also a special command for creating sparse trees based on a ++single property: ++ ++@table @kbd ++@kindex C-c / p ++@item C-c / p ++Create a sparse tree based on the value of a property. This first ++prompts for the name of a property, and then for a value. A sparse tree ++is created with all entries that define this property with the given ++value. If you enclose the value into curly braces, it is interpreted as ++a regular expression and matched against the property values. ++@end table ++ ++@node Property inheritance, Column view, Property searches, Properties and Columns ++@section Property Inheritance ++@cindex properties, inheritance ++@cindex inheritance, of properties ++ ++The outline structure of Org mode documents lends itself for an ++inheritance model of properties: If the parent in a tree has a certain ++property, the children can inherit this property. Org mode does not ++turn this on by default, because it can slow down property searches ++significantly and is often not needed. However, if you find inheritance ++useful, you can turn it on by setting the variable ++@code{org-use-property-inheritance}. It may be set to @code{t}, to make ++all properties inherited from the parent, to a list of properties ++that should be inherited, or to a regular expression that matches ++inherited properties. ++ ++Org mode has a few properties for which inheritance is hard-coded, at ++least for the special applications for which they are used: ++ ++@table @code ++@item COLUMNS ++The @code{:COLUMNS:} property defines the format of column view ++(@pxref{Column view}). It is inherited in the sense that the level ++where a @code{:COLUMNS:} property is defined is used as the starting ++point for a column view table, independently of the location in the ++subtree from where columns view is turned on. ++@item CATEGORY ++For agenda view, a category set through a @code{:CATEGORY:} property ++applies to the entire subtree. ++@item ARCHIVE ++For archiving, the @code{:ARCHIVE:} property may define the archive ++location for the entire subtree (@pxref{Moving subtrees}). ++@item LOGGING ++The LOGGING property may define logging settings for an entry or a ++subtree (@pxref{Tracking TODO state changes}). ++@end table ++ ++@node Column view, Property API, Property inheritance, Properties and Columns ++@section Column view ++ ++A great way to view and edit properties in an outline tree is ++@emph{column view}. In column view, each outline item is turned into a ++table row. Columns in this table provide access to properties of the ++entries. Org mode implements columns by overlaying a tabular structure ++over the headline of each item. While the headlines have been turned ++into a table row, you can still change the visibility of the outline ++tree. For example, you get a compact table by switching to CONTENTS ++view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view ++is active), but you can still open, read, and edit the entry below each ++headline. Or, you can switch to column view after executing a sparse ++tree command and in this way get a table only for the selected items. ++Column view also works in agenda buffers (@pxref{Agenda Views}) where ++queries have collected selected items, possibly from a number of files. ++ ++@menu ++* Defining columns:: The COLUMNS format property ++* Using column view:: How to create and use column view ++* Capturing column view:: A dynamic block for column view ++@end menu ++ ++@node Defining columns, Using column view, Column view, Column view ++@subsection Defining columns ++@cindex column view, for properties ++@cindex properties, column view ++ ++Setting up a column view first requires defining the columns. This is ++done by defining a column format line. ++ ++@menu ++* Scope of column definitions:: Where defined, where valid? ++* Column attributes:: Appearance and content of a column ++@end menu ++ ++@node Scope of column definitions, Column attributes, Defining columns, Defining columns ++@subsubsection Scope of column definitions ++ ++To define a column format for an entire file, use a line like ++ ++@example ++#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO ++@end example ++ ++To specify a format that only applies to a specific tree, add a ++@code{:COLUMNS:} property to the top node of that tree, for example: ++ ++@example ++** Top node for columns view ++ :PROPERTIES: ++ :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO ++ :END: ++@end example ++ ++If a @code{:COLUMNS:} property is present in an entry, it defines columns ++for the entry itself, and for the entire subtree below it. Since the ++column definition is part of the hierarchical structure of the document, ++you can define columns on level 1 that are general enough for all ++sublevels, and more specific columns further down, when you edit a ++deeper part of the tree. ++ ++@node Column attributes, , Scope of column definitions, Defining columns ++@subsubsection Column attributes ++A column definition sets the attributes of a column. The general ++definition looks like this: ++ ++@example ++ %[width]property[(title)][@{summary-type@}] ++@end example ++ ++@noindent ++Except for the percent sign and the property name, all items are ++optional. The individual parts have the following meaning: ++ ++@example ++width @r{An integer specifying the width of the column in characters.} ++ @r{If omitted, the width will be determined automatically.} ++property @r{The property that should be edited in this column.} ++(title) @r{The header text for the column. If omitted, the} ++ @r{property name is used.} ++@{summary-type@} @r{The summary type. If specified, the column values for} ++ @r{parent nodes are computed from the children.} ++ @r{Supported summary types are:} ++ @{+@} @r{Sum numbers in this column.} ++ @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.} ++ @{$@} @r{Currency, short for @samp{+;%.2f}.} ++ @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.} ++ @{X@} @r{Checkbox status, [X] if all children are [X].} ++ @{X/@} @r{Checkbox status, [n/m].} ++ @{X%@} @r{Checkbox status, [n%].} ++@end example ++ ++@noindent ++Here is an example for a complete columns definition, along with allowed ++values. ++ ++@example ++:COLUMNS: %20ITEM %9Approved(Approved?)@{X@} %Owner %11Status \@footnote{Please note that the COLUMNS definition must be on a single line - it is wrapped here only because of formatting constraints.} ++ %10Time_Estimate@{:@} %CLOCKSUM ++:Owner_ALL: Tammy Mark Karl Lisa Don ++:Status_ALL: "In progress" "Not started yet" "Finished" "" ++:Approved_ALL: "[ ]" "[X]" ++@end example ++ ++The first column, @samp{%25ITEM}, means the first 25 characters of the ++item itself, i.e. of the headline. You probably always should start the ++column definition with the @samp{ITEM} specifier. The other specifiers ++create columns @samp{Owner} with a list of names as allowed values, for ++@samp{Status} with four different possible values, and for a checkbox ++field @samp{Approved}. When no width is given after the @samp{%} ++character, the column will be exactly as wide as it needs to be in order ++to fully display all values. The @samp{Approved} column does have a ++modified title (@samp{Approved?}, with a question mark). Summaries will ++be created for the @samp{Time_Estimate} column by adding time duration ++expressions like HH:MM, and for the @samp{Approved} column, by providing ++an @samp{[X]} status if all children have been checked. The ++@samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervals ++in the subtree. ++ ++@node Using column view, Capturing column view, Defining columns, Column view ++@subsection Using column view ++ ++@table @kbd ++@tsubheading{Turning column view on and off} ++@kindex C-c C-x C-c ++@item C-c C-x C-c ++Create the column view for the local environment. This command searches ++the hierarchy, up from point, for a @code{:COLUMNS:} property that defines ++a format. When one is found, the column view table is established for ++the entire tree, starting from the entry that contains the @code{:COLUMNS:} ++property. If none is found, the format is taken from the @code{#+COLUMNS} ++line or from the variable @code{org-columns-default-format}, and column ++view is established for the current entry and its subtree. ++@kindex r ++@item r ++Recreate the column view, to include recent changes made in the buffer. ++@kindex g ++@item g ++Same as @kbd{r}. ++@kindex q ++@item q ++Exit column view. ++@tsubheading{Editing values} ++@item @key{left} @key{right} @key{up} @key{down} ++Move through the column view from field to field. ++@kindex S-@key{left} ++@kindex S-@key{right} ++@item S-@key{left}/@key{right} ++Switch to the next/previous allowed value of the field. For this, you ++have to have specified allowed values for a property. ++@item 1..9,0 ++Directly select the nth allowed value, @kbd{0} selects the 10th value. ++@kindex n ++@kindex p ++@itemx n / p ++Same as @kbd{S-@key{left}/@key{right}} ++@kindex e ++@item e ++Edit the property at point. For the special properties, this will ++invoke the same interface that you normally use to change that ++property. For example, when editing a TAGS property, the tag completion ++or fast selection interface will pop up. ++@kindex C-c C-c ++@item C-c C-c ++When there is a checkbox at point, toggle it. ++@kindex v ++@item v ++View the full value of this property. This is useful if the width of ++the column is smaller than that of the value. ++@kindex a ++@item a ++Edit the list of allowed values for this property. If the list is found ++in the hierarchy, the modified values is stored there. If no list is ++found, the new value is stored in the first entry that is part of the ++current column view. ++@tsubheading{Modifying the table structure} ++@kindex < ++@kindex > ++@item < / > ++Make the column narrower/wider by one character. ++@kindex S-M-@key{right} ++@item S-M-@key{right} ++Insert a new column, to the left of the current column. ++@kindex S-M-@key{left} ++@item S-M-@key{left} ++Delete the current column. ++@end table ++ ++@node Capturing column view, , Using column view, Column view ++@subsection Capturing column view ++ ++Since column view is just an overlay over a buffer, it cannot be ++exported or printed directly. If you want to capture a column view, use ++this @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame ++of this block looks like this: ++ ++@cindex #+BEGIN: columnview ++@example ++* The column view ++#+BEGIN: columnview :hlines 1 :id "label" ++ ++#+END: ++@end example ++ ++@noindent This dynamic block has the following parameters: ++ ++@table @code ++@item :id ++This is most important parameter. Column view is a feature that is ++often localized to a certain (sub)tree, and the capture block might be ++in a different location in the file. To identify the tree whose view to ++capture, you can use 3 values: ++@example ++local @r{use the tree in which the capture block is located} ++global @r{make a global view, including all headings in the file} ++"file:path-to-file" ++ @r{run column view at the top of this file} ++"ID" @r{call column view in the tree that has an @code{:ID:}} ++ @r{property with the value @i{label}. You can use} ++ @r{@kbd{M-x org-id-copy} to create a globally unique ID for} ++ @r{the current entry and copy it to the kill-ring.} ++@end example ++@item :hlines ++When @code{t}, insert a hline after every line. When a number N, insert ++a hline before each headline with level @code{<= N}. ++@item :vlines ++When set to @code{t}, enforce column groups to get vertical lines. ++@item :maxlevel ++When set to a number, don't capture entries below this level. ++@item :skip-empty-rows ++When set to @code{t}, skip row where the only non-empty specifier of the ++column view is @code{ITEM}. ++ ++@end table ++ ++@noindent ++The following commands insert or update the dynamic block: ++ ++@table @kbd ++@kindex C-c C-x i ++@item C-c C-x i ++Insert a dynamic block capturing a column view. You will be prompted ++for the scope or id of the view. ++@kindex C-c C-c ++@item C-c C-c ++@kindex C-c C-x C-u ++@itemx C-c C-x C-u ++Update dynamical block at point. The cursor needs to be in the ++@code{#+BEGIN} line of the dynamic block. ++@kindex C-u C-c C-x C-u ++@item C-u C-c C-x C-u ++Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if ++you have several clock table blocks in a buffer. ++@end table ++ ++You can add formulas to the column view table and you may add plotting ++instructions in front of the table - these will survive an update of the ++block. If there is a @code{#+TBLFM:} after the table, the table will ++actually be recalculated automatically after an update. ++ ++@node Property API, , Column view, Properties and Columns ++@section The Property API ++@cindex properties, API ++@cindex API, for properties ++ ++There is a full API for accessing and changing properties. This API can ++be used by Emacs Lisp programs to work with properties and to implement ++features based on them. For more information see @ref{Using the ++property API}. ++ ++@node Dates and Times, Capture, Properties and Columns, Top ++@chapter Dates and Times ++@cindex dates ++@cindex times ++@cindex time stamps ++@cindex date stamps ++ ++To assist project planning, TODO items can be labeled with a date and/or ++a time. The specially formatted string carrying the date and time ++information is called a @emph{timestamp} in Org mode. This may be a ++little confusing because timestamp is often used as indicating when ++something was created or last changed. However, in Org mode this term ++is used in a much wider sense. ++ ++@menu ++* Timestamps:: Assigning a time to a tree entry ++* Creating timestamps:: Commands which insert timestamps ++* Deadlines and scheduling:: Planning your work ++* Clocking work time:: Tracking how long you spend on a task ++* Effort estimates:: Planning work effort in advance ++* Relative timer:: Notes with a running timer ++@end menu ++ ++ ++@node Timestamps, Creating timestamps, Dates and Times, Dates and Times ++@section Timestamps, deadlines and scheduling ++@cindex time stamps ++@cindex ranges, time ++@cindex date stamps ++@cindex deadlines ++@cindex scheduling ++ ++A time stamp is a specification of a date (possibly with time or a range ++of times) in a special format, either @samp{<2003-09-16 Tue>} or ++@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue ++12:00-12:30>}@footnote{This is the standard ISO date/time format. To ++use an alternative format, see @ref{Custom time format}.}. A time stamp ++can appear anywhere in the headline or body of an Org tree entry. Its ++presence causes entries to be shown on specific dates in the agenda ++(@pxref{Weekly/daily agenda}). We distinguish: ++ ++@table @var ++@item Plain time stamp; Event; Appointment ++@cindex timestamp ++A simple time stamp just assigns a date/time to an item. This is just ++like writing down an appointment or event in a paper agenda. In the ++timeline and agenda displays, the headline of an entry associated with a ++plain time stamp will be shown exactly on that date. ++ ++@example ++* Meet Peter at the movies <2006-11-01 Wed 19:15> ++* Discussion on climate change <2006-11-02 Thu 20:00-22:00> ++@end example ++ ++@item Time stamp with repeater interval ++@cindex timestamp, with repeater interval ++A time stamp may contain a @emph{repeater interval}, indicating that it ++applies not only on the given date, but again and again after a certain ++interval of N days (d), weeks (w), months(m), or years(y). The ++following will show up in the agenda every Wednesday: ++ ++@example ++* Pick up Sam at school <2007-05-16 Wed 12:30 +1w> ++@end example ++ ++@item Diary-style sexp entries ++For more complex date specifications, Org mode supports using the ++special sexp diary entries implemented in the Emacs calendar/diary ++package. For example ++ ++@example ++* The nerd meeting on every 2nd Thursday of the month ++ <%%(diary-float t 4 2)> ++@end example ++ ++@item Time/Date range ++@cindex timerange ++@cindex date range ++Two time stamps connected by @samp{--} denote a range. The headline ++will be shown on the first and last day of the range, and on any dates ++that are displayed and fall in the range. Here is an example: ++ ++@example ++** Meeting in Amsterdam ++ <2004-08-23 Mon>--<2004-08-26 Thu> ++@end example ++ ++@item Inactive time stamp ++@cindex timestamp, inactive ++@cindex inactive timestamp ++Just like a plain time stamp, but with square brackets instead of ++angular ones. These time stamps are inactive in the sense that they do ++@emph{not} trigger an entry to show up in the agenda. ++ ++@example ++* Gillian comes late for the fifth time [2006-11-01 Wed] ++@end example ++ ++@end table ++ ++@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times ++@section Creating timestamps ++@cindex creating timestamps ++@cindex timestamps, creating ++ ++For Org mode to recognize time stamps, they need to be in the specific ++format. All commands listed below produce time stamps in the correct ++format. ++ ++@table @kbd ++@kindex C-c . ++@item C-c . ++Prompt for a date and insert a corresponding time stamp. When the cursor is ++at an existing time stamp in the buffer, the command is used to modify this ++timestamp instead of inserting a new one. When this command is used twice in ++succession, a time range is inserted. ++@c ++@kindex C-u C-c . ++@item C-u C-c . ++Like @kbd{C-c .}, but use the alternative format which contains date ++and time. The default time can be rounded to multiples of 5 minutes, ++see the option @code{org-time-stamp-rounding-minutes}. ++@c ++@kindex C-c ! ++@item C-c ! ++Like @kbd{C-c .}, but insert an inactive time stamp that will not cause ++an agenda entry. ++@c ++@kindex C-c < ++@item C-c < ++Insert a time stamp corresponding to the cursor date in the Calendar. ++@c ++@kindex C-c > ++@item C-c > ++Access the Emacs calendar for the current date. If there is a ++timestamp in the current line, go to the corresponding date ++instead. ++@c ++@kindex C-c C-o ++@item C-c C-o ++Access the agenda for the date given by the time stamp or -range at ++point (@pxref{Weekly/daily agenda}). ++@c ++@kindex S-@key{left} ++@kindex S-@key{right} ++@item S-@key{left} ++@itemx S-@key{right} ++Change date at cursor by one day. These key bindings conflict with ++CUA mode (@pxref{Conflicts}). ++@c ++@kindex S-@key{up} ++@kindex S-@key{down} ++@item S-@key{up} ++@itemx S-@key{down} ++Change the item under the cursor in a timestamp. The cursor can be on a ++year, month, day, hour or minute. Note that if the cursor is in a ++headline and not at a time stamp, these same keys modify the priority of ++an item. (@pxref{Priorities}). The key bindings also conflict with ++CUA mode (@pxref{Conflicts}). ++@c ++@kindex C-c C-y ++@cindex evaluate time range ++@item C-c C-y ++Evaluate a time range by computing the difference between start and end. ++With a prefix argument, insert result after the time range (in a table: into ++the following column). ++@end table ++ ++ ++@menu ++* The date/time prompt:: How Org mode helps you entering date and time ++* Custom time format:: Making dates look different ++@end menu ++ ++@node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps ++@subsection The date/time prompt ++@cindex date, reading in minibuffer ++@cindex time, reading in minibuffer ++ ++When Org mode prompts for a date/time, the default is shown as an ISO ++date, and the prompt therefore seems to ask for an ISO date. But it ++will in fact accept any string containing some date and/or time ++information, and it is really smart about interpreting your input. You ++can, for example, use @kbd{C-y} to paste a (possibly multi-line) string ++copied from an email message. Org mode will find whatever information ++is in there and derive anything you have not specified from the ++@emph{default date and time}. The default is usually the current date ++and time, but when modifying an existing time stamp, or when entering ++the second stamp of a range, it is taken from the stamp in the buffer. ++When filling in information, Org mode assumes that most of the time you ++will want to enter a date in the future: If you omit the month/year and ++the given day/month is @i{before} today, it will assume that you mean a ++future date@footnote{See the variable ++@code{org-read-date-prefer-future}.}. ++ ++For example, let's assume that today is @b{June 13, 2006}. Here is how ++various inputs will be interpreted, the items filled in by Org mode are ++in @b{bold}. ++ ++@example ++3-2-5 --> 2003-02-05 ++14 --> @b{2006}-@b{06}-14 ++12 --> @b{2006}-@b{07}-12 ++Fri --> nearest Friday (defaultdate or later) ++sep 15 --> @b{2006}-09-15 ++feb 15 --> @b{2007}-02-15 ++sep 12 9 --> 2009-09-12 ++12:45 --> @b{2006}-@b{06}-@b{13} 12:45 ++22 sept 0:34 --> @b{2006}-09-22 0:34 ++w4 --> ISO week for of the current year @b{2006} ++2012 w4 fri --> Friday of ISO week 4 in 2012 ++2012-w04-5 --> Same as above ++@end example ++ ++Furthermore you can specify a relative date by giving, as the ++@emph{first} thing in the input: a plus/minus sign, a number and a ++letter [dwmy] to indicate change in days weeks, months, years. With a ++single plus or minus, the date is always relative to today. With a ++double plus or minus, it is relative to the default date. If instead of ++a single letter, you use the abbreviation of day name, the date will be ++the nth such day. E.g. ++ ++@example +++0 --> today ++. --> today +++4d --> four days from today +++4 --> same as above +++2w --> two weeks from today ++++5 --> five days from default date +++2tue --> second tuesday from now. ++@end example ++ ++The function understands English month and weekday abbreviations. If ++you want to use unabbreviated names and/or other languages, configure ++the variables @code{parse-time-months} and @code{parse-time-weekdays}. ++ ++@cindex calendar, for selecting date ++Parallel to the minibuffer prompt, a calendar is popped up@footnote{If ++you don't need/want the calendar, configure the variable ++@code{org-popup-calendar-for-date-prompt}.}. When you exit the date ++prompt, either by clicking on a date in the calendar, or by pressing ++@key{RET}, the date selected in the calendar will be combined with the ++information entered at the prompt. You can control the calendar fully ++from the minibuffer: ++ ++@kindex < ++@kindex > ++@kindex mouse-1 ++@kindex S-@key{right} ++@kindex S-@key{left} ++@kindex S-@key{down} ++@kindex S-@key{up} ++@kindex M-S-@key{right} ++@kindex M-S-@key{left} ++@kindex @key{RET} ++@example ++> / < @r{Scroll calendar forward/backward by one month.} ++mouse-1 @r{Select date by clicking on it.} ++S-@key{right}/@key{left} @r{One day forward/backward.} ++S-@key{down}/@key{up} @r{One week forward/backward.} ++M-S-@key{right}/@key{left} @r{One month forward/backward.} ++@key{RET} @r{Choose date in calendar.} ++@end example ++ ++The actions of the date/time prompt may seem complex, but I assure you they ++will grow on you, and you will start getting annoyed by pretty much any other ++way of entering a date/time out there. To help you understand what is going ++on, the current interpretation of your input will be displayed live in the ++minibuffer@footnote{If you find this distracting, turn the display of with ++@code{org-read-date-display-live}.}. ++ ++@node Custom time format, , The date/time prompt, Creating timestamps ++@subsection Custom time format ++@cindex custom date/time format ++@cindex time format, custom ++@cindex date format, custom ++ ++Org mode uses the standard ISO notation for dates and times as it is ++defined in ISO 8601. If you cannot get used to this and require another ++representation of date and time to keep you happy, you can get it by ++customizing the variables @code{org-display-custom-times} and ++@code{org-time-stamp-custom-formats}. ++ ++@table @kbd ++@kindex C-c C-x C-t ++@item C-c C-x C-t ++Toggle the display of custom formats for dates and times. ++@end table ++ ++@noindent ++Org mode needs the default format for scanning, so the custom date/time ++format does not @emph{replace} the default format - instead it is put ++@emph{over} the default format using text properties. This has the ++following consequences: ++@itemize @bullet ++@item ++You cannot place the cursor onto a time stamp anymore, only before or ++after. ++@item ++The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust ++each component of a time stamp. If the cursor is at the beginning of ++the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day, ++just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the ++time will be changed by one minute. ++@item ++If the time stamp contains a range of clock times or a repeater, these ++will not be overlayed, but remain in the buffer as they were. ++@item ++When you delete a time stamp character-by-character, it will only ++disappear from the buffer after @emph{all} (invisible) characters ++belonging to the ISO timestamp have been removed. ++@item ++If the custom time stamp format is longer than the default and you are ++using dates in tables, table alignment will be messed up. If the custom ++format is shorter, things do work as expected. ++@end itemize ++ ++ ++@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times ++@section Deadlines and scheduling ++ ++A time stamp may be preceded by special keywords to facilitate planning: ++ ++@table @var ++@item DEADLINE ++@cindex DEADLINE keyword ++ ++Meaning: the task (most likely a TODO item, though not necessarily) is supposed ++to be finished on that date. ++ ++On the deadline date, the task will be listed in the agenda. In ++addition, the agenda for @emph{today} will carry a warning about the ++approaching or missed deadline, starting ++@code{org-deadline-warning-days} before the due date, and continuing ++until the entry is marked DONE. An example: ++ ++@example ++*** TODO write article about the Earth for the Guide ++ The editor in charge is [[bbdb:Ford Prefect]] ++ DEADLINE: <2004-02-29 Sun> ++@end example ++ ++You can specify a different lead time for warnings for a specific ++deadlines using the following syntax. Here is an example with a warning ++period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. ++ ++@item SCHEDULED ++@cindex SCHEDULED keyword ++ ++Meaning: you are planning to start working on that task on the given ++date. ++ ++The headline will be listed under the given date@footnote{It will still ++be listed on that date after it has been marked DONE. If you don't like ++this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In ++addition, a reminder that the scheduled date has passed will be present ++in the compilation for @emph{today}, until the entry is marked DONE. ++I.e., the task will automatically be forwarded until completed. ++ ++@example ++*** TODO Call Trillian for a date on New Years Eve. ++ SCHEDULED: <2004-12-25 Sat> ++@end example ++ ++@noindent ++@b{Important:} Scheduling an item in Org mode should @i{not} be ++understood in the same way that we understand @i{scheduling a meeting}. ++Setting a date for a meeting is just a simple appointment, you should ++mark this entry with a simple plain time stamp, to get this item shown ++on the date where it applies. This is a frequent mis-understanding from ++Org-users. In Org mode, @i{scheduling} means setting a date when you ++want to start working on an action item. ++@end table ++ ++You may use time stamps with repeaters in scheduling and deadline ++entries. Org mode will issue early and late warnings based on the ++assumption that the time stamp represents the @i{nearest instance} of ++the repeater. However, the use of diary sexp entries like ++@c ++@code{<%%(diary-float t 42)>} ++@c ++in scheduling and deadline timestamps is limited. Org mode does not ++know enough about the internals of each sexp function to issue early and ++late warnings. However, it will show the item on each day where the ++sexp entry matches. ++ ++@menu ++* Inserting deadline/schedule:: Planning items ++* Repeated tasks:: Items that show up again and again ++@end menu ++ ++@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling ++@subsection Inserting deadlines or schedules ++ ++The following commands allow to quickly insert a deadline or to schedule ++an item: ++ ++@table @kbd ++@c ++@kindex C-c C-d ++@item C-c C-d ++Insert @samp{DEADLINE} keyword along with a stamp. The insertion will ++happen in the line directly following the headline. When called with a ++prefix arg, an existing deadline will be removed from the entry. ++@c FIXME Any CLOSED timestamp will be removed.???????? ++@c ++@kindex C-c / d ++@cindex sparse tree, for deadlines ++@item C-c / d ++Create a sparse tree with all deadlines that are either past-due, or ++which will become due within @code{org-deadline-warning-days}. ++With @kbd{C-u} prefix, show all deadlines in the file. With a numeric ++prefix, check that many days. For example, @kbd{C-1 C-c / d} shows ++all deadlines due tomorrow. ++@c ++@kindex C-c C-s ++@item C-c C-s ++Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will ++happen in the line directly following the headline. Any CLOSED ++timestamp will be removed. When called with a prefix argument, remove ++the scheduling date from the entry. ++@c ++@kindex C-c C-x C-k ++@kindex k a ++@kindex k s ++@item C-c C-x C-k ++Mark the current entry for agenda action. After you have marked the entry ++like this, you can open the agenda or the calendar to find an appropriate ++date. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to ++schedule the marked item. ++@end table ++ ++@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling ++@subsection Repeated tasks ++ ++Some tasks need to be repeated again and again. Org mode helps to ++organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, ++or plain time stamp. In the following example ++@example ++** TODO Pay the rent ++ DEADLINE: <2005-10-01 Sat +1m> ++@end example ++the @code{+1m} is a repeater; the intended interpretation is that the ++task has a deadline on <2005-10-01> and repeats itself every (one) month ++starting from that time. If you need both a repeater and a special ++warning period in a deadline entry, the repeater comes first and the ++warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}. ++ ++Deadlines and scheduled items produce entries in the agenda when they ++are over-due, so it is important to be able to mark such an entry as ++completed once you have done so. When you mark a DEADLINE or a SCHEDULE ++with the TODO keyword DONE, it will no longer produce entries in the ++agenda. The problem with this is, however, that then also the ++@emph{next} instance of the repeated entry will not be active. Org mode ++deals with this in the following way: When you try to mark such an entry ++DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating ++time stamp by the repeater interval, and immediately set the entry state ++back to TODO. In the example above, setting the state to DONE would ++actually switch the date like this: ++ ++@example ++** TODO Pay the rent ++ DEADLINE: <2005-11-01 Tue +1m> ++@end example ++ ++A timestamp@footnote{You can change this using the option ++@code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat}, ++@code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you ++will also be prompted for a note.} will be added under the deadline, to keep ++a record that you actually acted on the previous instance of this deadline. ++ ++As a consequence of shifting the base date, this entry will no longer be ++visible in the agenda when checking past dates, but all future instances ++will be visible. ++ ++With the @samp{+1m} cookie, the date shift will always be exactly one ++month. So if you have not payed the rent for three months, marking this ++entry DONE will still keep it as an overdue deadline. Depending on the ++task, this may not be the best way to handle it. For example, if you ++forgot to call you father for 3 weeks, it does not make sense to call ++him 3 times in a single day to make up for it. Finally, there are tasks ++like changing batteries which should always repeat a certain time ++@i{after} the last time you did it. For these tasks, Org mode has ++special repeaters markers with @samp{++} and @samp{.+}. For example: ++ ++@example ++** TODO Call Father ++ DEADLINE: <2008-02-10 Sun ++1w> ++ Marking this DONE will shift the date by at least one week, ++ but also by as many weeks as it takes to get this date into ++ the future. However, it stays on a Sunday, even if you called ++ and marked it done on Saturday. ++** TODO Check the batteries in the smoke detectors ++ DEADLINE: <2005-11-01 Tue .+1m> ++ Marking this DONE will shift the date to one month after ++ today. ++@end example ++ ++You may have both scheduling and deadline information for a specific ++task - just make sure that the repeater intervals on both are the same. ++ ++@node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and Times ++@section Clocking work time ++ ++Org mode allows you to clock the time you spent on specific tasks in a ++project. When you start working on an item, you can start the clock. ++When you stop working on that task, or when you mark the task done, the ++clock is stopped and the corresponding time interval is recorded. It ++also computes the total time spent on each subtree of a project. ++ ++@table @kbd ++@kindex C-c C-x C-i ++@item C-c C-x C-i ++Start the clock on the current item (clock-in). This inserts the CLOCK ++keyword together with a timestamp. If this is not the first clocking of ++this item, the multiple CLOCK lines will be wrapped into a ++@code{:CLOCK:} drawer (see also the variable ++@code{org-clock-into-drawer}). When called with a @kbd{C-u} prefix argument, ++select the task from a list of recently clocked tasks. With two @kbd{C-u ++C-u} prefixes, clock into the task at point and mark it as the default task. ++The default task will always be available when selecting a clocking task, ++with letter @kbd{d}. ++@kindex C-c C-x C-o ++@item C-c C-x C-o ++Stop the clock (clock-out). This inserts another timestamp at the same ++location where the clock was last started. It also directly computes ++the resulting time in inserts it after the time range as @samp{=> ++HH:MM}. See the variable @code{org-log-note-clock-out} for the ++possibility to record an additional note together with the clock-out ++time stamp@footnote{The corresponding in-buffer setting is: ++@code{#+STARTUP: lognoteclock-out}}. ++@kindex C-c C-y ++@item C-c C-y ++Recompute the time interval after changing one of the time stamps. This ++is only necessary if you edit the time stamps directly. If you change ++them with @kbd{S-@key{cursor}} keys, the update is automatic. ++@kindex C-c C-t ++@item C-c C-t ++Changing the TODO state of an item to DONE automatically stops the clock ++if it is running in this same item. ++@kindex C-c C-x C-x ++@item C-c C-x C-x ++Cancel the current clock. This is useful if a clock was started by ++mistake, or if you ended up working on something else. ++@kindex C-c C-x C-j ++@item C-c C-x C-j ++Jump to the entry that contains the currently running clock. With a ++@kbd{C-u} prefix arg, select the target task from a list of recently clocked ++tasks. ++@kindex C-c C-x C-d ++@item C-c C-x C-d ++Display time summaries for each subtree in the current buffer. This ++puts overlays at the end of each headline, showing the total time ++recorded under that heading, including the time of any subheadings. You ++can use visibility cycling to study the tree, but the overlays disappear ++when you change the buffer (see variable ++@code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}. ++@kindex C-c C-x C-r ++@item C-c C-x C-r ++Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock ++report as an Org mode table into the current file. When the cursor is ++at an existing clock table, just update it. When called with a prefix ++argument, jump to the first clock report in the current document and ++update it. ++@cindex #+BEGIN: clocktable ++@example ++#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file ++#+END: clocktable ++@end example ++@noindent ++If such a block already exists at point, its content is replaced by the ++new table. The @samp{BEGIN} line can specify options: ++@example ++:maxlevel @r{Maximum level depth to which times are listed in the table.} ++:emphasize @r{When @code{t}, emphasize level one and level two items} ++:scope @r{The scope to consider. This can be any of the following:} ++ nil @r{the current buffer or narrowed region} ++ file @r{the full current buffer} ++ subtree @r{the subtree where the clocktable is located} ++ treeN @r{the surrounding level N tree, for example @code{tree3}} ++ tree @r{the surrounding level 1 tree} ++ agenda @r{all agenda files} ++ ("file"..) @r{scan these files} ++ file-with-archives @r{current file and its archives} ++ agenda-with-archives @r{all agenda files, including archives} ++:block @r{The time block to consider. This block is specified either} ++ @r{absolute, or relative to the current time and may be any of} ++ @r{these formats:} ++ 2007-12-31 @r{New year eve 2007} ++ 2007-12 @r{December 2007} ++ 2007-W50 @r{ISO-week 50 in 2007} ++ 2007 @r{the year 2007} ++ today, yesterday, today-N @r{a relative day} ++ thisweek, lastweek, thisweek-N @r{a relative week} ++ thismonth, lastmonth, thismonth-N @r{a relative month} ++ thisyear, lastyear, thisyear-N @r{a relative year} ++ @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.} ++:tstart @r{A time string specifying when to start considering times} ++:tend @r{A time string specifying when to stop considering times} ++:step @r{@code{week} or @code{day}, to split the table into chunks.} ++ @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.} ++:link @r{Link the item headlines in the table to their origins} ++:formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.} ++ @r{As a special case, @samp{:formula %} adds column with % time.} ++ @r{If you do not specify a formula here, any existing formula} ++ @r{below the clock table will survive updates and be evaluated.} ++@end example ++So to get a clock summary of the current level 1 tree, for the current ++day, you could write ++@example ++#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t ++#+END: clocktable ++@end example ++and to use a specific time range you could write@footnote{Note that all ++parameters must be specified in a single line - the line is broken here ++only to fit it onto the manual.} ++@example ++#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" ++ :tend "<2006-08-10 Thu 12:00>" ++#+END: clocktable ++@end example ++A summary of the current subtree with % times would be ++@example ++#+BEGIN: clocktable :scope subtree :link t :formula % ++#+END: clocktable ++@end example ++@kindex C-c C-c ++@item C-c C-c ++@kindex C-c C-x C-u ++@itemx C-c C-x C-u ++Update dynamical block at point. The cursor needs to be in the ++@code{#+BEGIN} line of the dynamic block. ++@kindex C-u C-c C-x C-u ++@item C-u C-c C-x C-u ++Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if ++you have several clock table blocks in a buffer. ++@kindex S-@key{left} ++@kindex S-@key{right} ++@item S-@key{left} ++@itemx S-@key{right} ++Shift the current @code{:block} interval and update the table. The cursor ++needs to be in the @code{#+BEGIN: clocktable} line for this command. If ++@code{:block} is @code{today}, it will be shifted to @code{today-1} etc. ++@end table ++ ++The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in ++the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been ++worked on or closed during a day. ++ ++@node Effort estimates, Relative timer, Clocking work time, Dates and Times ++@section Effort estimates ++@cindex effort estimates ++ ++If you want to plan your work in a very detailed way, or if you need to ++produce offers with quotations of the estimated work effort, you may want to ++assign effort estimates to entries. If you are also clocking your work, you ++may later want to compare the planned effort with the actual working time, a ++great way to improve planning estimates. Effort estimates are stored in a ++special property @samp{Effort}@footnote{You may change the property being ++used with the variable @code{org-effort-property}.}. Clearly the best way to ++work with effort estimates is through column view (@pxref{Column view}). You ++should start by setting up discrete values for effort estimates, and a ++@code{COLUMNS} format that displays these values together with clock sums (if ++you want to clock your time). For a specific buffer you can use ++ ++@example ++#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 8:00 ++#+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM ++@end example ++ ++@noindent ++or, even better, you can set up these values globally by customizing the ++variables @code{org-global-properties} and @code{org-columns-default-format}. ++In particular if you want to use this setup also in the agenda, a global ++setup may be advised. ++ ++The way to assign estimates to individual items is then to switch to column ++mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the ++value. The values you enter will immediately be summed up in the hierarchy. ++In the column next to it, any clocked time will be displayed. ++ ++If you switch to column view in the daily/weekly agenda, the effort column ++will summarize the estimated work effort for each day@footnote{Please note ++the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda ++column view}).}, and you can use this to find space in your schedule. To get ++an overview of the entire part of the day that is committed, you can set the ++option @code{org-agenda-columns-add-appointments-to-effort-sum}. The ++appointments on a day that take place over a specified time interval will ++then also be added to the load estimate of the day. ++ ++Effort estimates can be used in secondary agenda filtering that is triggered ++with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have ++these estimates defined consistently, two or three key presses will narrow ++down the list to stuff that fits into an available time slot. ++ ++@node Relative timer, , Effort estimates, Dates and Times ++@section Taking notes with a relative timer ++@cindex relative timer ++ ++When taking notes during, for example, a meeting or a video viewing, it can ++be useful to have access to times relative to a starting time. Org provides ++such a relative timer and make it easy to create timed notes. ++ ++@table @kbd ++@kindex C-c C-x . ++@item C-c C-x . ++Insert a relative time into the buffer. The first time you use this, the ++timer will be started. When called with a prefix argument, the timer is ++restarted. ++@kindex C-c C-x - ++@item C-c C-x - ++Insert a description list item with the current relative time. With a prefix ++argument, first reset the timer to 0. ++@kindex M-@key{RET} ++@item M-@key{RET} ++Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert ++new timer items. ++@kindex C-c C-x , ++@item C-c C-x , ++Pause the timer, or continue it if it is already paused. With prefix ++argument, stop it entirely. ++@kindex C-u C-c C-x , ++@item C-u C-c C-x , ++Stop the timer. After this, you can only start a new timer, not continue the ++old one. This command also removes the timer from the mode line. ++@kindex C-c C-x 0 ++@item C-c C-x 0 ++Reset the timer without inserting anything into the buffer. By default, the ++timer is reset to 0. When called with a @kbd{C-u} prefix, reset the timer to ++specific starting offset. The user is prompted for the offset, with a ++default taken from a timer string at point, if any, So this can be used to ++restart taking notes after a break in the process. When called with a double ++prefix argument @kbd{C-c C-u}, change all timer strings in the active region ++by a certain amount. This can be used to fix timer strings if the timer was ++not started at exactly the right moment. ++@end table ++ ++@node Capture, Agenda Views, Dates and Times, Top ++@chapter Capture ++@cindex capture ++ ++An important part of any organization system is the ability to quickly ++capture new ideas and tasks, and to associate reference material with them. ++Org uses the @file{remember} package to create tasks, and stores files ++related to a task (@i{attachments}) in a special directory. ++ ++@menu ++* Remember:: Capture new tasks/ideas with little interruption ++* Attachments:: Add files to tasks. ++@end menu ++ ++@node Remember, Attachments, Capture, Capture ++@section Remember ++@cindex @file{remember.el} ++ ++The @i{Remember} package by John Wiegley lets you store quick notes with ++little interruption of your work flow. See ++@uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more ++information. It is an excellent way to add new notes and tasks to ++Org files. Org significantly expands the possibilities of ++@i{remember}: You may define templates for different note types, and ++associate target files and headlines with specific templates. It also ++allows you to select the location where a note should be stored ++interactively, on the fly. ++ ++@menu ++* Setting up Remember:: Some code for .emacs to get things going ++* Remember templates:: Define the outline of different note types ++* Storing notes:: Directly get the note to where it belongs ++* Refiling notes:: Moving a note or task to a project ++@end menu ++ ++@node Setting up Remember, Remember templates, Remember, Remember ++@subsection Setting up Remember ++ ++The following customization will tell @i{remember} to use org files as ++target, and to create annotations compatible with Org links. ++ ++@example ++(org-remember-insinuate) ++(setq org-directory "~/path/to/my/orgfiles/") ++(setq org-default-notes-file (concat org-directory "/notes.org")) ++(define-key global-map "\C-cr" 'org-remember) ++@end example ++ ++The last line binds the command @code{org-remember} to a global ++key@footnote{Please select your own key, @kbd{C-c r} is only a ++suggestion.}. @code{org-remember} basically just calls @code{remember}, ++but it makes a few things easier: If there is an active region, it will ++automatically copy the region into the remember buffer. It also allows ++to jump to the buffer and location where remember notes are being ++stored: Just call @code{org-remember} with a prefix argument. If you ++use two prefix arguments, Org jumps to the location where the last ++remember note was stored. ++ ++The remember buffer will actually use @code{org-mode} as its major mode, so ++that all editing features of Org-mode are available. In addition to this, a ++minor mode @code{org-remember-mode} is turned on, for the single purpose that ++you can use its keymap @code{org-remember-mode-map} to overwrite some of ++Org-mode's key bindings. ++ ++You can also call @code{org-remember} in a special way from the agenda, ++using the @kbd{k r} key combination. With this access, any time stamps ++inserted by the selected remember template (see below) will default to ++the cursor date in the agenda, rather than to the current date. ++ ++@node Remember templates, Storing notes, Setting up Remember, Remember ++@subsection Remember templates ++@cindex templates, for remember ++ ++In combination with Org, you can use templates to generate ++different types of @i{remember} notes. For example, if you would like ++to use one template to create general TODO entries, another one for ++journal entries, and a third one for collecting random ideas, you could ++use: ++ ++@example ++(setq org-remember-templates ++ '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks") ++ ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") ++ ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) ++@end example ++ ++@noindent In these entries, the first string is just a name, and the ++character specifies how to select the template. It is useful if the ++character is also the first letter of the name. The next string specifies ++the template. Two more (optional) strings give the file in which, and the ++headline under which the new note should be stored. The file (if not present ++or @code{nil}) defaults to @code{org-default-notes-file}, the heading to ++@code{org-remember-default-headline}. If the file name is not an absolute ++path, it will be interpreted relative to @code{org-directory}. The heading ++can also be the symbols @code{top} or @code{bottom} to send note as level 1 ++entries to the beginning or end of the file, respectively. ++ ++An optional sixth element specifies the contexts in which the user can select ++the template. This element can be a list of major modes or a function. ++@code{org-remember} will first check whether the function returns @code{t} or ++if we are in any of the listed major mode, and exclude templates for which ++this condition is not fulfilled. Templates that do not specify this element ++at all, or that use @code{nil} or @code{t} as a value will always be ++selectable. ++ ++So for example: ++ ++@example ++(setq org-remember-templates ++ '(("Bug" ?b "* BUG %?\n %i\n %a" "~/org/BUGS.org" "Bugs" (emacs-lisp-mode)) ++ ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org" "X" my-check) ++ ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) ++@end example ++ ++The first template will only be available when invoking @code{org-remember} ++from an buffer in @code{emacs-lisp-mode}. The second template will only be ++available when the function @code{my-check} returns @code{t}. The third ++template will be proposed in any context. ++ ++When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember ++something, Org will prompt for a key to select the template (if you have ++more than one template) and then prepare the buffer like ++@example ++* TODO ++ [[file:link to where you called remember]] ++@end example ++ ++@noindent ++During expansion of the template, special @kbd{%}-escapes allow dynamic ++insertion of content: ++@example ++%^@{prompt@} @r{prompt the user for a string and replace this sequence with it.} ++ @r{You may specify a default value and a completion table with} ++ @r{%^@{prompt|default|completion2|completion3...@}} ++ @r{The arrow keys access a prompt-specific history.} ++%a @r{annotation, normally the link created with @code{org-store-link}} ++%A @r{like @code{%a}, but prompt for the description part} ++%i @r{initial content, the region when remember is called with C-u.} ++ @r{The entire text will be indented like @code{%i} itself.} ++%t @r{time stamp, date only} ++%T @r{time stamp with date and time} ++%u, %U @r{like the above, but inactive time stamps} ++%^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}} ++ @r{You may define a prompt like @code{%^@{Birthday@}t}} ++%n @r{user name (taken from @code{user-full-name})} ++%c @r{Current kill ring head.} ++%x @r{Content of the X clipboard.} ++%^C @r{Interactive selection of which kill or clip to use.} ++%^L @r{Like @code{%^C}, but insert as link.} ++%^g @r{prompt for tags, with completion on tags in target file.} ++%k @r{title of currently clocked task} ++%K @r{link to currently clocked task} ++%^G @r{prompt for tags, with completion all tags in all agenda files.} ++%^@{prop@}p @r{Prompt the user for a value for property @code{prop}} ++%:keyword @r{specific information for certain link types, see below} ++%[pathname] @r{insert the contents of the file given by @code{pathname}} ++%(sexp) @r{evaluate elisp @code{(sexp)} and replace with the result} ++%! @r{immediately store note after completing the template} ++ @r{(skipping the @kbd{C-c C-c} that normally triggers storing)} ++%& @r{jump to target location immediately after storing note} ++@end example ++ ++@noindent ++For specific link types, the following keywords will be ++defined@footnote{If you define your own link types (@pxref{Adding ++hyperlink types}), any property you store with ++@code{org-store-link-props} can be accessed in remember templates in a ++similar way.}: ++ ++@example ++Link type | Available keywords ++-------------------+---------------------------------------------- ++bbdb | %:name %:company ++bbdb | %::server %:port %:nick ++vm, wl, mh, rmail | %:type %:subject %:message-id ++ | %:from %:fromname %:fromaddress ++ | %:to %:toname %:toaddress ++ | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}} ++gnus | %:group, @r{for messages also all email fields} ++w3, w3m | %:url ++info | %:file %:node ++calendar | %:date" ++@end example ++ ++@noindent ++To place the cursor after template expansion use: ++ ++@example ++%? @r{After completing the template, position cursor here.} ++@end example ++ ++@noindent ++If you change your mind about which template to use, call ++@code{org-remember} in the remember buffer. You may then select a new ++template that will be filled with the previous context information. ++ ++@node Storing notes, Refiling notes, Remember templates, Remember ++@subsection Storing notes ++ ++When you are finished preparing a note with @i{remember}, you have to press ++@kbd{C-c C-c} to file the note away. If you have started the clock in the ++remember buffer, you will first be asked if you want to clock out ++now@footnote{To avoid this query, configure the variable ++@code{org-remember-clock-out-on-exit}.}. If you answer @kbd{n}, the clock ++will continue to run after the note was filed away. ++ ++The handler will then store the note in the file and under the headline ++specified in the template, or it will use the default file and headlines. ++The window configuration will be restored, sending you back to the working ++context before the call to @code{remember}. To re-use the location found ++during the last call to @code{remember}, exit the remember buffer with ++@kbd{C-0 C-c C-c}, i.e. specify a zero prefix argument to @kbd{C-c C-c}. ++Another special case is @kbd{C-2 C-c C-c} which files the note as a child of ++the currently clocked item. ++ ++If you want to store the note directly to a different place, use ++@kbd{C-1 C-c C-c} instead to exit remember@footnote{Configure the ++variable @code{org-remember-store-without-prompt} to make this behavior ++the default.}. The handler will then first prompt for a target file - ++if you press @key{RET}, the value specified for the template is used. ++Then the command offers the headings tree of the selected file, with the ++cursor position at the default headline (if you had specified one in the ++template). You can either immediately press @key{RET} to get the note ++placed there. Or you can use the following keys to find a different ++location: ++@example ++@key{TAB} @r{Cycle visibility.} ++@key{down} / @key{up} @r{Next/previous visible headline.} ++n / p @r{Next/previous visible headline.} ++f / b @r{Next/previous headline same level.} ++u @r{One level up.} ++@c 0-9 @r{Digit argument.} ++@end example ++@noindent ++Pressing @key{RET} or @key{left} or @key{right} ++then leads to the following result. ++ ++@multitable @columnfractions 0.2 0.15 0.65 ++@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted} ++@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor, first or last ++@item @tab @tab depending on @code{org-reverse-note-order}. ++@item @tab @key{left}/@key{right} @tab as same level, before/after current heading ++@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file or level 1 at beginning ++@item @tab @tab depending on @code{org-reverse-note-order}. ++@item not on headline @tab @key{RET} ++ @tab at cursor position, level taken from context. ++@end multitable ++ ++Before inserting the text into a tree, the function ensures that the text has ++a headline, i.e. a first line that starts with a @samp{*}. If not, a ++headline is constructed from the current date. If you have indented the text ++of the note below the headline, the indentation will be adapted if inserting ++the note into the tree requires demotion from level 1. ++ ++@node Refiling notes, , Storing notes, Remember ++@subsection Refiling notes ++@cindex refiling notes ++ ++Remember is usually used to quickly capture notes and tasks into one or ++a few capture lists. When reviewing the captured data, you may want to ++refile some of the entries into a different list, for example into a ++project. Cutting, finding the right location and then pasting the note ++is cumbersome. To simplify this process, you can use the following ++special command: ++ ++@table @kbd ++@kindex C-c C-w ++@item C-c C-w ++Refile the entry or region at point. This command offers possible locations ++for refiling the entry and lets you select one with completion. The item (or ++all items in the region) is filed below the target heading as a subitem. ++Depending on @code{org-reverse-note-order}, it will be either the first or ++last subitem.@* ++By default, all level 1 headlines in the current buffer are considered to be ++targets, but you can have more complex definitions across a number of files. ++See the variable @code{org-refile-targets} for details. If you would like to ++select a location via a file-path-like completion along the outline path, see ++the variables @code{org-refile-use-outline-path} and ++@code{org-outline-path-complete-in-steps}. ++@kindex C-u C-c C-w ++@item C-u C-c C-w ++Use the refile interface to jump to a heading. ++@kindex C-u C-u C-c C-w ++@item C-u C-u C-c C-w ++Jump to the location where @code{org-refile} last moved a tree to. ++@end table ++ ++@node Attachments, , Remember, Capture ++@section Attachments ++@cindex attachments ++ ++It is often useful to associate reference material with an outline node/task. ++Small chunks of plain text can simply be stored in the subtree of a project. ++Hyperlinks (@pxref{Hyperlinks}) can be used to establish associations with ++files that live elsewhere on your computer or in the cloud, like emails or ++source code files belonging to a project. Another method is @i{attachments}, ++which are files located in a directory belonging to an outline node. Org ++uses directories named by the unique ID of each entry. These directories are ++located in the @file{data} directory which lives in the same directory where ++your org-file lives@footnote{If you move entries or Org-files from one ++directory to the next, you may want to configure @code{org-attach-directory} ++to contain an absolute path.}. If you initialize this directory with ++@code{git-init}, Org will automatically commit changes when it sees them. ++The attachment system has been contributed to Org by John Wiegley. ++ ++In cases where this seems better, you can also attach a directory of your ++choice to an entry. You can also make children inherit the attachment ++directory from a parent, so that an entire subtree uses the same attached ++directory. ++ ++@noindent The following commands deal with attachments. ++ ++@table @kbd ++ ++@kindex C-c C-a ++@item C-c C-a ++The dispatcher for commands related to the attachment system. After these ++keys, a list of commands is displayed and you need to press an additional key ++to select a command: ++ ++@table @kbd ++@kindex C-c C-a a ++@item a ++Select a file and move it into the task's attachment directory. The file ++will be copied, moved, or linked, depending on @code{org-attach-method}. ++Note that hard links are not supported on all systems. ++ ++@kindex C-c C-a c ++@kindex C-c C-a m ++@kindex C-c C-a l ++@item c/m/l ++Attach a file using the copy/move/link method. ++Note that hard links are not supported on all systems. ++ ++@kindex C-c C-a n ++@item n ++Create a new attachment as an Emacs buffer. ++ ++@kindex C-c C-a z ++@item z ++Synchronize the current task with its attachment directory, in case you added ++attachments yourself. ++ ++@kindex C-c C-a o ++@item o ++Open current task's attachment. If there are more than one, prompt for a ++file name first. Opening will follow the rules set by @code{org-file-apps}. ++For more details, see the information on following hyperlinks ++(@pxref{Handling links}). ++ ++@kindex C-c C-a O ++@item O ++Also open the attachment, but force opening the file in Emacs. ++ ++@kindex C-c C-a f ++@item f ++Open the current task's attachment directory. ++ ++@kindex C-c C-a F ++@item F ++Also open the directory, but force using @code{dired} in Emacs. ++ ++@kindex C-c C-a d ++@item d ++Select and delete a single attachment. ++ ++@kindex C-c C-a D ++@item D ++Delete all of a task's attachments. A safer way is to open the directory in ++dired and delete from there. ++ ++@kindex C-c C-a s ++@item C-c C-a s ++Set a specific directory as the entry's attachment directory. This works by ++putting the directory path into the @code{ATTACH_DIR} property. ++ ++@kindex C-c C-a i ++@item C-c C-a i ++Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the ++same directory for attachments as the parent. ++@end table ++@end table ++ ++@node Agenda Views, Embedded LaTeX, Capture, Top ++@chapter Agenda Views ++@cindex agenda views ++ ++Due to the way Org works, TODO items, time-stamped items, and ++tagged headlines can be scattered throughout a file or even a number of ++files. To get an overview of open action items, or of events that are ++important for a particular date, this information must be collected, ++sorted and displayed in an organized way. ++ ++Org can select items based on various criteria, and display them ++in a separate buffer. Seven different view types are provided: ++ ++@itemize @bullet ++@item ++an @emph{agenda} that is like a calendar and shows information ++for specific dates, ++@item ++a @emph{TODO list} that covers all unfinished ++action items, ++@item ++a @emph{match view}, showings headlines based on the tags, properties and ++TODO state associated with them, ++@item ++a @emph{timeline view} that shows all events in a single Org file, ++in time-sorted view, ++@item ++a @emph{keyword search view} that shows all entries from multiple files ++that contain specified keywords. ++@item ++a @emph{stuck projects view} showing projects that currently don't move ++along, and ++@item ++@emph{custom views} that are special tag/keyword searches and ++combinations of different views. ++@end itemize ++ ++@noindent ++The extracted information is displayed in a special @emph{agenda ++buffer}. This buffer is read-only, but provides commands to visit the ++corresponding locations in the original Org files, and even to ++edit these files remotely. ++ ++Two variables control how the agenda buffer is displayed and whether the ++window configuration is restored when the agenda exits: ++@code{org-agenda-window-setup} and ++@code{org-agenda-restore-windows-after-quit}. ++ ++@menu ++* Agenda files:: Files being searched for agenda information ++* Agenda dispatcher:: Keyboard access to agenda views ++* Built-in agenda views:: What is available out of the box? ++* Presentation and sorting:: How agenda items are prepared for display ++* Agenda commands:: Remote editing of Org trees ++* Custom agenda views:: Defining special searches and views ++* Agenda column view:: Using column view for collected entries ++@end menu ++ ++@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views ++@section Agenda files ++@cindex agenda files ++@cindex files for agenda ++ ++The information to be shown is normally collected from all @emph{agenda ++files}, the files listed in the variable ++@code{org-agenda-files}@footnote{If the value of that variable is not a ++list, but a single file name, then the list of agenda files will be ++maintained in that external file.}. If a directory is part of this list, ++all files with the extension @file{.org} in this directory will be part ++of the list. ++ ++Thus even if you only work with a single Org file, this file should ++be put into that list@footnote{When using the dispatcher, pressing ++@kbd{<} before selecting a command will actually limit the command to ++the current file, and ignore @code{org-agenda-files} until the next ++dispatcher command.}. You can customize @code{org-agenda-files}, but ++the easiest way to maintain it is through the following commands ++ ++@cindex files, adding to agenda list ++@table @kbd ++@kindex C-c [ ++@item C-c [ ++Add current file to the list of agenda files. The file is added to ++the front of the list. If it was already in the list, it is moved to ++the front. With a prefix argument, file is added/moved to the end. ++@kindex C-c ] ++@item C-c ] ++Remove current file from the list of agenda files. ++@kindex C-, ++@kindex C-' ++@item C-, ++@itemx C-' ++Cycle through agenda file list, visiting one file after the other. ++@kindex M-x org-iswitchb ++@item M-x org-iswitchb ++Command to use an @code{iswitchb}-like interface to switch to and between Org ++buffers. ++@end table ++ ++@noindent ++The Org menu contains the current list of files and can be used ++to visit any of them. ++ ++If you would like to focus the agenda temporarily onto a file not in ++this list, or onto just one file in the list or even only a subtree in a ++file, this can be done in different ways. For a single agenda command, ++you may press @kbd{<} once or several times in the dispatcher ++(@pxref{Agenda dispatcher}). To restrict the agenda scope for an ++extended period, use the following commands: ++ ++@table @kbd ++@kindex C-c C-x < ++@item C-c C-x < ++Permanently restrict the agenda to the current subtree. When with a ++prefix argument, or with the cursor before the first headline in a file, ++the agenda scope is set to the entire file. This restriction remains in ++effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<} ++or @kbd{>} in the agenda dispatcher. If there is a window displaying an ++agenda view, the new restriction takes effect immediately. ++@kindex C-c C-x > ++@item C-c C-x > ++Remove the permanent restriction created by @kbd{C-c C-x <}. ++@end table ++ ++@noindent ++When working with @file{Speedbar}, you can use the following commands in ++the Speedbar frame: ++@table @kbd ++@kindex < ++@item < @r{in the speedbar frame} ++Permanently restrict the agenda to the item at the cursor in the ++Speedbar frame, either an Org file or a subtree in such a file. ++If there is a window displaying an agenda view, the new restriction takes ++effect immediately. ++@kindex > ++@item > @r{in the speedbar frame} ++Lift the restriction again. ++@end table ++ ++@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views ++@section The agenda dispatcher ++@cindex agenda dispatcher ++@cindex dispatching agenda commands ++The views are created through a dispatcher that should be bound to a ++global key, for example @kbd{C-c a} (@pxref{Installation}). In the ++following we will assume that @kbd{C-c a} is indeed how the dispatcher ++is accessed and list keyboard access to commands accordingly. After ++pressing @kbd{C-c a}, an additional letter is required to execute a ++command. The dispatcher offers the following default commands: ++@table @kbd ++@item a ++Create the calendar-like agenda (@pxref{Weekly/daily agenda}). ++@item t @r{/} T ++Create a list of all TODO items (@pxref{Global TODO list}). ++@item m @r{/} M ++Create a list of headlines matching a TAGS expression (@pxref{Matching ++tags and properties}). ++@item L ++Create the timeline view for the current buffer (@pxref{Timeline}). ++@item s ++Create a list of entries selected by a boolean expression of keywords ++and/or regular expressions that must or must not occur in the entry. ++@item / ++Search for a regular expression in all agenda files and additionally in ++the files listed in @code{org-agenda-multi-occur-extra-files}. This ++uses the Emacs command @code{multi-occur}. A prefix argument can be ++used to specify the number of context lines for each match, default is ++1. ++@item # @r{/} ! ++Create a list of stuck projects (@pxref{Stuck projects}). ++@item < ++Restrict an agenda command to the current buffer@footnote{For backward ++compatibility, you can also press @kbd{1} to restrict to the current ++buffer.}. After pressing @kbd{<}, you still need to press the character ++selecting the command. ++@item < < ++If there is an active region, restrict the following agenda command to ++the region. Otherwise, restrict it to the current subtree@footnote{For ++backward compatibility, you can also press @kbd{0} to restrict to the ++current buffer.}. After pressing @kbd{< <}, you still need to press the ++character selecting the command. ++@end table ++ ++You can also define custom commands that will be accessible through the ++dispatcher, just like the default commands. This includes the ++possibility to create extended agenda buffers that contain several ++blocks together, for example the weekly agenda, the global TODO list and ++a number of special tags matches. @xref{Custom agenda views}. ++ ++@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda Views ++@section The built-in agenda views ++ ++In this section we describe the built-in views. ++ ++@menu ++* Weekly/daily agenda:: The calendar page with current tasks ++* Global TODO list:: All unfinished action items ++* Matching tags and properties:: Structured information with fine-tuned search ++* Timeline:: Time-sorted view for single file ++* Keyword search:: Finding entries by keyword ++* Stuck projects:: Find projects you need to review ++@end menu ++ ++@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views ++@subsection The weekly/daily agenda ++@cindex agenda ++@cindex weekly agenda ++@cindex daily agenda ++ ++The purpose of the weekly/daily @emph{agenda} is to act like a page of a ++paper agenda, showing all the tasks for the current week or day. ++ ++@table @kbd ++@cindex org-agenda, command ++@kindex C-c a a ++@item C-c a a ++Compile an agenda for the current week from a list of org files. The agenda ++shows the entries for each day. With a numeric prefix@footnote{For backward ++compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be ++listed before the agenda. This feature is deprecated, use the dedicated TODO ++list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1 ++C-c a a}) you may set the number of days to be displayed (see also the ++variable @code{org-agenda-ndays}) ++@end table ++ ++Remote editing from the agenda buffer means, for example, that you can ++change the dates of deadlines and appointments from the agenda buffer. ++The commands available in the Agenda buffer are listed in @ref{Agenda ++commands}. ++ ++@subsubheading Calendar/Diary integration ++@cindex calendar integration ++@cindex diary integration ++ ++Emacs contains the calendar and diary by Edward M. Reingold. The ++calendar displays a three-month calendar with holidays from different ++countries and cultures. The diary allows you to keep track of ++anniversaries, lunar phases, sunrise/set, recurrent appointments ++(weekly, monthly) and more. In this way, it is quite complementary to ++Org. It can be very useful to combine output from Org with ++the diary. ++ ++In order to include entries from the Emacs diary into Org mode's ++agenda, you only need to customize the variable ++ ++@lisp ++(setq org-agenda-include-diary t) ++@end lisp ++ ++@noindent After that, everything will happen automatically. All diary ++entries including holidays, anniversaries etc will be included in the ++agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and ++@key{RET} can be used from the agenda buffer to jump to the diary ++file in order to edit existing diary entries. The @kbd{i} command to ++insert new entries for the current date works in the agenda buffer, as ++well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display ++Sunrise/Sunset times, show lunar phases and to convert to other ++calendars, respectively. @kbd{c} can be used to switch back and forth ++between calendar and agenda. ++ ++If you are using the diary only for sexp entries and holidays, it is ++faster to not use the above setting, but instead to copy or even move ++the entries into an Org file. Org mode evaluates diary-style sexp ++entries, and does it faster because there is no overhead for first ++creating the diary display. Note that the sexp entries must start at ++the left margin, no white space is allowed before them. For example, ++the following segment of an Org file will be processed and entries ++will be made in the agenda: ++ ++@example ++* Birthdays and similar stuff ++#+CATEGORY: Holiday ++%%(org-calendar-holiday) ; special function for holiday names ++#+CATEGORY: Ann ++%%(diary-anniversary 14 5 1956) Arthur Dent is %d years old ++%%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old ++@end example ++ ++@subsubheading Appointment reminders ++@cindex @file{appt.el} ++@cindex appointment reminders ++ ++Org can interact with Emacs appointments notification facility. ++ ++To add all the appointments of your agenda files, use the command ++@code{org-agenda-to-appt}. This commands also lets you filter through ++the list of your appointments and add only those belonging to a specific ++category or matching a regular expression. See the docstring for ++details. ++ ++@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views ++@subsection The global TODO list ++@cindex global TODO list ++@cindex TODO list, global ++ ++The global TODO list contains all unfinished TODO items, formatted and ++collected into a single place. ++ ++@table @kbd ++@kindex C-c a t ++@item C-c a t ++Show the global TODO list. This collects the TODO items from all ++agenda files (@pxref{Agenda Views}) into a single buffer. The buffer is in ++@code{agenda-mode}, so there are commands to examine and manipulate ++the TODO entries directly from that buffer (@pxref{Agenda commands}). ++@kindex C-c a T ++@item C-c a T ++@cindex TODO keyword matching ++Like the above, but allows selection of a specific TODO keyword. You ++can also do this by specifying a prefix argument to @kbd{C-c a t}. With ++a @kbd{C-u} prefix you are prompted for a keyword, and you may also ++specify several keywords by separating them with @samp{|} as boolean OR ++operator. With a numeric prefix, the Nth keyword in ++@code{org-todo-keywords} is selected. ++@kindex r ++The @kbd{r} key in the agenda buffer regenerates it, and you can give ++a prefix argument to this command to change the selected TODO keyword, ++for example @kbd{3 r}. If you often need a search for a specific ++keyword, define a custom command for it (@pxref{Agenda dispatcher}).@* ++Matching specific TODO keywords can also be done as part of a tags ++search (@pxref{Tag searches}). ++@end table ++ ++Remote editing of TODO items means that you can change the state of a ++TODO entry with a single key press. The commands available in the ++TODO list are described in @ref{Agenda commands}. ++ ++@cindex sublevels, inclusion into TODO list ++Normally the global TODO list simply shows all headlines with TODO ++keywords. This list can become very long. There are two ways to keep ++it more compact: ++@itemize @minus ++@item ++Some people view a TODO item that has been @emph{scheduled} for ++execution (@pxref{Timestamps}) as no longer @emph{open}. Configure the ++variable @code{org-agenda-todo-ignore-scheduled} to exclude scheduled ++items from the global TODO list. ++@item ++TODO items may have sublevels to break up the task into subtasks. In ++such cases it may be enough to list only the highest level TODO headline ++and omit the sublevels from the global list. Configure the variable ++@code{org-agenda-todo-list-sublevels} to get this behavior. ++@end itemize ++ ++@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views ++@subsection Matching tags and properties ++@cindex matching, of tags ++@cindex matching, of properties ++@cindex tags view ++@cindex match view ++ ++If headlines in the agenda files are marked with @emph{tags} ++(@pxref{Tags}), you can select headlines based on the tags that apply ++to them and collect them into an agenda buffer. ++ ++@table @kbd ++@kindex C-c a m ++@item C-c a m ++Produce a list of all headlines that match a given set of tags. The ++command prompts for a selection criterion, which is a boolean logic ++expression with tags, like @samp{+work+urgent-withboss} or ++@samp{work|home} (@pxref{Tags}). If you often need a specific search, ++define a custom command for it (@pxref{Agenda dispatcher}). ++@kindex C-c a M ++@item C-c a M ++Like @kbd{C-c a m}, but only select headlines that are also TODO items ++and force checking subitems (see variable ++@code{org-tags-match-list-sublevels}). Matching specific TODO keywords ++together with a tags match is also possible, see @ref{Tag searches}. ++@end table ++ ++The commands available in the tags list are described in @ref{Agenda ++commands}. ++ ++@node Timeline, Keyword search, Matching tags and properties, Built-in agenda views ++@subsection Timeline for a single file ++@cindex timeline, single file ++@cindex time-sorted view ++ ++The timeline summarizes all time-stamped items from a single Org mode ++file in a @emph{time-sorted view}. The main purpose of this command is ++to give an overview over events in a project. ++ ++@table @kbd ++@kindex C-c a L ++@item C-c a L ++Show a time-sorted view of the org file, with all time-stamped items. ++When called with a @kbd{C-u} prefix, all unfinished TODO entries ++(scheduled or not) are also listed under the current date. ++@end table ++ ++@noindent ++The commands available in the timeline buffer are listed in ++@ref{Agenda commands}. ++ ++@node Keyword search, Stuck projects, Timeline, Built-in agenda views ++@subsection Keyword search ++@cindex keyword search ++@cindex searching, for keywords ++ ++This agenda view is a general text search facility for Org mode entries. ++It is particularly useful to find notes. ++ ++@table @kbd ++@kindex C-c a s ++@item C-c a s ++This is a special search that lets you select entries by keywords or ++regular expression, using a boolean logic. For example, the search ++string ++ ++@example +++computer +wifi -ethernet -@{8\.11[bg]@} ++@end example ++ ++@noindent ++will search for note entries that contain the keywords @code{computer} ++and @code{wifi}, but not the keyword @code{ethernet}, and which are also ++not matched by the regular expression @code{8\.11[bg]}, meaning to ++exclude both 8.11b and 8.11g. ++ ++Note that in addition to the agenda files, this command will also search ++the files listed in @code{org-agenda-text-search-extra-files}. ++@end table ++ ++@node Stuck projects, , Keyword search, Built-in agenda views ++@subsection Stuck projects ++ ++If you are following a system like David Allen's GTD to organize your ++work, one of the ``duties'' you have is a regular review to make sure ++that all projects move along. A @emph{stuck} project is a project that ++has no defined next actions, so it will never show up in the TODO lists ++Org mode produces. During the review, you need to identify such ++projects and define next actions for them. ++ ++@table @kbd ++@kindex C-c a # ++@item C-c a # ++List projects that are stuck. ++@kindex C-c a ! ++@item C-c a ! ++Customize the variable @code{org-stuck-projects} to define what a stuck ++project is and how to find it. ++@end table ++ ++You almost certainly will have to configure this view before it will ++work for you. The built-in default assumes that all your projects are ++level-2 headlines, and that a project is not stuck if it has at least ++one entry marked with a TODO keyword TODO or NEXT or NEXTACTION. ++ ++Let's assume that you, in your own way of using Org mode, identify ++projects with a tag PROJECT, and that you use a TODO keyword MAYBE to ++indicate a project that should not be considered yet. Let's further ++assume that the TODO keyword DONE marks finished projects, and that NEXT ++and TODO indicate next actions. The tag @@SHOP indicates shopping and ++is a next action even without the NEXT tag. Finally, if the project ++contains the special word IGNORE anywhere, it should not be listed ++either. In this case you would start by identifying eligible projects ++with a tags/todo match @samp{+PROJECT/-MAYBE-DONE}, and then check for ++TODO, NEXT, @@SHOP, and IGNORE in the subtree to identify projects that ++are not stuck. The correct customization for this is ++ ++@lisp ++(setq org-stuck-projects ++ '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP") ++ "\\")) ++@end lisp ++ ++ ++@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda Views ++@section Presentation and sorting ++@cindex presentation, of agenda items ++ ++Before displaying items in an agenda view, Org mode visually prepares ++the items and sorts them. Each item occupies a single line. The line ++starts with a @emph{prefix} that contains the @emph{category} ++(@pxref{Categories}) of the item and other important information. You can ++customize the prefix using the option @code{org-agenda-prefix-format}. ++The prefix is followed by a cleaned-up version of the outline headline ++associated with the item. ++ ++@menu ++* Categories:: Not all tasks are equal ++* Time-of-day specifications:: How the agenda knows the time ++* Sorting of agenda items:: The order of things ++@end menu ++ ++@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting ++@subsection Categories ++ ++@cindex category ++The category is a broad label assigned to each agenda item. By default, ++the category is simply derived from the file name, but you can also ++specify it with a special line in the buffer, like this@footnote{For ++backward compatibility, the following also works: If there are several ++such lines in a file, each specifies the category for the text below it. ++The first category also applies to any text before the first CATEGORY ++line. However, using this method is @emph{strongly} deprecated as it is ++incompatible with the outline structure of the document. The correct ++method for setting multiple categories in a buffer is using a ++property.}: ++ ++@example ++#+CATEGORY: Thesis ++@end example ++ ++@noindent ++If you would like to have a special CATEGORY for a single entry or a ++(sub)tree, give the entry a @code{:CATEGORY:} property with the ++special category you want to apply as the value. ++ ++@noindent ++The display in the agenda buffer looks best if the category is not ++longer than 10 characters. ++ ++@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting ++@subsection Time-of-day specifications ++@cindex time-of-day specification ++ ++Org mode checks each agenda item for a time-of-day specification. The ++time can be part of the time stamp that triggered inclusion into the ++agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time ++ranges can be specified with two time stamps, like ++@c ++@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}. ++ ++In the headline of the entry itself, a time(range) may also appear as ++plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda ++integrates the Emacs diary (@pxref{Weekly/daily agenda}), time ++specifications in diary entries are recognized as well. ++ ++For agenda display, Org mode extracts the time and displays it in a ++standard 24 hour format as part of the prefix. The example times in ++the previous paragraphs would end up in the agenda like this: ++ ++@example ++ 8:30-13:00 Arthur Dent lies in front of the bulldozer ++ 12:45...... Ford Prefect arrives and takes Arthur to the pub ++ 19:00...... The Vogon reads his poem ++ 20:30-22:15 Marvin escorts the Hitchhikers to the bridge ++@end example ++ ++@cindex time grid ++If the agenda is in single-day mode, or for the display of today, the ++timed entries are embedded in a time grid, like ++ ++@example ++ 8:00...... ------------------ ++ 8:30-13:00 Arthur Dent lies in front of the bulldozer ++ 10:00...... ------------------ ++ 12:00...... ------------------ ++ 12:45...... Ford Prefect arrives and takes Arthur to the pub ++ 14:00...... ------------------ ++ 16:00...... ------------------ ++ 18:00...... ------------------ ++ 19:00...... The Vogon reads his poem ++ 20:00...... ------------------ ++ 20:30-22:15 Marvin escorts the Hitchhikers to the bridge ++@end example ++ ++The time grid can be turned on and off with the variable ++@code{org-agenda-use-time-grid}, and can be configured with ++@code{org-agenda-time-grid}. ++ ++@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting ++@subsection Sorting of agenda items ++@cindex sorting, of agenda items ++@cindex priorities, of agenda items ++Before being inserted into a view, the items are sorted. How this is ++done depends on the type of view. ++@itemize @bullet ++@item ++For the daily/weekly agenda, the items for each day are sorted. The ++default order is to first collect all items containing an explicit ++time-of-day specification. These entries will be shown at the beginning ++of the list, as a @emph{schedule} for the day. After that, items remain ++grouped in categories, in the sequence given by @code{org-agenda-files}. ++Within each category, items are sorted by priority (@pxref{Priorities}), ++which is composed of the base priority (2000 for priority @samp{A}, 1000 ++for @samp{B}, and 0 for @samp{C}), plus additional increments for ++overdue scheduled or deadline items. ++@item ++For the TODO list, items remain in the order of categories, but within ++each category, sorting takes place according to priority ++(@pxref{Priorities}). ++@item ++For tags matches, items are not sorted at all, but just appear in the ++sequence in which they are found in the agenda files. ++@end itemize ++ ++Sorting can be customized using the variable ++@code{org-agenda-sorting-strategy}, and may also include criteria based on ++the estimated effort of an entry (@pxref{Effort estimates}). ++ ++@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views ++@section Commands in the agenda buffer ++@cindex commands, in agenda buffer ++ ++Entries in the agenda buffer are linked back to the org file or diary ++file where they originate. You are not allowed to edit the agenda ++buffer itself, but commands are provided to show and jump to the ++original entry location, and to edit the org-files ``remotely'' from ++the agenda buffer. In this way, all information is stored only once, ++removing the risk that your agenda and note files may diverge. ++ ++Some commands can be executed with mouse clicks on agenda lines. For ++the other commands, the cursor needs to be in the desired line. ++ ++@table @kbd ++@tsubheading{Motion} ++@cindex motion commands in agenda ++@kindex n ++@item n ++Next line (same as @key{up} and @kbd{C-p}). ++@kindex p ++@item p ++Previous line (same as @key{down} and @kbd{C-n}). ++@tsubheading{View/Go to org file} ++@kindex mouse-3 ++@kindex @key{SPC} ++@item mouse-3 ++@itemx @key{SPC} ++Display the original location of the item in another window. ++With prefix arg, make sure that the entire entry is made visible in the ++outline, not only the heading. ++@c ++@kindex L ++@item L ++Display original location and recenter that window. ++@c ++@kindex mouse-2 ++@kindex mouse-1 ++@kindex @key{TAB} ++@item mouse-2 ++@itemx mouse-1 ++@itemx @key{TAB} ++Go to the original location of the item in another window. Under Emacs ++22, @kbd{mouse-1} will also works for this. ++@c ++@kindex @key{RET} ++@itemx @key{RET} ++Go to the original location of the item and delete other windows. ++@c ++@kindex f ++@item f ++Toggle Follow mode. In Follow mode, as you move the cursor through ++the agenda buffer, the other window always shows the corresponding ++location in the org file. The initial setting for this mode in new ++agenda buffers can be set with the variable ++@code{org-agenda-start-with-follow-mode}. ++@c ++@kindex b ++@item b ++Display the entire subtree of the current item in an indirect buffer. With a ++numeric prefix argument N, go up to level N and then take that tree. If N is ++negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the ++previously used indirect buffer. ++@c ++@kindex l ++@item l ++Toggle Logbook mode. In Logbook mode, entries that were marked DONE while ++logging was on (variable @code{org-log-done}) are shown in the agenda, as are ++entries that have been clocked on that day. You can configure the entry ++types that should be included in log mode using the variable ++@code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show ++all possible logbook entries, including state changes. When called with two ++prefix args @kbd{C-u C-u}, show only logging information, nothing else. ++@c ++@kindex v ++@item v ++Toggle Archives mode. In archives mode, trees that are marked ++@code{ARCHIVED} are also scanned when producing the agenda. When you call ++this command with a @kbd{C-u} prefix argument, even all archive files are ++included. To exit archives mode, press @kbd{v} again. ++@c ++@kindex R ++@item R ++Toggle Clockreport mode. In clockreport mode, the daily/weekly agenda will ++always show a table with the clocked times for the timespan and file scope ++covered by the current agenda view. The initial setting for this mode in new ++agenda buffers can be set with the variable ++@code{org-agenda-start-with-clockreport-mode}. ++ ++@tsubheading{Change display} ++@cindex display changing, in agenda ++@kindex o ++@item o ++Delete other windows. ++@c ++@kindex d ++@kindex w ++@kindex m ++@kindex y ++@item d w m y ++Switch to day/week/month/year view. When switching to day or week view, ++this setting becomes the default for subsequent agenda commands. Since ++month and year views are slow to create, they do not become the default. ++A numeric prefix argument may be used to jump directly to a specific day ++of the year, ISO week, month, or year, respectively. For example, ++@kbd{32 d} jumps to February 1st, @kbd{9 w} to ISO week number 9. When ++setting day, week, or month view, a year may be encoded in the prefix ++argument as well. For example, @kbd{200712 w} will jump to week 12 in ++2007. If such a year specification has only one or two digits, it will ++be mapped to the interval 1938-2037. ++@c ++@kindex D ++@item D ++Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}. ++@c ++@kindex G ++@item G ++Toggle the time grid on and off. See also the variables ++@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}. ++@c ++@kindex r ++@item r ++Recreate the agenda buffer, for example to reflect the changes after ++modification of the time stamps of items with @kbd{S-@key{left}} and ++@kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix ++argument is interpreted to create a selective list for a specific TODO ++keyword. ++@kindex g ++@item g ++Same as @kbd{r}. ++@c ++@kindex s ++@kindex C-x C-s ++@item s ++@itemx C-x C-s ++Save all Org buffers in the current Emacs session. ++@c ++@kindex @key{right} ++@item @key{right} ++Display the following @code{org-agenda-ndays} days. For example, if ++the display covers a week, switch to the following week. With prefix ++arg, go forward that many times @code{org-agenda-ndays} days. ++@c ++@kindex @key{left} ++@item @key{left} ++Display the previous dates. ++@c ++@kindex . ++@item . ++Go to today. ++@c ++@kindex C-c C-x C-c ++@item C-c C-x C-c ++Invoke column view (@pxref{Column view}) in the agenda buffer. The column ++view format is taken from the entry at point, or (if there is no entry at ++point), from the first entry in the agenda view. So whatever the format for ++that entry would be in the original buffer (taken from a property, from a ++@code{#+COLUMNS} line, or from the default variable ++@code{org-columns-default-format}), will be used in the agenda. ++ ++@tsubheading{Secondary filtering and query editing} ++@cindex filtering, by tag and effort, in agenda ++@cindex tag filtering, in agenda ++@cindex effort filtering, in agenda ++@cindex query editing, in agenda ++ ++@kindex / ++@item / ++Filter the current agenda view with respect to a tag and/or effort estimates. ++The difference between this and a custom agenda commands is that filtering is ++very fast, so that you can switch quickly between different filters without ++having to recreate the agenda. ++ ++You will be prompted for a tag selection letter. Pressing @key{TAB} at that ++prompt will offer use completion to select a tag (including any tags that do ++not have a selection character). The command then hides all entries that do ++not contain or inherit this tag. When called with prefix arg, remove the ++entries that @emph{do} have the tag. A second @kbd{/} at the prompt will ++turn off the filter and unhide any hidden entries. If the first key you ++press is either @kbd{+} or @kbd{-}, the previous filter will be narrowed by ++requiring or forbidding the selected additional tag. Instead of pressing ++@kbd{+} or @kbd{-} after @kbd{/}, you can also immediately use the @kbd{\} ++command. ++ ++In order to filter for effort estimates, you should set-up allowed ++efforts globally, for example ++@lisp ++(setq org-global-properties ++ '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) ++@end lisp ++You can then filter for an effort by first typing an operator, one of @kbd{<}, ++@kbd{>}, and @kbd{=}, and then the one-digit index of an effort estimate in ++your array of allowed values, where @kbd{0} means the 10th value. The filter ++will then restrict to entries with effort smaller-or-equal, equal, or ++larger-or-equal than the selected value. If the digits 0-9 are not used as ++fast access keys to tags, you can also simply press the index digit directly ++without an operator. In this case, @kbd{<} will be assumed. ++ ++@kindex \ ++@item \ ++Narrow the current agenda filter by an additional condition. When called with ++prefix arg, remove the entries that @emph{do} have the tag, or that do match ++the effort criterion. You can achieve the same effect by pressing @kbd{+} or ++@kbd{-} as the first key after the @kbd{/} command. ++ ++@kindex [ ++@kindex ] ++@kindex @{ ++@kindex @} ++@item [ ] @{ @} ++In the @i{search view} (@pxref{Keyword search}), these keys add new search ++words (@kbd{[} and @kbd{]}) or new regular expressions (@kbd{@{} and ++@kbd{@}}) to the query string. The opening bracket/brace will add a positive ++search term prefixed by @samp{+}, indicating that this search term @i{must} ++occur/match in the entry. The closing bracket/brace will add a negative ++search term which @i{must not} occur/match in the entry for it to be ++selected. ++ ++ ++@tsubheading{Remote editing} ++@cindex remote editing, from agenda ++ ++@item 0-9 ++Digit argument. ++@c ++@cindex undoing remote-editing events ++@cindex remote editing, undo ++@kindex C-_ ++@item C-_ ++Undo a change due to a remote editing command. The change is undone ++both in the agenda buffer and in the remote buffer. ++@c ++@kindex t ++@item t ++Change the TODO state of the item, both in the agenda and in the ++original org file. ++@c ++@kindex C-k ++@item C-k ++Delete the current agenda item along with the entire subtree belonging ++to it in the original Org file. If the text to be deleted remotely ++is longer than one line, the kill needs to be confirmed by the user. See ++variable @code{org-agenda-confirm-kill}. ++@c ++@kindex a ++@item a ++Toggle the ARCHIVE tag for the current headline. ++@c ++@kindex A ++@item A ++Move the subtree corresponding to the current entry to its @emph{Archive ++Sibling}. ++@c ++@kindex $ ++@item $ ++Archive the subtree corresponding to the current headline. This means the ++entry will be moved to the configured archive location, most likely a ++different file. ++@c ++@kindex T ++@item T ++Show all tags associated with the current item. This is useful if you have ++turned off @code{org-agenda-show-inherited-tags}, but still want to see all ++tags of a headline occasionally. ++@c ++@kindex : ++@item : ++Set tags for the current headline. If there is an active region in the ++agenda, change a tag for all headings in the region. ++@c ++@kindex , ++@item , ++Set the priority for the current item. Org mode prompts for the ++priority character. If you reply with @key{SPC}, the priority cookie ++is removed from the entry. ++@c ++@kindex P ++@item P ++Display weighted priority of current item. ++@c ++@kindex + ++@kindex S-@key{up} ++@item + ++@itemx S-@key{up} ++Increase the priority of the current item. The priority is changed in ++the original buffer, but the agenda is not resorted. Use the @kbd{r} ++key for this. ++@c ++@kindex - ++@kindex S-@key{down} ++@item - ++@itemx S-@key{down} ++Decrease the priority of the current item. ++@c ++@kindex C-c C-a ++@item C-c C-a ++Dispatcher for all command related to attachments. ++@c ++@kindex C-c C-s ++@item C-c C-s ++Schedule this item ++@c ++@kindex C-c C-d ++@item C-c C-d ++Set a deadline for this item. ++@c ++@kindex k ++@item k ++Agenda actions, to set dates for selected items to the cursor date. ++This command also works in the calendar! The command prompts for an ++additional key: ++@example ++m @r{Mark the entry at point for action. You can also make entries} ++ @r{in Org files with @kbd{C-c C-x C-k}.} ++d @r{Set the deadline of the marked entry to the date at point.} ++s @r{Schedule the marked entry at the date at point.} ++r @r{Call @code{org-remember} with the cursor date as default date.} ++@end example ++Press @kbd{r} afterward to refresh the agenda and see the effect of the ++command. ++@c ++@kindex S-@key{right} ++@item S-@key{right} ++Change the time stamp associated with the current line by one day into the ++future. With a numeric prefix argument, change it by that many days. For ++example, @kbd{3 6 5 S-@key{right}} will change it by a year. The stamp is ++changed in the original org file, but the change is not directly reflected in ++the agenda buffer. Use the @kbd{r} key to update the buffer. ++@c ++@kindex S-@key{left} ++@item S-@key{left} ++Change the time stamp associated with the current line by one day ++into the past. ++@c ++@kindex > ++@item > ++Change the time stamp associated with the current line to today. ++The key @kbd{>} has been chosen, because it is the same as @kbd{S-.} ++on my keyboard. ++@c ++@kindex I ++@item I ++Start the clock on the current item. If a clock is running already, it ++is stopped first. ++@c ++@kindex O ++@item O ++Stop the previously started clock. ++@c ++@kindex X ++@item X ++Cancel the currently running clock. ++ ++@kindex J ++@item J ++Jump to the running clock in another window. ++ ++@tsubheading{Calendar commands} ++@cindex calendar commands, from agenda ++@kindex c ++@item c ++Open the Emacs calendar and move to the date at the agenda cursor. ++@c ++@item c ++When in the calendar, compute and show the Org mode agenda for the ++date at the cursor. ++@c ++@cindex diary entries, creating from agenda ++@kindex i ++@item i ++Insert a new entry into the diary. Prompts for the type of entry ++(day, weekly, monthly, yearly, anniversary, cyclic) and creates a new ++entry in the diary, just as @kbd{i d} etc. would do in the calendar. ++The date is taken from the cursor position. ++@c ++@kindex M ++@item M ++Show the phases of the moon for the three months around current date. ++@c ++@kindex S ++@item S ++Show sunrise and sunset times. The geographical location must be set ++with calendar variables, see documentation of the Emacs calendar. ++@c ++@kindex C ++@item C ++Convert the date at cursor into many other cultural and historic ++calendars. ++@c ++@kindex H ++@item H ++Show holidays for three month around the cursor date. ++ ++@item M-x org-export-icalendar-combine-agenda-files ++Export a single iCalendar file containing entries from all agenda files. ++This is a globally available command, and also available in the agenda menu. ++ ++@tsubheading{Exporting to a file} ++@kindex C-x C-w ++@item C-x C-w ++@cindex exporting agenda views ++@cindex agenda views, exporting ++Write the agenda view to a file. Depending on the extension of the ++selected file name, the view will be exported as HTML (extension ++@file{.html} or @file{.htm}), Postscript (extension @file{.ps}), or ++plain text (any other extension). Use the variable ++@code{org-agenda-exporter-settings} to set options for @file{ps-print} ++and for @file{htmlize} to be used during export. ++ ++@tsubheading{Quit and Exit} ++@kindex q ++@item q ++Quit agenda, remove the agenda buffer. ++@c ++@kindex x ++@cindex agenda files, removing buffers ++@item x ++Exit agenda, remove the agenda buffer and all buffers loaded by Emacs ++for the compilation of the agenda. Buffers created by the user to ++visit org files will not be removed. ++@end table ++ ++ ++@node Custom agenda views, Agenda column view, Agenda commands, Agenda Views ++@section Custom agenda views ++@cindex custom agenda views ++@cindex agenda views, custom ++ ++Custom agenda commands serve two purposes: to store and quickly access ++frequently used TODO and tags searches, and to create special composite ++agenda buffers. Custom agenda commands will be accessible through the ++dispatcher (@pxref{Agenda dispatcher}), just like the default commands. ++ ++@menu ++* Storing searches:: Type once, use often ++* Block agenda:: All the stuff you need in a single buffer ++* Setting Options:: Changing the rules ++* Exporting Agenda Views:: Writing agendas to files ++* Using the agenda elsewhere:: Using agenda information in other programs ++@end menu ++ ++@node Storing searches, Block agenda, Custom agenda views, Custom agenda views ++@subsection Storing searches ++ ++The first application of custom searches is the definition of keyboard ++shortcuts for frequently used searches, either creating an agenda ++buffer, or a sparse tree (the latter covering of course only the current ++buffer). ++@kindex C-c a C ++Custom commands are configured in the variable ++@code{org-agenda-custom-commands}. You can customize this variable, for ++example by pressing @kbd{C-c a C}. You can also directly set it with ++Emacs Lisp in @file{.emacs}. The following example contains all valid ++search types: ++ ++@lisp ++@group ++(setq org-agenda-custom-commands ++ '(("w" todo "WAITING") ++ ("W" todo-tree "WAITING") ++ ("u" tags "+boss-urgent") ++ ("v" tags-todo "+boss-urgent") ++ ("U" tags-tree "+boss-urgent") ++ ("f" occur-tree "\\") ++ ("h" . "HOME+Name tags searches") ; description for "h" prefix ++ ("hl" tags "+home+Lisa") ++ ("hp" tags "+home+Peter") ++ ("hk" tags "+home+Kim"))) ++@end group ++@end lisp ++ ++@noindent ++The initial string in each entry defines the keys you have to press ++after the dispatcher command @kbd{C-c a} in order to access the command. ++Usually this will be just a single character, but if you have many ++similar commands, you can also define two-letter combinations where the ++first character is the same in several combinations and serves as a ++prefix key@footnote{You can provide a description for a prefix key by ++inserting a cons cell with the prefix and the description.}. The second ++parameter is the search type, followed by the string or regular ++expression to be used for the matching. The example above will ++therefore define: ++ ++@table @kbd ++@item C-c a w ++as a global search for TODO entries with @samp{WAITING} as the TODO ++keyword ++@item C-c a W ++as the same search, but only in the current buffer and displaying the ++results as a sparse tree ++@item C-c a u ++as a global tags search for headlines marked @samp{:boss:} but not ++@samp{:urgent:} ++@item C-c a v ++as the same search as @kbd{C-c a u}, but limiting the search to ++headlines that are also TODO items ++@item C-c a U ++as the same search as @kbd{C-c a u}, but only in the current buffer and ++displaying the result as a sparse tree ++@item C-c a f ++to create a sparse tree (again: current buffer only) with all entries ++containing the word @samp{FIXME} ++@item C-c a h ++as a prefix command for a HOME tags search where you have to press an ++additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa, ++Peter, or Kim) as additional tag to match. ++@end table ++ ++@node Block agenda, Setting Options, Storing searches, Custom agenda views ++@subsection Block agenda ++@cindex block agenda ++@cindex agenda, with block views ++ ++Another possibility is the construction of agenda views that comprise ++the results of @emph{several} commands, each of which creates a block in ++the agenda buffer. The available commands include @code{agenda} for the ++daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo} ++for the global TODO list (as constructed with @kbd{C-c a t}), and the ++matching commands discussed above: @code{todo}, @code{tags}, and ++@code{tags-todo}. Here are two examples: ++ ++@lisp ++@group ++(setq org-agenda-custom-commands ++ '(("h" "Agenda and Home-related tasks" ++ ((agenda "") ++ (tags-todo "home") ++ (tags "garden"))) ++ ("o" "Agenda and Office-related tasks" ++ ((agenda "") ++ (tags-todo "work") ++ (tags "office"))))) ++@end group ++@end lisp ++ ++@noindent ++This will define @kbd{C-c a h} to create a multi-block view for stuff ++you need to attend to at home. The resulting agenda buffer will contain ++your agenda for the current week, all TODO items that carry the tag ++@samp{home}, and also all lines tagged with @samp{garden}. Finally the ++command @kbd{C-c a o} provides a similar view for office tasks. ++ ++@node Setting Options, Exporting Agenda Views, Block agenda, Custom agenda views ++@subsection Setting options for custom commands ++@cindex options, for custom agenda views ++ ++Org mode contains a number of variables regulating agenda construction ++and display. The global variables define the behavior for all agenda ++commands, including the custom commands. However, if you want to change ++some settings just for a single custom view, you can do so. Setting ++options requires inserting a list of variable names and values at the ++right spot in @code{org-agenda-custom-commands}. For example: ++ ++@lisp ++@group ++(setq org-agenda-custom-commands ++ '(("w" todo "WAITING" ++ ((org-agenda-sorting-strategy '(priority-down)) ++ (org-agenda-prefix-format " Mixed: "))) ++ ("U" tags-tree "+boss-urgent" ++ ((org-show-following-heading nil) ++ (org-show-hierarchy-above nil))) ++ ("N" search "" ++ ((org-agenda-files '("~org/notes.org")) ++ (org-agenda-text-search-extra-files nil))))) ++@end group ++@end lisp ++ ++@noindent ++Now the @kbd{C-c a w} command will sort the collected entries only by ++priority, and the prefix format is modified to just say @samp{ Mixed: } ++instead of giving the category of the entry. The sparse tags tree of ++@kbd{C-c a U} will now turn out ultra-compact, because neither the ++headline hierarchy above the match, nor the headline following the match ++will be shown. The command @kbd{C-c a N} will do a text search limited ++to only a single file. ++ ++For command sets creating a block agenda, ++@code{org-agenda-custom-commands} has two separate spots for setting ++options. You can add options that should be valid for just a single ++command in the set, and options that should be valid for all commands in ++the set. The former are just added to the command entry, the latter ++must come after the list of command entries. Going back to the block ++agenda example (@pxref{Block agenda}), let's change the sorting strategy ++for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort ++the results for GARDEN tags query in the opposite order, ++@code{priority-up}. This would look like this: ++ ++@lisp ++@group ++(setq org-agenda-custom-commands ++ '(("h" "Agenda and Home-related tasks" ++ ((agenda) ++ (tags-todo "home") ++ (tags "garden" ++ ((org-agenda-sorting-strategy '(priority-up))))) ++ ((org-agenda-sorting-strategy '(priority-down)))) ++ ("o" "Agenda and Office-related tasks" ++ ((agenda) ++ (tags-todo "work") ++ (tags "office"))))) ++@end group ++@end lisp ++ ++As you see, the values and parenthesis setting is a little complex. ++When in doubt, use the customize interface to set this variable - it ++fully supports its structure. Just one caveat: When setting options in ++this interface, the @emph{values} are just lisp expressions. So if the ++value is a string, you need to add the double quotes around the value ++yourself. ++ ++ ++@node Exporting Agenda Views, Using the agenda elsewhere, Setting Options, Custom agenda views ++@subsection Exporting Agenda Views ++@cindex agenda views, exporting ++ ++If you are away from your computer, it can be very useful to have a printed ++version of some agenda views to carry around. Org mode can export custom ++agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's ++@file{htmlize.el}.}, Postscript, and iCalendar files. If you want to do this ++only occasionally, use the command ++ ++@table @kbd ++@kindex C-x C-w ++@item C-x C-w ++@cindex exporting agenda views ++@cindex agenda views, exporting ++Write the agenda view to a file. Depending on the extension of the ++selected file name, the view will be exported as HTML (extension ++@file{.html} or @file{.htm}), Postscript (extension @file{.ps}), ++iCalendar (extension @file{.ics}), or plain text (any other extension). ++Use the variable @code{org-agenda-exporter-settings} to ++set options for @file{ps-print} and for @file{htmlize} to be used during ++export, for example ++ ++@lisp ++(setq org-agenda-exporter-settings ++ '((ps-number-of-columns 2) ++ (ps-landscape-mode t) ++ (htmlize-output-type 'css))) ++@end lisp ++@end table ++ ++If you need to export certain agenda views frequently, you can associate ++any custom agenda command with a list of output file names ++@footnote{If you want to store standard views like the weekly agenda ++or the global TODO list as well, you need to define custom commands for ++them in order to be able to specify file names.}. Here is an example ++that first does define custom commands for the agenda and the global ++todo list, together with a number of files to which to export them. ++Then we define two block agenda commands and specify file names for them ++as well. File names can be relative to the current working directory, ++or absolute. ++ ++@lisp ++@group ++(setq org-agenda-custom-commands ++ '(("X" agenda "" nil ("agenda.html" "agenda.ps")) ++ ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps")) ++ ("h" "Agenda and Home-related tasks" ++ ((agenda "") ++ (tags-todo "home") ++ (tags "garden")) ++ nil ++ ("~/views/home.html")) ++ ("o" "Agenda and Office-related tasks" ++ ((agenda) ++ (tags-todo "work") ++ (tags "office")) ++ nil ++ ("~/views/office.ps" "~/calendars/office.ics")))) ++@end group ++@end lisp ++ ++The extension of the file name determines the type of export. If it is ++@file{.html}, Org mode will use the @file{htmlize.el} package to convert ++the buffer to HTML and save it to this file name. If the extension is ++@file{.ps}, @code{ps-print-buffer-with-faces} is used to produce ++postscript output. If the extension is @file{.ics}, iCalendar export is ++run export over all files that were used to construct the agenda, and ++limit the export to entries listed in the agenda now. Any other ++extension produces a plain ASCII file. ++ ++The export files are @emph{not} created when you use one of those ++commands interactively because this might use too much overhead. ++Instead, there is a special command to produce @emph{all} specified ++files in one step: ++ ++@table @kbd ++@kindex C-c a e ++@item C-c a e ++Export all agenda views that have export file names associated with ++them. ++@end table ++ ++You can use the options section of the custom agenda commands to also ++set options for the export commands. For example: ++ ++@lisp ++(setq org-agenda-custom-commands ++ '(("X" agenda "" ++ ((ps-number-of-columns 2) ++ (ps-landscape-mode t) ++ (org-agenda-prefix-format " [ ] ") ++ (org-agenda-with-colors nil) ++ (org-agenda-remove-tags t)) ++ ("theagenda.ps")))) ++@end lisp ++ ++@noindent ++This command sets two options for the postscript exporter, to make it ++print in two columns in landscape format - the resulting page can be cut ++in two and then used in a paper agenda. The remaining settings modify ++the agenda prefix to omit category and scheduling information, and ++instead include a checkbox to check off items. We also remove the tags ++to make the lines compact, and we don't want to use colors for the ++black-and-white printer. Settings specified in ++@code{org-agenda-exporter-settings} will also apply, but the settings ++in @code{org-agenda-custom-commands} take precedence. ++ ++@noindent ++From the command line you may also use ++@example ++emacs -f org-batch-store-agenda-views -kill ++@end example ++@noindent ++or, if you need to modify some parameters@footnote{Quoting may depend on the ++system you use, please check th FAQ for examples.} ++@example ++emacs -eval '(org-batch-store-agenda-views \ ++ org-agenda-ndays 30 \ ++ org-agenda-start-day "2007-11-01" \ ++ org-agenda-include-diary nil \ ++ org-agenda-files (quote ("~/org/project.org")))' \ ++ -kill ++@end example ++@noindent ++which will create the agenda views restricted to the file ++@file{~/org/project.org}, without diary entries and with 30 days ++extent. ++ ++@node Using the agenda elsewhere, , Exporting Agenda Views, Custom agenda views ++@subsection Using agenda information outside of Org ++@cindex agenda, pipe ++@cindex Scripts, for agenda processing ++ ++Org provides commands to access agenda information for the command ++line in emacs batch mode. This extracted information can be sent ++directly to a printer, or it can be read by a program that does further ++processing of the data. The first of these commands is the function ++@code{org-batch-agenda}, that produces an agenda view and sends it as ++ASCII text to STDOUT. The command takes a single string as parameter. ++If the string has length 1, it is used as a key to one of the commands ++you have configured in @code{org-agenda-custom-commands}, basically any ++key you can use after @kbd{C-c a}. For example, to directly print the ++current TODO list, you could use ++ ++@example ++emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr ++@end example ++ ++If the parameter is a string with 2 or more characters, it is used as a ++tags/todo match string. For example, to print your local shopping list ++(all items with the tag @samp{shop}, but excluding the tag ++@samp{NewYork}), you could use ++ ++@example ++emacs -batch -l ~/.emacs \ ++ -eval '(org-batch-agenda "+shop-NewYork")' | lpr ++@end example ++ ++@noindent ++You may also modify parameters on the fly like this: ++ ++@example ++emacs -batch -l ~/.emacs \ ++ -eval '(org-batch-agenda "a" \ ++ org-agenda-ndays 30 \ ++ org-agenda-include-diary nil \ ++ org-agenda-files (quote ("~/org/project.org")))' \ ++ | lpr ++@end example ++ ++@noindent ++which will produce a 30 day agenda, fully restricted to the Org file ++@file{~/org/projects.org}, not even including the diary. ++ ++If you want to process the agenda data in more sophisticated ways, you ++can use the command @code{org-batch-agenda-csv} to get a comma-separated ++list of values for each agenda item. Each line in the output will ++contain a number of fields separated by commas. The fields in a line ++are: ++ ++@example ++category @r{The category of the item} ++head @r{The headline, without TODO kwd, TAGS and PRIORITY} ++type @r{The type of the agenda entry, can be} ++ todo @r{selected in TODO match} ++ tagsmatch @r{selected in tags match} ++ diary @r{imported from diary} ++ deadline @r{a deadline} ++ scheduled @r{scheduled} ++ timestamp @r{appointment, selected by timestamp} ++ closed @r{entry was closed on date} ++ upcoming-deadline @r{warning about nearing deadline} ++ past-scheduled @r{forwarded scheduled item} ++ block @r{entry has date block including date} ++todo @r{The TODO keyword, if any} ++tags @r{All tags including inherited ones, separated by colons} ++date @r{The relevant date, like 2007-2-14} ++time @r{The time, like 15:00-16:50} ++extra @r{String with extra planning info} ++priority-l @r{The priority letter if any was given} ++priority-n @r{The computed numerical priority} ++@end example ++ ++@noindent ++Time and date will only be given if a timestamp (or deadline/scheduled) ++lead to the selection of the item. ++ ++A CSV list like this is very easy to use in a post processing script. ++For example, here is a Perl program that gets the TODO list from ++Emacs/Org and prints all the items, preceded by a checkbox: ++ ++@example ++@group ++#!/usr/bin/perl ++ ++# define the Emacs command to run ++$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; ++ ++# run it and capture the output ++$agenda = qx@{$cmd 2>/dev/null@}; ++ ++# loop over all lines ++foreach $line (split(/\n/,$agenda)) @{ ++ ++ # get the individual values ++ ($category,$head,$type,$todo,$tags,$date,$time,$extra, ++ $priority_l,$priority_n) = split(/,/,$line); ++ ++ # process and print ++ print "[ ] $head\n"; ++@} ++@end group ++@end example ++ ++@node Agenda column view, , Custom agenda views, Agenda Views ++@section Using column view in the agenda ++@cindex column view, in agenda ++@cindex agenda, column view ++ ++Column view (@pxref{Column view}) is normally used to view and edit ++properties embedded in the hierarchical structure of an Org file. It can be ++quite useful to use column view also from the agenda, where entries are ++collected by certain criteria. ++ ++@table @kbd ++@kindex C-c C-x C-c ++@item C-c C-x C-c ++Turn on column view in the agenda. ++@end table ++ ++To understand how to use this properly, it is important to realize that the ++entries in the agenda are no longer in their proper outline environment. ++This causes the following issues: ++ ++@enumerate ++@item ++Org needs to make a decision which @code{COLUMNS} format to use. Since the ++entries in the agenda are collected from different files, and different files ++may have different @code{COLUMNS} formats, this is a non-trivial problem. ++Org first checks if the variable @code{org-overriding-columns-format} is ++currently set, and if yes takes the format from there. Otherwise it takes ++the format associated with the first item in the agenda, or, if that item ++does not have a specific format (defined in a property, or in it's file), it ++uses @code{org-columns-default-format}. ++@item ++If any of the columns has a summary type defined (@pxref{Column attributes}), ++turning on column view in the agenda will visit all relevant agenda files and ++make sure that the computations of this property are up to date. This is ++also true for the special @code{CLOCKSUM} property. Org will then sum the ++values displayed in the agenda. In the daily/weekly agenda, the sums will ++cover a single day, in all other views they cover the entire block. It is ++vital to realize that the agenda may show the same entry @emph{twice} (for ++example as scheduled and as a deadline), and it may show two entries from the ++same hierarchy (for example a @emph{parent} and it's @emph{child}). In these ++cases, the summation in the agenda will lead to incorrect results because ++some values will count double. ++@item ++When the column view in the agenda shows the @code{CLOCKSUM}, that is always ++the entire clocked time for this item. So even in the daily/weekly agenda, ++the clocksum listed in column view may originate from times outside the ++current view. This has the advantage that you can compare these values with ++a column listing the planned total effort for a task - one of the major ++applications for column view in the agenda. If you want information about ++clocked time in the displayed period use clock table mode (press @kbd{R} in ++the agenda). ++@end enumerate ++ ++ ++@node Embedded LaTeX, Exporting, Agenda Views, Top ++@chapter Embedded LaTeX ++@cindex @TeX{} interpretation ++@cindex La@TeX{} interpretation ++ ++Plain ASCII is normally sufficient for almost all note taking. One ++exception, however, are scientific notes which need to be able to contain ++mathematical symbols and the occasional formula. La@TeX{}@footnote{La@TeX{} ++is a macro system based on Donald E. Knuth's @TeX{} system. Many of the ++features described here as ``La@TeX{}'' are really from @TeX{}, but for ++simplicity I am blurring this distinction.} is widely used to typeset ++scientific documents. Org mode supports embedding La@TeX{} code into its ++files, because many academics are used to reading La@TeX{} source code, and ++because it can be readily processed into images for HTML production. ++ ++It is not necessary to mark La@TeX{} macros and code in any special way. ++If you observe a few conventions, Org mode knows how to find it and what ++to do with it. ++ ++@menu ++* Math symbols:: TeX macros for symbols and Greek letters ++* Subscripts and superscripts:: Simple syntax for raising/lowering text ++* LaTeX fragments:: Complex formulas made easy ++* Processing LaTeX fragments:: Previewing LaTeX processing ++* CDLaTeX mode:: Speed up entering of formulas ++@end menu ++ ++@node Math symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX ++@section Math symbols ++@cindex math symbols ++@cindex TeX macros ++ ++You can use La@TeX{} macros to insert special symbols like @samp{\alpha} to ++indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion ++for these macros is available, just type @samp{\} and maybe a few letters, ++and press @kbd{M-@key{TAB}} to see possible completions. Unlike La@TeX{} ++code, Org mode allows these macros to be present without surrounding math ++delimiters, for example: ++ ++@example ++Angles are written as Greek letters \alpha, \beta and \gamma. ++@end example ++ ++During HTML export (@pxref{HTML export}), these symbols are translated ++into the proper syntax for HTML, for the above examples this is ++@samp{α} and @samp{→}, respectively. If you need such a symbol ++inside a word, terminate it like this: @samp{\Aacute@{@}stor}. ++ ++@node Subscripts and superscripts, LaTeX fragments, Math symbols, Embedded LaTeX ++@section Subscripts and superscripts ++@cindex subscript ++@cindex superscript ++ ++Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super- ++and subscripts. Again, these can be used without embedding them in ++math-mode delimiters. To increase the readability of ASCII text, it is ++not necessary (but OK) to surround multi-character sub- and superscripts ++with curly braces. For example ++ ++@example ++The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of ++the sun is R_@{sun@} = 6.96 x 10^8 m. ++@end example ++ ++To avoid interpretation as raised or lowered text, you can quote ++@samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}. ++ ++During HTML export (@pxref{HTML export}), subscript and superscripts ++are surrounded with @code{} and @code{} tags, respectively. ++ ++@node LaTeX fragments, Processing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX ++@section LaTeX fragments ++@cindex LaTeX fragments ++ ++With symbols, sub- and superscripts, HTML is pretty much at its end when ++it comes to representing mathematical formulas@footnote{Yes, there is ++MathML, but that is not yet fully supported by many browsers, and there ++is no decent converter for turning La@TeX{} or ASCII representations of ++formulas into MathML. So for the time being, converting formulas into ++images seems the way to go.}. More complex expressions need a dedicated ++formula processor. To this end, Org mode can contain arbitrary La@TeX{} ++fragments. It provides commands to preview the typeset result of these ++fragments, and upon export to HTML, all fragments will be converted to ++images and inlined into the HTML document@footnote{The La@TeX{} export ++will not use images for displaying La@TeX{} fragments but include these ++fragments directly into the La@TeX{} code.}. For this to work you ++need to be on a system with a working La@TeX{} installation. You also ++need the @file{dvipng} program, available at ++@url{http://sourceforge.net/projects/dvipng/}. The La@TeX{} header that ++will be used when processing a fragment can be configured with the ++variable @code{org-format-latex-header}. ++ ++La@TeX{} fragments don't need any special marking at all. The following ++snippets will be identified as La@TeX{} source code: ++@itemize @bullet ++@item ++Environments of any kind. The only requirement is that the ++@code{\begin} statement appears on a new line, preceded by only ++whitespace. ++@item ++Text within the usual La@TeX{} math delimiters. To avoid conflicts with ++currency specifications, single @samp{$} characters are only recognized as ++math delimiters if the enclosed text contains at most two line breaks, is ++directly attached to the @samp{$} characters with no whitespace in between, ++and if the closing @samp{$} is followed by whitespace, punctuation or a dash. ++For the other delimiters, there is no such restriction, so when in doubt, use ++@samp{\(...\)} as inline math delimiters. ++@end itemize ++ ++@noindent For example: ++ ++@example ++\begin@{equation@} % arbitrary environments, ++x=\sqrt@{b@} % even tables, figures ++\end@{equation@} % etc ++ ++If $a^2=b$ and \( b=2 \), then the solution must be ++either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. ++@end example ++ ++@noindent ++If you need any of the delimiter ASCII sequences for other purposes, you ++can configure the option @code{org-format-latex-options} to deselect the ++ones you do not wish to have interpreted by the La@TeX{} converter. ++ ++@node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX ++@section Processing LaTeX fragments ++@cindex LaTeX fragments, preview ++ ++La@TeX{} fragments can be processed to produce a preview images of the ++typeset expressions: ++ ++@table @kbd ++@kindex C-c C-x C-l ++@item C-c C-x C-l ++Produce a preview image of the La@TeX{} fragment at point and overlay it ++over the source code. If there is no fragment at point, process all ++fragments in the current entry (between two headlines). When called ++with a prefix argument, process the entire subtree. When called with ++two prefix arguments, or when the cursor is before the first headline, ++process the entire buffer. ++@kindex C-c C-c ++@item C-c C-c ++Remove the overlay preview images. ++@end table ++ ++During HTML export (@pxref{HTML export}), all La@TeX{} fragments are ++converted into images and inlined into the document if the following ++setting is active: ++ ++@lisp ++(setq org-export-with-LaTeX-fragments t) ++@end lisp ++ ++@node CDLaTeX mode, , Processing LaTeX fragments, Embedded LaTeX ++@section Using CDLaTeX to enter math ++@cindex CDLaTeX ++ ++CDLaTeX mode is a minor mode that is normally used in combination with a ++major La@TeX{} mode like AUCTeX in order to speed-up insertion of ++environments and math templates. Inside Org mode, you can make use of ++some of the features of CDLaTeX mode. You need to install ++@file{cdlatex.el} and @file{texmathp.el} (the latter comes also with ++AUCTeX) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. ++Don't use CDLaTeX mode itself under Org mode, but use the light ++version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it ++on for the current buffer with @code{M-x org-cdlatex-mode}, or for all ++Org files with ++ ++@lisp ++(add-hook 'org-mode-hook 'turn-on-org-cdlatex) ++@end lisp ++ ++When this mode is enabled, the following features are present (for more ++details see the documentation of CDLaTeX mode): ++@itemize @bullet ++@kindex C-c @{ ++@item ++Environment templates can be inserted with @kbd{C-c @{}. ++@item ++@kindex @key{TAB} ++The @key{TAB} key will do template expansion if the cursor is inside a ++La@TeX{} fragment@footnote{Org mode has a method to test if the cursor is ++inside such a fragment, see the documentation of the function ++@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will ++expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor ++correctly inside the first brace. Another @key{TAB} will get you into ++the second brace. Even outside fragments, @key{TAB} will expand ++environment abbreviations at the beginning of a line. For example, if ++you write @samp{equ} at the beginning of a line and press @key{TAB}, ++this abbreviation will be expanded to an @code{equation} environment. ++To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}. ++@item ++@kindex _ ++@kindex ^ ++Pressing @kbd{_} and @kbd{^} inside a La@TeX{} fragment will insert these ++characters together with a pair of braces. If you use @key{TAB} to move ++out of the braces, and if the braces surround only a single character or ++macro, they are removed again (depending on the variable ++@code{cdlatex-simplify-sub-super-scripts}). ++@item ++@kindex ` ++Pressing the backquote @kbd{`} followed by a character inserts math ++macros, also outside La@TeX{} fragments. If you wait more than 1.5 seconds ++after the backquote, a help window will pop up. ++@item ++@kindex ' ++Pressing the normal quote @kbd{'} followed by another character modifies ++the symbol before point with an accent or a font. If you wait more than ++1.5 seconds after the backquote, a help window will pop up. Character ++modification will work only inside La@TeX{} fragments, outside the quote ++is normal. ++@end itemize ++ ++@node Exporting, Publishing, Embedded LaTeX, Top ++@chapter Exporting ++@cindex exporting ++ ++Org mode documents can be exported into a variety of other formats. For ++printing and sharing of notes, ASCII export produces a readable and ++simple version of an Org file. HTML export allows you to publish a ++notes file on the web, while the XOXO format provides a solid base for ++exchange with a broad range of other applications. La@TeX{} export lets ++you use Org mode and its structured editing functions to easily create ++La@TeX{} files. To incorporate entries with associated times like ++deadlines or appointments into a desktop calendar program like iCal, ++Org mode can also produce extracts in the iCalendar format. Currently ++Org mode only supports export, not import of these different formats. ++ ++Org supports export of selected regions when @code{transient-mark-mode} is ++enabled (default in Emacs 23). ++ ++@menu ++* Markup rules:: Which structures are recognized? ++* Selective export:: Using tags to select and exclude trees ++* Export options:: Per-file export settings ++* The export dispatcher:: How to access exporter commands ++* ASCII export:: Exporting to plain ASCII ++* HTML export:: Exporting to HTML ++* LaTeX and PDF export:: Exporting to LaTeX, and processing to PDF ++* XOXO export:: Exporting to XOXO ++* iCalendar export:: Exporting in iCalendar format ++@end menu ++ ++@node Markup rules, Selective export, Exporting, Exporting ++@section Markup rules ++ ++When exporting Org mode documents, the exporter tries to reflect the ++structure of the document as accurately as possible in the back-end. Since ++export targets like HTML or La@TeX{} allow much richer formatting, Org mode ++has rules how to prepare text for rich export. This section summarizes the ++markup rule used in an Org mode buffer. ++ ++@menu ++* Document title:: How the document title is determined ++* Headings and sections:: The main structure of the exported document ++* Table of contents:: If, where, how to create a table of contents ++* Initial text:: Text before the first headline ++* Lists:: Plain lists are exported ++* Paragraphs:: What determines beginning and ending ++* Literal examples:: Source code and other examples ++* Include files:: Include the contents of a file during export ++* Tables exported:: Tables are exported richly ++* Inlined images:: How to inline images during export ++* Footnote markup:: ++* Emphasis and monospace:: To bold or not to bold ++* TeX macros and LaTeX fragments:: Create special, rich export. ++* Horizontal rules:: A line across the page ++* Comment lines:: Some lines will not be exported ++@end menu ++ ++@node Document title, Headings and sections, Markup rules, Markup rules ++@subheading Document title ++@cindex document title, markup rules ++ ++@noindent ++The title of the exported document is taken from the special line ++ ++@example ++#+TITLE: This is the title of the document ++@end example ++ ++@noindent ++If this line does not exist, the title is derived from the first non-empty, ++non-comment line in the buffer. If no such line exists, or if you have ++turned off exporting of the text before the first headline (see below), the ++title will be the file name without extension. ++ ++If you are exporting only a subtree by marking is as the region, the heading ++of the subtree will become the title of the document. If the subtree has a ++property @code{EXPORT_TITLE}, that will take precedence. ++ ++@node Headings and sections, Table of contents, Document title, Markup rules ++@subheading Headings and sections ++@cindex headings and sections, markup rules ++ ++The outline structure of the document as described in @ref{Document ++Structure} forms the basis for defining sections of the exported document. ++However, since the outline structure is also used for (for example) lists of ++tasks, only the first three outline levels will be used as headings. Deeper ++levels will become itemized lists. You can change the location of this ++switch, globally by setting the variable @code{org-headline-levels}, or on a ++per file basis with a line ++ ++@example ++#+OPTIONS: H:4 ++@end example ++ ++@node Table of contents, Initial text, Headings and sections, Markup rules ++@subheading Table of contents ++@cindex table of contents, markup rules ++ ++The table of contents is normally inserted directly before the first headline ++of the file. If you would like to get it to a different location, insert the ++string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired ++location. The depth of the table of contents is by default the same as the ++number of headline levels, but you can choose a smaller number or turn off ++the table of contents entirely by configuring the variable ++@code{org-export-with-toc}, or on a per-file basis with a line like ++ ++@example ++#+OPTIONS: toc:2 (only to two levels in TOC) ++#+OPTIONS: toc:nil (no TOC at all) ++@end example ++ ++@node Initial text, Lists, Table of contents, Markup rules ++@subheading Text before the first headline ++@cindex text before first headline, markup rules ++@cindex #+TEXT ++ ++Org mode normally exports the text before the first headline, and even uses ++the first line as the document title. The text will be fully marked up. If ++you need to include literal HTML or La@TeX{} code, use the special constructs ++described below in the sections for the individual exporters. ++ ++Some people like to use the space before the first headline for setup and ++internal links and therefore would like to control the exported text before ++the first headline in a different way. You can do so by setting the variable ++@code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-file ++basis, you can get the same effect with @samp{#+OPTIONS: skip:t}. ++ ++@noindent ++If you still want to have some text before the first headline, use the ++@code{#+TEXT} construct: ++ ++@example ++#+OPTIONS: skip:t ++#+TEXT: This text will go before the *first* headline. ++#+TEXT: [TABLE-OF-CONTENTS] ++#+TEXT: This goes between the table of contents and the first headline ++@end example ++ ++@node Lists, Paragraphs, Initial text, Markup rules ++@subheading Lists ++@cindex lists, markup rules ++ ++Plain lists as described in @ref{Plain lists} are translated to the back-ends ++syntax for such lists. Most back-ends support unordered, ordered, and ++description lists. ++ ++@node Paragraphs, Literal examples, Lists, Markup rules ++@subheading Paragraphs, line breaks, and quoting ++@cindex paragraphs, markup rules ++ ++Paragraphs are separated by at least one empty line. If you need to enforce ++a line break within a paragraph, use @samp{\\} at the end of a line. ++ ++To keep the line breaks in a region, but otherwise use normal formatting, you ++can use this construct, which can also be used to format poetry. ++ ++@example ++#+BEGIN_VERSE ++ Great clouds overhead ++ Tiny black birds rise and fall ++ Snow covers Emacs ++ ++ -- AlexSchroeder ++#+END_VERSE ++@end example ++ ++When quoting a passage from another document, it is customary to format this ++as a paragraph that is indented on both the left and the right margin. You ++can include quotations in Org mode documents like this: ++ ++@example ++#+BEGIN_QUOTE ++Everything should be made as simple as possible, ++but not any simpler -- Albert Einstein ++#+END_QUOTE ++@end example ++ ++ ++@node Literal examples, Include files, Paragraphs, Markup rules ++@subheading Literal examples ++@cindex literal examples, markup rules ++@cindex code line refenences, markup rules ++ ++You can include literal examples that should not be subjected to ++markup. Such examples will be typeset in monospace, so this is well suited ++for source code and similar examples. ++@cindex #+BEGIN_EXAMPLE ++ ++@example ++#+BEGIN_EXAMPLE ++Some example from a text file. ++#+END_EXAMPLE ++@end example ++ ++For simplicity when using small examples, you can also start the example ++lines with a colon followed by a space. There may also be additional ++whitespace before the colon: ++ ++@example ++Here is an example ++ : Some example from a text file. ++@end example ++ ++@cindex formatting source code, markup rules ++If the example is source code from a programming language, or any other text ++that can be marked up by font-lock in Emacs, you can ask for the example to ++look like the fontified Emacs buffer@footnote{Currently this works only for ++the HTML back-end, and requires the @file{htmlize.el} package version 1.34 or ++later.}. This is done with the @samp{src} block, where you also need to ++specify the name of the major mode that should be used to fontify the ++example: ++@cindex #+BEGIN_SRC ++ ++@example ++#+BEGIN_SRC emacs-lisp ++(defun org-xor (a b) ++ "Exclusive or." ++ (if a (not b) b)) ++#+END_SRC ++@end example ++ ++Both in @code{example} and in @code{src} snippets, you can add a @code{-n} ++switch to the end of the @code{BEGIN} line, to get the lines of the example ++numbered. If you use a @code{+n} switch, the numbering from the previous ++numbered snippet will be continued in the current one. In literal examples, ++Org will interpret strings like @samp{(ref:name)} as labels, and use them as ++targets for special hyperlinks like @code{[[(name)]]} (i.e. the reference ++name enclosed in single parenthesis). In HTML, hovering the mouse over such ++a link will remote-highlight the corresponding code line, which is kind of ++cool. If the example/src snippet is numbered, you can also add a @code{-r} ++switch. Then labels will be @i{removed} from the source code and the links ++will be @i{replaced}@footnote{If you want to explain the use of such labels ++themelves in org-mode example code, you can use the @code{-k} switch to make ++sure they are not touched.} with line numbers from the code listing. Here is ++an example: ++ ++@example ++#+BEGIN_SRC emacs-lisp -n -r ++(save-excursion (ref:sc) ++ (goto-char (point-min)) (ref:jump) ++#+END SRC ++In line [[(sc)]] we remember the current positon. [[(jump)][Line (jump)]] ++jumps to point-min. ++@end example ++ ++If the syntax for the label format conflicts with the language syntax, use a ++@code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal ++-n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}. ++ ++HTML export also allows examples to be published as text areas, @pxref{Text ++areas in HTML export}. ++ ++@table @kbd ++@kindex C-c ' ++@item C-c ' ++Edit the source code example at point in its native mode. This works by ++switching to an indirect buffer, narrowing the buffer and switching to the ++other mode. You need to exit by pressing @kbd{C-c '} again@footnote{Upon ++exit, lines starting with @samp{*} or @samp{#} will get a comma prepended, to ++keep them from being interpreted by Org as outline nodes or special ++comments. These commas will be striped for editing with @kbd{C-c '}, and ++also for export.}. Fixed-width ++regions (where each line starts with a colon followed by a space) will be ++edited using @code{artist-mode}@footnote{You may select a different-mode with ++the variable @code{org-edit-fixed-width-region-mode}.} to allow creating ++ASCII drawings easily. Using this command in an empty line will create a new ++fixed-width region. ++@kindex C-c l ++@item C-c l ++Calling @code{org-store-link} while editing a source code example in a ++temporary buffer created with @kbd{C-c '} will prompt for a label, make sure ++that it is unique in the current buffer, and insert it with the proper ++formatting like @samp{(ref:label)} at the end of the current line. Then the ++label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}. ++@end table ++ ++ ++@node Include files, Tables exported, Literal examples, Markup rules ++@subheading Include files ++@cindex include files, markup rules ++ ++During export, you can include the content of another file. For example, to ++include your .emacs file, you could use: ++@cindex #+INCLUDE ++ ++@example ++#+INCLUDE: "~/.emacs" src emacs-lisp ++@end example ++ ++The optional second and third parameter are the markup (@samp{quote}, ++@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the ++language for formatting the contents. The markup is optional, if it is not ++given, the text will be assumed to be in Org mode format and will be ++processed normally. The include line will also allow additional keyword ++parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the ++first line and for each following line, as well as any options accepted by ++the selected markup. For example, to include a file as an item, use ++ ++@example ++#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " " ++@end example ++ ++@table @kbd ++@kindex C-c ' ++@item C-c ' ++Visit the include file at point. ++@end table ++ ++@node Tables exported, Inlined images, Include files, Markup rules ++@subheading Tables ++@cindex tables, markup rules ++ ++Both the native Org mode tables (@pxref{Tables}) and tables formatted with ++the @file{table.el} package will be exported properly. For Org mode tables, ++the lines before the first horizontal separator line will become table header ++lines. You can use the following lines somewhere before the table to assign ++a caption and a label for cross references: ++ ++@example ++#+CAPTION: This is the caption for the next table (or link) ++#+LABEL: tbl:basic-data ++@end example ++ ++@node Inlined images, Footnote markup, Tables exported, Markup rules ++@subheading Inlined Images ++@cindex inlined images, markup rules ++ ++Some backends (HTML and LaTeX) allow to directly include images into the ++exported document. Org does this, if a link to an image files does not have ++a description part, for example @code{[[./img/a.jpg]]}. If you wish to ++define a caption for the image and maybe a label for internal cross ++references, you can use (before, but close to the link) ++ ++@example ++#+CAPTION: This is the caption for the next figure link (or table) ++#+LABEL: fig:SED-HR4049 ++@end example ++ ++You may also define additional attributes for the figure. As this is ++backend-specific, see the sections about the individual backends for more ++information. ++ ++@node Footnote markup, Emphasis and monospace, Inlined images, Markup rules ++@subheading Footnote markup ++@cindex footnotes, markup rules ++@cindex @file{footnote.el} ++ ++Footnotes defined in the way descriped in @ref{Footnotes} will be exported by ++all backends. Org does allow multiple references to the same note, and ++different backends support this to varying degree. ++ ++@node Emphasis and monospace, TeX macros and LaTeX fragments, Footnote markup, Markup rules ++@subheading Emphasis and monospace ++ ++@cindex underlined text, markup rules ++@cindex bold text, markup rules ++@cindex italic text, markup rules ++@cindex verbatim text, markup rules ++@cindex code text, markup rules ++@cindex strike-through text, markup rules ++You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} ++and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text ++in the code and verbatim string is not processed for Org mode specific ++syntax, it is exported verbatim. ++ ++@node TeX macros and LaTeX fragments, Horizontal rules, Emphasis and monospace, Markup rules ++@subheading @TeX{} macros and La@TeX{} fragments ++@cindex LaTeX fragments, markup rules ++@cindex TeX macros, markup rules ++@cindex HTML entities ++@cindex LaTeX entities ++ ++A @TeX{}-like syntax is used to specify special characters. Where possible, ++these will be transformed into the native format of the exporter back-end. ++Strings like @code{\alpha} will be exported as @code{α} in the HTML ++output, and as @code{$\alpha$} in the La@TeX{} output. Similarly, ++@code{\nbsp} will become @code{ } in HTML and @code{~} in La@TeX{}. ++This applies for a large number of entities, with names taken from both HTML ++and La@TeX{}, see the variable @code{org-html-entities} for the complete ++list. If you are unsure about a name, use @kbd{M-@key{TAB}} for completion ++after having typed the backslash and maybe a few characters ++(@pxref{Completion}). ++ ++La@TeX{} fragments are converted into images for HTML export, and they are ++written literally into the La@TeX{} export. See also @ref{Embedded LaTeX}. ++ ++Finally, @samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and ++@samp{...} are all converted into special commands creating hyphens of ++different lengths or a compact set of dots. ++ ++@node Horizontal rules, Comment lines, TeX macros and LaTeX fragments, Markup rules ++@subheading Horizontal rules ++@cindex horizontal rules, markup rules ++A line consisting of only dashes, and at least 5 of them, will be ++exported as a horizontal line (@samp{
} in HTML). ++ ++@node Comment lines, , Horizontal rules, Markup rules ++@subheading Comment lines ++@cindex comment lines ++@cindex exporting, not ++ ++Lines starting with @samp{#} in column zero are treated as comments and will ++never be exported. Also entire subtrees starting with the word ++@samp{COMMENT} will never be exported. Finally, regions surrounded by ++@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported. ++ ++@table @kbd ++@kindex C-c ; ++@item C-c ; ++Toggle the COMMENT keyword at the beginning of an entry. ++@end table ++ ++@node Selective export, Export options, Markup rules, Exporting ++@section Selective export ++@cindex export, selective by tags ++ ++You may use tags to select the parts of a document that should be exported, ++or to exclude parts from export. This behavior is governed by two variables: ++@code{org-export-select-tags} and @code{org-export-exclude-tags}. ++ ++Org first checks if any of the @emph{select} tags is present in the buffer. ++If yes, all trees that do not carry one of these tags will be excluded. If a ++selected tree is a subtree, the heading hierarchy above it will also be ++selected for export, but not the text below those headings. ++ ++@noindent ++If none of the select tags is found, the whole buffer will be selected for ++export. ++ ++@noindent ++Finally, all subtrees that are marked by any of the @emph{exclude} tags will ++be removed from the export buffer. ++ ++@node Export options, The export dispatcher, Selective export, Exporting ++@section Export options ++@cindex options, for export ++ ++@cindex completion, of option keywords ++The exporter recognizes special lines in the buffer which provide ++additional information. These lines may be put anywhere in the file. ++The whole set of lines can be inserted into the buffer with @kbd{C-c ++C-e t}. For individual lines, a good way to make sure the keyword is ++correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion ++(@pxref{Completion}). ++ ++@table @kbd ++@kindex C-c C-e t ++@item C-c C-e t ++Insert template with export options, see example below. ++@end table ++ ++@cindex #+TITLE: ++@cindex #+AUTHOR: ++@cindex #+DATE: ++@cindex #+EMAIL: ++@cindex #+LANGUAGE: ++@cindex #+TEXT: ++@cindex #+OPTIONS: ++@cindex #+LINK_UP: ++@cindex #+LINK_HOME: ++@cindex #+EXPORT_SELECT_TAGS: ++@cindex #+EXPORT_EXCLUDE_TAGS: ++@example ++#+TITLE: the title to be shown (default is the buffer name) ++#+AUTHOR: the author (default taken from @code{user-full-name}) ++#+DATE: A date, fixed, of a format string for @code{format-time-string} ++#+EMAIL: his/her email address (default from @code{user-mail-address}) ++#+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language}) ++#+TEXT: Some descriptive text to be inserted at the beginning. ++#+TEXT: Several lines may be given. ++#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... ++#+LINK_UP: the ``up'' link of an exported page ++#+LINK_HOME: the ``home'' link of an exported page ++#+EXPORT_SELECT_TAGS: Tags that select a tree for export ++#+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export ++@end example ++ ++@noindent ++The OPTIONS line is a compact@footnote{If you want to configure many options ++this way, you can use several OPTIONS lines.} form to specify export settings. Here ++you can: ++@cindex headline levels ++@cindex section-numbers ++@cindex table of contents ++@cindex line-break preservation ++@cindex quoted HTML tags ++@cindex fixed-width sections ++@cindex tables ++@cindex @TeX{}-like syntax for sub- and superscripts ++@cindex footnotes ++@cindex special strings ++@cindex emphasized text ++@cindex @TeX{} macros ++@cindex La@TeX{} fragments ++@cindex author info, in export ++@cindex time info, in export ++@example ++H: @r{set the number of headline levels for export} ++num: @r{turn on/off section-numbers} ++toc: @r{turn on/off table of contents, or set level limit (integer)} ++\n: @r{turn on/off line-break-preservation} ++@@: @r{turn on/off quoted HTML tags} ++:: @r{turn on/off fixed-width sections} ++|: @r{turn on/off tables} ++^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If} ++ @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but} ++ @r{the simple @code{a_b} will be left as it is.} ++-: @r{turn on/off conversion of special strings.} ++f: @r{turn on/off footnotes like this[1].} ++todo: @r{turn on/off inclusion of TODO keywords into exported text} ++pri: @r{turn on/off priority cookies} ++tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}} ++<: @r{turn on/off inclusion of any time/date stamps like DEADLINES} ++*: @r{turn on/off emphasized text (bold, italic, underlined)} ++TeX: @r{turn on/off simple @TeX{} macros in plain text} ++LaTeX: @r{turn on/off La@TeX{} fragments} ++skip: @r{turn on/off skipping the text before the first heading} ++author: @r{turn on/off inclusion of author name/email into exported file} ++creator: @r{turn on/off inclusion of creator info into exported file} ++timestamp: @r{turn on/off inclusion creation time into exported file} ++d: @r{turn on/off inclusion of drawers} ++@end example ++ ++These options take effect in both the HTML and La@TeX{} export, except ++for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and ++@code{nil} for the La@TeX{} export. ++ ++When exporting only a single subtree by selecting it with @kbd{C-c @@} before ++calling an export command, the subtree can overrule some of the file's export ++settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE}, ++@code{EXPORT_TEXT}, and @code{EXPORT_OPTIONS}. ++ ++@node The export dispatcher, ASCII export, Export options, Exporting ++@section The export dispatcher ++@cindex dispatcher, for export commands ++ ++All export commands can be reached using the export dispatcher, which is a ++prefix key that prompts for an additional key specifying the command. ++Normally the entire file is exported, but if there is an active region that ++contains one outline tree, the first heading is used as document title and ++the subtrees are exported. ++ ++@table @kbd ++@kindex C-c C-e ++@item C-c C-e ++Dispatcher for export and publishing commands. Displays a help-window ++listing the additional key(s) needed to launch an export or publishing ++command. The prefix arg is passed through to the exporter. A double prefix ++@kbd{C-u C-u} causes most commands to be executed in the background, in a ++separate emacs process@footnote{To make this behavior the default, customize ++the variable @code{org-export-run-in-background}.}. ++@kindex C-c C-e v ++@item C-c C-e v ++Like @kbd{C-c C-e}, but only export the text that is currently visible ++(i.e. not hidden by outline visibility). ++@kindex C-u C-u C-c C-e ++@item C-u C-u C-c C-e ++Call an the exporter, but reverse the setting of ++@code{org-export-run-in-background}, i.e. request background processing if ++not set, or force processing in the current Emacs process if st. ++@end table ++ ++@node ASCII export, HTML export, The export dispatcher, Exporting ++@section ASCII export ++@cindex ASCII export ++ ++ASCII export produces a simple and very readable version of an Org mode ++file. ++ ++@cindex region, active ++@cindex active region ++@cindex transient-mark-mode ++@table @kbd ++@kindex C-c C-e a ++@item C-c C-e a ++Export as ASCII file. For an org file @file{myfile.org}, the ASCII file ++will be @file{myfile.txt}. The file will be overwritten without ++warning. If there is an active region@footnote{this requires ++@code{transient-mark-mode} to be turned on}, only the region will be ++exported. If the selected region is a single tree@footnote{To select the ++current subtree, use @kbd{C-c @@}.}, the tree head will ++become the document title. If the tree head entry has or inherits an ++@code{EXPORT_FILE_NAME} property, that name will be used for the ++export. ++@kindex C-c C-e v a ++@item C-c C-e v a ++Export only the visible part of the document. ++@end table ++ ++@cindex headline levels, for exporting ++In the exported version, the first 3 outline levels will become ++headlines, defining a general document structure. Additional levels ++will be exported as itemized lists. If you want that transition to occur ++at a different level, specify it with a prefix argument. For example, ++ ++@example ++@kbd{C-1 C-c C-e a} ++@end example ++ ++@noindent ++creates only top level headlines and does the rest as items. When ++headlines are converted to items, the indentation of the text following ++the headline is changed to fit nicely under the item. This is done with ++the assumption that the first body line indicates the base indentation of ++the body text. Any indentation larger than this is adjusted to preserve ++the layout relative to the first line. Should there be lines with less ++indentation than the first, these are left alone. ++ ++@node HTML export, LaTeX and PDF export, ASCII export, Exporting ++@section HTML export ++@cindex HTML export ++ ++Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive ++HTML formatting, in ways similar to John Gruber's @emph{markdown} ++language, but with additional support for tables. ++ ++@menu ++* HTML Export commands:: How to invoke HTML export ++* Quoting HTML tags:: Using direct HTML in Org mode ++* Links:: Transformation of links for HTML ++* Images in HTML export:: How to insert figures into HTML output ++* Text areas in HTML export:: An alternative way to show an example ++* CSS support:: Changing the appearance of the output ++* Javascript support:: Info and Folding in a web browser ++@end menu ++ ++@node HTML Export commands, Quoting HTML tags, HTML export, HTML export ++@subsection HTML export commands ++ ++@cindex region, active ++@cindex active region ++@cindex transient-mark-mode ++@table @kbd ++@kindex C-c C-e h ++@item C-c C-e h ++Export as HTML file @file{myfile.html}. For an org file @file{myfile.org}, ++the ASCII file will be @file{myfile.html}. The file will be overwritten ++without warning. If there is an active region@footnote{this requires ++@code{transient-mark-mode} to be turned on}, only the region will be ++exported. If the selected region is a single tree@footnote{To select the ++current subtree, use @kbd{C-c @@}.}, the tree head will become the document ++title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} ++property, that name will be used for the export. ++@kindex C-c C-e b ++@item C-c C-e b ++Export as HTML file and immediately open it with a browser. ++@kindex C-c C-e H ++@item C-c C-e H ++Export to a temporary buffer, do not create a file. ++@kindex C-c C-e R ++@item C-c C-e R ++Export the active region to a temporary buffer. With a prefix argument, do ++not produce the file header and footer, but just the plain HTML section for ++the region. This is good for cut-and-paste operations. ++@kindex C-c C-e v h ++@kindex C-c C-e v b ++@kindex C-c C-e v H ++@kindex C-c C-e v R ++@item C-c C-e v h ++@item C-c C-e v b ++@item C-c C-e v H ++@item C-c C-e v R ++Export only the visible part of the document. ++@item M-x org-export-region-as-html ++Convert the region to HTML under the assumption that it was Org mode ++syntax before. This is a global command that can be invoked in any ++buffer. ++@item M-x org-replace-region-by-HTML ++Replace the active region (assumed to be in Org mode syntax) by HTML ++code. ++@end table ++ ++@cindex headline levels, for exporting ++In the exported version, the first 3 outline levels will become headlines, ++defining a general document structure. Additional levels will be exported as ++itemized lists. If you want that transition to occur at a different level, ++specify it with a numeric prefix argument. For example, ++ ++@example ++@kbd{C-2 C-c C-e b} ++@end example ++ ++@noindent ++creates two levels of headings and does the rest as items. ++ ++@node Quoting HTML tags, Links, HTML Export commands, HTML export ++@subsection Quoting HTML tags ++ ++Plain @samp{<} and @samp{>} are always transformed to @samp{<} and ++@samp{>} in HTML export. If you want to include simple HTML tags ++which should be interpreted as such, mark them with @samp{@@} as in ++@samp{@@bold text@@}. Note that this really works only for ++simple tags. For more extensive HTML that should be copied verbatim to ++the exported file use either ++ ++@example ++#+HTML: Literal HTML code for export ++@end example ++ ++@noindent or ++@cindex #+BEGIN_HTML ++ ++@example ++#+BEGIN_HTML ++All lines between these markers are exported literally ++#+END_HTML ++@end example ++ ++ ++@node Links, Images in HTML export, Quoting HTML tags, HTML export ++@subsection Links ++ ++@cindex links, in HTML export ++@cindex internal links, in HTML export ++@cindex external links, in HTML export ++Internal links (@pxref{Internal links}) will continue to work in HTML. This ++does include automatic links created by radio targets (@pxref{Radio ++targets}). Links to external files will still work if the target file is on ++the same @i{relative} path as the published Org file. Links to other ++@file{.org} files will be translated into HTML links under the assumption ++that an HTML version also exists of the linked file, at the same relative ++path. @samp{id:} links can then be used to jump to specific entries across ++files. For information related to linking files while publishing them to a ++publishing directory see @ref{Publishing links}. ++ ++If you want to specify attributes for links, you can do so using a special ++@code{#+ATTR_HTML} line to define attributes that will be added to the ++@code{} or @code{} tags. Here is an example that sets @code{alt} and ++@code{title} attributes for an inlined image: ++ ++@example ++#+ATTR_HTML: alt="This is image A" title="Image with no action" ++[[./img/a.jpg]] ++@end example ++ ++@node Images in HTML export, Text areas in HTML export, Links, HTML export ++@subsection Images ++ ++@cindex images, inline in HTML ++@cindex inlining images in HTML ++HTML export can inline images given as links in the Org file, and ++it can make an image the clickable part of a link. By ++default@footnote{but see the variable ++@code{org-export-html-inline-images}}, images are inlined if a link does ++not have a description. So @samp{[[file:myimg.jpg]]} will be inlined, ++while @samp{[[file:myimg.jpg][the image]]} will just produce a link ++@samp{the image} that points to the image. If the description part ++itself is a @code{file:} link or a @code{http:} URL pointing to an ++image, this image will be inlined and activated so that clicking on the ++image will activate the link. For example, to include a thumbnail that ++will link to a high resolution version of the image, you could use: ++ ++@example ++[[file:highres.jpg][file:thumb.jpg]] ++@end example ++ ++@noindent ++and you could use @code{http} addresses just as well. ++ ++@node Text areas in HTML export, CSS support, Images in HTML export, HTML export ++@subsection Text areas ++ ++@cindex text areas, in HTML ++An alternative way to publish literal code examples in HTML is to use text ++areas, where the example can even be edited before pasting it into an ++application. It is triggered by a @code{-t} switch at an @code{example} or ++@code{src} block. Using this switch disables any options for syntax and ++label highlighting, and line numbering, which may be present. You may also ++use @code{-h} and @code{-w} switches to specify the height and width of the ++text area, which default to the number of lines in the example, and 80, ++respectively. For example ++ ++@example ++#+BEGIN_EXAMPLE -t -w 40 ++(defun org-xor (a b) ++ "Exclusive or." ++ (if a (not b) b)) ++#+END_EXAMPLE ++@end example ++ ++ ++@node CSS support, Javascript support, Text areas in HTML export, HTML export ++@subsection CSS support ++@cindex CSS, for HTML export ++@cindex HTML export, CSS ++ ++You can also give style information for the exported file. The HTML exporter ++assigns the following special CSS classes to appropriate parts of the ++document - your style specifications may change these, in addition to any of ++the standard classes like for headlines, tables etc. ++@example ++.todo @r{TODO keywords} ++.done @r{the DONE keyword} ++.timestamp @r{time stamp} ++.timestamp-kwd @r{keyword associated with a time stamp, like SCHEDULED} ++.tag @r{tag in a headline} ++.target @r{target for links} ++div.figure @r{how to format an inlined image} ++.linenr @r{the line number in a code example} ++.code-highlighted @r{for highlighting referenced code lines} ++@end example ++ ++Each exported files contains a compact default style that defines these ++classes in a basic way@footnote{This style is defined in the constant ++@code{org-export-html-style-default}, which you should not modify. To turn ++inclusion of these defaults off, customize ++@code{org-export-html-style-include-default}}. You may overwrite these ++settings, or add to them by using the variables @code{org-export-html-style} ++(for Org-wide settings) and @code{org-export-html-style-extra} (for more ++granular settings, like file-local settings). To set the latter variable ++individually for each file, you can use ++ ++@example ++#+STYLE: ++@end example ++ ++@noindent ++For longer style definitions, you can use several such lines. You could also ++directly write a @code{} section in this way, without ++referring to an external file. ++ ++@c FIXME: More about header and footer styles ++@c FIXME: Talk about links and targets. ++ ++@node Javascript support, , CSS support, HTML export ++@subsection Javascript supported display of web pages ++ ++@emph{Sebastian Rose} has written a JavaScript program especially designed to ++enhance the web viewing experience of HTML files created with Org. This ++program allows you to view large files in two different ways. The first one ++is an @emph{Info}-like mode where each section is displayed separately and ++navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys ++as well, press @kbd{?} for an overview of the available keys). The second ++view type is a @emph{folding} view much like Org provides inside Emacs. The ++script is available at @url{http://orgmode.org/org-info.js} and you can find ++the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}. ++We are serving the script from our site, but if you use it a lot, you might ++not want to be dependent on @url{orgmode.org} and prefer to install a local ++copy on your own web server. ++ ++To use the script, you need to make sure that the @file{org-jsinfo.el} module ++gets loaded. It should be loaded by default, but you can try @kbd{M-x ++customize-variable @key{RET} org-modules @key{RET}} to convince yourself that ++this is indeed the case. All it then takes to make use of the program is ++adding a single line to the Org file: ++ ++@example ++#+INFOJS_OPT: view:info toc:nil ++@end example ++ ++@noindent ++If this line is found, the HTML header will automatically contain the code ++needed to invoke the script. Using the line above, you can set the following ++viewing options: ++ ++@example ++path: @r{The path to the script. The default is to grab the script from} ++ @r{@url{http://orgmode.org/org-info.js}, but you might want to have} ++ @r{a local copy and use a path like @samp{../scripts/org-info.js}.} ++view: @r{Initial view when website is first shown. Possible values are:} ++ info @r{Info-like interface with one section per page.} ++ overview @r{Folding interface, initially showing only top-level.} ++ content @r{Folding interface, starting with all headlines visible.} ++ showall @r{Folding interface, all headlines and text visible.} ++sdepth: @r{Maximum headline level that will still become an independent} ++ @r{section for info and folding modes. The default is taken from} ++ @r{@code{org-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).} ++ @r{If this is smaller than in @code{org-headline-levels}, each} ++ @r{info/folding section can still contain children headlines.} ++toc: @r{Should the table of content @emph{initially} be visible?} ++ @r{Even when @code{nil}, you can always get to the toc with @kbd{i}.} ++tdepth: @r{The depth of the table of contents. The defaults are taken from} ++ @r{the variables @code{org-headline-levels} and @code{org-export-with-toc}.} ++ftoc: @r{Does the css of the page specify a fixed position for the toc?} ++ @r{If yes, the toc will never be displayed as a section.} ++ltoc: @r{Should there be short contents (children) in each section?} ++ @r{Make this @code{above} it the section should be above initial text.} ++mouse: @r{Headings are highlighted when the mouse is over them. Should be} ++ @r{@samp{underline} (default) or a background color like @samp{#cccccc}.} ++buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the} ++ @r{default), only one such button will be present.} ++@end example ++ ++You can choose default values for these options by customizing the variable ++@code{org-infojs-options}. If you always want to apply the script to your ++pages, configure the variable @code{org-export-html-use-infojs}. ++ ++@node LaTeX and PDF export, XOXO export, HTML export, Exporting ++@section LaTeX and PDF export ++@cindex LaTeX export ++@cindex PDF export ++ ++Org mode contains a La@TeX{} exporter written by Bastien Guerry. With ++further processing, this backend is also used to produce PDF output. Since ++the LaTeX output uses @file{hyperref} to implement links and cross ++references, the PDF output file will be fully linked. ++ ++@menu ++* LaTeX/PDF export commands:: Which key invokes which commands ++* Quoting LaTeX code:: Incorporating literal LaTeX code ++* Sectioning structure:: Changing sectioning in LaTeX output ++* Tables in LaTeX export:: Options for exporting tables to LaTeX ++* Images in LaTeX export:: How to insert figures into LaTeX output ++@end menu ++ ++@node LaTeX/PDF export commands, Quoting LaTeX code, LaTeX and PDF export, LaTeX and PDF export ++@subsection LaTeX export commands ++ ++@cindex region, active ++@cindex active region ++@cindex transient-mark-mode ++@table @kbd ++@kindex C-c C-e l ++@item C-c C-e l ++Export as La@TeX{} file @file{myfile.tex}. For an org file ++@file{myfile.org}, the ASCII file will be @file{myfile.tex}. The file will ++be overwritten without warning. If there is an active region@footnote{this ++requires @code{transient-mark-mode} to be turned on}, only the region will be ++exported. If the selected region is a single tree@footnote{To select the ++current subtree, use @kbd{C-c @@}.}, the tree head will become the document ++title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME} ++property, that name will be used for the export. ++@kindex C-c C-e L ++@item C-c C-e L ++Export to a temporary buffer, do not create a file. ++@kindex C-c C-e v l ++@kindex C-c C-e v L ++@item C-c C-e v l ++@item C-c C-e v L ++Export only the visible part of the document. ++@item M-x org-export-region-as-latex ++Convert the region to La@TeX{} under the assumption that it was Org mode ++syntax before. This is a global command that can be invoked in any ++buffer. ++@item M-x org-replace-region-by-latex ++Replace the active region (assumed to be in Org mode syntax) by La@TeX{} ++code. ++@kindex C-c C-e p ++@item C-c C-e p ++Export as LaTeX and then process to PDF. ++@kindex C-c C-e d ++@item C-c C-e d ++Export as LaTeX and then process to PDF, then open the resulting PDF file. ++@end table ++ ++@cindex headline levels, for exporting ++In the exported version, the first 3 outline levels will become ++headlines, defining a general document structure. Additional levels ++will be exported as description lists. The exporter can ignore them or ++convert them to a custom string depending on ++@code{org-latex-low-levels}. ++ ++If you want that transition to occur at a different level, specify it ++with a numeric prefix argument. For example, ++ ++@example ++@kbd{C-2 C-c C-e l} ++@end example ++ ++@noindent ++creates two levels of headings and does the rest as items. ++ ++@node Quoting LaTeX code, Sectioning structure, LaTeX/PDF export commands, LaTeX and PDF export ++@subsection Quoting LaTeX code ++ ++Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly ++inserted into the La@TeX{} file. This includes simple macros like ++@samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore, ++you can add special code that should only be present in La@TeX{} export with ++the following constructs: ++ ++@example ++#+LaTeX: Literal LaTeX code for export ++@end example ++ ++@noindent or ++@cindex #+BEGIN_LaTeX ++ ++@example ++#+BEGIN_LaTeX ++All lines between these markers are exported literally ++#+END_LaTeX ++@end example ++ ++@node Sectioning structure, Tables in LaTeX export, Quoting LaTeX code, LaTeX and PDF export ++@subsection Sectioning structure ++@cindex LaTeX class ++@cindex LaTeX sectioning structure ++ ++By default, the La@TeX{} output uses the class @code{article}. ++ ++You can change this globally by setting a different value for ++@code{org-export-latex-default-class} or locally by adding an option like ++@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:} ++property that applies when exporting a region containing only this (sub)tree. ++The class should be listed in @code{org-export-latex-classes}, where you can ++also define the sectioning structure for each class, as well as defining ++additional classes. ++ ++@node Tables in LaTeX export, Images in LaTeX export, Sectioning structure, LaTeX and PDF export ++@subsection Tables in LaTeX export ++@cindex tables, in LaTeX export ++ ++For LaTeX export of a table, you can specify a label and a caption ++(@pxref{Markup rules}). You can also use the @code{ATTR_LaTeX} line to ++request a longtable environment for the table, so that it may span several ++pages: ++ ++@example ++#+CAPTION: A long table ++#+LABEL: tbl:long ++#+ATTR_LaTeX: longtable ++| ..... | ..... | ++| ..... | ..... | ++@end example ++ ++ ++@node Images in LaTeX export, , Tables in LaTeX export, LaTeX and PDF export ++@subsection Images in LaTeX export ++@cindex images, inline in LaTeX ++@cindex inlining images in LaTeX ++ ++Images that are linked to without a description part in the link, like ++@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF ++output files resulting from LaTeX output. Org will use an ++@code{\includegraphics} macro to insert the image. If you have specified a ++caption and/or a label as described in @ref{Markup rules}, the figure will ++be wrapped into a @code{figure} environment and thus become a floating ++element. Finally, you can use an @code{#+ATTR_LaTeX:} line to specify the ++options that can be used in the optional argument of the ++@code{\includegraphics} macro. ++ ++@example ++#+CAPTION: The black-body emission of the disk around HR 4049 ++#+LABEL: fig:SED-HR4049 ++#+ATTR_LaTeX: width=5cm,angle=90 ++[[./img/sed-hr4049.pdf]] ++@end example ++ ++If you need references to a label created in this way, write ++@samp{\ref@{fig:SED-HR4049@}} just like in LaTeX. The default settings will ++recognize files types that can be included as images during processing by ++pdflatex (@file{png}, @file{jpg}, and @file{pdf} files). If you process your ++files in a different way, you may need to customize the variable ++@code{org-export-latex-inline-image-extensions}. ++ ++@node XOXO export, iCalendar export, LaTeX and PDF export, Exporting ++@section XOXO export ++@cindex XOXO export ++ ++Org mode contains an exporter that produces XOXO-style output. ++Currently, this exporter only handles the general outline structure and ++does not interpret any additional Org mode features. ++ ++@table @kbd ++@kindex C-c C-e x ++@item C-c C-e x ++Export as XOXO file @file{myfile.html}. ++@kindex C-c C-e v ++@item C-c C-e v x ++Export only the visible part of the document. ++@end table ++ ++@node iCalendar export, , XOXO export, Exporting ++@section iCalendar export ++@cindex iCalendar export ++ ++Some people like to use Org mode for keeping track of projects, but still ++prefer a standard calendar application for anniversaries and appointments. ++In this case it can be useful to have deadlines and other time-stamped items ++in Org files show up in the calendar application. Org mode can export ++calendar information in the standard iCalendar format. If you also want to ++have TODO entries included in the export, configure the variable ++@code{org-icalendar-include-todo}. iCalendar export will export plain time ++stamps as VEVENT, and TODO items as VTODO. It will also create events from ++deadlines that are in non-TODO items. Deadlines and scheduling dates in TODO ++items will be used to set the start and due dates for the todo ++entry@footnote{See the variables @code{org-icalendar-use-deadline} and ++@code{org-icalendar-use-scheduled}.}. As categories, it will use the tags ++locally defined in the heading, and the file/tree category@footnote{To add ++inherited tags or the TODO state, configure the variable ++@code{org-icalendar-categories}.}. ++ ++The iCalendar standard requires each entry to have a globally unique ++identifier (UID). Org creates these identifiers during export. If you set ++the variable @code{org-icalendar-store-UID}, the UID will be stored in the ++@code{:ID:} property of the entry and re-used next time you report this ++entry. Since a single entry can give rise to multiple iCalendar entries (as ++a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds ++prefixes to the UID, depending on what triggered the inclusion of the entry. ++In this way the UID remains unique, but a synchronization program can still ++figure out from which entry all the different instances originate. ++ ++@table @kbd ++@kindex C-c C-e i ++@item C-c C-e i ++Create iCalendar entries for the current file and store them in the same ++directory, using a file extension @file{.ics}. ++@kindex C-c C-e I ++@item C-c C-e I ++Like @kbd{C-c C-e i}, but do this for all files in ++@code{org-agenda-files}. For each of these files, a separate iCalendar ++file will be written. ++@kindex C-c C-e c ++@item C-c C-e c ++Create a single large iCalendar file from all files in ++@code{org-agenda-files} and write it to the file given by ++@code{org-combined-agenda-icalendar-file}. ++@end table ++ ++The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION ++property can be inherited from higher in the hierarchy if you configure ++@code{org-use-property-inheritance} accordingly.} properties if the selected ++entries have them. If not, the summary will be derived from the headline, ++and the description from the body (limited to ++@code{org-icalendar-include-body} characters). ++ ++How this calendar is best read and updated, that depends on the application ++you are using. The FAQ covers this issue. ++ ++@node Publishing, Miscellaneous, Exporting, Top ++@chapter Publishing ++@cindex publishing ++ ++Org includes@footnote{@file{org-publish.el} is not distributed with ++Emacs 21, if you are still using Emacs 21, you need you need to download ++this file separately.} a publishing management system that allows you to ++configure automatic HTML conversion of @emph{projects} composed of ++interlinked org files. This system is called @emph{org-publish}. You can ++also configure org-publish to automatically upload your exported HTML ++pages and related attachments, such as images and source code files, to ++a web server. Org-publish turns Org into a web-site authoring tool. ++ ++You can also use Org-publish to convert files into La@TeX{}, or even ++combine HTML and La@TeX{} conversion so that files are available in both ++formats on the server@footnote{Since La@TeX{} files on a server are not ++that helpful, you surely want to perform further conversion on them -- ++e.g. convert them to @code{PDF} format.}. ++ ++Org-publish has been contributed to Org by David O'Toole. ++ ++@menu ++* Configuration:: Defining projects ++* Sample configuration:: Example projects ++* Triggering publication:: Publication commands ++@end menu ++ ++@node Configuration, Sample configuration, Publishing, Publishing ++@section Configuration ++ ++Publishing needs significant configuration to specify files, destination ++and many other properties of a project. ++ ++@menu ++* Project alist:: The central configuration variable ++* Sources and destinations:: From here to there ++* Selecting files:: What files are part of the project? ++* Publishing action:: Setting the function doing the publishing ++* Publishing options:: Tweaking HTML export ++* Publishing links:: Which links keep working after publishing? ++* Project page index:: Publishing a list of project files ++@end menu ++ ++@node Project alist, Sources and destinations, Configuration, Configuration ++@subsection The variable @code{org-publish-project-alist} ++@cindex org-publish-project-alist ++@cindex projects, for publishing ++ ++Org-publish is configured almost entirely through setting the value of ++one variable, called @code{org-publish-project-alist}. ++Each element of the list configures one project, and may be in one of ++the two following forms: ++ ++@lisp ++("project-name" :property value :property value ...) ++ ++@r{or} ++ ++("project-name" :components ("project-name" "project-name" ...)) ++ ++@end lisp ++ ++In both cases, projects are configured by specifying property values. ++A project defines the set of files that will be published, as well as ++the publishing configuration to use when publishing those files. When ++a project takes the second form listed above, the individual members ++of the ``components'' property are taken to be components of the ++project, which group together files requiring different publishing ++options. When you publish such a ``meta-project'' all the components ++will also publish. The @code{:components} are published in the sequence ++provided. ++ ++@node Sources and destinations, Selecting files, Project alist, Configuration ++@subsection Sources and destinations for files ++@cindex directories, for publishing ++ ++Most properties are optional, but some should always be set. In ++particular, org-publish needs to know where to look for source files, ++and where to put published files. ++ ++@multitable @columnfractions 0.3 0.7 ++@item @code{:base-directory} ++@tab Directory containing publishing source files ++@item @code{:publishing-directory} ++@tab Directory (possibly remote) where output files will be published. ++@item @code{:preparation-function} ++@tab Function called before starting the publishing process, for example to ++run @code{make} for updating files to be published. ++@item @code{:completion-function} ++@tab Function called after finishing the publishing process, for example to ++change permissions of the resulting files. ++@end multitable ++@noindent ++ ++@node Selecting files, Publishing action, Sources and destinations, Configuration ++@subsection Selecting files ++@cindex files, selecting for publishing ++ ++By default, all files with extension @file{.org} in the base directory ++are considered part of the project. This can be modified by setting the ++properties ++@multitable @columnfractions 0.25 0.75 ++@item @code{:base-extension} ++@tab Extension (without the dot!) of source files. This actually is a ++regular expression. ++ ++@item @code{:exclude} ++@tab Regular expression to match file names that should not be ++published, even though they have been selected on the basis of their ++extension. ++ ++@item @code{:include} ++@tab List of files to be included regardless of @code{:base-extension} ++and @code{:exclude}. ++@end multitable ++ ++@node Publishing action, Publishing options, Selecting files, Configuration ++@subsection Publishing action ++@cindex action, for publishing ++ ++Publishing means that a file is copied to the destination directory and ++possibly transformed in the process. The default transformation is to export ++Org files as HTML files, and this is done by the function ++@code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTML ++export}). But you also can publish your files in La@TeX{} by using the ++function @code{org-publish-org-to-latex} instead, or as PDF files using ++@code{org-publish-org-to-pdf}. Other files like images only need to be ++copied to the publishing destination. For non-Org files, you need to provide ++your own publishing function: ++ ++@multitable @columnfractions 0.3 0.7 ++@item @code{:publishing-function} ++@tab Function executing the publication of a file. This may also be a ++list of functions, which will all be called in turn. ++@end multitable ++ ++The function must accept two arguments: a property list containing at ++least a @code{:publishing-directory} property, and the name of the file ++to be published. It should take the specified file, make the necessary ++transformation (if any) and place the result into the destination folder. ++You can write your own publishing function, but @code{org-publish} ++provides one for attachments (files that only need to be copied): ++@code{org-publish-attachment}. ++ ++@node Publishing options, Publishing links, Publishing action, Configuration ++@subsection Options for the HTML/LaTeX exporters ++@cindex options, for publishing ++ ++The property list can be used to set many export options for the HTML ++and La@TeX{} exporters. In most cases, these properties correspond to user ++variables in Org. The table below lists these properties along ++with the variable they belong to. See the documentation string for the ++respective variable for details. ++ ++@multitable @columnfractions 0.32 0.68 ++@item @code{:link-up} @tab @code{org-export-html-link-up} ++@item @code{:link-home} @tab @code{org-export-html-link-home} ++@item @code{:language} @tab @code{org-export-default-language} ++@item @code{:customtime} @tab @code{org-display-custom-times} ++@item @code{:headline-levels} @tab @code{org-export-headline-levels} ++@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} ++@item @code{:section-number-format} @tab @code{org-export-section-number-format} ++@item @code{:table-of-contents} @tab @code{org-export-with-toc} ++@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks} ++@item @code{:archived-trees} @tab @code{org-export-with-archived-trees} ++@item @code{:emphasize} @tab @code{org-export-with-emphasize} ++@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} ++@item @code{:special-strings} @tab @code{org-export-with-special-strings} ++@item @code{:footnotes} @tab @code{org-export-with-footnotes} ++@item @code{:drawers} @tab @code{org-export-with-drawers} ++@item @code{:tags} @tab @code{org-export-with-tags} ++@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords} ++@item @code{:priority} @tab @code{org-export-with-priority} ++@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} ++@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} ++@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading} ++@item @code{:fixed-width} @tab @code{org-export-with-fixed-width} ++@item @code{:timestamps} @tab @code{org-export-with-timestamps} ++@item @code{:author-info} @tab @code{org-export-author-info} ++@item @code{:creator-info} @tab @code{org-export-creator-info} ++@item @code{:tables} @tab @code{org-export-with-tables} ++@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line} ++@item @code{:style-include-default} @tab @code{org-export-html-style-include-default} ++@item @code{:style} @tab @code{org-export-html-style} ++@item @code{:style-extra} @tab @code{org-export-html-style-extra} ++@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html} ++@item @code{:inline-images} @tab @code{org-export-html-inline-images} ++@item @code{:html-extension} @tab @code{org-export-html-extension} ++@item @code{:html-table-tag} @tab @code{org-export-html-table-tag} ++@item @code{:expand-quoted-html} @tab @code{org-export-html-expand} ++@item @code{:timestamp} @tab @code{org-export-html-with-timestamp} ++@item @code{:publishing-directory} @tab @code{org-export-publishing-directory} ++@item @code{:preamble} @tab @code{org-export-html-preamble} ++@item @code{:postamble} @tab @code{org-export-html-postamble} ++@item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble} ++@item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble} ++@item @code{:author} @tab @code{user-full-name} ++@item @code{:email} @tab @code{user-mail-address} ++@item @code{:select-tags} @tab @code{org-export-select-tags} ++@item @code{:exclude-tags} @tab @code{org-export-exclude-tags} ++@end multitable ++ ++If you use several email addresses, separate them by a semi-column. ++ ++Most of the @code{org-export-with-*} variables have the same effect in ++both HTML and La@TeX{} exporters, except for @code{:TeX-macros} and ++@code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the ++La@TeX{} export. ++ ++When a property is given a value in @code{org-publish-project-alist}, ++its setting overrides the value of the corresponding user variable (if ++any) during publishing. Options set within a file (@pxref{Export ++options}), however, override everything. ++ ++@node Publishing links, Project page index, Publishing options, Configuration ++@subsection Links between published files ++@cindex links, publishing ++ ++To create a link from one Org file to another, you would use ++something like @samp{[[file:foo.org][The foo]]} or simply ++@samp{file:foo.org.} (@pxref{Hyperlinks}). Upon publishing this link ++becomes a link to @file{foo.html}. In this way, you can interlink the ++pages of your "org web" project and the links will work as expected when ++you publish them to HTML. ++ ++You may also link to related files, such as images. Provided you are ++careful with relative pathnames, and provided you have also configured ++@code{org-publish} to upload the related files, these links will work ++too. See @ref{Complex example} for an example of this usage. ++ ++Sometime an Org file to be published may contain links that are ++only valid in your production environment, but not in the publishing ++location. In this case, use the property ++ ++@multitable @columnfractions 0.4 0.6 ++@item @code{:link-validation-function} ++@tab Function to validate links ++@end multitable ++ ++@noindent ++to define a function for checking link validity. This function must ++accept two arguments, the file name and a directory relative to which ++the file name is interpreted in the production environment. If this ++function returns @code{nil}, then the HTML generator will only insert a ++description into the HTML file, but no link. One option for this ++function is @code{org-publish-validate-link} which checks if the given ++file is part of any project in @code{org-publish-project-alist}. ++ ++@node Project page index, , Publishing links, Configuration ++@subsection Project page index ++@cindex index, of published pages ++ ++The following properties may be used to control publishing of an ++index of files or summary page for a given project. ++ ++@multitable @columnfractions 0.25 0.75 ++@item @code{:auto-index} ++@tab When non-nil, publish an index during org-publish-current-project or ++org-publish-all. ++ ++@item @code{:index-filename} ++@tab Filename for output of index. Defaults to @file{index.org} (which ++becomes @file{index.html}). ++ ++@item @code{:index-title} ++@tab Title of index page. Defaults to name of file. ++ ++@item @code{:index-function} ++@tab Plug-in function to use for generation of index. ++Defaults to @code{org-publish-org-index}, which generates a plain list ++of links to all files in the project. ++@end multitable ++ ++@node Sample configuration, Triggering publication, Configuration, Publishing ++@section Sample configuration ++ ++Below we provide two example configurations. The first one is a simple ++project publishing only a set of Org files. The second example is ++more complex, with a multi-component project. ++ ++@menu ++* Simple example:: One-component publishing ++* Complex example:: A multi-component publishing example ++@end menu ++ ++@node Simple example, Complex example, Sample configuration, Sample configuration ++@subsection Example: simple publishing configuration ++ ++This example publishes a set of Org files to the @file{public_html} ++directory on the local machine. ++ ++@lisp ++(setq org-publish-project-alist ++ '(("org" ++ :base-directory "~/org/" ++ :publishing-directory "~/public_html" ++ :section-numbers nil ++ :table-of-contents nil ++ :style ""))) ++@end lisp ++ ++@node Complex example, , Simple example, Sample configuration ++@subsection Example: complex publishing configuration ++ ++This more complicated example publishes an entire website, including ++org files converted to HTML, image files, emacs lisp source code, and ++style sheets. The publishing-directory is remote and private files are ++excluded. ++ ++To ensure that links are preserved, care should be taken to replicate ++your directory structure on the web server, and to use relative file ++paths. For example, if your org files are kept in @file{~/org} and your ++publishable images in @file{~/images}, you'd link to an image with ++@c ++@example ++file:../images/myimage.png ++@end example ++@c ++On the web server, the relative path to the image should be the ++same. You can accomplish this by setting up an "images" folder in the ++right place on the web server, and publishing images to it. ++ ++@lisp ++(setq org-publish-project-alist ++ '(("orgfiles" ++ :base-directory "~/org/" ++ :base-extension "org" ++ :publishing-directory "/ssh:user@@host:~/html/notebook/" ++ :publishing-function org-publish-org-to-html ++ :exclude "PrivatePage.org" ;; regexp ++ :headline-levels 3 ++ :section-numbers nil ++ :table-of-contents nil ++ :style "" ++ :auto-preamble t ++ :auto-postamble nil) ++ ++ ("images" ++ :base-directory "~/images/" ++ :base-extension "jpg\\|gif\\|png" ++ :publishing-directory "/ssh:user@@host:~/html/images/" ++ :publishing-function org-publish-attachment) ++ ++ ("other" ++ :base-directory "~/other/" ++ :base-extension "css\\|el" ++ :publishing-directory "/ssh:user@@host:~/html/other/" ++ :publishing-function org-publish-attachment) ++ ("website" :components ("orgfiles" "images" "other")))) ++@end lisp ++ ++@node Triggering publication, , Sample configuration, Publishing ++@section Triggering publication ++ ++Once org-publish is properly configured, you can publish with the ++following functions: ++ ++@table @kbd ++@item C-c C-e C ++Prompt for a specific project and publish all files that belong to it. ++@item C-c C-e P ++Publish the project containing the current file. ++@item C-c C-e F ++Publish only the current file. ++@item C-c C-e A ++Publish all projects. ++@end table ++ ++Org uses timestamps to track when a file has changed. The above ++functions normally only publish changed files. You can override this and ++force publishing of all files by giving a prefix argument. ++ ++@node Miscellaneous, Extensions, Publishing, Top ++@chapter Miscellaneous ++ ++@menu ++* Completion:: M-TAB knows what you need ++* Customization:: Adapting Org to your taste ++* In-buffer settings:: Overview of the #+KEYWORDS ++* The very busy C-c C-c key:: When in doubt, press C-c C-c ++* Clean view:: Getting rid of leading stars in the outline ++* TTY keys:: Using Org on a tty ++* Interaction:: Other Emacs packages ++* Bugs:: Things which do not work perfectly ++@end menu ++ ++@node Completion, Customization, Miscellaneous, Miscellaneous ++@section Completion ++@cindex completion, of @TeX{} symbols ++@cindex completion, of TODO keywords ++@cindex completion, of dictionary words ++@cindex completion, of option keywords ++@cindex completion, of tags ++@cindex completion, of property keys ++@cindex completion, of link abbreviations ++@cindex @TeX{} symbol completion ++@cindex TODO keywords completion ++@cindex dictionary word completion ++@cindex option keyword completion ++@cindex tag completion ++@cindex link abbreviations, completion of ++ ++Org supports in-buffer completion. This type of completion does ++not make use of the minibuffer. You simply type a few letters into ++the buffer and use the key to complete text right there. ++ ++@table @kbd ++@kindex M-@key{TAB} ++@item M-@key{TAB} ++Complete word at point ++@itemize @bullet ++@item ++At the beginning of a headline, complete TODO keywords. ++@item ++After @samp{\}, complete @TeX{} symbols supported by the exporter. ++@item ++After @samp{*}, complete headlines in the current buffer so that they ++can be used in search links like @samp{[[*find this headline]]}. ++@item ++After @samp{:} in a headline, complete tags. The list of tags is taken ++from the variable @code{org-tag-alist} (possibly set through the ++@samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created ++dynamically from all tags used in the current buffer. ++@item ++After @samp{:} and not in a headline, complete property keys. The list ++of keys is constructed dynamically from all keys used in the current ++buffer. ++@item ++After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}). ++@item ++After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or ++@samp{OPTIONS} which set file-specific options for Org mode. When the ++option keyword is already complete, pressing @kbd{M-@key{TAB}} again ++will insert example settings for this keyword. ++@item ++In the line after @samp{#+STARTUP: }, complete startup keywords, ++i.e. valid keys for this line. ++@item ++Elsewhere, complete dictionary words using Ispell. ++@end itemize ++@end table ++ ++@node Customization, In-buffer settings, Completion, Miscellaneous ++@section Customization ++@cindex customization ++@cindex options, for customization ++@cindex variables, for customization ++ ++There are more than 180 variables that can be used to customize ++Org. For the sake of compactness of the manual, I am not ++describing the variables here. A structured overview of customization ++variables is available with @kbd{M-x org-customize}. Or select ++@code{Browse Org Group} from the @code{Org->Customization} menu. Many ++settings can also be activated on a per-file basis, by putting special ++lines into the buffer (@pxref{In-buffer settings}). ++ ++@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous ++@section Summary of in-buffer settings ++@cindex in-buffer settings ++@cindex special keywords ++ ++Org mode uses special lines in the buffer to define settings on a ++per-file basis. These lines start with a @samp{#+} followed by a ++keyword, a colon, and then individual words defining a setting. Several ++setting words can be in the same line, but you can also have multiple ++lines for the keyword. While these settings are described throughout ++the manual, here is a summary. After changing any of those lines in the ++buffer, press @kbd{C-c C-c} with the cursor still in the line to ++activate the changes immediately. Otherwise they become effective only ++when the file is visited again in a new Emacs session. ++ ++@table @kbd ++@item #+ARCHIVE: %s_done:: ++This line sets the archive location for the agenda file. It applies for ++all subsequent lines until the next @samp{#+ARCHIVE} line, or the end ++of the file. The first such line also applies to any entries before it. ++The corresponding variable is @code{org-archive-location}. ++@item #+CATEGORY: ++This line sets the category for the agenda file. The category applies ++for all subsequent lines until the next @samp{#+CATEGORY} line, or the ++end of the file. The first such line also applies to any entries before it. ++@item #+COLUMNS: %25ITEM ..... ++Set the default format for columns view. This format applies when ++columns view is invoked in location where no @code{COLUMNS} property ++applies. ++@item #+CONSTANTS: name1=value1 ... ++Set file-local values for constants to be used in table formulas. This ++line set the local variable @code{org-table-formula-constants-local}. ++The global version of this variable is ++@code{org-table-formula-constants}. ++@item #+FILETAGS: :tag1:tag2:tag3: ++Set tags that can be inherited by any entry in the file, including the ++top-level entries. ++@item #+DRAWERS: NAME1 ..... ++Set the file-local set of drawers. The corresponding global variable is ++@code{org-drawers}. ++@item #+LINK: linkword replace ++These lines (several are allowed) specify link abbreviations. ++@xref{Link abbreviations}. The corresponding variable is ++@code{org-link-abbrev-alist}. ++@item #+PRIORITIES: highest lowest default ++This line sets the limits and the default for the priorities. All three ++must be either letters A-Z or numbers 0-9. The highest priority must ++have a lower ASCII number that the lowest priority. ++@item #+PROPERTY: Property_Name Value ++This line sets a default inheritance value for entries in the current ++buffer, most useful for specifying the allowed values of a property. ++@item #+SETUPFILE: file ++This line defines a file that holds more in-buffer setup. Normally this is ++entirely ignored. Only when the buffer is parsed for option-setting lines ++(i.e. when starting Org mode for a file, when pressing @kbd{C-c C-c} in a ++settings line, or when exporting), then the contents of this file are parsed ++as if they had been included in the buffer. In particular, the file can be ++any other Org mode file with internal setup. You can visit the file the ++cursor is in the line with @kbd{C-c '}. ++@item #+STARTUP: ++This line sets options to be used at startup of Org mode, when an ++Org file is being visited. The first set of options deals with the ++initial visibility of the outline tree. The corresponding variable for ++global default settings is @code{org-startup-folded}, with a default ++value @code{t}, which means @code{overview}. ++@cindex @code{overview}, STARTUP keyword ++@cindex @code{content}, STARTUP keyword ++@cindex @code{showall}, STARTUP keyword ++@example ++overview @r{top-level headlines only} ++content @r{all headlines} ++showall @r{no folding at all, show everything} ++@end example ++Then there are options for aligning tables upon visiting a file. This ++is useful in files containing narrowed table columns. The corresponding ++variable is @code{org-startup-align-all-tables}, with a default value ++@code{nil}. ++@cindex @code{align}, STARTUP keyword ++@cindex @code{noalign}, STARTUP keyword ++@example ++align @r{align all tables} ++noalign @r{don't align tables on startup} ++@end example ++Logging closing and reinstating TODO items, and clock intervals ++(variables @code{org-log-done}, @code{org-log-note-clock-out}, and ++@code{org-log-repeat}) can be configured using these options. ++@cindex @code{logdone}, STARTUP keyword ++@cindex @code{lognotedone}, STARTUP keyword ++@cindex @code{nologdone}, STARTUP keyword ++@cindex @code{lognoteclock-out}, STARTUP keyword ++@cindex @code{nolognoteclock-out}, STARTUP keyword ++@cindex @code{logrepeat}, STARTUP keyword ++@cindex @code{lognoterepeat}, STARTUP keyword ++@cindex @code{nologrepeat}, STARTUP keyword ++@example ++logdone @r{record a timestamp when an item is marked DONE} ++lognotedone @r{record timestamp and a note when DONE} ++nologdone @r{don't record when items are marked DONE} ++logrepeat @r{record a time when reinstating a repeating item} ++lognoterepeat @r{record a note when reinstating a repeating item} ++nologrepeat @r{do not record when reinstating repeating item} ++lognoteclock-out @r{record a note when clocking out} ++nolognoteclock-out @r{don't record a note when clocking out} ++@end example ++Here are the options for hiding leading stars in outline headings, and for ++indenting outlines. The corresponding variables are ++@code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a ++default setting @code{nil} (meaning @code{showstars} and @code{oddeven}). ++@cindex @code{hidestars}, STARTUP keyword ++@cindex @code{showstars}, STARTUP keyword ++@cindex @code{odd}, STARTUP keyword ++@cindex @code{even}, STARTUP keyword ++@example ++hidestars @r{make all but one of the stars starting a headline invisible.} ++showstars @r{show all stars starting a headline} ++indent @r{virtual indentation according to outline level} ++noindent @r{no virtual indentation according to outline level} ++odd @r{allow only odd outline levels (1,3,...)} ++oddeven @r{allow all outline levels} ++@end example ++To turn on custom format overlays over time stamps (variables ++@code{org-put-time-stamp-overlays} and ++@code{org-time-stamp-overlay-formats}), use ++@cindex @code{customtime}, STARTUP keyword ++@example ++customtime @r{overlay custom time format} ++@end example ++The following options influence the table spreadsheet (variable ++@code{constants-unit-system}). ++@cindex @code{constcgs}, STARTUP keyword ++@cindex @code{constSI}, STARTUP keyword ++@example ++constcgs @r{@file{constants.el} should use the c-g-s unit system} ++constSI @r{@file{constants.el} should use the SI unit system} ++@end example ++To influence footnote settings, use the following keywords. The ++corresponding variables are @code{org-footnote-define-inline} and ++@code{org-footnote-auto-label}. ++@cindex @code{fninline}, STARTUP keyword ++@cindex @code{fnnoinline}, STARTUP keyword ++@cindex @code{fnlocal}, STARTUP keyword ++@cindex @code{fnprompt}, STARTUP keyword ++@cindex @code{fnauto}, STARTUP keyword ++@cindex @code{fnconfirm}, STARTUP keyword ++@cindex @code{fnplain}, STARTUP keyword ++@example ++fninline @r{define footnotes inline} ++fnnoinline @r{define footnotes in separate section} ++fnlocal @r{define footnotes near first reference, but not inline} ++fnprompt @r{prompt for footnote labels} ++fnauto @r{create [fn:1]-like labels automatically (default)} ++fnconfirm @r{offer automatic label for editing or confirmation} ++fnplain @r{create [1]-like labels automatically} ++@end example ++@item #+TAGS: TAG1(c1) TAG2(c2) ++These lines (several such lines are allowed) specify the valid tags in ++this file, and (potentially) the corresponding @emph{fast tag selection} ++keys. The corresponding variable is @code{org-tag-alist}. ++@item #+TBLFM: ++This line contains the formulas for the table directly above the line. ++@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS, #+DATE: ++These lines provide settings for exporting files. For more details see ++@ref{Export options}. ++@item #+SEQ_TODO: #+TYP_TODO: ++These lines set the TODO keywords and their interpretation in the ++current file. The corresponding variables are @code{org-todo-keywords} ++and @code{org-todo-interpretation}. ++@end table ++ ++@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous ++@section The very busy C-c C-c key ++@kindex C-c C-c ++@cindex C-c C-c, overview ++ ++The key @kbd{C-c C-c} has many purposes in Org, which are all ++mentioned scattered throughout this manual. One specific function of ++this key is to add @emph{tags} to a headline (@pxref{Tags}). In many ++other circumstances it means something like @emph{Hey Org, look ++here and update according to what you see here}. Here is a summary of ++what this means in different contexts. ++ ++@itemize @minus ++@item ++If there are highlights in the buffer from the creation of a sparse ++tree, or from clock display, remove these highlights. ++@item ++If the cursor is in one of the special @code{#+KEYWORD} lines, this ++triggers scanning the buffer for these lines and updating the ++information. ++@item ++If the cursor is inside a table, realign the table. This command ++works even if the automatic table editor has been turned off. ++@item ++If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to ++the entire table. ++@item ++If the cursor is inside a table created by the @file{table.el} package, ++activate that table. ++@item ++If the current buffer is a remember buffer, close the note and file it. ++With a prefix argument, file it, without further interaction, to the ++default location. ++@item ++If the cursor is on a @code{<<>>}, update radio targets and ++corresponding links in this buffer. ++@item ++If the cursor is in a property line or at the start or end of a property ++drawer, offer property commands. ++@item ++If the cursor is at a footnote reference, go to the corresponding ++definition, and vice versa. ++@item ++If the cursor is in a plain list item with a checkbox, toggle the status ++of the checkbox. ++@item ++If the cursor is on a numbered item in a plain list, renumber the ++ordered list. ++@item ++If the cursor is on the @code{#+BEGIN} line of a dynamical block, the ++block is updated. ++@end itemize ++ ++@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous ++@section A cleaner outline view ++@cindex hiding leading stars ++@cindex dynamic indentation ++@cindex odd-levels-only outlines ++@cindex clean outline view ++ ++Some people find it noisy and distracting that the Org headlines are starting ++with a potentially large number of stars, and that text below the headlines ++is not indented. This is not really a problem when you are writing a book ++where the outline headings are really section headlines. However, in a more ++list-oriented outline, it is clear that an indented structure is a lot ++cleaner, as can be seen by comparing the two columns in the following ++example: ++ ++@example ++@group ++* Top level headline | * Top level headline ++** Second level | * Second level ++*** 3rd level | * 3rd level ++some text | some text ++*** 3rd level | * 3rd level ++more text | more text ++* Another top level headline | * Another top level headline ++@end group ++@end example ++ ++@noindent ++It is non-trivial to make such a look work in Emacs, but Org contains three ++separate features that, combined, achieve just that. ++ ++@enumerate ++@item ++@emph{Indentation of text below headlines}@* ++You may indent text below each headline to make the left boundary line up ++with the headline, like ++ ++@example ++*** 3rd level ++ more text, now indented ++@end example ++ ++A good way to get this indentation is by hand, and Org supports this with ++paragraph filling, line wrapping, and structure editing@footnote{See also the ++variable @code{org-adapt-indentation}.} preserving or adapting the ++indentation appropriate. A different approach would be to have a way to ++automatically indent lines according to outline structure by adding overlays ++or text properties. But I have not yet found a robust and efficient way to ++do this in large files. ++ ++@item ++@emph{Hiding leading stars}@* You can modify the display in such a way that ++all leading stars become invisible. To do this in a global way, configure ++the variable @code{org-hide-leading-stars} or change this on a per-file basis ++with ++ ++@example ++#+STARTUP: hidestars ++@end example ++ ++@noindent ++Note that the opposite behavior is selected with @code{showstars}. ++ ++With hidden stars, the tree becomes: ++ ++@example ++@group ++* Top level headline ++ * Second level ++ * 3rd level ++ ... ++@end group ++@end example ++ ++@noindent ++Note that the leading stars are not truly replaced by whitespace, they ++are only fontified with the face @code{org-hide} that uses the ++background color as font color. If you are not using either white or ++black background, you may have to customize this face to get the wanted ++effect. Another possibility is to set this font such that the extra ++stars are @i{almost} invisible, for example using the color ++@code{grey90} on a white background. ++ ++@item ++Things become cleaner still if you skip all the even levels and use only odd ++levels 1, 3, 5..., effectively adding two stars to go from one outline level ++to the next. In this way we get the outline view shown at the beginning of ++this section. In order to make the structure editing and export commands ++handle this convention correctly, configure the variable ++@code{org-odd-levels-only}, or set this on a per-file basis with one of the ++following lines: ++ ++@example ++#+STARTUP: odd ++#+STARTUP: oddeven ++@end example ++ ++You can convert an Org file from single-star-per-level to the ++double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels ++RET} in that file. The reverse operation is @kbd{M-x ++org-convert-to-oddeven-levels}. ++@end enumerate ++ ++@node TTY keys, Interaction, Clean view, Miscellaneous ++@section Using Org on a tty ++@cindex tty key bindings ++ ++Because Org contains a large number of commands, by default much of ++Org's core commands are bound to keys that are generally not ++accessible on a tty, such as the cursor keys (@key{left}, @key{right}, ++@key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used ++together with modifiers like @key{Meta} and/or @key{Shift}. To access ++these commands on a tty when special keys are unavailable, the following ++alternative bindings can be used. The tty bindings below will likely be ++more cumbersome; you may find for some of the bindings below that a ++customized work-around suits you better. For example, changing a time ++stamp is really only fun with @kbd{S-@key{cursor}} keys, whereas on a ++tty you would rather use @kbd{C-c .} to re-insert the timestamp. ++ ++@multitable @columnfractions 0.15 0.2 0.2 ++@item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2} ++@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab ++@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}} ++@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab ++@item @kbd{M-@key{right}} @tab @kbd{C-c C-x i} @tab @kbd{@key{Esc} @key{right}} ++@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab ++@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{@key{Esc} @key{up}} ++@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab ++@item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{@key{Esc} @key{down}} ++@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab ++@item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab ++@item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{@key{Esc} @key{RET}} ++@item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab ++@item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab ++@item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab ++@item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab ++@item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab ++@item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab ++@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab ++@end multitable ++ ++@node Interaction, Bugs, TTY keys, Miscellaneous ++@section Interaction with other packages ++@cindex packages, interaction with other ++Org lives in the world of GNU Emacs and interacts in various ways ++with other code out there. ++ ++@menu ++* Cooperation:: Packages Org cooperates with ++* Conflicts:: Packages that lead to conflicts ++@end menu ++ ++@node Cooperation, Conflicts, Interaction, Interaction ++@subsection Packages that Org cooperates with ++ ++@table @asis ++@cindex @file{calc.el} ++@item @file{calc.el} by Dave Gillespie ++Org uses the Calc package for implementing spreadsheet ++functionality in its tables (@pxref{The spreadsheet}). Org ++checks for the availability of Calc by looking for the function ++@code{calc-eval} which should be autoloaded in your setup if Calc has ++been installed properly. As of Emacs 22, Calc is part of the Emacs ++distribution. Another possibility for interaction between the two ++packages is using Calc for embedded calculations. @xref{Embedded Mode, ++, Embedded Mode, Calc, GNU Emacs Calc Manual}. ++@cindex @file{constants.el} ++@item @file{constants.el} by Carsten Dominik ++In a table formula (@pxref{The spreadsheet}), it is possible to use ++names for natural constants or units. Instead of defining your own ++constants in the variable @code{org-table-formula-constants}, install ++the @file{constants} package which defines a large number of constants ++and units, and lets you use unit prefixes like @samp{M} for ++@samp{Mega} etc. You will need version 2.0 of this package, available ++at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for ++the function @code{constants-get}, which has to be autoloaded in your ++setup. See the installation instructions in the file ++@file{constants.el}. ++@item @file{cdlatex.el} by Carsten Dominik ++@cindex @file{cdlatex.el} ++Org mode can make use of the CDLaTeX package to efficiently enter ++La@TeX{} fragments into Org files. See @ref{CDLaTeX mode}. ++@item @file{imenu.el} by Ake Stenhoff and Lars Lindberg ++@cindex @file{imenu.el} ++Imenu allows menu access to an index of items in a file. Org mode ++supports Imenu - all you need to do to get the index is the following: ++@lisp ++(add-hook 'org-mode-hook ++ (lambda () (imenu-add-to-menubar "Imenu"))) ++@end lisp ++By default the index is two levels deep - you can modify the depth using ++the option @code{org-imenu-depth}. ++@item @file{remember.el} by John Wiegley ++@cindex @file{remember.el} ++Org cooperates with remember, see @ref{Remember}. ++@file{Remember.el} is not part of Emacs, find it on the web. ++@item @file{speedbar.el} by Eric M. Ludlam ++@cindex @file{speedbar.el} ++Speedbar is a package that creates a special frame displaying files and ++index items in files. Org mode supports Speedbar and allows you to ++drill into Org files directly from the Speedbar. It also allows to ++restrict the scope of agenda commands to a file or a subtree by using ++the command @kbd{<} in the Speedbar frame. ++@cindex @file{table.el} ++@item @file{table.el} by Takaaki Ota ++@kindex C-c C-c ++@cindex table editor, @file{table.el} ++@cindex @file{table.el} ++ ++Complex ASCII tables with automatic line wrapping, column- and ++row-spanning, and alignment can be created using the Emacs table ++package by Takaaki Ota (@uref{http://sourceforge.net/projects/table}, ++and also part of Emacs 22). ++When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org mode ++will call @command{table-recognize-table} and move the cursor into the ++table. Inside a table, the keymap of Org mode is inactive. In order ++to execute Org mode-related commands, leave the table. ++ ++@table @kbd ++@kindex C-c C-c ++@item C-c C-c ++Recognize @file{table.el} table. Works when the cursor is in a ++table.el table. ++@c ++@kindex C-c ~ ++@item C-c ~ ++Insert a table.el table. If there is already a table at point, this ++command converts it between the table.el format and the Org mode ++format. See the documentation string of the command ++@code{org-convert-table} for the restrictions under which this is ++possible. ++@end table ++@file{table.el} is part of Emacs 22. ++@cindex @file{footnote.el} ++@item @file{footnote.el} by Steven L. Baur ++Org mode recognizes numerical footnotes as provided by this package. ++However, Org-mode also has its own footnote support (@pxref{Footnotes}), ++which makes using @file{footnote.el} unnecessary. ++@end table ++ ++@node Conflicts, , Cooperation, Interaction ++@subsection Packages that lead to conflicts with Org mode ++ ++@table @asis ++ ++@cindex @code{shift-selection-mode} ++In Emacs 23, @code{shift-selection-mode} is on by default, meaning that ++cursor motions combined with the shift key should start or enlarge regions. ++This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change ++timestamps, TODO keywords, priorities, and item bullet types if the cursor is ++at such a location. By default, @kbd{S-@key{cursor}} commands outside ++special contexts don't do anything, but you can customize the variable ++@code{org-support-shift-select}. Org-mode then tries to accommodate shift ++selection by (i) using it outside of the special contexts where special ++commands apply, and by (ii) extending an existing active region even if the ++cursor moves across a special context. ++ ++@cindex @file{CUA.el} ++@item @file{CUA.el} by Kim. F. Storm ++Key bindings in Org conflict with the @kbd{S-} keys used by CUA mode ++(as well as pc-select-mode and s-region-mode) to select and extend the ++region. In fact, Emacs 23 has this built-in in the form of ++@code{shift-selection-mode}, see previous paragraph. If you are using Emacs ++23 you probably don't want to use another package for this purpose. However, ++if you prefer to leave these keys to a different package while working in ++Org-mode, configure the variable @code{org-replace-disputed-keys}. When set, ++Org will move the following key bindings in Org files, and in the agenda ++buffer (but not during date selection). ++ ++@example ++S-UP -> M-p S-DOWN -> M-n ++S-LEFT -> M-- S-RIGHT -> M-+ ++C-S-LEFT -> M-S-- C-S-RIGHT -> M-S-+ ++@end example ++ ++Yes, these are unfortunately more difficult to remember. If you want ++to have other replacement keys, look at the variable ++@code{org-disputed-keys}. ++ ++@item @file{windmove.el} by Hovav Shacham ++@cindex @file{windmove.el} ++Also this package uses the @kbd{S-} keys, so everything written ++in the paragraph above about CUA mode also applies here. ++ ++@end table ++ ++ ++@node Bugs, , Interaction, Miscellaneous ++@section Bugs ++@cindex bugs ++ ++Here is a list of things that should work differently, but which I ++have found too hard to fix. ++ ++@itemize @bullet ++@item ++If a table field starts with a link, and if the corresponding table ++column is narrowed (@pxref{Narrow columns}) to a width too small to ++display the link, the field would look entirely empty even though it is ++not. To prevent this, Org throws an error. The work-around is to ++make the column wide enough to fit the link, or to add some text (at ++least 2 characters) before the link in the same field. ++@item ++Narrowing table columns does not work on XEmacs, because the ++@code{format} function does not transport text properties. ++@item ++Text in an entry protected with the @samp{QUOTE} keyword should not ++autowrap. ++@item ++When the application called by @kbd{C-c C-o} to open a file link fails ++(for example because the application does not exist or refuses to open ++the file), it does so silently. No error message is displayed. ++@item ++Recalculating a table line applies the formulas from left to right. ++If a formula uses @emph{calculated} fields further down the row, ++multiple recalculation may be needed to get all fields consistent. You ++may use the command @code{org-table-iterate} (@kbd{C-u C-c *}) to ++recalculate until convergence. ++@item ++The exporters work well, but could be made more efficient. ++@end itemize ++ ++ ++@node Extensions, Hacking, Miscellaneous, Top ++@appendix Extensions ++ ++This appendix lists the extension modules that have been written for Org. ++Many of these extensions live in the @file{contrib} directory of the Org ++distribution, others are available somewhere on the web. ++ ++@menu ++* Extensions in the contrib directory:: These come with the Org distro ++* Other extensions:: These you have to find on the web. ++@end menu ++ ++@node Extensions in the contrib directory, Other extensions, Extensions, Extensions ++@section Extensions in the @file{contrib} directory ++ ++A number of extension are distributed with Org when you download it from its ++homepage. Please note that these extensions are @emph{not} distributed as ++part of Emacs, so if you use Org as delivered with Emacs, you still need to ++go to @url{http://orgmode.org} to get access to these modules. ++ ++@table @asis ++@item @file{org-annotate-file.el} by @i{Philip Jackson} ++Annotate a file with org syntax, in a separate file, with links back to the ++annotated file. ++ ++@item @file{org-annotation-helper.el} by @i{Bastien Guerry and Daniel E. German} ++Call @i{remember} directly from Firefox/Opera, or from Adobe Reader. When ++activating a special link or bookmark, Emacs receives a trigger to create a ++note with a link back to the website. Requires some setup, a detailed ++description is in @file{contrib/packages/org-annotation-helper}. ++ ++@item @file{org-bookmark.el} by @i{Tokuya Kameshima} ++Support for links to Emacs bookmarks. ++ ++@item @file{org-depend.el} by @i{Carsten Dominik} ++TODO dependencies for Org-mode. Make TODO state changes in one entry trigger ++changes in another, or be blocked by the state of another entry. Also, ++easily create chains of TODO items with exactly one active item at any time. ++ ++@item @file{org-elisp-symbol.el} by @i{Bastien Guerry} ++Org links to emacs-lisp symbols. This can create annotated links that ++exactly point to the definition location of a variable of function. ++ ++@item @file{org-eval.el} by @i{Carsten Dominik} ++The @code{} tag, adapted from Emacs Wiki and Emacs Muse, allows text to ++be included in a document that is the result of evaluating some code. Other ++scripting languages like @code{perl} can be supported with this package as ++well. ++ ++@item @file{org-eval-light.el} by @i{Eric Schulte} ++User-controlled evaluation of code in an Org buffer. ++ ++@item @file{org-exp-blocks.el} by @i{Eric Schulte} ++Preprocess user-defined blocks for export. ++ ++@item @file{org-expiry.el} by @i{Bastien Guerry} ++Expiry mechanism for Org entries. ++ ++@item @file{org-indent.el} by @i{Carsten Dominik} ++Dynamic indentation of Org outlines. The plan is to indent an outline ++according to level, but so far this is too hard for a proper and stable ++implementation. Still, it works somewhat. ++ ++@item @file{org-interactive-query.el} by @i{Christopher League} ++Interactive modification of tags queries. After running a general query in ++Org, this package allows you to narrow down the results by adding more tags ++or keywords. ++ ++@item @file{org-mairix.el} by @i{Georg C. F. Greve} ++Hook mairix search into Org for different MUAs. ++ ++@item @file{org-man.el} by @i{Carsten Dominik} ++Support for links to manpages in Org-mode. ++ ++@item @file{org-mtags.el} by @i{Carsten Dominik} ++Support for some Muse-like tags in Org-mode. This package allows you to ++write @code{} and @code{} and other syntax copied from Emacs ++Muse, right inside an Org file. The goal here is to make it easy to publish ++the same file using either org-publish or Muse. ++ ++@item @file{org-panel.el} by @i{Lennart Borgman} ++Simplified and display-aided access to some Org commands. ++ ++@item @file{org-registry.el} by @i{Bastien Guerry} ++A registry for Org links, to find out from where links point to a given file ++or location. ++ ++@item @file{org2rem.el} by @i{Bastien Guerry} ++Convert org appointments into reminders for the @file{remind} program. ++ ++@item @file{org-screen.el} by @i{Andrew Hyatt} ++Visit screen sessions through Org-mode links. ++ ++@item @file{org-toc.el} by @i{Bastien Guerry} ++Table of contents in a separate buffer, with fast access to sections and easy ++visibility cycling. ++ ++@item @file{orgtbl-sqlinsert.el} by @i{Jason Riedy} ++Convert Org-mode tables to SQL insertions. Documentation for this can be ++found on the Worg pages. ++ ++@end table ++ ++@node Other extensions, , Extensions in the contrib directory, Extensions ++@section Other extensions ++ ++@i{TO BE DONE} ++ ++@node Hacking, History and Acknowledgments, Extensions, Top ++@appendix Hacking ++ ++This appendix covers some aspects where users can extend the functionality of ++Org. ++ ++@menu ++* Adding hyperlink types:: New custom link types ++* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs ++* Dynamic blocks:: Automatically filled blocks ++* Special agenda views:: Customized views ++* Using the property API:: Writing programs that use entry properties ++* Using the mapping API:: Mapping over all or selected entries ++@end menu ++ ++@node Adding hyperlink types, Tables in arbitrary syntax, Hacking, Hacking ++@section Adding hyperlink types ++@cindex hyperlinks, adding new types ++ ++Org has a large number of hyperlink types built-in ++(@pxref{Hyperlinks}). If you would like to add new link types, it ++provides an interface for doing so. Let's look at an example file ++@file{org-man.el} that will add support for creating links like ++@samp{[[man:printf][The printf manpage]]} to show Unix manual pages inside ++emacs: ++ ++@lisp ++;;; org-man.el - Support for links to manpages in Org ++ ++(require 'org) ++ ++(org-add-link-type "man" 'org-man-open) ++(add-hook 'org-store-link-functions 'org-man-store-link) ++ ++(defcustom org-man-command 'man ++ "The Emacs command to be used to display a man page." ++ :group 'org-link ++ :type '(choice (const man) (const woman))) ++ ++(defun org-man-open (path) ++ "Visit the manpage on PATH. ++PATH should be a topic that can be thrown at the man command." ++ (funcall org-man-command path)) ++ ++(defun org-man-store-link () ++ "Store a link to a manpage." ++ (when (memq major-mode '(Man-mode woman-mode)) ++ ;; This is a man page, we do make this link ++ (let* ((page (org-man-get-page-name)) ++ (link (concat "man:" page)) ++ (description (format "Manpage for %s" page))) ++ (org-store-link-props ++ :type "man" ++ :link link ++ :description description)))) ++ ++(defun org-man-get-page-name () ++ "Extract the page name from the buffer name." ++ ;; This works for both `Man-mode' and `woman-mode'. ++ (if (string-match " \\(\\S-+\\)\\*" (buffer-name)) ++ (match-string 1 (buffer-name)) ++ (error "Cannot create link to this man page"))) ++ ++(provide 'org-man) ++ ++;;; org-man.el ends here ++@end lisp ++ ++@noindent ++You would activate this new link type in @file{.emacs} with ++ ++@lisp ++(require 'org-man) ++@end lisp ++ ++@noindent ++Let's go through the file and see what it does. ++@enumerate ++@item ++It does @code{(require 'org)} to make sure that @file{org.el} has been ++loaded. ++@item ++The next line calls @code{org-add-link-type} to define a new link type ++with prefix @samp{man}. The call also contains the name of a function ++that will be called to follow such a link. ++@item ++The next line adds a function to @code{org-store-link-functions}, in ++order to allow the command @kbd{C-c l} to record a useful link in a ++buffer displaying a man page. ++@end enumerate ++ ++The rest of the file defines the necessary variables and functions. ++First there is a customization variable that determines which emacs ++command should be used to display man pages. There are two options, ++@code{man} and @code{woman}. Then the function to follow a link is ++defined. It gets the link path as an argument - in this case the link ++path is just a topic for the manual command. The function calls the ++value of @code{org-man-command} to display the man page. ++ ++Finally the function @code{org-man-store-link} is defined. When you try ++to store a link with @kbd{C-c l}, also this function will be called to ++try to make a link. The function must first decide if it is supposed to ++create the link for this buffer type, we do this by checking the value ++of the variable @code{major-mode}. If not, the function must exit and ++return the value @code{nil}. If yes, the link is created by getting the ++manual topic from the buffer name and prefixing it with the string ++@samp{man:}. Then it must call the command @code{org-store-link-props} ++and set the @code{:type} and @code{:link} properties. Optionally you ++can also set the @code{:description} property to provide a default for ++the link description when the link is later inserted into an Org ++buffer with @kbd{C-c C-l}. ++ ++@node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Hacking ++@section Tables and lists in arbitrary syntax ++@cindex tables, in other modes ++@cindex lists, in other modes ++@cindex Orgtbl mode ++ ++Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a ++frequent feature request has been to make it work with native tables in ++specific languages, for example La@TeX{}. However, this is extremely ++hard to do in a general way, would lead to a customization nightmare, ++and would take away much of the simplicity of the Orgtbl mode table ++editor. ++ ++ ++This appendix describes a different approach. We keep the Orgtbl mode ++table in its native format (the @i{source table}), and use a custom ++function to @i{translate} the table to the correct syntax, and to ++@i{install} it in the right location (the @i{target table}). This puts ++the burden of writing conversion functions on the user, but it allows ++for a very flexible system. ++ ++Bastien added the ability to do the same with lists. You can use Org's ++facilities to edit and structure lists by turning @code{orgstruct-mode} ++on, then locally exporting such lists in another format (HTML, La@TeX{} ++or Texinfo.) ++ ++ ++@menu ++* Radio tables:: Sending and receiving ++* A LaTeX example:: Step by step, almost a tutorial ++* Translator functions:: Copy and modify ++* Radio lists:: Doing the same for lists ++@end menu ++ ++@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax ++@subsection Radio tables ++@cindex radio tables ++ ++To define the location of the target table, you first need to create two ++lines that are comments in the current mode, but contain magic words for ++Orgtbl mode to find. Orgtbl mode will insert the translated table ++between these lines, replacing whatever was there before. For example: ++ ++@example ++/* BEGIN RECEIVE ORGTBL table_name */ ++/* END RECEIVE ORGTBL table_name */ ++@end example ++ ++@noindent ++Just above the source table, we put a special line that tells ++Orgtbl mode how to translate this table and where to install it. For ++example: ++@example ++#+ORGTBL: SEND table_name translation_function arguments.... ++@end example ++ ++@noindent ++@code{table_name} is the reference name for the table that is also used ++in the receiver lines. @code{translation_function} is the Lisp function ++that does the translation. Furthermore, the line can contain a list of ++arguments (alternating key and value) at the end. The arguments will be ++passed as a property list to the translation function for ++interpretation. A few standard parameters are already recognized and ++acted upon before the translation function is called: ++ ++@table @code ++@item :skip N ++Skip the first N lines of the table. Hlines do count as separate lines for ++this parameter! ++ ++@item :skipcols (n1 n2 ...) ++List of columns that should be skipped. If the table has a column with ++calculation marks, that column is automatically discarded as well. ++Please note that the translator function sees the table @emph{after} the ++removal of these columns, the function never knows that there have been ++additional columns. ++@end table ++ ++@noindent ++The one problem remaining is how to keep the source table in the buffer ++without disturbing the normal workings of the file, for example during ++compilation of a C file or processing of a La@TeX{} file. There are a ++number of different solutions: ++ ++@itemize @bullet ++@item ++The table could be placed in a block comment if that is supported by the ++language. For example, in C mode you could wrap the table between ++@samp{/*} and @samp{*/} lines. ++@item ++Sometimes it is possible to put the table after some kind of @i{END} ++statement, for example @samp{\bye} in TeX and @samp{\end@{document@}} ++in La@TeX{}. ++@item ++You can just comment the table line by line whenever you want to process ++the file, and uncomment it whenever you need to edit the table. This ++only sounds tedious - the command @kbd{M-x orgtbl-toggle-comment} does ++make this comment-toggling very easy, in particular if you bind it to a ++key. ++@end itemize ++ ++@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax ++@subsection A LaTeX example of radio tables ++@cindex LaTeX, and Orgtbl mode ++ ++The best way to wrap the source table in La@TeX{} is to use the ++@code{comment} environment provided by @file{comment.sty}. It has to be ++activated by placing @code{\usepackage@{comment@}} into the document ++header. Orgtbl mode can insert a radio table skeleton@footnote{By ++default this works only for La@TeX{}, HTML, and Texinfo. Configure the ++variable @code{orgtbl-radio-tables} to install templates for other ++modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will ++be prompted for a table name, let's say we use @samp{salesfigures}. You ++will then get the following template: ++ ++@cindex #+ORGTBL: SEND ++@example ++% BEGIN RECEIVE ORGTBL salesfigures ++% END RECEIVE ORGTBL salesfigures ++\begin@{comment@} ++#+ORGTBL: SEND salesfigures orgtbl-to-latex ++| | | ++\end@{comment@} ++@end example ++ ++@noindent ++The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function ++@code{orgtbl-to-latex} to convert the table into La@TeX{} and to put it ++into the receiver location with name @code{salesfigures}. You may now ++fill in the table, feel free to use the spreadsheet features@footnote{If ++the @samp{#+TBLFM} line contains an odd number of dollar characters, ++this may cause problems with font-lock in LaTeX mode. As shown in the ++example you can fix this by adding an extra line inside the ++@code{comment} environment that is used to balance the dollar ++expressions. If you are using AUCTeX with the font-latex library, a ++much better solution is to add the @code{comment} environment to the ++variable @code{LaTeX-verbatim-environments}.}: ++ ++@example ++% BEGIN RECEIVE ORGTBL salesfigures ++% END RECEIVE ORGTBL salesfigures ++\begin@{comment@} ++#+ORGTBL: SEND salesfigures orgtbl-to-latex ++| Month | Days | Nr sold | per day | ++|-------+------+---------+---------| ++| Jan | 23 | 55 | 2.4 | ++| Feb | 21 | 16 | 0.8 | ++| March | 22 | 278 | 12.6 | ++#+TBLFM: $4=$3/$2;%.1f ++% $ (optional extra dollar to keep font-lock happy, see footnote) ++\end@{comment@} ++@end example ++ ++@noindent ++When you are done, press @kbd{C-c C-c} in the table to get the converted ++table inserted between the two marker lines. ++ ++Now let's assume you want to make the table header by hand, because you ++want to control how columns are aligned etc. In this case we make sure ++that the table translator does skip the first 2 lines of the source ++table, and tell the command to work as a @i{splice}, i.e. to not produce ++header and footer commands of the target table: ++ ++@example ++\begin@{tabular@}@{lrrr@} ++Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\ ++% BEGIN RECEIVE ORGTBL salesfigures ++% END RECEIVE ORGTBL salesfigures ++\end@{tabular@} ++% ++\begin@{comment@} ++#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2 ++| Month | Days | Nr sold | per day | ++|-------+------+---------+---------| ++| Jan | 23 | 55 | 2.4 | ++| Feb | 21 | 16 | 0.8 | ++| March | 22 | 278 | 12.6 | ++#+TBLFM: $4=$3/$2;%.1f ++\end@{comment@} ++@end example ++ ++The La@TeX{} translator function @code{orgtbl-to-latex} is already part of ++Orgtbl mode. It uses a @code{tabular} environment to typeset the table ++and marks horizontal lines with @code{\hline}. Furthermore, it ++interprets the following parameters (see also @ref{Translator functions}): ++ ++@table @code ++@item :splice nil/t ++When set to t, return only table body lines, don't wrap them into a ++tabular environment. Default is nil. ++ ++@item :fmt fmt ++A format to be used to wrap each field, should contain @code{%s} for the ++original field value. For example, to wrap each field value in dollars, ++you could use @code{:fmt "$%s$"}. This may also be a property list with ++column numbers and formats. for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}. ++A function of one argument can be used in place of the strings; the ++function must return a formatted string. ++ ++@item :efmt efmt ++Use this format to print numbers with exponentials. The format should ++have @code{%s} twice for inserting mantissa and exponent, for example ++@code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This ++may also be a property list with column numbers and formats, for example ++@code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After ++@code{efmt} has been applied to a value, @code{fmt} will also be ++applied. Similar to @code{fmt}, functions of two arguments can be ++supplied instead of strings. ++@end table ++ ++@node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax ++@subsection Translator functions ++@cindex HTML, and Orgtbl mode ++@cindex translator function ++ ++Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv} ++(comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values) ++@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}. ++Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the same ++code that produces tables during HTML export.}, these all use a generic ++translator, @code{orgtbl-to-generic}. For example, @code{orgtbl-to-latex} ++itself is a very short function that computes the column definitions for the ++@code{tabular} environment, defines a few field and line separators and then ++hands over to the generic translator. Here is the entire code: ++ ++@lisp ++@group ++(defun orgtbl-to-latex (table params) ++ "Convert the Orgtbl mode TABLE to LaTeX." ++ (let* ((alignment (mapconcat (lambda (x) (if x "r" "l")) ++ org-table-last-alignment "")) ++ (params2 ++ (list ++ :tstart (concat "\\begin@{tabular@}@{" alignment "@}") ++ :tend "\\end@{tabular@}" ++ :lstart "" :lend " \\\\" :sep " & " ++ :efmt "%s\\,(%s)" :hline "\\hline"))) ++ (orgtbl-to-generic table (org-combine-plists params2 params)))) ++@end group ++@end lisp ++ ++As you can see, the properties passed into the function (variable ++@var{PARAMS}) are combined with the ones newly defined in the function ++(variable @var{PARAMS2}). The ones passed into the function (i.e. the ++ones set by the @samp{ORGTBL SEND} line) take precedence. So if you ++would like to use the La@TeX{} translator, but wanted the line endings to ++be @samp{\\[2mm]} instead of the default @samp{\\}, you could just ++overrule the default with ++ ++@example ++#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]" ++@end example ++ ++For a new language, you can either write your own converter function in ++analogy with the La@TeX{} translator, or you can use the generic function ++directly. For example, if you have a language where a table is started ++with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are ++started with @samp{!BL!}, ended with @samp{!EL!} and where the field ++separator is a TAB, you could call the generic translator like this (on ++a single line!): ++ ++@example ++#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!" ++ :lstart "!BL! " :lend " !EL!" :sep "\t" ++@end example ++ ++@noindent ++Please check the documentation string of the function ++@code{orgtbl-to-generic} for a full list of parameters understood by ++that function and remember that you can pass each of them into ++@code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function ++using the generic function. ++ ++Of course you can also write a completely new function doing complicated ++things the generic translator cannot do. A translator function takes ++two arguments. The first argument is the table, a list of lines, each ++line either the symbol @code{hline} or a list of fields. The second ++argument is the property list containing all parameters specified in the ++@samp{#+ORGTBL: SEND} line. The function must return a single string ++containing the formatted table. If you write a generally useful ++translator, please post it on @code{emacs-orgmode@@gnu.org} so that ++others can benefit from your work. ++ ++@node Radio lists, , Translator functions, Tables in arbitrary syntax ++@subsection Radio lists ++@cindex radio lists ++@cindex org-list-insert-radio-list ++ ++Sending and receiving radio lists works exactly the same way than ++sending and receiving radio tables (@pxref{Radio tables}) @footnote{You ++need to load the @code{org-export-latex.el} package to use radio lists ++since the relevant code is there for now.}. As for radio tables, you ++can insert radio lists templates in HTML, La@TeX{} and Texinfo modes by ++calling @code{org-list-insert-radio-list}. ++ ++Here are the differences with radio tables: ++ ++@itemize @minus ++@item ++Use @code{ORGLST} instead of @code{ORGTBL}. ++@item ++The available translation functions for radio lists don't take ++parameters. ++@item ++`C-c C-c' will work when pressed on the first item of the list. ++@end itemize ++ ++Here is a La@TeX{} example. Let's say that you have this in your ++La@TeX{} file: ++ ++@example ++% BEGIN RECEIVE ORGLST to-buy ++% END RECEIVE ORGLST to-buy ++\begin@{comment@} ++#+ORGLIST: SEND to-buy orgtbl-to-latex ++- a new house ++- a new computer ++ + a new keyboard ++ + a new mouse ++- a new life ++\end@{comment@} ++@end example ++ ++Pressing `C-c C-c' on @code{a new house} and will insert the converted ++La@TeX{} list between the two marker lines. ++ ++@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking ++@section Dynamic blocks ++@cindex dynamic blocks ++ ++Org documents can contain @emph{dynamic blocks}. These are ++specially marked regions that are updated by some user-written function. ++A good example for such a block is the clock table inserted by the ++command @kbd{C-c C-x C-r} (@pxref{Clocking work time}). ++ ++Dynamic block are enclosed by a BEGIN-END structure that assigns a name ++to the block and can also specify parameters for the function producing ++the content of the block. ++ ++#+BEGIN:dynamic block ++@example ++#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... ++ ++#+END: ++@end example ++ ++Dynamic blocks are updated with the following commands ++ ++@table @kbd ++@kindex C-c C-x C-u ++@item C-c C-x C-u ++Update dynamic block at point. ++@kindex C-u C-c C-x C-u ++@item C-u C-c C-x C-u ++Update all dynamic blocks in the current file. ++@end table ++ ++Updating a dynamic block means to remove all the text between BEGIN and ++END, parse the BEGIN line for parameters and then call the specific ++writer function for this block to insert the new content. If you want ++to use the original content in the writer function, you can use the ++extra parameter @code{:content}. ++ ++For a block with name @code{myblock}, the writer function is ++@code{org-dblock-write:myblock} with as only parameter a property list ++with the parameters given in the begin line. Here is a trivial example ++of a block that keeps track of when the block update function was last ++run: ++ ++@example ++#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" ++ ++#+END: ++@end example ++ ++@noindent ++The corresponding block writer function could look like this: ++ ++@lisp ++(defun org-dblock-write:block-update-time (params) ++ (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) ++ (insert "Last block update at: " ++ (format-time-string fmt (current-time))))) ++@end lisp ++ ++If you want to make sure that all dynamic blocks are always up-to-date, ++you could add the function @code{org-update-all-dblocks} to a hook, for ++example @code{before-save-hook}. @code{org-update-all-dblocks} is ++written in a way that is does nothing in buffers that are not in ++@code{org-mode}. ++ ++@node Special agenda views, Using the property API, Dynamic blocks, Hacking ++@section Special agenda views ++@cindex agenda views, user-defined ++ ++Org provides a special hook that can be used to narrow down the ++selection made by any of the agenda views. You may specify a function ++that is used at each match to verify if the match should indeed be part ++of the agenda view, and if not, how much should be skipped. ++ ++Let's say you want to produce a list of projects that contain a WAITING ++tag anywhere in the project tree. Let's further assume that you have ++marked all tree headings that define a project with the TODO keyword ++PROJECT. In this case you would run a TODO search for the keyword ++PROJECT, but skip the match unless there is a WAITING tag anywhere in ++the subtree belonging to the project line. ++ ++To achieve this, you must write a function that searches the subtree for ++the tag. If the tag is found, the function must return @code{nil} to ++indicate that this match should not be skipped. If there is no such ++tag, return the location of the end of the subtree, to indicate that ++search should continue from there. ++ ++@lisp ++(defun my-skip-unless-waiting () ++ "Skip trees that are not waiting" ++ (let ((subtree-end (save-excursion (org-end-of-subtree t)))) ++ (if (re-search-forward ":waiting:" subtree-end t) ++ nil ; tag found, do not skip ++ subtree-end))) ; tag not found, continue after end of subtree ++@end lisp ++ ++Now you may use this function in an agenda custom command, for example ++like this: ++ ++@lisp ++(org-add-agenda-custom-command ++ '("b" todo "PROJECT" ++ ((org-agenda-skip-function 'my-skip-unless-waiting) ++ (org-agenda-overriding-header "Projects waiting for something: ")))) ++@end lisp ++ ++Note that this also binds @code{org-agenda-overriding-header} to get a ++meaningful header in the agenda view. ++ ++A general way to create custom searches is to base them on a search for ++entries with a certain level limit. If you want to study all entries with ++your custom search function, simply do a search for @samp{LEVEL>0}, and then ++use @code{org-agenda-skip-function} to select the entries you really want to ++have. ++ ++You may also put a Lisp form into @code{org-agenda-skip-function}. In ++particular, you may use the functions @code{org-agenda-skip-entry-if} ++and @code{org-agenda-skip-subtree-if} in this form, for example: ++ ++@table @code ++@item '(org-agenda-skip-entry-if 'scheduled) ++Skip current entry if it has been scheduled. ++@item '(org-agenda-skip-entry-if 'notscheduled) ++Skip current entry if it has not been scheduled. ++@item '(org-agenda-skip-entry-if 'deadline) ++Skip current entry if it has a deadline. ++@item '(org-agenda-skip-entry-if 'scheduled 'deadline) ++Skip current entry if it has a deadline, or if it is scheduled. ++@item '(org-agenda-skip-entry 'regexp "regular expression") ++Skip current entry if the regular expression matches in the entry. ++@item '(org-agenda-skip-entry 'notregexp "regular expression") ++Skip current entry unless the regular expression matches. ++@item '(org-agenda-skip-subtree-if 'regexp "regular expression") ++Same as above, but check and skip the entire subtree. ++@end table ++ ++Therefore we could also have written the search for WAITING projects ++like this, even without defining a special function: ++ ++@lisp ++(org-add-agenda-custom-command ++ '("b" todo "PROJECT" ++ ((org-agenda-skip-function '(org-agenda-skip-subtree-if ++ 'regexp ":waiting:")) ++ (org-agenda-overriding-header "Projects waiting for something: ")))) ++@end lisp ++ ++@node Using the property API, Using the mapping API, Special agenda views, Hacking ++@section Using the property API ++@cindex API, for properties ++@cindex properties, API ++ ++Here is a description of the functions that can be used to work with ++properties. ++ ++@defun org-entry-properties &optional pom which ++Get all properties of the entry at point-or-marker POM. ++This includes the TODO keyword, the tags, time strings for deadline, ++scheduled, and clocking, and any additional properties defined in the ++entry. The return value is an alist, keys may occur multiple times ++if the property key was used several times. ++POM may also be nil, in which case the current entry is used. ++If WHICH is nil or `all', get all properties. If WHICH is ++`special' or `standard', only get that subclass. ++@end defun ++@defun org-entry-get pom property &optional inherit ++Get value of PROPERTY for entry at point-or-marker POM. By default, ++this only looks at properties defined locally in the entry. If INHERIT ++is non-nil and the entry does not have the property, then also check ++higher levels of the hierarchy. If INHERIT is the symbol ++@code{selective}, use inheritance if and only if the setting of ++@code{org-use-property-inheritance} selects PROPERTY for inheritance. ++@end defun ++ ++@defun org-entry-delete pom property ++Delete the property PROPERTY from entry at point-or-marker POM. ++@end defun ++ ++@defun org-entry-put pom property value ++Set PROPERTY to VALUE for entry at point-or-marker POM. ++@end defun ++ ++@defun org-buffer-property-keys &optional include-specials ++Get all property keys in the current buffer. ++@end defun ++ ++@defun org-insert-property-drawer ++Insert a property drawer at point. ++@end defun ++ ++@defun org-entry-put-multivalued-property pom property &rest values ++Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a list of ++strings. They will be concatenated, with spaces as separators. ++@end defun ++ ++@defun org-entry-get-multivalued-property pom property ++Treat the value of the property PROPERTY as a whitespace-separated list of ++values and return the values as a list of strings. ++@end defun ++ ++@defun org-entry-add-to-multivalued-property pom property value ++Treat the value of the property PROPERTY as a whitespace-separated list of ++values and make sure that VALUE is in this list. ++@end defun ++ ++@defun org-entry-remove-from-multivalued-property pom property value ++Treat the value of the property PROPERTY as a whitespace-separated list of ++values and make sure that VALUE is @emph{not} in this list. ++@end defun ++ ++@defun org-entry-member-in-multivalued-property pom property value ++Treat the value of the property PROPERTY as a whitespace-separated list of ++values and check if VALUE is in this list. ++@end defun ++ ++@node Using the mapping API, , Using the property API, Hacking ++@section Using the mapping API ++@cindex API, for mapping ++@cindex mapping entries, API ++ ++Org has sophisticated mapping capabilities to find all entries satisfying ++certain criteria. Internally, this functionality is used to produce agenda ++views, but there is also an API that can be used to execute arbitrary ++functions for each or selected entries. The main entry point for this API ++is: ++ ++@defun org-map-entries func &optional match scope &rest skip ++Call FUNC at each headline selected by MATCH in SCOPE. ++ ++FUNC is a function or a lisp form. The function will be called without ++arguments, with the cursor positioned at the beginning of the headline. ++The return values of all calls to the function will be collected and ++returned as a list. ++ ++MATCH is a tags/property/todo match as it is used in the agenda match view. ++Only headlines that are matched by this query will be considered during ++the iteration. When MATCH is nil or t, all headlines will be ++visited by the iteration. ++ ++SCOPE determines the scope of this command. It can be any of: ++ ++@example ++nil @r{the current buffer, respecting the restriction if any} ++tree @r{the subtree started with the entry at point} ++file @r{the current buffer, without restriction} ++file-with-archives ++ @r{the current buffer, and any archives associated with it} ++agenda @r{all agenda files} ++agenda-with-archives ++ @r{all agenda files with any archive files associated with them} ++(file1 file2 ...) ++ @r{if this is a list, all files in the list will be scanned} ++@end example ++ ++The remaining args are treated as settings for the skipping facilities of ++the scanner. The following items can be given here: ++ ++@example ++archive @r{skip trees with the archive tag} ++comment @r{skip trees with the COMMENT keyword} ++function or Lisp form ++ @r{will be used as value for @code{org-agenda-skip-function},} ++ @r{so whenever the function returns t, FUNC} ++ @r{will not be called for that entry and search will} ++ @r{continue from the point where the function leaves it} ++@end example ++@end defun ++ ++The function given to that mapping routine can really do anything you like. ++It can use the property API (@pxref{Using the property API}) to gather more ++information about the entry, or in order to change metadata in the entry. ++Here are a couple of functions that might be handy: ++ ++@defun org-todo &optional arg ++Change the TODO state of the entry, see the docstring of the functions for ++the many possible values for the argument ARG. ++@end defun ++ ++@defun org-priority &optional action ++Change the priority of the entry, see the docstring of this function for the ++possible values for ACTION. ++@end defun ++ ++@defun org-toggle-tag tag &optional onoff ++Toggle the tag TAG in the current entry. Setting ONOFF to either @code{on} ++or @code{off} will not toggle tag, but ensure that it is either on or off. ++@end defun ++ ++@defun org-promote ++Promote the current entry. ++@end defun ++ ++@defun org-demote ++Demote the current entry. ++@end defun ++ ++Here is a simple example that will turn all entries in the current file with ++a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}. ++Entries in comment trees and in archive trees will be ignored. ++ ++@lisp ++(org-map-entries ++ '(org-todo "UPCOMING") ++ "+TOMORROW" 'file 'archive 'comment) ++@end lisp ++ ++The following example counts the number of entries with TODO keyword ++@code{WAITING}, in all agenda files. ++ ++@lisp ++(length (org-map-entries t "/+WAITING" 'agenda)) ++@end lisp ++ ++@node History and Acknowledgments, Main Index, Hacking, Top ++@appendix History and Acknowledgments ++@cindex acknowledgments ++@cindex history ++@cindex thanks ++ ++Org was borne in 2003, out of frustration over the user interface ++of the Emacs Outline mode. I was trying to organize my notes and ++projects, and using Emacs seemed to be the natural way to go. However, ++having to remember eleven different commands with two or three keys per ++command, only to hide and show parts of the outline tree, that seemed ++entirely unacceptable to me. Also, when using outlines to take notes, I ++constantly want to restructure the tree, organizing it parallel to my ++thoughts and plans. @emph{Visibility cycling} and @emph{structure ++editing} were originally implemented in the package ++@file{outline-magic.el}, but quickly moved to the more general ++@file{org.el}. As this environment became comfortable for project ++planning, the next step was adding @emph{TODO entries}, basic @emph{time ++stamps}, and @emph{table support}. These areas highlight the two main ++goals that Org still has today: To create a new, outline-based, ++plain text mode with innovative and intuitive editing features, and to ++incorporate project planning functionality directly into a notes file. ++ ++A special thanks goes to @i{Bastien Guerry} who has not only written a large ++number of extensions to Org (most of them integrated into the core by now), ++but has also helped the development and maintenance of Org so much that he ++should be considered the main co-contributor to this package. ++ ++Since the first release, literally thousands of emails to me or on ++@code{emacs-orgmode@@gnu.org} have provided a constant stream of bug ++reports, feedback, new ideas, and sometimes patches and add-on code. ++Many thanks to everyone who has helped to improve this package. I am ++trying to keep here a list of the people who had significant influence ++in shaping one or more aspects of Org. The list may not be ++complete, if I have forgotten someone, please accept my apologies and ++let me know. ++ ++@itemize @bullet ++ ++@item ++@i{Russel Adams} came up with the idea for drawers. ++@item ++@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}. ++@item ++@i{Christophe Bataillon} created the great unicorn logo that we use on the ++Org-mode website. ++@item ++@i{Alex Bochannek} provided a patch for rounding time stamps. ++@item ++@i{Charles Cave}'s suggestion sparked the implementation of templates ++for Remember. ++@item ++@i{Pavel Chalmoviansky} influenced the agenda treatment of items with ++specified time. ++@item ++@i{Gregory Chernov} patched support for lisp forms into table ++calculations and improved XEmacs compatibility, in particular by porting ++@file{nouline.el} to XEmacs. ++@item ++@i{Sacha Chua} suggested to copy some linking code from Planner. ++@item ++@i{Eddward DeVilla} proposed and tested checkbox statistics. He also ++came up with the idea of properties, and that there should be an API for ++them. ++@item ++@i{Kees Dullemond} used to edit projects lists directly in HTML and so ++inspired some of the early development, including HTML export. He also ++asked for a way to narrow wide table columns. ++@item ++@i{Christian Egli} converted the documentation into Texinfo format, ++patched CSS formatting into the HTML exporter, and inspired the agenda. ++@item ++@i{David Emery} provided a patch for custom CSS support in exported ++HTML agendas. ++@item ++@i{Nic Ferrier} contributed mailcap and XOXO support. ++@item ++@i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes. ++@item ++@i{John Foerch} figured out how to make incremental search show context ++around a match in a hidden outline tree. ++@item ++@i{Niels Giesen} had the idea to automatically archive DONE trees. ++@item ++@i{Bastien Guerry} wrote the La@TeX{} exporter and @file{org-bibtex.el}, and ++has been prolific with patches, ideas, and bug reports. ++@item ++@i{Kai Grossjohann} pointed out key-binding conflicts with other packages. ++@item ++@i{Bernt Hansen} has driven much of the support for auto-repeating tasks, ++task state change logging, and the clocktable. His clear explanations have ++been critical when we started to adopt the GIT version control system. ++@item ++@i{Manuel Hermenegildo} has contributed various ideas, small fixed and ++patches. ++@item ++@i{Phil Jackson} wrote @file{org-irc.el}. ++@item ++@i{Scott Jaderholm} proposed footnotes, control over whitespace between ++folded entries, and column view for properties. ++@item ++@i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}. ++@item ++@i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also ++provided frequent feedback and some patches. ++@item ++@i{Matt Lundin} has proposed last-row references for table formulas and named ++invisible anchors. He has also worked a lot on the FAQ. ++@item ++@i{Jason F. McBrayer} suggested agenda export to CSV format. ++@item ++@i{Max Mikhanosha} came up with the idea of refiling. ++@item ++@i{Dmitri Minaev} sent a patch to set priority limits on a per-file ++basis. ++@item ++@i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler ++happy. ++@item ++@i{Rick Moynihan} proposed to allow multiple TODO sequences in a file ++and to be able to quickly restrict the agenda to a subtree. ++@item ++@i{Todd Neal} provided patches for links to Info files and elisp forms. ++@item ++@i{Tim O'Callaghan} suggested in-file links, search options for general ++file links, and TAGS. ++@item ++@i{Takeshi Okano} translated the manual and David O'Toole's tutorial ++into Japanese. ++@item ++@i{Oliver Oppitz} suggested multi-state TODO items. ++@item ++@i{Scott Otterson} sparked the introduction of descriptive text for ++links, among other things. ++@item ++@i{Pete Phillips} helped during the development of the TAGS feature, and ++provided frequent feedback. ++@item ++@i{T.V. Raman} reported bugs and suggested improvements. ++@item ++@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality ++control. ++@item ++@i{Paul Rivier} provided the basic implementation of named footnotes. ++@item ++@i{Kevin Rogers} contributed code to access VM files on remote hosts. ++@item ++@i{Sebastian Rose} wrote @file{org-info.js}, a Java script for displaying ++webpages derived from Org using an Info-like, or a folding interface with ++single key navigation. ++@item ++@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a ++conflict with @file{allout.el}. ++@item ++@i{Jason Riedy} generalized the send-receive mechanism for orgtbl tables with ++extensive patches. ++@item ++@i{Philip Rooke} created the Org reference card, provided lots ++of feedback, developed and applied standards to the Org documentation. ++@item ++@i{Christian Schlauer} proposed angular brackets around links, among ++other things. ++@item ++@i{Eric Schulte} wrote @file{org-plot.el}. ++@item ++Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s ++@file{organizer-mode.el}. ++@item ++@i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal ++examples, and remote highlighting for referenced code lines. ++@item ++@i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is ++now packaged into Org's @file{contrib} directory. ++@item ++@i{Daniel Sinder} came up with the idea of internal archiving by locking ++subtrees. ++@item ++@i{Dale Smith} proposed link abbreviations. ++@item ++@i{James TD Smith} has contributed a large number of patches for useful ++tweaks and features. ++@item ++@i{Adam Spiers} asked for global linking commands, inspired the link ++extension system, added support for mairix, and proposed the mapping API. ++@item ++@i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content ++with links transformation to Org syntax. ++@item ++@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual ++chapter about publishing. ++@item ++@i{J@"urgen Vollmer} contributed code generating the table of contents ++in HTML output. ++@item ++@i{Chris Wallace} provided a patch implementing the @samp{QUOTE} ++keyword. ++@item ++@i{David Wainberg} suggested archiving, and improvements to the linking ++system. ++@item ++@i{John Wiegley} wrote @file{emacs-wiki.el}, @file{planner.el}, and ++@file{muse.el}, which have some overlap with Org. Initially the development ++of Org was fully independent because I was not aware of the existence of ++these packages. But with time I have occasionally looked at John's code and ++learned a lot from it. John has also contributed a number of great ideas and ++patches directly to Org, including the attachment system ++(@file{org-attach.el}), integration with Apple Mail ++(@file{org-mac-message.el}), and hierarchical dependencies of TODO items. ++@item ++@i{Carsten Wimmer} suggested some changes and helped fix a bug in ++linking to Gnus. ++@item ++@i{Roland Winkler} requested additional key bindings to make Org ++work on a tty. ++@item ++@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks ++and contributed various ideas and code snippets. ++@end itemize ++ ++ ++@node Main Index, Key Index, History and Acknowledgments, Top ++@unnumbered The Main Index ++ ++@printindex cp ++ ++@node Key Index, , Main Index, Top ++@unnumbered Key Index ++ ++@printindex ky ++ ++@bye ++ ++@ignore ++ arch-tag: 7893d1Fe-cc57-4d13-b5e5-f494a1CBC7ac ++@end ignore ++ ++@c Local variables: ++@c ispell-local-dictionary: "en_US-w_accents" ++@c ispell-local-pdict: "./.aspell.org.pws" ++@c fill-column: 77 ++@c End: ++ +diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi +new file mode 100644 +index 0000000..1219441 +--- /dev/null ++++ b/doc/misc/pcl-cvs.texi +@@ -0,0 +1,1438 @@ ++\input texinfo @c -*-texinfo-*- ++@c %**start of header ++@setfilename ../../info/pcl-cvs ++@settitle PCL-CVS --- Emacs Front-End to CVS ++@syncodeindex vr fn ++@c %**end of header ++ ++@copying ++Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, ++1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++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 Emacs ++@direntry ++* PCL-CVS: (pcl-cvs). Emacs front-end to CVS. ++@end direntry ++ ++@c The titlepage section does not appear in the Info file. ++@titlepage ++@sp 4 ++@c The title is printed in a large font. ++@center @titlefont{User's Guide} ++@sp ++@center @titlefont{to} ++@sp ++@center @titlefont{PCL-CVS --- The Emacs Front-End to CVS} ++@ignore ++@sp 2 ++@center release 2.9 ++@c -release- ++@end ignore ++@sp 3 ++@center Per Cederqvist ++@center Stefan Monnier ++@c -date- ++ ++@c The following two commands start the copyright page ++@c for the printed manual. This will not appear in the Info file. ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@c ================================================================ ++@c The real text starts here ++@c ================================================================ ++ ++@node Top, About PCL-CVS, (dir), (dir) ++@ifnottex ++@top PCL-CVS ++ ++This manual describes PCL-CVS, the GNU Emacs front-end to CVS. It ++is nowhere near complete, so you are advised to use @kbd{M-x ++customize-group RET pcl-cvs @key{RET}} and to look at the documentation strings ++of the various commands and major modes for further information. ++@c This manual is updated to release 2.5 of PCL-CVS. ++ ++@insertcopying ++ ++@end ifnottex ++ ++@menu ++* About PCL-CVS:: Credits, history, @dots{} ++ ++* Getting started:: An introduction with a walk-through example. ++* Buffer contents:: An explanation of the buffer contents. ++* Selected files:: To which files are commands applied. ++* Commands:: All commands, grouped by type. ++ ++* Log Edit Mode:: Major mode to edit log messages. ++* Log View Mode:: Major mode to browse log changes. ++@c * CVS Status Mode:: Major mode to view CVS' status output. ++* Customization:: How you can tailor PCL-CVS to suit your needs. ++* Bugs:: Bugs (known and unknown). ++ ++* GNU Free Documentation License:: The license for this documentation. ++* Function and Variable Index:: List of functions and variables. ++* Concept Index:: List of concepts. ++* Key Index:: List of keystrokes. ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ ++About PCL-CVS ++ ++* Contributors:: Contributors to PCL-CVS. ++ ++Commands ++ ++* Entering PCL-CVS:: Commands to invoke PCL-CVS ++* Setting flags:: Setting flags for CVS commands ++* Updating the buffer:: ++* Movement commands:: How to move up and down in the buffer ++* Marking files:: How to mark files that other commands ++ will later operate on. ++* Committing changes:: Checking in your modifications to the ++ CVS repository. ++* Editing files:: Loading files into Emacs. ++* Getting info about files:: Display the log and status of files. ++* Adding and removing files:: Adding and removing files ++* Undoing changes:: Undoing changes ++* Removing handled entries:: Uninteresting lines can easily be removed. ++* Ignoring files:: Telling CVS to ignore generated files. ++* Viewing differences:: Commands to @samp{diff} different versions. ++* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer. ++* Updating files:: Updating files that Need-update. ++* Tagging files:: Tagging files. ++* Miscellaneous commands:: Miscellaneous commands. ++ ++Customization ++ ++* Customizing Faces:: ++ ++@end detailmenu ++@end menu ++ ++@node About PCL-CVS, Getting started, Top, Top ++@chapter About PCL-CVS ++@cindex About PCL-CVS ++ ++PCL-CVS is a front-end to CVS versions 1.9 and later. ++It concisely shows the present status of a checked out module in an ++Emacs buffer and provides single-key access to the most frequently used CVS ++commands. ++For Emacs users accustomed to VC, PCL-CVS can be thought of as a replacement ++for VC-dired (@pxref{VC Directory Mode, , , emacs, The GNU ++Emacs Manual}) specifically designed for CVS. ++ ++PCL-CVS was originally written many years ago by Per Cederqvist who ++proudly maintained it until January 1996, at which point he released the ++beta version 2.0b2 and passed on the maintainership to Greg A Woods. ++Development stayed mostly dormant for a few years during which ++version 2.0 never seemed to be able to leave the ``beta'' stage while a ++separate XEmacs version was slowly splitting away. In late 1998, ++Stefan Monnier picked up development again, adding some major new ++functionality and taking over the maintenance. ++ ++@menu ++* Contributors:: Contributors to PCL-CVS. ++@end menu ++ ++@node Contributors,, About PCL-CVS, About PCL-CVS ++@section Contributors to PCL-CVS ++@cindex Contributors ++@cindex Authors ++ ++Contributions to the package are welcome. I have limited time to work ++on this project, but I will gladly add any code that you contribute to ++me to this package (@pxref{Bugs}). ++ ++The following persons have made contributions to PCL-CVS. ++ ++@itemize @bullet ++@item ++Brian Berliner wrote CVS, together with some other contributors. ++Without his work on CVS this package would be useless@dots{} ++ ++@item ++Per Cederqvist wrote most of the otherwise unattributed functions in ++PCL-CVS as well as all the documentation. ++ ++@item ++@email{inge@@lysator.liu.se, Inge Wallin} wrote the skeleton of ++@file{pcl-cvs.texi}, and gave useful comments on it. He also wrote ++the files @file{elib-node.el} and @file{compile-all.el}. The file ++@file{cookie.el} was inspired by Inge.@refill ++ ++@item ++@email{linus@@lysator.liu.se, Linus Tolke} contributed useful comments ++on both the functionality and the documentation.@refill ++ ++@item ++@email{jwz@@jwz.com, Jamie Zawinski} contributed ++@file{pcl-cvs-lucid.el}, which was later renamed to ++@file{pcl-cvs-xemacs.el}.@refill ++ ++@item ++Leif Lonnblad contributed RCVS support (since superseded by the new ++remote CVS support). ++ ++@item ++@email{jimb@@cyclic.com, Jim Blandy} contributed hooks to automatically ++guess CVS log entries from @file{ChangeLog} contents, and initial support of ++the new Cygnus / Cyclic remote CVS, as well as various sundry bug fixes ++and cleanups. ++ ++@item ++@email{kingdon@@cyclic.com, Jim Kingdon} contributed lots of fixes to ++the build and installation procedure. ++ ++@item ++@email{woods@@weird.com, Greg A.@: Woods} contributed code to implement ++the use of per-file diff buffers, and vendor join diffs with emerge and ++ediff, as well as various and sundry bug fixes and cleanups. ++ ++@item ++@email{greg.klanderman@@alum.mit.edu, Greg Klanderman} implemented ++toggling of marked files, setting of CVS command flags via prefix ++arguments, updated the XEmacs support, updated the manual, and fixed ++numerous bugs. ++ ++@item ++@email{monnier@@gnu.org, Stefan Monnier} added a slew of other ++features and introduced even more new bugs. If there's any bug left, ++you can be sure it's his. ++ ++@item ++@c wordy to avoid an underfull hbox ++@email{masata-y@@is.aist-nara.ac.jp, Masatake YAMATO} made a gracious ++contribution of his cvstree code to display a tree of tags which was later ++superseded by the new @code{cvs-status-mode}. ++@end itemize ++ ++Apart from these, a lot of people have sent us suggestions, ideas, ++requests, bug reports and encouragement. Thanks a lot! Without you ++there would be no new releases of PCL-CVS. ++ ++ ++@node Getting started, Buffer contents, About PCL-CVS, Top ++@chapter Getting started ++@cindex Introduction ++@cindex Example run ++@cindex Sample session ++ ++This document assumes that you know what CVS is, and that you at least ++know the fundamental concepts of CVS. If that is not the case, you ++should read the CVS documentation. Type @kbd{info -f cvs} or @kbd{man ++cvs}. ++ ++PCL-CVS is only useful once you have checked out a module. So before ++you invoke it, you must have a copy of a module somewhere in the file ++system. ++ ++You can invoke PCL-CVS by typing @kbd{M-x cvs-examine @key{RET}}. ++You can also invoke it via the menu bar, under @samp{Tools}. ++Or, if you prefer, you can also invoke PCL-CVS by simply visiting the ++CVS administrative subdirectory of your module, with a prefix argument. ++For example, to invoke PCL-CVS in a separate frame, type @kbd{C-u C-x 5 ++f ~/my/project/CVS @key{RET}}. ++ ++The function @code{cvs-examine} will ask for a directory. The command ++@samp{cvs -n update} will be run in that directory. (It should contain ++files that have been checked out from a CVS archive.) The output from ++@code{cvs} will be parsed and presented in a table in a buffer called ++@samp{*cvs*}. It might look something like this: ++ ++@example ++Repository : /usr/CVSroot ++Module : test ++Working dir: /users/ceder/FOO/test ++ ++ ++In directory .: ++ Need-Update bar ++ Need-Update file.txt ++ Modified namechange ++ Need-Update newer ++In directory sub: ++ Modified ChangeLog ++ ++--------------------- End --------------------- ++-- last cmd: cvs -f -z6 -n update -d -P -- ++@end example ++ ++In this example, your repository is in @file{/usr/CVSroot} and CVS has ++been run in the directory @file{/users/ceder/FOO/test}. The three files ++(@file{bar}, @file{file.txt} and ++@file{newer}) that are marked with @samp{Need-Update} have been changed ++by someone else in the CVS repository. Two files (@file{namechange} ++and @file{sub/ChangeLog}) have been modified locally, and need to be ++checked in. ++ ++You can move the cursor up and down in the buffer with @kbd{C-n} and ++@kbd{C-p} or @kbd{n} and @kbd{p}. If you press @kbd{c} on one of the ++@samp{Modified} files, that file will be checked in to the CVS ++repository. @xref{Committing changes}. You can also press @kbd{O} to ++update any of the files that are marked @samp{Need-Update}. You can ++also run @kbd{M-x cvs-update @key{RET}} (bound to @kbd{M-u} in the ++@samp{*cvs*} buffer) to update all the files.@refill ++ ++You can then press @kbd{=} to easily get a @samp{diff} between your ++modified file and the base version that you started from, or you can ++press @kbd{l} to get the output from @samp{cvs log}. Many more such ++commands are available simply by pressing a key (@pxref{Getting info ++about files}). ++ ++@node Buffer contents, Selected files, Getting started, Top ++@chapter Buffer contents ++@cindex Buffer contents ++@cindex @code{*cvs*} buffer contents ++ ++The display contains several columns, some of which are optional. ++These columns are, from left to right: ++ ++@itemize @bullet ++ ++@item ++Optionally, the head revision of the file. This is the latest version ++found in the repository. It might also contain (instead of the head ++revision) a sub status which typically gives further information about ++how we got to the current state, for example @samp{patched}, ++@samp{merged}, @dots{} ++ ++@item ++An asterisk when the file is @dfn{marked} (@pxref{Selected ++files}).@refill ++ ++@item ++The actual status of the file wrt the repository. See below. ++ ++@item ++Optionally, the base revision of the file. This is the version ++which the copy in your working directory is based upon. ++ ++@item ++The file name. ++ ++@end itemize ++ ++The @samp{file status} field can have the following values: ++ ++@table @samp ++@item Modified ++The file is modified in your working directory, and there was no ++modification to the same file in the repository. This status can have ++the following substatus: ++ ++@table @samp ++@item merged ++The file was modified in your working directory, and there were ++modifications in the repository as well, but they were merged ++successfully, without conflict, in your working directory.@refill ++@end table ++ ++@item Conflict ++A conflict was detected while trying to merge your changes to @var{file} ++with changes from the repository. @var{file} (the copy in your ++working directory) is now the output of the @code{rcsmerge} command on ++the two versions; an unmodified copy of your file is also in your ++working directory, with the name @file{.#@var{file}.@var{version}}, ++where @var{version} is the RCS revision that your modified file started ++from. @xref{Viewing differences}, for more details.@refill ++ ++A conflict can also come from a disagreement on the existence of the file ++rather than on its content. This case is indicated by the following ++possible substatus: ++ ++@table @samp ++@item removed ++The file is locally removed but a new revision has been committed to ++the repository by someone else. ++ ++@item added ++The file is locally added and has also been added to the repository ++by someone else. ++ ++@item modified ++The file is locally modified but someone else has removed it from the ++repository. ++@end table ++ ++@item Added ++The file has been added by you, but it still needs to be checked in to ++the repository.@refill ++ ++@item Removed ++The file has been removed by you, but it still needs to be checked in to ++the repository. You can resurrect it by typing @kbd{a} (@pxref{Adding ++and removing files}).@refill ++ ++@item Unknown ++A file that was detected in your directory, but that neither appears in ++the repository, nor is present on the list of files that CVS should ++ignore.@refill ++ ++@item Up-to-date ++The file is up to date with respect to the version in the repository. ++This status can have a substatus of: ++ ++@table @samp ++@item added ++You have just added the file to the repository.@refill ++ ++@item updated ++The file was brought up to date with respect to the repository. This is ++done for any file that exists in the repository but not in your source, ++and for files that you haven't changed but are not the most recent ++versions available in the repository.@refill ++ ++@item patched ++The file was brought up to date with respect to the remote repository by ++way of fetching and applying a patch to the file in your source. This ++is equivalent to @samp{updated} except that CVS decided to use a hopefully ++more efficient method.@refill ++ ++@item committed ++You just committed the file.@refill ++@end table ++ ++@item Need-Update ++Either a newer version than the one in your source is available in the ++repository and you have not modified your checked out version, or the ++file exists in the repository but not in your source. Use ++@samp{cvs-mode-update} bound to @kbd{O} to update the file.@refill ++ ++@item Need-Merge ++You have modified the checked out version of the file, and a newer ++version is available in the repository. A merge will take place when ++you run a @samp{cvs-update}. ++ ++@item Missing ++The file has been unexpectedly removed from your working directory ++although it has not been @samp{cvs remove}d. ++@end table ++ ++@node Selected files, Commands, Buffer contents, Top ++@chapter Selected files ++@cindex Selected files ++@cindex Marked files ++@cindex File selection ++@cindex Active files ++@cindex Applicable ++ ++Many of the commands work on the current set of @dfn{selected} files ++which can be either the set of marked files (if any file is marked and ++marks are not ignored) or whichever file or directory the cursor is on. ++ ++If a directory is selected but the command cannot be applied to a ++directory, then it will be applied to the set of files under this ++directory which are in the @samp{*cvs*} buffer. ++ ++@findex cvs-mode-force-command ++@findex cvs-allow-dir-commit ++Furthermore, each command only operates on a subset of the selected ++files, depending on whether or not the command is @dfn{applicable} to ++each file (based on the file's status). For example, ++@code{cvs-mode-commit} is not applicable to a file whose status is ++@samp{Need-Update}. If it should happen that PCL-CVS guesses the ++applicability wrong, you can override it with the special prefix ++@code{cvs-mode-force-command} normally bound to @kbd{M-f} (and file a ++bug report). The applicability rule can be slightly changed with ++@code{cvs-allow-dir-commit} and @code{cvs-force-dir-tag}. ++ ++By default, marks are always in effect (you may change this, however, by ++setting the variable @code{cvs-default-ignore-marks}) except for the ++commands that @samp{tag} or @samp{diff} a file (which can be changed ++with the variable @code{cvs-invert-ignore-marks}). ++ ++In addition, you may use the special prefix @code{cvs-mode-toggle-marks} ++normally bound to @key{T} to toggle the use of marks for the following ++command. ++ ++This scheme might seem a little complicated, but once one gets used to ++it, it is quite powerful. ++ ++For commands to mark and unmark files, see @ref{Marking files}. ++ ++@node Commands, Log Edit Mode, Selected files, Top ++@chapter Commands ++ ++@iftex ++This chapter describes all the commands that you can use in PCL-CVS. ++@end iftex ++@ifnottex ++The nodes in this menu contains explanations about all the commands that ++you can use in PCL-CVS. They are grouped together by type. ++@end ifnottex ++ ++@menu ++* Entering PCL-CVS:: Commands to invoke PCL-CVS ++* Setting flags:: Setting flags for CVS commands ++* Updating the buffer:: ++* Movement commands:: How to move up and down in the buffer ++* Marking files:: How to mark files that other commands ++ will later operate on. ++* Committing changes:: Checking in your modifications to the ++ CVS repository. ++* Editing files:: Loading files into Emacs. ++* Getting info about files:: Display the log and status of files. ++* Adding and removing files:: Adding and removing files ++* Undoing changes:: Undoing changes ++* Removing handled entries:: Uninteresting lines can easily be removed. ++* Ignoring files:: Telling CVS to ignore generated files. ++* Viewing differences:: Commands to @samp{diff} different versions. ++* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer. ++* Updating files:: Updating files that Need-update. ++* Tagging files:: Tagging files. ++* Miscellaneous commands:: Miscellaneous commands. ++@end menu ++ ++ ++@node Entering PCL-CVS, Setting flags, Commands, Commands ++@section Entering PCL-CVS ++@findex cvs-update ++@findex cvs-examine ++@findex cvs-status ++@findex cvs-checkout ++@findex cvs-quickdir ++@cindex Creating the *cvs* buffer ++ ++Most commands in PCL-CVS require that you have a @samp{*cvs*} ++buffer. The commands that you use to get one are listed below. ++For each, a @samp{cvs} process will be run, the output will be parsed by ++PCL-CVS, and the result will be printed in the @samp{*cvs*} buffer (see ++@ref{Buffer contents}, for a description of the buffer's contents). ++ ++@table @kbd ++@item M-x cvs-update ++Run a @samp{cvs update} command. You will be asked for the directory ++in which the @samp{cvs update} will be run. ++ ++@item M-x cvs-examine ++Run a @samp{cvs -n update} command. This is identical to the previous ++command, except that it will only check what needs to be done but will ++not change anything. You will be asked for the directory in ++which the @samp{cvs -n update} will be run. ++ ++@item M-x cvs-status ++Run a @samp{cvs status} command. You will be asked for the directory ++in which the @samp{cvs status} will be run. ++ ++@item M-x cvs-checkout ++Run a @samp{cvs checkout} command. You will be asked for the directory ++in which the @samp{cvs update} will be run and the module to be checked ++out. ++ ++@item M-x cvs-quickdir ++Populate the @samp{*cvs*} buffer by just looking at the @file{CVS/Entries} ++files. This is very much like @code{cvs-examine} except that it does ++not access the CVS repository, which is a major advantage when the ++repository is far away. But of course, it will not be able to detect ++when a file needs to be updated or merged. ++@end table ++ ++@findex cvs-dired-action ++@findex cvs-dired-use-hook ++The first four of ++those commands are also reachable from the menu bar ++under @samp{Tools->PCL-CVS}. Finally, an alternative way is to visit ++the CVS administrative subdirectory in your work area with a simple ++prefix argument. For example @kbd{C-u C-x C-f ~/my/work/CVS @key{RET}}. This ++by default runs @code{cvs-quickdir} but the specific behavior can be ++changed with @code{cvs-dired-action} and @code{cvs-dired-use-hook}. ++ ++By default, the commands above will descend recursively into ++subdirectories. You can avoid that behavior by including @samp{-l} in ++the flags for the command. These flags can be set by giving a prefix ++argument to the command (e.g., by typing ++@kbd{C-u M-x cvs-update @key{RET} -l @key{RET}}). ++ ++ ++@node Setting flags, Updating the buffer, Entering PCL-CVS, Commands ++@section Setting flags for CVS commands ++@cindex Optional switches to CVS ++@cindex Command-line options to CVS ++ ++This section describes the convention used by nearly all PCL-CVS ++commands for setting optional flags sent to CVS. A single @kbd{C-u} ++prefix argument is used to cause the command to prompt for flags to be ++used for the current invocation of the command only. Two @kbd{C-u} prefix ++arguments are used to prompt for flags which will be set permanently, for the ++current invocation and all that follow, until the flags are changed, or ++unless temporary flags are set which override them. ++ ++Perhaps an example or two is in order. Say you are about to add a ++binary file to the repository, and want to specify the flags @samp{-kb} ++to @samp{cvs add}. You can type @kbd{C-u a -kb @key{RET}}, ++and the file will be added. Subsequent @samp{cvs add} ++commands will use the previously prevailing flags. ++ ++As a second example, say you are about to perform a diff and want to see ++the result in unified diff format, i.e. you'd like to pass the flag ++@samp{-u} to both @samp{cvs diff} and @samp{diff}. You'd also like all ++subsequent diffs to use this flag. You can type @kbd{C-u C-u = -u @key{RET}} ++and the diff will be performed, and the default flags will be set to ++@code{("-u")}. You can of course override this flag for a single diff ++by using a single @kbd{C-u} prefix argument. ++ ++@cindex Special prefix ++In addition to this, some commands can take @dfn{special prefix} arguments. ++These work as follows: When called with a @kbd{C-u} prefix, the user is ++prompted for a new value of the special prefix and the special prefix is ++activated for the next command. When called without the @kbd{C-u} ++prefix, the special prefix is re-activated (with the same value as last ++time) for the next command. Calling the prefix command again when it's ++already activated deactivates it. Calling it with the @kbd{C-u C-u} ++prefix activates it for all subsequent commands until you deactivate it ++explicitly. The special prefixes are: ++ ++@table @kbd ++@item T ++Toggles whether or not marks will be active in the next command.@refill ++ ++@item b ++Provide the next command with a branch (can be any version ++specifier) to work on.@refill ++ ++@item B ++Secondary branch argument. Only meaningful if @kbd{b} is also used. ++It can be used to provide a second branch argument to ++@code{cvs-mode-diff} or to @code{cvs-mode-update}. ++ ++@item M-f ++Forces the next command to apply to every selected file rather than only ++to the ones PCL-CVS thinks are relevant. ++@end table ++ ++@node Updating the buffer, Movement commands, Setting flags, Commands ++@section Updating the @samp{*cvs*} buffer ++@findex cvs-update ++@findex cvs-examine ++@findex cvs-status ++@findex cvs-mode-update ++@findex cvs-mode-examine ++@findex cvs-mode-status ++ ++The following commands can be used from within the @samp{*cvs*} buffer ++to update the display: ++ ++@table @kbd ++@item M-u ++Runs the command @samp{cvs-update}.@refill ++ ++@item M-e ++Runs the command @samp{cvs-examine}.@refill ++ ++@item M-s ++Runs the command @samp{cvs-status}.@refill ++@end table ++ ++In addition to the above commands which operate on the whole module, ++you can run the equivalent CVS command on just a subset of the ++files/directories with these keys: ++ ++@table @kbd ++@item O ++Runs @code{cvs-mode-update} on the selected files. When run on the ++top-level directory, this is equivalent to @kbd{M-u}.@refill ++ ++@item e ++Runs @code{cvs-mode-examine} on the selected files. When run on the ++top-level directory, this is equivalent to @kbd{M-e}.@refill ++ ++@findex cvs-status-mode ++@item s ++Runs @code{cvs-mode-status} on the selected files. When run on the ++top-level directory, this is equivalent to @kbd{M-s}, except that ++CVS output will be shown in a @samp{*cvs-info*} buffer that will be ++put in @samp{cvs-status-mode}.@refill ++@end table ++ ++ ++@node Movement commands, Marking files, Updating the buffer, Commands ++@section Movement Commands ++@cindex Movement Commands ++@findex cvs-mode-next-line ++@findex cvs-mode-previous-line ++@kindex SPC@r{--Move down one file} ++@kindex n@r{--Move down one file} ++@kindex p@r{--Move up one file} ++ ++You can use most normal Emacs commands to move forward and backward in ++the buffer. Some keys are rebound to functions that take advantage of ++the fact that the buffer is a PCL-CVS buffer: ++ ++ ++@table @kbd ++@item @key{SPC} ++@itemx n ++These keys move the cursor one file forward, towards the end of the ++buffer (@code{cvs-mode-next-line}).@refill ++ ++@itemx p ++This key moves one file backward, towards the beginning of the buffer ++(@code{cvs-mode-previous-line}). ++@end table ++ ++ ++@node Marking files, Committing changes, Movement commands, Commands ++@section Marking files ++@cindex Selecting files (commands to mark files) ++@cindex Marking files ++@kindex m@r{--marking a file} ++@kindex M@r{--marking all files} ++@kindex u@r{--unmark a file} ++@kindex ESC DEL@r{--unmark all files} ++@kindex DEL@r{--unmark previous file} ++@kindex %@r{--mark files matching regexp} ++@kindex S@r{--mark files in a particular state} ++@kindex T@r{--toggle marks} ++@findex cvs-mode-mark ++@findex cvs-mode-unmark ++@findex cvs-mode-mark-all-files ++@findex cvs-mode-unmark-all-files ++@findex cvs-mode-unmark-up ++@findex cvs-mode-mark-matching-files ++@findex cvs-mode-mark-on-state ++@findex cvs-mode-toggle-marks ++ ++PCL-CVS works on a set of @dfn{selected files} (@pxref{Selected files}). ++You can mark and unmark files with these commands: ++ ++@table @kbd ++@item m ++This marks the file that the cursor is positioned on. If the cursor is ++positioned on a directory all files in that directory are marked ++(@code{cvs-mode-mark}).@refill ++ ++@item u ++Unmark the file that the cursor is positioned on. If the cursor is on a ++directory, all files in that directory are unmarked ++(@code{cvs-mode-unmark}).@refill ++ ++@item M ++Mark @emph{all} files in the buffer (@code{cvs-mode-mark-all-files}). ++ ++@item M-@key{DEL} ++Unmark @emph{all} files (@code{cvs-mode-unmark-all-files}). ++ ++@item @key{DEL} ++Unmark the file on the previous line, and move point to that line ++(@code{cvs-mode-unmark-up}). ++ ++@item % ++Mark all files matching a regular expression ++(@code{cvs-mode-mark-matching-files}). ++ ++@item S ++Mark all files in a particular state, such as ``Modified'' or ++``Removed'' (@code{cvs-mode-mark-on-state}). ++ ++@item T ++Toggle use of marks for the next command (@code{cvs-mode-toggle-marks}). ++@end table ++ ++ ++@node Committing changes, Editing files, Marking files, Commands ++@section Committing changes ++@cindex Committing changes ++@findex cvs-mode-commit ++@findex cvs-mode-commit-setup ++@kindex c@r{--commit files} ++@kindex C@r{--commit files with @file{ChangeLog} message} ++@vindex cvs-auto-revert@r{ (variable)} ++@cindex Commit buffer ++@cindex Edit buffer ++@cindex Erasing commit message ++@cindex Reverting buffers after commit ++ ++Committing changes basically works as follows: ++ ++@enumerate ++@item ++After having selected the files you want to commit, you type either ++@kbd{c} or @kbd{C} which brings up a special buffer ++@samp{*cvs-commit*}.@refill ++ ++@item ++You type in the log message describing the changes you're about to ++commit (@pxref{Log Edit Mode}). ++ ++@item ++When you're happy with it, you type @kbd{C-c C-c} to do the actual ++commit.@refill ++@end enumerate ++ ++There's no hidden state, so you can abort the process or pick it up ++again at any time. ++ ++@vindex log-edit-confirm@r{ (variable)} ++The set of files actually committed is really decided only during the ++very last step, which is a mixed blessing. It allows you to go back and ++change your mind about which files to commit, but it also means that you ++might inadvertently change the set of selected files. To reduce the ++risk of error, @kbd{C-c C-c} will ask for confirmation if the set of ++selected files has changed between the first step and the last. You can ++change this last detail with @code{log-edit-confirm}. ++ ++As for the difference between @kbd{c} (i.e. @code{cvs-mode-commit}) and ++@kbd{C} (i.e. @code{cvs-mode-commit-setup}) is that the first gets you ++straight to @samp{*cvs-commit*} without erasing it or changing anything ++to its content, while the second first erases @samp{*cvs-commit*} ++and tries to initialize it with a sane default (it does that by either ++using a template provided by the CVS administrator or by extracting a ++relevant log message from a @file{ChangeLog} file). ++ ++If you are editing the files in your Emacs, an automatic ++@samp{revert-buffer} will be performed. (If the file contains ++@samp{$@asis{Id}$} keywords, @samp{cvs commit} will write a new file with ++the new values substituted. The auto-revert makes sure that you get ++them into your buffer.) The revert will not occur if you have modified ++your buffer, or if @samp{cvs-auto-revert} is set to ++@samp{nil}. ++ ++ ++@node Editing files, Getting info about files, Committing changes, Commands ++@section Editing files ++@cindex Editing files ++@cindex Finding files ++@cindex Loading files ++@cindex Dired ++@cindex Invoking dired ++@findex cvs-mode-find-file ++@findex cvs-mode-find-file-other-window ++@findex cvs-mode-add-change-log-entry-other-window ++@kindex f@r{--find file or directory} ++@kindex o@r{--find file in other window} ++@kindex A@r{--add @file{ChangeLog} entry} ++ ++There are currently three commands that can be used to find a file (that ++is, load it into a buffer and start editing it there). These commands ++work on the line that the cursor is situated at. They always ignore any marked ++files. ++ ++@table @kbd ++@item f ++Find the file that the cursor points to (@code{cvs-mode-find-file}). If ++the cursor points to a directory, run @code{dired} on that directory; ++@inforef{Dired, , emacs}. ++ ++@item o ++Like @kbd{f}, but use another window ++(@code{cvs-mode-find-file-other-window}).@refill ++ ++@item A ++Invoke @samp{add-change-log-entry-other-window} to edit a ++@file{ChangeLog} file. The @file{ChangeLog} file will be found in the ++directory of the file the cursor points to, or in a parent of that ++directory (@code{cvs-mode-add-change-log-entry-other-window}).@refill ++@end table ++ ++ ++@node Getting info about files, Adding and removing files, Editing files, Commands ++@section Getting info about files ++@cindex Status (cvs command) ++@cindex Log (RCS/cvs command) ++@cindex Getting status ++@kindex l@r{--run @samp{cvs log}} ++@kindex s@r{--run @samp{cvs status}} ++@findex cvs-mode-log ++@findex cvs-mode-status ++ ++@table @kbd ++@item l ++Call the command @code{cvs-mode-log} which runs @samp{cvs log} on all ++selected files, and show the result in a temporary buffer ++@samp{*cvs-info*} (@pxref{Log View Mode}). ++ ++@item s ++Call the command @code{cvs-mode-status} which runs @samp{cvs status} on ++all selected files, and show the result in a temporary buffer ++@samp{*cvs-info*}. ++@c Fixme: reinstate when node is written: ++@c (@pxref{CVS Status Mode}). ++@end table ++ ++ ++@node Adding and removing files, Undoing changes, Getting info about files, Commands ++@section Adding and removing files ++@cindex Adding files ++@cindex Removing files ++@cindex Resurrecting files ++@cindex Deleting files ++@cindex Putting files under CVS control ++@kindex a@r{--add a file} ++@kindex r@r{--remove a file} ++@findex cvs-mode-add ++@findex cvs-mode-remove-file ++ ++The following commands are available to make it easy to add files to ++and remove them from the CVS repository. ++ ++@table @kbd ++@item a ++Add all selected files. This command can be used on @samp{Unknown} ++files (@pxref{Buffer contents}). The status of the file will change to ++@samp{Added}, and you will have to use @kbd{c} (@samp{cvs-mode-commit} ++@pxref{Committing changes}), to really add the file to the ++repository.@refill ++ ++This command can also be used on @samp{Removed} files (before you commit ++them) to resurrect them. ++ ++The command that is run is @code{cvs-mode-add}. ++ ++@item r ++This command removes the selected files (after prompting for ++confirmation). The files are deleted from your directory and ++(unless the status was @samp{Unknown}; @pxref{Buffer contents}) they will ++also be @samp{cvs remove}d. If the files' status was @samp{Unknown} ++they will disappear from the buffer. Otherwise their status will change to ++@samp{Removed}, and you must use @kbd{c} (@samp{cvs-mode-commit}, ++@pxref{Committing changes}) to commit the removal.@refill ++ ++The command that is run is @code{cvs-mode-remove-file}. ++@end table ++ ++ ++@node Undoing changes, Removing handled entries, Adding and removing files, Commands ++@section Undoing changes ++@cindex Undo changes ++@cindex Flush changes ++@kindex U@r{--undo changes} ++@findex cvs-mode-undo-local-changes ++ ++@table @kbd ++@item U ++If you have modified a file, and for some reason decide that you don't ++want to keep the changes, you can undo them with this command. It works ++by removing your working copy of the file and then getting the latest ++version from the repository (@code{cvs-mode-undo-local-changes}). ++@end table ++ ++ ++@node Removing handled entries, Ignoring files, Undoing changes, Commands ++@section Removing handled entries ++@cindex Expunging uninteresting entries ++@cindex Uninteresting entries, getting rid of them ++@cindex Getting rid of uninteresting lines ++@cindex Removing uninteresting (processed) lines ++@cindex Handled lines, removing them ++@kindex x@r{--remove processed entries} ++@kindex C-k@r{--remove selected entries} ++@findex cvs-mode-remove-handled ++@findex cvs-mode-acknowledge ++@findex cvs-mode-ignore ++ ++@table @kbd ++@item x ++This command allows you to remove all entries that you have processed. ++More specifically, the lines for @samp{Up-to-date} files (@pxref{Buffer ++contents}) are removed from the buffer. If a directory becomes empty ++the heading for that directory is also removed. This makes it easier to ++get an overview of what needs to be done. ++ ++@vindex cvs-mode-remove-handled@r{ (variable)} ++@kbd{x} invokes @code{cvs-mode-remove-handled}. If ++@samp{cvs-auto-remove-handled} is set to non-@code{nil}, this will ++automatically be performed after every commit.@refill ++ ++@item C-k ++This command can be used for lines that @samp{cvs-mode-remove-handled} would ++not delete, but that you want to delete (@code{cvs-mode-acknowledge}). ++@end table ++ ++ ++@node Ignoring files, Viewing differences, Removing handled entries, Commands ++@section Ignoring files ++@cindex Ignoring files ++@kindex i@r{--ignoring files} ++@findex cvs-mode-ignore ++ ++@table @kbd ++@item i ++Arrange so that CVS will ignore the selected files. The file names are ++added to the @file{.cvsignore} file in the corresponding directory. If ++the @file{.cvsignore} file doesn't exist, it will be created. ++ ++The @file{.cvsignore} file should normally be added to the repository, ++but you could ignore it as well, if you like it better that way. ++ ++This runs @code{cvs-mode-ignore}. ++@end table ++ ++@node Viewing differences, Invoking Ediff, Ignoring files, Commands ++@section Viewing differences ++@cindex Diff ++@cindex Invoking @code{diff} ++@cindex Conflicts, how to resolve them ++@cindex Viewing differences ++@kindex d=@r{--run @samp{cvs diff}} ++@kindex =@r{--run @samp{cvs diff}} ++@kindex db@r{--diff against base version} ++@kindex dh@r{--diff against head of repository} ++@kindex dr@r{--diff between base and head of repository} ++@kindex dv@r{--diff against vendor branch} ++@kindex dy@r{--diff against yesterday's head} ++@findex cvs-mode-diff ++@findex cvs-mode-diff-backup ++@findex cvs-mode-diff-head ++@findex cvs-mode-diff-repository ++@findex cvs-mode-diff-vendor ++@findex cvs-mode-diff-yesterday ++@vindex cvs-invert-ignore-marks@r{ (variable)} ++ ++@table @kbd ++@item = ++@itemx d = ++Display a @samp{cvs diff} between the selected files and the version ++that they are based on (@code{cvs-mode-diff}).@refill ++ ++@item d b ++If CVS finds a conflict while merging two versions of a file (during a ++@samp{cvs update}, @pxref{Updating the buffer}) it will save the ++original file in a file called @file{.#@var{file}.@var{version}} where ++@var{file} is the name of the file, and @var{version} is the revision ++number that @var{file} was based on.@refill ++ ++With the @kbd{d b} command you can run a @samp{diff} on the files ++@file{.#@var{file}.@var{version}} and @file{@var{file}}.@refill ++ ++@item d h ++Display a @samp{cvs diff} between the selected files and the head ++revision (the most recent version on the current ++branch) in the repository (@code{cvs-mode-diff-head}).@refill ++ ++@item d r ++Display a @samp{cvs diff} between the base revision of the selected ++files and the head revision in the repository. This displays the ++changes anyone has committed to the repository since you last executed ++a checkout, update or commit operation ++(@code{cvs-mode-diff-repository}). ++ ++@item d v ++Display a @samp{cvs diff} between the selected files and the head ++revision of the vendor branch in the repository ++(@code{cvs-mode-diff-vendor}).@refill ++ ++@item d y ++Display a @samp{cvs diff} between the selected files and yesterday's ++head revision in the repository ++(@code{cvs-mode-diff-yesterday}).@refill ++@end table ++ ++By default, @samp{diff} commands ignore the marks. This can be changed ++with @code{cvs-invert-ignore-marks}. ++ ++@node Invoking Ediff, Updating files, Viewing differences, Commands ++@section Running ediff ++@cindex Ediff ++@cindex Invoking ediff ++@cindex Viewing differences ++@cindex Conflicts, how to resolve them ++@cindex Resolving conflicts ++@kindex e@r{--invoke @samp{ediff}} ++@findex cvs-mode-idiff ++@findex cvs-mode-imerge ++ ++@table @kbd ++@vindex cvs-idiff-imerge-handlers@r{ (variable)} ++@item d e ++This uses @code{ediff} (or @code{emerge}, depending on ++@samp{cvs-idiff-imerge-handlers}) to allow you to view diffs. ++If a prefix argument is given, PCL-CVS will prompt for a revision against ++which the diff should be made, else the default will be to use the BASE ++revision. ++ ++@cindex Merging with @code{ediff} and @code{emerge} ++@item d E ++This command use @code{ediff} (or @code{emerge}, see above) to allow you ++to do an interactive 3-way merge. ++ ++@strong{Please note:} when the file status is @samp{Conflict}, ++CVS has already performed a merge. The resulting file is not used in ++any way if you use this command. If you use the @kbd{q} command inside ++@samp{ediff} (to successfully terminate a merge) the file that CVS ++created will be overwritten.@refill ++@end table ++ ++@node Updating files, Tagging files, Invoking Ediff, Commands ++@section Updating files ++@findex cvs-mode-update ++@cindex Updating files ++@kindex O@r{--update files} ++ ++@table @kbd ++@item O ++Update all selected files with status @samp{Need-update} by running ++@samp{cvs update} on them (@code{cvs-mode-update}). ++@end table ++ ++ ++@node Tagging files, Miscellaneous commands, Updating files, Commands ++@section Tagging files ++@findex cvs-mode-tag ++@findex cvs-mode-untag ++@findex cvs-rtag ++@cindex Tagging files ++@kindex M-t@r{--repository tag files} ++@kindex t@r{--tag files} ++@vindex cvs-invert-ignore-marks@r{ (variable)} ++@vindex cvs-force-dir-tag@r{ (variable)} ++ ++@table @kbd ++@item t ++Tag all selected files by running @samp{cvs tag} on ++them (@code{cvs-mode-tag}). It's usually preferable to tag a directory ++at a time. Rather than selecting all files (which too often doesn't ++select all files but only the few that are displayed), clear the ++selection with @kbd{M-DEL} (@code{cvs-mode-unmark-all-files}), position ++the cursor on the directory you want to tag and hit @kbd{t}. ++@end table ++ ++By default, @samp{tag} commands ignore the marks. This can be changed ++with @code{cvs-invert-ignore-marks}. Also, by default @samp{tag} can ++only be applied to directories, see @code{cvs-force-dir-tag} if you want ++to change this behavior. ++ ++ ++@node Miscellaneous commands, , Tagging files, Commands ++@section Miscellaneous commands ++@findex cvs-mode-byte-compile-files ++@cindex Recompiling elisp files ++@cindex Byte compilation ++@findex cvs-mode-delete-lock ++@cindex Getting rid of lock files ++@cindex Lock files ++@kindex q@r{--bury the PCL-CVS buffer} ++@findex cvs-bury-buffer ++@findex cvs-mode-quit ++@cindex Quitting ++@kindex h@r{--help} ++@kindex ?@r{--help} ++@findex cvs-help ++@cindex Help ++ ++@table @kbd ++@item M-x cvs-mode-byte-compile-files ++Byte compile all selected files that end in @file{.el}. ++ ++@item M-x cvs-mode-delete-lock ++This command deletes the lock files that ++the @samp{*cvs*} buffer informs you about. You should normally never have to ++use this command, since CVS tries very carefully to always remove the ++lock files itself. ++ ++You can only use this command when a message in the @samp{*cvs*} buffer tells ++you so. You should wait a while before using this command in case ++someone else is running a @code{cvs} command. ++ ++Also note that this only works if the repository is local. ++ ++@item ? ++@itemx h ++Show a summary of common command key bindings in the echo ++area (@code{cvs-help}). ++ ++@item q ++Bury the PCL-CVS buffer (@code{cvs-bury-buffer}). ++ ++@item M-x cvs-mode-quit ++Quit PCL-CVS, killing the @samp{*cvs*} buffer. ++@end table ++ ++@node Log Edit Mode, Log View Mode, Commands, Top ++@chapter Editing a Log Message ++ ++@cindex Log Edit mode ++@cindex mode, Log Edit ++Buffers for entering/editing log messages for changes which are about ++to be committed are put into Log Edit mode. ++ ++Sometimes the log buffer contains default text when you enter it, ++typically the last log message entered. If it does, mark and point ++are set around the entire contents of the buffer so that it is easy to ++kill the contents of the buffer with @kbd{C-w}. ++ ++@findex log-edit-insert-changelog ++If you work by writing entries in the @file{ChangeLog} ++(@pxref{(emacs)Change Log}) and then commit the change under revision ++control, you can generate the Log Edit text from the ChangeLog using ++@kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for ++entries for the file(s) concerned in the top entry in the ChangeLog ++and uses those paragraphs as the log text. This text is only inserted ++if the top entry was made under your user name on the current date. ++@xref{(emacs)Change Logs and VC}, for the opposite way of ++working---generating ChangeLog entries from the revision control log. ++ ++In the Log Edit buffer, @kbd{C-c C-f} (@kbd{M-x log-edit-show-files}) ++shows the list of files to be committed in case you need to check ++that. ++ ++When you have finished editing the log message, type @kbd{C-c C-c} to ++exit the buffer and commit the change. ++ ++@c Fixme: customization variables ++ ++@node Log View Mode, Customization, Log Edit Mode, Top ++@chapter Browsing a Log of Changes ++ ++@cindex Log View mode ++@cindex mode, Log View ++@cindex output, logs ++ ++@findex cvs-mode-log ++@findex vc-print-log ++Log View mode provides a few useful commands for navigating revision ++control log output. It is used for the output buffers of both ++@code{cvs-mode-log} and @code{vc-print-log}. ++ ++In this mode, @kbd{n} goes to the next message and @kbd{p} goes to the ++previous message and @kbd{N} and @kbd{P} go to the next and previous ++files, respectively, in multi-file output. With a numeric prefix ++argument, these commands move that many messages of files. ++ ++@c @node CVS Status Mode ++@c @chapter Viewing CVS' Status output ++ ++@node Customization, Bugs, Log View Mode, Top ++@chapter Customization ++@vindex log-edit-changelog-full-paragraphs@r{ (variable)} ++@vindex cvs-auto-remove-handled@r{ (variable)} ++@vindex cvs-auto-remove-directories@r{ (variable)} ++@vindex cvs-update-prog-output-skip-regexp@r{ (variable)} ++@vindex cvs-cvsroot@r{ (variable)} ++@vindex cvs-auto-revert@r{ (variable)} ++@vindex log-edit-require-final-newline@r{ (variable)} ++@vindex cvs-sort-ignore-file@r{ (variable)} ++@cindex Customization ++@cindex Variables, list of all ++@cindex Erasing input buffer ++@cindex Context diff, how to get ++@cindex Unidiff, how to get ++@cindex Automatically remove handled files ++@cindex @samp{-u} option in modules file ++@cindex Modules file (@samp{-u} option) ++@cindex Update program (@samp{-u} option in modules file) ++@cindex Reverting buffers after commit ++@cindex Require final newline ++@cindex Automatically inserting newline ++@cindex Commit message, inserting newline ++@cindex Sorting @file{.cvsignore} file ++@cindex @file{.cvsignore} file, sorting ++@cindex Automatically sorting @file{.cvsignore} ++@cindex @samp{CVSROOT}, overriding ++ ++If you have an idea about any customization that would be handy but ++isn't present in this list, please tell us! ++For info on how to reach us, see @ref{Bugs}.@refill ++ ++@table @samp ++@item cvs-auto-remove-handled ++If this variable is set to any non-@code{nil} value, ++@samp{cvs-mode-remove-handled} will be called every time you check in ++files, after the check-in is ready. @xref{Removing handled ++entries}.@refill ++ ++@item cvs-auto-remove-directories ++If this variable is set to any non-@code{nil} value, directories that do ++not contain any files to be checked in will not be listed in the ++@samp{*cvs*} buffer.@refill ++ ++@item cvs-auto-revert ++If this variable is set to any non-@samp{nil} value any buffers you have ++that visit a file that is committed will be automatically reverted. ++This variable defaults to @samp{t}. @xref{Committing changes}.@refill ++ ++@item cvs-update-prog-output-skip-regexp ++The @samp{-u} flag in the @file{modules} file can be used to run a command ++whenever a @samp{cvs update} is performed (see @code{cvs(5)}). This regexp ++is used to search for the last line in that output. It is normally set ++to @samp{$}. That setting is only correct if the command outputs ++nothing. Note that PCL-CVS will get very confused if the command ++outputs @emph{anything} to @code{stderr}. ++ ++@item cvs-cvsroot ++This variable can be set to override @samp{CVSROOT}. It should be a ++string. If it is set, then every time a @code{cvs} command is run, it ++will be called as @samp{cvs -d @var{cvs-cvsroot}@dots{}}. This can be ++useful if your site has several repositories. ++ ++@item log-edit-require-final-newline ++@c wordy to avoid unhderfull hbox ++When you enter a log message by typing into the ++@samp{*cvs-commit-message*} buffer, PCL-CVS normally automatically ++inserts a trailing newline, unless there already is one. This behavior ++can be controlled via @samp{cvs-commit-buffer-require-final-newline}. ++If it is @samp{t} (the default behavior), a newline will always be ++appended. If it is @samp{nil}, newlines will never be appended. Any ++other value causes PCL-CVS to ask the user whenever there is no trailing ++newline in the commit message buffer. ++ ++@findex cvs-mode-changelog-commit ++@item log-edit-changelog-full-paragraphs ++If this variable is non-@code{nil}, include full @file{ChangeLog} ++paragraphs in the CVS log created by @samp{cvs-mode-changelog-commit}. ++This may be set in the local variables section of a @file{ChangeLog} ++file, to indicate the policy for that @file{ChangeLog}. ++ ++@cindex @file{ChangeLog} paragraphs ++A @dfn{@file{ChangeLog} paragraph} is a bunch of log text containing no ++blank lines; a paragraph usually describes a set of changes with a ++single purpose, but perhaps spanning several functions in several files. ++Changes in different paragraphs are unrelated. ++ ++You could argue that the CVS log entry for a file should contain the ++full @file{ChangeLog} paragraph mentioning the change to the file, even though ++it may mention other files, because that gives you the full context you ++need to understand the change. This is the behavior you get when this ++variable is set to @code{t}, the default. ++ ++On the other hand, you could argue that the CVS log entry for a change ++should contain only the text for the changes which occurred in that ++file, because the CVS log is per-file. This is the behavior you get ++when this variable is set to @code{nil}. ++ ++@findex cvs-mode-ignore@r{, and @file{.cvsignore} sorting} ++@item cvs-sort-ignore-file ++If this variable is set to any non-@samp{nil} value, the ++@file{.cvsignore} file will always be sorted whenever you use ++@samp{cvs-mode-ignore} to add a file to it. This option is on by ++default. ++@end table ++ ++ ++@menu ++* Customizing Faces:: ++@end menu ++ ++@node Customizing Faces, , Customization, Customization ++@section Customizing Faces ++@vindex cvs-header (face) ++@vindex cvs-filename (face) ++@vindex cvs-unknown (face) ++@vindex cvs-handled (face) ++@vindex cvs-need-action (face) ++@vindex cvs-marked (face) ++@vindex cvs-msg (face) ++ ++PCL-CVS adds a few extra features, including menus, mouse bindings, and ++fontification of the @samp{*cvs*} buffer. The faces defined for ++fontification are listed below: ++ ++@table @samp ++@item cvs-header ++used to highlight directory changes. ++ ++@item cvs-filename ++Used to highlight file names. ++ ++@item cvs-unknown ++Used to highlight the status of files which are @samp{Unknown}. ++ ++@item cvs-handled ++Used to highlight the status of files which are handled and ++need no further action. ++ ++@item cvs-need-action ++Used to highlight the status of files which still need action. ++ ++@item cvs-marked ++Used to highlight the marked file indicator (@samp{*}). ++ ++@item cvs-msg ++Used to highlight CVS messages. ++@end table ++ ++ ++@node Bugs, GNU Free Documentation License, Customization, Top ++@chapter Bugs (known and unknown) ++@cindex Reporting bugs and ideas ++@cindex Bugs, how to report them ++@cindex Author, how to reach ++@cindex Email to the author ++@cindex Known bugs ++@cindex Bugs, known ++@cindex FAQ ++@cindex Problems, list of common ++ ++If you find a bug or misfeature, don't hesitate to tell us! Send email ++to @email{bug-gnu-emacs@@gnu.org} which is gatewayed to the newsgroup ++@samp{gnu.emacs.bugs}. Feature requests should also be sent there. We ++prefer discussing one thing at a time. If you find several unrelated ++bugs, please report them separately. If you are running PCL-CVS under ++XEmacs, you should also send a copy of bug reports to ++@email{xemacs-beta@@xemacs.org}. ++ ++If you have problems using PCL-CVS or other questions, send them to ++@email{help-gnu-emacs@@gnu.org}, which is gatewayed to the ++@samp{gnu.emacs.help} newsgroup. This is a good place to get help, as ++is @email{cvs-info@@gnu.org}, gatewayed to @samp{gnu.cvs.help}. ++ ++If you have ideas for improvements, or if you have written some ++extensions to this package, we would like to hear from you. We hope that ++you find this package useful! ++ ++Below is a partial list of currently known problems with PCL-CVS. ++ ++@table @asis ++@item Unexpected output from CVS ++Unexpected output from CVS may confuse PCL-CVS. It will create ++warning messages in the @samp{*cvs*} buffer alerting you to any parse errors. ++If you get these messages, please send a bug report to the email ++addresses listed above. Include the contents of the @samp{*cvs*} buffer, the ++output of the CVS process (which should be found in the @samp{ *cvs-tmp*} ++buffer), and the versions of Emacs, PCL-CVS and CVS you are using. ++@end table ++ ++@node GNU Free Documentation License, Function and Variable Index, Bugs, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++ ++ ++@node Function and Variable Index, Concept Index, GNU Free Documentation License, Top ++@unnumbered Function and Variable Index ++ ++This is an index of all the functions and variables documented in this ++manual. ++ ++@printindex fn ++ ++@node Concept Index, Key Index, Function and Variable Index, Top ++@unnumbered Concept Index ++ ++This is an index of concepts discussed in this manual. ++ ++@printindex cp ++ ++@node Key Index, , Concept Index, Top ++@unnumbered Key Index ++ ++This index includes an entry for each PCL-CVS key sequence documented in ++this manual. ++ ++@printindex ky ++ ++@bye ++ ++@ignore ++ arch-tag: 5c7178ce-56fa-40b0-abd7-f4a09758b235 ++@end ignore +diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi +new file mode 100644 +index 0000000..11b0392 +--- /dev/null ++++ b/doc/misc/pgg.texi +@@ -0,0 +1,503 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/pgg ++@settitle PGG @value{VERSION} ++ ++@set VERSION 0.1 ++ ++@copying ++This file describes PGG @value{VERSION}, an Emacs interface to various ++PGP implementations. ++ ++Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++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 Emacs ++@direntry ++* PGG: (pgg). Emacs interface to various PGP implementations. ++@end direntry ++ ++@titlepage ++@title PGG ++ ++@author by Daiki Ueno ++@page ++ ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top ++@top PGG ++ ++PGG is an interface library between Emacs ++and various tools for secure communication. PGG also provides a simple ++user interface to encrypt, decrypt, sign, and verify MIME messages. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview:: What PGG is. ++* Prerequisites:: Complicated stuff you may have to do. ++* How to use:: Getting started quickly. ++* Architecture:: ++* Parsing OpenPGP packets:: ++* GNU Free Documentation License:: The license for this documentation. ++* Function Index:: ++* Variable Index:: ++@end menu ++ ++@node Overview ++@chapter Overview ++ ++PGG is an interface library between Emacs and various tools for secure ++communication. Even though Mailcrypt has similar feature, it does not ++deal with detached PGP messages, normally used in PGP/MIME ++infrastructure. This was the main reason why I wrote the new library. ++ ++PGP/MIME is an application of MIME Object Security Services (RFC1848). ++The standard is documented in RFC2015. ++ ++@node Prerequisites ++@chapter Prerequisites ++ ++PGG requires at least one implementation of privacy guard system. ++This document assumes that you have already obtained and installed them ++and that you are familiar with its basic functions. ++ ++By default, PGG uses GnuPG. If you are new to such a system, I ++recommend that you should look over the GNU Privacy Handbook (GPH) ++which is available at @uref{http://www.gnupg.org/documentation/}. ++ ++When using GnuPG, we recommend the use of the @code{gpg-agent} ++program, which is distributed with versions 2.0 and later of GnuPG. ++This is a daemon to manage private keys independently from any ++protocol, and provides the most secure way to input and cache your ++passphrases (@pxref{Caching passphrase}). By default, PGG will ++attempt to use @code{gpg-agent} if it is running. @xref{Invoking ++GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}. ++ ++PGG also supports Pretty Good Privacy version 2 or version 5. ++ ++@node How to use ++@chapter How to use ++ ++The toplevel interface of this library is quite simple, and only ++intended to use with public-key cryptographic operation. ++ ++To use PGG, evaluate following expression at the beginning of your ++application program. ++ ++@lisp ++(require 'pgg) ++@end lisp ++ ++If you want to check existence of pgg.el at runtime, instead you can ++list autoload setting for desired functions as follows. ++ ++@lisp ++(autoload 'pgg-encrypt-region "pgg" ++ "Encrypt the current region." t) ++(autoload 'pgg-encrypt-symmetric-region "pgg" ++ "Encrypt the current region with symmetric algorithm." t) ++(autoload 'pgg-decrypt-region "pgg" ++ "Decrypt the current region." t) ++(autoload 'pgg-sign-region "pgg" ++ "Sign the current region." t) ++(autoload 'pgg-verify-region "pgg" ++ "Verify the current region." t) ++(autoload 'pgg-insert-key "pgg" ++ "Insert the ASCII armored public key." t) ++(autoload 'pgg-snarf-keys-region "pgg" ++ "Import public keys in the current region." t) ++@end lisp ++ ++@menu ++* User Commands:: ++* Selecting an implementation:: ++* Caching passphrase:: ++* Default user identity:: ++@end menu ++ ++@node User Commands ++@section User Commands ++ ++At this time you can use some cryptographic commands. The behavior of ++these commands relies on a fashion of invocation because they are also ++intended to be used as library functions. In case you don't have the ++signer's public key, for example, the function @code{pgg-verify-region} ++fails immediately, but if the function had been called interactively, it ++would ask you to retrieve the signer's public key from the server. ++ ++@deffn Command pgg-encrypt-region start end recipients &optional sign passphrase ++Encrypt the current region between @var{start} and @var{end} for ++@var{recipients}. When the function were called interactively, you ++would be asked about the recipients. ++ ++If encryption is successful, it replaces the current region contents (in ++the accessible portion) with the resulting data. ++ ++If optional argument @var{sign} is non-@code{nil}, the function is ++request to do a combined sign and encrypt. This currently is ++confirmed to work with GnuPG, but might not work with PGP or PGP5. ++ ++If optional @var{passphrase} is @code{nil}, the passphrase will be ++obtained from the passphrase cache or user. ++@end deffn ++ ++@deffn Command pgg-encrypt-symmetric-region &optional start end passphrase ++Encrypt the current region between @var{start} and @var{end} using a ++symmetric cipher. After invocation you are asked for a passphrase. ++ ++If optional @var{passphrase} is @code{nil}, the passphrase will be ++obtained from the passphrase cache or user. ++ ++symmetric-cipher encryption is currently only implemented for GnuPG. ++@end deffn ++ ++@deffn Command pgg-decrypt-region start end &optional passphrase ++Decrypt the current region between @var{start} and @var{end}. If ++decryption is successful, it replaces the current region contents (in ++the accessible portion) with the resulting data. ++ ++If optional @var{passphrase} is @code{nil}, the passphrase will be ++obtained from the passphrase cache or user. ++@end deffn ++ ++@deffn Command pgg-sign-region start end &optional cleartext passphrase ++Make the signature from text between @var{start} and @var{end}. If the ++optional third argument @var{cleartext} is non-@code{nil}, or the ++function is called interactively, it does not create a detached ++signature. In such a case, it replaces the current region contents (in ++the accessible portion) with the resulting data. ++ ++If optional @var{passphrase} is @code{nil}, the passphrase will be ++obtained from the passphrase cache or user. ++@end deffn ++ ++@deffn Command pgg-verify-region start end &optional signature fetch ++Verify the current region between @var{start} and @var{end}. If the ++optional third argument @var{signature} is non-@code{nil}, it is treated ++as the detached signature file of the current region. ++ ++If the optional 4th argument @var{fetch} is non-@code{nil}, or the ++function is called interactively, we attempt to fetch the signer's ++public key from the key server. ++@end deffn ++ ++@deffn Command pgg-insert-key ++Retrieve the user's public key and insert it as ASCII-armored format. ++@end deffn ++ ++@deffn Command pgg-snarf-keys-region start end ++Collect public keys in the current region between @var{start} and ++@var{end}, and add them into the user's keyring. ++@end deffn ++ ++@node Selecting an implementation ++@section Selecting an implementation ++ ++Since PGP has a long history and there are a number of PGP ++implementations available today, the function which each one has differs ++considerably. For example, if you are using GnuPG, you know you can ++select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on ++the other hand the version 2 of PGP only supports IDEA. ++ ++Which implementation is used is controlled by the @code{pgg-scheme} ++variable. If it is @code{nil} (the default), the value of the ++@code{pgg-default-scheme} variable will be used instead. ++ ++@defvar pgg-scheme ++Force specify the scheme of PGP implementation. The value can be set to ++@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}. ++@end defvar ++ ++@defvar pgg-default-scheme ++The default scheme of PGP implementation. The value should be one of ++@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}. ++@end defvar ++ ++@node Caching passphrase ++@section Caching passphrase ++ ++When using GnuPG (gpg) as the PGP scheme, we recommend using a program ++called @code{gpg-agent} for entering and caching ++passphrases@footnote{Actually, @code{gpg-agent} does not cache ++passphrases but private keys. On the other hand, from a user's point ++of view, this technical difference isn't visible.}. ++ ++@defvar pgg-gpg-use-agent ++If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible. ++The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG ++is not the current PGP scheme, PGG's own passphrase-caching mechanism ++is used (see below). ++@end defvar ++ ++To use @code{gpg-agent} with PGG, you must first ensure that ++@code{gpg-agent} is running. For example, if you are running in the X ++Window System, you can do this by putting the following line in your ++@file{.xsession} file: ++ ++@smallexample ++eval "$(gpg-agent --daemon)" ++@end smallexample ++ ++For more details on invoking @code{gpg-agent}, @xref{Invoking ++GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}. ++ ++Whenever you perform a PGG operation that requires a GnuPG passphrase, ++GnuPG will contact @code{gpg-agent}, which prompts you for the ++passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so ++that subsequent uses will not require you to enter the passphrase ++again. (This cache usually expires after a certain time has passed; ++you can change this using the @code{--default-cache-ttl} option when ++invoking @code{gpg-agent}.) ++ ++If you are running in a X Window System environment, @code{gpg-agent} ++prompts for a passphrase by opening a graphical window. However, if ++you are running Emacs on a text terminal, @code{gpg-agent} has trouble ++receiving input from the terminal, since it is being sent to Emacs. ++One workaround for this problem is to run @code{gpg-agent} on a ++different terminal from Emacs, with the @code{--keep-tty} option; this ++tells @code{gpg-agent} use its own terminal to prompt for passphrases. ++ ++When @code{gpg-agent} is not being used, PGG prompts for a passphrase ++through Emacs. It also has its own passphrase caching mechanism, ++which is controlled by the variable @code{pgg-cache-passphrase} (see ++below). ++ ++There is a security risk in handling passphrases through PGG rather ++than @code{gpg-agent}. When you enter your passphrase into an Emacs ++prompt, it is temporarily stored as a cleartext string in the memory ++of the Emacs executable. If the executable memory is swapped to disk, ++the root user can, in theory, extract the passphrase from the ++swapfile. Furthermore, the swapfile containing the cleartext ++passphrase might remain on the disk after the system is discarded or ++stolen. @code{gpg-agent} avoids this problem by using certain tricks, ++such as memory locking, which have not been implemented in Emacs. ++ ++@defvar pgg-cache-passphrase ++If non-@code{nil}, store passphrases. The default value of this ++variable is @code{t}. If you are worried about security issues, ++however, you could stop the caching of passphrases by setting this ++variable to @code{nil}. ++@end defvar ++ ++@defvar pgg-passphrase-cache-expiry ++Elapsed time for expiration in seconds. ++@end defvar ++ ++If your passphrase contains non-ASCII characters, you might need to ++specify the coding system to be used to encode your passphrases, since ++GnuPG treats them as a byte sequence, not as a character sequence. ++ ++@defvar pgg-passphrase-coding-system ++Coding system used to encode passphrase. ++@end defvar ++ ++@node Default user identity ++@section Default user identity ++ ++The PGP implementation is usually able to select the proper key to use ++for signing and decryption, but if you have more than one key, you may ++need to specify the key id to use. ++ ++@defvar pgg-default-user-id ++User ID of your default identity. It defaults to the value returned ++by @samp{(user-login-name)}. You can customize this variable. ++@end defvar ++ ++@defvar pgg-gpg-user-id ++User ID of the GnuPG default identity. It defaults to @samp{nil}. ++This overrides @samp{pgg-default-user-id}. You can customize this ++variable. ++@end defvar ++ ++@defvar pgg-pgp-user-id ++User ID of the PGP 2.x/6.x default identity. It defaults to ++@samp{nil}. This overrides @samp{pgg-default-user-id}. You can ++customize this variable. ++@end defvar ++ ++@defvar pgg-pgp5-user-id ++User ID of the PGP 5.x default identity. It defaults to @samp{nil}. ++This overrides @samp{pgg-default-user-id}. You can customize this ++variable. ++@end defvar ++ ++@node Architecture ++@chapter Architecture ++ ++PGG introduces the notion of a "scheme of PGP implementation" (used ++interchangeably with "scheme" in this document). This term refers to a ++singleton object wrapped with the luna object system. ++ ++Since PGG was designed for accessing and developing PGP functionality, ++the architecture had to be designed not just for interoperability but ++also for extensiblity. In this chapter we explore the architecture ++while finding out how to write the PGG back end. ++ ++@menu ++* Initializing:: ++* Back end methods:: ++* Getting output:: ++@end menu ++ ++@node Initializing ++@section Initializing ++ ++A scheme must be initialized before it is used. ++It had better guarantee to keep only one instance of a scheme. ++ ++The following code is snipped out of @file{pgg-gpg.el}. Once an ++instance of @code{pgg-gpg} scheme is initialized, it's stored to the ++variable @code{pgg-scheme-gpg-instance} and will be reused from now on. ++ ++@lisp ++(defvar pgg-scheme-gpg-instance nil) ++ ++(defun pgg-make-scheme-gpg () ++ (or pgg-scheme-gpg-instance ++ (setq pgg-scheme-gpg-instance ++ (luna-make-entity 'pgg-scheme-gpg)))) ++@end lisp ++ ++The name of the function must follow the ++regulation---@code{pgg-make-scheme-} follows the back end name. ++ ++@node Back end methods ++@section Back end methods ++ ++In each back end, these methods must be present. The output of these ++methods is stored in special buffers (@ref{Getting output}), so that ++these methods must tell the status of the execution. ++ ++@deffn Method pgg-scheme-lookup-key scheme string &optional type ++Return keys associated with @var{string}. If the optional third ++argument @var{type} is non-@code{nil}, it searches from the secret ++keyrings. ++@end deffn ++ ++@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase ++Encrypt the current region between @var{start} and @var{end} for ++@var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign ++and encrypt. If encryption is successful, it returns @code{t}, ++otherwise @code{nil}. ++@end deffn ++ ++@deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase ++Encrypt the current region between @var{start} and @var{end} using a ++symmetric cipher and a passphrases. If encryption is successful, it ++returns @code{t}, otherwise @code{nil}. This function is currently only ++implemented for GnuPG. ++@end deffn ++ ++@deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase ++Decrypt the current region between @var{start} and @var{end}. If ++decryption is successful, it returns @code{t}, otherwise @code{nil}. ++@end deffn ++ ++@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase ++Make the signature from text between @var{start} and @var{end}. If the ++optional third argument @var{cleartext} is non-@code{nil}, it does not ++create a detached signature. If signing is successful, it returns ++@code{t}, otherwise @code{nil}. ++@end deffn ++ ++@deffn Method pgg-scheme-verify-region scheme start end &optional signature ++Verify the current region between @var{start} and @var{end}. If the ++optional third argument @var{signature} is non-@code{nil}, it is treated ++as the detached signature of the current region. If the signature is ++successfully verified, it returns @code{t}, otherwise @code{nil}. ++@end deffn ++ ++@deffn Method pgg-scheme-insert-key scheme ++Retrieve the user's public key and insert it as ASCII-armored format. ++On success, it returns @code{t}, otherwise @code{nil}. ++@end deffn ++ ++@deffn Method pgg-scheme-snarf-keys-region scheme start end ++Collect public keys in the current region between @var{start} and ++@var{end}, and add them into the user's keyring. ++On success, it returns @code{t}, otherwise @code{nil}. ++@end deffn ++ ++@node Getting output ++@section Getting output ++ ++The output of the back end methods (@ref{Back end methods}) is stored in ++special buffers, so that these methods must tell the status of the ++execution. ++ ++@defvar pgg-errors-buffer ++The standard error output of the execution of the PGP command is stored ++here. ++@end defvar ++ ++@defvar pgg-output-buffer ++The standard output of the execution of the PGP command is stored here. ++@end defvar ++ ++@defvar pgg-status-buffer ++The rest of status information of the execution of the PGP command is ++stored here. ++@end defvar ++ ++@node Parsing OpenPGP packets ++@chapter Parsing OpenPGP packets ++ ++The format of OpenPGP messages is maintained in order to publish all ++necessary information needed to develop interoperable applications. ++The standard is documented in RFC 2440. ++ ++PGG has its own parser for the OpenPGP packets. ++ ++@defun pgg-parse-armor string ++List the sequence of packets in @var{string}. ++@end defun ++ ++@defun pgg-parse-armor-region start end ++List the sequence of packets in the current region between @var{start} ++and @var{end}. ++@end defun ++ ++@defvar pgg-ignore-packet-checksum ++If non-@code{nil}, don't check the checksum of the packets. ++@end defvar ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Function Index ++@unnumbered Function Index ++@printindex fn ++ ++@node Variable Index ++@unnumbered Variable Index ++@printindex vr ++ ++@bye ++ ++@c End: ++ ++@ignore ++ arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85 ++@end ignore +diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi +new file mode 100644 +index 0000000..e2902cc +--- /dev/null ++++ b/doc/misc/rcirc.texi +@@ -0,0 +1,953 @@ ++\input texinfo ++@c %**start of header ++@setfilename ../../info/rcirc ++@settitle rcirc Manual ++@c %**end of header ++ ++@copying ++Copyright @copyright{} 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* Rcirc: (rcirc). Internet Relay Chat (IRC) client. ++@end direntry ++ ++@titlepage ++@title rcirc Manual ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top, Basics, (dir), (dir) ++@top rcirc Manual ++ ++@code{rcirc} is an Emacs IRC client. ++ ++IRC (Internet Relay Chat) is a multi-user chat protocol. Users ++communicate with each other in real-time. Communication occurs both in ++topic channels which are collections of many users, or privately, with ++just one other user. ++ ++@insertcopying ++ ++@end ifnottex ++ ++@menu ++* Basics:: ++* Reference:: ++* Fighting Information Overload:: ++* Hacking and Tweaking:: ++* GNU Free Documentation License:: ++* Key Index:: ++* Variable Index:: ++* Index:: ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ ++Basics ++ ++* Internet Relay Chat:: ++* Getting started with rcirc:: ++ ++Reference ++ ++* rcirc commands:: ++* Useful IRC commands:: ++* Configuration:: ++ ++Fighting Information Overload ++ ++* Channels:: ++* People:: ++* Keywords:: ++* Notices:: ++ ++Hacking and Tweaking ++ ++* Skipping /away messages using handlers:: ++* Using fly spell mode:: ++* Scrolling conservatively:: ++* Changing the time stamp format:: ++* Defining a new command:: ++* Reconnecting after you have lost the connection:: ++ ++@end detailmenu ++@end menu ++ ++@node Basics, Reference, Top, Top ++@chapter Basics ++ ++This chapter contains a brief introduction to IRC (Internet Relay Chat), ++and a quick tutorial on @code{rcirc}. ++ ++@menu ++* Internet Relay Chat:: ++* Getting started with rcirc:: ++@end menu ++ ++@node Internet Relay Chat, Getting started with rcirc, Basics, Basics ++@section Internet Relay Chat ++@cindex internet relay chat ++@cindex irc ++ ++@cindex channel ++@dfn{Internet Relay Chat} (IRC) is a form of instant communication over the ++Internet. It is mainly designed for group (many-to-many) communication ++in discussion forums called channels, but also allows one-to-one ++communication. ++ ++@cindex instant messaging, comparison ++@cindex server ++@cindex network ++Contrary to most Instant Messenger (IM) systems, users usually don't ++connect to a central server. Instead, users connect to a random ++server in a network, and servers relay messages from one to the next. ++ ++Here's a typical example: ++ ++@cindex redirection to random servers ++When you connect to the Freenode network ++(@code{http://freenode.net/}), you point your IRC client at the ++server @code{irc.freenode.net}. That server will redirect your client ++to a random server on the network, such as @code{zelazny.freenode.net}. ++ ++@cindex channel name ++@cindex # starts a channel name ++Once you're connected, you can send messages to all other users ++connected to the same network, and you can join all channels on the same ++network. You might join the @code{#emacs} and the @code{#rcirc} ++channels, for example. (Typically, channel names begin with a hash ++character.) ++ ++Once you have joined a channel, anything you type will be broadcast to ++all the other users on the same channel. ++ ++@cindex addressing other people ++@cindex other people, addressing them ++@cindex talk to other people ++If you want to address someone specifically, for example as an answer to ++a question, it is customary to prefix the message with the nick followed ++by a colon, like this: ++ ++@example ++deego: fsbot rules! ++@end example ++ ++@cindex nick completion ++@cindex completion of nicks ++@kindex TAB ++Since this is so common, you can use @key{TAB} to do nick completion. ++ ++@node Getting started with rcirc, , Internet Relay Chat, Basics ++@section Getting started with rcirc ++@cindex getting started ++@cindex connecting to a server ++ ++@cindex irc command ++Use the command @kbd{M-x irc} to connect using the defaults. ++@xref{Configuration}, if you want to change the defaults. ++ ++Use @kbd{C-u M-x irc} if you don't want to use the defaults, eg. if you ++want to connect to a different network, or connect to the same network ++using a different nick. This will prompt you for four things: ++ ++@table @asis ++@cindex server, connecting ++@cindex Freenode network ++@item IRC Server ++What server do you want to connect to? All the servers in a particular ++network are equivalent. Some networks use a round-robin system where a ++single server redirects new connections to a random server in the ++network. @code{irc.freenode.net} is such a server for the Freenode ++network. Freenode provides the network ``for the Free and Open Source ++Software communities, for not-for-profit organizations and for related ++communities and organizations.'' ++ ++@cindex port, connecting ++@cindex 6667, default IRC port ++@item IRC Port ++All network connections require a port. Just as web servers and clients ++use port 80 per default, IRC uses port 6667 per default. You rarely ++have to use a different port. ++ ++@cindex nick, connecting ++@cindex changing nick ++@cindex name changes ++@item IRC Nick ++@vindex user-login-name ++Every users needs a handle on-line. You will automatically be assigned ++a slightly different nick if your chosen nick is already in use. If ++your @code{user-login-name} is @code{alex}, and this nick is already ++in use, you might for example get assigned the nick @code{alex`}. ++ ++@cindex channels, connecting ++@cindex initial channels ++@cindex startup channels ++@item IRC Channels ++A space separated list of channels you want to join when connecting. ++You don't need to join any channels, if you just want to have one-to-one ++conversations with friends on the same network. If you're new to the ++Freenode network, join @code{#emacs}, the channel about all things ++Emacs, or join @code{#rcirc}, the channel about @code{rcirc}. ++@end table ++ ++@cindex server buffer ++When you have answered these questions, @code{rcirc} will create a server ++buffer, which will be named something like @code{*irc.freenode.net*}, ++and a channel buffer for each of the channels you wanted to join. ++ ++@kindex RET ++@cindex talking ++@cindex communicating ++To talk in a channel, just type what you want to say in a channel ++buffer, and press @key{RET}. ++ ++@kindex C-c C-c ++@cindex multiline messages ++@cindex messages, multiple lines ++@cindex pasting multiple lines ++@cindex edit message before sending ++If you want to paste multiple lines, such as source code, you can use ++@kbd{C-c C-c} to edit your message in a separate buffer. Use @kbd{C-c ++C-c} to finish editing. You still need to press @key{RET} to send it, ++though. Generally, IRC users don't like people pasting more than around ++four lines of code, so use with care. ++ ++@comment This section copied from the Channels section. ++@comment All index markers should point to the original! ++Once you are connected to multiple channels, or once you've turned you ++attention to other buffers in Emacs, you probably want to be notified ++of any activity in channels not currently visible. All you need to do ++is switch channel tracking on using @kbd{M-x rcirc-track-minor-mode}. ++To make this permanent, add the following to your init file: ++ ++@example ++(rcirc-track-minor-mode 1) ++@end example ++ ++Use @kbd{C-c C-@key{SPC}} to switch to these buffers. ++ ++@node Reference, Fighting Information Overload, Basics, Top ++@chapter Reference ++@cindex reference ++ ++This is the reference section of the manual. It is not complete. For ++complete listings of @code{rcirc} features, use Emacs built-in ++documentation. ++ ++@menu ++* rcirc commands:: ++* Useful IRC commands:: ++* Configuration:: ++@end menu ++ ++@node rcirc commands, Useful IRC commands, Reference, Reference ++@section rcirc commands ++@cindex rcirc commands ++@cindex commands ++ ++@kindex C-h m ++This is a list of commands that you may use in @code{rcirc}. It is not ++complete. For a complete listing, press @kbd{C-h m} in an @code{rcirc} ++buffer. ++ ++In addition to using regular Emacs key bindings, you can call them by ++typing them into an @code{rcirc} buffer. ++ ++@cindex call commands ++@cindex typing commands ++@cindex commands ++For instance, instead of using the command @kbd{C-c C-j} to join a new ++channel, you may type this in an @code{rcirc} buffer, and press @key{RET}: ++ ++@example ++/join #emacs ++@end example ++ ++@cindex / starts a command ++@cindex messages starting with a slash disappear ++@cindex disappearing messages if starting with a slash ++@cindex slash hides message ++This is why you cannot start a message with a slash. You will have to ++precede the command with a space, or rewrite your message in order to ++send it to a channel. ++ ++@cindex multiple words as parameters ++@cindex string delimiters ++@cindex quotes ++@cindex double-quotes ++Many commands take parameters. IRC commands usually ignore string ++delimiters. Neither quote nor double-quote have special meanings in ++IRC. ++ ++@example ++/nick "alex schroeder" ++@end example ++ ++This will try to change your nick to @code{"alex}. Usually this will ++fail because the double quote character is not a valid character for ++nicks. ++ ++@cindex case insensitive commands ++These commands are case insensitive. ++ ++@cindex new command ++@cindex unknown command ++@cindex command unknown ++If a command isn't known by @code{rcirc}, it will simply be sent along to the ++server. There is a list of some useful commands like that in the next ++section. ++ ++@table @kbd ++@item C-c C-j ++@kindex C-c C-j ++@cindex /join ++@cindex join channels ++@cindex other channels ++@cindex rooms, joining ++@cindex discussion, joining ++This joins a channel such as @code{#rcirc} or @code{#emacs}. On most ++networks, anybody can create new channels. If you want to talk with ++some friends, for example, all you have to do is agree on a valid ++channel name and join that channel. (Also @code{/join #emacs}.) ++ ++@item C-c C-p ++@kindex C-c C-p ++@cindex /part ++@cindex part a channel ++@cindex leave a channel ++@cindex disconnect from a channel ++@cindex stop talking on a channel ++@cindex kill channel buffer ++This leaves the current channel. You can optionally provide a reason ++for parting. When you kill a channel buffer, you automatically part the ++corresponding channel. (Also @code{/part you are too weird!}.) ++ ++@item C-c C-r ++@kindex C-c C-r ++@cindex /nick ++@cindex change name ++@cindex nick changing ++@cindex rename yourself ++@cindex other name ++This changes your nick to some other name. Your nick must be unique ++across the network. Most networks don't allow too many nick changes in ++quick succession, and have restrictions on the valid characters in nick ++names. (Also @code{/nick alex-test}) ++ ++@item C-c C-w ++@kindex C-c C-w ++@cindex /whois ++@cindex who are these people ++@cindex identifying people ++@cindex channels other people are on ++@cindex what channels people are on ++Gives you some basic information about a nick. This often includes what ++other channels people are on. (Also @code{/whois fsbot}.) ++ ++@item C-c C-q ++@kindex C-c C-q ++@cindex /query ++@cindex starting a private conversation ++@cindex one-to-one conversation ++@cindex talk privately ++@cindex private conversation ++@cindex contact one person only ++@cindex query a person ++Starts a one-to-one conversation with another person on the same ++network. A new buffer will be created for this conversation. It works ++like a channel with only two members. (Also @code{/query fsbot}.) ++ ++@item C-c @key{RET} ++@kindex C-c RET ++@cindex /msg ++@cindex single message ++@cindex message sending ++This sends a single message to a nick. Like with @kbd{C-c C-q}, a new ++buffer is created, where the response from the other party will show ++up. (Also @code{/msg nickserv identify secret}.) ++ ++@item C-c C-x ++@kindex C-c C-x ++@cindex /quit ++@cindex quit ++@cindex disconnect ++@cindex kill connection ++@cindex connection end ++@cindex part all channels ++@cindex end connection ++@cindex server buffer killing ++@cindex reason for quitting ++This disconnects from the server and parts all channels. You can ++optionally provide a reason for quitting. When you kill the server ++buffer, you automatically quit the server and part all channels. (Also ++@code{/quit ZZZzzz...}.) ++@end table ++ ++@node Useful IRC commands, Configuration, rcirc commands, Reference ++@section Useful IRC commands ++@cindex irc commands ++@cindex commands ++ ++As mentioned, if a command isn't known by @code{rcirc}, it will simply be sent ++along to the server. Some such commands are available on nearly all IRC ++servers, such as: ++ ++@table @code ++@item /away ++@cindex /away ++@cindex away status ++@cindex pause status ++@cindex unavailable status ++@cindex set away status ++This sets your status as ``being away'' if you provide a reason, or sets ++your status as ``being back'' if you do not. People can use the ++@kbd{C-c C-w} command to check your status. Example: @code{/away food}. ++@end table ++ ++@cindex irc resources ++@cindex help about irc ++Typical IRC servers implement many more commands. You can read more ++about the fantastic world of IRC online at ++@uref{http://www.irchelp.org/, the Internet Relay Chat (IRC) help ++archive}. ++ ++@node Configuration, , Useful IRC commands, Reference ++@section Configuration ++@cindex configuring rcirc ++ ++These are some variables you can change to configure @code{rcirc} to your ++liking. ++ ++@table @code ++@item rcirc-server-alist ++@vindex rcirc-server-alist ++@cindex channels, configuration ++@cindex initial channels, configuration ++@cindex startup channels, configuration ++@cindex servers, configuration ++@cindex initial servers, configuration ++@cindex startup servers, configuration ++This variable contains an alist of servers to connect to by default ++and the keywords parameters to use. The keyword parameters are ++optional. If you don't provide any, the defaults as documented below ++will be used. ++ ++The most important parameter is the @code{:channels} parameter. It ++controls which channels you will join by default as soon as you are ++connected to the server. ++ ++Here's an example of how to set it: ++ ++@example ++(add-to-list 'rcirc-server-alist ++ '("otherworlders.org" ++ :channels ("#FUDGE" "#game-design"))) ++@end example ++ ++By default you will be connected to the @code{rcirc} support channel: ++@code{#rcirc} on @code{irc.freenode.net}. ++ ++@table @code ++@item :nick ++This overrides @code{rcirc-default-nick}. ++ ++@item :port ++This overrides @code{rcirc-default-port}. ++ ++@item :user-name ++This overrides @code{rcirc-default-user-name}. ++ ++@item :full-name ++This overrides @code{rcirc-default-full-name}. ++ ++@item :channels ++This describes which channels to join when connecting to the server. ++If absent, no channels will be connected to automatically. ++ ++@end table ++ ++@item rcirc-default-nick ++@vindex rcirc-default-nick ++This variable is used for the default nick. It defaults to the login ++name returned by @code{user-login-name}. ++ ++@example ++(setq rcirc-default-nick "kensanata") ++@end example ++ ++@item rcirc-default-port ++@vindex rcirc-default-port ++@cindex port ++This variable contains the default port to connect to. It is 6667 by ++default and rarely needs changing. ++ ++@item rcirc-default-user-name ++@vindex rcirc-default-user-name ++@cindex user name ++This variable contains the default user name to report to the server. ++It defaults to the login name returned by @code{user-login-name}, just ++like @code{rcirc-default-nick}. ++ ++@item rcirc-default-user-full-name ++@vindex rcirc-default-user-full-name ++@cindex full name ++@cindex real name ++@cindex surname ++This variable is used to set your ``real name'' on IRC. It defaults ++to the name returned by @code{user-full-name}. If you want to hide ++your full name, you might want to set it to some pseudonym. ++ ++@example ++(setq rcirc-default-user-full-name "Curious Minds Want To Know") ++@end example ++ ++@item rcirc-authinfo ++@vindex rcirc-authinfo ++@cindex authentification ++@cindex identification ++@cindex nickserv ++@cindex login ++This variable is an alist used to automatically identify yourself on ++networks. Each sublist starts with a regular expression that is ++compared to the server address you're connecting to. The second ++element in the list is a symbol representing the method to use, ++followed by the arguments this method requires. ++ ++Here is an example to illustrate how you would set it: ++ ++@example ++(setq rcirc-authinfo ++ '(("freenode" nickserv "bob" "p455w0rd") ++ ("freenode" chanserv "bob" "#bobland" "passwd99") ++ ("bitlbee" bitlbee "robert" "sekrit"))) ++@end example ++ ++And here are the valid method symbols and the arguments they require: ++ ++@table @code ++@item nickserv ++@cindex nickserv authentification ++Use this symbol if you need to identify yourself as follows when ++connecting to a network: @code{/msg nickserv identify secret}. The ++necessary arguments are the nickname you want to use this for, and the ++password to use. ++ ++Before you can use this method, you will have to register your nick and ++pick a password for it. Contact @code{nickserv} and check out the ++details. (Using @code{/msg nickserv help}, for example.) ++ ++@item chanserv ++@cindex chanserv authentification ++Use this symbol if you need to identify yourself as follows if you want ++to join a particular channel: @code{/msg chanserv identify #underground ++secret}. The necessary arguments are the nickname and channel you want ++to use this for, and the password to use. ++ ++Before you can use this method, a channel contact must tell you about ++the password to use. Contact @code{chanserv} and check out the details. ++(Using @code{/msg chanserv help}, for example.) ++ ++@item bitlbee ++@cindex bitlbee authentification ++Use this symbol if you need to identify yourself in the Bitlbee channel ++as follows: @code{identify secret}. The necessary arguments are the ++nickname you want to use this for, and the password to use. ++ ++@cindex gateway to other IM services ++@cindex instant messaging, other services ++@cindex Jabber ++@cindex AIM ++@cindex ICQ ++@cindex MSN ++@cindex Yahoo! ++Bitlbee acts like an IRC server, but in fact it is a gateway to a lot of ++other instant messaging services. You can either install Bitlbee ++locally or use a public Bitlbee server. There, you need to create an ++account with a password. This is the nick and password you need to ++provide for the bitlbee authentification method. ++ ++Later, you will tell Bitlbee about your accounts and passwords on all ++the other instant messaging services, and Bitlbee will log you in. All ++@code{rcirc} needs to know, is the login to your Bitlbee account. Don't ++confuse the Bitlbee account with all the other accounts. ++ ++@end table ++ ++@end table ++ ++@node Fighting Information Overload, Hacking and Tweaking, Reference, Top ++@chapter Fighting Information Overload ++@cindex information overload ++ ++This is the section of the manual that caters to the busy person ++online. There are support channels with several hundred people in ++them. Trying to follow a conversation in these channels can be a ++daunting task. This chapters tells you how @code{rcirc} can help. ++ ++@menu ++* Channels:: ++* People:: ++* Keywords:: ++* Notices:: ++@end menu ++ ++@node Channels, People, Fighting Information Overload, Fighting Information Overload ++@section Channels ++@cindex channels ++@cindex modeline ++ ++@comment This section copied to the Getting started with rcirc section ++@kindex C-c C-SPC ++@vindex rcirc-track-minor-mode ++@cindex switching channels ++@cindex tracking activity ++@cindex active channel ++@cindex abbreviated channel names ++@cindex modeline tracks activity ++Most people want a notification when something is said on a channel they ++have joined, particularly if they have been addressed directly. There ++is a global minor mode that will do this kind of tracking for you. All ++you need to do is switch it on using @kbd{M-x rcirc-track-minor-mode}. ++To make this permanent, add the following to your init file: ++ ++@example ++(rcirc-track-minor-mode 1) ++@end example ++ ++When other people say things in buffers that are currently buried (no ++window is showing them), the mode line will now show you the abbreviated ++channel or nick name. Use @kbd{C-c C-@key{SPC}} to switch to these ++buffers. ++ ++@vindex rcirc-mode-hook ++If you prefer not to load @code{rcirc} immediately, you can delay the ++activation of this mode: ++ ++@example ++(add-hook 'rcirc-mode-hook ++ (lambda () ++ (rcirc-track-minor-mode 1))) ++@end example ++ ++@cindex busy channels ++If you've joined a very active support channel, tracking activity is ++no longer useful. The channel will be always active. Switching to ++active channels using @kbd{C-c C-@key{SPC}} no longer works as ++expected. ++ ++@kindex C-c C-l ++@cindex low priority channels ++The solution is to mark this channel as a low priority channel. ++Use @kbd{C-c C-l} to make the current channel a low-priority channel. ++Low priority channels have the modeline indicator ``LowPri''. ++@kbd{C-c C-@key{SPC}} will not switch to low priority channels unless ++you use the @kbd{C-u} prefix. ++ ++@kindex C-c TAB ++@cindex ignored channels ++If you prefer a channel to never show up in the modeline, then you ++have to ignore it. Use @kbd{C-c @key{TAB}} to ignore the current ++channel. ++ ++@node People, Keywords, Channels, Fighting Information Overload ++@section People ++@cindex people, how to ignore ++@cindex nicks, how to ignore ++@cindex friends ++@cindex buddies ++@cindex trolls ++ ++The most important command available to the discerning IRC user is ++@code{/ignore}. It's the big equalizer online: If people aggravate ++you, just ignore them. ++ ++This is of course a crude all-or-nothing solution. Fear not, ++@code{rcirc} offers alternatives: You can ``brighten'' your buddies ++and ``dim'' certain other nicks that you don't want to ignore ++altogether. ++ ++@table @code ++@item /ignore ++@cindex /ignore ++@cindex ignoring other people ++@cindex trolls, ignoring ++@cindex hide some posts ++@cindex idiots online ++This command toggles the ignore status of a nick, if you provide one. ++If you don't provide a nick, the command lists all the nicks you are ++ignoring. All messages by ignored nicks are---you guessed it---ignored. ++Since only ``operators'' can kick people from channels, the ++ignore command is often the only way to deal with some of the more ++obnoxious fellows online. Example: @code{/ignore rudybot}. ++ ++@item /bright ++@cindex /bright ++@cindex highlight other people ++@cindex friends, highlight ++@cindex buddies, highlight ++@cindex nicks, highlight ++@cindex brighten nicks ++This command toggles the bright status of a nick, if you provide one. ++If you don't provide a nick, the command lists all the ``brightened'' ++nicks. All messages by brightened nicks are---you guessed ++it---brightened. Use this for your friends. Example: @code{/bright ++rcy}. ++ ++@item /dim ++@cindex /dim ++@cindex soft-ignore other people ++@cindex obnoxious people online ++@cindex rabble online ++This command toggles the dim status of a nick, if you provide one. If ++you don't provide a nick, the command lists all the ``dimmed'' nicks. ++All messages by dimmed nicks are---you guessed it---dimmed. Use this ++for boring people and bots. If you are tracking channel activity, ++messages by dimmed nicks will not register as activity. Example: ++@code{/dim fsbot}. ++@end table ++ ++ ++@node Keywords, Notices, People, Fighting Information Overload ++@section Keywords ++@cindex keywords ++ ++On a busy channel, you might want to ignore all activity (using ++@kbd{C-c @key{TAB}}) and just watch for certain keywords. The ++following command allows you to highlight certain keywords: ++ ++@table @code ++@item /keyword ++@cindex /keyword ++This command toggles the highlighting of a keyword, if you provide ++one. If you don't provide a keyword, the current keywords are ++listed. Example: @code{/keyword manual}. ++@end table ++ ++@node Notices, , Keywords, Fighting Information Overload ++@section Notices ++@cindex part notices, how to omit ++@cindex join notices, how to omit ++@cindex quit notices, how to omit ++@cindex nick notices, how to omit ++ ++@kindex C-c C-o ++@cindex low priority channels ++In busy channels you might not be interested in all the joining, ++parting, quitting, and renaming that goes on. You can omit those ++notices using @kbd{C-c C-o}. ++ ++@vindex rcirc-omit-responses ++@cindex away notices, how to omit ++You can control which notices get omitted via the ++@code{rcirc-omit-responses} variable. Here's an example of how to ++omit away messages: ++ ++@example ++(setq rcirc-omit-responses '("JOIN" "PART" "QUIT" "NICK" "AWAY)) ++@end example ++ ++@vindex rcirc-omit-threshold ++Notice that these messages will not be omitted if the nick in question ++has recently been active. After all, you don't want to continue a ++conversation with somebody who just left. That's why @code{rcirc} ++checks recent lines in the buffer to figure out if a nick has been ++active and only omits a message if the nick has not been active. The ++window @code{rcirc} considers is controlled by the ++@code{rcirc-omit-threshold} variable. ++ ++@node Hacking and Tweaking, GNU Free Documentation License, Fighting Information Overload, Top ++@chapter Hacking and Tweaking ++@cindex hacking and tweaking ++ ++Here are some examples of stuff you can do to configure @code{rcirc}. ++ ++@menu ++* Skipping /away messages using handlers:: ++* Using fly spell mode:: ++* Scrolling conservatively:: ++* Changing the time stamp format:: ++* Defining a new command:: ++* Reconnecting after you have lost the connection:: ++@end menu ++ ++@node Skipping /away messages using handlers, Using fly spell mode, Hacking and Tweaking, Hacking and Tweaking ++@section Skipping @code{/away} messages using handlers ++@cindex /away messages ++ ++@cindex handlers ++@cindex status codes ++The IRC protocol specifies how certain events are signaled from server ++to client. These events have numbers and are dealt with using so-called ++handlers. You can override existing handlers by exploiting the naming ++convention adopted for @code{rcirc}. ++ ++Here's how to stop @code{rcirc} from printing @code{/away} messages. ++Since @code{rcirc} doesn't define a 301 handler, you don't need to ++require @code{rcirc} before defining the handler: ++ ++@example ++(defun rcirc-handler-301 (process cmd sender args) ++ "/away message handler.") ++@end example ++ ++@node Using fly spell mode, Scrolling conservatively, Skipping /away messages using handlers, Hacking and Tweaking ++@section Using fly spell mode ++@cindex fly spell ++@cindex spelling ++@cindex spell-checking as you type ++@cindex automatic spelling ++@vindex rcirc-mode-hook ++ ++The following code activates Fly Spell Mode ++for @code{rcirc} buffers: ++ ++@example ++(add-hook 'rcirc-mode-hook (lambda () ++ (flyspell-mode 1))) ++@end example ++ ++@xref{Spelling, , Flyspell mode, emacs, The GNU Emacs Manual}, ++for details. ++ ++@node Scrolling conservatively, Changing the time stamp format, Using fly spell mode, Hacking and Tweaking ++@section Scrolling conservatively ++@cindex input line ++@cindex scrolling ++@vindex scroll-conservatively ++@vindex rcirc-mode-hook ++ ++IRC buffers are constantly growing. If you want to see as much as ++possible at all times, you would want the prompt at the bottom of the ++window when possible. The following snippet uses a local value for ++@code{scroll-conservatively} to achieve this: ++ ++@example ++(add-hook 'rcirc-mode-hook ++ (lambda () ++ (set (make-local-variable 'scroll-conservatively) ++ 8192))) ++@end example ++ ++@xref{Scrolling, , Scrolling conservatively, emacs, The GNU Emacs ++Manual}, for details. ++ ++@node Changing the time stamp format, Defining a new command, Scrolling conservatively, Hacking and Tweaking ++@section Changing the time stamp format ++@cindex time stamp ++@cindex date time ++@cindex format time stamp ++@vindex rcirc-time-format ++ ++@code{rcirc-time-format} is the format used for the time stamp. Here's ++how to include the date in the time stamp: ++ ++@example ++(setq rcirc-time-format "%Y-%m-%d %H:%M ") ++@end example ++ ++@node Defining a new command, Reconnecting after you have lost the connection, Changing the time stamp format, Hacking and Tweaking ++@section Defining a new command ++@cindex defining commands ++@cindex commands, defining ++@cindex new commands, defining ++ ++Here's a simple new command, @code{/sv}. With it, you can boast about ++your IRC client. It shows how you can use @code{defun-rcirc-command} to ++define new commands. ++ ++We're waiting for the definition of this command until @code{rcirc} is loaded ++because @code{defun-rcirc-command} is not yet available, and without ++@code{rcirc} loaded, the command wouldn't do us much good anyway. ++ ++@smallexample ++(eval-after-load 'rcirc ++ '(defun-rcirc-command sv (arg) ++ "Boast about rcirc." ++ (interactive "i") ++ (rcirc-send-message process target ++ (concat "I use " rcirc-id-string)))) ++@end smallexample ++ ++@node Reconnecting after you have lost the connection, , Defining a new command, Hacking and Tweaking ++@section Reconnecting after you have lost the connection ++@cindex reconnecting ++@cindex disconnecting servers, reconnecting ++ ++If you're chatting from a laptop, then you might be familiar with this ++problem: When your laptop falls asleep and wakes up later, your IRC ++client doesn't realize that it has been disconnected. It takes several ++minutes until the client decides that the connection has in fact been ++lost. The simple solution is to use @kbd{M-x rcirc}. The problem is ++that this opens an @emph{additional} connection, so you'll have two ++copies of every channel buffer --- one dead and one live. ++ ++The real answer, therefore, is a @code{/reconnect} command: ++ ++@smallexample ++(eval-after-load 'rcirc ++ '(defun-rcirc-command reconnect (arg) ++ "Reconnect the server process." ++ (interactive "i") ++ (unless process ++ (error "There's no process for this target")) ++ (let* ((server (car (process-contact process))) ++ (port (process-contact process :service)) ++ (nick (rcirc-nick process)) ++ channels query-buffers) ++ (dolist (buf (buffer-list)) ++ (with-current-buffer buf ++ (when (eq process (rcirc-buffer-process)) ++ (remove-hook 'change-major-mode-hook ++ 'rcirc-change-major-mode-hook) ++ (if (rcirc-channel-p rcirc-target) ++ (setq channels (cons rcirc-target channels)) ++ (setq query-buffers (cons buf query-buffers)))))) ++ (delete-process process) ++ (rcirc-connect server port nick ++ rcirc-default-user-name ++ rcirc-default-user-full-name ++ channels)))) ++@end smallexample ++ ++@node GNU Free Documentation License, Key Index, Hacking and Tweaking, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++ ++@node Key Index, Variable Index, GNU Free Documentation License, Top ++@unnumbered Key Index ++@printindex ky ++ ++@node Variable Index, Index, Key Index, Top ++@unnumbered Variable Index ++@printindex vr ++ ++@node Index, , Variable Index, Top ++@unnumbered Index ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 2589e562-3843-4ffc-8c2f-477cbad57c01 ++@end ignore +diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi +new file mode 100644 +index 0000000..c8876cc +--- /dev/null ++++ b/doc/misc/reftex.texi +@@ -0,0 +1,5895 @@ ++\input texinfo @c -*-texinfo-*- ++@c %**start of header ++@setfilename ../../info/reftex ++@settitle RefTeX User Manual ++@synindex ky cp ++@syncodeindex vr cp ++@syncodeindex fn cp ++ ++@c Version and Contact Info ++@set VERSION 4.31 ++@set EDITION 4.31 ++@set DATE February 2006 ++@set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,AUCTeX distribution site} ++@set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,Ref@TeX{} web page} ++@set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers} ++@set MAINTAINER the AUC@TeX{} project ++@set SUPPORTADDRESS AUC@TeX{} user mailing list (@email{auctex@@gnu.org}) ++@set DEVELADDRESS AUC@TeX{} developer mailing list (@email{auctex-devel@@gnu.org}) ++@set BUGADDRESS AUC@TeX{} bug mailing list (@email{bug-auctex@@gnu.org}) ++@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site} ++@c %**end of header ++ ++@copying ++This file documents @b{Ref@TeX{}}, a package to do labels, references, ++citations and indices for LaTeX documents with Emacs. ++ ++This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for ++@b{Ref@TeX{}} @value{VERSION} ++ ++Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations. ++@end direntry ++ ++@finalout ++ ++@c Macro definitions ++ ++@c Subheadings inside a table. Need a difference between info and the rest. ++@macro tablesubheading{text} ++@ifinfo ++@subsubheading \text\ ++@end ifinfo ++@ifnotinfo ++@item @b{\text\} ++@end ifnotinfo ++@end macro ++ ++@titlepage ++@title Ref@TeX{} User Manual ++@subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs ++@subtitle Edition @value{EDITION}, @value{DATE} ++ ++@author by Carsten Dominik ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@summarycontents ++@contents ++ ++@ifnottex ++@node Top,,,(dir) ++ ++@b{Ref@TeX{}} is a package for managing Labels, References, ++Citations and index entries with GNU Emacs. ++ ++Don't be discouraged by the size of this manual, which covers ++@b{Ref@TeX{}} in great depth. All you need to know to use ++@b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a ++Nutshell}). You can go back later to other parts of this document when ++needed. ++ ++@insertcopying ++ ++@menu ++* Introduction:: Quick-Start information. ++ ++* Table of Contents:: A Tool to move around quickly. ++* Labels and References:: Creating and referencing labels. ++* Citations:: Creating Citations. ++* Index Support:: Creating and Checking Index Entries. ++* Viewing Cross-References:: Who references or cites what? ++ ++* RefTeXs Menu:: The Ref menu in the menubar. ++* Key Bindings:: The default key bindings. ++* Faces:: Fontification of RefTeX's buffers. ++* Multifile Documents:: Document spread over many files. ++* Language Support:: How to support other languages. ++* Finding Files:: Included TeX files and BibTeX .bib files. ++* AUCTeX:: Cooperation with AUCTeX. ++* Optimizations:: When RefTeX is too slow. ++* Problems and Work-Arounds:: First Aid. ++* Imprint:: Author, Web-site, Thanks ++ ++* Commands:: Which are the available commands. ++* Options:: How to extend and configure RefTeX. ++* Keymaps and Hooks:: For customization. ++* Changes:: A List of recent changes to RefTeX. ++* GNU Free Documentation License:: The license for this documentation. ++ ++The Index ++ ++* Index:: The full index. ++ ++@detailmenu ++ ++Introduction ++ ++* Installation:: How to install and activate RefTeX. ++* RefTeX in a Nutshell:: A brief summary and quick guide. ++ ++Labels and References ++ ++* Creating Labels:: ++* Referencing Labels:: ++* Builtin Label Environments:: The environments RefTeX knows about. ++* Defining Label Environments:: ... and environments it doesn't. ++* Reference Info:: View the label corresponding to a \ref. ++* xr (LaTeX package):: References to external documents. ++* varioref (LaTeX package):: How to create \vref instead of \ref. ++* fancyref (LaTeX package):: How to create \fref instead of \ref. ++ ++Defining Label Environments ++ ++* Theorem and Axiom:: Defined with @code{\newenvironment}. ++* Quick Equation:: When a macro sets the label type. ++* Figure Wrapper:: When a macro argument is a label. ++* Adding Magic Words:: Other words for other languages. ++* Using \eqref:: How to switch to this AMS-LaTeX macro. ++* Non-Standard Environments:: Environments without \begin and \end ++* Putting it Together:: How to combine many entries. ++ ++Citations ++ ++* Creating Citations:: How to create them. ++* Citation Styles:: Natbib, Harvard, Chicago and Co. ++* Citation Info:: View the corresponding database entry. ++* Chapterbib and Bibunits:: Multiple bibliographies in a Document. ++* Citations Outside LaTeX:: How to make citations in Emails etc. ++* BibTeX Database Subsets:: Extract parts of a big database. ++ ++Index Support ++ ++* Creating Index Entries:: Macros and completion of entries. ++* The Index Phrases File:: A special file for global indexing. ++* Displaying and Editing the Index:: The index editor. ++* Builtin Index Macros:: The index macros RefTeX knows about. ++* Defining Index Macros:: ... and macros it doesn't. ++ ++The Index Phrases File ++ ++* Collecting Phrases:: Collecting from document or external. ++* Consistency Checks:: Check for duplicates etc. ++* Global Indexing:: The interactive indexing process. ++ ++AUCTeX ++ ++* AUCTeX-RefTeX Interface:: How both packages work together ++* Style Files:: AUCTeX's style files can support RefTeX ++* Bib-Cite:: Hypertext reading of a document ++ ++Options, Keymaps, Hooks ++ ++* Options (Table of Contents):: ++* Options (Defining Label Environments):: ++* Options (Creating Labels):: ++* Options (Referencing Labels):: ++* Options (Creating Citations):: ++* Options (Index Support):: ++* Options (Viewing Cross-References):: ++* Options (Finding Files):: ++* Options (Optimizations):: ++* Options (Fontification):: ++* Options (Misc):: ++ ++@end detailmenu ++@end menu ++ ++@end ifnottex ++ ++@node Introduction, Table of Contents, , Top ++@chapter Introduction ++@cindex Introduction ++ ++@b{Ref@TeX{}} is a specialized package for support of labels, ++references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps ++itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite}, ++and @code{\index}. Using these macros usually requires looking up ++different parts of the document and searching through BibTeX database ++files. @b{Ref@TeX{}} automates these time--consuming tasks almost ++entirely. It also provides functions to display the structure of a ++document and to move around in this structure quickly. ++ ++@iftex ++Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}} ++in great depth. All you need to know to use @b{Ref@TeX{}} can be ++summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go ++back later to other parts of this document when needed. ++@end iftex ++ ++@xref{Imprint}, for information about who to contact for help, bug ++reports or suggestions. ++ ++@menu ++* Installation:: How to install and activate RefTeX. ++* RefTeX in a Nutshell:: A brief summary and quick guide. ++@end menu ++ ++@node Installation, RefTeX in a Nutshell, , Introduction ++@section Installation ++@cindex Installation ++ ++@b{Ref@TeX{}} is bundled and pre--installed with Emacs since version ++20.2. It was also bundled and pre--installed with XEmacs 19.16--20.x. ++XEmacs 21.x users want to install the corresponding plug-in package ++which is available from the @value{XEMACSFTP}. See the XEmacs 21.x ++documentation on package installation for details. ++ ++Users of earlier Emacs distributions (including Emacs 19) can get a copy ++of the @b{Ref@TeX{}} distribution from the maintainers web-page. ++@xref{Imprint}, for more information. ++ ++@section Environment ++@cindex Finding files ++@cindex BibTeX database files, not found ++@cindex TeX files, not found ++@cindex @code{TEXINPUTS}, environment variable ++@cindex @code{BIBINPUTS}, environment variable ++ ++@b{Ref@TeX{}} needs to access all files which are part of a multifile ++document, and the BibTeX database files requested by the ++@code{\bibliography} command. To find these files, @b{Ref@TeX{}} will ++require a search path, i.e. a list of directories to check. Normally ++this list is stored in the environment variables @code{TEXINPUTS} and ++@code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some ++systems these variables do not contain the full search path. If ++@b{Ref@TeX{}} does not work for you because it cannot find some files, ++read @ref{Finding Files}. ++ ++@section Entering @b{Ref@TeX{}} Mode ++ ++@findex turn-on-reftex ++@findex reftex-mode ++@vindex LaTeX-mode-hook ++@vindex latex-mode-hook ++To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use ++@kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX ++files, add the following lines to your @file{.emacs} file: ++ ++@example ++(add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode ++(add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode ++@end example ++ ++@page ++@node RefTeX in a Nutshell, , Installation, Introduction ++@section @b{Ref@TeX{}} in a Nutshell ++@cindex Quick-Start ++@cindex Getting Started ++@cindex RefTeX in a Nutshell ++@cindex Nutshell, RefTeX in a ++ ++@enumerate ++@item ++@b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show ++a table of contents of the document. This buffer can display sections, ++labels and index entries defined in the document. From the buffer, you ++can jump quickly to every part of your document. Press @kbd{?} to get ++help. ++ ++@item ++@b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels ++and to find the correct key for references quickly. It distinguishes ++labels for different environments, knows about all standard ++environments (and many others), and can be configured to recognize any ++additional labeled environments you have defined yourself (variable ++@code{reftex-label-alist}). ++ ++@itemize @bullet ++@item ++@b{Creating Labels}@* ++Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point. ++@b{Ref@TeX{}} will either ++@itemize @minus ++@item ++derive a label from context (default for section labels) ++@item ++prompt for a label string (default for figures and tables) or ++@item ++insert a simple label made of a prefix and a number (all other ++environments) ++@end itemize ++@noindent ++Which labels are created how is configurable with the variable ++@code{reftex-insert-label-flags}. ++ ++@item ++@b{Referencing Labels}@* To make a reference, type @kbd{C-c )} ++(@code{reftex-reference}). This shows an outline of the document with ++all labels of a certain type (figure, equation,...) and some label ++context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro ++into the original buffer. ++@end itemize ++ ++@item ++@b{Citations}@* ++Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a ++regular expression to search in current BibTeX database files (as ++specified in the @code{\bibliography} command) and pull out a list of ++matches for you to choose from. The list is @emph{formatted} and ++sorted. The selected article is referenced as @samp{\cite@{@var{key}@}} ++(see the variable @code{reftex-cite-format} if you want to insert ++different macros). ++ ++@item ++@b{Index Support}@* ++@b{Ref@TeX{}} helps to enter index entries. It also compiles all ++entries into an alphabetically sorted @file{*Index*} buffer which you ++can use to check and edit the entries. @b{Ref@TeX{}} knows about the ++standard index macros and can be configured to recognize any additional ++macros you have defined (@code{reftex-index-macros}). Multiple indices ++are supported. ++ ++@itemize @bullet ++@item ++@b{Creating Index Entries}@* ++To index the current selection or the word at point, type @kbd{C-c /} ++(@code{reftex-index-selection-or-word}). The default macro ++@code{reftex-index-default-macro} will be used. For a more complex entry ++type @kbd{C-c <} (@code{reftex-index}), select any of the index macros ++and enter the arguments with completion. ++ ++@item ++@b{The Index Phrases File (Delayed Indexing)}@* ++Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add ++the current word or selection to a special @emph{index phrase file}. ++@b{Ref@TeX{}} can later search the document for occurrences of these ++phrases and let you interactively index the matches. ++ ++@item ++@b{Displaying and Editing the Index}@* ++To display the compiled index in a special buffer, type @kbd{C-c >} ++(@code{reftex-display-index}). From that buffer you can check and edit ++all entries. ++@end itemize ++ ++@page ++@item @b{Viewing Cross-References}@* ++When point is on the @var{key} argument of a cross--referencing macro ++(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, ++@code{\index}, and variations) or inside a BibTeX database entry, you ++can press @kbd{C-c &} (@code{reftex-view-crossref}) to display ++corresponding locations in the document and associated BibTeX database ++files. @* ++When the enclosing macro is @code{\cite} or @code{\ref} and no other ++message occupies the echo area, information about the citation or label ++will automatically be displayed in the echo area. ++ ++@item ++@b{Multifile Documents}@* ++Multifile Documents are fully supported. The included files must have a ++file variable @code{TeX-master} or @code{tex-main-file} pointing to the ++master file. @b{Ref@TeX{}} provides cross-referencing information from ++all parts of the document, and across document borders ++(@file{xr.sty}). ++ ++@item ++@b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in ++order to find labels and other information. It does it automatically ++once and updates its list internally when @code{reftex-label} and ++@code{reftex-index} are used. To enforce reparsing, call any of the ++commands described above with a raw @kbd{C-u} prefix, or press the ++@kbd{r} key in the label selection buffer, the table of contents ++buffer, or the index buffer. ++ ++@item ++@b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can ++cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX ++contains style files which trigger appropriate settings in ++@b{Ref@TeX{}}, so that for many of the popular LaTeX packages no ++additional customizations will be necessary. ++ ++@item ++@b{Useful Settings}@* ++To integrate RefTeX with AUCTeX, use ++@lisp ++(setq reftex-plug-into-AUCTeX t) ++@end lisp ++ ++To make your own LaTeX macro definitions known to @b{Ref@TeX{}}, ++customize the variables ++@example ++@code{reftex-label-alist} @r{(for label macros/environments)} ++@code{reftex-section-levels} @r{(for sectioning commands)} ++@code{reftex-cite-format} @r{(for @code{\cite}-like macros)} ++@code{reftex-index-macros} @r{(for @code{\index}-like macros)} ++@code{reftex-index-default-macro} @r{(to set the default macro)} ++@end example ++If you have a large number of macros defined, you may want to write ++an AUCTeX style file to support them with both AUCTeX and ++@b{Ref@TeX{}}. ++ ++@item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus ++until you have picked up the key bindings. For an overview of what you ++can do in each of the different special buffers, press @kbd{?}. Read ++the manual if you get stuck, of if you are curious what else might be ++available. The first part of the manual explains in ++a tutorial way how to use and customize @b{Ref@TeX{}}. The second ++part is a command and variable reference. ++@end enumerate ++ ++@node Table of Contents, Labels and References, Introduction, Top ++@chapter Table of Contents ++@cindex @file{*toc*} buffer ++@cindex Structure editing ++@cindex Table of contents buffer ++@findex reftex-toc ++@kindex C-c = ++ ++Pressing the keys @kbd{C-c =} pops up a buffer showing the table of ++contents of the document. By default, this @file{*toc*} buffer shows ++only the sections of a document. Using the @kbd{l} and @kbd{i} keys you ++can display all labels and index entries defined in the document as ++well. ++ ++With the cursor in any of the lines denoting a location in the ++document, simple key strokes will display the corresponding part in ++another window, jump to that location, or perform other actions. ++ ++@kindex ? ++Here is a list of special commands in the @file{*toc*} buffer. A ++summary of this information is always available by pressing ++@kbd{?}. ++ ++@table @kbd ++ ++@tablesubheading{General} ++@item ? ++Display a summary of commands. ++ ++@item 0-9, - ++Prefix argument. ++ ++@tablesubheading{Moving around} ++@item n ++Goto next entry in the table of context. ++ ++@item p ++Goto previous entry in the table of context. ++ ++@item C-c C-n ++Goto next section heading. Useful when many labels and index entries ++separate section headings. ++ ++@item C-c C-p ++Goto previous section heading. ++ ++@item N z ++Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps ++to section 3. ++ ++@tablesubheading{Access to document locations} ++@item @key{SPC} ++Show the corresponding location in another window. This command does ++@emph{not} select that other window. ++ ++@item @key{TAB} ++Goto the location in another window. ++ ++@item @key{RET} ++Go to the location and hide the @file{*toc*} buffer. This will restore ++the window configuration before @code{reftex-toc} (@kbd{C-c =}) was ++called. ++ ++@item mouse-2 ++@vindex reftex-highlight-selection ++Clicking with mouse button 2 on a line has the same effect as @key{RET}. ++See also variable @code{reftex-highlight-selection}, @ref{Options ++(Fontification)}. ++ ++@item f ++@vindex reftex-toc-follow-mode ++@vindex reftex-revisit-to-follow ++Toggle follow mode. When follow mode is active, the other window will ++always show the location corresponding to the line at point in the ++@file{*toc*} buffer. This is similar to pressing @key{SPC} after each ++cursor motion. The default for this flag can be set with the variable ++@code{reftex-toc-follow-mode}. Note that only context in files already ++visited is shown. @b{Ref@TeX{}} will not visit a file just for follow ++mode. See, however, the variable ++@code{reftex-revisit-to-follow}. ++ ++@item . ++Show calling point in another window. This is the point from where ++@code{reftex-toc} was last called. ++ ++@page ++@tablesubheading{Promotion and Demotion} ++ ++@item < ++Promote the current section. This will convert @code{\section} to ++@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is ++an active region, all sections in the region will be promoted, including ++the one at point. To avoid mistakes, @b{Ref@TeX{}} requires a fresh ++document scan before executing this command - if necessary, it will ++automatically do this scan and ask the user to repeat the promotion ++command. ++ ++@item > ++Demote the current section. This is the opposite of promotion. It will ++convert @code{\chapter} to @code{\section} etc. If there is an active ++region, all sections in the region will be demoted, including the one at ++point. ++ ++@item M-% ++Rename the label at point. While generally not recommended, this can be ++useful when a package like @file{fancyref} is used where the label ++prefix determines the wording of a reference. After a ++promotion/demotion it may be necessary to change a few labels from ++@samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be ++used to do this - it launches a query replace to rename the definition ++and all references of a label. ++ ++@tablesubheading{Exiting} ++@item q ++Hide the @file{*toc*} buffer, return to the position where ++@code{reftex-toc} was last called. ++ ++@item k ++Kill the @file{*toc*} buffer, return to the position where ++@code{reftex-toc} was last called. ++ ++@item C-c > ++Switch to the @file{*Index*} buffer of this document. With prefix ++@samp{2}, restrict the index to the section at point in the @file{*toc*} ++buffer. ++ ++@tablesubheading{Controlling what gets displayed} ++ ++@item t ++@vindex reftex-toc-max-level ++Change the maximum level of toc entries displayed in the @file{*toc*} ++buffer. Without prefix arg, all levels will be included. With prefix ++arg (e.g @kbd{3 t}), ignore all toc entries with level greater than ++@var{arg} (3 in this case). Chapters are level 1, sections are level 2. ++The mode line @samp{T<>} indicator shows the current value. The default ++depth can be configured with the variable ++@code{reftex-toc-max-level}. ++ ++@item F ++@vindex reftex-toc-include-file-boundaries ++Toggle the display of the file borders of a multifile document in the ++@file{*toc*} buffer. The default for this flag can be set with the ++variable @code{reftex-toc-include-file-boundaries}. ++ ++@item l ++@vindex reftex-toc-include-labels ++Toggle the display of labels in the @file{*toc*} buffer. The default ++for this flag can be set with the variable ++@code{reftex-toc-include-labels}. When called with a prefix argument, ++@b{Ref@TeX{}} will prompt for a label type and include only labels of ++the selected type in the @file{*toc*} buffer. The mode line @samp{L<>} ++indicator shows which labels are included. ++ ++@item i ++@vindex reftex-toc-include-index-entries ++Toggle the display of index entries in the @file{*toc*} buffer. The ++default for this flag can be set with the variable ++@code{reftex-toc-include-index-entries}. When called with a prefix ++argument, @b{Ref@TeX{}} will prompt for a specific index and include ++only entries in the selected index in the @file{*toc*} buffer. The mode ++line @samp{I<>} indicator shows which index is used. ++ ++@item c ++@vindex reftex-toc-include-context ++Toggle the display of label and index context in the @file{*toc*} ++buffer. The default for this flag can be set with the variable ++@code{reftex-toc-include-context}. ++ ++@tablesubheading{Updating the buffer} ++ ++@item g ++Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the ++document. ++ ++@item r ++@vindex reftex-enable-partial-scans ++Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When ++@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this ++location is defined in, not the entire document. ++ ++@item C-u r ++Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*} ++buffer. ++ ++@item x ++Switch to the @file{*toc*} buffer of an external document. When the ++current document is using the @code{xr} package (@pxref{xr (LaTeX ++package)}), @b{Ref@TeX{}} will switch to one of the external ++documents. ++ ++ ++@tablesubheading{Automatic recentering} ++ ++@item d ++Toggle the display of a dedicated frame displaying just the @file{*toc*} ++buffer. Follow mode and visiting locations will not work that frame, ++but automatic recentering will make this frame always show your current ++editing location in the document (see below). ++ ++@item a ++Toggle the automatic recentering of the @file{*toc*} buffer. When this ++option is on, moving around in the document will cause the @file{*toc*} ++to always highlight the current section. By default, this option is ++active while the dedicated @file{*TOC*} frame exists. See also the ++variable @code{reftex-auto-recenter-toc}. ++ ++@end table ++ ++@vindex reftex-toc-map ++In order to define additional commands for the @file{*toc*} buffer, the ++keymap @code{reftex-toc-map} may be used. ++ ++@findex reftex-toc-recenter ++@vindex reftex-auto-recenter-toc ++@vindex reftex-idle-time ++@cindex @file{*toc*} buffer, recentering ++@cindex Table of contents buffer, recentering ++@kindex C-c - ++If you call @code{reftex-toc} while the @file{*toc*} buffer already ++exists, the cursor will immediately jump to the right place, i.e. the ++section from which @code{reftex-toc} was called will be highlighted. ++The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay ++the @file{*toc*} buffer and highlight the correct line without actually ++selecting the @file{*toc*} window. This can be useful to quickly find ++out where in the document you currently are. You can also automate this ++by asking RefTeX to keep track of your current editing position in the ++TOC. The TOC window will then be updated whenever you stop typing for ++more than @code{reftex-idle-time} seconds. By default this works only ++with the dedicated @file{*TOC*} frame. But you can also force automatic ++recentering of the TOC window on the current frame with ++@lisp ++(setq reftex-auto-recenter-toc t) ++@end lisp ++ ++ ++@cindex Sectioning commands ++@cindex KOMA-Script, LaTeX classes ++@cindex LaTeX classes, KOMA-Script ++@cindex TOC entries for environments ++@vindex reftex-section-levels ++The section macros recognized by @b{Ref@TeX{}} are all LaTeX section ++macros (from @code{\part} to @code{\subsubparagraph}) and the commands ++@code{\addchap} and @code{\addsec} from the KOMA-Script classes. ++Additional macros can be configured with the variable ++@code{reftex-section-levels}. It is also possible to add certain LaTeX ++environments to the table of contents. This is probably only useful for ++theorem-like environments. @xref{Defining Label Environments}, for an ++example. ++ ++@node Labels and References, Citations, Table of Contents, Top ++@chapter Labels and References ++@cindex Labels in LaTeX ++@cindex References in LaTeX ++@cindex Label category ++@cindex Label environment ++@cindex @code{\label} ++ ++LaTeX provides a powerful mechanism to deal with cross--references in a ++document. When writing a document, any part of it can be marked with a ++label, like @samp{\label@{mark@}}. LaTeX records the current value of a ++certain counter when a label is defined. Later references to this label ++(like @samp{\ref@{mark@}}) will produce the recorded value of the ++counter. ++ ++Labels can be used to mark sections, figures, tables, equations, ++footnotes, items in enumerate lists etc. LaTeX is context sensitive in ++doing this: A label defined in a figure environment automatically ++records the figure counter, not the section counter. ++ ++Several different environments can share a common counter and therefore ++a common label category. E.g. labels in both @code{equation} and ++@code{eqnarray} environments record the value of the same counter - the ++equation counter. ++ ++@menu ++* Creating Labels:: ++* Referencing Labels:: ++* Builtin Label Environments:: The environments RefTeX knows about. ++* Defining Label Environments:: ... and environments it doesn't. ++* Reference Info:: View the label corresponding to a \ref. ++* xr (LaTeX package):: References to external documents. ++* varioref (LaTeX package):: How to create \vref instead of \ref. ++* fancyref (LaTeX package):: How to create \fref instead of \ref. ++@end menu ++ ++@node Creating Labels, Referencing Labels, , Labels and References ++@section Creating Labels ++@cindex Creating labels ++@cindex Labels, creating ++@cindex Labels, deriving from context ++@kindex C-c ( ++@findex reftex-label ++ ++In order to create a label in a LaTeX document, press @kbd{C-c (} ++(@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive ++and will figure out the environment it currently is in and adapt the ++label to that environment. A label usually consists of a short prefix ++indicating the type of the label and a unique mark. @b{Ref@TeX{}} has ++3 different modes to create this mark. ++ ++@enumerate ++@item ++@vindex reftex-translate-to-ascii-function ++@vindex reftex-derive-label-parameters ++@vindex reftex-label-illegal-re ++@vindex reftex-abbrev-parameters ++A label can be derived from context. This means, @b{Ref@TeX{}} takes ++the context of the label definition and constructs a label from ++that@footnote{Note that the context may contain constructs which are ++invalid in labels. @b{Ref@TeX{}} will therefore strip the accent from ++accented Latin-1 characters and remove everything else which is not ++valid in labels. This mechanism is safe, but may not be satisfactory ++for non-western languages. Check the following variables if you need to ++change things: @code{reftex-translate-to-ascii-function}, ++@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re}, ++@code{reftex-abbrev-parameters}.}. This works best for section labels, ++where the section heading is used to construct a label. In fact, ++@b{Ref@TeX{}}'s default settings use this method only for section ++labels. You will be asked to confirm the derived label, or edit ++it. ++ ++@item ++We may also use a simple unique number to identify a label. This is ++mostly useful for labels where it is difficult to come up with a very ++good descriptive name. @b{Ref@TeX{}}'s default settings use this method ++for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}} ++tends to write documents with many equations and finds it impossible ++to come up with good names for each of them. These simple labels are ++inserted without query, and are therefore very fast. Good descriptive ++names are not really necessary as @b{Ref@TeX{}} will provide context to ++reference a label (@pxref{Referencing Labels}). ++ ++@item ++The third method is to ask the user for a label. This is most ++useful for things which are easy to describe briefly and do not turn up ++too frequently in a document. @b{Ref@TeX{}} uses this for figures and ++tables. Of course, one can enter the label directly by typing the full ++@samp{\label@{mark@}}. The advantage of using @code{reftex-label} ++anyway is that @b{Ref@TeX{}} will know that a new label has been defined. ++It will then not be necessary to rescan the document in order to access ++this label later. ++@end enumerate ++ ++@vindex reftex-insert-label-flags ++If you want to change the way certain labels are created, check out the ++variable @code{reftex-insert-label-flags} (@pxref{Options (Creating ++Labels)}). ++ ++If you are using AUCTeX to write your LaTeX documents, you can ++set it up to delegate the creation of labels to ++@b{Ref@TeX{}}. @xref{AUCTeX}, for more information. ++ ++@node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References ++@section Referencing Labels ++@cindex Referencing labels ++@cindex Labels, referencing ++@cindex Selection buffer, labels ++@cindex Selection process ++@cindex @code{\ref} ++@kindex C-c ) ++@findex reftex-reference ++ ++@vindex reftex-trust-label-prefix ++@b{Ref@TeX{}} scans the document in order to find all labels. To make ++referencing labels easier, it assigns to each label a category, the ++@emph{label type} (for example section, table, figure, equation, etc.). ++In order to determine the label type, RefTeX parses around each label ++to see in what kind of environments it is located. You can speed up ++the parsing by using type-specific prefixes for labels and configuring ++the variable @code{reftex-trust-label-prefix}. ++ ++Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c ++)} in order to reference a label (reftex-reference). This will start a ++selection process and finally insert the complete @samp{\ref@{label@}} ++into the buffer. ++ ++First, @b{Ref@TeX{}} will determine the label category which is required. ++Often that can be figured out from context. For example, if you ++write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows ++that an equation label is going to be referenced. If it cannot figure ++out what label category is needed, it will query for one. ++ ++You will then be presented with a label selection menu. This is a ++special buffer which contains an outline of the document along with all ++labels of the given label category. In addition, next to the label ++there will be one line of context of the label definition, which is some ++text in the buffer near the label definition. Usually this is ++sufficient to identify the label. If you are unsure about a certain ++label, pressing @key{SPC} will show the label definition point in ++another window. ++ ++In order to reference a label, move to cursor to the correct label and ++press @key{RET}. You can also reference several labels with a single ++call to @code{reftex-reference} by marking entries with the @kbd{m} ++key (see below). ++ ++@kindex ? ++Here is a list of special commands in the selection buffer. A summary ++of this information is always available from the selection process by ++pressing @kbd{?}. ++ ++ ++ ++@table @kbd ++@tablesubheading{General} ++@item ? ++Show a summary of available commands. ++ ++@item 0-9,- ++Prefix argument. ++ ++@tablesubheading{Moving around} ++@item n ++Go to next label. ++ ++@item p ++Go to previous label. ++ ++@item b ++Jump back to the position where you last left the selection buffer. ++Normally this should get you back to the last referenced label. ++ ++@item C-c C-n ++Goto next section heading. ++ ++@item C-c C-p ++Goto previous section heading. ++ ++@item N z ++Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to ++section 3. ++ ++@tablesubheading{Displaying Context} ++@item @key{SPC} ++Show the surroundings of the definition of the current label in another ++window. See also the @kbd{f} key. ++ ++@item f ++@vindex reftex-revisit-to-follow ++Toggle follow mode. When follow mode is active, the other window will ++always display the full context of the current label. This is similar ++to pressing @key{SPC} after each cursor motion. Note that only context ++in files already visited is shown. @b{RefTeX} will not visit a file ++just for follow mode. See, however, the variable ++@code{reftex-revisit-to-follow}. ++ ++@item . ++Show insertion point in another window. This is the point from where you ++called @code{reftex-reference}. ++ ++@tablesubheading{Selecting a label and creating the reference} ++@item @key{RET} ++Insert a reference to the label at point into the buffer from which the ++selection process was started. When entries have been marked, @key{RET} ++references all marked labels. ++ ++@item mouse-2 ++@vindex reftex-highlight-selection ++Clicking with mouse button 2 on a label will accept it like @key{RET} ++would. See also variable @code{reftex-highlight-selection}, @ref{Options ++(Misc)}. ++ ++@vindex reftex-multiref-punctuation ++@item m - + , ++Mark the current entry. When several entries have been marked, pressing ++@kbd{RET} will accept all of them and place them into several ++@code{\ref} macros. The special markers @samp{,-+} also store a ++separator to be inserted before the corresponding reference. So marking ++six entries with the keys @samp{m , , - , +} will give a reference list ++like this (see the variable @code{reftex-multiref-punctuation}) ++@example ++In eqs. (1), (2), (3)--(4), (5) and (6) ++@end example ++ ++@item u ++Unmark a marked entry. ++ ++@c FIXME: Do we need `A' as well for consistency? ++@cindex LaTeX packages, @code{saferef} ++@cindex @code{saferef}, LaTeX package ++@item a ++Accept the marked entries and put all labels as a comma-separated list ++into one @emph{single} @code{\ref} macro. Some packages like ++@file{saferef.sty} support multiple references in this way. ++ ++@item l ++Use the last referenced label(s) again. This is equivalent to moving to ++that label and pressing @key{RET}. ++ ++@item @key{TAB} ++Enter a label with completion. This may also be a label which does not ++yet exist in the document. ++ ++@item v ++@cindex @code{varioref}, LaTeX package ++@cindex @code{\vref} ++@cindex LaTeX packages, @code{varioref} ++Toggle between @code{\ref} and @code{\vref} macro for references. The ++@code{\vref} macro is defined in the @code{varioref} LaTeX package. ++With this key you can force @b{Ref@TeX{}} to insert a @code{\vref} ++macro. The current state of this flag is displayed by the @samp{S<>} ++indicator in the mode line of the selection buffer. ++ ++@item V ++@cindex @code{fancyref}, LaTeX package ++@cindex @code{\fref} ++@cindex @code{\Fref} ++@cindex LaTeX packages, @code{fancyref} ++Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The ++@code{\fref} and @code{\Fref} macros are defined in the @code{fancyref} ++LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a ++@code{\fref} or @code{\Fref} macro. The current state of this flag is ++displayed by the @samp{S<>} indicator in the mode line of the ++selection buffer. ++ ++@tablesubheading{Exiting} ++ ++@item q ++Exit the selection process without inserting any reference into the ++buffer. ++ ++@tablesubheading{Controlling what gets displayed} ++@vindex reftex-label-menu-flags ++The defaults for the following flags can be configured with the variable ++@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}). ++ ++@item c ++Toggle the display of the one-line label definition context in the ++selection buffer. ++ ++@item F ++Toggle the display of the file borders of a multifile document in the ++selection buffer. ++ ++@item t ++Toggle the display of the table of contents in the selection buffer. ++With prefix @var{arg}, change the maximum level of toc entries displayed ++to @var{arg}. Chapters are level 1, section are level 2. ++ ++@item # ++Toggle the display of a label counter in the selection buffer. ++ ++@item % ++Toggle the display of labels hidden in comments in the selection ++buffers. Sometimes, you may have commented out parts of your document. ++If these parts contain label definitions, @b{Ref@TeX{}} can still display ++and reference these labels. ++ ++@tablesubheading{Updating the buffer} ++@item g ++Update the menu. This will rebuilt the menu from the internal label ++list, but not reparse the document (see @kbd{r}). ++ ++@item r ++@vindex reftex-enable-partial-scans ++Reparse the document to update the information on all labels and rebuild ++the menu. If the variable @code{reftex-enable-partial-scans} is ++non-@code{nil} and your document is a multifile document, this will ++reparse only a part of the document (the file in which the label at ++point was defined). ++ ++@item C-u r ++Reparse the @emph{entire} document. ++ ++@item s ++Switch the label category. After prompting for another label category, ++a menu for that category will be shown. ++ ++@item x ++Reference a label from an external document. With the LaTeX package ++@code{xr} it is possible to reference labels defined in another ++document. This key will switch to the label menu of an external ++document and let you select a label from there (@pxref{xr (LaTeX ++package),,xr}). ++ ++@end table ++ ++@vindex reftex-select-label-map ++In order to define additional commands for the selection process, the ++keymap @code{reftex-select-label-map} may be used. ++ ++@node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References ++@section Builtin Label Environments ++@cindex Builtin label environments ++@cindex Label environments, builtin ++@cindex Environments, builtin ++@vindex reftex-label-alist ++@vindex reftex-label-alist-builtin ++ ++@b{Ref@TeX{}} needs to be aware of the environments which can be referenced ++with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}} ++recognizes all labeled environments and macros discussed in @cite{The ++LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley ++1994.}. These are: ++ ++@itemize @minus ++@item ++@cindex @code{figure}, LaTeX environment ++@cindex @code{figure*}, LaTeX environment ++@cindex @code{table}, LaTeX environment ++@cindex @code{table*}, LaTeX environment ++@cindex @code{equation}, LaTeX environment ++@cindex @code{eqnarray}, LaTeX environment ++@cindex @code{enumerate}, LaTeX environment ++@cindex @code{\footnote}, LaTeX macro ++@cindex LaTeX macro @code{footnote} ++@cindex LaTeX core ++@code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation}, ++@code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is ++the LaTeX core stuff) ++@item ++@cindex AMS-LaTeX ++@cindex @code{amsmath}, LaTeX package ++@cindex LaTeX packages, @code{amsmath} ++@cindex @code{align}, AMS-LaTeX environment ++@cindex @code{gather}, AMS-LaTeX environment ++@cindex @code{multline}, AMS-LaTeX environment ++@cindex @code{flalign}, AMS-LaTeX environment ++@cindex @code{alignat}, AMS-LaTeX environment ++@cindex @code{xalignat}, AMS-LaTeX environment ++@cindex @code{xxalignat}, AMS-LaTeX environment ++@cindex @code{subequations}, AMS-LaTeX environment ++@code{align}, @code{gather}, @code{multline}, @code{flalign}, ++@code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations} ++(from AMS-LaTeX's @file{amsmath.sty} package) ++@item ++@cindex @code{endnote}, LaTeX package ++@cindex LaTeX packages, @code{endnote} ++@cindex @code{\endnote}, LaTeX macro ++the @code{\endnote} macro (from @file{endnotes.sty}) ++@item ++@cindex @code{fancybox}, LaTeX package ++@cindex LaTeX packages, @code{fancybox} ++@cindex @code{Beqnarray}, LaTeX environment ++@code{Beqnarray} (@file{fancybox.sty}) ++@item ++@cindex @code{floatfig}, LaTeX package ++@cindex LaTeX packages, @code{floatfig} ++@cindex @code{floatingfig}, LaTeX environment ++@code{floatingfig} (@file{floatfig.sty}) ++@item ++@cindex @code{longtable}, LaTeX package ++@cindex LaTeX packages, @code{longtable} ++@cindex @code{longtable}, LaTeX environment ++@code{longtable} (@file{longtable.sty}) ++@item ++@cindex @code{picinpar}, LaTeX package ++@cindex LaTeX packages, @code{picinpar} ++@cindex @code{figwindow}, LaTeX environment ++@cindex @code{tabwindow}, LaTeX environment ++@code{figwindow}, @code{tabwindow} (@file{picinpar.sty}) ++@item ++@cindex @code{sidecap}, LaTeX package ++@cindex LaTeX packages, @code{sidecap} ++@cindex @code{SCfigure}, LaTeX environment ++@cindex @code{SCtable}, LaTeX environment ++@code{SCfigure}, @code{SCtable} (@file{sidecap.sty}) ++@item ++@cindex @code{rotating}, LaTeX package ++@cindex LaTeX packages, @code{rotating} ++@cindex @code{sidewaysfigure}, LaTeX environment ++@cindex @code{sidewaystable}, LaTeX environment ++@code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty}) ++@item ++@cindex @code{subfig}, LaTeX package ++@cindex LaTeX packages, @code{subfigure} ++@cindex @code{subfigure}, LaTeX environment ++@cindex @code{subfigure*}, LaTeX environment ++@code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro ++(@file{subfigure.sty}) ++@item ++@cindex @code{supertab}, LaTeX package ++@cindex LaTeX packages, @code{supertab} ++@cindex @code{supertabular}, LaTeX environment ++@code{supertabular} (@file{supertab.sty}) ++@item ++@cindex @code{wrapfig}, LaTeX package ++@cindex LaTeX packages, @code{wrapfig} ++@cindex @code{wrapfigure}, LaTeX environment ++@code{wrapfigure} (@file{wrapfig.sty}) ++@end itemize ++ ++If you want to use other labeled environments, defined with ++@code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize ++them (@pxref{Defining Label Environments}). ++ ++@node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References ++@section Defining Label Environments ++@cindex Label environments, defining ++ ++@vindex reftex-label-alist ++@b{Ref@TeX{}} can be configured to recognize additional labeled ++environments and macros. This is done with the variable ++@code{reftex-label-alist} (@pxref{Options (Defining Label ++Environments)}). If you are not familiar with Lisp, you can use the ++@code{custom} library to configure this rather complex variable. To do ++this, use ++ ++@example ++@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}} ++@end example ++ ++@vindex reftex-label-alist-builtin ++Here we will discuss a few examples, in order to make things clearer. ++It can also be instructive to look at the constant ++@code{reftex-label-alist-builtin} which contains the entries for ++all the builtin environments and macros (@pxref{Builtin Label ++Environments}). ++ ++@menu ++* Theorem and Axiom:: Defined with @code{\newenvironment}. ++* Quick Equation:: When a macro sets the label type. ++* Figure Wrapper:: When a macro argument is a label. ++* Adding Magic Words:: Other words for other languages. ++* Using \eqref:: How to switch to this AMS-LaTeX macro. ++* Non-Standard Environments:: Environments without \begin and \end ++* Putting it Together:: How to combine many entries. ++@end menu ++ ++@node Theorem and Axiom, Quick Equation, , Defining Label Environments ++@subsection Theorem and Axiom Environments ++@cindex @code{theorem}, newtheorem ++@cindex @code{axiom}, newtheorem ++@cindex @code{\newtheorem} ++ ++Suppose you are using @code{\newtheorem} in LaTeX in order to define two ++new environments, @code{theorem} and @code{axiom} ++ ++@example ++\newtheorem@{axiom@}@{Axiom@} ++\newtheorem@{theorem@}@{Theorem@} ++@end example ++ ++@noindent ++to be used like this: ++ ++@example ++\begin@{axiom@} ++\label@{ax:first@} ++ .... ++\end@{axiom@} ++@end example ++ ++So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new ++labeled environments which define their own label categories. We can ++either use Lisp to do this (e.g. in @file{.emacs}) or use the custom ++library. With Lisp it would look like this ++ ++@lisp ++(setq reftex-label-alist ++ '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) ++ ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3))) ++@end lisp ++ ++The type indicator characters @code{?a} and @code{?h} are used for ++prompts when @b{Ref@TeX{}} queries for a label type. @code{?h} ++was chosen for @code{theorem} since @code{?t} is already taken by ++@code{table}. Note that also @code{?s}, @code{?f}, @code{?e}, ++@code{?i}, @code{?n} are already used for standard environments. ++ ++@noindent ++The labels for Axioms and Theorems will have the prefixes @samp{ax:} and ++@samp{thr:}, respectively. @xref{AUCTeX}, for information on how ++AUCTeX can use RefTeX to automatically create labels when a new environment ++is inserted into a buffer. Additionally, the following needs to be ++added to one's .emacs file before AUCTeX will automatically create ++labels for the new environments. ++ ++@lisp ++(add-hook 'LaTeX-mode-hook ++ (lambda () ++ (LaTeX-add-environments ++ '("axiom" LaTeX-env-label) ++ '("theorem" LaTeX-env-label)))) ++@end lisp ++ ++ ++@noindent ++The @samp{~\ref@{%s@}} is a format string indicating how to insert ++references to these labels. ++ ++@noindent ++The next item indicates how to grab context of the label definition. ++@itemize @minus ++@item ++@code{t} means to get it from a default location (from the beginning of ++a @code{\macro} or after the @code{\begin} statement). @code{t} is ++@emph{not} a good choice for eqnarray and similar environments. ++@item ++@code{nil} means to use the text right after the label definition. ++@item ++For more complex ways of getting context, see the variable ++@code{reftex-label-alist} (@ref{Options (Defining Label ++Environments)}). ++@end itemize ++ ++The following list of strings is used to guess the correct label type ++from the word before point when creating a reference. E.g. if you ++write: @samp{As we have shown in Theorem} and then press @kbd{C-c )}, ++@b{Ref@TeX{}} will know that you are looking for a theorem label and ++restrict the menu to only these labels without even asking. ++ ++The final item in each entry is the level at which the environment ++should produce entries in the table of context buffer. If the number is ++positive, the environment will produce numbered entries (like ++@code{\section}), if it is negative the entries will be unnumbered (like ++@code{\section*}). Use this only for environments which structure the ++document similar to sectioning commands. For everything else, omit the ++item. ++ ++To do the same configuration with @code{customize}, you need to click on ++the @code{[INS]} button twice to create two templates and fill them in ++like this: ++ ++@example ++Reftex Label Alist: [Hide] ++[INS] [DEL] Package or Detailed : [Value Menu] Detailed: ++ Environment or \macro : [Value Menu] String: axiom ++ Type specification : [Value Menu] Char : a ++ Label prefix string : [Value Menu] String: ax: ++ Label reference format: [Value Menu] String: ~\ref@{%s@} ++ Context method : [Value Menu] After label ++ Magic words: ++ [INS] [DEL] String: axiom ++ [INS] [DEL] String: ax. ++ [INS] ++ [X] Make TOC entry : [Value Menu] Level: -2 ++[INS] [DEL] Package or Detailed : [Value Menu] Detailed: ++ Environment or \macro : [Value Menu] String: theorem ++ Type specification : [Value Menu] Char : h ++ Label prefix string : [Value Menu] String: thr: ++ Label reference format: [Value Menu] String: ~\ref@{%s@} ++ Context method : [Value Menu] Default position ++ Magic words: ++ [INS] [DEL] String: theorem ++ [INS] [DEL] String: theor. ++ [INS] [DEL] String: th. ++ [INS] ++ [X] Make TOC entry : [Value Menu] Level: -3 ++@end example ++ ++@vindex reftex-insert-label-flags ++@vindex reftex-label-menu-flags ++Depending on how you would like the label insertion and selection for ++the new environments to work, you might want to add the letters @samp{a} ++and @samp{h} to some of the flags in the variables ++@code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)}) ++and @code{reftex-label-menu-flags} (@pxref{Options (Referencing ++Labels)}). ++ ++ ++@node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments ++@subsection Quick Equation Macro ++@cindex Quick equation macro ++@cindex Macros as environment wrappers ++ ++Suppose you would like to have a macro for quick equations. It ++could be defined like this: ++ ++@example ++\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@} ++@end example ++ ++@noindent ++and used like this: ++ ++@example ++Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}. ++@end example ++ ++We need to tell @b{Ref@TeX{}} that any label defined in the argument of the ++@code{\quickeq} is an equation label. Here is how to do this with lisp: ++ ++@lisp ++(setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil))) ++@end lisp ++ ++The first element in this list is now the macro with empty braces as an ++@emph{image} of the macro arguments. @code{?e} indicates that this is ++an equation label, the different @code{nil} elements indicate to use the ++default values for equations. The @samp{1} as the fifth element ++indicates that the context of the label definition should be the 1st ++argument of the macro. ++ ++Here is again how this would look in the customization buffer: ++ ++@example ++Reftex Label Alist: [Hide] ++[INS] [DEL] Package or Detailed : [Value Menu] Detailed: ++ Environment or \macro : [Value Menu] String: \quickeq@{@} ++ Type specification : [Value Menu] Char : e ++ Label prefix string : [Value Menu] Default ++ Label reference format: [Value Menu] Default ++ Context method : [Value Menu] Macro arg nr: 1 ++ Magic words: ++ [INS] ++ [ ] Make TOC entry : [Value Menu] No entry ++@end example ++ ++@node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments ++@subsection Figure Wrapping Macro ++@cindex Macros as environment wrappers ++@cindex Figure wrapping macro ++ ++Suppose you want to make figures not directly with the figure ++environment, but with a macro like ++ ++@example ++\newcommand@{\myfig@}[5][tbp]@{% ++ \begin@{figure@}[#1] ++ \epsimp[#5]@{#2@} ++ \caption@{#3@} ++ \label@{#4@} ++ \end@{figure@}@} ++@end example ++ ++@noindent ++which would be called like ++ ++@example ++\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@} ++@end example ++ ++Now we need to tell @b{Ref@TeX{}} that the 4th argument of the ++@code{\myfig} macro @emph{is itself} a figure label, and where to find ++the context. ++ ++@lisp ++(setq reftex-label-alist ++ '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3))) ++@end lisp ++ ++The empty pairs of brackets indicate the different arguments of the ++@code{\myfig} macro. The @samp{*} marks the label argument. @code{?f} ++indicates that this is a figure label which will be listed together with ++labels from normal figure environments. The @code{nil} entries for ++prefix and reference format mean to use the defaults for figure labels. ++The @samp{3} for the context method means to grab the 3rd macro argument ++- the caption. ++ ++As a side effect of this configuration, @code{reftex-label} will now ++insert the required naked label (without the @code{\label} macro) when ++point is directly after the opening parenthesis of a @code{\myfig} macro ++argument. ++ ++Again, here the configuration in the customization buffer: ++ ++@example ++[INS] [DEL] Package or Detailed : [Value Menu] Detailed: ++ Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@} ++ Type specification : [Value Menu] Char : f ++ Label prefix string : [Value Menu] Default ++ Label reference format: [Value Menu] Default ++ Context method : [Value Menu] Macro arg nr: 3 ++ Magic words: ++ [INS] ++ [ ] Make TOC entry : [Value Menu] No entry ++@end example ++ ++@node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments ++@subsection Adding Magic Words ++@cindex Magic words ++@cindex German magic words ++@cindex Label category ++ ++Sometimes you don't want to define a new label environment or macro, but ++just change the information associated with a label category. Maybe you ++want to add some magic words, for another language. Changing only the ++information associated with a label category is done by giving ++@code{nil} for the environment name and then specify the items you want ++to define. Here is an example which adds German magic words to all ++predefined label categories. ++ ++@lisp ++(setq reftex-label-alist ++ '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil")) ++ (nil ?e nil nil nil ("Gleichung" "Gl.")) ++ (nil ?t nil nil nil ("Tabelle")) ++ (nil ?f nil nil nil ("Figur" "Abbildung" "Abb.")) ++ (nil ?n nil nil nil ("Anmerkung" "Anm.")) ++ (nil ?i nil nil nil ("Punkt")))) ++@end lisp ++ ++@node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments ++@subsection Using @code{\eqref} ++@cindex @code{\eqref}, AMS-LaTeX macro ++@cindex AMS-LaTeX ++@cindex Label category ++ ++Another case where one only wants to change the information associated ++with the label category is to change the macro which is used for ++referencing the label. When working with the AMS-LaTeX stuff, you might ++prefer @code{\eqref} for doing equation references. Here is how to ++do this: ++ ++@lisp ++(setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil))) ++@end lisp ++ ++@b{Ref@TeX{}} has also a predefined symbol for this special purpose. The ++following is equivalent to the line above. ++ ++@lisp ++(setq reftex-label-alist '(AMSTeX)) ++@end lisp ++ ++Note that this is automatically done by the @file{amsmath.el} style file ++of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX, ++this configuration will not be necessary. ++ ++@node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments ++@subsection Non-standard Environments ++@cindex Non-standard environments ++@cindex Environments without @code{\begin} ++@cindex Special parser functions ++@cindex Parser functions, for special environments ++ ++Some LaTeX packages define environment-like structures without using the ++standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse ++these directly, but you can write your own special-purpose parser and ++use it instead of the name of an environment in an entry for ++@code{reftex-label-alist}. The function should check if point is ++currently in the special environment it was written to detect. If so, ++it must return a buffer position indicating the start of this ++environment. The return value must be @code{nil} on failure to detect ++the environment. The function is called with one argument @var{bound}. ++If non-@code{nil}, @var{bound} is a boundary for backwards searches ++which should be observed. We will discuss two examples. ++ ++@cindex LaTeX commands, abbreviated ++ ++Some people define abbreviations for ++environments, like @code{\be} for @code{\begin@{equation@}}, and ++@code{\ee} for @code{\end@{equation@}}. The parser function would have ++to search backward for these macros. When the first match is ++@code{\ee}, point is not in this environment. When the first match is ++@code{\be}, point is in this environment and the function must return ++the beginning of the match. To avoid scanning too far, we can also look ++for empty lines which cannot occur inside an equation environment. ++Here is the setup: ++ ++@lisp ++;; Setup entry in reftex-label-alist, using all defaults for equations ++(setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil))) ++ ++(defun detect-be-ee (bound) ++ ;; Search backward for the macros or an empty line ++ (if (re-search-backward ++ "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t) ++ (if (match-beginning 2) ++ (match-beginning 2) ; Return start of environment ++ nil) ; Return nil because env is closed ++ nil)) ; Return nil for not found ++@end lisp ++ ++@cindex @code{linguex}, LaTeX package ++@cindex LaTeX packages, @code{linguex} ++A more complex example is the @file{linguex.sty} package which defines ++list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are ++terminated by @samp{\z.} or by an empty line. ++ ++@example ++\ex. \label@{ex:12@} Some text in an exotic language ... ++ \a. \label@{ex:13@} more stuff ++ \b. \label@{ex:14@} still more stuff ++ \a. List on a deeper level ++ \b. Another item ++ \b. and the third one ++ \z. ++ \b. Third item on this level. ++ ++... text after the empty line terminating all lists ++@end example ++ ++The difficulty is that the @samp{\a.} lists can nest and that an empty ++line terminates all list levels in one go. So we have to count nesting ++levels between @samp{\a.} and @samp{\z.}. Here is the implementation ++for @b{Ref@TeX{}}. ++ ++@lisp ++(setq reftex-label-alist ++ '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) ++ ++(defun detect-linguex (bound) ++ (let ((cnt 0)) ++ (catch 'exit ++ (while ++ ;; Search backward for all possible delimiters ++ (re-search-backward ++ (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|" ++ "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)") ++ nil t) ++ ;; Check which delimiter was matched. ++ (cond ++ ((match-beginning 1) ++ ;; empty line terminates all - return nil ++ (throw 'exit nil)) ++ ((match-beginning 2) ++ ;; \z. terminates one list level - decrease nesting count ++ (decf cnt)) ++ ((match-beginning 3) ++ ;; \ex. : return match unless there was a \z. on this level ++ (throw 'exit (if (>= cnt 0) (match-beginning 3) nil))) ++ ((match-beginning 4) ++ ;; \a. : return match when on level 0, otherwise ++ ;; increment nesting count ++ (if (>= cnt 0) ++ (throw 'exit (match-beginning 4)) ++ (incf cnt)))))))) ++@end lisp ++ ++@node Putting it Together, , Non-Standard Environments, Defining Label Environments ++@subsection Putting it all together ++ ++When you have to put several entries into @code{reftex-label-alist}, just ++put them after each other in a list, or create that many templates in ++the customization buffer. Here is a lisp example which uses several of ++the entries described above: ++ ++@lisp ++(setq reftex-label-alist ++ '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) ++ ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3) ++ ("\\quickeq@{@}" ?e nil nil 1 nil) ++ AMSTeX ++ ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3) ++ (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) ++@end lisp ++ ++@node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References ++@section Reference Info ++@findex reftex-view-crossref ++@findex reftex-mouse-view-crossref ++@cindex Cross-references, displaying ++@cindex Reference info ++@cindex Displaying cross-references ++@cindex Viewing cross-references ++@kindex C-c & ++@kindex S-mouse-2 ++ ++When point is idle for more than @code{reftex-idle-time} seconds on the ++argument of a @code{\ref} macro, the echo area will display some ++information about the label referenced there. Note that the information ++is only displayed if the echo area is not occupied by a different ++message. ++ ++@b{Ref@TeX{}} can also display the label definition corresponding to a ++@code{\ref} macro, or all reference locations corresponding to a ++@code{\label} macro. @xref{Viewing Cross-References}, for more ++information. ++ ++@node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References ++@section @code{xr}: Cross-Document References ++@cindex @code{xr}, LaTeX package ++@cindex LaTeX packages, @code{xr} ++@cindex @code{\externaldocument} ++@cindex External documents ++@cindex References to external documents ++@cindex Cross-document references ++ ++The LaTeX package @code{xr} makes it possible to create references to ++labels defined in external documents. The preamble of a document using ++@code{xr} will contain something like this: ++ ++@example ++\usepackage@{xr@} ++\externaldocument[V1-]@{volume1@} ++\externaldocument[V3-]@{volume3@} ++@end example ++ ++@noindent ++and we can make references to any labels defined in these ++external documents by using the prefixes @samp{V1-} and @samp{V3-}, ++respectively. ++ ++@b{Ref@TeX{}} can be used to create such references as well. Start the ++referencing process normally, by pressing @kbd{C-c )}. Select a label ++type if necessary. When you see the label selection buffer, pressing ++@kbd{x} will switch to the label selection buffer of one of the external ++documents. You may then select a label as before and @b{Ref@TeX{}} will ++insert it along with the required prefix. ++ ++For this kind of inter-document cross-references, saving of parsing ++information and the use of multiple selection buffers can mean a large ++speed-up (@pxref{Optimizations}). ++ ++@node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References ++@section @code{varioref}: Variable Page References ++@cindex @code{varioref}, LaTeX package ++@cindex @code{\vref} ++@cindex LaTeX packages, @code{varioref} ++@vindex reftex-vref-is-default ++@code{varioref} is a frequently used LaTeX package to create ++cross--references with page information. When you want to make a ++reference with the @code{\vref} macro, just press the @kbd{v} key in the ++selection buffer to toggle between @code{\ref} and @code{\vref} ++(@pxref{Referencing Labels}). The mode line of the selection buffer ++shows the current status of this switch. If you find that you almost ++always use @code{\vref}, you may want to make it the default by ++customizing the variable @code{reftex-vref-is-default}. If this ++toggling seems too inconvenient, you can also use the command ++@code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}. ++Or use AUCTeX to create your macros (@pxref{AUCTeX}). ++ ++@node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References ++@section @code{fancyref}: Fancy Cross References ++@cindex @code{fancyref}, LaTeX package ++@cindex @code{\fref} ++@cindex @code{\Fref} ++@cindex LaTeX packages, @code{fancyref} ++@vindex reftex-fref-is-default ++@code{fancyref} is a LaTeX package where a macro call like ++@code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of ++the referenced counter but also the complete text around it, like ++@samp{Figure 3 on the preceding page}. In order to make it work you ++need to use label prefixes like @samp{fig:} consistently - something ++@b{Ref@TeX{}} does automatically. When you want to make a reference ++with the @code{\fref} macro, just press the @kbd{V} key in the selection ++buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref} ++(@pxref{Referencing Labels}). The mode line of the selection buffer ++shows the current status of this switch. If this cycling seems ++inconvenient, you can also use the commands @code{reftex-fancyref-fref} ++and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c ++f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros ++(@pxref{AUCTeX}). ++ ++@node Citations, Index Support, Labels and References, Top ++@chapter Citations ++@cindex Citations ++@cindex @code{\cite} ++ ++Citations in LaTeX are done with the @code{\cite} macro or variations of ++it. The argument of the macro is a citation key which identifies an ++article or book in either a BibTeX database file or in an explicit ++@code{thebibliography} environment in the document. @b{Ref@TeX{}}'s ++support for citations helps to select the correct key quickly. ++ ++@menu ++* Creating Citations:: How to create them. ++* Citation Styles:: Natbib, Harvard, Chicago and Co. ++* Citation Info:: View the corresponding database entry. ++* Chapterbib and Bibunits:: Multiple bibliographies in a Document. ++* Citations Outside LaTeX:: How to make citations in Emails etc. ++* BibTeX Database Subsets:: Extract parts of a big database. ++@end menu ++ ++@node Creating Citations, Citation Styles, , Citations ++@section Creating Citations ++@cindex Creating citations ++@cindex Citations, creating ++@findex reftex-citation ++@kindex C-c [ ++@cindex Selection buffer, citations ++@cindex Selection process ++ ++In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then ++prompts for a regular expression which will be used to search through ++the database and present the list of matches to choose from in a ++selection process similar to that for selecting labels ++(@pxref{Referencing Labels}). ++ ++The regular expression uses an extended syntax: @samp{&&} defines a ++logic @code{and} for regular expressions. For example ++@samp{Einstein&&Bose} will match all articles which mention ++Bose-Einstein condensation, or which are co-authored by Bose and ++Einstein. When entering the regular expression, you can complete on ++known citation keys. RefTeX also offers a default when prompting for a ++regular expression. This default is the word before the cursor or the ++word before the current @samp{\cite} command. Sometimes this may be a ++good search key. ++ ++@cindex @code{\bibliography} ++@cindex @code{thebibliography}, LaTeX environment ++@cindex @code{BIBINPUTS}, environment variable ++@cindex @code{TEXBIB}, environment variable ++@b{Ref@TeX{}} prefers to use BibTeX database files specified with a ++@code{\bibliography} macro to collect its information. Just like ++BibTeX, it will search for the specified files in the current directory ++and along the path given in the environment variable @code{BIBINPUTS}. ++If you do not use BibTeX, but the document contains an explicit ++@code{thebibliography} environment, @b{Ref@TeX{}} will collect its ++information from there. Note that in this case the information ++presented in the selection buffer will just be a copy of relevant ++@code{\bibitem} entries, not the structured listing available with ++BibTeX database files. ++ ++@kindex ? ++In the selection buffer, the following keys provide special commands. A ++summary of this information is always available from the selection ++process by pressing @kbd{?}. ++ ++@table @kbd ++@tablesubheading{General} ++@item ? ++Show a summary of available commands. ++ ++@item 0-9,- ++Prefix argument. ++ ++@tablesubheading{Moving around} ++@item n ++Go to next article. ++ ++@item p ++Go to previous article. ++ ++@tablesubheading{Access to full database entries} ++@item @key{SPC} ++Show the database entry corresponding to the article at point, in ++another window. See also the @kbd{f} key. ++ ++@item f ++Toggle follow mode. When follow mode is active, the other window will ++always display the full database entry of the current article. This is ++equivalent to pressing @key{SPC} after each cursor motion. With BibTeX ++entries, follow mode can be rather slow. ++ ++@tablesubheading{Selecting entries and creating the citation} ++@item @key{RET} ++Insert a citation referencing the article at point into the buffer from ++which the selection process was started. ++ ++@item mouse-2 ++@vindex reftex-highlight-selection ++Clicking with mouse button 2 on a citation will accept it like @key{RET} ++would. See also variable @code{reftex-highlight-selection}, @ref{Options ++(Misc)}. ++ ++@item m ++Mark the current entry. When one or several entries are marked, ++pressing @kbd{a} or @kbd{A} accepts all marked entries. Also, ++@key{RET} behaves like the @kbd{a} key. ++ ++@item u ++Unmark a marked entry. ++ ++@item a ++Accept all (marked) entries in the selection buffer and create a single ++@code{\cite} macro referring to them. ++ ++@item A ++Accept all (marked) entries in the selection buffer and create a ++separate @code{\cite} macro for each of it. ++ ++@item e ++Create a new BibTeX database file which contains all @i{marked} entries ++in the selection buffer. If no entries are marked, all entries are ++selected. ++ ++@item E ++Create a new BibTeX database file which contains all @i{unmarked} ++entries in the selection buffer. If no entries are marked, all entries ++are selected. ++ ++@item @key{TAB} ++Enter a citation key with completion. This may also be a key which does ++not yet exist. ++ ++@item . ++Show insertion point in another window. This is the point from where you ++called @code{reftex-citation}. ++ ++@tablesubheading{Exiting} ++@item q ++Exit the selection process without inserting a citation into the ++buffer. ++ ++@tablesubheading{Updating the buffer} ++ ++@item g ++Start over with a new regular expression. The full database will be ++rescanned with the new expression (see also @kbd{r}). ++ ++@c FIXME: Should we use something else here? r is usually rescan! ++@item r ++Refine the current selection with another regular expression. This will ++@emph{not} rescan the entire database, but just the already selected ++entries. ++ ++@end table ++ ++@vindex reftex-select-bib-map ++In order to define additional commands for this selection process, the ++keymap @code{reftex-select-bib-map} may be used. ++ ++@node Citation Styles, Citation Info, Creating Citations, Citations ++@section Citation Styles ++@cindex Citation styles ++@cindex Citation styles, @code{natbib} ++@cindex Citation styles, @code{harvard} ++@cindex Citation styles, @code{chicago} ++@cindex Citation styles, @code{jurabib} ++@cindex @code{natbib}, citation style ++@cindex @code{harvard}, citation style ++@cindex @code{chicago}, citation style ++@cindex @code{jurabib}, citation style ++ ++@vindex reftex-cite-format ++The standard LaTeX macro @code{\cite} works well with numeric or simple ++key citations. To deal with the more complex task of author-year ++citations as used in many natural sciences, a variety of packages has ++been developed which define derived forms of the @code{\cite} macro. ++@b{Ref@TeX{}} can be configured to produce these citation macros as well ++by setting the variable @code{reftex-cite-format}. For the most ++commonly used packages (@code{natbib}, @code{harvard}, @code{chicago}, ++@code{jurabib}) this may be done from the menu, under ++@code{Ref->Citation Styles}. Since there are usually several macros to ++create the citations, executing @code{reftex-citation} (@kbd{C-c [}) ++starts by prompting for the correct macro. For the Natbib style, this ++looks like this: ++ ++@example ++SELECT A CITATION FORMAT ++ ++[^M] \cite@{%l@} ++[t] \citet@{%l@} ++[T] \citet*@{%l@} ++[p] \citep@{%l@} ++[P] \citep*@{%l@} ++[e] \citep[e.g.][]@{%l@} ++[s] \citep[see][]@{%l@} ++[a] \citeauthor@{%l@} ++[A] \citeauthor*@{%l@} ++[y] \citeyear@{%l@} ++@end example ++ ++@vindex reftex-cite-prompt-optional-args ++If cite formats contain empty paris of square brackets, RefTeX can ++will prompt for values of these optional arguments if you call the ++@code{reftex-citation} command with a @kbd{C-u} prefix. ++Following the most generic of these packages, @code{natbib}, the builtin ++citation packages always accept the @kbd{t} key for a @emph{textual} ++citation (like: @code{Jones et al. (1997) have shown...}) as well as ++the @kbd{p} key for a parenthetical citation (like: @code{As shown ++earlier (Jones et al, 1997)}). ++ ++To make one of these styles the default, customize the variable ++@code{reftex-cite-format} or put into @file{.emacs}: ++ ++@lisp ++(setq reftex-cite-format 'natbib) ++@end lisp ++ ++You can also use AUCTeX style files to automatically set the ++citation style based on the @code{usepackage} commands in a given ++document. @xref{Style Files}, for information on how to set up the style ++files correctly. ++ ++@node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top ++@section Citation Info ++@cindex Displaying citations ++@cindex Citations, displaying ++@cindex Citation info ++@cindex Viewing citations ++@kindex C-c & ++@kindex S-mouse-2 ++@findex reftex-view-crossref ++@findex reftex-mouse-view-crossref ++ ++When point is idle for more than @code{reftex-idle-time} seconds on the ++argument of a @code{\cite} macro, the echo area will display some ++information about the article cited there. Note that the information is ++only displayed if the echo area is not occupied by a different message. ++ ++@b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database ++entry corresponding to a @code{\cite} macro, or all citation locations ++corresponding to a @code{\bibitem} or BibTeX database entry. ++@xref{Viewing Cross-References}. ++ ++@node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations ++@section Chapterbib and Bibunits ++@cindex @code{chapterbib}, LaTeX package ++@cindex @code{bibunits}, LaTeX package ++@cindex Bibliographies, multiple ++ ++@code{chapterbib} and @code{bibunits} are two LaTeX packages which ++produce multiple bibliographies in a document. This is no problem for ++@b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database ++files. If they do not, it is best to have each document part in a ++separate file (as it is required for @code{chapterbib} anyway). Then ++@b{Ref@TeX{}} will still scan the locally relevant databases correctly. If ++you have multiple bibliographies within a @emph{single file}, this may ++or may not be the case. ++ ++@node Citations Outside LaTeX, BibTeX Database Subsets, Chapterbib and Bibunits, Citations ++@section Citations outside LaTeX ++@cindex Citations outside LaTeX ++@vindex reftex-default-bibliography ++ ++The command @code{reftex-citation} can also be executed outside a LaTeX ++buffer. This can be useful to reference articles in the mail buffer and ++other documents. You should @emph{not} enter @code{reftex-mode} for ++this, just execute the command. The list of BibTeX files will in this ++case be taken from the variable @code{reftex-default-bibliography}. ++Setting the variable @code{reftex-cite-format} to the symbol ++@code{locally} does a decent job of putting all relevant information ++about a citation directly into the buffer. Here is the lisp code to add ++the @kbd{C-c [} binding to the mail buffer. It also provides a local ++binding for @code{reftex-cite-format}. ++ ++@lisp ++(add-hook 'mail-setup-hook ++ (lambda () (define-key mail-mode-map "\C-c[" ++ (lambda () ++ (interactive) ++ (let ((reftex-cite-format 'locally)) ++ (reftex-citation)))))) ++@end lisp ++ ++@node BibTeX Database Subsets, , Citations Outside LaTeX, Citations ++@section Database Subsets ++@cindex BibTeX database subsets ++@findex reftex-create-bibtex-file ++ ++@b{Ref@TeX{}} offers two ways to create a new BibTeX database file. ++ ++The first option produces a file which contains only the entries ++actually referenced in the current document. This can be useful if ++the database in only meant for a single document and you want to clean ++it of old and unused ballast. It can also be useful while writing a ++document together with collaborators, in order to avoid sending around ++the entire (possibly very large) database. To create the file, use ++@kbd{M-x reftex-create-bibtex-file}, also available from the menu ++under @code{Ref->Global Actions->Create Bibtex File}. The command will ++prompt for a BibTeX file name and write the extracted entries to that ++file. ++ ++The second option makes use of the selection process started by the ++command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a ++regular expression to select entries, and lists them in a formatted ++selection buffer. After pressing the @kbd{e} key (mnemonics: Export), ++the command will prompt for the name of a new BibTeX file and write ++the selected entries to that file. You can also first mark some ++entries in the selection buffer with the @kbd{m} key and then export ++either the @i{marked} entries (with the @kbd{e} key) or the ++@i{unmarked} entries (with the @kbd{E} key). ++ ++@node Index Support, Viewing Cross-References, Citations, Top ++@chapter Index Support ++@cindex Index Support ++@cindex @code{\index} ++ ++LaTeX has builtin support for creating an Index. The LaTeX core ++supports two different indices, the standard index and a glossary. With ++the help of special LaTeX packages (@file{multind.sty} or ++@file{index.sty}), any number of indices can be supported. ++ ++Index entries are created with the @code{\index@{@var{entry}@}} macro. ++All entries defined in a document are written out to the @file{.aux} ++file. A separate tool must be used to convert this information into a ++nicely formatted index. Tools used with LaTeX include @code{MakeIndex} ++and @code{xindy}. ++ ++Indexing is a very difficult task. It must follow strict conventions to ++make the index consistent and complete. There are basically two ++approaches one can follow, and both have their merits. ++ ++@enumerate ++@item ++Part of the indexing should already be done with the markup. The ++document structure should be reflected in the index, so when starting ++new sections, the basic topics of the section should be indexed. If the ++document contains definitions, theorems or the like, these should all ++correspond to appropriate index entries. This part of the index can ++very well be developed along with the document. Often it is worthwhile ++to define special purpose macros which define an item and at the same ++time make an index entry, possibly with special formatting to make the ++reference page in the index bold or underlined. To make @b{Ref@TeX{}} ++support for indexing possible, these special macros must be added to ++@b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}). ++ ++@item ++The rest of the index is often just a collection of where in the ++document certain words or phrases are being used. This part is ++difficult to develop along with the document, because consistent entries ++for each occurrence are needed and are best selected when the document ++is ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file} ++which collects phrases and helps indexing the phrases globally. ++@end enumerate ++ ++Before you start, you need to make sure that @b{Ref@TeX{}} knows about ++the index style being used in the current document. @b{Ref@TeX{}} has ++builtin support for the default @code{\index} and @code{\glossary} ++macros. Other LaTeX packages, like the @file{multind} or @file{index} ++package, redefine the @code{\index} macro to have an additional ++argument, and @b{Ref@TeX{}} needs to be configured for those. A ++sufficiently new version of AUCTeX (9.10c or later) will do this ++automatically. If you really don't use AUCTeX (you should!), this ++configuration needs to be done by hand with the menu (@code{Ref->Index ++Style}), or globally for all your documents with ++ ++@lisp ++(setq reftex-index-macros '(multind)) @r{or} ++(setq reftex-index-macros '(index)) ++@end lisp ++ ++@menu ++* Creating Index Entries:: Macros and completion of entries. ++* The Index Phrases File:: A special file for global indexing. ++* Displaying and Editing the Index:: The index editor. ++* Builtin Index Macros:: The index macros RefTeX knows about. ++* Defining Index Macros:: ... and macros it doesn't. ++@end menu ++ ++@node Creating Index Entries, The Index Phrases File, , Index Support ++@section Creating Index Entries ++@cindex Creating index entries ++@cindex Index entries, creating ++@kindex C-c < ++@findex reftex-index ++@kindex C-c / ++@findex reftex-index-selection-or-word ++ ++In order to index the current selection or the word at the cursor press ++@kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the ++selection or word @samp{@var{word}} to be replaced with ++@samp{\index@{@var{word}@}@var{word}}. The macro which is used ++(@code{\index} by default) can be configured with the variable ++@code{reftex-index-default-macro}. When the command is called with a ++prefix argument (@kbd{C-u C-c /}), you get a chance to edit the ++generated index entry. Use this to change the case of the word or to ++make the entry a subentry, for example by entering ++@samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes ++(@kbd{C-u C-u C-c /}), you will be asked for the index macro as well. ++When there is nothing selected and no word at point, this command will ++just call @code{reftex-index}, described below. ++ ++In order to create a general index entry, press @kbd{C-c <} ++(@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the ++available index macros and for its arguments. Completion will be ++available for the index entry and, if applicable, the index tag. The ++index tag is a string identifying one of multiple indices. With the ++@file{multind} and @file{index} packages, this tag is the first argument ++to the redefined @code{\index} macro. ++ ++@node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support ++@section The Index Phrases File ++@cindex Index phrase file ++@cindex Phrase file ++@kindex C-c | ++@findex reftex-index-visit-phrases-buffer ++@cindex Macro definition lines, in phrase buffer ++ ++@b{Ref@TeX{}} maintains a file in which phrases can be collected for ++later indexing. The file is located in the same directory as the master ++file of the document and has the extension @file{.rip} (@b{R}eftex ++@b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c ++|} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it ++is initialized by inserting a file header which contains the definition ++of the available index macros. This list is initialized from ++@code{reftex-index-macros} (@pxref{Defining Index Macros}). You can ++edit the header as needed, but if you define new LaTeX indexing macros, ++don't forget to add them to @code{reftex-index-macros} as well. Here is ++a phrase file header example: ++ ++@example ++% -*- mode: reftex-index-phrases -*- ++% Key Macro Format Repeat ++%---------------------------------------------------------- ++>>>INDEX_MACRO_DEFINITION: i \index@{%s@} t ++>>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil ++>>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t ++>>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil ++%---------------------------------------------------------- ++@end example ++ ++The macro definition lines consist of a unique letter identifying a ++macro, a format string and the @var{repeat} flag, all separated by ++@key{TAB}. The format string shows how the macro is to be applied, the ++@samp{%s} will be replaced with the index entry. The repeat flag ++indicates if @var{word} is indexed by the macro as ++@samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as ++@samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the ++above example it is assumed that the macro @code{\index*@{@var{word}@}} ++already typesets its argument in the text, so that it is unnecessary to ++repeat @var{word} outside the macro. ++ ++@menu ++* Collecting Phrases:: Collecting from document or external. ++* Consistency Checks:: Check for duplicates etc. ++* Global Indexing:: The interactive indexing process. ++@end menu ++ ++@node Collecting Phrases, Consistency Checks, , The Index Phrases File ++@subsection Collecting Phrases ++@cindex Collecting index phrases ++@cindex Index phrases, collection ++@cindex Phrases, collecting ++ ++Phrases for indexing can be collected while writing the document. The ++command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) ++copies the current selection (if active) or the word near point into the ++phrases buffer. It then selects this buffer, so that the phrase line ++can be edited. To return to the LaTeX document, press @kbd{C-c C-c} ++(@code{reftex-index-phrases-save-and-return}). ++ ++You can also prepare the list of index phrases in a different way and ++copy it into the phrases file. For example you might want to start from ++a word list of the document and remove all words which should not be ++indexed. ++ ++The phrase lines in the phrase buffer must have a specific format. ++@b{Ref@TeX{}} will use font-lock to indicate if a line has the proper ++format. A phrase line looks like this: ++ ++@example ++[@var{key}] @var{phrase} [ @var{arg}[&&@var{arg}]... [ || @var{arg}]...] ++@end example ++ ++@code{} stands for white space containing at least one @key{TAB}. ++@var{key} must be at the start of the line and is the character ++identifying one of the macros defined in the file header. It is ++optional - when omitted, the first macro definition line in the file ++will be used for this phrase. The @var{phrase} is the phrase to be ++searched for when indexing. It may contain several words separated by ++spaces. By default the search phrase is also the text entered as ++argument of the index macro. If you want the index entry to be ++different from the search phrase, enter another @key{TAB} and the index ++argument @var{arg}. If you want to have each match produce several ++index entries, separate the different index arguments with @samp{ && ++}@footnote{@samp{&&} with optional spaces, see ++@code{reftex-index-phrases-logical-and-regexp}.}. If you want to be ++able to choose at each match between several different index arguments, ++separate them with @samp{ || }@footnote{@samp{||} with optional spaces, ++see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an ++example: ++ ++@example ++%-------------------------------------------------------------------- ++I Sun ++i Planet Planets ++i Vega Stars!Vega ++ Jupiter Planets!Jupiter ++i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars ++i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto ++@end example ++ ++ ++So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while ++@samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}. ++@samp{Vega} will be indexed as a subitem of @samp{Stars}. The ++@samp{Jupiter} line will also use the @samp{i} macro as it was the first ++macro definition in the file header (see above example). At each ++occurrence of @samp{Mars} you will be able choose between indexing it as ++a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}. ++Finally, every occurrence of @samp{Pluto} will be indexed as ++@samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto} ++and will therefore create two different index entries. ++ ++@node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File ++@subsection Consistency Checks ++@cindex Index phrases, consistency checks ++@cindex Phrases, consistency checks ++@cindex Consistency check for index phrases ++ ++@kindex C-c C-s ++Before indexing the phrases in the phrases buffer, they should be ++checked carefully for consistency. A first step is to sort the phrases ++alphabetically - this is done with the command @kbd{C-c C-s} ++(@code{reftex-index-sort-phrases}). It will sort all phrases in the ++buffer alphabetically by search phrase. If you want to group certain ++phrases and only sort within the groups, insert empty lines between the ++groups. Sorting will only change the sequence of phrases within each ++group (see the variable @code{reftex-index-phrases-sort-in-blocks}). ++ ++@kindex C-c C-i ++A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info}) ++which lists information about the phrase at point, including an example ++of how the index entry will look like and the number of expected matches ++in the document. ++ ++@kindex C-c C-t ++Another important check is to find out if there are double or ++overlapping entries in the buffer. For example if you are first ++searching and indexing @samp{Mars} and then @samp{Planet Mars}, the ++second phrase will not match because of the index macro inserted before ++@samp{Mars} earlier. The command @kbd{C-c C-t} ++(@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in ++the buffer which is either duplicate or a subphrase of another phrase. ++In order to check the whole buffer like this, start at the beginning and ++execute this command repeatedly. ++ ++@node Global Indexing, , Consistency Checks, The Index Phrases File ++@subsection Global Indexing ++@cindex Global indexing ++@cindex Indexing, global ++@cindex Indexing, from @file{phrases} buffer ++ ++Once the index phrases have been collected and organized, you are set ++for global indexing. I recommend to do this only on an otherwise ++finished document. Global indexing starts from the phrases buffer. ++There are several commands which start indexing: @kbd{C-c C-x} acts on ++the current phrase line, @kbd{C-c C-r} on all lines in the current ++region and @kbd{C-c C-a} on all phrase lines in the buffer. It is ++probably good to do indexing in small chunks since your concentration ++may not last long enough to do everything in one go. ++ ++@b{Ref@TeX{}} will start at the first phrase line and search the phrase ++globally in the whole document. At each match it will stop, compute the ++replacement string and offer you the following choices@footnote{Windows ++users: Restrict yourself to the described keys during indexing. Pressing ++@key{Help} at the indexing prompt can apparently hang Emacs.}: ++ ++@table @kbd ++@item y ++Replace this match with the proposed string. ++@item n ++Skip this match. ++@item ! ++Replace this and all further matches in this file. ++@item q ++Skip this match, start with next file. ++@item Q ++Skip this match, start with next phrase. ++@item o ++Select a different indexing macro for this match. ++@item 1-9 ++Select one of multiple index keys (those separated with @samp{||}). ++@item e ++Edit the replacement text. ++@item C-r ++Recursive edit. Use @kbd{C-M-c} to return to the indexing process. ++@item s ++Save this buffer and ask again about the current match. ++@item S ++Save all document buffers and ask again about the current match. ++@item C-g ++Abort the indexing process. ++@end table ++ ++The @samp{Find and Index in Document} menu in the phrases buffer also ++lists a few options for the indexing process. The options have ++associated customization variables to set the defaults (@pxref{Options ++(Index Support)}). Here is a short explanation of what the options do: ++ ++@table @i ++@item Match Whole Words ++When searching for index phrases, make sure whole words are matched. ++This should probably always be on. ++@item Case Sensitive Search ++Search case sensitively for phrases. I recommend to have this setting ++off, in order to match the capitalized words at the beginning of a ++sentence, and even typos. You can always say @emph{no} at a match you ++do not like. ++@item Wrap Long Lines ++Inserting index macros increases the line length. Turn this option on ++to allow @b{Ref@TeX{}} to wrap long lines. ++@item Skip Indexed Matches ++When this is on, @b{Ref@TeX{}} will at each match try to figure out if ++this match is already indexed. A match is considered indexed if it is ++either the argument of an index macro, or if an index macro is directly ++(without whitespace separation) before or after the match. Index macros ++are those configured in @code{reftex-index-macros}. Intended for ++re-indexing a documents after changes have been made. ++@end table ++ ++Even though indexing should be the last thing you do to a document, you ++are bound to make changes afterwards. Indexing then has to be applied ++to the changed regions. The command ++@code{reftex-index-phrases-apply-to-region} is designed for this ++purpose. When called from a LaTeX document with active region, it will ++apply @code{reftex-index-all-phrases} to the current region. ++ ++@node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support ++@section Displaying and Editing the Index ++@cindex Displaying the Index ++@cindex Editing the Index ++@cindex Index entries, creating ++@cindex Index, displaying ++@cindex Index, editing ++@kindex C-c > ++@findex reftex-display-index ++ ++In order to compile and display the index, press @kbd{C-c >}. If the ++document uses multiple indices, @b{Ref@TeX{}} will ask you to select ++one. Then, all index entries will be sorted alphabetically and ++displayed in a special buffer, the @file{*Index*} buffer. From that ++buffer you can check and edit each entry. ++ ++The index can be restricted to the current section or the region. Then ++only entries in that part of the document will go into the compiled ++index. To restrict to the current section, use a numeric prefix ++@samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current ++region, make the region active and use a numeric prefix @samp{3} (press ++@kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the ++restriction can be moved from one section to the next by pressing the ++@kbd{<} and @kbd{>} keys. ++ ++One caveat: @b{Ref@TeX{}} finds the definition point of an index entry ++by searching near the buffer position where it had found to macro during ++scanning. If you have several identical index entries in the same ++buffer and significant changes have shifted the entries around, you must ++rescan the buffer to ensure the correspondence between the ++@file{*Index*} buffer and the definition locations. It is therefore ++advisable to rescan the document (with @kbd{r} or @kbd{C-u r}) ++frequently while editing the index from the @file{*Index*} ++buffer. ++ ++@kindex ? ++Here is a list of special commands available in the @file{*Index*} buffer. A ++summary of this information is always available by pressing ++@kbd{?}. ++ ++@table @kbd ++@tablesubheading{General} ++@item ? ++Display a summary of commands. ++ ++@item 0-9, - ++Prefix argument. ++ ++@tablesubheading{Moving around} ++@item ! A..Z ++Pressing any capital letter will jump to the corresponding section in ++the @file{*Index*} buffer. The exclamation mark is special and jumps to ++the first entries alphabetically sorted below @samp{A}. These are ++usually non-alphanumeric characters. ++@item n ++Go to next entry. ++@item p ++Go to previous entry. ++ ++@tablesubheading{Access to document locations} ++@item @key{SPC} ++Show the place in the document where this index entry is defined. ++ ++@item @key{TAB} ++Go to the definition of the current index entry in another ++window. ++ ++@item @key{RET} ++Go to the definition of the current index entry and hide the ++@file{*Index*} buffer window. ++ ++@item f ++@vindex reftex-index-follow-mode ++@vindex reftex-revisit-to-follow ++Toggle follow mode. When follow mode is active, the other window will ++always show the location corresponding to the line in the @file{*Index*} ++buffer at point. This is similar to pressing @key{SPC} after each ++cursor motion. The default for this flag can be set with the variable ++@code{reftex-index-follow-mode}. Note that only context in files ++already visited is shown. @b{Ref@TeX{}} will not visit a file just for ++follow mode. See, however, the variable ++@code{reftex-revisit-to-follow}. ++ ++@tablesubheading{Entry editing} ++@item e ++Edit the current index entry. In the minibuffer, you can edit the ++index macro which defines this entry. ++ ++@item C-k ++Kill the index entry. Currently not implemented because I don't know ++how to implement an @code{undo} function for this. ++ ++@item * ++Edit the @var{key} part of the entry. This is the initial part of the ++entry which determines the location of the entry in the index. ++ ++@item | ++Edit the @var{attribute} part of the entry. This is the part after the ++vertical bar. With @code{MakeIndex}, this part is an encapsulating ++macro. With @code{xindy}, it is called @emph{attribute} and is a ++property of the index entry that can lead to special formatting. When ++called with @kbd{C-u} prefix, kill the entire @var{attribute} ++part. ++ ++@item @@ ++Edit the @var{visual} part of the entry. This is the part after the ++@samp{@@} which is used by @code{MakeIndex} to change the visual ++appearance of the entry in the index. When called with @kbd{C-u} ++prefix, kill the entire @var{visual} part. ++ ++@item ( ++Toggle the beginning of page range property @samp{|(} of the ++entry. ++ ++@item ) ++Toggle the end of page range property @samp{|)} of the entry. ++ ++@item _ ++Make the current entry a subentry. This command will prompt for the ++superordinate entry and insert it. ++ ++@item ^ ++Remove the highest superordinate entry. If the current entry is a ++subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy ++(@samp{bbb!ccc}). ++ ++@tablesubheading{Exiting} ++@item q ++Hide the @file{*Index*} buffer. ++ ++@item k ++Kill the @file{*Index*} buffer. ++ ++@item C-c = ++Switch to the Table of Contents buffer of this document. ++ ++@tablesubheading{Controlling what gets displayed} ++@item c ++@vindex reftex-index-include-context ++Toggle the display of short context in the @file{*Index*} buffer. The ++default for this flag can be set with the variable ++@code{reftex-index-include-context}. ++ ++@item @} ++Restrict the index to a single document section. The corresponding ++section number will be displayed in the @code{R<>} indicator in the ++mode line and in the header of the @file{*Index*} buffer. ++ ++@item @{ ++Widen the index to contain all entries of the document. ++ ++@item < ++When the index is currently restricted, move the restriction to the ++previous section. ++ ++@item > ++When the index is currently restricted, move the restriction to the ++next section. ++ ++@tablesubheading{Updating the buffer} ++@item g ++Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the ++document. However, it sorts the entries again, so that edited entries ++will move to the correct position. ++ ++@item r ++@vindex reftex-enable-partial-scans ++Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When ++@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this ++location is defined in, not the entire document. ++ ++@item C-u r ++Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*} ++buffer. ++ ++@item s ++Switch to a different index (for documents with multiple ++indices). ++@end table ++ ++ ++@node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support ++@section Builtin Index Macros ++@cindex Builtin index macros ++@cindex Index macros, builtin ++@vindex reftex-index-macros ++@cindex @code{multind}, LaTeX package ++@cindex @code{index}, LaTeX package ++@cindex LaTeX packages, @code{multind} ++@cindex LaTeX packages, @code{index} ++ ++@b{Ref@TeX{}} by default recognizes the @code{\index} and ++@code{\glossary} macros which are defined in the LaTeX core. It has ++also builtin support for the re-implementations of @code{\index} ++in the @file{multind} and @file{index} packages. However, since ++the different definitions of the @code{\index} macro are incompatible, ++you will have to explicitly specify the index style used. ++@xref{Creating Index Entries}, for information on how to do that. ++ ++@node Defining Index Macros, , Builtin Index Macros, Index Support ++@section Defining Index Macros ++@cindex Defining Index Macros ++@cindex Index macros, defining ++@vindex reftex-index-macros ++ ++When writing a document with an index you will probably define ++additional macros which make entries into the index. ++Let's look at an example. ++ ++@example ++\newcommand@{\ix@}[1]@{#1\index@{#1@}@} ++\newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@} ++\newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@} ++@end example ++ ++The first macro @code{\ix} typesets its argument in the text and places ++it into the index. The second macro @code{\nindex} typesets its ++argument in the text and places it into a separate index with the tag ++@samp{name}@footnote{We are using the syntax of the @file{index} package ++here.}. The last macro also places its argument into the index, but as ++subitems under the main index entry @samp{Astronomical Objects}. Here ++is how to make @b{Ref@TeX{}} recognize and correctly interpret these ++macros, first with Emacs Lisp. ++ ++@lisp ++(setq reftex-index-macros ++ '(("\\ix@{*@}" "idx" ?x "" nil nil) ++ ("\\nindex@{*@}" "name" ?n "" nil nil) ++ ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t))) ++@end lisp ++ ++Note that the index tag is @samp{idx} for the main index, and ++@samp{name} for the name index. @samp{idx} and @samp{glo} are reserved ++for the default index and for the glossary. ++ ++The character arguments @code{?x}, @code{?n}, and @code{?o} are for ++quick identification of these macros when @b{Ref@TeX{}} inserts new ++index entries with @code{reftex-index}. These codes need to be ++unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the ++@code{\index}, @code{\index*}, and @code{\glossary} macros, ++respectively. ++ ++The following string is empty unless your macro adds a superordinate ++entry to the index key - this is the case for the @code{\astobj} macro. ++ ++The next entry can be a hook function to exclude certain matches, it ++almost always can be @code{nil}. ++ ++The final element in the list indicates if the text being indexed needs ++to be repeated outside the macro. For the normal index macros, this ++should be @code{t}. Only if the macro typesets the entry in the text ++(like @code{\ix} and @code{\nindex} in the example do), this should be ++@code{nil}. ++ ++To do the same thing with customize, you need to fill in the templates ++like this: ++ ++@example ++Repeat: ++[INS] [DEL] List: ++ Macro with args: \ix@{*@} ++ Index Tag : [Value Menu] String: idx ++ Access Key : x ++ Key Prefix : ++ Exclusion hook : nil ++ Repeat Outside : [Toggle] off (nil) ++[INS] [DEL] List: ++ Macro with args: \nindex@{*@} ++ Index Tag : [Value Menu] String: name ++ Access Key : n ++ Key Prefix : ++ Exclusion hook : nil ++ Repeat Outside : [Toggle] off (nil) ++[INS] [DEL] List: ++ Macro with args: \astobj@{*@} ++ Index Tag : [Value Menu] String: idx ++ Access Key : o ++ Key Prefix : Astronomical Objects! ++ Exclusion hook : nil ++ Repeat Outside : [Toggle] on (non-nil) ++[INS] ++@end example ++ ++With the macro @code{\ix} defined, you may want to change the default ++macro used for indexing a text phrase (@pxref{Creating Index Entries}). ++This would be done like this ++ ++@lisp ++(setq reftex-index-default-macro '(?x "idx")) ++@end lisp ++ ++which specifies that the macro identified with the character @code{?x} (the ++@code{\ix} macro) should be used for indexing phrases and words already ++in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}). ++The index tag is "idx". ++ ++@node Viewing Cross-References, RefTeXs Menu, Index Support, Top ++@chapter Viewing Cross--References ++@findex reftex-view-crossref ++@findex reftex-mouse-view-crossref ++@kindex C-c & ++@kindex S-mouse-2 ++ ++@b{Ref@TeX{}} can display cross--referencing information. This means, ++if two document locations are linked, @b{Ref@TeX{}} can display the ++matching location(s) in another window. The @code{\label} and @code{\ref} ++macros are one way of establishing such a link. Also, a @code{\cite} ++macro is linked to the corresponding @code{\bibitem} macro or a BibTeX ++database entry. ++ ++The feature is invoked by pressing @kbd{C-c &} ++(@code{reftex-view-crossref}) while point is on the @var{key} argument ++of a macro involved in cross--referencing. You can also click with ++@kbd{S-mouse-2} on the macro argument. Here is what will happen for ++individual classes of macros: ++ ++@table @asis ++ ++@item @code{\ref} ++@cindex @code{\ref} ++Display the corresponding label definition. All usual ++variants@footnote{all macros that start with @samp{ref} or end with ++@samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for ++cross--reference display. This works also for labels defined in an ++external document when the current document refers to them through the ++@code{xr} interface (@pxref{xr (LaTeX package)}). ++ ++@item @code{\label} ++@cindex @code{\label} ++@vindex reftex-label-alist ++Display a document location which references this label. Pressing ++@kbd{C-c &} several times moves through the entire document and finds ++all locations. Not only the @code{\label} macro but also other macros ++with label arguments (as configured with @code{reftex-label-alist}) are ++active for cross--reference display. ++ ++@item @code{\cite} ++@cindex @code{\cite} ++Display the corresponding BibTeX database entry or @code{\bibitem}. ++All usual variants@footnote{all macros that either start or end with ++@samp{cite}} of the @code{\cite} macro are active for cross--reference ++display. ++ ++@item @code{\bibitem} ++@cindex @code{\bibitem} ++Display a document location which cites this article. Pressing ++@kbd{C-c &} several times moves through the entire document and finds ++all locations. ++ ++@item BibTeX ++@cindex BibTeX buffer, viewing cite locations from ++@cindex Viewing cite locations from BibTeX buffer ++@kbd{C-c &} is also active in BibTeX buffers. All locations in a ++document where the database entry at point is cited will be displayed. ++On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to ++the document you want to search. Subsequent calls will use the same ++document, until you break this link with a prefix argument to @kbd{C-c ++&}. ++ ++@item @code{\index} ++@cindex @code{\index} ++Display other locations in the document which are marked by an index ++macro with the same key argument. Along with the standard @code{\index} ++and @code{\glossary} macros, all macros configured in ++@code{reftex-index-macros} will be recognized. ++@end table ++ ++@vindex reftex-view-crossref-extra ++While the display of cross referencing information for the above ++mentioned macros is hard--coded, you can configure additional relations ++in the variable @code{reftex-view-crossref-extra}. ++ ++@iftex ++@chapter All the Rest ++@end iftex ++ ++@node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top ++@section @b{Ref@TeX{}}'s Menu ++@cindex RefTeXs Menu ++@cindex Menu, in the menu bar ++ ++@b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems ++which support this. From this menu you can access all of ++@b{Ref@TeX{}}'s commands and a few of its options. There is also a ++@code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s ++entire set of options. ++ ++@node Key Bindings, Faces, RefTeXs Menu, Top ++@section Default Key Bindings ++@cindex Key Bindings, summary ++ ++Here is a summary of the available key bindings. ++ ++@kindex C-c = ++@kindex C-c - ++@kindex C-c ( ++@kindex C-c ) ++@kindex C-c [ ++@kindex C-c & ++@kindex S-mouse-2 ++@kindex C-c / ++@kindex C-c \ ++@kindex C-c | ++@kindex C-c < ++@kindex C-c > ++@example ++@kbd{C-c =} @code{reftex-toc} ++@kbd{C-c -} @code{reftex-toc-recenter} ++@kbd{C-c (} @code{reftex-label} ++@kbd{C-c )} @code{reftex-reference} ++@kbd{C-c [} @code{reftex-citation} ++@kbd{C-c &} @code{reftex-view-crossref} ++@kbd{S-mouse-2} @code{reftex-mouse-view-crossref} ++@kbd{C-c /} @code{reftex-index-selection-or-word} ++@kbd{C-c \} @code{reftex-index-phrase-selection-or-word} ++@kbd{C-c |} @code{reftex-index-visit-phrases-buffer} ++@kbd{C-c <} @code{reftex-index} ++@kbd{C-c >} @code{reftex-display-index} ++@end example ++ ++Note that the @kbd{S-mouse-2} binding is only provided if this key is ++not already used by some other package. @b{Ref@TeX{}} will not override an ++existing binding to @kbd{S-mouse-2}. ++ ++Personally, I also bind some functions in the users @kbd{C-c} map for ++easier access. ++ ++@c FIXME: Do we need bindings for the Index macros here as well? ++@c C-c i C-c I or so???? ++@c How about key bindings for reftex-reset-mode and reftex-parse-document? ++@kindex C-c t ++@kindex C-c l ++@kindex C-c r ++@kindex C-c c ++@kindex C-c v ++@kindex C-c s ++@kindex C-c g ++@example ++@kbd{C-c t} @code{reftex-toc} ++@kbd{C-c l} @code{reftex-label} ++@kbd{C-c r} @code{reftex-reference} ++@kbd{C-c c} @code{reftex-citation} ++@kbd{C-c v} @code{reftex-view-crossref} ++@kbd{C-c s} @code{reftex-search-document} ++@kbd{C-c g} @code{reftex-grep-document} ++@end example ++ ++@noindent These keys are reserved for the user, so I cannot bind them by ++default. If you want to have these key bindings available, set in your ++@file{.emacs} file: ++ ++@vindex reftex-extra-bindings ++@lisp ++(setq reftex-extra-bindings t) ++@end lisp ++ ++@vindex reftex-load-hook ++Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook ++@code{reftex-load-hook}. For information on the keymaps ++which should be used to add keys, see @ref{Keymaps and Hooks}. ++ ++@node Faces, AUCTeX, Key Bindings, Top ++@section Faces ++@cindex Faces ++ ++@b{Ref@TeX{}} uses faces when available to structure the selection and ++table of contents buffers. It does not create its own faces, but uses ++the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will ++use faces only when @code{font-lock} is loaded. This seems to be ++reasonable because people who like faces will very likely have it ++loaded. If you wish to turn off fontification or change the involved ++faces, see @ref{Options (Fontification)}. ++ ++@node Multifile Documents, Language Support, AUCTeX, Top ++@section Multifile Documents ++@cindex Multifile documents ++@cindex Documents, spread over files ++ ++The following is relevant when working with documents spread over many ++files: ++ ++@itemize @bullet ++@item ++@b{Ref@TeX{}} has full support for multifile documents. You can edit parts of ++several (multifile) documents at the same time without conflicts. ++@b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and ++@code{query-replace} on all files which are part of a multifile ++document. ++ ++@item ++@vindex tex-main-file ++@vindex TeX-master ++All files belonging to a multifile document should define a File ++Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the ++standard Emacs LaTeX mode) containing the name of the master file. For ++example, to set the file variable @code{TeX-master}, include something ++like the following at the end of each TeX file: ++ ++@example ++%%% Local Variables: *** ++%%% mode:latex *** ++%%% TeX-master: "thesis.tex" *** ++%%% End: *** ++@end example ++ ++AUCTeX with the setting ++ ++@lisp ++(setq-default TeX-master nil) ++@end lisp ++ ++will actually ask you for each new file about the master file and insert ++this comment automatically. For more details see the documentation of ++the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the ++documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs, ++The GNU Emacs Manual}) and the Emacs documentation on File Variables ++(@pxref{File Variables,,,emacs, The GNU Emacs Manual}). ++ ++@item ++The context of a label definition must be found in the same file as the ++label itself in order to be processed correctly by @b{Ref@TeX{}}. The only ++exception is that section labels referring to a section statement ++outside the current file can still use that section title as ++context. ++@end itemize ++ ++@node Language Support, Finding Files, Multifile Documents, Top ++@section Language Support ++@cindex Language support ++ ++Some parts of @b{Ref@TeX{}} are language dependent. The default ++settings work well for English. If you are writing in a different ++language, the following hints may be useful: ++ ++@itemize @bullet ++@item ++@vindex reftex-derive-label-parameters ++@vindex reftex-abbrev-parameters ++The mechanism to derive a label from context includes the abbreviation ++of words and omission of unimportant words. These mechanisms may have ++to be changed for other languages. See the variables ++@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}. ++ ++@item ++@vindex reftex-translate-to-ascii-function ++@vindex reftex-label-illegal-re ++Also, when a label is derived from context, @b{Ref@TeX{}} clears the ++context string from non-ASCII characters in order to make a valid label. ++If there should ever be a version of @TeX{} which allows extended ++characters @emph{in labels}, then we will have to look at the ++variables @code{reftex-translate-to-ascii-function} and ++@code{reftex-label-illegal-re}. ++ ++@item ++When a label is referenced, @b{Ref@TeX{}} looks at the word before point ++to guess which label type is required. These @emph{magic words} are ++different in every language. For an example of how to add magic words, ++see @ref{Adding Magic Words}. ++ ++@vindex reftex-multiref-punctuation ++@vindex reftex-cite-punctuation ++@item ++@b{Ref@TeX{}} inserts ``punctuation'' for multiple references and ++for the author list in citations. Some of this may be language ++dependent. See the variables @code{reftex-multiref-punctuation} and ++@code{reftex-cite-punctuation}. ++@end itemize ++ ++@node Finding Files, Optimizations, Language Support, Top ++@section Finding Files ++@cindex Finding files ++ ++In order to find files included in a document via @code{\input} or ++@code{\include}, @b{Ref@TeX{}} searches all directories specified in the ++environment variable @code{TEXINPUTS}. Similarly, it will search the ++path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for ++BibTeX database files. ++ ++When searching, @b{Ref@TeX{}} will also expand recursive path ++definitions (directories ending in @samp{//} or @samp{!!}). But it will ++only search and expand directories @emph{explicitly} given in these ++variables. This may cause problems under the following circumstances: ++ ++@itemize @bullet ++@item ++Most TeX system have a default search path for both TeX files and BibTeX ++files which is defined in some setup file. Usually this default path is ++for system files which @b{Ref@TeX{}} does not need to see. But if your ++document needs TeX files or BibTeX database files in a directory only ++given in the default search path, @b{Ref@TeX{}} will fail to find them. ++@item ++Some TeX systems do not use environment variables at all in order to ++specify the search path. Both default and user search path are then ++defined in setup files. ++@end itemize ++ ++@noindent ++There are three ways to solve this problem: ++ ++@itemize @bullet ++@item ++Specify all relevant directories explicitly in the environment ++variables. If for some reason you don't want to mess with the default ++variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own ++variables and configure @b{Ref@TeX{}} to use them instead: ++ ++@lisp ++(setq reftex-texpath-environment-variables '("MYTEXINPUTS")) ++(setq reftex-bibpath-environment-variables '("MYBIBINPUTS")) ++@end lisp ++ ++@item ++Specify the full search path directly in @b{Ref@TeX{}}'s variables. ++ ++@lisp ++(setq reftex-texpath-environment-variables ++ '("./inp:/home/cd/tex//:/usr/local/tex//")) ++(setq reftex-bibpath-environment-variables ++ '("/home/cd/tex/lit/")) ++@end lisp ++ ++@item ++Some TeX systems provide stand--alone programs to do the file search just ++like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the ++@code{kpathsearch} library which provides the command @code{kpsewhich} ++to search for files. @b{Ref@TeX{}} can be configured to use this ++program. Note that the exact syntax of the @code{kpsewhich} ++command depends upon the version of that program. ++ ++@lisp ++(setq reftex-use-external-file-finders t) ++(setq reftex-external-file-finders ++ '(("tex" . "kpsewhich -format=.tex %f") ++ ("bib" . "kpsewhich -format=.bib %f"))) ++@end lisp ++@end itemize ++ ++@cindex Noweb files ++@vindex reftex-file-extensions ++@vindex TeX-file-extensions ++Some people like to use RefTeX with noweb files, which usually have the ++extension @file{.nw}. In order to deal with such files, the new ++extension must be added to the list of valid extensions in the variable ++@code{reftex-file-extensions}. When working with AUCTeX as major mode, ++the new extension must also be known to AUCTeX via the variable ++@code{TeX-file-extension}. For example: ++ ++@lisp ++(setq reftex-file-extensions ++ '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib"))) ++(setq TeX-file-extensions ++ '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo")) ++@end lisp ++ ++@node Optimizations, Problems and Work-Arounds, Finding Files, Top ++@section Optimizations ++@cindex Optimizations ++ ++@b{Note added 2002. Computers have gotten a lot faster, so most of the ++optimizations discussed below will not be necessary on new machines. I ++am leaving this stuff in the manual for people who want to write thick ++books, where some of it still might be useful.} ++ ++Implementing the principle of least surprises, the default settings of ++@b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However, ++when using @b{Ref@TeX{}} for a large project and/or on a small computer, ++there are ways to improve speed or memory usage. ++ ++@itemize @bullet ++@item ++@b{Removing Lookup Buffers}@* ++@cindex Removing lookup buffers ++@b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX ++database files for lookup purposes. These buffers are kept, so that ++subsequent use of the same files is fast. If you can't afford keeping ++these buffers around, and if you can live with a speed penalty, try ++ ++@vindex reftex-keep-temporary-buffers ++@lisp ++(setq reftex-keep-temporary-buffers nil) ++@end lisp ++ ++@item ++@b{Partial Document Scans}@* ++@cindex Partial documents scans ++@cindex Document scanning, partial ++A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label} ++(@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}), ++@code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c ++=}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates ++re-parsing of the entire document in order to update the parsing ++information. For a large document this can be unnecessary, in ++particular if only one file has changed. @b{Ref@TeX{}} can be configured ++to do partial scans instead of full ones. @kbd{C-u} re-parsing then ++does apply only to the current buffer and files included from it. ++Likewise, the @kbd{r} key in both the label selection buffer and the ++table-of-contents buffer will only prompt scanning of the file in which ++the label or section macro near the cursor was defined. Re-parsing of ++the entire document is still available by using @kbd{C-u C-u} as a ++prefix, or the capital @kbd{R} key in the menus. To use this feature, ++try ++ ++@vindex reftex-enable-partial-scans ++@lisp ++(setq reftex-enable-partial-scans t) ++@end lisp ++ ++@item ++@b{Saving Parser Information}@* ++@cindex Saving parser information ++@cindex Parse information, saving to a file ++@vindex reftex-parse-file-extension ++Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full ++scan, when you start working with a document. To avoid this, parsing ++information can be stored in a file. The file @file{MASTER.rel} is used ++for storing information about a document with master file ++@file{MASTER.tex}. It is written automatically when you kill a buffer ++in @code{reftex-mode} or when you exit Emacs. The information is ++restored when you begin working with a document in a new editing ++session. To use this feature, put into @file{.emacs}: ++ ++@vindex reftex-save-parse-info ++@lisp ++(setq reftex-save-parse-info t) ++@end lisp ++ ++@item ++@b{Identifying label types by prefix}@* ++@cindex Parse information, saving to a file ++@vindex reftex-trust-label-prefix ++@b{Ref@TeX{}} normally parses around each label to check in which ++environment this label is located, in order to assign a label type to ++the label. If your document contains thousands of labels, document ++parsing will take considerable time. If you have been using label prefixes ++like tab: and fn: consistently, you can tell @b{Ref@TeX{}} to get the ++label type directly from the prefix, without additional parsing. This ++will be faster and also allow labels to end up in the correct category ++if for some reason it is not possible to derive the correct type from ++context. For example, to enable this feature for footnote and ++equation labels, use ++ ++@lisp ++(setq reftex-trust-label-prefix '("fn:" "eq:")) ++@end lisp ++ ++@item ++@b{Automatic Document Scans}@* ++@cindex Automatic document scans ++@cindex Document scanning, automatic ++At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the ++document. If this gets into your way, it can be turned off with ++ ++@vindex reftex-allow-automatic-rescan ++@lisp ++(setq reftex-allow-automatic-rescan nil) ++@end lisp ++ ++@b{Ref@TeX{}} will then occasionally annotate new labels in the selection ++buffer, saying that their position in the label list in uncertain. A ++manual document scan will fix this. ++ ++@item ++@b{Multiple Selection Buffers}@* ++@cindex Multiple selection buffers ++@cindex Selection buffers, multiple ++Normally, the selection buffer @file{*RefTeX Select*} is re-created for ++every selection process. In documents with very many labels this can ++take several seconds. @b{Ref@TeX{}} provides an option to create a ++separate selection buffer for each label type and to keep this buffer ++from one selection to the next. These buffers are updated automatically ++only when a new label has been added in the buffers category with ++@code{reftex-label}. Updating the buffer takes as long as recreating it ++- so the time saving is limited to cases where no new labels of that ++category have been added. To turn on this feature, use ++ ++@vindex reftex-use-multiple-selection-buffers ++@lisp ++(setq reftex-use-multiple-selection-buffers t) ++@end lisp ++ ++@noindent ++@cindex Selection buffers, updating ++You can also inhibit the automatic updating entirely. Then the ++selection buffer will always pop up very fast, but may not contain the ++most recently defined labels. You can always update the buffer by hand, ++with the @kbd{g} key. To get this behavior, use instead ++ ++@vindex reftex-auto-update-selection-buffers ++@lisp ++(setq reftex-use-multiple-selection-buffers t ++ reftex-auto-update-selection-buffers nil) ++@end lisp ++@end itemize ++ ++@need 2000 ++@noindent ++@b{As a summary}, here are the settings I recommend for heavy use of ++@b{Ref@TeX{}} with large documents: ++ ++@lisp ++@group ++(setq reftex-enable-partial-scans t ++ reftex-save-parse-info t ++ reftex-use-multiple-selection-buffers t) ++@end group ++@end lisp ++ ++@node AUCTeX, Multifile Documents, Faces, Top ++@section AUC@TeX{} ++@cindex @code{AUCTeX}, Emacs package ++@cindex Emacs packages, @code{AUCTeX} ++ ++AUCTeX is without doubt the best major mode for editing TeX and LaTeX ++files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}). ++If AUCTeX is not part of your Emacs distribution, you can get ++it@footnote{XEmacs 21.x users may want to install the corresponding ++XEmacs package.} by ftp from the @value{AUCTEXSITE}. ++ ++@menu ++* AUCTeX-RefTeX Interface:: How both packages work together ++* Style Files:: AUCTeX's style files can support RefTeX ++* Bib-Cite:: Hypertext reading of a document ++@end menu ++ ++@node AUCTeX-RefTeX Interface, Style Files, , AUCTeX ++@subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface ++ ++@b{Ref@TeX{}} contains code to interface with AUCTeX. When this ++interface is turned on, both packages will interact closely. Instead of ++using @b{Ref@TeX{}}'s commands directly, you can then also use them ++indirectly as part of the AUCTeX ++environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be ++needed for all of this to work. Parts of it work also with earlier ++versions.}. The interface is turned on with ++ ++@lisp ++(setq reftex-plug-into-AUCTeX t) ++@end lisp ++ ++If you need finer control about which parts of the interface are used ++and which not, read the docstring of the variable ++@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x ++customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}. ++ ++The following list describes the individual parts of the interface. ++ ++@itemize @bullet ++@item ++@findex reftex-label ++@vindex LaTeX-label-function, @r{AUCTeX} ++@kindex C-c C-e ++@kindex C-c C-s ++@findex LaTeX-section, @r{AUCTeX} ++@findex TeX-insert-macro, @r{AUCTeX} ++@b{AUCTeX calls @code{reftex-label} to insert labels}@* ++When a new section is created with @kbd{C-c C-s}, or a new environment ++is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to ++go with it. With the interface, @code{reftex-label} is called instead. ++For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and ++@b{Ref@TeX{}} will insert ++ ++@example ++\begin@{equation@} ++\label@{eq:1@} ++ ++\end@{equation@} ++@end example ++ ++@noindent ++without further prompts. ++ ++Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}} ++will offer its default label which is derived from the section title. ++ ++@item ++@b{AUCTeX tells @b{Ref@TeX{}} about new sections}@* ++When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not ++have to rescan the buffer in order to see it. ++ ++@item ++@findex reftex-arg-label ++@findex TeX-arg-label, @r{AUCTeX function} ++@findex reftex-arg-ref ++@findex TeX-arg-ref, @r{AUCTeX function} ++@findex reftex-arg-cite ++@findex TeX-arg-cite, @r{AUCTeX function} ++@findex reftex-arg-index ++@findex TeX-arg-index, @r{AUCTeX function} ++@findex TeX-insert-macro, @r{AUCTeX function} ++@kindex C-c @key{RET} ++@b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro ++interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for ++macro arguments. Internally, it uses the functions ++@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to ++prompt for arguments which are labels, citation keys and index entries. ++The interface takes over these functions@footnote{@code{fset} is used to ++do this, which is not reversible. However, @b{Ref@TeX{}} implements the ++old functionality when you later decide to turn off the interface.} and ++supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For ++example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}} ++will supply its label selection process (@pxref{Referencing ++Labels}). ++ ++@item ++@b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@* ++@b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list. ++@end itemize ++ ++@node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX ++@subsection Style Files ++@cindex Style files, AUCTeX ++@findex TeX-add-style-hook, @r{AUCTeX} ++Style files are Emacs Lisp files which are evaluated by AUCTeX in ++association with the @code{\documentclass} and @code{\usepackage} ++commands of a document (@pxref{Style Files,,,auctex}). Support for ++@b{Ref@TeX{}} in such a style file is useful when the LaTeX style ++defines macros or environments connected with labels, citations, or the ++index. Many style files (e.g. @file{amsmath.el} or @file{natbib.el}) ++distributed with AUCTeX already support @b{Ref@TeX{}} in this ++way. ++ ++Before calling a @b{Ref@TeX{}} function, the style hook should always ++test for the availability of the function, so that the style file will ++also work for people who do not use @b{Ref@TeX{}}. ++ ++Additions made with style files in the way described below remain local ++to the current document. For example, if one package uses AMSTeX, the ++style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but ++this will not affect other documents. ++ ++@findex reftex-add-label-environments ++@findex reftex-add-to-label-alist ++A style hook may contain calls to ++@code{reftex-add-label-environments}@footnote{This used to be the ++function @code{reftex-add-to-label-alist} which is still available as an ++alias for compatibility.} which defines additions to ++@code{reftex-label-alist}. The argument taken by this function must have ++the same format as @code{reftex-label-alist}. The @file{amsmath.el} ++style file of AUCTeX for example contains the following: ++ ++@lisp ++@group ++(TeX-add-style-hook "amsmath" ++ (lambda () ++ (if (fboundp 'reftex-add-label-environments) ++ (reftex-add-label-environments '(AMSTeX))))) ++@end group ++@end lisp ++ ++@noindent ++@findex LaTeX-add-environments, @r{AUCTeX} ++while a package @code{myprop} defining a @code{proposition} environment ++with @code{\newtheorem} might use ++ ++@lisp ++@group ++(TeX-add-style-hook "myprop" ++ (lambda () ++ (LaTeX-add-environments '("proposition" LaTeX-env-label)) ++ (if (fboundp 'reftex-add-label-environments) ++ (reftex-add-label-environments ++ '(("proposition" ?p "prop:" "~\\ref@{%s@}" t ++ ("Proposition" "Prop.") -3)))))) ++@end group ++@end lisp ++ ++@findex reftex-set-cite-format ++Similarly, a style hook may contain a call to ++@code{reftex-set-cite-format} to set the citation format. The style ++file @file{natbib.el} for the Natbib citation style does switch ++@b{Ref@TeX{}}'s citation format like this: ++ ++@lisp ++(TeX-add-style-hook "natbib" ++ (lambda () ++ (if (fboundp 'reftex-set-cite-format) ++ (reftex-set-cite-format 'natbib)))) ++@end lisp ++ ++@findex reftex-add-index-macros ++The hook may contain a call to @code{reftex-add-index-macros} to ++define additional @code{\index}-like macros. The argument must have ++the same format as @code{reftex-index-macros}. It may be a symbol, to ++trigger support for one of the builtin index packages. For example, ++the style @file{multind.el} contains ++ ++@lisp ++(TeX-add-style-hook "multind" ++ (lambda () ++ (and (fboundp 'reftex-add-index-macros) ++ (reftex-add-index-macros '(multind))))) ++@end lisp ++ ++If you have your own package @file{myindex} which defines the ++following macros to be used with the LaTeX @file{index.sty} file ++@example ++\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@} ++\newcommand@{\aindex@}[1]@{#1\index[author]@{#1@} ++@end example ++ ++you could write this in the style file @file{myindex.el}: ++ ++@lisp ++(TeX-add-style-hook "myindex" ++ (lambda () ++ (TeX-add-symbols ++ '("molec" TeX-arg-index) ++ '("aindex" TeX-arg-index)) ++ (if (fboundp 'reftex-add-index-macros) ++ (reftex-add-index-macros ++ '(("molec@{*@}" "idx" ?m "Molecules!" nil nil) ++ ("aindex@{*@}" "author" ?a "" nil nil)))))) ++@end lisp ++ ++@findex reftex-add-section-levels ++Finally the hook may contain a call to @code{reftex-add-section-levels} ++to define additional section statements. For example, the FoilTeX class ++has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here ++is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these: ++ ++@lisp ++(TeX-add-style-hook "foils" ++ (lambda () ++ (if (fboundp 'reftex-add-section-levels) ++ (reftex-add-section-levels '(("foilhead" . 3) ++ ("rotatefoilhead" . 3)))))) ++@end lisp ++ ++@node Bib-Cite, , Style Files, AUCTeX ++@subsection Bib-Cite ++@cindex @code{bib-cite}, Emacs package ++@cindex Emacs packages, @code{bib-cite} ++ ++Once you have written a document with labels, references and citations, ++it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has ++support for that: @code{reftex-view-crossref} (bound to @kbd{C-c ++&}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and ++@code{reftex-search-document}. A somewhat fancier interface with mouse ++highlighting is provided (among other things) by Peter S. Galbraith's ++@file{bib-cite.el}. There is some overlap in the functionalities of ++Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with ++AUCTeX. ++ ++Bib-cite version 3.06 and later can be configured so that bib-cite's ++mouse functions use @b{Ref@TeX{}} for displaying references and citations. ++This can be useful in particular when working with the LaTeX @code{xr} ++package or with an explicit @code{thebibliography} environment (rather ++than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To ++make use of this feature, try ++ ++@vindex bib-cite-use-reftex-view-crossref ++@lisp ++(setq bib-cite-use-reftex-view-crossref t) ++@end lisp ++ ++@page ++@node Problems and Work-Arounds, Imprint, Optimizations, Top ++@section Problems and Work-arounds ++@cindex Problems and work-arounds ++ ++@itemize @bullet ++@item ++@b{LaTeX commands}@* ++@cindex LaTeX commands, not found ++@code{\input}, @code{\include}, and @code{\section} (etc.) statements ++have to be first on a line (except for white space). ++ ++@item ++@b{Commented regions}@* ++@cindex Labels, commented out ++@b{Ref@TeX{}} sees also labels in regions commented out and will refuse to ++make duplicates of such labels. This is considered to be a feature. ++ ++@item ++@b{Wrong section numbers}@* ++@cindex Section numbers, wrong ++@vindex reftex-enable-partial-scans ++When using partial scans (@code{reftex-enable-partial-scans}), the section ++numbers in the table of contents may eventually become wrong. A full ++scan will fix this. ++ ++@item ++@b{Local settings}@* ++@cindex Settings, local ++@findex reftex-add-label-environments ++@findex reftex-set-cite-format ++@findex reftex-add-section-levels ++The label environment definitions in @code{reftex-label-alist} are ++global and apply to all documents. If you need to make definitions ++local to a document, because they would interfere with settings in other ++documents, you should use AUCTeX and set up style files with calls to ++@code{reftex-add-label-environments}, @code{reftex-set-cite-format}, ++@code{reftex-add-index-macros}, and @code{reftex-add-section-levels}. ++Settings made with these functions remain local to the current ++document. @xref{AUCTeX}. ++ ++@item ++@b{Funny display in selection buffer}@* ++@cindex @code{x-symbol}, Emacs package ++@cindex Emacs packages, @code{x-symbol} ++@cindex @code{isotex}, Emacs package ++@cindex Emacs packages, @code{isotex} ++@cindex @code{iso-cvt}, Emacs package ++@cindex Emacs packages, @code{iso-cvt} ++When using packages which make the buffer representation of a file ++different from its disk representation (e.g. x-symbol, isotex, ++iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes ++reflects the disk state of a file. This happens only in @emph{unvisited} ++parts of a multifile document, because @b{Ref@TeX{}} visits these files ++literally for speed reasons. Then both short context and section ++headings may look different from what you usually see on your screen. ++In rare cases @code{reftex-toc} may have problems to jump to an affected ++section heading. There are three possible ways to deal with ++this: ++@itemize @minus ++@item ++@vindex reftex-keep-temporary-buffers ++@code{(setq reftex-keep-temporary-buffers t)}@* ++This implies that @b{Ref@TeX{}} will load all parts of a multifile ++document into Emacs (i.e. there won't be any temporary buffers). ++@item ++@vindex reftex-initialize-temporary-buffers ++@code{(setq reftex-initialize-temporary-buffers t)}@* ++This means full initialization of temporary buffers. It involves ++a penalty when the same unvisited file is used for lookup often. ++@item ++Set @code{reftex-initialize-temporary-buffers} to a list of hook ++functions doing a minimal initialization. ++@end itemize ++@vindex reftex-refontify-context ++See also the variable @code{reftex-refontify-context}. ++ ++@item ++@b{Labels as arguments to \begin}@* ++@cindex @code{pf}, LaTeX package ++@cindex LaTeX packages, @code{pf} ++Some packages use an additional argument to a @code{\begin} macro ++to specify a label. E.g. Lamport's @file{pf.sty} uses both ++@example ++\step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@} ++ @var{claim} ++ \end@{step+@} ++@end example ++ ++@noindent ++We need to trick @b{Ref@TeX{}} into swallowing this: ++ ++@lisp ++@group ++;; Configuration for Lamport's pf.sty ++(setq reftex-label-alist ++ '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St.")) ++ ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000))) ++@end group ++@end lisp ++ ++@noindent ++The first line is just a normal configuration for a macro. For the ++@code{step+} environment we actually tell @b{Ref@TeX{}} to look for the ++@emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first} ++argument (which really is a second argument to the macro @code{\begin}) ++as a label of type @code{?p}. Argument count for this macro starts only ++after the @samp{@{step+@}}, also when specifying how to get ++context. ++ ++@item ++@b{Idle timers in XEmacs}@* ++@cindex Idle timer restart ++@vindex reftex-use-itimer-in-xemacs ++In XEmacs, idle timer restart does not work reliably after fast ++keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command ++hook to start the timer used for automatic crossref information. When ++this bug gets fixed, a real idle timer can be requested with ++@lisp ++(setq reftex-use-itimer-in-xemacs t) ++@end lisp ++ ++@item ++@b{Viper mode}@* ++@cindex Viper mode ++@cindex Key bindings, problems with Viper mode ++@findex viper-harness-minor-mode ++With @i{Viper} mode prior to Vipers version 3.01, you need to protect ++@b{Ref@TeX{}}'s keymaps with ++ ++@lisp ++(viper-harness-minor-mode "reftex") ++@end lisp ++ ++@end itemize ++ ++@page ++@node Imprint, Commands, Problems and Work-Arounds, Top ++@section Imprint ++@cindex Imprint ++@cindex Maintainer ++@cindex Acknowledgments ++@cindex Thanks ++@cindex Bug reports ++@cindex @code{http}, @b{Ref@TeX{}} home page ++@cindex @code{ftp}, @b{Ref@TeX{}} site ++ ++Ref@TeX{} was written by @i{Carsten Dominik} ++@email{dominik@@science.uva.nl}, with contributions by @i{Stephen ++Eglen}. Ref@TeX{} is currently maintained by @value{MAINTAINER}, see ++the @value{MAINTAINERSITE} for detailed information. ++ ++If you have questions about Ref@TeX{}, you can send email to the ++@value{SUPPORTADDRESS}. If you want to contribute code or ideas, write ++to the @value{DEVELADDRESS}. And in the rare case of finding a bug, ++please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a ++bug report with useful information about your setup. Remember to add ++essential information like a recipe for reproducing the bug, what you ++expected to happen, and what actually happened. Send the bug report to ++the @value{BUGADDRESS}. ++ ++There are also several Usenet groups which have competent readers who ++might be able to help: @code{comp.emacs}, @code{gnu.emacs.help}, ++@code{comp.emacs.xemacs}, and @code{comp.text.tex}. ++ ++@b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2. ++It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs ++21.x users want to install the corresponding plugin package which is ++available from the @value{XEMACSFTP}. See the XEmacs 21.x ++documentation on package installation for details. ++ ++Users of earlier Emacs distributions (including Emacs 19) can get a ++@b{Ref@TeX{}} distribution from the @value{MAINTAINERSITE}. Note that ++the Emacs 19 version supports many but not all features described in ++this manual. ++ ++Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped ++developing it with their reports. In particular thanks to @i{Ralf ++Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton, ++Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai ++Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan ++Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz, ++Juri Linkov, Rory Molinari, Stefan Monnier, Laurent Mugnier, Dan ++Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha, ++Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan ++Williams, Roland Winkler, Hans-Christoph Wirth, Eli Zaretskii}. ++ ++ ++The @code{view-crossref} feature was inspired by @i{Peter Galbraith's} ++@file{bib-cite.el}. ++ ++Finally thanks to @i{Uwe Bolick} who first got me interested in ++supporting LaTeX labels and references with an editor (which was ++MicroEmacs at the time). ++ ++@node Commands, Options, Imprint, Top ++@chapter Commands ++@cindex Commands, list of ++ ++Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from ++LaTeX files. Command which are executed from the special buffers are ++not described here. All commands are available from the @code{Ref} ++menu. See @xref{Key Bindings}. ++ ++@deffn Command reftex-toc ++Show the table of contents for the current document. When called with ++one ore two @kbd{C-u} prefixes, rescan the document first. ++@end deffn ++ ++@deffn Command reftex-label ++Insert a unique label. With one or two @kbd{C-u} prefixes, enforce ++document rescan first. ++@end deffn ++ ++@deffn Command reftex-reference ++Start a selection process to select a label, and insert a reference to ++it. With one or two @kbd{C-u} prefixes, enforce document rescan first. ++@end deffn ++ ++@deffn Command reftex-citation ++Make a citation using BibTeX database files. After prompting for a regular ++expression, scans the buffers with BibTeX entries (taken from the ++@code{\bibliography} command or a @code{thebibliography} environment) ++and offers the matching entries for selection. The selected entry is ++formatted according to @code{reftex-cite-format} and inserted into the ++buffer. @* ++When called with a @kbd{C-u} prefix, prompt for optional arguments in ++cite macros. When called with a numeric prefix, make that many citations. ++When called with point inside the braces of a @code{\cite} command, it ++will add another key, ignoring the value of ++@code{reftex-cite-format}. @* ++The regular expression uses an expanded syntax: @samp{&&} is interpreted ++as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain ++both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion ++on knows citation keys is possible. @samp{=} is a good regular ++expression to match all entries in all files. ++@end deffn ++ ++@deffn Command reftex-index ++Query for an index macro and insert it along with its arguments. The ++index macros available are those defined in @code{reftex-index-macro} or ++by a call to @code{reftex-add-index-macros}, typically from an AUCTeX ++style file. @b{Ref@TeX{}} provides completion for the index tag and the ++index key, and will prompt for other arguments. ++@end deffn ++ ++@deffn Command reftex-index-selection-or-word ++Put current selection or the word near point into the default index ++macro. This uses the information in @code{reftex-index-default-macro} ++to make an index entry. The phrase indexed is the current selection or ++the word near point. When called with one @kbd{C-u} prefix, let the ++user have a chance to edit the index entry. When called with 2 ++@kbd{C-u} as prefix, also ask for the index macro and other stuff. When ++called inside TeX math mode as determined by the @file{texmathp.el} ++library which is part of AUCTeX, the string is first processed with the ++@code{reftex-index-math-format}, which see. ++@end deffn ++ ++@deffn Command reftex-index-phrase-selection-or-word ++Add current selection or the word at point to the phrases buffer. ++When you are in transient-mark-mode and the region is active, the ++selection will be used - otherwise the word at point. ++You get a chance to edit the entry in the phrases buffer - to save the ++buffer and return to the LaTeX document, finish with @kbd{C-c C-c}. ++@end deffn ++ ++@deffn Command reftex-index-visit-phrases-buffer ++Switch to the phrases buffer, initialize if empty. ++@end deffn ++ ++@deffn Command reftex-index-phrases-apply-to-region ++Index all index phrases in the current region. ++This works exactly like global indexing from the index phrases buffer, ++but operation is restricted to the current region. ++@end deffn ++ ++@deffn Command reftex-display-index ++Display a buffer with an index compiled from the current document. ++When the document has multiple indices, first prompts for the correct one. ++When index support is turned off, offer to turn it on. ++With one or two @kbd{C-u} prefixes, rescan document first. ++With prefix 2, restrict index to current document section. ++With prefix 3, restrict index to active region. ++@end deffn ++ ++@deffn Command reftex-view-crossref ++View cross reference of macro at point. Point must be on the @var{key} ++argument. Works with the macros @code{\label}, @code{\ref}, ++@code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of ++these. Where it makes sense, subsequent calls show additional ++locations. See also the variable @code{reftex-view-crossref-extra} and ++the command @code{reftex-view-crossref-from-bibtex}. With one or two ++@kbd{C-u} prefixes, enforce rescanning of the document. With argument ++2, select the window showing the cross reference. ++@end deffn ++ ++@deffn Command reftex-view-crossref-from-bibtex ++View location in a LaTeX document which cites the BibTeX entry at point. ++Since BibTeX files can be used by many LaTeX documents, this function ++prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this ++link to a document, call the function with a prefix arg. Calling ++this function several times find successive citation locations. ++@end deffn ++ ++@deffn Command reftex-create-tags-file ++Create TAGS file by running @code{etags} on the current document. The ++TAGS file is also immediately visited with ++@code{visit-tags-table}. ++@end deffn ++ ++@deffn Command reftex-grep-document ++Run grep query through all files related to this document. ++With prefix arg, force to rescan document. ++No active TAGS table is required. ++@end deffn ++ ++@deffn Command reftex-search-document ++Regexp search through all files of the current document. ++Starts always in the master file. Stops when a match is found. ++No active TAGS table is required. ++@end deffn ++ ++@deffn Command reftex-query-replace-document ++Run a query-replace-regexp of @var{from} with @var{to} over the entire ++document. With prefix arg, replace only word-delimited matches. No ++active TAGS table is required. ++@end deffn ++ ++@deffn Command reftex-isearch-minor-mode ++Toggle a minor mode which enables incremental search to work globally ++on the entire multifile document. Files will be searched in th ++sequence they appear in the document. ++@end deffn ++ ++@deffn Command reftex-goto-label ++Prompt for a label (with completion) and jump to the location of this ++label. Optional prefix argument @var{other-window} goes to the label in ++another window. ++@end deffn ++ ++ ++@deffn Command reftex-change-label ++Query replace @var{from} with @var{to} in all @code{\label} and ++@code{\ref} commands. Works on the entire multifile document. No ++active TAGS table is required. ++@end deffn ++ ++@deffn Command reftex-renumber-simple-labels ++Renumber all simple labels in the document to make them sequentially. ++Simple labels are the ones created by RefTeX, consisting only of the ++prefix and a number. After the command completes, all these labels will ++have sequential numbers throughout the document. Any references to the ++labels will be changed as well. For this, @b{Ref@TeX{}} looks at the ++arguments of any macros which either start or end with the string ++@samp{ref}. This command should be used with care, in particular in ++multifile documents. You should not use it if another document refers ++to this one with the @code{xr} package. ++@end deffn ++ ++@deffn Command reftex-find-duplicate-labels ++Produce a list of all duplicate labels in the document. ++@end deffn ++ ++@deffn Command reftex-create-bibtex-file ++Create a new BibTeX database file with all entries referenced in document. ++The command prompts for a filename and writes the collected entries to ++that file. Only entries referenced in the current document with ++any @code{\cite}-like macros are used. ++The sequence in the new file is the same as it was in the old database. ++@end deffn ++ ++@deffn Command reftex-customize ++Run the customize browser on the @b{Ref@TeX{}} group. ++@end deffn ++@deffn Command reftex-show-commentary ++Show the commentary section from @file{reftex.el}. ++@end deffn ++@deffn Command reftex-info ++Run info on the top @b{Ref@TeX{}} node. ++@end deffn ++@deffn Command reftex-parse-document ++Parse the entire document in order to update the parsing information. ++@end deffn ++@deffn Command reftex-reset-mode ++Enforce rebuilding of several internal lists and variables. Also ++removes the parse file associated with the current document. ++@end deffn ++ ++@node Options, Keymaps and Hooks, Commands, Top ++@chapter Options, Keymaps, Hooks ++@cindex Options, list of ++ ++Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All ++variables have customize support - so if you are not familiar with Emacs ++Lisp (and even if you are) you might find it more comfortable to use ++@code{customize} to look at and change these variables. @kbd{M-x ++reftex-customize} will get you there. ++ ++@menu ++* Options (Table of Contents):: ++* Options (Defining Label Environments):: ++* Options (Creating Labels):: ++* Options (Referencing Labels):: ++* Options (Creating Citations):: ++* Options (Index Support):: ++* Options (Viewing Cross-References):: ++* Options (Finding Files):: ++* Options (Optimizations):: ++* Options (Fontification):: ++* Options (Misc):: ++@end menu ++ ++@node Options (Table of Contents), Options (Defining Label Environments), , Options ++@section Table of Contents ++@cindex Options, table of contents ++@cindex Table of contents, options ++ ++@defopt reftex-include-file-commands ++List of LaTeX commands which input another file. ++The file name is expected after the command, either in braces or separated ++by whitespace. ++@end defopt ++ ++@defopt reftex-max-section-depth ++Maximum depth of section levels in document structure. ++Standard LaTeX needs 7, default is 12. ++@end defopt ++ ++@defopt reftex-section-levels ++Commands and levels used for defining sections in the document. The ++@code{car} of each cons cell is the name of the section macro. The ++@code{cdr} is a number indicating its level. A negative level means the ++same as the positive value, but the section will never get a number. ++The @code{cdr} may also be a function which then has to return the ++level. This list is also used for promotion and demotion of sectioning ++commands. If you are using a document class which has several sets of ++sectioning commands, promotion only works correctly if this list is ++sorted first by set, then within each set by level. The promotion ++commands always select the nearest entry with the correct new level. ++ ++@end defopt ++ ++@defopt reftex-toc-max-level ++The maximum level of toc entries which will be included in the TOC. ++Section headings with a bigger level will be ignored. In RefTeX, ++chapters are level 1, sections level 2 etc. This variable can be ++changed from within the @file{*toc*} buffer with the @kbd{t} key. ++@end defopt ++ ++@defopt reftex-part-resets-chapter ++Non-@code{nil} means, @code{\part} is like any other sectioning command. ++This means, part numbers will be included in the numbering of chapters, and ++chapter counters will be reset for each part. ++When @code{nil} (the default), parts are special, do not reset the ++chapter counter and also do not show up in chapter numbers. ++@end defopt ++ ++@defopt reftex-auto-recenter-toc ++Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on. ++When active, the @file{*TOC*} window will always show the section you ++are currently working in. Recentering happens whenever Emacs is idle for ++more than @code{reftex-idle-time} seconds. ++ ++Value @code{t} means, turn on immediately when RefTeX gets started. Then, ++recentering will work for any toc window created during the session. ++ ++Value @code{frame} (the default) means, turn automatic recentering on ++only while the dedicated TOC frame does exist, and do the recentering ++only in that frame. So when creating that frame (with @kbd{d} key in an ++ordinary TOC window), the automatic recentering is turned on. When the ++frame gets destroyed, automatic recentering is turned off again. ++ ++This feature can be turned on and off from the menu ++(Ref->Options). ++@end defopt ++ ++@defopt reftex-toc-split-windows-horizontally ++Non-@code{nil} means, create TOC window by splitting window ++horizontally. The default is to split vertically. ++@end defopt ++ ++@defopt reftex-toc-split-windows-fraction ++Fraction of the width or height of the frame to be used for TOC window. ++@end defopt ++ ++@defopt reftex-toc-keep-other-windows ++Non-@code{nil} means, split the selected window to display the ++@file{*toc*} buffer. This helps to keep the window configuration, but ++makes the @file{*toc*} small. When @code{nil}, all other windows except ++the selected one will be deleted, so that the @file{*toc*} window fills ++half the frame. ++@end defopt ++ ++@defopt reftex-toc-include-file-boundaries ++Non-@code{nil} means, include file boundaries in @file{*toc*} buffer. ++This flag can be toggled from within the @file{*toc*} buffer with the ++@kbd{i} key. ++@end defopt ++ ++@defopt reftex-toc-include-labels ++Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag ++can be toggled from within the @file{*toc*} buffer with the @kbd{l} ++key. ++@end defopt ++ ++@defopt reftex-toc-include-index-entries ++Non-@code{nil} means, include index entries in @file{*toc*} buffer. ++This flag can be toggled from within the @file{*toc*} buffer with the ++@kbd{i} key. ++@end defopt ++ ++@defopt reftex-toc-include-context ++Non-@code{nil} means, include context with labels in the @file{*toc*} ++buffer. Context will only be shown if the labels are visible as well. ++This flag can be toggled from within the @file{*toc*} buffer with the ++@kbd{c} key. ++@end defopt ++ ++@defopt reftex-toc-follow-mode ++Non-@code{nil} means, point in @file{*toc*} buffer (the ++table-of-contents buffer) will cause other window to follow. The other ++window will show the corresponding part of the document. This flag can ++be toggled from within the @file{*toc*} buffer with the @kbd{f} ++key. ++@end defopt ++ ++@deffn {Normal Hook} reftex-toc-mode-hook ++Normal hook which is run when a @file{*toc*} buffer is ++created. ++@end deffn ++ ++@deffn Keymap reftex-toc-map ++The keymap which is active in the @file{*toc*} buffer. ++(@pxref{Table of Contents}). ++@end deffn ++ ++@node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options ++@section Defining Label Environments ++@cindex Options, defining label environments ++@cindex Defining label environments, options ++ ++@defopt reftex-default-label-alist-entries ++Default label alist specifications. It is a list of symbols with ++associations in the constant @code{reftex-label-alist-builtin}. ++@code{LaTeX} should always be the last entry. ++@end defopt ++ ++@defopt reftex-label-alist ++Set this variable to define additions and changes to the defaults in ++@code{reftex-default-label-alist-entries}. The only things you ++@emph{must not} change is that @code{?s} is the type indicator for ++section labels, and @key{SPC} for the @code{any} label type. These are ++hard-coded at other places in the code. ++ ++The value of the variable must be a list of items. Each item is a list ++itself and has the following structure: ++ ++@example ++ (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format} ++ @var{context-method} (@var{magic-word} ... ) @var{toc-level}) ++@end example ++ ++Each list entry describes either an environment carrying a counter for ++use with @code{\label} and @code{\ref}, or a LaTeX macro defining a ++label as (or inside) one of its arguments. The elements of each list ++entry are: ++ ++@table @asis ++@item @var{env-or-macro} ++Name of the environment (like @samp{table}) or macro (like ++@samp{\myfig}). For macros, indicate the arguments, as in ++@samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional ++arguments, a star to mark the label argument, if any. The macro does ++not have to have a label argument - you could also use ++@samp{\label@{...@}} inside one of its arguments. ++ ++Special names: @code{section} for section labels, @code{any} to define a ++group which contains all labels. ++ ++This may also be a function to do local parsing and identify point to be ++in a non-standard label environment. The function must take an ++argument @var{bound} and limit backward searches to this value. It ++should return either nil or a cons cell @code{(@var{function} ++. @var{position})} with the function symbol and the position where the ++special environment starts. See the Info documentation for an ++example. ++ ++Finally this may also be @code{nil} if the entry is only meant to change ++some settings associated with the type indicator character (see ++below). ++ ++@item @var{type-key} ++Type indicator character, like @code{?t}, must be a printable ASCII ++character. The type indicator is a single character which defines a ++label type. Any label inside the environment or macro is assumed to ++belong to this type. The same character may occur several times in this ++list, to cover cases in which different environments carry the same ++label type (like @code{equation} and @code{eqnarray}). If the type ++indicator is @code{nil} and the macro has a label argument @samp{@{*@}}, ++the macro defines neutral labels just like @code{\label}. In this case ++the reminder of this entry is ignored. ++ ++@item @var{label-prefix} ++Label prefix string, like @samp{tab:}. The prefix is a short string ++used as the start of a label. It may be the empty string. The prefix ++may contain the following @samp{%} escapes: ++ ++@example ++%f Current file name, directory and extension stripped. ++%F Current file name relative to master file directory. ++%m Master file name, directory and extension stripped. ++%M Directory name (without path) where master file is located. ++%u User login name, on systems which support this. ++%S A section prefix derived with variable @code{reftex-section-prefixes}. ++@end example ++ ++@noindent ++Example: In a file @file{intro.tex}, @samp{eq:%f:} will become ++@samp{eq:intro:}. ++ ++@item @var{reference-format} ++Format string for reference insert in buffer. @samp{%s} will be ++replaced by the label. When the format starts with @samp{~}, this ++@samp{~} will only be inserted when the character before point is ++@emph{not} a whitespace. ++ ++@item @var{context-method} ++Indication on how to find the short context. ++@itemize @minus ++@item ++If @code{nil}, use the text following the @samp{\label@{...@}} macro. ++@item ++If @code{t}, use ++@itemize @minus ++@item ++the section heading for section labels. ++@item ++text following the @samp{\begin@{...@}} statement of environments (not ++a good choice for environments like eqnarray or enumerate, where one has ++several labels in a single environment). ++@item ++text after the macro name (starting with the first arg) for ++macros. ++@end itemize ++@item ++If an integer, use the nth argument of the macro. As a special case, ++1000 means to get text after the last macro argument. ++@item ++If a string, use as regexp to search @emph{backward} from the label. ++Context is then the text following the end of the match. E.g. putting ++this to @samp{\\caption[[@{]} will use the caption in a figure or table ++environment. @samp{\\begin@{eqnarray@}\|\\\\} works for ++eqnarrays. ++@item ++If any of @code{caption}, @code{item}, @code{eqnarray-like}, ++@code{alignat-like}, this symbol will internally be translated into an ++appropriate regexp (see also the variable ++@code{reftex-default-context-regexps}). ++@item ++If a function, call this function with the name of the environment/macro ++as argument. On call, point will be just after the @code{\label} macro. ++The function is expected to return a suitable context string. It should ++throw an exception (error) when failing to find context. As an example, ++here is a function returning the 10 chars following the label macro as ++context: ++ ++@example ++(defun my-context-function (env-or-mac) ++ (if (> (point-max) (+ 10 (point))) ++ (buffer-substring (point) (+ 10 (point))) ++ (error "Buffer too small"))) ++@end example ++@end itemize ++ ++Label context is used in two ways by @b{Ref@TeX{}}: For display in the label ++menu, and to derive a label string. If you want to use a different ++method for each of these, specify them as a dotted pair. ++E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for ++display, and text from the default position (@code{t}) to derive a label ++string. This is actually used for section labels. ++ ++@item @var{magic-word-list} ++List of magic words which identify a reference to be of this type. If ++the word before point is equal to one of these words when calling ++@code{reftex-reference}, the label list offered will be automatically ++restricted to labels of the correct type. If the first element of this ++word--list is the symbol `regexp', the strings are interpreted as regular ++expressions. ++ ++@item @var{toc-level} ++The integer level at which this environment should be added to the table ++of contents. See also @code{reftex-section-levels}. A positive value ++will number the entries mixed with the sectioning commands of the same ++level. A negative value will make unnumbered entries. Useful only for ++theorem-like environments which structure the document. Will be ignored ++for macros. When omitted or @code{nil}, no TOC entries will be ++made. ++@end table ++ ++If the type indicator characters of two or more entries are the same, ++@b{Ref@TeX{}} will use ++@itemize @minus ++@item ++the first non-@code{nil} format and prefix ++@item ++the magic words of all involved entries. ++@end itemize ++ ++Any list entry may also be a symbol. If that has an association in ++@code{reftex-label-alist-builtin}, the @code{cddr} of that association is ++spliced into the list. However, builtin defaults should normally be set ++with the variable @code{reftex-default-label-alist-entries}. ++@end defopt ++ ++@defopt reftex-section-prefixes ++Prefixes for section labels. When the label prefix given in an entry in ++@code{reftex-label-alist} contains @samp{%S}, this list is used to ++determine the correct prefix string depending on the current section ++level. The list is an alist, with each entry of the form ++@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro ++names like @samp{chapter}, integer section levels (as given in ++@code{reftex-section-levels}), and @code{t} for the default. ++@end defopt ++ ++@defopt reftex-default-context-regexps ++Alist with default regular expressions for finding context. The emacs ++lisp form @w{@code{(format regexp (regexp-quote environment))}} is used ++to calculate the final regular expression - so @samp{%s} will be ++replaced with the environment or macro. ++@end defopt ++ ++@defopt reftex-trust-label-prefix ++Non-@code{nil} means, trust the label prefix when determining label type. ++It is customary to use special label prefixes to distinguish different label ++types. The label prefixes have no syntactic meaning in LaTeX (unless ++special packages like fancyref) are being used. RefTeX can and by ++default does parse around each label to detect the correct label type, ++but this process can be slow when a document contains thousands of ++labels. If you use label prefixes consistently, you may speed up ++document parsing by setting this variable to a non-nil value. RefTeX ++will then compare the label prefix with the prefixes found in ++`reftex-label-alist' and derive the correct label type in this way. ++Possible values for this option are: ++ ++@example ++t @r{This means to trust any label prefixes found.} ++regexp @r{If a regexp, only prefixes matched by the regexp are trusted.} ++list @r{List of accepted prefixes, as strings. The colon is part of} ++ @r{the prefix, e.g. ("fn:" "eqn:" "item:").} ++nil @r{Never trust a label prefix.} ++@end example ++The only disadvantage of using this feature is that the label context ++displayed in the label selection buffer along with each label is ++simply some text after the label definition. This is no problem if you ++place labels keeping this in mind (e.g. @i{before} the equation, @i{at ++the beginning} of a fig/tab caption ...). Anyway, it is probably best ++to use the regexp or the list value types to fine-tune this feature. ++For example, if your document contains thousands of footnotes with ++labels fn:xxx, you may want to set this variable to the value "^fn:$" or ++("fn:"). Then RefTeX will still do extensive parsing for any ++non-footnote labels. ++@end defopt ++ ++@node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options ++@section Creating Labels ++@cindex Options, creating labels ++@cindex Creating labels, options ++ ++@defopt reftex-insert-label-flags ++Flags governing label insertion. The value has the form ++ ++@example ++(@var{derive} @var{prompt}) ++@end example ++ ++If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible ++label from context. A section label for example will be derived from ++the section heading. The conversion of the context to a valid label is ++governed by the specifications given in ++@code{reftex-derive-label-parameters}. If @var{derive} is @code{nil}, ++the default label will consist of the prefix and a unique number, like ++@samp{eq:23}. ++ ++If @var{prompt} is @code{t}, the user will be prompted for a label ++string. When @var{prompt} is @code{nil}, the default label will be ++inserted without query. ++ ++So the combination of @var{derive} and @var{prompt} controls label ++insertion. Here is a table describing all four possibilities: ++ ++@example ++@group ++@var{derive} @var{prompt} @var{action} ++----------------------------------------------------------- ++nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.} ++nil t @r{Prompt for label.} ++t nil @r{Derive a label from context and insert. No query.} ++t t @r{Derive a label from context, prompt for confirmation.} ++@end group ++@end example ++ ++Each flag may be set to @code{t}, @code{nil}, or a string of label type ++letters indicating the label types for which it should be true. Thus, ++the combination may be set differently for each label type. The default ++settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from ++headings (with confirmation). Prompt for figure and table labels. Use ++simple labels without confirmation for everything else. ++ ++The available label types are: @code{s} (section), @code{f} (figure), ++@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} ++(footnote), @code{N} (endnote) plus any definitions in ++@code{reftex-label-alist}. ++@end defopt ++ ++@deffn Hook reftex-format-label-function ++If non-@code{nil}, should be a function which produces the string to ++insert as a label definition. The function will be called with two ++arguments, the @var{label} and the @var{default-format} (usually ++@samp{\label@{%s@}}). It should return the string to insert into the ++buffer. ++@end deffn ++ ++@deffn Hook reftex-string-to-label-function ++Function to turn an arbitrary string into a valid label. ++@b{Ref@TeX{}}'s default function uses the variable ++@code{reftex-derive-label-parameters}. ++@end deffn ++ ++@deffn Hook reftex-translate-to-ascii-function ++Filter function which will process a context string before it is used to ++derive a label from it. The intended application is to convert ISO or ++Mule characters into something valid in labels. The default function ++@code{reftex-latin1-to-ascii} removes the accents from Latin-1 ++characters. X-Symbol (>=2.6) sets this variable to the much more ++general @code{x-symbol-translate-to-ascii}. ++@end deffn ++ ++@defopt reftex-derive-label-parameters ++Parameters for converting a string into a label. This variable is a ++list of the following items: ++@table @asis ++@item @var{nwords} ++Number of words to use. ++@item @var{maxchar} ++Maximum number of characters in a label string. ++@item @var{invalid} ++@code{nil}: Throw away any words containing characters invalid in labels.@* ++@code{t}: Throw away only the invalid characters, not the whole word. ++@item @var{abbrev} ++@code{nil}: Never abbreviate words.@* ++@code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@* ++@code{1}: Abbreviate words if necessary to shorten label string. ++@item @var{separator} ++String separating different words in the label. ++@item @var{ignorewords} ++List of words which should not be part of labels. ++@item @var{downcase} ++@code{t}: Downcase words before putting them into the label.@* ++@end table ++@end defopt ++ ++@defopt reftex-label-illegal-re ++Regexp matching characters not valid in labels. ++@end defopt ++ ++@defopt reftex-abbrev-parameters ++Parameters for abbreviation of words. A list of four parameters. ++@table @asis ++@item @var{min-chars} ++Minimum number of characters remaining after abbreviation. ++@item @var{min-kill} ++Minimum number of characters to remove when abbreviating words. ++@item @var{before} ++Character class before abbrev point in word. ++@item @var{after} ++Character class after abbrev point in word. ++@end table ++@end defopt ++ ++@node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options ++@section Referencing Labels ++@cindex Options, referencing labels ++@cindex Referencing labels, options ++ ++@defopt reftex-label-menu-flags ++List of flags governing the label menu makeup. The flags are: ++@table @asis ++@item @var{table-of-contents} ++Show the labels embedded in a table of context. ++@item @var{section-numbers} ++Include section numbers (like 4.1.3) in table of contents. ++@item @var{counters} ++Show counters. This just numbers the labels in the menu. ++@item @var{no-context} ++Non-@code{nil} means do @emph{not} show the short context. ++@item @var{follow} ++Follow full context in other window. ++@item @var{show-commented} ++Show labels from regions which are commented out. ++@item @var{match-everywhere} ++Obsolete flag. ++@item @var{show-files} ++Show begin and end of included files. ++@end table ++ ++Each of these flags can be set to @code{t} or @code{nil}, or to a string ++of type letters indicating the label types for which it should be true. ++These strings work like character classes in regular expressions. Thus, ++setting one of the flags to @samp{"sf"} makes the flag true for section ++and figure labels, @code{nil} for everything else. Setting it to ++@samp{"^sf"} makes it the other way round. ++ ++The available label types are: @code{s} (section), @code{f} (figure), ++@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} ++(footnote), plus any definitions in @code{reftex-label-alist}. ++ ++Most options can also be switched from the label menu itself - so if you ++decide here to not have a table of contents in the label menu, you can ++still get one interactively during selection from the label menu. ++@end defopt ++ ++@defopt reftex-multiref-punctuation ++Punctuation strings for multiple references. When marking is used in ++the selection buffer to select several references, this variable ++associates the 3 marking characters @samp{,-+} with prefix strings to be ++inserted into the buffer before the corresponding @code{\ref} macro. ++This is used to string together whole reference sets, like ++@samp{eqs. 1,2,3-5,6 and 7} in a single call to ++@code{reftex-reference}. ++@end defopt ++ ++@defopt reftex-vref-is-default ++Non-@code{nil} means, the varioref macro @code{\vref} is used as ++default. In the selection buffer, the @kbd{v} key toggles the reference ++macro between @code{\ref} and @code{\vref}. The value of this variable ++determines the default which is active when entering the selection ++process. Instead of @code{nil} or @code{t}, this may also be a string ++of type letters indicating the label types for which it should be ++true. ++@end defopt ++ ++@defopt reftex-fref-is-default ++Non-@code{nil} means, the fancyref macro @code{\fref} is used as ++default. In the selection buffer, the @kbd{V} key toggles the reference ++macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of ++this variable determines the default which is active when entering the ++selection process. Instead of @code{nil} or @code{t}, this may also be ++a string of type letters indicating the label types for which it should ++be true. ++@end defopt ++ ++@deffn Hook reftex-format-ref-function ++If non-@code{nil}, should be a function which produces the string to ++insert as a reference. Note that the insertion format can also be ++changed with @code{reftex-label-alist}. This hook also is used by the ++special commands to insert @code{\vref} and @code{\fref} references, so ++even if you set this, your setting will be ignored by the special ++commands. The function will be called with two arguments, the ++@var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}). ++It should return the string to insert into the buffer. ++@end deffn ++ ++@defopt reftex-level-indent ++Number of spaces to be used for indentation per section level. ++@end defopt ++ ++@defopt reftex-guess-label-type ++Non-@code{nil} means, @code{reftex-reference} will try to guess the ++label type. To do that, @b{Ref@TeX{}} will look at the word before the ++cursor and compare it with the magic words given in ++@code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will ++immediately offer the correct label menu - otherwise it will prompt you ++for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}} ++will always prompt for a label type. ++@end defopt ++ ++@deffn {Normal Hook} reftex-display-copied-context-hook ++Normal Hook which is run before context is displayed anywhere. Designed ++for @w{@code{X-Symbol}}, but may have other uses as well. ++@end deffn ++ ++@deffn Hook reftex-pre-refontification-functions ++@code{X-Symbol} specific hook. Probably not useful for other purposes. ++The functions get two arguments, the buffer from where the command ++started and a symbol indicating in what context the hook is ++called. ++@end deffn ++ ++@deffn {Normal Hook} reftex-select-label-mode-hook ++Normal hook which is run when a selection buffer enters ++@code{reftex-select-label-mode}. ++@end deffn ++ ++@deffn Keymap reftex-select-label-map ++The keymap which is active in the labels selection process ++(@pxref{Referencing Labels}). ++@end deffn ++ ++@node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options ++@section Creating Citations ++@cindex Options, creating citations ++@cindex Creating citations, options ++ ++@defopt reftex-bibliography-commands ++LaTeX commands which specify the BibTeX databases to use with the document. ++@end defopt ++ ++@defopt reftex-bibfile-ignore-regexps ++List of regular expressions to exclude files in ++@code{\\bibliography@{..@}}. File names matched by any of these regexps ++will not be parsed. Intended for files which contain only ++@code{@@string} macro definitions and the like, which are ignored by ++@b{Ref@TeX{}} anyway. ++@end defopt ++ ++@defopt reftex-default-bibliography ++List of BibTeX database files which should be used if none are specified. ++When @code{reftex-citation} is called from a document with neither ++a @samp{\bibliography@{...@}} statement nor a @code{thebibliography} ++environment, @b{Ref@TeX{}} will scan these files instead. Intended for ++using @code{reftex-citation} in non-LaTeX files. The files will be ++searched along the BIBINPUTS or TEXBIB path. ++@end defopt ++ ++@defopt reftex-sort-bibtex-matches ++Sorting of the entries found in BibTeX databases by reftex-citation. ++Possible values: ++@example ++nil @r{Do not sort entries.} ++author @r{Sort entries by author name.} ++year @r{Sort entries by increasing year.} ++reverse-year @r{Sort entries by decreasing year.} ++@end example ++@end defopt ++ ++@defopt reftex-cite-format ++The format of citations to be inserted into the buffer. It can be a ++string, an alist or a symbol. In the simplest case this is just the string ++@samp{\cite@{%l@}}, which is also the default. See the definition of ++@code{reftex-cite-format-builtin} for more complex examples. ++ ++If @code{reftex-cite-format} is a string, it will be used as the format. ++In the format, the following percent escapes will be expanded. ++ ++@table @code ++@item %l ++The BibTeX label of the citation. ++@item %a ++List of author names, see also @code{reftex-cite-punctuation}. ++@item %2a ++Like %a, but abbreviate more than 2 authors like Jones et al. ++@item %A ++First author name only. ++@item %e ++Works like @samp{%a}, but on list of editor names. (@samp{%2e} and ++@samp{%E} work a well). ++@end table ++ ++It is also possible to access all other BibTeX database fields: ++ ++@example ++%b booktitle %c chapter %d edition %h howpublished ++%i institution %j journal %k key %m month ++%n number %o organization %p pages %P first page ++%r address %s school %u publisher %t title ++%v volume %y year ++%B booktitle, abbreviated %T title, abbreviated ++@end example ++ ++@noindent ++Usually, only @samp{%l} is needed. The other stuff is mainly for the ++echo area display, and for @code{(setq reftex-comment-citations t)}. ++ ++@samp{%<} as a special operator kills punctuation and space around it ++after the string has been formatted. ++ ++A pair of square brackets indicates an optional argument, and RefTeX ++will prompt for the values of these arguments. ++ ++Beware that all this only works with BibTeX database files. When ++citations are made from the @code{\bibitems} in an explicit ++@code{thebibliography} environment, only @samp{%l} is available. ++ ++If @code{reftex-cite-format} is an alist of characters and strings, the ++user will be prompted for a character to select one of the possible ++format strings. ++ ++In order to configure this variable, you can either set ++@code{reftex-cite-format} directly yourself or set it to the ++@emph{symbol} of one of the predefined styles. The predefined symbols ++are those which have an association in the constant ++@code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format ++'natbib)}. ++@end defopt ++ ++@deffn Hook reftex-format-cite-function ++If non-@code{nil}, should be a function which produces the string to ++insert as a citation. Note that the citation format can also be changed ++with the variable @code{reftex-cite-format}. The function will be ++called with two arguments, the @var{citation-key} and the ++@var{default-format} (taken from @code{reftex-cite-format}). It should ++return the string to insert into the buffer. ++@end deffn ++ ++@defopt reftex-cite-prompt-optional-args ++Non-@code{nil} means, prompt for empty optional arguments in cite macros. ++When an entry in @code{reftex-cite-format} ist given with square brackets to ++indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can ++prompt for values. Possible values are: ++@example ++nil @r{Never prompt for optional arguments} ++t @r{Always prompt} ++maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example ++Unnecessary empty optional arguments are removed before insertion into ++the buffer. See @code{reftex-cite-cleanup-optional-args}. ++@end defopt ++ ++@defopt reftex-cite-cleanup-optional-args ++Non-@code{nil} means, remove empty optional arguments from cite macros ++if possible. ++@end defopt ++ ++@defopt reftex-comment-citations ++Non-@code{nil} means add a comment for each citation describing the full ++entry. The comment is formatted according to ++@code{reftex-cite-comment-format}. ++@end defopt ++ ++@defopt reftex-cite-comment-format ++Citation format used for commented citations. Must @emph{not} contain ++@samp{%l}. See the variable @code{reftex-cite-format} for possible ++percent escapes. ++@end defopt ++ ++@defopt reftex-cite-punctuation ++Punctuation for formatting of name lists in citations. This is a list ++of 3 strings. ++@enumerate ++@item ++normal names separator, like @samp{, } in Jones, Brown and Miller ++@item ++final names separator, like @samp{ and } in Jones, Brown and Miller ++@item ++The @samp{et al.} string, like @samp{ @{\it et al.@}} in ++Jones @{\it et al.@} ++@end enumerate ++@end defopt ++ ++@deffn {Normal Hook} reftex-select-bib-mode-hook ++Normal hook which is run when a selection buffer enters ++@code{reftex-select-bib-mode}. ++@end deffn ++ ++@deffn Keymap reftex-select-bib-map ++The keymap which is active in the citation-key selection process ++(@pxref{Creating Citations}). ++@end deffn ++ ++@node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options ++@section Index Support ++@cindex Options, Index support ++@cindex Index support, options ++ ++@defopt reftex-support-index ++Non-@code{nil} means, index entries are parsed as well. Index support ++is resource intensive and the internal structure holding the parsed ++information can become quite big. Therefore it can be turned off. When ++this is @code{nil} and you execute a command which requires index ++support, you will be asked for confirmation to turn it on and rescan the ++document. ++@end defopt ++ ++@defopt reftex-index-special-chars ++List of special characters in index entries, given as strings. These ++correspond to the @code{MakeIndex} keywords ++@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}. ++@end defopt ++ ++@defopt reftex-index-macros ++List of macros which define index entries. The structure of each entry ++is ++@lisp ++(@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat}) ++@end lisp ++ ++@var{macro} is the macro. Arguments should be denoted by empty braces, ++as for example in @samp{\index[]@{*@}}. Use square brackets to denote ++optional arguments. The star marks where the index key is. ++ ++@var{index-tag} is a short name of the index. @samp{idx} and @samp{glo} ++are reserved for the default index and the glossary. Other indices can ++be defined as well. If this is an integer, the Nth argument of the ++macro holds the index tag. ++ ++@var{key} is a character which is used to identify the macro for input ++with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are ++reserved for default index and glossary. ++ ++@var{prefix} can be a prefix which is added to the @var{key} part of the ++index entry. If you have a macro ++@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix ++should be @samp{Molecules!}. ++ ++@var{exclude} can be a function. If this function exists and returns a ++non-@code{nil} value, the index entry at point is ignored. This was ++implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts ++in the LaTeX2e @code{index} package. ++ ++@var{repeat}, if non-@code{nil}, means the index macro does not typeset ++the entry in the text, so that the text has to be repeated outside the ++index macro. Needed for @code{reftex-index-selection-or-word} and for ++indexing from the phrase buffer. ++ ++The final entry may also be a symbol. It must have an association in ++the variable @code{reftex-index-macros-builtin} to specify the main ++indexing package you are using. Valid values are currently ++@example ++default @r{The LaTeX default - unnecessary to specify this one} ++multind @r{The multind.sty package} ++index @r{The index.sty package} ++index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.} ++ @r{Should not be used - only for old documents} ++@end example ++Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well, ++so with a sufficiently new version of AUCTeX, you should not set the ++package here. ++@end defopt ++ ++@defopt reftex-index-default-macro ++The default index macro for @code{reftex-index-selection-or-word}. ++This is a list with @code{(@var{macro-key} @var{default-tag})}. ++ ++@var{macro-key} is a character identifying an index macro - see ++@code{reftex-index-macros}. ++ ++@var{default-tag} is the tag to be used if the macro requires a ++@var{tag} argument. When this is @code{nil} and a @var{tag} is needed, ++@b{Ref@TeX{}} will ask for it. When this is the empty string and the ++TAG argument of the index macro is optional, the TAG argument will be ++omitted. ++@end defopt ++ ++@defopt reftex-index-default-tag ++Default index tag. When working with multiple indexes, RefTeX queries ++for an index tag when creating index entries or displaying a specific ++index. This variable controls the default offered for these queries. ++The default can be selected with @key{RET} during selection or ++completion. Valid values of this variable are: ++@example ++nil @r{Do not provide a default index} ++"tag" @r{The default index tag given as a string, e.g. "idx"} ++last @r{The last used index tag will be offered as default} ++@end example ++@end defopt ++ ++@defopt reftex-index-math-format ++Format of index entries when copied from inside math mode. When ++@code{reftex-index-selection-or-word} is executed inside TeX math mode, ++the index key copied from the buffer is processed with this format ++string through the @code{format} function. This can be used to add the ++math delimiters (e.g. @samp{$}) to the string. Requires the ++@file{texmathp.el} library which is part of AUCTeX. ++@end defopt ++ ++@defopt reftex-index-phrase-file-extension ++File extension for the index phrase file. This extension will be added ++to the base name of the master file. ++@end defopt ++ ++@defopt reftex-index-phrases-logical-and-regexp ++Regexp matching the @samp{and} operator for index arguments in phrases ++file. When several index arguments in a phrase line are separated by ++this operator, each part will generate an index macro. So each match of ++the search phrase will produce @emph{several} different index entries. ++Make sure this does no match things which are not separators. This ++logical @samp{and} has higher priority than the logical @samp{or} ++specified in @code{reftex-index-phrases-logical-or-regexp}. ++@end defopt ++ ++@defopt reftex-index-phrases-logical-or-regexp ++Regexp matching the @samp{or} operator for index arguments in phrases ++file. When several index arguments in a phrase line are separated by ++this operator, the user will be asked to select one of them at each ++match of the search phrase. The first index arg will be the default. A ++number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make ++sure this does no match things which are not separators. The logical ++@samp{and} specified in @code{reftex-index-phrases-logical-or-regexp} ++has higher priority than this logical @samp{or}. ++@end defopt ++ ++@defopt reftex-index-phrases-search-whole-words ++Non-@code{nil} means phrases search will look for whole words, not subwords. ++This works by requiring word boundaries at the beginning and end of ++the search string. When the search phrase already has a non-word-char ++at one of these points, no word boundary is required there. ++@end defopt ++ ++@defopt reftex-index-phrases-case-fold-search ++Non-@code{nil} means, searching for index phrases will ignore ++case. ++@end defopt ++ ++@defopt reftex-index-verify-function ++A function which is called at each match during global indexing. ++If the function returns nil, the current match is skipped. ++@end defopt ++ ++@defopt reftex-index-phrases-skip-indexed-matches ++Non-@code{nil} means, skip matches which appear to be indexed already. ++When doing global indexing from the phrases buffer, searches for some ++phrases may match at places where that phrase was already indexed. In ++particular when indexing an already processed document again, this ++will even be the norm. When this variable is non-@code{nil}, ++@b{Ref@TeX{}} checks if the match is an index macro argument, or if an ++index macro is directly before or after the phrase. If that is the ++case, that match will be ignored. ++@end defopt ++ ++@defopt reftex-index-phrases-wrap-long-lines ++Non-@code{nil} means, when indexing from the phrases buffer, wrap lines. ++Inserting indexing commands in a line makes the line longer - often ++so long that it does not fit onto the screen. When this variable is ++non-@code{nil}, newlines will be added as necessary before and/or after the ++indexing command to keep lines short. However, the matched text ++phrase and its index command will always end up on a single line. ++@end defopt ++ ++@defopt reftex-index-phrases-sort-prefers-entry ++Non-@code{nil} means when sorting phrase lines, the explicit index entry ++is used. Phrase lines in the phrases buffer contain a search phrase, and ++sorting is normally based on these. Some phrase lines also have ++an explicit index argument specified. When this variable is ++non-@code{nil}, the index argument will be used for sorting. ++@end defopt ++ ++@defopt reftex-index-phrases-sort-in-blocks ++Non-@code{nil} means, empty and comment lines separate phrase buffer ++into blocks. Sorting will then preserve blocks, so that lines are ++re-arranged only within blocks. ++@end defopt ++ ++@defopt reftex-index-phrases-map ++Keymap for the Index Phrases buffer. ++@end defopt ++ ++@defopt reftex-index-phrases-mode-hook ++Normal hook which is run when a buffer is put into ++@code{reftex-index-phrases-mode}. ++@end defopt ++ ++@defopt reftex-index-section-letters ++The letters which denote sections in the index. Usually these are all ++capital letters. Don't use any downcase letters. Order is not ++significant, the index will be sorted by whatever the sort function ++thinks is correct. In addition to these letters, @b{Ref@TeX{}} will ++create a group @samp{!} which contains all entries sorted below the ++lowest specified letter. In the @file{*Index*} buffer, pressing any of ++these capital letters or @kbd{!} will jump to that section. ++@end defopt ++ ++@defopt reftex-index-include-context ++Non-@code{nil} means, display the index definition context in the ++@file{*Index*} buffer. This flag may also be toggled from the ++@file{*Index*} buffer with the @kbd{c} key. ++@end defopt ++ ++@defopt reftex-index-follow-mode ++Non-@code{nil} means, point in @file{*Index*} buffer will cause other ++window to follow. The other window will show the corresponding part of ++the document. This flag can be toggled from within the @file{*Index*} ++buffer with the @kbd{f} key. ++@end defopt ++ ++@deffn Keymap reftex-index-map ++The keymap which is active in the @file{*Index*} buffer ++(@pxref{Index Support}). ++@end deffn ++ ++@node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options ++@section Viewing Cross-References ++@cindex Options, viewing cross-references ++@cindex Viewing cross-references, options ++ ++@defopt reftex-view-crossref-extra ++Macros which can be used for the display of cross references. ++This is used when `reftex-view-crossref' is called with point in an ++argument of a macro. Note that crossref viewing for citations, ++references (both ways) and index entries is hard-coded. This variable ++is only to configure additional structures for which crossreference ++viewing can be useful. Each entry has the structure ++@example ++(@var{macro-re} @var{search-re} @var{highlight}). ++@end example ++@var{macro-re} is matched against the macro. @var{search-re} is the ++regexp used to search for cross references. @samp{%s} in this regexp is ++replaced with the macro argument at point. @var{highlight} is an ++integer indicating which subgroup of the match should be highlighted. ++@end defopt ++ ++@defopt reftex-auto-view-crossref ++Non-@code{nil} means, initially turn automatic viewing of crossref info ++on. Automatic viewing of crossref info normally uses the echo area. ++Whenever point is idle for more than @code{reftex-idle-time} seconds on ++the argument of a @code{\ref} or @code{\cite} macro, and no other ++message is being displayed, the echo area will display information about ++that cross reference. You can also set the variable to the symbol ++@code{window}. In this case a small temporary window is used for the ++display. This feature can be turned on and off from the menu ++(Ref->Options). ++@end defopt ++ ++@defopt reftex-idle-time ++Time (secs) Emacs has to be idle before automatic crossref display ++or toc recentering is done. ++@end defopt ++ ++@defopt reftex-cite-view-format ++Citation format used to display citation info in the message area. See ++the variable @code{reftex-cite-format} for possible percent ++escapes. ++@end defopt ++ ++@defopt reftex-revisit-to-echo ++Non-@code{nil} means, automatic citation display will revisit files if ++necessary. When nil, citation display in echo area will only be active ++for cached echo strings (see @code{reftex-cache-cite-echo}), or for ++BibTeX database files which are already visited by a live associated ++buffers. ++@end defopt ++ ++@defopt reftex-cache-cite-echo ++Non-@code{nil} means, the information displayed in the echo area for ++cite macros (see variable @code{reftex-auto-view-crossref}) is cached and ++saved along with the parsing information. The cache survives document ++scans. In order to clear it, use @kbd{M-x reftex-reset-mode}. ++@end defopt ++ ++@node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options ++@section Finding Files ++@cindex Options, Finding Files ++@cindex Finding files, options ++ ++@defopt reftex-texpath-environment-variables ++List of specifications how to retrieve the search path for TeX files. ++Several entries are possible. ++@itemize @minus ++@item ++If an element is the name of an environment variable, its content is ++used. ++@item ++If an element starts with an exclamation mark, it is used as a command ++to retrieve the path. A typical command with the kpathsearch library ++would be @w{@code{"!kpsewhich -show-path=.tex"}}. ++@item ++Otherwise the element itself is interpreted as a path. ++@end itemize ++Multiple directories can be separated by the system dependent ++@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will ++be expanded recursively. See also @code{reftex-use-external-file-finders}. ++@end defopt ++ ++@defopt reftex-bibpath-environment-variables ++List of specifications how to retrieve the search path for BibTeX ++files. Several entries are possible. ++@itemize @minus ++@item ++If an element is the name of an environment variable, its content is ++used. ++@item ++If an element starts with an exclamation mark, it is used as a command ++to retrieve the path. A typical command with the kpathsearch library ++would be @w{@code{"!kpsewhich -show-path=.bib"}}. ++@item ++Otherwise the element itself is interpreted as a path. ++@end itemize ++Multiple directories can be separated by the system dependent ++@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will ++be expanded recursively. See also @code{reftex-use-external-file-finders}. ++@end defopt ++ ++@defopt reftex-file-extensions ++Association list with file extensions for different file types. ++This is a list of items, each item is like: ++@code{(@var{type} . (@var{def-ext} @var{other-ext} ...))} ++@example ++@var{type}: @r{File type like @code{"bib"} or @code{"tex"}.} ++@var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.} ++@var{other-ext}: @r{Any number of other valid extensions for this file type.} ++@end example ++When a files is searched and it does not have any of the valid extensions, ++we try the default extension first, and then the naked file name. ++@end defopt ++ ++@defopt reftex-search-unrecursed-path-first ++Non-@code{nil} means, search all specified directories before trying ++recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./}, ++then @samp{/tex/}, and then all subdirectories of @samp{./}. If this ++option is @code{nil}, the subdirectories of @samp{./} are searched ++before @samp{/tex/}. This is mainly for speed - most of the time the ++recursive path is for the system files and not for the user files. Set ++this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with ++equal names in wrong sequence. ++@end defopt ++ ++@defopt reftex-use-external-file-finders ++Non-@code{nil} means, use external programs to find files. Normally, ++@b{Ref@TeX{}} searches the paths given in the environment variables ++@code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX ++database files. With this option turned on, it calls an external ++program specified in the option @code{reftex-external-file-finders} ++instead. As a side effect, the variables ++@code{reftex-texpath-environment-variables} and ++@code{reftex-bibpath-environment-variables} will be ignored. ++@end defopt ++ ++@defopt reftex-external-file-finders ++Association list with external programs to call for finding files. Each ++entry is a cons cell @w{@code{(@var{type} . @var{program})}}. ++@var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a ++string containing the external program to use with any arguments. ++@code{%f} will be replaced by the name of the file to be found. Note ++that these commands will be executed directly, not via a shell. Only ++relevant when @code{reftex-use-external-file-finders} is ++non-@code{nil}. ++@end defopt ++ ++@page ++@node Options (Optimizations), Options (Fontification), Options (Finding Files), Options ++@section Optimizations ++@cindex Options, optimizations ++@cindex Optimizations, options ++ ++@defopt reftex-keep-temporary-buffers ++Non-@code{nil} means, keep buffers created for parsing and lookup. ++@b{Ref@TeX{}} sometimes needs to visit files related to the current ++document. We distinguish files visited for ++@table @asis ++@item PARSING ++Parts of a multifile document loaded when (re)-parsing the ++document. ++@item LOOKUP ++BibTeX database files and TeX files loaded to find a reference, to ++display label context, etc. ++@end table ++The created buffers can be kept for later use, or be thrown away ++immediately after use, depending on the value of this variable: ++ ++@table @code ++@item nil ++Throw away as much as possible. ++@item t ++Keep everything. ++@item 1 ++Throw away buffers created for parsing, but keep the ones created for ++lookup. ++@end table ++ ++If a buffer is to be kept, the file is visited normally (which is ++potentially slow but will happen only once). If a buffer is to be thrown ++away, the initialization of the buffer depends upon the variable ++@code{reftex-initialize-temporary-buffers}. ++@end defopt ++ ++@defopt reftex-initialize-temporary-buffers ++Non-@code{nil} means do initializations even when visiting file ++temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and ++other stuff to briefly visit a file. When @code{t}, the full default ++initializations are done (@code{find-file-hook} etc.). Instead of ++@code{t} or @code{nil}, this variable may also be a list of hook ++functions to do a minimal initialization. ++@end defopt ++ ++@defopt reftex-no-include-regexps ++List of regular expressions to exclude certain input files from parsing. ++If the name of a file included via @code{\include} or @code{\input} is ++matched by any of the regular expressions in this list, that file is not ++parsed by @b{Ref@TeX{}}. ++@end defopt ++ ++@defopt reftex-enable-partial-scans ++Non-@code{nil} means, re-parse only 1 file when asked to re-parse. ++Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}} ++commands, or with the @kbd{r} key in menus. When this option is ++@code{t} in a multifile document, we will only parse the current buffer, ++or the file associated with the label or section heading near point in a ++menu. Requesting re-parsing of an entire multifile document then ++requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in ++menus. ++@end defopt ++ ++@defopt reftex-save-parse-info ++Non-@code{nil} means, save information gathered with parsing in files. ++The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is ++used to save the information. When this variable is @code{t}, ++@itemize @minus ++@item ++accessing the parsing information for the first time in an editing ++session will read that file (if available) instead of parsing the ++document. ++@item ++exiting Emacs or killing a buffer in reftex-mode will cause a new ++version of the file to be written. ++@end itemize ++@end defopt ++ ++@defopt reftex-parse-file-extension ++File extension for the file in which parser information is stored. ++This extension is added to the base name of the master file. ++@end defopt ++ ++@defopt reftex-allow-automatic-rescan ++Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems ++necessary. Applies (currently) only in rare cases, when a new label ++cannot be placed with certainty into the internal label list. ++@end defopt ++ ++@defopt reftex-use-multiple-selection-buffers ++Non-@code{nil} means use a separate selection buffer for each label ++type. These buffers are kept from one selection to the next and need ++not to be created for each use - so the menu generally comes up faster. ++The selection buffers will be erased (and therefore updated) ++automatically when new labels in its category are added. See the ++variable @code{reftex-auto-update-selection-buffers}. ++@end defopt ++ ++@defopt reftex-auto-update-selection-buffers ++Non-@code{nil} means, selection buffers will be updated automatically. ++When a new label is defined with @code{reftex-label}, all selection ++buffers associated with that label category are emptied, in order to ++force an update upon next use. When @code{nil}, the buffers are left ++alone and have to be updated by hand, with the @kbd{g} key from the ++label selection process. The value of this variable will only have any ++effect when @code{reftex-use-multiple-selection-buffers} is ++non-@code{nil}. ++@end defopt ++ ++@node Options (Fontification), Options (Misc), Options (Optimizations), Options ++@section Fontification ++@cindex Options, fontification ++@cindex Fontification, options ++ ++@defopt reftex-use-fonts ++Non-@code{nil} means, use fonts in label menu and on-the-fly help. ++Font-lock must be loaded as well to actually get fontified ++display. After changing this option, a rescan may be necessary to ++activate it. ++@end defopt ++ ++@defopt reftex-refontify-context ++Non-@code{nil} means, re-fontify the context in the label menu with ++font-lock. This slightly slows down the creation of the label menu. It ++is only necessary when you definitely want the context fontified. ++ ++This option may have 3 different values: ++@table @code ++@item nil ++Never refontify. ++@item t ++Always refontify. ++@item 1 ++Refontify when necessary, e.g. with old versions of the x-symbol ++package. ++@end table ++The option is ignored when @code{reftex-use-fonts} is @code{nil}. ++@end defopt ++ ++@defopt reftex-highlight-selection ++Non-@code{nil} means, highlight selected text in selection and ++@file{*toc*} buffers. Normally, the text near the cursor is the ++@emph{selected} text, and it is highlighted. This is the entry most ++keys in the selection and @file{*toc*} buffers act on. However, if you ++mainly use the mouse to select an item, you may find it nice to have ++mouse-triggered highlighting @emph{instead} or @emph{as well}. The ++variable may have one of these values: ++ ++@example ++nil @r{No highlighting.} ++cursor @r{Highlighting is cursor driven.} ++mouse @r{Highlighting is mouse driven.} ++both @r{Both cursor and mouse trigger highlighting.} ++@end example ++ ++Changing this variable requires to rebuild the selection and *toc* ++buffers to become effective (keys @kbd{g} or @kbd{r}). ++@end defopt ++ ++@defopt reftex-cursor-selected-face ++Face name to highlight cursor selected item in toc and selection buffers. ++See also the variable @code{reftex-highlight-selection}. ++@end defopt ++@defopt reftex-mouse-selected-face ++Face name to highlight mouse selected item in toc and selection buffers. ++See also the variable @code{reftex-highlight-selection}. ++@end defopt ++@defopt reftex-file-boundary-face ++Face name for file boundaries in selection buffer. ++@end defopt ++@defopt reftex-label-face ++Face name for labels in selection buffer. ++@end defopt ++@defopt reftex-section-heading-face ++Face name for section headings in toc and selection buffers. ++@end defopt ++@defopt reftex-toc-header-face ++Face name for the header of a toc buffer. ++@end defopt ++@defopt reftex-bib-author-face ++Face name for author names in bib selection buffer. ++@end defopt ++@defopt reftex-bib-year-face ++Face name for year in bib selection buffer. ++@end defopt ++@defopt reftex-bib-title-face ++Face name for article title in bib selection buffer. ++@end defopt ++@defopt reftex-bib-extra-face ++Face name for bibliographic information in bib selection buffer. ++@end defopt ++@defopt reftex-select-mark-face ++Face name for marked entries in the selection buffers. ++@end defopt ++@defopt reftex-index-header-face ++Face name for the header of an index buffer. ++@end defopt ++@defopt reftex-index-section-face ++Face name for the start of a new letter section in the index. ++@end defopt ++@defopt reftex-index-tag-face ++Face name for index names (for multiple indices). ++@end defopt ++@defopt reftex-index-face ++Face name for index entries. ++@end defopt ++ ++@node Options (Misc), , Options (Fontification), Options ++@section Miscellaneous ++@cindex Options, misc ++ ++@defopt reftex-extra-bindings ++Non-@code{nil} means, make additional key bindings on startup. These ++extra bindings are located in the users @samp{C-c letter} ++map. @xref{Key Bindings}. ++@end defopt ++ ++@defopt reftex-plug-into-AUCTeX ++Plug-in flags for AUCTeX interface. This variable is a list of ++5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}} ++will ++ ++@example ++- supply labels in new sections and environments (flag 1) ++- supply arguments for macros like @code{\label} (flag 2) ++- supply arguments for macros like @code{\ref} (flag 3) ++- supply arguments for macros like @code{\cite} (flag 4) ++- supply arguments for macros like @code{\index} (flag 5) ++@end example ++ ++You may also set the variable itself to t or nil in order to turn all ++options on or off, respectively.@* ++Supplying labels in new sections and environments applies when creating ++sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@* ++Supplying macro arguments applies when you insert such a macro ++interactively with @kbd{C-c @key{RET}}.@* ++See the AUCTeX documentation for more information. ++@end defopt ++ ++@defopt reftex-revisit-to-follow ++Non-@code{nil} means, follow-mode will revisit files if necessary. ++When nil, follow-mode will be suspended for stuff in unvisited files. ++@end defopt ++ ++@defopt reftex-allow-detached-macro-args ++Non-@code{nil} means, allow arguments of macros to be detached by ++whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb ++[xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that ++this will be the case even if @code{\bb} is defined with zero or one ++argument. ++@end defopt ++ ++@node Keymaps and Hooks, Changes, Options, Top ++@section Keymaps and Hooks ++@cindex Keymaps ++ ++@b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook. ++ ++@deffn Keymap reftex-mode-map ++The keymap for @b{Ref@TeX{}} mode. ++@end deffn ++ ++@deffn {Normal Hook} reftex-load-hook ++Normal hook which is being run when loading @file{reftex.el}. ++@end deffn ++ ++@deffn {Normal Hook} reftex-mode-hook ++Normal hook which is being run when turning on @b{Ref@TeX{}} mode. ++@end deffn ++ ++Furthermore, the 4 modes used for referencing labels, creating ++citations, the table of contents buffer and the phrases buffer have ++their own keymaps and mode hooks. See the respective sections. There ++are many more hooks which are described in the relevant sections about ++options for a specific part of @b{Ref@TeX{}}. ++ ++@node Changes, GNU Free Documentation License, Keymaps and Hooks, Top ++@chapter Changes ++@cindex Changes ++ ++Here is a list of recent changes to @b{Ref@TeX{}}. ++ ++@noindent @b{Version 4.28} ++@itemize @bullet ++@item Support for the Jurabib package. ++@item Improvements when selecting several items in a selection buffer. ++@end itemize ++ ++@noindent @b{Version 4.26} ++@itemize @bullet ++@item ++Support for global incremental search. ++@item ++Some improvements for XEmacs compatibility. ++@end itemize ++ ++@noindent @b{Version 4.25} ++@itemize @bullet ++@item ++Fixed bug with @samp{%F} in a label prefix. Added new escapes ++@samp{%m} and @samp{%M} for mater file name and master directory. ++@end itemize ++ ++@noindent @b{Version 4.24} ++@itemize @bullet ++@item ++Inserting citation commands now prompts for optional arguments ++when called with a prefix argument. Related new options are ++@code{reftex-cite-prompt-optional-args} and ++@code{reftex-cite-cleanup-optional-args}. ++@item ++New option @code{reftex-trust-label-prefix}. Configure this variable ++if you'd like RefTeX to base its classification of labels on prefixes. ++This can speed-up document parsing, but may in some cases reduce the ++quality of the context used by RefTeX to describe a label. ++@item ++Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations} ++is non-nil. ++@item ++Fixed bugs in indexing: Case-sensitive search, quotes before and/or ++after words. Disabled indexing in comment lines. ++@end itemize ++ ++@noindent @b{Version 4.22} ++@itemize @bullet ++@item ++New command @code{reftex-create-bibtex-file} to create a new database ++with all entries referenced in the current document. ++@item ++New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file ++from entries marked in a citation selection buffer. ++@end itemize ++ ++@noindent @b{Version 4.21} ++@itemize @bullet ++@item ++Renaming labels from the toc buffer with key @kbd{M-%}. ++@end itemize ++ ++@noindent @b{Version 4.20} ++@itemize @bullet ++@item ++Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in ++the TOC buffer promote/demote the section at point or all sections in ++the current region. ++@item ++New option @code{reftex-toc-split-windows-fraction} to set the size of ++the window used by the TOC. This makes the old variable ++@code{reftex-toc-split-windows-horizontally-fraction} obsolete. ++@item ++A dedicated frame can show the TOC with the current section ++always automatically highlighted. The frame is created and ++deleted from the toc buffer with the @kbd{d} key. ++@end itemize ++ ++@noindent @b{Version 4.19} ++@itemize @bullet ++@item ++New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current ++section in the TOC buffer without selecting the TOC window. ++@item ++Recentering happens automatically in idle time when the option ++@code{reftex-auto-recenter-toc} is turned on. ++@item ++Fixed several bugs related to automatic cursor positioning in the TOC ++buffer. ++@item ++The highlight in the TOC buffer stays when the focus moves to a ++different window. ++@item ++New command `reftex-goto-label'. ++@item ++Part numbers are no longer included in chapter numbers, and a new ++part does not reset the chapter counter. See new option ++@code{reftex-part-resets-chapter}. ++@end itemize ++ ++@noindent @b{Version 4.18} ++@itemize @bullet ++@item ++@code{reftex-citation} uses the word before the cursor as a default ++search string. ++@item ++Simplified several regular expressions for speed. ++@item ++Better support for chapterbib. ++@end itemize ++ ++@noindent @b{Version 4.17} ++@itemize @bullet ++@item ++The toc window can be split off horizontally. See new options ++@code{reftex-toc-split-windows-horizontally}, ++@code{reftex-toc-split-windows-horizontally-fraction}. ++@item ++It is possible to specify a function which verifies an index match ++during global indexing. See new option @code{reftex-index-verify-function}. ++@item ++The macros which input a file in LaTeX (like \input, \include) can ++be configured. See new option @code{reftex-include-file-commands}. ++@item ++The macros which specify the bibliography file (like \bibliography) can ++be configured. See new option @code{reftex-bibliography-commands}. ++@item ++The regular expression used to search for the \bibliography macro has ++been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by ++chapterbib. ++@item ++Small bug fixes. ++@end itemize ++ ++@noindent @b{Version 4.15} ++@itemize @bullet ++@item ++Fixed bug with parsing of BibTeX files, when fields contain quotes or ++unmatched parenthesis. ++@item ++Small bug fixes. ++@item ++Improved interaction with Emacs LaTeX mode. ++@end itemize ++ ++@noindent @b{Version 4.12} ++@itemize @bullet ++@item ++Support for @file{bibentry} citation style. ++@end itemize ++ ++@noindent @b{Version 4.11} ++@itemize @bullet ++@item ++Fixed bug which would parse @samp{\Section} just like @samp{\section}. ++@end itemize ++ ++@noindent @b{Version 4.10} ++@itemize @bullet ++@item ++Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict ++with @file{reftex-vars.el} on DOS machines. ++@item ++New options @code{reftex-parse-file-extension} and ++@code{reftex-index-phrase-file-extension}. ++@end itemize ++ ++@noindent [.....] ++@ignore ++@noindent @b{Version 4.09} ++@itemize @bullet ++@item ++New option @code{reftex-toc-max-level} to limit the depth of the toc. ++New key binding @kbd{t} in the @file{*toc*} buffer to change this ++setting. ++@item ++RefTeX maintains an @file{Index Phrases} file in which phrases can be ++collected. When the document is ready, RefTeX can search all ++these phrases and assist indexing all matches. ++@item ++The variables @code{reftex-index-macros} and ++@code{reftex-index-default-macro} have changed their syntax slightly. ++The @var{repeat} parameter has move from the latter to the former. ++Also calls to @code{reftex-add-index-macros} from AUCTeX style files ++need to be adapted. ++@item ++The variable @code{reftex-section-levels} no longer contains the ++default stuff which has been moved to a constant. ++@item ++Environments like theorems can be placed into the TOC by putting ++entries for @samp{"begin@{theorem@}"} in ++@code{reftex-setion-levels}. ++@end itemize ++ ++@noindent @b{Version 4.06} ++@itemize @bullet ++@item ++@code{reftex-section-levels} can contain a function to compute the level ++of a sectioning command. ++@item ++Multiple @code{thebibliography} environments recognized. ++@end itemize ++ ++@noindent @b{Version 4.04} ++@itemize @bullet ++@item ++New option @code{reftex-index-default-tag} implements a default for queries. ++@end itemize ++ ++@noindent @b{Version 4.02} ++@itemize @bullet ++@item ++macros ending in @samp{refrange} are considered to contain references. ++@item ++Index entries made with @code{reftex-index-selection-or-word} in TeX ++math mode automatically get enclosing @samp{$} to preserve math mode. See ++new option @code{reftex-index-math-format}. Requires AUCTeX. ++@end itemize ++ ++@noindent @b{Version 4.01} ++@itemize @bullet ++@item ++New command @code{reftex-index-globally} to index a word in many ++places in the document. Also available from the index buffer with ++@kbd{&}. ++@item ++The first item in a @code{reftex-label-alist} entry may now also be a parser ++function to do non-standard parsing. ++@item ++@code{reftex-auto-view-crossref} no longer interferes with ++@code{pop-up-frames} (patch from Stefan Monnier). ++@end itemize ++ ++@noindent @b{Version 4.00} ++@itemize @bullet ++@item ++RefTeX has been split into several smaller files which are autoloaded on ++demand. ++@item ++Index support, along with many new options. ++@item ++The selection of keys for @code{\ref} and @code{\cite} now allows to ++select multiple items by marking entries with the @kbd{m} key. ++@item ++Fancyref support. ++@end itemize ++ ++@noindent @b{Version 3.43} ++@itemize @bullet ++@item ++Viewing cross-references generalized. Now works on @code{\label}, ++@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of ++these, and from BibTeX buffers. ++@item ++New option @code{reftex-view-crossref-extra}. ++@item ++Support for the additional sectioning commands @code{\addchap} and ++@code{\addsec} which are defined in the LaTeX KOMA-Script classes. ++@item ++Files in @code{reftex-default-bibliography} will be searched along ++@code{BIBINPUTS} path. ++@item ++Reading a parse file now checks consistency. ++@end itemize ++ ++@noindent @b{Version 3.42} ++@itemize @bullet ++@item ++File search further refined. New option @code{reftex-file-extensions}. ++@item ++@file{*toc*} buffer can show the file boundaries of a multifile ++document, all labels and associated context. New keys @kbd{i}, @kbd{l}, ++and @kbd{c}. New options @code{reftex-toc-include-labels}, ++@code{reftex-toc-include-context}, ++@code{reftex-toc-include-file-boundaries}. ++@end itemize ++ ++@noindent @b{Version 3.41} ++@itemize @bullet ++@item ++New options @code{reftex-texpath-environment-variables}, ++@code{reftex-use-external-file-finders}, ++@code{reftex-external-file-finders}, ++@code{reftex-search-unrecursed-path-first}. ++@item ++@emph{kpathsearch} support. See new options and ++@code{reftex-bibpath-environment-variables}. ++@end itemize ++ ++@noindent @b{Version 3.38} ++@itemize @bullet ++@item ++@code{reftex-view-crossref} no longer moves to find a macro. Point has ++to be on the macro argument. ++@end itemize ++ ++@noindent @b{Version 3.36} ++@itemize @bullet ++@item ++New value @code{window} for option @code{reftex-auto-view-crossref}. ++@end itemize ++ ++@noindent @b{Version 3.35} ++@itemize @bullet ++@item ++ISO 8859 Latin-1 chars are converted to ASCII to derive better labels. ++This takes back the related changes in 3.34 for safety reasons. ++@end itemize ++ ++@noindent @b{Version 3.34} ++@itemize @bullet ++@item ++Additional flag in @code{reftex-derive-label-parameters} do make only ++lowercase labels (default @code{t}). ++@item ++All @file{.rel} files have a final newline to avoid queries. ++@item ++Single byte representations of accented European letters (ISO-8859-1) ++are now valid in labels. ++@end itemize ++ ++@noindent @b{Version 3.33} ++@itemize @bullet ++@item ++Multiple selection buffers are now hidden buffers (they start with a ++SPACE). ++@item ++Fixed bug with file search when TEXINPUTS environment variable is empty. ++@end itemize ++ ++@noindent @b{Version 3.30} ++@itemize @bullet ++@item ++In @code{reftex-citation}, the regular expression used to scan BibTeX ++files can be specified using completion on known citation keys. ++@item ++New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all} ++entries. ++@item ++New command @code{reftex-renumber-simple-labels} to renumber simple ++labels like @samp{eq:13} sequentially through a document. ++@end itemize ++ ++@noindent @b{Version 3.28} ++@itemize @bullet ++@item ++Auto view crossref for XEmacs uses @code{post-command-hook} to restart the ++timer, since itimer restart is not reliable. ++@item ++Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}. ++@item ++Expansion of recursive tex and bib path rewritten. ++@item ++Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers. ++@item ++Fixed bug with section numbering after *-red sections. ++@end itemize ++ ++@noindent @b{Version 3.27} ++@itemize @bullet ++@item ++Macros can define @emph{neutral} labels, just like @code{\label} ++itself. ++@item ++New option @code{reftex-allow-detached-macro-args}, default @code{nil}! ++@end itemize ++ ++@noindent @b{Version 3.26} ++@itemize @bullet ++@item ++[X]Emacs 19 no longer supported. Use 3.22 for Emacs 19. ++@item ++New hooks @code{reftex-translate-to-ascii-function}, ++@code{reftex-string-to-label-function}. ++@item ++Made sure automatic crossref display will not visit/scan files. ++@end itemize ++ ++@noindent @b{Version 3.25} ++@itemize @bullet ++@item ++Echoing of citation info caches the info for displayed entries. ++New option @code{reftex-cache-cite-echo}. ++@item ++@kbd{M-x reftex-reset-mode} now also removes the file with parsing ++info. ++@item ++Default of @code{reftex-revisit-to-follow} changed to nil. ++@end itemize ++ ++@noindent @b{Version 3.24} ++@itemize @bullet ++@item ++New option @code{reftex-revisit-to-echo}. ++@item ++Interface with X-Symbol (>=2.6) is now complete and stable. ++@item ++Adapted to new outline, which uses overlays. ++@item ++File names in @code{\bibliography} may now have the @code{.bib} ++extension. ++@item ++Fixed Bug with parsing "single file" from master file buffer. ++@end itemize ++ ++@noindent @b{Version 3.23} ++@itemize @bullet ++@item ++Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs. ++@item ++@code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse ++file. ++@item ++The cursor inside a @code{\ref} or @code{\cite} macro can now trigger ++automatic display of crossref information in the echo area. See ++variable @code{reftex-auto-view-crossref}. ++@item ++AUCTeX interface updates: ++@itemize @minus ++@item ++AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections. ++@item ++@b{Ref@TeX{}} notifies AUCTeX about new labels. ++@item ++@code{TeX-arg-ref} no longer used (introduction was unnecessary). ++@item ++@code{reftex-arg-label} and @code{reftex-arg-cite} fixed up. ++@item ++Settings added to @b{Ref@TeX{}} via style files remain local. ++@end itemize ++@item ++Fixed bug with @code{reftex-citation} in non-latex buffers. ++@item ++Fixed bug with syntax table and context refontification. ++@item ++Safety-net for name change of @code{font-lock-reference-face}. ++@end itemize ++ ++@noindent @b{Version 3.22} ++@itemize @bullet ++@item ++Fixed bug with empty context strings. ++@item ++@code{reftex-mouse-view-crossref} is now bound by default at ++@kbd{S-mouse-2}. ++@end itemize ++ ++@noindent @b{Version 3.21} ++@itemize @bullet ++@item ++New options for all faces used by @b{Ref@TeX{}}. They're in the ++customization group @code{reftex-fontification-configurations}. ++@end itemize ++ ++@noindent @b{Version 3.19} ++@itemize @bullet ++@item ++Fixed bug with AUCTeX @code{TeX-master}. ++@end itemize ++ ++@noindent @b{Version 3.18} ++@itemize @bullet ++@item ++The selection now uses a recursive edit, much like minibuffer input. ++This removes all restrictions during selection. E.g. you can now ++switch buffers at will, use the mouse etc. ++@item ++New option @code{reftex-highlight-selection}. ++@item ++@kbd{mouse-2} can be used to select in selection and @file{*toc*} ++buffers. ++@item ++Fixed some problems regarding the interaction with VIPER mode. ++@item ++Follow-mode is now only used after point motion. ++@item ++@b{Ref@TeX{}} now finally does not fontify temporary files anymore. ++@end itemize ++ ++@noindent @b{Version 3.17} ++@itemize @bullet ++@item ++Additional bindings in selection and @file{*toc*} buffers. @kbd{g} ++redefined. ++@item ++New command @code{reftex-save-all-document-buffers}. ++@item ++Magic word matching made more intelligent. ++@item ++Selection process can switch to completion (with @key{TAB}). ++@item ++@code{\appendix} is now recognized and influences section numbering. ++@item ++File commentary shortened considerably (use Info documentation). ++@item ++New option @code{reftex-no-include-regexps} to skip some include files. ++@item ++New option @code{reftex-revisit-to-follow}. ++@end itemize ++ ++@noindent @b{Version 3.16} ++@itemize @bullet ++@item ++New hooks @code{reftex-format-label-function}, ++@code{reftex-format-ref-function}, @code{reftex-format-cite-function}. ++@item ++TeXInfo documentation completed. ++@item ++Some restrictions in Label inserting and referencing removed. ++@item ++New variable @code{reftex-default-bibliography}. ++@end itemize ++ ++@noindent @b{Version 3.14} ++@itemize @bullet ++@item ++Selection buffers can be kept between selections: this is faster. ++See new variable @code{reftex-use-multiple-selection-buffers}. ++@item ++Prefix interpretation of reftex-view-crossref changed. ++@item ++Support for the @code{varioref} package (@kbd{v} key in selection ++buffer). ++@end itemize ++ ++@noindent @b{Version 3.12} ++@itemize @bullet ++@item ++There are 3 new keymaps for customization: @code{reftex-toc-map}, ++@code{reftex-select-label-map}, @code{reftex-select-bib-map}. ++@item ++Refontification uses more standard font-lock stuff. ++@item ++When no BibTeX database files are specified, citations can also use ++@code{\bibitem} entries from a @code{thebibliography} environment. ++@end itemize ++ ++@noindent @b{Version 3.11} ++@itemize @bullet ++@item ++Fixed bug which led to naked label in (e.g.) footnotes. ++@item ++Added scroll-other-window functions to RefTeX-Select. ++@end itemize ++ ++@noindent @b{Version 3.10} ++@itemize @bullet ++@item ++Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19. ++@item ++Removed unimportant code which caused OS/2 Emacs to crash. ++@item ++All customization variables now accessible from menu. ++@end itemize ++ ++@noindent @b{Version 3.07} ++@itemize @bullet ++@item ++@code{Ref} menu improved. ++@end itemize ++ ++@noindent @b{Version 3.05} ++@itemize @bullet ++@item ++Compatibility code now first checks for XEmacs feature. ++@end itemize ++ ++@noindent @b{Version 3.04} ++@itemize @bullet ++@item ++Fixed BUG in the @emph{xr} support. ++@end itemize ++ ++@noindent @b{Version 3.03} ++@itemize @bullet ++@item ++Support for the LaTeX package @code{xr}, for inter-document ++references. ++@item ++A few (minor) Mule-related changes. ++@item ++Fixed bug which could cause @emph{huge} @file{.rel} files. ++@item ++Search for input and @file{.bib} files with recursive path definitions. ++@end itemize ++ ++@noindent @b{Version 3.00} ++@itemize @bullet ++@item ++@b{Ref@TeX{}} should work better for very large projects: ++@item ++The new parser works without creating a master buffer. ++@item ++Rescanning can be limited to a part of a multifile document. ++@item ++Information from the parser can be stored in a file. ++@item ++@b{Ref@TeX{}} can deal with macros having a naked label as an argument. ++@item ++Macros may have white space and newlines between arguments. ++@item ++Multiple identical section headings no longer confuse ++@code{reftex-toc}. ++@item ++@b{Ref@TeX{}} should work correctly in combination with buffer-altering ++packages like outline, folding, x-symbol, iso-cvt, isotex, etc. ++@item ++All labeled environments discussed in @emph{The LaTeX Companion} by ++Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of ++@b{Ref@TeX{}}'s defaults. ++@end itemize ++ ++@noindent @b{Version 2.17} ++@itemize @bullet ++@item ++Label prefix expands % escapes with current file name and other stuff. ++@item ++Citation format now with % escapes. This is not backward ++compatible! ++@item ++TEXINPUTS variable recognized when looking for input files. ++@item ++Context can be the nth argument of a macro. ++@item ++Searching in the select buffer is now possible (@kbd{C-s} and ++@kbd{C-r}). ++@item ++Display and derive-label can use two different context methods. ++@item ++AMSmath @code{xalignat} and @code{xxalignat} added. ++@end itemize ++ ++@noindent @b{Version 2.14} ++@itemize @bullet ++@item ++Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with ++AUCTeX. ++@end itemize ++ ++@noindent @b{Version 2.11} ++@itemize @bullet ++@item ++Submitted for inclusion to Emacs and XEmacs. ++@end itemize ++ ++@noindent @b{Version 2.07} ++@itemize @bullet ++@item ++New functions @code{reftex-search-document}, ++@code{reftex-query-replace-document}. ++@end itemize ++ ++@noindent @b{Version 2.05} ++@itemize @bullet ++@item ++Support for @file{custom.el}. ++@item ++New function @code{reftex-grep-document} (thanks to Stephen Eglen). ++@end itemize ++ ++@noindent @b{Version 2.03} ++@itemize @bullet ++@item ++@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to ++default environments. ++@item ++@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari). ++@item ++New functions @code{reftex-arg-label}, @code{reftex-arg-ref}, ++@code{reftex-arg-cite}. ++@item ++Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is ++required. ++@item ++@code{reftex-add-to-label-alist} (to be called from AUCTeX style ++files). ++@item ++Finding context with a hook function. ++@item ++Sorting BibTeX entries (new variable: ++@code{reftex-sort-bibtex-matches}). ++@end itemize ++ ++@noindent @b{Version 2.00} ++@itemize @bullet ++@item ++Labels can be derived from context (default for sections). ++@item ++Configuration of label insertion and label referencing revised. ++@item ++Crossref fields in BibTeX database entries. ++@item ++@code{reftex-toc} introduced (thanks to Stephen Eglen). ++@end itemize ++ ++@noindent @b{Version 1.09} ++@itemize @bullet ++@item ++Support for @code{tex-main-file}, an analogue for ++@code{TeX-master}. ++@item ++MS-DOS support. ++@end itemize ++ ++@noindent @b{Version 1.07} ++@itemize @bullet ++@item ++@b{Ref@TeX{}} gets its own menu. ++@end itemize ++ ++@noindent @b{Version 1.05} ++@itemize @bullet ++@item ++XEmacs port. ++@end itemize ++ ++@noindent @b{Version 1.04} ++@itemize @bullet ++@item ++Macros as wrappers, AMSTeX support, delayed context parsing for ++new labels. ++@end itemize ++@end ignore ++ ++@noindent @b{Version 1.00} ++@itemize @bullet ++@item ++released on 7 Jan 1997. ++@end itemize ++ ++@node GNU Free Documentation License, Index, Changes, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index, , GNU Free Documentation License, Top ++@unnumbered Index ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43 ++@end ignore +diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi +new file mode 100644 +index 0000000..ef6bce2 +--- /dev/null ++++ b/doc/misc/remember.texi +@@ -0,0 +1,409 @@ ++\input texinfo @c -*-texinfo-*- ++@c %**start of header ++@setfilename ../../info/remember ++@settitle Remember Manual ++@syncodeindex fn cp ++@c %**end of header ++ ++@copying ++This manual is for Remember Mode, version 1.9 ++ ++Copyright @copyright{} 2001, 2004, 2005, 2007, 2008, 2009 ++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 Emacs ++@direntry ++* Remember: (remember). Simple information manager for Emacs ++@end direntry ++ ++@titlepage ++@title Guide to Remember Mode ++@subtitle a simple information manager ++@subtitle for Emacs and XEmacs ++ ++@c The following two commands ++@c start the copyright page. ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top, Preface, (dir), (dir) ++@comment node-name, next, previous, up ++@top Remember ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* Preface:: About the documentation. ++* Introduction:: What is Remember Mode? ++* Installation:: How to install Remember. ++* Implementation:: How Remember came into existence. ++* Quick Start:: Get started using Remember. ++* Function Reference:: Interactive functions in remember.el. ++* Keystrokes:: Keystrokes bound in Remember Mode. ++* Backends:: Backends for saving notes. ++* GNU Free Documentation License:: The license for this documentation. ++* Concept Index:: Search for terms. ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++ ++Backends ++ ++* Text File:: Saving to a text file. ++* Diary:: Saving to a Diary file. ++* Mailbox:: Saving to a mailbox. ++* Org:: Saving to an Org Mode file. ++ ++@end detailmenu ++@end menu ++ ++@node Preface, Introduction, Top, Top ++@comment node-name, next, previous, up ++@chapter Preface ++ ++This document describes remember-el, which was written by John Wiegley, ++was once maintained by Sacha Chua, and is now maintained by the Emacs ++developers. ++ ++This document is a work in progress, and your contribution will be ++greatly appreciated. ++ ++@node Introduction, Installation, Preface, Top ++@comment node-name, next, previous, up ++@chapter Introduction ++ ++Todo lists, schedules, phone databases... everything we use databases ++for is really just a way to extend the power of our memory, to be able ++to remember what our conscious mind may not currently have access to. ++ ++There are many different databases out there---and good ones---which ++this mode is not trying to replace. Rather, it's how that data gets ++there that's the question. Most of the time, we just want to say ++"Remember so-and-so's phone number, or that I have to buy dinner for the ++cats tonight." That's the FACT. How it's stored is really the ++computer's problem. But at this point in time, it's most definitely ++also the user's problem, and sometimes so laboriously so that people ++just let data slip, rather than expend the effort to record it. ++ ++``Remember'' is a mode for remembering data. It uses whatever ++back-end is appropriate to record and correlate the data, but its main ++intention is to allow you to express as @emph{little} structure as ++possible up front. If you later want to express more powerful ++relationships between your data, or state assumptions that were at ++first too implicit to be recognized, you can ``study'' the data later ++and rearrange it. But the initial ``just remember this'' impulse ++should be as close to simply throwing the data at Emacs as possible. ++ ++Have you ever noticed that having a laptop to write on doesn't ++@emph{actually} increase the amount of quality material that you turn ++out, in the long run? Perhaps it's because the time we save ++electronically in one way, we're losing electronically in another; the ++tool should never dominate one's focus. As the mystic Faridu'd-Din ++`Attar wrote: ``Be occupied as little as possible with things of the ++outer world but much with things of the inner world; then right action ++will overcome inaction.'' ++ ++If Emacs could become a more intelligent data store, where brainstorming ++would focus on the @emph{ideas} involved---rather than the structuring ++and format of those ideas, or having to stop your current flow of work ++in order to record them---it would map much more closely to how the mind ++(well, at least mine) works, and hence would eliminate that very ++manual-ness which computers from the very beginning have been championed ++as being able to reduce. ++ ++@node Installation, Implementation, Introduction, Top ++@comment node-name, next, previous, up ++@chapter Installation ++ ++Installing Remember Mode is as simple as adding the following lines to ++your Emacs configuration file (usually @file{~/.emacs.d/init.el} or ++@file{~/.emacs}). ++ ++@lisp ++(add-to-list 'load-path "/path/to/remember") ++(require 'remember) ++@end lisp ++ ++@node Implementation, Quick Start, Installation, Top ++@comment node-name, next, previous, up ++@chapter Implementation ++ ++Hyperbole, as a data presentation tool, always struck me as being very ++powerful, but it seemed to require a lot of ``front-end'' work before ++that data was really available. The problem with BBDB, or keeping up ++a Bibl-mode file, is that you have to use different functions to ++record the data, and it always takes time to stop what you're doing, ++format the data in the manner expected by that particular data ++interface, and then resume your work. ++ ++With ``remember'', you just hit @kbd{M-x remember} (you'd probably ++want to bind this to an easily accessible keystroke, like @kbd{C-x ++M-r}), slam in your text however you like, and then hit @kbd{C-c C-c}. ++It will file the data away for later retrieval, and possibly indexing. ++ ++Indexing is to data what ``studying'' is in the real world. What you do ++when you study (or lucubrate, for some of us) is to realize certain ++relationships implicit in the data, so that you can make use of those ++relationships. Expressing that a certain quote you remembered was a ++literary quote, and that you want the ability to pull up all quotes of a ++literary nature, is what studying does. This is a more labor intensive ++task than the original remembering of the data, and it's typical in real ++life to set aside a special period of time for doing this work. ++ ++``Remember'' works in the same way. When you enter data, either by ++typing it into a buffer, or using the contents of the selected region, ++it will store that data---unindexed, uninterpreted---in a data pool. ++It will also try to remember as much context information as possible ++(any text properties that were set, where you copied it from, when, ++how, etc). Later, you can walk through your accumulated set of data ++(both organized, and unorganized) and easily begin moving things ++around, and making annotations that will express the full meaning of ++that data, as far as you know it. ++ ++Obviously this latter stage is more user-interface intensive, and it ++would be nice if ``remember'' could do it as elegantly as possible, ++rather than requiring a billion keystrokes to reorganize your ++hierarchy. Well, as the future arrives, hopefully experience and user ++feedback will help to make this as intuitive a tool as possible. ++ ++@node Quick Start, Function Reference, Implementation, Top ++@comment node-name, next, previous, up ++@chapter Quick Start ++ ++@itemize ++ ++@item ++Load @file{remember.el}. ++ ++@item ++Type @kbd{M-x remember}. The @samp{*Remember*} buffer should be ++displayed. ++ ++@item ++Type in what you want to remember. The first line will be treated as ++the headline, and the rest of the buffer will contain the body of the ++note. ++ ++@item ++Type @kbd{C-c C-c} (@code{remember-finalize}) to save the note and close ++the @samp{*Remember*} buffer. ++@end itemize ++ ++By default, @code{remember-finalize} saves the note in @file{~/.notes}. ++You can edit it now to see the remembered and timestamped note. You ++can edit this file however you want. New entries will always be added ++to the end. ++ ++To remember a region of text, use the universal prefix. @kbd{C-u M-x ++remember} displays a @samp{*Remember*} buffer with the region as the ++initial contents. ++ ++As a simple beginning, you can start by using the Text File backend, ++keeping your @file{~/.notes} file in outline-mode format, with a final ++entry called @samp{* Raw data}. Remembered data will be added to the ++end of the file. Every so often, you can move the data that gets ++appended there into other files, or reorganize your document. ++ ++You can also store remembered data in other backends. ++(@pxref{Backends}) ++ ++Here is one way to map the remember functions in your @file{.emacs} to ++very accessible keystrokes facilities using the mode: ++ ++@lisp ++(autoload 'remember ``remember'' nil t) ++(autoload 'remember-region ``remember'' nil t) ++ ++(define-key global-map (kbd " r") 'remember) ++(define-key global-map (kbd " R") 'remember-region) ++@end lisp ++ ++By default, remember uses the first annotation returned by ++@code{remember-annotation-functions}. To include all of the annotations, ++set @code{remember-run-all-annotation-functions-flag} to non-nil. ++ ++@defopt remember-run-all-annotation-functions-flag ++Non-nil means use all annotations returned by ++@code{remember-annotation-functions}. ++@end defopt ++ ++You can write custom functions that use a different set of ++remember-annotation-functions. For example: ++ ++@lisp ++(defun my/remember-with-filename () ++ "Always use the filename." ++ (interactive) ++ (let ((remember-annotation-functions '(buffer-file-name))) ++ (call-interactively 'remember))) ++@end lisp ++ ++@node Function Reference, Keystrokes, Quick Start, Top ++@comment node-name, next, previous, up ++@chapter Function Reference ++ ++@file{remember.el} defines the following interactive functions: ++ ++@defun remember initial ++Remember an arbitrary piece of data. With a prefix, it will use the ++region as @var{initial}. ++@end defun ++ ++@defun remember-region beg end ++If called from within the remember buffer, @var{beg} and @var{end} are ++ignored, and the entire buffer will be remembered. If called from any ++other buffer, that region, plus any context information specific to ++that region, will be remembered. ++@end defun ++ ++@defun remember-clipboard ++Remember the contents of the current clipboard. This is most useful ++for remembering things from Netscape or other X Windows applications. ++@end defun ++ ++@defun remember-finalize ++Remember the contents of the current buffer. ++@end defun ++ ++@defun remember-mode ++This enters the major mode for output from @command{remember}. This ++buffer is used to collect data that you want remember. Just hit ++@kbd{C-c C-c} when you're done entering, and it will go ahead and file ++the data for latter retrieval, and possible indexing. ++@end defun ++ ++@node Keystrokes, Backends, Function Reference, Top ++@comment node-name, next, previous, up ++@chapter Keystroke Reference ++ ++@file{remember.el} defines the following keybindings by default: ++ ++@table @kbd ++ ++@item C-c C-c (`remember-finalize') ++Remember the contents of the current buffer. ++ ++@item C-c C-k (`remember-destroy') ++Destroy the current *Remember* buffer. ++ ++@item C-x C-s (`remember-finalize') ++Remember the contents of the current buffer. ++ ++@end table ++ ++@node Backends, GNU Free Documentation License, Keystrokes, Top ++@comment node-name, next, previous, up ++@chapter Backends ++ ++You can save remembered notes to a variety of backends. ++ ++@menu ++* Text File:: Saving to a text file. ++* Diary:: Saving to a Diary file. ++* Mailbox:: Saving to a mailbox. ++* Org:: Saving to an Org Mode file. ++@end menu ++ ++@node Text File, Diary, Backends, Backends ++@comment node-name, next, previous, up ++@section Saving to a Text File ++@cindex text file, saving to ++ ++@subheading Insinuation ++ ++@lisp ++(setq remember-handler-functions '(remember-append-to-file)) ++@end lisp ++ ++@subheading Options ++ ++@defopt remember-data-file ++The file in which to store unprocessed data. ++@end defopt ++ ++@defopt remember-leader-text ++The text used to begin each remember item. ++@end defopt ++ ++@node Diary, Mailbox, Text File, Backends ++@comment node-name, next, previous, up ++@section Saving to a Diary file ++@cindex diary, integration ++ ++@subheading Insinuation ++ ++@lisp ++(add-to-list 'remember-handler-functions 'remember-diary-extract-entries) ++@end lisp ++ ++@subheading Options ++ ++@defopt remember-diary-file ++File for extracted diary entries. ++If this is nil, then @code{diary-file} will be used instead." ++@end defopt ++ ++@node Mailbox, Org, Diary, Backends ++@comment node-name, next, previous, up ++@section Saving to a Mailbox ++@cindex mailbox, saving to ++ ++@subheading Insinuation ++ ++@lisp ++(add-to-list 'remember-handler-functions 'remember-store-in-mailbox) ++@end lisp ++ ++@subheading Options ++ ++@defopt remember-mailbox ++The file in which to store remember data as mail. ++@end defopt ++ ++@defopt remember-default-priority ++The default priority for remembered mail messages. ++@end defopt ++ ++@node Org, , Mailbox, Backends ++@comment node-name, next, previous, up ++@section Saving to an Org Mode file ++@cindex org mode, integration ++ ++For instructions on how to integrate Remember with Org Mode, ++consult @ref{Remember, , , org}. ++ ++@node GNU Free Documentation License, Concept Index, Backends, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Concept Index, , GNU Free Documentation License, Top ++@comment node-name, next, previous, up ++@unnumbered Index ++ ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 5b980db0-20cc-4167-b845-52dc11d53b9f ++@end ignore +diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi +new file mode 100644 +index 0000000..b787302 +--- /dev/null ++++ b/doc/misc/sasl.texi +@@ -0,0 +1,273 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/sasl ++ ++@set VERSION 0.2 ++@settitle Emacs SASL Library @value{VERSION} ++ ++@copying ++This file describes the Emacs SASL library, version @value{VERSION}. ++ ++Copyright @copyright{} 2000, 2004, 2005, 2006, 2007, 2008, 2009 ++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 Emacs 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.'' ++ ++This document is part of a collection distributed under the GNU Free ++Documentation License. If you want to distribute this document ++separately from the collection, you can do so by adding a copy of the ++license to the document, as described in section 6 of the license. ++@end quotation ++@end copying ++ ++@dircategory Emacs ++@direntry ++* SASL: (sasl). The Emacs SASL library. ++@end direntry ++ ++ ++@titlepage ++@title Emacs SASL Library @value{VERSION} ++ ++@author by Daiki Ueno ++@page ++ ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++ ++@node Top ++@top Emacs SASL ++ ++SASL is a common interface to share several authentication mechanisms between ++applications using different protocols. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview:: What Emacs SASL library is. ++* How to use:: Adding authentication support to your applications. ++* Data types:: ++* Back end drivers:: Writing your own drivers. ++* Index:: ++* Function Index:: ++* Variable Index:: ++@end menu ++ ++@node Overview ++@chapter Overview ++ ++@sc{sasl} is short for @dfn{Simple Authentication and Security Layer}. ++This standard is documented in RFC2222. It provides a simple method for ++adding authentication support to various application protocols. ++ ++The toplevel interface of this library is inspired by Java @sc{sasl} ++Application Program Interface. It defines an abstraction over a series ++of authentication mechanism drivers (@ref{Back end drivers}). ++ ++Back end drivers are designed to be close as possible to the ++authentication mechanism. You can access the additional configuration ++information anywhere from the implementation. ++ ++@node How to use ++@chapter How to use ++ ++(Not yet written). ++ ++To use Emacs SASL library, please evaluate following expression at the ++beginning of your application program. ++ ++@lisp ++(require 'sasl) ++@end lisp ++ ++If you want to check existence of sasl.el at runtime, instead you ++can list autoload settings for functions you want. ++ ++@node Data types ++@chapter Data types ++ ++There are three data types to be used for carrying a negotiated ++security layer---a mechanism, a client parameter and an authentication ++step. ++ ++@menu ++* Mechanisms:: ++* Clients:: ++* Steps:: ++@end menu ++ ++@node Mechanisms ++@section Mechanisms ++ ++A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl} ++authentication mechanism driver. ++ ++@defvar sasl-mechanisms ++A list of mechanism names. ++@end defvar ++ ++@defun sasl-find-mechanism mechanisms ++ ++Retrieve an appropriate mechanism. ++This function compares @var{mechanisms} and @code{sasl-mechanisms} then ++returns appropriate @code{sasl-mechanism} object. ++ ++@example ++(let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5"))) ++ (setq mechanism (sasl-find-mechanism server-supported-mechanisms))) ++@end example ++ ++@end defun ++ ++@defun sasl-mechanism-name mechanism ++Return name of mechanism, a string. ++@end defun ++ ++If you want to write an authentication mechanism driver (@ref{Back end ++drivers}), use @code{sasl-make-mechanism} and modify ++@code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly. ++ ++@defun sasl-make-mechanism name steps ++Allocate a @code{sasl-mechanism} object. ++This function takes two parameters---name of the mechanism, and a list ++of authentication functions. ++ ++@example ++(defconst sasl-anonymous-steps ++ '(identity ;no initial response ++ sasl-anonymous-response)) ++ ++(put 'sasl-anonymous 'sasl-mechanism ++ (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps)) ++@end example ++ ++@end defun ++ ++@node Clients ++@section Clients ++ ++A client (@code{sasl-client} object) initialized with four ++parameters---a mechanism, a user name, name of the service and name of ++the server. ++ ++@defun sasl-make-client mechanism name service server ++Prepare a @code{sasl-client} object. ++@end defun ++ ++@defun sasl-client-mechanism client ++Return the mechanism (@code{sasl-mechanism} object) of client. ++@end defun ++ ++@defun sasl-client-name client ++Return the authorization name of client, a string. ++@end defun ++ ++@defun sasl-client-service client ++Return the service name of client, a string. ++@end defun ++ ++@defun sasl-client-server client ++Return the server name of client, a string. ++@end defun ++ ++If you want to specify additional configuration properties, please use ++@code{sasl-client-set-property}. ++ ++@defun sasl-client-set-property client property value ++Add the given property/value to client. ++@end defun ++ ++@defun sasl-client-property client property ++Return the value of the property of client. ++@end defun ++ ++@defun sasl-client-set-properties client plist ++Destructively set the properties of client. ++The second argument is the new property list. ++@end defun ++ ++@defun sasl-client-properties client ++Return the whole property list of client configuration. ++@end defun ++ ++@node Steps ++@section Steps ++ ++A step (@code{sasl-step} object) is an abstraction of authentication ++``step'' which holds the response value and the next entry point for the ++authentication process (the latter is not accessible). ++ ++@defun sasl-step-data step ++Return the data which @var{step} holds, a string. ++@end defun ++ ++@defun sasl-step-set-data step data ++Store @var{data} string to @var{step}. ++@end defun ++ ++To get the initial response, you should call the function ++@code{sasl-next-step} with the second argument @code{nil}. ++ ++@example ++(setq name (sasl-mechanism-name mechanism)) ++@end example ++ ++At this point we could send the command which starts a SASL ++authentication protocol exchange. For example, ++ ++@example ++(process-send-string ++ process ++ (if (sasl-step-data step) ;initial response ++ (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t)) ++ (format "AUTH %s\r\n" name))) ++@end example ++ ++To go on with the authentication process, all you have to do is call ++@code{sasl-next-step} consecutively. ++ ++@defun sasl-next-step client step ++Perform the authentication step. ++At the first time @var{step} should be set to @code{nil}. ++@end defun ++ ++@node Back end drivers ++@chapter Back end drivers ++ ++(Not yet written). ++ ++@node Index ++@chapter Index ++@printindex cp ++ ++@node Function Index ++@chapter Function Index ++@printindex fn ++ ++@node Variable Index ++@chapter Variable Index ++@printindex vr ++ ++@summarycontents ++@contents ++@bye ++ ++@c End: ++ ++@ignore ++ arch-tag: dc9650be-a953-40bf-bc55-24fe5f19d875 ++@end ignore +diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi +new file mode 100644 +index 0000000..979cff2 +--- /dev/null ++++ b/doc/misc/sc.texi +@@ -0,0 +1,1946 @@ ++\input texinfo @comment -*-texinfo-*- ++@comment 3.48 ++@comment %**start of header (This is for running Texinfo on a region.) ++@setfilename ../../info/sc ++@settitle Supercite User's Manual ++@iftex ++@finalout ++@end iftex ++ ++@c @setchapternewpage odd % For book style double sided manual. ++@comment %**end of header (This is for running Texinfo on a region.) ++ ++@copying ++This document describes Supercite, an Emacs package for citing and ++attributing replies to mail and news messages. ++ ++Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 ++ ++@c @smallbook ++ ++@dircategory Emacs ++@direntry ++* SC: (sc). Supercite lets you cite parts of messages you're ++ replying to, in flexible ways. ++@end direntry ++ ++@titlepage ++@title Supercite User's Manual ++@subtitle cite and attribute mail and ++@subtitle news, in flexible ways ++ ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@summarycontents ++@contents ++ ++@ifnottex ++@node Top, Introduction, (dir), (dir) ++@comment node-name, next, previous, up ++ ++@insertcopying ++ ++The manual is divided ++into the following chapters. ++ ++@menu ++* Introduction:: ++* Citations:: ++* Getting Connected:: ++* Replying and Yanking:: ++* Selecting an Attribution:: ++* Configuring the Citation Engine:: ++* Post-yank Formatting Commands:: ++* Information Keys and the Info Alist:: ++* Reference Headers:: ++* Hints to MUA Authors:: ++* Thanks and History:: ++ ++* GNU Free Documentation License:: ++* Concept Index:: ++* Command Index:: ++* Key Index:: ++* Variable Index:: ++@end menu ++@end ifnottex ++ ++ ++@node Introduction, Usage Overview, Top, Top ++@chapter Introduction ++ ++Supercite is a GNU Emacs package written entirely in Emacs Lisp. It ++interfaces to most of the commonly used Emacs mail user agents ++(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides ++sophisticated facilities for the citing and attributing of message ++replies. Supercite has a very specific and limited role in the process ++of composing replies to both USENET network news and electronic mail. ++ ++The preferred way to spell Supercite is with a capital @samp{S}, ++lowercase @samp{upercite}. ++ ++@ifinfo ++@menu ++* Usage Overview:: ++* What Supercite Does Not Do:: ++* What Supercite Does:: ++@end menu ++@end ifinfo ++ ++@cindex MUA ++@cindex NUA ++Supercite is only useful in conjunction with MUAs and NUAs such as VM, ++Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a ++reply buffer has been setup. Thereafter, Supercite's many commands and ++formatting styles are available in that reply buffer until the reply is ++sent. Supercite is re-initialized in each new reply buffer. ++ ++ ++@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction ++@kindex r ++@kindex f ++@kindex C-c C-y ++@cindex yank ++@cindex cite, citing ++@cindex attribute, attributing ++@section Usage Overview ++ ++Typical usage is as follows. You want to reply or followup to a message ++in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} ++(i.e., ``forward'') to begin composing the reply. In response, the MUA ++will create a reply buffer and initialize the outgoing mail headers ++appropriately. The body of the reply will usually be empty at this ++point. You now decide that you would like to include part of the ++original message in your reply. To do this, you @dfn{yank} the original ++message into the reply buffer, typically with a key stroke such as ++@kbd{C-c C-y}. This sequence will invoke an MUA-specific function which ++fills the body of the reply with the original message and then ++@dfn{attributes} this text to its author. This is called @dfn{citing} ++and its effect is to prefix every line from the original message with a ++special text tag. Most MUAs provide some default style of citing; by ++using Supercite you gain a wider flexibility in the look and style of ++citations. Supercite's only job is to cite the original message. ++ ++@node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction ++@section What Supercite Doesn't Do ++ ++Because of this clear division of labor, there are useful features which ++are the sole responsibility of the MUA, even though it might seem that ++Supercite should provide them. For example, many people would like to ++be able to yank (and cite) only a portion of the original message. ++Since Supercite only modifies the text it finds in the reply buffer as ++set up by the MUA, it is the MUA's responsibility to do partial yanking. ++@xref{Reply Buffer Initialization}.@refill ++ ++@vindex mail-header-separator ++Another potentially useful thing would be for Supercite to set up the ++outgoing mail headers with information it gleans from the reply buffer. ++But by previously agreed upon convention, any text above the ++@code{mail-header-separator} which separates mail headers from message ++bodies cannot be modified by Supercite. Supercite, in fact, doesn't ++know anything about the meaning of these headers, and never ventures ++outside the designated region. @xref{Hints to MUA Authors}, for more ++details.@refill ++ ++@node What Supercite Does, Citations, What Supercite Does Not Do, Introduction ++@findex sc-cite-original ++@section What Supercite Does ++ ++Supercite is invoked for the first time on a reply buffer via your MUA's ++reply or forward command. This command will actually perform citations ++by calling a hook variable to which Supercite's top-level function ++@code{sc-cite-original} has been added. When @code{sc-cite-original} is ++executed, the original message must be set up in a very specific way, ++but this is handled automatically by the MUA. @xref{Hints to MUA ++Authors}.@refill ++ ++@cindex info alist ++The first thing Supercite does, via @code{sc-cite-original}, is to parse ++through the original message's mail headers. It saves this data in an ++@dfn{information association list}, or @dfn{info alist}. The information ++in this list is used in a number of places throughout Supercite. ++@xref{Information Keys and the Info Alist}.@refill ++ ++@cindex nuking mail headers ++@cindex reference header ++After the mail header info is extracted, the headers are optionally ++removed (@dfn{nuked}) from the reply. Supercite then writes a ++@dfn{reference header} into the buffer. This reference header is a ++string carrying details about the citation it is about to perform. ++ ++@cindex modeline ++Next, Supercite visits each line in the reply, transforming the line ++according to a customizable ``script.'' Lines which were not previously ++cited in the original message are given a citation, while already cited ++lines remain untouched, or are coerced to your preferred style. ++Finally, Supercite installs a keymap into the reply buffer so that you ++have access to Supercite's post-yank formatting and reciting commands as ++you subsequently edit your reply. You can tell that Supercite has been ++installed into the reply buffer because that buffer's modeline will ++display the minor mode string @samp{SC}. ++ ++@cindex filladapt ++@cindex gin-mode ++@vindex fill-prefix ++@findex fill-paragraph ++When the original message is cited by @code{sc-cite-original}, it will ++(optionally) be filled by Supercite. However, if you manually edit the ++cited text and want to re-fill it, you must use an add-on package such ++as @cite{filladapt} or @cite{gin-mode}. These packages can recognize ++Supercited text and will fill them appropriately. Emacs' built-in ++filling routines, e.g@. @code{fill-paragraph}, do not recognize cited ++text and will not re-fill them properly because it cannot guess the ++@code{fill-prefix} being used. ++@xref{Post-yank Formatting Commands}, for details.@refill ++ ++As mentioned above, Supercite provides commands to recite or uncite ++regions of text in the reply buffer, and commands to perform other ++beautifications on the cited original text, maintaining consistent and ++informative citations throughout. Supercite tries to be as configurable ++as possible to allow for a wide range of personalized citation styles, ++but it is also immediately useful with the default configuration, once ++it has been properly connected to your MUA. @xref{Getting Connected}, ++for more details.@refill ++ ++@node Citations, Citation Elements, What Supercite Does, Top ++@cindex nested citations ++@cindex citation ++@chapter Citations ++ ++A @dfn{citation} is the acknowledgement of the original author of a mail ++message in the body of the reply. There are two basic citation styles ++which Supercite supports. The first, called @dfn{nested citations} is ++an anonymous form of citation; in other words, an indication is made ++that the cited line was written by someone @emph{other} that the current ++message author (i.e., other than you, the person composing the reply), ++but no reference is made as to the identity of the original author. ++This style should look familiar since its use on the net is widespread. ++Here's an example of what a message buffer would look like using nested ++citations after multiple replies: ++ ++@example ++>> John originally wrote this ++>> and this as well ++> Jane said that John didn't know ++> what he was talking about ++And that's what I think too. ++@end example ++ ++@ifinfo ++@menu ++* Citation Elements:: ++* Recognizing Citations:: ++@end menu ++@end ifinfo ++ ++Note that multiple inclusions of the original messages result in a ++nesting of the @samp{@code{>}} characters. This can sometimes be quite ++confusing when many levels of citations are included since it may be ++difficult or impossible to figure out who actually participated in the ++thread, and multiple nesting of @samp{@code{>}} characters can sometimes ++make the message very difficult for the eye to scan. ++ ++@cindex non-nested citations ++In @dfn{non-nested citations}, each cited line begins with an ++informative string attributing that line to the original author. Only ++the first level of attribution will be shown; subsequent citations don't ++nest the citation strings. The above dialog might look like this when ++non-nested citations are used: ++ ++@example ++John> John originally wrote this ++John> and this as well ++Jane> Jane said that John didn't know ++Jane> what he was talking about ++And that's what I think too. ++@end example ++ ++Notice here that my inclusion of Jane's inclusion of John's original ++message did not result in a line cited with @samp{Jane>John>}. ++ ++@vindex sc-nested-citation-p ++@vindex nested-citation-p (sc-) ++Supercite supports both styles of citation, and the variable ++@code{sc-nested-citation-p} controls which style it will use when citing ++previously uncited text. When this variable is @code{nil} (the default), ++non-nested citations are used. When non-@code{nil}, nested citations ++are used. ++ ++ ++@node Citation Elements, Recognizing Citations, Citations, Citations ++@cindex citation string ++@section Citation Elements ++ ++@dfn{Citation strings} are composed of one or more elements. Non-nested ++citations are composed of four elements, three of which are directly ++user definable. The elements are concatenated together, in this order: ++ ++@cindex citation leader ++@vindex citation-leader (sc-) ++@vindex sc-citation-leader ++@enumerate ++@item ++The @dfn{citation leader}. The citation leader is contained in the ++variable @code{sc-citation-leader}, and has the default value of a ++string containing four spaces. ++ ++@cindex attribution string ++@item ++The @dfn{attribution string}. This element is supplied automatically by ++Supercite, based on your preferences and the original message's mail ++headers, though you may be asked to confirm Supercite's choice. ++@xref{Selecting an Attribution}, for more details.@refill ++ ++@cindex citation delimiter ++@vindex sc-citation-delimiter ++@vindex citation-delimiter (sc-) ++@item ++The @dfn{citation delimiter}. This string, contained in the variable ++@code{sc-citation-delimiter} visually separates the citation from the ++text of the line. This variable has a default value of @code{">"} and ++for best results, the string should consist of only a single character. ++ ++@cindex citation separator ++@vindex citation-separator (sc-) ++@vindex sc-citation-separator ++@item ++The @dfn{citation separator}. The citation separator is contained in ++the variable @code{sc-citation-separator}, and has the default value of ++a string containing a single space. ++@end enumerate ++ ++For example, suppose you were using the default values for the above ++variables, and Supercite provided the attribution string @samp{Jane}. ++In this case, the composed, non-nested citation string used might be ++something like ++@code{@asis{" Jane> "}}. ++This citation string will be inserted in front of ++every line in the original message that is not already cited.@refill ++ ++Nested citations, being simpler than non-nested citations, are composed ++of the same elements, sans the attribution string. Supercite is smart ++enough to not put additional spaces between citation delimiters for ++multi-level nested citations. ++ ++@node Recognizing Citations, Getting Connected, Citation Elements, Citations ++@section Recognizing Citations ++ ++Supercite also recognizes citations in the original article, and can ++transform these already cited lines in a number of ways. This is how ++Supercite suppresses the multiple citing of non-nested citations. ++Recognition of cited lines is controlled by variables analogous to those ++that make up the citation string as mentioned previously. ++ ++@vindex sc-citation-leader-regexp ++@vindex citation-leader-regexp (sc-) ++@vindex sc-citation-delimiter-regexp ++@vindex citation-delimiter-regexp (sc-) ++@vindex sc-citation-separator-regexp ++@vindex citation-separator-regexp (sc-) ++@vindex sc-citation-root-regexp ++@vindex citation-root-regexp (sc-) ++@vindex sc-citation-nonnested-root-regexp ++@vindex citation-nonnested-root-regexp (sc-) ++ ++The variable @code{sc-citation-leader-regexp} describes how citation ++leaders can look, by default it matches any number of spaces or tabs. ++Note that since the lisp function @code{looking-at} is used to do the ++matching, if you change this variable it need not start with a leading ++@code{"^"}. ++ ++Similarly, the variables @code{sc-citation-delimiter-regexp} and ++@code{sc-citation-separator-regexp} respectively describe how citation ++delimiters and separators can look. They follow the same rule as ++@code{sc-citation-leader-regexp} above. ++ ++When Supercite composes a citation string, it provides the attribution ++automatically. The analogous variable which handles recognition of the ++attribution part of citation strings is @code{sc-citation-root-regexp}. ++This variable describes the attribution root for both nested and ++non-nested citations. By default it can match zero-to-many alphanumeric ++characters (also ``.'', ``-'', and ``_''). But in some situations, ++Supercite has to determine whether it is looking at a nested or ++non-nested citation. Thus the variable ++@code{sc-citation-nonnested-root-regexp} is used to describe only ++non-nested citation roots. It is important to remember that if you ++change @code{sc-citation-root-regexp} you should always also change ++@code{sc-citation-nonnested-root-regexp}.@refill ++ ++@node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top ++@cindex information keys ++@cindex Info Alist ++@cindex information extracted from mail fields ++@findex sc-mail-field ++@findex mail-field (sc-) ++@chapter Information Keys and the Info Alist ++ ++@dfn{Mail header information keys} are nuggets of information that ++Supercite extracts from the various mail headers of the original ++message, placed in the reply buffer by the MUA. Information is kept in ++the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in ++various places within Supercite, such as in header rewrite functions and ++attribution selection. Other bits of data, composed and created by ++Supercite, are also kept as key-value pairs in this alist. In the case ++of mail fields, the key is the name of the field, omitting the trailing ++colon. Info keys are always case insensitive (as are mail headers), and ++the value for a corresponding key can be retrieved from the alist with ++the @code{sc-mail-field} function. Thus, if the following fields were ++present in the original article:@refill ++ ++@example ++Date:@: 08 April 1991, 17:32:09 EST ++Subject:@: Better get out your asbestos suit ++@end example ++ ++@vindex sc-mumble ++@vindex mumble (sc-) ++@noindent ++then, the following lisp constructs return: ++ ++@example ++(sc-mail-field "date") ++==> "08 April 1991, 17:32:09 EST" ++ ++(sc-mail-field "subject") ++==> "Better get out your asbestos suit" ++@end example ++ ++Since the argument to @code{sc-mail-field} can be any string, it is ++possible that the mail field will not be present on the info alist ++(possibly because the mail header was not present in the original ++message). In this case, @code{sc-mail-field} will return the value of ++the variable @code{sc-mumble}. ++ ++Supercite always places all mail fields found in the yanked original ++article into the info alist. If possible, Supercite will also places ++the following keys into the info alist: ++ ++@table @code ++@cindex sc-attribution info field ++@cindex attribution info field (sc-) ++@item "sc-attribution" ++the selected attribution string. ++ ++@cindex sc-citation info field ++@cindex citation info field (sc-) ++@item "sc-citation" ++the non-nested citation string. ++ ++@cindex sc-from-address info field ++@cindex from-address info field (sc-) ++@item "sc-from-address" ++email address extracted from the @samp{From:@:} field. ++ ++@cindex sc-reply-address info field ++@cindex reply-address info field (sc-) ++@item "sc-reply-address" ++email address extracted from the @samp{Reply-To:@:} field. ++ ++@cindex sc-sender-address info field ++@cindex sender-address info field (sc-) ++@item "sc-sender-address" ++email address extracted from the @samp{Sender:@:} field. ++ ++@cindex sc-emailname info field ++@cindex emailname info field (sc-) ++@item "sc-emailname" ++email terminus extracted from the @samp{From:@:} field. ++ ++@cindex sc-initials info field ++@cindex initials info field (sc-) ++@item "sc-initials" ++the author's initials. ++ ++@cindex sc-author info field ++@cindex author info field (sc-) ++@item "sc-author" ++the author's full name. ++ ++@cindex sc-firstname info field ++@cindex firstname info field (sc-) ++@item "sc-firstname" ++the author's first name. ++ ++@cindex sc-lastname info field ++@cindex lastname info field (sc-) ++@item "sc-lastname" ++the author's last name. ++ ++@cindex sc-middlename-1 info field ++@cindex middlename-1 info field (sc-) ++@item "sc-middlename-1" ++the author's first middle name. ++@end table ++ ++If the author's name has more than one middle name, they will appear as ++info keys with the appropriate index (e.g., @code{"sc-middlename-2"}, ++@dots{}). @xref{Selecting an Attribution}.@refill ++ ++@node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top ++@cindex reference headers ++@chapter Reference Headers ++ ++Supercite will insert an informative @dfn{reference header} at the ++beginning of the cited body of text, which display more detail about the ++original article and provides the mapping between the attribution and ++the original author in non-nested citations. Whereas the citation ++string usually only contains a portion of the original author's name, ++the reference header can contain such information as the author's full ++name, email address, the original article's subject, etc. In fact any ++information contained in the info alist can be inserted into a reference ++header. ++ ++@ifinfo ++@menu ++* The Built-in Header Rewrite Functions:: ++* Electric References:: ++@end menu ++@end ifinfo ++ ++@cindex header rewrite functions ++@vindex sc-rewrite-header-list ++@vindex rewrite-header-list (sc-) ++There are a number of built-in @dfn{header rewrite functions} supplied ++by Supercite, but you can write your own custom header rewrite functions ++(perhaps using the built-in ones as examples). The variable ++@code{sc-rewrite-header-list} contains the list of such header rewrite ++functions. This list is consulted both when inserting the initial ++reference header, and when displaying @dfn{electric references}. ++@xref{Electric References}. ++ ++@vindex sc-preferred-header-style ++@vindex preferred-header-style (sc-) ++When Supercite is initially run on a reply buffer (via ++@code{sc-cite-original}), it will automatically call one of these ++functions. The one it uses is defined in the variable ++@code{sc-preferred-header-style}. The value of this variable is an ++integer which is an index into the @code{sc-rewrite-header-list}, ++beginning at zero. ++ ++@node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers ++@cindex header rewrite functions, built-in ++@section The Built-in Header Rewrite Functions ++ ++Below are examples of the various built-in header rewrite functions. ++Please note the following:@: first, the text which appears in the ++examples below as @var{infokey} indicates that the corresponding value ++of the info key from the info alist will be inserted there. ++(@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said} ++below, @var{date} and @var{from} correspond to the values of the ++@samp{Date:@:} and @samp{From:@:} mail headers respectively.@refill ++ ++@vindex sc-reference-tag-string ++@vindex reference-tag-string (sc-) ++Also, the string @code{">>>>>"} below is really the value of the ++variable @code{sc-reference-tag-string}. This variable is used in all ++built-in header rewrite functions, and you can customize its value to ++change the tag string globally. ++ ++Finally, the references headers actually written may omit certain parts ++of the header if the info key associated with @var{infokey} is not ++present in the info alist. In fact, for all built-in headers, if the ++@samp{From:@:} field is not present in the mail headers, the entire ++reference header will be omitted (but this usually signals a serious ++problem either in your MUA or in Supercite's installation). ++ ++@table @code ++@findex sc-no-header ++@findex no-header (sc-) ++@item sc-no-header ++This function produces no header. It should be used instead of ++@code{nil} to produce a blank header. This header can possibly contain ++a blank line after the @code{mail-header-separator} line. ++ ++@item sc-no-blank-line-or-header ++@findex sc-no-blank-line-or-header ++@findex no-blank-line-or-header (sc-) ++This function is similar to @code{sc-no-header} except that any blank ++line after the @code{mail-header-separator} line will be removed. ++ ++@item sc-header-on-said ++@findex sc-header-on-said ++@findex header-on-said (sc-) ++@code{>>>>> On @var{date}, @var{from} said:} ++ ++@item sc-header-inarticle-writes ++@findex sc-header-inarticle-writes ++@findex header-inarticle-writes (sc-) ++@code{>>>>> In article @var{message-id}, @var{from} writes:} ++ ++@item sc-header-regarding-adds ++@findex sc-header-regarding-adds ++@findex header-regarding-adds (sc-) ++@code{>>>>> Regarding @var{subject}; @var{from} adds:} ++ ++@item sc-header-attributed-writes ++@findex sc-header-attributed-writes ++@findex header-attributed-writes (sc-) ++@code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:} ++ ++@item sc-header-author-writes ++@findex sc-header-author-writes ++@findex header-author-writes (sc-) ++@code{>>>>> @var{sc-author} writes:} ++ ++@item sc-header-verbose ++@findex sc-header-verbose ++@findex header-verbose (sc-) ++@code{>>>>> On @var{date},}@* ++@code{>>>>> @var{sc-author}}@* ++@code{>>>>> from the organization of @var{organization}}@* ++@code{>>>>> who can be reached at:@: @var{sc-reply-address}}@* ++@code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@* ++@code{>>>>> had this to say in article @var{message-id}}@* ++@code{>>>>> in newsgroups @var{newsgroups}}@* ++@code{>>>>> concerning the subject of @var{subject}}@* ++@code{>>>>> see @var{references} for more details} ++@end table ++ ++@node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers ++@cindex electric references ++@section Electric References ++ ++By default, when Supercite cites the original message for the first ++time, it just goes ahead and inserts the reference header indexed by ++@code{sc-preferred-header-style}. However, you may want to select ++different reference headers based on the type of reply or forwarding you ++are doing. You may also want to preview the reference header before ++deciding whether to insert it into the reply buffer or not. Supercite ++provides an optional @dfn{electric reference} mode which you can drop ++into to give you this functionality. ++ ++@vindex sc-electric-references-p ++@vindex electric-references-p (sc-) ++If the variable @code{sc-electric-references-p} is non-@code{nil}, ++Supercite will bring up an electric reference mode buffer and place you ++into a recursive edit. The electric reference buffer is read-only, so ++you cannot directly modify the reference text until you exit electric ++references and insert the text into the reply buffer. But you can cycle ++through all the reference header rewrite functions in your ++@code{sc-rewrite-header-list}. ++ ++You can also set a new preferred header style, jump to any header, or ++jump to the preferred header. The header will be shown in the electric ++reference buffer and the header index and function name will appear in ++the echo area. ++ ++The following commands are available while in electric reference mode ++(shown here with their default key bindings): ++ ++@table @asis ++@item @code{sc-eref-next} (@kbd{n}) ++@findex sc-eref-next ++@findex eref-next (sc-) ++@kindex n ++@vindex sc-electric-circular-p ++@vindex electric-circular-p (sc-) ++Displays the next reference header in the electric reference buffer. If ++the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking ++@code{sc-eref-next} while viewing the last reference header in the list ++will wrap around to the first header.@refill ++ ++@item @code{sc-eref-prev} (@kbd{p}) ++@findex sc-eref-prev ++@findex eref-prev (sc-) ++@kindex p ++Displays the previous reference header in the electric reference buffer. ++If the variable @code{sc-electric-circular-p} is non-@code{nil}, ++invoking @code{sc-eref-prev} will wrap around to the last header.@refill ++ ++@item @code{sc-eref-goto} (@kbd{g}) ++@findex sc-eref-goto ++@findex eref-goto (sc-) ++@kindex g ++Goes to a specified reference header. The index (into the ++@code{sc-rewrite-header-list}) can be specified as a numeric argument to ++the command. Otherwise, Supercite will query you for the index in the ++minibuffer.@refill ++ ++@item @code{sc-eref-jump} (@kbd{j}) ++@findex sc-eref-jump ++@findex eref-jump (sc-) ++@kindex j ++Display the preferred reference header, i.e., the one indexed by the current ++value of @code{sc-preferred-header-style}. ++ ++@item @code{sc-eref-setn} (@kbd{s}) ++@findex sc-eref-setn ++@findex eref-setn (sc-) ++@kindex s ++Set the preferred reference header (i.e., ++@code{sc-preferred-header-style}) to the currently displayed header.@refill ++ ++@item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c}) ++@kindex RET ++@kindex C-j ++@kindex q ++@findex sc-eref-exit ++@findex eref-exit (sc-) ++Exit from electric reference mode and insert the current header into the ++reply buffer.@refill ++ ++@item @code{sc-eref-abort} (@kbd{q}, @kbd{x}) ++@findex sc-eref-abort ++@findex eref-abort (sc-) ++@kindex x ++Exit from electric reference mode without inserting the current header. ++@end table ++ ++@vindex sc-electric-mode-hook ++@vindex electric-mode-hook (sc-) ++@noindent ++Supercite will execute the hook @code{sc-electric-mode-hook} before ++entering electric reference mode. ++ ++@node Getting Connected, Replying and Yanking, Recognizing Citations, Top ++@cindex citation interface specification ++@chapter Getting Connected ++ ++ ++@vindex mail-citation-hook ++@cindex .emacs file ++In most cases, all that is necessary to begin using Supercite is to add ++the following to @file{~.emacs}: ++ ++@example ++(add-hook 'mail-citation-hook 'sc-cite-original) ++@end example ++ ++@noindent For more details of the process, read on@dots{} ++ ++Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the ++original message into the reply buffer. In reality, the citation of the ++original message is performed via a call through a configurable hook ++variable. The name of this variable has been agreed to in advance as ++part of the @dfn{citation interface specification}. By default this ++hook variable has a @code{nil} value, which the MUA recognizes to mean, ++``use your default citation function.'' When you add Supercite's ++citation function to the hook, thereby giving the variable a ++non-@code{nil} value, it tells the MUA to run the hook via ++@code{run-hooks} instead of using the default citation.@refill ++ ++Early in Supercite's development, the Supercite author, a few MUA ++authors, and some early Supercite users got together and agreed upon a ++standard interface between MUAs and citation packages (of which ++Supercite is currently the only known add-on @t{:-)}. Supercite can ++probably be used with most Emacs MUAs, with a greater or lesser degree ++of effort. ++ ++To learn exactly how to connect Supercite to the software systems you ++are using, read the appropriate following sections. For details on the ++interface specifications, or if you are writing or maintaining an MUA, ++@pxref{Hints to MUA Authors}. ++ ++@cindex autoload ++@cindex .emacs file ++@findex sc-cite-original ++@findex cite-original (sc-) ++@findex sc-submit-bug-report ++@findex submit-bug-report (sc-) ++The first thing that everyone should do, regardless of the MUA you are ++using is to set up Emacs so it will load Supercite at the appropriate ++time. This happens automatically if Supercite is distributed with your ++Emacs version. If not, you can set up an @dfn{autoload} for Supercite. ++ ++To do the latter, put the following in your @file{.emacs} file: ++ ++@example ++(autoload 'sc-cite-original "supercite" nil t) ++@end example ++ ++@cindex point ++@cindex mark ++The function @code{sc-cite-original} is the top-level Supercite function ++designed to be run from the citation hook. It expects ++@samp{point} and @samp{mark} to be set around the region to cite, and it ++expects the original article's mail headers to be present within this ++region. Note that Supercite @emph{never} touches any text outside this ++region. Note further that the region need not be active ++for @code{sc-cite-original} to do its job. ++@xref{Hints to MUA Authors}.@refill ++ ++The other step in the getting connected process is to make sure your ++MUA calls @code{sc-cite-original} at the right time. As mentioned ++above, some MUAs handle this differently. Read the sections that follow ++pertaining to the MUAs you are using. ++ ++@vindex sc-load-hook ++@vindex load-hook (sc-) ++@vindex sc-pre-hook ++@vindex pre-hook (sc-) ++One final note. After Supercite is loaded into your Emacs session, it ++runs the hook @code{sc-load-hook}. You can put any customizations into ++this hook since it is only run once. This will not work, however, if ++your Emacs maintainer has put Supercite into your dumped Emacs' image. ++In that case, you can use the @code{sc-pre-hook} variable, but this will ++get executed every time @code{sc-cite-original} is called. @xref{Reply ++Buffer Initialization}.@refill ++ ++@node Replying and Yanking, Reply Buffer Initialization, Getting Connected, Top ++@chapter Replying and Yanking ++@ifinfo ++ ++This chapter explains what happens when you reply and yank an original ++message from an MUA. ++ ++@menu ++* Reply Buffer Initialization:: ++* Filling Cited Text:: ++@end menu ++@end ifinfo ++@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking ++@findex sc-cite-original ++@findex cite-original (sc-) ++@section Reply Buffer Initialization ++ ++Executing @code{sc-cite-original} performs the following steps as it ++initializes the reply buffer: ++ ++@enumerate ++@item ++@vindex sc-pre-hook ++@vindex pre-hook (sc-) ++@emph{Runs @code{sc-pre-hook}.} ++This hook variable is run before @code{sc-cite-original} does any other ++work. You could conceivably use this hook to set certain Supercite ++variables based on the reply buffer's mode or name (i.e., to do ++something different based on whether you are replying or following up to ++an article).@refill ++ ++@item ++@emph{Inserts Supercite's keymap.} ++@vindex sc-mode-map-prefix ++@vindex mode-map-prefix (sc-) ++@kindex C-c C-p ++@cindex keymap prefix ++Supercite provides a number of commands for performing post-yank ++modifications to the reply buffer. These commands are installed on ++Supercite's top-level keymap. Since Supercite has to interface with a ++wide variety of MUAs, it does not install all of its commands directly ++into the reply buffer's keymap. Instead, it puts its commands on a ++keymap prefix, then installs this prefix onto the buffer's keymap. What ++this means is that you typically have to type more characters to invoke ++a Supercite command, but Supercite's key bindings can be made much more ++consistent across MUAs. ++ ++You can control what key Supercite uses as its keymap prefix by changing ++the variable @code{sc-mode-map-prefix}. By default, this variable is ++set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the ++best default due to the scarcity of available key bindings in many MUAs. ++ ++@item ++@emph{Turns on Supercite minor mode.} ++@cindex modeline ++The modeline of the reply buffer should indicate that Supercite is ++active in that buffer by displaying the string @samp{SC}. ++ ++@item ++@emph{Sets the ``Undo Boundary.''} ++@cindex undo boundary ++Supercite sets an undo boundary before it begins to modify the original ++yanked text. This allows you to easily undo Supercite's changes to ++affect alternative citing styles. ++ ++@item ++@emph{Processes the mail headers.} ++@vindex sc-confirm-always-p ++@vindex confirm-always-p (sc-) ++@vindex sc-mail-warn-if-non-rfc822-p ++@vindex mail-warn-if-non-rfc822-p (sc-) ++All previously retrieved info key-value pairs are deleted from the info ++alist, then the mail headers in the body of the yanked message are ++scanned. Info key-value pairs are created for each header found. Also, ++such useful information as the author's name and email address are ++extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is ++non-@code{nil}, then Supercite will warn you if it finds a mail header ++that does not conform to RFC822. This is rare and indicates a problem ++either with your MUA or the original author's MUA, or some MTA (mail ++transport agent) along the way. ++ ++@vindex sc-nuke-mail-headers ++@vindex sc-nuke-mail-header-list ++@vindex nuke-mail-headers (sc-) ++@vindex nuke-mail-header-list (sc-) ++Once the info keys have been extracted from the mail headers, the ++headers are nuked from the reply buffer. You can control exactly which ++headers are removed or kept, but by default, all headers are removed. ++ ++There are two variables which control mail header nuking. The variable ++@code{sc-nuke-mail-headers} controls the overall behavior of the header ++nuking routines. By setting this variable to @code{'all}, you ++automatically nuke all mail headers. Likewise, setting this variable to ++@code{'none} inhibits nuking of any mail headers. In between these ++extremes, you can tell Supercite to nuke only a specified list of mail ++headers by setting this variable to @code{'specified}, or to keep only a ++specified list of headers by setting it to @code{'keep}. ++ ++If @code{sc-nuke-mail-headers} is set to @code{'specified} or ++@code{'keep}, then the variable @code{sc-nuke-mail-header-list} is ++consulted for the list of headers to nuke or keep. This variable ++contains a list of regular expressions. If the mail header line matches ++a regular expression in this list, the header will be nuked or kept. ++The line is matched against the regexp using @code{looking-at} rooted at ++the beginning of the line. ++ ++@vindex sc-blank-lines-after-headers ++@vindex blank-lines-after-headers (sc-) ++If the variable @code{sc-blank-lines-after-headers} is non-@code{nil}, ++it contains the number of blank lines remaining in the buffer after mail ++headers are nuked. By default, only one blank line is left in the buffer. ++ ++@item ++@emph{Selects the attribution and citation strings.} ++Once the mail headers have been processed, Supercite selects a ++attribution string and a citation string which it will use to cite the ++original message. @xref{Selecting an Attribution}, for details. ++ ++@item ++@emph{Cites the message body.} ++@vindex sc-cite-region-limit ++@vindex cite-region-limit (sc-)b ++After the selection of the attribution and citation strings, Supercite ++cites the original message by inserting the citation string prefix in ++front of every uncited line. You may not want Supercite to ++automatically cite very long messages however. For example, some email ++could contain a smaller header section followed by a huge uuencoded ++message. It wouldn't make sense to cite the uuencoded message part when ++responding to the original author's short preface. For this reason, ++Supercite provides a variable which limits the automatic citation of ++long messages to a certain maximum number of lines. The variable is ++called @code{sc-cite-region-limit}. If this variable contains an ++integer, messages with more lines that this will not be cited at all, ++and a warning message will be displayed. Supercite has performed ++everything necessary, though, for you to manually cite only the small ++portion of the original message that you want to use. ++ ++If @code{sc-cite-region-limit} contains a non-@code{nil} value, the ++original message will always be cited, regardless of its size. If the ++variable contains the value @code{nil}, the region will never be cited ++automatically. Use this if you always want to be able to edit and cite ++the message manually. ++ ++@vindex sc-cite-blank-lines-p ++@vindex cite-blank-lines-p (sc-) ++The variable @code{sc-cite-blank-lines-p} controls whether blank lines ++in the original message should be cited or not. If this variable is ++non-@code{nil}, blank lines will be cited just like non-blank lines. ++Otherwise, blank lines will be treated as paragraph separators. ++ ++Citing of the original message is highly configurable. Supercite's ++default setup does a pretty good job of citing many common forms of ++previously cited messages. But there are as many citation styles out ++there as people on the net, or just about! It would be impossible for ++Supercite to anticipate every style in existence, and you probably ++wouldn't encounter them all anyway. But you can configure Supercite to ++recognize those styles you see often. ++@xref{Configuring the Citation Engine}, for details.@refill ++ ++@item ++@emph{Runs @code{sc-post-hook}.} ++@vindex sc-post-hook ++@vindex post-hook (sc-) ++This variable is very similar to @code{sc-pre-hook}, except that it runs ++after @code{sc-cite-original} is finished. This hook is provided mostly ++for completeness and backward compatibility. Perhaps it could be used to ++reset certain variables set in @code{sc-pre-hook}.@refill ++@end enumerate ++ ++@node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking ++@cindex filling paragraphs ++@vindex sc-auto-fill-region-p ++@vindex auto-fill-region-p (sc-) ++@cindex filladapt ++@cindex gin-mode ++@findex sc-setup-filladapt ++@findex setup-filladapt (sc-) ++@vindex sc-load-hook ++@vindex load-hook (sc-) ++@section Filling Cited Text ++ ++Supercite will automatically fill newly cited text from the original ++message unless the variable @code{sc-auto-fill-region-p} has a ++@code{nil} value. Supercite will also re-fill paragraphs when you ++manually cite or re-cite text. ++ ++However, during normal editing, Supercite itself cannot be used to fill ++paragraphs. This is a change from version 2. There are other add-on ++lisp packages which do filling much better than Supercite ever did. The ++two best known are @dfn{filladapt} and @dfn{gin-mode}. Both work well ++with Supercite and both are available at the normal Emacs Lisp archive ++sites. @dfn{gin-mode} works pretty well out of the box, but if you use ++@dfn{filladapt}, you may want to run the function ++@code{sc-setup-filladapt} from your @code{sc-load-hook}. This simply ++makes @dfn{filladapt} a little more Supercite savvy than its default ++setup. ++ ++@vindex sc-fixup-whitespace-p ++@vindex fixup-whitespace-p (sc-) ++Also, Supercite will collapse leading whitespace between the citation ++string and the text on a line when the variable ++@code{sc-fixup-whitespace-p} is non-@code{nil}. The default value for ++this variable is @code{nil}.@refill ++ ++@vindex fill-prefix ++Its important to understand that Supercite's automatic filling (during ++the initial citation of the reply) is very fragile. That is because ++figuring out the @code{fill-prefix} for a particular paragraph is a ++really hard thing to do automatically. This is especially the case when ++the original message contains code or some other text where leading ++whitespace is important to preserve. For this reason, many Supercite ++users typically run with @code{sc-auto-fill-region-p} (and possibly also ++@code{sc-fixup-whitespace-p}) set to @code{nil}. They then manually ++fill each cited paragraph in the reply buffer. ++ ++I usually run with both these variables containing their default values. ++When Supercite's automatic filling breaks on a particular message, I ++will use Emacs' undo feature to undo back before the citation was ++applied to the original message. Then I'll toggle the variables and ++manually cite those paragraphs that I don't want to fill or collapse ++whitespace on. @xref{Variable Toggling Shortcuts}.@refill ++ ++@kindex C-c C-p C-p ++If you find that Supercite's automatic filling is just too fragile for ++your tastes, you might consider one of these alternate approaches. ++Also, to make life easier, a shortcut function to toggle the state of ++both of these variables is provided on the key binding ++@kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix}; ++@pxref{Post-yank Formatting Commands}).@refill ++ ++You will noticed that the minor mode string will ++show the state of these variables as qualifier characters. When both ++variables are @code{nil}, the Supercite minor mode string will display ++@samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the ++string will display @samp{SC:f}, and when just ++@code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display ++@samp{SC:w}. When both variables are non-@code{nil}, the string will ++display @samp{SC:fw}. Note that the qualifiers chosen are mnemonics for ++the default bindings of the toggling function for each respective ++variable. ++@xref{Variable Toggling Shortcuts}.@refill ++ ++Why are these variables not set to @code{nil} by default? It is because ++many users won't manually fill paragraphs that are Supercited, and there ++have been widespread complaints on the net about mail and news messages ++containing lines greater than about 72 characters. So the default is to ++fill cited text. ++ ++@node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top ++@cindex attribution list ++@vindex sc-preferred-attribution-list ++@vindex preferred-attribution-list (sc-) ++@chapter Selecting an Attribution ++ ++As you know, the attribution string is the part of the author's name ++that will be used to composed a non-nested citation string. Supercite ++scans the various mail headers present in the original article and uses ++a number of heuristics to extract strings which it puts into the ++@dfn{attribution association list} or @dfn{attribution alist}. This is ++analogous, but different than, the info alist previously mentioned. Each ++element in the attribution alist is a key-value pair containing such ++information as the author's first name, middle names, and last name, the ++author's initials, and the author's email terminus. ++ ++@ifinfo ++@menu ++* Attribution Preferences:: ++* Anonymous Attributions:: ++* Author Names:: ++@end menu ++@end ifinfo ++ ++@node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution ++@section Attribution Preferences ++ ++When you cite an original message, you can tell Supercite which part of ++the author's name you would prefer it to use as the attribution. The ++variable @code{sc-preferred-attribution-list} controls this; it contains ++keys which are matched against the attribution alist in the given order. ++The first value of a key that produces a non-@code{nil}, non-empty ++string match is used as the attribution string, and if no keys match, a ++secondary mechanism is used to generate the attribution. ++@xref{Anonymous Attributions}. ++ ++The following preferences are always available in the attribution alist ++(barring error): ++ ++@table @code ++@item "emailname" ++the author's email terminus. ++ ++@item "initials" ++the author's initials. ++ ++@item "firstname" ++the author's first name. ++ ++@item "lastname" ++the author's last name. ++ ++@item "middlename-1" ++the author's first middle name. ++ ++@item "sc-lastchoice" ++the last attribution string you have selected. This is useful when you ++recite paragraphs in the reply.@refill ++ ++@item "sc-consult" ++@vindex sc-attrib-selection-list ++@vindex attrib-selection-list (sc-) ++consults the customizable list @code{sc-attrib-selection-list} which can ++be used to select special attributions based on the value of any info ++key. See below for details. ++ ++@item "x-attribution" ++the original author's suggestion for attribution string choice. See below ++for details.@refill ++@end table ++ ++Middle name indexes can be any positive integer greater than zero, ++though it is unlikely that many authors will have more than one middle ++name, if that many. ++ ++At this point, let me digress into a discussion of etiquette. It is my ++belief that while the style of the citations is a reflection of the ++personal tastes of the replier (i.e., you), the attribution selection is ++ultimately the personal choice of the original author. In a sense it is ++his or her ``net nickname'', and therefore the author should have some ++say in the selection of attribution string. Imagine how you would feel ++if someone gave you a nickname that you didn't like? ++ ++For this reason, Supercite recognizes a special mail header, ++@samp{X-Attribution:}, which if present, tells Supercite the attribution ++string preferred by the original author. It is the value of this header ++that is associated with the @code{"x-attribution"} key in the ++attribution alist. Currently, you can override the preference of this ++key by changing @code{sc-preferred-attribution-list}, but that isn't ++polite, and in the future Supercite may hard-code this. For now, it is ++suggested that if you change the order of the keys in this list, that ++@code{"x-attribution"} always be first, or possible second behind only ++@code{"sc-lastchoice"}. This latter is the default. ++ ++@vindex sc-attrib-selection-list ++@vindex attrib-selection-list (sc-) ++The value @code{"sc-consult"} in @code{sc-preferred-attribution-list} ++has a special meaning during attribution selection. When Supercite ++encounters this preference, it begins processing a customizable list of ++attributions, contained in the variable @code{sc-attrib-selection-list}. ++Each element in this list contains lists of the following form: ++ ++@example ++@group ++(@var{infokey} ((@var{regexp} @. @var{attribution}) ++ (@var{regexp} @. @var{attribution}) ++ (@dots{}))) ++@end group ++@end example ++ ++@noindent ++@findex sc-mail-field ++@findex mail-field (sc-) ++where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp} ++is a regular expression to match against the @var{infokey}'s value. If ++@var{regexp} matches the @var{infokey}'s value, the @var{attribution} is ++used as the attribution string. Actually, @var{attribution} can be a ++string or a list; if it is a list, it is @code{eval}uated and the return ++value (which must be a string), is used as the attribution. ++ ++This can be very useful for when you are replying to net acquaintances ++who do not use the @samp{X-Attribution:@:} mail header. You may know ++what nickname they would prefer to use, and you can set up this list to ++match against a specific mail field, e.g., @samp{From:@:}, allowing you ++to cite your friend's message with the appropriate attribution. ++ ++@node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution ++@vindex sc-default-author-name ++@vindex default-author-name (sc-) ++@vindex sc-default-attribution ++@vindex default-attribution (sc-) ++@section Anonymous Attributions ++ ++When the author's name cannot be found in the @samp{From:@:} mail ++header, a fallback author name and attribution string must be supplied. ++The fallback author name is contained in the variable ++@code{sc-default-author-name} and the fallback attribution string is ++contained in the variable @code{sc-default-attribution}. Default values ++for these variables are @code{"Anonymous"} and @code{"Anon"}, ++respectively. Note that in most circumstances, getting the default ++author name or attribution is a sign that something is set up ++incorrectly. ++ ++@vindex sc-use-only-preference-p ++@vindex use-only-preference-p (sc-) ++Also, if the preferred attribution, which you specified in your ++@code{sc-preferred-attribution-list} variable cannot be found, a ++secondary method can be employed to find a valid attribution string. The ++variable @code{sc-use-only-preference-p} controls what happens in this ++case. If the variable's value is non-@code{nil}, then ++@code{sc-default-author-name} and @code{sc-default-attribution} are ++used, otherwise, the following steps are taken to find a valid ++attribution string, and the first step to return a non-@code{nil}, ++non-empty string becomes the attribution:@refill ++ ++@enumerate ++@item ++Use the last selected attribution, if there is one. ++ ++@item ++Use the value of the @code{"x-attribution"} key. ++ ++@item ++Use the author's first name. ++ ++@item ++Use the author's last name. ++ ++@item ++Use the author's initials. ++ ++@item ++Find the first non-@code{nil}, non-empty attribution string in the ++attribution alist. ++ ++@item ++@code{sc-default-attribution} is used. ++@end enumerate ++ ++@vindex sc-confirm-always-p ++@vindex confirm-always-p (sc-) ++Once the attribution string has been automatically selected, a number of ++things can happen. If the variable @code{sc-confirm-always-p} is ++non-@code{nil}, you are queried for confirmation of the chosen ++attribution string. The possible values for completion are those strings ++in the attribution alist, however you are not limited to these choices. ++You can type any arbitrary string at the confirmation prompt. The string ++you enter becomes the value associated with the @code{"sc-lastchoice"} ++key in the attribution alist. ++ ++@vindex sc-downcase-p ++@vindex downcase-p (sc-) ++Once an attribution string has been selected, Supercite will force the ++string to lower case if the variable @code{sc-downcase-p} is ++non-@code{nil}. ++ ++@vindex sc-attribs-preselect-hook ++@vindex attribs-preselect-hook (sc-) ++@vindex sc-attribs-postselect-hook ++@vindex attribs-postselect-hook (sc-) ++ ++Two hook variables provide even greater control of the attribution ++selection process. The hook @code{sc-attribs-preselect-hook} is run ++before any attribution is selected. Likewise, the hook ++@code{sc-attribs-postselect-hook} is run after the attribution is ++selected (and the corresponding citation string is built), but before ++these values are committed for use by Supercite. During the ++post-selection hook, the local variables @code{attribution} and ++@code{citation} are bound to the appropriate strings. By changing these ++variables in your hook functions, you change the attribution and ++citation strings used by Supercite. One possible use of this would be ++to override any automatically derived attribution string when it is only ++one character long; e.g. you prefer to use @code{"initials"} but the ++author only has one name.@refill ++ ++@node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution ++@cindex author names ++@section Author Names ++ ++Supercite employs a number of heuristics to decipher the author's name ++based on value of the @samp{From:@:} mail field of the original message. ++Supercite can recognize almost all of the common @samp{From:@:} field ++formats in use. If you encounter a @samp{From:@:} field that Supercite ++cannot parse, please report this bug using @kbd{M-x report-emacs-bug}. ++ ++@vindex sc-titlecue-regexp ++@vindex titlecue-regexp (sc-) ++There are a number of Supercite variables that control how author names ++are extracted from the @samp{From:@:} header. Some headers may contain a ++descriptive title as in: ++ ++@example ++From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker) ++@end example ++ ++Supercite knows which part of the @samp{From:@:} header is email address ++and which part is author name, but in this case the string @code{"Decent ++Hacker"} is not part of the author's name. You can tell Supercite to ++ignore the title, while still recognizing hyphenated names through the ++use of a regular expression in the variable @code{sc-titlecue-regexp}. ++This variable has the default value of @code{"\\\\s +-+\\\\s +"}. Any ++text after this regexp is encountered is ignored as noise. ++ ++@vindex sc-name-filter-alist ++@vindex name-filter-alist (sc-) ++Some @samp{From:@:} headers may contain extra titles in the name fields ++not separated by a title cue, but which are nonetheless not part of the ++author's name proper. Examples include the titles ``Dr.'', ``Mr.'', ++``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third). ++Also, some companies prepend or append the name of the division, ++organization, or project on the author's name. All of these titles are ++noise which should be ignored. The variable @code{sc-name-filter-alist} ++is used for this purpose. As implied by its name, this variable is an ++association list, where each element is a cons cell of the form: ++ ++@example ++(@var{regexp} @. @var{position}) ++@end example ++ ++@noindent ++where @var{regexp} is a regular expression that is matched (using ++@code{string-match}) against each element of the @samp{From:@:} field's ++author name. @var{position} is a position indicator, starting at zero. ++Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name, ++@code{sc-name-filter-alist} would have an entry such as: ++ ++@example ++("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0) ++@end example ++ ++@noindent ++which only removes them if they appear as the first word in the name. ++The position indicator is an integer, or one of the two special symbols ++@code{last} or @code{any}. @code{last} always matches against the last ++word in the name field, while @code{any} matches against every word in ++the name field. ++ ++@node Configuring the Citation Engine, Using Regi, Author Names, Top ++@cindex Regi ++@cindex frames (Regi) ++@cindex entries (Regi) ++@chapter Configuring the Citation Engine ++ ++At the heart of Supercite is a regular expression interpreting engine ++called @dfn{Regi}. Regi operates by interpreting a data structure ++called a Regi-frame (or just @dfn{frame}), which is a list of ++Regi-entries (or just @dfn{entry}). Each entry contains a predicate, ++typically a regular expression, which is matched against a line of text ++in the current buffer. If the predicate matches true, an associated ++expression is @code{eval}uated. In this way, an entire region of text ++can be transformed in an @emph{awk}-like manner. Regi is used ++throughout Supercite, from mail header information extraction, to header ++nuking, to citing text. ++ ++@ifinfo ++@menu ++* Using Regi:: ++* Frames You Can Customize:: ++@end menu ++@end ifinfo ++ ++While the details of Regi are discussed below (@pxref{Using Regi}), only ++those who wish to customize certain aspects of Supercite need concern ++themselves with it. It is important to understand though, that any ++conceivable citation style that can be described by a regular expression ++can be recognized by Supercite. This leads to some interesting ++applications. For example, if you regularly receive email from a ++co-worker that uses an uncommon citation style (say one that employs a ++@samp{|} or @samp{@}} character at the front of the line), it is ++possible for Supercite to recognize this and @emph{coerce} the citation ++to your preferred style, for consistency. In theory, it is possible for ++Supercite to recognize such things as uuencoded messages or C code and ++cite or fill those differently than normal text. None of this is ++currently part of Supercite, but contributions are welcome! ++ ++@node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine ++@findex regi-interpret ++@findex eval ++@findex looking-at ++@section Using Regi ++ ++Regi works by interpreting frames with the function ++@code{regi-interpret}. A frame is a list of arbitrary size where each ++element is a entry of the following form: ++ ++@example ++(@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]]) ++@end example ++ ++Regi starts with the first entry in a frame, evaluating the @var{pred} ++of that entry against the beginning of the line that @samp{point} is on. ++If the @var{pred} evaluates to true (or false if the optional ++@var{negate-p} is non-@code{nil}), then the @var{func} for that entry is ++@code{eval}uated. How processing continues is determined by the return ++value for @var{func}, and is described below. If @var{pred} was false ++the next entry in the frame is checked until all entries have been ++matched against the current line. If no entry matches, @samp{point} is ++moved forward one line and the frame is reset to the first entry. ++ ++@var{pred} can be a string, a variable, a list or one of the following ++symbols: @code{t}, @code{begin}, @code{end}, or @code{every}. If ++@var{pred} is a string, or a variable or list that @code{eval}uates to a ++string, it is interpreted as a regular expression. This regexp is ++matched against the current line, from the beginning, using ++@code{looking-at}. This match folds case if the optional ++@var{case-fold-search} is non-@code{nil}. If @var{pred} is not a ++string, or does not @code{eval}uate to a string, it is interpreted as a ++binary value (@code{nil} or non-@code{nil}).@refill ++ ++The four special symbol values for @var{pred} are recognized: ++ ++@table @code ++@item t ++Always produces a true outcome. ++@item begin ++Always executed before the frame is interpreted. This can be used to ++initialize some global variables for example. ++@item end ++Always executed after frame interpreting is completed. This can be used ++to perform any necessary post-processing. ++@item every ++Executes whenever the frame is reset, usually after the entire frame has ++been matched against the current line. ++@end table ++ ++Note that @var{negate-p} and @var{case-fold-search} are ignored if ++@var{pred} is one of these special symbols. Only the first occurrence of ++each symbol in a frame is used; any duplicates are ignored. Also ++note that for performance reasons, the entries associated with these ++symbols are removed from the frame during the main interpreting loop. ++ ++Your @var{func} can return certain values which control continued Regi ++processing. By default, if your @var{func} returns @code{nil} (as it ++should be careful to do explicitly), Regi will reset the frame to the ++first entry, and advance @samp{point} to the beginning of the next line. ++If a list is returned from your function, it can contain any combination ++of the following elements:@refill ++ ++@table @asis ++@item the symbol @code{continue} ++This tells Regi to continue processing entries after a match, instead of ++resetting the frame and moving @samp{point}. In this way, lines of text ++can have multiple matches, but you have to be careful to avoid entering ++infinite loops. ++ ++@item the symbol @code{abort} ++This tells Regi to terminate frame processing. However, any @code{end} ++entry is still processed. ++ ++@item the list @code{(frame . @var{newframe})} ++This tells Regi to substitute @var{newframe} as the frame it is ++interpreting. In other words, your @var{func} can modify the Regi frame ++on the fly. @var{newframe} can be a variable containing a frame, or it ++can be the frame in-lined.@refill ++ ++@item the list @code{(step . @var{step})} ++Tells Regi to move @var{step} number of lines forward as it continues ++processing. By default, Regi moves forward one line. @var{step} can be ++zero or negative of course, but watch out for infinite loops.@refill ++@end table ++ ++During execution of your @var{func}, the following variables will be ++temporarily bound to some useful information:@refill ++ ++@table @code ++@item curline ++The current line in the buffer that Regi is @code{looking-at}, as a string. ++@item curframe ++The current frame being interpreted. ++@item curentry ++The current frame entry being interpreted. ++@end table ++ ++@node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine ++@vindex sc-nuke-mail-header ++@section Frames You Can Customize ++ ++As mentioned earlier, Supercite uses various frames to perform ++certain jobs such as mail header information extraction and mail header ++nuking. However, these frames are not available for you to customize, ++except through abstract interfaces such as @code{sc-nuke-mail-header}, ++et al. ++ ++@vindex sc-default-cite-frame ++However, the citation frames Supercite uses provide a lot of customizing ++power and are thus available to you to change to suit your needs. The ++workhorse of citation is the frame contained in the variable ++@code{sc-default-cite-frame}. This frame recognizes many situations, ++such as blank lines, which it interprets as paragraph separators. It ++also recognizes previously cited nested and non-nested citations in the ++original message. By default it will coerce non-nested citations into ++your preferred citation style, and it will add a level of citation to ++nested citations. It will also simply cite uncited lines in your ++preferred style. ++ ++@cindex unciting ++@cindex reciting ++@vindex sc-default-uncite-frame ++@vindex sc-default-recite-frame ++In a similar vein, there are default frames for @dfn{unciting} and ++@dfn{reciting}, contained in the variables ++@code{sc-default-uncite-frame} and @code{sc-default-recite-frame} ++respectively.@refill ++ ++As mentioned earlier (@pxref{Recognizing Citations}), citations are ++recognized through the values of the regular expressions ++@code{sc-citation-root-regexp}, et al. To recognize odd styles, you ++could modify these variables, or you could modify the default citing ++frame. Alternatively, you could set up association lists of frames for ++recognizing specific alternative forms. ++ ++@vindex sc-cite-frame-alist ++@vindex sc-uncite-frame-alist ++@vindex sc-recite-frame-alist ++For each of the actions -- citing, unciting, and reciting -- an alist is ++consulted to find the frame to use (@code{sc-cite-frame-alist}, ++@code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist} ++respectively). These frames can contain alists of the form: ++ ++@example ++((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) ++ (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) ++ (@dots{})) ++@end example ++ ++@vindex sc-mail-field ++@findex string-match ++Where @var{infokey} is a key suitable for @code{sc-mail-field}, ++@var{regexp} is a regular expression which is @code{string-match}'d ++against the value of the @code{sc-mail-field} key, and @var{frame} is ++the frame to use if a match occurred. @var{frame} can be a variable ++containing a frame or a frame in-lined.@refill ++ ++When Supercite is about to cite, uncite, or recite a region, it consults ++the appropriate alist and attempts to find a frame to use. If one ++is not found from the alist, then the appropriate default frame is used. ++ ++@node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top ++@vindex sc-mode-map-prefix ++@vindex mode-map-prefix (sc-) ++@kindex C-c C-p ++@chapter Post-yank Formatting Commands ++ ++Once the original message has been yanked into the reply buffer, and ++@code{sc-cite-original} has had a chance to do its thing, a number of ++useful Supercite commands will be available to you. Since there is wide ++variety in the keymaps that MUAs set up in their reply buffers, it is ++next to impossible for Supercite to properly sprinkle its commands into ++the existing keymap. For this reason Supercite places its commands on a ++separate keymap, putting this keymap onto a prefix key in the reply ++buffer. You can customize the prefix key Supercite uses by changing the ++variable @code{sc-mode-map-prefix}. By default, the ++@code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice, ++but unfortunately the best general solution so far. In the rest of this ++chapter, we'll assume you've installed Supercite's keymap on the default ++prefix.@refill ++ ++@ifinfo ++@menu ++* Citing Commands:: ++* Insertion Commands:: ++* Variable Toggling Shortcuts:: ++* Mail Field Commands:: ++* Miscellaneous Commands:: ++@end menu ++@end ifinfo ++ ++@node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands ++@vindex sc-cite-region-limit ++@section Commands to Manually Cite, Recite, and Uncite ++ ++Probably the three most common post-yank formatting operations that you ++will perform will be the manual citing, reciting, and unciting of ++regions of text in the reply buffer. Often you may want to recite a ++paragraph to use a nickname, or manually cite a message when setting ++@code{sc-cite-region-limit} to @code{nil}. The following commands ++perform these functions on the region of text between @samp{point} and ++@samp{mark}. Each of them sets the @dfn{undo boundary} before modifying ++the region so that the command can be undone in the standard Emacs ++way.@refill ++ ++Here is the list of Supercite citing commands: ++ ++@table @asis ++@findex sc-cite-region ++@findex cite-region (sc-) ++@kindex C-c C-p c ++@vindex sc-pre-cite-hook ++@vindex pre-cite-hook (sc-) ++@vindex sc-confirm-always-p ++@vindex confirm-always-p ++@kindex C-u ++@item @code{sc-cite-region} (@kbd{C-c C-p c}) ++This command cites each line in the region of text by interpreting the ++selected frame from @code{sc-cite-frame-alist}, or the default citing ++frame @code{sc-default-cite-frame}. It runs the hook ++@code{sc-pre-cite-hook} before interpreting the frame. With an optional ++universal argument (@kbd{C-u}), it temporarily sets ++@code{sc-confirm-always-p} to @code{t} so you can confirm the ++attribution string for a single manual citing. ++@xref{Configuring the Citation Engine}.@refill ++ ++@findex sc-uncite-region ++@findex uncite-region (sc-) ++@kindex C-c C-p u ++@item @code{sc-uncite-region} (@kbd{C-c C-p u}) ++This command removes any citation strings from the beginning of each ++cited line in the region by interpreting the selected frame from ++@code{sc-uncite-frame-alist}, or the default unciting frame ++@code{sc-default-uncite-frame}. It runs the hook ++@code{sc-pre-uncite-hook} before interpreting the frame. ++@xref{Configuring the Citation Engine}.@refill ++ ++@findex sc-recite-region ++@findex recite-region (sc-) ++@kindex C-c C-p r ++@item @code{sc-recite-region} (@kbd{C-c C-p r}) ++This command recites each line the region by interpreting the selected ++frame from @code{sc-recite-frame-alist}, or the default reciting frame ++@code{sc-default-recite-frame}. It runs the hook ++@code{sc-pre-recite-hook} before interpreting the frame. ++@xref{Configuring the Citation Engine}.@refill ++ ++@vindex sc-confirm-always-p ++@vindex confirm-always-p (sc-) ++Supercite will always ask you to confirm the attribution when reciting a ++region, regardless of the value of @code{sc-confirm-always-p}. ++@end table ++ ++@node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands ++@section Insertion Commands ++ ++These two functions insert various strings into the reply buffer. ++ ++@table @asis ++@findex sc-insert-reference ++@findex insert-reference (sc-) ++@kindex C-c C-p w ++@item @code{sc-insert-reference} (@kbd{C-c C-p w}) ++@vindex sc-preferred-header-style ++@vindex preferred-header-style (sc-) ++Inserts a reference header into the reply buffer at @samp{point}. With ++no arguments, the header indexed by @code{sc-preferred-header-style} is ++inserted. An optional numeric argument is the index into ++@code{sc-rewrite-header-list} indicating which reference header to ++write.@refill ++ ++With just the universal argument (@kbd{C-u}), electric reference mode is ++entered, regardless of the value of @code{sc-electric-references-p}. ++ ++@findex sc-insert-citation ++@findex insert-citation (sc-) ++@kindex C-c C-p i ++@item @code{sc-insert-citation} (@kbd{C-c C-p i}) ++Inserts the current citation string at the beginning of the line that ++@samp{point} is on. If the line is already cited, Supercite will issue ++an error and will not cite the line. ++@end table ++ ++@node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands ++@cindex toggling variables ++@section Variable Toggling Shortcuts ++ ++Supercite defines a number of commands that make it easier for you to ++toggle and set various Supercite variables as you are editing the reply ++buffer. For example, you may want to turn off filling or whitespace ++cleanup, but only temporarily. These toggling shortcut commands make ++this easy to do. ++ ++@kindex C-c C-p C-t ++Like Supercite commands in general, the toggling commands are placed on ++a keymap prefix within the greater Supercite keymap. For the default ++value of @code{sc-mode-map-prefix}, this will be ++@kbd{C-c C-p C-t}.@refill ++ ++The following commands toggle the value of certain Supercite variables ++which take only a binary value: ++ ++@table @kbd ++@item C-c C-p C-t b ++Toggles the variable @code{sc-mail-nuke-blank-lines-p}. ++ ++@item C-c C-p C-t c ++Toggles the variable @code{sc-confirm-always-p}. ++ ++@item C-c C-p C-t d ++Toggles the variable @code{sc-downcase-p}. ++ ++@item C-c C-p C-t e ++Toggles the variable @code{sc-electric-references-p}. ++ ++@item C-c C-p C-t f ++Toggles the variable @code{sc-auto-fill-region-p}. ++ ++@item C-c C-p C-t o ++Toggles the variable @code{sc-electric-circular-p}. ++ ++@item C-c C-p C-t s ++Toggles the variable @code{sc-nested-citation-p}. ++ ++@item C-c C-p C-t u ++Toggles the variable @code{sc-use-only-preferences-p}. ++ ++@item C-c C-p C-t w ++Toggles the variable @code{sc-fixup-whitespace-p}. ++@end table ++ ++@findex set-variable ++The following commands let you set the value of multi-value variables, ++in the same way that Emacs' @code{set-variable} does: ++ ++@table @kbd ++@item C-c C-p C-t a ++Sets the value of the variable @code{sc-preferred-attribution-list}. ++ ++@item C-c C-p C-t l ++Sets the value of the variable @code{sc-cite-region-limit}. ++ ++@item C-c C-p C-t n ++Sets the value of the variable @code{sc-mail-nuke-mail-headers}. ++ ++@item C-c C-p C-t N ++Sets the value of the variable @code{sc-mail-header-nuke-list}. ++ ++@item C-c C-p C-t p ++Sets the value of the variable @code{sc-preferred-header-style}. ++@end table ++ ++@kindex C-c C-p C-p ++One special command is provided to toggle both ++@code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together. ++This is because you typically want to run Supercite with either variable ++as @code{nil} or non-@code{nil}. The command to toggle these variables ++together is bound on @kbd{C-c C-p C-p}.@refill ++ ++Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?}) ++brings up a Help message on the toggling keymap. ++ ++ ++@node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands ++@section Mail Field Commands ++ ++These commands allow you to view, modify, add, and delete various bits ++of information from the info alist. ++@xref{Information Keys and the Info Alist}.@refill ++ ++@table @asis ++@kindex C-c C-p f ++@findex sc-mail-field-query ++@findex mail-field-query (sc-) ++@kindex C-c C-p f ++@item @code{sc-mail-field-query} (@kbd{C-c C-p f}) ++Allows you to interactively view, modify, add, and delete info alist ++key-value pairs. With no argument, you are prompted (with completion) ++for a info key. The value associated with that key is displayed in the ++minibuffer. With an argument, this command will first ask if you want ++to view, modify, add, or delete an info key. Viewing is identical to ++running the command with no arguments. ++ ++If you want to modify the value of a key, Supercite will first prompt ++you (with completion) for the key of the value you want to change. It ++will then put you in the minibuffer with the key's current value so you ++can edit the value as you wish. When you hit @key{RET}, the key's value ++is changed. Minibuffer history is kept for the values. ++ ++If you choose to delete a key-value pair, Supercite will prompt you (with ++completion) for the key to delete. ++ ++If you choose to add a new key-value pair, Supercite firsts prompts you ++for the key to add. Note that completion is turned on for this prompt, ++but you can type any key name here, even one that does not yet exist. ++After entering the key, Supercite prompts you for the key's value. It ++is not an error to enter a key that already exists, but the new value ++will override any old value. It will not replace it though; if you ++subsequently delete the key-value pair, the old value will reappear. ++ ++@findex sc-mail-process-headers ++@findex mail-process-headers (sc-) ++@kindex C-c C-p g ++@item @code{sc-mail-process-headers} (@kbd{C-c C-p g}) ++This command lets you re-initialize Supercite's info alist from any set ++of mail headers in the region between @samp{point} and @samp{mark}. ++This function is especially useful for replying to digest messages where ++Supercite will initially set up its information for the digest ++originator, but you want to cite each component article with the real ++message author. Note that unless an error during processing occurs, any ++old information is lost.@refill ++@end table ++ ++@node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands ++@section Miscellaneous Commands ++ ++@table @asis ++@findex sc-open-line ++@findex open-line (sc-) ++@findex open-line ++@kindex C-c C-p o ++@item @code{sc-open-line} (@kbd{C-c C-p o}) ++Similar to Emacs' standard @code{open-line} commands, but inserts the ++citation string in front of the new line. As with @code{open-line}, ++an optional numeric argument inserts that many new lines.@refill ++@end table ++ ++@node Hints to MUA Authors, Thanks and History, Electric References, Top ++@chapter Hints to MUA Authors ++ ++In June of 1989, some discussion was held between the various MUA ++authors, the Supercite author, and other Supercite users. These ++discussions centered around the need for a standard interface between ++MUAs and Supercite (or any future Supercite-like packages). This ++interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in ++a mail message to the Supercite mailing list: ++ ++@example ++ Martin> Each news/mail-reader should provide a form of ++ Martin> mail-yank-original that ++ ++ Martin> 1: inserts the original message incl. header into the ++ Martin> reply buffer; no indentation/prefixing is done, the header ++ Martin> tends to be a "full blown" version rather than to be ++ Martin> stripped down. ++ ++ Martin> 2: `point' is at the start of the header, `mark' at the ++ Martin> end of the message body. ++ ++ Martin> 3: (run-hooks 'mail-yank-hooks) ++ ++ Martin> [Supercite] should be run as such a hook and merely ++ Martin> rewrite the message. This way it isn't anymore ++ Martin> [Supercite]'s job to gather the original from obscure ++ Martin> sources. [@dots{}] ++@end example ++ ++@vindex mail-citation-hook ++@vindex mail-yank-hooks ++@cindex sendmail.el ++@findex mail-yank-original ++@findex defvar ++This specification was adopted, but underwent a slight modification with ++the release of Emacs 19. Instead of the variable ++@code{mail-yank-hooks}, the hook variable that the MUA should provide is ++@code{mail-citation-hook}. Richard Stallman suggests that the MUAs ++should @code{defvar} @code{mail-citation-hook} to @code{nil} and perform ++some default citing when that is the case.@refill ++ ++If you are writing a new MUA package, or maintaining an existing MUA ++package, you should make it conform to this interface so that your users ++will be able to link Supercite easily and seamlessly. To do this, when ++setting up a reply or forward buffer, your MUA should follow these ++steps: ++ ++@enumerate ++@item ++Insert the original message, including the mail headers into the reply ++buffer. At this point you should not modify the raw text in any way, and ++you should place all the original headers into the body of the reply. ++This means that many of the mail headers will be duplicated, one copy ++above the @code{mail-header-separator} line and one copy below, ++however there will probably be more headers below this line.@refill ++ ++@item ++Set @samp{point} to the beginning of the line containing the first mail ++header in the body of the reply. Set @samp{mark} at the end of the ++message text. It is very important that the region be set around the ++text Supercite is to modify and that the mail headers are within this ++region. Supercite will not venture outside the region for any reason, ++and anything within the region is fair game, so don't put anything that ++@strong{must} remain unchanged inside the region.@refill ++ ++@item ++Run the hook @code{mail-citation-hook}. You will probably want to ++provide some kind of default citation functions in cases where the user ++does not have Supercite installed. By default, your MUA should ++@code{defvar} @code{mail-citation-hook} to @code{nil}, and in your ++yanking function, check its value. If it finds ++@code{mail-citation-hook} to be @code{nil}, it should perform some ++default citing behavior. User who want to connect to Supercite then ++need only add @code{sc-cite-original} to this list of hooks using ++@code{add-hook}.@refill ++@end enumerate ++ ++If you do all this your MUA will join the ranks of those that conform to ++this interface ``out of the box.'' ++ ++@node Thanks and History, GNU Free Documentation License, Hints to MUA Authors, Top ++@chapter Thanks and History ++ ++The Supercite package was derived from its predecessor Superyank 1.11 ++which was inspired by various bits of code and ideas from Martin Neitzel ++and Ashwin Ram. They were the folks who came up with the idea of ++non-nested citations and implemented some rough code to provide this ++style. Superyank and Supercite version 2 evolved to the point where much ++of the attribution selection mechanism was automatic, and features have ++been continuously added through the comments and suggestions of the ++Supercite mailing list participants. ++ ++With version 3, Supercite underwent an almost complete rewrite, ++benefitting in a number of ways, including vast improvements in the ++speed of performance, a big reduction in size of the code and in the use ++of Emacs resources, and a much cleaner and flexible internal ++architecture. Most of this work was internal and not of very great ++importance to the casual user. There were some changes at the ++user-visible level, but for the most part, the Supercite configuration ++variables from version 2 should still be relevant to version 3. ++Hopefully Supercite version 3 is faster, smaller, and much more flexible ++than its predecessors. ++ ++In the version 2 manual I thanked some specific people for their help in ++developing Supercite 2. You folks know who you are and your continued ++support is greatly appreciated. I wish to thank everyone on the ++Supercite mailing list, especially the brave alpha testers, who helped ++considerably in testing out the concepts and implementation of Supercite ++version 3. Special thanks go out to the MUA and Emacs authors Kyle ++Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming ++to a quick agreement on the new @code{mail-citation-hook} interface, and ++for adding the magic lisp to their code to support this. ++ ++All who have helped and contributed have been greatly appreciated. ++ ++Supercite was written by Barry Warsaw. ++ ++@node GNU Free Documentation License, Concept Index, Thanks and History, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Concept Index, Command Index, GNU Free Documentation License, Top ++@unnumbered Concept Index ++@printindex cp ++ ++@node Command Index, Key Index, Concept Index, Top ++@unnumbered Command Index ++@ifinfo ++ ++@end ifinfo ++Since all supercite commands are prepended with the string ++``@code{sc-}'', each appears under its @code{sc-}@var{command} name and ++its @var{command} name. ++@iftex ++@sp 2 ++@end iftex ++@printindex fn ++ ++@node Key Index, Variable Index, Command Index, Top ++@unnumbered Key Index ++@printindex ky ++ ++@node Variable Index, , Key Index, Top ++@unnumbered Variable Index ++@ifinfo ++ ++@end ifinfo ++Since all supercite variables are prepended with the string ++``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and ++its @var{variable} name. ++@iftex ++@sp 2 ++@end iftex ++@printindex vr ++@bye ++ ++@ignore ++ arch-tag: 0521847a-4680-44b6-ae6e-13ce20e18436 ++@end ignore +diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi +new file mode 100644 +index 0000000..89228df +--- /dev/null ++++ b/doc/misc/ses.texi +@@ -0,0 +1,988 @@ ++\input texinfo @c -*-texinfo-*- ++@c %**start of header ++@setfilename ../../info/ses ++@settitle SES: Simple Emacs Spreadsheet ++@setchapternewpage off ++@syncodeindex fn cp ++@syncodeindex vr cp ++@syncodeindex ky cp ++@c %**end of header ++ ++@copying ++This file documents SES: the Simple Emacs Spreadsheet. ++ ++Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++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 Emacs ++@direntry ++* SES: (ses). Simple Emacs Spreadsheet ++@end direntry ++ ++@finalout ++ ++@titlepage ++@title SES ++@subtitle Simple Emacs Spreadsheet ++@author Jonathan A. Yavner ++@author @email{jyavner@@member.fsf.org} ++ ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@c =================================================================== ++ ++@ifnottex ++@node Top, Sales Pitch, (dir), (dir) ++@comment node-name, next, previous, up ++@top SES: Simple Emacs Spreadsheet ++ ++@display ++SES is a major mode for GNU Emacs to edit spreadsheet files, which ++contain a rectangular grid of cells. The cells' values are specified ++by formulas that can refer to the values of other cells. ++@end display ++@end ifnottex ++ ++To report bugs, send email to @email{jyavner@@member.fsf.org}. ++ ++@insertcopying ++ ++@menu ++* Sales Pitch:: Why use SES? ++* The Basics:: Basic spreadsheet commands ++* Advanced Features:: Want to know more? ++* For Gurus:: Want to know @emph{even more}? ++* Index:: Concept, Function and Variable Index ++* Acknowledgements:: Acknowledgements ++* GNU Free Documentation License:: The license for this documentation. ++@end menu ++ ++@c =================================================================== ++ ++@node Sales Pitch, The Basics, Top, Top ++@comment node-name, next, previous, up ++@chapter Sales Pitch ++@cindex features ++ ++@itemize @bullet ++@item Create and edit simple spreadsheets with a minimum of fuss. ++@item Full undo/redo/autosave. ++@item Immune to viruses in spreadsheet files. ++@item Cell formulas are straight Emacs Lisp. ++@item Printer functions for control of cell appearance. ++@item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc. ++@item ``Spillover'' of lengthy cell values into following blank cells. ++@item Header line shows column letters or a selected row. ++@item Completing-read for entering symbols as cell values. ++@item Cut, copy, and paste can transfer formulas and printer functions. ++@item Import and export of tab-separated values or tab-separated formulas. ++@item Plaintext, easily-hacked file format. ++@end itemize ++ ++@c =================================================================== ++ ++@node The Basics, Advanced Features, Sales Pitch, Top ++@comment node-name, next, previous, up ++@chapter The Basics ++@cindex basic commands ++@findex ses-jump ++@findex ses-mark-row ++@findex ses-mark-column ++@findex ses-mark-whole-buffer ++@findex set-mark-command ++@findex keyboard-quit ++ ++To create a new spreadsheet, visit a nonexistent file whose name ends ++ with ".ses". For example, @kbd{C-x C-f test.ses RET}. ++ ++ ++A @dfn{cell identifier} is a symbol with a column letter and a row ++number. Cell B7 is the 2nd column of the 7th row. For very wide ++spreadsheets, there are two column letters: cell AB7 is the 28th ++column of the 7th row. Super wide spreadsheets get AAA1, etc. ++ ++@table @kbd ++@item j ++Moves point to cell, specified by identifier (@code{ses-jump}). ++@end table ++ ++Point is always at the left edge of a cell, or at the empty endline. ++When mark is inactive, the current cell is underlined. When mark is ++active, the range is the highlighted rectangle of cells (SES always ++uses transient mark mode). Drag the mouse from A1 to A3 to create the ++range A1-A2. Many SES commands operate only on single cells, not ++ranges. ++ ++@table @kbd ++@item C-SPC ++@itemx C-@@ ++Set mark at point (@code{set-mark-command}). ++ ++@item C-g ++Turn off the mark (@code{keyboard-quit}). ++ ++@item M-h ++Highlight current row (@code{ses-mark-row}). ++ ++@item S-M-h ++Highlight current column (@code{ses-mark-column}). ++ ++@item C-x h ++Highlight all cells (@code{mark-whole-buffer}). ++@end table ++ ++@menu ++* Formulas:: ++* Resizing:: ++* Printer functions:: ++* Clearing cells:: ++* Copy/cut/paste:: ++* Customizing SES:: ++@end menu ++ ++@node Formulas, Resizing, The Basics, The Basics ++@section Cell formulas ++@cindex formulas ++@cindex formulas, entering ++@findex ses-read-cell ++@findex ses-read-symbol ++@findex ses-edit-cell ++@findex ses-recalculate-cell ++@findex ses-recalculate-all ++ ++To enter a number into the current cell, just start typing: ++ ++@table @kbd ++@item 0..9 ++Self-insert a digit (@code{ses-read-cell}). ++ ++@item - ++Self-insert a negative number (@code{ses-read-cell}). ++ ++@item . ++Self-insert a fractional number (@code{ses-read-cell}). ++ ++@item " ++Self-insert a quoted string. The ending double-quote ++is inserted for you (@code{ses-read-cell}). ++ ++@item ( ++Self-insert an expression. The right-parenthesis is inserted for you ++(@code{ses-read-cell}). To access another cell's value, just use its ++identifier in your expression. Whenever the other cell is changed, ++this cell's formula will be reevaluated. While typing in the ++expression, you can use @kbd{M-@key{TAB}} to complete symbol names. ++ ++@item ' @r{(apostrophe)} ++Enter a symbol (ses-read-symbol). SES remembers all symbols that have ++been used as formulas, so you can type just the beginning of a symbol ++and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it. ++@end table ++ ++To enter something else (e.g., a vector), begin with a digit, then ++erase the digit and type whatever you want. ++ ++@table @kbd ++@item RET ++Edit the existing formula in the current cell (@code{ses-edit-cell}). ++ ++@item C-c C-c ++Force recalculation of the current cell or range (@code{ses-recalculate-cell}). ++ ++@item C-c C-l ++Recalculate the entire spreadsheet (@code{ses-recalculate-all}). ++@end table ++ ++@node Resizing, Printer functions, Formulas, The Basics ++@section Resizing the spreadsheet ++@cindex resizing spreadsheets ++@findex ses-insert-row ++@findex ses-insert-column ++@findex ses-delete-row ++@findex ses-delete-column ++@findex ses-set-column-width ++@findex ses-forward-or-insert ++@findex ses-append-row-jump-first-column ++ ++ ++Basic commands: ++ ++@table @kbd ++@item C-o ++(@code{ses-insert-row}) ++ ++@item M-o ++(@code{ses-insert-column}) ++ ++@item C-k ++(@code{ses-delete-row}) ++ ++@item M-k ++(@code{ses-delete-column}) ++ ++@item w ++(@code{ses-set-column-width}) ++ ++@item TAB ++Moves point to the next rightward cell, or inserts a new column if ++already at last cell on line, or inserts a new row if at endline ++(@code{ses-forward-or-insert}). ++ ++@item C-j ++Linefeed inserts below the current row and moves to column A ++(@code{ses-append-row-jump-first-column}). ++@end table ++ ++Resizing the spreadsheet (unless you're just changing a column width) ++relocates all the cell-references in formulas so they still refer to ++the same cells. If a formula mentioned B1 and you insert a new first ++row, the formula will now mention B2. ++ ++If you delete a cell that a formula refers to, the cell-symbol is ++deleted from the formula, so @code{(+ A1 B1 C1)} after deleting the third ++column becomes @code{(+ A1 B1)}. In case this is not what you wanted: ++ ++@table @kbd ++@item C-_ ++@itemx C-x u ++Undo previous action (@code{(undo)}). ++@end table ++ ++ ++@node Printer functions, Clearing cells, Resizing, The Basics ++@section Printer functions ++@cindex printer functions ++@findex ses-read-cell-printer ++@findex ses-read-column-printer ++@findex ses-read-default-printer ++@findex ses-center ++@findex ses-center-span ++@findex ses-dashfill ++@findex ses-dashfill-span ++@findex ses-tildefill-span ++ ++ ++Printer functions convert binary cell values into the print forms that ++Emacs will display on the screen. ++ ++A printer can be a format string, like @samp{"$%.2f"}. The result ++string is right-aligned within the print cell. To get left-alignment, ++use parentheses: @samp{("$%.2f")}. A printer can also be a ++one-argument function (a symbol or a lambda), whose result is a string ++(right-aligned) or list of one string (left-aligned). While typing in ++a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols. ++ ++Each cell has a printer. If @code{nil}, the column-printer for the cell's ++column is used. If that is also @code{nil}, the default-printer for the ++spreadsheet is used. ++ ++@table @kbd ++@item p ++Enter a printer for current cell or range (@code{ses-read-cell-printer}). ++ ++@item M-p ++Enter a printer for the current column (@code{ses-read-column-printer}). ++ ++@item C-c C-p ++Enter the default printer for the spreadsheet ++(@code{ses-read-default-printer}). ++@end table ++ ++The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer ++history, which is preloaded with the set of all printers used in this ++spreadsheet, plus the standard printers. ++ ++The standard printers are suitable only for cells, not columns or ++default, because they format the value using the column-printer (or ++default-printer if @code{nil}) and then center the result: ++ ++@table @code ++@item ses-center ++Just centering. ++ ++@item ses-center-span ++Centering with spill-over to following blank cells. ++ ++@item ses-dashfill ++Centering using dashes (-) instead of spaces. ++ ++@item ses-dashfill-span ++Centering with dashes and spill-over. ++ ++@item ses-tildefill-span ++Centering with tildes (~) and spill-over. ++@end table ++ ++ ++@node Clearing cells, Copy/cut/paste, Printer functions, The Basics ++@section Clearing cells ++@cindex clearing commands ++@findex ses-clear-cell-backward ++@findex ses-clear-cell-forward ++ ++These commands set both formula and printer to @code{nil}: ++ ++@table @kbd ++@item DEL ++Clear cell and move left (@code{ses-clear-cell-backward}). ++ ++@item C-d ++Clear cell and move right (@code{ses-clear-cell-forward}). ++@end table ++ ++ ++@node Copy/cut/paste, Customizing SES, Clearing cells, The Basics ++@section Copy, cut, and paste ++@cindex copy ++@cindex cut ++@cindex paste ++@findex kill-ring-save ++@findex mouse-set-region ++@findex mouse-set-secondary ++@findex ses-kill-override ++@findex yank ++@findex clipboard-yank ++@findex mouse-yank-at-click ++@findex mouse-yank-at-secondary ++@findex ses-yank-pop ++ ++The copy functions work on rectangular regions of cells. You can paste the ++copies into non-SES buffers to export the print text. ++ ++@table @kbd ++@item M-w ++@itemx [copy] ++@itemx [C-insert] ++Copy the highlighted cells to kill ring and primary clipboard ++(@code{kill-ring-save}). ++ ++@item [drag-mouse-1] ++Mark a region and copy it to kill ring and primary clipboard ++(@code{mouse-set-region}). ++ ++@item [M-drag-mouse-1] ++Mark a region and copy it to kill ring and secondary clipboard ++(@code{mouse-set-secondary}). ++ ++@item C-w ++@itemx [cut] ++@itemx [S-delete] ++The cut functions do not actually delete rows or columns---they copy ++and then clear (@code{ses-kill-override}). ++ ++@item C-y ++@itemx [S-insert] ++Paste from kill ring (@code{yank}). The paste functions behave ++differently depending on the format of the text being inserted: ++@itemize @bullet ++@item ++When pasting cells that were cut from a SES buffer, the print text is ++ignored and only the attached formula and printer are inserted; cell ++references in the formula are relocated unless you use @kbd{C-u}. ++@item ++The pasted text overwrites a rectangle of cells whose top left corner ++is the current cell. If part of the rectangle is beyond the edges of ++the spreadsheet, you must confirm the increase in spreadsheet size. ++@item ++Non-SES text is usually inserted as a replacement formula for the ++current cell. If the formula would be a symbol, it's treated as a ++string unless you use @kbd{C-u}. Pasted formulas with syntax errors ++are always treated as strings. ++@end itemize ++ ++@item [paste] ++Paste from primary clipboard or kill ring (@code{clipboard-yank}). ++ ++@item [mouse-2] ++Set point and paste from primary clipboard (@code{mouse-yank-at-click}). ++ ++@item [M-mouse-2] ++Set point and paste from secondary clipboard (@code{mouse-yank-secondary}). ++ ++@item M-y ++Immediately after a paste, you can replace the text with a preceding ++element from the kill ring (@code{ses-yank-pop}). Unlike the standard ++Emacs yank-pop, the SES version uses @code{undo} to delete the old ++yank. This doesn't make any difference? ++@end table ++ ++@node Customizing SES, , Copy/cut/paste, The Basics ++@section Customizing SES ++@cindex customizing ++@vindex enable-local-eval ++@vindex ses-mode-hook ++@vindex safe-functions ++@vindex enable-local-eval ++ ++ ++By default, a newly-created spreadsheet has 1 row and 1 column. The ++column width is 7 and the default printer is @samp{"%.7g"}. Each of these ++can be customized. Look in group ``ses''. ++ ++After entering a cell value, point normally moves right to the next ++cell. You can customize @code{ses-after-entry-functions} to move left or ++up or down. For diagonal movement, select two functions from the ++list. ++ ++@code{ses-mode-hook} is a normal mode hook (list of functions to ++execute when starting SES mode for a buffer). ++ ++The variable @code{safe-functions} is a list of possibly-unsafe ++functions to be treated as safe when analysing formulas and printers. ++@xref{Virus protection}. Before customizing @code{safe-functions}, ++think about how much you trust the person who's suggesting this ++change. The value @code{t} turns off all anti-virus protection. A ++list-of-functions value might enable a ``gee whiz'' spreadsheet, but it ++also creates trapdoors in your anti-virus armor. In order for virus ++protection to work, you must always press @kbd{n} when presented with ++a virus warning, unless you understand what the questionable code is ++trying to do. Do not listen to those who tell you to customize ++@code{enable-local-eval}---this variable is for people who don't wear ++safety belts! ++ ++ ++@c =================================================================== ++ ++@node Advanced Features, For Gurus, The Basics, Top ++@chapter Advanced Features ++@cindex advanced features ++@findex ses-read-header-row ++ ++ ++@table @kbd ++@item C-c M-C-h ++(@code{ses-set-header-row}). The header line at the top of the SES ++window normally shows the column letter for each column. You can set ++it to show a copy of some row, such as a row of column titles, so that ++row will always be visible. Default is to set the current row as the ++header; use C-u to prompt for header row. Set the header to row 0 to ++show column letters again. ++@item [header-line mouse-3] ++Pops up a menu to set the current row as the header, or revert to ++column letters. ++@end table ++ ++@menu ++* The print area:: ++* Ranges in formulas:: ++* Sorting by column:: ++* Standard formula functions:: ++* More on cell printing:: ++* Import and export:: ++* Virus protection:: ++* Spreadsheets with details and summary:: ++@end menu ++ ++@node The print area, Ranges in formulas, Advanced Features, Advanced Features ++@section The print area ++@cindex print area ++@findex widen ++@findex ses-renarrow-buffer ++@findex ses-reprint-all ++ ++A SES file consists of a print area and a data area. Normally the ++buffer is narrowed to show only the print area. The print area is ++read-only except for special SES commands; it contains cell values ++formatted by printer functions. The data area records the formula and ++printer functions, etc. ++ ++@table @kbd ++@item C-x n w ++Show print and data areas (@code{widen}). ++ ++@item C-c C-n ++Show only print area (@code{ses-renarrow-buffer}). ++ ++@item S-C-l ++@itemx M-C-l ++Recreate print area by reevaluating printer functions for all cells ++(@code{ses-reprint-all}). ++@end table ++ ++@node Ranges in formulas, Sorting by column, The print area, Advanced Features ++@section Ranges in formulas ++@cindex ranges ++@findex ses-insert-range-click ++@findex ses-insert-range ++@findex ses-insert-ses-range-click ++@findex ses-insert-ses-range ++@vindex from ++@vindex to ++ ++A formula like ++@lisp ++(+ A1 A2 A3) ++@end lisp ++is the sum of three specific cells. If you insert a new second row, ++the formula becomes ++@lisp ++(+ A1 A3 A4) ++@end lisp ++and the new row is not included in the sum. ++ ++The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of ++the values in a rectangle of cells. If your formula is ++@lisp ++(apply '+ (ses-range A1 A3)) ++@end lisp ++and you insert a new second row, it becomes ++@lisp ++(apply '+ (ses-range A1 A4)) ++@end lisp ++and the new row is included in the sum. ++ ++While entering or editing a formula in the minibuffer, you can select ++a range in the spreadsheet (using mouse or keyboard), then paste a ++representation of that range into your formula. Suppose you select ++A1-C1: ++ ++@table @kbd ++@item [S-mouse-3] ++Inserts "A1 B1 C1" @code{(ses-insert-range-click}) ++ ++@item C-c C-r ++Keyboard version (@code{ses-insert-range}). ++ ++@item [C-S-mouse-3] ++Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}). ++ ++@item C-c C-s ++Keyboard version (@code{ses-insert-ses-range}). ++@end table ++ ++If you delete the @var{from} or @var{to} cell for a range, the nearest ++still-existing cell is used instead. If you delete the entire range, ++the formula relocator will delete the ses-range from the formula. ++ ++If you insert a new row just beyond the end of a one-column range, or ++a new column just beyond a one-row range, the new cell is included in ++the range. New cells inserted just before a range are not included. ++ ++ ++@node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features ++@section Sorting by column ++@cindex sorting ++@findex ses-sort-column ++@findex ses-sort-column-click ++ ++@table @kbd ++@item C-c M-C-s ++Sort the cells of a range using one of the columns ++(@code{ses-sort-column}). The rows (or partial rows if the range ++doesn't include all columns) are rearranged so the chosen column will ++be in order. ++ ++@item [header-line mouse-2] ++The easiest way to sort is to click mouse-2 on the chosen column's header row ++(@code{ses-sort-column-click}). ++@end table ++ ++The sort comparison uses @code{string<}, which works well for ++right-justified numbers and left-justified strings. ++ ++With prefix arg, sort is in descending order. ++ ++Rows are moved one at a time, with relocation of formulas. This works ++well if formulas refer to other cells in their row, not so well for ++formulas that refer to other rows in the range or to cells outside the ++range. ++ ++ ++@node Standard formula functions, More on cell printing, Sorting by column, Advanced Features ++@section Standard formula functions ++@cindex standard formula functions ++@cindex *skip* ++@cindex *error* ++@findex ses-delete-blanks ++@findex ses-average ++@findex ses+ ++ ++Oftentimes you want a calculation to exclude the blank cells. Here ++are some useful functions to call from your formulas: ++ ++@table @code ++@item (ses-delete-blanks &rest @var{args}) ++Returns a list from which all blank cells (value is either @code{nil} or ++'*skip*) have been deleted. ++ ++@item (ses+ &rest @var{args}) ++Sum of non-blank arguments. ++ ++@item (ses-average @var{list}) ++Average of non-blank elements in @var{list}. Here the list is passed ++as a single argument, since you'll probably use it with @code{ses-range}. ++@end table ++ ++@node More on cell printing, Import and export, Standard formula functions, Advanced Features ++@section More on cell printing ++@cindex cell printing, more ++@findex ses-truncate-cell ++@findex ses-recalculate-cell ++ ++Special cell values: ++@itemize ++@item nil prints the same as "", but allows previous cell to spill over. ++@item '*skip* replaces nil when the previous cell actually does spill over; ++nothing is printed for it. ++@item '*error* indicates that the formula signaled an error instead of ++producing a value: the print cell is filled with hash marks (#). ++@end itemize ++ ++If the result from the printer function is too wide for the cell and ++the following cell is @code{nil}, the result will spill over into the ++following cell. Very wide results can spill over several cells. If ++the result is too wide for the available space (up to the end of the ++row or the next non-@code{nil} cell), the result is truncated if the cell's ++value is a string, or replaced with hash marks otherwise. ++ ++SES could get confused by printer results that contain newlines or ++tabs, so these are replaced with question marks. ++ ++@table @kbd ++@item t ++Confine a cell to its own column (@code{ses-truncate-cell}). This ++allows you to move point to a rightward cell that would otherwise be ++covered by a spill-over. If you don't change the rightward cell, the ++confined cell will spill over again the next time it is reprinted. ++ ++@item c ++When applied to a single cell, this command displays in the echo area ++any formula error or printer error that occurred during ++recalculation/reprinting (@code{ses-recalculate-cell}). You can use ++this to undo the effect of @kbd{t}. ++@end table ++ ++When a printer function signals an error, the fallback printer ++@samp{"%s"} is substituted. This is useful when your column printer ++is numeric-only and you use a string as a cell value. Note that the ++standard default printer is ``%.7g'' which is numeric-only, so cells ++that are empty of contain strings will use the fallback printer. ++@kbd{c} on such cells will display ``Format specifier doesn't match ++argument type''. ++ ++ ++@node Import and export, Virus protection, More on cell printing, Advanced Features ++@section Import and export ++@cindex import and export ++@cindex export, and import ++@findex ses-export-tsv ++@findex ses-export-tsf ++ ++@table @kbd ++@item x t ++Export a range of cells as tab-separated values (@code{ses-export-tsv}). ++@item x T ++Export a range of cells as tab-separated formulas (@code{ses-export-tsf}). ++@end table ++ ++The exported text goes to the kill ring --- you can paste it into ++another buffer. Columns are separated by tabs, rows by newlines. ++ ++To import text, use any of the yank commands where the text to paste ++contains tabs and/or newlines. Imported formulas are not relocated. ++ ++@node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features ++@section Virus protection ++@cindex virus protection ++ ++Whenever a formula or printer is read from a file or is pasted into ++the spreadsheet, it receives a ``needs safety check'' marking. Later, ++when the formula or printer is evaluated for the first time, it is ++checked for safety using the @code{unsafep} predicate; if found to be ++``possibly unsafe'', the questionable formula or printer is displayed ++and you must press Y to approve it or N to use a substitute. The ++substitute always signals an error. ++ ++Formulas or printers that you type in are checked immediately for ++safety. If found to be possibly unsafe and you press N to disapprove, ++the action is canceled and the old formula or printer will remain. ++ ++Besides viruses (which try to copy themselves to other files), ++@code{unsafep} can also detect all other kinds of Trojan horses, such as ++spreadsheets that delete files, send email, flood Web sites, alter ++your Emacs settings, etc. ++ ++Generally, spreadsheet formulas and printers are simple things that ++don't need to do any fancy computing, so all potentially-dangerous ++parts of the Emacs Lisp environment can be excluded without cramping ++your style as a formula-writer. See the documentation in @file{unsafep.el} ++for more info on how Lisp forms are classified as safe or unsafe. ++ ++@node Spreadsheets with details and summary, , Virus protection, Advanced Features ++@section Spreadsheets with details and summary ++@cindex details and summary ++@cindex summary, and details ++ ++A common organization for spreadsheets is to have a bunch of ``detail'' ++rows, each perhaps describing a transaction, and then a set of ++``summary'' rows that each show reduced data for some subset of the ++details. SES supports this organization via the @code{ses-select} ++function. ++ ++@table @code ++@item (ses-select @var{fromrange} @var{test} @var{torange}) ++Returns a subset of @var{torange}. For each member in @var{fromrange} ++that is equal to @var{test}, the corresponding member of @var{torange} ++is included in the result. ++@end table ++ ++Example of use: ++@lisp ++(ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5))) ++@end lisp ++This computes the average of the B column values for those rows whose ++A column value is the symbol 'Smith. ++ ++Arguably one could specify only @var{fromrange} plus ++@var{to-row-offset} and @var{to-column-offset}. The @var{torange} is ++stated explicitly to ensure that the formula will be recalculated if ++any cell in either range is changed. ++ ++File @file{etc/ses-example.el} in the Emacs distribution is an example of a ++details-and-summary spreadsheet. ++ ++ ++@c =================================================================== ++ ++@node For Gurus, Index, Advanced Features, Top ++@chapter For Gurus ++@cindex advanced features ++ ++@menu ++* Deferred updates:: ++* Nonrelocatable references:: ++* The data area:: ++* Buffer-local variables in spreadsheets:: ++* Uses of defadvice in SES:: ++@end menu ++ ++@node Deferred updates, Nonrelocatable references, For Gurus, For Gurus ++@section Deferred updates ++@cindex deferred updates ++@cindex updates, deferred ++@vindex run-with-idle-timer ++ ++To save time by avoiding redundant computations, cells that need ++recalculation due to changes in other cells are added to a set. At ++the end of the command, each cell in the set is recalculated once. ++This can create a new set of cells that need recalculation. The ++process is repeated until either the set is empty or it stops changing ++(due to circular references among the cells). In extreme cases, you ++might see progress messages of the form ``Recalculating... (@var{nnn} ++cells left)''. If you interrupt the calculation using @kbd{C-g}, the ++spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or ++@kbd{C-c C-l} to fix it. ++ ++To save even more time by avoiding redundant writes, cells that have ++changes are added to a set instead of being written immediately to the ++data area. Each cell in the set is written once, at the end of the ++command. If you change vast quantities of cells, you might see a ++progress message of the form ``Writing... (@var{nnn} cells left)''. ++These deferred cell-writes cannot be interrupted by @kbd{C-g}, so ++you'll just have to wait. ++ ++SES uses @code{run-with-idle-timer} to move the cell underline when ++Emacs will be scrolling the buffer after the end of a command, and ++also to narrow and underline after @kbd{C-x C-v}. This is visible as ++a momentary glitch after C-x C-v and certain scrolling commands. You ++can type ahead without worrying about the glitch. ++ ++ ++@node Nonrelocatable references, The data area, Deferred updates, For Gurus ++@section Nonrelocatable references ++@cindex nonrelocatable references ++@cindex references, nonrelocatable ++ ++@kbd{C-y} relocates all cell-references in a pasted formula, while ++@kbd{C-u C-y} relocates none of the cell-references. What about mixed ++cases? ++ ++You can use ++@lisp ++(symbol-value 'B3) ++@end lisp ++to make an @dfn{absolute reference}. The formula relocator skips over ++quoted things, so this will not be relocated when pasted or when ++rows/columns are inserted/deleted. However, B3 will not be recorded ++as a dependency of this cell, so this cell will not be updated ++automatically when B3 is changed. ++ ++The variables @code{row} and @code{col} are dynamically bound while a ++cell formula is being evaluated. You can use ++@lisp ++(ses-cell-value row 0) ++@end lisp ++to get the value from the leftmost column in the current row. This ++kind of dependency is also not recorded. ++ ++ ++@node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus ++@section The data area ++@cindex data area ++@findex ses-reconstruct-all ++ ++Begins with an 014 character, followed by sets of cell-definition ++macros for each row, followed by column-widths, column-printers, ++default-printer, and header-row. Then there's the global parameters ++(file-format ID, numrows, numcols) and the local variables (specifying ++SES mode for the buffer, etc.) ++ ++When a SES file is loaded, first the numrows and numcols values are ++loaded, then the entire data area is @code{eval}ed, and finally the local ++variables are processed. ++ ++You can edit the data area, but don't insert or delete any newlines ++except in the local-variables part, since SES locates things by ++counting newlines. Use @kbd{C-x C-e} at the end of a line to install ++your edits into the spreadsheet data structures (this does not update ++the print area, use e.g. @kbd{C-c C-l} for that). ++ ++The data area is maintained as an image of spreadsheet data ++structures that area stored in buffer-local variables. If the data ++area gets messed up, you can try reconstructing the data area from the ++data structures: ++ ++@table @kbd ++@item C-c M-C-l ++(@code{ses-reconstruct-all}). ++@end table ++ ++ ++@node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus ++@section Buffer-local variables in spreadsheets ++@cindex buffer-local variables ++@cindex variables, buffer-local ++ ++You can add additional local variables to the list at the bottom of ++the data area, such as hidden constants you want to refer to in your ++formulas. ++ ++You can override the variable @code{ses--symbolic-formulas} to be a list of ++symbols (as parenthesized strings) to show as completions for the ' ++command. This initial completions list is used instead of the actual ++set of symbols-as-formulas in the spreadsheet. ++ ++For an example of this, see file @file{etc/ses-example.ses}. ++ ++If (for some reason) you want your formulas or printers to save data ++into variables, you must declare these variables as buffer-locals in ++order to avoid a virus warning. ++ ++You can define functions by making them values for the fake local ++variable @code{eval}. Such functions can then be used in your ++formulas and printers, but usually each @code{eval} is presented to ++the user during file loading as a potential virus --- this can get ++annoying. ++ ++You can define functions in your @file{.emacs} file. Other people can ++still read the print area of your spreadsheet, but they won't be able ++to recalculate or reprint anything that depends on your functions. To ++avoid virus warnings, each function used in a formula needs ++@lisp ++(put 'your-function-name 'safe-function t) ++@end lisp ++ ++@node Uses of defadvice in SES, , Buffer-local variables in spreadsheets, For Gurus ++@section Uses of defadvice in SES ++@cindex defadvice ++@cindex undo-more ++@cindex copy-region-as-kill ++@cindex yank ++ ++@table @code ++@item undo-more ++Defines a new undo element format (@var{fun} . @var{args}), which ++means ``undo by applying @var{fun} to @var{args}''. For spreadsheet ++buffers, it allows undos in the data area even though that's outside ++the narrowing. ++ ++@item copy-region-as-kill ++When copying from the print area of a spreadsheet, treat the region as ++a rectangle and attach each cell's formula and printer as 'ses ++properties. ++ ++@item yank ++When yanking into the print area of a spreadsheet, first try to yank ++as cells (if the yank text has 'ses properties), then as tab-separated ++formulas, then (if all else fails) as a single formula for the current ++cell. ++@end table ++ ++@c =================================================================== ++@node Index, Acknowledgements, For Gurus, Top ++@unnumbered Index ++ ++@printindex cp ++ ++@c =================================================================== ++ ++@node Acknowledgements, GNU Free Documentation License, Index, Top ++@chapter Acknowledgements ++ ++Coding by: ++@quotation ++Jonathan Yavner @email{jyavner@@member.fsf.org}@* ++Stefan Monnier @email{monnier@@gnu.org}@* ++Shigeru Fukaya @email{shigeru.fukaya@@gmail.com} ++@end quotation ++ ++@noindent ++Texinfo manual by: ++@quotation ++Jonathan Yavner @email{jyavner@@member.fsf.org}@* ++Brad Collins ++@end quotation ++ ++@noindent ++Ideas from: ++@quotation ++Christoph Conrad @email{christoph.conrad@@gmx.de}@* ++CyberBob @email{cyberbob@@redneck.gacracker.org}@* ++Syver Enstad @email{syver-en@@online.no}@* ++Ami Fischman @email{fischman@@zion.bpnetworks.com}@* ++Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@* ++Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@* ++Yusong Li @email{lyusong@@hotmail.com}@* ++Juri Linkov @email{juri@@jurta.org}@* ++Harald Maier @email{maierh@@myself.com}@* ++Alan Nash @email{anash@@san.rr.com}@* ++François Pinard @email{pinard@@iro.umontreal.ca}@* ++Pedro Pinto @email{ppinto@@cs.cmu.edu}@* ++Stefan Reichör @email{xsteve@@riic.at}@* ++Oliver Scholz @email{epameinondas@@gmx.de}@* ++Richard M. Stallman @email{rms@@gnu.org}@* ++Luc Teirlinck @email{teirllm@@dms.auburn.edu}@* ++J. Otto Tennant @email{jotto@@pobox.com}@* ++Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr} ++@end quotation ++ ++@c =================================================================== ++ ++@node GNU Free Documentation License, , Acknowledgements, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@bye ++ ++@ignore ++ arch-tag: 10a4ee1c-7ef4-4c06-8b7a-f975e39f0dec ++@end ignore +diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi +new file mode 100644 +index 0000000..1984842 +--- /dev/null ++++ b/doc/misc/sieve.texi +@@ -0,0 +1,362 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/sieve ++@settitle Emacs Sieve Manual ++@synindex fn cp ++@synindex vr cp ++@synindex pg cp ++ ++@copying ++This file documents the Emacs Sieve package, for server-side mail filtering. ++ ++Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++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 Emacs ++@direntry ++* Sieve: (sieve). Managing Sieve scripts in Emacs. ++@end direntry ++@iftex ++@finalout ++@end iftex ++@setchapternewpage odd ++ ++@titlepage ++@title Emacs Sieve Manual ++ ++@author by Simon Josefsson ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@summarycontents ++@contents ++ ++@node Top ++@top Sieve Support for Emacs ++ ++This is intended as a users manual for Sieve Mode and Manage Sieve, and ++as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp ++API. ++ ++Sieve is a language for server-side filtering of mail. The language ++is documented in RFC 3028. This manual does not attempt to document ++the language, so keep RFC 3028 around. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Installation:: Getting ready to use the package. ++* Sieve Mode:: Editing Sieve scripts. ++* Managing Sieve:: Managing Sieve scripts on a remote server. ++* Examples :: A few Sieve code snippets. ++* Manage Sieve API :: Interfacing to the Manage Sieve Protocol API. ++* Standards:: A summary of RFCs and working documents used. ++* GNU Free Documentation License:: The license for this documentation. ++* Index:: Function and variable index. ++@end menu ++ ++ ++@node Installation ++@chapter Installation ++@cindex Install ++@cindex Setup ++ ++The Sieve package should come with your Emacs version, and should be ++ready for use directly. ++ ++However, to manually set up the package you can put the following ++commands in your @code{~/.emacs}: ++ ++@lisp ++(autoload 'sieve-mode "sieve-mode") ++@end lisp ++@lisp ++(setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode) ++ auto-mode-alist)) ++@end lisp ++ ++ ++@node Sieve Mode ++@chapter Sieve Mode ++ ++Sieve mode provides syntax-based indentation, font-locking support and ++other handy functions to make editing Sieve scripts easier. ++ ++Use @samp{M-x sieve-mode} to switch to this major mode. This command ++runs the hook @code{sieve-mode-hook}. ++ ++@vindex sieve-mode-map ++@vindex sieve-mode-syntax-table ++Sieve mode is derived from @code{c-mode}, and is very similar except ++for the syntax of comments. The keymap (@code{sieve-mode-map}) is ++inherited from @code{c-mode}, as are the variables for customizing ++indentation. Sieve mode has its own abbrev table ++(@code{sieve-mode-abbrev-table}) and syntax table ++(@code{sieve-mode-syntax-table}). ++ ++In addition to the editing utility functions, Sieve mode also contains ++bindings to manage Sieve scripts remotely. @xref{Managing Sieve}. ++ ++@table @kbd ++ ++@item C-c RET ++@kindex C-c RET ++@findex sieve-manage ++@cindex manage remote sieve script ++Open a connection to a remote server using the Managesieve protocol. ++ ++@item C-c C-l ++@kindex C-c C-l ++@findex sieve-upload ++@cindex upload sieve script ++Upload the Sieve script to the currently open server. ++ ++@end table ++ ++ ++@node Managing Sieve ++@chapter Managing Sieve ++ ++Manage Sieve is a special mode used to display Sieve scripts available ++on a remote server. It can be invoked with @kbd{M-x sieve-manage ++RET}, which queries the user for a server and if necessary, user ++credentials to use. ++ ++When a server has been successfully contacted, the Manage Sieve buffer ++looks something like: ++ ++@example ++Server : mailserver:2000 ++ ++2 scripts on server, press RET on a script name edits it, or ++press RET on to create a new script. ++ ++ ACTIVE .sieve ++ template.siv ++@end example ++ ++One of the scripts are highlighted, and standard point navigation ++commands (@kbd{}, @kbd{} etc) can be used to navigate the ++list. ++ ++The following commands are available in the Manage Sieve buffer: ++ ++@table @kbd ++ ++@item m ++@kindex m ++@findex sieve-activate ++Activates the currently highlighted script. ++ ++@item u ++@kindex u ++@findex sieve-deactivate ++Deactivates the currently highlighted script. ++ ++@item C-M-? ++@kindex C-M-? ++@findex sieve-deactivate-all ++Deactivates all scripts. ++ ++@item r ++@kindex r ++@findex sieve-remove ++Remove currently highlighted script. ++ ++@item RET ++@item mouse-2 ++@item f ++@kindex RET ++@kindex mouse-2 ++@kindex f ++@findex sieve-edit-script ++Bury the server buffer and download the currently highlighted script ++into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}). ++ ++@item o ++@kindex o ++@findex sieve-edit-script-other-window ++Create a new buffer in another window containing the currently ++highlighted script for editing in Sieve mode (@pxref{Sieve Mode}). ++ ++@item q ++@kindex q ++@findex sieve-bury-buffer ++Bury the Manage Sieve buffer without closing the connection. ++ ++@item ? ++@item h ++@kindex ? ++@kindex h ++@findex sieve-help ++Displays help in the minibuffer. ++ ++@end table ++ ++@node Examples ++@chapter Examples ++ ++If you are not familiar with Sieve, this chapter contains a few simple ++code snippets that you can cut'n'paste and modify at will, until you ++feel more comfortable with the Sieve language to write the rules from ++scratch. ++ ++The following complete Sieve script places all messages with a matching ++@samp{Sender:} header into the given mailbox. Many mailing lists uses ++this format. The first line makes sure your Sieve server understands ++the @code{fileinto} command. ++ ++@example ++require "fileinto"; ++ ++if address "sender" "owner-w3-beta@@xemacs.org" @{ ++ fileinto "INBOX.w3-beta"; ++@} ++@end example ++ ++A few mailing lists do not use the @samp{Sender:} header, but has a ++unique identifier in some other header. The following is not a ++complete script, it assumes that @code{fileinto} has already been ++required. ++ ++@example ++if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{ ++ fileinto "INBOX.auc-tex"; ++@} ++@end example ++ ++At last, we have the hopeless mailing lists that does not have any ++unique identifier and you are forced to match on the @samp{To:} and ++@samp{Cc} headers. As before, this snippet assumes that @code{fileinto} ++has been required. ++ ++@example ++if address ["to", "cc"] "kerberos@@mit.edu" @{ ++ fileinto "INBOX.kerberos"; ++@} ++@end example ++ ++@node Manage Sieve API ++@chapter Manage Sieve API ++ ++The @file{sieve-manage.el} library contains low-level functionality ++for talking to a server with the @sc{managesieve} protocol. ++ ++A number of user-visible variables exist, which all can be customized ++in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}): ++ ++@table @code ++ ++@item sieve-manage-default-user ++@vindex sieve-manage-default-user ++Sets the default username. ++ ++@item sieve-manage-default-port ++@vindex sieve-manage-default-port ++Sets the default port to use, the suggested port number is @code{2000}. ++ ++@item sieve-manage-log ++@vindex sieve-manage-log ++If non-@code{nil}, should be a string naming a buffer where a protocol trace ++is dumped (for debugging purposes). ++ ++@end table ++ ++The API functions include: ++ ++@table @code ++ ++@item sieve-manage-open ++@findex sieve-manage-open ++Open connection to managesieve server, returning a buffer to be used ++by all other API functions. ++ ++@item sieve-manage-opened ++@findex sieve-manage-opened ++Check if a server is open or not. ++ ++@item sieve-manage-close ++@findex sieve-manage-close ++Close a server connection. ++ ++@item sieve-manage-authenticate ++@findex sieve-manage-authenticate ++Authenticate to the server. ++ ++@item sieve-manage-capability ++@findex sieve-manage-capability ++Return a list of capabilities the server supports. ++ ++@item sieve-manage-listscripts ++@findex sieve-manage-listscripts ++List scripts on the server. ++ ++@item sieve-manage-havespace ++@findex sieve-manage-havespace ++Return non-@code{nil} if the server has room for a script of given ++size. ++ ++@item sieve-manage-getscript ++@findex sieve-manage-getscript ++Download script from server. ++ ++@item sieve-manage-putscript ++@findex sieve-manage-putscript ++Upload script to server. ++ ++@item sieve-manage-setactive ++@findex sieve-manage-setactive ++Indicate which script on the server should be active. ++ ++@end table ++ ++@node Standards ++@chapter Standards ++ ++The Emacs Sieve package implements all or parts of a small but ++hopefully growing number of RFCs and drafts documents. This chapter ++lists the relevant ones. They can all be fetched from ++@uref{http://quimby.gnus.org/notes/}. ++ ++@table @dfn ++ ++@item RFC3028 ++Sieve: A Mail Filtering Language. ++ ++@item draft-martin-managesieve-03 ++A Protocol for Remotely Managing Sieve Scripts ++ ++@end table ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index ++@unnumbered Index ++@printindex cp ++ ++@bye ++ ++@c End: ++ ++@ignore ++ arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3 ++@end ignore +diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi +new file mode 100644 +index 0000000..848da3e +--- /dev/null ++++ b/doc/misc/smtpmail.texi +@@ -0,0 +1,421 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/smtpmail ++@settitle Emacs SMTP Library ++@syncodeindex vr fn ++@copying ++Copyright @copyright{} 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++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 Emacs ++@direntry ++* SMTP: (smtpmail). Emacs library for sending mail via SMTP. ++@end direntry ++ ++@titlepage ++@title{Emacs SMTP Library} ++@subtitle{An Emacs package for sending mail via SMTP} ++@author{Simon Josefsson, Alex Schroeder} ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top ++@top Emacs SMTP Library ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* How Mail Works:: Brief introduction to mail concepts. ++* Emacs Speaks SMTP:: How to use the SMTP library in Emacs. ++* Authentication:: Authenticating yourself to the server. ++* Queued delivery:: Sending mail without an internet connection. ++* Server workarounds:: Mail servers with special requirements. ++* Debugging:: Tracking down problems. ++* GNU Free Documentation License:: The license for this documentation. ++ ++Indices ++ ++* Index:: Index over variables and functions. ++@end menu ++ ++@node How Mail Works ++@chapter How Mail Works ++ ++@cindex SMTP ++@cindex MTA ++ On the internet, mail is sent from mail host to mail host using the ++simple mail transfer protocol (SMTP). To send and receive mail, you ++must get it from and send it to a mail host. Every mail host runs a ++mail transfer agent (MTA) such as Exim that accepts mails and passes ++them on. The communication between a mail host and other clients does ++not necessarily involve SMTP, however. Here is short overview of what ++is involved. ++ ++@cindex MUA ++ The mail program --- also called a mail user agent (MUA) --- ++usually sends outgoing mail to a mail host. When your computer is ++permanently connected to the internet, it might even be a mail host ++itself. In this case, the MUA will pipe mail to the ++@file{/usr/lib/sendmail} application. It will take care of your mail ++and pass it on to the next mail host. ++ ++@cindex ISP ++ When you are only connected to the internet from time to time, your ++internet service provider (ISP) has probably told you which mail host ++to use. You must configure your MUA to use that mail host. Since you ++are reading this manual, you probably want to configure Emacs to use ++SMTP to send mail to that mail host. More on that in the next ++section. ++ ++@cindex MDA ++ Things are different when reading mail. The mail host responsible ++for your mail keeps it in a file somewhere. The messages get into the ++file by way of a mail delivery agent (MDA) such as procmail. These ++delivery agents often allow you to filter and munge your mails before ++you get to see it. When your computer is that mail host, this file is ++called a spool, and sometimes located in the directory ++@file{/var/spool/mail/}. All your MUA has to do is read mail from the ++spool, then. ++ ++@cindex POP3 ++@cindex IMAP ++ When your computer is not always connected to the internet, you ++must get the mail from the remote mail host using a protocol such as ++POP3 or IMAP. POP3 essentially downloads all your mail from the mail ++host to your computer. The mail is stored in some file on your ++computer, and again, all your MUA has to do is read mail from the ++spool. ++ ++ When you read mail from various machines, downloading mail from the ++mail host to your current machine is not convenient. In that case, ++you will probably want to use the IMAP protocol. Your mail is kept on ++the mail host, and you can read it while you are connected via IMAP to ++the mail host. ++ ++@cindex Webmail ++ So how does reading mail via the web work, you ask. In that case, ++the web interface just allows you to remote-control a MUA on the web ++host. Whether the web host is also a mail host, and how all the ++pieces interact is completely irrelevant. You usually cannot use ++Emacs to read mail via the web, unless you use software that parses ++the ever-changing HTML of the web interface. ++ ++@node Emacs Speaks SMTP ++@chapter Emacs Speaks SMTP ++ ++ Emacs includes a package for sending your mail to a SMTP server and ++have it take care of delivering it to the final destination, rather ++than letting the MTA on your local system take care of it. This can ++be useful if you don't have a MTA set up on your host, or if your ++machine is often disconnected from the internet. ++ ++ Sending mail via SMTP requires configuring your mail user agent ++(@pxref{Mail Methods,,,emacs}) to use the SMTP library. How to do ++this should be described for each mail user agent; for the default ++mail user agent the variable @code{send-mail-function} (@pxref{Mail ++Sending,,,emacs}) is used; for the Message and Gnus user agents the ++variable @code{message-send-mail-function} (@pxref{Mail ++Variables,,,message}) is used. ++ ++@example ++;; If you use the default mail user agent. ++(setq send-mail-function 'smtpmail-send-it) ++;; If you use Message or Gnus. ++(setq message-send-mail-function 'smtpmail-send-it) ++@end example ++ ++ Before using SMTP you must find out the hostname of the SMTP server ++to use. Your system administrator should provide you with this ++information, but often it is the same as the server you receive mail ++from. ++ ++@table @code ++@item smtpmail-smtp-server ++@vindex smtpmail-smtp-server ++@vindex SMTPSERVER ++ The variable @code{smtpmail-smtp-server} controls the hostname of ++the server to use. It is a string with an IP address or hostname. It ++defaults to the contents of the @env{SMTPSERVER} environment ++variable, or, if empty, the contents of ++@code{smtpmail-default-smtp-server}. ++ ++@item smtpmail-default-smtp-server ++@vindex smtpmail-default-smtp-server ++ The variable @code{smtpmail-default-smtp-server} controls the ++default hostname of the server to use. It is a string with an IP ++address or hostname. It must be set before the SMTP library is ++loaded. It has no effect if set after the SMTP library has been ++loaded, or if @code{smtpmail-smtp-server} is defined. It is usually ++set by system administrators in a site wide initialization file. ++@end table ++ ++The following example illustrates what you could put in ++@file{~/.emacs} to set the SMTP server name. ++ ++@example ++;; Send mail using SMTP via mail.example.org. ++(setq smtpmail-smtp-server "mail.example.org") ++@end example ++ ++@cindex Mail Submission ++SMTP is normally used on the registered ``smtp'' TCP service port 25. ++Some environments use SMTP in ``Mail Submission'' mode, which uses ++port 587. Using other ports is not uncommon, either for security by ++obscurity purposes, port forwarding, or otherwise. ++ ++@table @code ++@item smtpmail-smtp-service ++@vindex smtpmail-smtp-service ++ The variable @code{smtpmail-smtp-service} controls the port on the ++server to contact. It is either a string, in which case it will be ++translated into an integer using system calls, or an integer. ++@end table ++ ++The following example illustrates what you could put in ++@file{~/.emacs} to set the SMTP service port. ++ ++@example ++;; Send mail using SMTP on the mail submission port 587. ++(setq smtpmail-smtp-service 587) ++@end example ++ ++@node Authentication ++@chapter Authentication ++ ++@cindex SASL ++@cindex CRAM-MD5 ++@cindex LOGIN ++@cindex STARTTLS ++@cindex TLS ++@cindex SSL ++Many environments require SMTP clients to authenticate themselves ++before they are allowed to route mail via a server. The two following ++variables contains the authentication information needed for this. ++ ++The first variable, @code{smtpmail-auth-credentials}, instructs the ++SMTP library to use a SASL authentication step, currently only the ++CRAM-MD5 and LOGIN mechanisms are supported and will be selected in ++that order if the server support both. ++ ++The second variable, @code{smtpmail-starttls-credentials}, instructs ++the SMTP library to connect to the server using STARTTLS. This means ++the protocol exchange may be integrity protected and confidential by ++using the Transport Layer Security (TLS) protocol, and optionally also ++authentication of the client and server. ++ ++TLS is a security protocol that is also known as SSL, although ++strictly speaking, SSL is an older variant of TLS. TLS is backwards ++compatible with SSL. In most mundane situations, the two terms are ++equivalent. ++ ++The TLS feature uses the elisp package @file{starttls.el} (see it for ++more information on customization), which in turn require that at ++least one of the following external tools are installed: ++ ++@enumerate ++@item ++The GNUTLS command line tool @samp{gnutls-cli}, you can get it from ++@url{http://www.gnu.org/software/gnutls/}. This is the recommended ++tool, mainly because it can verify the server certificates. ++ ++@item ++The @samp{starttls} external program, you can get it from ++@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}. ++@end enumerate ++ ++It is not uncommon to use both these mechanisms, e.g., to use STARTTLS ++to achieve integrity and confidentiality and then use SASL for client ++authentication. ++ ++@table @code ++@item smtpmail-auth-credentials ++@vindex smtpmail-auth-credentials ++ The variable @code{smtpmail-auth-credentials} contains a list of ++hostname, port, username and password tuples. When the SMTP library ++connects to a host on a certain port, this variable is searched to ++find a matching entry for that hostname and port. If an entry is ++found, the authentication process is invoked and the credentials are ++used. ++ ++The hostname field follows the same format as ++@code{smtpmail-smtp-server} (i.e., a string) and the port field the ++same format as @code{smtpmail-smtp-service} (i.e., a string or an ++integer). The username and password fields, which either can be ++@code{nil} to indicate that the user is prompted for the value ++interactively, should be strings with the username and password, ++respectively, information that is normally provided by system ++administrators. ++ ++@item smtpmail-starttls-credentials ++@vindex smtpmail-starttls-credentials ++ The variable @code{smtpmail-starttls-credentials} contains a list of ++tuples with hostname, port, name of file containing client key, and ++name of file containing client certificate. The processing is similar ++to the previous variable. The client key and certificate may be ++@code{nil} if you do not wish to use client authentication. ++@end table ++ ++The following example illustrates what you could put in ++@file{~/.emacs} to enable both SASL authentication and STARTTLS. The ++server name (@code{smtpmail-smtp-server}) is @var{hostname}, the ++server port (@code{smtpmail-smtp-service}) is @var{port}, and the ++username and password are @var{username} and @var{password} ++respectively. ++ ++@example ++;; Authenticate using this username and password against my server. ++(setq smtpmail-auth-credentials ++ '(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}"))) ++ ++;; Note that if @var{port} is an integer, you must not quote it as a ++;; string. Normally @var{port} should be the integer 25, and the example ++;; become: ++(setq smtpmail-auth-credentials ++ '(("@var{hostname}" 25 "@var{username}" "@var{password}"))) ++ ++;; Use STARTTLS without authentication against the server. ++(setq smtpmail-starttls-credentials ++ '(("@var{hostname}" "@var{port}" nil nil))) ++@end example ++ ++@node Queued delivery ++@chapter Queued delivery ++ ++@cindex Dialup connection ++If you connect to the internet via a dialup connection, or for some ++other reason don't have permanent internet connection, sending mail ++will fail when you are not connected. The SMTP library implements ++queued delivery, and the following variable control its behavior. ++ ++@table @code ++@item smtpmail-queue-mail ++@vindex smtpmail-queue-mail ++ The variable @code{smtpmail-queue-mail} controls whether a simple ++off line mail sender is active. This variable is a boolean, and ++defaults to @code{nil} (disabled). If this is non-@code{nil}, mail is ++not sent immediately but rather queued in the directory ++@code{smtpmail-queue-dir} and can be later sent manually by invoking ++@code{smtpmail-send-queued-mail} (typically when you connect to the ++internet). ++ ++@item smtpmail-queue-dir ++@vindex smtpmail-queue-dir ++ The variable @code{smtpmail-queue-dir} specifies the name of the ++directory to hold queued messages. It defaults to ++@file{~/Mail/queued-mail/}. ++@end table ++ ++@findex smtpmail-send-queued-mail ++ The function @code{smtpmail-send-queued-mail} can be used to send ++any queued mail when @code{smtpmail-queue-mail} is enabled. It is ++typically invoked interactively with @kbd{M-x ++smtpmail-send-queued-mail RET} when you are connected to the internet. ++ ++@node Server workarounds ++@chapter Server workarounds ++ ++Some SMTP servers have special requirements. The following variables ++implement support for common requirements. ++ ++@table @code ++ ++@item smtpmail-local-domain ++@vindex smtpmail-local-domain ++ The variable @code{smtpmail-local-domain} controls the hostname sent ++in the first @code{EHLO} or @code{HELO} command sent to the server. ++It should only be set if the @code{system-name} function returns a ++name that isn't accepted by the server. Do not set this variable ++unless your server complains. ++ ++@item smtpmail-sendto-domain ++@vindex smtpmail-sendto-domain ++ The variable @code{smtpmail-sendto-domain} makes the SMTP library ++add @samp{@@} and the specified value to recipients specified in the ++message when they are sent using the @code{RCPT TO} command. Some ++configurations of sendmail requires this behavior. Don't bother to ++set this unless you have get an error like: ++ ++@example ++ Sending failed; SMTP protocol error ++@end example ++ ++when sending mail, and the debug buffer (@pxref{Debugging})) contains ++an error such as: ++ ++@example ++ RCPT TO: @var{someone} ++ 501 @var{someone}: recipient address must contain a domain ++@end example ++ ++@end table ++ ++ ++@node Debugging ++@chapter Debugging ++ ++Sometimes delivery fails, often with the generic error message ++@samp{Sending failed; SMTP protocol error}. Enabling one or both of ++the following variables and inspecting a trace buffer will often give ++clues to the reason for the error. ++ ++@table @code ++ ++@item smtpmail-debug-info ++@vindex smtpmail-debug-info ++ The variable @code{smtpmail-debug-info} controls whether to print ++the SMTP protocol exchange in the minibuffer, and retain the entire ++exchange in a buffer @samp{*trace of SMTP session to @var{server}*}, ++where @var{server} is the name of the mail server to which you send ++mail. ++ ++@item smtpmail-debug-verb ++@vindex smtpmail-debug-verb ++ The variable @code{smtpmail-debug-verb} controls whether to send the ++@code{VERB} token to the server. The @code{VERB} server instructs the ++server to be more verbose, and often also to attempt final delivery ++while your SMTP session is still running. It is usually only useful ++together with @code{smtpmail-debug-info}. Note that this may cause ++mail delivery to take considerable time if the final destination ++cannot accept mail. ++ ++@end table ++ ++@node GNU Free Documentation License ++@chapter GNU Free Documentation License ++@include doclicense.texi ++ ++@node Index ++@chapter Index ++ ++@section Concept Index ++ ++@printindex cp ++ ++@section Function and Variable Index ++ ++@printindex fn ++ ++@bye ++ ++@ignore ++ arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f ++@end ignore +diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi +new file mode 100644 +index 0000000..2e6e273 +--- /dev/null ++++ b/doc/misc/speedbar.texi +@@ -0,0 +1,1259 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/speedbar ++@settitle Speedbar: File/Tag summarizing utility ++@syncodeindex fn cp ++ ++@copying ++Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, ++2007, 2008, 2009 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 Emacs ++@direntry ++* Speedbar: (speedbar). File/Tag summarizing utility. ++@end direntry ++ ++@titlepage ++@sp 10 ++@center @titlefont{Speedbar} ++@sp 2 ++@center Eric Ludlam ++@vskip 0pt plus 1 fill ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top, , , (dir)Top ++@comment node-name, next, previous, up ++ ++Speedbar is a program for Emacs which can be used to summarize ++information related to the current buffer. Its original inspiration ++is the `explorer' often used in modern development environments, office ++packages, and web browsers. ++ ++Speedbar displays a narrow frame in which a tree view is shown. This ++tree view defaults to containing a list of files and directories. Files ++can be `expanded' to list tags inside. Directories can be expanded to ++list the files within itself. Each file or tag can be jumped to ++immediately. ++ ++Speedbar expands upon `explorer' windows by maintaining context with the ++user. For example, when using the file view, the current buffer's file ++is highlighted. Speedbar also mimics the explorer windows by providing ++multiple display modes. These modes come in two flavors. Major display ++modes remain consistent across buffers, and minor display modes appear ++only when a buffer of the applicable type is shown. This allows ++authors of other packages to provide speedbar summaries customized to ++the needs of that mode. ++ ++Throughout this manual, activities are defined as `clicking on', or ++`expanding' items. Clicking means using @kbd{Mouse-2} on a ++button. Expanding refers to clicking on an expansion button to display ++an expanded summary of the entry the expansion button is ++on. @xref{Basic Navigation}. ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Introduction:: Basics of speedbar. ++* Basic Navigation:: Basics of speedbar common between all modes. ++* File Mode:: Summarizing files. ++* Buffer Mode:: Summarizing buffers. ++* Minor Modes:: Additional minor modes such as Info and RMAIL. ++* Customizing:: Changing speedbar behavior. ++* Extending:: Extend speedbar for your own project. ++* GNU Free Documentation License:: The license for this documentation. ++* Index:: ++@end menu ++ ++@node Introduction, Basic Navigation, , Top ++@comment node-name, next, previous, up ++@chapter Introduction ++@cindex introduction ++ ++To start using speedbar use the command @kbd{M-x speedbar RET} or ++select it from the @samp{Options->Show/Hide} sub-menu. This command ++will open a new frame to summarize the local files. On X Window ++systems or on MS-Windows, speedbar's frame is twenty characters wide, ++and will mimic the height of the frame from which it was started. It ++positions itself to the left or right of the frame you started it ++from. ++ ++To use speedbar effectively, it is important to understand its ++relationship with the frame you started it from. This frame is the ++@dfn{attached frame} which speedbar will use as a reference point. Once ++started, speedbar watches the contents of this frame, and attempts to ++make its contents relevant to the buffer loaded into the attached ++frame. In addition, all requests made in speedbar that require the ++display of another buffer will display in the attached frame. ++ ++When used in terminal mode, the new frame appears the same size as the ++terminal. Since it is not visible while working in the attached frame, ++speedbar will save time by using the @dfn{slowbar mode}, where no tracking is ++done until speedbar is requested to show itself (i.e., the speedbar's ++frame becomes the selected frame). ++ ++@cindex @code{speedbar-get-focus} ++The function to use when switching between frames using the keyboard is ++@code{speedbar-get-focus}. This function will toggle between frames, and ++it's useful to bind it to a key in terminal mode. @xref{Customizing}. ++ ++@node Basic Navigation, File Mode, Introduction, Top ++@comment node-name, next, previous, up ++@chapter Basic Navigation ++ ++Speedbar can display different types of data, and has several display ++and behavior modes. These modes all have a common behavior, menu ++system, and look. If one mode is learned, then the other modes are easy ++to use. ++ ++@menu ++* Basic Key Bindings:: ++* Basic Visuals:: ++* Mouse Bindings:: ++* Displays Submenu:: ++@end menu ++ ++@node Basic Key Bindings, Basic Visuals, Basic Navigation, Basic Navigation ++@comment node-name, next, previous, up ++@section Basic Key Bindings ++@cindex key bindings ++ ++These key bindings are common across all modes: ++ ++@table @kbd ++@item Q ++@cindex quitting speedbar ++Quit speedbar, and kill the frame. ++@item q ++Quit speedbar, and hide the frame. This makes it faster to restore the ++speedbar frame, than if you press @kbd{Q}. ++@item g ++@cindex refresh speedbar display ++Refresh whatever contents are in speedbar. ++@item t ++@cindex slowbar mode ++Toggle speedbar to and from slowbar mode. In slowbar mode, frame ++tracking is not done. ++@item n ++@itemx p ++@cindex navigation ++Move, respectively, to the next or previous item. A summary of that ++item will be displayed in the attached frame's minibuffer. ++@item M-n ++@itemx M-p ++Move to the next or previous item in a restricted fashion. If a list is ++open, the cursor will skip over it. If the cursor is in an open list, ++it will not leave it. ++@item C-M-n ++@itemx C-M-n ++Move forwards and backwards across extended groups. This lets you ++quickly skip over all files, directories, or other common sub-items at ++the same current depth. ++@item C-x b ++Switch buffers in the attached frame. ++@end table ++ ++Speedbar can handle multiple modes. Two are provided by default. ++These modes are File mode, and Buffers mode. There are accelerators to ++switch into these different modes. ++ ++@cindex mode switching hotkeys ++@table @kbd ++@item b ++Switch into Quick Buffers mode (@pxref{Buffer Mode}). After one use, the ++previous display mode is restored. ++@item f ++Switch into File mode. ++@item r ++Switch back to the previous mode. ++@end table ++ ++Some modes provide groups, lists and tags. @xref{Basic Visuals}. When ++these are available, some additional common bindings are available. ++ ++@cindex common keys ++@table @kbd ++@item RET ++@itemx e ++Edit/Open the current group or tag. This behavior is dependent on the ++mode. In general, files or buffers are opened in the attached frame, ++and directories or group nodes are expanded locally. ++@item + ++@itemx = ++Expand the current group, displaying sub items. ++When used with a prefix argument, any data that may have been cached is ++flushed. This is similar to a power click. @xref{Mouse Bindings}. ++@item - ++Contract the current group, hiding sub items. ++@end table ++ ++@node Basic Visuals, Mouse Bindings, Basic Key Bindings, Basic Navigation ++@comment node-name, next, previous, up ++@section Basic Visuals ++@cindex visuals ++ ++Speedbar has visual cues for indicating different types of data. These ++cues are used consistently across the different speedbar modes to make ++them easier to interpret. ++ ++At a high level, in File mode, there are directory buttons, sub ++directory buttons, file buttons, tag buttons, and expansion buttons. ++This makes it easy to use the mouse to navigate a directory tree, and ++quickly view files, or a summary of those files. ++ ++The most basic visual effect used to distinguish between these button ++types is color and mouse highlighting. Anything the mouse highlights ++can be clicked on and is called a button (@pxref{Mouse Bindings}). ++Anything not highlighted by the mouse will not be clickable. ++ ++Text in speedbar consists of four different types of data. Knowing how ++to read these textual elements will make it easier to navigate by ++identifying the types of data available. ++ ++@subsubsection Groups ++@cindex groups ++ ++Groups summarize information in a single line, and provide a high level ++view of more complex systems, like a directory tree, or manual chapters. ++ ++Groups appear at different indentation levels, and are prefixed with a ++@samp{+} in some sort of `box'. The group name will summarize the ++information within it, and the expansion box will display that ++information inline. In File mode, directories and files are `groups' ++where the @samp{+} is surrounded by brackets like this: ++ ++@example ++<+> include ++<-> src ++ [+] foo.c ++@end example ++ ++In this example, we see both open and closed directories, in addition to ++a file. The directories have a box consisting of angle brackets, and a ++file uses square brackets. ++ ++In all modes, a group can be `edited' by pressing @kbd{RET}, meaning a ++file will be opened, or a directory explicitly opened in speedbar. A ++group can be expanded or contracted using @kbd{+} or ++@kbd{-}. @xref{Basic Key Bindings}. ++ ++Sometimes groups may have a @samp{?} in its indicator box. This means ++that it is a group type, but there are no contents, or no known way of ++extracting contents of that group. ++ ++When a group has been expanded, the indicator button changes from ++@samp{+} to @samp{-}. This indicates that the contents are being shown. ++Click the @samp{-} button to contract the group, or hide the contents ++currently displayed. ++ ++@subsubsection Tags ++@cindex tags ++ ++Tags are the leaf nodes of the tree system. Tags are generally prefixed ++with a simple character, such as @samp{>}. Tags can only be jumped to using ++@kbd{RET} or @kbd{e}. ++ ++@subsubsection Boolean Flags ++ ++Sometimes a group or tag is given a boolean flag. These flags appear as ++extra text characters at the end of the line. File mode uses boolean ++flags, such as a @samp{*} to indicate that a file has been checked out ++of a versioning system. ++ ++For additional flags, see ++@c Note to self, update these to sub-nodes which are more relevant. ++@ref{File Mode}, and @ref{Version Control}. ++ ++@subsubsection Unadorned Text ++ ++Unadorned text generally starts in column 0, without any special symbols ++prefixing them. In Buffers mode different buffer groups are prefixed ++with a description of what the following buffers are (Files, scratch ++buffers, and invisible buffers.) ++ ++Unadorned text will generally be colorless, and not clickable. ++ ++@subsubsection Color Cues ++ ++Each type of Group, item indicator, and label is given a different ++color. The colors chosen are dependent on whether the background color ++is light or dark. ++Of important note is that the `current item', which may be a buffer or ++file name, is highlighted red, and underlined. ++ ++Colors can be customized from the group @code{speedbar-faces}. Some ++modes, such as for Info, will use the Info colors instead of default ++speedbar colors as an indication of what is currently being displayed. ++ ++The face naming convention mirrors the File display mode. Modes which ++do not use files will attempt to use the same colors on analogous ++entries. ++ ++@node Mouse Bindings, Displays Submenu, Basic Visuals, Basic Navigation ++@comment node-name, next, previous, up ++@section Mouse Bindings ++@cindex mouse bindings ++ ++The mouse has become a common information navigation tool. Speedbar ++will use the mouse to navigate file systems, buffer lists, and other ++data. The different textual cues provide buttons which can be clicked ++on (@pxref{Basic Visuals}). Anything that highlights can be clicked on ++with the mouse, or affected by the menu. ++ ++The mouse bindings are: ++ ++@table @kbd ++@item Mouse-1 ++Move cursor to that location. ++@item Mouse-2 ++@itemx Double-Mouse-1 ++Activate the current button. @kbd{Double-Mouse-1} is called a @dfn{double ++click} on other platforms, and is useful for windows users with two ++button mice. ++@c Isn't it true that with two-button mice, the right button is Mouse-2? ++@c On GNU/Linux, the right button is Mouse-3. ++@item S-Mouse-2 ++@itemx S-Double-Mouse-1 ++@cindex power click ++This has the same effect as @kbd{Mouse-2}, except it is called a power ++click. This means that if a group with an expansion button @samp{+} is ++clicked, any caches are flushed, and subitems re-read. If it is a name, ++it will be opened in a new frame. ++@item Mouse-3 ++Activate the speedbar menu. The item selected affects the line clicked, ++not the line where the cursor was. ++@item Mouse-1 @r{(mode line)} ++Activate the menu. This affects the item the cursor is on before the ++click, since the mouse was not clicked on anything. ++@item C-Mouse-1 ++Buffers sub-menu. The buffer in the attached frame is switched. ++@end table ++ ++When the mouse moves over buttons in speedbar, details of that item ++should be displayed in the minibuffer of the attached frame. Sometimes ++this can contain extra information such as file permissions, or tag ++location. ++ ++@node Displays Submenu, , Mouse Bindings, Basic Navigation ++@comment node-name, next, previous, up ++@section Displays Submenu ++@cindex displays submenu ++ ++You can display different data by using different display modes. These ++specialized modes make it easier to navigate the relevant pieces of ++information, such as files and directories, or buffers. ++ ++In the main menu, found by clicking @kbd{Mouse-3}, there is a submenu ++labeled @samp{Displays}. This submenu lets you easily choose between ++different display modes. ++ ++The contents are modes currently loaded into emacs. By default, this ++would include Files, Quick Buffers, and Buffers. Other major display ++modes such as Info are loaded separately. ++ ++@node File Mode, Buffer Mode, Basic Navigation, Top ++@comment node-name, next, previous, up ++@chapter File Mode ++@cindex file mode ++ ++File mode displays a summary of your current directory. You can display ++files in the attached frame, or summarize the tags found in files. You ++can even see if a file is checked out of a version control system, or ++has some associated object file. ++ ++Advanced behavior, like copying and renaming files, is also provided. ++ ++@menu ++* Directory Display:: What the display means. ++* Hidden Files:: How to display hidden files. ++* File Key Bindings:: Performing file operations. ++@end menu ++ ++@node Directory Display, Hidden Files, File Mode, File Mode ++@comment node-name, next, previous, up ++@section Directory Display ++@cindex directory display ++ ++There are three major sections in the display. The first line or two is ++the root directory speedbar is currently viewing. You can jump to one ++of the parent directories by clicking on the name of the directory you ++wish to jump to. ++ ++Next, directories are listed. A directory starts with the group ++indicator button @samp{<+>}. Clicking the directory name makes speedbar ++load that directory as the root directory for its display. Clicking the ++@samp{<+>} button will list all directories and files beneath. ++ ++Next, files are listed. Files start with the group indicator @samp{[+]} ++or @samp{[?]}. You can jump to a file in the attached frame by clicking ++on the file name. You can expand a file and look at its tags by ++clicking on the @samp{[+]} symbol near the file name. ++ ++A typical session might look like this: ++ ++@example ++~/lisp/ ++<+> checkdoc ++<+> eieio ++<-> speedbar ++ [+] Makefile ++ [+] rpm.el # ++ [+] sb-gud.el # ++ [+] sb-info.el # ++ [+] sb-rmail.el # ++ [+] sb-w3.el ++ [-] speedbar.el *! ++ @{+@} Types ++ @{+@} Variables ++ @{+@} def (group) ++ @{+@} speedbar- ++ [+] speedbar.texi * ++<+> testme ++[+] align.el ++[+] autoconf.el ++@end example ++ ++In this example, you can see several directories. The directory ++@file{speedbar} has been opened inline. Inside the directory ++@file{speedbar}, the file @file{speedbar.el} has its tags exposed. ++These tags are extensive, and they are summarized into tag groups. ++ ++Files get additional boolean flags associated with them. Valid flags are: ++ ++@cindex file flags ++@table @code ++@item * ++This file has been checked out of a version control ++system. @xref{Version Control}. ++@cindex @code{speedbar-obj-alist} ++@item # ++This file has an up to date object file associated with it. The ++variable @code{speedbar-obj-alist} defines how speedbar determines this ++value. ++@item ! ++This file has an out of date object file associated with it. ++@end table ++ ++A Tag group is prefixed with the symbol @samp{@{+@}}. Clicking this ++symbol will show all symbols that have been organized into that group. ++Different types of files have unique tagging methods as defined by their ++major mode. Tags are generated with either the @code{imenu} package, or ++through the @code{etags} interface. ++ ++Tag groups are defined in multiple ways which make it easier to find the ++tag you are looking for. Imenu keywords explicitly create groups, and ++speedbar will automatically create groups if tag lists are too long. ++ ++In our example, Imenu created the groups @samp{Types} and ++@samp{Variables}. All remaining top-level symbols are then regrouped ++based on the variable @code{speedbar-tag-hierarchy-method}. The ++subgroups @samp{def} and @samp{speedbar-} are groupings where the first ++few characters of the given symbols are specified in the group name. ++Some group names may say something like @samp{speedbar-t to speedbar-v}, ++indicating that all symbols which alphabetically fall between those ++categories are included in that sub-group. @xref{Tag Hierarchy Methods}. ++ ++@node Hidden Files, File Key Bindings, Directory Display, File Mode ++@comment node-name, next, previous, up ++@section Hidden Files ++@cindex hidden files ++ ++On GNU and Unix systems, a hidden file is a file whose name starts ++with a period. They are hidden from a regular directory listing ++because the user is not generally interested in them. ++ ++In speedbar, a hidden file is a file which isn't very interesting and ++might prove distracting to the user. Any uninteresting files are ++removed from the File display. There are two levels of uninterest in ++speedbar. The first level of uninterest are files which have no ++expansion method, or way of extracting tags. The second level is any ++file that matches the same pattern used for completion in ++@code{find-file}. This is derived from the variable ++@code{completion-ignored-extensions}. ++ ++You can toggle the display of uninteresting files from the toggle menu ++item @samp{Show All Files}. This will display all level one hidden files. ++These files will be shown with a @samp{?} indicator. Level 2 hidden ++files will still not be shown. ++ ++Object files fall into the category of level 2 hidden files. You can ++determine their presence by the @samp{#} and @samp{!} file indicators. ++@xref{Directory Display}. ++ ++@node File Key Bindings, , Hidden Files, File Mode ++@comment node-name, next, previous, up ++@section File Key Bindings ++@cindex file key bindings ++ ++File mode has key bindings permitting different file system operations ++such as copy or rename. These commands all operate on the @dfn{current ++file}. In this case, the current file is the file at point, or clicked ++on when pulling up the menu. ++ ++@table @kbd ++@item U ++Move the entire speedbar display up one directory. ++@item I ++Display information in the minibuffer about this line. This is the same ++information shown when navigating with @kbd{n} and @kbd{p}, or moving ++the mouse over an item. ++@item B ++Byte compile the Emacs Lisp file on this line. ++@item L ++Load the Emacs Lisp file on this line. If a @file{.elc} file exists, ++optionally load that. ++@item C ++Copy the current file to some other location. ++@item R ++Rename the current file, possibly moving it to some other location. ++@item D ++Delete the current file. ++@item O ++Delete the current file's object file. Use the symbols @samp{#} and ++@samp{!} to determine if there is an object file available. ++@end table ++ ++One menu item toggles the display of all available files. By default, ++only files which Emacs understands, and knows how to convert into a tag ++list, are shown. By showing all files, additional files such as text files are ++also displayed, but they are prefixed with the @samp{[?]} symbol. This ++means that it is a file, but Emacs doesn't know how to expand it. ++ ++@node Buffer Mode, Minor Modes, File Mode, Top ++@comment node-name, next, previous, up ++@chapter Buffer Mode ++@cindex buffer mode ++ ++Buffer mode is very similar to File mode, except that instead of ++tracking the current directory and all files available there, the ++current list of Emacs buffers is shown. ++ ++These buffers can have their tags expanded in the same way as files, ++and uses the same unknown file indicator (@pxref{File Mode}). ++ ++Buffer mode does not have file operation bindings, but the following ++buffer specific key bindings are available: ++ ++@table @kbd ++@item k ++Kill this buffer. Do not touch its file. ++@item r ++Revert this buffer, reloading from disk. ++@end table ++ ++In addition to Buffer mode, there is also Quick Buffer mode. In fact, ++Quick Buffers is bound to the @kbd{b} key. The only difference between ++Buffers and Quick Buffers is that after one operation is performed ++which affects the attached frame, the display is immediately reverted to ++the last displayed mode. ++ ++Thus, if you are in File mode, and you need quick access to a buffer, ++press @kbd{b}, click on the buffer you want, and speedbar will revert ++back to File mode. ++ ++@node Minor Modes, Customizing, Buffer Mode, Top ++@comment node-name, next, previous, up ++@chapter Minor Display Modes ++@cindex minor display modes ++ ++For some buffers, a list of files and tags makes no sense. This could ++be because files are not currently in reference (such as web pages), or ++that the files you might be interested have special properties (such as ++email folders.) ++ ++In these cases, a minor display mode is needed. A minor display mode ++will override any major display mode currently being displayed for the ++duration of the specialized buffer's use. Minor display modes ++will follow the general rules of their major counterparts in terms of ++key bindings and visuals, but will have specialized behaviors. ++ ++@menu ++* RMAIL:: Managing folders. ++* Info:: Browsing topics. ++* GDB:: Watching expressions or managing the current ++ stack trace. ++@end menu ++ ++@node RMAIL, Info, Minor Modes, Minor Modes ++@comment node-name, next, previous, up ++@section RMAIL ++@cindex RMAIL ++ ++When using RMAIL, speedbar will display two sections. The first is a ++layer one reply button. Clicking here will initialize a reply buffer ++showing only this email address in the @samp{To:} field. ++ ++The second section lists all RMAIL folders in the same directory as your ++main RMAIL folder. The general rule is that RMAIL folders always appear ++in all caps, or numbers. It is possible to save mail in folders with ++lower case letters, but there is no clean way of detecting such RMAIL folders ++without opening them all. ++ ++Each folder can be visited by clicking the name. You can move mail from ++the current RMAIL folder into a different folder by clicking the ++@samp{} button. The @samp{M} stands for Move. ++ ++In this way you can manage your existing RMAIL folders fairly easily ++using the mouse. ++ ++@node Info, GDB, RMAIL, Minor Modes ++@comment node-name, next, previous, up ++@section Info ++@cindex Info ++ ++When browsing Info files, all local relevant information is displayed in ++the info buffer and a topical high-level view is provided in speedbar. ++All top-level info nodes are shown in the speedbar frame, and can be ++jumped to by clicking the name. ++ ++You can open these nodes with the @samp{[+]} button to see what sub-topics ++are available. Since these sub-topics are not examined until you click ++the @samp{[+]} button, sometimes a @samp{[?]} will appear when you click on ++a @samp{[+]}, indicating that there are no sub-topics. ++ ++@node GDB, , Info, Minor Modes ++@comment node-name, next, previous, up ++@section GDB ++@cindex gdb ++@cindex gud ++ ++You can debug an application with GDB in Emacs using graphical mode or ++text command mode (@pxref{GDB Graphical Interface,,, emacs, The ++extensible self-documenting text editor}). ++ ++If you are using graphical mode you can see how selected variables ++change each time your program stops (@pxref{Watch Expressions,,, ++emacs, The extensible self-documenting text editor}). ++ ++If you are using text command mode, speedbar can show ++you the current stack when the current buffer is the @file{*gdb*} ++buffer. Usually, it will just report that there is no stack, but when ++the application is stopped, the current stack will be shown. ++ ++You can click on any stack element and gdb will move to that stack ++level. You can then check variables local to that level at the GDB ++prompt. ++ ++@node Customizing, Extending, Minor Modes, Top ++@comment node-name, next, previous, up ++@chapter Customizing ++@cindex customizing ++ ++Speedbar is highly customizable, with a plethora of control elements. ++Since speedbar is so visual and reduces so much information, this is an ++important aspect of its behavior. ++ ++In general, there are three custom groups you can use to quickly modify ++speedbar's behavior. ++ ++@table @code ++@item speedbar ++Basic speedbar behaviors. ++@item speedbar-vc ++Customizations regarding version control handling. ++@item speedbar-faces ++Customize speedbar's many colors and fonts. ++@end table ++ ++@menu ++* Frames and Faces:: Visible behaviors. ++* Tag Hierarchy Methods:: Customizing how tags are displayed. ++* Version Control:: Adding new VC detection modes. ++* Hooks:: The many hooks you can use. ++@end menu ++ ++@node Frames and Faces, Tag Hierarchy Methods, Customizing, Customizing ++@comment node-name, next, previous, up ++@section Frames and Faces ++@cindex faces ++@cindex frame parameters ++ ++There are several faces speedbar generates to provide a consistent ++color scheme across display types. You can customize these faces using ++your favorite method. They are: ++ ++@table @asis ++@cindex @code{speedbar-button-face} ++@item speedbar-button-face ++Face used on expand/contract buttons. ++@cindex @code{speedbar-file-face} ++@item speedbar-file-face ++Face used on Files. Should also be used on non-directory like nodes. ++@cindex @code{speedbar-directory-face} ++@item speedbar-directory-face ++Face used for directories, or nodes which consist of groups of other nodes. ++@cindex @code{speedbar-tag-face} ++@item speedbar-tag-face ++Face used for tags in a file, or for leaf items. ++@cindex @code{speedbar-selected-face} ++@item speedbar-selected-face ++Face used to highlight the selected item. This would be the current ++file being edited. ++@cindex @code{speedbar-highlight-face} ++@item speedbar-highlight-face ++Face used when the mouse passes over a button. ++@end table ++ ++You can also customize speedbar's initial frame parameters. How this is ++accomplished is dependent on your platform being Emacs or XEmacs. ++ ++@cindex @code{speedbar-frame-parameters}, Emacs ++In Emacs, change the alist @code{speedbar-frame-parameters}. This ++variable is used to set up initial details. Height is also ++automatically added when speedbar is created, though you can override ++it. ++ ++@cindex @code{speedbar-frame-plist}, XEmacs ++In XEmacs, change the plist @code{speedbar-frame-plist}. This is the ++XEmacs way of doing the same thing. ++ ++@node Tag Hierarchy Methods, Version Control, Frames and Faces, Customizing ++@comment node-name, next, previous, up ++@section Tag Hierarchy Methods ++@cindex tag hierarchy ++@cindex tag groups ++@cindex tag sorting ++ ++When listing tags within a file, it is possible to get an annoyingly ++long list of entries. Imenu (which generates the tag list in Emacs) ++will group some classes of items automatically. Even here, however, ++some tag groups can be quite large. ++ ++@cindex @code{speedbar-tag-hierarchy-method} ++To solve this problem, tags can be grouped into logical units through a ++hierarchy processor. The specific variable to use is ++@code{speedbar-tag-hierarchy-method}. There are several methods that ++can be applied in any order. They are: ++ ++@table @code ++@cindex @code{speedbar-trim-words-tag-hierarchy} ++@item speedbar-trim-words-tag-hierarchy ++Find a common prefix for all elements of a group, and trim it off. ++@cindex @code{speedbar-prefix-group-tag-hierarchy} ++@item speedbar-prefix-group-tag-hierarchy ++If a group is too large, place sets of tags into bins based on common ++prefixes. ++@cindex @code{speedbar-simple-group-tag-hierarchy} ++@item speedbar-simple-group-tag-hierarchy ++Take all items in the top level list not in a group, and stick them into ++a @samp{Tags} group. ++@cindex @code{speedbar-sort-tag-hierarchy} ++@item speedbar-sort-tag-hierarchy ++Sort all items, leaving groups on top. ++@end table ++ ++You can also add your own functions to reorganize tags as you see fit. ++ ++Some other control variables are: ++ ++@table @code ++@cindex @code{speedbar-tag-group-name-minimum-length} ++@item speedbar-tag-group-name-minimum-length ++Default value: 4. ++ ++The minimum length of a prefix group name before expanding. Thus, if ++the @code{speedbar-tag-hierarchy-method} includes ++@code{speedbar-prefix-group-tag-hierarchy} and one such group's common ++characters is less than this number of characters, then the group name ++will be changed to the form of: ++ ++@example ++worda to wordb ++@end example ++ ++instead of just ++ ++@example ++word ++@end example ++ ++This way we won't get silly looking listings. ++ ++@cindex @code{speedbar-tag-split-minimum-length} ++@item speedbar-tag-split-minimum-length ++Default value: 20. ++ ++Minimum length before we stop trying to create sub-lists in tags. ++This is used by all tag-hierarchy methods that break large lists into ++sub-lists. ++ ++@cindex @code{speedbar-tag-regroup-maximum-length} ++@item speedbar-tag-regroup-maximum-length ++Default value: 10. ++ ++Maximum length of submenus that are regrouped. ++If the regrouping option is used, then if two or more short subgroups ++are next to each other, then they are combined until this number of ++items is reached. ++@end table ++ ++@node Version Control, Hooks, Tag Hierarchy Methods, Customizing ++@comment node-name, next, previous, up ++@section Version Control ++@cindex version control ++@cindex vc extensions ++ ++When using the file mode in speedbar, information regarding a version ++control system adds small details to the display. If a file is in a ++version control system, and is ``checked out'' or ``locked'' locally, an ++asterisk @samp{*} appears at the end of the file name. In addition, ++the directory name for Version Control systems are left out of the ++speedbar display. ++ ++@cindex @code{speedbar-directory-unshown-regexp} ++You can easily add new version control systems into speedbar's detection ++scheme. To make a directory ``disappear'' from the list, use the variable ++@code{speedbar-directory-unshown-regexp}. ++ ++@cindex @code{speedbar-vc-path-enable-hook} ++Next, you need to write entries for two hooks. The first is ++@code{speedbar-vc-path-enable-hook} which will enable a VC check in the ++current directory for the group of files being checked. Your hook ++function should take one parameter (the directory to check) and return ++@code{t} if your VC method is in control here. ++ ++@cindex @code{speedbar-vc-in-control-hook} ++The second function is @code{speedbar-vc-in-control-hook}. This hook ++takes two parameters, the @var{path} of the file to check, and the ++@var{file} name. Return @code{t} if you want to have the asterisk ++placed near this file. ++ ++@cindex @code{speedbar-vc-indicator} ++Lastly, you can change the VC indicator using the variable ++@code{speedbar-vc-indicator}, and specify a single character string. ++ ++@node Hooks, , Version Control, Customizing ++@comment node-name, next, previous, up ++@section Hooks ++@cindex hooks ++ ++There are several hooks in speedbar allowing custom behaviors to be ++added. Available hooks are: ++ ++@table @code ++@cindex @code{speedbar-visiting-file-hook} ++@item speedbar-visiting-file-hook ++Hooks run when speedbar visits a file in the selected frame. ++@cindex @code{speedbar-visiting-tag-hook} ++@item speedbar-visiting-tag-hook ++Hooks run when speedbar visits a tag in the selected frame. ++@cindex @code{speedbar-load-hook} ++@item speedbar-load-hook ++Hooks run when speedbar is loaded. ++@cindex @code{speedbar-reconfigure-keymaps-hook} ++@item speedbar-reconfigure-keymaps-hook ++Hooks run when the keymaps are regenerated. Keymaps are reconfigured ++whenever modes change. This will let you add custom key bindings. ++@cindex @code{speedbar-before-popup-hook} ++@item speedbar-before-popup-hook ++Hooks called before popping up the speedbar frame. ++New frames are often popped up when ``power clicking'' on an item to view ++it. ++@cindex @code{speedbar-before-delete-hook} ++@item speedbar-before-delete-hook ++Hooks called before deleting or hiding the speedbar frame. ++@cindex @code{speedbar-mode-hook} ++@item speedbar-mode-hook ++Hooks called after creating a speedbar buffer. ++@cindex @code{speedbar-timer-hook} ++@item speedbar-timer-hook ++Hooks called after running the speedbar timer function. ++@cindex @code{speedbar-scanner-reset-hook} ++@item speedbar-scanner-reset-hook ++Hook called whenever generic scanners are reset. ++Set this to implement your own scanning or rescan safe functions with ++state data. ++@end table ++ ++@node Extending, GNU Free Documentation License, Customizing, Top ++@comment node-name, next, previous, up ++@chapter Extending ++@cindex extending ++ ++Speedbar can run different types of Major display modes such as Files ++(@pxref{File Mode}), and Buffers (@pxref{Buffer Mode}). It can also manage ++different minor display modes for use with buffers handling specialized ++data. ++ ++These major and minor display modes are handled through an extension ++system which permits specialized keymaps and menu extensions, in ++addition to a unique rendering function. You can also specify a wide ++range of tagging functions. The default uses @code{imenu}, but new ++tagging methods can be easily added. In this chapter, you will ++learn how to write your own major or minor display modes, and how to ++create specialized tagging functions. ++ ++@menu ++* Minor Display Modes:: How to create a minor display mode. ++* Major Display Modes:: How to create a major display mode. ++* Tagging Extensions:: How to create your own tagging methods. ++* Creating a display:: How to insert buttons and hierarchies. ++@end menu ++ ++@node Minor Display Modes, Major Display Modes, Extending, Extending ++@section Minor Display Modes ++@cindex create minor display mode ++ ++A @dfn{minor display mode} is a mode useful when using a specific type of ++buffer. This mode might not be useful for any other kind of data or ++mode, or may just be more useful that a files or buffers based mode when ++working with a specialized mode. ++ ++Examples that already exist for speedbar include RMAIL, Info, and gdb. ++These modes display information specific to the major mode shown in the ++attached frame. ++ ++To enable a minor display mode in your favorite Major mode, follow these ++steps. The string @samp{@var{name}} is the name of the major mode being ++augmented with speedbar. ++ ++@enumerate ++@item ++Create the keymap variable @code{@var{name}-speedbar-key-map}. ++ ++@item ++Create a function, named whatever you like, which assigns values into your ++keymap. Use this command to create the keymap before assigning ++bindings: ++ ++@smallexample ++ (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap)) ++@end smallexample ++ ++This function creates a special keymap for use in speedbar. ++ ++@item ++Call your install function, or assign it to a hook like this: ++ ++@smallexample ++(if (featurep 'speedbar) ++ (@var{name}-install-speedbar-variables) ++ (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables)) ++@end smallexample ++ ++@item ++Create an easymenu compatible vector named ++@code{@var{name}-speedbar-menu-items}. This will be spliced into ++speedbar's control menu. ++ ++@item ++Create a function called @code{@var{name}-speedbar-buttons}. This function ++should take one variable, which is the buffer for which it will create ++buttons. At this time @code{(current-buffer)} will point to the ++uncleared speedbar buffer. ++@end enumerate ++ ++When writing @code{@var{name}-speedbar-buttons}, the first thing you will ++want to do is execute a check to see if you need to re-create your ++display. If it needs to be cleared, you need to erase the speedbar ++buffer yourself, and start drawing buttons. @xref{Creating a display}. ++ ++@node Major Display Modes, Tagging Extensions, Minor Display Modes, Extending ++@section Major Display Modes ++@cindex create major display mode ++ ++Creating a @dfn{Major Display Mode} for speedbar requires authoring a keymap, ++an easy-menu segment, and writing several functions. These items can be ++given any name, and are made the same way as in a minor display mode ++(@pxref{Minor Display Modes}). Once this is done, these items need to be ++registered. ++ ++Because this setup activity may or may not have speedbar available when ++it is being loaded, it is necessary to create an install function. This ++function should create and initialize the keymap, and add your ++expansions into the customization tables. ++ ++@cindex @code{speedbar-make-specialized-keymap} ++When creating the keymap, use the function ++@code{speedbar-make-specialized-keymap} instead of other keymap making ++functions. This will provide you with the initial bindings needed. ++Some common speedbar functions you might want to bind are: ++ ++@table @code ++@cindex @code{speedbar-edit-line} ++@item speedbar-edit-line ++Edit the item on the current line. ++@cindex @code{speedbar-expand-line} ++@item speedbar-expand-line ++Expand the item under the cursor. ++With a numeric argument (@kbd{C-u}), flush cached data before expanding. ++@cindex @code{speedbar-contract-line} ++@item speedbar-contract-line ++Contract the item under the cursor. ++@end table ++ ++@cindex @code{speedbar-line-path} ++These function require that function @code{speedbar-line-path} be ++correctly overloaded to work. ++ ++Next, register your extension like this; ++ ++@example ++ (speedbar-add-expansion-list '("MyExtension" ++ MyExtension-speedbar-menu-items ++ MyExtension-speedbar-key-map ++ MyExtension-speedbar-buttons)) ++@end example ++ ++There are no limitations to the names you use. ++ ++The first parameter is the string representing your display mode. ++The second parameter is a variable name containing an easymenu compatible ++menu definition. This will be stuck in the middle of speedbar's menu. ++The third parameter is the variable name containing the keymap we ++discussed earlier. ++The last parameter is a function which draws buttons for your mode. ++This function must take two parameters. The directory currently being ++displayed, and the depth at which you should start rendering buttons. ++The function will then draw (starting at the current cursor position) ++any buttons deemed necessary based on the input parameters. ++@xref{Creating a display}. ++ ++Next, you need to register function overrides. This may look something ++like this: ++ ++@example ++(speedbar-add-mode-functions-list ++ '("MYEXTENSION" ++ (speedbar-item-info . MyExtension-speedbar-item-info) ++ (speedbar-line-path . MyExtension-speedbar-line-path))) ++@end example ++ ++The first element in the list is the name of you extension. The second ++is an alist of functions to overload. The function to overload is ++first, followed by what you want called instead. ++ ++For @code{speedbar-line-path} your function should take an optional DEPTH ++parameter. This is the starting depth for heavily indented lines. If ++it is not provided, you can derive it like this: ++ ++@example ++(save-match-data ++ (if (not depth) ++ (progn ++ (beginning-of-line) ++ (looking-at "^\\([0-9]+\\):") ++ (setq depth (string-to-int (match-string 1))))) ++@end example ++ ++@noindent ++where the depth is stored as invisible text at the beginning of each ++line. ++ ++The path returned should be the full path name of the file associated ++with that line. If the cursor is on a tag, then the file containing ++that tag should be returned. This is critical for built in file based ++functions to work (meaning less code for you to write). If your display ++does not deal in files, you do not need to overload this function. ++ ++@cindex @code{speedbar-item-info} ++The function @code{speedbar-item-info}, however, is very likely to need ++overloading. This function takes no parameters and must derive a text ++summary to display in the minibuffer. ++ ++There are several helper functions you can use if you are going to use ++built in tagging. These functions can be @code{or}ed since each one ++returns non-@code{nil} if it displays a message. They are: ++ ++@table @code ++@cindex @code{speedbar-item-info-file-helper} ++@item speedbar-item-info-file-helper ++This takes an optional @var{filename} parameter. You can derive your own ++filename, or it will derive it using a (possibly overloaded) function ++@code{speedbar-line-file}. It shows details about a file. ++@cindex @code{speedbar-item-info-tag-helper} ++@item speedbar-item-info-tag-helper ++If the current line is a tag, then display information about that tag, ++such as its parent file, and location. ++@end table ++ ++Your custom function might look like this: ++ ++@example ++(defun MyExtension-item-info () ++ "Display information about the current line." ++ (or (speedbar-item-info-tag-helper) ++ (message "Interesting detail."))) ++@end example ++ ++Once you have done all this, speedbar will show an entry in the ++@samp{Displays} menu declaring that your extension is available. ++ ++@node Tagging Extensions, Creating a display, Major Display Modes, Extending ++@section Tagging Extensions ++ ++It is possible to create new methods for tagging files in speedbar. ++To do this, you need two basic functions, one function to fetch the ++tags from a buffer, the other to insert them below the filename. ++ ++@defun my-fetch-dynamic-tags file ++Parse @var{file} for a list of tags. Return the list, or @code{t} if there was ++an error. ++@end defun ++ ++The non-error return value can be anything, as long as it can be ++inserted by its paired function: ++ ++@defun my-insert-tag-list level lst ++Insert a list of tags @var{lst} started at indentation level ++@var{level}. Creates buttons for each tag, and provides any other ++display information required. ++@end defun ++ ++@cindex @code{speedbar-create-tag-hierarchy} ++It is often useful to use @code{speedbar-create-tag-hierarchy} on your ++token list. See that function's documentation for details on what it ++requires. ++ ++@cindex @code{speedbar-dynamic-tags-function-list} ++Once these two functions are written, modify the variable ++@code{speedbar-dynamic-tags-function-list} to include your parser at the ++beginning, like this: ++ ++@example ++(add-to-list 'speedbar-dynamic-tags-function-list ++ '(my-fetch-dynamic-tags . my-insert-tag-list)) ++@end example ++ ++If your parser is only good for a few types of files, make sure that it ++is either a buffer local modification, or that the tag generator returns ++@code{t} for non valid buffers. ++ ++@node Creating a display, , Tagging Extensions, Extending ++@section Creating a display ++@cindex creating a display ++ ++Rendering a display in speedbar is completely flexible. When your ++button function is called, see @ref{Minor Display Modes}, and @ref{Major ++Display Modes}, you have control to @code{insert} anything you want. ++ ++The conventions allow almost anything to be inserted, but several helper ++functions are provided to make it easy to create the standardized ++buttons. ++ ++To understand the built in functions, each `button' in speedbar consists ++of four important pieces of data. The text to be displayed, token ++data to be associated with the text, a function to call, and some face to ++display it in. ++ ++When a function is provided, then that text becomes mouse activated, ++meaning the mouse will highlight the text. ++ ++Additionally, for data which can form deep trees, each line is given a ++depth which indicates how far down the tree it is. This information is ++stored in invisible text at the beginning of each line, and is used by ++the navigation commands. ++ ++@defun speedbar-insert-button text face mouse function &optional token prevline ++This function inserts one button into the current location. ++@var{text} is the text to insert. @var{face} is the face in which it ++will be displayed. @var{mouse} is the face to display over the text ++when the mouse passes over it. @var{function} is called whenever the ++user clicks on the text. ++ ++The optional argument @var{token} is extra data to associated with the ++text. Lastly @var{prevline} should be non-@code{nil} if you want this line to ++appear directly after the last button which was created instead of on ++the next line. ++@end defun ++ ++@defun speedbar-make-tag-line exp-button-type exp-button-char exp-button-function exp-button-data tag-button tag-button-function tag-button-data tag-button-face depth ++ ++Create a tag line with @var{exp-button-type} for the small expansion ++button. This is the button that expands or contracts a node (if ++applicable), and @var{exp-button-char} the character in it (@samp{+}, ++@samp{-}, @samp{?}, etc). @var{exp-button-function} is the function ++to call if it's clicked on. Button types are @code{bracket}, ++@code{angle}, @code{curly}, @code{expandtag}, @code{statictag}, and ++@code{nil}. @var{exp-button-data} is extra data attached to the text ++forming the expansion button. ++ ++Next, @var{tag-button} is the text of the tag. ++@var{tag-button-function} is the function to call if clicked on, and ++@var{tag-button-data} is the data to attach to the text field (such a ++tag positioning, etc). @var{tag-button-face} is a face used for this ++type of tag. ++ ++Lastly, @var{depth} shows the depth of expansion. ++ ++This function assumes that the cursor is in the speedbar window at the ++position to insert a new item, and that the new item will end with a CR. ++@end defun ++ ++@defun speedbar-insert-generic-list level list expand-fun find-fun ++ ++At @var{level}, (the current indentation level desired) insert a generic ++multi-level alist @var{list}. Associations with lists get @samp{@{+@}} ++tags (to expand into more nodes) and those with positions or other data ++just get a @samp{>} as the indicator. @samp{@{+@}} buttons will have the ++function @var{expand-fun} and the token is the @code{cdr} list. The ++token name will have the function @var{find-fun} and not token. ++ ++Each element of the list can have one of these forms: ++ ++@table @code ++@item (@var{name} . marker-or-number) ++One tag at this level. ++@item (@var{name} (@var{name} . marker-or-number) (@var{name} . marker-or-number) ... ) ++One group of tags. ++@item (@var{name} marker-or-number (@var{name} . marker-or-number) ... ) ++One Group of tags where the group has a starting position. ++@end table ++ ++When you use @code{speedbar-insert-generic-list}, there are some ++variables you can set buffer-locally to change the behavior. The most ++obvious is @code{speedbar-tag-hierarchy-method}. ++@xref{Tag Hierarchy Methods}. ++ ++@defvar speedbar-generic-list-group-expand-button-type ++This is the button type used for groups of tags, whether expanded ++or added in via a hierarchy method. Two good values are ++@code{curly} and @code{expandtag}. Curly is the default button, and ++@code{expandtag} is useful if the groups also has a position. ++@end defvar ++ ++@defvar speedbar-generic-list-tag-button-type ++This is the button type used for a single tag. ++Two good values are @code{nil} and @code{statictag}. ++@code{nil} is the default, and @code{statictag} has the same width as ++@code{expandtag}. ++@end defvar ++ ++@end defun ++ ++@node GNU Free Documentation License, Index, Extending, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++ ++@node Index, , GNU Free Documentation License, Top ++@comment node-name, next, previous, up ++@unnumbered Concept Index ++@printindex cp ++ ++@bye ++@c LocalWords: speedbar's xref slowbar kbd subsubsection ++@c LocalWords: keybindings ++ ++@ignore ++ arch-tag: e1fc85f0-1eeb-489f-a8d4-a2bfe711fa02 ++@end ignore +diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex +new file mode 100644 +index 0000000..62f7a72 +--- /dev/null ++++ b/doc/misc/texinfo.tex +@@ -0,0 +1,8662 @@ ++% 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{2007-07-09.21} ++% ++% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, ++% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, ++% 2007, 2008 Free Software Foundation, Inc. ++% ++% This texinfo.tex file is free software; you can redistribute it and/or ++% modify it under the terms of the GNU General Public License as ++% published by the Free Software Foundation; either version 2, or (at ++% your option) any later version. ++% ++% This texinfo.tex file is distributed in the hope that it will be ++% useful, but WITHOUT ANY WARRANTY; without even the implied warranty ++% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ++% General Public License for more details. ++% ++% You should have received a copy of the GNU General Public License ++% along with this texinfo.tex file; see the file COPYING. If not, write ++% to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, ++% Boston, MA 02110-1301, USA. ++% ++% As a special exception, when this file is read by TeX when processing ++% a Texinfo source document, you may use the result without ++% restriction. (This has been our intent since Texinfo was invented.) ++% ++% Please try the latest version of texinfo.tex before submitting bug ++% reports; you can get the latest version from: ++% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or ++% ftp://tug.org/tex/texinfo.tex ++% (and all CTAN mirrors, see http://www.ctan.org). ++% The texinfo.tex in any given distribution could well be out ++% of date, so if that's what you're using, please check. ++% ++% Send bug reports to bug-texinfo@gnu.org. Please include including a ++% complete document in each bug report with which we can reproduce the ++% problem. Patches are, of course, greatly appreciated. ++% ++% To process a Texinfo manual with TeX, it's most reliable to use the ++% texi2dvi shell script that comes with the distribution. For a simple ++% manual foo.texi, however, you can get away with this: ++% tex foo.texi ++% texindex foo.?? ++% tex foo.texi ++% tex foo.texi ++% dvips foo.dvi -o # or whatever; this makes foo.ps. ++% The extra TeX runs get the cross-reference information correct. ++% Sometimes one run after texindex suffices, and sometimes you need more ++% than two; texi2dvi does it as many times as necessary. ++% ++% It is possible to adapt texinfo.tex for other languages, to some ++% extent. You can get the existing language-specific files from the ++% full Texinfo distribution. ++% ++% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. ++ ++ ++\message{Loading texinfo [version \texinfoversion]:} ++ ++% If in a .fmt file, print the version number ++% and turn on active characters that we couldn't do earlier because ++% they might have appeared in the input file name. ++\everyjob{\message{[Texinfo version \texinfoversion]}% ++ \catcode`+=\active \catcode`\_=\active} ++ ++ ++\chardef\other=12 ++ ++% We never want plain's \outer definition of \+ in Texinfo. ++% For @tex, we can use \tabalign. ++\let\+ = \relax ++ ++% Save some plain tex macros whose names we will redefine. ++\let\ptexb=\b ++\let\ptexbullet=\bullet ++\let\ptexc=\c ++\let\ptexcomma=\, ++\let\ptexdot=\. ++\let\ptexdots=\dots ++\let\ptexend=\end ++\let\ptexequiv=\equiv ++\let\ptexexclam=\! ++\let\ptexfootnote=\footnote ++\let\ptexgtr=> ++\let\ptexhat=^ ++\let\ptexi=\i ++\let\ptexindent=\indent ++\let\ptexinsert=\insert ++\let\ptexlbrace=\{ ++\let\ptexless=< ++\let\ptexnewwrite\newwrite ++\let\ptexnoindent=\noindent ++\let\ptexplus=+ ++\let\ptexrbrace=\} ++\let\ptexslash=\/ ++\let\ptexstar=\* ++\let\ptext=\t ++ ++% If this character appears in an error message or help string, it ++% starts a new line in the output. ++\newlinechar = `^^J ++ ++% Use TeX 3.0's \inputlineno to get the line number, for better error ++% messages, but if we're using an old version of TeX, don't do anything. ++% ++\ifx\inputlineno\thisisundefined ++ \let\linenumber = \empty % Pre-3.0. ++\else ++ \def\linenumber{l.\the\inputlineno:\space} ++\fi ++ ++% Set up fixed words for English if not already set. ++\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi ++\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi ++\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi ++\ifx\putwordin\undefined \gdef\putwordin{in}\fi ++\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi ++\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi ++\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi ++\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi ++\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi ++\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi ++\ifx\putwordof\undefined \gdef\putwordof{of}\fi ++\ifx\putwordon\undefined \gdef\putwordon{on}\fi ++\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi ++\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi ++\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi ++\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi ++\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi ++\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi ++\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi ++% ++\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi ++\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi ++\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi ++\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi ++\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi ++\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi ++\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi ++\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi ++\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi ++\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi ++\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi ++\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi ++% ++\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi ++\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi ++\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi ++\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi ++\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi ++ ++% Since the category of space is not known, we have to be careful. ++\chardef\spacecat = 10 ++\def\spaceisspace{\catcode`\ =\spacecat} ++ ++% sometimes characters are active, so we need control sequences. ++\chardef\colonChar = `\: ++\chardef\commaChar = `\, ++\chardef\dashChar = `\- ++\chardef\dotChar = `\. ++\chardef\exclamChar= `\! ++\chardef\lquoteChar= `\` ++\chardef\questChar = `\? ++\chardef\rquoteChar= `\' ++\chardef\semiChar = `\; ++\chardef\underChar = `\_ ++ ++% Ignore a token. ++% ++\def\gobble#1{} ++ ++% The following is used inside several \edef's. ++\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname} ++ ++% Hyphenation fixes. ++\hyphenation{ ++ Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script ++ ap-pen-dix bit-map bit-maps ++ data-base data-bases eshell fall-ing half-way long-est man-u-script ++ man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm ++ par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces ++ spell-ing spell-ings ++ stand-alone strong-est time-stamp time-stamps which-ever white-space ++ wide-spread wrap-around ++} ++ ++% Margin to add to right of even pages, to left of odd pages. ++\newdimen\bindingoffset ++\newdimen\normaloffset ++\newdimen\pagewidth \newdimen\pageheight ++ ++% For a final copy, take out the rectangles ++% that mark overfull boxes (in case you have decided ++% that the text looks ok even though it passes the margin). ++% ++\def\finalout{\overfullrule=0pt} ++ ++% @| inserts a changebar to the left of the current line. It should ++% surround any changed text. This approach does *not* work if the ++% change spans more than two lines of output. To handle that, we would ++% have adopt a much more difficult approach (putting marks into the main ++% vertical list for the beginning and end of each change). ++% ++\def\|{% ++ % \vadjust can only be used in horizontal mode. ++ \leavevmode ++ % ++ % Append this vertical mode material after the current line in the output. ++ \vadjust{% ++ % We want to insert a rule with the height and depth of the current ++ % leading; that is exactly what \strutbox is supposed to record. ++ \vskip-\baselineskip ++ % ++ % \vadjust-items are inserted at the left edge of the type. So ++ % the \llap here moves out into the left-hand margin. ++ \llap{% ++ % ++ % For a thicker or thinner bar, change the `1pt'. ++ \vrule height\baselineskip width1pt ++ % ++ % This is the space between the bar and the text. ++ \hskip 12pt ++ }% ++ }% ++} ++ ++% Sometimes it is convenient to have everything in the transcript file ++% and nothing on the terminal. We don't just call \tracingall here, ++% since that produces some useless output on the terminal. We also make ++% some effort to order the tracing commands to reduce output in the log ++% file; cf. trace.sty in LaTeX. ++% ++\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% ++\def\loggingall{% ++ \tracingstats2 ++ \tracingpages1 ++ \tracinglostchars2 % 2 gives us more in etex ++ \tracingparagraphs1 ++ \tracingoutput1 ++ \tracingmacros2 ++ \tracingrestores1 ++ \showboxbreadth\maxdimen \showboxdepth\maxdimen ++ \ifx\eTeXversion\undefined\else % etex gives us more logging ++ \tracingscantokens1 ++ \tracingifs1 ++ \tracinggroups1 ++ \tracingnesting2 ++ \tracingassigns1 ++ \fi ++ \tracingcommands3 % 3 gives us more in etex ++ \errorcontextlines16 ++}% ++ ++% add check for \lastpenalty to plain's definitions. If the last thing ++% we did was a \nobreak, we don't want to insert more space. ++% ++\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount ++ \removelastskip\penalty-50\smallskip\fi\fi} ++\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount ++ \removelastskip\penalty-100\medskip\fi\fi} ++\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount ++ \removelastskip\penalty-200\bigskip\fi\fi} ++ ++% For @cropmarks command. ++% Do @cropmarks to get crop marks. ++% ++\newif\ifcropmarks ++\let\cropmarks = \cropmarkstrue ++% ++% Dimensions to add cropmarks at corners. ++% Added by P. A. MacKay, 12 Nov. 1986 ++% ++\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines ++\newdimen\cornerlong \cornerlong=1pc ++\newdimen\cornerthick \cornerthick=.3pt ++\newdimen\topandbottommargin \topandbottommargin=.75in ++ ++% Main output routine. ++\chardef\PAGE = 255 ++\output = {\onepageout{\pagecontents\PAGE}} ++ ++\newbox\headlinebox ++\newbox\footlinebox ++ ++% \onepageout takes a vbox as an argument. Note that \pagecontents ++% does insertions, but you have to call it yourself. ++\def\onepageout#1{% ++ \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi ++ % ++ \ifodd\pageno \advance\hoffset by \bindingoffset ++ \else \advance\hoffset by -\bindingoffset\fi ++ % ++ % Do this outside of the \shipout so @code etc. will be expanded in ++ % the headline as they should be, not taken literally (outputting ''code). ++ \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% ++ \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% ++ % ++ {% ++ % Have to do this stuff outside the \shipout because we want it to ++ % take effect in \write's, yet the group defined by the \vbox ends ++ % before the \shipout runs. ++ % ++ \indexdummies % don't expand commands in the output. ++ \normalturnoffactive % \ in index entries must not stay \, e.g., if ++ % the page break happens to be in the middle of an example. ++ % We don't want .vr (or whatever) entries like this: ++ % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}} ++ % "\acronym" won't work when it's read back in; ++ % it needs to be ++ % {\code {{\tt \backslashcurfont }acronym} ++ \shipout\vbox{% ++ % Do this early so pdf references go to the beginning of the page. ++ \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi ++ % ++ \ifcropmarks \vbox to \outervsize\bgroup ++ \hsize = \outerhsize ++ \vskip-\topandbottommargin ++ \vtop to0pt{% ++ \line{\ewtop\hfil\ewtop}% ++ \nointerlineskip ++ \line{% ++ \vbox{\moveleft\cornerthick\nstop}% ++ \hfill ++ \vbox{\moveright\cornerthick\nstop}% ++ }% ++ \vss}% ++ \vskip\topandbottommargin ++ \line\bgroup ++ \hfil % center the page within the outer (page) hsize. ++ \ifodd\pageno\hskip\bindingoffset\fi ++ \vbox\bgroup ++ \fi ++ % ++ \unvbox\headlinebox ++ \pagebody{#1}% ++ \ifdim\ht\footlinebox > 0pt ++ % Only leave this space if the footline is nonempty. ++ % (We lessened \vsize for it in \oddfootingyyy.) ++ % The \baselineskip=24pt in plain's \makefootline has no effect. ++ \vskip 24pt ++ \unvbox\footlinebox ++ \fi ++ % ++ \ifcropmarks ++ \egroup % end of \vbox\bgroup ++ \hfil\egroup % end of (centering) \line\bgroup ++ \vskip\topandbottommargin plus1fill minus1fill ++ \boxmaxdepth = \cornerthick ++ \vbox to0pt{\vss ++ \line{% ++ \vbox{\moveleft\cornerthick\nsbot}% ++ \hfill ++ \vbox{\moveright\cornerthick\nsbot}% ++ }% ++ \nointerlineskip ++ \line{\ewbot\hfil\ewbot}% ++ }% ++ \egroup % \vbox from first cropmarks clause ++ \fi ++ }% end of \shipout\vbox ++ }% end of group with \indexdummies ++ \advancepageno ++ \ifnum\outputpenalty>-20000 \else\dosupereject\fi ++} ++ ++\newinsert\margin \dimen\margin=\maxdimen ++ ++\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} ++{\catcode`\@ =11 ++\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi ++% marginal hacks, juha@viisa.uucp (Juha Takala) ++\ifvoid\margin\else % marginal info is present ++ \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi ++\dimen@=\dp#1 \unvbox#1 ++\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi ++\ifr@ggedbottom \kern-\dimen@ \vfil \fi} ++} ++ ++% Here are the rules for the cropmarks. Note that they are ++% offset so that the space between them is truly \outerhsize or \outervsize ++% (P. A. MacKay, 12 November, 1986) ++% ++\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} ++\def\nstop{\vbox ++ {\hrule height\cornerthick depth\cornerlong width\cornerthick}} ++\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} ++\def\nsbot{\vbox ++ {\hrule height\cornerlong depth\cornerthick width\cornerthick}} ++ ++% Parse an argument, then pass it to #1. The argument is the rest of ++% the input line (except we remove a trailing comment). #1 should be a ++% macro which expects an ordinary undelimited TeX argument. ++% ++\def\parsearg{\parseargusing{}} ++\def\parseargusing#1#2{% ++ \def\argtorun{#2}% ++ \begingroup ++ \obeylines ++ \spaceisspace ++ #1% ++ \parseargline\empty% Insert the \empty token, see \finishparsearg below. ++} ++ ++{\obeylines % ++ \gdef\parseargline#1^^M{% ++ \endgroup % End of the group started in \parsearg. ++ \argremovecomment #1\comment\ArgTerm% ++ }% ++} ++ ++% First remove any @comment, then any @c comment. ++\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} ++\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} ++ ++% Each occurence of `\^^M' or `\^^M' is replaced by a single space. ++% ++% \argremovec might leave us with trailing space, e.g., ++% @end itemize @c foo ++% This space token undergoes the same procedure and is eventually removed ++% by \finishparsearg. ++% ++\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M} ++\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M} ++\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{% ++ \def\temp{#3}% ++ \ifx\temp\empty ++ % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp: ++ \let\temp\finishparsearg ++ \else ++ \let\temp\argcheckspaces ++ \fi ++ % Put the space token in: ++ \temp#1 #3\ArgTerm ++} ++ ++% If a _delimited_ argument is enclosed in braces, they get stripped; so ++% to get _exactly_ the rest of the line, we had to prevent such situation. ++% We prepended an \empty token at the very beginning and we expand it now, ++% just before passing the control to \argtorun. ++% (Similarily, we have to think about #3 of \argcheckspacesY above: it is ++% either the null string, or it ends with \^^M---thus there is no danger ++% that a pair of braces would be stripped. ++% ++% But first, we have to remove the trailing space token. ++% ++\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}} ++ ++% \parseargdef\foo{...} ++% is roughly equivalent to ++% \def\foo{\parsearg\Xfoo} ++% \def\Xfoo#1{...} ++% ++% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my ++% favourite TeX trick. --kasal, 16nov03 ++ ++\def\parseargdef#1{% ++ \expandafter \doparseargdef \csname\string#1\endcsname #1% ++} ++\def\doparseargdef#1#2{% ++ \def#2{\parsearg#1}% ++ \def#1##1% ++} ++ ++% Several utility definitions with active space: ++{ ++ \obeyspaces ++ \gdef\obeyedspace{ } ++ ++ % Make each space character in the input produce a normal interword ++ % space in the output. Don't allow a line break at this space, as this ++ % is used only in environments like @example, where each line of input ++ % should produce a line of output anyway. ++ % ++ \gdef\sepspaces{\obeyspaces\let =\tie} ++ ++ % If an index command is used in an @example environment, any spaces ++ % therein should become regular spaces in the raw index file, not the ++ % expansion of \tie (\leavevmode \penalty \@M \ ). ++ \gdef\unsepspaces{\let =\space} ++} ++ ++ ++\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} ++ ++% Define the framework for environments in texinfo.tex. It's used like this: ++% ++% \envdef\foo{...} ++% \def\Efoo{...} ++% ++% It's the responsibility of \envdef to insert \begingroup before the ++% actual body; @end closes the group after calling \Efoo. \envdef also ++% defines \thisenv, so the current environment is known; @end checks ++% whether the environment name matches. The \checkenv macro can also be ++% used to check whether the current environment is the one expected. ++% ++% Non-false conditionals (@iftex, @ifset) don't fit into this, so they ++% are not treated as enviroments; they don't open a group. (The ++% implementation of @end takes care not to call \endgroup in this ++% special case.) ++ ++ ++% At runtime, environments start with this: ++\def\startenvironment#1{\begingroup\def\thisenv{#1}} ++% initialize ++\let\thisenv\empty ++ ++% ... but they get defined via ``\envdef\foo{...}'': ++\long\def\envdef#1#2{\def#1{\startenvironment#1#2}} ++\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}} ++ ++% Check whether we're in the right environment: ++\def\checkenv#1{% ++ \def\temp{#1}% ++ \ifx\thisenv\temp ++ \else ++ \badenverr ++ \fi ++} ++ ++% Evironment mismatch, #1 expected: ++\def\badenverr{% ++ \errhelp = \EMsimple ++ \errmessage{This command can appear only \inenvironment\temp, ++ not \inenvironment\thisenv}% ++} ++\def\inenvironment#1{% ++ \ifx#1\empty ++ out of any environment% ++ \else ++ in environment \expandafter\string#1% ++ \fi ++} ++ ++% @end foo executes the definition of \Efoo. ++% But first, it executes a specialized version of \checkenv ++% ++\parseargdef\end{% ++ \if 1\csname iscond.#1\endcsname ++ \else ++ % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03 ++ \expandafter\checkenv\csname#1\endcsname ++ \csname E#1\endcsname ++ \endgroup ++ \fi ++} ++ ++\newhelp\EMsimple{Press RETURN to continue.} ++ ++ ++%% Simple single-character @ commands ++ ++% @@ prints an @ ++% Kludge this until the fonts are right (grr). ++\def\@{{\tt\char64}} ++ ++% This is turned off because it was never documented ++% and you can use @w{...} around a quote to suppress ligatures. ++%% Define @` and @' to be the same as ` and ' ++%% but suppressing ligatures. ++%\def\`{{`}} ++%\def\'{{'}} ++ ++% Used to generate quoted braces. ++\def\mylbrace {{\tt\char123}} ++\def\myrbrace {{\tt\char125}} ++\let\{=\mylbrace ++\let\}=\myrbrace ++\begingroup ++ % Definitions to produce \{ and \} commands for indices, ++ % and @{ and @} for the aux/toc files. ++ \catcode`\{ = \other \catcode`\} = \other ++ \catcode`\[ = 1 \catcode`\] = 2 ++ \catcode`\! = 0 \catcode`\\ = \other ++ !gdef!lbracecmd[\{]% ++ !gdef!rbracecmd[\}]% ++ !gdef!lbraceatcmd[@{]% ++ !gdef!rbraceatcmd[@}]% ++!endgroup ++ ++% @comma{} to avoid , parsing problems. ++\let\comma = , ++ ++% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent ++% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H. ++\let\, = \c ++\let\dotaccent = \. ++\def\ringaccent#1{{\accent23 #1}} ++\let\tieaccent = \t ++\let\ubaraccent = \b ++\let\udotaccent = \d ++ ++% Other special characters: @questiondown @exclamdown @ordf @ordm ++% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. ++\def\questiondown{?`} ++\def\exclamdown{!`} ++\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}} ++\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}} ++ ++% Dotless i and dotless j, used for accents. ++\def\imacro{i} ++\def\jmacro{j} ++\def\dotless#1{% ++ \def\temp{#1}% ++ \ifx\temp\imacro \ptexi ++ \else\ifx\temp\jmacro \j ++ \else \errmessage{@dotless can be used only with i or j}% ++ \fi\fi ++} ++ ++% The \TeX{} logo, as in plain, but resetting the spacing so that a ++% period following counts as ending a sentence. (Idea found in latex.) ++% ++\edef\TeX{\TeX \spacefactor=1000 } ++ ++% @LaTeX{} logo. Not quite the same results as the definition in ++% latex.ltx, since we use a different font for the raised A; it's most ++% convenient for us to use an explicitly smaller font, rather than using ++% the \scriptstyle font (since we don't reset \scriptstyle and ++% \scriptscriptstyle). ++% ++\def\LaTeX{% ++ L\kern-.36em ++ {\setbox0=\hbox{T}% ++ \vbox to \ht0{\hbox{\selectfonts\lllsize A}\vss}}% ++ \kern-.15em ++ \TeX ++} ++ ++% Be sure we're in horizontal mode when doing a tie, since we make space ++% equivalent to this in @example-like environments. Otherwise, a space ++% at the beginning of a line will start with \penalty -- and ++% since \penalty is valid in vertical mode, we'd end up putting the ++% penalty on the vertical list instead of in the new paragraph. ++{\catcode`@ = 11 ++ % Avoid using \@M directly, because that causes trouble ++ % if the definition is written into an index file. ++ \global\let\tiepenalty = \@M ++ \gdef\tie{\leavevmode\penalty\tiepenalty\ } ++} ++ ++% @: forces normal size whitespace following. ++\def\:{\spacefactor=1000 } ++ ++% @* forces a line break. ++\def\*{\hfil\break\hbox{}\ignorespaces} ++ ++% @/ allows a line break. ++\let\/=\allowbreak ++ ++% @. is an end-of-sentence period. ++\def\.{.\spacefactor=\endofsentencespacefactor\space} ++ ++% @! is an end-of-sentence bang. ++\def\!{!\spacefactor=\endofsentencespacefactor\space} ++ ++% @? is an end-of-sentence query. ++\def\?{?\spacefactor=\endofsentencespacefactor\space} ++ ++% @frenchspacing on|off says whether to put extra space after punctuation. ++% ++\def\onword{on} ++\def\offword{off} ++% ++\parseargdef\frenchspacing{% ++ \def\temp{#1}% ++ \ifx\temp\onword \plainfrenchspacing ++ \else\ifx\temp\offword \plainnonfrenchspacing ++ \else ++ \errhelp = \EMsimple ++ \errmessage{Unknown @frenchspacing option `\temp', must be on/off}% ++ \fi\fi ++} ++ ++% @w prevents a word break. Without the \leavevmode, @w at the ++% beginning of a paragraph, when TeX is still in vertical mode, would ++% produce a whole line of output instead of starting the paragraph. ++\def\w#1{\leavevmode\hbox{#1}} ++ ++% @group ... @end group forces ... to be all on one page, by enclosing ++% it in a TeX vbox. We use \vtop instead of \vbox to construct the box ++% to keep its height that of a normal line. According to the rules for ++% \topskip (p.114 of the TeXbook), the glue inserted is ++% max (\topskip - \ht (first item), 0). If that height is large, ++% therefore, no glue is inserted, and the space between the headline and ++% the text is small, which looks bad. ++% ++% Another complication is that the group might be very large. This can ++% cause the glue on the previous page to be unduly stretched, because it ++% does not have much material. In this case, it's better to add an ++% explicit \vfill so that the extra space is at the bottom. The ++% threshold for doing this is if the group is more than \vfilllimit ++% percent of a page (\vfilllimit can be changed inside of @tex). ++% ++\newbox\groupbox ++\def\vfilllimit{0.7} ++% ++\envdef\group{% ++ \ifnum\catcode`\^^M=\active \else ++ \errhelp = \groupinvalidhelp ++ \errmessage{@group invalid in context where filling is enabled}% ++ \fi ++ \startsavinginserts ++ % ++ \setbox\groupbox = \vtop\bgroup ++ % Do @comment since we are called inside an environment such as ++ % @example, where each end-of-line in the input causes an ++ % end-of-line in the output. We don't want the end-of-line after ++ % the `@group' to put extra space in the output. Since @group ++ % should appear on a line by itself (according to the Texinfo ++ % manual), we don't worry about eating any user text. ++ \comment ++} ++% ++% The \vtop produces a box with normal height and large depth; thus, TeX puts ++% \baselineskip glue before it, and (when the next line of text is done) ++% \lineskip glue after it. Thus, space below is not quite equal to space ++% above. But it's pretty close. ++\def\Egroup{% ++ % To get correct interline space between the last line of the group ++ % and the first line afterwards, we have to propagate \prevdepth. ++ \endgraf % Not \par, as it may have been set to \lisppar. ++ \global\dimen1 = \prevdepth ++ \egroup % End the \vtop. ++ % \dimen0 is the vertical size of the group's box. ++ \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox ++ % \dimen2 is how much space is left on the page (more or less). ++ \dimen2 = \pageheight \advance\dimen2 by -\pagetotal ++ % if the group doesn't fit on the current page, and it's a big big ++ % group, force a page break. ++ \ifdim \dimen0 > \dimen2 ++ \ifdim \pagetotal < \vfilllimit\pageheight ++ \page ++ \fi ++ \fi ++ \box\groupbox ++ \prevdepth = \dimen1 ++ \checkinserts ++} ++% ++% TeX puts in an \escapechar (i.e., `@') at the beginning of the help ++% message, so this ends up printing `@group can only ...'. ++% ++\newhelp\groupinvalidhelp{% ++group can only be used in environments such as @example,^^J% ++where each line of input produces a line of output.} ++ ++% @need space-in-mils ++% forces a page break if there is not space-in-mils remaining. ++ ++\newdimen\mil \mil=0.001in ++ ++% Old definition--didn't work. ++%\parseargdef\need{\par % ++%% This method tries to make TeX break the page naturally ++%% if the depth of the box does not fit. ++%{\baselineskip=0pt% ++%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak ++%\prevdepth=-1000pt ++%}} ++ ++\parseargdef\need{% ++ % Ensure vertical mode, so we don't make a big box in the middle of a ++ % paragraph. ++ \par ++ % ++ % If the @need value is less than one line space, it's useless. ++ \dimen0 = #1\mil ++ \dimen2 = \ht\strutbox ++ \advance\dimen2 by \dp\strutbox ++ \ifdim\dimen0 > \dimen2 ++ % ++ % Do a \strut just to make the height of this box be normal, so the ++ % normal leading is inserted relative to the preceding line. ++ % And a page break here is fine. ++ \vtop to #1\mil{\strut\vfil}% ++ % ++ % TeX does not even consider page breaks if a penalty added to the ++ % main vertical list is 10000 or more. But in order to see if the ++ % empty box we just added fits on the page, we must make it consider ++ % page breaks. On the other hand, we don't want to actually break the ++ % page after the empty box. So we use a penalty of 9999. ++ % ++ % There is an extremely small chance that TeX will actually break the ++ % page at this \penalty, if there are no other feasible breakpoints in ++ % sight. (If the user is using lots of big @group commands, which ++ % almost-but-not-quite fill up a page, TeX will have a hard time doing ++ % good page breaking, for example.) However, I could not construct an ++ % example where a page broke at this \penalty; if it happens in a real ++ % document, then we can reconsider our strategy. ++ \penalty9999 ++ % ++ % Back up by the size of the box, whether we did a page break or not. ++ \kern -#1\mil ++ % ++ % Do not allow a page break right after this kern. ++ \nobreak ++ \fi ++} ++ ++% @br forces paragraph break (and is undocumented). ++ ++\let\br = \par ++ ++% @page forces the start of a new page. ++% ++\def\page{\par\vfill\supereject} ++ ++% @exdent text.... ++% outputs text on separate line in roman font, starting at standard page margin ++ ++% This records the amount of indent in the innermost environment. ++% That's how much \exdent should take out. ++\newskip\exdentamount ++ ++% This defn is used inside fill environments such as @defun. ++\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break} ++ ++% This defn is used inside nofill environments such as @example. ++\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount ++ \leftline{\hskip\leftskip{\rm#1}}}} ++ ++% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current ++% paragraph. For more general purposes, use the \margin insertion ++% class. WHICH is `l' or `r'. ++% ++\newskip\inmarginspacing \inmarginspacing=1cm ++\def\strutdepth{\dp\strutbox} ++% ++\def\doinmargin#1#2{\strut\vadjust{% ++ \nobreak ++ \kern-\strutdepth ++ \vtop to \strutdepth{% ++ \baselineskip=\strutdepth ++ \vss ++ % if you have multiple lines of stuff to put here, you'll need to ++ % make the vbox yourself of the appropriate size. ++ \ifx#1l% ++ \llap{\ignorespaces #2\hskip\inmarginspacing}% ++ \else ++ \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}% ++ \fi ++ \null ++ }% ++}} ++\def\inleftmargin{\doinmargin l} ++\def\inrightmargin{\doinmargin r} ++% ++% @inmargin{TEXT [, RIGHT-TEXT]} ++% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right; ++% else use TEXT for both). ++% ++\def\inmargin#1{\parseinmargin #1,,\finish} ++\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing. ++ \setbox0 = \hbox{\ignorespaces #2}% ++ \ifdim\wd0 > 0pt ++ \def\lefttext{#1}% have both texts ++ \def\righttext{#2}% ++ \else ++ \def\lefttext{#1}% have only one text ++ \def\righttext{#1}% ++ \fi ++ % ++ \ifodd\pageno ++ \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin ++ \else ++ \def\temp{\inleftmargin\lefttext}% ++ \fi ++ \temp ++} ++ ++% @include file insert text of that file as input. ++% ++\def\include{\parseargusing\filenamecatcodes\includezzz} ++\def\includezzz#1{% ++ \pushthisfilestack ++ \def\thisfile{#1}% ++ {% ++ \makevalueexpandable ++ \def\temp{\input #1 }% ++ \expandafter ++ }\temp ++ \popthisfilestack ++} ++\def\filenamecatcodes{% ++ \catcode`\\=\other ++ \catcode`~=\other ++ \catcode`^=\other ++ \catcode`_=\other ++ \catcode`|=\other ++ \catcode`<=\other ++ \catcode`>=\other ++ \catcode`+=\other ++ \catcode`-=\other ++} ++ ++\def\pushthisfilestack{% ++ \expandafter\pushthisfilestackX\popthisfilestack\StackTerm ++} ++\def\pushthisfilestackX{% ++ \expandafter\pushthisfilestackY\thisfile\StackTerm ++} ++\def\pushthisfilestackY #1\StackTerm #2\StackTerm {% ++ \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}% ++} ++ ++\def\popthisfilestack{\errthisfilestackempty} ++\def\errthisfilestackempty{\errmessage{Internal error: ++ the stack of filenames is empty.}} ++ ++\def\thisfile{} ++ ++% @center line ++% outputs that line, centered. ++% ++\parseargdef\center{% ++ \ifhmode ++ \let\next\centerH ++ \else ++ \let\next\centerV ++ \fi ++ \next{\hfil \ignorespaces#1\unskip \hfil}% ++} ++\def\centerH#1{% ++ {% ++ \hfil\break ++ \advance\hsize by -\leftskip ++ \advance\hsize by -\rightskip ++ \line{#1}% ++ \break ++ }% ++} ++\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}} ++ ++% @sp n outputs n lines of vertical space ++ ++\parseargdef\sp{\vskip #1\baselineskip} ++ ++% @comment ...line which is ignored... ++% @c is the same as @comment ++% @ignore ... @end ignore is another way to write a comment ++ ++\def\comment{\begingroup \catcode`\^^M=\other% ++\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% ++\commentxxx} ++{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}} ++ ++\let\c=\comment ++ ++% @paragraphindent NCHARS ++% We'll use ems for NCHARS, close enough. ++% NCHARS can also be the word `asis' or `none'. ++% We cannot feasibly implement @paragraphindent asis, though. ++% ++\def\asisword{asis} % no translation, these are keywords ++\def\noneword{none} ++% ++\parseargdef\paragraphindent{% ++ \def\temp{#1}% ++ \ifx\temp\asisword ++ \else ++ \ifx\temp\noneword ++ \defaultparindent = 0pt ++ \else ++ \defaultparindent = #1em ++ \fi ++ \fi ++ \parindent = \defaultparindent ++} ++ ++% @exampleindent NCHARS ++% We'll use ems for NCHARS like @paragraphindent. ++% It seems @exampleindent asis isn't necessary, but ++% I preserve it to make it similar to @paragraphindent. ++\parseargdef\exampleindent{% ++ \def\temp{#1}% ++ \ifx\temp\asisword ++ \else ++ \ifx\temp\noneword ++ \lispnarrowing = 0pt ++ \else ++ \lispnarrowing = #1em ++ \fi ++ \fi ++} ++ ++% @firstparagraphindent WORD ++% If WORD is `none', then suppress indentation of the first paragraph ++% after a section heading. If WORD is `insert', then do indent at such ++% paragraphs. ++% ++% The paragraph indentation is suppressed or not by calling ++% \suppressfirstparagraphindent, which the sectioning commands do. ++% We switch the definition of this back and forth according to WORD. ++% By default, we suppress indentation. ++% ++\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent} ++\def\insertword{insert} ++% ++\parseargdef\firstparagraphindent{% ++ \def\temp{#1}% ++ \ifx\temp\noneword ++ \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent ++ \else\ifx\temp\insertword ++ \let\suppressfirstparagraphindent = \relax ++ \else ++ \errhelp = \EMsimple ++ \errmessage{Unknown @firstparagraphindent option `\temp'}% ++ \fi\fi ++} ++ ++% Here is how we actually suppress indentation. Redefine \everypar to ++% \kern backwards by \parindent, and then reset itself to empty. ++% ++% We also make \indent itself not actually do anything until the next ++% paragraph. ++% ++\gdef\dosuppressfirstparagraphindent{% ++ \gdef\indent{% ++ \restorefirstparagraphindent ++ \indent ++ }% ++ \gdef\noindent{% ++ \restorefirstparagraphindent ++ \noindent ++ }% ++ \global\everypar = {% ++ \kern -\parindent ++ \restorefirstparagraphindent ++ }% ++} ++ ++\gdef\restorefirstparagraphindent{% ++ \global \let \indent = \ptexindent ++ \global \let \noindent = \ptexnoindent ++ \global \everypar = {}% ++} ++ ++ ++% @asis just yields its argument. Used with @table, for example. ++% ++\def\asis#1{#1} ++ ++% @math outputs its argument in math mode. ++% ++% One complication: _ usually means subscripts, but it could also mean ++% an actual _ character, as in @math{@var{some_variable} + 1}. So make ++% _ active, and distinguish by seeing if the current family is \slfam, ++% which is what @var uses. ++{ ++ \catcode`\_ = \active ++ \gdef\mathunderscore{% ++ \catcode`\_=\active ++ \def_{\ifnum\fam=\slfam \_\else\sb\fi}% ++ } ++} ++% Another complication: we want \\ (and @\) to output a \ character. ++% FYI, plain.tex uses \\ as a temporary control sequence (why?), but ++% this is not advertised and we don't care. Texinfo does not ++% otherwise define @\. ++% ++% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\. ++\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi} ++% ++\def\math{% ++ \tex ++ \mathunderscore ++ \let\\ = \mathbackslash ++ \mathactive ++ $\finishmath ++} ++\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. ++ ++% Some active characters (such as <) are spaced differently in math. ++% We have to reset their definitions in case the @math was an argument ++% to a command which sets the catcodes (such as @item or @section). ++% ++{ ++ \catcode`^ = \active ++ \catcode`< = \active ++ \catcode`> = \active ++ \catcode`+ = \active ++ \gdef\mathactive{% ++ \let^ = \ptexhat ++ \let< = \ptexless ++ \let> = \ptexgtr ++ \let+ = \ptexplus ++ } ++} ++ ++% @bullet and @minus need the same treatment as @math, just above. ++\def\bullet{$\ptexbullet$} ++\def\minus{$-$} ++ ++% @dots{} outputs an ellipsis using the current font. ++% We do .5em per period so that it has the same spacing in the cm ++% typewriter fonts as three actual period characters; on the other hand, ++% in other typewriter fonts three periods are wider than 1.5em. So do ++% whichever is larger. ++% ++\def\dots{% ++ \leavevmode ++ \setbox0=\hbox{...}% get width of three periods ++ \ifdim\wd0 > 1.5em ++ \dimen0 = \wd0 ++ \else ++ \dimen0 = 1.5em ++ \fi ++ \hbox to \dimen0{% ++ \hskip 0pt plus.25fil ++ .\hskip 0pt plus1fil ++ .\hskip 0pt plus1fil ++ .\hskip 0pt plus.5fil ++ }% ++} ++ ++% @enddots{} is an end-of-sentence ellipsis. ++% ++\def\enddots{% ++ \dots ++ \spacefactor=\endofsentencespacefactor ++} ++ ++% @comma{} is so commas can be inserted into text without messing up ++% Texinfo's parsing. ++% ++\let\comma = , ++ ++% @refill is a no-op. ++\let\refill=\relax ++ ++% If working on a large document in chapters, it is convenient to ++% be able to disable indexing, cross-referencing, and contents, for test runs. ++% This is done with @novalidate (before @setfilename). ++% ++\newif\iflinks \linkstrue % by default we want the aux files. ++\let\novalidate = \linksfalse ++ ++% @setfilename is done at the beginning of every texinfo file. ++% So open here the files we need to have open while reading the input. ++% This makes it possible to make a .fmt file for texinfo. ++\def\setfilename{% ++ \fixbackslash % Turn off hack to swallow `\input texinfo'. ++ \iflinks ++ \tryauxfile ++ % Open the new aux file. TeX will close it automatically at exit. ++ \immediate\openout\auxfile=\jobname.aux ++ \fi % \openindices needs to do some work in any case. ++ \openindices ++ \let\setfilename=\comment % Ignore extra @setfilename cmds. ++ % ++ % If texinfo.cnf is present on the system, read it. ++ % Useful for site-wide @afourpaper, etc. ++ \openin 1 texinfo.cnf ++ \ifeof 1 \else \input texinfo.cnf \fi ++ \closein 1 ++ % ++ \comment % Ignore the actual filename. ++} ++ ++% Called from \setfilename. ++% ++\def\openindices{% ++ \newindex{cp}% ++ \newcodeindex{fn}% ++ \newcodeindex{vr}% ++ \newcodeindex{tp}% ++ \newcodeindex{ky}% ++ \newcodeindex{pg}% ++} ++ ++% @bye. ++\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} ++ ++ ++\message{pdf,} ++% adobe `portable' document format ++\newcount\tempnum ++\newcount\lnkcount ++\newtoks\filename ++\newcount\filenamelength ++\newcount\pgn ++\newtoks\toksA ++\newtoks\toksB ++\newtoks\toksC ++\newtoks\toksD ++\newbox\boxA ++\newcount\countA ++\newif\ifpdf ++\newif\ifpdfmakepagedest ++ ++% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1 ++% can be set). So we test for \relax and 0 as well as \undefined, ++% borrowed from ifpdf.sty. ++\ifx\pdfoutput\undefined ++\else ++ \ifx\pdfoutput\relax ++ \else ++ \ifcase\pdfoutput ++ \else ++ \pdftrue ++ \fi ++ \fi ++\fi ++ ++% PDF uses PostScript string constants for the names of xref targets, ++% for display in the outlines, and in other places. Thus, we have to ++% double any backslashes. Otherwise, a name like "\node" will be ++% interpreted as a newline (\n), followed by o, d, e. Not good. ++% http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html ++% (and related messages, the final outcome is that it is up to the TeX ++% user to double the backslashes and otherwise make the string valid, so ++% that's what we do). ++ ++% double active backslashes. ++% ++{\catcode`\@=0 \catcode`\\=\active ++ @gdef@activebackslashdouble{% ++ @catcode`@\=@active ++ @let\=@doublebackslash} ++} ++ ++% To handle parens, we must adopt a different approach, since parens are ++% not active characters. hyperref.dtx (which has the same problem as ++% us) handles it with this amazing macro to replace tokens, with minor ++% changes for Texinfo. It is included here under the GPL by permission ++% from the author, Heiko Oberdiek. ++% ++% #1 is the tokens to replace. ++% #2 is the replacement. ++% #3 is the control sequence with the string. ++% ++\def\HyPsdSubst#1#2#3{% ++ \def\HyPsdReplace##1#1##2\END{% ++ ##1% ++ \ifx\\##2\\% ++ \else ++ #2% ++ \HyReturnAfterFi{% ++ \HyPsdReplace##2\END ++ }% ++ \fi ++ }% ++ \xdef#3{\expandafter\HyPsdReplace#3#1\END}% ++} ++\long\def\HyReturnAfterFi#1\fi{\fi#1} ++ ++% #1 is a control sequence in which to do the replacements. ++\def\backslashparens#1{% ++ \xdef#1{#1}% redefine it as its expansion; the definition is simply ++ % \lastnode when called from \setref -> \pdfmkdest. ++ \HyPsdSubst{(}{\realbackslash(}{#1}% ++ \HyPsdSubst{)}{\realbackslash)}{#1}% ++} ++ ++\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images ++with PDF output, and none of those formats could be found. (.eps cannot ++be supported due to the design of the PDF format; use regular TeX (DVI ++output) for that.)} ++ ++\ifpdf ++ \input pdfcolor ++ \pdfcatalog{/PageMode /UseOutlines} ++ % ++ % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto). ++ \def\dopdfimage#1#2#3{% ++ \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% ++ \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% ++ % ++ % pdftex (and the PDF format) support .png, .jpg, .pdf (among ++ % others). Let's try in that order. ++ \let\pdfimgext=\empty ++ \begingroup ++ \openin 1 #1.png \ifeof 1 ++ \openin 1 #1.jpg \ifeof 1 ++ \openin 1 #1.jpeg \ifeof 1 ++ \openin 1 #1.JPG \ifeof 1 ++ \openin 1 #1.pdf \ifeof 1 ++ \errhelp = \nopdfimagehelp ++ \errmessage{Could not find image file #1 for pdf}% ++ \else \gdef\pdfimgext{pdf}% ++ \fi ++ \else \gdef\pdfimgext{JPG}% ++ \fi ++ \else \gdef\pdfimgext{jpeg}% ++ \fi ++ \else \gdef\pdfimgext{jpg}% ++ \fi ++ \else \gdef\pdfimgext{png}% ++ \fi ++ \closein 1 ++ \endgroup ++ % ++ % without \immediate, pdftex seg faults when the same image is ++ % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.) ++ \ifnum\pdftexversion < 14 ++ \immediate\pdfimage ++ \else ++ \immediate\pdfximage ++ \fi ++ \ifdim \wd0 >0pt width \imagewidth \fi ++ \ifdim \wd2 >0pt height \imageheight \fi ++ \ifnum\pdftexversion<13 ++ #1.\pdfimgext ++ \else ++ {#1.\pdfimgext}% ++ \fi ++ \ifnum\pdftexversion < 14 \else ++ \pdfrefximage \pdflastximage ++ \fi} ++ % ++ \def\pdfmkdest#1{{% ++ % We have to set dummies so commands such as @code, and characters ++ % such as \, aren't expanded when present in a section title. ++ \indexnofonts ++ \turnoffactive ++ \activebackslashdouble ++ \makevalueexpandable ++ \def\pdfdestname{#1}% ++ \backslashparens\pdfdestname ++ \safewhatsit{\pdfdest name{\pdfdestname} xyz}% ++ }} ++ % ++ % used to mark target names; must be expandable. ++ \def\pdfmkpgn#1{#1} ++ % ++ % by default, use a color that is dark enough to print on paper as ++ % nearly black, but still distinguishable for online viewing. ++ % (Defined in pdfcolor.tex.) ++ \let\urlcolor = \BrickRed ++ \let\linkcolor = \BrickRed ++ \def\endlink{\Black\pdfendlink} ++ % ++ % Adding outlines to PDF; macros for calculating structure of outlines ++ % come from Petr Olsak ++ \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0% ++ \else \csname#1\endcsname \fi} ++ \def\advancenumber#1{\tempnum=\expnumber{#1}\relax ++ \advance\tempnum by 1 ++ \expandafter\xdef\csname#1\endcsname{\the\tempnum}} ++ % ++ % #1 is the section text, which is what will be displayed in the ++ % outline by the pdf viewer. #2 is the pdf expression for the number ++ % of subentries (or empty, for subsubsections). #3 is the node text, ++ % which might be empty if this toc entry had no corresponding node. ++ % #4 is the page number ++ % ++ \def\dopdfoutline#1#2#3#4{% ++ % Generate a link to the node text if that exists; else, use the ++ % page number. We could generate a destination for the section ++ % text in the case where a section has no node, but it doesn't ++ % seem worth the trouble, since most documents are normally structured. ++ \def\pdfoutlinedest{#3}% ++ \ifx\pdfoutlinedest\empty ++ \def\pdfoutlinedest{#4}% ++ \else ++ % Doubled backslashes in the name. ++ {\activebackslashdouble \xdef\pdfoutlinedest{#3}% ++ \backslashparens\pdfoutlinedest}% ++ \fi ++ % ++ % Also double the backslashes in the display string. ++ {\activebackslashdouble \xdef\pdfoutlinetext{#1}% ++ \backslashparens\pdfoutlinetext}% ++ % ++ \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}% ++ } ++ % ++ \def\pdfmakeoutlines{% ++ \begingroup ++ % Thanh's hack / proper braces in bookmarks ++ \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace ++ \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace ++ % ++ % Read toc silently, to get counts of subentries for \pdfoutline. ++ \def\numchapentry##1##2##3##4{% ++ \def\thischapnum{##2}% ++ \def\thissecnum{0}% ++ \def\thissubsecnum{0}% ++ }% ++ \def\numsecentry##1##2##3##4{% ++ \advancenumber{chap\thischapnum}% ++ \def\thissecnum{##2}% ++ \def\thissubsecnum{0}% ++ }% ++ \def\numsubsecentry##1##2##3##4{% ++ \advancenumber{sec\thissecnum}% ++ \def\thissubsecnum{##2}% ++ }% ++ \def\numsubsubsecentry##1##2##3##4{% ++ \advancenumber{subsec\thissubsecnum}% ++ }% ++ \def\thischapnum{0}% ++ \def\thissecnum{0}% ++ \def\thissubsecnum{0}% ++ % ++ % use \def rather than \let here because we redefine \chapentry et ++ % al. a second time, below. ++ \def\appentry{\numchapentry}% ++ \def\appsecentry{\numsecentry}% ++ \def\appsubsecentry{\numsubsecentry}% ++ \def\appsubsubsecentry{\numsubsubsecentry}% ++ \def\unnchapentry{\numchapentry}% ++ \def\unnsecentry{\numsecentry}% ++ \def\unnsubsecentry{\numsubsecentry}% ++ \def\unnsubsubsecentry{\numsubsubsecentry}% ++ \readdatafile{toc}% ++ % ++ % Read toc second time, this time actually producing the outlines. ++ % The `-' means take the \expnumber as the absolute number of ++ % subentries, which we calculated on our first read of the .toc above. ++ % ++ % We use the node names as the destinations. ++ \def\numchapentry##1##2##3##4{% ++ \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}% ++ \def\numsecentry##1##2##3##4{% ++ \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}% ++ \def\numsubsecentry##1##2##3##4{% ++ \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}% ++ \def\numsubsubsecentry##1##2##3##4{% count is always zero ++ \dopdfoutline{##1}{}{##3}{##4}}% ++ % ++ % PDF outlines are displayed using system fonts, instead of ++ % document fonts. Therefore we cannot use special characters, ++ % since the encoding is unknown. For example, the eogonek from ++ % Latin 2 (0xea) gets translated to a | character. Info from ++ % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100. ++ % ++ % xx to do this right, we have to translate 8-bit characters to ++ % their "best" equivalent, based on the @documentencoding. Right ++ % now, I guess we'll just let the pdf reader have its way. ++ \indexnofonts ++ \setupdatafile ++ \catcode`\\=\active \otherbackslash ++ \input \tocreadfilename ++ \endgroup ++ } ++ % ++ \def\skipspaces#1{\def\PP{#1}\def\D{|}% ++ \ifx\PP\D\let\nextsp\relax ++ \else\let\nextsp\skipspaces ++ \ifx\p\space\else\addtokens{\filename}{\PP}% ++ \advance\filenamelength by 1 ++ \fi ++ \fi ++ \nextsp} ++ \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax} ++ \ifnum\pdftexversion < 14 ++ \let \startlink \pdfannotlink ++ \else ++ \let \startlink \pdfstartlink ++ \fi ++ % make a live url in pdf output. ++ \def\pdfurl#1{% ++ \begingroup ++ % it seems we really need yet another set of dummies; have not ++ % tried to figure out what each command should do in the context ++ % of @url. for now, just make @/ a no-op, that's the only one ++ % people have actually reported a problem with. ++ % ++ \normalturnoffactive ++ \def\@{@}% ++ \let\/=\empty ++ \makevalueexpandable ++ \leavevmode\urlcolor ++ \startlink attr{/Border [0 0 0]}% ++ user{/Subtype /Link /A << /S /URI /URI (#1) >>}% ++ \endgroup} ++ \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} ++ \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} ++ \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} ++ \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}} ++ \def\maketoks{% ++ \expandafter\poptoks\the\toksA|ENDTOKS|\relax ++ \ifx\first0\adn0 ++ \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3 ++ \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6 ++ \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9 ++ \else ++ \ifnum0=\countA\else\makelink\fi ++ \ifx\first.\let\next=\done\else ++ \let\next=\maketoks ++ \addtokens{\toksB}{\the\toksD} ++ \ifx\first,\addtokens{\toksB}{\space}\fi ++ \fi ++ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi ++ \next} ++ \def\makelink{\addtokens{\toksB}% ++ {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0} ++ \def\pdflink#1{% ++ \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}} ++ \linkcolor #1\endlink} ++ \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} ++\else ++ \let\pdfmkdest = \gobble ++ \let\pdfurl = \gobble ++ \let\endlink = \relax ++ \let\linkcolor = \relax ++ \let\pdfmakeoutlines = \relax ++\fi % \ifx\pdfoutput ++ ++ ++\message{fonts,} ++ ++% Change the current font style to #1, remembering it in \curfontstyle. ++% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in ++% italics, not bold italics. ++% ++\def\setfontstyle#1{% ++ \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd. ++ \csname ten#1\endcsname % change the current font ++} ++ ++% Select #1 fonts with the current style. ++% ++\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname} ++ ++\def\rm{\fam=0 \setfontstyle{rm}} ++\def\it{\fam=\itfam \setfontstyle{it}} ++\def\sl{\fam=\slfam \setfontstyle{sl}} ++\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} ++\def\tt{\fam=\ttfam \setfontstyle{tt}} ++ ++% Texinfo sort of supports the sans serif font style, which plain TeX does not. ++% So we set up a \sf. ++\newfam\sffam ++\def\sf{\fam=\sffam \setfontstyle{sf}} ++\let\li = \sf % Sometimes we call it \li, not \sf. ++ ++% We don't need math for this font style. ++\def\ttsl{\setfontstyle{ttsl}} ++ ++ ++% Default leading. ++\newdimen\textleading \textleading = 13.2pt ++ ++% Set the baselineskip to #1, and the lineskip and strut size ++% correspondingly. There is no deep meaning behind these magic numbers ++% used as factors; they just match (closely enough) what Knuth defined. ++% ++\def\lineskipfactor{.08333} ++\def\strutheightpercent{.70833} ++\def\strutdepthpercent {.29167} ++% ++\def\setleading#1{% ++ \normalbaselineskip = #1\relax ++ \normallineskip = \lineskipfactor\normalbaselineskip ++ \normalbaselines ++ \setbox\strutbox =\hbox{% ++ \vrule width0pt height\strutheightpercent\baselineskip ++ depth \strutdepthpercent \baselineskip ++ }% ++} ++ ++% ++% PDF CMaps. See also LaTeX's t1.cmap. ++% ++% \cmapOT1 ++\ifpdf ++ \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}% ++ }% ++\else ++ \expandafter\let\csname cmapOT1\endcsname\gobble ++ \expandafter\let\csname cmapOT1IT\endcsname\gobble ++ \expandafter\let\csname cmapOT1TT\endcsname\gobble ++\fi ++ ++ ++% Set the font macro #1 to the font named #2, adding on the ++% specified font prefix (normally `cm'). ++% #3 is the font's design size, #4 is a scale factor, #5 is the CMap ++% encoding (currently only OT1, OT1IT and OT1TT are allowed, pass ++% empty to omit). ++\def\setfont#1#2#3#4#5{% ++ \font#1=\fontprefix#2#3 scaled #4 ++ \csname cmap#5\endcsname#1% ++} ++% This is what gets called when #5 of \setfont is empty. ++\let\cmap\gobble ++ ++ ++% Use cm as the default font prefix. ++% To specify the font prefix, you must define \fontprefix ++% before you read in texinfo.tex. ++\ifx\fontprefix\undefined ++\def\fontprefix{cm} ++\fi ++% Support font families that don't use the same naming scheme as CM. ++\def\rmshape{r} ++\def\rmbshape{bx} %where the normal face is bold ++\def\bfshape{b} ++\def\bxshape{bx} ++\def\ttshape{tt} ++\def\ttbshape{tt} ++\def\ttslshape{sltt} ++\def\itshape{ti} ++\def\itbshape{bxti} ++\def\slshape{sl} ++\def\slbshape{bxsl} ++\def\sfshape{ss} ++\def\sfbshape{ss} ++\def\scshape{csc} ++\def\scbshape{csc} ++ ++% Definitions for a main text size of 11pt. This is the default in ++% Texinfo. ++% ++\def\definetextfontsizexi{% ++% Text fonts (11.2pt, magstep1). ++\def\textnominalsize{11pt} ++\edef\mainmagstep{\magstephalf} ++\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} ++\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} ++\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} ++\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} ++\setfont\textsl\slshape{10}{\mainmagstep}{OT1} ++\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} ++\setfont\textsc\scshape{10}{\mainmagstep}{OT1} ++\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} ++\font\texti=cmmi10 scaled \mainmagstep ++\font\textsy=cmsy10 scaled \mainmagstep ++ ++% A few fonts for @defun names and args. ++\setfont\defbf\bfshape{10}{\magstep1}{OT1} ++\setfont\deftt\ttshape{10}{\magstep1}{OT1TT} ++\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT} ++\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} ++ ++% Fonts for indices, footnotes, small examples (9pt). ++\def\smallnominalsize{9pt} ++\setfont\smallrm\rmshape{9}{1000}{OT1} ++\setfont\smalltt\ttshape{9}{1000}{OT1TT} ++\setfont\smallbf\bfshape{10}{900}{OT1} ++\setfont\smallit\itshape{9}{1000}{OT1IT} ++\setfont\smallsl\slshape{9}{1000}{OT1} ++\setfont\smallsf\sfshape{9}{1000}{OT1} ++\setfont\smallsc\scshape{10}{900}{OT1} ++\setfont\smallttsl\ttslshape{10}{900}{OT1TT} ++\font\smalli=cmmi9 ++\font\smallsy=cmsy9 ++ ++% 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 ++ ++% Fonts for title page (20.4pt): ++\def\titlenominalsize{20pt} ++\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} ++\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} ++\setfont\titlesl\slbshape{10}{\magstep4}{OT1} ++\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} ++\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} ++\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} ++\let\titlebf=\titlerm ++\setfont\titlesc\scbshape{10}{\magstep4}{OT1} ++\font\titlei=cmmi12 scaled \magstep3 ++\font\titlesy=cmsy10 scaled \magstep4 ++\def\authorrm{\secrm} ++\def\authortt{\sectt} ++ ++% 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 ++ ++% Section fonts (14.4pt). ++\def\secnominalsize{14pt} ++\setfont\secrm\rmbshape{12}{\magstep1}{OT1} ++\setfont\secit\itbshape{10}{\magstep2}{OT1IT} ++\setfont\secsl\slbshape{10}{\magstep2}{OT1} ++\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT} ++\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT} ++\setfont\secsf\sfbshape{12}{\magstep1}{OT1} ++\let\secbf\secrm ++\setfont\secsc\scbshape{10}{\magstep2}{OT1} ++\font\seci=cmmi12 scaled \magstep1 ++\font\secsy=cmsy10 scaled \magstep2 ++ ++% 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 ++ ++% Reduced fonts for @acro in text (10pt). ++\def\reducednominalsize{10pt} ++\setfont\reducedrm\rmshape{10}{1000}{OT1} ++\setfont\reducedtt\ttshape{10}{1000}{OT1TT} ++\setfont\reducedbf\bfshape{10}{1000}{OT1} ++\setfont\reducedit\itshape{10}{1000}{OT1IT} ++\setfont\reducedsl\slshape{10}{1000}{OT1} ++\setfont\reducedsf\sfshape{10}{1000}{OT1} ++\setfont\reducedsc\scshape{10}{1000}{OT1} ++\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT} ++\font\reducedi=cmmi10 ++\font\reducedsy=cmsy10 ++ ++% reset the current fonts ++\textfonts ++\rm ++} % end of 11pt text font size definitions ++ ++ ++% Definitions to make the main text be 10pt Computer Modern, with ++% section, chapter, etc., sizes following suit. This is for the GNU ++% Press printing of the Emacs 22 manual. Maybe other manuals in the ++% future. Used with @smallbook, which sets the leading to 12pt. ++% ++\def\definetextfontsizex{% ++% Text fonts (10pt). ++\def\textnominalsize{10pt} ++\edef\mainmagstep{1000} ++\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} ++\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} ++\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} ++\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} ++\setfont\textsl\slshape{10}{\mainmagstep}{OT1} ++\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} ++\setfont\textsc\scshape{10}{\mainmagstep}{OT1} ++\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} ++\font\texti=cmmi10 scaled \mainmagstep ++\font\textsy=cmsy10 scaled \mainmagstep ++ ++% A few fonts for @defun names and args. ++\setfont\defbf\bfshape{10}{\magstephalf}{OT1} ++\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT} ++\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT} ++\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} ++ ++% Fonts for indices, footnotes, small examples (9pt). ++\def\smallnominalsize{9pt} ++\setfont\smallrm\rmshape{9}{1000}{OT1} ++\setfont\smalltt\ttshape{9}{1000}{OT1TT} ++\setfont\smallbf\bfshape{10}{900}{OT1} ++\setfont\smallit\itshape{9}{1000}{OT1IT} ++\setfont\smallsl\slshape{9}{1000}{OT1} ++\setfont\smallsf\sfshape{9}{1000}{OT1} ++\setfont\smallsc\scshape{10}{900}{OT1} ++\setfont\smallttsl\ttslshape{10}{900}{OT1TT} ++\font\smalli=cmmi9 ++\font\smallsy=cmsy9 ++ ++% 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 ++ ++% Fonts for title page (20.4pt): ++\def\titlenominalsize{20pt} ++\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} ++\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} ++\setfont\titlesl\slbshape{10}{\magstep4}{OT1} ++\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} ++\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} ++\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} ++\let\titlebf=\titlerm ++\setfont\titlesc\scbshape{10}{\magstep4}{OT1} ++\font\titlei=cmmi12 scaled \magstep3 ++\font\titlesy=cmsy10 scaled \magstep4 ++\def\authorrm{\secrm} ++\def\authortt{\sectt} ++ ++% 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 ++ ++% 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 ++ ++% 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 ++ ++% Reduced fonts for @acro in text (9pt). ++\def\reducednominalsize{9pt} ++\setfont\reducedrm\rmshape{9}{1000}{OT1} ++\setfont\reducedtt\ttshape{9}{1000}{OT1TT} ++\setfont\reducedbf\bfshape{10}{900}{OT1} ++\setfont\reducedit\itshape{9}{1000}{OT1IT} ++\setfont\reducedsl\slshape{9}{1000}{OT1} ++\setfont\reducedsf\sfshape{9}{1000}{OT1} ++\setfont\reducedsc\scshape{10}{900}{OT1} ++\setfont\reducedttsl\ttslshape{10}{900}{OT1TT} ++\font\reducedi=cmmi9 ++\font\reducedsy=cmsy9 ++ ++% reduce space between paragraphs ++\divide\parskip by 2 ++ ++% reset the current fonts ++\textfonts ++\rm ++} % end of 10pt text font size definitions ++ ++ ++% We provide the user-level command ++% @fonttextsize 10 ++% (or 11) to redefine the text font size. pt is assumed. ++% ++\def\xword{10} ++\def\xiword{11} ++% ++\parseargdef\fonttextsize{% ++ \def\textsizearg{#1}% ++ \wlog{doing @fonttextsize \textsizearg}% ++ % ++ % Set \globaldefs so that documents can use this inside @tex, since ++ % makeinfo 4.8 does not support it, but we need it nonetheless. ++ % ++ \begingroup \globaldefs=1 ++ \ifx\textsizearg\xword \definetextfontsizex ++ \else \ifx\textsizearg\xiword \definetextfontsizexi ++ \else ++ \errhelp=\EMsimple ++ \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'} ++ \fi\fi ++ \endgroup ++} ++ ++ ++% In order for the font changes to affect most math symbols and letters, ++% we have to define the \textfont of the standard families. Since ++% texinfo doesn't allow for producing subscripts and superscripts except ++% in the main text, we don't bother to reset \scriptfont and ++% \scriptscriptfont (which would also require loading a lot more fonts). ++% ++\def\resetmathfonts{% ++ \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy ++ \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf ++ \textfont\ttfam=\tentt \textfont\sffam=\tensf ++} ++ ++% The font-changing commands redefine the meanings of \tenSTYLE, instead ++% of just \STYLE. We do this because \STYLE needs to also set the ++% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire ++% \tenSTYLE to set the current font. ++% ++% Each font-changing command also sets the names \lsize (one size lower) ++% and \lllsize (three sizes lower). These relative commands are used in ++% the LaTeX logo and acronyms. ++% ++% This all needs generalizing, badly. ++% ++\def\textfonts{% ++ \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl ++ \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc ++ \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy ++ \let\tenttsl=\textttsl ++ \def\curfontsize{text}% ++ \def\lsize{reduced}\def\lllsize{smaller}% ++ \resetmathfonts \setleading{\textleading}} ++\def\titlefonts{% ++ \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl ++ \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc ++ \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy ++ \let\tenttsl=\titlettsl ++ \def\curfontsize{title}% ++ \def\lsize{chap}\def\lllsize{subsec}% ++ \resetmathfonts \setleading{25pt}} ++\def\titlefont#1{{\titlefonts\rm #1}} ++\def\chapfonts{% ++ \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl ++ \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc ++ \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy ++ \let\tenttsl=\chapttsl ++ \def\curfontsize{chap}% ++ \def\lsize{sec}\def\lllsize{text}% ++ \resetmathfonts \setleading{19pt}} ++\def\secfonts{% ++ \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl ++ \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc ++ \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy ++ \let\tenttsl=\secttsl ++ \def\curfontsize{sec}% ++ \def\lsize{subsec}\def\lllsize{reduced}% ++ \resetmathfonts \setleading{16pt}} ++\def\subsecfonts{% ++ \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl ++ \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc ++ \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy ++ \let\tenttsl=\ssecttsl ++ \def\curfontsize{ssec}% ++ \def\lsize{text}\def\lllsize{small}% ++ \resetmathfonts \setleading{15pt}} ++\let\subsubsecfonts = \subsecfonts ++\def\reducedfonts{% ++ \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl ++ \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc ++ \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy ++ \let\tenttsl=\reducedttsl ++ \def\curfontsize{reduced}% ++ \def\lsize{small}\def\lllsize{smaller}% ++ \resetmathfonts \setleading{10.5pt}} ++\def\smallfonts{% ++ \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl ++ \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc ++ \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy ++ \let\tenttsl=\smallttsl ++ \def\curfontsize{small}% ++ \def\lsize{smaller}\def\lllsize{smaller}% ++ \resetmathfonts \setleading{10.5pt}} ++\def\smallerfonts{% ++ \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl ++ \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc ++ \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy ++ \let\tenttsl=\smallerttsl ++ \def\curfontsize{smaller}% ++ \def\lsize{smaller}\def\lllsize{smaller}% ++ \resetmathfonts \setleading{9.5pt}} ++ ++% Set the fonts to use with the @small... environments. ++\let\smallexamplefonts = \smallfonts ++ ++% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample ++% can fit this many characters: ++% 8.5x11=86 smallbook=72 a4=90 a5=69 ++% If we use \scriptfonts (8pt), then we can fit this many characters: ++% 8.5x11=90+ smallbook=80 a4=90+ a5=77 ++% For me, subjectively, the few extra characters that fit aren't worth ++% the additional smallness of 8pt. So I'm making the default 9pt. ++% ++% By the way, for comparison, here's what fits with @example (10pt): ++% 8.5x11=71 smallbook=60 a4=75 a5=58 ++% ++% I wish the USA used A4 paper. ++% --karl, 24jan03. ++ ++ ++% Set up the default fonts, so we can use them for creating boxes. ++% ++\definetextfontsizexi ++ ++% Define these so they can be easily changed for other fonts. ++\def\angleleft{$\langle$} ++\def\angleright{$\rangle$} ++ ++% Count depth in font-changes, for error checks ++\newcount\fontdepth \fontdepth=0 ++ ++% Fonts for short table of contents. ++\setfont\shortcontrm\rmshape{12}{1000}{OT1} ++\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12 ++\setfont\shortcontsl\slshape{12}{1000}{OT1} ++\setfont\shortconttt\ttshape{12}{1000}{OT1TT} ++ ++%% Add scribe-like font environments, plus @l for inline lisp (usually sans ++%% serif) and @ii for TeX italic ++ ++% \smartitalic{ARG} outputs arg in italics, followed by an italic correction ++% unless the following character is such as not to need one. ++\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else ++ \ptexslash\fi\fi\fi} ++\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx} ++\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx} ++ ++% like \smartslanted except unconditionally uses \ttsl. ++% @var is set to this for defun arguments. ++\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx} ++ ++% like \smartslanted except unconditionally use \sl. We never want ++% ttsl for book titles, do we? ++\def\cite#1{{\sl #1}\futurelet\next\smartitalicx} ++ ++\let\i=\smartitalic ++\let\slanted=\smartslanted ++\let\var=\smartslanted ++\let\dfn=\smartslanted ++\let\emph=\smartitalic ++ ++% @b, explicit bold. ++\def\b#1{{\bf #1}} ++\let\strong=\b ++ ++% @sansserif, explicit sans. ++\def\sansserif#1{{\sf #1}} ++ ++% We can't just use \exhyphenpenalty, because that only has effect at ++% the end of a paragraph. Restore normal hyphenation at the end of the ++% group within which \nohyphenation is presumably called. ++% ++\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} ++\def\restorehyphenation{\hyphenchar\font = `- } ++ ++% Set sfcode to normal for the chars that usually have another value. ++% Can't use plain's \frenchspacing because it uses the `\x notation, and ++% sometimes \x has an active definition that messes things up. ++% ++\catcode`@=11 ++ \def\plainfrenchspacing{% ++ \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m ++ \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m ++ \def\endofsentencespacefactor{1000}% for @. and friends ++ } ++ \def\plainnonfrenchspacing{% ++ \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000 ++ \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250 ++ \def\endofsentencespacefactor{3000}% for @. and friends ++ } ++\catcode`@=\other ++\def\endofsentencespacefactor{3000}% default ++ ++\def\t#1{% ++ {\tt \rawbackslash \plainfrenchspacing #1}% ++ \null ++} ++\def\samp#1{`\tclose{#1}'\null} ++\setfont\keyrm\rmshape{8}{1000}{OT1} ++\font\keysy=cmsy9 ++\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{% ++ \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% ++ \vbox{\hrule\kern-0.4pt ++ \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% ++ \kern-0.4pt\hrule}% ++ \kern-.06em\raise0.4pt\hbox{\angleright}}}} ++\def\key #1{{\nohyphenation \uppercase{#1}}\null} ++% The old definition, with no lozenge: ++%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} ++\def\ctrl #1{{\tt \rawbackslash \hat}#1} ++ ++% @file, @option are the same as @samp. ++\let\file=\samp ++\let\option=\samp ++ ++% @code is a modification of @t, ++% which makes spaces the same size as normal in the surrounding text. ++\def\tclose#1{% ++ {% ++ % Change normal interword space to be same as for the current font. ++ \spaceskip = \fontdimen2\font ++ % ++ % Switch to typewriter. ++ \tt ++ % ++ % But `\ ' produces the large typewriter interword space. ++ \def\ {{\spaceskip = 0pt{} }}% ++ % ++ % Turn off hyphenation. ++ \nohyphenation ++ % ++ \rawbackslash ++ \plainfrenchspacing ++ #1% ++ }% ++ \null ++} ++ ++% We *must* turn on hyphenation at `-' and `_' in @code. ++% Otherwise, it is too hard to avoid overfull hboxes ++% in the Emacs manual, the Library manual, etc. ++ ++% Unfortunately, TeX uses one parameter (\hyphenchar) to control ++% both hyphenation at - and hyphenation within words. ++% We must therefore turn them both off (\tclose does that) ++% and arrange explicitly to hyphenate at a dash. ++% -- rms. ++{ ++ \catcode`\-=\active \catcode`\_=\active ++ \catcode`\'=\active \catcode`\`=\active ++ % ++ \global\def\code{\begingroup ++ \catcode\rquoteChar=\active \catcode\lquoteChar=\active ++ \let'\codequoteright \let`\codequoteleft ++ % ++ \catcode\dashChar=\active \catcode\underChar=\active ++ \ifallowcodebreaks ++ \let-\codedash ++ \let_\codeunder ++ \else ++ \let-\realdash ++ \let_\realunder ++ \fi ++ \codex ++ } ++} ++ ++\def\realdash{-} ++\def\codedash{-\discretionary{}{}{}} ++\def\codeunder{% ++ % this is all so @math{@code{var_name}+1} can work. In math mode, _ ++ % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) ++ % will therefore expand the active definition of _, which is us ++ % (inside @code that is), therefore an endless loop. ++ \ifusingtt{\ifmmode ++ \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_. ++ \else\normalunderscore \fi ++ \discretionary{}{}{}}% ++ {\_}% ++} ++\def\codex #1{\tclose{#1}\endgroup} ++ ++% An additional complication: the above will allow breaks after, e.g., ++% each of the four underscores in __typeof__. This is undesirable in ++% some manuals, especially if they don't have long identifiers in ++% general. @allowcodebreaks provides a way to control this. ++% ++\newif\ifallowcodebreaks \allowcodebreakstrue ++ ++\def\keywordtrue{true} ++\def\keywordfalse{false} ++ ++\parseargdef\allowcodebreaks{% ++ \def\txiarg{#1}% ++ \ifx\txiarg\keywordtrue ++ \allowcodebreakstrue ++ \else\ifx\txiarg\keywordfalse ++ \allowcodebreaksfalse ++ \else ++ \errhelp = \EMsimple ++ \errmessage{Unknown @allowcodebreaks option `\txiarg'}% ++ \fi\fi ++} ++ ++% @kbd is like @code, except that if the argument is just one @key command, ++% then @kbd has no effect. ++ ++% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), ++% `example' (@kbd uses ttsl only inside of @example and friends), ++% or `code' (@kbd uses normal tty font always). ++\parseargdef\kbdinputstyle{% ++ \def\txiarg{#1}% ++ \ifx\txiarg\worddistinct ++ \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% ++ \else\ifx\txiarg\wordexample ++ \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% ++ \else\ifx\txiarg\wordcode ++ \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% ++ \else ++ \errhelp = \EMsimple ++ \errmessage{Unknown @kbdinputstyle option `\txiarg'}% ++ \fi\fi\fi ++} ++\def\worddistinct{distinct} ++\def\wordexample{example} ++\def\wordcode{code} ++ ++% Default is `distinct.' ++\kbdinputstyle distinct ++ ++\def\xkey{\key} ++\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% ++\ifx\one\xkey\ifx\threex\three \key{#2}% ++\else{\tclose{\kbdfont\look}}\fi ++\else{\tclose{\kbdfont\look}}\fi} ++ ++% For @indicateurl, @env, @command quotes seem unnecessary, so use \code. ++\let\indicateurl=\code ++\let\env=\code ++\let\command=\code ++ ++% @uref (abbreviation for `urlref') takes an optional (comma-separated) ++% second argument specifying the text to display and an optional third ++% arg as text to display instead of (rather than in addition to) the url ++% itself. First (mandatory) arg is the url. Perhaps eventually put in ++% a hypertex \special here. ++% ++\def\uref#1{\douref #1,,,\finish} ++\def\douref#1,#2,#3,#4\finish{\begingroup ++ \unsepspaces ++ \pdfurl{#1}% ++ \setbox0 = \hbox{\ignorespaces #3}% ++ \ifdim\wd0 > 0pt ++ \unhbox0 % third arg given, show only that ++ \else ++ \setbox0 = \hbox{\ignorespaces #2}% ++ \ifdim\wd0 > 0pt ++ \ifpdf ++ \unhbox0 % PDF: 2nd arg given, show only it ++ \else ++ \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url ++ \fi ++ \else ++ \code{#1}% only url given, so show it ++ \fi ++ \fi ++ \endlink ++\endgroup} ++ ++% @url synonym for @uref, since that's how everyone uses it. ++% ++\let\url=\uref ++ ++% rms does not like angle brackets --karl, 17may97. ++% So now @email is just like @uref, unless we are pdf. ++% ++%\def\email#1{\angleleft{\tt #1}\angleright} ++\ifpdf ++ \def\email#1{\doemail#1,,\finish} ++ \def\doemail#1,#2,#3\finish{\begingroup ++ \unsepspaces ++ \pdfurl{mailto:#1}% ++ \setbox0 = \hbox{\ignorespaces #2}% ++ \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi ++ \endlink ++ \endgroup} ++\else ++ \let\email=\uref ++\fi ++ ++% Check if we are currently using a typewriter font. Since all the ++% Computer Modern typewriter fonts have zero interword stretch (and ++% shrink), and it is reasonable to expect all typewriter fonts to have ++% this property, we can check that font parameter. ++% ++\def\ifmonospace{\ifdim\fontdimen3\font=0pt } ++ ++% Typeset a dimension, e.g., `in' or `pt'. The only reason for the ++% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt. ++% ++\def\dmn#1{\thinspace #1} ++ ++\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} ++ ++% @l was never documented to mean ``switch to the Lisp font'', ++% and it is not used as such in any manual I can find. We need it for ++% Polish suppressed-l. --karl, 22sep96. ++%\def\l#1{{\li #1}\null} ++ ++% Explicit font changes: @r, @sc, undocumented @ii. ++\def\r#1{{\rm #1}} % roman font ++\def\sc#1{{\smallcaps#1}} % smallcaps font ++\def\ii#1{{\it #1}} % italic font ++ ++% @acronym for "FBI", "NATO", and the like. ++% We print this one point size smaller, since it's intended for ++% all-uppercase. ++% ++\def\acronym#1{\doacronym #1,,\finish} ++\def\doacronym#1,#2,#3\finish{% ++ {\selectfonts\lsize #1}% ++ \def\temp{#2}% ++ \ifx\temp\empty \else ++ \space ({\unsepspaces \ignorespaces \temp \unskip})% ++ \fi ++} ++ ++% @abbr for "Comput. J." and the like. ++% No font change, but don't do end-of-sentence spacing. ++% ++\def\abbr#1{\doabbr #1,,\finish} ++\def\doabbr#1,#2,#3\finish{% ++ {\plainfrenchspacing #1}% ++ \def\temp{#2}% ++ \ifx\temp\empty \else ++ \space ({\unsepspaces \ignorespaces \temp \unskip})% ++ \fi ++} ++ ++% @pounds{} is a sterling sign, which Knuth put in the CM italic font. ++% ++\def\pounds{{\it\$}} ++ ++% @euro{} comes from a separate font, depending on the current style. ++% We use the free feym* fonts from the eurosym package by Henrik ++% Theiling, which support regular, slanted, bold and bold slanted (and ++% "outlined" (blackboard board, sort of) versions, which we don't need). ++% It is available from http://www.ctan.org/tex-archive/fonts/eurosym. ++% ++% Although only regular is the truly official Euro symbol, we ignore ++% that. The Euro is designed to be slightly taller than the regular ++% font height. ++% ++% feymr - regular ++% feymo - slanted ++% feybr - bold ++% feybo - bold slanted ++% ++% There is no good (free) typewriter version, to my knowledge. ++% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide. ++% Hmm. ++% ++% Also doesn't work in math. Do we need to do math with euro symbols? ++% Hope not. ++% ++% ++\def\euro{{\eurofont e}} ++\def\eurofont{% ++ % We set the font at each command, rather than predefining it in ++ % \textfonts and the other font-switching commands, so that ++ % installations which never need the symbol don't have to have the ++ % font installed. ++ % ++ % There is only one designed size (nominal 10pt), so we always scale ++ % that to the current nominal size. ++ % ++ % By the way, simply using "at 1em" works for cmr10 and the like, but ++ % does not work for cmbx10 and other extended/shrunken fonts. ++ % ++ \def\eurosize{\csname\curfontsize nominalsize\endcsname}% ++ % ++ \ifx\curfontstyle\bfstylename ++ % bold: ++ \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize ++ \else ++ % regular: ++ \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize ++ \fi ++ \thiseurofont ++} ++ ++% @registeredsymbol - R in a circle. The font for the R should really ++% be smaller yet, but lllsize is the best we can do for now. ++% Adapted from the plain.tex definition of \copyright. ++% ++\def\registeredsymbol{% ++ $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}% ++ \hfil\crcr\Orb}}% ++ }$% ++} ++ ++% @textdegree - the normal degrees sign. ++% ++\def\textdegree{$^\circ$} ++ ++% Laurent Siebenmann reports \Orb undefined with: ++% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38 ++% so we'll define it if necessary. ++% ++\ifx\Orb\undefined ++\def\Orb{\mathhexbox20D} ++\fi ++ ++ ++\message{page headings,} ++ ++\newskip\titlepagetopglue \titlepagetopglue = 1.5in ++\newskip\titlepagebottomglue \titlepagebottomglue = 2pc ++ ++% First the title page. Must do @settitle before @titlepage. ++\newif\ifseenauthor ++\newif\iffinishedtitlepage ++ ++% Do an implicit @contents or @shortcontents after @end titlepage if the ++% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage. ++% ++\newif\ifsetcontentsaftertitlepage ++ \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue ++\newif\ifsetshortcontentsaftertitlepage ++ \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue ++ ++\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% ++ \endgroup\page\hbox{}\page} ++ ++\envdef\titlepage{% ++ % Open one extra group, as we want to close it in the middle of \Etitlepage. ++ \begingroup ++ \parindent=0pt \textfonts ++ % Leave some space at the very top of the page. ++ \vglue\titlepagetopglue ++ % No rule at page bottom unless we print one at the top with @title. ++ \finishedtitlepagetrue ++ % ++ % Most title ``pages'' are actually two pages long, with space ++ % at the top of the second. We don't want the ragged left on the second. ++ \let\oldpage = \page ++ \def\page{% ++ \iffinishedtitlepage\else ++ \finishtitlepage ++ \fi ++ \let\page = \oldpage ++ \page ++ \null ++ }% ++} ++ ++\def\Etitlepage{% ++ \iffinishedtitlepage\else ++ \finishtitlepage ++ \fi ++ % It is important to do the page break before ending the group, ++ % because the headline and footline are only empty inside the group. ++ % If we use the new definition of \page, we always get a blank page ++ % after the title page, which we certainly don't want. ++ \oldpage ++ \endgroup ++ % ++ % Need this before the \...aftertitlepage checks so that if they are ++ % in effect the toc pages will come out with page numbers. ++ \HEADINGSon ++ % ++ % If they want short, they certainly want long too. ++ \ifsetshortcontentsaftertitlepage ++ \shortcontents ++ \contents ++ \global\let\shortcontents = \relax ++ \global\let\contents = \relax ++ \fi ++ % ++ \ifsetcontentsaftertitlepage ++ \contents ++ \global\let\contents = \relax ++ \global\let\shortcontents = \relax ++ \fi ++} ++ ++\def\finishtitlepage{% ++ \vskip4pt \hrule height 2pt width \hsize ++ \vskip\titlepagebottomglue ++ \finishedtitlepagetrue ++} ++ ++%%% Macros to be used within @titlepage: ++ ++\let\subtitlerm=\tenrm ++\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines} ++ ++\def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines ++ \let\tt=\authortt} ++ ++\parseargdef\title{% ++ \checkenv\titlepage ++ \leftline{\titlefonts\rm #1} ++ % print a rule at the page bottom also. ++ \finishedtitlepagefalse ++ \vskip4pt \hrule height 4pt width \hsize \vskip4pt ++} ++ ++\parseargdef\subtitle{% ++ \checkenv\titlepage ++ {\subtitlefont \rightline{#1}}% ++} ++ ++% @author should come last, but may come many times. ++% It can also be used inside @quotation. ++% ++\parseargdef\author{% ++ \def\temp{\quotation}% ++ \ifx\thisenv\temp ++ \def\quotationauthor{#1}% printed in \Equotation. ++ \else ++ \checkenv\titlepage ++ \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi ++ {\authorfont \leftline{#1}}% ++ \fi ++} ++ ++ ++%%% Set up page headings and footings. ++ ++\let\thispage=\folio ++ ++\newtoks\evenheadline % headline on even pages ++\newtoks\oddheadline % headline on odd pages ++\newtoks\evenfootline % footline on even pages ++\newtoks\oddfootline % footline on odd pages ++ ++% Now make TeX use those variables ++\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline ++ \else \the\evenheadline \fi}} ++\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline ++ \else \the\evenfootline \fi}\HEADINGShook} ++\let\HEADINGShook=\relax ++ ++% Commands to set those variables. ++% For example, this is what @headings on does ++% @evenheading @thistitle|@thispage|@thischapter ++% @oddheading @thischapter|@thispage|@thistitle ++% @evenfooting @thisfile|| ++% @oddfooting ||@thisfile ++ ++ ++\def\evenheading{\parsearg\evenheadingxxx} ++\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish} ++\def\evenheadingyyy #1\|#2\|#3\|#4\finish{% ++\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} ++ ++\def\oddheading{\parsearg\oddheadingxxx} ++\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish} ++\def\oddheadingyyy #1\|#2\|#3\|#4\finish{% ++\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} ++ ++\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}% ++ ++\def\evenfooting{\parsearg\evenfootingxxx} ++\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish} ++\def\evenfootingyyy #1\|#2\|#3\|#4\finish{% ++\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} ++ ++\def\oddfooting{\parsearg\oddfootingxxx} ++\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish} ++\def\oddfootingyyy #1\|#2\|#3\|#4\finish{% ++ \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}% ++ % ++ % Leave some space for the footline. Hopefully ok to assume ++ % @evenfooting will not be used by itself. ++ \global\advance\pageheight by -12pt ++ \global\advance\vsize by -12pt ++} ++ ++\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}} ++ ++ ++% @headings double turns headings on for double-sided printing. ++% @headings single turns headings on for single-sided printing. ++% @headings off turns them off. ++% @headings on same as @headings double, retained for compatibility. ++% @headings after turns on double-sided headings after this page. ++% @headings doubleafter turns on double-sided headings after this page. ++% @headings singleafter turns on single-sided headings after this page. ++% By default, they are off at the start of a document, ++% and turned `on' after @end titlepage. ++ ++\def\headings #1 {\csname HEADINGS#1\endcsname} ++ ++\def\HEADINGSoff{% ++\global\evenheadline={\hfil} \global\evenfootline={\hfil} ++\global\oddheadline={\hfil} \global\oddfootline={\hfil}} ++\HEADINGSoff ++% When we turn headings on, set the page number to 1. ++% For double-sided printing, put current file name in lower left corner, ++% chapter name on inside top of right hand pages, document ++% title on inside top of left hand pages, and page numbers on outside top ++% edge of all pages. ++\def\HEADINGSdouble{% ++\global\pageno=1 ++\global\evenfootline={\hfil} ++\global\oddfootline={\hfil} ++\global\evenheadline={\line{\folio\hfil\thistitle}} ++\global\oddheadline={\line{\thischapter\hfil\folio}} ++\global\let\contentsalignmacro = \chapoddpage ++} ++\let\contentsalignmacro = \chappager ++ ++% For single-sided printing, chapter title goes across top left of page, ++% page number on top right. ++\def\HEADINGSsingle{% ++\global\pageno=1 ++\global\evenfootline={\hfil} ++\global\oddfootline={\hfil} ++\global\evenheadline={\line{\thischapter\hfil\folio}} ++\global\oddheadline={\line{\thischapter\hfil\folio}} ++\global\let\contentsalignmacro = \chappager ++} ++\def\HEADINGSon{\HEADINGSdouble} ++ ++\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} ++\let\HEADINGSdoubleafter=\HEADINGSafter ++\def\HEADINGSdoublex{% ++\global\evenfootline={\hfil} ++\global\oddfootline={\hfil} ++\global\evenheadline={\line{\folio\hfil\thistitle}} ++\global\oddheadline={\line{\thischapter\hfil\folio}} ++\global\let\contentsalignmacro = \chapoddpage ++} ++ ++\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} ++\def\HEADINGSsinglex{% ++\global\evenfootline={\hfil} ++\global\oddfootline={\hfil} ++\global\evenheadline={\line{\thischapter\hfil\folio}} ++\global\oddheadline={\line{\thischapter\hfil\folio}} ++\global\let\contentsalignmacro = \chappager ++} ++ ++% Subroutines used in generating headings ++% This produces Day Month Year style of output. ++% Only define if not already defined, in case a txi-??.tex file has set ++% up a different format (e.g., txi-cs.tex does this). ++\ifx\today\undefined ++\def\today{% ++ \number\day\space ++ \ifcase\month ++ \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr ++ \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug ++ \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec ++ \fi ++ \space\number\year} ++\fi ++ ++% @settitle line... specifies the title of the document, for headings. ++% It generates no output of its own. ++\def\thistitle{\putwordNoTitle} ++\def\settitle{\parsearg{\gdef\thistitle}} ++ ++ ++\message{tables,} ++% Tables -- @table, @ftable, @vtable, @item(x). ++ ++% default indentation of table text ++\newdimen\tableindent \tableindent=.8in ++% default indentation of @itemize and @enumerate text ++\newdimen\itemindent \itemindent=.3in ++% margin between end of table item and start of table text. ++\newdimen\itemmargin \itemmargin=.1in ++ ++% used internally for \itemindent minus \itemmargin ++\newdimen\itemmax ++ ++% Note @table, @ftable, and @vtable define @item, @itemx, etc., with ++% these defs. ++% They also define \itemindex ++% to index the item name in whatever manner is desired (perhaps none). ++ ++\newif\ifitemxneedsnegativevskip ++ ++\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} ++ ++\def\internalBitem{\smallbreak \parsearg\itemzzz} ++\def\internalBitemx{\itemxpar \parsearg\itemzzz} ++ ++\def\itemzzz #1{\begingroup % ++ \advance\hsize by -\rightskip ++ \advance\hsize by -\tableindent ++ \setbox0=\hbox{\itemindicate{#1}}% ++ \itemindex{#1}% ++ \nobreak % This prevents a break before @itemx. ++ % ++ % If the item text does not fit in the space we have, put it on a line ++ % by itself, and do not allow a page break either before or after that ++ % line. We do not start a paragraph here because then if the next ++ % command is, e.g., @kindex, the whatsit would get put into the ++ % horizontal list on a line by itself, resulting in extra blank space. ++ \ifdim \wd0>\itemmax ++ % ++ % Make this a paragraph so we get the \parskip glue and wrapping, ++ % but leave it ragged-right. ++ \begingroup ++ \advance\leftskip by-\tableindent ++ \advance\hsize by\tableindent ++ \advance\rightskip by0pt plus1fil ++ \leavevmode\unhbox0\par ++ \endgroup ++ % ++ % We're going to be starting a paragraph, but we don't want the ++ % \parskip glue -- logically it's part of the @item we just started. ++ \nobreak \vskip-\parskip ++ % ++ % Stop a page break at the \parskip glue coming up. However, if ++ % what follows is an environment such as @example, there will be no ++ % \parskip glue; then the negative vskip we just inserted would ++ % cause the example and the item to crash together. So we use this ++ % bizarre value of 10001 as a signal to \aboveenvbreak to insert ++ % \parskip glue after all. Section titles are handled this way also. ++ % ++ \penalty 10001 ++ \endgroup ++ \itemxneedsnegativevskipfalse ++ \else ++ % The item text fits into the space. Start a paragraph, so that the ++ % following text (if any) will end up on the same line. ++ \noindent ++ % Do this with kerns and \unhbox so that if there is a footnote in ++ % the item text, it can migrate to the main vertical list and ++ % eventually be printed. ++ \nobreak\kern-\tableindent ++ \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0 ++ \unhbox0 ++ \nobreak\kern\dimen0 ++ \endgroup ++ \itemxneedsnegativevskiptrue ++ \fi ++} ++ ++\def\item{\errmessage{@item while not in a list environment}} ++\def\itemx{\errmessage{@itemx while not in a list environment}} ++ ++% @table, @ftable, @vtable. ++\envdef\table{% ++ \let\itemindex\gobble ++ \tablecheck{table}% ++} ++\envdef\ftable{% ++ \def\itemindex ##1{\doind {fn}{\code{##1}}}% ++ \tablecheck{ftable}% ++} ++\envdef\vtable{% ++ \def\itemindex ##1{\doind {vr}{\code{##1}}}% ++ \tablecheck{vtable}% ++} ++\def\tablecheck#1{% ++ \ifnum \the\catcode`\^^M=\active ++ \endgroup ++ \errmessage{This command won't work in this context; perhaps the problem is ++ that we are \inenvironment\thisenv}% ++ \def\next{\doignore{#1}}% ++ \else ++ \let\next\tablex ++ \fi ++ \next ++} ++\def\tablex#1{% ++ \def\itemindicate{#1}% ++ \parsearg\tabley ++} ++\def\tabley#1{% ++ {% ++ \makevalueexpandable ++ \edef\temp{\noexpand\tablez #1\space\space\space}% ++ \expandafter ++ }\temp \endtablez ++} ++\def\tablez #1 #2 #3 #4\endtablez{% ++ \aboveenvbreak ++ \ifnum 0#1>0 \advance \leftskip by #1\mil \fi ++ \ifnum 0#2>0 \tableindent=#2\mil \fi ++ \ifnum 0#3>0 \advance \rightskip by #3\mil \fi ++ \itemmax=\tableindent ++ \advance \itemmax by -\itemmargin ++ \advance \leftskip by \tableindent ++ \exdentamount=\tableindent ++ \parindent = 0pt ++ \parskip = \smallskipamount ++ \ifdim \parskip=0pt \parskip=2pt \fi ++ \let\item = \internalBitem ++ \let\itemx = \internalBitemx ++} ++\def\Etable{\endgraf\afterenvbreak} ++\let\Eftable\Etable ++\let\Evtable\Etable ++\let\Eitemize\Etable ++\let\Eenumerate\Etable ++ ++% This is the counter used by @enumerate, which is really @itemize ++ ++\newcount \itemno ++ ++\envdef\itemize{\parsearg\doitemize} ++ ++\def\doitemize#1{% ++ \aboveenvbreak ++ \itemmax=\itemindent ++ \advance\itemmax by -\itemmargin ++ \advance\leftskip by \itemindent ++ \exdentamount=\itemindent ++ \parindent=0pt ++ \parskip=\smallskipamount ++ \ifdim\parskip=0pt \parskip=2pt \fi ++ \def\itemcontents{#1}% ++ % @itemize with no arg is equivalent to @itemize @bullet. ++ \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi ++ \let\item=\itemizeitem ++} ++ ++% Definition of @item while inside @itemize and @enumerate. ++% ++\def\itemizeitem{% ++ \advance\itemno by 1 % for enumerations ++ {\let\par=\endgraf \smallbreak}% reasonable place to break ++ {% ++ % If the document has an @itemize directly after a section title, a ++ % \nobreak will be last on the list, and \sectionheading will have ++ % done a \vskip-\parskip. In that case, we don't want to zero ++ % parskip, or the item text will crash with the heading. On the ++ % other hand, when there is normal text preceding the item (as there ++ % usually is), we do want to zero parskip, or there would be too much ++ % space. In that case, we won't have a \nobreak before. At least ++ % that's the theory. ++ \ifnum\lastpenalty<10000 \parskip=0in \fi ++ \noindent ++ \hbox to 0pt{\hss \itemcontents \kern\itemmargin}% ++ \vadjust{\penalty 1200}}% not good to break after first line of item. ++ \flushcr ++} ++ ++% \splitoff TOKENS\endmark defines \first to be the first token in ++% TOKENS, and \rest to be the remainder. ++% ++\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% ++ ++% Allow an optional argument of an uppercase letter, lowercase letter, ++% or number, to specify the first label in the enumerated list. No ++% argument is the same as `1'. ++% ++\envparseargdef\enumerate{\enumeratey #1 \endenumeratey} ++\def\enumeratey #1 #2\endenumeratey{% ++ % If we were given no argument, pretend we were given `1'. ++ \def\thearg{#1}% ++ \ifx\thearg\empty \def\thearg{1}\fi ++ % ++ % Detect if the argument is a single token. If so, it might be a ++ % letter. Otherwise, the only valid thing it can be is a number. ++ % (We will always have one token, because of the test we just made. ++ % This is a good thing, since \splitoff doesn't work given nothing at ++ % all -- the first parameter is undelimited.) ++ \expandafter\splitoff\thearg\endmark ++ \ifx\rest\empty ++ % Only one token in the argument. It could still be anything. ++ % A ``lowercase letter'' is one whose \lccode is nonzero. ++ % An ``uppercase letter'' is one whose \lccode is both nonzero, and ++ % not equal to itself. ++ % Otherwise, we assume it's a number. ++ % ++ % We need the \relax at the end of the \ifnum lines to stop TeX from ++ % continuing to look for a . ++ % ++ \ifnum\lccode\expandafter`\thearg=0\relax ++ \numericenumerate % a number (we hope) ++ \else ++ % It's a letter. ++ \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax ++ \lowercaseenumerate % lowercase letter ++ \else ++ \uppercaseenumerate % uppercase letter ++ \fi ++ \fi ++ \else ++ % Multiple tokens in the argument. We hope it's a number. ++ \numericenumerate ++ \fi ++} ++ ++% An @enumerate whose labels are integers. The starting integer is ++% given in \thearg. ++% ++\def\numericenumerate{% ++ \itemno = \thearg ++ \startenumeration{\the\itemno}% ++} ++ ++% The starting (lowercase) letter is in \thearg. ++\def\lowercaseenumerate{% ++ \itemno = \expandafter`\thearg ++ \startenumeration{% ++ % Be sure we're not beyond the end of the alphabet. ++ \ifnum\itemno=0 ++ \errmessage{No more lowercase letters in @enumerate; get a bigger ++ alphabet}% ++ \fi ++ \char\lccode\itemno ++ }% ++} ++ ++% The starting (uppercase) letter is in \thearg. ++\def\uppercaseenumerate{% ++ \itemno = \expandafter`\thearg ++ \startenumeration{% ++ % Be sure we're not beyond the end of the alphabet. ++ \ifnum\itemno=0 ++ \errmessage{No more uppercase letters in @enumerate; get a bigger ++ alphabet} ++ \fi ++ \char\uccode\itemno ++ }% ++} ++ ++% Call \doitemize, adding a period to the first argument and supplying the ++% common last two arguments. Also subtract one from the initial value in ++% \itemno, since @item increments \itemno. ++% ++\def\startenumeration#1{% ++ \advance\itemno by -1 ++ \doitemize{#1.}\flushcr ++} ++ ++% @alphaenumerate and @capsenumerate are abbreviations for giving an arg ++% to @enumerate. ++% ++\def\alphaenumerate{\enumerate{a}} ++\def\capsenumerate{\enumerate{A}} ++\def\Ealphaenumerate{\Eenumerate} ++\def\Ecapsenumerate{\Eenumerate} ++ ++ ++% @multitable macros ++% Amy Hendrickson, 8/18/94, 3/6/96 ++% ++% @multitable ... @end multitable will make as many columns as desired. ++% Contents of each column will wrap at width given in preamble. Width ++% can be specified either with sample text given in a template line, ++% or in percent of \hsize, the current width of text on page. ++ ++% Table can continue over pages but will only break between lines. ++ ++% To make preamble: ++% ++% Either define widths of columns in terms of percent of \hsize: ++% @multitable @columnfractions .25 .3 .45 ++% @item ... ++% ++% Numbers following @columnfractions are the percent of the total ++% current hsize to be used for each column. You may use as many ++% columns as desired. ++ ++ ++% Or use a template: ++% @multitable {Column 1 template} {Column 2 template} {Column 3 template} ++% @item ... ++% using the widest term desired in each column. ++ ++% Each new table line starts with @item, each subsequent new column ++% starts with @tab. Empty columns may be produced by supplying @tab's ++% with nothing between them for as many times as empty columns are needed, ++% ie, @tab@tab@tab will produce two empty columns. ++ ++% @item, @tab do not need to be on their own lines, but it will not hurt ++% if they are. ++ ++% Sample multitable: ++ ++% @multitable {Column 1 template} {Column 2 template} {Column 3 template} ++% @item first col stuff @tab second col stuff @tab third col ++% @item ++% first col stuff ++% @tab ++% second col stuff ++% @tab ++% third col ++% @item first col stuff @tab second col stuff ++% @tab Many paragraphs of text may be used in any column. ++% ++% They will wrap at the width determined by the template. ++% @item@tab@tab This will be in third column. ++% @end multitable ++ ++% Default dimensions may be reset by user. ++% @multitableparskip is vertical space between paragraphs in table. ++% @multitableparindent is paragraph indent in table. ++% @multitablecolmargin is horizontal space to be left between columns. ++% @multitablelinespace is space to leave between table items, baseline ++% to baseline. ++% 0pt means it depends on current normal line spacing. ++% ++\newskip\multitableparskip ++\newskip\multitableparindent ++\newdimen\multitablecolspace ++\newskip\multitablelinespace ++\multitableparskip=0pt ++\multitableparindent=6pt ++\multitablecolspace=12pt ++\multitablelinespace=0pt ++ ++% Macros used to set up halign preamble: ++% ++\let\endsetuptable\relax ++\def\xendsetuptable{\endsetuptable} ++\let\columnfractions\relax ++\def\xcolumnfractions{\columnfractions} ++\newif\ifsetpercent ++ ++% #1 is the @columnfraction, usually a decimal number like .5, but might ++% be just 1. We just use it, whatever it is. ++% ++\def\pickupwholefraction#1 {% ++ \global\advance\colcount by 1 ++ \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}% ++ \setuptable ++} ++ ++\newcount\colcount ++\def\setuptable#1{% ++ \def\firstarg{#1}% ++ \ifx\firstarg\xendsetuptable ++ \let\go = \relax ++ \else ++ \ifx\firstarg\xcolumnfractions ++ \global\setpercenttrue ++ \else ++ \ifsetpercent ++ \let\go\pickupwholefraction ++ \else ++ \global\advance\colcount by 1 ++ \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a ++ % separator; typically that is always in the input, anyway. ++ \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% ++ \fi ++ \fi ++ \ifx\go\pickupwholefraction ++ % Put the argument back for the \pickupwholefraction call, so ++ % we'll always have a period there to be parsed. ++ \def\go{\pickupwholefraction#1}% ++ \else ++ \let\go = \setuptable ++ \fi% ++ \fi ++ \go ++} ++ ++% multitable-only commands. ++% ++% @headitem starts a heading row, which we typeset in bold. ++% Assignments have to be global since we are inside the implicit group ++% of an alignment entry. Note that \everycr resets \everytab. ++\def\headitem{\checkenv\multitable \crcr \global\everytab={\bf}\the\everytab}% ++% ++% A \tab used to include \hskip1sp. But then the space in a template ++% line is not enough. That is bad. So let's go back to just `&' until ++% we encounter the problem it was intended to solve again. ++% --karl, nathan@acm.org, 20apr99. ++\def\tab{\checkenv\multitable &\the\everytab}% ++ ++% @multitable ... @end multitable definitions: ++% ++\newtoks\everytab % insert after every tab. ++% ++\envdef\multitable{% ++ \vskip\parskip ++ \startsavinginserts ++ % ++ % @item within a multitable starts a normal row. ++ % We use \def instead of \let so that if one of the multitable entries ++ % contains an @itemize, we don't choke on the \item (seen as \crcr aka ++ % \endtemplate) expanding \doitemize. ++ \def\item{\crcr}% ++ % ++ \tolerance=9500 ++ \hbadness=9500 ++ \setmultitablespacing ++ \parskip=\multitableparskip ++ \parindent=\multitableparindent ++ \overfullrule=0pt ++ \global\colcount=0 ++ % ++ \everycr = {% ++ \noalign{% ++ \global\everytab={}% ++ \global\colcount=0 % Reset the column counter. ++ % Check for saved footnotes, etc. ++ \checkinserts ++ % Keeps underfull box messages off when table breaks over pages. ++ %\filbreak ++ % Maybe so, but it also creates really weird page breaks when the ++ % table breaks over pages. Wouldn't \vfil be better? Wait until the ++ % problem manifests itself, so it can be fixed for real --karl. ++ }% ++ }% ++ % ++ \parsearg\domultitable ++} ++\def\domultitable#1{% ++ % To parse everything between @multitable and @item: ++ \setuptable#1 \endsetuptable ++ % ++ % This preamble sets up a generic column definition, which will ++ % be used as many times as user calls for columns. ++ % \vtop will set a single line and will also let text wrap and ++ % continue for many paragraphs if desired. ++ \halign\bgroup &% ++ \global\advance\colcount by 1 ++ \multistrut ++ \vtop{% ++ % Use the current \colcount to find the correct column width: ++ \hsize=\expandafter\csname col\the\colcount\endcsname ++ % ++ % In order to keep entries from bumping into each other ++ % we will add a \leftskip of \multitablecolspace to all columns after ++ % the first one. ++ % ++ % If a template has been used, we will add \multitablecolspace ++ % to the width of each template entry. ++ % ++ % If the user has set preamble in terms of percent of \hsize we will ++ % use that dimension as the width of the column, and the \leftskip ++ % will keep entries from bumping into each other. Table will start at ++ % left margin and final column will justify at right margin. ++ % ++ % Make sure we don't inherit \rightskip from the outer environment. ++ \rightskip=0pt ++ \ifnum\colcount=1 ++ % The first column will be indented with the surrounding text. ++ \advance\hsize by\leftskip ++ \else ++ \ifsetpercent \else ++ % If user has not set preamble in terms of percent of \hsize ++ % we will advance \hsize by \multitablecolspace. ++ \advance\hsize by \multitablecolspace ++ \fi ++ % In either case we will make \leftskip=\multitablecolspace: ++ \leftskip=\multitablecolspace ++ \fi ++ % Ignoring space at the beginning and end avoids an occasional spurious ++ % blank line, when TeX decides to break the line at the space before the ++ % box from the multistrut, so the strut ends up on a line by itself. ++ % For example: ++ % @multitable @columnfractions .11 .89 ++ % @item @code{#} ++ % @tab Legal holiday which is valid in major parts of the whole country. ++ % Is automatically provided with highlighting sequences respectively ++ % marking characters. ++ \noindent\ignorespaces##\unskip\multistrut ++ }\cr ++} ++\def\Emultitable{% ++ \crcr ++ \egroup % end the \halign ++ \global\setpercentfalse ++} ++ ++\def\setmultitablespacing{% ++ \def\multistrut{\strut}% just use the standard line spacing ++ % ++ % Compute \multitablelinespace (if not defined by user) for use in ++ % \multitableparskip calculation. We used define \multistrut based on ++ % this, but (ironically) that caused the spacing to be off. ++ % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100. ++\ifdim\multitablelinespace=0pt ++\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip ++\global\advance\multitablelinespace by-\ht0 ++\fi ++%% Test to see if parskip is larger than space between lines of ++%% table. If not, do nothing. ++%% If so, set to same dimension as multitablelinespace. ++\ifdim\multitableparskip>\multitablelinespace ++\global\multitableparskip=\multitablelinespace ++\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller ++ %% than skip between lines in the table. ++\fi% ++\ifdim\multitableparskip=0pt ++\global\multitableparskip=\multitablelinespace ++\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller ++ %% than skip between lines in the table. ++\fi} ++ ++ ++\message{conditionals,} ++ ++% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext, ++% @ifnotxml always succeed. They currently do nothing; we don't ++% attempt to check whether the conditionals are properly nested. But we ++% have to remember that they are conditionals, so that @end doesn't ++% attempt to close an environment group. ++% ++\def\makecond#1{% ++ \expandafter\let\csname #1\endcsname = \relax ++ \expandafter\let\csname iscond.#1\endcsname = 1 ++} ++\makecond{iftex} ++\makecond{ifnotdocbook} ++\makecond{ifnothtml} ++\makecond{ifnotinfo} ++\makecond{ifnotplaintext} ++\makecond{ifnotxml} ++ ++% Ignore @ignore, @ifhtml, @ifinfo, and the like. ++% ++\def\direntry{\doignore{direntry}} ++\def\documentdescription{\doignore{documentdescription}} ++\def\docbook{\doignore{docbook}} ++\def\html{\doignore{html}} ++\def\ifdocbook{\doignore{ifdocbook}} ++\def\ifhtml{\doignore{ifhtml}} ++\def\ifinfo{\doignore{ifinfo}} ++\def\ifnottex{\doignore{ifnottex}} ++\def\ifplaintext{\doignore{ifplaintext}} ++\def\ifxml{\doignore{ifxml}} ++\def\ignore{\doignore{ignore}} ++\def\menu{\doignore{menu}} ++\def\xml{\doignore{xml}} ++ ++% Ignore text until a line `@end #1', keeping track of nested conditionals. ++% ++% A count to remember the depth of nesting. ++\newcount\doignorecount ++ ++\def\doignore#1{\begingroup ++ % Scan in ``verbatim'' mode: ++ \obeylines ++ \catcode`\@ = \other ++ \catcode`\{ = \other ++ \catcode`\} = \other ++ % ++ % Make sure that spaces turn into tokens that match what \doignoretext wants. ++ \spaceisspace ++ % ++ % Count number of #1's that we've seen. ++ \doignorecount = 0 ++ % ++ % Swallow text until we reach the matching `@end #1'. ++ \dodoignore{#1}% ++} ++ ++{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source. ++ \obeylines % ++ % ++ \gdef\dodoignore#1{% ++ % #1 contains the command name as a string, e.g., `ifinfo'. ++ % ++ % Define a command to find the next `@end #1'. ++ \long\def\doignoretext##1^^M@end #1{% ++ \doignoretextyyy##1^^M@#1\_STOP_}% ++ % ++ % And this command to find another #1 command, at the beginning of a ++ % line. (Otherwise, we would consider a line `@c @ifset', for ++ % example, to count as an @ifset for nesting.) ++ \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}% ++ % ++ % And now expand that command. ++ \doignoretext ^^M% ++ }% ++} ++ ++\def\doignoreyyy#1{% ++ \def\temp{#1}% ++ \ifx\temp\empty % Nothing found. ++ \let\next\doignoretextzzz ++ \else % Found a nested condition, ... ++ \advance\doignorecount by 1 ++ \let\next\doignoretextyyy % ..., look for another. ++ % If we're here, #1 ends with ^^M\ifinfo (for example). ++ \fi ++ \next #1% the token \_STOP_ is present just after this macro. ++} ++ ++% We have to swallow the remaining "\_STOP_". ++% ++\def\doignoretextzzz#1{% ++ \ifnum\doignorecount = 0 % We have just found the outermost @end. ++ \let\next\enddoignore ++ \else % Still inside a nested condition. ++ \advance\doignorecount by -1 ++ \let\next\doignoretext % Look for the next @end. ++ \fi ++ \next ++} ++ ++% Finish off ignored text. ++{ \obeylines% ++ % Ignore anything after the last `@end #1'; this matters in verbatim ++ % environments, where otherwise the newline after an ignored conditional ++ % would result in a blank line in the output. ++ \gdef\enddoignore#1^^M{\endgroup\ignorespaces}% ++} ++ ++ ++% @set VAR sets the variable VAR to an empty value. ++% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. ++% ++% Since we want to separate VAR from REST-OF-LINE (which might be ++% empty), we can't just use \parsearg; we have to insert a space of our ++% own to delimit the rest of the line, and then take it out again if we ++% didn't need it. ++% We rely on the fact that \parsearg sets \catcode`\ =10. ++% ++\parseargdef\set{\setyyy#1 \endsetyyy} ++\def\setyyy#1 #2\endsetyyy{% ++ {% ++ \makevalueexpandable ++ \def\temp{#2}% ++ \edef\next{\gdef\makecsname{SET#1}}% ++ \ifx\temp\empty ++ \next{}% ++ \else ++ \setzzz#2\endsetzzz ++ \fi ++ }% ++} ++% Remove the trailing space \setxxx inserted. ++\def\setzzz#1 \endsetzzz{\next{#1}} ++ ++% @clear VAR clears (i.e., unsets) the variable VAR. ++% ++\parseargdef\clear{% ++ {% ++ \makevalueexpandable ++ \global\expandafter\let\csname SET#1\endcsname=\relax ++ }% ++} ++ ++% @value{foo} gets the text saved in variable foo. ++\def\value{\begingroup\makevalueexpandable\valuexxx} ++\def\valuexxx#1{\expandablevalue{#1}\endgroup} ++{ ++ \catcode`\- = \active \catcode`\_ = \active ++ % ++ \gdef\makevalueexpandable{% ++ \let\value = \expandablevalue ++ % We don't want these characters active, ... ++ \catcode`\-=\other \catcode`\_=\other ++ % ..., but we might end up with active ones in the argument if ++ % we're called from @code, as @code{@value{foo-bar_}}, though. ++ % So \let them to their normal equivalents. ++ \let-\realdash \let_\normalunderscore ++ } ++} ++ ++% We have this subroutine so that we can handle at least some @value's ++% properly in indexes (we call \makevalueexpandable in \indexdummies). ++% The command has to be fully expandable (if the variable is set), since ++% the result winds up in the index file. This means that if the ++% variable's value contains other Texinfo commands, it's almost certain ++% it will fail (although perhaps we could fix that with sufficient work ++% to do a one-level expansion on the result, instead of complete). ++% ++\def\expandablevalue#1{% ++ \expandafter\ifx\csname SET#1\endcsname\relax ++ {[No value for ``#1'']}% ++ \message{Variable `#1', used in @value, is not set.}% ++ \else ++ \csname SET#1\endcsname ++ \fi ++} ++ ++% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined ++% with @set. ++% ++% To get special treatment of `@end ifset,' call \makeond and the redefine. ++% ++\makecond{ifset} ++\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}} ++\def\doifset#1#2{% ++ {% ++ \makevalueexpandable ++ \let\next=\empty ++ \expandafter\ifx\csname SET#2\endcsname\relax ++ #1% If not set, redefine \next. ++ \fi ++ \expandafter ++ }\next ++} ++\def\ifsetfail{\doignore{ifset}} ++ ++% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been ++% defined with @set, or has been undefined with @clear. ++% ++% The `\else' inside the `\doifset' parameter is a trick to reuse the ++% above code: if the variable is not set, do nothing, if it is set, ++% then redefine \next to \ifclearfail. ++% ++\makecond{ifclear} ++\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}} ++\def\ifclearfail{\doignore{ifclear}} ++ ++% @dircategory CATEGORY -- specify a category of the dir file ++% which this file should belong to. Ignore this in TeX. ++\let\dircategory=\comment ++ ++% @defininfoenclose. ++\let\definfoenclose=\comment ++ ++ ++\message{indexing,} ++% Index generation facilities ++ ++% Define \newwrite to be identical to plain tex's \newwrite ++% except not \outer, so it can be used within macros and \if's. ++\edef\newwrite{\makecsname{ptexnewwrite}} ++ ++% \newindex {foo} defines an index named foo. ++% It automatically defines \fooindex such that ++% \fooindex ...rest of line... puts an entry in the index foo. ++% It also defines \fooindfile to be the number of the output channel for ++% the file that accumulates this index. The file's extension is foo. ++% The name of an index should be no more than 2 characters long ++% for the sake of vms. ++% ++\def\newindex#1{% ++ \iflinks ++ \expandafter\newwrite \csname#1indfile\endcsname ++ \openout \csname#1indfile\endcsname \jobname.#1 % Open the file ++ \fi ++ \expandafter\xdef\csname#1index\endcsname{% % Define @#1index ++ \noexpand\doindex{#1}} ++} ++ ++% @defindex foo == \newindex{foo} ++% ++\def\defindex{\parsearg\newindex} ++ ++% Define @defcodeindex, like @defindex except put all entries in @code. ++% ++\def\defcodeindex{\parsearg\newcodeindex} ++% ++\def\newcodeindex#1{% ++ \iflinks ++ \expandafter\newwrite \csname#1indfile\endcsname ++ \openout \csname#1indfile\endcsname \jobname.#1 ++ \fi ++ \expandafter\xdef\csname#1index\endcsname{% ++ \noexpand\docodeindex{#1}}% ++} ++ ++ ++% @synindex foo bar makes index foo feed into index bar. ++% Do this instead of @defindex foo if you don't want it as a separate index. ++% ++% @syncodeindex foo bar similar, but put all entries made for index foo ++% inside @code. ++% ++\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}} ++\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}} ++ ++% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo), ++% #3 the target index (bar). ++\def\dosynindex#1#2#3{% ++ % Only do \closeout if we haven't already done it, else we'll end up ++ % closing the target index. ++ \expandafter \ifx\csname donesynindex#2\endcsname \undefined ++ % The \closeout helps reduce unnecessary open files; the limit on the ++ % Acorn RISC OS is a mere 16 files. ++ \expandafter\closeout\csname#2indfile\endcsname ++ \expandafter\let\csname\donesynindex#2\endcsname = 1 ++ \fi ++ % redefine \fooindfile: ++ \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname ++ \expandafter\let\csname#2indfile\endcsname=\temp ++ % redefine \fooindex: ++ \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}% ++} ++ ++% Define \doindex, the driver for all \fooindex macros. ++% Argument #1 is generated by the calling \fooindex macro, ++% and it is "foo", the name of the index. ++ ++% \doindex just uses \parsearg; it calls \doind for the actual work. ++% This is because \doind is more useful to call from other macros. ++ ++% There is also \dosubind {index}{topic}{subtopic} ++% which makes an entry in a two-level index such as the operation index. ++ ++\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} ++\def\singleindexer #1{\doind{\indexname}{#1}} ++ ++% like the previous two, but they put @code around the argument. ++\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} ++\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} ++ ++% Take care of Texinfo commands that can appear in an index entry. ++% Since there are some commands we want to expand, and others we don't, ++% we have to laboriously prevent expansion for those that we don't. ++% ++\def\indexdummies{% ++ \escapechar = `\\ % use backslash in output files. ++ \def\@{@}% change to @@ when we switch to @ as escape char in index files. ++ \def\ {\realbackslash\space }% ++ % ++ % Need these in case \tex is in effect and \{ is a \delimiter again. ++ % But can't use \lbracecmd and \rbracecmd because texindex assumes ++ % braces and backslashes are used only as delimiters. ++ \let\{ = \mylbrace ++ \let\} = \myrbrace ++ % ++ % I don't entirely understand this, but when an index entry is ++ % generated from a macro call, the \endinput which \scanmacro inserts ++ % causes processing to be prematurely terminated. This is, ++ % apparently, because \indexsorttmp is fully expanded, and \endinput ++ % is an expandable command. The redefinition below makes \endinput ++ % disappear altogether for that purpose -- although logging shows that ++ % processing continues to some further point. On the other hand, it ++ % seems \endinput does not hurt in the printed index arg, since that ++ % is still getting written without apparent harm. ++ % ++ % Sample source (mac-idx3.tex, reported by Graham Percival to ++ % help-texinfo, 22may06): ++ % @macro funindex {WORD} ++ % @findex xyz ++ % @end macro ++ % ... ++ % @funindex commtest ++ % ++ % The above is not enough to reproduce the bug, but it gives the flavor. ++ % ++ % Sample whatsit resulting: ++ % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} ++ % ++ % So: ++ \let\endinput = \empty ++ % ++ % Do the redefinitions. ++ \commondummies ++} ++ ++% For the aux and toc files, @ is the escape character. So we want to ++% redefine everything using @ as the escape character (instead of ++% \realbackslash, still used for index files). When everything uses @, ++% this will be simpler. ++% ++\def\atdummies{% ++ \def\@{@@}% ++ \def\ {@ }% ++ \let\{ = \lbraceatcmd ++ \let\} = \rbraceatcmd ++ % ++ % Do the redefinitions. ++ \commondummies ++ \otherbackslash ++} ++ ++% Called from \indexdummies and \atdummies. ++% ++\def\commondummies{% ++ % ++ % \definedummyword defines \#1 as \string\#1\space, thus effectively ++ % preventing its expansion. This is used only for control% words, ++ % not control letters, because the \space would be incorrect for ++ % control characters, but is needed to separate the control word ++ % from whatever follows. ++ % ++ % For control letters, we have \definedummyletter, which omits the ++ % space. ++ % ++ % These can be used both for control words that take an argument and ++ % those that do not. If it is followed by {arg} in the input, then ++ % that will dutifully get written to the index (or wherever). ++ % ++ \def\definedummyword ##1{\def##1{\string##1\space}}% ++ \def\definedummyletter##1{\def##1{\string##1}}% ++ \let\definedummyaccent\definedummyletter ++ % ++ \commondummiesnofonts ++ % ++ \definedummyletter\_% ++ % ++ % Non-English letters. ++ \definedummyword\AA ++ \definedummyword\AE ++ \definedummyword\L ++ \definedummyword\OE ++ \definedummyword\O ++ \definedummyword\aa ++ \definedummyword\ae ++ \definedummyword\l ++ \definedummyword\oe ++ \definedummyword\o ++ \definedummyword\ss ++ \definedummyword\exclamdown ++ \definedummyword\questiondown ++ \definedummyword\ordf ++ \definedummyword\ordm ++ % ++ % Although these internal commands shouldn't show up, sometimes they do. ++ \definedummyword\bf ++ \definedummyword\gtr ++ \definedummyword\hat ++ \definedummyword\less ++ \definedummyword\sf ++ \definedummyword\sl ++ \definedummyword\tclose ++ \definedummyword\tt ++ % ++ \definedummyword\LaTeX ++ \definedummyword\TeX ++ % ++ % Assorted special characters. ++ \definedummyword\bullet ++ \definedummyword\comma ++ \definedummyword\copyright ++ \definedummyword\registeredsymbol ++ \definedummyword\dots ++ \definedummyword\enddots ++ \definedummyword\equiv ++ \definedummyword\error ++ \definedummyword\euro ++ \definedummyword\expansion ++ \definedummyword\minus ++ \definedummyword\pounds ++ \definedummyword\point ++ \definedummyword\print ++ \definedummyword\result ++ \definedummyword\textdegree ++ % ++ % We want to disable all macros so that they are not expanded by \write. ++ \macrolist ++ % ++ \normalturnoffactive ++ % ++ % Handle some cases of @value -- where it does not contain any ++ % (non-fully-expandable) commands. ++ \makevalueexpandable ++} ++ ++% \commondummiesnofonts: common to \commondummies and \indexnofonts. ++% ++\def\commondummiesnofonts{% ++ % Control letters and accents. ++ \definedummyletter\!% ++ \definedummyaccent\"% ++ \definedummyaccent\'% ++ \definedummyletter\*% ++ \definedummyaccent\,% ++ \definedummyletter\.% ++ \definedummyletter\/% ++ \definedummyletter\:% ++ \definedummyaccent\=% ++ \definedummyletter\?% ++ \definedummyaccent\^% ++ \definedummyaccent\`% ++ \definedummyaccent\~% ++ \definedummyword\u ++ \definedummyword\v ++ \definedummyword\H ++ \definedummyword\dotaccent ++ \definedummyword\ringaccent ++ \definedummyword\tieaccent ++ \definedummyword\ubaraccent ++ \definedummyword\udotaccent ++ \definedummyword\dotless ++ % ++ % Texinfo font commands. ++ \definedummyword\b ++ \definedummyword\i ++ \definedummyword\r ++ \definedummyword\sc ++ \definedummyword\t ++ % ++ % Commands that take arguments. ++ \definedummyword\acronym ++ \definedummyword\cite ++ \definedummyword\code ++ \definedummyword\command ++ \definedummyword\dfn ++ \definedummyword\emph ++ \definedummyword\env ++ \definedummyword\file ++ \definedummyword\kbd ++ \definedummyword\key ++ \definedummyword\math ++ \definedummyword\option ++ \definedummyword\pxref ++ \definedummyword\ref ++ \definedummyword\samp ++ \definedummyword\strong ++ \definedummyword\tie ++ \definedummyword\uref ++ \definedummyword\url ++ \definedummyword\var ++ \definedummyword\verb ++ \definedummyword\w ++ \definedummyword\xref ++} ++ ++% \indexnofonts is used when outputting the strings to sort the index ++% by, and when constructing control sequence names. It eliminates all ++% control sequences and just writes whatever the best ASCII sort string ++% would be for a given command (usually its argument). ++% ++\def\indexnofonts{% ++ % Accent commands should become @asis. ++ \def\definedummyaccent##1{\let##1\asis}% ++ % We can just ignore other control letters. ++ \def\definedummyletter##1{\let##1\empty}% ++ % Hopefully, all control words can become @asis. ++ \let\definedummyword\definedummyaccent ++ % ++ \commondummiesnofonts ++ % ++ % Don't no-op \tt, since it isn't a user-level command ++ % and is used in the definitions of the active chars like <, >, |, etc. ++ % Likewise with the other plain tex font commands. ++ %\let\tt=\asis ++ % ++ \def\ { }% ++ \def\@{@}% ++ % how to handle braces? ++ \def\_{\normalunderscore}% ++ % ++ % Non-English letters. ++ \def\AA{AA}% ++ \def\AE{AE}% ++ \def\L{L}% ++ \def\OE{OE}% ++ \def\O{O}% ++ \def\aa{aa}% ++ \def\ae{ae}% ++ \def\l{l}% ++ \def\oe{oe}% ++ \def\o{o}% ++ \def\ss{ss}% ++ \def\exclamdown{!}% ++ \def\questiondown{?}% ++ \def\ordf{a}% ++ \def\ordm{o}% ++ % ++ \def\LaTeX{LaTeX}% ++ \def\TeX{TeX}% ++ % ++ % Assorted special characters. ++ % (The following {} will end up in the sort string, but that's ok.) ++ \def\bullet{bullet}% ++ \def\comma{,}% ++ \def\copyright{copyright}% ++ \def\registeredsymbol{R}% ++ \def\dots{...}% ++ \def\enddots{...}% ++ \def\equiv{==}% ++ \def\error{error}% ++ \def\euro{euro}% ++ \def\expansion{==>}% ++ \def\minus{-}% ++ \def\pounds{pounds}% ++ \def\point{.}% ++ \def\print{-|}% ++ \def\result{=>}% ++ \def\textdegree{degrees}% ++ % ++ % We need to get rid of all macros, leaving only the arguments (if present). ++ % Of course this is not nearly correct, but it is the best we can do for now. ++ % makeinfo does not expand macros in the argument to @deffn, which ends up ++ % writing an index entry, and texindex isn't prepared for an index sort entry ++ % that starts with \. ++ % ++ % Since macro invocations are followed by braces, we can just redefine them ++ % to take a single TeX argument. The case of a macro invocation that ++ % goes to end-of-line is not handled. ++ % ++ \macrolist ++} ++ ++\let\indexbackslash=0 %overridden during \printindex. ++\let\SETmarginindex=\relax % put index entries in margin (undocumented)? ++ ++% Most index entries go through here, but \dosubind is the general case. ++% #1 is the index name, #2 is the entry text. ++\def\doind#1#2{\dosubind{#1}{#2}{}} ++ ++% Workhorse for all \fooindexes. ++% #1 is name of index, #2 is stuff to put there, #3 is subentry -- ++% empty if called from \doind, as we usually are (the main exception ++% is with most defuns, which call us directly). ++% ++\def\dosubind#1#2#3{% ++ \iflinks ++ {% ++ % Store the main index entry text (including the third arg). ++ \toks0 = {#2}% ++ % If third arg is present, precede it with a space. ++ \def\thirdarg{#3}% ++ \ifx\thirdarg\empty \else ++ \toks0 = \expandafter{\the\toks0 \space #3}% ++ \fi ++ % ++ \edef\writeto{\csname#1indfile\endcsname}% ++ % ++ \safewhatsit\dosubindwrite ++ }% ++ \fi ++} ++ ++% Write the entry in \toks0 to the index file: ++% ++\def\dosubindwrite{% ++ % Put the index entry in the margin if desired. ++ \ifx\SETmarginindex\relax\else ++ \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}% ++ \fi ++ % ++ % Remember, we are within a group. ++ \indexdummies % Must do this here, since \bf, etc expand at this stage ++ \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now ++ % so it will be output as is; and it will print as backslash. ++ % ++ % Process the index entry with all font commands turned off, to ++ % get the string to sort by. ++ {\indexnofonts ++ \edef\temp{\the\toks0}% need full expansion ++ \xdef\indexsorttmp{\temp}% ++ }% ++ % ++ % Set up the complete index entry, with both the sort key and ++ % the original text, including any font commands. We write ++ % three arguments to \entry to the .?? file (four in the ++ % subentry case), texindex reduces to two when writing the .??s ++ % sorted result. ++ \edef\temp{% ++ \write\writeto{% ++ \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}% ++ }% ++ \temp ++} ++ ++% Take care of unwanted page breaks/skips around a whatsit: ++% ++% If a skip is the last thing on the list now, preserve it ++% by backing up by \lastskip, doing the \write, then inserting ++% the skip again. Otherwise, the whatsit generated by the ++% \write or \pdfdest will make \lastskip zero. The result is that ++% sequences like this: ++% @end defun ++% @tindex whatever ++% @defun ... ++% will have extra space inserted, because the \medbreak in the ++% start of the @defun won't see the skip inserted by the @end of ++% the previous defun. ++% ++% But don't do any of this if we're not in vertical mode. We ++% don't want to do a \vskip and prematurely end a paragraph. ++% ++% Avoid page breaks due to these extra skips, too. ++% ++% But wait, there is a catch there: ++% We'll have to check whether \lastskip is zero skip. \ifdim is not ++% sufficient for this purpose, as it ignores stretch and shrink parts ++% of the skip. The only way seems to be to check the textual ++% representation of the skip. ++% ++% The following is almost like \def\zeroskipmacro{0.0pt} except that ++% the ``p'' and ``t'' characters have catcode \other, not 11 (letter). ++% ++\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname} ++% ++\newskip\whatsitskip ++\newcount\whatsitpenalty ++% ++% ..., ready, GO: ++% ++\def\safewhatsit#1{% ++\ifhmode ++ #1% ++\else ++ % \lastskip and \lastpenalty cannot both be nonzero simultaneously. ++ \whatsitskip = \lastskip ++ \edef\lastskipmacro{\the\lastskip}% ++ \whatsitpenalty = \lastpenalty ++ % ++ % If \lastskip is nonzero, that means the last item was a ++ % skip. And since a skip is discardable, that means this ++ % -\skip0 glue we're inserting is preceded by a ++ % non-discardable item, therefore it is not a potential ++ % breakpoint, therefore no \nobreak needed. ++ \ifx\lastskipmacro\zeroskipmacro ++ \else ++ \vskip-\whatsitskip ++ \fi ++ % ++ #1% ++ % ++ \ifx\lastskipmacro\zeroskipmacro ++ % If \lastskip was zero, perhaps the last item was a penalty, and ++ % perhaps it was >=10000, e.g., a \nobreak. In that case, we want ++ % to re-insert the same penalty (values >10000 are used for various ++ % signals); since we just inserted a non-discardable item, any ++ % following glue (such as a \parskip) would be a breakpoint. For example: ++ % ++ % @deffn deffn-whatever ++ % @vindex index-whatever ++ % Description. ++ % would allow a break between the index-whatever whatsit ++ % and the "Description." paragraph. ++ \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi ++ \else ++ % On the other hand, if we had a nonzero \lastskip, ++ % this make-up glue would be preceded by a non-discardable item ++ % (the whatsit from the \write), so we must insert a \nobreak. ++ \nobreak\vskip\whatsitskip ++ \fi ++\fi ++} ++ ++% The index entry written in the file actually looks like ++% \entry {sortstring}{page}{topic} ++% or ++% \entry {sortstring}{page}{topic}{subtopic} ++% The texindex program reads in these files and writes files ++% containing these kinds of lines: ++% \initial {c} ++% before the first topic whose initial is c ++% \entry {topic}{pagelist} ++% for a topic that is used without subtopics ++% \primary {topic} ++% for the beginning of a topic that is used with subtopics ++% \secondary {subtopic}{pagelist} ++% for each subtopic. ++ ++% Define the user-accessible indexing commands ++% @findex, @vindex, @kindex, @cindex. ++ ++\def\findex {\fnindex} ++\def\kindex {\kyindex} ++\def\cindex {\cpindex} ++\def\vindex {\vrindex} ++\def\tindex {\tpindex} ++\def\pindex {\pgindex} ++ ++\def\cindexsub {\begingroup\obeylines\cindexsub} ++{\obeylines % ++\gdef\cindexsub "#1" #2^^M{\endgroup % ++\dosubind{cp}{#2}{#1}}} ++ ++% Define the macros used in formatting output of the sorted index material. ++ ++% @printindex causes a particular index (the ??s file) to get printed. ++% It does not print any chapter heading (usually an @unnumbered). ++% ++\parseargdef\printindex{\begingroup ++ \dobreak \chapheadingskip{10000}% ++ % ++ \smallfonts \rm ++ \tolerance = 9500 ++ \plainfrenchspacing ++ \everypar = {}% don't want the \kern\-parindent from indentation suppression. ++ % ++ % See if the index file exists and is nonempty. ++ % Change catcode of @ here so that if the index file contains ++ % \initial {@} ++ % as its first line, TeX doesn't complain about mismatched braces ++ % (because it thinks @} is a control sequence). ++ \catcode`\@ = 11 ++ \openin 1 \jobname.#1s ++ \ifeof 1 ++ % \enddoublecolumns gets confused if there is no text in the index, ++ % and it loses the chapter title and the aux file entries for the ++ % index. The easiest way to prevent this problem is to make sure ++ % there is some text. ++ \putwordIndexNonexistent ++ \else ++ % ++ % If the index file exists but is empty, then \openin leaves \ifeof ++ % false. We have to make TeX try to read something from the file, so ++ % it can discover if there is anything in it. ++ \read 1 to \temp ++ \ifeof 1 ++ \putwordIndexIsEmpty ++ \else ++ % Index files are almost Texinfo source, but we use \ as the escape ++ % character. It would be better to use @, but that's too big a change ++ % to make right now. ++ \def\indexbackslash{\backslashcurfont}% ++ \catcode`\\ = 0 ++ \escapechar = `\\ ++ \begindoublecolumns ++ \input \jobname.#1s ++ \enddoublecolumns ++ \fi ++ \fi ++ \closein 1 ++\endgroup} ++ ++% These macros are used by the sorted index file itself. ++% Change them to control the appearance of the index. ++ ++\def\initial#1{{% ++ % Some minor font changes for the special characters. ++ \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt ++ % ++ % Remove any glue we may have, we'll be inserting our own. ++ \removelastskip ++ % ++ % We like breaks before the index initials, so insert a bonus. ++ \nobreak ++ \vskip 0pt plus 3\baselineskip ++ \penalty 0 ++ \vskip 0pt plus -3\baselineskip ++ % ++ % Typeset the initial. Making this add up to a whole number of ++ % baselineskips increases the chance of the dots lining up from column ++ % to column. It still won't often be perfect, because of the stretch ++ % we need before each entry, but it's better. ++ % ++ % No shrink because it confuses \balancecolumns. ++ \vskip 1.67\baselineskip plus .5\baselineskip ++ \leftline{\secbf #1}% ++ % Do our best not to break after the initial. ++ \nobreak ++ \vskip .33\baselineskip plus .1\baselineskip ++}} ++ ++% \entry typesets a paragraph consisting of the text (#1), dot leaders, and ++% then page number (#2) flushed to the right margin. It is used for index ++% and table of contents entries. The paragraph is indented by \leftskip. ++% ++% A straightforward implementation would start like this: ++% \def\entry#1#2{... ++% But this frozes the catcodes in the argument, and can cause problems to ++% @code, which sets - active. This problem was fixed by a kludge--- ++% ``-'' was active throughout whole index, but this isn't really right. ++% ++% The right solution is to prevent \entry from swallowing the whole text. ++% --kasal, 21nov03 ++\def\entry{% ++ \begingroup ++ % ++ % Start a new paragraph if necessary, so our assignments below can't ++ % affect previous text. ++ \par ++ % ++ % Do not fill out the last line with white space. ++ \parfillskip = 0in ++ % ++ % No extra space above this paragraph. ++ \parskip = 0in ++ % ++ % Do not prefer a separate line ending with a hyphen to fewer lines. ++ \finalhyphendemerits = 0 ++ % ++ % \hangindent is only relevant when the entry text and page number ++ % don't both fit on one line. In that case, bob suggests starting the ++ % dots pretty far over on the line. Unfortunately, a large ++ % indentation looks wrong when the entry text itself is broken across ++ % lines. So we use a small indentation and put up with long leaders. ++ % ++ % \hangafter is reset to 1 (which is the value we want) at the start ++ % of each paragraph, so we need not do anything with that. ++ \hangindent = 2em ++ % ++ % When the entry text needs to be broken, just fill out the first line ++ % with blank space. ++ \rightskip = 0pt plus1fil ++ % ++ % A bit of stretch before each entry for the benefit of balancing ++ % columns. ++ \vskip 0pt plus1pt ++ % ++ % Swallow the left brace of the text (first parameter): ++ \afterassignment\doentry ++ \let\temp = ++} ++\def\doentry{% ++ \bgroup % Instead of the swallowed brace. ++ \noindent ++ \aftergroup\finishentry ++ % And now comes the text of the entry. ++} ++\def\finishentry#1{% ++ % #1 is the page number. ++ % ++ % The following is kludged to not output a line of dots in the index if ++ % there are no page numbers. The next person who breaks this will be ++ % cursed by a Unix daemon. ++ \setbox\boxA = \hbox{#1}% ++ \ifdim\wd\boxA = 0pt ++ \ % ++ \else ++ % ++ % If we must, put the page number on a line of its own, and fill out ++ % this line with blank space. (The \hfil is overwhelmed with the ++ % fill leaders glue in \indexdotfill if the page number does fit.) ++ \hfil\penalty50 ++ \null\nobreak\indexdotfill % Have leaders before the page number. ++ % ++ % The `\ ' here is removed by the implicit \unskip that TeX does as ++ % part of (the primitive) \par. Without it, a spurious underfull ++ % \hbox ensues. ++ \ifpdf ++ \pdfgettoks#1.% ++ \ \the\toksA ++ \else ++ \ #1% ++ \fi ++ \fi ++ \par ++ \endgroup ++} ++ ++% Like plain.tex's \dotfill, except uses up at least 1 em. ++\def\indexdotfill{\cleaders ++ \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill} ++ ++\def\primary #1{\line{#1\hfil}} ++ ++\newskip\secondaryindent \secondaryindent=0.5cm ++\def\secondary#1#2{{% ++ \parfillskip=0in ++ \parskip=0in ++ \hangindent=1in ++ \hangafter=1 ++ \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill ++ \ifpdf ++ \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. ++ \else ++ #2 ++ \fi ++ \par ++}} ++ ++% Define two-column mode, which we use to typeset indexes. ++% Adapted from the TeXbook, page 416, which is to say, ++% the manmac.tex format used to print the TeXbook itself. ++\catcode`\@=11 ++ ++\newbox\partialpage ++\newdimen\doublecolumnhsize ++ ++\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns ++ % Grab any single-column material above us. ++ \output = {% ++ % ++ % Here is a possibility not foreseen in manmac: if we accumulate a ++ % whole lot of material, we might end up calling this \output ++ % routine twice in a row (see the doublecol-lose test, which is ++ % essentially a couple of indexes with @setchapternewpage off). In ++ % that case we just ship out what is in \partialpage with the normal ++ % output routine. Generally, \partialpage will be empty when this ++ % runs and this will be a no-op. See the indexspread.tex test case. ++ \ifvoid\partialpage \else ++ \onepageout{\pagecontents\partialpage}% ++ \fi ++ % ++ \global\setbox\partialpage = \vbox{% ++ % Unvbox the main output page. ++ \unvbox\PAGE ++ \kern-\topskip \kern\baselineskip ++ }% ++ }% ++ \eject % run that output routine to set \partialpage ++ % ++ % Use the double-column output routine for subsequent pages. ++ \output = {\doublecolumnout}% ++ % ++ % Change the page size parameters. We could do this once outside this ++ % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 ++ % format, but then we repeat the same computation. Repeating a couple ++ % of assignments once per index is clearly meaningless for the ++ % execution time, so we may as well do it in one place. ++ % ++ % First we halve the line length, less a little for the gutter between ++ % the columns. We compute the gutter based on the line length, so it ++ % changes automatically with the paper format. The magic constant ++ % below is chosen so that the gutter has the same value (well, +-<1pt) ++ % as it did when we hard-coded it. ++ % ++ % We put the result in a separate register, \doublecolumhsize, so we ++ % can restore it in \pagesofar, after \hsize itself has (potentially) ++ % been clobbered. ++ % ++ \doublecolumnhsize = \hsize ++ \advance\doublecolumnhsize by -.04154\hsize ++ \divide\doublecolumnhsize by 2 ++ \hsize = \doublecolumnhsize ++ % ++ % Double the \vsize as well. (We don't need a separate register here, ++ % since nobody clobbers \vsize.) ++ \vsize = 2\vsize ++} ++ ++% The double-column output routine for all double-column pages except ++% the last. ++% ++\def\doublecolumnout{% ++ \splittopskip=\topskip \splitmaxdepth=\maxdepth ++ % Get the available space for the double columns -- the normal ++ % (undoubled) page height minus any material left over from the ++ % previous page. ++ \dimen@ = \vsize ++ \divide\dimen@ by 2 ++ \advance\dimen@ by -\ht\partialpage ++ % ++ % box0 will be the left-hand column, box2 the right. ++ \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ ++ \onepageout\pagesofar ++ \unvbox255 ++ \penalty\outputpenalty ++} ++% ++% Re-output the contents of the output page -- any previous material, ++% followed by the two boxes we just split, in box0 and box2. ++\def\pagesofar{% ++ \unvbox\partialpage ++ % ++ \hsize = \doublecolumnhsize ++ \wd0=\hsize \wd2=\hsize ++ \hbox to\pagewidth{\box0\hfil\box2}% ++} ++% ++% All done with double columns. ++\def\enddoublecolumns{% ++ % The following penalty ensures that the page builder is exercised ++ % _before_ we change the output routine. This is necessary in the ++ % following situation: ++ % ++ % The last section of the index consists only of a single entry. ++ % Before this section, \pagetotal is less than \pagegoal, so no ++ % break occurs before the last section starts. However, the last ++ % section, consisting of \initial and the single \entry, does not ++ % fit on the page and has to be broken off. Without the following ++ % penalty the page builder will not be exercised until \eject ++ % below, and by that time we'll already have changed the output ++ % routine to the \balancecolumns version, so the next-to-last ++ % double-column page will be processed with \balancecolumns, which ++ % is wrong: The two columns will go to the main vertical list, with ++ % the broken-off section in the recent contributions. As soon as ++ % the output routine finishes, TeX starts reconsidering the page ++ % break. The two columns and the broken-off section both fit on the ++ % page, because the two columns now take up only half of the page ++ % goal. When TeX sees \eject from below which follows the final ++ % section, it invokes the new output routine that we've set after ++ % \balancecolumns below; \onepageout will try to fit the two columns ++ % and the final section into the vbox of \pageheight (see ++ % \pagebody), causing an overfull box. ++ % ++ % Note that glue won't work here, because glue does not exercise the ++ % page builder, unlike penalties (see The TeXbook, pp. 280-281). ++ \penalty0 ++ % ++ \output = {% ++ % Split the last of the double-column material. Leave it on the ++ % current page, no automatic page break. ++ \balancecolumns ++ % ++ % If we end up splitting too much material for the current page, ++ % though, there will be another page break right after this \output ++ % invocation ends. Having called \balancecolumns once, we do not ++ % want to call it again. Therefore, reset \output to its normal ++ % definition right away. (We hope \balancecolumns will never be ++ % called on to balance too much material, but if it is, this makes ++ % the output somewhat more palatable.) ++ \global\output = {\onepageout{\pagecontents\PAGE}}% ++ }% ++ \eject ++ \endgroup % started in \begindoublecolumns ++ % ++ % \pagegoal was set to the doubled \vsize above, since we restarted ++ % the current page. We're now back to normal single-column ++ % typesetting, so reset \pagegoal to the normal \vsize (after the ++ % \endgroup where \vsize got restored). ++ \pagegoal = \vsize ++} ++% ++% Called at the end of the double column material. ++\def\balancecolumns{% ++ \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120. ++ \dimen@ = \ht0 ++ \advance\dimen@ by \topskip ++ \advance\dimen@ by-\baselineskip ++ \divide\dimen@ by 2 % target to split to ++ %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}% ++ \splittopskip = \topskip ++ % Loop until we get a decent breakpoint. ++ {% ++ \vbadness = 10000 ++ \loop ++ \global\setbox3 = \copy0 ++ \global\setbox1 = \vsplit3 to \dimen@ ++ \ifdim\ht3>\dimen@ ++ \global\advance\dimen@ by 1pt ++ \repeat ++ }% ++ %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}% ++ \setbox0=\vbox to\dimen@{\unvbox1}% ++ \setbox2=\vbox to\dimen@{\unvbox3}% ++ % ++ \pagesofar ++} ++\catcode`\@ = \other ++ ++ ++\message{sectioning,} ++% Chapters, sections, etc. ++ ++% \unnumberedno is an oxymoron, of course. But we count the unnumbered ++% sections so that we can refer to them unambiguously in the pdf ++% outlines by their "section number". We avoid collisions with chapter ++% numbers by starting them at 10000. (If a document ever has 10000 ++% chapters, we're in trouble anyway, I'm sure.) ++\newcount\unnumberedno \unnumberedno = 10000 ++\newcount\chapno ++\newcount\secno \secno=0 ++\newcount\subsecno \subsecno=0 ++\newcount\subsubsecno \subsubsecno=0 ++ ++% This counter is funny since it counts through charcodes of letters A, B, ... ++\newcount\appendixno \appendixno = `\@ ++% ++% \def\appendixletter{\char\the\appendixno} ++% We do the following ugly conditional instead of the above simple ++% construct for the sake of pdftex, which needs the actual ++% letter in the expansion, not just typeset. ++% ++\def\appendixletter{% ++ \ifnum\appendixno=`A A% ++ \else\ifnum\appendixno=`B B% ++ \else\ifnum\appendixno=`C C% ++ \else\ifnum\appendixno=`D D% ++ \else\ifnum\appendixno=`E E% ++ \else\ifnum\appendixno=`F F% ++ \else\ifnum\appendixno=`G G% ++ \else\ifnum\appendixno=`H H% ++ \else\ifnum\appendixno=`I I% ++ \else\ifnum\appendixno=`J J% ++ \else\ifnum\appendixno=`K K% ++ \else\ifnum\appendixno=`L L% ++ \else\ifnum\appendixno=`M M% ++ \else\ifnum\appendixno=`N N% ++ \else\ifnum\appendixno=`O O% ++ \else\ifnum\appendixno=`P P% ++ \else\ifnum\appendixno=`Q Q% ++ \else\ifnum\appendixno=`R R% ++ \else\ifnum\appendixno=`S S% ++ \else\ifnum\appendixno=`T T% ++ \else\ifnum\appendixno=`U U% ++ \else\ifnum\appendixno=`V V% ++ \else\ifnum\appendixno=`W W% ++ \else\ifnum\appendixno=`X X% ++ \else\ifnum\appendixno=`Y Y% ++ \else\ifnum\appendixno=`Z Z% ++ % The \the is necessary, despite appearances, because \appendixletter is ++ % expanded while writing the .toc file. \char\appendixno is not ++ % expandable, thus it is written literally, thus all appendixes come out ++ % with the same letter (or @) in the toc without it. ++ \else\char\the\appendixno ++ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi ++ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi} ++ ++% Each @chapter defines this as the name of the chapter. ++% page headings and footings can use it. @section does likewise. ++% However, they are not reliable, because we don't use marks. ++\def\thischapter{} ++\def\thissection{} ++ ++\newcount\absseclevel % used to calculate proper heading level ++\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count ++ ++% @raisesections: treat @section as chapter, @subsection as section, etc. ++\def\raisesections{\global\advance\secbase by -1} ++\let\up=\raisesections % original BFox name ++ ++% @lowersections: treat @chapter as section, @section as subsection, etc. ++\def\lowersections{\global\advance\secbase by 1} ++\let\down=\lowersections % original BFox name ++ ++% we only have subsub. ++\chardef\maxseclevel = 3 ++% ++% A numbered section within an unnumbered changes to unnumbered too. ++% To achive this, remember the "biggest" unnum. sec. we are currently in: ++\chardef\unmlevel = \maxseclevel ++% ++% Trace whether the current chapter is an appendix or not: ++% \chapheadtype is "N" or "A", unnumbered chapters are ignored. ++\def\chapheadtype{N} ++ ++% Choose a heading macro ++% #1 is heading type ++% #2 is heading level ++% #3 is text for heading ++\def\genhead#1#2#3{% ++ % Compute the abs. sec. level: ++ \absseclevel=#2 ++ \advance\absseclevel by \secbase ++ % Make sure \absseclevel doesn't fall outside the range: ++ \ifnum \absseclevel < 0 ++ \absseclevel = 0 ++ \else ++ \ifnum \absseclevel > 3 ++ \absseclevel = 3 ++ \fi ++ \fi ++ % The heading type: ++ \def\headtype{#1}% ++ \if \headtype U% ++ \ifnum \absseclevel < \unmlevel ++ \chardef\unmlevel = \absseclevel ++ \fi ++ \else ++ % Check for appendix sections: ++ \ifnum \absseclevel = 0 ++ \edef\chapheadtype{\headtype}% ++ \else ++ \if \headtype A\if \chapheadtype N% ++ \errmessage{@appendix... within a non-appendix chapter}% ++ \fi\fi ++ \fi ++ % Check for numbered within unnumbered: ++ \ifnum \absseclevel > \unmlevel ++ \def\headtype{U}% ++ \else ++ \chardef\unmlevel = 3 ++ \fi ++ \fi ++ % Now print the heading: ++ \if \headtype U% ++ \ifcase\absseclevel ++ \unnumberedzzz{#3}% ++ \or \unnumberedseczzz{#3}% ++ \or \unnumberedsubseczzz{#3}% ++ \or \unnumberedsubsubseczzz{#3}% ++ \fi ++ \else ++ \if \headtype A% ++ \ifcase\absseclevel ++ \appendixzzz{#3}% ++ \or \appendixsectionzzz{#3}% ++ \or \appendixsubseczzz{#3}% ++ \or \appendixsubsubseczzz{#3}% ++ \fi ++ \else ++ \ifcase\absseclevel ++ \chapterzzz{#3}% ++ \or \seczzz{#3}% ++ \or \numberedsubseczzz{#3}% ++ \or \numberedsubsubseczzz{#3}% ++ \fi ++ \fi ++ \fi ++ \suppressfirstparagraphindent ++} ++ ++% an interface: ++\def\numhead{\genhead N} ++\def\apphead{\genhead A} ++\def\unnmhead{\genhead U} ++ ++% @chapter, @appendix, @unnumbered. Increment top-level counter, reset ++% all lower-level sectioning counters to zero. ++% ++% Also set \chaplevelprefix, which we prepend to @float sequence numbers ++% (e.g., figures), q.v. By default (before any chapter), that is empty. ++\let\chaplevelprefix = \empty ++% ++\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz ++\def\chapterzzz#1{% ++ % section resetting is \global in case the chapter is in a group, such ++ % as an @include file. ++ \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 ++ \global\advance\chapno by 1 ++ % ++ % Used for \float. ++ \gdef\chaplevelprefix{\the\chapno.}% ++ \resetallfloatnos ++ % ++ \message{\putwordChapter\space \the\chapno}% ++ % ++ % Write the actual heading. ++ \chapmacro{#1}{Ynumbered}{\the\chapno}% ++ % ++ % So @section and the like are numbered underneath this chapter. ++ \global\let\section = \numberedsec ++ \global\let\subsection = \numberedsubsec ++ \global\let\subsubsection = \numberedsubsubsec ++} ++ ++\outer\parseargdef\appendix{\apphead0{#1}} % normally apphead0 calls appendixzzz ++\def\appendixzzz#1{% ++ \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 ++ \global\advance\appendixno by 1 ++ \gdef\chaplevelprefix{\appendixletter.}% ++ \resetallfloatnos ++ % ++ \def\appendixnum{\putwordAppendix\space \appendixletter}% ++ \message{\appendixnum}% ++ % ++ \chapmacro{#1}{Yappendix}{\appendixletter}% ++ % ++ \global\let\section = \appendixsec ++ \global\let\subsection = \appendixsubsec ++ \global\let\subsubsection = \appendixsubsubsec ++} ++ ++\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz ++\def\unnumberedzzz#1{% ++ \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 ++ \global\advance\unnumberedno by 1 ++ % ++ % Since an unnumbered has no number, no prefix for figures. ++ \global\let\chaplevelprefix = \empty ++ \resetallfloatnos ++ % ++ % This used to be simply \message{#1}, but TeX fully expands the ++ % argument to \message. Therefore, if #1 contained @-commands, TeX ++ % expanded them. For example, in `@unnumbered The @cite{Book}', TeX ++ % expanded @cite (which turns out to cause errors because \cite is meant ++ % to be executed, not expanded). ++ % ++ % Anyway, we don't want the fully-expanded definition of @cite to appear ++ % as a result of the \message, we just want `@cite' itself. We use ++ % \the to achieve this: TeX expands \the only once, ++ % simply yielding the contents of . (We also do this for ++ % the toc entries.) ++ \toks0 = {#1}% ++ \message{(\the\toks0)}% ++ % ++ \chapmacro{#1}{Ynothing}{\the\unnumberedno}% ++ % ++ \global\let\section = \unnumberedsec ++ \global\let\subsection = \unnumberedsubsec ++ \global\let\subsubsection = \unnumberedsubsubsec ++} ++ ++% @centerchap is like @unnumbered, but the heading is centered. ++\outer\parseargdef\centerchap{% ++ % Well, we could do the following in a group, but that would break ++ % an assumption that \chapmacro is called at the outermost level. ++ % Thus we are safer this way: --kasal, 24feb04 ++ \let\centerparametersmaybe = \centerparameters ++ \unnmhead0{#1}% ++ \let\centerparametersmaybe = \relax ++} ++ ++% @top is like @unnumbered. ++\let\top\unnumbered ++ ++% Sections. ++\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz ++\def\seczzz#1{% ++ \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 ++ \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}% ++} ++ ++\outer\parseargdef\appendixsection{\apphead1{#1}} % normally calls appendixsectionzzz ++\def\appendixsectionzzz#1{% ++ \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 ++ \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}% ++} ++\let\appendixsec\appendixsection ++ ++\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz ++\def\unnumberedseczzz#1{% ++ \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 ++ \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}% ++} ++ ++% Subsections. ++\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz ++\def\numberedsubseczzz#1{% ++ \global\subsubsecno=0 \global\advance\subsecno by 1 ++ \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}% ++} ++ ++\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz ++\def\appendixsubseczzz#1{% ++ \global\subsubsecno=0 \global\advance\subsecno by 1 ++ \sectionheading{#1}{subsec}{Yappendix}% ++ {\appendixletter.\the\secno.\the\subsecno}% ++} ++ ++\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz ++\def\unnumberedsubseczzz#1{% ++ \global\subsubsecno=0 \global\advance\subsecno by 1 ++ \sectionheading{#1}{subsec}{Ynothing}% ++ {\the\unnumberedno.\the\secno.\the\subsecno}% ++} ++ ++% Subsubsections. ++\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz ++\def\numberedsubsubseczzz#1{% ++ \global\advance\subsubsecno by 1 ++ \sectionheading{#1}{subsubsec}{Ynumbered}% ++ {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}% ++} ++ ++\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz ++\def\appendixsubsubseczzz#1{% ++ \global\advance\subsubsecno by 1 ++ \sectionheading{#1}{subsubsec}{Yappendix}% ++ {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}% ++} ++ ++\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz ++\def\unnumberedsubsubseczzz#1{% ++ \global\advance\subsubsecno by 1 ++ \sectionheading{#1}{subsubsec}{Ynothing}% ++ {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}% ++} ++ ++% These macros control what the section commands do, according ++% to what kind of chapter we are in (ordinary, appendix, or unnumbered). ++% Define them by default for a numbered chapter. ++\let\section = \numberedsec ++\let\subsection = \numberedsubsec ++\let\subsubsection = \numberedsubsubsec ++ ++% Define @majorheading, @heading and @subheading ++ ++% NOTE on use of \vbox for chapter headings, section headings, and such: ++% 1) We use \vbox rather than the earlier \line to permit ++% overlong headings to fold. ++% 2) \hyphenpenalty is set to 10000 because hyphenation in a ++% heading is obnoxious; this forbids it. ++% 3) Likewise, headings look best if no \parindent is used, and ++% if justification is not attempted. Hence \raggedright. ++ ++ ++\def\majorheading{% ++ {\advance\chapheadingskip by 10pt \chapbreak }% ++ \parsearg\chapheadingzzz ++} ++ ++\def\chapheading{\chapbreak \parsearg\chapheadingzzz} ++\def\chapheadingzzz#1{% ++ {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 ++ \parindent=0pt\raggedright ++ \rm #1\hfill}}% ++ \bigskip \par\penalty 200\relax ++ \suppressfirstparagraphindent ++} ++ ++% @heading, @subheading, @subsubheading. ++\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{} ++ \suppressfirstparagraphindent} ++\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{} ++ \suppressfirstparagraphindent} ++\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{} ++ \suppressfirstparagraphindent} ++ ++% These macros generate a chapter, section, etc. heading only ++% (including whitespace, linebreaking, etc. around it), ++% given all the information in convenient, parsed form. ++ ++%%% Args are the skip and penalty (usually negative) ++\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} ++ ++%%% Define plain chapter starts, and page on/off switching for it ++% Parameter controlling skip before chapter headings (if needed) ++ ++\newskip\chapheadingskip ++ ++\def\chapbreak{\dobreak \chapheadingskip {-4000}} ++\def\chappager{\par\vfill\supereject} ++\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi} ++ ++\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} ++ ++\def\CHAPPAGoff{% ++\global\let\contentsalignmacro = \chappager ++\global\let\pchapsepmacro=\chapbreak ++\global\let\pagealignmacro=\chappager} ++ ++\def\CHAPPAGon{% ++\global\let\contentsalignmacro = \chappager ++\global\let\pchapsepmacro=\chappager ++\global\let\pagealignmacro=\chappager ++\global\def\HEADINGSon{\HEADINGSsingle}} ++ ++\def\CHAPPAGodd{% ++\global\let\contentsalignmacro = \chapoddpage ++\global\let\pchapsepmacro=\chapoddpage ++\global\let\pagealignmacro=\chapoddpage ++\global\def\HEADINGSon{\HEADINGSdouble}} ++ ++\CHAPPAGon ++ ++% Chapter opening. ++% ++% #1 is the text, #2 is the section type (Ynumbered, Ynothing, ++% Yappendix, Yomitfromtoc), #3 the chapter number. ++% ++% To test against our argument. ++\def\Ynothingkeyword{Ynothing} ++\def\Yomitfromtockeyword{Yomitfromtoc} ++\def\Yappendixkeyword{Yappendix} ++% ++\def\chapmacro#1#2#3{% ++ \pchapsepmacro ++ {% ++ \chapfonts \rm ++ % ++ % Have to define \thissection before calling \donoderef, because the ++ % xref code eventually uses it. On the other hand, it has to be called ++ % after \pchapsepmacro, or the headline will change too soon. ++ \gdef\thissection{#1}% ++ \gdef\thischaptername{#1}% ++ % ++ % Only insert the separating space if we have a chapter/appendix ++ % number, and don't print the unnumbered ``number''. ++ \def\temptype{#2}% ++ \ifx\temptype\Ynothingkeyword ++ \setbox0 = \hbox{}% ++ \def\toctype{unnchap}% ++ \gdef\thischapternum{}% ++ \gdef\thischapter{#1}% ++ \else\ifx\temptype\Yomitfromtockeyword ++ \setbox0 = \hbox{}% contents like unnumbered, but no toc entry ++ \def\toctype{omit}% ++ \gdef\thischapternum{}% ++ \gdef\thischapter{}% ++ \else\ifx\temptype\Yappendixkeyword ++ \setbox0 = \hbox{\putwordAppendix{} #3\enspace}% ++ \def\toctype{app}% ++ \xdef\thischapternum{\appendixletter}% ++ % We don't substitute the actual chapter name into \thischapter ++ % because we don't want its macros evaluated now. And we don't ++ % use \thissection because that changes with each section. ++ % ++ \xdef\thischapter{\putwordAppendix{} \appendixletter: ++ \noexpand\thischaptername}% ++ \else ++ \setbox0 = \hbox{#3\enspace}% ++ \def\toctype{numchap}% ++ \xdef\thischapternum{\the\chapno}% ++ \xdef\thischapter{\putwordChapter{} \the\chapno: ++ \noexpand\thischaptername}% ++ \fi\fi\fi ++ % ++ % Write the toc entry for this chapter. Must come before the ++ % \donoderef, because we include the current node name in the toc ++ % entry, and \donoderef resets it to empty. ++ \writetocentry{\toctype}{#1}{#3}% ++ % ++ % For pdftex, we have to write out the node definition (aka, make ++ % the pdfdest) after any page break, but before the actual text has ++ % been typeset. If the destination for the pdf outline is after the ++ % text, then jumping from the outline may wind up with the text not ++ % being visible, for instance under high magnification. ++ \donoderef{#2}% ++ % ++ % Typeset the actual heading. ++ \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright ++ \hangindent=\wd0 \centerparametersmaybe ++ \unhbox0 #1\par}% ++ }% ++ \nobreak\bigskip % no page break after a chapter title ++ \nobreak ++} ++ ++% @centerchap -- centered and unnumbered. ++\let\centerparametersmaybe = \relax ++\def\centerparameters{% ++ \advance\rightskip by 3\rightskip ++ \leftskip = \rightskip ++ \parfillskip = 0pt ++} ++ ++ ++% I don't think this chapter style is supported any more, so I'm not ++% updating it with the new noderef stuff. We'll see. --karl, 11aug03. ++% ++\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} ++% ++\def\unnchfopen #1{% ++\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 ++ \parindent=0pt\raggedright ++ \rm #1\hfill}}\bigskip \par\nobreak ++} ++\def\chfopen #1#2{\chapoddpage {\chapfonts ++\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% ++\par\penalty 5000 % ++} ++\def\centerchfopen #1{% ++\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 ++ \parindent=0pt ++ \hfill {\rm #1}\hfill}}\bigskip \par\nobreak ++} ++\def\CHAPFopen{% ++ \global\let\chapmacro=\chfopen ++ \global\let\centerchapmacro=\centerchfopen} ++ ++ ++% Section titles. These macros combine the section number parts and ++% call the generic \sectionheading to do the printing. ++% ++\newskip\secheadingskip ++\def\secheadingbreak{\dobreak \secheadingskip{-1000}} ++ ++% Subsection titles. ++\newskip\subsecheadingskip ++\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}} ++ ++% Subsubsection titles. ++\def\subsubsecheadingskip{\subsecheadingskip} ++\def\subsubsecheadingbreak{\subsecheadingbreak} ++ ++ ++% Print any size, any type, section title. ++% ++% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is ++% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the ++% section number. ++% ++\def\sectionheading#1#2#3#4{% ++ {% ++ % Switch to the right set of fonts. ++ \csname #2fonts\endcsname \rm ++ % ++ % Insert space above the heading. ++ \csname #2headingbreak\endcsname ++ % ++ % Only insert the space after the number if we have a section number. ++ \def\sectionlevel{#2}% ++ \def\temptype{#3}% ++ % ++ \ifx\temptype\Ynothingkeyword ++ \setbox0 = \hbox{}% ++ \def\toctype{unn}% ++ \gdef\thissection{#1}% ++ \else\ifx\temptype\Yomitfromtockeyword ++ % for @headings -- no section number, don't include in toc, ++ % and don't redefine \thissection. ++ \setbox0 = \hbox{}% ++ \def\toctype{omit}% ++ \let\sectionlevel=\empty ++ \else\ifx\temptype\Yappendixkeyword ++ \setbox0 = \hbox{#4\enspace}% ++ \def\toctype{app}% ++ \gdef\thissection{#1}% ++ \else ++ \setbox0 = \hbox{#4\enspace}% ++ \def\toctype{num}% ++ \gdef\thissection{#1}% ++ \fi\fi\fi ++ % ++ % Write the toc entry (before \donoderef). See comments in \chapmacro. ++ \writetocentry{\toctype\sectionlevel}{#1}{#4}% ++ % ++ % Write the node reference (= pdf destination for pdftex). ++ % Again, see comments in \chapmacro. ++ \donoderef{#3}% ++ % ++ % Interline glue will be inserted when the vbox is completed. ++ % That glue will be a valid breakpoint for the page, since it'll be ++ % preceded by a whatsit (usually from the \donoderef, or from the ++ % \writetocentry if there was no node). We don't want to allow that ++ % break, since then the whatsits could end up on page n while the ++ % section is on page n+1, thus toc/etc. are wrong. Debian bug 276000. ++ \nobreak ++ % ++ % Output the actual section heading. ++ \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright ++ \hangindent=\wd0 % zero if no section number ++ \unhbox0 #1}% ++ }% ++ % Add extra space after the heading -- half of whatever came above it. ++ % Don't allow stretch, though. ++ \kern .5 \csname #2headingskip\endcsname ++ % ++ % Do not let the kern be a potential breakpoint, as it would be if it ++ % was followed by glue. ++ \nobreak ++ % ++ % We'll almost certainly start a paragraph next, so don't let that ++ % glue accumulate. (Not a breakpoint because it's preceded by a ++ % discardable item.) ++ \vskip-\parskip ++ % ++ % This is purely so the last item on the list is a known \penalty > ++ % 10000. This is so \startdefun can avoid allowing breakpoints after ++ % section headings. Otherwise, it would insert a valid breakpoint between: ++ % ++ % @section sec-whatever ++ % @deffn def-whatever ++ \penalty 10001 ++} ++ ++ ++\message{toc,} ++% Table of contents. ++\newwrite\tocfile ++ ++% Write an entry to the toc file, opening it if necessary. ++% Called from @chapter, etc. ++% ++% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno} ++% We append the current node name (if any) and page number as additional ++% arguments for the \{chap,sec,...}entry macros which will eventually ++% read this. The node name is used in the pdf outlines as the ++% destination to jump to. ++% ++% We open the .toc file for writing here instead of at @setfilename (or ++% any other fixed time) so that @contents can be anywhere in the document. ++% But if #1 is `omit', then we don't do anything. This is used for the ++% table of contents chapter openings themselves. ++% ++\newif\iftocfileopened ++\def\omitkeyword{omit}% ++% ++\def\writetocentry#1#2#3{% ++ \edef\writetoctype{#1}% ++ \ifx\writetoctype\omitkeyword \else ++ \iftocfileopened\else ++ \immediate\openout\tocfile = \jobname.toc ++ \global\tocfileopenedtrue ++ \fi ++ % ++ \iflinks ++ {\atdummies ++ \edef\temp{% ++ \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}% ++ \temp ++ }% ++ \fi ++ \fi ++ % ++ % Tell \shipout to create a pdf destination on each page, if we're ++ % writing pdf. These are used in the table of contents. We can't ++ % just write one on every page because the title pages are numbered ++ % 1 and 2 (the page numbers aren't printed), and so are the first ++ % two pages of the document. Thus, we'd have two destinations named ++ % `1', and two named `2'. ++ \ifpdf \global\pdfmakepagedesttrue \fi ++} ++ ++ ++% These characters do not print properly in the Computer Modern roman ++% fonts, so we must take special care. This is more or less redundant ++% with the Texinfo input format setup at the end of this file. ++% ++\def\activecatcodes{% ++ \catcode`\"=\active ++ \catcode`\$=\active ++ \catcode`\<=\active ++ \catcode`\>=\active ++ \catcode`\\=\active ++ \catcode`\^=\active ++ \catcode`\_=\active ++ \catcode`\|=\active ++ \catcode`\~=\active ++} ++ ++ ++% Read the toc file, which is essentially Texinfo input. ++\def\readtocfile{% ++ \setupdatafile ++ \activecatcodes ++ \input \tocreadfilename ++} ++ ++\newskip\contentsrightmargin \contentsrightmargin=1in ++\newcount\savepageno ++\newcount\lastnegativepageno \lastnegativepageno = -1 ++ ++% Prepare to read what we've written to \tocfile. ++% ++\def\startcontents#1{% ++ % If @setchapternewpage on, and @headings double, the contents should ++ % start on an odd page, unlike chapters. Thus, we maintain ++ % \contentsalignmacro in parallel with \pagealignmacro. ++ % From: Torbjorn Granlund ++ \contentsalignmacro ++ \immediate\closeout\tocfile ++ % ++ % Don't need to put `Contents' or `Short Contents' in the headline. ++ % It is abundantly clear what they are. ++ \def\thischapter{}% ++ \chapmacro{#1}{Yomitfromtoc}{}% ++ % ++ \savepageno = \pageno ++ \begingroup % Set up to handle contents files properly. ++ \raggedbottom % Worry more about breakpoints than the bottom. ++ \advance\hsize by -\contentsrightmargin % Don't use the full line length. ++ % ++ % Roman numerals for page numbers. ++ \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi ++} ++ ++% redefined for the two-volume lispref. We always output on ++% \jobname.toc even if this is redefined. ++% ++\def\tocreadfilename{\jobname.toc} ++ ++% Normal (long) toc. ++% ++\def\contents{% ++ \startcontents{\putwordTOC}% ++ \openin 1 \tocreadfilename\space ++ \ifeof 1 \else ++ \readtocfile ++ \fi ++ \vfill \eject ++ \contentsalignmacro % in case @setchapternewpage odd is in effect ++ \ifeof 1 \else ++ \pdfmakeoutlines ++ \fi ++ \closein 1 ++ \endgroup ++ \lastnegativepageno = \pageno ++ \global\pageno = \savepageno ++} ++ ++% And just the chapters. ++\def\summarycontents{% ++ \startcontents{\putwordShortTOC}% ++ % ++ \let\numchapentry = \shortchapentry ++ \let\appentry = \shortchapentry ++ \let\unnchapentry = \shortunnchapentry ++ % We want a true roman here for the page numbers. ++ \secfonts ++ \let\rm=\shortcontrm \let\bf=\shortcontbf ++ \let\sl=\shortcontsl \let\tt=\shortconttt ++ \rm ++ \hyphenpenalty = 10000 ++ \advance\baselineskip by 1pt % Open it up a little. ++ \def\numsecentry##1##2##3##4{} ++ \let\appsecentry = \numsecentry ++ \let\unnsecentry = \numsecentry ++ \let\numsubsecentry = \numsecentry ++ \let\appsubsecentry = \numsecentry ++ \let\unnsubsecentry = \numsecentry ++ \let\numsubsubsecentry = \numsecentry ++ \let\appsubsubsecentry = \numsecentry ++ \let\unnsubsubsecentry = \numsecentry ++ \openin 1 \tocreadfilename\space ++ \ifeof 1 \else ++ \readtocfile ++ \fi ++ \closein 1 ++ \vfill \eject ++ \contentsalignmacro % in case @setchapternewpage odd is in effect ++ \endgroup ++ \lastnegativepageno = \pageno ++ \global\pageno = \savepageno ++} ++\let\shortcontents = \summarycontents ++ ++% Typeset the label for a chapter or appendix for the short contents. ++% The arg is, e.g., `A' for an appendix, or `3' for a chapter. ++% ++\def\shortchaplabel#1{% ++ % This space should be enough, since a single number is .5em, and the ++ % widest letter (M) is 1em, at least in the Computer Modern fonts. ++ % But use \hss just in case. ++ % (This space doesn't include the extra space that gets added after ++ % the label; that gets put in by \shortchapentry above.) ++ % ++ % We'd like to right-justify chapter numbers, but that looks strange ++ % with appendix letters. And right-justifying numbers and ++ % left-justifying letters looks strange when there is less than 10 ++ % chapters. Have to read the whole toc once to know how many chapters ++ % there are before deciding ... ++ \hbox to 1em{#1\hss}% ++} ++ ++% These macros generate individual entries in the table of contents. ++% The first argument is the chapter or section name. ++% The last argument is the page number. ++% The arguments in between are the chapter number, section number, ... ++ ++% Chapters, in the main contents. ++\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}} ++% ++% Chapters, in the short toc. ++% See comments in \dochapentry re vbox and related settings. ++\def\shortchapentry#1#2#3#4{% ++ \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}% ++} ++ ++% Appendices, in the main contents. ++% Need the word Appendix, and a fixed-size box. ++% ++\def\appendixbox#1{% ++ % We use M since it's probably the widest letter. ++ \setbox0 = \hbox{\putwordAppendix{} M}% ++ \hbox to \wd0{\putwordAppendix{} #1\hss}} ++% ++\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}} ++ ++% Unnumbered chapters. ++\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}} ++\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}} ++ ++% Sections. ++\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}} ++\let\appsecentry=\numsecentry ++\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}} ++ ++% Subsections. ++\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}} ++\let\appsubsecentry=\numsubsecentry ++\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}} ++ ++% And subsubsections. ++\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}} ++\let\appsubsubsecentry=\numsubsubsecentry ++\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}} ++ ++% This parameter controls the indentation of the various levels. ++% Same as \defaultparindent. ++\newdimen\tocindent \tocindent = 15pt ++ ++% Now for the actual typesetting. In all these, #1 is the text and #2 is the ++% page number. ++% ++% If the toc has to be broken over pages, we want it to be at chapters ++% if at all possible; hence the \penalty. ++\def\dochapentry#1#2{% ++ \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip ++ \begingroup ++ \chapentryfonts ++ \tocentry{#1}{\dopageno\bgroup#2\egroup}% ++ \endgroup ++ \nobreak\vskip .25\baselineskip plus.1\baselineskip ++} ++ ++\def\dosecentry#1#2{\begingroup ++ \secentryfonts \leftskip=\tocindent ++ \tocentry{#1}{\dopageno\bgroup#2\egroup}% ++\endgroup} ++ ++\def\dosubsecentry#1#2{\begingroup ++ \subsecentryfonts \leftskip=2\tocindent ++ \tocentry{#1}{\dopageno\bgroup#2\egroup}% ++\endgroup} ++ ++\def\dosubsubsecentry#1#2{\begingroup ++ \subsubsecentryfonts \leftskip=3\tocindent ++ \tocentry{#1}{\dopageno\bgroup#2\egroup}% ++\endgroup} ++ ++% We use the same \entry macro as for the index entries. ++\let\tocentry = \entry ++ ++% Space between chapter (or whatever) number and the title. ++\def\labelspace{\hskip1em \relax} ++ ++\def\dopageno#1{{\rm #1}} ++\def\doshortpageno#1{{\rm #1}} ++ ++\def\chapentryfonts{\secfonts \rm} ++\def\secentryfonts{\textfonts} ++\def\subsecentryfonts{\textfonts} ++\def\subsubsecentryfonts{\textfonts} ++ ++ ++\message{environments,} ++% @foo ... @end foo. ++ ++% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. ++% ++% Since these characters are used in examples, it should be an even number of ++% \tt widths. Each \tt character is 1en, so two makes it 1em. ++% ++\def\point{$\star$} ++\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} ++\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} ++\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} ++\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} ++ ++% The @error{} command. ++% Adapted from the TeXbook's \boxit. ++% ++\newbox\errorbox ++% ++{\tentt \global\dimen0 = 3em}% Width of the box. ++\dimen2 = .55pt % Thickness of rules ++% The text. (`r' is open on the right, `e' somewhat less so on the left.) ++\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt} ++% ++\setbox\errorbox=\hbox to \dimen0{\hfil ++ \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. ++ \advance\hsize by -2\dimen2 % Rules. ++ \vbox{% ++ \hrule height\dimen2 ++ \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. ++ \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. ++ \kern3pt\vrule width\dimen2}% Space to right. ++ \hrule height\dimen2} ++ \hfil} ++% ++\def\error{\leavevmode\lower.7ex\copy\errorbox} ++ ++% @tex ... @end tex escapes into raw Tex temporarily. ++% One exception: @ is still an escape character, so that @end tex works. ++% But \@ or @@ will get a plain tex @ character. ++ ++\envdef\tex{% ++ \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 ++ \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 ++ \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie ++ \catcode `\%=14 ++ \catcode `\+=\other ++ \catcode `\"=\other ++ \catcode `\|=\other ++ \catcode `\<=\other ++ \catcode `\>=\other ++ \escapechar=`\\ ++ % ++ \let\b=\ptexb ++ \let\bullet=\ptexbullet ++ \let\c=\ptexc ++ \let\,=\ptexcomma ++ \let\.=\ptexdot ++ \let\dots=\ptexdots ++ \let\equiv=\ptexequiv ++ \let\!=\ptexexclam ++ \let\i=\ptexi ++ \let\indent=\ptexindent ++ \let\noindent=\ptexnoindent ++ \let\{=\ptexlbrace ++ \let\+=\tabalign ++ \let\}=\ptexrbrace ++ \let\/=\ptexslash ++ \let\*=\ptexstar ++ \let\t=\ptext ++ \let\frenchspacing=\plainfrenchspacing ++ % ++ \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% ++ \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% ++ \def\@{@}% ++} ++% There is no need to define \Etex. ++ ++% Define @lisp ... @end lisp. ++% @lisp environment forms a group so it can rebind things, ++% including the definition of @end lisp (which normally is erroneous). ++ ++% Amount to narrow the margins by for @lisp. ++\newskip\lispnarrowing \lispnarrowing=0.4in ++ ++% This is the definition that ^^M gets inside @lisp, @example, and other ++% such environments. \null is better than a space, since it doesn't ++% have any width. ++\def\lisppar{\null\endgraf} ++ ++% This space is always present above and below environments. ++\newskip\envskipamount \envskipamount = 0pt ++ ++% Make spacing and below environment symmetrical. We use \parskip here ++% to help in doing that, since in @example-like environments \parskip ++% is reset to zero; thus the \afterenvbreak inserts no space -- but the ++% start of the next paragraph will insert \parskip. ++% ++\def\aboveenvbreak{{% ++ % =10000 instead of <10000 because of a special case in \itemzzz and ++ % \sectionheading, q.v. ++ \ifnum \lastpenalty=10000 \else ++ \advance\envskipamount by \parskip ++ \endgraf ++ \ifdim\lastskip<\envskipamount ++ \removelastskip ++ % it's not a good place to break if the last penalty was \nobreak ++ % or better ... ++ \ifnum\lastpenalty<10000 \penalty-50 \fi ++ \vskip\envskipamount ++ \fi ++ \fi ++}} ++ ++\let\afterenvbreak = \aboveenvbreak ++ ++% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will ++% also clear it, so that its embedded environments do the narrowing again. ++\let\nonarrowing=\relax ++ ++% @cartouche ... @end cartouche: draw rectangle w/rounded corners around ++% environment contents. ++\font\circle=lcircle10 ++\newdimen\circthick ++\newdimen\cartouter\newdimen\cartinner ++\newskip\normbskip\newskip\normpskip\newskip\normlskip ++\circthick=\fontdimen8\circle ++% ++\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth ++\def\ctr{{\hskip 6pt\circle\char'010}} ++\def\cbl{{\circle\char'012\hskip -6pt}} ++\def\cbr{{\hskip 6pt\circle\char'011}} ++\def\carttop{\hbox to \cartouter{\hskip\lskip ++ \ctl\leaders\hrule height\circthick\hfil\ctr ++ \hskip\rskip}} ++\def\cartbot{\hbox to \cartouter{\hskip\lskip ++ \cbl\leaders\hrule height\circthick\hfil\cbr ++ \hskip\rskip}} ++% ++\newskip\lskip\newskip\rskip ++ ++\envdef\cartouche{% ++ \ifhmode\par\fi % can't be in the midst of a paragraph. ++ \startsavinginserts ++ \lskip=\leftskip \rskip=\rightskip ++ \leftskip=0pt\rightskip=0pt % we want these *outside*. ++ \cartinner=\hsize \advance\cartinner by-\lskip ++ \advance\cartinner by-\rskip ++ \cartouter=\hsize ++ \advance\cartouter by 18.4pt % allow for 3pt kerns on either ++ % side, and for 6pt waste from ++ % each corner char, and rule thickness ++ \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip ++ % Flag to tell @lisp, etc., not to narrow margin. ++ \let\nonarrowing = t% ++ \vbox\bgroup ++ \baselineskip=0pt\parskip=0pt\lineskip=0pt ++ \carttop ++ \hbox\bgroup ++ \hskip\lskip ++ \vrule\kern3pt ++ \vbox\bgroup ++ \kern3pt ++ \hsize=\cartinner ++ \baselineskip=\normbskip ++ \lineskip=\normlskip ++ \parskip=\normpskip ++ \vskip -\parskip ++ \comment % For explanation, see the end of \def\group. ++} ++\def\Ecartouche{% ++ \ifhmode\par\fi ++ \kern3pt ++ \egroup ++ \kern3pt\vrule ++ \hskip\rskip ++ \egroup ++ \cartbot ++ \egroup ++ \checkinserts ++} ++ ++ ++% This macro is called at the beginning of all the @example variants, ++% inside a group. ++\def\nonfillstart{% ++ \aboveenvbreak ++ \hfuzz = 12pt % Don't be fussy ++ \sepspaces % Make spaces be word-separators rather than space tokens. ++ \let\par = \lisppar % don't ignore blank lines ++ \obeylines % each line of input is a line of output ++ \parskip = 0pt ++ \parindent = 0pt ++ \emergencystretch = 0pt % don't try to avoid overfull boxes ++ \ifx\nonarrowing\relax ++ \advance \leftskip by \lispnarrowing ++ \exdentamount=\lispnarrowing ++ \else ++ \let\nonarrowing = \relax ++ \fi ++ \let\exdent=\nofillexdent ++} ++ ++% If you want all examples etc. small: @set dispenvsize small. ++% If you want even small examples the full size: @set dispenvsize nosmall. ++% This affects the following displayed environments: ++% @example, @display, @format, @lisp ++% ++\def\smallword{small} ++\def\nosmallword{nosmall} ++\let\SETdispenvsize\relax ++\def\setnormaldispenv{% ++ \ifx\SETdispenvsize\smallword ++ % end paragraph for sake of leading, in case document has no blank ++ % line. This is redundant with what happens in \aboveenvbreak, but ++ % we need to do it before changing the fonts, and it's inconvenient ++ % to change the fonts afterward. ++ \ifnum \lastpenalty=10000 \else \endgraf \fi ++ \smallexamplefonts \rm ++ \fi ++} ++\def\setsmalldispenv{% ++ \ifx\SETdispenvsize\nosmallword ++ \else ++ \ifnum \lastpenalty=10000 \else \endgraf \fi ++ \smallexamplefonts \rm ++ \fi ++} ++ ++% We often define two environments, @foo and @smallfoo. ++% Let's do it by one command: ++\def\makedispenv #1#2{ ++ \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2} ++ \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2} ++ \expandafter\let\csname E#1\endcsname \afterenvbreak ++ \expandafter\let\csname Esmall#1\endcsname \afterenvbreak ++} ++ ++% Define two synonyms: ++\def\maketwodispenvs #1#2#3{ ++ \makedispenv{#1}{#3} ++ \makedispenv{#2}{#3} ++} ++ ++% @lisp: indented, narrowed, typewriter font; @example: same as @lisp. ++% ++% @smallexample and @smalllisp: use smaller fonts. ++% Originally contributed by Pavel@xerox. ++% ++\maketwodispenvs {lisp}{example}{% ++ \nonfillstart ++ \tt\quoteexpand ++ \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special. ++ \gobble % eat return ++} ++% @display/@smalldisplay: same as @lisp except keep current font. ++% ++\makedispenv {display}{% ++ \nonfillstart ++ \gobble ++} ++ ++% @format/@smallformat: same as @display except don't narrow margins. ++% ++\makedispenv{format}{% ++ \let\nonarrowing = t% ++ \nonfillstart ++ \gobble ++} ++ ++% @flushleft: same as @format, but doesn't obey \SETdispenvsize. ++\envdef\flushleft{% ++ \let\nonarrowing = t% ++ \nonfillstart ++ \gobble ++} ++\let\Eflushleft = \afterenvbreak ++ ++% @flushright. ++% ++\envdef\flushright{% ++ \let\nonarrowing = t% ++ \nonfillstart ++ \advance\leftskip by 0pt plus 1fill ++ \gobble ++} ++\let\Eflushright = \afterenvbreak ++ ++ ++% @quotation does normal linebreaking (hence we can't use \nonfillstart) ++% and narrows the margins. We keep \parskip nonzero in general, since ++% we're doing normal filling. So, when using \aboveenvbreak and ++% \afterenvbreak, temporarily make \parskip 0. ++% ++\envdef\quotation{% ++ {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip ++ \parindent=0pt ++ % ++ % @cartouche defines \nonarrowing to inhibit narrowing at next level down. ++ \ifx\nonarrowing\relax ++ \advance\leftskip by \lispnarrowing ++ \advance\rightskip by \lispnarrowing ++ \exdentamount = \lispnarrowing ++ \else ++ \let\nonarrowing = \relax ++ \fi ++ \parsearg\quotationlabel ++} ++ ++% We have retained a nonzero parskip for the environment, since we're ++% doing normal filling. ++% ++\def\Equotation{% ++ \par ++ \ifx\quotationauthor\undefined\else ++ % indent a bit. ++ \leftline{\kern 2\leftskip \sl ---\quotationauthor}% ++ \fi ++ {\parskip=0pt \afterenvbreak}% ++} ++ ++% If we're given an argument, typeset it in bold with a colon after. ++\def\quotationlabel#1{% ++ \def\temp{#1}% ++ \ifx\temp\empty \else ++ {\bf #1: }% ++ \fi ++} ++ ++ ++% LaTeX-like @verbatim...@end verbatim and @verb{...} ++% If we want to allow any as delimiter, ++% we need the curly braces so that makeinfo sees the @verb command, eg: ++% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org ++% ++% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. ++% ++% [Knuth] p.344; only we need to do the other characters Texinfo sets ++% active too. Otherwise, they get lost as the first character on a ++% verbatim line. ++\def\dospecials{% ++ \do\ \do\\\do\{\do\}\do\$\do\&% ++ \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% ++ \do\<\do\>\do\|\do\@\do+\do\"% ++} ++% ++% [Knuth] p. 380 ++\def\uncatcodespecials{% ++ \def\do##1{\catcode`##1=\other}\dospecials} ++% ++% [Knuth] pp. 380,381,391 ++% Disable Spanish ligatures ?` and !` of \tt font ++\begingroup ++ \catcode`\`=\active\gdef`{\relax\lq} ++\endgroup ++% ++% Setup for the @verb command. ++% ++% Eight spaces for a tab ++\begingroup ++ \catcode`\^^I=\active ++ \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }} ++\endgroup ++% ++\def\setupverb{% ++ \tt % easiest (and conventionally used) font for verbatim ++ \def\par{\leavevmode\endgraf}% ++ \catcode`\`=\active ++ \tabeightspaces ++ % Respect line breaks, ++ % print special symbols as themselves, and ++ % make each space count ++ % must do in this order: ++ \obeylines \uncatcodespecials \sepspaces ++} ++ ++% Setup for the @verbatim environment ++% ++% Real tab expansion ++\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount ++% ++\def\starttabbox{\setbox0=\hbox\bgroup} ++ ++% Allow an option to not replace quotes with a regular directed right ++% quote/apostrophe (char 0x27), but instead use the undirected quote ++% from cmtt (char 0x0d). The undirected quote is ugly, so don't make it ++% the default, but it works for pasting with more pdf viewers (at least ++% evince), the lilypond developers report. xpdf does work with the ++% regular 0x27. ++% ++\def\codequoteright{% ++ \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax ++ \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax ++ '% ++ \else \char'15 \fi ++ \else \char'15 \fi ++} ++% ++% and a similar option for the left quote char vs. a grave accent. ++% Modern fonts display ASCII 0x60 as a grave accent, so some people like ++% the code environments to do likewise. ++% ++\def\codequoteleft{% ++ \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax ++ \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax ++ `% ++ \else \char'22 \fi ++ \else \char'22 \fi ++} ++% ++\begingroup ++ \catcode`\^^I=\active ++ \gdef\tabexpand{% ++ \catcode`\^^I=\active ++ \def^^I{\leavevmode\egroup ++ \dimen0=\wd0 % the width so far, or since the previous tab ++ \divide\dimen0 by\tabw ++ \multiply\dimen0 by\tabw % compute previous multiple of \tabw ++ \advance\dimen0 by\tabw % advance to next multiple of \tabw ++ \wd0=\dimen0 \box0 \starttabbox ++ }% ++ } ++ \catcode`\'=\active ++ \gdef\rquoteexpand{\catcode\rquoteChar=\active \def'{\codequoteright}}% ++ % ++ \catcode`\`=\active ++ \gdef\lquoteexpand{\catcode\lquoteChar=\active \def`{\codequoteleft}}% ++ % ++ \gdef\quoteexpand{\rquoteexpand \lquoteexpand}% ++\endgroup ++ ++% start the verbatim environment. ++\def\setupverbatim{% ++ \let\nonarrowing = t% ++ \nonfillstart ++ % Easiest (and conventionally used) font for verbatim ++ \tt ++ \def\par{\leavevmode\egroup\box0\endgraf}% ++ \catcode`\`=\active ++ \tabexpand ++ \quoteexpand ++ % Respect line breaks, ++ % print special symbols as themselves, and ++ % make each space count ++ % must do in this order: ++ \obeylines \uncatcodespecials \sepspaces ++ \everypar{\starttabbox}% ++} ++ ++% Do the @verb magic: verbatim text is quoted by unique ++% delimiter characters. Before first delimiter expect a ++% right brace, after last delimiter expect closing brace: ++% ++% \def\doverb'{'#1'}'{#1} ++% ++% [Knuth] p. 382; only eat outer {} ++\begingroup ++ \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other ++ \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next] ++\endgroup ++% ++\def\verb{\begingroup\setupverb\doverb} ++% ++% ++% Do the @verbatim magic: define the macro \doverbatim so that ++% the (first) argument ends when '@end verbatim' is reached, ie: ++% ++% \def\doverbatim#1@end verbatim{#1} ++% ++% For Texinfo it's a lot easier than for LaTeX, ++% because texinfo's \verbatim doesn't stop at '\end{verbatim}': ++% we need not redefine '\', '{' and '}'. ++% ++% Inspired by LaTeX's verbatim command set [latex.ltx] ++% ++\begingroup ++ \catcode`\ =\active ++ \obeylines % ++ % ignore everything up to the first ^^M, that's the newline at the end ++ % of the @verbatim input line itself. Otherwise we get an extra blank ++ % line in the output. ++ \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}% ++ % We really want {...\end verbatim} in the body of the macro, but ++ % without the active space; thus we have to use \xdef and \gobble. ++\endgroup ++% ++\envdef\verbatim{% ++ \setupverbatim\doverbatim ++} ++\let\Everbatim = \afterenvbreak ++ ++ ++% @verbatiminclude FILE - insert text of file in verbatim environment. ++% ++\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude} ++% ++\def\doverbatiminclude#1{% ++ {% ++ \makevalueexpandable ++ \setupverbatim ++ \input #1 ++ \afterenvbreak ++ }% ++} ++ ++% @copying ... @end copying. ++% Save the text away for @insertcopying later. ++% ++% We save the uninterpreted tokens, rather than creating a box. ++% Saving the text in a box would be much easier, but then all the ++% typesetting commands (@smallbook, font changes, etc.) have to be done ++% beforehand -- and a) we want @copying to be done first in the source ++% file; b) letting users define the frontmatter in as flexible order as ++% possible is very desirable. ++% ++\def\copying{\checkenv{}\begingroup\scanargctxt\docopying} ++\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}} ++% ++\def\insertcopying{% ++ \begingroup ++ \parindent = 0pt % paragraph indentation looks wrong on title page ++ \scanexp\copyingtext ++ \endgroup ++} ++ ++ ++\message{defuns,} ++% @defun etc. ++ ++\newskip\defbodyindent \defbodyindent=.4in ++\newskip\defargsindent \defargsindent=50pt ++\newskip\deflastargmargin \deflastargmargin=18pt ++\newcount\defunpenalty ++ ++% Start the processing of @deffn: ++\def\startdefun{% ++ \ifnum\lastpenalty<10000 ++ \medbreak ++ \defunpenalty=10003 % Will keep this @deffn together with the ++ % following @def command, see below. ++ \else ++ % If there are two @def commands in a row, we'll have a \nobreak, ++ % which is there to keep the function description together with its ++ % header. But if there's nothing but headers, we need to allow a ++ % break somewhere. Check specifically for penalty 10002, inserted ++ % by \printdefunline, instead of 10000, since the sectioning ++ % commands also insert a nobreak penalty, and we don't want to allow ++ % a break between a section heading and a defun. ++ % ++ % As a minor refinement, we avoid "club" headers by signalling ++ % with penalty of 10003 after the very first @deffn in the ++ % sequence (see above), and penalty of 10002 after any following ++ % @def command. ++ \ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi ++ % ++ % Similarly, after a section heading, do not allow a break. ++ % But do insert the glue. ++ \medskip % preceded by discardable penalty, so not a breakpoint ++ \fi ++ % ++ \parindent=0in ++ \advance\leftskip by \defbodyindent ++ \exdentamount=\defbodyindent ++} ++ ++\def\dodefunx#1{% ++ % First, check whether we are in the right environment: ++ \checkenv#1% ++ % ++ % As above, allow line break if we have multiple x headers in a row. ++ % It's not a great place, though. ++ \ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi ++ % ++ % And now, it's time to reuse the body of the original defun: ++ \expandafter\gobbledefun#1% ++} ++\def\gobbledefun#1\startdefun{} ++ ++% \printdefunline \deffnheader{text} ++% ++\def\printdefunline#1#2{% ++ \begingroup ++ % call \deffnheader: ++ #1#2 \endheader ++ % common ending: ++ \interlinepenalty = 10000 ++ \advance\rightskip by 0pt plus 1fil ++ \endgraf ++ \nobreak\vskip -\parskip ++ \penalty\defunpenalty % signal to \startdefun and \dodefunx ++ % Some of the @defun-type tags do not enable magic parentheses, ++ % rendering the following check redundant. But we don't optimize. ++ \checkparencounts ++ \endgroup ++} ++ ++\def\Edefun{\endgraf\medbreak} ++ ++% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn; ++% the only thing remainnig is to define \deffnheader. ++% ++\def\makedefun#1{% ++ \expandafter\let\csname E#1\endcsname = \Edefun ++ \edef\temp{\noexpand\domakedefun ++ \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}% ++ \temp ++} ++ ++% \domakedefun \deffn \deffnx \deffnheader ++% ++% Define \deffn and \deffnx, without parameters. ++% \deffnheader has to be defined explicitly. ++% ++\def\domakedefun#1#2#3{% ++ \envdef#1{% ++ \startdefun ++ \parseargusing\activeparens{\printdefunline#3}% ++ }% ++ \def#2{\dodefunx#1}% ++ \def#3% ++} ++ ++%%% Untyped functions: ++ ++% @deffn category name args ++\makedefun{deffn}{\deffngeneral{}} ++ ++% @deffn category class name args ++\makedefun{defop}#1 {\defopon{#1\ \putwordon}} ++ ++% \defopon {category on}class name args ++\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } ++ ++% \deffngeneral {subind}category name args ++% ++\def\deffngeneral#1#2 #3 #4\endheader{% ++ % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}. ++ \dosubind{fn}{\code{#3}}{#1}% ++ \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% ++} ++ ++%%% Typed functions: ++ ++% @deftypefn category type name args ++\makedefun{deftypefn}{\deftypefngeneral{}} ++ ++% @deftypeop category class type name args ++\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}} ++ ++% \deftypeopon {category on}class type name args ++\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } ++ ++% \deftypefngeneral {subind}category type name args ++% ++\def\deftypefngeneral#1#2 #3 #4 #5\endheader{% ++ \dosubind{fn}{\code{#4}}{#1}% ++ \defname{#2}{#3}{#4}\defunargs{#5\unskip}% ++} ++ ++%%% Typed variables: ++ ++% @deftypevr category type var args ++\makedefun{deftypevr}{\deftypecvgeneral{}} ++ ++% @deftypecv category class type var args ++\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}} ++ ++% \deftypecvof {category of}class type var args ++\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} } ++ ++% \deftypecvgeneral {subind}category type var args ++% ++\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{% ++ \dosubind{vr}{\code{#4}}{#1}% ++ \defname{#2}{#3}{#4}\defunargs{#5\unskip}% ++} ++ ++%%% Untyped variables: ++ ++% @defvr category var args ++\makedefun{defvr}#1 {\deftypevrheader{#1} {} } ++ ++% @defcv category class var args ++\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}} ++ ++% \defcvof {category of}class var args ++\def\defcvof#1#2 {\deftypecvof{#1}#2 {} } ++ ++%%% Type: ++% @deftp category name args ++\makedefun{deftp}#1 #2 #3\endheader{% ++ \doind{tp}{\code{#2}}% ++ \defname{#1}{}{#2}\defunargs{#3\unskip}% ++} ++ ++% Remaining @defun-like shortcuts: ++\makedefun{defun}{\deffnheader{\putwordDeffunc} } ++\makedefun{defmac}{\deffnheader{\putwordDefmac} } ++\makedefun{defspec}{\deffnheader{\putwordDefspec} } ++\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} } ++\makedefun{defvar}{\defvrheader{\putwordDefvar} } ++\makedefun{defopt}{\defvrheader{\putwordDefopt} } ++\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} } ++\makedefun{defmethod}{\defopon\putwordMethodon} ++\makedefun{deftypemethod}{\deftypeopon\putwordMethodon} ++\makedefun{defivar}{\defcvof\putwordInstanceVariableof} ++\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof} ++ ++% \defname, which formats the name of the @def (not the args). ++% #1 is the category, such as "Function". ++% #2 is the return type, if any. ++% #3 is the function name. ++% ++% We are followed by (but not passed) the arguments, if any. ++% ++\def\defname#1#2#3{% ++ % Get the values of \leftskip and \rightskip as they were outside the @def... ++ \advance\leftskip by -\defbodyindent ++ % ++ % How we'll format the type name. Putting it in brackets helps ++ % distinguish it from the body text that may end up on the next line ++ % just below it. ++ \def\temp{#1}% ++ \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi} ++ % ++ % Figure out line sizes for the paragraph shape. ++ % The first line needs space for \box0; but if \rightskip is nonzero, ++ % we need only space for the part of \box0 which exceeds it: ++ \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip ++ % The continuations: ++ \dimen2=\hsize \advance\dimen2 by -\defargsindent ++ % (plain.tex says that \dimen1 should be used only as global.) ++ \parshape 2 0in \dimen0 \defargsindent \dimen2 ++ % ++ % Put the type name to the right margin. ++ \noindent ++ \hbox to 0pt{% ++ \hfil\box0 \kern-\hsize ++ % \hsize has to be shortened this way: ++ \kern\leftskip ++ % Intentionally do not respect \rightskip, since we need the space. ++ }% ++ % ++ % Allow all lines to be underfull without complaint: ++ \tolerance=10000 \hbadness=10000 ++ \exdentamount=\defbodyindent ++ {% ++ % defun fonts. We use typewriter by default (used to be bold) because: ++ % . we're printing identifiers, they should be in tt in principle. ++ % . in languages with many accents, such as Czech or French, it's ++ % common to leave accents off identifiers. The result looks ok in ++ % tt, but exceedingly strange in rm. ++ % . we don't want -- and --- to be treated as ligatures. ++ % . this still does not fix the ?` and !` ligatures, but so far no ++ % one has made identifiers using them :). ++ \df \tt ++ \def\temp{#2}% return value type ++ \ifx\temp\empty\else \tclose{\temp} \fi ++ #3% output function name ++ }% ++ {\rm\enskip}% hskip 0.5 em of \tenrm ++ % ++ \boldbrax ++ % arguments will be output next, if any. ++} ++ ++% Print arguments in slanted roman (not ttsl), inconsistently with using ++% tt for the name. This is because literal text is sometimes needed in ++% the argument list (groff manual), and ttsl and tt are not very ++% distinguishable. Prevent hyphenation at `-' chars. ++% ++\def\defunargs#1{% ++ % use sl by default (not ttsl), ++ % tt for the names. ++ \df \sl \hyphenchar\font=0 ++ % ++ % On the other hand, if an argument has two dashes (for instance), we ++ % want a way to get ttsl. Let's try @var for that. ++ \let\var=\ttslanted ++ #1% ++ \sl\hyphenchar\font=45 ++} ++ ++% We want ()&[] to print specially on the defun line. ++% ++\def\activeparens{% ++ \catcode`\(=\active \catcode`\)=\active ++ \catcode`\[=\active \catcode`\]=\active ++ \catcode`\&=\active ++} ++ ++% Make control sequences which act like normal parenthesis chars. ++\let\lparen = ( \let\rparen = ) ++ ++% Be sure that we always have a definition for `(', etc. For example, ++% if the fn name has parens in it, \boldbrax will not be in effect yet, ++% so TeX would otherwise complain about undefined control sequence. ++{ ++ \activeparens ++ \global\let(=\lparen \global\let)=\rparen ++ \global\let[=\lbrack \global\let]=\rbrack ++ \global\let& = \& ++ ++ \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} ++ \gdef\magicamp{\let&=\amprm} ++} ++ ++\newcount\parencount ++ ++% If we encounter &foo, then turn on ()-hacking afterwards ++\newif\ifampseen ++\def\amprm#1 {\ampseentrue{\bf\ }} ++ ++\def\parenfont{% ++ \ifampseen ++ % At the first level, print parens in roman, ++ % otherwise use the default font. ++ \ifnum \parencount=1 \rm \fi ++ \else ++ % The \sf parens (in \boldbrax) actually are a little bolder than ++ % the contained text. This is especially needed for [ and ] . ++ \sf ++ \fi ++} ++\def\infirstlevel#1{% ++ \ifampseen ++ \ifnum\parencount=1 ++ #1% ++ \fi ++ \fi ++} ++\def\bfafterword#1 {#1 \bf} ++ ++\def\opnr{% ++ \global\advance\parencount by 1 ++ {\parenfont(}% ++ \infirstlevel \bfafterword ++} ++\def\clnr{% ++ {\parenfont)}% ++ \infirstlevel \sl ++ \global\advance\parencount by -1 ++} ++ ++\newcount\brackcount ++\def\lbrb{% ++ \global\advance\brackcount by 1 ++ {\bf[}% ++} ++\def\rbrb{% ++ {\bf]}% ++ \global\advance\brackcount by -1 ++} ++ ++\def\checkparencounts{% ++ \ifnum\parencount=0 \else \badparencount \fi ++ \ifnum\brackcount=0 \else \badbrackcount \fi ++} ++\def\badparencount{% ++ \errmessage{Unbalanced parentheses in @def}% ++ \global\parencount=0 ++} ++\def\badbrackcount{% ++ \errmessage{Unbalanced square braces in @def}% ++ \global\brackcount=0 ++} ++ ++ ++\message{macros,} ++% @macro. ++ ++% To do this right we need a feature of e-TeX, \scantokens, ++% which we arrange to emulate with a temporary file in ordinary TeX. ++\ifx\eTeXversion\undefined ++ \newwrite\macscribble ++ \def\scantokens#1{% ++ \toks0={#1}% ++ \immediate\openout\macscribble=\jobname.tmp ++ \immediate\write\macscribble{\the\toks0}% ++ \immediate\closeout\macscribble ++ \input \jobname.tmp ++ } ++\fi ++ ++\def\scanmacro#1{% ++ \begingroup ++ \newlinechar`\^^M ++ \let\xeatspaces\eatspaces ++ % Undo catcode changes of \startcontents and \doprintindex ++ % When called from @insertcopying or (short)caption, we need active ++ % backslash to get it printed correctly. Previously, we had ++ % \catcode`\\=\other instead. We'll see whether a problem appears ++ % with macro expansion. --kasal, 19aug04 ++ \catcode`\@=0 \catcode`\\=\active \escapechar=`\@ ++ % ... and \example ++ \spaceisspace ++ % ++ % Append \endinput to make sure that TeX does not see the ending newline. ++ % I've verified that it is necessary both for e-TeX and for ordinary TeX ++ % --kasal, 29nov03 ++ \scantokens{#1\endinput}% ++ \endgroup ++} ++ ++\def\scanexp#1{% ++ \edef\temp{\noexpand\scanmacro{#1}}% ++ \temp ++} ++ ++\newcount\paramno % Count of parameters ++\newtoks\macname % Macro name ++\newif\ifrecursive % Is it recursive? ++ ++% List of all defined macros in the form ++% \definedummyword\macro1\definedummyword\macro2... ++% Currently is also contains all @aliases; the list can be split ++% if there is a need. ++\def\macrolist{} ++ ++% Add the macro to \macrolist ++\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname} ++\def\addtomacrolistxxx#1{% ++ \toks0 = \expandafter{\macrolist\definedummyword#1}% ++ \xdef\macrolist{\the\toks0}% ++} ++ ++% Utility routines. ++% This does \let #1 = #2, with \csnames; that is, ++% \let \csname#1\endcsname = \csname#2\endcsname ++% (except of course we have to play expansion games). ++% ++\def\cslet#1#2{% ++ \expandafter\let ++ \csname#1\expandafter\endcsname ++ \csname#2\endcsname ++} ++ ++% Trim leading and trailing spaces off a string. ++% Concepts from aro-bend problem 15 (see CTAN). ++{\catcode`\@=11 ++\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }} ++\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@} ++\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @} ++\def\unbrace#1{#1} ++\unbrace{\gdef\trim@@@ #1 } #2@{#1} ++} ++ ++% Trim a single trailing ^^M off a string. ++{\catcode`\^^M=\other \catcode`\Q=3% ++\gdef\eatcr #1{\eatcra #1Q^^MQ}% ++\gdef\eatcra#1^^MQ{\eatcrb#1Q}% ++\gdef\eatcrb#1Q#2Q{#1}% ++} ++ ++% Macro bodies are absorbed as an argument in a context where ++% all characters are catcode 10, 11 or 12, except \ which is active ++% (as in normal texinfo). It is necessary to change the definition of \. ++ ++% It's necessary to have hard CRs when the macro is executed. This is ++% done by making ^^M (\endlinechar) catcode 12 when reading the macro ++% body, and then making it the \newlinechar in \scanmacro. ++ ++\def\scanctxt{% ++ \catcode`\"=\other ++ \catcode`\+=\other ++ \catcode`\<=\other ++ \catcode`\>=\other ++ \catcode`\@=\other ++ \catcode`\^=\other ++ \catcode`\_=\other ++ \catcode`\|=\other ++ \catcode`\~=\other ++} ++ ++\def\scanargctxt{% ++ \scanctxt ++ \catcode`\\=\other ++ \catcode`\^^M=\other ++} ++ ++\def\macrobodyctxt{% ++ \scanctxt ++ \catcode`\{=\other ++ \catcode`\}=\other ++ \catcode`\^^M=\other ++ \usembodybackslash ++} ++ ++\def\macroargctxt{% ++ \scanctxt ++ \catcode`\\=\other ++} ++ ++% \mbodybackslash is the definition of \ in @macro bodies. ++% It maps \foo\ => \csname macarg.foo\endcsname => #N ++% where N is the macro parameter number. ++% We define \csname macarg.\endcsname to be \realbackslash, so ++% \\ in macro replacement text gets you a backslash. ++ ++{\catcode`@=0 @catcode`@\=@active ++ @gdef@usembodybackslash{@let\=@mbodybackslash} ++ @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname} ++} ++\expandafter\def\csname macarg.\endcsname{\realbackslash} ++ ++\def\macro{\recursivefalse\parsearg\macroxxx} ++\def\rmacro{\recursivetrue\parsearg\macroxxx} ++ ++\def\macroxxx#1{% ++ \getargs{#1}% now \macname is the macname and \argl the arglist ++ \ifx\argl\empty % no arguments ++ \paramno=0% ++ \else ++ \expandafter\parsemargdef \argl;% ++ \fi ++ \if1\csname ismacro.\the\macname\endcsname ++ \message{Warning: redefining \the\macname}% ++ \else ++ \expandafter\ifx\csname \the\macname\endcsname \relax ++ \else \errmessage{Macro name \the\macname\space already defined}\fi ++ \global\cslet{macsave.\the\macname}{\the\macname}% ++ \global\expandafter\let\csname ismacro.\the\macname\endcsname=1% ++ \addtomacrolist{\the\macname}% ++ \fi ++ \begingroup \macrobodyctxt ++ \ifrecursive \expandafter\parsermacbody ++ \else \expandafter\parsemacbody ++ \fi} ++ ++\parseargdef\unmacro{% ++ \if1\csname ismacro.#1\endcsname ++ \global\cslet{#1}{macsave.#1}% ++ \global\expandafter\let \csname ismacro.#1\endcsname=0% ++ % Remove the macro name from \macrolist: ++ \begingroup ++ \expandafter\let\csname#1\endcsname \relax ++ \let\definedummyword\unmacrodo ++ \xdef\macrolist{\macrolist}% ++ \endgroup ++ \else ++ \errmessage{Macro #1 not defined}% ++ \fi ++} ++ ++% Called by \do from \dounmacro on each macro. The idea is to omit any ++% macro definitions that have been changed to \relax. ++% ++\def\unmacrodo#1{% ++ \ifx #1\relax ++ % remove this ++ \else ++ \noexpand\definedummyword \noexpand#1% ++ \fi ++} ++ ++% This makes use of the obscure feature that if the last token of a ++% is #, then the preceding argument is delimited by ++% an opening brace, and that opening brace is not consumed. ++\def\getargs#1{\getargsxxx#1{}} ++\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs} ++\def\getmacname #1 #2\relax{\macname={#1}} ++\def\getmacargs#1{\def\argl{#1}} ++ ++% Parse the optional {params} list. Set up \paramno and \paramlist ++% so \defmacro knows what to do. Define \macarg.blah for each blah ++% in the params list, to be ##N where N is the position in that list. ++% That gets used by \mbodybackslash (above). ++ ++% We need to get `macro parameter char #' into several definitions. ++% The technique used is stolen from LaTeX: let \hash be something ++% unexpandable, insert that wherever you need a #, and then redefine ++% it to # just before using the token list produced. ++% ++% The same technique is used to protect \eatspaces till just before ++% the macro is used. ++ ++\def\parsemargdef#1;{\paramno=0\def\paramlist{}% ++ \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,} ++\def\parsemargdefxxx#1,{% ++ \if#1;\let\next=\relax ++ \else \let\next=\parsemargdefxxx ++ \advance\paramno by 1% ++ \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname ++ {\xeatspaces{\hash\the\paramno}}% ++ \edef\paramlist{\paramlist\hash\the\paramno,}% ++ \fi\next} ++ ++% These two commands read recursive and nonrecursive macro bodies. ++% (They're different since rec and nonrec macros end differently.) ++ ++\long\def\parsemacbody#1@end macro% ++{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% ++\long\def\parsermacbody#1@end rmacro% ++{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% ++ ++% This defines the macro itself. There are six cases: recursive and ++% nonrecursive macros of zero, one, and many arguments. ++% Much magic with \expandafter here. ++% \xdef is used so that macro definitions will survive the file ++% they're defined in; @include reads the file inside a group. ++\def\defmacro{% ++ \let\hash=##% convert placeholders to macro parameter chars ++ \ifrecursive ++ \ifcase\paramno ++ % 0 ++ \expandafter\xdef\csname\the\macname\endcsname{% ++ \noexpand\scanmacro{\temp}}% ++ \or % 1 ++ \expandafter\xdef\csname\the\macname\endcsname{% ++ \bgroup\noexpand\macroargctxt ++ \noexpand\braceorline ++ \expandafter\noexpand\csname\the\macname xxx\endcsname}% ++ \expandafter\xdef\csname\the\macname xxx\endcsname##1{% ++ \egroup\noexpand\scanmacro{\temp}}% ++ \else % many ++ \expandafter\xdef\csname\the\macname\endcsname{% ++ \bgroup\noexpand\macroargctxt ++ \noexpand\csname\the\macname xx\endcsname}% ++ \expandafter\xdef\csname\the\macname xx\endcsname##1{% ++ \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% ++ \expandafter\expandafter ++ \expandafter\xdef ++ \expandafter\expandafter ++ \csname\the\macname xxx\endcsname ++ \paramlist{\egroup\noexpand\scanmacro{\temp}}% ++ \fi ++ \else ++ \ifcase\paramno ++ % 0 ++ \expandafter\xdef\csname\the\macname\endcsname{% ++ \noexpand\norecurse{\the\macname}% ++ \noexpand\scanmacro{\temp}\egroup}% ++ \or % 1 ++ \expandafter\xdef\csname\the\macname\endcsname{% ++ \bgroup\noexpand\macroargctxt ++ \noexpand\braceorline ++ \expandafter\noexpand\csname\the\macname xxx\endcsname}% ++ \expandafter\xdef\csname\the\macname xxx\endcsname##1{% ++ \egroup ++ \noexpand\norecurse{\the\macname}% ++ \noexpand\scanmacro{\temp}\egroup}% ++ \else % many ++ \expandafter\xdef\csname\the\macname\endcsname{% ++ \bgroup\noexpand\macroargctxt ++ \expandafter\noexpand\csname\the\macname xx\endcsname}% ++ \expandafter\xdef\csname\the\macname xx\endcsname##1{% ++ \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% ++ \expandafter\expandafter ++ \expandafter\xdef ++ \expandafter\expandafter ++ \csname\the\macname xxx\endcsname ++ \paramlist{% ++ \egroup ++ \noexpand\norecurse{\the\macname}% ++ \noexpand\scanmacro{\temp}\egroup}% ++ \fi ++ \fi} ++ ++\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}} ++ ++% \braceorline decides whether the next nonwhitespace character is a ++% {. If so it reads up to the closing }, if not, it reads the whole ++% line. Whatever was read is then fed to the next control sequence ++% as an argument (by \parsebrace or \parsearg) ++\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx} ++\def\braceorlinexxx{% ++ \ifx\nchar\bgroup\else ++ \expandafter\parsearg ++ \fi \macnamexxx} ++ ++ ++% @alias. ++% We need some trickery to remove the optional spaces around the equal ++% sign. Just make them active and then expand them all to nothing. ++\def\alias{\parseargusing\obeyspaces\aliasxxx} ++\def\aliasxxx #1{\aliasyyy#1\relax} ++\def\aliasyyy #1=#2\relax{% ++ {% ++ \expandafter\let\obeyedspace=\empty ++ \addtomacrolist{#1}% ++ \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}% ++ }% ++ \next ++} ++ ++ ++\message{cross references,} ++ ++\newwrite\auxfile ++\newif\ifhavexrefs % True if xref values are known. ++\newif\ifwarnedxrefs % True if we warned once that they aren't known. ++ ++% @inforef is relatively simple. ++\def\inforef #1{\inforefzzz #1,,,,**} ++\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, ++ node \samp{\ignorespaces#1{}}} ++ ++% @node's only job in TeX is to define \lastnode, which is used in ++% cross-references. The @node line might or might not have commas, and ++% might or might not have spaces before the first comma, like: ++% @node foo , bar , ... ++% We don't want such trailing spaces in the node name. ++% ++\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse} ++% ++% also remove a trailing comma, in case of something like this: ++% @node Help-Cross, , , Cross-refs ++\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse} ++\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}} ++ ++\let\nwnode=\node ++\let\lastnode=\empty ++ ++% Write a cross-reference definition for the current node. #1 is the ++% type (Ynumbered, Yappendix, Ynothing). ++% ++\def\donoderef#1{% ++ \ifx\lastnode\empty\else ++ \setref{\lastnode}{#1}% ++ \global\let\lastnode=\empty ++ \fi ++} ++ ++% @anchor{NAME} -- define xref target at arbitrary point. ++% ++\newcount\savesfregister ++% ++\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi} ++\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} ++\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} ++ ++% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an ++% anchor), which consists of three parts: ++% 1) NAME-title - the current sectioning name taken from \thissection, ++% or the anchor name. ++% 2) NAME-snt - section number and type, passed as the SNT arg, or ++% empty for anchors. ++% 3) NAME-pg - the page number. ++% ++% This is called from \donoderef, \anchor, and \dofloat. In the case of ++% floats, there is an additional part, which is not written here: ++% 4) NAME-lof - the text as it should appear in a @listoffloats. ++% ++\def\setref#1#2{% ++ \pdfmkdest{#1}% ++ \iflinks ++ {% ++ \atdummies % preserve commands, but don't expand them ++ \edef\writexrdef##1##2{% ++ \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef ++ ##1}{##2}}% these are parameters of \writexrdef ++ }% ++ \toks0 = \expandafter{\thissection}% ++ \immediate \writexrdef{title}{\the\toks0 }% ++ \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. ++ \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, during \shipout ++ }% ++ \fi ++} ++ ++% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is ++% the node name, #2 the name of the Info cross-reference, #3 the printed ++% node name, #4 the name of the Info file, #5 the name of the printed ++% manual. All but the node name can be omitted. ++% ++\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} ++\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} ++\def\ref#1{\xrefX[#1,,,,,,,]} ++\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup ++ \unsepspaces ++ \def\printedmanual{\ignorespaces #5}% ++ \def\printedrefname{\ignorespaces #3}% ++ \setbox1=\hbox{\printedmanual\unskip}% ++ \setbox0=\hbox{\printedrefname\unskip}% ++ \ifdim \wd0 = 0pt ++ % No printed node name was explicitly given. ++ \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax ++ % Use the node name inside the square brackets. ++ \def\printedrefname{\ignorespaces #1}% ++ \else ++ % Use the actual chapter/section title appear inside ++ % the square brackets. Use the real section title if we have it. ++ \ifdim \wd1 > 0pt ++ % It is in another manual, so we don't have it. ++ \def\printedrefname{\ignorespaces #1}% ++ \else ++ \ifhavexrefs ++ % We know the real title if we have the xref values. ++ \def\printedrefname{\refx{#1-title}{}}% ++ \else ++ % Otherwise just copy the Info node name. ++ \def\printedrefname{\ignorespaces #1}% ++ \fi% ++ \fi ++ \fi ++ \fi ++ % ++ % Make link in pdf output. ++ \ifpdf ++ \leavevmode ++ \getfilename{#4}% ++ {\indexnofonts ++ \turnoffactive ++ % See comments at \activebackslashdouble. ++ {\activebackslashdouble \xdef\pdfxrefdest{#1}% ++ \backslashparens\pdfxrefdest}% ++ % ++ \ifnum\filenamelength>0 ++ \startlink attr{/Border [0 0 0]}% ++ goto file{\the\filename.pdf} name{\pdfxrefdest}% ++ \else ++ \startlink attr{/Border [0 0 0]}% ++ goto name{\pdfmkpgn{\pdfxrefdest}}% ++ \fi ++ }% ++ \linkcolor ++ \fi ++ % ++ % Float references are printed completely differently: "Figure 1.2" ++ % instead of "[somenode], p.3". We distinguish them by the ++ % LABEL-title being set to a magic string. ++ {% ++ % Have to otherify everything special to allow the \csname to ++ % include an _ in the xref name, etc. ++ \indexnofonts ++ \turnoffactive ++ \expandafter\global\expandafter\let\expandafter\Xthisreftitle ++ \csname XR#1-title\endcsname ++ }% ++ \iffloat\Xthisreftitle ++ % If the user specified the print name (third arg) to the ref, ++ % print it instead of our usual "Figure 1.2". ++ \ifdim\wd0 = 0pt ++ \refx{#1-snt}{}% ++ \else ++ \printedrefname ++ \fi ++ % ++ % if the user also gave the printed manual name (fifth arg), append ++ % "in MANUALNAME". ++ \ifdim \wd1 > 0pt ++ \space \putwordin{} \cite{\printedmanual}% ++ \fi ++ \else ++ % node/anchor (non-float) references. ++ % ++ % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not ++ % insert empty discretionaries after hyphens, which means that it will ++ % not find a line break at a hyphen in a node names. Since some manuals ++ % are best written with fairly long node names, containing hyphens, this ++ % is a loss. Therefore, we give the text of the node name again, so it ++ % is as if TeX is seeing it for the first time. ++ \ifdim \wd1 > 0pt ++ \putwordsection{} ``\printedrefname'' \putwordin{} \cite{\printedmanual}% ++ \else ++ % _ (for example) has to be the character _ for the purposes of the ++ % control sequence corresponding to the node, but it has to expand ++ % into the usual \leavevmode...\vrule stuff for purposes of ++ % printing. So we \turnoffactive for the \refx-snt, back on for the ++ % printing, back off for the \refx-pg. ++ {\turnoffactive ++ % Only output a following space if the -snt ref is nonempty; for ++ % @unnumbered and @anchor, it won't be. ++ \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% ++ \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi ++ }% ++ % output the `[mynode]' via a macro so it can be overridden. ++ \xrefprintnodename\printedrefname ++ % ++ % But we always want a comma and a space: ++ ,\space ++ % ++ % output the `page 3'. ++ \turnoffactive \putwordpage\tie\refx{#1-pg}{}% ++ \fi ++ \fi ++ \endlink ++\endgroup} ++ ++% This macro is called from \xrefX for the `[nodename]' part of xref ++% output. It's a separate macro only so it can be changed more easily, ++% since square brackets don't work well in some documents. Particularly ++% one that Bob is working on :). ++% ++\def\xrefprintnodename#1{[#1]} ++ ++% Things referred to by \setref. ++% ++\def\Ynothing{} ++\def\Yomitfromtoc{} ++\def\Ynumbered{% ++ \ifnum\secno=0 ++ \putwordChapter@tie \the\chapno ++ \else \ifnum\subsecno=0 ++ \putwordSection@tie \the\chapno.\the\secno ++ \else \ifnum\subsubsecno=0 ++ \putwordSection@tie \the\chapno.\the\secno.\the\subsecno ++ \else ++ \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno ++ \fi\fi\fi ++} ++\def\Yappendix{% ++ \ifnum\secno=0 ++ \putwordAppendix@tie @char\the\appendixno{}% ++ \else \ifnum\subsecno=0 ++ \putwordSection@tie @char\the\appendixno.\the\secno ++ \else \ifnum\subsubsecno=0 ++ \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno ++ \else ++ \putwordSection@tie ++ @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno ++ \fi\fi\fi ++} ++ ++% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. ++% If its value is nonempty, SUFFIX is output afterward. ++% ++\def\refx#1#2{% ++ {% ++ \indexnofonts ++ \otherbackslash ++ \expandafter\global\expandafter\let\expandafter\thisrefX ++ \csname XR#1\endcsname ++ }% ++ \ifx\thisrefX\relax ++ % If not defined, say something at least. ++ \angleleft un\-de\-fined\angleright ++ \iflinks ++ \ifhavexrefs ++ \message{\linenumber Undefined cross reference `#1'.}% ++ \else ++ \ifwarnedxrefs\else ++ \global\warnedxrefstrue ++ \message{Cross reference values unknown; you must run TeX again.}% ++ \fi ++ \fi ++ \fi ++ \else ++ % It's defined, so just use it. ++ \thisrefX ++ \fi ++ #2% Output the suffix in any case. ++} ++ ++% This is the macro invoked by entries in the aux file. Usually it's ++% just a \def (we prepend XR to the control sequence name to avoid ++% collisions). But if this is a float type, we have more work to do. ++% ++\def\xrdef#1#2{% ++ {% The node name might contain 8-bit characters, which in our current ++ % implementation are changed to commands like @'e. Don't let these ++ % mess up the control sequence name. ++ \indexnofonts ++ \turnoffactive ++ \xdef\safexrefname{#1}% ++ }% ++ % ++ \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref ++ % ++ % Was that xref control sequence that we just defined for a float? ++ \expandafter\iffloat\csname XR\safexrefname\endcsname ++ % it was a float, and we have the (safe) float type in \iffloattype. ++ \expandafter\let\expandafter\floatlist ++ \csname floatlist\iffloattype\endcsname ++ % ++ % Is this the first time we've seen this float type? ++ \expandafter\ifx\floatlist\relax ++ \toks0 = {\do}% yes, so just \do ++ \else ++ % had it before, so preserve previous elements in list. ++ \toks0 = \expandafter{\floatlist\do}% ++ \fi ++ % ++ % Remember this xref in the control sequence \floatlistFLOATTYPE, ++ % for later use in \listoffloats. ++ \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0 ++ {\safexrefname}}% ++ \fi ++} ++ ++% Read the last existing aux file, if any. No error if none exists. ++% ++\def\tryauxfile{% ++ \openin 1 \jobname.aux ++ \ifeof 1 \else ++ \readdatafile{aux}% ++ \global\havexrefstrue ++ \fi ++ \closein 1 ++} ++ ++\def\setupdatafile{% ++ \catcode`\^^@=\other ++ \catcode`\^^A=\other ++ \catcode`\^^B=\other ++ \catcode`\^^C=\other ++ \catcode`\^^D=\other ++ \catcode`\^^E=\other ++ \catcode`\^^F=\other ++ \catcode`\^^G=\other ++ \catcode`\^^H=\other ++ \catcode`\^^K=\other ++ \catcode`\^^L=\other ++ \catcode`\^^N=\other ++ \catcode`\^^P=\other ++ \catcode`\^^Q=\other ++ \catcode`\^^R=\other ++ \catcode`\^^S=\other ++ \catcode`\^^T=\other ++ \catcode`\^^U=\other ++ \catcode`\^^V=\other ++ \catcode`\^^W=\other ++ \catcode`\^^X=\other ++ \catcode`\^^Z=\other ++ \catcode`\^^[=\other ++ \catcode`\^^\=\other ++ \catcode`\^^]=\other ++ \catcode`\^^^=\other ++ \catcode`\^^_=\other ++ % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc. ++ % in xref tags, i.e., node names. But since ^^e4 notation isn't ++ % supported in the main text, it doesn't seem desirable. Furthermore, ++ % that is not enough: for node names that actually contain a ^ ++ % character, we would end up writing a line like this: 'xrdef {'hat ++ % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first ++ % argument, and \hat is not an expandable control sequence. It could ++ % all be worked out, but why? Either we support ^^ or we don't. ++ % ++ % The other change necessary for this was to define \auxhat: ++ % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter ++ % and then to call \auxhat in \setq. ++ % ++ \catcode`\^=\other ++ % ++ % Special characters. Should be turned off anyway, but... ++ \catcode`\~=\other ++ \catcode`\[=\other ++ \catcode`\]=\other ++ \catcode`\"=\other ++ \catcode`\_=\other ++ \catcode`\|=\other ++ \catcode`\<=\other ++ \catcode`\>=\other ++ \catcode`\$=\other ++ \catcode`\#=\other ++ \catcode`\&=\other ++ \catcode`\%=\other ++ \catcode`+=\other % avoid \+ for paranoia even though we've turned it off ++ % ++ % This is to support \ in node names and titles, since the \ ++ % characters end up in a \csname. It's easier than ++ % leaving it active and making its active definition an actual \ ++ % character. What I don't understand is why it works in the *value* ++ % of the xrdef. Seems like it should be a catcode12 \, and that ++ % should not typeset properly. But it works, so I'm moving on for ++ % now. --karl, 15jan04. ++ \catcode`\\=\other ++ % ++ % Make the characters 128-255 be printing characters. ++ {% ++ \count1=128 ++ \def\loop{% ++ \catcode\count1=\other ++ \advance\count1 by 1 ++ \ifnum \count1<256 \loop \fi ++ }% ++ }% ++ % ++ % @ is our escape character in .aux files, and we need braces. ++ \catcode`\{=1 ++ \catcode`\}=2 ++ \catcode`\@=0 ++} ++ ++\def\readdatafile#1{% ++\begingroup ++ \setupdatafile ++ \input\jobname.#1 ++\endgroup} ++ ++ ++\message{insertions,} ++% including footnotes. ++ ++\newcount \footnoteno ++ ++% The trailing space in the following definition for supereject is ++% vital for proper filling; pages come out unaligned when you do a ++% pagealignmacro call if that space before the closing brace is ++% removed. (Generally, numeric constants should always be followed by a ++% space to prevent strange expansion errors.) ++\def\supereject{\par\penalty -20000\footnoteno =0 } ++ ++% @footnotestyle is meaningful for info output only. ++\let\footnotestyle=\comment ++ ++{\catcode `\@=11 ++% ++% Auto-number footnotes. Otherwise like plain. ++\gdef\footnote{% ++ \let\indent=\ptexindent ++ \let\noindent=\ptexnoindent ++ \global\advance\footnoteno by \@ne ++ \edef\thisfootno{$^{\the\footnoteno}$}% ++ % ++ % In case the footnote comes at the end of a sentence, preserve the ++ % extra spacing after we do the footnote number. ++ \let\@sf\empty ++ \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi ++ % ++ % Remove inadvertent blank space before typesetting the footnote number. ++ \unskip ++ \thisfootno\@sf ++ \dofootnote ++}% ++ ++% Don't bother with the trickery in plain.tex to not require the ++% footnote text as a parameter. Our footnotes don't need to be so general. ++% ++% Oh yes, they do; otherwise, @ifset (and anything else that uses ++% \parseargline) fails inside footnotes because the tokens are fixed when ++% the footnote is read. --karl, 16nov96. ++% ++\gdef\dofootnote{% ++ \insert\footins\bgroup ++ % We want to typeset this text as a normal paragraph, even if the ++ % footnote reference occurs in (for example) a display environment. ++ % So reset some parameters. ++ \hsize=\pagewidth ++ \interlinepenalty\interfootnotelinepenalty ++ \splittopskip\ht\strutbox % top baseline for broken footnotes ++ \splitmaxdepth\dp\strutbox ++ \floatingpenalty\@MM ++ \leftskip\z@skip ++ \rightskip\z@skip ++ \spaceskip\z@skip ++ \xspaceskip\z@skip ++ \parindent\defaultparindent ++ % ++ \smallfonts \rm ++ % ++ % Because we use hanging indentation in footnotes, a @noindent appears ++ % to exdent this text, so make it be a no-op. makeinfo does not use ++ % hanging indentation so @noindent can still be needed within footnote ++ % text after an @example or the like (not that this is good style). ++ \let\noindent = \relax ++ % ++ % Hang the footnote text off the number. Use \everypar in case the ++ % footnote extends for more than one paragraph. ++ \everypar = {\hang}% ++ \textindent{\thisfootno}% ++ % ++ % Don't crash into the line above the footnote text. Since this ++ % expands into a box, it must come within the paragraph, lest it ++ % provide a place where TeX can split the footnote. ++ \footstrut ++ \futurelet\next\fo@t ++} ++}%end \catcode `\@=11 ++ ++% In case a @footnote appears in a vbox, save the footnote text and create ++% the real \insert just after the vbox finished. Otherwise, the insertion ++% would be lost. ++% Similarily, if a @footnote appears inside an alignment, save the footnote ++% text to a box and make the \insert when a row of the table is finished. ++% And the same can be done for other insert classes. --kasal, 16nov03. ++ ++% Replace the \insert primitive by a cheating macro. ++% Deeper inside, just make sure that the saved insertions are not spilled ++% out prematurely. ++% ++\def\startsavinginserts{% ++ \ifx \insert\ptexinsert ++ \let\insert\saveinsert ++ \else ++ \let\checkinserts\relax ++ \fi ++} ++ ++% This \insert replacement works for both \insert\footins{foo} and ++% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}. ++% ++\def\saveinsert#1{% ++ \edef\next{\noexpand\savetobox \makeSAVEname#1}% ++ \afterassignment\next ++ % swallow the left brace ++ \let\temp = ++} ++\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}} ++\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1} ++ ++\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi} ++ ++\def\placesaveins#1{% ++ \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname ++ {\box#1}% ++} ++ ++% eat @SAVE -- beware, all of them have catcode \other: ++{ ++ \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-) ++ \gdef\gobblesave @SAVE{} ++} ++ ++% initialization: ++\def\newsaveins #1{% ++ \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}% ++ \next ++} ++\def\newsaveinsX #1{% ++ \csname newbox\endcsname #1% ++ \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts ++ \checksaveins #1}% ++} ++ ++% initialize: ++\let\checkinserts\empty ++\newsaveins\footins ++\newsaveins\margin ++ ++ ++% @image. We use the macros from epsf.tex to support this. ++% If epsf.tex is not installed and @image is used, we complain. ++% ++% Check for and read epsf.tex up front. If we read it only at @image ++% time, we might be inside a group, and then its definitions would get ++% undone and the next image would fail. ++\openin 1 = epsf.tex ++\ifeof 1 \else ++ % Do not bother showing banner with epsf.tex v2.7k (available in ++ % doc/epsf.tex and on ctan). ++ \def\epsfannounce{\toks0 = }% ++ \input epsf.tex ++\fi ++\closein 1 ++% ++% We will only complain once about lack of epsf.tex. ++\newif\ifwarnednoepsf ++\newhelp\noepsfhelp{epsf.tex must be installed for images to ++ work. It is also included in the Texinfo distribution, or you can get ++ it from ftp://tug.org/tex/epsf.tex.} ++% ++\def\image#1{% ++ \ifx\epsfbox\undefined ++ \ifwarnednoepsf \else ++ \errhelp = \noepsfhelp ++ \errmessage{epsf.tex not found, images will be ignored}% ++ \global\warnednoepsftrue ++ \fi ++ \else ++ \imagexxx #1,,,,,\finish ++ \fi ++} ++% ++% Arguments to @image: ++% #1 is (mandatory) image filename; we tack on .eps extension. ++% #2 is (optional) width, #3 is (optional) height. ++% #4 is (ignored optional) html alt text. ++% #5 is (ignored optional) extension. ++% #6 is just the usual extra ignored arg for parsing this stuff. ++\newif\ifimagevmode ++\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup ++ \catcode`\^^M = 5 % in case we're inside an example ++ \normalturnoffactive % allow _ et al. in names ++ % If the image is by itself, center it. ++ \ifvmode ++ \imagevmodetrue ++ \nobreak\bigskip ++ % Usually we'll have text after the image which will insert ++ % \parskip glue, so insert it here too to equalize the space ++ % above and below. ++ \nobreak\vskip\parskip ++ \nobreak ++ \line\bgroup ++ \fi ++ % ++ % Output the image. ++ \ifpdf ++ \dopdfimage{#1}{#2}{#3}% ++ \else ++ % \epsfbox itself resets \epsf?size at each figure. ++ \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi ++ \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi ++ \epsfbox{#1.eps}% ++ \fi ++ % ++ \ifimagevmode \egroup \bigbreak \fi % space after the image ++\endgroup} ++ ++ ++% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables, ++% etc. We don't actually implement floating yet, we always include the ++% float "here". But it seemed the best name for the future. ++% ++\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish} ++ ++% There may be a space before second and/or third parameter; delete it. ++\def\eatcommaspace#1, {#1,} ++ ++% #1 is the optional FLOATTYPE, the text label for this float, typically ++% "Figure", "Table", "Example", etc. Can't contain commas. If omitted, ++% this float will not be numbered and cannot be referred to. ++% ++% #2 is the optional xref label. Also must be present for the float to ++% be referable. ++% ++% #3 is the optional positioning argument; for now, it is ignored. It ++% will somehow specify the positions allowed to float to (here, top, bottom). ++% ++% We keep a separate counter for each FLOATTYPE, which we reset at each ++% chapter-level command. ++\let\resetallfloatnos=\empty ++% ++\def\dofloat#1,#2,#3,#4\finish{% ++ \let\thiscaption=\empty ++ \let\thisshortcaption=\empty ++ % ++ % don't lose footnotes inside @float. ++ % ++ % BEWARE: when the floats start float, we have to issue warning whenever an ++ % insert appears inside a float which could possibly float. --kasal, 26may04 ++ % ++ \startsavinginserts ++ % ++ % We can't be used inside a paragraph. ++ \par ++ % ++ \vtop\bgroup ++ \def\floattype{#1}% ++ \def\floatlabel{#2}% ++ \def\floatloc{#3}% we do nothing with this yet. ++ % ++ \ifx\floattype\empty ++ \let\safefloattype=\empty ++ \else ++ {% ++ % the floattype might have accents or other special characters, ++ % but we need to use it in a control sequence name. ++ \indexnofonts ++ \turnoffactive ++ \xdef\safefloattype{\floattype}% ++ }% ++ \fi ++ % ++ % If label is given but no type, we handle that as the empty type. ++ \ifx\floatlabel\empty \else ++ % We want each FLOATTYPE to be numbered separately (Figure 1, ++ % Table 1, Figure 2, ...). (And if no label, no number.) ++ % ++ \expandafter\getfloatno\csname\safefloattype floatno\endcsname ++ \global\advance\floatno by 1 ++ % ++ {% ++ % This magic value for \thissection is output by \setref as the ++ % XREFLABEL-title value. \xrefX uses it to distinguish float ++ % labels (which have a completely different output format) from ++ % node and anchor labels. And \xrdef uses it to construct the ++ % lists of floats. ++ % ++ \edef\thissection{\floatmagic=\safefloattype}% ++ \setref{\floatlabel}{Yfloat}% ++ }% ++ \fi ++ % ++ % start with \parskip glue, I guess. ++ \vskip\parskip ++ % ++ % Don't suppress indentation if a float happens to start a section. ++ \restorefirstparagraphindent ++} ++ ++% we have these possibilities: ++% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap ++% @float Foo,lbl & no caption: Foo 1.1 ++% @float Foo & @caption{Cap}: Foo: Cap ++% @float Foo & no caption: Foo ++% @float ,lbl & Caption{Cap}: 1.1: Cap ++% @float ,lbl & no caption: 1.1 ++% @float & @caption{Cap}: Cap ++% @float & no caption: ++% ++\def\Efloat{% ++ \let\floatident = \empty ++ % ++ % In all cases, if we have a float type, it comes first. ++ \ifx\floattype\empty \else \def\floatident{\floattype}\fi ++ % ++ % If we have an xref label, the number comes next. ++ \ifx\floatlabel\empty \else ++ \ifx\floattype\empty \else % if also had float type, need tie first. ++ \appendtomacro\floatident{\tie}% ++ \fi ++ % the number. ++ \appendtomacro\floatident{\chaplevelprefix\the\floatno}% ++ \fi ++ % ++ % Start the printed caption with what we've constructed in ++ % \floatident, but keep it separate; we need \floatident again. ++ \let\captionline = \floatident ++ % ++ \ifx\thiscaption\empty \else ++ \ifx\floatident\empty \else ++ \appendtomacro\captionline{: }% had ident, so need a colon between ++ \fi ++ % ++ % caption text. ++ \appendtomacro\captionline{\scanexp\thiscaption}% ++ \fi ++ % ++ % If we have anything to print, print it, with space before. ++ % Eventually this needs to become an \insert. ++ \ifx\captionline\empty \else ++ \vskip.5\parskip ++ \captionline ++ % ++ % Space below caption. ++ \vskip\parskip ++ \fi ++ % ++ % If have an xref label, write the list of floats info. Do this ++ % after the caption, to avoid chance of it being a breakpoint. ++ \ifx\floatlabel\empty \else ++ % Write the text that goes in the lof to the aux file as ++ % \floatlabel-lof. Besides \floatident, we include the short ++ % caption if specified, else the full caption if specified, else nothing. ++ {% ++ \atdummies ++ % ++ % since we read the caption text in the macro world, where ^^M ++ % is turned into a normal character, we have to scan it back, so ++ % we don't write the literal three characters "^^M" into the aux file. ++ \scanexp{% ++ \xdef\noexpand\gtemp{% ++ \ifx\thisshortcaption\empty ++ \thiscaption ++ \else ++ \thisshortcaption ++ \fi ++ }% ++ }% ++ \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident ++ \ifx\gtemp\empty \else : \gtemp \fi}}% ++ }% ++ \fi ++ \egroup % end of \vtop ++ % ++ % place the captured inserts ++ % ++ % BEWARE: when the floats start floating, we have to issue warning ++ % whenever an insert appears inside a float which could possibly ++ % float. --kasal, 26may04 ++ % ++ \checkinserts ++} ++ ++% Append the tokens #2 to the definition of macro #1, not expanding either. ++% ++\def\appendtomacro#1#2{% ++ \expandafter\def\expandafter#1\expandafter{#1#2}% ++} ++ ++% @caption, @shortcaption ++% ++\def\caption{\docaption\thiscaption} ++\def\shortcaption{\docaption\thisshortcaption} ++\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption} ++\def\defcaption#1#2{\egroup \def#1{#2}} ++ ++% The parameter is the control sequence identifying the counter we are ++% going to use. Create it if it doesn't exist and assign it to \floatno. ++\def\getfloatno#1{% ++ \ifx#1\relax ++ % Haven't seen this figure type before. ++ \csname newcount\endcsname #1% ++ % ++ % Remember to reset this floatno at the next chap. ++ \expandafter\gdef\expandafter\resetallfloatnos ++ \expandafter{\resetallfloatnos #1=0 }% ++ \fi ++ \let\floatno#1% ++} ++ ++% \setref calls this to get the XREFLABEL-snt value. We want an @xref ++% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we ++% first read the @float command. ++% ++\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}% ++ ++% Magic string used for the XREFLABEL-title value, so \xrefX can ++% distinguish floats from other xref types. ++\def\floatmagic{!!float!!} ++ ++% #1 is the control sequence we are passed; we expand into a conditional ++% which is true if #1 represents a float ref. That is, the magic ++% \thissection value which we \setref above. ++% ++\def\iffloat#1{\expandafter\doiffloat#1==\finish} ++% ++% #1 is (maybe) the \floatmagic string. If so, #2 will be the ++% (safe) float type for this float. We set \iffloattype to #2. ++% ++\def\doiffloat#1=#2=#3\finish{% ++ \def\temp{#1}% ++ \def\iffloattype{#2}% ++ \ifx\temp\floatmagic ++} ++ ++% @listoffloats FLOATTYPE - print a list of floats like a table of contents. ++% ++\parseargdef\listoffloats{% ++ \def\floattype{#1}% floattype ++ {% ++ % the floattype might have accents or other special characters, ++ % but we need to use it in a control sequence name. ++ \indexnofonts ++ \turnoffactive ++ \xdef\safefloattype{\floattype}% ++ }% ++ % ++ % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE. ++ \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax ++ \ifhavexrefs ++ % if the user said @listoffloats foo but never @float foo. ++ \message{\linenumber No `\safefloattype' floats to list.}% ++ \fi ++ \else ++ \begingroup ++ \leftskip=\tocindent % indent these entries like a toc ++ \let\do=\listoffloatsdo ++ \csname floatlist\safefloattype\endcsname ++ \endgroup ++ \fi ++} ++ ++% This is called on each entry in a list of floats. We're passed the ++% xref label, in the form LABEL-title, which is how we save it in the ++% aux file. We strip off the -title and look up \XRLABEL-lof, which ++% has the text we're supposed to typeset here. ++% ++% Figures without xref labels will not be included in the list (since ++% they won't appear in the aux file). ++% ++\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish} ++\def\listoffloatsdoentry#1-title\finish{{% ++ % Can't fully expand XR#1-lof because it can contain anything. Just ++ % pass the control sequence. On the other hand, XR#1-pg is just the ++ % page number, and we want to fully expand that so we can get a link ++ % in pdf output. ++ \toksA = \expandafter{\csname XR#1-lof\endcsname}% ++ % ++ % use the same \entry macro we use to generate the TOC and index. ++ \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}% ++ \writeentry ++}} ++ ++ ++\message{localization,} ++ ++% @documentlanguage is usually given very early, just after ++% @setfilename. If done too late, it may not override everything ++% properly. Single argument is the language (de) or locale (de_DE) ++% abbreviation. It would be nice if we could set up a hyphenation file. ++% ++{ ++ \catcode`\_ = \active ++ \globaldefs=1 ++\parseargdef\documentlanguage{\begingroup ++ \let_=\normalunderscore % normal _ character for filenames ++ \tex % read txi-??.tex file in plain TeX. ++ % Read the file by the name they passed if it exists. ++ \openin 1 txi-#1.tex ++ \ifeof 1 ++ \documentlanguagetrywithoutunderscore{#1_\finish}% ++ \else ++ \input txi-#1.tex ++ \fi ++ \closein 1 ++ \endgroup ++\endgroup} ++} ++% ++% If they passed de_DE, and txi-de_DE.tex doesn't exist, ++% try txi-de.tex. ++% ++\def\documentlanguagetrywithoutunderscore#1_#2\finish{% ++ \openin 1 txi-#1.tex ++ \ifeof 1 ++ \errhelp = \nolanghelp ++ \errmessage{Cannot read language file txi-#1.tex}% ++ \else ++ \input txi-#1.tex ++ \fi ++ \closein 1 ++} ++% ++\newhelp\nolanghelp{The given language definition file cannot be found or ++is empty. Maybe you need to install it? In the current directory ++should work if nowhere else does.} ++ ++% Set the catcode of characters 128 through 255 to the specified number. ++% ++\def\setnonasciicharscatcode#1{% ++ \count255=128 ++ \loop\ifnum\count255<256 ++ \global\catcode\count255=#1 ++ \advance\count255 by 1 ++ \repeat ++} ++ ++% @documentencoding sets the definition of non-ASCII characters ++% according to the specified encoding. ++% ++\parseargdef\documentencoding{% ++ % Encoding being declared for the document. ++ \def\declaredencoding{\csname #1.enc\endcsname}% ++ % ++ % Supported encodings: names converted to tokens in order to be able ++ % to compare them with \ifx. ++ \def\ascii{\csname US-ASCII.enc\endcsname}% ++ \def\latnine{\csname ISO-8859-15.enc\endcsname}% ++ \def\latone{\csname ISO-8859-1.enc\endcsname}% ++ \def\lattwo{\csname ISO-8859-2.enc\endcsname}% ++ \def\utfeight{\csname UTF-8.enc\endcsname}% ++ % ++ \ifx \declaredencoding \ascii ++ \asciichardefs ++ % ++ \else \ifx \declaredencoding \lattwo ++ \setnonasciicharscatcode\active ++ \lattwochardefs ++ % ++ \else \ifx \declaredencoding \latone ++ \setnonasciicharscatcode\active ++ \latonechardefs ++ % ++ \else \ifx \declaredencoding \latnine ++ \setnonasciicharscatcode\active ++ \latninechardefs ++ % ++ \else \ifx \declaredencoding \utfeight ++ \setnonasciicharscatcode\active ++ \utfeightchardefs ++ % ++ \else ++ \message{Unknown document encoding #1, ignoring.}% ++ % ++ \fi % utfeight ++ \fi % latnine ++ \fi % latone ++ \fi % lattwo ++ \fi % ascii ++} ++ ++% A message to be logged when using a character that isn't available ++% the default font encoding (OT1). ++% ++\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}} ++ ++% Take account of \c (plain) vs. \, (Texinfo) difference. ++\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi} ++ ++% First, make active non-ASCII characters in order for them to be ++% correctly categorized when TeX reads the replacement text of ++% macros containing the character definitions. ++\setnonasciicharscatcode\active ++% ++% Latin1 (ISO-8859-1) character definitions. ++\def\latonechardefs{% ++ \gdef^^a0{~} ++ \gdef^^a1{\exclamdown} ++ \gdef^^a2{\missingcharmsg{CENT SIGN}} ++ \gdef^^a3{{\pounds}} ++ \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} ++ \gdef^^a5{\missingcharmsg{YEN SIGN}} ++ \gdef^^a6{\missingcharmsg{BROKEN BAR}} ++ \gdef^^a7{\S} ++ \gdef^^a8{\"{}} ++ \gdef^^a9{\copyright} ++ \gdef^^aa{\ordf} ++ \gdef^^ab{\missingcharmsg{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}} ++ \gdef^^ac{$\lnot$} ++ \gdef^^ad{\-} ++ \gdef^^ae{\registeredsymbol} ++ \gdef^^af{\={}} ++ % ++ \gdef^^b0{\textdegree} ++ \gdef^^b1{$\pm$} ++ \gdef^^b2{$^2$} ++ \gdef^^b3{$^3$} ++ \gdef^^b4{\'{}} ++ \gdef^^b5{$\mu$} ++ \gdef^^b6{\P} ++ % ++ \gdef^^b7{$^.$} ++ \gdef^^b8{\cedilla\ } ++ \gdef^^b9{$^1$} ++ \gdef^^ba{\ordm} ++ % ++ \gdef^^bb{\missingcharmsg{RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK}} ++ \gdef^^bc{$1\over4$} ++ \gdef^^bd{$1\over2$} ++ \gdef^^be{$3\over4$} ++ \gdef^^bf{\questiondown} ++ % ++ \gdef^^c0{\`A} ++ \gdef^^c1{\'A} ++ \gdef^^c2{\^A} ++ \gdef^^c3{\~A} ++ \gdef^^c4{\"A} ++ \gdef^^c5{\ringaccent A} ++ \gdef^^c6{\AE} ++ \gdef^^c7{\cedilla C} ++ \gdef^^c8{\`E} ++ \gdef^^c9{\'E} ++ \gdef^^ca{\^E} ++ \gdef^^cb{\"E} ++ \gdef^^cc{\`I} ++ \gdef^^cd{\'I} ++ \gdef^^ce{\^I} ++ \gdef^^cf{\"I} ++ % ++ \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER ETH}} ++ \gdef^^d1{\~N} ++ \gdef^^d2{\`O} ++ \gdef^^d3{\'O} ++ \gdef^^d4{\^O} ++ \gdef^^d5{\~O} ++ \gdef^^d6{\"O} ++ \gdef^^d7{$\times$} ++ \gdef^^d8{\O} ++ \gdef^^d9{\`U} ++ \gdef^^da{\'U} ++ \gdef^^db{\^U} ++ \gdef^^dc{\"U} ++ \gdef^^dd{\'Y} ++ \gdef^^de{\missingcharmsg{LATIN CAPITAL LETTER THORN}} ++ \gdef^^df{\ss} ++ % ++ \gdef^^e0{\`a} ++ \gdef^^e1{\'a} ++ \gdef^^e2{\^a} ++ \gdef^^e3{\~a} ++ \gdef^^e4{\"a} ++ \gdef^^e5{\ringaccent a} ++ \gdef^^e6{\ae} ++ \gdef^^e7{\cedilla c} ++ \gdef^^e8{\`e} ++ \gdef^^e9{\'e} ++ \gdef^^ea{\^e} ++ \gdef^^eb{\"e} ++ \gdef^^ec{\`{\dotless i}} ++ \gdef^^ed{\'{\dotless i}} ++ \gdef^^ee{\^{\dotless i}} ++ \gdef^^ef{\"{\dotless i}} ++ % ++ \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER ETH}} ++ \gdef^^f1{\~n} ++ \gdef^^f2{\`o} ++ \gdef^^f3{\'o} ++ \gdef^^f4{\^o} ++ \gdef^^f5{\~o} ++ \gdef^^f6{\"o} ++ \gdef^^f7{$\div$} ++ \gdef^^f8{\o} ++ \gdef^^f9{\`u} ++ \gdef^^fa{\'u} ++ \gdef^^fb{\^u} ++ \gdef^^fc{\"u} ++ \gdef^^fd{\'y} ++ \gdef^^fe{\missingcharmsg{LATIN SMALL LETTER THORN}} ++ \gdef^^ff{\"y} ++} ++ ++% Latin9 (ISO-8859-15) encoding character definitions. ++\def\latninechardefs{% ++ % Encoding is almost identical to Latin1. ++ \latonechardefs ++ % ++ \gdef^^a4{\euro} ++ \gdef^^a6{\v S} ++ \gdef^^a8{\v s} ++ \gdef^^b4{\v Z} ++ \gdef^^b8{\v z} ++ \gdef^^bc{\OE} ++ \gdef^^bd{\oe} ++ \gdef^^be{\"Y} ++} ++ ++% Latin2 (ISO-8859-2) character definitions. ++\def\lattwochardefs{% ++ \gdef^^a0{~} ++ \gdef^^a1{\missingcharmsg{LATIN CAPITAL LETTER A WITH OGONEK}} ++ \gdef^^a2{\u{}} ++ \gdef^^a3{\L} ++ \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} ++ \gdef^^a5{\v L} ++ \gdef^^a6{\'S} ++ \gdef^^a7{\S} ++ \gdef^^a8{\"{}} ++ \gdef^^a9{\v S} ++ \gdef^^aa{\cedilla S} ++ \gdef^^ab{\v T} ++ \gdef^^ac{\'Z} ++ \gdef^^ad{\-} ++ \gdef^^ae{\v Z} ++ \gdef^^af{\dotaccent Z} ++ % ++ \gdef^^b0{\textdegree} ++ \gdef^^b1{\missingcharmsg{LATIN SMALL LETTER A WITH OGONEK}} ++ \gdef^^b2{\missingcharmsg{OGONEK}} ++ \gdef^^b3{\l} ++ \gdef^^b4{\'{}} ++ \gdef^^b5{\v l} ++ \gdef^^b6{\'s} ++ \gdef^^b7{\v{}} ++ \gdef^^b8{\cedilla\ } ++ \gdef^^b9{\v s} ++ \gdef^^ba{\cedilla s} ++ \gdef^^bb{\v t} ++ \gdef^^bc{\'z} ++ \gdef^^bd{\H{}} ++ \gdef^^be{\v z} ++ \gdef^^bf{\dotaccent z} ++ % ++ \gdef^^c0{\'R} ++ \gdef^^c1{\'A} ++ \gdef^^c2{\^A} ++ \gdef^^c3{\u A} ++ \gdef^^c4{\"A} ++ \gdef^^c5{\'L} ++ \gdef^^c6{\'C} ++ \gdef^^c7{\cedilla C} ++ \gdef^^c8{\v C} ++ \gdef^^c9{\'E} ++ \gdef^^ca{\missingcharmsg{LATIN CAPITAL LETTER E WITH OGONEK}} ++ \gdef^^cb{\"E} ++ \gdef^^cc{\v E} ++ \gdef^^cd{\'I} ++ \gdef^^ce{\^I} ++ \gdef^^cf{\v D} ++ % ++ \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER D WITH STROKE}} ++ \gdef^^d1{\'N} ++ \gdef^^d2{\v N} ++ \gdef^^d3{\'O} ++ \gdef^^d4{\^O} ++ \gdef^^d5{\H O} ++ \gdef^^d6{\"O} ++ \gdef^^d7{$\times$} ++ \gdef^^d8{\v R} ++ \gdef^^d9{\ringaccent U} ++ \gdef^^da{\'U} ++ \gdef^^db{\H U} ++ \gdef^^dc{\"U} ++ \gdef^^dd{\'Y} ++ \gdef^^de{\cedilla T} ++ \gdef^^df{\ss} ++ % ++ \gdef^^e0{\'r} ++ \gdef^^e1{\'a} ++ \gdef^^e2{\^a} ++ \gdef^^e3{\u a} ++ \gdef^^e4{\"a} ++ \gdef^^e5{\'l} ++ \gdef^^e6{\'c} ++ \gdef^^e7{\cedilla c} ++ \gdef^^e8{\v c} ++ \gdef^^e9{\'e} ++ \gdef^^ea{\missingcharmsg{LATIN SMALL LETTER E WITH OGONEK}} ++ \gdef^^eb{\"e} ++ \gdef^^ec{\v e} ++ \gdef^^ed{\'\i} ++ \gdef^^ee{\^\i} ++ \gdef^^ef{\v d} ++ % ++ \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER D WITH STROKE}} ++ \gdef^^f1{\'n} ++ \gdef^^f2{\v n} ++ \gdef^^f3{\'o} ++ \gdef^^f4{\^o} ++ \gdef^^f5{\H o} ++ \gdef^^f6{\"o} ++ \gdef^^f7{$\div$} ++ \gdef^^f8{\v r} ++ \gdef^^f9{\ringaccent u} ++ \gdef^^fa{\'u} ++ \gdef^^fb{\H u} ++ \gdef^^fc{\"u} ++ \gdef^^fd{\'y} ++ \gdef^^fe{\cedilla t} ++ \gdef^^ff{\dotaccent{}} ++} ++ ++% UTF-8 character definitions. ++% ++% This code to support UTF-8 is based on LaTeX's utf8.def, with some ++% changes for Texinfo conventions. It is included here under the GPL by ++% permission from Frank Mittelbach and the LaTeX team. ++% ++\newcount\countUTFx ++\newcount\countUTFy ++\newcount\countUTFz ++ ++\gdef\UTFviiiTwoOctets#1#2{\expandafter ++ \UTFviiiDefined\csname u8:#1\string #2\endcsname} ++% ++\gdef\UTFviiiThreeOctets#1#2#3{\expandafter ++ \UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname} ++% ++\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter ++ \UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname} ++ ++\gdef\UTFviiiDefined#1{% ++ \ifx #1\relax ++ \message{\linenumber Unicode char \string #1 not defined for Texinfo}% ++ \else ++ \expandafter #1% ++ \fi ++} ++ ++\begingroup ++ \catcode`\~13 ++ \catcode`\"12 ++ ++ \def\UTFviiiLoop{% ++ \global\catcode\countUTFx\active ++ \uccode`\~\countUTFx ++ \uppercase\expandafter{\UTFviiiTmp}% ++ \advance\countUTFx by 1 ++ \ifnum\countUTFx < \countUTFy ++ \expandafter\UTFviiiLoop ++ \fi} ++ ++ \countUTFx = "C2 ++ \countUTFy = "E0 ++ \def\UTFviiiTmp{% ++ \xdef~{\noexpand\UTFviiiTwoOctets\string~}} ++ \UTFviiiLoop ++ ++ \countUTFx = "E0 ++ \countUTFy = "F0 ++ \def\UTFviiiTmp{% ++ \xdef~{\noexpand\UTFviiiThreeOctets\string~}} ++ \UTFviiiLoop ++ ++ \countUTFx = "F0 ++ \countUTFy = "F4 ++ \def\UTFviiiTmp{% ++ \xdef~{\noexpand\UTFviiiFourOctets\string~}} ++ \UTFviiiLoop ++\endgroup ++ ++\begingroup ++ \catcode`\"=12 ++ \catcode`\<=12 ++ \catcode`\.=12 ++ \catcode`\,=12 ++ \catcode`\;=12 ++ \catcode`\!=12 ++ \catcode`\~=13 ++ ++ \gdef\DeclareUnicodeCharacter#1#2{% ++ \countUTFz = "#1\relax ++ \wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}% ++ \begingroup ++ \parseXMLCharref ++ \def\UTFviiiTwoOctets##1##2{% ++ \csname u8:##1\string ##2\endcsname}% ++ \def\UTFviiiThreeOctets##1##2##3{% ++ \csname u8:##1\string ##2\string ##3\endcsname}% ++ \def\UTFviiiFourOctets##1##2##3##4{% ++ \csname u8:##1\string ##2\string ##3\string ##4\endcsname}% ++ \expandafter\expandafter\expandafter\expandafter ++ \expandafter\expandafter\expandafter ++ \gdef\UTFviiiTmp{#2}% ++ \endgroup} ++ ++ \gdef\parseXMLCharref{% ++ \ifnum\countUTFz < "A0\relax ++ \errhelp = \EMsimple ++ \errmessage{Cannot define Unicode char value < 00A0}% ++ \else\ifnum\countUTFz < "800\relax ++ \parseUTFviiiA,% ++ \parseUTFviiiB C\UTFviiiTwoOctets.,% ++ \else\ifnum\countUTFz < "10000\relax ++ \parseUTFviiiA;% ++ \parseUTFviiiA,% ++ \parseUTFviiiB E\UTFviiiThreeOctets.{,;}% ++ \else ++ \parseUTFviiiA;% ++ \parseUTFviiiA,% ++ \parseUTFviiiA!% ++ \parseUTFviiiB F\UTFviiiFourOctets.{!,;}% ++ \fi\fi\fi ++ } ++ ++ \gdef\parseUTFviiiA#1{% ++ \countUTFx = \countUTFz ++ \divide\countUTFz by 64 ++ \countUTFy = \countUTFz ++ \multiply\countUTFz by 64 ++ \advance\countUTFx by -\countUTFz ++ \advance\countUTFx by 128 ++ \uccode `#1\countUTFx ++ \countUTFz = \countUTFy} ++ ++ \gdef\parseUTFviiiB#1#2#3#4{% ++ \advance\countUTFz by "#10\relax ++ \uccode `#3\countUTFz ++ \uppercase{\gdef\UTFviiiTmp{#2#3#4}}} ++\endgroup ++ ++\def\utfeightchardefs{% ++ \DeclareUnicodeCharacter{00A0}{\tie} ++ \DeclareUnicodeCharacter{00A1}{\exclamdown} ++ \DeclareUnicodeCharacter{00A3}{\pounds} ++ \DeclareUnicodeCharacter{00A8}{\"{ }} ++ \DeclareUnicodeCharacter{00A9}{\copyright} ++ \DeclareUnicodeCharacter{00AA}{\ordf} ++ \DeclareUnicodeCharacter{00AD}{\-} ++ \DeclareUnicodeCharacter{00AE}{\registeredsymbol} ++ \DeclareUnicodeCharacter{00AF}{\={ }} ++ ++ \DeclareUnicodeCharacter{00B0}{\ringaccent{ }} ++ \DeclareUnicodeCharacter{00B4}{\'{ }} ++ \DeclareUnicodeCharacter{00B8}{\cedilla{ }} ++ \DeclareUnicodeCharacter{00BA}{\ordm} ++ \DeclareUnicodeCharacter{00BF}{\questiondown} ++ ++ \DeclareUnicodeCharacter{00C0}{\`A} ++ \DeclareUnicodeCharacter{00C1}{\'A} ++ \DeclareUnicodeCharacter{00C2}{\^A} ++ \DeclareUnicodeCharacter{00C3}{\~A} ++ \DeclareUnicodeCharacter{00C4}{\"A} ++ \DeclareUnicodeCharacter{00C5}{\AA} ++ \DeclareUnicodeCharacter{00C6}{\AE} ++ \DeclareUnicodeCharacter{00C7}{\cedilla{C}} ++ \DeclareUnicodeCharacter{00C8}{\`E} ++ \DeclareUnicodeCharacter{00C9}{\'E} ++ \DeclareUnicodeCharacter{00CA}{\^E} ++ \DeclareUnicodeCharacter{00CB}{\"E} ++ \DeclareUnicodeCharacter{00CC}{\`I} ++ \DeclareUnicodeCharacter{00CD}{\'I} ++ \DeclareUnicodeCharacter{00CE}{\^I} ++ \DeclareUnicodeCharacter{00CF}{\"I} ++ ++ \DeclareUnicodeCharacter{00D1}{\~N} ++ \DeclareUnicodeCharacter{00D2}{\`O} ++ \DeclareUnicodeCharacter{00D3}{\'O} ++ \DeclareUnicodeCharacter{00D4}{\^O} ++ \DeclareUnicodeCharacter{00D5}{\~O} ++ \DeclareUnicodeCharacter{00D6}{\"O} ++ \DeclareUnicodeCharacter{00D8}{\O} ++ \DeclareUnicodeCharacter{00D9}{\`U} ++ \DeclareUnicodeCharacter{00DA}{\'U} ++ \DeclareUnicodeCharacter{00DB}{\^U} ++ \DeclareUnicodeCharacter{00DC}{\"U} ++ \DeclareUnicodeCharacter{00DD}{\'Y} ++ \DeclareUnicodeCharacter{00DF}{\ss} ++ ++ \DeclareUnicodeCharacter{00E0}{\`a} ++ \DeclareUnicodeCharacter{00E1}{\'a} ++ \DeclareUnicodeCharacter{00E2}{\^a} ++ \DeclareUnicodeCharacter{00E3}{\~a} ++ \DeclareUnicodeCharacter{00E4}{\"a} ++ \DeclareUnicodeCharacter{00E5}{\aa} ++ \DeclareUnicodeCharacter{00E6}{\ae} ++ \DeclareUnicodeCharacter{00E7}{\cedilla{c}} ++ \DeclareUnicodeCharacter{00E8}{\`e} ++ \DeclareUnicodeCharacter{00E9}{\'e} ++ \DeclareUnicodeCharacter{00EA}{\^e} ++ \DeclareUnicodeCharacter{00EB}{\"e} ++ \DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}} ++ \DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}} ++ \DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}} ++ \DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}} ++ ++ \DeclareUnicodeCharacter{00F1}{\~n} ++ \DeclareUnicodeCharacter{00F2}{\`o} ++ \DeclareUnicodeCharacter{00F3}{\'o} ++ \DeclareUnicodeCharacter{00F4}{\^o} ++ \DeclareUnicodeCharacter{00F5}{\~o} ++ \DeclareUnicodeCharacter{00F6}{\"o} ++ \DeclareUnicodeCharacter{00F8}{\o} ++ \DeclareUnicodeCharacter{00F9}{\`u} ++ \DeclareUnicodeCharacter{00FA}{\'u} ++ \DeclareUnicodeCharacter{00FB}{\^u} ++ \DeclareUnicodeCharacter{00FC}{\"u} ++ \DeclareUnicodeCharacter{00FD}{\'y} ++ \DeclareUnicodeCharacter{00FF}{\"y} ++ ++ \DeclareUnicodeCharacter{0100}{\=A} ++ \DeclareUnicodeCharacter{0101}{\=a} ++ \DeclareUnicodeCharacter{0102}{\u{A}} ++ \DeclareUnicodeCharacter{0103}{\u{a}} ++ \DeclareUnicodeCharacter{0106}{\'C} ++ \DeclareUnicodeCharacter{0107}{\'c} ++ \DeclareUnicodeCharacter{0108}{\^C} ++ \DeclareUnicodeCharacter{0109}{\^c} ++ \DeclareUnicodeCharacter{010A}{\dotaccent{C}} ++ \DeclareUnicodeCharacter{010B}{\dotaccent{c}} ++ \DeclareUnicodeCharacter{010C}{\v{C}} ++ \DeclareUnicodeCharacter{010D}{\v{c}} ++ \DeclareUnicodeCharacter{010E}{\v{D}} ++ ++ \DeclareUnicodeCharacter{0112}{\=E} ++ \DeclareUnicodeCharacter{0113}{\=e} ++ \DeclareUnicodeCharacter{0114}{\u{E}} ++ \DeclareUnicodeCharacter{0115}{\u{e}} ++ \DeclareUnicodeCharacter{0116}{\dotaccent{E}} ++ \DeclareUnicodeCharacter{0117}{\dotaccent{e}} ++ \DeclareUnicodeCharacter{011A}{\v{E}} ++ \DeclareUnicodeCharacter{011B}{\v{e}} ++ \DeclareUnicodeCharacter{011C}{\^G} ++ \DeclareUnicodeCharacter{011D}{\^g} ++ \DeclareUnicodeCharacter{011E}{\u{G}} ++ \DeclareUnicodeCharacter{011F}{\u{g}} ++ ++ \DeclareUnicodeCharacter{0120}{\dotaccent{G}} ++ \DeclareUnicodeCharacter{0121}{\dotaccent{g}} ++ \DeclareUnicodeCharacter{0124}{\^H} ++ \DeclareUnicodeCharacter{0125}{\^h} ++ \DeclareUnicodeCharacter{0128}{\~I} ++ \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}} ++ \DeclareUnicodeCharacter{012A}{\=I} ++ \DeclareUnicodeCharacter{012B}{\={\dotless{i}}} ++ \DeclareUnicodeCharacter{012C}{\u{I}} ++ \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}} ++ ++ \DeclareUnicodeCharacter{0130}{\dotaccent{I}} ++ \DeclareUnicodeCharacter{0131}{\dotless{i}} ++ \DeclareUnicodeCharacter{0132}{IJ} ++ \DeclareUnicodeCharacter{0133}{ij} ++ \DeclareUnicodeCharacter{0134}{\^J} ++ \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}} ++ \DeclareUnicodeCharacter{0139}{\'L} ++ \DeclareUnicodeCharacter{013A}{\'l} ++ ++ \DeclareUnicodeCharacter{0141}{\L} ++ \DeclareUnicodeCharacter{0142}{\l} ++ \DeclareUnicodeCharacter{0143}{\'N} ++ \DeclareUnicodeCharacter{0144}{\'n} ++ \DeclareUnicodeCharacter{0147}{\v{N}} ++ \DeclareUnicodeCharacter{0148}{\v{n}} ++ \DeclareUnicodeCharacter{014C}{\=O} ++ \DeclareUnicodeCharacter{014D}{\=o} ++ \DeclareUnicodeCharacter{014E}{\u{O}} ++ \DeclareUnicodeCharacter{014F}{\u{o}} ++ ++ \DeclareUnicodeCharacter{0150}{\H{O}} ++ \DeclareUnicodeCharacter{0151}{\H{o}} ++ \DeclareUnicodeCharacter{0152}{\OE} ++ \DeclareUnicodeCharacter{0153}{\oe} ++ \DeclareUnicodeCharacter{0154}{\'R} ++ \DeclareUnicodeCharacter{0155}{\'r} ++ \DeclareUnicodeCharacter{0158}{\v{R}} ++ \DeclareUnicodeCharacter{0159}{\v{r}} ++ \DeclareUnicodeCharacter{015A}{\'S} ++ \DeclareUnicodeCharacter{015B}{\'s} ++ \DeclareUnicodeCharacter{015C}{\^S} ++ \DeclareUnicodeCharacter{015D}{\^s} ++ \DeclareUnicodeCharacter{015E}{\cedilla{S}} ++ \DeclareUnicodeCharacter{015F}{\cedilla{s}} ++ ++ \DeclareUnicodeCharacter{0160}{\v{S}} ++ \DeclareUnicodeCharacter{0161}{\v{s}} ++ \DeclareUnicodeCharacter{0162}{\cedilla{t}} ++ \DeclareUnicodeCharacter{0163}{\cedilla{T}} ++ \DeclareUnicodeCharacter{0164}{\v{T}} ++ ++ \DeclareUnicodeCharacter{0168}{\~U} ++ \DeclareUnicodeCharacter{0169}{\~u} ++ \DeclareUnicodeCharacter{016A}{\=U} ++ \DeclareUnicodeCharacter{016B}{\=u} ++ \DeclareUnicodeCharacter{016C}{\u{U}} ++ \DeclareUnicodeCharacter{016D}{\u{u}} ++ \DeclareUnicodeCharacter{016E}{\ringaccent{U}} ++ \DeclareUnicodeCharacter{016F}{\ringaccent{u}} ++ ++ \DeclareUnicodeCharacter{0170}{\H{U}} ++ \DeclareUnicodeCharacter{0171}{\H{u}} ++ \DeclareUnicodeCharacter{0174}{\^W} ++ \DeclareUnicodeCharacter{0175}{\^w} ++ \DeclareUnicodeCharacter{0176}{\^Y} ++ \DeclareUnicodeCharacter{0177}{\^y} ++ \DeclareUnicodeCharacter{0178}{\"Y} ++ \DeclareUnicodeCharacter{0179}{\'Z} ++ \DeclareUnicodeCharacter{017A}{\'z} ++ \DeclareUnicodeCharacter{017B}{\dotaccent{Z}} ++ \DeclareUnicodeCharacter{017C}{\dotaccent{z}} ++ \DeclareUnicodeCharacter{017D}{\v{Z}} ++ \DeclareUnicodeCharacter{017E}{\v{z}} ++ ++ \DeclareUnicodeCharacter{01C4}{D\v{Z}} ++ \DeclareUnicodeCharacter{01C5}{D\v{z}} ++ \DeclareUnicodeCharacter{01C6}{d\v{z}} ++ \DeclareUnicodeCharacter{01C7}{LJ} ++ \DeclareUnicodeCharacter{01C8}{Lj} ++ \DeclareUnicodeCharacter{01C9}{lj} ++ \DeclareUnicodeCharacter{01CA}{NJ} ++ \DeclareUnicodeCharacter{01CB}{Nj} ++ \DeclareUnicodeCharacter{01CC}{nj} ++ \DeclareUnicodeCharacter{01CD}{\v{A}} ++ \DeclareUnicodeCharacter{01CE}{\v{a}} ++ \DeclareUnicodeCharacter{01CF}{\v{I}} ++ ++ \DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}} ++ \DeclareUnicodeCharacter{01D1}{\v{O}} ++ \DeclareUnicodeCharacter{01D2}{\v{o}} ++ \DeclareUnicodeCharacter{01D3}{\v{U}} ++ \DeclareUnicodeCharacter{01D4}{\v{u}} ++ ++ \DeclareUnicodeCharacter{01E2}{\={\AE}} ++ \DeclareUnicodeCharacter{01E3}{\={\ae}} ++ \DeclareUnicodeCharacter{01E6}{\v{G}} ++ \DeclareUnicodeCharacter{01E7}{\v{g}} ++ \DeclareUnicodeCharacter{01E8}{\v{K}} ++ \DeclareUnicodeCharacter{01E9}{\v{k}} ++ ++ \DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}} ++ \DeclareUnicodeCharacter{01F1}{DZ} ++ \DeclareUnicodeCharacter{01F2}{Dz} ++ \DeclareUnicodeCharacter{01F3}{dz} ++ \DeclareUnicodeCharacter{01F4}{\'G} ++ \DeclareUnicodeCharacter{01F5}{\'g} ++ \DeclareUnicodeCharacter{01F8}{\`N} ++ \DeclareUnicodeCharacter{01F9}{\`n} ++ \DeclareUnicodeCharacter{01FC}{\'{\AE}} ++ \DeclareUnicodeCharacter{01FD}{\'{\ae}} ++ \DeclareUnicodeCharacter{01FE}{\'{\O}} ++ \DeclareUnicodeCharacter{01FF}{\'{\o}} ++ ++ \DeclareUnicodeCharacter{021E}{\v{H}} ++ \DeclareUnicodeCharacter{021F}{\v{h}} ++ ++ \DeclareUnicodeCharacter{0226}{\dotaccent{A}} ++ \DeclareUnicodeCharacter{0227}{\dotaccent{a}} ++ \DeclareUnicodeCharacter{0228}{\cedilla{E}} ++ \DeclareUnicodeCharacter{0229}{\cedilla{e}} ++ \DeclareUnicodeCharacter{022E}{\dotaccent{O}} ++ \DeclareUnicodeCharacter{022F}{\dotaccent{o}} ++ ++ \DeclareUnicodeCharacter{0232}{\=Y} ++ \DeclareUnicodeCharacter{0233}{\=y} ++ \DeclareUnicodeCharacter{0237}{\dotless{j}} ++ ++ \DeclareUnicodeCharacter{1E02}{\dotaccent{B}} ++ \DeclareUnicodeCharacter{1E03}{\dotaccent{b}} ++ \DeclareUnicodeCharacter{1E04}{\udotaccent{B}} ++ \DeclareUnicodeCharacter{1E05}{\udotaccent{b}} ++ \DeclareUnicodeCharacter{1E06}{\ubaraccent{B}} ++ \DeclareUnicodeCharacter{1E07}{\ubaraccent{b}} ++ \DeclareUnicodeCharacter{1E0A}{\dotaccent{D}} ++ \DeclareUnicodeCharacter{1E0B}{\dotaccent{d}} ++ \DeclareUnicodeCharacter{1E0C}{\udotaccent{D}} ++ \DeclareUnicodeCharacter{1E0D}{\udotaccent{d}} ++ \DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}} ++ \DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}} ++ ++ \DeclareUnicodeCharacter{1E1E}{\dotaccent{F}} ++ \DeclareUnicodeCharacter{1E1F}{\dotaccent{f}} ++ ++ \DeclareUnicodeCharacter{1E20}{\=G} ++ \DeclareUnicodeCharacter{1E21}{\=g} ++ \DeclareUnicodeCharacter{1E22}{\dotaccent{H}} ++ \DeclareUnicodeCharacter{1E23}{\dotaccent{h}} ++ \DeclareUnicodeCharacter{1E24}{\udotaccent{H}} ++ \DeclareUnicodeCharacter{1E25}{\udotaccent{h}} ++ \DeclareUnicodeCharacter{1E26}{\"H} ++ \DeclareUnicodeCharacter{1E27}{\"h} ++ ++ \DeclareUnicodeCharacter{1E30}{\'K} ++ \DeclareUnicodeCharacter{1E31}{\'k} ++ \DeclareUnicodeCharacter{1E32}{\udotaccent{K}} ++ \DeclareUnicodeCharacter{1E33}{\udotaccent{k}} ++ \DeclareUnicodeCharacter{1E34}{\ubaraccent{K}} ++ \DeclareUnicodeCharacter{1E35}{\ubaraccent{k}} ++ \DeclareUnicodeCharacter{1E36}{\udotaccent{L}} ++ \DeclareUnicodeCharacter{1E37}{\udotaccent{l}} ++ \DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}} ++ \DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}} ++ \DeclareUnicodeCharacter{1E3E}{\'M} ++ \DeclareUnicodeCharacter{1E3F}{\'m} ++ ++ \DeclareUnicodeCharacter{1E40}{\dotaccent{M}} ++ \DeclareUnicodeCharacter{1E41}{\dotaccent{m}} ++ \DeclareUnicodeCharacter{1E42}{\udotaccent{M}} ++ \DeclareUnicodeCharacter{1E43}{\udotaccent{m}} ++ \DeclareUnicodeCharacter{1E44}{\dotaccent{N}} ++ \DeclareUnicodeCharacter{1E45}{\dotaccent{n}} ++ \DeclareUnicodeCharacter{1E46}{\udotaccent{N}} ++ \DeclareUnicodeCharacter{1E47}{\udotaccent{n}} ++ \DeclareUnicodeCharacter{1E48}{\ubaraccent{N}} ++ \DeclareUnicodeCharacter{1E49}{\ubaraccent{n}} ++ ++ \DeclareUnicodeCharacter{1E54}{\'P} ++ \DeclareUnicodeCharacter{1E55}{\'p} ++ \DeclareUnicodeCharacter{1E56}{\dotaccent{P}} ++ \DeclareUnicodeCharacter{1E57}{\dotaccent{p}} ++ \DeclareUnicodeCharacter{1E58}{\dotaccent{R}} ++ \DeclareUnicodeCharacter{1E59}{\dotaccent{r}} ++ \DeclareUnicodeCharacter{1E5A}{\udotaccent{R}} ++ \DeclareUnicodeCharacter{1E5B}{\udotaccent{r}} ++ \DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}} ++ \DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}} ++ ++ \DeclareUnicodeCharacter{1E60}{\dotaccent{S}} ++ \DeclareUnicodeCharacter{1E61}{\dotaccent{s}} ++ \DeclareUnicodeCharacter{1E62}{\udotaccent{S}} ++ \DeclareUnicodeCharacter{1E63}{\udotaccent{s}} ++ \DeclareUnicodeCharacter{1E6A}{\dotaccent{T}} ++ \DeclareUnicodeCharacter{1E6B}{\dotaccent{t}} ++ \DeclareUnicodeCharacter{1E6C}{\udotaccent{T}} ++ \DeclareUnicodeCharacter{1E6D}{\udotaccent{t}} ++ \DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}} ++ \DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}} ++ ++ \DeclareUnicodeCharacter{1E7C}{\~V} ++ \DeclareUnicodeCharacter{1E7D}{\~v} ++ \DeclareUnicodeCharacter{1E7E}{\udotaccent{V}} ++ \DeclareUnicodeCharacter{1E7F}{\udotaccent{v}} ++ ++ \DeclareUnicodeCharacter{1E80}{\`W} ++ \DeclareUnicodeCharacter{1E81}{\`w} ++ \DeclareUnicodeCharacter{1E82}{\'W} ++ \DeclareUnicodeCharacter{1E83}{\'w} ++ \DeclareUnicodeCharacter{1E84}{\"W} ++ \DeclareUnicodeCharacter{1E85}{\"w} ++ \DeclareUnicodeCharacter{1E86}{\dotaccent{W}} ++ \DeclareUnicodeCharacter{1E87}{\dotaccent{w}} ++ \DeclareUnicodeCharacter{1E88}{\udotaccent{W}} ++ \DeclareUnicodeCharacter{1E89}{\udotaccent{w}} ++ \DeclareUnicodeCharacter{1E8A}{\dotaccent{X}} ++ \DeclareUnicodeCharacter{1E8B}{\dotaccent{x}} ++ \DeclareUnicodeCharacter{1E8C}{\"X} ++ \DeclareUnicodeCharacter{1E8D}{\"x} ++ \DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}} ++ \DeclareUnicodeCharacter{1E8F}{\dotaccent{y}} ++ ++ \DeclareUnicodeCharacter{1E90}{\^Z} ++ \DeclareUnicodeCharacter{1E91}{\^z} ++ \DeclareUnicodeCharacter{1E92}{\udotaccent{Z}} ++ \DeclareUnicodeCharacter{1E93}{\udotaccent{z}} ++ \DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}} ++ \DeclareUnicodeCharacter{1E95}{\ubaraccent{z}} ++ \DeclareUnicodeCharacter{1E96}{\ubaraccent{h}} ++ \DeclareUnicodeCharacter{1E97}{\"t} ++ \DeclareUnicodeCharacter{1E98}{\ringaccent{w}} ++ \DeclareUnicodeCharacter{1E99}{\ringaccent{y}} ++ ++ \DeclareUnicodeCharacter{1EA0}{\udotaccent{A}} ++ \DeclareUnicodeCharacter{1EA1}{\udotaccent{a}} ++ ++ \DeclareUnicodeCharacter{1EB8}{\udotaccent{E}} ++ \DeclareUnicodeCharacter{1EB9}{\udotaccent{e}} ++ \DeclareUnicodeCharacter{1EBC}{\~E} ++ \DeclareUnicodeCharacter{1EBD}{\~e} ++ ++ \DeclareUnicodeCharacter{1ECA}{\udotaccent{I}} ++ \DeclareUnicodeCharacter{1ECB}{\udotaccent{i}} ++ \DeclareUnicodeCharacter{1ECC}{\udotaccent{O}} ++ \DeclareUnicodeCharacter{1ECD}{\udotaccent{o}} ++ ++ \DeclareUnicodeCharacter{1EE4}{\udotaccent{U}} ++ \DeclareUnicodeCharacter{1EE5}{\udotaccent{u}} ++ ++ \DeclareUnicodeCharacter{1EF2}{\`Y} ++ \DeclareUnicodeCharacter{1EF3}{\`y} ++ \DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}} ++ ++ \DeclareUnicodeCharacter{1EF8}{\~Y} ++ \DeclareUnicodeCharacter{1EF9}{\~y} ++ ++ \DeclareUnicodeCharacter{2013}{--} ++ \DeclareUnicodeCharacter{2014}{---} ++ \DeclareUnicodeCharacter{2022}{\bullet} ++ \DeclareUnicodeCharacter{2026}{\dots} ++ \DeclareUnicodeCharacter{20AC}{\euro} ++ ++ \DeclareUnicodeCharacter{2192}{\expansion} ++ \DeclareUnicodeCharacter{21D2}{\result} ++ ++ \DeclareUnicodeCharacter{2212}{\minus} ++ \DeclareUnicodeCharacter{2217}{\point} ++ \DeclareUnicodeCharacter{2261}{\equiv} ++}% end of \utfeightchardefs ++ ++ ++% US-ASCII character definitions. ++\def\asciichardefs{% nothing need be done ++ \relax ++} ++ ++% Make non-ASCII characters printable again for compatibility with ++% existing Texinfo documents that may use them, even without declaring a ++% document encoding. ++% ++\setnonasciicharscatcode \other ++ ++ ++\message{formatting,} ++ ++\newdimen\defaultparindent \defaultparindent = 15pt ++ ++\chapheadingskip = 15pt plus 4pt minus 2pt ++\secheadingskip = 12pt plus 3pt minus 2pt ++\subsecheadingskip = 9pt plus 2pt minus 2pt ++ ++% Prevent underfull vbox error messages. ++\vbadness = 10000 ++ ++% Don't be so finicky about underfull hboxes, either. ++\hbadness = 2000 ++ ++% Following George Bush, just get rid of widows and orphans. ++\widowpenalty=10000 ++\clubpenalty=10000 ++ ++% Use TeX 3.0's \emergencystretch to help line breaking, but if we're ++% using an old version of TeX, don't do anything. We want the amount of ++% stretch added to depend on the line length, hence the dependence on ++% \hsize. We call this whenever the paper size is set. ++% ++\def\setemergencystretch{% ++ \ifx\emergencystretch\thisisundefined ++ % Allow us to assign to \emergencystretch anyway. ++ \def\emergencystretch{\dimen0}% ++ \else ++ \emergencystretch = .15\hsize ++ \fi ++} ++ ++% Parameters in order: 1) textheight; 2) textwidth; ++% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip; ++% 7) physical page height; 8) physical page width. ++% ++% We also call \setleading{\textleading}, so the caller should define ++% \textleading. The caller should also set \parskip. ++% ++\def\internalpagesizes#1#2#3#4#5#6#7#8{% ++ \voffset = #3\relax ++ \topskip = #6\relax ++ \splittopskip = \topskip ++ % ++ \vsize = #1\relax ++ \advance\vsize by \topskip ++ \outervsize = \vsize ++ \advance\outervsize by 2\topandbottommargin ++ \pageheight = \vsize ++ % ++ \hsize = #2\relax ++ \outerhsize = \hsize ++ \advance\outerhsize by 0.5in ++ \pagewidth = \hsize ++ % ++ \normaloffset = #4\relax ++ \bindingoffset = #5\relax ++ % ++ \ifpdf ++ \pdfpageheight #7\relax ++ \pdfpagewidth #8\relax ++ \pdfhorigin = 1 true in ++ \pdfvorigin = 1 true in ++ \fi ++ % ++ \setleading{\textleading} ++ % ++ \parindent = \defaultparindent ++ \setemergencystretch ++} ++ ++% @letterpaper (the default). ++\def\letterpaper{{\globaldefs = 1 ++ \parskip = 3pt plus 2pt minus 1pt ++ \textleading = 13.2pt ++ % ++ % If page is nothing but text, make it come out even. ++ \internalpagesizes{46\baselineskip}{6in}% ++ {\voffset}{.25in}% ++ {\bindingoffset}{36pt}% ++ {11in}{8.5in}% ++}} ++ ++% Use @smallbook to reset parameters for 7x9.25 trim size. ++\def\smallbook{{\globaldefs = 1 ++ \parskip = 2pt plus 1pt ++ \textleading = 12pt ++ % ++ \internalpagesizes{7.5in}{5in}% ++ {-.2in}{0in}% ++ {\bindingoffset}{16pt}% ++ {9.25in}{7in}% ++ % ++ \lispnarrowing = 0.3in ++ \tolerance = 700 ++ \hfuzz = 1pt ++ \contentsrightmargin = 0pt ++ \defbodyindent = .5cm ++}} ++ ++% Use @smallerbook to reset parameters for 6x9 trim size. ++% (Just testing, parameters still in flux.) ++\def\smallerbook{{\globaldefs = 1 ++ \parskip = 1.5pt plus 1pt ++ \textleading = 12pt ++ % ++ \internalpagesizes{7.4in}{4.8in}% ++ {-.2in}{-.4in}% ++ {0pt}{14pt}% ++ {9in}{6in}% ++ % ++ \lispnarrowing = 0.25in ++ \tolerance = 700 ++ \hfuzz = 1pt ++ \contentsrightmargin = 0pt ++ \defbodyindent = .4cm ++}} ++ ++% Use @afourpaper to print on European A4 paper. ++\def\afourpaper{{\globaldefs = 1 ++ \parskip = 3pt plus 2pt minus 1pt ++ \textleading = 13.2pt ++ % ++ % Double-side printing via postscript on Laserjet 4050 ++ % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm. ++ % To change the settings for a different printer or situation, adjust ++ % \normaloffset until the front-side and back-side texts align. Then ++ % do the same for \bindingoffset. You can set these for testing in ++ % your texinfo source file like this: ++ % @tex ++ % \global\normaloffset = -6mm ++ % \global\bindingoffset = 10mm ++ % @end tex ++ \internalpagesizes{51\baselineskip}{160mm} ++ {\voffset}{\hoffset}% ++ {\bindingoffset}{44pt}% ++ {297mm}{210mm}% ++ % ++ \tolerance = 700 ++ \hfuzz = 1pt ++ \contentsrightmargin = 0pt ++ \defbodyindent = 5mm ++}} ++ ++% Use @afivepaper to print on European A5 paper. ++% From romildo@urano.iceb.ufop.br, 2 July 2000. ++% He also recommends making @example and @lisp be small. ++\def\afivepaper{{\globaldefs = 1 ++ \parskip = 2pt plus 1pt minus 0.1pt ++ \textleading = 12.5pt ++ % ++ \internalpagesizes{160mm}{120mm}% ++ {\voffset}{\hoffset}% ++ {\bindingoffset}{8pt}% ++ {210mm}{148mm}% ++ % ++ \lispnarrowing = 0.2in ++ \tolerance = 800 ++ \hfuzz = 1.2pt ++ \contentsrightmargin = 0pt ++ \defbodyindent = 2mm ++ \tableindent = 12mm ++}} ++ ++% A specific text layout, 24x15cm overall, intended for A4 paper. ++\def\afourlatex{{\globaldefs = 1 ++ \afourpaper ++ \internalpagesizes{237mm}{150mm}% ++ {\voffset}{4.6mm}% ++ {\bindingoffset}{7mm}% ++ {297mm}{210mm}% ++ % ++ % Must explicitly reset to 0 because we call \afourpaper. ++ \globaldefs = 0 ++}} ++ ++% Use @afourwide to print on A4 paper in landscape format. ++\def\afourwide{{\globaldefs = 1 ++ \afourpaper ++ \internalpagesizes{241mm}{165mm}% ++ {\voffset}{-2.95mm}% ++ {\bindingoffset}{7mm}% ++ {297mm}{210mm}% ++ \globaldefs = 0 ++}} ++ ++% @pagesizes TEXTHEIGHT[,TEXTWIDTH] ++% Perhaps we should allow setting the margins, \topskip, \parskip, ++% and/or leading, also. Or perhaps we should compute them somehow. ++% ++\parseargdef\pagesizes{\pagesizesyyy #1,,\finish} ++\def\pagesizesyyy#1,#2,#3\finish{{% ++ \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi ++ \globaldefs = 1 ++ % ++ \parskip = 3pt plus 2pt minus 1pt ++ \setleading{\textleading}% ++ % ++ \dimen0 = #1 ++ \advance\dimen0 by \voffset ++ % ++ \dimen2 = \hsize ++ \advance\dimen2 by \normaloffset ++ % ++ \internalpagesizes{#1}{\hsize}% ++ {\voffset}{\normaloffset}% ++ {\bindingoffset}{44pt}% ++ {\dimen0}{\dimen2}% ++}} ++ ++% Set default to letter. ++% ++\letterpaper ++ ++ ++\message{and turning on texinfo input format.} ++ ++% Define macros to output various characters with catcode for normal text. ++\catcode`\"=\other ++\catcode`\~=\other ++\catcode`\^=\other ++\catcode`\_=\other ++\catcode`\|=\other ++\catcode`\<=\other ++\catcode`\>=\other ++\catcode`\+=\other ++\catcode`\$=\other ++\def\normaldoublequote{"} ++\def\normaltilde{~} ++\def\normalcaret{^} ++\def\normalunderscore{_} ++\def\normalverticalbar{|} ++\def\normalless{<} ++\def\normalgreater{>} ++\def\normalplus{+} ++\def\normaldollar{$}%$ font-lock fix ++ ++% This macro is used to make a character print one way in \tt ++% (where it can probably be output as-is), and another way in other fonts, ++% where something hairier probably needs to be done. ++% ++% #1 is what to print if we are indeed using \tt; #2 is what to print ++% otherwise. Since all the Computer Modern typewriter fonts have zero ++% interword stretch (and shrink), and it is reasonable to expect all ++% typewriter fonts to have this, we can check that font parameter. ++% ++\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi} ++ ++% Same as above, but check for italic font. Actually this also catches ++% non-italic slanted fonts since it is impossible to distinguish them from ++% italic fonts. But since this is only used by $ and it uses \sl anyway ++% this is not a problem. ++\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi} ++ ++% Turn off all special characters except @ ++% (and those which the user can use as if they were ordinary). ++% Most of these we simply print from the \tt font, but for some, we can ++% use math or other variants that look better in normal text. ++ ++\catcode`\"=\active ++\def\activedoublequote{{\tt\char34}} ++\let"=\activedoublequote ++\catcode`\~=\active ++\def~{{\tt\char126}} ++\chardef\hat=`\^ ++\catcode`\^=\active ++\def^{{\tt \hat}} ++ ++\catcode`\_=\active ++\def_{\ifusingtt\normalunderscore\_} ++\let\realunder=_ ++% Subroutine for the previous macro. ++\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em } ++ ++\catcode`\|=\active ++\def|{{\tt\char124}} ++\chardef \less=`\< ++\catcode`\<=\active ++\def<{{\tt \less}} ++\chardef \gtr=`\> ++\catcode`\>=\active ++\def>{{\tt \gtr}} ++\catcode`\+=\active ++\def+{{\tt \char 43}} ++\catcode`\$=\active ++\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix ++ ++% If a .fmt file is being used, characters that might appear in a file ++% name cannot be active until we have parsed the command line. ++% So turn them off again, and have \everyjob (or @setfilename) turn them on. ++% \otherifyactive is called near the end of this file. ++\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} ++ ++% Used sometimes to turn off (effectively) the active characters even after ++% parsing them. ++\def\turnoffactive{% ++ \normalturnoffactive ++ \otherbackslash ++} ++ ++\catcode`\@=0 ++ ++% \backslashcurfont outputs one backslash character in current font, ++% as in \char`\\. ++\global\chardef\backslashcurfont=`\\ ++\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work ++ ++% \realbackslash is an actual character `\' with catcode other, and ++% \doublebackslash is two of them (for the pdf outlines). ++{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}} ++ ++% In texinfo, backslash is an active character; it prints the backslash ++% in fixed width font. ++\catcode`\\=\active ++@def@normalbackslash{{@tt@backslashcurfont}} ++% On startup, @fixbackslash assigns: ++% @let \ = @normalbackslash ++ ++% \rawbackslash defines an active \ to do \backslashcurfont. ++% \otherbackslash defines an active \ to be a literal `\' character with ++% catcode other. ++@gdef@rawbackslash{@let\=@backslashcurfont} ++@gdef@otherbackslash{@let\=@realbackslash} ++ ++% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of ++% the literal character `\'. ++% ++@def@normalturnoffactive{% ++ @let\=@normalbackslash ++ @let"=@normaldoublequote ++ @let~=@normaltilde ++ @let^=@normalcaret ++ @let_=@normalunderscore ++ @let|=@normalverticalbar ++ @let<=@normalless ++ @let>=@normalgreater ++ @let+=@normalplus ++ @let$=@normaldollar %$ font-lock fix ++ @unsepspaces ++} ++ ++% Make _ and + \other characters, temporarily. ++% This is canceled by @fixbackslash. ++@otherifyactive ++ ++% If a .fmt file is being used, we don't want the `\input texinfo' to show up. ++% That is what \eatinput is for; after that, the `\' should revert to printing ++% a backslash. ++% ++@gdef@eatinput input texinfo{@fixbackslash} ++@global@let\ = @eatinput ++ ++% On the other hand, perhaps the file did not have a `\input texinfo'. Then ++% the first `\' in the file would cause an error. This macro tries to fix ++% that, assuming it is called before the first `\' could plausibly occur. ++% Also turn back on active characters that might appear in the input ++% file name, in case not using a pre-dumped format. ++% ++@gdef@fixbackslash{% ++ @ifx\@eatinput @let\ = @normalbackslash @fi ++ @catcode`+=@active ++ @catcode`@_=@active ++} ++ ++% Say @foo, not \foo, in error messages. ++@escapechar = `@@ ++ ++% These look ok in all fonts, so just make them not special. ++@catcode`@& = @other ++@catcode`@# = @other ++@catcode`@% = @other ++ ++ ++@c Local variables: ++@c eval: (add-hook 'write-file-hooks 'time-stamp) ++@c page-delimiter: "^\\\\message" ++@c time-stamp-start: "def\\\\texinfoversion{" ++@c time-stamp-format: "%:y-%02m-%02d.%02H" ++@c time-stamp-end: "}" ++@c End: ++ ++@c vim:sw=2: ++ ++@ignore ++ arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115 ++@end ignore +diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi +new file mode 100644 +index 0000000..00b5f4c +--- /dev/null ++++ b/doc/misc/tramp.texi +@@ -0,0 +1,3500 @@ ++\input texinfo @c -*-texinfo-*- ++@setfilename ../../info/tramp ++@c %**start of header ++@settitle TRAMP User Manual ++@c %**end of header ++ ++@c This is *so* much nicer :) ++@footnotestyle end ++ ++@c In the Tramp CVS, the version number is auto-frobbed from ++@c configure.ac, so you should edit that file and run ++@c "autoconf && ./configure" to change the version number. ++ ++@c Additionally, flags are set with respect to the Emacs flavor; and ++@c depending whether Tramp is packaged into (X)Emacs, or standalone. ++ ++@include trampver.texi ++ ++@c Macro for formatting a filename according to the repective syntax. ++@c xxx and yyy are auxiliary macros in order to omit leading and ++@c trailing whitespace. Not very elegant, but I don't know it better. ++ ++@macro xxx {one}@c ++@set \one\@c ++@end macro ++ ++@macro yyy {one, two}@c ++@xxx{x\one\}@c ++@ifclear x@c ++\one\@w{}\two\@c ++@end ifclear ++@clear x\one\@c ++@end macro ++ ++@macro trampfn {method, user, host, localname}@c ++@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c ++@end macro ++ ++@copying ++Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, ++2006, 2007, 2008, 2009 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 ++ ++@c Entries for @command{install-info} to use ++@dircategory @value{emacsname} ++@direntry ++* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol ++ @value{emacsname} remote file access via rsh and rcp. ++@end direntry ++ ++@titlepage ++@title @value{tramp} version @value{trampver} User Manual ++@author by Daniel Pittman ++@author based on documentation by Kai Gro@ss{}johann ++@page ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top, Overview, (dir), (dir) ++@top @value{tramp} version @value{trampver} User Manual ++ ++This file documents @value{tramp} version @value{trampver}, a remote file ++editing package for @value{emacsname}. ++ ++@value{tramp} stands for `Transparent Remote (file) Access, Multiple ++Protocol'. This package provides remote file editing, similar to ++@value{ftppackagename}. ++ ++The difference is that @value{ftppackagename} uses FTP to transfer ++files between the local and the remote host, whereas @value{tramp} uses a ++combination of @command{rsh} and @command{rcp} or other work-alike ++programs, such as @command{ssh}/@command{scp}. ++ ++You can find the latest version of this document on the web at ++@uref{http://www.gnu.org/software/tramp/}. ++ ++@c Pointer to the other Emacs flavor is necessary only in case of ++@c standalone installation. ++@ifset installchapter ++The manual has been generated for @value{emacsname}. ++@ifinfo ++If you want to read the info pages for @value{emacsothername}, you ++should read in @ref{Installation} how to create them. ++@end ifinfo ++@ifhtml ++If you're using the other Emacs flavor, you should read the ++@uref{@value{emacsotherfilename}, @value{emacsothername}} pages. ++@end ifhtml ++@end ifset ++ ++@ifhtml ++@ifset jamanual ++This manual is also available as a @uref{@value{japanesemanual}, ++Japanese translation}. ++@end ifset ++ ++The latest release of @value{tramp} is available for ++@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see ++@ref{Obtaining Tramp} for more details, including the CVS server ++details. ++ ++@value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/, ++Savannah Project Page}. ++@end ifhtml ++ ++There is a mailing list for @value{tramp}, available at ++@email{tramp-devel@@gnu.org}, and archived at ++@uref{http://lists.gnu.org/archive/html/tramp-devel/, the ++@value{tramp} Mail Archive}. ++@ifhtml ++Older archives are located at ++@uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel, ++SourceForge Mail Archive} and ++@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/, ++The Mail Archive}. ++@c in HTML output, there's no new paragraph. ++@*@* ++@end ifhtml ++ ++@insertcopying ++ ++@end ifnottex ++ ++@menu ++* Overview:: What @value{tramp} can and cannot do. ++ ++For the end user: ++ ++* Obtaining Tramp:: How to obtain @value{tramp}. ++* History:: History of @value{tramp}. ++@ifset installchapter ++* Installation:: Installing @value{tramp} with your @value{emacsname}. ++@end ifset ++* Configuration:: Configuring @value{tramp} for use. ++* Usage:: An overview of the operation of @value{tramp}. ++* Bug Reports:: Reporting Bugs and Problems. ++* Frequently Asked Questions:: Questions and answers from the mailing list. ++* Function Index:: @value{tramp} functions. ++* Variable Index:: User options and variables. ++* Concept Index:: An item for each concept. ++ ++For the developer: ++ ++* Version Control:: The inner workings of remote version control. ++* Files directories and localnames:: How file names, directories and localnames are mangled and managed. ++* Traces and Profiles:: How to Customize Traces. ++* Issues:: Debatable Issues and What Was Decided. ++ ++* GNU Free Documentation License:: The license for this documentation. ++ ++@detailmenu ++ --- The Detailed Node Listing --- ++@c ++@ifset installchapter ++Installing @value{tramp} with your @value{emacsname} ++ ++* Installation parameters:: Parameters in order to control installation. ++* Load paths:: How to plug-in @value{tramp} into your environment. ++* Japanese manual:: Japanese manual. ++ ++@end ifset ++ ++Configuring @value{tramp} for use ++ ++* Connection types:: Types of connections made to remote machines. ++* Inline methods:: Inline methods. ++* External methods:: External methods. ++@ifset emacsgw ++* Gateway methods:: Gateway methods. ++@end ifset ++* Default Method:: Selecting a default method. ++* Default User:: Selecting a default user. ++* Default Host:: Selecting a default host. ++* Multi-hops:: Connecting to a remote host using multiple hops. ++* Customizing Methods:: Using Non-Standard Methods. ++* Customizing Completion:: Selecting config files for user/host name completion. ++* Password handling:: Reusing passwords for several connections. ++* Connection caching:: Reusing connection related information. ++* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. ++* Remote shell setup:: Remote shell setup hints. ++* Windows setup hints:: Issues with Cygwin ssh. ++* Auto-save and Backup:: Auto-save and Backup. ++ ++Using @value{tramp} ++ ++* Filename Syntax:: @value{tramp} filename conventions. ++* Alternative Syntax:: URL-like filename syntax. ++* Filename completion:: Filename completion. ++* Remote processes:: Integration with other @value{emacsname} packages. ++* Cleanup remote connections:: Cleanup remote connections. ++ ++The inner workings of remote version control ++ ++* Version Controlled Files:: Determining if a file is under version control. ++* Remote Commands:: Executing the version control commands on the remote machine. ++* Changed workfiles:: Detecting if the working file has changed. ++* Checking out files:: Bringing the workfile out of the repository. ++* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere. ++ ++Things related to Version Control that don't fit elsewhere ++ ++* Remote File Ownership:: How VC determines who owns a workfile. ++* Back-end Versions:: How VC determines what release your RCS is. ++ ++How file names, directories and localnames are mangled and managed ++ ++* Localname deconstruction:: Breaking a localname into its components. ++@ifset emacs ++* External packages:: Integration with external Lisp packages. ++@end ifset ++ ++@end detailmenu ++@end menu ++ ++@node Overview ++@chapter An overview of @value{tramp} ++@cindex overview ++ ++After the installation of @value{tramp} into your @value{emacsname}, you ++will be able to access files on remote machines as though they were ++local. Access to the remote file system for editing files, version ++control, and @code{dired} are transparently enabled. ++ ++Your access to the remote machine can be with the @command{rsh}, ++@command{rlogin}, @command{telnet} programs or with any similar ++connection method. This connection must pass @acronym{ASCII} ++successfully to be usable but need not be 8-bit clean. ++ ++The package provides support for @command{ssh} connections out of the ++box, one of the more common uses of the package. This allows ++relatively secure access to machines, especially if @command{ftp} ++access is disabled. ++ ++Under Windows, @value{tramp} is integrated with the PuTTY package, ++using the @command{plink} program. ++ ++The majority of activity carried out by @value{tramp} requires only that ++the remote login is possible and is carried out at the terminal. In ++order to access remote files @value{tramp} needs to transfer their content ++to the local machine temporarily. ++ ++@value{tramp} can transfer files between the machines in a variety of ways. ++The details are easy to select, depending on your needs and the ++machines in question. ++ ++The fastest transfer methods for large files rely on a remote file ++transfer package such as @command{rcp}, @command{scp}, @command{rsync} ++or (under Windows) @command{pscp}. ++ ++If the remote copy methods are not suitable for you, @value{tramp} also ++supports the use of encoded transfers directly through the shell. ++This requires that the @command{mimencode} or @command{uuencode} tools ++are available on the remote machine. These methods are generally ++faster for small files. ++ ++@value{tramp} is still under active development and any problems you encounter, ++trivial or major, should be reported to the @value{tramp} developers. ++@xref{Bug Reports}. ++ ++ ++@subsubheading Behind the scenes ++@cindex behind the scenes ++@cindex details of operation ++@cindex how it works ++ ++This section tries to explain what goes on behind the scenes when you ++access a remote file through @value{tramp}. ++ ++Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name, ++then hit @kbd{@key{TAB}} for completion. Suppose further that this is ++the first time that @value{tramp} is invoked for the host in question. Here's ++what happens: ++ ++@itemize ++@item ++@value{tramp} discovers that it needs a connection to the host. So it ++invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l ++@var{user}} or a similar tool to connect to the remote host. ++Communication with this process happens through an ++@value{emacsname} buffer, that is, the output from the remote end ++goes into a buffer. ++ ++@item ++The remote host may prompt for a login name (for @command{telnet}). ++The login name is given in the file name, so @value{tramp} sends the ++login name and a newline. ++ ++@item ++The remote host may prompt for a password or pass phrase (for ++@command{rsh} or for @command{telnet} after sending the login name). ++@value{tramp} displays the prompt in the minibuffer, asking you for the ++password or pass phrase. ++ ++You enter the password or pass phrase. @value{tramp} sends it to the remote ++host, followed by a newline. ++ ++@item ++@value{tramp} now waits for the shell prompt or for a message that the login ++failed. ++ ++If @value{tramp} sees neither of them after a certain period of time ++(a minute, say), then it issues an error message saying that it ++couldn't find the remote shell prompt and shows you what the remote ++host has sent. ++ ++If @value{tramp} sees a @samp{login failed} message, it tells you so, ++aborts the login attempt and allows you to try again. ++ ++@item ++Suppose that the login was successful and @value{tramp} sees the shell prompt ++from the remote host. Now @value{tramp} invokes @command{/bin/sh} because ++Bourne shells and C shells have different command ++syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login ++shell doesn't recognize @samp{exec /bin/sh} as a valid command. ++Maybe you use the Scheme shell @command{scsh}@dots{}} ++ ++After the Bourne shell has come up, @value{tramp} sends a few commands to ++ensure a good working environment. It turns off echoing, it sets the ++shell prompt, and a few other things. ++ ++@item ++Now the remote shell is up and it good working order. Remember, what ++was supposed to happen is that @value{tramp} tries to find out what files exist ++on the remote host so that it can do filename completion. ++ ++So, @value{tramp} basically issues @command{cd} and @command{ls} commands and ++also sometimes @command{echo} with globbing. Another command that is ++often used is @command{test} to find out whether a file is writable or a ++directory or the like. The output of each command is parsed for the ++necessary operation. ++ ++@item ++Suppose you are finished with filename completion, have entered @kbd{C-x ++C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to ++transfer the file contents from the remote host to the local host so ++that you can edit them. ++ ++See above for an explanation of how @value{tramp} transfers the file contents. ++ ++For inline transfers, @value{tramp} issues a command like @samp{mimencode -b ++/path/to/remote/file}, waits until the output has accumulated in the ++buffer that's used for communication, then decodes that output to ++produce the file contents. ++ ++For external transfers, @value{tramp} issues a command like the ++following: ++@example ++rcp user@@host:/path/to/remote/file /tmp/tramp.4711 ++@end example ++It then reads the local temporary file @file{/tmp/tramp.4711} into a ++buffer and deletes the temporary file. ++ ++@item ++You now edit the buffer contents, blithely unaware of what has happened ++behind the scenes. (Unless you have read this section, that is.) When ++you are finished, you type @kbd{C-x C-s} to save the buffer. ++ ++@item ++Again, @value{tramp} transfers the file contents to the remote host ++either inline or external. This is the reverse of what happens when ++reading the file. ++@end itemize ++ ++I hope this has provided you with a basic overview of what happens ++behind the scenes when you open a file with @value{tramp}. ++ ++ ++@c For the end user ++@node Obtaining Tramp ++@chapter Obtaining Tramp. ++@cindex obtaining Tramp ++ ++@value{tramp} is freely available on the Internet and the latest ++release may be downloaded from ++@uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full ++documentation and code for @value{tramp}, suitable for installation. ++But GNU Emacs (22 or later) includes @value{tramp} already, and there ++is a @value{tramp} package for XEmacs, as well. So maybe it is easier ++to just use those. But if you want the bleeding edge, read ++on@dots{...} ++ ++For the especially brave, @value{tramp} is available from CVS. The CVS ++version is the latest version of the code and may contain incomplete ++features or new issues. Use these versions at your own risk. ++ ++Instructions for obtaining the latest development version of @value{tramp} ++from CVS can be found by going to the Savannah project page at the ++following URL and then clicking on the CVS link in the navigation bar ++at the top. ++ ++@noindent ++@uref{http://savannah.gnu.org/projects/tramp/} ++ ++@noindent ++Or follow the example session below: ++ ++@example ++] @strong{cd ~/@value{emacsdir}} ++] @strong{export CVS_RSH="ssh"} ++] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp} ++@end example ++ ++@noindent ++You should now have a directory @file{~/@value{emacsdir}/tramp} ++containing the latest version of @value{tramp}. You can fetch the latest ++updates from the repository by issuing the command: ++ ++@example ++] @strong{cd ~/@value{emacsdir}/tramp} ++] @strong{export CVS_RSH="ssh"} ++] @strong{cvs update -d} ++@end example ++ ++@noindent ++Once you've got updated files from the CVS repository, you need to run ++@command{autoconf} in order to get an up-to-date @file{configure} ++script: ++ ++@example ++] @strong{cd ~/@value{emacsdir}/tramp} ++] @strong{autoconf} ++@end example ++ ++People who have no direct CVS access (maybe because sitting behind a ++blocking firewall), can try the ++@uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly ++CVS Tree Tarball} instead of. ++ ++ ++@node History ++@chapter History of @value{tramp} ++@cindex history ++@cindex development history ++ ++Development was started end of November 1998. The package was called ++@file{rssh.el}, back then. It only provided one method to access a ++file, using @command{ssh} to log in to a remote host and using ++@command{scp} to transfer the file contents. After a while, the name ++was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way, ++many more methods for getting a remote shell and for transferring the ++file contents were added. Support for VC was added. ++ ++The most recent addition of major features were the multi-hop methods ++added in April 2000 and the unification of @value{tramp} and Ange-FTP ++filenames in July 2002. In July 2004, multi-hop methods have been ++replaced by proxy hosts. Running commands on remote hosts was ++introduced in December 2005. ++@ifset emacsgw ++Support of gateways exists since April 2007. ++@end ifset ++ ++In December 2001, @value{tramp} has been added to the XEmacs package ++repository. Being part of the GNU Emacs repository happened in June ++2002, the first release including @value{tramp} was GNU Emacs 22.1. ++ ++@value{tramp} is also a GNU/Linux Debian package since February 2001. ++ ++ ++@c Installation chapter is necessary only in case of standalone ++@c installation. Text taken from trampinst.texi. ++@ifset installchapter ++@include trampinst.texi ++@end ifset ++ ++@node Configuration ++@chapter Configuring @value{tramp} for use ++@cindex configuration ++ ++@cindex default configuration ++@value{tramp} is (normally) fully functional when it is initially ++installed. It is initially configured to use the @command{scp} ++program to connect to the remote host. So in the easiest case, you ++just type @kbd{C-x C-f} and then enter the filename ++@file{@trampfn{, user, machine, /path/to.file}}. ++ ++On some hosts, there are problems with opening a connection. These are ++related to the behavior of the remote shell. See @xref{Remote shell ++setup}, for details on this. ++ ++If you do not wish to use these commands to connect to the remote ++host, you should change the default connection and transfer method ++that @value{tramp} uses. There are several different methods that @value{tramp} ++can use to connect to remote machines and transfer files ++(@pxref{Connection types}). ++ ++If you don't know which method is right for you, see @xref{Default ++Method}. ++ ++ ++@menu ++* Connection types:: Types of connections made to remote machines. ++* Inline methods:: Inline methods. ++* External methods:: External methods. ++@ifset emacsgw ++* Gateway methods:: Gateway methods. ++@end ifset ++* Default Method:: Selecting a default method. ++ Here we also try to help those who ++ don't have the foggiest which method ++ is right for them. ++* Default User:: Selecting a default user. ++* Default Host:: Selecting a default host. ++* Multi-hops:: Connecting to a remote host using multiple hops. ++* Customizing Methods:: Using Non-Standard Methods. ++* Customizing Completion:: Selecting config files for user/host name completion. ++* Password handling:: Reusing passwords for several connections. ++* Connection caching:: Reusing connection related information. ++* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. ++* Remote shell setup:: Remote shell setup hints. ++* Windows setup hints:: Issues with Cygwin ssh. ++* Auto-save and Backup:: Auto-save and Backup. ++@end menu ++ ++ ++@node Connection types ++@section Types of connections made to remote machines. ++@cindex connection types, overview ++ ++There are two basic types of transfer methods, each with its own ++advantages and limitations. Both types of connection make use of a ++remote shell access program such as @command{rsh}, @command{ssh} or ++@command{telnet} to connect to the remote machine. ++ ++This connection is used to perform many of the operations that @value{tramp} ++requires to make the remote file system transparently accessible from ++the local machine. It is only when visiting files that the methods ++differ. ++ ++@cindex inline methods ++@cindex external methods ++@cindex methods, inline ++@cindex methods, external ++Loading or saving a remote file requires that the content of the file ++be transfered between the two machines. The content of the file can ++be transfered using one of two methods: the @dfn{inline method} over ++the same connection used to log in to the remote machine, or the ++@dfn{external method} through another connection using a remote copy ++program such as @command{rcp}, @command{scp} or @command{rsync}. ++ ++The performance of the external methods is generally better than that ++of the inline methods, at least for large files. This is caused by ++the need to encode and decode the data when transferring inline. ++ ++The one exception to this rule are the @command{scp} based transfer ++methods. While these methods do see better performance when actually ++transferring files, the overhead of the cryptographic negotiation at ++startup may drown out the improvement in file transfer times. ++ ++External methods should be configured such a way that they don't ++require a password (with @command{ssh-agent}, or such alike). Modern ++@command{scp} implementations offer options to reuse existing ++@command{ssh} connections, see method @command{scpc}. If it isn't ++possible, you should consider @ref{Password handling}, otherwise you ++will be prompted for a password every copy action. ++ ++ ++@node Inline methods ++@section Inline methods ++@cindex inline methods ++@cindex methods, inline ++ ++The inline methods in @value{tramp} are quite powerful and can work in ++situations where you cannot use an external transfer program to connect. ++Inline methods are the only methods that work when connecting to the ++remote machine via telnet. (There are also strange inline methods which ++allow you to transfer files between @emph{user identities} rather than ++hosts, see below.) ++ ++These methods depend on the existence of a suitable encoding and ++decoding command on remote machine. Locally, @value{tramp} may be able to ++use features of @value{emacsname} to decode and encode the files or ++it may require access to external commands to perform that task. ++ ++@cindex uuencode ++@cindex mimencode ++@cindex base-64 encoding ++@value{tramp} checks the availability and usability of commands like ++@command{mimencode} (part of the @command{metamail} package) or ++@command{uuencode} on the remote host. The first reliable command ++will be used. The search path can be customized, see @ref{Remote ++Programs}. ++ ++If both commands aren't available on the remote host, @value{tramp} ++transfers a small piece of Perl code to the remote host, and tries to ++apply it for encoding and decoding. ++ ++ ++@table @asis ++@item @option{rsh} ++@cindex method rsh ++@cindex rsh method ++ ++Connect to the remote host with @command{rsh}. Due to the unsecure ++connection it is recommended for very local host topology only. ++ ++On operating systems which provide the command @command{remsh} instead ++of @command{rsh}, you can use the method @option{remsh}. This is true ++for HP-UX or Cray UNICOS, for example. ++ ++ ++@item @option{ssh} ++@cindex method ssh ++@cindex ssh method ++ ++Connect to the remote host with @command{ssh}. This is identical to ++the previous option except that the @command{ssh} package is used, ++making the connection more secure. ++ ++There are also two variants, @option{ssh1} and @option{ssh2}, that ++call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can ++explicitly select whether you want to use the SSH protocol version 1 ++or 2 to connect to the remote host. (You can also specify in ++@file{~/.ssh/config}, the SSH configuration file, which protocol ++should be used, and use the regular @option{ssh} method.) ++ ++Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the ++@command{ssh1} and @command{ssh2} commands explicitly. If you don't ++know what these are, you do not need these options. ++ ++All the methods based on @command{ssh} have an additional kludgy ++feature: you can specify a host name which looks like @file{host#42} ++(the real host name, then a hash sign, then a port number). This ++means to connect to the given host but to also pass @code{-p 42} as ++arguments to the @command{ssh} command. ++ ++ ++@item @option{telnet} ++@cindex method telnet ++@cindex telnet method ++ ++Connect to the remote host with @command{telnet}. This is as unsecure ++as the @option{rsh} method. ++ ++ ++@item @option{su} ++@cindex method su ++@cindex su method ++ ++This method does not connect to a remote host at all, rather it uses ++the @command{su} program to allow you to edit files as another user. ++That means, the specified host name in the file name must be either ++@samp{localhost} or the host name as returned by the function ++@command{(system-name)}. For an exception of this rule see ++@ref{Multi-hops}. ++ ++ ++@item @option{sudo} ++@cindex method sudo ++@cindex sudo method ++ ++This is similar to the @option{su} method, but it uses @command{sudo} ++rather than @command{su} to become a different user. ++ ++Note that @command{sudo} must be configured to allow you to start a ++shell as the user. It would be nice if it was sufficient if ++@command{ls} and @command{mimencode} were allowed, but that is not ++easy to implement, so I haven't got around to it, yet. ++ ++ ++@item @option{sshx} ++@cindex method sshx ++@cindex sshx method ++ ++As you would expect, this is similar to @option{ssh}, only a little ++different. Whereas @option{ssh} opens a normal interactive shell on ++the remote host, this option uses @samp{ssh -t -t @var{host} -l ++@var{user} /bin/sh} to open a connection. This is useful for users ++where the normal login shell is set up to ask them a number of ++questions when logging in. This procedure avoids these questions, and ++just gives @value{tramp} a more-or-less `standard' login shell to work ++with. ++ ++Note that this procedure does not eliminate questions asked by ++@command{ssh} itself. For example, @command{ssh} might ask ``Are you ++sure you want to continue connecting?'' if the host key of the remote ++host is not known. @value{tramp} does not know how to deal with such a ++question (yet), therefore you will need to make sure that you can log ++in without such questions. ++ ++This is also useful for Windows users where @command{ssh}, when ++invoked from an @value{emacsname} buffer, tells them that it is not ++allocating a pseudo tty. When this happens, the login shell is wont ++to not print any shell prompt, which confuses @value{tramp} mightily. ++For reasons unknown, some Windows ports for @command{ssh} require the ++doubled @samp{-t} option. ++ ++This supports the @samp{-p} kludge. ++ ++ ++@item @option{krlogin} ++@cindex method krlogin ++@cindex krlogin method ++@cindex Kerberos (with krlogin method) ++ ++This method is also similar to @option{ssh}. It only uses the ++@command{krlogin -x} command to log in to the remote host. ++ ++ ++@item @option{plink} ++@cindex method plink ++@cindex plink method ++ ++This method is mostly interesting for Windows users using the PuTTY ++implementation of SSH. It uses @samp{plink -ssh} to log in to the ++remote host. ++ ++This supports the @samp{-P} kludge. ++ ++Additionally, the methods @option{plink1} and @option{plink2} are ++provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in ++order to use SSH protocol version 1 or 2 explicitly. ++ ++CCC: Do we have to connect to the remote host once from the command ++line to accept the SSH key? Maybe this can be made automatic? ++ ++CCC: Say something about the first shell command failing. This might ++be due to a wrong setting of @code{tramp-rsh-end-of-line}. ++ ++ ++@item @option{plinkx} ++@cindex method plinkx ++@cindex plinkx method ++ ++Another method using PuTTY on Windows. Instead of host names, it ++expects PuTTY session names, calling @samp{plink -load @var{session} ++-t"}. User names are relevant only in case the corresponding session ++hasn't defined a user name. Different port numbers must be defined in ++the session. ++ ++ ++@item @option{fish} ++@cindex method fish ++@cindex fish method ++ ++This is an experimental implementation of the fish protocol, known from ++the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects ++the fish server implementation from the KDE kioslave. That means, the ++file @file{~/.fishsrv.pl} is expected to reside on the remote host. ++ ++The implementation lacks good performance. The code is offered anyway, ++maybe somebody can improve the performance. ++ ++@end table ++ ++ ++@node External methods ++@section External methods ++@cindex methods, external ++@cindex external methods ++ ++The external methods operate through multiple channels, using the ++remote shell connection for many actions while delegating file ++transfers to an external transfer utility. ++ ++This saves the overhead of encoding and decoding that multiplexing the ++transfer through the one connection has with the inline methods. ++ ++Since external methods need their own overhead opening a new channel, ++all files which are smaller than @var{tramp-copy-size-limit} are still ++transferred with the corresponding inline method. It should provide a ++fair trade-off between both approaches. ++ ++@table @asis ++@item @option{rcp} --- @command{rsh} and @command{rcp} ++@cindex method rcp ++@cindex rcp method ++@cindex rcp (with rcp method) ++@cindex rsh (with rcp method) ++ ++This method uses the @command{rsh} and @command{rcp} commands to connect ++to the remote machine and transfer files. This is probably the fastest ++connection method available. ++ ++The alternative method @option{remcp} uses the @command{remsh} and ++@command{rcp} commands. It should be applied on machines where ++@command{remsh} is used instead of @command{rsh}. ++ ++ ++@item @option{scp} --- @command{ssh} and @command{scp} ++@cindex method scp ++@cindex scp method ++@cindex scp (with scp method) ++@cindex ssh (with scp method) ++ ++Using @command{ssh} to connect to the remote host and @command{scp} to ++transfer files between the machines is the best method for securely ++connecting to a remote machine and accessing files. ++ ++The performance of this option is also quite good. It may be slower than ++the inline methods when you often open and close small files however. ++The cost of the cryptographic handshake at the start of an @command{scp} ++session can begin to absorb the advantage that the lack of encoding and ++decoding presents. ++ ++There are also two variants, @option{scp1} and @option{scp2}, that ++call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can ++explicitly select whether you want to use the SSH protocol version 1 ++or 2 to connect to the remote host. (You can also specify in ++@file{~/.ssh/config}, the SSH configuration file, which protocol ++should be used, and use the regular @option{scp} method.) ++ ++Two other variants, @option{scp1_old} and @option{scp2_old}, use the ++@command{ssh1} and @command{ssh2} commands explicitly. If you don't ++know what these are, you do not need these options. ++ ++All the @command{ssh} based methods support the kludgy @samp{-p} ++feature where you can specify a port number to connect to in the host ++name. For example, the host name @file{host#42} tells @value{tramp} to ++specify @samp{-p 42} in the argument list for @command{ssh}, and to ++specify @samp{-P 42} in the argument list for @command{scp}. ++ ++ ++@item @option{sftp} --- @command{ssh} and @command{sftp} ++@cindex method sftp ++@cindex sftp method ++@cindex sftp (with sftp method) ++@cindex ssh (with sftp method) ++ ++That is mostly the same method as @option{scp}, but using ++@command{sftp} as transfer command. So the same remarks are valid. ++ ++This command does not work like @value{ftppackagename}, where ++@command{ftp} is called interactively, and all commands are send from ++within this session. Instead of, @command{ssh} is used for login. ++ ++This method supports the @samp{-p} hack. ++ ++ ++@item @option{rsync} --- @command{ssh} and @command{rsync} ++@cindex method rsync ++@cindex rsync method ++@cindex rsync (with rsync method) ++@cindex ssh (with rsync method) ++ ++Using the @command{ssh} command to connect securely to the remote ++machine and the @command{rsync} command to transfer files is almost ++identical to the @option{scp} method. ++ ++While @command{rsync} performs much better than @command{scp} when ++transferring files that exist on both hosts, this advantage is lost if ++the file exists only on one side of the connection. ++ ++The @command{rsync} based method may be considerably faster than the ++@command{rcp} based methods when writing to the remote system. Reading ++files to the local machine is no faster than with a direct copy. ++ ++This method supports the @samp{-p} hack. ++ ++ ++@item @option{scpx} --- @command{ssh} and @command{scp} ++@cindex method scpx ++@cindex scpx method ++@cindex scp (with scpx method) ++@cindex ssh (with scpx method) ++ ++As you would expect, this is similar to @option{scp}, only a little ++different. Whereas @option{scp} opens a normal interactive shell on ++the remote host, this option uses @samp{ssh -t -t @var{host} -l ++@var{user} /bin/sh} to open a connection. This is useful for users ++where the normal login shell is set up to ask them a number of ++questions when logging in. This procedure avoids these questions, and ++just gives @value{tramp} a more-or-less `standard' login shell to work ++with. ++ ++This is also useful for Windows users where @command{ssh}, when ++invoked from an @value{emacsname} buffer, tells them that it is not ++allocating a pseudo tty. When this happens, the login shell is wont ++to not print any shell prompt, which confuses @value{tramp} mightily. ++ ++This method supports the @samp{-p} hack. ++ ++ ++@item @option{scpc} --- @command{ssh} and @command{scp} ++@cindex method scpx ++@cindex scpx method ++@cindex scp (with scpx method) ++@cindex ssh (with scpx method) ++ ++Newer versions of @option{ssh} (for example OpenSSH 4) offer an option ++@option{ControlMaster}. This allows @option{scp} to reuse an existing ++@option{ssh} channel, which increases performance. ++ ++Before you use this method, you shall check whether your @option{ssh} ++implementation does support this option. Try from the command line ++ ++@example ++ssh localhost -o ControlMaster=yes ++@end example ++ ++This method supports the @samp{-p} hack. ++ ++ ++@item @option{pscp} --- @command{plink} and @command{pscp} ++@cindex method pscp ++@cindex pscp method ++@cindex pscp (with pscp method) ++@cindex plink (with pscp method) ++@cindex PuTTY (with pscp method) ++ ++This method is similar to @option{scp}, but it uses the ++@command{plink} command to connect to the remote host, and it uses ++@command{pscp} for transferring the files. These programs are part ++of PuTTY, an SSH implementation for Windows. ++ ++This method supports the @samp{-P} hack. ++ ++ ++@item @option{psftp} --- @command{plink} and @command{psftp} ++@cindex method psftp ++@cindex psftp method ++@cindex psftp (with psftp method) ++@cindex plink (with psftp method) ++@cindex PuTTY (with psftp method) ++ ++As you would expect, this method is similar to @option{sftp}, but it ++uses the @command{plink} command to connect to the remote host, and it ++uses @command{psftp} for transferring the files. These programs are ++part of PuTTY, an SSH implementation for Windows. ++ ++This method supports the @samp{-P} hack. ++ ++ ++@item @option{fcp} --- @command{fsh} and @command{fcp} ++@cindex method fcp ++@cindex fcp method ++@cindex fsh (with fcp method) ++@cindex fcp (with fcp method) ++ ++This method is similar to @option{scp}, but it uses the @command{fsh} ++command to connect to the remote host, and it uses @command{fcp} for ++transferring the files. @command{fsh/fcp} are a front-end for ++@command{ssh} which allow for reusing the same @command{ssh} session ++for submitting several commands. This avoids the startup overhead of ++@command{scp} (which has to establish a secure connection whenever it ++is called). Note, however, that you can also use one of the inline ++methods to achieve a similar effect. ++ ++This method uses the command @samp{fsh @var{host} -l @var{user} ++/bin/sh -i} to establish the connection, it does not work to just say ++@command{fsh @var{host} -l @var{user}}. ++ ++@cindex method fsh ++@cindex fsh method ++ ++There is no inline method using @command{fsh} as the multiplexing ++provided by the program is not very useful in our context. @value{tramp} ++opens just one connection to the remote host and then keeps it open, ++anyway. ++ ++ ++@item @option{ftp} ++@cindex method ftp ++@cindex ftp method ++ ++This is not a native @value{tramp} method. Instead of, it forwards all ++requests to @value{ftppackagename}. ++@ifset xemacs ++This works only for unified filenames, see @ref{Issues}. ++@end ifset ++ ++ ++@item @option{smb} --- @command{smbclient} ++@cindex method smb ++@cindex smb method ++ ++This is another not natural @value{tramp} method. It uses the ++@command{smbclient} command on different Unices in order to connect to ++an SMB server. An SMB server might be a Samba (or CIFS) server on ++another UNIX host or, more interesting, a host running MS Windows. So ++far, it is tested towards MS Windows NT, MS Windows 2000, and MS ++Windows XP. ++ ++The first directory in the localname must be a share name on the remote ++host. Remember, that the @code{$} character in which default shares ++usually end, must be written @code{$$} due to environment variable ++substitution in file names. If no share name is given (i.e. remote ++directory @code{/}), all available shares are listed. ++ ++Since authorization is done on share level, you will be prompted ++always for a password if you access another share on the same host. ++This can be suppressed by @ref{Password handling}. ++ ++MS Windows uses for authorization both a user name and a domain name. ++Because of this, the @value{tramp} syntax has been extended: you can ++specify a user name which looks like @code{user%domain} (the real user ++name, then a percent sign, then the domain name). So, to connect to ++the machine @code{melancholia} as user @code{daniel} of the domain ++@code{BIZARRE}, and edit @file{.emacs} in the home directory (share ++@code{daniel$}) I would specify the filename @file{@trampfn{smb, ++daniel%BIZARRE, melancholia, /daniel$$/.emacs}}. ++ ++Depending on the Windows domain configuration, a Windows user might be ++considered as domain user per default. In order to connect as local ++user, the WINS name of that machine must be given as domain name. ++Usually, it is the machine name in capital letters. In the example ++above, the local user @code{daniel} would be specified as ++@file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}. ++ ++The domain name as well as the user name are optional. If no user ++name is specified at all, the anonymous user (without password ++prompting) is assumed. This is different from all other @value{tramp} ++methods, where in such a case the local user name is taken. ++ ++The @option{smb} method supports the @samp{-p} hack. ++ ++@strong{Please note:} If @value{emacsname} runs locally under MS ++Windows, this method isn't available. Instead of, you can use UNC ++file names like @file{//melancholia/daniel$$/.emacs}. The only ++disadvantage is that there's no possibility to specify another user ++name. ++ ++@end table ++ ++ ++@ifset emacsgw ++@node Gateway methods ++@section Gateway methods ++@cindex methods, gateway ++@cindex gateway methods ++ ++Gateway methods are not methods to access a remote host directly. ++These methods are intended to pass firewalls or proxy servers. ++Therefore, they can be used for proxy host declarations ++(@pxref{Multi-hops}) only. ++ ++A gateway method must come always along with a method who supports ++port setting (referred to as @samp{-p} kludge). This is because ++@value{tramp} targets the accompanied method to ++@file{localhost#random_port}, from where the firewall or proxy server ++is accessed to. ++ ++Gateway methods support user name and password declarations. These ++are used to authenticate towards the corresponding firewall or proxy ++server. They can be passed only if your friendly administrator has ++granted your access. ++ ++@table @asis ++@item @option{tunnel} ++@cindex method tunnel ++@cindex tunnel method ++ ++This method implements an HTTP tunnel via the @command{CONNECT} ++command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server ++shall support this command. ++ ++As authentication method, only @option{Basic Authentication} (see RFC ++2617) is implemented so far. If no port number is given in the ++declaration, port @option{8080} is used for the proxy server. ++ ++ ++@item @option{socks} ++@cindex method socks ++@cindex socks method ++ ++The @command{socks} method provides access to SOCKSv5 servers (see ++RFC 1928). @option{Username/Password Authentication} according to RFC ++1929 is supported. ++ ++The default port number of the socks server is @option{1080}, if not ++specified otherwise. ++ ++@end table ++@end ifset ++ ++ ++@node Default Method ++@section Selecting a default method ++@cindex default method ++ ++@vindex tramp-default-method ++When you select an appropriate transfer method for your typical usage ++you should set the variable @code{tramp-default-method} to reflect that ++choice. This variable controls which method will be used when a method ++is not specified in the @value{tramp} file name. For example: ++ ++@lisp ++(setq tramp-default-method "ssh") ++@end lisp ++ ++@vindex tramp-default-method-alist ++You can also specify different methods for certain user/host ++combinations, via the variable @code{tramp-default-method-alist}. For ++example, the following two lines specify to use the @option{ssh} ++method for all user names matching @samp{john} and the @option{rsync} ++method for all host names matching @samp{lily}. The third line ++specifies to use the @option{su} method for the user @samp{root} on ++the machine @samp{localhost}. ++ ++@lisp ++(add-to-list 'tramp-default-method-alist '("" "john" "ssh")) ++(add-to-list 'tramp-default-method-alist '("lily" "" "rsync")) ++(add-to-list 'tramp-default-method-alist ++ '("\\`localhost\\'" "\\`root\\'" "su")) ++@end lisp ++ ++@noindent ++See the documentation for the variable ++@code{tramp-default-method-alist} for more details. ++ ++External methods are normally preferable to inline methods, giving ++better performance. ++ ++@xref{Inline methods}. ++@xref{External methods}. ++ ++Another consideration with the selection of transfer methods is the ++environment you will use them in and, especially when used over the ++Internet, the security implications of your preferred method. ++ ++The @option{rsh} and @option{telnet} methods send your password as ++plain text as you log in to the remote machine, as well as ++transferring the files in such a way that the content can easily be ++read from other machines. ++ ++If you need to connect to remote systems that are accessible from the ++Internet, you should give serious thought to using @option{ssh} based ++methods to connect. These provide a much higher level of security, ++making it a non-trivial exercise for someone to obtain your password ++or read the content of the files you are editing. ++ ++ ++@subsection Which method is the right one for me? ++@cindex choosing the right method ++ ++Given all of the above, you are probably thinking that this is all fine ++and good, but it's not helping you to choose a method! Right you are. ++As a developer, we don't want to boss our users around but give them ++maximum freedom instead. However, the reality is that some users would ++like to have some guidance, so here I'll try to give you this guidance ++without bossing you around. You tell me whether it works @dots{} ++ ++My suggestion is to use an inline method. For large files, external ++methods might be more efficient, but I guess that most people will ++want to edit mostly small files. ++ ++I guess that these days, most people can access a remote machine by ++using @command{ssh}. So I suggest that you use the @option{ssh} ++method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost, ++/etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other ++host. ++ ++If you can't use @option{ssh} to log in to the remote host, then ++select a method that uses a program that works. For instance, Windows ++users might like the @option{plink} method which uses the PuTTY ++implementation of @command{ssh}. Or you use Kerberos and thus like ++@option{krlogin}. ++ ++For the special case of editing files on the local host as another ++user, see the @option{su} or @option{sudo} methods. They offer ++shortened syntax for the @samp{root} account, like ++@file{@trampfn{su, , , /etc/motd}}. ++ ++People who edit large files may want to consider @option{scpc} instead ++of @option{ssh}, or @option{pscp} instead of @option{plink}. These ++external methods are faster than inline methods for large files. ++Note, however, that external methods suffer from some limitations. ++Please try first whether you really get a noticeable speed advantage ++from using an external method! Maybe even for large files, inline ++methods are fast enough. ++ ++ ++@node Default User ++@section Selecting a default user ++@cindex default user ++ ++The user part of a @value{tramp} file name can be omitted. Usually, ++it is replaced by the user name you are logged in. Often, this is not ++what you want. A typical use of @value{tramp} might be to edit some ++files with root permissions on the local host. This case, you should ++set the variable @code{tramp-default-user} to reflect that choice. ++For example: ++ ++@lisp ++(setq tramp-default-user "root") ++@end lisp ++ ++@code{tramp-default-user} is regarded as obsolete, and will be removed ++soon. ++ ++@vindex tramp-default-user-alist ++You can also specify different users for certain method/host ++combinations, via the variable @code{tramp-default-user-alist}. For ++example, if you always have to use the user @samp{john} in the domain ++@samp{somewhere.else}, you can specify the following: ++ ++@lisp ++(add-to-list 'tramp-default-user-alist ++ '("ssh" ".*\\.somewhere\\.else\\'" "john")) ++@end lisp ++ ++@noindent ++See the documentation for the variable ++@code{tramp-default-user-alist} for more details. ++ ++One trap to fall in must be known. If @value{tramp} finds a default ++user, this user will be passed always to the connection command as ++parameter (for example @samp{ssh here.somewhere.else -l john}. If you ++have specified another user for your command in its configuration ++files, @value{tramp} cannot know it, and the remote access will fail. ++If you have specified in the given example in @file{~/.ssh/config} the ++lines ++ ++@example ++Host here.somewhere.else ++ User lily ++@end example ++ ++@noindent ++than you must discard selecting a default user by @value{tramp}. This ++will be done by setting it to @code{nil} (or @samp{lily}, likewise): ++ ++@lisp ++(add-to-list 'tramp-default-user-alist ++ '("ssh" "\\`here\\.somewhere\\.else\\'" nil)) ++@end lisp ++ ++The last entry in @code{tramp-default-user-alist} could be your ++default user you'll apply predominantly. You shall @emph{append} it ++to that list at the end: ++ ++@lisp ++(add-to-list 'tramp-default-user-alist '(nil nil "jonas") t) ++@end lisp ++ ++ ++@node Default Host ++@section Selecting a default host ++@cindex default host ++ ++@vindex tramp-default-host ++Finally, it is even possible to omit the host name part of a ++@value{tramp} file name. This case, the value of the variable ++@code{tramp-default-host} is used. Per default, it is initialized ++with the host name your local @value{emacsname} is running. ++ ++If you, for example, use @value{tramp} mainly to contact the host ++@samp{target} as user @samp{john}, you can specify: ++ ++@lisp ++(setq tramp-default-user "john" ++ tramp-default-host "target") ++@end lisp ++ ++Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you ++to John's home directory on target. ++@ifset emacs ++Note, however, that the most simplification @samp{/::} won't work, ++because @samp{/:} is the prefix for quoted file names. ++@end ifset ++ ++ ++@node Multi-hops ++@section Connecting to a remote host using multiple hops ++@cindex multi-hop ++@cindex proxy hosts ++ ++Sometimes, the methods described before are not sufficient. Sometimes, ++it is not possible to connect to a remote host using a simple command. ++For example, if you are in a secured network, you might have to log in ++to a `bastion host' first before you can connect to the outside world. ++Of course, the target host may also require a bastion host. ++ ++@vindex tramp-default-proxies-alist ++In order to specify such multiple hops, it is possible to define a proxy ++host to pass through, via the variable ++@code{tramp-default-proxies-alist}. This variable keeps a list of ++triples (@var{host} @var{user} @var{proxy}). ++ ++ The first matching item specifies the proxy host to be passed for a ++file name located on a remote target matching @var{user}@@@var{host}. ++@var{host} and @var{user} are regular expressions or @code{nil}, which ++is interpreted as a regular expression which always matches. ++ ++@var{proxy} must be a Tramp filename which localname part is ignored. ++Method and user name on @var{proxy} are optional, which is interpreted ++with the default values. ++@ifset emacsgw ++The method must be an inline or gateway method (@pxref{Inline ++methods}, @pxref{Gateway methods}). ++@end ifset ++@ifclear emacsgw ++The method must be an inline method (@pxref{Inline methods}). ++@end ifclear ++If @var{proxy} is @code{nil}, no additional hop is required reaching ++@var{user}@@@var{host}. ++ ++If you, for example, must pass the host @samp{bastion.your.domain} as ++user @samp{bird} for any remote host which is not located in your local ++domain, you can set ++ ++@lisp ++(add-to-list 'tramp-default-proxies-alist ++ '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}")) ++(add-to-list 'tramp-default-proxies-alist ++ '("\\.your\\.domain\\'" nil nil)) ++@end lisp ++ ++Please note the order of the code. @code{add-to-list} adds elements at the ++beginning of a list. Therefore, most relevant rules must be added last. ++ ++Proxy hosts can be cascaded. If there is another host called ++@samp{jump.your.domain}, which is the only one in your local domain who ++is allowed connecting @samp{bastion.your.domain}, you can add another ++rule: ++ ++@lisp ++(add-to-list 'tramp-default-proxies-alist ++ '("\\`bastion\\.your\\.domain\\'" ++ "\\`bird\\'" ++ "@trampfn{ssh, , jump.your.domain,}")) ++@end lisp ++ ++@var{proxy} can contain the patterns @code{%h} or @code{%u}. These ++patterns are replaced by the strings matching @var{host} or ++@var{user}, respectively. ++ ++If you, for example, wants to work as @samp{root} on hosts in the ++domain @samp{your.domain}, but login as @samp{root} is disabled for ++non-local access, you might add the following rule: ++ ++@lisp ++(add-to-list 'tramp-default-proxies-alist ++ '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}")) ++@end lisp ++ ++Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect ++first @samp{randomhost.your.domain} via @code{ssh} under your account ++name, and perform @code{sudo -u root} on that host afterwards. It is ++important to know that the given method is applied on the host which ++has been reached so far. @code{sudo -u root}, applied on your local ++host, wouldn't be useful here. ++ ++This is the recommended configuration to work as @samp{root} on remote ++Ubuntu hosts. ++ ++@ifset emacsgw ++Finally, @code{tramp-default-proxies-alist} can be used to pass ++firewalls or proxy servers. Imagine your local network has a host ++@samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to ++the outer world. Your friendly administrator has granted you access ++under your user name to @samp{host.other.domain} on that proxy ++server.@footnote{HTTP tunnels are intended for secure SSL/TLS ++communication. Therefore, many proxy server restrict the tunnels to ++related target ports. You might need to run your ssh server on your ++target host @samp{host.other.domain} on such a port, like 443 (https). ++See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall} ++for discussion of ethical issues.} You would need to add the ++following rule: ++ ++@lisp ++(add-to-list 'tramp-default-proxies-alist ++ '("\\`host\\.other\\.domain\\'" nil ++ "@trampfn{tunnel, , proxy.your.domain#3128,}")) ++@end lisp ++ ++Gateway methods can be declared as first hop only in a multiple hop ++chain. ++@end ifset ++ ++ ++@node Customizing Methods ++@section Using Non-Standard Methods ++@cindex customizing methods ++@cindex using non-standard methods ++@cindex create your own methods ++ ++There is a variable @code{tramp-methods} which you can change if the ++predefined methods don't seem right. ++ ++For the time being, I'll refer you to the Lisp documentation of that ++variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. ++ ++ ++@node Customizing Completion ++@section Selecting config files for user/host name completion ++@cindex customizing completion ++@cindex selecting config files ++@vindex tramp-completion-function-alist ++ ++The variable @code{tramp-completion-function-alist} is intended to ++customize which files are taken into account for user and host name ++completion (@pxref{Filename completion}). For every method, it keeps ++a set of configuration files, accompanied by a Lisp function able to ++parse that file. Entries in @code{tramp-completion-function-alist} ++have the form (@var{method} @var{pair1} @var{pair2} ...). ++ ++Each @var{pair} is composed of (@var{function} @var{file}). ++@var{function} is responsible to extract user names and host names ++from @var{file} for completion. There are two functions which access ++this variable: ++ ++@defun tramp-get-completion-function method ++This function returns the list of completion functions for @var{method}. ++ ++Example: ++@example ++(tramp-get-completion-function "rsh") ++ ++ @result{} ((tramp-parse-rhosts "/etc/hosts.equiv") ++ (tramp-parse-rhosts "~/.rhosts")) ++@end example ++@end defun ++ ++@defun tramp-set-completion-function method function-list ++This function sets @var{function-list} as list of completion functions ++for @var{method}. ++ ++Example: ++@example ++(tramp-set-completion-function "ssh" ++ '((tramp-parse-sconfig "/etc/ssh_config") ++ (tramp-parse-sconfig "~/.ssh/config"))) ++ ++ @result{} ((tramp-parse-sconfig "/etc/ssh_config") ++ (tramp-parse-sconfig "~/.ssh/config")) ++@end example ++@end defun ++ ++The following predefined functions parsing configuration files exist: ++ ++@table @asis ++@item @code{tramp-parse-rhosts} ++@findex tramp-parse-rhosts ++ ++This function parses files which are syntactical equivalent to ++@file{~/.rhosts}. It returns both host names and user names, if ++specified. ++ ++@item @code{tramp-parse-shosts} ++@findex tramp-parse-shosts ++ ++This function parses files which are syntactical equivalent to ++@file{~/.ssh/known_hosts}. Since there are no user names specified ++in such files, it can return host names only. ++ ++@item @code{tramp-parse-sconfig} ++@findex tramp-parse-shosts ++ ++This function returns the host nicknames defined by @code{Host} entries ++in @file{~/.ssh/config} style files. ++ ++@item @code{tramp-parse-shostkeys} ++@findex tramp-parse-shostkeys ++ ++SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and ++@file{~/ssh2/hostkeys/*}. Hosts are coded in file names ++@file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names ++are always @code{nil}. ++ ++@item @code{tramp-parse-sknownhosts} ++@findex tramp-parse-shostkeys ++ ++Another SSH2 style parsing of directories like ++@file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This ++case, hosts names are coded in file names ++@file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}. ++ ++@item @code{tramp-parse-hosts} ++@findex tramp-parse-hosts ++ ++A function dedicated to @file{/etc/hosts} style files. It returns ++host names only. ++ ++@item @code{tramp-parse-passwd} ++@findex tramp-parse-passwd ++ ++A function which parses @file{/etc/passwd} like files. Obviously, it ++can return user names only. ++ ++@item @code{tramp-parse-netrc} ++@findex tramp-parse-netrc ++ ++Finally, a function which parses @file{~/.netrc} like files. ++@end table ++ ++If you want to keep your own data in a file, with your own structure, ++you might provide such a function as well. This function must meet ++the following conventions: ++ ++@defun my-tramp-parse file ++@var{file} must be either a file name on your host, or @code{nil}. ++The function must return a list of (@var{user} @var{host}), which are ++taken as candidates for user and host name completion. ++ ++Example: ++@example ++(my-tramp-parse "~/.my-tramp-hosts") ++ ++ @result{} ((nil "toto") ("daniel" "melancholia")) ++@end example ++@end defun ++ ++ ++@node Password handling ++@section Reusing passwords for several connections. ++@cindex passwords ++ ++Sometimes it is necessary to connect to the same remote host several ++times. Reentering passwords again and again would be annoying, when ++the chosen method does not support access without password prompt ++through own configuration. ++ ++The best recommendation is to use the method's own mechanism for ++password handling. Consider @command{ssh-agent} for @option{ssh}-like ++methods, or @command{pageant} for @option{plink}-like methods. ++ ++However, if you cannot apply such native password handling, ++@value{tramp} offers altenatives. ++ ++ ++@anchor{auth-sources} ++@subsection Using an authentication file ++ ++@vindex auth-sources ++The package @file{auth-source.el}, originally developed in No Gnus, ++offers the possibility to read passwords from a file, like FTP does it ++from @file{~/.netrc}. The default authentication file is ++@file{~/.authinfo.gpg}, this can be changed via the variable ++@code{auth-sources}. ++ ++@noindent ++A typical entry in the authentication file would be ++ ++@example ++machine melancholia port scp login daniel password geheim ++@end example ++ ++The port can be any @value{tramp} method (@pxref{Inline methods}, ++@pxref{External methods}), to match only this method. When you omit ++the port, you match all @value{tramp} methods. ++ ++ ++@anchor{password-cache} ++@subsection Caching passwords ++ ++If there is no authentication file, @value{tramp} caches the passwords ++entered by you. They will be reused next time if a connection needs ++them for the same user name and host name, independently of the ++connection method. ++ ++@vindex password-cache-expiry ++Passwords are not saved permanently, that means the password caching ++is limited to the lifetime of your @value{emacsname} session. You ++can influence the lifetime of password caching by customizing the ++variable @code{password-cache-expiry}. The value is the number of ++seconds how long passwords are cached. Setting it to @code{nil} ++disables the expiration. ++ ++@vindex password-cache ++If you don't like this feature for security reasons, password caching ++can be disabled totally by customizing the variable ++@code{password-cache} (setting it to @code{nil}). ++ ++Implementation Note: password caching is based on the package ++@file{password-cache.el}. For the time being, it is activated only ++when this package is seen in the @code{load-path} while loading ++@value{tramp}. ++@ifset installchapter ++If you don't use No Gnus, you can take @file{password.el} from the ++@value{tramp} @file{contrib} directory, see @ref{Installation ++parameters}. ++@end ifset ++ ++ ++@node Connection caching ++@section Reusing connection related information. ++@cindex caching ++ ++@vindex tramp-persistency-file-name ++In order to reduce initial connection time, @value{tramp} stores ++connection related information persistently. The variable ++@code{tramp-persistency-file-name} keeps the file name where these ++information are written. Its default value is ++@ifset emacs ++@file{~/.emacs.d/tramp}. ++@end ifset ++@ifset xemacs ++@file{~/.xemacs/tramp}. ++@end ifset ++It is recommended to choose a local file name. ++ ++@value{tramp} reads this file during startup, and writes it when ++exiting @value{emacsname}. You can simply remove this file if ++@value{tramp} shall be urged to recompute these information next ++@value{emacsname} startup time. ++ ++Using such persistent information can be disabled by setting ++@code{tramp-persistency-file-name} to @code{nil}. ++ ++Once consequence of reusing connection related information is that ++@var{tramp} needs to distinguish hosts. If you, for example, run a ++local @code{sshd} on port 3001, which tunnels @command{ssh} to another ++host, you could access both @file{@trampfn{ssh, , localhost,}} and ++@file{@trampfn{ssh, , localhost#3001,}}. @var{tramp} would use the ++same host related information (like paths, Perl variants, etc) for ++both connections, although the information is valid only for one of ++them. ++ ++In order to avoid trouble, you must use another host name for one of ++the connections, like introducing a @option{Host} section in ++@file{~/.ssh/config} (@pxref{Frequently Asked Questions}) or applying ++multiple hops (@pxref{Multi-hops}). ++ ++When @value{tramp} detects a changed operating system version on a ++remote host (via the command @command{uname -sr}), it flushes all ++connection related information for this host, and opens the ++connection, again. ++ ++ ++@node Remote Programs ++@section How @value{tramp} finds and uses programs on the remote machine. ++ ++@value{tramp} depends on a number of programs on the remote host in order to ++function, including @command{ls}, @command{test}, @command{find} and ++@command{cat}. ++ ++In addition to these required tools, there are various tools that may be ++required based on the connection method. See @ref{Inline methods} and ++@ref{External methods} for details on these. ++ ++Certain other tools, such as @command{perl} (or @command{perl5}) and ++@command{grep} will be used if they can be found. When they are ++available, they are used to improve the performance and accuracy of ++remote file access. ++ ++@vindex tramp-remote-path ++When @value{tramp} connects to the remote machine, it searches for the ++programs that it can use. The variable @code{tramp-remote-path} ++controls the directories searched on the remote machine. ++ ++By default, this is set to a reasonable set of defaults for most ++machines. The symbol @code{tramp-default-remote-path} is a place ++holder, it is replaced by the list of directories received via the ++command @command{getconf PATH} on your remote machine. For example, ++on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is ++@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is ++recommended to apply this symbol on top of @code{tramp-remote-path}. ++ ++It is possible, however, that your local (or remote ;) system ++administrator has put the tools you want in some obscure local ++directory. ++ ++In this case, you can still use them with @value{tramp}. You simply ++need to add code to your @file{.emacs} to add the directory to the ++remote path. This will then be searched by @value{tramp} when you ++connect and the software found. ++ ++To add a directory to the remote search path, you could use code such ++as: ++ ++@lisp ++@i{;; We load @value{tramp} to define the variable.} ++(require 'tramp) ++@i{;; We have @command{perl} in "/usr/local/perl/bin"} ++(add-to-list 'tramp-remote-path "/usr/local/perl/bin") ++@end lisp ++ ++@value{tramp} caches several information, like the Perl binary ++location. The changed remote search path wouldn't affect these ++settings. In order to force @value{tramp} to recompute these values, ++you must exit @value{emacsname}, remove your persistency file ++(@pxref{Connection caching}), and restart @value{emacsname}. ++ ++ ++@node Remote shell setup ++@section Remote shell setup hints ++@cindex remote shell setup ++@cindex @file{.profile} file ++@cindex @file{.login} file ++@cindex shell init files ++ ++As explained in the @ref{Overview} section, @value{tramp} connects to the ++remote host and talks to the shell it finds there. Of course, when you ++log in, the shell executes its init files. Suppose your init file ++requires you to enter the birth date of your mother; clearly @value{tramp} ++does not know this and hence fails to log you in to that host. ++ ++There are different possible strategies for pursuing this problem. One ++strategy is to enable @value{tramp} to deal with all possible situations. ++This is a losing battle, since it is not possible to deal with ++@emph{all} situations. The other strategy is to require you to set up ++the remote host such that it behaves like @value{tramp} expects. This might ++be inconvenient because you have to invest a lot of effort into shell ++setup before you can begin to use @value{tramp}. ++ ++The package, therefore, pursues a combined approach. It tries to ++figure out some of the more common setups, and only requires you to ++avoid really exotic stuff. For example, it looks through a list of ++directories to find some programs on the remote host. And also, it ++knows that it is not obvious how to check whether a file exists, and ++therefore it tries different possibilities. (On some hosts and ++shells, the command @command{test -e} does the trick, on some hosts ++the shell builtin doesn't work but the program @command{/usr/bin/test ++-e} or @command{/bin/test -e} works. And on still other hosts, ++@command{ls -d} is the right way to do this.) ++ ++Below you find a discussion of a few things that @value{tramp} does not deal ++with, and that you therefore have to set up correctly. ++ ++@table @asis ++@item @var{shell-prompt-pattern} ++@vindex shell-prompt-pattern ++ ++After logging in to the remote host, @value{tramp} has to wait for the remote ++shell startup to finish before it can send commands to the remote ++shell. The strategy here is to wait for the shell prompt. In order to ++recognize the shell prompt, the variable @code{shell-prompt-pattern} has ++to be set correctly to recognize the shell prompt on the remote host. ++ ++Note that @value{tramp} requires the match for @code{shell-prompt-pattern} ++to be at the end of the buffer. Many people have something like the ++following as the value for the variable: @code{"^[^>$][>$] *"}. Now ++suppose your shell prompt is @code{a c $ }. In this case, ++@value{tramp} recognizes the @code{>} character as the end of the prompt, ++but it is not at the end of the buffer. ++ ++@item @var{tramp-shell-prompt-pattern} ++@vindex tramp-shell-prompt-pattern ++ ++This regular expression is used by @value{tramp} in the same way as ++@code{shell-prompt-pattern}, to match prompts from the remote shell. ++This second variable exists because the prompt from the remote shell ++might be different from the prompt from a local shell --- after all, ++the whole point of @value{tramp} is to log in to remote hosts as a ++different user. The default value of ++@code{tramp-shell-prompt-pattern} is the same as the default value of ++@code{shell-prompt-pattern}, which is reported to work well in many ++circumstances. ++ ++@item @var{tramp-password-prompt-regexp} ++@vindex tramp-password-prompt-regexp ++@vindex tramp-wrong-passwd-regexp ++ ++During login, @value{tramp} might be forced to enter a password or a ++passphrase. The difference between both is that a password is ++requested from the shell on the remote host, while a passphrase is ++needed for accessing local authentication information, like your ssh ++key. ++ ++@var{tramp-password-prompt-regexp} handles the detection of such ++requests for English environments. When you use another localization ++of your (local or remote) host, you might need to adapt this. Example: ++ ++@lisp ++(setq ++ tramp-password-prompt-regexp ++ (concat ++ "^.*" ++ (regexp-opt ++ '("passphrase" "Passphrase" ++ ;; English ++ "password" "Password" ++ ;; Deutsch ++ "passwort" "Passwort" ++ ;; Fran@,{c}ais ++ "mot de passe" "Mot de passe") t) ++ ".*:? *")) ++@end lisp ++ ++In parallel, it might also be necessary to adapt ++@var{tramp-wrong-passwd-regexp}. ++ ++@item @command{tset} and other questions ++@cindex Unix command tset ++@cindex tset Unix command ++ ++Some people invoke the @command{tset} program from their shell startup ++scripts which asks the user about the terminal type of the shell. ++Maybe some shells ask other questions when they are started. ++@value{tramp} does not know how to answer these questions. There are ++two approaches for dealing with this problem. One approach is to take ++care that the shell does not ask any questions when invoked from ++@value{tramp}. You can do this by checking the @code{TERM} ++environment variable, it will be set to @code{dumb} when connecting. ++ ++@vindex tramp-terminal-type ++The variable @code{tramp-terminal-type} can be used to change this value ++to @code{dumb}. ++ ++@vindex tramp-actions-before-shell ++The other approach is to teach @value{tramp} about these questions. See ++the variable @code{tramp-actions-before-shell}. Example: ++ ++@lisp ++(defconst my-tramp-prompt-regexp ++ (concat (regexp-opt '("Enter the birth date of your mother:") t) ++ "\\s-*") ++ "Regular expression matching my login prompt question.") ++ ++(defun my-tramp-action (proc vec) ++ "Enter \"19000101\" in order to give a correct answer." ++ (save-window-excursion ++ (with-current-buffer (tramp-get-connection-buffer vec) ++ (tramp-message vec 6 "\n%s" (buffer-string)) ++ (tramp-send-string vec "19000101")))) ++ ++(add-to-list 'tramp-actions-before-shell ++ '(my-tramp-prompt-regexp my-tramp-action)) ++@end lisp ++ ++ ++@item Environment variables named like users in @file{.profile} ++ ++If you have a user named frumple and set the variable @code{FRUMPLE} in ++your shell environment, then this might cause trouble. Maybe rename ++the variable to @code{FRUMPLE_DIR} or the like. ++ ++This weird effect was actually reported by a @value{tramp} user! ++ ++ ++@item Non-Bourne commands in @file{.profile} ++ ++After logging in to the remote host, @value{tramp} issues the command ++@command{exec /bin/sh}. (Actually, the command is slightly ++different.) When @command{/bin/sh} is executed, it reads some init ++files, such as @file{~/.shrc} or @file{~/.profile}. ++ ++Now, some people have a login shell which is not @code{/bin/sh} but a ++Bourne-ish shell such as bash or ksh. Some of these people might put ++their shell setup into the files @file{~/.shrc} or @file{~/.profile}. ++This way, it is possible for non-Bourne constructs to end up in those ++files. Then, @command{exec /bin/sh} might cause the Bourne shell to ++barf on those constructs. ++ ++As an example, imagine somebody putting @command{export FOO=bar} into ++the file @file{~/.profile}. The standard Bourne shell does not ++understand this syntax and will emit a syntax error when it reaches ++this line. ++ ++Another example is the tilde (@code{~}) character, say when adding ++@file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this ++character, and since there is usually no directory whose name consists ++of the single character tilde, strange things will happen. ++ ++What can you do about this? ++ ++Well, one possibility is to make sure that everything in ++@file{~/.shrc} and @file{~/.profile} on all remote hosts is ++Bourne-compatible. In the above example, instead of @command{export ++FOO=bar}, you might use @command{FOO=bar; export FOO} instead. ++ ++The other possibility is to put your non-Bourne shell setup into some ++other files. For example, bash reads the file @file{~/.bash_profile} ++instead of @file{~/.profile}, if the former exists. So bash ++aficionados just rename their @file{~/.profile} to ++@file{~/.bash_profile} on all remote hosts, and Bob's your uncle. ++ ++The @value{tramp} developers would like to circumvent this problem, so ++if you have an idea about it, please tell us. However, we are afraid ++it is not that simple: before saying @command{exec /bin/sh}, ++@value{tramp} does not know which kind of shell it might be talking ++to. It could be a Bourne-ish shell like ksh or bash, or it could be a ++csh derivative like tcsh, or it could be zsh, or even rc. If the ++shell is Bourne-ish already, then it might be prudent to omit the ++@command{exec /bin/sh} step. But how to find out if the shell is ++Bourne-ish? ++ ++@end table ++ ++ ++@node Auto-save and Backup ++@section Auto-save and Backup configuration ++@cindex auto-save ++@cindex backup ++@ifset emacs ++@vindex backup-directory-alist ++@end ifset ++@ifset xemacs ++@vindex bkup-backup-directory-info ++@end ifset ++ ++Normally, @value{emacsname} writes backup files to the same directory ++as the original files, but this behavior can be changed via the ++variable ++@ifset emacs ++@code{backup-directory-alist}. ++@end ifset ++@ifset xemacs ++@code{bkup-backup-directory-info}. ++@end ifset ++In connection with @value{tramp}, this can have unexpected side ++effects. Suppose that you specify that all backups should go to the ++directory @file{~/.emacs.d/backups/}, and then you edit the file ++@file{@trampfn{su, root, localhost, /etc/secretfile}}. The effect is ++that the backup file will be owned by you and not by root, thus ++possibly enabling others to see it even if they were not intended to ++see it. ++ ++When ++@ifset emacs ++@code{backup-directory-alist} ++@end ifset ++@ifset xemacs ++@code{bkup-backup-directory-info} ++@end ifset ++is @code{nil} (the default), such problems do not occur. ++ ++Therefore, it is useful to set special values for @value{tramp} ++files. For example, the following statement effectively `turns off' ++the effect of ++@ifset emacs ++@code{backup-directory-alist} ++@end ifset ++@ifset xemacs ++@code{bkup-backup-directory-info} ++@end ifset ++for @value{tramp} files: ++ ++@ifset emacs ++@lisp ++(add-to-list 'backup-directory-alist ++ (cons tramp-file-name-regexp nil)) ++@end lisp ++@end ifset ++@ifset xemacs ++@lisp ++(require 'backup-dir) ++(add-to-list 'bkup-backup-directory-info ++ (list tramp-file-name-regexp "")) ++@end lisp ++@end ifset ++ ++Another possibility is to use the @value{tramp} variable ++@ifset emacs ++@code{tramp-backup-directory-alist}. ++@end ifset ++@ifset xemacs ++@code{tramp-bkup-backup-directory-info}. ++@end ifset ++This variable has the same meaning like ++@ifset emacs ++@code{backup-directory-alist}. ++@end ifset ++@ifset xemacs ++@code{bkup-backup-directory-info}. ++@end ifset ++If a @value{tramp} file is backed up, and DIRECTORY is an absolute ++local file name, DIRECTORY is prepended with the @value{tramp} file ++name prefix of the file to be backed up. ++ ++@noindent ++Example: ++ ++@ifset emacs ++@lisp ++(add-to-list 'backup-directory-alist ++ (cons "." "~/.emacs.d/backups/")) ++(setq tramp-backup-directory-alist backup-directory-alist) ++@end lisp ++@end ifset ++@ifset xemacs ++@lisp ++(require 'backup-dir) ++(add-to-list 'bkup-backup-directory-info ++ (list "." "~/.emacs.d/backups/" 'full-path)) ++(setq tramp-bkup-backup-directory-info bkup-backup-directory-info) ++@end lisp ++@end ifset ++ ++@noindent ++The backup file name of @file{@trampfn{su, root, localhost, ++/etc/secretfile}} would be ++@ifset emacs ++@file{@trampfn{su, root, localhost, ++~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}} ++@end ifset ++@ifset xemacs ++@file{@trampfn{su, root, localhost, ++~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}} ++@end ifset ++ ++The same problem can happen with auto-saving files. ++@ifset emacs ++Since @value{emacsname} 21, the variable ++@code{auto-save-file-name-transforms} keeps information, on which ++directory an auto-saved file should go. By default, it is initialized ++for @value{tramp} files to the local temporary directory. ++ ++On some versions of @value{emacsname}, namely the version built for ++Debian GNU/Linux, the variable @code{auto-save-file-name-transforms} ++contains the directory where @value{emacsname} was built. A ++workaround is to manually set the variable to a sane value. ++ ++If auto-saved files should go into the same directory as the original ++files, @code{auto-save-file-name-transforms} should be set to @code{nil}. ++ ++Another possibility is to set the variable ++@code{tramp-auto-save-directory} to a proper value. ++@end ifset ++@ifset xemacs ++For this purpose you can set the variable @code{auto-save-directory} ++to a proper value. ++@end ifset ++ ++ ++@node Windows setup hints ++@section Issues with Cygwin ssh ++@cindex Cygwin, issues ++ ++This section needs a lot of work! Please help. ++ ++@cindex method sshx with Cygwin ++@cindex sshx method with Cygwin ++The recent Cygwin installation of @command{ssh} works only with a ++Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x ++eshell}, and starting @kbd{ssh test.machine}. The problem is evident ++if you see a message like this: ++ ++@example ++Pseudo-terminal will not be allocated because stdin is not a terminal. ++@end example ++ ++Older @command{ssh} versions of Cygwin are told to cooperate with ++@value{tramp} selecting @option{sshx} as the connection method. You ++can find information about setting up Cygwin in their FAQ at ++@uref{http://cygwin.com/faq/}. ++ ++@cindex method scpx with Cygwin ++@cindex scpx method with Cygwin ++If you wish to use the @option{scpx} connection method, then you might ++have the problem that @value{emacsname} calls @command{scp} with a ++Windows filename such as @code{c:/foo}. The Cygwin version of ++@command{scp} does not know about Windows filenames and interprets ++this as a remote filename on the host @code{c}. ++ ++One possible workaround is to write a wrapper script for @option{scp} ++which converts the Windows filename to a Cygwinized filename. ++ ++@cindex Cygwin and ssh-agent ++@cindex SSH_AUTH_SOCK and @value{emacsname} on Windows ++If you want to use either @option{ssh} based method on Windows, then ++you might encounter problems with @command{ssh-agent}. Using this ++program, you can avoid typing the pass-phrase every time you log in. ++However, if you start @value{emacsname} from a desktop shortcut, then ++the environment variable @code{SSH_AUTH_SOCK} is not set and so ++@value{emacsname} and thus @value{tramp} and thus @command{ssh} and ++@command{scp} started from @value{tramp} cannot communicate with ++@command{ssh-agent}. It works better to start @value{emacsname} from ++the shell. ++ ++If anyone knows how to start @command{ssh-agent} under Windows in such a ++way that desktop shortcuts can profit, please holler. I don't really ++know anything at all about Windows@dots{} ++ ++ ++@node Usage ++@chapter Using @value{tramp} ++@cindex using @value{tramp} ++ ++Once you have installed @value{tramp} it will operate fairly ++transparently. You will be able to access files on any remote machine ++that you can log in to as though they were local. ++ ++Files are specified to @value{tramp} using a formalized syntax specifying the ++details of the system to connect to. This is similar to the syntax used ++by the @value{ftppackagename} package. ++ ++@cindex type-ahead ++Something that might happen which surprises you is that ++@value{emacsname} remembers all your keystrokes, so if you see a ++password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}} ++twice instead of once, then the second keystroke will be processed by ++@value{emacsname} after @value{tramp} has done its thing. Why, this ++type-ahead is normal behavior, you say. Right you are, but be aware ++that opening a remote file might take quite a while, maybe half a ++minute when a connection needs to be opened. Maybe after half a ++minute you have already forgotten that you hit that key! ++ ++@menu ++* Filename Syntax:: @value{tramp} filename conventions. ++* Alternative Syntax:: URL-like filename syntax. ++* Filename completion:: Filename completion. ++* Remote processes:: Integration with other @value{emacsname} packages. ++* Cleanup remote connections:: Cleanup remote connections. ++@end menu ++ ++ ++@node Filename Syntax ++@section @value{tramp} filename conventions ++@cindex filename syntax ++@cindex filename examples ++ ++To access the file @var{localname} on the remote machine @var{machine} ++you would specify the filename @file{@trampfn{, , machine, ++localname}}. This will connect to @var{machine} and transfer the file ++using the default method. @xref{Default Method}. ++ ++Some examples of @value{tramp} filenames are shown below. ++ ++@table @file ++@item @trampfn{, , melancholia, .emacs} ++Edit the file @file{.emacs} in your home directory on the machine ++@code{melancholia}. ++ ++@item @trampfn{, , melancholia.danann.net, .emacs} ++This edits the same file, using the fully qualified domain name of ++the machine. ++ ++@item @trampfn{, , melancholia, ~/.emacs} ++This also edits the same file --- the @file{~} is expanded to your ++home directory on the remote machine, just like it is locally. ++ ++@item @trampfn{, , melancholia, ~daniel/.emacs} ++This edits the file @file{.emacs} in the home directory of the user ++@code{daniel} on the machine @code{melancholia}. The @file{~} ++construct is expanded to the home directory of that user on the remote ++machine. ++ ++@item @trampfn{, , melancholia, /etc/squid.conf} ++This edits the file @file{/etc/squid.conf} on the machine ++@code{melancholia}. ++ ++@end table ++ ++@var{machine} can also be an IPv4 or IPv6 address, like in ++@file{@trampfn{, , 127.0.0.1, .emacs}} or @file{@trampfn{, , ++@value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}. ++@ifset emacs ++For syntactical reasons, IPv6 addresses must be embedded in square ++brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}. ++@end ifset ++ ++Unless you specify a different name to use, @value{tramp} will use the ++current local user name as the remote user name to log in with. If you ++need to log in as a different user, you can specify the user name as ++part of the filename. ++ ++To log in to the remote machine as a specific user, you use the syntax ++@file{@trampfn{, user, machine, path/to.file}}. That means that ++connecting to @code{melancholia} as @code{daniel} and editing ++@file{.emacs} in your home directory you would specify ++@file{@trampfn{, daniel, melancholia, .emacs}}. ++ ++It is also possible to specify other file transfer methods ++(@pxref{Inline methods}, @pxref{External methods}) as part of the ++filename. ++@ifset emacs ++This is done by putting the method before the user and host name, as ++in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the ++trailing colon). ++@end ifset ++@ifset xemacs ++This is done by replacing the initial @file{@value{prefix}} with ++@file{@value{prefix}@value{postfixhop}}. (Note the trailing ++slash!). ++@end ifset ++The user, machine and file specification remain the same. ++ ++So, to connect to the machine @code{melancholia} as @code{daniel}, ++using the @option{ssh} method to transfer files, and edit ++@file{.emacs} in my home directory I would specify the filename ++@file{@trampfn{ssh, daniel, melancholia, .emacs}}. ++ ++ ++@node Alternative Syntax ++@section URL-like filename syntax ++@cindex filename syntax ++@cindex filename examples ++ ++Additionally to the syntax described in the previous chapter, it is ++possible to use a URL-like syntax for @value{tramp}. This can be ++switched on by customizing the variable @code{tramp-syntax}. Please ++note that this feature is experimental for the time being. ++ ++The variable @code{tramp-syntax} must be set before requiring @value{tramp}: ++ ++@lisp ++(setq tramp-syntax 'url) ++(require 'tramp) ++@end lisp ++ ++Then, a @value{tramp} filename would look like this: ++@file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}. ++@file{/@var{method}://} is mandatory, all other parts are optional. ++@file{:@var{port}} is useful for methods only who support this. ++ ++The last example from the previous section would look like this: ++@file{/ssh://daniel@@melancholia/.emacs}. ++ ++For the time being, @code{tramp-syntax} can have the following values: ++ ++@itemize @w{} ++@ifset emacs ++@item @code{ftp} -- That is the default syntax ++@item @code{url} -- URL-like syntax ++@end ifset ++@ifset xemacs ++@item @code{sep} -- That is the default syntax ++@item @code{url} -- URL-like syntax ++@item @code{ftp} -- EFS-like syntax ++@end ifset ++@end itemize ++ ++ ++@node Filename completion ++@section Filename completion ++@cindex filename completion ++ ++Filename completion works with @value{tramp} for completion of method ++names, of user names and of machine names as well as for completion of ++file names on remote machines. ++@ifset emacs ++In order to enable this, Partial Completion mode must be set on. ++@ifinfo ++@xref{Completion Options, , , @value{emacsdir}}. ++@end ifinfo ++@end ifset ++ ++If you, for example, type @kbd{C-x C-f @value{prefix}t ++@key{TAB}}, @value{tramp} might give you as result the choice for ++ ++@example ++@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}} ++@ifset emacs ++@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/ ++@item @value{prefixhop}toto@value{postfix} @tab ++@end ifset ++@ifset xemacs ++@item @value{prefixhop}telnet@value{postfixhop} @tab @value{prefixhop}toto@value{postfix} ++@end ifset ++@end multitable ++@end example ++ ++@samp{@value{prefixhop}telnet@value{postfixhop}} ++is a possible completion for the respective method, ++@ifset emacs ++@samp{tmp/} stands for the directory @file{/tmp} on your local ++machine, ++@end ifset ++and @samp{@value{prefixhop}toto@value{postfix}} ++might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts} ++file (given you're using default method @option{ssh}). ++ ++If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to ++@samp{@value{prefix}telnet@value{postfixhop}}. ++Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in ++your @file{/etc/hosts} file, let's say ++ ++@example ++@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}} ++@item @trampfn{telnet, , 127.0.0.1,} @tab @trampfn{telnet, , 192.168.0.1,} ++@item @trampfn{telnet, , @value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet, , localhost,} ++@item @trampfn{telnet, , melancholia.danann.net,} @tab @trampfn{telnet, , melancholia,} ++@end multitable ++@end example ++ ++Now you can choose the desired machine, and you can continue to ++complete file names on that machine. ++ ++If the configuration files (@pxref{Customizing Completion}), which ++@value{tramp} uses for analysis of completion, offer user names, those user ++names will be taken into account as well. ++ ++Remote machines, which have been visited in the past and kept ++persistently (@pxref{Connection caching}), will be offered too. ++ ++Once the remote machine identification is completed, it comes to ++filename completion on the remote host. This works pretty much like ++for files on the local host, with the exception that minibuffer ++killing via a double-slash works only on the filename part, except ++that filename part starts with @file{//}. ++@ifset emacs ++A triple-slash stands for the default behavior. ++@end ifset ++@ifinfo ++@xref{Minibuffer File, , , @value{emacsdir}}. ++@end ifinfo ++ ++@noindent ++Example: ++ ++@example ++@ifset emacs ++@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//etc} @key{TAB}} ++ @print{} @trampfn{telnet, , melancholia, /etc} ++ ++@kbd{C-x C-f @trampfn{telnet, , melancholia, //etc} @key{TAB}} ++ @print{} /etc ++ ++@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin///etc} @key{TAB}} ++ @print{} /etc ++@end ifset ++ ++@ifset xemacs ++@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//}} ++ @print{} @trampfn{telnet, , melancholia, /} ++ ++@kbd{C-x C-f @trampfn{telnet, , melancholia, //}} ++ @print{} / ++@end ifset ++@end example ++ ++A remote directory might have changed its contents out of ++@value{emacsname} control, for example by creation or deletion of ++files by other processes. Therefore, during filename completion the ++remote directory contents is reread regularly in order to detect such ++changes, which would be invisible otherwise (@pxref{Connection caching}). ++ ++@defopt tramp-completion-reread-directory-timeout ++This variable defines the number of seconds since last remote command ++before rereading a directory contents. A value of 0 would require an ++immediate reread during filename completion, @code{nil} means to use ++always cached values for the directory contents. ++@end defopt ++ ++ ++@node Remote processes ++@section Integration with other @value{emacsname} packages. ++@cindex compile ++@cindex recompile ++ ++@value{tramp} supports running processes on a remote host. This ++allows to exploit @value{emacsname} packages without modification for ++remote file names. It does not work for the @option{ftp} and ++@option{smb} methods. ++ ++Remote processes are started when a corresponding command is executed ++from a buffer belonging to a remote file or directory. Up to now, the ++packages @file{compile.el} (commands like @code{compile} and ++@code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}) have been ++integrated. Integration of further packages is planned, any help for ++this is welcome! ++ ++When your program is not found in the default search path ++@value{tramp} sets on the remote machine, you should either use an ++absolute path, or extend @code{tramp-remote-path} (see @ref{Remote ++Programs}): ++ ++@lisp ++(add-to-list 'tramp-remote-path "~/bin") ++(add-to-list 'tramp-remote-path "/appli/pub/bin") ++@end lisp ++ ++The environment for your program can be adapted by customizing ++@code{tramp-remote-process-environment}. This variable is a list of ++strings. It is structured like @code{process-environment}. Each ++element is a string of the form ENVVARNAME=VALUE. An entry ++ENVVARNAME= disables the corresponding environment variable, which ++might have been set in your init file like @file{~/.profile}. ++ ++@noindent ++Adding an entry can be performed via @code{add-to-list}: ++ ++@lisp ++(add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java") ++@end lisp ++ ++Changing or removing an existing entry is not encouraged. The default ++values are chosen for proper @value{tramp} work. Nevertheless, if for ++example a paranoid system administrator disallows changing the ++@var{$HISTORY} environment variable, you can customize ++@code{tramp-remote-process-environment}, or you can apply the ++following code in your @file{.emacs}: ++ ++@lisp ++(let ((process-environment tramp-remote-process-environment)) ++ (setenv "HISTORY" nil) ++ (setq tramp-remote-process-environment process-environment)) ++@end lisp ++ ++If you use other @value{emacsname} packages which do not run ++out-of-the-box on a remote host, please let us know. We will try to ++integrate them as well. @xref{Bug Reports}. ++ ++ ++@subsection Running shell-command on a remote host ++@cindex shell-command ++ ++@code{shell-command} allows to execute commands in a shell, either ++synchronously, either asynchronously. This works also on remote ++hosts. Example: ++ ++@example ++@kbd{C-x C-f @trampfn{sudo, , , } @key{RET}} ++@kbd{M-! tail -f /var/log/syslog.log & @key{RET}} ++@end example ++ ++You will see the buffer @file{*Async Shell Command*}, containing the ++continous output of the @command{tail} command. ++ ++ ++@subsection Running eshell on a remote host ++@cindex eshell ++ ++@value{tramp} is integrated into @file{eshell.el}. That is, you can ++open an interactive shell on your remote host, and run commands there. ++After you have started @code{eshell}, you could perform commands like ++this: ++ ++@example ++@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET} ++@b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET} ++host ++@b{@trampfn{sudo, root, host, /etc} $} id @key{RET} ++uid=0(root) gid=0(root) groups=0(root) ++@b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET} ++# ++@b{@trampfn{sudo, root, host, /etc} $} ++@end example ++ ++ ++@anchor{Running a debugger on a remote host} ++@subsection Running a debugger on a remote host ++@cindex gud ++@cindex gdb ++@cindex perldb ++ ++@file{gud.el} offers an unified interface to several symbolic ++debuggers ++@ifset emacs ++@ifinfo ++(@ref{Debuggers, , , @value{emacsdir}}). ++@end ifinfo ++@end ifset ++With @value{tramp}, it is possible to debug programs on ++remote hosts. You can call @code{gdb} with a remote file name: ++ ++@example ++@kbd{M-x gdb @key{RET}} ++@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET} ++@end example ++ ++The file name can also be relative to a remote default directory. ++Given you are in a buffer that belongs to the remote directory ++@trampfn{ssh, , host, /home/user}, you could call ++ ++@example ++@kbd{M-x perldb @key{RET}} ++@b{Run perldb (like this):} perl -d myprog.pl @key{RET} ++@end example ++ ++It is not possible to use just the absolute local part of a remote ++file name as program to debug, like @kbd{perl -d ++/home/user/myprog.pl}, though. ++ ++Arguments of the program to be debugged are taken literally. That ++means, file names as arguments must be given as ordinary relative or ++absolute file names, without any remote specification. ++ ++ ++@node Cleanup remote connections ++@section Cleanup remote connections. ++@cindex cleanup ++ ++Sometimes it is useful to cleanup remote connections. The following ++commands support this. ++ ++@deffn Command tramp-cleanup-connection vec ++This command flushes all connection related objects. @option{vec} is ++the internal representation of a remote connection. Called ++interactively, the command offers all active remote connections in the ++minibuffer as remote file name prefix like @file{@trampfn{method, ++user, host, }}. The cleanup includes password cache (@pxref{Password ++handling}), file cache, connection cache (@pxref{Connection caching}), ++connection buffers. ++@end deffn ++ ++@deffn Command tramp-cleanup-all-connections ++This command flushes objects for all active remote connections. The ++same objects are removed as in @code{tramp-cleanup-connection}. ++@end deffn ++ ++@deffn Command tramp-cleanup-all-buffers ++Like in @code{tramp-cleanup-all-connections}, all remote connections ++are cleaned up. Additionally all buffers, which are related to a ++remote connection, are killed. ++@end deffn ++ ++ ++@node Bug Reports ++@chapter Reporting Bugs and Problems ++@cindex bug reports ++ ++Bugs and problems with @value{tramp} are actively worked on by the ++development team. Feature requests and suggestions are also more than ++welcome. ++ ++The @value{tramp} mailing list is a great place to get information on ++working with @value{tramp}, solving problems and general discussion ++and advice on topics relating to the package. It is moderated so ++non-subscribers can post but messages will be delayed, possibly up to ++48 hours (or longer in case of holidays), until the moderator approves ++your message. ++ ++The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to ++this address go to all the subscribers. This is @emph{not} the address ++to send subscription requests to. ++ ++Subscribing to the list is performed via ++@uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/, ++the @value{tramp} Mail Subscription Page}. ++ ++@findex tramp-bug ++To report a bug in @value{tramp}, you should execute @kbd{M-x ++tramp-bug}. This will automatically generate a buffer with the details ++of your system and @value{tramp} version. ++ ++When submitting a bug report, please try to describe in excruciating ++detail the steps required to reproduce the problem, the setup of the ++remote machine and any special conditions that exist. You should also ++check that your problem is not described already in @xref{Frequently ++Asked Questions}. ++ ++If you can identify a minimal test case that reproduces the problem, ++include that with your bug report. This will make it much easier for ++the development team to analyze and correct the problem. ++ ++Before reporting the bug, you should set the verbosity level to 6 ++(@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and ++repeat the bug. Then, include the contents of the @file{*tramp/foo*} ++and @file{*debug tramp/foo*} buffers in your bug report. A verbosity ++level greater than 6 will produce a very huge debug buffer, which is ++mostly not necessary for the analysis. ++ ++Please be aware that, with a verbosity level of 6 or greater, the ++contents of files and directories will be included in the debug ++buffer. Passwords you've typed will never be included there. ++ ++ ++@node Frequently Asked Questions ++@chapter Frequently Asked Questions ++@cindex frequently asked questions ++@cindex FAQ ++ ++@itemize @bullet ++@item ++Where can I get the latest @value{tramp}? ++ ++@value{tramp} is available under the URL below. ++ ++@noindent ++@uref{ftp://ftp.gnu.org/gnu/tramp/} ++ ++@noindent ++There is also a Savannah project page. ++ ++@noindent ++@uref{http://savannah.gnu.org/projects/tramp/} ++ ++ ++@item ++Which systems does it work on? ++ ++The package has been used successfully on GNU Emacs 21, GNU Emacs 22 ++and XEmacs 21 (starting with 21.4). Gateway methods are supported for ++GNU Emacs 22 only. ++ ++The package was intended to work on Unix, and it really expects a ++Unix-like system on the remote end (except the @option{smb} method), ++but some people seemed to have some success getting it to work on MS ++Windows NT/2000/XP @value{emacsname}. ++ ++There is some informations on @value{tramp} on NT at the following URL; ++many thanks to Joe Stoy for providing the information: ++@uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/} ++ ++@c The link is broken. I've contacted Tom for clarification. Michael. ++@ignore ++The above mostly contains patches to old ssh versions; Tom Roche has a ++Web page with instructions: ++@uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html} ++@end ignore ++ ++@item ++How could I speed up @value{tramp}? ++ ++In the backstage, @value{tramp} needs a lot of operations on the ++remote host. The time for transferring data from and to the remote ++host as well as the time needed to perform the operations there count. ++In order to speed up @value{tramp}, one could either try to avoid some ++of the operations, or one could try to improve their performance. ++ ++Use an external method, like @option{scpc}. ++ ++Use caching. This is already enabled by default. Information about ++the remote host as well as the remote files are cached for reuse. The ++information about remote hosts is kept in the file specified in ++@code{tramp-persistency-file-name}. Keep this file. ++ ++Disable version control. If you access remote files which are not ++under version control, a lot of check operations can be avoided by ++disabling VC. This can be achieved by ++ ++@lisp ++(setq vc-handled-backends nil) ++@end lisp ++ ++Disable excessive traces. The default trace level of @value{tramp}, ++defined in the variable @code{tramp-verbose}, is 3. You should ++increase this level only temporarily, hunting bugs. ++ ++ ++@item ++@value{tramp} does not connect to the remote host ++ ++When @value{tramp} does not connect to the remote host, there are two ++reasons heading the bug mailing list: ++ ++@itemize @minus ++ ++@item ++Unknown characters in the prompt ++ ++@value{tramp} needs to recognize the prompt on the remote machine ++after execution any command. This is not possible, when the prompt ++contains unknown characters like escape sequences for coloring. This ++should be avoided on the remote side. @xref{Remote shell setup}. for ++setting the regular expression detecting the prompt. ++ ++You can check your settings after an unsuccessful connection by ++switching to the @value{tramp} connection buffer @file{*tramp/foo*}, ++setting the cursor at the top of the buffer, and applying the expression ++ ++@example ++@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))} ++@end example ++ ++If it fails, or the cursor is not moved at the end of the buffer, your ++prompt is not recognized correctly. ++ ++A special problem is the zsh, which uses left-hand side and right-hand ++side prompts in parallel. Therefore, it is necessary to disable the ++zsh line editor on the remote host. You shall add to @file{~/.zshrc} ++the following command: ++ ++@example ++[ $TERM = "dumb" ] && unsetopt zle && PS1='$ ' ++@end example ++ ++ ++@item ++@value{tramp} doesn't transfer strings with more than 500 characters ++correctly ++ ++On some few systems, the implementation of @code{process-send-string} ++seems to be broken for longer strings. It is reported for HP-UX, ++FreeBSD and Tru64 Unix, for example. This case, you should customize ++the variable @code{tramp-chunksize} to 500. For a description how to ++determine whether this is necessary see the documentation of ++@code{tramp-chunksize}. ++ ++Additionally, it will be useful to set @code{file-precious-flag} to ++@code{t} for @value{tramp} files. Then the file contents will be ++written into a temporary file first, which is checked for correct ++checksum. ++@ifinfo ++@pxref{Saving Buffers, , , elisp} ++@end ifinfo ++ ++@lisp ++(add-hook ++ 'find-file-hooks ++ '(lambda () ++ (when (file-remote-p default-directory) ++ (set (make-local-variable 'file-precious-flag) t)))) ++@end lisp ++ ++@end itemize ++ ++ ++@item ++File name completion does not work with @value{tramp} ++ ++When you log in to the remote machine, do you see the output of ++@command{ls} in color? If so, this may be the cause of your problems. ++ ++@command{ls} outputs @acronym{ANSI} escape sequences that your terminal ++emulator interprets to set the colors. These escape sequences will ++confuse @value{tramp} however. ++ ++In your @file{.bashrc}, @file{.profile} or equivalent on the remote ++machine you probably have an alias configured that adds the option ++@option{--color=yes} or @option{--color=auto}. ++ ++You should remove that alias and ensure that a new login @emph{does not} ++display the output of @command{ls} in color. If you still cannot use ++filename completion, report a bug to the @value{tramp} developers. ++ ++ ++@item ++File name completion does not work in large directories ++ ++@value{tramp} uses globbing for some operations. (Globbing means to use the ++shell to expand wildcards such as `*.c'.) This might create long ++command lines, especially in directories with many files. Some shells ++choke on long command lines, or don't cope well with the globbing ++itself. ++ ++If you have a large directory on the remote end, you may wish to execute ++a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs. ++Note that you must first start the right shell, which might be ++@command{/bin/sh}, @command{ksh} or @command{bash}, depending on which ++of those supports tilde expansion. ++ ++ ++@item ++How can I get notified when @value{tramp} file transfers are complete? ++ ++The following snippet can be put in your @file{~/.emacs} file. It ++makes @value{emacsname} beep after reading from or writing to the ++remote host. ++ ++@lisp ++(defadvice tramp-handle-write-region ++ (after tramp-write-beep-advice activate) ++ "Make tramp beep after writing a file." ++ (interactive) ++ (beep)) ++ ++(defadvice tramp-handle-do-copy-or-rename-file ++ (after tramp-copy-beep-advice activate) ++ "Make tramp beep after copying a file." ++ (interactive) ++ (beep)) ++ ++(defadvice tramp-handle-insert-file-contents ++ (after tramp-insert-beep-advice activate) ++ "Make tramp beep after inserting a file." ++ (interactive) ++ (beep)) ++@end lisp ++ ++ ++@ifset emacs ++@item ++I'ld like to get a Visual Warning when working in a sudo:ed context ++ ++When you are working with @samp{root} privileges, it might be useful ++to get an indication in the buffer's modeline. The following code, ++tested with @value{emacsname} 22.1, does the job. You should put it ++into your @file{~/.emacs}: ++ ++@lisp ++(defun my-mode-line-function () ++ (when (string-match "^/su\\(do\\)?:" default-directory) ++ (setq mode-line-format ++ (format-mode-line mode-line-format 'font-lock-warning-face)))) ++ ++(add-hook 'find-file-hooks 'my-mode-line-function) ++(add-hook 'dired-mode-hook 'my-mode-line-function) ++@end lisp ++@end ifset ++ ++ ++@ifset emacs ++@item ++I'ld like to see a host indication in the mode line when I'm remote ++ ++The following code has been tested with @value{emacsname} 22.1. You ++should put it into your @file{~/.emacs}: ++ ++@lisp ++(defconst my-mode-line-buffer-identification ++ (list ++ '(:eval ++ (let ((host-name ++ (if (file-remote-p default-directory) ++ (tramp-file-name-host ++ (tramp-dissect-file-name default-directory)) ++ (system-name)))) ++ (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) ++ (substring host-name 0 (match-beginning 1)) ++ host-name))) ++ ": %12b")) ++ ++(setq-default ++ mode-line-buffer-identification ++ my-mode-line-buffer-identification) ++ ++(add-hook ++ 'dired-mode-hook ++ '(lambda () ++ (setq ++ mode-line-buffer-identification ++ my-mode-line-buffer-identification))) ++@end lisp ++ ++Since @value{emacsname} 23.1, the mode line contains an indication if ++@code{default-directory} for the current buffer is on a remote host. ++The corresponding tooltip includes the name of that host. If you ++still want the host name as part of the mode line, you can use the ++example above, but the @code{:eval} clause can be simplified: ++ ++@lisp ++ '(:eval ++ (let ((host-name ++ (or (file-remote-p default-directory 'host) ++ (system-name)))) ++ (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) ++ (substring host-name 0 (match-beginning 1)) ++ host-name))) ++@end lisp ++@end ifset ++ ++ ++@ifset emacs ++@item ++My remote host does not understand default directory listing options ++ ++@value{emacsname} computes the @command{dired} options depending on ++the local host you are working. If your @command{ls} command on the ++remote host does not understand those options, you can change them ++like this: ++ ++@lisp ++(add-hook ++ 'dired-before-readin-hook ++ '(lambda () ++ (when (file-remote-p default-directory) ++ (setq dired-actual-switches "-al")))) ++@end lisp ++@end ifset ++ ++ ++@item ++There's this @file{~/.sh_history} file on the remote host which keeps ++growing and growing. What's that? ++ ++Sometimes, @value{tramp} starts @command{ksh} on the remote host for ++tilde expansion. Maybe @command{ksh} saves the history by default. ++@value{tramp} tries to turn off saving the history, but maybe you have ++to help. For example, you could put this in your @file{.kshrc}: ++ ++@example ++if [ -f $HOME/.sh_history ] ; then ++ /bin/rm $HOME/.sh_history ++fi ++if [ "$@{HISTFILE-unset@}" != "unset" ] ; then ++ unset HISTFILE ++fi ++if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then ++ unset HISTSIZE ++fi ++@end example ++ ++ ++@item There are longish file names to type. How to shorten this? ++ ++Let's say you need regularly access to @file{@trampfn{ssh, news, ++news.my.domain, /opt/news/etc}}, which is boring to type again and ++again. The following approaches can be mixed: ++ ++@enumerate ++ ++@item Use default values for method and user name: ++ ++You can define default methods and user names for hosts, ++(@pxref{Default Method}, @pxref{Default User}): ++ ++@lisp ++(setq tramp-default-method "ssh" ++ tramp-default-user "news") ++@end lisp ++ ++The file name left to type would be ++@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}. ++ ++Note, that there are some useful settings already. Accessing your ++local host as @samp{root} user, is possible just by @kbd{C-x C-f ++@trampfn{su, , ,}}. ++ ++@item Use configuration possibilities of your method: ++ ++Several connection methods (i.e. the programs used) offer powerful ++configuration possibilities (@pxref{Customizing Completion}). In the ++given case, this could be @file{~/.ssh/config}: ++ ++@example ++Host xy ++ HostName news.my.domain ++ User news ++@end example ++ ++The file name left to type would be @kbd{C-x C-f @trampfn{ssh, , xy, ++/opt/news/etc}}. Depending on files in your directories, it is even ++possible to complete the host name with @kbd{C-x C-f ++@value{prefix}ssh@value{postfixhop}x @key{TAB}}. ++ ++@item Use environment variables: ++ ++File names typed in the minibuffer can be expanded by environment ++variables. You can set them outside @value{emacsname}, or even with ++Lisp: ++ ++@lisp ++(setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}") ++@end lisp ++ ++Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you ++are. The disadvantage is, that you cannot edit the file name, because ++environment variables are not expanded during editing in the ++minibuffer. ++ ++@item Define own keys: ++ ++You can define your own key sequences in @value{emacsname}, which can ++be used instead of @kbd{C-x C-f}: ++ ++@lisp ++(global-set-key ++ [(control x) (control y)] ++ (lambda () ++ (interactive) ++ (find-file ++ (read-file-name ++ "Find Tramp file: " ++ "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))) ++@end lisp ++ ++Simply typing @kbd{C-x C-y} would initialize the minibuffer for ++editing with your beloved file name. ++ ++See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the ++Emacs Wiki} for a more comprehensive example. ++ ++@item Define own abbreviation (1): ++ ++It is possible to define an own abbreviation list for expanding file ++names: ++ ++@lisp ++(add-to-list ++ 'directory-abbrev-alist ++ '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")) ++@end lisp ++ ++This shortens the file openening command to @kbd{C-x C-f /xy ++@key{RET}}. The disadvantage is, again, that you cannot edit the file ++name, because the expansion happens after entering the file name only. ++ ++@item Define own abbreviation (2): ++ ++The @code{abbrev-mode} gives more flexibility for editing the ++minibuffer: ++ ++@lisp ++(define-abbrev-table 'my-tramp-abbrev-table ++ '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))) ++ ++(add-hook ++ 'minibuffer-setup-hook ++ '(lambda () ++ (abbrev-mode 1) ++ (setq local-abbrev-table my-tramp-abbrev-table))) ++ ++(defadvice minibuffer-complete ++ (before my-minibuffer-complete activate) ++ (expand-abbrev)) ++ ++;; If you use partial-completion-mode ++(defadvice PC-do-completion ++ (before my-PC-do-completion activate) ++ (expand-abbrev)) ++@end lisp ++ ++After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is ++expanded, and you can continue editing. ++ ++@item Use bookmarks: ++ ++Bookmarks can be used to visit Tramp files or directories. ++@ifinfo ++@pxref{Bookmarks, , , @value{emacsdir}} ++@end ifinfo ++ ++When you have opened @file{@trampfn{ssh, news, news.my.domain, ++/opt/news/etc/}}, you should save the bookmark via ++@ifset emacs ++@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}. ++@end ifset ++@ifset xemacs ++@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}. ++@end ifset ++ ++Later on, you can always navigate to that bookmark via ++@ifset emacs ++@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}. ++@end ifset ++@ifset xemacs ++@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}. ++@end ifset ++ ++@item Use recent files: ++ ++@ifset emacs ++@file{recentf} ++@end ifset ++@ifset xemacs ++@file{recent-files} ++@end ifset ++remembers visited places. ++@ifinfo ++@ifset emacs ++@pxref{File Conveniences, , , @value{emacsdir}} ++@end ifset ++@ifset xemacs ++@pxref{recent-files, , , edit-utils} ++@end ifset ++@end ifinfo ++ ++You could keep remote file names in the recent list without checking ++their readability through a remote access: ++ ++@lisp ++@ifset emacs ++(recentf-mode 1) ++@end ifset ++@ifset xemacs ++(recent-files-initialize) ++(add-hook ++ 'find-file-hooks ++ (lambda () ++ (when (file-remote-p (buffer-file-name)) ++ (recent-files-make-permanent))) ++ 'append) ++@end ifset ++@end lisp ++ ++The list of files opened recently is reachable via ++@ifset emacs ++@kbd{@key{menu-bar} @key{file} @key{Open Recent}}. ++@end ifset ++@ifset xemacs ++@kbd{@key{menu-bar} @key{Recent Files}}. ++@end ifset ++ ++@ifset emacs ++@item Use filecache: ++ ++@file{filecache} remembers visited places. Add the directory into ++the cache: ++ ++@lisp ++(eval-after-load "filecache" ++ '(file-cache-add-directory ++ "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")) ++@end lisp ++ ++Whenever you want to load a file, you can enter @kbd{C-x C-f ++C-@key{TAB}} in the minibuffer. The completion is done for the given ++directory. ++@end ifset ++ ++@ifset emacs ++@item Use bbdb: ++ ++@file{bbdb} has a built-in feature for @value{ftppackagename} files, ++which works also for @value{tramp}. ++@ifinfo ++@pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb} ++@end ifinfo ++ ++You need to load @file{bbdb}: ++ ++@lisp ++(require 'bbdb) ++(bbdb-initialize) ++@end lisp ++ ++Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}. ++Because BBDB is not prepared for @value{tramp} syntax, you must ++specify a method together with the user name, when needed. Example: ++ ++@example ++@kbd{M-x bbdb-create-ftp-site @key{RET}} ++@b{Ftp Site:} news.my.domain @key{RET} ++@b{Ftp Directory:} /opt/news/etc/ @key{RET} ++@b{Ftp Username:} ssh@value{postfixhop}news @key{RET} ++@b{Company:} @key{RET} ++@b{Additional Comments:} @key{RET} ++@end example ++ ++When you have opened your BBDB buffer, you can access such an entry by ++pressing the key @key{F}. ++@end ifset ++ ++@end enumerate ++ ++I would like to thank all @value{tramp} users, who have contributed to ++the different recipes! ++ ++ ++@item ++How can I disable @value{tramp}? ++ ++Shame on you, why did you read until now? ++ ++@itemize @minus ++ ++@item ++@ifset emacs ++If you just want to have @value{ftppackagename} as default remote ++files access package, you should apply the following code: ++ ++@lisp ++(setq tramp-default-method "ftp") ++@end lisp ++@end ifset ++ ++@item ++In order to disable ++@ifset emacs ++@value{tramp} (and @value{ftppackagename}), ++@end ifset ++@ifset xemacs ++@value{tramp}, ++@end ifset ++you must set @code{tramp-mode} to @code{nil}: ++ ++@lisp ++(setq tramp-mode nil) ++@end lisp ++ ++@item ++Unloading @value{tramp} can be achieved by applying @kbd{M-x ++tramp-unload-tramp}. ++@ifset emacs ++This resets also the @value{ftppackagename} plugins. ++@end ifset ++@end itemize ++@end itemize ++ ++ ++@c For the developer ++@node Version Control ++@chapter The inner workings of remote version control ++@cindex Version Control ++ ++Unlike @value{ftppackagename}, @value{tramp} has full shell access to the ++remote machine. This makes it possible to provide version control for ++files accessed under @value{tramp}. ++ ++The actual version control binaries must be installed on the remote ++machine, accessible in the directories specified in ++@code{tramp-remote-path}. ++ ++This transparent integration with the version control systems is one of ++the most valuable features provided by @value{tramp}, but it is far from perfect. ++Work is ongoing to improve the transparency of the system. ++ ++@menu ++* Version Controlled Files:: Determining if a file is under version control. ++* Remote Commands:: Executing the version control commands on the remote machine. ++* Changed workfiles:: Detecting if the working file has changed. ++* Checking out files:: Bringing the workfile out of the repository. ++* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere. ++@end menu ++ ++ ++@node Version Controlled Files ++@section Determining if a file is under version control ++ ++The VC package uses the existence of on-disk revision control master ++files to determine if a given file is under revision control. These file ++tests happen on the remote machine through the standard @value{tramp} mechanisms. ++ ++ ++@node Remote Commands ++@section Executing the version control commands on the remote machine ++ ++There are no hooks provided by VC to allow intercepting of the version ++control command execution. The calls occur through the ++@code{call-process} mechanism, a function that is somewhat more ++efficient than the @code{shell-command} function but that does not ++provide hooks for remote execution of commands. ++ ++To work around this, the functions @code{vc-do-command} and ++@code{vc-simple-command} have been advised to intercept requests for ++operations on files accessed via @value{tramp}. ++ ++In the case of a remote file, the @code{shell-command} interface is ++used, with some wrapper code, to provide the same functionality on the ++remote machine as would be seen on the local machine. ++ ++ ++@node Changed workfiles ++@section Detecting if the working file has changed ++ ++As there is currently no way to get access to the mtime of a file on a ++remote machine in a portable way, the @code{vc-workfile-unchanged-p} ++function is advised to call an @value{tramp} specific function for remote files. ++ ++The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC ++diff functionality to determine if any changes have occurred between the ++workfile and the version control master. ++ ++This requires that a shell command be executed remotely, a process that ++is notably heavier-weight than the mtime comparison used for local ++files. Unfortunately, unless a portable solution to the issue is found, ++this will remain the cost of remote version control. ++ ++ ++@node Checking out files ++@section Bringing the workfile out of the repository ++ ++VC will, by default, check for remote files and refuse to act on them ++when checking out files from the repository. To work around this ++problem, the function @code{vc-checkout} knows about @value{tramp} files and ++allows version control to occur. ++ ++ ++@node Miscellaneous Version Control ++@section Things related to Version Control that don't fit elsewhere ++ ++Minor implementation details, &c. ++ ++@menu ++* Remote File Ownership:: How VC determines who owns a workfile. ++* Back-end Versions:: How VC determines what release your RCS is. ++@end menu ++ ++ ++@node Remote File Ownership ++@subsection How VC determines who owns a workfile ++ ++@value{emacsname} provides the @code{user-login-name} function to ++return the login name of the current user as well as mapping from ++arbitrary user id values back to login names. The VC code uses this ++functionality to map from the uid of the owner of a workfile to the ++login name in some circumstances. ++ ++This will not, for obvious reasons, work if the remote system has a ++different set of logins. As such, it is necessary to delegate to the ++remote machine the job of determining the login name associated with a ++uid. ++ ++Unfortunately, with the profusion of distributed management systems such ++as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple, ++reliable and portable method for performing this mapping. ++ ++Thankfully, the only place in the VC code that depends on the mapping of ++a uid to a login name is the @code{vc-file-owner} function. This returns ++the login of the owner of the file as a string. ++ ++This function has been advised to use the output of @command{ls} on the ++remote machine to determine the login name, delegating the problem of ++mapping the uid to the login to the remote system which should know more ++about it than I do. ++ ++ ++@node Back-end Versions ++@subsection How VC determines what release your RCS is ++ ++VC needs to know what release your revision control binaries you are ++running as not all features VC supports are available with older ++versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}. ++ ++The default implementation of VC determines this value the first time it ++is needed and then stores the value globally to avoid the overhead of ++executing a process and parsing its output each time the information is ++needed. ++ ++Unfortunately, life is not quite so easy when remote version control ++comes into the picture. Each remote machine may have a different version ++of the version control tools and, while this is painful, we need to ++ensure that unavailable features are not used remotely. ++ ++To resolve this issue, @value{tramp} currently takes the sledgehammer ++approach of making the release values of the revision control tools ++local to each @value{tramp} buffer, forcing VC to determine these values ++again each time a new file is visited. ++ ++This has, quite obviously, some performance implications. Thankfully, ++most of the common operations performed by VC do not actually require ++that the remote version be known. This makes the problem far less ++apparent. ++ ++Eventually these values will be captured by @value{tramp} on a system by ++system basis and the results cached to improve performance. ++ ++ ++@node Files directories and localnames ++@chapter How file names, directories and localnames are mangled and managed. ++ ++@menu ++* Localname deconstruction:: Breaking a localname into its components. ++@ifset emacs ++* External packages:: Integration with external Lisp packages. ++@end ifset ++@end menu ++ ++ ++@node Localname deconstruction ++@section Breaking a localname into its components. ++ ++@value{tramp} file names are somewhat different, obviously, to ordinary file ++names. As such, the lisp functions @code{file-name-directory} and ++@code{file-name-nondirectory} are overridden within the @value{tramp} ++package. ++ ++Their replacements are reasonably simplistic in their approach. They ++dissect the filename, call the original handler on the localname and ++then rebuild the @value{tramp} file name with the result. ++ ++This allows the platform specific hacks in the original handlers to take ++effect while preserving the @value{tramp} file name information. ++ ++ ++@ifset emacs ++@node External packages ++@section Integration with external Lisp packages. ++ ++While reading filenames in the minibuffer, @value{tramp} must decide ++whether it completes possible incomplete filenames, or not. Imagine ++there is the following situation: You have typed @kbd{C-x C-f ++@value{prefix}ssh@value{postfixhop} @key{TAB}}. @value{tramp} cannot ++know, whether @option{ssh} is a method or a host name. It checks ++therefore the last input character you have typed. If this is ++@key{TAB}, @key{SPACE} or @kbd{?}, @value{tramp} assumes that you are ++still in filename completion, and it does not connect to the possible ++remote host @option{ssh}. ++ ++@vindex tramp-completion-mode ++External packages, which use other characters for completing filenames ++in the minibuffer, must signal this to @value{tramp}. For this case, ++the variable @code{tramp-completion-mode} can be bound temporarily to ++a non-nil value. ++ ++@lisp ++(let ((tramp-completion-mode t)) ++ ...) ++@end lisp ++@end ifset ++ ++ ++@node Traces and Profiles ++@chapter How to Customize Traces ++ ++All @value{tramp} messages are raised with a verbosity level. The ++verbosity level can be any number between 0 and 10. Only messages with ++a verbosity level less than or equal to @code{tramp-verbose} are ++displayed. ++ ++The verbosity levels are ++ ++ @w{ 0} silent (no @value{tramp} messages at all) ++@*@indent @w{ 1} errors ++@*@indent @w{ 2} warnings ++@*@indent @w{ 3} connection to remote hosts (default verbosity) ++@*@indent @w{ 4} activities ++@*@indent @w{ 5} internal ++@*@indent @w{ 6} sent and received strings ++@*@indent @w{ 7} file caching ++@*@indent @w{ 8} connection properties ++@*@indent @w{10} traces (huge) ++ ++When @code{tramp-verbose} is greater than or equal to 4, the messages ++are also written into a @value{tramp} debug buffer. This debug buffer ++is useful for analysing problems; sending a @value{tramp} bug report ++should be done with @code{tramp-verbose} set to a verbosity level of at ++least 6 (@pxref{Bug Reports}). ++ ++The debug buffer is in ++@ifinfo ++@ref{Outline Mode, , , @value{emacsdir}}. ++@end ifinfo ++@ifnotinfo ++Outline Mode. ++@end ifnotinfo ++That means, you can change the level of messages to be viewed. If you ++want, for example, see only messages up to verbosity level 5, you must ++enter @kbd{C-u 6 C-c C-q}. ++@ifinfo ++Other keys for navigating are described in ++@ref{Outline Visibility, , , @value{emacsdir}}. ++@end ifinfo ++ ++@value{tramp} errors are handled internally in order to raise the ++verbosity level 1 messages. When you want to get a Lisp backtrace in ++case of an error, you need to set both ++ ++@lisp ++(setq debug-on-error t ++ debug-on-signal t) ++@end lisp ++ ++Sometimes, it might be even necessary to step through @value{tramp} ++function call traces. Such traces are enabled by the following code: ++ ++@lisp ++(require 'tramp) ++(require 'trace) ++(dolist (elt (all-completions "tramp-" obarray 'functionp)) ++ (trace-function-background (intern elt))) ++(untrace-function 'tramp-read-passwd) ++(untrace-function 'tramp-gw-basic-authentication) ++@end lisp ++ ++The function call traces are inserted in the buffer ++@file{*trace-output*}. @code{tramp-read-passwd} and ++@code{tramp-gw-basic-authentication} shall be disabled when the ++function call traces are added to @value{tramp}, because both ++functions return password strings, which should not be distributed. ++ ++ ++@node Issues ++@chapter Debatable Issues and What Was Decided ++ ++@itemize @bullet ++@item The uuencode method does not always work. ++ ++Due to the design of @value{tramp}, the encoding and decoding programs ++need to read from stdin and write to stdout. On some systems, ++@command{uudecode -o -} will read stdin and write the decoded file to ++stdout, on other systems @command{uudecode -p} does the same thing. ++But some systems have uudecode implementations which cannot do this at ++all---it is not possible to call these uudecode implementations with ++suitable parameters so that they write to stdout. ++ ++Of course, this could be circumvented: the @code{begin foo 644} line ++could be rewritten to put in some temporary file name, then ++@command{uudecode} could be called, then the temp file could be ++printed and deleted. ++ ++But I have decided that this is too fragile to reliably work, so on some ++systems you'll have to do without the uuencode methods. ++ ++@item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs. ++ ++The GNU Emacs maintainers wish to use a unified filename syntax for ++Ange-FTP and @value{tramp} so that users don't have to learn a new ++syntax. It is sufficient to learn some extensions to the old syntax. ++ ++For the XEmacs maintainers, the problems caused from using a unified ++filename syntax are greater than the gains. The XEmacs package system ++uses EFS for downloading new packages. So, obviously, EFS has to be ++installed from the start. If the filenames were unified, @value{tramp} ++would have to be installed from the start, too. ++ ++@ifset xemacs ++@strong{Note:} If you'd like to use a similar syntax like ++@value{ftppackagename}, you need the following settings in your init ++file: ++ ++@lisp ++(setq tramp-unified-filenames t) ++(require 'tramp) ++@end lisp ++ ++The autoload of the @value{emacsname} @value{tramp} package must be ++disabled. This can be achieved by setting file permissions @code{000} ++to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}. ++ ++In case of unified filenames, all @value{emacsname} download sites are ++added to @code{tramp-default-method-alist} with default method ++@option{ftp} @xref{Default Method}. These settings shouldn't be ++touched for proper working of the @value{emacsname} package system. ++ ++The syntax for unified filenames is described in the @value{tramp} manual ++for @value{emacsothername}. ++@end ifset ++@end itemize ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Function Index ++@unnumbered Function Index ++@printindex fn ++ ++@node Variable Index ++@unnumbered Variable Index ++@printindex vr ++ ++@node Concept Index ++@unnumbered Concept Index ++@printindex cp ++ ++@bye ++ ++@c TODO ++@c ++@c * Say something about the .login and .profile files of the remote ++@c shells. ++@c * Explain how tramp.el works in principle: open a shell on a remote ++@c host and then send commands to it. ++@c * Use `filename' resp. `file name' consistently. ++@c * Use `host' resp. `machine' consistently. ++@c * Consistent small or capitalized words especially in menues. ++ ++@ignore ++ arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808 ++@end ignore +diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi +new file mode 100644 +index 0000000..7644a4a +--- /dev/null ++++ b/doc/misc/trampver.texi +@@ -0,0 +1,71 @@ ++@c -*-texinfo-*- ++@c texi/trampver.texi. Generated from trampver.texi.in by configure. ++ ++@c This is part of the Emacs manual. ++@c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 ++@c Free Software Foundation, Inc. ++@c See file doclicense.texi for copying conditions. ++ ++@c In the Tramp CVS, the version number is auto-frobbed from ++@c configure.ac, so you should edit that file and run ++@c "autoconf && ./configure" to change the version number. ++@set trampver 2.1.15 ++ ++@c Other flags from configuration ++@set instprefix /usr/local ++@set lispdir /usr/local/share/emacs/site-lisp ++@set infodir /usr/local/share/info ++ ++@c Formatting of the tramp program name consistent. ++@set tramp @sc{tramp} ++ ++@c Whether or not describe gateway methods. ++@ifclear noemacsgw ++@set emacsgw ++@end ifclear ++ ++@c Some flags which make the text independent on the (X)Emacs flavor. ++@c "emacs" resp "xemacs" are set in the Makefile. Default is "emacs". ++@ifclear emacs ++@ifclear xemacs ++@set emacs ++@end ifclear ++@end ifclear ++ ++@c Emacs values. ++@ifset emacs ++@set emacsname GNU Emacs ++@set emacsdir emacs ++@set ftppackagename Ange-FTP ++@set prefix / ++@set prefixhop ++@set postfix : ++@set postfixhop : ++@set ipv6prefix [ ++@set ipv6postfix ] ++@set emacsothername XEmacs ++@set emacsotherdir xemacs ++@set emacsotherfilename tramp-xemacs.html ++@set japanesemanual tramp_ja-emacs.html ++@end ifset ++ ++@c XEmacs counterparts. ++@ifset xemacs ++@set emacsname XEmacs ++@set emacsdir xemacs ++@set ftppackagename EFS ++@set prefix /[ ++@set prefixhop [ ++@set postfix ] ++@set postfixhop / ++@set ipv6prefix ++@set ipv6postfix ++@set emacsothername GNU Emacs ++@set emacsotherdir emacs ++@set emacsotherfilename tramp-emacs.html ++@set japanesemanual tramp_ja-xemacs.html ++@end ifset ++ ++@ignore ++ arch-tag: e0fe322c-e06b-46eb-bb5b-d091b521f41c ++@end ignore +diff --git a/doc/misc/url.texi b/doc/misc/url.texi +new file mode 100644 +index 0000000..f60952a +--- /dev/null ++++ b/doc/misc/url.texi +@@ -0,0 +1,1192 @@ ++\input texinfo ++@setfilename ../../info/url ++@settitle URL Programmer's Manual ++ ++@iftex ++@c @finalout ++@end iftex ++@c @setchapternewpage odd ++@c @smallbook ++ ++@tex ++\overfullrule=0pt ++%\global\baselineskip 30pt % for printing in double space ++@end tex ++@dircategory World Wide Web ++@dircategory Emacs ++@direntry ++* URL: (url). URL loading package. ++@end direntry ++ ++@copying ++This file documents the Emacs Lisp URL loading package. ++ ++Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002, ++2004, 2005, 2006, 2007, 2008, 2009 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 ++ ++@c ++@titlepage ++@title URL Programmer's Manual ++@subtitle First Edition, URL Version 2.0 ++@author William M. Perry @email{wmperry@@gnu.org} ++@author David Love @email{fx@@gnu.org} ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@node Top ++@top URL ++ ++@ifnottex ++@insertcopying ++@end ifnottex ++ ++@menu ++* Getting Started:: Preparing your program to use URLs. ++* Retrieving URLs:: How to use this package to retrieve a URL. ++* Supported URL Types:: Descriptions of URL types currently supported. ++* Defining New URLs:: How to define a URL loader for a new protocol. ++* General Facilities:: URLs can be cached, accessed via a gateway ++ and tracked in a history list. ++* Customization:: Variables you can alter. ++* GNU Free Documentation License:: The license for this documentation. ++* Function Index:: ++* Variable Index:: ++* Concept Index:: ++@end menu ++ ++@node Getting Started ++@chapter Getting Started ++@cindex URLs, definition ++@cindex URIs ++ ++@dfn{Uniform Resource Locators} (URLs) are a specific form of ++@dfn{Uniform Resource Identifiers} (URI) described in RFC 2396 which ++updates RFC 1738 and RFC 1808. RFC 2016 defines uniform resource ++agents. ++ ++URIs have the form @var{scheme}:@var{scheme-specific-part}, where the ++@var{scheme}s supported by this library are described below. ++@xref{Supported URL Types}. ++ ++FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270, ++IRC and gopher URLs all have the form ++ ++@example ++@var{scheme}://@r{[}@var{userinfo}@@@r{]}@var{hostname}@r{[}:@var{port}@r{]}@r{[}/@var{path}@r{]} ++@end example ++@noindent ++where @samp{@r{[}} and @samp{@r{]}} delimit optional parts. ++@var{userinfo} sometimes takes the form @var{username}:@var{password} ++but you should beware of the security risks of sending cleartext ++passwords. @var{hostname} may be a domain name or a dotted decimal ++address. If the @samp{:@var{port}} is omitted then the library will ++use the `well known' port for that service when accessing URLs. With ++the possible exception of @code{telnet}, it is rare for ports to be ++specified, and it is possible using a non-standard port may have ++undesired consequences if a different service is listening on that ++port (e.g., an HTTP URL specifying the SMTP port can cause mail to be ++sent). @c , but @xref{Other Variables, url-bad-port-list}. ++The meaning of the @var{path} component depends on the service. ++ ++@menu ++* Configuration:: ++* Parsed URLs:: URLs are parsed into vector structures. ++@end menu ++ ++@node Configuration ++@section Configuration ++ ++@defvar url-configuration-directory ++@cindex @file{~/.url} ++@cindex configuration files ++The directory in which URL configuration files, the cache etc., ++reside. Default @file{~/.url}. ++@end defvar ++ ++@node Parsed URLs ++@section Parsed URLs ++@cindex parsed URLs ++The library functions typically operate on @dfn{parsed} versions of ++URLs. These are actually vectors of the form: ++ ++@example ++[@var{type} @var{user} @var{password} @var{host} @var{port} @var{file} @var{target} @var{attributes} @var{full}] ++@end example ++ ++@noindent where ++@table @var ++@item type ++is the type of the URL scheme, e.g., @code{http} ++@item user ++is the username associated with it, or @code{nil}; ++@item password ++is the user password associated with it, or @code{nil}; ++@item host ++is the host name associated with it, or @code{nil}; ++@item port ++is the port number associated with it, or @code{nil}; ++@item file ++is the `file' part of it, or @code{nil}. This doesn't necessarily ++actually refer to a file; ++@item target ++is the target part, or @code{nil}; ++@item attributes ++is the attributes associated with it, or @code{nil}; ++@item full ++is @code{t} for a fully-specified URL, with a host part indicated by ++@samp{//} after the scheme part. ++@end table ++ ++@findex url-type ++@findex url-user ++@findex url-password ++@findex url-host ++@findex url-port ++@findex url-file ++@findex url-target ++@findex url-attributes ++@findex url-full ++@findex url-set-type ++@findex url-set-user ++@findex url-set-password ++@findex url-set-host ++@findex url-set-port ++@findex url-set-file ++@findex url-set-target ++@findex url-set-attributes ++@findex url-set-full ++These attributes have accessors named @code{url-@var{part}}, where ++@var{part} is the name of one of the elements above, e.g., ++@code{url-host}. Similarly, there are setters of the form ++@code{url-set-@var{part}}. ++ ++There are functions for parsing and unparsing between the string and ++vector forms. ++ ++@defun url-generic-parse-url url ++Return a parsed version of the string @var{url}. ++@end defun ++ ++@defun url-recreate-url url ++@cindex unparsing URLs ++Recreates a URL string from the parsed @var{url}. ++@end defun ++ ++@node Retrieving URLs ++@chapter Retrieving URLs ++ ++@defun url-retrieve-synchronously url ++Retrieve @var{url} synchronously and return a buffer containing the ++data. @var{url} is either a string or a parsed URL structure. Return ++@code{nil} if there are no data associated with it (the case for dired, ++info, or mailto URLs that need no further processing). ++@end defun ++ ++@defun url-retrieve url callback &optional cbargs ++Retrieve @var{url} asynchronously and call @var{callback} with args ++@var{cbargs} when finished. The callback is called when the object ++has been completely retrieved, with the current buffer containing the ++object and any MIME headers associated with it. @var{url} is either a ++string or a parsed URL structure. Returns the buffer @var{url} will ++load into, or @code{nil} if the process has already completed. ++@end defun ++ ++@node Supported URL Types ++@chapter Supported URL Types ++ ++@menu ++* http/https:: Hypertext Transfer Protocol. ++* file/ftp:: Local files and FTP archives. ++* info:: Emacs `Info' pages. ++* mailto:: Sending email. ++* news/nntp/snews:: Usenet news. ++* rlogin/telnet/tn3270:: Remote host connectivity. ++* irc:: Internet Relay Chat. ++* data:: Embedded data URLs. ++* nfs:: Networked File System ++@c * finger:: ++@c * gopher:: ++@c * netrek:: ++@c * prospero:: ++* cid:: Content-ID. ++* about:: ++* ldap:: Lightweight Directory Access Protocol ++* imap:: IMAP mailboxes. ++* man:: Unix man pages. ++@end menu ++ ++@node http/https ++@section @code{http} and @code{https} ++ ++The scheme @code{http} is Hypertext Transfer Protocol. The library ++supports version 1.1, specified in RFC 2616. (This supersedes 1.0, ++defined in RFC 1945) HTTP URLs have the following form, where most of ++the parts are optional: ++@example ++http://@var{user}:@var{password}@@@var{host}:@var{port}/@var{path}?@var{searchpart}#@var{fragment} ++@end example ++@c The @code{:@var{port}} part is optional, and @var{port} defaults to ++@c 80. The @code{/@var{path}} part, if present, is a slash-separated ++@c series elements. The @code{?@var{searchpart}}, if present, is the ++@c query for a search or the content of a form submission. The ++@c @code{#fragment} part, if present, is a location in the document. ++ ++The scheme @code{https} is a secure version of @code{http}, with ++transmission via SSL. It is defined in RFC 2069. Its default port is ++443. This scheme depends on SSL support in Emacs via the ++@file{ssl.el} library and is actually implemented by forcing the ++@code{ssl} gateway method to be used. @xref{Gateways in general}. ++ ++@defopt url-honor-refresh-requests ++This controls honoring of HTTP @samp{Refresh} headers by which ++servers can direct clients to reload documents from the same URL or a ++or different one. @code{nil} means they will not be honored, ++@code{t} (the default) means they will always be honored, and ++otherwise the user will be asked on each request. ++@end defopt ++ ++ ++@menu ++* Cookies:: ++* HTTP language/coding:: ++* HTTP URL Options:: ++* Dealing with HTTP documents:: ++@end menu ++ ++@node Cookies ++@subsection Cookies ++ ++@defopt url-cookie-file ++The file in which cookies are stored, defaulting to @file{cookies} in ++the directory specified by @code{url-configuration-directory}. ++@end defopt ++ ++@defopt url-cookie-confirmation ++Specifies whether confirmation is require to accept cookies. ++@end defopt ++ ++@defopt url-cookie-multiple-line ++Specifies whether to put all cookies for the server on one line in the ++HTTP request to satisfy broken servers like ++@url{http://www.hotmail.com}. ++@end defopt ++ ++@defopt url-cookie-trusted-urls ++A list of regular expressions matching URLs from which to accept ++cookies always. ++@end defopt ++ ++@defopt url-cookie-untrusted-urls ++A list of regular expressions matching URLs from which to reject ++cookies always. ++@end defopt ++ ++@defopt url-cookie-save-interval ++The number of seconds between automatic saves of cookies to disk. ++Default is one hour. ++@end defopt ++ ++ ++@node HTTP language/coding ++@subsection Language and Encoding Preferences ++ ++HTTP allows clients to express preferences for the language and ++encoding of documents which servers may honor. For each of these ++variables, the value is a string; it can specify a single choice, or ++it can be a comma-separated list. ++ ++Normally this list ordered by descending preference. However, each ++element can be followed by @samp{;q=@var{priority}} to specify its ++preference level, a decimal number from 0 to 1; e.g., for ++@code{url-mime-language-string}, @w{@code{"de, en-gb;q=0.8, ++en;q=0.7"}}. An element that has no @samp{;q} specification has ++preference level 1. ++ ++@defopt url-mime-charset-string ++@cindex character sets ++@cindex coding systems ++This variable specifies a preference for character sets when documents ++can be served in more than one encoding. ++ ++HTTP allows specifying a series of MIME charsets which indicate your ++preferred character set encodings, e.g., Latin-9 or Big5, and these ++can be weighted. The default series is generated automatically from ++the associated MIME types of all defined coding systems, sorted by the ++coding system priority specified in Emacs. @xref{Recognize Coding, , ++Recognizing Coding Systems, emacs, The GNU Emacs Manual}. ++@end defopt ++ ++@defopt url-mime-language-string ++@cindex language preferences ++A string specifying the preferred language when servers can serve ++files in several languages. Use RFC 1766 abbreviations, e.g., ++@samp{en} for English, @samp{de} for German. ++ ++The string can be @code{"*"} to get the first available language (as ++opposed to the default). ++@end defopt ++ ++@node HTTP URL Options ++@subsection HTTP URL Options ++ ++HTTP supports an @samp{OPTIONS} method describing things supported by ++the URL@. ++ ++@defun url-http-options url ++Returns a property list describing options available for URL. The ++property list members are: ++ ++@table @code ++@item methods ++A list of symbols specifying what HTTP methods the resource ++supports. ++ ++@item dav ++@cindex DAV ++A list of numbers specifying what DAV protocol/schema versions are ++supported. ++ ++@item dasl ++@cindex DASL ++A list of supported DASL search types supported (string form). ++ ++@item ranges ++A list of the units available for use in partial document fetches. ++ ++@item p3p ++@cindex P3P ++The @dfn{Platform For Privacy Protection} description for the resource. ++Currently this is just the raw header contents. ++@end table ++ ++@end defun ++ ++@node Dealing with HTTP documents ++@subsection Dealing with HTTP documents ++ ++HTTP URLs are retrieved into a buffer containing the HTTP headers ++followed by the body. Since the headers are quasi-MIME, they may be ++processed using the MIME library. @xref{Top,, Emacs MIME, ++emacs-mime, The Emacs MIME Manual}. The URL package provides a ++function to do this in general: ++ ++@defun url-decode-text-part handle &optional coding ++This function decodes charset-encoded text in the current buffer. In ++Emacs, the buffer is expected to be unibyte initially and is set to ++multibyte after decoding. ++HANDLE is the MIME handle of the original part. CODING is an explicit ++coding to use, overriding what the MIME headers specify. ++The coding system used for the decoding is returned. ++ ++Note that this function doesn't deal with @samp{http-equiv} charset ++specifications in HTML @samp{} elements. ++@end defun ++ ++@node file/ftp ++@section file and ftp ++@cindex files ++@cindex FTP ++@cindex File Transfer Protocol ++@cindex compressed files ++@cindex dired ++ ++@example ++ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} ++file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} ++@end example ++ ++These schemes are defined in RFC 1808. ++@samp{ftp:} and @samp{file:} are synonymous in this library. They ++allow reading arbitrary files from hosts. Either @samp{ange-ftp} ++(Emacs) or @samp{efs} (XEmacs) is used to retrieve them from remote ++hosts. Local files are accessed directly. ++ ++Compressed files are handled, but support is hard-coded so that ++@code{jka-compr-compression-info-list} and so on have no affect. ++Suffixes recognized are @samp{.z}, @samp{.gz}, @samp{.Z} and ++@samp{.bz2}. ++ ++@defopt url-directory-index-file ++The filename to look for when indexing a directory, default ++@samp{"index.html"}. If this file exists, and is readable, then it ++will be viewed instead of using @code{dired} to view the directory. ++@end defopt ++ ++@node info ++@section info ++@cindex Info ++@cindex Texinfo ++@findex Info-goto-node ++ ++@example ++info:@var{file}#@var{node} ++@end example ++ ++Info URLs are not officially defined. They invoke ++@code{Info-goto-node} with argument @samp{(@var{file})@var{node}}. ++@samp{#@var{node}} is optional, defaulting to @samp{Top}. ++ ++@node mailto ++@section mailto ++ ++@cindex mailto ++@cindex email ++A mailto URL will send an email message to the address in the ++URL, for example @samp{mailto:foo@@bar.com} would compose a ++message to @samp{foo@@bar.com}. ++ ++@defopt url-mail-command ++@vindex mail-user-agent ++The function called whenever url needs to send mail. This should ++normally be left to default from @var{mail-user-agent}. @xref{Mail ++Methods, , Mail-Composition Methods, emacs, The GNU Emacs Manual}. ++@end defopt ++ ++An @samp{X-Url-From} header field containing the URL of the document ++that contained the mailto URL is added if that URL is known. ++ ++RFC 2368 extends the definition of mailto URLs in RFC 1738. ++The form of a mailto URL is ++@example ++@samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]} ++@end example ++@noindent where an arbitrary number of @var{header}s can be added. If the ++@var{header} is @samp{body}, then @var{contents} is put in the body ++otherwise a @var{header} header field is created with @var{contents} ++as its contents. Note that the URL library does not consider any ++headers `dangerous' so you should check them before sending the ++message. ++ ++@c Fixme: update ++Email messages are defined in @sc{rfc}822. ++ ++@node news/nntp/snews ++@section @code{news}, @code{nntp} and @code{snews} ++@cindex news ++@cindex network news ++@cindex usenet ++@cindex NNTP ++@cindex snews ++ ++@c draft-gilman-news-url-01 ++The network news URL scheme take the following forms following RFC ++1738 except that for compatibility with other clients, host and port ++fields may be included in news URLs though they are properly only ++allowed for nntp an snews. ++ ++@table @samp ++@item news:@var{newsgroup} ++Retrieves a list of messages in @var{newsgroup}; ++@item news:@var{message-id} ++Retrieves the message with the given @var{message-id}; ++@item news:* ++Retrieves a list of all available newsgroups; ++@item nntp://@var{host}:@var{port}/@var{newsgroup} ++@itemx nntp://@var{host}:@var{port}/@var{message-id} ++@itemx nntp://@var{host}:@var{port}/* ++Similar to the @samp{news} versions. ++@end table ++ ++@samp{:@var{port}} is optional and defaults to :119. ++ ++@samp{snews} is the same as @samp{nntp} except that the default port ++is :563. ++@cindex SSL ++(It is tunneled through SSL.) ++ ++An @samp{nntp} URL is the same as a news URL, except that the URL may ++specify an article by its number. ++ ++@defopt url-news-server ++This variable can be used to override the default news server. ++Usually this will be set by the Gnus package, which is used to fetch ++news. ++@cindex environment variable ++@vindex NNTPSERVER ++It may be set from the conventional environment variable ++@code{NNTPSERVER}. ++@end defopt ++ ++@node rlogin/telnet/tn3270 ++@section rlogin, telnet and tn3270 ++@cindex rlogin ++@cindex telnet ++@cindex tn3270 ++@cindex terminal emulation ++@findex terminal-emulator ++ ++These URL schemes from RFC 1738 for logon via a terminal emulator have ++the form ++@example ++telnet://@var{user}:@var{password}@@@var{host}:@var{port} ++@end example ++but the @code{:@var{password}} component is ignored. ++ ++To handle rlogin, telnet and tn3270 URLs, a @code{rlogin}, ++@code{telnet} or @code{tn3270} (the program names and arguments are ++hardcoded) session is run in a @code{terminal-emulator} buffer. ++Well-known ports are used if the URL does not specify a port. ++ ++@node irc ++@section irc ++@cindex IRC ++@cindex Internet Relay Chat ++@cindex ZEN IRC ++@cindex ERC ++@cindex rcirc ++@c Fixme: reference (was http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt) ++@dfn{Internet Relay Chat} (IRC) is handled by handing off the @sc{irc} ++session to a function named in @code{url-irc-function}. ++ ++@defopt url-irc-function ++A function to actually open an IRC connection. ++This function ++must take five arguments, @var{host}, @var{port}, @var{channel}, ++@var{user} and @var{password}. The @var{channel} argument specifies the ++channel to join immediately, this can be @code{nil}. By default this is ++@code{url-irc-rcirc}. ++@end defopt ++@defun url-irc-rcirc host port channel user password ++Processes the arguments and lets @code{rcirc} handle the session. ++@end defun ++@defun url-irc-erc host port channel user password ++Processes the arguments and lets @code{ERC} handle the session. ++@end defun ++@defun url-irc-zenirc host port channel user password ++Processes the arguments and lets @code{zenirc} handle the session. ++@end defun ++ ++@node data ++@section data ++@cindex data URLs ++ ++@example ++data:@r{[}@var{media-type}@r{]}@r{[};@var{base64}@r{]},@var{data} ++@end example ++ ++Data URLs contain MIME data in the URL itself. They are defined in ++RFC 2397. ++ ++@var{media-type} is a MIME @samp{Content-Type} string, possibly ++including parameters. It defaults to ++@samp{text/plain;charset=US-ASCII}. The @samp{text/plain} can be ++omitted but the charset parameter supplied. If @samp{;base64} is ++present, the @var{data} are base64-encoded. ++ ++@node nfs ++@section nfs ++@cindex NFS ++@cindex Network File System ++@cindex automounter ++ ++@example ++nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} ++@end example ++ ++The @samp{nfs:} scheme is defined in RFC 2224. It is similar to ++@samp{ftp:} except that it points to a file on a remote host that is ++handled by the automounter on the local host. ++ ++@defvar url-nfs-automounter-directory-spec ++@end defvar ++A string saying how to invoke the NFS automounter. Certain @samp{%} ++sequences are recognized: ++ ++@table @samp ++@item %h ++The hostname of the NFS server; ++@item %n ++The port number of the NFS server; ++@item %u ++The username to use to authenticate; ++@item %p ++The password to use to authenticate; ++@item %f ++The filename on the remote server; ++@item %% ++A literal @samp{%}. ++@end table ++ ++Each can be used any number of times. ++ ++@node cid ++@section cid ++@cindex Content-ID ++ ++RFC 2111 ++ ++@node about ++@section about ++ ++@node ldap ++@section ldap ++@cindex LDAP ++@cindex Lightweight Directory Access Protocol ++ ++The LDAP scheme is defined in RFC 2255. ++ ++@node imap ++@section imap ++@cindex IMAP ++ ++RFC 2192 ++ ++@node man ++@section man ++@cindex @command{man} ++@cindex Unix man pages ++@findex man ++ ++@example ++@samp{man:@var{page-spec}} ++@end example ++ ++This is a non-standard scheme. @var{page-spec} is passed directly to ++the Lisp @code{man} function. ++ ++@node Defining New URLs ++@chapter Defining New URLs ++ ++@menu ++* Naming conventions:: ++* Required functions:: ++* Optional functions:: ++* Asynchronous fetching:: ++* Supporting file-name-handlers:: ++@end menu ++ ++@node Naming conventions ++@section Naming conventions ++ ++@node Required functions ++@section Required functions ++ ++@node Optional functions ++@section Optional functions ++ ++@node Asynchronous fetching ++@section Asynchronous fetching ++ ++@node Supporting file-name-handlers ++@section Supporting file-name-handlers ++ ++@node General Facilities ++@chapter General Facilities ++ ++@menu ++* Disk Caching:: ++* Proxies:: ++* Gateways in general:: ++* History:: ++@end menu ++ ++@node Disk Caching ++@section Disk Caching ++@cindex Caching ++@cindex Persistent Cache ++@cindex Disk Cache ++ ++The disk cache stores retrieved documents locally, whence they can be ++retrieved more quickly. When requesting a URL that is in the cache, ++the library checks to see if the page has changed since it was last ++retrieved from the remote machine. If not, the local copy is used, ++saving the transmission over the network. ++@cindex Cleaning the cache ++@cindex Clearing the cache ++@cindex Cache cleaning ++Currently the cache isn't cleared automatically. ++@c Running the @code{clean-cache} shell script ++@c fist is recommended, to allow for future cleaning of the cache. This ++@c shell script will remove all files that have not been accessed since it ++@c was last run. To keep the cache pared down, it is recommended that this ++@c script be run from @i{at} or @i{cron} (see the manual pages for ++@c crontab(5) or at(1) for more information) ++ ++@defopt url-automatic-caching ++Setting this variable non-@code{nil} causes documents to be cached ++automatically. ++@end defopt ++ ++@defopt url-cache-directory ++This variable specifies the ++directory to store the cache files. It defaults to sub-directory ++@file{cache} of @code{url-configuration-directory}. ++@end defopt ++ ++@c Fixme: function v. option, but neither used. ++@c @findex url-cache-expired ++@c @defopt url-cache-expired ++@c This is a function to decide whether or not a cache entry has expired. ++@c It takes two times as it parameters and returns non-@code{nil} if the ++@c second time is ``too old'' when compared with the first time. ++@c @end defopt ++ ++@defopt url-cache-creation-function ++The cache relies on a scheme for mapping URLs to files in the cache. ++This variable names a function which sets the type of cache to use. ++It takes a URL as argument and returns the absolute file name of the ++corresponding cache file. The two supplied possibilities are ++@code{url-cache-create-filename-using-md5} and ++@code{url-cache-create-filename-human-readable}. ++@end defopt ++ ++@defun url-cache-create-filename-using-md5 url ++Creates a cache file name from @var{url} using MD5 hashing. ++This is creates entries with very few cache collisions and is fast. ++@cindex MD5 ++@smallexample ++(url-cache-create-filename-using-md5 "http://www.example.com/foo/bar") ++ @result{} "/home/fx/.url/cache/fx/http/com/example/www/b8a35774ad20db71c7c3409a5410e74f" ++@end smallexample ++@end defun ++ ++@defun url-cache-create-filename-human-readable url ++Creates a cache file name from @var{url} more obviously connected to ++@var{url} than for @code{url-cache-create-filename-using-md5}, but ++more likely to conflict with other files. ++@smallexample ++(url-cache-create-filename-human-readable "http://www.example.com/foo/bar") ++ @result{} "/home/fx/.url/cache/fx/http/com/example/www/foo/bar" ++@end smallexample ++@end defun ++ ++@c Fixme: never actually used currently? ++@c @defopt url-standalone-mode ++@c @cindex Relying on cache ++@c @cindex Cache only mode ++@c @cindex Standalone mode ++@c If this variable is non-@code{nil}, the library relies solely on the ++@c cache for fetching documents and avoids checking if they have changed ++@c on remote servers. ++@c @end defopt ++ ++@c With a large cache of documents on the local disk, it can be very handy ++@c when traveling, or any other time the network connection is not active ++@c (a laptop with a dial-on-demand PPP connection, etc). Emacs/W3 can rely ++@c solely on its cache, and avoid checking to see if the page has changed ++@c on the remote server. In the case of a dial-on-demand PPP connection, ++@c this will keep the phone line free as long as possible, only bringing up ++@c the PPP connection when asking for a page that is not located in the ++@c cache. This is very useful for demonstrations as well. ++ ++@node Proxies ++@section Proxies and Gatewaying ++ ++@c fixme: check/document url-ns stuff ++@cindex proxy servers ++@cindex proxies ++@cindex environment variables ++@vindex HTTP_PROXY ++Proxy servers are commonly used to provide gateways through firewalls ++or as caches serving some more-or-less local network. Each protocol ++(HTTP, FTP, etc.)@: can have a different gateway server. Proxying is ++conventionally configured commonly amongst different programs through ++environment variables of the form @code{@var{protocol}_proxy}, where ++@var{protocol} is one of the supported network protocols (@code{http}, ++@code{ftp} etc.). The library recognizes such variables in either ++upper or lower case. Their values are of one of the forms: ++@itemize @bullet ++@item @code{@var{host}:@var{port}} ++@item A full URL; ++@item Simply a host name. ++@end itemize ++ ++@vindex NO_PROXY ++The @code{NO_PROXY} environment variable specifies URLs that should be ++excluded from proxying (on servers that should be contacted directly). ++This should be a comma-separated list of hostnames, domain names, or a ++mixture of both. Asterisks can be used as wildcards, but other ++clients may not support that. Domain names may be indicated by a ++leading dot. For example: ++@example ++NO_PROXY="*.aventail.com,home.com,.seanet.com" ++@end example ++@noindent says to contact all machines in the @samp{aventail.com} and ++@samp{seanet.com} domains directly, as well as the machine named ++@samp{home.com}. If @code{NO_PROXY} isn't defined, @code{no_PROXY} ++and @code{no_proxy} are also tried, in that order. ++ ++Proxies may also be specified directly in Lisp. ++ ++@defopt url-proxy-services ++This variable is an alist of URL schemes and proxy servers that ++gateway them. The items are of the form @w{@code{(@var{scheme} ++. @var{host}:@var{portnumber})}}, says that the URL @var{scheme} is ++gatewayed through @var{portnumber} on the specified @var{host}. An ++exception is the pseudo scheme @code{"no_proxy"}, which is paired with ++a regexp matching host names not to be proxied. This variable is ++initialized from the environment as above. ++ ++@example ++(setq url-proxy-services ++ '(("http" . "proxy.aventail.com:80") ++ ("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com"))) ++@end example ++@end defopt ++ ++@node Gateways in general ++@section Gateways in General ++@cindex gateways ++@cindex firewalls ++ ++The library provides a general gateway layer through which all ++networking passes. It can both control access to the network and ++provide access through gateways in firewalls. This may make direct ++connections in some cases and pass through some sort of gateway in ++others.@footnote{Proxies (which only operate over HTTP) are ++implemented using this.} The library's basic function responsible for ++making connections is @code{url-open-stream}. ++ ++@defun url-open-stream name buffer host service ++@cindex opening a stream ++@cindex stream, opening ++Open a stream to @var{host}, possibly via a gateway. The other ++arguments are as for @code{open-network-stream}. This will not make a ++connection if @code{url-gateway-unplugged} is non-@code{nil}. ++@end defun ++ ++@defvar url-gateway-local-host-regexp ++This is a regular expression that matches local hosts that do not ++require the use of a gateway. If @code{nil}, all connections are made ++through the gateway. ++@end defvar ++ ++@defvar url-gateway-method ++This variable controls which gateway method is used. It may be useful ++to bind it temporarily in some applications. It has values taken from ++a list of symbols. Possible values are: ++ ++@table @code ++@item telnet ++@cindex @command{telnet} ++Use this method if you must first telnet and log into a gateway host, ++and then run telnet from that host to connect to outside machines. ++ ++@item rlogin ++@cindex @command{rlogin} ++This method is identical to @code{telnet}, but uses @command{rlogin} ++to log into the remote machine without having to send the username and ++password over the wire every time. ++ ++@item socks ++@cindex @sc{socks} ++Use if the firewall has a @sc{socks} gateway running on it. The ++@sc{socks} v5 protocol is defined in RFC 1928. ++ ++@c @item ssl ++@c This probably shouldn't be documented ++@c Fixme: why not? -- fx ++ ++@item native ++This method uses Emacs's builtin networking directly. This is the ++default. It can be used only if there is no firewall blocking access. ++@end table ++@end defvar ++ ++The following variables control the gateway methods. ++ ++@defopt url-gateway-telnet-host ++The gateway host to telnet to. Once logged in there, you then telnet ++out to the hosts you want to connect to. ++@end defopt ++@defopt url-gateway-telnet-parameters ++This should be a list of parameters to pass to the @command{telnet} program. ++@end defopt ++@defopt url-gateway-telnet-password-prompt ++This is a regular expression that matches the password prompt when ++logging in. ++@end defopt ++@defopt url-gateway-telnet-login-prompt ++This is a regular expression that matches the username prompt when ++logging in. ++@end defopt ++@defopt url-gateway-telnet-user-name ++The username to log in with. ++@end defopt ++@defopt url-gateway-telnet-password ++The password to send when logging in. ++@end defopt ++@defopt url-gateway-prompt-pattern ++This is a regular expression that matches the shell prompt. ++@end defopt ++ ++@defopt url-gateway-rlogin-host ++Host to @samp{rlogin} to before telnetting out. ++@end defopt ++@defopt url-gateway-rlogin-parameters ++Parameters to pass to @samp{rsh}. ++@end defopt ++@defopt url-gateway-rlogin-user-name ++User name to use when logging in to the gateway. ++@end defopt ++@defopt url-gateway-prompt-pattern ++This is a regular expression that matches the shell prompt. ++@end defopt ++ ++@defopt socks-server ++This specifies the default server, it takes the form ++@w{@code{("Default server" @var{server} @var{port} @var{version})}} ++where @var{version} can be either 4 or 5. ++@end defopt ++@defvar socks-password ++If this is @code{nil} then you will be asked for the password, ++otherwise it will be used as the password for authenticating you to ++the @sc{socks} server. ++@end defvar ++@defvar socks-username ++This is the username to use when authenticating yourself to the ++@sc{socks} server. By default this is your login name. ++@end defvar ++@defvar socks-timeout ++This controls how long, in seconds, to wait for responses from the ++@sc{socks} server; it is 5 by default. ++@end defvar ++@c fixme: these have been effectively commented-out in the code ++@c @defopt socks-server-aliases ++@c This a list of server aliases. It is a list of aliases of the form ++@c @var{(alias hostname port version)}. ++@c @end defopt ++@c @defopt socks-network-aliases ++@c This a list of network aliases. Each entry in the list takes the form ++@c @var{(alias (network))} where @var{alias} is a string that names the ++@c @var{network}. The networks can contain a pair (not a dotted pair) of ++@c @sc{ip} addresses which specify a range of @sc{ip} addresses, an @sc{ip} ++@c address and a netmask, a domain name or a unique hostname or @sc{ip} ++@c address. ++@c @end defopt ++@c @defopt socks-redirection-rules ++@c This a list of redirection rules. Each rule take the form ++@c @var{(Destination network Connection type)} where @var{Destination ++@c network} is a network alias from @code{socks-network-aliases} and ++@c @var{Connection type} can be @code{nil} in which case a direct ++@c connection is used, or it can be an alias from ++@c @code{socks-server-aliases} in which case that server is used as a ++@c proxy. ++@c @end defopt ++@defopt socks-nslookup-program ++@cindex @command{nslookup} ++This the @samp{nslookup} program. It is @code{"nslookup"} by default. ++@end defopt ++ ++@menu ++* Suppressing network connections:: ++@end menu ++@c * Broken hostname resolution:: ++ ++@node Suppressing network connections ++@subsection Suppressing Network Connections ++ ++@cindex network connections, suppressing ++@cindex suppressing network connections ++@cindex bugs, HTML ++@cindex HTML `bugs' ++In some circumstances it is desirable to suppress making network ++connections. A typical case is when rendering HTML in a mail user ++agent, when external URLs should not be activated, particularly to ++avoid `bugs' which `call home' by fetch single-pixel images and the ++like. To arrange this, bind the following variable for the duration ++of such processing. ++ ++@defvar url-gateway-unplugged ++If this variable is non-@code{nil} new network connections are never ++opened by the URL library. ++@end defvar ++ ++@c @node Broken hostname resolution ++@c @subsection Broken Hostname Resolution ++ ++@c @cindex hostname resolver ++@c @cindex resolver, hostname ++@c Some C libraries do not include the hostname resolver routines in ++@c their static libraries. If Emacs was linked statically, and was not ++@c linked with the resolver libraries, it will not be able to get to any ++@c machines off the local network. This is characterized by being able ++@c to reach someplace with a raw ip number, but not its hostname ++@c (@url{http://129.79.254.191/} works, but ++@c @url{http://www.cs.indiana.edu/} doesn't). This used to happen on ++@c SunOS4 and Ultrix, but is now probably now rare. If Emacs can't be ++@c rebuilt linked against the resolver library, it can use the external ++@c @command{nslookup} program instead. ++ ++@c @defopt url-gateway-broken-resolution ++@c @cindex @code{nslookup} program ++@c @cindex program, @code{nslookup} ++@c If non-@code{nil}, this variable says to use the program specified by ++@c @code{url-gateway-nslookup-program} program to do hostname resolution. ++@c @end defopt ++ ++@c @defopt url-gateway-nslookup-program ++@c The name of the program to do hostname lookup if Emacs can't do it ++@c directly. This program should expect a single argument on the command ++@c line---the hostname to resolve---and should produce output similar to ++@c the standard Unix @command{nslookup} program: ++@c @example ++@c Name: www.cs.indiana.edu ++@c Address: 129.79.254.191 ++@c @end example ++@c @end defopt ++ ++@node History ++@section History ++ ++@findex url-do-setup ++The library can maintain a global history list tracking URLs accessed. ++URL completion can be done from it. The history mechanism is set up ++automatically via @code{url-do-setup} when it is configured to be on. ++Note that the size of the history list is currently not limited. ++ ++@vindex url-history-hash-table ++The history `list' is actually a hash table, ++@code{url-history-hash-table}. It contains access times keyed by URL ++strings. The times are in the format returned by @code{current-time}. ++ ++@defun url-history-update-url url time ++This function updates the history table with an entry for @var{url} ++accessed at the given @var{time}. ++@end defun ++ ++@defopt url-history-track ++If non-@code{nil}, the library will keep track of all the URLs ++accessed. If it is @code{t}, the list is saved to disk at the end of ++each Emacs session. The default is @code{nil}. ++@end defopt ++ ++@defopt url-history-file ++The file storing the history list between sessions. It defaults to ++@file{history} in @code{url-configuration-directory}. ++@end defopt ++ ++@defopt url-history-save-interval ++@findex url-history-setup-save-timer ++The number of seconds between automatic saves of the history list. ++Default is one hour. Note that if you change this variable directly, ++rather than using Custom, after @code{url-do-setup} has been run, you ++need to run the function @code{url-history-setup-save-timer}. ++@end defopt ++ ++@defun url-history-parse-history &optional fname ++Parses the history file @var{fname} (default @code{url-history-file}) ++and sets up the history list. ++@end defun ++ ++@defun url-history-save-history &optional fname ++Saves the current history to file @var{fname} (default ++@code{url-history-file}). ++@end defun ++ ++@defun url-completion-function string predicate function ++You can use this function to do completion of URLs from the history. ++@end defun ++ ++@node Customization ++@chapter Customization ++ ++@section Environment Variables ++ ++@cindex environment variables ++The following environment variables affect the library's operation at ++startup. ++ ++@table @code ++@item TMPDIR ++@vindex TMPDIR ++@vindex url-temporary-directory ++If this is defined, @var{url-temporary-directory} is initialized from ++it. ++@end table ++ ++@section General User Options ++ ++The following user options, settable with Customize, affect the ++general operation of the package. ++ ++@defopt url-debug ++@cindex debugging ++Specifies the types of debug messages the library which are logged to ++the @code{*URL-DEBUG*} buffer. ++@code{t} means log all messages. ++A number means log all messages and show them with @code{message}. ++If may also be a list of the types of messages to be logged. ++@end defopt ++@defopt url-personal-mail-address ++@end defopt ++@defopt url-privacy-level ++@end defopt ++@defopt url-uncompressor-alist ++@end defopt ++@defopt url-passwd-entry-func ++@end defopt ++@defopt url-standalone-mode ++@end defopt ++@defopt url-bad-port-list ++@end defopt ++@defopt url-max-password-attempts ++@end defopt ++@defopt url-temporary-directory ++@end defopt ++@defopt url-show-status ++@end defopt ++@defopt url-confirmation-func ++The function to use for asking yes or no functions. This is normally ++either @code{y-or-n-p} or @code{yes-or-no-p}, but could be another ++function taking a single argument (the prompt) and returning @code{t} ++only if an affirmative answer is given. ++@end defopt ++@defopt url-gateway-method ++@c fixme: describe gatewaying ++A symbol specifying the type of gateway support to use for connections ++from the local machine. The supported methods are: ++ ++@table @code ++@item telnet ++Run telnet in a subprocess to connect; ++@item rlogin ++Rlogin to another machine to connect; ++@item socks ++Connect through a socks server; ++@item ssl ++Connect with SSL; ++@item native ++Connect directly. ++@end table ++@end defopt ++ ++@node GNU Free Documentation License ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++@node Function Index ++@unnumbered Command and Function Index ++@printindex fn ++ ++@node Variable Index ++@unnumbered Variable Index ++@printindex vr ++ ++@node Concept Index ++@unnumbered Concept Index ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: c96be356-7e2d-4196-bcda-b13246c5c3f0 ++@end ignore +diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi +new file mode 100644 +index 0000000..a1ef6b9 +--- /dev/null ++++ b/doc/misc/vip.texi +@@ -0,0 +1,1952 @@ ++\input texinfo ++@setfilename ../../info/vip ++@settitle VIP ++ ++@copying ++Copyright @copyright{} 1987, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 ++ ++@titlepage ++@sp 10 ++@center @titlefont{VIP} ++@sp 1 ++@center A Vi Package for GNU Emacs ++@center (Version 3.5, September 15, 1987) ++@sp 2 ++@center Masahiko Sato ++@page ++@vskip 0pt plus1filll ++@insertcopying ++@end titlepage ++ ++@finalout ++@contents ++ ++@dircategory Emacs ++@direntry ++* VIP: (vip). An older VI-emulation for Emacs. ++@end direntry ++ ++@ifnottex ++@node Top, Survey,, (DIR) ++@top VIP ++ ++VIP is a Vi emulating package written in Emacs Lisp. VIP implements most ++Vi commands including Ex commands. It is therefore hoped that this package ++will enable you to do Vi style editing under the powerful GNU Emacs ++environment. This info file describes the usage of VIP assuming that you ++are fairly accustomed to Vi but not so much with Emacs. Also we will ++concentrate mainly on differences from Vi, especially features unique to ++VIP. ++ ++It is recommended that you read nodes on survey and on customization before ++you start using VIP. Other nodes may be visited as needed. ++ ++Comments and bug reports are welcome. Please send messages to ++@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to ++@code{masahiko@@sato.riec.tohoku.junet} if you are in Japan.@refill ++ ++@insertcopying ++ ++@end ifnottex ++ ++@menu ++* Survey:: A survey of VIP. ++* Vi Commands:: Details of Vi commands. ++* Ex Commands:: Details of Ex commands. ++* Customization:: How to customize VIP. ++* GNU Free Documentation License:: The license for this documentation. ++ ++@end menu ++@iftex ++@unnumbered Introduction ++ ++VIP is a Vi emulating package written in Emacs Lisp. VIP implements most ++Vi commands including Ex commands. It is therefore hoped that this package ++will enable you to do Vi style editing under the powerful GNU Emacs ++environment. This manual describes the usage of VIP assuming that you are ++fairly accustomed to Vi but not so much with Emacs. Also we will ++concentrate mainly on differences from Vi, especially features unique to ++VIP. ++ ++It is recommended that you read chapters on survey and on customization ++before you start using VIP. Other chapters may be used as future ++references. ++ ++Comments and bug reports are welcome. Please send messages to ++@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to ++@code{masahiko@@unsun.riec.tohoku.junet} if you are in Japan. ++@end iftex ++ ++@node Survey, Basic Concepts, Top, Top ++@chapter A Survey of VIP ++ ++In this chapter we describe basics of VIP with emphasis on the features not ++found in Vi and on how to use VIP under GNU Emacs. ++ ++@menu ++* Basic Concepts:: Basic concepts in Emacs. ++* Loading VIP:: How to load VIP automatically. ++* Modes in VIP:: VIP has three modes, which are orthogonal to modes ++ in Emacs. ++* Differences from Vi:: Differences of VIP from Vi is explained. ++@end menu ++ ++@node Basic Concepts, Loading VIP, Survey, Survey ++@section Basic Concepts ++ ++We begin by explaining some basic concepts of Emacs. These concepts are ++explained in more detail in the GNU Emacs Manual. ++ ++@cindex buffer ++@cindex point ++@cindex mark ++@cindex text ++@cindex looking at ++@cindex end (of buffer) ++@cindex region ++ ++Conceptually, a @dfn{buffer} is just a string of @acronym{ASCII} characters and two ++special characters @key{PNT} (@dfn{point}) and @key{MRK} (@dfn{mark}) such ++that the character @key{PNT} occurs exactly once and @key{MRK} occurs at ++most once. The @dfn{text} of a buffer is obtained by deleting the ++occurrences of @key{PNT} and @key{MRK}. If, in a buffer, there is a ++character following @key{PNT} then we say that point is @dfn{looking at} ++the character; otherwise we say that point is @dfn{at the end of buffer}. ++@key{PNT} and @key{MRK} are used ++to indicate positions in a buffer and they are not part of the text of the ++buffer. If a buffer contains a @key{MRK} then the text between @key{MRK} ++and @key{PNT} is called the @dfn{region} of the buffer.@refill ++ ++@cindex window ++ ++Emacs provides (multiple) @dfn{windows} on the screen, and you can see the ++content of a buffer through the window associated with the buffer. The ++cursor of the screen is always positioned on the character after @key{PNT}. ++@refill ++ ++@cindex mode ++@cindex keymap ++@cindex local keymap ++@cindex global keymap ++ ++A @dfn{keymap} is a table that records the bindings between characters and ++command functions. There is the @dfn{global keymap} common to all the ++buffers. Each buffer has its @dfn{local keymap} that determines the ++@dfn{mode} of the buffer. Local keymap overrides global keymap, so that if ++a function is bound to some key in the local keymap then that function will ++be executed when you type the key. If no function is bound to a key in the ++local map, however, the function bound to the key in the global map becomes ++in effect.@refill ++ ++@node Loading VIP, Modes in VIP, Basic Concepts, Survey ++@section Loading VIP ++ ++The recommended way to load VIP automatically is to include the line: ++@example ++(load "vip") ++@end example ++@noindent ++in your @file{.emacs} file. The @file{.emacs} file is placed in your home ++directory and it will be executed every time you invoke Emacs. If you wish ++to be in vi mode whenever Emacs starts up, you can include the following ++line in your @file{.emacs} file instead of the above line: ++@example ++(setq term-setup-hook 'vip-mode) ++@end example ++@noindent ++(@xref{Vi Mode}, for the explanation of vi mode.) ++ ++Even if your @file{.emacs} file does not contain any of the above lines, ++you can load VIP and enter vi mode by typing the following from within ++Emacs. ++@example ++M-x vip-mode ++@end example ++@noindent ++ ++@node Modes in VIP, Emacs Mode, Loading VIP, Survey ++@section Modes in VIP ++ ++@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) ++@kindex 0301 @kbd{C-x C-z} (@code{suspend-emacs}) ++ ++Loading VIP has the effect of globally binding @kbd{C-z} (@kbd{Control-z}) ++to the function @code{vip-change-mode-to-vi}. The default binding of @kbd{C-z} ++in GNU Emacs is @code{suspend-emacs}, but, you can also call ++@code{suspend-emacs} by typing @kbd{C-x C-z}. Other than this, all the ++key bindings of Emacs remain the same after loading VIP.@refill ++ ++@cindex vi mode ++ ++Now, if you hit @kbd{C-z}, the function @code{vip-change-mode-to-vi} will be ++called and you will be in @dfn{vi mode}. (Some major modes may locally bind ++@kbd{C-z} to some special functions. In such cases, you can call ++@code{vip-change-mode-to-vi} by @code{execute-extended-command} which is ++invoked by @kbd{M-x}. Here @kbd{M-x} means @kbd{Meta-x}, and if your ++terminal does not have a @key{META} key you can enter it by typing ++@kbd{@key{ESC} x}. The same effect can also be achieve by typing ++@kbd{M-x vip-mode}.)@refill ++ ++@cindex mode line ++ ++You can observe the change of mode by looking at the @dfn{mode line}. For ++instance, if the mode line is:@refill ++@example ++-----Emacs: *scratch* (Lisp Interaction)----All------------ ++@end example ++@noindent ++then it will change to: ++@example ++-----Vi: *scratch* (Lisp Interaction)----All------------ ++@end example ++@noindent ++Thus the word @samp{Emacs} in the mode line will change to @samp{Vi}. ++ ++@cindex insert mode ++@cindex emacs mode ++ ++You can go back to the original @dfn{emacs mode} by typing @kbd{C-z} in ++vi mode. Thus @kbd{C-z} toggles between these two modes.@refill ++ ++Note that modes in VIP exist orthogonally to modes in Emacs. This means ++that you can be in vi mode and at the same time, say, shell mode. ++ ++Vi mode corresponds to Vi's command mode. From vi mode you can enter ++@dfn{insert mode} (which corresponds to Vi's insert mode) by usual Vi command ++keys like @kbd{i}, @kbd{a}, @kbd{o} @dots{} etc. ++ ++In insert mode, the mode line will look like this: ++@example ++-----Insert *scratch* (Lisp Interaction)----All------------ ++@end example ++@noindent ++You can exit from insert mode by hitting @key{ESC} key as you do in Vi. ++ ++That VIP has three modes may seem very complicated, but in fact it is not ++so. VIP is implemented so that you can do most editing remaining only ++in the two modes for Vi (that is vi mode and insert mode). ++ ++@ifinfo ++The figure below shows the transition of three modes in VIP. ++@display ++ ++ ++ === C-z ==> == i,o ... ==> ++emacs mode vi mode insert mode ++ <== X-z === <=== ESC ==== ++@end display ++@end ifinfo ++ ++@menu ++* Emacs Mode:: This is the mode you should know better. ++* Vi Mode:: Vi commands are executed in this mode. ++* Insert Mode:: You can enter text, and also can do editing if you ++ know enough Emacs commands. ++@end menu ++ ++@node Emacs Mode, Vi Mode, Modes in VIP, Modes in VIP ++@subsection Emacs Mode ++ ++@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) ++ ++You will be in this mode just after you loaded VIP. You can do all ++normal Emacs editing in this mode. Note that the key @kbd{C-z} is globally ++bound to @code{vip-change-mode-to-vi}. So, if you type @kbd{C-z} in this mode ++then you will be in vi mode.@refill ++ ++@node Vi Mode, Insert Mode, Emacs Mode, Modes in VIP ++@subsection Vi Mode ++ ++This mode corresponds to Vi's command mode. Most Vi commands work as they ++do in Vi. You can go back to emacs mode by typing @kbd{C-z}. You can ++enter insert mode, just as in Vi, by typing @kbd{i}, @kbd{a} etc. ++ ++@node Insert Mode, Differences from Vi, Vi Mode, Modes in VIP ++@subsection Insert Mode ++ ++The key bindings in this mode is the same as in the emacs mode except for ++the following 4 keys. So, you can move around in the buffer and change ++its content while you are in insert mode. ++ ++@table @kbd ++@item @key{ESC} ++@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) ++This key will take you back to vi mode. ++@item C-h ++@kindex 010 @kbd{C-h} (@code{vip-delete-backward-char}) (insert mode) ++Delete previous character. ++@item C-w ++@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) ++Delete previous word. ++@item C-z ++@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) ++Typing this key has the same effect as typing @key{ESC} in emacs mode. ++Thus typing @kbd{C-z x} in insert mode will have the same effect as typing ++@kbd{ESC x} in emacs mode. ++@end table ++ ++@node Differences from Vi, Undoing, Insert Mode, Survey ++@section Differences from Vi ++ ++The major differences from Vi are explained below. ++ ++@menu ++* Undoing:: You can undo more in VIP. ++* Changing:: Commands for changing the text. ++* Searching:: Search commands. ++* z Command:: You can now use zH, zM and zL as well as z- etc. ++* Counts:: Some Vi commands which do not accept a count now ++ accept one. ++* Marking:: You can now mark the current point, beginning of ++ the buffer etc. ++* Region Commands:: You can now give a region as an argument for delete ++ commands etc. ++* New Commands:: Some new commands not available in Vi are added. ++* New Bindings:: Bindings of some keys are changed for the ++ convenience of editing under Emacs. ++* Window Commands:: Commands for moving among windows etc. ++* Buffer Commands:: Commands for selecting buffers etc. ++* File Commands:: Commands for visiting files etc. ++* Misc Commands:: Other useful commands. ++@end menu ++ ++@node Undoing, Changing, Differences from Vi, Differences from Vi ++@subsection Undoing ++ ++@kindex 165 @kbd{u} (@code{vip-undo}) ++@kindex 056 @kbd{.} (@code{vip-repeat}) ++ ++You can repeat undoing by the @kbd{.} key. So, @kbd{u} will undo ++a single change, while @kbd{u .@: .@: .@:}, for instance, will undo 4 previous ++changes. Undo is undoable as in Vi. So the content of the buffer will ++be the same before and after @kbd{u u}.@refill ++ ++@node Changing, Searching, Undoing, Differences from Vi ++@subsection Changing ++ ++Some commands which change a small number of characters are executed ++slightly differently. Thus, if point is at the beginning of a word ++@samp{foo} and you wished to change it to @samp{bar} by typing @w{@kbd{c w}}, ++then VIP will prompt you for a new word in the minibuffer by the prompt ++@samp{foo => }. You can then enter @samp{bar} followed by @key{RET} or ++@key{ESC} to complete the command. Before you enter @key{RET} or ++@key{ESC} you can abort the command by typing @kbd{C-g}. In general, ++@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) ++you can abort a partially formed command by typing @kbd{C-g}.@refill ++ ++@node Searching, z Command, Changing, Differences from Vi ++@subsection Searching ++ ++@kindex 057 @kbd{/} (@code{vip-search-forward}) ++@kindex 077 @kbd{?} (@code{vip-search-backward}) ++ ++As in Vi, searching is done by @kbd{/} and @kbd{?}. The string will be ++searched literally by default. To invoke a regular expression search, ++first execute the search command @kbd{/} (or @kbd{?}) with empty search ++string. (I.e, type @kbd{/} followed by @key{RET}.) ++A search for empty string will toggle the search mode between vanilla ++search and regular expression search. You cannot give an offset to the ++search string. (It is a limitation.) By default, search will wrap around ++the buffer as in Vi. You can change this by rebinding the variable ++@code{vip-search-wrap-around}. @xref{Customization}, for how to do this.@refill ++ ++@node z Command, Counts, Searching, Differences from Vi ++@subsection z Command ++ ++@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) ++@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) ++@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) ++@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) ++@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) ++@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) ++ ++For those of you who cannot remember which of @kbd{z} followed by @key{RET}, ++@kbd{.}@: and @kbd{-} do what. You can also use @kbd{z} followed by @kbd{H}, ++@kbd{M} and @kbd{L} to place the current line in the Home (Middle, and ++Last) line of the window.@refill ++ ++@node Counts, Marking, z Command, Differences from Vi ++@subsection Counts ++ ++Some Vi commands which do not accept a count now accept one ++ ++@table @kbd ++@item p ++@itemx P ++@kindex 160 @kbd{p} (@code{vip-put-back}) ++@kindex 120 @kbd{P} (@code{vip-Put-back}) ++Given counts, text will be yanked (in Vi's sense) that many times. Thus ++@kbd{3 p} is the same as @kbd{p p p}. ++@item o ++@itemx O ++@kindex 157 @kbd{o} (@code{vip-open-line}) ++@kindex 117 @kbd{O} (@code{vip-Open-line}) ++Given counts, that many copies of text will be inserted. Thus ++@kbd{o a b c @key{ESC}} will insert 3 lines of @samp{abc} below the current ++line. ++@item / ++@itemx ? ++@kindex 057 @kbd{/} (@code{vip-search-forward}) ++@kindex 077 @kbd{?} (@code{vip-search-backward}) ++Given a count @var{n}, @var{n}-th occurrence will be searched. ++@end table ++ ++@node Marking, Region Commands, Counts, Differences from Vi ++@subsection Marking ++ ++Typing an @kbd{m} followed by a lower-case character @var{ch} marks the ++point to the register named @var{ch} as in Vi. In addition to these, we ++have following key bindings for marking. ++ ++@kindex 155 @kbd{m} (@code{vip-mark-point}) ++ ++@table @kbd ++@item m < ++Set mark at the beginning of buffer. ++@item m > ++Set mark at the end of buffer. ++@item m . ++Set mark at point (and push old mark on mark ring). ++@item m , ++Jump to mark (and pop mark off the mark ring). ++@end table ++ ++@node Region Commands, New Commands, Marking, Differences from Vi ++@subsection Region Commands ++ ++@cindex region ++ ++Vi operators like @kbd{d}, @kbd{c} etc. are usually used in combination ++with motion commands. It is now possible to use current region as the ++argument to these operators. (A @dfn{region} is a part of buffer ++delimited by point and mark.) The key @kbd{r} is used for this purpose. ++Thus @kbd{d r} will delete the current region. If @kbd{R} is used instead ++of @kbd{r} the region will first be enlarged so that it will become the ++smallest region containing the original region and consisting of whole ++lines. Thus @kbd{m .@: d R} will have the same effect as @kbd{d d}.@refill ++ ++@node New Commands, New Bindings, Region Commands, Differences from Vi ++@subsection Some New Commands ++ ++Note that the keys below (except for @kbd{R}) are not used in Vi. ++ ++@table @kbd ++@item C-a ++@kindex 001 @kbd{C-a} (@code{vip-beginning-of-line}) ++Move point to the beginning of line. ++@item C-n ++@kindex 016 @kbd{C-n} (@code{vip-next-window}) ++If you have two or more windows in the screen, this key will move point to ++the next window. ++@item C-o ++@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) ++Insert a newline and leave point before it, and then enter insert mode. ++@item C-r ++@kindex 022 @kbd{C-r} (@code{isearch-backward}) ++Backward incremental search. ++@item C-s ++@kindex 023 @kbd{C-s} (@code{isearch-forward}) ++Forward incremental search. ++@item C-c ++@itemx C-x ++@itemx @key{ESC} ++@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) ++@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) ++@kindex 033 @kbd{ESC} (@code{vip-ESC}) ++These keys will exit from vi mode and return to emacs mode temporarily. If ++you hit one of these keys, Emacs will be in emacs mode and will believe ++that you hit that key in emacs mode. For example, if you hit @kbd{C-x} ++followed by @kbd{2}, then the current window will be split into 2 and you ++will be in vi mode again. ++@item \ ++@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) ++Escape to emacs mode. Hitting @kbd{\} will take you to emacs mode, and you ++can execute a single Emacs command. After executing the Emacs command you ++will be in vi mode again. You can give a count before typing @kbd{\}. ++Thus @kbd{5 \ *}, as well as @kbd{\ C-u 5 *}, will insert @samp{*****} ++before point. Similarly @kbd{1 0 \ C-p} will move the point 10 lines above ++the current line.@refill ++@item K ++@kindex 113 @kbd{K} (@code{vip-kill-buffer}) ++Kill current buffer if it is not modified. Useful when you selected a ++buffer which you did not want. ++@item Q ++@itemx R ++@kindex 121 @kbd{Q} (@code{vip-query-replace}) ++@kindex 122 @kbd{R} (@code{vip-replace-string}) ++@kbd{Q} is for query replace and @kbd{R} is for replace. By default, ++string to be replaced are treated literally. If you wish to do a regular ++expression replace, first do replace with empty string as the string to be ++replaced. In this way, you can toggle between vanilla and regular ++expression replacement. ++@item v ++@itemx V ++@kindex 166 @kbd{v} (@code{vip-find-file}) ++@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) ++These keys are used to Visit files. @kbd{v} will switch to a buffer ++visiting file whose name can be entered in the minibuffer. @kbd{V} is ++similar, but will use window different from the current window. ++@item # ++@kindex 0430 @kbd{#} (@code{vip-command-argument}) ++If followed by a certain character @var{ch}, it becomes an operator whose ++argument is the region determined by the motion command that follows. ++Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q} and ++@kbd{s}.@refill ++@item # c ++@kindex 0432 @kbd{# c} (@code{downcase-region}) ++Change upper-case characters in the region to lower case ++(@code{downcase-region}). ++@item # C ++@kindex 0431 @kbd{# C} (@code{upcase-region}) ++Change lower-case characters in the region to upper case. For instance, ++@kbd{# C 3 w} will capitalize 3 words from the current point ++(@code{upcase-region}). ++@item # g ++@kindex 0432 @kbd{# g} (@code{vip-global-execute}) ++Execute last keyboard macro for each line in the region ++(@code{vip-global-execute}).@refill ++@item # q ++@kindex 0432 @kbd{# q} (@code{vip-quote-region}) ++Insert specified string at the beginning of each line in the region ++(@code{vip-quote-region}). ++@item # s ++@kindex 0432 @kbd{# s} (@code{spell-region}) ++Check spelling of words in the region (@code{spell-region}). ++@item * ++@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) ++Call last keyboard macro. ++@end table ++ ++@node New Bindings, Window Commands, New Commands, Differences from Vi ++@subsection New Key Bindings ++ ++In VIP the meanings of some keys are entirely different from Vi. These key ++bindings are done deliberately in the hope that editing under Emacs will ++become easier. It is however possible to rebind these keys to functions ++which behave similarly as in Vi. @xref{Customizing Key Bindings}, for ++details. ++ ++@table @kbd ++@item C-g ++@itemx g ++@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) ++@kindex 147 @kbd{g} (@code{vip-info-on-file}) ++In Vi, @kbd{C-g} is used to get information about the file associated to ++the current buffer. Here, @kbd{g} will do that, and @kbd{C-g} is ++used to abort a command (this is for compatibility with emacs mode.) ++@item SPC ++@itemx @key{RET} ++@kindex 040 @kbd{SPC} (@code{vip-scroll}) ++@kindex 015 @kbd{RET} (@code{vip-scroll-back}) ++Now these keys will scroll up and down the text of current window. ++Convenient for viewing the text. ++@item s ++@itemx S ++@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) ++@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) ++They are used to switch to a specified buffer. Useful for switching to ++already existing buffer since buffer name completion is provided. Also ++a default buffer will be given as part of the prompt, to which you can ++switch by just typing @key{RET} key. @kbd{s} is used to select buffer ++in the current window, while @kbd{S} selects buffer in another window. ++@item C ++@itemx X ++@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) ++@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) ++These keys will exit from vi mode and return to emacs mode temporarily. ++If you type @kbd{C} (@kbd{X}), Emacs will be in emacs mode and will believe ++that you have typed @kbd{C-c} (@kbd{C-x}, resp.) in emacs mode. Moreover, ++if the following character you type is an upper-case letter, then Emacs ++will believe that you have typed the corresponding control character. ++You will be in vi mode again after the command is executed. For example, ++typing @kbd{X S} in vi mode is the same as typing @kbd{C-x C-s} in emacs ++mode. You get the same effect by typing @kbd{C-x C-s} in vi mode, but ++the idea here is that you can execute useful Emacs commands without typing ++control characters. For example, if you hit @kbd{X} (or @kbd{C-x}) followed ++by @kbd{2}, then the current window will be split into 2 and you will be in ++vi mode again.@refill ++@end table ++ ++In addition to these, @code{ctl-x-map} is slightly modified: ++ ++@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) ++ ++@table @kbd ++@item X 3 ++@itemx C-x 3 ++This is equivalent to @kbd{C-x 1 C-x 2} (1 + 2 = 3). ++@end table ++ ++@node Window Commands, Buffer Commands, New Bindings, Differences from Vi ++@subsection Window Commands ++ ++In this and following subsections, we give a summary of key bindings for ++basic functions related to windows, buffers and files. ++ ++@table @kbd ++@item C-n ++@kindex 016 @kbd{C-n} (@code{vip-next-window}) ++Switch to next window. ++@item X 1 ++@itemx C-x 1 ++@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) ++Delete other windows. ++@item X 2 ++@itemx C-x 2 ++@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) ++Split current window into two windows. ++@item X 3 ++@itemx C-x 3 ++@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) ++Show current buffer in two windows. ++@end table ++ ++@node Buffer Commands, File Commands, Window Commands, Differences from Vi ++@subsection Buffer Commands ++ ++@table @kbd ++@item s ++@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) ++Switch to the specified buffer in the current window ++(@code{vip-switch-to-buffer}). ++@item S ++@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) ++Switch to the specified buffer in another window ++(@code{vip-switch-to-buffer-other-window}). ++@item K ++@kindex 113 @kbd{K} (@code{vip-kill-buffer}) ++Kill the current buffer if it is not modified. ++@item X S ++@itemx C-x C-s ++@kindex 1302 @kbd{X S} (@code{save-buffer}) ++Save the current buffer in the file associated to the buffer. ++@end table ++ ++@node File Commands, Misc Commands, Buffer Commands, Differences from Vi ++@subsection File Commands ++ ++@table @kbd ++@item v ++@kindex 166 @kbd{v} (@code{vip-find-file}) ++Visit specified file in the current window. ++@item V ++@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) ++Visit specified file in another window. ++@item X W ++@itemx C-x C-w ++@kindex 1302 @kbd{X W} (@code{write-file}) ++Write current buffer into the specified file. ++@item X I ++@itemx C-x C-i ++@kindex 1302 @kbd{X I} (@code{insert-file}) ++ ++Insert specified file at point. ++@end table ++ ++@node Misc Commands, Vi Commands, File Commands, Differences from Vi ++@subsection Miscellaneous Commands ++ ++@table @kbd ++@item X ( ++@itemx C-x ( ++@kindex 1301 @kbd{X (} (@code{start-kbd-macro}) ++Start remembering keyboard macro. ++@item X ) ++@itemx C-x ) ++@kindex 1301 @kbd{X )} (@code{end-kbd-macro}) ++Finish remembering keyboard macro. ++@item * ++@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) ++Call last remembered keyboard macro. ++@item X Z ++@itemx C-x C-z ++@kindex 1302 @kbd{X Z} (@code{suspend-emacs}) ++Suspend Emacs. ++@item Z Z ++Exit Emacs. ++@itemx Q ++Query replace. ++@itemx R ++Replace. ++@end table ++ ++@node Vi Commands, Numeric Arguments, Misc Commands, Top ++@chapter Vi Commands ++ ++This chapter describes Vi commands other than Ex commands implemented in ++VIP. Except for the last section which discusses insert mode, all the ++commands described in this chapter are to be used in vi mode. ++ ++@menu ++* Numeric Arguments:: Many commands accept numeric arguments ++* Important Keys:: Some very important keys. ++* Buffers and Windows:: Commands for handling buffers and windows. ++* Files:: Commands for handling files. ++* Viewing the Buffer:: How you can view the current buffer. ++* Mark Commands:: Marking positions in a buffer. ++* Motion Commands:: Commands for moving point. ++* Searching and Replacing:: Commands for searching and replacing. ++* Modifying Commands:: Commands for modifying the buffer. ++* Other Vi Commands:: Miscellaneous Commands. ++* Commands in Insert Mode:: Commands for entering insert mode. ++@end menu ++ ++@node Numeric Arguments, Important Keys, Vi Commands, Vi Commands ++@section Numeric Arguments ++ ++@cindex numeric arguments ++@cindex count ++@kindex 061 @kbd{1} (numeric argument) ++@kindex 062 @kbd{2} (numeric argument) ++@kindex 063 @kbd{3} (numeric argument) ++@kindex 064 @kbd{4} (numeric argument) ++@kindex 065 @kbd{5} (numeric argument) ++@kindex 066 @kbd{6} (numeric argument) ++@kindex 067 @kbd{7} (numeric argument) ++@kindex 068 @kbd{8} (numeric argument) ++@kindex 069 @kbd{9} (numeric argument) ++ ++Most Vi commands accept a @dfn{numeric argument} which can be supplied as ++a prefix to the commands. A numeric argument is also called a @dfn{count}. ++In many cases, if a count is given, the command is executed that many times. ++For instance, @kbd{5 d d} deletes 5 lines while simple @kbd{d d} deletes a ++line. In this manual the metavariable @var{n} will denote a count.@refill ++ ++@node Important Keys, Buffers and Windows, Numeric Arguments, Vi Commands ++@section Important Keys ++ ++The keys @kbd{C-g} and @kbd{C-l} are unique in that their associated ++functions are the same in any of emacs, vi and insert mode. ++ ++@table @kbd ++@item C-g ++@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) ++Quit. Cancel running or partially typed command (@code{keyboard-quit}). ++@item C-l ++@kindex 014 @kbd{C-l} (@code{recenter}) ++Clear the screen and reprint everything (@code{recenter}). ++@end table ++ ++In Emacs many commands are bound to the key strokes that start with ++@kbd{C-x}, @kbd{C-c} and @key{ESC}. These commands can be ++accessed from vi mode as easily as from emacs mode.@refill ++ ++@table @kbd ++@item C-x ++@itemx C-c ++@itemx @key{ESC} ++@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) ++@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) ++@kindex 033 @kbd{ESC} (@code{vip-ESC}) ++Typing one of these keys have the same effect as typing it in emacs mode. ++Appropriate command will be executed according as the keys you type after ++it. You will be in vi mode again after the execution of the command. ++For instance, if you type @kbd{@key{ESC} <} (in vi mode) then the cursor will ++move to the beginning of the buffer and you will still be in vi mode. ++@item C ++@itemx X ++@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) ++@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) ++Typing one of these keys have the effect of typing the corresponding ++control character in emacs mode. Moreover, if you type an upper-case ++character following it, that character will also be translated to the ++corresponding control character. Thus typing @kbd{X W} in vi mode is the ++same as typing @kbd{C-x C-w} in emacs mode. You will be in vi mode again ++after the execution of a command. ++@item \ ++@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) ++Escape to emacs mode. Hitting the @kbd{\} key will take you to emacs mode, ++and you can execute a single Emacs command. After executing the ++Emacs command you will be in vi mode again. You can give a count before ++typing @kbd{\}. Thus @kbd{5 \ +}, as well as @kbd{\ C-u 5 +}, will insert ++@samp{+++++} before point.@refill ++@end table ++ ++@node Buffers and Windows, Files, Important Keys, Vi Commands ++@section Buffers and Windows ++ ++@cindex buffer ++@cindex selected buffer ++@cindex current buffer ++ ++In Emacs the text you edit is stored in a @dfn{buffer}. ++See GNU Emacs Manual, for details. There is always one @dfn{current} ++buffer, also called the @dfn{selected buffer}.@refill ++ ++@cindex window ++@cindex modified (buffer) ++ ++You can see the contents of buffers through @dfn{windows} created by Emacs. ++When you have multiple windows on the screen only one of them is selected. ++Each buffer has a unique name, and each window has a mode line which shows ++the name of the buffer associated with the window and other information ++about the status of the buffer. You can change the format of the mode ++line, but normally if you see @samp{**} at the beginning of a mode line it ++means that the buffer is @dfn{modified}. If you write out the content of ++the buffer to a file, then the buffer will become not modified. Also if ++you see @samp{%%} at the beginning of the mode line, it means that the file ++associated with the buffer is write protected. ++ ++We have the following commands related to windows and buffers. ++ ++@table @kbd ++@item C-n ++@kindex 016 @kbd{C-n} (@code{vip-next-window}) ++Move cursor to the next-window (@code{vip-next-window}). ++@item X 1 ++@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) ++Delete other windows and make the selected window fill the screen ++@*(@code{delete-other-windows}). ++@item X 2 ++@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) ++Split current window into two windows (@code{split-window-vertically}). ++@item X 3 ++@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) ++Show current buffer in two windows. ++@item s @var{buffer} @key{RET} ++@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) ++Select or create a buffer named @var{buffer} (@code{vip-switch-to-buffer}). ++@item S @var{buffer} @key{RET} ++@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) ++Similar but select a buffer named @var{buffer} in another window ++@*(@code{vip-switch-to-buffer-other-window}). ++@item K ++@kindex 113 @kbd{K} (@code{vip-kill-buffer}) ++Kill the current buffer if it is not modified or if it is not associated ++with a file @*(@code{vip-kill-buffer}). ++@item X B ++@kindex 1302 @kbd{X B} (@code{list-buffers}) ++List the existing buffers (@code{list-buffers}). ++@end table ++ ++@cindex buffer name completion ++ ++As @dfn{buffer name completion} is provided, you have only to type in ++initial substring of the buffer name which is sufficient to identify it ++among names of existing buffers. After that, if you hit @key{TAB} the rest ++of the buffer name will be supplied by the system, and you can confirm it ++by @key{RET}. The default buffer name to switch to will also be prompted, ++and you can select it by giving a simple @key{RET}. See GNU Emacs Manual ++for details of completion. ++ ++@node Files, Viewing the Buffer, Buffers and Windows, Vi Commands ++@section Files ++ ++We have the following commands related to files. They are used to visit, ++save and insert files. ++ ++@table @kbd ++@item v @var{file} @key{RET} ++@kindex 166 @kbd{v} (@code{vip-find-file}) ++Visit specified file in the current window (@code{vip-find-file}). ++@item V @var{file} @key{RET} ++@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) ++Visit specified file in another window (@code{vip-find-file-other-window}). ++@item X S ++@kindex 1302 @kbd{X S} (@code{save-buffer}) ++Save current buffer to the file associated with the buffer. If no file is ++associated with the buffer, the name of the file to write out the content ++of the buffer will be asked in the minibuffer. ++@item X W @var{file} @key{RET} ++@kindex 1302 @kbd{X W} (@code{write-file}) ++Write current buffer into a specified file. ++@item X I @var{file} @key{RET} ++@kindex 1302 @kbd{X I} (@code{insert-file}) ++Insert a specified file at point. ++@item g ++@kindex 147 @kbd{g} (@code{vip-info-on-file}) ++Give information on the file associated with the current buffer. Tell you ++the name of the file associated with the buffer, the line number of the ++current point and total line numbers in the buffer. If no file is ++associated with the buffer, this fact will be indicated by the null file ++name @samp{""}. ++@end table ++ ++@cindex visiting (a file) ++@cindex default directory ++ ++In Emacs, you can edit a file by @dfn{visiting} it. If you wish to visit a ++file in the current window, you can just type @kbd{v}. Emacs maintains the ++@dfn{default directory} which is specific to each buffer. Suppose, for ++instance, that the default directory of the current buffer is ++@file{/usr/masahiko/lisp/}. Then you will get the following prompt in the ++minibuffer.@refill ++@example ++visit file: /usr/masahiko/lisp/ ++@end example ++@noindent ++@cindex file name completion ++If you wish to visit, say, @file{vip.el} in this directory, then you can ++just type @samp{vip.el} followed by @key{RET}. If the file @file{vip.el} ++already exists in the directory, Emacs will visit that file, and if not, ++the file will be created. Emacs will use the file name (@file{vip.el}, in ++this case) as the name of the buffer visiting the file. In order to make ++the buffer name unique, Emacs may append @samp{<2>}, @samp{<3>} etc., to ++the buffer name. As the @dfn{file name completion} is provided here, you ++can sometime save typing. For instance, suppose there is only one file in the ++default directory whose name starts with @samp{v}, that is @samp{vip.el}. ++Then if you just type @kbd{v @key{TAB}} then it will be completed to ++@samp{vip.el}. Thus, in this case, you just have to type @kbd{v v @key{TAB} ++@key{RET}} to visit @file{/usr/masahiko/lisp/vip.el}. Continuing the ++example, let us now suppose that you wished to visit the file ++@file{/usr/masahiko/man/vip.texinfo}. Then to the same prompt which you get ++after you typed @kbd{v}, you can enter @samp{/usr/masahiko/man/vip.texinfo} or ++@samp{../man/vip.texinfo} followed by @key{RET}. ++ ++Use @kbd{V} instead of @kbd{v}, if you wish to visit a file in another ++window. ++ ++You can verify which file you are editing by typing @kbd{g}. (You can also ++type @kbd{X B} to get information on other buffers too.) If you type ++@kbd{g} you will get an information like below in the echo area:@refill ++@example ++"/usr/masahiko/man/vip.texinfo" line 921 of 1949 ++@end example ++ ++After you edited the buffer (@samp{vip.texinfo}, in our example) for a while, ++you may wish to save it in a file. If you wish to save it in the file ++associated with the buffer (@file{/usr/masahiko/man/vip.texinfo}, in this ++case), you can just say @kbd{X S}. If you wish to save it in another file, ++you can type @kbd{X W}. You will then get a similar prompt as you get for ++@kbd{v}, to which you can enter the file name.@refill ++ ++@node Viewing the Buffer, Mark Commands, Files, Vi Commands ++@section Viewing the Buffer ++ ++In this and next section we discuss commands for moving around in the ++buffer. These command do not change the content of the buffer. The ++following commands are useful for viewing the content of the current ++buffer. ++ ++@table @kbd ++@item @key{SPC} ++@itemx C-f ++@kindex 040 @kbd{SPC} (@code{vip-scroll}) ++@kindex 006 @kbd{C-f} (@code{vip-scroll-back}) ++Scroll text of current window upward almost full screen. You can go ++@i{forward} in the buffer by this command (@code{vip-scroll}). ++@item @key{RET} ++@itemx C-b ++@kindex 015 @kbd{RET} (@code{vip-scroll-back}) ++@kindex 002 @kbd{C-b} (@code{vip-scroll-back}) ++Scroll text of current window downward almost full screen. You can go ++@i{backward} in the buffer by this command (@code{vip-scroll-back}). ++@itemx C-d ++@kindex 004 @kbd{C-d} (@code{vip-scroll-up}) ++Scroll text of current window upward half screen. You can go ++@i{down} in the buffer by this command (@code{vip-scroll-down}). ++@itemx C-u ++@kindex 025 @kbd{C-u} (@code{vip-scroll-down}) ++Scroll text of current window downward half screen. You can go ++@i{up} in the buffer by this command (@code{vip-scroll-up}). ++@item C-y ++@kindex 031 @kbd{C-y} (@code{vip-scroll-down-one}) ++Scroll text of current window upward by one line (@code{vip-scroll-down-one}). ++@item C-e ++@kindex 005 @kbd{C-e} (@code{vip-scroll-up-one}) ++Scroll text of current window downward by one line (@code{vip-scroll-up-one}). ++@end table ++@noindent ++You can repeat these commands by giving a count. Thus, @kbd{2 @key{SPC}} ++has the same effect as @kbd{@key{SPC} @key{SPC}}. ++ ++The following commands reposition point in the window. ++ ++@table @kbd ++@item z H ++@itemx z @key{RET} ++@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) ++@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) ++Put point on the top (@i{home}) line in the window. So the current line ++becomes the top line in the window. Given a count @var{n}, point will be ++placed in the @var{n}-th line from top (@code{vip-line-to-top}). ++@item z M ++@itemx z . ++@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) ++@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) ++Put point on the @i{middle} line in the window. Given a count @var{n}, ++point will be placed in the @var{n}-th line from the middle line ++(@code{vip-line-to-middle}). ++@item z L ++@itemx z - ++@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) ++@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) ++Put point on the @i{bottom} line in the window. Given a count @var{n}, ++point will be placed in the @var{n}-th line from bottom ++(@code{vip-line-to-bottom}). ++@item C-l ++Center point in window and redisplay screen (@code{recenter}). ++@end table ++ ++@node Mark Commands, Motion Commands, Viewing the Buffer, Vi Commands ++@section Mark Commands ++ ++The following commands are used to mark positions in the buffer. ++ ++@table @kbd ++@item m @var{ch} ++@kindex 155 @kbd{m} (@code{vip-mark-point}) ++Store current point in the register @var{ch}. @var{ch} must be a ++lower-case @acronym{ASCII} letter. ++@item m < ++Set mark at the beginning of current buffer. ++@item m > ++Set mark at the end of current buffer. ++@item m . ++Set mark at point. ++@item m , ++Jump to mark (and pop mark off the mark ring). ++@end table ++ ++@cindex mark ring ++ ++Emacs uses the @dfn{mark ring} to store marked positions. The commands ++@kbd{m <}, @kbd{m >} and @kbd{m .}@: not only set mark but also add it as the ++latest element of the mark ring (replacing the oldest one). By repeating ++the command `@kbd{m ,}' you can visit older and older marked positions. You ++will eventually be in a loop as the mark ring is a ring. ++ ++@node Motion Commands, Searching and Replacing, Mark Commands, Vi Commands ++@section Motion Commands ++ ++Commands for moving around in the current buffer are collected here. These ++commands are used as an `argument' for the delete, change and yank commands ++to be described in the next section. ++ ++@table @kbd ++@item h ++@kindex 150 @kbd{h} (@code{vip-backward-char}) ++Move point backward by one character. Signal error if point is at the ++beginning of buffer, but (unlike Vi) do not complain otherwise ++(@code{vip-backward-char}). ++@item l ++@kindex 154 @kbd{l} (@code{vip-forward-char}) ++Move point backward by one character. Signal error if point is at the ++end of buffer, but (unlike Vi) do not complain otherwise ++(@code{vip-forward-char}). ++@item j ++@kindex 152 @kbd{j} (@code{vip-next-line}) ++Move point to the next line keeping the current column. If point is on the ++last line of the buffer, a new line will be created and point will move to ++that line (@code{vip-next-line}). ++@item k ++@kindex 153 @kbd{k} (@code{vip-previous-line}) ++Move point to the previous line keeping the current column ++(@code{vip-next-line}). ++@item + ++@kindex 053 @kbd{+} (@code{vip-next-line-at-bol}) ++Move point to the next line at the first non-white character. If point is ++on the last line of the buffer, a new line will be created and point will ++move to the beginning of that line (@code{vip-next-line-at-bol}). ++@item - ++@kindex 055 @kbd{-} (@code{vip-previous-line-at-bol}) ++Move point to the previous line at the first non-white character ++(@code{vip-previous-line-at-bol}). ++@end table ++@noindent ++If a count is given to these commands, the commands will be repeated that ++many times. ++ ++@table @kbd ++@item 0 ++@kindex 060 @kbd{0} (@code{vip-beginning-of-line}) ++Move point to the beginning of line (@code{vip-beginning-of-line}). ++@item ^ ++@kindex 136 @kbd{^} (@code{vip-bol-and-skip-white}) ++Move point to the first non-white character on the line ++(@code{vip-bol-and-skip-white}). ++@item $ ++@kindex 044 @kbd{$} (@code{vip-goto-eol}) ++Move point to the end of line (@code{vip-goto-eol}). ++@item @var{n} | ++@kindex 174 @kbd{|} (@code{vip-goto-col}) ++Move point to the @var{n}-th column on the line (@code{vip-goto-col}). ++@end table ++@noindent ++Except for the @kbd{|} command, these commands neglect a count. ++ ++@cindex word ++ ++@table @kbd ++@item w ++@kindex 167 @kbd{w} (@code{vip-forward-word}) ++Move point forward to the beginning of the next word ++(@code{vip-forward-word}). ++@item W ++@kindex 127 @kbd{W} (@code{vip-forward-Word}) ++Move point forward to the beginning of the next word, where a @dfn{word} is ++considered as a sequence of non-white characters (@code{vip-forward-Word}). ++@item b ++@kindex 142 @kbd{b} (@code{vip-backward-word}) ++Move point backward to the beginning of a word (@code{vip-backward-word}). ++@item B ++@kindex 102 @kbd{B} (@code{vip-backward-Word}) ++Move point backward to the beginning of a word, where a @i{word} is ++considered as a sequence of non-white characters (@code{vip-forward-Word}). ++@item e ++@kindex 145 @kbd{e} (@code{vip-end-of-word}) ++Move point forward to the end of a word (@code{vip-end-of-word}). ++@item E ++@kindex 105 @kbd{E} (@code{vip-end-of-Word}) ++Move point forward to the end of a word, where a @i{word} is ++considered as a sequence of non-white characters (@code{vip-end-of-Word}). ++@end table ++@noindent ++@cindex syntax table ++Here the meaning of the word `word' for the @kbd{w}, @kbd{b} and @kbd{e} ++commands is determined by the @dfn{syntax table} effective in the current ++buffer. Each major mode has its syntax mode, and therefore the meaning of ++a word also changes as the major mode changes. See GNU Emacs Manual for ++details of syntax table. ++ ++@table @kbd ++@item H ++@kindex 110 @kbd{H} (@code{vip-window-top}) ++Move point to the beginning of the @i{home} (top) line of the window. ++Given a count @var{n}, go to the @var{n}-th line from top ++(@code{vip-window-top}). ++@item M ++@kindex 115 @kbd{M} (@code{vip-window-middle}) ++Move point to the beginning of the @i{middle} line of the window. Given ++a count @var{n}, go to the @var{n}-th line from the middle line ++(@code{vip-window-middle}). ++@item L ++@kindex 114 @kbd{L} (@code{vip-window-bottom}) ++Move point to the beginning of the @i{lowest} (bottom) line of the ++window. Given count, go to the @var{n}-th line from bottom ++(@code{vip-window-bottom}). ++@end table ++@noindent ++These commands can be used to go to the desired line visible on the screen. ++ ++@table @kbd ++@item ( ++@kindex 050 @kbd{(} (@code{vip-backward-sentence}) ++Move point backward to the beginning of the sentence ++(@code{vip-backward-sentence}). ++@item ) ++@kindex 051 @kbd{)} (@code{vip-forward-sentence}) ++Move point forward to the end of the sentence ++(@code{vip-forward-sentence}). ++@item @{ ++@kindex 173 @kbd{@{} (@code{vip-backward-paragraph}) ++Move point backward to the beginning of the paragraph ++(@code{vip-backward-paragraph}). ++@item @} ++@kindex 175 @kbd{@}} (@code{vip-forward-paragraph}) ++Move point forward to the end of the paragraph ++(@code{vip-forward-paragraph}). ++@end table ++@noindent ++A count repeats the effect for these commands. ++ ++@table @kbd ++@item G ++@kindex 107 @kbd{G} (@code{vip-goto-line}) ++Given a count @var{n}, move point to the @var{n}-th line in the buffer on ++the first non-white character. Without a count, go to the end of the buffer ++(@code{vip-goto-line}). ++@item ` ` ++@kindex 140 @kbd{`} (@code{vip-goto-mark}) ++Exchange point and mark (@code{vip-goto-mark}). ++@item ` @var{ch} ++Move point to the position stored in the register @var{ch}. @var{ch} must ++be a lower-case letter. ++@item ' ' ++@kindex 047 @kbd{'} (@code{vip-goto-mark-and-skip-white}) ++Exchange point and mark, and then move point to the first non-white ++character on the line (@code{vip-goto-mark-and-skip-white}). ++@item ' @var{ch} ++Move point to the position stored in the register @var{ch} and skip to the ++first non-white character on the line. @var{ch} must be a lower-case letter. ++@item % ++@kindex 045 @kbd{%} (@code{vip-paren-match}) ++Move point to the matching parenthesis if point is looking at @kbd{(}, ++@kbd{)}, @kbd{@{}, @kbd{@}}, @kbd{[} or @kbd{]} ++@*(@code{vip-paren-match}). ++@end table ++@noindent ++The command @kbd{G} mark point before move, so that you can return to the ++original point by @kbd{` `}. The original point will also be stored in ++the mark ring. ++ ++The following commands are useful for moving points on the line. A count ++will repeat the effect. ++ ++@table @kbd ++@item f @var{ch} ++@kindex 146 @kbd{f} (@code{vip-find-char-forward}) ++Move point forward to the character @var{ch} on the line. Signal error if ++@var{ch} could not be found (@code{vip-find-char-forward}). ++@item F @var{ch} ++@kindex 106 @kbd{F} (@code{vip-find-char-backward}) ++Move point backward to the character @var{ch} on the line. Signal error if ++@var{ch} could not be found (@code{vip-find-char-backward}). ++@item t @var{ch} ++@kindex 164 @kbd{t} (@code{vip-goto-char-forward}) ++Move point forward upto the character @var{ch} on the line. Signal error if ++@var{ch} could not be found (@code{vip-goto-char-forward}). ++@item T @var{ch} ++@kindex 124 @kbd{T} (@code{vip-goto-char-backward}) ++Move point backward upto the character @var{ch} on the line. Signal error if ++@var{ch} could not be found (@code{vip-goto-char-backward}). ++@item ; ++@kindex 073 @kbd{;} (@code{vip-repeat-find}) ++Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command ++(@code{vip-repeat-find}). ++@item , ++@kindex 054 @kbd{,} (@code{vip-repeat-find-opposite}) ++Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command, in the ++opposite direction (@code{vip-repeat-find-opposite}). ++@end table ++ ++@node Searching and Replacing, Modifying Commands, Motion Commands, Vi Commands ++@section Searching and Replacing ++ ++Following commands are available for searching and replacing. ++ ++@cindex regular expression (search) ++ ++@table @kbd ++@item / @var{string} @key{RET} ++@kindex 057 @kbd{/} (@code{vip-search-forward}) ++Search the first occurrence of the string @var{string} forward starting ++from point. Given a count @var{n}, the @var{n}-th occurrence of ++@var{string} will be searched. If the variable @code{vip-re-search} has value ++@code{t} then @dfn{regular expression} search is done and the string ++matching the regular expression @var{string} is found. If you give an ++empty string as @var{string} then the search mode will change from vanilla ++search to regular expression search and vice versa ++(@code{vip-search-forward}). ++@item ? @var{string} @key{RET} ++@kindex 077 @kbd{?} (@code{vip-search-backward}) ++Same as @kbd{/}, except that search is done backward ++(@code{vip-search-backward}). ++@item n ++@kindex 156 @kbd{n} (@code{vip-search-next}) ++Search the previous search pattern in the same direction as before ++(@code{vip-search-next}). ++@item N ++@kindex 116 @kbd{N} (@code{vip-search-Next}) ++Search the previous search pattern in the opposite direction ++(@code{vip-search-Next}). ++@item C-s ++@kindex 023 @kbd{C-s} (@code{isearch-forward}) ++Search forward incrementally. See GNU Emacs Manual for details ++(@code{isearch-forward}). ++@item C-r ++@kindex 022 @kbd{C-r} (@code{isearch-backward}) ++Search backward incrementally (@code{isearch-backward}). ++@cindex vanilla (replacement) ++@cindex regular expression (replacement) ++@item R @var{string} RET @var{newstring} ++@kindex 122 @kbd{R} (@code{vip-replace-string}) ++There are two modes of replacement, @dfn{vanilla} and @dfn{regular expression}. ++If the mode is @i{vanilla} you will get a prompt @samp{Replace string:}, ++and if the mode is @i{regular expression} you will ge a prompt ++@samp{Replace regexp:}. The mode is initially @i{vanilla}, but you can ++toggle these modes by giving a null string as @var{string}. If the mode is ++vanilla, this command replaces every occurrence of @var{string} with ++@var{newstring}. If the mode is regular expression, @var{string} is ++treated as a regular expression and every string matching the regular ++expression is replaced with @var{newstring} (@code{vip-replace-string}). ++@item Q @var{string} RET @var{newstring} ++@kindex 121 @kbd{Q} (@code{vip-query-replace}) ++Same as @kbd{R} except that you will be asked form confirmation before each ++replacement ++@*(@code{vip-query-replace}). ++@item r @var{ch} ++@kindex 162 @kbd{r} (@code{vip-replace-char}) ++Replace the character point is looking at by the character @var{ch}. Give ++count, replace that many characters by @var{ch} (@code{vip-replace-char}). ++@end table ++@noindent ++The commands @kbd{/} and @kbd{?} mark point before move, so that you can ++return to the original point by @w{@kbd{` `}}. ++ ++@node Modifying Commands, Delete Commands, Searching and Replacing, Vi Commands ++@section Modifying Commands ++ ++In this section, commands for modifying the content of a buffer are ++described. These commands affect the region determined by a motion command ++which is given to the commands as their argument. ++ ++@cindex point commands ++@cindex line commands ++ ++We classify motion commands into @dfn{point commands} and ++@dfn{line commands}. The point commands are as follows: ++@example ++@kbd{h}, @kbd{l}, @kbd{0}, @kbd{^}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, @kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, @kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,} ++@end example ++@noindent ++The line commands are as follows: ++@example ++@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, @kbd{@}}, @kbd{G}, @kbd{'} ++@end example ++@noindent ++@cindex expanding (region) ++If a point command is given as an argument to a modifying command, the ++region determined by the point command will be affected by the modifying ++command. On the other hand, if a line command is given as an argument to a ++modifying command, the region determined by the line command will be ++enlarged so that it will become the smallest region properly containing the ++region and consisting of whole lines (we call this process @dfn{expanding ++the region}), and then the enlarged region will be affected by the modifying ++command. ++ ++@menu ++* Delete Commands:: Commands for deleting text. ++* Yank Commands:: Commands for yanking text in Vi's sense. ++* Put Back Commands:: Commands for putting back deleted/yanked text. ++* Change Commands:: Commands for changing text. ++* Repeating and Undoing Modifications:: ++@end menu ++@node Delete Commands, Yank Commands, Modifying Commands, Modifying Commands ++@subsection Delete Commands ++ ++@table @kbd ++@item d @var{motion-command} ++@kindex 1440 @kbd{d} (@code{vip-command-argument}) ++Delete the region determined by the motion command @var{motion-command}. ++@end table ++@noindent ++For example, @kbd{d $} will delete the region between point and end of ++current line since @kbd{$} is a point command that moves point to end of line. ++@kbd{d G} will delete the region between the beginning of current line and ++end of the buffer, since @kbd{G} is a line command. A count given to the ++command above will become the count for the associated motion command. ++Thus, @kbd{3 d w} will delete three words. ++ ++@kindex 042 @kbd{"} (@code{vip-command-argument}) ++It is also possible to save the deleted text into a register you specify. ++For example, you can say @kbd{" t 3 d w} to delete three words and save it ++to register @kbd{t}. The name of a register is a lower-case letter between ++@kbd{a} and @kbd{z}. If you give an upper-case letter as an argument to ++a delete command, then the deleted text will be appended to the content of ++the register having the corresponding lower-case letter as its name. So, ++@kbd{" T d w} will delete a word and append it to register @kbd{t}. Other ++modifying commands also accept a register name as their argument, and we ++will not repeat similar explanations. ++ ++We have more delete commands as below. ++ ++@table @kbd ++@item d d ++@kindex 1442 @kbd{d d} ++Delete a line. Given a count @var{n}, delete @var{n} lines. ++@item d r ++@kindex 1442 @kbd{d r} ++Delete current region. ++@item d R ++@kindex 1441 @kbd{d R} ++Expand current region and delete it. ++@item D ++@kindex 104 @kbd{D} (@code{vip-kill-line}) ++Delete to the end of a line (@code{vip-kill-line}). ++@item x ++@kindex 170 @kbd{x} (@code{vip-delete-char}) ++Delete a character after point. Given @var{n}, delete @var{n} characters ++(@code{vip-delete-char}). ++@item @key{DEL} ++@kindex 177 @kbd{DEL} (@code{vip-delete-backward-char}) ++Delete a character before point. Given @var{n}, delete @var{n} characters ++(@code{vip-delete-backward-char}). ++@end table ++ ++@node Yank Commands, Put Back Commands, Delete Commands, Modifying Commands ++@subsection Yank Commands ++ ++@cindex yank ++ ++Yank commands @dfn{yank} a text of buffer into a (usually anonymous) register. ++Here the word `yank' is used in Vi's sense. Thus yank commands do not ++alter the content of the buffer, and useful only in combination with ++commands that put back the yanked text into the buffer. ++ ++@table @kbd ++@item y @var{motion-command} ++@kindex 1710 @kbd{y} (@code{vip-command-argument}) ++Yank the region determined by the motion command @var{motion-command}. ++@end table ++@noindent ++For example, @kbd{y $} will yank the text between point and the end of line ++into an anonymous register, while @kbd{"c y $} will yank the same text into ++register @kbd{c}. ++ ++Use the following command to yank consecutive lines of text. ++ ++@table @kbd ++@item y y ++@itemx Y ++@kindex 131 @kbd{Y} (@code{vip-yank-line}) ++@kindex 1712 @kbd{y y} (@code{vip-yank-line}) ++Yank a line. Given @var{n}, yank @var{n} lines (@code{vip-yank-line}). ++@item y r ++@kindex 1712 @kbd{y r} ++Yank current region. ++@item y R ++@kindex 1711 @kbd{y R} ++Expand current region and yank it. ++@end table ++ ++@node Put Back Commands, Change Commands, Yank Commands, Modifying Commands ++@subsection Put Back Commands ++Deleted or yanked texts can be put back into the buffer by the command ++below. ++ ++@table @kbd ++@item p ++@kindex 160 @kbd{p} (@code{vip-put-back}) ++Insert, after the character point is looking at, most recently ++deleted/yanked text from anonymous register. Given a register name ++argument, the content of the named register will be put back. Given a ++count, the command will be repeated that many times. This command also ++checks if the text to put back ends with a new line character, and if so ++the text will be put below the current line (@code{vip-put-back}). ++@item P ++@kindex 120 @kbd{P} (@code{vip-Put-back}) ++Insert at point most recently deleted/yanked text from anonymous register. ++Given a register name argument, the content of the named register will ++be put back. Given a count, the command will be repeated that many times. ++This command also checks if the text to put back ends with a new line ++character, and if so the text will be put above the current line rather ++than at point (@code{vip-Put-back}). ++@end table ++@noindent ++@cindex number register ++Thus, @kbd{" c p} will put back the content of the register @kbd{c} into the ++buffer. It is also possible to specify @dfn{number register} which is a ++numeral between @kbd{1} and @kbd{9}. If the number register @var{n} is ++specified, @var{n}-th previously deleted/yanked text will be put back. It ++is an error to specify a number register for the delete/yank commands. ++ ++@node Change Commands, Repeating and Undoing Modifications, Put Back Commands, Modifying Commands ++@subsection Change Commands ++ ++Most commonly used change command takes the following form. ++ ++@table @kbd ++@item c @var{motion-command} ++@kindex 1430 @kbd{c} (@code{vip-command-argument}) ++Replace the content of the region determined by the motion command ++@var{motion-command} by the text you type. If the motion command is a ++point command then you will type the text into minibuffer, and if the ++motion command is a line command then the region will be deleted first and ++you can insert the text in @var{insert mode}. ++@end table ++@noindent ++For example, if point is at the beginning of a word @samp{foo} and you ++wish to change it to @samp{bar}, you can type @kbd{c w}. Then, as @kbd{w} ++is a point command, you will get the prompt @samp{foo =>} in the ++minibuffer, for which you can type @kbd{b a r @key{RET}} to complete the change ++command.@refill ++ ++@table @kbd ++@item c c ++@kindex 1432 @kbd{c c} ++Change a line. Given a count, that many lines are changed. ++@item c r ++@kindex 1432 @kbd{c r} ++Change current region. ++@item c R ++@kindex 1431 @kbd{c R} ++Expand current region and change it. ++@end table ++ ++@node Repeating and Undoing Modifications, Other Vi Commands, Change Commands, Modifying Commands ++@subsection Repeating and Undoing Modifications ++ ++VIP records the previous modifying command, so that it is easy to repeat ++it. It is also very easy to undo changes made by modifying commands. ++ ++@table @kbd ++@item u ++@kindex 165 @kbd{u} (@code{vip-undo}) ++Undo the last change. You can undo more by repeating undo by the repeat ++command @samp{.}. For example, you can undo 5 previous changes by typing ++@samp{u....}. If you type @samp{uu}, then the second @samp{u} undoes the ++first undo command (@code{vip-undo}). ++@item . ++@kindex 056 @kbd{.} (@code{vip-repeat}) ++Repeat the last modifying command. Given count @var{n} it becomes the new ++count for the repeated command. Otherwise, the count for the last ++modifying command is used again (@code{vip-repeat}). ++@end table ++ ++@node Other Vi Commands, Commands in Insert Mode, Repeating and Undoing Modifications, Vi Commands ++@section Other Vi Commands ++ ++Miscellaneous Vi commands are collected here. ++ ++@table @kbd ++@item Z Z ++@kindex 132 @kbd{Z Z} (@code{save-buffers-kill-emacs}) ++Exit Emacs. If modified buffers exist, you will be asked whether you wish ++to save them or not (@code{save-buffers-kill-emacs}). ++@item !@: @var{motion-command} @var{format-command} ++@itemx @var{n} !@: !@: @var{format-command} ++@kindex 041 @kbd{!} (@code{vip-command-argument}) ++The region determined by the motion command @var{motion-command} will be ++given to the shell command @var{format-command} and the region will be ++replaced by its output. If a count is given, it will be passed to ++@var{motion-command}. For example, @samp{3!Gsort} will sort the region ++between point and the 3rd line. If @kbd{!} is used instead of ++@var{motion-command} then @var{n} lines will be processed by ++@var{format-command} (@code{vip-command-argument}). ++@item J ++@kindex 112 @kbd{J} (@code{vip-join-lines}) ++Join two lines. Given count, join that many lines. A space will be ++inserted at each junction (@code{vip-join-lines}). ++@item < @var{motion-command} ++@itemx @var{n} < < ++@kindex 074 @kbd{<} (@code{vip-command-argument}) ++Shift region determined by the motion command @var{motion-command} to ++left by @var{shift-width} (default is 8). If @kbd{<} is used instead of ++@var{motion-command} then shift @var{n} lines ++@*(@code{vip-command-argument}). ++@item > @var{motion-command} ++@itemx @var{n} > > ++@kindex 076 @kbd{>} (@code{vip-command-argument}) ++Shift region determined by the motion command @var{motion-command} to ++right by @var{shift-width} (default is 8). If @kbd{<} is used instead of ++@var{motion-command} then shift @var{n} lines ++@*(@code{vip-command-argument}). ++@item = @var{motion-command} ++@kindex 075 @kbd{=} (@code{vip-command-argument}) ++Indent region determined by the motion command @var{motion-command}. If ++@kbd{=} is used instead of @var{motion-command} then indent @var{n} lines ++(@code{vip-command-argument}). ++@item * ++@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) ++Call last remembered keyboard macro. ++@item # ++A new vi operator. @xref{New Commands}, for more details. ++@end table ++ ++The following keys are reserved for future extensions, and currently ++assigned to a function that just beeps (@code{vip-nil}). ++ ++@kindex 046 @kbd{&} (@code{vip-nil}) ++@kindex 100 @kbd{@@} (@code{vip-nil}) ++@kindex 125 @kbd{U} (@code{vip-nil}) ++@kindex 133 @kbd{[} (@code{vip-nil}) ++@kindex 135 @kbd{]} (@code{vip-nil}) ++@kindex 137 @kbd{_} (@code{vip-nil}) ++@kindex 161 @kbd{q} (@code{vip-nil}) ++@kindex 176 @kbd{~} (@code{vip-nil}) ++ ++@example ++&, @@, U, [, ], _, q, ~ ++@end example ++ ++VIP uses a special local keymap to interpret key strokes you enter in vi ++mode. The following keys are bound to @var{nil} in the keymap. Therefore, ++these keys are interpreted by the global keymap of Emacs. We give below a ++short description of the functions bound to these keys in the global ++keymap. See GNU Emacs Manual for details. ++ ++@table @kbd ++@item C-@@ ++@kindex 000 @kbd{C-@@} (@code{set-mark-command}) ++Set mark and push previous mark on mark ring (@code{set-mark-command}). ++@item TAB ++@kindex 011 TAB (@code{indent-for-tab-command}) ++Indent line for current major mode (@code{indent-for-tab-command}). ++@item C-j ++@kindex 012 @kbd{C-j} (@code{newline-and-indent}) ++Insert a newline, then indent according to mode (@code{newline-and-indent}). ++@item C-k ++@kindex 013 @kbd{C-k} (@code{kill-line}) ++Kill the rest of the current line; before a newline, kill the newline. ++With a numeric argument, kill that many lines from point. Negative arguments ++kill lines backward (@code{kill-line}). ++@item C-l ++@kindex 014 @kbd{C-l} (@code{recenter}) ++Clear the screen and reprint everything (@code{recenter}). ++@item @var{n} C-p ++@kindex 020 @kbd{C-p} (@code{previous-line}) ++Move cursor vertically up @var{n} lines (@code{previous-line}). ++@item C-q ++@kindex 021 @kbd{C-q} (@code{quoted-insert}) ++Read next input character and insert it. Useful for inserting control ++characters ++@*(@code{quoted-insert}). ++@item C-r ++@kindex 022 @kbd{C-r} (@code{isearch-backward}) ++Search backward incrementally (@code{isearch-backward}). ++@item C-s ++@kindex 023 @kbd{C-s} (@code{isearch-forward}) ++Search forward incrementally (@code{isearch-forward}). ++@item @var{n} C-t ++@kindex 024 @kbd{C-t} (@code{transpose-chars}) ++Interchange characters around point, moving forward one character. With ++count @var{n}, take character before point and drag it forward past @var{n} ++other characters. If no argument and at end of line, the previous two ++characters are exchanged (@code{transpose-chars}). ++@item @var{n} C-v ++@kindex 026 @kbd{C-v} (@code{scroll-up}) ++Scroll text upward @var{n} lines. If @var{n} is not given, scroll near ++full screen (@code{scroll-up}). ++@item C-w ++@kindex 027 @kbd{C-w} (@code{kill-region}) ++Kill between point and mark. The text is save in the kill ring. The ++command @kbd{P} or @kbd{p} can retrieve it from kill ring ++(@code{kill-region}). ++@end table ++ ++@node Commands in Insert Mode, Ex Commands, Other Vi Commands, Vi Commands ++@section Insert Mode ++ ++You can enter insert mode by one of the following commands. In addition to ++these, you will enter insert mode if you give a change command with a line ++command as the motion command. Insert commands are also modifying commands ++and you can repeat them by the repeat command @kbd{.} (@code{vip-repeat}). ++ ++@table @kbd ++@item i ++@kindex 151 @kbd{i} (@code{vip-insert}) ++Enter insert mode at point (@code{vip-insert}). ++@item I ++@kindex 111 @kbd{I} (@code{vip-Insert}) ++Enter insert mode at the first non white character on the line ++(@code{vip-Insert}). ++@item a ++@kindex 141 @kbd{a} (@code{vip-append}) ++Move point forward by one character and then enter insert mode ++(@code{vip-append}). ++@item A ++@kindex 101 @kbd{A} (@code{vip-Append}) ++Enter insert mode at end of line (@code{vip-Append}). ++@item o ++@kindex 157 @kbd{o} (@code{vip-open-line}) ++Open a new line below the current line and enter insert mode ++(@code{vip-open-line}). ++@item O ++@kindex 117 @kbd{O} (@code{vip-Open-line}) ++Open a new line above the current line and enter insert mode ++(@code{vip-Open-line}). ++@item C-o ++@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) ++Insert a newline and leave point before it, and then enter insert mode ++@*(@code{vip-open-line-at-point}). ++@end table ++ ++Insert mode is almost like emacs mode. Only the following 4 keys behave ++differently from emacs mode. ++ ++@table @kbd ++@item @key{ESC} ++@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) ++This key will take you back to vi mode (@code{vip-change-mode-to-vi}). ++@item C-h ++@kindex 010 @kbd{C-h} (@code{delete-backward-char}) (insert mode) ++Delete previous character (@code{delete-backward-char}). ++@item C-w ++@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) ++Delete previous word (@code{vip-delete-backward-word}). ++@item C-z ++@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) ++This key simulates @key{ESC} key in emacs mode. For instance, typing ++@kbd{C-z x} in insert mode is the same as typing @kbd{ESC x} in emacs mode ++(@code{vip-ESC}). ++@end table ++@noindent ++You can also bind @kbd{C-h} to @code{help-command} if you like. ++(@xref{Customizing Key Bindings}, for details.) Binding @kbd{C-h} to ++@code{help-command} has the effect of making the meaning of @kbd{C-h} ++uniform among emacs, vi and insert modes. ++ ++When you enter insert mode, VIP records point as the start point of ++insertion, and when you leave insert mode the region between point and ++start point is saved for later use by repeat command etc. Therefore, repeat ++command will not really repeat insertion if you move point by emacs ++commands while in insert mode. ++ ++@node Ex Commands, Ex Command Reference, Commands in Insert Mode, Top ++@chapter Ex Commands ++ ++@kindex 072 @kbd{:} (@code{vip-ex}) ++ ++In vi mode, you can execute an Ex command @var{ex-command} by typing: ++@example ++@kbd{:@: @var{ex-command} @key{RET}} ++@end example ++Every Ex command follows the following pattern: ++@example ++@var{address command} @kbd{!}@: @var{parameters count flags} ++@end example ++@noindent ++@cindex address ++where all parts are optional. For the syntax of @dfn{address}, the reader ++is referred to the reference manual of Ex. ++ ++@cindex magic ++@cindex regular expression ++ ++In the current version of VIP, searching by Ex commands is always ++@dfn{magic}. That is, search patterns are always treated as @dfn{regular ++expressions}. For example, a typical forward search would be invoked by ++@kbd{:/@var{pat}/}. If you wish to include @samp{/} as part of ++@var{pat} you must preceded it by @samp{\}. VIP strips off these @kbd{\}'s ++before @kbd{/} and the resulting @var{pat} becomes the actual search ++pattern. Emacs provides a different and richer class or regular ++expressions than Vi/Ex, and VIP uses Emacs' regular expressions. See GNU ++Emacs Manual for details of regular expressions. ++ ++Several Ex commands can be entered in a line by separating them by a pipe ++character @samp{|}. ++ ++@menu ++* Ex Command Reference:: Explain all the Ex commands available in VIP. ++@end menu ++@node Ex Command Reference, Customization, Ex Commands, Ex Commands ++@section Ex Command Reference ++In this section we briefly explain all the Ex commands supported by VIP. ++Most Ex commands expect @var{address} as their argument, and they use ++default addresses if they are not explicitly given. In the following, such ++default addresses will be shown in parentheses. ++ ++Most command names can and preferably be given in abbreviated forms. In ++the following, optional parts of command names will be enclosed in ++brackets. For example, @samp{co[py]} will mean that copy command can be ++give as @samp{co} or @samp{cop} or @samp{copy}. ++ ++If @var{command} is empty, point will move to the beginning of the line ++specified by the @var{address}. If @var{address} is also empty, point will ++move to the beginning of the current line. ++ ++@cindex flag ++ ++Some commands accept @dfn{flags} which are one of @kbd{p}, @kbd{l} and ++@kbd{#}. If @var{flags} are given, the text affected by the commands will ++be displayed on a temporary window, and you will be asked to hit return to ++continue. In this way, you can see the text affected by the commands ++before the commands will be executed. If you hit @kbd{C-g} instead of ++@key{RET} then the commands will be aborted. Note that the meaning of ++@var{flags} is different in VIP from that in Vi/Ex. ++ ++@table @kbd ++@item (.,.@:) co[py] @var{addr} @var{flags} ++@itemx (.,.@:) t @var{addr} @var{flags} ++Place a copy of specified lines after @var{addr}. If @var{addr} is ++@kbd{0}, it will be placed before the first line. ++@item (.,.@:) d[elete] @var{register} @var{count} @var{flags} ++Delete specified lines. Text will be saved in a named @var{register} if a ++lower-case letter is given, and appended to a register if a capital letter is ++given. ++@item e[dit] !@: +@var{addr} @var{file} ++@itemx e[x] !@: +@var{addr} @var{file} ++@itemx vi[sual] !@: +@var{addr} @var{file} ++Edit a new file @var{file} in the current window. The command will abort ++if current buffer is modified, which you can override by giving @kbd{!}. ++If @kbd{+}@var{addr} is given, @var{addr} becomes the current line. ++@item file ++Give information about the current file. ++@item (1,$) g[lobal] !@: /@var{pat}/ @var{cmds} ++@itemx (1,$) v /@var{pat}/ @var{cmds} ++Among specified lines first mark each line which matches the regular ++expression @var{pat}, and then execute @var{cmds} on each marked line. ++If @kbd{!}@: is given, @var{cmds} will be executed on each line not matching ++@var{pat}. @kbd{v} is same as @kbd{g!}. ++@item (.,.+1) j[oin] !@: @var{count} @var{flags} ++Join specified lines into a line. Without @kbd{!}, a space character will ++be inserted at each junction. ++@item (.@:) k @var{ch} ++@itemx (.@:) mar[k] @var{ch} ++Mark specified line by a lower-case character @var{ch}. Then the ++addressing form @kbd{'}@var{ch} will refer to this line. No white space is ++required between @kbd{k} and @var{ch}. A white space is necessary between ++@kbd{mark} and @var{ch}, however. ++@item map @var{ch} @var{rhs} ++Define a macro for vi mode. After this command, the character @var{ch} ++will be expanded to @var{rhs} in vi mode. ++@item (.,.@:) m[ove] @var{addr} ++Move specified lines after @var{addr}. ++@item (.@:) pu[t] @var{register} ++Put back previously deleted or yanked text. If @var{register} is given, ++the text saved in the register will be put back; otherwise, last deleted or ++yanked text will be put back. ++@item q[uit] ! ++Quit from Emacs. If modified buffers with associated files exist, you will ++be asked whether you wish to save each of them. At this point, you may ++choose not to quit, by hitting @kbd{C-g}. If @kbd{!}@: is given, exit from ++Emacs without saving modified buffers. ++@item (.@:) r[ead] @var{file} ++Read in the content of the file @var{file} after the specified line. ++@item (.@:) r[ead] !@: @var{command} ++Read in the output of the shell command @var{command} after the specified ++line. ++@item se[t] ++Set a variable's value. @xref{Customizing Constants}, for the list of variables ++you can set. ++@item sh[ell] ++Run a subshell in a window. ++@item (.,.@:) s[ubstitute] /@var{pat}/@var{repl}/ @var{options} @var{count} @var{flags} ++@itemx (.,.@:) & @var{options} @var{count} @var{flags} ++On each specified line, the first occurrence of string matching regular ++expression @var{pat} is replaced by replacement pattern @var{repl}. Option ++characters are @kbd{g} and @kbd{c}. If global option character @kbd{g} ++appears as part of @var{options}, all occurrences are substituted. If ++confirm option character @kbd{c} appears, you will be asked to give ++confirmation before each substitution. If @kbd{/@var{pat}/@var{repl}/} is ++missing, the last substitution is repeated. ++@item st[op] ++Suspend Emacs. ++@item ta[g] @var{tag} ++@cindex tag ++@cindex selected tags table ++Find first definition of @var{tag}. If no @var{tag} is given, previously ++given @var{tag} is used and next alternate definition is find. By default, ++the file @file{TAGS} in the current directory becomes the @dfn{selected tags ++table}. You can select another tags table by @kbd{set} command. ++@xref{Customizing Constants}, for details. ++@item und[o] ++Undo the last change. ++@item unm[ap] @var{ch} ++The macro expansion associated with @var{ch} is removed. ++@item ve[rsion] ++Tell the version number of VIP. ++@item (1,$) w[rite] !@: @var{file} ++Write out specified lines into file @var{file}. If no @var{file} is given, ++text will be written to the file associated to the current buffer. Unless ++@kbd{!}@: is given, if @var{file} is different from the file associated to ++the current buffer and if the file @var{file} exists, the command will not ++be executed. Unlike Ex, @var{file} becomes the file associated to the ++current buffer. ++@item (1,$) w[rite]>> @var{file} ++Write out specified lines at the end of file @var{file}. @var{file} ++becomes the file associated to the current buffer. ++@item (1,$) wq !@: @var{file} ++Same as @kbd{write} and then @kbd{quit}. If @kbd{!}@: is given, same as ++@kbd{write !}@: then @kbd{quit}. ++@item (.,.) y[ank] @var{register} @var{count} ++Save specified lines into register @var{register}. If no register is ++specified, text will be saved in an anonymous register. ++@item @var{addr} !@: @var{command} ++Execute shell command @var{command}. The output will be shown in a new ++window. If @var{addr} is given, specified lines will be used as standard ++input to @var{command}. ++@item ($) = ++Print the line number of the addressed line. ++@item (.,.) > @var{count} @var{flags} ++Shift specified lines to the right. The variable @code{vip-shift-width} ++(default value is 8) determines the amount of shift. ++@item (.,.) < @var{count} @var{flags} ++Shift specified lines to the left. The variable @code{vip-shift-width} ++(default value is 8) determines the amount of shift. ++@item (.,.@:) ~ @var{options} @var{count} @var{flags} ++Repeat the previous @kbd{substitute} command using previous search pattern ++as @var{pat} for matching. ++@end table ++ ++The following Ex commands are available in Vi, but not implemented in VIP. ++@example ++@kbd{abbreviate}, @kbd{list}, @kbd{next}, @kbd{print}, @kbd{preserve}, @kbd{recover}, @kbd{rewind}, @kbd{source}, ++@kbd{unabbreviate}, @kbd{xit}, @kbd{z} ++@end example ++ ++@node Customization, Customizing Constants, Ex Command Reference, Top ++@chapter Customization ++ ++If you have a file called @file{.vip} in your home directory, then it ++will also be loaded when VIP is loaded. This file is thus useful for ++customizing VIP. ++ ++@menu ++* Customizing Constants:: How to change values of constants. ++* Customizing Key Bindings:: How to change key bindings. ++@end menu ++ ++@node Customizing Constants, Customizing Key Bindings, Customization, Customization ++@section Customizing Constants ++An easy way to customize VIP is to change the values of constants used ++in VIP. Here is the list of the constants used in VIP and their default ++values. ++ ++@table @code ++@item vip-shift-width 8 ++The number of columns shifted by @kbd{>} and @kbd{<} command. ++@item vip-re-replace nil ++If @code{t} then do regexp replace, if @code{nil} then do string replace. ++@item vip-search-wrap-around t ++If @code{t}, search wraps around the buffer. ++@item vip-re-search nil ++If @code{t} then search is reg-exp search, if @code{nil} then vanilla ++search. ++@item vip-case-fold-search nil ++If @code{t} search ignores cases. ++@item vip-re-query-replace nil ++If @code{t} then do reg-exp replace in query replace. ++@item vip-open-with-indent nil ++If @code{t} then indent to the previous current line when open a new line ++by @kbd{o} or @kbd{O} command. ++@item vip-tags-file-name "TAGS" ++The name of the file used as the tags table. ++@item vip-help-in-insert-mode nil ++If @code{t} then @key{C-h} is bound to @code{help-command} in insert mode, ++if @code{nil} then it sis bound to @code{delete-backward-char}. ++@end table ++@noindent ++You can reset these constants in VIP by the Ex command @kbd{set}. Or you ++can include a line like this in your @file{.vip} file: ++@example ++(setq vip-case-fold-search t) ++@end example ++ ++@node Customizing Key Bindings,, Customizing Constants, Customization ++@section Customizing Key Bindings ++ ++@cindex local keymap ++ ++VIP uses @code{vip-command-mode-map} as the @dfn{local keymap} for vi mode. ++For example, in vi mode, @key{SPC} is bound to the function ++@code{vip-scroll}. But, if you wish to make @key{SPC} and some other keys ++ behave like Vi, you can include the following lines in your @file{.vip} ++file. ++ ++@example ++(define-key vip-command-mode-map "\C-g" 'vip-info-on-file) ++(define-key vip-command-mode-map "\C-h" 'vip-backward-char) ++(define-key vip-command-mode-map "\C-m" 'vip-next-line-at-bol) ++(define-key vip-command-mode-map " " 'vip-forward-char) ++(define-key vip-command-mode-map "g" 'vip-keyboard-quit) ++(define-key vip-command-mode-map "s" 'vip-substitute) ++(define-key vip-command-mode-map "C" 'vip-change-to-eol) ++(define-key vip-command-mode-map "R" 'vip-change-to-eol) ++(define-key vip-command-mode-map "S" 'vip-substitute-line) ++(define-key vip-command-mode-map "X" 'vip-delete-backward-char) ++@end example ++ ++@node GNU Free Documentation License,,, Top ++@appendix GNU Free Documentation License ++@include doclicense.texi ++ ++ ++@unnumbered Key Index ++ ++@printindex ky ++ ++@unnumbered Concept Index ++@printindex cp ++ ++@bye ++ ++@ignore ++ arch-tag: 7c5d17b9-1d21-4261-a88a-b9fdbbf1020b ++@end ignore +diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi +new file mode 100644 +index 0000000..11f8f21 +--- /dev/null ++++ b/doc/misc/viper.texi +@@ -0,0 +1,4547 @@ ++% -*-texinfo-*- ++\input texinfo ++ ++@comment Using viper.info instead of viper in setfilename breaks DOS. ++@comment @setfilename viper ++@comment @setfilename viper.info ++@setfilename ../../info/viper ++ ++@copying ++Copyright @copyright{} 1995, 1996, 1997, 2001, 2002, 2003, 2004, ++2005, 2006, 2007, 2008, 2009 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 Emacs ++@direntry ++* VIPER: (viper). The newest Emacs VI-emulation mode. ++ (also, A VI Plan for Emacs Rescue ++ or the VI PERil.) ++@end direntry ++ ++@finalout ++ ++@titlepage ++@title Viper Is a Package for Emacs Rebels ++@subtitle a Vi emulator for Emacs ++@subtitle November 2008, Viper Version 3.11.2 ++ ++@author Michael Kifer (Viper) ++@author Aamod Sane (VIP 4.4) ++@author Masahiko Sato (VIP 3.5) ++ ++@page ++@vskip 0pt plus 1filll ++@insertcopying ++@end titlepage ++ ++@contents ++ ++@ifnottex ++@node Top, Overview,, (DIR) ++ ++@unnumbered Viper ++ ++We believe that one or more of the following statements are adequate ++descriptions of Viper: ++ ++@example ++Viper Is a Package for Emacs Rebels; ++it is a VI Plan for Emacs Rescue ++and/or a venomous VI PERil. ++@end example ++ ++Technically speaking, Viper is a Vi emulation package for Emacs. It ++implements all Vi and Ex commands, occasionally improving on them and ++adding many new features. It gives the user the best of both worlds: Vi ++keystrokes for editing combined with the power of the Emacs environment. ++ ++Viper emulates Vi at several levels, from the one that closely follows Vi ++conventions to the one that departs from many of them. It has many ++customizable options, which can be used to tailor Viper to the work habits ++of various users. ++This manual describes Viper, concentrating on the differences from Vi and ++new features of Viper. ++ ++Viper, formerly known as VIP-19, was written by Michael Kifer. It is based ++on VIP version 3.5 by Masahiko Sato and VIP version 4.4 by Aamod Sane. ++About 15% of the code still comes from those older packages. ++ ++Viper is intended to be usable without reading this manual --- the defaults ++are set to make Viper as close to Vi as possible. At startup, Viper will ++try to set the most appropriate default environment for you, based on ++your familiarity with Emacs. It will also tell you the basic GNU Emacs window ++management commands to help you start immediately. ++ ++Although this manual explains how to customize Viper, some basic ++familiarity with Emacs Lisp is a plus. ++ ++It is recommended that you read the Overview node. The other nodes may ++be visited as needed. ++ ++Comments and bug reports are welcome. ++@code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. ++Please use the Ex command @kbd{:submitReport} for this purpose.@refill ++ ++@insertcopying ++@end ifnottex ++ ++@menu ++* Overview:: Read for a smoother start ++* Improvements over Vi:: New features, Improvements ++* Customization:: How to customize Viper ++* Commands:: Vi and Ex Commands ++ ++* Key Index:: Index of Vi and Ex Commands ++* Function Index:: Index of Viper Functions ++* Variable Index:: Index of Viper Variables ++* Package Index:: Index of Packages Mentioned in this Document ++* Concept Index:: Vi, Ex and Emacs concepts ++ ++* Acknowledgments:: ++* GNU Free Documentation License:: The license for this documentation. ++ ++@end menu ++@iftex ++@unnumbered Introduction ++ ++We believe that one or more of the following statements are adequate ++descriptions of Viper: ++ ++@example ++Viper Is a Package for Emacs Rebels; ++it is a VI Plan for Emacs Rescue ++and/or a venomous VI PERil. ++@end example ++ ++Viper is a Vi emulation package for Emacs. Viper contains virtually all ++of Vi and Ex functionality and much more. It gives you the best of both ++worlds: Vi keystrokes for editing combined with the GNU Emacs ++environment. Viper also fixes some common complaints with Vi commands. ++This manual describes Viper, concentrating on the differences from Vi ++and on the new features of Viper. ++ ++Viper was written by Michael Kifer. It is based on VIP version 3.5 by ++Masahiko Sato and VIP version 4.4 by Aamod Sane. About 15% of the code ++still comes from those older packages. ++ ++Viper is intended to be usable out of the box, without reading this manual ++--- the defaults are set to make Viper as close to Vi as possible. At ++startup, Viper will attempt to set the most appropriate default environment ++for you, based on your familiarity with Emacs. It will also tell you the ++basic GNU Emacs window management commands to help you start immediately. ++ ++Although this manual explains how to customize Viper, some basic ++familiarity with Emacs Lisp is a plus. ++ ++It is recommended that you read the chapter Overview. The other chapters ++will be useful for customization and advanced usage. ++ ++You should also learn to use the Info on-line hypertext manual system that ++comes with Emacs. This manual can be read as an Info file. Try the command ++@kbd{@key{ESC} x info} with vanilla Emacs sometime. ++ ++Comments and bug reports are welcome. ++@code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. ++Please use the Ex command @kbd{:submitReport} for this purpose.@refill ++ ++@end iftex ++ ++@node Overview,Improvements over Vi,Top,Top ++@chapter Overview of Viper ++ ++Viper is a Vi emulation on top of Emacs. At the same time, Viper provides a ++virtually unrestricted access to Emacs facilities. Perfect compatibility ++with Vi is possible but not desirable. This chapter tells you about the ++Emacs ideas that you should know about, how to use Viper within Emacs and ++some incompatibilities. ++ ++This manual is written with the assumption that you are an experienced Vi ++user who wants to switch to Emacs while retaining the ability to edit files ++Vi style. Incredible as it might seem, there are experienced Emacs users ++who use Viper as a backdoor into the superior (as every Vi user already knows) ++world of Vi! These users are well familiar with Emacs bindings and prefer them ++in some cases, especially in the Vi Insert state. John Hawkins ++ has provided a set of customizations, which ++enables additional Emacs bindings under Viper. These customizations can be ++included in your @file{~/.viper} file and are found at the following URL: ++@file{http://traeki.freeshell.org/files/viper-sample}. ++ ++@menu ++* Emacs Preliminaries:: Basic concepts in Emacs. ++* Loading Viper:: Loading and Preliminary Configuration. ++* States in Viper:: Viper has four states orthogonal to Emacs ++ modes. ++* The Minibuffer:: Command line in Emacs. ++* Multiple Files in Viper:: True multiple file handling. ++* Unimplemented Features:: That are unlikely to be implemented. ++@end menu ++ ++@node Emacs Preliminaries, Loading Viper, Overview, Overview ++@section Emacs Preliminaries ++ ++@cindex buffer ++@cindex point ++@cindex mark ++@cindex text ++@cindex looking at ++@cindex end (of buffer) ++@cindex end (of line) ++@cindex region ++ ++Emacs can edit several files at once. A file in Emacs is placed in a ++@dfn{buffer} that usually has the same name as the file. Buffers are also used ++for other purposes, such as shell interfaces, directory editing, etc. ++@xref{Dired,,Directory Editor,emacs,The ++GNU Emacs Manual}, for an example.@refill ++ ++A buffer has a distinguished position called the @dfn{point}. ++A @dfn{point} is always between 2 characters, and is @dfn{looking at} ++the right hand character. The cursor is positioned on the right hand ++character. Thus, when the @dfn{point} is looking at the end-of-line, ++the cursor is on the end-of-line character, i.e.@: beyond the last ++character on the line. This is the default Emacs behavior.@refill ++ ++The default settings of Viper try to mimic the behavior of Vi, preventing ++the cursor from going beyond the last character on the line. By using ++Emacs commands directly (such as those bound to arrow keys), it is possible ++to get the cursor beyond the end-of-line. However, this won't (or ++shouldn't) happen if you restrict yourself to standard Vi keys, unless you ++modify the default editing style. @xref{Customization}.@refill ++ ++In addition to the @dfn{point}, there is another distinguished buffer ++position called the @dfn{mark}. @xref{Mark,,Mark,emacs,The GNU Emacs ++manual}, for more info on the mark. The text between the @dfn{point} and ++the @dfn{mark} is called the @dfn{region} of the buffer. For the Viper ++user, this simply means that in addition to the Vi textmarkers a--z, there ++is another marker called @dfn{mark}. This is similar to the unnamed Vi ++marker used by the jump commands @kbd{``} and @kbd{''}, which move the ++cursor to the position of the last absolute jump. Viper provides access to ++the region in most text manipulation commands as @kbd{r} and @kbd{R} suffix ++to commands that operate on text regions, e.g., @kbd{dr} to delete region, ++etc. ++ ++Furthermore, Viper lets Ex-style commands to work on the current region. ++This is done by typing a digit argument before @kbd{:}. For instance, ++typing @kbd{1:} will prompt you with something like @emph{:123,135}, ++assuming that the current region starts at line 123 and ends at line ++135. There is no need to type the line numbers, since Viper inserts them ++automatically in front of the Ex command. ++ ++@xref{Basics}, for more info.@refill ++ ++@cindex window ++@cindex mode line ++@cindex buffer information ++@cindex Minibuffer ++@cindex command line ++@cindex buffer (modified) ++ ++Emacs divides the screen into tiled @dfn{windows}. You can see the ++contents of a buffer through the window associated with the buffer. The ++cursor of the screen is positioned on the character after @dfn{point}. ++Every window has a @dfn{mode line} that displays information about the buffer. ++You can change the format of the mode ++line, but normally if you see @samp{**} at the beginning of a mode line it ++means that the buffer is @dfn{modified}. If you write out the contents of ++a buffer to a file, then the buffer will become not modified. Also if ++you see @samp{%%} at the beginning of the mode line, it means that the file ++associated with the buffer is write protected. The mode line will also ++show the buffer name and current major and minor modes (see below). ++A special buffer called @dfn{Minibuffer} is displayed as the last line ++in a Minibuffer window. The Minibuffer window is used for command input ++output. Viper uses Minibuffer window for @kbd{/} and @kbd{:} ++commands.@refill ++ ++@cindex mode ++@cindex keymap ++@cindex local keymap ++@cindex global keymap ++@cindex major mode ++@cindex minor mode ++ ++An Emacs buffer can have a @dfn{major mode} that customizes Emacs for ++editing text of a particular sort by changing the functionality of the keys. ++Keys are defined using a @dfn{keymap} that records the bindings between ++keystrokes and ++functions. The @dfn{global keymap} is common to all the ++buffers. Additionally, each buffer has its @dfn{local keymap} that determines the ++@dfn{mode} of the buffer. If a function is bound to some key in the local ++keymap then that function will be executed when you type the key. ++If no function is bound to a key in the ++local map, however, the function bound to the key in the global map ++will be executed. @xref{Major Modes,Major Modes,Major Modes,emacs,The ++GNU Emacs Manual}, for more information.@refill ++ ++A buffer can also have a @dfn{minor mode}. Minor modes are options that ++you can use or not. A buffer in @code{text-mode} can have ++@code{auto-fill-mode} as minor mode, which can be turned off or on at ++any time. In Emacs, a minor mode may have it own keymap, ++which overrides the local keymap when the minor mode is turned on. For ++more information, @pxref{Minor Modes,Minor Modes,Minor Modes,emacs,The ++GNU Emacs Manual} @refill ++ ++@cindex Viper as minor mode ++@cindex Control keys ++@cindex Meta key ++ ++Viper is implemented as a collection of minor modes. Different minor modes ++are involved when Viper emulates Vi command mode, Vi insert mode, etc. ++You can also turn Viper on and off at any time while in Vi command mode. ++@xref{States in Viper}, for ++more information.@refill ++ ++Emacs uses Control and Meta modifiers. These are denoted as C and M, ++e.g.@: @kbd{^Z} as @kbd{C-z} and @kbd{Meta-x} as @kbd{M-x}. The Meta key is ++usually located on each side of the Space bar; it is used in a manner ++similar to the Control key, e.g., @kbd{M-x} means typing @kbd{x} while ++holding the Meta key down. For keyboards that do not have a Meta key, ++@key{ESC} is used as Meta. Thus @kbd{M-x} is typed as @kbd{@key{ESC} ++x}. Viper uses @key{ESC} to switch from Insert state to Vi state. Therefore ++Viper defines @kbd{C-\} as its Meta key in Vi state. @xref{Vi State}, for ++more info.@refill ++ ++Emacs is structured as a Lisp interpreter around a C core. Emacs keys ++cause Lisp functions to be called. It is possible to call these ++functions directly, by typing @kbd{M-x function-name}. ++ ++@node Loading Viper, States in Viper, Emacs Preliminaries, Overview ++@section Loading Viper ++ ++The most common way to load it automatically is to include the following ++lines (in the given order!): ++ ++@lisp ++(setq viper-mode t) ++(require 'viper) ++@end lisp ++ ++@noindent ++in your @file{~/.emacs} file. The @file{.emacs} file is placed in your ++home directory and it is be executed every time you invoke Emacs. This is ++the place where all general Emacs customization takes place. Beginning with ++version 20.0, Emacsen have an interactive interface, which simplifies the ++job of customization significantly. ++ ++Viper also uses the file @file{~/.viper} for Viper-specific customization. ++The location of Viper customization file can be changed by setting the ++variable @code{viper-custom-file-name} in @file{.emacs} @emph{prior} to loading ++Viper. ++ ++The latest versions of Emacs have an interactive customization facility, ++which allows you to (mostly) bypass the use of the @file{.emacs} and ++@file{.viper} files. You can reach this customization ++facility from within Viper's VI state by executing the Ex command ++@kbd{:customize}. ++ ++Once invoked, Viper will arrange to bring up Emacs buffers in Vi state ++whenever this makes sense. ++@xref{Packages that Change Keymaps}, to find out when forcing Vi command state ++on a buffer may be counter-productive. ++ ++Even if your @file{.emacs} file does not invoke Viper automatically, ++you can still load Viper and enter the Vi command state by typing the ++following from within Emacs: ++ ++@lisp ++M-x viper-mode ++@end lisp ++ ++When Emacs first comes up, if you have not specified a file on the ++command line, it will show the @samp{*scratch*} buffer, in the ++@samp{Lisp Interaction} mode. After you invoke Viper, you can start ++editing files by using @kbd{:e}, @kbd{:vi}, or @kbd{v} commands. ++(@xref{File and Buffer Handling}, for more information on @kbd{v} and other ++new commands that, in many cases, are more convenient than @kbd{:e}, ++@kbd{:vi}, and similar old-style Vi commands.)@refill ++ ++Finally, if at some point you would want to de-Viperize your running ++copy of Emacs after Viper has been loaded, the command @kbd{M-x ++viper-go-away} will do it for you. The function @code{toggle-viper-mode} ++toggles Viperization of Emacs on and off. ++ ++@node States in Viper, The Minibuffer, Loading Viper,Overview ++@section States in Viper ++ ++@kindex @kbd{C-z} ++@kindex @key{ESC} ++@kindex @kbd{i} ++@cindex Emacs state ++@cindex Vi state ++@cindex Insert state ++@cindex Replace state ++@cindex Ex commands ++@findex @code{viper-go-away} ++@findex @code{toggle-viper-mode} ++ ++Viper has four states, Emacs, Vi, Insert, and Replace. ++ ++@table @samp ++@item Emacs state ++This is the state plain vanilla Emacs is normally in. After you have loaded ++Viper, @kbd{C-z} will normally take you to Vi command state. Another ++@kbd{C-z} will take you back to Emacs state. This toggle key can be ++changed, @pxref{Customization} You can also type @kbd{M-x viper-mode} to ++change to Vi state.@refill ++ ++ ++For users who chose to set their user level to 1 at Viper setup time, ++switching to Emacs state is deliberately made harder in order to not ++confuse the novice user. In this case, @kbd{C-z} will either iconify Emacs ++(if Emacs runs as an application under X) or it will stop Emacs (if ++Emacs runs on a dumb terminal or in an Xterm window). ++ ++@item Vi state ++This is the Vi command mode. Any of the Vi commands, such as @kbd{i, o, a}, ++@dots{}, will take you to Insert state. All Vi commands may ++be used in this mode. Most Ex commands can also be used. ++For a full list of Ex commands supported by Viper, type ++@kbd{:} and then @key{TAB}. To get help on any issue, including the Ex ++commands, type @kbd{:help}. This will invoke Viper Info ++(if it is installed). Then typing @kbd{i} will prompt you for a topic to ++search in the index. Note: to search for Ex commands in the index, you ++should start them with a @kbd{:}, e.g., @kbd{:WW}. ++ ++In Viper, Ex commands can be made to work on the current Emacs region. ++This is done by typing a digit argument before @kbd{:}. ++For instance, typing @kbd{1:} will prompt you with something like ++@emph{:123,135}, assuming that the current region starts at line 123 and ++ends at line 135. There is no need to type the line numbers, since Viper ++inserts them automatically in front of the Ex command. ++ ++@item Insert state ++Insert state is the Vi insertion mode. @key{ESC} will take you back to ++Vi state. Insert state editing can be done, including auto-indentation. By ++default, Viper disables Emacs key bindings in Insert state. ++ ++@item Replace state ++Commands like @kbd{cw} invoke the Replace state. When you cross the ++boundary of a replacement region (usually designated via a @samp{$} sign), ++it will automatically change to Insert state. You do not have to worry ++about it. The key bindings remain practically the same as in Insert ++state. If you type @key{ESC}, Viper will switch to Vi command mode, terminating the ++replacement state.@refill ++@end table ++ ++@cindex mode line ++ ++The modes are indicated on the @dfn{mode line} as , , , and , ++so that the multiple modes do not confuse you. Most of your editing can be ++done in Vi and Insert states. Viper will try to make all new buffers be in Vi ++state, but sometimes they may come up in Emacs state. @kbd{C-z} ++will take you to Vi state in such a case. In some major modes, like Dired, ++Info, Gnus, etc., you should not switch to Vi state (and Viper will not ++attempt to do so) because these modes are not intended for text editing and ++many of the Vi keys have special meaning there. If you plan to read news, ++browse directories, read mail, etc., from Emacs (which you should start ++doing soon!), you should learn about the meaning of the various keys in ++those special modes (typing @kbd{C-h m} in a buffer provides ++help with key bindings for the major mode of that buffer). ++ ++If you switch to Vi in Dired or similar modes---no harm is done. It is just ++that the special key bindings provided by those modes will be temporarily ++overshadowed by Viper's bindings. Switching back to Viper's Emacs state ++will revive the environment provided by the current major mode. ++ ++States in Viper are orthogonal to Emacs major modes, such as C mode or Dired ++mode. You can turn Viper on and off for any Emacs state. When Viper is turned ++on, Vi state can be used to move around. In Insert state, the bindings for ++these modes can be accessed. For beginners (users at Viper levels 1 and 2), ++these bindings are suppressed in Insert state, so that new users are not ++confused by the Emacs states. Note that unless you allow Emacs bindings in ++Insert state, you cannot do many interesting things, like language ++sensitive editing. For the novice user (at Viper level 1), all major mode ++bindings are turned off in Vi state as well. This includes the bindings for ++key sequences that start with @kbd{C-c}, which practically means that all ++major mode bindings are unsupported. @xref{Customization}, to find out how ++to allow Emacs keys in Insert state. ++ ++@menu ++* Emacs State:: This is the state you should learn more about when ++ you get up to speed with Viper. ++* Vi State:: Vi commands are executed in this state. ++* Insert State:: You can enter text, and also can do sophisticated ++ editing if you know enough Emacs commands. ++* Replace State:: Like Insert mode, but it is invoked via the ++ replacement commands, such as cw, C, R, etc. ++@end menu ++ ++@node Emacs State, Vi State, States in Viper, States in Viper ++@subsection Emacs State ++ ++@kindex @kbd{C-z} ++@cindex Emacs state ++ ++ ++You will be in this mode only by accident (hopefully). This is the state ++Emacs is normally in (imagine!!). Now leave it as soon as possible by ++typing @kbd{C-z}. Then you will be in Vi state (sigh of relief) :-). ++ ++Emacs state is actually a Viperism to denote all the major and minor modes ++(@pxref{Emacs Preliminaries}) other than Viper that Emacs can be in. Emacs ++can have several modes, such as C mode for editing C programs, LaTeX mode ++for editing LaTeX documents, Dired for directory editing, etc. These are ++major modes, each with a different set of key-bindings. Viper states are ++orthogonal to these Emacs major modes. The presence of these language ++sensitive and other modes is a major win over Vi. @xref{Improvements over ++Vi}, for more.@refill ++ ++The bindings for these modes can be made available in the Viper Insert state ++as well as in Emacs state. Unless you specify your user level as 1 (a ++novice), all major mode key sequences that start with @kbd{C-x} and ++@kbd{C-c} are also available in Vi state. This is important because major ++modes designed for editing files, such as cc-mode or latex-mode, use key ++sequences that begin with @kbd{C-x} and @kbd{C-c}. ++ ++There is also a key that lets you temporarily escape to Vi command state ++from the Insert state: typing @kbd{C-z} will let you execute a ++single Vi command while staying in Viper's Insert state. ++ ++ ++@node Vi State, Insert State, Emacs State, States in Viper ++@subsection Vi State ++ ++@cindex Vi state ++ ++This is the Vi command mode. When Viper is in Vi state, you will see the sign ++ in the mode line. Most keys will work as in Vi. The notable ++exceptions are: ++ ++@table @kbd ++@item C-x ++@kindex @kbd{C-x} ++@kbd{C-x} is used to invoke Emacs commands, mainly those that do window ++management. @kbd{C-x 2} will split a window, @kbd{C-x 0} will close a ++window. @kbd{C-x 1} will close all other windows. @kbd{C-xb} is used to ++switch buffers in a window, and @kbd{C-xo} to move through windows. ++These are about the only necessary keystrokes. ++For the rest, see the GNU Emacs Manual. ++ ++@item C-c ++@kindex @kbd{C-c} ++For user levels 2 and higher, this key serves as a prefix key for the key ++sequences used by various major modes. For users at Viper level 1, @kbd{C-c} ++simply beeps. ++ ++@item C-g and C-] ++@kindex @kbd{C-g} ++@kindex @kbd{C-]} ++ ++These are the Emacs @samp{quit} keys. ++There will be cases where you will have to ++use @kbd{C-g} to quit. Similarly, @kbd{C-]} is used to exit ++@samp{Recursive Edits} in Emacs for which there is no comparable Vi ++functionality and no key-binding. Recursive edits are indicated by ++@samp{[]} brackets framing the modes on the mode line. ++@xref{Recursive Edit,Recursive ++Edit,Recursive Edit,emacs,The GNU Emacs Manual}. ++At user level 1, @kbd{C-g} is bound to @code{viper-info-on-file} ++function instead. ++@refill ++@item C-\ ++@kindex @kbd{C-\} ++@cindex Meta key ++ ++Viper uses @key{ESC} as a switch between Insert and Vi states. Emacs uses ++@key{ESC} for Meta. The Meta key is very important in Emacs since many ++functions are accessible only via that key as @kbd{M-x function-name}. ++Therefore, we need to simulate it somehow. In Viper's Vi, Insert, and ++Replace states, the meta key is set to be @kbd{C-\}. Thus, to get ++@kbd{M-x}, you should type @kbd{C-\ x} (if the keyboard has no Meta key, ++which is rare these days). ++This works both in the Vi command state and in the Insert and Replace ++states. In Vi command state, you can also use @kbd{\ @key{ESC}} as the ++meta key. ++ ++Note: Emacs binds @kbd{C-\} to a function that offers to change the ++keyboard input method in the multilingual environment. Viper overrides this ++binding. However, it is still possible to switch the input method by typing ++@kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state. ++Or you can use the MULE menu in the menubar. ++@end table ++@noindent ++Other differences are mostly improvements. The ones you should know ++about are: ++ ++@table @samp ++@item Undo ++@kindex @kbd{u} ++@kbd{u} will undo. Undo can be repeated by the @kbd{.} key. Undo itself ++can be undone. Another @kbd{u} will change the direction. The presence ++of repeatable undo means that @kbd{U}, undoing lines, is not very ++important. Therefore, @kbd{U} also calls @code{viper-undo}. ++@cindex multiple undo ++@cindex undo ++ ++ ++@item Counts ++Most commands, @kbd{~}, @kbd{[[}, @kbd{p}, @kbd{/}, @dots{}, etc., take counts. ++ ++@comment ]] Just to balance parens ++@item Regexps ++Viper uses Emacs Regular Expressions for searches. These are a superset of ++Vi regular ++expressions, excepting the change-of-case escapes @samp{\u}, @samp{\L}, ++@dots{}, etc. @xref{Regexps,,Syntax of Regular Expressions,emacs,The ++GNU Emacs Manual}, for details. ++Files specified to @kbd{:e} use @code{csh} regular expressions ++(globbing, wildcards, what have you). ++However, the function @code{viper-toggle-search-style}, bound to @kbd{C-c /}, ++lets the user switch from search with regular expressions to plain vanilla ++search and vice versa. It also lets one switch from case-sensitive search ++to case-insensitive and back. ++@xref{Viper Specials}, for more details. ++@cindex regular expressions ++@cindex vanilla search ++@cindex case-sensitive search ++@cindex case-insensitive search ++@kindex @kbd{C-c /} ++ ++@item Ex commands ++@cindex Ex commands ++The current working directory of a buffer is automatically inserted in the ++minibuffer if you type @kbd{:e} then space. Absolute filenames are ++required less often in Viper. For file names, Emacs uses a convention that ++is slightly different from other programs. It is designed to minimize the ++need for deleting file names that Emacs provides in its prompts. (This is ++usually convenient, but occasionally the prompt may suggest a wrong file ++name for you.) If you see a prompt @kbd{/usr/foo/} and you wish to edit the ++file @kbd{~/.viper}, you don't have to erase the prompt. Instead, simply ++continue typing what you need. Emacs will interpret @kbd{/usr/foo/~/.viper} ++correctly. Similarly, if the prompt is @kbd{~/foo/} and you need to get to ++@kbd{/bar/file}, keep typing. Emacs interprets @kbd{~/foo//bar/} as ++@kbd{/bar/file}, since when it sees @samp{//}, it understands that ++@kbd{~/foo/} is to be discarded. ++ ++The command @kbd{:cd} will change the default directory for the ++current buffer. The command @kbd{:e} will interpret the ++filename argument in @code{csh}. @xref{Customization}, if you ++want to change the default shell. ++The command @kbd{:next} takes counts from ++@kbd{:args}, so that @kbd{:rew} is obsolete. Also, @kbd{:args} will show only ++the invisible files (i.e., those that are not currently seen in Emacs ++windows). ++ ++When applicable, Ex commands support file completion and history. This ++means that by typing a partial file name and then @key{TAB}, Emacs will try ++to complete the name or it will offer a menu of possible completions. ++This works similarly to Tcsh and extends the behavior of Csh. While Emacs ++is waiting for a file name, you can type @kbd{M-p} to get the previous file ++name you typed. Repeatedly typing @kbd{M-p} and @kbd{M-n} will let you ++browse through the file history. ++ ++Like file names, partially typed Ex commands can be completed by typing ++@key{TAB}, and Viper keeps the history of Ex commands. After typing ++@kbd{:}, you can browse through the previously entered Ex commands by ++typing @kbd{M-p} and @kbd{M-n}. Viper tries to rationalize when it puts Ex ++commands on the history list. For instance, if you typed @kbd{:w!@: foo}, ++only @kbd{:w!} will be placed on the history list. This is because the ++last history element is the default that can be invoked simply by typing ++@kbd{: @key{RET}}. If @kbd{:w!@: foo} were placed on the list, it would be all to ++easy to override valuable data in another file. Reconstructing the full ++command, @kbd{:w!@: foo}, from the history is still not that hard, since Viper ++has a separate history for file names. By typing @kbd{: M-p}, you will get ++@kbd{:w!} in the Minibuffer. Then, repeated @kbd{M-p} will get you through ++the file history, inserting one file name after another. ++ ++In contrast to @kbd{:w!@: foo}, if the command were @kbd{:r foo}, the entire ++command will appear in the history list. This is because having @kbd{:r} ++alone as a default is meaningless, since this command requires a file ++argument. ++@refill ++@end table ++@noindent ++As Vi, Viper's destructive commands can be re-executed by typing `@kbd{.}'. ++However, in addition, Viper keeps track of the history of such commands. This ++history can be perused by typing @kbd{C-c M-p} and @kbd{C-c M-n}. ++Having found the appropriate command, it can be then executed by typing ++`@kbd{.}'. ++@xref{Improvements over Vi}, for more information. ++ ++@node Insert State, Replace State, Vi State, States in Viper ++@subsection Insert State ++ ++@cindex Insert state ++ ++To avoid confusing the beginner (at Viper level 1 and 2), Viper makes only the ++standard Vi keys available in Insert state. The implication is that ++Emacs major modes cannot be used in Insert state. ++It is strongly recommended that as soon as you are comfortable, make the ++Emacs state bindings visible (by changing your user level to 3 or higher). ++@xref{Customization}, ++to see how to do this.@refill ++ ++Once this is done, it is possible to do quite a bit of editing in ++Insert state. For instance, Emacs has a @dfn{yank} command, @kbd{C-y}, ++which is similar to Vi's @kbd{p}. However, unlike @kbd{p}, @kbd{C-y} can be ++used in Insert state of Viper. Emacs also has a kill ring where it keeps ++pieces of text you deleted while editing buffers. The command @kbd{M-y} is ++used to delete the text previously put back by Emacs' @kbd{C-y} or by Vi's ++@kbd{p} command and reinsert text that was placed on the kill-ring earlier. ++ ++This works both in Vi and Insert states. ++In Vi state, @kbd{M-y} is a much better alternative to the usual Vi's way ++of recovering the 10 previously deleted chunks of text. In Insert state, ++you can ++use this as follows. Suppose you deleted a piece of text and now you need ++to re-insert it while editing in Insert mode. The key @kbd{C-y} will put ++back the most recently deleted chunk. If this is not what you want, type ++@kbd{M-y} repeatedly and, hopefully, you will find the chunk you want. ++ ++Finally, in Insert and Replace states, Viper provides the history of ++pieces of text inserted in previous insert or replace commands. These ++strings of text can be recovered by repeatedly typing @kbd{C-c M-p} or ++@kbd{C-c M-n} while in Insert or Replace state. (This feature is disabled ++in the minibuffer: the above keys are usually bound to other histories, ++which are more appropriate in the minibuffer.) ++ ++ ++@cindex Meta key ++ ++You can call Meta functions from Insert state. As in Vi state, the Meta key ++is @kbd{C-\}. Thus @kbd{M-x} is typed as @kbd{C-\ x}. ++ ++Other Emacs commands that are useful in Insert state are @kbd{C-e} ++and @kbd{C-a}, which move the cursor to the end and the beginning of the ++current line, respectively. You can also use @kbd{M-f} and @kbd{M-b}, ++which move the cursor forward (or backward) one word. ++If your display has a Meta key, these functions are invoked by holding the ++Meta key and then typing @kbd{f} and @kbd{b}, respectively. On displays ++without the Meta key, these functions are invoked by typing ++@kbd{C-\ f} and @kbd{C-\ b} (@kbd{C-\} simulates the Meta key in Insert ++state, as explained above). ++ ++The key @kbd{C-z} is sometimes also useful in Insert state: it allows you ++to execute a single command in Vi state without leaving the Insert state! ++For instance, @kbd{C-z d2w} will delete the next two words without leaving ++the Insert state. ++ ++When Viper is in Insert state, you will see in the mode line. ++ ++@node Replace State,, Insert State, States in Viper ++@subsection Replace State ++ ++@cindex Replace state ++ ++This state is entered through Vi replacement commands, such as @kbd{C}, ++@kbd{cw}, etc., or by typing @kbd{R}. In Replace state, Viper puts in ++the mode line to let you know which state is in effect. If Replace state is ++entered through @kbd{R}, Viper stays in that state until the user hits ++@key{ESC}. If this state is entered via the other replacement commands, ++then Replace state is in effect until you hit @key{ESC} or until you cross ++the rightmost boundary of the replacement region. In the latter case, Viper ++changes its state from Replace to Insert (which you will notice by the ++change in the mode line). ++ ++Since Viper runs under Emacs, it is possible to switch between buffers ++while in Replace state. You can also move the cursor using the arrow keys ++(even on dumb terminals!)@: and the mouse. Because of this freedom (which is ++unattainable in regular Vi), it is possible to take the cursor outside the ++replacement region. (This may be necessary for several reasons, including ++the need to enable text selection and region-setting with the mouse.) ++ ++The issue then arises as to what to do when the user ++hits the @key{ESC} key. In Vi, this would cause the text between cursor and ++the end of the replacement region to be deleted. But what if, as is ++possible in Viper, the cursor is not inside the replacement region? ++ ++To solve the problem, Viper keeps track of the last cursor position while it ++was still inside the replacement region. So, in the above situation, Viper ++would delete text between this position and the end of the replacement ++region. ++ ++@node The Minibuffer,Multiple Files in Viper, States in Viper, Overview ++@section The Minibuffer ++ ++@cindex Minibuffer ++ ++The Minibuffer is where commands are entered in. Editing can be done ++by commands from Insert state, namely: ++ ++@table @kbd ++@item C-h ++Backspace ++@item C-w ++Delete Word ++@item C-u ++Erase line ++@item C-v ++Quote the following character ++@item @key{RET} ++Execute command ++@item C-g and C-] ++Emacs quit and abort keys. These may be necessary. @xref{Vi State}, for an ++explanation. ++@item M-p and M-n ++These keys are bound to functions that peruse minibuffer history. The ++precise history to be perused depends on the context. It may be the history ++of search strings, Ex commands, file names, etc. ++@end table ++ ++Most of the Emacs keys are functional in the Minibuffer. While in the ++Minibuffer, Viper tries to make editing resemble Vi's behavior when the ++latter is waiting for the user to type an Ex command. In particular, you ++can use the regular Vi commands to edit the Minibuffer. You can switch ++between the Vi state and Insert state at will, and even use the replace mode. ++Initially, the Minibuffer comes up in Insert state. ++ ++Some users prefer plain Emacs bindings in the Minibuffer. To this end, set ++@code{viper-vi-style-in-minibuffer} to @code{nil} in @file{.viper}. ++@xref{Customization}, to learn how to do this. ++ ++When the Minibuffer changes Viper states, you will notice that the appearance ++of the text there changes as well. This is useful because the Minibuffer ++has no mode line to tell which Vi state it is in. ++The appearance of the text in the Minibuffer can be changed. ++@xref{Viper Specials}, for more details. ++ ++@node Multiple Files in Viper,Unimplemented Features,The Minibuffer,Overview ++@section Multiple Files in Viper ++ ++@cindex multiple files ++@cindex managing multiple files ++ ++Viper can edit multiple files. This means, for example that you never need ++to suffer through @code{No write since last change} errors. ++Some Viper elements are common over all the files. ++ ++@table @samp ++@item Textmarkers ++@cindex markers ++@cindex textmarkers ++Textmarkers remember @emph{files and positions}. ++If you set marker @samp{a} in ++file @file{foo}, start editing file @file{bar} and type @kbd{'a}, then ++@emph{YOU WILL SWITCH TO FILE @file{foo}}. You can see the contents of a ++textmarker using the Viper command @kbd{[} where are the ++textmarkers, e.g., @kbd{[a} to view marker @samp{a} .@refill ++@item Repeated Commands ++Command repetitions are common over files. Typing @kbd{!!} will repeat the ++last @kbd{!} command whichever file it was issued from. ++Typing @kbd{.} will repeat the last command from any file, and ++searches will repeat the last search. Ex commands can be repeated by typing ++@kbd{: @key{RET}}.@refill ++Note: in some rare cases, that @kbd{: @key{RET}} may do something dangerous. ++However, usually its effect can be undone by typing @kbd{u}. ++@item Registers ++@cindex registers ++Registers are common to files. Also, text yanked with @kbd{y} can be ++put back (@kbd{p}) into any file. The Viper command @kbd{]}, where are ++the registers, can be used to look at the contents of a register, e.g., ++type @kbd{]a} to view register @samp{a}. ++ ++There is one difference in text deletion that you should be ++aware of. This difference comes from Emacs and was adopted in Viper ++because we find it very useful. In Vi, if you delete a line, say, and then ++another line, these two deletions are separated and are put back ++separately if you use the @samp{p} command. In Emacs (and Viper), successive ++series of deletions that are @emph{not interrupted} by other commands are ++lumped together, so the deleted text gets accumulated and can be put back ++as one chunk. If you want to break a sequence of deletions so that the ++newly deleted text could be put back separately from the previously deleted ++text, you should perform a non-deleting action, e.g., move the cursor one ++character in any direction. ++@item Absolute Filenames ++@cindex absolute file names ++The current directory name for a file is automatically prepended to the ++file name in any ++@kbd{:e}, @kbd{:r}, @kbd{:w}, etc., command (in Emacs, each buffer has a ++current directory). ++This directory is inserted in the Minibuffer once you type space after ++@kbd{:e, r}, etc. Viper also supports completion of file names and Ex ++commands (@key{TAB}), and it keeps track of ++command and file history (@kbd{M-p}, @kbd{M-n}). ++Absolute filenames are required less ++often in Viper. ++ ++You should be aware that Emacs interprets @kbd{/foo/bar//bla} as ++@kbd{/bla} and @kbd{/foo/~/bar} as @kbd{~/bar}. This is designed to ++minimize the need for erasing file names that Emacs suggests in its ++prompts, if a suggested file name is not what you wanted. ++ ++The command @kbd{:cd} will change the default directory for the ++current Emacs buffer. The Ex command @kbd{:e} will interpret the ++filename argument in @samp{csh}, by default. @xref{Customization}, if you ++want to change this. ++@end table ++ ++@noindent ++Currently undisplayed files can be listed using the @kbd{:ar} command. The ++command @kbd{:n} can be given counts from the @kbd{:ar} list to switch to ++other files. For example, use `:n3' to move to the third file in that list. ++ ++@node Unimplemented Features,,Multiple Files in Viper,Overview ++@section Unimplemented Features ++ ++Unimplemented features include: ++ ++@itemize @bullet ++@item ++@kbd{:ab} and @kbd{:una} are not implemented, since ++@kbd{:ab} is considered obsolete, since Emacs has much ++more powerful facilities for defining abbreviations. ++@item ++@kbd{:set option?} is not implemented. The current ++@kbd{:set} can also be used to set Emacs variables. ++@item ++@kbd{:se list} requires modification of the display code for Emacs, so ++it is not implemented. ++A useful alternative is @code{cat -t -e file}. Unfortunately, it cannot ++be used directly inside Emacs, since Emacs will obdurately change @samp{^I} ++back to normal tabs.@refill ++@end itemize ++ ++@comment node-name, next, previous, up ++@node Improvements over Vi, Customization, Overview, Top ++@chapter Improvements over Vi ++ ++Some common problems with Vi and Ex have been solved in Viper. This ++includes better implementation of existing commands, new commands, and ++the facilities provided by Emacs. ++ ++@menu ++* Basics:: Basic Viper differences, Multi-file effects. ++* Undo and Backups:: Multiple undo, auto-save, backups and changes ++* History:: History for Ex and Vi commands. ++* Macros and Registers:: Keyboard Macros (extended ".")@: @@reg execution. ++* Completion:: Filename and Command Completion for Ex. ++* Improved Search:: Incremental Search and Buffer Content Search. ++* Abbreviation Facilities:: Normal Abbrevs, Templates, and Dynamic Abbrevs. ++* Movement and Markers:: Screen Editor movements, viewing textmarkers. ++* New Commands:: Commands that do not exist in Vi. ++* Useful Packages:: A Sampling of some Emacs packages, and things ++ you should know about. ++@end menu ++ ++@node Basics, Undo and Backups, Improvements over Vi, Improvements over Vi ++@section Basics ++ ++The Vi command set is based on the idea of combining motion commands ++with other commands. The motion command is used as a text region ++specifier for other commands. ++We classify motion commands into @dfn{point commands} and ++@dfn{line commands}.@refill ++ ++@cindex point commands ++ ++The point commands are: ++ ++@quotation ++@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, ++@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, ++@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} ++@end quotation ++ ++@cindex line commands ++ ++The line commands are: ++ ++@quotation ++@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, ++@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} ++@end quotation ++ ++@cindex region ++@cindex region specification ++@cindex expanding (region) ++@cindex describing regions ++@cindex movement commands ++ ++@noindent ++If a point command is given as an argument to a modifying command, the ++region determined by the point command will be affected by the modifying ++command. On the other hand, if a line command is given as an argument to a ++modifying command, the region determined by the line command will be ++enlarged so that it will become the smallest region properly containing the ++region and consisting of whole lines (we call this process @dfn{expanding ++the region}), and then the enlarged region will be affected by the modifying ++command. ++Text Deletion Commands (@pxref{Deleting Text}), Change commands ++(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) ++use these commands to describe a region of text to operate on. ++Thus, type @kbd{dw} to delete a word, @kbd{>@}} to shift a paragraph, or ++@kbd{!'afmt} to format a region from @samp{point} to textmarker ++@samp{a}. ++ ++@cindex r and R region specifiers ++ ++Viper adds the region specifiers @samp{r} and @samp{R}. Emacs has a ++special marker called @dfn{mark}. The text-area between the current cursor ++position @dfn{point} and the @dfn{mark} is called the @dfn{region}. ++@samp{r} specifies the raw region and @samp{R} is the expanded region ++(i.e., the minimal contiguous chunk of full lines that contains the raw ++region). ++@kbd{dr} will now delete the region, @kbd{>r} will shift it, etc. ++@kbd{r,R} are not motion commands, however. The special mark is set by ++@kbd{m.} and other commands. @xref{Marking}, for more info. ++ ++Viper also adds counts to most commands for which it would make sense. ++ ++In the Overview chapter, some Multiple File issues were discussed ++(@pxref{Multiple Files in Viper}). In addition to the files, Emacs has ++buffers. These can be seen in the @kbd{:args} list and switched using ++@kbd{:next} if you type @kbd{:set ex-cycle-through-non-files t}, or ++specify @code{(setq ex-cycle-through-non-files t)} in your @file{.viper} ++file. @xref{Customization}, for details. ++ ++@node Undo and Backups, History, Basics, Improvements over Vi ++@section Undo and Backups ++ ++@cindex undo ++ ++Viper provides multiple undo. The number of undo's and the size is limited ++by the machine. The Viper command @kbd{u} does an undo. Undo can be ++repeated by typing @kbd{.} (a period). Another @kbd{u} will undo the undo, ++and further ++@kbd{.} will repeat it. Typing @kbd{u} does the first undo, and changes the ++direction. ++ ++@cindex backup files ++@cindex auto save ++ ++Since the undo size is limited, Viper can create backup files and ++auto-save files. It will normally do this automatically. It is possible ++to have numbered backups, etc. For details, @pxref{Backup,,Backup and ++Auto-Save,emacs,The GNU Emacs Manual} @refill ++ ++@comment [ balance parens ++@cindex viewing registers and markers ++@cindex registers ++@cindex markers ++@cindex textmarkers ++ ++The results of the 9 previous changes are available in the 9 numeric ++registers, as in Vi. The extra goody is the ability to @emph{view} these ++registers, in addition to being able to access them through @kbd{p} and ++@kbd{M-y} (@xref{Insert State}, for details.) ++The Viper command @kbd{] register} will display the contents of any ++register, numeric or alphabetical. The related command @kbd{[ textmarker} ++will show the text around the textmarker. @samp{register} and @samp{textmarker} ++can be any letters from a through z. ++@comment ] balance parens ++ ++@node History, Macros and Registers, Undo and Backups,Improvements over Vi ++@section History ++ ++@cindex history ++@cindex Minibuffer ++ ++History is provided for Ex commands, Vi searches, file names, pieces of ++text inserted in earlier commands that use Insert or Replace state, and for ++destructive commands in Vi state. These are ++useful for fixing those small typos that screw up searches and @kbd{:s}, ++and for eliminating routine associated with repeated typing of file names ++or pieces of text that need to be inserted frequently. ++At the @kbd{:} or @kbd{/} prompts in the Minibuffer, you can do the following: ++ ++@table @kbd ++@item M-p and M-n ++To move to previous and next history items. This causes the history ++items to appear on the command line, where you can edit them, or ++simply type Return to execute. ++@item M-r and M-s ++To search backward and forward through the history. ++@item @key{RET} ++Type @key{RET} to accept a default (which is displayed in the prompt). ++@end table ++ ++The history of insertions can be perused by ++typing @kbd{C-c M-p} and @kbd{C-c M-n} while in Insert or Replace state. ++The history of destructive Vi commands can be perused via the same keys ++when Viper is in Vi state. @xref{Viper Specials}, for details. ++ ++All Ex commands have a file history. For instance, typing @kbd{:e}, space ++and then @kbd{M-p} will bring up the name of the previously typed file ++name. Repeatedly typing @kbd{M-p}, @kbd{M-n}, etc., will let you browse ++through the file history. ++ ++Similarly, commands that have to do with switching buffers ++have a buffer history, and commands that expect strings or regular ++expressions keep a history on those items. ++ ++@node Macros and Registers,Completion,History,Improvements over Vi ++@section Macros and Registers ++ ++@cindex keyboard macros ++@cindex macros ++@cindex registers ++@cindex register execution ++ ++Viper facilitates the use of Emacs-style keyboard macros. @kbd{@@#} will ++start a macro definition. As you type, the commands will be executed, and ++remembered (This is called ``learn mode'' in some editors.) ++@kbd{@@register} will complete the macro, putting it into @samp{register}, ++where @samp{register} is any character from @samp{a} through @samp{z}. Then ++you can execute this macro using @kbd{@@register}. It is, of course, ++possible to yank some text into a register and execute it using ++@kbd{@@register}. Typing @kbd{@@@@}, @kbd{@@RET}, or @kbd{@@C-j} will ++execute the last macro that was executed using @kbd{@@register}.@refill ++ ++Viper will automatically lowercase the register, so that pressing the ++@kbd{SHIFT} key for @kbd{@@} will not create problems. This is for ++@kbd{@@} macros and @kbd{"p} @emph{only}. In the case of @kbd{y}, ++@kbd{"Ayy} will append to @emph{register a}. For @kbd{[,],',`}, it ++is an error to use a Uppercase register name. ++ ++@comment [ balance parens ++@cindex viewing registers and markers ++ ++The contents of a register can be seen by @kbd{]register}. (@kbd{[textmarker} ++will show the contents of a textmarker). ++@comment ] balance parens ++ ++@cindex last keyboard macro ++ ++The last keyboard macro can also be executed using ++@kbd{*}, and it can be yanked into a register using @kbd{@@!register}. ++This is useful for Emacs style keyboard macros defined using @kbd{C-x(} ++and @kbd{C-x)}. Emacs keyboard macros have more capabilities. ++@xref{Keyboard Macros,,Keyboard Macros,emacs, The GNU Emacs Manual}, for ++details.@refill ++ ++Keyboard Macros allow an interesting form of Query-Replace: ++@kbd{/pattern} or @kbd{n} to go to the next pattern (the query), followed by a ++Keyboard Macro execution @kbd{@@@@} (the replace). ++ ++Viper also provides Vi-style macros. @xref{Vi Macros}, for details. ++ ++ ++@node Completion, Improved Search, Macros and Registers, Improvements over Vi ++@section Completion ++ ++@cindex completion ++ ++Completion is done when you type @key{TAB}. The Emacs completer does not ++grok wildcards in file names. Once you type a wildcard, the completer will ++no longer work for that file name. Remember that Emacs interprets a file name ++of the form @kbd{/foo//bar} as @kbd{/bar} and @kbd{/foo/~/bar} as ++@kbd{~/bar}. ++ ++@node Improved Search, Abbreviation Facilities, Completion, Improvements over Vi ++@section Improved Search ++ ++@cindex buffer search ++@cindex word search ++ ++Viper provides buffer search, the ability to search the buffer for a region ++under the cursor. You have to turn this on in @file{.viper} either by calling ++ ++@example ++(viper-buffer-search-enable) ++@end example ++ ++@noindent ++or by setting @code{viper-buffer-search-char} to, say, @kbd{f3}: ++@example ++(setq viper-buffer-search-char ?g) ++@end example ++ ++@noindent ++If the user calls @code{viper-buffer-search-enable} explicitly (the first ++method), then @code{viper-buffer-search-char} will be set to @kbd{g}. ++Regardless of how this feature is enabled, the key ++@code{viper-buffer-search-char} will take movement commands, like ++@kbd{w,/,e}, to find a region and then search for the contents of that ++region. This command is very useful for searching for variable names, etc., ++in a program. The search can be repeated by @kbd{n} or reversed by @kbd{N}. ++ ++@cindex incremental search ++ ++Emacs provides incremental search. As you type the string in, the ++cursor will move to the next match. You can snarf words from the buffer ++as you go along. Incremental Search is normally bound to @kbd{C-s} and ++@kbd{C-r}. @xref{Customization}, to find out how to change the bindings ++of @kbd{C-r or C-s}. ++For details, @pxref{Incremental Search,,Incremental ++Search,emacs,The GNU Emacs Manual} @refill ++ ++@cindex query replace ++ ++Viper also provides a query replace function that prompts through the ++Minibuffer. It is invoked by the @kbd{Q} key in Vi state. ++ ++@cindex mouse search ++ ++On a window display, Viper supports mouse search, i.e., you can search for a ++word by clicking on it. @xref{Viper Specials}, for details. ++ ++Finally, on a window display, Viper highlights search patterns as it finds ++them. This is done through what is known as @emph{faces} in Emacs. The ++variable that controls how search patterns are highlighted is ++@code{viper-search-face}. If you don't want any highlighting at all, put ++@example ++(copy-face 'default 'viper-search-face) ++@end example ++@vindex @code{viper-search-face} ++@noindent ++in @file{~/.viper}. If you want to change how patterns are highlighted, you ++will have to change @code{viper-search-face} to your liking. The easiest ++way to do this is to use Emacs customization widget, which is accessible ++from the menubar. Viper customization group is located under the ++@emph{Emulations} customization group, which in turn is under the ++@emph{Editing} group (or simply by typing @kbd{:customize}). All Viper ++faces are grouped together under Viper's ++@emph{Highlighting} group. ++ ++Try it: it is really simple! ++ ++@node Abbreviation Facilities,Movement and Markers,Improved Search,Improvements over Vi ++@section Abbreviation Facilities ++ ++@cindex abbrevs ++ ++It is possible in Emacs to define abbrevs based on the contents of the ++buffer. ++Sophisticated templates can be defined using the Emacs abbreviation ++facilities. @xref{Abbrevs,,Abbreviations,emacs,The GNU Emacs Manual}, for ++details. ++ ++@cindex dynamic abbrevs ++ ++Emacs also provides Dynamic Abbreviations. Given a partial word, Emacs ++will search the buffer to find an extension for this word. For instance, ++one can type @samp{Abbreviations} by typing @samp{A}, followed by a keystroke ++that completed the @samp{A} to @samp{Abbreviations}. Repeated typing ++will search further back in the buffer, so that one could get ++@samp{Abbrevs} by repeating the ++keystroke, which appears earlier in the text. Emacs binds this to ++@kbd{@key{ESC} /}, so you will have to find a key and bind the function ++@code{dabbrev-expand} to that key. ++Facilities like this make Vi's @kbd{:ab} command obsolete. ++ ++@node Movement and Markers, New Commands, Abbreviation Facilities, Improvements over Vi ++@section Movement and Markers ++ ++@cindex Ex style motion ++@cindex line editor motion ++ ++Viper can be set free from the line--limited movements in Vi, such as @kbd{l} ++refusing to move beyond the line, @key{ESC} moving one character back, ++etc. These derive from Ex, which is a line editor. If your @file{.viper} ++contains ++ ++@example ++@code{(setq viper-ex-style-motion nil)} ++@end example ++ ++@noindent ++the motion will be a true screen editor motion. One thing you must then ++watch out for is that it is possible to be on the end-of-line character. ++The keys @kbd{x} and @kbd{%} will still work correctly, i.e., as if they ++were on the last character. ++ ++@vindex @code{viper-syntax-preference} ++@cindex syntax table ++ ++The word-movement commands @kbd{w}, @kbd{e}, etc., and the associated ++deletion/yanking commands, @kbd{dw}, @kbd{yw}, etc., can be made to ++understand Emacs syntax tables. If the variable ++@code{viper-syntax-preference} is set to @code{strict-vi} then ++the meaning of @emph{word} is the same as in ++Vi. However, if the value is @code{reformed-vi} (the default) then the ++alphanumeric symbols will be those specified by the current Emacs syntax ++table (which may be different for different major modes) plus the ++underscore symbol @kbd{_}, minus some non-word symbols, like '.;,|, etc. ++Both @code{strict-vi} and @code{reformed-vi} work close to Vi in ++traditional cases, but @code{reformed-vi} does a better job when editing ++text in non-Latin alphabets. ++ ++The user can also specify the value @code{emacs}, which would ++make Viper use exactly the Emacs notion of word. In particular, the ++underscore may not be part of a word. Finally, if ++@code{viper-syntax-preference} is set to @code{extended}, Viper words would ++consist of characters that are classified as alphanumeric @emph{or} as ++parts of symbols. This is convenient for writing programs and in many other ++situations. ++ ++@code{viper-syntax-preference} is a local variable, so it can have different ++values for different major modes. For instance, in programming modes it can ++have the value @code{extended}. In text modes where words contain special ++characters, such as European (non-English) letters, Cyrillic letters, etc., ++the value can be @code{reformed-vi} or @code{emacs}. ++ ++Changes to @code{viper-syntax-preference} should be done in the hooks to ++various major modes by executing @code{viper-set-syntax-preference} as in ++the following example: ++ ++@example ++(viper-set-syntax-preference nil "emacs") ++@end example ++ ++@findex @code{viper-set-syntax-preference} ++ ++The above discussion of the meaning of Viper's words concerns only Viper's ++movement commands. In regular expressions, words remain the same as in ++Emacs. That is, the expressions @code{\w}, @code{\>}, @code{\<}, etc., use ++Emacs' idea of what is a word, and they don't look into the value of ++variable @code{viper-syntax-preference}. This is because Viper doesn't change ++syntax tables in fear of upsetting the various major modes that set these ++tables. ++ ++@cindex textmarkers ++ ++Textmarkers in Viper remember the file and the position, so that you can ++switch files by simply doing @kbd{'a}. If you set up a regimen for using ++Textmarkers, this is very useful. Contents of textmarkers can be viewed ++by @kbd{[marker}. (Contents of registers can be viewed by @kbd{]register}). ++ ++@node New Commands, Useful Packages, Movement and Markers, Improvements over Vi ++@section New Commands ++ ++These commands have no Vi analogs. ++ ++@table @kbd ++@item C-x, C-c ++@kindex @kbd{C-x} ++@kindex @kbd{C-c} ++These two keys invoke many important Emacs functions. For example, if you ++hit @kbd{C-x} followed by @kbd{2}, then the current window will be split ++into 2. Except for novice users, @kbd{C-c} is also set to execute an Emacs ++command from the current major mode. @key{ESC} will do the same, if you ++configure @key{ESC} as Meta by setting @code{viper-no-multiple-ESC} to @code{nil} ++in @file{.viper}. @xref{Customization}. @kbd{C-\} in Insert, Replace, or Vi ++states will make Emacs think @kbd{Meta} has been hit.@refill ++@item \ ++@kindex @kbd{\} ++Escape to Emacs to execute a single Emacs command. For instance, ++@kbd{\ @key{ESC}} will act like a Meta key. ++@item Q ++@kindex @kbd{Q} ++@cindex query replace ++@kbd{Q} is for query replace. By default, ++each string to be replaced is treated as a regular expression. You can use ++@code{(setq viper-re-query-replace nil)} in your @file{.emacs} file to ++turn this off. (For normal searches, @kbd{:se nomagic} will work. Note ++that @kbd{:se nomagic} turns Regexps off completely, unlike Vi). ++@item v ++@itemx V ++@itemx C-v ++@kindex @kbd{v} ++@kindex @kbd{V} ++@kindex @kbd{C-v} ++These keys are used to visit files. @kbd{v} will switch to a buffer ++visiting file whose name can be entered in the Minibuffer. @kbd{V} is ++similar, but will use a window different from the current window. ++@kbd{C-v} is like @kbd{V}, except that a new frame (X window) will be used ++instead of a new Emacs window. ++@item # ++@kindex @kbd{#} ++If followed by a certain character @var{ch}, it becomes an operator whose ++argument is the region determined by the motion command that follows ++(indicated as ). ++Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q}, and ++@kbd{s}. For instance, @kbd{#qr} will prompt you for a string and then ++prepend this string to each line in the buffer.@refill ++@item # c ++@kindex @kbd{#c} ++@cindex changing case ++Change upper-case characters in the region to lower-case ++(@code{downcase-region}). ++Emacs command @kbd{M-l} does the same for words. ++@item # C ++@kindex @kbd{#C} ++Change lower-case characters in the region to upper-case. For instance, ++@kbd{# C 3 w} will capitalize 3 words from the current point ++(@code{upcase-region}). ++Emacs command @kbd{M-u} does the same for words. ++@item # g ++@kindex @kbd{#g} ++Execute last keyboard macro for each line in the region ++(@code{viper-global-execute}).@refill ++@item # q ++@kindex @kbd{#q} ++Insert specified string at the beginning of each line in the region ++(@code{viper-quote-region}). The default string is composed of the comment ++character(s) appropriate for the current major mode. ++@item # s ++@kindex @kbd{#s} ++Check spelling of words in the region (@code{spell-region}). ++The function used for spelling is determined from the variable ++@code{viper-spell-function}. ++@vindex @code{viper-spell-function} ++@item * ++@kindex @kbd{*} ++Call last keyboard macro. ++@item m . ++Set mark at point and push old mark off the ring ++@item m< ++@item m> ++Set mark at beginning and end of buffer, respectively. ++@item m, ++Jump to mark and pop mark off the ring. @xref{Mark,,Mark,emacs,The GNU ++Emacs Manual}, for more info. ++@item ] register ++@kindex @kbd{]} ++View contents of register ++@item [ textmarker ++@kindex @kbd{[} ++View filename and position of textmarker ++@item @@# ++@item @@register ++@item @@! ++@kindex @kbd{@@#} ++@kindex @kbd{@@} ++@kindex @kbd{@@!} ++@cindex keyboard macros ++@cindex register execution ++ ++Begin/end keyboard macro. @@register has a different meaning when used after ++a @kbd{@@#}. @xref{Macros and Registers}, for details ++@item [] ++@kindex @kbd{[]} ++Go to end of heading. ++@item g <@emph{movement command}> ++Search buffer for text delimited by movement command. The canonical ++example is @kbd{gw} to search for the word under the cursor. ++@xref{Improved Search}, for details.@refill ++@item C-g and C-] ++@kindex @kbd{C-g} ++@kindex @kbd{C-]} ++Quit and Abort Recursive edit. These may be necessary on occasion. ++@xref{Vi State}, for a reason. ++@item C-c C-g ++@kindex @kbd{C-c C-g} ++Hitting @kbd{C-c} followed by @kbd{C-g} will display the information on the ++current buffer. This is the same as hitting @kbd{C-g} in Vi, but, as ++explained above, @kbd{C-g} is needed for other purposes in Emacs. ++@item C-c / ++@kindex @kbd{C-c /} ++Without a prefix argument, this command toggles ++case-sensitive/case-insensitive search modes and plain vanilla/regular ++expression search. With the prefix argument 1, i.e., ++@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, ++toggles plain vanilla search and search using ++regular expressions. @xref{Viper Specials}, for alternative ways to invoke ++this function. ++@cindex vanilla search ++@cindex case-sensitive search ++@cindex case-insensitive search ++ ++@item M-p and M-n ++@kindex @kbd{M-p} ++@kindex @kbd{M-n} ++In the Minibuffer, these commands navigate through the minibuffer ++histories, such as the history of search strings, Ex commands, etc. ++ ++@item C-c M-p and C-c M-n ++@kindex @kbd{C-c M-p} ++@kindex @kbd{C-c M-n} ++@cindex Insertion history ++@cindex Insertion ring ++@cindex Command history ++@cindex Command ring ++ ++In Insert or Replace state, these commands let the user ++peruse the history of insertion strings used in previous insert or replace ++commands. Try to hit @kbd{C-c M-p} or @kbd{C-c M-n} repeatedly and see what ++happens. @xref{Viper Specials}, for more. ++ ++In Vi state, these commands let the user peruse the history of Vi-style ++destructive commands, such as @kbd{dw}, @kbd{J}, @kbd{a}, etc. ++By repeatedly typing @kbd{C-c M-p} or @kbd{C-c M-n} you will cycle Viper ++through the recent history of Vi commands, displaying the commands one by ++one. Once ++an appropriate command is found, it can be executed by typing `@kbd{.}'. ++ ++Since typing @kbd{C-c M-p} is tedious, it is more convenient to bind an ++appropriate function to a function key on the keyboard and use that key. ++@xref{Viper Specials}, for details. ++ ++@item Ex commands ++@findex @kbd{:args} ++@findex @kbd{:n} ++@findex @kbd{:pwd} ++@findex @kbd{:pre} ++The commands @kbd{:args}, @kbd{:next}, @kbd{:pre} behave ++differently. @kbd{:pwd} exists to get current directory. ++The commands @kbd{:b} and @kbd{:B} switch buffers around. @xref{File and ++Buffer Handling}, for details. ++There are also the new commands @kbd{:RelatedFile} and ++@kbd{PreviousRelatedFile} (which abbreviate to @kbd{R} and @kbd{P}, ++respectively. @xref{Viper Specials}, for details. ++@findex @kbd{:RelatedFile} ++@findex @kbd{:PreviousRelatedFile} ++@end table ++ ++Apart from the new commands, many old commands have been enhanced. Most ++notably, Vi style macros are much more powerful in Viper than in Vi. @xref{Vi ++Macros}, for details. ++ ++@node Useful Packages, ,New Commands, Improvements over Vi ++@section Useful Packages ++ ++Some Emacs packages are mentioned here as an aid to the new Viper user, to ++indicate what Viper is capable of. ++A vast number comes with the standard Emacs distribution, and many more exist ++on the net and on the archives. ++ ++This manual also mentions some Emacs features a new user ++should know about. The details of these are found in the GNU Emacs ++Manual. ++ ++The features first. For details, look up the Emacs Manual. ++ ++@table @samp ++@item Make ++@cindex make ++@cindex compiling ++ ++Makes and Compiles can be done from the editor. Error messages will be ++parsed and you can move to the error lines. ++@item Shell ++@cindex shell ++@cindex interactive shell ++You can talk to Shells from inside the editor. Your entire shell session ++can be treated as a file. ++@item Mail ++@cindex email ++@cindex mail ++Mail can be read from and sent within the editor. Several sophisticated ++packages exist. ++@item Language Sensitive Editing ++Editing modes are written for most computer languages in existence. By ++controlling indentation, they catch punctuation errors. ++@end table ++ ++The packages, below, represents a drop in the sea of special-purpose ++packages that come with standard distribution of Emacs. ++ ++@table @samp ++@item Transparent FTP ++@cindex transparent ftp ++@pindex ange-ftp.el ++@code{ange-ftp.el} can ftp from the editor to files on other machines ++transparent to the user. ++@item RCS Interfaces ++@cindex version maintenance ++@cindex RCS ++@pindex vc.el ++@code{vc.el} for doing RCS commands from inside the editor ++@item Directory Editor ++@cindex dired ++@pindex dired.el ++@code{dired.el} for editing contents of directories and for navigating in ++the file system. ++@item Syntactic Highlighting ++@cindex font-lock ++@pindex font-lock.el ++@code{font-lock.el} for automatic highlighting various parts of a buffer ++using different fonts and colors. ++@item Saving Emacs Configuration ++@cindex desktop ++@pindex desktop.el ++@code{desktop.el} for saving/restoring configuration on Emacs exit/startup. ++@item Spell Checker ++@cindex ispell ++@pindex ispell.el ++@code{ispell.el} for spell checking the buffer, words, regions, etc. ++@item File and Buffer Comparison ++@cindex ediff ++@pindex ediff.el ++@code{ediff.el} for finding differences between files and for applying ++patches. ++@end table ++ ++@noindent ++Emacs Lisp archives exist on ++@samp{archive.cis.ohio-state.edu} ++and @samp{wuarchive.wustl.edu}@refill ++ ++ ++@node Customization,Commands,Improvements over Vi,Top ++@chapter Customization ++ ++@cindex customization ++ ++Customization can be done in 2 ways. ++ ++@itemize @bullet ++@item ++@cindex initialization ++@cindex .viper ++Elisp code in a @file{.viper} file in your home directory. Viper ++loads @file{.viper} just before it does the binding for mode ++hooks. This is recommended for experts only. ++@item ++@cindex .emacs ++Elisp code in your @file{.emacs} file before and after the @code{(require ++'viper)} line. This method is @emph{not} recommended, unless you know what ++you are doing. Only two variables, @code{viper-mode} and ++@code{viper-custom-file-name}, are supposed to be customized in @file{.emacs}, ++prior to loading Viper (i.e., prior to @code{(require 'viper)} command.@refill ++@item ++@cindex :customize ++By executing the @kbd{:customize} Ex command. This takes you to the Emacs ++customization widget, which lets you change the values of Viper ++customizable variables easily. This method is good for novice and ++experts alike. The customization code in the form of Lisp commands will be ++placed in @file{~/.emacs} or some other customization file depending on the ++version of Emacs that you use. Still, it is recommended to separate ++Viper-related customization produced by the Emacs customization widget ++and keep it in the @file{.viper} file. ++ ++Some advanced customization cannot be accomplished this way, however, and ++has to be done in Emacs Lisp in the @file{.viper} file. For the common ++cases, examples are provided that you can use directly. ++@end itemize ++ ++ ++@menu ++* Rudimentary Changes:: Simple constant definitions. ++* Key Bindings:: Enabling Emacs Keys, Rebinding keys, etc. ++* Packages that Change Keymaps:: How to deal with such beasts. ++* Viper Specials:: Special Viper commands. ++* Vi Macros:: How to do Vi style macros. ++@end menu ++ ++@node Rudimentary Changes,Key Bindings,Customization,Customization ++@section Rudimentary Changes ++ ++@cindex setting variables ++@cindex variables for customization ++@findex @kbd{:set} ++ ++An easy way to customize Viper is to change the values of constants used in ++Viper. Here is the list of the constants used in Viper and their default ++values. The corresponding :se command is also indicated. (The symbols ++@code{t} and @code{nil} represent ``true'' and ``false'' in Lisp). ++ ++Viper supports both the abbreviated Vi variable names and their full ++names. Variable completion is done on full names only. @key{TAB} and ++@key{SPC} complete ++variable names. Typing `=' will complete the name and then will prompt for ++a value, if applicable. For instance, @kbd{:se au @key{SPC}} will complete the ++command to @kbd{:set autoindent}; @kbd{:se ta @key{SPC}} will complete the command ++and prompt further like this: @kbd{:set tabstop = }. ++However, typing @kbd{:se ts @key{SPC}} will produce a ``No match'' message ++because @kbd{ts} is an abbreviation for @kbd{tabstop} and Viper supports ++completion on full names only. However, you can still hit @key{RET} ++or @kbd{=}, which will complete the command like this: @kbd{:set ts = } and ++Viper will be waiting for you to type a value for the tabstop variable. ++To get the full list of Vi variables, type @kbd{:se @key{SPC} @key{TAB}}. ++ ++@table @code ++@item viper-auto-indent nil ++@itemx :se ai (:se autoindent) ++@itemx :se ai-g (:se autoindent-global) ++If @code{t}, enable auto indentation. ++by @key{RET}, @kbd{o} or @kbd{O} command. ++ ++@code{viper-auto-indent} is a local variable. To change the value globally, use ++@code{setq-default}. It may be useful for certain major modes to have their ++own values of @code{viper-auto-indent}. This can be achieved by using ++@code{setq} to change the local value of this variable in the hooks to the ++appropriate major modes. ++ ++@kbd{:se ai} changes the value of @code{viper-auto-indent} in the current ++buffer only; @kbd{:se ai-g} does the same globally. ++@item viper-electric-mode t ++If not @code{nil}, auto-indentation becomes electric, which means that ++@key{RET}, @kbd{O}, and @kbd{o} indent cursor according to the current ++major mode. In the future, this variable may control additional electric ++features. ++ ++This is a local variable: @code{setq} changes the value of this variable ++in the current buffer only. Use @code{setq-default} to change the value in ++all buffers. ++@item viper-case-fold-search nil ++@itemx :se ic (:se ignorecase) ++If not @code{nil}, search ignores cases. ++This can also be toggled by quickly hitting @kbd{/} twice. ++@item viper-re-search nil ++@itemx :se magic ++If not @code{nil}, search will use regular expressions; if @code{nil} then ++use vanilla search. ++This behavior can also be toggled by quickly hitting @kbd{/} trice. ++@item buffer-read-only ++@itemx :se ro (:se readonly) ++Set current buffer to read only. To change globally put ++@code{(setq-default buffer-read-only t)} in your @file{.emacs} file. ++@item blink-matching-paren t ++@itemx :se sm (:se showmatch) ++Show matching parens by blinking cursor. ++@item tab-width t (default setting via @code{setq-default}) ++@itemx :se ts=value (:se tabstop=value) ++@itemx :se ts-g=value (:se tabstop-global=value) ++@code{tab-width} is a local variable that controls the width of the tab stops. ++To change the value globally, use @code{setq-default}; for local settings, ++use @code{setq}. ++ ++The command @kbd{:se ts} ++sets the tab width in the current ++buffer only; it has no effect on other buffers. ++ ++The command @kbd{:se ts-g} sets tab width globally, ++for all buffers where the tab is not yet set locally, ++including the new buffers. ++ ++Note that typing @key{TAB} normally ++doesn't insert the tab, since this key is usually bound to ++a text-formatting function, @code{indent-for-tab-command} (which facilitates ++programming and document writing). Instead, the tab is inserted via the ++command @code{viper-insert-tab}, which is bound to @kbd{S-tab} (shift + tab). ++ ++On some non-windowing terminals, Shift doesn't modify the @key{TAB} key, so ++@kbd{S-tab} behaves as if it were @key{TAB}. In such a case, you will have ++to bind @code{viper-insert-tab} to some other convenient key. ++ ++@item viper-shift-width 8 ++@itemx :se sw=value (:se shiftwidth=value) ++The number of columns shifted by @kbd{>} and @kbd{<} commands. ++@item viper-search-wrap-around t ++@itemx :se ws (:se wrapscan) ++If not @code{nil}, search wraps around the end/beginning of buffer. ++@item viper-search-scroll-threshold 2 ++If search lands within this many lines of the window top or bottom, the ++window will be scrolled up or down by about 1/7-th of its size, to reveal ++the context. If the value is negative---don't scroll. ++@item viper-tags-file-name "TAGS" ++The name of the file used as the tag table. ++@item viper-re-query-replace nil ++If not @code{nil}, use reg-exp replace in query replace. ++@item viper-want-ctl-h-help nil ++If not @code{nil}, @kbd{C-h} is bound to @code{help-command}; ++otherwise, @kbd{C-h} is bound as usual in Vi. ++@item viper-vi-style-in-minibuffer t ++If not @code{nil}, Viper provides a high degree of compatibility with Vi ++insert mode when you type text in the Minibuffer; if @code{nil}, typing in ++the Minibuffer feels like plain Emacs. ++@item viper-no-multiple-ESC t ++If you set this to @code{nil}, you can use @key{ESC} as Meta in Vi state. ++Normally, this is not necessary, since graphical displays have separate ++Meta keys (usually on each side of the space bar). On a dumb terminal, Viper ++sets this variable to @code{twice}, which is almost like @code{nil}, except ++that double @key{ESC} beeps. This, too, lets @key{ESC} to be used as a Meta. ++@item viper-fast-keyseq-timeout 200 ++Key sequences separated by this many milliseconds are treated as Vi-style ++keyboard macros. If the key sequence is defined as such a macro, it will be ++executed. Otherwise, it is processed as an ordinary sequence of typed keys. ++ ++Setting this variable too high may slow down your typing. Setting it too ++low may make it hard to type macros quickly enough. ++@item viper-ex-style-motion t ++Set this to @code{nil}, if you want @kbd{l,h} to cross ++lines, etc. @xref{Movement and Markers}, for more info. ++@item viper-ex-style-editing t ++Set this to @code{nil}, if you want ++@kbd{C-h} and @key{DEL} to not stop ++at the beginning of a line in Insert state, @key{X} and @key{x} to delete ++characters across lines in Vi command state, etc. ++@item viper-ESC-moves-cursor-back t ++It @code{t}, cursor moves back 1 character when switching from insert state to vi ++state. If @code{nil}, the cursor stays where it was before the switch. ++@item viper-always t ++@code{t} means: leave it to Viper to decide when a buffer must be brought ++up in Vi state, ++Insert state, or Emacs state. This heuristics works well in virtually all ++cases. @code{nil} means you either has to invoke @code{viper-mode} manually ++for each buffer (or you can add @code{viper-mode} to the appropriate major mode ++hooks using @code{viper-load-hook}). ++ ++This option must be set in the file @file{~/.viper}. ++@item viper-custom-file-name "~/.viper" ++File used for Viper-specific customization. ++Change this setting, if you want. Must be set in @file{.emacs} (not @file{.viper}!) ++before Viper is loaded. Note that you ++have to set it as a string inside double quotes. ++@item viper-spell-function 'ispell-region ++Function used by the command @kbd{#c} to spell. ++@item viper-glob-function ++The value of this variable is the function symbol used to expand wildcard ++symbols. This is platform-dependent. The default tries to set this variable ++to work with most shells, MS Windows, OS/2, etc. However, if it ++doesn't work the way you expect, you should write your own. ++Use @code{viper-glob-unix-files} and @code{viper-glob-mswindows-files} in ++@file{viper-util.el} as examples. ++ ++This feature is used to expand wildcards in the Ex command @kbd{:e}. ++Note that Viper doesn't support wildcards in the @kbd{:r} and @kbd{:w} ++commands, because file completion is a better mechanism. ++@findex @code{viper-glob-function} ++ ++@item ex-cycle-other-window t ++If not @code{nil}, @kbd{:n} and @kbd{:b} will cycle through files in another ++window, if one exists. ++@item ex-cycle-through-non-files nil ++@kbd{:n} does not normally cycle through buffers. Set this to get ++buffers also. ++@item viper-want-emacs-keys-in-insert ++This is set to @code{nil} for user levels 1 and 2 and to @code{t} for user ++levels 3 and 4. Users who specify level 5 are allowed to set this variable ++as they please (the default for this level is @code{t}). If set to ++@code{nil}, complete Vi compatibility is provided in Insert state. This is ++really not recommended, as this precludes you from using language-specific ++features provided by the major modes. ++@item viper-want-emacs-keys-in-vi ++This is set to @code{nil} for user ++level 1 and to @code{t} for user levels 2--4. ++At level 5, users are allowed to set this variable as they please (the ++default for this level is @code{t}). ++If set to @code{nil}, complete Vi compatibility is provided ++in Vi command state. Setting this to @code{nil} is really a bad idea, ++unless you are a novice, as this precludes the use ++of language-specific features provided by the major modes. ++@item viper-keep-point-on-repeat t ++If not @code{nil}, point is not moved when the user repeats the previous ++command by typing `.' This is very useful for doing repeated changes with ++the @kbd{.} key. ++@item viper-repeat-from-history-key 'f12 ++Prefix key used to invoke the macros @kbd{f12 1} and @kbd{f12 2} that repeat ++the second-last and the third-last destructive command. ++Both these macros are bound (as Viper macros) to ++@code{viper-repeat-from-history}, ++which checks the second key by which it is invoked to see which of the ++previous commands to invoke. Viper binds @kbd{f12 1} and @kbd{f12 2} only, ++but the user can bind more in @file{~/.viper}. @xref{Vi Macros}, for how to do ++this. ++@item viper-keep-point-on-undo nil ++If not @code{nil}, Viper tries to not move point when undoing commands. ++Instead, it will briefly move the cursor to the place where change has ++taken place. However, if the undone piece of text is not seen in window, ++then point will be moved to the place where the change took place. ++Set it to @code{t} and see if you like it better. ++@item viper-delete-backwards-in-replace nil ++If not @code{nil}, @key{DEL} key will delete characters while moving the cursor ++backwards. If @code{nil}, the cursor will move backwards without deleting ++anything. ++@item viper-replace-overlay-face 'viper-replace-overlay-face ++On a graphical display, Viper highlights replacement regions instead of ++putting a @samp{$} at the end. This variable controls the so called ++@dfn{face} used to highlight the region. ++ ++By default, @code{viper-replace-overlay-face} underlines the replacement on ++monochrome displays and also lays a stipple over them. On color displays, ++replacement regions are highlighted with color. ++ ++If you know something about Emacs faces and don't like how Viper highlights ++replacement regions, you can change @code{viper-replace-overlay-face} by ++specifying a new face. (Emacs faces are described in the Emacs Lisp ++reference.) On a color display, the following customization method is ++usually most effective: ++@example ++(set-face-foreground viper-replace-overlay-face "DarkSlateBlue") ++(set-face-background viper-replace-overlay-face "yellow") ++@end example ++For a complete list of colors available to you, evaluate the expression ++@code{(x-defined-colors)}. (Type it in the buffer @code{*scratch*} and then ++hit the @kbd{C-j} key. ++ ++@item viper-replace-overlay-cursor-color "Red" ++@vindex @code{viper-replace-overlay-cursor-color} ++Cursor color when it is inside the replacement region. ++This has effect only on color displays and only when Emacs runs as an X ++application. ++@item viper-insert-state-cursor-color nil ++@vindex @code{viper-insert-state-cursor-color} ++If set to a valid color, this will be the cursor color when Viper is in ++insert state. ++@item viper-emacs-state-cursor-color nil ++@vindex @code{viper-emacs-state-cursor-color} ++If set to a valid color, this will be the cursor color when Viper is in ++emacs state. ++@item viper-replace-region-end-delimiter "$" ++A string used to mark the end of replacement regions. It is used only on ++TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}. ++@item viper-replace-region-start-delimiter "" ++A string used to mark the beginning of replacement regions. It is used ++only on TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}. ++@item viper-use-replace-region-delimiters ++If non-@code{nil}, Viper will always use @code{viper-replace-region-end-delimiter} and ++@code{viper-replace-region-start-delimiter} to delimit replacement regions, ++even on color displays (where this is unnecessary). By default, this ++variable is non-@code{nil} only on TTYs or monochrome displays. ++@item viper-allow-multiline-replace-regions t ++If non-@code{nil}, multi-line text replacement regions, such as those produced by ++commands @kbd{c55w}, @kbd{3C}, etc., will stay around until the user exits ++the replacement mode. In this variable is set to @code{nil}, Viper will ++emulate the standard Vi behavior, which supports only intra-line ++replacement regions (and multi-line replacement regions are deleted). ++@item viper-toggle-key "\C-z" ++Specifies the key used to switch from Emacs to Vi and back. ++Must be set in @file{.viper}. This variable can't be ++changed interactively after Viper is loaded. ++ ++In Insert state, this key acts as a temporary escape to Vi state, i.e., it ++will set Viper up so that the very next command will be executed as if it ++were typed in Vi state. ++@item viper-buffer-search-char nil ++Key used for buffer search. @xref{Viper Specials}, for details. ++@item viper-surrounding-word-function 'viper-surrounding-word ++The value of this variable is a function name that is used to determine ++what constitutes a word clicked upon by the mouse. This is used by mouse ++search and insert. ++@item viper-search-face 'viper-search-face ++Variable that controls how search patterns are highlighted when they are ++found. ++@item viper-vi-state-hook nil ++List of parameterless functions to be run just after entering the Vi ++command state. ++@item viper-insert-state-hook nil ++Same for Insert state. This hook is also run after entering Replace state. ++@item viper-replace-state-hook nil ++List of (parameterless) functions called just after entering Replace state ++(and after all @code{viper-insert-state-hook}). ++@item viper-emacs-state-hook nil ++List of (parameterless) functions called just after switching from Vi state ++to Emacs state. ++@item viper-load-hook nil ++List of (parameterless) functions called just after loading Viper. This is ++the last chance to do customization before Viper is up and running. ++@end table ++@noindent ++You can reset some of these constants in Viper with the Ex command @kbd{:set} ++(when so indicated in the table). Or you ++can include a line like this in your @file{.viper} file: ++@example ++(setq viper-case-fold-search t) ++@end example ++@vindex @code{viper-auto-indent} ++@vindex @code{viper-electric-mode} ++@vindex @code{viper-case-fold-search} ++@vindex @code{viper-re-search} ++@vindex @code{viper-shift-width} ++@vindex @code{buffer-read-only} ++@vindex @code{viper-search-wrap-around} ++@vindex @code{viper-search-scroll-threshold} ++@vindex @code{viper-search-face} ++@vindex @code{viper-tags-file-name} ++@vindex @code{viper-re-query-replace} ++@vindex @code{viper-want-ctl-h-help} ++@vindex @code{viper-vi-style-in-minibuffer} ++@vindex @code{viper-no-multiple-ESC} ++@vindex @code{viper-always} ++@vindex @code{viper-fast-keyseq-timeout} ++@vindex @code{viper-ex-style-motion} ++@vindex @code{viper-ex-style-editing} ++@vindex @code{viper-ESC-moves-cursor-back} ++@vindex @code{viper-custom-file-name} ++@vindex @code{viper-spell-function} ++@vindex @code{ex-cycle-other-window} ++@vindex @code{ex-cycle-through-non-files} ++@vindex @code{viper-want-emacs-keys-in-insert} ++@vindex @code{viper-want-emacs-keys-in-vi} ++@vindex @code{viper-keep-point-on-repeat} ++@vindex @code{viper-keep-point-on-undo} ++@vindex @code{viper-delete-backwards-in-replace} ++@vindex @code{viper-replace-overlay-face} ++@vindex @code{viper-replace-region-end-symbol} ++@vindex @code{viper-replace-region-start-symbol} ++@vindex @code{viper-allow-multiline-replace-regions} ++@vindex @code{viper-toggle-key} ++@vindex @code{viper-buffer-search-char} ++@vindex @code{viper-surrounding-word-function} ++@vindex @code{viper-vi-state-hook} ++@vindex @code{viper-insert-state-hook} ++@vindex @code{viper-replace-state-hook} ++@vindex @code{viper-emacs-state-hook} ++ ++@node Key Bindings, Packages that Change Keymaps, Rudimentary Changes,Customization ++@section Key Bindings ++ ++@cindex key bindings ++@cindex keymaps ++ ++Viper lets you define hot keys, i.e., you can associate keyboard keys ++such as F1, Help, PgDn, etc., with Emacs Lisp functions (that may already ++exist or that you will write). Each key has a "preferred form" in ++Emacs. For instance, the Up key's preferred form is [up], the Help key's ++preferred form is [help], and the Undo key has the preferred form [f14]. ++You can find out the preferred form of a key by typing @kbd{M-x ++describe-key-briefly} and then typing the key you want to know about. ++ ++Under the X Window System, every keyboard key emits its preferred form, ++so you can just type ++ ++@lisp ++(global-set-key [f11] 'calendar) ; L1, Stop ++(global-set-key [f14] 'undo) ; L4, Undo ++@end lisp ++ ++@noindent ++to bind L1 (a key that exists on some SUN workstations) so it will invoke ++the Emacs Calendar and to bind L4 so it will undo changes. ++However, on a dumb terminal or in an Xterm window, even the standard arrow ++keys may ++not emit the right signals for Emacs to understand. To let Emacs know about ++those keys, you will have to find out which key sequences they emit ++by typing @kbd{C-q} and then the key (you should switch to Emacs state ++first). Then you can bind those sequences to their preferred forms using ++@code{input-decode-map} as follows: ++ ++@lisp ++(cond ((string= (getenv "TERM") "xterm") ++(define-key input-decode-map "\e[192z" [f11]) ; L1 ++(define-key input-decode-map "\e[195z" [f14]) ; L4, Undo ++@end lisp ++ ++The above illustrates how to do this for Xterm. On VT100, you would have to ++replace "xterm" with "vt100" and also change the key sequences (the same ++key may emit different sequences on different types of terminals). ++ ++The above keys are global, so they are overwritten by the local maps ++defined by the major modes and by Viper itself. Therefore, if you wish to ++change a binding set by a major mode or by Viper, read this. ++ ++Viper users who wish to specify their own key bindings should be concerned ++only with the following three keymaps: ++@code{viper-vi-global-user-map} for Vi state commands, ++@code{viper-insert-global-user-map} for Insert state commands, ++and @code{viper-emacs-global-user-map} for Emacs state commands (note: ++customized bindings for Emacs state made to @code{viper-emacs-global-user-map} ++are @emph{not} inherited by Insert state). ++ ++For more information on Viper keymaps, see the header of the file ++@file{viper.el}. ++If you wish to change a Viper binding, you can use the ++@code{define-key} command, to modify @code{viper-vi-global-user-map}, ++@code{viper-insert-global-user-map}, and @code{viper-emacs-global-user-map}, as ++explained below. Each of these key maps affects the corresponding Viper state. ++The keymap @code{viper-insert-global-user-map} also affects Viper's Replace ++state. ++ ++@noindent ++If you want to ++bind a key, say @kbd{C-v}, to the function that scrolls ++page down and to make @kbd{0} display information on the current buffer, ++putting this in @file{.viper} will do the trick in Vi state: ++@example ++(define-key viper-vi-global-user-map "\C-v" 'scroll-down) ++@end example ++@noindent ++To set a key globally, ++@example ++(define-key viper-emacs-global-user-map "\C-c m" 'smail) ++(define-key viper-vi-global-user-map "0" 'viper-info-on-file) ++@end example ++@noindent ++Note, however, that this binding may be overwritten by other keymaps, since ++the global keymap has the lowest priority. ++To make sure that nothing will override a binding in Emacs state, you ++can write this: ++@example ++(define-key viper-emacs-global-user-map "\C-c m" 'smail) ++@end example ++@noindent ++To customize the binding for @kbd{C-h} in Insert state: ++@example ++(define-key viper-insert-global-user-map "\C-h" 'my-del-backwards-function) ++@end example ++@noindent ++ ++Each Emacs command key calls some Lisp function. If you have enabled the ++Help, (@pxref{Rudimentary Changes}) @kbd{C-h k} will show you the function ++for each specific key; @kbd{C-h b} will show all bindings, and @kbd{C-h m} ++will provide information on the major mode in effect. If Help is not ++enabled, you can still get help in Vi state by prefixing the above commands ++with @kbd{\}, e.g., @kbd{\ C-h k} (or you can use the Help menu in the ++menu bar, if Emacs runs under X). ++ ++Viper users can also change bindings on a per major mode basis. As with ++global bindings, this can be done separately for each of the three main Viper ++states. To this end, Viper provides the function ++@code{viper-modify-major-mode}. ++@findex @code{viper-modify-major-mode} ++ ++To modify keys in Emacs state for @code{my-favorite-major-mode}, the user ++needs to create a sparse keymap, say, @code{my-fancy-map}, bind whatever ++keys necessary in that keymap, and put ++ ++@example ++(viper-modify-major-mode 'dired-mode 'emacs-state my-fancy-map) ++@end example ++ ++@noindent ++in @file{~/.viper}. To do the same in Vi and Insert states, you should use ++@code{vi-state} and @code{insert-state}. Changes in Insert state are also ++in effect in Replace state. For instance, suppose that the user wants to ++use @kbd{dd} in Vi state under Dired mode to delete files, @kbd{u} to unmark ++files, etc. The following code in @file{~/.viper} will then do the job: ++ ++@example ++(setq my-dired-modifier-map (make-sparse-keymap)) ++(define-key my-dired-modifier-map "dd" 'dired-flag-file-deletion) ++(define-key my-dired-modifier-map "u" 'dired-unmark) ++(viper-modify-major-mode 'dired-mode 'vi-state my-dired-modifier-map) ++@end example ++ ++A Vi purist may want to modify Emacs state under Dired mode so that ++@kbd{k}, @kbd{l}, etc., will move around in directory buffers, as in ++Vi. Although this is not recommended, as these keys are bound to useful ++Dired functions, the trick can be accomplished via the following code: ++ ++@example ++(setq my-dired-vi-purist-map (make-sparse-keymap)) ++(define-key my-dired-vi-purist-map "k" 'viper-previous-line) ++(define-key my-dired-vi-purist-map "l" 'viper-forward-char) ++(viper-modify-major-mode 'dired-mode 'emacs-state my-dired-vi-purist-map) ++@end example ++ ++Yet another way to customize key bindings in a major mode is to edit the ++list @code{viper-major-mode-modifier-list} using the customization widget. ++@vindex @code{viper-major-mode-modifier-list} ++(This variable is in the Viper-misc customization group.) ++The elements of this list are triples of the form: (major-mode viper-state ++keymap), where the keymap contains bindings that are supposed to be active ++in the given major mode and the given viper-state. ++ ++Effects similar to key binding changes can be achieved by defining Vi ++keyboard macros using the Ex commands @kbd{:map} and @kbd{:map!}. The ++difference is that multi-key Vi macros do not override the keys they are ++bound to, unless these keys are typed in quick succession. So, with macros, ++one can use the normal keys alongside with the macros. If per-mode ++modifications are needed, the user can try both ways and see which one is ++more convenient. ++@findex @kbd{:map} ++@xref{Vi Macros}, for details. ++ ++Note: in major modes that come up in @emph{Emacs state} by default, the ++aforesaid modifications may not take place immediately (but only after the ++buffer switches to some other Viper state and then back to Emacs state). To ++avoid this, one should add @code{viper-change-state-to-emacs} to an ++appropriate hook of that major mode. (Check the function ++@code{viper-set-hooks} in @file{viper.el} for examples.) However, if you ++did not set @code{viper-always} to @code{nil}, chances are that you won't ++need to perform the above procedure, because Viper will take care of most ++useful defaults. ++ ++ ++Finally, Viper has a facility that lets the user define per-buffer ++bindings, i.e., bindings that are in effect in some specific buffers ++only. Unlike per-mode bindings described above, per-buffer bindings can be ++defined based on considerations other than the major mode. This is done ++via the function @code{viper-add-local-keys}, which lets one specify bindings ++that should be in effect in the current buffer only and for a specific Viper ++state. For instance, ++@lisp ++(viper-add-local-keys 'vi-state '(("ZZ" .@: TeX-command-master) ++ ("ZQ" .@: viper-save-kill-buffer))) ++@end lisp ++@noindent ++redefines @kbd{ZZ} to invoke @code{TeX-command-master} in @code{vi-state} ++and @kbd{ZQ} to save-then-kill the current buffer. These bindings take ++effect only in the buffer where this command is executed. The typical use ++of this function is to execute the above expression from within a function ++that is included in a hook to some major mode. For instance, the above ++expression ++could be called from a function, @code{my-tex-init}, which may be added to ++@code{tex-mode-hook} as follows: ++@lisp ++(add-hook 'tex-mode-hook 'my-tex-init) ++@end lisp ++@noindent ++When TeX mode starts, the hook is executed and the above Lisp expression is ++evaluated. Then, the bindings for @kbd{ZZ} and @kbd{ZQ} are changed in Vi ++command mode for all buffers in TeX mode. ++ ++Another useful application is to bind @kbd{ZZ} to @code{send-mail} ++in the Mail mode buffers (the specifics of this depend on which mail ++package you are using, @code{rmail}, @code{mh-e}, @code{vm}, etc. ++For instance, here is how to do this for @code{mh-e}, the Emacs interface ++to MH: ++@lisp ++(defun mh-add-vi-keys () ++ "Set up ZZ for MH-e and XMH." ++ (viper-add-local-keys 'vi-state '(("ZZ" .@: mh-send-letter)))) ++(add-hook 'mh-letter-mode-hook 'mh-add-vi-keys) ++@end lisp ++ ++You can also use @code{viper-add-local-keys} to set per buffer ++bindings in Insert state and Emacs state by passing as a parameter the ++symbols @code{insert-state} and @code{emacs-state}, respectively. ++As with global bindings, customized local bindings done to Emacs state ++are not inherited by Insert state. ++ ++On rare occasions, local keys may be added by mistake. Usually this is done ++indirectly, by invoking a major mode that adds local keys (e.g., ++@code{shell-mode} redefines @key{RET}). In such a case, exiting the wrong ++major mode won't rid you from unwanted local keys, since these keys are ++local to Viper state and the current buffer, not to the major mode. ++In such situations, the remedy is to type @kbd{M-x viper-zap-local-keys}. ++ ++So much about Viper-specific bindings. ++@xref{Customization,,Customization,emacs,The GNU Emacs ++Manual}, and the Emacs quick reference card for the general info on key ++bindings in Emacs. ++ ++@vindex @code{input-decode-map} ++@vindex @code{function-key-map} ++@vindex @code{viper-vi-global-user-map} ++@vindex @code{viper-insert-global-user-map} ++@vindex @code{viper-emacs-global-user-map} ++@findex @code{viper-add-local-keys} ++@findex @code{viper-zap-local-keys} ++ ++@node Packages that Change Keymaps,Viper Specials,Key Bindings,Customization ++@subsection Packages that Change Keymaps ++@cindex C-c and Viper ++@cindex Viper and C-c ++ ++Viper is designed to coexist with all major and minor modes of Emacs. This ++means that bindings set by those modes are generally available with Viper ++(unless you explicitly prohibit them by setting ++@code{viper-want-emacs-keys-in-vi} and @code{viper-want-emacs-keys-in-insert} to ++@code{nil}). ++If @code{viper-always} is set to @code{t} (which is the default), Viper ++will try to bring each buffer ++in the Viper state that is most appropriate for that buffer. ++Usually, this would be the Vi state, but sometimes it could be the Insert ++state or the Emacs state. ++ ++Some major mode bindings will necessarily be overwritten by Viper. Indeed, in ++Vi state, most of the 1-character keys are used for Vi-style editing. This ++usually causes no problems because most packages designed for editing files ++typically do not bind such keys. Instead, they use key sequences that start ++with @kbd{C-x} and @kbd{C-c}. This is why it was so important for us to ++free up @kbd{C-x} and @kbd{C-c}. ++It is common for language-specific major modes to bind @key{TAB} and ++@kbd{C-j} (the line feed) keys to various formatting functions. This is ++extremely useful, but may require some getting used to for a Vi user. If you ++decide that this feature is not for you, you can re-bind these keys as ++explained earlier (@pxref{Customization}). ++ ++Binding for @key{TAB} is one of the most unusual aspects of Viper for many ++novice users. In Emacs, @key{TAB} is used to format text and programs, and ++is extremely useful. For instance, hitting @key{TAB} causes the current ++line to be re-indented in accordance with the context. In programming, ++this is very important, since improper automatic indentation would ++immediately alert the programmer to a possible error. For instance, if a ++@kbd{)} or a @kbd{"} is missing somewhere above the current ++line, @key{TAB} is likely to mis-indent the line. ++ ++For this reason, Viper doesn't change the standard Emacs binding of ++@key{TAB}, thereby sacrificing Vi compatibility ++(except for users at level 1). Instead, in Viper, the key ++@kbd{S-tab} (shift+ tab) is chosen to emulate Vi's @key{TAB}. ++ ++We should note that on some non-windowing terminals, Shift doesn't modify ++the @key{TAB} key, so @kbd{S-tab} behaves as if it were @key{TAB}. In such ++a case, you will have to bind @code{viper-insert-tab} to some other ++convenient key. ++ ++Some packages, notably Dired, Gnus, Info, etc., attach special meaning to ++common keys like @key{SPC}, @kbd{x}, @kbd{d}, @kbd{v}, and others. This ++means that Vi command state is inappropriate for working with these ++packages. Fortunately, these modes operate on read-only buffers and are ++designed not for editing files, but for special-purpose browsing, reading ++news, mail, etc., and Vi commands are meaningless in these situations. For ++this reason, Viper doesn't force Vi state on such major modes---it ++brings them in Emacs state. You can switch to Vi state by typing @kbd{C-z} ++if, for instance, you want to do Vi-style search in a buffer (although, ++usually, incremental search, which is bound to @kbd{C-s}, is sufficient in ++these situations). But you should then switch back to Emacs state if you ++plan to continue using these major modes productively. You can also switch ++to Vi temporarily, to execute just one command. This is done by typing ++@kbd{C-c \}. (In some of these modes, @kbd{/} and @kbd{:} are bound ++Vi-style, unless these keys perform essential duties.) ++ ++If you would like certain major modes to come up in Emacs state rather than ++Vi state (but Viper thinks otherwise), you should put these major modes ++on the @code{viper-emacs-state-mode-list} list and delete them from ++@code{viper-vi-state-mode-list}. ++Likewise, you can force Viper's Insert state on a major mode by putting it ++in @code{viper-insert-state-mode-list}. ++@vindex @code{viper-emacs-state-mode-list} ++@vindex @code{viper-insert-state-mode-list} ++@vindex @code{viper-vi-state-mode-list} ++ ++It is also possible to impose Vi on some major modes, even though they may ++bind common keys to specialized commands. This might make sense for modes ++that bind only a small number of common keys. For instance, Viper subverts ++the Shell mode by changing the bindings for @kbd{C-m} and @kbd{C-d} using ++@code{viper-add-local-keys} described in the section on customization ++(@pxref{Customization}). ++ ++In some cases, some @emph{minor} modes might override certain essential ++bindings in Vi command state. This is not a big problem because this ++can happen only in the beginning, when the minor mode kicks in. Typing ++@code{M-x viper-mode} will correct the situation. Viper knows about ++several such minor modes and takes care of them, so the above trick ++is usually not necessary. If you find that some minor mode, e.g., ++@code{nasty-mode} interferes with Viper, putting the following in ++@file{.viper} should fix the problem: ++@lisp ++(viper-harness-minor-mode "nasty-mode") ++@end lisp ++@noindent ++The argument to @code{viper-harness-minor-mode} is the name of the file for the ++offending minor mode with the suffixes @file{.el} and @file{.elc} removed. ++ ++It may not be always obvious which minor mode is at fault. The only ++guidance here is to look into the file that defines the minor mode you are ++suspecting, say @file{nasty-mode.el}, and see if it has a variable called ++@code{nasty-mode-map}. Then check if there is a statement of the form ++@lisp ++(define-key nasty-mode-map key function) ++@end lisp ++@noindent ++that binds the misbehaving ++keys. If so, use the above line to harness @code{nasty-mode}. If your ++suspicion is wrong, no harm is done if you harness a minor mode that ++doesn't need to be harnessed. ++ ++It is recommended to harness even those minor modes that don't override ++Viper keys, but still have their own keymaps. A general way to ++make a minor mode, @code{my-mode}, ++compatible with Viper is to have the file @file{my-mode.el} include the following code: ++ ++@lisp ++(when (fboundp 'viper-harness-minor-mode) ++ (let ((lib (file-name-sans-extension ++ (file-name-nondirectory load-file-name)))) ++ (viper-harness-minor-mode lib))) ++@end lisp ++ ++@vindex @code{viper-want-emacs-keys-in-vi} ++@vindex @code{viper-want-emacs-keys-in-insert} ++@vindex @code{viper-always} ++@findex @code{viper-set-hooks} ++@findex @code{viper-mode} ++@findex @code{viper-harness-minor-mode} ++@findex @code{remove-hook} ++@findex @code{add-hook} ++ ++@node Viper Specials,Vi Macros,Packages that Change Keymaps,Customization ++@section Viper Specials ++ ++Viper extends Vi with a number of useful features. This includes various ++search functions, histories of search strings, Ex commands, insertions, and ++Vi's destructive commands. In addition, Viper supports file name completion ++and history, completion of Ex commands and variables, and many other ++features. Some of these features are explained in detail elsewhere in this ++document. Other features are explained here. ++ ++@table @code ++@item (viper-buffer-search-enable) ++@item viper-buffer-search-char nil ++Enable buffer search. Explicit call to @code{viper-buffer-search-enable} ++sets @code{viper-buffer-search-char} to @kbd{g}. Alternatively, the user can ++set @code{viper-buffer-search-char} in @file{.viper} to a key sequence ++to be used for buffer search. There is no need to call ++@code{viper-buffer-search-enable} in that case. ++@findex @code{viper-buffer-search-enable} ++@vindex @code{viper-buffer-search-char} ++@item viper-toggle-search-style ++This function, bound to @kbd{C-c /}, lets one toggle case-sensitive and ++case-insensitive search, and also switch between plain vanilla search and ++search via regular expressions. Without the prefix argument, the user is ++asked which mode to toggle. With prefix argument 1, this toggles ++case-sensitivity. With prefix argument 2, regular expression/vanilla search ++will be toggled. ++ ++However, we found that the most convenient way to toggle ++these options is to bind a Vi macro to ++bind @kbd{//} to toggles case sensitivity and to @kbd{///} to toggles ++vanilla search. Thus, quickly hitting @kbd{/} twice will switch Viper from ++case sensitive search to case-insensitive. Repeating this once again will ++restore the original state. Likewise, quickly hitting @kbd{/} three times ++will switch you from vanilla-style search to search via regular expressions. ++If you hit something other than @kbd{/} after the first @kbd{/} or if the ++second @kbd{/} doesn't follow quickly enough, then Viper will issue the ++usual prompt @kbd{/} and will wait for input, as usual in Vi. ++If you don't like this behavior, you can ``unrecord'' these macros in your ++@file{~/.viper} file. For instance, if you don't like the above feature, put ++this in @file{~/.viper}: ++@example ++(viper-set-searchstyle-toggling-macros 'undefine) ++@end example ++@findex @code{viper-set-searchstyle-toggling-macros} ++ ++If you don't like this feature as a default, but would still like to have ++it in some major modes, you can do so by first unsetting it globally, as ++shown above, and then setting it in the desired major modes as follows: ++@example ++(viper-set-searchstyle-toggling-macros nil 'c-mode) ++(viper-set-searchstyle-toggling-macros nil 'lisp-mode) ++@end example ++ ++@item Vi-isms in Emacs state ++Some people find it useful to use the Vi-style search key, `/', to invoke ++search in modes which Viper leaves in emacs-state. These modes are: ++@code{dired-mode}, @code{mh-folder-mode}, ++@code{Info-mode}, and @code{Buffer-menu-mode} ++(more may be added in the future). So, in the above modes, Viper binds `/' ++so that it will behave Vi-style. Furthermore, in those major modes, Viper ++binds `:' to invoke ex-style commands, like in vi-state. And, as described ++above, `//' and `///' get bound to Vi-style macros that toggle ++case-insensitivity and regexp-search. ++ ++If you don't like these features---which I don't really understand---you ++can unbind `/' and `:' in @code{viper-dired-modifier-map} (for Dired) or in ++@code{viper-slash-and-colon-map}, for other modes. ++@vindex @code{viper-slash-and-colon-map} ++@vindex @code{viper-dired-modifier-map} ++ ++To unbind the macros `//' and `///' for a major mode where you feel they ++are undesirable, execute @code{viper-set-emacs-state-searchstyle-macros} with a ++non-@code{nil} argument. This can be done either interactively, by supplying a ++prefix argument, or by placing ++@example ++(viper-set-emacs-state-searchstyle-macros 'undefine) ++@end example ++@findex @code{viper-set-emacs-state-searchstyle-macros} ++in the hook to the major mode (e.g., @code{dired-mode-hook}). ++@xref{Vi Macros}, for more information on Vi macros. ++ ++@item viper-heading-start ++@item viper-heading-end ++@cindex headings ++@cindex sections ++@cindex paragraphs ++@cindex sentences ++Regular Expressions for @kbd{[[} and @kbd{]]}. Note that Emacs defines ++Regexps for paragraphs and sentences. @xref{Paragraphs,,Paragraphs and ++Sentences,emacs,The GNU Emacs Manual}, for details. ++@item M-x viper-set-expert-level ++@findex @code{viper-set-expert-level} ++Change your user level interactively. ++@item viper-smart-suffix-list '("" "tex" "c" "cc" "el" "p") ++@vindex @code{viper-smart-suffix-list} ++Viper supports Emacs-style file completion when it prompts the user for a ++file name. However, in many cases, the same directory may contain files ++with identical prefix but different suffixes, e.g., prog.c, prog.o, ++paper.tex, paper.dvi. In such cases, completion will stop at the `.'. ++If the above variable is a list of strings representing suffixes, Viper will ++try these suffixes ++in the order listed and will check if the corresponding file exists. ++ ++For instance, if completion stopped at `paper.'@: and the user typed ++@key{RET}, ++then Viper will check if the files `paper.', `paper.tex', `paper.c', etc., exist. ++It will take the first such file. If no file exists, Viper will give a chance ++to complete the file name by typing the appropriate suffix. If `paper.'@: was ++the intended file name, hitting return will accept it. ++ ++To turn this feature off, set the above variable to @code{nil}. ++ ++@item viper-insertion-ring-size 14 ++@vindex @code{viper-insertion-ring-size} ++@cindex Insertion ring ++Viper remembers what was previously inserted in Insert and Replace states. ++Several such recent insertions are kept in a special ring of strings of size ++@code{viper-insertion-ring-size}. ++If you enter Insert or Replace state you can reinsert strings from this ++ring by typing @kbd{C-c M-p} or @kbd{C-c M-n}. The former will search the ++ring in ++the direction of older insertions, and the latter will search in ++the direction of newer insertions. Hitting @kbd{C-c M-p} or @kbd{C-c M-n} ++in succession ++will undo the previous insertion from the ring and insert the next item on ++the ring. If a larger ring size is needed, change the value of the above ++variable in the @file{~/.viper} file. ++ ++Since typing these sequences of keys may be tedious, it is suggested that the ++user should bind a function key, such as @kbd{f31}, as follows: ++@example ++(define-key viper-insert-global-user-map [f31] ++ 'viper-insert-prev-from-insertion-ring) ++@end example ++This binds @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) ++to the function that inserts the previous string in the insertion history. ++To rotate the history in the opposite ++direction, you can either bind an unused key to ++@code{viper-insert-next-from-insertion-ring} or hit any digit (1 to 9) then ++@kbd{f31}. ++ ++One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since ++this will interfere with the Minibuffer histories and, possibly, other ++major modes. ++ ++@item viper-command-ring-size 14 ++@vindex @code{viper-command-ring-size} ++@cindex Destructive command ring ++@cindex Destructive command history ++Viper keeps track of the recent history of destructive ++commands, such as @kbd{dw}, @kbd{i}, etc. ++In Vi state, ++the most recent command can be re-executed by hitting `@kbd{.}', as in Vi. ++However, repeated typing @kbd{C-c M-p} will cause Viper to show the ++previous destructive commands in the minibuffer. Subsequent hitting `@kbd{.}' ++will execute the command that was displayed last. ++The key @kbd{C-c M-n} will cycle through the command history in the ++opposite direction. ++Since typing @kbd{C-c M-p} may be tedious, it is more convenient to bind an ++appropriate function to an unused function key on the keyboard and use that ++key. For instance, the following ++@example ++(define-key viper-vi-global-user-map [f31] ++ 'viper-prev-destructive-command) ++@end example ++binds the key @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) ++to the function that searches the command history in the direction of older ++commands. To search in the opposite ++direction, you can either bind an unused key to ++@code{viper-next-destructive-command} or hit any digit (1 to 9) then @kbd{f31}. ++ ++One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since ++this will interfere with the Minibuffer histories and, possibly, other ++major modes. ++ ++@item viper-minibuffer-vi-face 'viper-minibuffer-vi-face ++@item viper-minibuffer-insert-face 'viper-minibuffer-insert-face ++@item viper-minibuffer-emacs-face 'viper-minibuffer-emacs-face ++These faces control the appearance of the minibuffer text in the ++corresponding Viper states. You can change the appearance of these faces ++through Emacs' customization widget, which is accessible through the ++menubar. ++ ++Viper is located in this widget under the @emph{Emulations} customization ++subgroup of the @emph{Editing} group. All Viper faces are grouped together ++in Viper's @emph{Highlighting} customization subgroup. ++ ++Note that only the text you type in is affected by the above faces. ++Prompts and Minibuffer messages are not affected. ++ ++Purists who do not like adornments in the minibuffer can always zap them by ++putting ++@example ++(copy-face 'default 'viper-minibuffer-vi-face) ++(copy-face 'default 'viper-minibuffer-insert-face) ++(copy-face 'default 'viper-minibuffer-emacs-face) ++@end example ++in the @file{~/.viper} file or through the customization widget, as ++described above. However, in that case, the user will not have any ++indication of the current Viper state in the minibuffer. (This is important ++if the user accidentally switches to another Viper state by typing @key{ESC} or ++@kbd{C-z}). ++@item M-x viper-go-away ++@findex @code{viper-go-away} ++Make Viper disappear from the face of your running Emacs instance. If your ++fingers start aching again, @kbd{M-x viper-mode} might save your day. ++@item M-x toggle-viper-mode ++@findex @code{toggle-viper-mode} ++Toggle Viperization of Emacs on and off. ++@end table ++ ++@cindex Multifile documents and programs ++ ++Viper provides some support for multi-file documents and programs. ++If a document consists of several files we can designate one of them as a ++master and put the following at the end of that file: ++@lisp ++;; Local Variables: ++;; eval: (viper-setup-master-buffer "file1" "file2" "file3" "file4") ++;; End: ++@end lisp ++@noindent ++where @code{file1} to @code{file4} are names of files related to the master ++file. Next time, when the master file is visited, the command ++@code{viper-setup-master-buffer} will be evaluated and the above files will ++be associated with the master file. Then, the new Ex command ++@kbd{:RelatedFile} (abbr.@: @kbd{:R}) will display files 1 to 4 one after ++another, so you can edit them. If a file is not in any Emacs buffer, it ++will be visited. The command @kbd{PreviousRelatedFile} (abbr., @kbd{:P}) ++goes through the file list in the opposite direction. ++@findex @kbd{:RelatedFile} ++@findex @kbd{:PreviousRelatedFile} ++ ++These commands are akin to @kbd{:n} and @kbd{:N}, but they allow the user to ++focus on relevant files only. ++ ++Note that only the master file needs to have the aforementioned block of ++commands. Also, ";;" above can be replaced by some other ++markers. Semicolon is good for Lisp programs, since it is considered a ++comment designator there. For LaTeX, this could be "%%%", and for C the ++above block should be commented out. ++ ++Even though these commands are sometimes useful, they are no substitute for ++the powerful @emph{tag table} facility of Emacs. Viper's @kbd{:tag} command ++in a primitive interface to Emacs tags. @xref{Tags,Tags,Tags,emacs, ++The GNU Emacs Manual}, for more information on tags. ++ ++The following two commands are normally bound to a mouse click and are part ++of Viper. They work only if Emacs runs as an application under X ++Windows (or under some other window system for which a port of GNU Emacs 20 ++is available). Clicking the mouse when Emacs is invoked in an Xterm window ++(using @code{emacs -nw}) will do no good. ++ ++@table @code ++@cindex mouse ++@cindex mouse-search ++@item viper-mouse-search-key (meta shift 1) ++@vindex @code{viper-mouse-insert-key} ++This variable controls the @emph{mouse-search} feature of Viper. The ++default value ++states that holding Meta and Shift keys while clicking mouse button 1 ++should initiate search for a region under the mouse pointer (defined ++below). This command can take a prefix argument, which indicates the ++occurrence of the pattern to search for. ++ ++Note: while loading initially, Viper binds this mouse action only if it is ++not already bound to something else. If you want to use the mouse-search ++feature, and the @kbd{Meta-Shift-Mouse-1} mouse action is already bound to ++something else, you can rebind the mouse-search feature by setting ++@code{viper-mouse-search-key} to something else in your @code{~/.viper} ++file: ++@lisp ++(setq viper-mouse-search-key '(meta 1)) ++@end lisp ++This would bind mouse search to the action invoked by pressing the ++Meta key and clicking mouse button 1. The allowed values of ++@code{viper-mouse-search-key} are lists that contain a mouse-button number ++(1,2, or 3) and any combination of the words `control', `meta', and ++`shift'. ++ ++If the requested mouse action (e.g., (meta 1)) is already taken for other ++purposes then you have to confirm your intention by placing the following ++command in @code{~/.viper} after setting @code{viper-mouse-search-key}: ++@lisp ++(viper-bind-mouse-search-key 'force) ++@end lisp ++ ++You can also change this setting interactively, through the customization ++widget of Emacs (type @kbd{:customize}). ++ ++The region that is chosen as a pattern to search for is determined as ++follows. If search is invoked via a single click, Viper chooses the region ++that lies between the beginning of the ``word'' under the pointer (``word'' ++is understood in Vi sense) and the end of that word. The only difference ++with Vi's words is that in Lisp major modes `-' is considered an ++alphanumeric symbol. This is done for the convenience of working with Lisp ++symbols, which often have an `-' in them. Also, if you click on a ++non-alphanumeric character that is not a word separator (in Vi sense) then ++this character will also be considered alphanumeric, provided that it is ++adjacent (from either side) to an alphanumeric character. This useful ++feature gives added control over the patterns selected by the mouse click. ++ ++On a double-click, the region is determined by the beginning of the current ++Vi's ``Word'' (i.e., the largest non-separator chunk of text) and the End ++of that ``Word'' (as determined by the @kbd{E} command). ++ ++On a triple-click, the region consists of the entire line where the click ++occurred with all leading and trailing spaces and tabs removed. ++ ++@cindex mouse-insert ++@item viper-mouse-insert-key (meta shift 2) ++@vindex @code{viper-mouse-insert-key} ++This variable controls the @emph{mouse-insert} feature of Viper. ++The above default value states that ++holding Meta and Shift keys while clicking mouse button 2 ++should insert the region surrounding the ++mouse pointer. The rules defining this region are the same as for ++mouse-search. This command takes an optional prefix argument, which ++indicates how many such regions to snarf from the buffer and insert. (In ++case of a triple-click, the prefix argument is ignored.) ++ ++Note: while loading initially, Viper binds this mouse action only if it not ++already bound to something else. If you want to use this feature and the ++default mouse action is already bound, you can rebind mouse-insert by ++placing this command in @code{~/.viper}: ++@lisp ++(setq viper-mouse-insert-key '(meta 2)) ++@end lisp ++If you want to bind mouse-insert to an action even if this action is ++already taken for other purposes in Emacs, then you should add this command ++to @code{~/.viper}, after setting @code{viper-mouse-insert-key}: ++@lisp ++(viper-bind-mouse-insert-key 'force) ++@end lisp ++ ++This value can also be changed via the Emacs customization widget at the ++menubar. ++ ++@item viper-multiclick-timeout ++This variable controls the rate at which double-clicking must occur for the ++purpose of mouse search and mouse insert. By default, this is set to ++@code{double-click-time} in Emacs and to ++@code{mouse-track-multi-click-time} milliseconds in XEmacs. ++@end table ++@kindex @kbd{S-Mouse-1} ++@kindex @kbd{S-Mouse-2} ++@kindex @kbd{meta shift button1up} ++@kindex @kbd{meta shift button2up} ++@vindex @code{viper-multiclick-timeout} ++@findex @code{viper-mouse-click-insert-word} ++@findex @code{viper-mouse-click-search-word} ++ ++Note: The above functions search and insert in the selected window of ++the latest active frame. This means that you can click in another window or ++another frame and have search or insertion done in the frame and window you ++just left. This lets one use these functions in a multi-frame ++configuration. However, this may require some getting used to. For ++instance, if you are typing in a frame, A, and then move the mouse to frame ++B and click to invoke mouse search, search (or insertion) will be performed ++in frame A. To perform search/insertion in frame B, you will first have to ++shift focus there, which doesn't happen until you type a character or ++perform some other action in frame B---mouse search doesn't shift focus. ++ ++If you decide that you don't like the above feature and always want ++search/insertion be performed in the frame where the click occurs, don't ++bind (and unbind, if necessary) @code{viper-mouse-catch-frame-switch} from ++the mouse event it is bound to. ++ ++Mouse search is integrated with Vi-style search, so you can ++repeat it with @kbd{n} and @kbd{N}. It should be also noted that, while ++case-sensitivity of search in Viper is controlled by the variable ++@code{viper-case-fold-search}, the case of mouse search is ++controlled by the Emacs variable @code{case-fold-search}, which may be set ++differently from @code{viper-case-fold-search}. Therefore, case-sensitivity ++of mouse search may be different from that of the usual Vi-style search. ++ ++Finally, if the way Viper determines the word to be searched for or to be ++inserted is not what you want, there is a variable, ++@code{viper-surrounding-word-function}, which can be changed to indicate ++another function for snarfing words out of the buffer. The catch is that ++you will then have to write such a function and make it known to your ++Emacs. The function @code{viper-surrounding-word} in @file{viper.el} can be ++used as a guiding example. ++ ++@node Vi Macros, ,Viper Specials,Customization ++@section Vi Macros ++ ++@cindex Vi macros ++ ++Viper supports much enhanced Vi-style macros and also facilitates the use ++of Emacs-style macros. To define a temporary macro, it is generally more ++convenient to use Emacs keyboard macro facility. Emacs keyboard macros are ++usually defined anonymously, and the latest macro can be executed by typing ++@kbd{C-x e} (or @kbd{*}, if Viper is in Vi state). If you need to use several ++temporary macros, Viper lets you save them to a ++register (a lowercase letter); such macros can then be executed by typing ++@kbd{@@a} in Vi state (if a macro was previously saved in register ++@kbd{a}). ++@xref{Macros and Registers}, for details. ++ ++If, however, you need to use a macro regularly, it must be given a ++permanent name and saved. Emacs manual explains how to do this, but ++invocation of named Emacs macros is quite different from Vi's. First, ++invocation of permanent Emacs macros takes time because it requires typing ++too many keys (to a Vi user's taste, anyway). ++Second, binding such macros to function keys, for ++fast access, hogs valuable real estate on the keyboard. ++ ++Vi-style macros are better in that respect, since Vi lets the user overload ++the meaning of key sequences: keys typed in fast succession are treated ++specially, if this key sequence is bound to a macro. ++ ++Viper provides Vi-style keyboard macros through the usual Ex commands, ++@kbd{:map} and ++@kbd{:map!}. These macros are much more powerful in Viper than ++they are in the original Vi and in other emulators. This is because Viper ++implements an enhanced vi-style ++interface to the powerful Emacs keyboard macro facility. ++ ++First, any Emacs ++command can be executed while defining a macro, not just the Vi ++commands. In particular, the user can invoke Emacs commands via @kbd{M-x ++command-name} or by pressing various function keys on the keyboard. One ++can even use the mouse, although this is usually not useful and is not ++recommended (and macros defined with the use of the mouse cannot be saved in ++command history and in the startup file, for future use). ++ ++Macros defined by mixing Vi and Emacs commands are represented as ++vectors. So, don't be confused when you see one (usually through the ++history of Ex commands). For instance, if @kbd{gg} is defined by typing ++@kbd{l}, the up-arrow key and @kbd{M-x next-line}, its definition will look ++as follows in Emacs: ++ ++@example ++[l up (meta x) n e x t - l i n e return] ++@end example ++ ++Second, Viper macros are defined in a WYSIWYG style. This means that ++commands are executed as you type them, so you can see precisely what is ++being defined. Third, macros can be bound to arbitrary sequences of keys, ++not just to printable keys. For instance, one can define a macro that will ++be invoked by hitting @kbd{f3} then @kbd{f2} function keys. (The keys ++@kbd{delete} and @kbd{backspace} are excluded; also, a macro invocation ++sequence can't start with @key{ESC}. Some other keys, such as @kbd{f1} and ++@kbd{help}, can't be bound to macros under Emacs, since they ++are bound in @code{key-translation-map}, which overrides any other binding ++the user gives to keys. In general, keys that have a binding in ++@code{key-translation-map} can't be bound to a macro.) ++ ++Fourth, in Viper, one can define macros that are specific to a given ++buffer, a given major mode, or macros that are defined for all buffers. In ++fact, the same macro name can have several different definitions: one ++global, several definitions for various major modes, and ++definitions for various specific buffers. Buffer-specific definitions ++override mode-specific definitions, which, in turn, override global ++definitions. ++ ++As if all that is not enough, Viper (through its interface to Emacs ++macros) lets the user define keyboard macros that ask for confirmation or ++even prompt the user for input and then continue. To do this, one should ++type @kbd{C-x q} (for confirmation) or @kbd{C-u C-x q} (for prompt). ++For details, @pxref{Keyboard Macro Query,,Customization,emacs,The GNU Emacs ++Manual} @refill ++ ++When the user finishes defining a macro (which is done by typing @kbd{C-x)} --- ++a departure from Vi), you will be asked whether you want this ++macro to be global, mode-specific, or buffer-specific. You will also be ++given a chance to save the macro in your @file{~/.viper} file. ++This is the easiest way to save a macro and make ++it permanently available. If you work your startup files with bare hands, ++here is how Viper saves the above macro so that it will be ++available in Viper's Insert state (and Replace state) in buffer @code{my-buf} ++only: ++ ++@example ++(viper-record-kbd-macro "gg" 'insert-state ++ [l up (meta x) n e x t - l i n e return] ++ "my-buf") ++@end example ++ ++@noindent ++To do the same for Vi state and all buffers with the major mode ++@code{cc-mode}, use: ++ ++@example ++(viper-record-kbd-macro "gg" 'vi-state ++ [l up (meta x) n e x t - l i n e return] ++ 'cc-mode) ++@end example ++ ++@noindent ++Both macro names and macro definitions are vectors of symbols that denote ++keys on the keyboard. Some keys, like @kbd{\}, @kbd{ }, or digit-keys must ++be escaped with a backslash. Modified keys are represented as lists. For ++instance, holding Meta and Control and pressing @kbd{f4} is represented as ++@kbd{(control meta f4)}. ++If all members of a vectors are printable characters (or sequences, such as ++@kbd{\e}, @kbd{\t}, for @key{ESC} and @key{TAB}), then they can also be represented as ++strings: ++ ++@example ++(viper-record-kbd-macro "aa" 'vi-state "aaa\e" "my-buffer") ++@end example ++ ++@noindent ++Thus, typing @kbd{aa} fast in Vi state will switch Viper to Insert state ++(due to the first @kbd{a}), insert @kbd{aa}, and then it will switch back to Vi ++state. All this will take effect only in the buffer named @code{my-buffer}. ++ ++Note that the last argument to @code{viper-record-kbd-macro} must be either a ++string (a buffer name), a symbol representing a major mode, or @code{t}; ++the latter says that the macro is to be defined for all buffers ++(which is how macros are defined in original Vi). ++ ++For convenience, Viper also lets you define Vi-style macros in its Emacs ++state. There is no Ex command, like @kbd{:map} and @kbd{:map!} for doing ++this, but the user can include such a macro in the @file{~/.viper} file. The ++only thing is that the @code{viper-record-kbd-macro} command should specify ++@code{emacs-state} instead of @code{vi-state} or @code{insert-state}. ++ ++The user can get rid of a macro either by using the Ex commands @kbd{:unmap} ++and @kbd{:unmap!} or by issuing a call to @code{viper-unrecord-kbd-macro}. ++The latter is more powerful, since it can delete macros even in ++@code{emacs-state}. However, @code{viper-unrecord-kbd-macro} is usually ++needed only when the user needs to get rid of the macros that are already ++predefined in Viper. ++The syntax is: ++@findex @code{viper-unrecord-kbd-macro} ++@example ++(viper-unrecord-kbd-macro macro state) ++@end example ++@noindent ++The second argument must be @code{vi-state}, @code{insert-state}, or ++@code{emacs-state}. The first argument is a name of a macro. To avoid ++mistakes in specifying names of existing macros, type @kbd{M-x ++viper-describe-kbd-macros} and use a name from the list displayed by this ++command. ++ ++If an error occurs during macro definition, Emacs ++aborts the process, and it must be repeated. This is analogous to Vi, ++except that in Vi the user doesn't know there is an error until the macro is ++actually run. All that means that in order for a definition to be ++successful, the user must do some simple planning of the process in ++advance, to avoid errors. For instance, if you want to map @kbd{gg} to ++@kbd{llll} in Vi state, you must make sure that there is enough room on the ++current line. Since @kbd{l} moves the cursor forward, it may signal an ++error on reaching the end of line, which will abort the definition. ++ ++These precautions are necessary only when defining macros; they will help ++avoid the need to redo the job. When macros are actually run, an error ++during the execution will simply terminate the current execution ++(but the macro will remain mapped). ++ ++A macro name can be a string of characters or a vector of keys. ++The latter makes it possible to define macros bound to, say, double-hits ++on a function key, such as @kbd{up} or @kbd{f13}. ++This is very useful if you run out of function keys on your keyboard; it ++makes Viper macro facility a @emph{keyboard doubler}, so to speak. ++ ++Elsewhere (@xref{Key Bindings}, for details), we review ++the standard Emacs mechanism for binding function keys to commands. ++For instance, ++ ++@example ++(global-set-key [f13] 'repeat-complex-command) ++@end example ++ ++@noindent ++binds the key f13 to the Emacs function that repeats the last minibuffer ++command. Under Viper, however, you may still use this key for additional ++purposes, if you bind, say, a double-hitting action for that key to some ++other function. Emacs doesn't allow the user to do that, but Viper does ++this through its keyboard macro facility. To do this, type @kbd{:map } ++first. When you are asked to enter a macro name, hit f13 twice, followed by ++@key{RET} or @key{SPC}. ++ ++Emacs will now start the mapping process by actually executing ++Vi and Emacs commands, so that you could see what will happen each time the ++macro is executed. Suppose now we wanted to bind the key sequence ++@kbd{f13 f13} to the command @code{eval-last-sexp}. To accomplish this, we ++can type @kbd{M-x eval-last-sexp} followed by @kbd{C-x )}. ++If you answer positively to Viper's offer to save this macro in @file{~/.viper} ++for future uses, the following will be inserted in that file: ++ ++@example ++(viper-record-kbd-macro [f16 f16] 'vi-state ++ [(meta x) e v a l - l a s t - s e x p] ++ 'lisp-interaction-mode) ++@end example ++ ++To illustrate the above point, Viper provides two canned macros, which, by ++default, are bound to @kbd{[f12 \1]} and @kbd{[f12 \2]} (invoked by typing ++@kbd{f12} then @kbd{1} and @kbd{2}, respectively). These macros are useful ++shortcuts to Viper's command ring history. The first macro will execute the ++second-last destructive command (the last one is executed by @kbd{.}, as ++usual). The second macro executes the third-last command. ++ ++If you need to go deeper into the command history, you will have to use ++other commands, as described earlier in this section; or you can bind, ++say, @kbd{f12 \3} like this: ++ ++@example ++(viper-record-kbd-macro [f12 \3] 'vi-state ++ [(meta x) r e p e a t - f r o m - h i s t o r y] ++ t) ++@end example ++ ++ ++Note that even though the macro uses the function key @kbd{f12}, the key is ++actually free and can still be bound to some Emacs function via ++@code{define-key} or @code{global-set-key}. ++ ++ ++Viper allows the user to define macro names that are prefixes of other macros. ++For instance, one can define @kbd{[[} and @kbd{[[[[} to be macros. ++If you type the exact sequence of such keys and then pause, Viper will ++execute the right macro. However, if you don't pause and, say, type ++@kbd{[[[[text} then the conflict is resolved as follows. If only one of the ++key sequences, @kbd{[[} or @kbd{[[[[} has a definition applicable to the ++current buffer, then, in fact, there is no conflict and the right macro ++will be chosen. If both have applicable definitions, then the first one ++found will be executed. Usually this is the macro with a shorter name. So, ++in our case, @kbd{[[[[text} will cause the macro @kbd{[[} to be executed ++twice and then the remaining keys, @kbd{t e x t}, will be processed. ++ ++When defining macros using @kbd{:map} or @kbd{:map!}, the user enters ++the actually keys to be used to invoke the macro. For instance, you ++should hit the actual key @kbd{f6} if it is to be part of a macro ++name; you do @emph{not} write @kbd{f 6}. When entering keys, Viper ++displays them as strings or vectors (e.g., @code{"abc"} or @code{[f6 ++f7 a]}). The same holds for unmapping. Hitting @key{TAB} while ++typing a macro name in the @kbd{:unmap} or @kbd{:unmap!} command will ++cause name completion. Completions are displayed as strings or ++vectors. However, as before, you don't actually type @samp{"}, ++@samp{[}, or @samp{]} that appear in the completions. These are ++meta-symbols that indicate whether the corresponding macro name is a ++vector or a string. ++ ++One last difference from Vi: Vi-style keyboard macros cannot be defined in ++terms of other Vi-style keyboard macros (but named Emacs macros are OK). ++More precisely, while defining or executing a macro, the special meaning ++of key sequences (as Vi macros) is ignored. ++This is because it is all too easy to create an infinite loop in this way. ++Since Viper macros are much more powerful than Vi's it is impossible to ++detect such loops. In practice, this is not really a limitation but, ++rather, a feature. ++ ++We should also note that Vi macros are disabled in the Minibuffer, which ++helps keep some potential troubles away. ++ ++The rate at which the user must type keys in order for them to be ++recognized as a timeout macro is controlled by the variable ++@code{viper-fast-keyseq-timeout}, which defaults to 200 milliseconds. ++ ++For the most part, Viper macros defined in @file{~/.viper} can be shared ++between X and TTY modes. ++The problem with TTY may be that the function keys there generate sequences ++of events instead of a single event (as under a window system). ++Emacs maps some of these sequences back to the logical keys ++(e.g., the sequences generated by the arrow keys are mapped to @kbd{up}, ++@kbd{left}, etc.). However, not all function keys are mapped in this way. ++Macros that are bound to key sequences that contain such unmapped function ++keys have to be redefined for TTY's (and possibly for every type of TTY you ++may be using). To do this, start Emacs on an appropriate TTY device and ++define the macro using @kbd{:map}, as usual. ++ ++@findex @code{viper-describe-kbd-macros} ++Finally, Viper provides a function that conveniently displays all macros ++currently defined. To see all macros along with their definitions, type ++@kbd{M-x viper-describe-kbd-macros}. ++ ++@node Commands,,Customization,Top ++@chapter Commands ++ ++This section is a semi-automatically bowdlerized version of the Vi ++reference created by @* @samp{maart@@cs.vu.nl} and others. It can be ++found on the Vi archives. This reference has been adapted for Viper.@refill ++ ++@menu ++* Groundwork:: Textual Conventions and Viper basics ++* Text Handling:: Moving, Editing, Undoing. ++* Display:: Scrolling. ++* File and Buffer Handling:: Editing, Writing and Quitting. ++* Mapping:: Mapping Keys, Keyboard Macros ++* Shell Commands:: Accessing Shell Commands, Processing Text ++* Options:: Ex options, the @kbd{:set} commands ++* Emacs Related Commands:: Meta Keys, Windows ++* Mouse-bound Commands:: Search and insertion of text ++@end menu ++ ++@node Groundwork, Text Handling, Commands, Commands ++@comment node-name, next, previous, up ++@section Groundwork ++ ++The VI command set is based on the idea of combining motion commands ++with other commands. The motion command is used as a text region ++specifier for other commands. ++We classify motion commands into @dfn{point commands} and ++@dfn{line commands}.@refill ++ ++@cindex point commands ++ ++The point commands are: ++ ++@quotation ++@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, ++@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, ++@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} ++@end quotation ++ ++@cindex line commands ++ ++The line commands are: ++ ++@quotation ++@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, ++@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} ++@end quotation ++@noindent ++ ++Text Deletion Commands (@pxref{Deleting Text}), Change commands ++(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) ++use these commands to describe a region of text to operate on. ++ ++@cindex r and R region specifiers ++ ++Viper adds two region descriptors, @kbd{r} and @kbd{R}. These describe ++the Emacs regions (@pxref{Basics}), but they are not movement commands. ++ ++The command description uses angle brackets @samp{<>} to indicate ++metasyntactic variables, since the normal conventions of using simple ++text can be confusing with Viper where the commands themselves are ++characters. Watch out where @kbd{<} shift commands and @kbd{} are ++mentioned together!!! ++ ++@kindex ++@kindex ++@kindex
++@cindex ++@cindex ++@cindex
++@cindex movements ++ ++@samp{} refers to the above movement commands, and @samp{} ++refers to registers or textmarkers from @samp{a} to @samp{z}. Note ++that the @samp{} is described by full move commands, that is to ++say they will take counts, and otherwise behave like normal move commands. ++@cindex Ex addresses ++@samp{
} refers to Ex line addresses, which include ++ ++@table @kbd ++@item .@: ++Current line ++@item .+n .-n ++Add or subtract for current line ++@item number ++Actual line number, use @kbd{.=} to get the line number ++@item ' ++Textmarker ++@item $ ++Last line ++@item x,y ++Where x and y are one of the above ++@item % ++@cindex % (Ex address) ++For the whole file, same as (1,$). ++@item // ++@itemx ?? ++Next or previous line with pattern . ++ ++Note that the pattern is allowed to contain newline character (inserted as ++@kbd{C-qC-j}). Therefore, one can search for patterns that span several ++lines. ++@end table ++ ++@cindex % (Current file) ++Note that @samp{%} is used in Ex commands @kbd{:e} and @kbd{:r } ++to mean current file. If you want a @samp{%} in your command, it must be ++escaped as @samp{\%}. Note that @kbd{:w} and the regular @kbd{:r } ++command doesn't support the meta symbols @samp{%} and @samp{#}, because ++file history is a better mechanism. ++@cindex # (Previous file) ++Similarly, @samp{#} expands to the previous file. The previous file is ++the first file in @kbd{:args} listing. This defaults to previous window ++in the VI sense if you have one window only. ++ ++@kindex ++@kindex ++@cindex ++@cindex ++@noindent ++Others like @samp{ -- arguments}, @samp{ -- command} etc. ++should be fairly obvious. ++ ++@noindent ++Common characters referred to include: ++ ++@table @kbd ++@item ++Space ++@item ++Tab ++@item ++Linefeed ++@item ++Escape ++@item ++Return, Enter ++@end table ++@cindex ++@cindex ++@cindex ++@cindex ++@cindex ++ ++@cindex words ++@cindex WORDS ++@cindex char ++@cindex CHAR ++ ++We also use @samp{word} for alphanumeric/non-alphanumeric words, and ++@samp{WORD} for whitespace delimited words. @samp{char} refers to any ++@acronym{ASCII} character, @samp{CHAR} to non-whitespace character. ++Brackets @samp{[]} indicate optional parameters; @samp{} also ++optional, usually defaulting to 1. Brackets are elided for ++@samp{} to eschew obfuscation. ++ ++Viper's idea of Vi's words is slightly different from Vi. First, Viper ++words understand Emacs symbol tables. Therefore, all symbols declared to be ++alphanumeric in a symbol table can automatically be made part of the Viper ++word. This is useful when, for instance, editing text containing European, ++Cyrillic, Japanese, etc., texts. ++ ++Second, Viper lets you depart from Vi's idea of a word by changing the a ++syntax preference via the customization widget (the variable ++@code{viper-syntax-preference}) or by executing ++@code{viper-set-syntax-preference} interactively. ++ ++By default, Viper syntax preference is @code{reformed-vi}, which means that ++Viper considers only those symbols to be part of a word that are specified ++as word-symbols by the current Emacs syntax table (which may be different ++for different major modes) plus the underscore symbol @kbd{_}, minus the ++symbols that are not considered words in Vi (e.g., `,',;, etc.), but may be ++considered as word-symbols by various Emacs major modes. Reformed-Vi works ++very close to Vi, and it also recognizes words in other ++alphabets. Therefore, this is the most appropriate mode for editing text ++and is likely to fit all your needs. ++ ++You can also set Viper syntax preference to @code{strict-vi}, which would ++cause Viper to view all non-English letters as non-word-symbols. ++ ++You can also specify @code{emacs} as your preference, which would ++make Viper use exactly the same notion of a word as Emacs does. In ++particular, the underscore may not be part of a word in some major modes. ++ ++Finally, if @code{viper-syntax-preference} is set to @code{extended}, Viper ++words would consist of characters that are classified as alphanumeric ++@emph{or} as parts of symbols. This is convenient for editing programs. ++ ++@code{viper-syntax-preference} is a local variable, so it can have different ++values for different major modes. For instance, in programming modes it can ++have the value @code{extended}. In text modes where words contain special ++characters, such as European (non-English) letters, Cyrillic letters, etc., ++the value can be @code{reformed-vi} or @code{emacs}. ++If you consider using different syntactic preferences for different major ++modes, you should execute, for example, ++ ++@example ++(viper-set-syntax-preference nil "extended") ++@end example ++ ++in the appropriate major mode hooks. ++ ++@vindex @code{viper-syntax-preference} ++@findex @code{viper-set-syntax-preference} ++@cindex syntax table ++ ++ ++ ++The above discussion concerns only the movement commands. In regular ++expressions, words remain the same as in Emacs. That is, the expressions ++@code{\w}, @code{\>}, @code{\<}, etc., use Emacs' idea of what is a word, ++and they don't look into the value of variable ++@code{viper-syntax-preference}. This is because Viper avoids changing ++syntax tables in order to not thwart the various major modes that set these ++tables. ++ ++The usual Emacs convention is used to indicate Control Characters, i.e ++C-h for Control-h. @emph{Do not confuse this with a sequence of separate ++characters ++C, -, h!!!} The @kbd{^} is itself, never used to indicate a ++Control character. ++ ++Finally, we note that Viper's Ex-style commands can be made to work on the ++current Emacs region. This is done by typing a digit argument before ++@kbd{:}. For instance, typing @kbd{1:} will prompt you with something like ++@emph{:123,135}, assuming that the current region starts at line 123 and ++ends at line 135. There is no need to type the line numbers, since Viper ++inserts them automatically in front of the Ex command. ++@cindex Ex commands ++ ++@node Text Handling, Display, Groundwork, Commands ++@section Text Handling ++ ++@menu ++* Move Commands:: Moving, Searching ++* Marking:: Textmarkers in Viper and the Emacs Mark. ++* Appending Text:: Text insertion, Shifting, Putting ++* Editing in Insert State:: Autoindent, Quoting etc. ++* Deleting Text:: Deleting ++* Changing Text:: Changing, Replacement, Joining ++* Search and Replace:: Searches, Query Replace, Pattern Commands ++* Yanking:: Yanking, Viewing Registers ++* Undoing:: Multiple Undo, Backups ++@end menu ++ ++@node Move Commands,Marking,,Text Handling ++@subsection Move Commands ++ ++@cindex movement commands ++@cindex searching ++@cindex textmarkers ++@cindex markers ++@cindex column movement ++@cindex paragraphs ++@cindex headings ++@cindex sections ++@cindex sentences ++@cindex matching parens ++@cindex paren matching ++ ++@table @kbd ++@item h C-h ++ chars to the left. ++@item j C-n ++ lines downward. ++@item l ++ chars to the right. ++@item k C-p ++ lines upward. ++@item $ ++To the end of line from the cursor. ++@item ^ ++To the first CHAR - 1 lines lower. ++@item - ++To the first CHAR lines higher. ++@item + ++To the first CHAR lines lower. ++@item 0 ++To the first char of the line. ++@item | ++To column ++@item f ++ s to the right (find). ++@item t ++Till before s to the right. ++@item F ++ s to the left. ++@item T ++Till after s to the left. ++@item ; ++Repeat latest @kbd{f t F T} times. ++@item , ++Repeat latest @kbd{f t F T} ++ times in opposite direction. ++@item w ++ words forward. ++@item W ++ WORDS forward. ++@item b ++ words backward. ++@item B ++ WORDS backward. ++@item e ++To the end of word forward. ++@item E ++To the end of WORD forward. ++@item G ++Go to line (default end-of-file). ++@item H ++To line from top of the screen (home). ++@item L ++To line from bottom of the screen (last). ++@item M ++To the middle line of the screen. ++@item ) ++ sentences forward. ++@item ( ++ sentences backward. ++@item @} ++ paragraphs forward. ++@item @{ ++ paragraphs backward. ++@item ]] ++To the th heading. ++@item [[ ++To the th previous heading. ++@item [] ++To the end of th heading. ++@item m ++Mark the cursor position with a letter. ++@item ` ++To the mark. ++@item ' ++To the first CHAR of the line with the mark. ++@item [ ++Show contents of textmarker. ++@item ] ++Show contents of register. ++@item `` ++To the cursor position before the latest absolute ++jump (of which are examples @kbd{/} and @kbd{G}). ++@item '' ++To the first CHAR of the line on which the cursor ++was placed before the latest absolute jump. ++@item / ++To the th occurrence of . ++@item / ++To the th occurrence of from previous @kbd{/ or ?}. ++@item ? ++To the th previous occurrence of . ++@item ? ++To the th previous occurrence of from previous @kbd{?@: or /}. ++@item n ++Repeat latest @kbd{/} @kbd{?} (next). ++@item N ++Repeat latest search in opposite direction. ++@item C-c / ++Without a prefix argument, this command toggles ++case-sensitive/case-insensitive search modes and plain vanilla/regular ++expression search. With the prefix argument 1, i.e., ++@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, ++toggles plain vanilla search and search using ++regular expressions. @xref{Viper Specials}, for alternative ways to invoke ++this function. ++@cindex vanilla search ++@cindex case-sensitive search ++@cindex case-insensitive search ++@item % ++Find the next bracket/parenthesis/brace and go to its match. ++By default, Viper ignores brackets/parentheses/braces that occur inside ++parentheses. You can change this by setting ++@code{viper-parse-sexp-ignore-comments} to @code{nil} in your @file{.viper} file. ++This option can also be toggled interactively if you quickly hit @kbd{%%%}. ++ ++This latter feature is implemented as a vi-style keyboard macro. If you ++don't want this macro, put ++ ++@example ++(viper-set-parsing-style-toggling-macro 'undefine) ++@end example ++@findex @code{viper-set-parsing-style-toggling-macro} ++ ++in your @file{~/.viper} file. ++ ++@end table ++@kindex @kbd{%} ++@kindex @kbd{C-c /} ++@kindex @kbd{N} ++@kindex @kbd{n} ++@kindex @kbd{?} ++@kindex @kbd{/} ++@kindex @kbd{?} ++@kindex @kbd{/} ++@kindex @kbd{''} ++@kindex @kbd{``} ++@kindex @kbd{]} ++@kindex @kbd{[} ++@kindex @kbd{'} ++@kindex @kbd{`} ++@kindex @kbd{m} ++@kindex @kbd{[]} ++@kindex @kbd{[[} ++@kindex @kbd{]]} ++@kindex @kbd{@{} ++@kindex @kbd{@}} ++@kindex @kbd{(} ++@kindex @kbd{)} ++@kindex @kbd{M} ++@kindex @kbd{L} ++@kindex @kbd{H} ++@kindex @kbd{G} ++@kindex @kbd{E} ++@kindex @kbd{e} ++@kindex @kbd{B} ++@kindex @kbd{b} ++@kindex @kbd{W} ++@kindex @kbd{w} ++@kindex @kbd{,} ++@kindex @kbd{;} ++@kindex @kbd{T} ++@kindex @kbd{F} ++@kindex @kbd{t} ++@kindex @kbd{f} ++@kindex @kbd{|} ++@kindex @kbd{0} ++@kindex @kbd{} ++@kindex @kbd{+} ++@kindex @kbd{-} ++@kindex @kbd{^} ++@kindex @kbd{$} ++@kindex @kbd{C-p} ++@kindex @kbd{} ++@kindex @kbd{} ++@kindex @kbd{C-n} ++@kindex @kbd{C-h} ++@kindex @kbd{h} ++@kindex @kbd{j} ++@kindex @kbd{k} ++@kindex @kbd{l} ++@vindex @code{viper-parse-sexp-ignore-comments} ++ ++@node Marking,Appending Text,Move Commands,Text Handling ++@subsection Marking ++ ++Emacs mark is referred to in the region specifiers @kbd{r} and @kbd{R}. ++@xref{Emacs Preliminaries}, and @xref{Basics}, for explanation. Also ++see @ref{Mark,,Mark,emacs,The GNU Emacs manual}, for an explanation of ++the Emacs mark ring. ++ ++@cindex marking ++ ++@table @kbd ++@item m ++Mark the current file and position with the specified letter. ++@item m . ++Set the Emacs mark (@pxref{Emacs Preliminaries}) at point. ++@item m ^ ++Set the Emacs mark (@pxref{Emacs Preliminaries}) back to where it was last ++set with the @kbd{m.} command. This is useful when you set the mark with ++@kbd{m.}, but then some other command (such as @kbd{L} or @kbd{G}) changes ++it in a way that you didn't like. ++@item m < ++Set the Emacs mark at beginning of buffer. ++@item m > ++Set the Emacs mark at end of buffer. ++@item m , ++Jump to the Emacs mark. ++@item :mark ++Mark position with text marker named . This is an Ex command. ++@item :k ++Same as @kbd{:mark}. ++@item `` ++Exchange point and mark. ++@item '' ++Exchange point and mark and go to the first CHAR on line. ++@item ' ++Go to specified Viper mark. ++@item ++Go to specified Viper mark and go to the first CHAR on line. ++@end table ++@kindex @kbd{m} ++@kindex @kbd{m.} ++@kindex @kbd{m>} ++@kindex @kbd{m<} ++@kindex @kbd{m,} ++@kindex @kbd{m^} ++@findex @kbd{:mark} ++@findex @kbd{:k} ++@kindex @kbd{''} ++@kindex @kbd{``} ++@kindex @kbd{`} ++@kindex @kbd{'} ++ ++@node Appending Text, Editing in Insert State, Marking,Text Handling ++@subsection Appending Text ++ ++@xref{Options}, to see how to change tab and shiftwidth size. See the GNU ++Emacs manual, or try @kbd{C-ha tabs} (If you have turned Emacs help on). ++Check out the variable @code{indent-tabs-mode} to put in just spaces. ++Also see options for word-wrap. ++ ++@cindex inserting ++@cindex appending ++@cindex paste ++@cindex put ++ ++@table @kbd ++@item a ++ times after the cursor. ++@item A ++ times at the end of line. ++@item i ++ times before the cursor (insert). ++@item I ++ times before the first CHAR of the line ++@item o ++On a new line below the current (open). ++The count is only useful on a slow terminal. ++@item O ++On a new line above the current. ++The count is only useful on a slow terminal. ++@item > ++Shift the lines described by one ++shiftwidth to the right (layout!). ++@item >> ++Shift lines one shiftwidth to the right. ++@item ["]p ++Put the contents of the (default undo) buffer ++ times after the cursor. The register will ++be automatically down-cased. ++@item ["]P ++Put the contents of the (default undo) buffer ++ times before the cursor. The register will ++@item [ ++Show contents of textmarker. ++@item ] ++Show contents of register. ++@item . ++Repeat previous command times. For destructive ++commands as well as undo. ++@item f1 1 and f1 2 ++While @kbd{.} repeats the last destructive command, ++these two macros repeat the second-last and the third-last destructive ++commands. @xref{Vi Macros}, for more information on Vi macros. ++@item C-c M-p and C-c M-n ++In Vi state, ++these commands help peruse the history of Vi's destructive commands. ++Successive typing of @kbd{C-c M-p} causes Viper to search the history in ++the direction ++of older commands, while hitting @kbd{C-c M-n} does so in reverse ++order. Each command in the history is displayed in the Minibuffer. The ++displayed command can ++then be executed by typing `@kbd{.}'. ++ ++Since typing the above sequences of keys may be tedious, the ++functions doing the perusing can be bound to unused keyboard keys in the ++@file{~/.viper} file. @xref{Viper Specials}, for details. ++@end table ++@kindex @kbd{C-c M-p} ++@kindex @kbd{C-c M-n} ++@kindex @kbd{.} ++@kindex @kbd{]} ++@kindex @kbd{[} ++@kindex @kbd{P} ++@kindex @kbd{p} ++@kindex @kbd{"p} ++@kindex @kbd{"P} ++@kindex @kbd{>>} ++@kindex @kbd{>} ++@kindex @kbd{O} ++@kindex @kbd{o} ++@kindex @kbd{i} ++@kindex @kbd{A} ++@kindex @kbd{a} ++ ++@node Editing in Insert State, Deleting Text, Appending Text,Text Handling ++@subsection Editing in Insert State ++ ++Minibuffer can be edited similarly to Insert state, and you can switch ++between Insert/Replace/Vi states at will. ++Some users prefer plain Emacs feel in the Minibuffer. To this end, set ++@var{viper-vi-style-in-minibuffer} to @code{nil}. ++ ++@cindex Insert state ++ ++@table @kbd ++@item C-v ++Deprive the next char of its special meaning (quoting). ++@item C-h ++One char back. ++@item C-w ++One word back. ++@item C-u ++Back to the begin of the change on the ++current line. ++ ++@end table ++@kindex @kbd{C-u} ++@kindex @kbd{C-w} ++@kindex @kbd{C-v} ++ ++@node Deleting Text, Changing Text, Editing in Insert State, Text Handling ++@subsection Deleting Text ++ ++ ++There is one difference in text deletion that you should be ++aware of. This difference comes from Emacs and was adopted in Viper ++because we find it very useful. In Vi, if you delete a line, say, and then ++another line, these two deletions are separated and are put back ++separately if you use the @samp{p} command. In Emacs (and Viper), successive ++series of deletions that are @emph{not interrupted} by other commands are ++lumped together, so the deleted text gets accumulated and can be put back ++as one chunk. If you want to break a sequence of deletions so that the ++newly deleted text could be put back separately from the previously deleted ++text, you should perform a non-deleting action, e.g., move the cursor one ++character in any direction. ++ ++@cindex shifting text ++ ++@table @kbd ++@item x ++Delete chars under and after the cursor. ++@item X ++Delete chars before the cursor. ++@item d ++Delete from point to endpoint of . ++@item dd ++Delete lines. ++@item D ++The rest of the line. ++@item < ++Shift the lines described by one ++shiftwidth to the left (layout!). ++@item << ++Shift lines one shiftwidth to the left. ++@end table ++@kindex @kbd{<<} ++@kindex @kbd{<} ++@kindex @kbd{D} ++@kindex @kbd{dd} ++@kindex @kbd{d} ++@kindex @kbd{X} ++@kindex @kbd{x} ++ ++@node Changing Text, Search and Replace, Deleting Text,Text Handling ++@subsection Changing Text ++ ++@cindex joining lines ++@cindex changing case ++@cindex quoting regions ++@cindex substitution ++ ++@table @kbd ++@item r ++Replace chars by - no . ++@item R ++Overwrite the rest of the line, ++appending change @var{count - 1} times. ++@item s ++Substitute chars. ++@item S ++Change lines. ++@item c ++Change from begin to endpoint of . ++@item cc ++Change lines. ++@item C ++The rest of the line and - 1 next lines. ++@item = ++Reindent the region described by move. ++@item ~ ++Switch lower and upper cases. ++@item J ++Join lines (default 2). ++@item :[x,y]s/// ++Substitute (on lines x through y) the pattern ++ (default the last pattern) with . Useful ++flags are @samp{g} for @samp{global} (i.e.@: change every ++non-overlapping occurrence of ) and @samp{c} for ++@samp{confirm} (type @samp{y} to confirm a particular ++substitution, else @samp{n} ). Instead of @kbd{/} any ++punctuation CHAR unequal to and can be used as ++delimiter. ++ ++In Emacs, @samp{\&} stands for the last matched expression, so ++@kbd{s/[ab]+/\&\&/} will double the string matched by @kbd{[ab]}. ++Viper doesn't treat @samp{&} specially, unlike Vi: use @samp{\&} instead. ++ ++Viper does not parse search patterns and does not expand special symbols ++found there (e.g., @samp{~} is not expanded to the result of the previous ++substitution). ++ ++Note: @emph{The newline character (inserted as @kbd{C-qC-j}) ++can be used in }. ++@item :[x,y]copy [z] ++Copy text between @kbd{x} and @kbd{y} to the position after @kbd{z}. ++@item :[x,y]t [z] ++Same as @kbd{:copy}. ++@item :[x,y]move [z] ++Move text between @kbd{x} and @kbd{y} to the position after @kbd{z}. ++@item & ++Repeat latest Ex substitute command, e.g. ++@kbd{:s/wrong/right}. ++@item :x,yp ++@itemx :g/Pat/p ++@itemx :v/Pat/p ++The above commands display certain buffer lines in a ++temporary buffer. The first form above displays the buffer lines between ++@kbd{x} and @kbd{y}. The second displays the lines of the buffer, which ++match a given pattern. The third form displays the lines that do @emph{not} ++match the given pattern. ++@item #c ++Change upper-case characters in the region to lower-case. ++@item #C ++Change lower-case characters in the region to upper-case. ++@item #q ++Insert specified string at the beginning of each line in the region ++@item C-c M-p and C-c M-n ++In Insert and Replace states, these keys are bound to commands that peruse ++the history of the text ++previously inserted in other insert or replace commands. By repeatedly typing ++@kbd{C-c M-p} or @kbd{C-c M-n}, you will cause Viper to ++insert these previously used strings one by one. ++When a new string is inserted, the previous one is deleted. ++ ++In Vi state, these keys are bound to functions that peruse the history of ++destructive Vi commands. ++@xref{Viper Specials}, for details. ++@end table ++@kindex @kbd{C-c M-p} ++@kindex @kbd{C-c M-n} ++@kindex @kbd{#q } ++@kindex @kbd{#C} ++@kindex @kbd{#c} ++@kindex @kbd{&} ++@kindex @kbd{\&} ++@findex @kbd{:substitute///} ++@findex @kbd{:s///} ++@findex @kbd{:copy [z]} ++@findex @kbd{:t [z]} ++@findex @kbd{:move [z]} ++@kindex @kbd{J} ++@kindex @kbd{~} ++@kindex @kbd{=} ++@kindex @kbd{C} ++@kindex @kbd{cc} ++@kindex @kbd{c} ++@kindex @kbd{S} ++@kindex @kbd{s} ++@kindex @kbd{R} ++@kindex @kbd{r} ++ ++@node Search and Replace, Yanking, Changing Text,Text Handling ++@subsection Search and Replace ++ ++@xref{Groundwork}, for Ex address syntax. @xref{Options}, to see how to ++get literal (non-regular-expression) search and how to stop search from ++wrapping around. ++ ++@table @kbd ++@item C-c / ++Toggle case-sensitive search. With prefix argument, toggle vanilla/regular ++expression search. ++@item / ++To the th occurrence of . ++ ++Viper does not parse search patterns and does not expand special symbols ++found there (e.g., @samp{~} is not expanded to the result of the previous ++substitution). ++ ++@item ? ++To the th previous occurrence of . ++@item g ++Search for the text described by move. (off by default) ++@item n ++Repeat latest @kbd{/} @kbd{?} (next). ++@item N ++Idem in opposite direction. ++@item % ++Find the next bracket and go to its match ++@item :[x,y]g// ++@cindex text processing ++Search globally [from line x to y] for ++and execute the Ex on each occurrence. ++@item :[x,y]v// ++Execute on the lines that don't match. ++@item #g ++Execute the last keyboard macro for each line in the region. ++@xref{Macros and Registers}, for more info. ++@item Q ++Query Replace. ++@item :ta ++Search in the tags file where is defined (file, line), and go to it. ++@item :[x,y]s/// ++Substitute (on lines x through y) the pattern (default the last ++pattern) with . Useful ++flags are @samp{g} for @samp{global} (i.e.@: change every ++non-overlapping occurrence of ) and @samp{c} for ++@samp{confirm} (type @samp{y} to confirm a particular ++substitution, else @samp{n}). Instead of @kbd{/} any ++punctuation character other than and can be used as ++delimiter. ++ ++Note: @emph{The newline character (inserted as @kbd{C-qC-j}) ++can be used in }. ++@item & ++Repeat latest Ex substitute command, e.g.@: @kbd{:s/wrong/right}. ++@item :global // ++@itemx :g // ++Execute on all lines that match . ++@item :vglobal // ++@itemx :v // ++Execute on all lines that do not match . ++@end table ++@kindex @kbd{&} ++@findex @kbd{:substitute///} ++@kindex @kbd{Q} ++@kindex @kbd{#g} ++@findex @kbd{:v} ++@findex @kbd{:g} ++@findex @kbd{:global} ++@findex @kbd{:vglobal} ++@findex @kbd{:tag } ++@kindex @kbd{%} ++@kindex @kbd{N} ++@kindex @kbd{n} ++@kindex @kbd{g} ++@kindex @kbd{?} ++@kindex @kbd{/} ++ ++@node Yanking,Undoing,Search and Replace,Text Handling ++@subsection Yanking ++ ++@cindex cut and paste ++@cindex paste ++ ++@table @kbd ++@item y ++Yank from begin to endpoint of . ++@item "y ++Yank from begin to endpoint of to register. ++@item "y ++Yank from begin to endpoint of and append ++to register. ++@item yy ++ lines. ++@item Y ++Idem (should be equivalent to @kbd{y$} though). ++@item m ++Mark the cursor position with a letter. ++@item [ ++Show contents of textmarker. ++@item ] ++Show contents of register. ++@item ["]p ++Put the contents of the (default undo) buffer ++ times after the cursor. The register will ++be automatically down-cased. ++@item ["]P ++Put the contents of the (default undo) buffer ++ times before the cursor. The register will ++@end table ++@kindex @kbd{P} ++@kindex @kbd{p} ++@kindex @kbd{"p} ++@kindex @kbd{"P} ++@kindex @kbd{]} ++@kindex @kbd{[} ++@kindex @kbd{m} ++@kindex @kbd{Y} ++@kindex @kbd{yy} ++@kindex @kbd{"y} ++@kindex @kbd{"y} ++@kindex @kbd{y} ++@kindex @kbd{yank} ++@findex @kbd{:yank} ++ ++@node Undoing,, Yanking,Text Handling ++@subsection Undoing ++ ++@cindex undo ++@cindex backup files ++ ++@table @kbd ++@item u U ++Undo the latest change. ++@item . ++Repeat undo. ++@item :q! ++Quit Vi without writing. ++@item :e! ++Re-edit a messed-up file. ++@item :rec ++Recover file from autosave. Viper also creates backup files ++that have a @samp{~} appended to them. ++@end table ++@findex @kbd{:rec} ++@findex @kbd{:e!} ++@findex @kbd{:q!} ++@kindex @kbd{.} ++@kindex @kbd{U} ++@kindex @kbd{u} ++ ++@node Display, File and Buffer Handling, Text Handling, Commands ++@section Display ++ ++@cindex scrolling ++ ++@table @kbd ++@item C-g ++At user level 1, ++give file name, status, current line number ++and relative position.@* ++At user levels 2 and higher, abort the current command. ++@item C-c g ++Give file name, status, current line number and relative position -- all ++user levels. ++@item C-l ++Refresh the screen. ++@item C-e ++Expose more lines at bottom, cursor stays put (if possible). ++@item C-y ++Expose more lines at top, cursor stays put (if possible). ++@item C-d ++Scroll lines downward (default the number of the previous scroll; ++initialization: half a page). ++@item C-u ++Scroll lines upward (default the number of the previous scroll; ++initialization: half a page). ++@item C-f ++ pages forward. ++@item C-b ++ pages backward (in older versions @kbd{C-b} only works without count). ++@item z ++@item zH ++Put line at the top of the window (default the current line). ++@item z- ++@item zL ++Put line at the bottom of the window ++(default the current line). ++@item z. ++@item zM ++Put line in the center of the window ++(default the current line). ++@end table ++@kindex @kbd{zM} ++@kindex @kbd{zL} ++@kindex @kbd{zH} ++@kindex @kbd{z} ++@kindex @kbd{z.} ++@kindex @kbd{z-} ++@kindex @kbd{z} ++@kindex @kbd{C-b} ++@kindex @kbd{C-f} ++@kindex @kbd{C-u} ++@kindex @kbd{C-d} ++@kindex @kbd{C-y} ++@kindex @kbd{C-e} ++@kindex @kbd{C-l} ++@kindex @kbd{C-g} ++ ++ ++@node File and Buffer Handling, Mapping, Display,Commands ++@section File and Buffer Handling ++ ++@cindex multiple files ++ ++In all file handling commands, space should be typed before entering the file ++name. If you need to type a modifier, such as @kbd{>>} or @kbd{!}, don't ++put any space between the command and the modifier. ++ ++Note that many Ex commands, e.g., @kbd{:w}, accept command arguments. The ++effect is that the command would start acting on the current region. For ++instance, if the current region spans the lines 11 through 22, then if you ++type @kbd{1:w} you would see @samp{:11,22w} in the minibuffer. ++ ++@table @kbd ++@item :q ++Quit buffer except if modified. ++@item :q! ++Quit buffer without checking. In Viper, these two commands ++are identical. Confirmation is required if exiting modified buffers that ++visit files. ++@item :suspend ++@item :stop ++Suspend Viper ++@item :[x,y] w ++Write the file. Viper makes sure that a final newline is always added to ++any file where this newline is missing. This is done by setting Emacs ++variable @code{require-final-newline} to @code{t}. If you don't like this ++feature, use @code{setq-default} to set @code{require-final-newline} to ++@code{nil}. This must be done in @file{.viper} file. ++@item :[x,y] w ++Write to the file . ++@item :[x,y] w>> ++Append the buffer to the file . There should be no space between ++@kbd{w} and @kbd{>>}. Type space after the @kbd{>>} and see what happens. ++@item :w!@: ++Overwrite the file . In Viper, @kbd{:w} and @kbd{:w!} are identical. ++Confirmation is required for writing to an existing file (if this is not ++the file the buffer is visiting) or to a read-only file. ++@item :x,y w ++Write lines x through y to the file . ++@item :wq ++Write the file and kill buffer. ++@item :r [ ...] ++Read file into a buffer, inserting its contents after the current line. ++@item :xit ++Same as @kbd{:wq}. ++@item :Write ++@itemx :W ++Save all unsaved buffers, asking for confirmation. ++@item :WWrite ++@itemx :WW ++Like @kbd{W}, but without asking for confirmation. ++@item ZZ ++Save current buffer and kill it. If user level is 1, then save all files ++and kill Emacs. Killing Emacs is the wrong way to use it, so you should ++switch to higher user levels as soon as possible. ++@item :x [] ++Save and kill buffer. ++@item :x!@: [] ++@kbd{:w![]} and @kbd{:q}. ++@item :pre ++Preserve the file -- autosave buffers. ++@item :rec ++Recover file from autosave. ++@item :f [] ++without the argument, prints file name and character/line information afout ++the currently visited file. With an argument, sets the currently visited ++filename to @file{file}. ++@item :cd [] ++Set the working directory to (default home directory). ++@item :pwd ++Print present working directory. ++@item :e [+] ++Edit files. If no filename is given, edit the file visited by the current ++buffer. If buffer was modified or the file changed on disk, ask for ++confirmation. Unlike Vi, Viper allows @kbd{:e} to take multiple arguments. ++The first file is edited the same way as in Vi. The rest are visited ++in the usual Emacs way. ++@item :e!@: [+] ++Re-edit file. If no filename, re-edit current file. ++In Viper, unlike Vi, @kbd{e!} is identical to @kbd{:e}. In both cases, the ++user is asked to confirm if there is a danger of discarding changes to a ++buffer. ++@item :q! ++Quit Vi without writing. ++@item C-^ ++Edit the alternate (normally the previous) file. ++@item :rew ++Obsolete ++@item :args ++List files not shown anywhere with counts for next ++@item :n [count] [+] [] ++Edit file, or edit files. The count comes from @kbd{:args}. ++@item :N [count] [+] [] ++Like @kbd{:n}, but the meaning of the variable ++@var{ex-cycle-other-window} is reversed. ++@item :b ++Switch to another buffer. If @var{ex-cycle-other-window} is @code{t}, ++switch in another window. Buffer completion is supported. ++The variable @var{viper-read-buffer-function} controls which function is ++actually used to read the buffer name. The default is @code{read-buffer}, ++but better alternatives are also available in Emacs (e.g., ++@code{iswitchb-read-buffer}). ++@vindex @var{viper-read-buffer-function} ++@item :B ++Like @kbd{:b}, but the meaning of @var{ex-cycle-other-window} is reversed. ++@item :
r ++Read the file into the buffer after the line
. ++@item v, V, C-v ++Edit a file in current or another window, or in another frame. File name ++is typed in Minibuffer. File completion and history are supported. ++@end table ++@kindex @kbd{v} ++@kindex @kbd{V} ++@findex @kbd{:args} ++@findex @kbd{:rew} ++@kindex @kbd{C-^} ++@findex @kbd{:e!@: []} ++@findex @kbd{:e []} ++@findex @kbd{:edit []} ++@findex @kbd{:edit!@: []} ++@findex @kbd{:q!} ++@findex @kbd{:q} ++@findex @kbd{:quit} ++@findex @kbd{:quit!} ++@findex @kbd{:f} ++@findex @kbd{:rec} ++@findex @kbd{:r} ++@findex @kbd{:read} ++@findex @kbd{:pre} ++@kindex @kbd{ZZ} ++@findex @kbd{:wq} ++@findex @kbd{:w } ++@findex @kbd{:w!@: } ++@findex @kbd{:w >> } ++@findex @kbd{:write } ++@findex @kbd{:write!@: } ++@findex @kbd{:write >> } ++@findex @kbd{:W} ++@findex @kbd{:WW} ++@findex @kbd{:Write} ++@findex @kbd{:WWrite} ++@findex @kbd{:WWrite} ++@findex @kbd{:x} ++@findex @kbd{:x!} ++@findex @kbd{:suspend} ++@findex @kbd{:stop} ++@findex @kbd{:n [ | ]} ++@findex @kbd{:cd []} ++@findex @kbd{:pwd} ++ ++@node Mapping, Shell Commands, File and Buffer Handling, Commands ++@section Mapping ++ ++@cindex key bindings ++@cindex key mapping ++ ++@table @kbd ++@item :map ++Start defining a Vi-style keyboard macro. ++For instance, typing ++@kbd{:map www} followed by @kbd{:!wc %} and then typing @kbd{C-x )} ++will cause @kbd{www} to run wc on ++current file (Vi replaces @samp{%} with the current file name). ++@item C-x ) ++Finish defining a keyboard macro. ++In Viper, this command completes the process of defining all keyboard ++macros, whether they are Emacs-style or Vi-style. ++This is a departure from Vi, needed to allow WYSIWYG mapping of ++keyboard macros and to permit the use of function keys and arbitrary Emacs ++functions in the macros. ++@item :unmap ++Deprive of its mappings in Vi state. ++@item :map!@: ++Map a macro for Insert state. ++@item :unmap!@: ++Deprive of its mapping in Insert state (see @kbd{:unmap}). ++@item @@ ++In Vi state, ++execute the contents of register as a command. ++@item @@@@ ++In Vi state, ++repeat last register command. ++@item @@# ++In Vi state, ++begin keyboard macro. End with @@. This will ++put the macro in the proper register. Register will ++be automatically down-cased. ++@xref{Macros and Registers}, for more info. ++@item @@! ++In Vi state, ++yank anonymous macro to register ++@item * ++In Vi state, ++execute anonymous macro (defined by C-x( and C-x )). ++@item C-x e ++Like @kbd{*}, but works in all Viper states. ++@item #g ++Execute the last keyboard macro for each line in the region. ++@xref{Macros and Registers}, for more info. ++@item [ ++Show contents of textmarker. ++@item ] ++Show contents of register. ++@end table ++@kindex @kbd{]} ++@kindex @kbd{[} ++@kindex @kbd{#g} ++@kindex @kbd{*} ++@kindex @kbd{@@!} ++@kindex @kbd{@@#} ++@kindex @kbd{@@@@} ++@kindex @kbd{@@} ++@findex @kbd{:unmap } ++@findex @kbd{:map } ++@findex @kbd{:unmap!@: } ++@findex @kbd{:map!@: } ++ ++@node Shell Commands, Options, Mapping, Commands ++@section Shell Commands ++ ++@cindex % (Current file) ++ ++The symbol @samp{%} is used in Ex shell commands to mean current file. If ++you want a @samp{%} in your command, it must be escaped as @samp{\%}. ++@cindex @samp{%} (Ex address) ++However if @samp{%} is the first character, it stands as the address for ++the whole file. ++@cindex @samp{#} (Previous file) ++Similarly, @samp{#} expands to the previous file. The previous file is the ++first file in @kbd{:args} listing. This defaults to the previous file in ++the VI sense if you have one window.@refill ++ ++Symbols @samp{%} and @samp{#} are also used in the Ex commands @kbd{:e} and ++@kbd{:r }. The commands @kbd{:w} and the regular @kbd{:r ++} command don't support these meta symbols, because file history is a ++better mechanism. ++ ++@cindex shell commands ++ ++@table @kbd ++@item :sh ++Execute a subshell in another window ++@item :[x,y]! ++Execute a shell [on lines x through y; ++% is replace by current file, \% is changed to % ++@item :[x,y]!!@: [] ++Repeat last shell command [and append ]. ++@item :! ++Just execute command and display result in a buffer. ++@item :!!@: ++Repeat last shell command and append ++@item ! ++The shell executes , with standard ++input the lines described by , ++next the standard output replaces those lines ++(think of @samp{cb}, @samp{sort}, @samp{nroff}, etc.). ++@item !! ++Give lines as standard input to the ++shell , next let the standard output ++replace those lines. ++@item :[x,y] w ! ++Let lines x to y be standard input for ++(notice the between @kbd{w} and @kbd{!}). ++@item :
r ! ++Put the output of after the line
(default current). ++@item :
r ++Read the file into the buffer after the line
(default ++current). ++@item :make ++Run the make command in the current directory. ++@end table ++@findex @kbd{:
r } ++@findex @kbd{:
r !} ++@findex @kbd{!} ++@findex @kbd{!!} ++@findex @kbd{!} ++@findex @kbd{:w !} ++@findex @kbd{:x,y w !} ++@findex @kbd{:!!@: } ++@findex @kbd{:!} ++@findex @kbd{:sh} ++@findex @kbd{:make} ++ ++@node Options,Emacs Related Commands,Shell Commands,Commands ++@section Options ++ ++@cindex Vi options ++ ++@table @kbd ++@item autoindent ++@itemx ai ++@cindex autoindent ++autoindent -- In append mode after a the ++cursor will move directly below the first ++character on the previous line. ++This setting affects the current buffer only. ++@item autoindent-global ++@itemx ai-global ++Same as `autoindent', but affects all buffers. ++@item noautoindent ++@itemx noai ++Cancel autoindent. ++@item noautoindent-global ++@itemx noai-g ++Cancel autoindent-global. ++@item ignorecase ++@itemx ic ++@cindex case and searching ++ignorecase -- No distinction between upper and lower cases when searching. ++@item noignorecase ++@itemx noic ++Cancel ignorecase. ++@item magic ++@itemx ma ++@cindex literal searching ++Regular expressions used in searches; nomagic means no regexps. ++@item nomagic ++@item noma ++Cancel magic. ++@item readonly ++@itemx ro ++@cindex readonly files ++readonly -- The file is not to be changed. ++If the user attempts to write to this file, confirmation will be requested. ++@item noreadonly ++@itemx noro ++Cancel readonly. ++@item shell= ++@itemx sh= ++@cindex shell ++shell -- The program to be used for shell escapes ++(default @samp{$SHELL} (default @file{/bin/sh})). ++@item shiftwidth= ++@itemx sw= ++@cindex layout ++@cindex shifting text ++shiftwidth -- Gives the shiftwidth (default 8 positions). ++@item showmatch ++@itemx sm ++@cindex paren matching ++@cindex matching parens ++showmatch -- Whenever you append a @kbd{)}, Vi shows ++its match if it's on the same page; also with ++@kbd{@{} and @kbd{@}}. If there's no match, Vi will beep. ++@item noshowmatch ++@itemx nosm ++Cancel showmatch. ++@item tabstop= ++@itemx ts= ++@cindex changing tab width ++@cindex tabbing ++tabstop -- The length of a ; warning: this is ++only IN the editor, outside of it s have ++their normal length (default 8 positions). ++This setting affects the current buffer only. ++@item tabstop-global ++@itemx ts-g ++Same as `tabstop', but affects all buffers. ++@item wrapmargin= ++@itemx wm= ++@cindex auto fill ++@cindex word wrap ++wrapmargin -- In append mode Vi automatically ++puts a whenever there is a or ++within columns from the right margin. ++@item wrapscan ++@itemx ws ++@cindex searching ++wrapscan -- When searching, the end is ++considered @samp{stuck} to the begin of the file. ++@item nowrapscan ++@itemx nows ++Cancel wrapscan. ++@item :set